@terreno/mcp 57.14.0 → 57.16.1

package/dist/docs/versioned/57.15.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/dist/docs/versioned/57.15.0/how-to/run-tests-locally.md

@@ -0,0 +1,124 @@
+# 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            # lint, compile, 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.
+
+## 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` |
+| `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`.
+
+## 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` |
+| `e2e` `app` | `todos` `profile` `realtime` `ai-chat` `pdf` |
+| `e2e` `admin-core` | `admin` `admin-home` `admin-form` `admin-todo-crud` `admin-title-update-depth` |
+| `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.
+
+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`
+```
+
+## 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).

package/dist/docs/versioned/57.15.0/how-to/seed-a-database.md

@@ -0,0 +1,93 @@
+# Seed a database
+
+Use `runSeedCli` to keep development and test data aligned with code. Seed plans
+sync by default, can preview writes, and can reset only the data each step owns.
+
+## Define a seed plan
+
+```typescript
+import {runSeedCli, type SeedStep} from "@terreno/api";
+import mongoose from "mongoose";
+import {Todo} from "../models/todo";
+import {connectToMongoDB} from "../utils/database";
+
+const steps: SeedStep[] = [
+  {
+    name: "todos",
+    reset: async (context) => {
+      await context.deleteMany(Todo);
+    },
+    run: async (context) => {
+      await context.upsert(
+        Todo,
+        {seedKey: "welcome"},
+        {seedKey: "welcome", title: "Welcome to the app"}
+      );
+    },
+  },
+];
+
+const result = await runSeedCli({
+  allowProductionReset: () => process.env.ALLOW_SEED_RESET === "true",
+  connect: connectToMongoDB,
+  disconnect: async () => mongoose.disconnect(),
+  name: "bun run seed",
+  steps,
+});
+
+process.exit(result.exitCode);
+```
+
+Add the package command:
+
+```json
+{"scripts": {"seed": "bun run src/scripts/seed.ts"}}
+```
+
+## Run seeds
+
+```bash
+bun run seed                         # create or update code-defined data
+bun run seed --dry-run               # preview without writes
+bun run seed --only todos            # one step and its dependencies
+bun run seed --reset                 # reset managed data, then reseed
+```
+
+`--only` may be repeated. Declare `dependsOn` when one step needs records from
+another; dependencies run first. In reset mode, reset handlers run in reverse
+order so dependent records are removed before their parents.
+
+## Make sync runs idempotent
+
+Use `context.upsert(model, key, values)` with a stable, unique business key.
+The helper reports `created`, `updated`, or `unchanged` and writes only when the
+declared values differ. Nested arrays are compared without generated subdocument
+`_id`s, so feature-flag rules and similar payloads stay unchanged across syncs.
+`Map` values (for example consent-form `content`) compare as plain key/value
+objects so stored documents are not rewritten on every sync.
+If `isDeletedPlugin` hid a matching row, `upsert` restores that document instead
+of inserting a duplicate. If more than one document already shares the key,
+`upsert` keeps the first match, tombstones or deletes the extras, then syncs
+the survivor. Use `context.deleteMany()` only inside reset handlers.
+Custom writes must check `context.dryRun` themselves.
+
+The example backend seeds active, read, and archived notification rows for the default
+test user. This keeps the notification drawer and full history page populated for local
+development and browser tests.
+
+For Better Auth credentials, call `seedBetterAuthUser({auth, user, userModel})`.
+It creates a missing credential account, signs in when the account already
+exists, and reconciles the application user document.
+
+## Guard destructive resets
+
+Production reset mode is denied by default. It runs only when both conditions
+are true:
+
+1. The CLI receives `--force`.
+2. `allowProductionReset` returns `true` (normally from a dedicated environment variable).
+
+Reset handlers should delete only records owned by the seed plan. Preserve
+authentication, migration history (`terreno_migrations`), and operator-created
+data unless the plan explicitly manages them. Do not `dropDatabase` or delete
+the history collection in seed `--reset`.

package/dist/docs/versioned/57.15.0/how-to/set-up-terreno-mcp.md

@@ -0,0 +1,69 @@
+# Set up Terreno MCP
+
+Configure both Terreno servers: the hosted server supplies documentation and generators; the local
+stdio server inspects the app, database, logs, Metro, and Redux state.
+
+Install Bun 1.4 or newer to enable the local server's built-in WebView browser automation.
+
+## Cursor
+
+Add `.cursor/mcp.json` at the app repository root:
+
+```json
+{
+  "mcpServers": {
+    "terreno": {
+      "type": "http",
+      "url": "https://mcp.terreno.flourish.health/mcp"
+    },
+    "terreno-local": {
+      "command": "bunx",
+      "args": ["terreno-mcp-local"]
+    }
+  }
+}
+```
+
+## Claude Code
+
+Use the same project-scoped `.mcp.json`, or register the servers from the repository root:
+
+```bash
+claude mcp add --transport http terreno https://mcp.terreno.flourish.health/mcp
+claude mcp add terreno-local -- bunx terreno-mcp-local
+```
+
+## Configure local discovery
+
+Run the local server from the app root. It discovers bootstrap apps with `backend/` and `frontend/`,
+and this monorepo's `example-backend/` logs. Set these variables only when discovery needs help:
+
+| Variable | Use |
+| --- | --- |
+| `TERRENO_PROJECT_ROOT` | Absolute app/monorepo root |
+| `TERRENO_METRO_URL` | Metro origin when the frontend script does not expose `--port` |
+| `MONGO_URI` | MongoDB used by `database_schema` and read-only `database_query` |
+| `TERRENO_MCP_EVAL=1` | Explicitly enable `evaluate`, `navigate`, and SyncDB state changes |
+| `BUN_CHROME_PATH` | Chrome/Chromium/Edge binary when Bun cannot auto-discover one |
+
+Backend and browser JSONL normally live under `<backend cwd>/.terreno/logs/`. Keep Metro running to
+collect Metro `/events` and app console output over CDP. Hermes accepts one debugger connection, so
+close React Native DevTools if the local MCP reports that CDP is unavailable.
+
+## Verify
+
+Restart the editor's MCP clients, then ask it to call `application_info`. Confirm the result lists
+the app's installed `@terreno/*` versions. Next call `read_logs` with
+`{"sources":["backend","browser"]}`; an empty `entries` array is valid before the app logs anything.
+Call `browser` with `{"action":"open","url":"http://localhost:8082"}`, then `{"action":"snapshot"}`
+to confirm the agent can inspect the running web app. Finish with `{"action":"close"}`.
+If the app creates a SyncDB client with `debug: true`, call
+`get_syncdb_state` and confirm it returns the client name, status, collections,
+outbox, conflicts, cursors, and debug events.
+
+The CLI exposes the same local tools without MCP:
+
+```bash
+terreno info
+terreno logs --sources backend,browser
+```

package/dist/docs/versioned/57.15.0/how-to/ship-a-new-task-version.md

@@ -0,0 +1,76 @@
+# Ship a new task version
+
+Change a durable harness task without breaking runs that already started on the old code.
+Rules: [Versioning](../reference/ai-harness.md#versioning). Why:
+[Version pinning](../explanation/durable-agent-harness.md#version-pinning).
+
+## When to bump `version`
+
+Bump it on any change an in-flight task could notice:
+
+- A phase is renamed, removed, or added between existing phases.
+- The shape of `state`, `input`, or the result changes.
+- A phase's side effects or `replay` policy change.
+
+A fix that keeps the same phases, state shape, and side effects can ship under the same
+version.
+
+## Steps
+
+1. Copy the definition and bump `version`. Keep the old one unchanged.
+
+   ```typescript
+   export const intakeV1 = defineTask<IntakeInput, IntakeStateV1, IntakeResult>({
+     name: "clinic.intake",
+     version: 1,
+     // ...the old phases, untouched
+   });
+
+   export const intakeV2 = defineTask<IntakeInput, IntakeStateV2, IntakeResult>({
+     name: "clinic.intake",
+     version: 2,
+     // ...the new phases
+   });
+   ```
+
+2. Register both versions. Point new work at v2.
+
+   ```typescript
+   const harness = await Harness.open({registry: [intakeV1, intakeV2]});
+   await harness.start();
+
+   await harness.createTask(intakeV2, {patientId});
+   ```
+
+   Tasks created on v1 finish on v1's phases and v1's `abort` handler. New tasks run on
+   v2. Parent tasks that call `rt.createTask(intakeV1, ...)` keep making v1 children
+   until you change that call.
+
+3. Deploy. Every process that runs the harness needs the same registry.
+
+4. Wait until no v1 task is left in flight. Check in a Mongo shell:
+
+   ```javascript
+   db.harnesstasks.countDocuments({
+     name: "clinic.intake",
+     version: 1,
+     status: {$in: ["pending", "running", "waiting", "interrupted"]},
+   });
+   ```
+
+   Resolve stuck `interrupted` v1 tasks with `harness.resolveInterrupted`, or stop them
+   with `harness.abort`.
+
+5. When the count is 0, remove `intakeV1` from the registry and deploy again.
+
+## If you remove a version too early
+
+`Harness.start()` throws an `APIError` with code `harness-config-invalid` and claims
+nothing. Its `detail` reads:
+
+```text
+Harness.start: in-flight tasks use task versions this registry does not register: clinic.intake@1 (4 tasks). Register those definitions (keep old versions until their tasks finish) or resolve the tasks first.
+```
+
+Fix: add the old definition back to `registry` and redeploy. Its tasks resume from their
+last checkpoint.

package/dist/docs/versioned/57.15.0/how-to/test-ui-accessibility.md

@@ -0,0 +1,35 @@
+# Test UI accessibility
+
+Run the WCAG scanner against every changed rendered state:
+
+```bash
+bun run accessibility:scan \
+  "http://localhost:8085/dev/Theme?story=ThemeComponent&theme=light" \
+  "http://localhost:8085/dev/Theme?story=ThemeComponent&theme=dark"
+```
+
+The scanner applies axe rules tagged WCAG 2.0 A/AA, WCAG 2.1 A/AA, and WCAG
+2.2 AA. It writes a JSON report and full-page screenshots under
+`/opt/cursor/artifacts/accessibility/` and exits nonzero when any violation is
+found.
+
+## Verify what automation cannot
+
+1. Use only the keyboard to reach and operate each changed control.
+2. Confirm focus order and the visible focus indicator match the visual order.
+3. Inspect each control's accessible name, role, state, and error relationship.
+4. Check light and dark modes, plus loading, empty, disabled, and error states
+   affected by the change.
+5. At 200% browser zoom, confirm content remains usable without clipping or
+   losing actions.
+
+Automated scans do not prove keyboard behavior, announcement quality, reading
+order, or whether alternative text conveys the intended meaning. Record those
+manual checks with the automated report in the pull request Verification table.
+
+## Fixing findings
+
+Fix violations in the changed feature before submission. If a finding is
+pre-existing and outside the changed path, capture a baseline on an unaffected
+route and name both routes in the pull request. Do not suppress an axe rule
+without a linked issue and a documented reason.

package/dist/docs/versioned/57.15.0/how-to/track-upstream-expo.md

@@ -0,0 +1,52 @@
+# Track upstream Expo SDK betas
+
+Morning maintainer loop: see if Expo published a **new SDK major beta**, keep
+a long-lived `release-X.Y.Z` branch building, and leave a log so the next
+morning can resume.
+
+Agent procedure: skill `track-upstream-expo`. Upgrade commands: skill
+`upgrading-expo`. Log contract: skill reference `loop-log.md`.
+
+## 1. Probe
+
+From latest `master`:
+
+```bash
+bun run expo:track-probe
+```
+
+| Exit | Meaning |
+| --- | --- |
+| `1` | Nothing newer **and** no `open`/`blocked` loop. Stop. |
+| `0` | `create-branch`, `continue-branch` (newer beta), or `resume-loop` (same beta, unfinished). |
+| `2` | Probe broke (network/git). Fix that; do not skip. |
+
+The probe ignores patches of the current catalog major. It watches
+`expo@next` and `expo@latest` for a **higher major**, fetches `origin`
+`release-*` refs, then reads `loopStatus` from
+`origin/<releaseBranch>:scripts/track-upstream-expo/tracked.json`.
+
+State files (in the repo, not linked from this page):
+
+- `scripts/track-upstream-expo/tracked.json` — `expoVersion`, `loopStatus`
+- `scripts/track-upstream-expo/loop-log.md` — tries, failures, release-notes draft
+
+## 2. Branch name
+
+Expo `58.0.0-preview.1` → `release-58.0.0`. Create from `origin/master` the
+first day. Later days check it out, merge `master`, and either bump to a
+newer preview or resume **Open** items from the log.
+
+Do not merge `release-*` to master from this job.
+
+## 3. Native modules stay on the SDK train
+
+Packages that change the EAS fingerprint update **on this branch only**.
+
+## 4. Handoff every session
+
+Before edits: read `loop-log.md` (**Next**, **Open**, **Do not retry**).
+
+After edits: prepend **Tried**, refresh **Next** / **Open**, extend
+**Release notes draft**, set `loopStatus` to `open`, `blocked`, or `ready`,
+and push the release branch. Tomorrow starts from that commit.

package/dist/docs/versioned/57.15.0/how-to/update-dependencies.md

@@ -0,0 +1,63 @@
+# Update dependencies
+
+Routine version upgrades run through the `update-dependencies` skill (`/update-dependencies`). Dependabot opens **security PRs only**. The skill keeps one rolling PR; later runs push to it and rewrite its ledger instead of opening new PRs.
+
+```bash
+REPOSITORY="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
+OWNER="${REPOSITORY%%/*}"
+NAME="${REPOSITORY#*/}"
+gh pr list --state open --head chore/update-dependencies \
+  --json number,url,baseRefName,headRefName,headRepository,headRepositoryOwner,isCrossRepository \
+  | jq --arg owner "$OWNER" --arg name "$NAME" \
+      '[.[] | select(
+        .isCrossRepository == false and
+        .baseRefName == "master" and
+        .headRefName == "chore/update-dependencies" and
+        .headRepository.name == $name and
+        .headRepositoryOwner.login == $owner
+      )]'
+bun outdated
+```
+
+Prove each bump with an **exercise test** that imports that package. Verify the whole batch locally, then push **once**. Keep Expo fingerprints for `example-frontend` and `demo` unchanged. Skip `isFingerprintSkip` names until a release.
+
+Why: [Dependency management](../explanation/dependency-management.md). Native Expo/React Native bumps wait for `upgrading-expo`.
+
+## Do now
+
+1. Find the same-repository PR with exact head `chore/update-dependencies`, base `master`, and `isCrossRepository: false`. Marker/title matches are not trust signals; ignore forks. Merge `origin/master` without rewriting history. If no trusted PR exists, create the canonical branch on this run.
+2. Inventory with `bun outdated`. Retry **Failed** rows from the PR body first. Skip `isFingerprintSkip` in `scripts/planning/fingerprintRisk.ts`.
+3. For each candidate: confirm a test imports the package (add a tracer if needed), bump the catalog pin or single-use version, `bun install`, re-run that test, recompute fingerprints. Revert only that bump on failure. Commit each success as `Bump <name> from <old> to <new>`.
+4. Run the batch gate on the final head: `bun run compile`, `bun run lint`, `bun run prepush`. Run by hand any infra job `prepush` lists for a package you bumped (Playwright, Maestro, admin-spa integration). See [Run tests locally](run-tests-locally.md).
+5. Push once. Update the **same** PR body: Last run, local gate result, CI rounds, Landed, Failed, Skipped, Deferred to release. Do not `gh pr create` when that PR is already open.
+6. Read CI on the pushed head. Check each failed CircleCI job's `messages` before its step logs. Revert a bump that caused a failure and push a second time at most; stop and report anything else.
+
+## Guardrails
+
+| Rule | Action |
+| --- | --- |
+| Trusted rolling PR already exists | Push to its same-repository `chore/update-dependencies` head and edit that body |
+| Fork copies marker/title/branch | Ignore it; never checkout, copy, edit, close, or comment on it |
+| Fingerprint would change | Revert that bump. Defer to a release. Never add `fingerprint-acknowledged` |
+| No test imports the package | Write the tracer test first. Do not bump on `test:ci` alone |
+| Published < 7 days ago (non-CVE) | Skip; log under Skipped |
+| Major version | May land on the rolling PR if tests + fingerprints pass; no auto-merge |
+| Local gate red | Fix or revert before pushing. CI is not the test runner |
+| CI job has `messages` (for example `resource-class-not-in-plan`) | Config/plan error, not a dependency failure. Log it and stop |
+| A bump seems to need CI config changes | Never edit `.circleci/`, workflows, executors, or resource classes from this path. Stop and report |
+| CI red twice on heads this run pushed | Stop and report; do not push a third time |
+| Dependabot security PR is red | Do not push to `dependabot/*`. Fold the bump into the rolling PR |
+
+## Fingerprints
+
+`example-frontend` and `demo` use `fingerprint.config.js`. Hash with `eas fingerprint:generate` when `EXPO_TOKEN` is set, otherwise `bunx @expo/fingerprint <app-dir>`. Take a baseline after rebase, before new installs. After each successful bump, the new hashes become the baseline for the next package.
+
+`eas.json` Bun pins feed the fingerprint. Do not bump them here.
+
+## Who CI emails
+
+CircleCI attributes a pipeline to the GitHub user whose token pushed it and emails that user on each failed workflow. Run the scheduled agent with a bot identity when one is configured. If it runs as a person, the one-push rule caps their mail at one round per run.
+
+## Dependabot security PRs
+
+`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block, so Dependabot opens no version-update PRs. Security updates still open, grouped per block, and skip ignored native/Expo names. `dependabot-auto-merge.yml` approves them and enables squash auto-merge, so a green security PR merges without this skill. A red one gets its bump folded into the rolling PR. A security fix for an ignored native package is a manual release task (`release` + `upgrading-expo`).