create-cmp-cli 0.7.1 → 0.9.0

package/template/CLAUDE.md

@@ -1,85 +1,232 @@
 # __APP_NAME__ — AI delivery contract
 
-This project was generated by [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a
-verification harness. Any AI session working in this repo follows this contract.
+Generated by [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a verification
+harness. Every AI session in this repo works under this contract.
 
 ## Definition of done
 
-You are **not done until `node qa/verify.mjs` reports PASS** and the receipt it writes
-(`qa/evidence/latest.json`) is included in your commit. Claiming completion without a PASS
-receipt is a failure. SKIPped steps are recorded in the receipt — never present green-with-gaps
-as fully verified.
+Done means `node qa/verify.mjs` reports PASS and the receipt it writes
+(`qa/evidence/latest.json`) is in your commit. Claiming completion without a PASS receipt is
+a failure. SKIPped steps are recorded in the receipt; never present green-with-gaps as fully
+verified.
+
+**Verify in two tiers — the full lane is a checkpoint, not an inner loop.** It builds,
+tests, and gates the whole tree to produce the receipt, so it is slow by design; running it
+after every edit wastes the minutes it takes. Iterate on the fast tier, and run the lane
+once — when you believe the change is done.
+
+- **Inner loop — run continuously (seconds):** the preview loop (below) for UI, and
+  `./gradlew :composeApp:desktopTest` for the unit tests your change touches. This is where
+  you catch your own mistakes.
+- **Checkpoint — run once, at done:** `node qa/verify.mjs`. It writes the receipt; commit
+  the receipt with your change. The Stop hook (`qa/receipt-check.mjs`) then confirms — with a
+  cheap hash check, not another lane run — that a valid receipt attests your commit, and CI
+  re-runs the full lane on push. After a green checkpoint, do not re-run the lane unless you
+  change the tree again.
+
+Humans get the same gate at push time: run `node qa/setup-hooks.mjs` once (after `git init`)
+to enable the shipped pre-push hook. It blocks a push whose committed receipt doesn't attest
+HEAD — the same cheap check, before code leaves the machine (`git push --no-verify` bypasses
+it; CI still enforces it).
 
 ## Specifications — behavior starts here
 
-**New behavior begins as a spec clause** in `specs/<feature>.spec.md` (Given/When/Then with a
-stable id — see [`specs/README.md`](./specs/README.md)). Propose the clause, get it confirmed,
+New behavior begins as a spec clause in `specs/<feature>.spec.md`: Given/When/Then with a
+stable id (see [`specs/README.md`](./specs/README.md)). Propose the clause, get it confirmed,
 then implement. Durable tests cite their clause (`// SPEC: HOME-02`).
 [`specs/app-base.spec.md`](./specs/app-base.spec.md) states the architecture and shell
 invariants the conformance gates enforce.
 
-## Architecture (violations will be named by the conformance gates)
+## Architecture
+
+[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) is the doc of record. Every normative
+sentence in it carries a tier tag: `[enforced: CLAUSE-ID]`, `[governed]`, or `[advisory]`.
+Its `cmp:generated` sections (expect/actual table, layer inventory, ADR index, glossary) are
+derived from a tree walk, never hand-maintained — `node qa/arch-doc.mjs` regenerates them,
+and `node qa/arch-doc.mjs --check`, a verify-lane step, fails the lane when they drift from
+the tree. The governed `architecture` artifact (below) hashes the document alongside
+`specs/app-base.spec.md`, so approving it is consent to this document. The summary:
 
 - **Layers:** `presentation` → `domain` ← `data`. `domain` imports nothing app-internal;
   `presentation` never imports `data`. Koin wires implementations in `di/`.
-- **Every screen:** a `*Screen` composable with a `testTag`ged root, a ViewModel with a test.
-- **Design values** (colors / spacing / typography / radii) come from the theme's token catalog
-  (`presentation/theme/`). Never hardcode literals in screens.
-- The `home` feature is the **exemplar** — it shows the full pattern through every layer,
-  including the tests. When you add a feature, mirror it exactly: Screen → ViewModel (+ test) →
-  UseCase (+ test) → Repository interface in `domain` + impl in `data` (+ test) → DI module
-  entry → navigation route.
-
-## Testing (the pyramid this project uses)
+- **Screens compose the registry vocabulary** (`presentation/components/*.kt` —
+  `ScreenColumn`, `AppHeader`, `ContentStateContainer`, `ListItemCard`, …). Do not hand-roll
+  a header, loading state, or list row; the exemplar's `HomeScreen.kt` shows the pattern.
+  `ScreenColumn(screenTag = "<feature>")` tags the root, and ARCH-04 accepts that wiring as
+  tag provenance — a literal `testTag` is only needed for content the registry does not
+  already tag (per-row ids, for example). Every screen is a `*Screen` composable with a
+  tested ViewModel.
+- **Errors are typed, never thrown across layers.** Repositories return `AppResult`
+  (`Failure` carries a `DomainError` kind). The data layer's `suspendRunCatching` is the
+  only catch point and always rethrows `CancellationException`. ViewModels contain no
+  `try`/`catch`; they fold results into a sealed UiState, and presentation maps error kinds
+  to user copy.
+- **Design values** (colors, spacing, typography, radii) come from the token catalog in
+  `presentation/theme/`. No hardcoded literals in screens.
+- **One feature is the exemplar** — the full pattern through every layer, tests included.
+  It ships as `home`; `qa/approvals.json`'s `exemplarFeature` key retargets it to your own
+  first feature once shaped (see "Configurable exemplar"). New features mirror the exemplar
+  exactly: Screen → ViewModel (+ test) → UseCase (+ test) → Repository interface in `domain`
+  + impl in `data` (+ test) → DI entry → navigation route.
+
+## Testing
 
 - **Unit** (`composeApp/src/commonTest`, run via `./gradlew :composeApp:desktopTest`):
-  kotlin-test + coroutines-test + Turbine. **Hand-written fakes** in `testing/fakes/` — never
+  kotlin-test + coroutines-test + Turbine. Hand-written fakes in `testing/fakes/`; no
   mocking frameworks. Every new ViewModel/UseCase/Repository gets a test in the exemplar's
   style: Arrange-Act-Assert, behavior-named backtick tests, one behavior per test.
-- **Conformance + screen tests** (`composeApp/src/desktopTest`): dependency-free
-  source-scanning architecture gates (they enforce `specs/app-base.spec.md`'s ARCH clauses) + Compose UI Tests (durable,
-  spec-cited, testTag selectors) + the golden-tree structural baseline (`qa/golden/`). Golden
-  drift you did not intend = fix your change; intended drift = regenerate explicitly
-  (`UPDATE_GOLDEN=1`) and declare it.
-- **E2E** (`qa/e2e/*.yaml`): Maestro flows; smoke covers boot + bottom nav. Selectors by
-  testTag — never by display text.
-- Do not delete, weaken, or `@Ignore` a failing test to get to green. Fix the behavior, or if
-  the test itself is wrong, say so explicitly in your summary and justify the change.
+- **Conformance + screen tests** (`composeApp/src/desktopTest`): source-scanning
+  architecture gates enforcing `specs/app-base.spec.md`'s ARCH clauses, Compose UI Tests
+  (spec-cited, testTag selectors), and the golden-tree baseline (`qa/golden/`). Unintended
+  golden drift means fix your change; intended drift is regenerated explicitly
+  (`UPDATE_GOLDEN=1`) and declared.
+- **E2E** (`qa/e2e/*.yaml`): Maestro flows; smoke covers boot + bottom nav. Select by
+  testTag, never by display text.
+- Never delete, weaken, or `@Ignore` a failing test to reach green. Fix the behavior — or,
+  if the test itself is wrong, say so in your summary and justify the change.
 
 ## Evidence
 
 `node qa/verify.mjs` writes `qa/evidence/latest.json` (schema: `qa/evidence/schema.json`).
-Commit it with your change — git history is the audit ledger. Binary artifacts under
-`qa-artifacts/` are hashed into the receipt; never commit them.
+Commit it with your change; git history is the audit ledger. Binary artifacts under
+`qa-artifacts/` are hashed into the receipt, never committed. The studio console's Evidence
+page reconstructs the full audit trail from the git log of `latest.json` — every commit is
+one verified, attributed state — so committing each receipt is what builds the record.
+
+## Approvals — governed artifacts need a human's sign-off
+
+Some artifacts are **governed**: a human approves them, and the approval is bound to the
+artifact's content by hash (`qa/approvals.json`) — the evidence-receipt idea, applied to a
+human decision. The ordered walk is a **definition order**, not just an approval order:
+each artifact is the vocabulary the next is written in, so on a fresh app each step is a
+conversation that ends in an approval — the genesis walk, six conversations:
+
+0. **Intent** — `specs/intent.md`, the root brief everything else traces to (purpose,
+   audience, platforms, brand feel, reference apps, first screens, **glossary**). Filled by
+   the `cmp-new` interview; the seed's placeholder prose is marked unfilled. Its
+   `## Glossary` section is lifted verbatim into `docs/ARCHITECTURE.md` §8 — write it there
+   in the exact form you want published.
+1. **Design system** — `presentation/theme/Theme.kt`, `presentation/theme/Tokens.kt`.
+2. **Architecture + structure** — `specs/app-base.spec.md` **and**
+   [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) (`cmp:generated` sections stripped
+   before hashing, so a mechanical regeneration never invalidates the approval — only an
+   authored-prose edit does).
+3. **Components** — every `presentation/components/*.kt` (a dynamic, sorted glob). Once
+   approved, the registry is law: adding or changing a common component invalidates the
+   approval until a human re-approves.
+4. **Exemplar feature** — the **configured** exemplar's 11-file set the `add-feature`
+   stamper clones from (see "Configurable exemplar").
+5. **Exemplar spec** — `specs/<exemplar>.spec.md`.
+6. **Per-feature spec** — `specs/<feature>.spec.md`, one governed artifact per feature,
+   added as features land.
+
+| Command | What |
+|---|---|
+| `node qa/approve.mjs --status` | Every governed artifact with live state (`unreviewed` / `approved` / `changed-since-approval` / `reopened`), short hash, mode badge |
+| `node qa/approve.mjs <artifact>` | Record approval — hashes the artifact's files now, stamps the time; also clears a `defaults-accepted` mode |
+| `node qa/approve.mjs --accept-defaults` | **Express lane**: approve every currently-resolvable artifact in one visible act, each stamped `"mode": "defaults-accepted"` — build now, walk the definition later. Unresolvable artifacts are skipped with the standard refusal printed. The ledger never pretends the defaults were designed. |
+| `node qa/approve.mjs --reopen <artifact>` | Move an *approved* artifact (shaped or defaults-accepted) back to `reopened` for deliberate redesign — recorded (`reopenedAt`). Refuses unknown ids and anything not currently approved. |
+
+With the create-cmp plugin, the same decisions can be made from the preview console
+(`preview {projectDir}`'s URL) — it calls the same library, so the CLI and the console
+never disagree. An agent blocks on a pending decision with
+`approval_status {waitForDecision:true}`.
+
+The verify lane's `approvals` gate (a step like any other, in every profile) resolves each
+artifact's live status against `qa/approvals.json`:
+
+- **`unreviewed`** → SKIP with a warning line. Nothing fails until a human opts in by
+  approving.
+- **`reopened`** → SKIP with a warning line, exactly like `unreviewed`. Sanctioned redesign
+  never trips the gate; edits made while reopened are never drift. Re-approve when the
+  redesign lands.
+- **`approved`, hash still matches** → PASS.
+- **`approved`, hash no longer matches** → FAIL, naming the artifact and the re-approval
+  command. The artifact changed after sign-off — re-approve it or revert the change.
+  Invalidation is mechanical, like golden-tree drift, not a judgment call.
+
+That asymmetry is the point: **redesign is a decision; drift is an accident** — the ledger
+records which was which. A run with one reopened artifact and one drifted artifact FAILs
+naming only the drifted one.
+
+A gate FAIL fails the lane verdict, which fails `qa/receipt-check.mjs` (the Stop hook) by
+the same mechanism as any other FAIL — no separate enforcement to maintain. `add-feature`
+seeds each new feature's spec as `unreviewed` and prints the approval reminder; it never
+refuses to stamp over this.
+
+### Configurable exemplar — the DNA features are cloned from
+
+`qa/approvals.json` carries a top-level `"exemplarFeature"` key (absent means `"home"`, so
+older ledgers keep meaning what they meant). It names the feature whose 11-file set is the
+governed **exemplar-feature** artifact and the clone source `qa/scaffold-feature.mjs`
+stamps new features from. The genesis walk's endgame is pointing it at *your* first real
+feature: stamp it (`add-feature`), shape it, then set `exemplarFeature` — from then on the
+stamper clones your pattern in your domain language, and `home` demotes to an ordinary
+feature spec. If the configured exemplar has grown files beyond the canonical 11-file
+shape, the stamper clones the canonical set and warns, listing exactly what it skipped.
+
+## Comments — review feedback flows back through the agent
+
+Approvals are binding (they gate the verify lane); **comments are advisory** — a human's
+running commentary, with a defined path back into your plan, spec, and code.
+`qa/comments.json` is the ledger; `qa/lib/comments.mjs` is the library, mirroring
+`qa/lib/approvals.mjs`'s shape: state, validation, transitions, nothing fabricated.
+
+**The loop of record:**
+
+1. A human adds a comment from the preview console — on a screen, a spec clause, a
+   design-system token or component, or an architecture tree node.
+2. You observe it — `review_comments { waitForComment: true }` (plugin) blocks until a new
+   one lands; without the plugin, `node qa/comment.mjs --list --open`.
+3. You act on it — update the plan, the spec clause, or the code it points at.
+4. You resolve it **after** acting, with a note saying what you did —
+   `resolve_comment { id, note }` (plugin) or `node qa/comment.mjs --resolve <id> --note
+   "..."` (CLI, records author `agent-cli`). The console then shows `resolved` plus your
+   note. The console never edits code: humans comment, agents resolve.
+
+| Command | What |
+|---|---|
+| `node qa/comment.mjs --list` | Every comment, open and resolved, with resolution notes |
+| `node qa/comment.mjs --list --open` | Only open comments |
+| `node qa/comment.mjs --resolve <id> --note "..."` | Resolve a comment, recording what changed |
+
+A comment targets one of: a **screen**, an **element** (screen + testTag), a **spec-line**
+(file + clause id), a **design-system** token, an **architecture** path, or **general**.
+`addComment` refuses empty text and a target missing the fields its type requires — the
+same refusal-over-fabrication stance as approvals. A ledger that exists but cannot be
+parsed is never treated as empty (that would hide real feedback); reads and writes surface
+the honest error instead.
 
 ## UI feedback loop — see what you build, without a device
 
 <!-- >>> cmp:feature inspector -->
-While building or changing ANY screen, use the preview loop instead of an emulator: it
-renders this app's REAL screens (real DI, real theme, seeded data) headlessly in seconds
-and tells you exactly what your edit changed.
+While building or changing any screen, use the preview loop instead of an emulator. It
+renders this app's real screens (real DI, real theme, seeded data) headlessly in seconds
+and tells you what your edit changed.
 
 **With the create-cmp plugin (cmp-inspector MCP tools):**
 
-1. `preview { projectDir }` — once per session. Returns a live gallery URL (give it to
-   the human; it re-renders itself on every save) plus per-screen structural summaries
-   for you. Sources are watched; you never run Gradle by hand.
-2. After each edit: `preview_status { waitForRender: true }` — blocks until the
-   render/compile outcome. `changedLastRender` names the screens your edit touched
-   (empty = the edit reached no screen); `lastErrorSource: "compile"` means the edit
-   didn't even build (the compiler's `e:` lines are in `lastError`).
-3. `preview_diff { screen }` — one call proves the change: verdict `proven-clean` /
-   `changed-with-regressions` / `no-change`. No snapshot bookkeeping needed.
+1. `preview { projectDir }` — once per session. Returns a live gallery URL for the human
+   (it re-renders on every save) and per-screen structural summaries for you. Sources are
+   watched; you never run Gradle by hand.
+2. After each edit: `preview_status { waitForRender: true }` blocks until the outcome.
+   `changedLastRender` names the screens your edit touched (empty = the edit reached no
+   screen); `lastErrorSource: "compile"` means the edit did not build — the compiler's `e:`
+   lines are in `lastError`.
+3. `preview_diff { screen }` proves the change in one call: `proven-clean` /
+   `changed-with-regressions` / `no-change`. No snapshot bookkeeping.
 
 **Without the plugin:** `./gradlew :composeApp:renderScreens` renders every screen to
 `composeApp/build/previews/<id>/{screen.png, tree.json}` (`-Pscreen=<id>` for one);
 `node qa/preview-gallery.mjs` builds a self-contained gallery page from the output.
 
-Screens come from `inspector/PreviewRegistry.kt` (desktopMain). The `add-feature`/`add-screen`
-stamper **auto-registers** a stamped screen there (at the `// cmp:anchor preview-registry`
-marker). **When you add a screen by hand, register it there** — a forced-state variant is just
-another entry (`"home@empty"`).
-Assert on the `tree.json` structure; never read PNG bytes (pixels are for humans).
+Screens come from `inspector/PreviewRegistry.kt` (desktopMain). The `add-feature` and
+`add-screen` stampers auto-register stamped screens at the `// cmp:anchor preview-registry`
+marker; when you add a screen by hand, register it there — a forced-state variant is just
+another entry (`"home@empty"`). Every common component also carries a story entry
+(`"component.<kebab-name>"` in `inspector/ComponentStories.kt`); when you add a component,
+add its story — the lane's `componentStories` step fails naming the missing id otherwise.
+Assert on `tree.json` structure; never read PNG bytes. Pixels are for humans.
 <!-- <<< cmp:feature inspector -->
 <!-- >>> cmp:feature dev-client -->
 For one interactive window instead of stills of every screen:
@@ -98,7 +245,8 @@ conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional C
 
 | Command | What |
 |---|---|
-| `node qa/verify.mjs` | The verify lane (profile `local`) — your definition of done |
+| `node qa/verify.mjs` | The verify lane (profile `local`) — the done checkpoint, run once |
 | `./gradlew :composeApp:desktopTest` | Unit tests only (fast inner loop) |
+| `node qa/setup-hooks.mjs` | Enable the pre-push receipt gate (one-time, after `git init`) |
 | `./gradlew :composeApp:assembleDebug` | Android debug build |
 | `./gradlew :composeApp:hotRunDesktop --auto` | Desktop dev-client with hot reload |

package/template/README.md

@@ -1,6 +1,6 @@
 # __APP_NAME__
 
-A Kotlin / Compose Multiplatform app — generated by
+A Kotlin / Compose Multiplatform app, generated by
 [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a **verification harness**:
 the architecture, testing conventions, and definition of done are enforced mechanically, not
 by convention. Start with [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md); AI collaborators
@@ -80,32 +80,28 @@ Every change must pass the verify lane (`node qa/verify.mjs`) and commit its upd
 
 ## Verification enforcement
 
-This project ships a **Stop hook** (`.claude/settings.json`) that makes `CLAUDE.md`'s definition
-of done mechanical instead of honor-system, for AI sessions using Claude Code.
-
-**What it does:** when a session tries to end, the hook runs `node qa/receipt-check.mjs --hook`.
-That script recomputes a sha256 hash over this project's "verified surface" (`composeApp/`,
-`specs/`, `qa/`, and the Gradle build files — see `qa/lib/inputs-hash.mjs`) and compares it to the
-`inputs.hash` recorded in the committed `qa/evidence/latest.json`. If the receipt is a `PASS` and
-its hash matches the current tree, the session ends silently. If source changed without a fresh
-`PASS` receipt — or the receipt is missing, a `FAIL`, or predates this mechanism — the hook blocks
-with the specific reason and asks you to run `node qa/verify.mjs` and commit the receipt. **It runs
-no build and no tests — only file hashing —** so it costs milliseconds, and it never fires twice in
-a row for the same stop.
-
-Doc-only edits (`*.md`, `README`, `.github/`, `.claude/`) are deliberately **outside** the verified
-surface, so editing docs never invalidates a good receipt or forces a needless re-run — the intent
-is transparent enforcement, not a hostile one.
-
-**Why:** `CLAUDE.md` already says a change is "not done" without a `PASS` receipt committed. The
-Stop hook is what makes that check happen automatically instead of relying on the AI session to
-remember to run it.
-
-**Escape hatch:** this is your project. If you don't want the hook, delete or comment out the
-`Stop` block in [`.claude/settings.json`](./.claude/settings.json) — nothing else depends on 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.
+For AI sessions using Claude Code, a **Stop hook** (`.claude/settings.json`) makes
+`CLAUDE.md`'s definition of done mechanical instead of honor-system.
+
+**What it does:** when a session tries to end, the hook runs
+`node qa/receipt-check.mjs --hook`. That script recomputes a sha256 hash over the project's
+verified surface (`composeApp/`, `specs/`, `qa/`, and the Gradle build files — see
+`qa/lib/inputs-hash.mjs`) and compares it to the `inputs.hash` in the committed
+`qa/evidence/latest.json`. A `PASS` receipt whose hash matches the tree ends the session
+silently. Source changed without a fresh `PASS` — or a missing, failed, or pre-mechanism
+receipt — blocks with the specific reason and asks for `node qa/verify.mjs` plus a committed
+receipt. It runs no build and no tests, only file hashing, so it costs milliseconds, and it
+never fires twice in a row for the same stop.
+
+Doc-only edits (`*.md`, `README`, `.github/`, `.claude/`) are deliberately outside the
+verified surface: editing docs never invalidates a good receipt. The intent is transparent
+enforcement, not a hostile one.
+
+**Escape hatch:** this is your project. If you don't want the hook, delete the `Stop` block
+in [`.claude/settings.json`](./.claude/settings.json) — nothing else depends on it locally.
+CI independently enforces the same "receipt attests HEAD" check on every push
+(`.github/workflows/verify.yml`), so disabling the local hook only trades an immediate
+signal for a later one.
 
 ---
 

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/CrashRecorder.kt

@@ -0,0 +1,99 @@
+package __PACKAGE__.inspector
+
+import android.content.Context
+import android.util.Log
+import java.io.File
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+
+/**
+ * Debug-only crash capture: [install] sets a process-wide
+ * [Thread.UncaughtExceptionHandler] that persists crash JSON to
+ * `filesDir/inspector/crashes/` (bounded to the last [MAX_CRASHES]) so a crash survives the
+ * process death that follows it — an in-memory ring buffer would not.
+ *
+ * MUST NEVER SWALLOW THE CRASH: after persisting, it always hands off to whatever handler was
+ * installed before it (chained, not replaced) so system crash dialogs, `System.exit`, and any
+ * other crash-reporting tool still behave exactly as if this class did not exist.
+ */
+object CrashRecorder {
+
+    private const val TAG = "CmpInspector"
+    private const val MAX_CRASHES = 20
+
+    fun install(context: Context) {
+        val crashDir = File(context.filesDir, "inspector/crashes").apply { mkdirs() }
+        val previous = Thread.getDefaultUncaughtExceptionHandler()
+        Thread.setDefaultUncaughtExceptionHandler { thread, throwable ->
+            try {
+                persist(crashDir, throwable)
+            } catch (t: Throwable) {
+                // Persisting the crash record must never itself crash the crash handler.
+                Log.w(TAG, "failed to persist crash record", t)
+            } finally {
+                if (previous != null) {
+                    previous.uncaughtException(thread, throwable)
+                } else {
+                    // No previous handler installed: fall back to the JVM's own default so the
+                    // process still dies the normal way instead of hanging.
+                    Runtime.getRuntime().exit(10)
+                }
+            }
+        }
+    }
+
+    private fun persist(crashDir: File, throwable: Throwable) {
+        val doc = buildJsonObject {
+            put("timestamp", JsonPrimitive(isoNow()))
+            put("exception", JsonPrimitive(throwable::class.qualifiedName ?: throwable.javaClass.name))
+            put("message", throwable.message?.let { JsonPrimitive(it) } ?: JsonNull)
+            put("frames", buildJsonArray {
+                throwable.stackTrace.forEach { el ->
+                    add(buildJsonObject {
+                        put("className", JsonPrimitive(el.className))
+                        put("methodName", JsonPrimitive(el.methodName))
+                        put("fileName", el.fileName?.let { JsonPrimitive(it) } ?: JsonNull)
+                        put("lineNumber", JsonPrimitive(el.lineNumber))
+                    })
+                }
+            })
+        }
+        File(crashDir, "crash-${System.currentTimeMillis()}.json")
+            .writeText(Json.encodeToString(JsonElement.serializer(), doc))
+        prune(crashDir)
+    }
+
+    /** Keep only the most recent [MAX_CRASHES] crash files (current boot + previous ones). */
+    private fun prune(crashDir: File) {
+        val files = crashDir.listFiles { f -> f.isFile && f.name.endsWith(".json") } ?: return
+        if (files.size <= MAX_CRASHES) return
+        files.sortedBy { it.lastModified() }
+            .take(files.size - MAX_CRASHES)
+            .forEach { it.delete() }
+    }
+
+    /**
+     * Every persisted crash's raw JSON text, newest first — spans the current boot AND any
+     * previous ones ([install] never clears the directory, only [prune] bounds it).
+     */
+    fun readAll(context: Context): List<String> {
+        val crashDir = File(context.filesDir, "inspector/crashes")
+        val files = crashDir.listFiles { f -> f.isFile && f.name.endsWith(".json") } ?: return emptyList()
+        return files.sortedByDescending { it.lastModified() }
+            .mapNotNull { runCatching { it.readText() }.getOrNull() }
+    }
+
+    private fun isoNow(): String {
+        val fmt = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US)
+        fmt.timeZone = TimeZone.getTimeZone("UTC")
+        return fmt.format(Date())
+    }
+}

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/DbInspector.kt

@@ -0,0 +1,144 @@
+package __PACKAGE__.inspector
+
+// >>> cmp:feature room
+import __PACKAGE__.data.local.AppDatabase
+import androidx.room.useReaderConnection
+import kotlinx.coroutines.runBlocking
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import org.koin.core.context.GlobalContext
+// <<< cmp:feature room
+
+/**
+ * `GET /inspect/db` (schema: tables via `sqlite_master`) and `GET /inspect/db?table=<name>&limit=<n>`
+ * (rows). Read-only, off the main thread. 404 when this project's local-database feature is off
+ * (there is nothing to query) — see the `room`-gated implementation below for the real path.
+ */
+object DbInspector {
+
+    // >>> cmp:feature room
+    // Reads go through the project's Room database (a Koin single). Injection-safe by
+    // construction: a requested `table` is only ever used in a query after it is proven to be
+    // a real name returned by `sqlite_master` in THIS call — the raw wire value never reaches
+    // SQL beyond that validated identifier.
+    //
+    // This project's Room config uses the KMP driver architecture (BundledSQLiteDriver, see
+    // data/local/DatabaseBuilder.kt), not the legacy Android-only SupportSQLiteDatabase — so
+    // reads go through Room 2.8's public `useReaderConnection { transactor -> ... }` whose
+    // receiver is a pooled connection exposing `usePrepared(sql) { stmt -> ... }` (the
+    // statement is created and closed by Room; binds are 1-based, column reads 0-based).
+    private const val DEFAULT_ROW_LIMIT = 50
+    private const val MAX_ROW_LIMIT = 500
+    private val VALID_IDENTIFIER = Regex("^[A-Za-z_][A-Za-z0-9_]*$")
+    private val prettyJson = Json { prettyPrint = true }
+
+    private fun appDatabaseOrNull(): AppDatabase? =
+        try {
+            // GlobalContext.getOrNull() IS the Koin instance (or null before startKoin).
+            GlobalContext.getOrNull()?.getOrNull<AppDatabase>()
+        } catch (t: Throwable) {
+            null
+        }
+
+    fun schema(): Pair<Int, String> {
+        val db = appDatabaseOrNull()
+            ?: return 503 to errorJson("database not available yet (Room not initialised — is Koin started?).")
+        return try {
+            val tables = runBlocking {
+                db.useReaderConnection { connection ->
+                    connection.usePrepared(
+                        "SELECT name, sql FROM sqlite_master WHERE type = 'table' " +
+                            "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'room_%' ORDER BY name"
+                    ) { stmt ->
+                        val out = mutableListOf<Pair<String, String?>>()
+                        while (stmt.step()) {
+                            out += stmt.getText(0) to (if (stmt.isNull(1)) null else stmt.getText(1))
+                        }
+                        out
+                    }
+                }
+            }
+            200 to prettyJson.encodeToString(JsonElement.serializer(), buildJsonObject {
+                put("tables", buildJsonArray {
+                    tables.forEach { (name, sql) ->
+                        add(buildJsonObject {
+                            put("name", JsonPrimitive(name))
+                            put("sql", sql?.let { JsonPrimitive(it) } ?: JsonNull)
+                        })
+                    }
+                })
+            })
+        } catch (t: Throwable) {
+            500 to errorJson("failed to read schema: ${t.message}")
+        }
+    }
+
+    /** Row page for one table: columns + stringified values, capped. */
+    private class TableRows(val columns: List<String>, val rows: List<JsonElement>)
+
+    fun rows(table: String, limitParam: String?): Pair<Int, String> {
+        if (!VALID_IDENTIFIER.matches(table)) {
+            return 400 to errorJson("invalid table name '$table' — expected a plain SQL identifier.")
+        }
+        val db = appDatabaseOrNull()
+            ?: return 503 to errorJson("database not available yet (Room not initialised — is Koin started?).")
+        val limit = (limitParam?.toIntOrNull() ?: DEFAULT_ROW_LIMIT).coerceIn(1, MAX_ROW_LIMIT)
+        return try {
+            val result: TableRows? = runBlocking {
+                db.useReaderConnection { connection ->
+                    // STRICT validation: `table` is only used in the row query below once THIS
+                    // check proves it is a real sqlite_master identifier — never the raw wire value.
+                    val exists = connection.usePrepared(
+                        "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?"
+                    ) { stmt ->
+                        stmt.bindText(1, table)
+                        stmt.step()
+                    }
+                    if (!exists) return@useReaderConnection null
+
+                    connection.usePrepared("SELECT * FROM \"$table\" LIMIT ?") { stmt ->
+                        stmt.bindLong(1, limit.toLong())
+                        val colCount = stmt.getColumnCount()
+                        val columns = (0 until colCount).map { stmt.getColumnName(it) }
+                        val rows = mutableListOf<JsonElement>()
+                        while (stmt.step()) {
+                            rows += buildJsonObject {
+                                for (i in 0 until colCount) {
+                                    put(columns[i], if (stmt.isNull(i)) JsonNull else JsonPrimitive(stmt.getText(i)))
+                                }
+                            }
+                        }
+                        TableRows(columns, rows)
+                    }
+                }
+            }
+            if (result == null) {
+                return 404 to errorJson("unknown table '$table' — not present in sqlite_master.")
+            }
+            200 to prettyJson.encodeToString(JsonElement.serializer(), buildJsonObject {
+                put("table", JsonPrimitive(table))
+                put("columns", buildJsonArray { result.columns.forEach { add(JsonPrimitive(it)) } })
+                put("rows", buildJsonArray { result.rows.forEach { add(it) } })
+                put("rowCount", JsonPrimitive(result.rows.size))
+            })
+        } catch (t: Throwable) {
+            500 to errorJson("failed to read table '$table': ${t.message}")
+        }
+    }
+
+    private fun errorJson(message: String): String =
+        """{"error":${JsonPrimitive(message)}}"""
+    // <<< cmp:feature room
+    // >>> cmp:feature !room
+    private const val DISABLED_MESSAGE =
+        "the 'room' feature is disabled in this project — /inspect/db is unavailable."
+
+    fun schema(): Pair<Int, String> = 404 to """{"error":"$DISABLED_MESSAGE"}"""
+
+    fun rows(table: String, limitParam: String?): Pair<Int, String> = schema()
+    // <<< cmp:feature !room
+}