@terreno/mcp 57.0.0 → 57.2.0

package/dist/docs/versioned/57.1.0/implementationPlans/docs-site-and-versioning.md

@@ -0,0 +1,139 @@
+# Implementation Plan: Documentation Site, Versioned Docs, and Docs-Maintenance Skills
+
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1086
+*When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
+
+## Overview
+
+Terreno's docs today are a Diátaxis-organized markdown tree in `docs/` plus five curated bundles inside `mcp-server/src/docs/resources/`. There is no rendered site, no versioning, and no automation keeping docs in sync with code. The UI demo (an Expo web export of `demo/`, deployed to Netlify, with per-component deep links at `/demo/[component]` and `/dev/[component]`) is the closest thing to component documentation, but it isn't connected to any written docs.
+
+This plan delivers:
+
+1. A **Docusaurus site** (`website/`) rendering the existing `docs/` tree, with generated reference pages per package and per UI component.
+2. **Versioned docs** cut on every release, matching Terreno's lockstep package versioning — this is what unblocks version-aware MCP doc search (recommendation 4 from the Boost comparison).
+3. **Demo integration**: every component doc page embeds the live demo via iframe deep link, with an "open in playground" escape hatch.
+4. **Skills that keep docs current**: an `update-docs` skill wired into the PR workflow, a `docs-audit` drift detector, and release-skill extensions.
+
+**Key design decisions:**
+
+- **Docusaurus** over Starlight/Fumadocs/VitePress because versioned docs are first-class (`docusaurus docs:version X.Y.Z`), it's React (same mental model as the rest of the repo, and iframe/MDX component embeds are trivial), and local search (`docusaurus-search-local`) works without a SaaS dependency. Algolia DocSearch can replace local search later if wanted.
+- **Docs version = release version.** All nine packages publish in lockstep from one tag (see `.rulesync/skills/release/SKILL.md`), so a single docs version per release is unambiguous. Cut a docs version only for minor/major releases; patches update the existing version in place. Retain the last ~4 versions plus `next` to keep build times sane.
+- **Generated, not hand-written, reference pages.** Component pages are generated from `ui-types-documentation.json` (the TypeDoc output the demo already produces via `generate-types`); package API references come from `typedoc-plugin-markdown`. Hand-written content stays in tutorials/how-to/explanation.
+- **`docs/` stays the source of truth** in its current location; the site consumes it via Docusaurus's path config rather than moving files, so existing relative links, the MCP sync script, and in-repo readers keep working.
+- **The MCP server consumes the same artifacts.** `terreno_search_docs` (from the `mcp-boost-parity.md` plan) gains a `version` parameter; the MCP build syncs `website/versioned_docs/` so the hosted server can answer for any retained version.
+- **Netlify hosting** for the site, like the demo — PR deploy previews are the main reason (reviewers and the `verify-ui-changes` skill can check rendered docs per PR).
+
+## Architecture
+
+```
+website/
+├── docusaurus.config.ts        # docs path → ../docs, versions config, search plugin
+├── sidebars.ts                 # generated + manual sidebar (Diátaxis top-level)
+├── src/
+│   ├── components/
+│   │   └── ComponentDemo.tsx   # iframe embed of demo /demo/[component]?embed=1
+│   └── css/custom.css          # Terreno branding
+├── scripts/
+│   ├── generate-component-docs.ts  # ui-types-documentation.json → docs/reference/components/*.mdx
+│   └── generate-api-reference.ts   # typedoc-plugin-markdown per package
+├── versioned_docs/             # created by `docs:version` at release time
+├── versioned_sidebars/
+└── versions.json
+```
+
+### Content mapping
+
+| Site section | Source |
+|---|---|
+| Tutorials, How-to, Explanation | existing `docs/tutorials`, `docs/how-to`, `docs/explanation` (hand-written) |
+| Reference: packages | `typedoc-plugin-markdown` over `api`, `rtk`, `feature-flags`, `ai`, `admin-backend` + existing `docs/reference/*.md` overviews |
+| Reference: UI components | generated `.mdx` per component: description, props table from `ui-types-documentation.json`, `<ComponentDemo />` embed, link to story source in `demo/stories/` |
+| Upgrade guides | `mcp-server/src/docs/upgrades/<version>.md` (from the Boost-parity plan), rendered as a "Upgrading" section |
+| `docs/implementationPlans`, `docs/tasks` | excluded from the site (internal) |
+
+## Demo Integration
+
+The demo already routes per component (`demo/app/demo/[component].tsx`), so embedding needs only:
+
+1. **Embed mode in the demo**: support `?embed=1` in `demo/app/demo/_layout.tsx` — hide the sidebar/navigation chrome and render just the component playground. Persist via context so internal navigation keeps the flag.
+2. **`ComponentDemo` MDX component** in the site: responsive iframe pointing at `https://<demo-host>/demo/<Component>?embed=1`, with a fallback link "Open in playground" and lazy loading.
+3. **Environment wiring**: demo base URL set per environment (`DEMO_URL` build arg) so docs previews can point at the production demo.
+4. Optional later: reverse links — the demo's component page links to its doc page.
+
+Versioning caveat: the embedded demo always shows the *latest* deployed demo, even on older docs versions. Acceptable for v1; if it becomes a problem, deploy the demo export per release alongside versioned docs (`/demo/0.18/...`).
+
+## Versioning & CI
+
+### Release-time flow (extends `publish-on-tag.yml` and the `release` skill)
+
+1. Tag `X.Y.0` pushed → packages publish as today.
+2. New `docs-version` job (after publishes succeed): `cd website && bun docusaurus docs:version X.Y.0`, commit alongside the existing `chore: bump package versions` commit, trigger site deploy.
+3. Patch tags skip `docs:version`; the deploy rebuilds the current version with any docs fixes merged since.
+4. Prune: keep `next` + last 4 versions; the job deletes older `versioned_docs/` entries.
+
+### Continuous flow
+
+- Every PR: Netlify deploy preview of the site; `generate-component-docs` runs in CI so a new `@terreno/ui` component without TypeDoc-extractable props fails visibly.
+- Master: deploy `next` docs.
+
+### MCP integration (unblocks recommendation 4)
+
+- `mcp-server`'s `sync-docs` build step copies `website/versioned_docs/` (and `next` from `docs/`) into the image, namespaced by version.
+- `terreno_search_docs` accepts `version?: string`; the agent passes the consumer's `@terreno/*` version (from `application_info` in the local MCP, or `package.json`). Unmatched versions fall back to nearest retained version, with a note in the response.
+- `terreno_get_component_docs` gets the same parameter.
+
+## Skills to Keep Docs Current
+
+All live in `.rulesync/skills/` and sync via rulesync like existing skills.
+
+### `update-docs` (new)
+
+Triggered when a PR changes public API surface. Instructs the agent to:
+
+- Map changed exports to affected pages (component → its generated page source + story; `modelRouter`/`TerrenoApp` options → `docs/reference/api.md` + relevant how-tos).
+- Regenerate `ui-types-documentation.json` (`generate-types`) and component pages when `@terreno/ui` props change.
+- Update or add how-to entries for new user-facing capabilities.
+- Wire into the existing `implement` and `create-pr` skills: both gain a step — "if public APIs changed, run the `update-docs` skill before opening the PR."
+
+### `docs-audit` (new)
+
+Drift detector, runnable on demand or on a weekly scheduled CI job that opens an issue/agent task:
+
+- Diff TypeDoc-exported symbols vs. documented pages; list undocumented components, props, and exported functions.
+- Find docs referencing removed/renamed exports (broken symbol references, dead `docs/` links — Docusaurus's broken-link checker covers internal links at build time).
+- Flag stale code samples by compiling fenced `ts` blocks marked `check` against current packages.
+- Output a prioritized fix list the agent (or a human) works through.
+
+### Extensions to existing skills
+
+- **`release`**: add "cut docs version + verify site deploy" and "write `upgrades/<version>.md` if breaking changes were flagged" steps.
+- **`verify-ui-changes`**: when a new component or prop ships, require the story *and* the generated doc page to render in the deploy preview.
+- **`improve-rulesync`**: note that user-facing guidance belongs in `docs/` (site) while agent-facing guidance belongs in `.ai/`/rules — with cross-links rather than duplication.
+
+## Notifications
+
+Weekly `docs-audit` CI posts its report as a GitHub issue (reusing the Zoom notification pattern from `publish-on-tag.yml` is optional).
+
+## Phases
+
+### Phase 1: Site skeleton
+- Scaffold `website/` (Docusaurus, TS preset), point docs path at `../docs`, exclude `implementationPlans`/`tasks`, Terreno branding, local search plugin, Netlify deploy + PR previews.
+
+### Phase 2: Generated reference
+- `generate-component-docs.ts` from `ui-types-documentation.json`; `?embed=1` mode in the demo; `ComponentDemo` embeds; `typedoc-plugin-markdown` API reference for `api` and `rtk` (others follow).
+
+### Phase 3: Versioning
+- `docs:version` release job, retention pruning, version dropdown; MCP `sync-docs` + `version` parameter on search tools (coordinates with `mcp-boost-parity.md` Phase 1).
+
+### Phase 4: Skills
+- `update-docs`, `docs-audit`, release/verify-ui-changes/implement skill extensions, weekly audit CI job.
+
+## Feature Flags & Migrations
+
+None. The site is additive; `docs/` files are not moved. The only behavioral change to existing workflows is the new steps in `release` and `create-pr` skills.
+
+## Risks
+
+- **Generated-page churn**: regenerating component pages on every `ui` change creates diff noise; mitigate by generating at build time (not committed) except for the versioned snapshots.
+- **Expo web export quirks in iframes**: the demo uses `NODE_OPTIONS=--openssl-legacy-provider` and a Netlify asset fix-up script; embed mode needs testing across the docs site's origin (CSP/frame-ancestors on Netlify must allow the docs host).
+- **Version sprawl**: each retained version is a full docs copy in git and in the MCP image; the retention policy (4 versions) and excluding generated API reference from versioning (regenerate from tagged source instead) are the levers if size becomes a problem.

package/dist/docs/versioned/57.1.0/implementationPlans/docs-tutorials-ai-first.md

@@ -0,0 +1,146 @@
+# Implementation Plan: AI-First Tutorials
+
+**Status:** Draft — blocked on PR #869
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1010
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`docs-reference-coverage`](docs-reference-coverage.md), [`ai-dev-loop-boost`](ai-dev-loop-boost.md), [`deployment-foundation`](deployment-foundation.md)
+**RTK deprecation flag:** **Blocked** — every tutorial writes frontend data code. Must be written against the merged syncdb + Better Auth surface.
+
+## Goal
+
+Give a new developer a learning path, and make the AI-assisted path the default one. Today `docs/tutorials/` contains a single 45-line page that says "run the example full stack" and omits `bun run bootstrap`, the required environment variables, the MongoDB replica-set requirement, and the seeded login credentials — meaning a new user following it exactly will fail at step two. There is no tutorial anywhere for the MCP server, the AI package, the admin panel, or deploying.
+
+The Diátaxis split matters here: tutorials teach by doing a complete thing; how-to guides solve one problem for someone who already knows the system. Terreno has how-to guides and no tutorials.
+
+## Non-Goals
+
+- Video content.
+- Reference documentation (owned by [`docs-reference-coverage`](docs-reference-coverage.md)).
+- The blog-post app build (owned by [`build-terreno-app-validation`](build-terreno-app-validation.md), which consumes these tutorials as its input).
+- Teaching React Native, Expo, or MongoDB fundamentals — link out instead.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| T1 | Examples vs bootstrap entry | **C** — two entry points on the tutorials index |
+| T2 | Agent assumed? | **A** — agent-first; manual steps in collapsible sections |
+| T3 | Tutorial app | **B** — new small app (not todos, not the blog-post app) |
+| T4 | Deploy target in tutorial | **A** — Vercel, **pending [`deploy-to-vercel`](deploy-to-vercel.md) spike** (interim split topology until V1 closes) |
+| T5 | MongoDB setup | **B (Atlas) + local Mongo** — no Docker |
+
+## Architecture
+
+### The tutorial set
+
+| # | Tutorial | Time | Teaches |
+|---|----------|------|---------|
+| 0 | `run-the-examples.md` | 10 min | The stack exists and works; what each package does |
+| 1 | `your-first-app.md` | 30 min | Bootstrap → model → route → screen → running on web and phone |
+| 2 | `build-with-ai.md` | 30 min | MCP setup, generators, `read_logs`/`last_error`, the fix loop |
+| 3 | `add-ai-features.md` | 25 min | `@terreno/ai`: streaming chat, structured output, request logging |
+| 4 | `add-an-admin-panel.md` | 20 min | `AdminApp` registration, admin screens, admin-only permissions |
+| 5 | `deploy-your-app.md` | 25 min | Vercel deploy (topology per deploy-to-vercel spike), env vars, first production login |
+
+Every tutorial ends with: what you built, what to read next, and the corresponding reference page.
+
+### Fixing the getting-started gap
+
+`docs/tutorials/getting-started.md` becomes `run-the-examples.md` and gains the five things it is missing:
+
+1. `bun run bootstrap` (not `bun install` — packages must be compiled)
+2. `MONGO_URI` plus Better Auth secrets (`BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`) — tutorials target syncdb + Better Auth only per program P7; do not document the legacy JWT path
+3. That MongoDB **must** be a replica set, with the symptom when it is not
+4. `bun run backend:seed` and the seeded credentials
+5. That the web app shows one-time Terms/Privacy/Consent modals (including a signature draw) before the main screen — a first-run surprise that reads as a bug
+
+### The AI tutorial's arc
+
+Tutorial 2 is the differentiator and needs a real narrative, not a tool list:
+
+1. Wire up both MCP servers (hosted + `terreno-mcp-local`) in the reader's editor.
+2. Ask the agent to add a feature; it calls `terreno_search_docs`, then the generators.
+3. Introduce a deliberate bug (a validation error, a missing permission).
+4. The agent calls `last_error` and `read_logs`, finds it across backend and app sources, fixes it.
+5. Ask the agent to inspect client state (`get_rtk_state` → syncdb equivalent) and navigate the running app.
+6. Regenerate the SDK after the API change and see the typed client update.
+
+Point 4 is the moment the reader understands why this is different from pasting code into a chat window. It depends on Boost (#802) being merged.
+
+### Deferred: `docs/tutorials/README.md`
+
+The tutorials index must state the recommended order and the time budget, and link the how-to tree for readers who already know what they want.
+
+## Models / APIs
+
+None new. Tutorials 1 and 3 create models and routes *in the reader's app*; the tutorial app's schema must be defined in the tutorial itself and kept trivial (one or two models).
+
+## Notifications
+
+None.
+
+## UI
+
+The tutorial app's screens are written by the reader. No changes to `@terreno/ui`.
+
+## Phases
+
+1. **Fix and split the entry point** — `run-the-examples.md` with all five missing pieces; tutorials index.
+2. **`your-first-app.md`** — the core build tutorial.
+3. **`build-with-ai.md`** — depends on merged #802.
+4. **`add-ai-features.md`** and **`add-an-admin-panel.md`**.
+5. **`deploy-your-app.md`** — depends on [`deploy-to-vercel`](deploy-to-vercel.md).
+6. **Validation** — a fresh-environment run of every tutorial, timed, by someone who did not write it.
+
+## Feature Flags & Migrations
+
+None. Renaming `getting-started.md` requires a Docusaurus redirect and an audit of inbound links (`docs/README.md`, `docs/how-to/create-a-model.md`, the MCP resources, and `AGENTS.md` all reference it).
+
+## Not Included / Future Work
+
+- A tutorial for `@terreno/syncdb` offline behavior specifically (the migration guide covers it; a dedicated offline tutorial is a good follow-up).
+- Native build/TestFlight tutorial (the `expo-dev-client` and `expo-deployment` skills cover it).
+- Multi-tenant / organization setup tutorial.
+- Video walkthroughs.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/tutorials/README.md`
+- `docs/tutorials/run-the-examples.md` (from `getting-started.md`)
+- `docs/tutorials/your-first-app.md`
+- `docs/tutorials/build-with-ai.md`
+- `docs/tutorials/add-ai-features.md`
+- `docs/tutorials/add-an-admin-panel.md`
+- `docs/tutorials/deploy-your-app.md`
+
+**Modify**
+
+- `docs/tutorials/getting-started.md` (removed; redirect added)
+- `docs/README.md`, `docs/how-to/README.md`
+- `website/docusaurus.config.ts` (redirect, sidebar order)
+- `mcp-server/src/docs/resources/overview.md` (point agents at the tutorials)
+
+## Task List
+
+See [`docs/tasks/docs-tutorials-ai-first.md`](../tasks/docs-tutorials-ai-first.md).
+
+## Acceptance Criteria
+
+- [ ] Six tutorials exist, each stating its time budget, prerequisites, and what the reader will have built.
+- [ ] `run-the-examples.md` includes `bun run bootstrap`, every required environment variable, the replica-set requirement with its failure symptom, `bun run backend:seed` with the seeded credentials, and a note about the first-run consent modals.
+- [ ] Following `run-the-examples.md` on a clean machine reaches a logged-in web app with no step requiring outside knowledge.
+- [ ] Following `your-first-app.md` produces a working app with one model, CRUD routes, and a list plus detail screen, running on both web and a device or simulator.
+- [ ] `build-with-ai.md` includes the deliberate-bug exercise and the reader observes `last_error` locating it.
+- [ ] `add-ai-features.md` produces a working streaming chat screen and one structured-output call, with requests visible in the `AIRequest` log.
+- [ ] `add-an-admin-panel.md` produces a working admin panel with a registered model and admin-only access verified by logging in as a non-admin.
+- [ ] `deploy-your-app.md` ends with a public URL and a successful login against the deployed backend.
+- [ ] Every tutorial's commands are executed during validation, not just written.
+- [ ] `getting-started.md`'s old URL redirects; no inbound link is broken; `bun run website:build` passes.

package/dist/docs/versioned/57.1.0/implementationPlans/examples-demo-coverage.md

@@ -0,0 +1,163 @@
+# Implementation Plan: Examples, Demo, and Test Coverage
+
+**Status:** Draft — key decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1016
+**Priority:** Medium
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`docs-reference-coverage`](docs-reference-coverage.md) (demo README)
+**RTK deprecation flag:** **Partial** — example-app tasks touch the data layer and are `[RTK]` marked. The demo app is `@terreno/ui`-only and has no data layer, so its tasks are safe now.
+
+## Goal
+
+Close the credibility gaps a prospective adopter checks before trusting a framework: does the component library have visible examples, are the claimed features actually exercised, and does CI enforce the quality bar the project claims.
+
+Three concrete problems today:
+
+1. **The demo app covers roughly 58 of the library's components.** Notable omissions include `GPTChat`, `ActionSheet`, `SplitPage`, `SocialLoginButton`, `DraggableList`, `FilePickerButton`, `Image`, `ModalSheet`, and `UpgradeRequiredScreen`. A component with no visible example is a component people assume is broken. `demo/package.json`'s `test:ci` is `echo 'No tests'`.
+2. **Coverage gates are enforced unevenly.** `api`, `rtk`, and `mcp-server` CI enforce the 95% threshold via `scripts/check-coverage.ts`. `ui`, `ai`, `admin-backend`, `admin-frontend`, `admin-spa`, `feature-flags`, and `api-health` have `test:coverage` scripts but no CI job enforcing them. Three published packages have no dedicated CI workflow at all.
+3. **No public coverage signal.** No badge, no Codecov, so the claim "well tested" is unverifiable from outside.
+
+## Non-Goals
+
+- Raising coverage thresholds.
+- Writing tests for every uncovered line (the daily test-improver workflow already chips at this).
+- Building a fourth example app.
+- Visual regression testing.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| E1 | Demo story for every UI component? | **B** — CI-enforced exports + allowlist |
+| E2 | Codecov / badge | **A** |
+| E3 | Dedicated CI per package | **B** — matrix workflow |
+| E4 | Enforce coverage below threshold? | **A** — enforce immediately; failing packages catch up first |
+| E5 | Example feature-parity checklist | **A** |
+
+## Architecture
+
+### Demo story coverage
+
+`demo/` is an Expo Router app where each component demo is a story in `demo/stories/*.stories.tsx` registered in `demoConfig.tsx`. Adding coverage means adding stories and registering them.
+
+The enforcement mechanism: a script that reads the export list from `ui/src/index.tsx`, reads the registered stories from `demoConfig.tsx`, and fails when an exported component has neither a story nor an allowlist entry. Run in `ui-demo-ci.yml`.
+
+Priority for the missing stories — highest-visibility first:
+
+| Priority | Components | Why |
+|----------|-----------|-----|
+| P0 | `GPTChat`, `SocialLoginButton`, `SplitPage` | Directly demonstrate the AI and auth pillars and the responsive web layout |
+| P1 | `ActionSheet`, `ModalSheet`, `FilePickerButton`, `Image` | Common in real apps |
+| P2 | `DraggableList`, `UpgradeRequiredScreen`, remaining gaps | Less common |
+
+Derive the actual missing list from the export list at implementation time rather than trusting this table.
+
+### Coverage enforcement
+
+```mermaid
+flowchart LR
+  S["scripts/check-coverage.ts<br/>(exists)"]
+  T["95% threshold<br/>(per bunfig.toml)"]
+  M["ci: matrix job for packages<br/>without dedicated workflows"]
+  E["existing package CI<br/>api, rtk, mcp, ui, ai, admin-spa"]
+  C["Codecov upload<br/>+ per-PR delta"]
+  S --> T
+  T --> M
+  T --> E
+  M --> C
+  E --> C
+```
+
+Per decision E4, enforce the existing 95% threshold immediately on every published package. Packages currently below threshold must catch up before the gate passes CI — no ratchet floors file. The daily test-improver workflow continues to raise coverage over time.
+
+### Example app feature matrix
+
+The repo states that `example-frontend` and `example-backend` serve as documentation and integration tests. That is only true if it is checked. A matrix in `docs/explanation/example-coverage.md` maps each framework capability to whether an example exercises it:
+
+| Capability | example-backend | example-frontend | Gap |
+|------------|-----------------|------------------|-----|
+| `modelRouter` CRUD | yes | yes | — |
+| Owner permissions | yes | yes | — |
+| Admin panel (embedded) | yes | yes | — |
+| Admin SPA | yes | n/a | — |
+| AI streaming chat | yes | yes | — |
+| AI structured output | ? | ? | verify |
+| Feature flags + live updates | yes | yes | — |
+| Websockets / realtime | yes | yes | — |
+| Consent forms | yes | yes | — |
+| File upload / GCS | yes | yes | — |
+| Better Auth | ? | ? | verify |
+| syncdb local-first | (from #869) | (from #869) | verify after merge |
+| RBAC | no | no | not shipped |
+| Background jobs | no | no | not shipped |
+
+Every `?` must be resolved by reading the example source, and every real gap either filled or recorded as a known gap.
+
+## Models / APIs / Notifications
+
+None.
+
+## UI
+
+New demo stories only. No changes to `@terreno/ui` components except bug fixes discovered while writing stories — which is a common and welcome side effect.
+
+## Phases
+
+1. **Demo coverage** — audit, P0 stories, then the enforcement check.
+2. **Remaining demo stories** — P1 and P2.
+3. **Coverage enforcement** — wire the 95% threshold into every package CI (matrix job for packages without dedicated workflows).
+4. **Codecov** — upload and badges.
+5. **Example feature matrix** — audit and fill or record gaps.
+
+## Feature Flags & Migrations
+
+None. Enforcing the threshold immediately may require a short catch-up period for packages currently below 95%; track that work in the implementation PR rather than lowering the bar.
+
+## Not Included / Future Work
+
+- Visual regression / screenshot testing of the demo.
+- Raising coverage thresholds beyond current levels.
+- Publishing the demo app to app stores.
+- Consolidating the Appium and Maestro E2E suites.
+
+## Files to Create / Modify
+
+**Create**
+
+- `demo/stories/*.stories.tsx` (the missing components)
+- `scripts/check-demo-coverage.ts`
+- `.github/workflows/packages-ci.yml` (matrix for packages without dedicated CI)
+- `docs/explanation/example-coverage.md`
+- `codecov.yml`
+
+**Modify**
+
+- `demo/demoConfig.tsx`
+- `demo/package.json` (`test:ci` currently a no-op)
+- `.github/workflows/ui-demo-ci.yml`, `ui-ci.yml`, `ai-ci.yml`, `admin-spa-ci.yml`
+- `README.md` (coverage badge)
+- `CONTRIBUTING.md` (coverage expectations)
+
+## Task List
+
+See [`docs/tasks/examples-demo-coverage.md`](../tasks/examples-demo-coverage.md).
+
+## Acceptance Criteria
+
+- [ ] Every component exported from `ui/src/index.tsx` has a demo story or an allowlist entry with a stated reason.
+- [ ] `bun run scripts/check-demo-coverage.ts` fails when a newly exported component has no story and no allowlist entry, and runs in `ui-demo-ci.yml`.
+- [ ] `demo/package.json`'s `test:ci` runs something real.
+- [ ] Stories exist for all P0 components, each showing multiple states (default, loading, error, disabled) where applicable.
+- [ ] Every published package's CI runs `scripts/check-coverage.ts` at the 95% threshold.
+- [ ] Packages currently below 95% have a tracked catch-up plan; no package is permanently exempt.
+- [ ] Every published package is covered by CI running its tests and coverage check, either through a dedicated workflow or the matrix job.
+- [ ] Codecov receives uploads from every package's CI and reports per-PR deltas.
+- [ ] `README.md` shows a coverage badge that reflects reality.
+- [ ] `docs/explanation/example-coverage.md` resolves every `?` in the capability matrix, and each real gap is either filled with an example or recorded as a known gap with an issue link.
+- [ ] `CONTRIBUTING.md` states the 95% coverage expectation and how to run coverage locally per package.
+- [ ] `bun run lint`, `bun run compile`, and the full test suite pass.