@terreno/mcp 0.31.0 → 56.0.0-beta.2

package/src/docs/versioned/next/superpowers/plans/2026-07-28-admin-mobile-navigation.md

@@ -0,0 +1,97 @@
+# Admin Mobile Navigation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** On viewports below 768px, replace the admin shell’s fixed sidebar with a hamburger-triggered left slide-over drawer.
+
+**Architecture:** Keep navigation content in one shared internal component. `AdminShell` uses `useWindowDimensions` to switch between desktop rail and mobile header + overlay drawer. Drawer closes on backdrop, close button, and nav selection.
+
+**Tech Stack:** React Native / Expo, `@terreno/ui` (`Box`, `Heading`, `Text`, `IconButton`), bun test + `@testing-library/react-native`.
+
+## Global Constraints
+
+- Breakpoint: below 768px → mobile; 768px and above → desktop sidebar.
+- Menu style: left slide-over drawer with dismissible backdrop.
+- Accessibility: hamburger labeled "Open navigation menu"; close labeled "Close navigation menu".
+- Do not change public `AdminShellProps` API unless required.
+- Always support React Native Web.
+
+---
+
+### Task 1: Failing AdminShell responsive tests
+
+**Files:**
+- Create: `admin-frontend/src/AdminShell.test.tsx`
+
+**Interfaces:**
+- Consumes: `AdminShell` from `./AdminShell`; mocked `./useAdminConfig` and `expo-router`
+- Produces: failing tests that assert desktop sidebar at ≥768, mobile header below 768, drawer open/close, nav closes drawer, a11y labels
+
+- [ ] **Step 1: Write the failing test file**
+
+Mock `useWindowDimensions` via a mutable width, mock `useAdminConfig` with a small config (Home + one model), mock `expo-router.router.push`. Assert:
+
+1. width 1024 → `admin-shell-sidebar` present; hamburger absent
+2. width 500 → sidebar absent; `admin-shell-menu-button` present with accessibilityLabel "Open navigation menu"
+3. press menu → `admin-shell-drawer` and backdrop appear; close button has "Close navigation menu"
+4. press backdrop / close → drawer gone
+5. open drawer, press Home nav → `router.push` called and drawer closed
+
+- [ ] **Step 2: Run tests and confirm failure**
+
+Run: `cd admin-frontend && bun test src/AdminShell.test.tsx`
+Expected: FAIL (missing mobile UI / testIDs)
+
+---
+
+### Task 2: Implement responsive AdminShell
+
+**Files:**
+- Modify: `admin-frontend/src/AdminShell.tsx`
+- Test: `admin-frontend/src/AdminShell.test.tsx`
+
+**Interfaces:**
+- Consumes: nav data from `useAdminConfig` (existing)
+- Produces: `MOBILE_BREAKPOINT = 768`; shared sidebar body; mobile header; overlay drawer with backdrop
+
+- [ ] **Step 1: Extract shared sidebar body**
+
+Create an internal `AdminShellSidebarNav` that receives navigate callbacks, grouped models, scripts, screens, configurationPath, footer, sidebarVariant, and optional `onNavigate` that runs after each nav press (used to close the drawer).
+
+- [ ] **Step 2: Wire responsive chrome**
+
+```tsx
+const MOBILE_BREAKPOINT = 768;
+const {width} = useWindowDimensions();
+const isMobileLayout = width < MOBILE_BREAKPOINT;
+const [isNavOpen, setIsNavOpen] = useState(false);
+```
+
+Desktop: existing fixed 280px sidebar.
+Mobile: compact header (`admin-shell-mobile-header`) with `IconButton` (`iconName="bars"`, testID `admin-shell-menu-button`) + "Admin" heading; main content full width.
+When `isNavOpen`: absolute full-screen overlay (`admin-shell-drawer`) with backdrop (`admin-shell-drawer-backdrop`) and 280px panel containing close `IconButton` (`iconName="xmark"`, testID `admin-shell-drawer-close`) + shared nav. Close on backdrop, close button, and after navigate.
+
+- [ ] **Step 3: Close drawer when resizing to desktop**
+
+`useEffect` clears `isNavOpen` when `!isMobileLayout`.
+
+- [ ] **Step 4: Run tests**
+
+Run: `cd admin-frontend && bun test src/AdminShell.test.tsx`
+Expected: PASS
+
+- [ ] **Step 5: Compile and lint**
+
+Run: `cd admin-frontend && bun run compile && bun run lint`
+Expected: clean
+
+---
+
+### Task 3: Manual UI verification
+
+**Files:** none (runtime check in example-frontend admin)
+
+- [ ] **Step 1:** With backend + `frontend:web` running, open `/admin` as `admin@example.com`
+- [ ] **Step 2:** Narrow viewport below 768 → hamburger header, no fixed sidebar
+- [ ] **Step 3:** Open drawer, navigate, confirm close; widen to ≥768 → sidebar returns
+- [ ] **Step 4:** Capture screenshot evidence under `.devdata/artifacts/`

package/src/docs/versioned/next/superpowers/specs/2026-07-28-admin-mobile-navigation-design.md

@@ -0,0 +1,36 @@
+# Admin Mobile Navigation Design
+
+## Goal
+
+Make the admin shell usable on narrow devices by replacing its fixed 280px sidebar with a hamburger-triggered navigation drawer below 768px.
+
+## Responsive behavior
+
+- At widths of 768px and above, preserve the existing sidebar and content layout.
+- Below 768px, hide the fixed sidebar and show a compact header with an accessible hamburger button and the Admin label.
+- Opening the hamburger displays the same grouped navigation in a left slide-over drawer above the page.
+- A backdrop covers the remaining page and dismisses the drawer when pressed.
+- The drawer also closes from its close button and after any navigation item is selected.
+
+## Component structure
+
+Extract the sidebar body into a shared internal component so desktop and mobile render the same links, groups, configuration entry, and footer. `AdminShell` owns responsive width detection and drawer open state. The existing main content, top bar, breadcrumbs, and header actions remain unchanged apart from the added mobile header.
+
+## Accessibility
+
+- The hamburger button has an "Open navigation menu" label.
+- The drawer close button has a "Close navigation menu" label.
+- Backdrop dismissal is available in addition to the explicit close button.
+- Existing navigation labels and hints remain intact.
+
+## Testing
+
+Add focused `AdminShell` tests covering:
+
+- Desktop sidebar rendering at 768px and above.
+- Mobile header rendering below 768px.
+- Opening and closing the drawer.
+- Closing after selecting a navigation item.
+- Hamburger and close-button accessibility labels.
+
+Run the admin frontend test suite, compile, lint, and responsive UI verification.

package/src/docs/versioned/next/tasks/comms-abstraction.md

@@ -4,55 +4,68 @@ IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
 
 ## Phase 1 — Package + contracts
 
-- [ ] **Task 1.1**: Scaffold `@terreno/comms` workspace package
+- [x] **Task 1.1**: Scaffold `@terreno/comms` workspace package
   - Description: `comms/` package with tsconfig/biome/bun test setup mirroring `feature-flags/`; root workspace entry + `comms:*` scripts
   - Files: `comms/package.json`, `comms/tsconfig.json`, `comms/biome.jsonc`, root `package.json`
   - Depends on: none
   - Acceptance: `bun run comms:compile` and `bun run comms:lint` pass
 - [ ] **Task 1.2**: Provider interfaces and message types
-  - Description: `MailProvider`, `SmsProvider`, `PushProvider`, `VerificationProvider`, `SendResult`, `DeliveryEvent` per IP
+  - Description: `MailProvider`, `SmsProvider`, `PushProvider`, `VerificationProvider`, `SendResult` (incl. `errorCode`/`errorClass`), `DeliveryEvent`, `CommsHookContext`, `OptOutEvent` per IP
+  - Status: base provider/message contracts shipped; `errorCode`/`errorClass`, `CommsHookContext`, and `OptOutEvent` remain
   - Files: `comms/src/types.ts`
   - Depends on: 1.1
   - Acceptance: types compile and are exported
-- [ ] **Task 1.3**: Console adapters
+- [x] **Task 1.3**: Console adapters
   - Description: dev adapters for all four channels logging via `logger.info`
   - Files: `comms/src/adapters/console.ts` + tests
   - Depends on: 1.2
   - Acceptance: each adapter returns `accepted: true` and logs
 - [ ] **Task 1.4**: `CommsMessage` model + `logSend`
-  - Description: delivery log model with five-type pattern, `description` on every field, plugins, static `logSend` that never throws
+  - Description: delivery log model with five-type pattern, `description` on every field, plugins, static `logSend` that never throws; dashboard-ready fields (`errorCode`, `errorClass`, `attempts[]`, `attemptCount`, `lastAttemptAt`, `retriedFromId`/`retriedById`, `templateId`, retained `payload`)
   - Files: `comms/src/models/commsMessage.ts` + tests
   - Depends on: 1.1
-  - Acceptance: send logging survives a forced model error (logged, not thrown)
+  - Acceptance: send logging survives a forced model error (logged, not thrown); attempts append per attempt
+  - Status: model and non-throwing `logSend` shipped; dashboard-ready fields remain
 - [ ] **Task 1.5**: `commsService` send facade
-  - Description: `sendMail`/`sendSms`/`sendPushToUser`/`startVerification`/`checkVerification`; template render helper; unconfigured-channel behavior (501 in prod, console fallback in dev)
+  - Description: `sendMail`/`sendSms`/`sendPushToUser`/`startVerification`/`checkVerification`; template render helper; unconfigured-channel behavior (501 in prod, console fallback in dev); inline retry on `errorClass: "transient"` only
+  - Status: send facade, templates, and unconfigured-channel behavior shipped; inline transient retry remains
   - Files: `comms/src/commsService.ts`, `comms/src/templates.ts` + tests
   - Depends on: 1.2, 1.3, 1.4
-  - Acceptance: unit tests cover happy path + unconfigured channel in both env modes
+  - Acceptance: unit tests cover happy path + unconfigured channel in both env modes; permanent failures do not retry
+- [ ] **Task 1.6**: Lifecycle hooks
+  - Description: `beforeSend` (mutate/cancel), `onSend`, `onError`, `onRetry`, `onOptOut`, `onDeliveryEvent` wiring in the facade; every hook wrapped so a throw is logged and never changes the send outcome
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 1.5
+  - Acceptance: one test per hook (fires with correct context) plus one throwing-hook test per hook
+- [ ] **Task 1.7**: Payload retention + redaction
+  - Description: `retainPayloadDays` (default 30) storage of rendered payload post-`redactPayload`; expiry cleanup clears `payload` without touching the log row
+  - Files: `comms/src/commsService.ts`, `comms/src/models/commsMessage.ts` + tests
+  - Depends on: 1.4, 1.5
+  - Acceptance: payload stored redacted; expired payload cleared; `retainPayloadDays: 0` stores nothing
 
 ## Phase 2 — CommsApp + routes
 
-- [ ] **Task 2.1**: `PushToken` model
+- [x] **Task 2.1**: `PushToken` model
   - Description: model per IP with unique token upsert semantics
   - Files: `comms/src/models/pushToken.ts` + tests
   - Depends on: 1.1
   - Acceptance: duplicate token registration updates the existing row
-- [ ] **Task 2.2**: `CommsApp` TerrenoPlugin
+- [x] **Task 2.2**: `CommsApp` TerrenoPlugin
   - Description: options wiring, `getCommsService()` accessor, route mounting on `register()`
   - Files: `comms/src/commsApp.ts` + tests
   - Depends on: 1.5, 2.1
   - Acceptance: plugin registers on `TerrenoApp` and service accessor returns configured providers
-- [ ] **Task 2.3**: Push token routes
-  - Description: modelRouter with `preCreate` owner injection, `OwnerQueryFilter`, deactivate on delete
+- [x] **Task 2.3**: Push token routes
+  - Description: custom idempotent registration/list/deactivation endpoints plus modelRouter owner read; persisted `userId` scoping
   - Files: `comms/src/routes/pushTokens.ts` + supertest
   - Depends on: 2.2
   - Acceptance: acceptance criteria bullets 2 pass under supertest
-- [ ] **Task 2.4**: Admin delivery explorer
+- [x] **Task 2.4**: Admin delivery explorer
   - Description: `GET /comms/messages` admin-only, paginated, filtered; OpenAPI builder
   - Files: `comms/src/routes/commsExplorer.ts` + supertest
   - Depends on: 2.2
   - Acceptance: non-admin gets 403; filters work
-- [ ] **Task 2.5**: `sendPushToUser` token resolution + pruning
+- [x] **Task 2.5**: `sendPushToUser` token resolution + pruning
   - Description: resolve active tokens per user; deactivate tokens whose `SendResult` reports permanent failure
   - Files: `comms/src/commsService.ts` + tests
   - Depends on: 2.1, 1.5
@@ -60,17 +73,17 @@ IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
 
 ## Phase 3 — Integration + docs
 
-- [ ] **Task 3.1**: example-backend registration
+- [x] **Task 3.1**: example-backend registration
   - Description: register `CommsApp` with console adapters; env-gated
   - Files: `example-backend/src/server.ts`
   - Depends on: 2.2
   - Acceptance: backend boots; `/comms/pushTokens` in `/openapi.json`
-- [ ] **Task 3.2**: Reference docs + rules
+- [x] **Task 3.2**: Reference docs + rules
   - Description: `docs/reference/comms.md`, rulesync source rule, `bun run rules`
   - Files: `docs/reference/comms.md`, `.rulesync/**`
   - Depends on: 2.x
   - Acceptance: `bun run rules:check` passes
-- [ ] **Task 3.3**: CI + publish wiring
+- [x] **Task 3.3**: CI + publish wiring
   - Description: `comms-ci` workflow; add `@terreno/comms` to `publish-on-tag.yml`
   - Files: `.github/workflows/comms-ci.yml`, `.github/workflows/publish-on-tag.yml`
   - Depends on: 1.x

package/src/docs/versioned/next/tasks/comms-adapter-sendgrid.md

@@ -9,21 +9,31 @@ IP: [comms-adapter-sendgrid](../implementationPlans/comms-adapter-sendgrid.md)
   - Files: `comms/src/adapters/sendgrid.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests for text/html/template sends
-- [ ] **Task 1.2**: Error mapping
-  - Description: 4xx → `accepted: false` + message; full response body into `CommsMessage.metadata`; never throws
+- [ ] **Task 1.2**: Error classification
+  - Description: HTTP status → `errorCode`/`errorClass` per the IP table (400 permanent, 401/403 config, 429/5xx transient); full response body into `CommsMessage.metadata`; never throws
   - Files: `comms/src/adapters/sendgrid.ts`
   - Depends on: 1.1
-  - Acceptance: unverified-sender and bad-address fixtures covered
-- [ ] **Task 1.3**: Peer dep + registration + docs
+  - Acceptance: unverified-sender (config), bad-address (permanent), and 429 (transient) fixtures assert `errorClass`; permanent skips the inline retry
+- [ ] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Description: capture `x-message-id`; `metadata.consoleUrl` Email Activity deep link; `onError` fires with the classified `SendResult`
+  - Files: `comms/src/adapters/sendgrid.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: accepted-send test asserts message id + consoleUrl; failed-send test asserts onError invocation
+- [ ] **Task 1.4**: Peer dep + registration + docs
   - Description: optional peer `@sendgrid/mail`; env-gated example-backend registration with fail-fast; reference + env docs incl. sender-verification checklist
   - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
   - Depends on: 1.1
   - Acceptance: boot without key skips registration; compile passes without the SDK installed
 
-## Phase 2 — Delivery events (gated on inbound-webhooks)
+## Phase 2 — Delivery events + opt-outs (gated on inbound-webhooks)
 
 - [ ] **Task 2.1**: Event Webhook route
-  - Description: ECDSA signature verification via inbound-webhooks; delivered/bounce/dropped/open → `DeliveryEvent`
+  - Description: ECDSA signature verification via inbound-webhooks; event mapping per the IP table → `DeliveryEvent`; `x-message-id` prefix correlation
   - Files: `comms/src/adapters/sendgrid.ts`, webhook registration
   - Depends on: inbound-webhooks IP
-  - Acceptance: signed fixture updates `CommsMessage.status`; unsigned rejected 401
+  - Acceptance: signed fixtures per event type update `CommsMessage.status` (+ `errorCode` for bounce/dropped); unsigned rejected 401
+- [ ] **Task 2.2**: Opt-out events
+  - Description: `spamreport`/`unsubscribe`/`group_unsubscribe` → `OptOutEvent` → consumer `onOptOut`
+  - Files: `comms/src/adapters/sendgrid.ts` + tests
+  - Depends on: 2.1
+  - Acceptance: spamreport fixture fires `onOptOut`; subsequent `dropped` classified `permanent`

package/src/docs/versioned/next/tasks/comms-adapter-twilio-sms.md

@@ -9,21 +9,31 @@ IP: [comms-adapter-twilio-sms](../implementationPlans/comms-adapter-twilio-sms.m
   - Files: `comms/src/adapters/twilioSms.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests cover both sender configs
-- [ ] **Task 1.2**: E.164 validation + error mapping
-  - Description: `libphonenumber-js` normalization; Twilio error codes into `SendResult.error` + metadata
+- [ ] **Task 1.2**: E.164 validation + error classification
+  - Description: `libphonenumber-js` normalization; Twilio error-code → `errorCode`/`errorClass` map per the IP table (unknown codes → `transient`); full error payload into `CommsMessage.metadata`; Twilio SDK calls wrapped with `withApiErrorHandling`
   - Files: `comms/src/adapters/twilioSms.ts`
   - Depends on: 1.1
-  - Acceptance: invalid number → 400 before API call; API failure → `accepted: false`
-- [ ] **Task 1.3**: Peer dep + example-backend registration + docs
+  - Acceptance: invalid number → 400 before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
+- [ ] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Description: `metadata.consoleUrl` deep link per message SID; `onError` fires with the classified `SendResult`
+  - Files: `comms/src/adapters/twilioSms.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: failed-send test asserts consoleUrl and onError invocation
+- [ ] **Task 1.4**: Peer dep + example-backend registration + docs
   - Description: optional peer `twilio`; env-gated registration; reference + env-var docs
   - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
   - Depends on: 1.1
   - Acceptance: compile + boot without twilio installed when unconfigured
 
-## Phase 2 — Delivery callbacks (gated on inbound-webhooks)
+## Phase 2 — Delivery callbacks + opt-outs (gated on inbound-webhooks)
 
 - [ ] **Task 2.1**: Status callback route
-  - Description: webhook endpoint with Twilio signature verification via inbound-webhooks framework
+  - Description: webhook endpoint with Twilio signature verification via inbound-webhooks framework; status mapping per IP table incl. `ErrorCode` propagation
   - Files: `comms/src/adapters/twilioSms.ts`, webhook registration
   - Depends on: inbound-webhooks IP
-  - Acceptance: signed payload updates `CommsMessage.status`; unsigned rejected 401
+  - Acceptance: signed payload updates `CommsMessage.status` (+ `errorCode` on failure); unsigned rejected 401
+- [ ] **Task 2.2**: STOP/START opt-out handling
+  - Description: inbound keyword webhook → `OptOutEvent` → consumer `onOptOut`; opt-in (START) emitted symmetrically
+  - Files: `comms/src/adapters/twilioSms.ts`, webhook registration + tests
+  - Depends on: 2.1
+  - Acceptance: STOP fixture fires `onOptOut` with `reason: "sms-stop"`; 21610 on later sends classified `permanent`

package/src/docs/versioned/next/tasks/comms-adapter-twilio-verify.md

@@ -7,11 +7,11 @@ IP: [comms-adapter-twilio-verify](../implementationPlans/comms-adapter-twilio-ve
   - Files: `comms/src/adapters/twilioVerify.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests for approved/pending/expired/max-attempts
-- [ ] **Task 2**: Redacted logging
-  - Description: `CommsMessage` rows with channel `verification`, last-4 destination, no codes
+- [ ] **Task 2**: Redacted logging + error classification
+  - Description: `CommsMessage` rows with channel `verification`, fully redacted destination, no codes, and verification channel metadata on start; `errorCode`/`errorClass` mapping (rate-limit transient, expired/max-attempts permanent, bad SID config); rows flagged non-retryable; `onError` fires on failures
   - Files: `comms/src/adapters/twilioVerify.ts`
   - Depends on: Task 1
-  - Acceptance: log assertion tests prove no code/full destination in any row
+  - Acceptance: log assertion tests prove no code/full destination in any row; failure fixtures assert class + onError
 - [ ] **Task 3**: Registration + docs
   - Description: env-gated example-backend registration; fail-fast on missing service SID; reference + env docs
   - Files: `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`

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

@@ -0,0 +1,52 @@
+# Tasks: Comms admin dashboard (errors, retries, log digging)
+
+IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
+
+## Phase 1 — Backend routes
+
+- [ ] **Task 1.1**: Upgrade explorer to `commsDashboard.ts` list + detail
+  - Description: rich filters (channel/provider/status/errorClass/errorCode/userId/to/templateId/dates/`q`), pagination, `GET /comms/messages/:id` with attempts + metadata + retained payload
+  - Files: `comms/src/routes/commsDashboard.ts` + supertest
+  - Depends on: comms-abstraction Phase 2 (incl. hooks/error-taxonomy additions)
+  - Acceptance: every filter covered by a supertest case; non-admin 403
+- [ ] **Task 1.2**: `retryMessage` facade + retry route
+  - Description: retryability validation (status, errorClass, payload retention, channel configured, not verification), linked rows via `retriedFromId`/`retriedById`, hooks fire with `isRetry: true`, acting admin recorded
+  - Files: `comms/src/commsService.ts`, `comms/src/routes/commsDashboard.ts` + tests
+  - Depends on: 1.1
+  - Acceptance: each non-retryable reason returns 400 with its stable `code`; successful retry creates a linked row
+- [ ] **Task 1.3**: `retryMany` + `/comms/stats`
+  - Description: bulk retry with cap + skipped reasons; aggregation by channel × provider × status with day buckets and failure rate
+  - Files: `comms/src/routes/commsDashboard.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: stats counts match list totals for the same filter/range; cap enforced
+
+## Phase 2 — Admin screens
+
+- [ ] **Task 2.1**: `CommsDashboardScreen`
+  - Description: stats cards, filter bar (URL-persisted), DataTable with status badges + inline retry
+  - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx`, `CommsStatusBadge.tsx`, `useCommsDashboardApi.tsx` + tests
+  - Depends on: 1.1, 1.3
+  - Acceptance: loading/error/empty states; filters round-trip through the URL
+- [ ] **Task 2.2**: `CommsMessageDetail`
+  - Description: attempt timeline, provider console links, JSON viewer for payload/metadata, confirmed retry button with disabled-reason tooltips
+  - Files: `admin-frontend/src/comms/CommsMessageDetail.tsx` + tests
+  - Depends on: 1.2, 2.1
+  - Acceptance: non-retryable rows show the specific reason; retry navigates to the new row
+- [ ] **Task 2.3**: Example app + admin-spa wiring
+  - Description: expo-router screens under `app/admin/comms/`, admin-spa nav entry, `bun run sdk`
+  - Files: `example-frontend/app/admin/comms/*`, `example-frontend/store/openApiSdk.ts`, admin-spa nav
+  - Depends on: 2.1, 2.2
+  - Acceptance: frontend verification in the running example app with screenshots on the PR
+
+## Phase 3 — Bulk retry UI + docs
+
+- [ ] **Task 3.1**: "Retry all failed" flow
+  - Description: filtered bulk retry with count confirmation modal; skipped-reason summary toast
+  - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx` + tests
+  - Depends on: 1.3, 2.1
+  - Acceptance: confirmation shows the exact count; result summarizes retried/skipped
+- [ ] **Task 3.2**: Docs + rules
+  - Description: dashboard section in comms reference, admin reference update, rulesync
+  - Files: `docs/reference/comms.md`, `docs/reference/admin.md`, `.rulesync/**`
+  - Depends on: 2.x
+  - Acceptance: `bun run rules:check` passes

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

@@ -0,0 +1,215 @@
+# 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 `FlourishHealth/terreno` is connected with permission to report GitHub checks. Enable **dynamic config** / setup workflows for the project. Record org slug + project slug in the IP header or how-to doc.
+  - 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.
+
+- [ ] **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`.
+
+- [ ] **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
+
+- [ ] **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.
+
+- [ ] **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.
+
+- [ ] **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`.
+
+## Phase 2: Package CI + policy
+
+- [ ] **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.
+
+- [ ] **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.
+
+- [ ] **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.
+
+- [ ] **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
+
+- [ ] **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
+
+- [ ] **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.
+
+- [ ] **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.
+
+- [ ] **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.
+
+## 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).
+
+- [ ] **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.
+
+- [ ] **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.
+
+## 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)
+
+- [ ] **Task 8.1**: Port Maestro + Appium Android
+  - Description: Port `maestro-e2e` and Android half of `demo-appium-ci` to CircleCI Linux VM with emulator strategy documented.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 5.2
+  - Acceptance: manual pipeline runs Android Appium and Maestro successfully.
+
+- [ ] **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.
+
+## 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 + roadmap-generate + docs-audit
+  - 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.
+
+- [ ] **Task 9.3**: Replace architectural review + gh-aw agentics
+  - Description: Per lockfile (`update-rules`, `update-docs`, daily improvers) and `architectural-pr-review` / `agentics-maintenance`: either port to CircleCI scheduled/PR pipelines with the same scripts or **retire** with maintainer sign-off. CC1 forbids leaving them on GHA.
+  - Files: `.github/workflows/*lock*`, `architectural-pr-review.yml`, `agentics-maintenance.yml`, `.circleci/continue-config.yml`
+  - Depends on: Task 0.2
+  - Acceptance: written retire-or-port decision for each; no gh-aw workflows remain if ported/retired.
+
+## 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). Update `PLAN_INDEX.md`; archive IP when Complete.
+  - Files: `.github/workflows/`, `docs/implementationPlans/PLAN_INDEX.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.