@terreno/mcp 57.9.0 → 57.11.0

package/dist/docs/versioned/next/reference/ui.md

@@ -10,6 +10,7 @@ React Native UI component library (a large component library). Layout (Box, Page
 - Actions: `Button`, `IconButton`, `Link`
 - Feedback: `Spinner`, `Modal`, `Toast`
 - Notifications: `NotificationBell`, `NotificationInbox`, `NotificationPreferences`
+- AI chat: `GPTChat`, `AskCard` (agent asks in the transcript), `SimpleAskCard` (an ask's simple card for narrow layouts), `BlocksView` (a whole-reply YAML document)
 - Authentication: `SocialLoginButton`, `LoginScreen`, `SignUpScreen`
 - Theming: `TerrenoProvider`, `useTheme`, custom icon registry (`icons` prop)
 - **Type re-exports:** `StyleProp`, `ViewStyle` (re-exported from react-native to avoid version conflicts)
@@ -32,7 +33,7 @@ supported and is convenient when startup cost is not material:
 import {Box, DataTable, Icon} from "@terreno/ui";
 ```
 
-Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, `ChartCard`, `Scorecard`, `SparklineChart`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related admin tools) are
+Heavy optional widgets (`GPTChat`, `AskCard`, `BlocksView`, `EmojiSelector`, `MarkdownEditor`, consent flows, `ChartCard`, `Scorecard`, `SparklineChart`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related admin tools) are
 re-exported from the root entry through lazy boundaries. Importing them from `@terreno/ui` stays type-compatible, but
 their implementation modules load on first render instead of during the initial root import. `DashboardGrid` stays eager.
 `MarkdownView` and `DataTable` header info defer `react-native-markdown-display`;
@@ -250,6 +251,18 @@ Buttons automatically size to their content unless `fullWidth` is specified:
 
 Internally, Button sets `alignSelf: 'flex-start'` when `fullWidth={false}` to prevent stretching in column layouts.
 
+A label stays on one line by default, so a long label can make the button wider than its container.
+Set `wrapText` to keep the button inside its container instead: the label wraps onto centered lines
+and the button grows taller. A `size="sm"` button grows from its 28px height instead of clipping the
+second line. `SimpleAskCard` and `AskCard` set `wrapText` on their answer buttons, because their
+labels come from the agent.
+
+```tsx
+<Box direction="row" width={160}>
+  <Button onClick={handleSave} text="Save all changes now" wrapText />
+</Box>
+```
+
 ### TextField grow and maxHeight
 
 `grow` makes a multiline field expand with its content. Pair it with `maxHeight` (pixels) to cap the expansion; past the cap the content scrolls.
@@ -390,10 +403,321 @@ The attach control (`FilePickerButton`) opens an anchored dropdown with **Photo
 />
 ```
 
+Pass `uiBlocks` to render each assistant message through `BlocksView`. A streaming message
+shows each finished top-level block and a spinner for the block still arriving. `reply`
+calls `onSubmit` with the button text. `open` and `select` call `onBlockAction`. `callback`
+calls `onBlockCallback` and the button stays loading until that promise settles. Return
+`{replace: "block", blocks}` to swap that block, or `{text}` to place an assistant message
+immediately after the message that started the callback. A result that arrives after
+`currentHistoryId` changes is dropped. `hostActions` disables callback names the host did
+not list. `resolveDataset` loads `ref` datasets. `resolveImage` turns a `file:` image id
+into a URL.
+
+```tsx
+<GPTChat
+  currentMessages={messages}
+  histories={histories}
+  hostActions={["export_csv"]}
+  onBlockAction={handleBlockAction}
+  onBlockCallback={handleBlockCallback}
+  onCreateHistory={onCreateHistory}
+  onDeleteHistory={onDeleteHistory}
+  onSelectHistory={onSelectHistory}
+  onSubmit={onSubmit}
+  uiBlocks
+/>
+```
+
 Operator steps: [Add a GPT chat mascot](../how-to/add-gpt-chat-mascot.md). Demo story: `GPTChat` → `Mascot`.
+Blocks playground: `BlocksPlayground`.
 The example AI screen demonstrates a consumer selecting one of four bundled mascot
 images once per mount.
 
+#### Asks
+
+`GPTChat` shows an [agent ask](agent-ui-asks.md) as an `AskCard` in the transcript. Set `ask` on
+the ask's `tool-call` message and pass `onAskSubmit`:
+
+```tsx
+<GPTChat
+  askErrors={askErrors}
+  currentMessages={currentMessages}
+  histories={histories}
+  onAskSubmit={handleAskSubmit}
+  onCreateHistory={onCreateHistory}
+  onDeleteHistory={onDeleteHistory}
+  onSelectHistory={onSelectHistory}
+  onSubmit={onSubmit}
+/>
+```
+
+| Prop or field | Type | Description |
+| --- | --- | --- |
+| `GPTChatMessage.ask` | `ChatAsk` | On a `tool-call` message: the ask (`kind`, `input`), its `toolCallId`, `status` (`pending`, `answered`, or `cancelled`), and optional `response` and `simple` card. The chat shows an `AskCard` instead of the tool call. |
+| `onAskSubmit` | `(submission: {toolCallId, response}) => void \| Promise<void>` | Called when the user answers a pending ask. `response` is the answer envelope. The pressed control shows a loading state until the promise settles. Without it, asks show but cannot be answered. |
+| `askErrors` | `Record<string, AskValidationError[]>` | Errors for the last answer to each ask, keyed by tool call id, such as the `fields` of a 400 `Invalid askResponse`. Shown inside the card. |
+| `resolveAskFiles` | `AskFilesResolver` | Turns the files picked for a `files` ask into the refs its answer sends. Defaults to `resolveAskFilesAsDataUrls`. Pass an uploader to send `{fileId}` refs; see [Accept uploads with or without GCS](../how-to/agent-ui-asks.md#accept-uploads-with-or-without-gcs). |
+
+- The ask's `tool-result` message stays in `currentMessages` but is not shown. Keep it: message
+  indexes must match the stored `prompts` rows that ratings use. When `ask.response` is unset, the
+  card reads the answer from that message.
+- A pending ask takes focus when it appears: DOM focus on the card, labelled with the ask's
+  `title`, on web; accessibility focus on the question, an accessibility header, on native.
+- Answered and cancelled asks collapse to a one-line summary.
+
+The example AI screen, `example-frontend/app/(tabs)/ai.tsx`, handles the stream events, saved
+rows, answers, and errors. Steps: [Add agent asks to a chat](../how-to/agent-ui-asks.md).
+
+### BlocksView
+
+`BlocksView` paints a whole-reply document from `@terreno/blocks`. Pass the assistant text
+as `document`. Leaf blocks in this slice are `heading`, `text`, `metric`, `badge`,
+`divider`, and `context`. `columns` is a row from the `md` breakpoint and a stack on `sm`.
+`card` groups children under an optional title. A `callout` draws `Banner` and is not dismissible. An `image` draws `Image` and requires `alt`; pass `imageHosts` to allow `https` hosts. A `details` block draws `Accordion`. A `chart` draws `LineChart`, `BarChart`,
+`AreaChart`, or `DonutChart` from an inline dataset or from `points`. The series is only
+`{label, value}` — a point color in the document is not passed through. A `table` draws
+`DataTable`. A `ref` dataset stays empty until `resolveDataset` returns its rows, and the
+chart shows `loading` while that promise is in flight. A rejected fetch clears that
+loading state. A segmented control highlights the option whose `data` matches the target
+chart or table. A `select` action switches a table the same way it switches a chart.
+An image `file:` ref is not passed to `Image` until `resolveImage` returns a URL; the
+alt text still shows.
+
+A string that is not a document becomes one `text` block. A document that fails
+`validateBlocks` shows a `Banner` with the first three errors and the raw text inside a
+collapsed `Accordion`.
+
+An `actions` block draws `Button` and `SegmentedControl`. `onAction` receives
+`{action, blockId, elementId}` for reply, open, select, and callback. A `select`
+action also stores the chosen dataset on the target chart for this view. Pass
+`hostActions` to disable callback buttons whose names are not in that list. Omit
+`hostActions` and every callback stays enabled. `pendingElementIds` shows those
+buttons as loading. `overrides` replaces a block by id.
+
+```tsx
+<BlocksView
+  document={reply}
+  hostActions={["export_csv"]}
+  onAction={handleAction}
+  testID="assistant-blocks"
+/>
+```
+
+Demo story: `BlocksView`.
+
+### HtmlFrame
+
+`HtmlFrame` paints one `html` block. On web it is an `<iframe sandbox="" referrerpolicy="no-referrer">` whose `srcdoc` starts with a Content-Security-Policy meta tag (`default-src 'none'`). On native it is a WebView with JavaScript off, and navigation after the first load is rejected. `BlocksView` renders that frame only when `allowHtml` is true and `streaming` is false. Otherwise the block is a card that says the preview is off or still arriving. `GPTChat` passes `allowHtml` through.
+
+```tsx
+<HtmlFrame height="md" html="<h1>Invoice</h1>" title="Invoice preview" />
+```
+
+### AskCard
+
+One agent ask in a chat transcript: controls while it is pending, a summary line after. `GPTChat`
+renders it for messages with `ask`. Render it directly in a custom transcript. A saved ask whose
+input no longer validates, or whose `accept` answer has no `content` object, shows the generic
+line ("You answered this question.") and no sent values.
+
+```tsx
+<AskCard ask={ask} errors={errors} onSubmit={handleAskSubmit} testID="plan-ask" />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `ask` | `ChatAsk` | The ask. Pending asks are interactive. Answered and cancelled asks show a summary. |
+| `errors` | `AskValidationError[]` | Errors for the last answer, shown under the controls |
+| `onSubmit` | `AskSubmitHandler` | Called with `{toolCallId, response}`. Without it, the card cannot be answered: buttons and the select are disabled, and radio and checkbox options show as plain text. When the promise it returns rejects, the ask stays open and the card shows "Your answer could not be sent. Try again." until the next answer. |
+| `promptRef` | `React.Ref<Text>` (React Native) | Receives the question's native text, which is an accessibility header. `GPTChat` uses it to move screen reader focus to a pending ask on native. |
+| `resolveAskFiles` | `AskFilesResolver` | For a `files` ask: turns the picked files into refs on Submit. Defaults to data URLs. `GPTChat` passes its own `resolveAskFiles`. |
+| `testID` | string | Defaults to `ask-card`. `GPTChat` passes `gpt-ask-<toolCallId>`. |
+
+A saved ask whose input no longer passes `validateAskInput` shows "This question cannot be shown.
+Send a message to continue." while pending, and "You answered this question." once answered.
+
+`choice` controls:
+
+| Ask | Controls |
+| --- | --- |
+| The simple card has a button for every option (`handoff: false`), and every option label is at most 20 characters | The card's buttons as quick replies, then Skip unless `allowDecline` is `false`. A tap answers. |
+| Up to 8 options | `RadioField`, then Submit (`submitLabel`) and Skip |
+| More than 8 options | Searchable `SelectField`, then Submit and Skip |
+| `select: "many"` | `MultiselectField` with a hint such as "Choose 1 to 3.", then a `TextField` titled `otherLabel` (default "Other") when `allowOther` is `true`, then Submit and Skip |
+
+The selection starts on the ask's `default`. Submit is enabled only when `validateAskResponse`
+accepts the selection. For `select: "many"`, the answer lists the checked ids in option order and
+sends the Other text trimmed, leaving `other` out when the field is blank. When the checked
+options and the Other text add up to more than `maxSelected`, the checkboxes say so ("You chose
+4. Choose at most 3."). An Other text over 500 characters, or a server error at `content.other`,
+shows on the Other field. When `ask.simple` is absent, the card derives it with `toSimpleCard`. An
+ask whose input fails `validateAskInput` shows "This question cannot be shown. Send a message to
+continue." instead of controls.
+
+`confirm` controls: the simple card's two buttons in its order, the approve button (`confirmLabel`,
+default "Confirm") first and the deny button (`denyLabel`, default "Cancel") last. The approve
+button uses the `destructive` variant when the ask sets `destructive: true`, else `primary`; the
+deny button uses `ghost`. Skip follows only when `allowDecline` is `true`. A tap answers
+`{"confirmed": true}` or `{"confirmed": false}`. Without `onSubmit`, both buttons are disabled.
+
+`markdown` controls: a `MarkdownEditorField` (edit and preview, at most 320 pt tall) that starts
+on the ask's `initial` draft and shows `placeholder` while empty, then Submit (`submitLabel`) and
+Skip unless `allowDecline` is `false`. Under the editor a hint gives the length and the bounds,
+such as "1,240 / 2,000 characters. At least 20." Submit is enabled only when
+`validateAskResponse` accepts the text, and it sends `{markdown, changed}` with `changed` true
+when the text differs from `initial`. Text over `maxLength`, or a server error at
+`content.markdown`, shows on the editor. Without `onSubmit`, the editor and both buttons are
+disabled. An answered markdown ask shows the sent text under its summary; text over 280
+characters shows a preview cut at a word, with Show all and Show less.
+
+`form` controls: one field per entry in `fields`, in order, titled with the field's `label`
+("(required)" appended for required fields) and its `helperText`, then Submit (`submitLabel`) and
+Skip unless `allowDecline` is `false`. Each field uses the `@terreno/ui` control for its type:
+
+| Field `type` | Control | Sends |
+| --- | --- | --- |
+| `text`, `email`, `url` | `TextField` (`text`, `email`, `url`) | The trimmed text |
+| `phone` | `TextField` (`phoneNumber`) | E.164, such as `+14155552671`, when the number parses (as a US number without a country code); else the trimmed text |
+| `number` | `TextField` | A number when the text is plain decimal notation; else the text, so validation says why |
+| `textarea` | `TextArea` | The trimmed text |
+| `date` | `DateTimeField` (`date`) | `YYYY-MM-DD` |
+| `time` | `DateTimeField` (`time`) with its time zone picker (the device's zone to start) | 24-hour `HH:mm` as shown; the zone is not sent |
+| `datetime` | `DateTimeField` (`datetime`) with a time zone picker | An ISO datetime with the chosen zone's offset, such as `2026-10-01T09:30:00-07:00` |
+| `boolean` | `BooleanField` | `true` or `false`, always |
+| `select` | `SelectField` | The option id |
+| `multiselect` | `MultiselectField` | The checked option ids |
+
+Fields start on their `default`. Blank fields are left out of `values`. Submit is enabled only
+when `validateAskResponse` accepts the values and no date, time, or datetime field holds an
+unfinished entry. `DateTimeField` reports that through `onEntryStatusChange`, such as
+"0 / 5 / 026": the field says "Enter a complete date, or clear it." until the user finishes it,
+and clearing every part leaves the field out. After the user edits a field, it says what is
+wrong in plain words, such as "Enter a number from 1 to 500." or "This field is required." A
+server error whose path is `content.values.<id>` (or an item under it) shows on that field until
+the user edits it; other errors show under the form. Without `onSubmit`, every field and both
+buttons are disabled. An answered form lists each sent field as its label and a readable value
+(Yes or No, option labels, "Oct 1, 2026", "9:30 AM", text shortened to one line of 80
+characters) under its summary.
+
+`files` controls: a hint built from the counts and types, such as "Up to 3 files: images, PDFs or
+text files.", then a "Choose files" `FilePickerButton` ("Add files" once some are picked), the
+picked files as an `AttachmentPreview` with a remove control on each, then Submit (`submitLabel`,
+default "Submit") and Skip unless `allowDecline` is `false`. The picker offers Photo Library only
+when `accept` has `image`, and its document picker offers only the accepted MIME types. It allows
+several files when `maxFiles` is more than 1 and is disabled once `maxFiles` files are picked.
+Submit is enabled only when `validateAskResponse` accepts the picked names, types, and sizes. On
+Submit, the card calls `resolveAskFiles` with the picked files and sends `{files: refs}`; Submit
+shows a spinner and Skip is disabled until the answer is sent. When the ask ends another way while
+the resolver runs, such as an answer from another tab, its refs are not sent. If the resolver throws, the ask
+stays open and the card shows "The files could not be sent. Try again, or pick them again." Server
+errors, such as `MIME_MISMATCH`, show under the picked files. Each file's type is
+`selectedFileMimeType(file)`, so a CSV a picker reports as `application/vnd.ms-excel` is sent as
+`text/csv`.
+
+| How the ask ended | Summary |
+| --- | --- |
+| `files` `accept` | You sent `<n>` files: `<filenames>`, or You sent 1 file: `<filename>` |
+| `form` `accept` | You sent the form (`<n>` fields) |
+| `markdown` `accept` | You approved the draft as is (`changed: false`), or You edited the draft (`<n>` characters) |
+| `confirm` `accept` | You confirmed: `<confirmLabel>`, or You declined: `<denyLabel>`, with the default labels when the ask sets none |
+| `choice` `accept` | You chose: `<option labels>`. With Other text, it adds "`<otherLabel>`: `<text>`" (the label defaults to "Other"), or shows only that when no option was checked. An empty `select: "many"` answer shows "You chose none of the options." |
+| `decline` | You skipped this question. |
+| `cancel` with `user_sent_message` | Not answered: you sent a message instead. |
+| `cancel` with `one_ask_at_a_time` | Not asked: the assistant asked another question first. |
+| Any other `cancel`, or status `cancelled` without a response | This question was cancelled. |
+| Status `answered` without a response | You answered this question. |
+
+| Element | testID |
+| --- | --- |
+| Card | `{testID}` |
+| Quick reply row | `{testID}-quick-replies` |
+| Quick reply or Skip button | `{testID}-button-<button id>`, such as `{testID}-button-option:team` or `{testID}-button-skip` |
+| Confirm button row | `{testID}-confirm-buttons` |
+| Confirm approve or deny button | `{testID}-button-approve`, `{testID}-button-deny` |
+| Radio options (up to 8) | `{testID}-radio` |
+| Select | `{testID}-select` |
+| Checkboxes (`select: "many"`) | `{testID}-multiselect` |
+| Other text field | `{testID}-other` |
+| Markdown editor, and its text input | `{testID}-editor`, `{testID}-editor-input` |
+| Sent markdown under an answered ask, and its Show all toggle | `{testID}-answer`, `{testID}-answer-toggle` |
+| Form field, and its wrapper | `{testID}-field-<field id>` (a `BooleanField` switch is `{testID}-field-<field id>.switch`), `{testID}-form-field-<field id>` |
+| Sent form values under an answered ask | `{testID}-answer` |
+| Files hint, picker, and picked files | `{testID}-hint`, `{testID}-picker`, `{testID}-selected` |
+| Files that could not be sent | `{testID}-resolve-error` |
+| Radio or checkbox options as plain text, without `onSubmit` | `{testID}-options` |
+| Submit | `{testID}-submit` |
+| Answer errors | `{testID}-errors` |
+| Summary | `{testID}-summary` |
+| Ask that cannot be shown | `{testID}-invalid` |
+| Answer that could not be sent | `{testID}-submit-error` |
+
+Types: `AskCardProps`, `ChatAsk`, `ChatAskState`, `ChatAskStatus`, `AskSubmission`,
+`AskSubmitHandler`, `AskFilesResolver`. Demo story: `AskCard`.
+
+File ref helpers:
+
+| Export | Description |
+| --- | --- |
+| `AskFilesResolver` | `(files: SelectedFile[]) => Promise<AskFileRef[]>`. Throw to keep the ask open. |
+| `resolveAskFilesAsDataUrls` | The default resolver: every file as a `{url}` data URL |
+| `selectedFileToDataUrlRef(file)` | One picked file as `{filename, mimeType, size, url}`. The data URL's media type is `selectedFileMimeType(file)`, and `size` is the decoded byte count. |
+| `selectedFileMimeType(file)` | The picked file's normalized type. When the picker reports none, `application/octet-stream`, or `application/vnd.ms-excel` (Windows reports CSV files so), the type comes from the extension: `.csv`, `.gif`, `.jpeg`, `.jpg`, `.json`, `.pdf`, `.png`, `.txt`, `.webp`. Otherwise the reported type is kept. |
+| `normalizeMimeType(mimeType)` | Drops parameters and lowercases: `Text/CSV; charset=utf-8` becomes `text/csv` |
+
+`FilePickerButton` props used by the files card, also available to any caller:
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `documentTypes` | `string[]` | MIME types the document picker offers. Defaults to PDF, text, CSV, and JSON. An empty list hides Document. |
+| `includeImages` | boolean | Offer Photo Library. Defaults to `true`. When `false`, the button opens the document picker directly. |
+| `text` | string | Shows an outline button with this label instead of the paperclip icon |
+
+`SelectedFile.size` is the file's size in bytes when the picker reports it.
+
+### SimpleAskCard
+
+Any agent ask as its [simple card](agent-ui-asks.md#simple-cards): the title, the question, and up
+to three full-width buttons that each send an exact answer. Use it in narrow layouts, such as a
+watch-sized preview. It reads the card's `kind` only to word the handoff line.
+
+```tsx
+const [runTurn] = useGpthistoriesTurnMutation();
+
+<SimpleAskCard
+  card={pendingAsk.simple}
+  onPress={(button) =>
+    runTurn({
+      body: {buttonId: button.id, surface: "compact", toolCallId: pendingAsk.toolCallId},
+      id: historyId,
+    })
+  }
+  pendingButtonId={sendingButtonId}
+/>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `card` | `SimpleCard` | `pendingAsk.simple` from the server, or `simple` on an `{ask}` event |
+| `onPress` | `(button: SimpleCardButton) => void \| Promise<void>` | Called with the pressed button. Send `{toolCallId: card.toolCallId, buttonId: button.id}` to the history's [`turn` action](agent-ui-asks.md#headless-endpoints), or send `button.response` as the answer. |
+| `pendingButtonId` | string? | The button whose answer is still sending. It shows a spinner, the other buttons are disabled, and presses are ignored. |
+| `testID` | string? | Defaults to `simple-ask-card` |
+
+- A card with `handoff: true` shows "Continue on your phone" under the question, because its
+  buttons cannot give every answer. A `markdown` card shows "Edit on your phone" instead, a
+  `form` card "Fill it in on your phone", and a `files` card "Upload on your phone".
+- Button styles map to `Button` variants the same way as `AskCard` quick replies: `primary` to
+  `primary`, `default` to `outline`, `destructive` to `destructive`, and `cancel` to `ghost`.
+
+| Element | testID |
+| --- | --- |
+| Card | `{testID}` |
+| Continue on your phone, or Edit on your phone | `{testID}-handoff` |
+| Button | `{testID}-button-<button id>`, such as `{testID}-button-option:team` |
+
+Types: `SimpleAskCardProps`, and `SimpleCard` and `SimpleCardButton` from `@terreno/blocks`. Demo
+story: `SimpleAskCard`. Its demo answers a plan card on a watch-sized 198×242 pt screen, and its
+"Every fixture" story draws every valid fixture's card at that size.
+
 ### SplitPage
 
 Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list, and
@@ -401,11 +725,12 @@ Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list
 screens the detail replaces the list until the user goes back.
 
 `desktopChildrenMinWidth` opts into a minimum pixel width for each desktop child when there
-are one or two children. `narrowViewportChildLabels` opts into a labeled full-width pager on
-the narrow viewport. `narrowBelowWidth` uses that viewport when the window is at or below the
-given pixel width; when omitted, the narrow viewport follows `isNarrowViewport()`. These props
-are web only; the native `SplitPage` ignores them. See `SplitPageProps` for when each prop
-applies and what is ignored.
+are one or two children. `childColumnRounding` sets the border radius on each detail child
+column container (defaults to `md`, 4px); the list column is excluded. `narrowViewportChildLabels`
+opts into a labeled full-width pager on the narrow viewport. `narrowBelowWidth` uses that
+viewport when the window is at or below the given pixel width; when omitted, the narrow
+viewport follows `isNarrowViewport()`. These props are web only; the native `SplitPage`
+ignores them. See `SplitPageProps` for when each prop applies and what is ignored.
 `IconButton`'s `backgroundOpacity` tints only that button's background.
 
 ```typescript

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

@@ -0,0 +1,213 @@
+# Task List: Agent UI Asks
+
+**Status:** Phases 1–2 complete and Roast-passed (in review, [PR #1402](https://github.com/TerrenoLabs/terreno/pull/1402)). Phase 5 is the body-component IP (formerly Agent UI Blocks), folded in 2026-10-01 (D28). Phase 3 starts after B1.1 and B2.1.
+**Supporting skills:** `ai-prompt-governance`, `terreno-ui`, `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `update-docs`, `verify-ui-changes`.
+
+Every task is a vertical slice: contract, producer and/or renderer, docs, and Bun tests.
+Work the frontier (tasks whose blockers are complete). Body-component decisions and
+Blocks AC1–AC20 live in [`docs/implementationPlans/agent-ui-asks.md`](../implementationPlans/agent-ui-asks.md)
+under [Body components](../implementationPlans/agent-ui-asks.md#body-components-agent-ui-blocks).
+The design record remains [`docs/implementationPlans/agent-ui-blocks.md`](../implementationPlans/agent-ui-blocks.md).
+
+Tracer: `ask_choice` (select one) through `/gpt/prompt` pause → `askResponse` resume → `GPTChat` card; then the same ask answered by `buttonId` through `POST /gpt/histories/:id/turn`.
+
+### Phase 1: Tracer — "pick one" end to end
+
+- [x] **Task 1.1**: `ask_choice` (select one) pause and resume, proven on the server
+  - Delivers: `@terreno/blocks` asks module with the shared ask fields, `choice` (`select: one` only), `askResponseSchema`, `validateAskInput`, `validateAskResponse`, `toSimpleCard` + `simpleCardSchema` (choice-one rule), `ASK_LIMITS`, `ASK_ERROR_CODES`, and `askPromptSection`. If Agent UI Blocks Task 1.1 has not landed, this task creates the `blocks/` package scaffold exactly as that task lists it. `@terreno/ai`: `asks` route option; `createAskTools(["choice"])` (Zod `inputSchema` + `outputSchema`, no `execute`); `TERRENO_ASKS_SYSTEM_PROMPT` at the top of `prompts.ts`; the `/gpt/prompt` turn logic moved into `chatTurn.ts` behind an event sink so Task 1.3 can drive it without SSE; pause on an ask tool call (SSE `{ask}` with `simple`, `done.pendingAsk`, `GptHistory.pendingAsk` with `simple` and `responseMessages`, a `tool-call` row with `ask.status`); a second ask in one step is stored as `cancel` (`one_ask_at_a_time`); resume via `askResponse` (validate → tool-result row → replay `responseMessages` + tool result → stream, `{askResolved}` first); `cancel` when a `prompt` arrives while an ask is pending; 400 / 403 / 409 paths; `buildMessages` includes ask pairs; `AIRequest.metadata.ask`.
+  - Files: `blocks/src/asks/{schema,limits,errors,validateInput,validateResponse,simpleCard,prompt}.ts`, `blocks/src/asks/fixtures/{valid,invalid}/*.json`, `blocks/src/asks/*.test.ts`, `blocks/src/index.ts`; `ai/package.json`, `ai/src/service/asks.ts`, `ai/src/service/chatTurn.ts`, `ai/src/service/prompts.ts`, `ai/src/routes/gpt.ts`, `ai/src/routes/gptHistories.ts` (server-owned `pendingAsk`, read-only in OpenAPI), `ai/src/models/gptHistory.ts`, `ai/src/service/aiService.ts`, `ai/src/types/index.ts`, `ai/src/index.ts`, `ai/src/aiApp.ts`, `ai/src/routes/gpt.test.ts`, `ai/src/service/aiService.test.ts`, `ai/src/service/asks.test.ts`; package registration (root `package.json`, `knip.jsonc`, `codecov.yml`, `bun.lock`, `.circleci/*`, `.github/workflows/{blocks-ci,ai-ci,cd,publish-on-tag}.yml`, CI scripts under `scripts/`, `example-backend/Dockerfile`); `example-backend/src/__snapshots__/openapi.test.ts.snap`.
+  - Blocked by: none (IP approval)
+  - Docs: `docs/reference/agent-ui-asks.md` (new: envelope, `choice`, limits, error codes, SSE events, wire example), `docs/reference/ai.md` (`asks` option, `askResponse` body, full SSE event table, `GptHistory.pendingAsk`), `docs/explanation/agent-ui-asks.md` (new: why client-side tool calls, the round trip, how asks and blocks divide the work), `docs/reference/README.md`, `docs/explanation/README.md`.
+  - Acceptance: AC1, AC2, and AC15 for `choice` (select one); AC3, AC4, AC5, AC6, AC7, AC8 (the `chatTurn.ts` move is covered by AC8's unchanged-stream regression); mongoose-schema-safety checklist applied to `GptHistory` (additive, optional, described); ai-prompt-governance checklist applied (constant, mock-model tests with normal, edge, and adversarial inputs); `bun test blocks/ ai/` green.
+
+- [x] **Task 1.2**: "Pick one" in `GPTChat`, the example apps, and the demo
+  - Delivers: `GPTChatMessage.ask`; `GPTChat` props `onAskSubmit` and `askErrors`; `AskCard` + `AskChoice` (the simple card's buttons for ≤ 3 options with labels ≤ 20, `RadioField` for ≤ 8, searchable `SelectField` above 8); Skip; inline errors; loading while submitting; answered summary; pending ask restored from history stays interactive. example-backend passes `asks: true`; when no AI model is configured (no `GEMINI_API_KEY`, no Vertex, no per-request key), it uses a scripted demo agent instead of the canned demo reply, so every shipped ask can be tried in the example app without an API key (user directive 2026-09-27: "ensure we have an example-frontend that uses this in the gpt chat so we can test it out"). example-frontend `ai.tsx` handles `{ask}` / `{askResolved}` / `done.pendingAsk` and posts `askResponse` with the same streaming reader as a prompt. Demo `AskCard` story. e2e mock streams an ask, accepts the answer, and streams a continuation.
+  - Files: `ui/package.json`, `ui/src/asks/AskCard.tsx`, `ui/src/asks/AskChoice.tsx`, `ui/src/asks/askSummary.ts`, `ui/src/GPTChat.tsx`, `ui/src/lazyBoundaries/heavyOptionalExports.tsx`, `ui/src/index.tsx`, `ui/src/asks/*.test.tsx`, `ui/src/GPTChat.test.tsx`; `demo/stories/AskCard.stories.tsx`, `demo/story-config/AskCard.config.tsx`, `demo/demoConfig.tsx`; `example-backend/src/api/ai.ts`; `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/e2e/helpers/mockGpt.ts`, `example-frontend/e2e/ai-chat.spec.ts`.
+  - Blocked by: 1.1
+  - Docs: `docs/reference/ui.md` (`GPTChat` ask props, `AskCard`), `docs/how-to/agent-ui-asks.md` (new: enable asks on the backend, handle them in the frontend), `docs/explanation/example-coverage.md` (capability row), `docs/how-to/README.md`; regenerate component reference (`cd ui && bun run compile && bun run types`, then `bun run website:generate`).
+  - Acceptance: AC9 for `choice`; AC12; `bun run check:demo-coverage` green; screenshots of pending, error, and answered states and a recording of the example-app round trip under `/opt/cursor/artifacts/` (verify-ui-changes).
+
+- [x] **Task 1.3**: Small-screen path — simple cards, compact surface, headless endpoints
+  - Delivers: `modelRouter` actions on `/gpt/histories`: `collectionActions.pendingAsks` (`GET`, `IsAuthenticated`, caller's histories only) and `instanceActions.turn` (`POST`, `IsOwner`; body one of `{prompt}`, `{askResponse}`, `{toolCallId, buttonId}`, plus `surface`), both driving `chatTurn.ts` with a buffering sink and returning `{text, pendingAsk?}`; `buttonId` resolves to the stored card's `response` (`UNKNOWN_BUTTON` otherwise); the turn finishes and saves after a client disconnect. `surface: "compact"` on `/gpt/prompt` and `turn` narrows the ask tools and adds the compact prompt line (D25). JSON Schema export of the simple card and headless bodies for native clients. `SimpleAskCard` in `@terreno/ui` and a demo story that renders every fixture's card in a 198×242 pt watch-sized frame.
+  - Files: `ai/src/routes/gptHistories.ts`, `ai/src/service/chatTurn.ts`, `ai/src/service/asks.ts`, `ai/src/service/prompts.ts`, `ai/src/routes/gptHistories.test.ts`, `ai/src/routes/gpt.test.ts`; `blocks/src/asks/schema.ts` (compact variants), `blocks/src/asks/jsonSchema.ts`, tests; `ui/src/asks/SimpleAskCard.tsx`, `ui/src/asks/SimpleAskCard.test.tsx`, `ui/src/index.tsx`; `ui/src/Common.ts` and `ui/src/Button.tsx` (opt-in `wrapText` prop, off by default, set only by `SimpleAskCard` and `AskChoice`), `ui/src/Button.test.tsx`, `ui/src/asks/AskChoice.tsx`, `ui/src/asks/AskCard.test.tsx`; `demo/stories/SimpleAskCard.stories.tsx`, `demo/story-config/SimpleAskCard.config.tsx`, `demo/stories/Button.stories.tsx`, `demo/story-config/Button.config.tsx`, `demo/demoConfig.tsx`; `example-frontend/store/openApiSdk.ts` (regenerated with `bun run sdk`).
+  - Blocked by: 1.2
+  - Docs: `docs/reference/agent-ui-asks.md` (simple card contract, rule table, compact mode, headless endpoints, JSON Schema location), `docs/reference/ai.md` (`surface`, the two actions), `docs/how-to/agent-ui-asks.md` ("answer asks from an Apple Watch or another small client": SwiftUI `URLSession` sketch, token hand-off over WatchConnectivity, why the watch always sends `surface: "compact"`), `docs/explanation/agent-ui-asks.md` (why cards carry exact answers; watch paths and their follow-ups), `docs/reference/ui.md` (`SimpleAskCard`, Button `wrapText`); regenerate component reference (`bun run website:generate`).
+  - Acceptance: AC16, AC17, AC18; AC15 for `choice` cards made in compact mode; watch-frame screenshot under `/opt/cursor/artifacts/` (verify-ui-changes).
+
+### Phase 2: Remaining ask kinds
+
+- [x] **Task 2.1**: `choice` many and "Other"
+  - Delivers: `select: many`, `minSelected` / `maxSelected`, `allowOther` + `otherLabel`; `MultiselectField` plus an Other `TextField`; `SELECTION_COUNT` and `OTHER_NOT_ALLOWED`; simple-card rules for many-select and for single-select with more options than fit (Use suggested / Skip / handoff).
+  - Files: `blocks/src/asks/schema.ts`, `blocks/src/asks/validateResponse.ts`, `blocks/src/asks/simpleCard.ts`, fixtures, tests; `ui/src/asks/AskChoice.tsx`, tests; `demo/stories/AskCard.stories.tsx`. Also touched: `blocks/src/asks/{errors,limits,prompt}.ts`, `blocks/src/index.ts`; `ai/src/service/{asks,prompts}.ts` (full and compact `ask_choice` descriptions); `ui/src/asks/askSummary.ts`; `demo/stories/SimpleAskCard.stories.tsx`, `demo/story-config/AskCard.config.tsx`; `example-backend/src/api/demoAgent.ts` ("pick toppings" scenario); `docs/reference/ui.md`, `docs/how-to/agent-ui-asks.md`, `docs/explanation/{agent-ui-asks,example-coverage}.md`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/agent-ui-asks.md` (`choice` fields, card rules).
+  - Acceptance: AC1, AC2, AC9, and AC15 for many-select and Other; screenshot.
+
+- [x] **Task 2.2**: `confirm`
+  - Delivers: `ask_confirm` (`confirmLabel` / `denyLabel` ≤ 20 chars, `destructive`, `allowDecline` default `false`); two `Button`s, `variant="destructive"` when set; simple card Approve / Deny with the D26 destructive marking; offered in compact mode; prompt guidance to confirm before irreversible tool calls.
+  - Files: `blocks/src/asks/*`, `ai/src/service/asks.ts`, `ai/src/service/prompts.ts`, `ui/src/asks/AskConfirm.tsx`, tests, story. Also touched: `ui/src/asks/askControls.tsx` (controls shared with `AskChoice`), `ui/src/asks/{AskCard,AskChoice}.tsx`, `ui/src/asks/askSummary.ts`; `demo/stories/{AskCard,SimpleAskCard}.stories.tsx`, `demo/story-config/AskCard.config.tsx`; `example-backend/src/api/demoAgent.ts` ("send the weekly report" and "archive old chats" scenarios); `example-frontend/store/{openApiSdk,sdk}.ts`, `example-frontend/app/(tabs)/ai.tsx`; `docs/reference/ui.md`, `docs/explanation/{agent-ui-asks,example-coverage}.md`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/agent-ui-asks.md`, `docs/how-to/agent-ui-asks.md` ("confirm before a destructive tool").
+  - Acceptance: AC1, AC2, AC9, and AC15 for `confirm`; AC16 includes `ask_confirm`; prompt snapshot test lists `confirm` only when enabled.
+
+- [x] **Task 2.3**: `markdown`
+  - Delivers: `ask_markdown` (`initial`, `placeholder`, `minLength`, `maxLength` ≤ 20,000); `MarkdownEditorField`; answer `{markdown, changed}`; long answers collapse in the summary; simple card Approve draft / Cancel with `handoff`.
+  - Files: `blocks/src/asks/*`, `ai/src/service/asks.ts`, `ui/src/asks/AskMarkdown.tsx`, tests, story. Also touched: `ai/src/service/prompts.ts` (`ask_markdown` description); `ui/src/asks/{AskCard,SimpleAskCard}.tsx` ("Edit on your phone" handoff line), `ui/src/asks/askSummary.ts`; `demo/stories/{AskCard,SimpleAskCard}.stories.tsx`, `demo/story-config/AskCard.config.tsx`; `example-backend/src/api/demoAgent.ts` ("draft an announcement" scenario); `example-frontend/store/{openApiSdk,sdk}.ts`, `example-frontend/app/(tabs)/ai.tsx`; `docs/reference/ui.md`, `docs/how-to/agent-ui-asks.md`, `docs/explanation/{agent-ui-asks,example-coverage}.md`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/agent-ui-asks.md`.
+  - Acceptance: AC1, AC2 (`TOO_LONG`), AC9, and AC15 for `markdown`; `changed` is false when the text is unchanged; no Approve button when `initial` breaks the length rules.
+
+- [x] **Task 2.4**: `form`
+  - Delivers: `ask_form` with 1–8 flat fields (`text`, `textarea`, `email`, `url`, `phone`, `number`, `date`, `time`, `datetime`, `boolean`, `select`, `multiselect`); per-type rules; Luxon ISO validation (revised in Pick: Zod ISO validators); renderer maps each field to `Field` by type; simple card Submit defaults / Cancel with `handoff`.
+  - Files: `blocks/src/asks/*`, `ai/src/service/asks.ts`, `ui/src/asks/AskForm.tsx`, tests, story. Also touched: `blocks/src/asks/formValues.ts` (`formDefaultValues`, `formTextMaxLength`), `blocks/src/index.ts`; `ai/src/service/prompts.ts` (`ask_form` description); `ui/src/asks/askFormDraft.ts` (draft, picker, and error-text helpers), `ui/src/asks/{AskCard,SimpleAskCard}.tsx` ("Fill it in on your phone" handoff line), `ui/src/asks/askSummary.ts`; `demo/stories/{AskCard,SimpleAskCard}.stories.tsx`, `demo/story-config/AskCard.config.tsx`; `example-backend/src/api/demoAgent.ts` ("invoice details" scenario), `example-backend/src/__snapshots__/openapi.test.ts.snap`; `example-frontend/store/{openApiSdk,sdk}.ts`, `example-frontend/app/(tabs)/ai.tsx`; `docs/reference/ui.md`, `docs/how-to/agent-ui-asks.md`, `docs/explanation/{agent-ui-asks,example-coverage}.md`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/agent-ui-asks.md` (field-type table).
+  - Acceptance: AC1, AC2 (`REQUIRED_FIELD`, `FIELD_TYPE_MISMATCH`, `OUT_OF_RANGE`, `INVALID_DATE`), AC9, and AC15 for `form`; one fixture per field type.
+
+- [x] **Task 2.5**: `files`
+  - Delivers: `ask_files` (`accept`, `minFiles`, `maxFiles`); `FilePickerButton` + `AttachmentPreview` renderer; file refs `{fileId}` or `{url}` per D5; server ref resolution, owner check, byte-level MIME sniffing, size and count caps; `toModelOutput` with `image-data` / `file-data` / text parts; simple card Skip + `handoff`; an example-frontend helper that uploads through `/files/upload` when available and falls back to data URLs.
+  - Files: `blocks/src/asks/*`, `ai/src/service/askFiles.ts`, `ai/src/service/asks.ts`, `ai/src/routes/gpt.ts`, tests; `ui/src/asks/AskFiles.tsx`, tests, story; `example-frontend/app/(tabs)/ai.tsx`. Also touched: `blocks/src/asks/files.ts` (byte sniffer, data URL parsing), `blocks/schemas/*`; `ai/src/service/{chatTurn,fileStorage}.ts`, `ai/src/routes/files.ts` (upload `id`), `ai/src/aiApp.ts`, `ai/src/types/index.ts`; `ui/src/asks/askFileRefs.ts`, `ui/src/asks/{AskCard,SimpleAskCard,askSummary}.ts(x)`, `ui/src/FilePickerButton.tsx`, `ui/src/GPTChat.tsx`; `demo/stories/{AskCard,SimpleAskCard}.stories.tsx`, `demo/story-config/AskCard.config.tsx`; `example-backend/src/api/{ai,demoAgent}.ts` ("upload a receipt" scenario), `example-backend/src/__snapshots__/openapi.test.ts.snap`; `example-frontend/lib/gptAsks.ts` (`createAskFilesResolver`), `example-frontend/store/{openApiSdk,sdk}.ts`, `example-frontend/e2e/{ai-chat.spec.ts,helpers/mockGpt.ts}`; `docs/reference/{agent-ui-asks,ai,ui}.md`, `docs/how-to/agent-ui-asks.md`, `docs/explanation/{agent-ui-asks,example-coverage}.md`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/agent-ui-asks.md` (`files`, storage modes), `docs/how-to/agent-ui-asks.md` ("accept uploads with or without GCS").
+  - Acceptance: AC10; AC1, AC2 (`FILE_TYPE_NOT_ACCEPTED`, `FILE_TOO_LARGE`, `FILE_COUNT`, `FILE_NOT_OWNED`, `MIME_MISMATCH`), AC9, and AC15 for `files`.
+
+- [x] **Task 2.6**: Server-enforced approval for host tools
+  - Delivers: host tools with AI SDK `needsApproval` pause on `tool-approval-request` as a server-made `confirm` ask (`origin: "approval"`, `toolName`, `approvalId`); `AsksOptions.approvals[toolName]` customizes the prompt and labels, with a default "Allow <toolName>?"; the answer appends `tool-approval-response` and resumes, so the SDK runs or denies the tool; works through `/gpt/prompt` and `turn`; `AIRequest.metadata.ask.origin`. example-backend adds a `deleteCompletedTodos` tool with `needsApproval: true` and a destructive approval prompt.
+  - Files: `ai/src/service/asks.ts`, `ai/src/service/chatTurn.ts`, `ai/src/types/index.ts`, `ai/src/routes/gpt.test.ts`, `ai/src/routes/gptHistories.test.ts`; `example-backend/src/api/ai.ts`.
+  - Blocked by: 2.2
+  - Docs: `docs/reference/agent-ui-asks.md` (approval asks), `docs/reference/ai.md` (`asks.approvals`), `docs/how-to/agent-ui-asks.md` ("require approval before a tool runs").
+  - Acceptance: AC19; AC15 for approval cards (destructive approve button per D26).
+
+### Phase 3: HTML and display additions
+
+Deferred until B1.1 and B2.1 in this file are Roast-passed (D28, revised 2026-10-01).
+
+- [x] **Task 3.1**: Sandboxed `html` block
+  - Delivers: `html` block schema (`title`, `height: sm|md|lg`, `html` ≤ 100,000 bytes) and `HTML_DISABLED` / `HTML_TOO_LARGE` in `@terreno/blocks`; `uiBlocks.html` server option; `sanitizeHtml` in `@terreno/ai` applied to the final document (re-sent with `{replace: text}` when changed); `HtmlFrame` (web `iframe sandbox=""` + injected CSP meta; native WebView with JavaScript and navigation off); `html` renderer in `BlocksView` with a streaming placeholder and an `allowHtml` gate.
+  - Files: `blocks/src/schema.ts`, `blocks/src/errors.ts`, fixtures, tests; `root package.json` (catalog `sanitize-html`), `ai/package.json`, `ai/src/service/sanitizeHtml.ts`, `ai/src/routes/gpt.ts`, tests; `ui/src/HtmlFrame.tsx`, `ui/src/blocks/blockRenderers.tsx`, `ui/src/GPTChat.tsx`, tests; `demo/stories/HtmlFrame.stories.tsx`, `demo/story-config/HtmlFrame.config.tsx`, `demo/demoConfig.tsx`.
+  - Blocked by: 1.1, B1.1, B2.1
+  - Docs: `docs/reference/blocks.md` (`html` row and `uiBlocks.html`; the page exists once Agent UI Blocks Task 1.1 lands), `docs/explanation/agent-ui-asks.md` (threat model: XSS, phishing, exfiltration, clickjacking), `docs/reference/ui.md` (`HtmlFrame`, `allowHtml`); regenerate component reference (`bun run website:generate`).
+  - Acceptance: AC11; `bun run check:licenses` green with the new dependency; screenshot of a sanitized invoice preview on web.
+
+- [x] **Task 3.2**: `callout`, `image`, and `details` blocks
+  - Delivers: three display blocks rendered with `Banner` (not dismissible), `Image` (`alt` required; sources per D27, including the `uiBlocks.imageHosts` allowlist and `IMAGE_HOST_NOT_ALLOWED`), and `Accordion`; schema, lint, renderer, fixtures.
+  - Files: `blocks/src/schema.ts`, `blocks/src/errors.ts`, fixtures, tests; `ai/src/routes/gpt.ts` (`imageHosts` passed to validation), tests; `ui/src/blocks/blockRenderers.tsx`, tests; `demo/stories/BlocksView.stories.tsx`.
+  - Blocked by: B1.1, B2.1
+  - Docs: `docs/reference/blocks.md` (three rows, `imageHosts`), `docs/explanation/agent-ui-asks.md` (why image hosts are allowlisted).
+  - Acceptance: AC20; `BlocksView` renders each block with `@terreno/ui` components only.
+
+### Phase 4: Wrap-up
+
+- [x] **Task 4.1**: Changelog, rules, docs indexes, final gate
+  - Split (2026-09-27, Pick–Roast loop): Phase 3 is blocked on another plan, so this task ships the wrap-up for Phases 1–2 now; Tasks 3.1 and 3.2 add their own changelog, rules, and index lines when they land.
+  - Delivers: changelog entry; agent rules updated in their canonical source and regenerated; every new page linked from its README; `.github` and knip config updated for new files.
+  - Files: `changelog/unreleased/agent-ui-asks.md`, `.rulesync/rules/ai/00-ai.md`, `.rulesync/rules/ui/00-ui.md`, `docs/how-to/README.md`, `docs/reference/README.md`, `docs/explanation/README.md`, `knip.jsonc`.
+  - Blocked by: 1.3, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 3.1, 3.2
+  - Docs: as listed; `bun run rules`.
+  - Acceptance: AC13, AC14; `bun run website:build` and `bun run rules:check` green.
+
+### Phase 5: Body components — whole-reply YAML
+
+Folded from [`docs/tasks/agent-ui-blocks.md`](./agent-ui-blocks.md) on 2026-10-01 (D28).
+Ids here are B1.1–B4.2 so they do not collide with asks tasks. Acceptance ids are
+Blocks AC1–AC20 in the asks plan. `@terreno/blocks` already exists; B1.1 extends it.
+Chart components from PR #1302 are on master, so B2.2 is not blocked on that PR.
+Wire format is whole-reply YAML (BD2): no fences required.
+
+- [x] **Task B1.1**: Zod schema, parser, structural validation for leaf and layout blocks
+  - Delivers: `parseBlocks(text)` (strips an optional surrounding 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. The package scaffold from the original Task 1.1 already shipped with asks; this task adds the display schema, catalog `yaml`, and fixtures. It does not add chart, table, actions, datasets, or partial parse.
+  - Files: `blocks/package.json` (`yaml`), `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` (catalog `yaml`).
+  - Blocked by: none
+  - Docs: `docs/reference/blocks.md` (new: grammar tables, limits, error codes for this slice), `docs/explanation/agent-ui-blocks.md` (new: why a closed catalog, why whole-reply YAML, ownership), `docs/reference/README.md`, `docs/explanation/README.md`.
+  - Acceptance: Blocks AC1 for the leaf + layout blocks, including a prose-only `text` document; Blocks 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.
+
+- [x] **Task B1.2**: Datasets, chart and table schema, semantic lint
+  - Delivers: `datasets` map with `inline` and `ref`; `chart` and `table` blocks; lint for dataset refs, column existence/type, row arity, id uniqueness, BD7 limits, 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: B1.1
+  - Docs: `docs/reference/blocks.md` (dataset sources, chart, table, warning codes).
+  - Acceptance: Blocks AC2 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`); Blocks AC18 (`ref` half); Blocks AC3; doc-code parity test.
+
+- [x] **Task B1.3**: Actions schema, partial parser, JSON Schema, prompt section, CLI
+  - Delivers: `actions` with `button`/`segmented` and `reply` / `open` / `select` / `callback`; `UNKNOWN_HOST_ACTION` when an allowlist is supplied; `parseBlocksPartial`; `blocksJsonSchema`; `blocksPromptSection`; `terreno-blocks validate` CLI.
+  - 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: B1.2
+  - Docs: `docs/reference/blocks.md` (actions, partial parsing, CLI), `docs/how-to/agent-ui-blocks.md` ("validate a document locally" only).
+  - Acceptance: Blocks AC4; Blocks AC20 (`parsePartial` half); `SELECT_TARGET_INVALID`; CLI exit codes 0/1; prompt snapshot equals `BLOCK_LIMITS`.
+
+- [x] **Task B2.1**: `BlocksView` for leaf and layout blocks
+  - Delivers: `BlocksView` renders heading/text/metric/badge/divider/context/columns/card; invalid → `Banner` + collapsed raw YAML; non-document → `wrapAsTextDocument`; `columns` stacks on `sm`.
+  - Files: `ui/package.json`, `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksError.tsx`, `ui/src/Common.ts`, `ui/src/lazyBoundaries/heavyOptionalExports.tsx`, `ui/src/index.tsx`, tests, `demo/stories/BlocksView.stories.tsx`, `demo/story-config/BlocksView.config.tsx`, `demo/demoConfig.tsx`.
+  - Blocked by: B1.1
+  - Docs: `docs/reference/ui.md`, `docs/explanation/agent-ui-blocks.md`.
+  - Acceptance: Blocks AC5 for the covered blocks; Blocks AC6; `bun run check:demo-coverage`; screenshot under `/opt/cursor/artifacts/`.
+
+- [x] **Task B2.2**: Chart and table blocks bound to datasets
+  - Delivers: `chart` and `table` renderers; `resolveDataset` / `useResolvedDatasets`; no per-point `color` for the agent.
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/datasetToPoints.ts`, `ui/src/blocks/useResolvedDatasets.ts`, tests, demo story.
+  - Blocked by: B1.2, B2.1
+  - Docs: `docs/reference/ui.md`, `docs/how-to/charts-and-dashboards.md` (one paragraph).
+  - Acceptance: Blocks AC5 for chart/table; `datasetToPoints` and `useResolvedDatasets` tests; screenshot of bar + donut.
+
+- [x] **Task B2.3**: Actions, `onAction`, segmented dataset switch
+  - Delivers: `Button` / `SegmentedControl`; `onAction`; local `select`; disabled unknown callbacks; `pendingElementIds`; `overrides`.
+  - Files: `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/useBlockSelections.ts`, `ui/src/Common.ts`, tests, story.
+  - Blocked by: B1.3, B2.2
+  - Docs: `docs/reference/ui.md`, `docs/explanation/agent-ui-blocks.md`.
+  - Acceptance: Blocks AC8; Blocks AC19 (`BlocksView` half).
+
+- [x] **Task B2.4**: `GPTChat` `uiBlocks` mode and Blocks Playground
+  - Delivers: `uiBlocks` renders assistant messages through `BlocksView` (partial while streaming); `onBlockAction`, `onBlockCallback`, `resolveDataset`; playground story.
+  - 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: B2.3
+  - Docs: `docs/reference/ui.md`, `docs/how-to/agent-ui-blocks.md`.
+  - Acceptance: Blocks AC7; Blocks AC19 (`GPTChat` half); Blocks AC20 (`GPTChat` half); `uiBlocks` off regression; playground recording.
+
+- [x] **Task B3.1**: `uiBlocks` route option, prompt, post-stream validation, repair
+  - Delivers: `addGptRoutes` `uiBlocks` option; final-step document; SSE `{blocks}` before `{done}`; optional one repair pass; errors stored for the next turn.
+  - Files: `ai/package.json`, `ai/src/service/prompts.ts`, `ai/src/routes/gpt.ts`, `ai/src/types/index.ts`, `ai/src/routes/gpt.test.ts`.
+  - Blocked by: B1.3
+  - Docs: `docs/reference/ai.md`, `docs/how-to/agent-ui-blocks.md`.
+  - Acceptance: Blocks AC9; Blocks AC18 (`UNKNOWN_HOST_ACTION` half); prompt constant at top of `prompts.ts`; no change when `uiBlocks` is off.
+
+- [x] **Task B3.4**: `AIDataset`, `registerAiDataset`, `GET /gpt/datasets/:id`
+  - Delivers: model, TTL, row cap, grain bucketing, LTTB, pagination, `IsOwner`.
+  - Files: `ai/src/models/aiDataset.ts`, `ai/src/service/aiDatasets.ts`, `ai/src/routes/gptDatasets.ts`, `ai/src/routes/gpt.ts`, tests.
+  - Blocked by: B1.2
+  - Docs: `docs/reference/ai.md`, `docs/explanation/agent-ui-blocks.md`, `docs/how-to/agent-ui-blocks.md`.
+  - Acceptance: Blocks AC16; mongoose-schema-safety on the new model.
+
+- [x] **Task B3.5**: `POST /gpt/actions`
+  - Delivers: host callback route, payload validation, 10 s timeout, `ui_action` log.
+  - Files: `ai/src/routes/gptActions.ts`, `ai/src/routes/gpt.ts`, `ai/src/types/index.ts`, `ai/src/routes/gptActions.test.ts`, `ai/src/models/aiRequest.ts`.
+  - Blocked by: B3.1
+  - Docs: `docs/reference/ai.md`, `docs/how-to/agent-ui-blocks.md`, `docs/explanation/agent-ui-blocks.md`.
+  - Acceptance: Blocks AC17.
+
+- [x] **Task B3.2**: `AIService.generateBlocks`
+  - Delivers: object output, `validateBlocks`, one repair retry, `requestType: "ui_blocks"`.
+  - Files: `ai/src/service/aiService.ts`, `ai/src/types/index.ts`, `ai/src/service/aiService.test.ts`.
+  - Blocked by: B3.1
+  - Docs: `docs/reference/ai.md`.
+  - Acceptance: Blocks AC10.
+
+- [x] **Task B3.3**: MCP validator tool
+  - Delivers: `terreno_validate_ui_blocks`.
+  - Files: `mcp-server/package.json`, `mcp-server/src/tools.ts`, `mcp-server/src/tools.test.ts`.
+  - Blocked by: B1.3
+  - Docs: `docs/reference/mcp-server.md`, `.rulesync/rules/mcp-server/00-mcp-server.md`.
+  - Acceptance: Blocks AC11.
+
+- [x] **Task B4.1**: example-frontend renders blocks and handles actions
+  - Delivers: AI tab `uiBlocks`, dataset and action wiring, e2e mock document.
+  - Files: `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/store/openApiSdk.ts`, `example-frontend/e2e/helpers/mockGpt.ts`, `example-frontend/e2e/ai-chat.spec.ts`.
+  - Blocked by: B2.4, B3.1, B3.4, B3.5
+  - Docs: `docs/how-to/agent-ui-blocks.md`, `docs/explanation/example-coverage.md`.
+  - Acceptance: Blocks AC13; recording under `/opt/cursor/artifacts/`.
+
+- [x] **Task B4.2**: example-backend enable, changelog, docs sweep
+  - Delivers: `uiBlocks` host action and `todoStats` dataset tool; changelog; indexes; rules.
+  - 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 READMEs, `.rulesync/rules/ui/00-ui.md`.
+  - Blocked by: B4.1, B3.2, B3.3
+  - Docs: as listed.
+  - Acceptance: Blocks AC14, Blocks AC15.

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

@@ -1,11 +1,12 @@
 # Task List: Agent UI Blocks
 
-**Status:** Approved 2026-09-15 — ready for Pick (`docs/implementationPlans/agent-ui-blocks.md`). Wire format is whole-reply YAML (D2 = b): no fences anywhere in this list.
+**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`