create-cmp-cli 0.6.1 → 0.7.1

package/README.md

@@ -4,8 +4,9 @@
 
 **The AI delivery harness for Kotlin/Compose Multiplatform.**
 
-Scaffold a green-building Android + iOS app in minutes — then let AI extend it, held to a
-machine-enforced definition of done.
+Gives AI coding agents *eyes* and a *machine-enforced definition of done* on mobile: scaffold a
+green-building Android + iOS app in minutes, then let AI extend it — seeing every screen it
+renders, and blocked from "done" without proof.
 
 [![CI](https://github.com/kvdm-co-pilot/create-cmp/actions/workflows/ci.yml/badge.svg)](https://github.com/kvdm-co-pilot/create-cmp/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/create-cmp-cli.svg)](https://www.npmjs.com/package/create-cmp-cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Create production mobile apps (Android + iOS, one Kotlin codebase) with AI — the delivery harness for Compose Multiplatform, the current generation of cross-platform (Google-backed KMP, iOS stable since May 2025). A deterministic, non-interactive generator that scaffolds a green-building app in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Every app carries a device-free UI preview loop (real screens rendered headlessly on save; changed-screen attribution and compile-error surfacing for coding agents, a live gallery for humans) plus agent-first docs (CLAUDE.md + AGENTS.md). Installs the `create-cmp` command.",
   "type": "module",
   "bin": {

package/src/lib/tabs.mjs

@@ -378,8 +378,10 @@ ${imports.join("\n")}
  *
  * The \`@Preview\` analog for the create-cmp inspector: the registry makes "render screen
  * X" a closed, enumerable operation. The scaffolder regenerates the tab entries from the
- * configured \`tabs\`; when you add a screen by hand, add it here — the renderScreens
- * harness, the gallery, and golden baselines pick it up by id.
+ * configured \`tabs\`, and the feature stamper (\`qa/scaffold-feature.mjs\`, via the
+ * \`add-feature\`/\`add-screen\` skills) auto-appends a stamped screen at the
+ * \`// cmp:anchor preview-registry\` marker below; when you add a screen by hand, add it
+ * there too — the renderScreens harness, the gallery, and golden baselines pick it up by id.
  *
  * State variants (the Storybook "story" analog): a screen in a specific UI state is just
  * another entry with a derived id — e.g. \`ScreenPreview("home@empty", "Home — empty")\`
@@ -405,6 +407,7 @@ ${infos.map(previewTabArg).join("\n")}
     },
 ${infos.map(previewEntry).join("\n")}
     ScreenPreview("detail", "Detail (nav destination)") { DetailScreen(itemId = "1", onBack = {}) },
+    // cmp:anchor preview-registry
 )
 
 /**

package/template/.claude/skills/add-feature/SKILL.md

@@ -62,6 +62,10 @@ at their `// cmp:anchor` markers, and writes `specs/<feature>.spec.md` with a de
 set (`<FEATURE>-01..06`: loading, success, error, reload-after-failure, tap-navigates, golden
 tree) — copied verbatim from the `home` exemplar's shape.
 
+The stamped screen arrives **already wrapped in `BaseScreen { … }`** (SHELL-05): it is a
+pushed NavHost destination, so unlike the tab exemplar it must handle its own insets — the
+stamper does this for you; do not unwrap it.
+
 If it exits non-zero, read the message — it is actionable (name already taken, an anchor marker
 is missing, or a name isn't a valid Kotlin identifier). Do not hand-edit around a stamper
 failure; if an anchor is genuinely missing from a shared file, that is a template defect worth

package/template/CLAUDE.md

@@ -75,8 +75,10 @@ and tells you exactly what your edit changed.
 `composeApp/build/previews/<id>/{screen.png, tree.json}` (`-Pscreen=<id>` for one);
 `node qa/preview-gallery.mjs` builds a self-contained gallery page from the output.
 
-Screens come from `inspector/PreviewRegistry.kt` (desktopMain). **When you add a screen,
-register it there** — a forced-state variant is just another entry (`"home@empty"`).
+Screens come from `inspector/PreviewRegistry.kt` (desktopMain). The `add-feature`/`add-screen`
+stamper **auto-registers** a stamped screen there (at the `// cmp:anchor preview-registry`
+marker). **When you add a screen by hand, register it there** — a forced-state variant is just
+another entry (`"home@empty"`).
 Assert on the `tree.json` structure; never read PNG bytes (pixels are for humans).
 <!-- <<< cmp:feature inspector -->
 <!-- >>> cmp:feature dev-client -->

package/template/README.md

@@ -109,4 +109,4 @@ signal for a later one in CI.
 
 ---
 
-Built with [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) — the AI delivery harness for Compose Multiplatform.
+[![Built with create-cmp](https://img.shields.io/badge/Built%20with-create--cmp-7F52FF?logo=kotlin&logoColor=white)](https://github.com/kvdm-co-pilot/create-cmp) — the AI delivery harness for Compose Multiplatform. *(Just a static badge — delete this line if you prefer.)*

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewRegistry.kt

@@ -18,8 +18,10 @@ import __PACKAGE__.presentation.profile.ProfileScreen
  *
  * The `@Preview` analog for the create-cmp inspector: the registry makes "render screen
  * X" a closed, enumerable operation. The scaffolder regenerates the tab entries from the
- * configured `tabs`; when you add a screen by hand, add it here — the renderScreens
- * harness, the gallery, and golden baselines pick it up by id.
+ * configured `tabs`, and the feature stamper (`qa/scaffold-feature.mjs`, via the
+ * `add-feature`/`add-screen` skills) auto-appends a stamped screen at the
+ * `// cmp:anchor preview-registry` marker below; when you add a screen by hand, add it
+ * there too — the renderScreens harness, the gallery, and golden baselines pick it up by id.
  *
  * State variants (the Storybook "story" analog): a screen in a specific UI state is just
  * another entry with a derived id — e.g. `ScreenPreview("home@empty", "Home — empty")`
@@ -47,6 +49,7 @@ fun previewRegistry(): List<ScreenPreview> = listOf(
     ScreenPreview("home", "Home tab") { TabHost { HomeScreen(onItemClick = {}) } },
     ScreenPreview("profile", "Profile tab") { TabHost { ProfileScreen() } },
     ScreenPreview("detail", "Detail (nav destination)") { DetailScreen(itemId = "1", onBack = {}) },
+    // cmp:anchor preview-registry
 )
 
 /**

package/template/qa/lib/inputs-hash.mjs

@@ -4,6 +4,12 @@
 // qa/receipt-check.mjs (recomputes it to test validity) import this module so
 // there is exactly one definition of the surface and the algorithm.
 //
+// SINGLE SOURCE OF TRUTH: packages/receipts/src/inputs-hash.mjs in the
+// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
+// test/receipts-parity.test.mjs — edit the package source, then run
+// `node scripts/sync-receipts.mjs`.
+//
 // See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
 
 import { execSync } from "node:child_process";
@@ -49,14 +55,34 @@ function tryGitLsFiles(root) {
   }
 }
 
+// Directory names the walk fallback must skip wherever they appear under a
+// surface root. These mirror what the stamped .gitignore excludes: without
+// this, a pre-`git init` hash (walk mode) includes composeApp/build/** and
+// Gradle/Kotlin scratch that the post-`git init` hash (`git ls-files
+// --exclude-standard`) excludes — so the stamp-time PASS receipt would read
+// "INVALID — source changed" the moment the user runs `git init`, even though
+// no source changed. Pre-git and post-git hashes must agree for identical
+// source; that is the invariant the regression test pins.
+const WALK_EXCLUDED_DIRS = new Set(["build", ".gradle", ".kotlin", ".git", ".idea", "node_modules"]);
+// File-level mirror of the same principle (OS/editor junk the .gitignore covers).
+const WALK_EXCLUDED_FILES = new Set([".DS_Store"]);
+const WALK_EXCLUDED_SUFFIXES = [".iml", ".log"];
+
+function walkIncludesFile(name) {
+  if (WALK_EXCLUDED_FILES.has(name)) return false;
+  return !WALK_EXCLUDED_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
 // Dependency-free recursive walk, used when git is unavailable (non-git scaffold).
 function walkAllFiles(dir) {
   const out = [];
   if (!fs.existsSync(dir)) return out;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const p = path.join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walkAllFiles(p));
-    else if (entry.isFile()) out.push(p);
+    if (entry.isDirectory()) {
+      if (WALK_EXCLUDED_DIRS.has(entry.name)) continue; // non-source scratch — see note above
+      out.push(...walkAllFiles(p));
+    } else if (entry.isFile() && walkIncludesFile(entry.name)) out.push(p);
   }
   return out;
 }

package/template/qa/lib/receipt-validate.mjs

@@ -0,0 +1,234 @@
+// The evidence-binding predicate and its service-grade extensions, as pure
+// dependency-free functions. `evaluateReceipt` is the exact predicate the
+// generated project's qa/receipt-check.mjs (and its Stop hook + CI) runs;
+// the additional checks (freshness, execution plausibility, SKIP listing) are
+// consumed by hosted validators that judge a receipt fetched from a repo
+// tarball rather than the working tree.
+//
+// SINGLE SOURCE OF TRUTH: packages/receipts/src/receipt-validate.mjs in the
+// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
+// test/receipts-parity.test.mjs — edit the package source, then run
+// `node scripts/sync-receipts.mjs`.
+//
+// See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { computeInputsHash } from "./inputs-hash.mjs";
+
+/** Where a generated project keeps its committed receipt, relative to root. */
+export const RECEIPT_REL_PATH = "qa/evidence/latest.json";
+
+/**
+ * Read and parse the committed receipt for the project rooted at `root`.
+ * @param {string} root absolute path to the project root
+ * @returns {object|null} the parsed receipt, or null when absent/unparsable
+ */
+export function readReceipt(root, relPath = RECEIPT_REL_PATH) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, relPath), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The core predicate: does this receipt validly attest the tree whose inputs
+ * hash `recompute()` returns? Reasons are the exact refusal strings the
+ * generated project's receipt-check CLI (and Stop hook) prints.
+ *
+ * @param {object} receipt parsed receipt JSON
+ * @param {() => {hash: string, fileCount: number}} recompute lazily invoked —
+ *   never called when the receipt fails structurally first (missing binding,
+ *   FAIL verdict), so callers don't pay for a hash they don't need.
+ * @returns {{valid: boolean, reason: string, profile: (string|undefined), recomputed?: {hash: string, fileCount: number}}}
+ */
+export function evaluateReceipt(receipt, recompute) {
+  const profile = receipt.profile;
+
+  if (!receipt.inputs || typeof receipt.inputs.hash !== "string") {
+    return {
+      valid: false,
+      reason: `receipt predates evidence binding — re-run the lane (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  if (receipt.verdict === "FAIL") {
+    return {
+      valid: false,
+      reason: `the committed receipt is a FAIL (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  const recomputed = recompute();
+
+  if (receipt.inputs.hash !== recomputed.hash) {
+    return {
+      valid: false,
+      reason: `source changed since the receipt — re-run the lane (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+      recomputed,
+    };
+  }
+
+  if (receipt.verdict !== "PASS") {
+    return {
+      valid: false,
+      reason: `receipt verdict is "${receipt.verdict}", not PASS (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  return { valid: true, reason: `receipt is valid — PASS, attesting profile: ${profile ?? "unknown"}`, profile, recomputed };
+}
+
+// ── Service-grade checks (hosted validators; the local predicate above does
+//    not enforce these — the tree it checks is by definition "now") ─────────
+
+/** Default policy for hosted validation. Every knob is overridable. */
+export const DEFAULT_POLICY = {
+  /** A receipt older than this no longer counts as fresh (hosted check only). */
+  maxAgeMs: 30 * 24 * 60 * 60 * 1000, // 30 days
+  /**
+   * Executed (non-SKIP) gates must report at least this much total wall time.
+   * A "PASS" receipt whose executed gates sum to less cannot attest a real
+   * lane run — the tell for replayed/cached or hand-written verdicts
+   * (evidence must attest execution, not results).
+   */
+  minExecutedMs: 5000,
+};
+
+/**
+ * Freshness: is the receipt's generatedAt within maxAgeMs of `now`?
+ * @returns {{ok: boolean, detail: string, ageMs?: number}}
+ */
+export function checkFreshness(receipt, { now = Date.now(), maxAgeMs = DEFAULT_POLICY.maxAgeMs } = {}) {
+  const generatedAt = Date.parse(receipt?.generatedAt ?? "");
+  if (Number.isNaN(generatedAt)) {
+    return { ok: false, detail: "receipt has no parsable generatedAt timestamp" };
+  }
+  const ageMs = now - generatedAt;
+  if (ageMs < -60_000) {
+    // A receipt from the future is a clock lie, not a rounding artifact.
+    return { ok: false, detail: `receipt claims a future generatedAt (${receipt.generatedAt})`, ageMs };
+  }
+  if (ageMs > maxAgeMs) {
+    const days = Math.floor(ageMs / 86_400_000);
+    return { ok: false, detail: `receipt is stale — generated ${days} day(s) ago, older than the ${Math.floor(maxAgeMs / 86_400_000)}-day freshness window`, ageMs };
+  }
+  return { ok: true, detail: `receipt generated ${receipt.generatedAt}`, ageMs };
+}
+
+/**
+ * Execution plausibility: do the executed (non-SKIP) gates report durations a
+ * real lane run could produce? Catches replayed/cached greens and hand-edited
+ * receipts whose numbers were never lived.
+ * @returns {{ok: boolean, detail: string, executedMs?: number, executedSteps?: number}}
+ */
+export function checkExecutionPlausibility(receipt, { minExecutedMs = DEFAULT_POLICY.minExecutedMs } = {}) {
+  const steps = Array.isArray(receipt?.steps) ? receipt.steps : null;
+  if (!steps || steps.length === 0) {
+    return { ok: false, detail: "receipt lists no verify-lane steps — nothing was executed" };
+  }
+  const executed = steps.filter((s) => s && s.verdict !== "SKIP");
+  if (executed.length === 0) {
+    return { ok: false, detail: "every step in the receipt is a SKIP — the lane verified nothing" };
+  }
+  let total = 0;
+  for (const step of executed) {
+    if (typeof step.durationMs !== "number" || !Number.isFinite(step.durationMs) || step.durationMs < 0) {
+      return { ok: false, detail: `step "${step.name ?? "?"}" reports an invalid duration (${step.durationMs}) — durations must be real, non-negative numbers` };
+    }
+    total += step.durationMs;
+  }
+  if (total < minExecutedMs) {
+    return {
+      ok: false,
+      detail: `implausibly fast — executed gates report ${total}ms total, below the ${minExecutedMs}ms floor; a receipt this fast cannot attest a real lane run (evidence must attest execution)`,
+      executedMs: total,
+      executedSteps: executed.length,
+    };
+  }
+  return { ok: true, detail: `${executed.length} executed gate(s), ${total}ms total`, executedMs: total, executedSteps: executed.length };
+}
+
+/**
+ * List the SKIPped steps with their honest reasons. SKIPs are reported, not
+ * failed — green-with-gaps must be visible, never silently equated with
+ * fully-verified (or silently punished).
+ * @returns {Array<{name: string, reason: string}>}
+ */
+export function listSkippedSteps(receipt) {
+  const steps = Array.isArray(receipt?.steps) ? receipt.steps : [];
+  return steps
+    .filter((s) => s && s.verdict === "SKIP")
+    .map((s) => ({ name: s.name ?? "?", reason: s.reason ?? "no reason recorded" }));
+}
+
+/**
+ * The hosted composite: validate the receipt found in an extracted repo tree
+ * (e.g. a tarball at a PR's head SHA) with the full service-grade policy.
+ *
+ * @param {object} args
+ * @param {string} args.root absolute path to the extracted tree's project root
+ * @param {number} [args.now] epoch ms, for freshness (defaults to Date.now())
+ * @param {object} [args.policy] overrides for DEFAULT_POLICY
+ * @returns {{
+ *   status: "missing"|"valid"|"invalid",
+ *   reason: string,
+ *   profile?: string,
+ *   checks: Array<{id: string, ok: boolean, detail: string}>,
+ *   skips: Array<{name: string, reason: string}>,
+ * }}
+ */
+export function validateReceiptForTree({ root, now = Date.now(), policy = {} } = {}) {
+  const effective = { ...DEFAULT_POLICY, ...policy };
+  const receipt = readReceipt(root);
+
+  if (receipt === null) {
+    return {
+      status: "missing",
+      reason: `no receipt at ${RECEIPT_REL_PATH} — this repo does not carry the create-cmp evidence harness (that is not a failure)`,
+      checks: [{ id: "receipt-present", ok: false, detail: `no parsable receipt at ${RECEIPT_REL_PATH}` }],
+      skips: [],
+    };
+  }
+
+  const checks = [{ id: "receipt-present", ok: true, detail: RECEIPT_REL_PATH }];
+  const skips = listSkippedSteps(receipt);
+
+  // The core predicate (binding + verdict + hash), verbatim local semantics.
+  const core = evaluateReceipt(receipt, () => computeInputsHash(root));
+  checks.push({ id: "binding-and-hash", ok: core.valid, detail: core.reason });
+
+  // Service-grade extensions run regardless, so a failing receipt reports
+  // every violated rule at once (refusals name what failed, all of it).
+  const freshness = checkFreshness(receipt, { now, maxAgeMs: effective.maxAgeMs });
+  checks.push({ id: "freshness", ok: freshness.ok, detail: freshness.detail });
+
+  const plausibility = checkExecutionPlausibility(receipt, { minExecutedMs: effective.minExecutedMs });
+  checks.push({ id: "execution-plausibility", ok: plausibility.ok, detail: plausibility.detail });
+
+  const failed = checks.filter((c) => !c.ok);
+  if (failed.length > 0) {
+    return {
+      status: "invalid",
+      reason: failed.map((c) => c.detail).join("; "),
+      profile: core.profile,
+      checks,
+      skips,
+    };
+  }
+
+  return {
+    status: "valid",
+    reason: core.reason,
+    profile: core.profile,
+    checks,
+    skips,
+  };
+}

package/template/qa/receipt-check.mjs

@@ -20,9 +20,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { computeInputsHash } from "./lib/inputs-hash.mjs";
+import { evaluateReceipt, readReceipt } from "./lib/receipt-validate.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const RECEIPT_PATH = path.join(ROOT, "qa", "evidence", "latest.json");
 
 const args = process.argv.slice(2);
 const asHook = args.includes("--hook");
@@ -38,52 +38,15 @@ function readStdinJson() {
   }
 }
 
+// The predicate itself lives in qa/lib/receipt-validate.mjs (vendored from the
+// cmp-receipts package — one definition everywhere a receipt is judged); this
+// CLI only reads the receipt and frames the exit codes.
 function evaluate() {
-  let receipt;
-  try {
-    receipt = JSON.parse(fs.readFileSync(RECEIPT_PATH, "utf8"));
-  } catch {
+  const receipt = readReceipt(ROOT);
+  if (receipt === null) {
     return { valid: false, reason: "no receipt — run `node qa/verify.mjs`", profile: undefined };
   }
-
-  const profile = receipt.profile;
-
-  if (!receipt.inputs || typeof receipt.inputs.hash !== "string") {
-    return {
-      valid: false,
-      reason: `receipt predates evidence binding — re-run the lane (attesting profile: ${profile ?? "unknown"})`,
-      profile,
-    };
-  }
-
-  if (receipt.verdict === "FAIL") {
-    return {
-      valid: false,
-      reason: `the committed receipt is a FAIL (attesting profile: ${profile ?? "unknown"})`,
-      profile,
-    };
-  }
-
-  const recomputed = computeInputsHash(ROOT);
-
-  if (receipt.inputs.hash !== recomputed.hash) {
-    return {
-      valid: false,
-      reason: `source changed since the receipt — re-run the lane (attesting profile: ${profile ?? "unknown"})`,
-      profile,
-      recomputed,
-    };
-  }
-
-  if (receipt.verdict !== "PASS") {
-    return {
-      valid: false,
-      reason: `receipt verdict is "${receipt.verdict}", not PASS (attesting profile: ${profile ?? "unknown"})`,
-      profile,
-    };
-  }
-
-  return { valid: true, reason: `receipt is valid — PASS, attesting profile: ${profile ?? "unknown"}`, profile, recomputed };
+  return evaluateReceipt(receipt, () => computeInputsHash(ROOT));
 }
 
 const result = evaluate();

package/template/qa/scaffold-feature.mjs

@@ -212,7 +212,7 @@ const ALL_FILES = [
   { from: path.join(SRC("commonMain"), "domain/usecase/GetItemsUseCase.kt"), to: path.join(SRC("commonMain"), `domain/usecase/Get${E}sUseCase.kt`), presets: ["feature", "repository"] },
   { from: path.join(SRC("commonMain"), "data/remote/ItemRepositoryImpl.kt"), to: path.join(SRC("commonMain"), `data/remote/${E}RepositoryImpl.kt`), presets: ["feature", "repository"] },
   { from: path.join(SRC("commonTest"), "testing/fakes/FakeItemRepository.kt"), to: path.join(SRC("commonTest"), `testing/fakes/Fake${E}Repository.kt`), presets: ["feature", "repository"] },
-  { from: path.join(SRC("commonMain"), "presentation/home/HomeScreen.kt"), to: path.join(SRC("commonMain"), `presentation/${f}/${F}Screen.kt`), presets: ["feature", "screen"] },
+  { from: path.join(SRC("commonMain"), "presentation/home/HomeScreen.kt"), to: path.join(SRC("commonMain"), `presentation/${f}/${F}Screen.kt`), presets: ["feature", "screen"], wrapInBaseScreen: true },
   { from: path.join(SRC("commonMain"), "presentation/home/HomeViewModel.kt"), to: path.join(SRC("commonMain"), `presentation/${f}/${F}ViewModel.kt`), presets: ["feature", "screen"] },
   { from: path.join(SRC("commonTest"), "presentation/home/HomeViewModelTest.kt"), to: path.join(SRC("commonTest"), `presentation/${f}/${F}ViewModelTest.kt`), presets: ["feature", "screen"] },
   { from: path.join(SRC("desktopTest"), "presentation/home/HomeScreenTest.kt"), to: path.join(SRC("desktopTest"), `presentation/${f}/${F}ScreenTest.kt`), presets: ["feature", "screen"] },
@@ -292,6 +292,69 @@ function defaultSpec() {
 `;
 }
 
+// ── BaseScreen wrap (SHELL-05) ───────────────────────────────────────────────
+// HomeScreen is a TAB — AppShell provides its BaseScreen at the shell layer.
+// The stamped feature, however, is registered as a PUSHED NavHost destination,
+// and SHELL-05 requires every such destination to compose inside BaseScreen
+// (see DetailScreen for the pattern). Without this transform the stamped slice
+// fails verify out of the box. Anchored on the exemplar's known shape; fails
+// loudly if HomeScreen drifts (same discipline as the cmp:anchor markers).
+function wrapScreenInBaseScreen(content, relPathForErrors) {
+  if (content.includes("BaseScreen")) return content; // already wrapped — idempotent
+
+  const lines = content.split("\n");
+
+  // 1. Import — mirror DetailScreen's ordering: presentation.components.BaseScreen
+  //    sits immediately before the presentation.theme imports.
+  const themeImportIdx = lines.findIndex((l) => /^import .+\.presentation\.theme\./.test(l));
+  if (themeImportIdx === -1) {
+    die(
+      `no presentation.theme import found in ${relPathForErrors} — the HomeScreen exemplar ` +
+        "drifted from the shape this stamper wraps; cannot place the BaseScreen import.",
+    );
+  }
+  const importLine = lines[themeImportIdx].replace(
+    /^import (.+)\.presentation\.theme\..*$/,
+    "import $1.presentation.components.BaseScreen",
+  );
+  lines.splice(themeImportIdx, 0, importLine);
+
+  // 2. Root container start: the exemplar's body root is a top-level `    Column(`.
+  const rootIdx = lines.findIndex((l) => l === "    Column(");
+  if (rootIdx === -1) {
+    die(
+      `root "    Column(" not found in ${relPathForErrors} — the HomeScreen exemplar drifted ` +
+        "from the shape this stamper wraps in BaseScreen.",
+    );
+  }
+
+  // 3. Root container end: the `    }` immediately before the function's closing `}`.
+  let funCloseIdx = -1;
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (lines[i] === "}") {
+      funCloseIdx = i;
+      break;
+    }
+  }
+  if (funCloseIdx === -1 || lines[funCloseIdx - 1] !== "    }") {
+    die(
+      `could not locate the root container's closing brace in ${relPathForErrors} — the ` +
+        "HomeScreen exemplar drifted from the shape this stamper wraps in BaseScreen.",
+    );
+  }
+  const rootCloseIdx = funCloseIdx - 1;
+
+  // 4. Wrap: indent the container block one level and enclose it in BaseScreen { }.
+  const indented = lines.slice(rootIdx, rootCloseIdx + 1).map((l) => (l.length ? `    ${l}` : l));
+  return [
+    ...lines.slice(0, rootIdx),
+    "    BaseScreen {",
+    ...indented,
+    "    }",
+    ...lines.slice(rootCloseIdx + 1),
+  ].join("\n");
+}
+
 // ── Anchor injection (§5) ────────────────────────────────────────────────────
 // Idempotent (skip if the feature's line is already present); fails loudly if
 // an anchor marker is missing from the shared file. Each function is a pure
@@ -383,6 +446,11 @@ const plan = {
 const APP_MODULE = path.join(SRC("commonMain"), "di/AppModule.kt");
 const SCREEN_KT = path.join(SRC("commonMain"), "presentation/navigation/Screen.kt");
 const APP_NAV_HOST = path.join(SRC("commonMain"), "presentation/navigation/AppNavHost.kt");
+// Optional (present only when the inspector feature is enabled): the preview
+// registry lives in desktopMain. A stamped pushed-destination screen is
+// registered here so `renderScreens`, the gallery, and golden baselines pick it
+// up with zero hand edits — the same reason we wire nav/DI automatically.
+const PREVIEW_REGISTRY = path.join(SRC("desktopMain"), "inspector/PreviewRegistry.kt");
 
 // Each step is tagged with the presets it belongs to, same mechanism as
 // FILES above: `repository` gets repo+usecase DI (+ imports) only; `screen`
@@ -415,14 +483,30 @@ const ALL_INJECTION_PLANS = [
       { presets: ["feature", "screen"], apply: (c) => injectAtAnchor(c, APP_NAV_HOST, "nav-destinations", `composable(Screen.${F}.route) { ${F}Screen(onItemClick = {}) }`) },
     ],
   },
+  {
+    // Optional: only wired when the inspector feature shipped PreviewRegistry.kt.
+    // Registers the stamped screen exactly as the NavHost hosts it (pushed
+    // destination → standalone, matching DetailScreen), so preview parity holds.
+    filePath: PREVIEW_REGISTRY,
+    optional: true,
+    steps: [
+      { presets: ["feature", "screen"], apply: (c) => injectImport(c, PREVIEW_REGISTRY, `import ${PACKAGE}.presentation.${f}.${F}Screen`) },
+      { presets: ["feature", "screen"], apply: (c) => injectAtAnchor(c, PREVIEW_REGISTRY, "preview-registry", `ScreenPreview("${f}", "${F} (nav destination)") { ${F}Screen(onItemClick = {}) },`) },
+    ],
+  },
 ];
 
 // Filter steps by active preset; drop any file plan left with zero steps
 // (e.g. Screen.kt / AppNavHost.kt entirely for `repository`).
 const fileInjectionPlans = ALL_INJECTION_PLANS.map((p) => ({
   filePath: p.filePath,
+  optional: p.optional === true,
   steps: p.steps.filter((s) => s.presets.includes(preset)).map((s) => s.apply),
-})).filter((p) => p.steps.length > 0);
+}))
+  .filter((p) => p.steps.length > 0)
+  // An optional shared file (PreviewRegistry.kt when the inspector is disabled)
+  // simply isn't wired — a required file that's missing still dies in applyInjectionSteps.
+  .filter((p) => !(p.optional && !fs.existsSync(p.filePath)));
 
 const fileResults = fileInjectionPlans.map((p) => applyInjectionSteps(p.filePath, p.steps));
 
@@ -452,6 +536,16 @@ if (dryRun) {
       for (const line of inj.diff.split("\n").filter(Boolean)) console.log(`    + ${line}`);
     }
   }
+  if (FILES.some((file) => file.wrapInBaseScreen)) {
+    console.log(
+      `\n${F}Screen.kt is stamped wrapped in BaseScreen (SHELL-05 — pushed destinations wrap their own content).`,
+    );
+  }
+  if (fileInjectionPlans.some((p) => p.filePath === PREVIEW_REGISTRY)) {
+    console.log(
+      `\n${F}Screen is auto-registered in inspector/PreviewRegistry.kt (renderScreens + gallery + golden baseline pick it up).`,
+    );
+  }
   if (writesSpec) {
     console.log(`\nspecs/${f}.spec.md will be written with default clauses ${F_UPPER}-01..06.`);
   } else {
@@ -465,7 +559,12 @@ if (dryRun) {
 
 let filesWritten = 0;
 for (const file of FILES) {
-  const contents = file.isDefaultSpec ? defaultSpec() : applyRename(fs.readFileSync(file.from, "utf8"));
+  let contents = file.isDefaultSpec ? defaultSpec() : applyRename(fs.readFileSync(file.from, "utf8"));
+  if (file.wrapInBaseScreen) {
+    // Pushed destination: wrap the cloned tab-screen body so SHELL-05 passes
+    // out of the box (the tab exemplar relies on AppShell for its BaseScreen).
+    contents = wrapScreenInBaseScreen(contents, path.relative(ROOT, file.to));
+  }
   fs.mkdirSync(path.dirname(file.to), { recursive: true });
   fs.writeFileSync(file.to, contents);
   filesWritten += 1;