FullStackHero 10 .NET Starter Kit Release Merge

.agents/rules/api-conventions.md

@@ -0,0 +1,66 @@
+# API conventions
+
+Read before adding endpoints, commands/queries, validators, or error handling.
+
+## Endpoints
+
+Static extension methods on `IEndpointRouteBuilder`, returning `RouteHandlerBuilder`. The handler delegates to Mediator. Gate with `.RequirePermission(...)`.
+
+```csharp
+public static class RegisterUserEndpoint
+{
+    internal static RouteHandlerBuilder MapRegisterUserEndpoint(this IEndpointRouteBuilder endpoints) =>
+        endpoints.MapPost("/register", (RegisterUserCommand command,
+                IMediator mediator, CancellationToken cancellationToken) =>
+                mediator.Send(command, cancellationToken))
+            .WithName("RegisterUser")
+            .WithSummary("Register user")
+            .RequirePermission(IdentityPermissionConstants.Users.Create);
+}
+```
+
+- **Always accept and forward `CancellationToken`** to `mediator.Send`. ASP.NET injects it.
+- Wire each endpoint in the module's `MapEndpoints()`. Endpoints group under `api/v{version:apiVersion}/{module}`.
+- Use `TypedResults` / `.Produces<T>(...)` for accurate OpenAPI. Add `.WithIdempotency()` on POSTs that must be replay-safe.
+
+## CQRS
+
+- **Commands/Queries** live in `Modules.{Name}.Contracts` — implement `ICommand<TResponse>` / `IQuery<TResponse>`. Records preferred.
+- **Handlers** live in `Modules.{Name}/Features/` — `public sealed`, implement `ICommandHandler<T,TResponse>` / `IQueryHandler<T,TResponse>`, return `ValueTask<T>`, `.ConfigureAwait(false)` on awaits.
+- Paginated queries implement `IPagedQuery` (`PageNumber`, `PageSize`, `Sort`) and return `PagedResponse<T>`.
+
+## Validation
+
+FluentValidation, auto-registered by `ModuleLoader`. Name `{Command}Validator`. Live in the same feature folder.
+
+- **Every command handler needs a validator; every paginated query handler needs one too.** Enforced by `Architecture.Tests` (`HandlerValidatorPairingTests`). A handler legitimately without rules can be added to that test's known-missing allowlist, but prefer writing the validator.
+- Validators run via the `ValidationBehavior<,>` Mediator pipeline before the handler.
+
+## Exceptions → ProblemDetails
+
+Throw framework exception types; the global handler converts to RFC 9457 `ProblemDetails`:
+
+| Throw | HTTP |
+|---|---|
+| `NotFoundException` | 404 |
+| `ForbiddenException` | 403 |
+| `UnauthorizedException` | 401 |
+| `CustomException(msg, errors?, HttpStatusCode)` | as specified (default 400) |
+
+Don't catch broadly to swallow. Background loops may `catch (Exception)` to stay alive, but must **log with context** and exclude `OperationCanceledException` (filtered catch or a preceding `catch (OperationCanceledException)`).
+
+## Permissions
+
+Constants in `Shared/Identity/*Permissions.cs` (e.g. `IdentityPermissionConstants`). Apply with `.RequirePermission(...)` on the endpoint. `RequiredPermissionAttribute` implements `IRequiredPermissionMetadata` — never let a duplicate of that interface appear; it silently disables **all** `.RequirePermission()` gates.
+
+## Specifications
+
+Use `Specification<T>` (`src/BuildingBlocks/Persistence/Specifications/`) for query composition. Default `AsNoTracking = true` — see `database.md` for when tracking is required instead.
+
+## Adding a feature (checklist)
+
+1. Command/query + response in `Modules.{Name}.Contracts/v1/{Area}/{Feature}/`.
+2. Handler in `Modules.{Name}/Features/v1/{Area}/{Feature}/`.
+3. Validator in the same folder.
+4. Endpoint in the same folder; wire in module `MapEndpoints()`.
+5. Tests in `Tests/{Name}.Tests/` (+ integration test if it touches DB/IO).

.agents/rules/architecture.md

@@ -0,0 +1,99 @@
+# Architecture rules
+
+Modular Monolith + Vertical Slice Architecture (VSA). Read this before adding/moving modules or touching wiring.
+
+## Layers & dependency direction
+
+```
+Host (composition root)  →  Modules.{Name} (runtime)  →  Modules.{Name}.Contracts (public API)
+                         →  BuildingBlocks (shared framework)
+```
+
+- **BuildingBlocks** (`src/BuildingBlocks/`) — Core, Persistence, Web, Caching, Eventing, Storage, Quota, Jobs, Mailing, Shared. Consumed by all modules. **Do not modify without explicit approval.**
+- **Modules** (`src/Modules/{Name}/`) — bounded contexts. Each = a runtime project (internal) + a `.Contracts` project (public API: commands, queries, events, DTOs, service interfaces).
+- A module **MUST NOT** reference another module's runtime project — only its `.Contracts`. Enforced by `Architecture.Tests` (NetArchTest).
+
+## Module = runtime + Contracts
+
+```
+Modules.Identity/            ← runtime (internal): handlers, services, domain, data
+Modules.Identity.Contracts/  ← public: ICommand/IQuery types, DTOs, events, service interfaces
+```
+
+Cross-module communication: through Contracts service interfaces or integration events only.
+
+## Feature folder layout (VSA)
+
+Each feature is a vertical slice in `Features/v{version}/{Area}/{Feature}/`:
+
+```
+Features/v1/Users/RegisterUser/
+├── RegisterUserEndpoint.cs          # minimal API endpoint
+├── RegisterUserCommandHandler.cs    # CQRS handler (public sealed)
+└── RegisterUserCommandValidator.cs  # FluentValidation
+```
+
+Module support folders: `Domain/`, `Data/`, `Services/`, `Events/`, `Authorization/`.
+
+## IModule registration
+
+Each module implements `IModule`, declared via an **assembly-level** `[FshModule]` attribute (positional `(Type moduleType, int order = 0)`) — **not** a class-level `[FshModule(Order = n)]`:
+
+```csharp
+[assembly: FshModule(typeof(FSH.Modules.Identity.IdentityModule), 1)]   // above the namespace
+
+namespace FSH.Modules.Identity;
+
+public sealed class IdentityModule : IModule
+{
+    public void ConfigureServices(IHostApplicationBuilder builder) { ... }
+    public void ConfigureMiddleware(IApplicationBuilder app) { ... }   // optional, runs AFTER UseAuthentication
+    public void MapEndpoints(IEndpointRouteBuilder endpoints) { ... }
+}
+```
+
+`ModuleLoader.AddModules` (`src/BuildingBlocks/Web/Modules/ModuleLoader.cs`) discovers `[FshModule]` attributes, orders by `Order` then name, instantiates each, and calls `ConfigureServices`. Endpoints map under `api/v{version:apiVersion}/{module}`.
+
+## ⚠️ The four-place registration footgun
+
+Adding a module requires editing **four** lists. Miss one and it fails *silently*:
+
+| Place | File | Symptom if missed |
+|---|---|---|
+| Mediator `o.Assemblies` (two markers: Contracts type **and** module type) | `src/Host/FSH.Starter.Api/Program.cs` | Handlers silently undiscovered |
+| `moduleAssemblies` array | `src/Host/FSH.Starter.Api/Program.cs` | Module never loaded |
+| Mediator assemblies (same pair) | `src/Host/FSH.Starter.DbMigrator/Program.cs` | Migrate/seed misses the module |
+| module assemblies array | `src/Host/FSH.Starter.DbMigrator/Program.cs` | Migrate/seed misses the module |
+
+After wiring, the fastest sanity check is: build, hit the endpoint, confirm the handler runs.
+
+## DI & handler conventions
+
+- Mediator handlers: `public sealed`, implement `ICommandHandler<T,TResponse>` / `IQueryHandler<T,TResponse>`, return `ValueTask<T>`, `.ConfigureAwait(false)` on every await. `ServiceLifetime.Scoped`.
+- Validators auto-register via `ModuleLoader` (`AddValidatorsFromAssemblies`). Name them `{Command}Validator`.
+- Prefer constructor injection / primary constructors. Watch DI lifetimes: stateful singletons must be thread-safe (use `ConcurrentDictionary` / immutable snapshots).
+
+## Middleware ordering (critical)
+
+In `src/BuildingBlocks/Web/Extensions.cs` (`UseHeroPlatform`):
+
+1. ExceptionHandler → ResponseCompression
+2. **CORS before HTTPS redirect** (so OPTIONS preflight isn't 307-redirected)
+3. HttpsRedirection → SecurityHeaders → static files → Routing
+4. **`UseAuthentication`**
+5. **`UseModuleMiddlewares`** — each module's `ConfigureMiddleware`, runs **after** auth
+6. RateLimiting → Quotas → `UseAuthorization` → `MapModules`
+
+`app.UseHeroMultiTenantDatabases()` (Finbuckle `UseMultiTenant()`) runs in `Program.cs` **before** `UseHeroPlatform`, i.e. **before `UseAuthentication`** — so tenant resolution is header-driven, not claim-driven. See `modules/multitenancy.md`.
+
+## Static/global state
+
+No global mutable static collections enumerated under concurrency. `Audit` (Auditing module) swaps an immutable `IAuditEnricher[]` atomically; `ModuleLoader` guards with a lock. Follow that pattern if you must hold process-global state.
+
+## Configuration & options
+
+- `appsettings.json` (+ `.Development`/`.Production`) live in `src/Host/FSH.Starter.Api/`. DbMigrator links the same files.
+- Bind config with the Options pattern: `AddOptions<T>().BindConfiguration(nameof(T))`, section name == type name (e.g. `JwtOptions`, `DatabaseOptions`, `CachingOptions`, `CorsOptions`, `QuotaOptions`, `RateLimitingOptions`; **storage section is `Storage`**, not `StorageOptions`). Add `.ValidateDataAnnotations().ValidateOnStart()` for fail-fast.
+- Validate critical options via `IValidatableObject` — `JwtOptions` requires `SigningKey` ≥32 chars and **rejects placeholder strings containing `"replace-with"`**; `DatabaseOptions` rejects empty connection strings.
+- **Production fail-fast** (`Program.cs`, before service registration): missing `DatabaseOptions:ConnectionString`, `CachingOptions:Redis`, or `JwtOptions:SigningKey` throws. Dev secrets via `dotnet user-secrets` (AppHost has a `UserSecretsId`); MinIO creds are Aspire secret parameters.
+- Platform composition is one call each: `builder.AddHeroPlatform(o => { o.Enable... })` (DI) and `app.UseHeroPlatform(...)` (middleware). Feature flags toggle Caching/Jobs/Mailing/Quotas/Sse/Realtime/OpenTelemetry/CORS/Idempotency.

.agents/rules/buildingblocks-protection.md

@@ -0,0 +1,36 @@
+---
+paths:
+  - "src/BuildingBlocks/**/*"
+---
+
+# ⚠️ BuildingBlocks Protection
+
+**STOP. You are modifying BuildingBlocks.**
+
+Changes to BuildingBlocks affect ALL modules across the entire framework. These are core abstractions that many projects depend on.
+
+## Before Proceeding
+
+1. **Confirm explicit approval** - Has the user specifically approved this change?
+2. **Consider alternatives** - Can this be done in the module instead?
+3. **Assess impact** - What modules will this affect?
+
+## If Approved
+
+- Make minimal, focused changes
+- Ensure backward compatibility
+- Update all affected modules
+- Run full test suite: `dotnet test src/FSH.Starter.slnx`
+- Document the change
+
+## Alternatives to Consider
+
+| Instead of... | Consider... |
+|---------------|-------------|
+| Modifying Core | Extension method in module |
+| Changing Persistence | Custom repository in module |
+| Updating Web | Module-specific middleware |
+
+## If Not Approved
+
+Do not proceed. Suggest alternatives that don't require BuildingBlocks modifications.

.agents/rules/caching.md

@@ -0,0 +1,30 @@
+# Caching
+
+`src/BuildingBlocks/Caching/`. Read before adding cached reads or invalidation.
+
+## What's registered
+
+`AddHeroCaching(config)` always registers **`HybridCache`** (L1 in-memory + optional L2 Redis). Inject `HybridCache`, not `IDistributedCache`.
+
+- `CachingOptions.Redis` empty → in-memory only (dev fallback). Set → a **single shared `ConnectionMultiplexer`** (singleton `IConnectionMultiplexer`) backs both the L2 cache and the DataProtection key ring.
+- Defaults: total expiration 1h, L1 (local) expiration 2min (`CachingOptions`).
+- `ObservableHybridCache` transparently decorates `HybridCache` to emit OpenTelemetry (hits/misses/factory-duration/invalidations). You don't reference it — just inject `HybridCache`.
+
+## Pattern
+
+```csharp
+var perms = await cache.GetOrCreateAsync(
+    CacheKeys.UserPermissions(userId),
+    async ct => await LoadPermissionsAsync(userId, ct),
+    tags: [CacheKeys.Tags.Permissions, CacheKeys.Tags.User(userId)],
+    cancellationToken: ct);
+```
+
+- **Keys & tags live in `CacheKeys.cs`** — add new keys/tags there, don't inline strings. Existing: `UserPermissions(userId)`, `TenantTheme(tenantId)`, `IdempotencyEntry(tenantId,key)`, `ImpersonationGrantStatus(jti)`; tags `Permissions`, `Themes`, `Idempotency`, `Tenant(id)`, `User(id)`.
+- Invalidate with `RemoveAsync(key)` or `RemoveByTagAsync(tag)` in the relevant mutation handler.
+- `GetOrCreateAsync` gives **stampede protection** for free (factory runs once per key).
+
+## Gotchas
+
+- **No L1 backplane.** `RemoveByTagAsync` on one node does **not** evict L1 on peer nodes — cross-node staleness is bounded only by the 2-min local expiration. Don't rely on instant cross-node invalidation; keep local expiration short for hot, mutable data.
+- Don't reach for `IDistributedCache` directly except where the framework already does so deliberately (idempotency probe-read) — prefer `HybridCache`.

.agents/rules/database.md

@@ -0,0 +1,48 @@
+# Database & EF Core conventions
+
+Read before touching entities, DbContexts, migrations, or query filters.
+
+## Entities
+
+- `BaseEntity` — `Id`, `CreatedAt`, `UpdatedAt`, `TenantId`.
+- `AggregateRoot` — `BaseEntity` + domain events (`IHasDomainEvents`, `_domainEvents` list).
+- Marker interfaces: `IHasTenant`, `IAuditableEntity`, `ISoftDeletable`, `IGlobalEntity`.
+- Domain events inherit `DomainEvent` (record: `EventId`, `OccurredOnUtc`, `CorrelationId`, `TenantId`). Integration events implement `IIntegrationEvent`; handlers `IIntegrationEventHandler<T>`.
+
+## Tenant isolation (default-ON)
+
+- `BaseDbContext` auto-applies a tenant query filter to every entity. **Isolation is on by default.**
+- Opt out **only** via `IGlobalEntity` (e.g. `BillingPlan`, `ImpersonationGrant`, `Outbox`/`InboxMessage`).
+- A subclass DbContext that overrides `OnModelCreating` **must call `base.OnModelCreating(modelBuilder)` LAST**, or the auto-applied filters are lost.
+- Cross-tenant reads use `IgnoreQueryFilters()` **plus an explicit re-filter** — never rely on the absence of the filter.
+- **Query-filter naming:** SoftDelete filter is *named*; the tenant filter stays *anonymous* (Finbuckle owns it). Don't rename the tenant filter.
+
+## AsNoTracking — and when NOT to
+
+- Read-only queries: add `.AsNoTracking()` (Specifications default to it).
+- **Do NOT add `AsNoTracking()` to a read-then-mutate-then-`SaveChanges` query** — the entity must stay tracked or your changes won't persist. The analyzer (AP010) flags these as a smell, but for mutate-and-save flows it is a false positive — leave them tracked.
+- `AnyAsync(...)` materializes no entity, so `AsNoTracking()` there is a no-op — skip it.
+
+## Value generation for nav-collection children
+
+A child entity reached **only** through a parent's navigation collection needs `Property(x => x.Id).ValueGeneratedNever()` in its EF config — otherwise EF treats it as `Modified` instead of `Added` and the insert silently misbehaves.
+
+## Migrations
+
+All migrations live in **one** project, `src/Host/FSH.Starter.Migrations.PostgreSQL`, organized **per-module by folder** (`Identity/`, `Catalog/`, `Chat/`, …), each with its own `{Module}DbContextModelSnapshot`.
+
+```bash
+dotnet ef migrations add {Name} \
+  --project src/Host/FSH.Starter.Migrations.PostgreSQL \
+  --startup-project src/Host/FSH.Starter.Api \
+  --context {Module}DbContext
+```
+
+- **`migrations remove` operates on the snapshot** — run a full build *before* `migrations add` so the snapshot is current, or you can lose the previous migration.
+- The DB is **not** migrated at API startup. The `DbMigrator` host is a separate step: `apply` (default), `seed`, `seed-demo` (dev only), `list-pending`; flags `--tenant <id>`, `--catalog-only`, `--seed`. It migrates the tenant catalog first, then each tenant's per-module schema, serialized by a Postgres advisory lock.
+- `dotnet-ef` is pinned in `.config/dotnet-tools.json` — run `dotnet tool restore` first.
+
+## Tests + EF
+
+- Integration tests use Testcontainers (real PostgreSQL) — **Docker must be running**.
+- In integration tests, set the Finbuckle tenant context **inline in the same method** as the `UserManager`/`DbContext` call; an awaited-helper set is lost (AsyncLocal) and the tenant query filter NREs.

.agents/rules/eventing.md

@@ -0,0 +1,39 @@
+# Eventing — domain events, integration events, Outbox/Inbox
+
+Read before publishing/handling cross-module events. `src/BuildingBlocks/Eventing/`.
+
+## Two tiers
+
+- **Domain events** (in-process, pre-commit) — inherit `DomainEvent` (record: `EventId`, `OccurredOnUtc`, `CorrelationId`, `TenantId`). Raised on aggregates (`IHasDomainEvents`).
+- **Integration events** (cross-module, async) — implement `IIntegrationEvent` (`Id`, `OccurredOnUtc`, `TenantId`, `CorrelationId`, `Source`). Handlers implement `IIntegrationEventHandler<T>` (single `HandleAsync(T, ct)`), are `sealed`, live in `Events/` or `IntegrationEventHandlers/`.
+
+## The Outbox is the only way to publish
+
+**Do not call `IEventBus` directly from a handler.** Publish via the outbox so it commits in the same transaction and survives crashes:
+
+```csharp
+await _outboxStore.AddAsync(integrationEvent, ct).ConfigureAwait(false);
+```
+
+`EfCoreOutboxStore.AddAsync` serializes + `SaveChanges` immediately. `OutboxDispatcherHostedService` polls every `OutboxDispatchIntervalSeconds` (default 10), `OutboxDispatcher` pulls a batch (`OutboxBatchSize`, default 100), publishes via `IEventBus`, and dead-letters after `OutboxMaxRetries` (default 5) → `IsDead`. `OutboxMessage`/`InboxMessage` are `IGlobalEntity` (no tenant filter — the dispatcher has no tenant context; `TenantId` is an explicit column).
+
+## Idempotency is free (in-memory bus)
+
+`InMemoryEventBus` resolves handlers in a fresh DI scope and applies the **Inbox**: skips if `IInboxStore.HasProcessedAsync(eventId, handlerName)`, marks processed after success. Composite key `{Id, HandlerName}`; concurrent-insert race is swallowed. Don't hand-roll dedup.
+
+## Wiring (3 calls in the module's `ConfigureServices`)
+
+```csharp
+services.AddEventingCore(builder.Configuration);                        // serializer + bus + hosted dispatcher
+services.AddEventingForDbContext<MyDbContext>();                        // outbox/inbox stores (scoped)
+services.AddIntegrationEventHandlers(typeof(MyModule).Assembly);        // scans IIntegrationEventHandler<>
+```
+
+Bus = `EventingOptions.Provider`: `"RabbitMQ"` → `RabbitMqEventBus` (durable topic exchange); else `InMemoryEventBus` (default).
+
+## Gotchas
+
+- **Renaming/moving an integration event type breaks deserialization** — the outbox stores the assembly-qualified type name; `Type.GetType()` returns null → the message dead-letters. Keep event type names/namespaces stable, or migrate dead rows.
+- **Background handlers carry no HTTP/tenant context.** An open-generic or background handler that reads a tenant-filtered DbContext must restore Finbuckle context first via `IMultiTenantContextSetter` (see `WebhookFanoutHandler`, `modules/webhooks.md`).
+- In-memory bus runs handlers **synchronously in the publisher's scope** — keep handler work minimal; exceptions surface to the originating request (relevant for Notifications consuming Chat events).
+- Set `UseHostedServiceDispatcher=false` to drive the outbox via Hangfire instead of the hosted service.