@drunkcoding/dknet-implementation-skills 14.1.0 → 14.2.0

package/{skills → plugin/skills}/dknet-bdd-tests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dknet-bdd-tests
-description: Create and maintain Reqnroll + NUnit BDD .feature scenarios and step bindings in Minimal.App.BDDTests — request/status/response-body scenarios and domain-event side effects observed via log capture, for the hand-written PurchaseOrder and generator-driven Product samples. Use when adding or updating HTTP-facing scenarios for a DKNet.Templates feature. Result-level Result-object assertions, architecture rules and pure functional tests belong in the `dknet-unit-tests` skill instead — do not duplicate a behavior here that xUnit already covers. Invoke as `/dknet-bdd-tests <Feature>` to scaffold it for a feature.
+description: Create and maintain Reqnroll + NUnit BDD .feature scenarios and step bindings in <YourApp>.App.BDDTests — request/status/response-body scenarios and domain-event side effects observed via log capture, for the hand-written PurchaseOrder and generator-driven Product samples. Use when adding or updating HTTP-facing scenarios for a DKNet.Templates feature. Result-level Result-object assertions, architecture rules and pure functional tests belong in the `dknet-unit-tests` skill instead — do not duplicate a behavior here that xUnit already covers. Invoke as `/dknet-bdd-tests <Feature>` to scaffold it for a feature.
 metadata:
   kind: workflow
   arguments: "<Feature> e.g. Orders"
@@ -9,17 +9,23 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash
 
 Usage: `/dknet-bdd-tests <Feature> e.g. Orders`
 
-# BDD tests (Minimal.App.BDDTests)
+# BDD tests (<YourApp>.App.BDDTests)
 
 ## What BDD owns vs xUnit
 
-BDD owns user-facing HTTP behavior: request → status code → response body, and domain-event side effects
-observed through captured log lines. xUnit (`dknet-unit-tests`) owns architecture/convention rules, pure
-functional tests (entity methods, validators, specs), and result-level integration assertions on the
-handler's `IResult`/`IResultBase` object. Schema/model/migration assertions never belong in BDD. Don't
-write a BDD scenario for a rule already proven at the `Result` level in xUnit unless it's the one place
-that rule is reachable over HTTP — and don't add a duplicate xUnit HTTP test for a rule a BDD scenario
-already proves.
+**BDD is the default home for a feature's business rules.** Anything statable as "a caller does X and
+gets Y" — happy paths, refusals, state transitions, precondition conflicts, domain-event side effects
+observed through captured log lines — is a scenario here, because that is the form a team can read as
+the specification of the feature.
+
+xUnit (`dknet-unit-tests`) keeps what a scenario cannot express or cannot distinguish:
+architecture/convention rules, pure functional tests (entity methods, validators, specs in isolation),
+EF model/schema/migration shape, and a `Result`-level assertion **only** where the HTTP response does
+not identify which rule fired (two failures sharing one status code, a `NotFoundError` versus an
+ownership filter that also answers `404`). Schema/model/migration assertions never belong in BDD.
+
+Never assert the same rule in both suites. If a rule is reachable over HTTP and its response
+identifies it, the scenario is the test — delete the xUnit duplicate rather than keeping both.
 
 Both shipped suites are teaching material: every scenario must be about the `PurchaseOrder` (manual) or
 `Product` (automated) sample's business behavior, never about logging, health checks, CORS, security
@@ -185,7 +191,7 @@ Scenario: A product name that is already taken is refused
 The log-line step just asserts on `LogCapture.Messages` — no polling needed here because the response body
 already round-trips through the handler that logs synchronously before returning; if a future scenario
 asserts on an *async consumer's* log line instead (a domain event's own subscriber, not the handler that
-raised it), poll with `Eventually.IsTrueAsync(...)` from `Minimal.App.TestSupport` rather than asserting
+raised it), poll with `Eventually.IsTrueAsync(...)` from `<YourApp>.App.TestSupport` rather than asserting
 immediately — the in-memory bus publishes non-blocking:
 
 ```csharp
@@ -242,7 +248,7 @@ like `"status":"placed"` where the surrounding shape isn't in question.
 ## Commands
 
 ```bash
-dotnet test ApiEndpoints/Minimal.App.BDDTests/Minimal.App.BDDTests.csproj --filter "TestCategory=PurchaseOrder"
+dotnet test ApiEndpoints/<YourApp>.App.BDDTests/<YourApp>.App.BDDTests.csproj --filter "TestCategory=PurchaseOrder"
 ```
 
 ## Step-by-step
@@ -302,10 +308,10 @@ Before any BDD design or edits:
 ### Scope
 
 Work only on BDD test artifacts and closely related support wiring:
-- `ApiEndpoints/Minimal.App.BDDTests/Features/**/*.feature`
-- `ApiEndpoints/Minimal.App.BDDTests/Features/**/Steps/*.cs`
-- `ApiEndpoints/Minimal.App.BDDTests/Support/*.cs`
-- `ApiEndpoints/Minimal.App.BDDTests/*.csproj`
+- `ApiEndpoints/<YourApp>.App.BDDTests/Features/**/*.feature`
+- `ApiEndpoints/<YourApp>.App.BDDTests/Features/**/Steps/*.cs`
+- `ApiEndpoints/<YourApp>.App.BDDTests/Support/*.cs`
+- `ApiEndpoints/<YourApp>.App.BDDTests/*.csproj`
 
 ### Constraints
 
@@ -324,6 +330,9 @@ Work only on BDD test artifacts and closely related support wiring:
   forwarded DataAnnotations — a scenario expecting `400` from an out-of-range value will fail against
   a `201`. Cover that gap by asserting what happens, or leave it to the manual flow.
 - Do not implement unrelated domain/business logic outside BDD test scope.
+- Cover every business rule the feature exposes over HTTP — happy path, each refusal, each state
+  transition. If a rule already has an xUnit `Result`-level test and its HTTP response identifies it
+  uniquely, write the scenario here and say in your report that the xUnit duplicate should go.
 
 ### Workflow
 
@@ -338,7 +347,7 @@ Work only on BDD test artifacts and closely related support wiring:
 3. Implement/adjust step bindings in `Steps/*.cs`.
 4. Run validation:
    - `dotnet build -c Release`
-   - `dotnet test ApiEndpoints/Minimal.App.BDDTests`
+   - `dotnet test ApiEndpoints/<YourApp>.App.BDDTests`
 5. Report:
    - changed files
    - scenario count

package/{skills → plugin/skills}/dknet-bdd-tests/checklist.md

@@ -34,6 +34,6 @@ Use this checklist before considering BDD scenario work complete.
 ## Validation
 
 - [ ] `dotnet build -c Release` succeeds
-- [ ] `dotnet test ApiEndpoints/Minimal.App.BDDTests/Minimal.App.BDDTests.csproj` passes
+- [ ] `dotnet test ApiEndpoints/<YourApp>.App.BDDTests/<YourApp>.App.BDDTests.csproj` passes
 - [ ] No undefined or pending Reqnroll steps
 - [ ] Scenario names are readable in test output

package/{skills → plugin/skills}/dknet-crud/SKILL.md

@@ -16,14 +16,14 @@ Commands only: Create, Update, a business-rule transition, Delete, and the gener
 `dknet-queries-specs`. For DTO shape and Mapster wiring, load `dknet-dto-mapping`. For whether a
 rule belongs on the entity or in a handler, load `dknet-ddd-principles` first.
 
-## GlobalUsings already in Minimal.AppServices
+## GlobalUsings already in <YourApp>.AppServices
 
-`Minimal.AppServices/GlobalUsings.cs` gives every file in the project these without an explicit
+`<YourApp>.AppServices/GlobalUsings.cs` gives every file in the project these without an explicit
 `using`: `DKNet.AspCore.Extensions.ModelBinding` (`[FromClaim]`), `DKNet.SlimBus.Extensions`
 (`Fluents.*`, `NotFoundError`), `System.ComponentModel.DataAnnotations`, `System.Security.Claims`
-(`ClaimTypes`), `System.Text.Json.Serialization`, `FluentResults`, `Minimal.Domains.Services`,
+(`ClaimTypes`), `System.Text.Json.Serialization`, `FluentResults`, `<YourApp>.Domains.Services`,
 `Microsoft.Extensions.DependencyInjection`, `FluentValidation`, `Mapster`, `MapsterMapper`,
-`Minimal.AppServices.Extensions`, `DKNet.SlimBus.Extensions.LazyMapper`, `Minimal.AppServices.Share`
+`<YourApp>.AppServices.Extensions`, `DKNet.SlimBus.Extensions.LazyMapper`, `<YourApp>.AppServices.Share`
 (`PreconditionCodes`, `IPrincipalProvider`). An action file typically adds only the entity's and its
 own spec's namespace.
 
@@ -38,7 +38,7 @@ The handler method is `OnHandle(TRequest, CancellationToken)`, never `Handle`. B
 by assembly scan onto the in-memory bus — no per-message registration. Handlers never call
 `SaveChanges`: the SlimBus EF Core interceptor auto-saves once, after the handler returns. A request
 record is `public sealed record`; its validator and handler are `internal sealed class` — enforced
-by `Minimal.App.Tests/Architecture/AppServiceTests.cs`.
+by `<YourApp>.App.Tests/Architecture/AppServiceTests.cs`.
 
 File layout: one file per verb, request + validator + handler co-located —
 `<Feature>/V1/Actions/<Verb>.cs` (`ManualSample/V1/Actions/Create.cs`, `Update.cs`, `Cancel.cs`,
@@ -58,6 +58,10 @@ if (string.IsNullOrEmpty(request.ByUser))
 }
 ```
 
+`[FromRequestHeader("X-Header-Name")]` (same populator, same overwrite-always guarantee) reads a
+named request header instead of a claim — for a correlation id or tenant hint, never for identity: a
+header is caller-supplied and is not an authorization signal.
+
 The demo authentication provider (`FeatureManagement:EnableDemoAuthentication`) supplies this claim
 locally and in tests, so the guard is reachable but rarely hit — an authenticated caller with a
 missing name claim still has to fail it explicitly, there is no fallback to a system account.
@@ -88,7 +92,7 @@ from `DataOwnerHook`/the audit hook instead, or hand-write the action.
 ## FluentValidation
 
 A validator is `internal sealed class XValidator : AbstractValidator<TRequest>`, co-located with
-its request. There is no per-route opt-in call: `Minimal.Api/Configs/FluentValidationConfig.cs`
+its request. There is no per-route opt-in call: `<YourApp>.Api/Configs/FluentValidationConfig.cs`
 registers every validator in the assembly —
 
 ```csharp
@@ -99,7 +103,7 @@ builder.Services.AddValidatorsFromAssembly(typeof(AppSetup).Assembly, includeInt
 group (`Program.cs`), so it runs on generated routes exactly as it runs on hand-mapped ones. A
 request failing validation never reaches the handler; it short-circuits to `400` (or `409`, see
 below) with no handler code involved. Two hard constraints: the validator class must live in
-`Minimal.AppServices` (one in `Minimal.Api` is never registered), and it must be `internal sealed`.
+`<YourApp>.AppServices` (one in `<YourApp>.Api` is never registered), and it must be `internal sealed`.
 
 **Ordinary input rules** stay inline (`RuleFor(a => a.Amount).GreaterThan(0)`). Keep `Id` out of an
 update validator — an unknown/empty id is a `404` from the handler's spec lookup, not a `400` from
@@ -142,9 +146,9 @@ If it refused a missing id too, the route's own `404` would be hidden behind a `
 
 **Validators on generated requests are the supported way to add a business rule to a generated
 route.** `CreateProductRequestValidator` and `DeleteProductRequestValidator` both target generated
-request types (`Minimal.AppServices.Crud.CreateProductRequest` / `DeleteProductRequest`) — no
+request types (`<YourApp>.AppServices.Crud.CreateProductRequest` / `DeleteProductRequest`) — no
 literal `Map*` call is needed for FluentValidation to reach them, only the `using
-Minimal.AppServices.Crud;` and a constructor parameter naming the request type. This is the fix for
+<YourApp>.AppServices.Crud;` and a constructor parameter naming the request type. This is the fix for
 the one thing `[DataAnnotations]` cannot do on a generated route: `[Range]`/`[Required]`/etc.
 forwarded onto a generated request property is **not evaluated**, because .NET's validation source
 generator only recognizes literal `Map*(string, Delegate)` calls in the compiling project's own
@@ -229,7 +233,7 @@ Naming, mechanical from the entity's own signatures: `Create<Entity>Request` (fr
 `<Method><Entity>Request` (from `[CrudAction]`), `Delete<Entity>Request` (always). Handlers mirror
 the name with `Handler` instead of `Request` — `CreateProductHandler`, `ChangePriceProductHandler`,
 `ApproveProductHandler`, `DiscontinueProductHandler`, `AssignSupplierReferenceProductHandler` — all
-in namespace `Minimal.AppServices.Crud`, emitted under
+in namespace `<YourApp>.AppServices.Crud`, emitted under
 `obj/Generated/DKNet.SlimBus.Generators/.../<Entity>CrudRequests.g.cs` and `...Handlers.g.cs`. They
 are compiler output, not files in the repo — inspect them after a build, not by searching source.
 
@@ -255,7 +259,7 @@ Fetch by a private, generated `ProductByIdCrudSpec`, `404` if missing, call the
 
 **Replacing a generated handler.** The generated file's own doc comment says how: "Write a class
 implementing the same IHandler to replace it." Add your own `internal sealed class` implementing
-`Fluents.Requests.IHandler<ChangePriceProductRequest, ProductDto>` in `Minimal.AppServices` — DI
+`Fluents.Requests.IHandler<ChangePriceProductRequest, ProductDto>` in `<YourApp>.AppServices` — DI
 registration is by interface via assembly scan, so yours and the generated one cannot coexist; keep
 only yours (there is no attribute to suppress generation of the handler alone — drop the whole
 route with `CrudMapOptions.Exclude` if you also need to change the request shape).
@@ -281,12 +285,12 @@ constructor.
 
 Every body shares `title: "Error"`, `status`, `type` (the status's name, e.g. `"Conflict"`), and
 `traceId` (the current `Activity` id, falling back to `TraceIdentifier`). One registration answers
-all three failure kinds — `Minimal.Api/Configs/FluentValidationConfig.cs`'s single
+all three failure kinds — `<YourApp>.Api/Configs/FluentValidationConfig.cs`'s single
 `AddErrorResponses(...)` call — there is no second place to configure this.
 
 ## Architecture rules enforced by tests
 
-`Minimal.App.Tests/Architecture/AppServiceTests.cs` and `RecordArchitectureTests.cs` pin, exactly:
+`<YourApp>.App.Tests/Architecture/AppServiceTests.cs` and `RecordArchitectureTests.cs` pin, exactly:
 
 - Every class implementing `IRequestHandler<>`/`IRequestHandler<,>`/`IConsumer<>` must be
   non-public and `sealed` (`AllHandlerClassesShouldBeInternalAndSealed`).
@@ -298,13 +302,14 @@ all three failure kinds — `Minimal.Api/Configs/FluentValidationConfig.cs`'s si
 - A `[GenerateDto]` type must expose no property whose type (or generic argument) inherits
   `DomainEntity` (`DtosWithGenerateDtoAttribute_ShouldNotHaveProperties_ThatAreDomainEntities`) —
   the DTO boundary must not leak an entity.
-- No record type in `Minimal.Domains` or `Minimal.AppServices` may declare a public property with a
+- No record type in `<YourApp>.Domains` or `<YourApp>.AppServices` may declare a public property with a
   **private** setter (`RecordTypes_ShouldNotContain_PrivateSetters_OnPublicProperties`) — AutoMapper
   (Mapster's `MapToConstructor`/property assignment) cannot fill it.
 
 ## Step-by-step
 
-**mode=manual** (mirror `ManualSample/PurchaseOrder`):
+**mode=manual** (mirror `ManualSample/PurchaseOrder`) — only after confirming the operation is one
+of the five the generator genuinely cannot express (`dknet-feature-lifecycle` §1):
 
 1. Add `<Feature>/V1/Actions/Create.cs`: request implementing `IWitResponse<TDto>` with
    `[FromClaim(ClaimTypes.Name)] ByUser`, a co-located validator, a handler constructing the
@@ -316,6 +321,7 @@ all three failure kinds — `Minimal.Api/Configs/FluentValidationConfig.cs`'s si
    `Result.Ok()`.
 4. Wire each into `<Feature>V1Endpoint.cs` with a literal `Map*` call (`dknet-endpoint`) so
    DataAnnotations validation, if any, is actually enforced.
+5. Keep `ApiEndpoints/<YourApp>.Client` in step by adding the matching client methods (`I{Plural}Client`, contracts under `Contracts/`) in the same change.
 
 **mode=auto** (mirror `AutomatedSample/Product`):
 
@@ -327,6 +333,7 @@ all three failure kinds — `Minimal.Api/Configs/FluentValidationConfig.cs`'s si
 4. For an operation that must write more than one aggregate, or must reject a repeat call as a
    domain failure rather than a `200`, write a `...Command` (not `...Request`) and drop the
    generated route for that member with `CrudMapOptions.Exclude("MethodName")` in the endpoint.
+5. Keep `ApiEndpoints/<YourApp>.Client` in step by adding the matching client methods for every route the endpoint maps, in the same change.
 
 ## Validation checklist
 
@@ -386,10 +393,17 @@ the entity to already carry `[CrudCreate]`/`[CrudUpdate]`/`[RaisesEvent]`, and t
 generate without them. If `mode=` was not supplied, detect it: grep the entity for `[CrudCreate]`;
 present it means `auto`, absent means `manual`. Say which you detected.
 
-Pick one per aggregate, don't mix them for the same entity:
+Pick one per aggregate, don't mix them for the same entity, and **start from the declarative
+shape**:
 
-- **Hand-written** (below) — every request/validator/handler/spec/DTO is a file you write. Needed whenever the aggregate has a business rule beyond DataAnnotations, a filtered query, idempotent writes, or a DTO that must hide fields.
-- **Declarative CRUD generation** (further down) — `[CrudCreate]`/`[CrudUpdate]`/`[GenerateDto]` on the entity itself; `DKNet.SlimBus.Generators` produces the request/handler/route types for you. Only for genuinely plain CRUD — read the validation-gap caveat before choosing it.
+- **Declarative CRUD generation (`mode=auto`, the default)** — `[CrudCreate]`/`[CrudUpdate]`/
+  `[CrudAction]` + `[GenerateDto]` on the entity itself; `DKNet.SlimBus.Generators` produces the
+  request/handler/route types for you. A business rule that must *refuse* the operation is written
+  as a FluentValidation validator against the generated request and still runs, so it is not a
+  reason to leave this path.
+- **Hand-written (`mode=manual`)** — every request/validator/handler/spec/DTO is a file you write.
+  Step down to it only for idempotent create, an enforced DataAnnotations rule, a multi-aggregate
+  transaction, a bespoke query, or `[FromClaim]` acting-user attribution.
 
 The `dknet-feature-lifecycle` skill §1 is the authoritative comparison between the two; use it to decide.
 
@@ -405,7 +419,7 @@ The `dknet-feature-lifecycle` skill §1 is the decision procedure if the mode is
 #### Required reading
 
 1. The reference sections above
-2. `ApiEndpoints/Minimal.AppServices/ManualSample/V1/` (exemplar: `Actions/{Create,Update,Cancel,Delete}.cs`, `Specs/SpecGetPurchaseOrder.cs`, `Queries/{GetPurchaseOrderById,ListPurchaseOrders}.cs`, `Events/`, `PurchaseOrderDto.cs`)
+2. `ApiEndpoints/<YourApp>.AppServices/ManualSample/V1/` (exemplar: `Actions/{Create,Update,Cancel,Delete}.cs`, `Specs/SpecGetPurchaseOrder.cs`, `Queries/{GetPurchaseOrderById,ListPurchaseOrders}.cs`, `Events/`, `PurchaseOrderDto.cs`)
 
 #### Steps
 
@@ -430,7 +444,7 @@ The `dknet-feature-lifecycle` skill §1 is the decision procedure if the mode is
 
 ### Path 2: Declarative CRUD generation (`mode=auto`)
 
-For a genuinely plain CRUD entity, declare the CRUD surface on the entity instead of writing it. Exemplar: `Product` (`ApiEndpoints/Minimal.Domains/Features/AutomatedSample/Entities/Product.cs`, `ApiEndpoints/Minimal.AppServices/AutomatedSample/V1/ProductDto.cs`).
+The default path: declare the CRUD surface on the entity instead of writing it. Exemplar: `Product` (`ApiEndpoints/<YourApp>.Domains/Features/AutomatedSample/Entities/Product.cs`, `ApiEndpoints/<YourApp>.AppServices/AutomatedSample/V1/ProductDto.cs`).
 
 Most of the entity-side attributes are `/dknet-entity mode=auto`'s job. This command's own output at
 the AppServices layer is small on purpose: **one `[GenerateDto]` line, plus any hand-written event
@@ -460,7 +474,7 @@ consumer.** If you find yourself writing a request, validator, or handler here,
 
 #### What gets generated
 
-`DKNet.SlimBus.Generators` produces (namespace `Minimal.AppServices.Crud`, not committed — inspect via `dotnet build` then `obj/Generated/DKNet.SlimBus.Generators/`):
+`DKNet.SlimBus.Generators` produces (namespace `<YourApp>.AppServices.Crud`, not committed — inspect via `dotnet build` then `obj/Generated/DKNet.SlimBus.Generators/`):
 
 - `Create<Entity>Request` / `Change<Member><Entity>Request` (named after the `[CrudUpdate]` method, e.g. `ChangePriceProductRequest`) + matching `internal sealed` handlers (`Create<Entity>Handler` / `Change<Member><Entity>Handler`) — no hand-written request/validator/handler exists for these.
 - `<Entity>CrudEndpointExtensions.Map<Entity>Crud()` — GetById/GetList/Delete map straight to `DKNet.AspCore.Extensions`'s generic `MapGetById<TEntity,TKey,TDto>`/`MapGetList`/`MapDeleteById`; Create/Update use the generated handlers above.
@@ -469,7 +483,7 @@ consumer.** If you find yourself writing a request, validator, or handler here,
 
 - Do NOT hand-write a request or handler for a `[CrudCreate]`/`[CrudUpdate]` member while its route is still generated — that defeats the point of the generator. A **validator** is the exception and the supported shape: a FluentValidation validator for the generated request runs on the generated route through the group filter. Exclude a route by name (`CrudMapOptions.Exclude(string)`) and hand-write it below the `Map<Entity>Crud(...)` call only when the operation writes more than one aggregate in one transaction. Generated and hand-written routes coexisting in one endpoint is the shipped shape, not a smell — see `ProductV1Endpoint`.
 - **Validation gap, confirmed live**: a `[Range]`/`[Required]` on a `[CrudCreate]`/`[CrudUpdate]` parameter *is* forwarded onto the generated request property, but it is **never enforced** under this template's endpoint-registration convention — the .NET 10 validation source generator only recognizes literal `Map*(string, Delegate)` calls, and the generated route goes through `DKNet.AspCore.Extensions`'s generic `MapPost<TRequest,TDto>` wrapper instead. `POST /v1/products` with a negative price returns `201`, not `400`. Do not present a DataAnnotations attribute on a generated request as enforced without checking the endpoint's mapping style.
-- Acting-user attribution cannot use `[FromClaim]` on a generated request (the generator forwards only `System.ComponentModel.DataAnnotations` attributes) — it goes through `DKNet.EfCore.DataAuthorization`'s `DataOwnerHook` instead, wired once in `Minimal.Api/Configs/ServiceConfigs.cs`, not per-entity.
+- Acting-user attribution cannot use `[FromClaim]` on a generated request (the generator forwards only `System.ComponentModel.DataAnnotations` attributes) — it goes through `DKNet.EfCore.DataAuthorization`'s `DataOwnerHook` instead, wired once in `<YourApp>.Api/Configs/ServiceConfigs.cs`, not per-entity.
 - No idempotency key support on the generated create route — see `/dknet-endpoint`'s "Alternative: generated CRUD route" section if the feature needs it.
 
 #### Steps

package/{skills → plugin/skills}/dknet-ddd-principles/SKILL.md

@@ -24,7 +24,7 @@ An aggregate is a transactional consistency boundary: everything inside it is sa
 
 - If two pieces of data must always be consistent with each other *at the moment they're saved* (e.g. a `PurchaseOrder`'s `Amount` and its `Status` — cancelling and re-pricing an order in the same save must not leave those two fields disagreeing), they belong in the same aggregate. That's why `PurchaseOrder` owns both `Amount` and `Status` directly rather than splitting them into two persisted types.
 - If two pieces of data can be consistent *eventually*, a moment apart, they belong in separate aggregates, coordinated through a domain event — not a direct object reference.
-- Aggregates reference each other by ID (`Guid`), never by object reference. `PurchaseOrder` (`ApiEndpoints/Minimal.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`) does not hold a `Customer` object — it holds a plain `CustomerName` string, no navigation property back to another aggregate.
+- Aggregates reference each other by ID (`Guid`), never by object reference. `PurchaseOrder` (`ApiEndpoints/<YourApp>.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`) does not hold a `Customer` object — it holds a plain `CustomerName` string, no navigation property back to another aggregate.
 
 Keep aggregates small. A large aggregate means more contention (every mutation locks the whole thing) and usually signals a boundary was drawn around "things that seem related" rather than "things that must be consistent together."
 
@@ -41,26 +41,73 @@ An invariant is a rule that must always hold true for an entity (e.g. "amount is
 
 - Properties are `{ get; private set; }`. Nothing outside the entity can put it into an invalid state directly.
 - The constructor establishes the invariant for a new entity. Named mutation methods (`ChangeAmount`, `Cancel` — see `PurchaseOrder` in `dknet-entity`) re-establish it for every mutation, and are the *only* path to changing mutable state.
-- A rule that depends on the entity's **own current state** belongs on the entity, or right next to the fetch in the handler when it must read the stored row first. `PurchaseOrder.Cancel(string userId)` is the clearest example: `CancelPurchaseOrderCommandHandler` (`ApiEndpoints/Minimal.AppServices/ManualSample/V1/Actions/Cancel.cs`) checks `order.Status == PurchaseOrderStatus.Cancelled` and fails the request *before* calling `Cancel`; the transition itself still lives on the entity. Note the weakness this leaves — the guard is one call away from being bypassed by a second caller who skips it, so treat handler-side guards as a boundary check, not as the invariant's home.
+- A rule that depends on the entity's **own current state** belongs on the entity, or right next to the fetch in the handler when it must read the stored row first. `PurchaseOrder.Cancel(string userId)` is the clearest example: `CancelPurchaseOrderCommandHandler` (`ApiEndpoints/<YourApp>.AppServices/ManualSample/V1/Actions/Cancel.cs`) checks `order.Status == PurchaseOrderStatus.Cancelled` and fails the request *before* calling `Cancel`; the transition itself still lives on the entity. Note the weakness this leaves — the guard is one call away from being bypassed by a second caller who skips it, so treat handler-side guards as a boundary check, not as the invariant's home.
 - If a rule needs data external to the entity (e.g. "customer name must be unique across all orders"), that's not an entity invariant — it's a cross-entity business rule, and it belongs in the command handler as a duplicate-check `Specification` query (see `dknet-crud`), because the entity has no way to see other entities.
 
 ## When to Use a Domain Event
 
-This codebase has two equally valid ways to raise the same kind of event — pick the one that matches how much control you need over the raise:
-
-- **Hand-raised** (`PurchaseOrder`): the constructor calls `AddEvent(new PurchaseOrderCreatedEvent(Id, CustomerName, Amount))` directly, in application code you can step through in a debugger. You write the payload by hand. Use this when the event's payload, timing, or "did this actually happen" condition needs logic more specific than "a tracked property changed."
-- **Declared** (`Product`): the class carries `[RaisesEvent(EventOperations.Created, Include = [nameof(Id), nameof(Name), nameof(Price)])]` and `[RaisesEvent(EventOperations.Updated, nameof(Price))]` — no line of application code calls `AddEvent` anywhere in `AutomatedSample/`. DKNet's EF Core save hook reads these declarations and raises the composed event records (`ProductCreatedEvent`, `ProductPriceUpdatedEvent`) after a successful `SaveChanges`, driven by the change tracker. Use this when the event is a straightforward "this property changed" notification and you're already using `[CrudCreate]`/`[CrudUpdate]` for the entity.
-  The trade-offs: you cannot single-step from "constructor ran" to "event raised" the way you can with `AddEvent`, and the payload's name and shape follow a fixed composition rule (`<Entity><NarrowingProps><Operation>Event`) rather than one you choose — verify the composed name against the compiled assembly before wiring a consumer to it.
-
-Both styles are delivered identically afterward: `ApiEndpoints/Minimal.Infra/Services/EventPublisher.cs` forwards to `IMessageBus` regardless of which raised the event.
-
-Reach for either one when **something outside this aggregate might care that this happened** — another aggregate needs to react, or an external system needs to be notified. `Product`'s declared `Created` event is consumed both in-process and over Azure Service Bus (`ProductCreatedNotificationHandler`), exactly as a hand-raised one would be.
+First decide **whether** there should be an event at all. Reach for one when **something outside
+this aggregate might care that this happened** — another aggregate needs to react, or an external
+system needs to be notified. `Product`'s declared `Created` event is consumed both in-process and
+over Azure Service Bus (`ProductCreatedNotificationHandler`).
 
 Do NOT reach for an event when the effect is entirely local to this one request:
-- Setting a computed field during the same handler → just do it in the handler or the entity method, no event needed.
+
+- Setting a computed field during the same handler → just do it in the handler or the entity method.
 - A validation failure → return `Result.Fail(...)`, don't publish an event.
 
-If you can't name a concrete future subscriber (even a logging handler counts, but "just in case" doesn't), it's not an event yet — add it when a real consumer appears.
+If you can't name a concrete future subscriber (even a logging handler counts, but "just in case"
+doesn't), it's not an event yet — add it when a real consumer appears.
+
+### How to raise it — take the highest rung that works
+
+| Rung | Form | Use it when |
+|---|---|---|
+| 1 | **`[RaisesEvent]` on the class** | The event means "this entity was created" or "these properties changed". Default. |
+| 2 | **`AddEvent<TEvent>()` in a mutation method** | Rung 1 can't decide *whether* to raise — the condition is real logic — but the payload is still a projection of the entity. |
+| 3 | **`AddEvent(new TEvent(...))`** | The payload is not a projection of the entity: it carries a computed value, a before/after pair, or data the entity doesn't hold. |
+
+**Rung 1 — declared (`Product`).** The class carries
+`[RaisesEvent(EventOperations.Created, Include = [nameof(Id), nameof(Name), nameof(Price)])]` and
+`[RaisesEvent(EventOperations.Updated, nameof(Price))]`; no line of application code calls
+`AddEvent` anywhere in `AutomatedSample/`. DKNet's EF Core save hook reads the declarations and
+raises the composed records (`ProductCreatedEvent`, `ProductPriceUpdatedEvent`) after a successful
+`SaveChanges`, driven by the change tracker. `<YourApp>.App.Tests/Architecture/SampleInvariantTests`
+fails the build if a hand-written `AddEvent(` appears under `AutomatedSample`.
+
+What you give up: you cannot single-step from "constructor ran" to "event raised", and the payload's
+name and shape follow a fixed composition rule (`<Entity><NarrowingProps><Operation>Event`) rather
+than one you choose — verify the composed name against the compiled assembly before wiring a
+consumer to it, it has no source file.
+
+**Rung 2 — type-only (`AddEvent<TEvent>()`).** Registers the event *type*; the publisher maps the
+entity onto it (`IMapper.Map(entity, entityType, eventType)`) when the save succeeds:
+
+```csharp
+public void Cancel(string byUser)
+{
+    if (Status == PurchaseOrderStatus.Cancelled) return;   // the raise IS conditional
+    Status = PurchaseOrderStatus.Cancelled;
+    SetUpdatedBy(byUser);
+    AddEvent<PurchaseOrderCancelledEvent>();               // payload projected from the entity
+}
+```
+
+You keep control of *when*, and still hand-write no payload. It **requires an `IMapper`
+registration** — with none, the publisher throws `EventException` rather than silently dropping the
+event — and the event record's members must be mappable from the entity's own properties.
+
+**Rung 3 — instance (`AddEvent(new …)`, `PurchaseOrder`).** The constructor calls
+`AddEvent(new PurchaseOrderCreatedEvent(Id, CustomerName, Amount))` directly. Full control of
+payload, name and timing, at the cost of a hand-written record and a hand-written construction site
+that can drift from the entity. Take it only when the payload is genuinely not a projection of the
+entity's current state.
+
+All three are delivered identically afterward:
+`ApiEndpoints/<YourApp>.Infra/Services/EventPublisher.cs` forwards to `IMessageBus` regardless of
+which raised the event. Mixing rungs on one entity is allowed — a declared `Created` alongside one
+hand-raised transition event is fine — except under `AutomatedSample`, where the architecture test
+pins it to rung 1 only.
 
 ## Avoiding Anemic Domain Models
 
@@ -77,6 +124,8 @@ The handler's job is orchestration: fetch the entity (via `IRepositorySpec` + a
 - [ ] Does this type ever get looked up independently of its parent? If no, it's a value object, not an entity.
 - [ ] Does this rule only need data already on the entity? If yes, enforce it in the entity's constructor/`Update` method, not the handler.
 - [ ] Can I name a real, current subscriber for this event? If no, skip the event for now.
+- [ ] If it is an event: can `[RaisesEvent]` express it? If not, can `AddEvent<TEvent>()`? Only then
+      hand-build the payload with `AddEvent(new …)`.
 - [ ] Is the handler computing business logic, or just orchestrating fetch → mutate → persist → map? If it's computing, move the logic onto the entity.
 
 ---

package/{skills → plugin/skills}/dknet-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dknet-docs
-description: Generate structured technical documentation and Mermaid architecture diagrams for completed features. Use this when documenting implemented features with README, architecture diagrams, and API references. Invoke as `/dknet-docs <Feature>` to scaffold it for a feature.
+description: Generate structured technical documentation for a completed feature and every endpoint it exposes — README, architecture and flow diagrams drawn with archify (Mermaid as the fallback), per-route API reference, data model, and domain events. Use this when documenting an implemented feature. Invoke as `/dknet-docs <Feature>` to scaffold it for a feature.
 metadata:
   kind: workflow
   arguments: "<Feature>"
@@ -29,7 +29,9 @@ Usage: `/dknet-docs <Feature>`
 | `data-model.md` | Entity diagram, properties, constraints, relationships |
 | `events.md` | Domain events catalog with publishers and subscribers |
 
-**Diagram tool**: All diagrams use **Mermaid.js** — rendered natively in GitHub, VS Code Preview, and most wikis. No extra tools required.
+**Diagram tool**: **archify first, Mermaid as the fallback** — see *Diagrams* below. Every endpoint the
+feature exposes gets its own section in `api-reference.md`; a feature is not documented until every
+route it publishes is.
 
 **Real examples already in this repo**: this skill is about documenting a *new* feature you just
 built, not about the two worked samples that ship with the template — but those samples
@@ -107,7 +109,7 @@ X-Idempotency-Key: 6e6f4d3c-1b7e-4c7a-9f1d-8a2b5c6d7e01
 
 ### Step 3: Write architecture.md (Diagrams + Data Flow)
 
-**What you're doing**: Show how the feature is structured across layers with a vertical slice diagram. Use Mermaid for all diagrams.
+**What you're doing**: Show how the feature is structured across layers with a vertical slice diagram. Render it with archify per *Diagrams* below; the Mermaid examples here are the fallback shape.
 
 **Five diagrams to include**:
 
@@ -124,13 +126,13 @@ Example Vertical Slice Overview diagram (from the `PurchaseOrder` sample):
 ```mermaid
 graph TD
     Client["Client / Browser"]
-    subgraph API["Minimal.Api"]
+    subgraph API["<YourApp>.Api"]
         EP["PurchaseOrderV1Endpoint.cs"]
     end
-    subgraph AppServices["Minimal.AppServices"]
+    subgraph AppServices["<YourApp>.AppServices"]
         HDL["Command Handlers"]
     end
-    subgraph Domains["Minimal.Domains"]
+    subgraph Domains["<YourApp>.Domains"]
         ENT["PurchaseOrder (AggregateRoot)"]
     end
     DB[("PostgreSQL")]
@@ -143,6 +145,24 @@ graph TD
 
 **What you're doing**: Full endpoint documentation with curl examples, request/response schemas, and error codes.
 
+**One section per route, no exceptions.** Enumerate the feature's routes from the endpoint config —
+for a generated slice that means every route `Map<Entity>Crud()` publishes (`GET {id}`, `GET /`,
+`POST /`, one `PUT {id}` per `[CrudUpdate]`, `DELETE {id}`, and one route per `[CrudAction]`), minus
+anything `CrudMapOptions.Exclude` drops, plus every hand-mapped route below it. Build once and read
+the generated `<Entity>CrudEndpoints.g.cs` rather than guessing the list. Each section states:
+
+| Line | What it must say |
+|---|---|
+| Method + path | Including the `/v{n}` version segment when `EnableVersioning` is on |
+| Authorization | The scope the route requires, and whether it comes from `[EndpointGroupScope]`, `o.Configure(...)` or a hand-mapped `.RequireAuthorization(...)` — or "none, `RequireAuthorization` off" |
+| Idempotency | `X-Idempotency-Key` required, or explicitly "not idempotent — a retry creates a second row" for a generated create route |
+| Request | Every bound field, its type, whether it is required, and where it binds from (body, route, query, claim) |
+| Response | Status code + DTO, and every error status the route can actually return |
+| Enforcement | Whether the route's DataAnnotations are enforced (literal `Map*` call) or forwarded only (generated/generic route) |
+| curl | One runnable example including required headers |
+
+Add a `sequence` diagram for any route whose flow is not "bind → validate → handler → save → map".
+
 Copy `templates/api-reference-template.md` from this skill's folder and fill it in — Endpoints Summary table, one section per endpoint (query params/request body, response, error table, curl example), Common Error Response Format. Note the pagination-defaults gotcha: a hand-written list query's `pageIndex`/`pageSize` defaults differ from the generated `MapGetList` route's contract (`pageNumber`/`pageSize` default 1/1000, configurable ceiling via `DKNet:ListQuery`, plus `fromDate`/`toDate` windowing) — document whichever contract this feature's route actually uses. Also document the standard error format: `result.Response()` (`DKNet.AspCore.Extensions.Responses`) converts a failed `FluentResults` result into `ProblemDetails` with messages under an `errors` array; a `NotFoundError` produces the same shape with `status: 404`.
 
 Example endpoint entry (from the `PurchaseOrder` sample):
@@ -214,31 +234,43 @@ public sealed record PurchaseOrderCreatedEvent(Guid Id, string CustomerName, dec
 
 ---
 
-## Mermaid Diagram Types Reference
+## Diagrams — archify first, Mermaid as the fallback
 
-Use appropriate Mermaid diagram types for different aspects:
+Draw architecture, flow, sequence, data-flow and lifecycle diagrams with **archify**
+(<https://github.com/tt-a1i/archify>), a skill that turns a small typed JSON spec into a validated,
+self-contained HTML diagram plus SVG/PNG exports. Install it once with
+`npx skills add tt-a1i/archify`, then invoke the `archify` skill and let it author, validate and
+deliver each diagram — do not hand-write its JSON from memory.
 
-| Diagram type | Mermaid keyword | When to use |
-|-------------|-----------------|-------------|
-| Component flow | `graph TD` / `graph LR` | Overview of layers, event flows |
-| Request sequence | `sequenceDiagram` | How a specific API call flows step-by-step |
-| Entity classes | `classDiagram` | Class relationships and properties |
-| Entity-Relation | `erDiagram` | Database table structure |
-| State machine | `stateDiagram-v2` | Status transitions |
-| Timeline | `timeline` | Feature evolution, release history |
+Pick the archify type per diagram:
 
-**All Mermaid diagrams are fenced code blocks**:
+| Diagram | archify type | Mermaid fallback |
+|---|---|---|
+| Vertical slice across the six projects | `architecture` | `graph TD` |
+| Request lifecycle for one route (endpoint → handler → entity → DB → response) | `sequence` | `sequenceDiagram` |
+| Domain-event path (raise → publisher → in-memory + external consumers) | `dataflow` | `graph LR` |
+| Status transitions the handlers actually perform | `lifecycle` | `stateDiagram-v2` |
+| A multi-step business process or approval gate | `workflow` | `graph TD` |
+| Table structure | *(none — keep Mermaid)* | `erDiagram` |
+
+Commit both the spec and the export next to the docs that reference them:
 
-````md
-```mermaid
-graph TD
-    A --> B
 ```
-````
+docs/features/<feature>/diagrams/
+├── <feature>-slice.architecture.json     ← archify source, re-render from this
+├── <feature>-slice.svg                   ← exported, referenced from architecture.md
+├── <feature>-create.sequence.json
+└── <feature>-create.svg
+```
 
-They render automatically on GitHub, GitLab, VS Code (Markdown Preview), Docusaurus, and most modern wikis.
+Reference an export from markdown with a plain image link
+(`![Vertical slice](diagrams/<feature>-slice.svg)`), so it renders on GitHub, in VS Code preview and
+in a wiki without archify installed.
 
----
+**Fallback rule:** if archify is not installed and you cannot install it, write the diagram as a
+fenced ```mermaid block in the markdown itself and say in your report that the diagram is Mermaid
+pending an archify render. Never ship a feature doc with no diagram at all. An `erDiagram` stays
+Mermaid either way — archify has no table-schema type.
 
 ## Feature Docs Folder Structure
 
@@ -248,9 +280,10 @@ docs/
     └── purchase-orders/          ← kebab-case folder name
         ├── README.md             ← Overview (START HERE)
         ├── architecture.md       ← Diagrams + vertical slice
-        ├── api-reference.md      ← Endpoints + examples + curl
+        ├── api-reference.md      ← One section per route + examples + curl
         ├── data-model.md         ← Entity diagram + constraints
         ├── events.md             ← Domain events + subscribers
+        ├── diagrams/             ← archify sources + exported SVGs
         └── decisions/            ← Optional ADRs
             └── adr-001-idempotency-key-strategy.md
 ```
@@ -281,16 +314,25 @@ You are producing authoritative feature documentation for a vertical slice that
    - how the acting user is attributed (`[FromClaim]` vs `DataOwnerHook`).
    For automated slices, read event names off the compiled assembly, not off a guess at the
    composition rule.
-2. Render the four required artifacts under `docs/features/<feature>/` (or `docs/<feature>/` if the slice is template-internal):
+2. Enumerate every route the feature publishes (generated + hand-mapped) before writing anything —
+   this is the spine of `api-reference.md` and the completeness check at the end.
+3. Render the required artifacts under `docs/features/<feature>/` (or `docs/<feature>/` if the slice is template-internal):
    - `README.md` (feature overview + quick links)
-   - `architecture.md` (Mermaid diagrams: layer flow, sequence for Create, ER snippet)
-   - `data-model.md`
-   - `api-reference.md`
-3. Cross-link from `docs/features/README.md` (or whichever index file lists features).
-4. Verify all referenced files exist and Mermaid blocks render (no stray fences).
+   - `architecture.md` (vertical slice, create sequence, event path — drawn with archify per
+     *Diagrams*, Mermaid only if archify is unavailable)
+   - `data-model.md` (ER diagram stays Mermaid)
+   - `api-reference.md` (one section per route, per the table in Step 4)
+   - `events.md` when the feature raises or consumes any event
+   - `diagrams/` holding each archify JSON source next to its exported SVG
+4. Cross-link from `docs/features/README.md` (or whichever index file lists features).
+5. Verify every route has a section, every referenced diagram file exists, and any Mermaid block
+   renders (no stray fences).
 
 ### Constraints
 
 - Do not invent fields, validators, events, or endpoints — only document what's in the code.
 - Use the templates in the skill folder verbatim where they fit; deviations need a one-line note.
 - No hand-wavey language ("flexible", "robust", "scalable") — describe what the code actually does.
+- Every route the feature publishes has its own `api-reference.md` section. A missing route is a
+  failed run, not a trim.
+- Diagrams are archify renders unless archify could not be installed; say which in the report.

package/{skills → plugin/skills}/dknet-docs/templates/README-template.md

@@ -51,14 +51,14 @@ Authorization: Bearer {token}
 
 | Layer | Path |
 |-------|------|
-| Domain Entity | `ApiEndpoints/Minimal.Domains/Features/{EntityFolder}/Entities/{EntityName}.cs` |
-| EF Core Mapper | `ApiEndpoints/Minimal.Infra/Features/{EntityFolder}/Mappers/{EntityName}Mapper.cs` |
-| Create Handler | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Actions/Create.cs` |
-| Update Handler | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Actions/Update.cs` |
-| Delete Handler | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Actions/Delete.cs` |
-| Domain Events | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Events/` |
-| Query Specs | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Specs/` |
-| API Endpoints | `ApiEndpoints/Minimal.Api/ApiEndpoints/{EntityName}V1Endpoints.cs` |
+| Domain Entity | `ApiEndpoints/<YourApp>.Domains/Features/{EntityFolder}/Entities/{EntityName}.cs` |
+| EF Core Mapper | `ApiEndpoints/<YourApp>.Infra/Features/{EntityFolder}/Mappers/{EntityName}Mapper.cs` |
+| Create Handler | `ApiEndpoints/<YourApp>.AppServices/{FeatureFolder}/V1/Actions/Create.cs` |
+| Update Handler | `ApiEndpoints/<YourApp>.AppServices/{FeatureFolder}/V1/Actions/Update.cs` |
+| Delete Handler | `ApiEndpoints/<YourApp>.AppServices/{FeatureFolder}/V1/Actions/Delete.cs` |
+| Domain Events | `ApiEndpoints/<YourApp>.AppServices/{FeatureFolder}/V1/Events/` |
+| Query Specs | `ApiEndpoints/<YourApp>.AppServices/{FeatureFolder}/V1/Specs/` |
+| API Endpoints | `ApiEndpoints/<YourApp>.Api/ApiEndpoints/{EntityName}V1Endpoints.cs` |
 
 ## Related Documentation
 

package/{skills → plugin/skills}/dknet-docs/templates/api-reference-template.md

@@ -1,5 +1,12 @@
 # {FeatureName} — API Reference
 
+> Every route the feature publishes gets its own section below — generated CRUD routes included.
+> Read the list off the built `<Entity>CrudEndpoints.g.cs` plus the endpoint config's hand-mapped
+> calls; do not trim one because it looks obvious. Each section states method + path, the scope it
+> requires and where that scope is declared, whether it is idempotent, every bound field and where it
+> binds from, every status it can return, whether its DataAnnotations are enforced, and a runnable
+> curl. See the `dknet-docs` skill, Step 4.
+
 **Base Path**: `/api/v1/{feature-route}`
 **Auth**: Bearer token required on all endpoints
 **Content-Type**: `application/json`