@drunkcoding/dknet-implementation-skills 0.1.0

package/skills/dknet-queries-specs/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: dknet-queries-specs
+description: 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.
+---
+
+# Skill: Queries and Specifications
+
+Covers the read side of a feature: specifications, hand-written queries (`mode=manual`), and the
+generic list route every `[CrudCreate]`-declared entity gets automatically (`mode=auto`).
+
+## 1. Specifications — why, and the WHERE-FALSE trap
+
+Handlers never build a LINQ query against `CoreDbContext` directly. They ask `IRepositorySpec` for
+`FirstOrDefaultAsync(spec, ct)`, `AnyAsync(spec, ct)`, `Query(spec)`, or
+`ToPagedListAsync(spec, pageIndex, pageSize, ct)`, passing a `Specification<TEntity>`
+(`DKNet.EfCore.Specifications.Definitions`). A spec is a reusable, named, unit-testable filter — the
+same predicate isn't hand-rolled differently in every handler that needs it.
+
+```csharp
+internal sealed class SpecGetPurchaseOrder : Specification<PurchaseOrder>
+{
+    public SpecGetPurchaseOrder(Guid? byId = null, string? byCustomerName = null)
+    {
+        var predicator = CreatePredicate();
+
+        if (byId is not null)
+            predicator = predicator.And(a => a.Id == byId);
+
+        if (!string.IsNullOrEmpty(byCustomerName))
+            predicator = predicator.And(a => a.CustomerName == byCustomerName);
+
+        if (byId is null && string.IsNullOrEmpty(byCustomerName))
+            // An unstarted predicate builder compiles to WHERE FALSE — without this, "no filter"
+            // would silently match nothing instead of listing every order.
+            predicator = predicator.And(_ => true);
+
+        WithFilter(predicator);
+    }
+}
+```
+
+(`Minimal.AppServices/ManualSample/V1/Specs/SpecGetPurchaseOrder.cs`; the automated sample's
+`SpecGetProduct` and `SpecProductByName` follow the same shape.)
+
+- **`CreatePredicate()`** with no `.And(...)`/`.Or(...)` ever called compiles to `WHERE FALSE`. Any
+  spec whose constructor can be called with *no* filter argument at all needs an explicit
+  `.And(_ => true)` fallback in that branch, or an unfiltered "list everything" call silently returns
+  zero rows. `SpecGetProduct` hits the same trap with a plain `else` branch instead of a combined `if`
+  — same fix, either shape works.
+- **`WithFilter(predicate)`** is what actually attaches the compiled predicate to the specification;
+  building `predicator` without ever calling it is a no-op spec.
+- **Specs live in `<Feature>/V1/Specs/`, `internal sealed`** — `SpecGetPurchaseOrder`,
+  `SpecGetProduct`, `SpecProductByName` all follow this.
+- **Specs are reused outside query handlers, too.** `SpecProductByName` (`Minimal.AppServices/
+  AutomatedSample/V1/Specs/SpecProductByName.cs`) exists purely so `CreateProductRequestValidator` can
+  check for a duplicate name before create — a spec is not only a query-handler concern.
+- **Unit-test a spec without EF Core or a database**: compile `.FilterQuery!.Compile()` into a plain
+  `Func<TEntity, bool>` and assert against in-memory instances (`SpecGetPurchaseOrderTests.cs` — see
+  [Testing pointers](#5-testing-pointers)).
+
+## 2. Hand-written queries (`mode=manual`)
+
+A query is a record implementing one of two `SlimBus.Extensions.Fluents.Queries` interfaces,
+dispatched from the endpoint via `IMessageBus.Send(...)` exactly like a command.
+
+### Single result — `IWitResponse<TDto>` / `IHandler<TQuery,TDto>`
+
+```csharp
+public sealed record GetPurchaseOrderByIdQuery : Fluents.Queries.IWitResponse<PurchaseOrderDto>
+{
+    public required Guid Id { get; init; }
+}
+
+internal sealed class GetPurchaseOrderByIdQueryHandler(IRepositorySpec repository, IMapper mapper)
+    : Fluents.Queries.IHandler<GetPurchaseOrderByIdQuery, PurchaseOrderDto>
+{
+    public async Task<PurchaseOrderDto?> OnHandle(GetPurchaseOrderByIdQuery request, CancellationToken cancellationToken)
+    {
+        var order = await repository.FirstOrDefaultAsync(new SpecGetPurchaseOrder(request.Id), cancellationToken);
+        return order is null ? null : mapper.Map<PurchaseOrderDto>(order);
+    }
+}
+```
+
+`OnHandle` returns `TDto?`, not a `Result`. A `null` return is the "not found" signal — the calling
+endpoint turns it into `404` (`dto is null ? Results.NotFound() : Results.Ok(dto)`; see the
+`dknet-endpoint` skill). There is no failure channel beyond that; a query handler doesn't
+refuse with an error code the way a command handler does.
+
+### Paged list — `IWitPageResponse<TDto>` / `IPageHandler<TQuery,TDto>`
+
+```csharp
+public sealed record ListPurchaseOrdersQuery : Fluents.Queries.IWitPageResponse<PurchaseOrderDto>
+{
+    public const int DefaultPageIndex = 1;
+    public const int DefaultPageSize = 20;
+
+    // Nullable so [AsParameters] leaves these `null` (not the CLR default 0) when the caller never
+    // supplied the query parameter — distinguishing "not supplied" from an explicit pageSize=0.
+    public int? PageIndex { get; init; }
+    public int? PageSize { get; init; }
+    public string? CustomerName { get; init; }
+}
+
+internal sealed class ListPurchaseOrdersQueryValidator : AbstractValidator<ListPurchaseOrdersQuery>
+{
+    public ListPurchaseOrdersQueryValidator()
+    {
+        RuleFor(a => a.PageSize).InclusiveBetween(1, 100).When(a => a.PageSize.HasValue);
+        RuleFor(a => a.PageIndex).GreaterThan(0).When(a => a.PageIndex.HasValue);
+    }
+}
+
+internal sealed class ListPurchaseOrdersQueryHandler(IRepositorySpec repository, IMapper mapper)
+    : Fluents.Queries.IPageHandler<ListPurchaseOrdersQuery, PurchaseOrderDto>
+{
+    public async Task<IPagedList<PurchaseOrderDto>> OnHandle(ListPurchaseOrdersQuery request, CancellationToken cancellationToken)
+    {
+        var spec = new SpecGetPurchaseOrder(byCustomerName: request.CustomerName);
+        var pageIndex = request.PageIndex ?? ListPurchaseOrdersQuery.DefaultPageIndex;
+        var pageSize = request.PageSize ?? ListPurchaseOrdersQuery.DefaultPageSize;
+        var page = await repository.ToPagedListAsync(spec, pageIndex, pageSize, cancellationToken);
+        return new StaticPagedList<PurchaseOrderDto>(page.Select(mapper.Map<PurchaseOrderDto>), page);
+    }
+}
+```
+
+(`Minimal.AppServices/ManualSample/V1/Queries/GetPurchaseOrderById.cs`,
+`ListPurchaseOrders.cs`.)
+
+- **Nullable paging parameters + `[AsParameters]` + a co-located validator with `.When(x =>
+  x.PageSize.HasValue)`** is the pattern: it lets an omitted parameter fall back to the query's own
+  declared default (`DefaultPageIndex`/`DefaultPageSize`), while an explicit out-of-range value
+  (`pageSize=0`) still fails validation instead of silently falling back.
+- **`DefaultPageSize`/the `1..100` bound are this query's own choices**, unrelated to the generic list
+  route's `1000`/`DKNet:ListQuery` defaults (§3) — a hand-written query keeps whatever numbers you
+  pick regardless of the package's own configuration.
+- **`X.PagedList`'s `StaticPagedList<TDto>`** rewraps the projected DTO page so page metadata (total
+  count, page index, page size) survives the entity-to-DTO conversion — the handler pages the entity
+  query first, then projects, never the other way around.
+
+### Aggregate/summary queries over `repository.Query(spec)`
+
+Not every read is "one row" or "a page of rows". `ProductPriceSummaryQuery`
+(`Minimal.AppServices/AutomatedSample/V1/Queries/ProductPriceSummary.cs`) computes a count and an
+average directly against the queryable a spec produces:
+
+```csharp
+public sealed record ProductPriceSummaryDto(int ProductCount, decimal AveragePrice);
+public sealed record ProductPriceSummaryQuery : Fluents.Queries.IWitResponse<ProductPriceSummaryDto>;
+
+internal sealed class ProductPriceSummaryQueryHandler(IRepositorySpec repository)
+    : Fluents.Queries.IHandler<ProductPriceSummaryQuery, ProductPriceSummaryDto>
+{
+    public async Task<ProductPriceSummaryDto?> OnHandle(ProductPriceSummaryQuery request, CancellationToken cancellationToken)
+    {
+        var products = repository.Query(new SpecGetProduct());
+        var count = await products.CountAsync(cancellationToken);
+        var averagePrice = count == 0 ? 0m : await products.AverageAsync(p => p.Price, cancellationToken);
+        return new ProductPriceSummaryDto(count, averagePrice);
+    }
+}
+```
+
+`repository.Query(spec)` hands back an `IQueryable<TEntity>` with the spec's filter already applied —
+use it for `CountAsync`/`AverageAsync`/`GroupBy`/anything that isn't "one entity" or "one page of
+entities". This query has no dedicated DTO-projection step because the response isn't shaped like the
+entity at all.
+
+## 3. The generic list route (generator-driven, `mode=auto`)
+
+Every entity with `[CrudCreate]`/`[CrudUpdate]` gets a `GET /` list route for free through
+`Map{Entity}Crud()` — no handler, validator, or query object written by hand. It comes from
+`MapGetList<TEntity,TKey,TDto>()` in `DKNet.AspCore.Extensions`; you never call it directly, the
+generator emits the call.
+
+**This is a separate contract from §2 — the two don't share defaults, limits, or behavior.**
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `pageNumber` | int | `1` | `< 1` is clamped to `1`, never rejected. |
+| `pageSize` | int | `1000` | `< 1` falls back to `1000`; ceiling `1000` (host-configurable) — clamped, not rejected. |
+| `filter` | repeatable | none | `field:operation:value`, ANDed across repeats. Max 20. |
+| `search` | string | none | Free-text `Contains`, OR'd across every string DTO field. Min 2 chars. |
+| `orderBy` | string | none | One DTO field name; `Id` appended as a descending tie-break. |
+| `desc` | bool | `false` | Reverses `orderBy`. |
+| `fromDate`/`toDate` | ISO-8601 | none | Inclusive bounds on last-activity (`CreatedOn` or `UpdatedOn`); see below. |
+
+### Filter operations
+
+`Equal`, `NotEqual`, `GreaterThan`, `GreaterThanOrEqual`, `LessThan`, `LessThanOrEqual`, `Contains`,
+`NotContains`, `StartsWith`, `EndsWith`, `In`, `NotIn` (comma-separated value list), `IsNull`,
+`IsNotNull` (two-segment form, no value: `field:IsNull`). `Field` is normalized to PascalCase, matched
+case-insensitively, and only the **first two** colons split the triple — a value may itself contain
+colons (`filter=CreatedOn:GreaterThan:2026-01-31T00:00:00Z`).
+
+```
+GET /v1/products?filter=Price:GreaterThan:100&filter=IsDiscontinued:Equal:false
+```
+
+### Recent-activity window
+
+`fromDate`/`toDate` bound when a record was **last active** — either its creation or its last update
+moment falling inside the window counts. Neither bound given, over an audited entity (every
+`AggregateRoot` is): the listing covers the **last three months** by default, not all history. Naming
+either bound replaces the default entirely (open-ended on the side you left out) —
+`?fromDate=0001-01-01T00:00:00Z` is the documented way to ask for all history. `fromDate` later than
+`toDate` is a `400`. Configurable via `DKNet:ListQuery:DefaultActivityWindowMonths` (`0` disables the
+default window).
+
+### Configuring the defaults
+
+`DKNet:ListQuery` config section: `DefaultPageSize` (`1000`), `MaxPageSize` (`1000`, the ceiling an
+explicit `pageSize` clamps to and the cap on the default), `DefaultActivityWindowMonths` (`3`).
+
+### Response envelope
+
+`200 OK` with `PagedResponse<TDto>{ Items, PageCount, PageNumber, PageSize, TotalItemCount,
+HasNextPage, HasPreviousPage }`, built from `X.PagedList` via `ToPagedListAsync(...)` — `TotalItemCount`
+is always the full unpaged count.
+
+### Error behavior
+
+Everything malformed is `400`, never silently dropped or ignored: an unknown filter/order field, an
+unparseable filter triple, a value that won't coerce to the field's CLR type, more than 20 filters, a
+`search` under 2 characters, `fromDate` after `toDate`. Only paging is clamped instead of rejected.
+
+### The DTO is the boundary
+
+Filter, search, and order fields resolve against the **DTO** (`TModel`), never the raw entity — a
+deliberate security boundary. `ProductDto` excludes `OwnedBy`
+(`[GenerateDto(..., Exclude = [nameof(Product.OwnedBy), ...])]`), so `?filter=ownedBy:Equal:x` is a
+`400`, not a leak of a hidden column. Widen or narrow the query surface by changing the DTO's
+`Exclude`/`Include`, never the endpoint — see the `dknet-dto-mapping` skill for how a DTO's shape is
+declared.
+
+**Trap: a queryable DTO field must map to a real column.** Filter/search/order build EF predicates by
+property name against the *entity*. A DTO field the entity declares but does not map (`[NotMapped]`,
+or a computed property like `AuditedEntity<TKey>.LastModifiedBy`/`LastModifiedOn`) passes the "is this
+field on the DTO" check and then fails to translate — a **500**, not a `400`, and search hits it on
+the very first `?search=` call since search touches every string field. A DTO field with *no* entity
+counterpart at all (`ProductDto.GrossMargin`, hand-mapped via a Mapster `IRegister` — see the
+`dknet-dto-mapping` skill) is caught earlier and refused with a clean `400` naming the field instead.
+Either way: `Exclude` a computed/unmapped member from `[GenerateDto]` rather than let the list route
+inherit a latent failure.
+
+### Behavioral spec: `ProductList.feature`
+
+`Minimal.App.BDDTests/Features/Products/ProductList.feature` is the regression fence for this whole
+contract — it exists specifically because nothing in the slice is hand-written, so a future package
+bump could silently change behavior. Representative scenarios:
+
+- paging envelope carries the *unpaged* `totalItemCount`; `pageSize` above the max is clamped to
+  `1000`, not rejected;
+- `orderBy=price&desc=true` sorts descending; ascending is the default;
+- `filter=price:GreaterThan:20` and two ANDed filters both narrow correctly; `filter=name:In:Apple,Cherry`
+  matches any listed value;
+- `search=rico` matches `Apricot` (substring, not prefix); a one-character search is `400`;
+- `filter=colour:Equal:red` (unknown field) and `filter=ownedBy:Equal:someone` (excluded field) are
+  both `400` — the second is the DTO-boundary regression fence specifically;
+- a `fromDate` before the seeded rows still returns them; a `toDate` before them excludes all of them
+  (empty page, not `404`); `fromDate` after `toDate` is `400`;
+  `orderBy=grossMargin`/`filter=grossMargin:GreaterThan:0` are `400` naming the field, never a `500`.
+
+## 4. Status counts
+
+`group.MapGetStatusCounts<TEntity>("status", new StatusPropertyInfo(nameof(X.Status), typeof(XStatus)))`
+(`Minimal.Api/Configs/Endpoints/StatusCountsEndpointMapperExtensions.cs`) is template-local — not part
+of the published `DKNet.AspCore.Extensions` package. It groups rows by an enum-backed property using
+`ModelSpecStatusCounts<TEntity>` (`Minimal.AppServices/Share/Generics/ModelSpecGenericStatusCounts.cs`):
+
+```csharp
+public class ModelSpecStatusCounts<TEntity> : Specification<TEntity> where TEntity : DomainEntity
+{
+    public ModelSpecStatusCounts(GenericStatusCountsParameters parameters)
+    {
+        var predicate = CreatePredicate(x => true);   // seeded non-empty; no WHERE-FALSE guard needed
+        if (parameters.From is { } from) predicate = predicate.And(x => x.CreatedOn >= from);
+        if (parameters.To is { } to) predicate = predicate.And(x => x.CreatedOn <= to);
+        WithFilter(predicate);
+    }
+}
+```
+
+`StatusPropertyInfo(string Name, Type EnumType)` names the property to group by and its enum type;
+`GetStatusCounts<TEntity>` backfills every enum member with a zero count when the database has none,
+so a caller always sees the full status set. `GenericStatusCountsParameters.From`/`To` are both
+optional and **unbounded by default** — omitting both reports counts over all history, not a rolling
+window; pass explicit bounds for something like "the last 30 days". No shipped endpoint config calls
+this today; wire it into a `Map(RouteGroupBuilder)` like any other route (see the
+`dknet-endpoint` skill) if a status breakdown is useful for your entity.
+
+## 5. Decision table — generic list vs. hand-written query
+
+| Need | Use |
+|---|---|
+| Filter/sort/search only ever touches fields already on the generated DTO | Generic list route (§3) — free |
+| A filter on a field the DTO must *not* expose (ownership key, an internal flag) | Neither — exclude it from the DTO; don't build a query to reach it |
+| A join across two entities, or a projection the DTO can't express | Hand-written query (§2) |
+| Custom paging defaults/limits different from `1000`/`DKNet:ListQuery` | Hand-written query (§2) — the generic route's defaults aren't overridable per-feature |
+| An aggregate value (count, average, grouped totals) instead of a list of rows | Hand-written query over `repository.Query(spec)` (§2) |
+| The query needs the acting user (e.g. "orders I created") | Hand-written query — the generic list route has no request shape to carry a `[FromClaim]` member |
+| A field the DTO exposes only as a computed/unmapped value needs to be searchable | Neither works — searching/filtering an unmapped field 500s; add a real mapped column or drop the requirement |
+
+## 6. Testing pointers
+
+- **Spec unit tests** — compile the spec's `.FilterQuery!.Compile()` and assert against
+  hand-constructed entities, no EF Core or database involved
+  (`Minimal.App.Tests/Unit/ManualSample/SpecGetPurchaseOrderTests.cs`): a "no filter matches
+  everything" case is the WHERE-FALSE regression guard, plus one case per optional filter argument and
+  one for combining them.
+- **List/paging integration tests** — exercise the real HTTP route against `ApiFixture`
+  (`Minimal.App.Tests/Integration/ManualSample/V1/PurchaseOrderListPagingTests.cs`): the shape to copy
+  is asserting the *declared default* is served when a nullable paging parameter is omitted (not just
+  "200 OK"), and asserting an out-of-range value produces the same `ValidationProblemDetails` shape as
+  every other validation failure, not a `500`.
+- Full test-writing guidance (fixtures, `IMessageBus` test dispatch, assertion style): load the
+  `dknet-unit-tests` skill.
+
+## Common mistakes
+
+| What you might expect | What actually happens | Why |
+|---|---|---|
+| A spec with no filter argument supplied lists every row | It returns zero rows | `CreatePredicate()` with nothing ever `.And`'d compiles to `WHERE FALSE` — add an explicit `.And(_ => true)` fallback |
+| The generic list route and a hand-written list query share page-size defaults/limits | They don't — `1000`/`DKNet:ListQuery` vs. whatever the hand-written query declares (often `20`/`1..100`) | Two independent contracts; see §2 vs §3 |
+| Excluding a DTO field only hides it from JSON output | It also makes the field unqueryable through the generic list route | Filter/search/order resolve against the DTO, not the entity — this is a security boundary, not a display choice |
+| A computed DTO property (`LastModifiedBy`, a hand-mapped derived field) is safe to leave on a `[GenerateDto]` | The first `?search=` against it throws a `500` (unmapped) or a clean `400` (no entity counterpart at all) | Filter/search/order build EF predicates by property name against the entity; `Exclude` computed members |
+| Omitting `pageSize` on a hand-written list query falls back to `0` | It falls back to the query's own declared default, and an explicit `pageSize=0` still `400`s | Nullable paging properties + `[AsParameters]` + a validator gated on `.HasValue` — see §2 |
+| `fromDate`/`toDate` narrow an *unaudited* entity's listing | They're silently ignored | The recent-activity window only applies to entities carrying `CreatedOn`/`UpdatedOn` |
+| No `fromDate`/`toDate` means "all history" on the generic list route | It means "the last three months" (or whatever `DefaultActivityWindowMonths` is configured to) | The default window applies unless you explicitly widen it with `fromDate=0001-01-01T00:00:00Z` |

package/skills/dknet-scaffold/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: dknet-scaffold
+description: 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.
+---
+
+# Scaffolding a DKNet.Minimal solution
+
+This skill covers going from nothing to a green, running solution you can add business features to.
+Once you are there, `dknet-feature-lifecycle` takes over.
+
+## 1. Install and generate
+
+```bash
+dotnet nuget add source --username <GITHUB_USERNAME> --password <GITHUB_PAT_WITH_READ_PACKAGES> \
+  --store-password-in-clear-text --name github "https://nuget.pkg.github.com/baoduy/index.json"
+dotnet new install DKNet.Minimal.Template --nuget-source "https://nuget.pkg.github.com/baoduy/index.json"
+
+dotnet new dknet-minimal -n <YourApp>
+cd <YourApp>
+```
+
+`-n <YourApp>` sets the solution's root name. A dotted name works (`-n DKNet.Accounts` generates a
+solution that builds and tests green with no hand edits) — the template's `sourceName` is `Minimal`,
+and `dotnet new` rewrites that identifier to `<YourApp>` in **every** file name, folder name,
+namespace, project reference, and the text inside the shipped `AGENTS.md`. Never hand-edit a
+namespace after generating; the rename is already complete and consistent.
+
+**What does NOT get renamed:** the `ApiEndpoints/` folder itself, and any repo path that never
+contained the literal string `Minimal`. Only the project folders and files *inside* `ApiEndpoints/`
+pick up the new name — confirmed by generating: `-n DKNet.Accounts` produces
+`ApiEndpoints/DKNet.Accounts.Api/`, `ApiEndpoints/DKNet.Accounts.Domains/`, and so on, with
+`ApiEndpoints/` unchanged, and the solution file renamed to `DKNet.Accounts.sln`.
+
+### Parameters
+
+All six are optional and every one has a working default, so `-n <YourApp>` alone generates a
+solution that builds.
+
+| Parameter | Default | What it sets |
+|---|---|---|
+| `--Framework` | `net10.0` | Target framework. `net10.0` is the only offered choice. |
+| `--AuthorName` | `Steven Hoang` | `<Authors>` in `Directory.Packages.props`, inherited by every project. |
+| `--CompanyUrl` | `https://drunkcoding.net` | `<Company>` in `Directory.Packages.props`. |
+| `--RepositoryUrl` | `https://github.com/baoduy/DKNet` | `<PackageProjectUrl>`/`<RepositoryUrl>` in `Directory.Packages.props`. |
+| `--TenantId` | all-zero GUID | `Authentication:Schemes:Bearer:MetadataAddress` + `:ValidIssuer` in `appsettings.json`. |
+| `--ApiAudience` | `api://your-api` | The single entry in `Authentication:Schemes:Bearer:ValidAudiences`. |
+
+```bash
+dotnet new dknet-minimal -n <YourApp> \
+  --AuthorName "Jane Smith" --CompanyUrl "https://example.com" \
+  --RepositoryUrl "https://github.com/example/order-service" \
+  --TenantId "11111111-2222-3333-4444-555555555555" --ApiAudience "api://order-service"
+```
+
+**Replace `--TenantId` and `--ApiAudience` before enabling `FeatureManagement:RequireAuthorization`.**
+Left as shipped, the OIDC metadata fetch runs against a tenant that does not exist and every token
+is rejected on audience mismatch — see `dknet-auth-and-ownership` and `dknet-platform-config` for
+the full flag interaction. These are replace-on-generate values, not settings you can change by
+re-running the template; change them later by editing `Directory.Packages.props` (metadata) or
+`appsettings.json` (the auth pair) directly.
+
+## 2. What you get
+
+```
+<YourApp>/
+├── <YourApp>.sln                        ← the solution; dotnet build from here needs no path
+├── Directory.Packages.props             ← ALL NuGet versions, centrally managed
+├── global.json                          ← SDK pinned to net10.0
+├── coverage.runsettings
+├── AGENTS.md                            ← architecture reference, rewritten to your project names
+└── ApiEndpoints/                        ← this folder name does NOT change
+    ├── <YourApp>.Api/                   ← endpoints, auth, OpenAPI
+    ├── <YourApp>.AppServices/           ← CQRS handlers, validators, DTOs
+    ├── <YourApp>.Domains/               ← entities, aggregate roots
+    ├── <YourApp>.Infra/                 ← EF Core, repos, event publisher
+    ├── <YourApp>.Share/                 ← shared constants/options
+    ├── <YourApp>.AppHost/               ← Aspire orchestration
+    ├── <YourApp>.App.Tests/             ← xUnit + Shouldly
+    ├── <YourApp>.App.BDDTests/          ← Reqnroll + NUnit
+    └── <YourApp>.App.TestSupport/
+```
+
+**Path convention:** every other skill in this plugin writes paths relative to the solution root
+using the template's own placeholder names (`Minimal.Api`, `ApiEndpoints/Minimal.Domains/...`) —
+substitute your own `<YourApp>.*` prefix mentally when working in a generated solution.
+
+**No `.claude/`, `.github/`, or `docs/` reaches a generated solution.** Only `AGENTS.md`, the four
+solution-level files above, and `ApiEndpoints/**` are packed (`DKNet.Minimal.Template.nuspec`) —
+confirmed by generating and inspecting the output tree. Get this plugin's skills into a generated
+repo through §6 below, not through `dotnet new`.
+
+**There are no `*.sh` migration scripts** in a generated solution — the pack excludes them. Run the
+commands directly, from `ApiEndpoints/`:
+
+```bash
+cd ApiEndpoints
+dotnet ef migrations add <Name>   -c CoreDbContext -p <YourApp>.Infra/<YourApp>.Infra.csproj
+dotnet ef migrations remove       -c CoreDbContext -p <YourApp>.Infra/<YourApp>.Infra.csproj
+```
+
+## 3. Verify it is green before writing anything
+
+```bash
+dotnet build -c Release          # expect: 0 Warning(s), 0 Error(s)
+dotnet test --settings coverage.runsettings
+```
+
+Production projects run **warnings-as-errors** (`EnforceCodeStyleInBuild`, `AnalysisMode=All`). A
+new warning fails the build; that is deliberate. Test projects opt out.
+
+## 4. First run
+
+```bash
+# Full stack — Redis + PostgreSQL via Aspire. Requires Docker running.
+dotnet run --project ApiEndpoints/<YourApp>.AppHost
+
+# API only — no containers, fastest inner loop.
+dotnet run --project ApiEndpoints/<YourApp>.Api
+```
+
+The API-only path still needs a reachable database per `ConnectionStrings:AppDb`; the Aspire path
+provisions one and also seeds it with 10,000 generated `Product`/`PurchaseOrder` rows each (tune or
+disable via `SampleData:RecordsPerEntity` in the `AppHost`'s own `appsettings.json` — see
+`dknet-platform-config`). Start with the AppHost unless Docker is unavailable.
+
+Development defaults (`appsettings.Development.json`, applied when `ASPNETCORE_ENVIRONMENT=Development`,
+which `dotnet run` uses by default): `RequireAuthorization=false`, `EnableDemoAuthentication=true`
+(every request authenticates as a fixed demo identity), `EnableSwagger=true` (`/docs`),
+`RunDbMigrationWhenAppStart=true`, `EnableHttps`/`EnableRateLimit`/`EnableSecurityHeaders`/
+`EnableForwardedHeaders`/`EnableRequestBounds` all relaxed to `false`. None of this applies to a
+deployed service — the base `appsettings.json` (what Production runs with, since no
+`appsettings.Production.json` ships) keeps every security flag on. Full table in
+`dknet-platform-config`.
+
+Azure Service Bus stays off until `ConnectionStrings:AzureBus` is non-empty **and**
+`FeatureManagement:EnableServiceBus` is on — an in-memory bus handles internal handlers either way,
+so nothing extra is required for local development.
+
+## 5. The two sample features
+
+The solution ships two complete worked examples of the same feature shape, built two different
+ways. They exist to be read, then deleted:
+
+| Feature folder | Entity | Flow |
+|---|---|---|
+| `ManualSample` | `PurchaseOrder` | Hand-written — enforced DataAnnotations validation, idempotent create, `[FromClaim]` acting user |
+| `AutomatedSample` | `Product` | Generator-driven — `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]`/`[RaisesEvent]` attributes |
+
+Read `dknet-feature-lifecycle` §1 before copying either — it has the full trade-off table, including
+what the generated path gives up.
+
+**Deleting them is the expected first step** once you have read them. Do not hand-delete: each
+sample has out-of-folder touchpoints (`AutomatedSample` owns two `Produce`/`Consume` lines in
+`ServiceBusSetup.cs` plus its own scopes class; `ManualSample` owns seed data). Use the command,
+which handles those plus the drop migration:
+
+```
+/dknet-feature-remove ManualSample
+/dknet-feature-remove AutomatedSample
+```
+
+Keep one of them until your first real feature works — a correct reference in-tree is worth more
+than a tidy repo, and removal is one command whenever you want it.
+
+## 6. Installing this plugin into the generated repo
+
+The skills and workflow commands that guide feature work do not travel with `dotnet new` (§2). Add
+them to the generated repo separately, whichever tool you work in:
+
+```bash
+# Claude Code
+/plugin marketplace add baoduy/DKNet.Templates
+/plugin install dknet-minimal@dknet-marketplace
+
+# Any other agent (Codex, Cursor, Gemini CLI, ...)
+npx skills add baoduy/DKNet.Templates
+```
+
+GitHub Copilot: install through `npx skills add baoduy/DKNet.Templates -a github-copilot` (writes `.agents/skills/`, which Copilot reads) or `npm i -D @drunkcoding/dknet-implementation-skills` + `npx skills experimental_sync`
+once either directory exists in the cloned repo (e.g. after one of the two commands above has run
+in that repo, or after cloning a repo that already committed them).
+
+## 7. Where to go next
+
+| Goal | Use |
+|---|---|
+| Choose manual vs auto for a new aggregate | `dknet-feature-lifecycle` §1 |
+| Build a business feature end-to-end | `/dknet-feature <Feature> <Entity> mode=manual\|auto` |
+| Remove a feature | `/dknet-feature-remove <Feature>` |
+| Layer boundaries and auto-discovery wiring | `dknet-project-structure` |
+| Start-up order, flags, config sections, jobs, Aspire, test hosts | `dknet-platform-config` |
+| BDD scenarios | `dknet-bdd-tests`, `/dknet-bdd-tests` |
+
+## Gotchas
+
+- **Never add `Version=` to a `.csproj`.** All NuGet versions live in `Directory.Packages.props`
+  (central package management); a version attribute on a `PackageReference` fails the build.
+- **`FeatureManagement`, not `Features`,** is the config section backing `FeatureOptions`. Keys
+  match property names one-for-one, and `Get<FeatureOptions>()` ignores unknown keys — a misspelled
+  key silently no-ops instead of failing.
+- **EF Core needs no `DbSet` declarations.** `UseAutoConfigModel` + `UseAutoDataSeeding` discover
+  mappers and seeders by assembly scan. If you add seed data, wire `UseAutoDataSeeding` into **both**
+  `InfraSetup.AddInfraServices` and `InfraMigration.MigrateDb` — missing the second is a real bug
+  this template hit once, and seed rows silently never appear over HTTP.
+- **Register every new Infra service explicitly** in `InfraSetup.AddInfraServices` (one
+  `AddScoped<IService, Service>()` line) — there is no convention scan that finds it for you.
+- **`--TenantId`/`--ApiAudience` are placeholders, not working values.** Enabling
+  `RequireAuthorization` before replacing them fails every request on signature/audience mismatch,
+  not just unauthenticated ones.