@lotics/ui 11.8.10 → 12.0.0

package/AGENTS.md

@@ -1,5 +1,18 @@
 # @lotics/ui — the UI reference index
 
+> **Upgrading to v12 from 11.x.** Two exports were removed: **`CommentComposer`** (compose
+> comments with THE kit `Composer` — attach via `actionsButton`/`files`; `CommentList` is
+> unchanged) and **`DetailRow.info`** (field annotations are explicit — use the new
+> **`DetailRow.description`** under the value and **`DetailRow.error`**, the `FormField`
+> vocabulary; heading/card `info` ⓘ props are untouched). Visual behavior changes:
+> `SubsectionStack` is SPACE-ONLY (32px beat, no hairlines — titles carry the grouping),
+> `Section` heading gap 12→16, `DetailTable` row gap 6→8, `DetailRow` rows top-align with
+> label/control/trailing centered on the first control line, `Timeline` grew to 32px
+> discs / 16px icons / 40px minimum rows, `TextInputField` paints a WHITE surface on any
+> background (it was transparent — identical on the white canvas, visible on tinted
+> panels), and the inline editors' resting chip gained 6px vertical padding (identical for
+> one-line values; multi-line resting content now breathes).
+
 > **Upgrading to v11 from ≤10.x — the type scale was re-slotted.** The display sizes gained the
 > missing `##` step: `xl` is now 22/24 (section title), `xxl` is 28/32 (page/record title — the
 > OLD `xl` look), and the new `xxxl` is 32/48 (hero numbers — the OLD `xxl` look). Migrate an

package/docs/catalog.md

@@ -170,8 +170,8 @@ gap-spaced region + `SectionHeading`/`SectionHeadingTitle`/`SectionHeadingMeta`;
 component — children are the body), `Subsection` (+ `SubsectionHeading`/
 `SubsectionHeadingTitle` — the named group INSIDE a section, `###` lg-semibold title),
 `SectionStack` (the flat page's content column — owns the fixed 56px beat + hairline between
-top-level blocks), `SubsectionStack` (the same law one step tighter — fixed 24px beat +
-hairline between a section's `Subsection` groups), `SectionCard`, `PageHeader` /
+top-level blocks), `SubsectionStack` (a section's `Subsection` groups — fixed 32px beat,
+SPACE-ONLY: titles carry the grouping, hairlines stay at the section level), `SectionCard`, `PageHeader` /
 `PageContent`, `Stack`, `Spacer`, `Divider`, `Accordion`, `Tabs`, `SegmentedControl`,
 `Stepper`, `DangerZone` (the destructive section — delete/archive — set apart at the bottom
 of a record/settings surface).
@@ -396,8 +396,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `arrow-left` `MenuButton` reads as another nav ITEM, not an exit). `onPress` +
   `accessibilityLabel` (defaults to `label`, else the locale's `nav.back` — "Back" /
   "Quay lại"). Bare, it's the chevron-left `IconButton` (lg, secondary) heading a
-  screen/panel; pass **`label`** to name where back GOES ("Danh sách") and it becomes ONE
-  pressable over glyph + words — never an icon button beside unclickable prose.
+  screen/panel; pass **`label`** to name where back GOES ("Danh sách") — the SAME
+  circular glyph with the destination beside it, ONE pressable over disc + words —
+  never an icon button beside unclickable prose.
 - **`link`** — `Link`: the EXTERNAL hyperlink — fixed underline+blue + `role="link"`;
   `onPress` only (the consumer wires the opener).
 - **`text_link`** — `TextLink`: underlined text that's optionally an `onPress` action or an
@@ -489,7 +490,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 ### Form & text inputs
 
 - **`text_input_field`** — `TextInputField`: the standard text input (multiline grows via
-  the auto-grow engine; `shortcut` renders a `ShortcutBadge`).
+  the auto-grow engine; `shortcut` renders a `ShortcutBadge`). Its surface is WHITE on any
+  background — on a tinted panel the input still reads as an open well, never blending into
+  the tint; override via `style` only when a surface genuinely wants otherwise.
 - **`number_input`** — `NumberInput`: numeric input; `format` for currency/units.
 - **`search_input`** — `SearchInput`: the search box for toolbars/filters.
 - **`form_field`** — `FormField` + `useFormField`: label / description / error / `optional`
@@ -567,10 +570,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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`); optional `info` renders an ⓘ popover
-  hugging the label — the row-label member of the one `info` vocabulary (`CardHeaderTitle` /
-  `SectionHeadingTitle` / `SubsectionHeadingTitle`); pass `undefined` to hide it (callers may
-  gate it on their own state). `DetailTable`: the compound parent of
+  belong IN the value via `InlineNumberInput format`). The FIELD-ANNOTATION vocabulary (same
+  names + meanings as `FormField`), always EXPLICIT — a row never hides guidance behind an ⓘ:
+  **`description`** = persistent guidance, under the VALUE (stacked mode mirrors the form
+  order label · description · control); **`error`** = field-level failure under the value,
+  danger + alert semantics (the `Inline*` editors already render their own transient save
+  errors — don't wire both); invalid/cross-field STATE = a co-located `Callout`; **`flat`**
+  on a flat-text value row (`InlineStatic`, plain `Text`) tucks the annotation up by the
+  control band's slack so its gap matches a chip row's.
+  `DetailTable`: the compound parent of
   a row STACK — `labelWidth` (default 130) / `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
@@ -645,17 +653,23 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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
+  owns GEOMETRY only (row minHeight 32, gap 12, control/title alignment, the `meta`/
+  `expansion` indent, ONE `trailingWidth` so assignee cells column-align) while content
+  stays composed — `control` takes the `CheckCircle` (omit onChange = read-only ring; a
+  PICKER list puts a `CheckboxInput` here and sets `controlWidth={24}` so the indent
+  tracks), children the struck transparent `InlineTextInput` or plain `Text`, `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; wide surfaces use
-  `trailing`; never both. SUGGESTIONS are never rows: offer the commons as `SuggestionChip`s
-  under the list. Close the list with `CaptureRow`. There is deliberately NO monolithic Task
-  component — richer task-management rows compose their own anatomy directly.
+  second line indents to the title's text edge so the TITLE keeps the full width; wide
+  surfaces use `trailing`; never both. `expansion` is a BLOCK slot under the row on the
+  same indent — a transient inline fill editor, a drill-down — rendered only while open
+  (`tpl_record`'s Document set rows are the worked example). SUGGESTIONS are never rows:
+  offer the commons as `SuggestionChip`s under the list. Close the list with `CaptureRow`.
+  There is deliberately NO monolithic Task component — richer task-management rows compose
+  their own anatomy directly. Hand-rolling this checkbox-row anatomy in a template is how
+  alignment drifts — the compound exists so it can't.
 - **`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;
@@ -892,7 +906,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   expands for long text + attachments (`pills` + attachment slots, controlled or
   uncontrolled `value`, `onSend`/`onStop`, `sendDisabled` override).
 - **`agent_run`** — `AgentRun` + `AgentRunStep`/`AgentRunItem` + `resolveToolMeta`: the live
-  streaming work feed.
+  streaming work feed. AI work ONLY — deterministic work (template fill, an export) shows a
+  `loading` state on its trigger and delivers at once; dressing it as an agent run is theater.
 - **`agent_progress`** — `AgentProgress`: its compact, floating, expandable form — a
   composer's working state.
 - **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: calibrated
@@ -916,8 +931,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`finding`** — `Finding` + `FindingComparison` + `FindingSeverity`/`FindingLabels`: one
   ranked AI-check insight — severity word · title · detail · `Sources` · children slot; the
   expected-vs-actual body with the emphasized delta; the `finding` locale slice.
-- **`comments_thread`** — `CommentList` + `CommentComposer` + the
+- **`comments_thread`** — `CommentList` + the
   `ThreadComment`/`ThreadMember`/`ThreadFile` types: the record comments thread.
+  Composing is THE kit `Composer` (never a bespoke comment box): attach via its
+  `actionsButton`, staged files in its `files` slot; render attachments with
+  `renderFiles` (a pressable `FileGrid` → gallery preview — see tpl_record).
   **Limitation:** labels are not provider-wired — pass `CommentListLabels`.
 
 ### Utility hooks & plumbing

package/docs/composition.md

@@ -63,8 +63,9 @@ restyle a heading level per-page.
   `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold, with the same `info` ⓘ
   affordance as `SectionHeadingTitle`; siblings — a `Badge`, a
   `SectionHeadingMeta`, an action — ride the heading row's right edge). Sibling subsections stack
-  in a **`SubsectionStack`** (the same hairline law one step tighter: a fixed 24px beat + hairline
-  between groups — no margins, no hand-rolled dividers); a headingless `Subsection` is the
+  in a **`SubsectionStack`** (a fixed 32px beat, SPACE-ONLY — subsection titles carry the
+  grouping; hairlines belong to the SECTION level, one rule per altitude; no margins, no
+  hand-rolled dividers); a headingless `Subsection` is the
   section's lead group. Group leads INSIDE a subsection's rows are `md` medium at most. Do NOT
   hand-roll `Text weight="semibold"` group leads inside a section, and never promote a subsection
   to its own section-level heading just to separate it.
@@ -377,6 +378,58 @@ All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping
   `danger` (and its quieter `danger-secondary`) marks destructive — that's the whole axis. No
   "success"/green button. Decision UIs put positive/negative color on the STATUS (dot) and verdict
   (colored `Text`), not the buttons.
+- **Create buttons carry NO `+` icon** — "Add fee", not "+ Add fee". Section-heading creates are
+  `secondary` (one primary per scope, reserved for the scope's main verb); a create promotes to
+  `primary` only where creating IS the surface's job — the register page's New, an empty state's
+  action. (The icon-only `+` `IconButton` — a composer's attach — is a different thing and keeps
+  its glyph.)
+
+## The action-gating law — disabled + the reason as a co-located Callout
+
+A not-ready CTA is **DISABLED**, and the reason is a **persistent co-located `Callout` at the
+gate's SCOPE, once** — never prose beside the button, never revealed only on press:
+
+- A **local inconsistency** (a charged line without a payment method) → a callout in ITS group,
+  beside its own disabled CTA.
+- A **broken record-level premise** (no customer attached, invalid tax ID) → ONE callout at the
+  section top — not repeated beside every affected button.
+- **Self-evident empties stay silent**: an empty band's disabled Issue, a composer's Send on
+  empty input, a dialog's confirm until its one required adjacent field is filled — nothing to
+  explain, so nothing is said.
+- An **expected not-yet** (a stage that simply hasn't arrived) is not a problem — it gets no
+  callout; if that leaves a disabled button undiscoverable, remove the gate rather than narrate
+  it (a filled surface whose CTA stays silently dead is a trap).
+- A **DEGRADED-but-valid action is not a gate.** When the action can still produce a legitimate
+  outcome (generating forms whose optional fields print BLANK and get filled by hand), the CTA
+  stays **ENABLED**: the co-located callout states the CONSEQUENCE (not a block), and the press
+  CONFIRMS via `Alert` — name what's missing, offer "Cancel" (back to the inline fixes) and the
+  proceed verb. Reserve DISABLING for actions that cannot produce their outcome at all.
+
+## Field annotations & linked records
+
+- **The field-annotation vocabulary** (same names + meanings on `FormField` and `DetailRow`,
+  always EXPLICIT — never a hidden ⓘ on rows): **`description`** = persistent guidance (under
+  the VALUE on a horizontal row — the label column has no room for prose; stacked mode wears
+  the form order label · description · control); **`error`** = field-level failure under the
+  value, danger + alert semantics (the `Inline*` editors already render their own transient
+  save errors); cross-field / record-level STATE = a co-located `Callout`. Rows share ONE
+  alignment law: the row top-aligns and label · control · trailing each center within the
+  first control line — a tall value block never drags the label. A FLAT value row
+  (`InlineStatic`, plain `Text`) sets **`DetailRow flat`**: the annotation tucks up by the
+  control band's slack so the perceived gap under the text equals the gap under a chip —
+  the band's invisible bottom half must never read as a hole above the description.
+- **A LINKED record never renders as field rows** — another record's data must not read as
+  fields on THIS one. The reference shape (`tpl_record`'s Customer/Handoff, inline — no
+  wrapper component): a BORDERED, fully pressable box (glyph anchor · identity · facts
+  stacked vertically) whose press opens the record's detail drawer (read-only rows + the
+  navigate verb); the action row sits INSIDE the box — destructive LEFT in danger, go-to
+  RIGHT. Editing the linked record happens on ITS page, never here. The press ANATOMY:
+  the box is a `PressableRow` (role-less, non-focusable surface — hover wash spans the
+  nested verbs) with the keyboard DOOR — an EMPTY absolutely-positioned `role="button"`
+  sibling carrying the tab stop, the accessible name and the focus ring — beneath the
+  content, and the interior verbs lifted above it via `zIndex: 1`. NEVER `role="button"`
+  on a container with interactive descendants: a button must not contain a button
+  (invalid HTML, a hydration error, and AT double-announcement).
 
 ## Color discipline — solid / tint / ramp + ONE accent
 
@@ -454,11 +507,15 @@ that praises it is marketing.
 - **Instructions live where action is needed** — empty states, callouts, form-field
   descriptions: imperative, one concrete step ("Drop the CI + PL here."). A heading never
   instructs.
+- **NEVER prose beside a CTA.** No consequence narration next to a button ("Handing off moves
+  the record to Operations — fields stay editable after") and no label chips beside headings
+  ("Collected separately") — the CTA's label names where it goes, and STATE speaks through
+  the gating law below, not through standing text.
 - **Restatement is the second noise mode.** A description that repeats what the screen already
   shows — the title, the subsection names below it, the table's columns — carries zero
   information and fails even though it "states content". Useful copy states an **invisible
   truth**: an invariant of the data, a boundary ("P&L lives in the accounting app, not here"),
-  a linkage ("the HS code here feeds the customs declaration"), or a consequence ("past the
+  a linkage ("the commodity code here feeds the customs declaration"), or a consequence ("past the
   cut-off, the box misses the sailing").
 - **The deletion test**: if removing the line changes nothing for the reader, remove the line —
   `description` is optional for a reason; when no invisible truth is worth stating, omit it.

package/docs/data_entry.md

@@ -19,11 +19,27 @@ in [the templates](./templates.md) (`examples/tpl_*.tsx`).
 | CHARGES that bill onto documents | [**billing**](#billing--the-invoice-document-is-the-unit) (`tpl_record` Billing section) | the invoice document is the unit |
 | a record's FEE/charge SUMMARY | [**`Ledger`**](#fee-summary--ledger) (worked example: `tpl_item_list` drawer) | grouped money lines, one emphasized total — no bars/charts |
 | a multi-value TAG field | [**`Select multi`**](#tag--multi-value-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 |
+| ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker` — column when options carry descriptions, row when short) | required single-select, one tap, every option visible |
+| ONE pick from a BIG registry (ports, projects…) | on a RECORD surface: **`InlineSelect searchable`** (search lives in the popover); on a form/attach surface: **`Combobox`** with `value` | an inline row stays an inline editor — a persistent search input breaks the surface's grammar |
+| a YES/NO on a record | **`CheckboxInput`** as the `DetailRow` value | a boolean needs no editor mode |
 | a STATUS with terminal outcomes | [**disposition**](#disposition--lifecycle-status-is-asymmetric-by-phase) (open → resolve → revise) | guides the decision |
 | FILES | [**attachment field**](#attachments--a-full-add--preview--delete-field) (dropzone + grid + gallery) | add / preview / delete |
 | a state TRANSITION mid-flow | [**stage gate**](#stage-gates--tiered-by-weight) (popover / dialog by weight) | right-sized friction |
 
+**The right-input-per-field law.** A field gets the control its SHAPE wants, never a default
+text box — and on a record surface radio/checkbox render as PERSISTENT controls (the control
+is the best display of the value; prose-shaped values and registry picks stay inline
+editors). Rich `InlineSelect` options carry a description line (`renderOptionContent` — it
+shows in the resting row too; the `data` generic types option payloads). A DEPENDENT field
+renders only while its parent value makes it real — never a disabled ghost row. Worked rows:
+`tpl_record`'s Classification group.
+
+**The form-action alignment law.** On an open page, a label-left form's action row rides the
+form's OWN GRID — an empty-label `DetailRow` puts the CTA (and what it produces) exactly on
+the CONTROL COLUMN, the same left edge the user just filled, and inherits stacked mode on
+narrow containers. A right-floated button aligns to nothing; only OVERLAY footers
+(`DialogFooter`/`DrawerFooter`) right-align. Worked: `tpl_record`'s Delivery receipt.
+
 ## Inline edit — the preferred way to edit an existing record
 
 When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a
@@ -107,10 +123,14 @@ null). `InlineTagSelect` (multi) needs no `onClear` — an empty set is already
 ### The row stack — `DetailTable` + `DetailRow`
 
 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
+`labelWidth` / `trailingWidth` / `minHeight` set ONCE on the parent, plus the 8px 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'.
+narrower than its neighbours'. Rows share ONE alignment law: the row top-aligns and label ·
+control · trailing each center within the first control line — annotations (`description` under
+the value, `error` in danger with alert semantics; both indented to the chip's 8px text inset)
+grow the row downward without dragging the label. The full annotation vocabulary lives in
+composition.md §Field annotations.
 
 ### The editability affordance
 
@@ -127,10 +147,9 @@ border) but stays FLAT and non-interactive, so editable (chip) vs read-only (fla
 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).
+"kg"/"$" belong IN the value via `InlineNumberInput format`) — see the "General" section of
+`tpl_record`, which also reads top→bottom as a full record surface. 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
 

package/docs/templates.md

@@ -20,6 +20,11 @@ the package index is [../AGENTS.md](../AGENTS.md).
 - **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.
 - 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.
@@ -60,12 +65,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.
+   never hide, never hard-block. One sanctioned disclosure: a TRANSIENT fill-what's-missing
+   editor expanding under a just-checked item is progressive disclosure of the gate, not
+   shape change — it edits the record field in place and collapses 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.
+   model is right. (HOMING is what's forbidden, not repair: the output section may host a
+   transient fill editor that saves onto the record field — same storage, the field's home row
+   shows the value — rendered only while the field blocks a checked output.)
 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.
@@ -207,43 +216,133 @@ Oldest-first auto-allocates; each `AllocationRow` can be filled or typed.
 
 ### `tpl_record` — THE record surface
 
-Create-then-refine taken all the way: **"New" is ONE CLICK** (no dialog, no form) — it
-creates a fresh Draft and the surface IS the editor; everything refines in place. It absorbed
-the old order-form, inline-record, intake, settings, billing, and quick-capture templates.
-Top → bottom:
-
-- A `RecordSummary` header (identity · status · the one metric) over its key-fact
-  `DetailTable`, then a Details `DetailTable` — one shared column grid, auto-stacking when
-  narrow.
-- **The 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 a registry lookup keyed by tax ID, un-gating billing;
-  Remove (danger) sits low and detaches the link (the customer stays in the book) → the
-  find-or-create search, whose custom row opens the create `Dialog` rendering the SAME
-  inline-chip table + Fetch.
-- **Files** — `FileDropzone` add, gallery preview, delete.
-- **Billing, owned by a later desk** (gated until the record reaches that stage), in the
-  inline vocabulary: each invoice is a hairline-set band; charge amounts are 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`. Plus
-  a validated receipt and a separate refundable deposit.
-- **The lifecycle is a HANDOFF CHAIN** (e.g. Sales → Operations → Accounting → Closed): a
-  Tasks section speaking the full task-list grammar — a clearable Group-by `FilterChip`
-  (Desk/Assignee/Status) plus assignee/status filter chips derive the groups (empty groups
-  drop, EXCEPT desk groups — the journey stays visible; desk heads keep their owner dots,
-  assignee heads are `MemberChip`s), the add-a-task `CaptureRow` at the TOP landing on the
-  current desk, rows riding the `Checklist`/`ChecklistRow` compound with per-task
-  `InlineMemberSelect` assignees and a per-row `menu` (move to next desk · danger Delete),
-  and suggested tasks as `SuggestionChip`s. EVERY desk's rows edit — the stage gates the
-  handoff and Billing, never task editing (planning ahead on a later desk is normal work).
-  **Per-stage handoff CTAs are NEVER blocked** — open tasks warn and carry over.
-- Also the settings shape: Preferences switch rows + a `DangerZone`.
-- A LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`) jumps between the sections and
-  scroll-spies the active one; on narrow containers it becomes the pinned current-section
-  bar opening a section-picker `Modal`.
+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:
+
+- A MINIMAL header: `RecordSummary` (title · subtitle ONLY — no stage chip, no metric; Tasks
+  carries progress, Handoff 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` (tasks done · documents
+  · to collect).
+- **GENERAL — the MAIN details, FIRST in the rail**; every later section is supplementary.
+  A `SubsectionStack` (space-only beat) of a headingless LEAD group (the key facts) plus
+  named groups (e.g. Order / Fulfilment / System — system identifiers get a HOME, not a
+  per-row badge). Every group's `DetailTable` repeats the same `labelWidth`/`trailingWidth`
+  so the grid aligns through the groups. The FIELD-ANNOTATION vocabulary is the worked
+  example here: `description` (persistent, under the value, incl. a deliberately LONG one)
+  and `error` (derived, e.g. overdue Due) — always explicit, never an ⓘ; the inline editors
+  demo their own transient save error (a throwing `onSave`). The Classification group works
+  **the right-input-per-field law**: a field gets the control its SHAPE wants, never a
+  default text box — ≤5 exclusive options the user should see → `RadioPicker` (column when
+  options carry descriptions, row when short), a longer closed list → `InlineSelect` (rich
+  options carry a description line, shown in the resting row too), a pick from a big
+  REGISTRY → `Combobox` (search is the input), a boolean → `CheckboxInput`; a DEPENDENT
+  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 coworker's note is the first thing read on a shared record: `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.
+- **Tasks** — the full task-list grammar: clearable Group-by `FilterChip` (+ assignee/status
+  chips), the `CaptureRow` on top, `Checklist`/`ChecklistRow` rows with `InlineMemberSelect`
+  assignees and per-row menus, suggestions as `SuggestionChip`s; groups divide via the
+  `SubsectionStack` beat with plain text heads (no dot badges).
+- **Documents** — the Agents "Document desk" pattern (shared with `tpl_documents` — change
+  it in BOTH): the register `Table` (search · Add files) whose selection feeds the
+  `FloatingActionBar` → ONE "Use AI" fork (extract / cross-check / edit-with-AI). Every
+  row's leading visual is a `FileThumbnail` in ONE square 32px slot — an image file fills
+  it as a real thumbnail, a document centers its badge in it — never a bare `FileBadge`
+  (mixed footprints misalign the identity column). ONE
+  sanctioned divergence: GENERATION — on the record page this desk holds what ARRIVES and
+  Create moves to the Document set OUTPUT section below; `tpl_documents` (no output
+  pipeline on its page) keeps the toolbar "Create documents" dialog.
+- **Customer — the LINKED-RECORD reference implementation** (inline, no wrapper component):
+  another record's data NEVER renders as field rows on this one — a BORDERED, fully
+  pressable box (glyph anchor · identity · facts stacked VERTICALLY, legible at any width)
+  whose press opens the detail drawer (read-only rows + the navigate verb); the action row
+  sits INSIDE the box — destructive (Remove, `danger`) LEFT, go-to (Open record) RIGHT.
+  Built on `PressableRow` + the keyboard door, never `role="button"` on the box — the
+  press anatomy is [composition.md's linked-record law](./composition.md).
+  Empty state = the find-or-create search, custom row → the create `Dialog` (tax ID + Fetch;
+  its field errors ride `DetailRow error`, not a loose line).
+- **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" is create-then-refine: a blank fee opens straight in the drawer.
+- **Billing** — every group a `Subsection` on ONE beat: per-invoice bands (charge chips with
+  ghost list prices + one-tap "Standard …" fill, "How paid…" selects), the collect band
+  (owns the total + the receipt), the deposit. 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 — a band-local problem (charged line missing its method) in the band, 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.
+- **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 `Checklist`/
+  `ChecklistRow` (`controlWidth={24}` for the `CheckboxInput`) — the compound owns the row
+  geometry and the `meta`/`expansion` indent; hand-rolling the anatomy is how alignment
+  drifts. Every not-ready row shows BOTH the mark and the explicit trigger — the mark says
+  WHAT (the `meta` line: 12px `circle-alert` + "Needs: …", muted ink until checked,
+  warning once it blocks), the trigger says HOW: a colored `TextLink` ("Add missing
+  fields", link-blue) BESIDE the label — an inline row action; a `Button` here outweighs
+  the row. It toggles the TRANSIENT fill editor in the row's `expansion` ("These values
+  save onto the order and unlock the form.") — `FormTextInput`s (label + the consumer
+  hint as `description`), Cancel / "Save fields" (secondary — the section keeps ONE
+  primary, disabled while a draft is empty). Checking NEVER expands anything by itself —
+  an expansion that only a side effect reveals is no affordance. Save writes the record
+  field (its home row shows the value) and the panel collapses; mark + trigger vanish =
+  ready, and a ready form stays silent. Drafts are keyed BY FIELD, so two forms needing
+  the same field share one draft and one Save resolves both. The trigger HIDES while its
+  panel is open — the panel's Cancel is the closer. Missing fields are the gating law's
+  DEGRADED-BUT-VALID case (those fields print blank, filled by hand later): Create stays
+  ENABLED, the co-located warning `Callout` states the consequence ("… print blank unless
+  filled above"), and the press CONFIRMS via `Alert` — per-form "form — fields" lines,
+  Cancel back to the inline fixes / "Generate anyway". Only an empty pick disables, and
+  silently. A form can also be DATA-conditional (the hazardous-goods note renders only
+  while the record's Hazardous goods boolean is set — record data may reshape the list,
+  output selection never does).
+- **Delivery receipt — the QUICK-ISSUE form, its OWN section** (in the rail): one document
+  issued from a handful of facts at a known moment (a handover, an inspection, a visit) —
+  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 — the audit trail**: a `Timeline` (32px discs, 40px rows) of every change —
+  who and when — with DRILL-DOWN `details` (a field change carries its From → To diff, a
+  document entry a pressable `FileRow` → preview) and LIVE appends from the surface's real
+  actions (issue, fees, handoff).
+- **Handoff — ONCE.** Handing off CREATES the next desk's record on ITS table and links it
+  here: the dialog collects the receiver (`MemberSelect`, confirm disabled until chosen) +
+  an optional note; confirm writes the trail mark and the SIBLING record, shown as the same
+  linked-record box (its drawer holds the reference info + Open record + **Recall**). After
+  the handoff there is NO further CTA. Recall is the undo: confirmed, it withdraws the
+  sibling and returns the desk — history is NEVER erased (the trail keeps both marks) and
+  the CTA returns, so redo is possible.
+- **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
+  map** (every section including Danger zone; subsections never join it) — headed by the
+  bare circular `BackButton`; it scroll-spies the active section, and on narrow containers
+  becomes the pinned current-section bar opening a section-picker `Modal`.
 - **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**
@@ -253,17 +352,16 @@ Top → bottom:
   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 —
-  `position` is `"absolute" | "relative" | "static"`) 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"`.
+  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"`.
 
 ### `tpl_tasks` — the quick list