@hotmeshio/long-tail 0.10.13 → 0.11.0

package/docs/escalation-analytics.md

@@ -0,0 +1,251 @@
+# Escalation Analytics — Instrumenting a Process
+
+Every escalation is one interval an entity spends in one state: it opens at
+`created_at` and closes the instant the row leaves the live set. The
+escalation queue is therefore a complete state time-series for every process
+the platform runs, and the analytics surface reads it three ways — the
+aggregate, the categorical slice, and the individual — from vocabulary the
+workflow already writes plus two dials on the role.
+
+This page is the whole authoring contract. The worked example is the seeded
+printer scenario (`examples/seed-fleet-sim.ts`), which a fresh install
+produces automatically; every call below runs verbatim against it.
+
+## The sixty-second contract
+
+**1. The workflow parks every state as an escalation.** `role` is the queue
+that attends the state. `subtype` names the state *within* the role, for
+roles that hold several. `metadata` carries the entity key (stored as a JSON
+string) plus any categorical facts worth slicing by.
+
+```typescript
+// Inside a durable workflow: park the printer in the fleet queue, printing.
+const result = await condition(signalId, {
+  activity: ltCreateEscalation,
+  config: {
+    type: 'fleet',
+    subtype: 'printing',          // the state, within the printer-fleet role
+    role: 'printer-fleet',        // the queue that attends it
+    metadata: {
+      serialNumber: 'PRN-001',    // the entity
+      model: 'h2s',               // categorical facts, sliceable
+      pdac: true,
+      foaming: false,
+    },
+  },
+});
+```
+
+**2. Each role declares two dials** (in the role admin page's Pace Board
+section, beside the priority dials, or via `PATCH /api/roles/:role`):
+
+| Dial | Meaning |
+|------|---------|
+| **Entity** (`entity_facet`) | The metadata key naming what moves through this role — `serialNumber` here. Roles sharing an entity key form that entity's **system**; the system is derived, never maintained. |
+| **States from** (`entity_state_source`) | How the role names its contribution to the entity's state space. `'role'` (default): being in this queue is one state — a harvest or service bay. `'subtype'`: the role's subtypes are its states — a fleet role whose rows park as `idle` / `printing`. |
+
+The printer scenario declares three roles:
+
+```
+printer-fleet     entity_facet: serialNumber   states from: subtype  (idle, printing)
+printer-harvest   entity_facet: serialNumber   states from: role
+printer-service   entity_facet: serialNumber   states from: role
+```
+
+That is the entire contract. Everything below is reading it back.
+
+## The three questions
+
+### Q1 — the fleet: how did all printers spend their time?
+
+One call: scope to the entity's system, group by the derived state, measure
+dwell (open-seconds, clipped to the window).
+
+```bash
+ltc esc aggregate-facets --entity serialNumber --group-state \
+  --window '{"from":"2026-08-01T00:00:00Z","to":"2026-08-01T12:00:00Z"}'
+```
+
+```typescript
+const { data } = await client.escalations.aggregateByFacets({
+  query: { entity: 'serialNumber' },
+  groupBy: { state: true },
+  measure: { kind: 'dwell', window: { from, to } },
+});
+// → groups: [{ state: 'idle', dwellSeconds, ... }, { state: 'printing', ... },
+//            { state: 'printer-harvest', ... }, { state: 'printer-service', ... }]
+```
+
+```bash
+curl -s -X POST http://localhost:3000/api/escalations/aggregate-by-facets \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"query":{"entity":"serialNumber"},"groupBy":{"state":true},
+       "measure":{"kind":"dwell","window":{"from":"2026-08-01T00:00:00Z","to":"2026-08-01T12:00:00Z"}}}'
+```
+
+Each role contributes states per its dial: the fleet's subtypes (`idle`,
+`printing`) plus the harvest and service roles themselves.
+
+**Membership** is the other measure — rows (or, with `distinctBy`, distinct
+entities) open at an instant. Omit `asOf` for now; a past `asOf` reconstructs
+the live set at that moment.
+
+```typescript
+// How many printers are in each state right now?
+await client.escalations.aggregateByFacets({
+  query: { entity: 'serialNumber' },
+  groupBy: { state: true },
+  measure: { kind: 'membership' },
+  distinctBy: 'serialNumber',
+});
+// → one group per state, count = printers (not rows)
+```
+
+### Q2 — the slice: the same, compared by any facet
+
+Q1 plus `groupBy.facets` — each value gets an independent state split, and a
+NULL group key is a real group (rows missing the facet).
+
+```bash
+ltc esc aggregate-facets --entity serialNumber --group-state --group-facets model \
+  --window '{"from":"2026-08-01T00:00:00Z","to":"2026-08-01T12:00:00Z"}'
+# → p1s and h2s, each with its own idle/printing/harvest/service dwell
+```
+
+Filtering works the same way: `--facets '{"pdac":true}'` restricts the whole
+aggregate to the pdac printers.
+
+### Q3 — the individual: how did printer X spend its day?
+
+The ordered interval sequence across the whole system, durations included.
+Gaps between intervals are untracked time and are preserved — the settle
+latency between queues is a first-class signal.
+
+```bash
+ltc esc timeline serialNumber PRN-001 --entity serialNumber
+```
+
+```typescript
+const { data } = await client.escalations.timelineByFacet({
+  facet: { key: 'serialNumber', value: 'PRN-001' },
+  query: { entity: 'serialNumber' },
+});
+// → intervals: [{ role, subtype, startedAt, endedAt, durationSeconds }, ...]
+//   open intervals report endedAt: null; gaps appear as time between spans
+```
+
+```bash
+curl -s -X POST http://localhost:3000/api/escalations/timeline-by-facet \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"facet":{"key":"serialNumber","value":"PRN-001"},"query":{"entity":"serialNumber"}}'
+```
+
+## Where the answers appear in the dashboard
+
+- **Q1** — `/operations`: the view selector offers every entity system beside
+  the station view; the system band shows state dwell over the selected
+  period with membership-now counts and the distinct-entity headline.
+- **Q2** — the entity view's **Slice by** control: pick any metadata key the
+  rows carry and each value renders its own band, side by side.
+- **Q3** — the entity table's timeline action, or the history affordance on
+  any metadata value in any escalation list: the full cross-queue journey in
+  the side panel, untracked gaps included.
+
+Every surface refreshes from escalation events — resolve something and the
+band moves within seconds.
+
+## The interval, precisely
+
+`[created_at, ended_at)`. `ended_at` derives from the terminal transition:
+`resolved_at` for resolved rows, `updated_at` for cancelled or expired rows
+(both stamped inside their status-guarded transitions), NULL while the row is
+live. The `lt_escalations` view exposes it as a computed column, and a
+partial index on the terminal end instant keeps history scans bounded — one
+index write per row, at its terminal transition.
+
+`liveStatuses` (default `['pending']`) declares which statuses count as
+live; everything else is terminal.
+
+## Locating one entity among thousands
+
+Two filter fields make the individual findable at fleet scale, and both ride
+the scans the aggregate already bounds — no additional indexes:
+
+- **`prefix`** — case-insensitive prefix match on facet values
+  (`metadata->>key ILIKE 'value%'`, wildcards escaped). Type or scan the
+  leading characters of a serial and the entity table narrows:
+
+  ```bash
+  ltc esc aggregate-facets --entity serialNumber --group-facets serialNumber \
+    --prefix '{"serialNumber":"PRN-00"}' --window '{"from":"...","to":"..."}'
+  ```
+
+- **`anyOf`** — the row carries at least one of the given facet sets
+  (`metadata @> ANY(...)`, GIN-served; max 200 entries). Targets an explicit
+  entity set — the current table page — in one query:
+
+  ```json
+  { "anyOf": [{ "serialNumber": "PRN-001" }, { "serialNumber": "PRN-002" }] }
+  ```
+
+Result groups page with `orderBy` + `limit`/`offset`; `overflow: true` means
+another page exists. In the dashboard, every entity row is deep-linkable:
+`/operations?lens=serialNumber&entity=PRN-003` opens the fleet view focused
+on that printer with its timeline panel raised, and `&find=PRN-00` restores
+a narrowed table.
+
+## Paging a long timeline
+
+Timelines order by start instant. The default `asc` reads the journey
+top-down; a long history pages recent-first with `order: 'desc'` and the
+`before` cursor (a strict upper bound on `startedAt`):
+
+```bash
+ltc esc timeline serialNumber PRN-001 --entity serialNumber \
+  --order desc --limit 100
+# then, for the next-older page:
+ltc esc timeline serialNumber PRN-001 --entity serialNumber \
+  --order desc --limit 100 --before 2026-08-01T09:15:00Z
+```
+
+The dashboard's timeline panel loads the most recent 100 intervals and
+offers "Load earlier" until the history is exhausted.
+
+## Fail-loud validation
+
+The filter takes the WHAT of a facet query only — `role`/`roles` (or
+`entity`), `facets`, `block`, `range`, `exists`. Everything that would
+silently change what an aggregate means is rejected with a 400:
+
+- `status`, `available`, `jeopardy` on the filter — liveness derives from
+  the interval and the measure
+- `orderBy`/`limit`/`offset` on the filter — paging applies to result groups
+- `entity` together with `role`/`roles` — one scoping mechanism at a time
+- an entity key no role declares — the response names the configuration gap
+- `groupBy.state` together with `states[]` — one labeling mechanism
+- a window wider than `LT_ANALYTICS_MAX_WINDOW_DAYS`, a future `asOf`,
+  malformed facet keys, unknown statuses
+
+Result groups are capped (`LT_ANALYTICS_MAX_GROUPS`); when more exist the
+response carries `overflow: true`.
+
+## Access
+
+Aggregates and timelines require `read_all` on every role in scope —
+entity-derived roles included. A query with no role scope spans every queue
+and requires a global principal. With the public Pace Board flag on,
+counts-only aggregates (no facet keys among the group keys) are readable by
+any login — the same data class the station metrics expose; facet-keyed
+groupings and timelines always take the full gate. See [iam.md](iam.md).
+
+## Reference
+
+- HTTP: [api/http/escalations.md](api/http/escalations.md)
+- SDK: `client.escalations.aggregateByFacets` / `timelineByFacet`
+- MCP: `aggregate_by_facets` / `timeline_by_facet` on the admin server
+- CLI: `ltc esc aggregate-facets`, `ltc esc timeline` — [cli.md](cli.md)
+- Config: `LT_ANALYTICS_MAX_GROUPS`, `LT_ANALYTICS_MAX_WINDOW_DAYS`,
+  `LT_ANALYTICS_CACHE_TTL_MS`, `LT_ANALYTICS_PAST_CACHE_TTL_MS`,
+  `LT_ANALYTICS_CACHE_MAX_ENTRIES`
+
+To watch the seeded fleet move live: `npm run printers:cycle`.

package/docs/hitl/roles.md

@@ -57,7 +57,7 @@ const decision = await conditionLT<{ confirmed: boolean; address: string }>(sign
 
 ## Escalation Chains
 
-Users can escalate to other roles via the "Escalate" tab on the detail page. Configure chain targets in Admin > Roles. Each role lists which other roles it can escalate to. Common shape:
+Chains are role-to-role routing edges, configured via the roles API (`POST /api/roles/escalation-chains`). Each role lists which other roles it can route work to, and the edges scope the programmatic re-routing surfaces — the `escalate_and_wait` MCP tool and the escalate APIs (HTTP, SDK, MCP, CLI). Common shape:
 
 ```
 Analyst → Senior Analyst → Manager → VP

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

@@ -227,7 +227,8 @@ A top-level form_schema token (a peer of `x-lt-help`) that keeps the resolve but
       "assigned": "me"
     },
     "mustBeEmpty": true,
-    "message": "{{count}} item(s) still pending — pick them before closing the order."
+    "message": "{{count}} item(s) still pending — pick them before closing the order.",
+    "autoResolveWhenEmpty": true
   },
   "type": "object",
   "properties": { ... }
@@ -239,12 +240,15 @@ A top-level form_schema token (a peer of `x-lt-help`) that keeps the resolve but
 | `query` | `object` | Same shape as `x-lt-query` — including the `assigned` ownership scope; facet string values interpolate against the host escalation's context |
 | `mustBeEmpty` | `boolean` | The gate condition (default `true`) |
 | `message` | `string` | Shown beside the disabled submit; `{{count}}` carries the live row count, `{{domain.path}}` tokens also interpolate |
+| `autoResolveWhenEmpty` | `boolean` | Auto-submit the claimed parent the moment the query is confirmed empty |
 
-The guard and an escalation-list embed declaring the same query resolve through one shared mapping — the count and the visible rows always agree, whatever the scope.
+The guard and an escalation-list embed declaring the same query resolve through one shared mapping — the count and the visible rows always agree, whatever the scope. Pair it with an `escalation-list` embed on the same query so the operator sees exactly which rows are holding the gate.
 
-Pair it with an `escalation-list` embed on the same query so the operator sees exactly which rows are holding the gate.
+**Only a confirmed empty read clears the gate** — a successful query returning zero rows. While it is loading, or on an error or a 403, the submit stays disabled: the gate opens only when it can prove there is nothing left.
 
-The guard is a UI layer: it makes the form honest, it does not enforce. A resolve arriving through the raw API bypasses it by design — the consuming workflow's own verification (reject and re-park with the remainder) is the durable backstop. Triage is never gated: when the guarded work itself is the problem, "Send to Triage" stays available.
+**Enforced on both sides.** The dashboard disables the submit; for `enforce_schema` roles the API server runs the same query and rejects a resolve with a canonical `422` while it returns rows, so the rule holds through the raw API too. The server counts the true children regardless of the resolver's read scope, so a role that cannot see them can never falsely clear the gate. A surface with no resolving user (an MCP resolve of an `assigned:"me"` guard) and roles that do not `enforce_schema` fall back to the consuming workflow's own verification (reject and re-park with the remainder) as the durable backstop. Triage is never gated: when the guarded work itself is the problem, "Send to Triage" stays available.
+
+**`autoResolveWhenEmpty`** closes the loop. With it set, the claimed parent submits itself the moment the query is confirmed empty — re-checked on page-load and after each inline child-resolve — so a person clears the children (resolving them in place via `x-lt-actions`) and the parent closes with no extra click. A parent launched from a list with [`x-lt-submit-on-claim`](./x-lt-footer.md) that carries a guard claims, shows its children, and auto-closes as they drain; if the parent has a [transition](./x-lt-transition.md), it then hands off to the follow-on. The parent's own form must still validate — an incomplete parent is left for the person rather than auto-closed.
 
 ---
 

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

@@ -0,0 +1,67 @@
+# x-lt-footer — the escalation footer, configured
+
+A role's versioned `form_schema` can, at its root, shape the standard escalation
+footer: rename its action controls and fold claim-and-submit into one gesture.
+Both tokens are opt-in top-level form tokens, siblings of
+[`x-lt-transition`](./x-lt-transition.md) and `x-lt-submit-guard`
+([x-lt-embed.md](./x-lt-embed.md)).
+
+## Tokens (schema root)
+
+| Token | Type | Meaning |
+|-------|------|---------|
+| `x-lt-submit-on-claim` | boolean | Claiming also resolves, submitting whatever the form holds. Defaults off. |
+| `x-lt-labels` | object | Per-target overrides for the footer's action labels. |
+
+## `x-lt-labels` — configurable copy
+
+An object whose keys are standard footer targets and whose values are the labels
+to render in their place:
+
+| Target | Default | Control |
+|--------|---------|---------|
+| `claim` | Claim | The claim button (unclaimed). |
+| `cancel` | Cancel / Cancel escalation | The cancel control, both states. |
+| `submit` | Submit / Acknowledge | The resolve button (claimed). |
+| `release` | Release | The release tab. |
+
+```jsonc
+{
+  "type": "object",
+  "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" },
+  "properties": { /* … */ }
+}
+```
+
+Only the known targets are read; unknown keys and non-string values are
+ignored. Any target the schema omits keeps its default, so a schema overrides
+just the controls it cares about. The pending, triage, and confirmation states
+("Claiming…", "Send to Triage", "Yes, Release") keep their own copy.
+
+## `x-lt-submit-on-claim` — the one-gesture claim
+
+When true, clicking Claim also resolves the escalation in the same gesture,
+submitting the form's current values — its seeded defaults (metadata,
+`formDefaults`, or schema `default`), or a restored draft. The person advances
+the work item with a single click; there is no second Submit step.
+
+```jsonc
+{
+  "type": "object",
+  "x-lt-submit-on-claim": true,
+  "x-lt-labels": { "claim": "Claim and Submit" },
+  "properties": {
+    "approved": { "type": "boolean", "default": true }
+  }
+}
+```
+
+Claim and resolve are distinct operations — the server accepts a resolve only
+from the claimant — so they run in sequence: claim, then resolve. If the seeded
+defaults fail validation the claim still stands and the page drops into the
+normal claimed state with the field errors in the side panel, so the person
+completes the form by hand. Pair it with `x-lt-labels.claim` so the button reads
+honestly ("Claim and Submit").
+
+Use it when the standard outcome needs only a confirmation — the defaults are
+the answer, and claiming is the decision.

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

@@ -31,9 +31,10 @@ Every layout carries a persistent action button — the active card's CTA, a tra
 
 ```jsonc
 "x-lt-row-action": {
-  "action": "claim",        // "claim" | "view" — default "claim"
-  "label": "Service",       // button text; defaults "Claim" / "View"
-  "durationMinutes": 60     // claim hold time; default 30
+  "action": "claim",         // "claim" | "view" — default "claim"
+  "label": "Service",        // button text; defaults "Claim" / "View"
+  "durationMinutes": 60,     // claim hold time; default 30
+  "submitOnClaim": true      // claim AND submit, then transition on (see below)
 }
 ```
 
@@ -41,6 +42,12 @@ Every layout carries a persistent action button — the active card's CTA, a tra
 
 On My Escalations (`/escalations/queue`) every row is already held by the viewer, so a `claim` template renders as a View action there: the button opens the detail page with the default "View" label. Authored `view` actions keep their label.
 
+### Start from the list — `submitOnClaim`
+
+`submitOnClaim: true` turns the row action into a one-gesture start: the row is claimed and its form's seeded defaults are submitted, then — when the resolve spawns a follow-on born assigned to the person — the wait screen bridges to it. A "Start Harvesting" button on the list claims, submits, and lands the person on the next step, no detail-page stop in between.
+
+The behavior itself lives on the form: the claim-and-submit and the hand-off are the form schema's [`x-lt-submit-on-claim`](./x-lt-footer.md) and [`x-lt-transition`](./x-lt-transition.md). The list action only launches that flow with the authored claim duration — so one role owns the outcome and the list template just points to it. If the seeded defaults fail validation the claim still lands and the person finishes on the detail page. Applies to claimable rows; on My Escalations the row already belongs to the viewer, so it opens as a View.
+
 ---
 
 ## Layouts

package/docs/hitl-guide.md

@@ -20,6 +20,8 @@ This works because the form is data: a JSON Schema stored on the role, versioned
 | Sections, columns, ordering, side-panel help | Layout keywords | [x-lt-layout.md](hitl/x-lt-layout.md) |
 | Runtime-driven items, files, signatures, SOP blocks | Widgets | [x-lt-widget.md](hitl/x-lt-widget.md) |
 | A role-authored list page — document views, facet tables, entity card boards | List schema | [x-lt-list-schema.md](hitl/x-lt-list-schema.md) |
+| Rename the resolve footer, or claim-and-submit in one gesture | Footer tokens | [x-lt-footer.md](hitl/x-lt-footer.md) |
+| Block the resolve until embedded work drains, then auto-close when it does | `x-lt-submit-guard` | [x-lt-embed.md](hitl/x-lt-embed.md) |
 | A fully custom UI nothing above can express | Iframe viewport | [iframe.md](hitl/iframe.md) |
 
 ---
@@ -59,12 +61,12 @@ When you author a HITL-backed workflow, the platform handles:
 - **Accessible forms** — generated controls carry label association, error announcements, and keyboard-correct locking (see [form.md](hitl/form.md#accessibility))
 - **Side panel** — help, AI analysis, metadata, context, and raw-record views beside the form
 - **Section state persistence** — collapsed sections remembered across navigation
-- **Escalation chains** — users can re-route work to other roles
+- **Escalation chains** — role-to-role routing edges that scope programmatic re-routing (API, MCP, CLI)
 - **AI triage** — optional auto-resolution for common patterns
 - **Credential security** — password fields use ephemeral tokens, never stored in plain text
 - **Schema enforcement** — roles with `enforce_schema` validate every resolver payload server-side (dashboard, API, MCP, CLI alike) with the same pass the form runs, rejecting violations as a structured 422 (see [schema-enforcement.md](schema-enforcement.md))
 - **Telemetry** — trace IDs link escalations to OpenTelemetry traces
-- **Bulk operations** — bulk claim, assign, escalate, triage, and cancel for queue management
+- **Bulk operations** — bulk claim, assign, triage, and cancel for queue management
 - **Cancellation** — cancel pending escalations from the API or dashboard
 
 You write the workflow and the schema. Everything else is provided.
@@ -84,6 +86,8 @@ Ordered as a learning path — each file adds one capability to the same form:
 | Layout, ordering, sections, binding, help panel | [x-lt-layout.md](hitl/x-lt-layout.md) |
 | Custom widgets (checklist, file upload, code editor, signature, markdown) | [x-lt-widget.md](hitl/x-lt-widget.md) |
 | List schema (`active-history`, `active`, `facet-table`, `facet-board` cards) | [x-lt-list-schema.md](hitl/x-lt-list-schema.md) |
+| Embedded widgets (`link`, `escalation`, `escalation-list`) and the submit guard | [x-lt-embed.md](hitl/x-lt-embed.md) |
+| Footer labels, claim-and-submit, and the list-driven "start" action | [x-lt-footer.md](hitl/x-lt-footer.md) |
 | Iframe viewport protocol | [iframe.md](hitl/iframe.md) |
 | Claim lifecycle, resolving from system code, outcome recording, cancellation | [resolution.md](hitl/resolution.md) |
 | Role routing, RBAC, scope, chains | [roles.md](hitl/roles.md) |
@@ -118,7 +122,12 @@ Ordered as a learning path — each file adds one capability to the same form:
 | `x-lt-help` | schema | Markdown guidance for the side panel's Help view |
 | `x-lt-context` | schema | Plain-text fallback for the Help view when `x-lt-help` is absent |
 | `x-lt-viewport` | schema | Replace the generated form with a custom iframe UI |
+| `x-lt-submit-guard` | schema | Block the resolve while an embedded escalation query returns rows; `autoResolveWhenEmpty` auto-closes the claimed parent once it drains. Enforced isomorphically for `enforce_schema` roles |
+| `x-lt-submit-on-claim` | schema | Claiming also resolves the form's seeded defaults in one gesture |
+| `x-lt-labels` | schema | Per-target labels for the footer controls (`claim`, `cancel`, `submit`, `release`) |
+| `x-lt-transition` | schema | Pause on a wait screen after resolve and hand off to the born-assigned follow-on |
 | `x-lt-columns` | schema (list) | Column definitions for `facet-table` layout |
+| `x-lt-row-action` | schema (list) | Per-row list action: `claim` / `view`, or `submitOnClaim` to claim, submit, and transition straight from the list |
 | `x-lt-active` | schema (list) | Active-item card definition |
 | `x-lt-history` | schema (list) | History column definition |
 | `format` | field | Input specialization: `password`, `date`, `date-time`, `email`, `uri`, `textarea` |

package/docs/iam.md

@@ -92,6 +92,12 @@ HTTP surface: `GET/POST /api/personas`, `GET/PATCH/DELETE /api/personas/:key`, `
 
 Scope folds into the SQL, so it is atomic with no TOCTOU window. Read scope becomes part of the escalation search query — a member sees a row when `role ∈ allRoles OR (role ∈ selfRoles AND assigned_to = me)`. Write scope folds into the atomic resolve-by-metadata query and gates the by-id claim/resolve/cancel paths. `assigned_to` is indexed, so `self` scope scales to large queues.
 
+### Analytics gate
+
+The escalation analytics surfaces (`aggregate-by-facets`, `timeline-by-facet`) are reads that aggregate other operators' items, and they may span roles — so the gate is `read_all` on **every** role in the query's scope. When the filter uses `entity`, the scope is the derived system: every role declaring that entity facet. A query with no role scope at all is inherently cross-role and requires a global principal (superadmin/admin).
+
+While the `features.publicPaceBoard` flag stands (default on), counts-only aggregates — groupings with no `groupBy.facets` keys — are readable by any login: they emit counts and seconds, the same data class station metrics already expose to everyone. Facet-keyed groupings emit facet values (entity ids) as group keys, and a timeline is one entity's movement history — item-level disclosure — so both always take the full `read_all`-per-role gate.
+
 ## Workflow Types and IAM
 
 Long Tail has three workflow types (see the [Workflows Guide](workflows.md#three-workflow-types) for full details). IAM applies to all three:
@@ -239,6 +245,12 @@ If a token is expired or exhausted, the opaque string passes through unchanged.
 
 When an activity calls `getCredential('anthropic')` and no credential exists in the cascade (principal → initiator → env var), `MissingCredentialError` is thrown. The interceptor catches this and creates a credential-focused escalation with `category: 'missing_credential'`. The escalation form can include a password field so the human provides the credential ephemerally, without it being stored permanently.
 
+### Acting identity (badge grants)
+
+The same keystore carries **acting-identity grants** for shared station devices. A device signs in once as a station account — `read_scope: 'all'`, `write_scope: 'none'` on the queues it fronts — so reads are free and every mutation is structurally blocked for the account itself. A badge scan under an identity-kind scan scheme resolves the badge token against a server-side binding (`lt_users.metadata`, e.g. `badge_id`) and mints `eph:v1:acting_identity:<uuid>` under the scheme's TTL/max-uses policy.
+
+The grant rides scan requests as `actingToken` and is exchanged server-side before anything reads or writes: the verbs run **as the badged person under their own live RBAC**. The grant confers attribution, never privilege — a badged user without write scope on the queue is still denied. Mutations attribute to the person (`assigned_to`, `resolved_by`) with the device recorded beside them (`scanStation` provenance). A dead grant is a loud `not_primed` outcome, never a silent execution as the device. See [scan-codes.md](scan-codes.md#identity-schemes-and-acting-identity).
+
 ## Dashboard
 
 The dashboard surfaces IAM across four pages:

package/docs/operations.md

@@ -90,6 +90,23 @@ A 340 px right rail that slides open when a row or chart circle is clicked. Thre
 
 Close the panel with × or by clicking another row.
 
+## Entity lens
+
+The board carries one view selector. When any station declares an entity facet, a lens strip appears above the chart: **Stations** (the default station-first board) plus one lens per entity facet the visible roles declare, labeled `by <key>` (e.g. `by serialNumber`). The active lens is deep-linked (`?lens=<key>`). Selecting a lens flips the page from station-first to entity-first: roles sharing the facet form the entity's **system**, and each role contributes states per its `entity_state_source`. Three tiers, aggregate → individual:
+
+- **The system band** — how the fleet's time splits across states over the selected period: one stacked dwell band with a per-state legend (duration, percentage, and a `· N now` membership count where entities currently sit), headlined by the distinct-entity count in queue now (e.g. `6 serialNumber in queue now`).
+- **Slice by** — the same band per value of any metadata key, chosen from a select of the known facet keys (e.g. `model` splits the band into `p1s` vs `h2s`). Small-multiple bands, ranked by total dwell, top 8 values.
+- **The entity table** — one row per entity, ranked by tracked time: the entity value, its current state, its own dwell band, its total tracked time, and a timeline action that opens the entity's cross-queue interval timeline in the right panel.
+
+The lens is driven by two dials on the role's Pace Board section ([Role Detail](dashboard.md#role-detail)):
+
+| Dial | Description |
+|------|-------------|
+| `entity_facet` | The `lt_escalations.metadata` key naming the entity that moves through the role (e.g. `serialNumber`, `orderId`). Roles sharing a key form that entity's system. Blank = the role has no entity notion. |
+| `entity_state_source` | How the role names the entity's state: **Station** (`'role'` — being in this role is one state, e.g. a servicing queue) or **Subtypes** (`'subtype'` — the one role holds several states named by each escalation's subtype, e.g. a fleet role parking `idle` / `printing`). Default `'role'`. |
+
+The band tiers are counts-only aggregates, readable by any login while the public board flag stands; the slice and per-entity tiers group by facet values and require full (`read_all`) access to the system's queues. Data comes from `POST /api/escalations/aggregate-by-facets` and `POST /api/escalations/timeline-by-facet` — see [escalation-analytics.md](escalation-analytics.md) for the query contract.
+
 ## Data source
 
 All station metrics come from `GET /api/escalations/station-metrics?period=<period>`. The endpoint runs two queries against `public.hmsh_escalations` joined to `lt_roles` (for the priority dials and `target_per_hour`): a live-counts pass over the pending backlog, and a window-bounded percentile pass over resolved rows (`PERCENTILE_CONT` in Postgres, served by the `idx_hmsh_esc_resolved_cover` index). Updates reach the page as push events — every escalation write invalidates the metrics through the Socket.IO event system.

package/docs/scan-codes.md

@@ -22,6 +22,9 @@ canonical action surface. A scan is an **ECA rule** over that surface:
 - [Schemes](#schemes)
 - [Rules and steps](#rules-and-steps)
 - [Confirmation](#confirmation)
+- [Info-choice screens](#info-choice-screens)
+- [Identity schemes and acting identity](#identity-schemes-and-acting-identity)
+- [Station deployments](#station-deployments)
 - [The fallback screen](#the-fallback-screen)
 - [Executing a scan](#executing-a-scan)
 - [Capture on the dashboard](#capture-on-the-dashboard)
@@ -122,6 +125,115 @@ rule's prompt ("Cancel this printer's current state and send it home to
 servicing?"). Confirming fires the standard per-id endpoint — the same
 guarded call every other surface uses.
 
+## Info-choice screens
+
+Some objects carry one code for their whole life — an item tag, an order
+label. One code, many possible intents, and the right one depends on where
+the object is in its journey. The `present` verb closes that gap: the step
+locates the row, states its reality, and returns a configured, labeled
+choice set for the human to pick from. Upper half — what is true; lower
+half — what you may do about it.
+
+```jsonc
+{
+  "query": { "roles": ["printer-fleet", "printer-harvest", "printer-service"] },
+  "verb": "present",
+  "choices": [
+    { "label": "Claim & Start", "verb": "claim", "requireActingIdentity": true, "code": "CLAIM" },
+    { "label": "Complete", "verb": "resolve", "requireActingIdentity": true,
+      "confirm": { "prompt": "Mark this item complete?" },
+      "params": { "resolverPayload": { "outcome": "complete" } } },
+    { "label": "View Details", "verb": "show-detail" }
+  ]
+}
+```
+
+The scan answers `choices` with the located escalation and the choice list;
+each choice carries `withheld: true` when its identity requirement is
+unsatisfied. Picking one calls `POST /api/scan-codes/execute-choice` with a
+pointer (scheme, category, step index, choice index, escalation id) — and a
+pointer is never authority: the server re-reads live config, re-locates the
+row under the step's query, re-applies the identity gate, and runs the verb
+through the same atomic executors a direct scan uses. A row that moved on
+between render and tap answers `conflict`, exactly as a lost double-scan.
+
+A choice's `code` is a short printable token (letters, digits, underscore,
+dash) enabling double-scan selection: scan the object, then scan an action
+card. The station screen matches the second scan against the presented
+choices before treating it as a new code.
+
+A claim choice lands on the work: after `claim` or `claim-show-detail`
+executes, the station navigates to the escalation's detail page — the same
+form every operator uses to resolve, reject, or conclude the item.
+
+**One scan, one action.** A step with exactly one confirm-less choice can
+set `autoSelectSingle: true`: the scan executes the choice directly instead
+of presenting a one-button screen. The worker scans the item that just
+arrived at their bench and it is theirs, claimed for the configured
+duration, form on screen. An unsatisfied identity requirement never
+auto-fires as the wrong actor — the scan stops over at the badge screen and
+completes on its own once a badge primes.
+
+## Identity schemes and acting identity
+
+A scheme with `kind: "identity"` is the badge layer. Its `target_facet`
+names the `lt_users.metadata` key the scanned badge token matches (the demo
+binds `badge_id`) — resolution is only ever that metadata equality, so a
+printed username can never impersonate. Identity rules carry no steps;
+their `fallback` is the unknown-badge screen.
+
+A matching badge scan answers `identity_primed` with the person's display
+name, an expiry, and an **acting grant** — an ephemeral token
+(`eph:v1:acting_identity:…`) minted through the internal keystore under the
+scheme's policy:
+
+| Scheme field | Meaning |
+|---|---|
+| `grant_ttl_seconds` | How long the grant lives (1–86400). |
+| `grant_max_uses` | `0` = TTL-bound; `n` = the grant covers n scan requests (a strict one-scan policy is `1`). |
+
+The grant rides subsequent scans as `actingToken`. Verbs then run **as the
+badged person under their own live RBAC** — the grant confers attribution,
+never privilege. A dead grant (expired, exhausted, revoked) is a loud
+`not_primed`, never a silent execution as the device. Scanning the next
+badge replaces the session's grant; passing `previousActingToken` revokes
+the outgoing one immediately.
+
+Steps and choices opt in with `requireActingIdentity: true`: the effective
+actor must be a real acting identity — a badge grant, or an authenticated
+user whose own write scope covers the step. When unsatisfied, the outcome
+is `not_primed` with the rule's `notPrimed` screen (a sibling of
+`fallback`): the "scan your badge" message, never a silent or misattributed
+action.
+
+## Station deployments
+
+A shared floor device (tablet + tethered scanner) signs in once as a
+station account — an ordinary user with `read_scope: 'all'` and
+`write_scope: 'none'` on the queues it fronts. Reads are free: the station
+holds a real seat with a queue view and an audit identity. Every mutation
+takes the badge layer, and `write_scope: 'none'` is the structural
+backstop — even a misconfigured rule cannot mutate as the station, because
+the RBAC write gate denies the account itself.
+
+Mutations attribute to the badged person (`assigned_to`, `resolved_by`)
+with the device recorded beside them (`scanStation` in the scan
+provenance) — every action individually owned and geographically placed.
+The dashboard's `/scan/station` route is the full-screen experience: idle
+("scan your badge / scan an item"), the primed chrome with the grant
+countdown, the info-choice screen, and the **badge stop-over** — the one
+identity moment the flow ever surfaces. When an action needs a person and
+none is primed (a withheld choice tapped, an auto-select scan, a grant that
+lapsed mid-flow), the screen becomes a single clear prompt: scan your badge
+to continue. The badge scan primes the session and the pending action
+completes on its own. With a live grant the stop-over never appears — the
+identity layer is invisible when all is well.
+
+Badge tokens are printed credentials: seed them as long random strings,
+bind them server-side (`lt_users.metadata`), and treat badge possession
+with the same physical policy as any badge system. Unknown badges answer
+`identity_unknown` and are auditable.
+
 ## The fallback screen
 
 When no step matches, the response carries the rule's `fallback`: markdown

package/docs/sdk.md

@@ -63,7 +63,7 @@ The client mirrors the REST route structure:
 | Namespace | REST equivalent | Key operations |
 |-----------|----------------|----------------|
 | `lt.tasks` | `/api/tasks` | `list`, `get`, `listProcesses`, `getProcess`, `getProcessStats` |
-| `lt.escalations` | `/api/escalations` | `list`, `listAvailable`, `get`, `claim`, `release`, `resolve`, `escalate`, `bulkClaim`, `bulkAssign`, `findByMetadata`, `claimByMetadata`, `resolveByMetadata` |
+| `lt.escalations` | `/api/escalations` | `list`, `listAvailable`, `get`, `claim`, `release`, `resolve`, `escalate`, `bulkClaim`, `bulkAssign`, `findByMetadata`, `claimByMetadata`, `resolveByMetadata`, `aggregateByFacets`, `timelineByFacet` — see the [Escalations SDK reference](api/sdk/escalations.md) |
 | `lt.workflows` | `/api/workflows` | `invoke`, `getStatus`, `getResult`, `terminate`, `listWorkers`, `listDiscovered`, `listConfigs`, `getConfig`, `upsertConfig` |
 | `lt.yamlWorkflows` | `/api/yaml-workflows` | `list`, `get`, `create`, `deploy`, `activate`, `invoke`, `archive` |
 | `lt.users` | `/api/users` | `list`, `get`, `create`, `update`, `delete`, `getRoles`, `addRole`, `removeRole` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.10.13",
+  "version": "0.11.0",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -45,6 +45,7 @@
     "demo": "bash scripts/demo.sh",
     "ortho:populate": "ts-node scripts/ortho-populate.ts",
     "twin:farm": "ts-node scripts/twin-farm.ts",
+    "printers:cycle": "ts-node scripts/printer-cycle.ts",
     "dashboard:install": "cd dashboard && npm install",
     "dashboard:dev": "cd dashboard && npm run dev",
     "dashboard:build": "cd dashboard && npm run build",