tinybeeai 0.0.0-stage → 0.16.1

package/docs/API-V2.md

@@ -0,0 +1,532 @@
+# API v2 contract (parity build)
+
+Additions to the v1 API in `SPEC.md`. Server and client tracks build against this file at the same time. Types go in `src/types.ts` (add fields only) and the client imports them from there through the `@shared` alias.
+
+## Setup readiness
+
+`GET /api/setup` returns:
+
+```ts
+interface SetupStatus {
+  demo: boolean;
+  services: {
+    key: 'model' | 'github' | 'jira' | 'linear' | 'slack' | 'push' | 'publicUrl' | 'sandbox' | 'voice';
+    label: string;            // "Model", "GitHub", ...
+    state: 'ready' | 'demo' | 'missing' | 'error';
+    detail: string;           // "Claude CLI (claude-sonnet-5-5)", "PAT mode", "Not configured"
+    docs: string;             // relative docs link, e.g. "docs/SETUP.md#github"
+  }[];
+}
+```
+
+`docs` names the guide section for the service. The app opens it in the in-app docs at `#/docs/<name>#<anchor>`, for example `docs/SETUP.md#public-url` opens `#/docs/setup#public-url`.
+
+## Test engines
+
+`GET /api/setup/engines` returns the workspace default engine and the two engines behind it (KAT-224):
+
+```ts
+interface TestEnginesView {
+  default: 'auto' | 'playwright' | 'aivision';   // what a dot without runner.engine uses
+  source: 'env' | 'saved' | 'auto' | 'unset';    // env: LOCALDOST_TEST_ENGINE. auto: follows which engines are ready. unset: nothing chosen, AI-Vision only
+  envName?: 'LOCALDOST_TEST_ENGINE';                // with source env
+  engines: {
+    key: 'playwright' | 'aivision';
+    label: string;                               // "Playwright e2e", "AI-Vision"
+    runs: string;                                // what it runs, in one sentence
+    state: 'ready' | 'missing';
+    detail: string;                              // "Ready. ..." or "Missing: ..."
+    defaultOn: boolean;                          // the workspace default includes it
+  }[];
+}
+```
+
+`PUT /api/setup/engines` saves the default and answers with the new view. The body is `{ "playwright": boolean, "aivision": boolean }` (both on is `auto`) or `{ "auto": true }` to follow which engines are ready again. It answers 400 when both are false or the body is wrong, and 409 while `LOCALDOST_TEST_ENGINE` is set. It follows the rules of the other Setup writes: a token, or this machine only.
+
+## Docs
+
+The app shows README.md and the guides in docs/ on the Docs screen (`#/docs`). Both routes are read-only and resolve only names on a fixed list in `src/routes/docs.ts`, so no request reaches another file.
+
+| Route | Returns |
+|---|---|
+| `GET /api/docs` | `{ docs: { name, title, group }[] }`, the guides present in this install. `group` is `guide` or `reference` |
+| `GET /api/docs/:name` | `{ name, title, group, markdown, updatedAt }`. `name` is lower case (`setup`, `github`); `SETUP` and `setup.md` work too. 404 for a name off the list or a file missing from the install |
+
+## Dots (Watch additions)
+
+`Watch` gains: `role: 'product-area' | 'qa-lead' | 'release-guard' | 'ticket-reviewer' | 'prod-watcher' | 'custom'`, `instructions: string`, `mascot: 'pip' | 'nova' | 'bolt' | 'moss'`, `connections: string[]` (connection ids), `slackChannel?: string`.
+`GET /api/roles` returns role presets `{ key, label, description, defaults: Partial<Watch> }[]`, Product area first. `defaults.stages` holds the six stage switches of the preset ([STAGES.md](STAGES.md#63-stage-presets)).
+`POST /api/dots` and `PATCH /api/dots/:id` accept every Watch field except `archived`, which only the two routes below set. A paired device holds a role (see [Joining a team server](#joining-a-team-server)): a member may call `PATCH` with a body of only `{ "paused": true }` or `{ "paused": false }`, an editor may send any field, and any other body from a member is a 403 `phone_blocked`.
+`DELETE /api/dots/:id?mode=archive|delete` removes a dot, and `POST /api/dots/:id/restore` brings an archived one back. No paired device may call either, whatever its role: both answer 403 with code `phone_blocked` and need the admin token, or a loopback browser on a server with no token. Both modes close the dot's pending approvals as rejected, each with a reason (`closedReason` on the approval and a step on its run).
+
+- `mode=archive` (the default) sets `archived` and `paused`, stops the dot (pollers, probes, webhooks, and the digest skip it), drops its queued jobs, cancels its running runs, and keeps every run, case, memory item, and file. The dot leaves `GET /api/dots` unless `?archived=1` is set. Archiving twice is fine. Answers `{ ok, archived: true, approvalsClosed, jobsStopped, runsCancelled }`. Retrying a run of an archived dot answers 409.
+- `mode=delete` also needs `confirmName` set to the dot name (spaces at either end do not count), or it answers 400 and removes nothing. It then removes the dot and its runs, approvals, outbox items, memory, chat, test cases and results, events, jobs, links, probe state, report pages, poll cursors, and the artifact folder of every run. Rows of other dots and shared records (repos, connections) stay. It works on an archived dot too. Answers `{ ok, deleted: true, approvalsClosed, jobsStopped, runsCancelled, rows, artifactFolders }`.
+- `POST /api/dots/:id/restore` answers the dot. It is paused only if it was paused before it was archived. 404 for an unknown dot, 409 for a dot that is not archived.
+`runner.setup` holds install and build steps; `runner.command` is the test command, and both routes answer 400 when it holds a shell operator (`&&`, `|`, `;`, redirects). `POST /api/runner/try` runs the setup and command once and `GET /api/runner/try/:id` returns the result, see [SANDBOX.md](SANDBOX.md#try-it).
+`runner.passEnv?: string[]` names host variables for the test login of the app under test (KAT-361): each starts with `LOCALDOST_TEST_`, at most 20, saved trimmed and without repeats, and both routes answer 400 for any other name. A run sees each one that is set as `TEST_<rest>`. `GET /api/runner/pass-env?names=A,B` answers `{ names: [{ name, as, set }] }` for valid names (`as` is what the test sees, `set` is whether the server has it) and never a value; 400 for a name outside the rule. See [SANDBOX.md](SANDBOX.md#test-login).
+`TestReport` adds `notRun?: { stage: 'setup' | 'command' | 'report'; reason: string; exitCode?: number | null }` and `setup?: { steps, cache: 'hit' | 'miss' | 'none', durationMs }`.
+
+## Dot health
+
+`GET /api/dots/:id/health` (KAT-394) answers the one question at the top of a dot's page: does this dot need me? It reads rows the dot already stores in one pass. It calls no model and no tracker. The server keeps the answer 30 s per dot, and a run, an approval, or a status change of the dot drops it. 404 for an unknown dot.
+
+`GET /api/dots/health` answers the same for every dot of the list in one request: an object by dot id (`{ [dotId]: DotHealth }`, archived dots only with `?archived=1`). It reads the same kept answers, so a dot has one answer in the list and on its page. The dot list takes its status word and its last-check time from it, and so do the Dots page header count and the sidebar dots; no row asks for its own health.
+
+`GET /api/room` answers the Room page (0.15.0, `src/room.ts`): `leads` (each lead with its status, `statusReason`, `digestHour`, `digestEvery` and release call), `dots` (every dot that is not a lead or archived, with `status`, `statusReason` (the health reason in the words of the Board: "needs a person" for the last merge, "drafts to review" for Inbox drafts), `reasonRun` (the latest merge as `{ ref, open }`, only when the reason says the last merge needs a look), `now`, `next`, `nextCount`, `waitsForLimit`, `inbox`, `today` and `probes`), `jobs` (one card per job with `column` set to `queued`, `working`, `waiting` or `done`, its `ref`, the in-app link `open`, and `details` with run, job and draft ids and the stage), and `doneToday`. The same item queued more than once for a dot is one `queued` row (KAT-408): `count` says how many jobs it stands for (only from 2 up), `details.jobIds` lists them, `ref` carries the newest title, `at` the oldest turn, and `held` stays only when every one of them is held. `nextCount` counts those items, and `waitsForLimit` says how many of them wait for the dot's daily model cap (`held: "model_cap"`). A `waiting` card is one run and its `drafts` counts the Inbox drafts of that run, and that run is not in `done` as well; the page counts drafts, in its subtitle and in the Waits for you column alike, so the number it shows is the sum of `drafts` over the `waiting` jobs. Only a PR or a ticket groups, by the repo or tracker in its key (`testops-fe#1292`, `product#4666`, `KAT-408`); a merge, a failed build and a site check have no such key, so each stays its own row. A job a person asked for (`requestedBy`) and a `pr_check` of another head commit never group with another job, since each of them runs and posts. On a server in sandbox mode no site check runs, so every probe reads `unknown` with no check time. It reads the job queue, the runs, the live Inbox drafts and the site check states, makes no model or tracker call, and keeps one answer for 2 seconds.
+
+```
+{
+  status: 'failing' | 'needs_you' | 'healthy' | 'not_watching',
+  statusReason: string,
+  watching: {
+    on: boolean,
+    state: 'on' | 'paused' | 'archived' | 'sign_in' | 'github' | 'nothing' | 'site_off' | 'site_sandbox',
+    note: string | null,
+    lastCheck: { kind: JobKind | 'site', ref: string | null, title: string, at: string, runId?: string } | null,
+    trial: { day: number, days: number } | null,
+    postsWait: boolean
+  },
+  tiles: { review, bugs, checks, release, site, tests, tickets, ai },   // each: { title, state, line, action, facts }
+  suggestion: { rule, text, action } | null,
+  team?: TeamHealth,                    // set on a Lead QA dot only, see Lead QA dot (KAT-405)
+  builtAt: string
+}
+```
+
+Status, first match wins:
+
+- `not_watching`: the dot cannot watch: it is paused or archived, the AI sign-in of the default model expired, GitHub turned the sign-in down or does not answer, a poll alarm is up, nothing brings a PR to it, or there is nothing to watch (`statusReason` says "Nothing to watch yet." for a dot with no repo, tracker or site). It comes first, so a QA site that is down shows on its own tile and the dot still reads Not watching. No check in 24 hours is not a cause: a quiet repo on a weekend is normal, and `watching.note` carries it. The sentence names the trouble and never an order; `statusFix` (the Open Setup link, for the admin) says where it is repaired.
+- `failing`: a site check is down, or the latest merge into the default branch found a confirmed bug: a verdict of `product_failure` or `test_failure`, or failed tests with no verdict that are not an environment failure or flaky. A merge with a verdict of `needs_attention` is not a confirmed bug: it reads `needs_you`.
+- `needs_you`: a draft waits in the Inbox, a ticket review of the last 7 days left open questions, or the latest merge has a `needs_attention` verdict.
+- `healthy`: none of the above.
+
+`watching.state` says whether the dot watches and what stops it: `on`, `paused`, `archived`, `sign_in` (the AI sign-in), `github` (GitHub does not answer, or nothing brings a PR), `nothing`, or, for a dot whose only source is a QA site, `site_off` (the Prod watcher is off) or `site_sandbox` (sandbox mode): no site check runs, so nothing can come in. The Watching strip heading is "Watching" for `on` and "Not watching: <reason>" otherwise, so it agrees with the headline word, and it carries no site health. `watching.note` is one line for a dot that watches but has nothing recent: "Quiet: no check in 24 h", "Checks started, but none of them finished.", "The first check is still running.", or the first-check sentence ("No checks yet. The first site check runs within a minute." only where site checks run; a site-only dot where they do not run is Not watching and has no note). It is `null` while a check under a day old exists and for a dot that does not watch. A check that failed, was interrupted, is still running or could not run its tests is not a check; a site check is.
+
+`watching.trial` is the first week of the dot (`shadowWeek`): `{ day, days }` while it runs, `null` after. `postsWait` is true while the PR comment rule asks first.
+
+Tiles. `state` is `ready` (the `line` says it), `not_set_up` (nothing feeds the tile: the line is `Not set up` and the action is `{ label: 'Set up', setup }`, never a zero), or `error` (the tile could not be read and the others still answer). `action` holds one of `href` (an app link), `run: 'site_check'`, `setup: 'site' | 'tracker' | 'repo' | 'cap'`, `focus: 'model_usage'`, or `draft` (open the chat with that text). A tile with nothing to open has `action: null`, never a button that goes nowhere.
+
+| Tile | Reads | Not set up when |
+|---|---|---|
+| `review` | Drafts waiting and not expired: count and the age of the oldest. | Never. Zero reads "Nothing is waiting". |
+| `bugs` | Bugs the dot filed (executed drafts of `file_defect`, and of `issue_create` with a bug signature, which is how the defect flow drafts a new bug; and bugs a check filed on its own, from runs of any age): open, and new in the last 7 days. A GitHub issue the dot reads as closed is not open; a Jira or Linear bug counts as open. | The dot has no tracker and no repo to file a bug in. |
+| `checks` | Checks of the last 7 days (PR checks, merge checks, CI failures, reruns) by outcome: passed, bug, needs a look (only the latest merge says "1 merge needs a look"; a CI failure or a rerun says "1 needs a look", and an older merge a newer merge replaced is not counted), could not check. A check that skipped its tests on purpose (Run tests off, a docs only change) and ended with a pass counts as passed. Running checks are listed apart. | The dot has no repo whose tests it runs (`setup: 'repo'`) and no check this week. |
+| `release` | The nearest open milestone of the dot's requirements (traceability): tickets tested of all. The nearest is the soonest dated milestone from today on that still has a ticket not passing, else the latest past one, else the first in the tracker order. A GitHub tracker limited to milestones only looks at those. | No requirement has a milestone. |
+| `site` | The dot's site checks (`probes`): up, slow, failing or down, response time and time since the last check. `action.run` is `site_check`, and it is `null` for a paused or archived dot and on a sandbox, where the server refuses the check. A dot whose only source is the site, with site checks off or in a sandbox, gets the reason as the line ("Turn on site checks to start watching this site.") and no action. | The dot has no site check. |
+| `tests` | Tests of the last 7 days: flaky (passed on a retry) and needing a fix (the newest result on the default branch failed). A test is counted once. | The dot has no repo whose tests it runs (`setup: 'repo'`) and no result this week. |
+| `tickets` | Ticket reviews of the last 7 days: tickets reviewed and tickets whose newest review left questions. | The dot has no tracker and no review. |
+| `ai` | AI calls used today against the daily cap (`74 of 150 AI calls used`). | The dot has no daily cap. |
+
+Suggestion, one item, from the first rule that matches (`rule` names it):
+
+1. `release_without_cases`: a ticket of the nearest open release with no run, no spec, and no test case. The first one in tracker order. The text names a Jira or Linear ticket by its key (`PROD-1234 is in the release and has no test cases yet.`) and a GitHub ticket by its quoted title, since `owner/repo#115` tells a reader little. The action is `draft`.
+2. `bug_came_back`: a bug filed earlier was drafted again in the last 7 days (same bug signature, so the tracker no longer showed the first issue as open). Drafts of `file_defect` and `issue_create` both count. The newest draft wins. The text puts the title in quotes (`The bug "Total is wrong" came back after it was fixed.`).
+3. `flaky_test`: a flaky test with 3 or more flaky or failed results this week. Most results first, then newest, then path and title. The text names the test by its title, with no file path (`The test "cart" was flaky 3 times this week: it failed, then passed on a retry.`; a test with a real failure says `was flaky or failed`).
+4. `merge_look`: the latest merge ended with a `needs_attention` verdict (`The last merge needs a look.`). The action is `href` to its run.
+5. `ai_calls_low`: 80 percent or more of the daily calls used. The action is `setup: 'cap'`. A member sees the text and no button, and the card says who can act.
+
+`POST /api/dots/:id/site-check` runs the dot's site checks now (the QA site tile's Check now). It answers `{ ok, results: [{ url, ok, latencyMs, error? }] }`. 409 for a paused or archived dot, a dot with no site check, and a sandbox. A paired device may not call it.
+
+## Lead QA dot (KAT-405)
+
+A lead is a dot that names member dots and reads the rows they store. The build spec is [LEAD-DOT.md](LEAD-DOT.md), and [SETUP.md](SETUP.md#lead-qa-dot) says how to make one. A lead holds no repos, tracker, site checks, runner, review options, or stage switches of its own.
+
+`Watch` gains two fields. `POST /api/dots` and `PATCH /api/dots/:id` take both.
+
+- `kind?: 'dot' | 'lead'`: unset means `dot`. It is set on `POST` and never changes: a `PATCH` that names the other kind answers 400 `A dot cannot change kind. Make a new lead.`
+- `memberIds?: string[]`: the dots a lead names, 1 to 8, in the order the team panel shows them. A `PATCH` that leaves it out keeps the members; one that sends it replaces the list.
+
+A save of `kind: 'lead'` answers 400 with one of these, and saves nothing:
+
+| Refusal | When |
+|---|---|
+| `kind must be dot or lead.` | `kind` is any other value |
+| `Only a lead has members.` | `memberIds` is set on a dot |
+| `A lead has no repos, tracker or site checks of its own. Set them on a member.` | the body holds `repo`, `repos`, `tracker`, `probes`, `statusPages`, `baseUrl`, a `runner` with more than a `mode`, `review`, or `stages` |
+| `A lead names 1 to 8 dots.` | no members, more than 8, an id twice, or an id that is not a string |
+| `No dot with id <id>.` | a member that does not exist |
+| `<name> is a lead. A lead cannot be a member of another lead.` | a member that is a lead |
+| `<name> is archived. Restore it first.` | an archived dot added as a member; a member archived later keeps its place |
+
+A dot is in at most one lead, archived leads included, so a restore never gives a dot two leads. A save that adds a dot another lead holds answers 409 `<name> is already in <lead>. Remove it there first.` `GET /api/dots` and `GET /api/dots/:id` return `leadId` on a member (the id of the live lead that names it) and `memberIds` on a lead. A lead matches no webhook event.
+
+The chat message of a team digest (`GET /api/messages`, the live `update` event) carries `update.details`: Markdown with the counts and each member's own digest, which the chat draws under a Details fold below the message. The message text and the Slack post do not hold it, since the chat never renders raw HTML and Slack cannot fold.
+
+`GET /api/dots/:id/team` answers `TeamHealth` for a lead: the team word and one row per member. It reads the same kept answers as `GET /api/dots/:id/health`, so a member has one answer in its row and on its page. 404 for an unknown dot, 409 for a dot that is not a lead. The team panel reads the team again every minute and when a member publishes. The Open button of a row goes to the member's page, or to the `action.href` of the member's own health answer when that button is a link (an app route such as `#/setup`, or the tracker address of a bug already filed, which opens in a new tab); an action that runs, sets up or drafts needs the member's page.
+
+`GET /api/dots/:id/health` for a lead answers a `DotHealth` whose `status` and `statusReason` are the team's, whose `tiles` are all `not_set_up`, whose `suggestion` is `null`, and whose `team` holds the `TeamHealth`. Its `watching.state` is `on`, or `nothing` when the team reads `not_watching`. A lead that a person paused or archived reads `not_watching` with its own reason and `watching.state` `paused` or `archived`. The client draws the team panel whenever `team` is set, and the dot list and the sidebar read the one status word from it.
+
+```
+TeamHealth = {
+  status: 'failing' | 'needs_you' | 'healthy' | 'not_watching',
+  statusReason: string,                  // "Regression Runner: the last merge found a bug."
+  members: {
+    id: string, name: string,
+    job: string,                         // "Ticket review, Test cases": the stages that are on
+    status: HealthStatus,
+    away?: 'paused' | 'archived',        // a member a person stopped; it does not count toward the word
+    need: string,                        // the member's own statusReason, or "Nothing needs you."
+    action: HealthAction | null          // the member's own button; null when nothing needs a person
+  }[],
+  inbox: number,                         // live Inbox items across the members
+  builtAt: string
+}
+```
+
+The team word is the worst status among the members that are not away, in this order: `failing`, `needs_you`, `not_watching`, `healthy`. A member a person paused or archived has `away` set, shows `Paused` or `Archived` as its need, and does not count. A team with no member left to count reads `not_watching`: `Every dot of the team is paused or archived.`, or `The team has no dots. Add one in the lead settings.` for an empty list. `statusReason` names the first member in list order that holds the word, with that member's reason after the colon and `(and N more)` when others hold it too (`Regression Runner: the last merge found a bug.`). A team where every counted member is healthy reads `Nothing needs you.` A healthy member that has a suggestion shows the suggestion text as its need.
+
+`GET /api/dots/:id/release?milestone=` answers the release call of a lead for one milestone, or for the nearest open one when `milestone` is left out. It reads stored rows and calls no model. 404 for an unknown dot, 409 for a dot that is not a lead.
+
+```
+ReleaseCall = {
+  milestone: string,
+  answer: 'ready' | 'ready_with_risk' | 'not_ready' | 'no_tickets',
+  summary: string,                       // "14 of 19 requirements passing, 1 failing, 3 not tested"
+  counts: ReadinessCounts,
+  reasons: { level: 'blocker' | 'risk', text, ref?, href?, memberId, memberName? }[],
+  milestones: string[],                  // every milestone of the members' trackers, for the picker
+  rule: string,                          // the rule that set the answer, in one sentence
+  builtAt: string
+}
+```
+
+The answer is the first rule that matches, and `rule` carries its sentence. `no_tickets`: no requirement of the members has this milestone (`reasons` is empty). `not_ready`: a requirement of the milestone is failing, a bug is open against one, or the latest after-merge check of a member that runs them found a bug. `ready_with_risk`: a requirement is not tested, partly tested or out of date, a bug report for a ticket of the milestone waits in a member's Inbox, a test of those tickets was flaky 3 or more times this week, or a member that nobody paused is `not_watching`, so its data may be old. `ready`: none of the above. `reasons` lists the blockers first. The milestone is the nearest open one of the members' trackers when `milestone` is left out. When no milestone is open because every requirement passes, it is the newest milestone of the team's rows (the latest dated one, else the last in natural order), so a team that passes everything reads `ready` with `19 of 19 requirements passing`, not `no_tickets`. `no_tickets` with an empty `milestone` is left for a team whose requirements name no milestone at all. The daily digest asks for the open milestone only, so a milestone that is done never reads "Release 2026.11 is ready" every morning. A reason may carry `openLabel` (`See them` for a group of tickets, `Review` for a bug report that waits in an Inbox): the words of its button in a chat answer, where the page keeps Open. The server keeps an answer 30 s per lead and milestone, and a run, an approval, or a save of a member drops it. The call is read-only: it posts and files nothing, and it never says release or hold, the readiness words only.
+
+`POST /api/dots/:id/digest` makes the team digest now. It answers 202 `{ ok: true, jobId }`, or 200 `{ ok: true, duplicate: true }` when a digest of the same lead was already made in the same 10-minute slot. 409 for a dot that is not a lead, and for a paused or archived lead. The digest is text built by code from the members' rows. It makes no model call and counts nothing against a daily cap. It replies in the chat of the person who asked and nowhere else: the daily digest at `digestHour` is the only one that goes to the lead's `slackChannel`. A paired device may call this route.
+
+`GET /api/dots/:id/delete-preview` answers `{ otherRunItems, onlyMemberOf }` for any dot: the test run items of other dots that point at this dot's test cases and go with them (`{ dotId, dotName, items }[]`), and the lead that has this dot as its only member (`{ id, name }`, else `null`). The delete dialog reads it before it asks for the name. `DELETE /api/dots/:id?mode=delete` answers 409 for a dot that is the only member of a lead, since a lead always keeps 1 to 8 members. Its summary adds `leadsChanged` (the leads that lost this member) and `otherRunItems`. An archive keeps the member in its lead's list.
+
+Other routes that need a repo, tracker, site check, or runner answer 409 `<name> is a lead. Ask a member for this.` for a lead: `PUT` and `POST /api/dots/:id/review`, `GET /api/dots/:id/pulls`, `POST /api/dots/:id/cases`, `POST /api/dots/:id/site-check`, and `POST /api/runner/try` with its `dotId`.
+
+Team data. A ticket, its cases, its PR links and its results can sit on different members, so these reads cover every member of the lead:
+
+- `casesForTicket` and the case lookups of a PR check, of a merge, and of a test run read the cases of all members, and a result lands on the case's own dot. Traceability (`GET /api/dots/:id/traceability`) and the release call read the members' links, runs, and test results. The ticket reader of a member with no tracker uses the first member that has one.
+- The PR review of a member reads the tickets a PR links when their repo is the dot's own tracker or repo, or the tracker repo of another dot of the team (PR Reviewer has no tracker of its own).
+- A bug report that two members find is one Inbox item. Both runs go to `meta.sources` of the draft (`{ watchId, runId, at, pr?, head?, task?, bugSig? }[]`), and the item sits on the member that found it first. `GET /api/approvals` adds `foundBy` (`Found by PR Reviewer and Regression Runner.`) and `sources` (`{ dotName, runId, at, bugSig }[]`) to an item with more than one source. Rejecting it counts for every source, and a bug already filed or rejected by any member is not drafted again.
+
+Chat. A lead's chat takes the questions of the members' dots. `AskOrigin` of a web ask gains `scope: 'lead'` and `leadId`. The read tools take a member (its id or name) or `all`, and `all` is the default. A request that is an action for a member (`rerun_tests`, `review_pr`, `review_ticket`, `design_tests`) goes to the member that does that job, under that member's rules, cap, dedupe, and deploy wait. The answer says so ("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 `team_status` and `release_call` tools are built by code from stored rows, with no model call, `team_status` answers with a `table` block headed Team health (Dot, Job, Status, Needs a person), and `release_call` with the `release_call` block; see [CHAT-UI.md](CHAT-UI.md#component-registry).
+
+Phone. A paired device may call `POST /api/dots/:id/digest`. It may not save or delete a lead, since those need the admin token like any dot save.
+
+## Repos
+
+A dot holds a set of repos with a role each, see [MULTI-REPO.md](MULTI-REPO.md#1-data-model-workspace-repos-and-per-dot-repo-sets).
+- `Watch.repos?: { repo: 'owner/name', role: 'app' | 'test' | 'docs', defaultBranch?, pathFilters?, prScope?, runTests?, deployEnvironment?, waitForDeploySec?, deployUrlMatch?, test?, targets? }[]`. `deployUrlMatch` (app repos only) is a host or an origin, with no path, that picks which deployment address the tests of a merge run against; an admin setting. `runTests: false` (app repos only, KAT-361) reviews the repo's pull requests and merges and runs no tests for them; only `false` is stored, and the routes answer 400 for a non-boolean or for a test or docs repo, see [SANDBOX.md](SANDBOX.md#run-tests-per-repo). `repo` carries the switch of the first app repo too. `prScope` (app repos only) is `{ authors?, team?, skipDrafts?, skipBots?, linkedIssueLabels? }`, see [SETUP.md](SETUP.md#pr-scope); `repo` carries the first app repo's scope too. `POST /api/dots` and `PATCH /api/dots/:id` check it: ids are `owner/name`, each repo once, a test repo needs an app repo, `targets` name app repos of the dot. `repo` is rewritten from the first app repo on every save. A body with only `repo` (the single-repo form) replaces the first app repo in its place and keeps the others in their order; `repo: null` drops it. `repo.defaultBranch` on a dot you read is the branch a run reads for the first app repo now, so a form that sends it back changes nothing. A repo the workspace lacks is added on save; with GitHub connected, a repo the connection cannot read is a 400, and a GitHub error while checking it is a 502 (nothing is saved). `nightlyRun` is `{ on, time?, days? }` or `null` (KAT-390): the nightly test run of the dot's Tests repo against its Base URL. `on` is required and a boolean, `time` is `HH:MM` on the server's clock (default `02:00`), `days` is a non-empty list of whole numbers from 0 (Sunday) to 6 (Saturday) (default `[1, 2, 3, 4, 5]`); a save stores all three, with the days sorted, and `null` turns it off. Turning it on needs a Tests repo and a Base URL (a demo dot needs none) or the answer is a 400 with the reason; a Lead QA dot cannot have one. A save that changes `on`, `time` or `days` sets `nightlyLastSlot` (ISO, read-only: a client cannot write it) to the latest slot up to now, so slots before the save never run, and a save that sends the same schedule leaves it alone. A save that takes the last Tests repo away turns a stored schedule off. Each slot queues one job of kind `nightly_run` with the dedupe key `nightly:<dot id>:<slot ISO>`; its run has `kind: "nightly_run"`, `stage: "regression"`, and a trigger of source `schedule` with `nightly: { slot, lateMs }`. See [SETUP.md](SETUP.md#nightly-test-run). `waitForPreviewSec` is a whole number from 0 to 3600: a PR check whose tests will run waits up to that many seconds for the deployment of its head to be reported, then tests the preview or the base URL, see [SETUP.md](SETUP.md#pr-tests-without-a-preview). `testRepoOnPr` and `testRepoOnMerge` are `true`, `false` or `null` (the default, on): whether the dot runs its Tests repo on app PRs and on merges, see [SETUP.md](SETUP.md#tests-repo); any other value is a 400. A repo with `role: "test"` takes `test: { framework, dir?, ref?, command?, setup?, baseUrlEnv?, passEnv?, smokeGrep?, label?, areas?, on? }` (fields in [SANDBOX.md](SANDBOX.md#tests-repo)); the routes answer 400 for a command with a shell operator, a `dir` outside the checkout, a `ref` that is not `default`, `match_branch` or `{ fixed }`, a `passEnv` name that does not start with `LOCALDOST_TEST_`, a `baseUrlEnv` name that looks like a credential, and an `areas` grep text that is not a valid regular expression. The report of a run that ran a Tests repo carries `testRepos: [{ repo, name, label?, ref, refRule, sha, note?, selection, baseUrl?, passed, failed, flaky, skipped, notRun?, notRunOnPurpose? }]`, and the file of each of its cases is `owner/name:path`. `waitForDeploySec` (a whole number from 0 to 3600; `0` and `null` are off) and `deployEnvironment` (one line of up to 100 characters, `null` clears it) make a merge run wait for a successful deploy of the merge commit to that GitHub environment, see [SETUP.md](SETUP.md#waiting-for-the-deploy); a wait above 0 needs an environment, once the save is applied, or the answer is a 400. Both are stored as `null` when off, and an editor who changes either gets a 403 with the code `runner_admin_only` and the error "Ask your localdost admin to change the deploy wait.", as for the runner settings. An app repo takes its own `deployEnvironment` and `waitForDeploySec` in `repos` (KAT-395, role `app` only, `repo` carries those of the first app repo): a field left out uses the dot's, `waitForDeploySec: 0` stops the wait for that repo only, and `null` or an empty `deployEnvironment` puts a field back on the dot's value. The routes answer 400 for seconds outside 0 to 3600, a name that is not text of up to 100 characters on one line, the fields on a test or docs repo, and a repo that waits with no environment of its own or the dot's. They are the admin's like the dot's two fields: an editor who changes one gets the same 403, with `fields` such as `repos[acme/shop].deployEnvironment`. A body with only `repo` that leaves the two fields out keeps those of the first app repo. All the deployments of one commit in the environment are one set: the merge is deployed when every one succeeded, and a deployment that ended in `failure` or `error` ends the wait with no test run, no verdict and no defect (the held run is `cancelled`, `cancelledBy: "the failed deploy"`, with the step `The QA deploy of this merge failed, so the tests did not run.`; the job is `done` with `deployWait.outcome: "failed"`). The tests of a merge whose deployment gave an `environment_url` run against it, kept as `deployWait.url` on the job; a Base URL with a path keeps that path in it (a deployment of the bare site gives `https://web.qa.example.com/app`, not `https://web.qa.example.com`). A run held for the deploy has `status: "interrupted"`, `interruptReason: "deploy_wait"`, and `deployWait: { environment, sha, since, until }`. `prTestTarget` is `base`, `preview-only`, or `none` (default `base`): what a PR check tests against when no preview of the PR is known, see [SETUP.md](SETUP.md#pr-tests-without-a-preview); any other value is a 400. `shadowWeekDays` is save-only: a whole number from 0 to 30 that holds `pr_comment` and `check_run` at `ask` for that many days, and the dot stores `shadowWeek: { until, kinds, saved }`; `0` on a `PATCH` ends the week now, and a `PATCH` of `rules` for a held kind drops that kind from the week.
+- `Watch.runner.copyFiles?: string[]`: relative file paths of the working folder that are copied into the worktree of a run before setup (KAT-293). At most 20; saved trimmed and without repeats. `POST /api/dots` and `PATCH /api/dots/:id` answer 400 for an absolute path, `..`, a path in `.git`, a folder, or a value that is not a list of strings. `TestReport.hint` is a sentence for a person when a worktree run did not pass and untracked dotfiles were left out; it holds no file name. `TestReport.hintFiles` lists up to 5 of those names and is shown on the run page only. A `.git` path is refused in any letter case. See [SANDBOX.md](SANDBOX.md#copy-files).
+- `Watch.tracker.labels.require?: string[]` (GitHub tracker, KAT-353): an issue is reviewed only when it carries one of these labels, in any case; the first one also goes on the defects the dot files. At most 20 labels of 50 characters, saved trimmed and without repeats; an empty list drops the key. `POST /api/dots` and `PATCH /api/dots/:id` answer 400 for a value that is not a list of label names. A GitHub tracker whose `repos` is set files every defect in the first repo, unless the bug was found in another repo the tracker names, and the draft's `meta.project` says which. With `labels.require`, the draft's `meta.labels` also holds the defect label and `meta.issueType` the defect type. See [TRACKERS.md](TRACKERS.md#github-issues).
+- `Watch.testBranches?: string[]`: branches besides the default branch whose merges and pushes run post-merge tests (KAT-292). Plain branch names, at most 20, trimmed and without repeats on save; `[]` or unset means the default branch only. `POST /api/dots` and `PATCH /api/dots/:id` answer 400 for a name with a `refs/` prefix, a wildcard, `..`, or anything else that is not a plain branch name. See [SANDBOX.md](SANDBOX.md#test-branches).
+- `Watch.pollGithub?: boolean`: poll GitHub for this dot (KAT-352). `POST /api/dots` sets it to true when the server has no webhook route and the body names none; both routes answer 400 for a value that is not true or false. `GET /api/dots/:id` and `GET /api/dots` return `listening` (`'webhooks' | 'polling' | 'none'`), `pollSec` when polling, and `listeningMissing` when `none`, see [GITHUB.md](GITHUB.md#polling).
+- `GET /api/dots/:id` and `GET /api/dots` return `repos[]` with `owner`, `name`, `defaultBranch`, `scan`, `intake`, and `lastEventAt` per repo. A dot saved before repo sets shows its `repo` as one app entry.
+- GitHub events match a dot when the event repo is in its set. App repos get `pr_check`, `post_merge`, and `ci_failure`; a test repo gets `ci_failure` only, and a docs repo no job, until the test repo and scan jobs exist. The test repos of a dot run inside the `pr_check` and `post_merge` jobs of its app repos, after the app repo's own tests. Each repo is polled once, whatever the number of dots that hold it.
+- `GET /api/repos` lists workspace repos with their scan state and the dots that use each. `GET /api/repos/options?q=` lists repos the GitHub connection can see, with `added`. `POST /api/repos` `{ repos: ['owner/name'] }` adds repos after the same check (201, or 207 with per-repo `results` carrying `code` 400 or 502). `DELETE /api/repos/:owner/:name` removes one (409 with `dots` while a dot holds it). `POST /api/repos/:owner/:name/scan` with `{ full?: boolean }` queues a `repo_scan` job and answers 202 with `{ repo, scan, queued, jobId?, dot, full? }`: a dot that watches the repo owns the job, and with none the job runs without a dot. `full: true` rescans even when the stored profile is at the same commit. `queued: false` means a scan of the repo was already queued in the last 10 minutes. The repo's `scan.state` follows the job: `queued`, `scanning`, then `ready` (with `sha`, `at`, `mode`) or `error` (with `error`); the repo live event carries each change. The Setup page's GitHub repo picker reads and writes the same list, with the same check; a repo it cannot read drops out of the pick.
+- `GET /api/repos/:owner/:name/profile` returns what the newest scan found, in a short form: `{ repo, sha, scannedAt, summary, apps, routeCount, testFrameworks, specCount, smokeTag? }`. 404 until a scan of the repo has finished. In demo mode, `demo/shop-web` is scanned from `demo/sample-app` at the fixed sha `demo`, with no GitHub.
+- `POST /api/dots/:id/review` and `GET /api/dots/:id/pulls` take an optional `repo` (`owner/name`, an app repo of the dot). Unset: the first app repo.
+
+## Onboarding
+
+The first-run flow (`#/welcome`, KAT-257) saves its progress in the settings store, so a reload or another browser resumes at the same step.
+
+- `GET /api/onboarding` returns `{ progress, firstRun, dots, demo, sandbox, server, demoRepo? }`. `progress` is null until the flow opens. `firstRun` is true while the flow is open: no dot exists and the flow is neither `done` nor `dismissed`, or the progress is `active` (a reload after Create dot lands back in the flow). The app then opens `#/welcome` instead of the Dots list, and shows the Getting started link. `sandbox` is true under `LOCALDOST_SANDBOX=1`. `server` is `{ token, publicUrl, webhookSecret, webhookRoute, webhookSeen, githubMode, delivery, pollEverySec, remote }`: whether `LOCALDOST_TOKEN` is set, the public URL as an origin only (or null), whether the GitHub webhook secret is set, `webhookRoute` (an https public URL and the secret, so GitHub can send webhooks here), `webhookSeen` (`{ at, event }` of the last signed GitHub delivery, or null when none arrived in the last 7 days), `githubMode` (`app`, `pat`, or `demo`), `delivery` (`webhooks` only when `webhookRoute` is true and `webhookSeen` is set, else `polling`), the poll interval, and whether the caller is off the server's machine.
+- `PUT /api/onboarding` replaces the progress: `{ status, step, steps, demo?, mode?, repos?, repoSetup?, tracker?, githubIssues?, tests?, testsByRepo?, slack?, rules?, dot?, run?, checklistHidden?, startedAt?, finishedAt? }`. `status` is `new`, `active`, `done`, or `dismissed`. `step` and the keys of `steps` are `welcome`, `delivery`, `model`, `github`, `repo`, `tracker`, `tests`, `slack`, `rules`, `dot`, `value`, and each `steps` value is `done` or `skipped`. `mode` is `team` or `laptop`. `repoSetup` maps a lower-case `owner/name` to `{ role: 'app' | 'tests' | 'issues', prScope?: { authors?, skipDrafts?, skipBots? } }`. `githubIssues` is `{ repo, types, labels, milestone? }`, `testsByRepo` maps a repo to `{ setup?, command?, baseUrl?, tried? }`, `slack` is `{ channel?: { id, name }, approvers? }` with Slack ids, and `rules` is `{ shadowWeek }`. An unknown field or a wrong type is a 400 with the reason.
+- `DELETE /api/onboarding` clears the progress.
+- `POST /api/onboarding/github-check` takes `{ repos }` (up to 20 `owner/name`) and answers `{ ok, message, repos: [{ repo, ok, message, issues: 'ok' | 'off' | 'denied' | null, sso? }] }`. It reads each repo and its issues endpoint with the live GitHub connection. `issues: 'off'` means the repo has Issues turned off, which is a note, not a failure. `sso` is set, with the authorization `url` when GitHub sends one, when the token needs SAML SSO. 400 for a bad body, 409 when GitHub is not connected.
+- `POST /api/onboarding/issue-count` takes `{ repo, types?, labels?, milestone? }` and answers `{ repo, count, capped, milestoneMissing? }`: the open issues of the repo that carry one of the labels (the rule of `tracker.labels.require`), sit in the milestone, and fall in scope by type (a typed issue by its type, an untyped one by its labels). It reads at most 500 and sets `capped` when more exist. 400 for a bad body, 403 for SSO or an App that is not installed, 404 for a repo it cannot see, 409 for Issues turned off or GitHub not connected.
+- In demo mode with no GitHub connection, `GET /api/dots/suggest?repo=demo/shop-web` returns a suggestion for the sample shop with `runner: { mode: 'demo' }`.
+
+## Review on demand
+
+A person can ask a dot to review a change now, without waiting for the poller or a webhook.
+- `POST /api/dots/:id/review` takes exactly one of `{ pr }`, `{ sha }`, or `{ base, head }`. An open PR queues `pr_check` (sticky comment and check on the PR). A merged PR queues `post_merge` on its merge commit. A sha queues `post_merge` against its first parent, and `{ base, head }` (shas or branch names) against `base`. The request builds the same trigger the webhook path builds, so the job, the flow, and the rules gate are the same. Returns 202 `{ ok, duplicate, jobId, jobKind, title, head, runId? }`. When the same review is already queued or running (an earlier request or the poller's), `duplicate` is true and `jobId` is that job. The same review means the same PR and head for `pr_check`, and the same base and head for `post_merge`, so two ranges that end at one commit both run. A finished review does not block a new one. 400 for a bad body, 404 for an unknown dot, PR, or commit, 409 for a paused, archived, or repo-less dot, a PR closed without a merge, or an empty range, 502 when GitHub fails.
+- `GET /api/dots/:id/pulls?limit=20` lists recent open and merged PRs, newest first: `{ number, title, state: 'open'|'merged', headSha, mergeSha?, author?, url?, updatedAt? }[]`. In demo mode (no GitHub credentials) the list and diffs come from `demo/payloads` for the demo repo only.
+- The run's trigger carries `requestedBy: 'user' | 'chat'`, and its first step is "Review requested".
+- `GET /api/dots/:id/model-usage` (KAT-362) answers `{ cap, today, week, stages, todayFrom, weekFrom }`: model calls and tokens (`calls`, `inputTokens`, `outputTokens`, `tokenCalls`) today and over the last 7 local days, per stage (`stage`, `label`), and `cap` (`{ cap, used, reached, resetsAt }`, or `null` when the dot has none). The dot view carries `modelCap` with the same `cap` while a cap is set, and `PATCH /api/dots/:id` takes `dailyModelCap` (a whole number from 1 to 100000, `0` or `null` for none). See [Daily model cap](SETUP.md#daily-model-cap).
+- `POST /api/dots/:id/review` also takes `post: false` with a PR, a sha, or a range: **review without posting**. The event carries `outboxOnly`, and the PR comment and the check run of that review wait in the Inbox as drafts, whatever the dot's rules say. A rule that is already stricter than `act` stays as it is. A review of the same change that is queued or running and will post is not reused: the answer is 409. `post` must be a boolean.
+- `POST /api/dots/:id/review` also takes `{ ticket }`: a Jira browse URL, a Linear issue URL, a GitHub issue URL, `owner/name#12`, or a key such as `TAD-3` (the dot's tracker reads a bare key, and `#12` on a dot with one GitHub Issues repo). It reads the ticket through the connected tracker and queues `ticket_review` with `requestedBy: 'user'`. Returns 202 `{ ok, duplicate, jobId, jobKind: 'ticket_review', title, ticket: { key, tracker, url }, runId? }`. 400 for a bad body or `ticket` with another target, 404 for a ticket the account cannot see, 409 when the tracker is not connected, the link is on another Jira site or a repo the dot does not watch, the GitHub link is a pull request, or the dot is paused, 502 when the tracker fails.
+- Chat tools `get_ticket { dotId?, ticket }` and `review_ticket { dotId?, ticket }` take the same values. `review_ticket` emits a `run` event (the inline run card), waits up to `LOCALDOST_CHAT_REVIEW_WAIT_SEC` seconds (default 150) for the review, then emits an `approval` event for the comment draft when the rules hold it. `pending_approvals { dotId?, limit? }` lists pending approvals, oldest first, with the wait time (`list_approvals` is the old name and still works). Three more read-only lookups answer "what is the ongoing work": `open_prs { dotId?, limit? }` (open pull requests from GitHub for the dot's repo, or for every dot's repo), `runs_in_progress { dotId? }` (running runs and queued jobs), and `recent_defects { dotId?, sinceLastMerge?, sinceHours?, limit? }` (runs that found failing tests, a product failure, or a high risk, with the failing tests and the suspected cause). `list_runs`, `runs_in_progress`, `open_prs`, `pending_approvals`, `recent_defects`, `probe_status`, `get_memory`, and `list_tickets_reviewed` each answer with a block (the rows, built on the server from the tool result) and take `context?: boolean`: `true` marks a lookup the model makes only to choose its next step, and the chat shows no block for it. A call (`channel: 'call'`) gets no block. See [CHAT-UI.md](CHAT-UI.md#blocks-from-lookup-tools).
+- Chat tools `test_results { dotId?, sinceDays?, branch?, status?, file?, kind?, splitAt? }` and `compose_view { title?, datasets?, vars?, root }` (KAT-366). `test_results` answers the model with the columns, a count, and five rows, and holds every row (at most 2,000) for a view; each lookup result of a turn carries a `resultId`. `compose_view` checks the spec, binds it to those results, and streams a `view` block (see [CHAT-UI.md](CHAT-UI.md#composed-views)). Both only read.
+- On the Anthropic backend, chat reads ticket and PR links and keys in the message and runs `review_ticket`, `get_ticket`, or `review_pr` before the model. The Claude CLI and Codex CLI backends call the tools themselves through a local MCP server and run nothing first, so a message that needs no lookup shows no tool line. A turn runs each tool at most once per input; a repeat returns the first result and shows no second line. A line that refuses or conditions a review ("do not review TAD-3") hides `review_ticket` and `review_pr` for that turn on every backend. `npm run eval:chat` checks this on each backend (docs/CHAT-EVAL.md).
+- Chat tool `review_pr` takes `{ dotId?, pr?, repo?, sha?, base?, head? }` and calls the same function. `repo` comes from a PR link and must be the dot's repo. The dot page has a "Review a PR" action with a PR picker and a commit field.
+
+## Live test runs
+
+The runner captures a screenshot after each Playwright step (via a reporter that writes step events) and keeps trace.zip, video, and screenshots under `data/artifacts/<runId>/`.
+- `LiveEvent` adds `{ type: 'run_step'; runId: string; step: RunStep }`, `{ type: 'run_frame'; runId: string; frame: { at: string; test: string; step: string; image: string /* artifact URL */ } }`, and `{ type: 'run_log'; runId: string; line: string }`.
+- `LiveEvent` also has `{ type: 'picked_up'; watchId; jobId; kind: 'pr_check' | 'post_merge'; title; ahead: number; at; pr?: number; sha?: string; url?: string }`. It goes out when a `pr_check` or `post_merge` job is enqueued, before its run exists. `ahead` counts the jobs that start first. The same job keeps its `localdost` check current on GitHub, see [GITHUB.md](GITHUB.md#check-status).
+- `GET /api/runs/:id/artifacts` returns `{ name, kind: 'screenshot'|'trace'|'video'|'log'|'report', url, size }[]`.
+- `GET /artifacts/<runId>/<file>` serves files (auth as `/api`) and answers `Range: bytes=` requests with `206`, so a video can seek.
+- A run's `report.cases[].evidence` is `{ screenshots: { name, step? }[]; video?: string; trace?: string }`, the artifact names of that test. `RunStep.test` names the Playwright test a step belongs to.
+- `POST /api/runs/:id/rerun` and `POST /api/runs/:id/cancel`.
+- `GET /api/runs/:id` adds `evidencePack: boolean` (KAT-392): true when the run names an issue and some test left a screenshot or a video. The run page shows the link to [the evidence pack](#evidence-pack-kat-392) only then.
+- `POST /api/runs/:id/defect {file, title}` drafts a defect for one test that failed or was flaky in the run, through the same draft path as the run flows (`draftDefects`): an earlier draft or filed issue for the same bug is linked instead, and the draft passes the rules gate, so under the default ask rule it waits in the Inbox. Returns 202 `{ ok, state: 'drafted', approvalId? }`, or 200 with `state` `filed` (and `url`) or `rejected`. 400 without a title, 404 for an unknown run or a test that did not fail in it, 422 when the dot has no tracker or repo to file in (KAT-247).
+- Run `status` adds `'cancelled'`. Runs hold a lease. A run whose lease expires becomes `interrupted` with a Retry action.
+
+## Disk space
+
+`GET /api/disk` returns how much room the data folder has. It reads memory and one queue count, so it still answers when the disk is full.
+
+```ts
+interface DiskView {
+  freeBytes: number | null;     // free bytes where the data folder lives; null when unreadable
+  thresholdBytes: number;       // LOCALDOST_DISK_MIN_FREE_GB in bytes; 0 means the check is off
+  low: boolean;                 // freeBytes is under thresholdBytes
+  writeFailed: boolean;         // a write failed with "database or disk is full" in the last minute
+  lastWriteError?: { at: string; message: string };
+  paused: boolean;              // low or writeFailed: new test runs wait
+  checkedAt: string | null;
+  waitingJobs: number;          // queued pr_check, post_merge, ci_failure, rerun, repo_scan, and nightly_run jobs
+}
+```
+
+`LiveEvent` adds `{ type: 'disk'; disk: DiskStatus }` (the same shape without `waitingJobs`). It goes out when the status changes and on every check while `paused` is true. A write that finds the disk full answers `507` with `{ error, code: 'disk_full' }`. Setup: [SETUP.md](SETUP.md#disk-space).
+
+## Traceability
+
+- `GET /api/links?ref=<ref>` or `?dotId=<id>` lists links, see [TRACKERS.md](TRACKERS.md#github-issues).
+- `GET /api/cards?ref=<link, key, or owner/name#N>&kind=<github_pr|github_issue|jira|linear>&dotId=<id>` returns `{ card: ObjectCard }`, a GitHub PR, GitHub issue, Jira ticket, or Linear ticket built from the dot's connections (KAT-136, [CHAT-UI.md](CHAT-UI.md#object-cards)). `dotId` is optional: the dot that watches the repo or lists the tracker key answers. 400 for text that names no object, 404 for an unknown dot or an object nobody has, 409 when the dot does not watch the repo or the tracker is not connected, 502 when the tracker or GitHub does not answer.
+- `GET /api/cards/status-options?ref=&kind=&dotId=` returns `{ current, options: { id, label, kind }[] }`: the statuses a ticket can move to now (Jira transitions, a Linear team's states, or close and reopen for a GitHub issue). 400 for a PR.
+- `POST /api/cards/comment { ref, kind, dotId?, text }` and `POST /api/cards/status { ref, kind, dotId?, optionId }` send a `pr_comment` (plain) or `ticket_comment` (append) action, or a `ticket_status` action, through the gate and answer `{ result, runId, approvalId?, note? }` (`result` is `executed`, `pending_approval`, `blocked`, or `handed_off`). Sandbox mode and an archived dot refuse them. A PR comment for a repo the dot does not watch answers 409, like the card read. `POST /api/approvals/:id` answers 400 to an approve with an `edit` for a `ticket_status` draft.
+- `GET /api/tickets/status?dotId=<id>` returns `{ statuses: TicketTestStatus[] }` for every issue or ticket the dot tracks and caches each in `issue_state.testStatus`. With `&ref=<owner/name#N or ticket key>` it returns `{ status: TicketTestStatus }` for one. 400 without `dotId`, 404 for an unknown dot.
+
+- `GET /api/dots/:id/traceability?milestone=&status=&repo=` returns `{ rows: TraceRow[], milestones, repos, readiness }` for the requirements of a dot. `status` takes a word (`Not tested`) or a code (`not_tested`); an unknown value is a 400. `milestones` and `repos` ignore the filters, so a client can fill its controls. `readiness` counts the rows that pass the milestone and repo filters, and its `summary` is plain QA words, for example `14 of 18 requirements passing, 2 failing, 1 not tested, 1 out of date`.
+- `GET /api/dots/:id/traceability.csv` takes the same filters and returns `text/csv` as an attachment. RFC 4180 quoting, CRLF rows, and a leading single quote on cells that start with `=`, `+`, `-`, or `@`.
+- `GET /api/dots/:id/traceability/issue?ref=` returns the drawer detail of one requirement: summary, acceptance criteria, PRs with the last verdict, tests, defects, and the latest QA review comment. 404 when the ref is not a requirement of the dot.
+- `GET /api/dots/:id/trace/map` returns `{ tree: TraceMapNode, stats, milestones, observed }`: the app under test as the dot's recent runs saw it (app, section, page, state), built from each run's `observations.jsonl`, with status (`covered`, `partly`, `failing`, `needs_tests`, `not_run`) and counts per node. Routes the code, a requirement, or a probe names that no run visited are Needs tests nodes, or Not run yet when a spec covers them; a visited page whose source a merge changed since is Not run yet. A section with one page is that page. `GET /api/dots/:id/trace/map/:nodeId` returns one node's requirements, tests, defects, screenshots (one per test per route, the latest, with its result; up to 12), the coverage `gaps` below it, the source files and API routes from the repo scan (`code`), and skill markdown; 404 for a node not in the tree. `GET /api/dots/:id/trace/map/skill.md` returns the whole map as one agent skill. Section, page and state nodes carry `dots: { id, name, avatar, running?: { runId, label } }[]`, the dots whose runs visited them. `POST /api/dots/:id/trace/map/:nodeId/run` queues a rerun of the spec files that cover the node (409 when none does). Requirement rows with no title get it from the dot's tracker, cached (KAT-190). `GET /api/trace/map`, `GET /api/trace/map/:nodeId`, `GET /api/trace/map/skill.md`, and `POST /api/trace/map/:nodeId/run` are the same for every live dot on one canvas. Rules: [TRACE-MAP.md](TRACE-MAP.md).
+- `GET /api/dots/:id/readiness?milestone=` returns `{ milestone, readiness }`. `POST /api/dots/:id/readiness/report` with `{ milestone }` saves or updates the `readiness` report page of that milestone and returns `{ page, created }`.
+
+```ts
+interface TraceRow {
+  ref: string; // lower case: owner/name#12, shop-12
+  key: string; // as the tracker writes it
+  title: string;
+  type: string; // Feature, Story, or Requirement when a label made it one
+  milestone: string;
+  repo: string;
+  prs: { ref: string; number: number; repo: string; url: string; lastVerdict: VerdictOutcome | null }[];
+  tests: { passed: number; total: number };
+  defects: { open: number; total: number };
+  status: string; // Not tested, Passing, Failing, Partly tested, Out of date
+  statusCode: 'not_tested' | 'passing' | 'failing' | 'partly_tested' | 'out_of_date';
+}
+```
+
+```ts
+interface TicketTestStatus {
+  ref: string; // lower case
+  status: 'not_tested' | 'passing' | 'failing' | 'partly_tested' | 'out_of_date';
+  label: string; // Not tested, Passing, Failing, Partly tested, Out of date
+  prs: { ref: string; result: 'passed' | 'failed' | 'none'; outdated: boolean; runId?: string; items: { total: number; notRun: number; failed: number } }[];
+  specs: { path: string; result: 'passed' | 'failed' | 'not_run' }[];
+  defects: { ref: string; state: 'open' | 'closed' | 'unknown' }[];
+  reasons: string[];
+  computedAt: string;
+}
+```
+
+`ActionKind` gains `issue_create` (default rule `ask`): a defect drafted from a test that failed on every retry. Its `meta` holds `tracker`, `project`, `sig`, `labels`, `issueType`, `milestone`, `relates`, and after approval `filedUrl` and `filedKey`. `file_defect` files through the same creator. A `ticket_comment` with `meta.append: true` adds a plain comment on a GitHub issue, and one with `meta.statusLabel` sets a `qa: passing` or `qa: failing` label.
+
+`ActionKind` gains `ticket_status` (default rule `ask`, KAT-136): a status a person picked on a ticket card. Its `target` is `jira:KEY`, `linear:KEY`, or `github:owner/name#N`, and its `meta` holds `tracker`, `key`, `ticketId`, `optionId` (a Jira transition id, a Linear workflow state id, or `open`, `closed`, `not_planned` for a GitHub issue), `optionLabel`, and `from`. It passes the same destination check as a comment. A `pr_comment` with `meta.plain: true` is a new comment on the PR, written by a person on a card: it posts with `addComment`, never edits the sticky QA report, and does not replace a pending report draft for the same PR.
+
+## Test cases
+
+The test case store of a dot (KAT-163, [STAGES.md](STAGES.md) section 4). A case has a key such as `TC-12`, unique per dot and never reused, steps with expected results, a kind (`manual`, `playwright`, `aivision`), requirement refs in `LinkRecord` form, a spec path when it is automated, a priority (`must`, `should`, `could`), a status (`draft`, `ready`, `retired`), and a source (`designer`, `user`, `imported`). Results are append only.
+
+- `GET /api/dots/:id/cases?status=&kind=&requirement=&q=` returns `{ cases: TestCaseView[], requirements, counts }`. No `status` means draft and ready; `status=all` adds retired cases. `requirements` (every ref any case names, with its source, title, and link) and `counts` (per status) ignore the filters. An unknown status or kind is a 400.
+- `GET /api/dots/:id/cases/:caseId` takes the case id or its key and returns the case with `results`, newest first. 404 for a case of another dot.
+- `POST /api/dots/:id/cases` creates a case (source `user` unless the body names one) and returns 201. `PATCH /api/dots/:id/cases/:caseId` edits one; `specPath: null` clears the spec file. `POST /api/dots/:id/cases/:caseId/retire` retires one; its results stay. A bad field is a 400 in plain words: a manual case with a spec file, a ready case with no steps, a ref that is not a key, a spec path outside the repo.
+- `GET /api/cases/:id/results` lists results, newest first. `POST /api/cases/:id/results` with `{ result, notes?, runId?, evidence? }` adds a manual result (`passed`, `failed`, `skipped`, `blocked`). `runId` must be a run of the same dot.
+- `GET /api/dots/:id/folders` returns `{ folders, unfiled }` with `caseCount` on each folder. The ticket folder of a GitHub issue also has `repo` (KAT-398): the issue's repo as `owner/name` in lower case, which the designer matches with the issue number to find the folder again after a person moved it, so `#12` of one repo never takes the folder of `#12` in another. It is read only: `POST` and `PATCH` ignore a `repo` in the body, a rename or a move keeps it, and a folder of a Jira or Linear ticket has none. The boot migration fills `repo` on older ticket folders from the keys of their cases (`owner/name#12`), and leaves a folder with no such case, or with cases of two repos, without one.
+- `GET /api/dots/:id/cases/export.zip` downloads the draft and ready cases as `tests/cases/<key>.md` files: YAML front matter, then the steps. Nothing is committed.
+
+A run that saves a test report writes one result per case whose `specPath` names a file the run executed (`source: run`). The match ignores the testDir prefix, so `e2e/coupon.spec.ts` on the case matches `coupon.spec.ts` in the Playwright report. Any failed test fails the case; a test that passed on a retry passes it with a note. Screenshots, video, and trace of those tests become the result's `evidence`. A second save of the same run (the retry pass) replaces that row. Retired cases get no new results.
+
+Each ticket review that writes a review also designs test cases (KAT-164, the test designer in [STAGES.md](STAGES.md) section 3). One model call turns the review's risks, test ideas, and open questions into manual cases, each with steps and expected results, a priority, the ticket as its only requirement ref, status `draft`, and source `designer`. A case that has the same normalized title or the same normalized steps as a case the dot already has for that ticket, in any status, is not stored again. The mock backend designs from the review with a fixed rule instead of a model call. The run gets `designed: { requirement, added, keys, existing, dropped, error? }`. The run page and the chat answer of `review_ticket` show "N test cases designed" with a link to `#/cases?dot=<id>&req=<ticket>`. A person marks each draft ready on the Test cases page.
+
+Each ticket review also checks the tests the dot already has (KAT-304, [STAGES.md](STAGES.md) section 3.8). The run gets `impact: { ticket, checked, valid, update, obsolete, specs, leftOut?, error? }`. A check looks at the best 12 cases and 6 specs. `leftOut: { cases, specs }` says how many more matched and were dropped; it is absent when nothing was.
+
+- `GET /api/dots/:id/impact?ticket=&state=&case=` returns `{ items: ImpactItem[], open, leftOut? }`. With `ticket`, `leftOut` is the count from the latest check of that ticket (absent when nothing was left out). `ticket` is a key such as `SHOP-12` (a bad one is a 400). `state=open` keeps the rows a person still has to decide; `state=all` is the default. Each item has the verdict (`valid`, `update`, `obsolete`), `confidence`, the `ticketLine` that causes it, a plain `note`, the `changes` (new steps) for an update, the ticket as a titled `requirement`, the case's `currentSteps`, and `specUrl` for a spec. Rows that need a decision come first.
+- `POST /api/dots/:id/impact/:impactId/accept` writes the draft as the case's next version (the old version stays in its history), or marks a spec as updated. `POST .../reject` rejects the draft or dismisses the spec row. Both answer the ticket's list. A row that was already decided is a 409. A case the ticket makes obsolete is decided in the Inbox: its `case_retire` draft always asks, whatever the dot's rules say, and the two routes answer 409 for it. A paired phone may call both routes.
+- `GET /api/dots/:id/cases` and `GET /api/dots/:id/cases/:caseId` add `needsReview: { impactId, ticket, verdict }` to a case with a draft that waits. Run items in `GET /api/dots/:id/test-runs/:runId` carry the same field.
+
+## True Platform sync
+
+A dot copies its test cases, automated runs, and manual results into one True Platform project (KAT-406, setup and rules in [SETUP.md](SETUP.md#true-platform)). The setting is the `trueSync` field of the dot, saved with `POST` or `PATCH /api/dots/:id`.
+
+`Watch.trueSync?: { enabled, tenantUrl, projectId, repositoryId?, folderPath?, ownerUuid?, blocked? }`. A request sends only `enabled`, `tenantUrl` (an https address on a `katalon.io` host, saved as its origin), and `projectId` (a whole number, a numeric string is taken). Switching on needs both. Anything else a request sends under `trueSync` is ignored: `repositoryId`, `folderPath`, `ownerUuid`, and `blocked` (`{ reason: 'key_missing' | 'key_rejected' | 'project_not_found' | 'unreachable', since }`) are the server's. A save that moves the dot to another address or project drops what it sent, since the True ids belong to the old project, and queues the cases for the new one. A save that switches the dot on queues every draft and ready case, and nothing for runs and test runs that came before.
+
+- A bad address is a 400 with `Use your True Platform address, for example https://your-team.katalon.io.`; a switch without a project is a 400.
+- Only the admin token, or a loopback browser on a server with no token, may change `enabled`, `tenantUrl`, or `projectId`. A paired editor who sends a different value gets 403 `{ error: 'Ask your localdost admin.', code: 'true_admin', fields: ['trueSync.projectId'] }`; the same values are fine. A member may only pause (see [Dots](#dots-watch-additions)).
+- `GET /api/dots/:id` and the list add `trueKey: { set: boolean, source?: 'env' | 'file', warning?: string }`. The key is never in an answer.
+
+Routes:
+
+- `GET /api/dots/:id/true` answers the setting for the page: `{ enabled, tenantUrl, projectId, folderPath, key, blocked?, waiting, notSent, lastSentAt?, chatServer?, sandbox, items }`. `waiting` counts the items still queued, `notSent` those that gave up, `chatServer` is the URL of the dot's Katalon True Platform connection when it has one, and `items` lists up to 50 that gave up or wait with an error (`id, kind, refId, status, attempts, error, code, nextAt`).
+- `GET /api/dots/:id/true/line?kind=run|test_run|case&id=` answers the status line of a dot run, a manual test run, or a case (a case by id or key). With the switch off, or nothing to say yet, it answers `{ on, line: null }`. Otherwise `{ on: true, code, text, error?, nextAt?, since?, projectId?, url?, urlLabel?, itemId?, canResend?, details?, earlierRounds?, notes?, trueName? }`. `code` is one of `sent`, `sending`, `retry`, `unreachable`, `key_missing`, `key_rejected`, `project_not_found`, `no_tests`, `gave_up_24h`, `dependency`, `other_user`, `refused`, `sandbox`. `text` is the sentence with the time in the server's clock; the app draws its own from the same words (`src/true/line.ts`).
+- `POST /api/dots/:id/true/check` with an optional `{ tenantUrl, projectId }` (values the form has not saved) logs in and reads the key owner and the repository, then answers `{ ok: true, project }` or `{ ok: false, message }`. It is a POST so that a paired device, which may call every GET, cannot make the server call out: any paired device gets 403 `phone_blocked`. It answers 400 when no address and project are known, and `{ ok: false }` in sandbox mode or without a key.
+- `POST /api/dots/:id/true/resend` is **Send all again**: every item the dot gave up goes back in the queue in its original order, with a fresh 24 hours. Answers `{ requeued }`.
+- `POST /api/dots/:id/true/items/:itemId/resend` is **Send again** for one item that gave up, and for the items given up because of it. 404 for an item of another dot, 409 for one that is not waiting for a person. Both resend routes are open to a paired member.
+
+## Approvals
+
+`ApprovalRecord` gains `expiresAt` (default 24 h) and `executedAt`. Approving twice returns 409. An expired approval returns 410 and shows as expired.
+
+## Connections (MCP)
+
+```ts
+interface Connection { id: string; name: string; transport: 'stdio' | 'http'; command?: string; args?: string[]; url?: string; headersSecretRef?: string; enabled: boolean; tools: { name: string; description: string; readOnly: boolean; enabled: boolean }[]; status: 'connected' | 'error' | 'disabled'; error?: string; createdAt: string }
+```
+- `GET /api/connections`, `POST /api/connections`, `PATCH /api/connections/:id`, `DELETE /api/connections/:id`, `POST /api/connections/:id/refresh` (lists tools through `@modelcontextprotocol/sdk`).
+- Chat and flows can call enabled tools of connections attached to the dot. Read-only tools run directly. Any other tool goes through `gate()` as ActionKind `mcp_tool` (default rule `ask`), and the chat shows an inline approval card.
+- Secrets live in env vars referenced by name (`headersSecretRef`), never in the database.
+
+## Reports workspace
+
+```ts
+interface ReportPage { id: string; watchId?: string; parentId?: string; title: string; kind: 'test_plan' | 'readiness' | 'incident' | 'digest' | 'note'; markdown: string; revision: number; sourceRunId?: string; createdAt: string; updatedAt: string }
+```
+- `GET /api/reports?watchId=&q=`, `GET /api/reports/:id`, `POST /api/reports`, `PUT /api/reports/:id` with `{ markdown, title, revision }` (409 when `revision` is stale), `DELETE /api/reports/:id`.
+- `POST /api/runs/:id/save-report` creates a page from a run verdict. Digests save a page automatically.
+- `POST /api/chat` accepts `reportId` to scope the chat to a page. The dot may propose an edit, which arrives as an approval of kind `report_edit` with a markdown diff. A copy of the dot's Team notes (the `instructions` field, 8 words in a row or more) is cut from the page, the title and the note before the card shows the diff and again when the edit is saved, whatever the `report_edit` rule is (KAT-399). A copy that runs across a sentence end or a line break is cut with the sentences it touches and the rest of the page stays. When nothing but a copy is left, the tool answers `{ error }`, no approval is made, and the page is not changed.
+
+## Release notes (KAT-391)
+
+`GET /api/v2/release-notes?dot=&milestone=&format=` answers the release-note list: the note line of every merged PR the dots reviewed, grouped by milestone and then by the issue the PR names. It is read-only (no other method exists on the path), uses the same token as the rest of `/api`, and a paired device may call it. It reads stored rows and makes no model call and no tracker call. The page is `#/reports/release-notes` (Release notes in Reports): a table where the page is wide, a list where it is narrow.
+
+| Query | Meaning |
+|---|---|
+| `dot` | A dot id or its name (case does not matter). A Lead QA dot reads its members. Empty: every dot that is not archived. 404 `No dot named "<x>".` for an unknown dot. An archived dot is read only when named |
+| `milestone` | An exact milestone title, case does not matter. Empty: every milestone. A title with no note answers an empty list |
+| `format` | `json` (default) or `md`. Any other value is 400 |
+
+```ts
+interface ReleaseNotesList {
+  milestones: {                     // highest milestone name first (numbers compare as numbers), no milestone last
+    milestone: string | null;       // null: the issue has no milestone, or the PR names no issue
+    issues: {                       // by key, the group "no issue" last
+      ref: string | null;           // lower case: "owner/name#12" or the ticket key. null: the PR names no issue
+      key: string;                  // "KAT-12" or "owner/name#12". "" when ref is null
+      title: string;                // "" until a review or a tracker read gave it
+      url: string | null;
+      tracker: 'github' | 'jira' | 'linear' | null;
+      notes: {                      // newest merge first
+        note: string;               // one line of plain text
+        breaking: boolean;
+        audience: 'users' | 'admins' | 'developers';
+        testStatus: 'passed' | 'bug_found' | 'partly_tested' | 'not_tested';
+        testLabel: 'Passed' | 'Bug found' | 'Partly tested' | 'Not tested';
+        pr: { ref: string; number: number; repo: string; title: string; url: string; mergedAt: string };
+        alsoNames: { ref: string; key: string; url: string | null; tracker: 'github' | 'jira' | 'linear' | null }[];  // the other issues the PR names
+        dot: { id: string; name: string };
+        runId: string;              // the merge check the note came from
+      }[];
+    }[];
+  }[];
+  counts: { notes: number; breaking: number; passed: number; bugFound: number; partlyTested: number; notTested: number };  // the rows of milestones: each merged PR is one
+  cut: boolean;                     // true when a dot in scope has more PR and merge checks than the window reads: older merges may be missing
+  allMilestones: string[];          // every milestone that has a note for this dot filter, lowest first, for a picker
+  dots: { id: string; name: string }[];                       // the dots the filter can name
+  filter: { dot: { id: string; name: string } | null; milestone: string | null };
+  builtAt: string;
+}
+```
+
+How a note is built, all from rows the dots already hold:
+
+- **Which notes.** The note line comes from the newest finished after-merge check of each merged PR (`post_merge` run with a review), the same data as the daily digest's release notes (`releaseNoteSources` in `src/flows/digest.ts`). A change the review calls not user-visible, or one with no note line, has no note. The newest check of a PR decides.
+- **Audience.** The review's `end_users` is `users`, `admins` is `admins`, and `api_consumers` and `internal` are `developers`.
+- **Issues and milestone.** A note is listed once, under one issue: the issue its PR closes, else the first issue it names by a ticket key or a cross-reference (the same links as a ticket's test status). When a PR closes or names several, they are ordered by reference with the number read as a number (`acme/shop#2` before `acme/shop#10`), so the same PR is always listed under the same issue, whenever its links were recorded. The other issues the PR names are in `alsoNames` on the note, and the page and the Markdown show them as "Other issues". The issue's milestone and title come from the ticket catalog that Traceability reads, and from the cached tracker titles. A PR that names no issue is listed under "No issue named", and an issue with no milestone under "No milestone". The milestone filter keeps the notes whose deciding issue has that milestone, so the rows of a filtered list are still the notes `counts` counts.
+- **Test status.** The result of the PR's runs by the rule a ticket's test status uses (`prEvidence` in `src/flows/testStatus.ts`): `bug_found` when the latest run that ran the tests failed, `passed` when it passed, `partly_tested` when it passed but some What to test items of the review did not run, and `not_tested` when no run ran the tests, when the tests ran against the shared QA build, or when the result is for an older commit than the newest check.
+- **Four values.** A reader that knows three (`passed`, `bug_found`, `not_tested`) reads `partly_tested` as `passed` with a gap: the run passed and the review's What to test list has items that did not run. `counts.partlyTested` is the number of such notes, and `counts.passed` does not include them.
+- **How far back.** The newest 1000 PR and merge checks of each dot in scope. Digests, ticket reviews and site checks of the dot do not use up the window, so a busy dot keeps its merges. When a dot has more than 1000 such checks, `cut` is true, the page says "Only the newest checks of each dot are read, so older merges may be missing.", and the Markdown says the same in one line under the counts. The ticket test status keeps its own window of the newest 1000 runs of any kind.
+
+`?format=md` answers `text/markdown; charset=utf-8`: a title, the counts line, then `## <milestone>`, `### [<key>](<issue url>): <title>`, and one bullet per note with `**Breaking.**`, `For <audience>.`, the test label and a link to the PR. Every note, title and key is escaped, and a link is written only for an http or https address, since the text comes from PR bodies and tickets. A skill reads it with the token of the server:
+
+```
+curl -s -H "Authorization: Bearer $LOCALDOST_TOKEN" "$LOCALDOST_URL/api/v2/release-notes?milestone=2026.11&format=md"
+```
+
+## Evidence pack (KAT-392)
+
+`GET /api/v2/runs/:id/evidence-pack` answers the evidence of one run that names an issue. It is read-only, uses the same token as `/api`, makes no model call and no tracker call, and reuses the per-test evidence of KAT-222 (`report.cases[].evidence`). The page is `#/runs/:id/evidence` (the **Steps, screenshots and video** link on the run page): the issue, each test with its video and its steps, the verdict, and a **Copy JSON** link that puts this JSON on the clipboard. It fits a 390 px phone. 404 for an unknown run. 409 `This run names no issue, so it has no evidence pack.` for a run that names none.
+
+A run names an issue when it is a ticket review (the ticket), or when its PR names one: a closing keyword, a ticket key, or a cross-reference from the PR, the same links as the release-note list. The first issue is `issue`: the ticket of a ticket review, else an issue the PR closes, else one it mentions, in the same order as the release-note list, so a PR's pack and its note name the same issue. The rest are `moreIssues`.
+
+```ts
+interface EvidencePack {
+  run: { id: string; kind: JobKind; kindLabel: string; status: RunRecord['status']; dot: { id: string; name: string }; startedAt: string; finishedAt: string | null };
+  issue: { ref: string; key: string; title: string; url: string | null; tracker: 'github' | 'jira' | 'linear' | null; milestone: string | null };
+  moreIssues: PackIssue[];          // same shape as issue
+  pr: { ref: string; number: number; title: string; url: string } | null;
+  verdict: { outcome: VerdictOutcome; label: string; headline: string; summary: string; risk: 'low' | 'medium' | 'high' } | null;
+  tests: {                          // tests that ran (passed, failed, flaky, timed out), up to 50, skipped ones are only counted
+    title: string;                  // without the project prefix
+    status: 'passed' | 'failed' | 'flaky' | 'timedOut';
+    durationMs: number;
+    error: string | null;           // what went wrong in a line or two, scrubbed: the Expected and Received lines of a failed check, else the first line of the error. Only for a test that did not pass
+    errorDetails: string | null;    // the whole error text (up to 1200 characters, the call log included), scrubbed, when it says more than `error`. Otherwise null
+    steps: { n: number; step: string; screenshot: { name: string; url: string; size: number } | null; failed: boolean }[];
+    video: { name: string; url: string; size: number } | null;
+  }[];
+  counts: { tests: number; passed: number; failed: number; skipped: number; steps: number; screenshots: number; videos: number; shown: number; truncated: boolean };  // tests, passed, failed, skipped count the whole run; tests lists at most 50 (shown), truncated says it was cut; steps, screenshots, videos count the listed tests
+  links: { run: string; page: string; api: string };   // in-app and API paths
+  scrubbed: number;                 // how many values the scrub replaced with [redacted]
+  builtAt: string;
+}
+```
+
+- **Steps.** The steps are in the order they ran. A test that names its steps (`test.step`, kept for every test that ran in `case.namedSteps`) has one step per named block. The live session takes at most one frame per 500 ms, each labelled with the step that ended just before it, so a named block takes the frame labelled with its own name, and a block with no such frame takes the last frame taken before the next block's frame. The frames of the Playwright calls inside a block fold into it. A frame after the last block (the last screenshot of the test, which the runner labels `Test passed`, `Test failed` or `Test timed out`, and a report attachment `End of test`) follows as a step called `End of test`. A block with no screenshot stays in the list with `screenshot: null`. A test that names no steps has one step per screenshot, in the order taken, with the Playwright call in plain words (`Click the "Pay" button`, `Fill in the "Password" field`, `Open /cart`, `Check the text`); a call the pack cannot put in words keeps its label, scrubbed.
+- **Failed step.** For a failed or timed-out test, `failed` is true on one step: the `test.step` block that threw, else the last step before the `End of test` screenshot. It is false on every step of a test that passed, and on every step when the test left nothing to point at. The page shows it as "Failed here".
+- **Typed values.** Playwright titles a fill step with the value it typed (`Fill "<value>"`, also `Type`, `Insert`, and `Press "<key>"` for one key). The runner hides the value as `[redacted]` in the step list, the live frame, the log line and the label stored in the report, and the pack hides it again in every text it holds, so a password a test typed never reaches the JSON, the page or Copy JSON. The same goes for `fill("<value>")` in a call log or a code frame.
+- **Files.** A screenshot or a video is listed only when the run folder holds the file. `url` is `/artifacts/<runId>/<name>`: it needs the same token as the API, and it supports `Range` requests. The pack holds paths, never file bytes.
+- **Scrub.** Every text of the pack goes through `scrubText` (`src/evidence-pack.ts`): the token shapes of `redactCode` (GitHub, Anthropic, AWS, Slack and Google keys, JWTs, private keys, a password in a URL), the value of an `Authorization`, `Cookie` or `Set-Cookie` header, a Bearer or Basic credential, `document.cookie = ...`, a cookie object (`name` with `value`), a `name=value`, a `name: value` (a YAML, `.env` or log line) or a `"name": "value"` pair whose name says session, cookie, csrf, token, secret, password, auth, key or signature, the value a test typed, and any query value of 32 or more opaque characters. Each is replaced by `[redacted]` and counted in `scrubbed`. The trace, the test command, the output tail, the base URL and the run's trigger are not in the pack, since they can hold cookies and tokens. A screenshot or a video can still show what the page showed: the scrub reads text only.
+
+## Chat events
+
+SSE events on `/api/chat`: `delta {text}`, `tool {name, input}`, `tool_result {name, summary, error?}` (`error: true` when the call failed; `summary` then holds the reason), `approval {approval}` (inline card), `run {runId}` (inline TestRunCard), `block {block}` (an answer block, [CHAT-UI.md](CHAT-UI.md)), `reasoning {text}` (one step line of the summary the backend returned of its reasoning, plain text, KAT-374), `work {work}` (once the answer is final: `{ elapsedMs, steps, summary?, tools?, tokens? }`, where `tokens` sums the turn's `model_calls` rows and is left out when none knows its tokens; the stored assistant message keeps it as `work`), `view_node {id, at, node}` (one node of a composed view that is still streaming, [CHAT-UI.md](CHAT-UI.md#composed-views)), `view_drop {id}` (a view that streamed nodes could not be built after all: the client takes the block away), `done {text, replace?}`, `error {error}`. Every answer is rewritten so that each PR, issue, ticket, run, commit, and defect it names shows a short title with its link (`[Queued checks show at once (#30)](url)`; `<url|Queued checks show at once (#30)>` in Slack; plain `Queued checks show at once (#30)` for push and voice). Deltas stream as the model wrote them. When the rewrite changes the text, `done` carries the final text with `replace: true` and the client swaps it in. Titles come from the dot's GitHub data, the connected tracker, and the stored runs, with a 10 minute cache (`src/refs.ts`). A short sha (7 to 40 hex characters with a digit and a letter, or any hex after the word "commit") gets the first line of the commit message as its title. The chat shows the steps and the tool events in the Steps card, see [CHAT-UI.md](CHAT-UI.md#steps-card); tool results are not rewritten. A question about what failed gets the triage view instead of a model answer, see [CHAT-UI.md](CHAT-UI.md#triage). `GET /api/messages` returns stored `blocks` with each triage row's action state read again, and with the drafts, runs, ticket reviews, and notes of the lookup blocks read again.
+
+## Calls
+
+`POST /api/call/session` returns `{ mode: 'browser' | 'realtime', token?: string, model?: string }`. Realtime mode is used when `OPENAI_API_KEY` is set (ephemeral token for the OpenAI Realtime API). Otherwise the client uses Web Speech in and `speechSynthesis` out, with the same chat endpoint. `POST /api/call/receipt` stores `{ dotId, startedAt, endedAt, transcript[] }` as a message with kind `call_receipt`. An answer of the transcript may carry `work { elapsedMs, steps, tokens? }`, numbers only, for its folded Reasoning line.
+
+## Slack
+
+Socket Mode through `@slack/bolt` when `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` are set, so no public URL is needed. Allowlists: `SLACK_ALLOWED_TEAM`, `SLACK_ALLOWED_USERS` (comma list). A mention of the bot in a thread routes to the dot named in the message, or else to the dot whose `slackChannel` matches the channel. The bot replies in the thread. Outage and digest notices post to `slackChannel` when that is set, through `gate()` as ActionKind `slack_post` (default `act`).
+
+## Joining a team server
+
+A teammate joins with a code an admin made, and the device carries the teammate's name (KAT-356) and a role (KAT-364). The pairing routes are the phone's (`src/routes/phone.ts`).
+
+**Roles.** A device is a `member` or an `editor`; a device made before roles existed is a member, and so is the Tailscale owner. The admin token and a loopback browser on a server with no token may do everything. The check runs on every `/api` call (`remoteAccess` in `src/phone/auth.ts`), and anything not listed is refused:
+
+- A member: every read, `POST /api/approvals/:id`, `POST /api/chat`, `POST /api/runs/:id/rerun` and `/cancel`, `POST /api/dots/:id/review`, the manual test run results, impact accept and reject, failed alert retry and dismiss, `POST /api/push/subscribe`, `PUT /api/phone/me/updates`, `DELETE /api/phone/me`, and `PATCH /api/dots/:id` with a body of only `paused` (a boolean).
+- An editor adds: `PATCH /api/dots/:id` with any field but the admin-only runner fields below, `POST /api/runner/try` with the dot's saved runner, `POST /api/memory`, `DELETE /api/memory/:id`, `POST /api/cards/comment`, and `POST /api/cards/status`.
+- Admin only, inside the editor's routes: `runner.command`, `runner.setup`, `runner.passEnv`, `runner.copyFiles`, `runner.image`, `runner.mode`, `runner.workingDirectory`, `runner.workdir`, `runner.trustForks`, and `repos[].test.command`, `passEnv`, and `dir` (`RUNNER_ADMIN_FIELDS` in `src/runner/command.ts`). A `PATCH /api/dots/:id` from a device that changes one of them, a field left out of a sent `runner` included, answers 403 `{ error: "Ask your localdost admin to change test commands.", code: "runner_admin_only", fields }` and saves nothing; a `runner` with them as saved is a save. `POST /api/runner/try` from a device answers the same 403 for a runner that differs from the dot's in those fields, or with no `dotId`.
+- Admin only, also inside the editor's routes (KAT-369): which code a run checks out. These are the repos of the dot and their roles, their order (the first app repo is `repo`), `repos[].defaultBranch` and `repo.defaultBranch`, `repos[].targets`, `repos[].test.framework` and `ref`, and `testBranches` (`repoAdminChanges` in `src/repos.ts`). The command, setup, folder and test login of a Tests repo (`repos[].test.command`, `setup`, `dir`, `passEnv`) are admin settings like the runner's. A `PATCH /api/dots/:id` from a device that changes one of them, read as a run reads them, answers 403 `{ error: "Ask your localdost admin to change repositories.", code: "repo_admin_only", fields }` and saves nothing; the saved list, or `repo` with the saved owner, name and branch, is a save, and so are `pathFilters`, `prScope`, and `runTests`. `POST /api/runner/try` from a device answers the same 403 for a `repo` that is not the dot's own repo and branch.
+- Neither role: connections and setup (`/api/connect`, `/api/setup` writes), `POST /api/dots`, `DELETE /api/dots/:id` in any mode (archive and delete), `POST /api/dots/:id/restore`, and the pairing routes below. A phone that archived or restored a dot before roles existed is a member now, so it can no longer.
+- Chat holds the same line: `POST /api/chat` stays open to a member, but the `add_memory` tool answers a member's turn with `Ask your localdost admin.` and saves nothing, as `POST /api/memory` does.
+- A refusal is 403 `{ error: 'Ask your localdost admin.', code: 'phone_blocked' }`. The app shows "Ask your localdost admin" for that code and never takes it for an unpaired device.
+- `GET /api/phone/me` answers `{ kind, role }` for the caller: `kind: 'device'` also carries `device`, and the admin token answers `{ kind: 'admin', admin: true, role: 'admin' }`. The app reads it to show only the controls the role may use.
+
+- A request with no valid credential gets 401 `{ error: 'unauthorized', code: 'auth_required' }` from the server-wide check. The page shows the Join screen for that code only. The connection routes (`/api/connect`, `/api/setup/...`) answer a paired device or the Tailscale owner with 403 `phone_blocked`, never 401.
+- `GET /api/phone/join` is open without credentials. It answers `{ name, empty }`: the value of `LOCALDOST_SERVER_NAME`, or null, and whether the server has no dot yet. The Join screen shows the name, and on an empty server it also asks the admin for the server token. A `POST` to this path needs a credential like any other `/api` call.
+- `POST /api/phone/invite` makes an invite code. Admin only (the admin token, or a loopback browser on a server with no token) and same-origin. The optional body `{ ttlSec, role }`: `ttlSec` is 3600, 86400 (the default), or 604800, and `role` is `member` (the default) or `editor`; any other value is a 400. Answers 201 `{ code, display, expiresAt, ttlSec, role }`. A code works once, never cancels another open code, and is stored as a hash. 429 after 20 new invites in 10 minutes.
+- `DELETE /api/phone/invite` cancels every open invite. Answers `{ ok, cancelled }`. `GET /api/phone` carries `invites`, the number still open.
+- `POST /api/phone/pair/exchange` trades a code for a device token and takes `{ code, name }`. It accepts phone codes and invite codes, needs no credential, and is rate limited: 5 wrong codes per client in 10 minutes, and 20 in total cancel the open phone code. Invites stay until their admin cancels them or they expire. A code from an invite needs a `name`: a missing name is a 422 and a name another active device already uses (any case) is a 409, both before the code is spent. No device may be named `admin` (any case or spacing, also with a phone code): that is a 422, because an approval made with the admin token is recorded as `admin` and a teammate under the same name could not be told apart from it. A device made from an invite has `viaInvite: true` and the role of the invite; a phone code gives a member.
+- `PATCH /api/phone/devices/:id` takes `{ name?, role? }` and changes the name (never to `admin`, a 422), the role (`member` or `editor`), or both; the next request of the device uses the new role. Admin only. A page that is open reads its role again from `GET /api/phone/me` when its tab comes back to the front and after a `phone_blocked` refusal, so a change shows without a reload. `GET /api/phone` lists each device with its `role`.
+- `POST /api/phone/pair/self` takes `{ name }` and makes a device in the admin's name, an editor with no `viaInvite`, without spending an invite. Admin only. It answers 201 `{ token, device }` once, so the browser that asked keeps the token; a missing name is a 422, `admin` is a 422, and a name another active device uses is a 409. The audit trail records `paired` with the detail `admin computer`.
+- `PUT /api/phone/me/updates` saves the calling device's own update level and quiet hours, `{ level?, quiet? }` as in `PUT /api/updates/prefs/:id`. The row is `device:<device id>`, it needs a paired device (400 otherwise), and revoking the device removes it. Phone alerts to that device follow it: Off sends nothing, Only what needs me sends decisions, outages, and high urgency, and an alert that arrives in quiet hours is skipped for that device, not held or sent later. A teammate's device gets no digest and no Slack message. `GET /api/updates/people` answers a device with its own row only, labelled `You`.
+
+`POST /api/approvals/:id` stores `decidedBy` on the approval when the caller is a paired device (its name), the Tailscale owner (its login), or the admin token (`admin`); a loopback browser on a server with no token adds none. `POST /api/cards/comment` and `POST /api/cards/status` pass the same name: the run step reads `Asked on a card by <name>` and the draft carries `meta.askedByName`. A Slack decision stores `Slack <name>`, the name Slack sends with the button press, or `Slack <user id>` when it sends none.
+
+## Browser probes
+
+`ProbeConfig` gains `kind: 'http' | 'browser'`, `selector?: string`, `steps?: string[]`. Browser probes load the page in Playwright, wait for the selector, and capture a screenshot on failure.
+
+## Failed alerts
+
+`GET /api/updates/failed` answers `{ items, total }`. `items` lists urgent updates that gave up on Slack or the phone (`?dotId=` for one dot, `?limit=` up to 100), newest first. `total` is how many failed alerts there are in all, so it can be larger than `items`; the app's "Dismiss all N" button shows it. A row whose decision is no longer pending carries `approvalSettled: true`. The app shows them as "Alerts that did not arrive", on the dot page and in the Inbox. Three routes clear them:
+
+- `POST /api/updates/:id/retry` sends the alert again now on its failed channels only, with the same send code as the timed retries. Quiet hours do not hold it, and a channel that is turned off is reported and not sent. Answers `{ update, sent, failed, cleared }`. `cleared` is true when no failed channel is left. The attempts stay and the new try is added to them. 404 for an unknown update. 409 with `code` `not_failed`, `settled` (the approval it announced is already decided), or `archived` (the dot is archived).
+- `POST /api/updates/:id/dismiss` takes the alert off the list without sending it and ends its retries. It sets `dismissedBy` and `dismissedAt` on the update. Answers `{ update }`. 404 and 409 `not_failed` as above.
+- `POST /api/updates/failed/dismiss` dismisses many. The optional body `{ dotId?, olderThan? }` limits it to one dot and to alerts created before the timestamp. Dismisses every matching alert, not only the page that `GET` returns. Answers `{ dismissed, ids }`. 400 for a `dotId` that is not a string or an `olderThan` that is not a timestamp.
+
+A paired phone may call all three: a retry resends a message the dot already wrote, and a dismissal only hides the entry from the list.