@terreno/mcp 57.20.0 → 57.22.0

package/src/docs/versioned/57.21.0/tasks/describe-model-schema.md

@@ -0,0 +1,37 @@
+# Tasks: `describeModel()` schema metadata
+
+IP: [describe-model-schema.md](../implementationPlans/describe-model-schema.md)
+
+## Phase 1 — Descriptor + MCP
+
+- [x] **Task 1.1**: `describeModel` / `describeModelForRouter`
+  - Delivers: field graph + snapshot tests on a fixture schema
+  - Files: `api/src/schemaMetadata.ts`, `api/src/schemaMetadata.test.ts`
+  - Blocked by: none
+  - Acceptance: snapshots for enum, ref, array, subdocument, system fields
+- [x] **Task 1.2**: MCP Zod from descriptor
+  - Delivers: `schemaGenerator.ts` maps `FieldDescription`; no SchemaType switch for kinds already in the descriptor
+  - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: MCP schema tests pass; create tools still omit system fields
+
+## Phase 2 — Admin
+
+- [x] **Task 2.1**: `extractFieldMeta` from descriptor
+  - Delivers: admin config fields built from `describeModel`, not OpenAPI property walk
+  - Files: `admin-backend/src/adminApp.ts`, admin-backend tests
+  - Blocked by: 1.1
+  - Acceptance: ref, enum, required, nested array items still appear on `/admin/config`
+
+## Phase 3 — OpenAPI + docs
+
+- [x] **Task 3.1**: `getOpenApiSpecForModel` from descriptor
+  - Delivers: OpenAPI properties derived from `ModelDescription`; populate still applied
+  - Files: `api/src/populate.ts`, `api/src/openApi.test.ts` / example-backend openapi snapshot if required
+  - Blocked by: 1.1
+  - Acceptance: OpenAPI tests pass; any snapshot diff is reviewed in the PR
+- [x] **Task 3.2**: Docs + export
+  - Files: `docs/explanation/schema-metadata.md`, `docs/reference/api.md`, `docs/how-to/create-a-model.md`, admin reference, `api/src/index.ts`, changelog
+  - Blocked by: 1.2, 2.1, 3.1
+  - Skills: `update-docs`
+  - Acceptance: stranger finds “one descriptor, three views” without reading code

package/src/docs/versioned/57.21.0/tasks/docs-reference-coverage.md

@@ -0,0 +1,93 @@
+# Task List: Reference Documentation Coverage
+
+See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPlans/docs-reference-coverage.md)
+
+**RTK deprecation flag:** **Blocked.** Do not start until PR #869 merges. `docs/reference/syncdb.md` is owned by [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) — do not write it here. Tasks below marked `[RTK]` reference the frontend data layer.
+
+## Instructions for the implementing agent
+
+- **Do not write documentation from scratch.** The content already exists in `.cursor/rules/*/00-*.mdc` files. Your job is to convert prescriptive agent rules into descriptive public reference prose, verify every claim against source, and remove anything internal.
+- Verify every exported symbol you document by grepping the package's `src/index.ts`. If a rule file documents something that no longer exists, drop it and note the drift in the PR body.
+- READMEs are rendered on npmjs.com where relative links break. Use absolute `https://github.com/TerrenoLabs/terreno/...` or docs-site URLs in every README.
+- Match the section ordering of `docs/reference/api.md` for new reference pages. Read it first.
+- Run `bun run website:build` before each commit that adds or moves a docs page.
+
+## Phase 1: Missing reference pages
+
+- [x] **Task 1.1**: Write `docs/reference/ai.md`
+  - Description: Convert `.cursor/rules/ai/00-ai.mdc` into a public reference page. Sections, following `docs/reference/api.md`'s shape: Install; Commands; Architecture (file structure); `AIService` setup and full method table; structured-output helpers (`generateJsonValue`, `generateJsonObject`, `generateJsonArray`) including the JSON-normalization behavior and error logging; temperature presets; the `AIRequest` and `GptHistory` models with field tables; route registrars (`addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`) with endpoints, methods, and permissions; Langfuse integration; integration example with `setupServer`/`TerrenoApp`; environment variables; conventions; testing (including the mock-model pattern). Verify every symbol against `ai/src/index.ts`. Remove the internal-only conventions that make no sense to a consumer (for example instructions about not mocking `@terreno/api` belong in agent rules, not reference docs — use judgment).
+  - Files: `docs/reference/ai.md` (new)
+  - Depends on: none
+  - Acceptance: every documented symbol appears in `ai/src/index.ts`; the method table lists all `AIService` methods; all three route registrars documented with their permissions; no `.claude/` or `.cursor/` path referenced.
+
+- [x] **Task 1.2**: Write `docs/reference/admin-spa.md`
+  - Description: New reference page for `@terreno/admin-spa`, sourced from `admin-spa/README.md` and `admin-spa/src/`. Cover: what the package is (standalone Expo Router web admin SPA plus an Express plugin that serves it), install, the `AdminSpaServeApp` plugin registration with its options, building the SPA, configuring `apiBase`/`routeBase`, how it relates to the embedded `@terreno/admin-frontend` approach and when to choose each, and environment variables. Verify the plugin options against the source and against how `example-backend/src/server.ts` registers it.
+  - Files: `docs/reference/admin-spa.md` (new)
+  - Depends on: none
+  - Acceptance: every option documented exists in the source; includes a "standalone SPA vs embedded screens" decision paragraph; the registration example matches `example-backend/src/server.ts`.
+
+- [x] **Task 1.3**: Write `docs/reference/test.md`
+  - Description: New reference page for `@terreno/test`. Cover: what it provides (in-memory MongoDB management for bun test suites), install as a dev dependency, the `bunfig.toml` preload pattern, `setupEnvironment()`, the `TERRENO_TEST_USE_MEMORY_MONGO` / `TERRENO_TEST_MONGODB_URI` / `BUN_TEST_DISABLE_DB` environment variables, and the test-helper exports. Source the preload contract from `admin-backend/AGENTS.md`, `api/src/tests/bunSetup.ts`, and the `backend-test-env` skill. Keep it short — one page.
+  - Files: `docs/reference/test.md` (new)
+  - Depends on: none
+  - Acceptance: all three environment variables documented with their effects; the preload example matches an actual `bunfig.toml` in the repo; under 150 lines.
+
+- [x] **Task 1.4**: `[RTK]` Fix the reference index
+  - Description: Update `docs/reference/README.md` to list every reference page that exists, including `ai.md`, `admin-spa.md`, `test.md`, `api-health.md`, `feature-flags.md`, `environment-variables.md`, and `syncdb.md`, with `rtk.md` under a Legacy heading. Cross-check against `ls docs/reference/` so nothing is orphaned and nothing listed is missing.
+  - Files: `docs/reference/README.md`
+  - Depends on: Task 1.1, Task 1.2, Task 1.3
+  - Acceptance: `ls docs/reference/*.md` and the index agree exactly; every link resolves; `bun run website:build` reports no new broken links.
+
+## Phase 2: Package READMEs
+
+- [x] **Task 2.1**: Define and apply the README template to the four stubs
+  - Description: Write the six-section template from the IP (Title/description, Install, Quick start, What's included, Documentation, License/Contributing) and apply it to the four stub READMEs: `ai/README.md` (source: the new `docs/reference/ai.md`), `admin-backend/README.md` (source: `.cursor/rules/admin-backend/00-admin-backend.mdc` + `docs/reference/admin-backend.md`), `admin-frontend/README.md` (same pattern), `api-health/README.md` (source: `api-health/src/`). Each Quick start must be a complete, runnable snippet — not a fragment. Every link absolute.
+  - Files: `ai/README.md`, `admin-backend/README.md`, `admin-frontend/README.md`, `api-health/README.md`
+  - Depends on: Task 1.1
+  - Acceptance: all four follow the six sections in order; `rg -n "\.claude/|\.cursor/" ai/README.md admin-backend/README.md admin-frontend/README.md api-health/README.md` returns nothing; every relative link replaced with an absolute URL; each Quick start compiles if pasted into a matching file.
+
+- [x] **Task 2.2**: Add the missing READMEs
+  - Description: Create `feature-flags/README.md` (source: `docs/reference/feature-flags.md`; cover `FeatureFlagsApp` registration, the `/flagConfiguration` endpoint, `liveUpdates` and its replica-set requirement, and the deprecated `/evaluate` endpoint), `test/README.md` (source: the new `docs/reference/test.md`), `demo/README.md` (how to run the component demo on port 8085, how stories are organized under `stories/`, how to add a story and register it in `demoConfig.tsx`, and the demo-vs-dev mode split), and `website/README.md` (how to run the docs site locally, where content comes from — `../docs` — how versioning works, and how deploys happen via Netlify).
+  - Files: `feature-flags/README.md`, `test/README.md`, `demo/README.md`, `website/README.md` (all new)
+  - Depends on: Task 1.3
+  - Acceptance: every command shown exists in the corresponding `package.json` scripts or the root `package.json`; `demo/README.md` correctly names port 8085; `website/README.md` correctly states that docs content lives in `../docs`.
+
+- [x] **Task 2.3**: Normalize the four good READMEs
+  - Description: Apply the template's link discipline (not a rewrite) to `api/README.md`, `ui/README.md`, `mcp-server/README.md`, and `admin-spa/README.md`: convert relative repo links to absolute URLs, add the Documentation / License / Contributing sections if missing, and ensure the description line matches the standardized `package.json` description. Additionally, reconcile `mcp-server/README.md`'s tool list with `docs/reference/mcp-server.md` and the live hosted server — the README is known to omit `terreno_search_docs`, `terreno_get_component_docs`, and `terreno_get_upgrade_guide`.
+  - Files: `api/README.md`, `ui/README.md`, `mcp-server/README.md`, `admin-spa/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: no relative link escapes the package directory in any of the four; `mcp-server/README.md` and `docs/reference/mcp-server.md` list identical tool sets; each README's opening line matches its `package.json` description.
+
+- [x] **Task 2.4**: Add `docs/tasks/README.md`
+  - Description: Create a short README in `docs/tasks/` explaining that files there are structured task breakdowns for automated implementation of the IPs in `docs/implementationPlans/`, that they are internal planning artifacts rather than user documentation, and that they are excluded from the docs site. Do the same check for `docs/implementationPlans/README.md` — it exists; verify it says something similar and update if not.
+  - Files: `docs/tasks/README.md` (new), `docs/implementationPlans/README.md`
+  - Depends on: none
+  - Acceptance: `docs/tasks/README.md` exists and states the directory's purpose in under 15 lines; both directories are confirmed excluded in `website/docusaurus.config.ts`.
+
+## Phase 3: Sanitization
+
+- [x] **Task 3.1**: Sweep public docs for internal leakage
+  - Description: Run `rg -ni "flourish|a\.run\.app|netlify\.app|PRO-[0-9]|FH-[0-9]|slack|\.claude/|\.cursor/" docs/ */README.md README.md` excluding `infra/flourish/` and `docs/implementationPlans/`. For each hit decide: remove, replace with a placeholder, or relocate to `infra/flourish/`. Live example URLs (the Netlify frontend, the Cloud Run backend) may stay in a clearly-labeled "Live examples" list but must not appear in instructional steps as if the reader owns them. Record the total number of fixes in the PR body.
+  - Files: various under `docs/` and package READMEs
+  - Depends on: Task 2.3
+  - Acceptance: the grep returns only permitted hits (live-example URLs in labeled lists, and `docs/implementationPlans/` planning content); the PR body reports the count and lists each judgment call.
+
+- [x] **Task 3.2**: Fix the how-to index and stale "Coming Soon" entries
+  - Description: `docs/how-to/README.md` lists feature flags under "Coming Soon" even though `docs/how-to/add-feature-flags.md` exists. Audit the whole index against `ls docs/how-to/*.md`, remove stale "Coming Soon" markers for anything that shipped, and add entries for guides that exist but are unlisted. Do the same audit for `docs/explanation/` and `docs/tutorials/` indexes if they exist.
+  - Files: `docs/how-to/README.md`, `docs/explanation/README.md` and `docs/tutorials/README.md` if present
+  - Depends on: none
+  - Acceptance: every `.md` file in each directory appears in its index exactly once; no "Coming Soon" marker refers to a file that exists.
+
+## Phase 4: Drift protection
+
+- [x] **Task 4.1**: Extend the docs-audit check
+  - Description: Update `.rulesync/skills/docs-audit/SKILL.md` and the script it drives (find it via `.github/workflows/docs-audit.yml`) to add two checks: (1) every package published by `publish-on-tag.yml` has a non-stub `README.md` (heuristic: at least 30 lines and containing an `## Install` heading) and a `docs/reference/<pkg>.md` page; (2) no file under `docs/` or any published package README matches the internal-leakage pattern from Task 3.1. Make both failures fatal in CI. Regenerate skill mirrors with `bun run rules`.
+  - Files: `.rulesync/skills/docs-audit/SKILL.md`, the docs-audit script, `.github/workflows/docs-audit.yml`, generated mirrors
+  - Depends on: Task 3.1
+  - Acceptance: deleting `feature-flags/README.md` makes the audit fail with a message naming the package; adding the string `flourish-terreno` to a docs page makes it fail; `bun run rules:check` exits 0.
+
+- [x] **Task 4.2**: Document the reference/rule duplication policy
+  - Description: Add a short section to `docs/explanation/ai-workflows.md` (or `CONTRIBUTING.md` if that reads better) explaining the deliberate split from IP question RF2: `docs/reference/` is descriptive documentation for humans, `.rulesync/rules/` is prescriptive guidance for agents, both are maintained, and a change to a package's public API requires updating both. Note that the docs-audit workflow flags drift but cannot fully verify it.
+  - Files: `docs/explanation/ai-workflows.md` or `CONTRIBUTING.md`
+  - Depends on: Task 4.1
+  - Acceptance: the policy states which file type serves which reader and that both must be updated on public API changes.

package/src/docs/versioned/57.21.0/tasks/docs-site-and-versioning.md

@@ -0,0 +1,42 @@
+# Task List: Documentation Site, Versioned Docs, and Docs-Maintenance Skills
+
+See: [`docs/implementationPlans/docs-site-and-versioning.md`](../implementationPlans/docs-site-and-versioning.md)
+
+Phases 1–2 and most of 3–4 already shipped on `master` (`website/`, generated
+reference, `docs:version` job, `update-docs` / `docs-audit`, weekly audit CI).
+This file tracks the remaining frontier.
+
+## Instructions for the implementing agent
+
+- Public MCP tool schemas live in `mcp-server/src/tools.ts`. Search behavior
+  lives in `mcp-server/src/search/docIndex.ts`.
+- Run `cd mcp-server && bun test src/__tests__/search.test.ts src/search/docVersion.test.ts`.
+- Update `docs/reference/mcp-server.md` in the same slice as the tool schema.
+
+## Phase 3: Versioning (remaining)
+
+- [x] **Task 3.1**: MCP `version` parameter on doc search tools
+  - Delivers: `terreno_search_docs` and `terreno_get_component_docs` accept
+    optional `version`. Unmatched versions fall back to the nearest retained
+    snapshot with a note. Omitted `version` searches `next` (current `docs/`).
+    Historical searches do not mix other versions. Versioned `.mdx` files are
+    indexed.
+  - Files: `mcp-server/src/search/docIndex.ts`, `mcp-server/src/search/docVersion.ts`,
+    `mcp-server/src/tools.ts`, `docs/reference/mcp-server.md`
+  - Blocked by: none
+  - Acceptance: `searchDocs({queries: ["token"], version: "0.19.0"})` returns
+    only that snapshot; a patch like `0.19.1` falls back to `0.19.0` with a
+    note; omitted version does not return `versioned/0.19.0` chunks;
+    `getComponentDocsMarkdown` accepts the same `version` and reads the
+    snapshot MDX when present.
+
+## Phase 4: Skills (remaining)
+
+- [x] **Task 4.1**: `improve-rulesync` docs-vs-agent split
+  - Delivers: `improve-rulesync` states that user-facing guidance belongs in
+    `docs/` (the site) and agent-facing guidance belongs in `.ai/` / rules,
+    with cross-links rather than duplication.
+  - Files: `.rulesync/skills/improve-rulesync/SKILL.md` (then `bun run skills:sync`)
+  - Blocked by: Task 3.1
+  - Acceptance: the skill names both homes and forbids copying the same
+    architecture into both without a cross-link.

package/src/docs/versioned/57.21.0/tasks/durable-agent-harness.md

@@ -0,0 +1,185 @@
+# Tasks: Durable agent harness
+
+IP: [durable-agent-harness.md](../implementationPlans/durable-agent-harness.md)  
+**Feature profile:** false (full IP)  
+**Base branch:** `cursor/ai-observability-ip-64ca` (rebase as it lands)  
+**First PR scope:** Phases 1–2. Phases 3–5 ship in follow-up PRs.
+
+## Resume here (paused 2026-10-03)
+
+The Pick ⇄ Roast loop is paused after Phase 1. Tasks 1.1–1.12 are Roast-verified, one commit each.
+
+1. **Sync the base.** `git fetch origin && git merge origin/cursor/ai-observability-ip-64ca`.
+   At pause it was 5+ commits ahead, including a master merge and "Preserve AI observability
+   across chat turn refactor", which touches `ai/`. Re-run `cd ai && bun run test:ci` after the merge.
+2. **Resume the loop** with `/terreno:pick-roast-loop` (or `terreno-pick-roast-loop`) at
+   **Task 2.0**, then 2.1, then 2.2. Each task is Pick, then an independent Roast, then one commit.
+3. **Brew when Phase 2 is done.** Run the full independent branch review that was deferred at
+   pause, take the PR out of draft, then Taste.
+
+Known environment notes from Phase 1:
+
+- `/tmp` in the cloud VM is a 1 GB tmpfs, and in-memory replica sets use about 200 MB each. Run Mongo
+  test suites sequentially and delete leftover `/tmp/mongo-mem-*` directories after killed runs.
+- `example-backend` seed-heavy tests can hit Bun's 5 s default timeout under load. This also
+  happens on the base branch.
+- In the root `bun run lint`, `check:explicit-any:lint` requires a `// noExplicitAny: <reason>` line
+  above every `biome-ignore … noExplicitAny`.
+
+Every task: bun tests in `ai/` against the in-memory replica set from `@terreno/test`; real
+models are replaced by the mock model pattern in `.claude/rules/ai/00-ai.md`. Docs pages are
+created in 1.1 and extended by every later task — never deferred.
+
+## Phase 1 — Durable clinical tracer
+
+- [x] **Task 1.1**: Harness subpath + `defineTask` + transactional checkpoint/span (tracer)
+  - Delivers: `@terreno/ai/harness` export; `HarnessTask` model; `defineTask` with phases; `InProcessRunner` (no lease yet) runs a two-phase task to `completed`; `rt.commit` writes task + `ObsSpan` + root `ObsTrace` in one transaction; `Harness.open` throws without local observability plugin or without a replica set
+  - Files: `ai/package.json`, `ai/src/harness/harness.ts`, `defineTask.ts`, `runtime.ts`, `commit.ts`, `runners/inProcessRunner.ts`, `models/harnessTask.ts`, `ai/src/types/harness.ts`, tests
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`
+  - Docs: create `docs/explanation/durable-agent-harness.md` (concepts table), `docs/reference/ai-harness.md` (`defineTask`, `Harness.open`, `rt.commit`), link from `docs/reference/ai.md`
+  - Acceptance: AC1 — bun test asserts one CHAIN span per phase; forced throw inside the transaction leaves neither task update nor span
+
+- [x] **Task 1.2**: Owner lease, crash resume, replay semantics
+  - Delivers: `HarnessOwner` lease + heartbeat; standby second process; task leases with fencing token; resume on `start()`; per-phase `replay`; `interrupted` status; `harness.resolveInterrupted(taskId, action)`
+  - Files: `runners/inProcessRunner.ts`, `models/harnessOwner.ts`, `runtime.ts`, `commit.ts`, tests
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: reference "Replay and interruption" table; explanation section on leases
+  - Acceptance: AC2 + AC3 (phase rows) — simulate death by abandoning a harness mid-phase with an expired lease; new harness resumes safe phase and parks `never` phase as `interrupted`; stale-token commit rejected
+
+- [x] **Task 1.3**: Retries, failure, abort + ownership tree
+  - Delivers: task `retry` policy with backoff+jitter (Luxon), `failed` after `maxAttempts`; `rt.createTask` child ownership; `harness.abort` bottom-up with `abort` handlers; `rt.waitForTasks` (`all` / `failFast`); `background` flag
+  - Files: `runtime.ts`, `retryBackoff.ts`, `ownership.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: reference retry/abort/ownership; explanation ownership tree
+  - Acceptance: AC4 (phase retries) + AC5 — ordering assertion on abort handlers; `failFast` aborts siblings
+
+- [x] **Task 1.4**: Agents, conversations, tools, model-call resilience
+  - Delivers: `defineAgent`, `defineTool` (zod params, `replay`), `HarnessConversation` + `HarnessMessage`; built-in `terreno.agent.turn` task (`request` ⇄ `tools` phases, `maxSteps`); tools run as child tasks; interrupted `never` tools reported to the model; model calls retry 429/5xx then `fallbackModels`; interrupted model requests re-requested; LLM/TOOL spans with usage/cost; `ExecutionEnv` interface (types only) on `rt.env`
+  - Files: `defineAgent.ts`, `defineTool.ts`, `agentLoop.ts`, `modelCall.ts`, `executionEnv.ts`, `models/harnessConversation.ts`, `models/harnessMessage.ts`, tests
+  - Blocked by: 1.3
+  - Skills: `terreno-backend-api`, `claude-api` (model ids), `ai-prompt-governance`
+  - Docs: reference agents/tools/model resilience; explanation agent loop
+  - Acceptance: AC3 (tool rows) + AC4 (model rows) — mock model returns 503 twice then succeeds; fallback used after exhaustion; span tree CHAIN→LLM→TOOL
+
+- [x] **Task 1.5**: Subagents
+  - Delivers: `rt.runAgent(agent, {input, output})` creates a task-owned child conversation, idempotent on resume (finds existing by `ownerTaskId`), returns parsed structured output; AGENT span nests the child's spans
+  - Files: `runtime.ts`, `agentLoop.ts`, tests
+  - Blocked by: 1.4
+  - Skills: `terreno-backend-api`
+  - Docs: reference `runAgent`; explanation subagents
+  - Acceptance: bun test — crash between child creation and completion resumes the same child conversation (no duplicate); abort of parent aborts child
+
+- [x] **Task 1.6**: Extensions, hooks, wraps, memos
+  - Delivers: `defineExtension({name, sections, tools, hooks, wraps})`; `section` rebuilt per request and recorded in transcript; hooks `beforeModelRequest` / `beforeTool` (rewrite or `{block}`) / `afterTool`; `wrapTool`; `rt.memo(key, value?)` via `HarnessMemo`
+  - Files: `extensions.ts`, `models/harnessMemo.ts`, `agentLoop.ts`, tests
+  - Blocked by: 1.4
+  - Skills: `terreno-backend-api`
+  - Docs: reference extensions/hooks/memos
+  - Acceptance: AC6 — blocked tool result reaches the model; memo value survives a new harness instance
+
+- [x] **Task 1.7**: Events, waits, sleep
+  - Delivers: `rt.waitFor(event, {timeout})`, `rt.sleep(duration)`, `harness.sendEvent(taskId, event, payload)`; `waiting` status; runner wakes on event or `timeoutAt`; timeout resolves `undefined`
+  - Files: `runtime.ts`, `runners/inProcessRunner.ts`, tests
+  - Blocked by: 1.3
+  - Skills: `terreno-backend-api`
+  - Docs: reference waits/events
+  - Acceptance: bun test with frozen Luxon clock — event before timeout resumes with payload; timeout path; event sent while owner is down is delivered after restart
+
+- [x] **Task 1.8**: Approvals backend
+  - Delivers: `HarnessApproval` model; `rt.approval(key, {title, summary, payload, timeout, notify?})` with approvers declared per key on `defineTask({approvals})`; `approvalGate({tools, approvers})` extension (memo-backed); `HarnessApp` routes `GET /harness/approvals` (filtered by `approvers`), `approve` / `reject` instanceActions with reason; decision span with `decidedBy`
+  - Files: `approvals.ts`, `models/harnessApproval.ts`, `harnessApp.ts`, `routes/approvals.ts`, tests
+  - Blocked by: 1.6, 1.7
+  - Skills: `terreno-backend-api`, `model-router-actions`
+  - Docs: reference approvals + routes; how-to section "Require human approval"
+  - Acceptance: AC7 — supertest: unpermitted user gets 403 and an empty list; permitted user approves; span `output.decidedBy` equals user id; reject without reason → 400
+
+- [x] **Task 1.9**: SSE event stream + submit
+  - Delivers: `HarnessEvent` log (coalesced deltas with TTL, committed events permanent); `rt.output`; `GET /harness/conversations/:id/events` + `/harness/tasks/:id/events` SSE with `Last-Event-ID` replay then change-stream tail; `submit` instanceAction (`requestId` idempotent, `whenBusy: queue | steer`)
+  - Files: `events.ts`, `models/harnessEvent.ts`, `routes/events.ts`, `routes/conversations.ts`, tests
+  - Blocked by: 1.4
+  - Skills: `terreno-backend-api`, `model-router-actions`
+  - Docs: reference SSE contract (event types, ids, reconnect)
+  - Acceptance: AC9 — two `HarnessApp` instances on one replica set; client disconnects mid-stream, reconnects to the other with `Last-Event-ID`, receives each missed event exactly once
+
+- [x] **Task 1.10**: Version pinning
+  - Delivers: runs resume only on exact `name@version`; `Harness.start()` throws listing unregistered in-flight versions
+  - Files: `harness.ts`, `registry.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: reference "Versioning"; how-to "Ship a new task version"
+  - Acceptance: AC10
+
+- [x] **Task 1.11**: Approvals inbox (admin-frontend)
+  - Delivers: `admin-frontend/src/widgets/harness/HarnessApprovalInbox.tsx` (list, detail, approve/reject with reason, loading/empty/error states) via `adminRequest`; admin custom screen `harness-approvals` (group "AI Harness"); standalone export; example-frontend admin route; `bun run sdk`
+  - Files: `admin-frontend/src/widgets/harness/*`, `ai/src/harness/adminScreens.ts`, `example-frontend/app/admin/*`, tests
+  - Blocked by: 1.8
+  - Skills: `building-admin-interfaces`, `verify-ui-changes`
+  - Docs: `docs/reference/admin-frontend.md` inbox section
+  - Acceptance: AC8 — component tests + Playwright run on web: approve one item, reject one; screenshots in `/opt/cursor/artifacts/`
+
+- [x] **Task 1.12**: Clinical tracer in example-backend + how-to
+  - Delivers: `clinic.intakeSummary` (fetch → `runAgent` summary → approval → EHR write with `replay: "never"`) against a fake EHR model; `HarnessApp` registered in `server.ts`; admin action to start a run; e2e script kills the backend during `summarize`, restarts, approves in the inbox, asserts `filed` and the span tree in Traces
+  - Files: `example-backend/src/harness/*`, `example-backend/src/server.ts`, `example-frontend/e2e/harness-intake.spec.ts`
+  - Blocked by: 1.5, 1.9, 1.10, 1.11
+  - Skills: `verify-ui-changes`, `backend-test-env`
+  - Docs: create `docs/how-to/build-a-durable-workflow.md` using this workflow as the one example
+  - Acceptance: AC2 (e2e) — Playwright spec passes; screenshots of the inbox and the trace waterfall attached
+  - Shipped as two proofs: the kill/restart runs in `example-backend/src/harness/clinicalIntake.crash.test.ts` (spawns the real API process, SIGKILLs it mid-`summarize`, restarts); `harness-intake.spec.ts` approves in the inbox and asserts `filed` and the span tree
+
+## Phase 2 — Multi-instance
+
+- [x] **Task 2.0**: `InProcessRunner` concurrency
+  - Delivers: `new InProcessRunner({concurrency})` (default 8) runs up to N claimed tasks at once, each with its own lease and heartbeat; a slow phase no longer delays other tasks' wakes; `stop()` waits for all in-flight phases
+  - Files: `ai/src/harness/runners/inProcessRunner.ts`, tests
+  - Blocked by: 1.12
+  - Skills: `terreno-backend-api`
+  - Docs: reference "Runners" (concurrency option, ordering guarantees)
+  - Acceptance: bun test — a phase blocked on a gate does not prevent a second task from completing; never more than N concurrent; no task runs twice concurrently
+  - Shipped: fake-context cases in `ai/src/harness/runners/inProcessRunner.test.ts` (default 8, gate, peak, stop waits for all, invalid concurrency) and real-Mongo cases in `ai/src/harness/concurrency.test.ts` (blocked task does not hold up a second; 7 two-phase tasks at concurrency 3 peak at exactly 3 with no task running twice). Roast: PASS (2026-10-04; 76 targeted tests, three mutation checks red)
+
+- [x] **Task 2.1**: `JobsRunner`
+  - Delivers: `@terreno/ai/harness/jobsRunner` with optional peer `@terreno/jobs`; job `terreno.harness.phase` keyed `taskId:phase:attempt`; harness task lease + heartbeat is the authority; importing the root `@terreno/ai` never loads jobs
+  - Files: `ai/src/harness/runners/jobsRunner.ts`, `ai/package.json`, tests
+  - Blocked by: 2.0
+  - Skills: `terreno-backend-api`
+  - Docs: reference "Runners"; how-to "Run on multiple instances"
+  - Acceptance: AC11 — two workers race one phase; exactly one commit; stale owner rejected; knip clean without jobs installed
+  - Shipped: `ai/src/harness/runners/jobsRunner.test.ts` (two-worker race, stale-lease commit rejected, re-dispatch of a dead job, root imports never reach `@terreno/jobs`). Drift: the job key is `taskId:phase:attempt:claims` — `claims` (new `HarnessTask` counter) gives a phase revisited by an event wake or crash replay its own job, since jobs idempotency keys are permanent. Built before Task 2.0; it does not depend on `InProcessRunner` concurrency. Roast: PASS (2026-10-04; 17 targeted tests, ai suite 1185/0, knip clean, two mutation checks red)
+
+- [ ] **Task 2.2**: Runs admin screen
+  - Delivers: task list/tree with status filters, abort, resolve-interrupted (retry/abort/complete + reason), link to trace
+  - Files: `admin-frontend/src/widgets/harness/HarnessRuns*.tsx`, `ai/src/harness/routes/tasks.ts`
+  - Blocked by: 2.1
+  - Skills: `building-admin-interfaces`, `verify-ui-changes`
+  - Docs: admin-frontend reference
+  - Acceptance: Playwright resolves an interrupted EHR write; screenshots
+
+## Phase 3 — Long context
+
+- [ ] **Task 3.1**: Background compaction + manual `compact(instructions)`; originals stay searchable
+- [ ] **Task 3.2**: `reset` / handoff tool control
+- [ ] **Task 3.3**: Conversation forks at any message (parent history by reference)
+- [ ] **Task 3.4**: `defineDoc` typed documents (`scope`, `history: rewindable`, `fork: asOf`), committed atomically with transcripts
+
+Each 3.x task: Blocked by 1.12; Docs: reference + explanation sections; Acceptance: bun tests (10k-message conversation fits budget; fork isolation; doc rewind).
+
+## Phase 4 — Durable chat + multiplayer
+
+- [x] **Task 4.0**: Human gate — `GptHistory` migration strategy → **one-shot migration** script at deploy (decided 2026-10-02)
+- [ ] **Task 4.1**: `/gpt/prompt` on the harness; history mapping
+- [ ] **Task 4.2**: Steering, foreground/background abort, `viewState` over SSE
+- [ ] **Task 4.3**: rtk `useHarnessConversation` SSE hook + `GPTChat` adapter in example-frontend
+
+Acceptance: kill backend mid-chat, reconnect resumes; two browsers see the same view (Playwright, screenshots).
+
+## Phase 5 — Coding agents + malleability
+
+- [x] **Task 5.0**: Human gate — sandbox provider → **Cloud Run Jobs container** (decided 2026-10-02)
+- [ ] **Task 5.1**: `NodeExecutionEnv` + `CodingTools` (read/write/edit/bash with replay classes)
+- [ ] **Task 5.2**: Remote sandbox adapter
+- [ ] **Task 5.3**: Registry hot-replace (running calls finish on old code)
+
+Acceptance: a coding agent fixes a failing test in a fixture repo after a forced crash.

package/src/docs/versioned/57.21.0/tasks/examples-demo-coverage.md

@@ -0,0 +1,219 @@
+# Task List: Examples, Demo, and Test Coverage
+
+See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPlans/examples-demo-coverage.md)
+
+**RTK deprecation flag:** **Partial.** Tasks 5.1–5.3 originally waited on PR #869. `@terreno/syncdb` is in the example apps on this branch; those tasks are unblocked.
+
+## Instructions for the implementing agent
+
+- Derive the missing-component list from `ui/src/index.tsx` at implementation time. The list in the IP is a snapshot and will be stale.
+- When a component turns out to be hard to demo because of a bug, fix the bug and note it — that is a valuable side effect of this work, not a distraction.
+- Per IP decision E4, enforce the existing 95% threshold immediately. Packages below threshold must catch up before CI passes — do not introduce a ratchet floors file.
+- Follow the existing story conventions: read several files in `demo/stories/` first and match their structure, and use only `@terreno/ui` components inside stories.
+- Run `bun run lint`, `bun run demo:compile`, and `bun run ui:test` before each commit.
+
+## Phase 1: Demo coverage — audit and P0
+
+- [x] **Task 1.1**: Audit demo story coverage
+  - Description: Extract the list of components exported from `ui/src/index.tsx`. Extract the list of components registered in `demo/demoConfig.tsx`. Produce the difference. Classify each missing component as P0 (demonstrates a pillar: AI, auth, responsive layout), P1 (common in real apps), P2 (uncommon), or "cannot be demoed in isolation" with a reason. Report the full table in the PR body.
+  - Files: none (findings in the PR body)
+  - Depends on: none
+  - Acceptance: the table is derived from the two actual source files; every missing component has a classification; every "cannot be demoed" entry has a stated reason.
+
+### Task 1.1 audit (2026-09-10, `ui/src/index.tsx` + `demo/demoConfig.tsx`)
+
+Registered stories (65 configs, including OpenAPI Context): Accordion, AddressField, AiSuggestionBox, Avatar, Badge, Banner, BooleanField, Box, Button, Card, CheckBox, ConsentFormScreen, CustomSelectField, DataTable, DateTimeField, EditableCard, EmailField, EmojiSelector, Field, Filter, Heading, HeightField, Icon, IconButton, Link, LoginScreen, MarkdownEditorField, MarkdownView, Modal, MultiselectField, NumberField, OpenAPIContext, Page, Pagination, PasswordField, PhoneNumberField, Popover, RadioField, SectionDivider, SegmentedControl, SelectBadge, SelectField, SidebarNavigation (+ Panel), SideDrawer, SignatureCaptureField, SignatureField, Slider, Spinner, Table (+ Badge/Boolean/Date/IconButton/Number/Text/Title), TapToEdit, Text, TextArea, TextField, Theme, ThumbsUpDownFeedback, Toast, Tooltip, TypedSignatureField, UserInactivity.
+
+`ModalSheet.tsx` does not export a `ModalSheet` identifier; the public component is `SimpleContent`. Matching uses `component:` in `demo/story-config/*.config.tsx` plus `OpenAPIContext` in `demoConfig.tsx`.
+
+| Export | Class | Reason |
+| --- | --- | --- |
+| `GPTChat` | P0 | AI pillar |
+| `SocialLoginButton` | P0 | Auth pillar |
+| `SplitPage` | P0 | Responsive layout pillar |
+| `ActionSheet` | P1 | Common overlay |
+| `SimpleContent` | P1 | ModalSheet public export; bottom sheet |
+| `FilePickerButton` | P1 | Common file input |
+| `Image` | P1 | Common media |
+| `SignUpScreen` | P1 | Auth screen (LoginScreen already demos) |
+| `OAuthButtons` | P1 | Grouped social login |
+| `ErrorPage` | P1 | Common error UI |
+| `ErrorBoundary` | P1 | Common error UI |
+| `DismissButton` | P1 | Common chrome |
+| `ImageBackground` | P1 | Common layout |
+| `MarkdownEditor` | P1 | Editor (field already demos) |
+| `InfoTooltipButton` | P1 | Common help affordance |
+| `InfoModalIcon` | P1 | Common help affordance |
+| `OfflineBanner` | P1 | Sync/offline status |
+| `SyncStatusBanner` | P1 | Sync status |
+| `AttachmentPreview` | P1 | Chat/file UX |
+| `ConflictSheet` | P1 | Sync conflict UX |
+| `AIRequestExplorer` | P1 | AI admin surface |
+| `Body` | P1 | Layout primitive |
+| `PasswordRequirements` | P1 | Auth helper |
+| `UnifiedAddressAutoCompleteField` | P1 | Address (AddressField demos a wrapper) |
+| `WebAddressAutocomplete` | P1 | Web address |
+| `MobileAddressAutocomplete` | P1 | Native address |
+| `Radio` | P2 | Primitive under RadioField |
+| `DraggableList` | P2 | Uncommon |
+| `UpgradeRequiredScreen` | P2 | Uncommon |
+| `GPTMemoryModal` | P2 | GPTChat sub-surface |
+| `ConsentNavigator` | P2 | ConsentFormScreen already demos |
+| `DateTimeActionSheet` | P2 | DateTimeField already demos |
+| `HeightActionSheet` | P2 | HeightField already demos |
+| `DecimalRangeActionSheet` | P2 | Uncommon picker |
+| `NumberPickerActionSheet` | P2 | Uncommon picker |
+| `FilterAccordion` | P2 | Filter already demos |
+| `FilterBoolean` | P2 | Filter already demos |
+| `FilterChangesBadge` | P2 | Filter already demos |
+| `FilterSelectMenu` | P2 | Filter already demos |
+| `TableHeader` | P2 | Table already demos |
+| `TableHeaderCell` | P2 | Table already demos |
+| `TableRow` | P2 | Table already demos |
+| `Signature` | P2 | SignatureField already demos |
+| `Swiper` | P2 | Onboarding helper |
+| `BarsFilterIcon` | P2 | Icon primitive |
+| `ScrollView` | P2 | RN wrapper |
+| `FlatList` | P2 | RN wrapper |
+| `TerrenoProvider` | cannot | Demo root already wraps the app |
+| `ThemeProvider` | cannot | Theme story already exercises theme; provider is shell |
+| `OpenAPIProvider` | cannot | OpenAPI Context story already wraps usage |
+| `IconRegistryProvider` | cannot | Registry is app shell, not a visual component |
+| `TableContextProvider` | cannot | Table stories already wrap table context |
+| `Host` | cannot | Portal host is app shell |
+| `Portal` | cannot | Portal is a host primitive, not a visual story |
+| `PortalContext` | cannot | React context object |
+| `ThemeContext` | cannot | React context object |
+| `Unifier` | cannot | Platform utility singleton, not a component |
+| `SPACING_MAP` | cannot | Constant, not a component |
+| `USSTATESLIST` | cannot | Constant, not a component |
+| `COUNTY_AND_COUNTY_EQUIVALENT_ENTITIES` | cannot | Constant, not a component |
+| `GOOGLE_PLACES_API_RESTRICTIONS` | cannot | Constant, not a component |
+| `SIDEBAR_BADGE_STATUS_MAP` | cannot | Constant, not a component |
+| `SUPPORTED_ORIENTATIONS` | cannot | Constant, not a component |
+| `NATIVE_BREAKPOINT_MIN_WIDTH` | cannot | Constant, not a component |
+| `WEB_BREAKPOINT_MIN_WIDTH` | cannot | Constant, not a component |
+| `DEFAULT_SIGNATURE_FONTS` | cannot | Constant, not a component |
+| `CONFLICT_METADATA_FIELDS` | cannot | Constant, not a component |
+| `NO_CONFLICT_DIFF_FIELDS` | cannot | Constant, not a component |
+| `StyleProp` | cannot | Type re-export |
+| `ViewStyle` | cannot | Type re-export |
+| `OAuthProvider` | cannot | Type, not a component |
+| `OnboardingPage` | cannot | Type, not a component |
+| `PasswordRequirement` | cannot | Type, not a component |
+
+- [x] **Task 1.2**: Add P0 stories
+  - Description: Write stories for every P0 component from Task 1.1 (expected to include `GPTChat`, `SocialLoginButton`, and `SplitPage` — confirm against the audit). Each story shows multiple states where the component supports them: default, loading, error, disabled, and any variant enumerations. `GPTChat` needs a story that works without a live backend — use a static message list rather than wiring a real AI call. `SocialLoginButton` needs all three providers and both variants. `SplitPage` needs a story demonstrating the responsive breakpoint behavior. Register each in `demoConfig.tsx`.
+  - Files: `demo/stories/*.stories.tsx` (new), `demo/demoConfig.tsx`
+  - Depends on: Task 1.1
+  - Acceptance: every P0 component has a story reachable in the running demo (`bun run demo:start`, port 8085); each shows at least two states; `GPTChat`'s story renders with no backend running; `bun run demo:compile` passes.
+
+- [x] **Task 1.3**: Add the demo coverage check
+  - Description: Create `scripts/check-demo-coverage.ts` (Bun, TypeScript, `const` arrow functions with explicit return types). It parses the export list from `ui/src/index.tsx` and the registered components from `demo/demoConfig.tsx`, then fails with a list of unstoried components. Support an allowlist file or an in-script allowlist where each entry requires a comment explaining why the component cannot be demoed. Add a `check:demo-coverage` script to the root `package.json` and wire it into `.github/workflows/ui-demo-ci.yml`.
+  - Files: `scripts/check-demo-coverage.ts` (new), `package.json`, `.github/workflows/ui-demo-ci.yml`
+  - Depends on: Task 1.2
+  - Acceptance: the check passes with the current allowlist; adding a new export to `ui/src/index.tsx` without a story makes it fail and name the component; the CI job runs it.
+
+- [x] **Task 1.4**: Make the demo's `test:ci` real
+  - Description: `demo/package.json`'s `test:ci` is currently `echo 'No tests'`. Replace it with something meaningful: at minimum a smoke test that every registered story renders without throwing, using the `renderWithTheme` helper from `@terreno/ui`'s test utilities. This catches the most common demo breakage — a story that crashes after a component's props change.
+  - Files: `demo/package.json`, `demo/**` test files (new)
+  - Depends on: Task 1.2
+  - Acceptance: `bun run --filter 'terreno-demo' test:ci` runs real tests and passes; deliberately breaking one story's props makes it fail; the test iterates the registered stories rather than a hardcoded list.
+
+## Phase 2: Remaining demo stories
+
+- [x] **Task 2.1**: Add P1 stories
+  - Description: Write stories for every P1 component from the Task 1.1 audit (expected to include `ActionSheet`, `ModalSheet`, `FilePickerButton`, and `Image`). Interactive components need a story that can actually be triggered from the demo UI, not just a static render. Register each in `demoConfig.tsx`.
+  - Files: `demo/stories/*.stories.tsx` (new), `demo/demoConfig.tsx`
+  - Depends on: Task 1.3
+  - Acceptance: every P1 component has a story; interactive components can be opened and dismissed in the running demo; `bun run demo:compile` passes.
+
+- [x] **Task 2.2**: Add P2 stories and close the allowlist
+  - Description: Write stories for the remaining P2 components. For any component that genuinely cannot be demoed in isolation, add it to the allowlist with a specific reason (not "hard to demo"). The goal is an empty or near-empty gap list with a justified allowlist.
+  - Files: `demo/stories/*.stories.tsx` (new), `demo/demoConfig.tsx`, the allowlist
+  - Depends on: Task 2.1
+  - Acceptance: `bun run check:demo-coverage` passes with no unstoried, unallowlisted components; every allowlist entry has a specific reason.
+
+## Phase 3: Coverage enforcement
+
+- [x] **Task 3.1**: Measure current coverage per package
+  - Description: Run every published package's `test:coverage` on a clean `master` and record the actual coverage. Report which packages are below the 95% threshold in the PR body. This is a planning step — do not lower the threshold or add exemptions.
+  - Files: none (findings in the PR body)
+  - Depends on: none
+  - Acceptance: every published package has a measured coverage value; packages below 95% are listed with their gap.
+
+### Task 3.1 coverage (2026-09-10)
+
+Measured with `bun run ../scripts/check-coverage.ts --threshold=0` from each package directory after compile. Figures are the script's `Coverage summary` when present (isolated-test merge); otherwise the Bun `All files` row. Threshold is **95% functions and 95% lines** — not lowered.
+
+| Package | Functions % | Lines % | Below 95%? | Gap |
+| --- | --- | --- | --- | --- |
+| `@terreno/api` | 98.84 | 99.06 | no | — |
+| `@terreno/ui` | 99.78 | 99.65 | no | — |
+| `@terreno/rtk` | 99.67 | 98.98 | no | — |
+| `@terreno/syncdb` | 97.81 | 96.84 | no | — |
+| `@terreno/ai` | 99.21 | 99.63 | no | — |
+| `@terreno/comms` | 96.76 | 98.22 | no | — |
+| `@terreno/mcp` | 99.68 | 97.44 | no | — |
+| `@terreno/feature-flags` | 100.00 | 99.55 | no | — |
+| `@terreno/api-health` | 100.00 | 100.00 | no | — |
+| `@terreno/admin-backend` | 97.25 | 96.65 | no | — |
+| `@terreno/admin-frontend` | 95.11 | 95.55 | no | — |
+| `@terreno/admin-spa` | 100.00 | 100.00 | no | — |
+| `@terreno/test` | 96.34 | 95.32 | no | — |
+
+Packages below 95%: none (all published packages meet the 95% function and line thresholds as of the latest local `test:coverage` runs).
+
+- [x] **Task 3.2**: Wire the threshold into every package CI
+  - Description: Add `scripts/check-coverage.ts` (default 95% threshold) to every published package's CI — either the existing dedicated workflow or the new matrix job from Task 3.3. Packages below threshold when this lands will fail CI until catch-up work merges; track that in the implementation PR.
+  - Files: `.github/workflows/ui-ci.yml`, `ai-ci.yml`, `admin-spa-ci.yml`, `.github/workflows/packages-ci.yml`, package `package.json` files as needed
+  - Depends on: Task 3.1
+  - Acceptance: every published package's CI runs the coverage check at 95%; no package has a permanent exemption.
+
+- [x] **Task 3.3**: Add the matrix CI job for uncovered packages
+  - Description: Per IP question E3, create `.github/workflows/packages-ci.yml` with a matrix over the published packages that lack a dedicated workflow (`admin-backend`, `feature-flags`, `api-health`, `test` — verify the current set against `.github/workflows/`). Each matrix entry runs compile, lint, tests, and the coverage check. Use path filters so the job only runs for the affected package where practical. Follow the repo's required-input validation convention.
+  - Files: `.github/workflows/packages-ci.yml` (new)
+  - Depends on: Task 3.2
+  - Acceptance: the workflow parses as valid YAML; the matrix covers exactly the published packages without their own workflow; each entry runs compile, lint, test, and coverage at 95%.
+
+- [x] **Task 3.4**: Catch up packages below threshold
+  - Description: For each package measured below 95% in Task 3.1, add tests until `scripts/check-coverage.ts` passes. This may be a separate PR if the gap is large; do not merge the CI wiring until every package passes or the IP owner explicitly defers a package with a linked issue.
+  - Files: package test files as needed
+  - Depends on: Task 3.2
+  - Acceptance: `bun run check-coverage` (or per-package equivalent) passes at 95% for every published package.
+
+## Phase 4: Codecov
+
+- [x] **Task 4.1**: Configure Codecov
+  - Description: Add `codecov.yml` configuring per-package flags so each package's coverage is reported separately, a target of "auto" with a small allowed threshold so trivial deltas do not fail PRs, and comment settings that post the delta on pull requests. Add the upload step to every package CI workflow. Note in the file where the `CODECOV_TOKEN` secret must be configured (a maintainer action for a public repo, though public repos often need no token — verify current Codecov requirements before documenting).
+  - Files: `codecov.yml` (new), every package CI workflow
+  - Depends on: Task 3.4
+  - Acceptance: `codecov.yml` is valid; every package workflow uploads with a distinct flag; the token requirement is documented accurately for a public repo.
+
+- [x] **Task 4.2**: Add the coverage badge
+  - Description: Add a Codecov badge to `README.md` next to the existing npm and license badges. Add a "Testing and coverage" section to `CONTRIBUTING.md` explaining: the 95% coverage expectation for new code, that coverage must not drop in a PR, and how to run coverage locally per package.
+  - Files: `README.md`, `CONTRIBUTING.md`
+  - Depends on: Task 4.1
+  - Acceptance: the badge renders and reflects real coverage; the contributing section explains the 95% threshold and gives the local command.
+
+## Phase 5: Example feature matrix
+
+- [x] **Task 5.1**: `[RTK]` Audit example app feature coverage
+  - Description: Build the capability matrix from the IP by reading `example-backend/src/` and `example-frontend/app/`. Resolve every `?`: does an example actually exercise AI structured output, Better Auth, and (after #869) syncdb local-first behavior? For each capability, cite the file that exercises it or record it as a gap. Include capabilities that are not shipped (RBAC, background jobs) marked as such with links to their IPs.
+  - Files: `docs/explanation/example-coverage.md` (new)
+  - Depends on: none (`@terreno/syncdb` is in-tree; PR #869 closed)
+  - Acceptance: no `?` remains; every "yes" cites a file path; every gap is explicit; unshipped capabilities link their IPs.
+
+- [x] **Task 5.2**: `[RTK]` Fill the highest-value example gaps
+  - Description: For each gap found in Task 5.1, either add the example or record it as a known gap with an issue. Prioritize capabilities the launch documentation depends on — if a tutorial or reference page describes something with no working example, that is the highest priority because the docs claim will be tested by readers. Do not add examples for unshipped features.
+  - Files: `example-backend/src/**`, `example-frontend/app/**`, `docs/explanation/example-coverage.md`
+  - Depends on: Task 5.1
+  - Acceptance: every gap that a launch document depends on is filled with a working example; remaining gaps are recorded with issue links; both example apps still pass their CI.
+
+Recorded gaps (2026-09-11): AI structured output → [#1010](https://github.com/TerrenoLabs/terreno/issues/1010); generic background jobs → [#1188](https://github.com/TerrenoLabs/terreno/issues/1188). No launch tutorial currently depends on either.
+
+- [x] **Task 5.3**: Link the matrix into the contribution process
+  - Description: Add a note to `CONTRIBUTING.md` and the PR template: when adding a framework capability, add or update the example that exercises it and update `docs/explanation/example-coverage.md`. This is what keeps the matrix true. Link the matrix from `docs/explanation/README.md`.
+  - Files: `CONTRIBUTING.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `docs/explanation/README.md`
+  - Depends on: Task 5.1
+  - Acceptance: both the contributing guide and the PR template reference the requirement; the matrix is linked from the explanation index.