@hotmeshio/long-tail 0.10.14 → 0.11.1

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-footer.md

@@ -23,7 +23,6 @@ to render in their place:
 | `claim` | Claim | The claim button (unclaimed). |
 | `cancel` | Cancel / Cancel escalation | The cancel control, both states. |
 | `submit` | Submit / Acknowledge | The resolve button (claimed). |
-| `escalate` | Escalate | The escalate tab and button. |
 | `release` | Release | The release tab. |
 
 ```jsonc
@@ -34,7 +33,7 @@ to render in their place:
 }
 ```
 
-Only the five known targets are read; unknown keys and non-string values are
+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.

package/docs/hitl-guide.md

@@ -61,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.
@@ -124,7 +124,7 @@ Ordered as a learning path — each file adds one capability to the same form:
 | `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`, `escalate`, `release`) |
+| `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 |

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.14",
+  "version": "0.11.1",
   "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",

package/build/system/mcp-servers/admin/ortho.d.ts

@@ -1,10 +0,0 @@
-/**
- * Ortho pipeline MCP tools — AI-operable interface for the 8-stage manufacturing workflow.
- *
- * ortho_submit          — start a new order through the orthoPipeline workflow
- * ortho_pending         — list open stage escalations waiting for completion
- * ortho_complete_stage  — claim and resolve one stage escalation (advances the pipeline)
- * ortho_status          — get the current status and results for an order workflow
- */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerOrthoTools(server: McpServer): void;