aw-spec-cli 0.1.0 → 0.1.2

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

@@ -0,0 +1,245 @@
+# Jobs 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 `IJobScheduler` /
+> `IJobProgress` into a project, asking the user which engine + persistence implementation(s) to
+> wire. 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. The functional engine is
+   **Quartz** — `AppWeaver.Jobs` + `AppWeaver.Jobs.Quartz` are always installed.
+2. **Locate target projects** (see [[folder-structure]]): `…Application` (job classes + handlers
+   that depend on the abstractions), `…Infrastructure` (registration + DbContext), `…Service`
+   (`appsettings.json`).
+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`). Enforce the grouping rules when reading the answer:
+   - **Group A — Scheduler store (pick exactly one; default `Quartz.InMemoryStore`).**
+   - **Group B — Status persistence (pick zero or one; recommended `EfCore.JobDatabase`).**
+   - A valid selection is one Group A item, optionally plus one Group B item
+     (e.g. `Quartz.PersistentStore` + `EfCore.DataStore`).
+4. **Apply “Common steps” once** (§Common steps) — abstraction + Quartz + base registration.
+5. **For each selected implementation, apply its block** (§Implementation blocks) — Group A tunes
+   `UseQuartzJobScheduler`; Group B chains `.UseEfCoreJobs().UseXxx(...)`.
+6. **Create the DB schema** if a Group B (or persistent Group A) implementation was selected
+   (§Schema).
+7. **Author job classes + dispatch/poll** in the feature slice (§Usage); register each job `Scoped`.
+8. **Verify** (§Verification) and report what was added.
+
+> **Guardrails.** Do **not** use `AppWeaver.Jobs.InMemory` (work-in-progress, not functional). Always
+> set `options.Provider = "Quartz"`. Long-running jobs must check `IJobProgress.CancellationToken`
+> (cancellation is cooperative). In a Quartz **persistent** store, do not rename a job class/method
+> after jobs are scheduled — names are serialized as strings; version instead (`…JobV2`).
+
+---
+
+## Implementation catalog (selection list)
+
+| Key | Group | Implementation | Best for | Extra package (v) |
+|---|---|---|---|---|
+| `Quartz.InMemoryStore` | A · Scheduler store | Quartz with in-memory store | Single instance; schedule may be lost on restart | — (Quartz only) |
+| `Quartz.PersistentStore` | A · Scheduler store | Quartz with persistent store (Postgres/SqlServer/SQLite) | Durable + multi-instance scheduling | — (Quartz only; needs DB + DDL) |
+| `EfCore.JobDatabase` | B · Status persistence | `JobStatus` in a dedicated EF Core DB | Standalone apps; status survives restart | `AppWeaver.Jobs.Persistence.EfCore` (0.1.0) |
+| `EfCore.DataStore` | B · Status persistence | `JobStatus` in the shared AppWeaver DataStore | Apps already using `AppWeaver.DataStore` | `AppWeaver.Jobs.Persistence.EfCore` (0.1.0) |
+
+> Recommended production set: **`Quartz.PersistentStore` + `EfCore.JobDatabase`** (or `EfCore.DataStore`
+> when DataStore is present). Quartz store = durable *schedule*; EF Core store = durable *status*;
+> they are independent concerns.
+
+---
+
+## Common steps (apply once, always)
+
+### C1 — Package versions
+
+**File:** `Directory.Packages.props`
+
+```xml
+<ItemGroup>
+  <!-- AppWeaver — Jobs (engine: Quartz) -->
+  <PackageVersion Include="AppWeaver.Jobs" Version="0.1.1" />
+  <PackageVersion Include="AppWeaver.Jobs.Quartz" Version="0.1.0" />
+  <!-- + AppWeaver.Jobs.Persistence.EfCore 0.1.0 if a Group B item is selected -->
+</ItemGroup>
+```
+
+### C2 — Project references (no `Version=`)
+
+**File:** `src/<SampleProjectName>.Application/<SampleProjectName>.Application.csproj`
+```xml
+<ItemGroup>
+  <PackageReference Include="AppWeaver.Jobs" />   <!-- abstractions: IJob, IJobScheduler, IJobProgress -->
+</ItemGroup>
+```
+
+**File:** `src/<SampleProjectName>.Infrastructure/<SampleProjectName>.Infrastructure.csproj`
+```xml
+<ItemGroup>
+  <PackageReference Include="AppWeaver.Jobs" />
+  <PackageReference Include="AppWeaver.Jobs.Quartz" />
+  <!-- + AppWeaver.Jobs.Persistence.EfCore if a Group B item is selected -->
+</ItemGroup>
+```
+
+### C3 — appsettings
+
+**File:** `src/<SampleProjectName>.Service/appsettings.json`
+```jsonc
+{ "AppWeaver": { "Jobs": { "Provider": "Quartz", "Quartz": { "MaxConcurrency": 10 } } } }
+```
+
+### C4 — Registration scaffold
+
+**File:** `src/<SampleProjectName>.Infrastructure/Extensions/InfrastructureServiceRegistration.cs`
+
+The selected blocks fill in the `UseQuartzJobScheduler` body (Group A) and the persistence chain
+(Group B).
+
+```csharp
+using AppWeaver.Jobs.Extensions;
+using AppWeaver.Jobs.Quartz.Extensions;
+// + using AppWeaver.Jobs.Persistence.EfCore.Extensions;  (if Group B selected)
+// + using Microsoft.EntityFrameworkCore;                 (if Group B selected)
+
+services.AddAppWeaverJobs(
+    configureBuilder: builder => builder
+        .UseQuartzJobScheduler(opts =>
+        {
+            opts.MaxConcurrency = 10;
+            // ⬇ Group A block sets opts.ConfigureQuartz (persistent) or leaves it unset (in-memory)
+        })
+        // ⬇ Group B block chains .UseEfCoreJobs().UseJobDatabase(...) or .UseAppWeaverDataStore()
+        ,
+    configureOptions: options => options.Provider = "Quartz");
+```
+
+---
+
+## Implementation blocks
+
+### A · `Quartz.InMemoryStore`
+Leave `opts.ConfigureQuartz` **unset** — Quartz uses its in-memory store automatically. No DB, no
+DDL. Schedule and pending jobs are lost on restart; single instance only.
+
+### A · `Quartz.PersistentStore`
+Set `ConfigureQuartz` inside `UseQuartzJobScheduler`:
+```csharp
+opts.ConfigureQuartz = q => q.UsePersistentStore(s =>
+{
+    s.UsePostgres(configuration.GetConnectionString("Quartz")!);  // or UseSqlServer / UseMicrosoftSQLite
+    s.UseSystemTextJsonSerializer();
+});
+```
+> Apply the official Quartz DDL to that database **before first run** (Postgres/SQL Server scripts —
+> see framework `Jobs/README.md` → *Database Setup*). Do **not** set `opts.ConnectionString` without
+> `ConfigureQuartz` — that combination throws at startup.
+
+### B · `EfCore.JobDatabase` (standalone status DB)
+Add the package (C1/C2) and chain a dedicated `JobStatusDbContext`:
+```csharp
+.UseEfCoreJobs()
+.UseJobDatabase(opts => opts.UseNpgsql(configuration.GetConnectionString("Jobs")))  // or UseSqlite("Data Source=jobs.db")
+```
+
+### B · `EfCore.DataStore` (shared AppWeaver DataStore)
+Requires `AddDataStore().UseEfCoreDataStore()` to be registered **first**. Chain:
+```csharp
+.UseEfCoreJobs()
+.UseAppWeaverDataStore()
+```
+> `UseEfCoreJobs()` alone does **not** register a data context — it must be followed by exactly one
+> of `UseJobDatabase(...)` or `UseAppWeaverDataStore()`.
+
+---
+
+## Schema (only if a Group B / persistent Group A item was selected)
+
+- **`EfCore.JobDatabase`** — scaffold + apply a `JobStatusDbContext` migration (or
+  `EnsureCreatedAsync()` for dev):
+  ```bash
+  dotnet ef migrations add InitialJobs --context JobStatusDbContext \
+    --project src/<SampleProjectName>.Infrastructure --startup-project src/<SampleProjectName>.Service
+  dotnet ef database update --context JobStatusDbContext --startup-project src/<SampleProjectName>.Service
+  ```
+- **`EfCore.DataStore`** — Shared strategy: job tables ride in the `SharedComponentDbContext`
+  migration (only `dataStore.MigrateAsync()` at runtime). Isolated strategy: run the
+  `JobStatusDbContext` migration too (see [[persistence]]).
+- **`Quartz.PersistentStore`** — apply the Quartz DDL (above).
+
+> AI MAY scaffold migrations but MUST NOT run them against shared environments (see [[ai-rules]]).
+
+---
+
+## Usage (job classes + dispatch)
+
+### Author a job — implement the `IJob` marker; inject `IJobProgress` for progress/cancel
+**File:** `src/<SampleProjectName>.Application/Jobs/ExportDataJob.cs`
+```csharp
+using AppWeaver.Jobs.Abstractions;
+
+public class ExportDataJob(IExportService _exports, IJobProgress _progress) : IJob
+{
+    public async Task RunAsync(string table, Guid requestId)
+    {
+        await _progress.ReportProgressAsync(0, "Starting export…");
+        var rows = await _exports.FetchAsync(table);
+        for (int i = 0; i < rows.Count; i++)
+        {
+            _progress.CancellationToken.ThrowIfCancellationRequested();   // cooperative cancel
+            await _exports.ProcessAsync(rows[i]);
+            await _progress.ReportProgressAsync((i + 1) * 100 / rows.Count);
+        }
+        await _progress.ReportResultUrlAsync(await _exports.UploadAsync(requestId));
+    }
+}
+```
+
+### Register every job class as `Scoped`
+**File:** `…/Extensions/InfrastructureServiceRegistration.cs`
+```csharp
+services.AddScoped<ExportDataJob>();
+```
+
+### Dispatch / poll / cancel — inject `IJobScheduler` in a handler or endpoint
+```csharp
+var jobId = await _scheduler.EnqueueAsync<ExportDataJob>(
+    j => j.RunAsync(req.Table, req.RequestId), description: $"Export {req.Table}", userId: currentUserId);
+
+await _scheduler.ScheduleAsync<SendReminderJob>(j => j.SendAsync(userId), TimeSpan.FromMinutes(30)); // delayed
+JobStatus? status = await _scheduler.GetStatusAsync(jobId);   // null = unknown/expired → 404
+await _scheduler.CancelAsync(jobId);
+```
+
+### Recurring jobs — register at startup via `IHostedService` (fire at next CRON occurrence)
+```csharp
+public class JobConfigurator(IJobScheduler _scheduler) : IHostedService
+{
+    public Task StartAsync(CancellationToken ct) =>
+        _scheduler.AddOrUpdateRecurringAsync<NightlyReportJob>(
+            "nightly-report", j => j.GenerateAsync(), "0 2 * * *");   // daily 02:00
+    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
+}
+// services.AddHostedService<JobConfigurator>();
+```
+
+---
+
+## Verification
+
+1. **Builds** — `dotnet build` succeeds; no `Version=` on references; `AppWeaver.Jobs.InMemory` absent.
+2. **Startup validates** — app boots; `Provider` is `"Quartz"`; the Quartz hosted service starts.
+3. **Schema exists** — if a persistence implementation was selected, the `JobStatus` table (and/or
+   Quartz tables) are present.
+4. **Resolves** — `IJobScheduler` resolves; each job class resolves (registered `Scoped`).
+5. **Round-trip** — enqueue → poll `GetStatusAsync` → reaches `Completed` with expected
+   `ProgressPercent`/`ResultUrl`; status is readable from the persistence store.
+6. **Cancel** — a cancellable job moves to `Cancelled` after `CancelAsync`.
+
+## Related
+
+- [README.md](./README.md) · framework `Jobs/README.md` (deep-dive) · [[components-readme]] ·
+  [[cqrs]] · [[persistence]] · [[vertical-slices]] · [[dependency-policy]] · [[ai-rules]]

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

@@ -0,0 +1,78 @@
+# 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)
+```
+
+## Related
+
+- [integration.md](./integration.md) · [[components-readme]] · [[cqrs]] ·
+  [[vertical-slices]] · [[dependency-policy]]

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

@@ -0,0 +1,185 @@
+# 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. **Locate target projects** (see [[folder-structure]]): `…Application` (injects `IQRGenerator`),
+   `…Infrastructure` (does the registration), `…Service` (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. **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/<SampleProjectName>.Application/<SampleProjectName>.Application.csproj`
+**File:** `src/<SampleProjectName>.Infrastructure/<SampleProjectName>.Infrastructure.csproj`
+
+```xml
+<ItemGroup>
+  <PackageReference Include="AppWeaver.QrGenerator" />
+  <!-- + each selected implementation’s package — see block below -->
+</ItemGroup>
+```
+
+### C3 — Registration scaffold
+
+**File:** `src/<SampleProjectName>.Infrastructure/Extensions/InfrastructureServiceRegistration.cs`
+
+```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
+```
+
+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; }
+```
+
+---
+
+## 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.)
+
+## Related
+
+- [README.md](./README.md) · [[components-readme]] · [[cqrs]] · [[vertical-slices]] ·
+  [[clean-architecture]] · [[dependency-policy]]

package/assets/docs/components/README.md

@@ -0,0 +1,57 @@
+# 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 **Infrastructure** registration extension, never in a
+  feature slice or domain code (see [[clean-architecture]]).
+- **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]]