@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/src/docs/versioned/next/how-to/password-reset.md

@@ -69,7 +69,7 @@ On `BetterAuthConfig` set the same `publicAppUrl`, `sendMail`, and `renderAuthMa
 
 1. Pass `onForgotPassword` (or `onForgotPasswordPress`) to `LoginScreen`.
 2. Add `/forgotPassword` (email form) and `/resetPassword` that reads `token` from the query string.
-3. On Better Auth apps, request reset with `authClient.requestPasswordReset` and submit with `authClient.resetPassword({newPassword, token})`. JWT apps use `POST /auth/forgotPassword` and the RTK `resetPassword` mutation (`POST /resetPassword`). The example app falls back to the JWT request or reset route when Better Auth rejects the operation, so either auth mode can complete.
+3. On Better Auth apps, request reset with `authClient.requestPasswordReset` and submit with `authClient.resetPassword({newPassword, token})`. JWT apps call `POST /auth/forgotPassword` and `POST /resetPassword` through the generated `usePostAuthForgotPasswordMutation` / `usePostResetPasswordMutation` hooks (`store/apiSdk.ts`), or `useJwtAuth().resetPassword` from `@terreno/syncdb/auth`. The example app falls back to the JWT request or reset route when Better Auth rejects the operation, so either auth mode can complete.
 4. Show a profile banner when `emailVerified` is false, with Resend calling `POST /auth/sendVerification`.
 5. Add `/verifyEmail` that reads `token` from the query string. JWT apps call `POST /auth/verifyEmail`. Better Auth apps try `GET /verify-email?token=...` first, then the JWT route so either token type can complete.
 

package/src/docs/versioned/next/how-to/product-announcements.md

@@ -64,7 +64,7 @@ For release-driven batches, use an [announcement release pack](../reference/anno
 
 ### Admin overview
 
-`AnnouncementOverview` calls `GET /announcements/overview` (via RTK `injectEndpoints`) and shows:
+`AnnouncementOverview` calls `GET /announcements/overview` (through the `AdminProvider` fetch client) and shows:
 
 - Launch workflow guidance (draft → targeting → preview → publish) with a primary **Create announcement** action
 - Summary cards for published, drafts, impressions, acknowledgements, and CTA clicks
@@ -87,12 +87,15 @@ Wrap authenticated app content:
 
 ```tsx
 import {AnnouncementNavigator} from "@terreno/ui";
+import {apiClient} from "@/store/apiClient"; // @terreno/syncdb/api createApiClient(...)
 
-<AnnouncementNavigator api={terrenoApi}>
+<AnnouncementNavigator client={apiClient}>
   <AppTabs />
 </AnnouncementNavigator>
 ```
 
+`client` is the app's request client (see [`TerrenoRequestClient`](../reference/ui.md#terrenorequestclient)); the RTK `api` prop was removed in Terreno 58.
+
 Place it after consent/onboarding wrappers if you use `ConsentNavigator`. The navigator sends the native platform (`ios` / `android` / `web`) and, when available, the app build number from `Constants.expoConfig.extra.buildNumber` (same source as `useUpgradeCheck`) on pending and feed requests. Only pending failures block the app — changelog feed errors are non-fatal. These surfaces are not in the `@terreno/ui` component demo; wire them in the app (`example-frontend`) the same way.
 
 ## Modal vs banner
@@ -120,7 +123,7 @@ Interrupt frequency is enforced **client-side** in `AnnouncementNavigator` befor
 
 ```tsx
 <AnnouncementNavigator
-  api={terrenoApi}
+  client={apiClient}
   frequency={{
     cooldownHours: 24,
     skipFirstLaunch: false,

package/src/docs/versioned/next/how-to/rate-limiting.md

@@ -1,37 +1,62 @@
 # Rate limiting
 
-Turn on HTTP rate limiting for `@terreno/api` by passing `rateLimit` on `TerrenoApp`. The framework does **not** read `RATE_LIMIT_ENABLED`.
+`TerrenoApp` turns on HTTP rate limiting by default (Terreno 58 and later). Omitting `rateLimit` mounts the limiter with the memory store and the default limits. The framework does **not** read `RATE_LIMIT_ENABLED`.
 
-Terreno 58 will default the limiter **on**. Until then, omit `rateLimit` to leave it off.
+## Default (memory)
 
-## Terreno 58 (not this release)
+```typescript
+new TerrenoApp({userModel: User});
+```
+
+That is the same as `rateLimit: {}` or `rateLimit: {store: "memory"}`: auth 20 / 15 min, api 600 / 15 min, one bucket per Node process.
+
+## Cloud Run
+
+Cloud Run sits behind one Google Front End hop. Without `trustProxy`, every unauthenticated request shares the front end's address, so all users share one auth bucket (20 logins per 15 minutes for the whole service). Pass `trustProxy: 1`:
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  rateLimit: {trustProxy: 1},
+});
+```
+
+The limiter sets Express `trust proxy` from `rateLimit.trustProxy` when it mounts. Set it there, not with `app.set("trust proxy", …)` before `build()`.
 
-When Terreno 58 is cut, `TerrenoApp` will enable the limiter by default. Apps that must stay unlimited will pass an explicit off (documented in the 58 upgrade note). Until then, omitted `rateLimit` is unlimited. Stub: [`mcp-server/src/docs/upgrades/58.0.0.md`](../../mcp-server/src/docs/upgrades/58.0.0.md).
+## Turn it off
 
-## Enable (memory)
+Pass `false`:
 
 ```typescript
 new TerrenoApp({
   userModel: User,
-  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined,
+  rateLimit: false,
 });
 ```
 
-Empty `{}` is the same as `{store: "memory"}`.
+Apps that want an env toggle own it:
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  rateLimit: process.env.RATE_LIMIT_DISABLED === "true" ? false : {trustProxy: 1},
+});
+```
+
+## Tests
+
+Each `build()` creates a fresh memory store, so most suites never reach a limit. A suite that logs in more than 20 times or sends more than 600 requests against one app instance should pass `rateLimit: false` in its shared app helper, or raise `limits`.
 
 ## Redis on Cloud Run
 
 1. Add a Valkey or Redis instance (Memorystore or equivalent).
 2. Set `VALKEY_URL` (preferred) or `REDIS_URL` on the Cloud Run service. Same URL as realtime Redis.
-3. Pass `store: "redis"` only when you intend to enable the limiter:
+3. Pass `store: "redis"`:
 
 ```typescript
 new TerrenoApp({
   userModel: User,
-  rateLimit:
-    process.env.RATE_LIMIT_ENABLED === "true"
-      ? {store: "redis", trustProxy: 1}
-      : undefined,
+  rateLimit: {store: "redis", trustProxy: 1},
 });
 ```
 
@@ -50,7 +75,7 @@ new TerrenoApp({
 
 Pass `{store: "mongo"}`. Hits live in `rateLimitHits` on the same mongoose connection as the app. A TTL index on `expiresAt` expires windows. This collection is not a `modelRouter` resource.
 
-Unauthenticated keys use `req.ip`. Express `trust proxy` defaults to **off** so a client cannot rotate `X-Forwarded-For` to bypass the auth bucket. On Cloud Run (one hop via GFE), pass `trustProxy: 1`. Extra proxies: hop count or a subnet list. `trustProxy: false` is the same as the default.
+Unauthenticated keys use `req.ip`. Express `trust proxy` defaults to **off** so a client cannot rotate `X-Forwarded-For` to bypass the auth bucket. On Cloud Run (one hop via GFE), pass `trustProxy: 1` (see [Cloud Run](#cloud-run)). Extra proxies: hop count or a subnet list. `trustProxy: false` is the same as the default.
 
 ## Limit one route
 
@@ -90,6 +115,3 @@ JWT login/signup/refresh and password-reset paths skip access-token verification
 Auth-bucket keys are always the client IP, even if a Better Auth session already set `req.user`. API traffic still keys by user when authenticated.
 
 When `BetterAuthApp` is registered, TerrenoApp copies its `config.basePath` into the limiter unless you set `rateLimit.betterAuthBasePath`.
-
-
-

package/src/docs/versioned/next/how-to/run-mongodb-migrations.md

@@ -30,6 +30,25 @@ export const down = async ({dryRun, mongoose}): Promise<void> => {
 };
 ```
 
+## Framework migrations
+
+Some Terreno releases ship a data migration in a package. Wire it in with a one-line wrapper file, so it runs, dry-runs, and records history like your own files:
+
+```typescript
+// migrations/20261022120000-mcp-service-token-string-ids.ts
+import {mcpServiceTokenStringIdsMigration} from "@terreno/api";
+
+export const id = "20261022120000-mcp-service-token-string-ids";
+export const up = mcpServiceTokenStringIdsMigration.up;
+```
+
+| Package | Export | Since | What it does |
+| --- | --- | --- | --- |
+| `@terreno/api` | `mcpServiceTokenStringIdsMigration` | 58.0.0 | Re-keys ObjectId `McpServiceToken` rows to hex-string `_id`s. Idempotent; no `down`. |
+| `@terreno/ai` | `gptHistoryStringIdsMigration` | 58.0.0 | Re-keys ObjectId `GptHistory` rows to hex-string `_id`s and rewrites `AIDataset.historyId`. Idempotent; no `down`. |
+
+The upgrade note for each release says which framework migrations to add.
+
 ## First apply
 
 1. Generate a draft from the current models vs the last `schemaAfter` snapshot:

package/src/docs/versioned/next/how-to/run-tests-locally.md

@@ -21,7 +21,7 @@ with `origin/master`. It applies the CircleCI path-filter mapping in
 `.circleci/config.yml`, then runs the local command for each triggered job: package
 `test:coverage` plus the 90% new-file LCOV gate, `ui` types, demo typecheck,
 example-backend and example-frontend tests, every `repo-policies` step, rulesync drift,
-and the typedoc API reference when `api/src` or `rtk/src` changes. Every step runs even
+and the typedoc API reference when `api/src` changes. Every step runs even
 after a failure, so a single pass lists every problem. Fix them all, then push once.
 
 Jobs that need infrastructure (Playwright e2e, Maestro, admin-spa integration, Docker)
@@ -64,7 +64,6 @@ bun test --only-failures <path>
 | `ai-ci` | `cd ai && bun run test:ci` |
 | `blocks-ci` | `bun run blocks:test` |
 | `ui-ci` | `bun run ui:test` |
-| `rtk-ci` | `bun run rtk:test` |
 | `syncdb-ci` | `bun run syncdb:test` |
 | `comms-ci` | `bun run comms:test` |
 | `jobs-ci` / jobs package | `bun run jobs:test` |
@@ -124,7 +123,7 @@ MONGO_URI="mongodb://127.0.0.1:27017/terreno-e2e?replicaSet=rs0" \
 | CircleCI shard | Specs |
 | --- | --- |
 | `e2e` `auth` | `login` `signup` `consents` `forgot-password` `reset-password` `verify-email` `two-factor` |
-| `e2e` `app` | `todos` `profile` `realtime` `ai-chat` `pdf` |
+| `e2e` `app` | `todos` `todo-windows` `todo-browser` `profile` `realtime` `ai-chat` `pdf` `notifications` `socket-flags` `mcp-tokens` |
 | `e2e` `admin-core` | `admin` `admin-home` `admin-form` `admin-todo-crud` `admin-title-update-depth` `org-admin-security` `admin-user-security` |
 | `e2e-cross-site` (not required) | the cross-site specs below, then `account-linking` with `E2E_ACCOUNT_LINKING=explicit` |
 | `e2e` `admin-table` | `admin-table-search-filter` `admin-table-bulk-actions` `admin-custom-screens` `admin-comms-back` `harness-approvals` `harness-intake` |

package/src/docs/versioned/next/how-to/set-up-social-login.md

@@ -317,7 +317,7 @@ Expo plugin. The provider still returns to the backend's own
    `@better-auth/expo`, which serves `GET {basePath}/expo-authorization-proxy`. The app opens
    that URL in the browser; it sets the OAuth state cookie there and redirects to the provider.
 2. **Give the app a scheme.** Set `expo.scheme` in `app.json` (`frontend` in the example) and
-   pass the same value to `createBetterAuthClient({scheme})` from `@terreno/rtk`.
+   pass the same value to `createBetterAuthClient({scheme})` from `@terreno/syncdb/auth`.
 3. **List the scheme in `trustedOrigins`**, as `frontend://`. After the callback, the backend
    redirects the browser to the app's `callbackURL` (`frontend://.../login`), with the session in
    a `cookie` query parameter. Better Auth refuses a callback URL that matches no trusted origin.

package/src/docs/versioned/next/how-to/set-up-terreno-mcp.md

@@ -1,7 +1,7 @@
 # Set up Terreno MCP
 
-Connect your editor to both Terreno MCP servers:
-
+Configure both Terreno servers: the hosted server supplies documentation and generators; the local
+stdio server inspects the app, database, logs, Metro, and SyncDB state.
 - **`terreno`** (hosted, Streamable HTTP) supplies documentation search and code generators.
 - **`terreno-local`** (stdio, runs in your repository) reads the app's packages, database, logs,
   Metro, and client state.

package/src/docs/versioned/next/how-to/track-upstream-expo.md

@@ -33,7 +33,7 @@ State files (in the repo, not linked from this page):
 
 ## 2. Branch name
 
-Expo `58.0.0-preview.1` → `release-58.0.0`. Create from `origin/master` the
+Expo `58.0.0-preview.2` → `release-58.0.0`. Create from `origin/master` the
 first day. Later days check it out, merge `master`, and either bump to a
 newer preview or resume **Open** items from the log.
 

package/src/docs/versioned/next/how-to/upgrade-banner.md

@@ -25,10 +25,10 @@ This adds the public `GET /version-check` endpoint. The admin routes (`GET/PUT /
 
 ### 2. Frontend: Add build number injection
 
-Create or update `app.config.ts` in your Expo app root. Use the `resolveBuildNumber` helper from `@terreno/rtk/buildNumber`:
+Create or update `app.config.ts` in your Expo app root. Use the `resolveBuildNumber` helper from `@terreno/syncdb/buildNumber` (node-only, so import it only from `app.config.ts`):
 
 ```typescript
-import {resolveBuildNumber} from "@terreno/rtk/buildNumber";
+import {resolveBuildNumber} from "@terreno/syncdb/buildNumber";
 import type {ConfigContext, ExpoConfig} from "expo/config";
 
 export default ({config}: ConfigContext): ExpoConfig => ({
@@ -54,10 +54,12 @@ This sets `Constants.expoConfig.extra.buildNumber` when Metro loads the config.
 
 ### 3. Frontend: Wire up the hook
 
+`useUpgradeCheck` calls `/version-check` through the `@terreno/syncdb/api` request client,
+so render it inside `<ApiClientProvider client={apiClient}>` (or pass `{client: apiClient}`).
 In your root layout:
 
 ```typescript
-import {useUpgradeCheck} from "@terreno/rtk";
+import {useUpgradeCheck} from "@terreno/syncdb/app";
 import {UpgradeRequiredScreen} from "@terreno/ui";
 
 function RootLayoutNav() {

package/src/docs/versioned/next/how-to/upgrade-terreno.md

@@ -31,8 +31,8 @@ Or browse [`mcp-server/src/docs/upgrades/`](../../mcp-server/src/docs/upgrades/)
 | Clean git tree, work on a branch | Rollback is `git checkout -- .` / `git reset --hard` on that branch. |
 | Backend `@terreno/*` first | `/openapi.json` is the contract the frontend typed client is generated from. Regenerating against an old backend omits new routes; screens fail at compile. |
 | Backend compile + tests | Catch API breaks before touching Expo or UI. |
-| Expo SDK (if the Terreno major tracks a new Expo) | `@terreno/ui` pins `react-native` (for example `~0.86.0` on the 57 line in `ui/package.json` `peerDependencies`). Installing Terreno frontend packages before Expo leaves unmet peers. |
-| Frontend `@terreno/*` | UI, syncdb, admin-frontend, admin-spa, rtk. |
+| Expo SDK (if the Terreno major tracks a new Expo) | `@terreno/ui` pins `react-native` (for example `0.88.0-rc.1` on the 58 line in `ui/package.json` `peerDependencies`). Installing Terreno frontend packages before Expo leaves unmet peers. |
+| Frontend `@terreno/*` | UI, syncdb, admin-frontend, admin-spa. |
 | Regenerate typed client | Only after the **upgraded** backend is running. |
 | Compile, lint, tests | Whole app. |
 | Run the app | UI verification. |
@@ -42,11 +42,11 @@ Maintainers watching the next SDK beta use `track-upstream-expo` / [`track-upstr
 
 ### Backend vs frontend packages
 
-From `publish-on-tag.yml`: **backend** `api`, `test`, `admin-backend`, `blocks`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`. **frontend** `ui`, `rtk`, `syncdb`, `admin-frontend`, `admin-spa`. `blocks` holds contracts that both `ai` and `ui` depend on, so it moves with the backend step.
+From `publish-on-tag.yml`: **backend** `api`, `test`, `admin-backend`, `blocks`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`. **frontend** `ui`, `syncdb`, `admin-frontend`, `admin-spa`. `blocks` holds contracts that both `ai` and `ui` depend on, so it moves with the backend step.
 
-## 4. RTK → syncdb is not a version bump
+## 4. Crossing 58 removes `@terreno/rtk`
 
-If the range includes the syncdb release (`56.0.0-beta.2` and later), treat collection CRUD as a **platform migration**. Follow [migrate-rtk-to-syncdb.md](migrate-rtk-to-syncdb.md) in a separate change from the routine lockstep bump. Keep `@terreno/rtk` for the OpenAPI SDK, Better Auth, feature flags, and sockets until that migration is done.
+If the range crosses `58.0.0`, the app must drop `@terreno/rtk` and Redux: there is no 58 release of `@terreno/rtk`. Follow [How to upgrade from @terreno/rtk to @terreno/syncdb (Terreno 58)](migrate-rtk-to-syncdb.md) as part of the upgrade. Run the 58 data migrations before deploying 58 frontends.
 
 ## 5. Manual steps
 

package/src/docs/versioned/next/how-to/use-syncdb-correctly.md

@@ -2,7 +2,7 @@
 
 This page lists `@terreno/syncdb` behavior that a working app has to account for. Each entry says what the library does today, what breaks if you ignore it, and what to do instead. It was checked against `syncdb/src` and `api/src/sync` at 57.13.0. Several entries are library gaps rather than intended behavior. Delete an entry when its gap is fixed.
 
-Read [Local-first data](../explanation/local-first-data.md) and [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) first.
+Read [Local-first data](../explanation/local-first-data.md) and [How to upgrade from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) first.
 
 ## Startup and snapshots