@terreno/mcp 57.12.0 → 57.13.0

package/dist/docs/versioned/next/tasks/agent-ui-rich-replies.md

@@ -0,0 +1,188 @@
+# Task List: Agent UI Rich Replies
+
+**Status:** approved 2026-10-07. Start with T1 (or T19, which is independent).
+**IP:** [`docs/implementationPlans/agent-ui-rich-replies.md`](../implementationPlans/agent-ui-rich-replies.md). The contracts, acceptance criteria (AC1–AC14, including AC6b), and open questions are there.
+**Supporting skills:** `terreno-ui`, `terreno-backend-api`, `ai-prompt-governance`, `update-docs`, `verify-ui-changes`, `backend-test-env`.
+
+Two write chains share files, so their tasks are ordered.
+
+- **Contract chain:** T1 → T2 → T5 → T6 → T7 → T8 → T9. These write `blocks/src/schema.ts`, `limits.ts`, `lint.ts`, `prompt.ts`, fixtures, and `docs/reference/blocks.md`.
+- **Renderer chain:** T1 → T3 → T10 → T11 → T12 → T13 → T14. These write `ui/src/blocks/blockRenderers.tsx`, `BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, and the BlocksView section of `docs/reference/ui.md`.
+
+Each renderer task also waits for its own contract task. T4 sits in the renderer chain between T3 and T10 because it also edits `docs/reference/ui.md`. Every contract task that adds fixtures also edits `blocks/src/parse.test.ts` (`expectedInvalid`); invalid cases that need validate options go in `blocks/src/lint.test.ts`. Fixtures under `valid/` use `data:image` or `file:` image sources.
+
+### Phase 1: Tracer
+
+- [x] **T1** — Stepper block round trips through a host callback
+  - Depends on: none
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/errors.ts` (`OUT_OF_RANGE`), `blocks/src/lint.ts` (stepper `callback.name` in `UNKNOWN_HOST_ACTION`; reserved `<id>_increase` / `<id>_decrease` in `DUPLICATE_ID`), `blocks/src/fixtures/valid/stepper*.yaml`, `blocks/src/fixtures/invalid/stepper*.yaml`, `blocks/src/parse.test.ts`, `blocks/src/lint.test.ts`, `blocks/src/index.ts`; `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`; `ai/src/service/agentBlocks.ts` (`findAgentBlock`), `ai/src/service/agentBlocks.test.ts`, `ai/src/service/scaleStepper.ts`, `ai/src/service/scaleStepper.test.ts`, `ai/src/types/index.ts` (`handles?`, `logResponse?` on host actions), `ai/src/routes/gptActions.ts` (honour `logResponse: false`), `ai/src/routes/gptActions.test.ts`, `ai/src/index.ts`; `docs/reference/blocks.md`, `docs/reference/ai.md`, `docs/reference/ui.md`.
+  - Delivers:
+    - The `stepper` contract from the IP.
+    - The renderer: − value +, unit, `itemsTitle`, an items grid formatted with `decimals`, and the note. It emits the callback with `{...payload, value}`. Buttons are disabled at the bounds, while pending, and when the callback is not in `hostActions`.
+    - `scaleStepperHostAction`: payload `z.object({value: z.number()}).passthrough()`. It reads the agent's stepper through `findAgentBlock`: `history.prompts[n]` (`msg-<n>`), or the only prompt holding that stepper id (409 when there are several, 404 when none). It checks `value` and returns `{replace: "block", blocks: {v: 1, blocks: [stepper]}}`.
+    - The `logResponse` host-action option. With it off, the log keeps the ids-only prompt plus `value`, with no response.
+  - Acceptance: AC4; AC5; the stepper rows of AC1 and AC2. `bun test blocks/`, `cd ui && bun test src/blocks`, and `cd ai && bun test --preload ./src/tests/bunSetup.ts src/service/scaleStepper.test.ts src/routes/gptActions.test.ts` are green.
+
+- [x] **T2** — Prompt offers the new blocks by default, with an opt-out
+  - Depends on: T1
+  - Files: `blocks/src/prompt.ts`, `blocks/src/prompt.test.ts`, `blocks/src/validate.ts` (`stepperActions`), `blocks/src/lint.ts`; `ai/src/types/index.ts` (`uiBlocks.richBlocks`), `ai/src/service/prompts.ts`, `ai/src/service/chatTurn.ts` (derive `stepperActions` and `checklistActions` from the host actions' `handles`; pass `richBlocks`), `ai/src/routes/gpt.test.ts`; `docs/reference/blocks.md`, `docs/reference/ai.md`.
+  - Delivers: the default-on table in the IP. It adds the `richBlocks` plumbing (default `true` in both `uiBlocks` and `blocksPromptSection`), the stepper gate (a `handles: "stepper"` action), and the `checklistActions` list that T5 uses. With `richBlocks: false`, the prompt text is byte-identical to `master`, even with a stepper action registered. Later contract tasks add their prompt line under `richBlocks`.
+  - Acceptance: the AC3 `false` case, the default-on check, and the stepper line; a chat-turn test where a stepper naming a non-stepper action fails `UNKNOWN_HOST_ACTION`. The full on-case snapshot is T9's.
+
+### Phase 2: Tables
+
+- [x] **T3** — Table block renders typed columns
+  - Depends on: T1
+  - Files: `ui/src/DataTable.tsx` (number and date cells), `ui/src/DataTable.test.tsx`, `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `docs/reference/ui.md` (DataTable and BlocksView sections).
+  - Delivers: right-aligned `number` cells and Luxon `DATE_MED` `date` cells in `DataTable`. The `table` block maps the dataset column types to these cells, measures its width with `onLayout`, and splits the width evenly, at least 96 per column, scrolling sideways past that.
+  - Acceptance: AC9 (table half); the new tests fail on `master`.
+
+- [x] **T4** — Markdown tables in `text` get theme styling
+  - Depends on: T3 (shares `docs/reference/ui.md`; T10 follows T4 for the same reason)
+  - Files: `ui/src/MarkdownView.tsx`, `ui/src/MarkdownView.test.tsx`, `docs/reference/ui.md` (MarkdownView section only).
+  - Delivers: `border.default` cell borders, a bold header on `surface.secondaryLight`, and horizontal scroll when the table is wide.
+  - Acceptance: AC9 (markdown half); the test fails on `master`.
+
+### Phase 3: Contracts
+
+- [x] **T5** — `checklist` contract
+  - Depends on: T2
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/lint.ts` (item ids; reserved `<id>_<item id>` element ids; checklist `callback.name` against `checklistActions`), `blocks/src/prompt.ts`, `blocks/src/fixtures/{valid,invalid}/checklist*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: the `checklist` schema from the IP, including the optional `callback`. Its prompt line sits under `richBlocks` and names the checklist action when there is one.
+  - Acceptance: the checklist rows of AC1 and AC3; `bun test blocks/`.
+
+- [x] **T6** — `gallery` contract
+  - Depends on: T5
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/lint.ts` (image hosts per tile), `blocks/src/prompt.ts`, `blocks/src/fixtures/{valid,invalid}/gallery*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: the `gallery` schema. `IMAGE_HOST_NOT_ALLOWED` names the tile path (`blocks[0].images[2].src`).
+  - Acceptance: the gallery rows of AC1 and AC3; an invalid fixture with a disallowed host.
+
+- [x] **T7** — `list` contract
+  - Depends on: T6
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/lint.ts`, `blocks/src/prompt.ts`, `blocks/src/fixtures/{valid,invalid}/list*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: the `list` schema. The optional image on each item goes through image-host lint.
+  - Acceptance: the list rows of AC1 and AC3.
+
+- [x] **T8** — `card.eyebrow` contract
+  - Depends on: T7
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/prompt.ts`, `blocks/src/fixtures/{valid,invalid}/card-eyebrow*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: an optional `eyebrow` (1–60) on `card`.
+  - Acceptance: the eyebrow rows of AC1 and AC3.
+
+- [x] **T9** — `copy` action contract and `blockPlainText`
+  - Depends on: T8
+  - Files: `blocks/src/schema.ts`, `blocks/src/errors.ts` (`COPY_TARGET_INVALID`), `blocks/src/lint.ts` (exactly one of `text` / `target`, as `open` does), `blocks/src/prompt.ts`, `blocks/src/plainText.ts`, `blocks/src/plainText.test.ts`, `blocks/src/index.ts`, `blocks/src/fixtures/{valid,invalid}/copy*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: the `copy` action kind, target lint, and `blockPlainText` as the IP table describes it.
+  - Acceptance: the copy rows of AC1, AC2, and AC3; the full AC3 `richBlocks`-on snapshot. `plainText.test.ts` covers every row of the IP table.
+
+### Phase 4: Renderers
+
+- [x] **T10** — Checklist renders and toggles
+  - Depends on: T3, T4, T5
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/useChecklistState.ts`, `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, `docs/reference/ui.md`.
+  - Delivers: a `CheckBox` row per item (meta, bold text, detail) and the "n of m" counter. With a callback in `hostActions`, a tick emits `{...payload, itemId, checked, state}`, disables the whole checklist while a tick is pending (so a second tick cannot send a stale `state`), and shows the returned block. Without one, ticks are local for each rendered document.
+  - Acceptance: AC6.
+
+- [x] **T11** — Gallery renders
+  - Depends on: T6, T10
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, `docs/reference/ui.md`.
+  - Delivers: one row of 4:3 `Image` tiles up to 3, a 3-column grid above that, captions, `file:` ids through `useResolvedImages`, and sideways scroll on narrow screens.
+  - Acceptance: AC7 (gallery).
+
+- [x] **T12** — List renders
+  - Depends on: T7, T11
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, `docs/reference/ui.md`.
+  - Delivers: for each item, a 3:4 thumbnail on the left, a bold title, muted text, and the meta.
+  - Acceptance: AC7 (list).
+
+- [x] **T13** — Card eyebrow renders
+  - Depends on: T8, T12
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `docs/reference/ui.md`.
+  - Delivers: small, muted eyebrow text above the card title.
+  - Acceptance: AC7 (eyebrow).
+
+- [x] **T14** — Copy action writes the clipboard
+  - Depends on: T9, T13
+  - Files: `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `docs/reference/ui.md`.
+  - Delivers: a copy button builds its text with `blockPlainText` from the current block (override and toggles applied), writes it with `expo-clipboard`, and shows "Copied" in a polite live region for 2 s. It never calls `onAction`.
+  - Acceptance: AC8.
+
+### Phase 5: The roast reply end to end
+
+- [x] **T15** — Sunday roast golden document and playground story
+  - Depends on: T14
+  - Files: `blocks/src/fixtures/golden/sunday-roast.yaml`, `blocks/src/golden.test.ts` (validate with `hostActions: ["scaleStepper"]`, `stepperActions: ["scaleStepper"]`, `imageHosts: ["images.example.com"]`), `demo/stories/BlocksPlayground.stories.tsx` (a roast preset).
+  - Delivers: the GPT-6 demo reply as one document: the title; the gallery; the summary card with an eyebrow; the menu list; the stepper and copy card; the checklist with its first item checked; the USDA note as `context`; the tips as `text`; and follow-up `reply` buttons. It also includes the GPT-5.6 "How much lamb?" table as a `table` block. Images use `https://images.example.com/...` and validate only with `imageHosts`, so the file lives under `golden/`, not `valid/`.
+  - Acceptance: AC10; a playground screenshot under `/opt/cursor/artifacts/`.
+
+- [x] **T16** — Example app runs the roast reply against the real callback route
+  - Depends on: T15, T20, T21
+  - Files:
+    - `example-backend/src/ai/hostActions.ts`: register `scaleStepper: scaleStepperHostAction` and `toggleChecklist: toggleChecklistHostAction` (`richBlocks` is on by default).
+    - `example-frontend/app/(tabs)/ai.tsx`: add `scaleStepper` and `toggleChecklist` to `hostActions`.
+    - `example-frontend/e2e/helpers/seedGptHistory.ts` (new): `POST /gpt/histories` as the logged-in user, with the roast document as the assistant prompt.
+    - `example-frontend/e2e/helpers/mockGpt.ts`: the mocked stream returns the seeded `historyId`, and `/gpt/actions` is no longer mocked for this spec.
+    - `example-frontend/e2e/ai-chat.spec.ts`.
+    - `docs/explanation/example-coverage.md`.
+  - Delivers: the seeded roast document uses `file:` ids from a test `PhotoLibraryEntry`. Playwright presses + (5 → 6, the quantities change) and ticks a checklist item, both through the real `POST /gpt/actions`, then presses copy. Only the signed-URL image download is stubbed.
+  - Acceptance: AC11.
+
+- [x] **T17** — Model smoke: a real model writes the roast reply
+  - Depends on: T15, T20
+  - Files: `example-backend/src/scripts/blocksSmoke.ts`, `example-backend/package.json` and root `package.json` (`blocks:smoke` script).
+  - Delivers: a script that runs the post's prompt through `AIService` with the opted-in blocks prompt and checks the reply. It skips cleanly when no model key is set.
+  - Acceptance: AC12.
+
+- [x] **T18** — Docs sweep, changelog, rules
+  - Depends on: T15, T20, T21
+  - Files:
+    - `docs/explanation/agent-ui-blocks.md`: the catalog list, adding the missing `callout`, `image`, `details`, and `html`; why the stepper is a callback; the default-on rollout and the `richBlocks: false` opt-out for shipped native builds.
+    - `docs/how-to/agent-ui-blocks.md`: a section "Add a stepper callback", including the warning that stored history prompts are owner-writable, so a handler whose numbers matter must use its own data.
+    - `changelog/unreleased/agent-ui-rich-replies.md`, with a "Behaviour change" note: hosts with `uiBlocks` get the new blocks in the prompt by default; set `uiBlocks.richBlocks: false` to keep the old catalog.
+    - `.rulesync/rules/ui/00-ui.md` and `.rulesync/rules/ai/00-ai.md`, then `bun run rules`.
+  - Delivers: docs a stranger can follow to build the roast reply without reading the PR.
+  - Acceptance: AC13.
+
+- [x] **T19** — Generated photo library: generate images once and store them
+  - Depends on: none
+  - Files: `example-backend/src/models/photoLibraryEntry.ts`, `example-backend/src/types/models/photoLibraryEntryTypes.ts`, `example-backend/src/scripts/photoPrompts.ts`, `example-backend/src/scripts/generatePhotoLibrary.ts`, `example-backend/src/scripts/generatePhotoLibrary.test.ts`, `knip.jsonc` (script entry), `example-backend/package.json` (`photos:generate`).
+  - Delivers: the `PhotoLibraryEntry` model and the `photos:generate` script from the IP. It runs AI SDK `generateImage` with the Vertex image model, then `FileStorageService.upload`, then upserts by `prompt`. It validates the required env up front, skips existing prompts, and takes `--force`. Supporting skill: `mongoose-schema-safety`.
+  - Acceptance: AC14 (generation half), using a fake image model and fake storage.
+
+- [x] **T20** — `findPhotos` tool and photo URLs in the example app
+  - Depends on: T19
+  - Files: `example-backend/src/ai/tools.ts` (`findPhotos`), `example-backend/src/ai/tools.test.ts`, `example-backend/src/api/photoLibrary.ts` (`modelRouter` with instance action `url`), `example-backend/src/api/photoLibrary.test.ts`, `example-backend/src/server.ts` (register it), `example-frontend/store/openApiSdk.ts` (regenerated with `bun run sdk`), `example-frontend/app/(tabs)/ai.tsx` (`resolveImage`), `docs/how-to/agent-ui-blocks.md` ("Give the agent photos"; T18 follows it).
+  - Delivers: `findPhotos({query, count})` returns `{src: "file:<id>", alt}` from the library. `GET /photoLibrary/:id/url` returns a signed URL to any authenticated user. The example chat resolves `file:` ids through the generated hook. Supporting skills: `model-router-actions`, `generate-sdk`.
+  - Acceptance: AC14 (tool and route half).
+
+- [x] **T21** — Checklist ticks round trip through a host callback
+  - Depends on: T10
+  - Files: `ai/src/service/toggleChecklist.ts`, `ai/src/service/toggleChecklist.test.ts`, `ai/src/routes/gptActions.test.ts`, `ai/src/index.ts`, `docs/reference/ai.md`.
+  - Delivers: `toggleChecklistHostAction` from the IP, built on `findAgentBlock`.
+  - Acceptance: AC6b.
+
+### Phase 6: Playground follow-up (D7)
+
+- [x] **T22** — Every block type has a playground preset
+  - Depends on: T15
+  - Files: `demo/stories/BlocksPlayground.stories.tsx`, `demo/story-config/BlocksPlayground.config.tsx`, a demo test that every schema block type appears in a preset and every preset validates.
+  - Delivers: one preset per block type plus "All blocks", covering every action kind and the segmented control.
+  - Acceptance: the coverage test fails when a block type has no preset; every preset validates; runtime screenshots at 1280 and 390.
+
+- [x] **T23** — Stepper and checklist callbacks run in the playground
+  - Depends on: T22
+  - Files: `blocks/src/hostActionLogic.ts` (or similar) + tests + `blocks/src/index.ts`, `ai/src/service/scaleStepper.ts`, `ai/src/service/toggleChecklist.ts`, `demo/stories/BlocksPlayground.stories.tsx`, `docs/reference/blocks.md`.
+  - Delivers: pure `scaleStepperBlock` and `applyChecklistState` in `@terreno/blocks`, used by both host actions and the playground; other actions show a toast.
+  - Acceptance: in the playground, + shows 6 and "2.4 kg", a tick shows "2 of 8", a reply button shows a toast; ai host-action tests unchanged and green.
+
+- [x] **T24** — Checklist rows read bold title, then time, then description
+  - Depends on: none
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `docs/reference/ui.md`.
+  - Delivers: the row order from D7, test IDs unchanged.
+  - Acceptance: a test asserts the order; the e2e roast spec still passes.
+
+- [x] **T25** — Demo blocks use real photos
+  - Depends on: T22
+  - Files: `demo/assets/blocks/*.jpg`, `demo/assets/blocks/ATTRIBUTION.md`, `demo/stories/BlocksView.stories.tsx`, `demo/stories/BlocksPlayground.stories.tsx`.
+  - Delivers: gallery, list, and image presets and stories show bundled public-domain photos through `file:` ids and `resolveImage`.
+  - Acceptance: in the browser every photo loads (`naturalWidth` 800); attribution lists each source and license.

package/package.json

@@ -11,8 +11,8 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.12.0",
-    "@terreno/blocks": "57.12.0",
+    "@terreno/api": "57.13.0",
+    "@terreno/blocks": "57.13.0",
     "express": "^5.2.1",
     "luxon": "^3.7.2",
     "minisearch": "^7.2.0",
@@ -105,5 +105,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "type": "module",
-  "version": "57.12.0"
+  "version": "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/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

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