create-cmp-cli 0.3.0 → 0.3.2

package/README.md

@@ -2,56 +2,54 @@
 
 # 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).
+## 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 +60,240 @@ 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.
-
-> **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).
+It interviews you (or takes flags), checks your toolchain, stamps the template, and **builds the
+app to prove it's green** before reporting success.
 
-## Commands
+> **Name note:** the npm package is `create-cmp-cli` (the bare `create-cmp` name was already
+> squatted); the installed command is still `create-cmp`.
 
-`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:
+---
 
-| 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.
+# The features, one by one
 
-## Options
+Three surfaces: the **CLI**, the **Claude Code plugin**, and — most importantly — **what every
+generated project carries inside it**.
 
-| 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 |
+## The CLI (5 commands)
 
-_(Web/PWA is intentionally out of scope — Android + iOS only.)_
+Everything except `create` works on **any** KMP project, not just ones this tool made.
 
-## Use it from Claude Code
+| 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. |
 
-`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:
+
+| 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 |
 
-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.
+_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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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.",
   "type": "module",
   "bin": {

package/src/scaffold.mjs

@@ -181,9 +181,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 +200,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
-    }
-  }
 }
 
 /**

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`). Mirrored by the id selectors in `qa/e2e/smoke.yaml` — 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/gitignore

@@ -2,7 +2,10 @@
 .gradle
 /local.properties
 .DS_Store
-/build
+# Gradle build outputs — unanchored so module dirs (composeApp/build/, …) match too,
+# not just a root-level build/. Anchored `/build` misses composeApp/build/, which would
+# then get committed and destabilise the evidence receipt's inputs hash.
+build/
 /captures
 .externalNativeBuild
 .cxx

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/lib/inputs-hash.mjs

@@ -33,9 +33,16 @@ function isExcluded(relPath) {
   return EXCLUDED_PREFIXES.some((prefix) => relPath === prefix || relPath.startsWith(`${prefix}/`));
 }
 
+// The verified surface is the set of files that WILL be committed: tracked files
+// PLUS untracked-but-not-ignored files (`--others --exclude-standard`). A freshly
+// generated feature's files are untracked when the lane runs and the receipt is
+// written, yet they land in the very same commit as the receipt — so they must be
+// hashed, or the committed receipt would never attest its own commit (and CI's
+// receipt-matches-HEAD gate would false-fail on every change). Gitignored scratch
+// (build outputs, qa-artifacts) is still excluded via --exclude-standard.
 function tryGitLsFiles(root) {
   try {
-    const out = execSync("git ls-files -z", { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const out = execSync("git ls-files -z --cached --others --exclude-standard", { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
     return out.split("\0").filter(Boolean);
   } catch {
     return null;

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",