@hotmeshio/long-tail 0.10.13 → 0.11.0

package/docs/api/http/escalations.md

@@ -1154,3 +1154,136 @@ Batch-claim individual rows matching a facet query (`FOR UPDATE SKIP LOCKED`), a
 | `allOrNone` | `boolean` | no | Commit only if the full set was acquired |
 
 **Response 200:** `{ "claimed": [...] }`.
+
+## Aggregate by facets
+
+```
+POST /api/escalations/aggregate-by-facets
+```
+
+Grouped analytics over the escalation intervals. Every escalation is one open interval `[created_at, ended_at)` — `ended_at` is the instant the row left the live set (resolved / cancelled / expired), `NULL` while live. The aggregate reads that time-series two ways: **membership** (rows — or, with `distinctBy`, distinct entities — whose interval is open at an instant; a past `asOf` reconstructs the live set at that moment) and **dwell** (open-seconds per group within a half-open `[from, to)` window, clipped to it on both ends). One call replaces N per-filter count round-trips. See [escalation-analytics.md](../../escalation-analytics.md) for the full guide.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `query` | `object` | yes | The filter — `role`/`roles` (or `entity`), `facets`, `anyOf` (rows carrying ANY of the given facet sets, max 200 — target an explicit entity set such as one table page), `block`, `range`, `exists`, and `prefix` (case-insensitive prefix match on facet values — the locate affordance, e.g. `{"serialNumber":"PRN-00"}`). `entity` names an entity facet key and resolves server-side to every role declaring it as its `entity_facet` — the entity's **system**; mutually exclusive with `role`/`roles`, and it implies `exists: [entity]` so stray rows without the key stay out |
+| `groupBy` | `object` | yes | Group keys — `columns` (whitelisted: `role`, `subtype`, `status`), `facets` (metadata keys, projected as text; `NULL` group key when absent), and `state` (group by the derived state label: each role contributes per its `entity_state_source` — its subtypes or itself; mutually exclusive with `states[]`). An empty object yields one total row |
+| `measure` | `object` | yes | Exactly one kind: `{ "kind": "membership", "asOf"? }` (default anchor: now) or `{ "kind": "dwell", "window": { "from", "to" } }` |
+| `distinctBy` | `string` | no | Membership only — count DISTINCT of this metadata facet per group (entities, not rows). Omit to count rows |
+| `states` | `array` | no | Pure labeling: tag each group with the FIRST matching `{ name, match }` entry, evaluated top-to-bottom; `match` compares grouped columns/facets. Grouping is unchanged |
+| `liveStatuses` | `string[]` | no | Statuses considered live (default `["pending"]`) |
+| `orderBy` | `array` | no | Order the RESULT groups: `{ field, direction? }` — `count`, `dwellSeconds`, `sampleCount`, a grouped column, or a grouped facet key |
+| `limit` / `offset` | `integer` | no | Result-group paging, capped at `LT_ANALYTICS_MAX_GROUPS` |
+
+The filter takes the WHAT fields only. `status`, `available`, and `jeopardy` are rejected — liveness derives from the interval, `liveStatuses`, and the measure anchor. Query-level `orderBy`/`limit`/`offset` are rejected too — order and paginate the result groups with the top-level fields.
+
+**Example** — how the printer fleet spent a day, one row per state. The three seeded roles declare `entity_facet: "serialNumber"`: `printer-fleet` uses `entity_state_source: "subtype"` (its `idle` / `printing` subtypes are states), while `printer-harvest` and `printer-service` use `"role"` (each role is a state):
+
+```json
+{
+  "query": { "entity": "serialNumber" },
+  "groupBy": { "state": true },
+  "measure": {
+    "kind": "dwell",
+    "window": { "from": "2026-08-01T00:00:00Z", "to": "2026-08-02T00:00:00Z" }
+  }
+}
+```
+
+**Response 200:**
+
+```json
+{
+  "groups": [
+    { "facets": {}, "state": "printing", "dwellSeconds": 214380, "sampleCount": 41 },
+    { "facets": {}, "state": "idle", "dwellSeconds": 132600, "sampleCount": 38 },
+    { "facets": {}, "state": "printer-harvest", "dwellSeconds": 21540, "sampleCount": 17 },
+    { "facets": {}, "state": "printer-service", "dwellSeconds": 9060, "sampleCount": 3 }
+  ],
+  "overflow": false
+}
+```
+
+Adding `"facets": ["model"]` to `groupBy` slices the same bands per model value (`p1s` vs `h2s`).
+
+**Response fields (per group):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `role` / `subtype` / `status` | `string` | Present iff requested in `groupBy.columns`. `status` is the row's status NOW — status history is not stored, so a past `asOf` still groups by current status |
+| `facets` | `object` | One entry per `groupBy.facets` key; `null` when the facet is absent on the underlying rows |
+| `state` | `string` | Present when `groupBy.state` derived it or a `states[]` entry matched |
+| `count` | `number` | Membership: entities (with `distinctBy`) or rows (without) |
+| `dwellSeconds` | `number` | Dwell: summed open-seconds within the window |
+| `sampleCount` | `number` | Underlying escalation rows contributing to the group (pre-distinct) |
+
+`overflow: true` means the group cap was hit — more groups exist beyond this page.
+
+**Response 400** — a caller-input problem: a liveness field (`status`/`available`/`jeopardy`) or `orderBy`/`limit`/`offset` on the filter; `entity` together with `role`/`roles`; `groupBy.state` together with `states[]`; an unknown status in `liveStatuses`; an empty window or one wider than `LT_ANALYTICS_MAX_WINDOW_DAYS`; a future `asOf`; a malformed facet key; a `states[]` match referencing a key the query never groups by.
+
+**Response 403** — the caller must hold `read_all` on every role in scope (for `entity`, every role in the derived system); a filter with no role scope spans every pond and requires a global principal (superadmin/admin). While `features.publicPaceBoard` stands (default on), counts-only groupings — no `groupBy.facets` keys — are readable by any login, the same data class the Pace Board exposes; a facet-keyed grouping emits facet values (entity ids) as group keys and always takes the full gate.
+
+## Timeline by facet
+
+```
+POST /api/escalations/timeline-by-facet
+```
+
+One entity's ordered interval sequence — every escalation the entity facet appeared in, as `[startedAt, endedAt)` spans with durations, in `created_at` order. Open intervals report `endedAt: null`. Gaps between consecutive intervals are untracked time and are preserved, not filled. The facet is matched GIN-served (`metadata @> {key: value}`), so the stored value must be a JSON string.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `facet` | `{ key, value }` | yes | The entity facet to trace |
+| `query` | `object` | no | Optional extra filter / role scope (or `entity` — the derived system). Same field rules as the aggregate filter |
+| `window` | `{ from, to }` | no | Only intervals overlapping the window (overlap-filtered, not clipped) |
+| `select` | `object` | no | `columns` / `facets` to surface per interval (default: all three columns) |
+| `liveStatuses` | `string[]` | no | Statuses considered live (default `["pending"]`) |
+| `order` | `string` | no | Interval ordering by start instant — `asc` (default) or `desc`; `desc` + `before` pages a long history recent-first |
+| `before` | `string` | no | Strict upper bound on `startedAt` (ISO instant) — the "load earlier" cursor |
+| `limit` | `integer` | no | Max intervals |
+
+**Example** — one printer's movement across the fleet's queues:
+
+```json
+{
+  "facet": { "key": "serialNumber", "value": "PRN-001" },
+  "query": { "entity": "serialNumber" }
+}
+```
+
+**Response 200:**
+
+```json
+{
+  "intervals": [
+    {
+      "role": "printer-fleet",
+      "subtype": "printing",
+      "status": "resolved",
+      "facets": {},
+      "startedAt": "2026-08-01T08:00:00.000Z",
+      "endedAt": "2026-08-01T09:30:00.000Z",
+      "durationSeconds": 5400
+    },
+    {
+      "role": "printer-harvest",
+      "subtype": "harvest",
+      "status": "pending",
+      "facets": {},
+      "startedAt": "2026-08-01T09:30:00.000Z",
+      "endedAt": null,
+      "durationSeconds": 1800
+    }
+  ],
+  "overflow": false
+}
+```
+
+`durationSeconds` runs to `endedAt`, else to `window.to` clamped at now. `overflow: true` means the interval cap was hit.
+
+**Response 400** — same validation class as the aggregate: a rejected filter field, an invalid window, a malformed facet key.
+
+**Response 403** — timelines always take the full gate: an entity's movement history is item-level disclosure. The caller must hold `read_all` on every role in scope (for `entity`, every role in the derived system); a roleless query requires a global principal.

package/docs/api/http/roles.md

@@ -252,6 +252,8 @@ Returns all roles with metadata and usage counts.
       "worker_count": 4,
       "priority_threshold_minutes": null,
       "priority_facet": null,
+      "entity_facet": null,
+      "entity_state_source": "role",
       "user_count": 5,
       "chain_count": 2,
       "workflow_count": 3
@@ -275,6 +277,8 @@ Returns all roles with metadata and usage counts.
 | `worker_count` | `number \| null` | Capacity at this station — staff or machine count (capacity setting) |
 | `priority_threshold_minutes` | `number \| null` | Max age (minutes) before a pending unclaimed item counts toward `priority_count` in station metrics; falls back to `sla_minutes` |
 | `priority_facet` | `string \| null` | Escalation metadata key holding the age origin as an ISO 8601 UTC timestamp (e.g. `authorized_at`); falls back to `created_at` |
+| `entity_facet` | `string \| null` | Escalation metadata key naming the **entity** that moves through this role (e.g. `serialNumber`, `orderId`). Roles sharing the key form that entity's system; the analytics surfaces (distinct-entity counts, per-entity dwell, entity timelines) derive from it. `null` = the role has no entity notion |
+| `entity_state_source` | `'role' \| 'subtype'` | How the role names its contribution to the entity's state space: `'role'` (the station itself is the state) or `'subtype'` (the role's subtypes are its states). Default `'role'`; only meaningful while `entity_facet` is set |
 | `user_count` | `number` | Number of users assigned this role |
 | `chain_count` | `number` | Number of escalation chain entries referencing this role |
 | `workflow_count` | `number` | Number of workflow configs that reference this role |
@@ -374,6 +378,8 @@ When the update changes `form_schema` or `metadata_schema`, the new pair is snap
 | `worker_count` | `number \| null` | Station capacity |
 | `priority_threshold_minutes` | `number \| null` | Priority age threshold in minutes; falls back to `sla_minutes` |
 | `priority_facet` | `string \| null` | Metadata key for the priority age origin (letters, numbers, underscores); falls back to `created_at` |
+| `entity_facet` | `string \| null` | Metadata key naming the entity that moves through this role (letters, numbers, underscores). Roles sharing the key form the entity's system for the analytics surfaces. `null` clears |
+| `entity_state_source` | `'role' \| 'subtype' \| null` | How the role names the entity's states — the station itself (`'role'`) or its subtypes (`'subtype'`). `null` resets to the `'role'` default |
 | `upstream_roles` | `string[] \| null` | Replace the set of roles this station draws input from across other Operations sequences (omitted = preserve; `null` or `[]` = clear). Every entry must name an existing role other than this one. Distinct from `parent_role`, which places the role in its own sequence. |
 | `list_schema` | `object \| null` | Rich formatting (x-lt-* markup) for this role's escalation LIST page. Versions independently of `form_schema`; the list always renders the latest |
 | `default_pins` | `array \| null` | Pinned-view seeds for members: `[{ label, url, badge? }]` with dashboard-relative `url`s. Members promote, hide, or reorder them via their own preferences (`/api/me/preferences`). `null` clears |

package/docs/api/mcp/admin.md

@@ -377,6 +377,59 @@ Update the priority of multiple escalations.
 | ids | string[] | Yes | Escalation IDs |
 | priority | integer | Yes | New priority value |
 
+### aggregate_by_facets
+
+Grouped analytics over the escalation intervals. Every escalation is one open
+interval `[created_at, ended_at)`; this tool reads it two ways: **membership**
+(rows or, with `distinctBy`, distinct entities open at an instant — a past
+`asOf` reconstructs the live set then) and **dwell** (open-seconds per group
+within a half-open `[from, to)` window). Group by role/subtype/status columns
+plus metadata facet keys; optional `states[]` label each group. One call
+replaces N per-filter count round-trips. Mirrors
+`POST /api/escalations/aggregate-by-facets`.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| query | object | Yes | The filter (WHAT only — no status/available/jeopardy): `role`/`roles` or `entity` (the entity facet key, resolved to every role declaring it — the entity's system), plus `facets`, `block`, `range`, `exists` |
+| groupBy | object | Yes | Group keys: `columns` (`role`, `subtype`, `status`), `facets` (metadata keys), `state` (derived state label per each role's `entity_state_source`; mutually exclusive with `states`). Empty object → one total row |
+| measure | object | Yes | `{ kind: "membership", asOf? }` or `{ kind: "dwell", window: { from, to } }` |
+| distinctBy | string | No | Membership only: count DISTINCT of this metadata facet (entities, not rows) |
+| states | array | No | Pure labeling: tag each group with the FIRST matching state name |
+| liveStatuses | string[] | No | Statuses considered live (default `["pending"]`) |
+| orderBy | array | No | Order the RESULT groups: `{ field, direction? }` |
+| limit | integer | No | Max result groups (server-capped; `overflow` flag when more exist) |
+| offset | integer | No | Result-group offset |
+
+### timeline_by_facet
+
+One entity's ordered interval sequence — every escalation the entity facet
+(e.g. a machine id) appeared in, as `[startedAt, endedAt)` spans with durations,
+in `created_at` order. Open intervals report `endedAt: null`. Gaps between
+consecutive intervals are untracked time and are preserved, not filled. The
+entity facet value must be stored as a JSON string (GIN containment match).
+Mirrors `POST /api/escalations/timeline-by-facet`.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| facet | object | Yes | `{ key, value }` — the entity facet to trace |
+| query | object | No | Optional extra filter / role scope (or `entity` — the derived system) |
+| window | object | No | `{ from, to }` — only intervals overlapping this window (overlap-filtered, not clipped) |
+| select | object | No | `columns` / `facets` to surface per interval (default: all three columns) |
+| liveStatuses | string[] | No | Statuses considered live (default `["pending"]`) |
+| limit | integer | No | Max intervals |
+
 ## Workflow Configuration
 
 ### list_workflow_configs

package/docs/api/sdk/escalations.md

@@ -915,6 +915,64 @@ const result = await lt.escalations.claimByFacets({
 
 **Returns:** `LTApiResult<{ claimed }>`.
 
+## aggregateByFacets
+
+Grouped analytics over the escalation intervals — every escalation is one open interval `[created_at, ended_at)`, `ended_at` `NULL` while live. Two measures: **membership** (rows or, with `distinctBy`, distinct entities open at an instant; a past `asOf` reconstructs the live set then) and **dwell** (open-seconds per group within a half-open `[from, to)` window, clipped to it). `query.entity` names an entity facet key and scopes to every role declaring it as its `entity_facet` — the entity's system (mutually exclusive with `role`/`roles`); `groupBy.state` groups by the derived state label, each role contributing per its `entity_state_source`.
+
+```typescript
+// The printer fleet: how the entities spent the window, one row per state
+// (idle, printing, printer-harvest, printer-service)
+const result = await lt.escalations.aggregateByFacets({
+  query: { entity: 'serialNumber' },
+  groupBy: { state: true },
+  measure: { kind: 'dwell', window: { from: '2026-08-01T00:00:00Z', to: '2026-08-02T00:00:00Z' } },
+});
+
+// The slice: the same bands per model value (p1s vs h2s)
+await lt.escalations.aggregateByFacets({
+  query: { entity: 'serialNumber' },
+  groupBy: { state: true, facets: ['model'] },
+  measure: { kind: 'dwell', window: { from: '2026-08-01T00:00:00Z', to: '2026-08-02T00:00:00Z' } },
+});
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `query` | `AnalyticsQuery` | Yes | The filter — `role`/`roles` or `entity`, plus `facets`, `anyOf` (rows carrying ANY of the given facet sets, max 200), `block`, `range`, `exists`, and `prefix` (case-insensitive prefix match on facet values — the locate affordance). `status`/`available`/`jeopardy` and query-level paging are rejected with 400: liveness derives from the interval, `liveStatuses`, and the measure anchor |
+| `groupBy` | `FacetGroupBy` | Yes | `columns` (`role`, `subtype`, `status`), `facets` (metadata keys), `state` (derived state label; mutually exclusive with `states[]`). Empty object → one total row |
+| `measure` | `AggregateMeasure` | Yes | `{ kind: 'membership', asOf? }` or `{ kind: 'dwell', window }` |
+| `distinctBy` | `string` | No | Membership only — count DISTINCT of this facet (entities, not rows) |
+| `states` | `Array<{ name, match }>` | No | Pure labeling: tag each group with the first matching state name |
+| `liveStatuses` | `string[]` | No | Statuses considered live (default `['pending']`) |
+| `orderBy` / `limit` / `offset` | — | No | Order and page the RESULT groups (capped at `LT_ANALYTICS_MAX_GROUPS`) |
+
+**Returns:** `LTApiResult<{ groups: AggregateRow[]; overflow: boolean }>` — each group carries the grouped keys, `count` or `dwellSeconds`, and `sampleCount`. Gate: `read_all` on every role in scope (entity-derived roles included); a roleless filter requires a global principal; counts-only groupings (no `groupBy.facets`) are open to any login while `features.publicPaceBoard` stands. Mirrors `POST /api/escalations/aggregate-by-facets`.
+
+## timelineByFacet
+
+One entity's ordered interval sequence — every escalation the facet appeared in, as `[startedAt, endedAt)` spans with durations, in `created_at` order. Open intervals report `endedAt: null`; gaps are untracked time, preserved. GIN-served containment match — the stored facet value must be a JSON string. Always takes the full read gate (an entity's movement history is item-level disclosure).
+
+```typescript
+// One printer's movement across the fleet's queues
+const result = await lt.escalations.timelineByFacet({
+  facet: { key: 'serialNumber', value: 'PRN-001' },
+  query: { entity: 'serialNumber' },
+});
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `facet` | `{ key, value }` | Yes | The entity facet to trace |
+| `query` | `AnalyticsQuery` | No | Optional extra filter / role scope (or `entity` — the derived system) |
+| `window` | `{ from, to }` | No | Only intervals overlapping the window (overlap-filtered, not clipped) |
+| `select` | `{ columns?, facets? }` | No | Columns/facets to surface per interval (default: all three columns) |
+| `liveStatuses` | `string[]` | No | Statuses considered live (default `['pending']`) |
+| `order` | `'asc' \| 'desc'` | No | Interval ordering by start instant (default `asc`); `desc` + `before` pages a long history recent-first |
+| `before` | `Date \| string` | No | Strict upper bound on `startedAt` — the "load earlier" cursor |
+| `limit` | `integer` | No | Max intervals |
+
+**Returns:** `LTApiResult<{ intervals: TimelineInterval[]; overflow: boolean }>`. Mirrors `POST /api/escalations/timeline-by-facet`.
+
 ---
 
 ## getStationMetrics

package/docs/cli.md

@@ -78,8 +78,19 @@ ltc esc claim-by-meta orderId order-123             # Claim by metadata key
 ltc esc claim-by-meta orderId order-123 --assignee ext-user-42  # On behalf of user
 ltc esc resolve-by-meta orderId order-123 --data '{"approved": true}'
 ltc esc resolve-by-meta orderId order-123 --data '{"approved": true}' --assignee ext-user-42
+
+# Analytics: grouped membership/dwell aggregates and per-entity timelines
+# The fleet: how the entities spent the window, one row per state
+ltc esc aggregate-facets --entity serialNumber --group-state \
+  --window '{"from":"2026-08-01T00:00:00Z","to":"2026-08-02T00:00:00Z"}'
+# The individual: one printer's ordered interval timeline
+ltc esc timeline serialNumber PRN-001 --entity serialNumber
 ```
 
+`aggregate-facets` runs grouped analytics over the escalation intervals — membership at an instant (`--as-of`, default now), or dwell over a window (`--window` switches the measure). Scope with `--role`, `--roles`, or `--entity <key>` (the entity facet key — scopes to every role declaring it, the entity's system; no role at all spans every pond, global principals only). Group with `--group-columns role,subtype,status`, `--group-facets <list>`, or `--group-state` (the derived state label — each role's subtypes or itself). Refine with `--facets`/`--exists`, `--distinct-by <key>` (count entities, not rows; membership only), `--live-statuses`, and page the result groups with `--order-by`/`--limit`/`--offset`.
+
+`timeline <key> <value>` prints one entity's ordered escalation-interval timeline (gaps = untracked time). `--entity` scopes to the entity's system (every role declaring that entity facet); `--roles` restricts to specific roles; a call with neither spans every pond and requires a global principal. `--from`/`--to` keep only overlapping intervals; `--select-facets` surfaces metadata keys per interval.
+
 ### Workflows
 
 ```bash

package/docs/dashboard.md

@@ -56,7 +56,7 @@ The LLM authoring add-on. Appears when an Anthropic key is configured.
 | Page | Route | Purpose |
 |------|-------|---------|
 | **Accounts** | `/admin/users` | User accounts and service accounts (bots). Create, edit, assign roles, manage API keys. |
-| **Roles** | `/admin/roles` | Define roles — the queues, forms, and membership that connect workflows to people. Escalation chains, capacity settings, and versioned schemas live here. |
+| **Roles** | `/admin/roles` | Define roles — the queues, forms, and membership that connect workflows to people. Pace Board dials, capacity settings, versioned schemas, members, and default pins live here. |
 | **Personas** | `/admin/personas` | Bundle roles into named, one-step assignments. Each linked role carries a relationship scope (write-all, write-self, read-all); assigning a persona composes the member's whole surface from its roles' pins and schemas. |
 
 ### Infrastructure
@@ -223,41 +223,43 @@ Because roles carry the queue, the form schema, the membership, and the capacity
 
 **Master list** (`/admin/roles`) — one row per role:
 
-- **Ops dot** — a green dot marks roles that appear as stations on the [Pace Board](#pace-board).
-- **Role / Label / Description** — the role key and its human-facing identity.
+- **Role** — an ops status dot (green marks roles that appear as stations on the [Pace Board](#pace-board)) beside the display name: the user-set title, else Title Case derived from the key.
+- **Key** — the exact technical role id.
+- **Description** — the role's human-facing summary.
 - **Preceded By** — the role's prior step (`parent_role`), linked. Prior steps compose the Pace Board's sequences.
-- **Escalates To** — the chain targets this role can forward work to.
-- **Member Count** — how many accounts hold the role.
+- **Members** — how many accounts hold the role.
 - **Capacity** — SLA (minutes), Target (per hour), and Staff side by side. These drive the Pace Board's computed metrics.
 
 Search filters by key, label, or description. **+ Add Role** creates a role here; roles referenced in workflow configs are also auto-created at startup. Click any row to open [Role Detail](#role-detail).
 
-**API:** `GET /api/roles` lists roles. `POST /api/roles` creates. `GET /api/roles/details` returns full `RoleDetail` shapes. `GET /api/roles/escalation-chains` lists chains.
+**API:** `GET /api/roles` lists roles. `POST /api/roles` creates. `GET /api/roles/details` returns full `RoleDetail` shapes.
 
 ### Role Detail
 
-Accessible at `/admin/roles/:role`. One page per role — a header plus three columns covering identity, routing and people, and schemas.
+Accessible at `/admin/roles/:role`. One page per role — a quiet header carrying the role's identity, with the configuration organized into a five-section left sub-nav: **Identity · Pace Board · Schemas · Members · Pins**. The active section rides the URL (`?section=pace-board`), so deep links land on the right concern. One draft spans every section — switching sections never loses edits — and the **Save** button sits in the sub-nav footer, visible from every section. (Members, Pins, and Upstream Inputs save live.)
 
-**Header** — the role key with its prior step, the capacity set, and the **Ops** toggle that shows the role as a station on the [Pace Board](#pace-board). The capacity set holds `sla_minutes`, `target_per_hour`, and `worker_count`; enter any two and the header hints the derived third (`throughput = workers / (sla / 60)`). Beside it, the priority set holds `priority_threshold_minutes` and `priority_facet` — the age threshold and metadata timestamp key driving the Pace Board priority count (blank = `sla_minutes` and `created_at`). Save applies header and identity edits via `PATCH /api/roles/:role`.
+**Identity** — display name and description, shown on role rows and station labels. The danger zone lives here too: a role nothing references can be deleted.
 
-**Identity** — display name and description, shown on role rows and station labels.
+**Pace Board** — everything the board consumes about this role, in one column:
 
-**Sequence placement** — appears when the Ops toggle is on:
+- **Station** — the toggle that shows the role as a station on the [Pace Board](#pace-board).
+- **Capacity** — `sla_minutes`, `target_per_hour`, and `worker_count`; enter any two and the section hints the derived third (`throughput = workers / (sla / 60)`).
+- **Priority** — `priority_threshold_minutes` and the age facet (`priority_facet`) driving the Pace Board priority count and the jeopardy filter (blank = `sla_minutes` and `created_at`). The dials stay editable while the station is hidden — they also drive jeopardy in the queues.
+- **Entity** — the metadata key naming what moves through this station (`entity_facet`, e.g. `serialNumber`, `orderId`). Roles sharing a key form that entity's system: the [entity lens](operations.md#entity-lens), per-entity dwell, and timelines all derive from it. Once a key is set, the **States from** picker (`entity_state_source`) chooses how the station names the entity's state — **Station** (being here is one state, e.g. a servicing queue) or **Subtypes** (this one role holds several states named by each escalation's subtype, e.g. a fleet role parking `idle` / `printing`).
+- **Sequence** — board geometry, shown while the station is visible: **Prior Step** (places the role in one Pace Board sequence; a role with no prior step starts its own), **Upstream Inputs** (the roles this station also draws from in other sequences — mixin-like, many allowed, saved live, rendered as a merge glyph on the station, never a bend in the line), and **Home Segment** (lead the home Pace Board with this role's sequence; one role holds this).
 
-- **Prior Step** — places the role in one Pace Board sequence; a role with no prior step starts its own.
-- **Upstream Inputs** — the roles this station also draws from in other sequences. Mixin-like, many allowed, saved live. Rendered on the Pace Board as a merge glyph on the station, never a bend in the line: an upstream is an input, not a descendant.
+**Schemas** — the role's contracts:
 
-**Escalation Targets** — the chain out of this role, saved live. When a member escalates an item, these targets receive it. Chains are directional and support multiple targets per source.
+- **Enforcement** — the `enforce_schema` toggle: validate every resolve payload server-side against the role's form schema.
+- **Escalation Schema** — shows the schema version currently in use and links to the [Escalation Schema](#escalation-schema) editor page.
+- **Escalations List Schema** — shows the list-schema version in use and links to the [Escalations List Schema](#escalations-list-schema) editor page.
+- **Metadata Schema** — JSON Schema that validates each escalation's `metadata` at creation time. Its keys appear in faceted search autocomplete.
 
 **Members** — who holds the role: admins manage it; members work its queue according to their read/write work-surface scope (read = which items appear; write = which they can claim and resolve). A `member` grant carries a scope chosen from five named profiles: full worker (`all`/`all`, default), see-all-act-own (`all`/`self`), own-items-only (`self`/`self`), read-only auditor (`all`/`none`), and read-only own (`self`/`none`). The picker enforces **write ⊆ read**. `admin` and `superadmin` grants always work the whole queue.
 
-**Escalation Schema** — shows the schema version currently in use and links to the [Escalation Schema](#escalation-schema) editor page.
+**Pins** — 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. Live-save.
 
-**Metadata Schema** — JSON Schema that validates each escalation's `metadata` at creation time. Its keys appear in faceted search autocomplete.
-
-**Properties** — a free JSON bag for custom per-role values.
-
-**API:** `PATCH /api/roles/:role` updates identity, capacity, placement, and schemas. `POST /api/roles/escalation-chains` adds a chain target; `DELETE /api/roles/escalation-chains` removes one.
+**API:** `PATCH /api/roles/:role` updates identity, Pace Board dials, placement, schemas, and pins.
 
 ### Escalation Schema
 
@@ -334,10 +336,10 @@ The central queue for all escalation activity across every workflow.
 - **Title = queue selector** — the page title reads as the selected role's friendly title, or "All Escalations" when unfiltered; clicking it switches queues over the same `?role=` param the filter bar mirrors. The **My Escalations** personal inbox (`/escalations/queue`) carries the identical control, titling itself "My Escalations" or the filtered role's title.
 - **Filter bar** — filter by status (pending/claimed/resolved), role, workflow type, priority, and time window.
 - **Columns:** Escalation ID, workflow type, role, status, priority, created time, and claimed-by user.
+- **Metadata value affordances** — each metadata key/value row in the list carries a three-icon triad on hover: **filter** (filter the current role's queue to rows where the key equals this value), **search** (the same facet match across all roles), and **history** (open the entity's cross-queue interval timeline in the right panel — every station this value has moved through, with durations and gaps). Filter-present, search-present, history-past. The history affordance renders for string values, since the timeline's GIN containment match serves JSON-string facets.
 - **Rich list view** — when the list is scoped to exactly one role (`?role=<role>`) and that role owns a [list schema](#escalations-list-schema), a role-authored view renders in place of the table (the live item as a card, plus a load-on-demand history), with a **Table view** toggle back to the columns.
 - **Claim** — click the claim action to lock an escalation to your user. Only users with matching roles see pending escalations. The queue list and aggregate stats reflect `read_all` memberships — a member scoped to `read_self` lands directly on their own assigned item in user mode rather than browsing the full queue.
 - **Resolve** — after claiming, submit a resolver payload. The form is pre-filled from the role's versioned `form_schema` field defaults and from the workflow's seeded `envelope.formDefaults` (reverse-mapped through each field's `x-lt-bind`). The dashboard maps the flat form to the nested payload via `x-lt-bind` and the submitted payload is stored as-is. Resolution triggers a workflow re-run with the resolver data injected. A `member` whose `write_scope` is `self` can resolve only items already assigned to them; `write_scope=none` is read-only.
-- **Escalate** — forward a claimed escalation to a higher-tier role via the escalation chain.
 - **Side panel** — a slide-in beside the resolve form with switchable views, selected by the icon set at its top: **Help** (the form's `x-lt-help` markdown, `{{domain.path}}`-interpolated against the live record, or a state-aware hint such as "Claim this escalation to enable the form"), **Details** (status, role, priority, claim provenance, timestamps, and — for builders — identifier links), **AI Analysis** (what triage diagnosed and corrected — shown when AI is enabled and triage data is present), **Metadata** (the row's metadata values), **Context** (input envelope, escalation context, resolver payload), and **Record** (the raw escalation JSON, builders only). The panel and form share the width as a flex set — the form column narrows as the panel expands. It opens expanded on Help when the form carries `x-lt-help`, stays hidden otherwise, and the page-header panel button toggles it either way.
 
 **API:** `GET /api/escalations` lists with filters. `POST /api/escalations/:id/claim` claims. `POST /api/escalations/:id/resolve` resolves.

package/docs/data.md

@@ -106,9 +106,9 @@ Updated when claimed or resolved.
 
 The storage is the **shared HotMesh table `public.hmsh_escalations`**
 (written by both long-tail and the HotMesh SDK). `lt_escalations` remains as a
-backward-compatible **view** over it — `SELECT *` plus a computed `available`
-column — so existing read queries and the public API are unchanged. Indexes are
-managed by the SDK on `hmsh_escalations` (see below).
+backward-compatible **view** over it — `SELECT *` plus computed `available` and
+`ended_at` columns — so existing read queries and the public API are unchanged.
+Indexes are managed by the SDK on `hmsh_escalations` (see below).
 
 Role read/write scope does **not** add columns here. An escalation carries a `role`
 and an optional `assigned_to`; work-surface scope lives on the membership table
@@ -159,11 +159,12 @@ contract is stable.
 | `created_at` | `TIMESTAMPTZ NOT NULL` | `NOW()` | Row creation time |
 | `updated_at` | `TIMESTAMPTZ NOT NULL` | `NOW()` | Last modification |
 
-The `lt_escalations` view adds one computed column on top of the above:
+The `lt_escalations` view adds two computed columns on top of the above:
 
 | Column | Type | Description |
 |--------|------|-------------|
 | `available` | `BOOLEAN` | `true` when claimable — `assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()` |
+| `ended_at` | `TIMESTAMPTZ` | The instant the row left the live set — `NULL` while `pending`, `COALESCE(resolved_at, updated_at)` once terminal. Resolve stamps `resolved_at` in its guarded transition; cancel and expire stamp only `updated_at` in theirs, and no long-tail write path touches a terminal row afterward, so the coalesce is the transition instant for all three terminal statuses. Every escalation is thereby one open interval `[created_at, ended_at)` — the time-series the analytics surfaces read |
 
 **Claiming is implicit.** There is no separate status for "claimed". An escalation is considered claimed when `assigned_to IS NOT NULL` and `assigned_until > NOW()`. When the claim expires, the escalation is available again without any status change. The `/available` endpoint uses this logic:
 
@@ -187,6 +188,13 @@ WHERE status = 'pending'
 | `idx_hmsh_esc_task` | `(task_id) WHERE task_id IS NOT NULL` | Join escalations to their parent task |
 | `idx_hmsh_esc_workflow` | `(workflow_id) WHERE workflow_id IS NOT NULL` | Look up escalation by workflow ID |
 
+**Indexes** (app-managed, built at startup with `CREATE INDEX CONCURRENTLY`):
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| `idx_hmsh_esc_resolved_cover` | `(role, resolved_at DESC, claimed_at, created_at) WHERE status = 'resolved'` | Station-metrics percentile pass — bounds each station's scan to its resolved window and feeds the wait/work percentiles from the index |
+| `idx_hmsh_esc_ended_at` | `((COALESCE(resolved_at, updated_at))) WHERE status <> 'pending'` | The analytics interval scans — dwell and past-membership need terminal rows whose end instant falls after the window/`asOf`. The predicate excludes `pending` inserts, so each row costs exactly one index write, at its terminal transition |
+
 ### lt_users
 
 User and bot identity records. Users are created via the API and assigned roles that determine which escalations they can claim. Bot accounts (`account_type = 'bot'`) are service identities that authenticate with API keys.

package/docs/design-principles.md

@@ -24,9 +24,11 @@ swatches, and overlay scrims.
 
 Chroma is spent, not spread.
 
-- **Surfaces are near-neutral.** Hover fills, section bands, and borders
-  carry only a whisper of the theme hue. Chroma never lands on a large
-  rectangle — a colored slab makes every real accent invisible.
+- **Surfaces are near-neutral; lines carry the hue.** Hover fills and section
+  bands stay a whisper off-neutral, but the thin structure — borders,
+  dividers, outlines, field rules — carries a clear, light tint of the accent
+  so the frame reads as thematic. Chroma never lands on a large rectangle — a
+  colored slab makes every real accent invisible — but a hairline may glow.
 - **One elevation logic, both polarities.** The page carries the base wash
   (a light theme tint by day, the deep shade at night); sections and sheets
   are distinct surfaces on it (white paper by day, the deeper well at
@@ -64,10 +66,10 @@ Chroma is spent, not spread.
 
 ## 4. Fields and controls
 
-- **One recipe** (`.field/.input/.select/.textarea`): white body, light
-  neutral border, 3px radius (`--lt-radius-field`), border deepens to accent
-  and fill takes the theme tint on focus. Every field-like control uses the
-  recipe or the tokens — no bespoke field styling.
+- **One recipe** (`.field/.input/.select/.textarea`): white body, a light
+  accent-tinted border, soft radius (`--lt-radius-field`), border deepens to
+  accent and fill takes the theme tint on focus. Every field-like control uses
+  the recipe or the tokens — no bespoke field styling.
 - **Width follows content, capped by the measure:**
   - Generated forms hold a readable measure (`max-w-form`, 56rem). A wide
     monitor gets margin, never a 2000px input.