create-cmp-cli 0.2.0 → 0.3.1

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

@@ -0,0 +1,130 @@
+---
+name: add-screen
+description: >-
+  Add a presentation-only slice — Screen + ViewModel + tests + golden tree + spec + nav route —
+  for an EXISTING entity/repository in this Compose Multiplatform app, cloned deterministically
+  from the `home` exemplar's presentation layer. Requires the entity's data layer (model,
+  repository, use case, fake) to already exist. Use this when the user wants to "add a screen",
+  "add a screen for an existing entity", "add a screen backed by a repository I already have",
+  "put a UI on this data", or names an existing domain noun they want a screen for (e.g. "add a
+  screen for Tag", "I need a Bookmarks screen — the repository's already there"). Works with NO
+  create-cmp plugin installed — the stamper (`qa/scaffold-feature.mjs --preset screen`) and this
+  skill both ship inside the generated project.
+---
+
+# add-screen — stamp a presentation slice over an existing entity
+
+> Deterministic-stamp, gate-proven. The script (`qa/scaffold-feature.mjs --preset screen`) does
+> the mechanical work — copy the `home` exemplar's presentation files, whole-word identifier
+> rename, DI injection for the ViewModel only, nav route + import. You (the AI) only refine spec
+> wording and adapt the screen to the entity's real shape. You are not done until
+> `node qa/verify.mjs` PASSes and the receipt is committed — see this project's `CLAUDE.md`.
+
+This is the `screen` subset of `add-feature` — same stamper, same rename mechanic, filtered to
+the 6 presentation+tests+spec files, **composed on top of an entity that already exists** (via
+`add-repository` or a prior `add-feature` run). If the entity doesn't exist yet, this will refuse
+to stamp anything — see step 2.
+
+## Why a stamper and not hand-written files
+
+Every hand-written file is a drift chance in this project's architecture. `qa/scaffold-feature.mjs
+--preset screen` produces a **conforming skeleton by construction**: a Screen composable with a
+testTagged root, a ViewModel (+ test), a Compose UI test, a golden-tree test, and a six-clause
+spec — wired into Koin and the nav graph. Your job is to make it *behave* like the real screen,
+not to make it *structurally correct*.
+
+## The flow
+
+### 1. Name the feature and confirm the entity
+
+Ask the human for the feature/screen name (PascalCase, plural-ish noun — e.g. `Tags`,
+`Bookmarks`) and the entity it's backed by (e.g. `Tag`, `Bookmark`). If they don't give an
+entity, the script defaults it by stripping a trailing `s`/`ies` from the feature name — naive
+de-pluralization is unreliable for irregular nouns, so **always show the proposed entity and let
+the human confirm or override it** before proceeding (`--entity <EntityName>`).
+
+The entity must already exist — its use case, fake, and model must be present
+(`domain/usecase/Get<Entity>sUseCase.kt`, `testing/fakes/Fake<Entity>Repository.kt`,
+`domain/model/<Entity>.kt`). If it doesn't, the stamper will refuse before writing anything and
+tell you to run `add-repository` first (or use plain `add-feature` instead, which generates both
+layers together).
+
+### 2. Dry-run
+
+```
+node qa/scaffold-feature.mjs <FeatureName> --entity <EntityName> --preset screen --dry-run
+```
+
+Show the human the file plan (Screen, ViewModel, ViewModel test, Compose UI test, golden-tree
+test, spec) and the injection diffs (ViewModel DI binding, nav route + import — no repository or
+use case wiring, since those already exist). Confirm before stamping for real — this is the last
+chance to catch a wrong entity name.
+
+If the entity doesn't exist, this step (and the real stamp) exits non-zero with an actionable
+message rather than half-stamping a screen that won't compile.
+
+### 3. Stamp
+
+```
+node qa/scaffold-feature.mjs <FeatureName> --entity <EntityName> --preset screen
+```
+
+This writes the Screen/ViewModel/tests/golden-tree-test, wires the ViewModel into
+`di/AppModule.kt` and a route into `presentation/navigation/Screen.kt` +
+`presentation/navigation/AppNavHost.kt` at their `// cmp:anchor` markers, and writes
+`specs/<feature>.spec.md` with a default six-clause set (`<FEATURE>-01..06`) cited by the three
+generated test files.
+
+If it exits non-zero, read the message — it is actionable. Do not hand-edit around a stamper
+failure.
+
+### 4. Refine the spec, then the behavior
+
+Rewrite the clause prose in `specs/<feature>.spec.md` for the entity's real behavior — the six
+clause **ids stay fixed** (specCoverage binds tests to ids, not prose). Propose the rewritten
+clauses to the human; get them confirmed before moving on.
+
+Then adapt the generated code to match the entity's actual shape (which may differ from the
+`home` exemplar's `{id, title, subtitle}` list): update the screen's rendering in
+`presentation/<feature>/<Feature>Screen.kt` and the copied tests
+(`<Feature>ViewModelTest.kt`, `<Feature>ScreenTest.kt`) together, consistent with whatever
+`<Entity>.kt` already looks like. The gate (step 6) will name exactly what you missed.
+
+### 5. Capture the golden tree
+
+The golden baseline is **not** copied (a copied one would silently mismatch the adapted screen).
+Generate it fresh once the screen renders the real behavior:
+
+```
+UPDATE_GOLDEN=1 ./gradlew :composeApp:desktopTest --tests "*<Feature>GoldenTree*"
+```
+
+Review `qa/golden/<feature>.json` briefly — it should reflect the structure you intended. Commit
+it alongside the feature.
+
+### 6. Gate
+
+```
+node qa/verify.mjs
+```
+
+This must PASS. It proves: the spec's six clauses are all bound to a citing test
+(specCoverage — `<FEATURE>-01..06` newly bound), the build compiles, unit tests pass, architecture
+conformance holds, the golden tree matches, and accessibility holds. **Not done until this is
+PASS and the evidence receipt (`qa/evidence/latest.json`) is committed with your change** — this
+project's standing definition of done (see `CLAUDE.md`).
+
+If it fails: read the failing step's reason, fix the actual behavior or spec/test binding, and
+re-run. Do not delete or weaken a test to reach green.
+
+## Guardrails
+
+- Works identically with or without the create-cmp Claude Code plugin installed — everything it
+  needs (`qa/scaffold-feature.mjs`, this file) ships inside the generated project.
+- Respect whichever toggles this project was stamped with (e.g. if Room or Appium/Maestro were
+  disabled at scaffold time, don't reintroduce them for the new screen).
+- `add-screen` generates a pushed-nav-route screen, not a bottom-nav tab, and does not generate a
+  "tap → detail" destination — same MVP scope as `add-feature`.
+- If the entity doesn't exist yet, don't try to work around the stamper's refusal by hand-writing
+  the missing use case/fake/model — run `add-repository` first (or use plain `add-feature` for
+  both layers together), then retry.

package/template/.github/workflows/verify.yml

@@ -1,8 +1,9 @@
 # CI for your Compose Multiplatform app — stamped in by create-cmp.
 #
-# What runs on every push/PR: a toolchain report (advisory) and the Android
-# debug build — the same "verify gate" create-cmp ran when it generated this
-# project. Green here = your frozen version set still builds.
+# What runs on every push/PR: a toolchain report (advisory) and the VERIFY LANE
+# (qa/verify.mjs) — build + unit tests + every other gate this project carries,
+# producing the evidence receipt. Green here = your frozen version set still
+# builds AND the harness's checks pass.
 #
 # iOS: a ready-to-enable macOS job is included (commented out) at the bottom.
 # macOS runners cost ~10x Linux minutes, so it's opt-in.
@@ -35,11 +36,32 @@ jobs:
         continue-on-error: true
         run: npx --yes create-cmp-cli@latest doctor --yes --no-install --no-ios
 
-      # The verify gate. If this fails after a dependency bump, remember:
-      # Kotlin / KSP / Compose / Room / AGP move as ONE set (see the comments
-      # in gradle/libs.versions.toml).
-      - name: Build Android (debug)
-        run: ./gradlew :composeApp:assembleDebug --stacktrace
+      # Receipt attests HEAD: the committed evidence receipt (qa/evidence/latest.json)
+      # must validly attest the checked-out tree — verdict PASS and the inputs-hash
+      # still matching the verified surface — BEFORE we spend a runner re-running the
+      # lane. Robust to rebase/merge/squash: validity is a content hash of the inputs,
+      # not a parent SHA (docs/adr/0005). This is the same predicate the local Stop
+      # hook runs (qa/receipt-check.mjs) — one check, two locations — so a stale or
+      # hand-edited receipt fails here even if the author bypassed the local hook.
+      - name: Receipt attests HEAD
+        run: node qa/receipt-check.mjs
+
+      # The verify lane: build + unit tests + all shipped gates, with a typed
+      # verdict and an evidence receipt. If the build step fails after a
+      # dependency bump, remember: Kotlin / KSP / Compose / Room / AGP move as
+      # ONE set (see the comments in gradle/libs.versions.toml).
+      - name: Verify lane
+        run: node qa/verify.mjs --profile ci
+
+      # The receipt this run produced, kept as a build artifact. The receipt
+      # committed by the author (qa/evidence/latest.json) lives in the repo —
+      # this artifact is CI's independent re-verification of the same change.
+      - name: Upload evidence receipt
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: verify-evidence
+          path: qa/evidence/latest.json
 
   # ── iOS (opt-in) ──────────────────────────────────────────────────────────
   # Uncomment to build the iOS app on every push to main. Uses the exact

package/template/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Mon Jul 06 18:20:40 WAT 2026
+gradle.version=8.11.1

package/template/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to __APP_NAME__. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versioning: [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] — scaffold
+
+### Added
+- Initial scaffold generated by [create-cmp](https://github.com/kvdm-co-pilot/create-cmp):
+  Compose Multiplatform app with Clean Architecture, the `home` exemplar feature (with tests),
+  theme token catalog, and the verification harness (`qa/verify.mjs` + evidence receipts +
+  [`CLAUDE.md`](./CLAUDE.md) contract).

package/template/CLAUDE.md

@@ -0,0 +1,70 @@
+# __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.
+
+## 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.
+
+## 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,
+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)
+
+- **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)
+
+- **Unit** (`composeApp/src/commonTest`, run via `./gradlew :composeApp:desktopTest`):
+  kotlin-test + coroutines-test + Turbine. **Hand-written fakes** in `testing/fakes/` — never
+  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.
+
+## 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.
+
+## Docs
+
+[`README.md`](./README.md) (front page) · [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)
+(layers + how to add a feature) · [`docs/TESTING.md`](./docs/TESTING.md) (pyramid +
+conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional Commits) ·
+[`docs/adr/`](./docs/adr/) (decision records — significant decisions get one). Keep
+[`CHANGELOG.md`](./CHANGELOG.md) current under `[Unreleased]` as part of your change.
+
+## Commands
+
+| Command | What |
+|---|---|
+| `node qa/verify.mjs` | The verify lane (profile `local`) — your definition of done |
+| `./gradlew :composeApp:desktopTest` | Unit tests only (fast inner loop) |
+| `./gradlew :composeApp:assembleDebug` | Android debug build |
+| `./gradlew :composeApp:hotRunDesktop --auto` | Desktop dev-client with hot reload |

package/template/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+## The workflow
+
+1. Branch from `main` (`feat/<name>`, `fix/<name>`).
+2. Make the change — new features mirror the `home` exemplar
+   (see [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)), with tests at every layer
+   (see [`docs/TESTING.md`](./docs/TESTING.md)).
+3. Run the verify lane: `node qa/verify.mjs`.
+4. Commit **including the updated receipt** (`qa/evidence/latest.json`). A change without a
+   PASS receipt is not done — CI re-runs the same lane and will say so.
+5. Open a PR. Keep it one concern; note any intended golden/baseline changes explicitly.
+
+## Definition of done
+
+- `node qa/verify.mjs` → **PASS**, receipt committed.
+- New behavior has tests; existing tests untouched unless the behavior intentionally changed
+  (say so in the PR).
+- No hardcoded design values; testTags on anything E2E needs to reach.
+- Significant decisions recorded as an ADR (`docs/adr/`).
+
+## Commit style — Conventional Commits
+
+```
+<type>(<scope>): <imperative summary>
+
+feat(home): add pull-to-refresh
+fix(nav): keep state on tab re-selection
+test(profile): cover error retry path
+docs(adr): record image-loading choice
+```
+
+Types: `feat` `fix` `test` `refactor` `docs` `build` `ci` `chore`. Scope = feature/module.
+
+## Code style
+
+- Kotlin official style; match the surrounding file's idiom.
+- Comments explain constraints the code can't (never narrate what the next line does).
+- Public surface of `domain` stays framework-free.

package/template/README.md

@@ -0,0 +1,103 @@
+# __APP_NAME__
+
+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
+follow the contract in [`CLAUDE.md`](./CLAUDE.md).
+
+## Quick start
+
+```bash
+# Android (device/emulator attached)
+./gradlew :composeApp:installDebug
+
+<!-- >>> cmp:feature dev-client -->
+# Desktop dev-client with Compose Hot Reload — the daily dev loop
+./gradlew :composeApp:hotRunDesktop --auto
+<!-- <<< cmp:feature dev-client -->
+
+# Unit tests (fast inner loop)
+./gradlew :composeApp:desktopTest
+
+# The verify lane — build + tests + every shipped gate, with an evidence receipt
+node qa/verify.mjs
+```
+
+<!-- >>> cmp:feature ios -->
+**iOS:** `cd iosApp && xcodegen generate && pod install`, then open
+`iosApp.xcworkspace` in Xcode and run. (First time: `brew install xcodegen`.)
+<!-- <<< cmp:feature ios -->
+
+<!-- >>> cmp:feature firebase -->
+**Firebase:** the scaffold ships a placeholder `google-services.json`. Wire your real project
+before shipping — from Claude Code, the `cmp-firebase-connect` skill drives it end to end.
+<!-- <<< cmp:feature firebase -->
+
+## Project structure
+
+```
+specs/                       behavior specifications — new behavior starts here
+composeApp/src/commonMain/   shared UI + logic (presentation / domain / data / di)
+composeApp/src/commonTest/   unit tests — exemplar pattern in presentation/home
+composeApp/src/desktopTest/  conformance gates + Compose UI tests + golden trees (JVM tier)
+composeApp/src/androidMain/  Android entry point + platform actuals
+<!-- >>> cmp:feature ios -->
+composeApp/src/iosMain/      iOS actuals · iosApp/ is the Xcode shell
+<!-- <<< cmp:feature ios -->
+<!-- >>> cmp:feature dev-client -->
+composeApp/src/desktopMain/  desktop dev-client (see docs/dev-client.md)
+<!-- <<< cmp:feature dev-client -->
+qa/verify.mjs                the verify lane — this repo's definition of done
+qa/evidence/latest.json      the committed evidence receipt (see CONTRIBUTING.md)
+<!-- >>> cmp:feature e2e -->
+qa/e2e/                      Maestro E2E flows (device smoke)
+<!-- <<< cmp:feature e2e -->
+docs/                        architecture, testing, ADRs
+```
+
+## Documentation
+
+| Doc | What |
+|---|---|
+| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Layers, data flow, how to add a feature |
+| [`docs/TESTING.md`](./docs/TESTING.md) | The test pyramid, conventions, how to run everything |
+| [`docs/adr/`](./docs/adr/) | Architecture decision records |
+| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | Workflow, definition of done, commit style |
+| [`CLAUDE.md`](./CLAUDE.md) | The AI delivery contract |
+| [`CHANGELOG.md`](./CHANGELOG.md) | Notable changes (Keep a Changelog) |
+
+## Verification
+
+Every change must pass the verify lane (`node qa/verify.mjs`) and commit its updated receipt
+(`qa/evidence/latest.json`). CI re-runs the same lane on every push — see
+[`.github/workflows/verify.yml`](./.github/workflows/verify.yml).
+
+## 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.

package/template/composeApp/build.gradle.kts

@@ -51,16 +51,16 @@ kotlin {
     }
     // <<< cmp:feature ios
 
-    // >>> cmp:feature dev-client
-    // Desktop dev-client: runs the shared commonMain UI in a live JVM window — the daily dev
-    // loop. Compose Hot Reload attaches to this target (task: hotRunDesktop). See docs/dev-client.md.
+    // The JVM tier — harness infrastructure, NOT feature-gated. This target hosts the fast
+    // verification loop: unit tests, conformance gates, golden-tree renders, and Compose UI
+    // Tests all run here (`:composeApp:desktopTest`), device-free. The dev-client window
+    // feature merely reuses it.
     jvm("desktop") {
         @OptIn(ExperimentalKotlinGradlePluginApi::class)
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_17)
         }
     }
-    // <<< cmp:feature dev-client
 
     sourceSets {
         commonMain.dependencies {
@@ -130,7 +130,7 @@ kotlin {
         }
         // <<< cmp:feature ios
 
-        // >>> cmp:feature dev-client
+        // JVM tier deps (harness infrastructure — see the jvm("desktop") target note).
         val desktopMain by getting {
             dependencies {
                 implementation(compose.desktop.currentOs)
@@ -138,12 +138,21 @@ kotlin {
                 implementation(libs.ktor.client.cio)
             }
         }
-        // <<< cmp:feature dev-client
 
         commonTest.dependencies {
             implementation(libs.kotlin.test)
             implementation(libs.koin.test)
             implementation(libs.kotlinx.coroutines.test)
+            implementation(libs.turbine)
+        }
+
+        // JVM-tier test deps: Compose UI Tests, the golden-tree serializer, and the
+        // conformance gates all run here (the verify lane's fast, device-free steps).
+        val desktopTest by getting {
+            dependencies {
+                implementation(compose.desktop.uiTestJUnit4)
+                implementation(compose.desktop.currentOs)
+            }
         }
     }
 }
@@ -225,9 +234,7 @@ dependencies {
     add("kspIosX64", libs.room.compiler)
     add("kspIosArm64", libs.room.compiler)
     // <<< cmp:feature ios
-    // >>> cmp:feature dev-client
     add("kspDesktop", libs.room.compiler)
-    // <<< cmp:feature dev-client
     // <<< cmp:feature room
     add("coreLibraryDesugaring", libs.android.desugar.jdk)
 }

package/template/composeApp/src/commonMain/kotlin/com/example/app/di/AppModule.kt

@@ -4,19 +4,23 @@ import __PACKAGE__.data.remote.ItemRepositoryImpl
 import __PACKAGE__.domain.repository.ItemRepository
 import __PACKAGE__.domain.usecase.GetItemsUseCase
 import __PACKAGE__.presentation.home.HomeViewModel
+// cmp:anchor di-imports
 import org.koin.core.module.dsl.viewModelOf
 import org.koin.dsl.module
 
 val repositoryModule = module {
     single<ItemRepository> { ItemRepositoryImpl() }
+    // cmp:anchor di-repositories
 }
 
 val useCaseModule = module {
     factory { GetItemsUseCase(get()) }
+    // cmp:anchor di-usecases
 }
 
 val viewModelModule = module {
     viewModelOf(::HomeViewModel)
+    // cmp:anchor di-viewmodels
 }
 
 // Aggregated common modules, started from AppApplication (Android) and KoinHelper (iOS).

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/home/DetailScreen.kt

@@ -8,6 +8,8 @@ import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
 import __PACKAGE__.presentation.components.BaseScreen
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
 import __PACKAGE__.presentation.theme.designToken
@@ -27,8 +29,14 @@ fun DetailScreen(
                 )
                 .padding(__THEME_PREFIX__Tokens.PaddingPage),
         ) {
-            TextButton(onClick = onBack) { Text("← Back") }
-            Text("Detail", style = MaterialTheme.typography.headlineMedium)
+            TextButton(onClick = onBack, modifier = Modifier.semantics { testTag = "detail_back" }) {
+                Text("← Back")
+            }
+            Text(
+                "Detail",
+                style = MaterialTheme.typography.headlineMedium,
+                modifier = Modifier.semantics { testTag = "detail_title" },
+            )
             Text(
                 "Item id: $itemId",
                 style = MaterialTheme.typography.bodyLarge,

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/home/HomeScreen.kt

@@ -47,10 +47,20 @@ fun HomeScreen(
             modifier = Modifier.semantics { testTag = "home_title" }.padding(bottom = 12.dp),
         )
 
+        val errorMessage = state.errorMessage
         if (state.isLoading) {
             Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                 CircularProgressIndicator()
             }
+        } else if (errorMessage != null) {
+            Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+                Text(
+                    text = errorMessage,
+                    style = MaterialTheme.typography.bodyLarge,
+                    color = MaterialTheme.colorScheme.error,
+                    modifier = Modifier.semantics { testTag = "home_error" },
+                )
+            }
         } else {
             LazyColumn(verticalArrangement = Arrangement.spacedBy(__THEME_PREFIX__Tokens.GapCard)) {
                 items(state.items, key = { it.id }) { item ->

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/home/HomeViewModel.kt

@@ -12,6 +12,7 @@ import kotlinx.coroutines.launch
 data class HomeUiState(
     val isLoading: Boolean = true,
     val items: List<Item> = emptyList(),
+    val errorMessage: String? = null,
 )
 
 class HomeViewModel(
@@ -28,8 +29,11 @@ class HomeViewModel(
     fun load() {
         viewModelScope.launch {
             _state.value = HomeUiState(isLoading = true)
-            val items = getItems()
-            _state.value = HomeUiState(isLoading = false, items = items)
+            _state.value = try {
+                HomeUiState(isLoading = false, items = getItems())
+            } catch (e: Exception) {
+                HomeUiState(isLoading = false, errorMessage = e.message ?: "Something went wrong")
+            }
         }
     }
 }

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

@@ -39,5 +39,6 @@ fun AppNavHost() {
                 onBack = { navController.popBackStack() },
             )
         }
+        // cmp:anchor nav-destinations
     }
 }

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

@@ -5,11 +5,12 @@ sealed class Screen(val route: String) {
     data object Shell : Screen(Routes.SHELL)
     // Example detail destination reachable from a tab. Add your own below.
     data object Detail : Screen(Routes.DETAIL)
+    // cmp:anchor screen-objects
 }
 
 object Routes {
     const val SHELL  = "shell"
     const val DETAIL = "detail/{itemId}"
-
+    // cmp:anchor route-consts
     fun detail(itemId: String) = "detail/$itemId"
 }

package/template/composeApp/src/commonTest/kotlin/com/example/app/data/remote/ItemRepositoryImplTest.kt

@@ -0,0 +1,26 @@
+package __PACKAGE__.data.remote
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+import kotlinx.coroutines.test.runTest
+
+/**
+ * The exemplar data-layer test. [ItemRepositoryImpl] is the template's dependency-light
+ * example source; when you swap it for a real Firestore/Ktor + Room implementation, keep
+ * this shape: test the repository through its DOMAIN contract, under `runTest` virtual
+ * time (the simulated I/O delay costs nothing here — delays are skipped, not slept).
+ */
+class ItemRepositoryImplTest {
+
+    private val repository = ItemRepositoryImpl()
+
+    @Test
+    fun `returns the seeded example items`() = runTest {
+        val items = repository.getItems()
+
+        assertTrue(items.isNotEmpty(), "example source should seed items")
+        assertEquals(items.size, items.map { it.id }.toSet().size, "item ids must be unique")
+        assertTrue(items.all { it.title.isNotBlank() }, "every item needs a title")
+    }
+}