@hotmeshio/long-tail 0.23.1 → 0.24.0

package/docs/api/http/mcp-servers.md

@@ -1,6 +1,8 @@
 # MCP Servers API
 
-Manage MCP server registrations, connections, and tool invocations. All endpoints require authentication.
+Manage MCP server registrations, connections, and tool invocations. All endpoints require authentication. Registering, testing, updating, deleting, connecting, and disconnecting servers require builder access (superadmin or the `engineer` role).
+
+A `stdio` server is a command Long Tail starts on its own host, with that host's environment and network. Builder access therefore includes running commands on the host: grant the `engineer` role with the same care as host access.
 
 ## List servers
 
@@ -8,6 +10,8 @@ Manage MCP server registrations, connections, and tool invocations. All endpoint
 GET /api/mcp/servers
 ```
 
+`transport_config` is included only for builders.
+
 **Query parameters:**
 
 | Parameter | Type | Description |
@@ -53,6 +57,8 @@ GET /api/mcp/servers
 POST /api/mcp/servers
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Request body:**
 
 | Field | Type | Required | Description |
@@ -76,15 +82,17 @@ POST /api/mcp/servers
 **Transport config for `sse`:**
 
 ```json
-{ "url": "http://localhost:3001/sse" }
+{ "url": "http://localhost:3001/sse", "headers": { "Authorization": "Bearer <token>" } }
 ```
 
 **Transport config for `streamable-http`:**
 
 ```json
-{ "url": "http://localhost:3001/mcp" }
+{ "url": "http://localhost:3001/mcp", "headers": { "Authorization": "Bearer <token>" } }
 ```
 
+`headers` is optional and is sent with every request to the server, the SSE stream included. Like the rest of `transport_config`, it is returned only to builders.
+
 **Response 201:** Created server record.
 
 **Response 409:** Server name already exists.
@@ -95,6 +103,8 @@ POST /api/mcp/servers
 GET /api/mcp/servers/:id
 ```
 
+`transport_config` is included only for builders.
+
 **Response 200:** Server record.
 
 **Response 404:** Server not found.
@@ -105,6 +115,8 @@ GET /api/mcp/servers/:id
 PUT /api/mcp/servers/:id
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Request body:** Any fields from the registration (partial update), including `tags`, `compile_hints`, and `credential_providers`.
 
 **Response 200:** Updated server record.
@@ -117,6 +129,8 @@ PUT /api/mcp/servers/:id
 DELETE /api/mcp/servers/:id
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Response 200:**
 
 ```json
@@ -131,6 +145,8 @@ DELETE /api/mcp/servers/:id
 POST /api/mcp/servers/test-connection
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 Test connectivity to an MCP server without persisting a registration. Creates a temporary client, connects, lists tools, then disconnects.
 
 **Request body:**
@@ -167,6 +183,8 @@ On failure:
 POST /api/mcp/servers/:id/connect
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 Establishes a connection to the registered MCP server and caches its tool manifest.
 
 **Response 200:**
@@ -181,6 +199,8 @@ Establishes a connection to the registered MCP server and caches its tool manife
 POST /api/mcp/servers/:id/disconnect
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Response 200:**
 
 ```json
@@ -222,16 +242,24 @@ POST /api/mcp/servers/:id/tools/:toolName/call
 
 Invoke a tool on a connected MCP server.
 
+**Auth:** The tool runs as the caller, or as the `execute_as` account when given. 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. A tool on an external server (any registered network or local-process server) requires builder access, since it runs on the credential stored with that server. `execute_as` follows 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.
+
 **Request body:**
 
 ```json
 {
   "arguments": {
     "image_url": "https://example.com/image.png"
-  }
+  },
+  "execute_as": "optional-account-id"
 }
 ```
 
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `arguments` | `object` | No | Tool arguments |
+| `execute_as` | `string` | No | Account id or `external_id` to run the tool as |
+
 **Response 200:**
 
 ```json
@@ -242,6 +270,8 @@ Invoke a tool on a connected MCP server.
 }
 ```
 
+**Response 403:** The caller may not act as `execute_as`, or the acting account lacks the tool's capability.
+
 **Response 422** (missing credential):
 
 ```json

package/docs/api/http/namespaces.md

@@ -33,6 +33,8 @@ GET /api/namespaces
 POST /api/namespaces
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 Creates or upserts a namespace. Typically called automatically during YAML workflow deployment.
 
 **Request body:**

package/docs/api/http/pipelines.md

@@ -114,6 +114,8 @@ Returns full execution detail for a specific run, including inflated activity ev
 POST /api/pipelines/:jobId/interrupt
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 Immediately terminates a running pipeline job via `HotMesh.interrupt()`. The job is marked as interrupted and its state is expired.
 
 **Body:**

package/docs/api/http/roles.md

@@ -71,10 +71,11 @@ Certain API endpoints require builder access (`superadmin` or `engineer` role):
 
 | Endpoint | Access |
 |----------|--------|
-| `POST/PUT/DELETE /api/users` | Builder |
-| `POST /api/users/:id/roles` | Admin (scoped — see below) |
+| `POST/PUT/PATCH/DELETE /api/users` | Builder |
+| `POST /api/users/:id/roles` | Admin (scoped, see below) |
+| `DELETE /api/users/:id/roles/:role` | Admin (scoped, see below) |
 | All `/api/bot-accounts` | Builder |
-| All `/api/roles` mutations | Builder |
+| All `/api/roles` mutations | Admin access or the `engineer` role |
 | All `/api/controlplane` | Builder |
 
 ### Scoped Role Assignment
@@ -87,6 +88,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 |
 
+Removing a role follows the same rule for the role at the type the account holds it. Only a superadmin may change, remove roles from, or mint keys for an account that holds a superadmin grant; others receive `403`.
+
 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
@@ -289,7 +292,7 @@ Returns all roles with metadata and usage counts.
 POST /api/roles
 ```
 
-Create a standalone role. Requires admin.
+Create a standalone role. Requires role manager (admin type, superadmin, or engineer).
 
 **Request body:**
 
@@ -325,7 +328,7 @@ Create a standalone role. Requires admin.
 DELETE /api/roles/:role
 ```
 
-Delete a role if it has no references. Requires admin.
+Delete a role if it has no references. Requires role manager (admin type, superadmin, or engineer).
 
 **Path parameters:**
 
@@ -494,7 +497,7 @@ Returns all escalation chain pairs.
 POST /api/roles/escalation-chains
 ```
 
-Add a single escalation chain entry. Requires admin.
+Add a single escalation chain entry. Requires role manager (admin type, superadmin, or engineer).
 
 **Request body:**
 
@@ -527,7 +530,7 @@ Add a single escalation chain entry. Requires admin.
 DELETE /api/roles/escalation-chains
 ```
 
-Remove a single escalation chain entry. Requires admin.
+Remove a single escalation chain entry. Requires role manager (admin type, superadmin, or engineer).
 
 **Request body:**
 
@@ -576,7 +579,7 @@ Returns the allowed escalation targets for a specific role.
 PUT /api/roles/:role/escalation-targets
 ```
 
-Replace all escalation targets for a role. Requires admin.
+Replace all escalation targets for a role. Requires role manager (admin type, superadmin, or engineer).
 
 **Path parameters:**
 

package/docs/api/http/service-accounts.md

@@ -1,6 +1,6 @@
 # Service Accounts API
 
-Service accounts are named identities that authenticate with API keys instead of passwords. They share the same role-based access control as human users. All endpoints require admin access.
+Service accounts are named identities that authenticate with API keys instead of passwords. They share the same role-based access control as human users. All endpoints require builder access (superadmin or the `engineer` role). Role assignments follow the [scoped role assignment](roles.md#scoped-role-assignment) rules, and only a superadmin may change, delete, assign or remove roles on, or create or revoke keys for an account that holds a superadmin grant.
 
 ## List service accounts
 
@@ -107,7 +107,7 @@ Deletes the service account and all its API keys (cascade).
 
 ## Service account roles
 
-Roles work identically to user roles.
+Roles work identically to user roles, including the [scoped role assignment](roles.md#scoped-role-assignment) rules.
 
 ```
 GET    /api/bot-accounts/:id/roles
@@ -191,6 +191,12 @@ DELETE /api/bot-accounts/:id/api-keys/:keyId
 { "revoked": true }
 ```
 
+**Response 404:** The key does not exist or belongs to a different service account than `:id`.
+
+```json
+{ "error": "API key not found" }
+```
+
 ## Using a service account API key
 
 Include the raw key as a Bearer token in any API request:

package/docs/api/http/settings.md

@@ -21,7 +21,7 @@ GET /api/settings
   "events": {
     "transport": "socketio",
     "natsWsUrl": null,
-    "natsToken": null
+    "reconnect": { "initialDelayMs": 1000, "maxDelayMs": 60000, "noticeAfterMs": 30000, "spreadMs": 5000 }
   },
   "auth": {
     "sso": false,
@@ -42,8 +42,35 @@ GET /api/settings
 | `escalation.claimDurations` | `number[]` | Available claim duration options in minutes. Used by the frontend to populate duration selectors. Configurable via the `LT_CLAIM_DURATION_OPTIONS` environment variable (JSON array). |
 | `events.transport` | `'socketio' \| 'nats' \| 'none'` | Dashboard event transport. Defaults to `socketio`. Reports `nats` only when `EVENT_TRANSPORT=nats` is set and a NATS adapter is registered. |
 | `events.natsWsUrl` | `string \| null` | NATS WebSocket URL for browser connections. Only present when a NATS adapter is registered. Read from `NATS_WS_URL`. |
-| `events.natsToken` | `string \| null` | NATS auth token for browser connections. Only present when a NATS adapter is registered. Read from `NATS_TOKEN`. |
+| `events.reconnect.initialDelayMs` | `number` | First delay before the dashboard retries a dropped event connection. Read from `NATS_RECONNECT_INITIAL_MS` (default `1000`). |
+| `events.reconnect.maxDelayMs` | `number` | Upper bound on the retry delay as it backs off. Read from `NATS_RECONNECT_MAX_MS` (default `60000`). |
+| `events.reconnect.noticeAfterMs` | `number` | How long the connection may stay down before the dashboard shows a notice. Read from `NATS_LIVE_NOTICE_AFTER_MS` (default `30000`). |
+| `events.reconnect.spreadMs` | `number` | Window the first retry after a drop, and the catch-up refetch after reconnecting, are spread across, so tabs return gradually after a deploy. Read from `NATS_RECONNECT_SPREAD_MS` (default `5000`). |
 | `auth.sso` | `boolean` | Whether SSO is configured for embedded deployments. When `true`, the dashboard auto-exchanges host auth for an LT JWT instead of showing the login form. |
 | `auth.ssoLogoutUrl` | `string \| null` | URL to redirect the browser on logout. Set by the host via `sso.logoutUrl` in the startup config. When `null`, the dashboard shows its own login page on logout. |
 | `ai.enabled` | `boolean` | Whether an LLM API key is configured. When `false`, the dashboard hides AI-specific features (pipelines designer, AI assistant, triage). |
 | `branding.appName` | `string` | The product name shown in the dashboard header. Configured via `branding.appName` in the startup config; defaults to `"LongTail"`. |
+
+## Get NATS credentials
+
+```
+GET /api/nats-credentials
+```
+
+**Auth:** Requires authentication.
+
+Returns the connection details the dashboard uses to subscribe to NATS events.
+
+**Response 200:**
+
+```json
+{
+  "natsWsUrl": "wss://example.com/nats?ticket=...",
+  "natsToken": null
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `natsWsUrl` | `string \| null` | NATS WebSocket URL. Behind the WebSocket proxy, the URL carries a `ticket` query parameter for the caller, valid for `NATS_WS_TICKET_TTL_SECONDS` (default `300`). `null` when no NATS adapter is registered. |
+| `natsToken` | `string \| null` | `null` behind the WebSocket proxy, since the proxy holds the NATS credential and the ticket allows subscribing only. For direct connections, `NATS_DASHBOARD_TOKEN` when set, else `NATS_TOKEN`. |

package/docs/api/http/tasks.md

@@ -49,6 +49,8 @@ POST /api/tasks
 
 ---
 
+**Run data.** A task row carries its run's input (`envelope`), output (`data`) and `metadata`. A builder, and the person who started the run or the account it runs as, receive them; for any other caller those three fields are omitted from list, process and single-task responses.
+
 ## List tasks
 
 ```
@@ -169,7 +171,7 @@ List distinct `origin_id` values with summary stats. Each origin ID represents a
 GET /api/tasks/processes/:originId
 ```
 
-Returns all tasks and escalations for a process (identified by `origin_id`).
+Returns all tasks for a process (identified by `origin_id`), and the escalations in that process the caller may read (the same read-scope rule as `GET /api/escalations/by-workflow/:workflowId`).
 
 **Path parameters:**
 

package/docs/api/http/topics.md

@@ -2,7 +2,7 @@
 
 Browse, register, and manage the topic catalog — a persistent registry of known event topics with descriptions, payload schemas, and subscriber counts.
 
-All endpoints require authentication.
+All endpoints require authentication. Registering, updating, deleting, and publishing (`POST /api/topics/by-name/:topic/publish`) require builder access (superadmin or the `engineer` role). Publishing a subject that starts with `system.` or `agent.` requires superadmin.
 
 ## List topics
 
@@ -94,6 +94,8 @@ Subscribers are matched using NATS-style pattern matching — an agent subscribe
 POST /api/topics
 ```
 
+**Auth:** Requires builder access.
+
 Manually register a topic in the catalog. Use this to pre-declare topics before first publish.
 
 **Body:**
@@ -134,6 +136,8 @@ Manually register a topic in the catalog. Use this to pre-declare topics before
 PUT /api/topics/by-name/:topic
 ```
 
+**Auth:** Requires builder access.
+
 Partial update — only include fields to change. System topics (`source: 'system'`) can be updated (description, tags) but not deleted.
 
 **Body:**
@@ -155,6 +159,8 @@ Partial update — only include fields to change. System topics (`source: 'syste
 DELETE /api/topics/by-name/:topic
 ```
 
+**Auth:** Requires builder access.
+
 Permanently removes a topic from the catalog. System topics are protected.
 
 **Response 200:** `{ "deleted": true }`

package/docs/api/http/users.md

@@ -1,6 +1,6 @@
 # Users API
 
-Users represent the humans who claim and resolve escalations. Each user has a unique `external_id` that maps to your application's identity system. All endpoints require authentication. Mutating endpoints (create, update, delete, role management) require admin access (`admin` or `superadmin` role).
+Users represent the humans who claim and resolve escalations. Each user has a unique `external_id` that maps to your application's identity system. All endpoints require authentication. Creating, updating, patching, and deleting users require builder access (superadmin or the `engineer` role). Adding and removing roles require admin access and follow the assignment rules in the [Roles API](roles.md#scoped-role-assignment). Only a superadmin may grant the `superadmin` type or change a superadmin account.
 
 For service identities (CI bots, schedulers, automated agents), use the [Service Accounts API](service-accounts.md) instead. Service accounts share the same RBAC system but authenticate with API keys rather than passwords or OAuth.
 
@@ -76,6 +76,8 @@ GET /api/users/:id
 POST /api/users
 ```
 
+**Auth:** Requires builder access. Every initial role must be one the caller may assign (see [Roles API](roles.md#scoped-role-assignment)); otherwise `403`.
+
 **Request body:**
 
 | Field | Type | Required | Description |
@@ -140,6 +142,8 @@ Each element in `roles`:
 PUT /api/users/:id
 ```
 
+**Auth:** Requires builder access. Changing a superadmin account requires superadmin (`403` otherwise).
+
 Partial update — only the fields you include are changed.
 
 **Request body:**
@@ -174,7 +178,7 @@ Partial update — only the fields you include are changed.
 PATCH /api/users/:id/properties
 ```
 
-Atomically patch the user's properties dictionary (`metadata`) — one statement, never read-merge-write. Editing one property can never clobber another; a rename preserves its value with no key-absent window. Builder only (the same gate as every other user write).
+Atomically patch the user's properties dictionary (`metadata`) — one statement, never read-merge-write. Editing one property can never clobber another; a rename preserves its value with no key-absent window. Requires builder access, the same gate as every other user write. Changing a superadmin account requires superadmin.
 
 **Request body:**
 
@@ -226,6 +230,8 @@ The property keys the platform itself resolves identities against — every enab
 DELETE /api/users/:id
 ```
 
+**Auth:** Requires builder access. Changing a superadmin account requires superadmin (`403` otherwise).
+
 Deletes the user and all associated role assignments (cascade).
 
 **Response 200:**

package/docs/api/http/workflows.md

@@ -232,7 +232,7 @@ Start a workflow by its registered type. The workflow must have `invocable: true
 |-------|------|----------|-------------|
 | `data` | `object` | yes | Business data passed to the workflow as `envelope.data` |
 | `metadata` | `object` | no | Control flow metadata passed as `envelope.metadata` |
-| `execute_as` | `string` | no | Service account `external_id` to run as (admin only) |
+| `execute_as` | `string` | no | Account `external_id` or id to run as. Requires admin access and must satisfy the act-as rule below. |
 
 The input gate validates against the `metadata` in the request; the dashboard sends the config's `envelope_schema.metadata` with every invoke it starts.
 
@@ -268,12 +268,16 @@ The workflow starts on its configured `task_queue` with a generated workflow ID
 | `403` | `{ "error": "Workflow is not invocable" }` | `invocable` is `false` |
 | `403` | `{ "error": "User not registered" }` | RBAC check failed — no matching user |
 | `403` | `{ "error": "Insufficient role for invocation" }` | User lacks a required invocation role |
+| `403` | `{ "error": "execute_as may not exceed your own authority" }` | The caller may not act as the `execute_as` account |
+| `404` | `{ "error": "execute_as principal \"...\" not found" }` | No account matches `execute_as` |
 | `404` | `{ "error": "Workflow not found" }` | No config exists for this type |
 | `422` | `{ "error": "data failed input schema validation (n violations)", "code": "schema_validation", "violations": [{ "field", "message" }], "role": null, "schemaVersion": null, "workflowType" }` | The config declares `input_schema` and `data` violates it; `x-lt-options` over pinned `input_lookups` constrains values to the resolved edition |
 
 **Authorization:**
 
-When `invocation_roles` is empty, any authenticated user can invoke. When set, the user must hold at least one of the listed roles (checked against `lt_user_roles` via the user's `external_id`). Superadmins bypass this check.
+When `invocation_roles` is empty, any authenticated user can invoke. When set, the user must hold at least one of the listed roles. Roles are read from the caller's current grants in `lt_user_roles`, not from token claims. A superadmin grant, or the `admin` role held with `admin` type, invokes any workflow. `capabilityInvoke` requires a superadmin grant.
+
+`execute_as` follows the act-as rule: a superadmin may act as anyone. 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. Nobody else may.
 
 ### List the caller's invokable workflows
 
@@ -307,6 +311,8 @@ These endpoints let you check on running or completed workflows. The `workflowId
 GET /api/workflows/:workflowId/status
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Response 200:**
 
 ```json
@@ -330,6 +336,8 @@ GET /api/workflows/:workflowId/result
 
 Returns the result if the workflow is complete, or `202` if it's still running. Never blocks.
 
+**Auth:** Requires builder access, or being the person who started the run or the account it runs as (read from the run's start envelope: `lt.userId`, or `lt.initiatedBy` when it runs under `execute_as`). Others receive `403`.
+
 **Response 200** (complete):
 
 ```json
@@ -361,6 +369,8 @@ Returns the result if the workflow is complete, or `202` if it's still running.
 
 ## Execution History Export
 
+Every `/api/workflow-states` endpoint requires builder access, except `/:workflowId/execution`, which follows the same rule as `GET /api/workflows/:workflowId/result`.
+
 Every workflow's full execution history is exportable in JSON. Two formats are available: a raw state export (HotMesh-native) and a structured execution event history with typed events, ISO timestamps, durations, and cross-references.
 
 Because workflows are durably executed — state is transactionally checkpointed to Postgres after every step — the export is a complete, faithful record of everything that happened. Every activity scheduled, every result returned, every signal received, every child workflow spawned. Nothing is reconstructed or approximated.
@@ -371,6 +381,8 @@ Because workflows are durably executed — state is transactionally checkpointed
 GET /api/workflows/:workflowId/export
 ```
 
+**Auth:** Requires builder access.
+
 Returns the raw workflow state from HotMesh. For full control over facet filtering and execution format, use the dedicated `/api/workflow-states` endpoints below.
 
 **Response 200:** Raw workflow state object (data, state, status, timeline, transitions).
@@ -658,6 +670,8 @@ POST /api/workflows/:workflowId/terminate
 
 Interrupt a running workflow. The workflow is immediately terminated.
 
+**Auth:** Requires builder access.
+
 **Path parameters:**
 
 | Parameter | Description |
@@ -688,16 +702,17 @@ Interrupt a running workflow. The workflow is immediately terminated.
 | `DELETE` | `/:type/config` | admin | Delete a workflow configuration (cascade) |
 | `GET` | `/:type/input-lookups` | RBAC | Resolve the config's pinned knowledge lookups (invoke predicate) |
 | `POST` | `/:type/invoke` | RBAC | Invoke a workflow (requires `invocable: true`) |
-| `GET` | `/:workflowId/status` | any | Workflow status |
-| `GET` | `/:workflowId/result` | any | Get workflow result (200 if complete, 202 if running) |
-| `POST` | `/:workflowId/terminate` | any | Terminate a running workflow |
-| `GET` | `/:workflowId/export` | any | Raw state export (convenience alias) |
+| `GET` | `/:workflowId/status` | builder | Workflow status |
+| `GET` | `/:workflowId/result` | builder or run owner | Get workflow result (200 if complete, 202 if running) |
+| `POST` | `/:workflowId/terminate` | builder | Terminate a running workflow |
+| `GET` | `/:workflowId/export` | builder | Raw state export (convenience alias) |
 
 ### `/api/workflow-states`
 
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| `GET` | `/:workflowId` | any | Raw state export with facet filtering |
-| `GET` | `/:workflowId/execution` | any | Structured execution history |
-| `GET` | `/:workflowId/status` | any | Status semaphore |
-| `GET` | `/:workflowId/state` | any | Current workflow state snapshot |
+| `GET` | `/:workflowId` | builder | Raw state export with facet filtering |
+| `GET` | `/:workflowId/execution` | builder or run owner | Structured execution history |
+| `GET` | `/:workflowId/envelopes` | builder | Input and output envelopes |
+| `GET` | `/:workflowId/status` | builder | Status semaphore |
+| `GET` | `/:workflowId/state` | builder | Current workflow state snapshot |

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

@@ -2,6 +2,10 @@
 
 Manage YAML workflow definitions — the compiled deterministic pipelines generated from successful MCP triage executions. Each namespace (`app_id`) acts as a process server; each workflow is a tool within that server. All endpoints require authentication.
 
+**Auth:** Creating, updating, regenerating, deleting, deploying, activating, archiving, and restoring workflows, and setting or clearing a cron schedule (`PUT`/`DELETE /api/yaml-workflows/:id/cron`), require builder access (superadmin or the `engineer` role). Reads and invoke are open to any authenticated caller.
+
+An `execute_as` on invoke or on a cron schedule follows 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.
+
 ## List workflows
 
 ```
@@ -68,6 +72,8 @@ GET /api/yaml-workflows
 POST /api/yaml-workflows
 ```
 
+**Auth:** Requires builder access.
+
 Generates a YAML workflow from a completed MCP triage execution.
 
 **Request body:**
@@ -108,6 +114,8 @@ GET /api/yaml-workflows/:id
 PUT /api/yaml-workflows/:id
 ```
 
+**Auth:** Requires builder access.
+
 **Request body:** Partial update — `yaml_content`, `name`, `description`.
 
 **Response 200:** Updated workflow record.
@@ -120,6 +128,8 @@ PUT /api/yaml-workflows/:id
 DELETE /api/yaml-workflows/:id
 ```
 
+**Auth:** Requires builder access.
+
 Only allowed for `draft` or `archived` workflows.
 
 **Response 200:**
@@ -138,6 +148,8 @@ Only allowed for `draft` or `archived` workflows.
 POST /api/yaml-workflows/:id/deploy
 ```
 
+**Auth:** Requires builder access.
+
 Deploys all YAML workflows sharing this workflow's `app_id` as a merged version. Bumps the version, marks all non-archived siblings as `active`, and registers HotMesh workers for the deployed workflows.
 
 **Response 200:** Updated workflow record (with new version).
@@ -150,6 +162,8 @@ Deploys all YAML workflows sharing this workflow's `app_id` as a merged version.
 POST /api/yaml-workflows/:id/activate
 ```
 
+**Auth:** Requires builder access.
+
 Activates the deployed version and registers workers for all workflows in the same `app_id`. Requires status `deployed` or `active`.
 
 **Response 200:** Updated workflow record.
@@ -173,6 +187,9 @@ Invoke an active YAML workflow with parameters.
 | `data` | `object` | No | Input data matching the workflow's `input_schema` |
 | `sync` | `boolean` | No | Wait for result (default: false) |
 | `timeout` | `integer` | No | Timeout in ms for sync invocations (default: 120000) |
+| `execute_as` | `string` | No | Account id or `external_id` to run as. Must satisfy the act-as rule. |
+
+The server sets the workflow's `_scope` identity context. A `_scope` key in `data` is ignored.
 
 **Async response 200:**
 
@@ -202,6 +219,8 @@ Invoke an active YAML workflow with parameters.
 POST /api/yaml-workflows/:id/regenerate
 ```
 
+**Auth:** Requires builder access.
+
 Re-generate the YAML from the original source execution. Allowed for `draft`, `deployed`, and `active` workflows (not `archived`).
 
 **Request body:**
@@ -223,6 +242,8 @@ Re-generate the YAML from the original source execution. Allowed for `draft`, `d
 POST /api/yaml-workflows/:id/archive
 ```
 
+**Auth:** Requires builder access.
+
 Stops accepting invocations. If active, stops the engine.
 
 **Response 200:** Updated workflow record with status `archived`.