aw-spec-cli 0.1.4 → 0.1.6

package/assets/docs/components/QrGenerator/README.md

@@ -1,85 +0,0 @@
-# QrGenerator Component (`AppWeaver.QrGenerator`)
-
-> Pure technology (domain-agnostic). Reference sheet for the QR-code generation component.
-> To wire it into a project, follow the agent runbook in [integration.md](./integration.md).
-> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## What it is
-
-A small provider-agnostic component that turns a string into a QR-code **PNG byte array**.
-Application code depends on the `IQRGenerator` abstraction; the implementation
-(`QRCoder` library) is selected once during DI registration.
-
-**Use when:** a feature must produce a scannable QR code — patient/asset cards, share links,
-check-in tokens, downloadable QR images.
-
-## Public contract (`AppWeaver.QrGenerator`)
-
-```csharp
-namespace AppWeaver.QRGenerator;   // note: namespace is "QRGenerator" (capital R)
-
-public interface IQRGenerator
-{
-    /// <summary>Encodes the content and returns a PNG image as a byte[].</summary>
-    byte[] GenerateQR(string QRContent);
-}
-```
-
-Implementation detail (`QRCoderService`): ECC level **Q**, **20px** per module, output **PNG**.
-`null` content throws `ArgumentNullException`; an **empty string is allowed** (returns a valid
-PNG).
-
-## Packages
-
-| Package | Version | Role | Builder method | Provider key |
-|---|---|---|---|---|
-| `AppWeaver.QrGenerator` | `0.1.2` | **Required.** Abstraction + `AddQRGenerator` + facade. | — | — |
-| `AppWeaver.QrGenerator.QRCoder` | `0.1.2` | QRCoder-backed implementation. | `UseQRCoder` | `QRCoder` |
-
-> **Casing trap:** the **package IDs** use `QrGenerator` (lower `r`) but the **namespaces/types**
-> use `QRGenerator` (upper `R`). `using AppWeaver.QRGenerator;` is correct.
-
-## Registration entry point
-
-```csharp
-// In AppWeaver.QRGenerator.Extensions
-IComponentBuilder<IQRGenerator> AddQRGenerator(
-    this IServiceCollection services,
-    Action<IComponentBuilder<IQRGenerator>> configureBuilder,  // required
-    Action<QRConfiguration>? configureOptions = null,          // set Provider here
-    IConfiguration? configuration = null);                     // OR bind from config
-
-// In AppWeaver.QRGenerator.QRCoder.Extensions
-IComponentBuilder<IQRGenerator> UseQRCoder(
-    this IComponentBuilder<IQRGenerator> builder,
-    Action<QRGeneratorOptions>? options = null,   // QRGeneratorOptions is currently empty
-    IConfiguration? configuration = null);        // binds section "QRGenerator.QRCoder"
-```
-
-`QRConfiguration` exposes a single `[Required] string Provider`. The facade resolves the keyed
-provider whose key equals `Provider`.
-
-## Source map (framework)
-
-```
-framework/QrGenerator/
-  Integration.md                         ← original endpoint tutorial (reference)
-  README.md                              ← component overview
-  src/
-    AppWeaver.QrGenerator/               ← IQRGenerator, AddQRGenerator, DefaultImplementation
-    AppWeaver.QrGenerator.QRCoder/       ← UseQRCoder + QRCoderService
-  test/
-    QrGenerator.QrCoder.Tests/           ← QRCoderServiceTests (xUnit)
-```
-
-## Sample reference endpoint
-
-A ready-to-run FastEndpoint that generates a QR PNG inline (no command/handler) is bundled at
-[`ReferenceEndpoints/GenerateQrEndpoint.cs`](./ReferenceEndpoints/GenerateQrEndpoint.cs). It is
-offered (opt-in) at the end of the [integration.md](./integration.md) runbook and, if accepted,
-copied into the host project's `ReferenceEndpoints/` folder. Endpoint: `POST /reference/qr-codes`.
-
-## Related
-
-- [integration.md](./integration.md) · [[components-readme]] · [[cqrs]] ·
-  [[vertical-slices]] · [[dependency-policy]]

package/assets/docs/components/QrGenerator/ReferenceEndpoints/GenerateQrEndpoint.cs

@@ -1,57 +0,0 @@
-using FastEndpoints;
-using AppWeaver.QRGenerator;   // namespace uses QRGenerator (capital R); package id is QrGenerator
-
-// NOTE: This is a bundled SAMPLE endpoint for the AppWeaver QrGenerator component.
-// It lives under docs/ and is NOT compiled here. /aw-spec-addcomponent copies it into the
-// host project's ReferenceEndpoints/ folder and replaces the __HOSTPROJECT__ namespace token
-// with the host project's root namespace (e.g. AppWeaver.Health.Service).
-namespace __HOSTPROJECT__.ReferenceEndpoints;
-
-/// <summary>
-/// Sample reference endpoint for the AppWeaver QrGenerator component.
-///
-/// Demonstrates the full sequence inline — it injects the <see cref="IQRGenerator"/> abstraction
-/// directly, calls <c>GenerateQR</c>, and streams the PNG back as <c>image/png</c>. There is
-/// intentionally no command / command-handler / mediator: this is a copy-paste sample only.
-///
-/// Behaviour note: <c>GenerateQR(null)</c> throws <see cref="System.ArgumentNullException"/>, but an
-/// empty string is valid and returns a (small) PNG, so only <c>null</c> content is rejected here.
-/// </summary>
-public class GenerateQrEndpoint(IQRGenerator _qr) : Endpoint<GenerateQrRequest>
-{
-    public override void Configure()
-    {
-        Post("/reference/qr-codes");
-        AllowAnonymous();
-        Summary(s =>
-        {
-            s.Summary = "Generate a QR-code PNG from text content";
-            s.Description = "Reference endpoint for the AppWeaver QrGenerator component. Injects "
-                          + "IQRGenerator directly (no command/handler) and returns an image/png body.";
-        });
-        Options(o => o.WithTags("Reference - QrGenerator"));
-    }
-
-    public override async Task HandleAsync(GenerateQrRequest req, CancellationToken ct)
-    {
-        if (req.Content is null)   // null throws inside the provider; empty string is allowed
-        {
-            HttpContext.Response.StatusCode = 400;
-            await HttpContext.Response.WriteAsJsonAsync(
-                new { error = "'content' is required (an empty string is allowed)." }, ct);
-            return;
-        }
-
-        byte[] png = _qr.GenerateQR(req.Content);
-
-        HttpContext.Response.ContentType = "image/png";
-        HttpContext.Response.Headers["Content-Disposition"] = "inline; filename=qr-code.png";
-        await HttpContext.Response.Body.WriteAsync(png, ct);
-    }
-}
-
-public class GenerateQrRequest
-{
-    /// <summary>Text to encode into the QR code. Empty string is valid; null is rejected.</summary>
-    public string? Content { get; set; }
-}

package/assets/docs/components/QrGenerator/integration.md

@@ -1,230 +0,0 @@
-# QrGenerator Component — Integration Workflow (agent playbook)
-
-> Pure technology (domain-agnostic). This file is an **agent runbook**: read it top-to-bottom and
-> execute the workflow in order. It drives an interactive integration of `IQRGenerator` into a
-> project. Read [README.md](./README.md) first for the contract. Replace `<SampleProjectName>`
-> with the project name. Commands: `/aw-spec-implement`.
-
----
-
-## Agent workflow — execute in order
-
-1. **Load context.** Read [README.md](./README.md) and this file.
-2. **Resolve the host project** `<HostProject>` (see [[folder-structure]], [[components-readme]] R0.2):
-   the single startup project that owns **`Program.cs`** + the ASP.NET Core web SDK —
-   `<SampleProjectName>.Service` (Vertical Slice foundation), `<SampleProjectName>.API` (Modular
-   Monolith foundation), or another name in a future template. **Find it by locating `Program.cs`, not
-   by assuming the name.** There is **no** separate `…Application` / `…Infrastructure` project in these
-   foundations; `<HostProject>` is the target for C1–C3 below and holds the API endpoints.
-3. **Present the implementation catalog (below) as a selection list and ASK the user which
-   implementation(s) to integrate.** Use a multi-select prompt (`AskUserQuestion`,
-   `multiSelect: true`) for consistency with the other components.
-   - This component currently ships **one** implementation (`QRCoder`). If the catalog has a single
-     row, tell the user it is the only option and proceed once they confirm (do not invent others).
-4. **Apply “Common steps”** (§Common steps).
-5. **For each selected implementation, apply its block** (§Implementation blocks).
-6. **Set the provider:** `configureOptions: options => options.Provider = "<selected key>"`.
-7. **(Optional) Build the feature slice** (§Usage) — DTO + Command + Handler + Endpoint.
-8. **Offer the bundled sample endpoint (ASK).** After the wiring above, ask the user (single-select
-   yes/no via `AskUserQuestion`) whether to add the ready-made sample endpoint. If **yes**, copy it
-   into the host project — see §Sample reference endpoint. If **no**, skip silently.
-9. **Verify** (§Verification) and report what was added.
-
-> **Guardrail — namespace casing.** Package IDs use `QrGenerator` (lower `r`); **namespaces/types
-> use `QRGenerator` (upper `R`)**. `using AppWeaver.QRGenerator;` is correct — getting this wrong is
-> the most common build break.
-
----
-
-## Implementation catalog (selection list)
-
-| Key | Implementation | Best for | Package (v) | Settings |
-|---|---|---|---|---|
-| `QRCoder` | QRCoder library (PNG, ECC level Q, 20px/module) | All QR-code generation | `AppWeaver.QrGenerator.QRCoder` (0.1.2) | none (`QRGeneratorOptions` is empty) |
-
----
-
-## Common steps (apply once)
-
-### C1 — Abstraction package version
-
-**File:** `Directory.Packages.props`
-
-```xml
-<ItemGroup>
-  <!-- AppWeaver — QrGenerator (abstraction) -->
-  <PackageVersion Include="AppWeaver.QrGenerator" Version="0.1.2" />
-  <!-- + one <PackageVersion> per selected implementation — see block below -->
-</ItemGroup>
-```
-
-### C2 — Project references (no `Version=`)
-
-**File:** `src/<HostProject>/<HostProject>.csproj` (the host project resolved in step 2 — single
-project, no separate Application/Infrastructure).
-
-```xml
-<ItemGroup>
-  <PackageReference Include="AppWeaver.QrGenerator" />
-  <!-- + each selected implementation’s package — see block below -->
-</ItemGroup>
-```
-
-### C3 — Registration scaffold
-
-**File:** the host project `<HostProject>` (step 2) — register in its
-`Extensions/InfrastructureServiceRegistration.cs` (`AddInfrastructure`) when that file exists (it does
-in the Vertical Slice / Modular Monolith foundations), otherwise directly in `Program.cs` **before**
-`builder.Build()`.
-
-```csharp
-using AppWeaver.QRGenerator.Extensions;   // AddQRGenerator  (capital R)
-
-services.AddQRGenerator(
-    configureBuilder: builder =>
-    {
-        // ⬇ one Use…() call per selected implementation
-    },
-    configureOptions: options => options.Provider = "<selected key>");   // step 6
-```
-
-> **Dual local/Aspire startup ([[components-readme]] R0.2a).** If the host project also has an
-> `AddAspireInfrastructure` method (`Extensions/AspireInfrastructureExtensions.cs`) selected by
-> `if (isAspire) … else …` in `Program.cs`, add this **same** `AddQRGenerator(...)` block to **both**
-> `AddInfrastructure` and `AddAspireInfrastructure` (it is DB-agnostic — identical in both), or
-> `IQRGenerator` is unresolvable when the app runs under Aspire.
-
-No `appsettings.json` entry is required — there is nothing to configure.
-
----
-
-## Implementation blocks
-
-### QRCoder
-```xml
-<!-- Directory.Packages.props --> <PackageVersion Include="AppWeaver.QrGenerator.QRCoder" Version="0.1.2" />
-<!-- *.csproj                 --> <PackageReference Include="AppWeaver.QrGenerator.QRCoder" />
-```
-```csharp
-using AppWeaver.QRGenerator.QRCoder.Extensions;   // UseQRCoder
-// inside AddQRGenerator builder:
-builder.UseQRCoder();
-// → set options.Provider = "QRCoder" in step 6
-```
-
----
-
-## Usage (feature slice — DTO + Command + Handler + Endpoint)
-
-Generate inside an Application command handler; inject **`IQRGenerator`**. Return the image as
-base64 in a DTO so the API layer owns the response shape (see [[cqrs]], [[vertical-slices]]).
-
-**DTO** — `src/<SampleProjectName>.Application/Features/Qr/Dtos/QrCodeDto.cs`
-```csharp
-public record QrCodeDto
-{
-    public string Base64Image { get; init; } = string.Empty;
-    public string ContentType { get; init; } = "image/png";
-}
-```
-
-**Command + Handler** — `…/Features/Qr/Commands/GenerateQrCommand.cs`
-```csharp
-public record GenerateQrCommand(string Content) : ICommand<Result<QrCodeDto>>;
-
-public class GenerateQrCommandHandler(IQRGenerator _qr) // using AppWeaver.QRGenerator;
-    : ICommandHandler<GenerateQrCommand, Result<QrCodeDto>>
-{
-    public ValueTask<Result<QrCodeDto>> Handle(GenerateQrCommand req, CancellationToken ct)
-    {
-        if (string.IsNullOrWhiteSpace(req.Content))   // GenerateQR(null) throws; guard first
-            return ValueTask.FromResult(
-                Result<QrCodeDto>.Failure(new Error("qr.empty_content", "QR content is required.", 400)));
-
-        byte[] png = _qr.GenerateQR(req.Content);
-        return ValueTask.FromResult(Result<QrCodeDto>.Ok(new QrCodeDto
-        {
-            Base64Image = Convert.ToBase64String(png),
-            ContentType = "image/png"
-        }));
-    }
-}
-```
-
-**Endpoint** — `src/<SampleProjectName>.Service/Qr/Features/GenerateQr/GenerateQrEndpoint.cs`
-```csharp
-public class GenerateQrEndpoint(IMediator _mediator) : Endpoint<GenerateQrRequest>
-{
-    public override void Configure()
-    {
-        Post("/qr-codes");
-        Summary(s => s.Summary = "Generate a QR-code PNG from text content");
-        Options(o => o.WithTags("04 - QR - (FastEndpoints)"));
-    }
-
-    public override async Task HandleAsync(GenerateQrRequest req, CancellationToken ct)
-    {
-        var result = await _mediator.Send(new GenerateQrCommand(req.Content), ct);
-        if (result.IsSuccess && result.Value is not null)
-        {
-            var bytes = Convert.FromBase64String(result.Value.Base64Image);
-            HttpContext.Response.ContentType = result.Value.ContentType;        // image/png
-            HttpContext.Response.Headers["Content-Disposition"] = "attachment; filename=qr-code.png";
-            await HttpContext.Response.Body.WriteAsync(bytes, ct);
-        }
-        else
-        {
-            HttpContext.Response.StatusCode = 400;
-            await HttpContext.Response.WriteAsJsonAsync(new { error = "Failed to generate QR code" }, ct);
-        }
-    }
-}
-
-public class GenerateQrRequest { public string Content { get; set; } = string.Empty; }
-```
-
----
-
-## Sample reference endpoint
-
-The §Usage slice above routes through a command + handler. For a quick, self-contained sample there
-is also a ready-to-run FastEndpoint bundled in this component folder at
-[`ReferenceEndpoints/GenerateQrEndpoint.cs`](./ReferenceEndpoints/GenerateQrEndpoint.cs). It injects
-`IQRGenerator` directly and does the **full sequence inline** — no command/handler/mediator. It is
-**not** wired automatically; it is offered in workflow step 8.
-
-**When the user opts in (step 8) — copy procedure:**
-
-1. Confirm `docs/components/QrGenerator/ReferenceEndpoints/GenerateQrEndpoint.cs` exists. If it is
-   missing, tell the user and skip (do not hand-write a replacement).
-2. Create `src/<HostProject>/ReferenceEndpoints/` if it does not exist (`<HostProject>` = the project
-   resolved in step 2).
-3. Copy the file to `src/<HostProject>/ReferenceEndpoints/GenerateQrEndpoint.cs`, replacing the
-   namespace token `__HOSTPROJECT__` with `<HostProject>`'s root namespace (e.g.
-   `AppWeaver.Health.Service`). Keep the `using AppWeaver.QRGenerator;` (capital R) — do not "fix" it
-   to match the package id. Change nothing else.
-4. Do **not** touch the C1–C3 wiring. FastEndpoints auto-discovers the endpoint by assembly scan, so
-   no extra registration is required.
-
-**Endpoint:** `POST /reference/qr-codes` — body `{ "content" }` — returns an `image/png` body.
-An empty `content` string is valid (returns a small PNG); `null` is rejected with 400.
-
----
-
-## Verification
-
-1. **Builds** — `dotnet build` succeeds; `using` directives use `AppWeaver.QRGenerator…`; no
-   `Version=` on package references.
-2. **Startup validates** — app boots; `options.Provider` is `"QRCoder"`.
-3. **Resolves** — `IQRGenerator` resolves from DI.
-4. **Generates** — `GenerateQR("test")` returns a non-empty `byte[]`; `POST /qr-codes` returns an
-   `image/png` body that opens as a scannable QR image. (`null` content throws; empty string is
-   valid and returns a PNG.)
-5. **Sample endpoint (only if copied in step 8)** — the build still succeeds with
-   `ReferenceEndpoints/GenerateQrEndpoint.cs` added, the `__HOSTPROJECT__` token was replaced, and
-   `POST /reference/qr-codes` returns an `image/png`.
-
-## Related
-
-- [README.md](./README.md) · [[components-readme]] · [[cqrs]] · [[vertical-slices]] ·
-  [[clean-architecture]] · [[dependency-policy]]

package/assets/docs/components/README.md

@@ -1,74 +0,0 @@
-# Framework Components — Integration Catalog
-
-> Pure technology (domain-agnostic). These docs are the authoritative integration contracts for
-> opt-in AppWeaver framework components. An AI coding agent (or a human) MUST read the relevant
-> component folder **before** wiring the component into a project.
-> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-Each component is an optional NuGet-distributed building block that plugs into the standard
-AppWeaver layout (see [[folder-structure]]) via the same **provider/registry** registration
-pattern: `AddXxx(builder => builder.UseProvider(...), options => options.Provider = "Key")`.
-Your application code depends only on the component's **abstraction interface** — the concrete
-provider is a single registration decision and is swappable with zero changes to feature code.
-
-## Available components
-
-| Component | Abstraction | Folder | Use when… |
-|---|---|---|---|
-| **Email** | `IEmailService` | [Email](./Email/README.md) | Sending transactional/notification email (MsGraph, SMTP, SendGrid, OAuth2, File). |
-| **QrGenerator** | `IQRGenerator` | [QrGenerator](./QrGenerator/README.md) | Generating QR-code PNG images from text. |
-| **Jobs** | `IJobScheduler` | [Jobs](./Jobs/README.md) | Background jobs — fire-and-forget, delayed, recurring, with progress + status polling. |
-
-## How each component folder is organized
-
-Every folder contains two independent, agent-readable files:
-
-| File | Purpose | Read it to… |
-|---|---|---|
-| `README.md` | Reference — what the component is, its contract, packages, implementations, file map. | Understand the API surface and the available implementations. |
-| `integration.md` | **Agent runbook** — an ordered workflow that asks the user which implementation(s) to use, then adds the matching code. | Drive the integration interactively, end to end. |
-
-## Integration workflow (every component's `integration.md` follows this shape)
-
-1. The agent reads `README.md` + `integration.md` and locates the target projects.
-2. The agent presents the component's **implementation catalog** as a selection list and **asks the
-   user** which implementation(s) to wire — via a multi-select prompt (`AskUserQuestion`,
-   `multiSelect: true`). The user may pick more than one (e.g. a production transport + a local-dev one).
-3. The agent applies the **common steps** once, then the **per-implementation block** for each
-   selected implementation, and sets the default provider.
-4. The agent runs the **verification** checklist and reports what was added.
-
-## Cross-cutting rules (apply to every component)
-
-- **R0.1** — NuGet versions live in `Directory.Packages.props` only (`<PackageVersion>`); project
-  files reference the package **without** a `Version=` attribute (see [[dependency-policy]]).
-- **R0.2** — Register the component in the **startup/host project** — the one project that owns
-  `Program.cs` + the ASP.NET Core web SDK. Its name is template-dependent: `<App>.Service` (Vertical
-  Slice foundation), `<App>.API` (Modular Monolith foundation), and possibly other names as templates
-  are added — so **resolve it by locating `Program.cs`, never by assuming a fixed project name**.
-  These foundations have **no** separate `…Application` / `…Infrastructure` project. Put the
-  `AddXxx(...)` registration in that project's `Extensions/InfrastructureServiceRegistration.cs`
-  (`AddInfrastructure`) when that extension exists, otherwise directly in `Program.cs` before
-  `builder.Build()`. Never register in a feature slice or domain code (see [[clean-architecture]]).
-- **R0.2a** — *(dual local/Aspire startup)* Some foundations split infrastructure registration across
-  **two** methods that `Program.cs` selects at runtime — `if (isAspire) AddAspireInfrastructure(...)`
-  (the Aspire path: `Extensions/AspireInfrastructureExtensions.cs`, typically PostgreSQL + Redis)
-  `else AddInfrastructure(...)` (the local/dev path:
-  `Extensions/InfrastructureServiceRegistration.cs`, typically SQLite + in-memory cache). When
-  **both** methods exist, add the component registration to **both**, or the abstraction is
-  unresolvable in whichever run mode you skipped (e.g. `IEmailService` throws at runtime under
-  Aspire). The registration block is **identical** in both — copy it verbatim — *except*
-  provider-specific calls (connection strings, `UseSqlite(...)` vs `UseNpgsql(...)`, cache provider),
-  which must match each method's existing provider. If only `AddInfrastructure` (or only `Program.cs`)
-  exists, register once as in R0.2.
-- **R0.3** — Inject the **abstraction** (`IEmailService`, `IQRGenerator`, `IJobScheduler`) into
-  handlers — never the concrete provider type (see [[cqrs]]).
-- **R0.4** — Always set `options.Provider = "<Key>"` explicitly. Do not rely on the implicit
-  "first registered" fallback — it is order-dependent and, for Email, hardcoded.
-- **R0.5** — Secrets (client secrets, API keys, SMTP passwords, connection strings) MUST NOT be
-  committed. Use user-secrets / environment variables / key vault (see [[ai-rules]]).
-
-## Related
-
-- [[folder-structure]] · [[clean-architecture]] · [[cqrs]] · [[vertical-slices]] ·
-  [[dependency-policy]] · [[persistence]]

package/assets/docs/domain/domain-driven-design.md

@@ -1,212 +0,0 @@
-# Domain-Driven Design Standards (Tactical Patterns)
-
-> Pure technology (domain-agnostic) — generic DDD tactical patterns; the business model, canonical aggregates + invariants are in [[domain-driven-design.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-> Note: this file lives under `domain/` because DDD is a domain-modeling methodology, but the
-> rules here are domain-agnostic and reusable. The business-specific model is in the companion
-> `.domain.md`.
-
-## Ubiquitous language & bounded contexts
-
-- Use a consistent ubiquitous language across each bounded context.
-- Each bounded context = one module with `Domain / Features / Persistence / Shared`
-  (see [[modular-monolith]]).
-
-## Aggregate design
-
-- Every entity exposed to the Application layer is reached through an **Aggregate Root**.
-- Aggregate roots implement `IAggregateRoot`, `EntityBase<TId>`, and the
-  audit/soft-delete/concurrency/domain-event interfaces they need:
-  `IFullAuditedObject` or `IAuditableEntityBase`, `ISoftDeletable`, `IConcurrencyTracked`,
-  `IHasDomainEvents`, `INamedEntity<TId>` when listable.
-
-### Aggregate root responsibilities
-
-- Enforce all invariants for the aggregate.
-- Own the lifecycle of its child entities.
-- Raise domain events for state transitions.
-
-### Child entity ownership
-
-- Child entities implement `IAggregateChild` and expose `GetAggregateRoot()`.
-- They are mutated **only** through methods on the aggregate root.
-
-## Transactional / consistency boundaries
-
-- **Transaction boundary equals aggregate boundary**: a single command mutates a single
-  aggregate per transaction.
-- Cross-aggregate effects flow through **domain events** or **follow-up commands**
-  (see [[eventing]], [[cqrs]]).
-
-## Strongly typed IDs
-
-- IDs are **strongly-typed Vogen value objects** (`<Aggregate>Id` as
-  `[ValueObject<Guid>] partial struct`).
-- Raw `Guid` parameters at the Application boundary **MUST be wrapped** at the handler edge.
-
-## Value objects
-
-- Value Objects are **sealed**, have **private constructors**, **validate in the constructor**,
-  throw `DomainException` on invariant violations, and expose a `From(...)` factory.
-
-## Domain events
-
-- Derive from `DomainEventBase`, are immutable, added inside aggregate methods via
-  `AddDomainEvent(...)`, published explicitly by command handlers. See [[eventing]].
-
-## Domain services, repositories, specifications
-
-- Invariants are enforced **inside the aggregate**; validators check request shape only.
-- Repository usage is limited to `IRepository<T>` / `IReadRepository<T>` + `Specification<T>`.
-- Specification pattern: query composition lives in the Domain. See [[persistence]].
-
-## Domain exception handling
-
-- Exceptions are thrown by the Domain only (`DomainException`, `InvariantViolationException`).
-  Application code returns `Result<T>` (see [[cqrs]]).
-
-## Encapsulation, immutability, audit-awareness
-
-- **Rich domain model** — no public setters on aggregates, no business logic in handlers.
-- Soft-delete and audit behavior are first-class on protected aggregates
-  (see [[persistence]], [[auditing]]).
-
-## Anti-patterns (FORBIDDEN)
-
-- **Anemic domain models** — no public setters, no "manager/service" classes mutating
-  aggregate state from outside, no primitive-typed IDs, no business logic in handlers.
-- Cross-aggregate EF navigation properties — reference by strongly-typed ID only.
-- Cross-bounded-context interaction except via Shared DTOs / `IMediator` / anti-corruption
-  adapters.
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-Aggregate root with a strongly-typed Vogen ID, owned child collection, concurrency token,
-domain events, and an invariant enforced **inside** the aggregate:
-
-```csharp
-// <SampleProjectName>.Service/Projects/Domain/Project.cs
-[ValueObject<Guid>]
-public partial struct ProjectId { }
-
-public class Project :
-    EntityBase<ProjectId>, IAggregateRoot, IFullAuditedObject, IFieldAudited,
-    ISoftDeletable, IConcurrencyTracked, IHasDomainEvents, INamedEntity<ProjectId>
-{
-    private readonly List<ProjectTask> _tasks = new();
-
-    public string Name { get; set; } = default!;               // INamedEntity
-    public ProjectCode Code { get; private set; } = default!;   // value object
-    public ProjectStatus Status { get; private set; }
-    public TaskUserId? OwnerId { get; private set; }            // cross-aggregate ref by ID only
-    public IReadOnlyCollection<ProjectTask> Tasks => _tasks.AsReadOnly();
-
-    public byte[] RowVersion { get; set; } = Array.Empty<byte>();  // IConcurrencyTracked
-
-    private readonly List<DomainEventBase> _domainEvents = new();
-    [NotMapped] public IEnumerable<DomainEventBase> DomainEvents => _domainEvents.AsReadOnly();
-    public void ClearDomainEvents() => _domainEvents.Clear();
-
-    private Project() { }   // EF Core ctor
-
-    public Project(string code, string name, DateOnly startDate, TaskUserId? ownerId)
-    {
-        Id = ProjectId.From(Guid.NewGuid());
-        Code = ProjectCode.From(code);          // VO validates in its ctor
-        Name = ProjectTitle.From(name).Value;
-        Status = ProjectStatus.Planning;
-        OwnerId = ownerId;
-        AddDomainEvent(new ProjectCreatedEvent(Id.Value, Code.Value, Name));
-    }
-
-    // Invariant lives in the aggregate — never in the handler/validator.
-    public ProjectTask AddTask(string title, TaskPriority priority)
-    {
-        if (Status is ProjectStatus.Cancelled or ProjectStatus.Archived)
-            throw new DomainException("Cannot add tasks to a Cancelled or Archived project.");
-        var task = new ProjectTask(Id, title, priority);
-        _tasks.Add(task);
-        AddDomainEvent(new TaskCreatedEvent(Id.Value, task.Id.Value, task.Title.Value));
-        return task;
-    }
-
-    private void AddDomainEvent(DomainEventBase e) => _domainEvents.Add(e);
-}
-```
-
-Value object — sealed, private ctor, validates in the ctor, `From(...)` factory,
-throws `DomainException`:
-
-```csharp
-// <SampleProjectName>.Service/Projects/Domain/ProjectCode.cs
-public sealed class ProjectCode : IEquatable<ProjectCode>
-{
-    private static readonly Regex _valid = new(@"^[A-Z0-9][A-Z0-9\-]{1,14}$", RegexOptions.Compiled);
-    public string Value { get; private set; } = default!;
-
-    private ProjectCode() { }
-    private ProjectCode(string value)
-    {
-        if (string.IsNullOrWhiteSpace(value))
-            throw new DomainException("Project code cannot be empty.");
-        var trimmed = value.Trim().ToUpperInvariant();
-        if (!_valid.IsMatch(trimmed))
-            throw new DomainException("Project code must be uppercase alphanumeric with hyphens.");
-        Value = trimmed;
-    }
-
-    public static ProjectCode From(string value) => new(value);
-    public bool Equals(ProjectCode? o) => o is not null && Value == o.Value;
-    public override bool Equals(object? obj) => Equals(obj as ProjectCode);
-    public override int GetHashCode() => HashCode.Combine(Value);
-}
-```
-
-Child entity — implements `IAggregateChild`, exposes `GetAggregateRoot()`, has only `private`
-setters, and is mutated **only** through methods the parent aggregate calls:
-
-```csharp
-// <SampleProjectName>.Service/Projects/Domain/ProjectTask.cs
-[ValueObject<Guid>]
-public partial struct ProjectTaskId { }
-
-public class ProjectTask : EntityBase<ProjectTaskId>, IAggregateChild
-{
-    public ProjectId ProjectId { get; private set; }            // FK back to the root
-    public TaskTitle Title { get; private set; } = default!;    // value object
-    public ProjectTaskStatus Status { get; private set; }
-    public TaskUserId? AssigneeId { get; private set; }         // cross-aggregate ref by ID
-
-    public Project Project { get; private set; } = default!;    // EF-only nav, private setter
-    public object GetAggregateRoot() => Project;                // IAggregateChild
-
-    private ProjectTask() { }                                   // EF Core ctor
-    public ProjectTask(ProjectId projectId, string title, TaskPriority priority)
-    {
-        Id = ProjectTaskId.From(Guid.NewGuid());
-        ProjectId = projectId;
-        Title = TaskTitle.From(title);
-        Status = ProjectTaskStatus.Open;
-        Priority = priority;
-    }
-
-    // State-machine invariant lives on the child; the parent calls it (project.ChangeTaskStatus).
-    public void ChangeStatus(ProjectTaskStatus newStatus)
-    {
-        if (Status == ProjectTaskStatus.Cancelled)
-            throw new DomainException("A cancelled task cannot be re-opened.");
-        Status = newStatus;
-    }
-
-    public void AssignTo(TaskUserId assigneeId) => AssigneeId = assigneeId;
-}
-```
-
-> The aggregate root mutates children only through its own methods (e.g. `Project.AssignTask`
-> calls `task.AssignTo(...)` and raises the domain event) — callers never touch `ProjectTask`
-> directly. EF mapping for the owned collection is in [[persistence]].
-
-## Related
-
-- [[modular-monolith]] · [[clean-architecture]] · [[cqrs]] · [[persistence]] ·
-  [[eventing]] · [[domain-driven-design.domain]]