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

package/dist/docs/versioned/57.22.0/user-guide/account/profile.md

@@ -0,0 +1,43 @@
+---
+title: Update your profile
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I change my name?
+  - How do I change my email address?
+  - How do I change my password?
+  - How do I turn on dark mode?
+screens: [example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Update your profile
+
+## What it does
+
+The **Profile** tab shows your account details and lets you change your name, email,
+password, and how the app looks.
+
+## How to use it
+
+1. Open the **Profile** tab.
+2. Under **Account Details**, tap the edit control next to **Name**, **Email**, or
+   **New Password**.
+3. Enter the new value and tap **Save**. Tap **Cancel** to keep the old value.
+
+When you change **Email**, also enter your **Current password** in the field that appears.
+**Profile updated successfully!** confirms the change.
+
+To switch the app's colors, turn **Dark mode** on or off under **Appearance**.
+
+## Intended use
+
+Use **Profile** to keep your own account details current. Leave **New Password** blank to
+keep your current password. After changing your email, confirm the new address; see
+[Confirm your email address](verify-email.md).
+
+## Related
+
+- [Choose how you get notifications](notification-preferences.md)
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.22.0/user-guide/account/reset-password.md

@@ -0,0 +1,42 @@
+---
+title: Reset your password
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - I forgot my password. How do I reset it?
+  - How do I get a password reset email?
+  - My reset link says it is missing a token. What do I do?
+screens: [example-frontend/app/forgotPassword.tsx, example-frontend/app/resetPassword.tsx]
+added: user-guide-backfill
+---
+
+# Reset your password
+
+## What it does
+
+If you forget your password, the app emails you a link to choose a new one.
+
+## How to use it
+
+1. On **Welcome Back**, tap **Forgot password?**.
+2. On **Forgot password**, enter your **Email** and tap **Send reset link**.
+3. When **Check your email** appears, open the reset email and follow its link.
+4. On **Reset password**, enter a **New password** of at least six characters and tap
+   **Save new password**.
+5. When **Password updated** appears, tap **Back to login** and sign in with the new
+   password.
+
+## Intended use
+
+Use this when you cannot sign in because you forgot your password. The app shows the same
+**Check your email** message whether or not an account uses that address, so it never
+reveals who has an account. If the email does not arrive, check your spam folder. If the
+reset page says the link is missing a token, request a new email from **Forgot password**.
+
+To change a password you still know, use **New Password** on the **Profile** tab instead;
+see [Update your profile](profile.md).
+
+## Related
+
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.22.0/user-guide/account/sign-in.md

@@ -0,0 +1,41 @@
+---
+title: Sign in
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I sign in?
+  - How do I log in with Google, GitHub, or Apple?
+  - How do I log out?
+screens: [example-frontend/app/login.tsx, example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Sign in
+
+## What it does
+
+Signing in opens your account on this device so you can see your todos, chats, and files.
+
+## How to use it
+
+1. On **Welcome Back**, enter your **Email** and **Password**.
+2. Tap **Log In**.
+
+You land on **Todos**. To sign in with another account provider, tap
+**Continue with Google**, **Continue with GitHub**, or **Continue with Apple** and finish
+signing in with that provider.
+
+To sign out, open the **Profile** tab and tap **Logout** under **Session**.
+
+## Intended use
+
+Use the same method you signed up with. If you forgot your password, tap
+**Forgot password?** on **Welcome Back**; see [Reset your password](reset-password.md).
+If sign-in fails, the screen shows **Sign in failed. Please try again.**; check your
+email and password, then try again.
+
+## Related
+
+- [Create an account](sign-up.md)
+- [Reset your password](reset-password.md)

package/dist/docs/versioned/57.22.0/user-guide/account/sign-up.md

@@ -0,0 +1,40 @@
+---
+title: Create an account
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I create an account?
+  - How do I sign up?
+  - Can I sign up with Google, GitHub, or Apple?
+screens: [example-frontend/app/signup.tsx, example-frontend/app/login.tsx]
+added: user-guide-backfill
+---
+
+# Create an account
+
+## What it does
+
+Creating an account gives you your own todos, chats, files, and settings. You can sign up
+with an email address and password, or with a Google, GitHub, or Apple account.
+
+## How to use it
+
+1. On **Welcome Back**, tap **Need an account? Sign Up**.
+2. On **Create Account**, enter your **Name**, **Email**, and **Password**. The password
+   requirements under the field turn on as you meet them.
+3. Tap **Sign Up**.
+
+You land on **Todos**, signed in. To use another account provider instead, tap
+**Continue with Google**, **Continue with GitHub**, or **Continue with Apple** on
+**Create Account** and finish signing in with that provider.
+
+## Intended use
+
+Create one account per person. If you already have an account, tap
+**Already have an account? Log in** instead. After signing up, confirm your email address
+so you can recover the account later; see [Confirm your email address](verify-email.md).
+
+## Related
+
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.22.0/user-guide/account/verify-email.md

@@ -0,0 +1,37 @@
+---
+title: Confirm your email address
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I verify my email?
+  - How do I resend the verification email?
+  - Why does my profile say to verify my email?
+screens: [example-frontend/app/verifyEmail.tsx, example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Confirm your email address
+
+## What it does
+
+Confirming your email address proves the address is yours, so you can recover the account
+if you lose your password.
+
+## How to use it
+
+1. Open the verification email and follow its link.
+2. On the page that opens, tap **Confirm email**.
+
+To get a new verification email, open the **Profile** tab. Under the banner
+**Verify your email to keep this account recoverable.**, tap **Resend**.
+
+## Intended use
+
+Confirm the address once after you sign up, and again after you change your email. The
+banner on **Profile** disappears once the address is confirmed. If the page says the link
+is missing a token, send a new email from **Profile** and use the newest link.
+
+## Related
+
+- [Update your profile](profile.md)

package/dist/docs/versioned/57.22.0/user-guide/admin/manage-records.md

@@ -0,0 +1,44 @@
+---
+title: Browse and edit records in the admin panel
+area: admin
+audience: admin
+platforms: [web, ios, android]
+questions:
+  - How do I open the admin panel?
+  - How do I find a user or a todo as an admin?
+  - How do I create, edit, or delete a record?
+screens:
+  - "example-frontend/app/(tabs)/profile.tsx"
+  - "example-frontend/app/admin/index.tsx"
+  - "example-frontend/app/admin/[model]/index.tsx"
+  - "example-frontend/app/admin/[model]/[id].tsx"
+added: user-guide-backfill
+---
+
+# Browse and edit records in the admin panel
+
+## What it does
+
+The admin panel lets administrators view and change the app's records, such as
+**Users** and **Todos**, in tables with search, sorting, and paging.
+
+## How to use it
+
+1. Open the **Profile** tab and, under **Developer**, tap **Admin Panel**.
+2. In the side menu, choose a section such as **Users** or **Todos**.
+3. Search or sort the table to find a record, then tap its row to open it.
+4. Change fields and tap **Save**.
+
+To add a record, open a section and tap **Create**, fill in the fields, and tap
+**Create**. To remove one, use its delete action and confirm
+**Are you sure you want to delete this item?**. Tap **Refresh** to reload the table.
+
+## Intended use
+
+The admin panel is for administrators maintaining the app's data. It only appears for
+accounts with admin access. Changes apply right away and affect every user, and deleted
+records cannot be restored from the panel.
+
+## Related
+
+- [Set a user's password](set-user-password.md)

package/dist/docs/versioned/57.22.0/user-guide/admin/set-user-password.md

@@ -0,0 +1,37 @@
+---
+title: Set a user's password
+area: admin
+audience: admin
+platforms: [web, ios, android]
+questions:
+  - How do I reset a user's password as an admin?
+  - A user is locked out. How do I give them a new password?
+screens:
+  - "example-frontend/app/admin/[model]/[id].tsx"
+added: user-guide-backfill
+---
+
+# Set a user's password
+
+## What it does
+
+An administrator can give a user a new password directly, without an email.
+
+## How to use it
+
+1. Open the admin panel and choose **Users**.
+2. Tap the user's row.
+3. Under **Set Password**, enter the **New Password** and the same value in
+   **Confirm Password**.
+4. Tap **Set Password**. **Password updated** confirms the change.
+
+## Intended use
+
+Use this when a user cannot reset their own password by email. The new password must be at
+least eight characters and takes effect immediately. Share it with the user through a
+private channel and ask them to change it from their **Profile**. When the user can reach
+their email, point them to **Forgot password?** instead.
+
+## Related
+
+- [Browse and edit records in the admin panel](manage-records.md)

package/dist/docs/versioned/57.22.0/user-guide/ai/chat.md

@@ -0,0 +1,40 @@
+---
+title: Chat with the AI assistant
+area: ai
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I ask the AI a question?
+  - How do I start a new chat?
+  - How do I delete or rename a chat?
+  - Can I attach a file to a chat?
+  - How do I rate an answer?
+screens: [example-frontend/app/(tabs)/ai.tsx]
+added: user-guide-backfill
+---
+
+# Chat with the AI assistant
+
+## What it does
+
+The **AI** tab is a chat with an AI assistant. It keeps each conversation under **Chats**
+so you can come back to it later.
+
+## How to use it
+
+1. Open the **AI** tab.
+2. Type in **Type a message...** and tap **Send**. The answer appears as it is written.
+3. To start a fresh conversation, tap **New chat** (the plus button next to **Chats**).
+4. To return to an earlier conversation, tap it under **Chats**.
+
+To rename a chat, edit its title in the list and save it. To delete one, use its delete
+button in the list. To rate an answer, tap **Thumbs up** or **Thumbs down** under it, and
+tap **Copy message** to copy its text. When the attach button shows next to the message
+box, use it to add files to your message.
+
+## Intended use
+
+Use the assistant for questions, drafting, and working with your todos and files. When it
+needs a choice or confirmation from you, it shows a card in the chat; answer it to let the
+assistant continue. Answers can be wrong, so check anything important. Do not share
+passwords or other secrets in a chat.

package/dist/docs/versioned/57.22.0/user-guide/documents/files.md

@@ -0,0 +1,37 @@
+---
+title: Store and organize files
+area: documents
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I upload a file?
+  - How do I create a folder?
+  - How do I download or delete a file?
+  - Where can I see the consent forms I agreed to?
+screens: [example-frontend/app/(tabs)/documents.tsx]
+added: user-guide-backfill
+---
+
+# Store and organize files
+
+## What it does
+
+The **Documents** tab holds your files in folders. Its **Consents** section lists the
+consent forms you have agreed to.
+
+## How to use it
+
+1. Open the **Documents** tab. **Files** is selected at the top.
+2. To add a file, tap **Upload file** and choose it.
+3. To make a folder, tap **New folder**, enter a **Folder Name**, and tap **Create**.
+4. Tap a folder to open it.
+5. To remove a file, tap **Delete** on its row. On the web, tap **Download** on a file's
+   row to save a copy.
+
+To review the consent forms you signed, tap **Consents** at the top.
+
+## Intended use
+
+Use **Files** for your own documents. **Upload file** only shows when uploads are turned
+on for your account, and **Download** is available on the web. Deleting a file removes it
+for good.

package/dist/docs/versioned/57.22.0/user-guide/todos/manage-todos.md

@@ -0,0 +1,37 @@
+---
+title: Add, complete, rename, and delete todos
+area: todos
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I add a todo?
+  - How do I mark a todo as done?
+  - How do I rename a todo?
+  - How do I delete a todo?
+  - Do my todos work offline?
+screens: [example-frontend/app/(tabs)/index.tsx]
+added: user-guide-backfill
+---
+
+# Add, complete, rename, and delete todos
+
+## What it does
+
+**My Todos** keeps your personal list of things to do. Open todos appear under **To Do**,
+and finished ones move to **Completed**. A count under the title shows how many remain.
+
+## How to use it
+
+1. Open the **Todos** tab.
+2. Type in **New Todo** and tap **Add Todo**. The todo appears at the top of **To Do**.
+3. Tap the checkbox next to a todo to mark it done. Tap it again to move it back to
+   **To Do**.
+4. To rename a todo, tap its title or the edit button next to it, type the new title, and
+   press Enter or tap away from the field.
+5. To delete a todo, tap the trash button next to it.
+
+## Intended use
+
+Use todos for your own tasks; other people cannot see them. Changes show at once, even
+without a connection, and sync when the device is back online. A deleted todo cannot be
+restored.

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

@@ -17,7 +17,7 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [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 vs LangfuseApp, SOP loop
+- [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
@@ -36,6 +36,7 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [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

package/dist/docs/versioned/next/explanation/admin-interface.md

@@ -65,6 +65,9 @@ admin `Stack`); otherwise its default light screen containers cover the canvas.
 `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
 

package/dist/docs/versioned/next/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)