@terreno/mcp 57.8.0 → 57.10.1

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

@@ -0,0 +1,104 @@
+# Validate a block document locally
+
+`terreno-blocks` checks one whole-reply YAML or JSON document before you send it.
+
+1. Compile the package so the bin exists: `cd blocks && bun run compile`.
+2. Run `terreno-blocks validate path/to/document.yaml`.
+3. A valid document exits 0. Each problem prints as `path  CODE  message — fix` and the
+   process exits 1.
+4. Pass `-` to read the document from stdin.
+
+The same check is `validateBlocks` in `@terreno/blocks`. Field tables are in the
+[blocks reference](../reference/blocks.md).
+
+## Preview a document in the playground
+
+1. Open the component demo and choose **BlocksPlayground**.
+2. Start from Layout or Invalid, or paste your own document into the text area.
+3. The preview updates as you type. An invalid document shows the error banner and keeps
+   the raw text collapsed.
+
+## Require documents from the model
+
+Pass `uiBlocks: true` to `addGptRoutes`. The model is told that its whole reply is one document. When the turn's text finishes, the route checks it and sends `{blocks: {ok, errors, warnings}}` before `{done}`.
+
+```ts
+addGptRoutes(router, {
+  aiService,
+  uiBlocks: {
+    hostActions: {export_csv: {}},
+    repair: true,
+  },
+});
+```
+
+`hostActions` is the callback allowlist. A callback outside it fails with `UNKNOWN_HOST_ACTION`. `repair: true` runs one repair call and stores that document. A document that is still invalid is stored with a `Block validation errors:` note so the next turn sees the codes.
+
+An actions block that omits `id` gets one before storage. A block document written in the same step as a tool call is kept when no later step has text, so the first reply still shows. The chat receives that document after ids are filled, repair runs, and html is sanitized, so an invalid draft is not shown. `{replace: "text"}` is sent only when text was already streamed and then changed.
+
+Outside a chat turn, `AIService.generateBlocks({prompt})` returns one validated document. Temperature is 0. A failed check is repaired once. Pass `repair: false` to skip that retry. A second validation failure throws 422 and logs `metadata.errorCodes`. A model or network error throws 502 and is not repaired.
+
+## Store rows for a ref chart
+
+1. Turn `uiBlocks` on. `addGptRoutes` then mounts `GET /gpt/datasets/:id`.
+2. From a server tool, call `registerAiDataset({userId, historyId, columns, rows})`. The return type is `RegisteredDataset` (`datasetId`, `columns`, `rowCount`, `preview`, `stats`).
+3. Hand the model the returned `datasetId`. A `ref` dataset uses that id. The model cannot create one.
+4. The owner reads rows with `GET /gpt/datasets/:id?grain=week&limit=40`. Leave `page` off to downsample a line or area with LTTB. Pass `page` to paginate a table; `more` is true when another page remains.
+5. `datasetTtlDays: 0` (the default) stores no `expiresAt`. `7` sets `expiresAt` to seven days after `created`. More than `datasetMaxRows` (default 50,000) returns 413. Another user's id returns 404.
+
+## Register a server callback
+
+1. Pass `hostActions` on `uiBlocks`. Each name has a Zod `payload` and a `handler`.
+2. The client posts `{historyId, messageId, blockId, elementId, name, payload}` to `POST /gpt/actions`.
+3. Return `{replace: "block", blocks}` to swap the block, or `{text}` to append an assistant message. `blocks` must be a valid document (`v` then `blocks`).
+4. An unknown name is 404. A payload that fails the schema is 400 with `meta.fields`. Another user's history is 403. The handler stops at 10 seconds with 504. An invalid document from the handler is 500.
+
+```ts
+addGptRoutes(router, {
+  aiService,
+  uiBlocks: {
+    hostActions: {
+      export_csv: {
+        payload: z.object({format: z.literal("csv")}).strict(),
+        handler: async () => ({
+          replace: "block",
+          blocks: {v: 1, blocks: [{type: "badge", text: "Exporting", status: "info"}]},
+        }),
+      },
+    },
+  },
+});
+```
+
+The path is `/gpt/actions`, so a limiter on `/gpt` covers it. Each call is stored as an `AIRequest` with `requestType: "ui_action"`.
+
+## Wire the example chat
+
+1. Turn `uiBlocks` on in `addGptRoutes` so `GET /gpt/datasets/:id` and `POST /gpt/actions` are in the OpenAPI spec.
+2. Regenerate the frontend SDK: `cd example-frontend && bun run sdk`.
+3. Set `uiBlocks` and `hostActions` on `GPTChat`. `reply` already calls `onSubmit`.
+4. `onBlockCallback` calls `usePostGptActionsMutation`. Return that result so a `{replace: "block"}` swaps the block.
+5. `resolveDataset` calls `useLazyGetGptDatasetsByIdQuery` and returns `{columns, rows, source: "inline"}`.
+6. An `open` action uses `router.push` for a `/…` route and `Linking.openURL` for an `https` URL.
+7. When the `{blocks}` event is `ok`, set `blockNote` to the top-level block count, such as `3 components`. Recompute that caption from stored assistant YAML when a history is loaded again.
+
+## Turn blocks on in the example backend
+
+`example-backend` passes `uiBlocks` with `repair: true` and one host callback, `exportDataset`. Its payload is `{dataset: string}`. The handler returns `{replace: "block", blocks}` with a badge that names that dataset. Dataset TTL stays at the default, so stored rows are kept.
+
+The per-request tool `todoStats` counts the signed-in user's open and completed todos, calls `registerAiDataset`, and returns `datasetId`. It stores the rows on `req.body.historyId` when that id belongs to the caller. With no history id it uses the caller's newest history, and with no history it returns `{datasetId: null, rowCount: 0}`. A chart dataset uses `source: ref` and that id. Columns are `status` and `count`.
+
+`GPTChat` lists `exportDataset` in `hostActions`, so that callback stays enabled. The e2e mock also allows `export_csv`.
+
+## Render documents in chat
+
+Set `uiBlocks` on `GPTChat`. Assistant `content` is the YAML document. While `isStreaming`
+is true, finished top-level blocks render and a spinner marks the block still arriving.
+
+- `reply` calls `onSubmit` with the button's text.
+- `open` and `select` call `onBlockAction`.
+- `callback` calls `onBlockCallback`. Return `{replace: "block", blocks}` to swap that
+  block, or `{text}` to append an assistant message. The button shows loading until the
+  promise settles.
+- Pass `hostActions` to disable callbacks the host does not run, `resolveDataset` to
+  load `ref` datasets, and `resolveImage` to turn a `file:` image id into a URL.

package/dist/docs/versioned/next/how-to/ai-feature-development.md

@@ -0,0 +1,156 @@
+# Develop an AI feature
+
+Work this loop in **Terreno admin** when observability primaries are `local`. If prompts/datasets/experiments are Langfuse, the same screens proxy the vendor, or use **Open in Langfuse**.
+
+Architecture: [AI observability](../explanation/ai-observability.md). Routes and models: [AI reference](../reference/ai.md). Register plugins: [Observe LLM calls](./observe-llm-calls.md).
+
+Volume targets (how many gold items, class balance) live in the operator spreadsheet, not in Terreno. Use **tags** and **outcome class** so you can filter for balance.
+
+For a walkable example, run `bun run backend:seed`: it installs
+`examples/example-summarize` with production on v1 and candidate v2, the human
+`correctness-human` and automatic `schema-assert` evaluators, and the proofread
+`example-gold` dataset. It also installs `chat-safety-synthetic`, twelve proofread
+synthetic chats between two people. Each item is the new message plus a few earlier
+turns. Gold labels cover 988 (immediate danger to self), care-team follow-up,
+toxicity, a privacy leak, and a dismissive reply. Compare `chat-safety-screen` v1
+(new message only) with v2 (earlier turns) using evaluator `chat-safety-agreement`.
+These fixtures are proofread on purpose so experiments include them. The Generate
+button still lands drafts as `proofread: false` until a human accepts them. Load the
+same set into a running database, including a PR preview, with Admin → Scripts →
+`seedChatSafetyDataset` (wet run).
+
+## 1. Gather a gold dataset
+
+1. Open **Datasets** → create a named set. Optionally set `inputSchemaPromptName` to a registry prompt whose `inputSchema` should validate imported rows, and `expectedOutputSchema` if product has agreed a label shape.
+2. Add items in three ways:
+   - **From production traces** (preferred for open-ended features): Traces list → filter → **Add to dataset** (`POST /ai/observability/traces/add-to-dataset`). Sensitive traces always land `proofread: false`.
+   - **Import JSON or CSV** (`POST /ai/observability/datasets/:id/import`): JSON can be an array of bare input objects or structured rows with `input`, `expectedOutput`, `proofread`, `tags`, `outcomeClass`, and `metadata`. CSV accepts `Content-Type: text/csv` or `{format: "csv", content: "..."}`; plain columns map to `input`, `input.foo` nests fields, `expectedOutput.foo` maps labels, and reserved `proofread` / `tags` / `outcomeClass` columns map metadata. Invalid rows against the bound input schema return 400 with the row number and JSON path.
+   - **Manual**: `POST /datasets/:id/items` with a production-shaped `input`.
+   - **Synthetic** (phase 2.4): **Generate** drafts. They land as `origin: synthetic` and `proofread: false`. Do not run experiments on them until a human proofreads and sets `proofread: true`.
+3. Prefer a mix of true/false positives and negatives on classification features. Tag critical cases.
+
+In-app **thumbs** / **false positive|negative** on a live feature write feedback scores and can **flag for dataset** (step 7). Those traces show up with `flaggedForDataset`.
+
+## 2. Label expected output
+
+1. Open the dataset item.
+2. Fill `expectedOutput` to match the schema from step 1.
+3. Set `outcomeClass` (`tp` / `fp` / `tn` / `fn`) when the feature is a flag.
+4. Add `tags` for categories you will filter on later.
+5. Set `proofread: true` on synthetic items you accept.
+
+Skip unlabeled items in experiments unless you only need generation smoke (still prefer labels before scoring).
+
+## 3. Create the prompt
+
+1. Open **Admin → AI Observability → Prompts**. The folder rail shows counts; search filters name and folder. If your role lacks `aiPrompt:create`, **Create prompt** is hidden (API writes still 403).
+2. **Create prompt** (folder, name, system, user template with `{{variables}}`). That write is immutable **v1**. Open the row to the prompt hub (**Overview**, **Versions**, **Traces**, **Experiments**).
+3. On **Versions**, edit system/template/variables/temperature when `aiPrompt:update` is allowed, then **Save as vN+1**. There is no in-place save. **Playground → Run once** (when `aiPrompt:playground` is allowed) compiles and calls the model; it does **not** create a version. **Traces** and **Experiments** show recent items for this prompt from prompt detail relationships.
+4. Do not paste that string into app routes. Apps call `AIService` with `promptName` + `promptLabel` (step 6).
+
+Read-only auditors with `aiPrompt:list` and `read` can review overview metadata and relationship tabs but do not see create, save, promote, or playground controls. Operators with the full `aiPrompt` action set see those controls. UI gating follows `permissions` on `GET /ai/observability/status`; assign roles in **Admin → Roles** per [API reference — AI observability RBAC](../reference/api.md#ai-observability-rbac).
+
+Judge prompts for evaluators are named constants or registry prompts — never inline in `AIService`.
+
+## 4. Set up evaluators
+
+**Evaluators** → **Create from template** (`POST /ai/observability/evaluators/templates/:name`) or custom (`POST /ai/observability/evaluators`):
+
+| Feature shape | Template | Score |
+| --- | --- | --- |
+| Boolean flags (urgent, etc.) | `correctness` (`llm-judge`) or `correctness-human` (review queue) | boolean `correct` |
+| Open-ended text | `hallucination` / `hallucination-human` | boolean `hallucinated` / `contains_hallucination` |
+| Open-ended text | `helpfulness` / `helpfulness-human` | numeric 0–1 |
+| Open-ended text | `toxicity` / `toxicity-human` | boolean `is_toxic` / `toxic` |
+| Structured JSON output | `schema-assert` (`json-assert`) | boolean `schema_valid` |
+| Open-ended text (if useful) | `conciseness` | numeric 0–1 (human) |
+
+`llm-judge` templates require a registry judge prompt (`eval-judge-*`) whose `outputSchema` declares every required dimension. Create returns 400 naming any missing key. `confidenceAlertBelow` defaults to **0.7**.
+
+A human evaluator with `runModes.liveSampleRate > 0` is rejected (400). Live sampling for judges is task 2.2, capped by `AI_OBS_SAMPLE_RATE`.
+
+Add more dimensions with product/engineering. Attach them to the experiment in step 5.
+
+## 5. Run experiments
+
+1. **Experiments** → `POST /ai/observability/experiments` with dataset id, **2–3 prompt version numbers**, evaluator ids, optional `modelOverride`, and optional `thresholds[]`.
+2. Thresholds default to the SOP gates (override per run if product disagrees):
+
+| Dimension | Gate |
+| --- | --- |
+| correctness true-rate | = 100% |
+| hallucination true-rate | = 0% |
+| helpfulness mean | ≥ 90% |
+| toxicity true-rate | = 0% |
+
+3. Wait for the run (`BackgroundTask` when local — even for a one-item dataset).
+4. `GET /ai/observability/experiments/:id` returns gate pass/fail, aggregates (`trueRate` for booleans, `mean` for numerics), `outlierItemIds`, `lowConfidenceItemIds`, and per-item outputs (**failed rows first**).
+5. Skim **per-item outputs**. If they are nonsense, fix the prompt before trusting aggregates.
+6. Read **pass/fail vs thresholds**. Open outliers and low-confidence items (default alert below 0.7). Use those items to rewrite the prompt.
+7. Save a new prompt version. Repeat this step until gates pass (or product accepts a documented override).
+8. `POST /ai/observability/experiments/:id/promote` with `{version}` moves `production` when all gates pass; **409** while any gate fails. Experiments never auto-promote without this call.
+
+Unproofread synthetic items are excluded unless you set `includeUnproofread`.
+
+## 6. Deploy to production
+
+1. In the prompt editor, select the winning version and **Set vN as production…**. The confirm modal names the **outgoing** production version (or none). Experiments never auto-promote.
+2. In the app, resolve that label at call time:
+
+```typescript
+await aiService.generateText({
+  prompt: text,
+  promptLabel: "production",
+  promptName: "example-summarize",
+  userId: req.user?.id,
+});
+```
+
+Missing `production` fails the request (400). Do not fall back to a hardcoded string.
+
+## 7. Production tracing and feedback
+
+Do this in parallel with steps 1–6 once the feature is reachable.
+
+1. Register `ObservabilityApp`. Every `generate*` emits a trace unless `skipTrace`.
+2. Pass `userId` and `sessionId` from the request.
+3. From the product UI, call `POST /ai/observability/traces/:id/feedback` as the signed-in user:
+   - `kind: "thumbs"` + `up` / `down` (helpfulness of suggestions)
+   - `kind: "outcome"` + `tp` / `fp` / `tn` / `fn` (flags)
+   - `flagDataset: true` to queue the trace as a dataset candidate
+4. In **Admin → AI Observability → Traces**, filter by time, prompt dropdown, status, user, session, score presence, or data sensitivity. Score and sensitivity dropdowns include both positive and negative states. Rows show a status dot, `sensitive` badge, error line, `N prompts`, tokens, cost, and latency. Open a row for the span tree (kind, indent, duration bar). Sensitive I/O disclosures start **collapsed**.
+5. Select one or more traces. The bulk bar warns when any selected row is `sensitive`. Choose **Send to human review**, read the queue explanation, and pick a human evaluator. The evaluator's dimensions become the score fields and its instructions guide the reviewer. Confirming posts `POST /ai/observability/traces/review` with `reason: "manual"`. Automatic (`llm-judge` / `json-assert`) evaluators cannot enter this queue.
+6. Open **Review queue**. Tabs show Pending / In progress / Done / Skipped counts, and pending
+   items are oldest-first. Select **Start reviewing — oldest first**.
+7. On each item, compare **What the AI was given** with **What the AI wrote**. Long fields begin
+   collapsed with a word count; structured outputs retain field labels and reviewer notes. Use
+   **Raw JSON** only when the field view is insufficient.
+8. Score every required evaluator dimension: numeric dimensions use the declared range slider,
+   boolean dimensions use Pass / Fail, and categorical dimensions use pills. Add an optional
+   comment, then **Submit & next**. **Skip** records no score. For the second phase-1 intake path,
+   use **Assign to me** to manually claim an item and move it to In progress. Continue until the
+   toast says **Queue clear**.
+
+Feedback is a score (`source: "user-feedback"`) fanned out to every ScoreSink. Non-owners who are not admin get 403.
+
+## 8. Add weak production traces back to the dataset
+
+1. **Traces**: filter `thumbs=down`, `flaggedForDataset`, `failedEval`, or `lowConfidence` (filters land with task 2.6 feedback).
+2. **Add to dataset** (`POST /ai/observability/traces/add-to-dataset`, bulk allowed).
+3. Label the new items (step 2).
+4. Repeat steps 5–8.
+
+Phase 1 also supports **Send to review queue** from the Traces bulk bar (step 7) when human scoring is enough before dataset intake.
+
+## Checklist (one feature)
+
+- [ ] Gold set exists with mixed origins and labels
+- [ ] Prompt versions in the registry, not inlined in routes
+- [ ] SOP (or custom) evaluators attached
+- [ ] Experiment gates green or explicitly overridden
+- [ ] `production` label on the winning version
+- [ ] App calls `promptName` + `promptLabel`
+- [ ] Live traces include user/session
+- [ ] Product can send thumbs / outcome / flag-for-dataset
+- [ ] Human review queue reaches Queue clear
+- [ ] Weak traces can be added back to the dataset

package/dist/docs/versioned/next/how-to/build-a-durable-workflow.md

@@ -0,0 +1,232 @@
+# Build a durable workflow
+
+Build a multi-step task that survives restarts, asks a person to sign off, and performs its
+side effect exactly once. The one worked example is the example backend's clinical tracer,
+`clinic.intakeSummary`: fetch a chart, summarize it with an agent, wait for a clinician,
+file a note. API: [AI harness reference](../reference/ai-harness.md). Why it is shaped this
+way: [Durable agent harness](../explanation/durable-agent-harness.md).
+
+| File | What it holds |
+| --- | --- |
+| `example-backend/src/harness/clinicalIntake.ts` | The task, the summarizer agent, the approvers |
+| `example-backend/src/harness/fakeEhr.ts` | The EHR client (`getChart`, `writeNote`) over `FakePatientChart` / `FakeClinicalNote` |
+| `example-backend/src/harness/clinicModels.ts` | Model resolver: Gemini when configured, else the demo model |
+| `example-backend/src/harness/clinicDemoModel.ts` | Deterministic local `LanguageModel` for dev and e2e |
+| `example-backend/src/harness/exampleHarness.ts` | `Harness.open` + runner, started in the API process |
+| `example-backend/src/harness/startClinicalIntake.ts` | Admin script that starts a run |
+
+## Try it (5 minutes)
+
+1. Start a replica-set `mongod`, the backend (`bun run backend:dev`), and the frontend
+   (`bun run frontend:web`). Steps: [Run tests locally](run-tests-locally.md).
+2. Seed: `bun run backend:seed`. It creates charts `p-1001`, `p-1002`, `p-1003`, the admin
+   `admin@example.com`, and the clinician `clinician@example.com` (password
+   `testpassword123`).
+3. Start a run: `cd example-backend && bun run script startClinicalIntake --wet --patientId p-1001`,
+   or run `startClinicalIntake` from the admin **Scripts** screen.
+4. Sign in as the admin and open **AI Harness → Approvals**
+   (`http://localhost:8082/admin/harness-approvals`). Open the item and approve it.
+5. Open **AI Observability → Traces**: the newest `clinic.intakeSummary@1` trace shows every
+   phase, the summarizer with its model call, and the sign-off.
+
+## 1. Define the task
+
+Split the work at every point where a crash would need a different answer. Each phase is a
+checkpoint; `replay` says what to do when a phase is cut off.
+
+| Phase | `replay` | Work | Why that policy |
+| --- | --- | --- | --- |
+| `fetch` | `safe` | `ehr.getChart(patientId)`; no chart fails the task | A read; running it twice is harmless |
+| `summarize` | `safe` | `rt.runAgent(summarizer, {input: chart, output: IntakeSummarySchema})` | A replay finds the same subagent turn; finished model calls are not repeated |
+| `review` | `safe` | `rt.approval("clinician-signoff", {...})`; branch on the decision | A replay finds the same approval row |
+| `write` | default (`never`) | `ehr.writeNote(..., {idempotencyKey: \`note-${task.id}\`})` | A write cut off mid-call needs a person to check the EHR |
+
+```typescript
+const intakeSummary = defineTask<IntakeSummaryInput, IntakeSummaryState, IntakeSummaryResult>({
+  name: "clinic.intakeSummary",
+  version: 1,
+  approvals: {"clinician-signoff": {approvers: [isAdminOrClinician]}},
+  initial: () => ({phase: "fetch", state: {}}),
+  retry: {maxAttempts: 3},
+  phases: {
+    fetch: {
+      replay: "safe",
+      run: async (task, rt) => {
+        const chart = await ehr.getChart(task.input.patientId);
+        if (!chart) {
+          await rt.commit({terminal: {status: "failed", error: `No chart for patient ${task.input.patientId}`}});
+          return;
+        }
+        await rt.commit({phase: "summarize", state: {chart}});
+      },
+    },
+    // summarize, review, write: see the sections below
+  },
+});
+```
+
+Keep `state` plain JSON: it is stored on every checkpoint. Bump `version` when phases or
+state change: [Ship a new task version](ship-a-new-task-version.md).
+
+## 2. Add the agent
+
+```typescript
+const summarizer = defineAgent({
+  name: "clinic.summarizer",
+  model, // {provider: "google", modelId: "gemini-2.5-flash"} or the demo model
+  fallbackModels,
+  instructions: CLINIC_SUMMARIZER_INSTRUCTIONS, // a named constant, never inline
+  tools: [],
+});
+
+summarize: {
+  replay: "safe",
+  run: async (task, rt) => {
+    const summary = await rt.runAgent<NoteContent>(summarizer, {
+      input: task.state.chart,
+      output: IntakeSummarySchema, // {summary, risk, sources}
+    });
+    await rt.commit({phase: "review", state: {...task.state, summary}});
+  },
+},
+```
+
+`Harness.open({models})` turns the agent's `{provider, modelId}` into a model. The example
+resolver (`resolveExampleModel`) maps:
+
+| Ref | Model |
+| --- | --- |
+| `google/*` | The server's Gemini / Vertex model (`GEMINI_API_KEY` or `GOOGLE_VERTEX_PROJECT`) |
+| `demo/clinic-summarizer-demo` | The demo model: derives the summary from the chart by fixed rules, prefixes it `[Demo model: no LLM was called]`, calls no network |
+
+The summarizer uses the demo model when no provider is configured or `CLINIC_DEMO_MODEL=true`,
+so dev and e2e runs need no API key. Its `LLM` spans are named `demo/clinic-summarizer-demo`.
+
+## 3. Ask for approval
+
+Declare approvers on the definition, keyed by the approval key. Approvers in one list are
+ANDed, so "admin **or** clinician" is one approver:
+
+```typescript
+const isAdminOrClinician = anyApprover(
+  Permissions.IsAdmin,
+  access.permission({clinicalIntake: ["signoff"]}) // RBAC: the `clinician` role grants it
+);
+
+review: {
+  replay: "safe",
+  run: async (task, rt) => {
+    const decision = await rt.approval("clinician-signoff", {
+      title: `Sign off intake summary for ${chart.name}`,
+      summary: signoffSummary(chart, summary), // markdown shown in the inbox
+      payload: {patientId: chart.patientId, ...summary},
+      timeout: {hours: 24},
+    });
+    if (!decision.approved) {
+      const reason = decision.expired
+        ? "Sign-off expired before anyone decided"
+        : (decision.reason ?? "Rejected");
+      await rt.commit({terminal: {status: "completed", result: {status: "rejected", reason}}});
+      return;
+    }
+    await rt.commit({phase: "write", state: {...task.state, signedOffBy: decision.decidedBy}});
+  },
+},
+```
+
+The example adds the `clinicalIntake.signoff` statement and a `clinician` role
+(`example-backend/src/access.ts`, `rbacRoles.ts`). Admins decide in the admin inbox.
+Clinicians without admin access decide over HTTP (`GET /harness/approvals`,
+`POST /harness/approvals/:id/approve`) or in a `HarnessApprovalInbox` mounted outside the
+admin shell ([admin-frontend](../reference/admin-frontend.md#ai-harness-approvals-inbox)).
+
+## 4. Perform the side effect once
+
+Leave the side-effecting phase at the default `replay: "never"` and pass an idempotency key
+the EHR enforces:
+
+```typescript
+write: {
+  run: async (task, rt) => {
+    rt.signal.throwIfAborted();
+    const note = await ehr.writeNote(task.input.patientId, task.state.summary, {
+      idempotencyKey: `note-${task.id}`,
+      signedOffBy: task.state.signedOffBy,
+      taskId: task.id,
+    });
+    await rt.commit({terminal: {status: "completed", result: {status: "filed", noteId: String(note._id)}}});
+  },
+},
+```
+
+`FakeClinicalNote.idempotencyKey` is unique, so even a retried write returns the first note.
+
+## 5. Register and run
+
+```typescript
+const harness = await Harness.open({
+  models: resolveExampleModel,
+  registry: [intakeSummary, summarizer],
+  runner: new InProcessRunner(exampleRunnerOptions()),
+});
+terraApp.register(new HarnessApp({harness})); // before AdminApp: adds the approvals inbox
+await harness.start();                         // after listen: the runner claims work
+
+await harness.createTask(intakeSummary, {patientId}, {requestId: `intake-${patientId}`});
+```
+
+`requestId` makes starting idempotent: the script returns the first run for a repeated key
+(pass `--requestId` to start another). Every process that runs or decides tasks registers
+the same definitions.
+
+## 6. Observe
+
+| Where | What you see |
+| --- | --- |
+| **AI Harness → Approvals** | The pending sign-off: title, markdown summary, payload |
+| **AI Observability → Traces** (`/admin/ai-trace-detail?id=<traceId>`) | The span waterfall |
+| `GET /ai/observability/traces/:traceId` | The same tree as JSON (admin) |
+| `GET /harness/tasks/:id/events` | Live `task.status` and `approval.*` events (SSE) |
+
+`HarnessTask.traceId` links a run to its trace. A completed run's tree:
+
+```
+CHAIN clinic.intakeSummary@1
+├── CHAIN fetch
+├── CHAIN summarize                          (waiting on the summarizer)
+├── AGENT clinic.summarizer
+│   ├── CHAIN request
+│   └── LLM   demo/clinic-summarizer-demo
+├── CHAIN summarize                          (summary committed)
+├── CHAIN review                             (waiting on sign-off)
+├── CHAIN wait:terreno.approval:clinician-signoff:<step>:0
+├── CHAIN approval:clinician-signoff         (decision, decidedBy)
+├── CHAIN review
+└── CHAIN write
+```
+
+## 7. Recover an interrupted run
+
+| Cut off during | What happens | You do |
+| --- | --- | --- |
+| `fetch`, `summarize`, `review` | After the lease expires (`HARNESS_LEASE_SECONDS`, default 30), the next runner replays the phase. A cut-off model request is re-requested; an error `request` span records the interruption. | Nothing |
+| `write` | The task goes `interrupted`. | Check the EHR for `note-<taskId>`, then `POST /harness/tasks/:id/resolveInterrupted` with `{action: "retry" \| "complete" \| "abort", reason}` |
+
+The proof is `example-backend/src/harness/clinicalIntake.crash.test.ts`. It starts the real
+API process (`bun run src/index.ts`) against a replica set with
+`CLINIC_DEMO_MODEL_DELAY_MS=600000`, starts a run, waits until the summarizer's model
+request is in flight, sends `SIGKILL`, starts a fresh process, approves, and asserts:
+the run ends `filed`, exactly one `FakeClinicalNote` exists, and the trace has one `LLM`
+span plus an interruption span naming the dead process's lease. Run it with
+`cd example-backend && bun test src/harness/clinicalIntake.crash.test.ts` (about 50 s).
+The Playwright spec `example-frontend/e2e/harness-intake.spec.ts` covers approve-in-inbox →
+`filed` → span tree in the Traces screen.
+
+## Configuration
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `GEMINI_API_KEY` / `GOOGLE_VERTEX_PROJECT` | unset | When set, the summarizer uses `google/gemini-2.5-flash` (fallback `gemini-2.5-flash-lite`) |
+| `CLINIC_DEMO_MODEL` | unset | `true` forces the demo model even with a provider |
+| `CLINIC_DEMO_MODEL_DELAY_MS` | `0` | Demo model waits this long per request (crash drills) |
+| `HARNESS_LEASE_SECONDS` | `30` | Owner and task lease; heartbeat is a third of it. Short values speed up crash recovery in tests |

package/dist/docs/versioned/next/how-to/charts-and-dashboards.md

@@ -35,3 +35,10 @@ export const OpsDashboard: FC = () => {
 Charts have no width prop: each one fills the container you put it in and redraws when that width changes, so size the `Card` or `Box` around it. `height` is the chart's whole height, tick row and tooltip row included, so `height={140}` fits a 140px slot; the tooltip row is always reserved so hovering never reflows the page. Long x labels truncate inside their band rather than widening the chart.
 
 Prove paint with `bun run ui:charts:compare` against `demo/rendered-snapshots/`, not with JSON snapshots. See [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md).
+
+A chat reply can draw the same charts. `BlocksView` turns a `chart` block into one series of `{label, value}` points from an inline dataset or from `points`. It does not pass a per-point `color`. A `ref` dataset is loaded with `resolveDataset` and the chart stays in `loading` until those rows arrive.
+
+The example app admin home (`example-frontend/components/AdminCharts.tsx`, mounted
+below the admin dashboard at `/admin`) shows the same pieces together: scorecards with comparison
+sparklines, a multi-series line, a donut with a center label, a bar chart, and an
+area chart inside a spanning `DashboardGrid`.

package/dist/docs/versioned/next/how-to/circleci.md

@@ -80,7 +80,8 @@ for `.circleci/**`); the kitchen-sink does not start a second copy. If the same
 pipeline already set `run-api`, `run-ui`, `run-e2e`, `run-example-backend`, or
 `run-admin-spa`, that kitchen-sink workflow is skipped so jobs are not doubled.
 `comms/**` also sets `run-example-backend` and `run-example-backend-script`,
-matching the GitHub Actions twins.
+matching the GitHub Actions twins. `blocks/**` sets `run-blocks` plus every
+parameter `ai/**` sets, because `@terreno/ai` depends on `@terreno/blocks`.
 
 The example-backend Docker job runs only when its image recipe changes
 (`Dockerfile`, `.dockerignore`, package manifests, or `bun.lock`). API/source
@@ -165,7 +166,7 @@ non-PR branch builds.
 | Path (examples) | Parameter | PR job | `master` job |
 | --- | --- | --- | --- |
 | `demo/**`, `ui/**` | `run-deploy-demo` | `deploy-demo-preview` | `deploy-demo` |
-| `example-frontend/**`, `admin-frontend/**`, `rtk/**`, `ui/**`, `ai/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
+| `example-frontend/**`, `admin-frontend/**`, `rtk/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
 | `docs/**`, `website/**` | `run-deploy-docs` | `deploy-docs-preview` | `deploy-docs` |
 | `example-backend/**`, `api/**`, `comms/**`, `jobs/**`, `admin-spa/**`, `feature-flags/**`, `announcements/**`, plus every frontend path above | `run-cd-backend` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `terraform/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
@@ -242,9 +243,10 @@ restrict `terreno-release` and `terreno-npm` to tag/manual release pipelines.
 Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets only**
 (or the in-job `ci-e2e-*-secret` fallbacks). **Do not** put `GITHUB_TOKEN` (or any
 GitHub PAT) in project env vars — those are injected into every job, including
-`bun` scripts from the PR. Create `terreno-github-api`, restrict it to this
-project, leave fork-PR secret passing off, and attach that context **only** to
-`dco` and `architectural-pr-review`. DCO skips if `GITHUB_TOKEN` is unset.
+`bun` scripts from the PR. `terreno-github-api` must hold the PAT as
+`GITHUB_TOKEN`; restrict it to this project and leave fork-PR secret passing off.
+The `always` workflow attaches it **only** to `dco` and `architectural-pr-review`
+(the latter also gets `terreno-agentic`). DCO skips if `GITHUB_TOKEN` is unset.
 `architectural-pr-review` also skips if `GITHUB_TOKEN` or `CURSOR_API_KEY` is
 unset, and it skips fork PRs. The job checks out `origin/master` before running
 the review script so a PR cannot rewrite the reviewer.
@@ -268,7 +270,7 @@ ambient OIDC token for GCP impersonation.
 Branch protection must require the CircleCI job names below. Remove disabled
 GitHub check names or pull requests will wait for checks that can no longer run.
 
-Dedicated package jobs (`api-ci`, `ai-ci`, `rtk-ci`, `ui-ci`, `syncdb-ci`,
+Dedicated package jobs (`api-ci`, `ai-ci`, `blocks-ci`, `rtk-ci`, `ui-ci`, `syncdb-ci`,
 `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run `bun run test:coverage`
 (`scripts/check-coverage.ts`, 95% functions and lines). Isolated `syncdb` tests
 are included by that script. Published packages without a dedicated workflow
@@ -287,6 +289,7 @@ the same commands through the parameterized `packages-ci` job, gated by
 | Admin backend lint, compile, coverage | `packages-ci` (`admin-backend`) |
 | Admin frontend lint, compile, coverage | `packages-ci` (`admin-frontend`) |
 | Run all tests (AI CI) | `ai-ci` |
+| Lint, compile, and test blocks | `blocks-ci` |
 | RTK Lint and Build | `rtk-ci` |
 | Syncdb Lint, Build, and Tests | `syncdb-ci` |
 | UI Lint, Build, Types, and Tests + demo typecheck | `ui-ci` |

package/dist/docs/versioned/next/how-to/compare-chart-rendered-snapshots.md

@@ -33,4 +33,12 @@ easy-through-hard charts in the demo app and diffs those PNGs against goldens.
 Agents reviewing a fail should follow the `review-chart-visuals` skill and look at the
 PNGs, not only the code diff.
 
+Hard fixture `scorecard-sparkline-comparison` renders five KPI tiles with solid current
+and dotted previous-period sparklines.
+Cartesian parity fixtures are `bar-time-rotated-ticks`, `bar-day-of-week`, and
+`line-three-series`.
+Donut parity fixtures are `donut-center-and-share` and `donut-single-slice`.
+Hard fixture `hows-it-going-dashboard` composes KPI scorecards, time-series charts, donuts,
+and table placeholders in a spanning `DashboardGrid`.
+
 `CHART_VISUAL_BASE_URL` overrides the demo origin when the gallery is already hosted.

package/dist/docs/versioned/next/how-to/install-agent-skills.md

@@ -70,7 +70,7 @@ scan stages come from
 | Docs | `update-docs`, `update-agent-docs`, architecture skills |
 | GitHub | issues, review, UI verification, release, dependency updates |
 | Code scans | `terreno-scan-1-aim` … `terreno-scan-5-track`, `terreno-scan-campaign`, `terreno-scan-loop` |
-| Expo and native | `track-upstream-expo`, `upgrading-expo`, deployment / EAS skills |
+| Expo and native | `track-upstream-expo`, `upgrading-expo`, `store-assets`, deployment / EAS skills |
 | Plugin agents | `pre-commit`, `ui-verifier` |
 
 `skills.sh.json` at the repo root groups those names on [skills.sh](https://skills.sh).