@terreno/mcp 57.12.0 → 57.14.0

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/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-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

@@ -47,12 +47,15 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
 - [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
+- [Use syncdb correctly](use-syncdb-correctly.md) — Serial snapshot startup, outbox-halting 403s, phantom creates, conflicts, and other library behavior apps must handle
 - [Generate a REST CLI from OpenAPI](generate-a-rest-cli.md) — Scaffold `terreno generate rest-cli` for an app API
 - [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
 - [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples
 - [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

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 |

package/src/docs/versioned/next/how-to/test-ui-accessibility.md

@@ -0,0 +1,35 @@
+# Test UI accessibility
+
+Run the WCAG scanner against every changed rendered state:
+
+```bash
+bun run accessibility:scan \
+  "http://localhost:8085/dev/Theme?story=ThemeComponent&theme=light" \
+  "http://localhost:8085/dev/Theme?story=ThemeComponent&theme=dark"
+```
+
+The scanner applies axe rules tagged WCAG 2.0 A/AA, WCAG 2.1 A/AA, and WCAG
+2.2 AA. It writes a JSON report and full-page screenshots under
+`/opt/cursor/artifacts/accessibility/` and exits nonzero when any violation is
+found.
+
+## Verify what automation cannot
+
+1. Use only the keyboard to reach and operate each changed control.
+2. Confirm focus order and the visible focus indicator match the visual order.
+3. Inspect each control's accessible name, role, state, and error relationship.
+4. Check light and dark modes, plus loading, empty, disabled, and error states
+   affected by the change.
+5. At 200% browser zoom, confirm content remains usable without clipping or
+   losing actions.
+
+Automated scans do not prove keyboard behavior, announcement quality, reading
+order, or whether alternative text conveys the intended meaning. Record those
+manual checks with the automated report in the pull request Verification table.
+
+## Fixing findings
+
+Fix violations in the changed feature before submission. If a finding is
+pre-existing and outside the changed path, capture a baseline on an unaffected
+route and name both routes in the pull request. Do not suppress an axe rule
+without a linked issue and a documented reason.

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

@@ -0,0 +1,111 @@
+# How to Use syncdb Correctly
+
+This page lists `@terreno/syncdb` behavior that a working app has to account for. Each entry says what the library does today, what breaks if you ignore it, and what to do instead. It was checked against `syncdb/src` and `api/src/sync` at 57.13.0. Several entries are library gaps rather than intended behavior. Delete an entry when its gap is fixed.
+
+Read [Local-first data](../explanation/local-first-data.md) and [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) first.
+
+## Startup and snapshots
+
+### Cold start costs one round trip per stream
+
+A stream is one collection in one scope, so a user has roughly (synced collections) × (tenants they belong to) streams. Each stream costs at least one `GET /sync/snapshot` round trip, even when it is empty. Reconcile, subscribe catch-up, `forceResync` and wipe re-bootstrap page up to `snapshotConcurrency` streams side by side (default 6). Each stream runs one pass at a time, and a pass that purges (force resync, wipe) waits for the stream's in-flight pass to finish first.
+
+Measured with a fake HTTP channel at 150 ms latency, 13 collections and 2 workspaces (26 streams): 4.1 s to the first full reconcile when paging one stream at a time, 0.95 s at the default concurrency.
+
+| Do | Why |
+| --- | --- |
+| Sync only the collections the client reads. | Each collection adds one stream per tenant to cold start. |
+| Gate each screen on its **own** stream's bootstrap (see [No loading flag on synced reads](#no-loading-flag-on-synced-reads)), not on "sync finished". | The stream a screen needs may land after others. |
+| Don't call `forceResync()` on a hot path. | It purges and re-pages every stream. |
+| Raise `snapshotConcurrency` only if the backend can take it. | Each in-flight stream is one concurrent snapshot query on the server. |
+
+The startup reconcile and each collection's `sync:subscribed` catch-up both page the same streams. A catch-up queues behind a pass that started before the room join, because that pass may have missed a write. So a cold start still pages each stream twice, one pass after the other.
+
+### No loading flag on synced reads
+
+`useQuery` returns a plain array. `useListQuery` returns `{data}`. The `isPending` on `useEntity`/`useReadQuery` means an outbox write is pending, not that data is loading. An empty array before bootstrap looks the same as an empty collection, so a screen that renders its empty state from `[]` flashes "nothing here" on every cold start.
+
+The per-stream `bootstrapped` mark is the right signal, but `isStreamBootstrapped` is not exported. Read the cell directly:
+
+```typescript
+const isBootstrapped = (stream: string): boolean =>
+  syncDb.store.raw.getCell("_cursors", stream, "bootstrapped") === true;
+```
+
+Don't use the cursor (`useSyncStatus().streams`) for this. A live delta can move the cursor to the head before the snapshot below it has been paged. `useWindowQuery` (query collections only) does expose `isLoading`.
+
+A stream key is `<collection>|<scopeType>:<value>`, for example `documents|tenant:<workspaceId>`. A user with several tenants has one stream per tenant. Treat a collection as loaded only once every known stream for it is bootstrapped (`syncDb.store.getKnownStreams()`).
+
+## Writes
+
+### Mutations return an id, not an outcome
+
+`create`, `update` and `remove` from `useMutate` (and from the generated `useCreate*`/`useUpdate*`/`useDelete*` hooks) return `{mutationId, id}` synchronously. There is no promise for the server ack. The client also drops the ack's `warning`. A `warning` means a server post-hook threw after the write committed.
+
+If a screen needs to know the outcome (close a modal only once the create landed, toast a refusal), wrap the transport and HTTP channel and record ack and nack outcomes by `mutationId`. Then await that `mutationId`. Don't poll the store.
+
+### A 403 from a write halts the whole outbox
+
+The server maps 403/405 to an `unauthorized` nack and 400/404/422 to `validation`. They behave very differently:
+
+| Nack | Client behavior |
+| --- | --- |
+| `unauthorized` | The mutation is re-queued and the **whole drain stops** (auth-pause). On re-auth the same `mutationId` replays, reads the same stored nack, and pauses again. It never settles. |
+| `validation` | The mutation is marked `failed` and the drain continues. That entity's later writes stay blocked until `retryFailed({entityId})`. |
+| `conflict` | That entity's later writes stay blocked (or every write is blocked, with `haltQueueOnConflict: true`) until `resolveConflict`. |
+| `error` | Retried up to the retry budget, then handled like `validation`. |
+
+So a router hook that refuses a synced write for a business reason must throw **422**, not 403. That includes `preCreate`/`preUpdate` membership checks. Keep 403 for real auth failures.
+
+### Don't send a stale tenant field on create
+
+For a tenant-scoped collection, `enforceWriteScope` checks a client-sent scope field (for example `workspaceId`) against the user's memberships **before** `preCreate` runs. A value the user does not belong to is a 403, which halts the outbox (see above). If the field is missing or null, the check is skipped and `preCreate` can fill it in.
+
+Either omit the tenant field and let `preCreate` set it, or send it only from the currently synced row of the parent tenant, never from a persisted id that may be stale.
+
+### The local row never gets server-computed fields from the create
+
+After an ack, the client stamps the row with the ack's seq and keeps the optimistic data. The server's create delta has the same seq, so the client skips it. Whatever `preCreate`, schema defaults or hooks set on the server does not reach the local row until that row changes again or is repaired. If the delta arrives before the ack, the row is marked for repair, but repair only runs on the next `reconcile()` (reconnect, seq jump, or every 5 minutes).
+
+Do one of these:
+
+- Send every field the UI reads in the create payload, matching what the server would compute (defaults, `order`, ownership fields).
+- After the ack, patch the local row yourself.
+
+The local row's `data` is exactly what you passed. Include `_id` in the payload if anything reads `row._id`. Server-written rows carry `_id` and `id`.
+
+### A refused create leaves a phantom row
+
+When a create is nacked as `validation` (or runs out of `error` retries), the repair fetch finds no server row and only clears the repair mark. The optimistic row stays in the store with `stream: ""` and shows up in queries. Only `forceResync` purges such rows.
+
+On a refused create, tombstone the local row yourself and call `retryFailed({entityId})` so later writes to that id are released.
+
+### Conflicts are never resolved for you
+
+A `conflict` nack blocks every later write to that row, and any queued write whose args mention its id, until someone calls `client.resolveConflict({mutationId, strategy: "keepMine" | "useServer"})` (or `useConflicts().resolve`). Local edits keep applying optimistically, so the UI looks fine while nothing reaches the server.
+
+If the app has no conflict UI, run a watcher that resolves each conflict as it is recorded. Use `keepMine` for fields the user types, and `useServer` for everything else.
+
+## Server side
+
+### Write synced models one document at a time, by `_id`
+
+On a synced model, `updateMany`, `deleteMany`, `deleteOne`, `findOneAndDelete` and `bulkWrite` throw. Single-document writes by `_id` without upsert are allowed: `save()`, `updateOne`, `findOneAndUpdate`, `findByIdAndUpdate`, `replaceOne`. Delete by setting `deleted: true`, because a hard delete emits no delta.
+
+In tests, clean up with `Model.collection.deleteMany(...)`, which bypasses Mongoose.
+
+### Deltas don't apply `queryFilter`
+
+Snapshots and `/sync/entities` apply the router's `queryFilter`. Live deltas check only `permissions.read` (or RBAC) per recipient. A router that restricts visibility only through `queryFilter` leaks rows over the socket. Every synced router's `read` permission must enforce the same restriction itself.
+
+### Membership grants arrive late
+
+A user's new tenant is picked up by the socket's session revalidation sweep (`sessionRevalidationIntervalMs`, 60 s by default) or a resubscribe. The client finds the new stream on its next `reconcile()` (`reconcileIntervalMs`, 5 minutes by default, plus reconnects). Until then the new tenant's rows don't appear.
+
+When the product grants membership, push a content-free event to the user's sockets and have the client reconnect syncdb. Reconnecting resubscribes and reconciles. Grants written another way (admin, scripts) still wait for the timers.
+
+## Auth
+
+### Logging out does not wipe local data
+
+The client's own `onAuthChange` handling treats a logout as a pause and **never wipes**. A different user logging in does wipe. To clear one user's data on sign-out, set `wipeOnSignOut: true` and call `client.signOut()` explicitly when the app's user clears.