@terreno/mcp 57.2.0 → 57.4.0

package/src/docs/versioned/next/tasks/create-terreno-app.md

@@ -0,0 +1,82 @@
+# Tasks: create-terreno-app scaffolding CLI
+
+Plan: [`docs/implementationPlans/create-terreno-app.md`](../implementationPlans/create-terreno-app.md)
+
+**Status:** Approved — all in-scope tasks Roast PASS. **next: brew**.  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1174
+
+## Instructions for the implementing agent
+
+- Load `update-docs`. Generator/CLI tests use Bun `expect` in `create-terreno-app/` and `mcp-server/`.
+- TDD: failing test first per task. Public seam is the CLI bin / `generateAllFiles` / `handleBootstrapToolCall`, not private string helpers.
+- Do not clone `example-*`. Do not copy `example-backend/Dockerfile`. Do not add prompts or `bun install` to the CLI.
+- Hosted MCP must never write disk. Local write requires `TERRENO_MCP_WRITE_SCAFFOLD=1`.
+- After moving generators, `mcp-server` tests for dump shape must stay green.
+
+---
+
+### Phase 1: Shared generator
+
+- [x] **Task 1.1**: Workspace package + extracted `generateAllFiles`
+  - Delivers: `create-terreno-app` workspace package exports `generateAllFiles`; generated `@terreno/*` versions are `^` + this package’s `version`; `mcp-server` imports the export instead of inlining generators
+  - Files: `create-terreno-app/package.json`, `create-terreno-app/src/generate.ts` (and helpers split as needed), `create-terreno-app/src/__tests__/generate.test.ts`, `mcp-server/src/bootstrap.ts`, `mcp-server/package.json`, root `package.json` workspaces
+  - Blocked by: none
+  - Docs: none (package README stub only)
+  - Skills: `update-docs`
+  - Acceptance: `generateAllFiles({appName, appDisplayName})` returns the previous file set (backend, frontend, CI, MCP, seed); every `@terreno/*` range is `^<package.json version>`; `bun test` in `create-terreno-app` and `mcp-server` dump tests pass; no `"latest"` for `@terreno/*`
+
+---
+
+### Phase 2: CLI writer
+
+- [x] **Task 2.1**: `create-terreno-app` bin writes an empty target
+  - Delivers: `bunx create-terreno-app my-app --display-name "My App"` (cwd or explicit parent) writes files via `writeScaffold`; `--yes` derives display name; missing names or non-empty target (anything except `.git` / `.gitignore`) exits non-zero without writing app files; does not run install/seed
+  - Files: `create-terreno-app/src/cli.ts`, `create-terreno-app/src/writeScaffold.ts`, `create-terreno-app/src/__tests__/cli.test.ts`, `create-terreno-app/package.json` `bin`
+  - Blocked by: Task 1.1
+  - Docs: `create-terreno-app/README.md` (command table)
+  - Skills: `update-docs`
+  - Acceptance: temp-dir test writes `backend/package.json` and `frontend/package.json`; stdout includes next-step commands; dirty-dir test leaves the tree unchanged and non-zero; `--yes` without `--display-name` succeeds
+
+---
+
+### Phase 3: Deployable scaffold
+
+- [x] **Task 3.1**: Consumer Dockerfile, env examples, README deploy section
+  - Delivers: generator adds a consumer backend `Dockerfile` (`oven/bun`, `PORT`, `0.0.0.0`, `/health`), `backend/.env.example` + `frontend/.env.example`, keeps local `.env` defaults, README links [deployment baseline](../explanation/deployment-baseline.md), [deploy backend to Cloud Run](../how-to/deploy-backend-to-cloud-run.md), [build for web](../how-to/build-for-web.md)
+  - Files: generator helpers in `create-terreno-app/src/`, `create-terreno-app/src/__tests__/generate.test.ts`
+  - Blocked by: Task 1.1
+  - Docs: generated README in the scaffold (not repo docs yet)
+  - Skills: `update-docs`
+  - Acceptance: file list includes `Dockerfile` and both `.env.example` files; Dockerfile does not `COPY` Terreno monorepo packages or `example-backend`; README contains those three doc paths or their published URLs
+
+---
+
+### Phase 4: MCP delegate
+
+- [ ] **Task 4.1**: Dump names the CLI; write path uses the same generator
+  - Delivers: `handleBootstrapToolCall` dump leads with `bunx create-terreno-app …`; when `targetDir` is set and `TERRENO_MCP_WRITE_SCAFFOLD=1`, writes `<targetDir>/<appName>` with the same files as the CLI; without the env guard, `targetDir` is ignored and nothing is written
+  - Files: `mcp-server/src/bootstrap.ts`, `mcp-server/src/local/` (set the env guard in the local entry), `mcp-server/src/__tests__/bootstrap.test.ts`, `docs/reference/mcp-server.md`
+  - Blocked by: Task 1.1, Task 2.1
+  - Docs: `docs/reference/mcp-server.md` (`targetDir`, write guard, CLI)
+  - Skills: `update-docs`
+  - Acceptance: dump test asserts CLI command present; write test with env + temp `targetDir` creates files; write test without env does not create files even with `targetDir`
+
+---
+
+### Phase 5: Docs, publish, dogfood skill
+
+- [x] **Task 5.1**: Human docs + getting-started + how-to
+  - Delivers: first-run path is the CLI; clone-examples stays as a secondary path
+  - Files: `docs/tutorials/getting-started.md`, `docs/how-to/create-a-terreno-app.md`, `docs/how-to/README.md`, `docs/README.md` (package row)
+  - Blocked by: Task 2.1, Task 3.1
+  - Docs: those files
+  - Skills: `update-docs`
+  - Acceptance: getting-started step 1 is `bunx create-terreno-app` (or `npm create terreno-app`); how-to lists flags, refuse-non-empty, seed login, Dockerfile note; indexes link the how-to
+
+- [x] **Task 5.2**: Publish pipeline, changelog, build-terreno-app skill
+  - Delivers: unscoped package on tag publish; dogfood Phase 2 prefers the CLI and treats MCP dump as fallback
+  - Files: `.github/workflows/publish-on-tag.yml`, CircleCI publish list / `scripts/ci/publish-package.sh` if it enumerates packages, `changelog/unreleased/create-terreno-app.md`, `.rulesync/skills/build-terreno-app/SKILL.md` then `bun run skills:sync`, `docs/explanation/roadmap-seed-issues.md` (IP/task links already present — confirm)
+  - Blocked by: Task 2.1, Task 4.1, Task 5.1
+  - Docs: changelog fragment; skill; upgrade note if the next version file exists
+  - Skills: `update-docs`, `update-agent-docs`
+  - Acceptance: publish job includes `create-terreno-app`; changelog fragment `category: Added`; skill Phase 2 says to run `create-terreno-app` first; `bun run skills:sync` updates generated skill copies

package/src/docs/versioned/next/tasks/datatable-server-side-filtering.md

@@ -0,0 +1,87 @@
+# Tasks: DataTable server-side filtering and search
+
+Plan: [`docs/implementationPlans/datatable-server-side-filtering.md`](../implementationPlans/datatable-server-side-filtering.md)  
+**Status:** Pick complete — tasks 1.1–4.1 implemented
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1177
+
+**Feature profile:** false (full IP)
+
+## Instructions for the implementing agent
+
+- Load `terreno-ui`, `update-docs`, `verify-ui-changes`. Admin tasks also load `building-admin-interfaces`.
+- TDD: failing test first per task.
+- Run `bun test` in touched packages (`ui`, `admin-frontend`, `admin-backend`).
+- Do not import RTK, axios, or admin packages from `@terreno/ui`.
+- Do not change modelRouter list behavior or admin `q` ObjectId search.
+- Frontend slices: `verify-ui-changes` (demo on 8085; admin list when AdminModelTable changes).
+
+---
+
+### Phase 1 — Tracer (query object, no chrome)
+
+- [x] **Task 1.1**: `buildDataTableListQuery` + regex escape
+  - Delivers: Pure helper from filter/search state → modelRouter-shaped object per the IP contract table; empty values omitted; user text escaped; choice always `$in` (including one value)
+  - Files: `ui/src/dataTableListQuery.ts`, `ui/src/dataTableListQuery.test.ts`, export from `ui/src/index.tsx` only if other UI modules need it (prefer importing the file, no new barrel)
+  - Blocked by: none
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: stub the query table in `docs/reference/ui.md` so the helper is named when it lands
+  - Acceptance: `bun test ui/src/dataTableListQuery.test.ts` — search `$or` regex; `.*` in input is literal; boolean omit/true; date `_gte`/`_lte`; number nested `$gte`; choice `$in`; no `page`/`sort` keys
+
+---
+
+### Phase 2 — DataTable chrome
+
+- [x] **Task 2.1**: Types + controlled props
+  - Delivers: `DataTableColumn.filter` and search/filter/`onQueryChange` props; omitted props preserve today’s UI
+  - Files: `ui/src/Common.ts`, `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`
+  - Blocked by: 1.1
+  - Skills: `terreno-ui`
+  - Docs: none beyond types (generated props in 4.1)
+  - Acceptance: tests — no filter prop → no filter controls; `onQueryChange` not required; existing sort cycle and pagination tests still pass
+
+- [x] **Task 2.2**: Web per-column `Filter` + search box
+  - Delivers: Toolbar search (debounced) and header `Filter` popovers; text / boolean / numberRange / dateRange / choice (`MultiselectField`); `renderFilter` slot; Apply/Clear call `onFilterValuesChange` and `onQueryChange`
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`, `demo/stories/DataTable.stories.tsx`
+  - Blocked by: 2.1
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: demo story is the tutorial surface; reference example in `docs/reference/ui.md`
+  - Acceptance: tests fire `onQueryChange` for each kind; demo story renders search + four kinds; `verify-ui-changes` on demo DataTable story
+
+- [x] **Task 2.3**: Native Filters sheet
+  - Delivers: On non-web, one Filters control + `Modal` sheet containing the same fields and search; same query object as web
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`
+  - Blocked by: 2.2
+  - Skills: `terreno-ui`
+  - Docs: one row in the platform table in `docs/reference/ui.md`
+  - Acceptance: test with `Platform.OS` mock (or testIDs) — sheet apply emits the same params as web Apply; no `Filter` portal on native
+
+---
+
+### Phase 3 — Admin
+
+- [x] **Task 3.1**: `parseAdminListFilters` choice `$in` and text `$regex`
+  - Delivers: Declared `choice` accepts `{ $in: string[] }` (subset of `choices`); `text` accepts `{ $regex, $options: "i" }`; scalar choice/text still work; top-level `$or` still errors; values outside `choices` error
+  - Files: `admin-backend/src/filterParser.ts`, `admin-backend/src/filterParser.test.ts`
+  - Blocked by: none (can parallel 2.x)
+  - Skills: `building-admin-interfaces`
+  - Docs: note in `docs/how-to/admin-add-model.md` that choice filters may be multi-value `$in`
+  - Acceptance: `bun test admin-backend/src/filterParser.test.ts` covers happy `$in`, invalid choice, text regex, rejected `$or`
+
+- [x] **Task 3.2**: AdminModelTable adopts DataTable filters
+  - Delivers: Map `filters` → column `filter` / `renderFilter` for `ref`; search → `q`; drop `AdminFilterDrawer` from the table; `buildAdminListQueryParams` forwards `$in` and omits `$or`
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, `admin-frontend/src/adminModelListQueryParams.ts`, `admin-frontend/src/adminModelListQueryParams.test.ts`, `admin-frontend/src/AdminModelTable.test.tsx`, `admin-frontend/src/AdminFilterDrawer.tsx` / `index.tsx` if unused
+  - Blocked by: 2.2, 3.1
+  - Skills: `building-admin-interfaces`, `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: `docs/reference/admin-frontend.md`, `docs/explanation/admin-interface.md`, `docs/how-to/admin-add-model.md` (filters on columns, not a drawer)
+  - Acceptance: tests — search param is `q` not `$or`; choice multi → `$in`; drawer not in table output; admin list verification in admin-spa or example admin
+
+---
+
+### Phase 4 — Docs and seed
+
+- [x] **Task 4.1**: Diátaxis + generated props + changelog
+  - Delivers: Query contract and platform table in `docs/reference/ui.md`; admin how-to/reference/explanation; regenerate UI component reference; CHANGELOG Added; seed IP/task links already in Grow stay accurate
+  - Files: `docs/reference/ui.md`, `docs/how-to/admin-add-model.md`, `docs/reference/admin-frontend.md`, `docs/explanation/admin-interface.md`, `docs/explanation/roadmap-seed-issues.md`, `CHANGELOG.md`; `ui` types + `bun run website:generate` as required by `update-docs`
+  - Blocked by: 2.3, 3.2
+  - Skills: `update-docs`
+  - Acceptance: a stranger can wire `onQueryChange` to a modelRouter list from docs; admin text contains + choice `$in` are explicit; `bun run website:build` if the site is in the slice

package/src/docs/versioned/next/tasks/deploy-to-vercel.md

@@ -16,18 +16,24 @@ See: [`docs/implementationPlans/deploy-to-vercel.md`](../implementationPlans/dep
 Close every **Open TODO** in the IP before writing the how-to guide.
 
 - [ ] **Task 0.1**: Spike `@terreno/api` on Vercel
-  - Description: Prototype whether Socket.io, MongoDB change streams, and `@terreno/ai` SSE can run on Vercel (all-in-one candidate). Record runtime limits, cold starts, session affinity, and SSE buffering. Compare against split topology (Vercel web + long-running backend).
+  - Description: Prototype whether Socket.io, MongoDB change streams, and `@terreno/ai` SSE can run on Vercel (all-in-one candidate). Treat [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the vendor contract. Record Fluid compute, max-duration disconnects, instance pinning (not affinity across reconnects), Redis for cross-instance fan-out, Function billing while sockets are open, cold starts, and SSE buffering. Compare against split topology (Vercel web + long-running backend).
   - Files: spike notes in PR / IP update; optional scratch `example-backend/vercel.json`
   - Depends on: none
   - Acceptance: IP questions **V1**, **V2**, and **V3** updated with a recorded decision; all IP Open TODO checkboxes checked or explicitly deferred with owner.
 
+- [ ] **Task 0.2**: Write Vercel Functions WebSocket operator docs
+  - Description: Create `docs/how-to/vercel-function-websockets.md` from the IP section **Vercel Functions WebSockets (Public Beta)**. Cite `https://vercel.com/docs/functions/websockets`; do not copy Vercel examples. Cover Fluid compute, HTTP Upgrade + Firewall/rate limits, websocket-only Socket.IO, `export default` HTTP server vs `TerrenoApp.start()`, instance pinning, max-duration reconnects, Redis (`RealtimeApp` adapter), Function billing while connected, and verification (`WEBSOCKETS_DEBUG`, DevTools WS, no polling fallback). Mark **beta**. Do not recommend all-in-one topology until V1 is decided. Link from `docs/how-to/README.md` and later from `docs/how-to/deploy-web-to-vercel.md` and `docs/how-to/websocket-integration.md`.
+  - Files: `docs/how-to/vercel-function-websockets.md` (new), `docs/how-to/README.md`, `docs/how-to/websocket-integration.md`
+  - Depends on: none (may ship before Task 0.1 closes; must re-verify against the Vercel page at ship time)
+  - Acceptance: every required operator section from the IP is present; the Vercel URL is cited; Next.js `experimental_upgradeWebSocket`, Bun, and Python examples are out of scope; `corsOrigin: true` is not recommended; listed in the how-to index.
+
 ## Phase 1: Core how-to guide
 
 - [ ] **Task 1.1**: Write the Vercel deployment guide for `single` output
-  - Description: Create `docs/how-to/deploy-web-to-vercel.md`. Open with a "What goes where" section using the **topology decided in Phase 0** (interim split layout until spike closes; do not document all-in-one until V1 is decided). Then: prerequisites; backend host setup per V1 outcome; `vercel.json` for `single` output; `EXPO_PUBLIC_API_URL`; deploy + verify. Link `docs/explanation/deployment-baseline.md` instead of restating baseline requirements.
+  - Description: Create `docs/how-to/deploy-web-to-vercel.md`. Open with a "What goes where" section using the **topology decided in Phase 0** (interim split layout until spike closes; do not document all-in-one until V1 is decided). Then: prerequisites; backend host setup per V1 outcome; `vercel.json` for `single` output; `EXPO_PUBLIC_API_URL`; deploy + verify. Link `docs/explanation/deployment-baseline.md` instead of restating baseline requirements. Link `docs/how-to/vercel-function-websockets.md` wherever sockets on Functions are mentioned.
   - Files: `docs/how-to/deploy-web-to-vercel.md` (new), `docs/how-to/README.md`
-  - Depends on: `deployment-foundation` Phase 4
-  - Acceptance: every config key verified against current Expo docs; the "what goes where" reasoning is present in the first section; the guide links rather than duplicates the baseline explainer; listed in the how-to index.
+  - Depends on: `deployment-foundation` Phase 4, Task 0.2
+  - Acceptance: every config key verified against current Expo docs; the "what goes where" reasoning is present in the first section; the guide links rather than duplicates the baseline explainer; listed in the how-to index; websocket Functions page is linked, not duplicated.
 
 - [ ] **Task 1.2**: `[RTK]` Add the verification section
   - Description: Add a "Verify the deployment" section with four checks, each with the expected result and what failure means: (1) the root URL loads the app; (2) a deep link loads directly on refresh (proves the SPA rewrite works); (3) login succeeds, proving the API call reaches the backend and CORS is configured; (4) the websocket connects, proving realtime and live feature flags work. For check 4, give a concrete way to verify — browser devtools Network tab filtered to WS, or the client's debug logging flag (find the actual flag name in the client package, `WEBSOCKETS_DEBUG` at time of writing) — and explain that the app looks fine when this is broken, which is why it must be checked explicitly.
@@ -84,7 +90,7 @@ Close every **Open TODO** in the IP before writing the how-to guide.
   - Acceptance: frontmatter complete; the production-deploy confirmation gate is present; the verification step includes the websocket check; no command appears in the skill that is absent from the how-to guide.
 
 - [ ] **Task 4.2**: Add the troubleshooting reference
-  - Description: Create `.rulesync/skills/deploy-vercel/references/troubleshooting.md` covering at least these six, each with the literal symptom the user sees: blank white page after deploy (missing rewrites); 404 on refreshing a deep link (same root cause, different symptom); network requests going to `localhost:4000` in production (`EXPO_PUBLIC_API_URL` absent at build time); CORS error text quoted verbatim from a browser console; websocket connection failing while the rest of the app works; and SSE responses arriving all at once on server output (the buffering caveat). For each, give the fix and the file or setting to change.
+  - Description: Create `.rulesync/skills/deploy-vercel/references/troubleshooting.md` covering at least these six, each with the literal symptom the user sees: blank white page after deploy (missing rewrites); 404 on refreshing a deep link (same root cause, different symptom); network requests going to `localhost:4000` in production (`EXPO_PUBLIC_API_URL` absent at build time); CORS error text quoted verbatim from a browser console; websocket connection failing while the rest of the app works (Fluid off, long-polling fallback, or max-duration close — link `docs/how-to/vercel-function-websockets.md`); and SSE responses arriving all at once on server output (the buffering caveat). For each, give the fix and the file or setting to change.
   - Files: `.rulesync/skills/deploy-vercel/references/troubleshooting.md` (new)
   - Depends on: Task 4.1
   - Acceptance: at least six entries; each quotes a real error string or describes a precisely observable symptom; each names the file or setting to change.

package/src/docs/versioned/next/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
+
+- [ ] **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
+- [ ] **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
+
+- [ ] **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
+
+- [ ] **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
+- [ ] **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/next/tasks/docs-reference-coverage.md

@@ -32,7 +32,7 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
   - 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.
 
-- [ ] **Task 1.4**: `[RTK]` Fix the reference index
+- [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
@@ -46,19 +46,19 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
   - 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.
 
-- [ ] **Task 2.2**: Add the missing READMEs
+- [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`.
 
-- [ ] **Task 2.3**: Normalize the four good READMEs
+- [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.
 
-- [ ] **Task 2.4**: Add `docs/tasks/README.md`
+- [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
@@ -66,13 +66,13 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
 
 ## Phase 3: Sanitization
 
-- [ ] **Task 3.1**: Sweep public docs for internal leakage
+- [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.
 
-- [ ] **Task 3.2**: Fix the how-to index and stale "Coming Soon" entries
+- [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
@@ -80,13 +80,13 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
 
 ## Phase 4: Drift protection
 
-- [ ] **Task 4.1**: Extend the docs-audit check
+- [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.
 
-- [ ] **Task 4.2**: Document the reference/rule duplication policy
+- [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

package/src/docs/versioned/next/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/next/tasks/examples-demo-coverage.md

@@ -2,7 +2,7 @@
 
 See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPlans/examples-demo-coverage.md)
 
-**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` touch the example apps' data layer and must wait for PR #869. Demo-app and coverage-infrastructure tasks are `@terreno/ui`-only or CI-only and are safe to implement now.
+**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
 
@@ -14,25 +14,107 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 1: Demo coverage — audit and P0
 
-- [ ] **Task 1.1**: Audit demo story coverage
+- [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.2**: Add P0 stories
+### 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.
 
-- [ ] **Task 1.3**: Add the demo coverage check
+- [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.
 
-- [ ] **Task 1.4**: Make the demo's `test:ci` real
+- [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
@@ -40,13 +122,13 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 2: Remaining demo stories
 
-- [ ] **Task 2.1**: Add P1 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.
 
-- [ ] **Task 2.2**: Add P2 stories and close the allowlist
+- [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
@@ -54,25 +136,47 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 3: Coverage enforcement
 
-- [ ] **Task 3.1**: Measure current coverage per package
+- [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.2**: Wire the threshold into every package CI
+### 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.
 
-- [ ] **Task 3.3**: Add the matrix CI job for uncovered packages
+- [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%.
 
-- [ ] **Task 3.4**: Catch up packages below threshold
+- [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
@@ -80,13 +184,13 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 4: Codecov
 
-- [ ] **Task 4.1**: Configure 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.
 
-- [ ] **Task 4.2**: Add the coverage badge
+- [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
@@ -94,19 +198,21 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 5: Example feature matrix
 
-- [ ] **Task 5.1**: `[RTK]` Audit example app feature coverage
+- [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: PR #869 merged
+  - 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.
 
-- [ ] **Task 5.2**: `[RTK]` Fill the highest-value example gaps
+- [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.
 
-- [ ] **Task 5.3**: Link the matrix into the contribution process
+Recorded gaps (2026-09-11): AI structured output → [#1010](https://github.com/FlourishHealth/terreno/issues/1010); generic background jobs → [#1188](https://github.com/FlourishHealth/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

package/src/docs/versioned/next/tasks/feature-flags-openfeature.md

@@ -1,5 +1,7 @@
 # Feature Flags → OpenFeature — Task List
 
+**Status:** Closed (2026-08-25) — IP complete; `@terreno/feature-flags` and `@terreno/rtk` ship on OpenFeature. The two open boxes are verification steps (SDK regen, full workspace run) that landed with the merge.
+
 See `docs/implementationPlans/feature-flags-openfeature.md` for full details.
 
 ## Phase 0: Catalog & deps