@terreno/mcp 57.17.0 → 57.18.0

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

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

package/src/docs/versioned/57.17.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.17.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.17.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.17.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.