@hotmeshio/long-tail 0.23.1 → 0.24.0

package/docs/api/mcp/index.md

@@ -21,13 +21,13 @@ These servers ship with the product and reflect the core API surface:
 
 | Server | Category | Tools | Description |
 |--------|----------|-------|-------------|
-| [long-tail-admin](admin.md) | System | 71 | Unified system management — tasks, escalations, agents, workflows, users, etc. |
-| [long-tail-human-queue](human-queue.md) | Automation | 5 | Escalation workflow primitives (durable pause + signal) |
+| [long-tail-admin](admin.md) | System | 119 | Unified system management — tasks, escalations, agents, workflows, users, etc. |
+| [long-tail-human-queue](human-queue.md) | Automation | 10 | Escalation workflow primitives (durable pause + signal) |
 | [long-tail-file-storage](file-storage.md) | Data | 4 | Managed file storage (MinIO/GCS/S3) |
 | [long-tail-http-fetch](http-fetch.md) | Data | 3 | HTTP client for external requests |
 | [long-tail-schema-exchange](schema-exchange.md) | Data | 2 | Schema-validated HTTP exchange with credential resolution |
 | [long-tail-oauth](oauth.md) | System | 3 | OAuth token management and refresh |
-| [long-tail-knowledge](knowledge.md) | Data | 7 | Persistent JSONB knowledge store |
+| [long-tail-knowledge](knowledge.md) | Data | 10 | Persistent JSONB knowledge store |
 | [long-tail-docs](docs.md) | Reference | 3 | Documentation search and retrieval |
 | [long-tail-events](events.md) | Communication | 4 | Event bus pub/sub |
 | [long-tail-vision](vision.md) | Analysis | 2 | Image analysis via LLM vision (AI key required) |
@@ -38,15 +38,18 @@ These servers ship with the product and reflect the core API surface:
 
 These servers are included as examples of how to extend Long Tail with additional MCP capabilities. They demonstrate the registration pattern for adding browser automation or other domain-specific tools:
 
-| Server | Category | Description |
-|--------|----------|-------------|
-| long-tail-playwright | Automation | Low-level browser automation via Playwright (requires binary) |
-| long-tail-playwright-cli | Automation | High-level browser automation |
-| long-tail-gmail | Communication | Gmail integration (OAuth) |
-| long-tail-image-tools | Media | Image processing via sharp |
+| Server | Category | Tools | Description |
+|--------|----------|-------|-------------|
+| long-tail-playwright | Automation | 9 | Low-level browser automation via Playwright (requires binary) |
+| long-tail-playwright-cli | Automation | 5 | High-level browser automation |
+| long-tail-gmail | Communication | 5 | Gmail integration (OAuth) |
+| long-tail-image-tools | Media | 12 | Image processing via sharp |
+| [long-tail-ortho](ortho.md) | Automation | 4 | Drives the `ortho-pipeline` example workflow: submit orders, complete stage escalations, track status |
 
 See `examples/mcp-servers/` for the registration pattern.
 
 ## Read-Safe Classification
 
-Every tool is classified as either **read-safe** (query-only, no side effects) or **write** (modifies state). When `mcp.exposure.readOnly` is enabled, only read-safe tools are available to external MCP consumers.
+Every tool is classified as either **read-safe** (query-only, no side effects) or **write** (modifies state). When `mcp.exposure.readOnly` is enabled, only read-safe tools are available to external MCP consumers. A caller whose key or OAuth grant is read-only sees the same read-safe subset.
+
+Each tool also declares a role gate (`caller`, `admin`, `builder`, `roleManager`, or `superadmin`), and a tool appears only to accounts that hold it. See the MCP guide's [Access](../../mcp.md#access-which-tools-and-which-records) section.

package/docs/api/mcp/knowledge.md

@@ -139,3 +139,37 @@ Append a value to an array field within a knowledge entry. Creates the entry and
 | key | string | Yes | Document key |
 | path | string | Yes | JSONB path to array field |
 | value | any | Yes | Value to append to the array |
+
+### set_knowledge_field
+
+Set a value at a dot-notation path within a knowledge entry, keeping sibling fields. Creates the entry when it does not exist.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | string | Yes | Knowledge domain |
+| key | string | Yes | Document key |
+| path | string | Yes | Dot-notation path to the field |
+| value | any | Yes | Value to set, any JSON type |
+| tags | string[] | No | Tags to union with existing tags |
+
+### remove_knowledge_field
+
+Remove a field from a knowledge entry by dot-path. The entry remains; only the targeted path is deleted.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | string | Yes | Knowledge domain |
+| key | string | Yes | Document key |
+| path | string | Yes | Dot-notation path to remove |

package/docs/api/mcp/oauth.md

@@ -21,7 +21,7 @@ Get a fresh OAuth access token for an external service. Automatically refreshes
 
 | | |
 |---|---|
-| Read-safe | Yes |
+| Read-safe | No |
 
 **Parameters:**
 

package/docs/api/mcp/ortho.md

@@ -0,0 +1,113 @@
+# Ortho (example server)
+
+Example connector for the `ortho-pipeline` example workflow (`examples/workflows/ortho-pipeline`). `system/index.ts` registers it when the `examples/` tree is available; the npm package excludes it.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-ortho` |
+| Category | Automation |
+| AI required | No |
+| Source | `examples/mcp-servers/ortho.ts` |
+| Tool manifest | `examples/seed/tool-manifests-ortho.ts` |
+
+## Overview
+
+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 `conditional` 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/mcp/vision.md

@@ -11,7 +11,7 @@ Image analysis and description using LLM vision. Analyzes images to extract stru
 
 ## Compile Hints
 
-Vision tools process one image at a time. The argument name is `image` (NOT `image_path`). It accepts a storage path, data URI, or https:// URL. Vision tools do NOT use browser sessions. Do NOT wire page_id or _handle to vision tools. analyze_image output fields: description (string), text_content (string), objects (array).
+Vision tools process one image at a time. The argument name is `image` (NOT `image_path`). It accepts a storage path, data URI, or https:// URL. Reading a storage path requires builder access, as the file browser does; a data URI or https:// URL needs none. Vision tools do NOT use browser sessions. Do NOT wire page_id or _handle to vision tools. analyze_image output fields: description (string), text_content (string), objects (array).
 
 ## Tools
 

package/docs/api/sdk/bot-accounts.md

@@ -237,6 +237,7 @@ const result = await lt.botAccounts.revokeKey({ keyId: 'key-id' });
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `keyId` | `string` | Yes | Unique identifier of the API key to revoke |
+| `botId` | `string` | No | When given, the key is revoked only if it belongs to this bot; otherwise `404` |
 
 **Returns:** `LTApiResult<{ revoked: true }>`
 

package/docs/api/sdk/escalations.md

@@ -220,7 +220,7 @@ const result = await lt.escalations.getLookups({ id: 'esc_123' });
 
 ## getByWorkflowId
 
-List all escalations for a given workflow ID.
+List the escalations for a given workflow ID. With `auth` as the second argument, only the escalations that caller may read; without it, every escalation.
 
 ```typescript
 const result = await lt.escalations.getByWorkflowId({ workflowId: 'wf_abc' });
@@ -234,7 +234,7 @@ const result = await lt.escalations.getByWorkflowId({ workflowId: 'wf_abc' });
 
 **Returns:** `LTApiResult<{ escalations }>`
 
-**Auth:** Not required
+**Auth:** Optional (filters to the caller's readable escalations when provided)
 
 ---
 
@@ -1224,3 +1224,19 @@ interface StationMetric {
 `pending` reflects the live queue depth regardless of period. `claimed`, `resolved`, and both percentile objects use the lookback window. `priority_count` covers pending, unclaimed items whose age exceeds the role's threshold — age from the `priority_facet` metadata timestamp (`created_at` when unset) against `priority_threshold_minutes` (`sla_minutes` when unset); stations with neither threshold 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.
+
+## getRelated / getRelatedRows
+
+Read the related sets a role's list schema declares (`x-lt-related`) for list rows, under the caller's read scope. Mirrors `POST /api/escalations/related` and `/related/rows`.
+
+```typescript
+const page = await client.escalations.getRelated({ role: 'consolidate', ids: rows.map((r) => r.id) });
+// page.data.sets.contents.aggregates['reciprocal.metadata.serviceLevel'][rowId]
+//   → { count: 3, splits: { standard: 2, express: 1 } }
+
+const orders = await client.escalations.getRelatedRows({ role: 'consolidate', id: rowId, set: 'contents' });
+// orders.data.rows → [{ item: { itemKey, at, reciprocalId }, escalation }]
+```
+
+`list` and `listAvailable` take `groupBy` (a metadata key) to page by groups of rows sharing it: the response adds `groups: [{ key, ids }]` and `total` counts groups.
+

package/docs/api/sdk/mcp.md

@@ -243,8 +243,8 @@ const result = await lt.mcp.callTool({
 | `id` | `string` | Yes | The MCP server identifier |
 | `toolName` | `string` | Yes | Name of the tool to invoke |
 | `arguments` | `Record<string, any>` | No | Key-value arguments to pass to the tool |
-| `execute_as` | `string` | No | User ID to impersonate for the tool call |
+| `execute_as` | `string` | No | Account id or `external_id` to run the tool as |
 
 **Returns:** `LTApiResult<{ result: any }>`
 
-**Auth:** Optional (userId forwarded to the MCP adapter when provided)
+**Auth:** Required (`401` without it). The tool runs as the caller, or as `execute_as` when given; for `execute_as`, a superadmin may act as anyone, and a caller holding an `admin`-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type. A built-in tool requires the capability its manifest `gate` declares, checked for the acting account; a built-in tool with no gate requires builder access (superadmin or the `engineer` role). Refusals return `403`.

package/docs/api/sdk/settings.md

@@ -20,7 +20,7 @@ const result = await lt.settings.get();
 | `escalation.claimDurations` | `number[]` | Available claim duration options (minutes) |
 | `events.transport` | `'socketio' \| 'nats' \| 'none'` | Dashboard event transport (default: `socketio`; `nats` when `EVENT_TRANSPORT=nats`) |
 | `events.natsWsUrl` | `string \| null` | NATS WebSocket URL (present when NATS adapter registered) |
-| `events.natsToken` | `string \| null` | NATS auth token (present when NATS adapter registered) |
+| `events.reconnect` | `{ initialDelayMs, maxDelayMs, noticeAfterMs, spreadMs }` | Dashboard reconnect timing in ms (`NATS_RECONNECT_INITIAL_MS` default `1000`, `NATS_RECONNECT_MAX_MS` default `60000`, `NATS_LIVE_NOTICE_AFTER_MS` default `30000`, `NATS_RECONNECT_SPREAD_MS` default `5000`) |
 | `auth.sso` | `boolean` | Whether SSO is configured for embedded deployments |
 | `auth.ssoLogoutUrl` | `string \| null` | Host logout URL (redirected to on dashboard sign out) |
 | `ai.enabled` | `boolean` | Whether an LLM API key is configured |

package/docs/api/sdk/tasks.md

@@ -122,7 +122,7 @@ const result = await lt.tasks.listProcesses({
 
 ## getProcess
 
-Get a single process with all its tasks and escalations.
+Get a single process with all its tasks and escalations. With `auth` as the second argument, only the escalations that caller may read.
 
 ```typescript
 const result = await lt.tasks.getProcess({ originId: 'origin_xyz' });
@@ -136,7 +136,7 @@ const result = await lt.tasks.getProcess({ originId: 'origin_xyz' });
 
 **Returns:** `LTApiResult<{ origin_id, tasks, escalations }>`
 
-**Auth:** Not required
+**Auth:** Optional (filters escalations to the caller's readable ones when provided)
 
 ---
 

package/docs/api/sdk/workflows.md

@@ -23,12 +23,12 @@ const result = await lt.workflows.invoke({
 | `type` | `string` | Yes | Workflow function name |
 | `data` | `Record<string, any>` | No | Envelope data payload |
 | `metadata` | `Record<string, any>` | No | Envelope metadata |
-| `execute_as` | `string` | No | Service account for proxy invocation |
+| `execute_as` | `string` | No | Account id or `external_id` to run as. Requires admin access and the act-as rule below. |
 | `options` | `Record<string, any>` | No | Passthrough to Durable WorkflowOptions |
 
 **Returns:** `LTApiResult<{ workflowId, message }>`  (status 202)
 
-**Auth:** Required
+**Auth:** Required. When `invocation_roles` is set, the caller must hold one of them; roles are read from the caller's current grants in the database. Empty `invocation_roles` admits any authenticated caller. A superadmin grant, or the `admin` role held with `admin` type, invokes any workflow. `capabilityInvoke` requires a superadmin grant. For `execute_as`, a superadmin may act as anyone, and a caller holding an `admin`-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type; otherwise `403`.
 
 ---
 

package/docs/api/sdk/yaml-workflows.md

@@ -258,7 +258,7 @@ const result = await lt.yamlWorkflows.invoke({
 
 **Returns:** `LTApiResult<any>`
 
-**Auth:** Optional (userId forwarded to invoke service when provided)
+**Auth:** Optional (userId forwarded to invoke service when provided). `execute_as` requires an authenticated caller and the act-as rule: a superadmin may act as anyone, and a caller holding an `admin`-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type. The server sets the workflow's `_scope` identity context; a `_scope` key in `data` is ignored.
 
 ---
 

package/docs/architecture.md

@@ -24,7 +24,7 @@ system/          Always ships. The built-in tool inventory.
 └── mcp-servers/   Built-in MCP servers wrapping the activities
 
 examples/        Opt-in demos. Seed with `examples: true`.
-├── workflows/     review-content, verify-document, process-claim, ...
+├── workflows/     review-content, kitchen-sink, ortho-pipeline, ...
 └── types/
 
 your-app/        Your workflows. Same conventions, your directory.
@@ -150,6 +150,8 @@ const servers = await findServersByTags(['database', 'analytics'], 'any');
 
 Tags are GIN-indexed in PostgreSQL for fast lookup. Register a new MCP server tagged `analytics` and mcpQuery automatically picks up its tools. Register one tagged `vision` and mcpTriage can use it for remediation. The tool inventory grows without code changes.
 
+The model sees and calls only the tools the workflow's principal may call. A tool the LLM chooses in mcpQuery or mcpTriage acts as that principal and passes the same manifest gate it carries at `/mcp`. A workflow with no principal, such as an internal job, runs its tools as `lt-system`.
+
 ### System Workflows
 
 | Pipeline | Workflows | Purpose |

package/docs/auth.md

@@ -75,7 +75,7 @@ Long Tail's embedded server automatically applies auth middleware to all API rou
 
 ### requireAdmin
 
-`requireAdmin` is a separate middleware that runs after authentication. It checks whether the authenticated user holds superadmin status, either through a database lookup (`isSuperAdmin()`) or by verifying that the JWT `role` claim equals `'admin'`. Requests that fail this check receive a `403 Forbidden` response.
+`requireAdmin` is a separate middleware that runs after authentication. It passes a request whose JWT `role` claim is `'admin'` or `'superadmin'`, or whose user is a superadmin in the database (`isSuperAdmin()`). Requests that fail this check receive a `403 Forbidden` response.
 
 ## Custom Adapter Example
 
@@ -258,7 +258,7 @@ A resolve that slides the session makes this endpoint a session-refresh surface
 
 ### requireAuth Fallback
 
-When SSO is configured and a request arrives without a Bearer token, `requireAuth` calls `sso.resolve(req)` as a fallback. This allows direct API calls from the host backend (which forward cookies but not Bearer tokens) to authenticate without an explicit exchange. The dashboard always uses Bearer after the initial exchange. The fallback never passes `res` — session sliding belongs exclusively to the exchange.
+When SSO is configured and a request arrives without a Bearer token, `requireAuth` calls `sso.resolve(req)` as a fallback. This allows direct API calls from the host backend (which forward cookies but not Bearer tokens) to authenticate without an explicit exchange. The dashboard always uses Bearer after the initial exchange. The fallback never passes `res` — session sliding belongs exclusively to the exchange. The fallback does not apply at `/mcp`: an MCP request authenticates only with the Bearer credential it carries (an OAuth access token, a service-account key, or a signed JWT). See [Connect with OAuth](mcp.md#connect-with-oauth).
 
 ### Role Mapping
 
@@ -311,5 +311,6 @@ When a service account starts a workflow, its `userId` flows through the same en
 | Variable     | Required | Description                                      |
 |--------------|----------|--------------------------------------------------|
 | `JWT_SECRET` | Yes      | Signing and verification key for the JWT adapter. |
+| `LT_OAUTH_ISSUER` | No | Public base URL for the OAuth authorization server that MCP clients sign in through. Equivalent to `auth.oauthServer.issuer` in `start()`. See [Connect with OAuth](mcp.md#connect-with-oauth). |
 
 `JWT_SECRET` must be set when using `JwtAuthAdapter` or `signToken`. Omitting it will cause token verification to fail at runtime. Use a cryptographically random string of at least 32 characters in production.

package/docs/cloud.md

@@ -39,14 +39,14 @@ The worker container registers the LT interceptor, starts workflow workers, and
 // worker.ts — Worker container entry point
 import { start } from '@hotmeshio/long-tail';
 import * as reviewContent from './workflows/review-content';
-import * as verifyDocument from './workflows/verify-document';
+import * as kitchenSink from './workflows/kitchen-sink';
 
 await start({
   database: { connectionString: process.env.DATABASE_URL },
   server: { enabled: false },
   workers: [
     { taskQueue: 'long-tail', workflow: reviewContent.reviewContent },
-    { taskQueue: 'long-tail-verify', workflow: verifyDocument.verifyDocument },
+    { taskQueue: 'long-tail-examples', workflow: kitchenSink.kitchenSink },
   ],
   telemetry: process.env.HONEYCOMB_API_KEY
     ? { honeycomb: { apiKey: process.env.HONEYCOMB_API_KEY } }
@@ -217,6 +217,11 @@ The API Deployment sits behind a Service + Ingress. The worker Deployment has no
 | `HONEYCOMB_API_KEY` | — | yes | Honeycomb telemetry (optional) |
 | `HMSH_TELEMETRY` | — | yes | Span verbosity: `info` or `debug` |
 | `NATS_URL` | — | yes | NATS server for milestone events (optional) |
+| `NATS_WS_TICKET_TTL_SECONDS` | yes | — | Lifetime of the dashboard's WebSocket proxy ticket (default: 300) |
+| `NATS_RECONNECT_INITIAL_MS` | yes | — | Dashboard reconnect: first backoff delay (default: 1000) |
+| `NATS_RECONNECT_MAX_MS` | yes | — | Dashboard reconnect: backoff cap (default: 60000) |
+| `NATS_LIVE_NOTICE_AFTER_MS` | yes | — | How long live updates stay down before the dashboard shows a notice (default: 30000) |
+| `NATS_RECONNECT_SPREAD_MS` | yes | — | Window the first retry after a drop and the catch-up refetch spread across (default: 5000) |
 | `OPENAI_API_KEY` | — | yes | For workflows that call OpenAI (optional) |
 
 Environment variables serve as fallbacks. When using `start()`, prefer passing config directly — it's explicit and type-checked. The API container does not need telemetry, event, or AI keys — it never executes workflow code. The worker container does not need `JWT_SECRET` or `PORT` — it never serves HTTP.

package/docs/code-owned-configuration.md

@@ -157,3 +157,15 @@ dedicated advisory lock, separate from the migration lock. Single-statement
 applies are also individually race-safe: every upsert carries an
 `IS DISTINCT FROM` guard, so an identical declaration arriving from two
 containers writes once and no-ops once.
+
+## Display time zone
+
+`display.timeZone` (an IANA name) renders every dashboard date in that zone, so a floor reads its own time on every screen: list columns, station facts, and detail pages alike. Unset, dates render in the viewer's browser zone. An unknown zone fails the boot.
+
+```typescript
+await start({
+  // …
+  display: { timeZone: 'America/Chicago' },
+});
+```
+

package/docs/dashboard.md

@@ -86,7 +86,7 @@ The top navigation bar contains:
 - **scan** (Barcode icon) — opens the scan panel for manual code entry and capture settings, shown when `features.scanCodes` stands. See [Scan Codes](#scan-codes).
 - **events** — toggles the live event feed (builders and ops; doubles as the connection indicator).
 - **docs** (BookOpen icon) — toggles the in-app documentation drawer. Each page also has a contextual docs link next to its title that opens the drawer to the relevant section.
-- **User menu** — **Credentials** (OAuth connections and API keys), **Link variables** (per-device facet bindings that scope pins and the Pace Board — see [Faceted Routing](faceted-routing.md#link-variables)), the **theme picker** (five accent themes), and **Sign Out**.
+- **User menu** — **Credentials** (OAuth connections and API keys), **Connected apps** (MCP clients connected with OAuth, when the OAuth server is enabled), **Link variables** (per-device facet bindings that scope pins and the Pace Board — see [Faceted Routing](faceted-routing.md#link-variables)), the **theme picker** (five accent themes), and **Sign Out**.
 
 ## Home — Recent Activity
 
@@ -137,7 +137,7 @@ Accessible at `/workflows/durable/invoke` to anyone the server lists an invokabl
 Every invokable workflow is presented as a tool. The list of tools takes the left quarter of the row, grouped by task queue, with the prompt **Choose a tool to begin** until one is selected. Names read as titles (`fleetTools` shows as **Fleet Tools**, queues the same way) and each row leads with the workflow's icon, or its tier glyph when none is declared. The first row is preselected, `?type=<WorkflowType>` tracks the choice, and every choice is a history entry, so the page opens on a form and the back button retraces picks. The form fills the rest of the row, its heading and Submit staying put while the body scrolls:
 
 - **Heading and description** — the icon and title, with the identifier, tier, and queue as metadata, then the config's one-line description. Keep reference material in `x-lt-help`; it appears in the side panel on demand.
-- **Identity summary** — who will execute: the current user, the workflow's configured `execute_as` bot ("configured default"), or, for admins and superadmins, an override chosen from the bot picker ("admin override").
+- **Identity summary** — who will execute: the current user, the workflow's configured `execute_as` bot ("configured default"), or, for admins and superadmins, an override chosen from the bot picker ("admin override"). The server accepts an override only within the caller's own authority (see [IAM](iam.md#when-to-use-a-service-account)).
 - **Certification checkbox** — for a certified workflow, stamps `metadata.certified` on this one run.
 - **The form** — a workflow that declares `inputSchema` renders the x-lt-* form: sections, two columns, conditional fields and instruction blocks, selects with inline or lookup-backed labeled options, Yes/No decisions over booleans, multi-select lists, validated JSON maps, and a side panel with **Instructions** (the interpolated `x-lt-help`) and **Issues** (violations, click to focus). The `fleetTools` example exercises every shape. Every other workflow renders the envelope template form from `envelopeSchema`, with its Form and JSON views. See [Invoke forms](hitl/invoke-form.md).
 - **Submit** — posts `{ data, metadata }` to the invoke endpoint. The page stays put, reports the started id, and subscribes to that run's `system.workflow.{id}.completed` and `.failed` events, so the outcome and the workflow's returned `data` appear beside Submit without leaving the page. One click disarms the button until the person chooses **Submit again**. While live events are off, a warning beside the button offers a reconnect, since the result could not arrive otherwise. Builders also get a **View workflow** link to its execution. A `422` from the input schema gate lands in the Issues view.
@@ -176,7 +176,7 @@ Browse all registered MCP servers and their exposed tools.
 - **Register Server** button — opens a guided wizard: choose transport, configure connection, discover tools, review and save.
 - **Server detail** — click any row to view and edit. Shows all exposed tools with their input schemas, tags, compile hints, and credential providers. Tools are the building blocks that the MCP Tool Designer compiles into deterministic pipelines.
 
-**API:** `GET /api/mcp-servers` lists servers. `POST /api/mcp-servers` registers a new one. `GET /api/mcp-servers/:id/tools` lists tools for a server.
+**API:** `GET /api/mcp/servers` lists servers. `POST /api/mcp/servers` registers a new one. `GET /api/mcp/servers/:id/tools` lists tools for a server. Registering, editing, connecting and deleting servers require builder access; reads are open to any account, and `transport_config` is returned to builders only.
 
 ### Graph Workflows
 
@@ -196,7 +196,7 @@ The Graph → Configure page. Deterministic workflows compiled from dynamic MCP
 
 **Empty state:** When no tools have been compiled yet, a Wand2 icon prompts users to visit the MCP Tool Designer to create their first deterministic tool.
 
-**API:** `GET /api/yaml-workflows` lists pipeline tools. `POST /api/yaml-workflows/:id/deploy` deploys. `POST /api/yaml-workflows/:id/activate` activates. `POST /api/yaml-workflows/:id/invoke` invokes.
+**API:** `GET /api/yaml-workflows` lists pipeline tools. `POST /api/yaml-workflows/:id/deploy` deploys. `POST /api/yaml-workflows/:id/activate` activates. `POST /api/yaml-workflows/:id/invoke` invokes. Creating, editing, deploying, activating, archiving and scheduling require builder access; listing, reading and invoking are open to any account.
 
 ### Graph Executions
 
@@ -221,7 +221,7 @@ Accessible at `/workflows/executions`. Lists procedural workflow runs from one H
   - **Escalations** (panel) — every escalation the workflow raised as a row (status dot, type, role, age), each linking to its detail page; related child tasks list below. Empty reads "This workflow has not escalated."
   - **Actions** menu — Restart (prefills a fresh invoke from the start event), Terminate (running runs only), Compile into Pipeline (runs with tool calls), and jumps to worker / engine stream messages.
 
-**API:** `GET /api/workflow-states/jobs?namespace=durable` lists runs (params `entity` for type, `status`, `search`, `registered` for tier, `sort_by`, `order`, `limit`, `offset`). `GET /api/workflow-states/:workflowId/execution` returns the detail. `POST /api/workflows/:workflowId/terminate` stops a running one.
+**API:** `GET /api/workflow-states/jobs?namespace=durable` lists runs (params `entity` for type, `status`, `search`, `registered` for tier, `sort_by`, `order`, `limit`, `offset`). `GET /api/workflow-states/:workflowId/execution` returns the detail. `POST /api/workflows/:workflowId/terminate` stops a running one. The list and terminate require builder access (superadmin or the `engineer` role); the detail is open to builders and to the person who started the run or the account it runs as.
 
 ### Accounts
 
@@ -326,7 +326,7 @@ A code encodes **`version:category:target`** (e.g. `10:1:SN-12345`):
 
 **Rules are ECA over escalations.** A rule is an ordered list of event-condition-action steps, first match wins: the event is the scanned code, the condition is a query against the escalation (role, status, availability, metadata facets), and the action is a canonical verb (`show-detail`, `show-list`, `claim`, `claim-show-detail`, `release`, `resolve`, `escalate`, `cancel`, `present`). Mutations ride single-statement by-metadata operations under the caller's own role scope, and stamp provenance facets (`scanScheme`, `scanCategory`, `scanActionName`, `scannedAt`) on every transition. Ordering is the design: put the expected state first and a broad fallback last, since a scan is also a state query.
 
-**Admin config** lives at `/admin/scan-codes` (scheme list) and `/admin/scan-codes/:version` (a scheme with its rules) — builder-gated (admin, engineer, superadmin). A scheme carries a name, its target facet, encoding, and — for identity schemes — a grant policy.
+**Admin config** lives at `/admin/scan-codes` (scheme list) and `/admin/scan-codes/:version` (a scheme with its rules) — role-manager gated (admin, engineer, superadmin). A scheme carries a name, its target facet, encoding, and — for identity schemes — a grant policy.
 
 **Station surface.** `/scan/station` is a full-screen scan surface with an idle prompt, an info/choice screen (the current reality plus labeled choices when a rule presents options), and a badge prompt when identity is required. In **kiosk mode** — a login holding exactly one role whose `properties.kiosk` is set — the chrome falls away and only the role's list, escalation detail, and this scan screen are reachable. The header **scan** panel offers the same manual entry and capture settings on any page.
 
@@ -485,7 +485,7 @@ This is the primary view for understanding how a multi-step workflow progresses
 
 ### Files
 
-Accessible at `/files`. Browse and manage files in the connected storage backend (MinIO locally, S3/GCS in production).
+Accessible at `/files` (builder-only: superadmin or the `engineer` role). Browse and manage files in the connected storage backend (MinIO locally, S3/GCS in production).
 
 - **File browser** — navigate directories with breadcrumbs; the list shows name, size, and last-modified. Paginated via a continuation token.
 - **Preview panel** — click a file to preview it in the side panel: images inline, text and code inline, JSON, and a PDF open-in-tab. Everything else downloads.
@@ -534,6 +534,14 @@ Accessible via the user menu (or at `/credentials`). Manage OAuth provider conne
 
 Credentials flow through the system via the `_scope` identity context — workflows inherit the invoking user's credentials for authenticated tool calls.
 
+### Connected apps
+
+Accessible via the user menu (or at `/connected-apps`) when the OAuth server is enabled. Lists the MCP clients you connected with OAuth, the access each holds (Read-only or As me), when you connected it and when it last refreshed. **Disconnect** ends a client's access at once.
+
+### Consent
+
+`/oauth/consent` is where an MCP client's sign-in lands. It shows the app, your account, where the browser returns and the deployment, then offers **Allow read-only**, **Allow as me** (when it grants more than read-only) and **Deny**. Signed-out visitors sign in first and return to it. See [Connect with OAuth](mcp.md#connect-with-oauth).
+
 ## Realtime Refresh Strategy
 
 The dashboard is push-driven: broker events (Socket.IO or NATS) invalidate React Query keys and the mounted queries refetch — never polling. Every event-driven refetch flows through one shared scheduler (`dashboard/src/lib/realtime-refresh.ts`), which bounds the rate a surface can hit the API however heavy the event stream runs:
@@ -549,6 +557,7 @@ The dashboard is push-driven: broker events (Socket.IO or NATS) invalidate React
 - **One scheduler per client**: identical query keys requested by several hooks in a window invalidate once, and a key wanted by two tiers flushes on the snappier lane.
 - **Hidden tabs cost nothing**: a background tab's flushes mark queries stale without any network (`refetchType: 'none'`); one catch-up refetch runs when the tab becomes visible.
 - **Mutations stay immediate**: a user's own action (claim, resolve, bulk ops) invalidates directly in its `onSuccess` — the tiers govern only event-driven refresh.
+- **Reconnect catches up**: after a NATS drop the dashboard reconnects with a fresh ticket and jittered backoff, reopens its subscriptions and refetches the open pages. A drop that outlasts `NATS_LIVE_NOTICE_AFTER_MS` shows a "Live updates unavailable" notice in the announcement banner row. See [Events](events.md#dashboard-transport-selection).
 
 Every timing constant — the three tiers and the shared `SEARCH_DEBOUNCE_MS` input debounce — lives in `dashboard/src/lib/realtime-refresh.ts`. Tune there; nothing else in the event path carries a number.
 

package/docs/data.md

@@ -297,7 +297,7 @@ Unique constraint: `(workflow_type, role)`.
 
 ### lt_config_invocation_roles
 
-Roles allowed to invoke a workflow via the API. When a workflow has `invocable: true` and this table has entries for it, only users holding one of these roles (or superadmins) can invoke.
+Roles allowed to invoke a workflow via the API. When a workflow has `invocable: true` and this table has entries for it, only users holding one of these roles, superadmins, and holders of the `admin` role at admin type can invoke. With no entries, any authenticated user can invoke.
 
 | Column | Type | Default | Description |
 |--------|------|---------|-------------|

package/docs/escalation-strategies.md

@@ -234,30 +234,19 @@ import { escalationStrategyRegistry, McpEscalationStrategy } from '@hotmeshio/lo
 escalationStrategyRegistry.register(new McpEscalationStrategy());
 ```
 
-When the MCP strategy is configured, ensure the triage worker is registered:
-
-```typescript
-import * as mcpTriageWorkflow from '@hotmeshio/long-tail/workflows/mcp-triage';
-
-await start({
-  database: { ... },
-  workers: [
-    // ... your workflows
-    { taskQueue: 'lt-mcp-triage', workflow: mcpTriageWorkflow.mcpTriage },
-  ],
-  escalation: { strategy: 'mcp' },
-});
-```
+The triage workflows (`mcpTriageRouter`, `mcpTriageDeterministic`, `mcpTriage`) register as system workers on the `long-tail-system` task queue when `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` is set.
 
 ## Testing
 
-The MCP triage test demonstrates the full flow without requiring an OpenAI API key. It uses mock activities with deterministic extraction:
+The triage integration test runs the full lifecycle against the docker compose stack: it finds the seeded "wrong language" escalation, walks the reviewer, admin, and engineer chain, resolves with `needsTriage`, waits for the triage workflow, and verifies the remediated process and the engineering recommendation. It requires `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` and skips without one.
 
 ```bash
-# Run the triage test
-npx vitest run tests/workflows/mcp-triage.test.ts --reporter=verbose
+docker compose up -d --build
+npx vitest run --config tests/integration/vitest.config.ts tests/integration/mcpTriage.test.ts
 ```
 
-The test covers:
-1. **Full triage flow** — extraction fails, human flags `needsTriage`, triage workflow rotates pages, re-invoked workflow succeeds, signals back to parent
-2. **Standard fallback** — resolver doesn't set `needsTriage`, standard re-run proceeds as normal
+The same chain runs through the dashboard UI in `tests/functional/mcpTriage.test.ts`:
+
+```bash
+npx playwright test --config tests/functional/playwright.config.ts mcpTriage
+```

package/docs/events.md

@@ -45,6 +45,12 @@ services:
       - NATS_TOKEN=your-token
 ```
 
+**Browser access.** The dashboard only subscribes. With the WebSocket proxy (`wsProxy`, so browsers reach NATS through Long Tail at `<basePath>/nats-ws`), `GET /api/nats-credentials` returns a WebSocket URL carrying a short-lived ticket for the signed-in person (`NATS_WS_TICKET_TTL_SECONDS`, default 300) and no NATS credential. The proxy admits only a ticket holder, writes the server's `NATS_TOKEN` into the connection itself, and drops anything the browser tries to publish. When browsers connect to NATS directly, set `NATS_DASHBOARD_TOKEN` to a subscribe-only NATS credential and the route hands that out instead of `NATS_TOKEN`.
+
+**What a browser receives.** Builders (superadmin, or the `engineer` role) receive events whole. Everyone else receives the browser view: escalation events keep their routing fields (`id`, `type`, `subtype`, `status`, `priority`, `role`, `assigned_to`, `assigned_until`, `workflow_id`, `workflow_type`, `origin_id`, `task_id`, `parent_id`, `resolved_at`, `claimed_at`, and the bulk and reassignment fields), and every other event arrives without `data` and `milestones`. Records are read through the scoped API by id, so pages refresh as before; the invoke page reads its own run's result from `GET /api/workflows/:id/result`. The WebSocket proxy applies the view per connection from the ticket's person, and the Socket.IO adapter per socket from the person its authenticator returns (`{ userId }`; an authenticator that returns `true` admits the socket with the browser view). Server-side consumers, such as agent triggers and callbacks, receive events whole.
+
+**Reconnecting.** The dashboard fetches a fresh ticket from `GET /api/nats-credentials` for every connection attempt, through the same client as every API call, so an expired session is refreshed first. After a drop the first retry lands at a random point within `NATS_RECONNECT_SPREAD_MS` (default 5000), so tabs that dropped together after a deploy return gradually; later retries back off with jitter from `NATS_RECONNECT_INITIAL_MS` (default 1000) up to `NATS_RECONNECT_MAX_MS` (default 60000), one attempt at a time. It waits while the tab is hidden, and stops only when the person is signed out; a new sign-in starts it again. On reconnect it reopens every active subscription and refetches the open pages once, spread across the same window. When live updates stay down longer than `NATS_LIVE_NOTICE_AFTER_MS` (default 30000), a "Live updates unavailable" notice appears in the announcement banner row. `GET /api/settings` carries these values as `events.reconnect` (`initialDelayMs`, `maxDelayMs`, `noticeAfterMs`, `spreadMs`).
+
 Both adapters still publish events regardless of `EVENT_TRANSPORT` — the setting only controls what the dashboard listens on. This means server-side event consumers (callbacks, NATS subscribers) work independently of the dashboard transport.
 
 ## The event envelope

package/docs/hitl/portal.md

@@ -82,6 +82,8 @@ A portal page fills the content area with one grid row per declared row, each di
 
 **Fitting a screen.** A panel on a wall screen is read, not scrolled, so a pin can ask the table to spend its width tightly: `?view=table&layout=compact` keeps the table a table however narrow the panel, tightens every cell, and holds the non-identity columns (assignee, role, priority) back until the panel is wide enough, so a narrow cell reads as a tight list of item and age and twenty rows fit where the folded layout showed four. `layout=cards` asks for the folded console-card layout on purpose. Without `layout`, the table folds on its own below the card threshold. The hint rides the URL like `view`, so it works on the full list page too, and it is the seam for a compact timeline later: a series of tight offset lines that fit the whole story in the panel.
 
+A rich panel carries the role's whole list schema, so related columns, row expansion, and grouped rows (see [Related sets](x-lt-list-schema.md#related-sets)) read on a wall screen as they do on the list page.
+
 A portal page shows without the left nav, as kiosk does: it is a screen read from across a room, and the panels are the page. The header stays, so the user menu still switches portals. Any signed-in user may open a portal. Panels read through the same role-scoped endpoints as the list page, so RBAC is unchanged: each viewer sees exactly what their read scope returns, and a queue outside it renders empty. Link variables resolve per device at render time, exactly as pins in the nav do. One event subscription per queue named by the cells keeps every panel current, on the LIST refresh tier.
 
 ## Choosing a portal