@terreno/mcp 57.2.0 → 57.3.0

package/src/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,60 +22,118 @@ 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.
+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. Build forked PRs if you want DCO + rulesync on forks.
+
+GitHub App org/project slug (API and CLI):
+`circleci/6UHiK7pThPXbhnNi3umQNe/W3HZeMJujyMB2sYiUXaQbs`.
 
-Org/project slug: _(record after Phase 0.1 — e.g. `flourishhealth/terreno`)_.
+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.
-
-`.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.
+Smoke job `config-ok` and fork-only `dco` always run on continuation.
+`rulesync-check` runs only when generated-rule sources change (`run-rulesync`).
+
+`.circleci/**` sets `run-circleci-config`. On **config-only** PRs that workflow
+runs a representative slice (`api-ci`, `ui-ci`, `example-backend-ci`,
+`no-barrel-imports`, `source-rules`, `e2e` spec `login`). 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.
+
+## 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`. 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.
+
+The Netlify deploy helper validates its context before building, and the docs
+target disables Docusaurus minification for preview and production builds to
+remain within the available 8 GB CircleCI 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.
 
 | GHA job `name:` / workflow | CircleCI job |
 |----------------------------|--------------|
 | Repository policies / No barrel imports | `no-barrel-imports` |
+| Repository policies / Production source rules | `source-rules` |
 | Explicit any baseline | `explicit-any` |
 | License coverage | `license-coverage` |
 | Verify rules are in sync | `rulesync-check` |
@@ -80,6 +141,7 @@ checks appear as CircleCI job names in the GitHub Checks UI.
 | Run all tests (API CI) | `api-ci` |
 | Run all tests (AI CI) | `ai-ci` |
 | RTK Lint and Build | `rtk-ci` |
+| Syncdb Lint, Build, and Tests | `syncdb-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` |
@@ -96,41 +158,96 @@ checks appear as CircleCI job names in the GitHub Checks UI.
 | 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) |
+| Changelog fragments | `changelog-fragments` |
+| New file coverage | `new-file-coverage` |
+| 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.
 
 ## 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`, then shards attach that dist (60s test timeout, `large` Docker).
+Keeping Metro alive next to Chromium gets SIGKILL on 8GB. `xlarge` is not on
+this project's plan. 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.
 
 ## Nightly load test
 
@@ -144,7 +261,8 @@ 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
 
@@ -153,21 +271,33 @@ 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:
+
+| 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 |
 
-- 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
+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/src/docs/versioned/next/how-to/configure-better-auth.md

@@ -92,6 +92,27 @@ 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);
+  },
+  // ...
+};
+```
+
 ### 3. Register BetterAuthApp Plugin
 
 Use the TerrenoApp plugin system:
@@ -120,19 +141,21 @@ const server = app.start();
 
 ### 4. Update User Model
 
-Add optional Better Auth fields to your User schema:
-
-``````typescript
-import {betterAuthUserPlugin} from "@terreno/api";
+`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.
 
-const userSchema = new mongoose.Schema({
-  email: {type: String, unique: true},
-  name: {type: String},
-  // ... other fields
-});
+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.
 
-// 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

package/src/docs/versioned/next/how-to/connect-mcp-service-token.md

@@ -0,0 +1,110 @@
+# Connect an MCP client with a service token
+
+Mint a personal `mcp_…` Bearer key, then paste the MCP URL and key into Perplexity, Cursor, VS Code, or Claude Code.
+
+This is the **static-key** path for the consumer app's `POST /mcp`. It is not the hosted `@terreno/mcp` codegen server. For exposing tools, see [Expose MCP tools](expose-mcp-tools.md). Interactive OAuth for remote clients is a separate plan ([app MCP server](../implementationPlans/app-mcp-server.md)); do not send these keys in a query string.
+
+## 1. Enable the flag
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {
+    enabled: true,
+    publicMcpUrl: process.env.PUBLIC_API_URL,
+  },
+});
+```
+
+`mcpServiceTokens: true` is the same as `{enabled: true}`. Off (omitted or `enabled: false`) does not mount `/mcp/service-tokens` and does not accept `mcp_` Bearer credentials on `/mcp`.
+
+Pass `publicMcpUrl` so create responses include a copy-paste MCP URL (`…/mcp` is appended when missing). The example backend uses `PUBLIC_API_URL` or `BETTER_AUTH_URL`.
+
+## 2. Mint a token (Settings)
+
+1. Sign in to the example app.
+2. Open **Profile** → **MCP connections** (`/settings/mcp`).
+3. Enter a name (for example `Perplexity laptop`). Optionally set an expiry.
+4. Tap **Create token**.
+5. Copy the MCP URL, the full `mcp_…` secret, or the JSON snippet from the modal. The secret is shown **once**. Close the modal only after you have stored it in the client.
+
+Cap is **10** active tokens per user. List rows show prefix (`mcp_` + eight hex characters), last used, and expiry — never the full secret.
+
+## 3. Mint a token (curl)
+
+Use a session or JWT. A service token cannot mint another token.
+
+```bash
+curl -X POST "$API/mcp/service-tokens" \
+  -H "Authorization: Bearer $JWT" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Perplexity"}'
+```
+
+Read `data.token` and `data.mcpUrl` from the JSON. List and revoke never return `token`. Do not log the secret.
+
+## 4. Perplexity custom connector
+
+| Field | Value |
+| --- | --- |
+| MCP Server URL | `https://api.example.com/mcp` (use `data.mcpUrl` from create) |
+| Transport | Streamable HTTP |
+| Authentication | API Key |
+| API Key | full `mcp_…` string (Perplexity sends as Bearer) |
+
+Perplexity probes with GET, then POSTs JSON-RPC. Send the same key on both.
+
+GET does **not** authenticate. This server has no GET SSE stream, so `/mcp` answers `405` with `{"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."}}` whether or not the key is valid. That 405 is the expected probe — not a failed login.
+
+POST `initialize` and `tools/list` are the unauthenticated catalog in the stateless handler. Identity is checked when a **tool runs** (`tools/call`). A missing or invalid `mcp_` key then returns `Permission denied: authentication required`.
+
+## 5. Cursor, VS Code, Claude Code (JSON)
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer mcp_<secret-shown-once>"
+      }
+    }
+  }
+}
+```
+
+Replace the URL with `data.mcpUrl` and the Bearer value with the one-time `data.token`.
+
+## 6. Prove the key with curl
+
+```bash
+# Expected probe: JSON-RPC 405 "Method not allowed."
+curl -X GET "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream"
+
+# Catalog is unauthenticated. Identity is not proven here.
+curl -X POST "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
+
+# Identity check: tools/call as the owning user. Use a tool name from tools/list.
+curl -X POST "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"todos_list","arguments":{}}}'
+```
+
+A bogus key such as `mcp_deadbeef` on `tools/call` is denied. A valid key sees the same owner-scoped result as that user's REST session.
+
+The token acts as the owning user on **MCP only**. It cannot mint or list tokens, and it is not valid on REST, sync, or admin routes.
+
+## 7. Revoke
+
+- **Owner:** Profile → MCP connections → **Revoke** on the row (`DELETE /mcp/service-tokens/:id`).
+- **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete the row.
+
+Revoked and expired keys fail `tools/call` immediately. Disabled user accounts are refused the same way as over HTTP.

package/src/docs/versioned/next/how-to/create-a-model.md

@@ -32,7 +32,7 @@ export interface TodoModel extends DefaultModel<TodoDocument> {
 
 ### 2. Create the schema with field descriptions
 
-**Important:** Every field **must** include a `description` property. This flows through to the OpenAPI spec and makes generated SDK documentation more useful.
+**Important:** Every field **must** include a `description` property. Terreno's `describeModel()` reads descriptions into the canonical field graph; that graph feeds the OpenAPI spec, admin `/admin/config` field metadata, and MCP tool schemas.
 
 ``````typescript
 // src/models/todo.ts

package/src/docs/versioned/next/how-to/deploy-backend-to-cloud-run.md

@@ -104,6 +104,8 @@ Expect `"healthy": true`.
 | Websockets disconnect every few requests | No session affinity on Cloud Run | Add `--session-affinity` |
 | Socket connections drop after ~5 minutes | Default request timeout (300s) | Raise `--timeout` (for example `3600`) |
 | Live feature flags / realtime never update; log mentions replica set | MongoDB is standalone, not a replica set | Use Atlas or `replSet` — change streams required (`feature-flags/src/featureFlagsApp.ts`) |
+| Bun-compiled container never opens its port while creating indexes | OpenTelemetry Mongoose instrumentation patched an already-loaded Mongoose module | Do not explicitly patch Mongoose in the compiled binary; retain HTTP/Express tracing |
+| Container hangs before listening when cloud logging initializes | A network logging transport blocks startup | Log to stdout/stderr during boot; Cloud Run ingests both streams |
 | First request after idle is slow; sockets reconnect constantly | Scaled to zero | Set `--min-instances=1` for user-facing services |
 | Browser API calls blocked by CORS | `corsOrigin` / Better Auth `trustedOrigins` missing web origin | Add your CDN URL to backend CORS and auth config |
 

package/src/docs/versioned/next/how-to/deploy-to-gcp.md

@@ -26,9 +26,9 @@ Read the [deployment baseline](../explanation/deployment-baseline.md) — seven
 
 [Environment variables reference](../reference/environment-variables.md) — full list of backend and client config.
 
-## Legacy Flourish deployment
+## Operator-specific deployment
 
-Flourish-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives in `infra/flourish/` and the existing `demo-deploy.yml` / `frontend-example-deploy.yml` workflows. New deployments should follow the generalized guides above with your own `$PROJECT_ID` and bucket names.
+Vendor-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives outside these generalized guides. New deployments should follow the guides above with your own `$PROJECT_ID` and bucket names.
 
 ## Related
 

package/src/docs/versioned/next/how-to/expose-mcp-tools.md

@@ -48,9 +48,17 @@ to work while clients migrate.
 
 ### 3. Call the tools
 
-Point any MCP client at `POST /mcp` with the user's `Authorization: Bearer <token>` header. Both JWT and Better Auth sessions are accepted; the resolved user is what the permission checks run against, so an LLM can never see more than that user could see over REST.
+Point any MCP client at `POST /mcp`. Auth order on the Bearer header is:
 
-Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP.
+1. `mcp_…` service token, when `mcpServiceTokens` is enabled
+2. Better Auth session
+3. JWT
+
+The resolved user is what permission checks run against, so an LLM never sees more than that user could see over REST. Mint and paste a static key with [Connect an MCP client with a service token](connect-mcp-service-token.md).
+
+`initialize` and `tools/list` are the unauthenticated catalog. Identity is enforced on `tools/call`. GET `/mcp` is Streamable HTTP **405** (`Method not allowed.`) — there is no GET SSE stream; Perplexity still uses that 405 as a successful probe.
+
+Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP. Service tokens are MCP-only: they are rejected on `/mcp/service-tokens` and are not accepted on REST, sync, or admin.
 
 To run the same tools in-process (for example inside a chat route), use `getMCPTools`:
 

package/src/docs/versioned/next/how-to/github-actions-ci.md

@@ -0,0 +1,40 @@
+# GitHub Actions CI (Terreno)
+
+GitHub Actions is the CI of record. Operator map for the expensive jobs:
+[GitHub Actions CI](github-actions-ci.md). CircleCI twins are parked; see
+[CircleCI](circleci.md).
+
+## Docs site (`docs-deploy.yml`)
+
+`Build docs site` is often the longest PR job because Docusaurus compiles every
+versioned tree under `website/versioned_docs/` and TypeDoc regenerates API
+pages.
+
+PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
+`master` use Docusaurus Faster (Rspack/SWC via `@docusaurus/faster`).
+
+| Behavior | PR preview | `master` production |
+| --- | --- | --- |
+| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted (`disableVersioning`) | Built |
+| JS minify | Off | On |
+| Local search index | Skipped | Built |
+| Generated API + component MDX | Restored from cache when `api`/`rtk`/`ui` hashes match | Same cache, then full generate on miss |
+| TypeDoc workspace `tsc` | Once per generate (api+rtk deps share a process) | Same |
+| Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
+
+Production still builds every version. Do not rely on `/57.1.0/…` URLs in a
+PR deploy preview.
+
+## Other high-cost jobs
+
+| Workflow | What we skip or reuse |
+| --- | --- |
+| `e2e-ci`, `admin-spa-ci`, `admin-spa-integration` | Playwright Chromium under `~/.cache/ms-playwright`, keyed on `bun.lock`. E2E shards share one compile job (`workspace-dist` artifact) so required check names stay `E2E · <spec>`. |
+| `fingerprint-gate` | Master iOS/Android hashes cached per `pull_request.base.sha` (skips a second `bun run compile`) |
+| `maestro-e2e` | Demo export + static server only when `demo/`, `ui/`, or `.maestro/flows/demo/` change |
+| `example-backend-docker` | Buildx runs only when the image recipe changes (`Dockerfile`, lockfile, `package.json`). Source-only PRs skip; CD preview deploy still builds the image. `load: true` stays off. |
+| `cd` backend preview | Runs the built container against the configured Secret Manager values and requires a healthy `/health` response before pushing or deploying. |
+| Bun install | `.github/actions/setup-bun-workspace` pins Bun `1.4.0` and caches `~/.bun/install/cache` without `github.ref` in the key |
+
+Playwright e2e still uses one shard per spec file so required check names stay
+`E2E · <spec>`.