@hotmeshio/long-tail 0.5.12 → 0.6.2

package/docs/api/http/escalations.md

@@ -16,6 +16,16 @@ Claiming is implicit: `assigned_to` is set and `assigned_until` is set to a futu
 
 `cancelled` is a terminal state. A cancelled escalation cannot be claimed, resolved, or re-cancelled. When a workflow is terminated (`POST /api/workflows/:workflowId/terminate`), HotMesh automatically cancels any pending escalations tied to that workflow. Escalations can also be cancelled directly via `POST /api/escalations/:id/cancel`.
 
+## Work-Surface Scope
+
+A role is a task queue with four verbs — **search** (list/get), **claim**, **ack** (resolve), **delete** (cancel). A `member`'s grant carries `read_scope` (`self` | `all`) and `write_scope` (`none` | `self` | `all`) that set the breadth of those verbs on a given role's escalations. `admin` and `superadmin` ignore scope and act on the whole queue.
+
+- `read_scope` governs which escalations a member **sees** — list, `/available`, get-by-id, find-by-metadata, and stats. `self` means escalations assigned to the member (`assigned_to = user`); `all` means the whole role queue.
+- `write_scope` governs which escalations a member may **act on** — claim, resolve, cancel. `self` means only items already assigned to them; `none` is read-only.
+- Releasing and escalating are queue-management verbs and require `write_scope=all`. Creating a standalone escalation (`POST /api/escalations`) requires `write_scope=all` or global escalation access.
+
+Defaults are `read_scope=all` and `write_scope=all` — the full-queue worker — so a plain `member` works the whole queue. See [Work-Surface Scope](roles.md#work-surface-scope) in the Roles API for the five member profiles and the **write ⊆ read** constraint.
+
 ## List escalations
 
 ```
@@ -31,9 +41,34 @@ GET /api/escalations
 | `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) |
+| `sort_by` / `order` | `string` | Single-column sort + direction (`asc`/`desc`) |
 | `limit` | `integer` | Max results (default: 50) |
 | `offset` | `integer` | Pagination offset (default: 0) |
 
+**Faceted query parameters** (JSON-encoded — a "facet" is a key/value *inside* the row's
+`metadata` JSONB; the filter and count run in SQL, role-scoped):
+
+| Parameter | JSON shape | Description |
+|-----------|-----------|-------------|
+| `facets` | object | Required facets — `metadata @> facets`. `{"flags":"too_short"}` ≡ `metadata.flags == "too_short"` for a top-level scalar (containment for nested/arrays) |
+| `block` | array of objects | Exclude rows containing ANY set — `NOT (metadata @> ANY(block))` |
+| `range` | array of `{facet, op, value}` | Numeric range, op ∈ `< <= > >= =`, e.g. `[{"facet":"confidence","op":"<=","value":0.7}]` |
+| `exists` | array of strings | Keys that must be present — `metadata ? key` |
+| `roles` | array of strings | Restrict to these roles (narrows within scope, never widens) |
+| `available` | `true`/`false` | `true` = unclaimed/expired only; `false` = held now |
+| `orderBy` | array of `{field, direction?, numeric?}` | Sort by column or `metadata.<key>` |
+
+When any faceted parameter is present the request runs through the scoped faceted query.
+Example (URL-encode the JSON values):
+
+```
+GET /api/escalations?status=pending&facets={"flags":"too_short"}&range=[{"facet":"confidence","op":"<=","value":0.7}]
+```
+
+See [Faceted Routing — the human / operations query](../../faceted-routing.md#the-human--operations-query).
+
 **Response 200:**
 
 ```json
@@ -108,6 +143,8 @@ GET /api/escalations/:id
 |-----------|-------------|
 | `id` | Escalation UUID |
 
+**Scope:** Enforces read scope. A `member` with `read_scope=self` sees only escalations assigned to them; an item outside their read surface returns 404.
+
 **Response 200:** A single escalation object.
 
 **Response 404:**
@@ -126,6 +163,8 @@ Locks the escalation so no other reviewer can pick it up. The lock is time-boxed
 
 The `userId` is read from the auth token (`req.auth.userId`), not from the request body.
 
+**Scope:** Governed by write scope. A `member` with `write_scope=self` may claim only items already assigned to them; `write_scope=none` cannot claim.
+
 **Request body:**
 
 | Field | Type | Default | Description |
@@ -156,11 +195,14 @@ POST /api/escalations/:id/resolve
 
 Resolving an escalation starts a new workflow execution with the resolver's payload injected into `envelope.resolver`. The workflow re-runs, hits the `if (envelope.resolver)` branch, and completes with the human's decision as the final result.
 
+**Scope:** Governed by write scope (resolve is the **ack** verb). A `member` with `write_scope=self` may resolve only items assigned to them; `write_scope=none` cannot resolve.
+
 **Request body:**
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `resolverPayload` | `object` | yes | The reviewer's decision — injected into `envelope.resolver` |
+| `metadata` | `object` | no | Outcome facets merged into the escalation's GIN-indexed metadata. Records *what happened* (disposition, timing) next to *what was asked*; `@>`-queryable. Distinct from `resolverPayload`, which resumes the workflow and is not indexed |
 
 **Example request:**
 
@@ -169,6 +211,11 @@ Resolving an escalation starts a new workflow execution with the resolver's payl
   "resolverPayload": {
     "approved": true,
     "notes": "Content is fine, AI was overly cautious"
+  },
+  "metadata": {
+    "outcome": "approved",
+    "reviewedBy": "alice",
+    "durationMs": 1240
   }
 }
 ```
@@ -239,6 +286,7 @@ For callers that know the deterministic signal id (webhooks — e.g. `signal-sca
 |-------|------|----------|-------------|
 | `signalKey` | `string` | yes | The signal id passed to `conditionLT(signalId, config)` |
 | `resolverPayload` | `object` | yes | The decision payload delivered to the waiting workflow |
+| `metadata` | `object` | no | Outcome facets merged into the row's GIN-indexed metadata (see [Resolve an escalation](#resolve-an-escalation)) |
 
 Returns `404` when the key is unknown, `409` when the escalation is already terminal, and `200 { signaled: true }` on success. RBAC-scoped to the caller's visible roles.
 
@@ -377,7 +425,7 @@ Returns distinct escalation type values across all escalations.
 GET /api/escalations/stats
 ```
 
-Aggregated escalation statistics. RBAC-scoped: superadmins see all; others see only their roles.
+Aggregated escalation statistics. RBAC-scoped: superadmins see all; others see only their roles. The aggregate reflects `read_all` memberships only — a member's `read_scope=self` items are not aggregated here, since self-scope members get the single-item surface rather than a queue dashboard.
 
 **Query parameters:**
 
@@ -573,7 +621,7 @@ Resolve multiple escalations and start AI triage workflows (mcpTriage) for each.
 PATCH /api/escalations/:id/escalate
 ```
 
-Reassign a single escalation to a different role. The caller must be authorized to escalate from the current role to the target role (checked via escalation chains).
+Reassign a single escalation to a different role. The caller must be authorized to escalate from the current role to the target role (checked via escalation chains). Escalating is a queue-management verb and requires `write_scope=all` for a `member`.
 
 **Path parameters:**
 
@@ -723,7 +771,7 @@ Cancel multiple escalations at once. Skips any that are already terminal.
 POST /api/escalations/:id/release
 ```
 
-Release a claimed escalation back to the available pool. Only the user who holds the current claim can release it.
+Release a claimed escalation back to the available pool. Only the user who holds the current claim can release it. Releasing is a queue-management verb and requires `write_scope=all` for a `member`.
 
 **Path parameters:**
 
@@ -790,6 +838,8 @@ All three endpoints accept an optional `assignee` field — an `external_id` fro
 GET /api/escalations/by-metadata?key=orderId&value=order-123
 ```
 
+Scoped to the caller's read access. A `member` with `read_scope=self` matches only escalations assigned to them.
+
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `key` | `string` | **Required.** Metadata field name |
@@ -815,6 +865,8 @@ POST /api/escalations/claim-by-metadata
 
 Finds one available (pending + unassigned/expired) escalation matching the metadata and claims it atomically.
 
+**Scope:** For non-global callers this is scoped to `write_scope=all` roles. Self-scope members are excluded here — their items are pre-claimed and resolved by id, not discovered through the queue.
+
 **Body:**
 
 ```json
@@ -835,22 +887,22 @@ Finds one available (pending + unassigned/expired) escalation matching the metad
 | `metadata` | `object` | Additional metadata to merge (new keys added, existing overwritten) |
 | `provisionIfAbsent` | `object` | JIT-provision the assignee if they don't exist (superadmin only) |
 
-**`provisionIfAbsent`** — when the `assignee` doesn't exist in `lt_users` or lacks the escalation's role, provision them inline:
+**`provisionIfAbsent`** — when the `assignee` doesn't exist in `lt_users` or lacks the escalation's role, provision them inline. Each role entry accepts optional `read_scope` and `write_scope`, so a global caller can JIT-provision a one-time user with `read_scope=self` + `write_scope=self` and pre-claim their item in the same call:
 
 ```json
 {
   "key": "orderId",
   "value": "order-123",
-  "assignee": "jane.doe",
+  "assignee": "new-user",
   "provisionIfAbsent": {
-    "displayName": "Jane Doe",
-    "email": "jane@example.com",
-    "roles": [{ "role": "station-operator", "type": "member" }]
+    "displayName": "New User",
+    "email": "new-user@example.com",
+    "roles": [{ "role": "operator", "type": "member", "read_scope": "self", "write_scope": "self" }]
   }
 }
 ```
 
-Only callers with global escalation access (superadmin, admin/admin) can use this flag. The user is created with the declared roles if absent. If the user exists but lacks a required role, the role is added. The happy path (user exists, has role) adds zero extra queries.
+Only callers with global escalation access (superadmin, admin/admin) can use this flag. The user is created with the declared roles if absent. If the user exists but lacks a required role, the role is added. The happy path (user exists, has role) adds zero extra queries. A user provisioned at `read_self` + `write_self` sees and acts on exactly the one item the workflow routed to them.
 
 **Response 200:**
 
@@ -869,7 +921,7 @@ Only callers with global escalation access (superadmin, admin/admin) can use thi
 POST /api/escalations/resolve-by-metadata
 ```
 
-Single atomic query finds the pending escalation by metadata, auto-claims if unclaimed, and resolves it. RBAC is enforced in the SQL WHERE clause.
+Single atomic query finds the pending escalation by metadata, auto-claims if unclaimed, and resolves it. RBAC is enforced in the SQL WHERE clause. Write scope is honored here: a `member` with `write_scope=self` may resolve their own assigned item atomically, which is how a one-time user completes the form routed to them.
 
 **Signal guard:** If the escalation has `metadata.signal_id` (created by `conditionLT`), the SQL does NOT resolve it directly. Instead, the endpoint signals the running workflow — `conditionLT` receives the signal and resolves the escalation durably inside the workflow. This preserves the same transactional integrity as the standard resolve-by-ID path.
 
@@ -909,3 +961,72 @@ Single atomic query finds the pending escalation by metadata, auto-claims if unc
   "workflowId": "..."
 }
 ```
+
+## Resolve a set of escalations
+
+```
+POST /api/escalations/resolve-by-ids
+```
+
+Resolve many escalations in one guarded statement — the set-based sibling of `POST /:id/resolve`. Used for bookkeeping rows that are woken collectively (it does not deliver a per-row signal). RBAC: a scoped caller may only resolve rows whose role they hold (global principals are unrestricted).
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | yes | Escalation ids to resolve as one set |
+| `resolverPayload` | `object` | yes | Payload applied to every row |
+| `metadata` | `object` | no | Outcome patch merged into each row's GIN-indexed metadata |
+
+**Response 200:** `{ "resolved": <count>, "escalationIds": [...] }` — only the rows that were still `pending` are resolved and returned.
+
+## Faceted search
+
+```
+POST /api/escalations/search-by-facets
+```
+
+Item-level faceted search over a single pond `role`, scoped to the caller's role. The body is a faceted query.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | yes | Pond role to search |
+| `status` | `string` | no | e.g. `pending` |
+| `available` | `boolean` | no | Only rows not currently claimed |
+| `facets` | `object` | no | Metadata facet equality filters |
+| `orderBy` | `{ column, direction }[]` | no | Sort order |
+| `limit` / `offset` | `integer` | no | Paging |
+
+**Response 200:** `{ "escalations": [...], "total": <n> }`.
+
+## Claim groups
+
+```
+POST /api/escalations/claim-groups
+```
+
+Batch-claim complete origin groups (e.g. all units of an order) in priority order over a pond, assigned to the caller. RBAC-scoped to the pond role.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `query` | FacetQuery | yes | The pond/facet selector (see search-by-facets) |
+| `limit` | `integer` | no | Max groups to claim |
+| `durationMinutes` | `integer` | no | Claim TTL |
+| `sizeFacet` | `string` | no | Metadata key holding the group size |
+
+**Response 200:** `{ "groups": [...] }`.
+
+## Claim by facets
+
+```
+POST /api/escalations/claim-by-facets
+```
+
+Batch-claim individual rows matching a facet query (`FOR UPDATE SKIP LOCKED`), assigned to the caller. With `allOrNone`, commits only when the full `limit` is acquired. RBAC-scoped to the pond role.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `query` | FacetQuery | yes | The pond/facet selector |
+| `limit` | `integer` | no | Max rows to claim |
+| `durationMinutes` | `integer` | no | Claim TTL |
+| `allOrNone` | `boolean` | no | Commit only if the full set was acquired |
+
+**Response 200:** `{ "claimed": [...] }`.

package/docs/api/http/roles.md

@@ -6,16 +6,41 @@ Role management endpoints are nested under `/api/users/:id/roles`. All endpoints
 
 ## Role Types
 
-Every role assignment has a `type` that controls management permissions. All three types can claim and resolve escalations for their role.
+Every role assignment has a `type` that controls management permissions.
 
 | Type | Permissions |
 |------|-------------|
-| `member` | Claim and resolve escalations for this role |
-| `admin` | Everything a member can do, plus manage users within this role |
+| `member` | Work the role's task queue at the breadth set by its work-surface scope (see below) |
+| `admin` | Everything a member can do on the whole queue, plus manage users within this role |
 | `superadmin` | Full access — manage all roles, all users, system configuration |
 
 A user can hold multiple roles with different types. For example, a user might be a `member` of `reviewer` and an `admin` of `senior-reviewer`.
 
+## Work-Surface Scope
+
+A role is a task queue with four verbs — **search**, **claim**, **ack** (resolve), **delete** (cancel). A `member` carries two orthogonal scope axes that set the breadth of those verbs. `admin` and `superadmin` ignore scope and always act on the whole queue.
+
+| Axis | Values | Governs |
+|------|--------|---------|
+| `read_scope` | `self`, `all` | **search** — which escalations the member sees |
+| `write_scope` | `none`, `self`, `all` | **claim / ack / delete** — which escalations the member may act on |
+
+`self` means escalations assigned to the member (`assigned_to = user`); `all` means the whole role queue. The only constraint is **write ⊆ read** — you cannot act on what you cannot see — so `write_scope=all` requires `read_scope=all`. Both default to `all`, which is the full-queue worker.
+
+The five member profiles:
+
+| read_scope | write_scope | Profile |
+|-----------|------------|---------|
+| `all` | `all` | Full worker — search and act on the whole queue (default) |
+| `all` | `self` | See the whole queue, act only on own items (e.g. a chat-style room) |
+| `self` | `self` | Own items only — a one-time user filling in their pre-assigned form |
+| `all` | `none` | Read-only observer / auditor of the queue |
+| `self` | `none` | Read-only view of one's own items |
+
+Releasing and escalating are queue-management verbs (they move an item out of the member's hands) and require `write_scope=all`; creating a standalone escalation likewise requires `write_scope=all`. A member with `write_scope=self` may only claim/ack/delete items already assigned to them.
+
+This makes one-time and limited-surface users first-class: a workflow can assign an escalation to a named person (pre-claim) and provision them as `read_self` + `write_self`, and they see and act on exactly that one item — no access to the rest of the queue, no table, just the JIT form the workflow routed to them.
+
 ## Special Roles
 
 Three role names have fixed types and elevated permissions:
@@ -26,7 +51,7 @@ Three role names have fixed types and elevated permissions:
 | `engineer` | `admin` | Full (builder) | Engineer role only | Assign users to `engineer` role |
 | `admin` | `admin` | Escalations + user management | All roles — role filter ignored | Assign users to any non-special role. Bulk actions on all escalations |
 
-All other role names are dynamic. A dynamic role can have type `member` (claim/resolve escalations) or `admin` (plus manage users within that role and bulk actions).
+All other role names are dynamic. A dynamic role can have type `member` (work the queue at its read/write scope) or `admin` (whole-queue access plus manage users within that role and bulk actions).
 
 ## Dashboard Access
 
@@ -36,9 +61,9 @@ The dashboard adapts to the authenticated user's access tier:
 |------|-----------|------|
 | **Builder** | `superadmin` or `engineer` role | Full dashboard: workflows, pipelines, MCP, design, storage, admin, all home page sections |
 | **Operations** | Any role with `admin` type | Home page (escalations only), escalation pages, user/role management (scoped to their roles) |
-| **Operator** | Any role with `member` type | Home page (escalations only), escalation pages |
+| **Operator** | Any role with `member` type | Home page (escalations only), escalation pages — scoped to the member's read scope |
 
-Bulk escalation actions (bulk claim, assign, triage, escalate) require `admin` or `superadmin` type. Plain `member` users work on escalations one at a time.
+Bulk escalation actions (bulk claim, assign, triage, escalate) require `admin` or `superadmin` type. Plain `member` users work on escalations one at a time. A member whose read scope is `self` lands directly on their own item in user mode — the queue list and aggregate stats reflect only `read_all` memberships.
 
 ## API Access by Tier
 
@@ -62,6 +87,8 @@ When assigning roles via `POST /api/users/:id/roles`, the caller's own roles det
 | `engineer` | Any role up to `admin` type (never `superadmin` type) |
 | `*/admin` (non-builder) | `member` or `admin` type for roles they themselves hold |
 
+A caller who may assign a role may set any work-surface scope (`read_scope`/`write_scope`) on it. Scope is a refinement of a `member` grant; it is ignored for `admin`/`superadmin`, which always act on the whole queue.
+
 ## List roles for a user
 
 ```
@@ -113,11 +140,13 @@ POST /api/users/:id/roles
 |-------|------|----------|-------------|
 | `role` | `string` | yes | Role name (e.g., `reviewer`) |
 | `type` | `string` | yes | `superadmin`, `admin`, or `member` |
+| `read_scope` | `string` | no | `self` or `all` (default `all`). Search breadth for a `member`; ignored for admin/superadmin |
+| `write_scope` | `string` | no | `none`, `self`, or `all` (default `all`). Claim/ack/delete breadth for a `member` |
 
-**Example request:**
+**Example request** — a one-time user who works only their own assigned item:
 
 ```json
-{ "role": "reviewer", "type": "member" }
+{ "role": "customer-triage", "type": "member", "read_scope": "self", "write_scope": "self" }
 ```
 
 **Response 201:**
@@ -125,8 +154,10 @@ POST /api/users/:id/roles
 ```json
 {
   "user_id": "b2c3d4e5-...",
-  "role": "reviewer",
+  "role": "customer-triage",
   "type": "member",
+  "read_scope": "self",
+  "write_scope": "self",
   "created_at": "2025-01-15T12:00:00.000Z"
 }
 ```
@@ -141,6 +172,10 @@ POST /api/users/:id/roles
 { "error": "type must be superadmin, admin, or member" }
 ```
 
+```json
+{ "error": "write_scope=all requires read_scope=all (cannot act on what you cannot see)" }
+```
+
 A user can hold each role at most once. The primary key is `(user_id, role)`. Adding a role that already exists will return an error.
 
 ## Remove role from user

package/docs/api/http/users.md

@@ -41,8 +41,8 @@ GET /api/users?role=reviewer&status=active&limit=10
       "created_at": "2025-01-10T08:00:00.000Z",
       "updated_at": "2025-01-10T08:00:00.000Z",
       "roles": [
-        { "user_id": "b2c3d4e5-...", "role": "reviewer", "type": "member", "created_at": "2025-01-10T08:00:00.000Z" },
-        { "user_id": "b2c3d4e5-...", "role": "senior-reviewer", "type": "admin", "created_at": "2025-01-10T08:00:00.000Z" }
+        { "user_id": "b2c3d4e5-...", "role": "reviewer", "type": "member", "read_scope": "all", "write_scope": "all", "created_at": "2025-01-10T08:00:00.000Z" },
+        { "user_id": "b2c3d4e5-...", "role": "senior-reviewer", "type": "admin", "read_scope": "all", "write_scope": "all", "created_at": "2025-01-10T08:00:00.000Z" }
       ]
     }
   ],
@@ -92,22 +92,27 @@ Each element in `roles`:
 |-------|------|----------|-------------|
 | `role` | `string` | yes | Role name |
 | `type` | `string` | yes | `superadmin`, `admin`, or `member` |
+| `read_scope` | `string` | no | `self` or `all` (default `all`). Search breadth for a `member`; ignored for admin/superadmin |
+| `write_scope` | `string` | no | `none`, `self`, or `all` (default `all`). Claim/ack/delete breadth for a `member` |
+
+`read_scope` and `write_scope` set the work-surface scope of a `member` grant — how much of the role's queue the user can see and act on. Both default to `all` (the full-queue worker), so a `member` written without scope works the whole queue. The constraint is **write ⊆ read**: `write_scope=all` requires `read_scope=all`. See the [Work-Surface Scope](roles.md#work-surface-scope) section of the Roles API for the five member profiles.
 
 **Example request:**
 
 ```json
 {
-  "external_id": "jane",
-  "email": "jane@acme.com",
-  "display_name": "Jane Chen",
+  "external_id": "new-user",
+  "email": "new-user@example.com",
+  "display_name": "New User",
   "roles": [
     { "role": "reviewer", "type": "member" },
+    { "role": "customer-triage", "type": "member", "read_scope": "self", "write_scope": "self" },
     { "role": "senior-reviewer", "type": "admin" }
   ]
 }
 ```
 
-**Response 201:** The created user object with roles array.
+**Response 201:** The created user object with roles array. Each returned role object includes its `read_scope` and `write_scope`.
 
 **Response 400:**
 
@@ -119,6 +124,10 @@ Each element in `roles`:
 { "error": "Each role must have a role name and type (superadmin, admin, member)" }
 ```
 
+```json
+{ "error": "write_scope=all requires read_scope=all" }
+```
+
 **Response 409:**
 
 ```json

package/docs/api/mcp/admin.md

@@ -54,6 +54,8 @@ Get all tasks and escalations for a process (origin_id).
 
 ## Escalations
 
+Escalations belong to a role's queue. Which of them a person sees and acts on is set by their work-surface scope: a role membership carries a `type` (`member`, `admin`, or `superadmin`) plus `read_scope` (`self` | `all`) — which escalations a member sees — and `write_scope` (`none` | `self` | `all`) — which they may claim, resolve, or cancel — with write ⊆ read. `read_self`/`write_self` narrows a member to items assigned to them (`assigned_to = user`); an `admin` or `superadmin` acts on the whole queue. The tools below operate at whole-queue breadth and need a role permitted to act on the target (see [Access](#access) above). The `assigned_to` filter on `find_escalations` pairs with this model — it narrows results to one user's items, the same surface a `read_self` member sees. Defaults are `all`/`all`. See the [Roles API](../http/roles.md) for the full scope model.
+
 ### find_escalations
 
 Search escalations with optional filters and sorting. Returns full records
@@ -659,11 +661,13 @@ Create a new user account with optional roles.
 | external_id | string | Yes | External identifier |
 | display_name | string | No | Display name |
 | email | string | No | Email address |
-| roles | object[] | No | Roles array (each: role, type: superadmin/admin/member) |
+| roles | object[] | No | Roles array (each: `role`, `type`: superadmin/admin/member, optional `read_scope`, `write_scope`) |
+
+Each role entry may carry a member work-surface scope: `read_scope` (`self` \| `all`, default `all`) and `write_scope` (`none` \| `self` \| `all`, default `all`), with write ⊆ read. This is how a one-time user is provisioned — e.g. `{ "role": "customer-triage", "type": "member", "read_scope": "self", "write_scope": "self" }` for someone who only handles their own pre-assigned escalation.
 
 ### add_user_role
 
-Assign a role to a user.
+Assign a role to a user. For a `member`, optional scope narrows the work surface.
 
 | | |
 |---|---|
@@ -676,6 +680,8 @@ Assign a role to a user.
 | user_id | string | Yes | User ID |
 | role | string | Yes | Role name |
 | type | string | Yes | Role type: superadmin, admin, or member |
+| read_scope | string | No | Member search breadth: `self` or `all` (default `all`) |
+| write_scope | string | No | Member claim/ack/delete breadth: `none`, `self`, or `all` (default `all`) |
 
 ### remove_user_role
 

package/docs/api/mcp/human-queue.md

@@ -65,7 +65,7 @@ List available escalations for a role. Returns pending, unassigned escalations.
 
 ### claim_and_resolve
 
-Claim an escalation and immediately resolve it with a payload. Atomic operation.
+Claim an escalation and immediately resolve it with a payload. Atomic operation. A read/write service account uses this to close out work and record the outcome in one call.
 
 | | |
 |---|---|
@@ -77,7 +77,24 @@ Claim an escalation and immediately resolve it with a payload. Atomic operation.
 |-------|------|----------|-------------|
 | escalation_id | string | Yes | The escalation ID to claim and resolve |
 | resolver_id | string | Yes | Identifier for who/what is resolving |
-| payload | object | Yes | Resolution payload data |
+| payload | object | Yes | Resolution payload data — resumes the waiting workflow |
+| metadata | object | No | Outcome facets merged into the escalation's metadata: the durable, `@>`-queryable record of what happened (disposition, reviewer, timing). Distinct from `payload`, which is not indexed |
+
+### resolve_escalation
+
+Resolve an already-claimed escalation with a payload. Use when the claim happened externally (e.g. via API).
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| escalation_id | string | Yes | The escalation ID to resolve |
+| payload | object | Yes | Resolution payload data — resumes the waiting workflow |
+| metadata | object | No | Outcome facets merged into the escalation's metadata (see `claim_and_resolve`) |
 
 ### escalate_and_wait
 
@@ -99,3 +116,18 @@ Create an escalation and pause the workflow until a human responds. Returns a si
 | type | string | No | Escalation type classification (default: "mcp") |
 | subtype | string | No | Escalation subtype (default: "wait_for_human") |
 | priority | number | No | Priority: 1 (highest) to 4 (lowest) (default: 1) |
+
+## Scope and One-Time Users
+
+Escalations created by these tools land in the target role's queue. Each member of that role sees and acts on them according to their work-surface scope — two axes carried by the role membership alongside its `type` (`member`, `admin`, or `superadmin`):
+
+- `read_scope` (`self` | `all`) governs which escalations a member sees. `read_all` shows the whole role queue; `read_self` shows only items assigned to the member (`assigned_to = user`).
+- `write_scope` (`none` | `self` | `all`) governs which a member may claim and resolve. `write_self` acts only on the member's own assigned items; `write_all` acts on the whole queue. The constraint is write ⊆ read — you cannot act on what you cannot see.
+
+An `admin` or `superadmin` member ignores scope and always acts on the whole queue. The defaults are `all`/`all` — the full-queue worker.
+
+`get_available_work` lists pending, unassigned escalations for a role: the shared pool that whole-queue (`write_all`) workers pull from. A `write_self` member does not draw from this pool — their item is pre-assigned to them.
+
+### The one-time-user pattern
+
+To route a single escalation to a named person, set `assigned_to` when creating it — the `assigned_to` field on `escalate_and_wait` pre-claims the item for that user — and provision that person as a `member` of the role with `read_self` + `write_self`. The result is a scoped single-item surface: they see and act on exactly that one escalation, with no access to the rest of the queue. The scoped membership is provisioned through the platform's user and escalation APIs (see the [Roles API](../http/roles.md)); these MCP tools supply the `assigned_to` pre-claim.