@terreno/mcp 0.29.0 → 0.31.0

package/dist/docs/versioned/0.29.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/flourishhealth/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
+
+- [ ] **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.
+
+- [ ] **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`.
+
+- [ ] **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.
+
+- [ ] **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
+
+- [ ] **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.
+
+- [ ] **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
+  - 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`
+  - 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
+
+- [ ] **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
+  - 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
+
+- [ ] **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
+  - 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/dist/docs/versioned/0.29.0/tasks/docs-tutorials-ai-first.md

@@ -0,0 +1,98 @@
+# Task List: AI-First Tutorials
+
+See: [`docs/implementationPlans/docs-tutorials-ai-first.md`](../implementationPlans/docs-tutorials-ai-first.md)
+
+**RTK deprecation flag:** **Blocked.** Every tutorial writes frontend data-layer code. Do not start until PR #869 merges and [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) Phase 2 is complete, so there is a correct `docs/reference/syncdb.md` to write against. Tutorial 2 additionally requires PR #802 (Boost) merged.
+
+## Instructions for the implementing agent
+
+- **Execute every command you write.** A tutorial is a promise that the steps work. If you cannot run a step, mark the tutorial incomplete rather than shipping an unverified step.
+- Write agent-first (IP question T2). Manual steps go in a collapsible "Without an agent" section, never as the only path.
+- State a time budget at the top of each tutorial and check it during validation. If a tutorial takes 3x its budget, cut scope.
+- Keep the tutorial app trivial: one or two models. Resist adding features — this is teaching, not showcasing. The showcase is [`build-terreno-app-validation`](build-terreno-app-validation.md).
+- End every tutorial with: "What you built", "What's next" (link the next tutorial), and "Reference" (link the relevant `docs/reference/` page).
+- Run `bun run website:build` before each commit.
+
+## Phase 1: Entry point
+
+- [ ] **Task 1.1**: Write `docs/tutorials/run-the-examples.md`
+  - Description: Rewrite `docs/tutorials/getting-started.md` as `run-the-examples.md` with a 10-minute budget. Must include, in order: prerequisites (Bun with a version, a MongoDB replica set — Atlas free tier per IP question T5, with local Mongo as an alternative per T5; no Docker); `bun run bootstrap` with a note that `bun install` alone is insufficient because packages must be compiled; the environment variables `MONGO_URI`, `BETTER_AUTH_SECRET`, and `BETTER_AUTH_URL` with example values (syncdb + Better Auth only per program P7 — do not document JWT secrets); a callout stating that MongoDB must be a replica set because change streams power realtime and live feature flags, including the exact symptom when it is not (find the actual error by running the backend against a standalone `mongod` and quote it); starting the backend (`bun run backend:dev`) and verifying with `curl localhost:4000/health` expecting `"healthy":true`; `bun run backend:seed` and the seeded credentials; starting the frontend (`bun run frontend:web`); a callout that the first login shows one-time Terms/Privacy/Consent modals including a signature draw before the main screen; and a short "what you just ran" section mapping each package to what you saw. Verify the seeded credentials against `example-backend/src/scripts/` rather than copying them from this task.
+  - Files: `docs/tutorials/run-the-examples.md` (new)
+  - Depends on: none
+  - Acceptance: every command was executed by you and its real output is reflected; the replica-set symptom is a quoted real error; the seeded credentials match the seed script; a clean-machine run reaches a logged-in web app.
+
+- [ ] **Task 1.2**: Retire `getting-started.md` with a redirect
+  - Description: Delete `docs/tutorials/getting-started.md` and add a Docusaurus client redirect from its URL to `run-the-examples.md`. Then grep the whole repo for inbound links (`rg -n "getting-started"`) and update every one: `docs/README.md`, `docs/how-to/create-a-model.md`, `docs/how-to/README.md`, `mcp-server/src/docs/**`, `AGENTS.md`, `README.md`, and any `website/` config.
+  - Files: `docs/tutorials/getting-started.md` (deleted), `website/docusaurus.config.ts`, plus every file with an inbound link
+  - Depends on: Task 1.1
+  - Acceptance: `rg -n "tutorials/getting-started"` returns nothing outside the redirect config; the old URL resolves in a built site; `bun run website:build` reports no new broken links.
+
+- [ ] **Task 1.3**: Write the tutorials index
+  - Description: Create `docs/tutorials/README.md` listing all six tutorials in recommended order with time budgets and a one-line description each. Per IP question T1, present two entry points at the top: "Just looking? Run the examples (10 min)" and "Building something? Start your first app (30 min)". Add a note explaining the Diátaxis split — tutorials teach end to end, how-to guides solve one problem — and link `docs/how-to/README.md`. Add the tutorials section to the docs site sidebar in the right order.
+  - Files: `docs/tutorials/README.md` (new), `website/docusaurus.config.ts` or `website/sidebars.ts`
+  - Depends on: Task 1.1
+  - Acceptance: all six tutorials listed with budgets; both entry points present; sidebar order matches the index order; `bun run website:build` passes.
+
+## Phase 2: First app
+
+- [ ] **Task 2.1**: Write `docs/tutorials/your-first-app.md`
+  - Description: 30-minute tutorial building a small app that is **not** todos (per IP question T3 — a bookmarks or notes app is fine; pick one and stay consistent). Steps: scaffold via `terreno_bootstrap_app` (with a manual `git clone`-and-adapt fallback for readers without MCP); define one Mongoose model with a `description` on every field (link `docs/how-to/create-a-model.md` and the field-description rule); register a `modelRouter` with owner-based permissions and `OwnerQueryFilter`; regenerate the typed client; build a list screen and a create form using `@terreno/ui` components; run it on web and on a device or simulator. Verify the bootstrap tool's actual output shape before writing the scaffold step — do not assume the generated file layout.
+  - Files: `docs/tutorials/your-first-app.md` (new)
+  - Depends on: Task 1.1, `docs-reference-coverage` Phase 1
+  - Acceptance: you built the app by following your own steps; it runs on web and on one native target; every field in the model has a `description`; the tutorial completes within 1.5x its stated budget.
+
+- [ ] **Task 2.2**: Add the universal-app payoff section
+  - Description: Add a closing section to `your-first-app.md` that makes the universal-app pillar concrete: the same screen code running on iOS, Android, and web, what `@terreno/ui` handled automatically (theming, platform-appropriate `Modal` rendering as an action sheet on mobile versus a centered dialog on web, responsive `Box` breakpoints), and what the reader would have had to write per platform without it. Include screenshots from your own run on at least two platforms, saved under `/opt/cursor/artifacts/` and committed to `website/static/img/tutorials/`.
+  - Files: `docs/tutorials/your-first-app.md`, `website/static/img/tutorials/*`
+  - Depends on: Task 2.1
+  - Acceptance: at least two real screenshots from different platforms are committed and rendered; every automatic behavior claimed is verified against `ui/src/` (for example confirm the `Modal` platform split in `ui/src/Modal.tsx`).
+
+## Phase 3: Build with AI
+
+- [ ] **Task 3.1**: Write `docs/tutorials/build-with-ai.md`
+  - Description: 30-minute tutorial, requires merged PR #802. Follow the six-beat arc from the IP: (1) configure both MCP servers in the reader's editor — hosted HTTP plus `terreno-mcp-local` via `bunx`, with the exact `.cursor/mcp.json` and the Claude Code equivalent; (2) ask an agent to add a feature and observe it call `terreno_search_docs` and the generators; (3) introduce a deliberate bug — pick one with a non-obvious symptom, such as a missing `preCreate` owner assignment causing a permission failure on read; (4) the agent calls `last_error` and `read_logs`, locates the error across backend and app sources, and fixes it; (5) inspect client state and navigate the running app with the runtime tools; (6) regenerate the typed client after the API change. Each beat must show the actual tool call and its real output. Verify tool names and parameters against `mcp-server/src/tools.ts` and `mcp-server/src/local/localTools.ts` in the merged tree — do not trust the IP's names.
+  - Files: `docs/tutorials/build-with-ai.md` (new)
+  - Depends on: Task 2.1, PR #802 merged, `ai-dev-loop-boost` Phase 1
+  - Acceptance: every tool name and parameter matches the merged source; the deliberate-bug exercise was actually performed and `last_error` output is quoted verbatim; MCP configuration is given for at least two editors.
+
+- [ ] **Task 3.2**: Add the "why this is different" framing
+  - Description: Add a short closing section contrasting this loop with pasting code into a chat window: the agent read the current docs rather than remembered them, saw the actual error rather than a description of it, inspected real client state, and produced code matching framework conventions because the conventions ship as guidelines. Keep it to three paragraphs and make every claim traceable to something the reader just did in the tutorial.
+  - Files: `docs/tutorials/build-with-ai.md`
+  - Depends on: Task 3.1
+  - Acceptance: three paragraphs or fewer; every claim maps to a numbered beat earlier in the tutorial; no unsupported superlatives.
+
+## Phase 4: AI features and admin
+
+- [ ] **Task 4.1**: Write `docs/tutorials/add-ai-features.md`
+  - Description: 25-minute tutorial adding `@terreno/ai` to the app from Tutorial 1. Steps: install and configure `AIService` with a provider (document which provider the tutorial uses and what key the reader needs); register `addGptRoutes` and `addGptHistoryRoutes`; build a streaming chat screen consuming the SSE endpoint; add one structured-output call using `generateJsonObject` with a schema (something small and useful for the tutorial app, such as auto-tagging a bookmark); then inspect the `AIRequest` collection to show that every call was logged with tokens and latency. Note the prompt-as-constant convention and link the `ai-prompt-governance` skill.
+  - Files: `docs/tutorials/add-ai-features.md` (new)
+  - Depends on: Task 2.1, `docs-reference-coverage` Task 1.1
+  - Acceptance: streaming chat works in your run; the structured-output call returns a typed object; `AIRequest` documents are shown with real token counts; prompts in the tutorial code are declared as constants.
+
+- [ ] **Task 4.2**: Write `docs/tutorials/add-an-admin-panel.md`
+  - Description: 20-minute tutorial. Steps: register `AdminApp` with the Tutorial 1 model, choosing `listFields` and `displayName`; add the admin screens (choose the embedded `@terreno/admin-frontend` route path or the standalone `@terreno/admin-spa` — pick one, state why, and link the other); create an admin user; verify admin-only access by logging in as the non-admin seeded user and confirming the redirect or 403. Include the `/admin/config` endpoint as the thing that makes the UI self-describing.
+  - Files: `docs/tutorials/add-an-admin-panel.md` (new)
+  - Depends on: Task 2.1, `docs-reference-coverage` Task 1.2
+  - Acceptance: the admin panel lists and edits the model in your run; non-admin access is verified as denied; the choice between embedded and standalone is explained with a link to the alternative.
+
+## Phase 5: Deploy
+
+- [ ] **Task 5.1**: Write `docs/tutorials/deploy-your-app.md`
+  - Description: 25-minute tutorial deploying the Tutorial 1 app to a public URL, targeting Vercel for web per IP question T4, with the backend deployed per [`deploy-to-vercel`](../implementationPlans/deploy-to-vercel.md)'s recommended path. Steps: production environment variables and which are secrets; Mongo Atlas connection string; building and deploying the backend; building and deploying web with `EXPO_PUBLIC_API_URL` set at build time; configuring CORS and Better Auth `trustedOrigins` for the new origin; then log in on the deployed app. End with a link to the GCP how-to for readers who want production-grade infrastructure and a note on what this tutorial deliberately skipped (custom domains, CDN tuning, monitoring).
+  - Files: `docs/tutorials/deploy-your-app.md` (new)
+  - Depends on: Task 2.1, `deploy-to-vercel` Phase 2
+  - Acceptance: the deploy was performed and produced a working public URL; login succeeded against the deployed backend; the CORS and `trustedOrigins` steps are present (omitting them is the most common failure); skipped concerns are listed explicitly.
+
+## Phase 6: Validation
+
+- [ ] **Task 6.1**: Fresh-environment validation run
+  - Description: On a clean environment (fresh clone, no cached Bun modules, no pre-existing MongoDB), run all six tutorials in order, timing each. Record every step that failed, was ambiguous, or required knowledge not in the tutorial. Fix each. Capture one screenshot per tutorial at its completion state and save to `/opt/cursor/artifacts/`.
+  - Files: all six tutorial files
+  - Depends on: Task 5.1
+  - Acceptance: all six complete on a clean environment; each within 1.5x its stated budget or the budget is corrected; every gap found is fixed; six completion screenshots captured.
+
+- [ ] **Task 6.2**: Point agent surfaces at the tutorials
+  - Description: Update `mcp-server/src/docs/resources/overview.md` and the relevant `.rulesync/rules/` entry so that an agent asked "how do I start with Terreno?" points at `docs/tutorials/README.md` and, for AI-assisted work, `build-with-ai.md`. Regenerate rule mirrors with `bun run rules`.
+  - Files: `mcp-server/src/docs/resources/overview.md`, `.rulesync/rules/00-root.md`, generated mirrors
+  - Depends on: Task 6.1
+  - Acceptance: `bun run mcp:build` succeeds; `bun run rules:check` exits 0; the overview resource links the tutorials index.

package/dist/docs/versioned/0.29.0/tasks/examples-demo-coverage.md

@@ -0,0 +1,113 @@
+# Task List: Examples, Demo, and Test Coverage
+
+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.
+
+## 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
+
+- [ ] **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
+  - 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
+  - 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
+  - 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
+
+- [ ] **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
+  - 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
+
+- [ ] **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
+  - 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
+  - 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
+  - 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
+
+- [ ] **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
+  - 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
+
+- [ ] **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
+  - 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
+  - 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
+  - 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.

package/dist/docs/versioned/0.29.0/tasks/oss-governance-baseline.md

@@ -0,0 +1,129 @@
+# Task List: OSS Governance Baseline
+
+See: [`docs/implementationPlans/oss-governance-baseline.md`](../implementationPlans/oss-governance-baseline.md)
+
+**RTK deprecation flag:** None. No task here touches `@terreno/rtk`, syncdb, or auth. Safe to implement before PR #869.
+
+## Instructions for the implementing agent
+
+- Do **not** change any source code under `*/src/`. This IP is documentation, metadata, and CI configuration only.
+- Do **not** rewrite existing `README.md` prose. Only append the new governance section and badge.
+- Answer keys used below follow the IP decisions recorded 2026-07-29 (**MIT**, DCO, Contributor Covenant 2.1, `security@terreno.app`, `conduct@terreno.app`, Conventional Commits CI-enforced). If the IP decision table changes, follow the IP.
+- Run `bun run lint` before each commit. Run `bun run rules:check` if you touch anything under `.rulesync/`.
+- One commit per task unless a task explicitly says otherwise.
+
+## Phase 1: Legal baseline
+
+- [ ] **Task 1.1**: Add root `LICENSE` and `NOTICE`
+  - Description: Copy the MIT License text to a new root `LICENSE` (use the standard MIT template; `mcp-server` already ships MIT). Create `NOTICE` containing the project name, the copyright line `Copyright 2026 Flourish Health, Inc.`, and a one-line statement that the project is licensed under MIT. Include acknowledgement of vendored `api/src/vendor/wesleytodd-openapi/` with a pointer to its own `LICENSE`.
+  - Files: `LICENSE` (new), `NOTICE` (new)
+  - Depends on: none
+  - Acceptance: `LICENSE` exists at repo root with standard MIT text; `NOTICE` mentions the vendored openapi code. Do not compare against `api/LICENSE` or `ui/LICENSE` — those remain Apache-2.0 until Task 1.4.
+
+- [ ] **Task 1.2**: Audit license coverage across published packages
+  - Description: Read `.github/workflows/publish-on-tag.yml` and list every package it publishes. For each one, record in a scratch table: whether a `LICENSE` file exists, whether `package.json` has a `files` array, whether `LICENSE` is included in that array, and the `license` field value. Write the findings as a markdown table in the PR description. Do not fix anything in this task.
+  - Files: none (findings go in the PR body)
+  - Depends on: none
+  - Acceptance: PR body contains a table with one row per published package and the four columns above; the table is derived from the actual repo, not copied from the IP.
+
+- [ ] **Task 1.3**: Add `LICENSE` to every published package
+  - Description: For each package identified in Task 1.2 that lacks a `LICENSE`, create one by copying the root `LICENSE`. Packages to cover: `rtk`, `ai`, `admin-backend`, `admin-frontend`, `admin-spa`, `api-health`, `feature-flags`, `mcp-server`, `test`. Do not create `LICENSE` files in non-published directories (`demo`, `example-frontend`, `example-backend`, `website`, `terraform`).
+  - Files: `rtk/LICENSE`, `ai/LICENSE`, `admin-backend/LICENSE`, `admin-frontend/LICENSE`, `admin-spa/LICENSE`, `api-health/LICENSE`, `feature-flags/LICENSE`, `mcp-server/LICENSE`, `test/LICENSE` (all new)
+  - Depends on: Task 1.1, Task 1.2
+  - Acceptance: every published package directory contains a `LICENSE` identical to the root `LICENSE`.
+
+- [ ] **Task 1.4**: Align `license` fields and `files` arrays
+  - Description: Set `"license": "MIT"` in the root `package.json` and in every published package's `package.json` (relicense `api`/`ui` from Apache-2.0). For every package that has an explicit `files` array, add `"LICENSE"` to it (`ui`, `rtk`, `admin-frontend`, `admin-spa`, `mcp-server` at minimum — confirm against Task 1.2 findings). Do not otherwise reorder or reformat `package.json`.
+  - Files: `package.json`, `ui/package.json`, `rtk/package.json`, `admin-frontend/package.json`, `admin-spa/package.json`, `mcp-server/package.json`, plus any others found in Task 1.2
+  - Depends on: Task 1.3
+  - Acceptance: `bun pm pack --dry-run` run inside each published package lists `LICENSE` among the packed files; no `package.json` declares a license other than `MIT`.
+
+- [ ] **Task 1.5**: Verify relicensing consent for `api` and `ui`
+  - Description: Run `git log --format='%an <%ae>' -- api/ ui/ | sort -u` and list every distinct author. Report the list in the PR body, flagging any address that is not a `@flourish.health` address or a known bot. Do **not** proceed to merge the Apache-2.0 → MIT change for `api`/`ui` if a non-Flourish human contributor appears; instead leave a `TODO` note in the PR body requesting sign-off. (`mcp-server` is already MIT.)
+  - Files: none (findings go in the PR body)
+  - Depends on: Task 1.4
+  - Acceptance: PR body lists all `api`/`ui` authors and explicitly states either "all Flourish/bot — safe to relicense" or names the contributors needing sign-off.
+
+- [ ] **Task 1.6**: Add a license-coverage CI check
+  - Description: Create `scripts/check-license-coverage.ts` (Bun, TypeScript, `const` arrow functions, explicit return types). It should: read the list of published packages from `.github/workflows/publish-on-tag.yml` (parse job names or a hardcoded list with a comment pointing at the workflow), then for each assert (a) `LICENSE` exists, (b) `package.json` `license` equals the root `package.json` `license`, (c) if a `files` array exists it contains `LICENSE`. Print one line per failure and `process.exit(1)` when any check fails. Add a `check:licenses` script to the root `package.json` and a job to `.github/workflows/repo-policies.yml` that runs it.
+  - Files: `scripts/check-license-coverage.ts` (new), `package.json`, `.github/workflows/repo-policies.yml`
+  - Depends on: Task 1.4
+  - Acceptance: `bun run check:licenses` exits 0 on a clean tree; temporarily deleting `rtk/LICENSE` makes it exit 1 with a message naming `rtk`; the new CI job appears in `repo-policies.yml`.
+
+## Phase 2: Contribution process
+
+- [ ] **Task 2.1**: Write `CONTRIBUTING.md`
+  - Description: Create `CONTRIBUTING.md` covering, in this order: (1) Code of Conduct link; (2) ways to contribute (issue, discussion, docs fix, code); (3) development setup — `bun run bootstrap`, Bun version requirement, MongoDB replica-set requirement for `example-backend` (single-node replset is enough, change streams need it), the seeded users `test@example.com` / `superuser@example.com` with password `testpassword123`; (4) per-package commands table pulled from the root `package.json` scripts (`bun run api:test`, `bun run ui:test`, `bun run lint`, `bun run compile`); (5) code style pointers — link `AGENTS.md`, call out the no-barrel-imports rule and `bun run check:no-barrel-imports`, the Luxon requirement, and the logging conventions; (6) test expectations — new features ship with tests, coverage must not drop; (7) the IP process — link `docs/implementationPlans/README.md` and `IP_TEMPLATE.md`, explain when an IP is required (new package, new public API, cross-package change) versus not (bug fix, docs); (8) DCO sign-off instructions (`git commit -s`); (9) PR expectations — draft by default, CI green, screenshots for UI changes.
+  - Files: `CONTRIBUTING.md` (new)
+  - Depends on: none
+  - Acceptance: every command shown in `CONTRIBUTING.md` exists in a `package.json` `scripts` block; the seeded credentials match `example-backend/src/scripts/`; no reference to `.claude/` or other agent-private paths.
+
+- [ ] **Task 2.2**: Add `CODE_OF_CONDUCT.md`
+  - Description: Add Contributor Covenant 2.1 verbatim, with the enforcement contact set to `conduct@terreno.app`. Do not modify the covenant text other than the contact line and the project name.
+  - Files: `CODE_OF_CONDUCT.md` (new)
+  - Depends on: none
+  - Acceptance: file states "Contributor Covenant" and version 2.1; contact address is present and is not a placeholder.
+
+- [ ] **Task 2.3**: Add `SECURITY.md`
+  - Description: Create `SECURITY.md` with: a supported-versions table (current minor supported; previous minor receives security fixes only), reporting instructions naming GitHub private vulnerability reporting as the primary channel and `security@terreno.app` as fallback, a 5-business-day acknowledgement commitment, a statement that reporters should not open public issues for vulnerabilities, and a note that CodeQL runs on the repo (`.github/workflows/codeql-analysis.yml`).
+  - Files: `SECURITY.md` (new)
+  - Depends on: none
+  - Acceptance: file exists at repo root so GitHub surfaces it under Security → Policy; both reporting channels are named.
+
+- [ ] **Task 2.4**: Add a DCO check for external PRs
+  - Description: Add a workflow job (either in `repo-policies.yml` or a new `.github/workflows/dco.yml`) that, for pull requests whose head repository differs from the base repository, verifies every commit message contains a `Signed-off-by:` line matching the commit author. Skip the check for PRs from the same repo and for bot authors (`dependabot[bot]`, `cursor[bot]`). Follow the repo's existing convention of validating required inputs before use.
+  - Files: `.github/workflows/dco.yml` (new) or `.github/workflows/repo-policies.yml`
+  - Depends on: Task 2.1
+  - Acceptance: the job's condition explicitly excludes same-repo PRs and the named bots; the workflow parses as valid YAML (`bunx yaml-lint` or equivalent).
+
+## Phase 3: Changelog
+
+- [ ] **Task 3.1**: Create the root `CHANGELOG.md` and backfill releases
+  - Description: Create `CHANGELOG.md` in Keep-a-Changelog format with an `## [Unreleased]` section at the top, then one section per released version, newest first. Source the content from `gh release list --limit 40` and `gh release view <tag>` for each release from 0.20.0 to the current version. Group each entry under `Added` / `Changed` / `Fixed` / `Deprecated` / `Removed`. Include a header note that all `@terreno/*` packages are versioned in lockstep and a link to `docs/implementationPlans/oss-launch-program.md` is **not** needed here. Do not invent entries — if a release has no notes, write `- No published release notes.` under that version.
+  - Files: `CHANGELOG.md` (new)
+  - Depends on: none
+  - Acceptance: every version tag returned by `gh release list` between 0.20.0 and current has a section; no section is empty; the file states the lockstep versioning rule.
+
+- [ ] **Task 3.2**: Reduce `api/CHANGELOG.md` to a pointer
+  - Description: Replace the contents of `api/CHANGELOG.md` with a short note that the changelog moved to the repo root, linking `../CHANGELOG.md`. Preserve the historical entries by moving them into the corresponding root `CHANGELOG.md` sections first if they contain detail the GitHub releases lack.
+  - Files: `api/CHANGELOG.md`, `CHANGELOG.md`
+  - Depends on: Task 3.1
+  - Acceptance: `api/CHANGELOG.md` is under 10 lines and links to the root changelog; no historical detail was lost.
+
+- [ ] **Task 3.3**: Make changelog updates part of the release process
+  - Description: Edit `.rulesync/skills/release/SKILL.md` to add a required step: before tagging, move `## [Unreleased]` content into a new version section in the root `CHANGELOG.md` with today's date (via Luxon-formatted ISO date), and confirm the section is non-empty. Then run `bun run rules` to regenerate the mirrored skill files under `.cursor/`, `.claude/`, `.devin/`, `.github/`, and `.agents/`.
+  - Files: `.rulesync/skills/release/SKILL.md`, plus generated mirrors
+  - Depends on: Task 3.1
+  - Acceptance: `bun run rules:check` exits 0 (no uncommitted diff after regeneration); the release skill mentions `CHANGELOG.md` as a required pre-tag step.
+
+## Phase 4: GitHub templates
+
+- [ ] **Task 4.1**: Add issue forms
+  - Description: Create three GitHub issue forms. `bug_report.yml`: fields for affected package (dropdown listing all published `@terreno/*` packages plus `docs`, `examples`, `mcp`), version, platform (dropdown: iOS / Android / Web / Backend / N/A), reproduction steps (required textarea), expected vs actual, and a checkbox confirming the reporter searched existing issues. `feature_request.yml`: problem statement (required), proposed solution, alternatives considered, and a checkbox asking whether the requester is willing to open a PR. `docs_issue.yml`: page URL, what is wrong or missing, and suggested fix. Add `config.yml` with `blank_issues_enabled: false` and contact links to Discussions (Q&A and Ideas categories) and `SECURITY.md`.
+  - Files: `.github/ISSUE_TEMPLATE/bug_report.yml`, `.github/ISSUE_TEMPLATE/feature_request.yml`, `.github/ISSUE_TEMPLATE/docs_issue.yml`, `.github/ISSUE_TEMPLATE/config.yml` (all new)
+  - Depends on: Task 2.3
+  - Acceptance: all four files parse as valid YAML; the package dropdown in `bug_report.yml` matches the packages published by `publish-on-tag.yml`; `config.yml` disables blank issues.
+
+- [ ] **Task 4.2**: Add a PR template
+  - Description: Create `.github/PULL_REQUEST_TEMPLATE.md` with sections: Summary; Related IP or issue; Type of change (checkboxes); Testing performed (with a reminder that frontend changes require screenshots or video per `AGENTS.md`); Checklist (tests added, `bun run lint` passes, `bun run compile` passes, docs updated, changelog `Unreleased` entry added for user-facing changes, DCO signed off). Keep it short enough that contributors actually fill it in — under 40 lines.
+  - Files: `.github/PULL_REQUEST_TEMPLATE.md` (new)
+  - Depends on: Task 2.1, Task 3.1
+  - Acceptance: template is under 40 lines; references the changelog and the frontend-verification requirement.
+
+- [ ] **Task 4.3**: Add `CODEOWNERS`
+  - Description: Create `.github/CODEOWNERS` mapping each package directory to its owning team or maintainer, plus a catch-all root owner. Use GitHub team handles if they exist; otherwise use individual maintainer usernames. Include entries for `docs/`, `.github/`, `.rulesync/`, and `terraform/`.
+  - Files: `.github/CODEOWNERS` (new)
+  - Depends on: none
+  - Acceptance: every top-level package directory has an owner; the file has a catch-all `*` line; GitHub's CODEOWNERS validation (visible in repo settings) reports no errors.
+
+- [ ] **Task 4.4**: Document required repository settings
+  - Description: Add a short section to `CONTRIBUTING.md` (or a new `docs/explanation/repository-settings.md` if it exceeds 30 lines) listing the GitHub settings a maintainer must enable manually because they cannot be committed: Discussions enabled with the categories from [`public-roadmap-github.md`](../implementationPlans/public-roadmap-github.md), private vulnerability reporting enabled, branch protection on `master` requiring the CI checks, "Allow squash merging" only, and auto-delete of merged branches.
+  - Files: `CONTRIBUTING.md` or `docs/explanation/repository-settings.md`
+  - Depends on: Task 2.1
+  - Acceptance: the list names each setting and where to find it in the GitHub UI; no setting is described as already enabled unless verified.
+
+- [ ] **Task 4.5**: Append the governance section to `README.md`
+  - Description: Add a `## License` section and a `## Contributing` section near the end of `README.md`, plus a license badge next to the existing npm badges. Link `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md`. Do not modify any other README content — positioning changes belong to a different IP.
+  - Files: `README.md`
+  - Depends on: Task 1.1, Task 2.1, Task 2.2, Task 2.3
+  - Acceptance: `git diff README.md` shows only additions (badge line plus two new sections); all four links resolve to files that exist.

package/dist/docs/versioned/0.29.0/tasks/positioning-django-rails-universal.md

@@ -0,0 +1,100 @@
+# Task List: Positioning — "Django/Rails for TypeScript, with Universal Apps"
+
+See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../implementationPlans/positioning-django-rails-universal.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` touch the architecture diagram, package list, or integration flow and must run after PR #869 merges and after [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) Phase 6. Unmarked tasks are safe earlier.
+
+## Instructions for the implementing agent
+
+- Write the copy blocks **once** in `docs/explanation/positioning.md` (Task 1.1), then copy them verbatim everywhere else. Do not paraphrase per surface — drift is the problem this IP exists to fix.
+- Do not claim any feature listed under "Where Terreno is headed" as shipped. If you are unsure whether something ships today, grep for it in the package source before writing about it.
+- When moving content out of the README, use `git mv`-style discipline: cut from one file, paste into the other in the same commit, and grep for inbound links.
+- Run `bun run website:build` and `bun run rules:check` before each commit that touches `website/` or `.rulesync/`.
+
+## Phase 1: Canonical copy
+
+- [ ] **Task 1.1**: Write `docs/explanation/positioning.md`
+  - Description: New explainer containing five clearly-labeled copy blocks in fenced code blocks (so they can be copied verbatim without markdown rendering surprises): `tagline` (one line), `elevator` (2–3 sentences), `pillars` (three bullets, in the order batteries-included / universal-by-default / AI-native), `aiPillar` (2–3 sentences naming both AI layers per IP question PO7 — the MCP tool layer and the `/terreno-*` SDLC pipeline process layer), and `pitch` (~150 words). Then a "Why the Django/Rails analogy" section, then the honest comparison table from the IP. Then a "Language rules" section restating the four rules from the program doc (lead with the analogy, say "universal app", never claim unshipped features, keep superlatives off reference pages) plus a fifth: never describe one AI layer without the other.
+  - Files: `docs/explanation/positioning.md` (new)
+  - Depends on: none
+  - Acceptance: five fenced copy blocks present and labeled; the `aiPillar` block names both the MCP tools and the `/terreno-*` pipeline; comparison table has at least eight rows including at least three honest gaps with IP links; language rules section has all five rules.
+
+- [ ] **Task 1.2**: Verify every claim in the comparison table
+  - Description: For each row of the comparison table, confirm the Terreno side exists by finding it in source: `modelRouter` in `api/src/api.ts`, admin packages, `Permissions` in `api/src/permissions.ts`, Better Auth in `api/src/betterAuth*.ts`, MCP tools in `mcp-server/src/tools.ts`, and the SDLC pipeline in `plugins/terreno-planning/skills/`. For each "not shipped" row (background jobs, SSR, RBAC), confirm it is genuinely absent and link the IP or roadmap item tracking it. Correct any row that turns out to be wrong.
+  - Files: `docs/explanation/positioning.md`
+  - Depends on: Task 1.1
+  - Acceptance: every "shipped" row cites a source path; the generator row cites both `mcp-server/src/tools.ts` and `plugins/terreno-planning/`; every "not shipped" row links an IP file that exists in `docs/implementationPlans/`.
+
+- [ ] **Task 1.3**: Gate the pipeline claim on its portability work
+  - Description: The `/terreno-*` pipeline currently only runs inside this monorepo (see [`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md), "It only works here"). Do not publish positioning copy that implies consumers can use it until that IP's Phase 2 is complete. Check the state of `agentic-sdlc-plugin` Task 2.5 before writing the `aiPillar` block; if portability is not done, write the block describing the tool layer only and add a `TODO` in the IP to revisit, rather than making a claim that fails on first use.
+  - Files: `docs/explanation/positioning.md`
+  - Depends on: Task 1.1
+  - Acceptance: the `aiPillar` block claims the pipeline only if `agentic-sdlc-plugin` Task 2.5 has passed; otherwise the omission is recorded with a pointer to the blocking task.
+
+## Phase 2: README restructure
+
+- [ ] **Task 2.1**: Restructure the README's opening
+  - Description: Rewrite `README.md` above the packages list to this order: title with badges (preserve existing npm badges and the license badge from the governance IP), the `tagline` block as the subtitle, the `elevator` block, the three `pillars`, then a "Quickstart" section, then "Packages". Preserve the existing Vision and Philosophy content but fold it into the pillars rather than repeating it. Per IP question PO5, replace the "Where Terreno is headed" list with a two-line summary linking `ROADMAP.md`.
+  - Files: `README.md`
+  - Depends on: Task 1.1
+  - Acceptance: "Django/Rails for TypeScript" appears within the first two sentences; the pillars appear in the IP's order; the roadmap section is two lines plus a link; no feature claimed that is not shipped.
+
+- [ ] **Task 2.2**: Move maintainer content out of the README
+  - Description: Move these README sections to their correct homes: local development / bootstrap / linking instructions → `CONTRIBUTING.md`; the "Feature flags: OpenFeature migration" walkthrough → a new or existing page under `docs/how-to/` (check `docs/how-to/add-feature-flags.md` first — it may already cover this, in which case delete the README copy and link it); GCP project names, Cloud Run URLs, and Netlify hosts → `infra/flourish/README.md` (created by [`deploy-to-gcp`](../implementationPlans/deploy-to-gcp.md)) or a short "Live examples" list with URLs only and no infra detail; release instructions → `CONTRIBUTING.md`. After moving, grep the repo and `website/` for links to the removed anchors and fix them.
+  - Files: `README.md`, `CONTRIBUTING.md`, `docs/how-to/add-feature-flags.md`, `infra/flourish/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: `rg -i "flourish-terreno|a\.run\.app|Slack" README.md` returns nothing; no content was deleted without a new home; `bun run website:build` reports no new broken links.
+
+- [ ] **Task 2.3**: `[RTK]` Update the README architecture and package list
+  - Description: Confirm the architecture diagram and published-package list reflect syncdb (this may already be done by `rtk-to-syncdb-migration-docs` Task 6.5 — check first and skip if so). Ensure every package in `publish-on-tag.yml` appears in the list exactly once with a one-line description matching its `package.json` description.
+  - Files: `README.md`
+  - Depends on: Task 2.2, `rtk-to-syncdb-migration-docs` Task 6.5
+  - Acceptance: package list matches `publish-on-tag.yml` one-to-one; each description matches the package's `package.json`; diagram names syncdb not rtk.
+
+## Phase 3: Docs site
+
+- [ ] **Task 3.1**: `[RTK]` Rewrite `docs/README.md`
+  - Description: Replace the opening line ("shared packages for full-stack applications with React Native and Express/Mongoose") with the `tagline` + `elevator` + `pillars` blocks. Keep the Diátaxis structure section. Rebuild the package table so it contains every published package including `@terreno/ai`, `@terreno/syncdb`, `@terreno/admin-spa`, and `@terreno/feature-flags`, with `rtk` under a Legacy heading. Update the Quick links section: remove the `.cursorrules` link if that file no longer exists, add `positioning.md`, `ROADMAP.md`, and `CONTRIBUTING.md`.
+  - Files: `docs/README.md`
+  - Depends on: Task 1.1, `rtk-to-syncdb-migration-docs` Task 2.3
+  - Acceptance: tagline appears in the first two sentences; package table complete and matching `publish-on-tag.yml`; every Quick link resolves to an existing file.
+
+- [ ] **Task 3.2**: Update the docs site configuration
+  - Description: In `website/docusaurus.config.ts`, set `tagline` to the canonical tagline and confirm `title`, `themeConfig.metadata` (og description), and navbar title read consistently. Check whether `website/src/pages/index.tsx` exists; if it does, update the hero to use the tagline, the three pillars, and one short code sample (a `modelRouter` registration plus the matching generated hook usage). If there is no custom landing page, note that in the PR body and skip the hero work.
+  - Files: `website/docusaurus.config.ts`, `website/src/pages/index.tsx` (if present)
+  - Depends on: Task 1.1
+  - Acceptance: `bun run website:build` succeeds; the built HTML contains the canonical tagline in the meta description; the hero (if present) shows the three pillars.
+
+## Phase 4: Agent surfaces
+
+- [ ] **Task 4.1**: `[RTK]` Update root agent context files
+  - Description: In `.rulesync/rules/00-root.md` (the source for `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/00-root.mdc`, and the copilot instructions), replace the opening "A monorepo containing shared packages…" with the `tagline` + `elevator` + `pillars`. Keep all existing conventions content unchanged. Apply the same opening to `CLAUDE-consumer.md`. Then run `bun run rules` and commit every generated mirror. Note: `CLAUDE.local.md` appears to be a stale duplicate of `CLAUDE.md` — verify and either update or delete it, reporting which you chose and why.
+  - Files: `.rulesync/rules/00-root.md`, `CLAUDE-consumer.md`, possibly `CLAUDE.local.md`, generated mirrors
+  - Depends on: Task 1.1
+  - Acceptance: `bun run rules:check` exits 0; `AGENTS.md` and `CLAUDE.md` both open with the positioning; no conventions content was lost (diff review); the `CLAUDE.local.md` decision is explained in the PR body.
+
+- [ ] **Task 4.2**: Update the MCP overview resource
+  - Description: Update `mcp-server/src/docs/resources/overview.md` to open with the positioning blocks so agents reading `terreno://docs/overview` describe Terreno consistently. Check the other resource bundles (`api`, `ui`, `rtk`/`syncdb`, `patterns`) for stale positioning language in their intros and fix those too.
+  - Files: `mcp-server/src/docs/resources/*.md`
+  - Depends on: Task 4.1
+  - Acceptance: `bun run mcp:build` succeeds; the overview resource opens with the tagline; no resource intro describes Terreno as "a monorepo of shared packages".
+
+## Phase 5: Metadata
+
+- [ ] **Task 5.1**: Standardize `package.json` descriptions
+  - Description: For every package published by `publish-on-tag.yml`, set `description` to the pattern `<what it does> — part of Terreno, the batteries-included TypeScript framework for universal apps.` Keep the first clause specific and accurate per package (do not make them all identical). Also confirm `keywords`, `repository`, `homepage`, and `bugs` fields are present and correct on every published package — missing `repository` fields hurt npm discoverability.
+  - Files: every published `package.json`
+  - Depends on: Task 1.1
+  - Acceptance: every published package has a `description` matching the pattern, plus `repository`, `homepage`, and `bugs` fields; `bun install` still resolves cleanly.
+
+- [ ] **Task 5.2**: Document the GitHub repository metadata
+  - Description: The repo description and topics cannot be set from a commit. Add a "Repository metadata" subsection to `docs/explanation/positioning.md` giving the exact description string (the short tagline variant from PO1 option C) and the exact topic list to set: `typescript`, `react-native`, `expo`, `express`, `mongoose`, `framework`, `mcp`, `ai`, `universal-apps`, `full-stack`. Mark it as a maintainer action.
+  - Files: `docs/explanation/positioning.md`
+  - Depends on: Task 1.1
+  - Acceptance: the exact description string and full topic list are present and marked as a manual maintainer step.
+
+- [ ] **Task 5.3**: Consistency sweep
+  - Description: Grep the repo for stale positioning language and fix every hit: `rg -n "monorepo containing shared packages"`, `rg -ni "cross-platform"` (should be "universal app" in prose; library-internal technical uses are fine — judge case by case), and `rg -n "88\+ components|90\+ components"` (component counts drift; either verify the number against `ui/src/index.tsx` exports or replace with "a large component library"). Report the count of fixes in the PR body.
+  - Files: various
+  - Depends on: Task 4.1, Task 3.1
+  - Acceptance: no prose surface says "monorepo containing shared packages"; component counts are either verified against the export list or removed; `bun run rules:check` exits 0.