@terreno/mcp 57.2.0 → 57.3.0

package/dist/docs/versioned/0.28.0/tasks/deploy-to-gcp.md

@@ -1,99 +0,0 @@
-# Task List: Deploy to GCP (Generalized) + `deploy-gcp` Skill
-
-See: [`docs/implementationPlans/deploy-to-gcp.md`](../implementationPlans/deploy-to-gcp.md)
-
-**RTK deprecation flag:** None. The only client-side surface is `EXPO_PUBLIC_API_URL`, which is unchanged by PR #869. Safe to implement before #869 merges.
-
-## Instructions for the implementing agent
-
-- Use placeholder variables in all documentation: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$WEB_BUCKET`, `$UPLOADS_BUCKET`. Never hardcode a real project ID, bucket, or URL.
-- Grep for `flourish` in every file you write or edit before committing: `rg -i flourish <file>`. The only permitted matches are inside `infra/flourish/`.
-- Do **not** run `gcloud` commands that create or modify resources unless the user has explicitly named a target project in the request.
-- Verify every `gcloud` flag you document against `gcloud run deploy --help` before writing it. Do not guess flag names.
-- Run `bun run lint` before each commit; run `bun run rules:check` after touching `.rulesync/`.
-
-## Phase 1: Generalize the how-to guides
-
-- [ ] **Task 1.1**: Write `docs/how-to/deploy-backend-to-cloud-run.md`
-  - Description: New guide covering: prerequisites (gcloud installed and authenticated, billing enabled, required APIs — `run`, `artifactregistry`, `secretmanager`, `compute`); creating an Artifact Registry repo; building and pushing the backend image; creating Secret Manager secrets for `MONGO_URI`, `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`, and `BETTER_AUTH_SECRET`; creating the runtime service account with least-privilege roles; the `gcloud run deploy` invocation with `--session-affinity`, `--timeout`, `--min-instances`, `--set-secrets`, and `--set-env-vars`; and verification via `curl $SERVICE_URL/health`. Use placeholder variables throughout. Read `example-backend/src/server.ts` and `docs/reference/environment-variables.md` to get the env var list right — do not copy it from this task description without checking.
-  - Files: `docs/how-to/deploy-backend-to-cloud-run.md` (new)
-  - Depends on: none
-  - Acceptance: `rg -i flourish docs/how-to/deploy-backend-to-cloud-run.md` returns nothing; every env var named exists in `docs/reference/environment-variables.md` or the backend source; every `gcloud` flag used appears in `gcloud run deploy --help`.
-
-- [ ] **Task 1.2**: Add the production constraints section
-  - Description: Add a "Production constraints" section to the backend guide as a symptom → cause → fix table covering at minimum: (a) websockets disconnect every few requests → no session affinity → add `--session-affinity`; (b) long-lived socket connections drop at 5 minutes → default request timeout → raise `--timeout`; (c) realtime and live feature flags stop working → MongoDB is not a replica set → use Atlas or a replica set, because change streams require one; (d) first request after idle is slow and sockets churn → scaled to zero → `--min-instances=1`; (e) browser requests fail CORS → `corsOrigin` in `setupServer` and Better Auth `trustedOrigins` do not include the web origin. Verify claim (c) against `feature-flags` live-update code before writing it.
-  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`
-  - Depends on: Task 1.1
-  - Acceptance: all five rows present with a concrete symptom; the change-streams claim is verified against the source and the source path is cited in the guide.
-
-- [ ] **Task 1.3**: Write `docs/how-to/deploy-web-to-gcs-cdn.md`
-  - Description: New guide covering: building the web bundle (`bunx expo export -p web` — confirm the exact command against `example-frontend/package.json` scripts), the requirement to set `EXPO_PUBLIC_API_URL` at build time because it is inlined into the bundle, creating and configuring the GCS bucket with public read and `notFoundPage=index.html` for client-side routing, the five CDN resources (backend bucket, URL map, static IP, HTTP(S) proxy, forwarding rule), pointing DNS at the IP, and cache invalidation after each deploy. Include a note that this is a static-only path and link [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md) for the SSR future.
-  - Files: `docs/how-to/deploy-web-to-gcs-cdn.md` (new)
-  - Depends on: none
-  - Acceptance: no Flourish strings; the export command matches an actual script in `example-frontend/package.json`; the guide explains why `EXPO_PUBLIC_API_URL` must be set before building, not after.
-
-- [ ] **Task 1.4**: Write the architecture explainer
-  - Description: Create `docs/explanation/deployment-architecture-gcp.md` explaining the reference topology (reuse the mermaid diagram from the IP), what each component is responsible for, why Cloud Run rather than App Engine or GKE, why Atlas rather than self-hosted Mongo, and the tradeoffs of static web hosting versus a server-rendered deployment. Keep it conceptual — no commands.
-  - Files: `docs/explanation/deployment-architecture-gcp.md` (new)
-  - Depends on: Task 1.1, Task 1.3
-  - Acceptance: contains the topology diagram; contains no shell commands; explains at least three explicit tradeoffs.
-
-- [ ] **Task 1.5**: Rewire the existing GCP how-to and index
-  - Description: Replace `docs/how-to/deploy-to-gcp.md` with a short index page linking the two new guides and the explainer, preserving the old anchor names where practical so existing links do not break. Update `docs/how-to/README.md` to list the new guides. Check `website/` for any hardcoded reference to the old page path and update it.
-  - Files: `docs/how-to/deploy-to-gcp.md`, `docs/how-to/README.md`, `website/` (as needed)
-  - Depends on: Task 1.1, Task 1.3, Task 1.4
-  - Acceptance: `bun run website:build` succeeds with no new broken-link warnings introduced by this change.
-
-## Phase 2: Terraform module and Flourish separation
-
-- [ ] **Task 2.1**: Extract the generic backend module
-  - Description: Create `terraform/modules/terreno-backend/` with `main.tf`, `variables.tf`, `outputs.tf`, and `README.md`. Resources: Artifact Registry repository, Cloud Run v2 service (session affinity, timeout, min/max instances, secret env refs), Secret Manager secrets (created empty, values supplied out-of-band), runtime service account with `secretmanager.secretAccessor` and object admin on a supplied uploads bucket, and optional Workload Identity Federation pool for CI. Every value that could differ between users must be a variable with a description and no Flourish default. Outputs: service URL, service account email, registry path.
-  - Files: `terraform/modules/terreno-backend/main.tf`, `variables.tf`, `outputs.tf`, `README.md` (all new)
-  - Depends on: Task 1.1
-  - Acceptance: `terraform init && terraform validate` passes in the module directory; `rg -i flourish terraform/modules/` returns nothing; every variable has a `description`.
-
-- [ ] **Task 2.2**: Relocate Flourish-specific terraform
-  - Description: Move Flourish's environment configuration from `terraform/` to `infra/flourish/`, leaving only `terraform/modules/` behind. Update every path reference: `.github/workflows/cd.yml`, `terraform/README.md` (split into a generic module README and `infra/flourish/README.md`), `AGENTS.md` / `CLAUDE.md` if they reference `terraform/README.md`, and any script under `scripts/`. Use `git mv` so history is preserved.
-  - Files: `infra/flourish/**` (moved), `terraform/README.md`, `.github/workflows/cd.yml`, `AGENTS.md`, `CLAUDE.md`, `scripts/**`
-  - Depends on: Task 2.1
-  - Acceptance: `rg -n "terraform/" --glob '!infra/**' --glob '!terraform/**'` shows no stale paths pointing at moved files; the `cd.yml` workflow references the new location; `bun run rules:check` exits 0 after regenerating rules.
-
-- [ ] **Task 2.3**: Parameterize the GCS hosting script
-  - Description: Rewrite `scripts/setup-gcs-hosting.sh` to require `--project`, `--site-name`, and `--bucket` arguments (or positional equivalents) with a usage message and a check that all are present. Remove every hardcoded Flourish project, bucket, and service-account value. Keep the resource-creation logic intact. Add a `--dry-run` flag that prints commands without executing them.
-  - Files: `scripts/setup-gcs-hosting.sh`
-  - Depends on: Task 1.3
-  - Acceptance: running with no arguments prints usage and exits non-zero; `--dry-run` produces commands containing the supplied values and no Flourish strings; `rg -i flourish scripts/setup-gcs-hosting.sh` returns nothing.
-
-## Phase 3: The `deploy-gcp` skill
-
-- [ ] **Task 3.1**: Author the skill
-  - Description: Create `.rulesync/skills/deploy-gcp/SKILL.md` with frontmatter (`name: deploy-gcp`, a `description` that names the trigger phrases "deploy to GCP", "deploy to Cloud Run", "ship the backend", and `targets: ['*']`). Body sections in this order: When to use / When not to use; Preflight checks (project layout detection, `gcloud config get-value project`, required APIs, replica-set verification of `MONGO_URI`); **Plan and confirm** — print target project, region, service name, and every resource to be created or updated, then stop and require explicit user confirmation before any mutating command; Backend deploy steps; Frontend deploy steps; Verification (`curl $SERVICE_URL/health` expecting `"healthy":true`, fetch web root); Troubleshooting (link the reference file). Include an explicit prohibition: never deploy to a project the user did not name in the request, and never create or modify secrets without echoing which secret names will change.
-  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` (new)
-  - Depends on: Task 1.1, Task 1.3
-  - Acceptance: frontmatter has `name`, `description`, and `targets`; the confirmation gate appears before the first mutating command; every command in the skill also appears in the how-to guides (no skill-only knowledge).
-
-- [ ] **Task 3.2**: Add the troubleshooting reference
-  - Description: Create `.rulesync/skills/deploy-gcp/references/troubleshooting.md` containing the symptom → cause → fix table from Task 1.2 plus deploy-time failures: image push permission denied, secret access denied at cold start, Cloud Run revision failing health checks because `PORT` is not read from the environment, and CDN serving a stale bundle after deploy. For each, give the exact log line or error message the user will see.
-  - Files: `.rulesync/skills/deploy-gcp/references/troubleshooting.md` (new)
-  - Depends on: Task 3.1
-  - Acceptance: at least nine rows; each row quotes an actual error string rather than paraphrasing.
-
-- [ ] **Task 3.3**: Generate skill mirrors
-  - Description: Run `bun run rules` and commit every generated file under `.cursor/skills/`, `.claude/skills/`, `.devin/skills/`, `.github/skills/`, and `.agents/skills/`. Do not hand-edit generated files.
-  - Files: generated skill mirrors
-  - Depends on: Task 3.1, Task 3.2
-  - Acceptance: `bun run rules:check` exits 0; `deploy-gcp` appears under each configured target directory.
-
-## Phase 4: Validation
-
-- [ ] **Task 4.1**: Dry-run the guide end to end
-  - Description: Following **only** `docs/how-to/deploy-backend-to-cloud-run.md` and `docs/how-to/deploy-web-to-gcs-cdn.md` (no internal knowledge, no `infra/flourish/`), deploy `example-backend` and `example-frontend` to a scratch GCP project. Record every point where the guide was wrong, incomplete, or required outside knowledge. Fix the guides. Capture the successful `curl $SERVICE_URL/health` output and the loaded web app as artifacts under `/opt/cursor/artifacts/`.
-  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`, `docs/how-to/deploy-web-to-gcs-cdn.md`
-  - Depends on: Task 1.1, Task 1.3, Task 2.3
-  - Acceptance: the deploy succeeds; `/health` returns `"healthy":true`; the web app loads and can log in against the deployed backend; every guide correction is committed.
-
-- [ ] **Task 4.2**: Exercise the skill against the validated guide
-  - Description: Run the `deploy-gcp` skill in a fresh agent session against the same scratch project and confirm it reaches the same result, including the confirmation gate firing before any mutation. Note any step where the skill needed information the guide did not provide and fix the skill.
-  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` plus mirrors
-  - Depends on: Task 3.3, Task 4.1
-  - Acceptance: the skill run produces a working deploy; the confirmation gate is observed in the transcript; `bun run rules:check` exits 0 after any skill edits.

package/dist/docs/versioned/0.28.0/tasks/deployment-foundation.md

@@ -1,92 +0,0 @@
-# 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
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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
-
-- [ ] **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.
-
-- [ ] **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/dist/docs/versioned/0.28.0/tasks/docs-reference-coverage.md

@@ -1,93 +0,0 @@
-# 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.28.0/tasks/feature-flags.md

@@ -1,23 +0,0 @@
-# Feature Flags — Task List
-
-## 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.

package/dist/docs/versioned/0.28.0/tasks/model-router-actions.md

@@ -1,46 +0,0 @@
-# modelRouter Actions — Task List
-
-## Phase 1: Foundation (types + runtime + per-route OpenAPI middleware)
-
-- [ ] **Task 1.1**: Add `zod ^4.3.6` as a **peerDependency** of `@terreno/api` (also pin `^4.3.6` in `devDependencies` so the package compiles/tests on its own) and `@asteasolutions/zod-to-openapi ^8.5.0` as a regular `dependency` (it bundles its own usage). Use Bun catalog for Zod if a catalog version exists.
-- [ ] **Task 1.2**: Create `api/src/docLoader.ts` exporting `loadDocOr404(model, id, populatePaths?)`. Behavior matches the existing permission middleware doc-load (`permissions.ts:148–200`): 404 on missing, soft-delete-aware metadata via `model.collection.findOne` fallback.
-- [ ] **Task 1.3**: Refactor `permissionMiddleware` in `api/src/permissions.ts` to call `loadDocOr404`. Add a regression test asserting soft-delete 404 metadata is intact. No public API change.
-- [ ] **Task 1.4**: Create `api/src/actions.ts` with public types: `ActionContext`, `BaseActionConfig`, `InstanceActionConfig`, `CollectionActionConfig`. Also export `defineInstanceAction()` and `defineCollectionAction()` identity helpers that preserve per-action generics across the `Record<string, ...>` boundary.
-- [ ] **Task 1.5**: Implement `runActionPermissions(action, scope, req, doc?)` in `api/src/actions.ts`. Maps HTTP method + scope → CRUD method. Pre-doc denial → **405** (matches `permissions.ts:136`). Post-doc denial → **403** (matches `permissions.ts:203`). Uses existing `checkPermissions` helper so `[]` arrays disable the action via 405.
-- [ ] **Task 1.6**: Implement `validateActionRequest(action, req)` in `api/src/actions.ts`. Runs Zod `safeParse` on body/query when schemas provided. On failure throws `APIError({status: 400, title: "Validation failed", fields})` — emitted as `meta.fields` on the wire by `errors.ts:117–121`. Parsed values returned through `ctx`, NOT by mutating `req.query` (Express 5 getter).
-- [ ] **Task 1.7**: Implement `wrapActionResponse(handlerResult, action, res)` — auto-wraps in `{data: ...}` with `status ?? 200`; skips wrap if `res.headersSent`. Default `null` for `undefined` return.
-- [ ] **Task 1.8**: Implement `assertNoActionCollisions(model, options)` — throws synchronously on:
-  - Action name doesn't match `/^[A-Za-z][A-Za-z0-9_-]+$/` (incl. empty names).
-  - Action name matches a Mongoose array-field path (would collide with `POST /:id/:field` at `api.ts:1159–1175`).
-- [ ] **Task 1.9**: Implement `createActionOpenApiMiddleware({action, scope, actionName, model})` in `api/src/actions.ts`. Per-request middleware that on first request through the route calls `options.openApi.path()` with an Operation Object built from inlined Zod-derived schemas (`OpenApiGeneratorV3.generateSchema()`). No-op when `options.openApi` is undefined. Sets `operationId: '${tag}_${actionName}'`. Tag defaults to `model.collection.collectionName`.
-- [ ] **Task 1.10**: Implement `registerActionRoutes(router, model, options)` — composes the middleware chain in order: `authenticateMiddleware(options.allowAnonymous)` → action OpenAPI middleware → pre-doc `runActionPermissions` → (instance only) `loadDocOr404` + post-doc `runActionPermissions` → `validateActionRequest` → wrapped `asyncHandler(action.handler)` → `wrapActionResponse`.
-- [ ] **Task 1.11**: Extend `ModelRouterOptions<T>` in `api/src/api.ts` with `instanceActions?` and `collectionActions?`. Inside `_buildModelRouter`, call `assertNoActionCollisions` and `registerActionRoutes` in the pre-CRUD `endpoints` slot (before the user's `options.endpoints` callback runs, so actions take precedence on path conflicts).
-- [ ] **Task 1.12**: Re-export `ActionContext`, `InstanceActionConfig`, `CollectionActionConfig`, `defineInstanceAction`, `defineCollectionAction` from `api/src/index.ts`.
-- [ ] **Task 1.13**: Write tests in `api/src/actions.test.ts` covering all Phase 1 acceptance criteria: registration validation (missing perms throws, empty perms registers but returns 405, action-name regex, array-field collision, empty name); routing (instance + collection happy path for GET + POST; `ctx.doc` set on instance; `req.obj` set on instance for parity with CRUD); permission flow (pre-doc → 405, post-doc → 403, 401 from passport, `IsAuthenticatedOrReadOnly` GET works with `allowAnonymous: true`, `IsOwner` doc-aware); validation (good body, bad body → 400 with `meta.fields`, query schema, Zod coercion through `ctx`, `req.query` not mutated, Zod `.strip` default observed); response shape (envelope, custom `status`, null/undefined return, `res.headersSent` escape hatch, custom list-style envelope via `res.json` + return); doc loading (404 missing, 404 metadata on soft-deleted); **type ergonomics**: a TS-level compile-only test that `defineInstanceAction<TDoc>({body: z.object({x: z.string()}), handler: async ({doc, body}) => {}})` infers `doc: TDoc` and `body: {x: string}` correctly.
-- [ ] **Task 1.14**: Add a regression test for **co-registration**: a modelRouter using BOTH `instanceActions: {foo: ...}` AND `endpoints: (router) => router.get('/:id/foo', ...)` — assert that the action wins (registered first in the pre-CRUD slot, before user `options.endpoints`). Same test for `collectionActions` colliding with a user `endpoints` route. Documents the precedence.
-
-## Phase 2: OpenAPI verification
-
-- [ ] **Task 2.1**: Tests against the generated `openapi.json` for actions registered via `TerrenoApp`: operation appears under `paths`; correct method + path; default tag = `model.collection.collectionName`; per-action `tag` override; inlined request body schema; inlined response schema under configured status; `id` path param present for instance actions; deterministic `operationId`.
-- [ ] **Task 2.2**: Same suite but for actions registered via the legacy `setupServer` path (`expressServer.ts:257`) — verifies the per-request OpenAPI emission fires on first hit and produces parity with the `TerrenoApp` path.
-
-## Phase 3: Migration + dogfooding
-
-- [ ] **Task 3.1**: Migrate `api/src/consentApp.ts` `/consent-forms` `endpoints` actions (scope: only those three actions; `/consents/*` routes at lines 195–457 are out of scope):
-  - `generate` → `collectionActions.generate`, conditional on `aiConfig` (built at runtime into the `collectionActions` map before passing to `modelRouter`).
-  - `translate` → `collectionActions.translate`, same conditional.
-  - `/:id/publish` → `instanceActions.publish`.
-- [ ] **Task 3.2**: Confirm all existing consent-form tests pass without modification.
-- [ ] **Task 3.3**: Add a `markComplete` instance action and a `bulkComplete` collection action to `example-backend/src/api/todos.ts` to demonstrate both scopes (and document the Zod `.strict()` recommendation in the example).
-- [ ] **Task 3.4**: Regenerate `example-frontend` SDK: `cd example-frontend && bun run sdk`.
-- [ ] **Task 3.5**: Smoke-test: run `bun run backend:dev` and `bun run frontend:web` together; exercise both new todo actions end-to-end (curl + the regenerated hooks).
-
-## Phase 4: Consumer compile-check + docs
-
-- [ ] **Task 4.1**: Run `bun run compile` (and `bun run test` where present) in each in-repo consumer of `@terreno/api`: `admin-backend`, `admin-frontend`, `ai`, `api-health`, `feature-flags`, `mcp-server`, `rtk`, `example-backend`, `example-frontend`. Fix any breakage from the new deps.
-- [ ] **Task 4.2**: Document in the explainer that `zod` is a `peerDependency` of `@terreno/api` — consumers must install Zod themselves (already true for `example-backend`). Note this in the changelog as a breaking install requirement.
-- [ ] **Task 4.3**: Write `docs/explanation/model-router-actions.md` covering: motivation; call-site example; semantics (permission method mapping, 405 vs 403 status codes, response envelope, validation error wire shape at `meta.fields`, collision detection, Zod `.strict()` recommendation, concurrency caveat for action handlers, `queryFilter` not applied to instance auto-load); migration notes from hand-rolled `endpoints` actions.
-- [ ] **Task 4.4**: Update `mcp-server/src/tools.ts` `generate_route` (and any related prompt in `prompts.ts`) to suggest `instanceActions`/`collectionActions`.
-- [ ] **Task 4.5**: Bump `@terreno/api` package version in `api/package.json`. Prepare a changelog entry mentioning: the new feature, the new deps (`zod`, `@asteasolutions/zod-to-openapi`), the behavior-preserving permission middleware refactor, and the new `operationId`-based hook names in regenerated SDKs.
-
-See `docs/implementationPlans/model-router-actions.md` for full details on each task.

package/dist/docs/versioned/0.28.0/tasks/model-router-mcp.md

@@ -1,105 +0,0 @@
-# Tasks: modelRouter MCP Tools
-
-*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
-
----
-
-### Phase 1: Core MCP Infrastructure
-
-- [ ] **Task 1.1**: Define MCP types and interfaces
-  - Description: Create `MCPConfig` interface (with `methods` defaulting to `['list', 'read']`, `excludeFields` for hiding sensitive fields, `maxLimit` defaulting to 50), `MCPRegistryEntry`, and add `mcp?: MCPConfig` to `ModelRouterOptions`. Create the `api/src/mcp/` directory structure.
-  - Files: `api/src/mcp/types.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (add mcp to ModelRouterOptions)
-  - Depends on: none
-  - Acceptance: Types compile, existing tests still pass, `mcp` is an optional field on `ModelRouterOptions`
-
-- [ ] **Task 1.2**: Build MCP tool registry
-  - Description: Create a global registry that collects MCP tool entries as `modelRouter()` is called. When a modelRouter has `mcp` config, it pushes an entry to the registry. Export `getMCPRegistry()` internally and `getMCPTools()` publicly (returns `Record<string, CoreTool>`).
-  - Files: `api/src/mcp/registry.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (register in modelRouter function)
-  - Depends on: Task 1.1
-  - Acceptance: Calling `modelRouter(Todo, { ..., mcp: { methods: ['list', 'read'] } })` adds entries to the registry. `getMCPTools()` returns CoreTool objects.
-
-- [ ] **Task 1.3**: Generate Zod schemas from Mongoose models
-  - Description: Build a utility that converts a Mongoose model's schema into Zod schemas suitable for MCP tool `inputSchema`. Handle common field types (String, Number, Boolean, Date, ObjectId, Array, Mixed). Generate separate schemas for create (required fields), update (all optional + id required), read (id + optional populate), list (queryFields + pagination), and delete (id only). Respect `excludeFields` — omit listed fields from all generated schemas.
-  - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
-  - Depends on: Task 1.1
-  - Acceptance: Given a Mongoose model, produces valid Zod schemas for each CRUD method. Tests cover all common field types. `excludeFields` removes specified fields from schemas.
-
-- [ ] **Task 1.4**: Generate MCP tool definitions from registry entries
-  - Description: Build tool generator that takes an `MCPRegistryEntry` and produces both `@modelcontextprotocol/sdk` `Tool` objects (JSON Schema input) and Vercel `ai` SDK `CoreTool` objects. Auto-generate descriptions from model name, fields, and queryFields. Apply `toolPrefix` naming (`{prefix}_{method}`). Only generate tools for methods listed in `mcp.methods`.
-  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
-  - Depends on: Task 1.2, Task 1.3
-  - Acceptance: Registry entry with `methods: ['list', 'read']` produces exactly `todos_list` and `todos_read` tools with correct schemas and descriptions.
-
-- [ ] **Task 1.5**: Implement MCP tool handlers (CRUD execution)
-  - Description: Build the execute functions for each CRUD tool. Each handler: (1) extracts user from auth context, (2) checks permissions via `checkPermissions()`, (3) for read/update/delete: loads document and checks object-level permissions, (4) applies queryFilter and population for list, (5) enforces `maxLimit` cap on list results (default 50), (6) runs pre/post hooks, (7) strips `excludeFields` from response data, (8) serializes via `mcpResponseHandler` or default. Reuse internal logic from REST handlers but decoupled from Express req/res.
-  - Files: `api/src/mcp/handlers.ts`, `api/src/mcp/handlers.test.ts`
-  - Depends on: Task 1.4
-  - Acceptance: Each CRUD handler works with correct permission checks, population, filtering. List enforces maxLimit. excludeFields are stripped from responses. Tests cover: successful CRUD, permission denied (403), not found (404), validation errors, owner filtering, population, maxLimit enforcement, excludeFields stripping.
-
-- [ ] **Task 1.6**: Auth-agnostic user extraction for MCP
-  - Description: Build middleware/utility that extracts user from MCP transport headers using whichever auth provider is configured (JWT via passport or Better Auth via `auth.api.getSession()`). Should mirror `authenticateMiddleware` behavior but work with raw headers instead of Express req.
-  - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`
-  - Depends on: Task 1.1
-  - Acceptance: Given headers with a valid JWT, returns User. Given headers with a valid Better Auth session token, returns User. Given no/invalid headers with `allowAnonymous: false`, returns null. Works with both auth providers.
-
-- [ ] **Task 1.7**: Mount MCP server in TerrenoApp
-  - Description: In `TerrenoApp`'s startup flow, check if the MCP registry has any entries. If so, create an `McpServer` instance from `@modelcontextprotocol/sdk`, register all tools from the registry, set up `StreamableHTTPServerTransport`, and mount on `/mcp`. Wire up `ListToolsRequestSchema` and `CallToolRequestSchema` handlers.
-  - Files: `api/src/mcp/server.ts`, `api/src/expressServer.ts` (or TerrenoApp equivalent — integrate into startup)
-  - Depends on: Task 1.4, Task 1.5, Task 1.6
-  - Acceptance: Starting a TerrenoApp with MCP-configured models auto-mounts `/mcp`. MCP clients can list tools and call them. No MCP config = no `/mcp` endpoint.
-
-- [ ] **Task 1.8**: Integration tests
-  - Description: End-to-end tests that spin up a TerrenoApp with MCP-configured models and test the full flow: MCP client connects, lists tools, performs CRUD via tool calls, verifies permissions block unauthorized access, verifies population and query filtering work.
-  - Files: `api/src/mcp/integration.test.ts`
-  - Depends on: Task 1.7
-  - Acceptance: Full CRUD lifecycle works over MCP. Permission denials return appropriate errors. Owner filtering restricts results. Population returns nested data.
-
-- [ ] **Task 1.9**: Export public API
-  - Description: Export `MCPConfig`, `getMCPTools()`, and any other public interfaces from `@terreno/api`'s main index. Update package exports.
-  - Files: `api/src/index.ts`, `api/src/mcp/index.ts`
-  - Depends on: Task 1.7
-  - Acceptance: Consumers can `import { MCPConfig, getMCPTools } from "@terreno/api"`.
-
----
-
-### Phase 2: Frontend Integration
-
-- [ ] **Task 2.1**: `useTerrenoChat` hook
-  - Description: Create a hook wrapping `@ai-sdk/react`'s `useChat()` pre-configured for a Terreno MCP backend. Handles Bearer token injection from auth state (reads from Redux store — JWT token or Better Auth session). Accepts `baseURL` and optional `tools` override.
-  - Files: `rtk/src/useTerrenoChat.ts`, `rtk/src/useTerrenoChat.test.ts`
-  - Depends on: Task 1.7
-  - Acceptance: Hook connects to MCP-enabled backend, streams responses with tool calls, injects auth token automatically.
-
-- [ ] **Task 2.2**: `useMCPTools` hook
-  - Description: Create a hook that discovers available MCP tools from the backend. Uses `@ai-sdk/mcp`'s `createMCPClient()` to connect and list tools. Caches result. Returns typed tool list.
-  - Files: `rtk/src/useMCPTools.ts`, `rtk/src/useMCPTools.test.ts`
-  - Depends on: Task 1.7
-  - Acceptance: Hook returns list of available tools with names, descriptions, and input schemas. Handles connection errors gracefully.
-
-- [ ] **Task 2.3**: Export frontend public API
-  - Description: Export `useTerrenoChat` and `useMCPTools` from `@terreno/rtk`. Add `@ai-sdk/react` and `@ai-sdk/mcp` as dependencies.
-  - Files: `rtk/src/index.ts`, `rtk/package.json`
-  - Depends on: Task 2.1, Task 2.2
-  - Acceptance: Consumers can `import { useTerrenoChat, useMCPTools } from "@terreno/rtk"`.
-
----
-
-### Phase 3: Examples & Polish
-
-- [ ] **Task 3.1**: Add MCP config to example backend models
-  - Description: Add `mcp` config to the existing Todo and Food models in `example-backend`. Todos: read-only (`list`, `read`). Food: full CRUD. Include `mcpResponseHandler` example on one model.
-  - Files: `example-backend/src/routes/todos.ts`, `example-backend/src/routes/food.ts`
-  - Depends on: Task 1.9
-  - Acceptance: Starting example-backend mounts `/mcp` with todo and food tools. MCP client can list and call them.
-
-- [ ] **Task 3.2**: Demo chat screen in example frontend
-  - Description: Add a simple chat screen to `example-frontend` that uses `useTerrenoChat()` to connect to the MCP-enabled backend. Show tool calls inline (e.g., "Searching todos..." with results). Navigation from home screen.
-  - Files: `example-frontend/app/chat.tsx`, `example-frontend/app/_layout.tsx` (add nav)
-  - Depends on: Task 2.3, Task 3.1
-  - Acceptance: User can chat with the AI, which calls MCP tools to query/modify data. Tool calls and results visible in the UI.
-
-- [ ] **Task 3.3**: Refine auto-generated tool descriptions
-  - Description: Improve description generation quality. Include field types, required vs optional, enum values, ref model names. Test with multiple model shapes to ensure descriptions are helpful for LLMs.
-  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
-  - Depends on: Task 1.4
-  - Acceptance: Descriptions include actionable detail. LLM can understand what each tool does and what inputs are expected without additional context.