@terreno/mcp 57.21.0 → 58.0.0-beta.2

package/src/docs/versioned/next/how-to/add-organizations.md

@@ -173,7 +173,8 @@ exactly one administered organization may omit it; Terreno infers that org.
 Operators and superadmins must select an org.
 
 Frontend admin hosts use `OrgContextProvider` + `OrgSwitcher`.
-`useAdminApi` adds the selected organization header automatically.
+`useAdminModelApi` and the built-in admin screens add the selected organization
+header automatically.
 
 Disabled organizations are excluded from `/orgs/mine` and cannot be selected as
 tenant context. Operators re-enable them from the organization directory UI or

package/src/docs/versioned/next/how-to/admin-custom-home.md

@@ -25,8 +25,14 @@ Built-in IDs include `modelStats`, `modelsGrid`, `scriptRunner`, `versionConfig`
 For an app-specific widget, implement `AdminHomeWidgetProps` and register it:
 
 ```tsx
-<AdminProvider widgets={{home: {operationsSummary: OperationsSummary}}} api={api}>
-  <AdminHome api={api} />
+<AdminProvider
+  apiBase="/admin"
+  apiOrigin={baseUrl}
+  getAuthHeaders={getAdminAuthHeaders}
+  routeBase="/admin"
+  widgets={{home: {operationsSummary: OperationsSummary}}}
+>
+  <AdminHome />
 </AdminProvider>
 ```
 

package/src/docs/versioned/next/how-to/admin-custom-widget.md

@@ -33,7 +33,6 @@ const RichTextWidget: React.FC<AdminFieldWidgetProps> = ({
 
 ```tsx
 <AdminProvider
-  api={api}
   apiBase="/admin"
   routeBase="/admin"
   widgets={{fields: {"rich-text": RichTextWidget}}}

package/src/docs/versioned/next/how-to/agent-ui-asks.md

@@ -248,9 +248,9 @@ use uploads, or lower the per-file cap with `asks: {maxFileSizeBytes: 5_000_000}
    <GPTChat resolveAskFiles={resolveAskFiles} {...chatProps} />;
    ```
 
-   `postFilesUpload` is an RTK Query mutation in `example-frontend/store/sdk.ts` whose body is a
-   `FormData` with a `file` part; the base query sends it with the session token. The generated
-   SDK has no file endpoints, because `/files/*` exists only on a server with a bucket.
+   `usePostFilesUploadMutation` is a generated hook in `example-frontend/store/apiSdk.ts` whose
+   body is a `FormData` with a `file` part; the request client sends it with the session token.
+   `/files/*` exists only on a server with a bucket.
    `createAskFileUploader` (in `gptAsks.ts`) returns `undefined` on 404, the upload's `id` and
    `size` on success, and throws with the server's detail otherwise (such as 401 when the session
    has ended), so the ask stays open. See `example-frontend/app/(tabs)/ai.tsx`.
@@ -297,9 +297,9 @@ answer as two rows, and ratings are sent by message index.
 
 A turn can stream only `{done}`, for example when the server cancels a second ask because one is
 already pending. Reload the conversation with `GET /gpt/histories/:id` when a turn streamed nothing
-visible, or when `done.pendingAsk` names an ask the stream did not send. The `@terreno/rtk` base
-query returns the `data` of single-document responses, so an RTK query for that route resolves to
-the history itself, not `{data}` (see [emptyApi](../reference/legacy/rtk.md#emptyapi--emptysplitapi)).
+visible, or when `done.pendingAsk` names an ask the stream did not send. The `@terreno/syncdb/api`
+request client unwraps the `data` of single-document responses, so `apiClient.request` for that
+route resolves to the history itself, not `{data}` (see [API client](../reference/syncdb.md#api-client)).
 
 Refetch the history list after a turn that streams ask events or reloads the conversation. The
 example app reopens a conversation from the list's cached rows, which still hold the pending ask.

package/src/docs/versioned/next/how-to/build-admin-screens.md

@@ -25,7 +25,6 @@ Embedded app (`example-frontend`):
 const syncConflicts = useConflicts();
 
 <AdminProvider
-  api={api}
   apiBase="/admin"
   apiOrigin={baseUrl}
   getAuthHeaders={getAdminAuthHeaders}
@@ -35,7 +34,6 @@ const syncConflicts = useConflicts();
   widgets={{screens: {"sync-lab": SyncLabScreen}}}
 >
   <AdminShellLayout
-    api={api}
     apiBase="/admin"
     configurationPath="/admin/configuration"
     rolesPath="/roles"
@@ -53,8 +51,8 @@ store name and `windowCollections` set; do not mix admin rows into the owner/ten
 product store. Start that client after `canOpenAdminPage` succeeds, block the admin
 shell until `start()` resolves, and call `stop()` when the admin layout unmounts.
 
-Gate entry with `canOpenAdminPage` from `@terreno/rtk` (`admin:access`). Do not
-rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/rtk`
+Gate entry with `canOpenAdminPage` from `@terreno/syncdb/app` (`admin:access`). Do not
+rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/syncdb/config`
 and pass it as `apiOrigin` so admin RPC (`GET /admin/config`, `/rbac/roles`, …)
 hits the API instead of the Expo web origin.
 
@@ -123,11 +121,15 @@ for those paths. Otherwise `[model]/[id]` treats the id as a generic document.
 
 ## 5. Fetch data the admin way
 
+- Every admin request goes through the `AdminProvider` fetch client. Admin
+  components take no `api` prop.
 - String-`_id` collections configured with `adminBroadcast` use windowed syncdb
-  when the host passes `syncDb` plus fetch auth.
-- ObjectId model CRUD and API-only hosts keep `useAdminApi`.
-- Bulk patch remains server-side: native admin fetch for windowed hosts, RTK fallback otherwise.
-- Admin RPC uses the host-bound native fetch client. Do not add axios.
+  when the host passes `syncDb`.
+- ObjectId and API-only models use fetch CRUD. Custom screens call
+  `useAdminModelApi(routePath, modelName)` for list/read/create/update/delete.
+- Bulk patch stays server-side at `{routePath}/bulk-patch` for every model.
+- Custom admin RPC uses `useAdminRpc` + `useAdminRpcQuery` / `useAdminRpcMutation`.
+  Do not add axios or a second request client.
 
 ## 6. Sidebar and grouping
 

package/src/docs/versioned/next/how-to/build-for-web.md

@@ -26,7 +26,7 @@ bun expo export --platform web
 
 ### Alternative: `app.json` `extra.BASE_URL`
 
-`@terreno/rtk` resolves the API base from `expo-constants` `extra.BASE_URL` and `EXPO_PUBLIC_API_URL` (see `rtk/src/constants.ts` `resolveBaseUrls`). Priority in **production** builds:
+`@terreno/syncdb/config` resolves the API base from `expo-constants` `extra.BASE_URL` and `EXPO_PUBLIC_API_URL` (see `syncdb/src/config/resolveBaseUrls.ts`). Priority in **production** builds:
 
 1. `EXPO_PUBLIC_API_URL` environment variable (set before export)
 2. `extra.BASE_URL` in app config (when env var is unset)

package/src/docs/versioned/next/how-to/call-external-apis.md

@@ -10,7 +10,7 @@ How to talk to third-party HTTP APIs (payment processors, health integrations, m
 | Calling an external service through its own SDK (Twilio, Google APIs, Stripe) | `withApiErrorHandling` around the SDK calls — the SDK owns transport, you standardize failures |
 | Logging or classifying a caught error from any external call | `normalizeApiError` |
 | Surfacing an external failure to your API's consumers from a route handler | `withApiErrorHandling` with `rethrowAs: "apiError"` |
-| Making internal requests to your own `@terreno/api` backend | None of these — use `@terreno/rtk` on the frontend or direct function calls on the backend |
+| Making internal requests to your own `@terreno/api` backend | None of these — use the generated `store/apiSdk.ts` hooks (`@terreno/syncdb/api` request client) or syncdb collection hooks on the frontend, or direct function calls on the backend |
 
 **Rule of thumb:** any file that would otherwise contain `axios.create(...)` plus a token variable plus a `try/catch → axios.isAxiosError → log → throw` block should use these utilities instead.
 
@@ -92,7 +92,7 @@ Note the hook's output classification also feeds the client's retry decision —
 
 ## When not to use this
 
-- **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
+- **Your own backend's routes** — use syncdb collection hooks or the generated `store/apiSdk.ts` hooks (frontend) or call the function directly (backend).
 - **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
 - **Webhook notifiers** — `sendToSlack`/`sendToGoogleChat`/`sendToZoom` post to a fixed webhook. Slack channel creation, invites, and bot posts use `createSlackPrivateChannel`, `inviteSlackUsersToChannel`, and `postSlackMessage` with `SLACK_BOT_TOKEN`. See [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
 

package/src/docs/versioned/next/how-to/circleci.md

@@ -47,6 +47,13 @@ list pipelines on the slug above.
 | `.circleci/config.yml` | Setup workflow + `path-filtering` (this is the live config) |
 | `.circleci/continue-config.yml` | Real jobs/workflows gated by those params |
 
+## Bun version is pinned
+
+`install_bun_and_deps` pins Bun with `node/install-bun` `version`. Bun 1.4.4 reports
+lower line coverage than 1.4.2 for the same tests, which fails the 95% package
+coverage gates. Bump the pin together with the local toolchain and re-run
+`bun run test:coverage` in each package first.
+
 ## Bun install is uncached
 
 `install_bun_and_deps` runs `bun install --frozen-lockfile` with
@@ -87,8 +94,8 @@ The example-backend Docker job runs only when its image recipe changes
 (`Dockerfile`, `.dockerignore`, package manifests, or `bun.lock`). API/source
 changes are covered by preview CD builds and do not start a duplicate image job.
 
-UI, RTK, and admin-frontend changes do **not** start `example-backend-ci`.
-Those packages are covered by `ui-ci` / `rtk-ci` / `packages-ci` plus e2e and
+UI, syncdb, and admin-frontend changes do **not** start `example-backend-ci`.
+Those packages are covered by `ui-ci` / `syncdb-ci` / `packages-ci` plus e2e and
 admin-spa. `new-file-coverage` starts on package `src/` (and example app
 runtime paths including `example-frontend/components/`), not on every `*.ts`
 file in the repo (Playwright specs no longer compile the world). Package CI
@@ -169,13 +176,13 @@ non-PR branch builds.
 | Path (examples) | Parameter | PR job | `master` job |
 | --- | --- | --- | --- |
 | `demo/**`, `ui/**` | `run-deploy-demo` | `deploy-demo-preview` | `deploy-demo` |
-| `example-frontend/**`, `admin-frontend/**`, `rtk/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
+| `example-frontend/**`, `admin-frontend/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
 | `docs/**`, `website/**` | `run-deploy-docs` | `deploy-docs-preview` | `deploy-docs` |
 | `example-backend/**`, `api/**`, `comms/**`, `jobs/**`, `admin-spa/**`, `feature-flags/**`, `announcements/**`, plus every frontend path above | `run-cd-backend` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `terraform/**`, `infra/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `mcp-server/**`, `ui/**` | `run-cd-mcp` | _(none)_ | `gcp-cd-prod` (runs `mcp-server` `test:ci` first) |
 
-The backend image bundles the admin SPA (ui, rtk, admin-frontend, syncdb), so
+The backend image bundles the admin SPA (ui, admin-frontend, syncdb), so
 those paths redeploy the backend too. Every frontend PR preview therefore gets
 an isolated `pr-N` backend: `deploy-frontend-preview` always points
 `EXPO_PUBLIC_API_URL` at it (the prod backend rejects preview CORS) and waits
@@ -283,7 +290,7 @@ ambient OIDC token for GCP impersonation.
 Branch protection must require the CircleCI job names below. Remove disabled
 GitHub check names or pull requests will wait for checks that can no longer run.
 
-Dedicated package jobs (`api-ci`, `ai-ci`, `blocks-ci`, `rtk-ci`, `ui-ci`, `syncdb-ci`,
+Dedicated package jobs (`api-ci`, `ai-ci`, `blocks-ci`, `ui-ci`, `syncdb-ci`,
 `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run `bun run test:coverage`
 (`scripts/check-coverage.ts`, 95% functions and lines). Isolated `syncdb` tests
 are included by that script. Published packages without a dedicated workflow
@@ -305,7 +312,6 @@ the same commands through the parameterized `packages-ci` job, gated by
 | Admin frontend lint, compile, coverage | `packages-ci` (`admin-frontend`) |
 | Run all tests (AI CI) | `ai-ci` |
 | Lint, compile, and test blocks | `blocks-ci` |
-| RTK Lint and Build | `rtk-ci` |
 | Syncdb Lint, Build, and Tests | `syncdb-ci` |
 | UI Lint, Build, Types, and Tests + demo typecheck | `ui-ci` |
 | Demo Lint and TypeScript Check | `ui-demo-ci` (demo-only PRs) |

package/src/docs/versioned/next/how-to/configure-better-auth.md

@@ -4,7 +4,7 @@ Set up Better Auth as the **default** authentication provider for new Terreno ap
 
 ## Overview
 
-Better Auth is the recommended authentication system for new Terreno frontends. Register `BetterAuthApp` on the backend, set `AUTH_PROVIDER=better-auth`, and wire `createBetterAuthClient` + `generateBetterAuthSlice` on the client. Pair with `betterAuthAdapter` when using `@terreno/syncdb`.
+Better Auth is the recommended authentication system for new Terreno frontends. Register `BetterAuthApp` on the backend, set `AUTH_PROVIDER=better-auth`, and on the client create the client with `createBetterAuthClient` and wrap the app in `SessionProvider`, both from `@terreno/syncdb/auth`. Pass the same client to `betterAuthAdapter` for `createSyncDb` and the API client.
 
 JWT/Passport remains available for legacy deployments (`AUTH_PROVIDER=jwt`). Both can run in parallel during migration.
 
@@ -378,17 +378,22 @@ const userSchema = new mongoose.Schema(
 ### 1. Create Better Auth Client
 
 ``````typescript
-import {createBetterAuthClient} from "@terreno/rtk";
+// lib/betterAuth.ts
+import {createBetterAuthClient} from "@terreno/syncdb/auth";
+import {baseUrl} from "@terreno/syncdb/config";
 
 // `scheme` is the app's deep-link scheme (required).
 export const authClient = createBetterAuthClient({
-  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
-  scheme: "yourapp",
+  baseURL: baseUrl,
+  scheme: "yourapp", // app.json "scheme", for OAuth deep links
+  storagePrefix: "yourapp",
 });
 ``````
 
-On web the client authenticates with Better Auth's session cookie. When the web frontend and
-the API are on different sites, use [bearer mode](#frontend-and-api-on-different-sites).
+The client stores its session in `expo-secure-store` on native and AsyncStorage on web.
+Install them in the app with `bunx expo install expo-secure-store @react-native-async-storage/async-storage`.
+
+Install them in the app with `bunx expo install expo-secure-store @react-native-async-storage/async-storage`.
 
 A cookie-authenticated `POST`, `PUT`, `PATCH`, or `DELETE` to any Terreno route is
 authenticated only when its `Origin` (or, without one, its `Referer`) is in `trustedOrigins` or
@@ -406,7 +411,7 @@ the matching Better Auth client plugins and their typed methods:
 
 ``````typescript
 import {router} from "expo-router";
-import {createBetterAuthClient} from "@terreno/rtk";
+import {createBetterAuthClient} from "@terreno/syncdb/auth";
 
 export const authClient = createBetterAuthClient({
   baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
@@ -447,27 +452,54 @@ Notes:
 - **Server first.** A client feature only adds client methods. Turn the feature on in
   `BetterAuthConfig` too, or its calls answer 404.
 
-### 2. Add Session Redux Slice
+### 2. Provide the Session
+
+Wrap the app in `SessionProvider` and read the session with `useSession()`. No Redux store is
+needed.
+
+``````tsx
+// app/_layout.tsx
+import {SessionProvider, useSession} from "@terreno/syncdb/auth";
+import {authClient} from "@/lib/betterAuth";
+import {syncDb} from "@/store/syncdb";
+
+const RootLayout = (): React.ReactElement => (
+  <SessionProvider authClient={authClient} syncDbs={[syncDb]}>
+    <RootNavigator />
+  </SessionProvider>
+);
+
+const RootNavigator = (): React.ReactElement => {
+  const {userId, isLoading} = useSession();
+  if (isLoading) {
+    return <Spinner />;
+  }
+  return userId ? <AppTabs /> : <LoginScreen />;
+};
+``````
+
+The provider reads the session on start and follows Better Auth's session signal, so a
+sign-in or sign-out updates `useSession()` on its own. `logout()` from `useSession()` signs
+out of Better Auth, signs out each `syncDbs` client (create it with `wipeOnSignOut: true` to
+wipe local data), runs `onLogout`, and clears the session.
+
+After an email sign-in, call `refresh()` to resolve the user right away:
 
 ``````typescript
-import {generateBetterAuthSlice} from "@terreno/rtk";
-import {configureStore} from "@reduxjs/toolkit";
-import {authClient} from "./authClient";
-import {api} from "./sdk"; // the app's generated RTK Query API
-
-// Purge the SDK's cached responses on logout or user switch.
-const betterAuth = generateBetterAuthSlice({apisToReset: [api], authClient});
-
-export const store = configureStore({
-  reducer: {
-    betterAuth: betterAuth.reducer, // selectors read `state.betterAuth`
-    // ... other reducers
-  },
-  middleware: (getDefault) => getDefault().concat(...betterAuth.middleware),
-});
+const {refresh} = useSession();
 
-// Call after sign-in, sign-out, and at app startup to copy the session into Redux
-void betterAuth.syncSession(store.dispatch);
+const result = await authClient.signIn.email({email, password});
+if (!result.error) {
+  await refresh();
+}
+``````
+
+For `@terreno/syncdb`, build the auth provider from the same client:
+
+``````typescript
+import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb/auth";
+
+export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(authClient));
 ``````
 
 ### 3. Add Social Login UI
@@ -476,7 +508,7 @@ Use the SocialLoginButton component:
 
 ``````typescript
 import {SocialLoginButton, Box} from "@terreno/ui";
-import {authClient} from "@/store/authClient";
+import {authClient} from "@/lib/betterAuth";
 
 const LoginScreen = () => {
   return (
@@ -524,7 +556,7 @@ Better Auth's `lastLoginMethod`, which reads a backend cookie that a cross-site
 see.
 
 ``````typescript
-import {createRememberedAccountsStore, toLoginAccountOptions, useRememberedAccounts} from "@terreno/rtk";
+import {createRememberedAccountsStore, toLoginAccountOptions, useRememberedAccounts} from "@terreno/syncdb/auth";
 import {LoginScreen} from "@terreno/ui";
 
 // One store per app, at module scope.
@@ -606,7 +638,7 @@ only the sign-in methods the server enables, and it records each sign-in in the
 [remembered accounts](#4-remember-accounts-on-this-device) store.
 
 ``````typescript
-import {createRememberedAccountsStore, TerrenoLoginScreen} from "@terreno/rtk";
+import {createRememberedAccountsStore, TerrenoLoginScreen} from "@terreno/syncdb/auth";
 import {useLocalSearchParams, useRouter} from "expo-router";
 
 export const rememberedAccounts = createRememberedAccountsStore({rememberIdentity: false});
@@ -670,18 +702,19 @@ What it does:
   the screen has to see the returned session to record it, and it navigates on by itself. Pass
   `onStepChange` to catch the screen landing on its `login` step while your app already holds a
   session (the live-session check failed), and navigate away there; example-frontend's
-  `app/login.tsx` does both, and skips re-syncing Redux in `onSignedIn` when it already holds the
-  user.
-- **Signing out.** Dispatch `generateBetterAuthSlice`'s `logout()`. It keeps the session until
-  `authClient.signOut()` answers, then clears it, so the login screen never opens while the old
-  session is still live. Meanwhile `selectBetterAuthIsSigningOut` is true: show it on the
-  sign-out control. `logout()` leaves `isLoading` alone, so the screen stays put; if your
-  navigator shows a spinner on `selectBetterAuthIsLoading`, show it only while no user is
-  loaded (`isLoading && !userId`), or a session refresh would remount the navigator on its
-  first tab. A sign-out that cannot reach the server leaves a cookie or native session in place
-  and sets the slice's `error` (`SIGN_OUT_FAILED_MESSAGE`); show it. Stop anything that calls the
-  API with the session first: example-frontend's `logout` in `store/index.ts` stops syncdb,
-  then dispatches `logout()`, and its profile screen shows both.
+  `app/login.tsx` does both, and skips `refresh()` in `onSignedIn` when the session already holds
+  the user.
+- **Signing out.** Call `logout()` from `useSession()`. It keeps the session until
+  `authClient.signOut()` answers, then signs out each `syncDbs` client (wiping local data when
+  `wipeOnSignOut` is set) and clears the session, so the login screen never opens while the old
+  session is still live. Meanwhile `isSigningOut` is true: show it on the sign-out control.
+  `logout()` leaves `isLoading` alone, so the screen stays put; if your navigator shows a
+  spinner on `isLoading`, show it only while no user is loaded (`isLoading && !userId`), or a
+  session refresh would remount the navigator on its first tab. A sign-out that cannot reach the
+  server (or that the server refuses, or that outlasts `signOutTimeoutMs`, 10 seconds by default)
+  leaves a cookie or native session in place, wipes nothing, and sets `error` to
+  `SIGN_OUT_FAILED_MESSAGE`; show it. A bearer client that has dropped its token before the
+  request signs out locally. example-frontend's profile screen shows both states.
 - **Sign-up.** The sign-up link hides when the server's sign-up is closed (`signUp: false`).
 - **No email and password.** When the server has `emailPassword` off, the form, the Sign in
   button, and the forgot-password link are left out (`LoginScreen` with `fields={[]}`), and a
@@ -765,7 +798,7 @@ every card to the Better Auth client. Each card shows only when the server's
 [`/terreno/methods`](../reference/api.md#better-auth-authentication) turns its feature on.
 
 ``````typescript
-import {TerrenoAccountSecurityScreen} from "@terreno/rtk";
+import {TerrenoAccountSecurityScreen} from "@terreno/syncdb/auth";
 import {useLocalSearchParams} from "expo-router";
 
 const Security = (): React.ReactElement => {
@@ -869,10 +902,11 @@ Safari block it. The user signs in and is signed out on the next request.
 Use bearer mode in that case. Keep cookie mode when the frontend and API share a site.
 
 ``````typescript
-import {createBetterAuthClient} from "@terreno/rtk";
+import {createBetterAuthClient} from "@terreno/syncdb/auth";
+import {baseUrl} from "@terreno/syncdb/config";
 
 export const authClient = createBetterAuthClient({
-  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+  baseURL: baseUrl,
   scheme: "yourapp",
   webAuth: "bearer",
 });
@@ -904,14 +938,23 @@ Content-Security-Policy. `localStorage` is readable by any XSS on the frontend's
 outlives the tab, so a stolen or forgotten token stays usable after the person closes it.
 
 Read the stored token outside the client, without a network call, with
-`getBetterAuthBearerToken({storagePrefix?, bearerStorage?})`. Pass the same options the client
-was created with.
+`getBetterAuthBearerToken({storagePrefix?, bearerStorage?})` from `@terreno/syncdb/auth`. Pass
+the same options the client was created with. Pass it to `betterAuthAdapter` as
+`getBearerToken` so the shared `authProvider` reads the token locally instead of calling
+`get-session` on every request:
+
+``````typescript
+import {betterAuthAdapter, bridgeBetterAuthReactClient, getBetterAuthBearerToken} from "@terreno/syncdb/auth";
+
+export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(authClient), {
+  getBearerToken: () => getBetterAuthBearerToken({storagePrefix: "yourapp"}),
+});
+``````
 
 example-frontend shows the whole setup. `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true` turns on
 bearer mode in `lib/betterAuth.ts`. `store/syncdb.ts` passes the stored token to
-`betterAuthAdapter` as `getBearerToken`, and `store/index.ts` registers that adapter with
-`setTokenSource` before it creates the store, so RTK Query, the socket and MCP tools send the
-same token. `e2e/crossSiteBearer.spec.ts` signs in from `localhost:8082` to an API on
+`betterAuthAdapter` as `getBearerToken`, and that one `authProvider` feeds syncdb (and its
+socket), the request client, and MCP tools, so they all send the same token. `e2e/crossSiteBearer.spec.ts` signs in from `localhost:8082` to an API on
 `127.0.0.1:4000` with every `set-cookie` header stripped, then reloads.
 
 ### Server requirements
@@ -938,7 +981,7 @@ same token. `e2e/crossSiteBearer.spec.ts` signs in from `localhost:8082` to an A
 ### Social sign-in in bearer mode
 
 The server adds a single-use, three-minute token to the OAuth callback's redirect, in the URL
-fragment, and the web app exchanges it for the bearer. rtk binds each exchange to a random
+fragment, and the web app exchanges it for the bearer. syncdb binds each exchange to a random
 nonce the tab stored when it started the sign-in, so a token planted in a link is never sent.
 
 1. On the server, list the web app's origin and the one page that reads the token. The origin
@@ -965,7 +1008,7 @@ nonce the tab stored when it started the sign-in, so a token planted in a link i
    navigation, never with `fetch`, an `<img>`, or an `<iframe>`:
 
    ``````typescript
-   import {signInSocialWithHandoff} from "@terreno/rtk";
+   import {signInSocialWithHandoff} from "@terreno/syncdb/auth";
 
    <SocialLoginButton
      provider="google"
@@ -988,10 +1031,12 @@ nonce the tab stored when it started the sign-in, so a token planted in a link i
    before Sentry, analytics, or other third-party scripts start:
 
    ``````typescript
-   import {completeBetterAuthOAuthHandoff} from "@terreno/rtk";
+   import {completeBetterAuthOAuthHandoff} from "@terreno/syncdb/auth";
 
-   await completeBetterAuthOAuthHandoff({client: authClient});
-   await betterAuth.syncSession(store.dispatch);
+   const stored = await completeBetterAuthOAuthHandoff({client: authClient});
+   if (stored) {
+     await refresh(); // useSession().refresh(): SessionProvider read the session before the exchange
+   }
    initSentry();
    ``````
 
@@ -1005,7 +1050,10 @@ nonce the tab stored when it started the sign-in, so a token planted in a link i
 
 4. Show sign-in errors from the query. A failed start or callback comes back with
    `?error=provider_not_found`, `?error=sign_in_failed`, or one of Better Auth's own `error=`
-   codes. The function resolves `false` and leaves `error` in the URL.
+   codes. The function resolves `false` and leaves `error` in the URL. On better-auth 1.6 (the
+   version Terreno 58 pins), a generic OAuth provider's own error (such as `access_denied`)
+   goes to the API's `{basePath}/error` page instead of `errorCallbackURL`.
+   No token is issued either way.
 
 The return page must not redirect, on the server or in the browser, before the function has
 run. A browser carries the fragment through a redirect that has none of its own, so a redirect
@@ -1018,14 +1066,14 @@ the handoff only, so a token never goes to a page on the visitor's own machine,
 start when no other origin is left in `CORS_ORIGINS`. CORS and `trustedOrigins` keep them.
 `app/login.tsx` renders `TerrenoLoginScreen` with `callbackURL="/login"` in bearer mode, so its
 social buttons start with `signInSocialWithHandoff` and come back to the same screen, which finds
-the session and records the method. `app/_layout.tsx` syncs the session only after the exchange
+the session and records the method. `app/_layout.tsx` refreshes the session only after the exchange
 resolves, and leaves a signed-in user on `/login` so the screen can record the sign-in before it
 navigates on.
 
 In an Expo Router app, run the exchange from the entry file, not from a layout. Expo Router
 copies the URL, fragment included, as soon as it is imported, and writes that copy back into
 the address bar when it routes, which would put `ott` and `handoff` back. Importing
-`@terreno/rtk` imports Expo Router too (through `@terreno/ui`). example-frontend's `index.js`
+`@terreno/ui` imports Expo Router too. example-frontend's `index.js`
 first imports `lib/oauthHandoffUrl.ts`, which has no imports and hides `handoff` and `ott` from
 the URL, then `lib/oauthHandoff.ts`, which puts the URL back and calls
 `completeBetterAuthOAuthHandoff` in the same synchronous step, then `expo-router/entry`.
@@ -1049,12 +1097,12 @@ must refuse.
 A signed-in user links Google, GitHub, or a generic OAuth provider from the Security screen. In
 cookie mode `authClient.linkSocial` does this. In bearer mode it can't: its
 `POST /link-social` fetch comes from another site, so the OAuth state cookie it needs on the
-API's origin is never set. Use `linkSocialWithHandoff` from `@terreno/rtk` instead. It needs
+API's origin is never set. Use `linkSocialWithHandoff` from `@terreno/syncdb/auth` instead. It needs
 the same `oauthHandoff` server config as social sign-in, and account linking must be on
 (`accountLinking.mode` other than `never`).
 
 ``````typescript
-import {linkSocialWithHandoff} from "@terreno/rtk";
+import {linkSocialWithHandoff} from "@terreno/syncdb/auth";
 
 const {error} = await linkSocialWithHandoff({
   callbackURL: "/settings/security", // any page on a web origin; sent as an absolute URL
@@ -1125,7 +1173,7 @@ const sessionStorageOrDefault = (): Storage | undefined => {
 };
 
 export const authClient = createBetterAuthClient({
-  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+  baseURL: baseUrl,
   bearerStorage: sessionStorageOrDefault(),
   scheme: "yourapp",
   webAuth: "bearer",
@@ -1176,6 +1224,11 @@ Verify the callback URLs in your OAuth provider settings match your `BETTER_AUTH
 
 Check that `trustedOrigins` in your Better Auth config includes your app's deep link scheme (e.g., `"yourapp://"`).
 
+On native, if every request fails before it is sent after an app update, the stored cookie jar
+may hold an entry the Expo plugin cannot read. `createBetterAuthClient` drops such entries on
+read and logs `Discarded … unreadable Better Auth cookie entry`; sign in again to restore the
+session.
+
 ### Social login opens browser but doesn't redirect back
 
 Ensure your mobile app has the proper deep link configuration in `app.json`:
@@ -1220,5 +1273,6 @@ so new accounts cannot be created through the legacy `/auth/signup`.
 
 - [Authentication Architecture](../explanation/authentication.md)
 - [@terreno/api Reference](../reference/api.md#better-auth)
-- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md#better-auth-integration)
+- [@terreno/syncdb Reference: Auth](../reference/syncdb.md#auth)
+- [Upgrade from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md)
 - [Better Auth Documentation](https://better-auth.com/)

package/src/docs/versioned/next/how-to/connect-mcp-service-token.md

@@ -35,13 +35,13 @@ Cap is **10** active tokens per user. List rows show prefix (`mcp_` + eight hex
 Use a session or JWT. A service token cannot mint another token.
 
 ```bash
-curl -X POST "$API/mcp/service-tokens" \
+curl -X POST "$API/mcp/service-tokens/create" \
   -H "Authorization: Bearer $JWT" \
   -H "Content-Type: application/json" \
   -d '{"name":"Perplexity"}'
 ```
 
-Read `data.token` and `data.mcpUrl` from the JSON. List and revoke never return `token`. Do not log the secret.
+Read `data.token` and `data.mcpUrl` from the JSON. Only this create response carries `token`. List, read, revoke, and the synced `mcp/service-tokens` collection never return `token` or `tokenHash`. Do not log the secret.
 
 ## 4. Perplexity custom connector
 
@@ -104,11 +104,17 @@ The token acts as the owning user on **MCP only**. It cannot mint or list tokens
 
 ## 7. Revoke
 
-- **Owner:** Profile → MCP connections → **Revoke** on the row (`DELETE /mcp/service-tokens/:id`).
-- **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete the row.
+- **Owner:** Profile → MCP connections → **Revoke** on the row (`POST /mcp/service-tokens/:id/revoke`).
+- **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete or tombstone the row.
+
+The token list is a synced collection (`mcp/service-tokens`, owner-scoped), so a revoke from another device or the admin panel shows up on the owner's list as a `revokedAt` update.
 
 Revoked and expired keys fail `tools/call` immediately. Disabled user accounts are refused the same way as over HTTP.
 
+## Upgrading from 57.x
+
+58.0.0 gives `McpServiceToken` String ids. Before deploying, add the `mcp-service-token-string-ids` framework migration to your `migrations/` directory and apply it. Existing tokens keep working and keep their ids as hex strings. See [Run MongoDB migrations](run-mongodb-migrations.md#framework-migrations).
+
 A password reset, Better Auth password change, or "sign out everywhere" (`revoke-sessions` / `revoke-other-sessions`) bumps the user's `tokenEpoch` and ends every key minted before it. The keys show as revoked in the list; mint a new one for each client you still use.
 
 To put `/mcp` on the public internet behind a Cloudflare Tunnel, see [Expose an MCP server safely](expose-mcp-server-safely.md).

package/src/docs/versioned/next/how-to/create-a-terreno-app.md

@@ -58,7 +58,7 @@ cd .. && bunx create-terreno-app my-app --yes
 | Path | Purpose |
 | --- | --- |
 | `backend/` | Express/Mongoose API (`@terreno/api`, Better Auth, admin, sync) |
-| `frontend/` | Expo universal app (`@terreno/ui`, `@terreno/syncdb`, `@terreno/rtk`) |
+| `frontend/` | Expo universal app (`@terreno/ui`, `@terreno/syncdb`). No Redux: session from `@terreno/syncdb/auth`, requests through `store/apiClient.ts`, generated hooks in `store/apiSdk.ts` |
 | `Dockerfile` | Consumer backend image (`backend/` only — not the Terreno monorepo) |
 | `.dockerignore` | Excludes local env secrets, dependencies, and build output from the image context |
 | `backend/.env`, `frontend/.env` | Gitignored local-dev defaults (written on scaffold). `backend/.env` sets `NODE_ENV=development`, which turns on the dev-only `POST /__terreno/browser-logs` route |
@@ -69,6 +69,18 @@ cd .. && bunx create-terreno-app my-app --yes
 
 Generated `@terreno/*` dependencies pin to `^<create-terreno-app version>` at scaffold time.
 
+### Frontend data and session wiring
+
+| File | What it does |
+| --- | --- |
+| `frontend/lib/betterAuth.ts` | `createBetterAuthClient` from `@terreno/syncdb/auth`, pointed at `baseUrl` from `@terreno/syncdb/config` |
+| `frontend/store/syncdb.ts` | `authProvider` (Better Auth session token) and the `syncDb` client for synced collections |
+| `frontend/store/apiClient.ts` | `createApiClient` from `@terreno/syncdb/api` with the same `authProvider`, `App-Version` / `App-Platform` headers, and `getAdminAuthHeaders` for `AdminProvider` |
+| `frontend/store/apiSdk.ts` | Typed hooks for non-synced routes (`useGetAuthMeQuery`, `usePatchAuthMeMutation`, ...). The scaffold ships the `/auth/me` hooks; `bun run sdk` regenerates the file for every route |
+| `frontend/app/_layout.tsx` | `ApiClientProvider` + `SessionProvider` (`useSession()` gives `userId`, `isLoading`, `refresh`, `logout`) + `SyncDbProvider`; starts `syncDb` after login |
+
+`bun run sdk` runs the `api-sdk` script: `terreno-syncdb-codegen --schema $OPENAPI_URL --api-out ./store/apiSdk.ts` (default schema `http://localhost:4000/openapi.json`). Never edit `apiSdk.ts` by hand.
+
 ## 2. Install dependencies
 
 ```bash
@@ -122,7 +134,7 @@ Health check: `curl http://localhost:4000/health` → `"healthy":true`.
 Terminal 2 — web UI (port `8082`):
 
 ```bash
-(cd frontend && bun run sdk)   # after backend is up; regenerates OpenAPI hooks
+(cd frontend && bun run sdk)   # after backend is up; regenerates store/apiSdk.ts
 (cd frontend && bun run web)
 ```