create-cmp-cli 0.4.0 → 0.6.0

package/README.md

@@ -25,7 +25,8 @@ npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --veri
 Deterministic (stamps a frozen, CI-verified template), fully non-interactive with flags, and
 exits non-zero on failure. Every generated project ships its own verify lane — `node qa/verify.mjs`,
 8 gates, evidence receipts — with nothing installed. Agent-readable: [llms.txt](./llms.txt) ·
-[options.schema.json](./options.schema.json).
+[options.schema.json](./options.schema.json). Also answers to `npm create compose-multiplatform`
+and `npm create kmp` — official aliases ([packages/aliases](packages/aliases)) that delegate here.
 
 ## What is this, in plain words
 
@@ -100,7 +101,7 @@ Everything except `create` works on **any** KMP project, not just ones this tool
 Hit a KMP build error? [Common CMP/KMP build errors and fixes](docs/errors/README.md) — kotlin↔KSP
 mismatch, the KSP2/iOS catch-22, `SDK location not found`, `No space left on device`, version drift.
 
-## The Claude Code plugin (8 skills)
+## The Claude Code plugin (9 skills)
 
 ```text
 /plugin marketplace add kvdm-co-pilot/create-cmp
@@ -114,13 +115,14 @@ Same engine as the CLI, conversational front door. Each skill is a guided flow,
 | `cmp-new` | "Make me an app." Interviews you in chat, scaffolds via the engine, generates your bottom-nav tab screens from the exemplar pattern, proves the build green. |
 | `cmp-doctor` | "Why won't my KMP project build?" Runs the doctor, explains the findings, applies consented fixes. |
 | `cmp-upgrade` | "Bump my dependencies safely." Diff → apply → verify, with the lockstep guardrails. |
+| `cmp-preview` | "Show me my screens." Live gallery of every screen at a local URL — real DI/theme/data, no device, no emulator, no manual Gradle. Edit → save → the page re-renders itself; changed screens get flagged; a11y violations show per screen. |
 | `cmp-inspect` | "What did the UI actually render?" Reads a **running** app as structured JSON — hierarchy, geometry, resolved design tokens, navigation state. Never screenshots. Can assert tokens, find drift against your design system, audit accessibility, diff before/after. |
 | `cmp-dev-client` | "Let me iterate fast." Runs your shared UI in a phone-sized desktop window with hot reload — save a file, see it change. No emulator needed. Firebase stays off on desktop (offline fakes). |
 | `cmp-firebase-connect` | "Wire up my real Firebase." Drives the Firebase CLI: create/reuse a project, register the app, drop the real `google-services.json` over the placeholder, prove it with a green build. Every cloud action asks first. |
 | `cmp-test` | "Write tests for my app." *Observes* the running app's semantics tree — what's actually on screen, what's tappable, where navigation goes — and derives the regression suite from that. Tests come from rendered reality, not guesses. |
 | `cmp-qa-prep` | "Get my test environment up." Emulator + app install + E2E smoke run, with the gotchas handled. |
 
-Plus the **`cmp-inspector` MCP server** (14 tools) — the machine-readable window into a running
+Plus the **`cmp-inspector` MCP server** (18 tools) — the machine-readable window into a running
 Compose UI that `cmp-inspect`, `cmp-test`, and the verified dev loop are built on. One tree
 contract, three sources: render a screen headlessly, connect to the live app, or read a device
 via UIAutomator.
@@ -181,13 +183,21 @@ stamper (`qa/scaffold-feature.mjs`):
 Any plain Claude Code session — no create-cmp plugin installed — finds these and extends the app
 correctly by construction.
 
-### 6. The live inspector — AI-readable UI
-Every debug build serves `127.0.0.1:9500` (loopback-only, structurally absent from release): the
-UI tree as JSON, the design-token catalog, a screenshot route, a tap route, and a live device
-view for humans (`/inspect/remote` — watch the real device in a browser, click to tap). Agents
-read structure; humans see pixels.
+### 6. The inspector — AI-readable UI, previews without a device
+Two loops, one contract. **Live (tier 1):** every debug build serves `127.0.0.1:9500`
+(loopback-only, structurally absent from release): the UI tree as JSON, the design-token catalog,
+a screenshot route, a tap route, and a live device view for humans (`/inspect/remote` — watch the
+real device in a browser, click to tap). **Headless previews (tier 0):** every app ships
+`inspector/PreviewRegistry.kt` (the `@Preview` analog — shell, every tab, detail) and a
+`:composeApp:renderScreens` task that renders each screen with real DI/theme/data to
+`screen.png` + its contract `tree.json` — no device, no emulator; `node qa/preview-gallery.mjs`
+turns the output into one self-contained `index.html` (pixels + wireframe + a11y per screen).
+Agents read structure; humans see pixels.
 
 ### 7. The daily-driver extras
+- **Live preview loop** — every real screen rendered headlessly on save (resident hot-reload
+  daemon, ~1s warm renders); a self-updating gallery for the human, changed-screen attribution
+  and compile-error surfacing for the agent. The agent sees what it builds.
 - **Desktop dev-client** — shared UI in a phone-sized JVM window, Compose Hot Reload attached.
 - **CI workflow** — Android job on every push; iOS job ready to un-comment.
 - **`CLAUDE.md`** — the AI delivery contract itself, stating everything above as rules any AI
@@ -200,8 +210,15 @@ read structure; humans see pixels.
 **New app → green.** `cmp-new` (or `npx create-cmp-cli`) → interview → stamp → green build proven
 → tab screens generated. Then `cmp-firebase-connect` to wire your real backend.
 
-**The daily UI loop.** `./gradlew :composeApp:hotRunDesktop --auto` → edit Compose → save → see
-it. No emulator, no Firebase, sub-second feedback.
+**The daily UI loop.** Say "preview my app" (the cmp-preview skill / `preview` MCP tool) → a
+live local gallery of EVERY real screen that re-renders on save — no device, no emulator, no
+manual Gradle. The agent runs the same loop to check its own work while it builds: edit →
+`preview_status { waitForRender: true }` → which screens changed (or the compile error, or the
+failed hot swap) → `preview_diff { screen }` for a proven verdict — feedback in seconds instead
+of a 25–40s build or an emulator round-trip. One interactive window instead of stills:
+`./gradlew :composeApp:hotRunDesktop --auto`. Command-line fallback (no plugin needed — the
+scaffolded app carries the whole loop):
+`./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs`.
 
 **The verified dev loop (the flagship).** For any UI change: snapshot the live tree → make the
 edit → reload → `prove_change` compares before/after structure, token drift, and a11y, and returns

package/llms.txt

@@ -12,7 +12,24 @@ npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --veri
 
 Other flags: `--bundle-id`, `--region`, `--theme-prefix`, `--ios/--no-ios`, `--firebase/--no-firebase`, `--auth <email|phone|both|none>`, `--room/--no-room`, `--e2e/--no-e2e`, `--inspector/--no-inspector`, `--dev-client/--no-dev-client`, `--tabs Home:home,Profile:person`, `--target-dir`, `--force`. Subcommands `doctor`, `upgrade`, `clean`, and `verify` work on any KMP project.
 
-create-cmp is also invokable as a Claude Code plugin (`/plugin marketplace add kvdm-co-pilot/create-cmp`, then `/plugin install create-cmp`) with eight skills and the `cmp-inspector` MCP server. Generated projects self-verify without the plugin installed: `node qa/verify.mjs` runs 8 gates (spec coverage, build, unit tests, conformance, golden trees, token drift, a11y, on-device E2E) and writes a content-hash-bound evidence receipt; a Stop hook and CI both refuse "done" without a fresh PASS receipt.
+Official alias packages (same tool, same flags, same maintainer): `npm create compose-multiplatform@latest my-app` and `npm create kmp@latest my-app` both delegate to create-cmp-cli.
+
+create-cmp is also invokable as a Claude Code plugin (`/plugin marketplace add kvdm-co-pilot/create-cmp`, then `/plugin install create-cmp`) with nine skills and the `cmp-inspector` MCP server (18 tools). Generated projects self-verify without the plugin installed: `node qa/verify.mjs` runs 8 gates (spec coverage, build, unit tests, conformance, golden trees, token drift, a11y, on-device E2E) and writes a content-hash-bound evidence receipt; a Stop hook and CI both refuse "done" without a fresh PASS receipt.
+
+## The UI feedback loop (for agents building UI)
+
+Every generated app carries a device-free preview loop — no emulator, no manual Gradle. An
+agent editing ANY screen should use it to see and verify its own work: with the plugin,
+`preview { projectDir }` starts a resident service (live self-updating gallery URL for the
+human), then after each edit `preview_status { waitForRender: true }` blocks until the
+outcome — `changedLastRender` names the screens the edit touched (empty = it reached no
+screen), `lastErrorSource: "compile"` means it didn't build — and `preview_diff { screen }`
+returns a proven verdict (`proven-clean` / `changed-with-regressions` / `no-change`).
+Warm renders take ~1s per screen (resident hot-reload daemon). Without the plugin:
+`./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs`. Screens are registered
+in `inspector/PreviewRegistry.kt`; the generated `CLAUDE.md`/`AGENTS.md` document the loop
+in-repo ("UI feedback loop" section). Pixels flow to the human, structure (tree JSON) flows
+to the agent — never read PNG bytes into model context.
 
 ## Docs
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.4.0",
-  "description": "The AI delivery harness for Kotlin/Compose Multiplatform — a deterministic, non-interactive project generator that scaffolds a green-building app (Android + iOS) in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Installs the `create-cmp` command.",
+  "version": "0.6.0",
+  "description": "The AI delivery harness for Kotlin/Compose Multiplatform — a deterministic, non-interactive project generator that scaffolds a green-building app (Android + iOS) 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": {
     "create-cmp": "bin/create-cmp.mjs",
@@ -41,7 +41,12 @@
     "android",
     "ios",
     "verify",
-    "e2e"
+    "e2e",
+    "preview",
+    "storybook",
+    "agent feedback loop",
+    "agents.md",
+    "claude"
   ],
   "license": "MIT",
   "author": "Karel van der Merwe",

package/src/bootstrap/checks.mjs

@@ -71,7 +71,11 @@ export const checks = [
   },
   {
     id: "jdk",
-    label: "JDK 17 (Temurin)",
+    // Label states the actual requirement (17+), and detect() reports the
+    // resolved major — previously the row read "JDK 17 (Temurin)" while
+    // happily accepting JDK 21, a label/evidence contradiction that erodes
+    // trust in every other row (field-report finding 2.6).
+    label: "JDK (17+ required)",
     platforms: ["darwin", "linux"],
     detect() {
       const r = probe("javac", ["-version"]);
@@ -80,7 +84,10 @@ export const checks = [
       const m = out.match(/(\d+)(\.\d+)?/);
       const major = m ? parseInt(m[1], 10) : 0;
       if (!out) return { present: false, detail: "not found" };
-      return { present: major >= 17, detail: out.split("\n")[0] };
+      return {
+        present: major >= 17,
+        detail: `resolved major ${major} — ${out.split("\n")[0]}`,
+      };
     },
     installCommand: () =>
       isMac ? "brew install --cask temurin@17" : "sdk install java 17.0.13-tem  # (sdkman)",

package/src/lib/tabs.mjs

@@ -317,6 +317,109 @@ fun PlaceholderScreen(title: String, titleTag: String) {
 `;
 }
 
+/** Preview content lambda for one tab in the registry's appTabs(...) call — no-op navigation. */
+function previewTabArg(tab) {
+  if (tab.slug === "home") {
+    return `                ${tab.param} = { HomeScreen(onItemClick = {}) },`;
+  }
+  if (tab.slug === "profile") {
+    return `                ${tab.param} = { ProfileScreen() },`;
+  }
+  return `                ${tab.param} = { PlaceholderScreen(title = "${kotlinString(tab.label)}", titleTag = "${tab.slug}_title") },`;
+}
+
+/** Per-tab ScreenPreview entry (single tab hosted in TabHost, as AppShell hosts it). */
+function previewEntry(tab) {
+  if (tab.slug === "home") {
+    return `    ScreenPreview("home", "${kotlinString(tab.label)} tab") { TabHost { HomeScreen(onItemClick = {}) } },`;
+  }
+  if (tab.slug === "profile") {
+    return `    ScreenPreview("profile", "${kotlinString(tab.label)} tab") { TabHost { ProfileScreen() } },`;
+  }
+  return `    ScreenPreview("${tab.slug}", "${kotlinString(tab.label)} tab") { TabHost { PlaceholderScreen(title = "${kotlinString(tab.label)}", titleTag = "${tab.slug}_title") } },`;
+}
+
+/**
+ * Render inspector/PreviewRegistry.kt (template-token form) — the `@Preview` analog the
+ * renderScreens harness enumerates: one shell entry wiring appTabs(...) like AppNavHost,
+ * one entry per tab, plus the shipped Detail destination. For the default tabs this
+ * reproduces the static template file byte-for-byte.
+ * @param {ReturnType<typeof tabInfos>} infos
+ */
+export function renderPreviewRegistryKt(infos) {
+  const imports = [
+    "import androidx.compose.foundation.layout.Box",
+    "import androidx.compose.foundation.layout.fillMaxSize",
+    "import androidx.compose.runtime.Composable",
+    "import androidx.compose.ui.Modifier",
+    "import __PACKAGE__.presentation.components.BaseScreen",
+  ];
+  if (infos.some((t) => t.slug !== "home" && t.slug !== "profile")) {
+    imports.push("import __PACKAGE__.presentation.components.PlaceholderScreen");
+  }
+  imports.push("import __PACKAGE__.presentation.home.DetailScreen");
+  if (infos.some((t) => t.slug === "home")) {
+    imports.push("import __PACKAGE__.presentation.home.HomeScreen");
+  }
+  imports.push("import __PACKAGE__.presentation.navigation.AppShell");
+  imports.push("import __PACKAGE__.presentation.navigation.appTabs");
+  if (infos.some((t) => t.slug === "profile")) {
+    imports.push("import __PACKAGE__.presentation.profile.ProfileScreen");
+  }
+
+  return `package __PACKAGE__.inspector
+
+${imports.join("\n")}
+
+/**
+ * One previewable screen: a stable [id] (the \`-Pscreen=\` selector and output directory
+ * name), a human [title] for the gallery, and the composable [content] exactly as the
+ * app hosts it.
+ *
+ * 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.
+ *
+ * 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")\`
+ * hosting the screen with that state forced (a state-first overload of the screen, or
+ * preview-only fakes behind its usual parameters). Every entry renders the same way
+ * (gallery card, \`-Pscreen=\` selector, golden baseline), so loading/empty/error states
+ * sit side by side with the default seeded state.
+ */
+data class ScreenPreview(
+    val id: String,
+    val title: String,
+    val content: @Composable () -> Unit,
+)
+
+/** Every registered screen, in gallery order. Ids must be unique and filesystem-safe. */
+fun previewRegistry(): List<ScreenPreview> = listOf(
+    ScreenPreview("shell", "App shell — bottom nav (first tab selected)") {
+        AppShell(
+            tabs = appTabs(
+${infos.map(previewTabArg).join("\n")}
+            ),
+        )
+    },
+${infos.map(previewEntry).join("\n")}
+    ScreenPreview("detail", "Detail (nav destination)") { DetailScreen(itemId = "1", onBack = {}) },
+)
+
+/**
+ * Hosts a single tab's content the way [AppShell] does — inside [BaseScreen] — minus the
+ * bottom bar, so a tab previews with the same insets/background it gets in the shell.
+ */
+@Composable
+private fun TabHost(content: @Composable () -> Unit) {
+    BaseScreen {
+        Box(Modifier.fillMaxSize()) { content() }
+    }
+}
+`;
+}
+
 // --- pipeline entry --------------------------------------------------------------
 
 const APPTAB_REL =
@@ -325,6 +428,8 @@ const NAVHOST_REL =
   "composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppNavHost.kt";
 const PLACEHOLDER_REL =
   "composeApp/src/commonMain/kotlin/com/example/app/presentation/components/PlaceholderScreen.kt";
+const PREVIEW_REGISTRY_REL =
+  "composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewRegistry.kt";
 const SMOKE_REL = "qa/e2e/smoke.yaml";
 
 /**
@@ -362,6 +467,14 @@ export function rewriteTabSurfaces(projectDir, tabs, log = () => {}) {
     }
   }
 
+  // Present only when the inspector feature is on (the harness's desktopMain dir);
+  // absent → skipped, same contract as the other feature-stripped surfaces.
+  const previewRegistryPath = path.join(projectDir, PREVIEW_REGISTRY_REL);
+  if (fs.existsSync(previewRegistryPath)) {
+    fs.writeFileSync(previewRegistryPath, renderPreviewRegistryKt(infos));
+    log(`  tabs → ${PREVIEW_REGISTRY_REL}`);
+  }
+
   const smokePath = path.join(projectDir, SMOKE_REL);
   if (fs.existsSync(smokePath)) {
     fs.writeFileSync(smokePath, renderSmokeYaml(infos));

package/src/lib/verify.mjs

@@ -66,8 +66,15 @@ export async function runVerify({ projectDir, manifest, config, dryRun = false }
       results.push({ platform: item.platform, command: item.command, code: 0, ran: false });
       continue;
     }
+    const startedAt = Date.now();
     const { code } = await runCommand(item.command, projectDir);
-    results.push({ platform: item.platform, command: item.command, code, ran: true });
+    results.push({
+      platform: item.platform,
+      command: item.command,
+      code,
+      ran: true,
+      durationMs: Date.now() - startedAt,
+    });
     if (code !== 0) green = false;
   }
 
@@ -94,4 +101,20 @@ export function printVerifyVerdict(verdict) {
       ? `\n${colors.green("GREEN — build proven.")}\n`
       : `\n${colors.red("FAIL — build did not go green.")}\n`
   );
+
+  // Machine-readable verdict, one greppable line (field-report finding 2.3):
+  // a verify run can exceed 170k log lines, where "-Werror=" clang flags and
+  // Xcode phase names false-positive naive error greps. Agents anchor on this
+  // marker instead of parsing raw Gradle/xcodebuild output.
+  process.stdout.write(
+    `::create-cmp-verdict::${JSON.stringify({
+      green: verdict.green,
+      results: verdict.results.map((r) => ({
+        platform: r.platform,
+        green: r.code === 0,
+        ran: r.ran,
+        durationMs: r.durationMs ?? null,
+      })),
+    })}\n`
+  );
 }

package/src/scaffold.mjs

@@ -205,6 +205,46 @@ function applyAppNameSlug(projectDir, appName) {
   }
 }
 
+/**
+ * Persist the fully-resolved engine config as `create-cmp.json` in the project
+ * root — the durable spec-of-record (field-report finding 5.5-1 / D6). The
+ * conformance/consistency tooling compares code against whatever this file
+ * currently says, so a hand-edit is a visible spec change rather than drift.
+ * @param {string} projectDir
+ * @param {object} config validated engine config
+ */
+function writeSpecOfRecord(projectDir, config) {
+  let engineVersion = "unknown";
+  try {
+    engineVersion = JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, "package.json"), "utf8")
+    ).version;
+  } catch {
+    /* best-effort — never fail the stamp over version metadata */
+  }
+  const record = {
+    schemaVersion: 1,
+    name: config.appName,
+    package: config.package,
+    bundleId: config.iosBundleId,
+    themePrefix: config.themePrefix,
+    region: config.region,
+    platforms: config.platforms,
+    firebase: config.firebase,
+    room: config.room,
+    e2e: config.e2e,
+    inspector: config.inspector,
+    devClient: config.devClient,
+    tabs: config.tabs,
+    engineVersion,
+    stampedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(
+    path.join(projectDir, "create-cmp.json"),
+    JSON.stringify(record, null, 2) + "\n"
+  );
+}
+
 /**
  * Run the full scaffold pipeline.
  * @param {object} config engine config object (CONTRACT)
@@ -231,10 +271,20 @@ export async function scaffold(config, opts = {}) {
 
   const projectDir = path.resolve(config.targetDir);
   if (fs.existsSync(projectDir)) {
+    // Harmless entries must not force `--force`: our own doctor/session
+    // droppings (.claude), VCS metadata, and OS/editor noise. The documented
+    // doctor→create flow used to poison its own target dir this way. Anything
+    // else is real user content and still refuses — naming the offenders so
+    // the caller can decide without an `ls` round-trip.
+    const HARMLESS = new Set([".git", ".claude", ".DS_Store", ".idea", ".vscode"]);
     const entries = fs.readdirSync(projectDir).filter((e) => e !== "." && e !== "..");
-    if (entries.length > 0 && !opts.force) {
+    const blocking = entries.filter((e) => !HARMLESS.has(e) && !e.endsWith(".swp"));
+    if (blocking.length > 0 && !opts.force) {
+      const ignored = entries.filter((e) => !blocking.includes(e));
       throw new Error(
-        `target directory ${projectDir} is not empty (pass force to overwrite)`
+        `target directory ${projectDir} is not empty (pass force to overwrite)\n` +
+          `  Blocking entries: ${blocking.join(", ")}` +
+          (ignored.length > 0 ? `\n  (ignored as harmless: ${ignored.join(", ")})` : "")
       );
     }
   }
@@ -322,6 +372,14 @@ export async function scaffold(config, opts = {}) {
     if (fs.existsSync(abs)) fs.rmSync(abs);
   }
 
+  // Persist the resolved config as the project's spec-of-record. Until now the
+  // config was validated, consumed, and discarded — the only pre-code spec in
+  // the system evaporated at stamp time, so nothing could later answer "was
+  // this app built to its spec?" (tabs ↔ AppTab ↔ smoke consistency, upgrade
+  // intent, re-stamp/resume all need it). Committed with the app; hand-edits
+  // are visible spec changes, not drift.
+  writeSpecOfRecord(projectDir, config);
+
   ok("Scaffold complete.");
 
   // (f) verify gate

package/template/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent instructions
+
+This repository is agent-first. The full working contract — the definition of done
+(`node qa/verify.mjs` must PASS), the architecture gates, the testing pyramid, and the
+device-free **UI feedback loop** (render every real screen headlessly and see exactly
+what your edit changed) — lives in [CLAUDE.md](./CLAUDE.md).
+
+Read CLAUDE.md before making changes. It applies to every coding agent, not only Claude.

package/template/CLAUDE.md

@@ -52,6 +52,38 @@ invariants the conformance gates enforce.
 Commit it with your change — git history is the audit ledger. Binary artifacts under
 `qa-artifacts/` are hashed into the receipt; never commit them.
 
+## UI feedback loop — see what you build, without a device
+
+<!-- >>> cmp:feature inspector -->
+While building or changing ANY screen, use the preview loop instead of an emulator: it
+renders this app's REAL screens (real DI, real theme, seeded data) headlessly in seconds
+and tells you exactly what your edit changed.
+
+**With the create-cmp plugin (cmp-inspector MCP tools):**
+
+1. `preview { projectDir }` — once per session. Returns a live gallery URL (give it to
+   the human; it re-renders itself on every save) plus per-screen structural summaries
+   for you. Sources are watched; you never run Gradle by hand.
+2. After each edit: `preview_status { waitForRender: true }` — blocks until the
+   render/compile outcome. `changedLastRender` names the screens your edit touched
+   (empty = the edit reached no screen); `lastErrorSource: "compile"` means the edit
+   didn't even build (the compiler's `e:` lines are in `lastError`).
+3. `preview_diff { screen }` — one call proves the change: verdict `proven-clean` /
+   `changed-with-regressions` / `no-change`. No snapshot bookkeeping needed.
+
+**Without the plugin:** `./gradlew :composeApp:renderScreens` renders every screen to
+`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"`).
+Assert on the `tree.json` structure; never read PNG bytes (pixels are for humans).
+<!-- <<< cmp:feature inspector -->
+<!-- >>> cmp:feature dev-client -->
+For one interactive window instead of stills of every screen:
+`./gradlew :composeApp:hotRunDesktop --auto` (Compose Hot Reload dev-client).
+<!-- <<< cmp:feature dev-client -->
+
 ## Docs
 
 [`README.md`](./README.md) (front page) · [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)

package/template/README.md

@@ -17,6 +17,11 @@ follow the contract in [`CLAUDE.md`](./CLAUDE.md).
 ./gradlew :composeApp:hotRunDesktop --auto
 <!-- <<< cmp:feature dev-client -->
 
+<!-- >>> cmp:feature inspector -->
+# Preview EVERY screen headlessly — no device, no emulator (agents: CLAUDE.md "UI feedback loop")
+./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs
+<!-- <<< cmp:feature inspector -->
+
 # Unit tests (fast inner loop)
 ./gradlew :composeApp:desktopTest
 

package/template/composeApp/build.gradle.kts

@@ -136,6 +136,13 @@ kotlin {
                 implementation(compose.desktop.currentOs)
                 implementation(libs.kotlinx.coroutines.swing)
                 implementation(libs.ktor.client.cio)
+                // >>> cmp:feature inspector
+                // Headless semantics API (runDesktopComposeUiTest / onRoot) for the preview
+                // harness (inspector/PreviewHarness.kt) — renders real screens with no window.
+                // Desktop is a dev-only target, so shipping the test artifact here is deliberate.
+                @OptIn(org.jetbrains.compose.ExperimentalComposeLibrary::class)
+                implementation(compose.uiTest)
+                // <<< cmp:feature inspector
             }
         }
 
@@ -250,7 +257,19 @@ compose.resources {
 
 // >>> cmp:feature room
 room {
-    schemaDirectory("$projectDir/schemas")
+    // Per-target schema directories, NOT one shared dir. With a single directory the
+    // copyRoomSchemas aggregation task requires every target's exported schema to be
+    // byte-identical — and the first entity edit after scaffold trips a cross-target
+    // checksum conflict against the stale intermediate of whichever target built last
+    // ("Inconsistency detected exporting Room schema files"). Per-target locations are
+    // exactly what that error's remediation asks for.
+    schemaDirectory("android", "$projectDir/schemas/android")
+    schemaDirectory("desktop", "$projectDir/schemas/desktop")
+    // >>> cmp:feature ios
+    schemaDirectory("iosSimulatorArm64", "$projectDir/schemas/iosSimulatorArm64")
+    schemaDirectory("iosX64", "$projectDir/schemas/iosX64")
+    schemaDirectory("iosArm64", "$projectDir/schemas/iosArm64")
+    // <<< cmp:feature ios
 }
 // <<< cmp:feature room
 
@@ -263,6 +282,52 @@ compose.desktop {
 }
 // <<< cmp:feature dev-client
 
+// >>> cmp:feature inspector
+// Headless screen previews — the project-wired tier-0 loop of the create-cmp inspector.
+// Renders every screen in inspector/PreviewRegistry.kt (real DI, real theme, real data)
+// to build/previews/<id>/{screen.png, tree.json} with NO device, emulator, or window,
+// then qa/preview-gallery.mjs turns the output into one self-contained index.html:
+//
+//   ./gradlew :composeApp:renderScreens                      # all screens
+//   ./gradlew :composeApp:renderScreens -Pscreen=home        # one screen
+//   node qa/preview-gallery.mjs                              # build the gallery
+//
+// Parameters travel as -P properties -> system properties, NEVER via --args (Gradle's CLI
+// parsing splits space-separated --args values into task names).
+tasks.register<JavaExec>("renderScreens") {
+    group = "verification"
+    description = "Render registered screens headlessly to PNG + inspector-contract tree JSON."
+    val desktopCompilation = kotlin.targets.getByName("desktop").compilations.getByName("main")
+    classpath(desktopCompilation.output.allOutputs, desktopCompilation.runtimeDependencyFiles)
+    mainClass.set("__PACKAGE__.inspector.PreviewHarnessKt")
+    systemProperty("java.awt.headless", "true")
+    systemProperty("screen", providers.gradleProperty("screen").getOrElse("all"))
+    systemProperty(
+        "out",
+        providers.gradleProperty("previewOut")
+            .getOrElse(layout.buildDirectory.dir("previews").get().asFile.absolutePath),
+    )
+    systemProperty("pngScale", providers.gradleProperty("pngScale").getOrElse("2"))
+}
+
+// Resident preview daemon (phase 2): a long-lived headless JVM serving /render on
+// 127.0.0.1:9601 so warm re-renders skip the task cycle. Preferred launch is under
+// Compose Hot Reload (saves hot-swap into the running daemon; needs the dev-client
+// feature's Compose Hot Reload plugin):
+//
+//   ./gradlew :composeApp:hotRunDesktop --mainClass=__PACKAGE__.inspector.PreviewDaemonKt --auto
+//
+// This plain variant runs on any JDK with no hot swap (restart to pick up new code):
+tasks.register<JavaExec>("runPreviewDaemon") {
+    group = "verification"
+    description = "Run the resident preview daemon (loopback HTTP /render, no hot reload)."
+    val desktopCompilation = kotlin.targets.getByName("desktop").compilations.getByName("main")
+    classpath(desktopCompilation.output.allOutputs, desktopCompilation.runtimeDependencyFiles)
+    mainClass.set("__PACKAGE__.inspector.PreviewDaemonKt")
+    systemProperty("java.awt.headless", "true")
+}
+// <<< cmp:feature inspector
+
 // Evidence integrity: golden-tree baselines (qa/golden) and the UPDATE_GOLDEN capture flag are
 // REAL inputs of the JVM test tier, but Gradle can't see either on its own — baselines are read
 // at runtime, not compiled, and env vars aren't tracked. Undeclared, the build cache will happily

package/template/composeApp/src/commonMain/kotlin/com/example/app/core/format/Format.kt

@@ -0,0 +1,36 @@
+package __PACKAGE__.core.format
+
+/**
+ * KMP-safe formatting helpers.
+ *
+ * `String.format` / `"%02d".format(...)` are JVM-only — they compile in `androidMain` but do
+ * not exist in `commonMain`, and reaching for them is the single most common first-week
+ * porting mistake in a shared module. These cover the cases that actually come up; add here
+ * rather than sprinkling `padStart` call sites.
+ */
+
+/** Pad an Int to two digits: 7 -> "07". The `%02d` you were about to write. */
+fun pad2(n: Int): String = n.toString().padStart(2, '0')
+
+/** "HH:mm" from minutes-since-midnight: 555 -> "09:15". */
+fun clockLabel(minutesOfDay: Int): String {
+    val m = ((minutesOfDay % (24 * 60)) + 24 * 60) % (24 * 60) // wrap + never negative
+    return "${pad2(m / 60)}:${pad2(m % 60)}"
+}
+
+/**
+ * Fixed decimal places without java.text: 12.5 -> "12.5" (1 dp). Rounds half away from zero
+ * via floor(abs + 0.5) — deterministic on every backend (kotlin.math.round's tie behavior and
+ * `%.Nf` locale handling both vary). For layout-stable numeric UI text, not accounting math.
+ */
+fun fixed(value: Double, decimals: Int = 1): String {
+    require(decimals >= 0) { "decimals must be >= 0" }
+    var factor = 1L
+    repeat(decimals) { factor *= 10 }
+    val scaled = kotlin.math.floor(kotlin.math.abs(value) * factor + 0.5).toLong()
+    val sign = if (value < 0 && scaled != 0L) "-" else ""
+    if (decimals == 0) return "$sign$scaled"
+    val whole = scaled / factor
+    val frac = (scaled % factor).toString().padStart(decimals, '0')
+    return "$sign$whole.$frac"
+}

package/template/composeApp/src/commonTest/kotlin/com/example/app/core/format/FormatTest.kt

@@ -0,0 +1,36 @@
+package __PACKAGE__.core.format
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class FormatTest {
+
+    @Test
+    fun pad2_pads_single_digits() {
+        assertEquals("07", pad2(7))
+        assertEquals("00", pad2(0))
+        assertEquals("15", pad2(15))
+    }
+
+    @Test
+    fun clockLabel_formats_minutes_of_day() {
+        assertEquals("09:15", clockLabel(9 * 60 + 15))
+        assertEquals("00:00", clockLabel(0))
+        assertEquals("23:59", clockLabel(23 * 60 + 59))
+        // wraps past midnight and never goes negative
+        assertEquals("00:30", clockLabel(24 * 60 + 30))
+        assertEquals("23:30", clockLabel(-30))
+    }
+
+    @Test
+    fun fixed_renders_stable_decimals() {
+        // Binary-exact inputs only — 0.1-style values are not representable and would make
+        // these assertions depend on the platform's double formatting.
+        assertEquals("12.5", fixed(12.5, 1))
+        assertEquals("0.3", fixed(0.25, 1)) // half rounds away from zero
+        assertEquals("-0.8", fixed(-0.75, 1))
+        assertEquals("3.00", fixed(3.0, 2))
+        assertEquals("13", fixed(12.5, 0))
+        assertEquals("0.0", fixed(0.0, 1))
+    }
+}