@lotics/ui 45.9.0 → 45.10.1

package/docs/templates.md

@@ -2,11 +2,10 @@
 
 The package ships full worked-example screens in `examples/tpl_*.tsx` — each a complete,
 runnable recipe for one screen **job**, built purely from `@lotics/ui` components plus mock
-data. This doc is the map: what shape each template solves, what it owns versus what its
-primitives own, and which one to start from. Read it when starting any new screen, then read
-the chosen template's source before writing code. Component contracts live in
-[the catalog](./catalog.md), the layout/color laws in [the composition grammar](./composition.md);
-the package index is [../AGENTS.md](../AGENTS.md).
+data. This doc is the map: what shape each template solves and which one to start from. Read it
+when starting any new screen, then read the chosen template's source before writing code.
+Component contracts live in [the catalog](./catalog.md), the layout/color laws in [the
+composition grammar](./composition.md); the package index is [../AGENTS.md](../AGENTS.md).
 
 ## How to use an example
 
@@ -18,13 +17,12 @@ the package index is [../AGENTS.md](../AGENTS.md).
   resolution by design. Copy the bands you need into your app, keep the component imports,
   and replace the mock constants with real reads.
 - **Pick by the job, not the domain.** Templates are scenario-flavoured (a pick run, cash
-  application, a delivery week) but generic-purpose — they teach the shape. Your orders /
-  items / customers screen starts from the template whose *job* matches, whatever the domain.
-  **Flavor lives in VALUES, never in STRUCTURE**: section identities, teaching comments, and
-  registry keys name the generic PATTERN; mock nouns stay at the common-denominator level any
-  goods/services business uses (a service level, a destination, a delivery receipt) — never
-  one vertical's jargon (an FCL, an EIR, an HS code). Adapt a template by swapping the
-  values; the patterns are what you keep.
+  application, a delivery week) but generic-purpose — they teach the shape. Your orders / items
+  / customers screen starts from the template whose *job* matches, whatever the domain. **Flavor
+  lives in VALUES, never in STRUCTURE**: section identities, teaching comments, and registry
+  keys name the generic PATTERN; mock nouns stay at the common-denominator level any
+  goods/services business uses (a service level, a destination, a delivery receipt) — never one
+  vertical's jargon (an FCL, an EIR, an HS code).
 - The templates encode the composition grammar (band order, toolbar law, color discipline,
   status weight) as working code — when a template and your instinct disagree, the template
   wins.
@@ -64,10 +62,150 @@ its own navigated route only when one of these holds:
 - **The work needs the canvas.** A docked comments gutter, a document read beside the fields,
   an outline rail worth navigating — width the drawer's single column cannot give.
 
-The volume of DATA is not the test. A record with forty fields still closes in the drawer if
-the operator opens it from the list, works it, and goes back to the list. What an app without
-a destination skips is the ROUTE, never the template: the drawer renders `tpl_record` either
-way, so "no record page" must never become a hand-built detail surface.
+The volume of DATA is not the test. What an app without a destination skips is the ROUTE, never
+the template: the drawer renders `tpl_record` either way, so "no record page" must never become
+a hand-built detail surface.
+
+### The shape taxonomy — two families
+
+Everything above picks a TEMPLATE. This picks a SHAPE, which is the decision that comes first —
+and the one an agent otherwise re-derives, badly and differently each time, because the register
+has ~13 templates and the record surface has one.
+
+**An app screen is `[tabs] + list → record`, and that is nearly every app in every industry.**
+The LIST is the only constant: glancing, filtering, narrowing, summarising. It is where the reader
+spends the day and where the app is judged. The RECORD is the detail layer behind it, with two
+destinations decided by who arrives and from where (§ Register + drawer, or a navigated page?).
+TABS are optional, and reaching for them by reflex is how one set becomes piles nobody asked for.
+
+**A dashboard is the other family and shares none of it** — no list, no drawer, no work.
+Read-only, visual-first, immediate: it answers "how is the operation doing", never "which of these
+do I act on".
+
+**This is a map of known territory, not a fence.** Building a shape that is not on it is the
+intended behaviour when the job calls for one — the line between a choice and a defect is drawn in
+[composition.md](./composition.md) §"The form comes before the treatment", and it is drawn there
+for this too.
+
+### App-screen shapes
+
+**What earns a tab.** A band is a TAB when it changes what the screen IS — its columns, the act on
+its row, what its summary states. A band showing the same columns and the same act over fewer rows
+is a LENS, and a lens is a `ChipGroup` / `Select` / `FilterChip` in the toolbar (→
+[composition.md](./composition.md) §"One view-control vocabulary"). Tabs are the COARSE cut above
+the filters, never a second copy of them; each states its own size and trouble as props (→
+[composition.md](./composition.md) §"A partitioning control states its band's size as a PROP").
+
+**The lifecycle desk** — one record type walking ordered stages: an order, a claim, an
+application, a shipment, a repair. *"What is stuck, and what do I move next?"*
+
+- **Tabs: the stages**, and here they earn it — each band carries its own act (confirm, dispatch,
+  close), its own summary, often its own columns. Roughly five; past that the tail is a lens.
+- **Record: a `Drawer`.** The reader came from the list and returns to it, and the drawer's ◀ ▶
+  sequences the band they were reading.
+- **Row vs record:** the row carries what the NEXT act needs — the goods, the money, the clock —
+  so the decision is made without opening anything. The record carries the history, the documents,
+  and the way back (§ Anything that ADVANCES a record must be able to walk it back).
+- **Adapt:** rename the stages and the shape survives intact. An approval queue is its two-stage
+  degenerate case, not a shape of its own.
+
+**The party register** — a person or an organisation you have a relationship with: a customer, a
+supplier, a member, a tenant, a patient. *"Who is this, what is our history, is there a risk?"*
+
+- **Tabs: usually NONE.** A party has no stages; its segments (region, source, risk) are filters,
+  and splitting people into permanent piles buries the ones the reader did not pick.
+- **Record: a PAGE.** A party is arrived at COLD — from an order, a call, a notification — so it
+  must stand up without the list that would have opened it.
+- **Row vs record:** identity (`Avatar` initials), ONE reachable contact, what the relationship is
+  WORTH (spend, count, last contact), and the single flag that costs money when missed. The record
+  holds the transaction history and the interaction log the user writes into.
+- **Adapt:** the worth metrics and the risk flag are the industry-specific half; identity and
+  reach are not.
+
+**The offering register** — what you sell: products, services, plans, a rate card. *"What do we
+offer, at what price, can I sell it today?"*
+
+- **Tabs: none, or the sales categories** the business already thinks in.
+- **Record: a PAGE.** Media, a long description and variants need canvas, and an offering is
+  arrived at cold from every order line that names it.
+- **Row vs record:** the row is IMAGE-led — a `FileThumbnail` in one square slot, then the name
+  with its code on the supporting line, the price, and the one availability figure. The record
+  holds the media, the description, and the price/cost history.
+- **Adapt:** a services business swaps availability for a rate basis. The image column stays: it
+  is the row's own data doing the work
+  ([composition.md](./composition.md) §"Character comes from the DATA").
+
+**The transaction ledger** — dated movements in a book: bank lines, journal entries, stock
+movements, metered usage. *"Does this period reconcile, and what is still unexplained?"*
+
+- **Tabs: the BOOKS** — one per source or account. Not the periods: a period is a
+  `DateRangeFilterField` in the header band
+  ([composition.md](./composition.md) §"Period filters for time-constrained data"), and tabbing it
+  strands every other period behind a tab bar that grows monthly.
+- **Record: a `Drawer`.** A line has little of its own; what it needs is the document that proves
+  it and whatever it was matched against.
+- **Row vs record:** date, counterparty, ONE signed amount (never paired in/out columns), its
+  classification, and whether its document is attached — absence is the information. Where the
+  BALANCE is the point the list is a `RunningLedger`, which derives every running figure itself
+  rather than trusting a supplied one.
+- **Adapt:** the classification vocabulary. **The period's default decides whether the screen
+  opens rich or empty** — open on a settled period and surface the incomplete one as a call to
+  action; a screen that opens on its own unfinished work reads as broken.
+
+**The monitored-asset set** — a population with a live state and a history: stock, machines,
+vehicles, containers, sensors. *"What needs attention now, and is that number normal?"*
+
+- **Tabs: by RESPONSIBILITY, not by state** — holding, receiving and counting are different jobs
+  with different acts. State is what the reader sorts and filters by, so it is a lens.
+- **Record: a `Drawer`** onto the unit's recent movements: a `RunningLedger` where they are
+  arithmetic, a `Timeline` where they are events.
+- **Row vs record:** the row carries the level, the THRESHOLD it is measured against and the
+  derived shortfall — a level with no threshold beside it cannot be acted on — plus its trajectory
+  as a `Sparkline`. Where the population runs to hundreds and the job is scanning for red, the
+  list becomes a `StatusGrid` (`tpl_tower`); where it runs to thousands, `tpl_stock`.
+- **Adapt:** name the two levels the way the trade does. A gross level and an available level are
+  never synonyms, and the available one is what a person checks before committing.
+
+**The reconciliation desk** — two sources that should agree: a statement against the ledger, a
+count against the system, a remittance against the orders it covers. *"What does not match, and by
+how much?"* The kit ships no example for this one.
+
+- **Tabs: the RUNS** — each a dated session — or none where only one run is ever open.
+- **Record: a `Drawer` on the PAIR**, not on either side: the two figures and everything that
+  explains the gap between them.
+- **Row vs record:** a row is a PAIRING, so it carries both figures and the signed difference. A
+  committed difference takes a REASON — an unexplained variance cannot be audited, and that is
+  where breakage hides. The unmatched remainder is the `SummaryLine`, and the desk is not finished
+  until it is zero (`RemainderMeter` + `tpl_allocate` where one source splits across many
+  targets).
+- **Adapt:** the two sources and the reason vocabulary; the arithmetic does not change.
+
+### Dashboard shapes
+
+Both are read-only and visual-first, and neither runs AI (→ `tpl_dashboard`). They differ by the
+reader's CLOCK, and a screen that mixes them answers neither: a wallboard filtered by quarter is
+not glanceable, and a quarterly review showing only now explains nothing.
+
+**The live-status board** — the operation's units, right now. *"Is everything OK?"* Glanced at
+repeatedly, often on a wall.
+
+- **No period control** — "now" has no range.
+- Leads with STATE (`KPIStrip` + `StatusGrid`), then an exceptions rail ordered by severity and
+  then by how long each has gone unresolved, then where it clusters (`Heatmap`). `tpl_tower` is
+  the worked example.
+- Every cell and every exception row is a door into that unit's `Drawer`.
+- **Adapt:** the state vocabulary — one `ColorName` per state, at every weight.
+
+**The trend deep-dive** — a period of the business. *"How did it go, and why?"* Opened to decide
+something.
+
+- **The period control governs every figure on the screen** (`DateRangeFilterField`).
+- Leads with the shape of CHANGE (`LineChart`, `BarChart`), then composition (`StackedBarChart`,
+  `Breakdown`, `PieChart`), then the BRIDGE that explains a movement (`WaterfallChart`, where the
+  step that costs the money is the red one rather than a footnote). `tpl_dashboard` for the shape;
+  `tpl_pivot` / `tpl_rollup` when the answer is chased down a dimension.
+- **Adapt:** the metrics — and every one traces to a stored or derived value. A chart licenses no
+  number the data cannot produce.
 
 ## Composition rules — how a record surface is assembled
 
@@ -81,16 +219,16 @@ Laws for any screen where a record's data is edited and a primary action produce
 2. **Static shape.** The page never changes shape from output-selection state. Conditional
    rendering is DATA-driven only (a control appears because two stored values differ), never
    selection-driven. Relevance is an advisory `Callout` with a jump-to-section action — warn,
-   never hide, never hard-block. One sanctioned disclosure: a fill-what's-missing `Inset`
-   editor CO-LOCATED under a just-checked item is progressive disclosure of the gate, not
-   shape change — it edits the record field in place and clears once satisfied.
+   never hide, never hard-block. One sanctioned disclosure: a fill-what's-missing `Inset` editor
+   CO-LOCATED under a just-checked item edits the record field in place and clears once
+   satisfied.
 3. **Colocation & ownership.** Every output option (selections, print/export switches) lives in
    the output section beside its action; a per-entity selection carries its owner's name in its
    heading. Persisted record DATA never lives there — data belongs in data sections. Misfiled
-   data announces itself as callout special-cases; the exception disappearing is the sign the
-   model is right. (HOMING is what's forbidden, not repair: the output section may host a
-   co-located fill editor that saves onto the record field — same storage, the field's home
-   row shows the value — rendered only while a checked output still lacks the field.)
+   data announces itself as callout special-cases. (HOMING is what's forbidden, not repair: the
+   output section may host a co-located fill editor that saves onto the record field — same
+   storage, the field's home row shows the value — rendered only while a checked output still
+   lacks the field.)
 4. **Resolved state.** Controls show the EFFECTIVE state, never raw storage: a derived/suggested
    selection renders checked; the first manual change persists the full explicit set; a
    reset-to-auto affordance appears only in explicit mode. What's shown = what happens.
@@ -146,6 +284,23 @@ name `Peek`s the dossier). Also exercises the wider chart family (`LineChart`, `
 filter actually filters the KPI datasets. Start here for any "state of the operation"
 landing screen.
 
+**A dashboard is VISUAL first.** Lead with the charts, let the figures support them. `KPIStrip`
+earns its place as the headline row above the charts, never as the whole screen.
+
+The chart family is `BarChart`, `LineChart`, `PieChart`, `Funnel`, `Heatmap`, `Sparkline`,
+`ProgressRing`, `ProgressBar`, `StackedProgressBar`, `StackedBarChart`, `WaterfallChart`,
+`StepProgress` — and **that list is a starting inventory, not the boundary.** When the truth
+needs a shape the kit has no component for — a dual-axis pairing spend against return, a bullet
+against target — **build it into `@lotics/ui`** rather than hand-rolling it inside one app (→
+AGENTS.md, "components graduate into `src/` + an `examples/tpl_*` + a catalog entry").
+
+Read the `dataviz` guidance before choosing a chart type or a palette.
+
+**No AI run belongs on a dashboard.** If a figure is worth showing, compute it and show it; if
+the question is open-ended enough to need a model, it belongs in chat. The same test
+disqualifies anything else that makes a dashboard *ask before it answers*: a required mode
+chooser, an empty state awaiting a selection, a panel that loads only on click.
+
 ### `tpl_stock` — the drill-down overview (large populations)
 
 Monitoring a population too large to browse (10,000+ units). The funnel: `KPIStrip`
@@ -194,51 +349,63 @@ master-detail panel.
 ### `tpl_item_list` — THE canonical register
 
 The one work-execution list shape; it subsumes approvals, dispatch, batch-building, and run
-screens — register, per-row action, gated selection, and act-on-many in one. The page:
+screens — register, per-row action, gated selection, and act-on-many in one.
+
+**A register is a WORK surface, and that fixes its altitude.** The aggregate belongs elsewhere:
+**no `KPIStrip`, no chart panel, no report band above the rows.** The register's whole summary
+is the one `SummaryLine`, and what it states is *this filtered view* — money at stake, how many
+need a decision, the worst case in view — never a count of rows the reader can already see.
+Aggregates are a DASHBOARD's job: a dashboard says how the operation is doing, a register is
+where the work gets done. (A per-row micro-visual — a `Sparkline`, a bar in a cell — is row
+DATA, not a panel, and is fine.)
+
+The corollaries, each of which a register is routinely missing:
+
+- **Filter on the axis its reader actually thinks in**, and make anything transactional
+  filterable by DATE.
+- **Sortable columns wherever the reader ranks** — dates and amounts above all.
+- **Put intake ON the register**, and one CTA per tab covers the tab's own shape. Where a file
+  is the real-world input, the CTA pair is manual entry beside a file-drop that proposes rows
+  for review.
+- **If a row can carry a document, the register states whether it has one.** Absence is the
+  information — a badge that shows nothing for a row missing its invoice is exactly the column
+  that earns its width.
 
 - **One toolbar row** — search + a status `Select` + facet `FilterChip`s LEFT, the New CTA
-  RIGHT; then a light `SummaryLine` of the filtered view BELOW it, above the rows — the counts are what the toolbar just produced, so they read after it, not before.
+  RIGHT; then a light `SummaryLine` of the filtered view BELOW it, above the rows.
 - **A sortable `Table`** — rows separated by their own height and the hover wash, with the one
-  hairline under the column band. It sets no row height: the register's rhythm is the kit's,
-  and a template that overrode it would teach the override. → [composition.md](./composition.md)
-  §"The register's rhythm". The record's SUBJECT is the first column —
-  who or what the record is FOR, because that is what a reader scans for and what they say out
-  loud ("the Harbor Freight one", never "RC-2026-0041"). The KEY is how the SYSTEM refers to the
-  record, so it rides the identity cell's supporting line, muted, where the other supporting
-  values live; it does NOT take a column of its own, and it is never the row's name. It also does
-  not SHRINK there — a key is quoted whole or it is not a key, so a long phone number gives way
-  first (it has a `CopyButton` handing over the full value regardless). The record surface names
-  itself the same way, or the two disagree about what a record is called. Every row carries a
-  leading checkbox; a row that can't take the bulk action gets a
-  **disabled** checkbox (the same gating as any blocked line). A row's status is
-  `Badge variant="dot"` — never the tonal `Badge` (that's the drawer/header twin; → [composition.md](./composition.md)
-  §"`Badge` is for STATUS only") — and the SAME dot vocabulary
-  drives the status facet. A cell that carries supporting detail is a HIERARCHY, not two peers:
-  the identity on top (`size="sm"`, `weight="medium"` when it IS the row's name), its supporting
-  value beneath as `size="xs" color="muted"`, `gap: 2` — and a category / type / attribute goes
-  on THAT line, never a second chip beside the name (which reads as its peer, or louder when
-  colored, inverting what the row is scanned by; → [composition.md](./composition.md)
-  §"`Badge` is for STATUS only"). Every value in a row is SELECTABLE, so a reader copies any of them
-  without chrome; the supporting phone additionally carries a **`CopyButton`** as the worked
-  example of a verb riding its value — the one value copied often enough to earn a control, and
-  in its own cell rather than the trailing gutter, which two values in a cell give nothing to
-  name. A per-row action `Button` (here Print) is the row's primary action in
-  the trailing column, `⋯` its overflow. A select-all band, footer totals + `Pagination`, and a
-  `FloatingActionBar` carrying the bulk action while rows are ticked.
+  hairline under the column band. It sets no row height: the register's rhythm is the kit's. →
+  [composition.md](./composition.md) §"The register's rhythm". The record's SUBJECT is the first
+  column — who or what the record is FOR. The KEY is how the SYSTEM refers to the record, so it
+  rides the identity cell's supporting line, muted, where the other supporting values live; it
+  does NOT take a column of its own, and it is never the row's name. It also does not SHRINK
+  there — a long phone number gives way first (it has a `CopyButton` handing over the full value
+  regardless). The record surface names itself the same way. Every row carries a leading
+  checkbox; a row that can't take the bulk action gets a **disabled** checkbox (the same gating
+  as any blocked line). A row's status is `Badge variant="dot"` — never the tonal `Badge`
+  (that's the drawer/header twin; → [composition.md](./composition.md) §"`Badge` is for STATUS
+  only") — and the SAME dot vocabulary drives the status facet. A cell that carries supporting
+  detail is a HIERARCHY, not two peers: the identity on top (`size="sm"`, `weight="medium"` when
+  it IS the row's name), its supporting value beneath as `size="xs" color="muted"`, `gap: 2` —
+  and a category / type / attribute goes on THAT line, never a second chip beside the name (→
+  [composition.md](./composition.md) §"`Badge` is for STATUS only"). Every value in a row is
+  SELECTABLE, so a reader copies any of them without chrome; the supporting phone additionally
+  carries a **`CopyButton`** as the worked example of a verb riding its value, in its own cell
+  rather than the trailing gutter. A per-row action `Button` (here Print) is the row's primary
+  action in the trailing column, `⋯` its overflow. A select-all band, footer totals +
+  `Pagination`, and a `FloatingActionBar` carrying the bulk action while rows are ticked.
 - **A row press opens the PRODUCTION workspace `Drawer`** — which RENDERS
   [`tpl_record`](../examples/tpl_record.tsx) in `chrome="drawer"`, not a copy of it. Same
   sections, same order, same rules, because it is the same component: `<TplRecord
   chrome="drawer" code={row.id} />`. A hand-built second record surface is exactly how the two
-  drifted apart — the progress ladder grouped one way here and flat there, a reference as a
-  section here and a field there — so the register owns the REGISTER and nothing else.
+  drift apart, so the register owns the REGISTER and nothing else.
   - What the chrome flag changes is only what a nested surface must not do: the back button is
-    left to the Drawer's header, since two exits is two exits. Everything else follows from
-    width — the layout measures its CONTAINER via `onLayout`, never the window, so the outline
-    rail and the mirrored gutters collapse on their own, and the section picker is a popover
-    ANCHORED to its bar button rather than a full-page `Modal` that would escape the drawer.
-    **The discussion follows the same measure**: docked beside the record where there is room for
-    its column, and a SECTION under General where there is not — which a drawer always is. It is
-    never behind a control.
+    left to the Drawer's header. Everything else follows from width — the layout measures its
+    CONTAINER via `onLayout`, never the window, so the outline rail and the mirrored gutters
+    collapse on their own, and the section picker is a popover ANCHORED to its bar button rather
+    than a full-page `Modal` that would escape the drawer. **The discussion follows the same
+    measure**: docked beside the record where there is room for its column, and a SECTION under
+    General where there is not — which a drawer always is. It is never behind a control.
   - **Linked records** still push an editable screen for that record inside the drawer via the
     hosted `ScreenRouter` — while `canGoBack` the drawer header swaps to a back button + the
     pushed id and the ◀ ▶ sequencer hides; back pops with scroll preserved.
@@ -270,12 +437,9 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
     they will be stored, each editable in place, a `DiffMark` per card, Keep/Drop via
     `useChangeSet` (`initial: "accepted"` — the operator drops the exceptions rather than
     approving six identical records) — and ONE commit named for its outcome creates them. The
-    manual form beside it skips all of that and saves direct: the operator typed those three
-    values and read them on the way in. Only the DOCUMENT path needs the gate, because a
-    receipt saying "Created 3 records" is the first moment a misread order reference could
-    have been caught, and by then it is in the data. The receipt still follows the write — it
-    states the outcome, ROUTES, and carries the deterministic checks (a checksum, a count
-    reconciliation) that a person cannot eyeball anyway.
+    manual form beside it skips all of that and saves direct. Only the DOCUMENT path needs the
+    gate. The receipt still follows the write — it states the outcome, ROUTES, and carries the
+    deterministic checks (a checksum, a count reconciliation).
 
 ### `tpl_pick` — the guided queue
 
@@ -297,17 +461,17 @@ Oldest-first auto-allocates; each `AllocationRow` can be filled or typed.
 
 ### `tpl_record` — THE record surface
 
-The record page — **the surface IS the editor**; every field refines in place. No breadcrumb
-and no create CTA (creation belongs to the REGISTER — the list owns "new"; back lives in the
-left panel as the bare circular `BackButton`). First paint is a `Skeleton` MIRRORING the
-layout, never a spinner. It absorbed the old order-form, inline-record, intake, settings,
-billing, and quick-capture templates. Top → bottom:
+The record page — **the surface IS the editor**; every field refines in place. No breadcrumb and
+no create CTA (creation belongs to the REGISTER — the list owns "new"; back lives in the left
+panel as the bare circular `BackButton`). First paint is a `Skeleton` MIRRORING the layout,
+never a spinner. It absorbs the order-form, inline-record, intake, settings, billing, and
+quick-capture templates. Top → bottom:
 
 - A MINIMAL header: `RecordSummary` (title, subtitle ONLY — no stage chip, no metric; Progress
   carries the desk, money lives in Billing), then the record's
   ATTENTION state as a co-located `Callout` (e.g. overdue — record-scoped state reads here;
-  field-scoped state stays on its field), then a quiet `SummaryLine` (desk, documents
- , to collect).
+  field-scoped state stays on its field), then a quiet `SummaryLine` (desk, documents, to
+  collect).
 - **GENERAL — the MAIN details, first in THIS record's rail** because its work starts at the
   details; rule 1 orders sections by work flow, so a surface whose work starts at a DOCUMENT
   (an invoice desk, a claims desk) leads with Documents and General follows. Every later
@@ -327,23 +491,20 @@ billing, and quick-capture templates. Top → bottom:
   field renders only while its parent value makes it real (no disabled ghost rows).
   Radio/checkbox/search are PERSISTENT controls — the control is the best display;
   prose-shaped values stay inline editors.
-- **Comments — a docked PANEL, not a section.** It is about the whole record, so it has no place
-  in a top-to-bottom read and no rail entry: it pins in the page's RIGHT gutter (the column the
-  outline rail's balance already reserved), scrolling inside itself so a long thread never
-  lengthens the record, and collapses onto the pinned bar's right on narrow. `CommentList`
-  (author-only edit/delete; attachments as a pressable `FileGrid` → gallery preview; a
-  file-capable edit form injected via `renderEditForm`) + THE kit `Composer` (attach via
-  `actionsButton`, staged files in its `files` slot) — never a bespoke comment box.
-- **Progress** — directly UNDER General, because where the record SITS is the second question a
-  reader has after what it IS, ahead of its files, its route and its money, which are all
-  reference. The desk handoff as the ordered positions it is: a `Checklist connected` where the
-  desks are `ChecklistGroup`s (Sales → Operations → Accounting) and the milestones they produce
-  are the rows. The row that OWES the work
-  carries all three: how long it has been owed (`meta`), its condition (`ChecklistNote`, e.g.
-  past the due date — with an `action` jumping to the section that owns a missing field rather
-  than editing it here) and the single act that leaves the desk (`ChecklistActions` → the handoff
-  dialog). `meta` is prose
-  the reader can't set, never the date that the stage's own field already shows. See § The
+- **Comments — a docked PANEL, not a section.** It is about the whole record, so it has no rail
+  entry: it pins in the page's RIGHT gutter (the column the outline rail's balance already
+  reserved), scrolling inside itself so a long thread never lengthens the record, and collapses
+  onto the pinned bar's right on narrow. `CommentList` (author-only edit/delete; attachments as
+  a pressable `FileGrid` → gallery preview; a file-capable edit form injected via
+  `renderEditForm`) + THE kit `Composer` (attach via `actionsButton`, staged files in its
+  `files` slot) — never a bespoke comment box.
+- **Progress** — directly UNDER General. The desk handoff as the ordered positions it is: a
+  `Checklist connected` where the desks are `ChecklistGroup`s (Sales → Operations → Accounting)
+  and the milestones they produce are the rows. The row that OWES the work carries all three:
+  how long it has been owed (`meta`), its condition (`ChecklistNote`, e.g. past the due date —
+  with an `action` jumping to the section that owns a missing field rather than editing it here)
+  and the single act that leaves the desk (`ChecklistActions` → the handoff dialog). `meta` is
+  prose the reader can't set, never the date that the stage's own field already shows. See § The
   handoff shape for the rules; for a record that genuinely needs a CHECKLIST, the task-list
   grammar is worked in `tpl_item_list`.
 - **Documents** — the Agents "Document desk" pattern (this template is its worked example —
@@ -365,82 +526,69 @@ billing, and quick-capture templates. Top → bottom:
   own (see [composition.md's reference law](./composition.md)). It wears the inline editor's
   resting surface with an `InlineButton` **Open** inside it; pressing the surface PEEKS the
   facts, and the peek's footer carries detach LEFT / Open RIGHT — so the row itself shows no
-  destructive verb at all. The tax-ID problem that gates invoicing is the row's `warning`, not
-  a floating `Callout`. Transport's three party rows are the same shape repeated, which is where
-  it earns itself: N references as field rows scan as one list, where N cards would be a wall.
-  Empty state = the find-or-create `Combobox` in the same value slot, custom row → the create
-  `Dialog` (tax ID + Fetch). That dialog is built from **`FormField` / `FormTextInput`, never the
-  record surface's `Inline*` editors** — see [data_entry.md](./data_entry.md) §"A dialog is a
-  draft".
-  **Reference (the buyer's own) is the `actions` worked example**: its `Copy` is an
-  `InlineButton` ON the field, passed unconditionally and `disabled` while empty — not in the
-  row's `trailing`, and not conditional, which would resize the field as you type.
+  destructive verb at all. The tax-ID problem that gates invoicing is the row's `warning`, not a
+  floating `Callout`. Transport's three party rows are the same shape repeated: N references as
+  field rows scan as one list, where N cards would be a wall. Empty state = the find-or-create
+  `Combobox` in the same value slot, custom row → the create `Dialog` (tax ID + Fetch). That
+  dialog is built from **`FormField` / `FormTextInput`, never the record surface's `Inline*`
+  editors** — see [data_entry.md](./data_entry.md) §"A dialog is a draft". **Reference (the
+  buyer's own) is the `actions` worked example**: its `Copy` is an `InlineButton` ON the field,
+  passed unconditionally and `disabled` while empty — not in the row's `trailing`, and not
+  conditional, which would resize the field as you type.
 - **Fees — the DETAILED money ledger** (both directions), distinct from Billing's invoice
-  documents: a `SummaryLine` (collected, to collect, to pay, warning-toned when overdue) →
-  a `priority`-annotated register `Table` (Fee, Type, Party, Amount, Status — status in
-  plain ink, danger only when overdue) → EVERY row opens a right-docked entity `Drawer`
-  (◀ ▶ + position stepping) with all fields inline-editable and a confirmed Remove in the
-  `DrawerFooter`. "Add fee" rides the section heading's right edge — the one place it does not
-  move as rows arrive — and is create-then-refine: a blank fee opens straight in the drawer. The
-  empty state carries no button of its own, because that one is already on screen.
+  documents: a `SummaryLine` (collected, to collect, to pay, warning-toned when overdue) → a
+  `priority`-annotated register `Table` (Fee, Type, Party, Amount, Status — status in plain ink,
+  danger only when overdue) → EVERY row opens a right-docked entity `Drawer` (◀ ▶ + position
+  stepping) with all fields inline-editable and a confirmed Remove in the `DrawerFooter`. "Add
+  fee" rides the section heading's right edge and is create-then-refine: a blank fee opens
+  straight in the drawer. The empty state carries no button of its own, because that one is
+  already on screen.
 - **Billing — INLINE bands, closed by a STATEMENT.** Each invoice is a `Subsection` costing ONE
   line of chrome (its name, its total, its issued ref) over its charge rows in a `DetailTable`;
   the charge editors carry ghost list prices with a one-tap "Standard …" fill and a "How paid…"
-  select. Three shapes were tried. Inline bands with a heading rung, a band callout and an
-  action row each made the CHROME three times the content; a `Table` + right-docked `Drawer`
-  then hid four charge lines behind three expansions, which trades a real fault for a worse one
-  — you can no longer see what you are paying for. So the lines all stay and the chrome
-  shrank, and a per-invoice problem rides the CHARGE ROW that has it (`warning` on the line
-  missing its method), which is smaller than a callout and more precise: it names the offender
-  instead of counting offenders.
+  select. The lines all stay, and a per-invoice problem rides the CHARGE ROW that has it
+  (`warning` on the line missing its method), which is smaller than a callout and more precise.
   The section then CLOSES with a `Ledger` — the money grammar's worked example, and the answer
-  the bands cannot give: three invoice totals down the page are three facts the reader has to
-  add up, and "is anything still owed" appeared nowhere. THREE sides — `Invoiced`, a one-row
-  `Adjustments` credit, and `Received` with its rows negative and `success`-toned — so the total
-  states arithmetic rather than a difference, over a `LedgerTotal` carrying `zeroLabel="Paid in
-  full"`. Every row state is on screen: a `peek` door on the multi-line invoice (its lookup link
-  INSIDE the popover, since a button cannot hold a button), a flat `reference` on the single-line
-  one, `meta` qualifying how money came back. `Received` is DERIVED from the charges that carry a
-  payment method — not a second flag to keep in step — and the refundable deposit stays OUT,
-  because a ledger earns trust by summing exactly what its label claims. The fixture is
-  deliberately uneven (an unpriced charge, one issued invoice, a one-row group) because a tidy
-  one verifies nothing.
-  THE ACTION-GATING LAW is still the worked example: a not-ready Issue is DISABLED and the
+  the bands cannot give. THREE sides — `Invoiced`, a one-row `Adjustments` credit, and
+  `Received` with its rows negative and `success`-toned — so the total states arithmetic rather
+  than a difference, over a `LedgerTotal` carrying `zeroLabel="Paid in full"`. Every row state
+  is on screen: a `peek` door on the multi-line invoice (its lookup link INSIDE the popover,
+  since a button cannot hold a button), a flat `reference` on the single-line one, `meta`
+  qualifying how money came back. `Received` is DERIVED from the charges that carry a payment
+  method — not a second flag to keep in step — and the refundable deposit stays OUT, because a
+  ledger earns trust by summing exactly what its label claims. The fixture is deliberately
+  uneven (an unpriced charge, one issued invoice, a one-row group) because a tidy one verifies
+  nothing. THE ACTION-GATING LAW is the worked example: a not-ready Issue is DISABLED and the
   reason is a co-located `Callout` at the gate's SCOPE, once — an invoice's own inconsistency (a
   charged line with no method) on that line, a broken record premise (no customer / invalid tax
   ID) at the section top; self-evident empties stay silent, and NEVER prose beside a CTA.
   Issuing gates on record premises only — never silently on stage. It is also the worked example
-  of **an irreversible action taking an ID, not a captured object** — the confirm re-resolves the
-  invoice from its key, so the quoted total is the one that will be billed even when the press
-  was held for a charge cell's write (data_entry.md § Inline edit).
-- **Document set — the OUTPUT desk, the last WORK section** (the composition rules' output
-  law worked on the record surface: the top is intake, the bottom produces on demand).
-  Forms group PER PARTY on the `SubsectionStack` beat — each party a `SubsectionHeading` +
-  plain `CheckboxInput` rows, the common ones PRE-CHECKED, the long tail folded behind a
-  muted "Show all forms (N hidden)" toggle. Between the pickers and the CTA sit the OUTPUT
-  CONFIG fields (values printed on the forms — e.g. issuing office, prefill-signing-date
-  boolean), each with the input its shape wants. "Create document set" (primary — create IS
-  this scope's job; an empty pick self-evidently disables it, no callout) is DETERMINISTIC
-  template fill, NOT AI — the CTA carries a brief `loading` state and the whole set appears
-  at once (`AgentRun` is for AI work only; dressing deterministic work as an agent run is
-  theater). The produced files list under the action row as `FileRow`s (press → preview;
-  ⋯ → Download / Remove) with "Download all" BELOW the files it acts on. Regenerating
-  REPLACES the set — derived paperwork, never intake; the desk register above keeps what
-  arrived. **READINESS**: a form declares the RECORD FIELDS it reads (`needs`); the fields'
-  HOME stays their DATA section (the colocation law) with descriptions naming their
-  consumers ("printed on the delivery note"). The picker rows ride a
+  of **an irreversible action taking an ID, not a captured object** — the confirm re-resolves
+  the invoice from its key, so the quoted total is the one that will be billed even when the
+  press was held for a charge cell's write (data_entry.md § Inline edit).
+- **Document set — the OUTPUT desk, the last WORK section** (the composition rules' output law
+  worked on the record surface: the top is intake, the bottom produces on demand). Forms group
+  PER PARTY on the `SubsectionStack` beat — each party a `SubsectionHeading` + plain
+  `CheckboxInput` rows, the common ones PRE-CHECKED, the long tail folded behind a muted "Show
+  all forms (N hidden)" toggle. Between the pickers and the CTA sit the OUTPUT CONFIG fields
+  (values printed on the forms — e.g. issuing office, prefill-signing-date boolean), each with
+  the input its shape wants. "Create document set" (primary — create IS this scope's job; an
+  empty pick self-evidently disables it, no callout) is DETERMINISTIC template fill, NOT AI —
+  the CTA carries a brief `loading` state and the whole set appears at once (`AgentRun` is for
+  AI work only; dressing deterministic work as an agent run is theater). The produced files list
+  under the action row as `FileRow`s (press → preview; ⋯ → Download / Remove) with "Download
+  all" BELOW the files it acts on. Regenerating REPLACES the set — derived paperwork, never
+  intake; the desk register above keeps what arrived. **READINESS**: a form declares the RECORD
+  FIELDS it reads (`needs`); the fields' HOME stays their DATA section (the colocation law) with
+  descriptions naming their consumers ("printed on the delivery note"). The picker rows ride a
   `Checklist connected={false} mark="select"` — the SAME compound as Progress, TWO axes apart.
-  Unconnected because these forms are a SET the user picks from rather than a sequence, and a
-  line between them would claim an order the work does not have; `select` because picking a form
-  is a CHOICE, and a filled ring there would read as work already carried out to a reader who
-  learned what a ring means one section above. The row NAMES what is missing in a `ChecklistNote` — "Needs: …"
-  the actual field labels, muted at rest so gaps show WITHOUT checking, warning once checked
-  because it now blocks — and points at the section that owns those fields.
-
-  **It does not collect them.** The row briefly opened a form of its own here, which made every
-  row two things at once (a status and a form) with nothing to say which one the reader was in,
-  and put an editor beside a field's real home where its description and its neighbours live. A
-  checklist REPORTS; the section that owns a value COLLECTS it. A ready form stays SILENT.
+  Unconnected because these forms are a SET the user picks from rather than a sequence; `select`
+  because picking a form is a CHOICE. The row NAMES what is missing in a `ChecklistNote` —
+  "Needs: …" the actual field labels, muted at rest so gaps show WITHOUT checking, warning once
+  checked because it now blocks — and points at the section that owns those fields.
+
+  **It does not collect them.** A checklist REPORTS; the section that owns a value COLLECTS it.
+  A ready form stays SILENT.
 
   Missing fields are the gating law's DEGRADED-BUT-VALID case (they print blank, filled by hand later): Create stays ENABLED, a
   co-located warning `Callout` states the consequence, and the press CONFIRMS via `Alert`.
@@ -452,115 +600,91 @@ billing, and quick-capture templates. Top → bottom:
   a label-left capture form (auto-stamped date/receipt-no, record-prefilled fields, the
   right input each) whose CTA and produced `FileRow` ride an empty-label `DetailRow` — the
   form-action alignment law (data_entry.md), worked.
-- **Activity — what was SAID with the other party**, newest first, directly under Progress: the
-  two answer a reader's first two questions in order, where the record stands and what passed
-  between us to get it there. It is NOT an audit trail and NOT the handoff — see the next bullet
-  for the line, which is what keeps this section from becoming the change log Progress refuses.
+- **Activity — what was SAID with the other party**, newest first, directly under Progress. It
+  is NOT an audit trail and NOT the handoff — see the next bullet for the line.
 
   **The GIST is what the feed is scanned by** — what came of the exchange, in the reader's own
-  words. Building it the other way round is the natural mistake and it makes the feed unreadable:
-  every entry renders as a pair of enum values ("Outbound Meeting"), the substance sits behind a
-  chevron, and a column of near-identical labels defeats the scan the feed exists for.
+  words. Building it the other way round makes the feed unreadable: every entry renders as a
+  pair of enum values ("Outbound Meeting") and the substance sits behind a chevron.
 
   **An entry is a COMMENT, not a `Timeline` row.** `Timeline` renders its label inside the row's
   press target, which is right for derived read-only text ("Stage changed to Won") and wrong for
-  the one thing on an entry a person WROTE — text inside a button cannot be edited where it sits.
-  So the gist is a RESIDENT field and the derived
-  facts sit above it on a muted `xs` **byline** — which way it went, over what, when. Order does
-  not decide the scan; weight does. The byline is small and grey, the prose is `sm` on the page's
-  own ground, and the eye lands on the substance even though it reads second.
+  the one thing on an entry a person WROTE — text inside a button cannot be edited where it
+  sits. So the gist is a RESIDENT field and the derived facts sit above it on a muted `xs`
+  **byline** — which way it went, over what, when. Order does not decide the scan; weight does:
+  the byline is small and grey, the prose is `sm` on the page's own ground.
 
   **ONE anatomy, a body that VARIES.** An entry can be a call, a recorded demo, an email, a
   message or a note typed between meetings — and those differ in what they CARRY, not in what
   they are: all of them answer what-came-of-it, which way, over what, and when. So the four
-  invariants are the row, and the body is a SET OF BLOCKS rather than a shape per kind. A shape
-  per kind writes the same block five times and lets the copies drift, and the sixth kind — the
-  one nobody has thought of — needs a sixth. **Every block is optional and any combination is
-  legal**, because what an entry carries is independent of what it is: a call may arrive as a
-  recording alone, gain a transcript minutes later and a summary after that.
+  invariants are the row, and the body is a SET OF BLOCKS rather than a shape per kind. **Every
+  block is optional and any combination is legal**: a call may arrive as a recording alone, gain
+  a transcript minutes later and a summary after that.
 
   The blocks, in the order they render (`ActivityBody` in `tpl_record` is the worked one):
 
   | Block | What it is | How it renders |
   |---|---|---|
-  | Participants | ONLY what cannot be derived — a third party who joined, an email's From/To. The record is already the counterparty, so naming the obvious attendees is padding | muted line |
+  | Participants | ONLY what cannot be derived — a third party who joined, an email's From/To | muted line |
   | Subject | the one thing an email has that nothing else does | `sm` medium |
   | Media | the exchange itself, recorded | `MediaPlayer` — **give it a box**, it fills its parent and collapses to nothing without one |
   | Transcript | VERBATIM and long; the source a summary was made from | a muted underlined `TextLink` in your own `Pressable`, revealing PLAIN text — see the disclosure exception in composition.md §"Commit & feedback surfaces" |
-  | Prose | what the COUNTERPARTY sent — an email body. Not a second field of ours: an entry offering both a gist and a "note" gives one event two free-text boxes and nothing to tell a writer which to use, and the gist auto-grows, so it already carries whatever length someone wants | `Markdown variant="embedded"` on the page's own ground |
-  | AI prose | what a MODEL wrote | ONE short label INSIDE the `Inset` ("AI summary") — floating above it, a 12px muted fragment over a tinted box reads as an orphan. Name the evidence only where it is NOT on screen: over a player the reader can see, "from the recording" is four words restating a video. Let the label replace the block's own `## Heading` rather than sit above it |
+  | Prose | what the COUNTERPARTY sent — an email body. Not a second field of ours: the gist auto-grows, so it already carries whatever length someone wants | `Markdown variant="embedded"` on the page's own ground |
+  | AI prose | what a MODEL wrote | ONE short label INSIDE the `Inset` ("AI summary"), never floating above it. Name the evidence only where it is NOT on screen. Let the label replace the block's own `## Heading` rather than sit above it |
   | Files | what came with it — EVIDENCE, so it is writable | one `InlineFiles` (`onRemove`, no `onAdd`), mixed pdf/image, previewing in place |
   | Source | where it happened, if openable | `Link` |
 
-  **An entry's files are WRITABLE, on both paths.** A touchpoint is very often about a document —
-  you sent the quote, they sent the PO back — so a feed that displays `files` but offers no way to
-  file one is a read-only surface over a writable model, which reads as a missing feature every
-  time. Two places, because there are two moments: the section's `Composer` stages them on the
-  entry being logged (`actionsButton` + the `files` slot + `sendDisabled`, the three kit slots the
-  comment thread already used), and the entry's own menu attaches to one that already exists.
-
-  **`sendDisabled` is not optional once a composer can attach.** The default blocks send on empty
-  text, which is right for a message and wrong the moment an attachment is the whole point — "here
-  is the signed PO" needs no sentence. Pass `false` while files are staged, `undefined` otherwise
-  so the default returns.
-
-  **Attaching lives on the MENU, not on the file list.** The list's own CTA cannot work on an entry
-  with nothing attached — there is no list to hang it off — so a menu verb that works in every
-  state is the single path, and the list takes `onRemove` alone. Removing CONFIRMS: that file is
-  already in the customer's history, unlike a staged attachment on the composer, which is not yet
-  anything.
-
-  **An entry is its own `FileDropTarget`**, nested inside the record-level one. A file dropped on a
-  conversation belongs to that conversation; routing it to the record's Documents intake instead
-  leaves the reader to relate the two by hand. Nesting is sound rather than lucky — the component
-  stops propagation on every drag/drop event, so the innermost region wins, the outer one neither
-  fires nor lights, and the file is added once. Pass a plain child so the target paints its own
-  drag affordance: with two live regions the drag has to say WHICH one it is about to land in.
-  Both paths — the menu verb and the drop — call ONE append function, because two implementations
-  of "add to this list" is how one of them quietly becomes a replace. A section earns its own
-  target when the drop MEANS something different there; "the same thing, closer" does not.
+  **An entry's files are WRITABLE, on both paths.** Two places, because there are two moments:
+  the section's `Composer` stages them on the entry being logged (`actionsButton` + the `files`
+  slot + `sendDisabled`, the three kit slots the comment thread already used), and the entry's
+  own menu attaches to one that already exists.
+
+  **`sendDisabled` is not optional once a composer can attach.** The default blocks send on
+  empty text, which is wrong the moment an attachment is the whole point. Pass `false` while
+  files are staged, `undefined` otherwise so the default returns.
+
+  **Attaching lives on the MENU, not on the file list.** The list's own CTA cannot work on an
+  entry with nothing attached, so a menu verb that works in every state is the single path, and
+  the list takes `onRemove` alone. Removing CONFIRMS.
+
+  **An entry is its own `FileDropTarget`**, nested inside the record-level one. Nesting is sound
+  rather than lucky — the component stops propagation on every drag/drop event, so the innermost
+  region wins, the outer one neither fires nor lights, and the file is added once. Pass a plain
+  child so the target paints its own drag affordance. Both paths — the menu verb and the drop —
+  call ONE append function. A section earns its own target when the drop MEANS something
+  different there; "the same thing, closer" does not.
 
   **A MESSAGE's attachments are tiles — staged or filed.** The composer's `files` slot takes
   `<FileGrid files={…} itemSize={THUMBNAIL_SIZE} onDisplayRemove={…}>` — the exact component and
-  size the product's own chat composer passes — because a staged file is not yet a document in a
-  list: it is a thing you are about to send, checked by LOOKING at it, and the control that
-  unstages it belongs on the tile. Getting this backwards is easy and invisible: a row of staged
-  attachments looks tidy and quietly makes the composer feel like a file manager.
-
-  Filing it does not turn it into a row — it turns it into a `FilesEditor`. Tiles either way, the
-  same as `chat_user_message` renders a posted message's attachments and the same as this record's
-  Files section, because evidence is recognised by LOOKING (a scanned PO, a photo of a seal). The
-  rows belong to a different object: `InlineFiles` is a labelled FIELD in a `DetailRow` ("Signed
-  contract", "Supplier original"), where the document set has a name, a cardinality and a
-  `blockedReason`. Reasoning from that field to a message's attachments is the mistake to avoid —
-  it is not "the filed version of the same thing".
-
-  **A FILED attachment must be hard to lose; a STAGED one is not yet anything.** That is the whole
-  difference between the two components. A bare `FileGrid` draws a ✕ on every tile, one click from
-  gone — right in a composer, wrong on a record's history. `FilesEditor`'s default view never draws
-  one at all: removal means opening the file and doing it from the gallery, where you are looking
-  at the thing you are about to delete and it still asks, naming the file. Reach for the editor and
-  three things you would otherwise hand-roll come with it — the confirmation, the full-screen
-  gallery, and press-to-open.
-
-  **Give it no children unless a toolbar earns its place.** `FilesEditor` renders its bar from its
-  children and nothing without them, and select mode is reachable ONLY from that bar — so omitting
-  it removes the mode rather than stranding it. A feed of eight entries does not want eight
-  toolbars.
+  size the product's own chat composer passes. A staged file is not yet a document in a list:
+  the control that unstages it belongs on the tile.
+
+  Filing it does not turn it into a row — it turns it into a `FilesEditor`. Tiles either way,
+  the same as `chat_user_message` renders a posted message's attachments and the same as this
+  record's Files section, because evidence is recognised by LOOKING. The rows belong to a
+  different object: `InlineFiles` is a labelled FIELD in a `DetailRow` ("Signed contract",
+  "Supplier original"), where the document set has a name, a cardinality and a `blockedReason`.
+
+  **A FILED attachment must be hard to lose; a STAGED one is not yet anything.** A bare
+  `FileGrid` draws a ✕ on every tile, one click from gone — right in a composer, wrong on a
+  record's history. `FilesEditor`'s default view never draws one at all: removal means opening
+  the file and doing it from the gallery, and it still asks, naming the file. Reach for the
+  editor and three things you would otherwise hand-roll come with it — the confirmation, the
+  full-screen gallery, and press-to-open.
+
+  **Give it no children unless a toolbar earns its place.** `FilesEditor` renders its bar from
+  its children and nothing without them, and select mode is reachable ONLY from that bar — so
+  omitting it removes the mode rather than stranding it.
 
   **Never write a tile size as a number.** The kit exports the two that exist — `THUMBNAIL_SIZE`
-  (a composer attachment, a file tile you are meant to recognise) and `COMPACT_THUMBNAIL_SIZE` (the
-  badge on a list row) — and the product uses nothing else. A literal is how a surface ends up at
-  56 or 84 for no reason anyone can reconstruct, looking subtly unlike the same surface elsewhere;
-  the complaint arrives as "why is it smaller here", which is not a question a constant can raise.
-  For a grid that should FILL its container instead, omit `itemSize` and let `minItemWidth` derive
-  the columns — that is a different decision from the tile's size, not a smaller version of it.
+  (a composer attachment, a file tile you are meant to recognise) and `COMPACT_THUMBNAIL_SIZE`
+  (the badge on a list row) — and the product uses nothing else. For a grid that should FILL its
+  container instead, omit `itemSize` and let `minItemWidth` derive the columns.
 
   **Copy the component, not the layout mode.** Chat's POSTED attachments use `columns={3}
-  partialRowAlign="end"`; the `partialRowAlign` is there because a chat bubble is right-aligned, so
-  a short last row hugging the end is what lines up. A comment on a record is a left-aligned block
-  and inherits neither. Matching chat means the same component and the same size constant, not
-  transplanting a decision that belongs to a bubble.
+  partialRowAlign="end"`; the `partialRowAlign` is there because a chat bubble is right-aligned,
+  so a short last row hugging the end is what lines up. A comment on a record is a left-aligned
+  block and inherits neither.
 
   **One list, not the documents/images split.** That split — documents as rows because a name
   identifies them, images as tiles because content does — holds where files are the SUBJECT (a
@@ -568,53 +692,41 @@ billing, and quick-capture templates. Top → bottom:
   identified by what they are, which is the shape the fee ledger's "Supplier original" already
   uses: one `InlineFiles` taking `application/pdf,image/*`.
 
-  **Delete is the only verb on the entry itself, and it sits in an `ActionMenu` at the TOP RIGHT.** Edit
-  stopped existing the moment the gist became a resident field — the fix that removes a control
-  beats the one that relocates it — and what remains goes where every comment surface puts it,
-  beside the byline rather than in a footer a scroll below the sentence it acts on. The menu is a
-  SIBLING of the content, so nothing nests a button inside another.
+  **Delete is the only verb on the entry itself, and it sits in an `ActionMenu` at the TOP
+  RIGHT** — where every comment surface puts it, beside the byline rather than in a footer a
+  scroll below the sentence it acts on. The menu is a SIBLING of the content, so nothing nests a
+  button inside another.
 
-  Delete belongs there DESPITE the feed being a record — because of what a multi-writer feed
-  actually produces. An extraction filing against the wrong contact and an automation
-  double-filing a recording are not history, and a feed with no way to remove them accumulates
-  garbage it also asks you to trust. Name what leaves with the entry in the confirmation: a
-  count somewhere else is the part nobody expects.
+  Delete belongs there DESPITE the feed being a record: an extraction filing against the wrong
+  contact and an automation double-filing a recording are not history. Name what leaves with the
+  entry in the confirmation.
 
   Only the GIST is editable — everything else is derived, verbatim, an artifact or a model's
-  output, and a counterparty's own email body is a record of what THEY said for the same reason a
-  transcript is not editable. It is resident, with no mode and no verb, and it follows the value:
-  `bare` once written up so it reads as prose, `framed` while empty so it is recognisable as an
-  input. Both halves are in data_entry.md §"A value rendered TWICE is the bug".
-
-  **NO AUTHOR on an entry.** A recording is made by the people in the meeting and merely
-  transcribed by a service, so a byline reading "Recording bot" names the plumbing and fabricates
-  an author for somebody else's conversation. Once that shape is refused, showing an author on the
-  entries that happen to have one is worse than showing none — the reader learns only that we
-  attribute when we can, which is a fact about the pipeline. The record has an Owner; a customer's
-  history does not restate it once per entry. What a machine actually TOUCHED stays visible where
-  it changes how you read something: the `Inset` names an "AI summary", a transcript is labelled
-  verbatim. That is attribution of the CONTENT, which is the only kind that was load-bearing.
-
-  **The blocks SHOW; they are not folded behind a disclosure.** They are what the entry IS, and a
-  control that hides them makes the reader click to discover what the entry already says is there
-  — on every entry, forever. A video is the
-  honest counter-case at 358px and it still shows — it is the most informative thing on a recorded
-  call, the feed folds its own tail, and the byline and gist stay at the top of every entry, so the
-  scan survives a tall one.
-
-  **The TRANSCRIPT keeps its disclosure, and it is the only one.** It is the one block that is
-  unbounded by nature — a machine's verbatim record of half an hour — and the one nobody reads
-  straight through: you open it to check a claim the summary above made. That is what a disclosure
-  is for. An email BODY is prose of unknown length too and still shows, because it is human-written,
-  ordinarily short, and it IS the message rather than the source behind one.
+  output, and a counterparty's own email body is a record of what THEY said. It is resident,
+  with no mode and no verb, and it follows the value: `bare` once written up, `framed` while
+  empty. Both halves are in data_entry.md §"A value rendered TWICE is the bug".
+
+  **NO AUTHOR on an entry.** A byline reading "Recording bot" names the plumbing and fabricates
+  an author for somebody else's conversation. Showing an author on the entries that happen to
+  have one is worse than showing none. The record has an Owner; a customer's history does not
+  restate it once per entry. What a machine actually TOUCHED stays visible where it changes how
+  you read something: the `Inset` names an "AI summary", a transcript is labelled verbatim.
+
+  **The blocks SHOW; they are not folded behind a disclosure.** A video is the honest
+  counter-case at 358px and it still shows — the feed folds its own tail, and the byline and
+  gist stay at the top of every entry, so the scan survives a tall one.
+
+  **The TRANSCRIPT keeps its disclosure, and it is the only one.** It is the one block unbounded
+  by nature — a machine's verbatim record of half an hour — and the one nobody reads straight
+  through: you open it to check a claim the summary above made. An email BODY is prose of
+  unknown length too and still shows: it IS the message rather than the source behind one.
 
   **A block earns its place by carrying what nothing else on the row does.** The failure is not
   a missing block, it is three blocks saying one thing: a participants line, a rep's gist and a
-  machine summary all reporting that the spreadsheet owner was absent. When the summary is good
-  the rep usually adds nothing, and an entry with no note is the normal case rather than an
-  incomplete one. Cut on sight: a label above a block that already labels itself, a fact the
-  record or the row already states, and any block whose content the reader can see rendered
-  directly above it.
+  machine summary all reporting the same absence. An entry with no note is the normal case
+  rather than an incomplete one. Cut on sight: a label above a block that already labels itself,
+  a fact the record or the row already states, and any block whose content the reader can see
+  rendered directly above it.
 
   **Two of those rows are the whole point of the section on a modern record.** A feed fills from
   more than one direction — a person, a chat agent, an extraction off an upload, an automation
@@ -624,50 +736,43 @@ billing, and quick-capture templates. Top → bottom:
   plus a recessed ground — never by a weight nudge. The reasoning and the failure modes are in
   ai_patterns.md §After the run.
 
-  **The transcript folds, and it reveals in place.** It is the source a summary was made from,
-  read rarely and in full when at all — and the reason anyone opens it is to check a claim the
-  summary made, so a dialog is wrong: it takes the claim off screen at the moment they want to
-  compare. Reveal it whole rather than into a scroll box; a scroller inside a scrolling drawer
-  traps the wheel, and a reader who pressed it asked for the length.
+  **The transcript folds, and it reveals in place** — a dialog is wrong: it takes the claim off
+  screen at the moment they want to compare. Reveal it whole rather than into a scroll box; a
+  scroller inside a scrolling drawer traps the wheel.
 
   **The toggle is underlined text, and that is a deliberate exception** (the in-prose disclosure,
   composition.md §"Commit & feedback surfaces"): a muted underlined `TextLink` in your own
   `Pressable` — visible at rest, on the column's own left edge, and carrying no more weight than
   the words. The ink keeps underline honest: blue leaves the surface, muted stays on it.
 
-  **Reveal it PLAIN, with no tinted well.** The toggle directly above already says what the text
-  is; a panel would put two identical recessed boxes on one row meaning two different things — a
-  verbatim record and a machine's reading of it. Keep the `Inset` for the machine's.
+  **Reveal it PLAIN, with no tinted well** — the toggle directly above already says what the
+  text is. Keep the `Inset` for the machine's.
 
   **The capture sits AT the feed**, as a `Composer` — compact until typed into. Logging an entry
   is this section's input, not a distinct AREA of the record, and a section of its own costs a
-  rail entry, which is a claim that there is somewhere else to go.
+  rail entry.
 
-  **The tail FOLDS, it does not page.** A record's feed is read newest-first and the rest is
-  reference; an unbounded one makes every section below it unreachable by scroll. Show the recent
-  few with a toggle naming how many are behind it — a register pages, a record's feed folds.
+  **The tail FOLDS, it does not page.** An unbounded feed makes every section below it
+  unreachable by scroll. Show the recent few with a toggle naming how many are behind it.
 
-  The toggle is a `TextDisclosure`, the same control as the transcript's, because it is the same
-  act: it reveals more of what is already here. It sits on the
-  SECTION's left edge, not the rows': the rows are inset by the disc rail, and at the fold's line
-  the rail has ended, so nothing visible occupies that indent. Same for any other fold on the
-  surface — a document set's "show the rest" is this control too.
+  The toggle is a `TextDisclosure`, the same control as the transcript's. It sits on the
+  SECTION's left edge, not the rows'. Same for any other fold on the surface — a document set's
+  "show the rest" is this control too.
 - **No Handoff section.** Progress owns it: it says where the record SITS and carries the act
-  that moves it, so a second section repeating the handoff was one more place to look for one
-  answer. What that costs is explicit: the sibling record a handoff creates has no home on this
-  surface. It belongs on the Progress stage that produced it if an app needs it back.
+  that moves it. The sibling record a handoff creates has no home on this surface; it belongs on
+  the Progress stage that produced it if an app needs it back.
 
   **Activity is not that trail, and the line is the SUBJECT.** Activity carries what a person
   said or sent to a counterparty; the handoff trail carries where the record moved and which
   field changed. Put desk transitions in Activity and it becomes the audit log this template
-  declined to build — a feed of everything, scanned for nothing.
-
-  Recall is the undo: confirmed, it withdraws the sibling, clears the custody stamp that
-  handoff wrote, and returns the record to the desk BEFORE it — one step, never a jump to the
-  first desk, which would silently drop the desks between. History is NEVER erased (the trail
-  keeps both marks) and the CTA returns, so redo is possible. **Only the LATEST handoff offers
-  Recall.** Undoing a superseded one would leave the record behind a sibling that still exists
-  — the stage and the linked records would disagree — so a walk-back is one handoff at a time.
+  declined to build.
+
+  Recall is the undo: confirmed, it withdraws the sibling, clears the custody stamp that handoff
+  wrote, and returns the record to the desk BEFORE it — one step, never a jump to the first
+  desk, which would silently drop the desks between. History is NEVER erased (the trail keeps
+  both marks) and the CTA returns, so redo is possible. **Only the LATEST handoff offers
+  Recall.** Undoing a superseded one would leave the record behind a sibling that still exists,
+  so a walk-back is one handoff at a time.
 - **Danger zone** — with the full section anatomy (heading + description) like every other
   section; the fenced red `DangerZone` card is the section's BODY.
 - A LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`) — **the rail is the page's COMPLETE
@@ -677,25 +782,42 @@ billing, and quick-capture templates. Top → bottom:
   current-section bar opening a section-picker POPOVER, anchored to that bar's own button, whose
   items carry the same `current`. Anchored, not a `Modal`: a modal escapes its container, so the
   same surface hosted in a drawer would take the whole window over the register behind it.
-- **The page layout is the DOCS layout — the reading column is CENTRED IN THE VIEWPORT, and
-  the rail sits in its left gutter.** The `ScrollView` is FULL-WIDTH — **never cap it at
-  `CONTENT_MAX`, or the scroll container becomes the column and the gutters go wheel-dead**
-  (a capped scroller leaves the page either side of it ignoring the wheel).
-  Inside it sits one centred row (`width: "100%"`,
-  `maxWidth: GUTTER * 2 + CONTENT_MAX`, `alignSelf: "center"`, `flexDirection: "row"`) of
-  three parts: a gutter RESERVED for the rail (`width: GUTTER` — the rail's own `RAIL_W`
-  PLUS `RAIL_GAP`, the docs' 3rem of breathing room, so the rail never butts against the
-  column), the reading column (`flex: 1, minWidth: 0`), and an EMPTY right gutter of the
-  same `GUTTER` that BALANCES the rail — without it the column sits half a rail right of
-  centre. (The public docs pages get this balance for free: their right-hand TOC is the
-  counterweight. A record surface has no TOC, so the gutter is simply reserved.) The rail is
-  NOT window chrome: no full-height border, not glued to the window edge — it FLOATS over
-  its reserved gutter (`position: "absolute"`, `left` mirroring the row's centring maths),
-  so it stays put while the record scrolls **without** web-only `position: sticky` (which RN
-  does not type) and without stealing the page's scrollable width. The rail earns its place
-  only while the centred column still has room beside it (`pageWidth >= GUTTER * 2 + 560`);
-  below that it collapses to the pinned bar. Sizing the column is the SHELL's job — inner
-  blocks are plain `width: "100%"`, never a second `maxWidth` + `alignSelf: "center"`.
+- **The page layout is the DOCS layout — the reading column is CENTRED IN THE VIEWPORT, and the
+  rail sits in its left gutter.** The `ScrollView` is FULL-WIDTH — **never cap it at
+  `CONTENT_MAX`, or the scroll container becomes the column and the gutters go wheel-dead** (a
+  capped scroller leaves the page either side of it ignoring the wheel). Inside it sits one
+  centred row (`width: "100%"`, `maxWidth: GUTTER + CONTENT_MAX + PANEL_GUTTER`, `alignSelf:
+  "center"`, `flexDirection: "row"`) of three parts: a gutter RESERVED for the rail (`width:
+  GUTTER` — the rail's own `RAIL_W` PLUS `RAIL_GAP`, the docs' 3rem of breathing room, so the
+  rail never butts against the column), the reading column (`flex: 1, minWidth: 0`), and a right
+  gutter of `PANEL_GUTTER` (`PANEL_W` + the same `RAIL_GAP`) that BALANCES the rail — without it
+  the column sits half a rail right of centre — and that the discussion panel then floats over,
+  exactly as the rail floats over its own. The rail is NOT window chrome: no full-height border,
+  not glued to the window edge — it FLOATS over its reserved gutter (`position: "absolute"`,
+  `left` mirroring the row's centring maths), so it stays put while the record scrolls
+  **without** web-only `position: sticky` (which RN does not type) and without stealing the
+  page's scrollable width. Both gutters earn their place only while the reading column still
+  clears its FLOOR beside them (`pageWidth >= PAGE_PAD * 2 + GUTTER + PANEL_GUTTER +
+  CONTENT_FLOOR` — every term the row spends, `PAGE_PAD` included, or the check passes while the
+  column sits under the floor the same code declares); below that they collapse onto the pinned
+  bar. Sizing the column is the SHELL's job — inner blocks are plain `width: "100%"`, never a
+  second `maxWidth` + `alignSelf: "center"`.
+
+### Anything that ADVANCES a record must be able to walk it back
+
+This holds wherever the progression is rendered — a stage CTA on a register row, a tick in a
+drawer's checklist, a bulk action over a selection, the handoff compound below. **Every control
+that moves a record forward ships its inverse, in reach of the person who pressed it.**
+
+A one-way control makes a misclick permanent, and stage CTAs invite the misclick: the row leaves
+the tab the moment it is pressed, so the feedback for "that was wrong" is the record vanishing,
+with no obvious way back.
+
+The undo belongs **beside the forward act, as its secondary** — the same pairing the kit already
+uses for a commit and the control that undoes it. Do not bury it in an `ActionMenu`. Where a
+stage is genuinely irreversible (money has moved, a document has been filed, something left the
+building), the honest answer is not a missing undo — it is a confirmation *before* the act, and
+copy that says why it cannot be taken back.
 
 ### The handoff shape — a CONNECTED checklist, and where it lives
 
@@ -707,57 +829,47 @@ It is NOT its own template. A handoff is something a RECORD does, so it renders
 that record — see `tpl_record` § Progress, where the desks (Sales → Operations → Accounting) are
 `ChecklistGroup`s and the milestones they produce are the rows.
 
-**Two levels, because a desk and a milestone are not peers.** The ladder was briefly one flat run
-of eight — "Operations" beside "Collected" — which asked the reader to know which name was a PLACE
-and which was an EVENT. Grouping the milestones under the desk that produces them says it in the
-shape instead.
+**Two levels, because a desk and a milestone are not peers.** One flat run — "Operations" beside
+"Collected" — asks the reader to know which name is a PLACE and which is an EVENT; grouping the
+milestones under the desk that produces them says it in the shape instead.
 
-**A group is a name and nothing else.** No control: a phase owns no completion of its own, so any
-ring it wore would report without responding — and one identical to the pressable rings beneath it
-invites the press it refuses, which is worse than showing nothing, because the reader clicks and
-the product says nothing back. No BODY either: a condition or an act hung off a heading leaves the
-reader working out which of the rows below it they were about.
+**A group is a name and nothing else.** No control: a phase owns no completion of its own, and a
+ring identical to the pressable rings beneath it invites the press it refuses. No BODY either: a
+condition or an act hung off a heading leaves the reader working out which of the rows below it
+they were about.
 
-**Rows tick ONE at a time, and position is the highest stamp.** That is what lets one click say
-"everything up to here": ticking `Delivered` puts the record there and the rungs below it read
-done immediately. The alternative — a parent tick that fills its children — marks the same rows
-but INVENTS their dates, writing today onto milestones that happened on days nobody recorded. A
-rung the record passed without a recorded day shows a BLANK date, which is the honest answer to
-"when" and stays one click from being filled.
+**Rows tick ONE at a time, and position is the highest stamp**: ticking `Delivered` puts the
+record there and the rungs below it read done immediately. The alternative — a parent tick that
+fills its children — marks the same rows but INVENTS their dates, writing today onto milestones
+that happened on days nobody recorded. A rung the record passed without a recorded day shows a
+BLANK date, one click from being filled.
 
 **A checklist REPORTS.** It does not collect and it does not preview: a field some section owns is
 NAMED as a gap by a `ChecklistNote` whose `action` jumps there, never edited in the row and never
 rendered as a value. The row's OWN stamp (`trailing`) and a value with no other home
 (`ChecklistField`) are the two exceptions.
 
-**It replaced a per-desk CHECKLIST without the line, and that swap is the lesson.** Ticking boxes
-described the WORK; it never said where the record SAT, so the reader inferred position from which
-group still had unticked rows — and the handoff CTA sat in a different section entirely, the act
-divorced from the state that gated it. A connected run says the position outright, and the act
-rides the row that owes it. `connected={false}` is for rows that are genuinely N independent
-items; a record's own progress asserts sequence.
+A connected run says the position outright, and the act rides the row that owes it.
+`connected={false}` is for rows that are genuinely N independent items; a record's own progress
+asserts sequence.
 
 Built on `checklist` (`Checklist`, `ChecklistGroup`, `ChecklistItem`, `ChecklistNote`,
 `ChecklistActions`, `ChecklistField`), which composes over `Stepper` — `Stepper` renders POSITION,
 this adds the anatomy that turns a position into a workspace.
 
-Three rules the anatomy holds, each learned from getting it wrong:
+Rules the anatomy holds:
 
 - **Only the OWED row carries an act.** A control on an unreached row invites acting out of
   order — and where position is derived from the highest stamp, one stray press jumps the record
   past the desk that owns it. On a passed row it re-offers something already done.
 - **A condition belongs to its row.** "Sent back", "rejected", "waiting on the customer" are
-  facts about ONE position, so they render inside it (`ChecklistNote`) rather than as a `Callout`
-  above the run, which reads as "something is wrong with this record" and sits nowhere near the
-  control that answers it — and nowhere near enough to say WHICH row it is about.
+  facts about ONE position, so they render inside it (`ChecklistNote`) rather than as a
+  `Callout` above the run, which sits nowhere near the control that answers it.
 - **A passed row stays correctable** — its stamp is editable, which is how a date recorded wrong
-  gets fixed and how a record walks BACK. Otherwise a value typed wrong becomes unreachable the
-  moment the record moves on, and the only fix is direct table access.
-- **The stage that OPENS gets stamped by the act that opened it**, and the TERMINAL act is not
-  a handoff. Handing off asks whom (a dialog) and writes that answer into the receiving stage's
-  own fields — coming up blank re-asks a question just answered. Finishing has no receiving
-  desk, so it asks for confirmation and nothing else; routing it through the same dialog is how
-  a template ends up asking "Assignee at Closed" and then confirming nothing.
+  gets fixed and how a record walks BACK.
+- **The stage that OPENS gets stamped by the act that opened it**, and the TERMINAL act is not a
+  handoff. Handing off asks whom (a dialog) and writes that answer into the receiving stage's
+  own fields. Finishing has no receiving desk, so it asks for confirmation and nothing else.
 
 **Altitude rule**: the pipeline is ONE record's progress. N records each at their own stage is
 a REGISTER (`tpl_item_list`) with a derived stage column — the same ladder module feeding both,
@@ -784,8 +896,7 @@ grouped sections, and the aligned rows. It demonstrates:
 - A trailing `ActionMenu` (the `⋯` overflow — a `danger` Remove behind a confirm `Alert`).
 - CUSTOM pressable cells (files, the action link) hover with the **background-tint WASH**
   (`zinc-100`) — the ROW's own hover language, distinct from the field frame a `bare` editor
-  fades in on its own hover. (The row washes; the field's edge draws — the two
-  hover languages, one per surface.)
+  fades in on its own hover.
 - Per-group add rows that pre-set the group's field (align with the exported `gridRowStyle`),
   and a Draft-from-notes CTA.
 
@@ -871,10 +982,10 @@ proposes parameters. The panel carries the single Download.
 Look-up-and-explain (classification, tariff/fee lookup, policy Q&A, a spec/compliance desk).
 Describe the subject on the LEFT (`Composer` + `AgentRun`), the agent RANKS the matching
 candidates (nearest matches, the top one wearing a Recommended `Badge`), you pick one and its
-structured ANSWER pins on the RIGHT — the code, the exact breakdown as hand-composed spec
-rows, policy `Callout`s, `Confidence`, and `Sources`. The flow is input → matches → pick, not
-a single confident verdict: classification is ambiguous, so the alternatives are first-class.
-Refine the description in a follow-up and the ranking updates.
+structured ANSWER pins on the RIGHT — the code, the exact breakdown as hand-composed spec rows,
+policy `Callout`s, `Confidence`, and `Sources`. The flow is input → matches → pick, not a single
+confident verdict: the alternatives are first-class. Refine the description in a follow-up and
+the ranking updates.
 
 ### The document desk — in `tpl_record`
 
@@ -889,17 +1000,15 @@ so review opens at the top):
 - **Extract** (read the documents, fill the record) — a `DetailTable` of proposed values, each
   row a label plus a `DiffValue` and its own Keep/Drop, with `useChangeSet` holding the
   verdicts. **Editing IS the review**; the four shapes are ONE component — an add omits
-  `before`, a removal omits `after` (the struck value IS the change), an update passes both,
-  and a conflict is a `DiffValue` on its placeholder over `CardSelectItem` candidates plus a
+  `before`, a removal omits `after` (the struck value IS the change), an update passes both, and
+  a conflict is a `DiffValue` on its placeholder over `CardSelectItem` candidates plus a
   type-another-value option, Keep gated until one is picked. Proposed line items arrive as a
   `Table` with `DiffMark` leading each row — a set of lines reads like the ledger it is about.
   The line table also works the ATTACHMENT case: a dropped invoice's proposal is WHICH LINE it
   belongs to, so the Document column is a `DiffValue` whose sides are file chips, and a file
-  replacing one already filed shows both with the superseded one struck. Its untouched lines
-  are deliberate — a fixture where every row changed would prove nothing about the screen that
-  matters, and they are why an untouched row draws NO mark: the eye finds the filled discs
-  among the blanks without reading the column.
-  Keep-all + one outcome-named Apply commit.
+  replacing one already filed shows both with the superseded one struck. Its untouched lines are
+  deliberate — they are why an untouched row draws NO mark. Keep-all + one outcome-named Apply
+  commit.
 - **Cross-check** (compare the documents against the record and each other) — ranked,
   display-only `Finding`s the human acts on, closing in a recorded verdict.
 - **Edit with AI** — the `askAi` handoff: dialogue-shaped file iteration happens in the