@terreno/mcp 0.28.0 → 0.29.0

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

@@ -0,0 +1,166 @@
+# Implementation Plan: Deploy to GCP (Generalized) + `deploy-gcp` Skill
+
+**Status:** Approved — decisions recorded (2026-07-29)
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`deployment-foundation`](deployment-foundation.md) for the shared Dockerfile and env reference (soft dependency — Phase 1 can start in parallel)
+**RTK deprecation flag:** None for the backend and infrastructure. The frontend build step is data-layer agnostic (`expo export -p web` output is static either way). The only RTK-adjacent content is the `EXPO_PUBLIC_API_URL` env var, which survives the syncdb migration.
+
+## Goal
+
+Turn Terreno's GCP deployment story from "how Flourish deploys Terreno" into "how anyone deploys a Terreno app to GCP", and give agents a skill that can execute it. Today `docs/how-to/deploy-to-gcp.md` hardcodes the `flourish-terreno` project, `flourish-terreno-terreno-demo` bucket names, and Flourish's service-account layout; `terraform/README.md` is Flourish-specific; and `scripts/setup-gcs-hosting.sh` provisions Flourish's two static sites. None of it is reusable by an outside user, and no skill wraps any of it.
+
+## Non-Goals
+
+- Multi-region or multi-environment (staging/prod) topologies beyond a documented single extra environment.
+- Kubernetes/GKE. Cloud Run only.
+- Managing MongoDB inside GCP. Mongo Atlas is the documented path; self-hosted Mongo is explicitly out of scope.
+- Replacing Flourish's existing terraform — that is relocated, not rewritten (see program question P5).
+
+## Blocking questions
+
+**Recorded 2026-07-29.**
+
+| # | Question | Decision |
+|---|----------|----------|
+| GC1 | Frontend web hosting | **GCS + Cloud CDN as GCP default**, plus **Netlify** (document the existing Flourish/Terreno Netlify pattern as a first-class alternative for static web export) |
+| GC2 | Database guidance | **MongoDB Atlas only** for launch; add a **future-work note** toward Postgres when the data layer supports it |
+| GC3 | terraform or gcloud | **C** — `gcloud` quickstart + terraform for production |
+| GC4 | Reusable terraform module | **B** — `terraform/modules/terreno-backend/` |
+| GC5 | Flourish infra location (→ P5) | **C** — `infra/flourish/` now; **migrate to B** (private repo) post-launch |
+| GC6 | `deploy-gcp` skill deploys? | **C** — full deploy behind explicit confirmation gate |
+| GC7 | Secret management | **A** — Secret Manager for secrets; plain env for non-secrets |
+
+## Architecture
+
+### Reference topology (documented default)
+
+**GCP path:** GCS + Cloud CDN for static web export (see diagram below).
+
+**Netlify path:** Document the existing Terreno/Flourish Netlify static hosting pattern as a first-class alternative for `expo export -p web` — same backend topology, different static host.
+
+```mermaid
+flowchart TD
+  U["User<br/>iOS / Android / Web"]
+  CDN["Cloud CDN + GCS bucket<br/>expo export -p web output"]
+  CR["Cloud Run<br/>@terreno/api backend"]
+  SM["Secret Manager<br/>auth secrets, MONGO_URI"]
+  AT["MongoDB Atlas<br/>replica set (change streams)"]
+  GCS["GCS bucket<br/>user file uploads"]
+  AR["Artifact Registry<br/>backend image"]
+  U -->|"web"| CDN
+  U -->|"native app"| CR
+  CDN -->|"API calls"| CR
+  CR --> SM
+  CR --> AT
+  CR --> GCS
+  AR --> CR
+```
+
+### Required GCP resources
+
+| Resource | Purpose | Notes |
+|----------|---------|-------|
+| Artifact Registry repo | backend container images | Regional, Docker format |
+| Cloud Run service | backend | Min instances 0 for dev, ≥1 for prod (cold starts break websockets); `--session-affinity` required for Socket.io |
+| Secret Manager secrets | auth secrets + `MONGO_URI` | Mounted as env vars via `--set-secrets` |
+| GCS bucket (web) | static web export | `notFoundPage=index.html` for client-side routing |
+| Backend bucket + URL map + IP + proxy + forwarding rule | Cloud CDN in front of the web bucket | The five resources the current script creates |
+| GCS bucket (uploads) | user file storage | Separate from the web bucket; not public |
+| Service account (runtime) | Cloud Run identity | `roles/secretmanager.secretAccessor`, `roles/storage.objectAdmin` on the uploads bucket only |
+| Service account (deploy) | CI identity | Prefer Workload Identity Federation over JSON keys |
+
+### Websocket and change-stream constraints to document
+
+These are the non-obvious failure modes and must be called out explicitly:
+
+- Socket.io on Cloud Run requires `--session-affinity` and a request timeout raised from the 300s default.
+- Change streams (realtime + feature-flag live updates) require a replica set. A standalone `mongod` silently fails at startup — the guide must say so.
+- Scaling to zero drops websocket connections; the client reconnects, but feature-flag live updates lag. Recommend `--min-instances=1` for anything user-facing.
+- `corsOrigin` in `setupServer` must include the CDN domain, and Better Auth needs the web origin in `trustedOrigins`.
+
+### `deploy-gcp` skill shape
+
+New skill at `.rulesync/skills/deploy-gcp/SKILL.md`, generated into all agent targets. Structure:
+
+1. **Preflight** — detect project layout (bootstrap `backend/`+`frontend/` vs monorepo), read `gcloud config`, verify required APIs enabled, verify `MONGO_URI` points at a replica set.
+2. **Plan** — print the exact resources to be created/updated and the target project, region, and service names. Require explicit user confirmation before mutating anything (GC6).
+3. **Backend** — build image, push to Artifact Registry, create/update secrets, deploy Cloud Run with session affinity and the correct env/secret wiring.
+4. **Frontend** — `expo export -p web`, sync to the web bucket, invalidate CDN cache.
+5. **Verify** — `curl <backend>/health` expecting `"healthy":true`, fetch the web root, confirm the SPA loads, print URLs.
+6. **Troubleshoot** — a table of symptom → cause → fix covering the four constraints above.
+
+## Models
+
+None.
+
+## APIs
+
+None new. The guide relies on the existing `/health` endpoint from `@terreno/api-health` for verification.
+
+## Notifications
+
+None.
+
+## UI
+
+None.
+
+## Phases
+
+1. **Generalize the how-to** — rewrite `docs/how-to/deploy-to-gcp.md` as a project-agnostic guide covering backend + frontend, with placeholder variables and the constraints section.
+2. **Terraform module** — extract a reusable `terraform/modules/terreno-backend/` module; relocate Flourish-specific config to `infra/flourish/`.
+3. **Scripts** — parameterize `scripts/setup-gcs-hosting.sh` to take project/bucket/site names as arguments instead of hardcoding Flourish's.
+4. **Skill** — author `deploy-gcp` in `.rulesync/skills/` and generate mirrors.
+5. **Validate** — deploy the example stack to a scratch GCP project using only the public guide, then fix what the guide got wrong.
+
+## Feature Flags & Migrations
+
+No product flags. Moving `terraform/` to `infra/flourish/` breaks paths referenced by `.github/workflows/cd.yml` and `terraform/README.md`; both must be updated in the same commit.
+
+## Not Included / Future Work
+
+- Multi-environment terraform workspaces beyond one documented staging example.
+- Cost estimation guidance.
+- Cloud Armor / WAF configuration.
+- Deploying the hosted MCP server (that is Flourish's own infra, documented in `infra/flourish/`).
+- SSR-capable web hosting — depends on [`web-ssr-and-admin-spa`](web-ssr-and-admin-spa.md).
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/how-to/deploy-backend-to-cloud-run.md`
+- `docs/how-to/deploy-web-to-gcs-cdn.md`
+- `docs/explanation/deployment-architecture-gcp.md`
+- `terraform/modules/terreno-backend/{main.tf,variables.tf,outputs.tf,README.md}`
+- `.rulesync/skills/deploy-gcp/SKILL.md`
+- `.rulesync/skills/deploy-gcp/references/troubleshooting.md`
+
+**Modify**
+
+- `docs/how-to/deploy-to-gcp.md` (becomes an index pointing at the two new guides, or is deleted with redirects)
+- `docs/how-to/README.md`
+- `scripts/setup-gcs-hosting.sh` (parameterize)
+- `terraform/README.md` (split generic vs Flourish)
+- `.github/workflows/cd.yml`, `.github/workflows/demo-deploy.yml`, `.github/workflows/frontend-example-deploy.yml` (path updates if terraform moves)
+- `example-backend/Dockerfile` (created by [`deployment-foundation`](deployment-foundation.md); referenced here)
+
+## Task List
+
+See [`docs/tasks/deploy-to-gcp.md`](../tasks/deploy-to-gcp.md).
+
+## Acceptance Criteria
+
+- [ ] `docs/how-to/deploy-backend-to-cloud-run.md` contains no `flourish` string and no hardcoded project ID, bucket name, or service URL.
+- [ ] The backend guide documents session affinity, request timeout, min-instances, and the replica-set requirement, each with the symptom that occurs when it is missed.
+- [ ] The web guide covers `expo export -p web`, bucket configuration with `notFoundPage=index.html`, CDN setup, cache invalidation, and setting `EXPO_PUBLIC_API_URL` at build time.
+- [ ] `terraform/modules/terreno-backend/` applies cleanly against a scratch project with only variables supplied, creating Cloud Run + Artifact Registry + secrets + service accounts.
+- [ ] `scripts/setup-gcs-hosting.sh` accepts project and site names as arguments and contains no Flourish defaults.
+- [ ] The `deploy-gcp` skill exists in `.rulesync/skills/` and all generated mirrors are committed (`bun run rules:check` exits 0).
+- [ ] The skill's plan step prints project, region, and service names and stops for confirmation before any mutating command.
+- [ ] A full deploy of `example-backend` + `example-frontend` to a scratch GCP project succeeds following only the public docs, and `curl <backend>/health` returns `"healthy":true`.
+- [ ] All Flourish-specific infrastructure lives under `infra/flourish/` and CI still passes.

package/dist/docs/versioned/0.28.0/implementationPlans/deploy-to-vercel.md

@@ -0,0 +1,167 @@
+# Implementation Plan: Deploy to Vercel + `deploy-vercel` Skill
+
+**Status:** Draft — open Vercel spike TODOs; other decisions recorded (2026-07-29)
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`deployment-foundation`](deployment-foundation.md)
+**RTK deprecation flag:** **Partial** — the web build and client configuration sections depend on the frontend data layer; the syncdb websocket transport also has implications for which parts of the app can be served from serverless functions. Marked tasks must be re-verified after PR #869.
+
+## Goal
+
+Give Terreno the fastest possible "my app is on the internet" path, and a skill that executes it. Vercel is where most JavaScript developers expect to deploy, and Expo Router has first-class Vercel support (`vercel.json` with `expo export -p web`, plus `expo-server/adapter/vercel` for server output). Terreno currently has zero Vercel documentation — the only occurrences of "Vercel" in the repo refer to the Vercel **AI SDK** inside `@terreno/ai`, which is a completely different thing and is itself a source of confusion worth addressing.
+
+**Topology is not finalized.** A pre-implementation spike must answer whether a single-platform Vercel deploy (web + `@terreno/api` + file storage) is viable, or whether the documented path remains split (static web on Vercel, long-lived backend elsewhere). Until the spike completes, this IP documents the **interim split topology** and tracks open questions as TODOs.
+
+## Non-Goals
+
+- Committing to a Vercel backend topology before the spike (see **Open TODOs** below).
+- Vercel-hosted MongoDB (does not exist; Atlas is the answer).
+- Native app distribution (that is EAS; see the `expo-deployment` skill).
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted where not marked open).
+
+| # | Question | Decision |
+|---|----------|----------|
+| V1 | Backend host | **Open — spike required.** Candidate: all-in-one on Vercel (web + backend + Blob storage). Fallback: Railway/Render/Fly + Vercel static web (see [`deployment-foundation`](deployment-foundation.md)). **Do not publish a final answer until TODOs below are closed.** |
+| V2 | Document `server` output? | **Open — depends on V1 spike.** Default if documented: advanced section, Expo SDK ≥ 55, SSE buffering caveat |
+| V3 | Commit `vercel.json`? | **Open — depends on V1 spike.** Candidate: wired to real deployment in `example-frontend` and `example-backend` |
+| V4 | Preview deployments | **A** — include CORS + Better Auth `trustedOrigins` for preview URLs |
+| V5 | Disambiguate Vercel AI SDK vs hosting | **A** — consistent phrasing: "the Vercel AI SDK" vs "Vercel (hosting)" |
+
+## Open TODOs (pre-implementation spike)
+
+Complete these before Phase 1 of the how-to guide ships:
+
+- [ ] **V1-todo:** Can `@terreno/api` run on Vercel with Socket.io sessions and MongoDB change streams? Document runtime limits, cold starts, and whether session affinity is available.
+- [ ] **V1-todo:** Can `@terreno/ai` SSE streaming work through `expo-server/adapter/vercel` without unacceptable buffering?
+- [ ] **V1-todo:** Where do user file uploads land on an all-in-one Vercel deploy (Blob, external GCS, or other)?
+- [ ] **V1-todo:** Compare all-in-one Vercel vs split (Vercel web + long-running backend) on cost, ops complexity, and preview-deployment ergonomics.
+- [ ] **V2-todo:** If `server` output is documented, confirm Expo SDK ≥ 55+ requirements and list which Terreno features break under static/server export.
+- [ ] **V3-todo:** If committing `vercel.json`, confirm CI/deploy wiring for `example-frontend` and `example-backend` and who owns the Vercel project.
+
+## Architecture
+
+### Interim topology (document until spike closes)
+
+Until V1 is decided, document this split layout — it is known to work:
+
+```mermaid
+flowchart LR
+  U["Users<br/>web + native"]
+  V["Vercel<br/>Expo web export<br/>(single output)"]
+  B["Long-running host<br/>@terreno/api + Socket.io"]
+  A["MongoDB Atlas<br/>replica set"]
+  S["Object storage<br/>uploads"]
+  U -->|"web"| V
+  U -->|"native"| B
+  V -->|"XHR + websocket"| B
+  B --> A
+  B --> S
+```
+
+The web deployment is static; dynamic operations go to the backend. Vercel needs SPA rewrites and build-time `EXPO_PUBLIC_API_URL`.
+
+### Candidate topology (if spike succeeds)
+
+```mermaid
+flowchart LR
+  U["Users<br/>web + native"]
+  VC["Vercel<br/>web + @terreno/api + storage"]
+  A["MongoDB Atlas<br/>replica set"]
+  U --> VC
+  VC --> A
+```
+
+**Do not document this as the recommended path until all V1 TODOs are checked.**
+
+### `vercel.json` for `single` output
+
+Per Expo's published configuration, the SPA case needs rewrites so client-side routes resolve:
+
+```json
+{
+  "buildCommand": "expo export -p web",
+  "outputDirectory": "dist",
+  "devCommand": "expo",
+  "cleanUrls": true,
+  "framework": null,
+  "rewrites": [{ "source": "/:path*", "destination": "/" }]
+}
+```
+
+### `vercel.json` for `server` output (advanced)
+
+Server output changes the shape: `dist/client` is served statically and a function handles everything else via `expo-server/adapter/vercel`, with `includeFiles` pulling in `dist/server/**`. Document only after V2 TODOs close. Flag the streaming caveat for `@terreno/ai` chat.
+
+### The preview-deployment problem
+
+Vercel gives every PR a unique origin. That breaks two things:
+
+1. **CORS** — `corsOrigin` in `setupServer` must accept the preview origin. Document a pattern (a function or regex matching `https://<project>-*.vercel.app`) rather than `corsOrigin: true`, and say plainly that `true` is not acceptable in production.
+2. **Better Auth `trustedOrigins`** — same problem, separate config, and OAuth redirect URIs must be registered per provider.
+
+This section ships regardless of V1 outcome.
+
+### `deploy-vercel` skill
+
+New skill at `.rulesync/skills/deploy-vercel/SKILL.md`:
+
+1. **Detect** — is this an Expo Router web app; what is `web.output` in the app config; is there an existing `vercel.json`.
+2. **Configure** — write or update `vercel.json` for the detected output mode; add the `vercel-build` script when using server output.
+3. **Wire the backend** — determine the backend URL (per finalized V1 decision), set `EXPO_PUBLIC_API_URL` as a Vercel environment variable per environment (production/preview/development), and print the CORS and `trustedOrigins` changes the user must make on the backend.
+4. **Deploy** — `vercel` / `vercel --prod`, with a confirmation gate before the first production deploy.
+5. **Verify** — load the deployed URL, confirm the app boots, confirm an authenticated request reaches the backend, and confirm the websocket connects.
+6. **Troubleshoot** — blank page (missing rewrites), 404 on refresh (same), API calls to localhost (`EXPO_PUBLIC_API_URL` not set at build time), CORS failure, websocket failure, buffered SSE on server output.
+
+The verification step must include the websocket check. A Terreno web app can look completely fine while realtime and live feature flags are silently broken.
+
+## Models / APIs / Notifications / UI
+
+None.
+
+## Phases
+
+0. **Spike** — close all **Open TODOs** above; record decision on V1/V2/V3 in this file.
+1. **How-to guide** — `single` output, clone → public URL (topology per V1 outcome).
+2. **Preview deployments and origins** — CORS, `trustedOrigins`, OAuth redirects.
+3. **Advanced: server output** — only if V2 is approved.
+4. **Skill** — author and generate mirrors.
+5. **Validate** — deploy examples per V3 outcome.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- EAS native distribution (separate skill).
+- Multi-region Vercel edge configuration.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/how-to/deploy-to-vercel.md` (blocked on Phase 0 spike)
+- `.rulesync/skills/deploy-vercel/SKILL.md`
+
+**Modify (after V3 decision)**
+
+- `example-frontend/vercel.json` (candidate)
+- `example-backend/vercel.json` (candidate — only if all-in-one path wins)
+
+## Task List
+
+See [`docs/tasks/deploy-to-vercel.md`](../tasks/deploy-to-vercel.md).
+
+## Acceptance Criteria
+
+- [ ] All **Open TODOs** are closed with a written decision on V1, V2, and V3.
+- [ ] `docs/how-to/deploy-to-vercel.md` matches the decided topology (not the interim split doc if all-in-one wins, and vice versa).
+- [ ] Preview-deployment CORS and `trustedOrigins` guidance is present.
+- [ ] `deploy-vercel` skill includes websocket verification in its checklist.
+- [ ] Vercel AI SDK vs Vercel hosting disambiguation appears in both `@terreno/ai` and deployment docs.

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

@@ -0,0 +1,132 @@
+# Implementation Plan: Deployment Foundation
+
+**Status:** Draft — blocking questions open
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** none (soft: [`docs-reference-coverage`](docs-reference-coverage.md) for the env var reference page)
+**RTK deprecation flag:** **Partial** — the client environment-variable section and the web build output depend on the frontend data layer. Tasks touching client env vars and Better Auth origins are `[RTK]` marked.
+
+## Goal
+
+Establish the provider-agnostic layer that every deployment guide needs, so [`deploy-to-vercel`](deploy-to-vercel.md) and [`deploy-to-gcp`](deploy-to-gcp.md) can be short and specific instead of each re-explaining the same eight concepts. Right now there is no canonical answer to "what does a Terreno app need in order to run in production?" — the environment variables are spread across `docs/reference/environment-variables.md`, `AGENTS.md`, package rules, and several `.env.example` files; there is no backend Dockerfile in the repo for consumers to copy; and nothing explains the choice between Expo's three web output modes.
+
+## Non-Goals
+
+- Provider-specific instructions (separate IPs per provider).
+- Implementing SSR (that is [`web-ssr-and-admin-spa`](web-ssr-and-admin-spa.md); this IP only documents that `single` is today's default and what the alternatives mean).
+- CI/CD pipeline templates for consumers.
+- Monitoring, alerting, or log aggregation setup.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| DF1 | Reference backend `Dockerfile`? | **A** — canonical `example-backend/Dockerfile`; docs reference it |
+| DF2 | Base image | **A** — `oven/bun:1-slim` |
+| DF3 | Default web output mode | **A** — `single` (SPA) today + decision table for `static` / `server` |
+| DF4 | Health endpoint required? | **A** — require `@terreno/api-health` |
+| DF5 | Staging environment | **B** — short two-environment section |
+| DF6 | File uploads default | **C** — document GCS; verify backends before writing |
+
+## Architecture
+
+### The deployment baseline
+
+Every Terreno production deployment needs these seven things. The foundation doc names them once; provider guides map them to provider primitives.
+
+| # | Requirement | Why | Where it is configured |
+|---|-------------|-----|------------------------|
+| 1 | MongoDB **replica set** | Change streams power realtime and live feature flags; a standalone server fails at startup | `MONGO_URI` |
+| 2 | Auth secrets | JWT signing and sessions | `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`; Better Auth adds `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` |
+| 3 | A long-lived process for the backend | Socket.io connections; not compatible with short-timeout serverless | Provider service config |
+| 4 | Correct origins | CORS (`corsOrigin`) plus Better Auth `trustedOrigins` including native deep-link schemes | Backend config |
+| 5 | Build-time client config | `EXPO_PUBLIC_API_URL` is inlined into the web bundle at build time; it cannot be changed after the fact | Web build environment |
+| 6 | A health endpoint | Readiness and liveness probes | `@terreno/api-health` |
+| 7 | File storage | Uploads must not live on ephemeral container disk | GCS bucket + credentials |
+
+Requirements 1, 3, and 5 are the ones people get wrong. Each needs its failure symptom documented, not just the rule.
+
+### Web output modes
+
+Expo Router offers three, and the choice determines what hosting works:
+
+| Mode | Output | API routes | SSR | Hosting | Status in Terreno |
+|------|--------|-----------|-----|---------|-------------------|
+| `single` | one `index.html` SPA | no | no | any static host | **current default** |
+| `static` | per-route HTML | no | no | any static host | usable now; better SEO |
+| `server` | `dist/client` + `dist/server` | yes | yes (alpha, SDK ≥ 55) | needs a Node/Bun/edge runtime | not yet — see the SSR IP |
+
+The repo is currently on Expo `~54.0.29` (root `package.json` catalog), so `server` output with SSR requires the SDK upgrade tracked in PR [#779](https://github.com/flourishhealth/terreno/pull/779). The foundation doc must state this rather than implying SSR is available.
+
+### Backend container
+
+A multi-stage Bun build that works for a monorepo consumer *and* for the repo's own `example-backend`:
+
+1. Stage 1: install with the lockfile, compile workspace packages.
+2. Stage 2: copy the built output, run as a non-root user, read `PORT` from the environment (platforms assign it), expose the health endpoint.
+
+The critical detail platforms trip on: the server must bind `0.0.0.0` and read `PORT` from the environment rather than hardcoding 4000. Verify how `example-backend` currently resolves its port before writing the Dockerfile.
+
+### Environment variable reference
+
+`docs/reference/environment-variables.md` exists but must become the single source of truth: every variable, which package reads it, required or optional, default, whether it is a secret, and whether it is build-time (client) or runtime (server). The build-time/runtime distinction is the one that causes production incidents, because `EXPO_PUBLIC_*` values are baked into the bundle.
+
+## Models / APIs / Notifications / UI
+
+None.
+
+## Phases
+
+1. **Environment variable reference** — audit every variable in every package and complete the reference table.
+2. **Deployment baseline explainer** — the seven requirements, the output-mode table, environment differences.
+3. **Backend container** — `example-backend/Dockerfile`, a `.dockerignore`, and a CI job that builds it.
+4. **Web build documentation** — how to build for web, build-time config, the output-mode decision.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- Consumer CI/CD templates.
+- Monitoring, tracing, and log aggregation guidance (Sentry is already wired; a production-observability guide is a good follow-up).
+- Blue/green or canary deployment patterns.
+- Database backup and restore procedures.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/explanation/deployment-baseline.md`
+- `docs/how-to/build-for-web.md`
+- `example-backend/Dockerfile`, `example-backend/.dockerignore`
+- `.github/workflows/example-backend-docker.yml`
+
+**Modify**
+
+- `docs/reference/environment-variables.md`
+- `docs/how-to/README.md`, `docs/explanation/README.md`
+- `example-backend/.env.example`, `example-frontend/.env.example`
+- `example-backend/src/server.ts` (only if it does not already read `PORT` and bind `0.0.0.0`)
+
+## Task List
+
+See [`docs/tasks/deployment-foundation.md`](../tasks/deployment-foundation.md).
+
+## Acceptance Criteria
+
+- [ ] `docs/reference/environment-variables.md` lists every environment variable read anywhere in the repo, with reading package, required/optional, default, secret flag, and build-time versus runtime.
+- [ ] A grep for `process.env.` and `EXPO_PUBLIC_` across all packages finds no variable absent from the reference.
+- [ ] `docs/explanation/deployment-baseline.md` documents all seven baseline requirements, each with the symptom that occurs when it is missed.
+- [ ] The web output-mode table states Terreno's current default and that `server` output requires Expo SDK ≥ 55.
+- [ ] `example-backend/Dockerfile` builds successfully and the container serves `/health` returning `"healthy":true` against an external MongoDB.
+- [ ] The container reads `PORT` from the environment and binds `0.0.0.0`, verified by running it with `PORT=9999`.
+- [ ] The container runs as a non-root user.
+- [ ] A CI job builds the Docker image on changes to `example-backend/` or `api/`.
+- [ ] `docs/how-to/build-for-web.md` explains that `EXPO_PUBLIC_API_URL` is inlined at build time and shows the symptom when it is set only at runtime.
+- [ ] Both `.env.example` files contain every required variable with safe placeholder values and no real secrets.

package/dist/docs/versioned/0.28.0/implementationPlans/docs-reference-coverage.md

@@ -0,0 +1,141 @@
+# Implementation Plan: Reference Documentation Coverage
+
+**Status:** Draft — blocked on PR #869
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md), [`positioning-django-rails-universal`](positioning-django-rails-universal.md) (supplies the shared package-README intro block)
+**RTK deprecation flag:** **Blocked** — `syncdb.md` cannot be written before #869, and the package README rewrites reference the frontend data layer.
+
+## Goal
+
+Give every published package a public reference page and a real README. Today four package READMEs are one-line stubs pointing at `.claude/rules/...` — paths that do not exist in a published npm tarball and that leak an internal agent-tooling layout to consumers. Meanwhile the substantive documentation for those packages *does* exist, in `.cursor/rules/*/00-*.mdc` files, and is genuinely good; it is just published to the wrong audience.
+
+| Package | README | `docs/reference/` page |
+|---------|--------|------------------------|
+| `api` | good (~290 lines) | `api.md` |
+| `ui` | good (~187 lines) | `ui.md` |
+| `rtk` | good (~103 lines) | `rtk.md` → legacy |
+| `mcp-server` | good (~267 lines) | `mcp-server.md` |
+| `admin-spa` | good (~126 lines) | **missing** |
+| `ai` | **stub → `.claude/`** | **missing** |
+| `admin-backend` | **stub → `.claude/`** | `admin-backend.md` |
+| `admin-frontend` | **stub → `.claude/`** | `admin-frontend.md` |
+| `api-health` | **stub ("see source")** | `api-health.md` |
+| `feature-flags` | **missing** | `feature-flags.md` |
+| `test` | **missing** | **missing** |
+| `syncdb` | (from #869) | **missing** |
+
+## Non-Goals
+
+- Writing tutorials or how-to guides (that is [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md)).
+- Auto-generating API reference from TypeScript types — the existing `docs-audit` skill and TypeDoc-driven component pages already partially cover `@terreno/ui`; expanding that is future work.
+- Changing any package's public API.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Decision |
+|---|----------|
+| RF1 | **`docs/reference/<pkg>.md` canonical**; README is short intro + link |
+| RF2 | Keep **`.cursor/rules/*/00-*.mdc`** agent-optimized; add drift check |
+| RF3 | **`@terreno/test` gets public docs** |
+| RF4 | README links **`.ai/guidelines/core.md`** when Boost Phase 2 ships |
+| RF5 | Keep `docs/implementationPlans/` + `docs/tasks/` in repo; **README on `docs/tasks/`** explaining planning artifacts |
+
+## Architecture
+
+### Standard package README template
+
+Every published package's README follows the same six-section shape:
+
+1. Title + one-line description (from the positioning IP's standard pattern)
+2. `Install` — the exact install command including peer dependencies
+3. `Quick start` — the shortest complete working example, runnable
+4. `What's included` — bullets, 5–8 items
+5. `Documentation` — link to `docs/reference/<pkg>.md` on the docs site (absolute URL, since npm renders it outside the repo)
+6. `License` + `Contributing` links (absolute URLs)
+
+Rule: **no relative links to repository-internal paths.** A README rendered on npmjs.com must not link `../.claude/rules/...` or `../docs/`.
+
+### Standard reference page shape
+
+Follow the existing `docs/reference/api.md` and `docs/reference/rtk.md` structure, which is already good: Commands → Architecture/file structure → Key exports → Usage per feature area → Options tables → Conventions → Testing. New pages must match it so the reference tree reads as one document.
+
+### Content sources
+
+Do not write from scratch. The content exists:
+
+| Target | Source |
+|--------|--------|
+| `docs/reference/ai.md` | `.cursor/rules/ai/00-ai.mdc` (comprehensive: AIService, methods table, temperature presets, models, routes, integration, testing) |
+| `docs/reference/admin-spa.md` | `admin-spa/README.md` + `admin-spa/src/` |
+| `docs/reference/syncdb.md` | written by [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) — do not duplicate |
+| `docs/reference/test.md` | `test/src/` + the preload/bunfig patterns in `admin-backend/AGENTS.md` |
+| `ai/README.md` | new, from `docs/reference/ai.md` |
+| `admin-backend/README.md` | `.cursor/rules/admin-backend/00-admin-backend.mdc` + existing `docs/reference/admin-backend.md` |
+| `admin-frontend/README.md` | `.cursor/rules/admin-frontend/00-admin-frontend.mdc` + existing `docs/reference/admin-frontend.md` |
+| `feature-flags/README.md` | `docs/reference/feature-flags.md` |
+| `api-health/README.md` | `api-health/src/` |
+
+### Sanitization pass
+
+Every public page must be checked for internal leakage: `flourish` strings, GCP project IDs, Cloud Run URLs, Slack references, `.claude/` or `.cursor/` paths, and internal Linear ticket IDs (`PRO-`, `FH-`).
+
+## Models / APIs / Notifications / UI
+
+None.
+
+## Phases
+
+1. **Missing reference pages** — `ai.md`, `admin-spa.md`, `test.md`; fix the reference index.
+2. **De-stub package READMEs** — `ai`, `admin-backend`, `admin-frontend`, `api-health`, plus new READMEs for `feature-flags`, `test`, `demo`, `website`.
+3. **Sanitization** — sweep every public doc for internal leakage.
+4. **Drift protection** — extend the `docs-audit` skill and workflow to catch a published package without a README or reference page, and to flag reference/rule divergence.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- TypeDoc-generated API reference for `api`, `rtk`/`syncdb`, and `ai`.
+- Translating docs.
+- A searchable reference index beyond what Docusaurus provides.
+- Consolidating agent rules and reference docs into one generated source (see RF2).
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/reference/ai.md`, `docs/reference/admin-spa.md`, `docs/reference/test.md`
+- `feature-flags/README.md`, `test/README.md`, `demo/README.md`, `website/README.md`
+- `docs/tasks/README.md`
+
+**Modify**
+
+- `ai/README.md`, `admin-backend/README.md`, `admin-frontend/README.md`, `api-health/README.md`
+- `api/README.md`, `ui/README.md`, `mcp-server/README.md`, `admin-spa/README.md` (apply the standard template; convert relative links to absolute)
+- `docs/reference/README.md`, `docs/README.md`
+- `docs/reference/mcp-server.md` (tool list is behind the live server — reconcile)
+- `.rulesync/skills/docs-audit/SKILL.md`, `.github/workflows/docs-audit.yml`
+
+## Task List
+
+See [`docs/tasks/docs-reference-coverage.md`](../tasks/docs-reference-coverage.md).
+
+## Acceptance Criteria
+
+- [ ] Every package published by `publish-on-tag.yml` has both a README following the standard template and a `docs/reference/<pkg>.md` page.
+- [ ] No published package README links to a path outside its own package directory using a relative link.
+- [ ] `rg -n "\.claude/|\.cursor/" -- */README.md` returns nothing.
+- [ ] `rg -ni "flourish|a\.run\.app|PRO-[0-9]|FH-[0-9]" docs/reference/ docs/how-to/ docs/tutorials/ docs/explanation/ */README.md` returns nothing (excluding `infra/flourish/`).
+- [ ] `docs/reference/ai.md` documents every public export of `@terreno/ai`, including all `AIService` methods, temperature presets, both models, and all three route registrars.
+- [ ] `docs/reference/mcp-server.md` and `mcp-server/README.md` list the same tools as the live hosted server.
+- [ ] `docs/reference/README.md` lists every reference page, and every listed page exists.
+- [ ] `docs/tasks/README.md` states that the directory holds agent task lists, not user documentation.
+- [ ] The `docs-audit` workflow fails when a published package is missing a README or reference page.
+- [ ] `bun run website:build` produces no new broken-link warnings.