@terreno/mcp 57.19.2 → 57.21.0

package/src/docs/versioned/next/explanation/responsive-design.md

@@ -0,0 +1,143 @@
+# Responsive design
+
+Terreno apps run on desktop web and native mobile. Responsive behavior follows the workflow, the available viewport, and how important that workflow is on that surface.
+
+The goal is not to make every screen work everywhere. The goal is the best experience on the devices and workflows people actually use. Design specs name the supported breakpoints and the support level for each feature. Implement and test only those behaviors.
+
+Breakpoints are viewport width in points, not a device model and not a physical screen resolution. Browser chrome, a resized window, split screen, and display scaling all change the available width.
+
+## Surfaces
+
+Primary devices define the design target. Support for other devices comes from the breakpoint system.
+
+| Surface | Who it is for | Where it runs | Design target | Role |
+| --- | --- | --- | --- | --- |
+| Desktop web | People doing data-heavy work | Web, validated in Chrome | 13" laptop at `xl` (≥ 1280pt), such as a MacBook Air 13" | Primary experience. Full functionality, including complex review and multi-panel workflows. |
+| Primary mobile | People whose main experience is the phone or tablet | iOS and Android | Large phone / small tablet at native `lg` (600–1023pt), such as a Samsung A11 | Full supported mobile workflows. |
+| Reduced mobile | People who need emergency or lightweight access | iOS and Android | Common phones | A reduced set of workflows. Not a replacement for desktop. |
+
+Other browsers are outside the desktop support contract. Do not create a layout for an individual phone or tablet model.
+
+## Support levels
+
+Every feature names one of these levels at each breakpoint it claims.
+
+| Level | Definition | Example |
+| --- | --- | --- |
+| Fully supported | Designed and tested at this breakpoint. Intended workflows work. | A filter with search, groups, saved filters, and bulk actions on desktop `lg` and `xl`. |
+| Supported with adaptation | Still fully usable. Layout or interaction is simpler so it fits. | The same filter on a tighter width becomes one category at a time, or moves advanced options behind an "Advanced filters" action. |
+| Functionally available | Essential workflows can be finished. Complexity is intentionally omitted. | On reduced mobile, the filter keeps search and one or two high-value filters. |
+| Not supported | Not available, not optimized, or not guaranteed. | The advanced filter below the minimum supported breakpoint. The app may still open. Layout and functionality are not guaranteed. |
+
+### What a feature spec must define
+
+| Item | Required? |
+| --- | --- |
+| Supported surfaces (desktop web, primary mobile, reduced mobile) | Yes |
+| Supported breakpoints (`sm`, `md`, `lg`, `xl`) | Yes |
+| Support level at each of those breakpoints | Yes |
+| Behavior when a breakpoint is not supported | Yes |
+| Layout changes at supported breakpoints | When the layout changes |
+
+## Breakpoints
+
+Tokens are platform-specific. `lg` is not the same width on web and native. The tables and the constants `WEB_BREAKPOINT_MIN_WIDTH` and `NATIVE_BREAKPOINT_MIN_WIDTH` are the same contract. API details: [Media query helpers](../reference/ui.md#media-query-helpers).
+
+### Desktop web
+
+The desktop web app is optimized for desktop. The minimum supported desktop breakpoint is `lg`.
+
+| Category | Token | Viewport | Meaning |
+| --- | --- | --- | --- |
+| Primary desktop | `xl` | ≥ 1280pt | Full desktop layouts, multi-panel workflows, dense data. |
+| Smaller desktop | `lg` | 1024–1279pt | Minimum supported desktop. Collapse secondary content, adjust panels, or simplify controls. Keep core workflows. |
+| Below supported desktop | below `lg` | < 1024pt | Not a supported desktop experience. The app may stay reachable. Layouts are not guaranteed. |
+
+On web, `sm` (320) and `md` (375) still classify widths below 1024 so a layout can stay reachable.
+
+Test `xl` fully, including complex layouts and multi-panel interactions. Test `lg` to confirm critical workflows stay usable when space shrinks. Do not do breakpoint-specific testing below `lg`. Degrade gracefully there when it is cheap.
+
+### Native mobile
+
+| Category | Token | Viewport | Meaning |
+| --- | --- | --- | --- |
+| Extra large | `xl` | ≥ 1024pt | Not a supported mobile layout. Use desktop web where it exists. |
+| Large mobile / tablet | `lg` | 600–1023pt | Primary tablet experience. Optimize supported mobile workflows here. |
+| Standard mobile | `md` | 375–599pt | Common phone. Supported workflows stay usable. |
+| Small mobile | `sm` | 320–374pt | Small phone. Critical workflows stay functional. Extra scrolling or a simpler layout is expected. |
+| Below supported mobile | below `sm` | < 320pt | Not supported. The app may stay reachable. Layouts are not guaranteed. |
+
+Test native `lg`, `md`, and `sm` unless the spec says otherwise. Do not do breakpoint-specific testing below `sm`.
+
+A larger mobile screen does not automatically get the desktop layout. Use a breakpoint only when the layout actually changes.
+
+`isSupportedDesktopWidth({width})` is the desktop floor: web `lg` and native `xl`, both 1024pt. Below that, do not ship a desktop multi-panel layout.
+
+## Adapting a layout
+
+### Desktop
+
+Support a primary laptop display, a resized browser window, split screen, and a smaller window that is still inside `lg` or `xl`. Keep the workflow as width drops inside that range.
+
+When width drops:
+
+- Collapse secondary panels.
+- Allow horizontal scrolling for a dense table.
+- Move secondary actions into an overflow menu.
+- Reduce spacing before removing content.
+
+Do not shrink content until it is unreadable, compress a layout into a strip, or hide a critical workflow with no other way to reach it.
+
+### Native
+
+Mobile layouts favor finishing the task over matching desktop feature parity.
+
+Reduced mobile, when a desktop workflow is too complex:
+
+- Simplify the workflow.
+- Reduce the available actions.
+- Keep the high-value, time-sensitive tasks.
+- Send people to desktop when the workflow needs it.
+
+Do not recreate a desktop layout on mobile, support every desktop workflow, show a dense table or a multi-panel layout, or require a lot of horizontal scrolling.
+
+Primary mobile should stay clear, readable, touch-friendly, and focused on the supported workflows.
+
+## Checklist
+
+Before building a new experience, answer these:
+
+1. Is this desktop-only, mobile-only, or both? Is the workflow required on reduced mobile, or only on primary mobile?
+2. What is the minimum supported width? When space decreases, does content collapse, stack, scroll, or hide?
+3. What is the primary goal, which information is essential, and which actions are secondary?
+4. Does this need a breakpoint, or a mobile variant of a component? Does it match an existing responsive pattern?
+
+## Framework component audit
+
+Audited against this policy. Pixel cutoffs that were not a breakpoint token were moved onto `isSupportedDesktopWidth`.
+
+| Component | Result |
+| --- | --- |
+| `Box` responsive props (`sm` / `md` / `lg` / `xl`) | Compliant. One shared dimension listener. The largest matching token wins. |
+| `DashboardGrid` | Compliant. Column counts follow `sm`, `md`, and `lg` (`xl` uses the `lg` count). |
+| `SplitPage` (web) | Compliant. Side-by-side layout follows `isNarrowViewport()` unless the caller passes `narrowBelowWidth`. |
+| `SplitPage` (native) | Compliant. Stacked list/detail at every native width, including tablet `lg`. Native tablets do not inherit the desktop split. |
+| `Modal` | Compliant. Action sheet on native, centered dialog on web. |
+| `DataTable` | Partial. Web keeps inline filters. Native collapses filters into one sheet. Horizontal scroll stays on for wide tables, including native, which is more scrolling than reduced mobile should require. |
+| `Text` / `Heading` | Compliant. Separate web and native type scales. Type does not shrink again inside `sm`. |
+| `Card` | Fixed. Container and display variants used a 768pt cutoff. They now follow the desktop floor. |
+| `MarkdownEditor` | Fixed. Side-by-side edit/preview used a 768pt cutoff. It now follows the desktop floor. |
+| `AdminShell` | Fixed. The sidebar became a hamburger drawer below 768pt. It now does that below the desktop floor. |
+| `AdminFilterDrawer` | Fixed. The bottom sheet used the same 768pt cutoff. It now follows the desktop floor. `ADMIN_FILTER_MOBILE_BREAKPOINT` is 1024. |
+| `AdminHome` | Fixed. Main and sidebar stay side by side only at or above the desktop floor, and only when the dashboard is not embedded. Below the floor they stack. |
+| Admin SPA shell | Compliant. It wraps `AdminShell`, so it uses the same floor. |
+| Example app screens | Compliant. `maxWidth={800}` is a content measure. Toolbars that sit in a row also wrap. No second pixel cutoff. |
+| Sync debugger | Fixed. The event list and JSON inspector stack below the desktop floor. The screen still uses raw `View` and `Text` on purpose. |
+| Demo headers | Fixed. Back-button visibility and header margin followed `isNarrowViewport()` once at module load. They now follow the desktop floor and update when the window resizes. |
+| Demo stories (Tooltip, Multiselect, Accordion) | Fixed. Width switches followed a one-time `isNarrowViewport()` read. They now follow the desktop floor and update on resize. |
+| Admin action rows | Partial. Some rows (`ConsentHistory`, consent editors) stay in one row without `wrap`. They are not a second breakpoint. |
+| `DateTimeField` | Partial. Inline controls switch to an action sheet when the parent is narrower than 395pt, and also when `isNarrowViewport()` is true. 395pt is the field's own minimum, not a viewport token. |
+| `Image` (`fullWidth`) | Gap. Width is read from `Dimensions` once at module load, so it does not track resize or rotation. |
+| `SideDrawer` | Partial. Width is 40% on web and 95% on native, by platform rather than by breakpoint token. |
+
+Do not add a new raw pixel cutoff. Use `Box` breakpoint props, `useResponsiveBreakpoint`, or `isSupportedDesktopWidth`.

package/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -1342,6 +1342,64 @@ One easy-to-use harness inside `@terreno/ai` that runs long-lived agentic work d
 
 ---
 
+## e2e-and-regression-testing
+
+**Title:** `E2E tests and manual regression cases in every plan`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`e2e-and-regression-testing`, Status=`In review`
+
+Today an implementation plan never says which end-to-end tests a feature needs, so bots decide alone whether a slice deserves a Playwright spec, and the manual checks a person should repeat before a release live in nobody's file. Most packages are tested only in-process.
+
+Every IP will carry `## E2E tests` and `## Regression cases` sections (either may be `None — <reason>`, neither may be missing). Grow plans the rows, Pick writes each spec with its feature, Roast runs them, Brew merges manual cases into one living suite per area under `docs/regression/`, and Taste keeps both current after fixes. Regression stays minimal: only what a developer or QA must check by hand, such as push notifications, real email delivery, or how the app feels. Terreno itself gains a real-process smoke test and an e2e guide page for every package, and brewery mirrors the contract.
+
+Out of scope: running manual cases automatically, and coverage targets.
+
+- **Implementation plan:** [e2e-and-regression-testing.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/e2e-and-regression-testing.md)
+- **Pull requests:** [#1628](https://github.com/TerrenoLabs/terreno/pull/1628), brewery [#15](https://github.com/joshgachnang/brewery/pull/15)
+
+---
+
+## lifecycle-user-guide
+
+**Title:** `An end-user guide that grows with every feature`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`lifecycle-user-guide`, Status=`Shaping`
+
+Chat agents cannot answer "how do I…" questions about an app today, because no text describes its features in the words users see, and a guide written once drifts from the app the first time a label changes.
+
+Every IP will gain a `## User guide` section, and the task that ships a feature writes its page: one plain-text file per feature under `docs/user-guide/<area>/<feature>.md`, with `audience`, `platforms`, and the `questions` users would ask in its frontmatter, then what it does, how to use it, and what it is meant for. Roast checks the steps against the shipped screens, and Brew gates on the page. A repository with no end users opts out with `User guide: none`. A `backfill-user-guide` skill drafts pages for features that already shipped, for a human to approve.
+
+Open for discussion: how this relates to the support agent's `support/kb/` docs (one corpus or two), whether pages ship in the app or are served by the backend, and who reviews the wording.
+
+- **Implementation plan:** [lifecycle-user-guide.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/lifecycle-user-guide.md)
+- **Pull request:** [#1633](https://github.com/TerrenoLabs/terreno/pull/1633)
+
+---
+
+## list-detail-layout
+
+**Title:** `ListDetailLayout: a route-driven list/detail layout for phone and tablet`
+
+**Labels:** `area:ui`, `type:feature`  
+**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=`list-detail-layout`, Status=`Planned`
+
+- **Implementation plan:** [list-detail-layout.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/list-detail-layout.md)
+
+---
+
+## e2e-and-regression-testing
+
+**Title:** `E2E tests and manual regression cases in every plan`
+
+**Labels:** `area:tooling`, `type:feature`  
+**Project fields:** Area=`tooling`, Target=`Next`, Impact=`Feature`, IP=`e2e-and-regression-testing`, Status=`Planned`
+
+- **Implementation plan:** [e2e-and-regression-testing.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/e2e-and-regression-testing.md)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

package/src/docs/versioned/next/explanation/schema-metadata.md

@@ -43,6 +43,11 @@ const routerDescription = describeModelForRouter(Todo, {
 
 System paths (`_id`, `__v`, `created`, `updated`, `deleted`) are marked with `system: true`.
 
+`required` is true only when the field is required on every document. A conditional
+`required` (a function, such as "required when `provisional` is true") leaves it false, so
+OpenAPI and generated SDKs type the field as optional; Mongoose still enforces the condition
+on save.
+
 ## Views (not canonical)
 
 | Surface | Function | Notes |

package/src/docs/versioned/next/how-to/README.md

@@ -27,17 +27,22 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Durable background jobs](background-jobs.md) — `@terreno/jobs`: enqueue, workers, schedules, Cloud Tasks / Vercel Queues
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
 - [Enable the framework audit log](audit-log.md) — `AuditApp`, per-router `audit`, append-only events
+- [Sign consent on a user's behalf](sign-consent-on-behalf.md) — Provisional consent signatures: RBAC grant, signer screen, status checks, void, print
 - [Seed a database](seed-a-database.md) — Idempotent sync, dry runs, and guarded reset-and-reseed
 - [Run MongoDB migrations](run-mongodb-migrations.md) — Versioned `up`/`down` files, `terreno-migrate`, production gate
 - [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
 - [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
+- [Set up social login](set-up-social-login.md) — Register Google, GitHub, and Apple once on the stable deploy, proxy previews through it, and move stable onto one domain
 - [Password reset and email verification](password-reset.md) — JWT routes, comms templates, Better Auth hooks
+- [Recover a locked-out user](recover-locked-out-user.md) — Platform and org-admin recovery: 2FA, passkeys, providers, sessions, suspend
 - [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
 - [Expose Model Context Protocol tools](expose-mcp-tools.md) — Turn `modelRouter` models into MCP tools an LLM can call
-- [Set up Terreno MCP](set-up-terreno-mcp.md) — Configure hosted docs/codegen and local runtime tools
-- [Debug with MCP](debug-with-mcp.md) — Diagnose backend, browser, Metro, app, and client-state failures
+- [Set up Terreno MCP](set-up-terreno-mcp.md) — Connect Cursor or Claude Code to the hosted docs/codegen server and the local runtime server
+- [Debug with MCP](debug-with-mcp.md) — Follow a failure from symptom to verified fix with the local MCP tools
 - [Connect an MCP client with a service token](connect-mcp-service-token.md) — Mint a personal `mcp_` key for Perplexity and other remote clients
 - [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md) — Let Claude.ai and ChatGPT connect to `/mcp` through OAuth 2.1 with your own consent screen
+- [Manage MCP from the admin panel](manage-mcp-in-admin.md) — Service tokens, OAuth clients and connections, request log, tool on/off switches, and sign-out-everywhere
+- [Expose an MCP server safely](expose-mcp-server-safely.md) — Put `/mcp` on the internet with OAuth, service tokens, a named Cloudflare Tunnel, and Access on the console
 - [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
 - [Develop an AI feature](ai-feature-development.md) — Dataset → prompt → evaluators → experiment → production label → live traces (SOP)
 - [Observe LLM calls](observe-llm-calls.md) — Register ObservabilityApp, primaries, price map, sampleRate
@@ -48,7 +53,9 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
 - [Upgrade banner](upgrade-banner.md) — Soft warning and hard-block app update UX
 - [Upgrade Terreno](upgrade-terreno.md) — Lockstep `@terreno/*` bumps, note range, order, rollback
+- [Automate Terreno upgrades](automate-terreno-upgrades.md) — Hourly workflow that launches one upgrade agent when a week-old release is out and no upgrade is open
 - [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
+- [Build a list/detail screen](build-list-detail-screens.md) — `ListDetailLayout` route group: list on a phone, list + detail panes on a tablet, selection in the URL
 - [Show loading skeletons](show-loading-skeletons.md) — `loading`, `loadingComponent`, and `loadingAnimation` on Box, Card, charts, and Page; `withLoading` for custom components
 - [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
 - [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots

package/src/docs/versioned/next/how-to/audit-log.md

@@ -38,7 +38,10 @@ modelRouter("/todos", Todo, {
 | PATCH `/:id/:field/:itemId` | `updated` | `arrayUpdate` | Changed fields; `recordId` set |
 | DELETE `/:id/:field/:itemId` | `updated` | `arrayRemove` | Changed fields; `recordId` set |
 
-`source` is `modelRouter` for these writes. Secrets (`password`, `hash`, `salt`, `token`,
+`source` is `modelRouter` for these writes. `ConsentApp` also writes `modelRouter` events for
+provisional consent actions: `created`/`create` for a provisional signature, `updated`/`update` for a void, and
+`viewed`/`read` when staff read another user's consent statuses. `read` and `viewed` mark
+audited reads; no other surface writes them. Secrets (`password`, `hash`, `salt`, `token`,
 `secret`, `refreshToken`) are omitted at every object and array depth, including compound
 keys such as `tokenHash`. Extra `redact` names merge with that list as exact field names.
 
@@ -51,6 +54,22 @@ Admin diffs also omit each model's `hiddenFields` and `excludeFields`.
 
 RBAC mutations fan into the same collection when `createAccess({auditSink: persistRbacAuditToAuditEvent})` is set. `source` is `rbac`.
 
+### 4. Account security actions
+
+`AccountSecurityApp` writes the same collection for account recovery. It refuses to start
+unless `AuditApp` is registered (or you pass `audit: false`).
+
+| `source` | Written by | `modelName` / `recordId` | `after` |
+| --- | --- | --- | --- |
+| `admin` | AdminApp POST/PATCH/DELETE | Model / document id | Changed fields |
+| `modelRouter` | `modelRouter` with `audit` | Model / document id | Changed fields |
+| `rbac` | `createAccess({auditSink: persistRbacAuditToAuditEvent})` | RBAC target | Role change |
+| `security` | `AccountSecurityApp` recovery actions (2FA reset and later actions) | `User` / target user id | `{securityAction, organizationId?}` |
+
+A recovery call that changes nothing (resetting 2FA that is already off) writes no row. List
+one user's security history with `GET /audit-events?source=security&recordId=<userId>`. Routes
+and action names: [Account security reference](../reference/account-security.md).
+
 `organizationId` is copied onto the event when `req.organization` is set (`id` or `_id`), otherwise from the request org AsyncLocalStorage, then `X-Organization-Id`, then the mutated document's `organizationId` string. Socket admin-window mutates attach `organizationId` on the payload so non-tenant models still land in the selected organization's audit log. The field is omitted when none of those exist. Admin list/read for `AuditEvent` is not organization-scoped, so unscoped rows stay visible when no organization is selected.
 
 `actorId` comes from `req.user.id` (or `_id`). Only a 24-hex Mongo ObjectId is stored;
@@ -60,7 +79,7 @@ shape still writes the event with `actorId` omitted and a warning logged.
 Update and delete snapshot `before` only when `audit` is on. If that `toJSON` throws, the
 mutation still completes and the event is recorded without a `before` snapshot.
 
-### 4. Fire-and-forget persist
+### 5. Fire-and-forget persist
 
 HTTP handlers do not await Mongo. Diffs still run before the response so `before` / `after` are captured. Failures log; the mutation stays 2xx.
 
@@ -80,6 +99,6 @@ Authenticated malformed queue payloads are acknowledged without persistence. The
 become valid on retry, and returning a non-2xx response would make Cloud Tasks retry the
 same poison task indefinitely.
 
-### 5. Retention
+### 6. Retention
 
 Omit `retentionDays` or set `0` to keep events forever (no TTL index). `new AuditApp({retentionDays: 90})` creates a Mongo TTL index on `created` with `expireAfterSeconds = 90 * 86400`, replacing the default `{created: 1}` field index so Mongo does not reject a duplicate key pattern. Mongo expires documents in the background; lowering or removing TTL later requires dropping that index yourself (`db.auditevents.dropIndex(...)`) — Mongoose will not remove it.

package/src/docs/versioned/next/how-to/automate-terreno-upgrades.md

@@ -0,0 +1,169 @@
+# How to automate Terreno upgrades with a scheduled agent
+
+Run a GitHub Actions job every working hour that checks whether your app is behind the latest Terreno release. When it is, and no upgrade is already in progress, the job starts one cloud agent. The agent runs the [`upgrading-terreno`](upgrade-terreno.md) skill and opens a pull request. The job never edits the tree and cannot merge. A person reviews the pull request.
+
+```text
+cron tick ──► in working hours? ──► behind the latest GitHub release?
+                                         │
+                                         ▼
+          release ≥ 7 days old? ──► no open upgrade PR? ──► no upgrade agent running or in cooldown?
+                                         │
+                                         ▼
+                 npm integrity for every installed package ──► launch one agent ──► agent opens PR
+```
+
+This page is an example. Copy the workflow and adapt the script to your repository. The Terreno repository does not run it.
+
+## Why the job only decides
+
+A GitHub runner usually has no MongoDB, no running backend, and no browser. The upgrade skill needs all three: it starts the upgraded backend, regenerates the typed client from `/openapi.json`, and runs the app. So the job decides and enqueues. The agent runs in a cloud environment that already has your app's services, such as a Cursor Cloud Agent environment.
+
+## Example workflow
+
+`.github/workflows/upgrade-terreno.yml`:
+
+```yaml
+name: Upgrade Terreno
+
+on:
+  schedule:
+    # 13:00–22:00 UTC covers 9:00am–5:59pm America/New_York in both EST and EDT.
+    # The script drops ticks outside the local window.
+    - cron: "0 13-22 * * 1-5"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Target @terreno/* version (empty = latest GitHub release)"
+        required: false
+        type: string
+      dry_run:
+        description: "Decide only — do not launch an upgrade agent"
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+  pull-requests: read
+
+# A second tick waits instead of racing the pull-request and active-agent checks.
+concurrency:
+  group: upgrade-terreno
+  cancel-in-progress: false
+
+jobs:
+  upgrade-terreno:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.4.4"
+
+      - run: bun install --frozen-lockfile
+
+      - name: Launch Terreno upgrade when one is not already open
+        env:
+          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TERRENO_UPGRADE_CLOUD_ENVIRONMENT: ${{ vars.TERRENO_UPGRADE_CLOUD_ENVIRONMENT }}
+          TERRENO_UPGRADE_DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || 'false' }}
+          TERRENO_UPGRADE_VERSION: ${{ inputs.version }}
+        run: bun .github/scripts/upgrade-terreno.ts
+```
+
+The job needs read access to contents and pull requests only. The agent pushes with its own credentials.
+
+## What the script decides
+
+`.github/scripts/upgrade-terreno.ts` checks these in order and stops at the first one that says no. Order matters: the cheap checks run first, and no agent API call happens until every gate passes.
+
+| Order | Check | Skip when |
+| --- | --- | --- |
+| 1 | Working hours | A scheduled tick lands outside weekdays 9:00am–5:59pm in your team's timezone. Use Luxon with a named zone so daylight saving does not move the window. Manual runs are not gated. |
+| 2 | Installed versions | No `@terreno/*` pin is found. This is an error, not a skip. Read every manifest that pins Terreno. With a Bun catalog, the versions live in the root `package.json` under `workspaces.catalog` (and `workspaces.catalogs.<name>`); workspace packages say `catalog:`. |
+| 3 | Target version | The lowest installed pin already equals the target, or any pin is newer than it. Never downgrade. Resolving the target fails the job when `@terreno/api` at that version is not on npm yet; see below. |
+| 4 | Release age | A scheduled run targets a release under 7 days old. A manual run is the human gate and is not held. |
+| 5 | Open pull request | Any open pull request is an upgrade: its title names a Terreno upgrade, its branch contains `upgrade-terreno`, or its body has the `<!-- terreno-upgrade -->` marker. |
+| 6 | Running agent | An upgrade agent (name starts with `Upgrade Terreno`) is still running. |
+| 7 | Cooldown | An agent for the same target version was created in the last 24 hours, even one that finished or failed. Without this, a broken upgrade is retried every hour. |
+| 8 | npm integrity | Any installed package has no published `dist.integrity` for the target. |
+
+Take the target from the latest stable [TerrenoLabs/terreno GitHub release](https://github.com/TerrenoLabs/terreno/releases), not the npm `latest` dist-tag. Reject drafts, prereleases, and tags that are not semver. Validate a manual `version` input as semver before using it.
+
+Write the decision to `$GITHUB_STEP_SUMMARY` so each run says why it skipped:
+
+```text
+## Terreno upgrade
+
+- Decision: skipped (open-pull-request)
+- Detail: Open Terreno upgrade pull request #261 (Upgrade Terreno to 57.19.2).
+- From: 57.16.2
+- To: 57.19.2
+```
+
+The job fails, rather than skips, in two cases:
+
+- A launch would happen and `CURSOR_API_KEY` is missing. A skip with no key is still green.
+- The latest GitHub release exists but `@terreno/api` at that version is not on npm. This check runs while the target is resolved, before the release-age and open-pull-request gates, so every in-hours run is red until publishing finishes. That points at a stuck release. If you would rather skip quietly, return a skip from that check instead of throwing.
+
+## The agent prompt
+
+The skill stops for confirmation unless the invoking task names both versions and authorizes the bump. The prompt does that, so the agent prints its plan into the transcript and continues:
+
+```text
+Upgrade Terreno from 57.16.2 to 57.19.2.
+
+This unattended task names fromVersion 57.16.2 and toVersion 57.19.2 and authorizes the
+lockstep bump. Follow the upgrading-terreno skill. Print the plan into the transcript, then
+perform the upgrade. Do not wait for confirmation.
+
+Check out the latest origin/master and create a feature branch before editing. Do not commit
+to master.
+
+Bump every already-installed @terreno/* dependency to 57.19.2. Do not add @terreno packages
+that are not already installed.
+
+Installed pins:
+package.json workspaces.catalog @terreno/api@57.16.2
+package.json workspaces.catalog @terreno/ui@57.16.2
+
+The target is the TerrenoLabs/terreno GitHub release 57.19.2, not the npm latest dist-tag.
+Install these exact versions. npm dist.integrity:
+@terreno/api@57.19.2 sha512-…
+@terreno/ui@57.19.2 sha512-…
+
+Open exactly one pull request against master. Put <!-- terreno-upgrade --> in its body.
+```
+
+Add the repo-specific steps the skill cannot know, such as which apps run `bun run sdk`. Install the skill in the app first ([install agent skills](install-agent-skills.md)); otherwise the agent has nothing to follow.
+
+Name the agent `Upgrade Terreno to <version>` so checks 6 and 7 can find it.
+
+## Test the script
+
+Inject the I/O (manifest reads, GitHub, npm, the agent API, and the clock) as dependencies and test the decision function with fakes. Cover at least:
+
+- A scheduled tick at 8:59am and 6:00pm local time in both winter and summer
+- Already current, and a pin newer than the target
+- A 6-day-old release on a schedule, and the same release on a manual run
+- Each open pull request signal on its own
+- A finished agent for the same version inside and outside the cooldown
+- A package with no npm integrity
+- A dry run that reports `launch` without calling the agent API
+
+## Try it
+
+Run the workflow manually with `dry_run` checked. The summary shows the decision without launching anything. Then run it locally:
+
+```bash
+GITHUB_EVENT_NAME=workflow_dispatch \
+GITHUB_REPOSITORY=<owner>/<repo> \
+GITHUB_TOKEN=$(gh auth token) \
+TERRENO_UPGRADE_DRY_RUN=true \
+bun .github/scripts/upgrade-terreno.ts
+```

package/src/docs/versioned/next/how-to/build-list-detail-screens.md

@@ -0,0 +1,160 @@
+# Build a list/detail screen
+
+Put the list and its detail route in one route group, and make `ListDetailLayout` the group's
+layout. On a phone the list pushes the detail. On a tablet or a wide browser the list stays in a
+left pane and the detail opens beside it. The URL always names the open item.
+
+```text
+app/mail/
+  _layout.tsx   ListDetailLayout
+  index.tsx     ListDetailIndex
+  [id].tsx      the detail screen
+```
+
+```tsx
+// app/mail/_layout.tsx
+import {ListDetailLayout, Text} from "@terreno/ui";
+import type React from "react";
+
+import {MailList} from "@/components/MailList";
+
+// A deep link to /mail/3 on a phone still has the list to go back to.
+export const unstable_settings = {initialRouteName: "index"};
+
+const MailLayout: React.FC = () => (
+  <ListDetailLayout
+    detailHref={(id) => `/mail/${id}`}
+    emptyDetail={<Text>Select a message</Text>}
+    indexHref="/mail"
+    list={<MailList />}
+    screenOptions={{title: "Inbox"}}
+  />
+);
+export default MailLayout;
+```
+
+```tsx
+// app/mail/index.tsx
+import {ListDetailIndex} from "@terreno/ui";
+import type React from "react";
+
+const MailIndex: React.FC = () => <ListDetailIndex />;
+export default MailIndex;
+```
+
+```tsx
+// app/mail/[id].tsx
+import {Page, Text} from "@terreno/ui";
+import {useLocalSearchParams} from "expo-router";
+import type React from "react";
+
+const MailMessage: React.FC = () => {
+  const {id} = useLocalSearchParams<{id: string}>();
+  return (
+    <Page>
+      <Text>Message {id}</Text>
+    </Page>
+  );
+};
+export default MailMessage;
+```
+
+## Select rows from the list
+
+Read the open item and open others with `useListDetail()`. Mark the open row as selected so
+screen readers announce it. On web a clickable `Box` row sends this as `aria-current="true"`.
+
+```tsx
+import {Box, Text, useListDetail} from "@terreno/ui";
+import type React from "react";
+
+export const MailRow: React.FC<{id: string; subject: string}> = ({id, subject}) => {
+  const {select, selectedId} = useListDetail();
+  const isSelected = id === selectedId;
+  return (
+    <Box
+      accessibilityHint="Opens the message"
+      accessibilityLabel={subject}
+      accessibilityState={{selected: isSelected}}
+      color={isSelected ? "primary" : "base"}
+      onClick={() => select(id)}
+      padding={3}
+      testID={`mail-row-${id}`}
+    >
+      <Text color={isSelected ? "inverted" : "primary"}>{subject}</Text>
+    </Box>
+  );
+};
+```
+
+| Call | Stacked (phone) | Split (tablet, wide web) |
+| --- | --- | --- |
+| `select(id)`, nothing open | Pushes `detailHref(id)` | Pushes `detailHref(id)` |
+| `select(id)`, another item open | Pushes `detailHref(id)` | Replaces the open detail |
+| `select(selectedId)` | Pushes again | Does nothing |
+| `clear()` | `router.dismissTo(indexHref)`: pops back to the list inside this group | Same |
+| `clear()`, nothing open | Does nothing | Does nothing |
+
+Because split mode replaces the open detail, the stack is never deeper than the list plus one
+detail, so back returns to the list after a rotation too. When split, the header's back button
+(`list-detail-leave`) leaves the whole group instead, since the list is already on screen.
+
+When another screen opens a detail directly, push it with `withAnchor` so the list sits below it
+and back lands on the list instead of leaving the group:
+
+```tsx
+router.push("/mail/3", {withAnchor: true});
+<Link href="/mail/3" withAnchor>Open message</Link>
+```
+
+`selectedId` is the `paramName` param (default `id`) of the route directly below `indexHref`
+whose segment is `detailRoute` (default `[id]`). An `id` from a parent dynamic segment, such as
+`/orgs/[id]/mail`, never counts.
+
+## Publish the detail URL
+
+A static web export (`web.output: "static"`) writes an HTML file only for paths
+`generateStaticParams` returns. Without it, opening `/mail/3` directly is a 404 on a host that
+does not rewrite unknown paths.
+
+```tsx
+// app/mail/[id].tsx
+export const generateStaticParams = (): {id: string}[] =>
+  messages.map((message) => ({id: message.id}));
+```
+
+Ids that are not known at build time need the host fallback from
+[Build for web](build-for-web.md): Netlify `_redirects` with `/* /index.html 200`, or the Vercel
+rewrite in [Deploy to Vercel](deploy-to-vercel.md). The demo inbox exports one page per fixture
+message at `/demo/list-detail/:id` and `/demo/sidebar-navigation/mail/:id`. The Netlify demo
+deploy also writes that fallback, so an id outside the fixtures still opens the missing-message
+screen.
+
+## Keep list state across the breakpoint
+
+The open item survives a rotation or a browser resize. The `list` element does not: it moves
+between the index screen and the left pane, so it remounts. Keep filters, search text, and other
+list state in the route (`router.setParams`) or a store.
+
+## Nest it inside a sidebar
+
+`ListDetailLayout` measures its own width, so it splits correctly inside `SidebarNavigation` or
+an admin rail. Make the group a screen of the sidebar navigator:
+
+```text
+app/workspace/
+  _layout.tsx         SidebarNavigation with <SidebarNavigation.Screen name="mail" />
+  mail/_layout.tsx    ListDetailLayout with indexHref="/workspace/mail"
+  mail/index.tsx
+  mail/[id].tsx
+```
+
+## Choose SplitPage instead
+
+Use `SplitPage` when the list and detail do not have their own routes, such as a picker inside a
+modal. `SplitPage` keeps the selection in component state, so it has no URL, deep links, or back
+navigation for the open item.
+
+## Reference
+
+Props, defaults, and testIDs: [`ListDetailLayout`](../reference/ui.md#listdetaillayout).