@hotmeshio/long-tail 0.19.1 → 0.21.0

package/docs/dashboard.md

@@ -139,7 +139,7 @@ Every invokable workflow is presented as a tool. The list of tools takes the lef
 - **Heading and description** — the icon and title, with the identifier, tier, and queue as metadata, then the config's one-line description. Keep reference material in `x-lt-help`; it appears in the side panel on demand.
 - **Identity summary** — who will execute: the current user, the workflow's configured `execute_as` bot ("configured default"), or, for admins and superadmins, an override chosen from the bot picker ("admin override").
 - **Certification checkbox** — for a certified workflow, stamps `metadata.certified` on this one run.
-- **The form** — a workflow that declares `inputSchema` renders the x-lt-* form: sections, two columns, conditional fields and instruction blocks, and a side panel with **Instructions** (the interpolated `x-lt-help`) and **Issues** (violations, click to focus). Every other workflow renders the envelope template form from `envelopeSchema`, with its Form and JSON views. See [Invoke forms](hitl/invoke-form.md).
+- **The form** — a workflow that declares `inputSchema` renders the x-lt-* form: sections, two columns, conditional fields and instruction blocks, selects with inline or lookup-backed labeled options, Yes/No decisions over booleans, multi-select lists, validated JSON maps, and a side panel with **Instructions** (the interpolated `x-lt-help`) and **Issues** (violations, click to focus). The `fleetTools` example exercises every shape. Every other workflow renders the envelope template form from `envelopeSchema`, with its Form and JSON views. See [Invoke forms](hitl/invoke-form.md).
 - **Submit** — posts `{ data, metadata }` to the invoke endpoint. The page stays put, reports the started id, and subscribes to that run's `system.workflow.{id}.completed` and `.failed` events, so the outcome and the workflow's returned `data` appear beside Submit without leaving the page. One click disarms the button until the person chooses **Submit again**. While live events are off, a warning beside the button offers a reconnect, since the result could not arrive otherwise. Builders also get a **View workflow** link to its execution. A `422` from the input schema gate lands in the Issues view.
 
 Below 1280px the list folds into a select and the form takes the full width.
@@ -166,7 +166,7 @@ The MCP Tool Designer page lists previous tool design sessions and provides entr
 
 **Composer mode** — manual tool design for building tools from scratch using the visual DAG editor.
 
-Steps unlock sequentially in each wizard. Compiled tools appear in **Graph Workflows** and **Graph Executions**. See the [Compilation Pipeline](compilation.md) guide for details.
+Steps unlock sequentially in each wizard. Compiled tools appear in **Graph Workflows** and **Graph Executions**. See the [Compilation Pipeline](https://github.com/hotmeshio/long-tail/blob/main/docs/donotpublish/compilation.md) guide for details.
 
 ### MCP Server Tools
 
@@ -278,7 +278,9 @@ Accessible at `/admin/roles/:role`. One page per role — a quiet header carryin
 
 **Pins** — two live-save groups. **Link Variables** leads: the facet names members bind per device (`properties.link_variables` — name, optional label, optional default). A pin below may reference a variable as a facet value, `facets={"facility":"{lt:facility}"}`; each member device opens it scoped to its own binding (set from the user menu → Link variables), falling back to the declared default or, unbound, applying no filter. A caption under each templated pin previews the binding on the viewing device (`facility = 'soleful'` / `facility = <empty>`). **Default Pins** follows — the pinned-view seeds this role hands its members (`default_pins`): label, dashboard-relative URL, optional badge. Members see them in their Pinned nav section from first login (marked role-provided) and may promote, hide, or reorder them via preferences; promoting a templated pin copies the template, so it keeps following the device's bindings. See [Faceted Routing — Link variables](faceted-routing.md#link-variables).
 
-**API:** `PATCH /api/roles/:role` updates identity, Pace Board dials, placement, schemas, and pins.
+**Portal** — the role's named portals, each its pinned views laid out as one page. The editor mirrors the page: sheets, title bands, cell panels, dashed slots for adding. Name a portal and start it from a pin; then rows of cells, each cell a pin picked from the role's default pins or the admin's own pins, or typed as a label and URL, with editable panel titles (`portals`, up to 12 portals of 4 rows by 6). Edits join the page draft and **Save** writes them. A sketch shows each shape; **Open** opens `/portal/<role>/<key>`. See [Portal](hitl/portal.md).
+
+**API:** `PATCH /api/roles/:role` updates identity, Pace Board dials, placement, schemas, pins, and the portal.
 
 ### Escalation Schema
 
@@ -377,7 +379,7 @@ Accessible at `/escalations/available`. The central queue for escalation activit
 - **Columns:** a **Summary** cell (status dot + description or type), **Assignee** (claimant, or `—`), **Role** pill, **Priority**, and **Created**. The status dot distinguishes pending, claimed, resolved, cancelled, and expired; notification escalations show a bell.
 - **Faceted query** — beyond the filter bar, the queue takes a structured metadata query, all URL-backed so a query copy-pastes: `?facets={"orderId":"..."}` (equality, AND-ed), `?block=` (exclude), `?range=` (numeric bounds), `?exists=` (key present), `?roles=` (union of role queues), and `?orderBy=` (JSON sort). `?jeopardy=1` narrows to rows past the role's age threshold. List rows omit the envelope by default; `?include=envelope` pulls the full envelope and payload columns for rich views.
 - **Metadata value affordances** — each metadata key/value row carries a three-icon triad on hover: **filter** (scope the current role's queue to `key = value`), **search** (the same facet match across all roles), and **history** (open the entity's cross-queue interval timeline in the right panel — every role this value moved through, with durations and gaps). Filter-present, search-present, history-past. History renders for string values, since the timeline's GIN containment match serves JSON-string facets.
-- **View modes** (`?view=`) — `table` (the columns above), `timeline` (100 rows per page of cross-queue movement), and `rich`. When a role owns a [list schema](#escalations-list-schema), the list defaults to the role-authored `rich` view (the live item as a card, plus a load-on-demand history) with a **Table view** toggle back.
+- **View modes** (`?view=`) — `table` (the columns above), `timeline` (100 rows per page of cross-queue movement), and `rich`. A `?layout=` hint shapes the table: `compact` stays a tight table however narrow, holding non-identity columns until the container clears the split width; `cards` folds into console cards on purpose; absent, the table folds on its own below the card threshold (the same hint a portal pin carries, see [Portal](hitl/portal.md)). When a role owns a [list schema](#escalations-list-schema), the list defaults to the role-authored `rich` view (the live item as a card, plus a load-on-demand history) with a **Table view** toggle back.
 - **Claim** — the claim action locks an item to your user for a claim window (default 30 min). Only members of the role see its pending items; a member scoped `read_self` lands directly on their own assigned item rather than browsing the queue. Re-claiming your own expired item extends it rather than failing.
 - **Bulk actions (admin)** — row checkboxes surface a selection bar: **Claim**, **Assign**, **Unassign**, **Escalate** (move to another role), and **Cancel**. Assign opens a modal for the target user and claim duration; rows under a live claim are skipped unless the modal's takeover checkbox (shown when the selection includes live claims) reassigns them — admin/superadmin only. Unassign returns claimed rows to the pool. Each response reports how many rows were skipped and why. Scoped to a single role, the Cancel verb and its confirmation speak the role form's `x-lt-labels.cancel` vocabulary (`false` hides it). Assign also accepts a faceted query instead of an id list, so "claim everything matching this facet" is one call.
 
@@ -387,6 +389,10 @@ Accessible at `/escalations/available`. The central queue for escalation activit
 
 Accessible at `/escalations/queue`. The personal inbox — the items currently assigned to you across your roles. It carries the same title-as-role-selector, the same rich/table views, and the same metadata affordances as All Escalations, minus the bulk selection bar (every row is already yours). A **Claim expiry** column counts down each item's remaining window. The shell also auto-navigates here on hand-off: when a workflow assigns a follow-on escalation to you (`assigned_to = you`), the dashboard opens that item's detail directly.
 
+### Portal
+
+Accessible at `/portal/<role>/<key>` to any signed-in user, from the **Portals** section of the user menu, and from the rows that lead the role's group in the nav. Each of the role's `portals` renders as a grid: one row per declared row, each dividing its width among its cells, every cell a bounded panel of a pinned list view drawn with the same rich, table, and timeline components as All Escalations; the left nav steps aside on portal pages as it does in kiosk mode. Panels show the pin label, the live count, a view toggle and sort direction for the visit, a refresh, and a link to the full view; rows open the item detail. A kiosk role lands on its first portal as home. See [Portal](hitl/portal.md).
+
 ### Escalation Detail & Resolve Form
 
 Accessible at `/escalations/detail/:id`. Where a person completes the work the workflow is waiting on. The main column is the resolve form; a switchable side panel carries context.
@@ -399,7 +405,7 @@ Accessible at `/escalations/detail/:id`. Where a person completes the work the w
 - **Submit guard** — `x-lt-submit-guard` gates a parent on a child query (e.g. "every item in this batch must resolve first"): the dashboard disables Submit with a live count while rows remain, and the server re-checks the guard atomically inside the resolving `UPDATE` so no race slips through. `autoResolveWhenEmpty` submits the parent the moment the query empties.
 - **Transition hand-off** — `x-lt-transition` replaces the return-to-previous-page jump with a short wait screen: the workflow assigns a follow-on escalation back to the submitter, the screen detects it and navigates onward (or falls back to `x-lt-transition-done` after a bounded wait). This is the submit → side-effect → next-step chain (submit, a label prints, the harvest task opens).
 - **Batch resolution** — a `conditional({ batch })` escalation accumulates N items on one row; `POST /api/escalations/:id/resolve-batch-item` submits each (claim-agnostic by default, `assertClaim` to require your own live claim), and the last item wakes the workflow with the full collection.
-- **Side panel** — switchable views selected by the icon strip: **Help** (the form's `x-lt-help` markdown, `{{domain.path}}`-interpolated against the live record — escalation, metadata, envelope, payload, resolver, and `lookup.*` — or a state-aware hint like "Claim this escalation to enable the form"), **Details** (status, role, priority, claim provenance, timestamps, and for builders the identifier links), **AI Analysis** (what triage diagnosed and corrected, when AI is on), **Metadata** (the row's facets, with the same triad), **Context** (input envelope, escalation context, resolver payload), **Record** (the raw JSON, builders only), and **Errors** (the last submit's validation failures). The panel and form share the width as a flex set; it opens expanded on Help when the form carries `x-lt-help`.
+- **Side panel** — switchable views selected by the icon strip: **Help** (the form's `x-lt-help` markdown, `{{domain.path}}`-interpolated against the live record — escalation, metadata, envelope, payload, resolver, and `lookup.*` — or a state-aware hint like "Claim this escalation to enable the form"), **Details** (status, role, priority, claim provenance, timestamps, and for builders the identifier links), **AI Analysis** (what triage diagnosed and corrected, when AI is on), **Metadata** (the row's facets, with the same triad), **Items** (on an accumulator or batch row: the held items in arrival order with the count against max, each with its payload summary, arrival time, actor, and a link to its reciprocal row; on a pending accumulator the actor adds an item by key with an optional JSON payload or removes one, each through the same guarded statement the API runs), **Context** (input envelope, escalation context, resolver payload), **Record** (the raw JSON, builders only), and **Errors** (the last submit's validation failures). The panel and form share the width as a flex set; it opens expanded on Help when the form carries `x-lt-help`.
 - **Admin claim override** — when an item is held by someone else, admins and superadmins see **Reassign…** (hand the claim to another user, takeover implied) and **Return to queue** (unassign) in the action bar.
 
 **API:** `POST /api/escalations/:id/claim` claims, `/release` releases, `/resolve` resolves; `/resolve-batch-item` submits one batch item; `/escalate` moves; `/cancel` cancels. The role's form and its versions come from `GET /api/roles/:role/schema`.

package/docs/hitl/design.md

@@ -8,7 +8,7 @@ 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
+[`docs/donotpublish/design-principles.md`](https://github.com/hotmeshio/long-tail/blob/main/docs/donotpublish/design-principles.md); the reference form
 implementation is `examples/workflows/acme-stations`.
 
 ---

package/docs/hitl/escalation.md

@@ -103,7 +103,43 @@ The declaration folds into the row at creation, inside the same Leg1 commit:
 
 Items are submitted via `POST /api/escalations/:id/resolve-batch-item`, `POST /api/escalations/resolve-batch-item-by-signal-key` (the deterministic home signal id — no UUID lookup, no facet duplication), or `POST /api/escalations/resolve-batch-item-by-metadata` (see [Resolution — Batch items](resolution.md)). Each item validates against the same versioned role form a single-item resolver gets, `schemaVersion` pins included. Each fill is one guarded statement: the payload lands only while its key is still pending (duplicates return `duplicate-item` untouched), and the LAST fill resolves the row, stores the assembled collection as `resolver_payload`, and wakes this wait — atomically. The completing submission's `$resolution` rides the delivered collection.
 
-`timeout` and cancellation keep their standard semantics (`false` / `null`); a plain resolve on a batch row remains an admin override that resolves the whole row with the payload given.
+`timeout` and cancellation keep their standard semantics (`false` / `null`); a plain resolve on a batch row remains an admin override that resolves the whole row with the payload given. Add `partialOnTimeout: true` (hotmesh 0.29.0+) and the timer instead resumes the wait with the items filled so far plus `$trigger: 'timeout'`, the same value the expired row stores as `resolver_payload`.
+
+### Open accumulation — items arrive over time
+
+Declare `accumulate` and the escalation becomes an open container: items join it one at a time through `accumulateItem` while the row stays pending, and the wait resumes with the ordered collection when the container is full, when its window closes, or when someone resolves it by hand. A timeout is a delivery, never a failure, so the wait has no `false` branch; `conditionalAccumulator` types that contract.
+
+```typescript
+import { conditionalAccumulator } from '@hotmeshio/long-tail';
+
+const bin = await conditionalAccumulator<BagV1, { shippedBy?: string }>(signalId, {
+  role: 'bin',
+  description: 'Scan each bag into the bin',
+  metadata: { binKey },
+  accumulate: { max: 12 },   // count trigger; omit for an unbounded window
+  timeout: '4h',             // the window
+});
+if (bin === null) { /* cancelled */ }
+bin.$trigger;      // 'count' | 'timeout' | 'resolve'
+bin.$accumulated;  // [{ itemKey, payload?, at, actor?, reciprocalId? }, ...] in arrival order
+bin.shippedBy;     // present only when $trigger is 'resolve' (the resolver's payload merges in)
+```
+
+`accumulate` takes three dials. `max` is the count trigger; absent, only the timer or a manual resolve ends the wait. `resolveAtMax: false` makes `max` a cap: the last slot answers `accepted`, further adds answer `full`, and the wait still ends by timer or resolve. `unique: false` lets a repeated item key replace its entry in place; the default answers `duplicate-item` and leaves the row untouched.
+
+The declaration folds into the row at creation, inside the same Leg1 commit:
+
+- `metadata.accumulate_count` — items held right now, recomputed in every add and remove
+- `metadata.accumulate_max` — the count trigger, or `null` when unbounded
+- `metadata.accumulate_keys` — the held item keys (`@>`-queryable: `{"accumulate_keys":["ORD-9"]}` finds the container holding that order)
+- `envelope.accumulate_items` — `Record<itemKey, { payload?, at, actor?, reciprocalId? }>`, with `at` stamped by the database clock in the add statement
+- `envelope.accumulate_config` — the folded `{ unique, resolveAtMax }`
+
+Items are added via `POST /api/escalations/:id/accumulate`, `POST /api/escalations/accumulate-by-signal-key`, or `POST /api/escalations/accumulate-by-metadata`, removed via the matching `remove-item` forms, and read in arrival order via `GET /api/escalations/:id/items` (see [Resolution — Accumulator items](resolution.md#accumulator-items)). Each add is one guarded statement: the entry lands only while the row is pending and the key is not already held, the facets recompute, and the add that reaches `max` resolves the row, stores `{ $accumulated, $trigger: 'count' }` as `resolver_payload`, and wakes this wait, atomically. When the timer fires first the expiry statement stores and delivers `{ $accumulated, $trigger: 'timeout' }` and the row is `expired`; a manual `resolve` stores and delivers the collection merged with the resolver's payload under `$trigger: 'resolve'`. Cancellation still yields `null` with the held items preserved on the row.
+
+A **reciprocal** add writes two accumulator rows in that same statement, both or neither: the container gains the item, and a second row (the item's own escalation, declared `accumulate: { max: 1 }`) gains the container's id as its item key. Each entry carries the other row's id as `reciprocalId`, so "which bin holds this bag" reads from the bag's row and "which bags are in this bin" from the bin's, both as row truth. A blocked reciprocal (already resolved, full, already holding this container) answers `reciprocal-*` and the container is untouched. The `rollupBin` and `rollupMember` examples show both sides.
+
+`accumulate` and `batch` are mutually exclusive on one wait. The full contract, guarantees, and what is deferred are collected in [Open accumulator](../accumulator.md).
 
 ### Row completeness guarantee
 

package/docs/hitl/form.md

@@ -26,16 +26,21 @@ Declare `title` on every field whose key isn't already a readable label — it i
 
 ## Field Types
 
-| JSON Type | Renders As |
+The control follows the field's declared `type` and its tokens; the stored value only fills it. A field with no value yet renders the empty state of its control: a number is an empty input, a boolean is an unchecked box, a select opens on **Choose…**, a multi-select has nothing picked, a JSON editor is empty. Every property starts at its `default`, or `{}` for an object, or empty text.
+
+| Declared type | Renders As |
 |-----------|-----------|
 | `boolean` | Checkbox toggle |
-| `number` | Number input |
-| `string` | Text input (default) |
-| `string` + `enum` | Dropdown select |
-| `string`/`number` + `x-lt-options` | Dropdown select — options resolved from the escalation context (see [x-lt-validation.md](x-lt-validation.md#dynamic-select-options-x-lt-options)) |
+| `boolean` + `enum` / `x-lt-options` | Select emitting `true` or `false` (a Yes/No decision) |
+| `number` / `integer` | Number input |
+| `string` | Text input; `format: "textarea"` for multi-line |
+| `string`/`number` + `enum` | Select |
+| any scalar + `x-lt-options` | Select with labeled options: inline, from the context, or from a lookup (see [x-lt-validation.md](x-lt-validation.md#select-options-x-lt-options)) |
+| `array` + `x-lt-options` | Multi-select chips emitting the picked values in list order |
+| `array` / `object` + `x-lt-widget: "json"` | Validated JSON editor (see [x-lt-widget.md](x-lt-widget.md#json)) |
+| `array` without options | Tag display (read-only) |
+| `object` | Nested fields from `properties`, or a widget (see [x-lt-widget.md](x-lt-widget.md)) |
 | `null` | Read-only "null" display |
-| `array` | Tag display (read-only) |
-| `object` | Nested section with recursive fields, or a widget (see [x-lt-widget.md](x-lt-widget.md)) |
 
 ---
 

package/docs/hitl/invoke-form.md

@@ -22,7 +22,8 @@ Workflow names read as titles on the page: `fleetTools` shows as **Fleet Tools**
 | Field | Role in the invoke |
 |---|---|
 | `inputSchema` | The form. JSON Schema `properties` plus x-lt-* tokens. Rendered by the Invoke Tool page; enforced by the invoke API. |
-| `envelopeSchema.metadata` | The `metadata` stamped on every run from this form. `envelopeSchema.data` is ignored when `inputSchema` is present. |
+| `envelopeSchema.metadata` | The `metadata` the Invoke Tool page stamps on every run from this form. `envelopeSchema.data` is ignored when `inputSchema` is present. |
+| `inputLookups` | Versioned knowledge refs (`{ domain, key, version, as? }`) the form reads as `lookup.<as ?? key>`. See [Lookups](lookups.md#pinning-on-a-workflow-config). |
 | `invocationRoles` | Who sees the workflow on the Invoke Tool page and who may start it. Empty means every authenticated user. |
 | `description` | One line at the top of the form column, markdown allowed. Keep the reference material in `x-lt-help`, which appears in the side panel on demand. |
 | `icon` | A curated icon from `WORKFLOW_ICONS` (`icon: WORKFLOW_ICONS.WRENCH`). Leads the workflow's row and heading in place of the tier glyph so operators tell tools apart at a glance. The registry offers the same set as a picker. |
@@ -44,7 +45,9 @@ The form edits flat values keyed by property name. On submit, `x-lt-bind` maps t
   "metadata": { "source": "dashboard" } }
 ```
 
-Conditions and help tokens read the live form under the `input` domain: `x-lt-showIf: "input.action=retire"`, `{{input.serialNumber}}`. `resolver` names the same values, so a schema written for an escalation form works unchanged. The only other domain an invoke form can read is `metadata`, the envelope metadata declared above.
+Conditions and help tokens read the live form under the `input` domain: `x-lt-showIf: "input.action=retire"`, `{{input.serialNumber}}`. `resolver` names the same values, so a schema written for an escalation form works unchanged. An invoke form reads four domains: `input`, `resolver`, `metadata` (the run's metadata), and `lookup` (the editions pinned by `inputLookups`, keyed `<as ?? key>`).
+
+The gate validates against the `metadata` the caller sends. The Invoke Tool page sends the declared `envelopeSchema.metadata` plus the per-run `certified` flag; an API or MCP caller that wants a condition such as `x-lt-showIf: "metadata.mode=strict"` to hold sends that metadata itself.
 
 Hidden conditional fields still submit their defaults, as on every x-lt-* form. Treat empty as absent in the workflow.
 
@@ -67,6 +70,10 @@ An array of conditions requires every one, so the prompt belongs to its tool and
 
 `x-lt-help` on the schema root is the longer reference for the side panel: markdown, tables, and `{{input.*}}` tokens that re-interpolate as the operator types.
 
+## From an escalation form
+
+A role's `form_schema` can offer the same invoke from inside the work item: an `x-lt-invoke` field names the workflow and maps the escalation's values into its payload, then either posts directly or opens this form in a dialog with those values in place. Visibility follows the same per-caller list, the payload meets the same gate, and the run reports over the same events. See [x-lt-invoke.md](x-lt-invoke.md).
+
 ## The Invoke Tool page
 
 The page is open to anyone the server lists an invokable workflow for. Builders reach **Invoke Tool** under Orchestrate; every other persona gets a **Tools** section in the nav that appears only when there is something to invoke. Each invokable workflow is a tool; the list sits on the left, grouped by task queue, with the first workflow preselected; the form takes the rest of the row. Below 1280px the list folds into a select and the form takes the full width.
@@ -93,6 +100,6 @@ Once a run starts, the page subscribes to `system.workflow.{workflowId}.complete
 }
 ```
 
-The MCP tools `invoke_workflow` and `invoke_workflow_read_safe` run the same gate and return the body as an error result. The gate reads bound paths from the nested `data`, skips fields a `x-lt-showIf` hides, and applies every validation keyword the form applies.
+The MCP tools `invoke_workflow` and `invoke_workflow_read_safe` run the same gate and return the body as an error result; `get_workflow_config` returns the `input_schema`, the declared metadata, and the resolved lookup data a caller needs to compose a valid payload. The gate reads bound paths from the nested `data`, skips fields a `x-lt-showIf` hides, resolves `x-lt-options` over pinned lookups, and applies every validation keyword the form applies.
 
 `GET /api/workflows/invocable` returns the caller's invokable workflows with their tier. The list and the gate share one predicate, so the page never offers a workflow the API would refuse.

package/docs/hitl/lookups.md

@@ -37,6 +37,27 @@ const decision = await conditional<CascadeResolverV1>(signalId, {
 
 The refs fold into `envelope.lookups` as a pure transform — a pinned wait costs exactly what an unpinned one does. A malformed ref (missing field, non-integer version) throws before the row is written; over the HTTP create surface the same validation answers with a 400.
 
+## Pinning on a Workflow Config
+
+An invoke form pins editions the same way. Declare `inputLookups` beside `inputSchema` on the worker config and the form reads them under `lookup.<as ?? key>`:
+
+```typescript
+const fleetToolsConfig: LTWorkerConfig = {
+  invocable: true,
+  inputSchema: FLEET_TOOLS_INPUT_SCHEMA,
+  inputLookups: [{ domain: 'fleet', key: 'serial-numbers', version: 1, as: 'serials' }],
+};
+```
+
+```jsonc
+// inputSchema.properties
+"serialNumber": { "type": "string", "title": "Serial", "x-lt-options": "lookup.serials.items" }
+```
+
+The Invoke Tool page fetches `GET /api/workflows/:type/input-lookups` once per workflow; the grant is the invoke predicate, so whoever may start the workflow reads exactly the pinned editions. The invoke API resolves the same refs into the gate, so a value outside the edition is refused with the canonical 422. The registry detail page edits the refs under **Lookups** in its Invocation column; the preview renders against the resolved editions.
+
+The refs are checked twice on save. Shape first: a missing `domain` or `key`, a `version` that is not a positive integer, or an empty `as` answers `400` with the field named. Existence second: a ref whose edition does not exist answers `400` naming the editions that do (`Lookup ref fleet/serial-numbers v3 names no edition (editions: v1, v2)`), from `PUT /api/workflows/:type/config` and from the MCP `upsert_workflow_config` tool alike. On the worker boot path a malformed ref fails the boot; a ref whose edition is not yet written logs a warning, since seeds commonly run after registration. At run time the resolver reads each edition once and holds it in memory (editions are immutable), a missing edition answers `missing: true` for that ref without failing the batch, the Invoke Tool page shows which pinned editions are unavailable, and the fields that read them follow the `x-lt-options` rules: a plain path falls back to the typed input, an interpolated path stays a disabled select and fails closed.
+
 ## Versioning
 
 Every knowledge entry carries a `current_version`, and every write that changes its data mints an immutable snapshot automatically — no publish step:

package/docs/hitl/pinned-views.md

@@ -40,6 +40,10 @@ A role may declare `default_pins: [{ label, url, badge? }]` (edited on Role Deta
 
 Membership *is* the persona's bookmark set — no per-user setup. Duplicate labels across a user's roles collapse to the first role's pin.
 
+## Portal
+
+A role can lay its pins out as pages: `portals` is a list of named matrices, each an array of rows of pins, rendered at `/portal/<role>/<key>` as a grid of live list panels. Members choose one from the global menu, each also leads the role's group in the nav, and a kiosk role lands on its first portal as home. See [portal.md](portal.md).
+
 ## Reference Example
 
 The `fleet-servicer` seed (`examples/seed-fleet-sim.ts`) ships a facet-board list schema, jeopardy dials, and three default pins — the board, a badged "Needs harvesting" facet query, and a badged jeopardy view — so the whole persona story is exercisable from the dashboard. The seeded `reviewer` user is a member.

package/docs/hitl/portal.md

@@ -0,0 +1,97 @@
+# Portals: a role's pinned views as pages
+
+A role can declare **portals**: named matrices of pinned views, each rendered as a single page of live list panels at `/portal/<role>/<key>`. A matrix is an array of rows, each row an array of cells, each cell a pin. One row with one cell fills the page with that view. Two rows, the first holding one cell and the second three, give a full-width band over three columns. A 2x2 splits one queue by region, each cell the same role scoped to a different facet. Cells carry nothing but the pin, so everything a pin already says composes for free: the view (`view=rich`, `table`, `timeline`), facet scopes, jeopardy, link variables, and the live count.
+
+A role carries several portals because screens serve different purposes. One shows urgent items by facility on the floor, four facilities in a 2x2. Another is the day's focus for the team, one panel per person, each named for them and scoped to their facets, so everyone sees their own list under their own name. Members choose a portal from the global menu, where the kiosk queue picker already lives, and each portal also appears as a row under the role's group in the left nav. A kiosk role lands on its first portal as home.
+
+---
+
+## Declaring portals
+
+`portals` on the role: a list of `{ key, label, rows }`. `key` is a short url-safe slug, unique within the role, and the portal's address segment. `label` is the name shown in the menu and the nav. `rows` is the matrix: up to 4 rows of up to 6 cells, every row holding at least one cell, every cell `{ label, url, badge? }` with a dashboard-relative `url`, the `default_pins` shape.
+
+```typescript
+roles: [
+  {
+    role: 'printer-fleet',
+    portals: [
+      {
+        key: 'floor',
+        label: 'Floor screen',
+        rows: [
+          [{ label: 'Fleet board', url: '/escalations/available?role=printer-fleet&view=rich' }],
+          [
+            { label: 'North', url: '/escalations/available?role=printer-fleet&facets=%7B%22facility%22%3A%22north%22%7D&view=table', badge: true },
+            { label: 'South', url: '/escalations/available?role=printer-fleet&facets=%7B%22facility%22%3A%22south%22%7D&view=table', badge: true },
+            { label: 'Harvest queue', url: '/escalations/available?role=printer-harvest&view=table', badge: true },
+          ],
+        ],
+      },
+      {
+        key: 'focus',
+        label: 'Focus of the day',
+        rows: [[
+          { label: 'Jim', url: '/escalations/available?role=printer-fleet&facets=%7B%22owner%22%3A%22jim%22%7D' },
+          { label: 'Sally', url: '/escalations/available?role=printer-fleet&facets=%7B%22owner%22%3A%22sally%22%7D' },
+          { label: 'Anu', url: '/escalations/available?role=printer-fleet&facets=%7B%22owner%22%3A%22anu%22%7D' },
+        ]],
+      },
+    ],
+  },
+],
+```
+
+### Counts above the panels
+
+A portal may lead with **counts**: `counts` is a list of `{ label, url, blurb? }` (up to 8). Each becomes a tile above the panels showing the live total of its list URL, the same number a pin badge carries, under the label and over the blurb, and the tile opens the list. A queue's counts read at a glance before its lists do:
+
+```typescript
+{
+  key: 'review-desk',
+  label: 'Review desk',
+  counts: [
+    { label: 'Waiting', url: '/escalations/available?role=reviewer', blurb: 'Unclaimed items in the queue' },
+    { label: 'In progress', url: '/escalations/available?role=reviewer&status=claimed', blurb: 'Claimed and being worked' },
+    { label: 'Resolved', url: '/escalations/available?role=reviewer&status=resolved', blurb: 'Closed out by a reviewer' },
+    { label: 'Expired', url: '/escalations/available?role=reviewer&status=expired', blurb: 'Timed out before anyone acted' },
+    { label: 'Cancelled', url: '/escalations/available?role=reviewer&status=cancelled', blurb: 'Withdrawn by the workflow' },
+  ],
+  rows: [[
+    { label: 'Waiting', url: '/escalations/available?role=reviewer&view=table&layout=compact', badge: true },
+    { label: 'In progress', url: '/escalations/available?role=reviewer&status=claimed&view=table&layout=compact', badge: true },
+  ]],
+}
+```
+
+The `reviewer` role in the examples' start config (`index.ts`) declares exactly this portal, in code, with `reset: true` so it applies on every boot.
+
+The same field rides `PATCH /api/roles/:role` and the `update_role` MCP tool. `null` clears every portal. Under code-owned configuration the declaration is compared in order and applied on every boot, so reordering portals or rows is a change.
+
+## Composing them in the dashboard
+
+Role Detail carries a **Portal** section listing the role's portals. The editor draws what it produces: each portal a bounded sheet with a title band, each cell its own small panel, and dashed placeholders wherever a view can be added. Edits build the page's draft; **Save** writes them with the rest of the role, one `PATCH` into the role's `portals` column:
+
+- **New portal**: type a name, then **Start it with a view** over the role's default pins and the admin's own pins. The first pick creates the portal; its key derives from the name. **Label and URL** adds a view that is not yet pinned.
+- Each portal shows a sketch of its shape, its editable name, its key, **Open**, and a remove control. Each row lists its cells with an editable panel title (name a cell for the person or place it serves), the view its URL asks for (`rich`, `table`, `timeline`, or `default` when the role's list schema decides), the URL, and the device binding of any link variable it references.
+- Each row ends with **Add a view to this row** (up to six); below the matrix, **Start a new row with a view** (up to four rows). Removing the last cell of a row removes the row; removing the last cell of a portal removes the portal.
+- A **counts** strip leads each portal's body: **Add a count** picks a pin whose total becomes a tile; each tile's title and blurb edit in place.
+
+## The page
+
+A portal page fills the content area with one grid row per declared row, each dividing its width evenly among its cells. Each panel is a bounded sheet with a tinted title band and its own scroll, drawn with the same components as the escalations list: the rich view when the role owns a non-table list schema and the pin does not ask for another, the table when it asks for one or the schema is plain, the timeline when asked. Count tiles, when declared, sit in one row above the panels: label, large number, blurb, each a link to its list. The band of every panel shows the pin's label, the live total, a view toggle (table or rich, when the role offers both), the sort direction, a refresh, and a link to the full view. The toggle and sort hold for the visit; the pin stays as authored. Rows open the item detail page, which returns to the portal. Up to 25 rows render per panel, then a quiet "N more in the full view" link. A narrow window stacks the cells in declaration order.
+
+**Fitting a screen.** A panel on a wall screen is read, not scrolled, so a pin can ask the table to spend its width tightly: `?view=table&layout=compact` keeps the table a table however narrow the panel, tightens every cell, and holds the non-identity columns (assignee, role, priority) back until the panel is wide enough, so a narrow cell reads as a tight list of item and age and twenty rows fit where the folded layout showed four. `layout=cards` asks for the folded console-card layout on purpose. Without `layout`, the table folds on its own below the card threshold. The hint rides the URL like `view`, so it works on the full list page too, and it is the seam for a compact timeline later: a series of tight offset lines that fit the whole story in the panel.
+
+A portal page shows without the left nav, as kiosk does: it is a screen read from across a room, and the panels are the page. The header stays, so the user menu still switches portals. Any signed-in user may open a portal. Panels read through the same role-scoped endpoints as the list page, so RBAC is unchanged: each viewer sees exactly what their read scope returns, and a queue outside it renders empty. Link variables resolve per device at render time, exactly as pins in the nav do. One event subscription per queue named by the cells keeps every panel current, on the LIST refresh tier.
+
+## Choosing a portal
+
+The global menu (the user menu in the header) lists **Portals**: every portal of the roles the viewer belongs to, grouped by role when more than one role declares any; global viewers see every role's. A device dedicated to a portal, a screen on the floor, opens the menu once and lands there, the same gesture as choosing a kiosk queue. The left nav repeats each portal as a row leading the role's pinned group.
+
+## Kiosk
+
+Kiosk home is the role's first portal when it declares any, and the role's escalation list otherwise. The station queue picker follows the same rule. `/portal` is on the kiosk allow-list beside the list, detail, and scan screens. See [Kiosk mode](../scan-codes.md#kiosk-mode--the-locked-station-viewport).
+
+## Reference example
+
+The `printer-fleet` seed (`examples/seed-fleet-sim.ts`) declares two portals: **Floor screen**, the fleet board over the two facility tables and the harvest queue, and **By model**, one panel per printer model. Open Admin → Roles → printer-fleet → Portal to see them composed, and the user menu's Portals section to open either.

package/docs/hitl/resolution.md

@@ -109,6 +109,47 @@ Each item validates against the same versioned role form a single-item resolve u
 
 Item keys are non-empty strings up to 128 characters; prefer URL-friendly names (`u1-L`). Payload keys inside each item are caller-owned — the platform reserves no names inside `batch_items` values. Every fill stamps `envelope.batch_filled_at[itemKey]` with the database clock in the same statement, so the row carries the collection timeline as row truth. After an SLA expiry (`conditional` returns `false`) the terminal row retains the partial `batch_items` and their timestamps — read them back with `GET /api/escalations/:id` or `getEscalationBySignalKey` from an activity.
 
+### Accumulator items
+
+An accumulator escalation (a `conditionalAccumulator` wait declared with `accumulate: {...}`, see [Creating Escalations](escalation.md#open-accumulation--items-arrive-over-time)) holds items added over time. Add by id, by signal key, or by metadata facet:
+
+```typescript
+const first = await lt.escalations.accumulate({
+  id: binId,
+  itemKey: orderId,
+  payload: { weight: 2 },                  // optional; validates against the bin role's form
+  reciprocal: { id: bagEscalationId },     // optional; the bag's own row is written in the same statement
+});
+// → { outcome: 'accepted', count: 1, remaining: 11, escalationId,
+//     reciprocal: { outcome: 'completed', count: 1, escalationId, signaled: true } }
+
+const second = await lt.escalations.accumulateBySignalKey({
+  signalKey: homeSignalId,
+  itemKey: 'order-2',
+});
+
+const last = await lt.escalations.accumulateByMetadata({
+  key: 'binKey',
+  value: binKey,
+  itemKey: 'order-12',
+});
+// → { outcome: 'completed', count: 12, remaining: 0, signaled: true, workflowId }
+
+await lt.escalations.removeItem({ id: binId, itemKey: 'order-2' });
+// → { outcome: 'removed', count: 11, escalationId }
+
+const held = await lt.escalations.getItems({ id: binId });
+// → { kind: 'accumulate', count, max, items: [{ itemKey, payload?, at, actor?, reciprocalId? }, ...] }
+```
+
+Interim adds return `accepted` with the count held and the slots remaining (`null` when unbounded) and publish `escalation.updated` carrying `item_key`, `count`, `actor`, and `reciprocal_id`; the add that reaches `max` returns `completed`, the row resolved with `{ $accumulated, $trigger: 'count' }` as `resolver_payload` and the workflow woke with it, in the same statement. A key already held returns 409 (`duplicate-item`, safe under scanner double-reads); a full cap returns 409 (`full`); a row that is not an accumulator returns 400. Removals return the new count, publish `escalation.updated` with `removed: true`, and never wake the waiter.
+
+Adds are claim-agnostic, the same rationale as batch fills: a container collects contributions from many hands. `assertClaim: true` (by-id form) opts into the caller's own live-claim assertion inside the guarded statement. Every add records the actor on the entry and merges `resolved_by` into the row's metadata, so the completing add's stamp is the resolution provenance and `$resolution` rides the completing wake.
+
+A reciprocal names a second row by `id`, `signalKey`, or `key`/`value`; it is RBAC-gated before the statement (404 when the caller cannot see it, 403 when they see it but cannot act on it) and written in the same statement as the container, both or neither. The reciprocal row holds the container's id as its item key; a member declared `accumulate: { max: 1 }` completes and wakes on that add. When the reciprocal blocks the add, the response names why (`reciprocal-full`, `reciprocal-duplicate`, `reciprocal-terminal`, `reciprocal-not-accumulator`) and the container is untouched.
+
+Item keys are non-empty strings up to 128 characters. Reserved accumulate keys (`accumulate_count`, `accumulate_max`, `accumulate_keys`) cannot appear in the `metadata` patch. A plain `resolve` on an accumulator row is the hand-close: the workflow receives the collection merged with the resolver payload under `$trigger: 'resolve'`, and the row stores the same. After the window closes the row is `expired` with the collection stored as `resolver_payload`, exactly what the workflow received.
+
 ### Resolving a set atomically
 
 When one decision settles a set of waits — each with its own payload — use `resolveAllOrNone`:

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

@@ -1,6 +1,6 @@
 # Embed and Navigation Widgets
 
-Three display-only widgets that surface related information inside an escalation's resolver form without leaving the page. All three produce **no resolver payload** — they must never appear in the schema's `required` array and are always declared `readOnly: true`.
+Three display-only widgets that surface related information inside an escalation's resolver form without leaving the page. All three produce **no resolver payload**: their keys are dropped from the submitted payload, they must never appear in the schema's `required` array, and they are always declared `readOnly: true`. The [`invoke`](x-lt-invoke.md) widget, which starts a workflow from the form, follows the same rules.
 
 | Widget | Token | What it shows |
 |--------|-------|---------------|

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

@@ -0,0 +1,95 @@
+# x-lt-invoke — start a workflow from the form
+
+A role's `form_schema` can place a control that starts another workflow: a link, an icon-link, or a button that either fires the workflow at once with a payload mapped from the escalation, or opens the workflow's own invoke form in a dialog, prefilled from the same mapping. The control reuses the Invoke Tool page end to end: the same per-caller list decides who sees it, the same `input_schema` gate validates the payload, the same registered icon leads the label, and the run's outcome arrives over the same live events.
+
+The field is display-only. It carries no answer, is dropped from the resolver payload, and must never appear in `required`.
+
+```jsonc
+"print_pamphlet": {
+  "type": "string",
+  "readOnly": true,
+  "x-lt-widget": "invoke",
+  "x-lt-invoke": {
+    "workflow": "printPamphlet",
+    "data": { "order": { "id": "{{metadata.orderId}}" }, "copies": 1 },
+    "metadata": { "escalationId": "{{escalation.id}}" },
+    "modal": true
+  },
+  "title": "Print pamphlet",
+  "description": "Prints the patient pamphlet for this order",
+  "x-lt-section": "Tools",
+  "x-lt-span": 2,
+  "x-lt-showIf": "metadata.orderId"
+}
+```
+
+## The declaration
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `workflow` | string | The `workflow_type` to start. Required. |
+| `data` | object | The nested `data` the invoke API receives. Leaves interpolate `{{domain.path}}` tokens against the escalation context. Defaults to `{}`. |
+| `metadata` | object | Extra run metadata, merged over the workflow's declared `envelopeSchema.metadata`. Same interpolation. |
+| `modal` | boolean | `true` opens the workflow's invoke form prefilled; `false` (default) posts `data` at once. |
+| `confirm` | string | Direct mode only: a prompt shown before the post. Tokens interpolate. |
+| `variant` | `"link"` \| `"button"` | The control's shape. Defaults to `link`. |
+| `icon` | boolean | Lead the label with the workflow's registered icon, the one the registry picker sets and the Invoke Tool page shows. Defaults to `true`. |
+
+The field's `title` is the label; without one the workflow type reads as a title (`printPamphlet` → **Print Pamphlet**). `description` renders as the helper line beneath it. Every layout token composes: `x-lt-section`, `x-lt-span`, `x-lt-showIf`, `x-lt-order`.
+
+## Mapping values
+
+`data` is written once, in the shape the workflow receives. In direct mode it is posted as resolved. In modal mode the same object prefills the workflow's `input_schema` by inverting each field's `x-lt-bind`, so a field bound to `printer.serialNumber` opens holding `data.printer.serialNumber`. A workflow without an `input_schema` gets its envelope template form with `data` merged over the template.
+
+Interpolation keeps types:
+
+| Leaf | Resolves to |
+|------|-------------|
+| `"{{metadata.copies}}"` | The raw context value: a number stays a number, a boolean a boolean, an array an array |
+| `"ORD-{{metadata.orderId}}"` | A string |
+| A token whose value is missing or null | The key is omitted, so the workflow's own defaults apply |
+| A mixed string with any missing segment | The key is omitted |
+| `1`, `true`, `"plain text"` | Passed through unchanged |
+
+Objects and arrays recurse. The domains are the escalation form's: `escalation`, `metadata`, `envelope`, `payload`, `lookup`, and the live `resolver` values, so a mapping can carry what the operator has typed so far.
+
+## Who sees it
+
+The control renders only for workflows the signed-in user may invoke, read from the same per-caller list that drives the Invoke Tool page and its nav entry. A workflow outside that list leaves no trace in the form. The server runs the same predicate on the post. The control follows the form's claim state: it is live once the operator has claimed the escalation, and it leaves the form once the escalation is resolved, cancelled, or expired.
+
+One request serves every invoke field on the page, and the list is shared with the rest of the dashboard's cache.
+
+## Direct mode
+
+Clicking the control posts `data` with the workflow's declared metadata (plus the field's `metadata` mapping) and the `certified` flag the workflow is registered with. The control gives way to **Working…** while the run is in flight, then reads **Completed** with the returned `data` as an outline beneath, or **Failed** with the reason. The outcome arrives over the same `system.workflow.{id}.completed` and `.failed` events the Invoke Tool page follows. Once the run has settled the control returns beneath the result, ready for another run. A warning offers to reconnect live events when they are off.
+
+When the target declares an `input_schema`, the payload is checked against it before the post with the shared validation pass. Violations, from that check or from a server 422, list beneath the control with an **Open form** action that opens the workflow's form prefilled, so the operator completes what the mapping could not supply. A mapping meant for direct mode should satisfy the schema on its own; declare `confirm` when the action deserves a second look.
+
+## Modal mode
+
+`"modal": true` opens the workflow's invoke form in a dialog headed by its icon and title: the full x-lt-* form when the workflow declares an `input_schema`, with pinned lookups resolved, conditional sections, and the shared validation pass; the envelope template form otherwise. Prefilled values sit in their fields ready to be changed. Issues and the form's `x-lt-help` render inside the dialog.
+
+Submit posts exactly as the Invoke Tool page does, and the dialog becomes a receipt with one action. While the run works it shows the workflow's icon and **Working…** with a Close control; closing leaves the run going. On completion it reads **Completed** with the returned `data` as an outline and a **Done** button. On failure it reads **Failed** with the reason, **Try again** returns to the form holding what was typed, and Close dismisses. The backdrop does not dismiss the dialog; Escape and the close control do. Each opening starts clean.
+
+## Example
+
+The `printer-fleet` role's work form offers the fleet tools for the machine on screen. Its escalations carry `metadata.serialNumber`, the same facet the fleet-tools serial lookup reads, so the dialog opens with the serial already chosen:
+
+```typescript
+fleet_tools: {
+  type: 'string',
+  readOnly: true,
+  'x-lt-widget': 'invoke',
+  'x-lt-invoke': {
+    workflow: 'fleetTools',
+    modal: true,
+    data: { printer: { serialNumber: '{{metadata.serialNumber}}' } },
+  },
+  'x-lt-section': 'Tools',
+  'x-lt-span': 2,
+  title: 'Fleet tools',
+  description: 'Reprint a label, change filament, or report this machine offline',
+}
+```
+
+See [`examples/seed-fleet-sim.ts`](../../examples/seed-fleet-sim.ts) for the role and [invoke-form.md](invoke-form.md) for the `fleetTools` form it opens.

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

@@ -21,7 +21,9 @@ Every string is a markdown/text template run through the same `{{domain.path}}`
 | `x-lt-card` | schema | `facet-board`: the per-entity card — `{ title, state?, fields?: [{ label, value, format? }] }` |
 | `x-lt-row-action` | schema | The per-row action button: `{ action?, label?, durationMinutes? }` — see below |
 
-`format: "age"` on a `facet-table` column or `facet-board` field renders a timestamp as a compact age (`12m`, `3h`, `2d`) with the absolute time as its tooltip, repainted each minute — aging interim states are scannable at a glance.
+`format: "age"` (or its spoken twin `"ago"`) on a `facet-table` column or `facet-board` field renders a timestamp as a compact age (`12m`, `3h`, `2d`) with the absolute time as its tooltip, repainted each minute — aging interim states are scannable at a glance. `format: "date"` renders the full date the dashboard uses everywhere, hoverable for the exact time; a bare ISO timestamp with no format renders the same way. Both readings of a date column are useful: age for pace, date for the record.
+
+The `facet-table` renders at the table's dense setting: small type and tight side padding, so a row of six values fits without truncating. When no column declares a `width`, the first column holds 200px and the rest share the remainder; the row action sizes to its label.
 
 `format: "user"` resolves a user-id token — `{{escalation.assigned_to}}` — to that person's display name. Resolution is batched: every id on a page is coalesced into one `POST /api/users/names` request returning display fields only (no secrets, scopes, or metadata), cached by id for the session and not refetched on window focus; a user edit invalidates the cache. It truncates with an ellipsis and carries the full name on hover; an unassigned row shows a quiet em dash. `assigned_to` is the claimant while the item is worked and stays as the resolver once it is resolved, so one column reads correctly across the row's whole life. The built-in table and timeline views carry this user column by default; authored templates opt in per column.
 

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

@@ -6,7 +6,7 @@ The form runs a full validation pass before any submit is accepted. Every visibl
 
 ## Required
 
-Fields listed in the schema's `required` array block submission when empty. A red asterisk marks required fields. Required validation is skipped for fields hidden by `x-lt-showIf` at submission time.
+Fields listed in the schema's `required` array block submission when empty. A red asterisk marks required fields. Empty means `null`, `undefined`, blank text, an unchecked checkbox, an object with no truthy value, an empty multi-select, or an empty `json` list. A boolean with an option list is answered by either value, and a `json` map is answered by any key. Required validation is skipped for fields hidden by `x-lt-showIf` at submission time.
 
 ```json
 {
@@ -93,9 +93,30 @@ When `envelope.min_score` is `60`, submitting a score of `45` blocks with "Minim
 
 ---
 
-## Dynamic Select Options (`x-lt-options`)
+## Select Options (`x-lt-options`)
 
-A select's option list can ride the escalation instead of the schema. The field-level token names a `"domain.path"`; the array of strings or numbers at that path becomes the field's options — one static role form, per-row legal values:
+`x-lt-options` takes one of three forms. A `"domain.path"` string, or an array of path strings, resolves the list from the context (first path that resolves wins). An array with **no string entries** is the list itself, written inline: `{ value, label }` objects, numbers, or booleans. A literal string value is written as an object, `{ "value": "rn", "label": "Registered Nurse" }`, since a bare string is always read as a path. A static `enum` wins over both.
+
+```json
+{
+  "properties": {
+    "role": {
+      "type": "string",
+      "x-lt-options": [{ "value": "rn", "label": "Registered Nurse" }, { "value": "lpn", "label": "Practical Nurse" }]
+    },
+    "powerCycled": {
+      "type": "boolean",
+      "x-lt-options": [{ "value": true, "label": "Yes" }, { "value": false, "label": "No" }]
+    }
+  }
+}
+```
+
+A boolean with an option list renders as a select, not a checkbox: use it for decisions, and keep the checkbox for confirmations.
+
+**Clearable selects.** A select opens on a disabled **Choose…** placeholder and, once a value is picked, offers no way back. With `"x-lt-nullable": true` the placeholder stays enabled and picking it submits `null`, for a choice that may lawfully stay unmade.
+
+The list can also ride the escalation instead of the schema. The token names a `"domain.path"`; the array of strings or numbers at that path becomes the field's options, one static role form, per-row legal values:
 
 ```json
 {
@@ -126,6 +147,32 @@ When the envelope carries `left_quantity_options: [0, 1, 2, 3]`, the field rende
 
 ---
 
+## Lists and Maps
+
+A `type: "array"` field with its own `x-lt-options` (path or literal) renders as a multi-select of chips; the submitted value is the array of picked values in list order. A list is validated only when it is edited this way or through the `json` widget; a list shown as read-only tags is left alone.
+
+```json
+{
+  "required": ["roles"],
+  "properties": {
+    "roles": { "type": "array", "x-lt-options": [{ "value": "gluer", "label": "Gluer" }, { "value": "qa", "label": "QA" }], "minItems": 1, "maxItems": 2 },
+    "weights": {
+      "type": "object",
+      "x-lt-widget": "json",
+      "propertyNames": { "enum": ["bag", "plate", "spool"] },
+      "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }
+    }
+  }
+}
+```
+
+- A required multi-select or `json` list needs at least one item. An empty optional list passes its constraints.
+- Every item must belong to the option list (`Must be one of: gluer, qa`); `minItems`/`maxItems` bound the length (`At least 1 item`, `At most 2 items`); a `json` list checks each item against `items`, including `items.enum` (`Item 2: Expected a number`).
+- A map's keys must belong to `propertyNames.enum` (`Unknown key "tray". Allowed: bag, plate, spool`) and every value must satisfy an object-shaped `additionalProperties` (`"bag": Minimum value is 0`). A required map needs at least one key; a zero weight is an answer.
+- The same rules run on the wire: an API or MCP caller sending the list or map under the bound key receives the same violations as the form shows.
+
+---
+
 ## Checklist Completion (`x-lt-require-all`)
 
 A checklist-widget field can require every item to be checked before submission: