@terreno/mcp 57.3.0 → 57.6.0

package/src/docs/versioned/next/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/src/docs/versioned/next/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/src/docs/versioned/next/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/src/docs/versioned/next/tasks/migrate-admin-to-syncdb.md

@@ -0,0 +1,209 @@
+# Tasks: Migrate built-in admin to syncdb
+
+IP: [migrate-admin-to-syncdb.md](../implementationPlans/migrate-admin-to-syncdb.md)
+
+**Status:** Approved. Pick–Roast execution is in progress.
+
+Skills for Pick: `terreno-data-fetching`, `terreno-backend-api`, `mongoose-schema-safety` (only if a later task touches schema — this IP must not), `generate-sdk` (only if OpenAPI for non-admin routes changes), `verify-ui-changes`, `update-docs`, `backend-test-env`, `terreno-ui`, `update-agent-docs`.
+
+---
+
+## Phase 1 — Characterization + CI (no product behavior)
+
+Phase 1 is a hard gate. Protocol and UI tasks stay blocked until every Phase 1 checkbox is done.
+
+- [x] **Task 1.1**: `admin-frontend` ≥95% line+function coverage + threshold
+  - Delivers: existing screens/hooks covered enough that `bun test` in `admin-frontend` meets 95% lines and functions; `bunfig.toml` `coverageThreshold` set so CI fails on drop
+  - Files: `admin-frontend/src/**/*.test.*`, `admin-frontend/bunfig.toml`
+  - Blocked by: none
+  - Acceptance: `cd admin-frontend && bun test --coverage` reports ≥95% lines and functions; threshold is committed
+
+- [x] **Task 1.2**: `admin-backend` coverage scope excludes `@terreno/test` dist
+  - Delivers: LCOV / bun coverage for the package measures `admin-backend/src` (and dist of this package only), not `../test/dist/**`; package still ≥95% on that scope
+  - Files: `admin-backend/bunfig.toml` (or coverage ignore), related test config
+  - Blocked by: none
+  - Acceptance: coverage report no longer attributes `@terreno/test` files; `adminApp.ts` and package source still ≥95%; `cd admin-backend && bun test --coverage` green
+
+- [x] **Task 1.3**: CircleCI jobs for admin packages
+  - Delivers: `admin-backend-ci` and `admin-frontend-ci` in continue-config; root script `admin-frontend:test`; both jobs in the required workflow
+  - Files: `.circleci/continue-config.yml`, `package.json`
+  - Blocked by: 1.1, 1.2
+  - Acceptance: config YAML lists both jobs; `bun run admin-frontend:test` and `bun run admin-backend:test` work from repo root
+
+- [x] **Task 1.4**: Shard existing admin Playwright specs into CI
+  - Delivers: `example-frontend/e2e/admin-home.spec.ts`, `admin-form.spec.ts`, `admin-table-search-filter.spec.ts`, `admin-table-bulk-actions.spec.ts`, `admin-custom-screens.spec.ts`, `admin-comms-back.spec.ts` (and siblings that exist) run in the CircleCI Playwright matrix, not only `admin.spec.ts`
+  - Files: `.circleci/continue-config.yml`, any e2e project config
+  - Blocked by: none
+  - Acceptance: continue-config matrix includes those spec files; a dry read of the YAML shows them next to `admin.spec.ts`
+
+- [x] **Task 1.5**: Golden HTTP tests for admin membership + config
+  - Delivers: pinned assertions for `GET /admin/config` shape and list/search/bulk-patch on a synced String `_id` model (example Todo) plus an ObjectId model (User) so later protocol work cannot silently change REST
+  - Files: `admin-backend/src/adminApp*.test.ts` (or new focused spec)
+  - Blocked by: none
+  - Acceptance: tests fail if list query params, pagination envelope, or bulk-patch URL/body change; `bun test` in admin-backend passes
+
+- [x] **Task 1.6**: Pin `useAdminApi` URL shapes
+  - Delivers: isolated tests that `list/read/create/update/delete/bulk-patch` hit `/admin/{routePath}` exactly as today
+  - Files: `admin-frontend/src/isolated/hooks.isolated.tsx`, `useAdminApi` tests
+  - Blocked by: none
+  - Acceptance: URL/method goldens for all six operations; isolated suite green
+
+- [x] **Task 1.7**: CRUD smoke E2E for embedded + SPA
+  - Delivers: Playwright covering Todos list → create → edit → delete on `example-frontend` `/admin` and `admin-spa` `/console` (extend existing specs; do not skip login/consent)
+  - Files: `example-frontend/e2e/admin.spec.ts` (or `admin-form.spec.ts`), `admin-spa/e2e/integration/adminSpa.integration.spec.ts` or new `admin-spa/e2e/crud.spec.ts`
+  - Blocked by: none
+  - Acceptance: specs assert visible row after create, field change after edit, row gone after delete; they pass locally against the documented full-stack commands
+  - Skills: `verify-ui-changes` (record how to run; Phase 1 may land specs that CI runs)
+
+---
+
+## Phase 2 — Fetch wrapper (RPC off RTK)
+
+- [x] **Task 2.1**: Tiny fetch client
+  - Delivers: `adminRequest({url, method, body, signal})` using native `fetch`, AbortController timeout, JSON + FormData, maps failures to `APIError`; unit tests with mocked `globalThis.fetch`
+  - Files: `admin-frontend/src/adminRequest.ts`, `admin-frontend/src/adminRequest.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: tests for timeout abort, 4xx/5xx → APIError, JSON parse, FormData not JSON-stringified, credentials forwarded; no axios import
+  - Skills: `terreno-data-fetching`
+
+- [x] **Task 2.2**: Host-injected auth contract
+  - Delivers: admin context accepts `{baseUrl, getAuthHeaders, credentials}`; SPA fixture uses `credentials: "same-origin"` and empty/cookie headers; embedded fixture uses Bearer from `getAuthHeaders`
+  - Files: admin-frontend provider/context (existing Admin host types), tests
+  - Blocked by: 2.1
+  - Acceptance: unit tests prove Authorization header present/absent per fixture; cookie credential mode set
+  - Skills: `terreno-data-fetching`
+
+- [x] **Task 2.3**: Dual-run RPC hooks onto fetch
+  - Delivers: `useAdminConfig`, scripts, roles, configuration, documents, comms, AI explorer, consent, version-config, background-tasks, `AdminObjectPicker` list fetch use `adminRequest` when the client is provided; if only `api` is provided, existing `injectEndpoints` still works
+  - Files: `admin-frontend/src/useAdminConfig.ts`, `useAdminScripts.ts`, `useAdminRoles.ts`, `useConfigurationApi.ts`, `useDocumentStorageApi.ts`, `useAdminBackgroundTask.ts`, `useConsentHistory.ts`, `ConsentFormEditor.tsx`, `AdminVersionConfig.tsx`, `AdminObjectPicker.tsx`, `comms/useCommsDashboardApi.tsx`, `widgets/AIRequestsScreenWidget.tsx`, tests
+  - Blocked by: 2.2, 1.6
+  - Acceptance: each hook has tests for both backends; no behavior change when only `api` is passed
+  - Skills: `terreno-data-fetching`
+
+---
+
+## Phase 3 — Protocol (`adminBroadcast` + window subscribe)
+
+- [x] **Task 3.1**: `adminBroadcast` on `SyncConfig`
+  - Delivers: optional `adminBroadcast?: boolean` on existing collection `sync` config; default false; registration stores the flag; docs comment in types
+  - Files: `api/src/sync/types.ts`, `api/src/api.ts` (options plumbing), `api/src/sync/*.test.ts`
+  - Blocked by: 1.5
+  - Acceptance: registering with/without the flag; existing sync tests pass; no second `registerSync` for the same model
+  - Skills: `terreno-backend-api`
+
+- [x] **Task 3.2**: Emit deltas to `{collection}|admin`
+  - Delivers: when `adminBroadcast` is true, change-stream / mutate emit also targets `{collection}|admin` in addition to the owner/tenant/broadcast stream
+  - Files: emit path under `api/src/sync/` (change stream + mutate ack), tests
+  - Blocked by: 3.1
+  - Acceptance: unit/socket test: owner-scoped Todo create emits to `todos|owner:{id}` **and** `todos|admin`; flag false emits only the owner stream
+  - Skills: `terreno-backend-api`
+
+- [x] **Task 3.3**: Window subscribe — no snapshot, no full reconcile
+  - Delivers: admin clients subscribe to `{collection}|admin` (or `sync:subscribe` with window mode) and receive **cursor/ack only**, not a full snapshot; syncdb skips `reconcile()` for that collection while in window mode
+  - Files: `api/src/sync/socketHandlers.ts`, `syncdb/src/client.ts`, subscribe/bootstrap/reconcile modules, tests on both sides
+  - Blocked by: 3.2
+  - Acceptance: socket test: window subscribe does not emit snapshot pages; client test: reconcile interval does not GET `/sync/snapshot` for that collection
+  - Skills: `terreno-backend-api`
+
+- [x] **Task 3.4**: Hydrate known ids via REST + `GET /sync/entities`
+  - Delivers: helper used by admin UI (or syncdb window API) that given ids upserts entities; missing rows fetched from `/sync/entities`; RBAC: only admin-capable users may subscribe to `|admin`
+  - Files: `syncdb/src/sync/httpChannel.ts` (entities already), new window hydrate helper if needed, `api/src/sync/socketHandlers.ts` permission, tests
+  - Blocked by: 3.3, 1.5
+  - Acceptance: tests: hydrate 2 of 3 ids; unknown id ignored; non-admin subscribe to `|admin` nacks
+  - Skills: `terreno-backend-api`, `terreno-data-fetching`
+
+- [x] **Task 3.5**: Known-id-only deltas + Refresh contract
+  - Delivers: delta applier in window mode updates/deletes **existing local ids only**; new server rows do not appear until membership Refresh or load-more upserts them
+  - Files: `syncdb/src/sync/deltaApplier.ts`, tests
+  - Blocked by: 3.3
+  - Acceptance: tests: delta for unknown id is no-op; delta for known id updates store; delete delta removes known id; documented Refresh is a REST re-query + upsert (implemented in 4.x, contract tested here at applier)
+
+---
+
+## Phase 4 — Admin UI dual-run
+
+- [x] **Task 4.1**: `AdminModelTable` windowed path
+  - Delivers: when `syncDb` + fetch client present and model is String `_id` + synced + `adminBroadcast`, table membership from REST, rows from TinyBase, load more hydrates, Refresh control visible
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, tests
+  - Blocked by: 3.4, 3.5, 2.2, 1.7
+  - Acceptance: unit tests with fake syncdb: page ids render; extra delta id does not render; Refresh adds it; RTK path still used when `api` only
+  - Skills: `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 4.2**: `AdminModelForm` syncdb writes
+  - Delivers: create/update/delete for String `_id` synced models go through `useMutate`; ObjectId models stay fetch/RTK dual-run
+  - Files: `admin-frontend/src/AdminModelForm.tsx`, tests
+  - Blocked by: 4.1
+  - Acceptance: form save tests for both model classes; ObjectId never calls `useMutate`
+  - Skills: `terreno-ui`
+
+- [x] **Task 4.3**: ConflictSheet in admin
+  - Delivers: `useConflicts` + `ConflictSheet` (`useServer` / `keepMine`) for admin-loaded ids, same as example app
+  - Files: admin-frontend conflict host (table or shell), tests
+  - Blocked by: 4.2
+  - Acceptance: test: conflict row shows sheet; keepMine / useServer callbacks invoked
+  - Skills: `terreno-ui`
+
+- [x] **Task 4.4**: Bulk-patch stays fetch
+  - Delivers: existing bulk-patch still uses fetch/RTK dual-run (not sync mutate) with goldens from 1.5/1.6 still passing
+  - Files: table bulk actions wiring
+  - Blocked by: 2.3, 4.1
+  - Acceptance: bulk-patch tests still pass on both backends
+
+---
+
+## Phase 5 — Hosts
+
+- [x] **Task 5.1**: example-frontend `/admin`
+  - Delivers: `AdminProvider` gets fetch client (Bearer) + existing `syncDb`; example `Todo` `sync` sets `adminBroadcast: true`; `/admin` Todos changelist uses windowed path
+  - Files: `example-frontend` admin layout/store, `example-backend/src/api/todos.ts` (`adminBroadcast: true`)
+  - Blocked by: 4.3, 4.4
+  - Acceptance: `bun run backend:dev` + `frontend:web`; Playwright from 1.7 still passes; new assertions for Refresh optional
+  - Skills: `verify-ui-changes`, `generate-sdk` only if OpenAPI changed (should not)
+
+- [x] **Task 5.2**: admin-spa `/console`
+  - Delivers: same windowed Todos path with `credentials: "same-origin"`; SyncDbProvider in SPA; cookie session still logs in
+  - Files: `admin-spa` app providers, e2e
+  - Blocked by: 5.1
+  - Acceptance: SPA CRUD E2E from 1.7 passes with the new path; no Bearer required for same-origin
+  - Skills: `verify-ui-changes`
+
+---
+
+## Phase 6 — Docs, skills, deprecation
+
+- [x] **Task 6.1**: Human + agent docs
+  - Delivers: admin collection CRUD documented as windowed syncdb; RPC as fetch wrapper; `adminBroadcast` + window subscribe in syncdb reference; migrate-rtk guide no longer says admin collection CRUD stays RTK; `api`/`injectEndpoints` deprecated; next-major removal named; changelog
+  - Files: `docs/reference/syncdb.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/admin.md` / `admin-frontend` pages if present, `.rulesync/skills/terreno-data-fetching`, `verify-ui-changes` if admin login steps change, changelog
+  - Blocked by: 5.2
+  - Acceptance: `update-docs` checklist; `bun run skills:sync` if skill text changed; no remaining “keep admin on RTK” for **model CRUD**
+  - Skills: `update-docs`, `update-agent-docs`
+
+---
+
+## Task graph (Pick frontier)
+
+```
+1.1 1.2 1.4 1.5 1.6 1.7
+  └─ 1.3 (needs 1.1+1.2)
+
+2.1 ← 1.1
+2.2 ← 2.1
+2.3 ← 2.2, 1.6
+
+3.1 ← 1.5
+3.2 ← 3.1
+3.3 ← 3.2
+3.4 ← 3.3, 1.5
+3.5 ← 3.3
+
+4.1 ← 3.4, 3.5, 2.2, 1.7
+4.2 ← 4.1
+4.3 ← 4.2
+4.4 ← 2.3, 4.1
+
+5.1 ← 4.3, 4.4
+5.2 ← 5.1
+6.1 ← 5.2
+```
+
+First Pick after Approved: **Task 1.1** (and any other Phase 1 tasks with `Blocked by: none` as the frontier).

package/src/docs/versioned/next/tasks/migrate-cicd-to-circleci.md

@@ -15,7 +15,7 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
 ## Phase 0: Prerequisites
 
 - [ ] **Task 0.1**: Confirm CircleCI org/plan and project link
-  - Description: Verify the requester-created CircleCI organization, plan, and that `FlourishHealth/terreno` is connected with permission to report GitHub checks. Enable **dynamic config** / setup workflows for the project. Record org slug + project slug in the IP header or how-to doc.
+  - Description: Verify the requester-created CircleCI organization, plan, and that `TerrenoLabs/terreno` is connected with permission to report GitHub checks. Enable **dynamic config** / setup workflows for the project. Record org slug + project slug in the IP header or how-to doc.
   - Files: `docs/how-to/circleci.md` (stub OK)
   - Depends on: none (human prerequisite)
   - Acceptance: a manual “hello” pipeline can be triggered from the project; dynamic config is enabled.
@@ -178,7 +178,7 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Description: Port `maestro-e2e` (Chrome + xvfb against example-frontend, optional demo smokes) to CircleCI `node22_browsers_mongo_rs`. Appium Android remains separate.
   - Files: `.circleci/continue-config.yml`, `.circleci/config.yml`, `.github/workflows/maestro-e2e.yml`
   - Depends on: Task 5.2
-  - Acceptance: CircleCI `maestro-e2e` is the writer; GHA workflow is `on: []`.
+  - Acceptance: CircleCI `maestro-e2e` is the writer; GHA workflow is `push.branches-ignore: ["**"]`.
 
 - [ ] **Task 8.2**: Port Appium iOS on CircleCI macOS
   - Description: Select macOS resource class/image with Working WDA; port iOS job; compare flake rate to GHA `macos-15`.
@@ -207,7 +207,7 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Acceptance: each former workflow’s acceptance behavior has an owner on CircleCI; GHA files deleted.
 
 - [x] **Task 9.3a**: Port architectural PR review
-  - Description: CircleCI `architectural-pr-review` runs `.github/scripts/architectural-pr-review.ts` after checking out `origin/master`. Skips forks and missing `CURSOR_API_KEY` / `GITHUB_TOKEN`. GHA workflow is `on: []`.
+  - Description: CircleCI `architectural-pr-review` runs `.github/scripts/architectural-pr-review.ts` after checking out `origin/master`. Skips forks and missing `CURSOR_API_KEY` / `GITHUB_TOKEN`. GHA workflow is `push.branches-ignore: ["**"]`.
   - Files: `.circleci/continue-config.yml`, `.github/workflows/architectural-pr-review.yml`, `.github/scripts/architectural-pr-review.ts`
   - Depends on: Task 0.2
   - Acceptance: CircleCI job is the writer; Cursor Approval Agent stays on GitHub.