@lotics/ui 7.19.3 → 9.0.0

package/AGENTS.md

@@ -75,12 +75,12 @@ Pick by capability, not by name. (→ the source file for the API.)
   `InlineNumberInput` · `InlineSelect` · `InlineMemberSelect` · `InlineDatePicker` ·
   `InlineTimePicker`; a READ-ONLY field in that same column uses `InlineStatic` (matches the
   editor box exactly, no input chrome, so it aligns pixel-for-pixel) (see §Data entry).
-- **Tasks / to-dos** — there is NO Task component (a task row varies too much app-to-app to abstract
-  well — a Reminders row and a Linear column-grid share almost nothing). Compose the row directly:
-  `CheckCircle` (the completion ring — fills with a spring, distinct from the square `Checkbox`) + an
-  inline-editable title (`InlineTextInput` with `struck` for done) + whatever meta cells you add
-  (`OptionBadge` dot tags, `InlineDatePicker`, `InlineMemberSelect`). The one reusable primitive is
-  `CheckCircle`; the rest is composition — see `tpl_tasks` (quick list) and `tpl_task_board` (columns).
+- **Tasks / to-dos — pick by ALTITUDE.** A task-management PAGE (many tasks, grouping, filters,
+  expandable rows) is COMPOSITION — there is NO Task component (a Reminders row and a Linear
+  column-grid share almost nothing): `CheckCircle` + a struck `InlineTextInput` + your meta cells;
+  see `tpl_tasks` (quick list) and `tpl_task_board` (columns). A record's own small CHECKLIST
+  (the 5–8 tasks living in a drawer/section) is the `Checklist`/`ChecklistRow` compound +
+  `SuggestionChip` commons + `CaptureRow` — see `tpl_record`/`tpl_item_list`.
 - **Tabular data — pick by SCALE + intent.** Two columnar shapes, and the choice is about data size:
   - **High-volume register** (thousands+ you BROWSE) — `Table` (columns defined once; sortable
     headers via `SortHeader`; paired with `Pagination`) + read-only rows that open a `Drawer` to edit.
@@ -100,7 +100,9 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **Numbers & charts** — `KPIStrip` (the dashboard stat band) · `SummaryLine` (the light inline
   register/list summary — below the toolbar, from the filtered rows) · `KPICard` / `Metric` (headline figures), `TrendChip`
   (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG set — no
-  recharts), `RingGauge`, `ProgressBar` / `StackedProgressBar` / `StepProgress`, `Breakdown`
+  recharts), `RingGauge`, `ProgressBar` (its `compact` prop = ONE row, track + a plain sm
+  tabular count beside it — the cell/heading/peek-trigger meter; a caption floating above a
+  tiny bar reads misaligned) / `StackedProgressBar` / `StepProgress`, `Breakdown`
   (a stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
   "Show N more" toggle — `labels` to localize — so several facet cards align to one height in a row),
   `Funnel` (a CONVERSION funnel — ordered stages as bars that NARROW; the step conversion rate is the
@@ -153,18 +155,22 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **AI surfaces** — `Composer` (the adaptive command/chat composer — a compact pill when empty that
   expands for long text + attachments; the surface that triggers agent work),
   `AgentRun` (the live streaming work feed) + `AgentProgress` (its compact, floating, expandable
-  form — a composer's "working" state), `ReviewCard` (THE single-proposal review card — compositional
-  body via `children`: a `RecordFields` record (header-first) or a `MatchSides` pairing (body-first))
-  + `Confidence`; `ChangeReview` (the BATCH review list — whole-set OR 1-by-1; compositional via
-  `renderItem`, with `ChangeDiff` for the before→after body) + `ChangeReviewActions` (its commit bar,
-  pinned by the host in a `DialogFooter`/`DrawerFooter` or inline),
+  form — a composer's "working" state) + `Confidence`;
+  **`ChangeReview` — THE one review-before-apply surface, a COMPOUND family** (frame: `ChangeReview`
+  · `ChangeReviewHeader` · `ChangeReviewActions`; sections: `Change` · `ChangeLabel` ·
+  `ChangeSummary` · `ChangeReasoning`; the grammar: `ChangeFields` + `ChangeField` ·
+  `ChangeRecord` · `ChangeBand` + `ChangeValueInput`): adds, updates, removals, conflicts, whole
+  records, display-only findings are all compositions — see §AI workflows for the laws;
   `Clarify` (the agent asks back — selectable `ChoiceList` options),
-  `Sources` (provenance chips for AI output). For STRUCTURED AI output the review
-  surfaces above don't cover: `SpecList` (the "exact breakdown" — a labeled-value spec sheet, the
-  panel of an answer),
-  `Finding` (one ranked briefing/audit insight — severity + metric + sources + action), `Discrepancy`
-  (a field whose value disagrees across sources — pick the truth), `TriageRow` (an incoming item the
-  agent classified + routed), `ScoredOption` (an AI-ranked candidate — score + rationale + specs).
+  `Sources` (provenance chips for AI output — at review scale, `label={null}` slots the chips at a
+  section's bottom), `Finding` (one ranked insight from an AI check — localized severity word ·
+  title · detail · `Sources` chips · a `children` slot; **`FindingComparison`** is the
+  expected-vs-actual body: each disagreeing side a labeled row, the DELTA emphasized under a
+  hairline (localized "Difference") — quantities, totals, dates; a plain `metric` prop remains for
+  one-number findings. The children slot composes ANY visual result — a compact `Table` for
+  per-line detail (danger color on the offending cells), `ProgressBar` for
+  consumption-toward-a-cliff (free time, credit), dot `Badge`s for a present/missing checklist,
+  `Confidence` for judgment calls — the AI-page demos show each. Display-only — it informs the verdict the host records; `finding` slice).
   See §AI workflows.
 
 ---
@@ -176,15 +182,15 @@ This is the most common thing to get right. Match the JOB to the pattern:
 | You're capturing… | Reach for | Why |
 |---|---|---|
 | an EXISTING record's fields | **Inline edit** (`Inline*`) | edit in place, no form mode |
-| a brand-NEW record (a form) | **fieldset form** (`FormField` + the 2-col grid) | structured entry + a Save |
+| a brand-NEW record | **create-then-refine** (`tpl_record`: "New" is ONE CLICK → a fresh Draft; everything refines in place on the record surface) | nobody fills 5 sections in one sitting; the surface is the editor |
 | a RELATED record (pick or make) | **find-or-create** (`Combobox allowCustom`) | one control covers both |
 | REPEATING rows you build & revise | **line items** (create→preview→edit) | add / edit / remove, live totals |
-| CHARGES that bill onto documents | **billing** (`tpl_billing`) | the invoice document is the unit |
+| CHARGES that bill onto documents | **billing** (`tpl_record` Billing section) | the invoice document is the unit |
+| a record's FEE/charge SUMMARY | **`Ledger`** (worked example: `tpl_item_list` drawer) | LedgerGroup (label + sum) → LedgerRow (label · meta · ONE right tabular money column; `peek` makes the row a door to its PARTICULARS in an anchored popover — references live inside the peek; `reference` = a trailing link on a non-peek row) → LedgerTotal (divider-set emphasized close, `zeroLabel` for the settled state). Pair with a Record-payment POPOVER that appends a receipt. No bars/charts |
 | a multi-value TAG field | **`Select multi`** (`renderSelected` → `Chip`) | chips composed, not a separate control |
 | ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker`) | required single-select, one tap, every option visible |
 | a STATUS with terminal outcomes | **disposition** (open → resolve → revise) | guides the decision |
 | FILES | **attachment field** (dropzone + grid + gallery) | add / preview / delete |
-| many entries FAST | **quick capture** (one row, Enter to add) | repeat-entry speed |
 | a state TRANSITION mid-flow | **stage gate** (popover / dialog by weight) | right-sized friction |
 
 ### Inline edit — the preferred way to edit an existing record
@@ -196,19 +202,33 @@ reflow, the whole point), and it commits on blur (Enter saves, Escape reverts) o
 (`format` for currency/units) · `InlineSelect` (plain options OR `renderOptionContent`; floats an
 `OptionList` in a popover so the row never grows; the RESTING value renders like its option
 (`renderOptionContent` by default; `renderSelected` overrides) — a colored `OptionBadge`, not just a label) · `InlineMemberSelect` (a `MemberChip` at rest →
-member picker; the inline twin of `MemberSelect`) · `InlineDatePicker` (`format="datetime"` for
+member picker; the inline twin of `MemberSelect`; worked example: `tpl_record`'s "Sales owner" fact) · `InlineDatePicker` (`format="datetime"` for
 always-on time; `optionalTime` to let the user ADD/REMOVE a time — the value's own shape, date vs
-datetime, is the source of truth) · `InlineTimePicker` — all
+datetime, is the source of truth) · `InlineTimePicker` · `InlineTagSelect` (the MULTI member —
+a tag SET in the inline vocabulary: selected tags render as badges inside the standard chip,
+clicking floats a multi `OptionList` (checkbox rows), CLOSING commits the new set in one
+`onSave` — never a borderless `Select` posing as an inline field) — all
 on `useInlineEdit` + `InlineEditView` (custom inputs join via those). `onSave` is async: the
 saving spinner sits INSIDE the control (never a sibling — that reflows); an error shows inline
-without losing the edit. Pair with `DetailRow` (label left, inline value right). A READ-ONLY value
-in the same column — a computed total, a system ID, a synced/locked field — is `InlineStatic`: it
-copies the editor box exactly (height, padding, 1px transparent border) but is non-interactive, so
-it sits FLUSH with the editors instead of reading as a disabled input. To hang a right-side
-action/badge/unit off a row, use `DetailRow`'s `trailing` slot (wrap the editor in a `flex:1` View
-so it takes the slack and the trailing pins right) — see the "Row anatomy" section of
-`tpl_record_plain`, which also reads top→bottom as a full drawer record (header → fields →
-`DangerZone`). Not every field is a same-height swap — a tag field, a status, or an attachment grid
+without losing the edit. A STACK of rows lives in a `DetailTable` (label ·
+value · trailing laid out like a TABLE: `labelWidth` / `trailingWidth` /
+`minHeight` set ONCE on the parent, plus the 6px row gap the zinc-50 chips
+need) holding `DetailRow`s — set `trailingWidth` when ANY row carries a
+trailing action/badge, so EVERY row reserves the column and one row's
+`Copy` button never makes its editor narrower than its neighbours'. An editor AT REST sits
+on a zinc-50 chip — THE editability affordance: users see what's editable without hovering.
+`background="transparent"` opts a field out of the chip — for DENSE, uniformly-editable
+surfaces (a task list/board where EVERY cell edits: the chip repeated everywhere is noise and
+distinguishes nothing; hover/focus still reveal the input). Keep the chip wherever editable and
+static values MIX. A `disabled` editor rests FLAT automatically — the chip is the editability
+promise, and an inert field must not make it. A
+READ-ONLY value in the same column — a computed total, a system ID, a synced/locked field — is
+`InlineStatic`: it copies the editor box metrics exactly (height, padding, 1px transparent border)
+but stays FLAT and non-interactive, so editable (chip) vs read-only (flat) is legible at a glance
+and the static value never reads as a disabled input. To hang a right-side
+action/badge off a row, use `DetailRow`'s `trailing` slot (NOT for units — "kg"/"₫" belong IN the value via `InlineNumberInput format`) — see the "Details"
+`DetailTable` of `tpl_record`, which also reads top→bottom as a full record surface
+(header → fields → `DangerZone`). Not every field is a same-height swap — a tag field, a status, or an attachment grid
 edit in place too (below).
 
 ### Fieldset form — fields lay out on a RESPONSIVE two-column grid
@@ -246,8 +266,11 @@ the chevron shows while the field is empty and a clear ✕ replaces it once ther
 pressing ✕ clears the text and reopens the full-browse list, so `onClear` lands back on the whole
 set (on focus an empty field already browses everything — `recentOptions ?? all`). `allowCustom` appends a "Create …" row (`customOptionLabel`) when the query
 matches no option, emitting the typed text as the value — so a value not in the known set means
-CREATE. Wire that branch to a create overlay (a modal `Dialog` for 4+ fields, an anchored popover
-for 1–3) that builds the new record and attaches it; existing matches attach directly. The create
+CREATE. Wire that branch to a create overlay (an anchored popover for a 1–2 field gate, a modal
+`Dialog` for 3+) that builds the new record and attaches it; existing matches attach directly.
+A record-CREATION dialog stays a MINIMAL gate and really creates — the row lands and its own
+workspace opens for refinement (an EMPTY checklist, commons as ghosts). NEVER a creation
+wizard: create-then-refine puts complexity on the record surface, not in front of it. The create
 row sits BELOW matches by default (the keyboard highlight lands on the first MATCH, so Enter on a
 partial picks it, never a duplicate); pass `customOptionPlacement="top"` to pin it above. Use
 `reflectSelection={false}` and render the attached record below as a card with a Change action.
@@ -267,12 +290,61 @@ snapshot the item on Edit so Cancel reverts, or DISCARDS a freshly-added one. Du
 the destructive **Delete is `danger-secondary`**; Cancel + the Save/Edit toggle sit right. Every
 screen composes its own (~15 lines) so the preview rows + form fit the data.
 
-### Billing & invoicing — the invoice DOCUMENT is the unit (`tpl_billing`)
+### Handoff — a stage transition, never a message
+When work crosses departments (sales → operations → accounting), the HANDOFF is the RECORD
+changing desks — never an inbox, a notification, or a copied task. Two types:
+**(A) Same entity** → a STAGE field on the shared record: sections carry OWNER dot tags, and
+the handoff is MANAGED AS TASKS — each desk's checklist on the record (the task-row vocabulary:
+sibling `CheckCircle` + struck transparent `InlineTextInput` + per-task `InlineMemberSelect`
+assignees + the `CaptureRow` add-affordance — never a decorative progress strip). A NEW record
+starts with an EMPTY checklist — tasks truly vary. The commons split in two: MANDATORY tasks are
+seeded by the app (a workflow on create, per record type) — no human types them; common-but-
+OPTIONAL tasks appear as `SuggestionChip`s under the list — a PILL, never a row,
+so a suggestion can't be mistaken for a task (tap = materialize, ✕ = dismiss for this record;
+already-present labels filter out; suggestions never count in done/total and pause while a
+filter narrows the view) — the same suggestion grammar as the
+billing Standard pill. Real rows carry a ⋯ `menu` (an `ActionMenu`; Delete lives BEHIND it, danger-styled and last — never a bare ✕ a stray tap can hit), completing the checklist's CRUD. Open
+tasks INFORM
+the handoff, they NEVER block it: the CTA stays enabled, the count warns, and open tasks carry
+over. The handoff CTA opens a DIALOG for the receiving desk (assignee `MemberSelect` + an
+optional note; the open-task warning inside); confirming closes the drawer — the record left
+this register. Tasks PEEK from the register: the done/total column is a pressable
+compact-`ProgressBar` trigger whose popover holds the checklist on FIXED columns — every row
+ring · struck `InlineTextInput` title (flex) · quick-reassign `InlineMemberSelect` (140) — no
+expandable rows (tags/files depth is the Task list template's lesson, not the peek's); the
+popover body is `PopoverContent`'s own ScrollView (`disableBodyScroll` is ONLY for children
+that manage their own scroll, like `OptionList`). The DRAWER carries a real Tasks SECTION in
+the Record template's shape (heading + the compact meter + the same checklist) — one shared
+task state per record feeds the column, the peek, the section, and the handoff dialog;
+a section owned by a later desk sits visible but GATED ("Billing opens when the record reaches
+Accounting"). Registers scope by stage — the receiving department's register IS its inbox. The
+sender's sections stay editable after handoff (the gate transfers RESPONSIBILITY, not access —
+locking is app IAM, not template grammar). Worked example: `tpl_record`.
+**(B) Different entity** (a deal → a shipment) → SPAWN-AND-LINK: the upstream record's terminal
+gate CREATES the downstream record on the shared spine, linked both ways (a linked-record row
+each side); usually TWO apps — the upstream closes its own lifecycle, the downstream starts
+fresh in its department's app. Never merge the two lifecycles into one record.
+
+### Sequential phases on one record + the outline rail
+When a record's work happens in ORDERED PHASES (gate in → gate out; receive → dispatch), the
+phases are NOT tabs or a segmented control — hiding the other phase loses the context the
+current one needs and buries why its gate is blocked. Both phase sections sit on ONE page in
+chronological order; each phase owns ITS OWN fee rows + phase total (the invoice-band idea one
+level up — money never reads as one pot); each closes with a SEQUENTIAL confirm gate that names
+its blockers ("Confirm gate in first."). The header status chip carries the phase. A LONG record
+surface pairs with a LEFT OUTLINE RAIL — `MenuButton` items + `useSectionNav` (scroll-spy: jump
+to a section, the highlight follows the scroll); on narrow containers the rail becomes a
+PINNED bar naming the current section that opens a full-page section-picker `Modal`. A per-phase
+dot on a rail item carries its confirmed state. A direction that is a TYPE (one record per gate
+EVENT) is instead a discriminator chosen ONCE at creation — a `SegmentedControl` in the create
+step, never a toggle on the record.
+
+### Billing — the invoice DOCUMENT is the unit (`tpl_record` Billing section)
 When charges get grouped into issuable documents (an e-invoice, a bill) and then collected, don't
 split the screen into "enter fees here, issue there" — that smears one job across two places. Make
-**each invoice a `Card` that holds its own editable charge lines** (amount input + payment method),
-its **live total**, its **status badge** (nothing-to-bill · draft · issued + ref), and its **issue
-action** in the footer. A charge never lives apart from the document it bills on. Issuing is gated
+**each invoice a FLAT hairline-set band that holds its own editable charge lines** (amount input +
+payment method), its **live total**, its **status badge** (nothing-to-bill · draft · issued + ref),
+and its **issue action** in its closing row — no card chrome; Data-capture templates are flat. A charge never lives apart from the document it bills on. Issuing is gated
 **inline, never a dead end**: when a prerequisite is missing (a bill-to tax ID, a method on a
 charged line) the issue button disables with one muted line saying what's needed; the payment-method
 picker turns required the instant a line carries an amount. Issuing a real e-invoice is irreversible
@@ -383,12 +455,6 @@ copy stay local):
   NEW blob for re-upload (`useImageRotation` is view-only; this is how a rotation is persisted). Pair with
   `FileGalleryModal`'s `onPersistRotation`/`persisting` (the ✓ shown on a rotated image).
 
-### Quick capture — the SPEED surface
-For fast repeat entry (logging activity, expenses), one compact capture row (a `SegmentedControl`
-mode, a `Combobox`-as-select, a `Counter`, an Enter-to-submit `TextInputField`); each entry commits
-on its own into an undoable log below, the field keeps focus and the prior choices carry over. No
-screen-wide Save.
-
 ### Stage gates — tiered by weight
 A transition that needs NO input is one click. 1–3 quick fields → a POPOVER FORM anchored to its
 action button (title + one-line stake + `FormField`s; confirm in `PopoverFooter`). A
@@ -406,6 +472,27 @@ accepts / edits / dismisses, the deterministic app applies. The agent owns judgm
 (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`). 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.
+
 - **Command / compose** — `Composer`, the adaptive command surface. Empty + minimal (no `footerRight`
   model picker, no `pills`, no `files`), 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
@@ -439,28 +526,47 @@ Compose the surfaces as a loop, and reach for the right one by job:
   free — no hand-assembly). Transparent work, NEVER a bare spinner. On a canvas/composer app reach for
   `AgentProgress` — `AgentRun` collapsed into a floating pill (avatar + current step) that EXPANDS on
   press; the composer morphs into it while running, and reveals again when done.
-- **Review before apply — ONE card + the batch engine, the BODY is compositional.** Every "the agent
-  proposes → the human accepts / edits / dismisses → nothing auto-applies" surface wears the same
-  `reviewCardStyle` + an optional `Confidence`. There are two primitives:
-  - **`ReviewCard`** — THE single-proposal review card. It owns the chrome (eyebrow + `Confidence`,
-    rationale, a generic `actions` footer — Accept/Edit/Dismiss, Confirm/Remove, Accept/Reassign,
-    whatever the verbs are — and a collapse-to-a-row resolved state); the BODY is `children`. **Layout
-    follows the props**: give it an `eyebrow`/`title` and the chrome LEADS (header-first — a value or
-    record proposal, e.g. a `RecordFields` → `tpl_extract`); give it only `children` and the BODY leads,
-    the confidence + reason beneath it (body-first — a `MatchSides` pairing where the link is the hero
-    → `tpl_match`). Stack several (rank by confidence) for a shortlist or a document's records.
-  - **`ChangeReview`** — THE batch engine for a SET you decide each then commit together. `renderItem`
-    draws each proposal (a `ChangeDiff` before→after body, a record, an editable form), 1-by-1
-    Keep/Drop collapses each (e.g. ingested rate lines — `tpl_ratedesk`); whole-set mode reviews the
-    lot. It is the LIST only — the commit bar (Accept all / Apply / Discard) is the SEPARATE
-    **`ChangeReviewActions`**, which the host places where commit bars belong (a `DialogFooter` /
-    `DrawerFooter`, or inline under the list). Don't bundle a commit into a scroll body — like every
-    other footer in the kit it's the container's to pin (`tpl_ratedesk` puts it in the `DialogFooter`).
-    `ChangeReviewActions` reads the same `items`/`statusOf`, so it owns Accept-all + the kept count —
-    never re-derive them in the host.
-  The body atoms (`RecordFields`, `MatchSides`, `ChangeDiff`) are pure presentation — usable inside
-  either engine OR standalone (a live-edit field card). The decide / accept-all / apply mechanics are
-  never re-implemented per surface.
+- **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. **Frame**: `ChangeReview` (context provider + stack; hairline
+  dividers between `Change` sections — and `ChangeFields` rules between fields) ·
+  `ChangeReviewHeader` (the SECTION heading — md semibold; keep it lean: never repeat the record
+  the dialog is already about) · `ChangeReviewActions` (the commit bar — pin it in the
+  `DialogFooter`/`DrawerFooter`; **Keep all** bottom-left presses every pending decision — pass
+  `onAcceptAll` when field state lives in the host; the "N of M kept" counter reads HERE beside it,
+  never in the header; Apply disables at 0 kept or via `applyDisabled`). **Sections**: `Change`
+  (heading + free body + optional verbs + collapse — omit both callbacks for display-only) ·
+  `ChangeLabel` · `ChangeSummary` (the collapsed row's content) · `ChangeReasoning` (the agent's
+  quiet hairline aside — only when 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). Each `ChangeField`:
+    label (sm, muted — the DetailRow convention) · the `−` band when replacing (`before`) · the value — `ChangeValueInput`
+    by default (the green `+` band; pressing it edits IN THE BAND — a borderless input with
+    identical type metrics, so nothing shifts; `unit="pcs"` fixes the suffix outside the editable
+    core — type the number, never the unit) or any input · conflict `candidates` as full-width decision rows + the localized
+    "Type another value" third option (`custom*` props; the outcome band is read-only via
+    `valueReadOnly` — the decision comes from picking, never from editing the band; gate with
+    `keepDisabled`) · row `reasoning` LAST · per-field **Keep/Drop** bottom-right
+    (`status`/`onKeep`/`onDrop`/`onUndo`). A pure REMOVAL is `before` with an empty value — the
+    `−` band alone. A decided field collapses to the compact one-row card (mark · label →
+    `summary` · Undo).
+  - **`ChangeRecord`** — THE item card for SETS of records (order lines): `id` (it registers in
+    the review context like a `Change`), `tone` add/edit/remove, the tinted header band with the
+    localized op word (Add/Edit/Delete · Thêm/Sửa/Xóa) + title, body = its `ChangeField`s, and
+    **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). Collapses via `summary`.
+  - **`ChangeBand`** — the raw diff band (aligned `+`/`−` marker column, light emerald/red, dark
+    text) every piece builds from; reach for it directly for custom strokes.
+  **The scaling boundary (known, deliberate)**: `ChangeFields` + `ChangeRecord` cards cover one
+  record through ~10; a BULK review (30+ imported rows — a bank statement, an Excel 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; never rename per shape (Apply is
+  the only outcome-named button). 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`; the family owns the
+  mechanics (collapse + Undo, the counter, Keep-all, apply gating). Never apply a field with no
+  value — gate unresolved conflicts. Editing IS the review.
 - **Ask back** — `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.
 - **Provenance** — `Sources`: openable chips saying where the output came FROM (records, a
@@ -476,54 +582,42 @@ a conversation, a single pass, or generated prose:
 - **Canvas** (`tpl_dieline`) — 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 `RecordFields` field-card
+  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.
-- **Chat** (`tpl_assistant`) — a conversation where the agent's answer carries suggested edits the
-  user approves/rejects **1-by-1** (`ChangeReview` per-item), applying only the accepted set. An AI
-  copilot that proposes changes to a record and never commits on its own.
-- **One-shot** (`tpl_extract`) — read an image → the agent extracts the records → review each as a
-  `ReviewCard` wrapping a `RecordFields` body (fields click-to-edit, Confirm collapses it to a
-  checklist row) → Save all to the table. A data-capture pass; nothing stored until confirmed.
-- **Bulk ingest desk** (`tpl_ratedesk`) — the page IS a filterable register (a From → To route picker
-  + `ColumnFilter` pills → `Card padding:0` + full-bleed `Table`), the register the hero. Updating
-  prices is ONE header CTA that opens a Dialog wizard: drop SEVERAL source docs at once → the agent
-  reads them all (`AgentRun`) → a `ChangeReview` 1-by-1 (each proposal a Keep/Drop card, New / Updated
-  with old→new delta, "Accept all" + Apply) → the kept rows land in the register. Pairs `tpl_extract`'s
-  ingest with `tpl_directory`'s register. For a maintained reference table — rate card, price list,
-  tariff, catalogue: re-ingest the source sheets beats hand-typing.
-- **Draft** (`tpl_draft`) — the agent writes a first draft from context; the OUTPUT itself streams
-  (the text fills in live), then becomes an editable surface the human refines before sending.
-  Tone/length steer it. For generated prose — a reply, a quote, a listing.
 
 The next six output STRUCTURE the first four can't — when the answer is a panel of facts, a queue of
 decisions, or a ranked set, don't cram it into chat prose. Each pairs a template with a primitive:
-- **Answer desk** (`tpl_lookup`, `SpecList`) — describe the goods on the LEFT → the agent RANKS the
+- **Answer desk** (`tpl_lookup`) — 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 duty; refining the description re-ranks. For look-up-and-explain:
   tariff/HS, fee lookup, policy Q&A, a spec/compliance desk. (NOT a chat with the answer in a bubble.)
-- **Match** (`tpl_match`, body-first `ReviewCard` + `MatchSides`) — the agent proposes PAIRINGS with
-  its reasoning; each is a `ReviewCard` (no title, so body-first) whose body is a two-sided `MatchSides`
-  pairing (source → proposed counterpart), with the confidence + reason beneath, accept / reassign /
-  reject, high-confidence batch-accept. The AI reconciliation / dedup / correlation queue. (Strip the agent's
-  reasoning and it would be a plain deterministic match register — the reasoning is the tell for when
-  you need this.)
-- **Briefing** (`tpl_briefing`, `Finding`) — a generated narrative over the data + a RANKED list of
-  what needs attention, each finding carrying a severity, a metric, its sources, and one action. The
-  leadership digest / anomaly scan — the agent's COMMENTARY, not a raw dashboard.
-- **Cross-check** (`tpl_crosscheck`, `Discrepancy`) — the agent compares the documents of one
-  transaction and surfaces every field that DISAGREES; resolve each to a source of truth or flag it.
-  The audit / 3-way-match desk. Symmetric (N sources), unlike a before→after edit.
-- **Triage** (`tpl_triage`, `TriageRow`) — an inbox the agent classified + routed; accept the call,
-  override, or dismiss, high-confidence in bulk. Leads, tickets, documents, emails.
-- **Compare** (`tpl_compare`, `ScoredOption`) — the agent SCORES and ranks options with its rationale
-  and the key specs; the human picks one. Quotes, carriers, suppliers, plans.
+
+- **Document desk** (`tpl_documents` — 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` (struck before · bordered input · candidate chips),
+  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 — no phantom "record verdict" write, a persisted check-status
+  goes stale on the next edit). 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; verbs Accept / Dismiss; Accept-all covers the high-confidence sweep).
+- **Compare / ranked pick** — one `ChangeField` whose `candidates` carry the ranked options
+  (`description` = the score/reason, `source` where it came from); the human picks one. Quotes,
+  carriers, suppliers, plans.
 
 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
@@ -533,17 +627,16 @@ a left-ruled margin note (a hairline rule + muted text), quoted apart from the f
 controls — while **status/severity/diffs use functional colour** the way the rest of the kit does:
 - **Confidence** — a 3-tick meter + the full phrase ("High confidence" / "Medium" / "Low"), emerald /
   amber / zinc by level; `labels` to translate (one phrase per level).
-- **Finding severity** — a coloured dot `Badge` + metric: red critical, amber warning, blue note,
-  emerald on-track (+ stacking order, most severe first). The badge words localize through
-  `LoticsLocaleProvider` (`locale.finding`, override per-instance via `labels`) — never hardcode them.
 - **Stepper / AgentRun nodes** — progress dots on a spine: `current` a **pulsing accent ring** (white
   centre), `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
   (`color` 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).
-- **ChangeReview diffs** — the old value struck in **red**, the new value in **green**.
-- **Discrepancy** — the agent's pick gets a **blue** highlight; `Mismatch` reads amber, `Resolved`
-  emerald.
+- **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.
 
 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
@@ -563,11 +656,14 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
     a period filter — never a summary Badge (those belong to the KPI strip).
   · **Card header** (a card's own title band, or separate banded cards): `CardHeader` +
     `CardHeaderTitle` (`sm semibold`; `info` when the title alone doesn't define the numbers).
-  · **Section title** (a substantial titled block — a form, a timeline, a field group — INSIDE one
-    multi-section card or drawer): a `Text size="sm" weight="semibold"` at the TOP of the section's
-    content, sections separated by ONE `Divider`. Do NOT wrap each section in its own `CardHeader`
-    (its auto-divider double-stacks hairlines around every title). A card-less full page uses
-    `SectionHeading` + `SectionHeadingTitle`. NEVER a bare eyebrow standing in for a section title.
+  · **Section title** — ONE construct: `Section` > `SectionHeading` > `SectionHeadingTitle`
+    (lg semibold + optional muted `description`/`info`), everything left-aligned at the column
+    edge. The `Divider` goes BETWEEN sections (page column `gap: 32`, a bare hairline separating
+    one section from the next) — NEVER directly under the heading, which orphans the title from
+    its own content. Inside a DRAWER, a full multi-section WORKSPACE uses the real
+    `SectionHeading` (lg) — its meta + CTA slots carry each section's count and action; a
+    `Text size="sm" weight="semibold"` stand-in is only for small sub-groups. Do NOT wrap each section in its own `CardHeader`, do NOT
+    hand-roll sm-semibold lead lines on a flat page. NEVER a bare eyebrow as a section title.
   · **Eyebrow / label** (`<Text size="xs" color="muted" weight="medium">` — **sentence case, NEVER
     `transform="uppercase"`**): a small quiet label above or beside content — an artifact tag
     ("Proposed", "Question", "Suggested edit"), a field name, a metric caption, a minor one-line
@@ -639,13 +735,16 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   </Card>
   ```
   Never nest cards; never hand-compose a title or footer band. `info` is standard, not garnish.
-- **Flat work execution vs carded monitoring.** A `Card` is ALWAYS a bordered, lifted container —
-  there is no "flat card". MONITORING / dashboard screens group with cards (and the `KPIStrip`
-  band). WORK-EXECUTION screens — registers, lists, the worklists an operator acts on — are FLAT:
-  the register/list sits DIRECTLY on the white canvas with no Card wrapper; separation comes from
-  the row wash, gaps, and `Divider`/`CardHeader`/`CardFooter` bands used BARE. Reach for a Card only
+- **Flat work execution & data capture vs carded monitoring.** A `Card` is ALWAYS a bordered,
+  lifted container — there is no "flat card". MONITORING / dashboard screens group with cards (and
+  the `KPIStrip` band). WORK-EXECUTION screens — registers, lists, worklists — AND **data-capture /
+  record screens (forms, wizards, billing, settings, inline records) are FLAT**: content sits
+  DIRECTLY on the white canvas with no Card wrapper; separation comes from the row wash, gaps,
+  `SectionHeading` + `Divider` rhythm. Reach for a Card only
   where a screen holds a DISTINCT region that must be told apart from another; a single register or
-  list filling the screen needs none.
+  list filling the screen needs none. ONE carve-out inside a flat form: **repeating SUB-OBJECTS
+  (line items) are each their own small Card** (`padding: 16`), so discrete items
+  read as discrete objects; hairlines between them blur into one run-on list.
 - **Summaries — two altitudes, never mixed.** A DASHBOARD opens with the boxed stat band
   `<KPIStrip items={[{label, value, trend?, caption?, tone?, info?}…]}>` (a `Card` of `KPICard`
   columns). A REGISTER/LIST (work-execution) screen instead carries a LIGHT inline
@@ -726,7 +825,9 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   `Drawer` (above). (2) **Act on many** — a flat list with a leading `CheckboxInput` per row + a
   select-all `CardHeader` band, plus a bottom-pinned `<FloatingActionBar count label onClear>`
   carrying the bulk action(s) while ≥1 row is ticked (`tpl_item_list`); a row
-  that can't take the action has NO checkbox. When a region genuinely must sit beside the list (a
+  that can't take the action has NO checkbox. Bar weight gradient, left → right: the built-in
+  Clear is muted (the quietest act), destructive bulk = `danger-secondary` + icon, secondary
+  bulk = `secondary` + icon, ONE primary CTA last — never repeat the count in a CTA title; the bar's label already carries it. When a region genuinely must sit beside the list (a
   source/remainder summary, a capacity picker) make it a TOP summary header or move it into a
   Popover/sheet at the decision point — not a standing column.
 - **One control radius** — every interactive control (`Button`, the inputs/selects/pickers,
@@ -808,13 +909,11 @@ Full worked-example screens ship in the package — **read the source at
 `node_modules/@lotics/ui/examples/<name>.tsx`** (pure `@lotics/ui` + mock data, each a usable
 recipe for a screen JOB; copy and adapt). Pick by the job:
 
-- **Monitor & decide** — `tpl_dashboard` (KPIStrip + trends + attention list) · `tpl_stock`
-  (10k-record faceted funnel) · `tpl_report` (scope-first lookup report — a header period +
-  one-of-N dimension search drives KPIs → aligned facets w/ a `maxRows` long-tail toggle →
-  paginated register → export) · `tpl_tower` (live `StatusGrid` wallboard) · `tpl_pivot` (the
+- **Analytics** — `tpl_dashboard` (KPIStrip + trends + attention list) · `tpl_stock`
+  (10k-record faceted funnel) · `tpl_tower` (live `StatusGrid` wallboard) · `tpl_pivot` (the
   `Matrix` cross-tab desk: one dimension × another, number + heat per cell + row/col/grand totals,
   press a cell to drill the list behind it) · `tpl_rollup` (hierarchical totals).
-- **Work execution** — every screen is FLAT (no Card) and ONE of two shapes: a register/list you
+- **Work** — every screen is FLAT (no Card) and ONE of two shapes: a register/list you
   WORK EACH of (press a row → workspace `Drawer`) or a list you ACT ON MANY of (tick rows →
   `FloatingActionBar`) — never a side-by-side panel. `tpl_item_list` (THE canonical register and the
   consolidated work-list: search + a status `Select` + facet `FilterChip`s LEFT, the New CTA RIGHT in
@@ -822,11 +921,46 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   carries a leading checkbox; a select-all band, footer `Pagination`, and a `FloatingActionBar` for
   the bulk action over the ticked rows; a per-row PRINT button (the trailing action column) is the
   row's primary action and the ⋯ its overflow; a row that can't take the bulk action gets a DISABLED
-  checkbox (here an "Awaiting docs" case — the same gating as a blocked run line) — a row press opens
-  the workspace `Drawer`. This ONE template subsumes the old approvals / dispatch / batch / run
+  checkbox (here an "Awaiting docs" record — the same gating as a blocked run line) — a row press opens
+  the PRODUCTION workspace `Drawer`: a Details `DetailTable` showing every inline field type
+  (text · `InlineMemberSelect` · dates incl. optional-time · dot-select · money number · the
+  `InlineTagSelect` tag field · `InlineStatic` + System badge), a LINKED CASES section (the
+  customer's other records as `ListItem`s — the aligned row compound (title + description at
+  the column edge, its own 8px outdent; badge · fee · chevron right) — pressing one PUSHES an
+  EDITABLE workspace for that record inside the drawer via the hosted `ScreenRouter`; the
+  drawer HEADER swaps to back + the pushed id, back pops with scroll preserved), a Files section with its
+  OWN Add CTA (`FileRows` CRUD via `pickFiles` + an EXPECTED document as a ghost `FileRow
+  placeholder` with a Request action), the Payment `Ledger` (peekable fee rows + the Record-payment popover), an ACTIVITY section (the CRM touch-log shape: OUTCOME PILLS — `ChipGroup`, optional, tap-to-deselect — over a MULTILINE note (the note IS the record and the one requirement), an always-visible optional Follow-up `InlineDatePicker`, an "Attach files" secondary (`pickFiles` → removable `FileThumbnailGrid` in the composer), the PRIMARY Log saying WHY when disabled; below, a labelled "History" `Timeline` of outcome-typed items, newest first — an entry's attachments ride its expandable `details` as a thumbnail grid whose press opens the shared `FileGalleryModal`), and a closing `DangerZone`. Detail rows show trailing CTAs where earned (Phone → Call, Due → Today) — the case where `trailingWidth` IS set. This ONE template subsumes the old approvals / dispatch / batch / run
   screens: register, per-row action, gated selection, and act-on-many in one) · `tpl_pick` (guided `ScanField` run — a single-focus task column with
   the pick path collapsed into an `Accordion` below) · `tpl_allocate` (`RemainderMeter` split — a
   source/remainder summary header over the invoice list + Apply) ·
+  `tpl_record` (THE record surface, create-then-refine: "New" = a small
+  dialog with the identity essentials + find-or-create → lands as a Draft; the surface IS the
+  editor — `RecordSummary` header over its key-fact `DetailTable` + a Details `DetailTable`
+  (one shared column grid, auto-stacking when narrow), a CUSTOMER section (TWO states, no
+  swap mode: attached = the read-only-first card — Edit/Done live in the SECTION HEADING and
+  swap the fields to inline chips, where a trailing Fetch fills contact + city from the
+  tax-ID registry, un-gating billing; Remove (danger) sits low and detaches the link → the
+  find-or-create search, whose custom row opens the create Dialog rendering the SAME
+  inline-chip table + Fetch), a FILES section (dropzone add, gallery preview, delete),
+  and a BILLING
+  section OWNED BY Accounting (gated until the record reaches that stage) in the INLINE vocabulary (each invoice a hairline-set band: charge amounts as chips
+  with the list price as ghost placeholder + a one-tap "Standard …" suggestion pill while
+  unset, "How paid…" select chips, NO per-band totals — the collect band owns the number; the
+  band's action row sits BOTTOM-RIGHT as hint → status dot → Issue, the hint naming exactly
+  what blocks (fees → method → the customer gate); an ISSUED invoice keeps its lines editable
+  and offers Re-issue — a new lookup code replaces the old, confirmed in the same Dialog;
+  validated receipt; separate refundable deposit) — and
+  the lifecycle is a HANDOFF CHAIN (Sales → Operations → Accounting → Closed): a TASKS section
+  speaking the FULL Task-list grammar — a clearable Group-by `FilterChip` (Desk/Assignee/Status)
+  + Assignee/Status filter chips derive the groups (empty groups drop; desk heads keep their
+  owner dots, assignee heads are `MemberChip`s), the add-a-task capture at the TOP landing on
+  the current desk, rows with per-task `InlineMemberSelect` assignees — EVERY desk's rows edit
+  (the stage gates the handoff and Billing, never task editing; planning ahead on a later desk
+  is normal work) — OWNER dot tags per section, per-stage handoff CTAs NEVER blocked (open
+  tasks warn + carry over); "New" is ONE CLICK → a fresh record at Sales; ALSO the settings shape: Preferences switch rows + `DangerZone`; a LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`)
+  jumps between the sections. Absorbed the
+  old order-form, inline-record, intake, settings, billing, and quick-capture templates) ·
   `tpl_tasks` (the QUICK LIST — Apple-Reminders shape for personal lists: `CheckCircle` rows you tick +
   expand in place to edit (`Inline*`, stable row — the meta summary never shifts on expand), colour-dot
   tags, an attachments field (`FileThumbnailGrid` → tap a tile to the gallery for download + confirmed
@@ -837,7 +971,9 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   popover grid → gallery), a **dynamic action column** (a per-row underlined action LINK driven by each
   task's `action` descriptor — attach/approve/open, each wired in a real app to its OWN workflow: one
   board, a different action per row; the link's pressable fills the cell to match the inline editors),
-  a trailing **`ActionMenu`** (the ⋯ overflow — a `danger` Remove + confirm
+  a trailing **`ActionMenu`** (the ⋯ overflow — a `danger` Remove + confirm; CUSTOM pressable
+  cells (files, the action link) hover with the control-surface BORDER reveal (`HOVER_BORDER`),
+  the same language as the inline-editor cells beside them — never their own background wash
   today, more row actions later), per-group add rows that pre-set the group's field, and the same
   Draft-from-notes CTA). Both `tpl_tasks` and `tpl_task_board`: filters/search left, primary CTA right, one
   row; group-by holds only real dimensions, ✕ clears to ungrouped (no "Nothing" option). **`tpl_task_board` is the inline-managed
@@ -850,30 +986,25 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   (for tap-to-expand) with those controls nested inside: RNW renders the row AND each control as a `<button>`,
   so you get `<button>`s inside a `<button>` — invalid DOM + the inner controls drop out of the keyboard tab
   order. Give "expand" its own affordance (a trailing `Pressable` over the meta/chevron), as `tpl_tasks` does.
-- **Data capture** — `tpl_intake` (multi-fieldset form + attachments) · `tpl_order` (the
-  transactional form: find-or-create + line items + attachment CRUD + 2-col grid) · `tpl_billing`
-  (charges→invoice→collect: the invoice DOCUMENT is the unit — editable charge lines + method,
-  live total, status, inline-gated issue; validated receipt; separate deposit) · `tpl_quick`
-  (quick-capture log) · `tpl_wizard` (`Stepper` form + review) · `tpl_record_plain` (inline edit + Stage
-  disposition + `Select` tags + Documents grid; `tpl_record_plain` = card-less).
-- **Records & lookup** — `tpl_detail` (full record + tabs) · `tpl_directory` (searchable register) ·
-  `tpl_timeline` (audit feed).
-- **Planning & time** — `tpl_calendar` · `tpl_attendance` · `tpl_shifts`.
-- **Administration** — `tpl_settings`.
-- **AI workflows** — *produce*: `tpl_dieline` (the design CANVAS: photo → stream → the dieline
+- **Finance** — `tpl_statements` (the income statement, balance sheet, and cash flow statement
+  in ONE statement grammar: right-aligned column captions over fixed money columns, items
+  indented under group headers, a hairline rule above every subtotal, the grand total
+  DOUBLE-RULED, negatives in accounting parentheses, per-cell currency-free (the meta line says
+  VND once), no bars/charts. The three statements TIE — net income → retained earnings, closing
+  cash = the balance sheet's cash, the loan repayment moves the debt line — keep mock books
+  reconciled or the template teaches the wrong thing) · `tpl_report` (scope-first lookup report —
+  a header period + one-of-N dimension search drives KPIs → aligned facets w/ a `maxRows`
+  long-tail toggle → paginated register → export).
+- **Scheduling** — `tpl_calendar` · `tpl_attendance` · `tpl_shifts`.
+- **Agents** — *produce*: `tpl_dieline` (the design CANVAS: photo → stream → the dieline
   reveals CENTRED on a pannable/zoomable surface, the floating composer morphing into `AgentProgress`,
   a pinned live-edit params panel centre-right; prompt OR edit a param to iterate) ·
-  `tpl_assistant` (a chat copilot: the agent's answer carries suggested edits approved/rejected
-  1-by-1) · `tpl_extract` (read an image → extract records → review/edit each (`ReviewCard` +
-  `RecordFields`) → Save all) · `tpl_ratedesk` (BULK INGEST desk: a register-as-hero with an "Import
-  prices" CTA → a Dialog wizard: drop several sheets → `ChangeReview` 1-by-1 → kept rows land in the
-  register; for a maintained rate card / price list / tariff) · `tpl_draft` (draft generation: context → the reply text streams into an editable surface
-  → refine → send; tone/length steer it). *Structure*: `tpl_lookup` (the ANSWER desk: converse left,
-  a pinned `SpecList` verdict panel right; a follow-up refines it) · `tpl_match` (AI reconciliation:
-  body-first `ReviewCard` + `MatchSides` pairings with reasoning, accept/reassign/reject) · `tpl_briefing` (a generated narrative
-  + a ranked `Finding` attention list) · `tpl_crosscheck` (the audit desk: `Discrepancy` cards where
-  the documents disagree) · `tpl_triage` (an inbox of `TriageRow`s the agent classified + routed) ·
-  `tpl_compare` (ranked `ScoredOption` candidates the agent scored).
+  *Structure*: `tpl_lookup` (the ANSWER desk: converse left,
+  a pinned verdict panel right; a follow-up refines it) ·
+  `tpl_documents` (the DOCUMENT DESK — files on a record → the Use-AI fork: extract = the open
+  `ChangeFields` review (adds/updates/removal/conflict) + proposed order lines as `ChangeRecord`
+  cards, Keep-all + one outcome-named Apply; cross-check = display-only `Change` findings → a
+  recorded verdict; plus the Create-documents readiness checklist).
 
 ---
 
@@ -886,7 +1017,7 @@ section_heading (Section · SectionHeading · SectionHeadingTitle · SectionHead
 option_badge (OptionBadge — a select value as its configured colored badge) ·
 member_chip (MemberChip — avatar + name; the universal person render) ·
 member_select (MemberSelect — a Picker of MemberChip options; the member picker) ·
-status_badge · button · icon_button · link · text_link (TextLink — underlined text that's optionally an `onPress` action or an `href` link, or plain underlined text to wrap in your own pressable; the neutral counterpart to the fixed-blue `Link`) · chip · tabs (Tabs — switch between content sections; WAI-ARIA tablist + roving tabindex; each TabOption takes an optional `status` ColorName → a small attention dot before its label, for a tab whose area needs work) · segmented_control ·
+status_badge · button · icon_button · link · text_link (TextLink — underlined text that's optionally an `onPress` action or an `href` link, or plain underlined text to wrap in your own pressable; the neutral counterpart to the fixed-blue `Link`) · chip (Chip — the generic pill: pressable when `onPress` (announces as a button; pass `accessibilityLabel` when children aren't self-describing text) + an absolutely-positioned dismiss ✕ sibling when `onDismiss` (its name = `dismissTooltip` ?? the `chip.remove` locale slice). Suggestion pills → `SuggestionChip`) · tabs (Tabs — switch between content sections; WAI-ARIA tablist + roving tabindex; each TabOption takes an optional `status` ColorName → a small attention dot before its label, for a tab whose area needs work) · segmented_control ·
 picker (native `<select>`, plain label-only single) · select (Select — rich/custom-rendered, single/multi, select-all, chips via `renderSelected` + `searchable` + `allowCustom` — the tag field is just a multi Select; opens `OptionList`) · option_list (OptionList — the ONE shared searchable listbox body every selector opens: single/multi, optional internal search, create row, keyboard + native-`<select>` typeahead; host it directly in a `Popover`/`Dialog` for a command palette) · combobox (COMPOUND single-select editable search: `Combobox` root + `ComboboxInput` + `ComboboxContent`, optional `ComboboxEmpty`/`ComboboxFooter`, `useCombobox()`; over the shared `useOptionList` engine; browses on focus; no `multi` — multi-value chips → `Select multi`) ·
 text_input_field · number_input · search_input · form_field · checkbox · checkbox_input · switch ·
 radio_picker · counter · range_slider · date_picker · date_range_filter_field · time_picker ·
@@ -894,30 +1025,38 @@ inline_text_input · inline_number_input · inline_select · inline_member_selec
 inline_time_picker (the Inline* family — per-field editors on `inline_edit`'s `useInlineEdit` +
 `InlineEditView`; `InlineSelect`/`InlineMemberSelect` render the resting value like its option — `renderOptionContent` by default, `renderSelected` to override — a chip/badge at rest, not just text) ·
 inline_static (InlineStatic — a READ-ONLY value matching the Inline* box metrics EXACTLY (height, padding, 1px transparent border) so a non-editable field — a computed total, a system ID, a synced/locked value — aligns pixel-for-pixel in the same column; non-interactive, NOT a disabled input; `muted`/`tabular`/`align="right"` for a number column, `weight="medium"` to emphasise a total among plain rows) ·
-list · list_item · menu_button · menu_list_item · detail_row (DetailRow — label+value row for drawer/peek detail; in FORM mode (`labelWidth` set) the value column FILLS the row so a stack of inline editors all span the same width + none jumps wider on edit; optional `trailing` slot renders a right-side action/badge/unit after the value) · danger_zone (DangerZone — the destructive section: a soft danger-tinted frame (`tint`/`solid`, never raw hex) + a danger heading + a description + a destructive action slot (children, e.g. a `danger` Button); sits APART at the bottom of a record/settings surface) · pressable_row ·
-check_circle (CheckCircle — the completion ring: an empty ring that springs to a filled check when done, distinct from the square checkbox; the task/to-do/checklist toggle. Compose task rows directly, no Task component) · action_menu ·
+record_summary (RecordSummary — the identity band of a record detail/drawer: ONE row — `title` xl semibold tabular · `subtitle` sm muted · `status` Badge slot · optional `metric` {label,value,tone,note} pinned right, the band's ONE accent. The record's FIELDS never live in the header: compose them as `DetailTable`s in the sections below, the header's key facts as their own `DetailTable` right under the band on the same labelWidth/trailingWidth — `tpl_record` does this. Replaces hand-rolled record headers (mixed scales, several competing figures, color noise)) ·
+list · list_item · menu_button · menu_list_item · detail_row (DetailTable + DetailRow — the record field grid. DetailRow: label+value row for drawer/peek detail; in FORM mode (`labelWidth` set) the value column FILLS the row so a stack of inline editors all span the same width + none jumps wider on edit; optional `trailing` slot renders a right-side action/badge after the value (units belong IN the value via `InlineNumberInput format`). DetailTable: the compound parent of a row STACK — `labelWidth`/`trailingWidth`/`minHeight` (default 40, the inline-control grid) declared ONCE + the 6px row gap; with `trailingWidth` every row reserves the trailing column so value cells share one width and trailing items align at one x, like a table. RESPONSIVE with no prop: it measures its own container (onLayout, not the viewport — works inside a Drawer; the unmeasured first frame renders opacity-0 so the first PAINT is already in the right mode — no reshuffle as a drawer opens) and when the columns would crush the value cell it STACKS every row (the label above a full-width value row IN THE FORMFIELD LABEL GRAMMAR — medium, default ink — so narrow record surfaces and forms read as one vocabulary; trailing beside the value, gap 14. The components stay separate: FormField = draft controls validated + committed together; inline editors self-persist); raise `minValueWidth` (default 160) when a cell holds MORE than one editor (an amount+method pair) so the table stacks earlier. Two tables on one page share one grid by repeating the same labelWidth/trailingWidth. Worked example: `tpl_record`) · ledger (Ledger + LedgerGroup + LedgerRow + LedgerTotal — the record-level money list: charge/receipt GROUPS with sums in their headers, every figure on ONE right-aligned tabular column (all lines share the 8px inset), `peek` turns a row into a pressable door floating its particulars in an anchored popover (put links INSIDE the peek — never a button in a button; `reference` is the trailing-link alternative for static rows), LedgerTotal = the divider-set emphasized close with `zeroLabel` for settled. The financial-statement grammar at record density; worked example: `tpl_item_list` drawer) · danger_zone (DangerZone — the destructive section: a soft danger-tinted frame (`tint`/`solid`, never raw hex) + a danger heading + a description + a destructive action slot (children, e.g. a `danger` Button); sits APART at the bottom of a record/settings surface) · pressable_row ·
+check_circle (CheckCircle — the completion ring: an empty ring that springs to a filled check when done, distinct from the square checkbox; the task/to-do/checklist toggle) · checklist (Checklist + ChecklistRow — the record-scoped checklist COMPOUND: it owns GEOMETRY only (row minHeight 32, gap 12, ring/title alignment, ONE `trailingWidth` so assignee cells column-align) while content stays composed — `control` takes the CheckCircle (omit onChange = read-only ring), children the struck transparent InlineTextInput, `trailing` an InlineMemberSelect, `menu` the row's ⋯ options ({items: ActionMenuItem[], accessibilityLabel}) — Delete lives BEHIND the menu, danger-styled and last, never a bare ✕ (omit on read-only rows). NARROW surfaces (a drawer/peek checklist) put the editors on the `meta` line instead of `trailing` — the second line indents past the ring so the TITLE keeps the full width and stays readable; wide surfaces use `trailing`; never both. SUGGESTIONS are never rows: offer the commons as `SuggestionChip`s under the list (tap = materialize, ✕ = dismiss; a pill can't be mistaken for a task). Close the list with `CaptureRow`. There is deliberately NO monolithic Task component — richer task-management rows (tpl_tasks expand affordances, board cards) compose their own anatomy directly) · suggestion_chip (SuggestionChip — the dismissible SUGGESTION pill: an item the record could have but doesn't yet (a common task, an expected line) as a `Chip` whose press MATERIALIZES it (plus glyph + label, one tuned anatomy) and whose ✕ refuses it; filter out labels already present; suggestions never count in totals. Chrome via the `suggestionChip` locale slice) · capture_row (CaptureRow — the add-an-item row closing an editable list: dashed empty ring + borderless input on the item-title inset + a primary Save that appears on type; Enter commits too. Controlled: `value`/`onChangeText`/`onSubmit`. One shape wherever a list grows in place — task checklists, simple item lists) · action_menu ·
 floating_action_bar · filter_chip · column_filter (ColumnFilter — the typed per-column filter pill +
 columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
 sort_header · table · data_grid (DataGrid — the inline-managed grouped table: a grouped, sortable grid of LIVE inline-editor cells (`columns[].cell` → ANY field) + optional per-row `leading` (a CheckCircle) + `renderGroupFooter` (per-group add, align with the exported `gridRowStyle`) + `labels` (localize the sort-header a11y via `SortHeaderLabels`). Owns header/sections/rows; consumer owns data + sort/group/filter/collapse state + toolbar. Renders ALL rows — MODERATE data; 10k+ → the paginated `Table` register. Example: `tpl_task_board`) · pagination · accordion · stepper (Stepper + Step — done/current/upcoming/warning/complete progress on a track (horizontal) or spine (vertical); compound `<Step status>children` OR data `steps[]`+`current`; **navigable** via `Step.onPress` (both orientations — the whole step is the tap target) + `active` to wash the selected one, so it doubles as a section/phase switcher; the guided-run / agent-feed primitive — subsumes the old StepList) ·
-step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · modal (Modal + ModalHeader + ModalBody + ModalFooter — the full-bleed, edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a focused capture / multi-step wizard / a console the user steps INTO, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · popover · tooltip ·
+step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · modal (Modal + ModalHeader + ModalBody + ModalFooter — the full-bleed, edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a focused capture / multi-step wizard / a console the user steps INTO, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · screen_router (ScreenRouter + Screen + useScreenRouter — the SCREENS compound: a flat navigation stack (`navigate("/case/:id")` pushes, `goBack` pops, `canGoBack`, route `params`; stacked screens stay mounted `display:none` so scroll survives the round trip). Dialog BAKES a router in (`<Dialog><Screen route="">…`); ANY other container hosts the standalone `<ScreenRouter>` — and it wraps AROUND the container so the CHROME can read the stack: a Drawer drilling into a LINKED record swaps its header to a BACK IconButton + the pushed record's id while `canGoBack` (sequence ◀ ▶ hides — stepping the root from inside a linked record disorients), and the pushed `<Screen route="/case/:id">` is a REAL editable workspace with its own footer CTAs. Key the router by record id so stepping ◀ ▶ resets the stack. Worked example: `tpl_item_list` drawer) · popover · tooltip ·
 alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · summary_line (SummaryLine — the light inline summary of a register/list's FILTERED view, sits below the toolbar; NOT the boxed dashboard `kpi_strip` band) · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
 funnel (Funnel — conversion funnel: narrowing bars + the step rate as a bold aligned headline row, count below; `orientation` vertical|horizontal, `onSelect`/`selectedKey` press-to-drill; the subset/drop-off sibling of stacked_progress_bar's whole-split) ·
 status_grid (StatusGrid + StatusLegend) · heatmap (density cross-tab — colour-only, no numbers) · matrix (Matrix — the PIVOT cross-tab: band-compound `Matrix` root + `Matrix.Header` (corner + axis labels) + `Matrix.Grid` (`display` number|heat|both — the cells, pressable, the value IN the cell) + `Matrix.Totals` (row + column + grand) + `Matrix.Legend`; the data layer `matrixTotals`/`MatrixAxisItem`/`MatrixCellRef` import from `@lotics/ui/matrix_totals`. Pick over `Heatmap` when the NUMBER and totals matter, not just where it clusters) · legend_item · remainder_meter · allocation_row ·
 scan_field · file_dropzone · files_editor (FilesEditor — THE all-in-one attachment field: FileGrid + a toolbar (Upload primary · Select · Download all) that swaps into a batch SELECT mode (Select all · a Menu of Download/Share/Delete · Done; the per-tile ✕ is select-mode-only, never in the default view; `selectTileRemove={false}` drops even that so delete is menu-only) + built-in gallery (Download + inline preview; no "open in new tab") + Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`, `onShareSelected`, `readOnly`, `selectTileRemove`, `labels`, `galleryLabels`, `gridMaxHeight` — cap the grid height so it scrolls and the toolbar pins, for a popover/drawer); mirrors the frontend cell_files_editor. Use FileGrid/FileRows bare only when you own the chrome) · file_grid (FileGrid — the upload-aware grid: completed files + a live upload queue in one surface; FileUpload/PendingUpload types; the add-files default) · uploading_thumbnail (UploadingThumbnail — the single in-flight upload tile FileGrid renders; reach for it only when hand-rolling a non-grid upload layout) · file_thumbnail · file_thumbnail_grid · file_row · file_rows (FileRows — batteries-included file list: row press → built-in gallery + a ⋯ Download/Open-external/Remove menu; composes FileRow + ActionMenu + FileGalleryModal) · file_preview (FilePreview — the universal inline preview: image/PDF/video/audio + Word via `@lotics/docx` + Excel/CSV via `@lotics/xlsx`; the heavy engines (pdf.js · `@lotics/docx` · `@lotics/xlsx`) are LAZY (dynamic-imported, ~free until a doc of that type is opened) and SHIP AS `@lotics/ui` deps (7.14.0+) — custom-code apps get PDF/Word/Excel preview with ZERO extra install. Renders to canvas/DOM, never a nested iframe — works in the sandboxed app iframe) ·
-file_gallery_modal · image_gallery · use_selection (useSelection — always-on multi-select state for a register/list: the `selected` Set + `toggle`/`setAll`/`allSelected`/`indeterminate`/`count`/`clear`; selectability gating stays with the caller. The checkbox-always-visible counterpart to `use_selection_mode`) · use_selection_mode · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·
+file_gallery_modal · image_gallery · use_selection (useSelection — always-on multi-select state for a register/list: the `selected` Set + `toggle`/`setAll`/`allSelected`/`indeterminate`/`count`/`clear`; selectability gating stays with the caller. The checkbox-always-visible counterpart to `use_selection_mode`) · use_selection_mode · use_section_nav (useSectionNav — scroll-spy for a LONG record surface with a left outline rail: keys in page order → {scrollRef, onScroll, register(key)→onLayout, jumpTo(key), activeKey}; rail items are `MenuButton`s (selected={activeKey===key}); section wrappers must be DIRECT children of the ScrollView content. On NARROW containers the rail becomes a PINNED bar naming the CURRENT section (the spy keeps it honest) that opens a full-page section-picker `Modal` (`MenuButton` list; Escape / the close control dismiss) — never a horizontal tab strip the thumb has to scroll. Worked example: `tpl_record`) · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·
 spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·
 comments_thread · agent_run (live streaming work feed) · agent_progress (its compact floating
 expandable form — a composer's working state) · composer (Composer — the adaptive command/chat
-composer: a compact pill that expands for long text + attachments) · review_card (ReviewCard — THE single-proposal review card; compositional body via children + a generic actions footer; header-first with a title/eyebrow, body-first without) · confidence (calibrated high/med/low) ·
-record_fields (RecordFields — the editable extracted-record BODY for a ReviewCard, or a standalone live-edit field card) · change_review (ChangeReview — the BATCH review LIST, whole-set OR 1-by-1; compositional `renderItem` body + the `ChangeDiff` before→after helper, `labels` localizes Undo/Applied/Discarded/counter — PLUS `ChangeReviewActions`, the separate commit bar the host pins in a `DialogFooter`/`DrawerFooter` or inline so it never scrolls away) ·
+composer: a compact pill that expands for long text + attachments) · confidence (calibrated high/med/low) ·
+change_review (the COMPOUND review family — frame: ChangeReview provider/stack · ChangeReviewHeader
+(auto kept-counter over decidable entries) · ChangeReviewActions (the commit bar in the
+DialogFooter/DrawerFooter: Keep-all bottom-left (onAcceptAll for host-held field state) + Apply
+gating); sections: Change (host-owned status, labeled verbs, collapses to its ChangeSummary + Undo;
+no callbacks = display-only) · ChangeLabel · ChangeSummary · ChangeReasoning (the quiet why);
+grammar: ChangeFields (the open record form) + ChangeField (THE field: − band · value · candidates
++ type-another-value · reasoning · per-field Keep/Drop · collapse) · ChangeRecord (THE item card:
+registers like a Change; tone wash + localized op word; verb level follows the decision level) ·
+ChangeBand (the raw ± band) · ChangeValueInput (the diff-at-rest editor); the `changeReview`
+locale slice) ·
 clarify (the agent asks back, via ChoiceList) · choice_list (ChoiceList — selectable answer options,
-the agent's quick-reply surface) · sources (provenance chips, per-kind glyphs) · spec_list (SpecList — the exact
-labeled-value breakdown, the panel of an answer) · match_sides (MatchSides — the two-sided pairing BODY for a body-first ReviewCard reconciliation; composable side slots + the MatchSideText default) ·
-finding (Finding — one ranked briefing/audit insight) · discrepancy (Discrepancy — a field that
-disagrees across sources) · triage_row (TriageRow — an item the agent classified + routed) ·
-scored_option (ScoredOption — an AI-ranked candidate) ·
+the agent's quick-reply surface) · sources (provenance chips, per-kind glyphs) · finding (Finding — one ranked AI-check insight: severity word · title · detail · Sources ·
+children slot — with FindingComparison, the expected-vs-actual body: labeled sides + emphasized
+delta; the `finding` locale slice) ·
 format_money · format_date · colors (solid · tint · ramp · ColorName ·
 isColorName · asColorName — coerce a stored option/status token to a ColorName, neutral fallback) ·
 use_focus_ring (useFocusRing — keyboard-aware focus state for painting a control's own ring; see Focus rings) ·