@hotmeshio/long-tail 0.6.2 → 0.7.1

package/docs/api/http/escalations.md

@@ -36,13 +36,13 @@ GET /api/escalations
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `status` | `string` | `pending`, `resolved`, or `cancelled` |
+| `status` | `string` | `pending`, `resolved`, `cancelled`, or `expired` |
 | `role` | `string` | Filter by target role |
 | `type` | `string` | Filter by escalation type |
 | `subtype` | `string` | Filter by subtype |
 | `assigned_to` | `string` | Filter by claimer's user ID |
 | `priority` | `integer` | Filter by priority (1–4) |
-| `search` | `string` | Free-text across description/type/role/ids/metadata values (server-side) |
+| `search` | `string` | Exact-match by correlation id — escalation id, workflow id, or origin id (server-side, index-served). To match a value inside metadata, use `facets` |
 | `sort_by` / `order` | `string` | Single-column sort + direction (`asc`/`desc`) |
 | `limit` | `integer` | Max results (default: 50) |
 | `offset` | `integer` | Pagination offset (default: 0) |
@@ -419,6 +419,82 @@ Returns distinct escalation type values across all escalations.
 }
 ```
 
+## Station Metrics
+
+```
+GET /api/escalations/station-metrics
+```
+
+Per-role operational metrics for all visible stations. Returns queue depth, throughput efficiency, wait time (creation → claim) and work time (claim → resolution) at multiple percentiles. This drives the Operations pace chart and station detail panel.
+
+RBAC: `superadmin` sees all stations; other roles see only stations for their assigned roles.
+
+**Query parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `period` | `string` | `24h` | Lookback window for resolved/wait/work metrics. One of `15m`, `1h`, `24h`, `7d`, `30d` |
+
+**Response 200:**
+
+```json
+{
+  "stations": [
+    {
+      "role": "reviewer",
+      "pending": 12,
+      "claimed": 3,
+      "resolved": 45,
+      "in_arrears": 2,
+      "throughput_pct": 112.5,
+      "wait": {
+        "p99": 18.3,
+        "p50": 4.1,
+        "avg": 5.2,
+        "max": 22.0
+      },
+      "work": {
+        "p99": 28.7,
+        "p50": 14.0,
+        "avg": 15.3,
+        "max": 35.1
+      }
+    }
+  ]
+}
+```
+
+**Response fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `role` | `string` | Role key |
+| `pending` | `number` | Escalations currently pending (real-time) |
+| `claimed` | `number` | Escalations actively claimed (real-time) |
+| `resolved` | `number` | Escalations resolved within the selected period |
+| `in_arrears` | `number` | Pending escalations that have exceeded the role's `sla_minutes` target |
+| `throughput_pct` | `number \| null` | `resolved / (target_per_hour × period_hours) × 100`. `null` when the role has no `target_per_hour` set |
+| `wait.p99` | `number \| null` | 99th-percentile wait time in minutes (creation → first claim) within the period. `null` when no resolved items |
+| `wait.p50` | `number \| null` | Median wait time in minutes |
+| `wait.avg` | `number \| null` | Mean wait time in minutes |
+| `wait.max` | `number \| null` | Max wait time in minutes |
+| `work.p99` | `number \| null` | 99th-percentile work time in minutes (claim → resolution) |
+| `work.p50` | `number \| null` | Median work time |
+| `work.avg` | `number \| null` | Mean work time |
+| `work.max` | `number \| null` | Max work time |
+
+**Notes:**
+- `pending` and `claimed` reflect the live queue state, not the selected period.
+- `throughput_pct` above 100 means the station resolved more than its target — ahead of schedule. Below 100 means behind.
+- `in_arrears` counts items whose age exceeds the role's `sla_minutes`; it is 0 when `sla_minutes` is not configured for the role.
+- Time values are in decimal minutes.
+
+**Example:** Fetch station metrics for the last hour:
+
+```
+GET /api/escalations/station-metrics?period=1h
+```
+
 ## Get escalation stats
 
 ```
@@ -431,7 +507,7 @@ Aggregated escalation statistics. RBAC-scoped: superadmins see all; others see o
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `period` | `string` | Time period filter (e.g., `24h`, `7d`) |
+| `period` | `string` | Counting window for created/resolved. One of `1h`, `24h`, `7d`, `30d` (default `24h`; other values fall back to `24h`). Station metrics additionally support `15m` |
 
 **Response 200:**
 
@@ -804,7 +880,7 @@ Release a claimed escalation back to the available pool. Only the user who holds
 | `subtype` | `string` | Subcategory for finer routing |
 | `modality` | `string` | Modality from workflow config |
 | `description` | `string` | Human-readable reason |
-| `status` | `string` | `pending`, `resolved`, or `cancelled` |
+| `status` | `string` | `pending`, `resolved`, `cancelled`, or `expired` |
 | `priority` | `integer` | Numeric priority |
 | `task_id` | `UUID` | FK to the task that triggered this escalation |
 | `origin_id` | `string` | Correlation ID from the parent orchestrator |
@@ -828,7 +904,7 @@ See [Data Model](../data.md) for the full SQL schema and index strategy.
 
 ## Metadata Candidate Key Operations
 
-These endpoints find, claim, and resolve escalations using a business-domain key stored in the `metadata` JSONB column (e.g., `orderId`). No raw SQL needed — the GIN index makes lookups fast.
+These endpoints find, claim, and resolve escalations using a business-domain key stored in the `metadata` JSONB column (e.g., `orderId`). Lookups go straight through the GIN index on `metadata`, so they stay fast at any scale.
 
 All three endpoints accept an optional `assignee` field — an `external_id` from your auth system. Long Tail resolves it to an internal userId. When omitted, the authenticated caller is used.
 
@@ -844,7 +920,7 @@ Scoped to the caller's read access. A `member` with `read_scope=self` matches on
 |-----------|------|-------------|
 | `key` | `string` | **Required.** Metadata field name |
 | `value` | `string` | **Required.** Metadata field value |
-| `status` | `string` | Filter by status (`pending`, `resolved`, `cancelled`) |
+| `status` | `string` | Filter by status (`pending`, `resolved`, `cancelled`, `expired`) |
 | `limit` | `integer` | Max results (default 50) |
 | `offset` | `integer` | Pagination offset (default 0) |
 

package/docs/api/http/roles.md

@@ -231,19 +231,49 @@ Returns all distinct role names known to the system.
 GET /api/roles/details
 ```
 
-Returns all roles with usage counts.
+Returns all roles with metadata and usage counts.
 
 **Response 200:**
 
 ```json
 {
   "roles": [
-    { "role": "reviewer", "user_count": 5 },
-    { "role": "senior-reviewer", "user_count": 2 }
+    {
+      "role": "reviewer",
+      "title": "Document Reviewer",
+      "description": "Reviews flagged documents for compliance",
+      "form_schema": null,
+      "metadata_schema": null,
+      "properties": {},
+      "ops_visible": true,
+      "parent_role": null,
+      "sla_minutes": 30,
+      "target_per_hour": 20,
+      "worker_count": 4,
+      "user_count": 5,
+      "chain_count": 2,
+      "workflow_count": 3
+    }
   ]
 }
 ```
 
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string \| null` | Display name separate from the technical role key |
+| `description` | `string \| null` | Human-readable summary |
+| `form_schema` | `object \| null` | JSON Schema for the escalation resolve form (overridden per-workflow by `resolver_schema`) |
+| `metadata_schema` | `object \| null` | JSON Schema declaring the expected shape of `lt_escalations.metadata` for this role. Drives faceted-query key autocomplete and creation-time validation |
+| `properties` | `object` | Free user-owned bag — icons, colors, tags, etc. No reserved keys |
+| `ops_visible` | `boolean` | When `true`, the role appears as a station on the `/operations` view |
+| `parent_role` | `string \| null` | Parent role in the process dependency graph; `null` for root stations |
+| `sla_minutes` | `number \| null` | Target resolution time in minutes (capacity setting) |
+| `target_per_hour` | `number \| null` | Intended throughput — items resolved per hour (capacity setting) |
+| `worker_count` | `number \| null` | Capacity at this station — staff or machine count (capacity setting) |
+| `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 |
+
 ### Create a role
 
 ```
@@ -306,6 +336,55 @@ Delete a role if it has no references. Requires admin.
 { "error": "Cannot delete role" }
 ```
 
+### Update a role
+
+```
+PATCH /api/roles/:role
+```
+
+Update role metadata. Only provided fields are changed; omitted fields remain unchanged. `form_schema`, `metadata_schema`, and `parent_role` can be explicitly set to `null` to clear them. Requires role manager (admin type, superadmin, or engineer).
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `role` | Role key to update |
+
+**Request body** (all fields optional):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string \| null` | Display name |
+| `description` | `string \| null` | Short description |
+| `form_schema` | `object \| null` | JSON Schema for the resolve form |
+| `metadata_schema` | `object \| null` | JSON Schema for `lt_escalations.metadata` |
+| `properties` | `object \| null` | Free user-owned bag |
+| `ops_visible` | `boolean` | Include in the `/operations` view |
+| `parent_role` | `string \| null` | Parent in the process dependency graph |
+| `sla_minutes` | `number \| null` | SLA target in minutes |
+| `target_per_hour` | `number \| null` | Throughput target (items per hour) |
+| `worker_count` | `number \| null` | Station capacity |
+
+**Example request** — configure a role as a station in the ops view:
+
+```json
+{
+  "title": "Document Reviewer",
+  "ops_visible": true,
+  "sla_minutes": 30,
+  "target_per_hour": 20,
+  "worker_count": 4
+}
+```
+
+**Response 200:** Updated `RoleDetail` object (same shape as `GET /api/roles/details`).
+
+**Response 404:**
+
+```json
+{ "error": "Role 'unknown-role' not found" }
+```
+
 ---
 
 ## Escalation Chains

package/docs/api/mcp/admin.md

@@ -74,7 +74,7 @@ including `metadata`, workflow linkage, assignment, and `signal_key`.
 | type | string | No | Filter by type |
 | subtype | string | No | Filter by subtype |
 | assigned_to | string | No | Filter by assigned user UUID (active claim holder) |
-| search | string | No | Free-text search across description, type/subtype, role, workflow/origin id, and metadata values (e.g. a correlation key like an order id). Server-side over the full result set. |
+| search | string | No | Exact-match lookup by correlation id — escalation id, workflow id, or origin id (order/ticket). Index-served, server-side over the full result set. To match a value inside metadata (e.g. an order id), use `facets`. |
 | priority | integer | No | Filter by priority |
 | sort_by | string | No | Sort column: created_at, priority, updated_at |
 | order | string | No | Sort direction (asc, desc) for sort_by |
@@ -722,6 +722,30 @@ Create a new role. Lowercase alphanumeric with hyphens/underscores.
 |-------|------|----------|-------------|
 | role | string | Yes | Role name |
 
+### update_role
+
+Update a role's metadata: display name, description, form schema, metadata schema, free properties bag, operations visibility, process parent, and the typed operational targets (SLA minutes, throughput goal, worker count). Only provided fields are changed.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | Yes | Role key to update |
+| `title` | `string \| null` | No | Display name |
+| `description` | `string \| null` | No | Short description |
+| `form_schema` | `object \| null` | No | JSON Schema for the escalation resolve form |
+| `metadata_schema` | `object \| null` | No | JSON Schema for `lt_escalations.metadata` shape validation |
+| `properties` | `object \| null` | No | Free user-owned bag (icon, color, tags, etc.) |
+| `ops_visible` | `boolean` | No | When `true`, role appears as a station on the Operations view |
+| `parent_role` | `string \| null` | No | Parent role in the process dependency graph |
+| `sla_minutes` | `number \| null` | No | Target resolution time in minutes |
+| `target_per_hour` | `number \| null` | No | Throughput goal (items resolved per hour) |
+| `worker_count` | `number \| null` | No | Station capacity (staff or machines) |
+
 ### add_escalation_chain
 
 Define an escalation path from one role to another.
@@ -1428,3 +1452,105 @@ Return the numeric status semaphore for a workflow.
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | workflow_id | string | Yes | Workflow ID |
+
+## Ortho Pipeline
+
+AI-operable tools for driving the orthotic manufacturing pipeline. Each order passes through eight sequential stages (design → review → print → grind → glue → finish → qa → ship). The pipeline is a HotMesh durable workflow; each stage suspends at a `conditionLT` checkpoint until an escalation is resolved.
+
+A Claude agent loop calls `ortho_submit` to start an order, polls `ortho_pending` to see what's waiting, drives each stage forward with `ortho_complete_stage`, and monitors progress with `ortho_status`.
+
+### ortho_submit
+
+Start a new orthotic manufacturing order through the 8-stage pipeline.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `order_id` | `string` | Yes | Unique order identifier (e.g. `"ORD-001"`) |
+| `item_type` | `string` | Yes | Item type (e.g. `"insole-standard"`, `"insole-diabetic"`) |
+| `stages` | `string[]` | No | Override the stage sequence. Default: `["design","review","print","grind","glue","finish","qa","ship"]` |
+| `metadata` | `object` | No | Additional order metadata passed through to each stage escalation |
+
+**Returns:** `{ workflow_id, order_id, item_type, stages, message }`
+
+---
+
+### ortho_pending
+
+List open ortho-pipeline stage escalations waiting to be completed.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `stage` | `string` | No | Filter to a specific stage (e.g. `"design"`). Omit to see all stages |
+| `limit` | `integer` | No | Max results (default: 50) |
+
+**Returns:** `{ count, escalations }` where each escalation includes `id`, `stage`, `order_id`, `item_type`, `description`, `created_at`, `workflow_id`.
+
+---
+
+### ortho_complete_stage
+
+Complete a pending ortho pipeline stage. Claims the escalation and resolves it with notes and outcome data. Resolving automatically advances the workflow — a new escalation for the next stage appears within seconds.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `escalation_id` | `string` | Yes | Escalation ID from `ortho_pending` |
+| `notes` | `string` | Yes | Completion notes — what was done, any decisions made |
+| `outcome` | `object` | No | Structured outcome data specific to this stage |
+
+**Returns:** `{ resolved, escalation_id, status, message }`
+
+---
+
+### ortho_status
+
+Get the current status and completed stage results for an ortho pipeline workflow.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflow_id` | `string` | Yes | Workflow ID from `ortho_submit` |
+
+**Returns:** `{ workflow_id, status }` where `status` is `"running"` while in progress or `"complete"` with `result` containing all stage outputs once finished.
+
+---
+
+**Agent loop example:**
+
+```
+ortho_submit({ order_id: "ORD-042", item_type: "insole-diabetic" })
+→ { workflow_id: "wf-abc123", stages: ["design", "review", ...] }
+
+ortho_pending({ stage: "design" })
+→ [{ id: "esc-001", stage: "design", order_id: "ORD-042" }]
+
+ortho_complete_stage({ escalation_id: "esc-001", notes: "3mm heel, D-width approved", outcome: { spec_version: "v2" } })
+→ { resolved: true }
+
+... repeat through all 8 stages ...
+
+ortho_status({ workflow_id: "wf-abc123" })
+→ { status: "complete", result: { order_id: "ORD-042", results: [...] } }
+```

package/docs/api/sdk/escalations.md

@@ -79,7 +79,7 @@ const faceted = await lt.escalations.list({
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `status` | `string` | No | Filter by `pending`, `resolved`, or `cancelled` |
+| `status` | `string` | No | Filter by `pending`, `resolved`, `cancelled`, or `expired` |
 | `role` | `string` | No | Filter by assigned role |
 | `roles` | `string[]` | No | Restrict to these roles (`role = ANY`) — narrows within the caller's scope, never widens past it |
 | `type` | `string` | No | Filter by workflow type |
@@ -91,6 +91,7 @@ const faceted = await lt.escalations.list({
 | `range` | `{ facet, op, value }[]` | No | Numeric range over a metadata facet, e.g. `{ facet: 'confidence', op: '<=', value: 0.7 }` |
 | `exists` | `string[]` | No | Metadata keys that must be present — `metadata ? key` |
 | `available` | `boolean` | No | `true` = unclaimed/expired only; `false` = held now |
+| `search` | `string` | No | Exact-match by correlation id — escalation id, workflow id, or origin id (index-served). To match a value inside metadata, use `facets` instead |
 | `limit` | `number` | No | Max results (default: 50) |
 | `offset` | `number` | No | Pagination offset |
 | `sort_by` | `string` | No | Column to sort by (e.g. `created_at`, `priority`) |
@@ -365,7 +366,7 @@ Pass an escalation config as the second argument. The escalation row is written
 
 `conditionLT` returns `T | false | null`:
 - `T` — the resolver's payload (normal resolution)
-- `false` — the escalation timed out (if a timeout was configured)
+- `false` — the SLA timer fired first (`config.timeout`); the row is now `status='expired'`
 - `null` — the escalation was cancelled (workflow terminated or explicit `POST /api/escalations/:id/cancel`)
 
 Always guard for `null` and `false` before accessing the payload:
@@ -386,16 +387,32 @@ export async function stationWorker(envelope: LTEnvelope) {
     workflowType: 'stationWorker',
     metadata: { orderId: envelope.data.orderId, station: 'qc' },
     envelope: { instructions: 'Review and approve or reject' },
+    timeout: '24h',   // SLA for this worklist row (hotmesh 0.25.1+)
   });
 
-  if (!decision) {
-    // null = cancelled, false = timeout
+  if (decision === false) {
+    // SLA passed: the workflow resumed on the timer and the engine transitioned
+    // the row pending → expired atomically. A late resolve returns
+    // already-expired, and system.escalation.{id}.expired fired for dashboards.
+    return { type: 'return' as const, data: { autoRejected: 'sla' } };
+  }
+  if (decision === null) {
     return { type: 'return' as const, data: { cancelled: true } };
   }
   // decision is clean — the escalation was resolved by the resolve endpoint
 }
 ```
 
+### SLA-gated waits (`timeout`)
+
+`ConditionQueueConfig.timeout` (hotmesh 0.25.1+) arms the same resume timer as
+`condition(signalId, '24h')` **in the same single Leg1 write** that creates the
+escalation row. The race is resolved atomically on both sides: a signal that
+arrives first resolves the row normally and the timer is inert; a timer that
+fires first resumes the workflow with `false` and expires the row in a guarded
+UPDATE, so operators can never resolve into a workflow that already moved on.
+`expiresAt`, by contrast, is display metadata on the row — it arms nothing.
+
 ### Two-step form
 
 Create the escalation first (e.g. to enrich routing metadata), then wait:
@@ -860,3 +877,47 @@ const result = await lt.escalations.claimByFacets({
 ```
 
 **Returns:** `LTApiResult<{ claimed }>`.
+
+---
+
+## getStationMetrics
+
+Retrieve per-role throughput and latency metrics for all stations visible to the caller. Used by the Operations view to power the pace chart and station table.
+
+```typescript
+const result = await lt.escalations.getStationMetrics({ period: '24h' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `period` | `'1h' \| '24h' \| '7d' \| '30d' \| '15m'` | No | Lookback window for resolved/percentile stats (default `'24h'`) |
+
+**Returns:** `LTApiResult<{ stations: StationMetric[] }>`
+
+### StationMetric type
+
+```typescript
+interface StationMetricPeriod {
+  p99: number | null;   // minutes
+  p50: number | null;
+  avg: number | null;
+  max: number | null;
+}
+
+interface StationMetric {
+  role: string;
+  pending: number;        // currently queued (status = pending and not claimed)
+  claimed: number;        // active — claimed and assignment not expired
+  resolved: number;       // resolved within the lookback period
+  in_arrears: number;     // pending items older than sla_minutes
+  throughput_pct: number | null;  // resolved / (target_per_hour × hours) × 100
+  wait: StationMetricPeriod;      // queue time: created_at → claimed_at
+  work: StationMetricPeriod;      // processing time: claimed_at → resolved_at
+}
+```
+
+`pending` reflects the live queue depth regardless of period. `claimed`, `resolved`, and both percentile objects use the lookback window. `in_arrears` is computed from `sla_minutes` on the role — stations without `sla_minutes` always return `0`. `throughput_pct` is `null` when `target_per_hour` is not set.
+
+**Auth:** Same RBAC as `getStats` — callers see only the stations for roles they hold.

package/docs/api/sdk/roles.md

@@ -13,6 +13,50 @@ A role is a task queue worked by its members. Each `member` assignment carries t
 
 Scope is set when a role is assigned to a user, via [`lt.users.addRole`](users.md) and [`lt.users.create`](users.md). See [Roles API — Work-Surface Scope](../http/roles.md) for the five member profiles.
 
+## RoleDetail type
+
+`listWithDetails` and `update` return `RoleDetail` objects:
+
+```typescript
+interface RoleDetail {
+  role: string;
+  title: string | null;
+  description: string | null;
+  form_schema: Record<string, any> | null;
+  metadata_schema: Record<string, any> | null;
+  properties: Record<string, any>;
+  ops_visible: boolean;
+  parent_role: string | null;
+  sla_minutes: number | null;
+  target_per_hour: number | null;
+  worker_count: number | null;
+  user_count: number;
+  chain_count: number;
+  workflow_count: number;
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `role` | Unique role key |
+| `title` | Display name shown in the dashboard |
+| `description` | Short description of the role's purpose |
+| `form_schema` | Default JSON Schema for the resolve form; overridden per-escalation by `metadata.form_schema` |
+| `metadata_schema` | JSON Schema for `lt_escalations.metadata`; used for validation and UI hints |
+| `properties` | Free user-owned bag — arbitrary config stored on the role |
+| `ops_visible` | When `true`, the role appears as a station on the Operations view |
+| `parent_role` | Parent role in the process dependency graph; drives the pace chart dependency ordering |
+| `sla_minutes` | SLA target in minutes — items older than this appear in `in_arrears` in station metrics |
+| `target_per_hour` | Throughput target used to compute `throughput_pct` in station metrics |
+| `worker_count` | Station capacity — number of workers expected to be active |
+| `user_count` | Number of users currently assigned to this role |
+| `chain_count` | Number of escalation chain links originating from this role |
+| `workflow_count` | Number of registered workflows that target this role |
+
+The three capacity fields (`sla_minutes`, `target_per_hour`, `worker_count`) power the Operations station detail panel. `ops_visible` controls which roles appear on the `/operations` view. `parent_role` enables the process dependency graph in the pace chart — set it to describe which upstream role feeds this one.
+
+---
+
 ## list
 
 List all distinct role names in the system.
@@ -192,3 +236,40 @@ const result = await lt.roles.replaceEscalationTargets({
 **Returns:** `LTApiResult<{ role, targets }>`
 
 **Auth:** Not required
+
+---
+
+## update
+
+Update a role's metadata. Only provided fields are changed; omitted fields remain unchanged. `form_schema`, `metadata_schema`, and `parent_role` can be set to `null` to clear them.
+
+```typescript
+const result = await lt.roles.update({
+  role: 'reviewer',
+  title: 'Document Reviewer',
+  ops_visible: true,
+  sla_minutes: 30,
+  target_per_hour: 20,
+  worker_count: 4,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | Yes | Role key to update |
+| `title` | `string \| null` | No | Display name |
+| `description` | `string \| null` | No | Short description |
+| `form_schema` | `object \| null` | No | JSON Schema for the resolve form |
+| `metadata_schema` | `object \| null` | No | JSON Schema for `lt_escalations.metadata` |
+| `properties` | `object \| null` | No | Free user-owned bag |
+| `ops_visible` | `boolean` | No | Show as a station on the Operations view |
+| `parent_role` | `string \| null` | No | Parent role in the process dependency graph |
+| `sla_minutes` | `number \| null` | No | SLA target in minutes |
+| `target_per_hour` | `number \| null` | No | Throughput target (items per hour) |
+| `worker_count` | `number \| null` | No | Station capacity |
+
+**Returns:** `LTApiResult<RoleDetail>` — the updated role.
+
+**Auth:** Role manager (admin type, superadmin, or engineer)

package/docs/cli.md

@@ -63,6 +63,8 @@ Shows pending escalations, active workers, pipeline tools, and event transport.
 ltc esc list                              # All escalations
 ltc esc list --status pending             # Pending only
 ltc esc list --role reviewer --limit 10   # Filter by role
+ltc esc list --search wf-abc123           # Exact-match by escalation / workflow / origin id
+ltc esc find-by-meta orderId ORD-42       # Match a value inside metadata (any status)
 ltc esc get abc123                        # Detail view
 ltc esc claim abc123                      # Claim for yourself
 ltc esc claim abc123 --duration 60        # Claim for 60 minutes

package/docs/dashboard.md

@@ -28,6 +28,7 @@ The sidebar organizes pages into five groups.
 | Page | Route | Purpose |
 |------|-------|---------|
 | **Recent Activity** | `/` | Live event stream and business process overview. |
+| **Operations** | `/operations` | COO shop-floor view — pace chart of actual-vs-target flow across all ops-visible roles, station table with live metrics, and the station detail panel. Visible to any user with ops or builder access. |
 | **Capabilities** | `/capabilities` | Browse MCP servers grouped by capability category. |
 | **Agent Automations** | `/agents` | Autonomous event-driven automations. Configure subscriptions, schedules, and knowledge domains. |
 | **Topics** | `/topics` | Topic catalog — browse all known event topics with descriptions, schemas, and subscriber counts. |
@@ -197,12 +198,13 @@ User Accounts and Service Accounts live on the same page, separated by a tab tog
 
 Define roles and configure escalation chains that control how work flows between teams.
 
-- **Role list** — all roles in the system with their type (admin, operator, custom). Click to view assigned users.
+- **Role list** — all roles in the system. Each row shows the role key, title, description, user count, chain count, workflow count, and an OPS badge if `ops_visible` is set.
+- **Role detail** — click a role to open its detail panel: identity fields (title, description), escalation chains, and the capacity settings (`sla_minutes`, `target_per_hour`, `worker_count`). Edit these inline and save via `PATCH /api/roles/:role`.
 - **Create Role** — add a new role. Roles referenced in workflow configs are auto-created, but you can also create them here for organizational clarity.
 - **Scope picker** — when granting a role at `member` type, a Scope picker offers the five named work-surface 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`). `admin` and `superadmin` grants show no Scope picker — they always work the whole queue. The picker enforces **write ⊆ read**, so a write breadth wider than the read breadth cannot be selected.
 - **Escalation chains** — define source → target role mappings. When a reviewer escalates, the chain determines which roles receive the escalation next. Chains are directional (reviewer → engineer → admin) and support multiple targets per source.
 
-**API:** `GET /api/roles` lists roles. `POST /api/roles` creates. `GET /api/roles/escalation-chains` lists chains. `POST /api/roles/escalation-chains` adds a chain.
+**API:** `GET /api/roles` lists roles. `POST /api/roles` creates. `PATCH /api/roles/:role` updates metadata and capacity fields. `GET /api/roles/details` returns full `RoleDetail` shapes. `GET /api/roles/escalation-chains` lists chains. `POST /api/roles/escalation-chains` adds a chain.
 
 ### DB Maintenance
 
@@ -260,6 +262,19 @@ Accessible at `/escalations`. A statistics dashboard for escalation health acros
 - **Summary cards** — open (pending), claimed (in progress), created (new), and resolved counts for the selected window.
 - **Role breakdown table** — groups escalations by role so you can see which teams have the most pending work. Useful for identifying bottlenecks and rebalancing workload.
 
+### Operations
+
+Accessible at `/operations`. The COO shop-floor view — shows actual-vs-target flow across every ops-visible role as a pace chart, with a station table and detail panel below.
+
+- **Period selector** — `15m`, `1h`, `24h`, `7d`, `30d`. Controls the lookback window for resolved counts, percentile metrics, and the throughput metrics.
+- **Pace chart** — connects all ops-visible stations in process dependency order and plots absolute counts for the selected window: a straight red target polyline (`target_per_hour × window hours`) against a smooth actual (resolved) curve with a light area fill. Station circles are colored by pace ratio (green ≥ 100%, amber ≥ 60%, red below), with a three-number strip per station: pending, active, resolved.
+- **Station table** — one row per ops-visible role with PENDING, ACTIVE, RESOLVED, P99 WAIT, P99 WORK, and a PRESSURE mini-bar. Stations with in-arrears items show a sub-row with a link to oldest-first queue view.
+- **Station detail panel** — opens on row or circle click. Shows the role's identity, an independent period toggle, and full metric breakdown (wait/work percentiles, SLA target, worker count, links to queue).
+
+Roles appear on this view when `ops_visible = true` is set. The capacity settings (`sla_minutes`, `target_per_hour`, `worker_count`) drive the computed metrics. Set these via `PATCH /api/roles/:role` or the Roles admin page. See [Operations](operations.md) for the full concept doc.
+
+**API:** `GET /api/escalations/station-metrics?period=24h`
+
 ### Processes Overview
 
 Accessible at `/` (home page) and `/processes`. Shows all tracked business processes — each process is a group of related workflow executions sharing an origin ID.