@terreno/mcp 57.21.0 → 58.0.0-beta.1

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)
 ```
 

package/src/docs/versioned/next/how-to/debug-with-mcp.md

@@ -399,26 +399,21 @@ terreno logs --entries 100 --level error --sources backend,browser,metro,app
 
 ### Inspect client state
 
-Check authentication and non-synced RTK Query cache state:
+Client state lives in `@terreno/syncdb`: synced collections in the local store, and the session in
+`SessionProvider`. There is no Redux store to inspect (the `get_rtk_state` tool and
+`terreno state --slice` were removed with `@terreno/rtk` in Terreno 58). Use the SyncDB tools in
+the next step for data, and `read_logs` / `last_error` above for failed request-client calls.
 
-```json
-{"name":"get_client_state","arguments":{"slice":"rtk","query":"todos"}}
-```
-
-The tool reads `globalThis.__TERRENO_STORE__` registered by the app, using CDP when the MCP process
-cannot access the app heap directly. It also detects a SyncDB client created with `debug: true`, and
-its `layer` field reports what it found: `rtk`, `syncdb`, `syncdb+rtk` (both payloads returned), or
-`none` (with a setup hint). On web it returns `none`, as shown in step 5. `get_rtk_state` is a
-deprecated alias for one release. `slice: "auth"` prefers the Better Auth slice and falls back to
-legacy JWT auth; pass `betterAuth` to request that exact slice.
+CLI equivalent of `get_syncdb_state`:
 
 Sensitive fields whose names include `password`, `token`, `secret`, `authorization`, or `cookie` are
-returned as `[REDACTED]`; use this summary to inspect cache state, never to retrieve credentials.
+returned as `[REDACTED]` in MCP summaries; use them to inspect state, never to retrieve credentials.
+
 
 The CLI equivalent is:
 
 ```bash
-terreno state --slice rtk --query todos
+terreno state --collection todos
 ```
 
 ### Inspect and change SyncDB state

package/src/docs/versioned/next/how-to/expose-mcp-tools.md

@@ -71,10 +71,21 @@ import {getMCPTools} from "@terreno/ai";
 const tools = getMCPTools(req.user);
 ```
 
-`useMCPTools()` from `@terreno/rtk` uses the official MCP v2 client with automatic
-version negotiation. It no longer constructs JSON-RPC or parses SSE responses by
-hand; the SDK supplies the `2026-07-28` `_meta` envelope and required
-`Mcp-Method` / `Mcp-Name` routing headers.
+To list the signed-in user's tools in an app, use `useMCPTools` from
+`@terreno/syncdb/app` with the same auth provider you pass to `createSyncDb`:
+
+```typescript
+import {useMCPTools} from "@terreno/syncdb/app";
+import {authProvider} from "@/store/syncdb";
+
+const {tools, isLoading, error, refetch} = useMCPTools({authProvider});
+```
+
+The hook reads the token from `authProvider.getToken()` on every fetch, so Better Auth
+sessions work as well as JWT. It uses the official MCP v2 client with automatic version
+negotiation; the SDK supplies the `2026-07-28` `_meta` envelope and the required
+`Mcp-Method` / `Mcp-Name` routing headers. Install `@modelcontextprotocol/client` in the app (optional peer of
+`@terreno/syncdb`).
 
 ## Naming tools
 

package/src/docs/versioned/next/how-to/generate-the-client-sdk.md

@@ -0,0 +1,33 @@
+# Generate the client SDK
+
+Run this after any backend change to routes, models, permissions, or OpenAPI docs. The
+backend must serve `/openapi.json` (Terreno `TerrenoApp` / `setupServer` does).
+
+1. Start the backend: `bun run backend:dev` (port 4000).
+2. Generate both SDK files from the app's frontend package:
+
+```bash
+bunx terreno-syncdb-codegen \
+  --schema http://localhost:4000/openapi.json \
+  --out ./store/syncDbSdk.ts \
+  --api-out ./store/apiSdk.ts \
+  --config ./syncdb-codegen.json
+```
+
+3. Commit both generated files. Never edit them by hand.
+
+| File | Holds | Use for |
+|------|-------|---------|
+| `store/syncDbSdk.ts` | Collection hooks + `SYNC_COLLECTIONS` | Synced collections (`useTodos`, `useCreateTodo`) |
+| `store/apiSdk.ts` | Typed query/mutation hooks + request builders | Every other route (`useGetAuthMeQuery`, `usePostAuthForgotPasswordMutation`) |
+
+A route missing from `apiSdk.ts` is missing from the OpenAPI spec. Document it in the
+backend (modelRouter actions are documented automatically; hand-written routes use
+`createOpenApiBuilder`) and regenerate. To leave routes out, add `excludePaths` to
+`syncdb-codegen.json`:
+
+```json
+{"excludePaths": ["/admin/", "^/internal/"]}
+```
+
+Reference: [`@terreno/syncdb` codegen](../reference/syncdb.md#codegen).

package/src/docs/versioned/next/how-to/github-actions-ci.md

@@ -19,8 +19,8 @@ PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
 | Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted | Prebuilt archives unpacked under `/<version>/` |
 | JS minify | Off | On |
 | Local search index | Skipped | Built |
-| Generated API + component MDX | Restored from cache when `api`/`rtk`/`ui` hashes match | Same cache, then full generate on miss |
-| TypeDoc workspace `tsc` | Once per generate (api+rtk deps share a process) | Same |
+| Generated API + component MDX | Restored from cache when `api`/`ui` hashes match | Same cache, then full generate on miss |
+| TypeDoc workspace `tsc` | Once per generate | Same |
 | Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
 
 Do not rely on `/57.1.0/…` URLs in a PR deploy preview.

package/src/docs/versioned/next/how-to/in-app-notifications.md

@@ -73,7 +73,7 @@ does not skip later channels.
 
 ## 4. Sync collections on the client
 
-Regenerate syncdb hooks (not RTK CRUD) for `notifications` and `notification-preferences`:
+Regenerate syncdb collection hooks for `notifications` and `notification-preferences`:
 
 ```bash
 cd example-frontend