create-cmp-cli 0.3.1 → 0.4.0

package/README.md

@@ -2,56 +2,63 @@
 
 # create-cmp
 
-**The AI delivery harness for Kotlin/Compose Multiplatform — scaffold a green-building app (Android + iOS) in minutes, with best practices your AI is mechanically held to.**
+**The AI delivery harness for Kotlin/Compose Multiplatform.**
 
-Toolchain auto-bootstrapped · Navigation & insets pre-solved · Clean Architecture wired · Test pyramid + E2E flows included · AI-native inspector & verification lane.
+Scaffold a green-building Android + iOS app in minutes — then let AI extend it, held to a
+machine-enforced definition of done.
 
 [![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)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 [![Kotlin Multiplatform](https://img.shields.io/badge/Kotlin-Multiplatform-7F52FF.svg?logo=kotlin&logoColor=white)](https://kotlinlang.org/docs/multiplatform.html)
-[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757.svg)](#use-it-from-claude-code)
+[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757.svg)](#the-claude-code-plugin-8-skills)
 
 </div>
 
 ---
 
-Starting a Compose Multiplatform project is slow and flaky — not because the knowledge is hard, but
-because it isn't *reproducible*. Kotlin ↔ KSP ↔ CMP ↔ Room ↔ AGP must all agree or the build dies;
-the iOS shell (XcodeGen + CocoaPods + Firebase pods + AppDelegate + framework embedding) is a
-multi-step minefield; edge-to-edge insets get re-debugged on every project; and the toolchain itself
-is a cliff most scaffolders leave to you. That friction is why greenfield mobile apps quietly default
-to React Native.
-
-**`create-cmp` removes the friction.** It *stamps* a frozen, CI-verified golden template (it does not
-freehand-generate your project), bootstraps the toolchain, and **proves a green build** before it
-reports success.
-
-And it goes further than scaffolding: `create-cmp` is an **AI delivery harness**. In the age of
-AI-driven development, the scarce thing isn't code — it's a machine-enforceable definition of
-*correct*. Every generated project ships the architecture patterns as running exemplars (with
-tests), the best practices as executable conformance checks, generation tools so the AI extends
-the app right-by-construction, an AI-native structural inspector, and a verification lane that
-refuses "done" without evidence. See [`docs/HARNESS-PLAN.md`](./docs/HARNESS-PLAN.md) for the
-full product definition.
-
-## Contents
-
-- [Quick start](#quick-start)
-- [Commands](#commands)
-- [What you get](#what-you-get-the-pre-solved-moat)
-- [Options](#options)
-- [Use it from Claude Code](#use-it-from-claude-code)
-- [Why CMP, not React Native](#why-cmp-not-react-native)
-- [How it works](#how-it-works)
-- [Requirements](#requirements)
-- [Roadmap](#roadmap)
-- [Contributing](#contributing)
-
-> **Full usage in one place:** [`docs/USAGE.md`](./docs/USAGE.md) is the single entry point — setup,
-> every CLI command, all 8 skills, the 14-tool `cmp-inspector` MCP, and the workflows that tie them
-> together. Read it and you can drive create-cmp end to end (agents included).
+```bash
+npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --verify
+```
+
+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).
+
+## What is this, in plain words
+
+**Day one, it's a scaffolder.** One command gives you a working Compose Multiplatform app —
+Android and iOS, navigation and insets solved, Clean Architecture wired, tests passing, build
+green. It *stamps* a frozen, CI-verified template; it never asks an AI to freehand your project,
+so every scaffold is identical and every scaffold builds.
+
+**Every day after, it's a harness.** AI writes code fast, and confidently — including confidently
+wrong. The scarce thing is no longer code; it's a **machine-checkable definition of "correct"**.
+Every project this tool generates carries that definition inside it: behavior specs, an
+executable verify lane, generators that extend the app the right way by construction, and
+enforcement that refuses "done" without evidence. An AI session working in your repo doesn't
+*promise* the feature works — it has to *prove* it, and it gets blocked when it can't.
+
+**See it live:** [create-cmp-showcase](https://github.com/kvdm-co-pilot/create-cmp-showcase) is a
+public repo built entirely by this tool — every commit carries its evidence receipt, and
+[PR #1](https://github.com/kvdm-co-pilot/create-cmp-showcase/pull/1) shows the harness *refusing*
+a bad change and naming the exact rule it broke.
+
+## The core loop
+
+```
+  spec clause  →  generate from exemplar  →  verify lane (8 gates)  →  evidence receipt
+      ↑                                                                      │
+      └────────────── enforcement: Stop hook + CI refuse "done" without it ──┘
+```
+
+Behavior starts as a written spec clause. Code is cloned from a proven exemplar. The verify lane
+checks everything — spec coverage, build, tests, architecture, UI structure, design tokens,
+accessibility, on-device E2E — and writes a receipt bound to a content hash of the code it
+verified. The Stop hook and CI both check that receipt. You cannot hand-forge it, and a stale one
+doesn't pass.
 
 ## Quick start
 
@@ -62,208 +69,243 @@ npx create-cmp-cli@latest
 …or non-interactively:
 
 ```bash
-npx create-cmp-cli@latest --name Acme --package com.acme.app --yes --verify
+npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --verify
 ```
 
-The scaffolder interviews you (or takes flags), runs the toolchain doctor, stamps the template, and
-builds the app to prove it's green.
+It interviews you (or takes flags), checks your toolchain, stamps the template, and **builds the
+app to prove it's green** before reporting success.
 
-> **On the package name:** it publishes as `create-cmp-cli` — the bare name `create-cmp` is held by
-> an unrelated placeholder, and `create-cmp-app` is a real, unrelated CMP generator, so we didn't
-> reuse either. The installed *command* is still `create-cmp`. You can also run straight from GitHub
-> with no install: `npx github:kvdm-co-pilot/create-cmp`, or use the
-> [Claude Code plugin](#use-it-from-claude-code).
+> **Name note:** the npm package is `create-cmp-cli` (the bare `create-cmp` name was already
+> squatted); the installed command is still `create-cmp`.
 
-## Commands
+---
 
-`create-cmp` is useful across the whole life of a project, not just day one — and every command
-except `create` works on **any** KMP project, not only ones it scaffolded:
+# The features, one by one
 
-| Command | What it does |
-|---|---|
-| `create-cmp [dir]` / `create-cmp create` | Scaffold a new app from the frozen golden template (the default command). |
-| `create-cmp doctor [--fix]` | Toolchain preflight (JDK/SDK/Xcode/Appium — legacy driver install for the pre-Maestro path, consent-gated installs) **plus** project diagnosis when run inside a Gradle project: kotlin↔ksp lockstep, drift vs proven-green sets, the KSP2/iOS catch-22, sdk.dir, `~/.konan` bloat, disk space. `--fix` applies the safe heals. |
-| `create-cmp upgrade [--dry-run]` | Migrate `gradle/libs.versions.toml` to the next proven-green version set — diff table first, surgical in-place edits with `.bak-upgrade` backups, kotlin↔ksp lockstep guardrail, `--verify` to prove the result. |
-| `create-cmp clean` | Cache & build-output hygiene: stale `~/.konan` toolchains + project `build/`/`.gradle/` dirs (sizes shown, consent-gated); `~/.gradle/caches` is size-reported only. |
-| `create-cmp verify [--target-dir .]` | Run the green-build gate (Android, and iOS on macOS) against an existing project. |
-
-> **North-star (a goal, measured honestly — not a benchmark):** *time-to-green* — a running app on
-> the Android emulator **and** the iOS simulator, smoke-passing, with zero manual steps modulo the
-> one Xcode App Store install. Target: **under 5 minutes on a clean machine.** Every scaffold ends
-> with a `--verify` build gate, so success is *proven*, not assumed.
-
-## What you get (the pre-solved moat)
-
-Everything below is **stamped from a template that builds green on Android + iOS** — not regenerated
-per run, so it can't silently drift:
-
-- **A pinned, version-locked dependency set** — Kotlin, KSP, Compose Multiplatform, Room, AGP, Koin,
-  Ktor, GitLive Firebase KMP, Navigation Compose, Lifecycle — chosen to actually agree with each
-  other, including the iOS Room/KSP2 catch-22 (`ksp.useKSP2=true`). Frozen and CI-gated.
-- **The iOS shell, in the order that builds** — `project.yml` (XcodeGen), `Podfile` (Firebase static
-  linkage), `Info.plist`, `iOSApp.swift` (AppDelegate + `FirebaseApp.configure()` before Koin),
-  `ContentView.swift` (ComposeUIViewController bridge).
-- **The Android shell** — `AndroidManifest`, `MainActivity` with `enableEdgeToEdge()`, `Application`
-  starting Koin + Room, adaptive-icon structure.
-- **Navigation + insets, solved once** — a generic `BaseScreen` Scaffold owning window insets /
-  status- and nav-bar padding, plus a data-driven `AppShell` + bottom nav fed by your `tabs` list
-  (not role-hardcoded), with type-safe routes.
-- **Clean Architecture, wired** — `core / data{local,remote} / domain{model,repository,usecase} /
-  presentation{components,theme,navigation,<feature>} / di` with Koin modules registered and **one
-  example feature wired end-to-end** as the copy-paste pattern.
-- **Theme & tokens** — `<Prefix>Theme`, `<Prefix>Tokens`, `<Prefix>Colors`, DM Sans.
-- **The test pyramid, pre-built** — unit exemplars (Turbine + fakes), dependency-free architecture
-  conformance gates, Compose UI Tests, golden-tree structural baselines, and Maestro E2E flows —
-  bound to a committed behavior spec (`specs/*.spec.md`, Given/When/Then, stable clause ids) so a
-  `specCoverage` gate catches untested or untraceable behavior — plus the verify lane
-  (`qa/verify.mjs`) that runs it all and emits a typed PASS/FAIL/SKIP verdict + evidence receipt.
-- **Extend it with Claude Code, no plugin required** — every generated project ships its own
-  `add-feature`/`add-screen`/`add-repository` skills (backed by the deterministic
-  `qa/scaffold-feature.mjs` stamper) that clone the exemplar feature end-to-end: Screen →
-  ViewModel → UseCase → Repository → DI → nav, tests at every layer, golden baseline included.
-- **Mechanically enforced, not honor-system** — a generated `.claude/settings.json` Stop hook
-  refuses "done" unless a fresh, evidence-bound PASS receipt covers the changed surface (content-
-  hash bound, rebase/merge-proof), and CI independently re-checks the committed receipt still
-  attests `HEAD`. Proven against real violations: hardcoded colors, illegal layer imports, deleted
-  spec tests, and structural regressions are each refused and named by clause, 4/4 in the
-  repo's refusal-demo script.
-- **A toolchain doctor** — diagnoses *and* heals JDK, Android SDK + AVD, Xcode/CLT, CocoaPods,
-  XcodeGen, Appium + drivers (the legacy pre-Maestro path), Node. Idempotent, OS-aware, consent-gated.
-  The E2E flows themselves run on Maestro — install with
-  `curl -fsSL https://get.maestro.mobile.dev | bash`.
-- **AI-inspectable by default** — every generated app ships a debug-only live inspector
-  (`127.0.0.1:9500`, loopback, structurally absent from release). An agent runs `connect_live` and
-  reads the running UI as JSON — hierarchy, geometry, resolved design tokens, real navigation
-  state. Never screenshots. Toggle with `--no-inspector`; `create-cmp doctor` verifies it stays
-  debug-only and that every declared theme token is served on `/inspect/design-system`.
-- **Live device view** — with the debug app running, open `http://127.0.0.1:9500/inspect/remote`
-  (after `adb forward tcp:9500 tcp:9500`) to watch the real device and click the image to tap it,
-  while the agent drives `navigate_and_inspect` on the semantics tree and proves every change with
-  `prove_change`. Pixels for the human, structure for the AI.
-- **Desktop dev-client** — a phone-sized JVM window running the shared UI with Compose Hot Reload
-  attached (`./gradlew :composeApp:hotRunDesktop --auto`); Firebase never initializes on desktop
-  (offline DI fakes). Toggle with `--no-dev-client`.
-
-`google-services.json` / `GoogleService-Info.plist` are intentionally **not** real — you get
-placeholders and clear "drop your Firebase config here" instructions.
+Three surfaces: the **CLI**, the **Claude Code plugin**, and — most importantly — **what every
+generated project carries inside it**.
 
-## Options
+## The CLI (5 commands)
 
-| Option | Choices | Default |
-|---|---|---|
-| Platforms | Android (always) + iOS | iOS on |
-| App name / package / iOS bundle id | — | required / derived |
-| Firebase region | any Firebase region | `us-central1` |
-| Firebase (GitLive KMP) | on / off | on |
-| Auth | `email` / `phone` / `both` / `none` | `both` |
-| Firebase services | Firestore · Storage · Functions · FCM | all on |
-| Room local cache | on / off | on |
-| E2E flows (Maestro) | on / off | on |
-| Bottom-nav tabs | label + icon, any count | Home, Profile |
+Everything except `create` works on **any** KMP project, not just ones this tool made.
 
-_(Web/PWA is intentionally out of scope — Android + iOS only.)_
+| Command | Plain-speech: what it does |
+|---|---|
+| `create-cmp [dir]` | Makes a new app. Asks questions (or takes flags), stamps the template, renames everything to your package, removes features you turned off, builds it, tells you GREEN or FAIL. |
+| `create-cmp doctor [--fix]` | Checks your machine (JDK, Android SDK, emulator, Xcode, CocoaPods, XcodeGen, Node) **and** your project (do Kotlin and KSP versions agree? is the version catalog drifting? is `~/.konan` eating your disk?). `--fix` applies safe repairs — always asking first. |
+| `create-cmp upgrade [--dry-run]` | Moves your `libs.versions.toml` to the next **proven-green** version set. Shows a diff first, edits surgically with backups, guards the Kotlin↔KSP lockstep, and can re-verify the build after. |
+| `create-cmp clean` | Reclaims disk: stale Kotlin/Native toolchains, `build/` dirs. Shows sizes, asks before deleting. |
+| `create-cmp verify` | Runs the green-build gate against an existing project. Exit 0 = green. Useful in scripts and CI. |
 
-## Use it from Claude Code
+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.
 
-`create-cmp` also ships as a [Claude Code](https://docs.claude.com/en/docs/claude-code) plugin — one
-shared engine, two front doors. Install from the bundled marketplace:
+## The Claude Code plugin (8 skills)
 
 ```text
 /plugin marketplace add kvdm-co-pilot/create-cmp
 /plugin install create-cmp
 ```
 
-No `/plugin` UI available (headless/non-interactive sessions)? See
-[the settings.json fallback in `docs/USAGE.md`](./docs/USAGE.md#2-setup) — it's a real two-step
-install (marketplace registration, then plugin install), not a one-line tweak.
-
-It bundles eight skills (plus the `cmp-inspector` MCP server), each with a deterministic engine
-behind it:
-
-- **cmp-new** — conversational interview, then shells out to the same engine to scaffold, and
-  generates your tab screens from the example-feature pattern.
-- **cmp-doctor** — toolchain bootstrap + project diagnosis on any KMP project (consent-gated).
-- **cmp-upgrade** — migrate to the next proven-green version set (diff → apply → verify).
-- **cmp-inspect** — see and drive a rendered Compose UI as structured JSON: hierarchy, geometry,
-  resolved design tokens, drift diffs, golden-tree snapshots, a11y audit, live navigation
-  (`navigate_and_inspect`), wireframe rendering, and `prove_change` — the verified dev loop.
-- **cmp-dev-client** — run the shared UI in a phone-sized desktop window with Compose Hot Reload
-  (`./gradlew :composeApp:hotRunDesktop --auto`) — the Expo-style dev loop for KMP.
-- **cmp-firebase-connect** — post-scaffold onboarding: create/reuse a Firebase project, register
-  the app, and replace the placeholder config via the Firebase CLI (consent-gated), proven by a
-  green build.
-- **cmp-test** — generate the regression suite by *observing* the app: read the running UI's
-  semantics tree and emit Maestro E2E flows plus golden-tree snapshots in the shipped harness style.
-- **cmp-qa-prep** — brings up the emulator + Maestro flow run + smoke (legacy Appium bring-up
-  path also supported).
+Same engine as the CLI, conversational front door. Each skill is a guided flow, not a wrapper:
 
-## Why CMP, not React Native
+| Skill | Plain-speech: what it does |
+|---|---|
+| `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-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. |
 
-This isn't a knock on React Native — it's about defaults. The only place CMP loses to RN on a new
-app is **time-to-first-green-build**, and that's a tooling problem, not a merits problem. With
-`create-cmp`, CMP's `npx`-and-go is competitive:
+Plus the **`cmp-inspector` MCP server** (14 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.
 
-- **One language, real native UI.** Kotlin shared logic *and* Compose UI across Android and iOS — no
-  JS bridge, no separate native-module dance for the common case.
-- **Native performance and platform access** without the RN bridge tax.
-- **Reproducible by construction.** A frozen, version-locked, CI-gated template means the build that
-  was green yesterday is green today — the exact property ad-hoc CMP setups lack.
-- **Proven, not assumed.** Every scaffold ends on the verify lane — real build + the full JVM
-  test tier — with a typed GREEN/FAIL verdict and an evidence receipt.
+## What every generated project carries (the harness itself)
 
-If `create-next-app` made React the default for the web by removing setup friction, the goal here is
-the same for multiplatform mobile.
+This is the product. Delete the plugin, uninstall the CLI — your generated repo keeps all of it.
 
-## How it works
+### 1. Specs — behavior is written down first
+`specs/*.spec.md` — plain Given/When/Then clauses with stable ids (`HOME-01`, `ARCH-05`). New
+behavior starts as a clause; durable tests cite their clause (`// SPEC: HOME-02`). The `home`
+feature ships as the fully-cited example.
 
-```
-Front doors:  npx create-cmp-cli   +   Claude Code plugin (cmp-new / cmp-doctor / cmp-qa-prep)
-                                  │  one shared engine, two front doors
-Engine (Node, deterministic):     copy → token-replace → rename packages → toggle features → VERIFY
-Golden template (frozen, CI'd):   pinned versions · iOS shell · nav+insets · Clean Arch · DI · test pyramid
-```
+### 2. The verify lane — one command, eight gates
+`node qa/verify.mjs` runs everything and writes a typed PASS/FAIL/SKIP receipt:
 
-The engine never puts an LLM in the hot path: it copies the template, replaces placeholders in file
-contents *and* paths, atomically renames package directories, toggles features (Firebase / auth type
-/ Room / the e2e harness — feature key `e2e`, renamed from `appium` in 0.3.0; the old
-`--no-appium` flag still works as a deprecated alias), and runs the verify
-build. Determinism is the moat. See
-[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full design, and
-[`docs/DOCUMENTATION.md`](./docs/DOCUMENTATION.md) for the map of every doc — what's
-authoritative for what, and the standards each implements.
+| Gate | Plain-speech: what it catches |
+|---|---|
+| `specCoverage` | Behavior nobody tests, and test citations pointing at nothing. Every clause needs a test; every citation needs a clause. |
+| `build` | The app doesn't compile. |
+| `unitTests` | A behavior broke. ViewModels/UseCases/Repositories, tested with hand-written fakes. |
+| `conformance` | Architecture violations, **named by rule**: UI importing the data layer, hardcoded colors outside the theme, a screen without a ViewModel test. |
+| `goldenTrees` | A screen's *structure* changed when you didn't mean it to. Compares the rendered semantics tree against a committed baseline — no pixels, no flake. |
+| `tokenDrift` | The running app's design tokens drifting from the declared catalog — queried live from the debug inspector. Hardcode a color and it shows up here too. |
+| `a11y` | Missing content descriptions, undersized touch targets. |
+| `e2eSmoke` | The app doesn't actually boot and navigate on a device. Real Maestro run, hardened for slow emulators. |
+
+No device attached? Device-dependent gates record an honest **SKIP** — never a fake green.
+
+### 3. Evidence — receipts you can't forge
+The lane writes `qa/evidence/latest.json`: verdict, per-gate results, durations, and an
+`inputs.hash` — a content hash of every file that could affect the verdict. You commit the
+receipt with your change; git history becomes the audit ledger. Because validity is a *content*
+hash (not a commit SHA), rebases and merges don't invalidate honest receipts — but editing the
+verdict by hand, or reusing a stale receipt, fails immediately. The lane also forces test
+*execution* (`--rerun`), so a receipt can never launder a cached result from a different tree.
+
+### 4. Enforcement — "done" is mechanical, not honor-system
+- **Stop hook** (`.claude/settings.json`): when an AI session tries to end, it re-hashes the
+  verified surface and compares against the committed receipt. Changed code without a fresh PASS
+  receipt → the session is blocked, with the reason. Costs milliseconds (hashing only). Doc-only
+  edits never trigger it — enforcement is transparent, not hostile.
+- **CI receipt gate** (`.github/workflows/verify.yml`): every push re-checks that the committed
+  receipt attests `HEAD`, then independently re-runs the whole lane.
+- **The refusal demo** (`node qa/refusal-demo.mjs`): four staged violations — hardcoded color,
+  illegal layer import, deleted spec test, structural regression — each caught and **named by
+  clause**, 4/4. Run it to watch the harness say no.
+
+### 5. In-project generators — extend without the plugin
+Three skills ship *inside* the generated repo (`.claude/skills/`), backed by a deterministic
+stamper (`qa/scaffold-feature.mjs`):
+
+- **`add-feature`** — a full vertical slice cloned from the `home` exemplar: Screen → ViewModel →
+  UseCase → Repository → DI → nav route, **with tests at every layer** and a golden baseline slot.
+- **`add-screen`** — presentation only, for an entity whose data layer already exists.
+- **`add-repository`** — data/domain only: model, repository interface + impl, use case, fake.
+
+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.
+
+### 7. The daily-driver extras
+- **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
+  session in the repo must follow.
+
+---
+
+# Workflows — how it fits together
+
+**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 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
+a verdict. The agent doesn't say "I centered the title" — it shows *"title bounds moved, tokens
+unchanged, no a11y regressions: proven clean."*
+
+**Add a feature with AI (no plugin).** Ask any Claude Code session for a feature → it reads
+`CLAUDE.md` → proposes the spec clause first → runs `add-feature` → runs the lane → commits code
++ receipt together. If it violates the architecture, the gates name the broken rule; if it tries
+to stop early, the Stop hook blocks it.
+
+**Tests that write themselves.** `cmp-test` reads the running app's semantics tree and emits the
+regression suite — existence, interaction, navigation, golden trees — in the shipped harness style.
+
+**Maintenance, for the life of the repo.** `doctor` when anything misbehaves, `upgrade` when you
+want newer versions without the version-matrix gamble, `clean` when disk fills, `verify` as the
+standalone gate. All of it works on any KMP project.
+
+## Agent flows — who does what
+
+- **A plain AI session** in a generated repo is the common case: the contract (`CLAUDE.md`), the
+  generators, the lane, and the hook are all local files — the session follows the loop above
+  with nothing installed.
+- **The `cmp-orchestrator` agent** (ships with the plugin) splits bigger jobs: it delegates
+  generation and mechanical work to sub-agents with self-contained briefs, then **gates every
+  hand-off through the verify lane** before accepting it. Nothing is reported done on prose —
+  only on a receipt.
+- **The MCP tools** are how any agent *sees*: `inspect_tree`, `get_node`, `assert_token`,
+  `layout_gaps`, `diff_against_design_system`, `find_drift`, `snapshot_save`, `snapshot_diff`,
+  `audit_a11y`, `connect_live`, `navigate_and_inspect`, `render_tree`, `render_screen`,
+  `prove_change`. Structure in, structure out — never pixels in model context.
+
+## The philosophy (why it's built this way)
+
+1. **Stamp, don't generate.** The skeleton comes from a frozen, CI-verified template. LLMs are
+   never in the hot path for code that must be identical every time. Determinism is the moat.
+2. **Evidence over claims.** "It works" is a claim. A committed receipt from an executed lane is
+   evidence. The whole harness exists to convert one into the other.
+3. **Specs before code.** If behavior isn't written as a clause, the coverage gate calls it
+   untested. New behavior starts in `specs/`, not in a diff.
+4. **Exemplars over documentation.** The `home` feature *is* the architecture guide — a running,
+   tested pattern that generators clone and humans copy. Patterns you can execute don't rot.
+5. **Refusal is a feature.** A green checkmark is cheap. A red one that names the violated clause
+   is what makes the green one mean something. The refusal demo is part of the product.
+6. **Honest SKIPs.** No device → the gate says SKIP, visibly, in the receipt. Green-with-gaps
+   presented as fully verified is treated as a bug — in the harness itself.
+7. **Structure, not pixels.** Golden trees, token assertions, and semantic diffs instead of
+   screenshot comparisons: platform-stable, flake-free, and machine-readable.
+8. **The contract lives in the project.** Everything enforcing correctness ships in the generated
+   repo, not the tool. Your repo stays verifiable after the tool is gone.
+9. **Enforcement must be cheap and fair.** The hook hashes files in milliseconds; doc edits never
+   invalidate evidence; rebases don't force re-runs. Gates that punish honest work get disabled —
+   so they're designed not to.
+10. **Dogfood in public.** The [showcase](https://github.com/kvdm-co-pilot/create-cmp-showcase) is
+    rebuilt from the published package, receipts and refusals included. Two of the last three
+    releases fixed bugs the dogfooding itself caught — the harness catching its own tool is the
+    system working.
+
+---
+
+## Options
+
+| Option | Choices | Default |
+|---|---|---|
+| Platforms | Android (always) + iOS | iOS on |
+| App name / package / iOS bundle id | — | required / derived |
+| Firebase (GitLive KMP) | on / off | on |
+| Auth | `email` / `phone` / `both` / `none` | `both` |
+| Firebase region + services | any region · Firestore/Storage/Functions/FCM | `us-central1` · all on |
+| Room local cache | on / off | on |
+| E2E flows (Maestro) | on / off (`--e2e` / `--no-e2e`; `--appium` is a deprecated alias) | on |
+| Live inspector | on / off | on |
+| Desktop dev-client | on / off | on |
+| Bottom-nav tabs | label + icon, any count | Home, Profile |
+
+_Web/PWA is intentionally out of scope — Android + iOS only._
 
 ## Requirements
 
-- **Node.js ≥ 18** to run the scaffolder.
-- **macOS** for iOS output (Xcode, CocoaPods, XcodeGen). Android output works on macOS or Linux.
-- Everything else — JDK 17, Android SDK + emulator, CocoaPods, XcodeGen, Appium + drivers (legacy
-  e2e path) — the built-in `doctor` detects and (with your consent) installs. The E2E flows
-  themselves run on Maestro, installed separately with
-  `curl -fsSL https://get.maestro.mobile.dev | bash`. Xcode itself must be installed from the App
-  Store; the doctor surfaces that as the one manual step.
-
-## Roadmap
-
-The full plan — six pillars from scaffold to store release, and the sequencing — lives in
-[`docs/ROADMAP.md`](./docs/ROADMAP.md). The AI delivery harness itself (exemplars → conformance
-gates → in-project generation → mechanical enforcement → observability) is **complete** — see
-[`docs/HARNESS-PLAN.md`](./docs/HARNESS-PLAN.md) for the per-layer detail. Near-term:
-
-- [x] Publish to npm as `create-cmp-cli` (`npx create-cmp-cli@latest`) — **live on the registry**;
-      `0.3.0` (the harness release) is prepared and pending its own publish.
-- [x] AI-native Compose inspector — read a running app's hierarchy, geometry, and *resolved design
-      tokens* as structured JSON (no screenshots), including **live on-device inspection** over a
-      loopback debug server. See [`docs/INSPECTOR-PLAN.md`](./docs/INSPECTOR-PLAN.md).
-- [x] Android build matrix in CI on every push; iOS matrix runs on manual dispatch.
-- [ ] Publish `create-cmp-cli@0.3.0` to npm (needs an interactive OTP session) + record the
-      asciinema demo (scaffold → `add-feature` → gate refuses a violation → fix → PASS).
-- [ ] More example features and nav shapes.
+- **Node.js ≥ 18** for the tool itself.
+- **macOS** for iOS output; Android works on macOS or Linux.
+- Everything else (JDK 17, Android SDK + emulator, CocoaPods, XcodeGen) the `doctor` detects and —
+  with consent — installs. Maestro installs with `curl -fsSL https://get.maestro.mobile.dev | bash`.
+  Xcode itself is the one manual App Store step.
+
+## Why CMP, not React Native
+
+The only place CMP loses to RN on a new app is time-to-first-green-build — a tooling problem, not
+a merits problem. With one language, real native UI, no bridge, and a reproducible frozen
+template, CMP's `npx`-and-go is now competitive. If `create-next-app` made React the web default
+by deleting setup friction, the goal here is the same for multiplatform mobile.
+
+## Docs
+
+[`docs/USAGE.md`](./docs/USAGE.md) — the complete usage guide (every command, skill, MCP tool,
+workflow) · [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — engine design ·
+[`docs/HARNESS-PLAN.md`](./docs/HARNESS-PLAN.md) — the harness, layer by layer ·
+[`docs/adr/`](./docs/adr/) — decision records · [`docs/ROADMAP.md`](./docs/ROADMAP.md) — what's next.
 
 ## Contributing
 
-Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) and our
+Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) and the
 [Code of Conduct](./CODE_OF_CONDUCT.md). The golden template is CI-gated: an upstream version bump
-must fail CI, not your generated project.
+must fail our CI, not your generated project.
 
 ## License
 

package/bin/create-cmp.mjs

@@ -63,7 +63,9 @@ async function main() {
 
 function printHelp() {
   process.stdout.write(
-    `create-cmp — scaffold & maintain Kotlin/Compose Multiplatform apps (Android + iOS)\n\n` +
+    `create-cmp — the AI delivery harness for Kotlin/Compose Multiplatform (Android + iOS)\n` +
+      `Scaffolds a green-building app in minutes; every generated project carries a spec-driven\n` +
+      `verify lane, evidence receipts, and mechanical enforcement of "done".\n\n` +
       `Usage:\n` +
       `  npx create-cmp [target-dir] [flags]    scaffold a new app (default command)\n` +
       `  npx create-cmp create [target-dir]     same, explicit\n` +

package/llms.txt

@@ -0,0 +1,27 @@
+# create-cmp
+
+> The AI delivery harness for Kotlin/Compose Multiplatform (Android + iOS): scaffolds a deterministic, green-building app in which every project carries a spec-driven verify lane, evidence receipts, and mechanical enforcement of "done".
+
+create-cmp (npm package: `create-cmp-cli`) stamps a frozen, CI-verified template — it never asks an LLM to freehand project code, so every scaffold is identical and every scaffold builds. It runs fully non-interactively with flags, validates them against a machine-readable schema (`options.schema.json`), and exits non-zero on failure. The `--verify` flag builds the generated app before reporting success.
+
+Non-interactive one-liner (flags per `options.schema.json` and `create-cmp --help`):
+
+```bash
+npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --verify
+```
+
+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.
+
+## Docs
+
+- [README](https://github.com/kvdm-co-pilot/create-cmp/blob/main/README.md): full feature tour — CLI commands, plugin skills, and the harness every generated project carries
+- [Usage guide](https://github.com/kvdm-co-pilot/create-cmp/blob/main/docs/USAGE.md): every command, skill, MCP tool, and workflow in detail
+- [Options schema](https://github.com/kvdm-co-pilot/create-cmp/blob/main/options.schema.json): machine-readable JSON Schema for the engine config the flags build
+- [Changelog](https://github.com/kvdm-co-pilot/create-cmp/blob/main/CHANGELOG.md): release history, Keep-a-Changelog format
+
+## Examples
+
+- [create-cmp-showcase](https://github.com/kvdm-co-pilot/create-cmp-showcase): public repo built entirely by this tool, every commit carrying its evidence receipt
+- [Refusal PR #1](https://github.com/kvdm-co-pilot/create-cmp-showcase/pull/1): live proof of the harness blocking a bad change and naming the violated rule

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.3.1",
-  "description": "The AI delivery harness for Kotlin/Compose Multiplatform — scaffolds a green-building app (Android + iOS) in minutes and holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Installs the `create-cmp` command.",
+  "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.",
   "type": "module",
   "bin": {
     "create-cmp": "bin/create-cmp.mjs",
@@ -14,7 +14,8 @@
     "bin",
     "src",
     "template",
-    "options.schema.json"
+    "options.schema.json",
+    "llms.txt"
   ],
   "scripts": {
     "test": "node --test",
@@ -24,13 +25,23 @@
   "keywords": [
     "create-cmp",
     "create-cmp-cli",
+    "compose multiplatform",
     "compose-multiplatform",
+    "kotlin multiplatform",
     "kotlin-multiplatform",
+    "kotlin",
+    "compose",
     "kmp",
     "cmp",
     "scaffold",
+    "project generator",
+    "cli",
+    "claude code",
+    "ai agent",
     "android",
-    "ios"
+    "ios",
+    "verify",
+    "e2e"
   ],
   "license": "MIT",
   "author": "Karel van der Merwe",

package/src/lib/tabs.mjs

@@ -0,0 +1,370 @@
+// Tab-driven surface regeneration (scaffold pipeline step b.3).
+//
+// The template ships the DEFAULT tabs (Home:home, Profile:person) baked into
+// three surfaces; this module rewrites them from `config.tabs` at stamp time
+// so a non-default tabs config can never go stale:
+//   - presentation/navigation/AppTab.kt      (the appTabs() list — one entry per tab)
+//   - presentation/navigation/AppNavHost.kt  (the appTabs(...) call-site wiring)
+//   - qa/e2e/smoke.yaml                      (Maestro taps/asserts per tab)
+// Tabs without a shipped feature screen (anything that doesn't slug to
+// `home`/`profile`) get a generated PlaceholderScreen stub carrying the
+// `<slug>_title` testTag the smoke flow asserts.
+//
+// Everything is written in TEMPLATE-TOKEN form (__PACKAGE__ contents, literal
+// com/example/app paths) BEFORE token replacement / package rename, so the
+// normal pipeline stamps these files like any other template file. For the
+// default tabs config the output is byte-identical to the static template
+// files — golden/deterministic scaffolding is a core product property.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// --- slug + naming ------------------------------------------------------------
+
+/**
+ * Nav-item tag slug for a tab label.
+ * MUST MIRROR `navItemTag` in
+ * template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppShell.kt:
+ * lowercase, every run of chars outside [a-z0-9] collapsed to a single "_",
+ * leading/trailing "_" trimmed. ("My Stuff!" → "my_stuff")
+ * @param {string} label
+ * @returns {string}
+ */
+export function navSlug(label) {
+  return String(label)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+}
+
+// Kotlin hard keywords — a derived parameter name colliding with one must be backticked.
+const KOTLIN_HARD_KEYWORDS = new Set([
+  "as", "break", "class", "continue", "do", "else", "false", "for", "fun",
+  "if", "in", "interface", "is", "null", "object", "package", "return",
+  "super", "this", "throw", "true", "try", "typealias", "typeof", "val",
+  "var", "when", "while",
+]);
+
+/**
+ * Kotlin parameter name for a tab: camelCase of the slug ("my_stuff" → "myStuff"),
+ * backticked when it collides with a hard keyword or starts with a digit.
+ * @param {string} slug
+ * @returns {string}
+ */
+export function kotlinParamName(slug) {
+  const parts = slug.split("_").filter(Boolean);
+  const name = parts
+    .map((p, i) => (i === 0 ? p : p[0].toUpperCase() + p.slice(1)))
+    .join("");
+  if (KOTLIN_HARD_KEYWORDS.has(name) || /^[0-9]/.test(name)) return `\`${name}\``;
+  return name;
+}
+
+/**
+ * Material icon symbol for a CLI icon key: PascalCase the key's alphanumeric
+ * parts ("home" → "Home", "shopping_cart" → "ShoppingCart", "ShoppingCart"
+ * stays as-is). The template depends on compose.materialIconsExtended, so any
+ * `Icons.Filled.*` symbol from the extended set resolves.
+ * @param {string} key
+ * @returns {string}
+ */
+export function iconSymbol(key) {
+  return String(key)
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((p) => p[0].toUpperCase() + p.slice(1))
+    .join("");
+}
+
+/** Escape a label for use inside a Kotlin double-quoted string literal. */
+function kotlinString(s) {
+  return String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$");
+}
+
+/**
+ * Derive per-tab info (slug, param, icon) and validate the set: every label
+ * must produce a non-empty, unique slug (the slug is the nav testTag AND the
+ * Kotlin parameter name — collisions or empties cannot compile/automate).
+ * @param {Array<{label:string, icon:string}>} tabs
+ */
+export function tabInfos(tabs) {
+  const seen = new Map();
+  return tabs.map((tab) => {
+    const slug = navSlug(tab.label);
+    if (!slug) {
+      throw new Error(
+        `tab label ${JSON.stringify(tab.label)} produces an empty nav slug — labels need at least one [a-z0-9] character`
+      );
+    }
+    if (seen.has(slug)) {
+      throw new Error(
+        `tab labels ${JSON.stringify(seen.get(slug))} and ${JSON.stringify(tab.label)} both slug to "${slug}" — nav testTags must be unique`
+      );
+    }
+    seen.set(slug, tab.label);
+    return { label: tab.label, slug, param: kotlinParamName(slug), icon: iconSymbol(tab.icon) };
+  });
+}
+
+// --- generators ----------------------------------------------------------------
+
+/**
+ * Render AppTab.kt (template-token form). For the default tabs this reproduces
+ * the static template file byte-for-byte.
+ * @param {ReturnType<typeof tabInfos>} infos
+ */
+export function renderAppTabsKt(infos) {
+  const iconImports = [...new Set(infos.map((t) => t.icon))]
+    .sort()
+    .map((i) => `import androidx.compose.material.icons.filled.${i}`)
+    .join("\n");
+  const params = infos.map((t) => `    ${t.param}: @Composable () -> Unit,`).join("\n");
+  const entries = infos
+    .map((t) => `    AppTab("${kotlinString(t.label)}", Icons.Filled.${t.icon}, ${t.param}),`)
+    .join("\n");
+
+  return `package __PACKAGE__.presentation.navigation
+
+import androidx.compose.material.icons.Icons
+${iconImports}
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.graphics.vector.ImageVector
+
+// A single bottom-nav tab: its label, icon, and the screen it renders.
+data class AppTab(
+    val label: String,
+    val icon: ImageVector,
+    val content: @Composable () -> Unit,
+)
+
+// The tab list drives AppShell + AppBottomNav generically (no role-hardcoded shells).
+// The scaffolder regenerates this list from the configured \`tabs\`.
+@Composable
+fun appTabs(
+${params}
+): List<AppTab> = listOf(
+${entries}
+)
+`;
+}
+
+/**
+ * Render qa/e2e/smoke.yaml (template-token form): launch, wait for the first
+ * tab's content, then for each subsequent tab tap nav_<slug> and assert its
+ * <slug>_title + the shell, then return to the first tab. Byte-identical to
+ * the static template file for the default tabs.
+ * @param {ReturnType<typeof tabInfos>} infos
+ */
+export function renderSmokeYaml(infos) {
+  const [first, ...rest] = infos;
+  const lines = [];
+  lines.push(`# E2E smoke — Maestro flow. SPEC: SHELL-01, SHELL-02.
+#
+# Proves the real app boots on a device/emulator and the bottom-nav shell works.
+# Selectors go by testTag (surfaced as resource-ids on Android via TestTagAutomation),
+# never by display text. Nav-item ids are nav_<label-slug> — the slug rule lives in
+# AppShell.kt's navItemTag (lowercase, non-[a-z0-9] runs collapsed to "_", trimmed);
+# keep these ids in sync with it if the configured tabs change.
+#
+# Run:  maestro test qa/e2e/smoke.yaml      (device/emulator attached)
+# The verify lane's e2eSmoke step runs this automatically when maestro + a device are present.
+appId: __PACKAGE__
+---
+- launchApp:
+    clearState: true
+
+# SPEC: SHELL-01 — the app boots and the first tab renders inside the shell, bottom nav visible.
+# Cold-start after clearState can take longer than a bare assert's default window on a slow/CI
+# emulator (first Compose frame under load). Waiting for the first frame IS the SHELL-01 boot
+# proof, so wait explicitly with a generous budget rather than asserting immediately.
+- extendedWaitUntil:
+    visible:
+      id: "${first.slug}_title"
+    timeout: 60000
+- assertVisible:
+    id: "app_bottom_nav"`);
+
+  rest.forEach((tab, i) => {
+    lines.push("");
+    if (i === 0) lines.push("# SPEC: SHELL-02 — switching tabs keeps the shell");
+    lines.push(`- tapOn:
+    id: "nav_${tab.slug}"
+- assertVisible:
+    id: "${tab.slug}_title"
+- assertVisible:
+    id: "app_bottom_nav"`);
+  });
+
+  if (rest.length > 0) {
+    lines.push("");
+    lines.push(`# and back
+- tapOn:
+    id: "nav_${first.slug}"
+- assertVisible:
+    id: "${first.slug}_title"`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+/** Call-site content lambda for one tab in AppNavHost's appTabs(...) call. */
+function navHostTabArg(tab) {
+  if (tab.slug === "home") {
+    return `                ${tab.param} = {
+                    HomeScreen(
+                        onItemClick = { itemId -> navController.navigate(Routes.detail(itemId)) },
+                    )
+                },`;
+  }
+  if (tab.slug === "profile") {
+    return `                ${tab.param} = { ProfileScreen() },`;
+  }
+  return `                ${tab.param} = { PlaceholderScreen(title = "${kotlinString(tab.label)}", titleTag = "${tab.slug}_title") },`;
+}
+
+// The exact template blocks AppNavHost rewriting anchors on. If the template
+// drifts, rewriteNavHost throws instead of silently shipping stale wiring.
+const NAVHOST_IMPORTS_ANCHOR = `import __PACKAGE__.presentation.home.HomeScreen
+import __PACKAGE__.presentation.profile.ProfileScreen`;
+const NAVHOST_TABS_OPEN = "            val tabs = appTabs(\n";
+const NAVHOST_TABS_CLOSE = "\n            )\n";
+
+/**
+ * Rewrite AppNavHost.kt content: the screen imports and the appTabs(...) call
+ * site, one argument per configured tab. Home/Profile slugs wire the shipped
+ * feature screens; anything else wires a PlaceholderScreen stub.
+ * @param {string} content template-token AppNavHost.kt content
+ * @param {ReturnType<typeof tabInfos>} infos
+ * @returns {string}
+ */
+export function rewriteNavHost(content, infos) {
+  if (!content.includes(NAVHOST_IMPORTS_ANCHOR)) {
+    throw new Error("AppNavHost.kt: screen-imports block not found — template drifted from the tab rewriter");
+  }
+  const start = content.indexOf(NAVHOST_TABS_OPEN);
+  const end = start === -1 ? -1 : content.indexOf(NAVHOST_TABS_CLOSE, start);
+  if (start === -1 || end === -1) {
+    throw new Error("AppNavHost.kt: `val tabs = appTabs(` block not found — template drifted from the tab rewriter");
+  }
+
+  const imports = [];
+  if (infos.some((t) => t.slug !== "home" && t.slug !== "profile")) {
+    imports.push("import __PACKAGE__.presentation.components.PlaceholderScreen");
+  }
+  if (infos.some((t) => t.slug === "home")) {
+    imports.push("import __PACKAGE__.presentation.home.HomeScreen");
+  }
+  if (infos.some((t) => t.slug === "profile")) {
+    imports.push("import __PACKAGE__.presentation.profile.ProfileScreen");
+  }
+
+  const tabsBlock =
+    NAVHOST_TABS_OPEN + infos.map(navHostTabArg).join("\n") + NAVHOST_TABS_CLOSE;
+
+  return (
+    content.slice(0, start) + tabsBlock + content.slice(end + NAVHOST_TABS_CLOSE.length)
+  ).replace(NAVHOST_IMPORTS_ANCHOR, () => imports.join("\n"));
+}
+
+/**
+ * Render the PlaceholderScreen stub (template-token form) — written only when
+ * a configured tab has no shipped feature screen, so the default scaffold's
+ * output is unchanged. Mirrors ProfileScreen's stub shape; the title testTag
+ * is what qa/e2e/smoke.yaml asserts for the tab.
+ */
+export function renderPlaceholderScreenKt() {
+  return `package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.unit.dp
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+
+// Generated stub for a configured bottom-nav tab that has no feature yet.
+// Build the real feature with the add-feature skill (qa/scaffold-feature.mjs),
+// then swap this out in AppNavHost. The title testTag (\`<slug>_title\`) is what
+// qa/e2e/smoke.yaml asserts for this tab — keep it when you replace the stub.
+@Composable
+fun PlaceholderScreen(title: String, titleTag: String) {
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .padding(__THEME_PREFIX__Tokens.PaddingPage),
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+        horizontalAlignment = Alignment.Start,
+    ) {
+        Text(
+            text = title,
+            style = MaterialTheme.typography.headlineMedium,
+            modifier = Modifier.semantics { testTag = titleTag },
+        )
+        Text(
+            text = "This is a generated stub tab. Wire it up like the Home feature.",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+    }
+}
+`;
+}
+
+// --- pipeline entry --------------------------------------------------------------
+
+const APPTAB_REL =
+  "composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppTab.kt";
+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 SMOKE_REL = "qa/e2e/smoke.yaml";
+
+/**
+ * Rewrite every tab-driven surface present in the copied project dir. Runs
+ * BEFORE token replacement and the package rename (files are addressed at
+ * their literal com/example/app template paths and written in token form).
+ * Surfaces missing from the tree (feature-stripped qa/e2e, synthetic test
+ * templates) are skipped; a PRESENT AppNavHost that no longer contains the
+ * expected blocks throws.
+ * @param {string} projectDir
+ * @param {Array<{label:string, icon:string}>} tabs
+ * @param {(msg:string)=>void} [log]
+ */
+export function rewriteTabSurfaces(projectDir, tabs, log = () => {}) {
+  const infos = tabInfos(tabs);
+
+  const appTabPath = path.join(projectDir, APPTAB_REL);
+  if (fs.existsSync(appTabPath)) {
+    fs.writeFileSync(appTabPath, renderAppTabsKt(infos));
+    log(`  tabs → ${APPTAB_REL}`);
+  }
+
+  const navHostPath = path.join(projectDir, NAVHOST_REL);
+  if (fs.existsSync(navHostPath)) {
+    const rewritten = rewriteNavHost(fs.readFileSync(navHostPath, "utf8"), infos);
+    fs.writeFileSync(navHostPath, rewritten);
+    log(`  tabs → ${NAVHOST_REL}`);
+  }
+
+  if (infos.some((t) => t.slug !== "home" && t.slug !== "profile")) {
+    const placeholderPath = path.join(projectDir, PLACEHOLDER_REL);
+    if (fs.existsSync(path.dirname(placeholderPath))) {
+      fs.writeFileSync(placeholderPath, renderPlaceholderScreenKt());
+      log(`  tabs → ${PLACEHOLDER_REL}`);
+    }
+  }
+
+  const smokePath = path.join(projectDir, SMOKE_REL);
+  if (fs.existsSync(smokePath)) {
+    fs.writeFileSync(smokePath, renderSmokeYaml(infos));
+    log(`  tabs → ${SMOKE_REL}`);
+  }
+}

package/src/scaffold.mjs

@@ -3,6 +3,8 @@
 //   (b) copy template/ → targetDir
 //   (b.2) delete disabled-feature paths (MUST precede the package rename —
 //         feature paths are declared against the literal com/example/app)
+//   (b.3) regenerate tab-driven surfaces (AppTab.kt, AppNavHost wiring,
+//         qa/e2e/smoke.yaml) from config.tabs, in template-token form
 //   (c) token-replace contents AND paths
 //   (d) rename package source dirs com/example/app → __PACKAGE_PATH__ (atomic)
 //   (e) toggle features (strip cmp:feature marker blocks)
@@ -23,6 +25,7 @@ import {
   disabledFeaturesFromConfig,
   deleteDisabledFeaturePaths,
 } from "./lib/toggle.mjs";
+import { rewriteTabSurfaces } from "./lib/tabs.mjs";
 import { copyDir, listFiles, listDirsDeepestFirst } from "./lib/fsutil.mjs";
 import { runVerify, printVerifyVerdict } from "./lib/verify.mjs";
 import { colors, step, ok, warn } from "./lib/log.mjs";
@@ -181,9 +184,8 @@ function writeLocalProperties(projectDir) {
 
 /**
  * Replace the (already token-substituted) app display name with a slugified,
- * identifier-safe form in the few files that demand it: Gradle's
- * rootProject.name and the appium npm package name. Idempotent and a no-op when
- * the name is already slug-safe.
+ * identifier-safe form in the one file that demands it: Gradle's
+ * rootProject.name. Idempotent and a no-op when the name is already slug-safe.
  * @param {string} projectDir
  * @param {string} appName raw display name (may contain spaces)
  */
@@ -201,20 +203,6 @@ function applyAppNameSlug(projectDir, appName) {
     );
     if (out !== src) fs.writeFileSync(settings, out);
   }
-
-  // qa/appium/package.json: "name": "Demo App-appium" -> "demo-app-appium"
-  const pkg = path.join(projectDir, "qa", "appium", "package.json");
-  if (fs.existsSync(pkg)) {
-    try {
-      const json = JSON.parse(fs.readFileSync(pkg, "utf8"));
-      if (typeof json.name === "string" && json.name.includes(appName)) {
-        json.name = json.name.split(appName).join(slug).toLowerCase();
-        fs.writeFileSync(pkg, `${JSON.stringify(json, null, 2)}\n`);
-      }
-    } catch {
-      // leave as-is on parse failure
-    }
-  }
 }
 
 /**
@@ -276,6 +264,14 @@ export async function scaffold(config, opts = {}) {
     );
   }
 
+  // (b.3) Regenerate the tab-driven surfaces from config.tabs BEFORE token
+  // replacement and the package rename: the rewriter addresses files at their
+  // literal com/example/app template paths and writes template-token contents,
+  // so the pipeline below stamps them like any other template file. For the
+  // default tabs this reproduces the static template files byte-for-byte.
+  step("Regenerating tab surfaces from configured tabs…");
+  rewriteTabSurfaces(projectDir, config.tabs, (m) => process.stdout.write(`${m}\n`));
+
   const tokenMap = buildTokenMap(config);
 
   // (c) token-replace contents AND paths

package/template/README.md

@@ -101,3 +101,7 @@ remember to run it.
 locally. Note that CI independently enforces the same "receipt attests HEAD" check on every push
 (see `.github/workflows/verify.yml`), so disabling the local hook only trades an immediate local
 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.

package/template/composeApp/build.gradle.kts

@@ -262,3 +262,16 @@ compose.desktop {
     }
 }
 // <<< cmp:feature dev-client
+
+// 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
+// replay a PASS from a tree whose baselines differed (or serve an UPDATE_GOLDEN capture run from
+// cache so it never writes the baseline at all). Declaring them makes caching honest; the verify
+// lane additionally forces `--rerun` so evidence receipts always attest actual execution.
+tasks.withType<Test>().configureEach {
+    inputs.files(fileTree(rootProject.layout.projectDirectory.dir("qa/golden")) { include("*.json") })
+        .withPropertyName("goldenBaselines")
+        .withPathSensitivity(PathSensitivity.RELATIVE)
+    inputs.property("updateGolden", System.getenv("UPDATE_GOLDEN") ?: "")
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppShell.kt

@@ -114,6 +114,10 @@ private fun AppBottomNav(
     }
 }
 
+/** Deterministic automation tag for a nav item: `nav_` + the label lowercased with every non-[a-z0-9] run collapsed to `_` and trimmed (e.g. "My Stuff!" → `nav_my_stuff`). Must mirror `navSlug` in create-cmp's engine (src/lib/tabs.mjs), which generates `qa/e2e/smoke.yaml`'s id selectors from the configured tabs — keep the two in sync. */
+private fun navItemTag(label: String): String =
+    "nav_" + label.lowercase().replace(Regex("[^a-z0-9]+"), "_").trim('_')
+
 @Composable
 private fun NavItem(
     label: String,
@@ -128,6 +132,8 @@ private fun NavItem(
             // a11y: guarantee the 48dp minimum touch target regardless of label width
             // (the inspector's audit_a11y flags anything smaller).
             .defaultMinSize(minWidth = 48.dp, minHeight = 48.dp)
+            // Durable selection handle (tests/E2E select by testTag, never display text).
+            .semantics { testTag = navItemTag(label) }
             .padding(horizontal = 8.dp, vertical = 4.dp),
         horizontalAlignment = Alignment.CenterHorizontally,
         verticalArrangement = Arrangement.Center,

package/template/composeApp/src/desktopTest/kotlin/com/example/app/presentation/navigation/AppShellTest.kt

@@ -11,7 +11,6 @@ import androidx.compose.ui.test.ExperimentalTestApi
 import androidx.compose.ui.test.assertIsDisplayed
 import androidx.compose.ui.test.hasTestTag
 import androidx.compose.ui.test.onNodeWithTag
-import androidx.compose.ui.test.onNodeWithText
 import androidx.compose.ui.test.performClick
 import androidx.compose.ui.test.runComposeUiTest
 import __PACKAGE__.testing.awaitNode
@@ -66,12 +65,14 @@ class AppShellTest {
 
         awaitNode(hasTestTag("tab_one_content"))
 
-        onNodeWithText("Tab Two").performClick()
+        // Nav items carry a derived nav_<label-slug> tag (AppShell's navItemTag) —
+        // select by it, never by display text.
+        onNodeWithTag("nav_tab_two").performClick()
         awaitNode(hasTestTag("tab_two_content"))
         onNodeWithTag("tab_two_content").assertIsDisplayed()
         onNodeWithTag("app_bottom_nav").assertIsDisplayed()
 
-        onNodeWithText("Tab One").performClick()
+        onNodeWithTag("nav_tab_one").performClick()
         awaitNode(hasTestTag("tab_one_content"))
         onNodeWithTag("tab_one_content").assertIsDisplayed()
         onNodeWithTag("app_bottom_nav").assertIsDisplayed()

package/template/qa/e2e/smoke.yaml

@@ -2,7 +2,9 @@
 #
 # Proves the real app boots on a device/emulator and the bottom-nav shell works.
 # Selectors go by testTag (surfaced as resource-ids on Android via TestTagAutomation),
-# falling back to visible text only for content assertions.
+# never by display text. Nav-item ids are nav_<label-slug> — the slug rule lives in
+# AppShell.kt's navItemTag (lowercase, non-[a-z0-9] runs collapsed to "_", trimmed);
+# keep these ids in sync with it if the configured tabs change.
 #
 # Run:  maestro test qa/e2e/smoke.yaml      (device/emulator attached)
 # The verify lane's e2eSmoke step runs this automatically when maestro + a device are present.
@@ -23,13 +25,15 @@ appId: __PACKAGE__
     id: "app_bottom_nav"
 
 # SPEC: SHELL-02 — switching tabs keeps the shell
-- tapOn: "Profile"
+- tapOn:
+    id: "nav_profile"
 - assertVisible:
     id: "profile_title"
 - assertVisible:
     id: "app_bottom_nav"
 
 # and back
-- tapOn: "Home"
+- tapOn:
+    id: "nav_home"
 - assertVisible:
     id: "home_title"

package/template/qa/refusal-demo.mjs

@@ -27,7 +27,14 @@ import { fileURLToPath } from "node:url";
 
 const TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const REPO_ROOT = path.resolve(TEMPLATE_ROOT, "..");
-const CREATE_CMP_BIN = path.join(REPO_ROOT, "bin", "create-cmp.mjs");
+// Scaffolding the throwaway app: inside the create-cmp dev tree the engine sits at
+// ../bin relative to the template — use it directly (fast, offline, tests the local
+// code). In a real generated repo that path doesn't exist, so fall back to the
+// published CLI via npx (needs network on first run).
+const LOCAL_ENGINE = path.join(REPO_ROOT, "bin", "create-cmp.mjs");
+const SCAFFOLD_CMD = fs.existsSync(LOCAL_ENGINE)
+  ? `node "${LOCAL_ENGINE}"`
+  : "npx --yes create-cmp-cli@latest";
 const GRADLEW = process.platform === "win32" ? "gradlew.bat" : "./gradlew";
 
 function log(msg) {
@@ -57,7 +64,7 @@ function scaffold() {
   log(`Scaffolding a throwaway app at ${projectDir} (never touching ${TEMPLATE_ROOT})…`);
 
   const res = sh(
-    `node "${CREATE_CMP_BIN}" "${projectDir}" --name RefusalDemo --package com.example.refusaldemo --no-ios --yes --no-verify`,
+    `${SCAFFOLD_CMD} "${projectDir}" --name RefusalDemo --package com.example.refusaldemo --no-ios --yes --no-verify`,
     REPO_ROOT,
     { timeout: 5 * 60_000 },
   );

package/template/qa/verify.mjs

@@ -187,11 +187,11 @@ function stepBuild() {
 }
 
 // Runs a filtered slice of the JVM test tier and names the verdict after the gate it proves.
-// The full suite already ran in unitTests; these re-runs are cheap (compiled, cached) and give
-// each gate its own named verdict + failure text in the receipt.
+// The full suite already ran in unitTests; the filtered slices stay cheap (compilation is
+// cached) while `--rerun` forces the tests themselves to EXECUTE — see stepUnitTests.
 function gradleTestStep(name, testsFilter, failHint) {
   return () => {
-    const res = sh(`${GRADLEW} :composeApp:desktopTest --tests "${testsFilter}" --console=plain`);
+    const res = sh(`${GRADLEW} :composeApp:desktopTest --rerun --tests "${testsFilter}" --console=plain`);
     return {
       name,
       verdict: res.ok ? "PASS" : "FAIL",
@@ -204,7 +204,12 @@ function gradleTestStep(name, testsFilter, failHint) {
 }
 
 function stepUnitTests() {
-  const res = sh(`${GRADLEW} :composeApp:desktopTest --console=plain`);
+  // `--rerun` is EVIDENCE INTEGRITY, not pedantry: without it, Gradle's build cache can
+  // restore a PASS recorded against a *different* tree state (deterministic re-scaffolds
+  // produce byte-identical sources, and golden baselines aren't compile inputs), so the
+  // receipt would attest tests that never executed. Compilation stays cached — only the
+  // test execution is forced.
+  const res = sh(`${GRADLEW} :composeApp:desktopTest --rerun --console=plain`);
   const summary = junitSummary(path.join(ROOT, "composeApp/build/test-results/desktopTest"));
   return {
     name: "unitTests",