@drunkcoding/dknet-implementation-skills 14.1.0 → 14.1.1

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
   "plugins": [
     {
       "name": "dknet-minimal",
-      "source": ".",
+      "source": "./plugin",
       "description": "Skills (Claude Code plugin + Agent Skills standard) and subagents for building vertical-slice features on the DKNet.Minimal.Template: endpoints, actions, queries, validation, DTO mapping, entities, seeding, SlimMessageBus/Azure Service Bus events, auth/ownership, platform flags, tests, and end-to-end /dknet-feature workflows.",
       "category": "development",
       "homepage": "https://github.com/baoduy/DKNet.Templates",

package/README.md

@@ -59,8 +59,8 @@ Every scaffold parameter, plus the run/test/migrate/pack commands:
 
 ## The shape your endpoints should take
 
-**Composite-first.** One endpoint class per aggregate: map the generated CRUD composite at the top,
-each generated route carrying its own authorization, then hand-write below it only the routes that
+**Composite-first.** One endpoint class per aggregate: declare the group's authorization scopes on the
+class, map the generated CRUD composite at the top, then hand-write below it only the routes that
 carry real orchestration. Generated and hand-written routes live in the same group — this is not a
 choice between two styles of endpoint.
 
@@ -68,29 +68,38 @@ choice between two styles of endpoint.
 trimmed here to its structure:
 
 ```csharp
-public void Map(RouteGroupBuilder group)
+[EndpointGroupScope(ProductScopes.Read, EndpointHttpMethods.Get)]
+[EndpointGroupScope(ProductScopes.Write, EndpointHttpMethods.Post, EndpointHttpMethods.Put,
+    EndpointHttpMethods.Delete)]
+internal sealed class ProductV1Endpoint : IEndpointConfig
 {
-    group.MapProductCrud(o =>
+    public void Map(RouteGroupBuilder group)
     {
-        o.Exclude("Discontinue");                                            // hand-written below
-
-        o.Configure(CrudOp.GetById, rb => rb.RequireAuthorization(ProductScopes.Read));
-        o.Configure(CrudOp.Create,  rb => rb.RequireAuthorization(ProductScopes.Write));
-        o.Configure("Approve",      rb => rb.RequireAuthorization(ProductScopes.Write));
-        // its own scope — holding products.write must not be enough to assign a supplier reference
-        o.Configure("AssignSupplierReference", rb => rb.RequireAuthorization(ProductScopes.Supplier));
-    });
-
-    // writes two aggregates in one transaction — outside what the generator can express
-    group.MapPut("{id:guid}/discontinue", /* ... */).Produces<ProductDto>();
-
-    // a response shape the generator has none for
-    group.MapGet("summary", /* ... */).Produces<ProductPriceSummaryDto>();
+        group.MapProductCrud(o =>
+        {
+            o.Exclude("Discontinue");                                        // hand-written below
+
+            // a PUT like Update, so the per-method declaration cannot separate them — holding
+            // products.write must not be enough to assign a supplier reference
+            if (requireAuthorization)
+                o.Configure("AssignSupplierReference", rb => rb.RequireAuthorization(ProductScopes.Supplier));
+        });
+
+        // writes two aggregates in one transaction — outside what the generator can express
+        group.MapPut("{id:guid}/discontinue", /* ... */).Produces<ProductDto>();
+
+        // a response shape the generator has none for; the group's GET declaration already covers it
+        group.MapGet("summary", /* ... */).Produces<ProductPriceSummaryDto>();
+    }
 }
 ```
 
-Seven of the nine routes come from `MapProductCrud`. Scopes are applied only when
-`FeatureManagement:RequireAuthorization` is on, so a stock Development run enforces none of them.
+Seven of the nine routes come from `MapProductCrud`. `[EndpointGroupScope]` names the scope per HTTP
+method once and covers generated and hand-mapped routes alike; a per-route `Configure`/
+`RequireAuthorization` is needed only where two routes share an HTTP method but not a scope. Scopes
+are applied only when `FeatureManagement:RequireAuthorization` is on, so a stock Development run
+enforces none of them — the attribute checks that flag itself, which is why the per-route overrides
+are the only calls that need an explicit guard.
 
 ### When an operation needs a hand-written route
 
@@ -160,15 +169,17 @@ capability-to-attribute tables ("I want X; which attribute or call gives it to m
 
 ## AI Plugin — Claude Code, GitHub Copilot, and any agent that reads SKILL.md
 
-This repository root is also the `dknet-minimal` plugin: `.claude-plugin/plugin.json` + `skills/` +
-`agents/` (Claude Code), `plugin.json` (GitHub Copilot), `package.json` (npm). One set of
+The `dknet-minimal` plugin lives in [`plugin/`](plugin): `plugin/.claude-plugin/plugin.json` +
+`plugin/skills/` + `plugin/agents/` (Claude Code). The repository root keeps only the entry points
+that have to be found there — `.claude-plugin/marketplace.json` (pointing at `./plugin`),
+`plugin.json` (GitHub Copilot) and `package.json` (npm). One set of
 [Agent Skills](https://agentskills.io) teaches an AI coding agent how to build on this template: the
 layer boundaries, every endpoint shape (hand-mapped, generated `Map<Entity>Crud()`, or the generic
 route helpers), actions and queries, FluentValidation + Mapster DTOs, domain entities and static
 seeding, SlimMessageBus internal events and Azure Service Bus forwarding, auth/ownership and every
 `FeatureManagement` flag. Eight of the skills are slash workflows that scaffold a vertical slice end to
 end; three Claude Code subagents (`dknet-architect`, `dknet-implementer`, `dknet-bdd-engineer`) back
-`/dknet-feature`. Index of every skill: [`skills/README.md`](skills/README.md).
+`/dknet-feature`. Index of every skill: [`plugin/skills/README.md`](plugin/skills/README.md).
 
 `dotnet new dknet-minimal` does **not** copy the plugin into a generated solution (only `AGENTS.md`
 ships) — install it into the generated repo with one of the channels below.
@@ -200,14 +211,14 @@ npx skills add baoduy/DKNet.Templates -s '*' -y  # everything, no prompts
 
 ```bash
 npm i -D @drunkcoding/dknet-implementation-skills
-claude --plugin-dir node_modules/@drunkcoding/dknet-implementation-skills   # Claude Code
+claude --plugin-dir node_modules/@drunkcoding/dknet-implementation-skills/plugin   # Claude Code
 npx skills experimental_sync -a '*'                                  # any agent: node_modules -> .agents/skills/ etc.
 ```
 
 **Working on this repository**
 
 ```bash
-claude --plugin-dir .          # loads skills/ and agents/ from the checkout
+claude --plugin-dir plugin     # loads plugin/skills/ and plugin/agents/ from the checkout
 ./validate-plugin.sh           # manifests, README install channels, skill portability
 ```
 
@@ -243,7 +254,7 @@ claude --plugin-dir .          # loads skills/ and agents/ from the checkout
 
 **Release.** Versions stay `0.0.0` in git. `publish-nuget-github.yml` computes the release version from
 tags on `main`, packs and publishes the NuGet template, creates the GitHub release, then stamps the same
-version into `package.json` / `plugin.json` / `.claude-plugin/plugin.json` (`npm version` →
+version into `package.json` / `plugin.json` / `plugin/.claude-plugin/plugin.json` (`npm version` →
 `scripts/sync-version.mjs`), validates the skills (`agentskills validate`, `claude plugin validate`,
 `npx skills add --list`, `./validate-plugin.sh`) and publishes `@drunkcoding/dknet-implementation-skills` to npm
 with OIDC trusted publishing. A version already on npm is skipped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/dknet-implementation-skills",
-  "version": "14.1.0",
+  "version": "14.1.1",
   "description": "Agent skills (Claude Code plugin + Agent Skills standard) that teach coding agents how to build features on solutions generated from DKNet.Minimal.Template. Install with `npx skills add baoduy/DKNet.Templates`.",
   "keywords": [
     "dknet",
@@ -36,8 +36,7 @@
   },
   "files": [
     ".claude-plugin/",
-    "skills/",
-    "agents/",
+    "plugin/",
     "plugin.json",
     "README.md",
     "LICENSE"

package/{.claude-plugin → plugin/.claude-plugin}/plugin.json

@@ -3,7 +3,7 @@
   "name": "dknet-minimal",
   "displayName": "DKNet Minimal Template",
   "description": "Skills and subagents that teach an agent how to build features on the DKNet.Minimal.Template (.NET 10, vertical-slice DDD/CQRS): endpoints (hand-mapped, generated CRUD, generic helpers), actions and queries, FluentValidation + Mapster DTOs, domain entities and static seeding, SlimMessageBus internal and Azure Service Bus events, auth/ownership and every platform flag — plus slash workflows that scaffold a slice end-to-end.",
-  "version": "14.1.0",
+  "version": "14.1.1",
   "author": {
     "name": "baoduy",
     "email": "baoduy2412@gmail.com",

package/{agents → plugin/agents}/dknet-architect.md

@@ -19,19 +19,19 @@ Always start by reading:
 - the `dknet-ddd-principles` skill for aggregate boundary, entity-vs-value-object, invariant, and domain-event judgment calls — apply these when deciding what the new aggregate owns and what triggers an event.
 - `CLAUDE.md` and `AGENTS.md` for current layer rules and conventions.
 - The two existing exemplar slices, and the `dknet-feature-lifecycle` skill §1 for the layer-by-layer trade-off between them:
-  - Hand-written — `Minimal.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`, `Minimal.Infra/Features/ManualSample/`, `Minimal.AppServices/ManualSample/V1/`, `Minimal.Api/ApiEndpoints/ManualSample/PurchaseOrderV1Endpoint.cs`.
-  - Generator-driven — `Minimal.Domains/Features/AutomatedSample/Entities/Product.cs` (`[RaisesEvent]`/`[CrudCreate]`/`[CrudUpdate]`), `Minimal.AppServices/AutomatedSample/V1/ProductDto.cs` (`[GenerateDto]`), `Minimal.Api/ApiEndpoints/AutomatedSample/ProductV1Endpoint.cs`.
+  - Hand-written — `<YourApp>.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`, `<YourApp>.Infra/Features/ManualSample/`, `<YourApp>.AppServices/ManualSample/V1/`, `<YourApp>.Api/ApiEndpoints/ManualSample/PurchaseOrderV1Endpoint.cs`.
+  - Generator-driven — `<YourApp>.Domains/Features/AutomatedSample/Entities/Product.cs` (`[RaisesEvent]`/`[CrudCreate]`/`[CrudUpdate]`), `<YourApp>.AppServices/AutomatedSample/V1/ProductDto.cs` (`[GenerateDto]`), `<YourApp>.Api/ApiEndpoints/AutomatedSample/ProductV1Endpoint.cs`.
 - The skill that matches the layer you're planning (the `dknet-entity` skill, `dknet-efcore-config`, `dknet-crud`, `dknet-endpoint`, `dknet-bdd-tests`, `dknet-unit-tests`).
 
 ## Output contract
 
 Produce a single markdown plan with these sections, no more no less:
 
-1. **Aggregates & owned types** — name, schema prefix for `DomainSchemas`, immutable vs. mutable fields, mutation methods, sequence usage. State explicitly which fields are entities vs. value objects and why (per `dknet-ddd-principles`), and what the aggregate's consistency boundary is. Also state up front which shape this feature should take: hand-written (`PurchaseOrder`-style — needed for idempotent writes, an operation that writes more than one aggregate in one transaction, filtered queries, or a DTO that hides fields; a rule that merely refuses an operation is a FluentValidation validator on the generated request instead) or generator-driven (`Product`-style — a genuinely plain CRUD entity whose validation is fully expressible as DataAnnotations). The `dknet-feature-lifecycle` skill §1 is the deciding reference.
+1. **Aggregates & owned types** — name, schema prefix for `DomainSchemas`, immutable vs. mutable fields, mutation methods, sequence usage. State explicitly which fields are entities vs. value objects and why (per `dknet-ddd-principles`), and what the aggregate's consistency boundary is. Also state up front which shape this feature should take. **Default to generator-driven** (`Product`-style: `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]`/`[RaisesEvent]` + `[GenerateDto]`). Propose hand-written (`PurchaseOrder`-style) only for idempotent writes, an operation that writes more than one aggregate in one transaction, a query beyond the generic list route's `filter`/`search`/`orderBy` contract, `[FromClaim]` acting-user attribution, or attribute-declared validation that must return `400`. A rule that merely refuses an operation is a FluentValidation validator on the generated request, and a DTO that hides fields is `[GenerateDto(..., Exclude = [...])]` — neither forces the hand-written shape. The `dknet-feature-lifecycle` skill §1 is the deciding reference.
 2. **EF Core mapping** — table name, indexes, max lengths, column types, owned-type registrations, seed data. Both sample shapes hand-write this layer — no generator touches `IEntityTypeConfiguration<T>`.
 3. **AppServices actions (V1)** — for the hand-written shape: for each of Create/Update/Delete, request shape, validator rules, duplicate spec, domain events emitted, lazy-mapping decision (mirror `PurchaseOrder`'s `Actions/Create.cs`/`Update.cs`/`Cancel.cs`/`Delete.cs`). For the generator-driven shape: which entity members carry `[CrudCreate]`/`[CrudUpdate]`/`[RaisesEvent]`, and the one-line `[GenerateDto(typeof(Entity))]` DTO — flag explicitly that generated-route validation is enforced only when the entity's endpoint uses literal `Map*(string, Delegate)` calls, not the generic `Map*<TRequest,TDto>` wrapper (see `Product`'s confirmed-live gap: `POST /v1/products` with a negative price returns `201`).
 4. **Query specs** — `SpecGet<Entity>` constructor parameters; expected callers. N/A for the generator-driven shape (GetById/GetList map straight to `DKNet.AspCore.Extensions`'s generic `MapGetById`/`MapGetList` — no per-entity query object exists).
-5. **Endpoint contract** — `IEndpointConfig` group path, version, mapping style (literal `group.MapPost/MapGet/MapPut/MapDelete` for hand-written, or the generated `Map<Entity>Crud()` extension for generator-driven), idempotency requirements (`.RequiredIdempotentKey()` for POST — required whenever the plan calls for idempotent writes; the generated CRUD route does not add this), auth/`RequireAuthorization` decisions.
+5. **Endpoint contract** — `IEndpointConfig` group path, version, mapping style (literal `group.MapPost/MapGet/MapPut/MapDelete` for hand-written, or the generated `Map<Entity>Crud()` extension for generator-driven), idempotency requirements (`.RequiredIdempotentKey()` for POST — required whenever the plan calls for idempotent writes; the generated CRUD route does not add this), auth decisions — name the scope per HTTP method so it can be declared with `[EndpointGroupScope]` on the endpoint class, and call out any route whose scope its HTTP method cannot decide, since that one needs a per-route `Configure`/`RequireAuthorization` behind the `FeatureOptions.RequireAuthorization` guard.
 6. **Tests** — unit test coverage targets (happy path, validation, duplicates, not-found, events) and BDD scenarios (happy, business-rule failure, validation failure) with key contract assertions (status, response shape, key fields).
 7. **Risks & open questions** — anything ambiguous; surface it here for the user to resolve before implementation begins.
 8. **Hand-off checklist** — explicit list of slash commands the implementer should run in order.

package/{agents → plugin/agents}/dknet-bdd-engineer.md

@@ -11,17 +11,17 @@ You are the DKNet BDD Engineer. You write Reqnroll + NUnit acceptance tests that
 
 1. the `dknet-bdd-tests` skill — the canonical pattern.
 2. the `dknet-bdd-tests` skill's `checklist.md` — the completion gate.
-3. `ApiEndpoints/Minimal.App.BDDTests/Support/BddApiFactory.cs` and `ApiHooks.cs` — fixture wiring you must not duplicate.
+3. `ApiEndpoints/<YourApp>.App.BDDTests/Support/BddApiFactory.cs` and `ApiHooks.cs` — fixture wiring you must not duplicate.
 4. `specs/<feature>/contracts/*` (when present) — the source of truth for assertions.
 5. `docs/features/<feature>/` (when present) — reference context for scenario wording.
 
 ## Scope (do not stray)
 
 You may touch only:
-- `ApiEndpoints/Minimal.App.BDDTests/Features/**/*.feature`
-- `ApiEndpoints/Minimal.App.BDDTests/Features/**/Steps/*.cs`
-- `ApiEndpoints/Minimal.App.BDDTests/Support/*.cs` (only when adding shared step infrastructure)
-- `ApiEndpoints/Minimal.App.BDDTests/Minimal.App.BDDTests.csproj` (only when adding a NuGet/project ref through central package management)
+- `ApiEndpoints/<YourApp>.App.BDDTests/Features/**/*.feature`
+- `ApiEndpoints/<YourApp>.App.BDDTests/Features/**/Steps/*.cs`
+- `ApiEndpoints/<YourApp>.App.BDDTests/Support/*.cs` (only when adding shared step infrastructure)
+- `ApiEndpoints/<YourApp>.App.BDDTests/<YourApp>.App.BDDTests.csproj` (only when adding a NuGet/project ref through central package management)
 
 If a test reveals a product bug, REPORT it — do not modify domain/AppServices/Api code.
 
@@ -49,7 +49,7 @@ For every API behavior, produce at minimum:
 
 After edits:
 1. `dotnet build -c Release`
-2. `dotnet test ApiEndpoints/Minimal.App.BDDTests/Minimal.App.BDDTests.csproj`
+2. `dotnet test ApiEndpoints/<YourApp>.App.BDDTests/<YourApp>.App.BDDTests.csproj`
 3. Report scenario count, pass/fail, any undefined or pending steps, and any contract gap that the spec did not cover.
 
 ## Output

package/{agents → plugin/agents}/dknet-implementer.md

@@ -24,30 +24,30 @@ Read these in order, every time:
    - the `dknet-crud` skill
    - the `dknet-endpoint` skill
 5. The exemplar slice for any layer where you're unsure — this template ships two, and the `dknet-feature-lifecycle` skill §1 is the authoritative layer-by-layer comparison between them:
-   - **Hand-written (primary walkthrough below)** — `Minimal.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`, `Minimal.Infra/Features/ManualSample/Mappers/`, `Minimal.AppServices/ManualSample/V1/Actions/`, `Specs/`, `Queries/`, `Events/`, `Minimal.Api/ApiEndpoints/ManualSample/PurchaseOrderV1Endpoint.cs`.
-   - **Generator-driven (faster path, plain CRUD only — see below)** — `Minimal.Domains/Features/AutomatedSample/Entities/Product.cs`, `Minimal.AppServices/AutomatedSample/V1/ProductDto.cs`, `Minimal.Api/ApiEndpoints/AutomatedSample/ProductV1Endpoint.cs`.
+   - **Generator-driven (the default — see "Declarative path" below)** — `<YourApp>.Domains/Features/AutomatedSample/Entities/Product.cs`, `<YourApp>.AppServices/AutomatedSample/V1/ProductDto.cs`, `<YourApp>.Api/ApiEndpoints/AutomatedSample/ProductV1Endpoint.cs`.
+   - **Hand-written (fallback, walkthrough below)** — `<YourApp>.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`, `<YourApp>.Infra/Features/ManualSample/Mappers/`, `<YourApp>.AppServices/ManualSample/V1/Actions/`, `Specs/`, `Queries/`, `Events/`, `<YourApp>.Api/ApiEndpoints/ManualSample/PurchaseOrderV1Endpoint.cs`.
 
 ## Execution order (do not skip, do not reorder)
 
-This is the hand-written path — follow it when the plan calls for idempotent writes, an operation that writes more than one aggregate in one transaction, a filtered query, or a DTO that hides fields (mirror `PurchaseOrder`). A rule that conditionally refuses an operation is not on that list: a FluentValidation validator written against a *generated* request runs on the generated route through the group-level `AddFluentValidationAutoValidation()` filter, which is how `Product` refuses a duplicate name and a delete of a product still for sale. For a genuinely plain CRUD entity with no such requirement, skip to "Declarative alternative" below instead of doing steps 5–6 by hand.
+**Start from the declarative path below; this hand-written walkthrough is the fallback.** Follow it only when the plan calls for idempotent writes, an operation that writes more than one aggregate in one transaction, a query beyond the generic list route's `filter`/`search`/`orderBy` contract, `[FromClaim]` acting-user attribution, or attribute-declared validation that must return `400`. Neither a rule that conditionally refuses an operation nor a DTO that hides fields is on that list: the first is a FluentValidation validator written against the *generated* request, which runs on the generated route through the group-level `AddFluentValidationAutoValidation()` filter (how `Product` refuses a duplicate name and a delete of a product still for sale); the second is `[GenerateDto(..., Exclude = [...])]`. Steps 1–4 are the same either way — for the declarative path, do them and then skip to "Declarative path" instead of steps 5–6.
 
 1. **Domain** — entity (`AggregateRoot`/`DomainEntity`), owned types, `DomainSchemas` constant, sequence name (if used), domain service interface (if needed). `PurchaseOrder` raises its own creation event by calling `AddEvent(new PurchaseOrderCreatedEvent(...))` directly inside the constructor — no attribute involved.
 2. **Infra mapper** — `internal sealed : DefaultEntityTypeConfiguration<T>`, `base.Configure(builder)` first, indexes, lengths, `ToTable("...", DomainSchemas.X)` (see `PurchaseOrderConfigs`).
-3. **Infra services / static seed data** — services `internal sealed` under `Minimal.Infra/Services/` and registered explicitly in `InfraSetup.AddInfraServices` (no convention scan exists); seeders `internal sealed : DataSeedingConfiguration<T>` under `Features/<X>/StaticData/` so auto-seeding picks them up (see `PurchaseOrderStaticData`). Wire `.UseAutoDataSeeding(...)` into **both** `InfraSetup.AddInfraServices` and `InfraMigration.MigrateDb` — seeding only from one of the two paths means seed rows silently never appear over HTTP (a real bug this template hit once).
-4. **EF migration** — `cd ApiEndpoints && dotnet ef migrations add <Name> -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj`. Inspect the generated migration before continuing.
+3. **Infra services / static seed data** — services `internal sealed` under `<YourApp>.Infra/Services/` and registered explicitly in `InfraSetup.AddInfraServices` (no convention scan exists); seeders `internal sealed : DataSeedingConfiguration<T>` under `Features/<X>/StaticData/` so auto-seeding picks them up (see `PurchaseOrderStaticData`). Wire `.UseAutoDataSeeding(...)` into **both** `InfraSetup.AddInfraServices` and `InfraMigration.MigrateDb` — seeding only from one of the two paths means seed rows silently never appear over HTTP (a real bug this template hit once).
+4. **EF migration** — `cd ApiEndpoints && dotnet ef migrations add <Name> -c CoreDbContext -p <YourApp>.Infra/<YourApp>.Infra.csproj`. Inspect the generated migration before continuing.
 5. **AppServices** — hand-written DTO record (no `[GenerateDto]`; see `PurchaseOrderDto` — exposes exactly the fields you write into it), `Create*Request` / `Update*Request` / `Delete*Request` (`Fluents.Requests.IWitResponse<TDto>` or `INoResponse`, `[FromClaim(ClaimTypes.Name)] ByUser` for the acting user — never trust a payload value for it), `AbstractValidator`, `internal sealed` handlers using `IRepositorySpec` + `IMapper`, `SpecGet<Entity>`, domain event record + handler.
 6. **Api endpoint** — new `*V1Endpoint : IEndpointConfig`; map every route with literal `group.MapPost/MapGet/MapPut/MapDelete(...)` calls against the raw minimal-API surface (see `PurchaseOrderV1Endpoint`). Add `.RequiredIdempotentKey()` to the POST chain — clients then send `X-Idempotency-Key: {Guid}`; a replayed key returns the original response instead of creating a duplicate.
 7. **Tests** — invoke `/dknet-unit-tests` and `/dknet-bdd-tests` (or follow the corresponding skills directly). Don't claim done until both pass.
 
-## Declarative alternative — faster path for plain CRUD (`Product`)
+## Declarative path — the default (`Product`)
 
-For a plain CRUD entity, skip steps 2–6's AppServices/Api work almost entirely (a business rule is still allowed here — write it as a FluentValidation validator against the generated request):
+Skip steps 5–6's AppServices/Api work almost entirely (a business rule is still allowed here — write it as a FluentValidation validator against the generated request):
 
-- `[RaisesEvent(EventOperations.Created, Include=[...])]` / `[RaisesEvent(EventOperations.Updated, nameof(Prop))]` at the class level instead of a hand-written event + `AddEvent(...)` call. Naming composes as `<Entity><NarrowingProps><Operation>Event` — e.g. `[RaisesEvent(EventOperations.Updated, nameof(Price))]` on `Product` generates `ProductPriceUpdatedEvent`, not `ProductUpdatedEvent`. Verify the composed name against the compiled assembly before wiring a consumer to it.
-- `[CrudCreate]` on the constructor and `[CrudUpdate]` on a mutation method — `DKNet.SlimBus.Generators` then generates the request record, handler, and route registration for you (namespace `Minimal.AppServices.Crud`, not committed — inspect `obj/Generated/DKNet.SlimBus.Generators/` after a build).
+- `[RaisesEvent(EventOperations.Created, Include=[...])]` / `[RaisesEvent(EventOperations.Updated, nameof(Prop))]` at the class level instead of a hand-written event + `AddEvent(...)` call. Where a raise needs a real condition that `[RaisesEvent]` cannot express, use `AddEvent<TEvent>()` and let `IMapper` project the payload; hand-build one with `AddEvent(new …)` only when the payload is not a projection of the entity. Naming composes as `<Entity><NarrowingProps><Operation>Event` — e.g. `[RaisesEvent(EventOperations.Updated, nameof(Price))]` on `Product` generates `ProductPriceUpdatedEvent`, not `ProductUpdatedEvent`. Verify the composed name against the compiled assembly before wiring a consumer to it.
+- `[CrudCreate]` on the constructor and `[CrudUpdate]` on a mutation method — `DKNet.SlimBus.Generators` then generates the request record, handler, and route registration for you (namespace `<YourApp>.AppServices.Crud`, not committed — inspect `obj/Generated/DKNet.SlimBus.Generators/` after a build).
 - `[GenerateDto(typeof(Entity))] public sealed partial record <Entity>Dto;` — one line — instead of a hand-written DTO. Generates every audited property by default; use `Exclude`/`Include` to narrow.
-- The endpoint becomes one `group.Map<Entity>Crud(o => …)` call instead of five hand-written `Map*` calls, with any route the generator cannot express excluded by name and hand-mapped below it (see `ProductV1Endpoint`).
-- **Validation-gap caveat — do not skip this:** 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 sees literal `Map*(string, Delegate)` calls, and the generated CRUD route goes through `DKNet.AspCore.Extensions`'s generic `MapPost<TRequest,TDto>` wrapper instead. Confirmed live: `POST /v1/products` with a negative price returns `201`, not `400`. Pick this path only when that gap is acceptable, or when you plan to enforce the rule some other way. Also: `[FromClaim]` can never reach a generated request (the generator forwards only DataAnnotations attributes), so acting-user attribution goes through `DKNet.EfCore.DataAuthorization`'s `DataOwnerHook` instead — wired once in `Minimal.Api/Configs/ServiceConfigs.cs`, not per-entity.
+- The endpoint becomes one `group.Map<Entity>Crud(o => …)` call instead of five hand-written `Map*` calls, with any route the generator cannot express excluded by name and hand-mapped below it (see `ProductV1Endpoint`). Declare authorization scopes with `[EndpointGroupScope]` on the endpoint class, one declaration per HTTP method (needs `DKNet.AspCore.Extensions` 13.0.0+, which this template pins); use `o.Configure(...)`/`.RequireAuthorization(...)` behind the `FeatureOptions.RequireAuthorization` guard only for a route whose HTTP method cannot decide its scope.
+- **Validation-gap caveat — do not skip this:** 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 sees literal `Map*(string, Delegate)` calls, and the generated CRUD route goes through `DKNet.AspCore.Extensions`'s generic `MapPost<TRequest,TDto>` wrapper instead. Confirmed live: `POST /v1/products` with a negative price returns `201`, not `400`. Pick this path only when that gap is acceptable, or when you plan to enforce the rule some other way. Also: `[FromClaim]` can never reach a generated request (the generator forwards only DataAnnotations attributes), so acting-user attribution goes through `DKNet.EfCore.DataAuthorization`'s `DataOwnerHook` instead — wired once in `<YourApp>.Api/Configs/ServiceConfigs.cs`, not per-entity.
 
 ## Build/verify gates
 

package/{skills → plugin/skills}/README.md

@@ -1,21 +1,22 @@
 # dknet-minimal skills
 
-Every folder here is one [Agent Skill](https://agentskills.io) (`<name>/SKILL.md`). The repository root is the
-`dknet-minimal` Claude Code plugin; the same files are what `npx skills add baoduy/DKNet.Templates` installs and what
-`@drunkcoding/dknet-minimal-skills` ships on npm. Start with `dknet-project-structure`.
+Every folder here is one [Agent Skill](https://agentskills.io) (`<name>/SKILL.md`). `plugin/` is the
+`dknet-minimal` Claude Code plugin (`claude --plugin-dir plugin`); the same files are what
+`npx skills add baoduy/DKNet.Templates` installs and what `@drunkcoding/dknet-minimal-skills` ships on npm.
+Start with `dknet-project-structure`.
 
 ## Workflows (invoke as a slash command with arguments)
 
 | Skill | Arguments | Purpose |
 |---|---|---|
-| `/dknet-bdd-tests` | `<Feature> e.g. Orders` | 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. |
+| `/dknet-bdd-tests` | `<Feature> e.g. Orders` | 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. |
 | `/dknet-crud` | `<Feature> <Entity> [mode=manual\|auto] [version=V1]` | Create commands (Create/Update/business transitions/Delete) at the AppServices layer for a DKNet.Minimal feature — request contracts, FluentValidation validators, and SlimMessageBus handlers, in both the hand-written and generator-driven (CrudCreate/CrudUpdate/CrudAction) shapes. Use after the domain entity and EF Core mapper exist. Queries and paged lists are the `dknet-queries-specs` skill; response DTOs and Mapster are `dknet-dto-mapping`. Invoke as `/dknet-crud <Feature> <Entity> [mode=manual\|auto] [version=V1]` to scaffold it for a feature. |
-| `/dknet-docs` | `<Feature>` | 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. |
+| `/dknet-docs` | `<Feature>` | 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. |
 | `/dknet-endpoint` | `<Feature> <Entity> [mode=manual\|auto] [routePrefix] [version=V1]` | Create Minimal API endpoint configurations using this project's IEndpointConfig pattern — raw minimal-API routes mapped by hand, a single generated Map<Entity>Crud() call, or the underlying DKNet.AspCore.Extensions generic route helpers called directly. Use after AppServices actions (or CrudCreate/CrudUpdate/CrudAction entity attributes) are ready, to expose a feature over HTTP. Invoke as `/dknet-endpoint <Feature> <Entity> [mode=manual\|auto] [routePrefix] [version=V1]` to scaffold it for a feature. |
-| `/dknet-entity` | `<Feature> <Entity> [mode=manual\|auto] [props…] e.g. Orders Order mode=manual Number:string Total:decimal` | 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. |
+| `/dknet-entity` | `<Feature> <Entity> [mode=manual\|auto] [props…] e.g. Orders Order mode=manual Number:string Total:decimal` | 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. |
 | `/dknet-feature-remove` | `<Feature> [--dry-run] e.g. Orders` | Retire a DKNet vertical-slice business feature end-to-end — deletes its folders across all six projects, cleans the out-of-folder touchpoints, and drops its tables via a new migration. |
 | `/dknet-feature` | `<Feature> <Entity> [mode=manual\|auto] [props…] e.g. Orders Order mode=manual Number:string Total:decimal` | Drive an end-to-end DKNet vertical-slice feature from plan to merged tests in either the manual or automated flow — orchestrates entity, CRUD, endpoint, tests, BDD, and docs. |
-| `/dknet-unit-tests` | `<Feature> <Entity> [mode=manual\|auto]` | Write xUnit + Shouldly tests for a DKNet.Templates feature in Minimal.App.Tests — architecture/convention rules, pure functional tests (entity methods, validators, specs, mapping), and result-level integration tests against ApiFixture + IMessageBus (handler Result failures, EF persistence, domain events). Use after AppServices actions and endpoint config are ready. Covers only what xUnit owns; HTTP request/response and event-log scenarios belong in the `dknet-bdd-tests` skill. Invoke as `/dknet-unit-tests <Feature> <Entity> [mode=manual\|auto]` to scaffold it for a feature. |
+| `/dknet-unit-tests` | `<Feature> <Entity> [mode=manual\|auto]` | Write xUnit + Shouldly tests for a DKNet.Templates feature in <YourApp>.App.Tests — architecture/convention rules, pure functional tests (entity methods, validators, specs, mapping), and result-level integration tests against ApiFixture + IMessageBus (handler Result failures, EF persistence, domain events). Use after AppServices actions and endpoint config are ready. Covers only what xUnit owns; HTTP request/response and event-log scenarios belong in the `dknet-bdd-tests` skill. Invoke as `/dknet-unit-tests <Feature> <Entity> [mode=manual\|auto]` to scaffold it for a feature. |
 
 ## Reference skills (loaded by the agent when the topic comes up)
 
@@ -23,14 +24,14 @@ Every folder here is one [Agent Skill](https://agentskills.io) (`<name>/SKILL.md
 |---|---|
 | `dknet-auth-and-ownership` | Explains authentication, per-route authorization scopes, acting-user attribution, row-level data ownership, and role-aware sensitive-data filtering in this template — including the demo authentication provider and how to write a test that runs with RequireAuthorization on. Use whenever adding a scope-guarded route, wiring acting-user attribution for a new feature, reasoning about data isolation between callers, or writing an auth-on integration test. |
 | `dknet-ddd-principles` | DDD tactical judgment for this codebase — aggregate boundaries, entity vs. value object, invariant enforcement, when to use a domain event, avoiding anemic domain models. Use before dknet-entity and dknet-crud whenever the aggregate shape or business-rule placement isn't obvious. |
-| `dknet-dto-mapping` | Design response DTOs and Mapster mapping for a DKNet.Minimal feature — hand-written vs [GenerateDto] shapes, custom Mapster IRegister mappings for values the generator's convention can't produce, LazyMapper, and the JSON/sensitive-data contract. Use after (or alongside) dknet-crud when a handler needs a DTO to return. |
+| `dknet-dto-mapping` | Design response DTOs and Mapster mapping for a DKNet.Minimal feature — [GenerateDto] first and hand-written records as the fallback, custom Mapster IRegister mappings for values the generator's convention can't produce, LazyMapper, and the JSON/sensitive-data contract. Use after (or alongside) dknet-crud when a handler needs a DTO to return. |
 | `dknet-efcore-config` | Create EF Core entity type configurations (mappers), static data seeders, CoreDbContext wiring, and infra domain-service implementations following this project's assembly-scan auto-discovery conventions. Use after creating a domain entity, for both mode=manual and mode=auto entities. |
 | `dknet-feature-lifecycle` | The add/remove lifecycle of a DKNet vertical-slice business feature — how to choose the manual vs automated flow, the exact file footprint a feature occupies across all six projects, and the out-of-folder touchpoints a delete must clean up. Use before /dknet-feature or /dknet-feature-remove, and whenever you need to enumerate or retire an existing feature. |
-| `dknet-messaging-events` | Explains how this template wires SlimMessageBus as its command/query/event backbone, how the two domain-event styles (manual AddEvent vs declared RaisesEvent) reach a subscriber, and how to forward an event to an external Azure Service Bus topic. Use whenever adding a domain event, wiring an internal or external event consumer, or reasoning about how a command/query travels from an endpoint to its handler. |
+| `dknet-messaging-events` | Explains how this template wires SlimMessageBus as its command/query/event backbone, how the three domain-event raise styles ([RaisesEvent], AddEvent<TEvent>(), AddEvent(instance)) reach a subscriber, and how to forward an event to an external Azure Service Bus topic. Use whenever adding a domain event, wiring an internal or external event consumer, or reasoning about how a command/query travels from an endpoint to its handler. |
 | `dknet-package-adoption` | Add DKNet's Core, EF Core, messaging/CQRS, or blob-storage NuGet packages to an EXISTING .NET project that was NOT created from the DKNet.Minimal.Template. Use when a consumer wants to reuse pieces of the DKNet framework in their own project layout without scaffolding a new solution. |
 | `dknet-platform-config` | Reference for everything the template wires outside a feature's own vertical slice — Program.cs start-up order, the FeatureManagement flag table, every configuration section and its defaults, launch-time jobs, the Aspire host, and the test-host overrides. Use when adding or changing a platform-level behavior (auth, rate limiting, health checks, telemetry, caching, CORS, a new flag, a new launch job) rather than a business feature. |
 | `dknet-project-structure` | Orientation to the DKNet.Minimal.Template layer boundaries, the six projects, the vertical-slice folder layout for a feature, and auto-discovery wiring. Use first, before any other dknet-* skill, when working in a solution generated from this template. |
-| `dknet-queries-specs` | Write read/query logic for a DKNet feature — Specification<T> filters, hand-written query requests/handlers dispatched over IMessageBus, and the generic filter/search/order/page list route every generator-driven CRUD slice gets for free. Use after the domain entity and DTO exist, whenever a feature needs anything more than the default GET-by-id. |
+| `dknet-queries-specs` | Write read/query logic for a DKNet feature — the generic filter/search/order/page list route every generator-driven CRUD slice gets for free, Specification<T> filters, and hand-written query requests/handlers over IMessageBus for the shapes that route cannot express. Use after the domain entity and DTO exist, whenever a feature needs anything more than the default GET-by-id. |
 | `dknet-scaffold` | Scaffold a new solution from the DKNet.Minimal template and get it running — dotnet new install/new, the six template parameters, what the generated tree looks like, first build/run with or without Aspire, deleting the two shipped sample features, and installing this skill plugin into the generated repo. Use when starting a new DKNet.Minimal solution, or when orienting inside a freshly generated one. |
 
 ## Claude Code subagents (`../agents/`)
@@ -41,7 +42,7 @@ Every folder here is one [Agent Skill](https://agentskills.io) (`<name>/SKILL.md
 
 ## Authoring
 
-Rules every skill follows (enforced by `../validate-plugin.sh`): frontmatter `name` equals the folder, a single-line
-`description` (max 1024 chars), paths relative to the consumer solution root (`ApiEndpoints/Minimal.*`, never `src/`),
+Rules every skill follows (enforced by `../../validate-plugin.sh`): frontmatter `name` equals the folder, a single-line
+`description` (max 1024 chars), paths relative to the consumer solution root (`ApiEndpoints/<YourApp>.*` where `<YourApp>` is the consumer's solution prefix — never a hard-coded `Minimal.*`, never `src/`),
 other skills referenced by name, no links into this repository's `docs/`, exemplar code inlined. This index is
 generated from the frontmatter — regenerate it after changing a skill.

package/{skills → plugin/skills}/dknet-auth-and-ownership/SKILL.md

@@ -7,7 +7,7 @@ description: Explains authentication, per-route authorization scopes, acting-use
 
 ## `FeatureManagement:RequireAuthorization`
 
-When `true`, `AddAppConfig` calls `AddAuthConfig` (`Minimal.Api/Configs/Auth/AuthConfig.cs`):
+When `true`, `AddAppConfig` calls `AddAuthConfig` (`<YourApp>.Api/Configs/Auth/AuthConfig.cs`):
 
 ```csharp
 services.AddAuthentication().AddJwtBearer();
@@ -47,7 +47,7 @@ local development and the test hosts do not exercise real JWT validation by defa
 
 ## Scopes → policies
 
-`Minimal.Api/ApiEndpoints/AutomatedSample/ProductScopes.cs` defines the scope constants for the
+`<YourApp>.Api/ApiEndpoints/AutomatedSample/ProductScopes.cs` defines the scope constants for the
 `Product` feature:
 
 ```csharp
@@ -62,46 +62,96 @@ internal static class ProductScopes
 ```
 
 `AuthConfig`'s `foreach (var scope in ProductScopes.All)` loop registers **one authorization policy
-per scope, the scope value doubling as its own policy name** — so a route calls
-`.RequireAuthorization(ProductScopes.Read)` directly, no separate policy name to remember.
+per scope, the scope value doubling as its own policy name** — so a route names
+`ProductScopes.Read` directly, with no separate policy name to remember.
 
-A route only calls `RequireAuthorization(scope)` when the flag is actually on — calling it
-unconditionally would throw at request time if `RequireAuthorization` is off, because no policies
-were registered for the app to resolve against. `ProductV1Endpoint.Map` reads the flag once via DI
-and branches on it:
+### Attach the scope with `[EndpointGroupScope]` first
+
+Prefer declaring scopes **above the `IEndpointConfig` class**, not route by route inside `Map`:
 
 ```csharp
+[EndpointGroupScope(ProductScopes.Read, EndpointHttpMethods.Get)]
+[EndpointGroupScope(ProductScopes.Write, EndpointHttpMethods.Post, EndpointHttpMethods.Put,
+    EndpointHttpMethods.Delete)]
+internal sealed class ProductV1Endpoint : IEndpointConfig
+{
+    public int Version => 1;
+    public string GroupEndpoint => "/products";
+
+    public void Map(RouteGroupBuilder group) => group.MapProductCrud();
+}
+```
+
+(`EndpointGroupScopeAttribute`/`EndpointHttpMethods` live in
+`DKNet.AspCore.Extensions.Endpoints`.)
+
+Rules, in the order they bite:
+
+- The attribute is `AllowMultiple` — stack one declaration per scope, each naming the HTTP methods
+  that need it.
+- A declaration naming **no** HTTP method is the group's default for every method it serves. A
+  declaration that names a method wins over that default for its own method.
+- It is applied **only when `EndpointRegistrationOptions.RequireAuthorization` is `true`** — the
+  same value `Program.cs` assigns from `FeatureOptions.RequireAuthorization`. That is the reason to
+  prefer it: the flag check is built in, so there is no `if (!requireAuthorization) return;` branch
+  to write and no way to forget one.
+- A route that already names its own policy, or allows anonymous access, is left alone — which is
+  what makes the per-route fallbacks below safe to mix in.
+- Once **any** declaration exists on a group, an endpoint serving a method with neither its own
+  declaration nor a group default is **refused when the group's endpoints are built**. Cover every
+  method the group serves, or declare a default.
+- Requires `DKNet.AspCore.Extensions` **13.0.0 or newer**. The shipped `ProductV1Endpoint` is
+  declared exactly this way.
+
+### Fallback, in order
+
+Drop one rung only when the rung above cannot express the rule:
+
+1. **`[EndpointGroupScope]`** — the scope is a function of the HTTP method. Covers a whole
+   generated CRUD slice in two lines.
+2. **`o.Configure(CrudOp.X, …)` / `o.Configure("RouteName", …)`** — two routes sharing one HTTP
+   method need *different* scopes, so no per-method declaration can separate them.
+   `o.Configure(CrudOp, …)` targets a generated composite route by operation kind (see
+   `dknet-endpoint`); `o.Configure("RouteName", …)` targets one `[CrudAction]` route by its C#
+   member name. `Product` needs this: `Update` and `AssignSupplierReference` are both `PUT`, and
+   the second must demand `products.supplier` rather than `products.write`.
+3. **`.RequireAuthorization(scope)` on the `RouteHandlerBuilder`** — a hand-mapped route, or a
+   generated route replaced by a hand-mapped one (`discontinue` below).
+
+Rungs 2 and 3 do **not** self-gate. Calling `RequireAuthorization(scope)` with the flag off throws
+at request time, because `AddAuthConfig` never ran and no policy of that name was registered — so
+each must sit behind a flag check. `ProductV1Endpoint` reads it once via DI, and needs it for
+exactly the two `PUT` routes the group declarations cannot separate:
+
+```csharp
+// Only for the per-route overrides below — the class-level declarations gate themselves.
 var requireAuthorization = ((IEndpointRouteBuilder)group).ServiceProvider
     .GetRequiredService<IOptions<FeatureOptions>>().Value.RequireAuthorization;
 
 group.MapProductCrud(o =>
 {
     o.Exclude("Discontinue");
-    if (!requireAuthorization) return;
-
-    o.Configure(CrudOp.GetById, rb => rb.RequireAuthorization(ProductScopes.Read));
-    o.Configure(CrudOp.GetList, rb => rb.RequireAuthorization(ProductScopes.Read));
-    o.Configure(CrudOp.Create, rb => rb.RequireAuthorization(ProductScopes.Write));
-    o.Configure(CrudOp.Update, rb => rb.RequireAuthorization(ProductScopes.Write));
-    o.Configure(CrudOp.Delete, rb => rb.RequireAuthorization(ProductScopes.Write));
-    o.Configure("Approve", rb => rb.RequireAuthorization(ProductScopes.Write));
-    // Its own scope, not Write — holding only products.write must not be enough to assign it.
-    o.Configure("AssignSupplierReference", rb => rb.RequireAuthorization(ProductScopes.Supplier));
+
+    // A PUT like Update, so no per-method declaration separates them, and products.write must not
+    // be enough to assign a supplier reference.
+    if (requireAuthorization)
+        o.Configure("AssignSupplierReference", rb => rb.RequireAuthorization(ProductScopes.Supplier));
 });
 
 var discontinue = group.MapPut("{id:guid}/discontinue", /* ... */);
 if (requireAuthorization) discontinue.RequireAuthorization(ProductScopes.Discontinue);
+
+// GET summary needs no call at all — the group's products.read declaration covers it.
+group.MapGet("summary", /* ... */);
 ```
 
-`o.Configure(CrudOp, ...)` targets a generated composite route by operation kind (see
-`dknet-endpoint`); `o.Configure("RouteName", ...)` targets a specific `[CrudAction]` route by
-its C# member name. A hand-mapped route (`discontinue` above) calls `.RequireAuthorization(scope)`
-directly on the `RouteHandlerBuilder` the same way.
+`GetById`, `GetList`, `Create`, `Update`, `Delete` and `Approve` carry no scope call: their HTTP
+method decides their scope, and the two class-level declarations already say what it is.
 
 `IEndpointConfig` also exposes an optional `string? AuthPolicy` member for gating an entire group
-under one policy (`null` means plain authentication) rather than per-route scopes — neither shipped
-sample overrides it; both use per-route `RequireAuthorization(scope)` inside `Map` instead, because
-different routes in the same group need different scopes.
+under one policy (`null` means plain authentication) rather than per-method scopes — neither shipped
+sample overrides it, because different methods in the same group need different scopes and
+`[EndpointGroupScope]` expresses that without giving up the group-level declaration.
 
 **Recipe: add a new scope for a new feature.**
 1. Add a constant (and to an `All` array, if you loop like `ProductScopes` does) in a
@@ -109,14 +159,15 @@ different routes in the same group need different scopes.
 2. Register it as a policy — either loop over your `All` array in `AuthConfig` the way
    `ProductScopes.All` is registered, or call `options.AddPolicy(YourScopes.X, ...)` explicitly for a
    one-off scope.
-3. Call `.RequireAuthorization(YourScopes.X)` on the route, gated behind the same
-   `FeatureOptions.RequireAuthorization` check `ProductV1Endpoint` uses — never call it
-   unconditionally.
+3. Attach it with `[EndpointGroupScope(YourScopes.X, EndpointHttpMethods.…)]` on the endpoint class.
+   Only where a single HTTP method needs two different scopes, fall back to `o.Configure(...)` or
+   `.RequireAuthorization(...)` — and then gate that call behind
+   `FeatureOptions.RequireAuthorization`, never call it unconditionally.
 
 ## Demo authentication
 
 `FeatureManagement:EnableDemoAuthentication` registers `DemoAuthenticationHandler`
-(`Minimal.Api/Configs/Auth/DemoAuthConfig.cs`) as the default authenticate/challenge scheme. Every
+(`<YourApp>.Api/Configs/Auth/DemoAuthConfig.cs`) as the default authenticate/challenge scheme. Every
 request is authenticated, unconditionally, as a fixed fake identity:
 
 ```csharp
@@ -156,10 +207,19 @@ if (string.IsNullOrEmpty(request.ByUser))
 — from `CreatePurchaseOrderCommandHandler`. A payload value for `ByUser` is always overwritten, never
 trusted; this is a security seam, not a binding convenience.
 
+`[FromRequestHeader("X-Header-Name")]` is the same populator reading a named request header instead
+of a claim: also overwritten before validation and the handler (with the property's default when the
+header is absent), also impossible to forge through the payload, and also inert unless
+`AddContextualRequestPopulation` is registered — it is. A missing header is never a refusal, just a
+default. **It is not an authorization signal**: a header is caller-supplied and carries no identity
+guarantee, so never use it where `[FromClaim]` belongs. Neither shipped sample uses it; reach for it
+for correlation ids, a tenant hint, or a client-version marker the handler wants without adding a
+body field.
+
 **Automated: `PrincipalProvider` + two save hooks.** A `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]`
 generated request forwards only `System.ComponentModel.DataAnnotations` attributes, so it can never
 carry `[FromClaim]`. Acting-user attribution instead goes through `PrincipalProvider`
-(`Minimal.Api/Configs/Handlers/PrincipalProvider.cs`), which implements `IPrincipalProvider`
+(`<YourApp>.Api/Configs/Handlers/PrincipalProvider.cs`), which implements `IPrincipalProvider`
 (`IDataOwnerProvider` + `ICurrentUserProvider` plus `ProfileId`/`Email`/`UserName`):
 
 ```csharp
@@ -257,7 +317,7 @@ pins the whole chain: an authenticated caller with no resolvable subject claim g
 is never persisted at all (checked with `IgnoreQueryFilters()` directly against the database, not
 just "unreadable over HTTP").
 
-**Tests that pin this area** (all in `Minimal.App.Tests/Integration/...`):
+**Tests that pin this area** (all in `<YourApp>.App.Tests/Integration/...`):
 
 - `AutomatedSample/V1/ProductOwnershipIsolationTests` — two distinct authenticated callers get
   distinct ownership keys; neither can read or list the other's row; `oid` takes precedence over
@@ -325,7 +385,7 @@ that two callers are judged independently in either request order), `ProductSens
 POST routes are not idempotent unless the route calls `.RequiredIdempotentKey()` explicitly, with
 callers sending `X-Idempotency-Key`. The store is Redis when `ConnectionStrings:Redis` is set, else
 an in-process in-memory store; both use `ConflictHandling = IdempotentConflictHandling.ConflictResponse`
-(`Minimal.Api/Configs/AppConfig.cs`). See `dknet-crud` for how a handler's `Result`
+(`<YourApp>.Api/Configs/AppConfig.cs`). See `dknet-crud` for how a handler's `Result`
 maps to a response body, and `dknet-platform-config` for CORS, security headers, and rate limiting.
 Status mapping: 400 validation, 401 no/invalid credential, 403 `OwnershipRequiredException` or a
 failed authorization policy, 404 not found or filtered out by ownership, 409 a
@@ -365,7 +425,7 @@ public sealed class AuthOnApiFixture : TestApiFactoryBase, IAsyncLifetime
 This is only safe because the test assembly disables collection parallelization — no other test's
 host can boot while the variable is set, or it would leak into an unrelated test run.
 
-`TestAuthHandler` (`Minimal.App.TestSupport/TestAuthHandler.cs`) replaces the real JWT bearer scheme
+`TestAuthHandler` (`<YourApp>.App.TestSupport/TestAuthHandler.cs`) replaces the real JWT bearer scheme
 so a request can be authenticated without a live token. It issues a fixed name/subject and a scope
 claim built from every `ProductScopes` entry by default, overridable per request via a header:
 
@@ -387,7 +447,7 @@ in the constructor, cleared in `Dispose`, `TestAuthHandler.Register(services)` i
 `ConfigureTestServices`), then assert against `TestAuthHandler.CallerName` /
 `TestAuthHandler.CallerProfileId` the same way `PurchaseOrderSecurityTests`/`ProductSecurityTests`
 do. For a test that needs two distinct callers in one host (row-isolation tests),
-`Minimal.App.TestSupport/MultiSubjectAuthHandler.cs` reads the subject from a request header instead
+`<YourApp>.App.TestSupport/MultiSubjectAuthHandler.cs` reads the subject from a request header instead
 of a fixed constant — see `AuthOnMultiSubjectApiFixture` and `ProductOwnershipIsolationTests`. For a
 caller authenticated with no name claim at all, see `AuthOnNoNameClaimApiFixture`. For a fixed-tenant
 `OwnedBy` with a still-distinct acting `CreatedBy`, see `AuthOnFixedTenantApiFixture`.
@@ -399,8 +459,12 @@ the thing under test, and it is expected to fail start-up.
 
 - **What you might expect:** calling `.RequireAuthorization(scope)` unconditionally on a route.
   **What actually happens:** with `RequireAuthorization` off, no policies were ever registered, so
-  the call throws at request time. Always gate it on `FeatureOptions.RequireAuthorization`, as
-  `ProductV1Endpoint` does.
+  the call throws at request time. Gate it on `FeatureOptions.RequireAuthorization`, as
+  `ProductV1Endpoint` does — or declare the scope with `[EndpointGroupScope]`, which is applied only
+  when that flag is on and therefore needs no branch at all.
+- **What you might expect:** one `[EndpointGroupScope]` covering the methods you care about leaves
+  the rest of the group unguarded. **What actually happens:** it fails closed — a served method with
+  no declaration and no group default makes endpoint building throw, not silently pass through.
 - **What you might expect:** giving a generated `[CrudAction]` a parameter meant to auto-populate
   from the caller. **What actually happens:** it becomes an ordinary, caller-settable bound property
   — there is no `[FromClaim]` seam on a generated request.