@terreno/mcp 57.19.2 → 57.20.0

package/dist/docs/versioned/next/explanation/consent-forms.md

@@ -0,0 +1,105 @@
+# Consent forms
+
+`ConsentApp` gives an app versioned consent forms (terms, privacy, HIPAA, research, and
+custom agreements), a record of every response, and a gate that keeps a user out of the app
+until they have answered every form that applies to them.
+
+## Forms and versions
+
+A `ConsentForm` has a `slug`, a `version`, localized markdown `content`, and options such as
+required checkboxes, a drawn signature, and whether the user may decline. Publishing
+(`POST /consent-forms/:id/publish`) copies the form to `version + 1`, activates the copy, and
+deactivates every other version of the same slug. Only active forms are shown to users. Publish a new version rather than editing
+a form users have already answered, so each response still points at the text the user saw.
+
+An app can narrow which active forms apply to a user with `resolveConsentForms(user, forms)`,
+for example to show a research consent only to enrolled members. Every consent endpoint that
+asks "which forms apply to this user" runs the same resolver.
+
+## Responses
+
+A `ConsentResponse` records one answer to one form version: `agreed`, `agreedAt`, the locale
+shown, checkbox values, an optional signature, and `formVersionSnapshot`. With
+`auditTrail: true`, it also keeps the user's IP address and user agent and a snapshot of the
+exact content they saw. Responses are append-only. A user who answers again gets a new
+record, so the history of what they agreed to, and when, is never rewritten.
+
+## The gate
+
+`GET /consents/pending` returns the forms that apply to the user and that the user has not
+answered at the form's current version. The client (`ConsentNavigator` in `@terreno/ui`)
+shows them one at a time until the list is empty. A decline also clears the form from the
+list: the user has answered it.
+
+When a form is republished, every user's earlier answer is for an older version, so the new
+version reappears in their gate.
+
+## Provisional signatures
+
+Some consent is given before the user ever opens the app. A guardian may agree on the phone
+at intake, or staff may record verbal consent during a visit. For compliance the form must
+count as signed from that moment, but the user should still read the form and sign it
+themselves.
+
+A provisional signature is a `ConsentResponse` with `provisional: true`. Staff create it with
+`POST /consent-responses/provisional`, naming the target user, the form, and a required note
+that explains how consent was obtained. The response records:
+
+- `agreed: true` and `agreedAt` (server time)
+- `provisionalSignedBy`: the staff member who recorded it
+- `provisionalNote`: the note (trimmed, at most 2000 characters)
+- `formVersionSnapshot`, plus `contentSnapshot`, `provisionalSignerIp`, and
+  `provisionalSignerUserAgent` when `auditTrail` is on
+
+`ipAddress`, `userAgent`, `signature`, and `signedAt` stay empty. Those fields describe the
+user's own device and signature, and the user did not sign.
+
+### Why a provisional signature does not clear the gate
+
+Only the user's own responses remove a form from `/consents/pending`. A provisional signature
+is a record that someone else vouched for the user's consent. It is not the user's consent in
+their own words. Keeping the form in the gate means the user still meets it, reads it, and
+agrees or declines. The gate tells them who signed on their behalf and when, but not the
+signer's note: that stays in the admin audit history. The user's own answer is stored as a separate response, so both records
+stay for audit.
+
+A separate `ProvisionalConsent` model was rejected. A field on `ConsentResponse` keeps one
+audit trail per user and reuses the existing admin screens, populate paths, and PDF code.
+
+### Voiding a provisional signature
+
+A provisional signature recorded in error (the wrong member, the wrong form) is voided with
+`POST /consent-responses/:id/void` and a required reason. Voiding sets `voidedAt`,
+`voidedBy`, and `voidReason`; it never deletes the record, so the audit history shows both
+the signature and its void. A voided signature no longer counts as consent, and the user's
+gate no longer mentions it. Only provisional signatures can be voided: the user's own
+answers are theirs to change by answering again.
+
+### What counts as signed
+
+`getConsentStatuses` (and `GET /consent-responses/status`) is the "considered signed"
+contract. For each form that applies to the user, only non-voided responses to the current
+version count. The user's own latest answer always wins: agreeing makes the form `signed`, declining
+makes it `declined`. Without one, a provisional signature makes it `provisional`, which
+counts as consented. Otherwise it is `pending`. App code that needs to know whether a user
+may proceed (for example before scheduling a visit) checks `isConsented` on these rows
+instead of reading responses directly.
+
+### Who may sign for another user
+
+Pass `accessControl` to `ConsentApp` to use RBAC. Any authenticated user whose roles grant
+`consentResponse:signOnBehalf` may then sign for others. The built-in `admin` role includes
+that action, and existing unsealed admin roles gain it the next time roles are seeded. The
+merge runs on every seed, so removing `signOnBehalf` from the `admin` role does not stick.
+To keep admins from signing, give them a custom role instead of `admin`.
+Without `accessControl`, only users with `admin: true` may sign, and `ConsentApp` logs a
+warning at register.
+
+There is no relationship check: a permitted signer may sign for any user. A signer cannot
+sign for themselves, and the form must be active and must apply to the target user under
+`resolveConsentForms`. The same permission covers reading another user's consent statuses.
+When `AuditApp` is registered, every provisional signature, void, and status read writes an
+`AuditEvent` naming the actor and the target user. Audit events gain a `read` operation and
+a `viewed` verb for these reads.
+
+Reference: [ConsentApp](../reference/api.md#consent-forms-consentapp).

package/dist/docs/versioned/next/explanation/example-coverage.md

@@ -27,6 +27,7 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts`, `file-uploads` flag in `example-backend/src/api/fileUploads.ts` | yes — `example-frontend/app/(tabs)/documents.tsx` (Files section, every signed-in user, 1 upload / IP / min), `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/app/gcs-settings.tsx` | The `file-uploads` feature flag hides upload controls and rejects uploads when off. A missing flag leaves uploads enabled. Deployed bucket is terraform-managed (`google_storage_bucket.example_documents`). |
 | Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
 | syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |
+| List/detail layout | n/a — reuses the synced todos | yes — `example-frontend/app/todo-browser/` (`ListDetailLayout` group, opened from the todos screen's Browse button), list in `example-frontend/components/TodoBrowserList.tsx` | Phones push each todo; at 768px and wider the list stays on the left. e2e: `example-frontend/e2e/todo-browser.spec.ts` (phone, tablet, deep link, resize, keyboard). The demo inbox at `demo/app/demo/list-detail/` shows the same layout with static data. Steps: [build-list-detail-screens.md](../how-to/build-list-detail-screens.md). |
 | SyncDB diagnostics | n/a | yes — `debug` registration in `example-frontend/store/syncdb.ts`, debugger UI at `example-frontend/app/syncdb-debug.tsx` | `terreno-mcp-local` can inspect, snapshot/compare/merge, mutate, flush, reconcile/resync, and exercise offline/conflict paths against the running development client. |
 | RBAC | yes — `example-backend/src/rbacRoles.ts` (including optional `aiObservabilityViewer` / `aiObservabilityOperator` roles), `access.ts`, `accessControl: access` on `ObservabilityApp` / `AdminApp`, `access: {resource: "todo"}` on the todo router | yes — `example-frontend/app/admin/roles.tsx` | Shipped. Plan: [rbac-permissions.md](../implementationPlans/rbac-permissions.md). |
 | Organizations | yes — `createAccess({organizations: true})`, `organizationSettingsSchema`, `orgScopedPlugin` on projects | yes — admin org directory/settings at `example-frontend/app/admin/orgs/` | Settings live on `Organization.settings`; example registers a nested timezone schema. |

package/dist/docs/versioned/next/explanation/local-first-data.md

@@ -35,7 +35,7 @@ Terreno 57.
 ## What you start doing
 
 1. **Conflict resolution UI** — When the server rejects a mutation (409 / `sync:nack`), the user must choose a strategy (`useServer` or `keepMine`). Use `ConflictSheet` from `@terreno/ui` or build your own with `useConflicts`.
-2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`).
+2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`, which waits `offlineGraceMs` — 3s by default — before showing "Offline" so startup and brief socket drops do not flash it).
 3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
 4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
 5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server. Optional `sync.adminBroadcast: true` also emits `sync:delta` to `{collection}|admin`. Admin clients subscribe with `mode: "window"` (`createSyncDb({windowCollections})`) so they do not snapshot or reconcile that collection; they call `hydrateWindow` (REST membership ids + `GET /sync/entities`). Pass the same `accessControl` into `SyncApp` that `AdminApp` uses so `{collection}|admin` requires `admin:access`. `AdminApp.register` also installs that model's admin list/read/`queryFilter` on the admin window so hydrate and live `|admin` deltas match `/admin` REST. Without RBAC, `user.admin` is enough for the shell gate. Live deltas on that stream apply only to ids already in the window; Refresh is a REST re-query plus `hydrateWindow`.

package/dist/docs/versioned/next/explanation/organizations.md

@@ -47,6 +47,13 @@ Tenant isolation uses multiple checks rather than one convention:
 admin models whose schema contains `organizationId`. Models without that path
 remain platform-scoped.
 
+Adding, changing, or removing a membership through `POST` / `PATCH` / `DELETE
+/orgs/:id/members` clears that user's cached permissions, so a new org-admin can open the
+admin page (and a demoted or removed one loses it) on their next request instead of after
+the permission cache's 30-second TTL. Disabling (`PATCH /orgs/:id` with `disabled: true`) or
+deleting (`DELETE /orgs/:id`) an organization suspends all of its memberships and clears the
+cached permissions of every member the same way.
+
 ## Disabled organizations
 
 When `Organization.disabled` is `true`, tenant context and membership mutations
@@ -64,6 +71,35 @@ stop, but operators can still manage the organization record itself:
 Disabling or deleting an organization suspends its memberships. Re-enabling does
 not automatically reactivate them.
 
+## Member recovery
+
+When the app registers `AccountSecurityApp`, an org-admin can help a locked-out member without
+platform staff. `OrgsApp` mounts the same recovery handlers the platform uses at
+`/orgs/:orgId/members/:userId/security/*`, behind an org authorizer.
+
+- **Reach.** An org-admin may act on any active member of their org, even one who also belongs
+  to other orgs (D2). A suspended member, or a user outside the org, answers `404`, so the routes
+  do not reveal who exists elsewhere.
+- **Guards.** Platform staff (`superadmin`, `operator`) and `admin: true` users are never reachable
+  through an org (D3). Neither is anyone who holds a permission the org-admin lacks, nor the
+  org-admin themselves (D9). Disabled orgs answer `403`.
+- **Disable means suspend.** One org must not lock a user out of every other org, so the org
+  path has no account disable. It offers `suspend-membership` instead, which suspends the
+  membership in that org only (Q8). The user still signs in and keeps their other orgs.
+  `User.disabled` and `issue-sign-in-link` stay platform-only.
+- **Attach-then-act.** An org-admin can attach any existing user by email
+  (`POST /orgs/:id/members`). Every org-admin action is audited with the org's id and emails the
+  user, so they learn about it ([notifications](../reference/account-security.md#notifications);
+  the org is named only with `notifications.includeOrgName`). Apps that want more can set
+  `orgRecovery.minMembershipDays` to refuse members who joined too recently.
+- **Platform staff** holding `user:manageSecurity` pass the org checks. The target must still be
+  an active member of the org in the path. Their reach check is the platform one: both sides are
+  resolved outside the organization, so an org-only grant does not put the member out of reach.
+
+See [Recover a locked-out user](../how-to/recover-locked-out-user.md) for who can do what, and
+the [account security reference](../reference/account-security.md#org-admin-routes) for every
+response.
+
 ## Why organizations are optional
 
 Automatically registering routes, roles, or Mongoose models would change
@@ -83,6 +119,7 @@ multi-tenant-ready apps.
 ## Related
 
 - [Add organizations](../how-to/add-organizations.md)
+- [Recover a locked-out user](../how-to/recover-locked-out-user.md)
 - [API reference](../reference/api.md#organizations)
 - [Admin backend reference](../reference/admin-backend.md#organization-scoping)
 - [Admin frontend reference](../reference/admin-frontend.md#orgdirectoryscreen)

package/dist/docs/versioned/next/explanation/planning-plugins.md

@@ -112,3 +112,7 @@ Install both from the marketplaces described in
 [install agent skills](../how-to/install-agent-skills.md). Claude Code resolves a plugin
 skill's command from its frontmatter `name`, which is why the two `*-claude/` trees are
 generated with shortened names by `bun run skills:sync`.
+
+## Related
+
+- [AI development loop](ai-development-loop.md): the tool layer these stages use to see the running app

package/dist/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/dist/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -1342,6 +1342,17 @@ One easy-to-use harness inside `@terreno/ai` that runs long-lived agentic work d
 
 ---
 
+## 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)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

package/dist/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/dist/docs/versioned/next/how-to/README.md

@@ -27,15 +27,18 @@ 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
 - [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
@@ -48,7 +51,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/dist/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/dist/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
+```