@lotics/ui 45.10.0 → 46.0.0

package/docs/ai_patterns.md

@@ -14,11 +14,9 @@ file). Every component here is in the [catalog](./catalog.md) inventory.
 The AI surfaces share ONE law: the agent never commits **invisibly**. The agent owns judgment
 (recognition, estimation, intent→parameters); the app owns geometry, math, and the write. How
 the human stays in charge follows **who supplied the values**, not whether a before-state
-exists. A diff is one way to show a person what a machine decided; it is not the only reason
-they need to see it. Values a HUMAN typed need no gate — they already read them, on the way in.
+exists. Values a HUMAN typed need no gate — they already read them, on the way in.
 Values a MACHINE read off a document need one, and a create is not exempt just because there is
-nothing to compare against: a receipt saying "Created 3 cases" is the first moment the operator
-could have caught a misread reference, and by then it is in the data.
+nothing to compare against.
 
 - **Modifying an existing record** — a diff exists, and a wrong value can clobber a right one →
   review BEFORE apply: `DiffValue` + `DiffMark` + `useChangeSet`, composed into the screen; nothing auto-applies.
@@ -26,20 +24,18 @@ could have caught a misread reference, and by then it is in the data.
   so nothing to diff, but the values are still proposed rather than typed → **a full EDITABLE
   preview of every record before the write**, not a summary of it. Lay the records out as they
   will be stored — every field, editable in place, nothing behind a "3 fields" count — and
-  commit once. There is no diff to mark, so the whole record is the review; `DiffMark` still
-  earns its place to say which records are new versus matched onto something existing.
+  commit once. `DiffMark` still earns its place to say which records are new versus matched onto something existing.
 - **Creating new records a human TYPED** (the manual create form) — they read every value on
   the way in → **apply directly, then end on the RECEIPT**
-  (`@lotics/ui/result_header`) — the receipt states the outcome and ROUTES; it is never a
-  record editor. Run DETERMINISTIC checks over what the save STORED (a checksum, a count
+  (`@lotics/ui/result_header`) — the receipt states the outcome and ROUTES. Run DETERMINISTIC
+  checks over what the save STORED (a checksum, a count
   reconciliation — binary math, never a fabricated score). ONE record: `ResultHeader` (tone,
   outcome title) → the RECEIPT LINES — a `DetailTable` of spread `DetailRow`s (who, how
   much, how many, the schedule) — → **`Confidence`**: the level WITH its basis as
   one block, always (the happy path says what was checked; the flagged path NAMES the exact
-  failing values — the user knows what to verify BEFORE opening). Confidence never floats
+  failing values). Confidence never floats
   alone as a bare meter on a result surface. NOTHING in the receipt edits: the RECORD is the edit surface (its
-  flagged cells carry the same amber marks), one press away — correction uses the record's
-  ordinary verbs. SEVERAL records: a compact attention-first RESULT REGISTER (`ListItem` per
+  flagged cells carry the same amber marks), one press away. SEVERAL records: a compact attention-first RESULT REGISTER (`ListItem` per
   record — tone mark, outcome title, key figures, the needs-checking count) whose rows
   press STRAIGHT THROUGH to the record — no intermediate screen. Never tabs (they cap out),
   never stacked collapsed cards, never a field wall duplicating the record page. A
@@ -51,9 +47,7 @@ could have caught a misread reference, and by then it is in the data.
   The closing footer button is dismissal (secondary "Done"), never primary. Correction beyond
   the receipt uses the record's ORDINARY verbs — open it, edit or delete (make the delete
   workflow CASCADE the record's children, so deletion is always safe) — never a special undo
-  affordance duplicating the delete verb. A review GATE on a create degenerates into
-  proofreading a wall of cards the user blind-confirms — and a human cannot eyeball-verify a
-  reference number anyway; deterministic post-save checks catch what proofreading cannot.
+  affordance duplicating the delete verb.
 
 Either way the deterministic app applies the write. Compose the surfaces as a loop, and reach
 for the right one by job.
@@ -71,14 +65,12 @@ Three shapes:
    operator acts on what was found) → **in-app agent** + **`Finding`**. Still bounded and
    prompt-free (an optional instructions brief at most): the brief is fixed, the output is
    structured display-only findings read IN the record's context, and there is no conversation
-   to have — the loop closes when the operator acts in the app. Chat would add prompting and
-   tear the findings away from the record they judge.
+   to have — the loop closes when the operator acts in the app.
 3. **A file or an open-ended answer** (edit this document, draft from context, explain) →
    **hand off to the chat agent** (`askAi` in `@lotics/app-sdk` — see
    [the SDK's fields-vs-file razor](../../app-sdk/docs/ai.md)). The loop is multi-turn with
    no output schema, judged by looking — and the chat harness already owns it: preview beside
-   the thread, version chains, branching, session memory. An in-app "edit chat" would
-   re-implement all of that inside every app.
+   the thread, version chains, branching, session memory.
 
 The Document desk's Use-AI fork IS this table as UI: Extract data (1), Cross-check (2),
 Edit with AI (3) — one entry point, three outcome shapes
@@ -124,37 +116,32 @@ A CTA that starts an agent run (or any paid/mutating action) must make the PRESS
 transition — never leave a live button waiting on a network round-trip:
 
 - **Same-tick feedback.** On press, synchronously close the dialog / swap to the run surface
-  (`AgentRun` with its streaming state) so there is nothing left to click. A button that stays
-  pressable while an attach/start request round-trips invites double-fires.
+  (`AgentRun` with its streaming state) so there is nothing left to click.
 - **Single-flight in app code too.** Guard the handler with a ref (state alone races the
   re-render): first press wins, later presses no-op until the flow settles.
 - **The SDK backstops runs, not workflows.** `useAgentRun().run()` is single-flight by default
   (a duplicate call joins the in-flight run; `replace: true` is the deliberate restart) — but
-  `useWorkflow` calls are NOT deduped (rapid distinct calls are legitimate), so a workflow CTA
+  `useWorkflow` calls are NOT deduped, so a workflow CTA
   must disable itself (`loading`) while pending or a double-click writes twice.
 
 ## Stopping — the exit is part of the trigger
 
 The press being irreversible is a property of the BUTTON, not of the run. Every streaming surface
-owes the operator a way out, because the reason to leave is usually visible in the first few
-steps: it read the wrong document, it is grouping the wrong way, the brief was wrong. Without an
-exit they pay for a result they already know they will discard.
+owes the operator a way out.
 
 - **`cancel`, never `abort`.** `useAgentRun` exposes both and they are not synonyms. `abort` stops
   LISTENING — the run keeps executing server-side and lands in the session history. `cancel` stops
   the run itself. A user-facing Stop wires to `cancel`; `abort` is for unmount.
-- **Closing a dialog must CANCEL.** This is the one that leaks silently. The hook aborts on
-  unmount by design — right for a page you navigate away from and will come back to, wrong for a
-  dialog just dismissed, where the result is abandoned and every remaining token is spent on
-  nobody. Unmount is not cancellation; the close handler calls `cancel` itself.
+- **Closing a dialog must CANCEL.** The hook aborts on unmount by design — right for a page you
+  navigate away from and will come back to, wrong for a dialog just dismissed, where the result is
+  abandoned. Unmount is not cancellation; the close handler calls `cancel` itself.
 - **Stop lands where the run STARTED**, not on a dead transcript — the intake, with the files, the
-  brief and the answers still there, because the operator stopped in order to change one of them.
-  It is the same destination the parked wizard's Cancel uses; only the verb differs, and it
-  differs truthfully — you STOP something running, you CANCEL something waiting.
+  brief and the answers still there.
+  It is the same destination the parked wizard's Cancel uses; only the verb differs — you STOP
+  something running, you CANCEL something waiting.
 - **The control is PINNED, in the footer.** A feed that follows its newest part scrolls a control
-  placed inside it away from the reader — exactly while the run is doing the thing they want to
-  stop. `AgentRunActions` renders Stop for you; a surface composing its own footers states it
-  directly ([`tpl_item_list`](../examples/tpl_item_list.tsx) and
+  placed inside it away from the reader. `AgentRunActions` renders Stop for you; a surface
+  composing its own footers states it directly ([`tpl_item_list`](../examples/tpl_item_list.tsx) and
   [`tpl_record`](../examples/tpl_record.tsx) respectively).
 
 ## Show the work — `AgentRun`
@@ -170,12 +157,10 @@ bespoke transcript type. It renders three part kinds:
 | `reasoning` | Thinking — COLLAPSED, a muted "Thinking" row; press to reveal the Markdown |
 | a tool part — `dynamic-tool` (app agents) or `tool-<name>` (chat) | An activity row with a status dot |
 
-Parts appear in the order they happened — a real run is think → text → a burst of calls → more
-text, NOT all text on top of a flat step list. Content parts with no feed representation
+Parts appear in the order they happened, NOT all text on top of a flat step list. Content parts with no feed representation
 (`source-*`, `file`, `data-*`, `step-start`, `custom`) are skipped. Transparent work, NEVER a bare spinner.
 
-**Progressive disclosure.** The feed shows the label + state; the detail is revealed on demand. A
-tool part's `input`/`output` are hidden in the row and **expand in place** on press — auto-built
+**Progressive disclosure.** A tool part's `input`/`output` are hidden in the row and **expand in place** on press — auto-built
 Input / Output `JsonPanel`s roll out under the row (the same disclosure pattern as "Thinking",
 never a popover). A tool in an `output-error` state flows like any other call — the dot goes
 amber and its `errorText` shows in the expanded Error panel. To render a tool's OUTPUT yourself
@@ -186,39 +171,104 @@ Output panel; `undefined` keeps it. Input + error rendering are untouched.
 **Activity grouping.** Consecutive tool parts fold into ONE group. While the agent is mid-tools
 the tail group is a SINGLE pulsing row whose label swaps in place as each call fires (no growing
 stack of dots); once prose resumes the group settles: a single call becomes one done row, and a
-multi-call group becomes a persistent "{final action} ({n} steps)" HEADER (a `complete` terminal
+multi-call group becomes a persistent "{final action}" HEADER (a `complete` terminal
 dot — distinct from the filled `done` step dots; amber `warning` if any call errored) that STAYS
-PUT and rolls the calls out BELOW it on press. The run ALWAYS ends on the agent's text — there is
-no global terminal node.
+PUT and rolls the calls out BELOW it on press.
+
+**ONE row for the whole run, and NO prose until it ends.** While the agent works, the entire feed
+is a single row. It names the call in flight — "Searching records" — and says
+**"Thinking…"** whenever the model is writing rather than calling, which is every gap between
+calls. The dot pulses; nothing rolls out unless the reader asks.
+
+**No step count.** The row says WHAT is happening and stops there. A tally was a number the reader
+could act on in no way: live, the label already changes on every call, so it added no motion the
+row did not have; settled, it sized work nobody had asked to size. The chevron carries "there is
+more inside".
+
+**The agent's between-call text is not shown at all.** It is narration by instruction — a plan the
+prompt tells it to state up front, asides capped at two sentences — and none of it is load-bearing
+in flight. The one message that genuinely needs a response is a bulk-mutation confirmation, and
+there the agent WAITS: the run stops, so that text becomes the trailing text and renders as the
+answer. Showing the rest bought a sentence that appeared, got half-read, and vanished when the
+next call superseded it. The threshold is that the run did SOME work — a reply with no tool calls
+at all is all answer, and hiding *that* behind a row until settle would be the real loss.
+
+A reader waiting on an answer is not reading a transcript, and a transcript that scrolls past
+while they wait is still noise — bounding it only makes the noise a fixed size. What they need is
+that something is happening and roughly what; the label and the count carry both, and the press
+carries the rest. That the waits are long (production: **p50 25s, p90 94s**; five-plus tool calls
+p50 52s / p90 144s) is an argument for the label CHANGING, not for showing the feed.
+
+The cost, stated plainly: the answer appears at settle rather than streaming. Final responses are
+≤3 sentences by instruction, so what is given up is a second of typing — against never yanking a
+half-read sentence out from under anyone.
+
+Grouping alone could never deliver this, because a group breaks on every prose part AND every
+reasoning part. An interleaved-thinking run therefore rebuilt the stack one group at a time — the
+reader watched finished rows pile up while they waited, and was then left with that pile sitting
+above the answer at the answer's weight, every row of it stale.
+
+**Expanding is where live and settled differ, and the only place they do.** Opened mid-run the
+timeline is CAPPED and self-pinning (220px, ~5 rows) — someone who opens a run in flight asked to
+see the work, not to hand the page a feed that grows for another minute; `FollowScroll` follows at
+LAYOUT level so each call paints already pinned. Opened once settled it is uncapped: nothing is
+arriving, so there is nothing to cap. Settling never closes what a reader opened; it just stops
+capping it.
+
+The split is POSITIONAL (`splitTimeline` in `agent_transform`): what comes after the last tool
+call is the answer, everything before it is the work. Nothing has to decide whether a paragraph
+was a plan or a report — a model emits all of it as `text`, so only position is knowable, and
+while the run is still moving that position is not yet final. Which is why the answer waits for
+settle: at that moment, and only then, the trailing text is known to be the report.
+
+The work stays fully open where collapsing would hide something needed: while any call is parked
+`awaiting` a human decision (the approval surface would be asking about work the reader can no
+longer see); when a SETTLED run stopped ON a tool call, leaving no answer to fold behind (mid-run
+that is just "not there yet", not a dead end); when the work is already one row (folding buys
+nothing and costs a second press to reach a step's I/O); and when no tool ran at all (`Thinking`
+is already a collapsed row, and a summary could only name a step that never happened).
+**`collapseProcess={false}`** hands the whole job back to the caller — for a surface that ALREADY
+frames the run (`AgentProgress`'s pill) or one whose subject is a step's own output; such a
+surface owns the `FollowScroll` too, and one on the default must NOT add one or it nests a
+scroller in a scroller. **`summarizeRun(steps)`** renames the row; the default names the current
+or last action and nothing more, because only the HOST knows which of its tools WROTE, and a
+kit-side list of write tools would be silently incomplete the first time one was added —
+reporting a run that changed data as though it had only read. A host that knows should say so
+("Updated 3 records"): that is the one fact worth reading without expanding.
+
+An ARTIFACT the run produced — a file, an image, a record diff — belongs in the result zone the
+host renders below the feed, never inside a tool's output panel where the fold puts it two
+presses away.
 
 **Tool labels.** A tool part carries the RAW tool name (`update_records` from `tool-update_records`,
-or a `dynamic-tool`'s `toolName`), resolved through the active locale's **`agentRun.tools`** map —
-so a `vi` provider renders Vietnamese tool rows with no per-app wiring, the same way the rest of the
-feed's chrome already resolved. An optional **`labelForCall`** override still wins, for phrasing a
-call by what it TARGETS rather than by which tool ran. It gets the whole call — `{ toolName, input, state }` (`AgentToolCall`) — so a caller can phrase by what the
-call targets or by whether it's awaiting; return `undefined` to fall back. Unknown names fall back
-to a prettified form. `stepsLabel` localizes the "{n} steps" suffix. The tool `state` folds ai's
+or a `dynamic-tool`'s `toolName`), resolved through the active locale's **`agentRun.tools`** map.
+An optional **`labelForCall`** override still wins, for phrasing a call by what it TARGETS rather
+than by which tool ran. It gets the whole call — `{ toolName, input, state }` (`AgentToolCall`);
+return `undefined` to fall back. Unknown names fall back
+to a prettified form. The tool `state` folds ai's
 7-state lifecycle to **running / awaiting / done / error**: `approval-requested` → `awaiting` (the
-call is parked on a human decision — an amber dot + an "awaiting" annotation, and it NEVER pulses,
-because it isn't working); `approval-responded` → running; `output-denied` → error carrying the
+call is parked on a human decision — an amber dot + an "awaiting" annotation, and it NEVER
+pulses); `approval-responded` → running; `output-denied` → error carrying the
 denial reason. The whole-run `state` prop (`"streaming" | "done" | "error"`) defaults to `streaming`
 while any tool is running, else `done` (an awaiting call is not running, so it settles).
 
 **Errors — two kinds, both surfaced, neither shouting.** An INTERMEDIARY tool failure rides in
 that tool's `output-error` part and flows like a normal call — the amber dot marks it (a settled
-group's header goes amber too), the reason waits in the expanded Error panel; real runs retry and
-move on, so the feed doesn't dramatize it. A BREAKING error that terminates the whole run lives
+group's header goes amber too), the reason waits in the expanded Error panel. A BREAKING error that terminates the whole run lives
 OUTSIDE `parts` (chat persists it in the message's `errors`; `useAgentRun().error` carries it) —
 pass it as the `error` prop and it terminates the feed with an error `Callout` — a contained,
-tinted panel rather than another step row, because the run did not advance, it stopped, and it
-carries `role="alert"` so a screen reader announces it. Pass **`onRetry`** alongside it and a Retry
+tinted panel rather than another step row, and it carries `role="alert"` so a screen reader announces it. Pass **`onRetry`** alongside it and a Retry
 action (a secondary `Button`) sits INSIDE that panel so the operator can re-fire the run; omit it
 and the panel carries the message alone.
 
-**In a bounded container, wrap it in `FollowScroll`.** An `AgentRun` streaming inside a dialog,
-drawer, or fixed-height panel grows BELOW the fold — a plain scroll container doesn't follow. Wrap
-the feed: `<FollowScroll style={{ maxHeight: … }}><AgentRun … /></FollowScroll>` — the same
-inverted-list mechanism as a chat message list, packaged as a wrapper: the follow happens at
+**`FollowScroll` — only when you took the job (`collapseProcess={false}`).** A run opened mid-flight
+already caps itself with exactly this, so wrapping the default AGAIN nests a scroller in a
+scroller: the outer never overflows, the inner holds the content, and the wheel lands on whichever
+the pointer happens to be over. Reach for the wrapper when the run is a raw timeline you are
+framing yourself — a dialog, drawer, or fixed-height panel where the feed grows BELOW the fold and
+a plain scroll container doesn't follow. Wrap it then:
+`<FollowScroll style={{ maxHeight: … }}><AgentRun … collapseProcess={false} /></FollowScroll>` — the same
+inverted-list mechanism as a chat message list: the follow happens at
 LAYOUT level (each growth paints already pinned — no scroll-after-paint flash), scrolling up
 releases it, and the feed stays at the newest content when the run settles (`AgentProgress`'s
 expanded panel does this). When settling REPLACES the feed with different content (a results
@@ -233,7 +283,7 @@ for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={
 install; the imports are type-only (purity-enforced), so no `ai` runtime ever enters a bundle.
 **A run with no parts yet renders the breathing "Starting…" row** (streaming state only) — the
 live dot plus a label that pulses, covering the gap between the CTA press and the first streamed
-part (upload + run creation + first token); a silent feed reads as broken. **The law: pass
+part (upload + run creation + first token). **The law: pass
 `state="streaming"` from the moment the paid CTA fires — uploads included — and render
 `AgentRun` even with zero parts. Never hand-roll a text/skeleton placeholder in front of the
 feed**; the starting row IS the placeholder, consistent and localized.
@@ -243,9 +293,9 @@ feed**; the starting row IS the placeholder, consistent and localized.
 
 **Localization.** The feed's fixed chrome — the "Thinking" label, the "Input"/"Output"/"Error"
 panel titles, the "awaiting" annotation, the "Retry" action, the tool labels (`agentRun.tools`,
-keyed by raw tool name) and the "{n} steps" suffix (`agentRun.steps`) — resolves through the
+keyed by raw tool name) — resolves through the
 `LoticsLocale` `agentRun` slice (translate once at the provider; a `vi` app gets them for free);
-`labelForCall` and `stepsLabel` remain as per-call-site OVERRIDES.
+`labelForCall` remains a per-call-site OVERRIDE.
 
 **Answering an awaiting call — `ApprovalPrompt`.** The `awaiting` row inside `AgentRun` is
 READ-ONLY — it only NAMES that a call is parked on a human decision. The surface that ANSWERS it
@@ -263,7 +313,7 @@ locale slice → English.
 On a canvas/composer app reach for `AgentProgress` (`@lotics/ui/agent_progress`) — `AgentRun`
 collapsed into a floating pill (an animated `WaveAvatar` + the current step's label) that EXPANDS
 on press to the full feed in a capped scroll panel. It takes the same `parts`/`state`/`error`, and
-forwards `labelForCall`/`renderToolOutput`/`onRetry`/`stepsLabel` to the expanded feed, plus `label`
+forwards `labelForCall`/`renderToolOutput`/`onRetry` to the expanded feed, plus `label`
 (override the collapsed text — defaults to the running step's label, else "Working…" / "Done" /
 "Stopped"; pass it to localize — note it's one static string, so it no longer tracks the running
 step) and `defaultExpanded`. Its pill matches `Composer`'s compact geometry, so the composer morphs
@@ -275,17 +325,15 @@ into it while running and reveals again when done.
 ## Review before apply — TWO atoms and a hook, composed into your screen
 
 **When to reach for it — the one law's boundary.** A review gates values the MACHINE
-supplied, whether or not they replace anything. Modifying an existing record is the obvious
-case and takes the full diff. Creating records FROM A DOCUMENT takes the same gate in a
-different shape — no diff, because nothing is being replaced, but the whole record laid out
-and editable before the write (`examples/tpl_item_list.tsx`). Only values a HUMAN TYPED skip
-it: they read them on the way in, so the manual form saves direct and ends on the receipt.
+supplied, whether or not they replace anything. Modifying an existing record takes the full
+diff. Creating records FROM A DOCUMENT takes the same gate in a different shape — no diff, but
+the whole record laid out and editable before the write (`examples/tpl_item_list.tsx`). Only
+values a HUMAN TYPED skip it: the manual form saves direct and ends on the receipt.
 
 **There is no review CONTAINER, deliberately.** A review is not a place you go; it is something
 that happens to values already on screen. So the diff renders wherever the value renders — a
 table cell, a `DetailRow`, a total, a chip, a sentence — and inherits that container's width,
-alignment and rhythm. A compound family with a provider at its root can only produce the one
-shape its root draws, and every surface needing a diff somewhere else rebuilds it by hand.
+alignment and rhythm.
 
 ### The three pieces
 
@@ -294,39 +342,28 @@ shape its root draws, and every surface needing a diff somewhere else rebuilds i
   dense rows; `align`/`tabular` for money so the struck value and its replacement line up;
   `tone` when the change itself is the bad news. **The three ops are the same component:**
   an ADD omits `before`, a REMOVAL omits `after` (the struck value IS the change), an UPDATE
-  passes both, and **equal values collapse to one** — agreement is not a change, and an invoice
-  confirming the amount that was claimed is the GOOD case, not a diff of a value against
-  itself. **Both values stay on screen** on a real change (the old one is the only evidence the
-  correction is the right SIZE), and **`delta`** prints the movement itself — "+250 pcs",
-  "−118.519 ₫ VAT" — so nobody subtracts in their head.
+  passes both, and **equal values collapse to one** — agreement is not a change.
+  **Both values stay on screen** on a real change, and **`delta`** prints the movement itself — "+250 pcs",
+  "−118.519 ₫ VAT".
 
   **The struck value is muted, never red.** An old value is not an ERROR, and red is this
-  system's error colour — every routine update would read as a problem, and a table of eight
-  changed rows would carry sixteen coloured figures. Red-against-green is also the one pair a
-  colour-blind reader cannot separate, and it is the distinction a review turns on. The
-  strikethrough carries "going away" with no colour at all; weight, tone and (stacked) size
+  system's error colour. Red-against-green is also the one pair a colour-blind reader cannot
+  separate. The strikethrough carries "going away" with no colour at all; weight, tone and (stacked) size
   carry the rest.
 - **`DiffMark`** (`@lotics/ui/diff_mark`) — what happened to the row holding the value, for the
   cases no single value carries: `added` / `changed` / `removed` / `unchanged`. Glyph plus an
-  accessible word, never colour alone. `unchanged` draws a quiet dot, because most rows in a
-  real review are untouched.
+  accessible word, never colour alone.
 
   **ONE treatment, every surface: a filled 22px disc.** The form, the line table, the files
-  list and the thumbnail grid all draw the same mark, because a reader parses shape before
-  meaning and a form marked with bare glyphs beside a table marked with filled shapes reads as
-  two systems saying the same thing. `unchanged` renders as an empty disc-sized HOLE: an
-  operator opening a job of twelve fee lines to see where a dropped invoice landed should find
-  the one filled shape in a column of blanks without reading anything or separating two hues.
-  The hole keeps the column's width and announces nothing.
+  list and the thumbnail grid all draw the same mark. `unchanged` renders as an empty
+  disc-sized HOLE: it keeps the column's width and announces nothing.
 
   **Derive the kind from the same before/after the row's `DiffValue` carries — never from a
   boolean "did this differ".** A field with no prior value (`before` empty or absent) that a run
   now proposes a value for is an ADD, not a CHANGE, and a local review row that only asks
   "does `draft !== before`" answers yes for both and always renders `changed` — the amber pencil
-  on a value that was never there to begin with, which reads as the AI having second-guessed a
-  figure it actually just filled in for the first time. This bites hardest on the record that
-  looks most ordinary: the first proposal any fresh record ever gets has an empty `before` on
-  every field, so every mark on that one run is wrong until the kind is derived per field
+  on a value that was never there to begin with. The first proposal any fresh record ever gets
+  has an empty `before` on every field, so every mark on that one run is wrong until the kind is derived per field
   (`before === after` → no mark; `before === ""` → `added`; otherwise → `changed`).
 - **`useChangeSet(ids, { initial })`** (`@lotics/ui/use_change_set`) — the bookkeeping:
   `status`/`accept`/`reject`/`undo`/`acceptAll`/`reset`, `accepted`/`rejected`/`pending`,
@@ -339,33 +376,28 @@ shape its root draws, and every surface needing a diff somewhere else rebuilds i
 - **A record's fields** — a `DetailTable` of rows, each a label plus a `DiffValue`, with
   Keep/Drop on the row and a collapsed state once decided. That row is ~20 lines and it belongs
   to your screen: `examples/tpl_record.tsx` and `dev/pages/ai.tsx` each write their own and they
-  read differently, which is the system working.
+  read differently.
 - **A record SET** — a `Table`, one row per proposed record, `DiffMark` leading and `DiffValue`
-  inside the figure cells. A set of ledger lines reads like the ledger it is about.
+  inside the figure cells.
 - **A conflict** — two documents disagree, so the value is the read-only OUTCOME of a pick:
   a `DiffValue` showing the placeholder until resolved, over `CardSelectItem` candidates (each
   naming its source document) and a type-another-value option. **Never pre-select**, and gate
-  Keep until one is chosen — a pre-selected candidate is a decision the system made and
-  attributed to the person.
+  Keep until one is chosen.
 - **An ATTACHMENT** — a dropped document's proposal is often not a value at all: it is WHICH
-  LINE the file belongs to. That decision is as wrong-able as a misread figure and gets the
-  same treatment — the file rendered on the row it lands on, inside a `DiffValue` whose sides
+  LINE the file belongs to. That decision gets the same treatment — the file rendered on the row it lands on, inside a `DiffValue` whose sides
   are NODES (a `FileBadge` plus its name). A file replacing one already filed shows both, and
   the superseded one is struck by a DRAWN rule: `line-through` set on a `Text` does not cross
-  a `View` child, so without it the old scan renders at full strength beside its replacement
-  with nothing saying which is going away. Worked in `examples/tpl_record.tsx`.
+  a `View` child. Worked in `examples/tpl_record.tsx`.
 - **A DOCUMENT SET** — a files section is not a field. It is a set of objects with identity,
   so what changes is MEMBERSHIP plus per-document properties, and the kinds do not share a
   treatment. **Added** and **removed** are membership: the row's existence and its mark are
   the whole change. **Superseded** is one slot whose bytes changed — the row names the new
   file and its second line names the one it displaces. **Reclassified** is the one a review
   surface gets wrong: the bytes are untouched and only the FILING moved, so the `DiffValue`
-  belongs on the property — a mark with no visible diff reads as though the file itself
-  changed. `FileRow` takes the mark in `leading` (so the names still form a column) and a node
+  belongs on the property. `FileRow` takes the mark in `leading` (so the names still form a column) and a node
   `meta` (so the second line can carry a diff).
 
-  **In a GRID** the same set reads differently again, and that is a property of the shape
-  rather than a gap: a grid is scanned whole, so it carries membership (this is arriving, that
+  **In a GRID** the same set reads differently again: a grid is scanned whole, so it carries membership (this is arriving, that
   is leaving — `FileThumbnailGrid diffs`, a corner mark plus a fade) at a glance and carries
   pairing not at all. Pick the surface for the change; do not shrink the change to fit a shape.
 
@@ -373,56 +405,45 @@ shape its root draws, and every surface needing a diff somewhere else rebuilds i
   a tile — the badge earns its space and the row is built around it. Where the file is one
   VALUE among several columns, render the filename as a value at the column's own text size:
   a badge shrunk to fit a table cell takes its label off the type scale entirely (5px, at the
-  size a cell allows), and sizing it back up makes it set the row's height for a fact the
-  extension already carries.
+  size a cell allows), and sizing it back up makes it set the row's height.
 
   **The strikethrough has a discriminator.** Strike the superseded file when it shares a CELL
   with its replacement, adjacent — a table's document column, where the pairing is what the
   cell means. Do NOT strike it on a files-section line, where the two sit on different rows:
-  there the strike says "going away" without saying what replaces it, so a word names the
-  relation and the chip only identifies the file. Both shapes are worked in `dev/pages/ai.tsx`.
+  a word names the relation and the chip only identifies the file. Both shapes are worked in `dev/pages/ai.tsx`.
 - **A record being CREATED from a document** — no before-state, so no diff: the whole record
   is the review. Lay every field out as it will be stored, editable in place, and mark only
   the fact that IS relational (matched onto something existing, or new alongside it). One
   commit named for the outcome. Worked in `examples/tpl_item_list.tsx`.
 - **Display-only** — a finding that informs but has nothing to decide simply is not in the
-  change set. There is no "display-only" mode to remember.
+  change set.
 
 ### The laws that survive the container
 
 - **Nothing auto-applies.** The commit is one explicit press, named for its outcome
   ("Update record (3)", "Add 4 tasks") — never "Apply" alone, never "OK".
 - **Editing IS the review.** A value the operator can correct in place beats accept-or-reject
-  on a value they cannot touch: a wrong proposal you can fix costs a keystroke, one you can
-  only reject costs the whole re-entry.
+  on a value they cannot touch.
 - **Gate the commit on what will actually be written**, not on the proposal count — disable at
   zero kept.
 - **A decided row's Keep/Drop must be reachable from BOTH directions when `initial: "accepted"`.**
   `undo` returns a row to its DEFAULT, not to `"pending"` — so on the common default
-  (`initial: "accepted"`, the operator drops the exceptions rather than re-approving every
-  identical field) a row starts already decided and Undo is a no-op with nothing to reach:
-  there is no path back to a `pending`-style Keep/Drop pair, and the row is stuck accepted
-  forever. The collapsed-to-Undo anatomy (value + one "Undo" button, swapping to Keep/Drop only
+  (`initial: "accepted"`) a row starts already decided and Undo is a no-op with nothing to
+  reach. The collapsed-to-Undo anatomy (value + one "Undo" button, swapping to Keep/Drop only
   while `pending`) is correct ONLY under `initial: "pending"`, where every row genuinely starts
   undecided. Under `initial: "accepted"`, render Keep/Drop as an always-visible TOGGLE instead —
-  both buttons present, the one matching the row's current status disabled, the other live —
-  so either direction is one press away regardless of where the row started.
+  both buttons present, the one matching the row's current status disabled, the other live.
 - **The mark rides the LABEL, and the value sits in an `InlineSlot`.** Both are alignment
   before they are semantics. A mark beside the VALUE indents every row it marks by its own
   width plus a gap, so an unmarked row needs a spacer of exactly the glyph's width to keep up —
-  and they drift (17 against 13 shipped that way). The label column is a fixed width with one
+  and they drift. The label column is a fixed width with one
   left edge, so a mark placed there aligns down the page for free. Give the slot a fixed HEIGHT
   as well as width: it is an inline-flex box inside `DetailRow`'s label `Text`, so an empty one
   baselines differently from one holding a glyph. On the value side, a form mixes 40px editors
-  with 20px flat diffs; without the slot the column has two left edges and two baselines, and
-  the label agrees with one kind of row and not the other.
+  with 20px flat diffs; without the slot the column has two left edges and two baselines.
 - **The reason goes above the verdict.** A `why` passed as `DetailRow`'s `description` renders
-  under the whole cell — which is under the Keep/Drop buttons. A justification printed after
-  the controls that act on it is one nobody reads. Render it inside the value block.
-- **Show the WHOLE thing, not just the parts that moved.** The operator's question is rarely
-  "what did it find" — it is "is this right, and where does it sit". A surface showing only
-  the changed rows answers the first and leaves the second to a second screen. Render the
-  record entire and let `DiffValue` collapse what agrees (equal values render as one plain
+  under the whole cell — which is under the Keep/Drop buttons. Render it inside the value block.
+- **Show the WHOLE thing, not just the parts that moved.** Render the record entire and let `DiffValue` collapse what agrees (equal values render as one plain
   value, so the same component tree serves a record with one change and a record with twenty).
   Emphasis, not omission, is what makes the changes findable.
 - **The fixture must not flatter.** A review demo whose every row carries a change proves
@@ -435,8 +456,7 @@ shape its root draws, and every surface needing a diff somewhere else rebuilds i
 `Clarify` (`@lotics/ui/clarify`): when the agent is unsure, it asks a question with quick-reply
 options and PAUSES, instead of guessing wrong. Human-in-the-loop input mid-run: `question` (the
 prompt, rendered as-is — no eyebrow chrome), `options` (`{ label, value, description }` — every
-answer carries a REQUIRED one-line description so the human picks without re-deriving it from the
-question; a `ChoiceList`), `onAnswer(value)` resumes the run, the controlled `answer` keeps the pick
+answer carries a REQUIRED one-line description; a `ChoiceList`), `onAnswer(value)` resumes the run, the controlled `answer` keeps the pick
 switchable until committed. **`allowCustom`** adds an always-visible, borderless, auto-growing multiline field below the
 options — typing it IS the selection; its text becomes the value (any value not matching an option
 reads as the custom answer).
@@ -446,7 +466,7 @@ Back / Next / Cancel / Submit (Next/Submit primary), the step position an eyebro
 question — no progress bar, and no eyebrow at all for a single question. Each step is a `Clarify`; advance only once the
 current question is answered; `onSubmit` gives one `{ value, custom }` per question (aligned by index,
 `custom` true when the answer came from "Other…"), `onCancel` dismisses. All navigation chrome is
-locale-wired (the `clarify` slice). The multi-question form of the ask-back. **Placement follows
+locale-wired (the `clarify` slice). **Placement follows
 the dialog grammar**: standalone (riding a parked run's stream, where no footer exists) the wizard
 renders its own inline action row; as a DIALOG phase, wrap the `Dialog` with `ClarifyWizardScope`
 and put `ClarifyWizardActions` in the `DialogFooter` — the wizard suppresses the inline row and
@@ -474,29 +494,25 @@ const run = useAgentRun("intake");            // @lotics/app-sdk
 after a question it is the only thing holding how the answered leg ended — your own `run()` promise
 already resolved, with `parked`, and never resolves again. Give `onLanding` the same handler you
 give `run()`: it is typed from your run (no cast), and it re-fires if answering leads to a follow-up
-ask. Omit it and an answered run completes with the host none the wiser — the transcript reads
-"done", your review step never opens, and the paid read is discarded. A host that instead reads its
-result off `status`/`output` does not need it, but is then re-deriving from a render what it was
-handed directly.
+ask. Omit it and an answered run completes with the host none the wiser — your review step never
+opens, and the paid read is discarded. A host that instead reads its result off `status`/`output`
+does not need it.
 
 **The parked question REPLACES the feed — that is the contract, not a style.** The run is blocked
 on the answer, so the question is the only thing to act on; it gets the dialog's own scroller and
-its actions sit outside it. Stacked under the transcript in an unscrollable box — the arrangement
-every app reached for first — a multi-question ask runs past the dialog's height and clips its own
-Submit, leaving a live `awaiting_input` run readable and unanswerable until it expires. The pane
+its actions sit outside it. Stacked under the transcript in an unscrollable box, a multi-question
+ask runs past the dialog's height and clips its own Submit, leaving a live `awaiting_input` run readable and unanswerable until it expires. The pane
 also swaps `FollowScroll` for `DialogScrollArea` on the park, so the question opens at the top
 rather than wherever the feed was scrolled to.
 
 **Mount `AgentRunActions` wherever the run drives the surface — never gated on one phase.** It
 holds the wizard's verbs while a question is up, **Stop** while the run streams, and nothing once
-it settles; the RUN decides, which is the whole point of handing it the run. A host that names a
-single phase out here duplicates that decision and gets it wrong the moment the bar learns a new
-one.
+it settles; the RUN decides. A host that names a single phase out here duplicates that decision.
 
 **`run` is a SHAPE, not an import** (`AgentRunLike`: `status`, `parts`, `pendingChoice`,
 `answerChoice`, `cancel`, `error`; `AgentRunQuestion` names what `pendingChoice` carries, so a template or
 test declares one directly — an option is a label + description and the answer's value IS the
-label, which is the `ask_user_choice` wire shape, so nothing maps between two question types). `useAgentRun()` satisfies it structurally — `@lotics/ui` never depends on
+label, which is the `ask_user_choice` wire shape). `useAgentRun()` satisfies it structurally — `@lotics/ui` never depends on
 `@lotics/app-sdk` — which also means a template or test can hand it a plain object and exercise the
 whole pane with no backend ([`tpl_item_list`](../examples/tpl_item_list.tsx) does exactly that).
 
@@ -533,28 +549,24 @@ list renders nothing.
 reader is deciding about it. The harder surface is the one they open a week later: a stored
 record whose fields were written by a person, by a chat agent, by an extraction off an upload,
 and by an automation that fired when a file landed — and which carries no memory of which was
-which. Increasingly that is the normal shape, because the app's own form is the LEAST used way
-in. Three rules, each of which a screen built for a single writer gets wrong for free.
+which. Three rules, each of which a screen built for a single writer gets wrong for free.
 
 **An unwritten value must not render like a written one.** A row assembled by an automation
 arrives with its enums set and its prose empty, and the natural repair — composing a label out
 of the enums that ARE set — produces a real-looking sentence in body ink. "Nobody has written
-this up" and "this is what happened" then look identical, which is the one distinction the
-reader most needs. Say the value is missing, in the ink an unfilled field already uses
+this up" and "this is what happened" then look identical. Say the value is missing, in the ink an unfilled field already uses
 (`Timeline`'s `placeholder`; the same idea wherever a component takes a `label: string` and
 therefore cannot express absence — that type is the trap, so give it a way to say so).
 
-**A machine's prose and a person's must not share a treatment.** They are different claims and
-they earn different trust, so rendering them alike teaches the reader to skim both at one
-speed. Carry the difference with SHAPE, not weight: name the author and the evidence on the
+**A machine's prose and a person's must not share a treatment.** Carry the difference with SHAPE, not weight: name the author and the evidence on the
 line above ("Written by AI from the recording" — the source alone is not authorship), and drop
 the machine's text into a recessed `Inset`, which says it was not written on this page. Leave
 the person's conclusion on the page's own ground; that contrast IS the signal.
 
 **Model prose arrives with its own type ladder — take it away at the door.** A model asked for
 a summary emits `##` headings and heavy `**bold**` knowing nothing of what surrounds it, and
-document-scale markdown hands those an `h1` equal to your section heading — so the
-least-trustworthy text on the screen ends up the loudest. Render every embedded value with
+document-scale markdown hands those an `h1` equal to your section heading. Render every
+embedded value with
 `<Markdown variant="embedded">`.
 
 And one that is not about treatment at all: **check that the read path projects every field the
@@ -568,22 +580,18 @@ Confidence IS a callout (`@lotics/ui/confidence`) — the ONLY form it takes: th
 meter + level phrase head the block, and the REQUIRED `children` carry the basis — what was
 checked and what came of it ("all 7 references pass their checksum" / "2 of 7 fail (X, Y) —
 verify against the source"). The box stays white with a hairline border at EVERY level — the
-meter is the only colored element (the level already lives in the meter and the phrase; a
-tinted fill would say it a third time). Pass `level` or a 0–1 `score` (≥0.8 high,
+meter is the only colored element. Pass `level` or a 0–1 `score` (≥0.8 high,
 ≥0.5 medium, else low; `levelFromScore` exported). There is NO standalone meter: a level
-without its reasons cannot be acted on, so it cannot be rendered — and where a compact meter
-used to decorate a ranked row or a proposal card, remove it (rank, badges, and severity
-already convey standing). Derive levels HONESTLY (deterministic checks: all pass → high, any
+without its reasons cannot be acted on, so it cannot be rendered. Derive levels HONESTLY (deterministic checks: all pass → high, any
 fail → low) — never render a fabricated score.
 
 ## Findings — evidence, not writes
 
 `Finding` (`@lotics/ui/finding`) is one ranked insight from an AI check — a cross-check
 discrepancy, an audit observation, a briefing item — laid out HORIZONTALLY, in the order a reader
-needs it: a severity dot, the `title`, and the `delta` right-aligned on that same line, then one
-dim line of `readings` (`source value · source value`) beneath. Two lines carry all four things a
-reader wants, and scanning a stack gives severity down the left edge and magnitude down the
-right. `detail` is the CONSEQUENCE and is optional — a second sentence restating the title in
+needs it: a severity dot, the `title`, and the `delta` right-aligned on that same line, then the
+`readings` beneath — ONE PER LINE, each a dim `source` plus its `value`, never joined by a
+separator. `detail` is the CONSEQUENCE and is optional — a second sentence restating the title in
 longer words costs a line and adds nothing.
 
 BOTH readings stay on screen and NEITHER is struck through or marked wrong: a finding reports
@@ -602,7 +610,7 @@ persisted check-status goes stale on the next edit). Stack several most-severe f
 
 The outputs accrue as a history the user can CLEAR ("New session"); the APP owns the evolving
 state, each run is a discrete task. (The agent may re-read the session for "make it a bit less",
-but it's a run LOG, not a conversation transcript — that's why it's not a chat.) The session key
+but it's a run LOG, not a conversation transcript.) The session key
 and history reads are the SDK's: `sessionId` on each run, `useAgentRuns` for the history — see
 [the SDK doc](../../app-sdk/docs/ai.md).
 
@@ -684,13 +692,11 @@ kit does:
   (white centre — pulses only when live), `done` a filled accent dot + **white check**,
   `upcoming` a faint **grey** ring, the terminal `complete` a **blackish ring + black check**,
   `warning` **amber**. Default accent is neutral ink (`Stepper`'s `color` prop themes it);
-  `AgentRun` keeps the neutral default — an active group's tail pulses (`current`), a settled
-  group is a `done`/`warning` row, and there is no global terminal node (the run ends on text).
+  `AgentRun` keeps the neutral default.
 - **ChangeBand** — the removed value on the light **red** band with the `−` marker, the incoming
   value on the light **emerald** band with `+` (the GitHub-diff idiom, markers in one aligned
   column); everything else in a review stays neutral — a decided row reads a single emerald
   check, an add/remove record card wears the quiet tone wash (50 body, 100 header, 200 border).
-  Colour marks the change, never the chrome.
 - **Finding severity** — the coloured dot badge (red / amber / zinc / emerald), most severe
   first.
 
@@ -698,5 +704,5 @@ Card chrome (borders, microlabels) stays neutral — colour marks the *state*, n
 The **composer keeps its icons**: `Composer` compact is a single-row pill with an optional
 circular attach `actionsButton` + a circular send button; expanded it adds a `FileThumbnail`
 attachment row (each `onRemove`-able) above the input; `AgentProgress` is the `WaveAvatar` pill.
-"No icons" was only ever about the review surfaces' sparkles/severity glyphs, not functional
+The "no icons" rule covers the review surfaces' sparkles and severity glyphs, not functional
 affordances.