@lotics/ui 11.4.0 → 11.6.0

package/docs/ai_patterns.md

@@ -0,0 +1,374 @@
+# AI patterns — AI proposes, the human decides
+
+The AI surfaces of `@lotics/ui`: the command composer, the live run feed, the review-before-apply
+family, findings, clarification, provenance, confidence — how to compose them into a loop, which
+surface fits which outcome, the proven screen shapes, and the visual vocabulary AI output uses.
+Read this before building any AI-driven app screen. **This doc is the UI half of a pair**: the SDK
+half — declaring and running agents (`useAgentRun`, `askAi`, sessions, the authority model) — is
+[`@lotics/app-sdk` docs/ai.md](../../app-sdk/docs/ai.md); that doc feeds the data, this one renders
+it. Exact prop APIs are the shipped sources — `../src/<name>.tsx` (never guess a prop; open the
+file). Every component here is in the [catalog](./catalog.md) inventory.
+
+## The one law
+
+The AI surfaces share ONE law: the agent never commits — it **proposes**, the human
+accepts / edits / dismisses, the deterministic app applies. The agent owns judgment
+(recognition, estimation, intent→parameters); the app owns geometry, math, and the write.
+Compose the surfaces as a loop, and reach for the right one by job.
+
+## Which AI surface — decide by the OUTCOME's shape, not the task's topic
+
+Three shapes:
+
+1. **Field writes** (extract, match, rank, classify → the record changes) → **in-app agent**
+   (`useAgentRun`) + **`ChangeReview`**. The commits must obey the diff law (Keep/Drop per
+   change, app-workflow writes, bounded app authority), and the operator wants one button +
+   a review — never a prompt box.
+2. **Evidence for an in-app decision** (cross-check, audit, tie-out → nothing is written; the
+   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.
+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 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
+([`tpl_documents`](../examples/tpl_documents.tsx)).
+
+## Command / compose — `Composer`
+
+`Composer` (`@lotics/ui/composer`) is the adaptive command surface. Empty + minimal (no
+`footerRight` model picker, no `pills`, no `files`, no `children`), it's a COMPACT PILL: an
+optional `actionsButton` (attach) left, the input, a send arrow right (Enter sends, Shift+Enter
+for a newline) — the same geometry `AgentProgress` morphs into. Type past one line, or add
+files/pills/footer chrome, and it EXPANDS: the input lifts onto its own row, the `files` slot
+(`FileThumbnail`s, each `onRemove`-able) and `pills` stack above, and the buttons drop to a
+footer row. The expansion latches until the text is fully cleared — blank lines (Shift+Enter)
+keep it expanded; Send still gates on non-whitespace text.
+
+Key props (full API: `../src/composer.tsx`):
+
+| Prop | What it does |
+|---|---|
+| `onSend(text)` | Fires on Enter / the send button; clears the input. The host holds any uploaded file id itself |
+| `onStop` | With `disabled`, swaps the send button for a Stop button |
+| `sendDisabled` | Overrides the default block-on-empty-text gate — set it to allow a files-only send, or to require an attachment |
+| `value` / `onChangeText` | Optional controlled text; omit for internal state |
+| `pills` / `files` / `children` | Slots stacked above the input; any of them forces the expanded layout |
+| `actionsButton` | Attach/actions button — inline-left in the pill, footer-left expanded |
+| `footerRight` | Footer-right content before Send (a model picker); forces expanded |
+| `maxLines` | Expanded growth cap before the input scrolls (default 10) |
+| `sendLabel` / `stopLabel` | Accessible/tooltip labels (default English "Send"/"Stop" — pass translations) |
+| `textInputProps` | Extra `TextInput` props; a consumer `onKeyPress` runs before Enter-to-send and can `preventDefault()` to suppress it |
+
+For a run that needs a FILE + a prompt together (attach a photo, review/remove it, add a note,
+THEN send), fill `actionsButton` + the `files` slot and set `sendDisabled` so Send fires with an
+attachment and/or text. **Never auto-run an agent on attach** — attaching HOLDS the file for
+review; the human presses Send. The canvas template
+([`tpl_dieline`](../examples/tpl_dieline.tsx)) uses it this way; while running the host swaps
+`Composer` for `AgentProgress` (same pill geometry, so it reads as a morph).
+
+## Show the work — `AgentRun`
+
+`AgentRun` (`@lotics/ui/agent_run`) is a live feed of the agent's work as a TIMELINE. The prop is
+an ORDERED `items` array (`AgentRunItem`):
+
+| Item | Shape | Renders as |
+|---|---|---|
+| `{ type: "text", id, text }` | Answer prose | `Markdown`, a trailing ▍ caret on the last segment while streaming |
+| `{ type: "reasoning", id, text }` | Thinking | COLLAPSED — a muted "Thinking" row; press to reveal the Markdown |
+| `{ type: "step", id, label, status, kind?, input?, output?, errorText?, detail?, peek? }` | A tool/step call | An activity row with a status dot |
+
+Items 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. Transparent work, NEVER a bare spinner.
+
+**Progressive disclosure.** The feed shows the label + state; the detail is revealed on demand.
+A `step`'s `input`/`output` are hidden in the row but open in a press-to-reveal **peek**
+(auto-built Input / Output `JsonPanel`s). On `status: "error"` the row's dot goes amber, the
+`detail` line reads in the danger ink, and `errorText` shows in the peek's Error panel. Pass an
+explicit `peek` node to render that reveal yourself (it overrides the auto panels). `detail` is
+OPTIONAL — a short human summary (a count), never invented prose or raw I/O (that's
+`input`/`output`).
+
+**Activity grouping.** Consecutive `step` items 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
+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.
+
+**Tool labels.** A `step` with `kind: "tool"` carries the RAW tool name (`update_records`),
+resolved via a built-in map of the platform record/document tools + an optional `labelForTool`
+override (localize THERE — the kit stays English); unknown names fall back to a prettified form.
+`stepsLabel` localizes the "{n} steps" suffix. `state` (`"streaming" | "done" | "error"`)
+defaults to `streaming` while any step is running, else `done`.
+
+Fed natively by `@lotics/app-sdk`'s `useAgentRun().items` (reasoning + per-tool I/O + state come
+for free — no hand-assembly): `<AgentRun items={run.items} state={…} />` — see
+[the SDK doc](../../app-sdk/docs/ai.md) for the hook.
+
+**Limitation:** the collapsed reasoning row's "Thinking" label and the auto peek's
+"Input"/"Output"/"Error" panel titles are currently English-only (not on the locale provider and
+not prop-overridable); `labelForTool`/`stepsLabel` localize everything else in the feed.
+
+### `AgentProgress` — the floating pill
+
+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 `items`/`state`/
+`labelForTool`/`stepsLabel`, 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 into it while running and reveals again
+when done.
+
+**Limitation:** the pill's expand/collapse accessibility labels ("Show the agent's steps" /
+"Hide the agent's steps") are currently hardcoded English.
+
+## Review before apply — ONE surface, the compound `ChangeReview` family
+
+Every "the agent proposes → the human accepts / edits / dismisses → nothing auto-applies" surface
+composes from twelve pieces in three groups (all in `@lotics/ui/change_review`; worked example:
+[`tpl_documents`](../examples/tpl_documents.tsx)).
+
+**Frame**
+
+- `ChangeReview` — context provider + stack; hairline dividers between consecutive `Change`
+  sections (and `ChangeFields` rules between fields). Changes are OPEN sections — spacing and
+  rules, never card boxes.
+- `ChangeReviewHeader` — the SECTION heading (md semibold; default title localizes to "Suggested
+  edits"). Keep it lean: never repeat the record the dialog is already about. The counter does
+  NOT live here.
+- `ChangeReviewActions` — the commit bar; pin it in the `DialogFooter`/`DrawerFooter` (or inline
+  under the list). **Keep all** sits bottom-left and presses every pending decision's own
+  `onAccept` — pass `onAcceptAll` when decisions live in host state the registry can't see
+  (field-level Keep/Drop, unresolved conflicts); it then replaces the derived handler entirely.
+  The "N of M kept" counter reads HERE beside it, never in the header (the counter renders only
+  when at least one registered entry carries `onAccept`; Keep-all renders when one does OR when
+  you pass `onAcceptAll`; `showAcceptAll={false}` hides Keep-all). Apply
+  disables below `minKept` kept (default 1 when any registered entry carries `onAccept`, else 0)
+  or via `applyDisabled` (host-level gate, ORed in); `applyLoading` marks the async write.
+  `onDiscard` puts the Discard button beside Apply. Apply is the only outcome-named button
+  (`applyLabel`).
+
+**Sections**
+
+- `Change` — one proposed change: `id` (registers in the review context — the counter, Keep-all
+  and the apply gate derive from registered ids), controlled `status`
+  (`"pending" | "accepted" | "rejected"`), `onAccept`/`onReject`/`onUndo`, heading + free body +
+  optional verbs + collapse. Omit both callbacks for a **display-only** entry (a finding inside a
+  review). Decided → collapses to the `ChangeSummary` child (falls back to the body) behind a
+  status mark + Undo. `acceptDisabled` gates Keep on a precondition.
+- `ChangeLabel` — the change's SUBJECT heading; a stack of changes skims by subject.
+- `ChangeSummary` — the collapsed row's one-line content after a decision.
+- `ChangeReasoning` — the agent's quiet hairline-ruled aside (muted text behind a left rule) —
+  only when the change is not self-explanatory.
+
+**The grammar**
+
+- **`ChangeFields` + `ChangeField`** — THE field unit. `ChangeFields` is the OPEN form (the
+  section IS the record — an extract dialog's one order: no card chrome), stacking `ChangeField`s
+  with hairline rules. A diff-form `ChangeField` renders, top to bottom: the label (sm medium,
+  **full colour** — it names the subject of a decision, never `DetailRow`'s muted ink) · the
+  field's `reasoning` directly under the label · the `−` band when replacing (`before`) · the
+  value — `ChangeValueInput` when `onChangeText` is given (the green `+` band; pressing it edits
+  IN THE BAND — a borderless input with identical type metrics, so nothing shifts), the read-only
+  `+` band when `valueReadOnly` or no `onChangeText` (muted `placeholder` while empty), or any
+  input via `children` — compose `<ChangeValueInput unit="pcs" …>` there yourself for a unit
+  suffix (`unit` fixes the suffix outside the editable core — type the number, never the unit;
+  the built-in default doesn't take it) · conflict `candidates` as full-width decision rows
+  (picked via `onPickCandidate`) + the localized "Type another value" third option
+  (`customValue`/`customSelected`/`onCustomValue`/`onCustomSelect`; the outcome band is read-only
+  via `valueReadOnly` — the decision comes from picking, never from editing the band; gate with
+  `keepDisabled`) · per-field **Keep/Drop** bottom-right
+  (`status: "pending" | "kept" | "dropped"`, `onKeep`/`onDrop`/`onUndo`). A pure REMOVAL is
+  `before` with no value — the `−` band alone. A decided field collapses to the compact one-row
+  card (mark · label → `summary` · Undo). A field with no diff and no decision is the plain
+  inline label · value row — this form borrows `DetailRow`'s *metrics* (130px label column /
+  40px row) — press-to-edit when `onChangeText` is given.
+
+  **Limitation:** `ChangeFieldCandidate.source` and `.description` are accepted by the type but
+  the built-in candidate row currently renders only the `value` (plus `selected`). Fold a short
+  qualifier into the value string, or compose your own rows; provenance belongs in `Sources` at
+  the review's bottom anyway.
+
+- **`ChangeRecord`** — THE item card for SETS of records (order lines): `id` (registers in the
+  review context like a `Change`), `tone` `"add" | "edit" | "remove"`, the tinted header band
+  with the localized op word (Add / Edit / Delete — the `changeReview` locale slice) + `title`,
+  body = its `ChangeField`s, required `summary` for the collapsed row. **The verb level follows
+  the decision level**: add/remove carry ONE card Keep/Drop (fields none — editable parts, one
+  write); edit carries NO card verbs (only its changed fields, each deciding for itself —
+  dropping a field narrows the update diff).
+- **`ChangeBand`** — the raw diff band (aligned `+`/`−` marker column, light emerald/red, dark
+  text) every piece builds from; reach for it directly for custom strokes (a removed record's
+  one-line summary). String content is UNCLAMPED by default (`numberOfLines` to clamp) — a
+  review must show the whole value being decided.
+- **`ChangeValueInput`** — the proposed value as a proper diff at rest (the green `+` line) that
+  becomes a real input on press; rest and edit share one height, so nothing shifts.
+
+**The scaling boundary (known, deliberate)**: `ChangeFields` + `ChangeRecord` cards cover one
+record through ~10; a BULK review (30+ imported rows — a bank statement, a spreadsheet import)
+needs a dense form that does not exist yet — design it against the first real migration, not
+speculatively.
+
+**The laws**: ONE verb pair everywhere — Keep/Drop, localized through the `changeReview` locale
+slice (en: Keep / Drop / Keep all / Apply / Discard / Undo); never rename per shape (Apply is the
+only outcome-named button; `acceptLabel`/`rejectLabel` exist but are not a license to invent
+verbs). Candidate rows carry the VALUE only; provenance = `Sources` at the VERY bottom of the
+review (after every change; or omit it — lean beats decorated). The HOST owns every decision in
+plain `useState` (controlled `status` everywhere); the family owns the mechanics (collapse +
+Undo, the counter, Keep-all, apply gating). Never apply a field with no value — gate unresolved
+conflicts (`keepDisabled`, `applyDisabled`). Editing IS the review.
+
+## Ask back — `Clarify`
+
+`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`,
+`options` (`{ label, value, description? }` — a `ChoiceList`), `onAnswer(value)` resumes the run,
+and the controlled `answer` keeps the pick switchable until committed.
+
+**Limitation:** the "Question" eyebrow above the prompt is currently hardcoded English (no label
+prop, not on the locale provider).
+
+## Provenance — `Sources`
+
+`Sources` (`@lotics/ui/sources`): openable chips saying where the output came FROM, under any
+answer / summary / extracted value. Makes AI output verifiable — show it on anything produced
+from data the agent read. Each `SourceRef` is `{ id, label, kind?, detail? }` — `detail` is a
+locator after the label ("page 2", a record code). Kinds carry recognizable glyph + colour:
+
+| `kind` | Glyph | Colour |
+|---|---|---|
+| `document` (the default) | file-text | red |
+| `table` | table-2 | emerald |
+| `record` | box | blue |
+| `knowledge` | book-open | amber |
+| `web` | globe | sky |
+
+`label` sets the eyebrow above the chips (default "Sources" — English; pass a translation), or
+`label={null}` for chips only — the form used INSIDE a `Change` or a `Finding`. Pass `onOpen` to
+make each chip pressable (hover wash + an open glyph); the host does the navigation. An empty
+list renders nothing.
+
+## Confidence — `Confidence`
+
+`Confidence` (`@lotics/ui/confidence`): how sure the AI is — a 3-tick meter + the full level
+phrase ("High confidence" / "Medium confidence" / "Low confidence"), emerald / amber / zinc by
+level (low is *unsure*, not an error). Pass `level` (`"high" | "medium" | "low"`) or a 0–1
+`score` (≥ 0.8 high · ≥ 0.5 medium · else low; neither given defaults to medium). Phrases resolve
+prop `labels` → the `confidence` locale slice → English — one phrase per level, so it translates
+cleanly. The human weights an AI proposal by it; pair with `ChangeReview`.
+
+## 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: severity dot-badge + localized word ·
+`title` · `detail` · the PROMINENT `metric` (lg semibold, never a side note) + `metricCaption` ·
+`Sources` chips at the bottom (`sources`/`onOpenSource`), with a `children` slot between body and
+sources. Severity → colour: `critical` red · `warning` amber · `info` zinc ("Note") · `positive`
+emerald ("On track"); words come from the `finding` locale slice. **Display-only**: a finding
+informs the action the human takes in the app; it decides nothing itself — no phantom "record
+verdict" write (a persisted check-status goes stale on the next edit). Stack several most-severe
+first — inside a `ChangeReview` wrap each in a display-only `Change` (the family's dividers
+apply). `FindingComparison` is the expected-vs-actual body: each disagreeing side a labeled row
+(source · value), a hairline, then the DELTA emphasized — compose it as the finding's children
+for any one-value-disagrees insight (quantities, totals, dates).
+
+## Session, not chat
+
+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
+and history reads are the SDK's: `sessionId` on each run, `useAgentRuns` for the history — see
+[the SDK doc](../../app-sdk/docs/ai.md).
+
+## Five proven shapes
+
+Five shapes prove the range. **One PRODUCES** — a living artifact the user shapes over time.
+(The other producing outcomes — a conversation, generated prose, an edited document — are the
+chat handoff, shape 3 of
+[the decision table](#which-ai-surface--decide-by-the-outcomes-shape-not-the-tasks-topic);
+the chat harness owns them.)
+
+- **Canvas** ([`tpl_dieline`](../examples/tpl_dieline.tsx)) — the page IS the design on a
+  pannable/zoomable surface: it stays CENTRED at every zoom (a floating zoom pill bottom-left),
+  the FLOATING composer at the bottom (a `Composer`: attach a photo → review/remove it → add a
+  note → send, with `sendDisabled` allowing a file-and/or-text submit — NOT auto-run on attach)
+  morphs into `AgentProgress` while running, and a pinned PARAMS PANEL (a label/value field-card
+  in live-edit mode, carrying the single Download; minimizes to a pill) floats centre-right.
+  Panel, zoom pill and composer float ON TOP — they never shift the design. (Floating layers use
+  a `pointerEvents: "none"` wrapper with the interactive child set `"auto"`; RN-Web ignores
+  `"box-none"` in style, so a full-width wrapper would otherwise eat clicks on the canvas behind
+  it.) Change the design by prompt ("5 mm taller") OR by editing a param directly — either
+  re-flows it in place. For a design/document the user shapes over time.
+
+The other four output STRUCTURE — when the answer is a panel of facts, a queue of decisions, or a
+ranked set, don't cram it into chat prose:
+
+- **Answer desk** ([`tpl_lookup`](../examples/tpl_lookup.tsx)) — describe the goods on the LEFT →
+  the agent RANKS the matching codes (nearest matches, the top one Recommended) → pick one and
+  its STRUCTURED answer pins on the RIGHT (a verdict header + an exact breakdown + the policies +
+  sources). Input → matches → pick, NOT a single confident verdict: classification is ambiguous,
+  so the alternatives are first-class and picking a different one changes the outcome; refining
+  the description re-ranks. For look-up-and-explain: tariff/classification codes, fee lookup,
+  policy Q&A, a spec/compliance desk. (NOT a chat with the answer in a bubble.)
+- **Document desk** ([`tpl_documents`](../examples/tpl_documents.tsx) — THE go-to for
+  document-driven records) — the record's files block feeds ONE "Use AI" entry that FORKS into
+  the two document tasks, each a specialized run with a task-pure result: **Extract** (files
+  read → fields already matching fold into one quiet line → every add / update / conflict a
+  `ChangeField` (the `−` band · the editable value · candidate rows), the record's current value
+  a first-class choice — plus proposed new lines as record-body `Change`s → one outcome-named
+  `ChangeReviewActions` commit) and **Cross-check** (documents compared against the record and
+  each other → ranked `Finding`s — severity · title · the prominent metric · sources — separated
+  by hairlines; the findings ARE the outcome the human acts on). The fork carries an OPTIONAL
+  instructions field — the user steers what the agent checks or extracts, so `Finding` serves ANY
+  file-based AI request, not just the stock cross-check. Every file list in the flow opens the
+  full-page `FileGalleryModal`. Plus **Create documents**: a readiness checklist (unchecked by
+  default, missing inputs called out) → generate → the files land back on the record. Never merge
+  the two AI tasks into one mixed output — the fork is the design.
+- **Triage** — an inbox the agent classified + routed is a `ChangeReview` of `Change`s (body: the
+  item + the agent's call; the standard Keep/Drop verbs; Keep-all covers the high-confidence
+  sweep). Leads, tickets, documents, emails.
+- **Compare / ranked pick** — one `ChangeField` whose `candidates` carry the ranked options; the
+  human picks one. Quotes, carriers, suppliers, plans. (Fold the score/reason into each
+  candidate's value string — see the candidate-row limitation above.)
+
+## The visual vocabulary — functional colour, no gimmicks
+
+The AI vocabulary has **no purple accent and no gimmick glyphs** (no sparkles) — but it is NOT
+monochrome: **colour is used where it carries meaning, not for decoration.** What the violet
+sparkle used to carry now reads structurally — **provenance** is a quiet sentence-case microlabel
+naming the artifact ("Proposed" · "Match" · "Mismatch" · "Suggested edit" · "Question" — xs,
+muted, medium; all-caps is banned kit-wide), and the agent's **reasoning** is a left-ruled margin
+note (a hairline rule + muted text — `ChangeReasoning`), quoted apart from the facts and the
+human's controls — while **status/severity/diffs use functional colour** the way the rest of the
+kit does:
+
+- **Confidence** — the 3-tick meter + the full phrase, emerald / amber / zinc by level.
+- **Stepper / AgentRun nodes** — progress dots on a spine: `current` a **pulsing accent ring**
+  (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).
+- **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.
+
+Card chrome (borders, microlabels) stays neutral — colour marks the *state*, never the container.
+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
+affordances.