@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/dist/docs/versioned/next/reference/ai.md

@@ -96,7 +96,8 @@ src/
   `getMCPTools`, `runBufferedChatTurn` (one chat turn to completion without HTTP: the same system
   prompt, tools, and block checks as `/gpt/histories/:id/turn`; takes `{body: {historyId, prompt},
   options, req}` where `req` carries `user` and `headers`)
-- **Models:** `AIRequest`, `GptHistory`, `FileAttachment`, `Project` (lazy; prefer `getProjectModel()`)
+- **Models:** `AIRequest`, `AIDataset`, `GptHistory`, `FileAttachment`, `Project` (lazy; prefer `getProjectModel()`)
+- **Migrations:** `gptHistoryStringIdsMigration` (`{slug, up}` for an app migration file), `migrateGptHistoryStringIds`, `GPT_HISTORY_STRING_IDS_MIGRATION`, type `GptHistoryStringIdsResult` ([GptHistory String ids](#gpthistory-string-ids))
 - **Routes:** `addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`, `addFileRoutes`, `addProjectRoutes`, `addMcpRoutes`
 - **Structured output:** `parseAiJson`, `normalizeLlmJsonTextForStructuredOutput`, re-exported `Output`, `jsonSchema`, `JSONValue`, `FlexibleSchema` from `ai`
 - **Langfuse:** `initLangfuseClient`, `getLangfuseClient`, `shutdownLangfuseClient`, `compilePrompt`, `createPrompt`, `getPrompt`, `createTelemetryConfig`, `preparePromptForAI`, `initTracing`, `shutdownTracing`, `LangfuseCache`, cache helpers
@@ -224,10 +225,12 @@ Logs all AI calls for monitoring and admin explorer.
 
 ### GptHistory
 
-Conversation history with multi-modal prompts.
+Conversation history with multi-modal prompts. A synced collection: `/gpt/histories` streams each
+user's histories to `@terreno/syncdb` clients (see [addGptHistoryRoutes](#addgpthistoryroutesrouter-options)).
 
 | Field | Type | Description |
 |-------|------|-------------|
+| `_id` | string | A UUID for new histories, so offline sync clients can mint ids. Histories saved before 58 keep their old ObjectId as a hex string after the [migration](#gpthistory-string-ids) |
 | `userId` | ObjectId | Owner (required) |
 | `title` | string? | Auto-generated on the first chat turn's reply (`/gpt/prompt` or `turn`) when empty |
 | `projectId` | ObjectId? | Optional project association |
@@ -238,6 +241,30 @@ Assistant replies from `/gpt/prompt` carry `streamId` and `status`: `streaming`
 
 **Virtual:** `ownerId` aliases `userId` for `Permissions.IsOwner`.
 
+**Plugins:** `createdUpdatedPlugin`, `isDeletedPlugin`, `findOneOrNone`, `findExactlyOne`, `syncPlugin`. `syncPlugin` refuses `GptHistory.deleteMany`, `updateMany`, hard deletes, upserts, and query writes whose filter has no `_id`. Write one history at a time by `_id`; in tests, clear the collection with `GptHistory.collection.deleteMany({})`.
+
+`AIDataset.historyId` is the history's String `_id`. `registerAiDataset` still accepts an ObjectId and stores its hex string.
+
+#### GptHistory String ids
+
+Terreno 58 changed `GptHistory._id` from ObjectId to String. Histories saved before the upgrade still have ObjectId `_id`s, which the String schema cannot find. The `gpt-history-string-ids` migration moves them. Add it to the app's `migrations/` directory and apply it with `terreno-migrate` before deploying 58 frontends:
+
+```typescript
+// migrations/20261022130000-gpt-history-string-ids.ts
+import {gptHistoryStringIdsMigration} from "@terreno/ai";
+
+export const id = "20261022130000-gpt-history-string-ids";
+export const up = gptHistoryStringIdsMigration.up;
+```
+
+| Step | Effect |
+|------|--------|
+| 1 | Copy each ObjectId history (500 per batch) to `_id: oldId.toHexString()`, keeping every stored field. URLs and clients that hold the hex id keep working |
+| 2 | Rewrite `AIDataset.historyId` refs from the ObjectId to the hex string, including refs to histories that no longer exist |
+| 3 | Delete the ObjectId originals |
+
+A dry run (`terreno-migrate up --dry`) only counts the histories and refs it would change. The migration writes through the MongoDB driver, so it does not stamp sync seqs; moved histories reach sync clients as unstamped legacy rows on the next snapshot. Running it again changes nothing, and a run stopped partway finishes on the next run. It has no `down`: new histories get UUIDs, which have no ObjectId to go back to. `migrateGptHistoryStringIds({connection, dryRun, batchSize?, logger?, checkCancellation?})` runs the same steps without a migration file and returns `{historiesMigrated, datasetsUpdated}`.
+
 ### FileAttachment
 
 Metadata for files stored in GCS.
@@ -412,6 +439,8 @@ CRUD at `/gpt/histories` via `modelRouter`:
 | Create, List | `IsAuthenticated` |
 | Read, Update, Delete | `IsOwner` |
 
+Registered with the three-argument `modelRouter("/gpt/histories", GptHistory, {sync: {scope: {type: "owner", field: "userId"}}})`, so `SyncApp` serves the histories as the sync collection `gpt/histories` on each user's stream `gpt/histories|owner:{userId}`. A client reads them with `useQuery("gpt/histories")` and renames or deletes them with `useMutate("gpt/histories")`; sync payloads go through the same response handler as REST, so they also leave out `pendingAsk.promptIndex` and `pendingAsk.responseMessages`. Register `SyncApp` (and `RealtimeApp` for live deltas) in the app. REST CRUD stays for clients that do not sync. Every history route takes the String `_id`.
+
 Query filtered by `userId`; sort `-updated`; query fields `userId`, `projectId`. Create sets `userId` to the caller, so `{}` is a valid create body even when the app validates request bodies. Create and update bodies drop `pendingAsk` (including dotted `pendingAsk.*` paths), so only a chat turn writes it; the OpenAPI spec marks it `readOnly` on create and update. Create and update bodies also drop any `gcsKey` on `prompts[].content[]` parts (including dotted `prompts.N.content.M.gcsKey` paths) that the history does not already store, so a client can send stored prompts back but cannot add an attachment key.
 
 Pass `chat`, the options given to `addGptRoutes`, to add two headless actions for clients that do not read server-sent events, such as a watch app. Both exist only when `chat` turns `asks` on: without `chat`, or with `asks` off, neither action exists, so a host that never turned asks on gets no new endpoints. `AiApp` adds them when its `asks` option is set.
@@ -434,6 +463,9 @@ Bodies, results, and errors: [Headless endpoints](agent-ui-asks.md#headless-endp
 ### addFileRoutes(router, options)
 
 Requires `fileStorageService` and `gcsBucket` (registered by `AiApp` when both are set).
+`fileStorageService` may also be a function that returns the current service or `undefined`.
+Use it when storage is configured at runtime: the routes stay mounted and documented in
+`/openapi.json`, and answer `503 File storage is not configured` while it returns `undefined`.
 
 | Endpoint | Method | Auth | Description |
 |----------|--------|------|-------------|
@@ -495,7 +527,7 @@ new AiApp({
 | `toolChoice` | `"auto"` \| `"none"` \| `"required"` (default `"auto"` when tools present) |
 | `maxSteps` | Max tool-calling steps (default 5) |
 | `titleModelId` | Cheaper model for conversation title generation |
-| `openApiOptions` | Passed to route OpenAPI builders |
+| `openApiOptions` | Passed to route OpenAPI builders. Defaults to the OpenAPI instance `TerrenoApp` passes to `register` |
 | `projects` | Default `true`. `false` skips the `/gpt/projects` routes, so `AiApp` never registers the `Project` model |
 
 ## Cost and abuse limits
@@ -670,7 +702,7 @@ When `prompts.primary` is `local`, `ObservabilityApp.register` mounts admin-only
 | GET/POST | `/ai/observability/evaluators` | List / create. Create accepts `target: "full trace"` only (`generation span` and `dataset item` → 400). Seeded template install can still store other targets. `llm-judge` requires `judgePromptName`; create rejects when the judge prompt `outputSchema` omits a required dimension (400 names the key). `json-assert` supports `assertion` (`path` + `constraint`) or built-in output-schema mode. Human + `liveSampleRate > 0` → 400. Numeric dimension `range` is `min-max` (for example `0-1`); categorical `range` is `label|label` |
 | GET/PATCH/DELETE | `/ai/observability/evaluators/:id` | Read / update / soft-delete |
 | POST | `/ai/observability/traces/review` | Enqueue one or many traces against a human evaluator (`reason: "manual"`) |
-| GET | `/ai/observability/review` | Queue by `status` with counts; oldest-first. Response includes `more: false` so RTK preserves the count envelope. Rows include `traceName`, `promptName`, assignee, reason, and enqueue time |
+| GET | `/ai/observability/review` | Queue by `status` with counts; oldest-first. Response includes `more: false` so request clients keep the count envelope instead of unwrapping `data`. Rows include `traceName`, `promptName`, assignee, reason, and enqueue time |
 | GET | `/ai/observability/review/:id` | Item + evaluator dimensions + `given` / `wrote` panels and `rawInput` / `rawOutput` for the Raw JSON disclosure |
 | POST | `/ai/observability/review/:id` | `submit` (scores via ScoreSinks, status `done`), `skip`, or `assign` |
 

package/dist/docs/versioned/next/reference/announcements.md

@@ -82,7 +82,7 @@ The plugin applies `matchAudienceByType` before `matchAudience`. When `isStaff`
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/announcements/pending` | Current interrupt (`modal` or `banner` only) + `remainingCount` (`platform` query: `ios` \| `android` \| `web`; optional `version` build number) |
-| GET | `/announcements/feed` | Paginated published changelog — all display modes (`platform` and optional `version` as above) |
+| GET | `/announcements/feed` | Paginated published changelog — all display modes (`platform` and optional `version` as above; `limit` 1–100, default 20; `page` from 1). Returns `{data, more, page, total}`; `more` is true when a later page has items. |
 | POST | `/announcements/:id/acknowledge` | Record acknowledgement (idempotent per version). Same visibility as pending/feed; **404** when not visible. |
 | POST | `/announcements/:id/impression` | Record a view (`{ platform? }`). Same visibility as pending/feed; **404** when not visible. **400** for unknown keys or an invalid `platform`. |
 | POST | `/announcements/:id/click` | Record a primary-action click (`{ action: "primaryAction", platform? }`; optional `?version=` for min-build visibility). Returns **404** when not visible (checked before action/CTA validation). **400** when `action` is invalid, `primaryAction` is absent, or an explicit `platform` value is invalid. |
@@ -172,11 +172,11 @@ Set these environment variables on the MCP server to include live announcements:
 
 ### `useAcknowledgeAnnouncement`
 
-Injects RTK Query mutations for acknowledgement, impression, and primary-action click tracking:
+Sends acknowledgement, impression, and primary-action click events through the `client` passed to `useAcknowledgeAnnouncement(client, baseUrl?)` (see [`TerrenoRequestClient`](ui.md#terrenorequestclient)):
 
 | Method | Route | Notes |
 |--------|-------|-------|
-| `acknowledge(id)` | `POST /announcements/:id/acknowledge` | Invalidates pending queue. Query includes `platform` and, when available, `version` (same visibility gate as pending/feed). |
+| `acknowledge(id)` | `POST /announcements/:id/acknowledge` | Refetches the pending announcement in every mounted `useAnnouncements` on the same client. Query includes `platform` and, when available, `version` (same visibility gate as pending/feed). |
 | `recordImpression(id)` | `POST /announcements/:id/impression` | Sends current `platform` in body |
 | `recordClick(id)` | `POST /announcements/:id/click` | Body `{ action: "primaryAction", platform }`; query includes `platform` and, when available, `version` (same visibility gate as pending/feed) |
 

package/dist/docs/versioned/next/reference/api.md

@@ -49,11 +49,16 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 
 Two patterns for building Terreno APIs:
 
-### Deprecated: modelRouter `realtime`
+### Removed: modelRouter `realtime`
 
-`modelRouter({ realtime })` (RTK cache-patching websocket events) is **deprecated** and **will be removed in Terreno 58**. Use `sync` with [`@terreno/syncdb`](syncdb.md). See [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md).
+Terreno 58 removed `modelRouter({ realtime })` and the legacy RTK `sync` websocket event. Passing `realtime` is now a TypeScript error. Use `sync` with [`@terreno/syncdb`](syncdb.md). See [Upgrade from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md).
 
-`RealtimeApp` is **not** deprecated. It still hosts Socket.io, change streams, and `sync:delta`.
+Also removed: `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, the realtime registry (`registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`), the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. The server no longer handles `subscribe:model`, `subscribe:document`, or `subscribe:query`.
+
+`RealtimeApp` stays. It hosts Socket.io, socket auth, change streams, and `sync:delta`.
+Before it sends a `sync:delta` to a socket, it runs the router's `read` permissions (or RBAC
+read access) against the change's post-image hydrated as a model document, as REST does. So a
+virtual owner field works: `GptHistory`'s `ownerId` alias of `userId` passes `Permissions.IsOwner`.
 
 Keep `admin.realtime` when you want admin `admin:model.changed` events.
 
@@ -99,15 +104,21 @@ new TerrenoApp({
 
 ### HTTP rate limiting
 
-Opt-in. Pass `rateLimit: {}` on `TerrenoApp` to enable (omitted = off; Terreno 58 defaults on).
+On by default. Omitted, `undefined`, or `{}` mounts the limiter with the memory store and the defaults below. `rateLimit: false` turns it off. On Cloud Run pass `trustProxy: 1`.
 
 ```typescript
 new TerrenoApp({
   userModel: User,
-  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined,
+  rateLimit: {trustProxy: 1}, // or `false` to turn the limiter off
 });
 ```
 
+| `rateLimit` | Result |
+|-------------|--------|
+| omitted / `undefined` | On: memory store, default limits |
+| `{}` / `{store, limits, trustProxy, skip, betterAuthBasePath}` | On with those options |
+| `false` | Off |
+
 | Option | Default | Meaning |
 |--------|---------|---------|
 | `store` | `"memory"` | `"memory"` \| `"redis"` \| `"mongo"` |
@@ -211,7 +222,7 @@ Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI). H
 
 ## Collection catalog
 
-`modelRouter("/path", Model, options)` writes one catalog record per route path. MCP, realtime, and sync surfaces read that record; TerrenoApp calls `replaceCollectionOptions` once when access control is injected. Test helpers `clearMCPRegistry`, `clearRealtimeRegistry`, and `clearSyncRegistry` clear the entire catalog.
+`modelRouter("/path", Model, options)` writes one catalog record per route path. MCP and sync surfaces read that record; TerrenoApp calls `replaceCollectionOptions` once when access control is injected. Test helpers `clearMCPRegistry` and `clearSyncRegistry` clear the entire catalog.
 
 ## modelRouter actions
 
@@ -382,7 +393,7 @@ Create, update, and delete tools share REST permission, hook, and persistence se
 
 ### MCP service token model
 
-`McpServiceToken` stores the hashed credential records used by the optional MCP service-token feature. It is not a `modelRouter` model: consumer-facing create, list, and revoke routes are registered only when `mcpServiceTokens` is enabled on `TerrenoApp`.
+`McpServiceToken` stores the hashed credential records used by the optional MCP service-token feature. `_id` is a String (UUID for new rows; ObjectId hex for rows migrated from 57.x). The schema uses `isDeletedPlugin` and `syncPlugin`, so with `mcpServiceTokens` enabled the collection is synced read-only to its owner.
 
 ```typescript
 import {McpServiceToken} from "@terreno/api";
@@ -394,17 +405,23 @@ const {mcpServiceToken, token} = await McpServiceToken.issueFor(
 // Store or show `token` once. Only its SHA-256 hash is persisted.
 ```
 
-The token begins with `mcp_` followed by 32 random bytes encoded as hex. `issueFor` records the user's `tokenEpoch` (pass it on the user argument; default 0). `/mcp` refuses a token whose recorded epoch differs from the user's current `tokenEpoch` and sets its `revokedAt`, so a password reset, Better Auth password change, or session revocation ends every key minted before it. A row stored without `tokenEpoch` counts as epoch 0. `revokeOutdatedForUser(user)` revokes the user's keys from earlier epochs; the list and create routes call it so the list shows them as revoked. `verify(token)` returns `null` for unknown, expired, or revoked tokens. `revokeForUser(user, tokenId)` records `revokedAt`, and `countActiveForUser(userId)` excludes expired or revoked records. Document `deleteOne` (admin DELETE) also sets `revokedAt` and leaves the row for audit. `revokeAllForUser(userId)` revokes every active token the user holds and returns the count. Never return or log `tokenHash` or the plaintext token outside the initial issue result.
+The token begins with `mcp_` followed by 32 random bytes encoded as hex. `issueFor` records the user's `tokenEpoch` (pass it on the user argument; default 0). `/mcp` refuses a token whose recorded epoch differs from the user's current `tokenEpoch` and sets its `revokedAt`, so a password reset, Better Auth password change, or session revocation ends every key minted before it. A row stored without `tokenEpoch` counts as epoch 0. `revokeOutdatedForUser(user)` revokes the user's keys from earlier epochs; the list and create routes call it so the list shows them as revoked. `verify(token)` returns `null` for unknown, expired, or revoked tokens. `revokeForUser(user, tokenId)` records `revokedAt`, and `countActiveForUser(userId)` excludes expired or revoked records. A delete never removes or tombstones the row: document `deleteOne` and a soft delete (admin DELETE sets `deleted: true`) both set `revokedAt` and keep `deleted: false`, so the owner's synced row shows the revoke. `revokeAllForUser(userId)` revokes every active token the user holds and returns the count. Never return or log `tokenHash` or the plaintext token outside the initial issue result.
 
-Self-serve HTTP routes live at `/mcp/service-tokens`. `TerrenoApp` mounts them when `mcpServiceTokens` is enabled, passing its OpenAPI bundle. You can also call `addMcpServiceTokenRoutes(app, {publicMcpUrl, openApi})` yourself. They require session or JWT auth and **reject** `Authorization: Bearer mcp_…` so a service token cannot mint or list tokens.
+Self-serve routes are `modelRouter("/mcp/service-tokens", McpServiceToken, {sync: {scope: {type: "owner", field: "userId"}}})`. `TerrenoApp` mounts them when `mcpServiceTokens` is enabled, passing its OpenAPI bundle. You can also call `addMcpServiceTokenRoutes(app, {publicMcpUrl, openApi})` yourself, or build the registration with `createMcpServiceTokenRouter(options)`. They require session or JWT auth and **reject** `Authorization: Bearer mcp_…` so a service token cannot mint, list, or revoke tokens.
 
 | Method | Path | Body / params | Response |
 | --- | --- | --- | --- |
-| POST | `/mcp/service-tokens` | `{name, expiresAt?}` | `{data: {id, name, token, tokenPrefix, mcpUrl, expiresAt, created}}` |
-| GET | `/mcp/service-tokens` | `?page&limit` | `{data, page, limit, total, more}` — no `token` or `tokenHash` |
-| DELETE | `/mcp/service-tokens/:id` | — | `{data: {id, revokedAt}}` — owner only |
+| POST | `/mcp/service-tokens/create` | `{name, expiresAt?}` | `{data: {id, name, token, tokenPrefix, mcpUrl, expiresAt, created}}` (operation `mcpServiceTokens_create`) |
+| GET | `/mcp/service-tokens` | `?page&limit` | `{data, page, limit, more, total}` — the caller's rows, no `token` or `tokenHash` |
+| GET | `/mcp/service-tokens/:id` | — | `{data}` — owner only (`403` otherwise) |
+| POST | `/mcp/service-tokens/:id/revoke` | — | `{data}` — the revoked row without `tokenHash` (operation `mcpServiceTokens_revoke`) |
+| POST / PATCH / DELETE | `/mcp/service-tokens[/:id]` | — | `405`: client writes are disabled |
+
+`expiresAt` is an optional ISO-8601 datetime (Luxon `DateTime.fromISO`). Omit it for a token that does not expire. Create returns `mcpUrl` from `publicMcpUrl`, else `BETTER_AUTH_URL`, else the request host, with `/mcp` appended when missing. An 11th **active** token for the same user is `400`. Revoking an unknown, foreign, or already revoked token is `404`. List includes revoked rows for the owner so the UI can show history. Default and maximum page size is 100.
+
+Sync: collection `mcp/service-tokens`, stream `mcp/service-tokens|owner:{userId}`. Snapshot entities, `/sync/entities` rows, and `sync:delta` payloads go through `toPublicMcpServiceToken`, which drops `tokenHash`. Sync `create`, `update`, and `delete` mutations are nacked `unauthorized`; mint and revoke through the actions above.
 
-`expiresAt` is an optional ISO-8601 datetime (Luxon `DateTime.fromISO`). Omit it for a token that does not expire. Create returns `mcpUrl` from `publicMcpUrl`, else `BETTER_AUTH_URL`, else the request host, with `/mcp` appended when missing. An 11th **active** token for the same user is `400`. Revoke and cross-owner access are `404`. List includes revoked rows for the owner so the UI can show history. Default page size is 100 (maximum 100).
+Migration: `mcpServiceTokenStringIdsMigration.up` (slug `mcp-service-token-string-ids`) re-inserts each ObjectId row with `_id = oldId.toHexString()` and deletes the original. It is idempotent, resumes an interrupted run, and works without transactions. `migrateMcpServiceTokenStringIds(ctx)` returns `{converted, pending}`. Wire it into an app `migrations/` file as shown in [Run MongoDB migrations](../how-to/run-mongodb-migrations.md#framework-migrations).
 
 ### MCP OAuth
 
@@ -489,8 +506,7 @@ setupServer({
 - `POST /auth/refresh_token` — Refresh access token
 - `POST /auth/forgotPassword` — Always 202; mails a reset link only when the email exists (with
   `BetterAuthApp` registered, only when that user already has a JWT password)
-- `POST /auth/resetPassword` — `{token, password}`; also aliased at `POST /resetPassword` for the
-  RTK client. With `BetterAuthApp` registered, a token for a user without a JWT password gets 400
+- `POST /auth/resetPassword` — `{token, password}`; also aliased at `POST /resetPassword` (the `jwtAuthAdapter` `resetPassword` path in `@terreno/syncdb/auth`). With `BetterAuthApp` registered, a token for a user without a JWT password gets 400
   `legacy-password-reset-unavailable` and sets no password (`POST /auth/login` has no second
   factor); that user resets through Better Auth
 - `POST /auth/sendVerification` — Authenticated; 202 only after delivery succeeds; mails a verification link when `emailVerified` is not true
@@ -515,8 +531,8 @@ letter case, needs no password. `currentPassword` is never saved.
 | User has no password (for example GitHub-only or social-only) | 400 `Set a password on your account before changing your email. …` | Nothing |
 | Right `currentPassword` | 200 with the updated user | The whole body |
 
-The status is 403, not 401, so `@terreno/rtk` does not treat a wrong password as an expired
-session and log the user out.
+The status is 403, not 401, so the syncdb request client does not treat a wrong password as an
+expired session and log the user out.
 
 The password is checked against the passport-local-mongoose hash first. A wrong password
 counts toward the model's passport lockout when `limitAttempts` is on, the same counter
@@ -593,7 +609,7 @@ case instead of 202. Email lookup is case-insensitive. Successful reset calls `s
 and deletes Better Auth sessions. Better Auth password reset updates the JWT password of the
 matching app User when it already has one, and bumps its `tokenEpoch`. Access
 tokens stay valid until expiry (default 15m). `POST /resetPassword`
-matches the `@terreno/rtk` `resetPassword` mutation path (`password` or `newPassword`).
+matches the `@terreno/syncdb/auth` `jwtAuthAdapter` `resetPassword` path (`password` or `newPassword`).
 
 For any other server-side password change, such as an admin "set password" action, call
 `changeUserPassword(user, password, {adminId, app: req.app})`. It does what reset does: sets the
@@ -821,7 +837,7 @@ Endpoints it adds, under `basePath` (default `/api/auth`):
   cookie, and redirects to the provider. A link that cannot start redirects to
   `errorCallbackURL` (or `callbackURL`) with `error=session_expired`, `error=provider_not_found`,
   or `error=link_failed`. The provider callback links the account and redirects to `callbackURL`
-  with no `#ott`, since no session is created. rtk's `linkSocialWithHandoff` drives both steps;
+  with no `#ott`, since no session is created. `linkSocialWithHandoff` from `@terreno/syncdb/auth` drives both steps;
   see [Linking a provider in bearer mode](../how-to/configure-better-auth.md#linking-a-provider-in-bearer-mode).
 
 With the opt-in `rateLimit`, every path above is in the auth bucket. Better Auth's own limiter
@@ -832,7 +848,7 @@ allows three starts, three link intents, and three link starts per ten seconds p
 Every Better Auth server answers `GET {basePath}/terreno/methods` (default
 `/api/auth/terreno/methods`) with the sign-in methods it has enabled, so a login screen renders
 only those. It needs no session. Read it from a frontend with `useAuthMethods(authClient)` from
-`@terreno/rtk`.
+`@terreno/syncdb/auth`.
 
 ``````json
 {
@@ -870,8 +886,7 @@ plugin-registered providers are reflected.
 
 Every Better Auth server serves `POST {basePath}/terreno/set-password` (default
 `/api/auth/terreno/set-password`) so a signed-in user who has no password, such as one who signed
-up with a provider, can add one. Better Auth's own `setPassword` is server-only. rtk's
-`useAccountSecurity` calls it from the password card's "Set a password" form.
+up with a provider, can add one. Better Auth's own `setPassword` is server-only. `useAccountSecurity` from `@terreno/syncdb/auth` calls it from the password card's "Set a password" form.
 
 | Request | Response |
 | --- | --- |
@@ -903,8 +918,8 @@ means the cookie expired. Only values the response sets are carried. Such a sign
 answers with a two-factor challenge has no `set-auth-token`. The header is listed in
 `Access-Control-Expose-Headers`. On `{basePath}/two-factor/*`, `/passkey/*`, and `/sign-in/*`,
 the header's challenge cookies are merged into the request's cookies unless a real cookie of
-the same name is present; other names, including session cookies, are ignored. rtk's bearer mode
-uses it; see
+the same name is present; other names, including session cookies, are ignored. The
+`@terreno/syncdb/auth` bearer mode uses it; see
 [Challenges without cookies](../explanation/authentication.md#challenges-without-cookies).
 
 **Endpoints (when enabled):**

package/dist/docs/versioned/next/reference/cli.md

@@ -2,7 +2,7 @@
 
 Install: `bun add -g @terreno/cli` then run `terreno --help`.
 
-The `terreno` binary is the operator CLI for Terreno apps. It wraps documentation search, codegen (syncdb SDK, RTK OpenAPI SDK, Mongoose models, routes, screens, forms, admin install notes), app bootstrap, local project tools from `@terreno/mcp`, and **OpenAPI-driven REST calls**.
+The `terreno` binary is the operator CLI for Terreno apps. It wraps documentation search, codegen (syncdb collection SDK, typed API request SDK, Mongoose models, routes, screens, forms, admin install notes), app bootstrap, local project tools from `@terreno/mcp`, and **OpenAPI-driven REST calls**.
 
 Generate an app-specific CLI from your backend spec:
 
@@ -18,7 +18,7 @@ terreno generate rest-cli --schema http://localhost:4000/openapi.json --out ./to
 | `docs component <Name>` | Print `@terreno/ui` component props |
 | `docs upgrade --from --to` | Lockstep upgrade notes |
 | `generate syncdb` | Typed syncdb hooks from OpenAPI (`--schema`, `--out`, `--collections`, `--config`, `--no-format`) |
-| `generate sdk` | Run `@rtk-query/codegen-openapi` with `--config` |
+| `generate sdk` | Typed request hooks (`apiSdk.ts`) for every non-synced route via the syncdb codegen (`--schema`, `--out`, `--config`, `--no-format`); same output as `terreno-syncdb-codegen --api-out`. A legacy RTK `--config openapi-config.ts` alone is rejected |
 | `generate rest-cli` | Scaffold a bun CLI from OpenAPI (`--schema`, `--out`, `--name`, `--base-url`) |
 | `generate model` | Mongoose model (`--name`, `--field name:Type:required`, `--owner`, `--soft-delete`) |
 | `generate route` | `modelRouter` module (`--model-name`, `--route-path`, `--owner-filtered`, `--query-fields`, `--sort`) |
@@ -33,8 +33,7 @@ terreno generate rest-cli --schema http://localhost:4000/openapi.json --out ./to
 | `api request <METHOD> <path>` | Invoke by method + path template |
 | `info` | Local `@terreno/*` versions (via MCP local tools) |
 | `logs` | Merge backend/browser JSONL, Metro events, and app CDP console (`--entries`, `--level`, `--since`, `--sources`; `last-error`) |
-| `state` | Inspect client state with `get_client_state`: RTK Query (Better Auth via the `auth` alias or `betterAuth`; `--slice`, `--query`) and SyncDB, through the dev stores or Metro CDP. The result names the detected `layer` |
-| `eval` | Evaluate JavaScript in the app runtime through Metro CDP (`--code`; requires `TERRENO_MCP_EVAL=1`) |
+| `state` | Inspect the live SyncDB client (`get_syncdb_state`): status, entities, outbox, conflicts, cursors, streams, debug events (`--collection`, `--entity-id`, `--limit`, `--name`, `--no-events`). Needs `createSyncDb({debug: true})`. The Terreno 57 `--slice` / `--query` Redux flags were removed in 58 and now exit 1 || `eval` | Evaluate JavaScript in the app runtime through Metro CDP (`--code`; requires `TERRENO_MCP_EVAL=1`) |
 | `navigate` | Navigate Expo Router through Metro CDP (requires `TERRENO_MCP_EVAL=1`) |
 | `web [url]` | Automate the web app with Bun 1.4 `Bun.WebView`; ordered `--action` JSON, `--snapshot`, and `--screenshot` |
 | `db schema` | Mongo collections (`--collection-filter`, `--summary`) |

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

@@ -85,10 +85,10 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
-| `EXPO_PUBLIC_API_URL` | `@terreno/rtk` | ✅ prod web | dev auto-detect | No | **client** |
-| `EXPO_PUBLIC_DEV_API_PORT` | `@terreno/rtk` | ❌ | `4000` | No | **client** |
-| `EXPO_PUBLIC_BUILD_NUMBER` | example-frontend | ❌ | — | No | **client** |
-| `OPENAPI_URL` | example-frontend `sdk` script | ❌ | `http://localhost:4000/openapi.json` | No | tooling |
+| `EXPO_PUBLIC_API_URL` | `@terreno/syncdb/config` | ✅ prod web | dev auto-detect | No | **client** |
+| `EXPO_PUBLIC_DEV_API_PORT` | `@terreno/syncdb/config` | ❌ | `4000` | No | **client** |
+| `EXPO_PUBLIC_BUILD_NUMBER` | `@terreno/syncdb/buildNumber` (`app.config.ts`) | ❌ | git commit count | No | **client** |
+| `OPENAPI_URL` | example-frontend `sdk` / `sync-sdk` scripts | ❌ | `http://localhost:4000/openapi.json` | No | tooling |
 
 ### `app.json` `extra` (not `process.env`)
 
@@ -96,18 +96,17 @@ Configured in `expo.extra` and read via `expo-constants`:
 
 | Key | Read by | Notes |
 |-----|---------|-------|
-| `BASE_URL` | `@terreno/rtk` | Production fallback when `EXPO_PUBLIC_API_URL` unset; use `__SAME_ORIGIN__` for same-origin admin SPA |
-| `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 |
+| `BASE_URL` | `@terreno/syncdb/config` | Production fallback when `EXPO_PUBLIC_API_URL` unset; use `__SAME_ORIGIN__` for same-origin admin SPA |
+| `DEV_API_PORT` | `@terreno/syncdb/config` | Override dev API port (mirrors `EXPO_PUBLIC_DEV_API_PORT`) |
+| `buildNumber` | `@terreno/syncdb/app` `useUpgradeCheck` | Sent to `GET /version-check`; set it with `resolveBuildNumber` |
+| `SOCKET_TRANSPORTS` | example-frontend (`store/socketTransports.ts`) | Comma-separated Socket.IO transports passed to `createSyncDb({socketTransports})`. Unset keeps `polling,websocket`; the Vercel build sets `websocket` |
 
-Resolution order for API base URL (`rtk/src/constants.ts`):
+Resolution order for API base URL (`syncdb/src/config/resolveBaseUrls.ts`):
 
-1. `EXPO_PUBLIC_API_URL` (production and dev)
-2. `extra.BASE_URL` (production only, when env unset)
-3. Dev fallbacks: `hostUri`, experience URL, `localhost`
+1. `extra.BASE_URL` = `__SAME_ORIGIN__` → the page origin (web)
+2. `EXPO_PUBLIC_API_URL` (production and dev)
+3. `extra.BASE_URL` (production only, when env unset)
+4. Dev fallbacks: `hostUri`, experience URL, `localhost` on the dev API port
 
 `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`.
 
@@ -232,7 +231,7 @@ for authenticated test sends.
 | `VALKEY_URL` | `@terreno/api` realtime adapter **and** `rateLimit.store: "redis"` | ❌ | — | Yes | server |
 | `REDIS_URL` | `@terreno/api` fallback after `VALKEY_URL` (realtime + Redis rate-limit store) | ❌ | — | Yes | server |
 
-There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. Apps that want an env toggle pass `rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined` themselves. See [Rate limiting](../how-to/rate-limiting.md).
+There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. The limiter is on by default. Apps that want an env toggle pass `rateLimit: process.env.RATE_LIMIT_DISABLED === "true" ? false : {trustProxy: 1}` themselves. See [Rate limiting](../how-to/rate-limiting.md).
 
 ## Webhooks & notifications
 
@@ -317,7 +316,8 @@ example-backend **test** setup only. They are not read by `@terreno/jobs`. Use
 
 `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.
+skips it, so no deployed revision holds those accounts. The exception is a PR preview, whose
+`MONGO_DB_NAME` starts with `terreno-example-pr-`: it seeds its own throwaway database.
 
 ## Testing & CI (tooling only)
 

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

@@ -41,14 +41,16 @@ new TerrenoApp({userModel: User})
 
 ### Frontend
 
-Use the `useFeatureFlags` hook from `@terreno/rtk` to evaluate flags for the current user:
+Use `useFeatureFlags` from `@terreno/syncdb/flags` to read flags for the current user. It
+loads `GET {basePath}/flagConfiguration` with the syncdb request client (the one from
+`ApiClientProvider`) and refetches when the server pushes `featureFlagsChanged` on the
+syncdb socket:
 
 ```typescript
-import {useFeatureFlags} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
+import {useFeatureFlags} from "@terreno/syncdb/flags";
 
-const MyComponent = () => {
-  const {getFlag, getVariant, isLoading} = useFeatureFlags(terrenoApi);
+const MyComponent: React.FC<{userId?: string}> = ({userId}) => {
+  const {getFlag, getVariant, isLoading} = useFeatureFlags({skip: !userId, userId});
 
   if (isLoading) return <Spinner />;
 
@@ -59,11 +61,41 @@ const MyComponent = () => {
 };
 ```
 
-New code can also use OpenFeature React hooks (`useBooleanFlagValue`, `useStringFlagValue`, `FeatureFlag`, …) after wiring `useTerrenoFeatureFlags` and `<OpenFeatureProvider domain="feature-flags">` — see `@terreno/rtk` and [how-to: add feature flags](../how-to/add-feature-flags.md).
+New code can also use OpenFeature React hooks (`useBooleanFlagValue`, `useStringFlagValue`, `FeatureFlag`, …) after wiring `useTerrenoFeatureFlags` and `<OpenFeatureProvider domain="feature-flags">` — see [how-to: add feature flags](../how-to/add-feature-flags.md).
+
+#### `@terreno/syncdb/flags`
+
+| Export | Description |
+|--------|-------------|
+| `useTerrenoFeatureFlags(options?)` | Loads `/flagConfiguration` into OpenFeature's `TypedInMemoryProvider` for `domain`; returns `{client, flags, isLoading, error, refetch}` |
+| `useFeatureFlags(options?)` | Flat accessors over `useTerrenoFeatureFlags`: `{flags, getFlag, getVariant, isLoading, error, refetch}` |
+| `TerrenoFlagConfiguration`, `TerrenoFlagDefinition` | Wire shape of `/flagConfiguration` |
+| `DEFAULT_FEATURE_FLAGS_BASE_PATH`, `DEFAULT_FEATURE_FLAGS_DOMAIN`, `DEFAULT_FEATURE_FLAGS_EVENT` | `"/feature-flags"`, `"feature-flags"`, `"featureFlagsChanged"` |
+
+Options (both hooks):
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `userId` | `null` | Current user. A change refetches and sets the OpenFeature `targetingKey` |
+| `skip` | `false` | Do not fetch or listen (for example while signed out) |
+| `client` | `ApiClientProvider` client | Request client from `@terreno/syncdb/api` |
+| `socket` | `SyncDbProvider` client | Anything with `onSocketEvent` (a `SyncDb`). Pass your `syncDb` when the hook sits above `SyncDbProvider`; `null` turns live refresh off |
+| `socketEventName` | `"featureFlagsChanged"` | Push event that triggers a refetch |
+| `basePath` | `"/feature-flags"` | `FeatureFlagsApp` `basePath` |
+| `domain` | `"feature-flags"` | OpenFeature domain; must match `<OpenFeatureProvider domain>` |
+
+`isLoading` is `true` until the first response is installed in OpenFeature and again while a
+refetch is in flight; it is `false` when skipped or after an error. Every hook reading the same
+`basePath` shares one cache entry, so a single instance that listens to the socket (usually the
+root `OpenFeatureProvider` bridge) is enough; other screens can pass `socket: null`. The last
+unmounted `useTerrenoFeatureFlags` for a domain restores OpenFeature's NOOP provider.
+
+`@openfeature/web-sdk` (and `@openfeature/react-sdk` for the React hooks) are optional peer
+dependencies of `@terreno/syncdb`; add them to apps that import `@terreno/syncdb/flags`.
 
 ## OpenFeature integration
 
-`FeatureFlagsApp` registers an OpenFeature **server** provider (`MongoFeatureFlagProvider`) on a dedicated domain (default `"feature-flags"`) so the global default provider is unchanged. The authenticated bulk endpoint **`GET {basePath}/flagConfiguration`** returns a `FlagConfiguration`-compatible map (suitable for `TypedInMemoryProvider` on the client). Disabled **boolean** flags are included and resolve to `off`, so a client can tell a turned-off flag from one that was never created. Disabled variant flags and archived flags are omitted. The legacy **`GET {basePath}/evaluate`** response shape is unchanged but is **deprecated**: responses include `Deprecation: true` and a `Sunset` HTTP-date header (~90 days). Prefer `useTerrenoFeatureFlags` / `useFeatureFlags` from `@terreno/rtk`, or migrate direct HTTP callers to `/flagConfiguration`.
+`FeatureFlagsApp` registers an OpenFeature **server** provider (`MongoFeatureFlagProvider`) on a dedicated domain (default `"feature-flags"`) so the global default provider is unchanged. The authenticated bulk endpoint **`GET {basePath}/flagConfiguration`** returns a `FlagConfiguration`-compatible map (suitable for `TypedInMemoryProvider` on the client). Disabled **boolean** flags are included and resolve to `off`, so a client can tell a turned-off flag from one that was never created. Disabled variant flags and archived flags are omitted. The legacy **`GET {basePath}/evaluate`** response shape is unchanged but is **deprecated**: responses include `Deprecation: true` and a `Sunset` HTTP-date header (~90 days). Prefer `useTerrenoFeatureFlags` / `useFeatureFlags` from `@terreno/syncdb/flags`, or migrate direct HTTP callers to `/flagConfiguration`. The server logs this advice once per process on the first `/evaluate` call.
 
 ### `defaultVariant` on `FeatureFlag`
 
@@ -81,6 +113,15 @@ Consumers may augment `@openfeature/core` with `BooleanFlagKey` / `StringFlagKey
 
 Pass `liveUpdates: { socketIoServer: io | () => io }` to broadcast on Mongoose change streams. **Requires MongoDB as a replica set** (single-node replset is fine). Emits a socket event (default `featureFlagsChanged`, payload `{ key }`) and `PROVIDER_CONFIGURATION_CHANGED` on the server provider. All authenticated subscribers receive the same event name; payload is only the flag key (same keys are already exposed per user via `/flagConfiguration`).
 
+Emit on the Socket.io server that hosts the syncdb socket — `RealtimeApp.getIo()` — so clients
+receive the push on the one socket they already hold:
+
+```typescript
+const realtimeApp = new RealtimeApp({/* ... */});
+app.register(realtimeApp);
+app.register(new FeatureFlagsApp({liveUpdates: {socketIoServer: () => realtimeApp.getIo()}}));
+```
+
 ## Exports
 
 ### Classes

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

@@ -237,8 +237,8 @@ always hides payload regardless of the hook.
 Widgets are registered in the built-in registry — enable via `JobsApp.adminContribution()` only.
 The admin shell lists Jobs under **Platform** (not Screens). Hosts still contribute
 `name: "jobs"`; do not add a second sidebar link.
-Custom screens should pass the app's generated RTK `api` into `AdminProvider`; jobs screens wire
-admin HTTP internally (not via a public `useJobsDashboardApi` export).
+Custom screens render inside the app's `AdminProvider` (auth binding); jobs screens wire
+admin HTTP through its fetch client internally (not via a public `useJobsDashboardApi` export).
 
 ## GCP Cloud Tasks (`@terreno/jobs/runners/gcpCloudTasks`)