aw-spec-cli 0.1.2 → 0.1.3

package/assets/docs/VerticalSlice/unpack-reference-foundation.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+#
+# unpack-reference-foundation.sh — bash/macOS port of unpack-reference-foundation.ps1
+#
+# SYNOPSIS
+#   Unpack an AW-Spec reference pack file into a target project, renaming the
+#   sentinel app name to the caller's app name.
+#
+# DESCRIPTION
+#   Reads --pack-file (produced by pack-reference-foundation.sh/.ps1), takes the sentinel
+#   from its header (override with --sentinel), derives four case forms of the target app
+#   name, and writes every file block to --out-dir with the sentinel rewritten in both file
+#   CONTENTS and file/dir PATHS. Text blocks are rewritten and written as UTF-8; base64
+#   blocks are decoded as-is. Refuses to overwrite existing files unless --force.
+#
+# EXAMPLE
+#   ./unpack-reference-foundation.sh \
+#       --pack-file ./VerticalSlice.Reference.pack.txt \
+#       --target-app-name AppWeaver.Pharma \
+#       --out-dir ../../
+#
+set -euo pipefail
+
+# ------------------------------------------------------------------ defaults ---
+PACK_FILE=''
+TARGET_APP_NAME=''
+OUT_DIR='.'
+SENTINEL=''
+FORCE=0
+DRYRUN=0
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: unpack-reference-foundation.sh --pack-file <file> --target-app-name <name>
+                                      [--out-dir <dir>] [--sentinel <name>]
+                                      [--force] [--dry-run]
+
+  -p, --pack-file <file>        Reference pack file to unpack               (required)
+  -t, --target-app-name <name>  New app name to rename the sentinel into    (required)
+  -o, --out-dir <dir>           Output root                   (default: .)
+      --sentinel <name>         Override the sentinel from the pack header
+      --force                   Overwrite files that already exist
+      --dry-run                 List what would be written, write nothing
+  -h, --help                    Show this help
+
+Positional fallback: unpack-reference-foundation.sh <pack-file> <target-app-name> [out-dir]
+EOF
+}
+
+# -------------------------------------------------------------- arg parsing ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -p|--pack-file)        PACK_FILE="${2:?--pack-file needs a value}";             shift 2 ;;
+    -t|--target-app-name)  TARGET_APP_NAME="${2:?--target-app-name needs a value}"; shift 2 ;;
+    -o|--out-dir)          OUT_DIR="${2:?--out-dir needs a value}";                 shift 2 ;;
+    --sentinel)            SENTINEL="${2:?--sentinel needs a value}";               shift 2 ;;
+    --force)               FORCE=1; shift ;;
+    --dry-run)             DRYRUN=1; shift ;;
+    -h|--help)             usage; exit 0 ;;
+    --)                    shift; break ;;
+    -*)                    echo "Error: unknown option: $1" >&2; usage; exit 2 ;;
+    *)
+      if   [ -z "$PACK_FILE" ];       then PACK_FILE="$1"
+      elif [ -z "$TARGET_APP_NAME" ]; then TARGET_APP_NAME="$1"
+      else OUT_DIR="$1"
+      fi
+      shift ;;
+  esac
+done
+
+[ -n "$PACK_FILE" ]       || { echo "Error: --pack-file is required." >&2; usage; exit 2; }
+[ -n "$TARGET_APP_NAME" ] || { echo "Error: --target-app-name is required." >&2; usage; exit 2; }
+[ -f "$PACK_FILE" ]       || { echo "Error: pack file not found: $PACK_FILE" >&2; exit 1; }
+
+case "$TARGET_APP_NAME" in
+  *[!A-Za-z0-9._-]*)
+    echo "Error: --target-app-name may contain only letters, digits, '.', '_' or '-': $TARGET_APP_NAME" >&2
+    exit 2 ;;
+esac
+
+# ------------------------------------------------ sentinel from header --------
+if [ -z "$SENTINEL" ]; then
+  SENTINEL="$(LC_ALL=C sed -n 's/^#[[:space:]]*sentinel:[[:space:]]*\(.*[^[:space:]]\)[[:space:]]*$/\1/p' "$PACK_FILE" | head -n1)"
+fi
+[ -n "$SENTINEL" ] || { echo "Error: Sentinel not found in pack header; supply it with --sentinel." >&2; exit 1; }
+
+# ------------------------------------------------ derive case forms -----------
+to_lower() { printf '%s' "$1" | LC_ALL=C tr '[:upper:]' '[:lower:]'; }
+
+S_DOT="$SENTINEL";               T_DOT="$TARGET_APP_NAME"
+S_UND="${SENTINEL//./_}";        T_UND="${TARGET_APP_NAME//./_}"
+s_low="$(to_lower "$SENTINEL")"; t_low="$(to_lower "$TARGET_APP_NAME")"
+S_HYP="${s_low//./-}";           T_HYP="${t_low//./-}"
+S_LDOT="$s_low";                 T_LDOT="$t_low"
+
+FROM=(); TO=()
+add_form() {
+  local from="$1" to="$2" e
+  [ -n "$from" ] || return 0
+  [ "$from" = "$to" ] && return 0
+  if [ "${#FROM[@]}" -gt 0 ]; then
+    for e in "${FROM[@]}"; do [ "$e" = "$from" ] && return 0; done
+  fi
+  FROM+=("$from"); TO+=("$to")
+}
+add_form "$S_DOT"  "$T_DOT"
+add_form "$S_UND"  "$T_UND"
+add_form "$S_HYP"  "$T_HYP"
+add_form "$S_LDOT" "$T_LDOT"
+
+# Sort indices by FROM length descending
+ORDER=()
+{
+  local_n="${#FROM[@]}"
+  used=(); for ((k = 0; k < local_n; k++)); do used[$k]=0; done
+  for ((pass = 0; pass < local_n; pass++)); do
+    best=-1; bestlen=-1
+    for ((j = 0; j < local_n; j++)); do
+      if [ "${used[$j]}" -eq 0 ] && [ "${#FROM[$j]}" -gt "$bestlen" ]; then
+        bestlen="${#FROM[$j]}"; best="$j"
+      fi
+    done
+    used[$best]=1; ORDER+=("$best")
+  done
+}
+
+REPL_OUT=''
+apply_repl() {
+  local text="$1" idx from to
+  if [ "${#ORDER[@]}" -gt 0 ]; then
+    for idx in "${ORDER[@]}"; do
+      from="${FROM[$idx]}"; to="${TO[$idx]}"
+      text="${text//"$from"/$to}"
+    done
+  fi
+  REPL_OUT="$text"
+}
+
+# ------------------------------------------------ output root ----------------
+[ -d "$OUT_DIR" ] || mkdir -p "$OUT_DIR"
+OUT_ROOT="$(cd "$OUT_DIR" && pwd -P)"
+
+# ------------------------------------------------ base64 decoder (portable) --
+B64D=()
+if   printf 'aGk=' | base64 -d        >/dev/null 2>&1; then B64D=(base64 -d)
+elif printf 'aGk=' | base64 -D        >/dev/null 2>&1; then B64D=(base64 -D)
+elif printf 'aGk=' | base64 --decode  >/dev/null 2>&1; then B64D=(base64 --decode)
+else                                                        B64D=(openssl base64 -d -A)
+fi
+
+# ------------------------------------------------ parse file blocks ----------
+rels=(); encs=(); contents=()
+in_block=0; cur_rel=''; cur_enc=''; cur_content=''; first_line=1
+file_re='^<<<FILE path="([^"]+)"( encoding="([^"]+)")?>>>[[:space:]]*$'
+
+while IFS= read -r line || [ -n "$line" ]; do
+  line="${line%$'\r'}"
+  if [ "$in_block" -eq 0 ]; then
+    if [[ "$line" =~ $file_re ]]; then
+      cur_rel="${BASH_REMATCH[1]}"
+      cur_enc="${BASH_REMATCH[3]:-}"
+      in_block=1; first_line=1; cur_content=''
+    fi
+  else
+    if [ "$line" = '<<<ENDFILE>>>' ]; then
+      rels+=("$cur_rel"); encs+=("$cur_enc"); contents+=("$cur_content")
+      in_block=0
+    elif [ "$first_line" -eq 1 ]; then
+      cur_content="$line"; first_line=0
+    else
+      cur_content="$cur_content"$'\n'"$line"
+    fi
+  fi
+done < "$PACK_FILE"
+
+[ "${#rels[@]}" -gt 0 ] || { echo "Error: No <<<FILE>>> blocks found in pack: $PACK_FILE" >&2; exit 1; }
+
+# ------------------------------------------------ resolve destinations -------
+dests=()
+for ((i = 0; i < ${#rels[@]}; i++)); do
+  apply_repl "${rels[$i]}"
+  dests+=("$OUT_ROOT/$REPL_OUT")
+done
+
+# ------------------------------------------------ conflict guard -------------
+if [ "$FORCE" -eq 0 ] && [ "$DRYRUN" -eq 0 ]; then
+  conflicts=()
+  for d in "${dests[@]}"; do [ -e "$d" ] && conflicts+=("$d"); done
+  if [ "${#conflicts[@]}" -gt 0 ]; then
+    echo "Error: Refusing to overwrite existing files (re-run with --force):" >&2
+    printf '  %s\n' "${conflicts[@]}" >&2
+    exit 1
+  fi
+fi
+
+# ------------------------------------------------ write ----------------------
+written=0
+for ((i = 0; i < ${#rels[@]}; i++)); do
+  rel="${rels[$i]}"; enc="${encs[$i]}"; dest="${dests[$i]}"
+  if [ "$DRYRUN" -eq 1 ]; then
+    echo "WOULD WRITE  $rel  ->  $dest"
+    continue
+  fi
+  mkdir -p "$(dirname "$dest")"
+  if [ "$enc" = 'base64' ]; then
+    printf '%s' "${contents[$i]}" | tr -d '[:space:]' | "${B64D[@]}" > "$dest"
+  else
+    apply_repl "${contents[$i]}"
+    printf '%s' "$REPL_OUT" > "$dest"
+  fi
+  written=$((written + 1))
+done
+
+if [ "$DRYRUN" -eq 1 ]; then
+  echo "DryRun: ${#rels[@]} file(s) would be written to $OUT_ROOT (sentinel '$SENTINEL' -> '$TARGET_APP_NAME')."
+else
+  echo "Unpacked $written file(s) to $OUT_ROOT (sentinel '$SENTINEL' -> '$TARGET_APP_NAME')."
+fi

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

@@ -106,6 +106,13 @@ framework/Messaging.Email/
     TestApp/Program.cs                   ← OAuth2 + File multi-provider sample
 ```
 
+## Sample reference endpoint
+
+A ready-to-run FastEndpoint that sends mail inline (no command/handler) is bundled at
+[`ReferenceEndpoints/SendEmailEndpoint.cs`](./ReferenceEndpoints/SendEmailEndpoint.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/email/send`.
+
 ## Related
 
 - [integration.md](./integration.md) · [[components-readme]] · [[cqrs]] ·

package/assets/docs/components/Email/ReferenceEndpoints/SendEmailEndpoint.cs

@@ -0,0 +1,84 @@
+using FastEndpoints;
+using Microsoft.Extensions.Configuration;
+using AppWeaver.Messaging.Email;
+
+// NOTE: This is a bundled SAMPLE endpoint for the AppWeaver Email 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 Email component.
+///
+/// Demonstrates the full send sequence inline — it injects the <see cref="IEmailService"/>
+/// abstraction directly and calls <c>SendAsync</c> with the provider wired during DI
+/// registration (see the component's integration runbook). There is intentionally no
+/// command / command-handler / mediator: this is a copy-paste sample only.
+///
+/// The active transport is whatever <c>options.Provider</c> was set to when
+/// <c>AddEmailMessaging(...)</c> was registered. With the <c>File</c> provider the message is
+/// written to <c>Emails_&lt;yyyy-MM-dd&gt;.txt</c> in the application base directory.
+/// </summary>
+public class SendEmailEndpoint(IEmailService _email, IConfiguration _config)
+    : Endpoint<SendEmailRequest>
+{
+    public override void Configure()
+    {
+        Post("/reference/email/send");
+        AllowAnonymous();
+        Summary(s =>
+        {
+            s.Summary = "Send a sample email via the configured Email provider";
+            s.Description = "Reference endpoint for the AppWeaver Email component. Injects "
+                          + "IEmailService directly (no command/handler). 'from' falls back to "
+                          + "Messaging:Email:DefaultFrom when omitted.";
+        });
+        Options(o => o.WithTags("Reference - Email"));
+    }
+
+    public override async Task HandleAsync(SendEmailRequest req, CancellationToken ct)
+    {
+        if (string.IsNullOrWhiteSpace(req.To) || string.IsNullOrWhiteSpace(req.Subject))
+        {
+            HttpContext.Response.StatusCode = 400;
+            await HttpContext.Response.WriteAsJsonAsync(
+                new { error = "'to' and 'subject' are required." }, ct);
+            return;
+        }
+
+        // 'from' is optional in the request — fall back to the configured DefaultFrom.
+        var from = string.IsNullOrWhiteSpace(req.From)
+            ? _config["Messaging:Email:DefaultFrom"] ?? "no-reply@your-domain.com"
+            : req.From;
+
+        await _email.SendAsync(from, req.To, req.Subject, req.Body ?? string.Empty, req.IsHtml, ct);
+
+        await HttpContext.Response.WriteAsJsonAsync(new
+        {
+            status = "sent",
+            from,
+            to = req.To,
+            note = "With the File provider, output is written to Emails_<yyyy-MM-dd>.txt "
+                 + "in the app base directory."
+        }, ct);
+    }
+}
+
+public class SendEmailRequest
+{
+    /// <summary>Recipient address (required).</summary>
+    public string To { get; set; } = string.Empty;
+
+    /// <summary>Subject line (required).</summary>
+    public string Subject { get; set; } = string.Empty;
+
+    /// <summary>HTML or plain-text body.</summary>
+    public string Body { get; set; } = string.Empty;
+
+    /// <summary>Treat <see cref="Body"/> as HTML. Defaults to true.</summary>
+    public bool IsHtml { get; set; } = true;
+
+    /// <summary>Optional sender; falls back to Messaging:Email:DefaultFrom when omitted.</summary>
+    public string? From { get; set; }
+}

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

@@ -11,9 +11,13 @@
 ## Agent workflow — execute in order
 
 1. **Load context.** Read [README.md](./README.md) (contract + provider matrix) and this file.
-2. **Locate target projects** in the solution (see [[folder-structure]]):
-   `…Application` (injects `IEmailService`), `…Infrastructure` (does the registration),
-   `…Service` (holds `appsettings.json`). If the layout differs, map these roles before continuing.
+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.** In these foundations application/domain/infrastructure code all live in this
+   one project (modules are folders); there is **no** separate `…Application` / `…Infrastructure`
+   project. `<HostProject>` is the target for C2–C4 below.
 3. **Present the implementation catalog (below) as a selection list and ASK the user which
    implementation(s) to integrate.** Use an interactive multi-select prompt (`AskUserQuestion`,
    `multiSelect: true`). The list options are the rows of the *Implementation catalog*.
@@ -27,7 +31,10 @@
 6. **Set the default provider:** `configureOptions: options => options.Provider = "<default key>"`.
    All selected implementations stay registered; the active one is switchable later via config.
 7. **(Optional) Wire a usage example** in the relevant feature handler (§Usage).
-8. **Verify** (§Verification) and report what was added.
+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 — always set `options.Provider`.** When `Provider` is null the facade falls back to a
 > **hardcoded `"SendGrid"`** key; if SendGrid is not registered, resolution throws at runtime. Never
@@ -68,26 +75,24 @@ Present these as the multi-select options. `Key` is the provider key and the `Us
 
 ### C2 — Project references
 
-**File:** `src/<SampleProjectName>.Application/<SampleProjectName>.Application.csproj`
+**File:** `src/<HostProject>/<HostProject>.csproj` (the host project resolved in step 2 — single
+project, no separate Application/Infrastructure). Add the abstraction **and** every selected
+implementation's package here (no `Version=` — versions live in `Directory.Packages.props`, C1).
 
 ```xml
 <ItemGroup>
   <PackageReference Include="AppWeaver.Messaging.Email" />   <!-- no Version= -->
-</ItemGroup>
-```
-
-**File:** `src/<SampleProjectName>.Infrastructure/<SampleProjectName>.Infrastructure.csproj`
-(add the abstraction here too, plus each selected implementation’s package — see its block).
-
-```xml
-<ItemGroup>
-  <PackageReference Include="AppWeaver.Messaging.Email" />
+  <!-- + each selected implementation’s package — see its block below -->
 </ItemGroup>
 ```
 
 ### C3 — Registration scaffold
 
-**File:** `src/<SampleProjectName>.Infrastructure/Extensions/InfrastructureServiceRegistration.cs`
+**File:** the host project `<HostProject>` (step 2) — add the registration 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()`. (`configuration` below = the `IConfiguration` in scope: `config` inside
+`AddInfrastructure`, `builder.Configuration` in `Program.cs`.)
 
 Add the base call; each selected implementation contributes one `builder.Use…(…)` line (C4).
 
@@ -103,9 +108,16 @@ services.AddEmailMessaging(
     configureOptions: options => options.Provider = "<default 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** `AddEmailMessaging(...)` block to
+> **both** `AddInfrastructure` and `AddAspireInfrastructure`. The Email registration is DB-agnostic, so
+> it is identical in both methods — copy it verbatim. Registering in only one leaves `IEmailService`
+> unresolvable (throws at runtime) in the other run mode.
+
 ### C4 — Base appsettings block
 
-**File:** `src/<SampleProjectName>.Service/appsettings.json`
+**File:** `src/<HostProject>/appsettings.json` (the host project resolved in step 2)
 
 ```jsonc
 {
@@ -128,7 +140,7 @@ line**, **config**. Secrets MUST be supplied via user-secrets / env / key vault
 ### MsGraph
 ```xml
 <!-- Directory.Packages.props --> <PackageVersion Include="AppWeaver.Messaging.Email.MsGraph" Version="0.1.2" />
-<!-- Infrastructure.csproj   --> <PackageReference Include="AppWeaver.Messaging.Email.MsGraph" />
+<!-- host .csproj          --> <PackageReference Include="AppWeaver.Messaging.Email.MsGraph" />
 ```
 ```csharp
 using AppWeaver.Messaging.Email.MsGraph.Extensions;
@@ -244,6 +256,31 @@ see [README.md](./README.md)).
 
 ---
 
+## Sample reference endpoint
+
+A ready-to-run FastEndpoint is bundled in this component folder at
+[`ReferenceEndpoints/SendEmailEndpoint.cs`](./ReferenceEndpoints/SendEmailEndpoint.cs). It injects
+`IEmailService` directly and performs the **full send inline** — no command/handler/mediator — purely
+as a copy-paste sample. 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/Email/ReferenceEndpoints/SendEmailEndpoint.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/SendEmailEndpoint.cs`, replacing the
+   namespace token `__HOSTPROJECT__` with `<HostProject>`'s root namespace (e.g.
+   `AppWeaver.Health.Service`). Change nothing else.
+4. Do **not** touch the C1–C4 wiring. FastEndpoints auto-discovers the endpoint by assembly scan, so
+   no extra registration is required.
+
+**Endpoint:** `POST /reference/email/send` — body `{ "to", "subject", "body", "isHtml"?, "from"? }`.
+`from` falls back to `Messaging:Email:DefaultFrom`. With the `File` provider the message is written
+to `Emails_<yyyy-MM-dd>.txt` in the app base directory (no real mail is sent).
+
+---
+
 ## Verification
 
 1. **Builds** — `dotnet build` succeeds; no `Version=` on package references.
@@ -253,6 +290,9 @@ see [README.md](./README.md)).
 4. **Sends** — a send succeeds; for `File`, confirm `Emails_<yyyy-MM-dd>.txt` appears in the app
    base directory.
 5. **No secrets in diff** — `git diff` shows no secret / API key / password literals.
+6. **Sample endpoint (only if copied in step 8)** — the build still succeeds with
+   `ReferenceEndpoints/SendEmailEndpoint.cs` added, the `__HOSTPROJECT__` token was replaced, and
+   `POST /reference/email/send` is discoverable.
 
 ## Related
 

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

@@ -12,9 +12,13 @@
 
 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`).
+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.** In these foundations job classes, handlers, registration, `DbContext`, and
+   `appsettings.json` all live in this one project (modules are folders) — there is **no** separate
+   `…Application` / `…Infrastructure` project. `<HostProject>` is the target for the steps below.
 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:
@@ -69,17 +73,12 @@
 
 ### C2 — Project references (no `Version=`)
 
-**File:** `src/<SampleProjectName>.Application/<SampleProjectName>.Application.csproj`
+**File:** `src/<HostProject>/<HostProject>.csproj` (the host project resolved in step 2 — single
+project, no separate Application/Infrastructure). Add the abstraction, the Quartz engine, and (if a
+Group B item is selected) the EF Core persistence package here:
 ```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" />          <!-- abstractions: IJob, IJobScheduler, IJobProgress -->
   <PackageReference Include="AppWeaver.Jobs.Quartz" />
   <!-- + AppWeaver.Jobs.Persistence.EfCore if a Group B item is selected -->
 </ItemGroup>
@@ -87,14 +86,18 @@
 
 ### C3 — appsettings
 
-**File:** `src/<SampleProjectName>.Service/appsettings.json`
+**File:** `src/<HostProject>/appsettings.json` (the host project resolved in step 2)
 ```jsonc
 { "AppWeaver": { "Jobs": { "Provider": "Quartz", "Quartz": { "MaxConcurrency": 10 } } } }
 ```
 
 ### C4 — Registration scaffold
 
-**File:** `src/<SampleProjectName>.Infrastructure/Extensions/InfrastructureServiceRegistration.cs`
+**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()`. (`configuration` below = the `IConfiguration` in scope: `config` inside
+`AddInfrastructure`, `builder.Configuration` in `Program.cs`.)
 
 The selected blocks fill in the `UseQuartzJobScheduler` body (Group A) and the persistence chain
 (Group B).
@@ -117,6 +120,16 @@ services.AddAppWeaverJobs(
     configureOptions: options => options.Provider = "Quartz");
 ```
 
+> **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 `AddAppWeaverJobs(...)` registration to **both**
+> `AddInfrastructure` and `AddAspireInfrastructure`, or `IJobScheduler` is unregistered whenever the
+> app runs under Aspire. Keep the structure identical, but make any **provider-specific** call match
+> each method's database: in `AddAspireInfrastructure` use the PostgreSQL forms (`s.UsePostgres(...)`,
+> `opts.UseNpgsql(...)`); in `AddInfrastructure` use the SQLite forms (`s.UseMicrosoftSQLite(...)`,
+> `opts.UseSqlite(...)`). `EfCore.DataStore` (`.UseAppWeaverDataStore()`) is provider-agnostic — it
+> rides whichever DataStore that method already registered.
+
 ---
 
 ## Implementation blocks
@@ -199,7 +212,8 @@ public class ExportDataJob(IExportService _exports, IJobProgress _progress) : IJ
 ```
 
 ### Register every job class as `Scoped`
-**File:** `…/Extensions/InfrastructureServiceRegistration.cs`
+**File:** the host project's `Extensions/InfrastructureServiceRegistration.cs` (or `Program.cs`) — the
+same registration site as C4
 ```csharp
 services.AddScoped<ExportDataJob>();
 ```

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

@@ -72,6 +72,13 @@ framework/QrGenerator/
     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]] ·

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

@@ -0,0 +1,57 @@
+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; }
+}