@terreno/mcp 57.17.0 → 57.19.2

package/src/docs/versioned/57.18.0/implementationPlans/migrate-admin-to-syncdb.md

@@ -0,0 +1,211 @@
+# Implementation Plan: Migrate built-in admin to syncdb
+
+**Status:** Complete
+**Roadmap:** Area=`admin`, Target=`Released`, Impact=`Improvement`  
+**Branch:** `cursor/migrate-admin-to-syncdb-de61`
+**Owner:** Josh Gachnang
+**Created:** 2026-09-01
+**Grow run:** https://cursor.com/agents/bc-47350376-6566-4c5a-aee2-e6a28698de61
+
+## Goal
+
+Move **built-in admin model list/read/create/update/delete** for collections that already use **String `_id`** onto **windowed local-first syncdb**, with **REST remaining the membership source** (search, sort, pagination, RBAC). Remaining admin RPC (config, scripts, roles, comms, AI, consent, documents, version-config, background-tasks) leaves RTK `injectEndpoints` for a **tiny native `fetch` wrapper** with **host-injected auth**.
+
+Ship **great characterization coverage and CI first**, then protocol, then UI, then hosts. Dual-run RTK `api` for one release so existing hosts keep working; **deprecate `api` / `injectEndpoints` in docs in this IP**; **delete the inject path in the next Terreno major**.
+
+## Non-Goals
+
+- Migrating ObjectId `_id` models (`User`, `AdminAuditLog`, and any other ObjectId collection) onto syncdb. Those stay **fetch CRUD**. No schema migration in this IP.
+- Axios. Admin HTTP uses native `fetch` plus a small wrapper.
+- Full-stream `reconcile()` for admin collections. Admin subscribe is **window mode**: no snapshot of the entire owner/tenant/broadcast stream.
+- A second `sync:` registration on the admin `modelRouter`. One sync registration per model stays on the **app** router (`/todos`, not `/admin/todos`).
+- Changing app-user collections to broadcast. Users keep owner/tenant streams; admin is an extra fan-in (`adminBroadcast`).
+- Removing `injectEndpoints` in this release (next major).
+- Replacing generated OpenAPI SDK, Better Auth Redux, or feature-flag RTK with syncdb.
+
+## Decisions
+
+| # | Question | Decision |
+| --- | --- | --- |
+| Q1 | What data plane does admin use? | String-`_id` **model CRUD** → **syncdb** (windowed). Remaining admin **RPC is not RTK**; dedicated **fetch** hooks. |
+| Q2 | Coverage-first? | **A:** ≥95% line+function on admin packages; **fix CI coverage scope**; add embedded + SPA CRUD E2E **before** behavior migration. |
+| Q3 | HTTP client | Native **`fetch` + tiny wrapper** (AbortController timeout, credentials, JSON/FormData, `APIError`). **No axios**. |
+| Q4 | Auth injection | Host injects `{baseUrl, getAuthHeaders, credentials}`. SPA: `credentials: "same-origin"`. Embedded: Bearer. |
+| Q5 | Local-first shape | **Windowed local-first:** load more hydrates more; keep loaded rows synced. |
+| Q6 | Which models? | **B:** Sync only models that already have **String `_id`**. ObjectId models stay fetch CRUD. |
+| Q7 | RTK dual-run | **B:** Dual-run **this release** (`api` still works). Delete RTK inject path **next major**. |
+| Q8 | List membership vs store | **A:** REST list/search/sort/RBAC stays **membership**. Pages **upsert** into TinyBase. Writes + per-id via syncdb. **Full-stream reconcile OFF** for admin collections. |
+| Q9 | Deltas vs new matches | **A + Refresh:** deltas **update/delete known ids only**. New matches via load-more or **visible Refresh**. No surprise inserts. |
+| Q10 | Owner streams? | Admin needs a **cross-owner** view. Not the signed-in admin's owner stream. |
+| Q11 | Dual-run vs cutover | Land **both** in this IP. **Deprecate `api` in docs now**. Remove `injectEndpoints` **next Terreno major**. |
+| Q12 | Conflicts | **`ConflictSheet`** (`useServer` / `keepMine`) like the example app. |
+| Q13 | Fan-in | **`adminBroadcast: true`** on the **existing** collection `SyncConfig`. Deltas also to `{collection}\|admin`. Admin clients join in **window** mode: no full snapshot/reconcile; hydrate via REST ids + `GET /sync/entities`. |
+
+## Architecture
+
+### Today
+
+Admin CRUD is **RTK `injectEndpoints`** in `@terreno/admin-frontend` (`useAdminApi.ts` → `GET/POST/PATCH/DELETE /admin/{routePath}` plus bulk-patch). Config and other RPC are more inject hooks (`useAdminConfig`, scripts, roles, configuration, documents, comms, AI explorer, consent, version-config, background-tasks).
+
+The backend mounts a **separate** `modelRouter` under `/admin/...` **without** `sync:`. Example `Todo` is already synced on the **app** router (`example-backend/src/api/todos.ts`) with String `_id` + `syncPlugin`. Same Mongo model, different mount. Registry allows **one sync registration per model**; a second `sync` on the admin router is forbidden (`api/src/sync/registrationSideEffects.ts`).
+
+Canonical docs still say profile/admin stay on RTK (`docs/how-to/migrate-rtk-to-syncdb.md`).
+
+### Target data planes
+
+| Surface | After this IP | Auth |
+| --- | --- | --- |
+| String-`_id` model changelist + form | REST membership + TinyBase rows + `{collection}\|admin` window subscribe | Host-injected (cookie or Bearer) via fetch for REST; existing sync socket auth for deltas/mutate |
+| ObjectId model changelist + form | Fetch CRUD only (same `/admin/{routePath}` URLs) | Same fetch wrapper |
+| Admin RPC (config, scripts, roles, comms, …) | Fetch hooks; **not** RTK | Same fetch wrapper |
+| Host RTK `api` | Still accepted; dual-run. Deprecated in docs | Unchanged |
+
+### Windowed local-first (String `_id`)
+
+1. **Membership:** `GET /admin/{routePath}` (existing list/search/sort/RBAC) returns the **page of ids** (and enough fields to render immediately).
+2. **Hydrate:** those ids **upsert** into TinyBase. Missing entities come from `GET /sync/entities` (already exists) when the list payload is incomplete for sync seq / tombstones.
+3. **Subscribe:** admin client joins collection stream `{collection}|admin` in **window** mode. Socket handlers must **not** send a full snapshot or trigger client `reconcile()` of the whole user stream.
+4. **Deltas:** apply **update/delete only if the id is already in the local window**. Unknown ids are ignored (no surprise inserts).
+5. **Load more / Refresh:** load more requests the next REST page and hydrates those ids. **Refresh** re-runs the current REST query and upserts/removes to match membership (visible control).
+6. **Writes:** `useMutate` / `POST /sync/mutate` (same write path as the app) plus admin REST bulk-patch remaining on fetch until a later IP if bulk is not a sync mutation.
+
+Do **not** set collection `scope` to broadcast for the app. App clients keep owner/tenant streams. `adminBroadcast: true` is an **additive fan-in**: change-stream emit also publishes to `{collection}|admin`. Only clients that subscribe in admin window mode join that stream.
+
+### Why not a second sync registration
+
+`registerSync` throws if the model is already registered. Admin REST stays the **admin RBAC/list** surface. Sync stays on the **app** collection registration. Admin UI does not invent a second TinyBase table name; it uses the same collection tag as the app (`todos`), with an admin stream suffix.
+
+### Fetch wrapper
+
+New module in `@terreno/admin-frontend` (not axios, not `emptyApi` JWT refresh). Responsibilities:
+
+- `AbortController` timeout
+- `credentials` (`same-origin` for SPA cookies; `omit`/`include` as injected)
+- `getAuthHeaders()` for Bearer (embedded)
+- JSON body by default; `FormData` passthrough
+- Map non-2xx to `APIError` shape admin already understands
+
+Hosts pass `{baseUrl, getAuthHeaders, credentials}` into `AdminProvider` / existing admin context. SPA must keep cookie session working; embedded example-frontend must keep Bearer.
+
+### Dual-run
+
+`AdminModelTable` / `AdminModelForm` / related hooks:
+
+- If `syncDb` + `adminRequest` (fetch client) are present **and** the model is String `_id` + registered for sync with `adminBroadcast`, use the new path.
+- Else existing `useAdminApi(api, …)` RTK path.
+
+No host is forced to pass `syncDb` this release. Docs tell new/updated hosts to inject both.
+
+### Conflicts
+
+Same `ConflictSheet` as the example app: `useServer` / `keepMine`. Admin window does not invent a second conflict UX.
+
+## Models
+
+No new Mongo models. No `_id` type changes.
+
+| Model (example) | `_id` | This IP |
+| --- | --- | --- |
+| `Todo` | String | Tracer: windowed syncdb + adminBroadcast |
+| Other app models already String `_id` + `sync` | String | Same pattern once `adminBroadcast: true` |
+| `User`, `AdminAuditLog`, other ObjectId | ObjectId | Fetch CRUD only |
+
+`SyncConfig` gains:
+
+```ts
+adminBroadcast?: boolean;
+```
+
+Default `false`. When `true`, emitters also send deltas to `{collection}|admin`. Permission to join that stream is **admin-only** (reuse existing admin permission checks used by `/admin/*`, not owner-stream membership).
+
+## APIs
+
+### Additive protocol
+
+| Piece | Change |
+| --- | --- |
+| `SyncConfig.adminBroadcast` | Opt-in fan-in to `{collection}\|admin` |
+| `sync:subscribe` | Accept window/admin mode (exact payload field named in Pick; suggested `{mode: "window"}` or subscribe to `{tag}\|admin` without snapshot) |
+| `sync:subscribed` | Must not dump full stream snapshot for window subscribers |
+| `GET /sync/entities` | Hydrate known ids (already exists; pin tests) |
+| `GET /admin/{routePath}` | Unchanged membership/search/RBAC |
+| `POST /sync/mutate` | Writes for String `_id` synced models (already exists) |
+
+### Unchanged REST (still used)
+
+- `GET /admin/config`
+- `/admin/{routePath}` list/read/create/update/delete/bulk-patch (membership + ObjectId CRUD + bulk)
+- `/rbac/*`, scripts, configuration, documents, comms, AI, consent, version-config, background-tasks
+
+## Notifications
+
+None. No user-facing comms templates.
+
+## UI
+
+- **Changelist (`AdminModelTable`):** windowed rows from TinyBase for String `_id` synced models; REST pagination/search/sort unchanged; **Refresh** control; load more hydrates more ids; no rows appearing that were not in the last membership set.
+- **Form (`AdminModelForm`):** read/write via syncdb for those models; ObjectId stays fetch.
+- **Conflicts:** `ConflictSheet` when `useConflicts` reports for admin-loaded ids.
+- **Hosts:** `example-frontend` `/admin` and `admin-spa` `/console` both wired for the tracer.
+- Admin v2 `home.slots` unchanged.
+
+## Phases
+
+1. **Characterization + CI** — raise coverage, fix LCOV scope, add package CI jobs, pin URL goldens, add CRUD E2E. **No product behavior change.**
+2. **Fetch wrapper** — client + host injection; migrate RPC inject hooks onto fetch (dual-run until hosts pass the wrapper).
+3. **Protocol** — `adminBroadcast`, `{collection}|admin` emit, window subscribe, skip reconcile, known-id delta apply, entity hydrate tests.
+4. **Admin UI dual-run** — table/form/ConflictSheet/Refresh; ObjectId stays fetch.
+5. **Hosts** — example-frontend + admin-spa; cookie vs Bearer must both work.
+6. **Docs/skills** — stop saying admin collection CRUD stays RTK; deprecate `api` inject; changelog.
+
+Phase 1 is a **hard gate**. Protocol/UI tasks are blocked until Phase 1 acceptance is green.
+
+## Feature Flags & Migrations
+
+No feature flag. `adminBroadcast` is explicit per collection. Hosts opt into the new UI path by passing `syncDb` + fetch client.
+
+**Deprecation:** this release documents “do not add new `injectEndpoints` in admin-frontend.” Next major deletes `useAdminApi` RTK inject and the `api` prop requirement.
+
+## Activity Log & User Updates
+
+No end-user product changelog beyond admin operators. Framework changelog records protocol + deprecation.
+
+## Not Included / Future Work
+
+- ObjectId → String `_id` + `syncPlugin` for User / audit log (own IP; mongoose-schema-safety).
+- Delete RTK inject (next major).
+- Bulk-patch as sync mutations.
+- Admin-only collections with no app router (would still need one `sync:` registration, not a duplicate).
+
+## Files to Create / Modify
+
+**Phase 1:** `admin-frontend/**/*.test.*`, `admin-frontend/bunfig.toml`, `admin-backend` coverage config, `.circleci/continue-config.yml`, root `package.json` (`admin-frontend:test`), `example-frontend/e2e/admin*.spec.ts`, `admin-spa/e2e/**`.
+
+**Phase 2:** `admin-frontend/src/adminRequest.ts` (name at Pick), host context types, RPC hooks listed under Architecture.
+
+**Phase 3:** `api/src/sync/types.ts`, `streams.ts`, change-stream emit, `socketHandlers.ts`, `syncdb/src/client.ts` + subscribe/reconcile/delta applier, tests in `api/src/sync/*.test.ts` and `syncdb/src/sync/*.test.ts`.
+
+**Phase 4:** `AdminModelTable`, `AdminModelForm`, conflict wiring, `useAdminApi` dual-run.
+
+**Phase 5:** `example-frontend` store/syncdb + admin layout; `admin-spa` session fetch + SyncDbProvider.
+
+**Phase 6:** `docs/reference/admin-*.md`, `docs/reference/syncdb.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/admin-frontend.md` (if present), `terreno-data-fetching` skill (admin fetch exception), `verify-ui-changes`, changelog.
+
+## Task List
+
+[docs/tasks/migrate-admin-to-syncdb.md](../tasks/migrate-admin-to-syncdb.md)
+
+## Acceptance Criteria
+
+- [ ] `admin-frontend` and `admin-backend` report ≥95% line and function coverage on **package source** (not `@terreno/test/dist`). CircleCI runs both package jobs.
+- [ ] Embedded `/admin` and SPA `/console` have CRUD E2E for Todos (list, create, edit, delete, search/filter, bulk where already specified) **before** protocol/UI cutover, and they still pass after cutover.
+- [ ] Example **Todos** admin changelist is windowed local-first: REST membership, TinyBase rows, `{todos}|admin` deltas update known ids only, Refresh/load-more add membership, ConflictSheet works.
+- [ ] ObjectId models still CRUD via fetch; no `_id` migration.
+- [ ] SPA cookie auth and embedded Bearer auth both work; no axios in the new client.
+- [ ] Hosts that still pass only `api` keep working (dual-run).
+- [ ] Docs and skills no longer tell agents to keep admin **collection CRUD** on RTK; `api`/`injectEndpoints` marked deprecated; next-major removal called out.
+- [ ] `bun run lint` and focused package tests pass; `verify-ui-changes` for `/admin` and `/console` tracer.
+
+## Tracer
+
+Example **Todos** admin changelist: `example-frontend` `/admin` and `admin-spa` `/console`.

package/src/docs/versioned/57.18.0/implementationPlans/migrate-cicd-to-circleci-research.md

@@ -0,0 +1,127 @@
+# Research: Migrate CI/CD to CircleCI
+
+**Status:** Research complete — decisions recorded in IP `migrate-cicd-to-circleci.md`  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1088
+**Date:** 2026-08-17  
+**Repo:** TerrenoLabs/terreno (`master` @ `1e3e79a6`)  
+**Branch:** `cursor/migrate-cicd-circleci-2b6d`
+
+## Scope statement
+
+Investigate what “migrate all CI/CD to CircleCI” means for Terreno: inventory every GitHub Actions workflow, classify what is portable vs GitHub-native, map secrets/OIDC/deploy targets, and surface **candidate** CircleCI architectures with tradeoffs. No implementation decisions are committed here.
+
+## Current state (findings)
+
+### Scale
+
+- **~36** hand-maintained `.github/workflows/*.yml` workflows
+- **4** agentic `*.lock.yml` pipelines (gh-aw / Copilot), compiled from `.md` sources
+- **No** `.circleci/` today
+- **No** `.github/actions/` composites — Bun setup + cache is copy-pasted per workflow
+- Helper scripts live under `.github/workflows/scripts/` (EAS/fingerprint) and `.github/scripts/`
+
+### Category inventory
+
+| Category | Examples | CircleCI portability |
+|----------|----------|----------------------|
+| Package CI | `api-ci`, `ui-ci`, `rtk-ci`, `ai-ci`, `comms-ci`, `mcp-server-ci`, example-* | High |
+| Web E2E | `e2e-ci`, `admin-spa-ci`, `admin-spa-integration` (Playwright + Mongo) | High–medium |
+| Mobile E2E | `demo-appium-ci` (Android + macos-15 iOS), `maestro-e2e` | Medium–low (macOS/Android emulator parity) |
+| Expo/EAS | `eas-pr`, `eas-dev-build`, `fingerprint-gate` | Medium (CLI portable; PR labels/comments GitHub-centric) |
+| Deploy GCP | `cd.yml`, `preview-cleanup` | Medium–hard (OIDC is GitHub-issuer only today) |
+| Deploy Netlify | `demo-deploy`, `frontend-example-deploy`, `docs-deploy` | High–medium |
+| Publish | `publish-on-tag`, `publish-feature-flags-manual` | Medium–hard (token push to master, Zoom, cross-workflow dispatch) |
+| Policy | `repo-policies`, `rulesync-check`, `dco` | High (DCO is GitHub-PR metadata) |
+| Security | `codeql-analysis` | Low (GitHub Code Scanning / Security tab) |
+| GitHub-native | `dependabot-auto-merge`, `triage`, `roadmap-generate` | Low–none |
+| Agentic | `architectural-pr-review`, `agentics-maintenance`, `*.lock.yml` | None (gh-aw, `pull_request_target`, Copilot) |
+
+### Shared CI patterns
+
+1. `oven-sh/setup-bun@v2` (`bun-version: latest`, sometimes pinned `1.4.0` for EAS)
+2. `actions/cache` on `~/.bun/install/cache` keyed by OS + ref + lockfile
+3. `bun install --frozen-lockfile` then package `lint` / `compile` / `test(:coverage|:ci)`
+4. Mongo via `supercharge/mongodb-github-action` (image `mirror.gcr.io/library/mongo`) for api/ai/example-backend/e2e
+5. Most package CI is **`on: push` with path filters**, not `pull_request` — checks appear when the PR head branch is pushed
+6. Path filtering also uses `dorny/paths-filter` inside larger workflows (`cd.yml`, deploys)
+
+### Deploy / release targets
+
+| Target | Mechanism |
+|--------|-----------|
+| GCP `flourish-terreno` | Cloud Run (backend, tasks, mcp), Artifact Registry, Infra Manager terraform |
+| Auth to GCP | Workload Identity Federation — issuer `https://token.actions.githubusercontent.com` (`terraform/modules/github_oidc`) |
+| Preview cleanup | Still uses `GCP_SA_KEY` JSON (not WIF) |
+| Netlify | demo, example-frontend, docs sites via `nwtgck/actions-netlify` |
+| npm | Tag-driven publish of ~12 `@terreno/*` packages |
+| EAS Cloud | PR updates/builds + manual workflow dispatch |
+| GitHub Deployments API | CD + Netlify preview environments |
+
+### Secrets / vars (union, migration-relevant)
+
+**Secrets:** `NPM_TOKEN`, `EXPO_TOKEN`, `NETLIFY_*`, `GCP_SA_KEY`, `MCP_SENTRY_DSN`, `E2E_*`, `CURSOR_API_KEY`, `REPO_ADMIN_TOKEN`, `ROADMAP_PROJECT_TOKEN`, `ZOOM_WEBHOOK_*`, plus gh-aw Copilot tokens on lockfiles.
+
+**Vars:** `GCP_WIF_PROVIDER_PROD`, `GCP_TF_ADMIN_SA_PROD`, `GCP_CD_DEPLOYER_SA_PROD`, `GCP_TF_PROJECT_ID_PROD`, `GCP_INFRA_MANAGER_LOCATION`, `ARCHITECTURAL_REVIEW_MODEL`, `TERRENO_PROJECT_NUMBER`.
+
+### Branch protection (documented)
+
+`docs/explanation/repository-settings.md`: require status checks including **Repository policies**, **package CI**, and **Rulesync Check** relevant to the change. Path-filtered checks are not always present — any CircleCI cutover must remap required checks carefully.
+
+### External / CircleCI platform notes
+
+- Official migration guide: map Actions → CircleCI jobs/workflows; Actions Marketplace ≈ Orb Registry ([CircleCI migrate from GitHub](https://circleci.com/docs/guides/migrate/migrating-from-github/)).
+- Monorepo best practice: **dynamic config** (`setup: true`) + **path-filtering** orb so only affected packages run ([2026 monorepo guidance](https://www.devopsness.com/blog/circleci-best-practices-2026-07-19)).
+- `circleci/node` orb **≥7.2.0** has first-class Bun (`install-bun`, frozen lockfile, cache) ([node-orb Bun support](https://github.com/oven-sh/bun/discussions/22830)).
+- GCP OIDC from CircleCI is supported but requires a **new** Workload Identity provider (not a drop-in for the current GitHub-only module).
+
+## Candidate options (not chosen)
+
+### A. Full cutover (literal “all”)
+
+Move every runnable pipeline to CircleCI; disable GHA workflows.
+
+- **Pros:** Single CI vendor; one secrets home; one config language.
+- **Cons:** Breaks CodeQL Security tab, Dependabot auto-merge, gh-aw agentic bots, issue triage, roadmap generate, `pull_request_target` review, GitHub Deployments UX unless reimplemented via API. Highest risk and cost.
+
+### B. Hybrid “CI/CD on CircleCI, GitHub stays for GitHub-native”
+
+Move package CI, E2E, Netlify, GCP CD, EAS triggers, publish to CircleCI. Keep CodeQL, Dependabot, DCO/triage/roadmap, and all gh-aw agentic workflows on GitHub Actions.
+
+- **Pros:** Matches “migrate CI/CD” intent without destroying OSS/agentic GitHub integrations; clear ownership split.
+- **Cons:** Two systems forever; dual required-check configuration; doc/contrib complexity.
+
+### C. Phased hybrid with long dual-run
+
+Same end-state as B, but phases: (1) mirror package CI, (2) Netlify, (3) EAS/fingerprint, (4) GCP OIDC + CD, (5) publish last. GHA remains required until each phase proves green.
+
+- **Pros:** Lowest blast radius; easy rollback; validates CircleCI org/contexts/credits before cutting release path.
+- **Cons:** Temporary double spend; longer calendar; discipline needed to delete GHA when done.
+
+### D. CircleCI for compute-heavy only; keep CD/publish on GHA
+
+Only migrate lint/test/Playwright/Appium; leave `cd.yml` + `publish-on-tag.yml` on Actions.
+
+- **Pros:** Avoids OIDC rewrite and release double-publish risk; still reduces GHA minute pressure if that is the pain.
+- **Cons:** Does not fulfill “all CI/CD”; two systems for the most critical paths.
+
+## Recommended research framing (for questions, not a plan decision)
+
+Option **C** is the lowest-risk path that still delivers a real CircleCI CD home; Option **A** is only viable if product/security accepts losing or re-homing GitHub-native surfaces. Option **D** is a scope cut, not a full migration.
+
+## Open questions (fed into Step 3)
+
+1. Literal “all” vs hybrid (what stays on GitHub)?
+2. Dual-run duration and when GHA workflows are deleted?
+3. CircleCI org/project already exist? Free vs Performance plan? Credit budget?
+4. In-scope: GCP CD + npm publish in v1, or defer?
+5. macOS Appium iOS — CircleCI macOS resource class vs keep on GHA?
+6. Who owns secrets migration and branch-protection remapping?
+7. Roadmap tracking issue after Approved?
+
+## References
+
+- Inventory of workflows: `.github/workflows/`
+- GCP OIDC: `terraform/modules/github_oidc/`
+- Deploy docs: `docs/explanation/deployment-architecture-gcp.md`, `terraform/README.md`
+- Branch protection: `docs/explanation/repository-settings.md`
+- CircleCI: [Migrating from GitHub](https://circleci.com/docs/guides/migrate/migrating-from-github/), node orb Bun support

package/src/docs/versioned/57.18.0/implementationPlans/migrate-cicd-to-circleci.md

@@ -0,0 +1,288 @@
+# Implementation Plan: Migrate CI/CD to CircleCI
+
+**Status:** In progress — CI, release, Netlify/GCP production path deploys, and PR previews landed; EAS PR/fingerprint temporarily disabled; GitHub-native maintenance remains  
+**Discussion:** _(none)_  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1088
+**Linear:** _(none)_  
+**Priority:** High  
+**Effort:** Large (cross-cutting infra; many workflows)  
+**Owner:** unassigned (CircleCI org/plan: requester)  
+**Created:** 2026-08-17  
+**Branch:** `cursor/migrate-cicd-circleci-2b6d`  
+**Research:** [`migrate-cicd-to-circleci-research.md`](migrate-cicd-to-circleci-research.md)  
+**Depends on:** CircleCI org + paid plan created by requester; GCP project access for OIDC terraform  
+
+## Goal
+
+Move Terreno’s CI/CD from GitHub Actions to CircleCI end-to-end: every pipeline that builds, tests, deploys, publishes, or gates PRs runs on CircleCI. Use a dual-run cutover (GHA stays required until the matching CircleCI workflow is green, then delete the GHA workflow). End state: no `.github/workflows/*.yml` CI/CD jobs remain; GitHub keeps only what CircleCI cannot replace (if any residual is accepted, document it explicitly under Not Included).
+
+## Non-Goals
+
+- Changing what tests assert (only where they run), except for runner-parity fixes.
+- Migrating sibling repos (Flourish, Zapling, etc.).
+- Redesigning product deploy topology (Cloud Run / Netlify / EAS stay; only the orchestrator changes).
+- Shipping Appium **iOS** on CircleCI in **v1** (deferred to a late phase; Android Appium may move earlier if ubuntu parity is easy).
+- Rewriting gh-aw agentic *prompt* content; only re-home or replace the *runner*.
+
+## Decisions
+
+Recorded 2026-08-17 from Blend clarification.
+
+| # | Question | Decision |
+|---|----------|----------|
+| CC1 | Scope | **A — Full cutover.** All CI/CD moves to CircleCI; GHA workflows deleted after dual-run proves green. |
+| CC2 | Cutover style | **A — Dual-run.** Keep GHA required checks until the CircleCI twin is trusted, then remove GHA. |
+| CC3 | v1 must include | **GCP CD + terraform**, **npm publish-on-tag**, **Netlify** (demo / example-frontend / docs), **EAS PR + fingerprint gate**. Not Appium iOS in v1. |
+| CC4 | CircleCI account | Requester creates the CircleCI plan/org and links the GitHub repo. |
+| CC5 | Branch protection | Remapping required checks is in scope; maintainers apply GitHub settings when CircleCI check names are stable. |
+| CC6 | Config shape | **A — Dynamic config** (`setup: true`) + **path-filtering** orb. |
+
+## Architecture
+
+### Target topology
+
+```mermaid
+flowchart TB
+  subgraph gh [GitHub]
+    PUSH[push / PR / tag / schedule]
+    BP[branch protection required checks]
+  end
+
+  subgraph cci [CircleCI]
+    SETUP[setup workflow path-filtering]
+    CONT[continue config]
+    PKG[package CI + policy]
+    E2E[Playwright e2e]
+    NET[Netlify deploys]
+    EAS[EAS + fingerprint]
+    GCP[GCP CD via OIDC]
+    PUB[npm publish on tag]
+    MOB[Appium / Maestro late phase]
+    REP[replacements: CodeQL alt, bots, triage]
+  end
+
+  PUSH --> SETUP --> CONT
+  CONT --> PKG & E2E & NET & EAS & GCP & PUB & MOB & REP
+  PKG & E2E & EAS --> BP
+  GCP --> CR[Cloud Run / Artifact Registry / Infra Manager]
+  NET --> NL[Netlify sites]
+  PUB --> NPM[npmjs @terreno/*]
+  EAS --> EXPO[EAS Cloud]
+```
+
+### Config layout
+
+```
+.circleci/
+  config.yml              # setup: true — path-filtering only
+  continue-config.yml     # all real workflows/jobs
+  src/                    # optional: generated fragments if we split by package
+```
+
+- Use `circleci/path-filtering` to set boolean parameters (`run-api`, `run-ui`, `run-cd`, …) from changed paths (mirror today’s path filters).
+- Use `circleci/node` orb (≥7.2.0) for Bun install + cache (`pkg-manager: bun`).
+- Shared commands: `bun_install`, `start_mongo` (Docker service or `cimg` + mongo service), `compile_workspace_deps`.
+- Prefer a **private org orb** later for reuse; v1 may inline commands in `continue-config.yml` to ship faster, then extract.
+
+### Secrets: CircleCI Contexts
+
+| Context | Contents (from current GHA) |
+|---------|------------------------------|
+| `terreno-npm` | `NPM_TOKEN` |
+| `terreno-netlify` | `NETLIFY_AUTH_TOKEN`, site IDs |
+| `terreno-expo` | `EXPO_TOKEN` |
+| `terreno-gcp` | CircleCI OIDC (no long-lived key for CD); migrate `GCP_SA_KEY` off preview-cleanup onto OIDC |
+| `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` |
+| `terreno-release` | `REPO_ADMIN_TOKEN`, `ZOOM_WEBHOOK_URL`, `ZOOM_WEBHOOK_TOKEN` |
+| `terreno-agentic` | `CURSOR_API_KEY` (and replacements for Copilot/gh-aw tokens if re-homed) |
+| `terreno-github-api` | PAT with `pull-requests`, `deployments`, `contents` as needed for comments / Deployments API / roadmap |
+
+Restrict context access by project + environment (e.g. `release` context only on tag workflows).
+
+### GCP identity (blocking infra for Phase GCP)
+
+Today `terraform/modules/github_oidc` trusts **only** `https://token.actions.githubusercontent.com`. CircleCI CD requires:
+
+1. New Workload Identity pool provider for CircleCI’s OIDC issuer.
+2. Attribute condition on org/project/VCS origin.
+3. Bind `roles/iam.workloadIdentityUser` for deployer + terraform SAs.
+4. Dual-trust during dual-run (GitHub + CircleCI providers both valid), then remove GitHub provider when GHA CD is deleted.
+
+Prefer extending the module (`circleci_oidc` or rename to `ci_oidc` with multiple providers) over a one-off in Flourish terraform only — keep consumer docs honest.
+
+### GitHub ↔ CircleCI integration
+
+- CircleCI GitHub App (or OAuth) on `TerrenoLabs/terreno`.
+- Status checks reported to GitHub for branch protection (job names documented in `docs/explanation/repository-settings.md`).
+- PR comments / labels / Deployments API: call GitHub REST via `gh` or `curl` with `terreno-github-api` context (replaces `GITHUB_TOKEN` action privileges).
+- Tag + schedule triggers: CircleCI pipeline triggers (or GitHub → CircleCI API webhook) for cron jobs currently on GHA.
+
+### Dual-run protocol (every phase)
+
+1. Land CircleCI twin; name check `cci/<old-job-name>` or stable CircleCI job name.
+2. Add CircleCI check as **non-required** optional signal; keep GHA required.
+3. Observe green on `master` + representative PRs.
+4. Flip branch protection: require CircleCI; unrequire GHA.
+5. Delete the GHA workflow file in the same PR window as the protection flip (or immediately after).
+6. Never leave tag publish listening on **both** systems.
+
+## Models / APIs / Notifications / UI
+
+None (infra-only). Zoom release notify stays a webhook call from the publish workflow.
+
+## Phases
+
+### Phase 0 — Prerequisites (human + docs)
+
+- Create CircleCI org/plan; link repo; enable dynamic config.
+- Create empty Contexts; document secret migration checklist.
+- Inventory required check names vs today’s GHA job `name:` fields.
+
+### Phase 1 — Foundation
+
+- Add `.circleci/config.yml` + `continue-config.yml` skeleton.
+- Path-filtering parameter map covering all packages + terraform + docs + demo.
+- Shared Bun + cache + Mongo patterns.
+- Smoke workflow on every push that only validates config.
+
+### Phase 2 — Package CI + repo policy (v1)
+
+Port and dual-run:
+
+- `api-ci`, `ai-ci`, `rtk-ci`, `ui-ci`, `ui-demo-ci`, `comms-ci`, `mcp-server-ci`
+- `example-frontend-ci`, `example-backend-ci`, `example-backend-script-runner`, `example-backend-docker`
+- `admin-spa-ci`
+- `repo-policies`, `rulesync-check`, `dco` (DCO via GitHub API + CircleCI)
+
+### Phase 3 — Playwright E2E (v1)
+
+- `e2e-ci`, `admin-spa-integration` (Mongo replica set + secrets context).
+
+### Phase 4 — Netlify deploys (v1)
+
+- `demo-deploy`, `frontend-example-deploy`, `docs-deploy`
+- Recreate preview aliases + optional GitHub Deployments via API.
+- `preview-cleanup` equivalent for Netlify/GCP previews as applicable.
+
+Implemented: production and PR preview jobs exist on CircleCI. GitHub Actions
+is the live Netlify/GCP writer until `terreno-netlify` / `terreno-gcp` are
+populated; CircleCI deploy scripts skip (exit 0) when those variables are
+missing. After a successful CircleCI deploy, set GHA deploy workflows back to
+`push.branches-ignore: ["**"]` in the same change. Preview cleanup on PR close is GHA
+`preview-cleanup.yml` plus the manual CircleCI parameter.
+
+### Phase 5 — EAS + fingerprint (v1)
+
+- Port `eas-pr`, `eas-dev-build`, `fingerprint-gate` scripts under `.circleci/` or keep scripts in `.github/workflows/scripts/` and invoke from CircleCI until relocated to `scripts/ci/`.
+- PR comment + `fingerprint-acknowledged` label via GitHub API.
+
+Manual EAS dispatch is implemented. EAS PR updates and fingerprint
+acknowledgement are retained with `push.branches-ignore: ["**"]` until CircleCI comment/label parity
+is implemented.
+
+### Phase 6 — GCP CD + OIDC (v1)
+
+- Terraform: CircleCI OIDC provider + dual-trust.
+- Port `cd.yml` (detect → terraform → backend/mcp deploy).
+- Port `preview-cleanup` onto OIDC (eliminate `GCP_SA_KEY`).
+- Dual-run CD carefully (concurrency: one deployer).
+
+Implemented as CircleCI jobs plus GHA dual-run until CircleCI OIDC/context
+values exist. Path filters start `gcp-cd-prod` / `gcp-cd-preview`. CircleCI
+skips apply when `terreno-gcp` is empty so terraform is not double-applied.
+
+### Phase 7 — npm publish (v1)
+
+- Port `publish-on-tag` + `publish-feature-flags-manual`.
+- **Single-writer rule:** disable GHA tag trigger in the same change that enables CircleCI tag pipeline.
+- Keep Zoom notify + master version bump + docs cut + demo dispatch.
+
+Implemented as a semver-tag release job plus manual `syncdb`/`feature-flags`
+publishing. GHA publishing triggers are disabled. Docs version cutting remains
+a follow-up; package publish, stable master bumps, Zoom notify, and demo deploy
+are ported.
+
+### Phase 8 — Mobile runners (post-v1 / still required for full cutover)
+
+- Maestro web/Chrome (`maestro-e2e`) is implemented on CircleCI Linux browsers + Mongo replica set. GHA `maestro-e2e.yml` is `push.branches-ignore: ["**"]`.
+- Appium Android on Linux VM and Appium iOS on CircleCI macOS remain unported.
+
+### Phase 9 — GitHub-native + agentic replacements (full cutover)
+
+| Current GHA | Replacement approach |
+|-------------|----------------------|
+| `codeql-analysis` | CircleCI job uploading SARIF to GitHub Code Scanning API **or** third-party SAST orb; preserve Security tab if possible |
+| `dependabot-auto-merge` | Keep Dependabot PRs on GitHub; auto-merge via CircleCI on Dependabot branches **or** Renovate on CircleCI |
+| `triage.yml` | CircleCI pipeline trigger on `issues` via GitHub Apps webhook → CircleCI API, or GitHub Action **stub** only if product accepts residual GHA (conflicts with CC1 — prefer webhook) |
+| `roadmap-generate`, `roadmap-sync`, `roadmap-reconcile` | **Stay on GitHub Actions** (decided 2026-09-26). They only talk to GitHub (issues, Projects v2, `master` commits via `ROADMAP_PROJECT_TOKEN`), so moving them buys nothing. Exception to CC1. |
+| `architectural-pr-review` | Implemented: CircleCI job + `CURSOR_API_KEY` / `GITHUB_TOKEN`. Checks out `origin/master`, skips forks. GHA workflow is `push.branches-ignore: ["**"]`. |
+| Cursor Approval / Security / Bugbot | **Cannot move.** Cursor GitHub App automations, not repo workflows. |
+| `agentics-maintenance` + `*.lock.yml` gh-aw | Re-home to CircleCI scheduled pipelines calling the same scripts **or** retire features; do not leave gh-aw as the only runner if CC1 holds |
+| `docs-audit` | Scheduled CircleCI job |
+
+### Phase 10 — Cleanup + docs
+
+- Delete remaining `.github/workflows/*.yml` (and lock sources if retired).
+- Update `CONTRIBUTING.md`, `docs/explanation/repository-settings.md`, `terraform/README.md`, deploy how-tos, AGENTS.md Cloud CI notes.
+- Archive research; mark IP Complete.
+
+## Feature Flags & Migrations
+
+- No product feature flags.
+- Infra migration: dual OIDC trust window; dual CI check window; **no dual tag-publish**.
+- Secret migration checklist is the migration artifact (Contexts populated before jobs go required).
+
+## Activity Log & User Updates
+
+- Announce in Discord/Slack/Zoom when required checks flip and when tag publish moves.
+- Changelog: under Unreleased chore — “CI/CD runs on CircleCI”.
+
+## Not Included / Future Work
+
+- Private orb publication + versioning pipeline (nice follow-up after Phase 1–2 stabilize).
+- Moving Netlify sites to GCS+CDN (separate deploy architecture IPs).
+- Self-hosted CircleCI runners.
+- Credit-cost optimization beyond path-filtering (test splitting, resource-class tuning).
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Double npm publish | Single-writer cutover for tags; disable GHA first or in same commit |
+| GCP deploy from wrong IdP | Dual-trust then remove GitHub provider; dry-run terraform preview on CircleCI first |
+| Branch protection gaps during flip | Document exact check names; flip in a dedicated maintainer window |
+| macOS/Appium flake | Deferred to Phase 8; keep GHA Appium until CircleCI macOS proven |
+| gh-aw feature loss | Phase 9 explicit replace-or-retire decision per lockfile before deleting |
+| Credit burn during dual-run | Path filters; timebox dual-run per phase (target: days, not months) |
+| `mcp-server-ci` still filters `main` | Normalize to `master` while porting |
+
+## Files to Create / Modify
+
+**Create**
+
+- `.circleci/config.yml`
+- `.circleci/continue-config.yml`
+- `docs/how-to/circleci.md` (or `docs/explanation/ci-cd-circleci.md`)
+- `terraform/modules/circleci_oidc/` or extend `github_oidc` → multi-provider `ci_oidc`
+- `scripts/ci/` (relocated EAS/fingerprint helpers)
+
+**Modify**
+
+- `docs/explanation/repository-settings.md`
+- `terraform/README.md`, Flourish/terreno terraform roots that wire OIDC
+- `CONTRIBUTING.md`, root/CI docs references to GitHub Actions
+- Delete `.github/workflows/*` progressively per phase
+
+## Task List
+
+See [`docs/tasks/migrate-cicd-to-circleci.md`](../tasks/migrate-cicd-to-circleci.md).
+
+## Acceptance Criteria
+
+- [ ] All v1 workflows (package CI, policy, Playwright e2e, Netlify, EAS/fingerprint, GCP CD, npm publish) are green on CircleCI and required on `master` where applicable.
+- [ ] Matching GHA workflows for those surfaces are deleted; tag publish has exactly one listener.
+- [ ] CircleCI OIDC can deploy Cloud Run without `GCP_SA_KEY` for CD paths.
+- [ ] Path-filtering skips unrelated package jobs on a docs-only change.
+- [ ] `repository-settings.md` lists CircleCI check names; branch protection matches.
+- [ ] Phase 8–9 either complete (full cutover) or are tracked as blocking follow-ups before calling CC1 done.
+- [ ] CONTRIBUTING / terraform / deploy docs no longer instruct maintainers to use GHA for Terreno CI/CD.