@terreno/mcp 57.0.0 → 57.1.0

package/dist/docs/versioned/next/explanation/local-first-data.md

@@ -0,0 +1,52 @@
+# Local-first data in Terreno
+
+Terreno's default frontend data path is **local-first**: the on-device store is what your UI reads and writes, and the server reconciles changes asynchronously. This is a different mental model from request/response fetching with RTK Query.
+
+## What local-first means here
+
+In `@terreno/syncdb`, a TinyBase `MergeableStore` on the device is the **UI source of truth**. When a user taps "save," the mutation applies to local state immediately and lands in a durable outbox. The client then pushes the change to `@terreno/api` over the sync protocol (socket deltas with HTTP snapshot catch-up). The server remains the **authority** for permissions, validation, and conflict resolution — but the UI does not wait on the network for every write.
+
+There is no server-first mode and no opt-in flag: if you use syncdb, you adopt this model for every synced collection.
+
+## Mental model shift
+
+| Server-first (RTK Query) | Local-first (syncdb) |
+|--------------------------|----------------------|
+| UI reads from cache filled by HTTP | UI reads from the local store |
+| Writes call the API, then invalidate/refetch | Writes apply locally, then reconcile |
+| Loading spinners track request lifecycle | Sync status tracks outbox + connectivity |
+| Optimistic updates are manual and fragile | Optimistic state is the default path |
+| Conflicts are rare / ignored | Conflicts are explicit and must be resolved |
+
+Think **apply locally, then reconcile** instead of **request, wait, update cache**.
+
+## What you stop doing
+
+1. **Manual optimistic updates** — `onQueryStarted` patches, temporary IDs, and rollback logic for writes.
+2. **Write-level loading spinners** — `isLoading` on mutations for "saving…" UX; the row updates instantly.
+3. **Refetch orchestration** — `invalidatesTags`, `refetch()`, and list/detail cache coordination after mutations.
+4. **Treating the network as the read path** — list screens blocked on `isLoading` for every navigation.
+
+RTK Query remains appropriate for **non-synced** endpoints: `/auth/me`, admin RPC, AI routes, and anything that should stay request/response.
+
+## What you start doing
+
+1. **Conflict resolution UI** — When the server rejects a mutation (409 / `sync:nack`), the user must choose a strategy (`useServer` or `keepMine`). Use `ConflictSheet` from `@terreno/ui` or build your own with `useConflicts`.
+2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`).
+3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
+4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
+5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server.
+
+## Tradeoffs
+
+**Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).
+
+**Costs:** larger conceptual surface (conflicts, sync status, local storage), mandatory replica-set MongoDB for realtime, and migration work for existing RTK Query screens.
+
+Server-first fetching is simpler when you only need online CRUD with no offline requirement — but Terreno's blessed path for collection data is local-first.
+
+## Related docs
+
+- [syncdb reference](../reference/syncdb.md) — API ground truth
+- [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) — step-by-step migration
+- [Authentication architecture](authentication.md) — Better Auth + socket sessions

package/dist/docs/versioned/next/explanation/loop-engineering.md

@@ -0,0 +1,117 @@
+# Loop engineering
+
+Terreno separates engineering method from orchestration:
+
+```text
+                 LOOP
+       orchestrate / persist / wait
+          retry / stop / escalate
+                  |
+                  v
+               GROW
+               shape
+                  |
+                  v
+               PICK
+               build
+                  |
+                  v
+              ROAST
+               prove
+                  |
+                  v
+               BREW
+              submit
+                  |
+                  v
+              TASTE
+             react once
+```
+
+Repository knowledge composes underneath every invocation:
+
+```text
+lifecycle stage + project skills + IP/task/state + evidence
+```
+
+## Why fresh invocations
+
+One enormous agent context accumulates assumptions, stale external state, and confidence
+in its own implementation. The lifecycle instead makes every stage reconstructable from
+durable artifacts. Pick can retry from exact Roast evidence; Roast can verify without the
+implementer's assumptions; Taste can react to the current PR head rather than an old
+green result.
+
+The outer loop decides **when, who, what next, when to retry, when to wait, and when to
+escalate**. Stages decide how to perform one transition correctly.
+
+## The five transitions
+
+| Stage | Question | Primary evidence |
+| --- | --- | --- |
+| Grow | Is the work shaped and approved? | IP/tasks, decisions, criterion→verification map |
+| Pick | Was this slice implemented carefully? | red/green tests, checks, internal reviews |
+| Roast | Does the result actually satisfy the IP? | independent requirement→evidence verdict |
+| Brew | Is the verified result correctly submitted? | final checks, commit/head, PR, artifacts |
+| Taste | What is actionable on the current PR head now? | CI, mergeability, reviews, bounded fixes |
+
+Roast is not another implementation review. It independently proves or disproves
+acceptance criteria. Taste is not a resident watcher. It observes once, acts once, emits
+`PASS`, `FAIL`, `BLOCKED`, or `PENDING`, then exits.
+
+## Portable plugin, local knowledge
+
+The reusable plugin defines contracts, invariants, evidence, and transitions. Repo-local
+skills define exact API/UI/database patterns, commands, test environments, generated
+code, deployment, and safety rules.
+
+Each stage inspects available skills and loads those whose descriptions match the
+affected domain. A useful skill is optional when absent; a capability required by
+repository policy is a hard gate and produces `BLOCKED` if unavailable.
+
+Stages also load architecture docs before acting. Docs are the design; code implements
+them. Missing docs for a user-visible or architectural change is `FAIL`.
+
+This lets the same Pick method compose with backend API and test-environment knowledge,
+while Roast composes with UI conventions and real-app verification.
+
+### Terreno's current project-skill layer
+
+The canonical sources remain under `.rulesync/skills/` and are generated for supported
+agents. The current high-value composition points include:
+
+| Domain | Repo-local skills stages may discover |
+| --- | --- |
+| Backend/API/data | `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `generate-sdk`, `terreno-data-fetching` |
+| UI/app | `terreno-ui`, `building-terreno-apps`, `building-native-ui`, `verify-ui-changes` |
+| AI/prompts | `ai-prompt-governance` |
+| Docs/submission | `update-docs`, `commit`, `create-pr`, `fix-conflicts` |
+| Deployment/runtime | `deploy-gcp`, Expo deployment/workflow skills |
+
+This inventory is descriptive, not a plugin dependency list. Stages inspect the actual
+catalog on every invocation.
+
+## State and evidence
+
+The IP remains the design/scope source of truth. The task file remains the execution
+checklist. Lightweight loop-owned state stores only current stage/attempt/task,
+branch/head/PR, the previous structured result, artifacts, attempted approaches, and next
+transition.
+
+The fallback state location is `.terreno/pipeline/<slug>.json`; the outer loop preserves
+or transports it and Brew excludes it from commits unless repository policy says
+otherwise. Stage results follow the plugin's JSON-schema-backed YAML contract and never
+contain chain-of-thought or transcripts.
+
+## Retry and stop rules
+
+- Roast failure returns exact expected/actual evidence to a fresh Pick.
+- Engineering retries require a new hypothesis and preserve failed approaches.
+- Taste `PENDING` lets the outer loop wait and invoke fresh Taste against current state.
+- Human decisions are `BLOCKED`, never arbitrary retries.
+- Taste `PASS` requires all current-head checks terminal/non-failing, no conflicts, and
+  no actionable review findings.
+
+The detailed contract, schemas, and three execution scenarios live under
+[`plugins/terreno-planning/references/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning/references).
+

package/dist/docs/versioned/next/explanation/repository-settings.md

@@ -36,6 +36,14 @@ descriptions):
 - Require branches to be up to date before merging
 - Do not allow bypassing the above settings
 
+### CircleCI dual-run (in progress)
+
+Package CI / policy / Playwright twins live under `.circleci/` (see
+[how-to/circleci.md](../how-to/circleci.md)). **Keep requiring the existing GitHub
+Actions check names** until a twin is trusted; then add the CircleCI job name and
+remove the GHA workflow. Do not require CircleCI deploy jobs yet (deploys not
+ported).
+
 ## Merge settings
 
 **Path:** Settings → General → Pull Requests

package/dist/docs/versioned/next/explanation/roadmap-process.md

@@ -22,10 +22,10 @@ Discussion (Ideas/RFC)
     ▼
 Issue: Status = Shaping ─────────────────────────────┐
                                                       │  IP approved → roadmap-item
-Blend writes IP + task list  ────────────────────────┤  (sets IP field, Shaping → Planned)
+Grow writes IP + task list   ────────────────────────┤  (sets IP field, Shaping → Planned)
 (docs/implementationPlans/ + docs/tasks/)             ▼
                                           Issue: Status = Planned
-                                                      │  Roast → Cupping → Pour
+                                                      │  Pick → Roast → Brew
                                                       ▼
                                           PR: Fixes #NNN
                                                       │  merge
@@ -34,17 +34,17 @@ Blend writes IP + task list  ─────────────────
 ```
 
 The planning pipeline (the `terreno-planning` plugin) drives the design-and-build half;
-the roadmap skills drive the public-tracking half. They meet at one handoff: **Blend
+the roadmap skills drive the public-tracking half. They meet at one handoff: **Grow
 writes the IP, and once it is Approved hands off to `roadmap-item`.**
 
 | Transition | Who owns it | Authoritative artifact |
 | ---------- | ----------- | ---------------------- |
 | Idea debated and shaped | Community + maintainers | GitHub Discussion |
 | Discussion → first tracking issue (`Shaping`) | `roadmap-promote` | GitHub Issue + Project |
-| Design, scope, acceptance criteria | `terreno-1-blend` / `ip` | `docs/implementationPlans/<slug>.md` |
-| Task breakdown for implementation | `terreno-1-blend` / `ip` | `docs/tasks/<slug>.md` |
+| Design, scope, acceptance criteria | `terreno-1-grow` | `docs/implementationPlans/<slug>.md` |
+| Task breakdown for implementation | `terreno-1-grow` | `docs/tasks/<slug>.md` |
 | Approved IP → issue `Planned` + `IP` field set | `roadmap-item` | GitHub Issue + Project |
-| Implement, verify, submit, review | `terreno-2-roast` … `terreno-5-dialin` | the PR |
+| Implement, verify, submit, review | `terreno-2-pick` … `terreno-5-taste` | the PR |
 | Sprint estimates, assignees, internal-only work | Linear | Linear |
 | Public rendered list | CI (`roadmap:generate`) | `ROADMAP.md` |
 
@@ -60,7 +60,7 @@ The `terreno-planning` plugin is meant to run in any Terreno repo, including one
 Discussions and no roadmap board (Flourish, most consumer apps). There, only the design-and-build
 half applies:
 
-- **Blend** still writes the IP + task list — that dual-file model is the source of truth
+- **Grow** still writes the IP + task list — that dual-file model is the source of truth
   everywhere. It detects the absence of `.github/roadmap-fields.yml` and the `roadmap-item`
   skill and **skips the roadmap handoff** instead of inventing issues or labels.
 - Sprint execution is tracked in Linear and linked from the IP header; it is never copied
@@ -236,9 +236,9 @@ is the variable the generator reads.
 
 ## Maintainer skills
 
-Four agent skills cover the recurring roadmap work. Each one researches, proposes, and then
+Five agent skills cover the recurring roadmap work. Each one researches, proposes, and then
 **stops for a maintainer to approve** before touching GitHub — roadmap decisions are the most
-human part of the process, so none of them mutate state on their own. All four are
+human part of the process, so none of them mutate state on their own. All five are
 `disable-model-invocation`, meaning an agent will not start them on its own initiative;
 you invoke them explicitly.
 
@@ -248,6 +248,19 @@ you invoke them explicitly.
 | `roadmap-promote` | Maintainers accepted an Ideas or RFC discussion and it needs a tracked issue that links back to the thread |
 | `roadmap-item` | An approved IP needs its public tracking issue, or an existing entry's scope changed |
 | `roadmap-review` | Recurring hygiene: status drift, stale items, untriaged backlog, promotion candidates, then regenerate `ROADMAP.md` |
+| `roadmap-frontier` | A destination is too large or uncertain for one IP/context and needs a map, a small unblocked frontier, and repeated Grow → Taste delivery loops |
+
+### Huge features: frontier maps
+
+A frontier map is one low-resolution roadmap issue with an observable destination,
+resolved-decision index, current frontier, fog, and explicit out-of-scope boundary. Child
+tickets hold the detail and native blocking relationships. Work only the **frontier**:
+open, unblocked, unclaimed tickets.
+
+Decision tickets resolve one question. Delivery tickets link one approved IP/task pair and
+run the complete planning pipeline. After each ticket, update the map, graduate clarified
+fog into precise tickets, and return to the frontier with a fresh agent context. The map
+closes only when the destination is reached and no in-scope fog or open child tickets remain.
 
 Sources live in `.rulesync/skills/`; run `bun run rules` after editing to regenerate the
 per-agent mirrors.

package/dist/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -885,3 +885,42 @@ ad-hoc backfill scripts.
 - **Tasks:** *(not yet written)*
 - **RTK flag:** None
 - **Depends on:** —
+
+---
+
+# Shipped, umbrella, and declined IPs
+
+Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.
+Add each to the **Terreno Roadmap** project with the `IP` field set to the slug below.
+
+| IP slug | GitHub issue | Status |
+|---------|--------------|--------|
+| `admin-only` | https://github.com/FlourishHealth/terreno/issues/1075 | Shipped |
+| `admin-ui-v2-django-parity` | https://github.com/FlourishHealth/terreno/issues/1076 | Shipped |
+| `admin-script-runner` | https://github.com/FlourishHealth/terreno/issues/1077 | Shipped |
+| `consent-forms` | https://github.com/FlourishHealth/terreno/issues/1078 | Shipped |
+| `upgrade-banner` | https://github.com/FlourishHealth/terreno/issues/1079 | Shipped |
+| `apierror-standard-error-redesign` | https://github.com/FlourishHealth/terreno/issues/1080 | Shipped |
+| `syncdb-local-first` | https://github.com/FlourishHealth/terreno/issues/1081 | Shipped |
+| `feature-flags-openfeature` | https://github.com/FlourishHealth/terreno/issues/1082 | Shipped |
+| `design-blend-skill` | https://github.com/FlourishHealth/terreno/issues/1083 | Shipped |
+| `ModularAPI` | https://github.com/FlourishHealth/terreno/issues/1084 | Shipped |
+| `mcp-boost-parity` | https://github.com/FlourishHealth/terreno/issues/1085 | In progress |
+| `docs-site-and-versioning` | https://github.com/FlourishHealth/terreno/issues/1086 | Planned |
+| `syncdb-codegen` | https://github.com/FlourishHealth/terreno/issues/1087 | Planned |
+| `migrate-cicd-to-circleci` | https://github.com/FlourishHealth/terreno/issues/1088 | Planned |
+| `rbac-permissions` | https://github.com/FlourishHealth/terreno/issues/1089 | Planned |
+| `infra-mcp` | https://github.com/FlourishHealth/terreno/issues/1090 | Planned (blocked) |
+| `comms-admin-dashboard` | https://github.com/FlourishHealth/terreno/issues/1091 | Planned |
+| `model-router-mcp` | https://github.com/FlourishHealth/terreno/issues/1092 | Planned |
+| `terreno-langfuse-integration` | https://github.com/FlourishHealth/terreno/issues/1093 | Future |
+| `oss-launch-program` | https://github.com/FlourishHealth/terreno/issues/1094 | In progress |
+| `b2b-platform-program` | https://github.com/FlourishHealth/terreno/issues/1095 | Planned |
+| `offline-mode` | https://github.com/FlourishHealth/terreno/issues/1096 | Declined |
+| `model-router-actions` | https://github.com/FlourishHealth/terreno/issues/1097 | Declined |
+| `feature-flags` | https://github.com/FlourishHealth/terreno/issues/1098 | Declined |
+| `admin-improvements` | https://github.com/FlourishHealth/terreno/issues/1099 | Declined |
+
+Research and design sub-documents share the parent IP's issue: `admin-only-research` →
+#1075; `infra-mcp-research` → #1090; `migrate-cicd-to-circleci-research` → #1088;
+`syncdb-phase-c-design`, `terreno-syncdb-2`, and `syncdb-api-inventory` → #1081.

package/dist/docs/versioned/next/how-to/README.md

@@ -12,10 +12,13 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 
 ## Contents
 
+- [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
 - [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
 - [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
 - [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Expose Model Context Protocol tools](expose-mcp-tools.md) — Turn `modelRouter` models into MCP tools an LLM can call
+- [Install agent skills](install-agent-skills.md) — Install Grow/Pick/Roast/Brew/Taste and domain skills with `npx skills`
 - [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
 - [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer

package/dist/docs/versioned/next/how-to/admin-add-model.md

@@ -0,0 +1,41 @@
+# Add a model to the admin
+
+Add `admin` directly to the model's existing `modelRouter` options:
+
+```ts
+export const userRouter = modelRouter("/users", User, {
+  admin: {
+    displayName: "Users",
+    listFields: ["email", "name", "admin", "created"],
+    searchFields: ["email", "name"],
+    sortableFields: ["email", "name", "created"],
+    filters: [{field: "admin", kind: "boolean", label: "Admin user"}],
+  },
+  permissions: {
+    create: [Permissions.IsAdmin],
+    delete: [Permissions.IsAdmin],
+    list: [Permissions.IsAdmin],
+    read: [Permissions.IsAdmin],
+    update: [Permissions.IsAdmin],
+  },
+});
+```
+
+Register that router with `TerrenoApp`, then register `AdminApp`. The model appears in
+`GET /admin/config` and at `/admin/User` without a duplicate `AdminApp.models` entry.
+
+If the same Mongoose model is mounted at two `routePath`s (different filters or list
+columns), `/admin/config` keeps `name` as the model name for the registered entry and
+suffixes the others with the route slug (for example `Food-archived-foods`) so each list
+is reachable.
+
+Common fields:
+
+- `listFields`: columns and fields exposed to admin CRUD.
+- `searchFields`: string fields matched by the list search box (`q`) as a
+  case-insensitive partial (`$regex`) query.
+- `sortableFields`: the only columns with sorting enabled.
+- `filters`: typed filter drawer controls.
+- `fieldsets`: grouped form sections.
+- `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
+- `adminPermissions`: optional admin-specific permission methods.

package/dist/docs/versioned/next/how-to/admin-custom-home.md

@@ -0,0 +1,31 @@
+# Customize the admin home
+
+Configure home slots on `AdminApp`:
+
+```ts
+new AdminApp({
+  home: {
+    title: "Operations",
+    slots: {
+      contentTop: ["feature-flags-overrides"],
+      main: ["modelStats"],
+      navGlobal: ["scriptRunner"],
+      sidebar: ["versionConfig", "recentActivity"],
+    },
+  },
+});
+```
+
+Built-in IDs include `modelStats`, `modelsGrid`, `scriptRunner`, `versionConfig`, and
+`recentActivity`. Plugins add IDs such as `feature-flags-overrides`.
+
+For an app-specific widget, implement `AdminHomeWidgetProps` and register it:
+
+```tsx
+<AdminProvider widgets={{home: {operationsSummary: OperationsSummary}}} api={api}>
+  <AdminHome api={api} />
+</AdminProvider>
+```
+
+Then place `"operationsSummary"` in a home slot. Unknown IDs render a visible missing-widget
+placeholder in development instead of crashing the dashboard.

package/dist/docs/versioned/next/how-to/admin-custom-widget.md

@@ -0,0 +1,42 @@
+# Add a custom admin field widget
+
+1. Name the widget in model admin metadata:
+
+```ts
+admin: {
+  displayName: "Articles",
+  listFields: ["title", "body"],
+  fieldOverrides: {body: {widget: "rich-text"}},
+}
+```
+
+2. Implement the field widget:
+
+```tsx
+const RichTextWidget: React.FC<AdminFieldWidgetProps> = ({
+  value,
+  onChange,
+  readOnly,
+}) => (
+  <RichTextEditor
+    disabled={Boolean(readOnly)}
+    onChange={onChange}
+    value={typeof value === "string" ? value : ""}
+  />
+);
+```
+
+3. Register it once around the admin routes:
+
+```tsx
+<AdminProvider
+  api={api}
+  apiBase="/admin"
+  routeBase="/admin"
+  widgets={{fields: {"rich-text": RichTextWidget}}}
+>
+  <AdminRoutes />
+</AdminProvider>
+```
+
+Host registrations override built-ins with the same ID.

package/dist/docs/versioned/next/how-to/admin-import-prebuilt.md

@@ -0,0 +1,25 @@
+# Import pre-built admins
+
+Register first-party plugins on the same `TerrenoApp` as `AdminApp`:
+
+```ts
+const app = new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp())
+  .register(new ConsentApp({auditTrail: true}))
+  .register(new DocumentStorageApp({bucketName: process.env.GCS_BUCKET ?? ""}))
+  .register(new AIAdminApp())
+  .register(new AdminApp({home: {slots: {main: ["modelStats"]}}}));
+```
+
+`AdminApp` aggregates each plugin's `adminContribution()`:
+
+- `FeatureFlagsApp`: FeatureFlag model and `feature-flags-overrides` home widget.
+- `ConsentApp`: ConsentForm and ConsentResponse models plus consent field-widget IDs.
+- `DocumentStorageApp`: `documents` custom screen.
+- `AIAdminApp`: `ai-requests` custom screen and explorer API.
+
+Wrap frontend admin routes in `AdminProvider`. First-party widgets are already in the built-in
+registry, so no consumer-side switch statement or custom-screen map is required.
+
+`featureFlagAdminConfig` and `AdminApp.models` remain compatibility paths, but new integrations
+should use plugin contributions and `modelRouter({admin: ...})`.

package/dist/docs/versioned/next/how-to/circleci.md

@@ -0,0 +1,173 @@
+# CircleCI (Terreno)
+
+Dual-run migration from GitHub Actions. See
+[`docs/implementationPlans/migrate-cicd-to-circleci.md`](../implementationPlans/migrate-cicd-to-circleci.md).
+
+**Status (2026-08-20):** CircleCI is **disabled**. GitHub Actions is the CI of
+record. Setup/path-filtering is parked in `.circleci/config.setup.yml`;
+`.circleci/config.yml` is a no-op (`workflows.disabled.when: false`). Real jobs
+remain in `.circleci/continue-config.yml`. To re-enable, copy `config.setup.yml`
+over `config.yml`.
+
+**Parked (2026-08-17):** Phase 1–3 config is in-repo (package CI, repo policy, Playwright
+e2e). **Deploys are not ported yet** (Netlify, GCP CD, EAS, npm publish). GHA remains
+required until CircleCI twins are trusted.
+
+## Project setup (maintainers)
+
+1. Link `FlourishHealth/terreno` in CircleCI (GitHub App).
+2. Default branch: `master`.
+3. Enable **dynamic config** / setup workflows for the project (required for
+   `.circleci/config.yml` `setup: true`).
+4. Build forked PRs if you want DCO + rulesync on forks.
+
+Org/project slug: _(record after Phase 0.1 — e.g. `flourishhealth/terreno`)_.
+
+## Config layout
+
+| File | Role |
+|------|------|
+| `.circleci/config.yml` | Active CircleCI config (currently a disabled no-op) |
+| `.circleci/config.setup.yml` | Parked setup workflow + `path-filtering` (copy over `config.yml` to re-enable) |
+| `.circleci/continue-config.yml` | Real jobs/workflows gated by those params |
+
+Smoke job `config-ok` always runs on continuation.
+
+`.circleci/**` sets `run-circleci-config`, which starts the `circleci-config`
+workflow: one job from each ported family (package CI, policy, example apps,
+`e2e` with `spec: login`, admin-spa). `comms/**` also sets
+`run-example-backend` and `run-example-backend-script`, matching the GitHub
+Actions twins.
+
+## Contexts (create empty shells, then fill)
+
+Do **not** paste secret values into the repo. Create these CircleCI Contexts and restrict
+`terreno-release` to tag/release pipelines when publish is ported.
+
+| Context | Maps from GHA | Used by (planned / current) |
+|---------|---------------|------------------------------|
+| `terreno-npm` | `NPM_TOKEN` | publish (deferred) |
+| `terreno-netlify` | `NETLIFY_*` | deploys (deferred) |
+| `terreno-expo` | `EXPO_TOKEN` | EAS (deferred) |
+| `terreno-gcp` | OIDC / WIF (no long-lived key for CD) | GCP CD (deferred) |
+| `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` | `e2e`, `admin-spa-integration` |
+| `terreno-release` | `REPO_ADMIN_TOKEN`, Zoom webhooks | publish (deferred) |
+| `terreno-agentic` | `CURSOR_API_KEY` | agentic replacements (deferred) |
+| `terreno-github-api` | PAT (`pull-requests`, `contents`, …) | `dco`, PR comments later |
+
+Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets only**
+(or the in-job `ci-e2e-*-secret` fallbacks). **Do not** put `GITHUB_TOKEN` (or any
+GitHub PAT) in project env vars — those are injected into every job, including
+`bun` scripts from the PR. Create `terreno-github-api`, restrict it to this
+project, leave fork-PR secret passing off, and attach that context **only** to
+`dco` (and later comment jobs). DCO skips if `GITHUB_TOKEN` is unset.
+
+After contexts exist, attach them on the matching jobs in
+`.circleci/continue-config.yml` (see comments in the `workflows:` section).
+
+## Check name map (GHA → CircleCI)
+
+Branch protection still requires **GitHub Actions** names during dual-run. CircleCI
+checks appear as CircleCI job names in the GitHub Checks UI.
+
+| GHA job `name:` / workflow | CircleCI job |
+|----------------------------|--------------|
+| Repository policies / No barrel imports | `no-barrel-imports` |
+| Explicit any baseline | `explicit-any` |
+| License coverage | `license-coverage` |
+| Verify rules are in sync | `rulesync-check` |
+| `dco` | `dco` |
+| Run all tests (API CI) | `api-ci` |
+| Run all tests (AI CI) | `ai-ci` |
+| RTK Lint and Build | `rtk-ci` |
+| UI Lint, Build, Types, and Tests | `ui-ci` |
+| Demo TypeScript Check (UI dependency) | `ui-demo-typecheck` |
+| Demo Lint and TypeScript Check | `ui-demo-ci` |
+| Lint, compile, and test communications | `comms-ci` |
+| Lint, Build, and Test (MCP) | `mcp-server-ci` |
+| Build Docker Image (MCP) | `mcp-server-docker` |
+| Example Frontend Lint and Test | `example-frontend-ci` |
+| Example Backend Lint, Build, and Test | `example-backend-ci` |
+| Run admin script CLI | `example-backend-script-runner` |
+| Build backend Docker image | `example-backend-docker` |
+| Admin SPA Build and E2E | `admin-spa-ci` |
+| E2E · `<spec>` | `e2e` (matrix `spec`) |
+| E2E Load · syncdb-loadlab | `e2e-load` (trigger-gated, see below) |
+| Admin SPA Backend Integration E2E | `admin-spa-integration` |
+| _(new)_ CircleCI path-filter parity | `circleci-parity` |
+| _(smoke)_ | `config-ok` |
+
+Deferred phases keep their GHA checks for now; these are the planned CircleCI job
+names so branch protection can be remapped in one pass later:
+
+| GHA job `name:` / workflow (not yet ported) | Planned CircleCI job |
+|---------------------------------------------|----------------------|
+| Fingerprint gate (`fingerprint-gate.yml`) | `fingerprint-gate` (Phase 5) |
+| EAS PR update/build (`eas-pr.yml`) | `eas-pr` (Phase 5) |
+| EAS dev build (`eas-dev-build.yml`) | `eas-dev-build`, manual pipeline (Phase 5) |
+| CD terraform preview/apply (`cd.yml`) | `cd-terraform`, `cd-deploy` (Phase 6) |
+| Preview cleanup (`preview-cleanup.yml`) | `preview-cleanup` (Phase 6) |
+| Netlify demo / frontend / docs deploys | `deploy-demo`, `deploy-example-frontend`, `deploy-docs` (Phase 4) |
+| Publish on tag (`publish-on-tag.yml`) | `publish-npm` (Phase 7, single-writer cutover) |
+| Appium / Maestro | `appium-android`, `appium-ios`, `maestro` (Phase 8) |
+
+## Path-filter parity guard
+
+`bun run check:circleci-parity` fails when a GHA `paths:` entry has no mapping to
+its CircleCI parameter — otherwise the twin silently never runs. It runs as the
+`circleci-parity` job (CircleCI) and the **CircleCI path-filter parity** job
+(GitHub Actions `repo-policies`). Add new packages/paths to the mapping in
+`.circleci/config.setup.yml` (or `config.yml` when enabled) and to `WORKFLOW_PARAMETERS` in
+`scripts/check-circleci-parity/lib.ts`.
+
+## Config-only changes
+
+When CircleCI is enabled, `.circleci/config.yml` / `continue-config.yml` /
+`example-frontend/playwright.circleci.config.ts` edits set `run-circleci-config`,
+which runs a representative slice (`api-ci`, `ui-ci`, `example-backend-ci`,
+`no-barrel-imports`, `e2e` spec `login`) so config changes are actually exercised
+instead of only hitting the always-on smoke jobs. While disabled, keep the mapping
+in `config.setup.yml` in sync; `check:circleci-parity` reads that file first. CircleCI e2e
+pre-starts a static `bun expo export` on `:8082` (`NODE_OPTIONS=--max-old-space-size=3072`
+for the export only) and reuses it (60s test timeout, `large` Docker). Keeping Metro
+alive next to Chromium gets SIGKILL on 8GB. `xlarge` is not on this project's plan.
+
+## Nightly load test
+
+`e2e-load` (syncdb-loadlab) is never PR-blocking. Trigger the **setup** pipeline
+with `run-e2e-load`. Setup skips path-filtering and continues with a differently
+named continuation parameter (`e2e-load`) so CircleCI does not report conflicting
+pipeline parameters.
+
+```json
+{"run-e2e-load": true}
+```
+
+This replaces the GHA cron / `workflow_dispatch` / `load-test` label triggers in
+`e2e-load-nightly.yml`.
+
+## Local validation
+
+```bash
+circleci config validate .circleci/config.yml
+circleci config validate .circleci/continue-config.yml
+```
+
+## Dual-run drift
+
+While both systems run, keep these in sync when editing a GHA workflow:
+
+1. `paths:` → mapping in `.circleci/config.setup.yml` (or `config.yml` when enabled; enforced by `check:circleci-parity`)
+2. e2e `spec:` matrix → `e2e` workflow matrix in `continue-config.yml`
+3. New package CI workflow → new param + job + `WORKFLOW_PARAMETERS` entry
+
+## Not in this phase
+
+- Netlify / docs / demo / example-frontend **deploys**
+- GCP `cd.yml`, preview-cleanup, OIDC
+- EAS / fingerprint
+- npm publish-on-tag
+- Appium / Maestro
+- CodeQL, Dependabot auto-merge, triage, gh-aw agentics
+
+Keep matching `.github/workflows/*` until dual-run cutover deletes them per phase.