@terreno/mcp 57.16.2 → 57.18.0

package/dist/docs/versioned/57.17.0/tasks/agent-ui-blocks.md

@@ -0,0 +1,115 @@
+# Task List: Agent UI Blocks
+
+**Status:** Folded into [`docs/tasks/agent-ui-asks.md`](./agent-ui-asks.md) Phase 5 on 2026-10-01. Do not Pick from this file. Task 1.1 here is B1.1 there. Wire format is whole-reply YAML (D2 = b).
+**Supporting skills:** `terreno-ui`, `ai-prompt-governance`, `update-docs`, `verify-ui-changes`, `backend-test-env`, `terreno-backend-api`.
+
+Every task is a vertical slice: contract + renderer or producer + docs + Bun tests. Work
+the frontier (blockers complete). Phase 2 chart/table work is additionally blocked on
+[PR #1302](https://github.com/TerrenoLabs/terreno/pull/1302) merging to `master`.
+Agent UI Asks Tasks 3.1 and 3.2 (`html`, `callout`, `image`, `details` blocks; [`agent-ui-asks.md`](./agent-ui-asks.md)) wait on Tasks 1.1 and 2.1 here.
+
+### Phase 1: Contract — `@terreno/blocks`
+
+- [ ] **Task 1.1**: Package scaffold, Zod schema, parser, structural validation
+  - Delivers: `parseBlocks(text)` (strips an optional surrounding ` ```yaml ` fence, YAML or JSON, `NOT_A_DOCUMENT` when not a mapping with `v`), `wrapAsTextDocument(text)`, and `validateBlocks(doc)` reject unknown keys, wrong enums, and wrong top-level key order (`v` → `datasets` → `blocks`, `KEY_ORDER`) with `{path, code, message, fix}`; `v: 1` required; heading/text/metric/badge/divider/context/columns/card blocks and their enums exist.
+  - Files: `blocks/package.json`, `blocks/tsconfig.json`, `blocks/biome.jsonc`, `blocks/src/index.ts`, `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/errors.ts`, `blocks/src/parse.ts`, `blocks/src/validate.ts`, `blocks/src/fixtures/valid/*.yaml`, `blocks/src/fixtures/invalid/*.yaml`, `blocks/src/*.test.ts`; root `package.json` (workspace + catalog `yaml`), `knip.jsonc`, `.github/workflows/blocks-ci.yml` (mirror `comms-ci.yml`) or a `blocks` job in `packages-ci.yml`, plus `.circleci` parity if `check:circleci-parity` requires it.
+  - Blocked by: none
+  - Docs: `docs/reference/blocks.md` (new: grammar tables, limits, error codes), `docs/explanation/agent-ui-blocks.md` (new: why a closed catalog, why whole-reply YAML, approaches considered, ownership diagram), `docs/reference/README.md`, `docs/explanation/README.md`.
+  - Acceptance: AC1 (golden fixtures for the leaf + layout blocks, including a prose-only `text` document), AC2 for structural codes (`UNKNOWN_KEY`, `INVALID_ENUM`, `MISSING_REQUIRED`, `UNSUPPORTED_VERSION`, `DEPTH_EXCEEDED`, `TOO_MANY_BLOCKS`, `KEY_ORDER`, `NOT_A_DOCUMENT`); YAML anchors/tags rejected (`YAML_FEATURE_DISALLOWED`); `bun test blocks/` green; `bun run check:knip` green.
+
+- [ ] **Task 1.2**: Datasets, chart and table schema, semantic lint
+  - Delivers: `datasets` map with two sources — `inline` (typed columns + rows) and `ref` (`{source: ref, id, grain?, limit?}`, D4/Q6); `chart` (`kind`, `data`/`x`/`y` or `points`) and `table` blocks; lint pass for dataset refs, column existence/type (inline; `ref` columns checked when a `knownDatasets` map is passed, deferred otherwise), row arity, id uniqueness, D7 limits including `ref` `limit` caps, chart heuristics as warnings.
+  - Files: `blocks/src/schema.ts`, `blocks/src/lint.ts`, `blocks/src/validate.ts`, `blocks/src/fixtures/**`, `blocks/src/lint.test.ts`, `blocks/src/validate.perf.test.ts`.
+  - Blocked by: 1.1
+  - Docs: `docs/reference/blocks.md` (dataset sources + chart + table sections, warning codes).
+  - Acceptance: AC2 for semantic codes (`DATASET_NOT_FOUND`, `COLUMN_NOT_FOUND`, `COLUMN_TYPE_MISMATCH`, `ROW_ARITY_MISMATCH`, `DUPLICATE_ID`, `DATASET_TOO_LARGE`, `TABLE_TOO_WIDE`, `TOO_MANY_POINTS`) and warnings (`BAR_TOO_MANY_CATEGORIES`, `DONUT_TOO_MANY_SLICES`, `LINE_SINGLE_POINT`); AC18 (`ref` half); AC3 perf test; doc-code parity test reads `docs/reference/blocks.md` and asserts every code in `BLOCK_ERROR_CODES` appears.
+
+- [ ] **Task 1.3**: Actions schema, partial parser, JSON Schema, prompt section, CLI
+  - Delivers: `actions` block with `button`/`segmented` elements and closed `action.kind` set (`reply`, `open`, `select`, `callback`); `validateBlocks(doc, {hostActions?, knownDatasets?})` emits `UNKNOWN_HOST_ACTION` when an allowlist is supplied; `parseBlocksPartial(text)` → `{datasets, blocks, pending}` from a truncated document (completed top-level `blocks` items only, each validated individually, never throws); `blocksJsonSchema`; `blocksPromptSection({hostActions})` that embeds the grammar, key-order rule, limits, the reply rule ("your entire reply is one document; no prose outside it; no text before tool calls"), the `ref` dataset rule ("use the `datasetId` a tool returned; never paste more than 500 rows"), and two examples (data + prose-only); `terreno-blocks validate` CLI bin.
+  - Files: `blocks/src/schema.ts`, `blocks/src/parsePartial.ts`, `blocks/src/jsonSchema.ts`, `blocks/src/prompt.ts`, `blocks/src/cli.ts`, `blocks/package.json` (`bin`), `blocks/src/fixtures/partial/*.yaml`, tests.
+  - Blocked by: 1.2
+  - Docs: `docs/reference/blocks.md` (actions, partial parsing, CLI), `docs/how-to/agent-ui-blocks.md` (new: "validate a document locally" section only).
+  - Acceptance: AC4 (ajv round-trip on fixtures); AC20 (`parsePartial` half: truncated fixtures cut mid-block, mid-dataset, and mid-scalar); `select` with a non-chart/table target → `SELECT_TARGET_INVALID`; CLI exit codes 0/1 asserted via `Bun.spawn`; prompt section snapshot test asserts limits text equals `BLOCK_LIMITS` values (single source of truth).
+
+### Phase 2: Renderer — `@terreno/ui`
+
+- [ ] **Task 2.1**: `BlocksView` for leaf and layout blocks, error and placeholder states
+  - Delivers: `BlocksView` (lazy via `heavyOptionalExports`) renders heading/text/metric/badge/divider/context/columns/card with `@terreno/ui` components; string input is validated; invalid → `Banner` + collapsed raw YAML; non-document string → `wrapAsTextDocument` fallback; `columns` stacks on `sm`.
+  - Files: `ui/package.json` (`@terreno/blocks` dep), `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksError.tsx`, `ui/src/Common.ts` (`BlocksViewProps`), `ui/src/lazyBoundaries/heavyOptionalExports.tsx`, `ui/src/index.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, `demo/story-config/BlocksView.config.tsx`, `demo/demoConfig.tsx`.
+  - Blocked by: 1.1
+  - Docs: `docs/reference/ui.md` (`BlocksView` section), `docs/explanation/agent-ui-blocks.md` (renderer ownership).
+  - Acceptance: AC5 for the covered blocks (plus an `rg` guard test that `ui/src/blocks/` imports no `react-native` `View`/`Text`); AC6 (both halves); `bun run check:demo-coverage` green; screenshot of the story saved under `/opt/cursor/artifacts/`.
+
+- [ ] **Task 2.2**: Chart and table blocks bound to datasets
+  - Delivers: `chart` renders `BarChart`/`LineChart`/`AreaChart`/`DonutChart` inside a `Card` with title, legend, `emptyText`, `height` map (`sm`/`md`/`lg` → px); `table` renders `DataTable` with typed columns (paginated via `more` for `ref` sources); `ref` datasets resolve through the `resolveDataset` prop (`useResolvedDatasets` hook: `loading` state on the chart, error `Banner` on failure, request de-duplicated per `{id, grain, limit, page}`); per-point `color` is not exposed to the agent.
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/datasetToPoints.ts`, `ui/src/blocks/useResolvedDatasets.ts`, tests, `demo/stories/BlocksView.stories.tsx` (chart presets incl. a mocked `ref` preset).
+  - Blocked by: 1.2, 2.1, PR #1302 merged
+  - Docs: `docs/reference/ui.md`, `docs/how-to/charts-and-dashboards.md` (one paragraph: "charts from agent replies").
+  - Acceptance: AC5 for chart/table; `datasetToPoints` unit tests (date columns formatted with Luxon, numeric parse, empty dataset → `emptyText`); `useResolvedDatasets` tests (loading → data, rejection → banner, no duplicate fetch); screenshot of bar + donut from one dataset.
+
+- [ ] **Task 2.3**: Actions, `onAction`, segmented dataset switch
+  - Delivers: `actions` renders `Button` / `SegmentedControl`; every press calls `onAction({blockId, elementId, messageId, action})`; `select` updates local dataset binding of the target block and still reports; `hostActions` allowlist marks unknown `callback` names as disabled with tooltip; `callback` buttons show `loading` while their id is in `pendingElementIds`; `BlocksView` accepts `overrides: Record<blockId, BlocksDocument>` so a host can replace one block in place (D6 `replace: block`).
+  - Files: `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/useBlockSelections.ts`, `ui/src/Common.ts`, tests, story additions.
+  - Blocked by: 1.3, 2.2
+  - Docs: `docs/reference/ui.md` (`onAction` payload table, `pendingElementIds`, `overrides`), `docs/explanation/agent-ui-blocks.md` (interaction flow incl. server callbacks).
+  - Acceptance: AC8; `onAction` payload snapshot per kind; disabled unknown callback asserted; AC19 (`BlocksView` half: loading + block override).
+
+- [ ] **Task 2.4**: `GPTChat` `uiBlocks` mode, progressive render, Blocks Playground
+  - Delivers: `GPTChat` prop `uiBlocks?: boolean`; when on, assistant messages render through `BlocksView` instead of `MarkdownView` — streaming messages use `parseBlocksPartial` and show completed top-level blocks plus a `Spinner` tail row, completed messages use `parseBlocks` with `wrapAsTextDocument` fallback; forwards `reply` to `onSubmit`, `open`/`select` to `onBlockAction`, and `callback` to `onBlockCallback?: (action) => Promise<{text?, blocks?, replace?}>` — tracking pending element ids, applying `replace: block` via `overrides`, `replace: message` by swapping the message body, and `text` by appending an assistant message; passes `resolveDataset` through; user messages and tool-call cards unchanged; demo Blocks Playground (YAML `TextArea` → live render + error list, fixture presets, "simulate streaming" toggle that feeds the document in 40-char steps).
+  - Files: `ui/src/GPTChat.tsx`, `ui/src/GPTChat.test.tsx`, `ui/src/Common.ts`, `demo/stories/BlocksPlayground.stories.tsx`, `demo/story-config/BlocksPlayground.config.tsx`, `demo/demoConfig.tsx`.
+  - Blocked by: 2.3
+  - Docs: `docs/reference/ui.md` (`GPTChat.uiBlocks`, `onBlockAction`, `onBlockCallback`, `resolveDataset`), `docs/how-to/agent-ui-blocks.md` (playground section).
+  - Acceptance: AC7; AC19 (`GPTChat` half); AC20 (`GPTChat` half: a streaming message cut mid-block renders the preceding blocks and a `Spinner`, never raw YAML); `uiBlocks` off → existing `MarkdownView` path untouched (regression test); playground recording saved under `/opt/cursor/artifacts/`.
+
+### Phase 3: Producer — `@terreno/ai`
+
+- [ ] **Task 3.1**: `uiBlocks` route option, prompt constant, post-stream validation SSE, repair pass
+  - Delivers: `addGptRoutes(router, {uiBlocks: true | UiBlocksOptions})` appends `TERRENO_UI_BLOCKS_SYSTEM_PROMPT` (built from `blocksPromptSection` + host callback names) and pins the blocks temperature preset; the **final step's** `text-delta`s form the document (earlier-step text is logged, not stored as the message); after the stream ends the document is validated with `{hostActions: Object.keys(...), knownDatasets}` and SSE `{blocks: {ok, errors, warnings}}` is emitted before `{done}`; with `repair: true` and `ok: false`, one non-streamed repair call (errors appended) replaces the stored assistant `content` and streams a `{replace: text}` SSE event before `{done}`; validation errors are appended to the stored assistant turn as a system note so the next user turn's context includes them; `AIRequest.metadata.uiBlocks` summary logged.
+  - Files: `ai/package.json` (`@terreno/blocks` dep), `ai/src/service/prompts.ts`, `ai/src/routes/gpt.ts`, `ai/src/types/index.ts` (`HostAction`, `UiBlocksOptions`), `ai/src/routes/gpt.test.ts`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/ai.md` (option + SSE event rows), `docs/how-to/agent-ui-blocks.md` (backend enable section, repair trade-off).
+  - Acceptance: AC9 with a mock model that streams a valid document, an invalid document, and a prose-only non-document; AC18 (`UNKNOWN_HOST_ACTION` half); prompt constant lives at the top of `prompts.ts` (ai-prompt-governance); no SSE `blocks` event and no prompt change when `uiBlocks` is off (regression test).
+
+- [ ] **Task 3.4**: `AIDataset` model, `registerAiDataset`, `GET /gpt/datasets/:id`
+  - Delivers: `AIDataset` Mongoose model (D18: `expiresAt?` with `{expiresAt: 1}, {expireAfterSeconds: 0}` index, `isDeletedPlugin`, descriptions on every field); `configureAiDatasets({datasetTtlDays = 0, datasetMaxRows = 50_000})` called by `addGptRoutes`; `registerAiDataset({userId, historyId, columns, rows})` sets `expiresAt` only when `datasetTtlDays > 0`, rejects over-cap rows with `APIError 413`, and returns `{datasetId, columns, rowCount, preview, stats}` for tool results; `GET /gpt/datasets/:id?grain=&limit=&page=` (`IsOwner`) buckets `date` columns by `grain`, downsamples line/area with LTTB when rows exceed `limit`, paginates tables with `more`; mounted by `addGptRoutes` when `uiBlocks` is on.
+  - Files: `ai/src/models/aiDataset.ts`, `ai/src/service/aiDatasets.ts` (`configureAiDatasets`, `registerAiDataset`, `bucketByGrain`, `lttb`), `ai/src/routes/gptDatasets.ts`, `ai/src/routes/gpt.ts` (mount), `ai/src/types/index.ts`, `ai/src/index.ts`, `ai/src/service/aiDatasets.test.ts`, `ai/src/routes/gptDatasets.test.ts`.
+  - Blocked by: 1.2
+  - Docs: `docs/reference/ai.md` (model + route + helper + options rows), `docs/explanation/agent-ui-blocks.md` ("why rows never pass through the model"; retention defaults to unlimited), `docs/how-to/agent-ui-blocks.md` ("return a dataset from a tool", "set a retention window").
+  - Acceptance: AC16 (including the `datasetTtlDays` 0 vs 7 assertion); `lttb` property test (output length ≤ `limit`, first/last points preserved); mongoose-schema-safety checklist applied (new model, additive only).
+
+- [ ] **Task 3.5**: `POST /gpt/actions` host callback route
+  - Delivers: `POST /gpt/actions` (D19) validates `{historyId, messageId, blockId, elementId, name, payload}`, looks up `hostActions[name]`, validates `payload` against its Zod schema, checks history ownership, runs `handler({payload, user, history, blockId, elementId})` with a 10 s timeout, validates any returned `blocks` with `validateBlocks`, returns `{text?, blocks?, replace?}`, logs `AIRequest` `requestType: "ui_action"`; shares the `/gpt` rate-limit bucket.
+  - Files: `ai/src/routes/gptActions.ts`, `ai/src/routes/gpt.ts` (mount), `ai/src/types/index.ts`, `ai/src/routes/gptActions.test.ts`, `ai/src/models/aiRequest.ts` (`requestType` enum additions).
+  - Blocked by: 3.1
+  - Docs: `docs/reference/ai.md` (route row + `HostAction` type), `docs/how-to/agent-ui-blocks.md` ("register a server callback"), `docs/explanation/agent-ui-blocks.md` (Block Kit `block_actions` comparison table).
+  - Acceptance: AC17; handler timeout returns 504 and is logged; returned invalid `blocks` → 500 with error list (host bug, not agent bug).
+
+- [ ] **Task 3.2**: `AIService.generateBlocks` with bounded repair
+  - Delivers: `generateBlocks({prompt, systemPrompt?, userId?, repair?})` → `Output.object(blocksJsonSchema)` → `validateBlocks`; one repair retry on failure with errors appended to the prompt; `requestType: "ui_blocks"`; throws `APIError 422` with the error list after the retry fails.
+  - Files: `ai/src/service/aiService.ts`, `ai/src/types/index.ts`, `ai/src/service/aiService.test.ts`.
+  - Blocked by: 3.1
+  - Docs: `docs/reference/ai.md` (method table row + temperature preset note).
+  - Acceptance: AC10; deterministic temperature asserted; logged `metadata.errorCodes` on failure.
+
+- [ ] **Task 3.3**: MCP validator tool
+  - Delivers: `terreno_validate_ui_blocks({document})` returns the CLI report text; listed in `ListTools`.
+  - Files: `mcp-server/package.json` (`@terreno/blocks` dep), `mcp-server/src/tools.ts`, `mcp-server/src/tools.test.ts`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/mcp-server.md` (tool row), `.cursor/rules/mcp-server/00-mcp-server.mdc` via rulesync source `.rulesync/rules/mcp-server/00-mcp-server.md`.
+  - Acceptance: AC11; tool schema snapshot.
+
+### Phase 4: Examples, e2e, docs
+
+- [ ] **Task 4.1**: example-frontend AI tab renders blocks and handles actions
+  - Delivers: `ai.tsx` handles SSE `blocks` event (attaches validation summary to the message for a subtle "n components" caption), passes `onBlockAction` (`open` → `router.push` for `/…` routes or `Linking.openURL` for https), `onBlockCallback` → generated `usePostGptActionsMutation`, `resolveDataset` → generated `useLazyGetGptDatasetsByIdQuery` (SDK regenerated via `bun run sdk`), `reply` flows through existing `onSubmit`; `GPTChat uiBlocks` on; e2e mock streams a whole-reply document (in chunks, to exercise progressive render) with one inline and one `ref` dataset and serves the dataset + action routes.
+  - Files: `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/store/openApiSdk.ts` (generated), `example-frontend/e2e/helpers/mockGpt.ts`, `example-frontend/e2e/ai-chat.spec.ts`.
+  - Blocked by: 2.4, 3.1, 3.4, 3.5
+  - Docs: `docs/how-to/agent-ui-blocks.md` (frontend wiring section), `docs/explanation/example-coverage.md` (capability row).
+  - Acceptance: AC13; recording of prompt → bar chart (from `ref`) → callback button loading → block replaced → follow-up `reply` button → new user message, saved under `/opt/cursor/artifacts/`.
+
+- [ ] **Task 4.2**: example-backend enable, changelog, docs sweep
+  - Delivers: `example-backend` passes `uiBlocks: {hostActions: {exportDataset: {payload, handler}}, repair: true}` (TTL left at the unlimited default) with a handler that returns `{replace: "block", blocks}`; a `todoStats` tool calls `registerAiDataset` so a real prompt produces a `ref` chart; changelog entry; all reference/how-to/explanation pages cross-linked; rules regenerated.
+  - Files: `example-backend/src/server.ts`, `example-backend/src/ai/hostActions.ts`, `example-backend/src/ai/tools.ts`, `changelog/unreleased/agent-ui-blocks.md`, `docs/how-to/README.md`, `docs/reference/README.md`, `docs/explanation/README.md`, `.rulesync/rules/ui/00-ui.md` (BlocksView bullet) → `bun run rules`.
+  - Blocked by: 4.1, 3.2, 3.3
+  - Docs: as listed.
+  - Acceptance: AC14, AC15; `bun run website:build` green; `bun run rules:check` green.

package/dist/docs/versioned/57.17.0/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/dist/docs/versioned/57.17.0/tasks/agentic-sdlc-plugin.md

@@ -0,0 +1,57 @@
+# Task List: Loop-Engineering Lifecycle Plugin
+
+See: [`docs/implementationPlans/agentic-sdlc-plugin.md`](../implementationPlans/agentic-sdlc-plugin.md)
+
+## Phase 1: Audit and contracts
+
+- [x] **Task 1.1**: Audit five lifecycle skills, metadata, references, repo skills, state conventions, sync tooling, and long-lived-context assumptions
+  - Blocked by: none
+  - Acceptance: Findings identify duplicated repository knowledge, missing handoffs, generated sources, and orchestration owned by stages.
+- [x] **Task 1.2**: Define shared stage result and execution-state schemas
+  - Blocked by: Task 1.1
+  - Acceptance: Stable schemas use only `PASS`/`FAIL`/`BLOCKED`/`PENDING`, preserve evidence/attempts, and contain no reasoning transcript.
+- [x] **Task 1.3**: Document loop ownership, retries, human gates, state transport, and supporting-skill discovery
+  - Blocked by: Task 1.2
+  - Acceptance: A fresh invocation packet and fallback execution-state location are explicit.
+
+## Phase 2: Bounded lifecycle stages
+
+- [x] **Task 2.1**: Refactor Grow as an approved-artifact transition
+  - Blocked by: Task 1.3
+  - Acceptance: Grow classifies uncertainty, researches facts, grills decisions, maps acceptance to verification, and emits Pick-ready state.
+- [x] **Task 2.2**: Refactor Pick as one-slice TDD implementation
+  - Blocked by: Task 1.3
+  - Acceptance: Pick consumes retry evidence, preserves verified behavior, runs independent implementation/test-quality review, and delegates repository detail.
+- [x] **Task 2.3**: Refactor Roast as independent authoritative verification
+  - Blocked by: Task 2.2
+  - Acceptance: Roast executes a requirement/evidence matrix, does not trust Pick claims, and returns exact failures to Pick.
+- [x] **Task 2.4**: Refactor Brew to terminate after PR setup
+  - Blocked by: Task 2.3
+  - Acceptance: Brew records PR/current head and recommends Taste without executing or waiting for it.
+- [x] **Task 2.5**: Refactor Taste as one reactive iteration
+  - Blocked by: Task 2.4
+  - Acceptance: Taste observes current head once, handles current actionable work, emits state, exits, and contains no internal waiting loop.
+
+## Phase 3: Plugin boundary and composition
+
+- [x] **Task 3.1**: Remove Terreno package commands/patterns from lifecycle control surfaces
+  - Blocked by: Task 2.5
+  - Acceptance: Exact repo knowledge remains under `.rulesync/skills/`; lifecycle stages discover applicable skills.
+- [x] **Task 3.2**: Convert plugin utility/orchestration skills to shared references
+  - Blocked by: Task 2.5
+  - Acceptance: Plugin exposes exactly five lifecycle skill directories; independent review and feature-loop behavior remain documented once.
+- [x] **Task 3.3**: Document backend, UI, and multi-invocation CI/review compositions
+  - Blocked by: Task 3.2
+  - Acceptance: Each scenario shows lifecycle + project skills + durable evidence.
+
+## Phase 4: Validation and documentation
+
+- [x] **Task 4.1**: Add lifecycle architecture validator and unit tests
+  - Blocked by: Task 3.2
+  - Acceptance: Validator enforces names/directories, required contracts, status/transition values, portability, Brew/Taste boundaries, and migration docs.
+- [x] **Task 4.2**: Update plugin/docs/metadata/changelog and regenerate integrations
+  - Blocked by: Task 4.1
+  - Acceptance: Plugin is `2.0.0`; docs describe the bounded loop; generated rules are current; retired names appear only in intentional migration/history.
+- [x] **Task 4.3**: Run static tests, rulesync validation, lint/type checks, and independent review
+  - Blocked by: Task 4.2
+  - Acceptance: All checks pass and no material standards/spec findings remain.

package/dist/docs/versioned/57.17.0/tasks/ai-agents-and-failover.md

@@ -0,0 +1,107 @@
+# Tasks: AI agents and provider failover
+
+IP: [ai-agents-and-failover](../implementationPlans/ai-agents-and-failover.md)
+
+Instructions for Pick:
+
+- TDD: failing test first on every task that ships code.
+- Mock `LanguageModel` with `doGenerate` / `doStream` (see `ai/src/service/aiService.test.ts`). Never call a live provider.
+- Agent instructions are named constants (`ai-prompt-governance`).
+- Docs in the same slice as the public API they describe (`update-docs`).
+- Import concrete files, not internal barrels.
+- `bun test` from `ai/` after each task; `bun run compile` before considering a phase done.
+
+## Phase 1 — Failover LanguageModel (tracer)
+
+- [ ] **Task 1.1**: `isFailoverableError`
+  - Delivers: shared predicate used by the wrapper and tests
+  - Files: `ai/src/service/failoverModel.ts`, `ai/src/service/failoverModel.test.ts`
+  - Blocked by: none
+  - Acceptance: 429 / 502 / 503 / 529 → true; `{statusCode: 429}` → true; 400 / 401 / 404 → false; `NoObjectGeneratedError`-shaped errors → false
+  - Docs: none (internal until 1.3)
+  - Skills: none
+
+- [ ] **Task 1.2**: `createFailoverModel` generate + stream
+  - Delivers: LanguageModel that tries the next model on failoverable `doGenerate` / `doStream` rejection
+  - Files: `ai/src/service/failoverModel.ts`, `ai/src/service/failoverModel.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: two mocks, first 429, second succeeds; non-failoverable error does not call the second; empty `models` throws at construct; last error rethrown when all fail; `doStream` that returns then errors does **not** failover; `lastServedModelId` set on success
+  - Docs: none until 1.3
+  - Skills: none
+
+- [ ] **Task 1.3**: Export failover helpers
+  - Delivers: public package surface
+  - Files: `ai/src/index.ts`
+  - Blocked by: 1.2
+  - Acceptance: `createFailoverModel` and `isFailoverableError` importable from `@terreno/ai`; `bun run compile` in `ai/` succeeds
+  - Docs: none until Phase 4
+  - Skills: none
+
+## Phase 2 — Logging served model (tracer with AIService)
+
+- [ ] **Task 2.1**: Log the model that actually served
+  - Delivers: `AIRequest.aiModel` + `metadata.failover` after a failover generate
+  - Files: `ai/src/service/aiService.ts`, `ai/src/service/aiService.test.ts` (or `failoverModel` integration test using `AIService`)
+  - Blocked by: 1.2
+  - Acceptance: `generateText` through `createFailoverModel` logs backup `modelId`; `metadata.failover.attempts` length 2; logging failure still does not throw
+  - Docs: none until Phase 4
+  - Skills: none
+
+## Phase 3 — Agent
+
+- [ ] **Task 3.1**: `Agent` text `run`
+  - Delivers: named agent → `generateText` with instructions as `systemPrompt`
+  - Files: `ai/src/agent/agent.ts`, `ai/src/agent/agent.test.ts`, `ai/src/types/index.ts`
+  - Blocked by: none (can parallelize with Phase 1; logging assertions need 2.1)
+  - Acceptance: mock sees named instruction constant as system; `requestType` `"agent"`; `metadata.agentName` set; constructor requires `name` + `instructions`
+  - Docs: none until 3.4
+  - Skills: `ai-prompt-governance`
+
+- [ ] **Task 3.2**: `Agent` schema `run`
+  - Delivers: `schema` path uses `generateJsonObject`
+  - Files: `ai/src/agent/agent.ts`, `ai/src/agent/agent.test.ts`
+  - Blocked by: 3.1
+  - Acceptance: typed object returned; fence-stripping behavior unchanged; tools ignored when schema is set (asserted)
+  - Docs: none until 3.4
+  - Skills: `ai-prompt-governance`
+
+- [ ] **Task 3.3**: `Agent` tools + `runStream` + middleware
+  - Delivers: chat/tool loop, text stream, middleware chain
+  - Files: `ai/src/agent/agent.ts`, `ai/src/agent/agent.test.ts`
+  - Blocked by: 3.1
+  - Acceptance: tools passed through to `generateChatStream`; `maxSteps` default 5; `runStream` yields chunks; middleware order outer-first; short-circuit skips the model
+  - Docs: none until 3.4
+  - Skills: none
+
+- [ ] **Task 3.4**: Export Agent + explorer filter
+  - Delivers: public export; admin explorer can filter `agent`
+  - Files: `ai/src/index.ts`, `ai/src/routes/aiRequestsExplorer.ts`, explorer tests if present
+  - Blocked by: 3.1
+  - Acceptance: `Agent` importable from `@terreno/ai`; explorer query accepts `requestType=agent`
+  - Docs: Phase 4
+  - Skills: `update-docs`
+
+## Phase 4 — Docs and agent rules
+
+- [ ] **Task 4.1**: Reference + how-tos
+  - Delivers: operators can use Agent and failover without reading the IP
+  - Files: `docs/reference/ai.md`, `docs/how-to/define-an-ai-agent.md`, `docs/how-to/configure-ai-failover.md`, `docs/how-to/README.md`, `ai/README.md`
+  - Blocked by: 1.3, 3.4
+  - Acceptance: one minimal example per API; exports match `ai/src/index.ts`; how-to index links both pages
+  - Skills: `update-docs`
+
+- [ ] **Task 4.2**: Cursor rules + prompt-governance skill
+  - Delivers: agents use named instruction constants and failover wrapper, not ad-hoc retries in routes
+  - Files: `.cursor/rules/ai/00-ai.mdc` (or rulesync source), `skills/ai-prompt-governance/SKILL.md`; run `bun run rules` / `bun run skills:sync` if that is the repo workflow
+  - Blocked by: 4.1
+  - Acceptance: rule mentions `Agent` and `createFailoverModel`; prompt skill mentions agent instructions
+  - Skills: `update-docs`, `update-agent-docs`
+
+## Phase 5 — Optional example (skip if dual providers are not already wired)
+
+- [ ] **Task 5.1**: example-backend agent **or skip with recorded reason**
+  - Delivers: one in-repo Agent using existing Google/Vertex setup if both exist
+  - Files: `example-backend/src/api/ai.ts` (or adjacent module), named prompt constant
+  - Blocked by: 3.4, 1.3
+  - Acceptance: either (a) example constructs `createFailoverModel` + `Agent` without new required env, tests or typecheck pass, **or** (b) PR notes why skipped
+  - Skills: `ai-prompt-governance`