@terreno/mcp 57.18.0 → 57.20.0

package/dist/docs/versioned/57.18.0/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/dist/docs/versioned/57.18.0/tasks/migrate-cicd-to-circleci.md

@@ -0,0 +1,236 @@
+# Task List: Migrate CI/CD to CircleCI
+
+See: [`docs/implementationPlans/migrate-cicd-to-circleci.md`](../implementationPlans/migrate-cicd-to-circleci.md)  
+Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../implementationPlans/migrate-cicd-to-circleci-research.md)
+
+## Instructions for the implementing agent
+
+- Dual-run every phase: CircleCI green → flip required checks → delete GHA twin. Never enable tag publish on both systems.
+- Do not store plaintext GCP JSON keys in CircleCI if OIDC is available; migrate `preview-cleanup` off `GCP_SA_KEY`.
+- Pin orb versions (including `circleci/node` with Bun support ≥7.2.0).
+- Prefer path parameters that mirror existing GHA path filters.
+- Update docs in the same PR that changes the source of truth for how CI runs.
+- After Phase 0, confirm CircleCI project follows the GitHub default branch `master`.
+
+## Phase 0: Prerequisites
+
+- [ ] **Task 0.1**: Confirm CircleCI org/plan and project link
+  - 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.
+  - Note: hello scaffold merged (#1052). Dynamic config + org slug still need maintainer confirmation.
+
+- [ ] **Task 0.2**: Create CircleCI Contexts (empty shells)
+  - Description: Create contexts named in the IP (`terreno-npm`, `terreno-netlify`, `terreno-expo`, `terreno-gcp`, `terreno-e2e`, `terreno-release`, `terreno-agentic`, `terreno-github-api`). Document which GitHub secrets map into each. Do not paste secret values into the repo.
+  - Files: `docs/how-to/circleci.md`
+  - Depends on: Task 0.1
+  - Acceptance: contexts exist; mapping table is complete; access restrictions noted for `terreno-release`.
+  - Note: mapping table documented in how-to; contexts themselves are still a human step.
+
+- [x] **Task 0.3**: Inventory required GitHub checks
+  - Description: List current branch-protection required checks and map each to the GHA job `name:` and the future CircleCI job name. Start from `docs/explanation/repository-settings.md` and live settings.
+  - Files: `docs/how-to/circleci.md` or a short table in the IP
+  - Depends on: none
+  - Acceptance: table covers policies, rulesync, package CI, fingerprint, and CD-related checks.
+
+## Phase 1: Foundation
+
+- [x] **Task 1.1**: Add setup + continue config skeleton
+  - Description: Create `.circleci/config.yml` with `setup: true` using `circleci/path-filtering` (and `circleci/continuation`). Create `.circleci/continue-config.yml` with parameters for each package/area and a no-op `config-ok` job that always runs.
+  - Files: `.circleci/config.yml`, `.circleci/continue-config.yml`
+  - Depends on: Task 0.1
+  - Acceptance: push triggers setup → continuation; `config-ok` is green.
+
+- [x] **Task 1.2**: Shared Bun + cache commands
+  - Description: Add reusable commands (inline or orb) for installing Bun via `circleci/node`, `bun install --frozen-lockfile`, and cache keys equivalent to today’s GHA bun cache. Pin Bun policy (`latest` vs pin) consistently with EAS jobs that need a pin.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 1.1
+  - Acceptance: a sample job restores cache on second run; install is frozen-lockfile.
+
+- [x] **Task 1.3**: Path-filter mapping
+  - Description: Encode path → parameter mapping for api, ai, ui, rtk, comms, mcp-server, admin-*, example-*, demo, docs/website, terraform, e2e-relevant sets, matching current workflow path filters.
+  - Files: `.circleci/config.yml`
+  - Depends on: Task 1.1
+  - Acceptance: a docs-only change sets docs/deploy params without setting `run-api`.
+  - Note: deploy path params omitted until Phase 4+.
+
+## Phase 2: Package CI + policy
+
+- [x] **Task 2.1**: Port package CI jobs
+  - Description: Port api/ai/rtk/ui/ui-demo/comms/mcp-server/example-frontend/example-backend(+script)/admin-spa CI to CircleCI jobs gated by path params. Include Mongo service where GHA used it. Fix mcp branch filter to `master`.
+  - Files: `.circleci/continue-config.yml`, possibly package scripts unchanged
+  - Depends on: Task 1.2, Task 1.3
+  - Acceptance: dual-run green for each package on a change that touches it; GHA still required.
+
+- [x] **Task 2.2**: Port Docker build-only job
+  - Description: Port `example-backend-docker.yml` to CircleCI remote Docker / machine with layer caching replacement for `type=gha`.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 2.1
+  - Acceptance: PR touching `example-backend/**` builds the image without pushing.
+
+- [x] **Task 2.3**: Port repo-policies + rulesync + DCO
+  - Description: Port `repo-policies.yml`, `rulesync-check.yml`, and fork DCO checks. DCO must use GitHub API via `terreno-github-api` context.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 0.2, Task 1.2
+  - Acceptance: intentional barrel-import / dirty rulesync / missing DCO on a fork PR fails the CircleCI job.
+  - Note: DCO skips cleanly if `GITHUB_TOKEN` unset until context is created.
+
+- [ ] **Task 2.4**: Dual-run cutover for Phase 2
+  - Description: Add CircleCI checks to branch protection; remove GHA package/policy workflows once trusted; delete corresponding `.github/workflows/*-ci.yml` and policy workflows.
+  - Files: `.github/workflows/*`, `docs/explanation/repository-settings.md`
+  - Depends on: Task 2.1, Task 2.2, Task 2.3
+  - Acceptance: required checks are CircleCI-only for these surfaces; GHA files gone.
+
+## Phase 3: Playwright E2E
+
+- [x] **Task 3.1**: Port `e2e-ci` and `admin-spa-integration`
+  - Description: Mongo replica set, E2E secrets context, Playwright browsers, artifact store for reports. Skip Dependabot-equivalent if applicable.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 2.1, Task 0.2
+  - Acceptance: matrix (or equivalent) passes on master; artifacts downloadable.
+
+- [ ] **Task 3.2**: Dual-run cutover for E2E
+  - Description: Flip required checks if any; delete GHA e2e/admin-spa-integration workflows.
+  - Files: `.github/workflows/e2e-ci.yml`, `admin-spa-integration.yml`, `admin-spa-ci.yml` as applicable
+  - Depends on: Task 3.1
+  - Acceptance: GHA twins deleted; CircleCI owns e2e.
+
+## Phase 4: Netlify deploys
+
+- [x] **Task 4.1**: Port demo / frontend-example / docs Netlify workflows
+  - Description: Build + `netlify-cli` deploy prod/preview; preserve alias naming (`pr-N`); recreate GitHub Deployment statuses via API if still desired.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 0.2, Task 1.3
+  - Acceptance: preview deploy URL posted or visible; prod deploy on master path filter.
+  - Note: CircleCI is the only Netlify deployer; jobs fail when `terreno-netlify` is empty. PR close triggers CircleCI `preview-cleanup` through `preview-cleanup.yml`.
+
+- [ ] **Task 4.2**: Preview cleanup port
+  - Description: On PR close, clean Netlify/GCP preview resources from CircleCI (webhook or GitHub App → pipeline). Prefer OIDC over `GCP_SA_KEY`.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 4.1
+  - Acceptance: closing a PR removes preview resources; no orphaned Cloud Run `pr-N` services in a test PR.
+  - Note: Cutover code landed on branch `move-cd-to-circleci` (GHA deploy workflows disabled; CircleCI deploy jobs fail on empty contexts). Check off after contexts are filled and the acceptance is observed.
+
+- [ ] **Task 4.3**: Dual-run cutover for Netlify
+  - Description: Delete GHA deploy workflows after CircleCI trusted.
+  - Files: `.github/workflows/demo-deploy.yml`, `frontend-example-deploy.yml`, `docs-deploy.yml`, `preview-cleanup.yml`
+  - Depends on: Task 4.1, Task 4.2
+  - Acceptance: GHA deploy twins deleted.
+  - Note: Cutover code landed on branch `move-cd-to-circleci` (GHA deploy workflows disabled; CircleCI deploy jobs fail on empty contexts). Check off after contexts are filled and the acceptance is observed.
+
+## Phase 5: EAS + fingerprint
+
+- [ ] **Task 5.1**: Relocate CI scripts
+  - Description: Move EAS/fingerprint shell scripts from `.github/workflows/scripts/` to `scripts/ci/` (or `.circleci/scripts/`) and update callers.
+  - Files: `scripts/ci/*`, old script paths
+  - Depends on: none
+  - Acceptance: scripts runnable locally with documented env; no broken references.
+
+- [ ] **Task 5.2**: Port eas-pr, eas-dev-build, fingerprint-gate
+  - Description: CircleCI jobs using `EXPO_TOKEN`; PR comments and label gate via GitHub API; manual pipeline for eas-dev-build.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 5.1, Task 0.2
+  - Acceptance: fingerprint change fails until `fingerprint-acknowledged`; EAS update/build path works on a test PR.
+
+- [ ] **Task 5.3**: Dual-run cutover for EAS
+  - Description: Delete GHA eas/fingerprint workflows after trust.
+  - Files: `.github/workflows/eas-pr.yml`, `eas-dev-build.yml`, `fingerprint-gate.yml`
+  - Depends on: Task 5.2
+  - Acceptance: GHA twins deleted; CircleCI checks required where fingerprint was required.
+
+## Phase 6: GCP CD + OIDC
+
+- [ ] **Task 6.1**: Add CircleCI OIDC provider in terraform
+  - Description: Extend or add module so GCP trusts CircleCI OIDC alongside GitHub during dual-run. Wire terreno terraform root; document outputs for CircleCI project settings.
+  - Files: `terraform/modules/**`, terreno/Flourish terraform roots, `terraform/README.md`
+  - Depends on: Task 0.1
+  - Acceptance: `gcloud` auth from a CircleCI job succeeds with WIF (no JSON key).
+
+- [x] **Task 6.2**: Port `cd.yml`
+  - Description: Path-filtered terraform fmt/preview/apply + Docker build/push + Cloud Run deploys + mcp-test/deploy. Preserve concurrency semantics (do not cancel in-flight prod applies).
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 6.1
+  - Acceptance: terraform preview on PR; apply+deploy on master for a safe test path; GitHub Deployment records optional but documented.
+  - Note: CircleCI is the only GCP deployer; jobs fail when `terreno-gcp` is empty. `gcp-cd-prod` runs MCP `test:ci` before the MCP deploy.
+
+- [ ] **Task 6.3**: Dual-run cutover for CD
+  - Description: Single deployer: disable GHA `cd.yml` when CircleCI CD is required; remove GitHub OIDC provider only after GHA CD is gone (or keep read-only if other repos need it — document).
+  - Files: `.github/workflows/cd.yml`, terraform OIDC
+  - Depends on: Task 6.2
+  - Acceptance: only CircleCI performs terreno CD; no double apply.
+  - Note: Cutover code landed on branch `move-cd-to-circleci` (GHA deploy workflows disabled; CircleCI deploy jobs fail on empty contexts). Check off after contexts are filled and the acceptance is observed.
+
+## Phase 7: npm publish
+
+- [ ] **Task 7.1**: Port publish-on-tag + manual feature-flags publish
+  - Description: Reproduce package publish graph, upgrade-docs gate, version bump, Zoom notify, demo dispatch, docs version cut. Use `terreno-release` + `terreno-npm` contexts.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 0.2, Task 2.1
+  - Acceptance: dry-run or package-by-package rehearsal documented; Zoom path tested against a sandbox webhook if available.
+
+- [ ] **Task 7.2**: Single-writer tag cutover
+  - Description: In one coordinated change: enable CircleCI tag pipeline; delete/disable `.github/workflows/publish-on-tag.yml` and manual GHA publish; verify no double publish.
+  - Files: `.github/workflows/publish-on-tag.yml`, `publish-feature-flags-manual.yml`
+  - Depends on: Task 7.1
+  - Acceptance: next tag publishes once from CircleCI only.
+
+## Phase 8: Mobile (post-v1, required for CC1)
+
+- [x] **Task 8.1**: Port Maestro web E2E
+  - 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 `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`.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 8.1
+  - Acceptance: iOS Appium green on a representative run; then delete GHA Appium workflow.
+
+- [ ] **Task 8.3**: Port Appium Android
+  - Description: Linux VM with emulator strategy documented.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 8.1
+  - Acceptance: Android Appium green on a representative run.
+
+## Phase 9: GitHub-native + agentic replacements
+
+- [ ] **Task 9.1**: Replace CodeQL workflow
+  - Description: Implement SARIF upload to GitHub Code Scanning from CircleCI or an approved SAST substitute; delete `codeql-analysis.yml` only when coverage is accepted.
+  - Files: `.circleci/continue-config.yml`, `.github/workflows/codeql-analysis.yml`
+  - Depends on: Task 0.2
+  - Acceptance: Security tab still receives results **or** explicit maintainer sign-off on alternative.
+
+- [ ] **Task 9.2**: Replace Dependabot auto-merge + triage + docs-audit (roadmap workflows stay on GitHub Actions, decided 2026-09-26)
+  - Description: Implement CircleCI (or Renovate) equivalents; wire issue/schedule triggers without leaving required logic on GHA.
+  - Files: `.circleci/continue-config.yml`, corresponding GHA deletions
+  - Depends on: Task 0.2
+  - 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 `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.
+
+- [ ] **Task 9.3b**: Replace remaining gh-aw agentics
+  - Description: Per lockfile (`update-rules`, `update-docs`, daily improvers) and `agentics-maintenance`: either port to CircleCI scheduled pipelines or retire with maintainer sign-off.
+  - Files: `.github/workflows/*lock*`, `agentics-maintenance.yml`, `.circleci/continue-config.yml`
+  - Depends on: Task 0.2
+  - Acceptance: written retire-or-port decision for each remaining lock workflow.
+
+## Phase 10: Cleanup
+
+- [ ] **Task 10.1**: Docs sweep
+  - Description: Update CONTRIBUTING, repository-settings, terraform README, deploy guides, AGENTS/Cursor Cloud CI notes to CircleCI-first. Remove stale GHA instructions.
+  - Files: `docs/**`, `CONTRIBUTING.md`, `AGENTS.md` / rules as needed
+  - Depends on: Phases 2–7 at minimum; 8–9 for full CC1
+  - Acceptance: `rg -n "GitHub Actions" docs/explanation/repository-settings.md` and deploy docs reflect CircleCI as source of truth.
+
+- [ ] **Task 10.2**: Final GHA workflow purge + IP close
+  - Description: Ensure `.github/workflows` has no CI/CD yml left (except intentionally empty dir or README). Set the IP `**Status:**` to Complete and archive the IP.
+  - Files: `.github/workflows/`, `docs/implementationPlans/migrate-cicd-to-circleci.md`
+  - Depends on: Task 9.3, Task 10.1, Task 8.2
+  - Acceptance: `ls .github/workflows/*.yml` is empty (or only an agreed stub); IP status Complete.

package/dist/docs/versioned/57.18.0/tasks/model-router-mcp.md

@@ -0,0 +1,105 @@
+# Tasks: modelRouter MCP Tools
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+---
+
+### Phase 1: Core MCP Infrastructure
+
+- [x] **Task 1.1**: Define MCP types and interfaces
+  - Description: Create `MCPConfig` interface (with `methods` defaulting to `['list', 'read']`, `excludeFields` for hiding sensitive fields, `maxLimit` defaulting to 50), `MCPRegistryEntry`, and add `mcp?: MCPConfig` to `ModelRouterOptions`. Create the `api/src/mcp/` directory structure.
+  - Files: `api/src/mcp/types.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (add mcp to ModelRouterOptions)
+  - Depends on: none
+  - Acceptance: Types compile, existing tests still pass, `mcp` is an optional field on `ModelRouterOptions`
+
+- [x] **Task 1.2**: Build MCP tool registry
+  - Description: Create a global registry that collects MCP tool entries as `modelRouter()` is called. When a modelRouter has `mcp` config, it pushes an entry to the registry. Export `getMCPRegistry()` from `@terreno/api`. Vercel AI SDK wrapping lives in `getMCPTools()` on `@terreno/ai`.
+  - Files: `api/src/mcp/registry.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (register in modelRouter function)
+  - Depends on: Task 1.1
+  - Acceptance: Calling `modelRouter(Todo, { ..., mcp: { methods: ['list', 'read'] } })` adds entries to the registry. `getMCPRegistry()` returns those entries.
+
+- [x] **Task 1.3**: Generate Zod schemas from Mongoose models
+  - Description: Build a utility that converts a Mongoose model's schema into Zod schemas suitable for MCP tool `inputSchema`. Handle common field types (String, Number, Boolean, Date, ObjectId, Array, Mixed). Generate separate schemas for create (required fields), update (all optional + id required), read (id + optional populate), list (queryFields + pagination), and delete (id only). Respect `excludeFields` — omit listed fields from all generated schemas.
+  - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
+  - Depends on: Task 1.1
+  - Acceptance: Given a Mongoose model, produces valid Zod schemas for each CRUD method. Tests cover all common field types. `excludeFields` removes specified fields from schemas.
+
+- [x] **Task 1.4**: Generate MCP tool definitions from registry entries
+  - Description: Build tool generator that takes an `MCPRegistryEntry` and produces both `@modelcontextprotocol/sdk` `Tool` objects (JSON Schema input) and Vercel AI SDK (`ai`) `CoreTool` objects. Auto-generate descriptions from model name, fields, and queryFields. Apply `toolPrefix` naming (`{prefix}_{method}`). Only generate tools for methods listed in `mcp.methods`.
+  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
+  - Depends on: Task 1.2, Task 1.3
+  - Acceptance: Registry entry with `methods: ['list', 'read']` produces exactly `todos_list` and `todos_read` tools with correct schemas and descriptions.
+
+- [x] **Task 1.5**: Implement MCP tool handlers (CRUD execution)
+  - Description: Build the execute functions for each CRUD tool. Each handler: (1) extracts user from auth context, (2) checks permissions via `checkPermissions()`, (3) for read/update/delete: loads document and checks object-level permissions, (4) applies queryFilter and population for list, (5) enforces `maxLimit` cap on list results (default 50), (6) runs pre/post hooks, (7) strips `excludeFields` from response data, (8) serializes via `mcpResponseHandler` or default. Reuse internal logic from REST handlers but decoupled from Express req/res.
+  - Files: `api/src/mcp/handlers.ts`, `api/src/mcp/handlers.test.ts`
+  - Depends on: Task 1.4
+  - Acceptance: Each CRUD handler works with correct permission checks, population, filtering. List enforces maxLimit. excludeFields are stripped from responses. Tests cover: successful CRUD, permission denied (403), not found (404), validation errors, owner filtering, population, maxLimit enforcement, excludeFields stripping.
+
+- [x] **Task 1.6**: Auth-agnostic user extraction for MCP
+  - Description: Build middleware/utility that extracts user from MCP transport headers using whichever auth provider is configured (JWT via passport or Better Auth via `auth.api.getSession()`). Should mirror `authenticateMiddleware` behavior but work with raw headers instead of Express req.
+  - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`
+  - Depends on: Task 1.1
+  - Acceptance: Given headers with a valid JWT, returns User. Given headers with a valid Better Auth session token, returns User. Given no/invalid headers with `allowAnonymous: false`, returns null. Works with both auth providers.
+
+- [x] **Task 1.7**: Mount MCP server in TerrenoApp
+  - Description: In `TerrenoApp`'s startup flow, check if the MCP registry has any entries. If so, create an `McpServer` instance from `@modelcontextprotocol/sdk`, register all tools from the registry, set up `StreamableHTTPServerTransport`, and mount on `/mcp`. Wire up `ListToolsRequestSchema` and `CallToolRequestSchema` handlers.
+  - Files: `api/src/mcp/server.ts`, `api/src/expressServer.ts` (or TerrenoApp equivalent — integrate into startup)
+  - Depends on: Task 1.4, Task 1.5, Task 1.6
+  - Acceptance: Starting a TerrenoApp with MCP-configured models auto-mounts `/mcp`. MCP clients can list tools and call them. No MCP config = no `/mcp` endpoint.
+
+- [x] **Task 1.8**: Integration tests
+  - Description: End-to-end tests that spin up a TerrenoApp with MCP-configured models and test the full flow: MCP client connects, lists tools, performs CRUD via tool calls, verifies permissions block unauthorized access, verifies population and query filtering work.
+  - Files: `api/src/mcp/integration.test.ts`
+  - Depends on: Task 1.7
+  - Acceptance: Full CRUD lifecycle works over MCP. Permission denials return appropriate errors. Owner filtering restricts results. Population returns nested data.
+
+- [x] **Task 1.9**: Export public API
+  - Description: Export `MCPConfig` and MCP registry/server helpers from `@terreno/api`. Export `getMCPTools()` from `@terreno/ai` so the Vercel AI SDK (`ai`) stays out of `@terreno/api`.
+  - Files: `api/src/index.ts`, `ai/src/index.ts`, `ai/src/service/getMCPTools.ts`
+  - Depends on: Task 1.7
+  - Acceptance: Consumers can `import { MCPConfig } from "@terreno/api"` and `import { getMCPTools } from "@terreno/ai"`.
+
+---
+
+### Phase 2: Frontend Integration
+
+- [x] **Task 2.1**: `useTerrenoChat` hook
+  - Description: Create a hook wrapping `@ai-sdk/react`'s `useChat()` pre-configured for a Terreno MCP backend. Handles Bearer token injection from auth state (reads from Redux store — JWT token or Better Auth session). Accepts `baseURL` and optional `tools` override.
+  - Files: `rtk/src/useTerrenoChat.ts`
+  - Depends on: Task 1.7
+  - Acceptance: Hook connects to MCP-enabled backend, streams responses with tool calls, injects auth token automatically.
+
+- [x] **Task 2.2**: `useMCPTools` hook
+  - Description: Create a hook that discovers available MCP tools from the backend via JSON-RPC call to /mcp endpoint. Caches result. Returns typed tool list.
+  - Files: `rtk/src/useMCPTools.ts`
+  - Depends on: Task 1.7
+  - Acceptance: Hook returns list of available tools with names, descriptions, and input schemas. Handles connection errors gracefully.
+
+- [x] **Task 2.3**: Export frontend public API
+  - Description: Export `useTerrenoChat` and `useMCPTools` from `@terreno/rtk`. Add `@ai-sdk/react` and `ai` as dependencies.
+  - Files: `rtk/src/index.ts`, `rtk/package.json`
+  - Depends on: Task 2.1, Task 2.2
+  - Acceptance: Consumers can `import { useTerrenoChat, useMCPTools } from "@terreno/rtk"`.
+
+---
+
+### Phase 3: Examples & Polish
+
+- [x] **Task 3.1**: Add MCP config to example backend models
+  - Description: Add `mcp` config to the existing Todo and User models in `example-backend`. Todos: read-only (`list`, `read`) with excludeFields. Users: read-only (`list`, `read`) with sensitive fields excluded.
+  - Files: `example-backend/src/api/todos.ts`, `example-backend/src/api/users.ts`
+  - Depends on: Task 1.9
+  - Acceptance: Starting example-backend mounts `/mcp` with todo and user tools. MCP client can list and call them.
+
+- [x] **Task 3.2**: Demo chat screen in example frontend
+  - Description: Add a simple chat screen to `example-frontend` that uses `useTerrenoChat()` to connect to the MCP-enabled backend. Show tool calls inline (e.g., "Searching todos..." with results). Navigation from home screen.
+  - Files: `example-frontend/app/chat.tsx`, `example-frontend/app/_layout.tsx` (add nav)
+  - Depends on: Task 2.3, Task 3.1
+  - Acceptance: User can chat with the AI, which calls MCP tools to query/modify data. Tool calls and results visible in the UI.
+
+- [x] **Task 3.3**: Refine auto-generated tool descriptions
+  - Description: Improve description generation quality. Include field types, required vs optional, enum values, ref model names. Test with multiple model shapes to ensure descriptions are helpful for LLMs.
+  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
+  - Depends on: Task 1.4
+  - Acceptance: Descriptions include actionable detail. LLM can understand what each tool does and what inputs are expected without additional context.