doc: add categories

Author: mcquenji

.gitignore

@@ -10,4 +10,6 @@ pubspec.lock
 .fvm/
 custom_lint.log
 grumpy_lints.log
-build/
+build/
+doc/
+pubspec_overrides.yaml

dartdoc_options.yaml

@@ -0,0 +1,31 @@
+dartdoc:
+  categories:
+    module:
+      displayName: Modules
+      markdown: lib/src/module/README.md
+    routing:
+      displayName: Routing
+      markdown: lib/src/routing/README.md
+    repo:
+      displayName: Repositories 
+      markdown: lib/src/repo/README.md
+    cache:
+      displayName: Caching
+      markdown: lib/src/cache/README.md
+    persistence:
+      displayName: Persistence
+      markdown: lib/src/persistence/README.md
+    transactions:
+      displayName: Transactions
+      markdown: lib/src/transactions/README.md
+    telemetry:
+      displayName: Telemetry & Analytics
+      markdown: lib/src/telemetry/README.md
+    presentation:
+      displayName: Presentation Layer
+      markdown: lib/src/presentation/README.md
+    shared:
+      displayName: Shared Primitives
+      markdown: lib/src/shared/README.md
+  categoryOrder: [Shared Primitives, Modules,Presentation Layer, Repositories, Routing, Caching, Persistence, Transactions, Telemetry & Analytics]
+  showUndocumentedCategories: true

lib/src/cache/domain/models/cache_entry.dart

@@ -1,6 +1,9 @@
 import 'package:grumpy/grumpy.dart';
 
 /// Stored cache entry with optional expiry metadata.
+///
+/// {@category cache}
+
 class CacheEntry<T> extends Model {
   /// Creates a cache entry.
   const CacheEntry({

lib/src/cache/domain/models/cache_policy.dart

@@ -12,6 +12,9 @@ import 'package:grumpy/grumpy.dart';
 ///   `CachePolicy(useMemory: true, useFile: true, fileTtl: ...)`
 /// - Strict debugging mode:
 ///   `CachePolicy(strictLayerErrors: true)`
+///
+/// {@category cache}
+
 class CachePolicy<Serialized extends Object> extends Model {
   /// Creates cache behavior options for a query read/write cycle.
   const CachePolicy({

lib/src/cache/domain/models/cache_result.dart

@@ -1,6 +1,9 @@
 import 'package:grumpy/grumpy.dart';
 
 /// Source used to satisfy a cache lookup.
+///
+/// {@category cache}
+
 enum CacheSource {
   /// Value came from the memory layer.
   memory,
@@ -13,6 +16,9 @@ enum CacheSource {
 }
 
 /// Returned cache value with source metadata.
+///
+/// {@category cache}
+
 class CacheResult<T> extends Model {
   /// Creates a cache lookup result.
   const CacheResult({

lib/src/cache/domain/services/cache_layer_service.dart

@@ -3,6 +3,9 @@ import 'dart:typed_data';
 import 'package:grumpy/grumpy.dart';
 
 /// Shared cache layer surface.
+///
+/// {@category cache}
+
 abstract class CacheLayerService extends Service {
   /// Returns the DI-registered implementation of [CacheLayerService].
   ///

lib/src/cache/domain/services/cache_pipeline_service.dart

@@ -10,6 +10,9 @@ import 'package:grumpy/grumpy.dart';
 ///
 /// Repos typically do not call this service directly. Prefer [QueryMixin],
 /// which integrates this pipeline automatically when registered.
+///
+/// {@category cache}
+
 abstract class CachePipelineService extends Service {
   /// Returns the DI-registered cache pipeline.
   factory CachePipelineService() => Service.get<CachePipelineService>();

lib/src/cache/domain/services/file_cache_layer_service.dart

@@ -1,6 +1,9 @@
 import 'package:grumpy/grumpy.dart';
 
 /// L2 persistent cache layer.
+///
+/// {@category cache}
+
 abstract class FileCacheLayerService extends CacheLayerService {
   /// Returns the DI-registered implementation of [FileCacheLayerService].
   ///

lib/src/cache/domain/services/memory_cache_layer_service.dart

@@ -1,6 +1,9 @@
 import 'package:grumpy/grumpy.dart';
 
 /// L1 in-memory cache layer.
+///
+/// {@category cache}
+
 abstract class MemoryCacheLayerService extends CacheLayerService {
   /// Returns the DI-registered implementation of [MemoryCacheLayerService].
   ///

lib/src/cache/infra/services/default_cache_pipeline_service.dart

@@ -12,6 +12,9 @@ import 'package:grumpy/grumpy.dart';
 /// - write-through to enabled layers when policy allows
 /// - per-layer TTL application
 /// - optional strict error propagation
+///
+/// {@category cache}
+
 class DefaultCachePipelineService extends CachePipelineService {
   /// Creates a default pipeline with optional memory/file layers.
   DefaultCachePipelineService({