@terreno/mcp 0.31.0 → 56.0.0-beta.2

package/src/docs/versioned/next/implementationPlans/comms-admin-dashboard.md

@@ -0,0 +1,180 @@
+# Implementation Plan: Comms admin dashboard (errors, retries, log digging)
+
+**Status:** Draft
+**Roadmap issue:** *(not yet seeded — see [roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md))*
+**Priority:** High
+**Effort:** Medium batch
+**Owner:** unassigned
+**Created:** 2026-08-11
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [comms-abstraction](comms-abstraction.md) (Phases 1–2, including the hook + error-taxonomy additions); adapters optional but the dashboard is most useful once [comms-adapter-twilio-sms](comms-adapter-twilio-sms.md) and [comms-adapter-sendgrid](comms-adapter-sendgrid.md) land
+**RTK deprecation flag:** Partial — screens use the generated SDK; migrate with syncdb like other admin screens
+
+## Goal
+
+Make the admin panel the single place to **operate** the comms layer: see errors and
+failure rates at a glance, filter and dig into individual delivery logs (attempt history,
+provider error codes, raw provider metadata), and retry failed sends with one click —
+across every channel and provider, without touching Twilio/SendGrid consoles or raw Mongo.
+
+The comms-abstraction IP ships a minimal read-only `GET /comms/messages` explorer. This IP
+upgrades that into a real operations dashboard, following the same pattern the AI package
+uses (`addAiRequestsExplorerRoutes`) but with mutation (retry) and much richer filtering.
+
+## Non-Goals
+
+- Building the messages themselves (comms-abstraction) or provider integrations (adapter
+  IPs).
+- Charts beyond simple count cards — themed chart components arrive with
+  `charts-and-dashboards`; the stats endpoint is designed so charts can be added then.
+- Broadcast/bulk *composition* from admin (sending new messages, campaign tooling).
+- User-facing notification history (`notification-center` item).
+- Cross-service log aggregation (Sentry/Cloud Logging stay the deep-debug tools; the
+  dashboard links out via `providerMessageId`).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Where do the routes live? | `@terreno/comms` (`src/routes/commsDashboard.ts`) — they operate on `CommsMessage`, which the comms package owns. `@terreno/admin-backend` stays model-generic |
+| Where does the UI live? | `@terreno/admin-frontend` (`CommsDashboard*` components), rendered inside `AdminShellLayout` like the rest of the admin panel, and wired into example-frontend + admin-spa |
+| Retry semantics | Retry creates a **new** `CommsMessage` row linked back via `retriedFromId`; the original row is never mutated except `retriedById`. Sends go through the normal `commsService` facade so hooks, logging, and error taxonomy all apply |
+| What is retryable? | `status: "failed" \| "bounced"` **and** `errorClass !== "permanent"` (permanent failures — invalid number, unsubscribed, suppressed address — get a disabled button with the reason) **and** a retained payload exists. `verification` channel is never retryable (codes expire; users restart the flow) |
+| Payload retention for retry | `CommsApp` option `retainPayloadDays` (default 30) keeps the rendered message body on the `CommsMessage` row, passed through the `redactPayload` hook before storage; without a retained payload the retry button is disabled with the reason |
+| Filtering | Server-side query params, not client-side table filtering — delivery logs get large. Free-text `q` matches `subject`, `error`, and `to` (last-4 for redacted destinations) |
+| Bulk retry | `POST /comms/messages/retryMany` takes the same filter object as the list route plus a hard cap (default 100 per call) so an admin can re-drive an outage window without scripting |
+| Stats | One aggregation endpoint with day buckets per channel/provider/status; rendered as count cards now, charts later |
+
+## Architecture
+
+```
+@terreno/comms
+  src/routes/commsDashboard.ts   # list/detail/retry/retryMany/stats (replaces commsExplorer.ts)
+  src/commsService.ts            # retryMessage({messageId, req}) added to the facade
+
+@terreno/admin-frontend
+  src/comms/CommsDashboardScreen.tsx   # cards + filter bar + DataTable
+  src/comms/CommsMessageDetail.tsx     # attempt timeline + raw metadata + retry
+  src/comms/CommsStatusBadge.tsx       # status → Badge mapping
+  src/comms/useCommsDashboardApi.tsx   # RTK Query hooks (pattern: useAdminApi)
+```
+
+### Retry flow
+
+```
+Admin clicks Retry
+  → POST /comms/messages/:id/retry (IsAdmin)
+  → commsService.retryMessage: validates retryability, loads retained payload
+  → normal send path (beforeSend/onSend/onError hooks fire with isRetry: true)
+  → new CommsMessage row {retriedFromId: original._id}
+  → original row gets {retriedById: new._id}
+  → response returns the new row; UI navigates to it
+```
+
+## Models
+
+No new models. Uses the `CommsMessage` fields added by the comms-abstraction IP
+(`errorCode`, `errorClass`, `attempts[]`, `attemptCount`, `lastAttemptAt`,
+`retriedFromId`, `retriedById`, `templateId`, retained `payload`).
+
+## APIs
+
+All routes `Permissions.IsAdmin`, built with `createOpenApiBuilder`, in `/openapi.json`.
+
+| Method | Path | Notes |
+|---|---|---|
+| GET | `/comms/messages` | Paginated list. Filters: `channel`, `provider`, `status`, `errorClass`, `errorCode`, `userId`, `to`, `templateId`, `retriedFromId`, `startDate`, `endDate`, free-text `q`; sort `-created` default |
+| GET | `/comms/messages/:id` | Full detail: attempts array, raw provider `metadata`, retained payload (post-redaction), linked retry rows |
+| POST | `/comms/messages/:id/retry` | Re-send; 400 with a stable `code` (`comms-retry-not-retryable`, `comms-retry-payload-expired`, `comms-retry-channel-unconfigured`) when not retryable |
+| POST | `/comms/messages/retryMany` | Body: same filter object as list + `limit` (cap 100); returns `{retried, skipped: [{id, reason}]}` |
+| GET | `/comms/stats` | Aggregation: counts by `channel` × `provider` × `status` with day buckets over `startDate`/`endDate` (default 7d); includes failure rate per provider |
+
+## Notifications
+
+None. (A failure-rate alert notifier is Future Work — see below.)
+
+## UI
+
+All screens live in `@terreno/admin-frontend`, use `@terreno/ui` components only, and
+render on the `AdminShellLayout` canvas (`Page` with `color="transparent"`, `padding={0}`).
+
+- **`CommsDashboardScreen`**
+  - Summary `Card` row from `/comms/stats`: sent / delivered / failed / bounced for the
+    selected range, failure rate per provider, with an error-colored card when the failure
+    rate exceeds 5%.
+  - Filter bar: `SelectField`s for channel/provider/status/errorClass, `TextField`
+    (search icon) for `q`, `DateTimeField` pair for the range. Filters map 1:1 to list
+    query params and persist in the URL so views are shareable.
+  - `DataTable`: created, channel, provider, to (redacted), subject/preview, status
+    (`CommsStatusBadge`), errorCode, attemptCount; row click → detail; inline Retry
+    `IconButton` on retryable rows.
+  - Loading, error, and empty states per admin-frontend conventions.
+- **`CommsMessageDetail`**
+  - Header: status badge, channel/provider, recipient, timestamps, linked user
+    (`AdminRefField` → User), `retriedFromId`/`retriedById` links.
+  - **Attempt timeline**: one row per `attempts[]` entry — timestamp, provider,
+    `providerMessageId` (rendered as an external link to the provider console when the
+    adapter supplies `consoleUrl` in metadata), errorCode + error message.
+  - **Log digging**: collapsible JSON viewer (`Accordion` + `MarkdownView` code block) for
+    retained payload and raw provider `metadata` — everything the adapter recorded, post
+    redaction.
+  - **Retry** `Button` (`withConfirmation`) — disabled with a tooltip reason when not
+    retryable.
+
+## Phases
+
+1. **Backend routes:** upgrade the explorer to `commsDashboard.ts` (filters, detail,
+   stats), `retryMessage` on the facade, retry + retryMany routes, supertest coverage for
+   every filter and every non-retryable reason.
+2. **Admin screens:** `CommsDashboardScreen`, `CommsMessageDetail`, badge + hooks; wire
+   into example-frontend admin routes and admin-spa nav; regenerate SDK; frontend
+   verification with screenshots.
+3. **Bulk retry + docs:** `retryMany` UI (filtered "Retry all failed" with count
+   confirmation), `docs/reference/comms.md` dashboard section, rulesync.
+
+## Feature Flags & Migrations
+
+None. New routes and screens only; `CommsMessage` fields ship in comms-abstraction.
+
+## Activity Log & User Updates
+
+Every retry is itself a `CommsMessage` row (with `retriedFromId` and the acting admin in
+`metadata.retriedByUserId`), so the audit trail is the same surface the dashboard shows.
+
+## Not Included / Future Work
+
+- Failure-rate alerting (Slack/Google Chat notifier when a provider's failure rate spikes)
+  — small follow-up once `/comms/stats` exists.
+- Charts on the stats endpoint (`charts-and-dashboards`).
+- Editing a message before retry ("retry with edits").
+- Automatic scheduled retries with backoff — arrives with `job-queues`; this IP is
+  explicitly *manual, admin-driven* retry.
+
+## Files to Create / Modify
+
+- `comms/src/routes/commsDashboard.ts` (+ tests) — replaces `commsExplorer.ts`
+- `comms/src/commsService.ts` — `retryMessage`
+- `admin-frontend/src/comms/*` (+ tests)
+- `example-frontend/app/admin/comms/*` — routes; `store/openApiSdk.ts` via `bun run sdk`
+- `admin-spa` — nav entry
+- `docs/reference/comms.md`, `docs/reference/admin.md`
+
+## Task List
+
+See [docs/tasks/comms-admin-dashboard.md](../tasks/comms-admin-dashboard.md).
+
+## Acceptance Criteria
+
+- [ ] An admin can filter delivery logs by channel, provider, status, error class, error
+      code, user, recipient, template, date range, and free text — server-side, paginated.
+- [ ] The detail view shows every attempt with timestamp, provider message id, error code
+      and message, plus the raw provider metadata and retained payload in a JSON viewer.
+- [ ] Retry re-sends through the configured provider, creates a linked `CommsMessage` row,
+      fires the normal lifecycle hooks with `isRetry: true`, and records the acting admin.
+- [ ] Non-retryable messages (permanent failure, expired payload, unconfigured channel,
+      verification channel) show a disabled retry with the specific reason; the route
+      returns 400 with the matching stable error `code`.
+- [ ] `retryMany` re-drives at most the cap per call and reports skipped ids with reasons.
+- [ ] `/comms/stats` counts match the filtered list totals for the same range.
+- [ ] All routes are `IsAdmin`; non-admin requests get 403 (supertest coverage).
+- [ ] Screens verified in the running example app with screenshots attached to the PR.

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

@@ -0,0 +1,126 @@
+# Research: Migrate CI/CD to CircleCI
+
+**Status:** Research complete — decisions recorded in IP `migrate-cicd-to-circleci.md`  
+**Date:** 2026-08-17  
+**Repo:** FlourishHealth/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.3.10` 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/next/implementationPlans/migrate-cicd-to-circleci.md

@@ -0,0 +1,269 @@
+# Implementation Plan: Migrate CI/CD to CircleCI
+
+**Status:** Draft — decisions recorded; awaiting Approval  
+**Discussion:** _(none)_  
+**Roadmap issue:** _(pending — hand off via `roadmap-item` when Approved)_  
+**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 `FlourishHealth/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.
+
+### 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.
+
+### 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).
+
+### 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.
+
+### Phase 8 — Mobile runners (post-v1 / still required for full cutover)
+
+- Maestro (`maestro-e2e`).
+- Appium Android on Linux VM.
+- Appium iOS on CircleCI macOS resource class (image pin parity with `macos-15` intent).
+- Then delete `demo-appium-ci.yml` / `maestro-e2e.yml`.
+
+### 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` | Scheduled CircleCI job with `ROADMAP_PROJECT_TOKEN` |
+| `architectural-pr-review` | CircleCI job + `CURSOR_API_KEY` (lose `pull_request_target` free fork safety — use least privilege + fork policy) |
+| `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.