@terreno/mcp 57.20.0 → 57.22.0

package/src/docs/versioned/57.21.0/how-to/recover-locked-out-user.md

@@ -0,0 +1,112 @@
+# Recover a locked-out user
+
+Help a user who lost their authenticator, passkey, or social account get back in. Platform
+staff use `/users/:id/security`; org-admins use `/orgs/:orgId/members/:userId/security`. Both
+run the same handlers, and every change writes a security `AuditEvent`.
+
+## Before you start
+
+1. Register `AuditApp` and `AccountSecurityApp` on the `TerrenoApp`:
+
+   ```typescript
+   import {AccountSecurityApp, AuditApp, BetterAuthApp, TerrenoApp} from "@terreno/api";
+
+   new TerrenoApp({accessControl: access, organizations: true, userModel: User})
+     .register(new BetterAuthApp({config: betterAuthConfig}))
+     .register(new AuditApp())
+     .register(new AccountSecurityApp())
+     .start();
+   ```
+
+2. For `disable` and `enable`, apply `isDisabledPlugin` to the User schema.
+3. For `send-password-reset`, set `sendMail` and `publicAppUrl` in `BetterAuthConfig`.
+4. For the org path, turn organizations on (`organizations: true`). `TerrenoApp` hands the
+   registered `AccountSecurityApp` to `OrgsApp`, which mounts the org routes.
+
+## Who can do what
+
+| Action | Route suffix | Platform staff (`user:manageSecurity`) | Org-admin of the user's org |
+| --- | --- | --- | --- |
+| Read the summary | `GET /security` | Yes | Yes |
+| Reset two-factor | `POST /security/reset-two-factor` | Yes | Yes |
+| Remove a passkey | `DELETE /security/passkeys/:passkeyId` | Yes | Yes |
+| Unlink a provider | `DELETE /security/accounts/:providerId` | Yes | Yes |
+| Sign out everywhere | `POST /security/revoke-sessions` | Yes | Yes |
+| Send a password reset | `POST /security/send-password-reset` | Yes | Yes |
+| Disable or enable the account | `POST /security/disable`, `/enable` | Yes | No |
+| Suspend the membership | `POST /security/suspend-membership` | Through the org path | Yes |
+| Issue a sign-in link | `POST /security/issue-sign-in-link` | `superadmin` only (`user:issueSignInLink`) | No |
+
+`superadmin` and `operator` hold `user:manageSecurity`. An org-admin is a user whose active
+`Membership` in that org has `roleName: "org-admin"`.
+
+Nobody can act on themselves, or on someone who holds a permission they lack. An org-admin can't
+reach platform staff or `admin: true` users, members of other orgs, or suspended members. Platform
+staff on the org path are judged the same way as on the platform path, so an org-only permission
+does not block them.
+
+## Platform path
+
+Prefix every route with `/users/<userId>`.
+
+1. Read the summary to see the user's sign-in methods and the actions that apply:
+
+   ```bash
+   curl -H "Authorization: Bearer $TOKEN" https://api.example.com/users/<userId>/security
+   ```
+
+   `data.actions` lists only the actions that apply to this user and that you may run.
+2. Run the action that fixes the problem:
+   - Lost authenticator: `POST .../reset-two-factor`. The user signs in with their password and
+     can enroll again.
+   - Lost device with a passkey: `DELETE .../passkeys/<passkeyId>` (ids are in the summary).
+   - Lost social account: `DELETE .../accounts/<providerId>`.
+   - Stolen device: `POST .../revoke-sessions`.
+   - Forgotten password: `POST .../send-password-reset`.
+   - Compromised account: `POST .../disable`. Later, `POST .../enable`.
+   - Legacy user with no password and no inbox: `POST .../issue-sign-in-link`, then give the
+     user the returned link yourself. Only a superadmin can do this.
+3. Removing the user's last sign-in method answers `409` unless their email is verified. With a
+   verified email, the route also mails a password reset.
+
+## Org path
+
+Prefix every route with `/orgs/<orgId>/members/<userId>`. The user must be an active member of
+`<orgId>`. They may belong to other orgs too.
+
+1. Read the summary: `GET /orgs/<orgId>/members/<userId>/security`.
+2. Run the same recovery actions as the platform path (2FA, passkey, provider, sessions, reset).
+3. To cut the user off from your org, run `POST .../suspend-membership`. It suspends only their
+   membership in `<orgId>`. They still sign in and keep their other orgs.
+4. To bring a suspended member back, use the membership route:
+   `PATCH /orgs/<orgId>/members/<memberId>` with `{"status": "active"}`. A suspended member is out
+   of reach of the security routes until then.
+
+To stop an org-admin from attaching an existing user by email and acting on them right away, set
+a minimum membership age:
+
+```typescript
+new TerrenoApp({
+  accessControl: access,
+  organizations: {orgRecovery: {minMembershipDays: 7}},
+  userModel: User,
+});
+```
+
+## Check the audit trail
+
+Every change is one `AuditEvent` with `source: "security"`. Org actions carry the org's id in
+`organizationId`. When `sendMail` is configured, each change also emails the user (except
+`send-password-reset`, whose reset email is the notice). For `issue-sign-in-link` the email says a
+link was created, never the link itself. The email says "an administrator" and never names you;
+see
+[Notifications](../reference/account-security.md#notifications).
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://api.example.com/audit-events?source=security&recordId=<userId>"
+```
+
+Related: [Account security reference](../reference/account-security.md),
+[How organization tenancy works](../explanation/organizations.md#member-recovery),
+[Enable the framework audit log](audit-log.md).

package/src/docs/versioned/57.21.0/how-to/release-automation.md

@@ -0,0 +1,83 @@
+# How to let agents merge release notes and roadmap updates
+
+An agent (or the scheduled roadmap workflow) opens a pull request. The **Bot merge** workflow
+([`.github/workflows/bot-merge.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/bot-merge.yml))
+merges it after CI passes. No human review is needed. For a release it then tags the merged commit,
+and that tag starts CircleCI `publish-release`. The packages are built from the tagged commit, so the
+release notes are already in each npm tarball.
+
+```text
+release/X.Y.Z PR ──► Bot merge waits for CI ──► squash-merge (bot bypass)
+                                                   │
+                                                   ▼
+                     tag X.Y.Z on the squash commit + draft GitHub release
+                                                   │
+                                                   ▼
+            CircleCI publish-release: require merged notes ──► npm publish
+                                                    (every tarball ships CHANGELOG.md)
+```
+
+## What the bot merges
+
+[`scripts/ci/release/lib.ts`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/ci/release/lib.ts)
+(`planBotMerge`) decides eligibility. A pull request qualifies only if all of these are true:
+
+- It comes from a branch in this repository. Drafts and forks are skipped.
+- Its author is listed in the `BOT_MERGE_AUTHORS` repository variable. Logins are compared without regard to case.
+- Its branch name and changed files match one of the rows below.
+
+| Branch | Files it may change |
+|--------|---------------------|
+| `release/X.Y.Z` or `cursor/release-X.Y.Z` (stable versions only) | `CHANGELOG.md`, `changelog/unreleased/*`, `example-frontend/constants/whatsNew.generated.json`, `mcp-server/src/docs/upgrades/*.md` |
+| `automation/roadmap-*` | `ROADMAP.md`, `docs/explanation/roadmap-seed-issues.md` |
+
+A release branch also needs a non-empty `## [X.Y.Z]` section in its `CHANGELOG.md`. The workflow
+uses `pull_request_target`, so both the workflow file and the eligibility script come from
+`master`. A pull request cannot change its own eligibility rules. The job never runs pull request
+code; it reads file names and `CHANGELOG.md` through the API. Any pull request that fails a rule keeps a green **Bot merge** check and waits
+for a human. Examples are a release pull request that also edits a skill, or a prerelease branch.
+
+The `master` ruleset requires no status checks, so the workflow does that job itself. It waits
+until every other check on the head commit has passed, including GitHub Actions and CircleCI
+statuses. It merges with the head SHA pinned, so a push made after the checks finished blocks the
+merge.
+
+## The publish gate
+
+`publish-release` runs
+`bun run scripts/ci/release/cli.ts check-tag <tag> <on-master>` before it compiles anything. A
+stable tag fails if any of these is true:
+
+- The tagged commit is not on `master`.
+- `CHANGELOG.md` has no non-empty `## [X.Y.Z]` section.
+- Fragments are left in `changelog/unreleased/`.
+
+Prerelease tags (`-beta.N`) skip the gate; they are often cut from a feature branch.
+
+The manual fallback `.github/workflows/publish-on-tag.yml` runs the same `check-tag` gate. It also
+fails unless it was dispatched from the tag itself, because its publish jobs build the dispatched
+ref, not the tag by name. Use **Run workflow** with the tag selected as the ref.
+
+`scripts/ci/prepare-package-publish.mjs` copies the root `CHANGELOG.md` into each package before
+`npm publish`. Packages that declare a `files` whitelist list `CHANGELOG.md` in it.
+
+## One-time GitHub setup
+
+1. Create a GitHub App under **TerrenoLabs → Settings → Developer settings → GitHub Apps**. Turn
+   off webhooks. Give it these repository permissions:
+   - Contents: read and write
+   - Pull requests: read and write
+   - Metadata: read
+
+   Install it on `TerrenoLabs/terreno` only.
+2. Generate a private key. Add it as the repository secret `BOT_MERGE_PRIVATE_KEY`. Add the
+   App ID as the repository variable `BOT_MERGE_APP_ID`.
+3. Set the repository variable `BOT_MERGE_AUTHORS` to the logins allowed to open bot-merged pull
+   requests, separated by commas. Include the account that owns `ROADMAP_PROJECT_TOKEN`, which
+   opens the roadmap pull requests.
+4. Add the App as an **Always** bypass actor on both `master` rulesets (**Branch** and
+   **master protection**). Its token can then squash-merge without an approving review.
+
+Once these are set, the agent's job ends at opening the pull request. Steps 5b–5c of the
+[`release` skill](https://github.com/TerrenoLabs/terreno/blob/master/.rulesync/skills/release/SKILL.md)
+describe that hand-off.

package/src/docs/versioned/57.21.0/how-to/run-harness-on-multiple-instances.md

@@ -0,0 +1,93 @@
+# Run the harness on multiple instances
+
+Run durable harness tasks on every instance of a scaled-out backend (for example several
+Cloud Run instances). Swap the default `InProcessRunner`, where one process drains every
+task, for `JobsRunner`, which runs each phase as a `@terreno/jobs` job. API:
+[AI harness reference → JobsRunner](../reference/ai-harness.md#jobsrunner). Why it is safe:
+[Durable agent harness → Runners](../explanation/durable-agent-harness.md#runners).
+
+You need a working harness (see [Build a durable workflow](build-a-durable-workflow.md)) and
+a MongoDB replica set. Task data does not change, so you can switch runners without a
+migration.
+
+## 1. Install the jobs package (1 minute)
+
+`@terreno/jobs` is an optional peer of `@terreno/ai`. Add it to the app:
+
+```bash
+bun add @terreno/jobs
+```
+
+## 2. Open the harness with a JobsRunner (5 minutes)
+
+Create the `JobsApp` first, hand it to the runner, and register it on the app. Build the
+app before the harness starts: `harness.start()` throws when no `JobsApp` is registered.
+The runner defines the `terreno.harness.phase` job on it.
+
+```typescript
+import {Harness} from "@terreno/ai/harness";
+import {JobsRunner} from "@terreno/ai/harness/jobsRunner";
+import {TerrenoApp} from "@terreno/api";
+import {JobsApp} from "@terreno/jobs";
+
+const jobs = new JobsApp();
+const harness = await Harness.open({
+  registry: [intakeSummary, summarizer],
+  runner: new JobsRunner({jobs}),
+});
+
+const app = new TerrenoApp({userModel: User}).register(jobs);
+// ...register HarnessApp and your routes, then build or start the server.
+app.start();
+
+await harness.start();
+await jobs.startWorker();
+```
+
+Shut down in the reverse order so phases in flight finish:
+
+```typescript
+await harness.stop(); // stops dispatching, waits for this instance's phases
+await jobs.stopWorker();
+```
+
+## 3. Run the same code on every instance
+
+Every instance runs the same startup. Each one:
+
+- scans for runnable tasks and enqueues one job per runnable phase (duplicates collapse on
+  the job's idempotency key),
+- runs phase jobs from the shared jobs queue, and
+- sweeps task leases that expired because an instance died.
+
+No instance is special, and none waits on standby.
+
+## 4. Check it works (2 minutes)
+
+1. Start two backend processes against the same database (different `PORT`s).
+2. Create a task (for the example backend, run `startClinicalIntake`).
+3. Open the admin **Jobs** screen. Each phase shows as its own `terreno.harness.phase` job
+   with payload `{taskId}`.
+4. Kill one process mid-phase. Within one lease (`leaseDuration`, default 30 s) the other
+   process replays a `replay: "safe"` phase, or parks any other phase as `interrupted`.
+
+## Tune it
+
+| Want | Set |
+| --- | --- |
+| Faster pickup of new work | `new JobsRunner({jobs, pollInterval: {milliseconds: 200}})` and `new JobsApp({pollIntervalMs: 200})` |
+| Faster crash recovery | A shorter `leaseDuration` with `heartbeatInterval` about a third of it |
+| Phases longer than the jobs lock TTL | Nothing: the task lease, renewed by heartbeats, decides who commits |
+
+## Troubleshoot
+
+- **Jobs fail with `harness-runner-stopped`.** A jobs worker runs on an instance whose
+  harness is not started. Start the harness before `jobs.startWorker()`. The jobs worker
+  retries the job, so no task is lost.
+- **`harness.start()` throws "JobsRunner needs a registered JobsApp".** The dispatcher
+  enqueues through the registered jobs service, and `TerrenoApp` registers plugins when it
+  builds. Call `app.start()` (or `build()`) before `harness.start()`.
+- **A task stays `pending`.** Check that its `name@version` is in the registry of the
+  running instances. A runner only dispatches registered versions.
+- **Pick one runner per database.** Mixing them is safe (every claim and commit is fenced),
+  but an `InProcessRunner` owner then claims tasks itself and runs them to a stop.

package/src/docs/versioned/57.21.0/how-to/run-mongodb-migrations.md

@@ -0,0 +1,127 @@
+# Run MongoDB migrations
+
+Use `terreno-migrate` for schema and data changes that must run once per environment. Keep ad-hoc admin scripts for one-off maintenance.
+
+## Add a file
+
+Put TypeScript modules in `migrations/`:
+
+```text
+migrations/20260910120000-add-todos-index.ts
+```
+
+The exported `id` must match the filename stem. `up` is required; `down` is optional.
+
+```typescript
+export const id = "20260910120000-add-todos-index";
+
+export const up = async ({dryRun, mongoose}): Promise<void> => {
+  if (dryRun) {
+    return;
+  }
+  await mongoose.connection.collection("todos").createIndex({owner: 1});
+};
+
+export const down = async ({dryRun, mongoose}): Promise<void> => {
+  if (dryRun) {
+    return;
+  }
+  await mongoose.connection.collection("todos").dropIndex("owner_1");
+};
+```
+
+## First apply
+
+1. Generate a draft from the current models vs the last `schemaAfter` snapshot:
+   `terreno-migrate generate --dir ./migrations --models ./src/models.ts`
+2. Dry-run pending files (no history write):
+   `terreno-migrate up --dir ./migrations --dry`
+3. Apply for real:
+   `terreno-migrate up --dir ./migrations`
+4. In production, set `ALLOW_MIGRATIONS=true` and pass `--force` on that last command.
+
+If generate prints `No schema changes`, there is nothing to apply. Replace any fail-closed stub in the new file before step 2.
+
+## Commands
+
+`terreno-migrate` is the `@terreno/api` bin. `up`, `down`, and `status` need `MONGO_URI` or `MONGODB_URI`.
+
+| Command | Mongo | Effect |
+|---------|-------|--------|
+| `terreno-migrate check --dir ./migrations` | No | Load and validate files (CI) |
+| `terreno-migrate generate --dir ./migrations --models ./src/models.ts [--name slug]` | No | Diff current models vs last `schemaAfter`; write one file or print `No schema changes` |
+| `terreno-migrate status --dir ./migrations` | Yes | List applied and pending ids |
+| `terreno-migrate up --dir ./migrations [--dry] [--force]` | Yes | Apply pending `up` in filename order |
+| `terreno-migrate down --dir ./migrations [--dry] [--force] [--steps N]` | Yes | Roll back the last `N` applied files (default 1) |
+
+`--dry` calls `up`/`down` with `dryRun: true` and does **not** write `terreno_migrations` history. Authors must no-op writes when `dryRun` is true.
+
+`down` fails with `Migration has no down` when the target file omits `down`. History stays unchanged.
+
+## What generate can emit
+
+`buildSchemaCatalog` / `diffSchemaCatalog` classify model changes. `terreno-migrate generate` writes one file per non-empty diff:
+
+| Diff | Safe? | Generated `up` |
+|------|-------|----------------|
+| Add optional field | Yes | Snapshot only (Mongo is schemaless); comment, no write |
+| Add / drop non-unique index | Yes | `createIndex` / `dropIndex`, skipped when `dryRun` |
+| Add required field (no default) | No | Fail-closed stub that throws in dry-run and wet until you write a backfill |
+| Unique index | No | Fail-closed stub (valid JavaScript `throw`) |
+| Rename (removed + added field, same type) | No | Fail-closed stub |
+| Remove field | No | Fail-closed stub |
+| Same-path type change | No | Fail-closed stub |
+
+A file with any unsafe op is still a throw stub (dry-run and wet). Safe `createIndex` /
+`dropIndex` calls are kept as comments in that stub and listed in the throw message.
+
+Do not inspect the live database during generate. Baseline is the last `schemaAfter` snapshot in `migrations/`.
+
+## Admin HTTP
+
+Pass `migrations: {dir: "./migrations"}` into `AdminApp`. Both routes are
+`modelRouter` collection actions under the `adminMigrations` OpenAPI tag, so they appear in
+`/openapi.json` and in generated SDKs. Then:
+
+| Method | Path | Gate | Effect |
+|--------|------|------|--------|
+| GET | `/admin/migrations/status` | `admin:access` (or `IsAdmin`) | Applied, pending, lock (`{data: ...}`) |
+| POST | `/admin/migrations/run?wetRun=true\|false` | `admin:runScripts` (or `IsAdmin`) | `{data: {taskId}}` — one BackgroundTask (`migrations:up`) |
+| GET/DELETE | `/admin/scripts/tasks/:id` | `viewBackgroundTasks` / `runScripts` | Poll or cancel that task |
+
+Dry-run and Apply use the same `admin:runScripts` gate as Scripts (`platformTools.runScripts`
+disables the buttons when the caller cannot run scripts). Status listing stays on
+`admin:access`. Collection-action permission denials are **405** (modelRouter). Admin wet
+in production still needs `ALLOW_MIGRATIONS=true` (**403**). The admin UI is
+**Migrations** under Platform (`/admin/__migrations` or `/console/__migrations`):
+status list plus Dry run / Apply pending. Task logs poll `GET /admin/scripts/tasks/:id`.
+
+## Example app
+
+`example-backend` keeps files in `migrations/` and wires `resolveExampleMigrationsDir()` into
+`TerrenoApp` and `AdminApp`. From `example-backend/`:
+
+```bash
+bun run migrate:check
+bun run migrate:status
+bun run migrate:up
+```
+
+Compiled deploys (`bun build --compile`, Cloud Run) cannot scandir `$bunfs`. The example
+Dockerfile copies `migrations/` to `/app/migrations` and sets `MIGRATIONS_DIR`. GET
+`/admin/migrations/status` returns **404** `Migration directory not found` when that path is
+missing, not a generic 500.
+
+
+## Production wet apply
+
+`NODE_ENV=production` wet `up`/`down` requires both:
+
+1. `ALLOW_MIGRATIONS=true`
+2. `--force`
+
+Dry-run is allowed in production without those. Non-production wet apply does not need `--force`.
+
+## History and lock
+
+Applied ids live in Mongo collection `terreno_migrations` (lock row `_id: "_lock"`). Do not wipe that collection in seed `--reset`. See [Seed a database](seed-a-database.md).

package/src/docs/versioned/57.21.0/how-to/run-tests-locally.md

@@ -0,0 +1,251 @@
+# Run Terreno tests locally
+
+Every CircleCI test job has a local command. On Cursor Cloud, run the failed tests
+from the last CI run with these commands before pushing.
+
+Package unit tests use in-memory Mongo from `@terreno/test`. Playwright, Maestro, and
+the example-backend **dev** server need a replica-set `mongod` (see
+[AGENTS.md](https://github.com/TerrenoLabs/terreno/blob/master/AGENTS.md) Cursor Cloud
+section).
+
+## Do now — prepush mirrors CI
+
+```bash
+bun run prepush            # compile, lint + typecheck, then every CI job this branch triggers
+bun run prepush --dry-run  # print the plan only
+bun run prepush --all      # every check, regardless of changed files
+```
+
+`prepush` diffs committed, staged, unstaged, and untracked files against the merge-base
+with `origin/master`. It applies the CircleCI path-filter mapping in
+`.circleci/config.yml`, then runs the local command for each triggered job: package
+`test:coverage` plus the 90% new-file LCOV gate, `ui` types, demo typecheck,
+example-backend and example-frontend tests, every `repo-policies` step, rulesync drift,
+and the typedoc API reference when `api/src` or `rtk/src` changes. Every step runs even
+after a failure, so a single pass lists every problem. Fix them all, then push once.
+
+Jobs that need infrastructure (Playwright e2e, Maestro, admin-spa integration, Docker)
+are listed at the end with the command to run by hand. A test in
+`scripts/ci/prepush/plan.test.ts` fails when the mapping gains a parameter that
+`prepush` neither runs nor lists.
+
+## Typecheck
+
+Every package has a `typecheck` script that runs `tsc` with its
+`tsconfig.typecheck.json`. That config extends the build `tsconfig.json`, emits
+nothing, and includes the test files the build excludes (`*.test.ts(x)`,
+`*.isolated.ts(x)`, `src/tests/**`). Root `bun run lint` ends with `bun run typecheck`.
+CircleCI runs it in the `typecheck` job beside `repo-policies`.
+
+```bash
+bun run compile                # typecheck reads workspace packages' dist types
+bun run typecheck              # every package
+cd ui && bun run typecheck     # one package
+```
+
+## Package tests
+
+From the repo root after `bun bootstrap`:
+
+```bash
+bun run test          # every workspace `test:ci`
+bun run test:agent    # same suites; passing cases suppressed
+```
+
+Closest package during a red/green cycle:
+
+```bash
+bun test --only-failures <path>
+```
+
+| CircleCI job | Local command |
+| --- | --- |
+| `api-ci` | `bun run api:test` |
+| `ai-ci` | `cd ai && bun run test:ci` |
+| `blocks-ci` | `bun run blocks:test` |
+| `ui-ci` | `bun run ui:test` |
+| `rtk-ci` | `bun run rtk:test` |
+| `syncdb-ci` | `bun run syncdb:test` |
+| `comms-ci` | `bun run comms:test` |
+| `jobs-ci` / jobs package | `bun run jobs:test` |
+| `mcp-server-ci` | `cd mcp-server && bun run test:ci` |
+| `create-terreno-app-ci` | `cd create-terreno-app && bun run test:ci` |
+| `packages-ci` (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `test`) | `cd <package> && bun run test:ci` |
+| `example-backend-ci` | `cd example-backend && bun run test:ci` |
+| `smoke` | `bun run smoke` (see [Package smokes](#package-smokes-smoke)) |
+| `example-frontend-ci` | `bun run frontend:test` |
+| `ui-demo-ci` | `cd demo && bun run test:ci` then `bun run check:demo-coverage` |
+| `new-file-coverage` | `bun run check:new-file-coverage --base=origin/master --threshold=90` |
+| `repo-policies` | `bun run prepush` (runs every repo-policies step) |
+
+Coverage gate for a published package: `cd <package> && bun run test:coverage`.
+
+## Package smokes (`smoke`)
+
+The CircleCI `smoke` job runs on any package change. It compiles the workspace, builds
+the admin-spa, demo, and example-frontend smoke web exports, installs Playwright Chromium, then runs every
+workspace `smoke` script against the job's replica-set Mongo sidecar
+(`TERRENO_TEST_MONGODB_URI`). `prepush` lists it with the command below instead of
+running it.
+
+`bun run smoke:local` runs every step below in order. Run them yourself to reuse builds:
+
+```bash
+bun run compile
+(cd admin-spa && bun run build:web) && (cd demo && bun run export)
+(cd example-frontend && bun run export:smoke)
+bunx playwright install --with-deps chromium   # once
+bun run smoke              # every package; prints each one's time, flags any over 30 s
+bun run smoke api rtk      # only these workspaces
+```
+
+A package over 30 s is flagged, not failed: the CircleCI `smoke` job's table judges the budget
+([smoke conventions](../testing/e2e.md#smoke-conventions)). If a browser smoke fails with
+`Executable doesn't exist`, the preinstalled Playwright browsers do not match the locked
+version; install Chromium with `PLAYWRIGHT_BROWSERS_PATH=$HOME/.cache/ms-playwright` set and run
+`bun run smoke` with the same variable.
+
+Without `TERRENO_TEST_MONGODB_URI`, a smoke that needs Mongo starts its own in-memory
+replica set. To reuse a local replica-set `mongod`, export
+`TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0"` first.
+
+## Playwright (example-frontend e2e)
+
+1. Install Chromium once: `cd example-frontend && bunx playwright install --with-deps chromium`
+2. Start a replica-set `mongod` on `127.0.0.1:27017` (Cursor Cloud steps in AGENTS.md).
+3. Re-run one failed spec (Playwright starts backend + web if they are not up):
+
+```bash
+cd example-frontend
+MONGO_URI="mongodb://127.0.0.1:27017/terreno-e2e?replicaSet=rs0" \
+  bunx playwright test e2e/<spec>.spec.ts --reporter=list
+```
+
+| CircleCI shard | Specs |
+| --- | --- |
+| `e2e` `auth` | `login` `signup` `consents` `forgot-password` `reset-password` `verify-email` `two-factor` |
+| `e2e` `app` | `todos` `profile` `realtime` `ai-chat` `pdf` |
+| `e2e` `admin-core` | `admin` `admin-home` `admin-form` `admin-todo-crud` `admin-title-update-depth` `org-admin-security` `admin-user-security` |
+| `e2e-cross-site` (not required) | the cross-site specs below, then `account-linking` with `E2E_ACCOUNT_LINKING=explicit` |
+| `e2e` `admin-table` | `admin-table-search-filter` `admin-table-bulk-actions` `admin-custom-screens` `admin-comms-back` `harness-approvals` `harness-intake` |
+| `e2e` `syncdb` | `syncdb-load-delta` `syncdb-offline` `syncdb-conflicts` `syncdb-storage` `syncdb-chaos` |
+
+Full local suite: `bun run frontend:e2e`. Nightly load (`e2e-load` / `syncdb-loadlab`) is
+not PR-blocking; run `bunx playwright test e2e/syncdb-loadlab.spec.ts` only when that job
+failed.
+
+The cross-site specs (`CROSS_SITE_SPEC_FILES` in `playwright.config.ts`:
+`e2e/crossSiteBearer.spec.ts`, `e2e/crossSiteOAuth.spec.ts`, `e2e/authMethods.spec.ts`,
+`e2e/crossSiteChallenges.spec.ts`, `e2e/crossSiteLogin.spec.ts`,
+`e2e/account-linking.spec.ts`, `e2e/account-security.spec.ts`) run in CircleCI's `e2e-cross-site` job, which is not a required
+check, rather than in an `e2e` shard: they need
+a web server built with `EXPO_PUBLIC_API_URL=http://127.0.0.1:4000` and
+`EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true`, a backend with
+`BETTER_AUTH_URL=http://127.0.0.1:4000`, `BETTER_AUTH_OAUTH_HANDOFF=true` and
+`MOCK_OIDC_ISSUER` (the login page shows the mock provider's button because
+`/api/auth/terreno/methods` then lists `mock-oidc`), and the mock OIDC provider on
+`127.0.0.1:4555`. Naming any of those spec files (or
+setting `E2E_CROSS_SITE_BEARER=true`) makes `playwright.config.ts` start all three and run only
+the cross-site specs, so stop any other backend on 4000 and web server on 8082 first:
+`cd example-frontend && E2E_CROSS_SITE_BEARER=true bunx playwright test`. CI serves a static
+export instead of a Metro dev server, which gets OOM-killed bundling beside the backend and
+Chromium. To run the specs exactly as `e2e-cross-site` does:
+
+```bash
+cd example-frontend
+EXPO_PUBLIC_API_URL=http://127.0.0.1:4000 EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true \
+  bun expo export --platform web --output-dir dist-cross-site --clear
+bunx serve dist-cross-site -s -l 8082 &
+CI=true E2E_CROSS_SITE_BEARER=true MONGO_URI="mongodb://127.0.0.1:27017/terreno-e2e?replicaSet=rs0" \
+  bunx playwright test --config playwright.circleci.config.ts --reporter=list
+```
+
+`--clear` matters: Metro's cache keeps the `EXPO_PUBLIC_*` values of an earlier export. A new
+spec that needs
+the mock provider or cookie-less sessions joins `CROSS_SITE_SPEC_FILES` and the
+`cross-site-bearer` shard in `scripts/ci/e2eAffected/shards.ts`.
+
+`e2e/account-linking.spec.ts` has cases for the backend's `explicit` linking mode, which skip
+unless the backend reports that mode. `E2E_ACCOUNT_LINKING=explicit` starts the backend with
+`AUTH_ACCOUNT_LINKING=explicit`; run that spec alone, because the other specs expect the default
+`verified-email` (`e2e-cross-site` does this as its second step):
+`cd example-frontend && E2E_ACCOUNT_LINKING=explicit bunx playwright test e2e/account-linking.spec.ts`.
+
+### Deployed bearer smoke (`deploy-frontend-preview`)
+
+`netlify-deploy.sh frontend` builds the web app with `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true`
+for production and previews. After the preview deploy, the `deploy-frontend-preview` job's
+"Smoke the deployed preview in web bearer mode" step runs `bun run smoke:deployed`
+(`playwright.smoke.config.ts`, `e2e/deployedBearer.smoke.ts`) against
+`https://pr-<n>--terreno-frontend.netlify.app`. It signs up a new `smoke-*@example.com` user on
+the PR's own backend, agrees to the consent forms, reloads, opens the profile, and fails if the
+API's origin holds a Better Auth session cookie. It also checks that the Google button's OAuth
+handoff start link redirects (to the provider, or back to `/login?error=provider_not_found`)
+instead of returning 404; `gcp-deploy.sh` sets `BETTER_AUTH_OAUTH_HANDOFF=true` on both backends.
+Production deploys never run it. To re-run it:
+
+1. Against the PR preview, which takes about 1 minute:
+
+   ```bash
+   cd example-frontend
+   SMOKE_BASE_URL=https://pr-<n>--terreno-frontend.netlify.app \
+     SMOKE_API_URL=https://pr-<n>---terreno-backend-example-7knxlrnpqq-uc.a.run.app \
+     bun run smoke:deployed
+   ```
+
+2. Against a local cross-site stack, which takes about 5 minutes because of the web export.
+   Start the backend with Better Auth on `127.0.0.1:4000`, then build and serve the web app
+   with the flag on `localhost:8082` (a different site):
+
+   ```bash
+   # Terminal 1, from example-backend/ (the replica-set mongod from step 2 above)
+   AUTH_PROVIDER=better-auth BETTER_AUTH_URL=http://127.0.0.1:4000 PORT=4000 \
+     BETTER_AUTH_OAUTH_HANDOFF=true \
+     MONGO_URI="mongodb://127.0.0.1:27017/terreno-smoke?replicaSet=rs0" \
+     TOKEN_SECRET=dev TOKEN_ISSUER=dev REFRESH_TOKEN_SECRET=dev SESSION_SECRET=dev \
+     bun run src/index.ts
+   # Terminal 2, from example-frontend/. --clear: Metro's cache can keep an earlier
+   # build's EXPO_PUBLIC_* values.
+   EXPO_PUBLIC_API_URL=http://127.0.0.1:4000 EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true \
+     bun run export --clear && bunx serve dist -s -l 8082
+   # Terminal 3, from example-frontend/
+   SMOKE_BASE_URL=http://localhost:8082 bun run smoke:deployed
+   ```
+
+CircleCI skips a shard no changed file can reach. Ask for the same verdict before
+pushing with `bun run check:e2e-affected` (see
+[the affected gate](circleci.md#e2e-affected-gate)).
+
+## Admin SPA
+
+```bash
+cd admin-spa
+bun run test:ci
+bunx playwright install --with-deps chromium
+bun run test:e2e
+bun run test:integration    # needs Mongo + example-backend; job `admin-spa-integration`
+```
+
+For `test:integration`, start example-backend with `ADMIN_SPA_ENABLED=true`,
+`AUTH_PROVIDER=better-auth`, and, for the MCP OAuth consent spec, `MCP_OAUTH_ENABLED=true` and
+`PUBLIC_API_URL=http://localhost:4000`. Without the last two the consent spec is skipped.
+
+## Maestro web e2e
+
+Install CLI if missing: `curl -fsSL "https://get.maestro.mobile.dev" | bash`, then put
+`$HOME/.maestro/bin` on `PATH`.
+
+```bash
+bun run maestro:test
+```
+
+Demo-only flows: `bun run demo:maestro:test`. Job `maestro-e2e` uses a static web export
+plus replica-set Mongo; local Maestro talks to the running example-frontend on 8082.
+
+## Taste mapping
+
+When CircleCI names a failed test, copy the file/case from the log and run the matching
+row above. Record that command in Taste `checks.ev`. Re-run it after the fix and before
+`git push`. `bun run prepush` does not replace that re-verify.
+
+Appium Android/iOS is not in CircleCI (Maestro web covers those flows).