@terreno/mcp 57.20.0 → 58.0.0-beta.1

package/dist/docs/versioned/57.20.0/tasks/job-queues.md

@@ -0,0 +1,144 @@
+# Tasks: Durable background jobs
+
+IP: [job-queues.md](../implementationPlans/job-queues.md)  
+**Closes:** https://github.com/TerrenoLabs/terreno/issues/1188
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (package, enqueue, Mongo worker)
+
+- [x] **Task 1.1**: Scaffold `@terreno/jobs`
+  - Delivers: workspace package compiles and lints; root `jobs:compile` / `jobs:test` / `jobs:lint` scripts; empty `JobsApp` registers as `TerrenoPlugin` without starting a worker
+  - Files: `jobs/package.json`, `jobs/tsconfig.json`, `jobs/src/index.ts`, `jobs/src/jobsApp.ts`, root `package.json`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`
+  - Docs: none (Phase 5)
+  - Acceptance: `bun run jobs:compile` and `bun run jobs:lint` pass; `new TerrenoApp().register(new JobsApp())` boots in a bun test
+
+- [x] **Task 1.2**: `Job` model + `define` / `enqueue` + Mongo claim
+  - Delivers: five-type `Job` model; `jobs.define(name, {handler})`; `getJobsService().enqueue({name, payload})` inserts `pending`; `MongoJobRunner` claims with `findOneAndUpdate`; handler runs inside `runWithRequestContext({jobId})`; unknown `name` throws `APIError` 400
+  - Files: `jobs/src/models/job.ts`, `jobs/src/modelTypes.ts`, `jobs/src/jobsService.ts`, `jobs/src/runners/mongoRunner.ts`, tests
+  - Blocked by: 1.1
+  - Skills: `mongoose-schema-safety`, `backend-test-env`, `terreno-backend-api`
+  - Docs: stub one sentence in `docs/reference/jobs.md` if the file exists; else wait for 5.1
+  - Acceptance: bun test — enqueue then `startWorker` completes the job; missing handler fails loud; every schema field has `description`
+
+- [x] **Task 1.3**: Explicit `startWorker` in-process and lock reclaim
+  - Delivers: `JobsApp.register` does **not** poll; `startWorker()` starts the runner; `stopWorker()` aborts; expired `lockedAt` reclaims `running`; two workers claim one job once
+  - Files: `jobs/src/jobsApp.ts`, `jobs/src/runners/mongoRunner.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun test — no worker until `startWorker`; kill-the-process simulation: leave `pending`, new worker runs it; dual-worker claim uniqueness
+
+## Phase 2 — Retries, DLQ, delay, cron
+
+- [x] **Task 2.1**: Attempts, backoff, `dead`
+  - Delivers: throw → `attemptCount++`, `attempts[]`, `runAt` backoff with jitter; at `maxAttempts` → `status: "dead"`; success → `completed`; `ctx.signal` abort on cancel
+  - Files: `jobs/src/jobsService.ts`, retry helper, tests
+  - Blocked by: 1.3
+  - Skills: `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun test — three failures with `maxAttempts: 3` land `dead`; between attempts status is `pending` with future `runAt`; Luxon used for delay math
+
+- [x] **Task 2.2**: Delayed `runAt` + `idempotencyKey`
+  - Delivers: `enqueue({runAt})` not claimed before `runAt`; duplicate `(name, idempotencyKey)` returns the existing job and does not insert a second row
+  - Files: `jobs/src/jobsService.ts`, Job indexes, tests
+  - Blocked by: 1.2
+  - Skills: `mongoose-schema-safety`
+  - Docs: none (5.1)
+  - Acceptance: bun test — frozen clock (Luxon); unique index violation path covered
+
+- [x] **Task 2.3**: `JobSchedule` + recurring cron + IANA timezone
+  - Delivers: `define(..., {schedule: {cron, timezone}})`; upsert `JobSchedule`; tick enqueues a child `Job`; skip tick if a child is still `running`/`pending` for that schedule; invalid cron fails at define/start
+  - Files: `jobs/src/models/jobSchedule.ts`, scheduler, tests
+  - Blocked by: 1.3
+  - Skills: `mongoose-schema-safety`, `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun test — `America/New_York` vs `UTC` next-run; overlap skip; default timezone `UTC`
+
+## Phase 3 — Runners and execute HTTP
+
+- [x] **Task 3.1**: `JobRunner` interface + custom runner
+  - Delivers: injected `runner` used on enqueue/start; test fake runner records `enqueue` calls; Mongo remains default
+  - Files: `jobs/src/types.ts`, `jobs/src/runners/custom.ts` (or types-only), tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun test — custom runner `enqueue` called once per job; Mongo runner tests still pass
+
+- [x] **Task 3.2**: `POST /jobs/execute` auth gate
+  - Delivers: route mounted when `mountExecuteRoute` or cloud runner; body `{jobId}`; loads/claims/runs; unsigned 401; terminal completed → 200 no-op; live lock → 409
+  - Files: `jobs/src/routes/jobsExecute.ts`, tests
+  - Blocked by: 1.3
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: none (5.1)
+  - Acceptance: bun + supertest; path can be omitted from SDK codegen (internal tag); rate-limit not skipped
+
+- [x] **Task 3.3**: GCP Cloud Tasks adapter (mocked)
+  - Delivers: `@terreno/jobs/runners/gcpCloudTasks` optional peer `@google-cloud/tasks`; `enqueue` creates HTTP task to `{publicUrl}/jobs/execute` with OIDC audience; no live GCP
+  - Files: `jobs/src/runners/gcpCloudTasks.ts`, tests with fake client, `jobs/package.json` exports/peers
+  - Blocked by: 3.1, 3.2
+  - Skills: `terreno-backend-api`
+  - Docs: env names listed in 5.1
+  - Acceptance: bun test — fake client receives queue/url/oidc; missing config fails startup loud
+
+- [x] **Task 3.4**: Vercel Queues adapter (mocked)
+  - Delivers: `@terreno/jobs/runners/vercelQueues` optional peer; `send(topic,{jobId})` with retention/delay coupling; private `handleCallback` consumer → `executeJobById`; no Workflows API; no live Vercel
+  - Files: `jobs/src/runners/vercelQueues.ts`, tests
+  - Blocked by: 3.1, 3.2
+  - Skills: `terreno-backend-api`
+  - Docs: 5.1
+  - Acceptance: bun test — fake queue publish/send options, consumer retry directives, >7d dispatch compensation; platform auth delegated to vendor `handleCallback`
+
+## Phase 4 — Admin API and UI
+
+- [x] **Task 4.1**: Admin HTTP + `admin:jobs`
+  - Delivers: list/detail/retry/requeue/cancel + schedule pause/resume; `terrenoStatements.admin` includes `jobs`; 403 without permission; retry creates linked row; requeue from `dead`
+  - Files: `jobs/src/routes/jobsAdmin.ts`, `api/src/rbac/statements.ts`, RBAC tests in jobs package, example-backend OpenAPI if needed
+  - Blocked by: 2.1, 2.3
+  - Skills: `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun + supertest for 200/403/401; retry vs requeue semantics per IP
+
+- [x] **Task 4.2**: Admin frontend Jobs screens
+  - Delivers: `JOBS_ADMIN_WIDGETS`, `JobsDashboardScreen`, `JobsJobDetail`, home widget `jobs`; built-in registry (no host remap)
+  - Files: `admin-frontend/src/jobs/*`, widget registry, tests + isolated specs
+  - Blocked by: 4.1
+  - Skills: `building-admin-interfaces`, `terreno-ui`, `terreno-data-fetching`
+  - Docs: `docs/how-to/admin-import-prebuilt.md` in 5.1
+  - Acceptance: bun tests for render/filter/actions; no `fetch`/`axios`; no syncdb
+
+- [x] **Task 4.3**: example-backend + example-frontend + admin-spa + UI verify
+  - Delivers: example registers `JobsApp` + Mongo runner; demo job; optional `jobs:worker` script; routes `/admin/jobs`; admin-spa `/jobs`; SDK regen if OpenAPI changed; `JOBS_START_WORKER` gates API-process worker (default true)
+  - Files: `example-backend/src/server.ts`, worker entry, `example-frontend/app/admin/**`, `admin-spa/app/**`, `store/openApiSdk.ts` (generated)
+  - Blocked by: 4.2, 1.3
+  - Skills: `building-admin-interfaces`, `verify-ui-changes`, `generate-sdk`
+  - Docs: none (5.1)
+  - Acceptance: `verify-ui-changes` — `/opt/cursor/artifacts/jobs_admin_dlq_workflow.mp4` (script→dead attempts→requeue execution→retry linked row); `/opt/cursor/artifacts/jobs_admin_cancel_scheduled_job.mp4` (scheduled cancel confirmation, refresh persistence, no attempts); worker script documented
+
+## Phase 5 — Docs, CI, publish
+
+- [x] **Task 5.1**: Diátaxis + agent docs + changelog + seed
+  - Delivers: how-to, reference, api.md cron contrast, env table, import-prebuilt, seed IP/task URLs, jobs rule, backend-api skill mention, unreleased changelog, `bun run rules` / `skills:sync`
+  - Files: `docs/how-to/background-jobs.md`, `docs/reference/jobs.md`, `docs/how-to/README.md`, `docs/reference/api.md`, `docs/reference/environment-variables.md`, `docs/how-to/admin-import-prebuilt.md`, `docs/explanation/roadmap-seed-issues.md`, `.rulesync/rules/jobs/00-jobs.md`, `plugins/terreno-planning/skills/terreno-backend-api/SKILL.md`, `changelog/unreleased/job-queues.md`
+  - Blocked by: 3.4, 4.3
+  - Skills: `update-docs`, `update-agent-docs`
+  - Docs: (this task)
+  - Acceptance: stranger can define, enqueue, run a worker, and choose Mongo vs GCP vs Vercel from the how-to; `bun run website:build`; `cronjob()` still documented as process-local
+
+- [x] **Task 5.2**: CI + publish wiring
+  - Delivers: `jobs-ci.yml`; `publish-on-tag` for `@terreno/jobs`; `cd.yml` path filter includes `jobs/**`
+  - Files: `.github/workflows/*`
+  - Blocked by: 1.1
+  - Skills: none
+  - Docs: none
+  - Acceptance: workflow validates required secrets if any; package listed in publish job graph
+
+- [x] **Task 5.3**: Positioning row (when Complete)
+  - Delivers: `docs/explanation/positioning.md` Celery/ActiveJob cell updated only when IP header is **Complete**
+  - Files: `docs/explanation/positioning.md`
+  - Blocked by: 5.1 and all prior acceptance criteria
+  - Skills: `update-docs`
+  - Docs: positioning
+  - Acceptance: row no longer says Not shipped

package/dist/docs/versioned/57.20.0/tasks/knip-cleanup.md

@@ -0,0 +1,146 @@
+# Task List: Remove the Knip baseline
+
+See: [`docs/implementationPlans/knip-cleanup.md`](../implementationPlans/knip-cleanup.md)
+
+**Status:** Complete  
+**RTK deprecation flag:** None
+
+## Instructions for the implementing agent
+
+- Re-run Knip (JSON reporter, default + production, same as `scripts/static-analysis/full.ts`) at the start of every task. The IP inventory is a snapshot, not the live list.
+- Disposition order: **entry → ignore (with comment) → unexport → delete**. Never `knip --fix`.
+- Do not delete the old Knip baseline until Task 6.1. Earlier tasks must keep `bun run analyze:full` green while the live finding count falls.
+- Do not remove symbols from published package public entries (`src/index.ts` / `src/index.tsx` / `package.json` `exports`).
+- Do not remove Expo autolink, native, or Metro packages from `demo`, `admin-spa`, `example-frontend`, or `ui` `package.json` because Knip cannot see them.
+- Tests: `bun test --only-failures` on the closest package; after config edits, `bun test scripts/static-analysis/lib.test.ts`.
+- Supporting skills: `update-docs`. UI deletes also use `verify-ui-changes`.
+
+### Phase 1: Entry graph
+
+- [x] **Task 1.1**: Register isolated suites and repo script tests as Knip entries
+  - Delivers: `*.isolated.ts(x)` and `scripts/**/*.test.ts` (plus `scripts/static-analysis/lib.test.ts`, `.github/scripts/*.test.ts`) stop reporting as unused files
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (entry-graph section: isolated files and `scripts/` tests are first-class entries)
+  - Blocked by: none
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: live default Knip report has no `files` finding whose path contains `.isolated.` or `scripts/` + `.test.`; `bun run analyze:full` exits 0; docs name this entry rule
+
+- [x] **Task 1.2**: Put mcp-server tests back on the Bun plugin
+  - Delivers: `mcp-server/src/__tests__/**` are in the graph (today `workspaces.mcp-server.bun: false` because Knip 6.34 wants `test.preload` as an array)
+  - Files: `knip.jsonc` and/or `mcp-server/package.json` (`test.preload` array form if required)
+  - Blocked by: none
+  - Docs: none beyond a comment in `knip.jsonc`
+  - Acceptance: no default `files` findings under `mcp-server/src/__tests__/`; mcp `bun test` still runs; `analyze:full` exits 0
+
+- [x] **Task 1.3**: Register codegen, Metro stubs, Playwright, fingerprint, and Docusaurus theme entries
+  - Delivers: tool-owned files are entries instead of “unused files”: `openapi-config.ts`, `comms-openapi-config.ts`, `jspdf-native-stub.js`, `fingerprint.config.js`, `playwright.circleci.config.ts`, `ui/babel.config.js`, `website/src/theme/**`, `scripts/ci/prepare-package-publish.mjs`, `scripts/planning/fingerprintRisk.ts`, `scripts/planning/updateDependenciesPr.ts` if they are invoked from `package.json` / CI
+  - Files: `knip.jsonc`; `package.json` scripts only if an entry name is wrong
+  - Blocked by: none
+  - Docs: `docs/explanation/static-analysis.md` — table row for Metro stubs / codegen configs
+  - Skills: `update-docs`
+  - Acceptance: those paths are absent from live `files` findings or listed as `entry`; comments explain each ignore glob if an ignore is used instead; `analyze:full` exits 0
+
+- [x] **Task 1.4**: Ignore generated Expo skill script copies; keep the canonical copy in graph if it is real
+  - Delivers: duplicate `expo-cicd-workflows/scripts/{fetch,validate}.js` under `.agents/`, `.claude/`, `.cursor/`, `.devin/`, `.github/`, `.rulesync/`, `skills/` do not appear as unused files
+  - Files: `knip.jsonc` ignore globs; confirm canonical path (`.rulesync/skills/...` or `skills/...`)
+  - Blocked by: none
+  - Docs: one sentence in `docs/explanation/static-analysis.md` that generated skill copies are ignored
+  - Skills: `update-docs`
+  - Acceptance: no `files` findings whose path contains `expo-cicd-workflows/scripts/`; `analyze:full` exits 0
+
+### Phase 2: Documented ignores (cannot fix)
+
+- [x] **Task 2.1**: Ignore Expo autolink / Metro / font / native `dependencies` Knip cannot see
+  - Delivers: `ignoreDependencies` (or workspace-scoped equivalent) for the live unused-deps list on `demo`, `admin-spa`, `example-frontend`, `ui` that exist for autolinking or Metro, including `jspdf` unlisted from metro stubs and `expo-system-ui` / `expo-updates` unlisted from `app.json`
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (why these stay in `package.json`)
+  - Blocked by: Task 1.3
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: those packages are gone from live `dependencies` / `unlisted` findings; each ignore has a comment; no app/`ui` `package.json` lost an Expo native dep; `analyze:full` exits 0
+
+- [x] **Task 2.2**: Ignore binaries, catalog-only, and optional peers that are real
+  - Delivers: `eas`, `maestro`, catalog `@sentry/react-native` if unused in this repo but required by the catalog contract, `admin-frontend` optional `react-native-webview`
+  - Files: `knip.jsonc`
+  - Blocked by: none
+  - Docs: comment in `knip.jsonc`; mention binaries in `docs/explanation/static-analysis.md` if not already there
+  - Skills: `update-docs`
+  - Acceptance: live report has no `binaries` / `catalog` / `optionalPeerDependencies` findings except any still destined for Task 3.1 deletion; `analyze:full` exits 0
+
+- [x] **Task 2.3**: Ignore remaining unlisted modules that are optional or type-only
+  - Delivers: honest ignores or `optionalDependencies` for `ioredis` (rate-limit redis store), `@ai-sdk/google-vertex`, `@docusaurus/plugin-content-docs`, `express` in ai tests, `@terreno/api` from `@terreno/test` if the graph cannot see the workspace package
+  - Files: `knip.jsonc` and/or the declaring `package.json` if the package should be listed instead of ignored
+  - Blocked by: Task 1.2
+  - Acceptance: Pick records in the task log each remaining unlisted name as either added to `package.json` or ignored with reason; live `unlisted` count is 0 or only items Task 3 will delete; `analyze:full` exits 0
+
+### Phase 3: Remove true unused packages
+
+- [x] **Task 3.1**: Delete unused `devDependencies` after the graph is honest
+  - Delivers: remove packages that still appear as unused `devDependencies` and are not CLIs invoked from scripts (`sinon`, `@types/sinon`, `@types/bcrypt`, `@types/cron`, leftover `typedoc`/`prettier`/`ts-node`/`tsx` only if no script references them). Keep `@rtk-query/codegen-openapi`, `@biomejs/biome`, `mongodb` as a driver for example-backend tests, etc., when a script or plugin uses them — those become entries or ignores in Phase 1–2, not deletions
+  - Files: affected `package.json` files, lockfile via `bun install`
+  - Blocked by: Task 1.1, Task 1.2, Task 1.3, Task 2.2
+  - Docs: none unless a documented install step named a removed tool
+  - Acceptance: `rg` of the repo and `package.json` scripts show no remaining reference; `bun run compile` (or package `compile`) and the package test script still pass for each touched package; live unused-devDep list for those names is empty; `analyze:full` exits 0
+
+- [x] **Task 3.2**: Remove unused runtime deps that are not Expo/autolink
+  - Delivers: example-backend / website / test / api leftovers (`clsx`, unused `lodash` in `@terreno/test`, `generaterr` / `scmp` / `@sentry/profiling-node` **only if** nothing loads them including Sentry init). If a dep is loaded via string/dynamic import, ignore it instead
+  - Files: affected `package.json`, source if an import must move
+  - Blocked by: Task 2.1, Task 3.1
+  - Acceptance: each removed name has no remaining import; package tests pass; `analyze:full` exits 0
+
+### Phase 4: Dead files
+
+- [x] **Task 4.1**: Delete in-repo-dead example-frontend modules
+  - Delivers: remove unused files Knip still reports after Phase 1 (candidates from snapshot: `hooks/useLogoutUser.ts`, `useSentryUserSetup.ts`, `useUpdateProfile.ts`, `constants/Colors.ts`, and any unused store helpers). Keep files that routes, tests, or docs still import — those need an entry or a real import
+  - Files: `example-frontend/**` listed by live Knip `files`
+  - Blocked by: Task 1.3
+  - Docs: update example-frontend docs/README only if a named file was documented
+  - Skills: `update-docs`, `verify-ui-changes` if a routed screen changes
+  - Acceptance: those paths absent from live `files` findings; `cd example-frontend && bun test` passes; if UI was unwired, login + related screen still work with artifacts under `/opt/cursor/artifacts/`
+
+- [x] **Task 4.2**: Delete or wire dead demo / example-backend / api example files
+  - Delivers: `demo/stories/PasswordField.stories.tsx` if unregistered; `demo/.eslintrc.js` if unused; `example-backend` unused scripts (`configuration-example.ts`, `seed-admin-spa-admin.ts`, `seedConsents.ts`) unless `package.json` / AdminApp should call them — then add entries; `example-backend/src/constants/index.ts` if a banned barrel leftover; `api/src/example.ts`; unused vendor `convert-yaml.js` only if nothing requires it
+  - Files: paths from live Knip `files` in those packages
+  - Blocked by: Task 1.3
+  - Docs: example-backend README / how-to if a seed script is removed or registered
+  - Skills: `update-docs`
+  - Acceptance: live `files` findings for those packages are 0 or only ignored globs; relevant `bun test` passes; `analyze:full` exits 0
+
+- [x] **Task 4.3**: Delete or keep-with-entry remaining unused files (`ui/checkDeps.js`, `processCounties.js`, `compileAuthEntry.ts`, leftover demo tests already covered)
+  - Delivers: every remaining default `files` finding is either an entry, an ignore glob with comment, or deleted
+  - Files: leftover paths from live Knip
+  - Blocked by: Task 1.1, Task 1.4, Task 4.1, Task 4.2
+  - Acceptance: live default+production `files` count is 0; `analyze:full` exits 0
+
+### Phase 5: Exports and types
+
+- [x] **Task 5.1**: Unexport unused **internal** symbols in `scripts/` and examples
+  - Delivers: after tests are in the graph, remaining unused exports/types in `scripts/`, `example-frontend/`, `example-backend/`, `demo/` that are not a public package entry become non-exported (or deleted if the whole helper is dead)
+  - Files: modules named by live `exports` / `types` findings in those trees
+  - Blocked by: Task 1.1, Task 4.1, Task 4.2
+  - Acceptance: those packages have no unused **internal** export/type findings; tests that imported the symbol still compile (they use the same module, not the export); `analyze:full` exits 0
+
+- [x] **Task 5.2**: Unexport unused **internal** symbols in published packages
+  - Delivers: same as 5.1 for `api`, `admin-frontend`, `comms`, `syncdb`, `mcp-server`, `ai`. Do **not** remove re-exports from `src/index.ts(x)`
+  - Files: internal modules named by live findings
+  - Blocked by: Task 1.2
+  - Docs: none unless a documented “internal helper” was publicized in explanation/reference — then update that page
+  - Skills: `update-docs`
+  - Acceptance: each remaining unused export/type is classified public (re-exported from the package entry) or is gone; package `bun test` / `compile` passes; `analyze:full` exits 0
+
+- [x] **Task 5.3**: Ignore leftover **public** unused exports and types
+  - Delivers: `ignoreIssues` (path-scoped `exports`/`types`) for public API unused inside this monorepo, with comments
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (public API ignore rule)
+  - Blocked by: Task 5.1, Task 5.2
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: live `exports` and `types` counts are 0; no public `index` export removed; `analyze:full` exits 0
+
+### Phase 6: Remove baseline
+
+- [x] **Task 6.1**: Delete the Knip baseline and enforce zero findings directly
+  - Delivers: live default+production fingerprint set is `[]`; no Knip baseline exists; docs state that new findings are fixed or added to `knip.jsonc` with a reason
+  - Files: delete `scripts/static-analysis/knip-baseline.json`; update `docs/explanation/static-analysis.md`, `scripts/static-analysis/full.ts`, and tests
+  - Blocked by: Task 2.1, Task 2.2, Task 2.3, Task 3.2, Task 4.3, Task 5.3
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: `test ! -e scripts/static-analysis/knip-baseline.json`; `bun run check:knip` prints no findings and exits 0; `bun run analyze:full` exits 0; static-analysis tests pass

package/dist/docs/versioned/57.20.0/tasks/mcp-doc-sync-off-compile-path.md

@@ -0,0 +1,30 @@
+# Tasks: Move mcp-server doc-sync off the compile path
+
+IP: [mcp-doc-sync-off-compile-path.md](../implementationPlans/mcp-doc-sync-off-compile-path.md)
+Slice: mcp-doc-sync-off-compile-path · Scan goal: reduce-cold-compile-time (305s → 214s)
+
+## T0 — Baseline snapshot (done)
+
+- Built current mcp `compile` (full pipeline) and snapshotted `dist/docs`
+  (3224 versioned + 6 guidelines + ui-types) for parity diff.
+
+## T1 — Split compile/build + bundle docs at publish (done)
+
+- `mcp-server/package.json`: `compile` → `NODE_OPTIONS=--max-old-space-size=8192 tsc`;
+  `build` keeps sync+tsc+cp, redundant `NODE_OPTIONS` dropped from the copy steps.
+- Added `prepublishOnly: "bun run build"` so **both** publish paths (GitHub Actions and
+  CircleCI `scripts/ci/publish-package.sh`) bundle docs via npm's lifecycle. No workflow
+  edit needed. (Fixes Bugbot: CircleCI publish also runs the tsc-only `compile`.)
+
+## T2 — Verify (done)
+
+- mcp `compile`: tsc only, 0 "Synced docs" lines, no `dist/docs`, `dist/index.js` present. ✅
+- mcp `build`: `dist/docs` byte-identical to baseline (`diff -r` → IDENTICAL). ✅
+- Combined A+B integration (B stacked temporarily): full `bun run compile` ×3 →
+  exit 0, 0 errors, 0 mcp sync during compile. Best cold **186s vs 305s baseline (−39%)**. ✅
+- publish-mcp job runs `bun run build`. ✅
+
+## T3 — Docs (done)
+
+- Updated `.claude/rules/mcp-server/00-mcp-server.md`: `compile` = type-check,
+  `build` = shippable artifact with docs.

package/dist/docs/versioned/57.20.0/tasks/mcp-service-tokens.md

@@ -0,0 +1,132 @@
+# Tasks: MCP service tokens
+
+Plan: [`docs/implementationPlans/mcp-service-tokens.md`](../implementationPlans/mcp-service-tokens.md)
+
+**Status:** Approved — all in-scope tasks Roast PASS. **next: brew**.
+
+## Instructions for the implementing agent
+
+- Load `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `update-docs`.
+- Phase 4+: `verify-ui-changes`, `building-admin-interfaces`, `generate-sdk`.
+- TDD: failing test first per task.
+- Run `bun test` in touched packages; `bun run lint` on `api/`, `example-backend/`, `example-frontend/` as applicable.
+- Never log or persist full `mcp_` tokens after the create response.
+- Do not implement OAuth, scopes, or REST bearer for service tokens.
+
+---
+
+### Phase 1: Model and MCP auth
+
+- [x] **Task 1.1**: `McpServiceToken` model + types
+  - Delivers: Mongoose model with issue/verify/revoke/count statics; SHA-256 hash; `mcp_` + 32-byte hex secret; field descriptions on every path
+  - Files: `api/src/models/mcpServiceToken.ts`, `api/src/types/mcpServiceToken.ts`, `api/src/models/mcpServiceToken.test.ts`, `api/src/index.ts`
+  - Blocked by: none
+  - Docs: `docs/reference/api.md` (exported model contract)
+  - Skills: `mongoose-schema-safety`, `terreno-backend-api`
+  - Acceptance: `issueFor` returns plaintext once; `verify` finds active token; respects `revokedAt` and `expiresAt`; `countActiveForUser` correct; duplicate hash impossible
+
+- [x] **Task 1.2**: Service token branch in `extractUserFromHeaders`
+  - Delivers: when `mcpServiceTokens` enabled and bearer starts with `mcp_`, resolve user via model verify; update `lastUsedAt`; order before Better Auth and JWT
+  - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`, `api/src/mcp/types.ts` (extend `MCPAuthContext` if needed)
+  - Blocked by: Task 1.1
+  - Docs: none
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Acceptance: valid token resolves owner; revoked/expired/disabled user → undefined; non-`mcp_` bearer still uses existing JWT/session tests unchanged
+
+---
+
+### Phase 2: Self-serve routes and TerrenoApp flag
+
+- [x] **Task 2.1**: `/mcp/service-tokens` HTTP routes
+  - Delivers: POST create (cap 10), GET list (owner), DELETE revoke (owner); OpenAPI via `createOpenApiBuilder`; reject `mcp_` bearer on these routes
+  - Files: `api/src/mcp/serviceTokens.ts`, `api/src/mcp/serviceTokens.test.ts`, `api/src/index.ts`
+  - Blocked by: Task 1.1
+  - Docs: `docs/reference/api.md` (route table)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: supertest covers happy path, cap, owner isolation, create response includes `mcpUrl` + one-time `token`; list omits hash and plaintext
+
+- [x] **Task 2.2**: `TerrenoAppOptions.mcpServiceTokens`
+  - Delivers: `{enabled, publicMcpUrl?}` or boolean shorthand; mounts routes when enabled; passes flag into `MCPAuthContext`
+  - Files: `api/src/terrenoApp.ts`, `api/src/terrenoApp.test.ts` (or service token integration test)
+  - Blocked by: Task 1.2, Task 2.1
+  - Docs: `docs/reference/api.md` (`TerrenoAppOptions`); `docs/how-to/connect-mcp-service-token.md` (create skeleton)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: app with flag on serves routes and accepts `mcp_` on `/mcp`; flag off serves neither
+
+- [x] **Task 2.3**: End-to-end MCP call with service token
+  - Delivers: integration test — mint token, `POST /mcp` JSON-RPC `tools/call` with Bearer, assert the same owner-visible result as a session JWT
+  - Files: extend `api/src/mcp/server.test.ts` or `serviceTokens.test.ts`
+  - Blocked by: Task 2.2
+  - Docs: `docs/how-to/connect-mcp-service-token.md` (GET 405 probe + POST `initialize` / `tools/call`)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: GET `/mcp` returns Streamable-HTTP JSON-RPC 405; POST `tools/call` with `mcp_` acts as the owner; invalid `mcp_` is denied
+
+---
+
+### Phase 3: Example-backend admin
+
+- [x] **Task 3.1**: Enable flag + admin model registration
+  - Delivers: `mcpServiceTokens: {enabled: true, publicMcpUrl: …}` on example `TerrenoApp`; `AdminApp` model entry — listFields, create/update disabled, admin delete → revoke; `responseHandler` strips `tokenHash`
+  - Files: `example-backend/src/server.ts`, `example-backend/src/api/mcpServiceTokensAdmin.ts` (if preDelete hook extracted), `example-backend/src/tests/mcpServiceTokens.admin.test.ts`
+  - Blocked by: Task 2.2
+  - Docs: `example-backend/README.md` (one paragraph + admin path)
+  - Skills: `building-admin-interfaces`, `terreno-backend-api`, `update-docs`
+  - Acceptance: admin user lists tokens for multiple users; revoke removes MCP access; non-admin cannot hit admin routes
+
+---
+
+### Phase 4: Example-frontend settings UI
+
+- [x] **Task 4.1**: SDK codegen for service-token routes
+  - Delivers: regenerated `openApiSdk` hooks for POST/GET/DELETE `/mcp/service-tokens`
+  - Files: `example-frontend/store/openApiSdk.ts` (generated), `example-frontend/openapi-config.ts` (only if path filter needed)
+  - Blocked by: Task 2.1
+  - Skills: `generate-sdk`
+  - Acceptance: TypeScript compiles; hooks callable from settings screen
+
+- [x] **Task 4.2**: `/settings/mcp` screen
+  - Delivers: create form (name, optional expiry), copy-once modal (URL + token + JSON snippet), list with revoke, link from Profile
+  - Files: `example-frontend/app/settings/_layout.tsx`, `example-frontend/app/settings/mcp.tsx`, `example-frontend/app/(tabs)/profile.tsx`
+  - Blocked by: Task 4.1
+  - Docs: none (how-to covers operator steps)
+  - Skills: `terreno-ui`, `verify-ui-changes`
+  - Acceptance: manual test — create, copy snippet, revoke; artifacts in `/opt/cursor/artifacts/`; web on port 8082
+
+---
+
+### Phase 5: Documentation
+
+- [x] **Task 5.1**: Operator docs + cross-links
+  - Delivers: complete `docs/how-to/connect-mcp-service-token.md` (Perplexity form table, JSON snippet, curl); update `docs/how-to/expose-mcp-tools.md` auth section; `docs/explanation/authentication.md` short subsection; note sibling OAuth in `app-mcp-server.md` cross-link only
+  - Files: docs listed above
+  - Blocked by: Task 2.3, Task 4.2
+  - Docs: same files
+  - Skills: `update-docs`
+  - Acceptance: stranger can connect Perplexity from docs alone; `bun run website:build` passes if pages are wired in sidebar
+
+---
+
+## Frontier
+
+Completed: 1.1, 1.2, 2.1, 2.2, 2.3, 3.1, 4.1, 4.2, 5.1. Frontier: none. **next: brew**.
+
+```
+1.1 → 1.2 → 2.2 → 2.3
+1.1 → 2.1 → 2.2
+2.1 → 4.1 → 4.2
+2.2 → 3.1
+2.3 + 4.2 → 5.1
+```
+
+## Acceptance → verification map
+
+| IP criterion | Task(s) |
+| --- | --- |
+| Flag off behavior | 2.2 |
+| Create once / list safe | 2.1 |
+| Cap 10 | 2.1 |
+| Expiry + revoke on `/mcp` | 1.2, 2.3 |
+| Admin all-users revoke | 3.1 |
+| Perplexity GET+POST | 2.3 |
+| Settings UI | 4.2 |
+| Docs | 5.1 |