@terreno/mcp 57.15.0 → 57.16.1

package/dist/docs/versioned/57.15.0/how-to/observe-llm-calls.md

@@ -0,0 +1,197 @@
+# 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/dist/docs/versioned/57.15.0/how-to/password-reset.md

@@ -0,0 +1,76 @@
+# 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,
+}
+```
+
+| 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.
+
+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`, `newPassword`, `oldPassword`, `token`, and `refreshToken` in bodies and in URL query strings.

package/dist/docs/versioned/57.15.0/how-to/preview-demo.md

@@ -0,0 +1,23 @@
+# Preview a component demo
+
+Open a demo or dev route and change the shareable query. The preview controls sit in the
+navigation header on every demo and dev screen, including the catalogs: dropdowns for theme, viewport, and
+background, plus a settings button (sliders icon) that opens a modal for right-to-left,
+reduced motion, locale, and the share query. In windows narrower than 768px every
+preview control moves into that modal; the Dev/Demo mode link stays in the header. The header chrome uses the same `theme` query. `?embed=1` applies the same query and hides
+the controls.
+
+```text
+/demo/Button?theme=dark&viewport=375&background=inverse&locale=en-US&rtl=1&reducedMotion=1
+```
+
+| Query | Values |
+| --- | --- |
+| `theme` | `light` (default), `dark`, or `system` (follow the device color scheme) |
+| `viewport` | `full` (default), `320`, `375`, `1024`, `1280` |
+| `background` | `default`, `inverse`, `transparent` |
+| `locale` | Passed to components that already read a locale, such as consent |
+| `rtl` | `1` sets document direction to `rtl` on web |
+| `reducedMotion` | `1` sets `data-reduced-motion="1"` on the document element |
+
+Reload keeps the query. The settings modal shows the current query when any value is not the default. Choosing a control's default removes that key from the URL. Opening a component from the catalog keeps the current preview query. Leaving a component route restores document direction and reduced motion on web. Custom palettes stay on `/palette`.

package/dist/docs/versioned/57.15.0/how-to/product-announcements.md

@@ -0,0 +1,158 @@
+# 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 seeded interrupts still appear on first 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:
+
+- **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 staff launch example is rich markdown with a YouTube embed, overview/editor screenshots, and a tracked docs CTA. Re-running the seed updates that example in place. An existing legacy welcome row (`Welcome to Terreno announcements`) is archived idempotently so it no longer blocks the patient banner. `example-frontend` wraps authenticated users with `AnnouncementNavigator` (`skipFirstLaunch: false`, `userId` from the profile); non-staff users therefore see only the patient banner interrupt under the default session cap of `1`.

package/dist/docs/versioned/57.15.0/how-to/rate-limiting.md

@@ -0,0 +1,95 @@
+# 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/*` | 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.
+
+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/dist/docs/versioned/57.15.0/how-to/run-harness-on-multiple-instances.md

@@ -0,0 +1,93 @@
+# Run the harness on multiple instances
+
+Run durable harness tasks on every instance of a scaled-out backend (for example several
+Cloud Run instances). Swap the default `InProcessRunner`, where one process drains every
+task, for `JobsRunner`, which runs each phase as a `@terreno/jobs` job. API:
+[AI harness reference → JobsRunner](../reference/ai-harness.md#jobsrunner). Why it is safe:
+[Durable agent harness → Runners](../explanation/durable-agent-harness.md#runners).
+
+You need a working harness (see [Build a durable workflow](build-a-durable-workflow.md)) and
+a MongoDB replica set. Task data does not change, so you can switch runners without a
+migration.
+
+## 1. Install the jobs package (1 minute)
+
+`@terreno/jobs` is an optional peer of `@terreno/ai`. Add it to the app:
+
+```bash
+bun add @terreno/jobs
+```
+
+## 2. Open the harness with a JobsRunner (5 minutes)
+
+Create the `JobsApp` first, hand it to the runner, and register it on the app. Build the
+app before the harness starts: `harness.start()` throws when no `JobsApp` is registered.
+The runner defines the `terreno.harness.phase` job on it.
+
+```typescript
+import {Harness} from "@terreno/ai/harness";
+import {JobsRunner} from "@terreno/ai/harness/jobsRunner";
+import {TerrenoApp} from "@terreno/api";
+import {JobsApp} from "@terreno/jobs";
+
+const jobs = new JobsApp();
+const harness = await Harness.open({
+  registry: [intakeSummary, summarizer],
+  runner: new JobsRunner({jobs}),
+});
+
+const app = new TerrenoApp({userModel: User}).register(jobs);
+// ...register HarnessApp and your routes, then build or start the server.
+app.start();
+
+await harness.start();
+await jobs.startWorker();
+```
+
+Shut down in the reverse order so phases in flight finish:
+
+```typescript
+await harness.stop(); // stops dispatching, waits for this instance's phases
+await jobs.stopWorker();
+```
+
+## 3. Run the same code on every instance
+
+Every instance runs the same startup. Each one:
+
+- scans for runnable tasks and enqueues one job per runnable phase (duplicates collapse on
+  the job's idempotency key),
+- runs phase jobs from the shared jobs queue, and
+- sweeps task leases that expired because an instance died.
+
+No instance is special, and none waits on standby.
+
+## 4. Check it works (2 minutes)
+
+1. Start two backend processes against the same database (different `PORT`s).
+2. Create a task (for the example backend, run `startClinicalIntake`).
+3. Open the admin **Jobs** screen. Each phase shows as its own `terreno.harness.phase` job
+   with payload `{taskId}`.
+4. Kill one process mid-phase. Within one lease (`leaseDuration`, default 30 s) the other
+   process replays a `replay: "safe"` phase, or parks any other phase as `interrupted`.
+
+## Tune it
+
+| Want | Set |
+| --- | --- |
+| Faster pickup of new work | `new JobsRunner({jobs, pollInterval: {milliseconds: 200}})` and `new JobsApp({pollIntervalMs: 200})` |
+| Faster crash recovery | A shorter `leaseDuration` with `heartbeatInterval` about a third of it |
+| Phases longer than the jobs lock TTL | Nothing: the task lease, renewed by heartbeats, decides who commits |
+
+## Troubleshoot
+
+- **Jobs fail with `harness-runner-stopped`.** A jobs worker runs on an instance whose
+  harness is not started. Start the harness before `jobs.startWorker()`. The jobs worker
+  retries the job, so no task is lost.
+- **`harness.start()` throws "JobsRunner needs a registered JobsApp".** The dispatcher
+  enqueues through the registered jobs service, and `TerrenoApp` registers plugins when it
+  builds. Call `app.start()` (or `build()`) before `harness.start()`.
+- **A task stays `pending`.** Check that its `name@version` is in the registry of the
+  running instances. A runner only dispatches registered versions.
+- **Pick one runner per database.** Mixing them is safe (every claim and commit is fenced),
+  but an `InProcessRunner` owner then claims tasks itself and runs them to a stop.