@terreno/mcp 57.2.0 → 57.3.0

package/dist/upgradeGuide.js.map

@@ -1 +1 @@
-{"version":3,"file":"upgradeGuide.js","sourceRoot":"","sources":["../src/upgradeGuide.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"upgradeGuide.js","sourceRoot":"","sources":["../src/upgradeGuide.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@terreno/mcp",
-  "version": "57.2.0",
-  "description": "MCP server for Terreno - provides documentation, tools, and prompts for building full-stack apps",
+  "version": "57.3.0",
+  "description": "MCP server that gives coding agents Terreno docs, codegen tools, and prompts — part of Terreno, the batteries-included TypeScript framework for universal apps.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.2.0",
+    "@terreno/api": "57.3.0",
     "express": "^5.2.1",
     "minisearch": "^7.2.0",
     "mongoose": "9.7.4"
@@ -56,5 +56,13 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/FlourishHealth/terreno/issues"
+  },
+  "homepage": "https://github.com/FlourishHealth/terreno#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/FlourishHealth/terreno.git"
   }
 }

package/src/docs/guidelines/admin-backend/guidelines/core.md

@@ -1,5 +1,13 @@
-## Admin Panel (backend)
+## Admin panel backend
 
-The backend uses `@terreno/admin-backend`'s `AdminApp` for auto-generated admin CRUD endpoints.
-All admin routes require `IsAdmin` permission and are mounted at `/admin`.
-Add models to `AdminApp` in `src/server.ts` to expose them in the admin panel.
+Read the architecture first:
+
+- `docs/explanation/admin-interface.md`
+- `docs/how-to/admin-add-model.md`
+- `docs/how-to/build-admin-screens.md`
+
+Put `admin` on `modelRouter`. Use plugin `adminContribution()` for plugin-owned
+models and screens. `AdminApp.customScreens` `name` must match the frontend widget
+key. `admin:access` opens `/admin/config`; model CRUD is not a substitute.
+
+Agent workflow: skill `building-admin-interfaces`.

package/src/docs/guidelines/admin-frontend/guidelines/core.md

@@ -1,10 +1,13 @@
-## Admin Panel Frontend
+## Admin panel frontend
 
-The frontend uses `@terreno/admin-frontend` components for the admin panel:
+Read the architecture first:
 
-- `AdminModelList` — entry screen listing all admin models
-- `AdminModelTable` — table view for a model with pagination
-- `AdminModelForm` — create/edit form (auto-generated from schema)
-- `ConfigurationScreen` — admin configuration editor
+- `docs/explanation/admin-interface.md`
+- `docs/how-to/build-admin-screens.md`
 
-Admin screens live in `app/(tabs)/admin/`. The panel reads metadata from `GET /admin/config`.
+Use `AdminProvider` + `AdminShellLayout`. Home is `AdminHome`. Generic models use
+`AdminScreenRouter` on `[model]/index` (create is `[model]/create`, not `new`).
+Custom screens need the same `name` on `AdminApp.customScreens` and
+`widgets.screens`. Admin HTTP uses `useAdminConfig` / `useAdminApi` (not syncdb).
+
+Agent workflow: skill `building-admin-interfaces`.

package/src/docs/guidelines/ui/guidelines/core.md

@@ -1,6 +1,6 @@
 ### @terreno/ui
 
-React Native component library with 88+ components:
+React Native UI component library (a large component library):
 
 - **Layout**: Box, Page, SplitPage, Card
 - **Forms**: TextField, SelectField, DateTimeField, CheckBox

package/src/docs/resources/overview.md

@@ -1,15 +1,39 @@
 # Terreno Overview
 
-A monorepo containing shared packages for building full-stack applications with React Native and Express/Mongoose.
+Terreno is Django/Rails for TypeScript — with universal app support.
+
+Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
+framework where the undifferentiated 80% of an app is already written. On the
+backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
+panel, authentication, and an AI service. On the frontend you get one universal
+app — a single React Native codebase that ships to iOS, Android, and web. It is
+built to be driven by AI coding agents from the first prompt to a production
+deploy.
+
+- Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
+  feature flags, and consent are already built, so your code is business logic.
+- Universal by default — one React Native codebase ships to iOS, Android, and
+  web. Not a web framework with a mobile bolt-on.
+- AI-native — agents are a first-class client of the framework, not an
+  afterthought.
+
+Terreno's AI-native story has two layers. The tool layer is a Model Context
+Protocol (MCP) server that gives coding agents codegen, documentation search,
+and component reference for the framework's conventions. The process layer is the
+`/terreno-*` SDLC pipeline — plan, implement test-first, verify in a fresh
+context, submit with evidence, then own the review loop — which today runs inside
+the Terreno repository while its consumer-installable packaging is finished.
+Django gives you `manage.py startapp`; Terreno is building a reviewed path from a
+request to a mergeable pull request.
 
 ## Packages
 
-- **@terreno/api** - REST API framework built on Express/Mongoose
-- **@terreno/ui** - React Native UI component library
-- **@terreno/syncdb** - Local-first data layer (primary path for collection CRUD)
-- **@terreno/rtk** - OpenAPI SDK, Better Auth Redux, feature flags (legacy for data sync)
-- **@terreno/ai** - AI service layer
-- **@terreno/admin-backend** / **@terreno/admin-frontend** / **@terreno/admin-spa** - Admin panel stack
+- **@terreno/api** — REST API framework for Express/Mongoose (modelRouter, auth, OpenAPI)
+- **@terreno/ui** — React Native UI component library for iOS, Android, and web
+- **@terreno/syncdb** — Local-first data layer (primary path for collection CRUD)
+- **@terreno/rtk** — OpenAPI SDK, Better Auth Redux, feature flags (legacy for data sync)
+- **@terreno/ai** — Provider-agnostic AI service
+- **@terreno/admin-backend** / **@terreno/admin-frontend** / **@terreno/admin-spa** — Admin panel stack
 
 New apps: **syncdb + Better Auth** for data and auth; **rtk** for generated SDK hooks on non-synced routes only.
 

package/src/docs/resources/ui.md

@@ -1,6 +1,6 @@
 # @terreno/ui Documentation
 
-Comprehensive React Native UI component library with cross-platform support (web, iOS, Android).
+React Native UI component library for one universal app (iOS, Android, and web).
 
 ## Installation
 

package/src/docs/templates/bootstrap/frontend/app/(tabs)/profile.template.tsx

@@ -1,39 +1,127 @@
-import {Box, Button, Heading, Page, Text} from "@terreno/ui";
+import {Box, Button, Card, Heading, Page, Spinner, TapToEdit, Text} from "@terreno/ui";
 import type React from "react";
-import {useCallback} from "react";
-import {useGetMeQuery} from "@/store/sdk";
-import {logout, useAppDispatch} from "@/store/index";
+import {useCallback, useEffect, useState} from "react";
+import {signOut} from "@/lib/betterAuth";
+import {logout, syncBetterAuthSession, useAppDispatch} from "@/store/index";
+import {useGetMeQuery, usePatchMeMutation} from "@/store/sdk";
 
 const ProfileScreen: React.FC = () => {
   const dispatch = useAppDispatch();
   const {data: profile, isLoading} = useGetMeQuery();
+  const [updateProfile] = usePatchMeMutation();
+  const [name, setName] = useState<string>("");
+  const [email, setEmail] = useState<string>("");
+  const [password, setPassword] = useState<string>("");
+  const [saveError, setSaveError] = useState<string | null>(null);
 
-  const handleLogout = useCallback((): void => {
+  const user = profile?.data;
+
+  // Copy the server name into local state without resetting an in-progress email edit.
+  useEffect(() => {
+    if (!user) {
+      return;
+    }
+    setName(user.name || "");
+  }, [user?.name]);
+
+  // Copy the server email into local state without resetting an in-progress name edit.
+  useEffect(() => {
+    if (!user) {
+      return;
+    }
+    setEmail(user.email || "");
+  }, [user?.email]);
+
+  const handleLogout = useCallback(async (): Promise<void> => {
+    await signOut();
     dispatch(logout());
+    await syncBetterAuthSession(dispatch);
   }, [dispatch]);
 
+  const handleSaveName = useCallback(
+    async (value: string): Promise<void> => {
+      setSaveError(null);
+      try {
+        await updateProfile({name: value}).unwrap();
+      } catch (err) {
+        console.error("Error updating name:", err);
+        setSaveError("Failed to update name");
+      }
+    },
+    [updateProfile]
+  );
+
+  const handleSaveEmail = useCallback(
+    async (value: string): Promise<void> => {
+      setSaveError(null);
+      try {
+        await updateProfile({email: value}).unwrap();
+      } catch (err) {
+        console.error("Error updating email:", err);
+        setSaveError("Failed to update email");
+      }
+    },
+    [updateProfile]
+  );
+
+  const handleSavePassword = useCallback(
+    async (value: string): Promise<void> => {
+      if (!value) {
+        return;
+      }
+      setSaveError(null);
+      try {
+        await updateProfile({password: value}).unwrap();
+        setPassword("");
+      } catch (err) {
+        console.error("Error updating password:", err);
+        setSaveError("Failed to update password");
+      }
+    },
+    [updateProfile]
+  );
+
   if (isLoading) {
     return (
       <Page navigation={undefined} title="Profile">
-        <Box padding={4}>
-          <Text>Loading...</Text>
+        <Box alignItems="center" flex="grow" justifyContent="center" padding={4}>
+          <Spinner />
         </Box>
       </Page>
     );
   }
 
   return (
-    <Page navigation={undefined} title="Profile">
+    <Page navigation={undefined} scroll title="Profile">
       <Box gap={4} padding={4}>
         <Heading>Profile</Heading>
-        <Box gap={2}>
-          <Text weight="bold">Name</Text>
-          <Text>{profile?.data?.name || "Not set"}</Text>
-        </Box>
-        <Box gap={2}>
-          <Text weight="bold">Email</Text>
-          <Text>{profile?.data?.email || "Not set"}</Text>
-        </Box>
+        <Card>
+          <Box gap={4}>
+            <TapToEdit
+              onSave={handleSaveName}
+              setValue={setName}
+              title="Name"
+              type="text"
+              value={name}
+            />
+            <TapToEdit
+              onSave={handleSaveEmail}
+              setValue={setEmail}
+              title="Email"
+              type="email"
+              value={email}
+            />
+            <TapToEdit
+              helperText="Leave blank to keep your current password"
+              onSave={handleSavePassword}
+              setValue={setPassword}
+              title="New Password"
+              type="password"
+              value={password}
+            />
+            {saveError && <Text color="error">{saveError}</Text>}
+          </Box>
+        </Card>
         <Box marginTop={4}>
           <Button fullWidth onClick={handleLogout} text="Logout" variant="outline" />
         </Box>

package/src/docs/upgrades/0.30.0.md

@@ -0,0 +1,119 @@
+# Upgrading to 0.30.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/api, @terreno/ui, @terreno/rtk, @terreno/feature-flags, @terreno/test, @terreno/ai, @terreno/admin-backend
+
+Per-release upgrade notes were not maintained from 0.22.0 through 0.30.0. This note consolidates consumer-facing changes for **0.21.0 → 0.30.0**. It does not replace later notes (`0.31.0.md`, `56.0.0-beta.2.md`, `57.x`). If you are jumping past 0.30.0, apply this note and then the later notes in order.
+
+OpenFeature (`GET …/evaluate` → `GET …/flagConfiguration`) shipped in 0.20.0 (`#761`) without an upgrade note. It is included here because the 0.21.0 README carried the only copy of the migration, and that section is no longer in the root README.
+
+## Summary
+
+Bump every `@terreno/*` package together to `0.30.0`. Most apps only need the SelectField prop rename and `APIError` field contract. Direct feature-flag HTTP clients must leave `/evaluate`. New packages (`@terreno/test`, later first publishes of `@terreno/ai` / `@terreno/admin-backend` / `@terreno/feature-flags`) are additive.
+
+## Breaking changes
+
+### `SelectField` `searchable` renamed to `disableSearch`
+
+**What changed**
+
+`@terreno/ui` `SelectField` no longer accepts `searchable`. Search is on by default. Pass `disableSearch` to turn it off. Commit `121b9b81` (`#954`, 0.28.0).
+
+**Why**
+
+The old default (`searchable={true}`) made “off” the thing you had to name. The new prop names the exception.
+
+**Migration**
+
+```tsx
+// Before
+<SelectField searchable options={options} value={value} onChange={onChange} />
+<SelectField searchable={false} options={options} value={value} onChange={onChange} />
+
+// After
+<SelectField options={options} value={value} onChange={onChange} />
+<SelectField disableSearch options={options} value={value} onChange={onChange} />
+```
+
+### `APIError` uses standard `Error` fields
+
+**What changed**
+
+`APIError.message` is exactly `title`. Put per-occurrence text in `detail` and wrapped errors in `cause`. Status subclasses (`NotFoundError`, `ForbiddenError`, …) exist. 0.28.0 `adde07d4` (`#949`); 0.30.0 `#967` preserves `status` / `title` / `detail` / `code` / `meta` when `modelRouter` rethrows.
+
+**Why**
+
+Sentry and log explorers group on `Error.message` / `name`. Concatenating `detail` into `title` split one problem type into many issues.
+
+**Migration**
+
+```typescript
+// Before
+throw new APIError({status: 400, title: `Todo ${id} failed: ${err.message}`});
+
+// After
+throw new APIError({
+  status: 400,
+  title: "Todo update failed",
+  detail: err.message,
+  cause: err,
+  code: "todo-update-failed",
+});
+```
+
+If you read `error.title` on the client, keep doing so for JSON:API bodies. Do not assume `message` contains `detail`.
+
+### Feature flags: stop calling `GET …/evaluate`
+
+**What changed**
+
+`GET {basePath}/flagConfiguration` is the supported bulk endpoint. `GET {basePath}/evaluate` is deprecated (`Deprecation: true`, `Sunset` header). Client path: `useTerrenoFeatureFlags` plus OpenFeature React hooks. Shipped 0.20.0 `#761`; documented on the 0.21.0 README; not previously in `mcp-server/src/docs/upgrades/`.
+
+**Why**
+
+The payload matches OpenFeature’s static configuration shape so `@openfeature/react-sdk` can evaluate on the client without a second targeting pass.
+
+**Migration**
+
+Full checklist: [Migrating from GET …/evaluate](../../../docs/how-to/add-feature-flags.md#migrating-from-get-evaluate-openfeature).
+
+```typescript
+// Before — hand-written client
+await fetch("/feature-flags/evaluate");
+
+// After — OpenFeature via @terreno/rtk
+import {useBooleanFlagValue} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags} from "@terreno/rtk";
+
+useTerrenoFeatureFlags(terrenoApi, {userId, skip: !userId});
+const enabled = useBooleanFlagValue("new-ui", false);
+```
+
+Install `@openfeature/react-sdk` and `@openfeature/web-sdk` in the app (peer versions from `@terreno/rtk`). Wrap readers in `<OpenFeatureProvider domain="feature-flags">`. `useFeatureFlags(terrenoApi)` still works and already uses `/flagConfiguration`.
+
+## Deprecations
+
+- `GET {basePath}/evaluate` on `@terreno/feature-flags` — use `/flagConfiguration` or `@terreno/rtk` hooks. See the how-to linked above.
+
+## New capabilities
+
+- `@terreno/test` (0.22.0 `#822` / `#823`): shared Bun helpers and in-memory Mongo. `@terreno/api` lists it as a runtime dependency from 0.22.2 (`#827`) so `@terreno/api/testing` resolves on isolated installs.
+- First npm publish of `@terreno/ai`, `@terreno/admin-backend`, `@terreno/feature-flags` at 0.22.1 (lockstep bump; `#824`).
+- `OpenApiMiddlewareBuilder.withOperationId()` (0.22.0 `#815`).
+- `Button` `ghost` / `sm` (0.22.0 `#816`).
+- Compound UI `testID`s (0.23.0 `#832` / `#840`).
+- Admin Script Runner CLI (0.23.0 `#828`).
+- `createAuthenticatedClient` / `normalizeApiError` / `withApiErrorHandling` exported from `@terreno/api` (0.25.0 `api/src/index.ts` `export * from "./httpClient"`).
+- `IconButton` `state?: "default" | "active"` (0.26.0 `#885`).
+- Signature capture fields (0.29.0 `#958`).
+- `ThumbsUpDownFeedback` (0.30.0 `#948`).
+
+Example-backend seed admin email is `admin@example.com` from 0.27.0 (`#935`); password unchanged. Internal barrel `index.ts` files are banned in this repo (0.26.0 `#907`) — only a consumer issue if you copied those internals.
+
+## Verification
+
+- `bun add` every `@terreno/*` dependency to `0.30.0` (do not mix with 0.21.x).
+- `bun run compile` and `bun run lint` at the app root.
+- Search the frontend for `searchable=` on `SelectField` — there must be none.
+- If you called `/feature-flags/evaluate` directly, switch to `/flagConfiguration` or `useTerrenoFeatureFlags`, then `cd <your frontend> && bun run sdk`.
+- Hit an error path and confirm the JSON:API `title` is stable and `detail` holds the occurrence text.

package/src/docs/upgrades/57.3.0.md

@@ -0,0 +1,146 @@
+# Upgrading to 57.3.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/api, @terreno/rtk, @terreno/ui, @terreno/comms, @terreno/admin-frontend, @terreno/mcp
+
+## Summary
+
+Bump every `@terreno/*` package together to `57.3.0`. This minor on the Expo SDK 57 line adds opt-in rate limiting, inbound webhooks, password reset / email verification, comms adapters (Twilio SMS, Twilio Verify, Expo push), a comms admin dashboard, `describeModel`, and `Popover`. Collection live updates through `modelRouter` `realtime` and `@terreno/rtk` cache-patch helpers are deprecated for removal in Terreno 58. No Expo upgrade is required if you are already on `57.x`.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+### `modelRouter` `realtime` and RTK cache-patch helpers
+
+These still work in 57.3.0 and will be removed in Terreno **58**:
+
+- `modelRouter` option `realtime`
+- `@terreno/rtk` `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`
+
+Migrate collection live updates to `sync` + `@terreno/syncdb`. Keep `RealtimeApp` registered — sync sockets still need it.
+
+See [migrate-rtk-to-syncdb.md](../../../docs/how-to/migrate-rtk-to-syncdb.md).
+
+## Changed behavior
+
+### Collection registry
+
+**What changed**
+
+`modelRouter` stores options in one in-memory catalog keyed by route path. MCP, realtime, and sync read that catalog. `replaceCollectionOptions` updates every surface at once. Test `clear*` helpers clear the whole catalog.
+
+**Why**
+
+MCP, REST, and sync were drifting onto separate option copies.
+
+**Migration**
+
+If tests called a per-surface `clear*` helper expecting other surfaces to stay registered, re-register routers after clear. Production apps that only call `modelRouter` once per path do not need a code change.
+
+### MCP writes use REST/Sync executors
+
+**What changed**
+
+MCP create, update, and delete run through `executeCreate` / `executeUpdate` / `executeDelete`. Permission denials and hook failures use `APIError` titles in the MCP error envelope. Invalid document `_id` values from `loadDocOr404` are 404, not populate `CastError`s. User-role stripping runs after hooks.
+
+**Why**
+
+MCP writes were a second mutation path that skipped REST/Sync permission and hook behavior.
+
+**Migration**
+
+```typescript
+// Before: MCP tools could surface CastError on a bad _id
+// After: treat invalid ids as 404 / APIError title in the MCP envelope
+```
+
+Update MCP clients that matched populate `CastError` strings. Hooks now see the same executor path as REST.
+
+### Heavy `@terreno/ui` screens are lazy
+
+**What changed**
+
+`GPTChat`, `MarkdownEditor`, `ConsentFormScreen`, `AIRequestExplorer`, and the other named exports from `lazyBoundaries/heavyOptionalExports` load through lazy boundaries. Named exports are unchanged.
+
+**Why**
+
+A root `@terreno/ui` import pulled those screens into every bundle.
+
+**Migration**
+
+Keep importing the same names from `@terreno/ui`. If a test or Metro config assumed those modules loaded synchronously at import time, wait for the lazy boundary (or import the concrete file in tests).
+
+### OpenAPI / admin / MCP field graphs come from `describeModel`
+
+**What changed**
+
+`getOpenApiSpecForModel`, admin `/admin/config` field metadata, and MCP Zod tool schemas format `describeModel()` instead of walking `schema.paths` separately. Map fields take their value kind from Mongoose `of` / `getEmbeddedSchemaType()` (not a date fallback).
+
+**Why**
+
+Three surfaces were inventing different types for the same schema.
+
+**Migration**
+
+Regenerate the frontend SDK (`bun run sdk`). If a Map field was typed as date in OpenAPI, expect the real value kind.
+
+### Better Auth-only realtime
+
+**What changed**
+
+Realtime sockets can authenticate with Better Auth only. A legacy JWT secret is no longer required for that path.
+
+**Migration**
+
+Better Auth apps can omit JWT token secrets for realtime. JWT apps are unchanged.
+
+### `oauthProvider` on email/password Better Auth users
+
+**What changed**
+
+Lazy User create no longer writes `oauthProvider: null` on email/password sign-up.
+
+**Why**
+
+`strict: "throw"` User schemas without that field returned 401 on the first authenticated request.
+
+**Migration**
+
+No action if the field is optional. If you queried `{oauthProvider: null}` for password users, query missing/`$in` instead.
+
+## New capabilities
+
+### Opt-in HTTP rate limiting
+
+Pass `rateLimit: {}` on `TerrenoApp` (memory default; `redis` or `mongo` for shared buckets). Auth credential routes: 20 / 15 minutes. Other framework HTTP: 600 / 15 minutes. Omit `rateLimit` to leave HTTP unlimited until Terreno 58. 429 uses `APIError` `code: "rate-limit-exceeded"`. `trustProxy` defaults off (set `1` on Cloud Run). See [rate-limiting.md](../../../docs/how-to/rate-limiting.md).
+
+### Inbound webhooks
+
+Register `WebhooksApp` for HMAC / Stripe / Twilio / SendGrid verification, raw-body capture, and idempotency. `CommsApp` can mount Twilio status/inbound and SendGrid Event Webhook routes on the same plugin. See [inbound-webhooks.md](../../../docs/how-to/inbound-webhooks.md).
+
+### Password reset and email verification
+
+JWT: `POST /auth/forgotPassword` (always 202), `POST /auth/resetPassword`, `POST /auth/sendVerification`, `POST /auth/verifyEmail`. Opt in with `emailVerificationPlugin`, `tokenEpoch`, `authOptions.publicAppUrl` / `sendMail`, and `@terreno/comms` `renderAuthMail`. Better Auth uses the same `publicAppUrl` and `sendMail`. `LoginScreen` accepts `onForgotPassword`. See [password-reset.md](../../../docs/how-to/password-reset.md).
+
+### Comms adapters and admin dashboard
+
+Optional peers: `TwilioSmsProvider` (`@terreno/comms/adapters/twilioSms`), `TwilioVerifyProvider` (`@terreno/comms/adapters/twilioVerify`), `ExpoPushProvider` (`@terreno/comms/adapters/expoPush`). Admin comms screens in `@terreno/admin-frontend` list delivery logs, retry, and provider failure rates.
+
+### `describeModel` and `Popover`
+
+`describeModel` / `describeModelForRouter` plus OpenAPI/admin/Zod converters are public in `@terreno/api`. `Popover` is new in `@terreno/ui`.
+
+### MCP docs `version`
+
+`terreno_search_docs` and `terreno_get_component_docs` accept `version` to search retained docs snapshots.
+
+## Verification
+
+- `bun add` every `@terreno/*` dependency to `57.3.0`, then `bun run compile` and `bun run lint` at the app root
+- `cd <your frontend> && bun run sdk` after pulling `@terreno/api` (schema metadata and new auth routes)
+- If you still pass `realtime` on `modelRouter` or use RTK `realtimeList` / `realtimeDocument`, start the syncdb migration before Terreno 58
+- If you enable `rateLimit`, confirm login 429s after 20 attempts / 15 minutes and that Cloud Run sets `trustProxy: 1`
+- If you add password reset, follow [password-reset.md](../../../docs/how-to/password-reset.md) and confirm forgot-password always returns 202

package/src/docs/upgrades/58.0.0.md

@@ -0,0 +1,9 @@
+# 58.0.0 (stub)
+
+This file is a placeholder until Terreno 58 is cut. When that release ships, expand this page into a full upgrade note.
+
+## HTTP rate limiting defaults on
+
+`TerrenoApp` will enable HTTP rate limiting by default (memory store unless you pass `store`). Apps that must stay unlimited must pass an explicit off once 58 defines that API.
+
+Until 58: omit `rateLimit` to leave the limiter off. See [Rate limiting](../../../docs/how-to/rate-limiting.md).

package/src/docs/upgrades/README.md

@@ -0,0 +1,78 @@
+# Upgrade notes
+
+Per-release notes for `terreno_get_upgrade_guide`. One file per published version: `<version>.md` (for example `57.2.0.md`). This README is format documentation only and is **not** concatenated into a version range.
+
+`terreno_get_upgrade_guide` concatenates every matching note in the requested range. Each note must be **self-contained** and must not assume the reader read an adjacent note.
+
+Existing notes such as `0.20.0.md` and `0.21.0.md` predate this template. Keep them as-is. New notes use the sections below. Extra sections are allowed; do not omit a required section — write `None` when a section has nothing to report.
+
+## Required header
+
+Start with the version heading, then these two lines:
+
+````markdown
+# Upgrading to <version>
+
+**Action required:** Yes | No
+**Affected packages:** @terreno/api, @terreno/ui
+````
+
+`Action required` is `Yes` when a consumer must change code, config, or dependencies. List only packages whose public surface the consumer must touch.
+
+## Required sections
+
+| Section | Purpose |
+| --- | --- |
+| Summary | One short paragraph of what this version does for a consumer |
+| Breaking changes | Each change is its own `###` heading with **What changed**, **Why**, and **Migration** (before-and-after code) |
+| Deprecations | What is still supported, until when, and the replacement |
+| New capabilities | Additions a consumer may opt into. Write `None` when there are none |
+| Verification | Concrete commands or checks that prove this version's upgrade succeeded |
+
+## Copy-paste template
+
+````markdown
+# Upgrading to <version>
+
+**Action required:** Yes
+**Affected packages:** @terreno/api
+
+## Summary
+
+<one paragraph>
+
+## Breaking changes
+
+### <change title>
+
+**What changed**
+
+<what a consumer sees>
+
+**Why**
+
+<reason, one or two sentences>
+
+**Migration**
+
+```typescript
+// Before
+oldCall();
+
+// After
+newCall();
+```
+
+## Deprecations
+
+None
+
+## New capabilities
+
+None
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- `cd <your frontend> && bun run sdk` after any `@terreno/api` route or model surface change
+````