@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/dist/docs/upgrades/58.0.0.md

@@ -1,6 +1,105 @@
-# 58.0.0 (stub)
+# Upgrading to 58.0.0
 
-This file is a placeholder until Terreno 58 is cut. When that release ships, expand this page into a full upgrade note.
+**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 `GptHistory` and `McpServiceToken` data migrations before deploying 58 frontends. 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) and [GPT history](#gpt-histories-are-a-synced-collection) migrations.
+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
 
@@ -8,6 +107,398 @@ This file is a placeholder until Terreno 58 is cut. When that release ships, exp
 
 ## HTTP rate limiting defaults on
 
-`TerrenoApp` will enable HTTP rate limiting by default (memory store unless you pass `store`). Apps that must stay unlimited must pass an explicit off once 58 defines that API.
+`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 a String `_id` (UUID for new rows), `isDeletedPlugin`, and `syncPlugin`. `/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 except that history ids are Strings. `/gpt/actions` no longer answers 400 `historyId is not valid` for a non-ObjectId id; an unknown id is 404. `AIDataset.historyId` is a String.
+
+| 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({})` |
+| `history._id` is an `ObjectId` | `history._id` is a `string`; drop `new ObjectId(historyId)` casts and `ObjectId.isValid` checks |
+
+**Run the data migration before deploying 58.** Existing histories keep their ids as hex strings, and `AIDataset.historyId` refs are rewritten to match. Add this file to your `migrations/` directory, dry-run it, then apply it:
+
+```typescript
+// migrations/20261022130000-gpt-history-string-ids.ts
+import {gptHistoryStringIdsMigration} from "@terreno/ai";
+
+export const id = "20261022130000-gpt-history-string-ids";
+export const up = gptHistoryStringIdsMigration.up;
+```
+
+The migration is idempotent and has no `down` (new rows use UUIDs). See [@terreno/ai reference](../../../docs/reference/ai.md#gpthistory-string-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`, `useMCPTools({authProvider})` (`@terreno/syncdb/app`) |
+| `@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`; rebuild native clients.
+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
+```
 
-Until 58: omit `rateLimit` to leave the limiter off. See [Rate limiting](../../../docs/how-to/rate-limiting.md).
+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/dist/docs/versioned/next/README.md

@@ -53,9 +53,9 @@ Canonical copy, language rules, and the Django/Rails comparison:
 
 | Package | Description |
 |---------|-------------|
-| [@terreno/rtk](reference/legacy/rtk.md) (deprecated for data sync) | OpenAPI SDK, Better Auth Redux, and feature flags for Terreno frontends |
+| [@terreno/rtk](reference/legacy/rtk.md) (removed in 58) | Replaced by `@terreno/syncdb` |
 
-**Migrating from RTK?** See [How to migrate from @terreno/rtk to @terreno/syncdb](how-to/migrate-rtk-to-syncdb.md).
+**Upgrading from RTK?** See [How to upgrade from @terreno/rtk to @terreno/syncdb (Terreno 58)](how-to/migrate-rtk-to-syncdb.md).
 
 ## Testing
 

package/dist/docs/versioned/next/approval-rubric.md

@@ -64,8 +64,8 @@ violation is an Architecture finding; cite the rule only when the diff breaks it
   element; Luxon for dates, never `Date` arithmetic or dayjs; React Native Web still
   works (no web-only or native-only APIs without a platform guard).
 - **Data layer**: synced collections use `@terreno/syncdb` (`useQuery`/`useMutate`); other
-  routes use the generated SDK hooks from `@terreno/rtk`; no direct `axios`/`fetch` in
-  app code; `openApiSdk.ts` is regenerated with `bun run sdk`, never hand-edited, and a
+  routes use the generated SDK hooks in `store/apiSdk.ts` (`@terreno/syncdb` request client);
+  no direct `axios`/`fetch` in app code; `apiSdk.ts` is regenerated with `bun run sdk`, never hand-edited, and a
   backend route change ships the regenerated SDK in the same PR.
 - **Cross-cutting style**: interfaces over types; maps over enums; `const` arrow
   functions; named exports; RORO (receive an object, return an object); early returns;

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

@@ -14,14 +14,15 @@ workflow (consent publish, comms message detail, password-on-create).
 
 | Host | When to use | Route prefix (`routeBase`) | API prefix (`apiBase`) | Fetch auth |
 | --- | --- | --- | --- | --- |
-| Embedded (`example-frontend/app/admin`) | Admin lives inside the product Expo app | `"/admin"` | `"/admin"` | `getAuthHeaders` → Bearer, plus `apiOrigin` = RTK `baseUrl` so RPC does not hit the Expo origin |
-| Standalone (`@terreno/admin-spa`) | Same-origin console served by `AdminSpaServeApp` | `""` (SPA root; mount is `/console`) | `"/admin"` | `credentials="same-origin"`; empty `getAuthHeaders`; omit `apiOrigin` |
+| Embedded (`example-frontend/app/admin`) | Admin lives inside the product Expo app | `"/admin"` | `"/admin"` | `getAuthHeaders` → Bearer, plus `apiOrigin` = `baseUrl` from `@terreno/syncdb/config` so admin requests do not hit the Expo origin |
+| Standalone (`@terreno/admin-spa`) | Same-origin console served by `AdminSpaServeApp` | `""` (SPA root; mount is `/console`) | `"/admin"` | `credentials="same-origin"`; omit `getAuthHeaders` and `apiOrigin` |
 
 `apiBase` is the HTTP path for `/config` and CRUD. `routeBase` is the Expo Router
 prefix the sidebar concatenates onto `/{model.name}` and `/{screen.name}`. Mixing
 them puts nav on the wrong URL. Embedded hosts must also set `apiOrigin` (the
-backend origin, e.g. `http://localhost:4000`) on `AdminProvider`. Native `fetch`
-RPC uses that origin to prefix `/admin/config` and `/rbac/roles`. Do not put the
+backend origin, e.g. `http://localhost:4000`) on `AdminProvider`. Every admin
+request (model CRUD and RPC) is a native `fetch` through that provider, which uses
+the origin to prefix `/admin/config`, `/admin/users`, and `/rbac/roles`. Do not put the
 origin in `apiBase` — that would rewrite in-app navigation.
 
 ## Screen kinds
@@ -75,7 +76,7 @@ admin `Stack`); otherwise its default light screen containers cover the canvas.
 | Field widgets | `admin.fieldOverrides.widget` + `widgets.fields` |
 | Expo files | `app/admin/_layout.tsx` (shell once) or per-route shell in admin-spa |
 | Dedicated extra segments (`/comms/:id`) | Explicit Expo files so `[model]/[id]` does not treat them as generic forms |
-| Data fetching | REST remains membership/search/sort/pagination. String `_id` models with `adminBroadcast` overlay TinyBase and write through syncdb when the host passes a window client + fetch auth. Framework RPC uses host-bound fetch; ObjectId/API-only CRUD keeps RTK compatibility in Terreno 57. |
+| Data fetching | REST remains membership/search/sort/pagination. String `_id` models with `adminBroadcast` overlay TinyBase and write through syncdb when the host passes a window client + fetch auth. Every admin request goes through the `AdminProvider` host-bound fetch client: ObjectId/API-only CRUD (`useAdminModelApi`) and framework RPC alike. Terreno 58 removed the RTK `api` prop and `useAdminApi`. |
 
 ## Related
 

package/dist/docs/versioned/next/explanation/admin-plugin-frontend.md

@@ -18,7 +18,7 @@ registry into `AdminProvider`; `@terreno/admin-frontend` only owns first-party T
 
 Opening the admin UI is a separate decision from what an operator may do inside it. The page
 gate is `admin:access` (`GET /admin/config` 403 without it). Host apps should hide admin
-navigation with the same check (`canOpenAdminPage` from `@terreno/rtk`).
+navigation with the same check (`canOpenAdminPage` from `@terreno/syncdb/app`).
 
 `AdminApp` then resolves authorization before returning `/admin/config`. The response only contains
 models and custom screens the caller may read, includes effective write capabilities, and exposes

package/dist/docs/versioned/next/explanation/ai-workflows.md

@@ -110,7 +110,7 @@ Each package has its own CI workflow that runs on pull requests and pushes:
 |----------|---------|-------|
 | `api-ci.yml` | @terreno/api | Unit tests, type checking, linting |
 | `ui-ci.yml` | @terreno/ui | Component tests, type checking, linting |
-| `rtk-ci.yml` | @terreno/rtk | Unit tests, type checking, linting |
+| `syncdb-ci.yml` | @terreno/syncdb | Unit tests, type checking, linting |
 | `mcp-server-ci.yml` | @terreno/mcp | Integration tests, type checking, linting |
 | `example-backend-ci.yml` | example-backend | Integration tests, type checking |
 | `example-frontend-ci.yml` | example-frontend | Build verification, type checking |
@@ -184,7 +184,7 @@ Ensures preview environments don't accumulate and waste resources.
 **Packages published:**
 - @terreno/api
 - @terreno/ui
-- @terreno/rtk
+- @terreno/syncdb
 - @terreno/mcp
 
 ## Workflow Philosophy
@@ -192,7 +192,9 @@ Ensures preview environments don't accumulate and waste resources.
 ### Single Source of Truth
 - **Documentation:** Code is truth, docs must reflect it
 - **Agent configuration:** `.rulesync/rules/`, `.rulesync/skills/`, and
-  `.rulesync/hooks.json` are truth; generated files derive from them
+  `.rulesync/hooks.json` are truth; generated files derive from them. Root `AGENTS.md`
+  and `CLAUDE.md` are generated from `.rulesync/rules/00-root.md` by `bun run rules`
+  (rulesync 17), so edit the rule, not the output
 - **Tests:** Implementation is truth, tests verify it
 
 ### Fail Fast