@terreno/mcp 57.16.2 → 57.18.0

package/src/docs/versioned/next/reference/environment-variables.md

@@ -47,7 +47,7 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
-| `BETTER_AUTH_SECRET` | `@terreno/api` | ✅ if Better Auth | — | Yes | server |
+| `BETTER_AUTH_SECRET` | `@terreno/api`, example-backend | ✅ if Better Auth | example-backend outside production: a published dev-only value. With `NODE_ENV=production`, example-backend refuses to start when it is unset or equals that value | Yes | server |
 | `BETTER_AUTH_URL` | `@terreno/api` | ✅ if Better Auth | — | No | server |
 | `GOOGLE_CLIENT_ID` | `@terreno/api` | ❌ | — | No | server |
 | `GOOGLE_CLIENT_SECRET` | `@terreno/api` | ❌ | — | Yes | server |
@@ -68,12 +68,16 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `APP_ENV` | example-backend | ❌ | `development` | No | server |
 | `BACKEND_URL` | scripts, deploy | ❌ | — | No | server |
 | `FRONTEND_URL` | example-backend CORS and `authOptions.publicAppUrl` | ❌ | `http://localhost:8082` | No | server |
+| `CORS_ORIGINS` | example-backend (`utils/betterAuthConfig.ts`) | ✅ for deployed web origins | localhost:8082 origins only | No | server |
+| `CROSS_DOMAIN_AUTH_COOKIES` | example-backend Better Auth config | ❌ | `false` | No | server |
 | `API_URL` | microservice split | ❌ | — | No | server |
 | `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
 | `TERRENO_BROWSER_LOGS` | `@terreno/api` dev log ingestion | ❌ | enabled only in development; loopback or authenticated requests only | No | server |
 | `ALLOW_MIGRATIONS` | `@terreno/api` `terreno-migrate` | ❌ | unset | No | server |
 | `MIGRATIONS_DIR` | example-backend Dockerfile / `resolveMigrationDir` | ❌ | `<cwd>/migrations` when `dir` is `$bunfs` | No | server |
 
+`CORS_ORIGINS` is comma-separated. An entry may contain `*` (for example `https://*.preview.example.com`); use it only on a domain you control, never on a shared namespace like `vercel.app`. For `corsOrigin`, `*` becomes a `RegExp` that matches letters, digits, and hyphens but never a dot. Better Auth `trustedOrigins` receives the raw pattern and applies its own, broader wildcard matching. Never use `corsOrigin: true` in production; see [Deploy to Vercel](../how-to/deploy-to-vercel.md#cors). Set `CROSS_DOMAIN_AUTH_COOKIES=true` when the web app and API are on different sites.
+
 ## Client / build-time
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -93,6 +97,7 @@ Configured in `expo.extra` and read via `expo-constants`:
 | `DEV_API_PORT` | `@terreno/rtk` | Override dev API port (mirrors `EXPO_PUBLIC_DEV_API_PORT`) |
 | `AUTH_DEBUG` | `@terreno/rtk` | `"true"` enables auth debug logs |
 | `WEBSOCKETS_DEBUG` | `@terreno/rtk` | `"true"` enables socket debug logs |
+| `SOCKET_TRANSPORTS` | example-frontend (`store/socketTransports.ts`) | Comma-separated Socket.IO transports passed to `useSocketConnection({transports})` and `createSyncDb({socketTransports})`. Unset keeps `polling,websocket`; the Vercel build sets `websocket` |
 | `APP_ENV` | `@terreno/rtk` | Logged at startup |
 
 Resolution order for API base URL (`rtk/src/constants.ts`):
@@ -101,6 +106,12 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 2. `extra.BASE_URL` (production only, when env unset)
 3. Dev fallbacks: `hostUri`, experience URL, `localhost`
 
+`EXPO_PUBLIC_API_URL` is inlined only into app source. Code under `node_modules`, including `@terreno/rtk`, does not see the inlined value in a production export and falls back to `extra.BASE_URL`, so set both for production web builds. `example-frontend/scripts/vercelBuild.ts` writes `extra.BASE_URL` from `EXPO_PUBLIC_API_URL` before `expo export`.
+
+### Per-environment values on hosting platforms
+
+Hosting platforms scope variables per environment. Vercel has **Production**, **Preview**, and **Development** scopes; set `EXPO_PUBLIC_API_URL` in each so each build points at its own backend. Because the value is inlined at build time, promoting a preview build to production keeps the preview backend URL. Rebuild for production instead. See [Deploy to Vercel](../how-to/deploy-to-vercel.md#configure-each-environment) and the [multi-environment checklist](../explanation/deployment-baseline.md#multi-environment-checklist).
+
 ## Development tooling
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -282,6 +293,7 @@ example-backend **test** setup only. They are not read by `@terreno/jobs`. Use
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
 | `OTEL_SERVICE_NAME` | OpenTelemetry (example-backend) | ❌ | `example-backend` | No | server |
+| `SEED_DEFAULTS` | example-backend boot | ❌ | — | No | server |
 | `PR_NUMBER` | PR preview deploy | ❌ | — | No | server |
 | `PR_SERVICE_URL` | PR preview deploy | ❌ | — | No | server |
 | `JOBS_RUNNER` | example-backend | ❌ | `mongo` | No | server |
@@ -297,6 +309,10 @@ example-backend **test** setup only. They are not read by `@terreno/jobs`. Use
 | `WIDGET_CLIENT_SECRET` | widgets | ❌ | — | Yes | server |
 | `API_KEY` | integrations | ❌ | — | Yes | server |
 
+`SEED_DEFAULTS=true` runs the example seed (default users, all with the published password
+`testpassword123`) when the server starts. A process with `NODE_ENV=production` logs a warning and
+skips it, so no deployed revision, PR previews included, holds those accounts.
+
 ## Testing & CI (tooling only)
 
 | Variable | Read by | Scope |
@@ -324,6 +340,7 @@ example-backend **test** setup only. They are not read by `@terreno/jobs`. Use
 
 - [Deployment baseline](../explanation/deployment-baseline.md)
 - [Build for web](../how-to/build-for-web.md)
+- [Deploy to Vercel](../how-to/deploy-to-vercel.md)
 - [Configure Better Auth](../how-to/configure-better-auth.md)
 - [Rate limiting](../how-to/rate-limiting.md)
 - [Durable background jobs](../how-to/background-jobs.md)

package/src/docs/versioned/next/reference/feature-flags.md

@@ -301,4 +301,4 @@ Segment names can be referenced in flag rules via the admin UI.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `FEATURE_FLAGS_DEBUG` | Set to `"false"` to disable evaluation debug logs | Enabled |
+| `FEATURE_FLAGS_DEBUG` | Set to `"true"` to write evaluation diagnostics at `debug` level: flag key, rule field, operator, and result. User attribute values are never logged | Disabled |

package/src/docs/versioned/next/reference/jobs.md

@@ -33,7 +33,7 @@ Peers: `mongoose ^8.0.0 || ^9.0.0`; optional `@google-cloud/tasks`, `@vercel/que
 | `basePath` | `"/jobs"` | Admin routes and execute route prefix |
 | `runner` | `MongoJobRunner` | Dispatch + optional poll loop |
 | `timezone` | `"UTC"` | Default IANA zone for schedules without `schedule.timezone` |
-| `lockTtlMs` | `900_000` (15 min) | Stale `lockedAt` reclaim threshold |
+| `lockTtlMs` | `900_000` (15 min) | Claim lease length; renewed every `lockTtlMs / 3` while the handler runs, reclaimable once stale |
 | `pollIntervalMs` | `1_000` | Mongo runner idle sleep between polls |
 | `accessControl` | — | Terreno RBAC; jobs admin needs `admin:access` **and** `admin:jobs` |
 | `redactPayload` | — | Admin payload projection hook (see below) |
@@ -90,8 +90,10 @@ singleton (tests).
 
 `@terreno/admin-backend` `defineAdminScriptJob` registers handler name `admin/script` with
 `retry.maxAttempts: 1`. Payload: `{scriptName, taskId, wetRun, args, createdByName?}`.
-The Scripts UI still polls `BackgroundTask` by `taskId`. Without `JobsApp`, script HTTP
-runs stay in-process.
+The Scripts UI still polls `BackgroundTask` by `taskId`. The handler runs the script only
+when it wins the task's `pending` -> `running` transition: a task that already started
+throws a 409 `APIError` (the job goes `dead`), and a task cancelled before it started is
+skipped. Without `JobsApp`, script HTTP runs stay in-process.
 
 ## JobRunner
 
@@ -116,13 +118,13 @@ Built-in ids: `mongo`, `gcp-cloud-tasks`, `vercel-queues`.
 | `payload` | — | Handler input |
 | `payloadRedacted` | `false` | Admin omission flag |
 | `runAt` | — | Earliest claim (indexed) |
-| `attemptCount` | `0` | Executions so far |
+| `attemptCount` | `0` | Failed or lost (lease-expired) attempts so far |
 | `attempts` | `[]` | `{at, error?, errorClass?}` |
 | `maxAttempts` | `5` | From definition at enqueue |
 | `backoffMs` | `1_000` | Retry base |
 | `maxBackoffMs` | `900_000` | Retry cap |
 | `lastError` | — | Latest failure message; `$unset` when the job completes |
-| `lockedAt` / `lockedBy` | — | Claim lease |
+| `lockedAt` / `lockedBy` | — | Claim lease; `lockedAt` is renewed while the handler runs |
 | `idempotencyKey` | — | Partial unique with `name` |
 | `scheduleId` | — | Parent schedule ref |
 | `retriedFromId` / `retriedById` | — | Admin retry linkage |
@@ -138,7 +140,7 @@ Indexes: `(name, idempotencyKey)` partial unique; `(status, runAt)`; `(scheduleI
 | `running` | Claimed; handler executing |
 | `scheduled` | Reserved in schema / in-flight filter |
 | `completed` | Success |
-| `dead` | Exhausted `maxAttempts` |
+| `dead` | Exhausted `maxAttempts` (handler failures and lease-expired reclaims both count) |
 | `failed` | No handler registered at run time |
 | `cancelled` | Admin cancel |
 

package/src/docs/versioned/next/reference/legacy/rtk.md

@@ -46,7 +46,7 @@ export const store = configureStore({
 **Returns:**
 - `authReducer` — Redux reducer for auth state
 - `authSlice` — Full Redux slice
-- `logout` — Action to clear tokens and reset state
+- `logout` — Action to clear tokens and reset state. A logout that ends a signed-in session also purges the API's RTK Query cache (`resetApiState`), so the next user never gets the previous user's cached responses
 - `setUserId` — Action to set current user ID
 - `tokenRefreshedSuccess` — Action signaling token refresh
 - `middleware` — Login/logout listener middleware array
@@ -88,46 +88,158 @@ const userId = selectCurrentUserId(state);
 For apps using Better Auth instead of JWT:
 
 ``````typescript
-import {createBetterAuthClient, generateBetterAuthSlice} from "@terreno/rtk";
 import {configureStore} from "@reduxjs/toolkit";
+import {createBetterAuthClient, generateBetterAuthSlice} from "@terreno/rtk";
+import {api} from "./sdk"; // the app's generated RTK Query API
 
-// Create Better Auth client
+// Create Better Auth client. `scheme` is the app's deep-link scheme (required).
 export const authClient = createBetterAuthClient({
   baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+  scheme: "myapp",
 });
 
-// Generate session Redux slice
-const {sessionReducer, sessionMiddleware} = generateBetterAuthSlice(authClient);
+// Generate the session Redux slice; list the APIs whose cache belongs to the signed-in user
+const betterAuth = generateBetterAuthSlice({apisToReset: [api], authClient});
 
 export const store = configureStore({
   reducer: {
-    session: sessionReducer,
+    betterAuth: betterAuth.reducer, // selectors read `state.betterAuth`
     // ... other reducers
   },
-  middleware: (getDefault) => getDefault().concat(sessionMiddleware),
+  middleware: (getDefault) => getDefault().concat(...betterAuth.middleware),
 });
+
+// Call after sign-in, sign-out, and at app startup to copy the session into Redux
+void betterAuth.syncSession(store.dispatch);
 ``````
 
 **Key exports:**
-- `createBetterAuthClient` — Factory for Better Auth client with Expo support
-- `generateBetterAuthSlice` — Redux slice for session state management
-- `BetterAuthSessionData` — TypeScript types for session/user data
-
-**Session State:**
+- `createBetterAuthClient({baseURL, scheme, storagePrefix?, webAuth?, bearerStorage?})` — Factory for Better Auth client with Expo support. `webAuth: "bearer"` authenticates the web client with a stored bearer token and no cookies, for a frontend and API on different sites ([how-to](../../how-to/configure-better-auth.md#frontend-and-api-on-different-sites))
+- `getBetterAuthBearerToken({storagePrefix?, bearerStorage?})` — Reads the token bearer mode stored, or `null`
+- `signInSocialWithHandoff({client, provider, callbackURL?, errorCallbackURL?})` — Starts a social or generic OAuth sign-in for a web bearer client: stores a random nonce in `sessionStorage` and navigates the page to the server's `{basePath}/oauth-handoff/start` with `handoff=<nonce>` on the callback URLs. Throws on native and in cookie mode ([how-to](../../how-to/configure-better-auth.md#social-sign-in-in-bearer-mode))
+- `completeBetterAuthOAuthHandoff({client}): Promise<boolean>` — On the return page, removes `#ott` and `handoff` from the URL first, then exchanges the token at `{basePath}/one-time-token/verify` only when `handoff` matches the stored nonce. Resolves `true` only when a bearer token was stored; never rejects. Await it at startup before session reads and Sentry
+- `generateBetterAuthSlice({authClient, apisToReset?, syncInterval?})` — Returns `{reducer, middleware, actions, slice, syncSession, authClient}`. Pass the app's RTK Query APIs (for example `apisToReset: [terrenoApi]`) so their caches are purged (`util.resetApiState()`) when a signed-in session logs out (`betterAuth/logout` or `auth/logout`), when `syncSession` finds the session gone, and when the session changes to another user. Without it, the next account on the same client can be served the previous account's cached responses
+- `selectBetterAuthIsAuthenticated`, `selectBetterAuthUserId`, `selectBetterAuthUser` — Selectors over `state.betterAuth`
+- `BetterAuthUser`, `BetterAuthState` — TypeScript types for session/user data
+
+**Session State (`state.betterAuth`):**
 ``````typescript
 {
-  session: BetterAuthSession | null;
+  isAuthenticated: boolean;
+  userId: string | null;
   user: BetterAuthUser | null;
   isLoading: boolean;
+  error: string | null;
+  lastSyncTimestamp: number | null;
 }
 ``````
 
 **Learn more:** [Configure Better Auth](../../how-to/configure-better-auth.md)
 
+### Token source
+
+rtk reads the request token from one registered **token source**, typed as syncdb's
+`AuthProvider` (`getToken`, `getUserId`, `onAuthChange`, optional `refresh`). A Better Auth
+app registers the same adapter it builds for syncdb, once at startup:
+
+``````typescript
+import {setTokenSource} from "@terreno/rtk";
+import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb";
+import {authClient} from "./betterAuth";
+
+export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(authClient));
+setTokenSource(authProvider); // before the first RTK Query request
+``````
+
+With `webAuth: "bearer"`, also pass the adapter `getBearerToken` so it reads the stored token
+without a `get-session` call ([syncdb adapter](../syncdb.md#createsyncdb-configuration)).
+
+**Exports:**
+- `setTokenSource(source | undefined)` — Registers the source. `undefined` restores the default.
+- `getTokenSource()` — The registered source, or `undefined` when none is registered.
+- `jwtTokenSource` — The legacy JWT source: `getToken` is `getAuthToken`, `refresh` runs
+  `refreshAuthToken` and resolves `true` on success, `getUserId` reads the stored JWT's `id`
+  (or `sub`) claim, and `onAuthChange` fires on JWT login, logout, and token refresh.
+- `isJwtTokenSource(source)` — `true` for `undefined` or `jwtTokenSource`.
+
+**Base query behavior (`emptySplitApi` / `staggeredBaseQuery`):**
+- **No source registered, or `jwtTokenSource`:** the JWT path below, unchanged. JWT apps need
+  no code change.
+- **Any other source:** sends `authorization: Bearer <token>` from `getToken()` on every
+  request, or no `authorization` header when the token is null. It never logs out because a
+  token is missing. On a 401 it calls `refresh()` once (shared by concurrent requests), re-reads
+  the token, and retries once; only a second 401 dispatches `auth/logout`. The public endpoints
+  `emailLogin`, `emailSignUp`, `getVersionCheck`, `getZoomSignature`, and `googleLogin` skip
+  the refresh and retry.
+
+The registry is module-global, like `baseUrl`: one app, one source. Apps that forked the base
+query to read the Better Auth session can point their SDK back at `emptySplitApi` once they
+register the source.
+
+**Other consumers.** The socket, chat, MCP, and offline APIs read the same source. Each takes a
+`tokenSource` option that overrides it for that one consumer. Without the option they use the
+registered source, else `jwtTokenSource`. Pass `useSocketConnection` a stable object, not a new
+one per render, or it re-subscribes to `onAuthChange`.
+
+| API | Option | How it uses the source |
+| --- | --- | --- |
+| `useSocketConnection` | `tokenSource`, used when `getAuthToken` is omitted | Reads `getToken()` on every connect and reconnect, refreshes once per auth failure, and reconnects when `onAuthChange` brings a new token. See [useSocketConnection](#usesocketconnection). |
+| `useTerrenoChat` | `tokenSource` | Reads `getToken()` per chat request. Sends no `Authorization` header when it returns null. |
+| `useMCPTools` | `tokenSource` | Reads `getToken()` before every MCP request, so a refreshed token needs no refetch. A fetch that starts with no token connects without auth. |
+| `createOfflineMiddleware` | `tokenSource` | With a non-JWT source, tags queued mutations with `getUserId()` and replays them with `getToken()`. See [Offline queue](#offline-queue). |
+
+#### Offline queue
+
+`createOfflineMiddleware({endpoints, api, tokenSource?})` queues the listed mutations while
+offline and replays them on reconnect.
+
+- **JWT source:** the queue reads `state.auth.userId` and the stored JWT, as before.
+- **Any other source** (for example syncdb's `betterAuthAdapter`): each queued mutation carries
+  `userId` from `getUserId()`. Replay runs only while that same user is signed in. It sends
+  `authorization: Bearer <token>` from `getToken()`, or no header when the token is null.
+- **Last user id:** `state.offline.lastUserId` holds the last id the source confirmed. It
+  refreshes on the first action, on rehydrate, on `onAuthChange`, and on reconnect, so a failed
+  session read while offline does not untag new mutations.
+- **Persist the `offline` slice** with redux-persist (do not blacklist it). Otherwise mutations
+  made after an app launches offline carry no user and are dropped on reconnect.
+- **Unconfirmed ids:** a rehydrated id is unconfirmed until a read in this process returns a
+  user. Mutations tagged with it carry `userIdConfirmed: false`. A later read keeps them only
+  when it names the same user and no `onAuthChange` or source swap happened since. Any auth
+  change drops them, even for the same user.
+- **Cost:** syncdb's `betterAuthAdapter` fires `onAuthChange` on the session's first successful
+  load. After an offline launch that happens when the network returns, so it drops
+  offline-launch writes the reconnect read has not confirmed yet.
+- **Residual risk:** the signed-in user changes while no running instance of the middleware sees
+  it (for example in another browser tab that shares the persisted slice), between an
+  unconfirmed write and the next launch's first read. Then that write can replay as a user who
+  did not make it.
+- **Sign-out:** `auth/logout`, `betterAuth/logout` (on a non-JWT source), or the source
+  reporting no user after `onAuthChange` clears the queue, conflicts, and `lastUserId`, and
+  discards in-flight enqueues and replays.
+- **No user on reconnect:** when the source has no user, or the user changes during a replay,
+  the rest of the queue stays for a later reconnect.
+- **Different user on reconnect:** a replay drops each mutation queued by a user other than the
+  one signed in.
+
+Offline-slice exports the middleware uses for the user tag (exported from the package root):
+
+- `setLastUserId(userId | undefined)` — Action that sets `state.offline.lastUserId`.
+- `resolveUnconfirmedMutations(userId)` — Action that keeps unconfirmed mutations tagged with
+  `userId`, marks them confirmed, and drops the other unconfirmed ones.
+- `dropUnconfirmedMutations()` — Action that drops every mutation whose user id is unconfirmed.
+- `selectLastUserId(state)` — The last user id the source confirmed, or `undefined` when unknown
+  or signed out.
+
 ## WebSocket Integration
 
 > **Deprecated (removed in Terreno 58):** `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, and `getRealtimeSocket` patch RTK Query caches from `sync` events. Use [`@terreno/syncdb`](../syncdb.md). `useSocketConnection` remains for feature flags and other sockets.
 
+A `realtimeList` query subscription (`subscribe:query`) may filter only on fields in the router's
+`queryFields`, the same as the REST list; the server ignores a subscription that names any other
+field. On RBAC routers with field views, each subscriber's create, update, or delete event is
+decided against the document as their field view masks it, so a hidden field never changes which
+event they receive.
+
 ### useSocketConnection
 
 React hook for managing Socket.io connections with automatic reconnection, token refresh, and user feedback.
@@ -135,10 +247,10 @@ React hook for managing Socket.io connections with automatic reconnection, token
 ``````typescript
 import {useSocketConnection} from "@terreno/rtk";
 
+// Reads the token source registered with setTokenSource (the JWT in storage by default).
 const {socket, isSocketConnected} = useSocketConnection({
   baseUrl: "wss://api.example.com",
   shouldConnect: !!userId,
-  getAuthToken: () => getAuthToken(),
   onConnect: () => console.info("WebSocket connected"),
   onDisconnect: () => console.warn("WebSocket disconnected"),
   onConnectError: (error) => console.error("Connection error:", error),
@@ -162,12 +274,17 @@ useEffect(() => {
 **Options:**
 - `baseUrl` (string, required) — WebSocket server URL
 - `shouldConnect` (boolean, required) — Whether to connect (typically `!!userId`)
-- `getAuthToken` (function, required) — Async function returning JWT token
+- `tokenSource` (`AuthProvider`) — Source for the handshake token. Defaults to the
+  [registered source](#token-source), else `jwtTokenSource`. Used only when `getAuthToken` is
+  omitted.
+- `getAuthToken` (function) — Legacy getter. When passed, the hook reads the token once per
+  connect, sends it as a static `auth` payload, and ignores `tokenSource`.
 - `onConnect` (function) — Callback on successful connection
 - `onDisconnect` (function) — Callback on disconnection
 - `onConnectError` (function) — Callback on connection error
 - `onReconnectFailed` (function) — Callback after all reconnection attempts fail
 - `captureEvent` (function) — Analytics event tracking (optional)
+- `transports` (string[]) — Socket.IO transports in order. Default `["polling", "websocket"]`. Pass `["websocket"]` for hosts without session affinity, such as Vercel Functions ([details](../../how-to/vercel-function-websockets.md))
 
 **Returns:**
 - `socket` (Socket | null) — Socket.io client instance
@@ -175,7 +292,7 @@ useEffect(() => {
 
 **Features:**
 - **Automatic reconnection:** 5 attempts with exponential backoff (1-5 seconds)
-- **Bearer token authentication:** Automatically includes JWT in `socket.auth`
+- **Bearer token authentication:** Sends `Bearer <token>` in `socket.auth`
 - **Token refresh integration:** Reconnects automatically when tokens are refreshed
 - **User feedback:** Toast notifications for disconnections (after 9+ seconds) and token errors
 - **Connection monitoring:** Periodic checks with automatic reconnection attempts
@@ -186,7 +303,18 @@ useEffect(() => {
 - **Reconnection:** Shows "You have been reconnected" (suppressed if reconnect within 10 seconds)
 - **Token error:** Shows "Error refreshing token. Please log out and log back in..." with persistent error state
 
-**Token Management:**
+**Token source behavior (no `getAuthToken`):**
+- The handshake reads `getToken()` on every connect and reconnect, including socket.io's own
+  reconnects.
+- On an auth `connect_error` (the server's `UnauthorizedError`), the hook calls `refresh()`
+  once and reconnects. A second auth failure before a successful connect stops reconnecting and
+  calls `onConnectError`. If the source has no `refresh`, or it fails, the hook stops at once.
+  A successful connect resets this.
+- While `shouldConnect` is true, an `onAuthChange` with a different token drops a live
+  connection and reconnects with the new token. With no token it disconnects. The same token
+  keeps the connection up.
+
+**JWT token management** (`getAuthToken` passed, or the JWT source):
 - Checks token expiration on disconnect and connection errors
 - Automatically refreshes tokens if expiring within 60 seconds
 - Attempts reconnection after successful token refresh
@@ -335,7 +463,7 @@ Base RTK Query API with authentication, retry logic, and automatic token refresh
 - **Query serialization:** Uses `qs.stringify()` for complex queries (`$in`, `$lt`, `$gte`)
 
 **Automatic Headers:**
-- `authorization: Bearer <token>`
+- `authorization: Bearer <token>` (from the registered [token source](#token-source); the JWT in storage by default)
 - `App-Version` (from Expo config)
 - `App-Platform` ("web" or "mobile")
 

package/src/docs/versioned/next/reference/lifecycle-plugin.md

@@ -68,6 +68,11 @@ fresh subagent with no parent conversation. If the repository root defines a `pr
 package script, Taste runs it as the authoritative local gate; otherwise it falls back
 to lint, typecheck, and locally affected tests in each affected package. Taste then
 pushes and watches product CI.
+Every stage that pushes follows `references/push-ownership.md`: it owns the PR until
+CI is green on every host and every review-bot comment is fixed, declined with a
+reply, or raised as a decision. After three fix rounds that leave the PR red, Taste
+stops pushing and escalates as `BLOCKED`; the final message starts with
+`BLOCKED — PR #<n> still red after <k> fix rounds`. No stage ends quietly on a red PR.
 Taste observes product CI on every discovered host (GitHub Actions, CircleCI,
 Buildkite, and similar), not only GitHub checks. A documented not-applicable host
 counts as skipped; an unexplained untriggered host prevents Brew `PASS`. Brew still

package/src/docs/versioned/next/reference/syncdb.md

@@ -91,6 +91,10 @@ todoSchema.plugin(syncPlugin);      // stamps per-stream _syncSeq on every write
 
 Apply plugins **before** the model compiles. Registration validates their presence.
 
+`_syncSeq` and `_syncPrevStream` are server-owned. modelRouter create and update (REST, MCP
+tools, and sync mutations) drop them from the client body, and a save that changes only these
+fields gets a freshly claimed seq instead of keeping the value it was given.
+
 ### modelRouter sync config
 
 Use the three-argument `modelRouter` form:
@@ -132,8 +136,16 @@ new TerrenoApp({userModel: User})
 - **`ensureSyncIndexes`** — `TerrenoApp.start()` binds the HTTP port first (or attaches to `httpServer` if the process already listened), then awaits index builds for snapshot queries and sync bookkeeping (`SyncMutation.mutationId` unique, `SyncCounter.stream` unique, etc.). Registration queues this work without contacting MongoDB, so models can load before the database connects. Hosts that build Express without `TerrenoApp.start()` should await `ensureSyncIndexes()` after connecting.
 
 Socket auth requires at least one configured authentication method. It enables legacy JWT
-validation when `tokenSecret` or `TOKEN_SECRET` is available. Better Auth can be used without
-a JWT secret:
+validation when `tokenSecret` or `TOKEN_SECRET` is available. When a `BetterAuthApp` is
+registered on the same `TerrenoApp`, `RealtimeApp` validates Better Auth sessions with its
+instance automatically, with or without a JWT secret. The handshake creates the app `User` on
+first contact and refuses disabled users. A `RealtimeApp` without its own `userModel` uses the
+`TerrenoApp`'s, for JWT and Better Auth sockets alike: socket authorization reads the user from
+the database instead of the token's claims, and the revalidation sweep disconnects users who
+were disabled or deleted. With a user model, the JWT handshake also refuses a token whose user
+is disabled or no longer exists, so a disconnected client cannot reconnect with the same token.
+Pass `betterAuth` only for a `RealtimeApp` mounted without
+`TerrenoApp`:
 
 ```typescript
 new RealtimeApp({betterAuth: {auth, userModel: User}})
@@ -162,6 +174,49 @@ bridge exposes the client's `$store.atoms.session` atom and degrades to the poll
 that atom is absent. Clients that already expose `getSession` plus a subscribable `useSession` can
 be passed to `betterAuthAdapter` directly.
 
+`betterAuthAdapter(client, options)` options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `getBearerToken` | `() => string \| null` | — | Reads a locally stored session token. When it returns a token, `getToken` uses it and skips `getSession()`. A null or empty result, or a throw, falls back to `getSession()`. `getUserId`, `onAuthChange` and `refresh` always read the session. |
+| `pollIntervalMs` | `number` | `5000` | Polling cadence when the client has no subscribable session |
+| `setIntervalFn` / `clearIntervalFn` | test hooks | global timers | Inject timers for deterministic tests |
+
+For a web app in Better Auth bearer mode (`createBetterAuthClient({webAuth: "bearer"})`), pass
+rtk's `getBetterAuthBearerToken` so every sync request reads the stored token without a
+`get-session` round trip. syncdb does not import rtk; the app wires the two together:
+
+```typescript
+import {getBetterAuthBearerToken} from "@terreno/rtk";
+import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb";
+
+const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(authClient), {
+  getBearerToken: () => getBetterAuthBearerToken({storagePrefix: "myapp"}),
+});
+```
+
+Pass the same `storagePrefix` and `bearerStorage` you gave `createBetterAuthClient`. The option
+is explicit: the adapter never detects bearer mode from the client.
+
+The adapter never throws on a failed session read (a rejected `getSession()`, or a `{error}`
+envelope other than a 401). `getToken` and `refresh` answer null and false. `getUserId` answers
+with the user id the server last confirmed, through a successful read or a session-atom
+emission, and null before the first confirmation. A read that fails while the device is offline
+is therefore never reported as a sign-out, which would clear the client's current user and make
+`mutate()` throw. A successful read with no session, or a 401 (from `getSession()` or the session
+atom), is a sign-out; a 401 emission also fires `onAuthChange`, deduped like any other
+signed-out emission.
+
+The last confirmed user id follows the newest answer, not the last one to arrive. A read counts
+from when it started; an emission that changes or clears the identity counts from when it
+arrived. A read that started before a sign-out or user switch and resolves after it still
+answers its own caller, but does not update the confirmed user id. Emissions that repeat the
+atom's cached session are not new answers: a refetch-start emission (`isRefetching: true`) is
+ignored, and the value a new subscriber receives on subscribing only fills the confirmed user id
+before anything else has confirmed one.
+
+`createSyncDb(options)` options:
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `name` | `string` | — (required) | Persisted database name |
@@ -172,6 +227,7 @@ be passed to `betterAuthAdapter` directly.
 | `authProvider` | `AuthProvider` | — (required) | `{getToken, getUserId, onAuthChange, refresh?}` |
 | `baseUrl` | `string` | — | Server origin; required unless both `transport` and `httpChannel` are injected |
 | `transport` | `SyncTransport` | socket transport from `baseUrl` | Override for tests or custom wiring |
+| `socketTransports` | `string[]` | `["polling", "websocket"]` | Socket.IO transports for the default socket transport. Use `["websocket"]` on hosts without session affinity, such as Vercel Functions ([details](../how-to/vercel-function-websockets.md)) |
 | `httpChannel` | `HttpChannel` | built from `baseUrl` | HTTP fallback channel override |
 | `persisterFactory` | `PersisterFactory` | platform default (IndexedDB web, expo-sqlite native) | Storage backend override |
 | `keyProvider` | `KeyProvider` | server-derived via `GET /sync/key` | Web encryption key provider |
@@ -616,7 +672,7 @@ is 2 requests (`GET /sync/streams` plus one batch) instead of 101.
 
 | Endpoint | Purpose |
 |----------|---------|
-| `GET /sync/snapshot?collection=&stream=&cursor=&limit=` | Bootstrap + catch-up for one stream (`limit` max 100) |
+| `GET /sync/snapshot?collection=&stream=&cursor=&limit=` | Bootstrap + catch-up for one stream (`limit` max 100). Soft-deleted documents, including pre-sync rows paged by `legacyCursor` (seq 0), arrive as tombstones with `data: null` |
 | `POST /sync/snapshot/batch` | Bootstrap + catch-up for many streams in one round trip. Body `{streams: [{stream, cursor?, legacyCursor?}], limit?}`, at most 500 streams, no repeats. `limit` (default 5,000, max 10,000) is the entity budget for the whole response, split evenly across the streams. Returns `{pages}`, one `GET /sync/snapshot`-shaped page per stream in request order. Any stream the caller may not read fails the whole request |
 | `GET /sync/streams` | Current stream membership for the user |
 | `GET /sync/entities` | Point lookup for entity repair and admin window hydrate. Admin-window callers (`admin:access` with RBAC, else `user.admin`) on `adminBroadcast` collections receive requested ids across product streams. When AdminApp registered a scope, list/read/`queryFilter` still apply; unknown or out-of-scope ids are omitted |
@@ -642,6 +698,12 @@ Conflict responses on mutate: **409** with `{nack}` body (`code: "conflict"`).
 
 Limits: 50 collection subscriptions per socket; 100 mutations/second per socket (each batch mutation counts); batches capped at 100.
 
+A redelivered `mutationId` returns the outcome recorded for it only to the same user and only
+for the collection it was first sent to; any other replay gets an `unauthorized` nack. A
+replayed `conflict` nack includes `serverDoc` only when the caller can still read the document
+now (read permission and stream membership, or the admin broadcast scope for an admin-window
+mutation); otherwise it carries `serverSeq` alone.
+
 ## Encryption at rest
 
 **Web:** AES-256-GCM encrypted IndexedDB by default via pluggable `KeyProvider`:

package/src/docs/versioned/next/reference/ui.md

@@ -97,7 +97,7 @@ const AppearanceSetting = () => {
 };
 ``````
 
-Dark `surface.warningLight` uses `warning200`. The lighter warning orange, `warning100`, is 2.52:1 against warning text and misses WCAG AA. Highlighted `DataTable` cells switch to `text.inverted` when `text.primary` is below 4.5:1 on that fill. Inverted `MarkdownView` code uses `surface.neutralDark` when `surface.neutralLight` is below 4.5:1 against that text, and blockquotes do the same with `surface.baseAlternate`. Primary `Button` labels use `text.secondaryDark` when that pair meets 4.5:1 on `surface.primary`, and `text.inverted` otherwise, so `setTheme(darkThemeConfig)` stays readable without changing `colorScheme`. The demo palette generator emits status `050` steps so custom palettes update those dark error, success, and warning surfaces.
+Dark `surface.warningLight` uses `warning200`. The lighter warning orange, `warning100`, is 2.52:1 against warning text and misses WCAG AA. Striped `DataTable` rows use `neutral900` in dark mode instead of `surface.neutralLight`, which is too light for ghost and link text. Highlighted `DataTable` cells switch to `text.inverted` when `text.primary` is below 4.5:1 on that fill. Inverted `MarkdownView` code uses `surface.neutralDark` when `surface.neutralLight` is below 4.5:1 against that text, and blockquotes do the same with `surface.baseAlternate`. Primary `Button` labels use `text.secondaryDark` when that pair meets 4.5:1 on `surface.primary`, and `text.inverted` otherwise, so `setTheme(darkThemeConfig)` stays readable without changing `colorScheme`. The demo palette generator emits status `050` steps so custom palettes update those dark error, success, and warning surfaces.
 
 `themeColorSchemeOptions` labels those values Light, Dark, and Follow system.
 `useTheme()` also returns the resolved `colorScheme` (`"light"` or `"dark"`)
@@ -280,6 +280,26 @@ and do not expose dismiss or read-state actions.
 | `preferences` | `{inapp, mail, push, sms}` | Current toggles |
 | `onChange` | `(channel, value) => void` | Per-channel updates |
 
+## WhatsNewBanner
+
+Non-blocking release notes banner. It shows `What's new in <version>` (plus a count of earlier
+unseen releases) until the viewer opens or dismisses it, and stays hidden until a newer release
+is listed. **See what's new** opens a `Modal` with each unseen release's Markdown notes.
+Steps: [Show release notes with WhatsNewBanner](../how-to/whats-new-banner.md).
+
+| Prop | Type | Description |
+|---|---|---|
+| `releases` | `WhatsNewRelease[]` | `{version, body, date?}` entries, newest first. `body` is Markdown |
+| `storageKey` | `string` | Device storage key for the last seen version. Default `@TerrenoUI:whatsNew:lastSeenVersion` |
+| `title` | `string` | Modal title. Default `What's new` |
+| `onOpen` | `() => void` | Called when the viewer opens the notes |
+| `testID` | `string` | Default `whats-new-banner`. Children: `-text`, `-open-button`, `-dismiss`, `-modal`, `-release-<version>` |
+
+`getUnseenWhatsNewReleases({releases, lastSeenVersion})` returns the releases newer than
+`lastSeenVersion`; an unknown or missing version counts as nothing seen.
+
+`BannerButton` also accepts an optional `testID`.
+
 ## Component Behaviors
 
 ### Button Layout Behavior
@@ -428,6 +448,8 @@ Pass `mascot` when the app owns a character. Terreno ships none. The node render
 
 The composer row (attachment picker, tools, input, Send) is vertically centered, so controls stay aligned with the input as it grows. The composer input grows with its text up to 200px, then scrolls. The attachment cell is omitted when `onAttachFiles` is not provided.
 
+The history sidebar (model selector, toolbar, New chat, and the history list) is a 250px-minimum column. Pass `showHistory={false}` to leave it out so the chat panel takes the full width, as on a phone. The host then owns history navigation and the sidebar's controls. `showHistory` defaults to `true`.
+
 Each history row keeps rename and delete in a three-dot overflow menu (`gpt-history-menu-{id}`), anchored with `DropdownPanel`. Rename uses an outlined pencil in the dark secondary text color. Titles truncate before the menu trigger, so the trigger stays aligned at any sidebar width.
 
 "Scroll to bottom" appears only when content sits more than 100px below the viewport. It never shows in an empty chat.