@terreno/mcp 57.11.0 → 57.13.0

package/src/docs/upgrades/57.13.0.md

@@ -0,0 +1,75 @@
+# Upgrading to 57.13.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/ai, @terreno/ui
+
+## Summary
+
+Agent replies can use rich blocks (stepper, checklist, gallery, list, card eyebrow, copy), and hosts with `uiBlocks` on offer them in the prompt by default. `DataTable` number and date columns render differently, `neutral500` is a slightly darker gray, and the admin Roles screen groups permissions by resource. `@terreno/api` adds a per-route rate limiter, and `DocumentStorageApp` can be opened to signed-in non-admins. Action is required only for hosts with `uiBlocks` on that still have native builds from before this release.
+
+## Breaking changes
+
+### Rich blocks are offered in the chat prompt by default
+
+**What changed**
+
+With `uiBlocks` on, the chat system prompt now offers `checklist`, `gallery`, `list`, card `eyebrow`, and `copy`, plus `stepper` when a host action has `handles: "stepper"`. A native build shipped before 57.13.0 cannot render those blocks and shows an error banner for a reply that uses them.
+
+**Why**
+
+Rich blocks make agent replies more useful, so new hosts get them without extra setup.
+
+**Migration**
+
+Keep the old catalog until every shipped native build is on 57.13.0 or later:
+
+```typescript
+// Before
+addGptRoutes(router, {aiService, uiBlocks: {hostActions}});
+
+// After (until old native builds age out)
+addGptRoutes(router, {aiService, uiBlocks: {hostActions, richBlocks: false}});
+```
+
+With `richBlocks: false` the prompt is the same as before. Validation accepts the new blocks either way.
+
+### `DataTable` number and date cells
+
+**What changed**
+
+`columnType: "number"` columns right-align cells and header. `columnType: "date"` cells format an ISO string or `Date` as Luxon `DATE_MED` (date only, local zone). Strings that are not ISO dates show as before.
+
+**Why**
+
+Numbers line up by digit, and raw ISO timestamps were hard to read.
+
+**Migration**
+
+To keep the old look for a column, render it with `customColumnComponentMap`:
+
+```typescript
+// Before
+{columnType: "date", title: "Created", width: 150}
+
+// After (keep the raw value)
+{columnType: "rawDate", title: "Created", width: 150}
+// with customColumnComponentMap={{rawDate: ({cellData}) => <Text>{String(cellData.value)}</Text>}}
+```
+
+## Deprecations
+
+None
+
+## New capabilities
+
+- `createRouteRateLimitMiddleware({name, max, windowMs, store?, keyBy?})` from `@terreno/api` for a fixed-window limit on one route.
+- `DocumentStorageApp` `access: "authenticated"` (non-admins see only `users/<userId>/`) and `uploadRateLimit`.
+- `scaleStepperHostAction`, `toggleChecklistHostAction`, `findAgentBlock`, and `runBufferedChatTurn` from `@terreno/ai`.
+- `SegmentedControl` `size="sm"`; `Box` `accessibilityState` and `accessibilityLiveRegion`.
+- The `neutral500` primitive is `#949494`. Override it with `setPrimitives({neutral500: "#9A9A9A"})` to keep the old gray.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- Send a chat prompt that asks for a checklist; on a current build it renders, and with `richBlocks: false` the agent replies with the old block types
+- Open a screen with a `DataTable` date column and check the dates read as `Oct 10, 2026`

package/src/docs/versioned/next/explanation/README.md

@@ -19,7 +19,7 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [Durable agent harness](durable-agent-harness.md) — Phases, checkpoints, and why the audit span shares the checkpoint transaction
 - [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
 - [Agent UI Asks](agent-ui-asks.md) — Why agent questions are client-side tool calls, the pause and resume round trip, why cards carry exact answers, the watch paths, asks vs blocks
-- [Agent UI blocks](agent-ui-blocks.md) — Why chat replies use a closed YAML catalog instead of free-form UI
+- [Agent UI blocks](agent-ui-blocks.md) — Why chat replies use a closed YAML catalog instead of free-form UI, why steppers and checklists call the server, and the rich-blocks rollout
 - [Authentication architecture](authentication.md) — Better Auth, JWT, and optional MCP service tokens
 - [Organization tenancy](organizations.md) — Optional Membership-backed tenancy, context, and isolation boundaries
 - [Configuration system](configuration-system.md) — Runtime configuration with database persistence

package/src/docs/versioned/next/explanation/agent-ui-blocks.md

@@ -9,19 +9,79 @@ in [Agent UI Asks](agent-ui-asks.md).
 The design record is
 [agent-ui-blocks.md](../implementationPlans/agent-ui-blocks.md). Pick executes that work as
 Phase 5 of [Agent UI Asks](../implementationPlans/agent-ui-asks.md).
+The stepper, checklist, gallery, list, card eyebrow, and copy additions are recorded in
+`docs/implementationPlans/agent-ui-rich-replies.md`.
 
 ## Why a closed catalog
 
 An agent that can emit arbitrary components can also emit styles, scripts, and layout the
 app theme does not own. The catalog is the list of `@terreno/ui` components the chat can
-paint: heading, text, metric, badge, divider, context, chart, table, actions, and the two
-layout blocks `columns` and `card`. Unknown
-keys and unknown block types fail validation, so a reply cannot smuggle a `style` object
-or a hex color.
+paint. Unknown keys and unknown block types fail validation, so a reply cannot smuggle a
+`style` object or a hex color.
+
+| Group | Blocks | Notes |
+| --- | --- | --- |
+| Text | `heading`, `text`, `context`, `callout`, `details` | `text` is markdown, including GFM tables |
+| Values | `metric`, `badge`, `divider` | |
+| Data | `chart`, `table` | Read an inline or `ref` dataset |
+| Media | `image`, `gallery`, `list` | Sources are `data:image`, `file:`, or an allowed `https` host |
+| Interactive | `actions` (`button`, `segmented`), `stepper`, `checklist` | Button actions: `reply`, `open`, `select`, `callback`, `copy` |
+| Layout | `columns`, `card` (optional `title` and `eyebrow`) | Leaf blocks only inside |
+| Escape hatch | `html` | Only with `uiBlocks.html`; sanitized before storage |
+
+Field rules for each block are in the [reference](../reference/blocks.md).
 
 The same pure functions run wherever a document is checked. `parseBlocks` and
-`validateBlocks` live in `@terreno/blocks`, which has no React and no Express. The renderer
-and the chat route will call them; they do not grow a second grammar.
+`validateBlocks` live in `@terreno/blocks`, which has no React and no Express. The renderer,
+the chat route, and the `terreno-blocks` CLI all call them; none grows a second grammar.
+
+## Why interactive blocks call the server
+
+A stepper that rescales a shopping list, or a checklist that remembers ticks, needs logic.
+Terreno does not give the document a shared `state` with `{{formula}}` bindings, and it does
+not run scripted html. Both need an expression language the theme and the validator cannot
+see into. Instead, an interactive block names a host callback, as a callback button does:
+
+| Interaction | Who runs it | Result |
+| --- | --- | --- |
+| Stepper − / + | Host action with `handles: "stepper"`, through `POST /gpt/actions` | The replacement stepper, swapped in by block id |
+| Checklist tick | Host action with `handles: "checklist"`, or the device when the checklist has no callback | The replacement checklist, or a local tick |
+| `copy` button | The device | Text on the clipboard; nothing reaches the server |
+
+The cost is one round trip per tap. The view disables the block while the call is pending, so
+fast taps are dropped, not queued, and a checklist tick cannot send ticks that miss the one
+before it. The gain is that the agent writes plain data, and the app's code decides what a
+tap means. `scaleStepperHostAction` and `toggleChecklistHostAction` in `@terreno/ai` cover the
+common case. They read the block the agent wrote from the stored history and never trust the
+tap request's copy of it. The history owner can still edit stored prompts, so an app whose
+numbers matter (prices, stock) registers its own action over its own data.
+
+Overrides live in client memory. A reload shows the agent's original block again.
+
+## Why photos come from a stored library
+
+A model cannot make a photo while it writes a reply, and an `https` image needs an
+`imageHosts` allowlist the model cannot know. The example app generates a photo library once
+per environment with the Vertex image model, stores it through `FileStorageService`, and gives
+the agent a `findPhotos` tool that returns `file:` ids. The reply cites ids; the client
+resolves each id to a signed URL. Generation cost and latency stay out of the chat turn, and
+every photo the user sees was made and stored ahead of time. See
+[Give the agent photos](../how-to/agent-ui-blocks.md#give-the-agent-photos).
+
+## Rollout: rich blocks are on by default
+
+`uiBlocks.richBlocks` defaults to `true`. The prompt then offers `checklist`, `gallery`,
+`list`, `card.eyebrow`, and `copy`, and offers `stepper` when a host action has
+`handles: "stepper"`. A stepper without such an action would have dead buttons, so the
+prompt does not mention it.
+
+The server and the web client upgrade together. A native build already in the app stores
+does not know the new blocks: a reply that uses them fails its validation and shows the
+error banner with the raw YAML. A host with such builds sets `uiBlocks.richBlocks: false`
+until they update. The prompt is then the same as before rich blocks. Validation still
+accepts the new blocks, so a stored reply that uses them still renders on new clients.
+A client-declared catalog version, so the server picks blocks per client, would remove that
+manual step; it is not built yet.
 
 ## Why the whole reply is YAML
 
@@ -49,9 +109,9 @@ another, which makes a small document able to expand in ways the limits cannot s
 
 | Layer | Owns |
 | --- | --- |
-| `@terreno/blocks` | Schema, parse, partial parse, validate, JSON Schema, prompt section, CLI, limits, error codes |
-| `@terreno/ui` | `BlocksView` for heading, text, metric, badge, divider, context, chart, table, actions, columns, and card. A select action changes the target chart or table dataset in that view. A segmented control starts on the option that matches that dataset. A callback stays disabled when `hostActions` is set and does not include its name. `GPTChat` `uiBlocks` renders assistant messages through `BlocksView`, including a spinner while the reply is still streaming. A `file:` image stays as alt text until `resolveImage` returns a URL. |
-| `@terreno/ai` | When `uiBlocks` is on: the chat system prompt, the post-stream `{blocks}` check, `AIDataset` storage, and `POST /gpt/actions`. `AIService.generateBlocks` returns one validated document outside a chat turn. |
+| `@terreno/blocks` | Schema, parse, partial parse, validate, JSON Schema, prompt section, `blockPlainText`, CLI, limits, error codes |
+| `@terreno/ui` | `BlocksView` renders every block in the catalog. A select action changes the target chart or table dataset in that view. A segmented control starts on the option that matches that dataset. A callback button or stepper stays disabled when `hostActions` is set and does not include its name; a checklist with such a callback ticks locally instead. A `copy` button writes the clipboard on the device. `GPTChat` `uiBlocks` renders assistant messages through `BlocksView`, including a spinner while the reply is still streaming, and swaps a block when a callback returns `{replace: "block"}`. A `file:` image stays as alt text until `resolveImage` returns a URL. |
+| `@terreno/ai` | When `uiBlocks` is on: the chat system prompt, the post-stream `{blocks}` check, `AIDataset` storage, and `POST /gpt/actions`. The opt-in `scaleStepperHostAction` and `toggleChecklistHostAction`. `AIService.generateBlocks` returns one validated document outside a chat turn. |
 
 Asks use the same package under `src/asks/`. A block shows something. An ask collects an
 answer and returns it to the agent.

package/src/docs/versioned/next/explanation/ai-workflows.md

@@ -49,9 +49,10 @@ Maintains centralized agent guidance and generates the matching configuration fo
 
 Rulesync generates native hooks from `.rulesync/hooks.json`. Biome checks changed files
 after edits and staged files before commits. At agent stop,
-`.rulesync/hooks/quality-check.sh` runs lint, TypeScript compilation, Knip, and
-dependency-cruiser. It keeps stdout machine-readable for each host and prevents
-retry-triggered Stop hooks from rerunning the commands.
+`.rulesync/hooks/quality-check.sh` runs `bun install --frozen-lockfile` when
+`node_modules/typescript` or any workspace package link is missing, then runs lint,
+TypeScript compilation, Knip, and dependency-cruiser. It keeps stdout machine-readable
+for each host and prevents retry-triggered Stop hooks from rerunning the commands.
 
 Existing findings are ratcheted so the checks reject new debt without requiring unrelated
 cleanup. See [Static analysis](static-analysis.md).

package/src/docs/versioned/next/explanation/example-coverage.md

@@ -16,14 +16,14 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | Admin panel (embedded) | yes — Admin plugin registration in `example-backend/src/server.ts` | yes — `example-frontend/app/admin/` | Expo routes wrap `@terreno/admin-frontend` screens. |
 | Admin SPA | yes — `AdminSpaServeApp` in `example-backend/src/server.ts` | n/a | Standalone SPA is served from the backend; not a frontend route. |
 | AI streaming chat | yes — `example-backend/src/api/ai.ts` (`addGptRoutes`) | yes — `example-frontend/app/(tabs)/ai.tsx` (`GPTChat`, optional `mascot`) | Empty-chat mascot is consumer-owned; the example fox is not a framework default. |
-| UI blocks | yes — `uiBlocks` with `repair: true` and `exportDataset` in `example-backend/src/ai/hostActions.ts`, wired from `example-backend/src/api/ai.ts`; `todoStats` in `example-backend/src/ai/tools.ts` stores a `ref` dataset | yes — `example-frontend/app/(tabs)/ai.tsx` (`uiBlocks`, dataset and action hooks, `hostActions` includes `exportDataset`) | e2e mocks a document with one inline and one `ref` chart. Steps: [agent-ui-blocks.md](../how-to/agent-ui-blocks.md). |
+| UI blocks | yes — `uiBlocks` with `repair: true`, `exportDataset`, and the opt-in `scaleStepper` and `toggleChecklist` callbacks in `example-backend/src/ai/hostActions.ts`, wired from `example-backend/src/api/ai.ts`; `todoStats` in `example-backend/src/ai/tools.ts` stores a `ref` dataset; `findPhotos` in the same file cites the generated photo library, and `example-backend/src/api/photoLibrary.ts` signs its URLs | yes — `example-frontend/app/(tabs)/ai.tsx` (`uiBlocks`, dataset and action hooks, `hostActions` includes `exportDataset`, `scaleStepper`, and `toggleChecklist`, `resolveImage` resolves `file:` photo ids through `useLazyPhotoLibraryUrlQuery`) | e2e mocks a document with one inline and one `ref` chart. A second e2e test stores the Sunday roast reply (`blocks/src/fixtures/golden/sunday-roast.yaml` with `file:` photo ids) in a real `GptHistory`, streams it from the mocked model, and runs the stepper and checklist through the real `POST /gpt/actions`; photo URLs come from the real `GET /photoLibrary/:id/url`, and only the image download is stubbed (`example-frontend/e2e/helpers/seedGptHistory.ts`). Steps: [agent-ui-blocks.md](../how-to/agent-ui-blocks.md). |
 | Agent asks | yes — `asks: {approvals}` in `example-backend/src/api/ai.ts`, with the per-request `deleteCompletedTodos` approval tool from `example-backend/src/api/todoTools.ts`; it also passes `chat` to `addGptHistoryRoutes` for the headless `pendingAsks` and `turn` endpoints; keyless scripted agent with short compact-surface replies in `example-backend/src/api/demoAgent.ts` | yes — `example-frontend/app/(tabs)/ai.tsx` (`onAskSubmit`, `askErrors`), helpers in `example-frontend/lib/gptAsks.ts` | Without `GEMINI_API_KEY`, "Help me pick a plan" asks a `choice` in chat, "Pick toppings" asks a `select: "many"` `choice` with an Other field, "Send the weekly report" and "Archive old chats" ask a `confirm` (the second `destructive`), "Draft an announcement" asks a `markdown` edit of a draft, "Fill in the invoice details" asks a `form` with eight typed fields, "Upload a receipt" asks for `files`, sent as uploads when `GCS_BUCKET` is set and as data URLs otherwise, and "Delete my completed todos" calls `deleteCompletedTodos`, which runs only after the user approves the server's destructive approval card. e2e: `example-frontend/e2e/ai-chat.spec.ts`. Small clients: the curl walkthrough in the how-to and the demo's watch-sized `SimpleAskCard` story. Steps: [agent-ui-asks.md](../how-to/agent-ui-asks.md). |
 | AI structured output | no | no | `@terreno/ai` supports structured generation; the example only streams chat. Recorded gap — not claimed by a current tutorial. |
 | Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
 | Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
-| Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/consents.tsx`, admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
+| Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/documents.tsx` (Consents section), admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
 | Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
-| File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts`, `file-uploads` flag in `example-backend/src/api/fileUploads.ts` | yes — `example-frontend/app/(tabs)/files.tsx`, `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/app/gcs-settings.tsx` | The `file-uploads` feature flag hides upload controls and rejects uploads when off. A missing flag leaves uploads enabled. |
+| File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts`, `file-uploads` flag in `example-backend/src/api/fileUploads.ts` | yes — `example-frontend/app/(tabs)/documents.tsx` (Files section, every signed-in user, 1 upload / IP / min), `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/app/gcs-settings.tsx` | The `file-uploads` feature flag hides upload controls and rejects uploads when off. A missing flag leaves uploads enabled. Deployed bucket is terraform-managed (`google_storage_bucket.example_documents`). |
 | Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
 | syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |
 | SyncDB diagnostics | n/a | yes — `debug` registration in `example-frontend/store/syncdb.ts`, debugger UI at `example-frontend/app/syncdb-debug.tsx` | `terreno-mcp-local` can inspect, snapshot/compare/merge, mutate, flush, reconcile/resync, and exercise offline/conflict paths against the running development client. |

package/src/docs/versioned/next/explanation/roadmap-process.md

@@ -402,7 +402,7 @@ do not claim completion until done.
 | Workflow | Trigger | Purpose |
 | -------- | ------- | ------- |
 | [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present; `area:*` / `type:*` labels the issue was opened with win, so `roadmap:sync` issues are not asked for an area |
-| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when it changes |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when roadmap content changes. A new **Last updated** timestamp alone does not open a pull request |
 | [`.github/workflows/roadmap-sync.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
 | [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, add an entry for every new IP, open its tracking issue, push to the board, regenerate `ROADMAP.md` |
 All three share the `roadmap` concurrency group. They write the same board, and interleaving
@@ -495,4 +495,6 @@ GITHUB_TOKEN=$(gh auth token) TERRENO_PROJECT_NUMBER=... bun run roadmap:generat
 ```
 
 The generator exits non-zero when the project cannot be read, so a bad project number or a
-token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`.
+token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`. When the
+rendered list matches the file already on disk, it keeps that file's **Last updated** stamp
+and does not write. The daily workflow then sees a clean diff and does not open a pull request.

package/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -1319,6 +1319,18 @@ One easy-to-use harness inside `@terreno/ai` that runs long-lived agentic work d
 
 ---
 
+## agent-ui-rich-replies
+
+**Title:** `Agent UI Rich Replies: steppers, checklists, galleries, and copy`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`agent-ui-rich-replies`, Status=`Planned`
+
+- **Implementation plan:** [agent-ui-rich-replies.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/agent-ui-rich-replies.md)
+- **Tasks:** [agent-ui-rich-replies.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/tasks/agent-ui-rich-replies.md)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

package/src/docs/versioned/next/how-to/README.md

@@ -53,6 +53,8 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Add a GPT chat mascot](add-gpt-chat-mascot.md) — Optional consumer-owned character on empty `GPTChat`
 - [Add agent asks to a chat](agent-ui-asks.md) — Turn on `asks`, show and answer them in `GPTChat`, try the keyless demo agent, and answer asks from an Apple Watch or another small client
 - [Validate a block document locally](agent-ui-blocks.md) — `terreno-blocks validate` for a whole-reply YAML document
+- [Add a stepper callback](agent-ui-blocks.md#add-a-stepper-callback) — `scaleStepperHostAction` or your own `handles: "stepper"` action; checklist ticks, copy buttons, the `richBlocks: false` opt-out, and the `blocks:smoke` model check are on the same page
+- [Give the agent photos](agent-ui-blocks.md#give-the-agent-photos) — Generate a stored photo library once and let the agent cite it with `findPhotos`
 
 ## Admin
 

package/src/docs/versioned/next/how-to/agent-ui-blocks.md

@@ -14,9 +14,17 @@ The same check is `validateBlocks` in `@terreno/blocks`. Field tables are in the
 ## Preview a document in the playground
 
 1. Open the component demo and choose **BlocksPlayground**.
-2. Start from Layout or Invalid, or paste your own document into the text area.
+2. Start from a preset: **All blocks** (one of each block type), **Block type** (one preset per
+   block type, with every chart kind, callout status, and action kind), Layout, Invalid, or
+   Sunday roast. Or paste your own document into the text area.
 3. The preview updates as you type. An invalid document shows the error banner and keeps
    the raw text collapsed.
+4. Press the controls. The playground has no server: a stepper's − and + and a checklist tick
+   run on the device with `scaleStepperBlock` and `applyChecklistState` from `@terreno/blocks`
+   (the helpers `scaleStepperHostAction` and `toggleChecklistHostAction` use), and a toast names
+   the callback and its result, such as "scaleStepper → 6 People". A reply, open, select, or
+   other callback shows a toast describing the event instead. Copy writes the clipboard.
+   Editing the text drops the local results.
 
 ## Require documents from the model
 
@@ -72,6 +80,133 @@ addGptRoutes(router, {
 
 The path is `/gpt/actions`, so a limiter on `/gpt` covers it. Each call is stored as an `AIRequest` with `requestType: "ui_action"`.
 
+## Add a stepper callback
+
+A `stepper` is a − value + control. Each tap goes to a host action, and the action returns the
+replacement stepper. Use it when a number changes other numbers, such as guests changing a
+shopping list.
+
+1. Register a stepper action. `scaleStepperHostAction` from `@terreno/ai` scales every item
+   linearly from the stepper the agent wrote:
+
+   ```ts
+   import {addGptRoutes, scaleStepperHostAction} from "@terreno/ai";
+
+   addGptRoutes(router, {
+     aiService,
+     uiBlocks: {hostActions: {scaleStepper: scaleStepperHostAction}},
+   });
+   ```
+
+2. Leave `uiBlocks.richBlocks` unset (it defaults to `true`). The prompt offers `stepper` only
+   when some host action has `handles: "stepper"`, and names those actions as its callbacks.
+3. List the same name in `GPTChat` `hostActions` (`["scaleStepper"]`). `onBlockCallback` posts
+   to `POST /gpt/actions` and returns the result, as in [Wire the example chat](#wire-the-example-chat).
+4. The agent writes a stepper whose `callback.name` is that action:
+
+   ```yaml
+   - type: stepper
+     id: guests
+     label: Number of people
+     unit: People
+     value: 5
+     min: 1
+     max: 20
+     callback: {name: scaleStepper}
+     items:
+       - {label: Bone-in leg of lamb, amount: 2, unit: kg, decimals: 1}
+       - {label: Carrots, amount: 8, round: up}
+   ```
+
+5. Press +. The client sends `payload: {...callback.payload, value: 6}`, with `blockId: guests`
+   and `elementId: guests_increase`. The action returns `{replace: "block", blocks}` and
+   `GPTChat` swaps the stepper: lamb reads "2.4 kg", carrots "10". Both buttons are disabled
+   until the reply lands, so a fast second tap is dropped.
+
+A stepper whose `callback.name` is not a `handles: "stepper"` action fails `UNKNOWN_HOST_ACTION`.
+`value` outside `min`–`max`, or off the `step` grid, returns 400.
+
+**Stored prompts are owner-writable.** The history owner can change any stored prompt with
+`PATCH /gpt/histories/:id`, including the stepper `scaleStepperHostAction` reads. When the numbers
+matter (prices, stock, dosage), write your own action and compute them from your own data:
+
+```ts
+import {findAgentBlock, type HostAction} from "@terreno/ai";
+import {z} from "@terreno/api";
+
+const priceGuests: HostAction = {
+  handles: "stepper",
+  logResponse: false, // keep the returned block out of the AIRequest log
+  payload: z.object({value: z.number().int().min(1).max(20)}).passthrough(),
+  handler: async ({blockId, history, messageId, payload, user}) => {
+    const stepper = findAgentBlock({blockId, history, messageId, type: "stepper"});
+    const {value} = payload as {value: number};
+    const items = await quoteItems({guests: value, userId: user._id}); // your data, not the stored block
+    return {replace: "block", blocks: {v: 1, blocks: [{...stepper, items, value}]}};
+  },
+};
+```
+
+`findAgentBlock` reads `history.prompts[n]` for `messageId: msg-<n>`, otherwise the only assistant
+prompt holding that block: several matches throw 409, none 404. Field rules are in
+[Stepper](../reference/blocks.md#stepper) and [Host actions](../reference/ai.md#host-actions).
+
+## Add a checklist callback
+
+A `checklist` without a `callback` ticks on the device only. To send ticks to the server:
+
+1. Register `toggleChecklistHostAction` (or your own `handles: "checklist"` action) under a name,
+   such as `toggleChecklist`, and list it in `GPTChat` `hostActions`.
+2. The prompt then tells the model to set `callback: {name: toggleChecklist}` on a checklist.
+3. A tick sends `{...callback.payload, itemId, checked, state}`, where `state` holds every item's
+   tick after this one. The whole checklist is locked until the reply lands, and the "n of m"
+   counter changes when the returned checklist arrives.
+
+`toggleChecklistHostAction` returns the stored checklist with `checked` from `state` and saves
+nothing. An unknown item id returns 400. An app that records progress writes its own action.
+
+## Copy a block's text
+
+Add a button with `action: {kind: copy, target: <block id>}` (or `text` for a literal). The
+target is a `stepper`, `checklist`, `list`, `table`, or `text` block. `BlocksView` copies the
+block as it is shown now, so a stepper at 6 copies the scaled amounts. Nothing reaches the
+server, so `hostActions` does not apply. See [Copy](../reference/blocks.md#copy).
+
+## Keep the old catalog for shipped native builds
+
+Rich blocks (`stepper`, `checklist`, `gallery`, `list`, `card.eyebrow`, `copy`) are in the prompt
+by default. A native build released before them shows an error banner for a reply that uses
+them. Until those builds update, turn them off:
+
+```ts
+addGptRoutes(router, {aiService, uiBlocks: {hostActions, richBlocks: false}});
+```
+
+The prompt is then the same as before rich blocks, even with a stepper action registered.
+Validation still accepts the new blocks.
+
+## Smoke-test a real model
+
+`bun run blocks:smoke` (from the repo root) sends "Give me a plan for a sunday lamb roast, I'm
+having friends over still figuring out numbers tbh" through one real chat turn with the example
+backend's `uiBlocks` options and the `findPhotos` tool.
+
+| Check | Passes when |
+| --- | --- |
+| Document | The reply parses and passes `validateBlocks` |
+| Blocks | It holds a `gallery`, `list`, `stepper`, and `checklist`, and a `copy` action |
+| Photos | Every image `src` is a `file:` id that `findPhotos` returned in that turn |
+
+| Variable | Use |
+| --- | --- |
+| `GOOGLE_VERTEX_PROJECT` (with Application Default Credentials) or `GEMINI_API_KEY` | The model. With neither, the script prints that it skipped and exits 0 |
+| `BLOCKS_SMOKE_MODEL` | Optional model id instead of the server default |
+| `MONGO_URI`, `MONGO_DB_NAME` | The database holding the photo library ([Give the agent photos](#give-the-agent-photos)) |
+| `BLOCKS_SMOKE_OUT_DIR` or `--out <dir>` | Where `reply.yaml` and `result.json` go (default: a new temp directory) |
+
+It exits 1 when any check fails. The turn runs as `blocks-smoke@system.invalid`, and its history
+is deleted afterwards.
+
 ## Wire the example chat
 
 1. Turn `uiBlocks` on in `addGptRoutes` so `GET /gpt/datasets/:id` and `POST /gpt/actions` are in the OpenAPI spec.
@@ -84,11 +219,57 @@ The path is `/gpt/actions`, so a limiter on `/gpt` covers it. Each call is store
 
 ## Turn blocks on in the example backend
 
-`example-backend` passes `uiBlocks` with `repair: true` and one host callback, `exportDataset`. Its payload is `{dataset: string}`. The handler returns `{replace: "block", blocks}` with a badge that names that dataset. Dataset TTL stays at the default, so stored rows are kept.
+`example-backend` passes `uiBlocks` (`exampleUiBlocksOptions` in `src/ai/hostActions.ts`) with
+`repair: true`, `html: true`, and three host callbacks:
+
+| Name | Handles | Does |
+| --- | --- | --- |
+| `exportDataset` | buttons | Payload `{dataset: string}`. Returns a badge that names that dataset |
+| `scaleStepper` | `stepper` | `scaleStepperHostAction` |
+| `toggleChecklist` | `checklist` | `toggleChecklistHostAction` |
+
+`richBlocks` is left at its default (`true`). Dataset TTL stays at the default, so stored rows are kept.
 
 The per-request tool `todoStats` counts the signed-in user's open and completed todos, calls `registerAiDataset`, and returns `datasetId`. It stores the rows on `req.body.historyId` when that id belongs to the caller. With no history id it uses the caller's newest history, and with no history it returns `{datasetId: null, rowCount: 0}`. A chart dataset uses `source: ref` and that id. Columns are `status` and `count`.
 
-`GPTChat` lists `exportDataset` in `hostActions`, so that callback stays enabled. The e2e mock also allows `export_csv`.
+`GPTChat` lists `exportDataset`, `scaleStepper`, and `toggleChecklist` in `hostActions`, so those callbacks stay enabled. The e2e mock also allows `export_csv`.
+
+## Give the agent photos
+
+The model cannot make photos on the fly, and an `https` image needs `imageHosts`. The example
+app generates a photo library once, and the agent cites its photos as `file:` ids.
+
+1. Generate the library, once per environment. From `example-backend`, with `GOOGLE_VERTEX_PROJECT`,
+   Application Default Credentials for Vertex, and `GCS_BUCKET` set, run `bun run photos:generate`.
+   Each prompt in `src/scripts/photoPrompts.ts` becomes one `PhotoLibraryEntry`. A re-run skips
+   prompts that already have an entry; pass `--force` to regenerate them. `PHOTO_IMAGE_MODEL`
+   (default `imagen-4.0-fast-generate-001`) and `GOOGLE_VERTEX_LOCATION` (default `us-central1`)
+   are optional.
+2. Register the `findPhotos` tool. `createFindPhotosTool()` from `src/ai/tools.ts` is in the
+   example's per-request tools. `findPhotos({query, count})` matches the query words against each
+   entry's `tags` and `alt`. `count` is 1–6. It returns `{photos: [{src: "file:<entry id>", alt}], note}`.
+   Entries that match more words come first; ties keep entry id order. Soft-deleted entries are
+   left out. When nothing matches, `photos` is empty and `note` tells the model not to invent an
+   id. The tool description tells the model to put each `src` into a `gallery`, `list`, or
+   `image` block exactly as returned.
+3. Serve the URLs. `photoLibraryRouter` (`src/api/photoLibrary.ts`) mounts `/photoLibrary`.
+   List and read need a signed-in user; create, update, and delete return 405.
+   `GET /photoLibrary/:id/url` returns `{url}`, a signed read URL that lasts one hour, to any
+   signed-in user. The library is shared, so the per-user `GET /files/*` route does not fit.
+   An unknown or soft-deleted id is 404. Without a bucket (`GCS_BUCKET` unset and none saved in
+   Profile) it returns 503 `Photo storage is not configured`.
+4. Regenerate the frontend SDK: `cd example-frontend && bun run sdk`. This adds
+   `useLazyPhotoLibraryUrlQuery`.
+5. Pass `resolveImage` to `GPTChat`. The example builds it with `createPhotoImageResolver`
+   (`example-frontend/lib/photoLibraryImages.ts`) around `openapi.useLazyPhotoLibraryUrlQuery`.
+   It fetches each id once while the URL is fresh (50 minutes). A failed lookup returns
+   `undefined`, so the block keeps its labelled placeholder, and a later render tries again.
+
+In the example app, every `file:` image id in a block is a photo library entry id. Nothing else
+in the example writes `file:` image ids, so the ids carry no extra prefix. A host that also cites
+its own files must tell the two apart in its `resolveImage`. An id that is not in the library,
+such as `file:roast-lamb` in the reference examples, resolves to `undefined` and shows the
+placeholder.
 
 ## Render documents in chat
 
@@ -100,5 +281,8 @@ is true, finished top-level blocks render and a spinner marks the block still ar
 - `callback` calls `onBlockCallback`. Return `{replace: "block", blocks}` to swap that
   block, or `{text}` to append an assistant message. The button shows loading until the
   promise settles.
+- Stepper taps and checklist ticks with a callback also call `onBlockCallback`. The block is
+  disabled until the promise settles.
+- `copy` writes the clipboard on the device and calls nothing.
 - Pass `hostActions` to disable callbacks the host does not run, `resolveDataset` to
   load `ref` datasets, and `resolveImage` to turn a `file:` image id into a URL.

package/src/docs/versioned/next/how-to/circleci.md

@@ -179,6 +179,8 @@ an isolated `pr-N` backend: `deploy-frontend-preview` always points
 up to 20 minutes for its `/health` before publishing, because `gcp-cd-preview`
 runs in a separate workflow.
 
+Those backend deploys set `GCS_BUCKET` to `flourish-terreno-example-documents` (override with `GCP_DOCUMENTS_BUCKET`). Preview revisions also set `GCS_FOLDER_PREFIX=pr-<number>/` so each PR keeps its own folder. Without `GCS_BUCKET`, `GET /documents/` returns 503 and the Files section shows “Storage is not configured.”
+
 Backend previews prune not-Ready tagged revisions from traffic
 (`rebuild-cloud-run-ready-traffic.sh`), deploy untagged with
 `--revision-suffix`, then point the `pr-N` tag at that revision. Terraform
@@ -254,8 +256,12 @@ the review script so a PR cannot rewrite the reviewer.
 Netlify and GCP jobs **validate their context as the first step** and fail,
 before checkout or `bun install`, listing the missing variables. Preview jobs
 halt earlier on fork PRs, where CircleCI withholds contexts. Docker Layer
-Caching is off (200 credits per job). The docs Netlify target disables
-Docusaurus minification so the build stays within the 8 GB `large` executor.
+Caching is off (200 credits per job). The docs Netlify target builds only the
+current docs tree, disables Docusaurus minification, and pins SSG to one worker
+thread so the build peaks near 3 GB and fits the 4 GB `medium` executor.
+Released versions are not rebuilt: `archive-docs-version` (in `publish-release`,
+`X.Y.0` tags only) builds each one once and uploads it to its GitHub release, and
+`deploy-docs` unpacks those archives under `/<version>/`. See `website/README.md`.
 
 `terreno-gcp` uses CircleCI OIDC (`CIRCLE_OIDC_TOKEN_V2`), never a JSON service
 account key. Set `circleci_org_id`, `circleci_project_id`, and

package/src/docs/versioned/next/how-to/github-actions-ci.md

@@ -7,24 +7,23 @@ describes how they behaved if one is ever re-enabled.
 
 ## Docs site (`docs-deploy.yml`)
 
-`Build docs site` is often the longest PR job because Docusaurus compiles every
-versioned tree under `website/versioned_docs/` and TypeDoc regenerates API
-pages.
+`Build docs site` is often the longest PR job because TypeDoc regenerates API
+pages. The site builds only the current docs tree; `website/versioned_docs/` is
+markdown for the MCP server.
 
 PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
 `master` use Docusaurus Faster (Rspack/SWC via `@docusaurus/faster`).
 
 | Behavior | PR preview | `master` production |
 | --- | --- | --- |
-| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted (`disableVersioning`) | Built |
+| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted | Prebuilt archives unpacked under `/<version>/` |
 | JS minify | Off | On |
 | Local search index | Skipped | Built |
 | Generated API + component MDX | Restored from cache when `api`/`rtk`/`ui` hashes match | Same cache, then full generate on miss |
 | TypeDoc workspace `tsc` | Once per generate (api+rtk deps share a process) | Same |
 | Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
 
-Production still builds every version. Do not rely on `/57.1.0/…` URLs in a
-PR deploy preview.
+Do not rely on `/57.1.0/…` URLs in a PR deploy preview.
 
 ## Other high-cost jobs
 

package/src/docs/versioned/next/how-to/preview-demo.md

@@ -1,10 +1,10 @@
 # Preview a component demo
 
-Open a component demo and change the shareable query. The preview controls sit in the
-navigation header on demo and dev component routes: dropdowns for theme, viewport, and
+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. `?embed=1` applies the same query and hides
+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
@@ -13,11 +13,11 @@ the controls.
 
 | Query | Values |
 | --- | --- |
-| `theme` | `light` (default) or `dark` (canonical dark role remap) |
+| `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. Leaving the component route restores the app theme and, on web, document direction and reduced motion. Custom palettes stay on `/palette`.
+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/src/docs/versioned/next/how-to/rate-limiting.md

@@ -52,6 +52,23 @@ Pass `{store: "mongo"}`. Hits live in `rateLimitHits` on the same mongoose conne
 
 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 |