@terreno/mcp 58.0.0-beta.2 → 58.0.0-beta.4

package/src/docs/versioned/next/reference/admin-frontend.md

@@ -561,6 +561,55 @@ client is `adminRequest`, built on `apiFetch` from `@terreno/syncdb/api` (timeou
 `FormData`, `credentials` forwarded); `unwrapAdminEnvelope` unwraps `{data}` responses the
 same way the syncdb request client does.
 
+### buildAdminReadUrl, buildAdminListQueryParams, buildAdminApiListQueryRequest
+
+The URL builders the model hooks use, exported so a server render can request exactly what a
+screen will request and seed it under the same key:
+
+- `buildAdminReadUrl(routePath, id)`: `GET {routePath}/:id`, with `id` encoded by
+  `encodeURIComponent`. `useReadQuery` uses it.
+- `buildAdminListQueryParams({filterState, limit, modelConfig, page, searchDebounced, sort?})`:
+  the list params `AdminModelTable` sends for its current state.
+- `buildAdminApiListQueryRequest(routePath, params)`: `{method: "GET", url}` for a list
+  request, with the params serialized as `useListQuery` serializes them.
+
+### homeWidgetUrls
+
+`homeWidgetUrls({adminConfig, apiBase})` returns the URLs the home dashboard's built-in widgets
+request on mount, for the widgets in `adminConfig.home.slots`: one `limit=1` count per model for
+`modelStats` / `modelsGrid`, the audit log's first 8 rows for `recentActivity`,
+`{apiBase}/version-config` for `versionConfig`, and `/jobs/stats` for `jobs`. Each URL appears
+once. Custom widgets and organization-scoped models contribute nothing: a server render seeds
+what this returns, and the rest loads on the client.
+
+### AdminRpcSeed and adminRpcSeedKey
+
+`<AdminRpcSeed data={...}>` gives `useAdminRpcQuery` initial data, such as response bodies a
+server render already fetched. Key each body with `adminRpcSeedKey(url, headers?)`: the exact
+`url` the hook receives (query string included) plus its `X-Organization-Id` header, when it
+sends one. Other headers do not change the key, so a body fetched for one organization, or for
+none, never answers a hook that asks for another.
+
+```tsx
+import {AdminRpcSeed, adminRpcSeedKey} from "@terreno/admin-frontend";
+
+<AdminRpcSeed data={{[adminRpcSeedKey("/admin/roles")]: roles}}>
+  <AdminRolesList />
+</AdminRpcSeed>
+```
+
+A query with a matching seed returns it as `data` (after `transformResponse`) with
+`isLoading: false` on its first render, and skips its first fetch. It fetches again on
+`refetch()`, when its `url` or `X-Organization-Id` changes, and when a mutation invalidates its
+`providesTags`. `skip: true` wins over a seed. Seeds nest, and inner seeds override outer ones
+for the same key. `AdminRpcSeed` does not need `AdminProvider`.
+
+Seeded or not, `useAdminRpcQuery` treats a change of `url` or `X-Organization-Id` as a new
+request and clears the previous body before the next render is shown, so one organization's data
+never appears under another. `keepPreviousData` keeps rows across a `url` change only while the
+organization stays the same. In earlier releases, an organization change on the same `url` kept
+the old body on screen until the new one arrived.
+
 ## Expo Router Setup
 
 ``````typescript
@@ -697,10 +746,34 @@ plugin is on. `AI Requests` (`ai-requests`) stays ungrouped. Widgets also regist
 `ai-prompt-editor`, `ai-trace-detail`, `ai-review-item`, `ai-evaluator-detail`, `ai-evaluator-new`,
 `ai-dataset-detail`, `ai-experiment-new`, and `ai-experiment-results`.
 
-Every observability screen wraps `AiObservabilityChrome`: breadcrumbs
-`Admin / AI Observability / <Section> / <leaf>` and a status chip from
-`GET /ai/observability/status` (`Local on|off` plus active primaries). Review queue nav and the
-review screen body hide when `localOn` is false.
+Every observability screen wraps `AiObservabilityChrome`: a breadcrumb row with a quiet status
+chip from `GET /ai/observability/status` (**Local observability on** / **Local observability
+off**), then one left-aligned page header (title, one-sentence description, optional meta badges,
+and header actions on the right). There is no back arrow. List screens end the breadcrumbs at the
+section (`Admin / AI Observability / <Section>`); detail screens add the leaf
+(`Admin / AI Observability / <Section> / <leaf>`). Review queue nav and the review screen body
+(including header actions) hide when `localOn` is false.
+
+#### Shared patterns
+
+The shell components live in `widgets/aiObservability/shell/`:
+
+| Component | Use |
+| --- | --- |
+| `ObservabilityPageHeader` | The one page header: 32px title, one sentence of purpose, optional `meta`, and `actions` that wrap under the title on phones. `AiObservabilityChrome` renders it from `title`, `description`, `meta`, and `actions` |
+| `ObservabilityStatusBadge` | The one status scale (`observabilityStatus.ts`): pending neutral, in progress / running info, done / completed / ok success, skipped neutral, failed / error error. Unknown statuses fall back to a neutral badge with a readable label |
+| `AgreementMeter`, `ProgressMeter`, `MeterBar` | `AgreementMeter` shows judge-vs-people agreement as percent, bar, and badge from `AGREEMENT_THRESHOLDS`: ≥ 90% **Matches**, 75–89% **Close**, < 75% **Off**, otherwise **No answers yet** (`compact` drops the bar). `ProgressMeter` shows "8 of 10" with a bar. `MeterBar` is the thin bar both use |
+| `ObservabilityEmptyState`, `ObservabilityErrorState` | Empty list: icon, short heading, the next step, and an optional outline action. Load failure: alert banner in place of the content with an outline **Try again** |
+| `EvalStepper` | Numbered stepper: done steps show a check, the current step is filled, later steps are outlined. Used for the four-step eval plan and both New experiment wizards |
+
+Rules:
+
+- One primary action per screen, in the header. Other header actions are outline.
+- Colour means state, never kind. Kinds (evaluator type, prompt folder, experiment kind) use
+  neutral badges or `SegmentedControl` filters.
+- Filters and pickers with a few fixed choices use `SegmentedControl`. Status tabs show counts as
+  badges.
+- Labels are readable words, not API keys (for example **Has a score**, **Agrees with people**).
 
 Each observability list screen is contributed with `adminAccess: {resource, action: "list"}` so
 `/admin/config` omits screens the caller cannot list (`aiPrompt`, `aiTrace`, `aiEvaluator`,
@@ -712,24 +785,26 @@ action). Legacy admin users and apps without `accessControl` receive all actions
 callers receive effective flags for the signed-in user. Pass the same `accessControl` to
 `ObservabilityApp` and `AdminApp` so status permissions match sidebar filtering. Admin widgets
 read the payload through `resolvePromptActionPermissions` and `observabilityActionAllowed` (fail
-closed while status is loading, errored, or missing `permissions`). List screens gate **Create
-prompt** on `aiPrompt:create`, **Create evaluator** on `aiEvaluator:create`, and **New dataset** on
-`aiDataset:create`; experiment lists hide **New experiment** without `aiExperiment:create`.
+closed while status is loading, errored, or missing `permissions`). List screens gate the header
+**New prompt** on `aiPrompt:create`, **New evaluator** on `aiEvaluator:create`, and **New dataset**
+on `aiDataset:create`; experiment lists hide **New experiment** without `aiExperiment:create`.
 Dataset detail hides **Add item** without `aiDataset:update` and **Run experiment** without
 `aiExperiment:create`; dataset lists hide **Import** without
 `aiDataset:update`. Judge schema checks use the production prompt version, or the latest version
 when production is unset. Widgets do not couple to host app state.
 
-`ai-prompts` lists prompts with a folder rail, search, type badge, latest vs production columns
-(tooltips), 7-day usage, and **Create prompt** when `aiPrompt:create` is allowed. The create modal
-includes an optional **Description** (saved on the prompt record and shown on the hub Overview tab).
-`ai-prompt-editor?name=` is a prompt hub with **Overview**, **Versions**, **Traces**, and
-**Experiments** tabs. Overview shows optional description, folder, tags, and latest vs production
-badges. Traces and Experiments render bounded relationship rows from
+`ai-prompts` lists prompts with a folder `SegmentedControl` (All plus each folder, with counts),
+search, type, Production and Newest version columns, 7-day calls, last used, and a header **New
+prompt** when `aiPrompt:create` is allowed. The create modal
+includes an optional **Description** (saved on the prompt record and shown on the hub Versions screen).
+`ai-prompt-editor?name=` is a prompt hub with **Versions**, **Traces**, and
+**Experiments** tabs. Versions shows optional description, folder, tags, latest vs production
+badges, and the version editor on one screen. System and template fields include helper text.
+Traces and Experiments render bounded relationship rows from
 `GET /ai/observability/prompts/:name?promptVersion=` (the hub pins the selected version, defaulting
 to latest after the first load, so related traces and experiments are filtered server-side while the
-full immutable version list stays on the detail payload). The **Versions** tab
-hosts the versioned editor: full-width version history rows show `vN`, every label attached to
+full immutable version list stays on the detail payload). The **Versions** screen
+hosts the versioned editor under that metadata: full-width version history rows show `vN`, every label attached to
 that version, and its creation time on one line. The selected row is highlighted. Editor /
 Playground tabs appear on Versions when allowed; **Save as vN+1**, **Set vN as production…**, and
 playground **Run once** hide when `aiPrompt:update`, `aiPrompt:promote`, or `aiPrompt:playground`
@@ -744,17 +819,21 @@ trimmed key is available. When `playgroundAi.source` is `server`, no key is requ
 `requestAiServiceFactory`. A stale playground **503** with the missing-key title is remapped to the
 same hint for `request-key` hosts so operators are not told to fix server configuration. The
 example admin supplies the Gemini key saved from Profile. **Save this run to dataset** stays
-disabled until phase 2.
-
-`ai-traces` lists traces with a filter bar: from/to date fields; dropdowns for prompt, status,
-score presence (**All traces / Has a score / No scores**), and data sensitivity
-(**All traces / Sensitive only / Not sensitive**); plus user and session text fields.
+disabled until phase 2. The editor's schema line lists variables and output fields: for a JSON
+Schema `outputSchema` it names each entry in `properties` with its `type` (for example
+`faithful (boolean)`); for a plain field map it lists the keys.
+
+`ai-traces` lists traces in a `DataTable` sorted on the server (`sort` query param): Trace,
+Status, Started, Tokens, Latency, Cost, and Scores are sortable, newest first by default.
+Filters live in the column headers: Trace (prompt), Status (OK / Error), Started (date range), and
+Scores (**Has a score**), plus additional filters for Sensitive, User, and Session. Changing a sort or
+filter returns to page 1 and clears the selection.
 Checkbox selection opens a bulk bar with **Send to human review**, a sensitive-count
 warning, **Clear**, and **Add to dataset** (opens a dataset picker modal; sensitive traces show a
 warning before bulk add). **Send to human review** opens a modal that explains how human
 evaluators define the score fields and reviewer instructions, then requires a human evaluator
-before creating one review-queue item per trace. When local trace storage is on,
-**Run multi-stage trace test** calls the admin-only smoke endpoint and
+before creating one review-queue item per trace. When local trace storage is on, the header
+**Run a test trace** action calls the admin-only smoke endpoint and
 opens the resulting detail: two schema-validated LLM stages, one deterministic tool span, and a
 final schema-validated combining LLM stage under one CHAIN root. LLM span input includes
 `outputSchema`. That run needs AI the same way the playground does: hosts may pass `apiKey`,
@@ -762,28 +841,45 @@ final schema-validated combining LLM stage under one CHAIN root. LLM span input
 `x-ai-api-key`. When `GET /ai/observability/status` reports `playgroundAi.source: "request-key"`
 and no trimmed key is available, the button is disabled and the hint explains where to save one;
 `unavailable` instead reports that the backend must configure `aiService` or
-`requestAiServiceFactory`. The example admin supplies the Gemini key saved from Profile. Rows show a status dot (primary for successful runs, accent for failed runs),
-`sensitive` badge, error line, numeric prompt count, span count, tokens, cost, latency, score count, and
-**Open**. Pagination uses `page` / `limit` / `more` / `total`.
+`requestAiServiceFactory`. The example admin supplies the Gemini key saved from Profile. Each row's
+Trace cell (click to open) shows the name, a **Sensitive** badge, and a subline; Status shows the
+shared status badge and the error line for failed runs; then tokens, latency, cost, and score
+count. Pagination uses `page` / `limit` / `more` / `total`.
 `ai-trace-detail?id=` shows the header, left span list (kind badge, indent, duration bar),
 right span detail with **collapsed** sensitive I/O, and scores (value + source). The two columns
 size from the row width rather than their content, so a wide span value (multi-stage LLM spans embed
 `outputSchema` JSON) wraps inside the detail column instead of pushing it below the span list.
 
-`ai-review` shows Pending / In progress / Done / Skipped tabs with counts. Each tab is
-oldest-first and lists the trace action, prompt, assignee, waiting time, and status.
-**Start reviewing — oldest first** opens the first pending item; the empty state names both
-Traces intake and manual **Assign to me** assignment.
-
-`ai-review-item?id=` shows "Item N of M pending", previous/next navigation, read-only
-**What the AI was given** / **What the AI wrote** panels, collapsed long fields with word
-counts, reviewer notes, and a collapsed Raw JSON disclosure. Score controls come from evaluator
-dimensions (numeric slider, boolean Pass / Fail, categorical pills). Actions are
-**Submit & next**, **Skip**, and **Assign to me**; completion toasts report the remaining count
-or **Queue clear**.
-
-`ai-evaluators` lists evaluators with type badge, dimension summary, target, and run-mode chips.
-**Create evaluator** opens `ai-evaluator-new` with the name and optional purpose first, then how
+`ai-review` shows Pending / In progress / Done / Skipped as a `SegmentedControl` with counts.
+Each tab is oldest-first and lists the output (click to open), question set, prompt, assignee,
+waiting time, and status. Header actions are outline **Review batches** and the primary **Review
+oldest pending**, which opens the first pending item; the empty state points to Traces and review
+batches.
+
+`ai-review-batches` lists batches with answered-by-people progress and the best judge's agreement.
+The search field and **More filters** button sit on the same baseline. Pick a question set and optional
+prompt, then **Save batch** on the New batch card creates
+a batch from the 10 newest successful traces. `ai-review-batch?id=` shows progress, **Answer N remaining**, **Run on N items** for a
+chosen judge, and **Which judge matches people?** with an `AgreementMeter` per judge.
+
+`ai-review-item?id=` is titled "Item N of M" (or "Review item" when not pending), with status and
+source badges under the title and outline **Previous** / **Next** in the header. **What the AI was
+given** and **What the AI wrote** are headings above equal columns; each card holds the field
+labels and values, and the model output card uses the `ai` surface.
+Long fields start collapsed with a word count; reviewer notes and a collapsed Raw JSON disclosure
+stay available. Every question is on one screen: the segmented **Yes** / **No** control (or a
+numeric slider or categorical pills) is a fixed-width column on the left and the question is on
+the right. A numeric or categorical score with no `question` spans the full row under its
+humanized key (for example `tone_rating` reads "Tone rating"). On web, `Y` / `N` answer the highlighted question as soon as the item opens, including
+when a Yes/No segment is focused, `Enter`
+submits, and `S` skips. Actions are **Submit and open next**, **Assign to me**, and **Skip**;
+completion toasts report the remaining count or **Queue clear** (**Batch complete** inside a
+batch). The nested admin stack hides its header (`headerShown: false`); `AdminScreenPage` owns
+the back arrow.
+
+`ai-evaluators` lists evaluators with a kind `SegmentedControl` (All / Human / LLM judge / JSON
+assert), kind, scores, looks at, runs in, and **Agrees with people** (`AgreementMeter`). The header
+**New evaluator** opens `ai-evaluator-new` with the name and optional purpose first, then how
 scoring happens (human / JSON assert / LLM judge). New evaluators score a **full trace** only;
 generation span and dataset item targets are not offered yet. Score fields depend on data type:
 boolean has no extra control, numeric asks for min and max, and categorical is a list you add to.
@@ -794,18 +890,21 @@ model-call impact. The optional purpose is saved as the evaluator description an
 detail screen. LLM judge schema feedback stays idle until a prompt is selected, then shows
 loading/error states and only checks dimensions after its production schema loads.
 `ai-evaluator-detail?id=` leads with the evaluator name, description, and type/target/run-mode
-badges, then explains the saved scores, how scoring works, where it runs, and a **Used by** list
-derived from recent experiments. A failed experiments request shows **Could not load experiments.**
+badges, then explains the saved scores, how scoring works, where it runs, and a **Used in the last 30 days**
+table derived from recent experiments. Each experiment name opens that experiment's results.
+A failed experiments request shows **Could not load experiments.**
 instead of an empty 30-day list. Its dimension and usage rows use the shared `ObservabilityTable` instead of
 `DataTable`, which sizes to a height-constrained parent and collapses inside a scrolling page. LLM
 judge details show loading or load-failed feedback while resolving the judge prompt; schema
 mismatches appear only after its production schema loads.
 
 `ai-datasets` lists datasets with item counts, provenance bar, input-schema binding, and updated
-time. **New dataset** creates a dataset; **Import** on each row accepts `.json` or `.csv` via
+time. When any dataset has human answers, a **People's answers** column summarizes each dataset's
+`judgments`: **N answers out of date** when questions were reworded since they were answered,
+**All answered** when every question set answered every item, otherwise **N of M answered**. The header **New dataset** creates a dataset; **Import** on each row accepts `.json` or `.csv` via
 `FilePickerButton` (local URI read) or paste, posting `{rows}` for JSON or `{format:'csv',content}`
 for CSV. `ai-dataset-detail?id=` shows counts, schema binding, tabs **All / Human / Auto / Needs
-review**. Human is proofread items. Auto is unreviewed trace or synthetic items, so a proofread
+review** (a `SegmentedControl`). Human is proofread items. Auto is unreviewed trace or synthetic items, so a proofread
 trace is not listed in both tabs. The screen includes an items table (input, expected, provenance,
 trace link), **Add item**, and **Run experiment**. The items table uses `ObservabilityTable`: rows grow with their content
 and cells wrap to three lines before truncating, so long inputs and expected outputs no longer
@@ -823,13 +922,26 @@ cell renders truncated text and a node cell renders as-is. Its
 bordered shell shrink-wraps the rows inside flex/scroll parents so its bottom border cannot stretch
 into the following section.
 
-`ai-experiments` lists experiments with status, running progress, and cost. **New experiment**
-opens a four-step wizard (dataset with counts, prompt versions tagged latest/production/superseded,
-llm-judge and json-assert evaluators, review & run with estimate). A slower in-flight estimate is ignored after the selection changes, so it cannot replace a newer estimate or its error. Human evaluators are omitted. On the prompt-versions step, **Next** and the later
-wizard rail buttons stay disabled until 2–3 versions are selected. `includeUnproofread` and optional model override are on
-the wizard. `ai-experiment-results?id=` polls while pending/running, shows gate tiles per version,
-failing gate count, outliers, a side-by-side per-item output table (failed rows first from the
-API), and **Promote to production** with a confirm modal; promote is blocked when gates fail (409).
+`ai-experiments` lists experiments with a kind `SegmentedControl` (All / Judge calibration /
+Prompt comparison), status badge, running progress (`ProgressMeter`), result, and cost. The screen
+loads the newest 100 experiments (the route's maximum page); sorting and filters apply to those,
+and when the server reports more, a note under the table (`ai-experiments-truncated-note`) says so. The header
+**New experiment** opens `ai-experiment-new`, where a `SegmentedControl` picks **Calibrate a
+judge** or **Compare prompt versions**. Each pipeline is a four-step `EvalStepper` wizard with
+ghost **Back** and primary **Continue** (the last step shows the run button). Compare prompt
+versions: Dataset (with counts), Prompt versions (tagged latest/production/superseded),
+Evaluators (llm-judge and json-assert), Review and run (with estimate). Calibrate a judge:
+Judged dataset, Question set, Judge and versions, Review and run. A slower in-flight estimate is
+ignored after the selection changes, so it cannot replace a newer estimate or its error. Human
+evaluators are omitted. On the prompt-versions step, **Continue** and later stepper steps stay
+disabled until 2–3 versions are selected. `includeUnproofread` and optional model override are on
+the wizard. `ai-experiment-results?id=` polls while pending/running (`ProgressMeter`), shows one
+verdict banner, one **Gates** table (Gate, Needs, one Pass / Fail column per version), outliers, a
+side-by-side per-item output table (failed rows first from the API), and header actions outline
+**Run again** and primary **Promote vN to production** with a confirm modal; promote is blocked
+when gates fail (409). The promoted version defaults to the newest version that passes every gate
+(the newest version while gates are pending) and follows the gates as they arrive, until the
+operator picks one in **Version to promote**, which appears once gates exist and a version passes.
 
 ### AI Harness approvals inbox
 

package/src/docs/versioned/next/reference/admin-spa.md

@@ -1,9 +1,11 @@
 # @terreno/admin-spa
 
-Standalone Expo Router admin web SPA plus an Express plugin (`AdminSpaServeApp`) that serves the pre-built static export from a Terreno backend on the same origin.
+Standalone Expo Router admin web SPA plus an Express plugin (`AdminSpaServeApp`) that server-renders the pre-built export from a Terreno backend on the same origin.
 
 How screens and nav work (including `routeBase=""`): [How admin interfaces are shaped](../explanation/admin-interface.md).
 How to add a screen: [Build admin screens](../how-to/build-admin-screens.md).
+How server rendering works: [Server-rendering the admin SPA](../explanation/admin-spa-ssr.md).
+Upgrading from the static export: [Upgrade to the server-rendered admin SPA](../how-to/upgrade-admin-spa-ssr.md).
 
 ## Table of Contents
 
@@ -13,6 +15,8 @@ How to add a screen: [Build admin screens](../how-to/build-admin-screens.md).
 - [AdminSpaServeApp](#adminspaserveapp)
 - [App config](#app-config)
 - [Serving and caching](#serving-and-caching)
+- [Access gate](#access-gate)
+- [Loopback calls and rate limits](#loopback-calls-and-rate-limits)
 - [Mount path constraint](#mount-path-constraint)
 - [Standalone SPA vs embedded admin-frontend](#standalone-spa-vs-embedded-admin-frontend)
 
@@ -30,10 +34,10 @@ From the `@terreno/admin-spa` package directory:
 
 ```bash
 bun run compile      # Compile the server plugin (src/ -> src/dist)
-bun run build:web    # Expo static export into dist/
+bun run build:web    # Expo server export into dist/ (client/ + server/)
 bun run dev          # expo start --web --port 8083
 bun run test:ci      # Serve-plugin unit tests
-bun run smoke        # Smoke test over built dist/
+bun run smoke        # HTTP smoke over the built dist/ (SSR login, root loader, app-config)
 bun run test:e2e     # Playwright e2e over built dist/
 ```
 
@@ -43,15 +47,21 @@ bun run test:e2e     # Playwright e2e over built dist/
 admin-spa/
   src/
     serve.ts           # AdminSpaServeApp TerrenoPlugin
+    gate.ts            # Access gate, run in Express before any render
     appConfig.ts       # AdminSpaAppConfig defaults + merge helper
     index.ts           # Public exports
-  app/                 # Expo Router SPA (Better Auth + admin screens)
+  app/                 # Expo Router routes (Better Auth + admin screens), with route loaders
+  server/              # Loader helpers: loadSsrPayload, model, RPC, jobs/comms and orgs requests
   components/          # AppConfigGate, StoreProvider (session + request client), AdminGate
   store/               # Admin window syncdb config
-  dist/                # Pre-built static export (produced by build:web)
+  dist/                # Export root, produced by build:web
+    client/            # Hashed JavaScript and assets
+    server/            # Expo server build: _expo/routes.json, render.js, one module per loader
 ```
 
-Boot flow in the SPA: `AppConfigGate` fetches `${basePath}/app-config.json` →
+Boot flow in the SPA: `AppConfigGate` reads the config the server render wrote into the page
+(`window.__ADMIN_SPA_CONFIG__`), and fetches `${basePath}/app-config.json` only in dev proxy
+mode →
 `StoreProvider` builds a cookie-session Better Auth client and a same-origin
 request client (`createApiClient({credentials: "same-origin"})` from
 `@terreno/syncdb/api`), then mounts `SessionProvider` (`@terreno/syncdb/auth`) and
@@ -77,7 +87,7 @@ The default `/console` mount therefore serves these as `/console/orgs/...`.
 
 ## AdminSpaServeApp
 
-`AdminSpaServeApp` implements `TerrenoPlugin`. Register it on `TerrenoApp` alongside `AdminApp` and auth plugins:
+`AdminSpaServeApp` implements `TerrenoPlugin`. Register it after `BetterAuthApp` and `AdminApp`. The access gate reads `req.user`, which the Better Auth session middleware sets, so `BetterAuthApp` must be registered before `AdminSpaServeApp`:
 
 ```typescript
 import {AdminSpaServeApp} from "@terreno/admin-spa";
@@ -97,7 +107,7 @@ new TerrenoApp({userModel: User})
   .start();
 ```
 
-`example-backend` registers the plugin when `ADMIN_SPA_ENABLED=true`, with optional `ADMIN_SPA_DEV_PROXY` and `ADMIN_SPA_DIST_DIR` overrides.
+`example-backend` registers the plugin when `ADMIN_SPA_ENABLED=true`, with optional `ADMIN_SPA_DEV_PROXY` and `ADMIN_SPA_DIST_DIR` (the export root, passed as `distDir`) overrides.
 
 ### AdminSpaServeOptions
 
@@ -105,13 +115,18 @@ new TerrenoApp({userModel: User})
 |--------|---------|-------------|
 | `basePath` | `"/console"` | URL prefix where the SPA is mounted. Admin API stays at `/admin`. |
 | `appConfig` | see [App config](#app-config) | Partial config merged over defaults; served at `${basePath}/app-config.json`. |
-| `distDir` | `<package>/dist` | Directory containing the pre-built static export (tests/custom builds). |
+| `distDir` | `<package>/dist` | The export root: the directory that holds `client/` and `server/`, not `client/` itself. Set it for a compiled binary, a custom build, or tests. |
 | `devProxyTarget` | — | When set, proxy all SPA paths to a running `expo start --web` server (e.g. `http://localhost:8083`). `app-config.json` is still served by the plugin. |
+| `internalOrigin` | `http://127.0.0.1:${PORT ?? 4000}` | Origin server renders fetch API data from, with the visitor's cookie. Never derived from `Host` or `X-Forwarded-*`. |
+| `ssrApiPrefixes` | admin API base path, `/auth/me`, `/orgs`, `/jobs`, `/comms`, `/configuration`, `/rbac`, and the RBAC root for a nested admin base (`/internal/admin` adds `/internal/rbac`) | API path prefixes a server render may fetch; any other path is rejected before a request is sent, and that screen loads its data on the client. A value replaces the defaults; it is not merged. Include the admin API base path, or model screens load on the client. |
+
+`devProxyTarget` returns before the server render is mounted: in dev there is no access gate,
+no root `/_expo/loaders/*` route and no injected config. `expo start` renders the pages itself.
 
 ### Utility exports
 
-- `rewriteIndexHtml(html, basePath)` — Rewrites absolute `/_expo/` and `/assets/` refs for sub-path mounts.
-- `injectBaseGlobal(html, basePath)` — Injects `window.__ADMIN_SPA_BASE__` before `</head>`.
+- `rewriteIndexHtml(html, basePath)` — **Deprecated.** Rewrites absolute `/_expo/` and `/assets/` refs in a static `index.html`. The server-rendered build has no `index.html`. Removed in the next major release.
+- `injectBaseGlobal(html, basePath)` — **Deprecated.** Injects `window.__ADMIN_SPA_BASE__` before `</head>`. `app/+html.tsx` now writes it into every rendered page. Removed in the next major release.
 - `resolveAppConfig(overrides?)` — Merge partial config with `DEFAULT_APP_CONFIG`.
 - `DEFAULT_APP_CONFIG` — Default `app-config.json` values.
 
@@ -130,20 +145,76 @@ new TerrenoApp({userModel: User})
 
 ## Serving and caching
 
-**Production (no `devProxyTarget`):**
+**Production (no `devProxyTarget`):** `build:web` runs `expo export --platform web` with
+`web.output: "server"`. It writes the export root `dist/`, and the plugin serves it like this:
+
+| Path | Served from | `Cache-Control` |
+| --- | --- | --- |
+| `${basePath}/_expo/*`, `${basePath}/assets/*` | `dist/client/` (`express.static`) | `public, max-age=31536000, immutable` |
+| `${basePath}/app-config.json` | the plugin's merged `appConfig` | `no-store` |
+| `${basePath}` and `${basePath}/*` (pages) | rendered by `dist/server/` behind the [access gate](#access-gate) | `no-store, private` |
+| `${basePath}/_expo/loaders/*` and root `/_expo/loaders/*` (loader data) | rendered by `dist/server/` behind the access gate | `no-store, private` |
+| a gate redirect (302), a gate denial (401/403 JSON), the gate's 503, a render error (500) | the plugin | `no-store, private` |
 
-1. `${basePath}/_expo` and `${basePath}/assets` — `express.static` with `maxAge: 365d`, `immutable: true`.
-2. `${basePath}/app-config.json` — `Cache-Control: no-store`.
-3. `${basePath}` and `${basePath}/*splat` — SPA fallback returns rewritten `index.html` with `Cache-Control: no-store`.
+Pages and loader data can hold PHI, so neither may be cached or shared by a browser, proxy or
+CDN. See [Server-rendering the admin SPA](../explanation/admin-spa-ssr.md) for the request
+scope, `loadSsrPayload` and the escaping rules.
 
-`index.html` is read once at startup; asset paths are rewritten to `${basePath}/...` and `window.__ADMIN_SPA_BASE__` is injected for deep-link config fetches.
+**Root `/_expo/loaders/*`.** Expo SDK 58's client fetches route loader data from the site root,
+`/_expo/loaders/<route>`, and ignores the baked `baseUrl`. The plugin therefore also claims root
+`/_expo/loaders/*` on the backend's origin, behind the same gate and headers. A second Expo
+server app on the same origin would collide with it. A reverse proxy must route root
+`/_expo/loaders/*` to the backend.
+
+**No server build.** If `distDir/server/_expo/routes.json` is missing, the plugin logs a warning
+suggesting `bun run --filter '@terreno/admin-spa' build:web` or `devProxyTarget`, and answers
+`503 Admin SPA unavailable` on `${basePath}` and `${basePath}/*`. Assets and `app-config.json`
+are still mounted. The backend keeps running.
 
 **Development (`devProxyTarget` set):**
 
 - `${basePath}/app-config.json` served locally (no cache).
-- All other `${basePath}/*` requests proxied to the Expo dev server (WebSocket enabled).
+- All other `${basePath}/*` requests proxied to the Expo dev server (WebSocket enabled). No gate
+  and no root loader route are mounted.
+
+## Access gate
+
+`createAdminSpaGate` decides access in Express before anything renders. It gates `GET` and
+`HEAD` requests for pages and loader data. It decides on the normalized path (escapes of
+unreserved characters decoded, dot segments resolved) and hands Expo that same path.
+
+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
+visitor without `req.user` is anonymous and costs no loopback call.
+
+| Visitor | Page | Loader data |
+| --- | --- | --- |
+| Anonymous (no session, or a 401 from any read) | `/login` renders; any other page answers 302 to `${basePath}/login?returnTo=<path>` | 401 JSON, except `login` and `forbidden` |
+| Forbidden (`/admin/config` answers 403) | `/login` answers 302 to a safe `returnTo` when there is one; `/login`, `/forbidden` and the signed-in-only `/oauth/consent` render; any other page answers 302 to `${basePath}/forbidden` | 403 JSON, except `login`, `forbidden` and `oauth/consent` |
+| Admin (`/admin/config` answers 200) | `/login` answers 302 to a safe `returnTo` (or `${basePath}/`); `/forbidden` answers 302 to `${basePath}/`; every other page renders | renders |
+| Any, when a read answers another status, fails, or takes over 5 s | 503 `Admin SPA unavailable`, nothing rendered (fails closed) | 503 |
 
-If no bundle exists at `distDir/index.html`, the plugin logs a warning suggesting `bun run --filter '@terreno/admin-spa' build:web` or `devProxyTarget`.
+- `returnTo` passes through `sanitizeReturnTo`: one leading `/`, no scheme, no backslash.
+- A path under `${basePath}/_expo/static`, `${basePath}/assets` or `${basePath}/app-config.json`
+  that is not a real file gets a 404. It never reaches the page renderer.
+- Requests other than `GET` and `HEAD` are not gated.
+
+## Loopback calls and rate limits
+
+The gate and the route loaders read API data over HTTP from `internalOrigin`, with the
+visitor's cookie. Those requests pass through the backend's rate limiter like any other, keyed
+by the visitor's user id, so they count against the visitor's own `api` bucket (600 per
+15 minutes by default).
+
+| Request | Loopback calls |
+| --- | --- |
+| Anonymous page or loader | 0 |
+| Signed-in page, gate | 3: `get-session`, `/auth/me`, `{adminApiBasePath}/config` |
+| Signed-in page, loader | By screen: 1 for a model list or detail; 2 for configuration or roles; 3 for the jobs dashboard; on the home page, one per readable model for `modelStats` plus up to 3 for the other widgets |
+| Signed-in page, total | 3 + the loader's calls: about 4 to 6 on most screens; on the home page it grows with the number of models |
+
+The browser's own requests after hydration come on top. If admins hit 429s, raise
+`rateLimit.limits.apiMax` on `TerrenoApp`.
 
 ## MCP OAuth consent route
 
@@ -156,10 +227,23 @@ If no bundle exists at `distDir/index.html`, the plugin logs a warning suggestin
 
 ## Mount path constraint
 
-The default web export is built with `experiments.baseUrl: "/console"`, so `basePath` must match. To mount elsewhere, rebuild with a matching base (e.g. `EXPO_BASE_URL=/admin-ui bun run build:web`) and set `basePath` accordingly. Mounting at `/` requires a root-base build and `basePath: "/"`.
+The bundle's mount path is baked in at build time from `experiments.baseUrl` in
+`admin-spa/app.json` (`/console`). `basePath` must equal it. `register()` reads the baked
+`baseUrl` from `dist/server/_expo/routes.json` and throws on a mismatch:
+
+```text
+Admin SPA basePath "/admin-ui" does not match the bundle's baseUrl "/console"
+```
+
+To mount elsewhere, set `experiments.baseUrl` in `admin-spa/app.json`, run `build:web`, and
+pass the same value as `basePath`. `EXPO_BASE_URL=/admin-ui bun run build:web` does not change
+the mount: Metro reads the base URL from the app config, not the shell. The published package
+ships only the `/console` export (`files` holds `src/dist/**` and `dist/**`, not `app.json` or
+`app/`), so another mount means building admin-spa from the Terreno source and pointing
+`distDir` at that export root. Mounting at the site root is not supported.
 
 ## Standalone SPA vs embedded admin-frontend
 
-Use **`@terreno/admin-spa`** when you want a complete admin UI served from the API process (same-origin Better Auth cookies, no separate static deploy). The backend image stays lean until you opt in by registering `AdminSpaServeApp`.
+Use **`@terreno/admin-spa`** when you want a complete admin UI served and server-rendered by the API process (same-origin Better Auth cookies, no separate static deploy). The backend image stays lean until you opt in by registering `AdminSpaServeApp`.
 
 Use **`@terreno/admin-frontend`** when admin screens live inside your main Expo app (e.g. `example-frontend/app/admin/*`). You bring your own routing, auth, and deploy; the package supplies reusable list/table/form components and hooks against `/admin` CRUD routes from `@terreno/admin-backend`.