@terreno/mcp 57.18.0 → 57.19.2

package/dist/docs/versioned/57.18.0/scans/reduce-cold-compile-time/charter.md

@@ -0,0 +1,129 @@
+# Scan charter — reduce cold `bun run compile` wall-clock time
+
+- Slug: reduce-cold-compile-time
+- Status: approved (2026-09-20)
+- Owner: joshgachnang
+
+## Goal
+
+The terreno monorepo compiles with per-package standalone `tsc` and no build
+cache, TS project references, or shared-dep deduplication. A full cold
+`bun run compile` currently takes ~305s, and the pipeline recompiles shared
+packages (`@terreno/test`, `@terreno/api`, `@terreno/syncdb`, `@terreno/jobs`)
+multiple times per run. This campaign cuts cold compile wall-clock by 30% by
+removing redundant tsc passes, deduplicating shared-dependency recompiles,
+introducing project references, and trimming non-typecheck work from the compile
+path — without changing published dist output or weakening type-safety. Faster
+compiles shorten every bootstrap, CI run, and agent iteration.
+
+## Metric
+
+| Field | Value |
+| --- | --- |
+| Name | Cold full-monorepo compile wall-clock |
+| Command | `find . -maxdepth 2 -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete; rm -rf */dist; time bun run compile` (min of 3 runs, seconds) |
+| Unit | s |
+| Direction | down |
+| Protocol | Cold (dist + tsbuildinfo removed before each run), best (min) of 3 consecutive runs, same VM |
+| Baseline | 305 (measured 2026-09-20) |
+| Target | 214 |
+| Horizon | 4 rounds |
+
+Baseline evidence:
+
+```text
+run1 exit=0 elapsed=321s
+run2 exit=0 elapsed=305s
+run3 exit=0 elapsed=309s
+# best of 3 = 305s ; target -30% = 214s
+```
+
+## Scope
+
+- In scope: build/compile configuration only — root `package.json` compile
+  scripts, per-package `tsconfig.json` / `tsconfig.server.json`,
+  `.github/scripts/compile-workspace-deps.js`, per-package `compile` scripts,
+  and any new build tooling that measurably reduces cold compile time.
+- Out of scope: product/source logic, test assertions, runtime behavior,
+  dependency version bumps unrelated to the build.
+- Unacceptable trade-offs:
+  - **Published dist output must stay intact** — `declaration` (.d.ts) emit and
+    the published `dist/` layout for every `@terreno/*` package are preserved.
+  - **No type-safety loss** — no loosening `strict`/`strictNullChecks`, no
+    removing existing `skipLibCheck`, no `noEmit`-to-skip-checks tricks. Adding
+    `skipLibCheck` where absent is allowed.
+  - Publish-time behavior of `compile-workspace-deps.js` must be preserved
+    (it exists because tag-publish replaces `workspace:*` refs before install).
+
+New build dependencies ARE permitted (owner did not exclude them), provided the
+two guardrails above hold.
+
+## Detection rules
+
+| Rule | Query | Matches | Why it moves the metric | Hits |
+| --- | --- | --- | --- | --- |
+| redundant-pipeline | Inspect root `compile` script; `grep -rl compile-workspace-deps */package.json` | Root `compile` runs `@terreno/test` and `@terreno/api` explicitly, then `--filter '*'` recompiles them again; `api` and `admin-backend` re-`tsc` shared deps via `compile-workspace-deps.js` | Every duplicate tsc pass of a large package (api=90k LOC, syncdb, test) is pure cold-time waste | 4 |
+| no-project-references | For each compile-path tsconfig: `grep -L '"references"'`; check for a root solution tsconfig | 19 tsconfigs compile as isolated `tsc` with no `references`; no root solution tsconfig | Project references (`tsc -b`) compile each package once in dep order and enable parallelism, killing recompile overlap | 19 |
+| non-typecheck-work-in-compile | `grep -E 'sync-\|cp \|&&.*&&'` in each package `compile` script | `mcp-server` runs 3 doc-sync scripts at 8GB heap plus a `cp` before/around its `tsc` on every compile | Non-tsc work on the compile critical path adds fixed cold-time cost unrelated to type-checking | 1 |
+| missing-skiplibcheck | For each compile-participating tsconfig: `grep '"skipLibCheck"'` | `demo/tsconfig.json` and `website/tsconfig.json` lack `skipLibCheck` (their compile scripts use these configs) | Without `skipLibCheck`, tsc type-checks every `.d.ts` in the dependency tree — costly for RN/Expo/docs dep trees | 2 |
+
+## Exclusions
+
+Beyond the map-reduce defaults: `node_modules/`, `*/dist/`, `patches/`,
+`terraform/`, generated files (`openApiSdk.ts`, `plugins/terreno-claude/`), and
+`example-frontend` (no `compile` script — not on the compile path).
+
+## Validity rule
+
+A finding is valid only when applying it measurably reduces cold `bun run compile`
+wall-clock (best-of-3) while keeping published dist output identical and
+type-safety unchanged.
+
+## Severity rubric
+
+| Severity | Threshold |
+| --- | --- |
+| high | Plausibly removes ≥30s of cold compile time |
+| medium | Plausibly removes 5–30s |
+| low | Plausibly removes <5s |
+
+Effort: S = under an hour, M = under a day, L = more than a day or needs design.
+
+## Slice policy
+
+- Maximum 4 files and 3 findings per slice.
+- Never mix: a project-references migration with unrelated tsconfig flag tweaks;
+  or `compile-workspace-deps.js` changes with anything else.
+- Always its own slice: the `tsc -b` / project-references migration (touches
+  every package + CI; reviewer-heavy) and any `compile-workspace-deps.js`
+  change (publish-time behavior risk).
+
+## Review routing
+
+| Field | Value |
+| --- | --- |
+| Mode | fixed |
+| Reviewers | @joshgachnang |
+| Assignee | @joshgachnang |
+| Teams | — |
+| Draft | no |
+| Labels | reduce-cold-compile-time, build-perf |
+| Merge policy | human |
+| Notify | PR body mention |
+
+## Budget
+
+- Rounds: 4
+- Slices per round: 2
+- Open PRs at once (`wipLimit`): 1
+- Minimum metric step per round before reporting diminishing returns: 10s
+
+## Decisions
+
+| Decision | Question that prompted it |
+| --- | --- |
+| Goal = reduce cold `bun run compile` wall-clock | "What goal should this scan campaign drive toward?" |
+| Target = 214s (−30% of 305s baseline) | "How aggressive a cold-compile reduction should this campaign target?" |
+| Guardrails = keep published dist output + no type-safety loss; new build deps allowed | "What must this campaign NOT break while cutting compile time?" |
+| Review = fixed @joshgachnang, human merge | "Who reviews the campaign's PRs, and what's the merge policy?" |
+| Budget = 1 open PR, 2 slices/round, 4 rounds | "How much work-in-progress should the campaign carry per round?" |

package/dist/docs/versioned/57.18.0/scans/reduce-cold-compile-time/round-1-findings.md

@@ -0,0 +1,62 @@
+# Round 1 findings — reduce cold `bun run compile` time
+
+- Goal: reduce cold `bun run compile` wall-clock across the terreno monorepo
+- Metric: cold compile seconds (best of 3). **Baseline 305s → target 214s (−30%)**
+- Head: `f8779a96`
+- Kept: 4 findings · Merged: 2 candidates · Dropped: 2 candidates
+
+## Measured evidence (Sift verification)
+
+| Measurement | Result |
+| --- | --- |
+| `@terreno/test` compile (cold) | 10s |
+| `@terreno/api` compile FULL (compile-workspace-deps + tsc, cold) | 50s |
+| `@terreno/api` tsc-only (deps prebuilt) | 31s → compile-workspace-deps adds **~19s per api compile** |
+| demo `tsc --noEmit` without vs with `--skipLibCheck` | 10s vs 10s → **0s** delta |
+| mcp-server sync scripts (sync-ui / sync-versioned / sync-package) | 0s + 5s + 0s = **~5s** |
+
+## Ranked findings
+
+| # | ID | Rule | Sev | Conf | Effort | Est. cold-time saving | Anchors |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | redundant-explicit-prefix | redundant-pipeline | high | high | S* | ~60s (1× test + 1× api) | `package.json:223` |
+| 2 | compile-workspace-deps-overlap | redundant-pipeline | high | high | M | ~19s+ per api compile, ×2–3 dependents | `.github/scripts/compile-workspace-deps.js:22`, `api/package.json:117`, `admin-backend/package.json:47` |
+| 3 | no-project-references | no-project-references | high | medium | L | large but unquantified; durable fix that enables #1/#2 safely | `api/tsconfig.json:1` + 18 more; no root solution tsconfig |
+| 4 | mcp-doc-sync-on-compile-path | non-typecheck-work-in-compile | medium | high | S | ~5s | `mcp-server/package.json:52` |
+
+\* #1 is a one-line edit but is **load-bearing for build ordering** — safe only once #2/#3 provide dependency-ordered builds. See coupling note below.
+
+## High-severity findings (adversarial verification)
+
+### 1. Redundant explicit `test`+`api` prefixes in root compile — CONFIRMED
+Root `compile` = `bun run --filter '@terreno/test' compile && bun run --filter '@terreno/api' compile && bun run --filter '*' compile`. The final `--filter '*'` already builds all 19 workspaces including `test` and `api`, so the two prefixes are a full extra cold compile of test (10s) + api (50s) = **~60s of duplication**.
+
+*Refutation attempted:* "The prefixes force build order; removing them breaks `*`." → Partially holds. `compile-workspace-deps.js` makes api self-build its deps, so api compiles fine inside `*`; but bun `--filter '*'` gives no guaranteed dependency order, so the prefixes currently serve as a crude ordering hack. Verdict: the **duplication is real and confirmed**, but the safe fix is to introduce real ordering (#2/#3), not to blindly delete the prefixes. Kept high.
+
+### 2. compile-workspace-deps.js re-tsc's shared deps every compile — CONFIRMED
+`compile-workspace-deps.js:22` (`const compiled = new Set()`) dedupes only within one node process. Each package's compile runs in its own `bun run` process, so api re-builds test+syncdb (+19s measured over tsc-only), and admin-backend re-builds api (~50s!)+jobs+test — while `--filter '*'` also builds those same packages as their own targets. Shared deps are cold-compiled multiple times per run.
+
+*Refutation attempted:* "The script is required so deps' `dist` exists before dependents compile." → Holds for the current unordered `*` build, and the script's own doc comment says it exists for tag-publish (post-`workspace:*`-replacement installs). Verdict: confirmed redundant **for the dev/monorepo build**; the fix must preserve publish-time behavior (charter guardrail) and supply ordering another way. Kept high, effort M.
+
+### 3. No TS project references / `tsc -b` solution build — CONFIRMED
+No package tsconfig has `references` or `composite`, and there is no root solution tsconfig (`grep -c '"composite"'` → 0 everywhere; `ls tsconfig.json` → not found). Every package is a full standalone `tsc`.
+
+*Refutation attempted:* "Project references help warm builds (via .tsbuildinfo reuse), not cold — this campaign measures cold." → Fails: even cold, `tsc -b` walks the reference graph and compiles each package **exactly once** in dependency order and parallelizes independent leaves, eliminating the multi-recompile waste that #1 and #2 describe. It is the durable structural fix that makes #1 and #2 safe. Verdict: confirmed high; magnitude unproven without doing the migration → confidence medium, effort L.
+
+## Coupling note (for Plot)
+
+Findings #1, #2, #3 are one problem at three depths: the pipeline recompiles shared packages because there is no dependency-ordered build. #3 (project references) is the durable fix and would subsume #1/#2. A lighter interim fix is bun topological filter ordering. Per charter slice policy: the project-references migration and any `compile-workspace-deps.js` change each get **their own slice**. Finding #4 is fully independent and is the cheapest standalone win.
+
+## Merged candidates
+
+- `s1-pipeline-3` ("test compiled 3×") — folded into #1 and #2; it is the same duplication counted from test's side.
+- `s3-mcpwork-2` ("8GB heap flag on copy scripts") — folded into #4; negligible sub-part of the same compile string.
+
+## Dropped candidates
+
+| Candidate | Reason |
+| --- | --- |
+| `s4-skiplibcheck-1` (demo) | **Invalid — refuted.** `skipLibCheck` is already inherited from `expo/tsconfig.base` (`skipLibCheck: true`). Measured delta 10s vs 10s = 0s. No metric movement. |
+| `s4-skiplibcheck-2` (website) | **Invalid — refuted.** `skipLibCheck` already inherited from `@docusaurus/tsconfig` (`skipLibCheck: true`). `--noEmit` + tiny source set → no measurable movement. |
+
+Drop reasons: 2/2 = already-satisfied-via-inheritance / no-metric-movement.

package/dist/docs/versioned/57.18.0/tasks/README.md

@@ -0,0 +1,53 @@
+# Task lists
+
+Bot-consumable execution checklists. Most files pair with an implementation plan (IP)
+as described in [`docs/implementationPlans/README.md`](../implementationPlans/README.md):
+
+- **IP** (`docs/implementationPlans/<slug>.md`) — the design: what and why.
+- **Task list** (`docs/tasks/<slug>.md`) — the steps: the concrete, ordered work.
+
+The filename slug matches the IP it belongs to.
+
+The loop's small-feature profile may use a task file with `**Feature profile:** true` and
+no full IP when repository policy permits. The destination, scope, decisions, acceptance
+criteria, tracer, and verification seam live in that durable contract so Pick can
+implement one task, roast it, and continue to the next without conversation history.
+
+## Task shape
+
+Each task is a tracer-bullet vertical slice with explicit blocking edges:
+
+```markdown
+- [ ] **Task 1.1**: Short title
+  - Delivers: the narrow end-to-end behavior this makes usable
+  - Files: expected files to create or modify
+  - Blocked by: none | other task IDs
+  - Acceptance: observable proof, including focused Bun tests
+```
+
+Group tasks by phase (`### Phase 1: …`) and order them by dependency. Every normal task
+cuts through the required data, API, UI, documentation, and test layers rather than
+batching one layer across the whole feature. A completed task is demoable or independently
+verifiable and small enough for one fresh agent context. Work the **frontier**: any task
+whose blockers are complete.
+
+Wide mechanical refactors that cannot land green as vertical slices use
+**expand → migrate batches → contract**. The contract task is blocked by every migration
+batch. Grow-style runs may append a **Plan vs Actual** log after each task.
+
+## What lives here vs elsewhere
+
+| Concern | Home |
+| ------- | ---- |
+| Design, scope, acceptance criteria | the IP (`docs/implementationPlans/`) |
+| Concrete task steps and their status | this directory |
+| Public status and target | GitHub roadmap issue / Project (roadmap-enabled repos) |
+| Sprint estimates and assignees | Linear |
+| Current stage/attempt/head/result | loop-owned execution state (default `.terreno/pipeline/<slug>.json`) |
+
+Do not copy the full checklist into a GitHub issue or Linear. Create linked GitHub child
+issues only for tasks that outside contributors should be able to claim independently; the
+task file stays the source of truth for scope and acceptance.
+
+The docs site excludes this directory, so link to task files with full GitHub URLs from
+pages that render on the site.

package/dist/docs/versioned/57.18.0/tasks/admin-scripts-durable-jobs.md

@@ -0,0 +1,10 @@
+# Tasks: Admin scripts via durable jobs
+
+**IP:** [admin-scripts-durable-jobs.md](../implementationPlans/admin-scripts-durable-jobs.md)
+
+- [x] **Task 1**: `admin/script` adapter (`defineAdminScriptJob`, payload parse, dual-write `BackgroundTask`)
+- [x] **Task 2**: `AdminApp` enqueue/cancel when `JobsApp` is registered; in-process fallback
+- [x] **Task 3**: example-backend worker + API share `defineAdminScriptJob(adminScripts)`
+- [x] **Task 4**: Docs (how-to jobs, jobs reference, admin-backend scripts)
+- [x] **Task 5**: Example GCP runtime selects `GcpCloudTasksRunner` and verifies callback OIDC
+- [x] **Task 6**: CD supplies `JOBS_RUNNER=gcp-cloud-tasks` and per-PR callback URLs

package/dist/docs/versioned/57.18.0/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.