@terreno/mcp 57.1.0 → 57.3.0

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

@@ -0,0 +1,110 @@
+# Task List: Deploy to Vercel + `deploy-vercel` Skill
+
+See: [`docs/implementationPlans/deploy-to-vercel.md`](../implementationPlans/deploy-to-vercel.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` cover client configuration, auth origins, and websocket verification, all of which change shape with PR #869 (syncdb uses a websocket delta transport, so the websocket verification step becomes more load-bearing, not less). Re-verify marked tasks after #869.
+
+## Instructions for the implementing agent
+
+- Verify every Vercel configuration key against the current Expo documentation at `https://docs.expo.dev/guides/publishing-websites` and `https://docs.expo.dev/router/web/api-routes` before writing it. Vercel's config schema has changed across versions (`routes`/`builds` versus `rewrites`/`functions`) — document the current one and note the legacy form only if the repo's Expo version requires it.
+- Confirm the repo's Expo SDK version from the root `package.json` catalog before writing anything about server output or SSR. If it is below 55, the server-output section must be clearly marked as unavailable-until-upgrade and link PR #779.
+- Never write `corsOrigin: true` as a recommendation.
+- Run `bun run lint` before each commit; `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 0: Vercel topology spike (blocks Phase 1)
+
+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).
+  - 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.
+
+## 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.
+  - 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.
+
+- [ ] **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.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.1
+  - Acceptance: all four checks present with expected results; the websocket check names a real debug flag verified in the client source; the "looks fine while broken" warning is present.
+
+- [ ] **Task 1.3**: Add the reference `vercel.json`
+  - Description: Per IP question V3 (after Phase 0), add `vercel.json` to `example-frontend` and optionally `example-backend` if all-in-one wins. Wire to a real deployment only if V3 decision is **A**.
+  - Files: `example-frontend/vercel.json` (new), `example-frontend/README.md`
+  - Depends on: Task 1.1
+  - Acceptance: the file is valid JSON and matches the guide's configuration exactly; the README explains its status; no new deploy workflow was added.
+
+## Phase 2: Preview deployments and origins
+
+- [ ] **Task 2.1**: `[RTK]` Document the preview-origin problem
+  - Description: Add a "Preview deployments" section covering: how Vercel assigns a unique origin per deployment; why that breaks CORS and Better Auth; a concrete `corsOrigin` pattern accepting production plus preview origins (write it as a function or regex matching the project's preview hostname shape — read `api/src/expressServer.ts` to confirm what shapes `corsOrigin` actually accepts before writing the example); the equivalent `trustedOrigins` configuration for Better Auth including native deep-link schemes; and OAuth redirect-URI registration per provider, noting that most providers do not support wildcards so preview OAuth needs either a fixed proxy origin or provider-specific handling. State that `corsOrigin: true` must not be used in production and explain the risk.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.2
+  - Acceptance: the `corsOrigin` example is a shape actually supported by `setupServer`, cited to source; `trustedOrigins` guidance matches `api/src/betterAuth.ts`; the OAuth wildcard limitation is stated; the `corsOrigin: true` warning explains the risk rather than just prohibiting it.
+
+- [ ] **Task 2.2**: `[RTK]` Document per-environment client configuration
+  - Description: Add a short section on Vercel's three environment scopes (production, preview, development) and how `EXPO_PUBLIC_API_URL` should differ across them — typically a production backend and a staging backend. Explain the consequence that follows from build-time inlining: each environment produces a different bundle, so a promoted preview build points at the preview backend unless rebuilt. Cross-reference the multi-environment checklist in `docs/explanation/deployment-baseline.md`. Add a note to `docs/reference/environment-variables.md` about Vercel's per-environment scoping.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 2.1
+  - Acceptance: the promotion pitfall is stated explicitly; the reference page notes Vercel scoping; both link the baseline checklist.
+
+## Phase 3: Advanced — server output
+
+- [ ] **Task 3.1**: Determine and record server-output availability
+  - Description: Read the `expo` version in the root `package.json` catalog and the state of PR #779 (Expo SDK 56 upgrade). Record in the guide whether `server` output is available today. If the SDK is below 55, the section must open with a clear "not available on the current Terreno Expo version" note plus a link to PR #779 and [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md).
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.1
+  - Acceptance: the stated Expo version matches the catalog exactly; availability is stated unambiguously; PR #779 is linked if applicable.
+
+- [ ] **Task 3.2**: Write the server-output section
+  - Description: Document the server-output path as advanced: setting `web.output` to `server` in the app config, the server entry file using `expo-server/adapter/vercel`, the `vercel.json` with `outputDirectory` pointing at the client output and a function including `dist/server/**`, and the `vercel-build` script. Verify the exact adapter import path, function config keys, and required file locations against the current Expo API-routes documentation. Add a clearly-marked caveat: responses through the Vercel adapter may be buffered rather than streamed, which breaks the SSE streaming used by `@terreno/ai`'s `/gpt/prompt` endpoint — link the upstream issue and state the workaround (keep AI streaming on the `@terreno/api` backend rather than routing it through Expo API routes on Vercel).
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 3.1
+  - Acceptance: every config key and import path verified against current Expo docs with the doc URL cited; the streaming caveat names the affected Terreno endpoint and gives a workaround; the section is labeled advanced.
+
+- [ ] **Task 3.3**: Disambiguate "Vercel AI SDK" across the repo
+  - Description: Grep for `Vercel` across `docs/`, package READMEs, and `.rulesync/rules/` (`rg -n "Vercel"`). For every occurrence referring to the AI library, ensure it reads "the Vercel AI SDK" and never bare "Vercel". Add a one-line note to `docs/reference/ai.md` clarifying that `@terreno/ai` is provider-agnostic via the Vercel AI SDK and that this is unrelated to Vercel hosting. Add the same clarification to the new deployment guide.
+  - Files: `docs/reference/ai.md`, `docs/how-to/deploy-web-to-vercel.md`, `.rulesync/rules/ai/00-ai.md`, `ai/README.md`, generated mirrors
+  - Depends on: Task 1.1
+  - Acceptance: `rg -n "Vercel" docs/ */README.md .rulesync/` shows every hit is either "the Vercel AI SDK" or a hosting context; `bun run rules:check` exits 0.
+
+## Phase 4: The `deploy-vercel` skill
+
+- [ ] **Task 4.1**: Author the skill
+  - Description: Create `.rulesync/skills/deploy-vercel/SKILL.md` with frontmatter (`name`, a `description` naming trigger phrases "deploy to Vercel", "deploy the web app", "put this online", and `targets: ['*']`). Body: When to use / when not to use (explicitly: not for the backend); Detect (Expo Router app, `web.output` value, existing `vercel.json`, backend URL); Configure (`vercel.json` per output mode, `vercel-build` script for server output); Wire the backend (set `EXPO_PUBLIC_API_URL` per Vercel environment; print the exact `corsOrigin` and `trustedOrigins` changes the user must apply on the backend and stop until they confirm, since the agent cannot safely edit a deployed backend's config); Deploy (`vercel`, then `vercel --prod` behind a confirmation gate); Verify (the four checks from Task 1.2); Troubleshoot (link the reference). Include a prohibition on deploying to production without explicit confirmation and on setting `corsOrigin: true`.
+  - Files: `.rulesync/skills/deploy-vercel/SKILL.md` (new)
+  - Depends on: Task 2.1, Task 3.2
+  - 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.
+  - 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.
+
+- [ ] **Task 4.3**: Generate skill mirrors
+  - Description: Run `bun run rules` and commit all generated files. Do not hand-edit generated output.
+  - Files: generated skill mirrors
+  - Depends on: Task 4.1, Task 4.2
+  - Acceptance: `bun run rules:check` exits 0; `deploy-vercel` appears under every configured target directory.
+
+## Phase 5: Validation
+
+- [ ] **Task 5.1**: Deploy the example frontend to a scratch Vercel project
+  - Description: Following only `docs/how-to/deploy-web-to-vercel.md`, deploy `example-frontend` to a scratch Vercel project pointed at a real deployed backend. Run all four verification checks. Record and fix every gap in the guide. Capture screenshots of the deployed app (logged in, with a deep link loaded directly) and the devtools websocket connection, saved under `/opt/cursor/artifacts/`.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.3, Task 2.2
+  - Acceptance: all four verification checks pass on the deployed app; every guide gap found is fixed; screenshots captured including the websocket evidence.
+
+- [ ] **Task 5.2**: Exercise the skill in a fresh session
+  - Description: Run the `deploy-vercel` skill in a fresh agent session against a second scratch project and confirm it reaches a working deployment, that the production confirmation gate fires, and that it correctly stops to ask the user to apply backend CORS changes. Fix any step where the skill needed information it did not have.
+  - Files: `.rulesync/skills/deploy-vercel/SKILL.md` plus mirrors
+  - Depends on: Task 4.3, Task 5.1
+  - Acceptance: the skill run produces a working deployment; both stop-and-confirm points are observed in the transcript; `bun run rules:check` exits 0 after any edits.

package/src/docs/versioned/57.1.0/tasks/deployment-foundation.md

@@ -0,0 +1,92 @@
+# Task List: Deployment Foundation
+
+See: [`docs/implementationPlans/deployment-foundation.md`](../implementationPlans/deployment-foundation.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` describe client environment variables and auth origins and must be re-checked after PR #869 merges. Unmarked tasks (env audit, Dockerfile, CI) are safe to implement immediately.
+
+## Instructions for the implementing agent
+
+- Derive facts from source, never from this task list. Where a task states a value (a port, a variable name, a default), verify it before writing it and correct the IP if it is wrong.
+- Every claimed failure symptom must be one you reproduced or found quoted in the codebase/tests. Do not invent error messages.
+- Do not add new runtime dependencies.
+- Run `bun run lint` before each commit; `bun run compile` if you touch `example-backend/src/`.
+
+## Phase 1: Environment variable reference
+
+- [x] **Task 1.1**: Audit every environment variable in the repo
+  - Description: Run `rg -n "process\.env\.[A-Z_]+" --glob '!node_modules' --glob '!*.test.ts'` and `rg -n "EXPO_PUBLIC_[A-Z_]+"` across the repo. Build a complete list of distinct variables with the file and package where each is read. Also check `Constants.expoConfig?.extra` reads in `rtk/src/constants.ts` (and the syncdb equivalent post-#869) since those are configured through `app.json` rather than the environment. Save the raw findings in the PR body.
+  - Files: none (findings in the PR body)
+  - Depends on: none
+  - Acceptance: the list is generated from grep output, not hand-written; every entry names the reading file; `extra`-based config is listed separately from `process.env` reads.
+
+- [x] **Task 1.2**: Complete `docs/reference/environment-variables.md`
+  - Description: Restructure the page into tables grouped by concern (Database, Auth — JWT, Auth — Better Auth, AI, Storage, Feature flags, Observability, MCP, Client/build-time). Each row: variable, read by (package), required or optional, default, secret (yes/no), and scope (server runtime / client build-time). Add an explicit callout explaining that `EXPO_PUBLIC_*` variables are inlined into the JavaScript bundle at build time — they are not secrets and cannot be changed without rebuilding. Every variable from Task 1.1 must appear exactly once.
+  - Files: `docs/reference/environment-variables.md`
+  - Depends on: Task 1.1
+  - Acceptance: every variable from the Task 1.1 audit appears; no variable is listed that does not appear in the audit; the build-time callout is present; secrets are marked.
+
+- [x] **Task 1.3**: `[RTK]` Update the `.env.example` files
+  - Description: Update `example-backend/.env.example` and `example-frontend/.env.example` so each contains every required variable for that app with safe placeholder values and a one-line comment per variable. Verify no real secret values are present. Add the Better Auth variables to the backend example, commented out, with a note pointing at `docs/how-to/configure-better-auth.md`.
+  - Files: `example-backend/.env.example`, `example-frontend/.env.example`
+  - Depends on: Task 1.2
+  - Acceptance: starting each example app using only its `.env.example` (with placeholders replaced by real local values) works; no value in either file is a real credential; every required variable from the reference is present.
+
+## Phase 2: Deployment baseline
+
+- [x] **Task 2.1**: Write `docs/explanation/deployment-baseline.md`
+  - Description: Explainer covering the seven baseline requirements from the IP. For each: what it is, why Terreno needs it, and the symptom when it is missing. Requirements 1, 3, and 5 need reproduced symptoms: (1) run the backend against a standalone `mongod` and quote the actual startup or change-stream error; (3) describe what happens to Socket.io on a platform with a short request timeout — cite the reconnect behavior in the client socket code; (5) build the web bundle with `EXPO_PUBLIC_API_URL` unset, then serve it and quote the resulting client-side failure. Requirement 6 must state that `@terreno/api-health` is part of the baseline (IP question DF4).
+  - Files: `docs/explanation/deployment-baseline.md` (new)
+  - Depends on: Task 1.2
+  - Acceptance: all seven requirements documented; symptoms for 1, 3, and 5 are reproduced and quoted verbatim, not paraphrased.
+
+- [x] **Task 2.2**: Add the web output-mode decision table
+  - Description: Add a section to `docs/explanation/deployment-baseline.md` with the three-mode table from the IP (`single`, `static`, `server`) covering output shape, API-route support, SSR support, hosting requirements, and current Terreno status. State explicitly: `single` is today's default, `static` is available now and improves SEO, and `server` requires Expo SDK ≥ 55 while the repo catalog is on `~54.0.29` — link PR #779 and [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md). Verify the current Expo version from the root `package.json` catalog rather than trusting this description.
+  - Files: `docs/explanation/deployment-baseline.md`
+  - Depends on: Task 2.1
+  - Acceptance: table has all three modes with all five columns; the stated Expo version matches the root catalog; no text implies SSR is currently available.
+
+- [x] **Task 2.3**: `[RTK]` Add the multi-environment section
+  - Description: Add a section listing exactly what differs between a staging and a production deployment: secret values, `MONGO_URI` (separate cluster or database), `EXPO_PUBLIC_API_URL` (requires a separate web build per environment — call this out, it is the non-obvious one), `corsOrigin`, Better Auth `trustedOrigins` and `BETTER_AUTH_URL`, and feature-flag defaults. Keep it under 40 lines; this is a checklist, not a guide.
+  - Files: `docs/explanation/deployment-baseline.md`
+  - Depends on: Task 2.2
+  - Acceptance: the section states that each environment needs its own web build; every item names the config location; under 40 lines.
+
+## Phase 3: Backend container
+
+- [x] **Task 3.1**: Verify and fix the backend's port and host binding
+  - Description: Read `example-backend/src/server.ts` and `api/src/expressServer.ts` to determine how the listen port and host are resolved. Confirm the port comes from `process.env.PORT` with a fallback and that the server binds `0.0.0.0` (or Express's default, which is all interfaces — verify rather than assume). If either is wrong for containerized deployment, fix it in the smallest possible change and add a test. If both are already correct, make no code change and record that finding.
+  - Files: `example-backend/src/server.ts` and/or `api/src/expressServer.ts` (only if a fix is needed), plus a test
+  - Depends on: none
+  - Acceptance: running `PORT=9999 bun run backend:dev` serves on 9999; the finding (fixed or already correct) is stated in the PR body with file citations.
+
+- [x] **Task 3.2**: Write the backend Dockerfile
+  - Description: Create `example-backend/Dockerfile` as a multi-stage build on `oven/bun:1-slim` (IP question DF2). Stage 1: copy the lockfile and workspace manifests, run `bun install --frozen-lockfile`, then compile the workspace packages the backend depends on (`@terreno/test`, `@terreno/api`, then the rest — mirror the ordering in the root `compile` script). Stage 2: copy only the built output and production dependencies, create and switch to a non-root user, set `ENV NODE_ENV=production`, expose the port, and set the entrypoint. Add a `HEALTHCHECK` hitting the health endpoint. Create `example-backend/.dockerignore` excluding `node_modules`, `.git`, `.env*`, test files, and build caches.
+  - Files: `example-backend/Dockerfile` (new), `example-backend/.dockerignore` (new)
+  - Depends on: Task 3.1
+  - Acceptance: `docker build -f example-backend/Dockerfile .` succeeds from the repo root; the image runs and `curl localhost:$PORT/health` returns `"healthy":true` against an external MongoDB replica set; `docker run` with `--user` unset shows a non-root user via `id`; the final image is under 500 MB.
+
+- [x] **Task 3.3**: Add a Docker build CI job
+  - Description: Create `.github/workflows/example-backend-docker.yml` that builds the image on pull requests touching `example-backend/**`, `api/**`, `package.json`, or `bun.lock`. Build only — do not push. Use layer caching. Follow the repo's convention of validating required inputs before use even though this job needs no secrets.
+  - Files: `.github/workflows/example-backend-docker.yml` (new)
+  - Depends on: Task 3.2
+  - Acceptance: the workflow parses as valid YAML; the path filter covers all four inputs; the job does not push an image or require registry credentials.
+
+- [x] **Task 3.4**: Reference the Dockerfile from the docs
+  - Description: Add a "Containerizing the backend" section to `docs/explanation/deployment-baseline.md` that explains the Dockerfile's structure and links `example-backend/Dockerfile` as the canonical copy rather than duplicating its contents (per IP question DF1). Call out the three details consumers get wrong: reading `PORT` from the environment, running as non-root, and compiling workspace packages in the right order.
+  - Files: `docs/explanation/deployment-baseline.md`
+  - Depends on: Task 3.2
+  - Acceptance: the section links the Dockerfile by path and does not paste more than a few illustrative lines; all three pitfalls are named.
+
+## Phase 4: Web build documentation
+
+- [x] **Task 4.1**: `[RTK]` Write `docs/how-to/build-for-web.md`
+  - Description: How-to covering: the build command (verify the exact script in `example-frontend/package.json` — do not assume `expo export -p web`), what the output directory contains for the current output mode, setting `EXPO_PUBLIC_API_URL` before the build with an explicit warning that it is inlined into the bundle, the `app.json` `extra` alternative (`BASE_URL`) and how the two interact — check the base-URL resolution priority order in the client package and document it accurately, serving the output locally to verify before deploying, and the SPA-routing requirement (all unknown paths must serve `index.html`) with a note that each host configures this differently. Link the provider guides.
+  - Files: `docs/how-to/build-for-web.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 2.2
+  - Acceptance: the build command matches an actual script; the base-URL priority order matches the client source and cites the file; the local-verification step works; the guide is listed in the how-to index.
+
+- [x] **Task 4.2**: Cross-link the deployment documentation
+  - Description: Add a "Deployment" grouping to `docs/how-to/README.md` and `docs/explanation/README.md` listing the baseline explainer, the web build guide, and the provider guides from [`deploy-to-vercel`](../implementationPlans/deploy-to-vercel.md) and [`deploy-to-gcp`](../implementationPlans/deploy-to-gcp.md). Ensure each provider guide links back to the baseline instead of restating the seven requirements.
+  - Files: `docs/how-to/README.md`, `docs/explanation/README.md`
+  - Depends on: Task 4.1
+  - Acceptance: both indexes have a Deployment grouping; every provider guide that exists links the baseline explainer; `bun run website:build` reports no new broken links.

package/src/docs/versioned/57.1.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
+
+- [x] **Task 1.1**: Write `docs/reference/ai.md`
+  - Description: Convert `.cursor/rules/ai/00-ai.mdc` into a public reference page. Sections, following `docs/reference/api.md`'s shape: Install; Commands; Architecture (file structure); `AIService` setup and full method table; structured-output helpers (`generateJsonValue`, `generateJsonObject`, `generateJsonArray`) including the JSON-normalization behavior and error logging; temperature presets; the `AIRequest` and `GptHistory` models with field tables; route registrars (`addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`) with endpoints, methods, and permissions; Langfuse integration; integration example with `setupServer`/`TerrenoApp`; environment variables; conventions; testing (including the mock-model pattern). Verify every symbol against `ai/src/index.ts`. Remove the internal-only conventions that make no sense to a consumer (for example instructions about not mocking `@terreno/api` belong in agent rules, not reference docs — use judgment).
+  - Files: `docs/reference/ai.md` (new)
+  - Depends on: none
+  - Acceptance: every documented symbol appears in `ai/src/index.ts`; the method table lists all `AIService` methods; all three route registrars documented with their permissions; no `.claude/` or `.cursor/` path referenced.
+
+- [x] **Task 1.2**: Write `docs/reference/admin-spa.md`
+  - Description: New reference page for `@terreno/admin-spa`, sourced from `admin-spa/README.md` and `admin-spa/src/`. Cover: what the package is (standalone Expo Router web admin SPA plus an Express plugin that serves it), install, the `AdminSpaServeApp` plugin registration with its options, building the SPA, configuring `apiBase`/`routeBase`, how it relates to the embedded `@terreno/admin-frontend` approach and when to choose each, and environment variables. Verify the plugin options against the source and against how `example-backend/src/server.ts` registers it.
+  - Files: `docs/reference/admin-spa.md` (new)
+  - Depends on: none
+  - Acceptance: every option documented exists in the source; includes a "standalone SPA vs embedded screens" decision paragraph; the registration example matches `example-backend/src/server.ts`.
+
+- [x] **Task 1.3**: Write `docs/reference/test.md`
+  - Description: New reference page for `@terreno/test`. Cover: what it provides (in-memory MongoDB management for bun test suites), install as a dev dependency, the `bunfig.toml` preload pattern, `setupEnvironment()`, the `TERRENO_TEST_USE_MEMORY_MONGO` / `TERRENO_TEST_MONGODB_URI` / `BUN_TEST_DISABLE_DB` environment variables, and the test-helper exports. Source the preload contract from `admin-backend/AGENTS.md`, `api/src/tests/bunSetup.ts`, and the `backend-test-env` skill. Keep it short — one page.
+  - Files: `docs/reference/test.md` (new)
+  - Depends on: none
+  - Acceptance: all three environment variables documented with their effects; the preload example matches an actual `bunfig.toml` in the repo; under 150 lines.
+
+- [ ] **Task 1.4**: `[RTK]` Fix the reference index
+  - Description: Update `docs/reference/README.md` to list every reference page that exists, including `ai.md`, `admin-spa.md`, `test.md`, `api-health.md`, `feature-flags.md`, `environment-variables.md`, and `syncdb.md`, with `rtk.md` under a Legacy heading. Cross-check against `ls docs/reference/` so nothing is orphaned and nothing listed is missing.
+  - Files: `docs/reference/README.md`
+  - Depends on: Task 1.1, Task 1.2, Task 1.3
+  - Acceptance: `ls docs/reference/*.md` and the index agree exactly; every link resolves; `bun run website:build` reports no new broken links.
+
+## Phase 2: Package READMEs
+
+- [x] **Task 2.1**: Define and apply the README template to the four stubs
+  - Description: Write the six-section template from the IP (Title/description, Install, Quick start, What's included, Documentation, License/Contributing) and apply it to the four stub READMEs: `ai/README.md` (source: the new `docs/reference/ai.md`), `admin-backend/README.md` (source: `.cursor/rules/admin-backend/00-admin-backend.mdc` + `docs/reference/admin-backend.md`), `admin-frontend/README.md` (same pattern), `api-health/README.md` (source: `api-health/src/`). Each Quick start must be a complete, runnable snippet — not a fragment. Every link absolute.
+  - Files: `ai/README.md`, `admin-backend/README.md`, `admin-frontend/README.md`, `api-health/README.md`
+  - Depends on: Task 1.1
+  - Acceptance: all four follow the six sections in order; `rg -n "\.claude/|\.cursor/" ai/README.md admin-backend/README.md admin-frontend/README.md api-health/README.md` returns nothing; every relative link replaced with an absolute URL; each Quick start compiles if pasted into a matching file.
+
+- [ ] **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/src/docs/versioned/57.1.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/src/docs/versioned/57.1.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/src/docs/versioned/57.1.0/tasks/feature-flags.md

@@ -0,0 +1,25 @@
+# Feature Flags — Task List
+
+**Status:** Closed (2026-08-20) — IP deferred; superseded by [feature-flags-openfeature.md](./feature-flags-openfeature.md). Open tasks below will not be executed.
+
+## Phase 1: Backend + Evaluation Engine
+
+- [ ] **Task 1.1**: Create `feature-flags/` package with FeatureFlag model (including archived field)
+- [ ] **Task 1.2**: Implement FeatureFlagsApp plugin with modelRouter CRUD
+- [ ] **Task 1.3**: Implement evaluation engine (field rules with dot notation, segment rules, deterministic hashing for boolean rollout and variant assignment)
+- [ ] **Task 1.4**: Implement `/evaluate` and `/segments` custom endpoints
+- [ ] **Task 1.5**: Write tests for evaluation logic
+- [ ] **Task 1.6**: Integrate with example-backend
+
+## Phase 2: Frontend Hook
+
+- [ ] **Task 2.1**: Add `useFeatureFlags()` hook to `@terreno/rtk`
+- [ ] **Task 2.2**: Export from rtk index
+
+## Phase 3: Example App Integration
+
+- [ ] **Task 3.1**: Wire up FeatureFlagsApp in example-backend, register model in AdminApp
+- [ ] **Task 3.2**: Add sample flags and use `useFeatureFlags()` in example-frontend
+- [ ] **Task 3.3**: Regenerate SDK
+
+See `docs/implementationPlans/feature-flags.md` for full details on each task.