@terreno/mcp 58.0.0-beta.4 → 58.0.1

package/src/docs/versioned/57.18.0/how-to/observe-llm-calls.md

@@ -1,197 +0,0 @@
-# Observe LLM calls
-
-Register observability on the backend. Registration **is** the feature flag. Then run product iteration in [Develop an AI feature](ai-feature-development.md).
-
-## Register
-
-```typescript
-import {access} from "./access";
-
-const priceMap = parseObservabilityPriceMap(process.env.AI_OBS_PRICE_MAP_JSON);
-
-server.register(new ObservabilityApp({
-  accessControl: access,
-  aiService,
-  plugins: [localPlugin, langfuseAdapter, otelSink].filter(Boolean),
-  control: {
-    datasets: process.env.AI_OBS_DATASETS_PRIMARY ?? "local",
-    experiments: process.env.AI_OBS_EXPERIMENTS_PRIMARY ?? "local",
-    prompts: process.env.AI_OBS_PROMPTS_PRIMARY ?? "local",
-    reviewQueue: "local",
-  },
-  priceMap,
-  sampleRate: Number(process.env.AI_OBS_SAMPLE_RATE ?? 0),
-}));
-```
-
-For an admin playground that accepts a user-supplied provider key, add
-`requestAiServiceFactory: ({apiKey, modelId}) => ...`. The playground route passes
-`x-ai-api-key` to that factory only when the server-wide `aiService` is absent. Never persist or
-log the key. `GET /ai/observability/status` exposes `playgroundAi.source` so admin UIs can block
-**Run once** with a host-specific hint (`request-key`) instead of surfacing the backend **503**
-missing-key title as a server misconfiguration.
-
-Validate the parsed object before registration: each model needs non-negative numeric
-`inputPerMTok` and `outputPerMTok`. The example implementation is
-`example-backend/src/utils/observabilityConfig.ts`; malformed values fail startup with the
-variable name.
-
-Keep existing `LangfuseApp` if you already use Langfuse keys. The Langfuse **adapter** must reuse `getLangfuseClient()` and must not start a second OpenTelemetry SDK.
-
-Boot **fails** if `experiments.primary !== datasets.primary`, if `reviewQueue` is `langfuse`, or if a primary’s plugin is missing.
-
-Pass the same `access` object you use for `TerrenoApp` and `AdminApp` so
-`GET /ai/observability/status` permissions match `/admin/config` screen filtering and every
-observability route enforces RBAC.
-
-### Example consumer roles
-
-The example backend seeds two optional roles in `example-backend/src/rbacRoles.ts`. They are
-**not** assigned automatically — attach them in the admin **Roles** UI or on `User.roles`.
-
-| Role | Grants |
-| --- | --- |
-| `aiObservabilityViewer` | `admin:access` plus `list` and `read` on all six observability resources |
-| `aiObservabilityOperator` | `admin:access` plus every approved action on those resources |
-
-Compose your own roles the same way: grant `admin: ["access"]` for the admin shell, then add
-only the `aiPrompt` / `aiTrace` / `aiReview` / `aiDataset` / `aiEvaluator` / `aiExperiment`
-actions each persona needs. Prompt `folder` and `description` stay consumer-defined metadata —
-Terreno does not ship domain-specific folder names or an in-app approval workflow.
-
-## Env
-
-| Variable | Role |
-| --- | --- |
-| `AI_OBS_PROMPTS_PRIMARY` | `local` or `langfuse` (default `local`) |
-| `AI_OBS_DATASETS_PRIMARY` | default `local` |
-| `AI_OBS_EXPERIMENTS_PRIMARY` | must equal datasets |
-| `AI_OBS_SAMPLE_RATE` | `0`–`1`, default `0` (live evals off) |
-| `AI_OBS_PRICE_MAP_JSON` | `{ "gemini-2.5-flash": { "inputPerMTok": 0.1, "outputPerMTok": 0.4 } }` |
-| `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | existing Langfuse plugin |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | optional OTLP trace sink |
-
-## App generate calls
-
-Pass identity and the production prompt ref so traces feed the SOP loop:
-
-```typescript
-await aiService.generateText({
-  prompt: text,
-  promptLabel: "production",
-  promptName: "example-summarize",
-  sessionId: req.header("x-ai-session-id"),
-  userId: req.user?.id,
-});
-```
-
-Opt out of tracing with `skipTrace: true`. Sink failures are logged and never fail the generate. `AIRequest` is still written.
-
-## Admin
-
-Phase 1 admin ships **Prompts**, **Traces**, and **Review**. Datasets, Evaluators, and
-Experiments screens arrive in phase 2. **Open in Langfuse** appears in phase 3 when the
-Langfuse plugin is registered. Review is hidden when the local plugin is off.
-
-On **Traces**, **Run multi-stage trace test** (local sink only) runs two schema-backed
-`generateJsonObject` calls, a deterministic tool stage, and a final schema-backed combine
-call, then opens the nested trace. Each LLM span input includes `outputSchema`. It uses the
-server `aiService` when one is configured; otherwise it sends the admin's saved key as
-`x-ai-api-key` to `requestAiServiceFactory`, and the button stays disabled with a hint until
-that key exists.
-
-## Run the example locally
-
-1. Set `MONGO_URI` to a replica set and the auth secrets from
-   `example-backend/.env.example`.
-2. Run `bun run backend:seed`. The idempotent seed creates `examples/example-summarize`
-   v1 with `production` pointing to v1 and candidate v2, plus the human
-   `correctness-human` evaluator, automatic `schema-assert` evaluator, and
-   two-item `example-gold` dataset. It also creates `chat-safety-synthetic` (12 proofread
-   two-person chats), `chat-safety-screen` v1 and v2, and the `chat-safety-agreement`
-   evaluator. On a database that already booted, run Admin → Scripts →
-   `seedChatSafetyDataset` as a wet run, or
-   `cd example-backend && bun run script seedChatSafetyDataset --wet`.
-3. Start `bun run backend:dev` and `bun run frontend:web`, then sign in as the seeded
-   admin.
-4. Open **AI Observability → Prompts** to inspect or save a new immutable version. Move
-   `production` explicitly; the seed never overwrites an existing label.
-5. Configure `GOOGLE_VERTEX_PROJECT` or `GEMINI_API_KEY`, then sign in with Better Auth
-   and call the seeded route:
-
-   ```bash
-   API=http://localhost:4000
-   COOKIE_JAR="$(mktemp)"
-   curl -sS -c "$COOKIE_JAR" \
-     -H "Content-Type: application/json" \
-     -d '{"email":"admin@example.com","password":"testpassword123"}' \
-     "$API/api/auth/sign-in/email" >/dev/null
-
-   curl -X POST "$API/ai/example-summarize" \
-     -b "$COOKIE_JAR" \
-     -H "Content-Type: application/json" \
-     -H "x-ai-session-id: docs-walkthrough" \
-     -d '{"text":"Terreno records local nested traces for every AI call."}'
-   ```
-
-6. Open its `example-summarize` trace, send it to Review, score **correct**, and submit
-   until the queue reports **Queue clear**.
-
-The example app also calls this route from the UI: **Todos → Summarize** sends the user's todo
-list, so each press produces a trace with the production prompt reference, `userId`, and a
-per-app-run `x-ai-session-id`. Without server credentials the screen forwards the Gemini key
-saved in **Profile** as `x-ai-api-key`; otherwise the route answers **503**.
-
-The route sends `text` as the user prompt. The labelled registry version supplies the
-system prompt and the route uses `TemperaturePresets.LOW`.
-
-The example registers the local plugin even when no Langfuse keys exist. Set
-`AI_OBS_PRICE_MAP_JSON` to calculate USD cost; unlisted models show tokens with no cost,
-never `$0`.
-
-## Create a prompt and pin production
-
-Admin-only routes live under `/ai/observability`. Create the prompt in a folder, save later edits as `vN+1` (v1 stays immutable), then move `production` — the response names the outgoing version for the confirm modal.
-
-```bash
-# 1. Create v1 in a folder
-curl -X POST "$API/ai/observability/prompts" \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"folder":"examples","name":"example-summarize","system":"Summarize {{text}}","template":"{{text}}","type":"text"}'
-
-# 2. Pin production (first pin has no outgoing version)
-curl -X POST "$API/ai/observability/prompts/example-summarize/labels" \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"label":"production","version":1}'
-
-# 3. Save as v2, then move production (response.outgoingVersion is 1)
-curl -X POST "$API/ai/observability/prompts/example-summarize/versions" \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"system":"Summarize {{text}} in one sentence","template":"{{text}}","type":"text"}'
-curl -X POST "$API/ai/observability/prompts/example-summarize/labels" \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"label":"production","version":2}'
-```
-
-`GET /ai/observability/prompts?folder=examples&search=sum&include=usage7d` lists folder matches with 7-day call/cost rollups. A prompt with no `production` label returns `production: "—"`. Playground `POST /ai/observability/prompts/:name/playground` compiles `{{var}}`, runs one `AIService` call, and does not create a version.
-
-The example backend registers `requestAiServiceFactory` but no server `aiService`, so status reports
-`playgroundAi.source: "request-key"`. In **AI Observability → Prompts → Playground**, save a Gemini
-API key on **Profile** first; the admin UI blocks **Run once** with that hint until the key loads
-from storage and is sent as `x-ai-api-key`. **Traces → Run multi-stage trace test** uses the same
-saved key and is blocked the same way.
-
-## Review a trace
-
-1. Use the seeded human `correctness-human` evaluator. If you skipped `bun run backend:seed`,
-   install it once with `POST /ai/observability/evaluators/templates/correctness-human`; a
-   duplicate install returns 409.
-2. Enqueue traces: `POST /ai/observability/traces/review` with `{evaluatorId, traceIds, reason: "manual"}`.
-3. List oldest-first: `GET /ai/observability/review?status=pending` (response includes per-status counts).
-4. Open an item: `GET /ai/observability/review/:id` returns evaluator dimensions plus `given` / `wrote` panels (variable labels when present, otherwise raw keys).
-5. `POST /ai/observability/review/:id` with `action: "submit"` writes dimension-keyed scores through every ScoreSink and marks the item `done` (it leaves the pending list). `skip` and `assign` move status to `skipped` / `in_progress`.
-

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

@@ -1,82 +0,0 @@
-# Password reset and email verification
-
-Wire JWT recovery routes and Better Auth to `@terreno/comms` mail, then add a reset screen.
-
-## 1. User schema
-
-1. Apply `emailVerificationPlugin` so `emailVerified` defaults to false.
-2. Add `tokenEpoch` (number, default 0) so password reset can invalidate refresh tokens.
-
-```typescript
-import {emailVerificationPlugin} from "@terreno/api";
-
-userSchema.plugin(emailVerificationPlugin);
-```
-
-## 2. JWT `authOptions`
-
-Set `publicAppUrl` and `sendMail`. Forgot-password always returns 202.
-
-```typescript
-authOptions: {
-  publicAppUrl: process.env.FRONTEND_URL || "http://localhost:8082",
-  // Set false if the host already owns POST /resetPassword.
-  legacyResetPasswordRoute: false,
-  sendMail: async (message) => {
-    await getCommsService().sendMail(message);
-  },
-  requireEmailVerification: false,
-}
-```
-
-Pass the `message` through unchanged. Recovery mail carries `sensitive: true`, and `@terreno/comms` stores no payload for a sensitive message, so the reset or verify link never reaches the `CommsMessage` log or the admin Comms Dashboard. If you send through another transport, do not log or store the content of a message with `sensitive: true`.
-
-| Action | Path | Body |
-| --- | --- | --- |
-| Forgot | `POST /auth/forgotPassword` | `{email}` → 202 |
-| Reset | `POST /auth/resetPassword` or `POST /resetPassword` | `{token, password}` or `{token, newPassword}` |
-| Send verify | `POST /auth/sendVerification` | authenticated → 202 after delivery; 501 if `publicAppUrl` is missing |
-| Verify | `POST /auth/verifyEmail` | `{token}` |
-
-Recovery routes default on for compatibility. Set `authOptions.passwordReset: false` to omit
-both password-reset routes and forgot-password. Set `authOptions.emailVerification: false` to
-omit both verification routes. Set `authOptions.legacyResetPasswordRoute: false` when the host
-owns `POST /resetPassword`; `POST /auth/resetPassword` remains registered.
-
-Reset links: `${publicAppUrl}/resetPassword?token=...`. Verify links: `${publicAppUrl}/verifyEmail?token=...`.
-
-Set `requireEmailVerification: true` to return 403 `email-not-verified` on JWT login until verify succeeds. Signup still returns JWTs and sends the verify mail.
-
-## 3. Comms templates
-
-```typescript
-import {renderAuthMail} from "@terreno/comms";
-
-const mail = renderAuthMail({
-  publicAppUrl: "https://app.example.com",
-  templateId: "resetPassword",
-  token,
-});
-```
-
-Pass `templates` to override subject/text/html. Variables: `resetUrl`, `verifyUrl`, `publicAppUrl`, `token`.
-
-## 4. Better Auth
-
-On `BetterAuthConfig` set the same `publicAppUrl`, `sendMail`, and `renderAuthMail` from `@terreno/comms`. That wires `sendResetPassword` and `sendVerificationEmail` to those templates. Those hooks do not send (they throw 501) when `publicAppUrl` is empty.
-
-## 5. Frontend
-
-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.
-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.
-
-A new `issueFor` for the same user and type invalidates earlier unused tokens of that type. Changing the mailbox through `PATCH /auth/me` invalidates unused `passwordReset` tokens even when the User schema has no `emailVerified` field. When `emailVerificationPlugin` is applied, mailbox change also sets `emailVerified` to false and invalidates unused `emailVerification` tokens. Letter casing alone does not count as a mailbox change. `emailVerified` and `tokenEpoch` are privileged user fields: signup and `PATCH /auth/me` drop them, along with the password fields `hash` and `salt`.
-
-To set a password from your own server code (for example an admin action), call `changeUserPassword(user, password, {adminId, app: req.app})` from `@terreno/api` so the change revokes sessions the same way a reset does. The example backend's `POST /users/:id/password` uses it.
-
-Either reset path also ends the user's MCP credentials: `mcp_` service tokens and MCP OAuth grants issued before the reset stop working, because they are bound to `tokenEpoch`. With `CommsApp` registered, push also stops going to devices the user registered before the reset until each device registers again.
-
-Better Auth password reset revokes that user's Better Auth sessions (`revokeSessionsOnPasswordReset`) and, when an app User exists, updates the JWT password and `tokenEpoch` so `POST /auth/login` cannot keep the old passport hash. JWT `POST /auth/resetPassword` does the reverse for Better Auth when `BetterAuthApp` is registered: it updates the Better Auth password and deletes Better Auth sessions. Console mail in development prints length only; check `CommsMessage` / console adapter logs for delivery, not the raw token in logger output. Request logs redact password, token, secret, and code fields (any key name, any depth) in bodies and in URL query strings.

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

@@ -1,160 +0,0 @@
-# Product announcements
-
-Use `@terreno/announcements` on the backend and `AnnouncementNavigator` on the frontend to show admin-managed update surfaces.
-
-## Backend
-
-1. Register the plugin on your `TerrenoApp`:
-
-```typescript
-import {AnnouncementsApp} from "@terreno/announcements";
-
-new AnnouncementsApp({
-  defaultAcknowledgementPolicy: "dismiss-only",
-  uploadToken: process.env.ANNOUNCEMENTS_UPLOAD_TOKEN,
-  // audienceType staff/patient/all is applied inside the plugin via matchAudienceByType.
-  isStaff: (user) => (user as {admin?: boolean}).admin === true,
-  matchAudience: (user, announcement) => {
-    const audience = announcement.audience as {organizationIds?: string[]};
-    if (!audience.organizationIds?.length) {
-      return true;
-    }
-    const userOrganizationIds = (user as {organizationIds?: string[]}).organizationIds ?? [];
-    return audience.organizationIds.some((organizationId) =>
-      userOrganizationIds.includes(organizationId)
-    );
-  },
-});
-```
-
-Use admin `audienceType` for staff vs patient vs all. Reserve the `audience` JSON field for custom segments (orgs, tiers, feature cohorts) in `matchAudience`. Do **not** call `matchAudienceByType` in your app — the plugin composes it before your callback.
-
-When the admin shell uses Terreno RBAC without the legacy `user.admin` flag, pass the same read permission to the overview:
-
-```typescript
-new AnnouncementsApp({
-  adminOverviewPermissions: [access.permission({adminAnnouncement: ["read"]})],
-});
-```
-
-For Flourish-style surfaces on one collection:
-
-| Audience | Typical `displayMode` | `acknowledgementPolicy` |
-|----------|----------------------|-------------------------|
-| `staff` | `modal` (blocking) | `required` |
-| `patient` | `banner` or `feed` | `dismiss-only` |
-| `all` | any | per announcement or `defaultAcknowledgementPolicy` |
-
-2. Create announcements in admin (draft → publish). Use `AnnouncementOverview`, `AnnouncementEditor`, and (optionally) `AnnouncementList` from `@terreno/admin-frontend` with dedicated Expo routes (see `example-frontend/app/admin/announcements/`). The built-in admin screen widget key `announcements` renders the overview when your host uses `AdminScreenRouter` for custom screens. Published `title`/`body` edits auto-increment `version`, which re-shows the surface to users who only acknowledged the previous version.
-
-For release-driven batches, use an [announcement release pack](../reference/announcement-release-packs.md). It keeps one `pack.yaml` manifest plus multiple Markdown announcements in source control, validates release and build versioning, and can import idempotent drafts or explicitly publish the whole pack through a dedicated bearer token. The example Cloud Run service accepts `Authorization: Bearer terreno-example-announcement-upload` (Terraform variable `announcements_upload_token`).
-
-### Admin editor fields
-
-`AnnouncementEditor` exposes structured targeting controls (no raw `requiresAcknowledgement` boolean):
-
-| Field | Control | Notes |
-|-------|---------|-------|
-| `displayMode` | Select | `modal`, `banner`, or `feed` |
-| `audienceType` | Select | `all`, `staff`, or `patient` — composed with `matchAudience` |
-| `acknowledgementPolicy` | Select | `required` or `dismiss-only`. On **create**, pre-filled from `GET /announcements/config` (`defaultAcknowledgementPolicy`); defaults to `dismiss-only` when config is unavailable |
-| `minBuildNumber` | Number (optional) | Minimum client build; cleared with `null` on edit when empty |
-| `platforms` | Multiselect | One or more of iOS, Android, and web; at least one is required |
-| `audience` | JSON textarea (advanced) | Opaque metadata for `matchAudience`; use audience type for staff/patient/all |
-
-### Admin overview
-
-`AnnouncementOverview` calls `GET /announcements/overview` (via RTK `injectEndpoints`) 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
-- A paginated table with per-row metrics and an edit action
-- Optional quick links to the raw acknowledgement, impression, and click-event admin tables
-
-Register the screen through `AnnouncementsApp.adminContribution()` (`customScreens: [{ name: "announcements", displayName: "Overview", group: "Announcements" }]`) and rely on `ANNOUNCEMENTS_ADMIN_WIDGETS` from `@terreno/admin-frontend` (merged into `BUILT_IN_SCREEN_WIDGETS`). Grouped custom screens appear in the **Announcements** sidebar group before model links; ungrouped screens stay under **Screens**.
-
-`AnnouncementList` remains available for a CRUD-style list; the overview is the launch dashboard.
-
-`AnnouncementEditor` uses `MultiselectField` for platforms and requires at least one platform before save.
-
-<img alt="Announcement overview with delivery metrics" src="/img/announcements/admin-overview.png" />
-
-<img alt="Platform multiselect in the announcement editor" src="/img/announcements/admin-editor-platforms.png" />
-
-## Frontend
-
-Wrap authenticated app content:
-
-```tsx
-import {AnnouncementNavigator} from "@terreno/ui";
-
-<AnnouncementNavigator api={terrenoApi}>
-  <AppTabs />
-</AnnouncementNavigator>
-```
-
-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
-
-| `displayMode` | Navigator behavior |
-|---------------|-------------------|
-| `modal` | Renders `AnnouncementScreen` and hides children until the announcement is cleared. |
-| `banner` | Keeps children mounted and renders `AnnouncementBanner` above them (one interrupt at a time). |
-| `feed` | Changelog-only; never shown by `AnnouncementNavigator` even if it appears unexpectedly in `pending.current`. |
-
-`AnnouncementBanner` composes the existing `Banner` component: title text, a dismiss or acknowledgement action, and an optional primary-action button. When used inside `AnnouncementNavigator`, primary CTA presses call `POST /announcements/:id/click` (via `useAcknowledgeAnnouncement().recordClick`) and then open the URL; tracking failures never block navigation.
-
-Acknowledgement policy still resolves to `requiresAcknowledgement` on the public DTO:
-
-| Policy | Banner / modal behavior |
-|--------|-------------------------|
-| `required` | Primary action is **Got it**, which acknowledges through the existing handler. |
-| `dismiss-only` | Dismiss records an impression only. |
-
-Impressions are recorded once per announcement version while the modal or banner is visible.
-
-## Client frequency caps
-
-Interrupt frequency is enforced **client-side** in `AnnouncementNavigator` before a modal or banner is shown. The server still returns the full pending queue; caps never filter `useAnnouncements` feed data.
-
-```tsx
-<AnnouncementNavigator
-  api={terrenoApi}
-  frequency={{
-    cooldownHours: 24,
-    skipFirstLaunch: false,
-    userId: currentUser?.id,
-  }}
->
-  <AppTabs />
-</AnnouncementNavigator>
-```
-
-`maxInterruptionsPerSession` defaults to `1` when omitted. The example app sets `skipFirstLaunch: false` so an announcement an admin publishes appears on the next launch.
-
-| Prop | Default | Behavior |
-|------|---------|----------|
-| `maxInterruptionsPerSession` | `1` | In-memory module session counter. After the cap is reached, pending interrupts are skipped until the JS runtime reloads (cold start / full app restart). Remounting `AnnouncementNavigator` alone does **not** reset the counter. |
-| `cooldownHours` | off | When set, skips interrupts if the last shown interrupt was within this many hours. Timestamp is persisted in AsyncStorage when an interrupt becomes visible. |
-| `skipFirstLaunch` | `false` | When `true`, the first app launch ever (no `hasLaunched` key) records the flag and skips interrupts for that launch only. |
-| `userId` | `"anon"` | AsyncStorage namespace for frequency keys when a signed-in user id is available. |
-
-When a cap applies, the navigator renders children (does not block the app) and does **not** record an impression. AsyncStorage read/write failures fail open with a `console.warn` and allow the interrupt to show. If `hasLaunched` cannot be persisted on first launch, the interrupt is shown and the in-memory first-launch skip is not armed for the rest of the session.
-
-Tests call `resetFrequencySessionStateForTests()` to simulate a cold start; that helper is not part of the production API.
-
-## Media in markdown
-
-Paste YouTube or Loom URLs in the announcement `body` using markdown links or images, for example `[Watch the demo](https://www.youtube.com/watch?v=...)`. `MarkdownView` renders them as embeds (iframe on web, WebView on native). Banner surfaces show the title only; use modal mode or the feed when the full body should be visible.
-
-## Example app
-
-`example-backend` registers `AnnouncementsApp` with `isStaff: (user) => user.admin === true` and an optional `matchAudience` org filter. `bun run backend:seed` idempotently seeds two **drafts**:
-
-- **Staff modal (required)** — `audienceType: "staff"`, `displayMode: "modal"`, `acknowledgementPolicy: "required"` (`Example staff operations bulletin`)
-- **Patient banner (dismiss-only)** — `audienceType: "patient"`, `displayMode: "banner"`, `acknowledgementPolicy: "dismiss-only"` (`Example patient care tip`)
-
-The seed keeps them as drafts so a fresh database (local dev or a PR preview) does not interrupt sign-in. Publish one from **Admin → Announcements** to see it. Re-running the seed updates both examples in place and sets them back to draft. The staff example is rich markdown with a YouTube embed, overview/editor screenshots, and a tracked docs CTA. An existing legacy welcome row (`Welcome to Terreno announcements`) is archived idempotently. `example-frontend` wraps authenticated users with `AnnouncementNavigator` (`skipFirstLaunch: false`, `userId` from the profile).
-
-Release notes in the example app use [`WhatsNewBanner`](./whats-new-banner.md) instead of announcements.

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

@@ -1,95 +0,0 @@
-# Rate limiting
-
-Turn on HTTP rate limiting for `@terreno/api` by passing `rateLimit` on `TerrenoApp`. The framework does **not** read `RATE_LIMIT_ENABLED`.
-
-Terreno 58 will default the limiter **on**. Until then, omit `rateLimit` to leave it off.
-
-## Terreno 58 (not this release)
-
-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).
-
-## Enable (memory)
-
-```typescript
-new TerrenoApp({
-  userModel: User,
-  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined,
-});
-```
-
-Empty `{}` is the same as `{store: "memory"}`.
-
-## 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:
-
-```typescript
-new TerrenoApp({
-  userModel: User,
-  rateLimit:
-    process.env.RATE_LIMIT_ENABLED === "true"
-      ? {store: "redis", trustProxy: 1}
-      : undefined,
-});
-```
-
-4. Install `ioredis` in the app that runs `@terreno/api` if it is not already a dependency.
-5. Missing `VALKEY_URL` / `REDIS_URL` fails **startup** when `store: "redis"` (clear `APIError`).
-
-## Stores
-
-| `store` | When to use | Config |
-| --- | --- | --- |
-| `memory` (default) | Single process | none |
-| `redis` | Shared bucket across replicas | `VALKEY_URL` then `REDIS_URL` |
-| `mongo` | Shared bucket without Redis | Open mongoose connection; collection `rateLimitHits` with TTL on `expiresAt` |
-
-## Mongo
-
-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.
-
-## Limit one route
-
-Use `createRouteRateLimitMiddleware` for a stricter limit on one expensive route. It works with or without the global limiter.
-
-```typescript
-import {createRouteRateLimitMiddleware} from "@terreno/api";
-
-const uploadLimit = createRouteRateLimitMiddleware({
-  name: "uploads",
-  max: 1,
-  windowMs: 60_000,
-  store: "mongo",
-});
-```
-
-`DocumentStorageApp` takes the same options as `uploadRateLimit`. The example backend allows one upload per IP per minute and sets `trust proxy` to `1` on Cloud Run so the key is the real client IP.
-
-## Auth vs API buckets
-
-| Path | Bucket |
-| --- | --- |
-| `POST /auth/login`, `/auth/signup`, `/auth/refresh_token` | auth (20 / 15 min) |
-| `POST /auth/forgotPassword`, `/auth/resetPassword`, `/resetPassword` | auth |
-| `POST /auth/sendVerification`, `/auth/verifyEmail` | auth |
-| `GET /auth/github`, `/auth/github/callback` | auth |
-| `{betterAuthBasePath}/sign-in/*`, `sign-up/*`, `forget-password`, `request-password-reset`, `reset-password`, `send-verification-email`, `verify-email`, `callback/*`, `oauth-handoff/*`, `one-time-token/*` | auth |
-| Trailing slash on those paths (`/auth/login/`) | same bucket as the unsuffixed path |
-| `GET`/`PATCH /auth/me` | api (600 / 15 min) |
-| modelRouter, admin, AI HTTP, `POST /mcp`, `POST /sync/mutate` | api |
-| `GET /health`, `/healthz`, `/openapi.json`, `/swagger` | skip |
-
-`rateLimit.skip` adds extra skips. Health/openapi/swagger always skip. Paths use Express `req.path` (not the raw request-target), without a trailing slash. Classification also resolves `.` and `..` segments, including `%2e` forms, the way Better Auth's router does: a request is charged to the auth bucket when either the path as sent or its resolved form is a credential route (so `/api/auth/%2e/sign-in/email` counts as sign-in), and a path that contains dot segments never gets the health/openapi/swagger skip.
-
-JWT login/signup/refresh and password-reset paths skip access-token verification so a stale `Authorization` header cannot block credential exchange. Other routes still 401 on an expired JWT. Path matching uses Express `req.path` and ignores trailing slashes and letter case.
-
-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/57.18.0/how-to/run-mongodb-migrations.md

@@ -1,127 +0,0 @@
-# Run MongoDB migrations
-
-Use `terreno-migrate` for schema and data changes that must run once per environment. Keep ad-hoc admin scripts for one-off maintenance.
-
-## Add a file
-
-Put TypeScript modules in `migrations/`:
-
-```text
-migrations/20260910120000-add-todos-index.ts
-```
-
-The exported `id` must match the filename stem. `up` is required; `down` is optional.
-
-```typescript
-export const id = "20260910120000-add-todos-index";
-
-export const up = async ({dryRun, mongoose}): Promise<void> => {
-  if (dryRun) {
-    return;
-  }
-  await mongoose.connection.collection("todos").createIndex({owner: 1});
-};
-
-export const down = async ({dryRun, mongoose}): Promise<void> => {
-  if (dryRun) {
-    return;
-  }
-  await mongoose.connection.collection("todos").dropIndex("owner_1");
-};
-```
-
-## First apply
-
-1. Generate a draft from the current models vs the last `schemaAfter` snapshot:
-   `terreno-migrate generate --dir ./migrations --models ./src/models.ts`
-2. Dry-run pending files (no history write):
-   `terreno-migrate up --dir ./migrations --dry`
-3. Apply for real:
-   `terreno-migrate up --dir ./migrations`
-4. In production, set `ALLOW_MIGRATIONS=true` and pass `--force` on that last command.
-
-If generate prints `No schema changes`, there is nothing to apply. Replace any fail-closed stub in the new file before step 2.
-
-## Commands
-
-`terreno-migrate` is the `@terreno/api` bin. `up`, `down`, and `status` need `MONGO_URI` or `MONGODB_URI`.
-
-| Command | Mongo | Effect |
-|---------|-------|--------|
-| `terreno-migrate check --dir ./migrations` | No | Load and validate files (CI) |
-| `terreno-migrate generate --dir ./migrations --models ./src/models.ts [--name slug]` | No | Diff current models vs last `schemaAfter`; write one file or print `No schema changes` |
-| `terreno-migrate status --dir ./migrations` | Yes | List applied and pending ids |
-| `terreno-migrate up --dir ./migrations [--dry] [--force]` | Yes | Apply pending `up` in filename order |
-| `terreno-migrate down --dir ./migrations [--dry] [--force] [--steps N]` | Yes | Roll back the last `N` applied files (default 1) |
-
-`--dry` calls `up`/`down` with `dryRun: true` and does **not** write `terreno_migrations` history. Authors must no-op writes when `dryRun` is true.
-
-`down` fails with `Migration has no down` when the target file omits `down`. History stays unchanged.
-
-## What generate can emit
-
-`buildSchemaCatalog` / `diffSchemaCatalog` classify model changes. `terreno-migrate generate` writes one file per non-empty diff:
-
-| Diff | Safe? | Generated `up` |
-|------|-------|----------------|
-| Add optional field | Yes | Snapshot only (Mongo is schemaless); comment, no write |
-| Add / drop non-unique index | Yes | `createIndex` / `dropIndex`, skipped when `dryRun` |
-| Add required field (no default) | No | Fail-closed stub that throws in dry-run and wet until you write a backfill |
-| Unique index | No | Fail-closed stub (valid JavaScript `throw`) |
-| Rename (removed + added field, same type) | No | Fail-closed stub |
-| Remove field | No | Fail-closed stub |
-| Same-path type change | No | Fail-closed stub |
-
-A file with any unsafe op is still a throw stub (dry-run and wet). Safe `createIndex` /
-`dropIndex` calls are kept as comments in that stub and listed in the throw message.
-
-Do not inspect the live database during generate. Baseline is the last `schemaAfter` snapshot in `migrations/`.
-
-## Admin HTTP
-
-Pass `migrations: {dir: "./migrations"}` into `AdminApp`. Both routes are
-`modelRouter` collection actions under the `adminMigrations` OpenAPI tag, so they appear in
-`/openapi.json` and in generated SDKs. Then:
-
-| Method | Path | Gate | Effect |
-|--------|------|------|--------|
-| GET | `/admin/migrations/status` | `admin:access` (or `IsAdmin`) | Applied, pending, lock (`{data: ...}`) |
-| POST | `/admin/migrations/run?wetRun=true\|false` | `admin:runScripts` (or `IsAdmin`) | `{data: {taskId}}` — one BackgroundTask (`migrations:up`) |
-| GET/DELETE | `/admin/scripts/tasks/:id` | `viewBackgroundTasks` / `runScripts` | Poll or cancel that task |
-
-Dry-run and Apply use the same `admin:runScripts` gate as Scripts (`platformTools.runScripts`
-disables the buttons when the caller cannot run scripts). Status listing stays on
-`admin:access`. Collection-action permission denials are **405** (modelRouter). Admin wet
-in production still needs `ALLOW_MIGRATIONS=true` (**403**). The admin UI is
-**Migrations** under Platform (`/admin/__migrations` or `/console/__migrations`):
-status list plus Dry run / Apply pending. Task logs poll `GET /admin/scripts/tasks/:id`.
-
-## Example app
-
-`example-backend` keeps files in `migrations/` and wires `resolveExampleMigrationsDir()` into
-`TerrenoApp` and `AdminApp`. From `example-backend/`:
-
-```bash
-bun run migrate:check
-bun run migrate:status
-bun run migrate:up
-```
-
-Compiled deploys (`bun build --compile`, Cloud Run) cannot scandir `$bunfs`. The example
-Dockerfile copies `migrations/` to `/app/migrations` and sets `MIGRATIONS_DIR`. GET
-`/admin/migrations/status` returns **404** `Migration directory not found` when that path is
-missing, not a generic 500.
-
-
-## Production wet apply
-
-`NODE_ENV=production` wet `up`/`down` requires both:
-
-1. `ALLOW_MIGRATIONS=true`
-2. `--force`
-
-Dry-run is allowed in production without those. Non-production wet apply does not need `--force`.
-
-## History and lock
-
-Applied ids live in Mongo collection `terreno_migrations` (lock row `_id: "_lock"`). Do not wipe that collection in seed `--reset`. See [Seed a database](seed-a-database.md).