@hotmeshio/long-tail 0.10.2 → 0.10.4

package/docs/api/http/roles.md

@@ -268,6 +268,7 @@ Returns all roles with metadata and usage counts.
 | `metadata_schema` | `object \| null` | JSON Schema declaring the expected shape of `lt_escalations.metadata` for this role. Drives faceted-query key autocomplete and creation-time validation |
 | `properties` | `object` | Free user-owned bag — icons, colors, tags, etc. No reserved keys |
 | `ops_visible` | `boolean` | When `true`, the role appears as a station on the `/operations` view |
+| `enforce_schema` | `boolean` | When `true`, every resolve surface validates submitted payloads against this role's form schema and rejects violations with `422` (`code: schema_validation`) — see [Schema Enforcement](../../schema-enforcement.md) |
 | `parent_role` | `string \| null` | Parent role in the process dependency graph; `null` for root stations |
 | `sla_minutes` | `number \| null` | Target resolution time in minutes (capacity setting) |
 | `target_per_hour` | `number \| null` | Intended throughput — items resolved per hour (capacity setting) |
@@ -366,6 +367,7 @@ When the update changes `form_schema` or `metadata_schema`, the new pair is snap
 | `metadata_schema` | `object \| null` | JSON Schema for `lt_escalations.metadata` |
 | `properties` | `object \| null` | Free user-owned bag |
 | `ops_visible` | `boolean` | Include in the `/operations` view |
+| `enforce_schema` | `boolean` | Turn server-side resolver schema validation on/off |
 | `parent_role` | `string \| null` | Parent in the process dependency graph |
 | `sla_minutes` | `number \| null` | SLA target in minutes |
 | `target_per_hour` | `number \| null` | Throughput target (items per hour) |

package/docs/design-principles.md

@@ -0,0 +1,234 @@
+# Design Principles
+
+The design system behind the dashboard and every generated x-lt-* form. One
+token vocabulary, one value discipline, one form doctrine — the built-in pages
+and the forms customers author render from the same rules.
+
+---
+
+## 1. Tokens are the system
+
+Every color, size, radius, and spacing knob flows through a `--lt-*` CSS
+variable declared in `dashboard/src/styles/globals.css`. Nothing paints a raw
+hex. A registered stylesheet (`branding.customCss` / `branding.themes` in
+`start()`) can therefore restyle the entire product — including full dark
+themes — with zero source changes. Midnight is the standing proof: if a color
+escapes the token system, it glows in the dark.
+
+Deliberate exceptions, each carrying a stated constraint in code: the
+signature pad (the exported PNG is a document — ink on white), customer
+iframes (their HTML assumes a white canvas), OAuth brand marks, theme-picker
+swatches, and overlay scrims.
+
+## 2. Color — the value discipline
+
+Chroma is spent, not spread.
+
+- **Surfaces are near-neutral.** Hover fills, section bands, and borders
+  carry only a whisper of the theme hue. Chroma never lands on a large
+  rectangle — a colored slab makes every real accent invisible.
+- **One elevation logic, both polarities.** The page carries the base wash
+  (a light theme tint by day, the deep shade at night); sections and sheets
+  are distinct surfaces on it (white paper by day, the deeper well at
+  night); fields are wells that step AWAY from their surface (darker than
+  white by day, lighter than the shade at night). Light is Midnight
+  inverted — never a flat white page with white sections.
+- **The accent appears in small doses**: links, buttons, checks, pills,
+  section labels, focus states. Because it is scarce, it reads as "act here."
+- **Dark themes are the same principle, inverted** — near-black neutral
+  surfaces, the identical accent discipline. Midnight is not a different
+  design; it is the same design at night.
+- **Status is information, not decoration.** Text-safe status tokens
+  (≥4.5:1) for words; brighter `-graphic` variants for dots, bars, and
+  charts (≥3:1).
+- **The focus fill is the one ambient accent moment** — entering a field
+  earns the tint.
+
+## 3. Text — black speaks, color acts
+
+- One neutral near-black ramp shared by every light theme: `#171717` body,
+  `#373737` labels, `#646464` helper, `#8C8C8C` low-emphasis meta. Labels are
+  never theme-colored — a tinted label is indistinguishable from a link.
+  If it's colored, it must be clickable.
+- **11px floor.** No informative text below `text-2xs`. Quaternary tone is
+  reserved for large or decorative text (≥3:1).
+- **Headings**: near-black (`#333333`), small caps, weight 300, generous
+  sizes — `heading-1` (2.125rem) / `heading-2` (1.5rem) / `heading-3`
+  (1.25rem). The size carries hierarchy; the light weight keeps it elegant.
+  Mono identifiers (role keys, workflow types, topics) stay code-styled,
+  never small-caps.
+
+## 4. Fields and controls
+
+- **One recipe** (`.field/.input/.select/.textarea`): white body, light
+  neutral border, 3px radius (`--lt-radius-field`), border deepens to accent
+  and fill takes the theme tint on focus. Every field-like control uses the
+  recipe or the tokens — no bespoke field styling.
+- **Width follows content, capped by the measure:**
+  - Generated forms hold a readable measure (`max-w-form`, 56rem). A wide
+    monitor gets margin, never a 2000px input.
+  - Selects size to their content, floored at 16rem for presence — a
+    one-word choice never stretches across the page. The floor yields to
+    the cell (`min(16rem, 100%)`): CSS lets min-width beat max-width, so
+    a bare floor would overflow a narrow column.
+  - Number and date inputs hold a hand-sized width (12rem; datetimes
+    16rem) — fixed-length values never stretch to the measure.
+  - Text, textarea, email, and url fill their cell — prose-length content
+    deserves the measure.
+  - Widgets follow the same split. Prose surfaces (code editor, markdown,
+    rich text, uploads) fill the cell. The signature pad holds its natural
+    document proportion (25rem, the 400×150 export) — the PNG is the
+    artifact, and stretching the pad stretches the document.
+- **Decisions are never checkboxes.** A decision is an enum opening on an
+  explicit disabled **Choose…** placeholder. The user picks; nothing is an
+  implicit first option, and there is no way back to unchosen.
+- Checkboxes exist only inside checklists — confirmations of work, not
+  choices.
+- **Item length and selection mode determine list geometry.**
+  Sentence-length require-all *rituals* read top-down, one per row — the
+  vertical stack is deliberate. Short pick-any *tags* (reasons, categories)
+  flow horizontally as selectable chips: thumb-sized pills that wrap,
+  selection in solid accent. Never stack six two-word items into six
+  full-width rows — endless y with an empty x is a dead layout.
+- **Required is marked, everywhere.** Every required input — text, select,
+  number, upload, checkbox, or checkbox group — carries the red asterisk at
+  its label. A require-all checklist is required by definition and marked
+  like the rest. Required or optional is never a guess.
+
+## 5. Layout — the canonical shell
+
+```
+┌──────────────── Header (full width) ────────────────┐
+│ left nav │        main viewport        │ right panel │
+└──────────────── EventFeed (full width) ─────────────┘
+```
+
+- Header and event-stream footer span the full width. The left nav and the
+  global right SlidePanel are flex siblings of the main viewport — content
+  narrows when either opens; nothing overlays it. Pages fill the right panel
+  via `useShellPanel()`. The DocsDrawer is the full-screen overlay for
+  markdown.
+- iPad (768–1366) is the floor target: page padding clamps down, the sidebar
+  auto-collapses below 1024, nothing depends on hover alone.
+- Structure comes from typography, whitespace, and divider lines — never
+  rounded-bordered cards, never gradient fades. Sections sit on a barely
+  sunken band with an accent left rule.
+
+## 6. The form doctrine
+
+The reference implementation is `examples/workflows/acme-stations` — mimic it.
+
+1. **Facts first, as a dictionary.** Read-only work-item facts render as a dense
+   label/value spec sheet (`x-lt-display: "dictionary"`), not form rows.
+2. **One explicit decision** gates the form. Until it is made the page shows
+   facts, the decision, nothing else — even sign-off waits.
+3. **Linear reveals.** Each outcome fades in exactly the section it needs
+   (`x-lt-showIf` value matches). The enter animation makes the
+   cause-and-effect visible in time: click Reject, watch the report arrive.
+4. **The left/right law.** Left and Right always render side by side, Left
+   first — as dictionary pairs (two-column dictionaries fill row by row, so
+   consecutive items share a row) and as inputs (`x-lt-column-group` pairs
+   them in one cell, the 2×2).
+5. **Checklists**: standard confirmations may arrive pre-checked
+   (formDefaults) — the standard is the default and the resolver unchecks
+   what isn't true. The work item's own custom work arrives unchecked; those
+   clicks are the record. `x-lt-require-all` guards completion.
+6. **Every input carries a `title` and one instructional `description`
+   line — no input goes without.** The anatomy is fixed and identical for
+   every input kind: label, instruction, control, in that order. The
+   anatomy is a declared column, never an accident of width — the label is
+   a block, so a narrow control (a number, a short select) can never ride
+   sideways beside it when the instruction line is absent. Inputs that
+   share a row carry instructions of similar length so their controls align
+   across the row; a bare input beside an instructed one is a consistency
+   defect, in both content and alignment. The WHY — reference tables,
+   consequences, vocabulary — lives in `x-lt-help` beside the form.
+7. **Sign-off last.** A short audit note with a live counter.
+8. Hidden conditional fields still submit their defaults; resolver contracts
+   treat empty as absent.
+
+## 7. Copy — the economist tone
+
+The escalation `description` is the detail page's title: a short noun
+phrase naming the artifact — "Final QA — ACME-1042 · wgt-8127" —
+never a sentence, never an instruction, never a status report.
+
+Say what to do. Speak to the actor, in the imperative, always: "Pick Reject
+to file a report" — never "Reject files a report." The system is never the
+subject of an instruction, and passive voice never appears. One line per
+instruction; consequences ride the same sentence ("Resolve — the widget moves
+on to assembly"). Reference tables over paragraphs. Never preachy, never
+motivational, never "you're the first human — do well." State what a thing is
+and does, never what it lacks.
+
+## 8. Motion
+
+Motion explains causality; it never decorates. Reveals fade in tied to the
+choice that caused them (200–300ms enter). Errors shake once and settle.
+Panels slide as flex siblings so content reflows rather than being covered.
+Nothing loops, nothing floats.
+
+## 9. Accessibility floors
+
+- Body and label text ≥4.5:1; large/meta text and graphics ≥3:1.
+- Every input is label-associated; errors and helpers ride
+  `aria-describedby`; the errors panel click-focuses the field
+  (`data-field-key` is a contract).
+- Disabled forms use `inert` — out of the tab order, not just grayed.
+- `color-scheme` follows the theme so native controls match the surface.
+
+## 10. Responsive — geometry follows the container
+
+1. **Geometry follows the container, not the viewport.** Side panels, the
+   facet drawer, and the nav rail narrow containers below any viewport
+   breakpoint — a `md:`/`lg:` variant on a content grid is a defect.
+   Viewport variants are lawful only in the shell frame (header, nav rail),
+   where the viewport is the container.
+2. **Thresholds are named container tokens** (tailwind `containers`):
+   `@dict-inline` 22rem · `@grp-cols` 26rem · `@form-cols` 34rem ·
+   `@filters` 72rem · `@dict-pairs` 38rem · `@table` 48rem. Components use
+   the names, never raw rem values. A fold threshold is sized for the
+   HEAVIEST content its component carries — escaping to the condensed
+   format early beats ever letting a bar wrap.
+3. **The dictionary reflow ladder** — the poster child. The same
+   label/value pairs render as: two pairs per row at `@dict-pairs`; one
+   label|value pair per row at `@dict-inline`; label stacked over value
+   below. Pairing order never changes across geometries.
+4. **A table row IS a dictionary.** Below `@table`, tables fold into dense
+   console-style cards — identity columns become the title line, the rest
+   fold into label/value pairs on the dictionary ladder. **Tables never
+   scroll horizontally** — master lists use `layout="fixed"` so a table
+   physically cannot outgrow its container. Fixed columns cut both ways:
+   **cell content never bleeds into a neighbor** — every cell clips
+   (`overflow-hidden` on the `td`) and every text-bearing pill or label
+   truncates with an ellipsis (`max-w-full` + `truncate`), carrying the
+   full value in `title` for hover reveal.
+5. **The column budget, disclosed both ways.** The floor set — identity,
+   owner, urgency, age — always renders. Enrichment columns (workflow,
+   metadata facets) return only when the table's container has room
+   (`showFrom: '@split' | '@wall'`); below that they fold into card pairs.
+   The list is a jumping-off spot: the metadata cell carries the refine
+   icons — filter within the role, search across roles, shift+click to AND
+   facets — the ELK-style drill the whole product surfaces.
+6. **Refine icons are always visible enough to tap** — half-opacity at
+   rest, full on hover. Hover-only affordances do not exist on the floor.
+7. **Disclosure order**: drop priority-3 columns, fold priority-2 into
+   pairs, keep priority-1 always.
+8. **Touch parity**: every hover-only affordance has a tap equivalent —
+   the iPad floor has no hover.
+9. **The header diet ladder** (below lg): mark-only logo, icon+count links,
+   secondary actions fold into the user menu, the nav rail becomes a
+   drawer behind a menu button.
+10. **Sticky elements are never containers** — `container-type` breaks
+   `position: sticky` on the same element; wrap the geometry element
+   instead.
+
+## 11. Never
+
+Raw hex in components. Chroma on large surfaces. Theme-colored labels.
+Text below 11px. Decisions as checkboxes. Implicit select defaults.
+Full-width one-word inputs. Tag lists stacked as rows. Unmarked required
+fields. Inputs without instruction lines. Passive voice or system-voice
+copy. Horizontal scroll. Viewport breakpoints on content grids. Cards and
+gradient fades. "Back to X" links. Polling. Preachy copy. Customer names —
+the showcase brand is always Acme.

package/docs/hitl/design.md

@@ -0,0 +1,228 @@
+# Design
+
+Long-tail ships one design system. The built-in pages and every form generated
+from your schemas render from the same rules, so a form you author with plain
+JSON Schema and `x-lt-*` tokens arrives already styled, responsive, accessible,
+and themed. This page explains the principles in the terms that matter when you
+author schemas and copy, the rules the renderer applies to errors, and how a
+deployment plugs its own stylesheet in through static config.
+
+The full internal doctrine lives in
+[`docs/design-principles.md`](../design-principles.md); the reference form
+implementation is `examples/workflows/acme-stations`.
+
+---
+
+## The principles, from the author's seat
+
+### Tokens carry everything
+
+Every color, size, radius, and spacing value in the product flows through a
+`--lt-*` CSS variable. Your schemas never mention style — they declare
+structure (`title`, `description`, sections, `x-lt-*` tokens) and the renderer
+supplies the design. This is what makes theming total: a registered stylesheet
+restyles the dashboard and your generated forms in one stroke, including full
+dark themes.
+
+### Color means "act here"
+
+Surfaces stay near-neutral with a whisper of the theme hue; the saturated
+accent appears only in small doses — links, buttons, checks, focus states.
+Because color is scarce, anything colored reads as actionable. The same rule
+governs your content: labels and copy render near-black, status renders through
+the status tokens, and the accent marks the interactive. A form that "adds
+color" through its copy fights the system; a form that relies on structure gets
+the emphasis for free.
+
+### Text: black speaks, color acts
+
+Labels resolve from your schema (`title` first, then title-cased keys — see
+[form.md](form.md)) and render in the neutral near-black ramp. Headings are
+small-caps, light-weight, generously sized; section names you declare in
+`x-lt-section-options` render in that voice. Nothing informative renders below
+11px.
+
+### Fields behave by declaration
+
+- **Width follows content.** Forms hold a readable measure; selects size to
+  their options; numbers stay hand-sized; prose fields fill their cell. You
+  never set widths.
+- **Decisions are enums.** A decision field renders as a select opening on an
+  explicit disabled **Choose…** placeholder — the resolver picks; nothing is
+  an implicit default. Model decisions as `enum`, never as booleans.
+- **Checkboxes are confirmations of work**, and they live in checklists.
+  Sentence-length require-all rituals render one per row; short pick-any tags
+  (reasons, categories) flow as selectable chips. The renderer chooses from
+  your item lengths and `x-lt-require-all`; override with `x-lt-variant`.
+- **Required is marked everywhere.** Every field in `required` — and every
+  require-all checklist — carries the red asterisk. Declare `required`
+  honestly and the form communicates it uniformly.
+
+### The form doctrine
+
+The shape that makes a resolver fast:
+
+1. **Facts first, as a dictionary** — read-only work-item facts render as a dense
+   spec sheet (`x-lt-display: "dictionary"`), not as form rows.
+2. **One explicit decision gates the form** — until the outcome is chosen,
+   the page shows facts and the decision, nothing else.
+3. **Linear reveals** — each outcome fades in exactly the section it needs
+   (`x-lt-showIf`), so cause and effect are visible in time.
+4. **Pairs render side by side** — `x-lt-column-group` keeps Left and Right
+   together; two-column dictionaries fill row by row.
+5. **Sign-off last** — a short audit note closes the form.
+
+### Responsive comes free
+
+Geometry follows the container, not the viewport. Your dictionary reflows from
+paired columns to stacked labels as space narrows; tables fold into dense
+console cards instead of ever scrolling horizontally; the form grid drops to
+one column when a side panel narrows it. Authors declare structure once; every
+width from an iPad to a wall monitor is handled.
+
+---
+
+## Error display
+
+Errors follow fixed rules; your schema and copy determine only their content.
+
+**At the field.** The first failing check on a visible field renders inline:
+the control's border turns to the status-error token, the field shakes once and
+settles, and the message appears beneath the control. Format guards fire on
+blur; everything else fires on submit. The message rides `aria-describedby`,
+so screen readers announce it with the field.
+
+**The errors panel.** A blocked submit opens the right-side panel with the
+full list — one row per issue, showing the field's label (derived exactly as
+the form derives it, so `title` pays off here too) and the message. Clicking a
+row scrolls to and focuses the field. The panel is `aria-live`; the count
+("3 issues to resolve") updates as fixes land.
+
+**Server enforcement, same surfaces.** Roles with schema enforcement enabled
+validate the submission server-side and reject invalid payloads with a
+canonical `422` carrying per-field errors. The form maps those onto the same
+inline and panel surfaces — a resolver sees one error language whether the
+check ran in the browser or on the server.
+
+**Hidden fields are exempt.** Fields hidden by `x-lt-showIf` at submission
+time are skipped by required validation — an unchosen branch never blocks the
+chosen one.
+
+**Error copy is instruction.** An error message states the fix, in the
+imperative, in one line: "Enter a quantity between 1 and 4." It names what to
+do next, never narrates what went wrong at length, and never speaks as the
+system ("invalid input detected"). When you supply custom validation messages,
+write them as the direct instruction the resolver should follow.
+
+---
+
+## Recommendations — write instructions that work
+
+The renderer guarantees the anatomy: label, one instruction line, control, in
+that order, for every input. Your job is the words. The tone is a sparse
+economist: say what to do, to the actor, and stop.
+
+| Write | In place of |
+|-------|-------------|
+| Pick Reject to file a report | Reject files a report |
+| Confirm each custom item on the widget | Items should be confirmed |
+| Enter the count from the work ticket | Quantity field |
+| Resolve — the widget moves on to final QA | When resolved, the widget will be moved on |
+
+- **Every input carries a `title` and one `description` line.** The
+  description is the instruction: imperative, actor-addressed, one line.
+  Inputs sharing a row should carry instructions of similar length so their
+  controls align.
+- **Consequences ride the same sentence.** "Pick Complete to send the widget
+  to final QA" tells the actor what to do and what happens, in one
+  breath. A second sentence is almost always the start of a paragraph nobody
+  reads.
+- **The escalation `description` is a title, not a sentence.** It names the
+  artifact — "Addons — ACME-1042 · wgt-8127" — because it becomes the detail
+  page's heading and the list's summary line.
+- **The WHY lives in `x-lt-help`.** Reference tables, vocabulary, and
+  decision consequences belong in the side panel, in markdown, where the
+  resolver can consult them without the form carrying paragraphs. Keep it
+  factual; skip the motivation.
+- **Let defaults do the routine work.** Standard confirmations arrive
+  pre-checked via `formDefaults` — the resolver unchecks what isn't true.
+  The work item's own custom items arrive unchecked; those clicks are the record.
+
+---
+
+## Plugging in a stylesheet
+
+A deployment takes control of the design system through the `branding` block
+of the static start config. `customCss` is appended to the dashboard
+stylesheet; `themes` registers full themes that join the header theme picker
+alongside the built-ins. Both are served at `GET /api/settings/custom.css` and
+load before first paint.
+
+```typescript
+import { start } from 'long-tail';
+
+await start({
+  // ...database, workers, roles...
+  branding: {
+    appName: 'AcmeAdmin',
+
+    // Targeted overrides — adjust tokens globally.
+    customCss: `
+      :root {
+        --lt-radius-field: 6px;
+        --lt-measure-form: 48rem;
+      }
+    `,
+
+    // A full registered theme. Author every --lt-* token under the
+    // [data-theme] selector; the id becomes the data-theme attribute and
+    // the theme appears in the header picker with its swatch.
+    themes: [
+      {
+        id: 'acme-slate',
+        label: 'Acme Slate',
+        swatch: '#334155',
+        dark: true,
+        css: `
+          [data-theme='acme-slate'] {
+            color-scheme: dark;
+            --lt-color-scheme: dark;
+
+            --lt-surface: 15 23 42;          /* page wash */
+            --lt-surface-raised: 30 41 59;   /* header, sheets */
+            --lt-surface-sunken: 10 16 30;   /* section bands */
+            --lt-surface-hover: 40 53 74;
+            --lt-surface-border: 51 65 85;
+
+            --lt-field-bg: 34 46 66;         /* fields step lighter than the page */
+            --lt-field-border: 71 85 105;
+            --lt-field-focus: 41 56 81;
+
+            --lt-accent: 125 170 255;
+            --lt-accent-hover: 155 190 255;
+            --lt-heading: 170 200 255;
+
+            --lt-text-primary: 233 238 248;
+            --lt-text-secondary: 185 197 219;
+            --lt-text-tertiary: 140 155 182;
+            --lt-text-quaternary: 105 120 148;
+          }
+        `,
+      },
+    ],
+  },
+});
+```
+
+Values are RGB triplets (`15 23 42`, not `#0F172A`) so the system can apply
+alpha through `rgb(var(--lt-*) / <alpha>)`. The bundled Midnight theme
+(`examples/themes/midnight.ts`) is a complete worked example covering every
+token family — surfaces, fields, accent, text ramp, and the status family —
+and is registered through this exact mechanism; deployment themes are
+first-class in the same way.
+
+Keep the elevation logic when authoring a theme: the page carries the wash,
+sections are distinct surfaces on it, and fields step away from their surface
+— darker than the sheets in a light theme, lighter than the shade in a dark
+one. A theme that holds those relationships inherits the whole system's
+legibility; the tokens make it a matter of picking six surface values.

package/docs/hitl/form.md

@@ -4,6 +4,26 @@ The dashboard renders forms automatically from JSON Schema. No frontend code nee
 
 ---
 
+## Field Labels
+
+A field's label resolves in order:
+
+1. The `title` keyword — the author's explicit label, always wins.
+2. Snake/kebab keys title-cased: `left_quantity` → `Left Quantity`. All-caps tokens inside a key keep their casing (`po_number` → `Po Number`, `PO_number` → `PO Number`).
+3. Single-token keys pass through unchanged: `PO`, `SKU`, `LEFTQUANTITY`.
+
+Declare `title` on every field whose key isn't already a readable label — it is the difference between `LEFTQUANTITY` and `Left Quantity` everywhere the field faces a human: the form, the dictionary display, and the errors panel.
+
+```json
+{
+  "properties": {
+    "LEFTQUANTITY": { "type": "number", "title": "Left Quantity" }
+  }
+}
+```
+
+---
+
 ## Field Types
 
 | JSON Type | Renders As |
@@ -46,7 +66,7 @@ Use `format` on any `string` field to get a specialized input:
 
 ## Required Fields
 
-Fields listed in `required` show a red asterisk and block submission when empty:
+Every required input — text, select, number, upload, or checklist group — shows a red asterisk at its label and blocks submission when empty. A checklist with `x-lt-require-all` is required by definition and carries the asterisk too. Required or optional is never a guess.
 
 ```json
 {

package/docs/hitl/iframe.md

@@ -54,7 +54,7 @@ const WORKBENCH_FORM_SCHEMA = {
 // Workflow side — the wait is a normal conditionLT; the iframe submits the payload
 const design = await conditionLT<{ stl_url: string }>(signalId, {
   role: 'cad-designer',
-  description: 'Design the orthotic insole for this order.',
+  description: 'Design the widget for this order.',
   escalation_payload: JSON.stringify({ workbenchId, companyId }),
 });
 if (design) {

package/docs/hitl/x-lt-display.md

@@ -0,0 +1,56 @@
+# Dictionary Display (`x-lt-display`)
+
+Read-only facts — order numbers, quantities, product names — render as a dense definition list when dictionary display is requested: labels beside values in a compact grid, a run of consecutive facts merged into one list. This is the display for reference data the resolver reads but never edits.
+
+`x-lt-display: "dictionary"` applies at three levels; the nearest wins:
+
+| Level | Placement | Applies to |
+|-------|-----------|-----------|
+| Field | on the property | that field |
+| Section | `x-lt-section-options` at the schema root | read-only fields in that section |
+| Schema | at the schema root | every read-only field |
+
+Only read-only fields (`readOnly: true`) render as dictionary rows. Editable fields keep their inputs, and content widgets (`markdown`, `attachment`, `image`) keep their block rendering regardless of display settings.
+
+```json
+{
+  "x-lt-layout": "two-column",
+  "x-lt-display": "dictionary",
+  "properties": {
+    "po":             { "type": "string", "title": "PO",       "readOnly": true, "x-lt-section": "The Order" },
+    "order_id":       { "type": "string", "title": "Order ID", "readOnly": true, "x-lt-section": "The Order" },
+    "left_quantity":  { "type": "number", "title": "Left Qty", "readOnly": true, "x-lt-section": "The Order" },
+    "right_quantity": { "type": "number", "title": "Right Qty","readOnly": true, "x-lt-section": "The Order" },
+    "approved":       { "type": "boolean", "x-lt-section": "The Decision" }
+  }
+}
+```
+
+The four order facts render as one two-column dictionary under "The Order"; `approved` stays a checkbox.
+
+## Section Options (`x-lt-section-options`)
+
+Per-section display settings live at the schema root, keyed by section name:
+
+```json
+{
+  "x-lt-section-options": {
+    "The Order": { "display": "dictionary", "columns": 2 }
+  }
+}
+```
+
+| Option | Values | Meaning |
+|--------|--------|---------|
+| `display` | `"dictionary"` | Read-only fields in the section render as dictionary rows |
+| `columns` | `1` \| `2` | Dictionary column count; defaults to 2 in two-column layouts, 1 otherwise |
+
+Two-column dictionaries fill **row by row**: consecutive items share a row, so ordering controls pairing — declare `left_quantity` and `right_quantity` together and they render side by side, Left first.
+
+## Value formatting
+
+Strings and numbers render as-is. Booleans render as Yes / No. Objects and arrays render as compact JSON. Empty values (`null`, `""`) render as an em dash.
+
+Labels resolve the same way as form labels: the `title` keyword when present, otherwise the field key with snake/kebab separators title-cased. Declare `title` on every fact — `"PO"`, `"Order ID"` — for labels that read like product copy rather than column names.
+
+Presentation tokens (`x-lt-display`, `x-lt-section-options`, `x-lt-column-group`) never affect validation or the submitted payload; a schema renders identically strict with or without them.

package/docs/hitl/x-lt-layout.md

@@ -58,6 +58,25 @@ Sections are ordered by the first field that carries the section name (respects
 
 ---
 
+## Nested Column Groups (`x-lt-column-group`)
+
+In a two-column layout, consecutive fields sharing an `x-lt-column-group` name render inside a single grid cell as their own two-column pair — a 2×2 arrangement. One nesting level is supported; the token is ignored when the schema layout is not `two-column`.
+
+```json
+{
+  "x-lt-layout": "two-column",
+  "properties": {
+    "left_quantity":  { "type": "number", "title": "Left Qty",  "x-lt-column-group": "quantities" },
+    "right_quantity": { "type": "number", "title": "Right Qty", "x-lt-column-group": "quantities" },
+    "notes":          { "type": "string", "format": "textarea" }
+  }
+}
+```
+
+The two quantities share one cell of the outer grid (each taking half of it) while `notes` occupies a normal cell beside them.
+
+---
+
 ## Payload Binding (`x-lt-bind`)
 
 The form is flat; the payload the workflow consumes rarely is. A field may declare `x-lt-bind` — the path its value occupies in the resolver payload (dot keys, optional `[n]` indices). The dashboard maps the flat form through the binds on submit, and reverse-maps `envelope.formDefaults` through them to prefill. A field with no bind lands at its own name at the payload root.
@@ -89,7 +108,7 @@ Only the form is versioned on the role — the payload shape is the workflow's o
 
 ## Help Panel (`x-lt-help`)
 
-Schema-level `x-lt-help` carries the form's guidance — checklists, tier tables, callouts, links — as markdown. The dashboard renders it in the side panel beside the form, so the form itself stays a clean title-and-fields surface while the SOP sits one glance to the right. The help text versions with the form: it lives in the same `form_schema` snapshot in `lt_role_schemas`.
+Schema-level `x-lt-help` carries the form's guidance — checklists, tier tables, callouts, links — as markdown. The dashboard renders it in the side panel beside the form, so the form itself stays a clean title-and-fields surface while the SOP sits one glance to the right. When a schema carries `x-lt-help` (or `x-lt-context`), a help icon renders beside the form title; it opens the Instructions view of the side panel. The help text versions with the form: it lives in the same `form_schema` snapshot in `lt_role_schemas`.
 
 ```json
 {

package/docs/hitl/x-lt-list-schema.md

@@ -98,6 +98,13 @@ Use when the rows describe **entities** (machines, stations) rather than a queue
 }
 ```
 
-The card's `state` renders as a status chip (a stable hue per token — commonly a subtype or a metadata state facet). The grid wraps to the viewport (wall-screen friendly). Clicking a card opens the entity's history: the table view filtered to that facet value (`x-lt-group-by` should therefore be a `metadata.*` path). `x-lt-help` renders above the board as in `facet-table`. In the digital-twin pattern — each machine advertising one live pending row — the board is exact by construction; for wider scopes it groups the fetched page, with standard pagination beyond it.
+The card's `state` renders as a status chip (a stable hue per token — commonly a subtype or a metadata state facet). The grid wraps to the viewport (wall-screen friendly). `x-lt-help` renders above the board as in `facet-table`. In the digital-twin pattern — each machine advertising one live pending row — the board is exact by construction; for wider scopes it groups the fetched page, with standard pagination beyond it.
+
+Cards are fully interactive (`x-lt-group-by` should be a `metadata.*` path so the facet affordances apply):
+
+- **Click** opens the group's latest row in the detail view.
+- **⇧ click** adds the entity's facet to the live filter set — additive, so shift-clicking narrows the board in place and the facet chips row shows each condition with its own remove.
+- **Hovering the card footer** reveals the entity's history as the filtered **table** or **timeline** view (the same view modes the queue offers everywhere else).
+- **Fields bound to a pure `{{metadata.KEY}}` token** carry the same hover pair the table's metadata cells offer: **filter** (narrows within the current role; ⇧ click adds to the current filters) and **search** (the facet across all roles).
 
 The reference: `examples/seed-fleet-sim.ts` — one advert per machine, a `format: "age"` "Since" field, and role default pins (see [pinned-views.md](pinned-views.md)).

package/docs/hitl/x-lt-widget.md

@@ -144,6 +144,29 @@ The field type must be `"object"`. The submitted value is `Record<string, boolea
 - `"envelope"` — for item definitions that are render data only (no query cost). The workflow puts them in `conditionLT`'s `envelope` parameter.
 - `"metadata"` — only when items need to be GIN-indexed and searchable as facets. Adds index cost.
 
+### Geometry (`x-lt-variant`)
+
+Item length and selection mode decide the checklist's shape:
+
+| Variant | Shape | The shape for |
+|---------|-------|---------------|
+| `"rows"` | One item per line | Rituals — sentence-length confirmations, read top-down and ticked deliberately |
+| `"chips"` | A wrapping cloud of selectable pills | Tags — short pick-any items (reject reasons, categories); selection shows in solid accent |
+
+Set `"x-lt-variant"` explicitly, or let the renderer decide: `x-lt-require-all` always renders rows; otherwise chips when every label is 28 characters or fewer. The submitted value is identical in both shapes.
+
+```json
+{
+  "rejectReasons": {
+    "type": "object",
+    "description": "Check every reason that applies",
+    "x-lt-widget": "checklist",
+    "x-lt-source": "envelope.reject_reason_items",
+    "x-lt-variant": "chips"
+  }
+}
+```
+
 A checklist enforces one of three completion levels:
 
 | Level | Declaration | Blocks submission until |