@terreno/mcp 57.2.0 → 57.4.0

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

@@ -1,17 +1,20 @@
 # CircleCI (Terreno)
 
-Dual-run migration from GitHub Actions. See
+CircleCI CI/CD source of truth. 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.
+**Status:** CircleCI owns package CI, repo policies, Playwright e2e, Maestro web
+e2e, architectural PR review, and semver-tag npm releases. Path filters start
+CircleCI Netlify and GCP production/preview jobs, but those jobs **skip green**
+until `terreno-netlify` and `terreno-gcp` are filled. GitHub Actions still
+owns live Netlify/GCP deploys in this window. Do not leave both applying
+terraform once CircleCI GCP deploys succeed — set the GHA deploy workflows
+back to `on: []` in the same change. GitHub-native security, Cursor GitHub App
+checks (Approval / Security / Bugbot), and repository automation remain
+enabled. EAS PR updates and the fingerprint gate are temporarily disabled;
+manual EAS development dispatch remains available in CircleCI. Preview
+**cleanup** on PR close is GitHub `preview-cleanup.yml` plus the manual
+CircleCI `run-preview-cleanup` parameter.
 
 ## Project setup (maintainers)
 
@@ -19,118 +22,338 @@ required until CircleCI twins are trusted.
 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`)_.
+4. Create the contexts below (`terreno-netlify`, `terreno-gcp`, and the rest).
+   Copy Netlify and GCP values from GitHub Actions secrets/vars. Until they
+   are set, CircleCI deploy jobs skip with exit 0 and GHA remains the live
+   deployer.
+5. Set project Environment Variable `CODECOV_TOKEN` (Codecov upload token) so
+   package CI can upload `coverage/lcov.info`. Uploads skip when it is unset.
+   Mirror the same secret as GitHub Actions `CODECOV_TOKEN` for retained twins.
+   Public repos need a token unless the Codecov org disables token auth for
+   public repositories.
+6. Build forked PRs if you want DCO + rulesync on forks.
+
+GitHub App org/project slug (API and CLI):
+`circleci/6UHiK7pThPXbhnNi3umQNe/W3HZeMJujyMB2sYiUXaQbs`.
+
+Do not query `gh/FlourishHealth/terreno` — that slug returns `404 Project not found`.
+Cloud agents use `CIRCLECI_TOKEN` (accepted alias of CircleCI's `CIRCLE_TOKEN`). Send
+it as the `Circle-Token` header. Confirm with `GET https://circleci.com/api/v2/me`, then
+list pipelines on the slug above.
 
 ## 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/config.yml` | Setup workflow + `path-filtering` (this is the live config) |
 | `.circleci/continue-config.yml` | Real jobs/workflows gated by those params |
 
-Smoke job `config-ok` always runs on continuation.
+Fork-only `dco` and PR `architectural-pr-review` always start on continuation
+(review skips before checkout when the agentic/GitHub contexts are empty).
+`rulesync-check` runs only when generated-rule sources change (`run-rulesync`).
+`admin-backend/**` and `admin-frontend/**` start `packages-ci` (lint, compile,
+`test:coverage`). Dedicated `admin-*-ci` job definitions stay in the config as
+the same command sequence.
+
+`.circleci/**` sets `run-circleci-config`. On **config-only** PRs that workflow
+runs a representative slice (`api-ci`, `ui-ci`, `example-backend-ci`, `e2e`
+shard `auth`). `repo-policies` still starts from `run-repo-policies` (also set
+for `.circleci/**`); the kitchen-sink does not start a second copy. If the same
+pipeline already set `run-api`, `run-ui`, `run-e2e`, `run-example-backend`, or
+`run-admin-spa`, that kitchen-sink workflow is skipped so jobs are not doubled.
+`comms/**` also sets `run-example-backend` and `run-example-backend-script`,
+matching the GitHub Actions twins.
+
+The example-backend Docker job runs only when its image recipe changes
+(`Dockerfile`, `.dockerignore`, package manifests, or `bun.lock`). API/source
+changes are covered by preview CD builds and do not start a duplicate image job.
+
+UI, RTK, and admin-frontend changes do **not** start `example-backend-ci`.
+Those packages are covered by `ui-ci` / `rtk-ci` / `packages-ci` plus e2e and
+admin-spa. `new-file-coverage` starts on package `src/` (and example app
+runtime paths including `example-frontend/components/`), not on every `*.ts`
+file in the repo (Playwright specs no longer compile the world). Package CI
+jobs that already ran `test:coverage` evaluate the 90% new-file gate against
+that LCOV (`scripts/ci/check-new-file-coverage-lcov.sh`). Retained GitHub
+Actions twins run that script with `working-directory: .` so a package-level
+`defaults.run` cwd cannot nest `{package}/coverage/lcov.info`. GHA
+`upload-codecov` steps pass `token: ${{ secrets.CODECOV_TOKEN }}`. The dedicated
+`new-file-coverage` job skips those packages and only reruns tests for
+workspaces without a coverage job in the same pipeline (example apps). Reruns
+prefer colocated `*.test.ts` files and compile `@terreno/*` dist deps only
+when the package imports them. Coverage-script unit tests run in the cheap
+`coverage-scripts` job.
+
+Playwright runs five shards after `e2e-prepare` (`auth`, `app`, `admin-core`,
+`admin-table`, `syncdb`) instead of one container per spec file. Each shard
+first checks the [affected gate](#e2e-affected-gate) and halts when no changed
+file can reach it. Repository
+policy checks share one `repo-policies` job so eight small checkouts do not
+sit in the concurrency queue. `repo-policies` uses Node 22.14 because Knip's
+oxc-parser throws `ERR_REQUIRE_ESM` on the shared 22.11 executor.
+Require `repo-policies` in branch protection. Require `e2e-auth` /
+`e2e-app` / … only as path-filtered checks; config-only PRs post `e2e-auth`
+as the smoke shard and do not run the other four. Do not require the old
+`no-barrel-imports` / `e2e-login` names.
+
+## E2E affected gate
+
+Path filters decide whether e2e is a *candidate*; `scripts/ci/e2eAffected`
+decides which shards actually run. `e2e-prepare` runs
 
-`.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.
+```bash
+bun run check:e2e-affected --base origin/master --write e2e-affected.json
+```
+
+and persists the decision to the workspace (also stored as the
+`e2e-affected.json` artifact). Each shard reads it and calls
+`circleci-agent step halt` before `bun install` when it is unaffected, so an
+unneeded shard costs one container start instead of a full Playwright run.
+Run the same command locally to see what a branch would trigger.
+
+`e2e-prepare` always runs when a path filter starts the workflow: compiling the
+workspace and `bun expo export`ing the web bundle is the check that catches
+build breakage the shards would otherwise miss.
+
+The gate **fails open** — it runs every shard when the base revision cannot be
+resolved, when a module cannot be resolved, or when the analysis throws. A
+change is only skipped when it is provably outside a shard's surface:
+
+| Change | Decision |
+| --- | --- |
+| Module reachable from the shard's screens, specs, or `example-backend/src` | run |
+| Module nothing reachable imports (`ui/src/Avatar.tsx` today) | skip |
+| Type-only edit to a reachable module (interfaces, `type`, `declare`) | skip |
+| New export or lazy registry entry no consumer imports | skip |
+| Re-export barrel that repoints a binding the app imports | run |
+| `bun.lock` install the app resolves changing version | run |
+| `bun.lock` or `package.json` churn outside that closure | skip |
+| Docs, rules, `demo/**`, `scripts/**`, unit tests, snapshots, lint config | skip |
+| Anything else (`metro.config.js`, `app.json`, `.circleci/**`, patches) | run |
+
+Shard membership comes from `scripts/ci/e2eAffected/shards.ts`, which must
+mirror the spec groups in `run_example_frontend_e2e`. `shards.test.ts` fails
+when the two drift, when a spec is unassigned, or when a spec navigates to a
+screen its shard does not declare. It also asserts that `ui/src/index.tsx`
+stays a pass-through barrel — runtime code there would make every
+`@terreno/ui` change look reachable.
+
+## Automatic deploys
+
+Path filters set `run-deploy-*` and `run-cd-*`. Production jobs run only on
+`master`. Preview jobs run on PRs from this repository and skip forks and
+non-PR branch builds.
+
+| Path (examples) | Parameter | PR job | `master` job |
+| --- | --- | --- | --- |
+| `demo/**`, `ui/**` | `run-deploy-demo` | `deploy-demo-preview` | `deploy-demo` |
+| `example-frontend/**`, `admin-frontend/**`, `rtk/**` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
+| `docs/**`, `website/**` | `run-deploy-docs` | `deploy-docs-preview` | `deploy-docs` |
+| `example-backend/**`, `api/**`, `comms/**` | `run-cd-backend` | `gcp-cd-preview` | `gcp-cd-prod` |
+| `terraform/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
+| `mcp-server/**` | `run-cd-mcp` | _(none)_ | `gcp-cd-prod` |
+
+Until `terreno-netlify` is populated, GitHub Actions `docs-deploy` /
+`demo-deploy` / `frontend-example-deploy` publish the live sites (including
+PR aliases). CircleCI `deploy-*-preview` jobs still start from path filters
+and skip when `NETLIFY_AUTH_TOKEN` or the site id is missing. The same skip
+applies to `gcp-cd-*` when `terreno-gcp` lacks WIF or SA emails, so GitHub
+`cd.yml` remains the live GCP writer. GitHub `terraform-preview` and
+`backend-deploy-preview` run only when
+`github.event.pull_request.head.repo.full_name == github.repository`.
+Terraform preview always describes the Infra Manager preview (state,
+`errorCode`, `errorLogs`) before delete, including when `previews create`
+fails. Fork PRs still present `repository: FlourishHealth/terreno` on the
+OIDC token, so
+WIF would accept them if those jobs ran. Netlify GHA jobs fail closed on
+forks (secrets withheld). After filling a context, confirm a CircleCI deploy
+URL, then set the matching GHA workflows to `on: []`. Turn off Netlify's
+GitHub auto-build so only one system publishes.
 
 ## 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.
+Do **not** paste secret values into the repo. Create these CircleCI Contexts and
+restrict `terreno-release` and `terreno-npm` to tag/manual release pipelines.
 
 | 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 |
+| `terreno-npm` | `NPM_TOKEN` | tag + manual package publishing |
+| `terreno-netlify` | `NETLIFY_AUTH_TOKEN`, three `NETLIFY_*_SITE_ID` values | Netlify deploys |
+| `terreno-expo` | `EXPO_TOKEN` | manual EAS workflows |
+| `terreno-gcp` | `GCP_WIF_PROVIDER_PROD`, `GCP_TF_ADMIN_SA_PROD`, `GCP_CD_DEPLOYER_SA_PROD`, optional `GCP_INFRA_MANAGER_LOCATION`, `MCP_SENTRY_DSN` | GCP CD + cleanup |
+| `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` | `e2e`, `admin-spa-integration`, `maestro-e2e` |
+| `terreno-release` | `REPO_ADMIN_TOKEN`, `ZOOM_WEBHOOK_URL`, `ZOOM_WEBHOOK_TOKEN` | stable version bump + release notification |
+| `terreno-agentic` | `CURSOR_API_KEY`, optional `CURSOR_MODEL` | `architectural-pr-review` |
+| `terreno-github-api` | PAT (`pull-requests`, `contents`, …) | `dco`, `architectural-pr-review` |
 
 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).
+`dco` and `architectural-pr-review`. DCO skips if `GITHUB_TOKEN` is unset.
+`architectural-pr-review` also skips if `GITHUB_TOKEN` or `CURSOR_API_KEY` is
+unset, and it skips fork PRs. The job checks out `origin/master` before running
+the review script so a PR cannot rewrite the reviewer.
+
+Netlify and GCP jobs **halt as the first step** when `terreno-netlify` /
+`terreno-gcp` are empty, before checkout or `bun install`. Path filters still
+start those jobs so filling the context turns deploys on without a config
+change; skip-green no longer pays for a full `large` install. Docker Layer
+Caching is off (200 credits per job). The docs Netlify target disables
+Docusaurus minification so the build stays within the 8 GB `large` executor.
+
+`terreno-gcp` uses CircleCI OIDC (`CIRCLE_OIDC_TOKEN_V2`), never a JSON service
+account key. Set `circleci_org_id`, `circleci_project_id`, and
+`circleci_gcp_context_id` in `terraform/terraform.tfvars`, apply once with an
+existing Terraform admin identity, then copy `circleci_workload_identity_provider`
+into the context as `GCP_WIF_PROVIDER_PROD`. The WIF condition requires the
+`terreno-gcp` context UUID so a PR job without that context cannot exchange the
+ambient OIDC token for GCP impersonation.
 
 ## 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.
+Branch protection must require the CircleCI job names below. Remove disabled
+GitHub check names or pull requests will wait for checks that can no longer run.
+
+Dedicated package jobs (`api-ci`, `ai-ci`, `rtk-ci`, `ui-ci`, `syncdb-ci`,
+`comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run `bun run test:coverage`
+(`scripts/check-coverage.ts`, 95% functions and lines). Isolated `syncdb` tests
+are included by that script. Published packages without a dedicated workflow
+(`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `test`) run
+the same commands through the parameterized `packages-ci` job, gated by
+`run-admin-backend`, `run-admin-frontend`, `run-api-health`,
+`run-feature-flags`, and `run-test-package`. The retained
+`.github/workflows/packages-ci.yml` matrix twin stays `on: []`.
 
 | GHA job `name:` / workflow | CircleCI job |
 |----------------------------|--------------|
-| Repository policies / No barrel imports | `no-barrel-imports` |
-| Explicit any baseline | `explicit-any` |
-| License coverage | `license-coverage` |
+| Repository policies (barrels, source rules, explicit any, licenses, changelog, parity, lifecycle, static analysis) | `repo-policies` |
 | Verify rules are in sync | `rulesync-check` |
 | `dco` | `dco` |
 | Run all tests (API CI) | `api-ci` |
+| Admin backend lint, compile, coverage | `packages-ci` (`admin-backend`) |
+| Admin frontend lint, compile, coverage | `packages-ci` (`admin-frontend`) |
 | 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` |
+| Syncdb Lint, Build, and Tests | `syncdb-ci` |
+| UI Lint, Build, Types, and Tests + demo typecheck | `ui-ci` |
+| Demo Lint and TypeScript Check | `ui-demo-ci` (demo-only PRs) |
 | Lint, compile, and test communications | `comms-ci` |
 | Lint, Build, and Test (MCP) | `mcp-server-ci` |
+| Lint, compile, and coverage (create-terreno-app) | `create-terreno-app-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` |
+| Example Backend lint/test + admin script CLI | `example-backend-ci` |
+| Run admin script CLI (when backend CI did not already run) | `example-backend-script-runner` |
 | Build backend Docker image | `example-backend-docker` |
 | Admin SPA Build and E2E | `admin-spa-ci` |
-| E2E · `<spec>` | `e2e` (matrix `spec`) |
+| Lint, compile, and coverage (matrix package) | `packages-ci` (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `test`) |
+| E2E · `<shard>` | `e2e` (matrix `shard`: `auth`, `app`, `admin-core`, `admin-table`, `syncdb`) |
 | 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:
+| _(e2e compile+export once)_ | `e2e-prepare` |
+| Architectural PR review | `architectural-pr-review` (non-blocking; skip forks / missing secrets) |
+| Maestro E2E Tests | `maestro-e2e` (`include-demo` when ui/demo Maestro flows change) |
+| New file coverage | `new-file-coverage` |
+| Coverage gate scripts | `coverage-scripts` |
+| Netlify production | `deploy-demo`, `deploy-frontend`, `deploy-docs` |
+| Netlify PR preview | `deploy-demo-preview`, `deploy-frontend-preview`, `deploy-docs-preview` |
+| GCP production | `gcp-cd-prod` |
+| GCP PR preview | `gcp-cd-preview` |
+| npm semver tag | `publish-release` |
+
+CD replacement map:
 
 | 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) |
+| Fingerprint gate (`fingerprint-gate.yml`) | Temporarily disabled; no CircleCI automatic gate |
+| EAS PR update/build (`eas-pr.yml`) | Temporarily disabled; use manual EAS dispatch |
+| EAS dev build (`eas-dev-build.yml`) | CircleCI manual `eas-dev-target` |
+| CD terraform / Cloud Run (`cd.yml`) | `gcp-cd-prod` (master) and `gcp-cd-preview` (PRs) |
+| Preview cleanup (`preview-cleanup.yml`) | CircleCI manual `run-preview-cleanup` |
+| Netlify demo / frontend / docs deploys | production + `*-preview` jobs |
+| Publish on tag (`publish-on-tag.yml`) | `publish-release` |
+| Appium Android / iOS | Not ported (Maestro web is `maestro-e2e`) |
+
+## Manual pipelines
+
+Trigger a pipeline from the CircleCI UI/API on the ref containing the code to
+operate. Set exactly one operation per pipeline.
+
+Netlify and GCP operations require the contexts in the table above. Path filters
+start production deploys on `master` and PR previews on other branches
+automatically. Use the manual parameters to force a deploy or to clean up after
+a closed PR.
+
+| Operation | Pipeline parameters |
+|-----------|---------------------|
+| Force all GCP production CD (use `master`) | `{"run-cd":true}` |
+| Force demo production deploy | `{"run-demo-deploy":true}` |
+| Deploy backend + Netlify previews | `{"deploy-preview-pr":"1199"}` |
+| Remove preview backend tag/database | `{"run-preview-cleanup":"1199"}` |
+| Dispatch EAS development builds | `{"eas-dev-target":"both"}` (`example-frontend`, `demo`, or `both`) |
+| Publish one package | `{"manual-publish-package":"syncdb","manual-publish-version":"57.3.0"}` |
+| Run load test | `{"run-e2e-load":true}` |
+
+`manual-publish-package` also accepts `feature-flags`. Versions must be semver.
+Semver git tags (`57.3.0`, `57.3.0-beta.1`) automatically start
+`publish-release`; prereleases publish to their prerelease npm dist-tag.
+`scripts/ci/publish-package.sh` pins `workspace:*` to the tag version for the
+tarball, then compiles and tests against the root workspace install. It must
+not `bun install` after that pin: sibling `@terreno/*` packages are not on npm
+yet, so bun would look up `@terreno/test@X.Y.Z` (and similar) on the registry
+and fail the whole job. Tests use `test:ci` when that script exists, not
+`test`. `@terreno/ui`'s `test` is `bun test --watch` and would hang the
+publish step after the suite finishes. `publish-release` uses a 20-minute
+no-output timeout as a backstop. If a package's tag version is already on npm,
+`publish-package.sh` skips it so a recut of the same tag can finish the rest.
+
+Only stable tags (`57.3.0`) run `deploy-demo` after publish. Use
+`{"run-demo-deploy":true}` on `master` if a prerelease must also refresh the
+demo site.
+
+PR preview **cleanup** is manual because CircleCI does not receive GitHub
+`pull_request.closed` events. Configure a GitHub App/webhook to call
+`run-preview-cleanup` if automatic lifecycle cleanup is required. Path-filtered
+preview **deploys** run on open PRs from this repository; fork PRs are skipped.
+If `CIRCLE_PULL_REQUEST` is unset (GitHub App `push` pipelines), the job looks
+up the open PR for `CIRCLE_BRANCH` via the GitHub API.
+
+`mcp-server-docker` is push-only, matching GitHub Actions. It uses
+`resolve-preview-pr.sh` for that lookup and skips when a PR exists. Its
+production `bun install` passes `--ignore-scripts`: root `prepare` runs
+`simple-git-hooks`, which is a devDependency and is missing from a production
+tree.
 
 ## 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`.
+`bun run check:circleci-parity` guards active GitHub/CircleCI twins. Deploy
+workflows are dual-run until CircleCI contexts are filled; they are not in
+the parity mapping. New CircleCI-only path rules still belong in
+`.circleci/config.yml` and config tests. The checker prefers live `config.yml`
+when `setup: true`.
 
 ## 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.
+Edits to `.circleci/config.yml` / `continue-config.yml` /
+`example-frontend/playwright.circleci.config.ts` set `run-circleci-config`.
+When no package/e2e path param is also set, that workflow runs the slice above.
+CircleCI e2e compiles the workspace and `bun expo export`s **once** in
+`e2e-prepare` (`large`, 8 GB — the export heap is 3 GB). Five shards then
+attach that dist on `medium+` (6 GB, 15 credits/min). `xlarge` is not on this project's plan. In-job
+compile+export jobs (`maestro-e2e`, `admin-spa-integration`, `e2e-load`) stay
+on `large`. Chaos e2e treats a hidden Offline banner after `goOnline` as
+reconnect — a `client.stop()`/`start()` handshake hung 30s on the static
+export. `maestro-e2e` follows the same static-export rule: it exports
+example-frontend and serves the static `dist`. If the browsers image has no
+Xvfb on `:99`, a `background: true` fallback starts one and keeps it alive
+for later steps.
+
+Package jobs that only lint/compile/test one workspace package stay on
+`medium` (including `mcp-server-ci`, `example-backend-ci`, and
+`new-file-coverage`). `coverage-scripts` is `small`. Do not put Docker Layer Caching on remote-docker jobs
+unless a profiled image build reuses layers enough to beat 200 credits/run.
 
 ## Nightly load test
 
@@ -144,30 +367,46 @@ pipeline parameters.
 ```
 
 This replaces the GHA cron / `workflow_dispatch` / `load-test` label triggers in
-`e2e-load-nightly.yml`.
+`e2e-load-nightly.yml`. Create a CircleCI schedule with
+`{"run-e2e-load":true}` at `0 6 * * *` to retain the nightly run.
 
 ## Local validation
 
+Map every CircleCI test job to a local command with
+[run tests locally](run-tests-locally.md). Config syntax:
+
 ```bash
 circleci config validate .circleci/config.yml
 circleci config validate .circleci/continue-config.yml
 ```
 
-## Dual-run drift
+## Disabled GitHub workflows
 
-While both systems run, keep these in sync when editing a GHA workflow:
+Package CI, e2e, and npm tag workflows stay `on: []`. Netlify/GCP deploy
+workflows are **re-enabled** until CircleCI contexts have the same secrets.
+After a successful CircleCI production or preview deploy, set
+`docs-deploy.yml`, `demo-deploy.yml`, `frontend-example-deploy.yml`, `cd.yml`,
+and `preview-cleanup.yml` back to `on: []` in the same PR. Never enable both
+npm tag publishers. Never leave both GCP terraform applies enabled.
 
-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
+## Cursor GitHub App checks
 
-## Not in this phase
+Do not try to run these on CircleCI. They are Cursor-hosted GitHub App
+automations (dashboard / GitHub App), not workflow files in this repo:
 
-- 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
+| Check | Why it stays on GitHub |
+| --- | --- |
+| Cursor Approval Agent: Pull Request Approver | Cursor cloud agent; posts its own GitHub check |
+| Cursor Security Agent: Security Reviewer | Same Cursor GitHub App path |
+| Cursor Bugbot | Same Cursor GitHub App path |
+
+The in-repo architectural reviewer (`cursor-agent` CLI +
+`.github/scripts/architectural-pr-review.ts`) is the job that *can* move, and it
+now runs on CircleCI.
+
+## Not in this phase
 
-Keep matching `.github/workflows/*` until dual-run cutover deletes them per phase.
+- Appium (Android emulator / iOS simulator)
+- CodeQL, Dependabot auto-merge, triage, gh-aw lockfile agentics
+- EAS PR updates and fingerprint acknowledgement
+- Cursor Approval / Security / Bugbot GitHub App checks

package/dist/docs/versioned/next/how-to/compare-chart-rendered-snapshots.md

@@ -0,0 +1,36 @@
+# Compare rendered chart snapshots
+
+JSON snapshots of the React tree do not prove chart paint. Terreno renders a gallery of
+easy-through-hard charts in the demo app and diffs those PNGs against goldens.
+
+1. Start from the repo root (reuses demo web on port 8085 if it is already up):
+
+   ```bash
+   bun run ui:charts:compare
+   ```
+
+2. Open `http://localhost:8085/demo/chart-visual-gallery` if you want to see the same
+   fixtures a person sees.
+
+3. On a mismatch, inspect:
+
+   - `demo/rendered-snapshots/<id>.png` — accepted render
+   - `demo/chart-visual-output/actual/<id>.png` — this checkout
+   - `demo/chart-visual-output/diff/<id>.png` — pixel highlight
+
+4. If the new paint is the intended design, write goldens:
+
+   ```bash
+   bun run ui:charts:update-snapshots
+   ```
+
+5. Limit one fixture while iterating:
+
+   ```bash
+   bun scripts/charts/compareRenderedSnapshots.ts --only=line-three-points
+   ```
+
+Agents reviewing a fail should follow the `review-chart-visuals` skill and look at the
+PNGs, not only the code diff.
+
+`CHART_VISUAL_BASE_URL` overrides the demo origin when the gallery is already hosted.

package/dist/docs/versioned/next/how-to/configure-better-auth.md

@@ -92,6 +92,31 @@ const buildBetterAuthConfig = (): BetterAuthConfig | undefined => {
 };
 ``````
 
+Set `publicAppUrl`, `sendMail`, and `renderAuthMail` from `@terreno/comms` so password-reset and
+email-verification mail match the JWT recovery templates. The hooks throw 501 and do not send when
+`publicAppUrl` is missing. JWT `POST /auth/resetPassword` updates the Better Auth password and
+deletes Better Auth sessions when this plugin is registered. Better Auth password reset updates
+the JWT password and `tokenEpoch` for the matching app User so dual-enrolled accounts cannot keep
+the old passport hash.
+
+```typescript
+import {getCommsService, renderAuthMail} from "@terreno/comms";
+
+const config: BetterAuthConfig = {
+  enabled: true,
+  publicAppUrl: process.env.FRONTEND_URL || "http://localhost:8082",
+  renderAuthMail,
+  sendMail: async (message) => {
+    await getCommsService().sendMail(message);
+  },
+  // ...
+};
+```
+
+Throwaway in-process seed apps (CLI / container smoke tests that call Better Auth
+sign-up many times) should set `disableRateLimit: true` on that instance only.
+Better Auth enables its limiter in production, which 429s the fourth seeded user.
+
 ### 3. Register BetterAuthApp Plugin
 
 Use the TerrenoApp plugin system:
@@ -120,19 +145,21 @@ const server = app.start();
 
 ### 4. Update User Model
 
-Add optional Better Auth fields to your User schema:
+`syncBetterAuthUser` creates the app `User` on the first authenticated request after Better Auth sign-up. Declare `betterAuthId` on that schema. Declare `oauthProvider` only if the app uses social OAuth.
 
-``````typescript
-import {betterAuthUserPlugin} from "@terreno/api";
+Email/password sync does **not** write `oauthProvider`. A `strict: "throw"` schema that omits the field stays valid. Social login still passes a provider string and requires the field.
 
-const userSchema = new mongoose.Schema({
-  email: {type: String, unique: true},
-  name: {type: String},
-  // ... other fields
-});
-
-// Adds: betterAuthId, oauthProvider
-userSchema.plugin(betterAuthUserPlugin);
+``````typescript
+const userSchema = new mongoose.Schema(
+  {
+    email: {type: String, unique: true},
+    name: {type: String},
+    betterAuthId: {index: true, sparse: true, type: String},
+    // Required only when using Google, GitHub, or Apple:
+    // oauthProvider: {type: String},
+  },
+  {strict: "throw"}
+);
 ``````
 
 ## Frontend Setup