@drunkcoding/dknet-implementation-skills 14.1.0 → 14.1.1

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

@@ -12,9 +12,20 @@ Usage: `/dknet-endpoint <Feature> <Entity> [mode=manual|auto] [routePrefix] [ver
 # Skill: Endpoint Configuration
 
 Wires AppServices actions/queries — or an entity's `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]`
-declarations — to HTTP routes via `IEndpointConfig`. Three ways to map a route: pick the one matching
-how the feature's actions were built (`mode=manual` or `mode=auto`), and reach for the third only when
-neither fits one particular route.
+declarations — to HTTP routes via `IEndpointConfig`.
+
+**Pick the highest rung that expresses the route. Do not start at the bottom.**
+
+| Rung | Shape | Use it when |
+|---|---|---|
+| 1 | **Option B** — `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]` on the entity + one `group.Map{Entity}Crud()` call (§3) | The route is create, update, delete, get-by-id, list, or a single-aggregate business action. This is the default for a new feature — declare the operation on the entity and let the generator emit the request, handler and route. |
+| 2 | **Option C** — the package's generic `MapGetById`/`MapGetList`/`MapPost<TRequest,TDto>`/… helpers (§4) | The entity carries no CRUD attributes (a read-mostly reference table, an entity you don't own), but the route is still a plain shape the helpers already implement. |
+| 3 | **Option A** — a literal `group.MapPost/MapGet/MapPut/MapDelete(...)` call dispatching through `IMessageBus` (§2) | Nothing above can express it: multiple aggregates in one transaction, a response shape with no DTO behind it, or a create route that must enforce `.RequiredIdempotentKey()` or a DataAnnotations attribute (§5). |
+
+Rungs mix freely inside one `Map(RouteGroupBuilder)` — `ProductV1Endpoint` maps its whole generated
+slice, excludes one route by name, and hand-maps two below it. `mode=manual`/`mode=auto` says which
+rung the feature's *actions* were built for; it does not license dropping to rung 3 for a route rung 1
+would have covered.
 
 ## 1. The `IEndpointConfig` contract
 
@@ -28,7 +39,7 @@ internal sealed class {Entity}V1Endpoint : IEndpointConfig
 ```
 
 - **Discovery**: every non-abstract `IEndpointConfig` in the API assembly is found by
-  `UseEndpointConfigs(...)`, called once from `Minimal.Api/Program.cs`. Never register a route group
+  `UseEndpointConfigs(...)`, called once from `<YourApp>.Api/Program.cs`. Never register a route group
   by hand.
 - **Versioning**: `EnableVersioning` (`FeatureManagement`, default `true`) turns `GroupEndpoint` into
   `/v{version}/{route}` — `"/products"` at `Version => 1` becomes `/v1/products`. Off, the group
@@ -56,11 +67,11 @@ MapDelete(...)` call, dispatching through `IMessageBus` by hand:
 ```csharp
 using DKNet.AspCore.Extensions.Responses;
 using DKNet.AspCore.Idempotency;
-using Minimal.AppServices.ManualSample.V1.Actions;
-using Minimal.AppServices.ManualSample.V1.Queries;
-using PurchaseOrderDto = Minimal.AppServices.ManualSample.V1.PurchaseOrderDto;
+using <YourApp>.AppServices.ManualSample.V1.Actions;
+using <YourApp>.AppServices.ManualSample.V1.Queries;
+using PurchaseOrderDto = <YourApp>.AppServices.ManualSample.V1.PurchaseOrderDto;
 
-namespace Minimal.Api.ApiEndpoints.ManualSample;
+namespace <YourApp>.Api.ApiEndpoints.ManualSample;
 
 internal sealed class PurchaseOrderV1Endpoint : IEndpointConfig
 {
@@ -80,10 +91,6 @@ internal sealed class PurchaseOrderV1Endpoint : IEndpointConfig
                 "Create purchase order. <br/><br/> Note: Idempotency key is required in the header. <br/>" +
                 "X-Idempotency-Key: {IdempotencyKey} <br/>");
 
-        group.MapGet("/", async ([AsParameters] ListPurchaseOrdersQuery query, IMessageBus bus, CancellationToken ct) =>
-                Results.Ok(await bus.Send(query, cancellationToken: ct)))
-            .WithDescription("Get purchase orders (paged, optionally filtered by customer name).");
-
         group.MapGet("{id:guid}", async (Guid id, IMessageBus bus, CancellationToken ct) =>
             {
                 var dto = await bus.Send(new GetPurchaseOrderByIdQuery { Id = id }, cancellationToken: ct);
@@ -144,12 +151,12 @@ registers the entire generated CRUD surface; hand-mapped routes for what the gen
 go below it.
 
 ```csharp
-using Minimal.AppServices.AutomatedSample.V1;
-using Minimal.AppServices.AutomatedSample.V1.Actions;
-using Minimal.AppServices.AutomatedSample.V1.Queries;
-using Minimal.AppServices.Crud;
+using <YourApp>.AppServices.AutomatedSample.V1;
+using <YourApp>.AppServices.AutomatedSample.V1.Actions;
+using <YourApp>.AppServices.AutomatedSample.V1.Queries;
+using <YourApp>.AppServices.Crud;
 
-namespace Minimal.Api.ApiEndpoints.AutomatedSample;
+namespace <YourApp>.Api.ApiEndpoints.AutomatedSample;
 
 internal sealed class ProductV1Endpoint : IEndpointConfig
 {
@@ -197,7 +204,7 @@ internal sealed class ProductV1Endpoint : IEndpointConfig
 }
 ```
 
-`ProductScopes` (`Minimal.Api/ApiEndpoints/AutomatedSample/ProductScopes.cs`) is a plain
+`ProductScopes` (`<YourApp>.Api/ApiEndpoints/AutomatedSample/ProductScopes.cs`) is a plain
 `internal static class` of policy-name constants — one per authorization scope the routes above
 require, registered as authorization policies by `AddAuthConfig()` only when `RequireAuthorization`
 is on:
@@ -229,7 +236,7 @@ PUT {id} (per update request), DELETE {id} and each generated domain-action endp
 ### Where the generated code lives
 
 `DKNet.SlimBus.Generators` emits, per entity, under
-`ApiEndpoints/Minimal.AppServices/obj/Generated/DKNet.SlimBus.Generators/.../` — not committed, so
+`ApiEndpoints/<YourApp>.AppServices/obj/Generated/DKNet.SlimBus.Generators/.../` — not committed, so
 build once (`dotnet build`) and read it there for the exact shape:
 
 - `{Entity}CrudRequests.g.cs` — one `sealed partial record` per route (`Create{Entity}Request`,
@@ -305,8 +312,9 @@ group.MapParameterlessActionById<TRequest, TKey, TDto>("{id}/x", "PUT"); // any
   already resolve `ErrorResponseOptions` via `[FromServices]` — calling these helpers directly gets
   the same behavior.
 
-Reach for Option C only when neither A nor B fits one particular entity — most features should be
-entirely A or entirely B.
+Reach for Option C when the entity carries no CRUD attributes but the route is still one of these
+stock shapes — it is a rung above hand-mapping, not a last resort. Drop to Option A only for a route
+none of these helpers can express.
 
 ## 5. Cross-cutting behavior
 
@@ -333,12 +341,34 @@ Only Option A's literal `group.MapPost("/", async (CreateXRequest req, ...) => .
 attribute enforced. If a create/update rule must be enforced, either hand-map that one route (Option
 A) or write it as a FluentValidation validator instead of a DataAnnotations attribute.
 
-**Authorization scopes are conditional on the flag, always.** `RequireAuthorization(...)` needs
-authorization middleware to evaluate — that middleware is only added when `FeatureManagement:
-RequireAuthorization` is `true`. Calling `.RequireAuthorization(scope)` unconditionally would throw at
-request time with the flag off (local development, both test suites). Every scope call in
-`ProductV1Endpoint` is therefore gated behind reading the flag from `IOptions<FeatureOptions>`, as
-shown in §3 — copy that guard, don't call `RequireAuthorization` bare.
+**Authorization scopes: declare them on the class with `[EndpointGroupScope]` first.**
+`EndpointGroupScopeAttribute` (`DKNet.AspCore.Extensions.Endpoints`, **13.0.0 or newer**) sits above
+the `IEndpointConfig` class and names the scope one or more HTTP methods require:
+
+```csharp
+[EndpointGroupScope(ProductScopes.Read, EndpointHttpMethods.Get)]
+[EndpointGroupScope(ProductScopes.Write, EndpointHttpMethods.Post, EndpointHttpMethods.Put,
+    EndpointHttpMethods.Delete)]
+internal sealed class ProductV1Endpoint : IEndpointConfig { /* ... */ }
+```
+
+It is stackable; a declaration naming no method becomes the group's default, and a per-method
+declaration beats that default for its own method. It applies to generated and hand-mapped routes
+alike, skips any route that already names its own policy or allows anonymous access, and **fails
+closed** — once one declaration exists, a served method with neither a declaration nor a group
+default is refused when the group's endpoints are built. Above all, it is applied only when
+`EndpointRegistrationOptions.RequireAuthorization` is `true` (the value `Program.cs` assigns from
+`FeatureOptions.RequireAuthorization`), so it needs no flag check of its own.
+
+Fall back to `o.Configure(CrudOp.X, …)`, `o.Configure("RouteName", …)`, or
+`.RequireAuthorization(scope)` on a `RouteHandlerBuilder` **only when two routes sharing one HTTP
+method need different scopes** — `Product`'s `Update` and `AssignSupplierReference` are both `PUT`,
+and only the latter may demand `products.supplier`. Those three forms do *not* self-gate: with the
+flag off no policies were registered and the call throws at request time, so each must sit behind the
+`IOptions<FeatureOptions>` guard shown in §3. The shipped `ProductV1Endpoint` is written exactly this
+way: two class-level declarations, and a guarded per-route override for only the two `PUT` routes
+(`AssignSupplierReference`, `discontinue`) that need their own scope. Full treatment: the
+`dknet-auth-and-ownership` skill.
 
 **Status-counts helper.** `group.MapGetStatusCounts<TEntity>("status", new StatusPropertyInfo(nameof(X.Status), typeof(XStatus)))`
 is a template-local extension (not part of the published package) that groups an entity's rows by an
@@ -365,9 +395,10 @@ skill.
 
 ### `mode=manual`
 
-1. Confirm the feature's `AppServices` layer exposes hand-written request/query records (see the
-   `dknet-crud` skill).
-2. Create `ApiEndpoints/Minimal.Api/ApiEndpoints/{Feature}/{Entity}V1Endpoint.cs`, `internal sealed`,
+1. Confirm rung 3 is actually needed — that the route is not one `[CrudCreate]`/`[CrudUpdate]`/
+   `[CrudAction]` (rung 1) or a generic helper (rung 2) would have covered — and that the feature's
+   `AppServices` layer exposes hand-written request/query records (see the `dknet-crud` skill).
+2. Create `ApiEndpoints/<YourApp>.Api/ApiEndpoints/{Feature}/{Entity}V1Endpoint.cs`, `internal sealed`,
    implementing `IEndpointConfig`.
 3. Map every route as a literal `group.MapPost/MapGet/MapPut/MapDelete(...)` call per §2, dispatching
    through `IMessageBus`.
@@ -379,25 +410,21 @@ skill.
 1. Confirm the entity declares `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]` (see `/dknet-entity`)
    and its DTO is `[GenerateDto(typeof(Entity))]`.
 2. Build once so the generated `Map{Entity}Crud()` extension exists.
-3. Create `ApiEndpoints/Minimal.Api/ApiEndpoints/{Feature}/{Entity}V1Endpoint.cs`, calling
-   `group.Map{Entity}Crud()` — bare, or with an `Action<CrudMapOptions>` per §3 for per-route scopes
-   or exclusions.
+3. Create `ApiEndpoints/<YourApp>.Api/ApiEndpoints/{Feature}/{Entity}V1Endpoint.cs`, calling
+   `group.Map{Entity}Crud()` — bare, or with an `Action<CrudMapOptions>` per §3 for exclusions.
+   Declare authorization scopes with `[EndpointGroupScope]` on the class (§5); use
+   `o.Configure(...)` only for a route whose scope its HTTP method cannot decide.
 4. For anything the generator can't express, hand-map it below the composite call, dropping the
    generated route it replaces via `o.Exclude(...)` when one exists.
 
 ## Verification
 
-```bash
-dotnet build -c Release
-dotnet run --project ApiEndpoints/Minimal.Api
-```
-
-Then exercise the route via `/docs` (Scalar, when `EnableSwagger` is on) or curl:
+`dotnet build -c Release`, then `dotnet run --project ApiEndpoints/<YourApp>.Api` and exercise the
+route via `/docs` (Scalar, when `EnableSwagger` is on) or curl:
 
 ```bash
 curl -X POST https://localhost:5001/v1/{route} \
   -H "Content-Type: application/json" -H "X-Idempotency-Key: $(uuidgen)" -d '{...}'
-curl https://localhost:5001/v1/{route}/{id}
 ```
 
 ## Common mistakes
@@ -406,7 +433,7 @@ curl https://localhost:5001/v1/{route}/{id}
 |---|---|---|
 | A `[Range]`/`[Required]` on a `[CrudCreate]`/`[CrudUpdate]` parameter is enforced | A generated route accepts the out-of-range value and returns `201`/`200` | The .NET validation source generator can't see through the package's generic `Map*<TRequest,TDto>` wrapper — see §5 |
 | `.RequiredIdempotentKey()` works the same on a generated create route | There's no route to call it on unless you exclude `"Create"` and hand-map it | The generated extension's calls are compiler output, not source you can chain onto |
-| `RequireAuthorization(scope)` is safe to call unconditionally | It throws at request time when `RequireAuthorization` is off | No authorization middleware is added unless the flag is on — gate every call on `IOptions<FeatureOptions>` |
+| `RequireAuthorization(scope)` is safe to call unconditionally | It throws at request time when `RequireAuthorization` is off | No authorization middleware is added unless the flag is on — gate every call on `IOptions<FeatureOptions>`, or declare the scope with `[EndpointGroupScope]`, which is applied only when the flag is on |
 | A `[CrudAction]` method parameter named `byUser` is the acting-user stamp | It becomes a caller-settable, body-bound `required string ByUser` on the generated request | Generated requests carry no `[FromClaim]`; the automated sample's acting-user attribution goes through `DataOwnerHook`/`AddCurrentUserProvider` instead — never name a generated action parameter after the acting user |
 | Excluding a route by a typo'd name is silently ignored | The host throws `ArgumentException` at start-up | `ValidateRouteNames` checks every `Exclude`/`Configure` name against the entity's real route names before the app can serve traffic |
 | A hand-mapped endpoint can call the generic `MapPost<TRequest,TDto>` helper directly for convenience | It works, but bypasses the DataAnnotations-enforcement your Option A route would otherwise get | Only a literal `group.MapPost("/", async (...) => ...)` — not a call to the generic wrapper — is visible to the validation source generator |
@@ -432,7 +459,7 @@ not apply to it. If `mode=` was not supplied, detect it: a `[CrudCreate]` on the
 ### Required reading
 
 1. The reference sections above
-2. `ApiEndpoints/Minimal.Api/ApiEndpoints/ManualSample/PurchaseOrderV1Endpoint.cs` (exemplar — every route is a literal `group.MapPost/MapGet/MapPut/MapDelete(...)` call against the raw minimal-API surface, base route `/v1/purchase-orders`)
+2. `ApiEndpoints/<YourApp>.Api/ApiEndpoints/ManualSample/PurchaseOrderV1Endpoint.cs` (exemplar — every route is a literal `group.MapPost/MapGet/MapPut/MapDelete(...)` call against the raw minimal-API surface, base route `/v1/purchase-orders`)
 3. The `dknet-feature-lifecycle` skill §1 — read the endpoint-registration and request-idempotency rows before choosing a mapping style
 
 ### Steps (`mode=manual`)
@@ -455,4 +482,4 @@ not apply to it. If `mode=` was not supplied, detect it: a `[CrudCreate]` on the
 
 ### Alternative: generated CRUD route
 
-If the entity is plain CRUD with `[CrudCreate]`/`[CrudUpdate]`/`[GenerateDto]` already in place (see `Product`), skip hand-mapping entirely — the generator emits a `Map<Entity>Crud()` extension (namespace `Minimal.AppServices.Crud`) that wires GetById/GetList/Create/Update/Delete in one call. `ProductV1Endpoint` is the exemplar: `group.MapProductCrud(o => …)` carrying the per-route scopes and one `Exclude("Discontinue")`, plus a `.WithDescription`, with the two routes the generator cannot express hand-mapped below it. This path does **not** get `.RequiredIdempotentKey()` and its DataAnnotations validation is not enforced (the .NET 10 validation source generator can't see through the generic `Map*<TRequest,TDto>` wrapper the generated route uses) — confirmed live: `POST /v1/products` with a negative price returns `201`. Only use this path when idempotency and enforced validation are not required.
+If the entity is plain CRUD with `[CrudCreate]`/`[CrudUpdate]`/`[GenerateDto]` already in place (see `Product`), skip hand-mapping entirely — the generator emits a `Map<Entity>Crud()` extension (namespace `<YourApp>.AppServices.Crud`) that wires GetById/GetList/Create/Update/Delete in one call. `ProductV1Endpoint` is the exemplar: `group.MapProductCrud(o => …)` carrying the per-route scopes and one `Exclude("Discontinue")`, plus a `.WithDescription`, with the two routes the generator cannot express hand-mapped below it. This path does **not** get `.RequiredIdempotentKey()` and its DataAnnotations validation is not enforced (the .NET 10 validation source generator can't see through the generic `Map*<TRequest,TDto>` wrapper the generated route uses) — confirmed live: `POST /v1/products` with a negative price returns `201`. Only use this path when idempotency and enforced validation are not required.

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

@@ -1,6 +1,6 @@
 ---
 name: dknet-entity
-description: Create DDD domain entities following this project's AggregateRoot/DomainEntity inheritance pattern, either hand-written (mode=manual) or generator-declared (mode=auto). Use when adding a new domain entity or owned type to Minimal.Domains. Invoke as `/dknet-entity <Feature> <Entity> [mode=manual|auto] [props…]` to scaffold it for a feature.
+description: Create DDD domain entities following this project's AggregateRoot/DomainEntity inheritance pattern, either hand-written (mode=manual) or generator-declared (mode=auto). Use when adding a new domain entity or owned type to <YourApp>.Domains. Invoke as `/dknet-entity <Feature> <Entity> [mode=manual|auto] [props…]` to scaffold it for a feature.
 metadata:
   kind: workflow
   arguments: "<Feature> <Entity> [mode=manual|auto] [props…] e.g. Orders Order mode=manual Number:string Total:decimal"
@@ -13,8 +13,14 @@ Usage: `/dknet-entity <Feature> <Entity> [mode=manual|auto] [props…] e.g. Orde
 
 Create domain entities that integrate with this project's DDD infrastructure — `AggregateRoot`,
 `DomainEntity`, and (rarely) owned value objects — in either of the two shapes this template ships:
-hand-written (`mode=manual`, mirrors `ManualSample/PurchaseOrder`) or generator-declared
-(`mode=auto`, mirrors `AutomatedSample/Product`).
+generator-declared (`mode=auto`, mirrors `AutomatedSample/Product`) or hand-written
+(`mode=manual`, mirrors `ManualSample/PurchaseOrder`).
+
+**`mode=auto` is the default.** Declare the CRUD surface with `[CrudCreate]`/`[CrudUpdate]`/
+`[CrudAction]` and the events with `[RaisesEvent]`; hand-write an entity's operations only for the
+reasons `dknet-feature-lifecycle` §1 lists. Within a hand-written entity, raise events in the same
+order of preference: `[RaisesEvent]`, then `AddEvent<TEvent>()` (payload projected from the entity
+by `IMapper`), then `AddEvent(new …)` with a hand-built payload.
 
 If the aggregate boundary, entity-vs-value-object choice, or invariant placement isn't obvious, read
 `dknet-ddd-principles` first — this skill covers class mechanics, not those judgment calls. Event
@@ -25,11 +31,11 @@ here — this skill only covers how an entity raises an event.
 
 ```
 AuditedEntity<Guid>   (DKNet.EfCore.Abstractions.Entities — Id, CreatedBy/On, UpdatedBy/On)
-  └── DomainEntity     (Minimal.Domains/Share/DomainEntity.cs)
-       └── AggregateRoot (Minimal.Domains/Share/AggregateRoot.cs)
+  └── DomainEntity     (<YourApp>.Domains/Share/DomainEntity.cs)
+       └── AggregateRoot (<YourApp>.Domains/Share/AggregateRoot.cs)
 ```
 
-`Minimal.Domains/Share/DomainEntity.cs`:
+`<YourApp>.Domains/Share/DomainEntity.cs`:
 
 ```csharp
 public abstract class DomainEntity : AuditedEntity<Guid>
@@ -45,7 +51,7 @@ public abstract class DomainEntity : AuditedEntity<Guid>
 }
 ```
 
-`Minimal.Domains/Share/AggregateRoot.cs`:
+`<YourApp>.Domains/Share/AggregateRoot.cs`:
 
 ```csharp
 public abstract class AggregateRoot : DomainEntity
@@ -89,7 +95,7 @@ and every property setter is `private` — don't redeclare any of them.
 
 ## mode=manual — hand-written (`ManualSample/PurchaseOrder`)
 
-`Minimal.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`:
+`<YourApp>.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`:
 
 ```csharp
 public enum PurchaseOrderStatus { Draft, Placed, Cancelled }
@@ -137,7 +143,7 @@ public sealed class PurchaseOrder : AggregateRoot
 }
 ```
 
-`Minimal.Domains/Features/ManualSample/Entities/PurchaseOrderCreatedEvent.cs` — the whole file:
+`<YourApp>.Domains/Features/ManualSample/Entities/PurchaseOrderCreatedEvent.cs` — the whole file:
 
 ```csharp
 public sealed record PurchaseOrderCreatedEvent(Guid Id, string CustomerName, decimal Amount);
@@ -155,11 +161,14 @@ Rules this shape follows:
 - Every mutation method calls `SetUpdatedBy(userId)` at the end.
 - The domain event is raised by hand: `AddEvent(new PurchaseOrderCreatedEvent(...))` inside the
   constructor, right where the aggregate becomes valid. The event itself is a plain
-  `public sealed record` next to the entity, in the same file or the same folder.
+  `public sealed record` next to the entity, in the same file or the same folder. This is the
+  lowest rung — a hand-written entity can still carry `[RaisesEvent]`, or call
+  `AddEvent<TEvent>()` and let `IMapper` project the payload; reach for a hand-built payload only
+  when it is not a projection of the entity's own state.
 
 ## mode=auto — generator-declared (`AutomatedSample/Product`)
 
-`Minimal.Domains/Features/AutomatedSample/Entities/Product.cs` (XML docs trimmed):
+`<YourApp>.Domains/Features/AutomatedSample/Entities/Product.cs` (XML docs trimmed):
 
 ```csharp
 [RaisesEvent(EventOperations.Created, Include = [nameof(Id), nameof(Name), nameof(Price)])]
@@ -207,7 +216,7 @@ public class Product : AggregateRoot, IOwnedBy
 }
 ```
 
-**`Product` is not `sealed`.** No architecture test enforces sealing on `Minimal.Domains` entities
+**`Product` is not `sealed`.** No architecture test enforces sealing on `<YourApp>.Domains` entities
 (only on mappers/handlers/validators), and nothing subclasses it — an inconsistency, not a rule to
 copy. Default to `sealed` unless you have a concrete reason not to, as `mode=manual` does.
 
@@ -234,13 +243,14 @@ uses them.
 - None of the three has a hand-written source file — they're compiled output. Verify a composed name
   against the built assembly before wiring a consumer to it:
   ```bash
-  strings ApiEndpoints/Minimal.Domains/bin/Release/net10.0/Minimal.Domains.dll | grep Event
+  strings ApiEndpoints/<YourApp>.Domains/bin/Release/net10.0/<YourApp>.Domains.dll | grep Event
   ```
 - `[RaisesEvent]` alone raises nothing — the host must register `DKNet.EfCore.Events`' save hook
   (`AddSlimBusEfCoreInterceptor<CoreDbContext>()`, already wired in this template) before declared
   events publish.
-- Never both styles for the same logical change: pick `AddEvent` (mode=manual) or `[RaisesEvent]`
-  (mode=auto) for a given entity's events, not a mix on one property. Writing a consumer for a
+- Never two raise styles for the same logical change: one property's event comes from
+  `[RaisesEvent]`, `AddEvent<TEvent>()`, or `AddEvent(new …)` — never a mix on one property. Prefer
+  them in that order; see `dknet-ddd-principles` for when each rung is the right one. Writing a consumer for a
   raised event (either style) is covered by `dknet-messaging-events`, not this skill.
 
 ### Generator attributes: `[CrudCreate]`, `[CrudUpdate]`, `[CrudAction]`
@@ -305,11 +315,11 @@ the interface alone doesn't do it.
 
 ## Domain services, sequences, and `DomainSchemas`
 
-`Minimal.Domains/Share/DomainSchemas.cs` holds named schema constants (`Migration = "migrate"`,
+`<YourApp>.Domains/Share/DomainSchemas.cs` holds named schema constants (`Migration = "migrate"`,
 `Profile = "pro"`) for reuse across mappers — neither sample uses one; both pass a literal schema
 string to `ToTable(...)` instead. Add a constant only when a schema name is reused by >1 entity.
 
-`Minimal.Domains/Share/Sequences.cs` declares named PostgreSQL sequences:
+`<YourApp>.Domains/Share/Sequences.cs` declares named PostgreSQL sequences:
 
 ```csharp
 [SqlSequence]
@@ -322,7 +332,7 @@ public enum Sequences
 }
 ```
 
-The domain-service contract pattern that wraps a sequence (`Minimal.Domains/Services/`):
+The domain-service contract pattern that wraps a sequence (`<YourApp>.Domains/Services/`):
 
 ```csharp
 public interface IDomainService;                                       // marker, no members
@@ -333,7 +343,7 @@ public interface ISequenceServices : IDomainService
 public interface IMembershipService : ISequenceServices;                // one sequence, one interface
 ```
 
-The `Minimal.Infra` implementation is a one-line primary-constructor subclass of an internal
+The `<YourApp>.Infra` implementation is a one-line primary-constructor subclass of an internal
 `SequenceService` base (see `dknet-efcore-config`). Neither sample uses a sequence; add one the same
 way `IMembershipService`/`MembershipService` do for `Sequences.Membership`, for entities needing a
 human-readable sequential id instead of a `Guid`.
@@ -359,9 +369,9 @@ builder.OwnsOne(e => e.ShippingAddress, owned =>
 });
 ```
 
-## Architecture tests that constrain `Minimal.Domains`
+## Architecture tests that constrain `<YourApp>.Domains`
 
-`Architecture/RecordArchitectureTests.cs` scans `Minimal.Domains`/`Minimal.AppServices` for any
+`Architecture/RecordArchitectureTests.cs` scans `<YourApp>.Domains`/`<YourApp>.AppServices` for any
 record with a public property that has a **private** setter, and fails — Mapster/AutoMapper can't
 map those. A hand-written event record (`public sealed record XCreatedEvent(...)`) is positional and
 passes by construction. `Architecture/SampleInvariantTests.cs` enforces the two-sample split:
@@ -373,10 +383,10 @@ conventions above are followed by convention, not test (unlike mapper/handler/va
 
 ## Unit tests to mirror
 
-- `Minimal.App.Tests/Unit/ManualSample/PurchaseOrderTests.cs` — constructor sets properties and
+- `<YourApp>.App.Tests/Unit/ManualSample/PurchaseOrderTests.cs` — constructor sets properties and
   raises `PurchaseOrderCreatedEvent` (asserted via `order.GetEvents()`); the rehydration constructor
   does not raise it; mutation methods stamp `UpdatedBy`.
-- `Minimal.App.Tests/Unit/AutomatedSample/ProductTests.cs` — constructor sets properties (no event
+- `<YourApp>.App.Tests/Unit/AutomatedSample/ProductTests.cs` — constructor sets properties (no event
   assertion — declared events don't raise outside a real `SaveChanges`, see
   `dknet-messaging-events`); reflection asserts `[CrudCreate]`/`[CrudUpdate]` `DataAnnotations` are
   present, the only thing a unit test can prove about a forwarded-but-unenforced attribute;
@@ -387,7 +397,7 @@ conventions above are followed by convention, not test (unlike mapper/handler/va
 
 **mode=manual**
 
-1. Create `ApiEndpoints/Minimal.Domains/Features/<Feature>/Entities/<Entity>.cs` following the
+1. Create `ApiEndpoints/<YourApp>.Domains/Features/<Feature>/Entities/<Entity>.cs` following the
    three-constructor shape above, `AddEvent(new <Entity>CreatedEvent(...))` in the public one.
 2. Add `public sealed record <Entity>CreatedEvent(...)` next to the entity.
 3. Mark the class `sealed` unless you have a specific reason not to.
@@ -395,11 +405,11 @@ conventions above are followed by convention, not test (unlike mapper/handler/va
 
 **mode=auto**
 
-1. Create `ApiEndpoints/Minimal.Domains/Features/<Feature>/Entities/<Entity>.cs` following the
+1. Create `ApiEndpoints/<YourApp>.Domains/Features/<Feature>/Entities/<Entity>.cs` following the
    attribute shape above (`[RaisesEvent]`, `[CrudCreate]`, `[CrudUpdate]`, `[CrudAction]`, `IOwnedBy`
    as needed).
 2. Build once, inspect `obj/Generated/DKNet.SlimBus.Generators/…` for request/handler names and
-   `strings …/Minimal.Domains.dll | grep Event` for composed event names.
+   `strings …/<YourApp>.Domains.dll | grep Event` for composed event names.
 3. Continue to `dknet-efcore-config` for the mapper (unchanged by this mode).
 
 ## mode=manual vs mode=auto — when to pick which
@@ -435,9 +445,9 @@ more than one aggregate, or a domain method needs the acting user's identity as
 | Adding a `createdBy`/`byUser` constructor parameter to a `[CrudCreate]` constructor | Never — it becomes a caller-settable field on the generated create request. Stamp the acting user from the authenticated caller at save time instead. |
 | Naming a `[CrudAction]` parameter `byUser` and expecting it to carry the authenticated caller | **What you might expect:** it's populated like `[FromClaim]`. **What actually happens:** it's an ordinary caller-settable body field on the generated request. **Why:** the generator forwards only the parameter list and its `DataAnnotations`; it has no concept of `[FromClaim]`. |
 | Assuming `ChangePrice`'s `[Range(0.01, double.MaxValue)]` is enforced because it's on the entity | It's forwarded onto the generated request but only *enforced* when the route is a literal `Map*(string, Delegate)` call — generated CRUD routes aren't. See `dknet-crud`. |
-| Guessing a composed `[RaisesEvent]` name from the pattern alone | Always verify with `strings ApiEndpoints/Minimal.Domains/bin/Release/net10.0/Minimal.Domains.dll \| grep Event` after building — there's no source file to read. |
+| Guessing a composed `[RaisesEvent]` name from the pattern alone | Always verify with `strings ApiEndpoints/<YourApp>.Domains/bin/Release/net10.0/<YourApp>.Domains.dll \| grep Event` after building — there's no source file to read. |
 | Expecting an `Updated` rule to fire because a setter ran | It only fires when the named property's value actually changed relative to the change tracker's original value on that save. |
-| Sealing `Product`-style logic because "the manual sample is sealed" | `sealed` is a good default but is not enforced on `Minimal.Domains` entities by any architecture test — don't cite one that doesn't exist. |
+| Sealing `Product`-style logic because "the manual sample is sealed" | `sealed` is a good default but is not enforced on `<YourApp>.Domains` entities by any architecture test — don't cite one that doesn't exist. |
 
 ---
 
@@ -462,14 +472,14 @@ the `dknet-feature-lifecycle` skill §1 to choose one and say which you chose.
 
 1. The reference sections above (mode=manual / mode=auto sections cover the exemplar shapes in full)
 2. the `dknet-efcore-config` skill
-3. `manual` exemplar — `ApiEndpoints/Minimal.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`; `auto` exemplar — `ApiEndpoints/Minimal.Domains/Features/AutomatedSample/Entities/Product.cs`
-4. `ApiEndpoints/Minimal.Infra/Features/ManualSample/Mappers/PurchaseOrderConfigs.cs` (exemplar mapper — hand-written in **both** modes; no generator produces this)
+3. `manual` exemplar — `ApiEndpoints/<YourApp>.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`; `auto` exemplar — `ApiEndpoints/<YourApp>.Domains/Features/AutomatedSample/Entities/Product.cs`
+4. `ApiEndpoints/<YourApp>.Infra/Features/ManualSample/Mappers/PurchaseOrderConfigs.cs` (exemplar mapper — hand-written in **both** modes; no generator produces this)
 
 ### Steps
 
-1. Use the `dknet-implementer` subagent (via the Agent tool) to execute Steps 1–4 of the implementer protocol: domain entity, schema constant, owned types, EF Core mapper, optional sequence/seed data, then `dotnet ef migrations add <Name> -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj` from `ApiEndpoints/`. Apply the mode=manual or mode=auto rules from the sections above verbatim — don't re-derive them.
+1. Use the `dknet-implementer` subagent (via the Agent tool) to execute Steps 1–4 of the implementer protocol: domain entity, schema constant, owned types, EF Core mapper, optional sequence/seed data, then `dotnet ef migrations add <Name> -c CoreDbContext -p <YourApp>.Infra/<YourApp>.Infra.csproj` from `ApiEndpoints/`. Apply the mode=manual or mode=auto rules from the sections above verbatim — don't re-derive them.
 2. Run `dotnet build -c Release` and stop on first error.
-3. **`auto` only** — verify composed event-record names against the built DLL (see "Events: `[RaisesEvent]`" above) before wiring a consumer: `strings ApiEndpoints/Minimal.Domains/bin/Release/net10.0/Minimal.Domains.dll | grep <Entity>`.
+3. **`auto` only** — verify composed event-record names against the built DLL (see "Events: `[RaisesEvent]`" above) before wiring a consumer: `strings ApiEndpoints/<YourApp>.Domains/bin/Release/net10.0/<YourApp>.Domains.dll | grep <Entity>`.
 4. Report:
    - mode used,
    - files created (relative paths),
@@ -479,5 +489,5 @@ the `dknet-feature-lifecycle` skill §1 to choose one and say which you chose.
 
 ### Constraints
 
-- Do NOT touch `Minimal.AppServices` or `Minimal.Api` here — those belong to `/dknet-crud` and `/dknet-endpoint`.
+- Do NOT touch `<YourApp>.AppServices` or `<YourApp>.Api` here — those belong to `/dknet-crud` and `/dknet-endpoint`.
 - Entity/mapper/event rules: see Validation checklist above — verify against it, don't restate it.

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

@@ -39,12 +39,15 @@ of the same output.
 | `auto` | `AutomatedSample` / `Product` | `[RaisesEvent]` / `[CrudCreate]` / `[CrudUpdate]` / `[CrudAction]` on the entity plus a one-line `[GenerateDto]`. Requests, handlers, and routes are generated. No idempotency, **forwarded DataAnnotations not enforced** (a FluentValidation validator on a generated request *is*), acting user via `DataOwnerHook`. |
 
 If `mode=` was not supplied, apply §1 of the lifecycle skill, **recommend one with a reason**, and ask
-the user to confirm. Default to `manual` whenever the request mentions an operation that writes more
-than one aggregate in one transaction, idempotent writes, a filtered query, a DTO that hides fields,
-or attribute-declared validation that must return `400` — `auto` is a deliberate trade, not a
-fallback. A business rule, state transition or duplicate check on its own does **not** force
-`manual`: write it as a FluentValidation validator on the generated request, the way the product
-sample refuses a duplicate name and a delete of a product still for sale.
+the user to confirm. **Default to `auto`.** Recommend `manual` only when the request actually needs
+one of the five things the generator cannot express: an operation writing more than one aggregate in
+one transaction, idempotent writes, a query beyond the generic list route's
+`filter`/`search`/`orderBy` contract, `[FromClaim]` acting-user attribution, or attribute-declared
+validation that must return `400` and cannot be restated as a FluentValidation rule. A business
+rule, state transition, duplicate check or a DTO that hides fields does **not** force `manual`:
+write the rule as a FluentValidation validator on the generated request (as the product sample
+refuses a duplicate name and a delete of a product still for sale) and narrow the DTO with
+`[GenerateDto(..., Exclude = [...])]`.
 
 When `auto` is selected, state the validation gap in your confirmation message: a `[Range]` on a
 generated request property is forwarded but never enforced, so a `POST` with an invalid value returns
@@ -74,7 +77,9 @@ Run `/dknet-entity <Feature> <Entity> mode=<mode> <props…>`. Verify in both mo
 - `dotnet build` is green.
 
 Additionally verify, by mode:
-- `manual` — mutation methods raise events via `AddEvent(...)`; a hand-written event record exists.
+- `manual` — every event is raised at the highest rung that fits: `[RaisesEvent]` where the event is
+  "created" or "these properties changed", else `AddEvent<TEvent>()` with the payload projected from
+  the entity, and a hand-built `AddEvent(new …)` only where the payload is not a projection.
 - `auto` — class-level `[RaisesEvent(...)]`, a `[CrudCreate]` constructor, and at least one
   `[CrudUpdate]` method are present. No `AddEvent` call anywhere in the slice.
 
@@ -89,24 +94,40 @@ Build green either way.
 ### Phase 4 — Endpoint
 
 Run `/dknet-endpoint <Feature> <Entity> mode=<mode>`. Verify the new `*V1Endpoint : IEndpointConfig` exists and:
-- `manual` — every route is a literal `group.MapPost/MapGet/MapPut/MapDelete(...)` call, and the create route chains `.RequiredIdempotentKey()`.
+- `manual` — every route is a literal `group.MapPost/MapGet/MapPut/MapDelete(...)` call, and the create route chains `.RequiredIdempotentKey()`. Confirm each hand-mapped route is one no CRUD attribute and no generic `Map*` helper could have covered; report any that could have been generated.
 - `auto` — the body is a single `group.Map<Entity>Crud()` call. There is no `.RequiredIdempotentKey()` on this path; do not add one, it will not compile onto the generated route.
 
+Authorization scopes, either mode: declared with `[EndpointGroupScope]` on the endpoint class where
+the package version supports it, dropping to `o.Configure(...)`/`.RequireAuthorization(...)` — each
+behind the `FeatureOptions.RequireAuthorization` guard — only for a route whose HTTP method cannot
+decide its scope.
+
 Build green.
 
 ### Phase 5 — Unit/integration tests
 
-Run `/dknet-unit-tests <Feature> <Entity> mode=<mode>`. Verify all tests pass and cover happy path, not-found, and domain events in both modes, plus by mode:
-- `manual` — FluentValidation failures, duplicate detection, and any rejected state transition.
+Run `/dknet-unit-tests <Feature> <Entity> mode=<mode>`. xUnit here covers only what a BDD scenario
+cannot: architecture/convention rules, pure functional tests (entity methods, validators, specs),
+EF model/schema shape, and a `Result`-level assertion where the HTTP response cannot tell two
+failures apart. Every business rule reachable over HTTP is Phase 6's job — do not write it twice.
+- `manual` — validator rules and rejected state transitions asserted at the unit level.
 - `auto` — entity-method behavior directly. Do **not** write a test asserting a `400` from a forwarded DataAnnotations attribute; it will return `201` and the test would encode the gap as expected behavior.
 
 ### Phase 6 — BDD acceptance tests
 
-Dispatch the `dknet-bdd-engineer` subagent with the feature scope. Verify `.feature` + step files exist with status + shape + key-field assertions and the BDD project passes.
+Dispatch the `dknet-bdd-engineer` subagent with the feature scope. **This is where the feature's
+business rules are specified** — happy path, every refusal, every state transition, and the
+domain-event side effects visible in captured logs. Verify `.feature` + step files exist with
+status + shape + key-field assertions, that every route from Phase 4 appears in at least one
+scenario, and that the BDD project passes.
 
 ### Phase 7 — Feature documentation
 
-Run `/dknet-docs <Feature>`. Verify README, architecture diagrams, data-model, and api-reference exist under `docs/features/<feature-kebab>/` (or `docs/<feature>/` if internal).
+Run `/dknet-docs <Feature>`. Verify README, architecture diagrams, data-model, and api-reference
+exist under `docs/features/<feature-kebab>/` (or `docs/<feature>/` if internal), that
+`api-reference.md` has a section for **every** route Phase 4 published, and that the architecture,
+sequence and event diagrams are archify renders committed with their JSON sources under
+`diagrams/` (Mermaid only if archify could not be installed — the report must say so).
 
 ### Phase 8 — Final gates
 
@@ -118,7 +139,7 @@ Run `/dknet-docs <Feature>`. Verify README, architecture diagrams, data-model, a
    - Migration name + tables.
    - Endpoints (route + verbs), flagging whether the create route is idempotent.
    - Test counts (unit + BDD).
-   - Docs paths.
+   - Docs paths, and whether the diagrams are archify renders or Mermaid fallbacks.
    - For `auto`: the exact generated type names produced, and a plain statement that the forwarded
      DataAnnotations validation on those routes is not enforced.
    - `/dknet-feature-remove <Feature>` as the way to retire the slice.