@terreno/mcp 57.17.0 → 57.18.0

package/src/docs/versioned/57.17.0/tasks/admin-only.md

@@ -0,0 +1,223 @@
+# Task List: Admin-Only — Serve Admin SPA From a Terreno Backend
+
+**Status:** Closed (2026-08-20) — IP complete. Shipped as `@terreno/admin-spa`. Open tasks below were not executed; see shipped code in `admin-spa/`.
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+See: `docs/implementationPlans/admin-only.md` for full plan.
+
+## Phase 0: admin-frontend prop split (prerequisite — verified blocker)
+
+- [ ] **Task 0.1**: Split `baseUrl` → `apiBase` + `routeBase` across admin-frontend
+  - Description: Add optional `apiBase` and `routeBase` props alongside the existing `baseUrl` to every exported admin-frontend component. Internally resolve `const apiBase = props.apiBase ?? props.baseUrl; const routeBase = props.routeBase ?? props.baseUrl;`. Replace each occurrence: `useAdminConfig(api, baseUrl)` → `useAdminConfig(api, apiBase)`; `useAdminApi(api, baseUrl, modelName)` → `useAdminApi(api, apiBase, modelName)`; every `router.push(\`${baseUrl}/...\`)` and `href: \`${baseUrl}/...\`` → use `routeBase` instead.
+  - Files: `admin-frontend/src/AdminModelList.tsx`, `AdminModelTable.tsx`, `AdminModelForm.tsx`, `AdminRefField.tsx`, `AdminScriptList.tsx`, `AdminVersionConfig.tsx`, `ConfigurationScreen.tsx`, `useAdminConfig.tsx`, `useAdminApi.ts`, `AdminScriptRunModal.tsx` (if it references baseUrl)
+  - Depends on: none
+  - Acceptance: `bun run admin-frontend:lint` + `bun run admin-frontend:compile` pass. Type-check passes.
+
+- [ ] **Task 0.2**: Tests for prop split
+  - Description: Add a focused test asserting that when `apiBase="/admin"` + `routeBase="/console"` are passed, `useAdminConfig` is called with `/admin` and `router.push` is invoked with `/console/${modelName}`. Also assert backward-compat: `baseUrl="/admin"` alone still works (both internally default to `/admin`).
+  - Files: `admin-frontend/src/AdminModelList.test.tsx`, `AdminModelTable.test.tsx`
+  - Depends on: 0.1
+  - Acceptance: `bun run admin-frontend:test` passes with new assertions.
+
+- [ ] **Task 0.3**: Verify embedded admin still works
+  - Description: Run `example-frontend` against `example-backend`. Log in as admin, navigate to `/admin`, click through a model. Verify no regression. No code change expected — this is a verification step.
+  - Files: (manual)
+  - Depends on: 0.1
+  - Acceptance: All embedded admin flows in example-frontend render and function identically to pre-Phase 0.
+
+## Phase 1: Package scaffolding
+
+- [ ] **Task 1.1**: Create `admin-spa/` workspace package files
+  - Description: Create `package.json` (`@terreno/admin-spa`, version 0.13.0, deps mirror needed runtime: `@terreno/admin-frontend`, `@terreno/rtk`, `@terreno/ui`, `expo`, `expo-router`, `react`, `react-native-web`, `redux-persist`, `better-auth`; peer dep `@terreno/api`; dev deps mirror `example-frontend`). Add `tsconfig.json` (extends Expo preset, covers `app/`, `store/`, `components/`), `tsconfig.server.json` (covers `src/`, outputs `src/dist/`), `biome.jsonc` and `bunfig.toml` copied from `admin-frontend`, `babel.config.js` and `metro.config.js` copied from `example-frontend` (with workspace path adjustments), `app.json` with `web.output: "static"` and `extra.BASE_URL: "__SAME_ORIGIN__"`.
+  - Files: `admin-spa/package.json`, `admin-spa/tsconfig.json`, `admin-spa/tsconfig.server.json`, `admin-spa/biome.jsonc`, `admin-spa/bunfig.toml`, `admin-spa/babel.config.js`, `admin-spa/metro.config.js`, `admin-spa/app.json`, `admin-spa/.gitignore` (must include `dist/`, `store/openApiSdk.ts`, `src/dist/`)
+  - Depends on: none
+  - Acceptance: `bun install` from root succeeds; `bun run --filter '@terreno/admin-spa' compile` is a no-op (succeeds with no source yet).
+
+- [ ] **Task 1.2**: Register workspace in root and add scripts
+  - Description: Add `"admin-spa"` to `workspaces` array in root `package.json`. Add `admin-spa:compile`, `admin-spa:lint`, `admin-spa:test`, `admin-spa:build`, `admin-spa:sdk` scripts mirroring the admin-backend/admin-frontend convention.
+  - Files: `package.json` (root)
+  - Depends on: 1.1
+  - Acceptance: `bun install` resolves admin-spa; `bun run admin-spa:lint` runs (even with no source).
+
+- [ ] **Task 1.3**: Stub server-side plugin entry
+  - Description: Create `src/index.ts` exporting `AdminSpaServeApp` (stub class implementing `TerrenoPlugin` with empty `register()`). Create `src/appConfig.ts` with `AdminSpaAppConfig` interface and `DEFAULT_APP_CONFIG`. Run `tsc -p tsconfig.server.json` and verify `src/dist/` is produced.
+  - Files: `admin-spa/src/index.ts`, `admin-spa/src/appConfig.ts`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' compile` outputs `src/dist/index.js` and `src/dist/appConfig.js`.
+
+- [ ] **Task 1.4**: Stub Expo Router app entry
+  - Description: Create minimal `app/_layout.tsx` (just `<Stack/>`) and `app/index.tsx` rendering a `<Box>Hello admin</Box>` from `@terreno/ui`. Goal: verify the static export pipeline works end-to-end before adding real logic.
+  - Files: `admin-spa/app/_layout.tsx`, `admin-spa/app/index.tsx`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' build:web` produces `dist/index.html`, `dist/_expo/...`, no errors. Open `dist/index.html` in a browser → "Hello admin" renders.
+
+## Phase 2: Same-origin BASE_URL support
+
+- [ ] **Task 2.1**: Add `__SAME_ORIGIN__` sentinel to `@terreno/rtk`
+  - Description: Add `export const SAME_ORIGIN_SENTINEL = "__SAME_ORIGIN__";` to `rtk/src/constants.ts`. Modify `resolveBaseUrls` signature to accept optional `windowOrigin?: string`. When `baseFromExtra === SAME_ORIGIN_SENTINEL` and `windowOrigin` (or `globalThis.location?.origin`) is set, return `{baseUrl: origin, baseTasksUrl: `${origin}/tasks`, baseWebsocketsUrl: `${origin.replace(/^http/, "ws")}/`}`. Module-level call passes `globalThis.location?.origin` (with safe `typeof` check).
+  - Files: `rtk/src/constants.ts`
+  - Depends on: none
+  - Acceptance: Existing tests pass; new sentinel-aware path returns expected URLs.
+
+- [ ] **Task 2.2**: Tests for same-origin sentinel
+  - Description: Add tests to `rtk/src/constants.test.ts` covering: (a) sentinel + `windowOrigin: "https://api.example.com"` → `https://...` + `wss://...`; (b) sentinel + `windowOrigin: "http://localhost:4000"` → `http://...` + `ws://...`; (c) sentinel + no window origin → falls back to existing resolution; (d) non-sentinel BASE_URL is unchanged; (e) sentinel + isDev=true behaves the same as production for the sentinel path.
+  - Files: `rtk/src/constants.test.ts`
+  - Depends on: 2.1
+  - Acceptance: `bun run rtk:test` passes including new cases.
+
+## Phase 3: Express plugin
+
+- [ ] **Task 3.1**: Implement `AdminSpaServeApp.register()`
+  - Description: Implement `src/serve.ts`: resolve `basePath` (default `/console`), `distDir` (default `path.resolve(__dirname, "../../dist")` so it works from `src/dist/serve.js`), merged `appConfig`. Register three Express handlers: `express.static` for `_expo/` and `assets/` with `{immutable: true, maxAge: "365d"}`, `GET ${basePath}/app-config.json` returning JSON with `Cache-Control: no-store`, `GET ${basePath}{/*splat}` returning `index.html` with `Cache-Control: no-store`. Log at info level on mount.
+  - Files: `admin-spa/src/serve.ts`, `admin-spa/src/index.ts` (export)
+  - Depends on: 1.3
+  - Acceptance: `bun run admin-spa:compile` produces `src/dist/serve.js`; manual import from Node ESM works.
+
+- [ ] **Task 3.2**: Plugin unit tests
+  - Description: Add `src/serve.test.ts` using `supertest`. Create a tmpdir with stub `index.html` ("STUB-SPA"), `_expo/static/js/web/foo.abc123.js` ("CONTENT"), and `assets/foo.png` (any bytes). Construct an Express app and register the plugin with `distDir` pointing at the tmpdir. Cases: `GET /console/` → 200 + STUB-SPA + `Cache-Control: no-store`; `GET /console/users` → 200 + STUB-SPA (fallback); `GET /console/users/abc123` → 200 + STUB-SPA; `GET /console/_expo/static/js/web/foo.abc123.js` → 200 + CONTENT + cache headers; `GET /console/app-config.json` → 200 + JSON with `brandName: "Terreno Admin"` (default) + `Cache-Control: no-store`; `GET /console/app-config.json` with custom appConfig → returns merged config; `GET /unrelated` → 404 (plugin doesn't catch outside `basePath`); custom `basePath: "/admin-ui"` works.
+  - Files: `admin-spa/src/serve.test.ts`
+  - Depends on: 3.1
+  - Acceptance: `bun run admin-spa:test` passes all cases.
+
+## Phase 4: SPA — gates and auth
+
+- [ ] **Task 4.1**: AppConfigGate component
+  - Description: Create `components/AppConfigGate.tsx`. Uses React context to expose `AdminSpaAppConfig`. On mount, fetches `./app-config.json` (relative to current URL — so `/console/app-config.json` when mounted at `/console`). Defines defaults to merge with response. Renders a centered `<Spinner>` with `testID="admin-spa-app-config-loading"` while loading. Errors → renders a `<Text>` with retry button. Exposes `useAppConfig()` hook.
+  - Files: `admin-spa/components/AppConfigGate.tsx`
+  - Depends on: 1.4, 3.1
+  - Acceptance: Build succeeds; importing `useAppConfig` outside the gate throws a clear error.
+
+- [ ] **Task 4.2**: StoreProvider component (replaces "factory function" pattern)
+  - Description: Create `components/StoreProvider.tsx`. Reads `useAppConfig()`. Inside the component body, memo-builds `authClient = createAuthClient({baseURL: window.location.origin, basePath: appConfig.authBasePath ?? "/api/auth"})` using `better-auth/react` **directly** (NOT `@terreno/rtk`'s factory — that one is RN-targeted with the expo plugin). Builds `{betterAuthReducer, middleware, selectors} = generateBetterAuthSlice(authClient)`, then `store = configureStore({reducer: {betterAuth: betterAuthReducer, [openapi.reducerPath]: openapi.reducer}, middleware: (gdm) => gdm().concat(openapi.middleware, ...middleware)})`, then `persistor = persistStore(store)`. Wraps children: `<Provider store={store}><PersistGate loading={<Spinner testID="admin-spa-persist-loading"/>} persistor={persistor}>{children}</PersistGate></Provider>`. The `loading` prop is **required** — without it, AdminGate flashes the login screen during rehydration.
+  - Files: `admin-spa/components/StoreProvider.tsx`, `admin-spa/store/sdk.ts` (re-exports `emptySplitApi as openapi` from `@terreno/rtk` with tag types)
+  - Depends on: 4.1, 6.1
+  - Acceptance: Build succeeds; type-check passes; no `expo-secure-store` import surfaces in the bundle (since this is web-only).
+
+- [ ] **Task 4.3**: AdminGate component
+  - Description: Create `components/AdminGate.tsx`. Wraps children. On mount, calls `authClient.getSession()`. Uses `useSelectIsAuthenticated`. Renders spinner with `testID="admin-spa-admin-gate-loading"` while loading. If unauth and not on `/login`, `router.replace("/login")`. If auth + `user.admin !== true` and not on `/forbidden`, `router.replace("/forbidden")`. If auth + admin and on `/login` or `/forbidden`, `router.replace("/")`. Otherwise pass through.
+  - Files: `admin-spa/components/AdminGate.tsx`
+  - Depends on: 4.2
+  - Acceptance: Build succeeds; gate logic verifiable via unit test of selector behavior (`bun test`).
+
+- [ ] **Task 4.4**: Login screen
+  - Description: Create `app/login.tsx`. Reads `useAppConfig().providers`. Renders form with `TextField` (email) + `TextField` (password, type="password") + `Button` ("Sign in") calling `authClient.signIn.email({email, password})`. For each provider in `providers` that isn't `"email"`, renders a `SocialLoginButton`. Handles loading, error display. On success, `router.replace("/")`. testIDs as listed in IP.
+  - Files: `admin-spa/app/login.tsx`
+  - Depends on: 4.3
+  - Acceptance: Rendering the SPA logged-out shows the login form; clicking submit attempts the better-auth signIn (verifiable by mock in unit test).
+
+- [ ] **Task 4.5**: Forbidden screen + signout
+  - Description: Create `app/forbidden.tsx`. Renders `<Page>` with heading "Admins only" and explanation text. Includes a "Sign out" button calling `authClient.signOut()` then `router.replace("/login")`.
+  - Files: `admin-spa/app/forbidden.tsx`
+  - Depends on: 4.3
+  - Acceptance: Build succeeds; testID on screen root.
+
+- [ ] **Task 4.6**: Root layout assembly (correct provider order)
+  - Description: Update `app/_layout.tsx`. Order: `<AppConfigGate><StoreProvider><TerrenoProvider><AdminGate><Stack screenOptions={{headerShown: false}}>...</Stack></AdminGate></TerrenoProvider></StoreProvider></AppConfigGate>`. AppConfigGate is outermost because it has no Redux dependency and its result is needed to build the store. StoreProvider includes Provider + PersistGate. TerrenoProvider is inside Provider so theme hooks can read store state. AdminGate is innermost so it sees fully-hydrated state.
+  - Files: `admin-spa/app/_layout.tsx`
+  - Depends on: 4.1, 4.2, 4.3, 4.4, 4.5
+  - Acceptance: `bun run admin-spa:build` succeeds with no Metro errors. Sequential render: loading splash → (rehydrating) spinner → (unauth) login OR (admin) model list. No login flash for authenticated admins.
+
+## Phase 5: Wire admin screens
+
+All screens pass `apiBase={appConfig.adminApiBasePath ?? "/admin"}` AND `routeBase=""` so navigation stays inside the SPA's `/console` root. Depends on Phase 0.
+
+- [ ] **Task 5.1**: Model list screen
+  - Description: `app/index.tsx` renders `<AdminModelList api={terrenoApi} apiBase={apiBase} routeBase={routeBase} />`. Get values from `useAppConfig()`: `const apiBase = appConfig.adminApiBasePath ?? "/admin"; const routeBase = "";`.
+  - Files: `admin-spa/app/index.tsx`
+  - Depends on: 4.6, 0.1
+  - Acceptance: After login, model list renders models from `${apiBase}/config`. Clicking a model card calls `router.push("/${modelName}")` (relative to SPA root), NOT `/admin/${modelName}`.
+
+- [ ] **Task 5.2**: Model table + form routes
+  - Description: Create `app/[model]/_layout.tsx` (`<Stack/>`), `app/[model]/index.tsx` (renders `<AdminModelTable>`), `app/[model]/[id].tsx` (renders `<AdminModelForm id={id}>`), `app/[model]/create.tsx` (renders `<AdminModelForm>`). Use `useLocalSearchParams()` for params. Handle the `__scripts` and `version-config` sentinels like example-frontend does.
+  - Files: `admin-spa/app/[model]/_layout.tsx`, `admin-spa/app/[model]/index.tsx`, `admin-spa/app/[model]/[id].tsx`, `admin-spa/app/[model]/create.tsx`
+  - Depends on: 5.1
+  - Acceptance: Navigating to `/console/Users` shows the table; clicking a row opens the form.
+
+- [ ] **Task 5.3**: Configuration + scripts + version-config screens
+  - Description: Create `app/configuration.tsx`, `app/scripts.tsx`, `app/version-config.tsx` wrapping the corresponding `@terreno/admin-frontend` screens (`ConfigurationScreen`, `AdminScriptList`, `AdminVersionConfig`).
+  - Files: `admin-spa/app/configuration.tsx`, `admin-spa/app/scripts.tsx`, `admin-spa/app/version-config.tsx`
+  - Depends on: 5.1
+  - Acceptance: Each screen renders without errors.
+
+- [ ] **Task 5.4**: Not-found + Expo Router conventions
+  - Description: Create `app/+not-found.tsx` rendering a friendly 404 with link back to `/`. Add `app/+html.tsx` if needed for static export head config (favicon, viewport).
+  - Files: `admin-spa/app/+not-found.tsx`, `admin-spa/app/+html.tsx`
+  - Depends on: 4.6
+  - Acceptance: Visiting `/console/nonexistent` shows the 404 screen.
+
+## Phase 6: SDK glue (no codegen by default)
+
+Admin endpoints are runtime-injected by `admin-frontend/src/useAdminApi.ts` — codegen is unnecessary for the admin flow itself.
+
+- [ ] **Task 6.1**: Hand-written `store/sdk.ts`
+  - Description: Create `store/sdk.ts` that re-exports `emptySplitApi as openapi` from `@terreno/rtk` and uses `.enhanceEndpoints({addTagTypes: ["admin-models", "admin-version-config", "admin-scripts", "profile"]})`. Export `const terrenoApi = openapi` for consumers.
+  - Files: `admin-spa/store/sdk.ts`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' compile` passes; importing `terrenoApi` from `store/sdk` works in app code.
+
+- [ ] **Task 6.2 (optional)**: Codegen config for consumers wanting extended SDKs
+  - Description: Create `openapi-config.ts` pointing at `http://localhost:4000/openapi.json`. Document in README as optional — not part of the standard build.
+  - Files: `admin-spa/openapi-config.ts`, `admin-spa/README.md` section
+  - Depends on: 6.1
+  - Acceptance: Running `bun run --filter '@terreno/admin-spa' sdk` against a live backend regenerates `store/openApiSdk.ts` with all endpoints.
+
+## Phase 7: Example backend integration
+
+- [ ] **Task 7.1**: Add admin-spa dep to example-backend
+  - Description: Add `"@terreno/admin-spa": "workspace:*"` to `example-backend/package.json` dependencies.
+  - Files: `example-backend/package.json`
+  - Depends on: 1.2
+  - Acceptance: `bun install` resolves.
+
+- [ ] **Task 7.2**: Register plugin in example-backend
+  - Description: In `example-backend/src/server.ts`, import `AdminSpaServeApp`. Register it (gated on `process.env.ADMIN_SPA_ENABLED === "true"`) with `basePath: "/console"`, `appConfig: {brandName: "Terreno Example", primaryColor: "#7C3AED", providers: ["email", "google"]}`.
+  - Files: `example-backend/src/server.ts`
+  - Depends on: 7.1, 3.1
+  - Acceptance: With `ADMIN_SPA_ENABLED=true AUTH_PROVIDER=better-auth bun run backend:dev`, server starts and logs "Admin SPA mounted at /console/".
+
+- [ ] **Task 7.3**: Manual smoke test
+  - Description: Start the backend with the env flags above. Open `http://localhost:4000/console/`. Confirm: (a) login screen renders with brand name "Terreno Example"; (b) sign in with an admin user → redirects to admin list; (c) clicking a model opens the table; (d) editing a row works; (e) `app-config.json` GET returns the configured shape; (f) non-admin user → forbidden screen. Document any gaps found.
+  - Files: (manual)
+  - Depends on: 7.2, 5.x complete
+  - Acceptance: All six checks pass.
+
+## Phase 8: Docs and rules
+
+- [ ] **Task 8.1**: README for admin-spa
+  - Description: Write `admin-spa/README.md`. Sections: overview, install, register with backend, customizing app-config, regenerating SDK, comparison with embedded admin-frontend usage.
+  - Files: `admin-spa/README.md`
+  - Depends on: 7.3
+  - Acceptance: Reading the README is sufficient for a new consumer to add admin to their backend.
+
+- [ ] **Task 8.2**: rulesync rule file
+  - Description: Author `.claude/rules/admin-spa/00-admin-spa.md` matching the shape of `.claude/rules/admin-frontend/00-admin-frontend.md`. Run `bun run rules` to regenerate `rulesync.jsonc` artifacts. Verify the rule appears in any AI consumer config files generated.
+  - Files: `.claude/rules/admin-spa/00-admin-spa.md`, plus regenerated rulesync artifacts
+  - Depends on: 8.1
+  - Acceptance: `bun run rules:check` passes (no diff after a clean regen).
+
+- [ ] **Task 8.3**: Update CLAUDE.local.md and admin-backend README
+  - Description: Add admin-spa to the packages list in `CLAUDE.local.md`. Add a "Standalone admin SPA" pointer to `admin-backend/README.md`.
+  - Files: `CLAUDE.local.md`, `admin-backend/README.md`
+  - Depends on: 8.1
+  - Acceptance: Both files mention admin-spa and reference the IP.
+
+- [ ] **Task 8.5**: Publish CI job
+  - Description: Add an `admin-spa` publish job to `.github/workflows/publish-on-tag.yml` mirroring the existing 8 publish jobs. Job must: `bun install` → `bun run admin-spa:build` → `bun run admin-spa:compile` → `bun publish --filter '@terreno/admin-spa'`. Without this, tagged releases publish an empty `dist/`.
+  - Files: `.github/workflows/publish-on-tag.yml`
+  - Depends on: 8.1
+  - Acceptance: Dry-run the workflow on a feature branch; verify the tarball contains `src/dist/`, `dist/index.html`, and at least one file in `dist/_expo/`.
+
+- [ ] **Task 8.6**: CI smoke test
+  - Description: New job (or extension of existing E2E workflow). Boots example-backend with `ADMIN_SPA_ENABLED=true AUTH_PROVIDER=better-auth` after running `bun run --filter '@terreno/admin-spa' build:web`. curl `/console/`, `/console/app-config.json`, and one `/console/_expo/static/js/web/*.js` asset. Assert 200s + correct cache headers. Catches path-rewrite regressions in CI.
+  - Files: `.github/workflows/admin-spa-smoke.yml` (new) or update an existing test workflow
+  - Depends on: 7.2, 3.1
+  - Acceptance: Workflow passes on a clean run; mutating the rewrite list in `serve.ts` to omit `_expo` causes a CI failure.
+
+## Optional Phases
+
+- [ ] **Task 9.1 (optional)**: Playwright E2E
+  - Description: Add `e2e/admin-spa.spec.ts` to example-frontend with three tests: anonymous user sees login screen, admin can log in and view model list, non-admin gets forbidden screen.
+  - Files: `example-frontend/e2e/admin-spa.spec.ts`, plus testIDs already added in Phase 4
+  - Depends on: 7.3
+  - Acceptance: `bun run --filter '@terreno/example-frontend' e2e -- admin-spa.spec.ts` passes locally with backend running.

package/src/docs/versioned/57.17.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/src/docs/versioned/57.17.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.