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

package/src/docs/upgrades/58.0.0-beta.4.md

@@ -0,0 +1,509 @@
+# Upgrading to 58.0.0-beta.4
+
+**Action required:** Yes
+**Affected packages:** @terreno/rtk (removed), @terreno/syncdb, @terreno/ui, @terreno/admin-frontend, @terreno/admin-spa, @terreno/api, @terreno/ai, @terreno/feature-flags, @terreno/mcp, @terreno/cli, create-terreno-app
+
+## Summary
+
+First release of the Expo SDK 58 line. Upgrade the app to Expo 58 and React Native 0.88, rebuild native binaries, then bump every `@terreno/*` package to `58.0.0` together. This major also deletes `@terreno/rtk` and Redux: `@terreno/syncdb` is the only frontend data, request, and session layer. Run the `McpServiceToken` data migration before deploying 58 frontends. `@terreno/admin-spa` is now server-rendered, which changes its export layout and pins its mount path ([Server-render the admin SPA](#server-render-the-admin-spa)). Each removal has its own section below.
+
+Order of work:
+
+1. Upgrade Expo (next section) and rebuild native binaries.
+2. Backend: remove `modelRouter` `realtime`, then run the [MCP service token](#mcp-service-tokens-are-a-synced-collection) migration. GPT histories keep their ObjectId ids and need no migration ([GPT histories](#gpt-histories-are-a-synced-collection)).
+3. Frontend: [replace `@terreno/rtk` and Redux](#terrenortk-and-redux-are-removed) with `@terreno/syncdb`, then update [admin](#admin-no-longer-takes-an-rtk-api) and [ui navigators](#consent-and-announcement-navigators-take-a-client).
+
+## Upgrade Expo before Terreno
+
+| Package | Version |
+|---------|---------|
+| `expo` | `~58.0.14` |
+| `react-native` | `0.88.0` |
+| `react` / `react-dom` | `19.3.0` |
+| `@types/react` | `~19.3.0` |
+| `@sentry/react-native` | `~8.28.0` (major 7 → 8) |
+| `react-native-gesture-handler` | `~3.3.0` (major 2 → 3) |
+| `react-native-webview` | `14.0.1` (major 13 → 14) |
+
+Run `bunx expo install expo@^58.0.0 --fix` at the app root, rebuild dev clients and store binaries (the native fingerprint changes), then `bun run compile` / `bun run lint`.
+
+### Expo Router `initialRouteName`
+
+**What changed**
+
+Expo Router 58 no longer accepts `initialRouteName` as a `<Slot>` / `<Stack>` / `<Navigator>` prop. `SidebarNavigation` ignores it.
+
+**Migration**
+
+```tsx
+// Before
+<Slot initialRouteName="home" />
+
+// After — in the same _layout.tsx
+export const unstable_settings = {initialRouteName: "home"};
+<Slot />
+```
+
+### Custom `app/+html.tsx`
+
+Expo Router 58 renders static web pages by streaming. The bundle `<script>` tags,
+React Native Web styles, and route metadata now reach a custom `app/+html.tsx` through
+`useServerDocumentContext()`. A `+html.tsx` that does not render them exports pages with
+no JavaScript: the static HTML shows, but nothing hydrates or responds.
+
+```tsx
+import {ScrollViewStyleReset, useServerDocumentContext} from "expo-router/html";
+
+export default function Root({children}: {children: React.ReactNode}) {
+  const {bodyAttributes, bodyNodes, headNodes, htmlAttributes} = useServerDocumentContext();
+  return (
+    <html lang="en" {...htmlAttributes}>
+      <head>
+        <meta charSet="utf-8" />
+        <ScrollViewStyleReset />
+        {headNodes}
+      </head>
+      <body {...bodyAttributes}>
+        {children}
+        {bodyNodes}
+      </body>
+    </html>
+  );
+}
+```
+
+Apps without a custom `+html.tsx` need no change.
+
+### React Native 0.88 instance types
+
+**What changed**
+
+React Native 0.87+ ships generated types without `react-native-legacy-deep-imports`. Component names such as `View`, `Text`, `ScrollView`, and `TextInput` are no longer usable as ref types. `Box.scrollRef`, `TextField.inputRef`, and the `Text` `ref` now use the instance types.
+
+**Migration**
+
+```tsx
+// Before
+const ref = useRef<TextInput>(null);
+
+// After
+import type {TextInputInstance} from "react-native";
+const ref = useRef<TextInputInstance>(null);
+```
+
+Use `ViewInstance`, `TextInstance`, `ScrollViewInstance`, and `TextInputInstance`. `TextStyle` is `Readonly`; build style objects instead of mutating them. `TextInput.State.currentlyFocusedInput()` replaces `currentlyFocusedField()`.
+
+### `@terreno/ui` peer dependency
+
+`@terreno/ui` peers `react-native` `0.88.0`. Installing `@terreno/ui@58` next to Expo 57 is unsupported.
+
+### `@sentry/react-native` 8
+
+Expo 58 bundles `@sentry/react-native` `~8.28.0`. Follow Sentry's 7 → 8 migration guide for your app's `Sentry.init` options.
+
+## `Filter` and `FilterProps` are removed
+
+`@terreno/ui` removes the `Filter` and `FilterProps` aliases added as deprecations in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps`. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names. See [57.7.0](57.7.0.md).
+
+## Server-render the admin SPA
+
+`@terreno/admin-spa` now exports with `web.output: "server"`, and `AdminSpaServeApp` server-renders
+`/console` in your backend's Express process behind a login gate. Two changes break existing setups:
+
+- **Export layout.** `expo export` writes `dist/client` (static assets) and `dist/server` (the
+  server build). Copy the whole `dist` folder into your image and point `distDir` /
+  `ADMIN_SPA_DIST_DIR` at it.
+- **Mount path.** `basePath` must equal the base URL baked into the bundle (`/console` by default)
+  or `register()` throws. A different mount needs `experiments.baseUrl` in admin-spa's `app.json`
+  and a rebuild from source.
+
+Register `BetterAuthApp` before `AdminSpaServeApp`, never cache `/console/*` HTML or
+`/_expo/loaders/*` at a proxy or CDN, and route the site-root `/_expo/loaders/*` to the backend.
+Full steps: `docs/how-to/upgrade-admin-spa-ssr.md`.
+
+## HTTP rate limiting defaults on
+
+`TerrenoApp` now mounts the HTTP rate limiter when `rateLimit` is omitted: memory store, auth 20 / 15 min (login, signup, refresh, GitHub OAuth, Better Auth credential routes), api 600 / 15 min (everything else). `/health`, `/healthz`, `/openapi.json`, and `/swagger` are never limited. Over the limit returns 429 `rate-limit-exceeded` with `Retry-After`.
+
+Steps:
+
+1. **Cloud Run (or any load balancer): pass `trustProxy: 1`.** Without it every unauthenticated request keys by the front end's address, so the whole service shares one auth bucket (20 logins per 15 minutes for all users).
+
+   ```typescript
+   new TerrenoApp({userModel: User, rateLimit: {trustProxy: 1}});
+   ```
+
+2. **If you set `app.set("trust proxy", …)` before `build()`** (for example in `beforeJsonSetup`), move the value to `rateLimit.trustProxy`. The limiter sets Express `trust proxy` when it mounts and defaults it to `false`.
+3. **More than one replica:** the memory store is per process. Pass `store: "redis"` (`VALKEY_URL` / `REDIS_URL`) or `store: "mongo"` for one shared bucket.
+4. **To keep HTTP unlimited, pass `rateLimit: false`:**
+
+   ```typescript
+   new TerrenoApp({userModel: User, rateLimit: false});
+   ```
+
+5. **Tests:** each `build()` gets a fresh memory store. A suite that logs in more than 20 times or sends more than 600 requests against one app instance should pass `rateLimit: false` in its shared app helper.
+
+Apps that already pass `rateLimit: {…}` see no change. `@terreno/api` still does not read `RATE_LIMIT_ENABLED`; an app-owned toggle should now produce `false` to turn the limiter off. See [Rate limiting](../../../docs/how-to/rate-limiting.md).
+
+## Admin no longer takes an RTK `api`
+
+`@terreno/admin-frontend` stopped injecting endpoints into your RTK Query API. Every admin request — model CRUD (including ObjectId and API-only models), `/admin/config`, scripts, roles, configuration, documents, comms, jobs, organizations, consent, announcements, and AI observability — now goes through one native `fetch` client that `AdminProvider` binds to your auth. The `api` prop, `useAdminApi`, `AdminApi`, `EndpointBuilder`, and admin `injectEndpoints` are removed. String-`_id` models with `adminBroadcast` keep the windowed syncdb path from 57.
+
+Before:
+
+```tsx
+<AdminProvider api={terrenoApi} apiBase="/admin" apiOrigin={baseUrl} getAuthHeaders={getAdminAuthHeaders} routeBase="/admin">
+  <AdminShellLayout api={terrenoApi} apiBase="/admin" routeBase="/admin">
+    <Stack />
+  </AdminShellLayout>
+</AdminProvider>
+
+<AdminScreenRouter api={terrenoApi} apiBase="/admin" name={model} routeBase="/admin" />
+<AdminModelTable api={terrenoApi} baseUrl="/admin" modelName="User" />
+
+const {useListQuery} = useAdminApi(terrenoApi, "/admin/users", "User");
+const {config} = useAdminConfig(terrenoApi, "/admin");
+```
+
+After:
+
+```tsx
+<AdminProvider apiBase="/admin" apiOrigin={baseUrl} getAuthHeaders={getAdminAuthHeaders} routeBase="/admin">
+  <AdminShellLayout apiBase="/admin" routeBase="/admin">
+    <Stack />
+  </AdminShellLayout>
+</AdminProvider>
+
+<AdminScreenRouter apiBase="/admin" name={model} routeBase="/admin" />
+<AdminModelTable baseUrl="/admin" modelName="User" />
+
+const {useListQuery} = useAdminModelApi("/admin/users", "User");
+const {config} = useAdminConfig("/admin");
+```
+
+Same-origin cookie SPAs (like `@terreno/admin-spa`) pass `credentials="same-origin"` on `AdminProvider` and omit `apiOrigin` / `getAuthHeaders`. `getAdminAuthHeaders` is your host's `() => ({Authorization: "Bearer …"})` (example-frontend reads the Better Auth session token).
+
+Product screens that reuse admin components outside the admin tree (for example `DocumentStorageBrowser` or `ConsentHistory` on a user tab) must render inside an `AdminProvider` with the same binding. Without one, admin hooks fall back to an unauthenticated same-origin `fetch` and warn once in development.
+
+Checklist:
+
+- [ ] Remove `api={…}` from every `@terreno/admin-frontend` component and from custom admin widget props.
+- [ ] Drop the `api` first argument from `useAdminConfig`, `useAdminScripts`, `useAdminRoles`, `useConfigurationApi`, `useDocumentStorageApi`, `useConsentHistory`, `useOrganizationsApi`, `useCommsDashboardApi`, `useJobsDashboardApi`, and the `useAiObservability*Api` hooks. `useOrganizationsApi` also drops its unused `organizationId` argument.
+- [ ] Query `refetch()` now returns a Promise; wrap fire-and-forget calls as `void refetch()`.
+- [ ] Replace `useAdminApi(api, routePath, name)` with `useAdminModelApi(routePath, name)`. Hook names, `.unwrap()`, and response shapes are unchanged.
+- [ ] Make sure one `AdminProvider` wraps the admin tree with `credentials` (cookie) or `apiOrigin` + `getAuthHeaders` (Bearer).
+- [ ] Wrap any product-side reuse of admin components in `AdminProvider`.
+- [ ] Delete type-erased casts such as `terrenoApi as unknown as AdminScreenProps["api"]` and any admin-only RTK tag types.
+- [ ] Replace custom admin `injectEndpoints` with `useAdminRpc` + `useAdminRpcQuery` / `useAdminRpcMutation`.
+
+## New native modules (rebuild dev clients)
+
+Terreno 58 adds every native module the B2B features need in one release, so later features ship as JavaScript and OTA updates against the same binary. A dev client or store build made before 58 does not contain these modules. Apps that call them on an old binary crash or get `null` modules.
+
+| Package | Version | Config plugin |
+| --- | --- | --- |
+| `@stripe/stripe-react-native` | `0.81.0` | Yes: `merchantIdentifier`, `enableGooglePay` |
+| `react-native-purchases` | `10.12.2` | None |
+| `react-native-purchases-ui` | `10.12.2` | None (keep the same version as `react-native-purchases`) |
+| `expo-device` | `~58.0.5` | None |
+| `expo-crypto` | `~58.0.2` (unchanged pin) | None |
+| `expo-local-authentication` | `~58.0.2` | Yes: `faceIDPermission` |
+| `expo-system-ui` | `~58.0.6` | Applied automatically |
+| `expo-build-properties` | `~58.0.11` | Yes: Android Kotlin and `compileSdkVersion` pins |
+
+`react-native-otp-verify` is not in the baseline. It does not support the New Architecture, the only architecture React Native 0.88 runs. For one-time codes, use `TextInput` with `textContentType="oneTimeCode"` (iOS) and `autoComplete="sms-otp"` (Android), which need no native module.
+
+Checklist:
+
+1. Add the packages to the app with `bunx expo install @stripe/stripe-react-native react-native-purchases@10.12.2 react-native-purchases-ui@10.12.2 expo-device expo-crypto expo-local-authentication expo-system-ui expo-build-properties`. In the Terreno monorepo they are root catalog entries; reference them with `"catalog:"`.
+2. Add the config plugins to `app.json` (or `app.config.ts`). Replace the merchant id with your own Apple Pay merchant id; register it in the Apple Developer portal before the iOS build.
+
+   ```json
+   [
+     "expo-build-properties",
+     {"android": {"compileSdkVersion": 37, "kotlinVersion": "2.2.21"}}
+   ],
+   [
+     "@stripe/stripe-react-native",
+     {"enableGooglePay": true, "merchantIdentifier": "merchant.com.yourcompany.app"}
+   ],
+   [
+     "expo-local-authentication",
+     {"faceIDPermission": "Allow $(PRODUCT_NAME) to use Face ID to confirm it is you."}
+   ]
+   ```
+
+   React Native 0.88 already compiles against Android SDK 37. Stripe needs at least SDK 36 and Kotlin 2.x; the pins keep both explicit. Kotlin `2.2.21` matches the Stripe Android build default and Expo's KSP table.
+3. Rebuild every dev client and store binary (`eas build --profile development` for iOS and Android). Expo fingerprints change, so OTA updates from 57 binaries do not apply to 58 binaries.
+4. Open the demo's hidden **Native Modules** page (`/demo/Native%20Modules`) on the new dev client. Each native module must show **Linked**. Web shows **Native only**.
+
+What still works in Expo Go:
+
+| Flow | Expo Go |
+| --- | --- |
+| `expo-device`, `expo-crypto`, `expo-system-ui` | Works (bundled in Expo Go) |
+| `expo-local-authentication` | Works, except Face ID on iOS (Expo Go has no Face ID usage string); use a dev build |
+| `react-native-purchases` / `-ui` | Runs in RevenueCat Preview API mode: mock offerings and paywalls, no real purchases |
+| `@stripe/stripe-react-native` | Card flows work (Expo Go 58 bundles `0.81.0`). Apple Pay and Google Pay need a dev build, because the merchant id is set by the config plugin |
+| Web | Unchanged. Native-only calls need a `Platform.OS` guard |
+
+## Legacy RTK realtime is removed
+
+Terreno 58 deletes the RTK cache-patching realtime path. Collection live updates go through `@terreno/syncdb`: `sync` on `modelRouter` plus `sync:delta` events. `RealtimeApp` stays: it still hosts Socket.io, socket auth, change streams, and `sync:delta`. `SyncApp` and `admin.realtime` (`admin:model.changed` events) are unchanged. The rest of `@terreno/rtk`, including `useSocketConnection` and `useRealtimeDebug`, is removed too; see [`@terreno/rtk` and Redux are removed](#terrenortk-and-redux-are-removed).
+
+Removed from `@terreno/api`:
+
+- `modelRouter` option `realtime`. Passing it is now a TypeScript error.
+- The `sync` websocket event. The change stream emits only `sync:delta` for models registered with `sync`.
+- The `subscribe:model`, `subscribe:document`, and `subscribe:query` socket events (and their `unsubscribe:*` pairs, plus `query:subscribed`).
+- Types `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, and `QuerySubscription`.
+- Registry helpers `registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, and type `RealtimeRegistryEntry`.
+- Query store helpers `addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, and `clearQueryStore`.
+- Constants `MAX_MODEL_SUBSCRIPTIONS`, `MAX_DOCUMENT_SUBSCRIPTIONS`, and `MAX_QUERY_SUBSCRIPTIONS`.
+
+Removed from `@terreno/rtk`:
+
+- `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `useSyncConnection`, and type `RealtimeEvent`.
+
+To upgrade:
+
+1. Backend: delete `realtime: {...}` from every `modelRouter` config. For each collection that needs live updates, add `syncPlugin` + `isDeletedPlugin` to the schema and a `sync` config to the router (three-argument form), then register `SyncApp` next to `RealtimeApp`.
+2. Frontend: delete `setRealtimeSocket(socket)`, `useSyncConnection(...)`, and every `onCacheEntryAdded: realtimeList(...)` / `realtimeDocument(...)` override. Read and write synced collections with `useQuery` / `useMutate` from `@terreno/syncdb/react`.
+3. Tests: replace `clearRealtimeRegistry()` with `clearSyncRegistry()`, which clears the whole collection catalog.
+
+See [How to upgrade from @terreno/rtk to @terreno/syncdb](../../../docs/how-to/migrate-rtk-to-syncdb.md).
+
+## MCP service tokens are a synced collection
+
+`McpServiceToken` now has a String `_id` (UUID for new rows), `isDeletedPlugin`, and `syncPlugin`. With `mcpServiceTokens` enabled, `/mcp/service-tokens` is a `modelRouter` synced read-only to its owner (collection `mcp/service-tokens`, owner scope on `userId`). Sync snapshots and deltas never include `tokenHash`. `McpServiceToken.verify` and `/mcp` authentication are unchanged.
+
+| 57.x | 58.0.0 |
+|------|--------|
+| `POST /mcp/service-tokens` | `POST /mcp/service-tokens/create` (same body; same one-time `token` response) |
+| `DELETE /mcp/service-tokens/:id` | `POST /mcp/service-tokens/:id/revoke` (response is the token row without `tokenHash`) |
+| `GET /mcp/service-tokens` rows `{id, name, tokenPrefix, …}` with `null` dates | Standard `modelRouter` list rows (`_id`, `id`, unset dates omitted); or `useQuery("mcp/service-tokens")` |
+| `revokeForUser(user, ObjectId)` | `revokeForUser(user, string)` |
+
+`POST`, `PATCH`, and `DELETE` on the collection return `405`, and sync client writes are nacked `unauthorized`. Admin delete still revokes: a soft delete is stored as `revokedAt`, not a tombstone. `McpServiceToken.deleteMany` now throws once the collection is synced (use `McpServiceToken.collection.deleteMany` in tests).
+
+**Run the data migration before deploying 58.** Existing rows keep their ids as hex strings. Add this file to your `migrations/` directory, dry-run it, then apply it:
+
+```typescript
+// migrations/20261022120000-mcp-service-token-string-ids.ts
+import {mcpServiceTokenStringIdsMigration} from "@terreno/api";
+
+export const id = "20261022120000-mcp-service-token-string-ids";
+export const up = mcpServiceTokenStringIdsMigration.up;
+```
+
+The migration is idempotent and has no `down` (new rows use UUIDs). See [Connect an MCP client with a service token](../../../docs/how-to/connect-mcp-service-token.md).
+
+## GPT histories are a synced collection
+
+`GptHistory` now has `isDeletedPlugin` and `syncPlugin`, and keeps its ObjectId `_id` (no data migration). `/gpt/histories` is registered with `sync: {scope: {type: "owner", field: "userId"}}`, so `SyncApp` serves each user's histories as the collection `gpt/histories`. REST CRUD, `/gpt/prompt`, `/gpt/histories/:id/stream`, the `turn` and `pendingAsks` actions, ratings, and `/gpt/actions` are unchanged.
+
+| 57.x | 58.0.0 |
+|------|--------|
+| `useGetGptHistoriesQuery` + `updateQueryData` / `invalidateTags` | `useQuery("gpt/histories")` and `useMutate("gpt/histories")` from `@terreno/syncdb/react` |
+| `GptHistory.deleteMany(...)` / `updateMany(...)` in app code or tests | Write one history at a time by `_id`; tests use `GptHistory.collection.deleteMany({})` |
+
+If the app creates histories from the client with `useMutate("gpt/histories").create`, pass `idFormats: {"gpt/histories": "objectId"}` to `createSyncDb` so the client mints ObjectIds instead of UUIDs. See [@terreno/ai reference](../../../docs/reference/ai.md#gpthistory-ids).
+
+## `@terreno/rtk` and Redux are removed
+
+`@terreno/rtk` is not published for 58, and no Terreno package uses Redux. `@terreno/syncdb` takes over every job it did. The [upgrade guide](../../../docs/how-to/migrate-rtk-to-syncdb.md) walks through each step and maps **every** removed export to its replacement; this section is the summary.
+
+| `@terreno/rtk` 57.x | 58.0.0 |
+|---------------------|--------|
+| `emptySplitApi`, `getBaseQuery`, `@rtk-query/codegen-openapi` → `store/openApiSdk.ts` | `createApiClient` (`@terreno/syncdb/api`) + `ApiClientProvider`; `terreno-syncdb-codegen --api-out` → `store/apiSdk.ts` (same hook names) |
+| RTK Query hooks for collection CRUD | `useQuery` / `useMutate` (`@terreno/syncdb/react`) |
+| `api.injectEndpoints(...)` | Document the route in OpenAPI and regenerate, or `useApiQuery` / `useApiMutation` |
+| `createBetterAuthClient` | `createBetterAuthClient` (`@terreno/syncdb/auth`) |
+| `generateBetterAuthSlice` + `selectBetterAuth*` selectors | `SessionProvider` + `useSession()` (`@terreno/syncdb/auth`) |
+| `generateAuthSlice` (JWT) + `useSelectCurrentUserId` | `jwtAuthAdapter` + `useJwtAuth` + `useSession()` (`@terreno/syncdb/auth`) |
+| `getTokenExpirationTimes`, `shouldShowStillThereModal` | Same names (`@terreno/syncdb/auth`) |
+| `baseUrl`, `baseWebsocketsUrl`, `resolveBaseUrls` | Same names (`@terreno/syncdb/config`), plus `appHeaders()` |
+| `useSocketConnection` | The syncdb socket: `useSocketEvent` (`@terreno/syncdb/react`) / `syncDb.onSocketEvent` |
+| `useFeatureFlags(api, …)`, `useTerrenoFeatureFlags(api, …)` | `useFeatureFlags({client, socket, …})`, `useTerrenoFeatureFlags({client, socket, …})` (`@terreno/syncdb/flags`) |
+| `useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installTerrenoDevConsoleLogger`, `useMCPTools` | `useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger` (`@terreno/syncdb/app`); `useMCPTools({authProvider})` (`@terreno/syncdb/mcp`) |
+| `@terreno/rtk/buildNumber` | `@terreno/syncdb/buildNumber` |
+| Offline middleware, `useOfflineStatus`, `useServerStatus` | The syncdb outbox; `useSyncStatus()` |
+| `useCan`, `useSelectPermissions`, `createSessionApi`, `useTerrenoChat`, `generateTags`, `populateId`, `registerTerrenoDevStore` | Removed (no replacement needed; see the guide) |
+
+Steps:
+
+1. Remove the packages: `bun remove @terreno/rtk @reduxjs/toolkit react-redux redux-persist @rtk-query/codegen-openapi`. Add `@terreno/syncdb` and `bunx expo install expo-sqlite expo-secure-store @react-native-async-storage/async-storage expo-constants expo-network`; rebuild native clients. `@terreno/rtk` depended on `expo-constants` and `expo-network`, so apps got them transitively; `@terreno/syncdb` only lists them as optional peers, and `baseUrl` imports `expo-constants`. Keep or add these optional peers for the features you use: `better-auth`, `@better-auth/expo`, and `@better-auth/passkey` (`createBetterAuthClient`); `@openfeature/web-sdk` and `@openfeature/react-sdk` (flags); `@modelcontextprotocol/client` (`useMCPTools`).
+2. Create one `authProvider` (`betterAuthAdapter(bridgeBetterAuthReactClient(betterAuthClient))`, or `jwtAuthAdapter`) and pass it to both `createSyncDb` and `createApiClient`.
+3. Replace `<Provider store>` / `<PersistGate>` with `<SessionProvider>`, `<ApiClientProvider>`, and `<SyncDbProvider>`. Replace `useSelector` session reads with `useSession()`; move app-state slices to React context or `useStoredState`.
+4. Point `bun run sdk` at `terreno-syncdb-codegen --api-out ./store/apiSdk.ts`, regenerate, and change imports from `@/store/openApiSdk` / `@/store/sdk` to `@/store/apiSdk` (`useGetMeQuery` → `useGetAuthMeQuery`).
+5. Remove `useSocketConnection`; pass `socket: syncDb` to the flag hooks and use `useSocketEvent` for other server pushes. The app opens one socket.
+6. Verify: `rg -l "@terreno/rtk|@reduxjs/toolkit|react-redux|redux-persist|rtk-query" --glob '!**/node_modules/**' .` returns nothing; compile, lint, and test pass.
+
+The feature-flags `GET /evaluate` deprecation warning now points at `@terreno/syncdb/flags`.
+
+### Consent and announcement navigators take a `client`
+
+`@terreno/ui` no longer calls into an RTK Query API. `ConsentNavigator`, `AnnouncementNavigator`, and their hooks take a request `client` (`TerrenoRequestClient`; a syncdb `ApiClient` satisfies it).
+
+| 57.x | 58.0.0 |
+|------|--------|
+| `<ConsentNavigator api={terrenoApi}>` | `<ConsentNavigator client={apiClient}>` |
+| `<AnnouncementNavigator api={terrenoApi} …>` | `<AnnouncementNavigator client={apiClient} …>` |
+| `useConsentForms(api, baseUrl)`, `useSubmitConsent(api, baseUrl)` | `useConsentForms(client, baseUrl)`, `useSubmitConsent(client, baseUrl)` |
+| `useAnnouncements(api, …)`, `useAcknowledgeAnnouncement(api, …)` | `useAnnouncements(client, …)`, `useAcknowledgeAnnouncement(client, …)` |
+
+See [@terreno/ui reference](../../../docs/reference/ui.md).
+
+### Scaffolds, MCP tools, and the CLI
+
+`create-terreno-app` and the `terreno_bootstrap` prompt now scaffold a frontend with no Redux and no `@terreno/rtk`: `lib/betterAuth.ts` (`createBetterAuthClient` from `@terreno/syncdb/auth`), `store/syncdb.ts` (shared `authProvider` + `syncDb`), `store/apiClient.ts` (`createApiClient` from `@terreno/syncdb/api`), and `store/apiSdk.ts` (generated hooks). `app/_layout.tsx` mounts `ApiClientProvider` and `SessionProvider`.
+
+| 57.x | 58.0.0 |
+|------|--------|
+| `bun run sdk` → `scripts/generate-sdk.ts` + `openapi-config.ts` (`@rtk-query/codegen-openapi`) → `store/openApiSdk.ts` | `bun run sdk` → `api-sdk` script: `terreno-syncdb-codegen --schema <openapi.json> --api-out ./store/apiSdk.ts` |
+| `store/index.ts`, `store/appState.ts`, `store/errors.ts`, `store/sdk.ts`, `store/betterAuthApi.ts`, `tsconfig.codegen.json` | Deleted. Session: `useSession()`; request errors: `createApiClient({onError})` |
+| `useGetMeQuery` / `usePatchMeMutation` from `@/store/sdk` | `useGetAuthMeQuery` / `usePatchAuthMeMutation` from `@/store/apiSdk` |
+| `getAdminAuthHeaders` from `@/store/betterAuthApi` | `getAdminAuthHeaders` from `@/store/apiClient` (reads `authProvider.getToken()`) |
+| MCP `get_rtk_state` (terreno-mcp-local) | `get_syncdb_state`, `syncdb_snapshot`, `syncdb_action` |
+| `terreno state --slice rtk` | `terreno state` (reads `get_syncdb_state`; `--collection`, `--id`, `--limit`) |
+| `terreno generate sdk --config openapi-config.ts` | `terreno generate sdk --schema <openapi.json> --out store/apiSdk.ts` |
+| MCP resource `terreno://docs/rtk` | `terreno://docs/syncdb` |
+| `terreno_generate_screen` list/detail/form used `@/store/openApiSdk` hooks | Uses `useQuery` / `useEntity` / `useMutate` from `@terreno/syncdb/react` |
+
+## Better Auth 1.7 and native sign-in
+
+Terreno 58 pins `better-auth` and `@better-auth/expo` to `1.7.4` (the root catalog). `@better-auth/passkey` needs 1.7, and the 1.6 and 1.7 Expo plugins differ on native.
+
+### Pin Better Auth 1.7.4
+
+**What changed**
+
+`@terreno/syncdb` and `@terreno/api` type-check against Better Auth 1.7. Mixing 1.6 and 1.7 between `better-auth`, `@better-auth/expo`, and `@better-auth/passkey` fails to compile (client plugin types disagree) and breaks passkey sign-in at runtime. Better Auth 1.7 serves provider callbacks at `/callback/:id`; check that any redirect URI you registered with a provider still matches.
+
+**Migration**
+
+Set all three to the same version in the app (`"catalog:"` in the Terreno monorepo):
+
+```json
+{
+  "dependencies": {
+    "@better-auth/expo": "1.7.4",
+    "@better-auth/passkey": "1.7.4",
+    "better-auth": "1.7.4"
+  }
+}
+```
+
+### Native storage needs `getItemAsync` and `setItemAsync`
+
+**What changed**
+
+The 1.7 Expo client plugin reads and writes its session cookie through `storage.getItemAsync` / `storage.setItemAsync`. A storage object with only `getItem` / `setItem` makes every auth request on iOS and Android throw `undefined is not a function`. Web does not exercise this path, so web e2e passes while a device build is broken.
+
+`createBetterAuthClient` from `@terreno/syncdb/auth` supplies both methods through its `StorageAdapter`. Apps that build their own Better Auth client with `expoClient({storage})` must provide them too (`getItemAsync?: (key) => Promise<string | null>`, `setItemAsync?: (key, value) => Promise<void>`).
+
+### Native sign-out needs `nativeApps: true` on the server
+
+**What changed**
+
+Native requests carry `expo-origin` instead of `Origin`. Without the server-side Expo plugin, `POST /auth/sign-out` answers `403 Missing or null Origin` on iOS and Android, so the user can never sign out.
+
+**Migration**
+
+Set `nativeApps: true` in the Better Auth server config (`create-terreno-app` and `example-backend` already do):
+
+```typescript
+const config: BetterAuthConfig = {enabled: true, nativeApps: true, /* ... */};
+```
+
+### Logout waits for the server and keeps the session on failure
+
+`useSession().logout()` signs out of the server first, with the session held. While it runs, `useSession().isSigningOut` is `true` and `isLoading` is unchanged, so a navigator gated on `isLoading` keeps its screen. A sign-out that fails or times out (`signOutTimeoutMs`, default 10 seconds) first checks the session. If it is still live, the session and local data stay and `error` is `SIGN_OUT_FAILED_MESSAGE`; if it is gone, local state is cleared. Do not treat `logout()` as instant, and show `isSigningOut` on the sign-out button.
+
+### Keep `SyncDbProvider` mounted across sign-out
+
+Mounting `<SyncDbProvider>` only while `userId` is set unmounts every `useQuery` / `useMutate` consumer in the middle of logout, and screens that are still on screen throw. Mount it unconditionally and let `SessionProvider` (`syncDbs={[syncDb]}`) start and stop the client:
+
+```tsx
+// Before
+{userId ? <SyncDbProvider client={syncDb}>{stack}</SyncDbProvider> : stack}
+
+// After
+<SyncDbProvider client={syncDb}>{stack}</SyncDbProvider>
+```
+
+Also keep the navigator on screen while a refresh or sign-out runs with a user present: gate the loading screen on `isLoading && !userId`, not on `isLoading` alone.
+
+### Social login, passkeys, two-factor, and account security live in `@terreno/syncdb/auth`
+
+57.x apps that adopted the screens and hooks from `@terreno/rtk` change the import path. Names are unchanged.
+
+| 57.x (`@terreno/rtk`) | 58.0.0 (`@terreno/syncdb/auth`) |
+|-----------------------|---------------------------------|
+| `TerrenoLoginScreen`, `useLoginController` | Same |
+| `TerrenoAccountSecurityScreen`, `useAccountSecurity` | Same |
+| `useAuthMethods(authClient)` | Same |
+| `createRememberedAccountsStore`, `signInSocialWithHandoff`, `completeBetterAuthOAuthHandoff` | Same |
+| `createBetterAuthClient({features})` | Same; `features: {multiSession, passkey, twoFactor}` |
+| `selectBetterAuthIsSigningOut` | `useSession().isSigningOut` |
+
+`@terreno/syncdb` now has `@better-auth/passkey` and `@terreno/ui` as optional peers (the auth screens render `@terreno/ui`). Add `@terreno/ui` to apps that import `TerrenoLoginScreen` or `TerrenoAccountSecurityScreen`.
+
+### Provisional consent hooks take a `client`
+
+`useProvisionalConsent` and `ProvisionalConsentSigner` (`@terreno/ui`) take `client` (a `TerrenoRequestClient`) like the other consent hooks, not `api`.
+
+### `PATCH /auth/me` documents `currentPassword`
+
+The OpenAPI body of `PATCH /auth/me` now lists `currentPassword`. Regenerate `store/apiSdk.ts` (`bun run sdk`) so `usePatchAuthMeMutation` types it. The server still refuses a `password` field on that route; use the password-change flow.
+
+### Admin lists: `useAdminRpcQuery` `keepPreviousData`
+
+`useAdminRpcQuery` clears its data when the `url` changes, so a body is never shown under the wrong URL. Custom admin screens that page through a list pass `keepPreviousData: true` to keep the previous page visible while the next one loads; without it the list goes blank on every page.
+
+## Example app changes to copy
+
+`example-frontend` and `example-backend` are the reference app. Apply these to your own app; each maps to a section above.
+
+**Native build config** (needed for EAS and local dev client builds):
+
+| File | Change | Why |
+|------|--------|-----|
+| `app.json` | `"disableSPM": true` on the `@stripe/stripe-react-native` plugin | iOS `pod install` fails when Expo's precompiled modules turn Stripe's SPM dynamic framework into a static library. `useFrameworks: "dynamic"` does not fix it |
+| `eas.json` | On the Android `development` build profile: `"resourceClass": "large"` and `"gradleCommand": ":app:assembleDebug -PreactNativeArchitectures=arm64-v8a"` | The default Android worker kills the Gradle daemon (container out of memory); building one ABI also halves the native compile |
+| `package.json` | `"eas-build-post-install"` compiles workspace dependencies in dependency order, not `bun run compile` | A clean EAS checkout has no `dist/`. `--filter '*'` does not order dev and peer dependencies, so `@terreno/test` compiles before `@terreno/ui`. Outside the Terreno monorepo, publish the packages and this hook is not needed |
+| `package.json` | `@terreno/ui` is a dependency whenever you import `@terreno/syncdb/auth` screens | `syncdb` compiles against it |
+
+**Auth and session wiring:**
+
+| File | Change |
+|------|--------|
+| `lib/betterAuth.ts` | `createBetterAuthClient({features: {multiSession: true, passkey: true, twoFactor: true}})`; `createRememberedAccountsStore`; `getLoginCallbackURL` / `getSecurityCallbackURL` helpers; `brandedOAuthProviders()` driven by the server's `/terreno/methods` instead of `EXPO_PUBLIC_MOCK_OIDC_SIGN_IN` |
+| `app/_layout.tsx` | `SyncDbProvider` always mounted; loading screen only while `isAuthLoading && !userId`; a signed-in user may stay on `/login` (the login screen records the method and navigates itself); only `/signup` redirects signed-in users |
+| `app/login.tsx` | `TerrenoLoginScreen` with `rememberIdentity`, two-factor inline challenge, passkey sign-in, "Continue as" cards |
+| `app/settings/security.tsx` (new) | `TerrenoAccountSecurityScreen`: password, two-factor, passkeys, linked providers, device sessions |
+| `app/(tabs)/profile.tsx` | Changing the email asks for the current password (`currentPassword` on `PATCH /auth/me`); there is no "New Password" field, because `PATCH /auth/me` refuses `password`; the sign-out button shows `isSigningOut` |
+| `app/consent-sign/[userId].tsx` (new) | Provisional consent signing on a member's behalf, via `useProvisionalConsent({client, userId})` |
+| `utils/userSecurityAccess.ts` and the admin user and org member security screens | Admin recovery and per-member security views |
+| `store/apiSdk.ts`, `store/syncDbSdk.ts` | Regenerate: `bun run sdk && bun run sync-sdk` |
+
+**Backend (`example-backend`):** `betterAuthConfig.ts` turns on `nativeApps`, `multiSession`, `twoFactor`, and passkeys (passkeys stay off in production while `FRONTEND_URL` is a loopback URL; a browser only accepts a passkey on the `rpID` host or a subdomain of it). It also registers a mock OIDC provider only when `MOCK_OIDC_ISSUER` is set, never in production.
+
+**Phone layouts.** The web layouts these screens had do not fit a phone; the example fixes show what to check in your own screens:
+
+| Screen | Problem | Fix |
+|--------|---------|-----|
+| `app/(tabs)/ai.tsx` | The fixed chat-history sidebar left no room for the conversation on a phone | Show the sidebar at desktop width only (`isSupportedDesktopWidth`). Below it, add Chats and New chat buttons, a history sheet, and safe-area padding |
+| `components/SyncTodosScreen.tsx` | The header's Browse button squeezed the title into a one-character column | Stack the header: `direction="column" lgDirection="row"`. Use `lg`, not `md`: native breakpoints are sm 320 / md 375 / lg 600 / xl 1024, so every phone is at least `md` |
+
+**Verify a device build, not only web.** The native-only breakages in this section (async storage, `nativeApps`, `SyncDbProvider` unmount) pass web e2e. Run the dev client on iOS and Android, sign in, sign out, and sign back in as a second user before shipping.
+
+### Verification
+
+```bash
+rg -l "@terreno/rtk|@reduxjs/toolkit|react-redux|redux-persist|rtk-query" --glob '!**/node_modules/**' .   # nothing
+bun pm ls 2>/dev/null | rg "better-auth|@better-auth"   # all 1.7.4
+bun run compile && bun run lint && bun test
+```
+
+On a dev client: sign in, open Profile, tap Sign out (it shows progress, then lands on login with no error screen), and confirm `POST /auth/sign-out` returns 200.

package/src/docs/upgrades/58.0.0.md

@@ -5,7 +5,7 @@
 
 ## Summary
 
-First release of the Expo SDK 58 line. Upgrade the app to Expo 58 and React Native 0.88, rebuild native binaries, then bump every `@terreno/*` package to `58.0.0` together. This major also deletes `@terreno/rtk` and Redux: `@terreno/syncdb` is the only frontend data, request, and session layer. Run the `McpServiceToken` data migration before deploying 58 frontends. Each removal has its own section below.
+First release of the Expo SDK 58 line. Upgrade the app to Expo 58 and React Native 0.88, rebuild native binaries, then bump every `@terreno/*` package to `58.0.0` together. This major also deletes `@terreno/rtk` and Redux: `@terreno/syncdb` is the only frontend data, request, and session layer. Run the `McpServiceToken` data migration before deploying 58 frontends. `@terreno/admin-spa` is now server-rendered, which changes its export layout and pins its mount path ([Server-render the admin SPA](#server-render-the-admin-spa)). Each removal has its own section below.
 
 Order of work:
 
@@ -105,6 +105,22 @@ Expo 58 bundles `@sentry/react-native` `~8.28.0`. Follow Sentry's 7 → 8 migrat
 
 `@terreno/ui` removes the `Filter` and `FilterProps` aliases added as deprecations in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps`. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names. See [57.7.0](57.7.0.md).
 
+## Server-render the admin SPA
+
+`@terreno/admin-spa` now exports with `web.output: "server"`, and `AdminSpaServeApp` server-renders
+`/console` in your backend's Express process behind a login gate. Two changes break existing setups:
+
+- **Export layout.** `expo export` writes `dist/client` (static assets) and `dist/server` (the
+  server build). Copy the whole `dist` folder into your image and point `distDir` /
+  `ADMIN_SPA_DIST_DIR` at it.
+- **Mount path.** `basePath` must equal the base URL baked into the bundle (`/console` by default)
+  or `register()` throws. A different mount needs `experiments.baseUrl` in admin-spa's `app.json`
+  and a rebuild from source.
+
+Register `BetterAuthApp` before `AdminSpaServeApp`, never cache `/console/*` HTML or
+`/_expo/loaders/*` at a proxy or CDN, and route the site-root `/_expo/loaders/*` to the backend.
+Full steps: `docs/how-to/upgrade-admin-spa-ssr.md`.
+
 ## HTTP rate limiting defaults on
 
 `TerrenoApp` now mounts the HTTP rate limiter when `rateLimit` is omitted: memory store, auth 20 / 15 min (login, signup, refresh, GitHub OAuth, Better Auth credential routes), api 600 / 15 min (everything else). `/health`, `/healthz`, `/openapi.json`, and `/swagger` are never limited. Over the limit returns 429 `rate-limit-exceeded` with `Retry-After`.
@@ -309,7 +325,7 @@ If the app creates histories from the client with `useMutate("gpt/histories").cr
 | `baseUrl`, `baseWebsocketsUrl`, `resolveBaseUrls` | Same names (`@terreno/syncdb/config`), plus `appHeaders()` |
 | `useSocketConnection` | The syncdb socket: `useSocketEvent` (`@terreno/syncdb/react`) / `syncDb.onSocketEvent` |
 | `useFeatureFlags(api, …)`, `useTerrenoFeatureFlags(api, …)` | `useFeatureFlags({client, socket, …})`, `useTerrenoFeatureFlags({client, socket, …})` (`@terreno/syncdb/flags`) |
-| `useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installTerrenoDevConsoleLogger`, `useMCPTools` | `useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools({authProvider})` (`@terreno/syncdb/app`) |
+| `useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installTerrenoDevConsoleLogger`, `useMCPTools` | `useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger` (`@terreno/syncdb/app`); `useMCPTools({authProvider})` (`@terreno/syncdb/mcp`) |
 | `@terreno/rtk/buildNumber` | `@terreno/syncdb/buildNumber` |
 | Offline middleware, `useOfflineStatus`, `useServerStatus` | The syncdb outbox; `useSyncStatus()` |
 | `useCan`, `useSelectPermissions`, `createSessionApi`, `useTerrenoChat`, `generateTags`, `populateId`, `registerTerrenoDevStore` | Removed (no replacement needed; see the guide) |

package/src/docs/versioned/57.22.0/README.md

@@ -0,0 +1,84 @@
+# Terreno Documentation
+
+**Terreno is Django/Rails for TypeScript — with universal app support.**
+
+Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
+framework where the undifferentiated 80% of an app is already written. On the
+backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
+panel, authentication, and an AI service. On the frontend you get one universal
+app — a single React Native codebase that ships to iOS, Android, and web. It is
+built to be driven by AI coding agents from the first prompt to a production
+deploy.
+
+- Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
+  feature flags, and consent are already built, so your code is business logic.
+- Universal by default — one React Native codebase ships to iOS, Android, and
+  web. Not a web framework with a mobile bolt-on.
+- AI-native — agents are a first-class client of the framework, not an
+  afterthought.
+
+Canonical copy, language rules, and the Django/Rails comparison:
+[Positioning](explanation/positioning.md).
+
+## Structure
+
+- **[Tutorials](tutorials/)** — Learning-oriented, hands-on lessons
+- **[How-to guides](how-to/)** — Problem-oriented, practical steps
+- **[Reference](reference/)** — Technical reference for APIs and packages
+- **[Explanation](explanation/)** — Concepts and context
+- **[Implementation Plans](implementationPlans/)** — Forward-looking plans for major features
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [@terreno/api](reference/api.md) | REST API framework for Express/Mongoose (modelRouter, auth, OpenAPI) |
+| [@terreno/test](reference/test.md) | Shared Bun test helpers, MongoDB preload utilities, and HTTP fixtures |
+| [@terreno/ui](reference/ui.md) | React Native UI component library for iOS, Android, and web |
+| [@terreno/syncdb](reference/syncdb.md) | Local-first data layer with TinyBase, durable outbox, and delta sync |
+| [@terreno/ai](reference/ai.md) | Provider-agnostic AI service with streaming chat, request logging, and admin tools |
+| [@terreno/blocks](reference/blocks.md) | Shared contracts for agent-driven UI: ask schemas and whole-reply block documents |
+| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin for `@terreno/api` |
+| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens for `@terreno/api` backends |
+| [@terreno/admin-spa](reference/admin-spa.md) | Standalone admin SPA (Expo Router web) plus Express serve plugin |
+| [@terreno/api-health](reference/api-health.md) | Health check plugin for `@terreno/api` |
+| [@terreno/announcements](reference/announcements.md) | In-app product update announcements |
+| [@terreno/comms](reference/comms.md) | Pluggable communications providers |
+| [@terreno/feature-flags](reference/feature-flags.md) | Feature flags and A/B testing plugin for `@terreno/api` |
+| [@terreno/mcp](reference/mcp-server.md) | MCP server that gives coding agents Terreno docs, codegen tools, and prompts |
+| [@terreno/cli](reference/cli.md) | `terreno` CLI for docs, codegen, bootstrap, and OpenAPI REST |
+| [create-terreno-app](reference/create-terreno-app.md) | CLI to scaffold a deployable full-stack Terreno app (`bunx create-terreno-app`) |
+
+### Legacy
+
+| Package | Description |
+|---------|-------------|
+| [@terreno/rtk](reference/legacy/rtk.md) (deprecated for data sync) | OpenAPI SDK, Better Auth Redux, and feature flags for Terreno frontends |
+
+**Migrating from RTK?** See [How to migrate from @terreno/rtk to @terreno/syncdb](how-to/migrate-rtk-to-syncdb.md).
+
+## Testing
+
+- [E2E testing guide](testing/e2e.md) — the test tiers, smoke conventions, Playwright and
+  Maestro specs, and one page per package on how it is e2e-tested
+- [Regression suites](regression/README.md) — the manual cases a person walks before a release,
+  one file per area
+
+## User guide
+
+- [User guide](user-guide/README.md) — one page per example-app feature, in end-user words,
+  for chat agents answering "how do I…" questions
+
+## Quick links
+
+- [Getting started](tutorials/getting-started.md)
+- [Set up Terreno MCP](how-to/set-up-terreno-mcp.md)
+- [Debug with MCP](how-to/debug-with-mcp.md)
+- [Create a Terreno app](how-to/create-a-terreno-app.md)
+- [Positioning](explanation/positioning.md)
+- [How admin interfaces are shaped](explanation/admin-interface.md)
+- [Build admin screens](how-to/build-admin-screens.md)
+- [Local-first data](explanation/local-first-data.md)
+- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
+- [ROADMAP.md](../ROADMAP.md) — Public roadmap
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Setup, tests, and pull requests