@terreno/mcp 58.0.0-beta.4 → 58.0.1

package/src/docs/versioned/58.0.0/explanation/README.md

@@ -0,0 +1,47 @@
+# Explanation
+
+Understanding-oriented documentation: concepts, architecture, and context.
+
+## Deployment
+
+- [Deployment baseline](deployment-baseline.md) — seven requirements for production Terreno apps
+- [GCP deployment architecture](deployment-architecture-gcp.md) — Cloud Run + GCS/CDN topology and tradeoffs
+- [GCP hosting architecture](gcp-hosting-architecture.md) — static site hosting with GCS and Cloud CDN (legacy detail)
+
+## Contents
+
+- [Local-first data](local-first-data.md) — Why the local store is the UI source of truth
+- [Planning plugins](planning-plugins.md) — How the lifecycle and scan plugins divide discovery from delivery
+- [Loop engineering](loop-engineering.md) — Fresh-invocation lifecycle, state, evidence, and orchestration boundaries
+- [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md) — Pick-ready issues and plan comments for Pick/Roast
+- [Install agent skills](../how-to/install-agent-skills.md) — `npx skills add TerrenoLabs/terreno`
+- [AI development loop](ai-development-loop.md) — The five-stage Ask, Generate, Run, Observe, Fix loop, what the agent can and cannot see, and how it composes with expo-mcp, Playwright MCP, and Maestro
+- [Agent guidelines](agent-guidelines.md) — How hosted docs, per-package `.ai/` guidelines, and `.rulesync/` rules reach an agent, and how apps extend them
+- [AI observability](ai-observability.md) — Two planes (telemetry vs control), plugins, SOP loop
+- [Durable agent harness](durable-agent-harness.md) — Phases, checkpoints, and why the audit span shares the checkpoint transaction
+- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
+- [Agent UI Asks](agent-ui-asks.md) — Why agent questions are client-side tool calls, the pause and resume round trip, why cards carry exact answers, the watch paths, asks vs blocks
+- [Agent UI blocks](agent-ui-blocks.md) — Why chat replies use a closed YAML catalog instead of free-form UI, why steppers and checklists call the server, and the rich-blocks rollout
+- [Authentication architecture](authentication.md) — Better Auth, JWT, and optional MCP service tokens
+- [Account linking](account-linking.md) — Linking modes, why both emails must be verified, Apple relay emails, and migrating JWT users
+- [Organization tenancy](organizations.md) — Optional Membership-backed tenancy, context, and isolation boundaries
+- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
+- [Dependency management](dependency-management.md) — Catalog pins, exercise tests, fingerprint freeze
+- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
+- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
+- [Explicit `any` policy](explicit-any-policy.md) — Require rationale markers and ratchet usage per file
+- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels
+- [TypeScript configuration](typescript-configuration.md) — tsconfig profiles for Node, frontend, Expo, and Bun workspaces on TypeScript 6
+- [Production source rules](source-rules.md) — Arrow functions, Luxon, APIError, logging, findOne, `as any`
+- [Positioning](positioning.md) — Canonical copy blocks and the honest Django/Rails comparison
+- [Versioning policy](versioning-policy.md) — Lockstep `@terreno/*` versions, pre-1.0 breaks, deprecation window
+- [How admin interfaces are shaped](admin-interface.md) — Screens, sidebar, `apiBase` vs `routeBase`
+- [Server-rendering the admin SPA](admin-spa-ssr.md) — How `AdminSpaServeApp` renders pages in Express, and the Expo 58 constraints it works around
+- [Admin plugin frontend widgets](admin-plugin-frontend.md) — Widget IDs from backend plugins
+- [Consent forms](consent-forms.md) — Versions, responses, the consent gate, and why provisional signatures don't clear it
+- [Consent admin migration](admin-consent-migration.md) — Which consent screens stay hand-written
+- [Public roadmap process](roadmap-process.md) — GitHub roadmap vs Linear execution
+- [Example app coverage](example-coverage.md) — Which framework capabilities the example apps exercise
+- [Repository settings](repository-settings.md) — Maintainer GitHub settings that cannot be committed
+- [Why Terreno owns chart SVG](charts.md) — Owned `react-native-svg` vs victory-native
+- [Responsive design](responsive-design.md) — Support levels, breakpoints, and the desktop floor

package/src/docs/versioned/58.0.0/explanation/account-linking.md

@@ -0,0 +1,169 @@
+# Account linking
+
+One person can sign in to a Terreno app in several ways: email and password, Google, GitHub,
+Apple, or a passkey. Account linking decides what happens when a new sign-in method arrives with
+an email that already belongs to an account. Done carelessly, it is an account takeover. This page
+explains the three modes, why Terreno asks for proof of the email before it links anything, and
+how apps that started on JWT auth move their users over.
+
+Setup: [Auth features](../how-to/configure-better-auth.md#auth-features). Reference:
+[`GET {basePath}/terreno/methods`](../reference/api.md#better-auth-authentication).
+
+## Two layers of accounts
+
+A Terreno app with Better Auth has two records per person:
+
+- **The Better Auth user** (`user` collection) owns sign-in. Each sign-in method is an `account`
+  row under it: `credential` for email and password, `google`, `github`, and so on. Better Auth
+  keeps emails unique, so there is at most one Better Auth user per email.
+- **The app `User`** (your Mongoose model) owns everything else: permissions, `admin`,
+  `disabled`, org memberships, and your data. It points at its Better Auth user through
+  `betterAuthId`.
+
+Linking happens at both layers. Better Auth decides whether a new provider `account` joins an
+existing Better Auth user. Terreno decides whether a Better Auth user may claim an existing app
+`User` (`syncBetterAuthUser`).
+
+## The three modes
+
+Set `accountLinking: {mode}` on `BetterAuthConfig`. The mode controls the Better Auth layer.
+
+| Mode | A same-email sign-in with a new method | `POST {basePath}/link-social` |
+| --- | --- | --- |
+| `verified-email` (default) | Joins the account when both emails are verified | Links |
+| `explicit` | Refused with `account_not_linked`; nothing is created | Links, from a signed-in session |
+| `never` | Refused with `account_not_linked`; nothing is created | Refused with 403 `LINKING_DISABLED` |
+
+- **`verified-email`** is the least friction: someone who signed up with email and password and
+  later taps "Continue with Google" on the same address lands in the same account.
+- **`explicit`** makes the user prove they own the existing account first. They sign in the old
+  way, open the Security screen, and link the provider there. A login screen should turn
+  `account_not_linked` into "sign in with your original method, then link this one".
+- **`never`** keeps every sign-in method separate. Because Better Auth keeps emails unique, a
+  second method on the same email cannot sign in at all. Pick it when a shared inbox must not
+  join two people's records.
+
+`/terreno/methods` reports the mode so clients can word their guidance. Unlinking the only
+remaining sign-in method is refused in every mode (400 `FAILED_TO_UNLINK_LAST_ACCOUNT`), so a user
+cannot lock themselves out. rtk's `TerrenoAccountSecurityScreen` checks the same rule before it
+asks, and a social-only user can add a password there (`POST {basePath}/terreno/set-password`) to
+gain a second method before unlinking a provider.
+
+### What the refusals look like
+
+| Path | `account_not_linked` | Unverified email matches an app `User` |
+| --- | --- | --- |
+| OAuth redirect (`/callback/{provider}`) | Redirect with `?error=account_not_linked` | Redirect with `?error=VERIFY_EMAIL_TO_USE_ACCOUNT` |
+| ID-token sign-in (`/sign-in/social` with `idToken`) | 401, `message: "account not linked"` | 409, `code: "VERIFY_EMAIL_TO_USE_ACCOUNT"` |
+| Email sign-up or sign-in | n/a | 409, `code: "VERIFY_EMAIL_TO_USE_ACCOUNT"`, `message: "Verify your email to use this account"` |
+
+## Why both emails must be verified
+
+Linking by email trusts that whoever controls the email controls the account. That trust has to
+hold on both sides:
+
+- **The new method's email.** A provider that reports an unverified email has not checked that
+  the person owns it. Linking on it lets anyone who types your address into that provider into
+  your account. An unverified provider email never links, in any mode. `trustedProviders` turns
+  this check off for the providers it lists, so list only providers that prove email ownership.
+- **The existing account's email.** If the existing account was itself created without proving
+  the email, an attacker can **pre-register**: sign up with the victim's address and a password
+  the attacker knows, wait for the victim to sign in with Google, and share the account.
+  Terreno keeps Better Auth's `requireLocalEmailVerified: true` in every mode, so an unverified
+  local account never absorbs a new method.
+
+The same rule applies one layer down. A Better Auth user claims an existing app `User` only when
+the provider verified its email, or when the user proves they own that `User` another way (see
+the migration below). Terreno checks this **before the Better Auth user is created**. An
+unverified sign-up for someone else's address gets 409 "Verify your email to use this account"
+and leaves nothing behind: no Better Auth user, no `account` row, no verification email. That
+matters because a Better Auth user left behind would be a pre-registration one layer down: once
+anyone verified that email (the victim clicking the mail the attacker's sign-up triggered, or an
+admin), the attacker's password would open the victim's `User`. Terreno never inserts a second
+`User` for the same email either.
+
+Two more rules hold whichever way the claim is proven. A `User` that already carries another
+Better Auth account's `betterAuthId` is never relinked by email (409 `ACCOUNT_ALREADY_EXISTS`).
+And when a verified email links a `User` whose own `emailVerified` is not `true`, the `User`'s
+legacy password is removed and its `tokenEpoch` bumped: whoever set that password never proved
+they own the mailbox, so it and the JWT refresh tokens issued from it stop working. A link proven
+by the legacy password itself keeps that password. Operator seeds pass `trustEmail` to
+`syncBetterAuthUser`, which skips these checks for accounts the seed created itself.
+
+Emails are compared ignoring case, so a legacy `User` stored as `Jane@Example.com` is protected
+from a sign-up as `jane@example.com`, and claiming it never creates a second `User`.
+
+**Trade-off: the 409 reveals that an account exists.** A sign-up that gets 409
+`VERIFY_EMAIL_TO_USE_ACCOUNT` tells the caller that an app `User` already has that email. Terreno
+accepts this account-existence signal: refusing silently would either leave the
+pre-registration hole open or leave legitimate users stuck with no explanation, and Better Auth's
+own sign-up already answers `USER_ALREADY_EXISTS` for emails it knows. Apps that must hide
+membership (for example, where an account implies care) should rate-limit sign-up (the `auth`
+bucket) and word the client message neutrally.
+
+The guard needs a user model on the Better Auth instance. `BetterAuthApp` uses its own
+`userModel`, or adopts `TerrenoApp`'s when it was given none, before it creates Better Auth. If you
+call `createBetterAuth` yourself, pass `userModel` to it whenever a session middleware links app
+`User`s.
+
+Terreno then syncs the app `User` as each Better Auth session is created, while the request that
+proves who the user is (its password, its provider) is still in hand. That is also when
+`oauthProvider` is recorded. The session check repeats the claim rule as a second guard, and a
+password-proven link that fails to save fails the sign-in (500 `APP_USER_LINK_FAILED`) instead of
+leaving a session that every request would refuse.
+
+## Apple private-relay emails
+
+Sign in with Apple lets users hide their address. Apple then reports a relay address such as
+`abc123@privaterelay.appleid.com`, marked verified, that forwards to the real inbox. It never
+matches the email the person used elsewhere, so Apple sign-in creates a separate account in every
+mode. Users who want one account sign in their usual way and link Apple from the Security screen
+(`/link-social`). That link works only when Apple shares the real address ("Share My Email"):
+Better Auth refuses a link whose email differs from the account's unless `allowDifferentEmails`
+is on. Do not merge relay accounts by name: a name proves nothing.
+
+## Several accounts on one device
+
+Linking answers "is this the same person?". Some people really have several accounts, for example
+a parent with their own login and a child's. They should not merge them. `multiSession` lets one
+device hold several signed-in accounts and switch between them without signing out, and
+`signUp: {mode: "closed"}` stops new accounts altogether. Together with the linking mode, these
+are the three knobs an app has over "multiple accounts".
+
+## Migrating users from JWT auth
+
+Apps that started on Terreno's JWT and passport auth already have app `User`s with
+passport-local-mongoose password hashes. When such a user first signs in through Better Auth with
+the same email, Terreno links the new Better Auth user to their existing `User` if either:
+
+- the sign-in comes from a provider (Google, GitHub, Apple, ...) that reports the email as
+  verified, or
+- the password they sign up with verifies against the `User`'s existing passport hash. The
+  plaintext is checked only during that request and never stored. The check does not count as a
+  failed JWT login, so with passport's `limitAttempts` a stranger signing up with the victim's
+  email cannot lock the victim out.
+
+Otherwise the sign-up answers 409 "Verify your email to use this account" and nothing is created.
+Verifying the email afterwards cannot link anything, because there is no Better Auth user to
+verify. Before this change, any unverified sign-up claimed the `User` with the same email, which
+let anyone take over a legacy account by signing up with its address.
+
+Users who signed in with GitHub through JWT have no password hash. They get in one of three ways:
+
+- a provider sign-in whose email the provider verified;
+- a password reset sent to their email through the JWT forgot-password flow
+  (`POST /auth/forgotPassword`), then a Better Auth sign-up with the new password;
+- an admin-issued account recovery link (see [account security](../reference/api.md#better-auth-authentication)
+  once recovery is enabled) that sets their password and creates the Better Auth user.
+
+To migrate smoothly:
+
+1. Keep the JWT auth routes mounted while users move over, so forgot-password still works.
+2. Tell users to sign up with the email and password they already use; those link at once.
+3. Point users without a password at a provider sign-in or at JWT forgot-password.
+
+## Learn more
+
+- [Authentication architecture](authentication.md)
+- [Configure Better Auth](../how-to/configure-better-auth.md)
+- [Better Auth: users and accounts](https://www.better-auth.com/docs/concepts/users-accounts#account-linking)

package/src/docs/versioned/58.0.0/explanation/admin-interface.md

@@ -0,0 +1,92 @@
+# How admin interfaces are shaped
+
+Prefer existing admin packages over a new dashboard. `@terreno/admin-backend`
+exposes `/admin/config` plus per-model CRUD. `@terreno/admin-frontend` renders that
+config as a sidebar, home dashboard, tables, and forms. `@terreno/admin-spa` is the
+same UI served from the API origin.
+
+Consumer screens are thin routes. They wrap `AdminProvider` + `AdminShellLayout` and
+let `AdminHome`, `AdminScreenRouter`, `AdminModelTable`, and `AdminModelForm` do the
+work. Hand-write a route only when the generic table/form cannot express the
+workflow (consent publish, comms message detail, password-on-create).
+
+## Two hosts
+
+| Host | When to use | Route prefix (`routeBase`) | API prefix (`apiBase`) | Fetch auth |
+| --- | --- | --- | --- | --- |
+| Embedded (`example-frontend/app/admin`) | Admin lives inside the product Expo app | `"/admin"` | `"/admin"` | `getAuthHeaders` → Bearer, plus `apiOrigin` = `baseUrl` from `@terreno/syncdb/config` so admin requests do not hit the Expo origin |
+| Standalone (`@terreno/admin-spa`) | Same-origin console served by `AdminSpaServeApp` | `""` (SPA root; mount is `/console`) | `"/admin"` | `credentials="same-origin"`; omit `getAuthHeaders` and `apiOrigin` |
+
+`apiBase` is the HTTP path for `/config` and CRUD. `routeBase` is the Expo Router
+prefix the sidebar concatenates onto `/{model.name}` and `/{screen.name}`. Mixing
+them puts nav on the wrong URL. Embedded hosts must also set `apiOrigin` (the
+backend origin, e.g. `http://localhost:4000`) on `AdminProvider`. Every admin
+request (model CRUD and RPC) is a native `fetch` through that provider, which uses
+the origin to prefix `/admin/config`, `/admin/users`, and `/rbac/roles`. Do not put the
+origin in `apiBase` — that would rewrite in-app navigation.
+
+## Screen kinds
+
+| Kind | Source of truth | Frontend |
+| --- | --- | --- |
+| Model changelist / form | `modelRouter({admin: ...})` or plugin `adminContribution()` | `AdminScreenRouter` → `AdminModelTable` / `AdminModelForm` (list filters live on `DataTable`, not a side drawer) |
+| Custom screen | `AdminApp.customScreens` or plugin `customScreens` (`name` + `displayName`) | Matching `AdminProvider.widgets.screens[name]`, or a dedicated Expo route |
+| Platform tool | Built-in (`scripts`, `roles`, `version`, `configuration`, audit log, feature flags, jobs) | Sidebar **Platform** section; visibility from `/admin/config.platformTools` (jobs is lifted from `customScreens`) |
+| Home widget | `AdminApp.home.slots` IDs | `AdminProvider.widgets.home` (built-ins already registered) |
+
+`GET /admin/config` is caller-specific. Models and custom screens without read
+access are omitted. The sidebar must not invent links the config did not return.
+
+## Navigation chrome
+
+`AdminShell` (via `AdminShellLayout`) always owns the sidebar. Do not add a second
+app-level nav inside admin.
+
+Order in the rail:
+
+1. **Home** → `{routeBase}/`
+2. **Models** grouped by `admin.group` (ungrouped models land in **General**). Custom screens with `group` render inside the matching group **before** model links for that group. A grouped screen with no models still gets its own group heading.
+3. **Screens** — only `customScreens` **without** `group` (plus optional host extras)
+4. **Platform** — Scripts (`/__scripts`), Migrations (`/__migrations` when
+   `migrations.enabled`), Roles, Version, Audit Log, Feature Flags, Jobs, Configuration
+
+Audit log and Feature Flags are models, but the shell lifts them into Platform so
+operators do not hunt for them among business collections. The Platform Audit Log
+row is `AuditEvent` when `AuditApp` is registered. `isAuditLogModel` also matches
+legacy `AdminAuditLog`, `audit-log`, and `audit-events` names. Jobs is a custom
+screen (`name: "jobs"`); the shell lifts it the same way.
+
+Below the desktop floor (1024pt) the rail becomes a hamburger drawer. The main column is a body-style
+canvas (`neutral-050`, or `neutral-900` in dark mode so `surface.base` cards stand out).
+The colorful teal rail has no dark palette, so dark mode always uses the clinical rail.
+Host apps must give React Navigation a theme that follows the Terreno color scheme
+(the example app uses `buildNavigationTheme` with a transparent background inside the
+admin `Stack`); otherwise its default light screen containers cover the canvas. Nested `Page` screens use `color="transparent"` and
+`padding={0}` so cards sit on that canvas. Custom screens wrap content in
+`AdminScreenPage`; the back arrow uses `router.push(routeBase)` rather than
+`router.back()` because sidebar clicks do not always leave history on web.
+Nested model stacks (`app/admin/[model]/_layout.tsx` and `admin-spa/app/[model]/_layout.tsx`)
+set `headerShown: false` so Expo does not title the screen `index` or add a second back arrow.
+Page components do not draw their own navigator arrows.
+
+## Where code goes
+
+| Concern | Location |
+| --- | --- |
+| Which models appear | `modelRouter` `admin` block, or plugin `adminContribution()` |
+| Extra non-CRUD pages | `AdminApp.customScreens` + `widgets.screens` with the **same** `name`. Optional `group` places the screen in that sidebar group (see **Models** above). |
+| Home dashboard composition | `AdminApp.home.slots` |
+| Field widgets | `admin.fieldOverrides.widget` + `widgets.fields` |
+| Expo files | `app/admin/_layout.tsx` (shell once) or per-route shell in admin-spa |
+| Dedicated extra segments (`/comms/:id`) | Explicit Expo files so `[model]/[id]` does not treat them as generic forms |
+| Data fetching | REST remains membership/search/sort/pagination. String `_id` models with `adminBroadcast` overlay TinyBase and write through syncdb when the host passes a window client + fetch auth. Every admin request goes through the `AdminProvider` host-bound fetch client: ObjectId/API-only CRUD (`useAdminModelApi`) and framework RPC alike. Terreno 58 removed the RTK `api` prop and `useAdminApi`. |
+
+## Related
+
+- [Build admin screens](../how-to/build-admin-screens.md)
+- [Add a model to the admin](../how-to/admin-add-model.md)
+- [Customize the admin home](../how-to/admin-custom-home.md)
+- [Add a custom admin field widget](../how-to/admin-custom-widget.md)
+- [Admin plugin frontend widgets](admin-plugin-frontend.md)
+- [admin-frontend reference](../reference/admin-frontend.md)
+- [admin-config reference](../reference/admin-config.md)

package/src/docs/versioned/58.0.0/explanation/admin-plugin-frontend.md

@@ -0,0 +1,33 @@
+# Admin plugin frontend widgets
+
+Screen layout, sidebar order, and host wiring: [How admin interfaces are
+shaped](admin-interface.md) and [Build admin screens](../how-to/build-admin-screens.md).
+
+Backend plugins contribute stable widget IDs through `adminContribution()`. Their React
+implementations ship from `@terreno/admin-frontend`, under `src/widgets/`.
+
+This keeps the first-party integration in one frontend package and avoids making backend-only
+packages depend on React Native. The built-in registry includes consent field widgets, feature
+flag home widgets, and Documents/AI Requests/AI Observability/Comms custom screens. Hosts can
+override any ID through `AdminProvider.widgets`.
+
+Third-party plugins should publish their own frontend package and ask the host to spread its
+registry into `AdminProvider`; `@terreno/admin-frontend` only owns first-party Terreno widgets.
+
+## Authorization metadata
+
+Opening the admin UI is a separate decision from what an operator may do inside it. The page
+gate is `admin:access` (`GET /admin/config` 403 without it). Host apps should hide admin
+navigation with the same check (`canOpenAdminPage` from `@terreno/syncdb/app`).
+
+`AdminApp` then resolves authorization before returning `/admin/config`. The response only contains
+models and custom screens the caller may read, includes effective write capabilities, and exposes
+visibility flags for built-in Platform tools. The frontend treats this metadata as navigation and
+affordance guidance; backend model, script, configuration, and RBAC routes enforce the same
+permissions independently.
+
+Standard model permissions are intentionally three-level (`read`, `write`, `writeOwned`) so roles
+remain understandable as the number of admin models grows. Model configuration supplies the
+ownership predicate because ownership is domain-specific (`ownerId`, `staffId`, tenant membership,
+or another relationship). A custom authorization callback remains available for policies that
+cannot be represented by those levels.

package/src/docs/versioned/58.0.0/explanation/admin-spa-ssr.md

@@ -0,0 +1,214 @@
+# Server-rendering the admin SPA
+
+`@terreno/admin-spa` is built with Expo Router's `web.output: "server"`. `AdminSpaServeApp`
+renders each admin page inside the Terreno backend's own Express process instead of sending
+one static `index.html`. The first HTML already contains the page, so an operator sees the
+login form, and later the screen's data, before any JavaScript runs.
+
+## How a request is served
+
+1. `expo export --platform web` writes the export root `dist/`:
+   - `dist/client/` holds the hashed JavaScript and assets.
+   - `dist/server/_expo/` holds `routes.json`, `server/render.js` and one module per route
+     `loader`.
+2. `AdminSpaServeApp` serves `dist/client` under `basePath` (`/console` by default) with a
+   one-year immutable cache.
+3. It publishes `{appConfig, basePath, internalOrigin, ssrApiPrefixes}` on a process global
+   (`Symbol.for("terreno.adminSpa.server")`). `render.js` and the loaders are separate bundles
+   running in the same process, so the global is how they read the runtime config.
+4. It mounts `expo-server`'s Express adapter at `basePath`. The adapter strips `basePath`, so
+   `/console/login` matches the route pattern `^/login$`.
+5. `app/+html.tsx` writes `window.__ADMIN_SPA_BASE__` and `window.__ADMIN_SPA_CONFIG__` into
+   the page. `AppConfigGate` hydrates from them without fetching `app-config.json`. In dev
+   proxy mode nothing is injected, so the gate fetches the config as before.
+6. A route `loader` (for example `/login`'s, which returns `{appConfig}`) runs on the server.
+   Its data is embedded in the page. A client-side navigation fetches it as JSON.
+
+## Constraints from Expo SDK 58
+
+These were found by the T1 tracer on Expo 58.0.14, expo-router 58.0.23 and expo-server
+58.0.5. Each one shapes the plugin.
+
+| Finding | Consequence |
+| --- | --- |
+| The client requests loader data from the site root, `/_expo/loaders/<route>`, ignoring the baked baseUrl | The plugin also routes root `/_expo/loaders/*` to the same handler. A second Expo server app on the same origin would collide with it. |
+| `routes.json` is exported unsorted, and expo-server uses the first regex match. `/[model]` matches `/login` and is listed first. | The plugin passes expo-server a manifest whose HTML routes are ordered static, then dynamic, then catch-all, which is the router's own priority. Without that, every static route would render without its loader data. |
+| A layout cannot read loader data: only routes have loaders | Data that every page needs (session, admin config) cannot come from a layout loader |
+| The baseUrl is baked into the asset URLs at build time | `basePath` must equal the baked baseUrl (`/console` by default), or `register()` throws. For another mount, set `experiments.baseUrl` in `admin-spa/app.json` and rebuild (`EXPO_BASE_URL` in the shell has no effect: Metro reads the app config). |
+| Expo exports a `pageHeaders` rule that sets `Cache-Control: no-store` on every loader response, applied after Express middleware | The plugin rewrites that rule to `no-store, private` when it prepares the manifest. A header set in Express alone would be overwritten. |
+| `render.js` is self-contained and loaded with a runtime `require` | It runs inside a `bun build --compile` binary with no `node_modules` next to it. `ADMIN_SPA_DIST_DIR` points the binary at the copied export root. |
+
+## Request scope and server-side data
+
+Each server render runs inside a request scope: one `AsyncLocalStorage`, shared by every
+bundle in the process through `Symbol.for("terreno.adminSpa.requestStore")`.
+`runInAdminSpaRequest(scope, fn)` sets it, and `getAdminSpaRequest()` reads it in `render.js`,
+`+html.tsx` and the loaders. The plugin opens a base scope (`appConfig`, `basePath`) for every
+render; middleware that opened one earlier keeps its own. Two concurrent renders never see each
+other's scope, so data loaded for one operator cannot reach another's page.
+
+A loader fetches the API data a screen needs with `loadSsrPayload(request, {requests})`:
+
+- Each request is a path plus query (route params already `encodeURIComponent`-encoded) and,
+  optionally, `X-Organization-Id`. Any other header is rejected with `SSR header not allowed`.
+- The path is normalized first (dot segments resolved, encoded segments kept encoded) and must
+  start with one of `ssrApiPrefixes`: by default the admin API base path, `/auth/me`, `/orgs`,
+  `/jobs`, `/comms`, `/configuration` and `/rbac`. Anything else, including an absolute URL, is
+  rejected with `SSR path not allowed`. Every request is checked before any is sent.
+- Requests go in parallel to `internalOrigin` (default `http://127.0.0.1:${PORT ?? 4000}`)
+  with only the visitor's `Cookie`. The origin never comes from `Host` or `X-Forwarded-*`.
+- A visitor with no cookie fetches nothing, so anonymous traffic never shares the loopback
+  address's rate-limit bucket.
+- The result is `{rpc, status}`, keyed by `adminRpcSeedKey(url, headers)` from
+  `@terreno/admin-frontend`, ready for `AdminRpcSeed`. A failed read has a status and no body.
+- A transport failure or a 2xx body that is not JSON throws an error naming only the API path,
+  without its query string (a search filter can hold PHI). The underlying error is not
+  attached, because its message carries the full URL, and the parser's would quote the body.
+
+## PHI in rendered pages
+
+Rendered pages and loader data can hold PHI, so:
+
+- Every HTML page, every `{basePath}/_expo/loaders/*` response and every root
+  `/_expo/loaders/*` response sends `Cache-Control: no-store, private`. `app-config.json` stays
+  `no-store`; hashed assets keep their immutable cache.
+- JSON written into HTML goes through `serializeForHtml`, which escapes `<`, `>`, `&`, U+2028
+  and U+2029, so a stored value such as `</script><script>` cannot end the script.
+- A failed render or loader logs `Admin SPA render failed for <route path>` with the error
+  message only. The page's query string is never logged. A loader that throws its own error
+  owns what that message says.
+- Each `loadSsrPayload` read has a 5 s timeout and fails on its own: a network error, a timeout
+  or a body that is not JSON leaves that read out (the screen loads it on the client) and warns
+  with the API path only, never its query string, the cookie or the body. The other reads still
+  seed the page. A request outside the SSR allowlist still throws before anything is fetched.
+- Server render code warns through `warnAdminSpaServer`, which calls the host's `logger.warn`
+  (the plugin publishes it on the server context), so these warnings reach the backend's log
+  transports even though the render bundle stubs `@terreno/api`.
+
+## Access is decided before rendering
+
+`createAdminSpaGate` runs in Express before any page or loader renders. It gates `GET`
+requests under `basePath` (except `_expo/static`, `assets` and `app-config.json`) and loader
+requests at the root `/_expo/loaders/*`. It decides on the normalized path (dot segments,
+including encoded ones, resolved) and hands Expo that same path, so a path such as
+`/console/assets/../Todo` cannot pass as an asset and then render as `/Todo`. A request under
+`_expo/static`, `assets` or `app-config.json` that is not a real file gets a 404: it never
+reaches the page renderer, which would otherwise render `/assets/Todo` as a model page.
+The admin SPA serves only reads: any other method under `basePath`, or at the root
+`/_expo/loaders/*`, passes on to the host app (a 404 unless the host handles it) and never
+reaches the renderer or a loader.
+
+For a visitor with `req.user`, it reads three things over loopback, in parallel, with the
+visitor's cookie: `{authBasePath}/get-session`, `/auth/me` and `{adminApiBasePath}/config`.
+A 200 from the config means admin, a 403 means signed in but not an admin, and a 401 from any
+of them means anonymous. Anything else (a 5xx, a network error, no answer within 5 s) answers
+503 without rendering: the gate fails closed.
+
+| Visitor | Page | Loader data |
+| --- | --- | --- |
+| Anonymous | `/login` renders; any other page redirects to `/login?returnTo=<path>` | 401 JSON, except `login` and `forbidden` |
+| Not an admin | `/login` redirects to a safe `returnTo` when there is one; `/login`, `/forbidden` and the signed-in-only `/oauth/consent` render; any other page redirects to `/forbidden` | 403 JSON, except `login`, `forbidden` and `oauth/consent` |
+| Admin | `/login` redirects to `returnTo` (or `/`); `/forbidden` redirects to `/`; every other page renders | runs |
+
+`returnTo` is an in-app path. `sanitizeReturnTo` accepts it only when it starts with a single
+`/` and has no scheme and no backslash, so it cannot send anyone to another site. The gate and
+the login screen use the same function.
+
+An admin's render runs in a request scope that holds the session snapshot `{userId, user}`, the
+profile, and the admin config, so the shell can render from them. `AdminGate` keeps its client
+redirects as a fallback for a session that ends after the page has loaded. While the client
+session is still loading, it renders `/login` as is, so the server-rendered form stays on
+screen, and shows a spinner on other routes.
+
+## Hydrating the shell
+
+The server render hands the browser what the gate already read, so the shell renders on its
+first client render with no spinner and no repeated requests:
+
+- `+html.tsx` writes the request scope into `<script id="admin-spa-ssr" type="application/json">`
+  with `serializeForHtml`. `useSsrPayload()` returns that scope on the server and, in the
+  browser, reads the script once and removes it.
+- `StoreProvider` passes the payload's session to the session store as `initialSession`, so
+  `useSession()` is settled from the first render, and primes the request client's
+  `GET /auth/me` entry with the profile (`primeQuery`).
+- The layout wraps `AdminGate` in `<AdminRpcSeed>` with the payload's admin config, so every
+  `/admin/config` reader renders from it. The config is filtered per user, so it seeds only
+  while the payload's session is the live one; after another sign-in, readers fetch their own.
+  Likewise, a payload with `adminConfigStatus: 403` sends the session to `/forbidden` without
+  probing the config again, but only while the live session is the payload's.
+- With a payload, the sync provider renders the shell at once and starts syncdb behind it; a
+  failed start shows an error above the shell. Without one (dev proxy), it keeps the spinner.
+- On the server, clients are built on `internalOrigin`, and nothing starts: no session watch,
+  no socket, no request.
+- The server lays out for a 1280×800 viewport (`Dimensions.set` in `+html.tsx`), so a desktop
+  browser hydrates into the same tree. A narrower browser re-renders once after hydration.
+
+The payload describes only the page the server rendered. After the first client commit,
+`useSsrPayload()` returns `undefined` to anything that mounts later, so a sign-in, sign-out
+or navigation reads live state. Route loader data (`__EXPO_ROUTER_LOADER_DATA__` and its
+inline script) is deleted once every route has read its entry, or after 5 s. Loader rows can
+hold PHI, so they do not stay on `window` or in the DOM, and a later client navigation fetches
+loader JSON instead.
+
+## Server-rendered data
+
+Route loaders render a screen's data into the first HTML. Each one asks for the same URLs the
+screen's hooks request, through `loadSsrPayload`, and the route wraps its screen in
+`<AdminRpcSeed data={rpc}>`, so the hooks render the seeded bodies and skip their first fetch.
+
+- **Model list** (`/console/<Model>`): the loader resolves the model by name from the gate's
+  admin config with `resolveModelListUrl` and fetches its first page: page 1, the model's page
+  size, its default sort. It builds the URL with the table's own builders
+  (`buildAdminListQueryParams`, `buildAdminApiListQueryRequest`), so the key matches the
+  table's request. An unknown name or a screen that is not a model list loads nothing.
+- **Model detail** (`/console/<Model>/<id>`): the loader fetches the document's read URL
+  (`resolveModelReadUrl`) and seeds the form, which fills its fields on the first render. A
+  backend 404 renders a "Not found" page with HTTP 200: expo-server 58 can set another status
+  only by throwing, which replaces the page with an error body.
+- **Read URLs:** `useReadQuery` builds them with `buildAdminReadUrl(routePath, id)`, which
+  encodes the id, so a server render that uses the same builder seeds the same key. Loaders
+  decode their route params first, because expo-server passes them still encoded.
+- **Encoded ids (Expo 58 limitation):** Expo keys server loader data by the raw path but looks
+  it up by the decoded params. The gate canonicalizes escapes (RFC 3986: `%36` becomes `6`), so
+  an over-encoded plain id renders normally. An id that must stay encoded (a space, `/`, `%` or
+  a non-ASCII character) renders its page without the form's values; the browser then fetches
+  the loader data and fills the form. Expo's client trims leading and trailing whitespace
+  from the path, so for such an id it fetches another path's loader data; the form then falls
+  back to its own read, and a missing record shows an empty form rather than "Not found".
+  ObjectIds and UUIDs never need encoding.
+- **RPC screens** (home, configuration, roles, scripts, version config): each route's loader
+  fetches `rpcUrlsForRoute(route)`, the exact URLs its screen's `useAdminRpcQuery` calls request
+  on mount, and wraps the screen in `RouteSeed`. A read that fails, or a URL outside the SSR
+  allowlist, is left out and loads on the client.
+- **Home widgets:** `homeWidgetUrls` derives the home page's URLs from `adminConfig.home.slots`
+  for the built-in widgets (`modelStats` / `modelsGrid`, `recentActivity`, `versionConfig`,
+  `jobs`). Custom app widgets are not seeded and load on the client, as are organization-scoped
+  models, because a server render has no organization selected.
+- **Jobs and comms** (`/console/jobs`, `/console/comms` and their detail pages): the loaders
+  fetch the URLs the dashboards request on mount (`jobsSsrUrls`, `commsSsrUrls`); a missing
+  job or message renders "Not found" with HTTP 200. The comms dashboard's default 7-day range
+  ends at the next whole minute, so the server render and the hydrating browser build the same
+  URL within that minute.
+- **Organizations** (`/console/orgs` and an organization's settings and members): the loaders
+  build their requests with `orgsSsrRequests`. Organization-scoped reads carry the hooks'
+  `X-Organization-Id`, which is part of the seed key. The directory is fetched only for an
+  operator (`operator` or `superadmin` role on the gate's profile); an organization admin gets
+  no directory data, as on the client.
+- **Path ids:** the jobs, comms and organization hooks put the decoded id into their URL
+  unencoded, so the server seeds an id only when it is one plain path segment: no `/`, `?`,
+  `#`, `\` or `%`, and not `.` or `..`. Any other id seeds nothing, and the screen loads it on
+  the client.
+- **Selected organization (limitation):** once the client selects an organization (from
+  `/orgs/mine`), its model reads carry `X-Organization-Id`. A server render has no selected
+  organization, so for a visitor who belongs to one, the model list and detail seeds do not
+  match and those screens refetch after hydration. The first HTML still shows the visitor's
+  own data; nothing crosses organizations, since every read uses the visitor's session.
+- **Windowed sync models** render the seeded REST page first. The admin provider binds the
+  syncdb client only after `start()` resolves, and the table then switches to its window,
+  so live updates reach it. On that switch the table refetches its REST page once, so a change
+  made between the server render and the sync start shows up without a manual refresh.
+
+## Related
+
+- [Admin SPA reference](../reference/admin-spa.md)
+- [How admin interfaces are shaped](admin-interface.md)