@terreno/mcp 57.20.0 → 57.21.0

package/src/docs/versioned/57.20.0/how-to/set-up-terreno-mcp.md

@@ -0,0 +1,274 @@
+# Set up Terreno MCP
+
+Connect your editor to both Terreno MCP servers:
+
+- **`terreno`** (hosted, Streamable HTTP) supplies documentation search and code generators.
+- **`terreno-local`** (stdio, runs in your repository) reads the app's packages, database, logs,
+  Metro, and client state.
+
+Apps made with `create-terreno-app` already contain both configurations. Use this guide to check
+them, to add them to an older app, or to fix a server that does not connect.
+
+Prerequisites: Bun 1.4 or newer. The local server's bin is `#!/usr/bin/env bun`, and its `browser`
+tool needs Bun 1.4.
+
+## 1. Configure Cursor
+
+Create `.cursor/mcp.json` at the app repository root. This is the file `create-terreno-app` writes:
+
+```json
+{
+  "mcpServers": {
+    "expo": {
+      "type": "http",
+      "url": "https://mcp.expo.dev/mcp"
+    },
+    "playwright": {
+      "args": [
+        "-y",
+        "@playwright/mcp@0.0.76"
+      ],
+      "command": "npx"
+    },
+    "terreno": {
+      "type": "http",
+      "url": "https://mcp.terreno.app/mcp"
+    },
+    "terreno-local": {
+      "args": [
+        "-p",
+        "@terreno/mcp",
+        "terreno-mcp-local"
+      ],
+      "command": "bunx"
+    }
+  }
+}
+```
+
+Only `terreno` and `terreno-local` are required. `expo` and `playwright` are optional; see
+[step 5](#5-optional-add-expo-mcp-and-playwright-mcp).
+
+Keep `-p @terreno/mcp` in the `terreno-local` args. The bin is named `terreno-mcp-local`, but the
+npm package is `@terreno/mcp`. Without `-p`, `bunx` looks for an npm package named
+`terreno-mcp-local`, gets a 404, and the server never starts.
+
+Open the app repository root as the Cursor workspace. Then open Cursor's MCP settings and confirm
+each server is enabled and lists its tools. If `terreno-local` reports the wrong project root, set
+`TERRENO_PROJECT_ROOT` in its entry (step 4).
+
+## 2. Configure Claude Code
+
+Claude Code reads project servers from `.mcp.json` at the repository root. `create-terreno-app`
+writes the same content there as in `.cursor/mcp.json`, so the two files are byte-for-byte
+identical:
+
+```json
+{
+  "mcpServers": {
+    "expo": {
+      "type": "http",
+      "url": "https://mcp.expo.dev/mcp"
+    },
+    "playwright": {
+      "args": [
+        "-y",
+        "@playwright/mcp@0.0.76"
+      ],
+      "command": "npx"
+    },
+    "terreno": {
+      "type": "http",
+      "url": "https://mcp.terreno.app/mcp"
+    },
+    "terreno-local": {
+      "args": [
+        "-p",
+        "@terreno/mcp",
+        "terreno-mcp-local"
+      ],
+      "command": "bunx"
+    }
+  }
+}
+```
+
+Run `claude` from the repository root. On the first run, Claude Code asks you to approve the
+project's servers. Approve them. Then check the servers:
+
+```bash
+claude mcp list
+```
+
+A server you have not approved yet is listed as `⏸ Pending approval`. After approval, each server
+reports `✔ Connected`.
+
+To register the two Terreno servers without editing the file, run these commands from the
+repository root. `--scope project` writes the servers to `.mcp.json`:
+
+```bash
+claude mcp add --scope project --transport http terreno https://mcp.terreno.app/mcp
+claude mcp add --scope project terreno-local -- bunx -p @terreno/mcp terreno-mcp-local
+```
+
+## 3. Check the hosted endpoint
+
+The hosted server's URL is `https://mcp.terreno.app/mcp`. It speaks MCP Streamable HTTP
+(`"type": "http"`). `POST /` is accepted as an alias, but configure the `/mcp` path. Requests must
+send `Accept: application/json, text/event-stream`; MCP clients do this for you.
+`create-terreno-app` writes this URL into `.cursor/mcp.json` and `.mcp.json`. Use
+`--mcp-server-url` to point a new app at a different deployment.
+
+Check that the host answers:
+
+```bash
+curl -s https://mcp.terreno.app/
+```
+
+A working host returns `{"mcpEndpoint":"/mcp","service":"terreno-mcp","status":"ok"}`. If the
+command prints `Could not resolve host: mcp.terreno.app`, or the editor reports
+`getaddrinfo ENOTFOUND mcp.terreno.app`, that hostname does not resolve yet. Until it does, set the
+`terreno` URL to `https://mcp.terreno.flourish.health/mcp` in `.cursor/mcp.json` and `.mcp.json`. It
+serves the same service and tools.
+
+### Moving off `mcp.terreno.flourish.health`
+
+Earlier docs and scaffolds used `https://mcp.terreno.flourish.health/mcp`. That hostname serves the
+same Cloud Run service and keeps working for at least one release after the release that announces
+`mcp.terreno.app`. Replace the old URL in `.cursor/mcp.json`, `.mcp.json`, and any
+`claude mcp add` registration:
+
+For a project `.mcp.json`, edit the `url` in the file. For a registration you added with
+`claude mcp add` outside the project file, re-add it in the same scope:
+
+```bash
+claude mcp remove --scope local terreno
+claude mcp add --scope local --transport http terreno https://mcp.terreno.app/mcp
+```
+
+The operator cutover (domain mapping, DNS, retiring the old hostname) is in the
+[infra/flourish README](https://github.com/TerrenoLabs/terreno/blob/master/infra/flourish/README.md#hosted-mcp-hostname).
+
+## 4. Give the local server what it needs
+
+`terreno-local` starts without any of the items below, but each tool reads only what it can find.
+The full rules are in the
+[local server reference](../reference/mcp-server.md#local-server-terreno-mcp-local).
+
+| Need | What to do |
+| --- | --- |
+| Project root | Start the editor in the app repository root. The server walks up from its working directory looking for a `package.json` with `backend/` and `frontend/` workspaces, and otherwise uses the working directory itself. Apps from `create-terreno-app` have no root `package.json`, so the walk-up never matches from a subfolder: start the editor at the app root or set `TERRENO_PROJECT_ROOT`. |
+| A reachable MongoDB | Put `MONGO_URI` in `backend/.env` (`create-terreno-app` does this) or export it. `database_schema` and `database_query` use it. |
+| Backend log file | Run the backend with `bun run dev`. Outside production the `@terreno/api` logger writes `backend/.terreno/logs/app.log`, which `read_logs` and `last_error` read. |
+| Metro for app logs | Keep `bun run web` (or `start`, `ios`, `android`) running in `frontend/`. The server reads Metro on the script's `--port` (8082 in generated apps). Set `TERRENO_METRO_URL` for another origin. |
+
+Set environment variables for the server in its config entry with `env`. For example, to point the
+server at a root and allow the gated tools:
+
+```json
+"terreno-local": {
+  "args": [
+    "-p",
+    "@terreno/mcp",
+    "terreno-mcp-local"
+  ],
+  "command": "bunx",
+  "env": {
+    "TERRENO_MCP_EVAL": "1",
+    "TERRENO_PROJECT_ROOT": "/absolute/path/to/my-app"
+  }
+}
+```
+
+`TERRENO_MCP_EVAL=1` enables `evaluate`, `navigate`, and SyncDB state changes; leave it out unless
+you need them. Every variable is listed under
+[Environment variables](../reference/mcp-server.md#environment-variables).
+
+Hermes accepts one debugger connection. Close React Native DevTools if the local server reports
+that CDP is unavailable.
+
+## 5. Optional: add expo-mcp and Playwright MCP
+
+`create-terreno-app` adds two more servers next to the Terreno ones. Keep them when you want the
+agent to drive the app, or delete their entries from both files:
+
+- **`expo`** (`https://mcp.expo.dev/mcp`) takes screenshots and taps in the iOS simulator or
+  Android emulator. It asks you to sign in with your Expo account the first time it connects. Its
+  simulator tools also need the `expo-mcp` dev package in the app
+  (`cd frontend && bunx expo install expo-mcp --dev`) and a dev server started with
+  `EXPO_UNSTABLE_MCP_SERVER=1`, which the generated frontend scripts already set. See
+  [Expo MCP Server](https://docs.expo.dev/eas/ai/mcp/).
+- **`playwright`** (`npx -y @playwright/mcp@0.0.76`) drives the web app in a full browser. The
+  version is pinned so `npx` does not resolve a moving `@latest`.
+
+These servers interact with the app. Terreno's servers observe what the app did behind the screen.
+Read [How this composes](../explanation/ai-development-loop.md#how-this-composes) for the division
+of labor, including when a flow should become a Maestro test.
+
+## 6. Verify
+
+1. Restart the editor's MCP clients.
+2. Ask the agent: "Call the `application_info` tool from `terreno-local`."
+3. Confirm the result lists your app's `@terreno/*` packages. For an app generated with
+   `create-terreno-app` and no `bun install` yet, the result is (project root shortened):
+
+   ```markdown
+   # Application info
+
+   - **projectRoot**: `…/setup-check`
+   - **root package**: (none) @ ?
+   - **bun.lock present**: no
+
+   ## Backend workspace (backend/)
+   - **name**: @setup-check/backend
+   - **version**: 1.0.0
+   - @terreno/admin-backend: ^57.14.0
+   - @terreno/api: ^57.14.0
+   - @terreno/api-health: ^57.14.0
+   - **mongoose**: 9.7.4
+   - **@types/bun**: ^1.4.0
+
+   ## Frontend workspace (frontend/)
+   - **name**: @setup-check/frontend
+   - **version**: 1.0.0
+   - @terreno/admin-frontend: ^57.14.0
+   - @terreno/rtk: ^57.14.0
+   - @terreno/syncdb: ^57.14.0
+   - @terreno/ui: ^57.14.0
+   - **expo**: ~57.0.14
+   - **react**: 19.2.3
+   - **react-native**: 0.86.2
+   - **@types/bun**: ^1.4.0
+   ```
+
+   The versions are the ranges declared in each `package.json`, not resolved versions. If
+   `projectRoot` is not your app, set `TERRENO_PROJECT_ROOT` (step 4).
+4. Ask the agent to call `terreno_search_docs` from `terreno` with any query. A list of doc results
+   confirms the hosted server.
+
+With the backend and frontend running, check the runtime tools too:
+
+- Call `read_logs` with `{"sources":["backend","browser"]}`. An empty `entries` array is valid
+  before the app logs anything. A `create-terreno-app` app sends web console errors and warnings
+  to the backend with `installTerrenoDevConsoleLogger({baseUrl})` in `frontend/app/_layout.tsx`.
+  Its `backend/.env` sets `NODE_ENV=development`, which the backend needs to accept them. In
+  another app, add the same call at startup and run the backend with `NODE_ENV=development` or
+  `TERRENO_BROWSER_LOGS=true`.
+- Call `browser` with `{"action":"open","url":"http://localhost:8082"}`, then
+  `{"action":"snapshot"}`, to confirm the agent can inspect the web app. Finish with
+  `{"action":"close"}`.
+- If the app creates its 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
+```
+
+## Related
+
+- [MCP server reference](../reference/mcp-server.md): every tool, variable, and discovery rule
+- [Debug a Terreno app with MCP](debug-with-mcp.md): the loop on a real failure
+- [AI development loop](../explanation/ai-development-loop.md): how the servers fit together

package/src/docs/versioned/57.20.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/src/docs/versioned/57.20.0/how-to/show-loading-skeletons.md

@@ -0,0 +1,74 @@
+# Show loading skeletons
+
+Show placeholders in the shape of your content while it loads, instead of a spinner. Every
+container in `@terreno/ui` takes the same `loading` props. See
+[Loading states and skeletons](../reference/ui.md#loading-states-and-skeletons) for every prop
+and default.
+
+## Skeleton a Box
+
+Pass `loading` and a `loadingComponent` built from skeleton primitives:
+
+```tsx
+import {Box, SkeletonList} from "@terreno/ui";
+
+<Box loading={isLoading} loadingComponent={<SkeletonList rows={3} />} padding={4}>
+  {todos.map((todo) => <TodoRow key={todo.id} todo={todo} />)}
+</Box>
+```
+
+Without `loadingComponent`, the Box shows three lines of `SkeletonText`.
+
+## Choose an animation
+
+Set `loadingAnimation` on the container: `"pulse"` (default), `"shimmer"`, or `"none"`. Every
+skeleton inside picks it up and animates in sync.
+
+```tsx
+<Card loading={isLoading} loadingAnimation="shimmer">
+  <ProfileSummary user={user} />
+</Card>
+```
+
+Animations turn off on their own when the OS reduce-motion setting is on.
+
+## Skeleton cards, charts, and pages
+
+- `Card`, `EditableCard`: `loading` replaces the content. A display `Card` defaults to a
+  `SkeletonCard`, with media when it has `imageUri`.
+- `ChartCard`, `Scorecard`: `loading` keeps the title and replaces the body or value.
+- Charts, `Page`, `SplitPage`: `loading` still shows a spinner. Pass `loadingComponent` to show a
+  skeleton instead.
+
+```tsx
+<Page loading={isLoading} loadingComponent={<SkeletonCard showMedia />} title="Profile">
+  <ProfileScreen />
+</Page>
+```
+
+## Add loading to your own component
+
+Wrap it once with `withLoading`:
+
+```tsx
+import {SkeletonList, withLoading} from "@terreno/ui";
+
+const UserRowWithLoading = withLoading(UserRow, {loadingComponent: <SkeletonList rows={1} />});
+
+<UserRowWithLoading loading={isLoading} user={user} testID="user-row" />
+```
+
+While loading it renders a busy `Box` with test id `user-row-loading`. Use it only for a component
+that has no `loading` prop of its own.
+
+## Test it
+
+Skeletons are hidden from screen readers, so React Native Testing Library needs
+`includeHiddenElements` to find them:
+
+```tsx
+expect(getByTestId("list-skeleton", {includeHiddenElements: true})).toBeTruthy();
+expect(getByTestId("todos").props["aria-busy"]).toBe(true);
+```
+
+In Playwright, `getByTestId` finds them as usual.

package/src/docs/versioned/57.20.0/how-to/sign-consent-on-behalf.md

@@ -0,0 +1,139 @@
+# Sign consent on a user's behalf
+
+Let staff record consent for a user ahead of time, for example after a guardian agrees by
+phone at intake. The form counts as signed from then on, and the user still sees it and signs
+it themselves. Concepts: [Consent forms](../explanation/consent-forms.md#provisional-signatures).
+
+## 1. Pass access control to ConsentApp
+
+Add `userSchema.plugin(rbacUserPlugin)` (from `@terreno/api`) to your User schema so users
+have a `roles` field and role assignments are saved. Then wire RBAC into the app:
+
+```typescript
+import {
+  backfillAdmins,
+  ConsentApp,
+  createAccess,
+  rbacRouter,
+  TerrenoApp,
+  terrenoStatements,
+} from "@terreno/api";
+
+const access = createAccess({
+  connection: mongoose.connection,
+  statements: terrenoStatements,
+  userModel: User,
+});
+
+// After connecting to MongoDB: create or update the built-in roles.
+await access.roles.seedDefaults();
+// Give existing `admin: true` users the superadmin role, so they keep their access.
+await backfillAdmins({access, userModel: User, wetRun: true});
+
+new TerrenoApp({accessControl: access, userModel: User})
+  .register(rbacRouter({access, userModel: User}))
+  .register(new ConsentApp({accessControl: access, auditTrail: true}))
+  .start();
+```
+
+With `accessControl`, any authenticated user whose roles grant
+`consentResponse:signOnBehalf` may sign, read statuses, and void for other users. Without it,
+only `user.admin` users may, and `ConsentApp` logs a warning at startup. With
+`accessControl`, `user.admin` alone no longer grants signing: the user needs a role that
+grants it. Turn on
+`auditTrail` to keep the signer's IP address and user agent and a snapshot of the content they
+signed. `rbacRouter` mounts the `/rbac` role API used in step 2.
+
+Register `AuditApp` too if you want every provisional signature, status read, and void in the
+audit log.
+
+## 2. Grant the permission
+
+The built-in `admin` role includes `consentResponse: ["signOnBehalf"]`. Databases created
+before this release get it the next time roles are seeded (`access.roles.seedDefaults()`),
+without losing other grants on an unsealed `admin` role. `superadmin` has every action.
+
+For staff who are not admins, create a role and assign it. `$TOKEN` must belong to a user
+whose roles grant `rbac:manageRoles` and `rbac:assignRoles`, such as `superadmin`; the
+built-in `admin` role has neither.
+
+```bash
+curl -X POST "$API/rbac/roles" -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "intake-staff", "displayName": "Intake staff",
+       "permissions": {"consentResponse": ["signOnBehalf"]}}'
+
+curl -X PUT "$API/rbac/users/$STAFF_USER_ID/roles" -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" -d '{"roleNames": ["intake-staff"]}'
+```
+
+There is no relationship check: a permitted signer can sign for any user. Give the role only
+to staff who should have that reach.
+
+## 3. Mount the signer screen
+
+```tsx
+import {Page, ProvisionalConsentSigner} from "@terreno/ui";
+import {useLocalSearchParams} from "expo-router";
+import {terrenoApi} from "@/store/sdk";
+
+const ConsentSignScreen: React.FC = () => {
+  const {userId} = useLocalSearchParams<{userId: string}>();
+  return (
+    <Page backButton title="Sign consent on behalf">
+      <ProvisionalConsentSigner api={terrenoApi} userId={userId} />
+    </Page>
+  );
+};
+```
+
+Put the route outside your admin area if non-admin staff use it. The component lists every
+form that applies to the user with its status. Staff open a pending form, read it,
+write a note saying how consent was obtained, and sign. The user then sees "Signed on your
+behalf by <name> on <date>" above the form in their consent gate, but not the note.
+
+Build your own UI with `useProvisionalConsent({api, userId})` instead, which returns
+`statuses`, `sign`, and `voidSignature`.
+
+## 4. Check whether a user is considered signed
+
+```typescript
+import {getConsentStatuses} from "@terreno/api";
+
+const rows = await getConsentStatuses({resolveConsentForms, userId});
+const canSchedule = rows.filter((row) => row.form.required).every((row) => row.isConsented);
+```
+
+`isConsented` is true for `signed` and `provisional`. The user's own answer always wins: once
+they agree the row is `signed`, and once they decline it is `declined`. Pass the same
+`resolveConsentForms` you gave `ConsentApp`. Clients call `GET /consent-responses/status?userId=`
+for the same rows.
+
+## 5. Void a signature made in error
+
+In `ProvisionalConsentSigner`, press "Void" on a provisional row and give a reason. Over HTTP:
+
+```bash
+curl -X POST "$API/consent-responses/$RESPONSE_ID/void" -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" -d '{"reason": "Signed for the wrong member"}'
+```
+
+The record stays, with `voidedAt`, `voidedBy`, and `voidReason` set. The form returns to
+`pending` and the user's notice disappears.
+
+## 6. Print a consent record
+
+- `ProvisionalConsentSigner`: "Print" on a provisional, signed, or declined row, or on the
+  confirmation after signing.
+- Admin: the "Print" button on `ConsentResponseViewer` (`@terreno/admin-frontend`).
+- The user's own history: the print icon on a `ConsentHistory` entry
+  (`@terreno/admin-frontend`).
+
+When the record is provisional, the printout includes a "Provisional signature" section with
+the signer and date. Staff and
+admin printouts also show the note; the user's own printout never does. To print your own
+HTML, call `printConsentHtml({html: buildConsentPdfHtml(data)})` from `@terreno/ui`.
+
+Reference: [ConsentApp](../reference/api.md#consent-forms-consentapp),
+[consent components](../reference/ui.md#consent-components),
+[consent records and PDFs](../reference/admin-frontend.md#consent-records-and-pdfs).

package/src/docs/versioned/57.20.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/src/docs/versioned/57.20.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.