@terreno/mcp 57.18.0 → 57.19.2

package/src/docs/versioned/57.18.0/tasks/deploy-to-gcp.md

@@ -0,0 +1,100 @@
+# 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
+
+- [x] **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`.
+
+- [x] **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.
+
+- [x] **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.
+
+- [x] **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.
+
+- [x] **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
+
+- [x] **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`.
+  - Implementation note: secrets start empty, and Cloud Run rejects a revision that references a versionless secret, so the module does not mount secret env refs at creation. The `set_secrets_flag` output supplies the `--set-secrets` flag for the first real `gcloud run deploy`, consistent with the existing "Terraform owns structure, deploy owns payload" split (`lifecycle.ignore_changes` on env).
+
+- [x] **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.
+
+- [x] **Task 2.3**: Parameterize the GCS hosting script
+  - Description: Rewrite `scripts/setup-gcs-hosting.sh` to require `--project`, `--site-name`, `--bucket`, and `--domain` 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, with HTTPS as the only public serving path. 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 HTTPS commands containing the supplied values, no port 80 forwarding rule, and no Flourish strings; `rg -i flourish scripts/setup-gcs-hosting.sh` returns nothing.
+
+## Phase 3: The `deploy-gcp` skill
+
+- [x] **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).
+
+- [x] **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.
+
+- [x] **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/src/docs/versioned/57.18.0/tasks/deploy-to-vercel.md

@@ -0,0 +1,116 @@
+# 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.
+
+- [x] **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). Treat [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the vendor contract. Record Fluid compute, max-duration disconnects, instance pinning (not affinity across reconnects), Redis for cross-instance fan-out, Function billing while sockets are open, cold starts, and SSE buffering. Compare against split topology (Vercel web + long-running backend).
+  - Files: spike notes in PR / IP update; optional scratch `example-backend/vercel.json`
+  - Depends on: none
+  - Acceptance: IP questions **V1**, **V2**, and **V3** updated with a recorded decision; all IP Open TODO checkboxes checked or explicitly deferred with owner.
+
+- [x] **Task 0.2**: Write Vercel Functions WebSocket operator docs
+  - Description: Create `docs/how-to/vercel-function-websockets.md` from the IP section **Vercel Functions WebSockets (Public Beta)**. Cite `https://vercel.com/docs/functions/websockets`; do not copy Vercel examples. Cover Fluid compute, HTTP Upgrade + Firewall/rate limits, websocket-only Socket.IO, `export default` HTTP server vs `TerrenoApp.start()`, instance pinning, max-duration reconnects, Redis (`RealtimeApp` adapter), Function billing while connected, and verification (`WEBSOCKETS_DEBUG`, DevTools WS, no polling fallback). Mark **beta**. Do not recommend all-in-one topology until V1 is decided. Link from `docs/how-to/README.md` and later from `docs/how-to/deploy-web-to-vercel.md` and `docs/how-to/websocket-integration.md`.
+  - Files: `docs/how-to/vercel-function-websockets.md` (new), `docs/how-to/README.md`, `docs/how-to/websocket-integration.md`
+  - Depends on: none (may ship before Task 0.1 closes; must re-verify against the Vercel page at ship time)
+  - Acceptance: every required operator section from the IP is present; the Vercel URL is cited; Next.js `experimental_upgradeWebSocket`, Bun, and Python examples are out of scope; `corsOrigin: true` is not recommended; listed in the how-to index.
+
+## Phase 1: Core how-to guide
+
+- [x] **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. Link `docs/how-to/vercel-function-websockets.md` wherever sockets on Functions are mentioned.
+  - Files: `docs/how-to/deploy-web-to-vercel.md` (new), `docs/how-to/README.md`
+  - Depends on: `deployment-foundation` Phase 4, Task 0.2
+  - Acceptance: every config key verified against current Expo docs; the "what goes where" reasoning is present in the first section; the guide links rather than duplicates the baseline explainer; listed in the how-to index; websocket Functions page is linked, not duplicated.
+
+- [x] **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.
+
+- [x] **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
+
+- [x] **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.
+
+- [x] **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
+
+- [x] **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.
+
+- [x] **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.
+
+- [x] **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
+
+- [x] **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.
+
+- [x] **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 (Fluid off, long-polling fallback, or max-duration close — link `docs/how-to/vercel-function-websockets.md`); and SSE responses arriving all at once on server output (the buffering caveat). For each, give the fix and the file or setting to change.
+  - Files: `.rulesync/skills/deploy-vercel/references/troubleshooting.md` (new)
+  - Depends on: Task 4.1
+  - Acceptance: at least six entries; each quotes a real error string or describes a precisely observable symptom; each names the file or setting to change.
+
+- [x] **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
+
+- [x] **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.18.0/tasks/describe-model-schema.md

@@ -0,0 +1,37 @@
+# Tasks: `describeModel()` schema metadata
+
+IP: [describe-model-schema.md](../implementationPlans/describe-model-schema.md)
+
+## Phase 1 — Descriptor + MCP
+
+- [x] **Task 1.1**: `describeModel` / `describeModelForRouter`
+  - Delivers: field graph + snapshot tests on a fixture schema
+  - Files: `api/src/schemaMetadata.ts`, `api/src/schemaMetadata.test.ts`
+  - Blocked by: none
+  - Acceptance: snapshots for enum, ref, array, subdocument, system fields
+- [x] **Task 1.2**: MCP Zod from descriptor
+  - Delivers: `schemaGenerator.ts` maps `FieldDescription`; no SchemaType switch for kinds already in the descriptor
+  - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: MCP schema tests pass; create tools still omit system fields
+
+## Phase 2 — Admin
+
+- [x] **Task 2.1**: `extractFieldMeta` from descriptor
+  - Delivers: admin config fields built from `describeModel`, not OpenAPI property walk
+  - Files: `admin-backend/src/adminApp.ts`, admin-backend tests
+  - Blocked by: 1.1
+  - Acceptance: ref, enum, required, nested array items still appear on `/admin/config`
+
+## Phase 3 — OpenAPI + docs
+
+- [x] **Task 3.1**: `getOpenApiSpecForModel` from descriptor
+  - Delivers: OpenAPI properties derived from `ModelDescription`; populate still applied
+  - Files: `api/src/populate.ts`, `api/src/openApi.test.ts` / example-backend openapi snapshot if required
+  - Blocked by: 1.1
+  - Acceptance: OpenAPI tests pass; any snapshot diff is reviewed in the PR
+- [x] **Task 3.2**: Docs + export
+  - Files: `docs/explanation/schema-metadata.md`, `docs/reference/api.md`, `docs/how-to/create-a-model.md`, admin reference, `api/src/index.ts`, changelog
+  - Blocked by: 1.2, 2.1, 3.1
+  - Skills: `update-docs`
+  - Acceptance: stranger finds “one descriptor, three views” without reading code

package/src/docs/versioned/57.18.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/TerrenoLabs/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.
+
+- [x] **Task 1.4**: `[RTK]` Fix the reference index
+  - Description: Update `docs/reference/README.md` to list every reference page that exists, including `ai.md`, `admin-spa.md`, `test.md`, `api-health.md`, `feature-flags.md`, `environment-variables.md`, and `syncdb.md`, with `rtk.md` under a Legacy heading. Cross-check against `ls docs/reference/` so nothing is orphaned and nothing listed is missing.
+  - Files: `docs/reference/README.md`
+  - Depends on: Task 1.1, Task 1.2, Task 1.3
+  - 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.
+
+- [x] **Task 2.2**: Add the missing READMEs
+  - Description: Create `feature-flags/README.md` (source: `docs/reference/feature-flags.md`; cover `FeatureFlagsApp` registration, the `/flagConfiguration` endpoint, `liveUpdates` and its replica-set requirement, and the deprecated `/evaluate` endpoint), `test/README.md` (source: the new `docs/reference/test.md`), `demo/README.md` (how to run the component demo on port 8085, how stories are organized under `stories/`, how to add a story and register it in `demoConfig.tsx`, and the demo-vs-dev mode split), and `website/README.md` (how to run the docs site locally, where content comes from — `../docs` — how versioning works, and how deploys happen via Netlify).
+  - Files: `feature-flags/README.md`, `test/README.md`, `demo/README.md`, `website/README.md` (all new)
+  - Depends on: Task 1.3
+  - Acceptance: every command shown exists in the corresponding `package.json` scripts or the root `package.json`; `demo/README.md` correctly names port 8085; `website/README.md` correctly states that docs content lives in `../docs`.
+
+- [x] **Task 2.3**: Normalize the four good READMEs
+  - Description: Apply the template's link discipline (not a rewrite) to `api/README.md`, `ui/README.md`, `mcp-server/README.md`, and `admin-spa/README.md`: convert relative repo links to absolute URLs, add the Documentation / License / Contributing sections if missing, and ensure the description line matches the standardized `package.json` description. Additionally, reconcile `mcp-server/README.md`'s tool list with `docs/reference/mcp-server.md` and the live hosted server — the README is known to omit `terreno_search_docs`, `terreno_get_component_docs`, and `terreno_get_upgrade_guide`.
+  - Files: `api/README.md`, `ui/README.md`, `mcp-server/README.md`, `admin-spa/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: no relative link escapes the package directory in any of the four; `mcp-server/README.md` and `docs/reference/mcp-server.md` list identical tool sets; each README's opening line matches its `package.json` description.
+
+- [x] **Task 2.4**: Add `docs/tasks/README.md`
+  - Description: Create a short README in `docs/tasks/` explaining that files there are structured task breakdowns for automated implementation of the IPs in `docs/implementationPlans/`, that they are internal planning artifacts rather than user documentation, and that they are excluded from the docs site. Do the same check for `docs/implementationPlans/README.md` — it exists; verify it says something similar and update if not.
+  - Files: `docs/tasks/README.md` (new), `docs/implementationPlans/README.md`
+  - Depends on: none
+  - 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
+
+- [x] **Task 3.1**: Sweep public docs for internal leakage
+  - Description: Run `rg -ni "flourish|a\.run\.app|netlify\.app|PRO-[0-9]|FH-[0-9]|slack|\.claude/|\.cursor/" docs/ */README.md README.md` excluding `infra/flourish/` and `docs/implementationPlans/`. For each hit decide: remove, replace with a placeholder, or relocate to `infra/flourish/`. Live example URLs (the Netlify frontend, the Cloud Run backend) may stay in a clearly-labeled "Live examples" list but must not appear in instructional steps as if the reader owns them. Record the total number of fixes in the PR body.
+  - Files: various under `docs/` and package READMEs
+  - Depends on: Task 2.3
+  - Acceptance: the grep returns only permitted hits (live-example URLs in labeled lists, and `docs/implementationPlans/` planning content); the PR body reports the count and lists each judgment call.
+
+- [x] **Task 3.2**: Fix the how-to index and stale "Coming Soon" entries
+  - Description: `docs/how-to/README.md` lists feature flags under "Coming Soon" even though `docs/how-to/add-feature-flags.md` exists. Audit the whole index against `ls docs/how-to/*.md`, remove stale "Coming Soon" markers for anything that shipped, and add entries for guides that exist but are unlisted. Do the same audit for `docs/explanation/` and `docs/tutorials/` indexes if they exist.
+  - Files: `docs/how-to/README.md`, `docs/explanation/README.md` and `docs/tutorials/README.md` if present
+  - Depends on: none
+  - 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
+
+- [x] **Task 4.1**: Extend the docs-audit check
+  - Description: Update `.rulesync/skills/docs-audit/SKILL.md` and the script it drives (find it via `.github/workflows/docs-audit.yml`) to add two checks: (1) every package published by `publish-on-tag.yml` has a non-stub `README.md` (heuristic: at least 30 lines and containing an `## Install` heading) and a `docs/reference/<pkg>.md` page; (2) no file under `docs/` or any published package README matches the internal-leakage pattern from Task 3.1. Make both failures fatal in CI. Regenerate skill mirrors with `bun run rules`.
+  - Files: `.rulesync/skills/docs-audit/SKILL.md`, the docs-audit script, `.github/workflows/docs-audit.yml`, generated mirrors
+  - Depends on: Task 3.1
+  - Acceptance: deleting `feature-flags/README.md` makes the audit fail with a message naming the package; adding the string `flourish-terreno` to a docs page makes it fail; `bun run rules:check` exits 0.
+
+- [x] **Task 4.2**: Document the reference/rule duplication policy
+  - Description: Add a short section to `docs/explanation/ai-workflows.md` (or `CONTRIBUTING.md` if that reads better) explaining the deliberate split from IP question RF2: `docs/reference/` is descriptive documentation for humans, `.rulesync/rules/` is prescriptive guidance for agents, both are maintained, and a change to a package's public API requires updating both. Note that the docs-audit workflow flags drift but cannot fully verify it.
+  - Files: `docs/explanation/ai-workflows.md` or `CONTRIBUTING.md`
+  - Depends on: Task 4.1
+  - 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.18.0/tasks/docs-site-and-versioning.md

@@ -0,0 +1,42 @@
+# Task List: Documentation Site, Versioned Docs, and Docs-Maintenance Skills
+
+See: [`docs/implementationPlans/docs-site-and-versioning.md`](../implementationPlans/docs-site-and-versioning.md)
+
+Phases 1–2 and most of 3–4 already shipped on `master` (`website/`, generated
+reference, `docs:version` job, `update-docs` / `docs-audit`, weekly audit CI).
+This file tracks the remaining frontier.
+
+## Instructions for the implementing agent
+
+- Public MCP tool schemas live in `mcp-server/src/tools.ts`. Search behavior
+  lives in `mcp-server/src/search/docIndex.ts`.
+- Run `cd mcp-server && bun test src/__tests__/search.test.ts src/search/docVersion.test.ts`.
+- Update `docs/reference/mcp-server.md` in the same slice as the tool schema.
+
+## Phase 3: Versioning (remaining)
+
+- [x] **Task 3.1**: MCP `version` parameter on doc search tools
+  - Delivers: `terreno_search_docs` and `terreno_get_component_docs` accept
+    optional `version`. Unmatched versions fall back to the nearest retained
+    snapshot with a note. Omitted `version` searches `next` (current `docs/`).
+    Historical searches do not mix other versions. Versioned `.mdx` files are
+    indexed.
+  - Files: `mcp-server/src/search/docIndex.ts`, `mcp-server/src/search/docVersion.ts`,
+    `mcp-server/src/tools.ts`, `docs/reference/mcp-server.md`
+  - Blocked by: none
+  - Acceptance: `searchDocs({queries: ["token"], version: "0.19.0"})` returns
+    only that snapshot; a patch like `0.19.1` falls back to `0.19.0` with a
+    note; omitted version does not return `versioned/0.19.0` chunks;
+    `getComponentDocsMarkdown` accepts the same `version` and reads the
+    snapshot MDX when present.
+
+## Phase 4: Skills (remaining)
+
+- [x] **Task 4.1**: `improve-rulesync` docs-vs-agent split
+  - Delivers: `improve-rulesync` states that user-facing guidance belongs in
+    `docs/` (the site) and agent-facing guidance belongs in `.ai/` / rules,
+    with cross-links rather than duplication.
+  - Files: `.rulesync/skills/improve-rulesync/SKILL.md` (then `bun run skills:sync`)
+  - Blocked by: Task 3.1
+  - Acceptance: the skill names both homes and forbids copying the same
+    architecture into both without a cross-link.

package/src/docs/versioned/57.18.0/tasks/durable-agent-harness.md

@@ -0,0 +1,185 @@
+# Tasks: Durable agent harness
+
+IP: [durable-agent-harness.md](../implementationPlans/durable-agent-harness.md)  
+**Feature profile:** false (full IP)  
+**Base branch:** `cursor/ai-observability-ip-64ca` (rebase as it lands)  
+**First PR scope:** Phases 1–2. Phases 3–5 ship in follow-up PRs.
+
+## Resume here (paused 2026-10-03)
+
+The Pick ⇄ Roast loop is paused after Phase 1. Tasks 1.1–1.12 are Roast-verified, one commit each.
+
+1. **Sync the base.** `git fetch origin && git merge origin/cursor/ai-observability-ip-64ca`.
+   At pause it was 5+ commits ahead, including a master merge and "Preserve AI observability
+   across chat turn refactor", which touches `ai/`. Re-run `cd ai && bun run test:ci` after the merge.
+2. **Resume the loop** with `/terreno:pick-roast-loop` (or `terreno-pick-roast-loop`) at
+   **Task 2.0**, then 2.1, then 2.2. Each task is Pick, then an independent Roast, then one commit.
+3. **Brew when Phase 2 is done.** Run the full independent branch review that was deferred at
+   pause, take the PR out of draft, then Taste.
+
+Known environment notes from Phase 1:
+
+- `/tmp` in the cloud VM is a 1 GB tmpfs, and in-memory replica sets use about 200 MB each. Run Mongo
+  test suites sequentially and delete leftover `/tmp/mongo-mem-*` directories after killed runs.
+- `example-backend` seed-heavy tests can hit Bun's 5 s default timeout under load. This also
+  happens on the base branch.
+- In the root `bun run lint`, `check:explicit-any:lint` requires a `// noExplicitAny: <reason>` line
+  above every `biome-ignore … noExplicitAny`.
+
+Every task: bun tests in `ai/` against the in-memory replica set from `@terreno/test`; real
+models are replaced by the mock model pattern in `.claude/rules/ai/00-ai.md`. Docs pages are
+created in 1.1 and extended by every later task — never deferred.
+
+## Phase 1 — Durable clinical tracer
+
+- [x] **Task 1.1**: Harness subpath + `defineTask` + transactional checkpoint/span (tracer)
+  - Delivers: `@terreno/ai/harness` export; `HarnessTask` model; `defineTask` with phases; `InProcessRunner` (no lease yet) runs a two-phase task to `completed`; `rt.commit` writes task + `ObsSpan` + root `ObsTrace` in one transaction; `Harness.open` throws without local observability plugin or without a replica set
+  - Files: `ai/package.json`, `ai/src/harness/harness.ts`, `defineTask.ts`, `runtime.ts`, `commit.ts`, `runners/inProcessRunner.ts`, `models/harnessTask.ts`, `ai/src/types/harness.ts`, tests
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`
+  - Docs: create `docs/explanation/durable-agent-harness.md` (concepts table), `docs/reference/ai-harness.md` (`defineTask`, `Harness.open`, `rt.commit`), link from `docs/reference/ai.md`
+  - Acceptance: AC1 — bun test asserts one CHAIN span per phase; forced throw inside the transaction leaves neither task update nor span
+
+- [x] **Task 1.2**: Owner lease, crash resume, replay semantics
+  - Delivers: `HarnessOwner` lease + heartbeat; standby second process; task leases with fencing token; resume on `start()`; per-phase `replay`; `interrupted` status; `harness.resolveInterrupted(taskId, action)`
+  - Files: `runners/inProcessRunner.ts`, `models/harnessOwner.ts`, `runtime.ts`, `commit.ts`, tests
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: reference "Replay and interruption" table; explanation section on leases
+  - Acceptance: AC2 + AC3 (phase rows) — simulate death by abandoning a harness mid-phase with an expired lease; new harness resumes safe phase and parks `never` phase as `interrupted`; stale-token commit rejected
+
+- [x] **Task 1.3**: Retries, failure, abort + ownership tree
+  - Delivers: task `retry` policy with backoff+jitter (Luxon), `failed` after `maxAttempts`; `rt.createTask` child ownership; `harness.abort` bottom-up with `abort` handlers; `rt.waitForTasks` (`all` / `failFast`); `background` flag
+  - Files: `runtime.ts`, `retryBackoff.ts`, `ownership.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: reference retry/abort/ownership; explanation ownership tree
+  - Acceptance: AC4 (phase retries) + AC5 — ordering assertion on abort handlers; `failFast` aborts siblings
+
+- [x] **Task 1.4**: Agents, conversations, tools, model-call resilience
+  - Delivers: `defineAgent`, `defineTool` (zod params, `replay`), `HarnessConversation` + `HarnessMessage`; built-in `terreno.agent.turn` task (`request` ⇄ `tools` phases, `maxSteps`); tools run as child tasks; interrupted `never` tools reported to the model; model calls retry 429/5xx then `fallbackModels`; interrupted model requests re-requested; LLM/TOOL spans with usage/cost; `ExecutionEnv` interface (types only) on `rt.env`
+  - Files: `defineAgent.ts`, `defineTool.ts`, `agentLoop.ts`, `modelCall.ts`, `executionEnv.ts`, `models/harnessConversation.ts`, `models/harnessMessage.ts`, tests
+  - Blocked by: 1.3
+  - Skills: `terreno-backend-api`, `claude-api` (model ids), `ai-prompt-governance`
+  - Docs: reference agents/tools/model resilience; explanation agent loop
+  - Acceptance: AC3 (tool rows) + AC4 (model rows) — mock model returns 503 twice then succeeds; fallback used after exhaustion; span tree CHAIN→LLM→TOOL
+
+- [x] **Task 1.5**: Subagents
+  - Delivers: `rt.runAgent(agent, {input, output})` creates a task-owned child conversation, idempotent on resume (finds existing by `ownerTaskId`), returns parsed structured output; AGENT span nests the child's spans
+  - Files: `runtime.ts`, `agentLoop.ts`, tests
+  - Blocked by: 1.4
+  - Skills: `terreno-backend-api`
+  - Docs: reference `runAgent`; explanation subagents
+  - Acceptance: bun test — crash between child creation and completion resumes the same child conversation (no duplicate); abort of parent aborts child
+
+- [x] **Task 1.6**: Extensions, hooks, wraps, memos
+  - Delivers: `defineExtension({name, sections, tools, hooks, wraps})`; `section` rebuilt per request and recorded in transcript; hooks `beforeModelRequest` / `beforeTool` (rewrite or `{block}`) / `afterTool`; `wrapTool`; `rt.memo(key, value?)` via `HarnessMemo`
+  - Files: `extensions.ts`, `models/harnessMemo.ts`, `agentLoop.ts`, tests
+  - Blocked by: 1.4
+  - Skills: `terreno-backend-api`
+  - Docs: reference extensions/hooks/memos
+  - Acceptance: AC6 — blocked tool result reaches the model; memo value survives a new harness instance
+
+- [x] **Task 1.7**: Events, waits, sleep
+  - Delivers: `rt.waitFor(event, {timeout})`, `rt.sleep(duration)`, `harness.sendEvent(taskId, event, payload)`; `waiting` status; runner wakes on event or `timeoutAt`; timeout resolves `undefined`
+  - Files: `runtime.ts`, `runners/inProcessRunner.ts`, tests
+  - Blocked by: 1.3
+  - Skills: `terreno-backend-api`
+  - Docs: reference waits/events
+  - Acceptance: bun test with frozen Luxon clock — event before timeout resumes with payload; timeout path; event sent while owner is down is delivered after restart
+
+- [x] **Task 1.8**: Approvals backend
+  - Delivers: `HarnessApproval` model; `rt.approval(key, {title, summary, payload, timeout, notify?})` with approvers declared per key on `defineTask({approvals})`; `approvalGate({tools, approvers})` extension (memo-backed); `HarnessApp` routes `GET /harness/approvals` (filtered by `approvers`), `approve` / `reject` instanceActions with reason; decision span with `decidedBy`
+  - Files: `approvals.ts`, `models/harnessApproval.ts`, `harnessApp.ts`, `routes/approvals.ts`, tests
+  - Blocked by: 1.6, 1.7
+  - Skills: `terreno-backend-api`, `model-router-actions`
+  - Docs: reference approvals + routes; how-to section "Require human approval"
+  - Acceptance: AC7 — supertest: unpermitted user gets 403 and an empty list; permitted user approves; span `output.decidedBy` equals user id; reject without reason → 400
+
+- [x] **Task 1.9**: SSE event stream + submit
+  - Delivers: `HarnessEvent` log (coalesced deltas with TTL, committed events permanent); `rt.output`; `GET /harness/conversations/:id/events` + `/harness/tasks/:id/events` SSE with `Last-Event-ID` replay then change-stream tail; `submit` instanceAction (`requestId` idempotent, `whenBusy: queue | steer`)
+  - Files: `events.ts`, `models/harnessEvent.ts`, `routes/events.ts`, `routes/conversations.ts`, tests
+  - Blocked by: 1.4
+  - Skills: `terreno-backend-api`, `model-router-actions`
+  - Docs: reference SSE contract (event types, ids, reconnect)
+  - Acceptance: AC9 — two `HarnessApp` instances on one replica set; client disconnects mid-stream, reconnects to the other with `Last-Event-ID`, receives each missed event exactly once
+
+- [x] **Task 1.10**: Version pinning
+  - Delivers: runs resume only on exact `name@version`; `Harness.start()` throws listing unregistered in-flight versions
+  - Files: `harness.ts`, `registry.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: reference "Versioning"; how-to "Ship a new task version"
+  - Acceptance: AC10
+
+- [x] **Task 1.11**: Approvals inbox (admin-frontend)
+  - Delivers: `admin-frontend/src/widgets/harness/HarnessApprovalInbox.tsx` (list, detail, approve/reject with reason, loading/empty/error states) via `adminRequest`; admin custom screen `harness-approvals` (group "AI Harness"); standalone export; example-frontend admin route; `bun run sdk`
+  - Files: `admin-frontend/src/widgets/harness/*`, `ai/src/harness/adminScreens.ts`, `example-frontend/app/admin/*`, tests
+  - Blocked by: 1.8
+  - Skills: `building-admin-interfaces`, `verify-ui-changes`
+  - Docs: `docs/reference/admin-frontend.md` inbox section
+  - Acceptance: AC8 — component tests + Playwright run on web: approve one item, reject one; screenshots in `/opt/cursor/artifacts/`
+
+- [x] **Task 1.12**: Clinical tracer in example-backend + how-to
+  - Delivers: `clinic.intakeSummary` (fetch → `runAgent` summary → approval → EHR write with `replay: "never"`) against a fake EHR model; `HarnessApp` registered in `server.ts`; admin action to start a run; e2e script kills the backend during `summarize`, restarts, approves in the inbox, asserts `filed` and the span tree in Traces
+  - Files: `example-backend/src/harness/*`, `example-backend/src/server.ts`, `example-frontend/e2e/harness-intake.spec.ts`
+  - Blocked by: 1.5, 1.9, 1.10, 1.11
+  - Skills: `verify-ui-changes`, `backend-test-env`
+  - Docs: create `docs/how-to/build-a-durable-workflow.md` using this workflow as the one example
+  - Acceptance: AC2 (e2e) — Playwright spec passes; screenshots of the inbox and the trace waterfall attached
+  - Shipped as two proofs: the kill/restart runs in `example-backend/src/harness/clinicalIntake.crash.test.ts` (spawns the real API process, SIGKILLs it mid-`summarize`, restarts); `harness-intake.spec.ts` approves in the inbox and asserts `filed` and the span tree
+
+## Phase 2 — Multi-instance
+
+- [x] **Task 2.0**: `InProcessRunner` concurrency
+  - Delivers: `new InProcessRunner({concurrency})` (default 8) runs up to N claimed tasks at once, each with its own lease and heartbeat; a slow phase no longer delays other tasks' wakes; `stop()` waits for all in-flight phases
+  - Files: `ai/src/harness/runners/inProcessRunner.ts`, tests
+  - Blocked by: 1.12
+  - Skills: `terreno-backend-api`
+  - Docs: reference "Runners" (concurrency option, ordering guarantees)
+  - Acceptance: bun test — a phase blocked on a gate does not prevent a second task from completing; never more than N concurrent; no task runs twice concurrently
+  - Shipped: fake-context cases in `ai/src/harness/runners/inProcessRunner.test.ts` (default 8, gate, peak, stop waits for all, invalid concurrency) and real-Mongo cases in `ai/src/harness/concurrency.test.ts` (blocked task does not hold up a second; 7 two-phase tasks at concurrency 3 peak at exactly 3 with no task running twice). Roast: PASS (2026-10-04; 76 targeted tests, three mutation checks red)
+
+- [x] **Task 2.1**: `JobsRunner`
+  - Delivers: `@terreno/ai/harness/jobsRunner` with optional peer `@terreno/jobs`; job `terreno.harness.phase` keyed `taskId:phase:attempt`; harness task lease + heartbeat is the authority; importing the root `@terreno/ai` never loads jobs
+  - Files: `ai/src/harness/runners/jobsRunner.ts`, `ai/package.json`, tests
+  - Blocked by: 2.0
+  - Skills: `terreno-backend-api`
+  - Docs: reference "Runners"; how-to "Run on multiple instances"
+  - Acceptance: AC11 — two workers race one phase; exactly one commit; stale owner rejected; knip clean without jobs installed
+  - Shipped: `ai/src/harness/runners/jobsRunner.test.ts` (two-worker race, stale-lease commit rejected, re-dispatch of a dead job, root imports never reach `@terreno/jobs`). Drift: the job key is `taskId:phase:attempt:claims` — `claims` (new `HarnessTask` counter) gives a phase revisited by an event wake or crash replay its own job, since jobs idempotency keys are permanent. Built before Task 2.0; it does not depend on `InProcessRunner` concurrency. Roast: PASS (2026-10-04; 17 targeted tests, ai suite 1185/0, knip clean, two mutation checks red)
+
+- [ ] **Task 2.2**: Runs admin screen
+  - Delivers: task list/tree with status filters, abort, resolve-interrupted (retry/abort/complete + reason), link to trace
+  - Files: `admin-frontend/src/widgets/harness/HarnessRuns*.tsx`, `ai/src/harness/routes/tasks.ts`
+  - Blocked by: 2.1
+  - Skills: `building-admin-interfaces`, `verify-ui-changes`
+  - Docs: admin-frontend reference
+  - Acceptance: Playwright resolves an interrupted EHR write; screenshots
+
+## Phase 3 — Long context
+
+- [ ] **Task 3.1**: Background compaction + manual `compact(instructions)`; originals stay searchable
+- [ ] **Task 3.2**: `reset` / handoff tool control
+- [ ] **Task 3.3**: Conversation forks at any message (parent history by reference)
+- [ ] **Task 3.4**: `defineDoc` typed documents (`scope`, `history: rewindable`, `fork: asOf`), committed atomically with transcripts
+
+Each 3.x task: Blocked by 1.12; Docs: reference + explanation sections; Acceptance: bun tests (10k-message conversation fits budget; fork isolation; doc rewind).
+
+## Phase 4 — Durable chat + multiplayer
+
+- [x] **Task 4.0**: Human gate — `GptHistory` migration strategy → **one-shot migration** script at deploy (decided 2026-10-02)
+- [ ] **Task 4.1**: `/gpt/prompt` on the harness; history mapping
+- [ ] **Task 4.2**: Steering, foreground/background abort, `viewState` over SSE
+- [ ] **Task 4.3**: rtk `useHarnessConversation` SSE hook + `GPTChat` adapter in example-frontend
+
+Acceptance: kill backend mid-chat, reconnect resumes; two browsers see the same view (Playwright, screenshots).
+
+## Phase 5 — Coding agents + malleability
+
+- [x] **Task 5.0**: Human gate — sandbox provider → **Cloud Run Jobs container** (decided 2026-10-02)
+- [ ] **Task 5.1**: `NodeExecutionEnv` + `CodingTools` (read/write/edit/bash with replay classes)
+- [ ] **Task 5.2**: Remote sandbox adapter
+- [ ] **Task 5.3**: Registry hot-replace (running calls finish on old code)
+
+Acceptance: a coding agent fixes a failing test in a fixture repo after a forced crash.