@terreno/mcp 57.20.0 → 57.22.0

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

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