tinybeeai 0.0.0-stage → 0.16.1

package/docs/CHAT-UI.md

@@ -0,0 +1,416 @@
+# Chat answers you can act on
+
+A chat answer can carry small working views next to its text. When you ask "what is waiting for me?", the dot replies with a sentence and the drafts themselves, each with Approve, Edit, and Reject. It works like a waiter who brings the menu to your table so you can point at what you want.
+
+This page describes the answer blocks (KAT-136) and the object cards that came with them: the component registry, the format of a block, how the server and the client check it, what happens with data that does not fit, how actions stay inside the gate, and how blocks stream. The client and the server are built. The server builds every block from a tool result: the lookup tools (see Blocks from lookup tools), `list_cases`, `design_tests`, the stats tools (see Stats and charts), the object cards, and the triage view. The model never writes a block or a row. When one block does not answer the question, the model composes a view from these blocks (see Composed views).
+
+## Sources
+
+Two OpenAI designs shaped this. The Intelligent UI in ChatGPT answers fast and puts the tools for the task in the answer, so a question about data comes back as something you can click. The Apps SDK ([ChatGPT UI](https://developers.openai.com/apps-sdk/build/chatgpt-ui)) renders a tool's structured result with a component inline and ships a small UI kit of cards, buttons, and inputs.
+
+localdost takes the structured-result idea and the small kit. It leaves out the iframe and the host bridge: every component lives in this repo, and the model never sends HTML or code. The server picks the block kind from the tool the model called and fills in the data from the tool result; the client owns how it looks and what each button does. A composed view goes one step further in the direction of the Intelligent UI: the model arranges our components, the logic runs in a sandbox, and the app draws the result with native components.
+
+## Component registry
+
+The registry is `BLOCK_REGISTRY` in `client/src/features/chat/blocks/registry.tsx`. One kind maps to one component.
+
+| Kind | Shows | Actions | Action path |
+|---|---|---|---|
+| `runs` | Test runs: status, outcome, tests passed and failed, duration, time. Filter chips (All, Failed, Running, Passed) when there are more than 3. | Open, Rerun | Open: `#/runs/<id>`. Rerun: `POST /api/runs/:id/rerun` |
+| `pulls` | Open PRs: number, title, state, checks, author, branch, the last QA report line | Open, Review now, View report, Show card (the PR's full card under the row) | Review now: `POST /api/dots/:id/review {pr, repo}` with the repo of the block, so PR 12 of a second app repo is not read as PR 12 of the first; ask when the block has no dot |
+| `approvals` | Pending drafts through the Inbox's `ApprovalCard`. In chat each card starts collapsed (title, target, reason, actions); Show draft reveals the exact text | Approve, Edit, Reject | `POST /api/approvals/:id` |
+| `defects` | Defects: key, title, severity, status, the run that found it | Open | Link to the tracker |
+| `probes` | Probe status: up, degraded, down, HTTP status, latency, last check, error | Retry | Ask: "Check the <name> probe again" |
+| `memory` | What the dot remembers: text, kind, who added it | Edit, Delete, Undo | `POST /api/memory` and `DELETE /api/memory/:id` |
+| `ticket_review` | A ticket review: the ticket's card, then risk, risks, test ideas, open questions. When the tracker cannot be read, the key, the title, and an Open link stand in for the card | Post comment (the card has its own buttons) | Approve the drafted comment (`approvalId`), else ask |
+| `release_call` | The release call of a Lead QA dot (KAT-405): the answer word (Ready, Ready with risk, Not ready, No tickets) with the milestone, the blocking reasons under Why, the risks under Also, and the counts and the rule under Details. Built from stored rows by the `release_call` tool, with no model call | Open (on each reason; See them on a group of tickets and Review on a bug report that waits in an Inbox) | Link to the ticket, bug, PR, run or Inbox the reason names |
+| `test_cases` | Test cases with a checkbox each, priority, and result. The `list_cases` chat tool fills it from the test case store (KAT-163): one row per case by key, with its latest result | Tick, Run | Ask: "Run these test cases from run <id>: ..." |
+| `triage` | Bugs the QA review found and failed or flaky tests from recent runs, grouped by cause, with a "3 of 7 triaged" progress line | Tests: Rerun, Mark flaky, Draft defect. Review bugs: Draft defect, the Inbox link, or Open defect | Rerun: `POST /api/runs/:id/rerun`. Mark flaky: `POST /api/memory {kind: flaky_spec}`. Draft defect: `POST /api/runs/:id/defect` with `{file, title}` or `{bugKey}`, which waits in the Inbox |
+| `cards` | A GitHub PR, a GitHub issue, a Jira ticket, or a Linear ticket as a card in that product's own look (see Object cards). The block has no frame or heading, because each card is framed and named | Open, Review now or Review ticket, Comment, View diff or Change status | Review: `POST /api/dots/:id/review`. Comment: `POST /api/cards/comment`. Change status: `POST /api/cards/status`. All through the gate |
+| `table` | Any rows as a compact table, also the fallback for unknown data | Show all | None |
+| `stats` | Big-number tiles: a label, the number, and a sub-line under it. Optional tone (ok, attention, bad) colors the number. | None | Runs it points at open as RefChips |
+| `chart` | A bar, stacked bar, or line chart with series, x labels, and a one-line finding with the key number in bold | None | Runs it points at open as RefChips |
+| `view` | A composed view (KAT-366): layout nodes around the other 14 kinds, with datasets the app computes in a Web Worker. See Composed views | The actions of the blocks inside it, and none of its own | Each block calls its own route |
+
+Every block sits in one hairline frame with a heading and a count. Its records are rows with dividers inside that frame. Approvals are the exception: each draft is already a framed card, so that block drops its own frame. Blocks answer to their own width through a container query, so a row puts its actions to the right in a wide reply and under the text on a phone.
+
+## Stats and charts
+
+`stats` and `chart` (KAT-237, tier 1) show numbers from run data. They are drawn by our own components in `client/src/features/chat/blocks/charts.tsx` with SVG, so there is no chart library and no HTML from the model. The chat never renders model-written HTML: a model-written view in a sandbox is not built and will not be. A question that needs more than one block gets a composed view instead (see Composed views).
+
+Both follow these rules:
+
+- Colors are theme tokens only. Series use `--chart-1` to `--chart-4` (in `tokens.css`, each one an alias of a status color, so dark mode follows). A second and later line also differs by dash pattern, so color is never the only cue.
+- Numbers are monospace with tabular digits. Nothing animates.
+- The plot is measured in real pixels, so its text keeps its size at phone width (320px and up). A bar chart whose names do not fit under the bars lies down: names run down the left and the value sits at the end of each bar. A line that is too tight for its names shows every second or third one.
+- Bars start at zero. A percentage line ends at 100 and starts at the next ten below its lowest point.
+- A screen reader gets the finding as the name and the numbers as a hidden table, with "No data" for a gap.
+- A run the block points at shows as a `RefChip` (`client/src/ui/RefChip.tsx`) with its title from `runTitle()` in `src/refs.ts` and a link to `#/runs/<id>`. The block carries `runs: [{ runId, title }]` and an optional `runsLabel`.
+
+`stats` fields: `tiles` (up to 8) with `label`, `value` (a string shown as written, or a number), optional `sub`, optional `tone`.
+
+`chart` fields: `chartType` (`bar`, `stacked_bar`, `line`), `labels` (up to 31), `series` (up to 4, each `name` and `values` lined up with `labels`, `null` for a gap), optional `unit` (`%`), and `finding`, one line with the key number between `**` marks. The client turns only those marks into bold.
+
+```json
+{
+  "id": "b-pass-rate-chart",
+  "kind": "chart",
+  "title": "Pass rate by day",
+  "tool": "pass_rate",
+  "chartType": "line",
+  "labels": ["Fri", "Sat", "Sun", "Mon", "Tue", "Wed", "Thu"],
+  "series": [{ "name": "Pass rate", "values": [96.5, null, null, 92, 88.7, 95.1, 94.2] }],
+  "unit": "%",
+  "finding": "**94.2%** of tests passed in the last 7 days, up **1.6 points** from the week before.",
+  "runs": [{ "runId": "run-a", "title": "Merge check: Coupon total is wrong after the cart refresh" }],
+  "runsLabel": "Latest runs with failures"
+}
+```
+
+### Chat tools that return them
+
+Both tools only read. The server builds the blocks from stored runs (`src/chat-stats.ts`), checks them with `parseChatBlock`, streams them as `block` events right after the tool result, sets `tool` so the tool line leaves that call out, and stores them on the assistant message. The model gets the key numbers and writes one or two sentences; it does not repeat the numbers. A voice call or a Slack thread shows no blocks, so the prompt tells the model to say the key numbers there.
+
+| Tool | Question | Blocks |
+|---|---|---|
+| `pass_rate` | "Pass rate this week", "how are the tests doing" | `stats` with Pass rate, Test runs, Failed, Flaky, then a `chart` (line) of the pass rate by day |
+| `flaky_by_spec` | "Flaky tests by spec", "which specs are flaky" (`sinceDays`, default 7, at most 90) | A `chart` (bar) of the top 8 spec files by how often a test passed only on a retry, with the latest runs |
+
+How the numbers are counted:
+
+- The week is today and the 6 days before it, in the server's time zone. The comparison is the 7 days before that.
+- A test counts as passed when its final result is pass. A test that passed on a retry is a pass for the rate and is counted again as flaky. Skipped tests are not counted.
+- A run counts only when its tests ran to the end. A run whose setup failed, that was interrupted, or that is still running says nothing about the tests, so it is left out.
+- When no run qualifies, the tool sends no block and the answer says so in text.
+
+The rule-based chat (mock model, and the fallback when a CLI model gives no answer) routes these two questions to the tools too.
+
+## Answer format
+
+The types are in `src/types.ts` (`ChatBlock` and its row types). Every field past `id` and `kind` is optional, so a partial stream or an older client still renders something.
+
+```json
+{
+  "id": "b-runs",
+  "kind": "runs",
+  "title": "Runs today",
+  "dotId": "0muz17sj3000a15f8a",
+  "tool": "list_runs",
+  "state": "ready",
+  "more": 4,
+  "runs": [
+    { "id": "run-a", "kind": "post_merge", "status": "done", "outcome": "product_failure", "title": "Coupon total is wrong after the cart refresh", "passed": 41, "failed": 2, "durationMs": 184000, "startedAt": "2026-10-08T14:02:00Z" }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | Stable within a turn. A second block with the same id replaces the first. |
+| `kind` | One of the registry kinds. |
+| `title` | Heading. Each component has a default. |
+| `dotId` | Dot the rows belong to. Actions that need a dot use it, then the chat's own dot. |
+| `tool` | Tool call that produced the rows. The transcript hides that tool's card, so a lookup shows once. |
+| `state` | `loading` while the server fills rows, `ready` (the default) when final. |
+| `more` | Rows left out. The block says "4 more runs in the Feed". |
+
+The answer is text first, then blocks. Text carries the judgement ("the Cart API is down"); the block carries the records. A block appears only for data that answers the question. Lookups the dot made for context (reading a ticket before it answers) stay on the collapsed tool line and get no block (see Blocks from lookup tools).
+
+## Validation
+
+`parseChatBlock` in `src/chat-blocks.ts` checks every block. The server runs it before it streams a block, and the client runs it again before it renders. It has no dependencies, so both sides import the same file (`@chat-blocks` in the client).
+
+- A block must be an object with an id. The client passes a local id for a block that arrived without one.
+- Rows are checked one by one. Invalid rows are dropped and counted; valid rows stay.
+- Enums (status, severity, state) keep only known values. The validator drops an unknown value and never guesses a replacement.
+- Strings are trimmed and capped at 500 characters (memory text at 4,000).
+- Links must be `http` or `https`. `javascript:`, `data:`, and protocol-relative links are dropped.
+- A block keeps at most 50 rows. The rest add to `more`.
+- Approval rows must carry an id, a status, and an action with a kind and a body, because the card reads the full record.
+
+## Fallback
+
+| Input | Result |
+|---|---|
+| Known kind, some rows invalid | The block with the valid rows |
+| Known kind, every row invalid | A table of the raw rows |
+| Unknown kind with a list of objects | A table: up to 6 columns from the row keys, up to 50 rows |
+| Unknown kind with only fields | A two-column Field and Value table |
+| Not an object, no id and no fallback id, or nothing to show | No block. The answer stays text. |
+| A component throws while it renders | A table of the same rows, in place; the rest of the answer is untouched |
+
+A fallback table says "Shown as a table because this answer has no matching view yet." The wrapper owns the horizontal scroll, so a wide table never scrolls the page sideways, and edge shadows show when columns sit off screen.
+
+## Actions and the gate
+
+A button runs one of two paths. Neither path posts outside localdost on its own.
+
+- **Endpoint.** The button calls a route the app already has: rerun, review on demand, decide an approval, add or delete a note. Reruns and reviews queue a job. Anything that job wants to post (a PR comment, a ticket comment, a check run) goes through `gate()` and waits in the Inbox when the rule says ask.
+- **Ask.** The button sends a follow-up chat message, for example "Check the Cart API probe again". The dot answers with its tools, and any outward action it takes goes through the same gate and approvals as a run.
+
+Post comment on a ticket review approves the drafted comment when the block carries `approvalId`, because that approval is the gate step: a person approves the exact text. Without a draft it asks the dot to write one, and the draft waits in the Inbox unless the rule for ticket comments is act.
+
+Each action shows its result under the row that started it: "Rerun queued. Open the new run", "A review of this head is already queued or running", or the server's error with its status code. A second press while the first is in flight does nothing. An ask while an answer is still streaming does not send; it says "Wait for the current answer to finish, then try again."
+
+## Streaming
+
+`POST /api/chat` streams a block as one SSE event:
+
+```
+data: {"type":"block","block":{"id":"b-runs","kind":"runs","state":"loading"}}
+
+data: {"type":"block","block":{"id":"b-runs","kind":"runs","state":"ready","runs":[...]}}
+```
+
+The timeline (`client/src/features/chat/timeline.ts`) validates each event and adds a `block` part in stream order. A block with an id already in the turn replaces that part, so the server can send a loading skeleton first and the rows later. A loading block with no rows shows three skeleton rows shaped like the real ones. When the turn ends (`done`, `error`, or Stop) a block still loading shows the rows it has.
+
+Stored replies keep their blocks in `blocks` on the message (`ChatMessage.blocks`). History renders them after the reply text, through the same validation.
+
+## Composed views
+
+A composed view is one answer that arranges several blocks, or shows numbers that no single tool gives. "Flaky tests by hour of day" is one: a tile for the busiest hour and a chart of all 24 hours. The model writes a small tree, the server checks it and binds it to the tool results of the turn, and the app draws it with its own components (KAT-366). The model never writes HTML, CSS, a row, a link, or an action. The earlier plan for a model-written html view in a sandbox is dropped.
+
+### When a view shows
+
+The model decides, with no picker and no separate prompt. A question that one tool answers gets that tool and its block, or text. The `compose_view` tool exists for the rest, and its description says so: use it when the answer needs several blocks together, or numbers a tool does not give (by hour, by branch, before and after a merge). The rule picker for triage still runs first.
+
+On Slack and on a call the model still says the key numbers in words. The view is stored in the dot's chat, and the reply gets one line with a link to that answer. The reply is stored under an id the server picks before the turn starts, so the link carries it: `[The full view is in the chat](https://<public url>/#/chat/<dot id>?m=<message id>)` on Slack, and `[The full view is in the chat](#/chat/<dot id>?m=<message id>)` on a call, which the voice reads as plain words. The app opens the chat of the dot, scrolls to that message, and marks it with a soft panel; the reader stays there, and Latest goes back to the bottom. Slack has no link without a public URL, like every other link from the app, so the line names the dot instead: "The full view is in the chat of Checkout, in the localdost app." A call is not stored as a chat turn, so a view composed in a call is stored on its own as a message of kind `call_view`, under the same id.
+
+### The format
+
+The tool input is JSON. `root` is a column of nodes, at most 4 levels deep and 40 nodes in all.
+
+```json
+{
+  "title": "Flaky tests by hour of day",
+  "datasets": {
+    "byHour": {
+      "from": "r2",
+      "steps": [
+        { "op": "derive", "as": "hour", "expr": { "fn": "bucket", "of": "at", "by": "hour_of_day" } },
+        { "op": "group", "by": ["hour"], "agg": [{ "as": "flaky", "fn": "count" }], "fill": "hour_of_day" }
+      ]
+    }
+  },
+  "vars": { "peak": { "of": "byHour", "fn": "cell", "field": "hour", "row": 0, "format": "hour" } },
+  "root": {
+    "type": "column",
+    "children": [
+      { "type": "stats", "tiles": [{ "label": "Busiest hour", "value": "{peak}" }] },
+      { "type": "chart", "data": "byHour", "chartType": "line", "x": "hour", "xFormat": "hour", "series": [{ "field": "flaky" }] }
+    ]
+  }
+}
+```
+
+The registry of components is `VIEW_COMPONENTS` in `src/view-spec.ts`: one entry per component with every prop, its type, and its allowed values. The prop lists in the tool description (`viewSpecGuide()`) are written from it. Nothing else passes.
+
+| Component | Props | Shows |
+|---|---|---|
+| `column`, `row` | `children` | A stack. A row puts its children side by side when there is room and stacks them when there is not |
+| `section` | `title`, `children` | A heading over its children |
+| `tabs` | `tabs`: up to 6 of `{ label, children }` | One tab at a time. A tab list with the arrow keys, Home, and End |
+| `text` | `text`, `tone` (`muted`), `href` (http or https) | A short line. `{name}` marks take values from `vars` |
+| `runs`, `pulls`, `approvals`, `defects`, `probes`, `memory`, `ticket_review`, `release_call`, `test_cases`, `cards` | `from` (a result id), `nth`, `title`, `limit` | The block the server builds from that result, the same as the lookup tool shows alone |
+| `triage` | `window` (`last_merge`, `today`, `recent`), `title` | The failure triage, built from the stored runs |
+| `table` | `data` or `from`, `columns` (up to 6 of `{ field, label, format }`), `title`, `limit` | A table of a dataset, or of a result that is already a table |
+| `stats` | `tiles` (up to 6 of `{ label, value, sub, tone }`) or `from`, `title` | Tiles. `tone` is `ok`, `attention`, or `bad`: a name for a theme token, never a color |
+| `chart` | `data`, `chartType`, `x`, `xFormat`, `series` (up to 4 of `{ field, name }`), `unit`, `finding`, `limit`, `title`, or `from` | A bar, stacked bar, or line chart |
+
+A color is only a `tone`. A class name, a style, an event handler, an endpoint, or an `action` is not a prop of any component, so it is dropped and counted. The only link a view can hold is the `href` of a `text`, and it opens a new tab with `rel="noopener noreferrer"`.
+
+### Data
+
+Data comes from tool results only. Each lookup result of a turn gets an id (`r1`, `r2`, in call order), and the model reads it as `resultId` in the result (a list is wrapped as `{ resultId, rows }`). The server holds the full rows. The model filters through tools, and the view only arranges what came back.
+
+Only the chat's own dot feeds a view. A lookup made for another dot (a `dotId` that is not the dot of the chat) gets no id, and the model reads `viewSource: "Not a view source: ..."` with the result, which tells it to look the data up again for the chat's dot. The server checks it again where a dataset or a record node binds a result, and drops the part that names one, so a view never shows the data of a dot the chat is not for. A chat with no dot (the overview) reads any dot.
+
+- **Record blocks.** `{ "type": "runs", "from": "r1" }` shows the block that `list_runs` would show, built by the server from the result: its rows, its links, its approval ids. A lookup that the model marked `context` shows nothing alone, and a view may still use it. The view holds the block, so a block of the same turn that was streamed alone is dropped from the stream and from the stored answer.
+- **`test_results`.** One row per test per run, for the runs that finished their tests: `at` (the run time, ISO), `runId`, `dot`, `branch`, `kind`, `suite` (the last two parts of the spec path), `file`, `title`, `status` (`passed`, `failed`, `flaky`, `timedOut`), `durationMs`, and `retries`. It takes `dotId`, `sinceDays` (default 7, at most 90), `branch`, `status`, `file`, `kind`, and `splitAt: "last_merge"`, which adds a `period` column: `before` or `after` the newest merge into the default branch (there is no release record, so a release is that merge). A skipped test is not a result. The branch is the head of a PR check, the branch a merge went into, or the ref of a push. The model gets the columns, the count, and five rows; a call keeps at most 2,000 rows (the newest runs first) and counts the rest in `more`.
+- **Rows that were cut.** A source that holds fewer rows than the tool found (the 2,000 rows of `test_results`, or the 12,000 cells the server sends) keeps its `more` count in the view, so a count, a rate, or a list of branches over it covers part of the data. The view says so in a note under it: "Computed from 336 of 5,136 rows, so counts and rates cover only part of the data. Ask again with a shorter window or one branch to count all of it." The `compose_view` answer carries `partial` (the result, its tool, the rows it holds, and `more`) and tells the model to say so in its sentence and to give no total as a fact, or to call the lookup again with fewer days, one branch, or one spec. The rule-based chat does the same: its reply names the newest rows it read, and never says that only one branch ran when the rows that were left out may hold the other. The chat eval fails a view case whose view read cut rows when the answer does not say it covers part of the data.
+- **Datasets.** `{ "from": "r1" | an earlier dataset, "steps": [...] }`. The steps run in order: `filter` (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`), `derive` (a `bucket` of a time into `hour`, `hour_of_day`, `day`, `weekday`, `week`, or `month`, or `ratio`, `percent`, `change`, or `diff` of two fields, where the second may be a number), `group` (with `count`, `sum`, `avg`, `min`, `max`, `distinct`, each with an optional condition, and `fill` for every hour of the day or day of the week), `sort`, `limit`, and `pick`. Fields are plain names, or dotted names for the nested fields of a lookup result.
+- **Vars.** One value out of a dataset (`count`, `sum`, `avg`, `min`, `max`, `cell`), written in a format (`text`, `number`, `percent`, `duration`, `hour`, `weekday`, `day`, and `spec`, a test file path without its `.spec.ts`, so a chart names a suite as `e2e/cart`). A `{name}` mark in a text, a tile, or a finding takes the value. A table shows the words the runs block uses for a column called `outcome` (Product bug, Environment), `kind` (After merge, PR check), or `status` (Timed out), not the stored value.
+- **Figures.** Every figure on screen comes from a tool result, through vars. A tile `value` must hold a `{name}`, and a text, a tile `sub`, or a `finding` that holds a number typed by hand (`1234`, `99.9%`, `12ms`, `#58`) is dropped and the model is told which. A look-back window such as "the last 7 days", a title, and a label may carry a number: they name what the tool was asked for. The check reads digits only: a number spelled out in words, or a claim with no number in it ("everything passed") is not caught, so the sentence the model writes after the view is still its own.
+- **Time zone.** Hours and days follow the server clock, like the pass rate tool, so the sentence of the answer and the chart agree. The view carries `tzOffsetMin`, and a view that buckets a time says which clock it is under the view: "Hours and days are in UTC+7, the clock of the server that runs the dot."
+
+### Logic
+
+The expressions are data, not code. The steps above are all there is: a spec names no function, no global, and nothing to evaluate. `src/view-compute.ts` reads them and does arithmetic. It is pure, so the server runs the same code once before it streams a view: a column that is not in the data drops the dataset and every node that reads it, and the model is told which and why. The app runs it again in a Web Worker (`client/src/features/chat/blocks/view-worker.ts`), which returns values and never touches the page.
+
+- **No network, no DOM.** The worker removes `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `importScripts`, `BroadcastChannel`, `indexedDB`, `caches`, and sub-workers from its scope before its first message, and has no `document` or `window`. A browser keeps `fetch` on `WorkerGlobalScope.prototype`, so the lockdown cuts each name on the scope and on every prototype of it, and the self-check reports what a prototype still holds. The server also sends the worker file with `Content-Security-Policy: default-src 'none'; connect-src 'none'`, so the browser blocks a connection even if the lockdown failed. The e2e tests ask the real worker what it can reach, on its scope and on its prototypes, and run a script that has the same policy and no lockdown: it takes `fetch` from `WorkerGlobalScope.prototype` and tries a fetch, a synchronous XHR, a WebSocket, and `importScripts` against a server of the test, which sees no request. The same script without the policy does reach the server, so the result means something.
+- **Caps.** 2 seconds per call, then the worker is stopped and the parts that need it say so. At most 60,000 input cells, 400,000 row visits, and 500 rows per dataset. The server sends at most 2,000 rows of a source and 12,000 cells in all, and only the columns the view uses.
+- **A button never reads a computed number.** A view has no button of its own. A button of a block calls its own route (rerun, review, decide an approval, notes, ask a follow-up) with the id of its row, as the server put it there, and the route reads the server's records. Every action still goes through `gate()` and the Inbox. The model cannot define an action or an endpoint.
+
+### Checks
+
+`parseViewTree` in `src/view-spec.ts` checks every spec, and `parseChatBlock` calls it for a `view` block. The server runs it on what the model sends, and the client runs it again on what it receives, with the same rules as the blocks:
+
+- A component or a prop that the registry does not know is dropped and counted.
+- Depth (4), nodes (40), children (12), tabs (6), datasets (8), steps (8), and vars (12) are capped. Strings are trimmed and capped. A string that opens an HTML tag is dropped: a `<` followed by a letter, `/`, `!`, or `?`, with or without a closing `>`.
+- A figure the model typed is dropped (see Figures under Data), and a tile whose value holds no `{name}` goes.
+- Links are http or https.
+- A pipeline with one bad step drops its dataset, and every node and var that reads it, because a skipped step would show wrong numbers. A dataset or var cannot be named like a built-in (`constructor`, `toString`), and a field cannot be `__proto__`.
+- A record node must carry `from`, and a bound node must carry a valid block of its own kind. A model's spec is never bound, so it cannot hand a view its own block.
+
+### Fallback
+
+| Input | Result |
+|---|---|
+| Some nodes, props, or datasets invalid | The view with what is valid. The model is told what was dropped |
+| A chart or table over a dataset with no rows, or over a column it does not have | That node is dropped, with the reason |
+| The whole spec fails, and it holds nodes that read a tool result by id | Every block it contains, shown alone, in document order, however deep it was nested: the record kinds, the triage, and a `stats`, `chart`, or `table` with `from`, each with the `title` and `limit` the registry allows. A node built from a dataset has no block of its own, so it is left out |
+| The whole spec fails and holds no block | An error to the model, and the answer stays text |
+| The client cannot check a stored view | The blocks it holds in a plain column, then text |
+| The worker fails or is too slow | The nodes that read data say why in one line; the blocks the server built still show |
+| A node throws while it renders | One line for that node; the rest of the view stays |
+
+### Streaming
+
+The view appears while the model is still writing the call. The Anthropic API backend sends the input of a tool call as pieces of JSON, and `ViewStream` (`src/agent/chat-views.ts`) reads them as they come, without waiting for the end. `scanViewInput` walks the brackets and finds the complete values of `title`, `datasets`, and `vars`, and each child of `root.children` at the moment its closing brace arrives. Nothing is evaluated: a half-written node waits for the next piece.
+
+- The first event is a `view` block with `state: "loading"`, sent once the first node of the root has closed. It holds the title, the datasets the tool results can feed, the rows they read, and the vars. The number of nodes is not known yet, so there is no `total`, and the client shows one placeholder.
+- Then each node of the root is one event, `view_node { id, at, node }`, as soon as its closing brace has come. A node goes through the checks of the finished view first: the registry, the binding to a tool result, and the run of the pipelines. A node that fails any of them is skipped.
+- When the call ends, `compose_view` checks the whole spec and sends the finished `block` with the same id, which replaces what streamed. A node that the full check drops disappears then. When the full check fails, the server sends `view_drop { id }` first, so the preview goes, and then the blocks the spec holds, or nothing and the answer in text. A call that no tool call finishes (the same call twice in one message, or a turn that fails) also ends with `view_drop`.
+- Input the scanner cannot read (a spec wrapped in `spec`, a `root` written after the datasets it reads, more than 96,000 characters) streams nothing, and the finished view is sent as before. The preview is never stored and never changes what is stored.
+- A backend that receives the whole call at once (Claude CLI and Codex CLI, through the chat bridge) has nothing to read early. It sends the shell with `total`, then each node with a pause between them, then the finished block.
+
+The shell holds every column of a source, because the nodes that read them have not come; the finished view holds only the columns it uses. A node that has not come shows as a placeholder, and so does a node that waits for the worker. The transcript stays at the bottom while the view grows, because it ignores the scroll event of its own move.
+
+```
+data: {"type":"block","block":{"id":"b-view-1","kind":"view","state":"loading","view":{"sources":{...},"datasets":{...},"root":{"type":"column","children":[]}}}}
+
+data: {"type":"view_node","id":"b-view-1","at":0,"node":{"type":"stats","tiles":[...]}}
+
+data: {"type":"view_node","id":"b-view-1","at":1,"node":{"type":"chart","data":"byHour",...}}
+
+data: {"type":"block","block":{"id":"b-view-1","kind":"view","state":"ready","view":{...}}}
+```
+
+A stored reply keeps the finished view, with its sources, in `blocks`. `GET /api/messages` reads the blocks inside it again like any block: a draft that was decided shows as it stands, and a deleted one drops out.
+
+## Triage
+
+A chat answer can be a working tool built for the question (KAT-247). The first one is failure triage: ask "what broke?", "what failed since the last merge", "why is the run red?", "which tests are failing", or "anything flaky?" in the app chat, and the dot answers with one short line ("1 bug found by review and 3 tests failed or flaked in the last 6 runs of Checkout (since 09:30 today). Suspected causes: 2 product, 1 flaky.") and a `triage` block.
+
+**Picking the view.** `pickChatView` in `src/agent/chat-view.ts` runs before any model call. Today it is a keyword and intent rule; `setViewPicker` swaps in another picker, such as a decision API, with the same signature (it may be async, and a picker that throws means no view). The rule skips calls and Slack (no components there), report-scoped chats, refusals ("don't triage"), and lines with a PR link or a ticket key, which stay with the model. When the rule picks triage, the chat model is not called at all: the block is built from stored runs and the line is written from its counts.
+
+**Window.** `triageWindowOf` reads the question. "Since the last merge" reads the runs from the newest post-merge run of a merge into the default branch on; "today" reads the runs since local midnight; anything else reads the last 20 runs. Both named windows stop at 100 runs, and "since the last merge" with no merge on record falls back to the last 20 runs. A run counts when it finished and has test results or a QA review. The block carries `window` and `since` (the window start), and the empty state names both: "No failed tests and no bugs found in the last 4 runs (since 09:30 today)."
+
+**Rows.** `buildTriageBlock` in `src/agent/triage.ts` reads the runs of the window for the dot, or for every dot in the all-dots chat. Each bug the QA review found by reading the change is one row: the same list the run report shows under "Bugs found" (`findBugs`, review bugs only), with the bug title, severity, the code it points at, the run and its PR as chips, and the defect state. A newer review of the same PR replaces the older one, and a bug found again after the merge shows once: the newest finding, or the one that already has a defect. Each test that failed, timed out, or was flaky in one of them is one row with the test name and file, the newest run where it failed (as a run chip) and that run's PR (as a PR chip), the result in the newest run that ran it, how many of the runs that ran it it failed in, and the first error line.
+
+**Cause.** The suspected cause comes from the verdict of that newest failing run: product failure, test failure, environment failure, or flaky. A case that passed on retry is flaky. When the verdict names no cause, a test that also passed in the window is flaky, else product. Review bugs show first under "Found by review", most severe first; then the test groups in that order: product, test, environment, flaky.
+
+**Actions and state.** Rerun queues a rerun of the row's run through the existing endpoint, and marks every row of that run. Mark flaky saves a `flaky_spec` memory note in the format the runner writes (`file :: title (marked flaky in chat)`). Draft defect calls `POST /api/runs/:id/defect`, the run flows' draft path, so a second press or a draft the flow already made links that draft, and the draft waits in the Inbox under the default ask rule. A review bug row has one action that follows its defect state: Draft defect (`{bugKey}`) when there is none, a link to the Inbox while the draft waits, and Open defect with the tracker link once it is filed. A row counts as triaged once any action went through. The state lives in those records, not in the chat: the run's rerun job, the dot memory, and the defect approval. `GET /api/messages` reads it again for every stored triage row, so a reopened chat shows the same progress, including drafts approved or rejected in the Inbox since.
+
+## Blocks from lookup tools
+
+Nine read-only chat tools answer with a block (KAT-136). The tool still gives the model its own result. The server turns that same result into the matching block, so the model writes one or two sentences about the rows and never writes a row. `blocksFromToolResult` in `src/agent/chat-tool-blocks.ts` does the mapping. `executeChatTool` calls it after every tool call, so the block is the same on every backend: the Anthropic API, the Codex CLI and the Claude CLI (their calls come through the chat bridge into the same turn), and the rule-based reply that a CLI turn falls back to. Each block goes through `parseChatBlock`, streams as a `block` event right after the tool result, carries `tool` so the tool line leaves that call out, and is stored with the reply.
+
+| Tool | Block | Rows |
+|---|---|---|
+| `list_runs` | `runs` | One per run: the trigger title, status, outcome, tests passed (a pass on retry counts) and failed, the duration of the stored run, and when it started. The heading is "Recent runs", or "Runs that need attention" with `onlyProblems`. Runs left out by `limit` count toward `more`. The all-dots chat names the dot of each row. |
+| `runs_in_progress` | `runs` | The runs working now, headed "Running now". A queued job has no run yet, so only the answer text counts it. |
+| `open_prs` | `pulls` | One block per dot and repo, and the block names its repo, which Review now sends with the PR number. The last QA report line, its run, and the head branch come from the newest PR check of that PR, and a QA check that is running shows "Checks running". GitHub's own check state is not read, so no other state is claimed. |
+| `pending_approvals` | `approvals` | The stored approval records, so each card acts on its own record. `more` counts drafts beyond the tool's `limit`. |
+| `recent_defects` | `defects` | One per run that found a problem. The key is the ticket or PR the run was about (`TAD-3`, `#11`; a second run of the same PR is `#11 (2)`). Severity is High only when the run named a high risk. The status is the outcome in words. A headline that starts with the key does not repeat it. A run has no tracker issue, so a row has no Open button, only the link to the run. |
+| `probe_status` | `probes` | One per probe, named by host and path (the address shows only when it says more than the name). A probe whose last check failed shows Degraded until the dot calls an outage (three failures in a row); only a probe the dot declared down shows Down. |
+| `get_memory` | `memory` | The stored notes with their dot and time, so Edit and Delete find them. |
+| `list_tickets_reviewed` | `ticket_review` | One block per ticket, five at most, from the stored review run: risk, risks, test ideas, open questions, the ticket link, and the pending comment draft. |
+| `get_ticket` | `ticket_review` | The ticket's last review, only when the question is about the review (see below). |
+
+Rules:
+
+- **A block answers the question.** Each of the eight list tools, and `get_ticket`, takes an optional `context` flag. `pass_rate`, `flaky_by_spec`, and `list_cases` take none, and the chat prompt names only the tools that do. A call with `context: true` is a lookup the model makes only to decide its next step, for example to find the run it will rerun. It streams its tool result and no block, and stays on the collapsed tool line (KAT-133). The tool description and the chat prompt say so, and the chat eval checks that the expected kinds show and that a context lookup shows none (see CHAT-EVAL.md).
+- **`get_ticket` reads a ticket, which no block shows.** The ticket's stored review shows as a `ticket_review` block only when the question asks about that review (review, risks, open questions, test ideas, the comment the dot drafted) and the call is not marked `context`. These read the ticket and show nothing: "What is TAD-3 about?", a refusal ("do not review TAD-3"), a request for a new review ("review TAD-3 again", "please review TAD-3", which `review_ticket` answers), a question about the tracker ("the latest comment on TAD-3 in Jira"), and a general risk ("the risks of shipping TAD-3"). A model that reads the ticket before it acts marks the call `context`, and then no question can bring the old review back.
+- **A call shows no block.** The voice call hears the answer, so the server builds no block for the `call` channel. The call prompt asks the model to say the key items in words. A Slack thread gets the same words, and the reply is stored with its blocks for the app chat.
+- **No rows, no block.** A failed call, an empty result, and a result with no rows send no block, and the answer says so in text.
+- **Unknown data becomes a table.** Rows no component row can hold (a result without run ids, an approval the store no longer holds) go to the compact `table` block through the same fallback as any other unknown data, so the answer still shows something and never an empty frame.
+- **Actions stay inside the gate.** A row carries only what the server holds. The approvals block reads the stored records, and a ticket review carries an `approvalId` only for the pending `ticket_comment` draft of its own run, so Post comment is the person approving that exact text. Rerun, Review now, and the memory buttons call the routes the app already has. The model cannot add a link, an approval id, or an endpoint.
+- **A stored reply reads its records again.** `GET /api/messages` runs `refreshStoredBlocks` on every stored block. An approvals block shows each draft as it stands now and drops a draft the store no longer holds. A ticket review loses its `approvalId` once the draft is no longer pending, so a stale card cannot approve it. A runs block shows the run as it ended, and a memory block drops a deleted note.
+
+### Lead QA chat
+
+The chat of a Lead QA dot (KAT-405) has two more tools, both built from stored rows with no model call: `team_status` answers with a `table` block headed Team health (Dot, Job, Status, Needs a person, one row per member), and `release_call` answers with the `release_call` block. The read tools above take a member's name or id as `dotId`, or `all` (the default), and the rows say which member each came from. `rerun_tests`, `review_pr`, `review_ticket`, and `design_tests` go to the member whose job it is, under that member's own rules and cap; the answer reads "Asked PR Reviewer to review PR 412." and the result replies in the lead's chat with the member's name. One turn sends at most 3 such requests. The `release_call` block shows the answer word and the milestone, the blocking reasons under Why, the risks under Also with an Open button each, and the counts and the rule under Details. The block never offers release or hold.
+
+## Tests
+
+- `client/src/features/chat/blocks/blocks.test.tsx`: validation and fallback rules, the timeline, every component and its actions against stubbed API calls, and the tool line left out for a call whose data a block shows. `tool-lines.test.tsx`: the tool rows, folding words, the details toggle, errors, and reference chips in the answer text. `reasoning-card.test.tsx`: fold and unfold, the clock timer, the step count, the Details part with the token count, text-only steps, the live region, and the call transcript line.
+- `test/chat-reasoning.test.ts`: steps from the stream of each backend with and without summaries, tokens from `model_calls`, the stored work, and call receipts. `e2e/chat-reasoning.spec.ts`: the card while working and folded on the real client.
+- `client/src/features/chat/blocks/charts.test.tsx`: stats and chart validation and fallback, the axis math, and what the components draw (lines with gaps, bars sideways and upright, stacked bars, the hidden data table, RefChips).
+- `test/chat-stats.test.ts`: the pass rate and flaky-by-spec numbers from fixed runs and a fixed clock, and a chat turn that streams and stores the blocks.
+- `test/chat-tool-blocks.test.ts`: one test per lookup tool (the block is emitted, matches the stored data, and passes the validator), the `context` flag and the call channel, the table fallback, the gate rules for `approvalId`, the stored reply read again, and the block on the Anthropic API, Claude CLI, and Codex CLI backends, including the rule-based fallback.
+- `test/chat-eval-blocks.test.ts`: the chat eval fails a case when an expected block kind is missing (`blocks`, `blocksAny`, `noBlocks`), the case table in CHAT-EVAL.md names the kinds, and the runner (`src/cli/eval-chat.ts`) is run on the mock backend to check that it reads the `block` events of the stream.
+- `client/src/features/chat/blocks/triage.test.tsx`, `test/chat-blocks.test.ts`, and `test/chat-triage.test.ts`: triage validation, the view rule on seven phrasings, grouping, each action against its endpoint, and the state after a reload.
+- `test/triage-review.test.ts`: rows from review findings in each defect state, Draft defect by bug key, the window each phrasing picks, and the empty-state text.
+- `client/src/features/cards/cards.test.tsx`: every card kind (what it shows, the state colors by `data-state`, the marks per status and priority), each button against its stubbed route and its result in place, the comment field by keyboard, the unfurl of pasted links (read once per address, never for a bare key, errors with and without a retry), the cards block and its fallback, the run and Inbox lookups. `test/object-cards.test.ts`: references, the PR and ticket cards from fakes of GitHub, Jira, and Linear, the lookup route, the gated comment and status routes (act, ask, sandbox, archived), and the chat tools. `test/client-css.test.ts` checks the card colors and contrast in both themes.
+- `e2e/object-cards.spec.ts`: a streamed answer with all four cards, the keyboard path, the buttons against stubbed routes, a pasted link, the run card (the card of the run's own ticket, not a fixture), the Inbox cards, a PR in a list and a linked PR, and with `LOCALDOST_SCREENS=1` a screenshot of every card in both themes at 390x844 and 1280x800 (`LOCALDOST_SHOTS_DIR`).
+- `e2e/cards-live.ts` (`npx tsx e2e/cards-live.ts`): the cards from live server data. It starts the real server on port 5182 with an empty database, answers the GitHub, Jira, and Linear APIs from fixed fake responses, builds the client, and drives Chromium over a chat answer, three pasted links, a run, and the Inbox with nothing stubbed in the browser. It checks the data on the cards (the counts of the fake checks, the review decision, the stored QA report, the linked PRs, the last review, the run's card against its trigger) and saves its screenshots as `live-*.png`. It exits 1 when a check fails.
+- `test/view-spec.test.ts`, `test/view-compute.test.ts`, and `test/chat-views.test.ts` (KAT-366): the spec check (unknown component or prop, depth and node caps, strings, markup, links, injection strings, a pipeline with one bad step), the expression language over fixed rows, `test_results`, `compose_view` (binding, the stream while the model writes, `view_drop`, the fallback chain, rows that were cut, typed figures, the id each result carries, the link to the stored answer on Slack and calls), and the three questions through the rule-based chat, and over a busy dot whose rows were cut. `test/view-worker-csp.test.ts`: the worker script is served with a policy that forbids connections. `test/chat-views.test.ts` also runs `ViewStream` on input cut at every character and through a fake of the Anthropic stream. `test/chat-eval-blocks.test.ts`: the three view cases of the chat eval.
+- `client/src/features/chat/blocks/view.test.tsx` (KAT-366): the three views drawn from fixed rows, streaming and placeholders, a part that fails, tabs by keyboard, the actions of a block inside a view, the notes under a view (cut rows, the clock), words and units, `view_drop`, and the worker (it cannot reach the network on its scope or a prototype, a slow one is stopped). `client/src/features/chat/answer-link.test.tsx`: the route of a linked answer and the transcript that scrolls to it. `e2e/chat-views.spec.ts`: the same in Chromium with the real worker and its policy header, the probe of a script with that policy and no lockdown, a view that is dropped, a link to an answer, a live run against the server, and with `LOCALDOST_SCREENS=1` screenshots of the views and the fallback states in both themes at 390x844 and 1280x800 (`LOCALDOST_SHOTS_DIR`, default `/tmp/qd-evidence/kat366`).
+- `e2e/chat-blocks.spec.ts`: replays the fixtures (`client/src/features/chat/blocks/fixtures.ts`) through a stubbed `/api/chat` stream in the real app, then runs each action and the keyboard path, and checks the page never scrolls sideways.
+- Screenshots at 390x844 and 1440x900 in light and dark: `LOCALDOST_SCREENS=1 npx playwright test e2e/chat-blocks.spec.ts -g screenshots`, saved to `test-results/chat-ui/`.
+
+## Object cards
+
+A PR, an issue, a Jira ticket, and a Linear ticket show as compact cards wherever they appear: in a chat answer, under a message that holds their link, in a run, and in the Inbox. Each card mirrors the visual language of its own product at small size and is built with our own components and the brand marks of KAT-84. Nothing is embedded or loaded from those products, and there are no remote avatar images: a person is their initials.
+
+| Card | Head | Body | Colors |
+|---|---|---|---|
+| GitHub PR | Repo, `#number`, when it changed | Title, state pill (Open, Draft, Merged, Closed), `base <- head` branches, checks row, review state, `+lines -lines files`, author, labels, the latest localdost report | Pill: open green, merged purple, closed red, draft grey (Primer's public palette), white text at 4.5:1 |
+| GitHub issue | Repo, `#number`, when it changed | Title, state pill (Open, Closed, Closed as not planned), who opened it, assignee, labels in their own colors | The same pill colors |
+| Jira | Issue type mark, key, status lozenge | Summary, priority chevrons, assignee, labels as grey tags | Lozenge by status category (to do grey, in progress blue, done green), light and dark sets |
+| Linear | Priority bars, identifier, status circle with its word | Title, labels with a dot, assignee | Status circle by kind (backlog dashed, to do ring, in progress half, done filled, canceled crossed) |
+
+A ticket card also shows a description preview (three lines), the PRs that close or reference it with their titles and "Merged" when a merge run shows it, and the last localdost ticket review with its risk and whether its comment waits in the Inbox. A PR card shows checks as "All 7 checks pass", "1 of 7 checks failing", "3 of 5 checks running", or "No checks". When one failed or is still running, the card lists checks under that line, one row each with its own status icon and its name in plain sight, failed first, then running, then passed, up to five, with "2 more checks" for the rest. A name stays on one line and cuts with an ellipsis; its full text is the tooltip. When every check passes, the summary line stands alone. Every state has its own shape and its word, so color is never the only cue.
+
+### Where the data comes from
+
+`src/object-cards.ts` builds a card from what the dot's connections already read. The PR comes from `getPull` (state, draft, branches, lines, labels, requested reviewers), its checks from the check runs and commit statuses on the head (a token writes localdost' own check as a status), its review decision from the PR's reviews (the latest verdict of each reviewer counts, a dismissed one does not, changes requested wins), and its report from the newest stored run of that PR. A ticket comes from `fetchTicketRef`, which now also returns `status`, `statusKind`, `assignee` and `updatedAt` (Jira `status` and `assignee`, a Linear `state` and `assignee`, a GitHub issue's state and assignees). Linked PRs come from the links table (`closes`, `references`), titles from the stored runs. The review reads that were missing are new and optional on the GitHub client (`pullReviews`, `commitStatuses`), and a read that fails or times out leaves its row out: the card never shows a guess as passing.
+
+`GET /api/cards?ref=<link, key, or owner/name#N>&kind=<github_pr|github_issue|jira|linear>&dotId=<id>` answers `{ card }`. Without `dotId` the dot that watches the repo or lists the tracker key answers, else the only dot. Errors say why in words: 404 for a PR or ticket nobody has, 409 for a repo the dot does not watch or a tracker that is not connected, 502 when GitHub does not answer. `parseObjectCard` in `src/chat-blocks.ts` checks every card on both sides, with the same rules as the blocks: strings capped, links `http` or `https` only, label colors six hex digits or none.
+
+### Buttons and the gate
+
+Each action is a labeled button, and its result shows in place under the buttons.
+
+| Action | What it does |
+|---|---|
+| Open | Opens the object in its own product, in a new tab |
+| Review now (PR) | `POST /api/dots/:id/review { pr, repo }`: queues the PR check, or the merge review for a merged PR. Not shown on a closed PR |
+| Review ticket | The same route with `{ ticket }`: queues a ticket review. Its comment waits in the Inbox under the dot's rule |
+| Comment | Opens a field. Post comment sends `POST /api/cards/comment { ref, kind, dotId, text }`. A PR comment needs a repo the dot watches (409 otherwise, the same answer the card read gives), and is a `pr_comment` action marked `plain`, a new comment that replaces no QA report draft and never edits the sticky one. A ticket comment is a `ticket_comment` action marked `append`, so the sticky ticket review is not overwritten. The dot's rule for that kind decides: it posts, or it waits in the Inbox |
+| View diff (PR) | The PR's files in GitHub |
+| Change status (ticket) | Loads the statuses the tracker offers now (`GET /api/cards/status-options`: Jira transitions, a Linear team's states, or close, close as not planned, and reopen for a GitHub issue), asks for a pick, then `POST /api/cards/status { ref, kind, dotId, optionId }`. It is the new `ticket_status` action, `ask` by default and a row of its own in the rules matrix. An approved change calls the tracker: a Jira transition, a Linear `issueUpdate`, or a GitHub issue state. The draft in the Inbox has no Edit button: the move runs from the status that was picked, not from the draft's words, and `POST /api/approvals/:id` refuses an edit of it with 400 |
+
+Both writes answer `{ result, runId, approvalId?, note? }`. `executed` says it went out, `pending_approval` says it waits in the Inbox with a link, and `blocked` or `handed_off` carry the reason in `note` ("Sandbox mode is on, so nothing is sent outside localdost."). Each write runs on a run of its own, like a chat action, so the Inbox groups it under its PR or ticket. Sandbox mode refuses both, and an archived dot answers 409. A button never posts to GitHub, Jira, or Linear by itself.
+
+### Where cards appear
+
+- **Chat answers.** `get_ticket`, `review_ticket`, and `review_pr` stream a `cards` block with `tool` set, so the lookup line leaves the answer. The PR card is built after the tool answers, so GitHub's reads never hold the model.
+- **Pasted links.** A GitHub PR or issue address, a Jira browse address, or a Linear issue address in a message unfurls into its card under the message, up to three, each object once. A bare key or number does not unfurl. The client and the server read the message with one function (`src/object-links.ts`, `@object-links` in the client), so the dot's own answer adds no second card for exactly the objects that unfurled, and a fourth link, or an address that does not unfurl (a Jira board link), still gets its card in the answer. A link the dot cannot read shows the server's reason in one line, with Try again only for a failure that may pass. The transcript stays at the bottom while a card loads.
+- **Run detail.** The Trigger section shows the card of the run's PR or ticket above the facts.
+- **Inbox.** A group of drafts for a PR, issue, or ticket shows its card on the page, above the drafts, with no button first. The card reads its object when it comes near the screen (400px of margin), so a long Inbox does not read every PR and ticket at once; until then the card's place is a plain frame. A card the dot cannot read for a reason a retry will not change (not connected, not watched, not found) leaves no note in the Inbox, since the group head already names the object; a failure that may pass keeps its Try again.
+- **Lists and reviews.** A PR in the `pulls` block and a PR linked from a ticket card each have a Show card button that opens the PR's own card under the row (read when it opens, hidden again with Hide card). The `ticket_review` block starts with the ticket's card.
+
+The card is a size container: it lays out by its own width, the same on a phone and in a wide reply. Buttons wrap to a second row on a phone and keep full labels, 44px tall on touch and compact with a mouse. Light and dark are both designed, and the colors of GitHub, Jira, and Linear are tokens in `client/src/features/cards/cards.css` with checked contrast.
+
+## Steps card
+
+Each answer has a Steps card above its text (`client/src/features/chat/ReasoningCard.tsx`, KAT-374). A tester reads "reasoning" as model internals, so the card says Steps. Its header is one line in everyday words: `Working, 2 steps so far · 0:12` while the dot works and `Checked 4 things in 16 s` when the answer is done.
+
+- Steps are the summary lines the backend returned of its reasoning: a Codex CLI `reasoning` item, an Anthropic API summarized `thinking` block (`src/agent/reasoning.ts`). The server keeps the bold title or the first sentence of each, masks secrets, and caps it at 120 characters. A redacted thinking block, raw thinking, and the Claude CLI thinking stream never reach the chat. Each line renders as text, never as HTML.
+- Without a summary, each tool call is a step, in the tool-line words below. Either way each tool call is a row of the card: the running icon and `Checking runs`, then the result, and a tap opens it with `Show details`.
+- The timer reads `m:ss` and counts from the question while the dot works; once done the card shows the server's time for the turn (`16 s`, `2 min 5 s`).
+- The token count is not in the header. The expanded card ends with a Details part (`Tokens 269`) that sums the turn's `model_calls` rows. When no row knows its tokens (the mock, a CLI that reports none) there is no Details part.
+- The card is open while the dot works and folds to its header line when the answer is done. A tap opens or folds it (`aria-expanded` on the toggle); a fold chosen while the dot works holds until the answer is done. A polite live region says each new step (`Step 2: Reading the ticket`) and the end (`Checked 4 things in 16 s`). The spinner stops for reduced motion.
+- A plain answer with no steps has no card. A stored answer comes back folded, with its steps and tool rows.
+- Slack answers end with one line, `Checked 4 things in 16 s`, and the link to the dot's chat (`Answered in 2 s` when the turn took no steps). A call transcript shows the folded line under each answer.
+
+## Tool lines
+
+The calls a dot makes while it answers show as one quiet line above the answer text, collapsed: a small status icon, a past-tense phrase with the result in plain words (`Checked 213 runs`, `Read KAT-123 Cleaner lists`, `Looked up 2 tickets`), and the state word (`Done`, `Working`, `Failed`) where the line is wide. Several calls fold into one line (`Checked runs, 3 PRs and 2 tickets`). While a call runs the line reads `Checking runs` with the running icon, then turns into the done line.
+
+- A tap lists the calls with their plain results. `Show details` inside the list opens the raw input and result of each call, for debugging.
+- A call whose data an answer block already shows (`tool` on the block) is left out of the line. The match is by tool name, but a call the model marked `context` stays on the line, so a turn with a context lookup and an answering call of the same tool shows the lookup and the block. When every call is left out, there is no line.
+- A failed call (`tool_result.error`) is never folded away or hidden: it keeps a line of its own with the reason, such as `Couldn't check runs: Which dot? More than one exists; pass dotId.`
+- The words come from `client/src/features/chat/tool-lines.ts`; the server sends only the tool name, its input, and a one-line result.

package/docs/CONNECTIONS.md

@@ -0,0 +1,89 @@
+# MCP connections
+
+A connection plugs an MCP server into the dots' chat. The services localdost itself needs (model, GitHub, trackers, Slack, voice) connect from the Setup page instead, see [SETUP.md](SETUP.md). Once you attach it to a dot, the dot can call the server's tools when you chat with it in the app or in Slack. A test management system, a feature flag service, or an internal admin API are typical examples.
+
+## Add a connection
+
+Open Settings, Connections, and add a connection, or call `POST /api/connections`.
+
+| Field | Purpose |
+|---|---|
+| Name | Display name, at most 60 characters |
+| Transport | `http` for a Streamable HTTP server, `stdio` for a command localdost starts on its own host |
+| URL | `http` only: the server's MCP endpoint, for example `https://mcp.example.com/mcp` |
+| Command and arguments | `stdio` only: for example `npx` with `-y` and `@acme/mcp-server` |
+| Secret env var | Name of an environment variable that holds a JSON object. For `http` it holds the request headers, for `stdio` extra environment variables |
+
+The secret itself never goes into the database or through the API. You put it in the server's environment, and localdost reads the variable on every connect:
+
+```bash
+export ACME_MCP_HEADERS='{"Authorization":"Bearer <token>"}'
+```
+
+Then enter `ACME_MCP_HEADERS` as the secret env var. In `.env.localdost`, reference it from your shell or a password manager the same way as other secrets.
+
+After you save, localdost connects within 20 seconds and lists the server's tools. A server with more than 100 tools is cut at 100. Each tool has its own switch, so you can turn off the ones a dot should never see. Refresh a connection after the server adds tools.
+
+## Presets
+
+A preset fills in a known MCP server for you: the command, the env var names it reads, and which of its tools only read. In Settings, Connections, choose **Add from preset**, or call `POST /api/connections/presets/:id`.
+
+| Preset | What it starts | Env vars passed to the server |
+|---|---|---|
+| `aivision`: AI-Vision (Veesan) | `npx tsx <checkout>/apps/playground/demo/veesan-mcp.mts` from a local checkout of the AI-Vision server | `VEESAN_ENGINE_URL` or `AIVISION_PORT`, `VEESAN_TENANT`, and `VEESAN_SESSION_COOKIE` or `AIVISION_INTERNAL_TOKEN` when the server has sign-in on |
+| `midscene-web-bridge`: Midscene MCP (web bridge) | `npx -y @midscene/web-bridge-mcp`, the open-source Midscene server; the Midscene Chrome extension must be in bridge mode | `MIDSCENE_MODEL_BASE_URL`, `MIDSCENE_MODEL_API_KEY`, `MIDSCENE_MODEL_NAME`, `MIDSCENE_MODEL_FAMILY` |
+| `katalon-true-platform`: Katalon True Platform | An HTTP connection to the Katalon MCP server at the URL you enter. It starts no command | `KATALON_MCP_HEADERS` (request headers as JSON), attached only when the server has it set |
+
+Set the env vars on the localdost server, the same way as other secrets. The connection stores the names only and copies the values into the server process on every connect. A preset passes only the names it declares, so no other localdost secret reaches the MCP process. For the AI-Vision preset, `AIVISION_CHECKOUT` pre-fills the checkout path, and the AI-Vision server itself must be running.
+
+The Katalon True Platform preset is the one HTTP preset. It takes one parameter, the https address of the server, and stores that address on the connection. It carries no secret: when the localdost server has `KATALON_MCP_HEADERS`, the connection points at that variable by name. It marks nothing read-only itself, so a tool the server does not annotate as read-only goes through the `mcp_tool` rule (Ask first). The Next steps card offers it as the row **Connect True Platform**.
+
+The AI-Vision MCP server sends no `readOnlyHint`, so the preset names its read-only tools: listing and reading tests, runs, run status, reports, evidence, coverage, findings, and waiting for a run. These run without approval. Starting, stopping, or changing anything is an `mcp_tool` action and goes through the rules gate. Two guards apply on top:
+
+- `veesan_runs_wait` is capped at 50 seconds per call, inside the 60 second tool timeout. The dot calls it again while the run is not settled.
+- `veesan_runs_report` cannot take `saveTo`, so a read never writes a file on the host.
+
+The Midscene preset marks nothing read-only itself. Only tools the server annotates as read-only run without approval.
+
+When a dot has a connected AI-Vision connection, its chat tools carry the run loop: find cases, start a run (approval), wait, then read verdicts and screenshots. Flows reach the same tools through `callPresetTool(watch, 'aivision', tool, input, runId)` with the same rules, and `presetHintsForWatch(watch)` returns a short paragraph that the dot's chat prompt includes on every backend. The `codex-cli` and `claude-cli` backends reach the same tools through the localdost chat MCP server, so the model decides when to call `veesan_tests_list` or start a run, and a run start still waits for approval.
+
+## Attach to a dot
+
+A connection does nothing until a dot uses it. In Settings, select the dot and attach the connection, or set the dot's `connections` field to a list of connection ids with `PATCH /api/dots/:id`. Deleting a connection detaches it from every dot.
+
+In chat, each enabled tool appears as `mcp__<connection>__<tool>`.
+
+## Rules for tools
+
+MCP servers mark read-only tools with the `readOnlyHint` annotation. localdost trusts that mark:
+
+- A read-only tool runs as soon as the model calls it.
+- Any other tool is an outward action of kind `mcp_tool`. It passes the rules gate like a PR comment. The default rule is `ask`, so the call waits in the Inbox with its exact input until you approve it.
+
+Change the `mcp_tool` rule of a dot only when you trust every write tool on its attached servers. A tool call times out after 60 seconds, and a result longer than 20,000 characters is cut.
+
+## Stdio safety
+
+A stdio connection runs a command on the localdost host with the server's user. localdost accepts a new stdio connection, or a change to one, only when one of these holds:
+
+- `LOCALDOST_TOKEN` is set, so only token holders reach the API.
+- The request comes from the same machine.
+- `LOCALDOST_ALLOW_STDIO=1` is set.
+
+Prefer `http` connections on a shared or hosted server.
+
+## Data
+
+A tool call sends its input to the MCP server, and the result goes into the model prompt for that chat turn. Pick servers you would trust with the dot's chat context.
+
+## API
+
+| Route | Purpose |
+|---|---|
+| `GET /api/connections?dotId=` | Connections, optionally only those attached to a dot |
+| `POST /api/connections` | Create, then connect and list tools |
+| `PATCH /api/connections/:id` | Change fields, turn it on or off, or switch tools with `tools: [{ name, enabled }]` |
+| `DELETE /api/connections/:id` | Delete and detach from every dot |
+| `POST /api/connections/:id/refresh` | Reconnect and list tools again |
+| `GET /api/connections/presets` | Presets with their params, env var names and whether each is set, and read-only tools |
+| `POST /api/connections/presets/:id` | Create from a preset with `{ params, name? }`, then connect and list tools |