nodmix 2026.5.25

package/docs/clawhub/publishing.md

@@ -0,0 +1,96 @@
+---
+summary: "How ClawHub publishing works for skills, plugins, owners, scopes, releases, and review."
+read_when:
+  - Publishing a skill or plugin
+  - Debugging owner or package scope errors
+  - Adding publish UI, CLI, or backend behavior
+---
+
+# Publishing on ClawHub
+
+ClawHub publishing is owner-scoped: every publish targets a publisher, and the
+server decides whether the signed-in user is allowed to publish there.
+
+## Owners
+
+An owner is a ClawHub publisher handle, such as `@alice` or `@nodmix`.
+Personal owners are created for users. Org owners can have multiple members.
+
+When you publish, you either use your personal owner or choose an org owner
+where you have publisher access.
+
+## Skills
+
+Skills are published from a skill folder. The public page is:
+
+```text
+https://clawhub.ai/<owner>/<slug>
+```
+
+Example:
+
+```text
+https://clawhub.ai/alice/review-helper
+```
+
+The publish request includes the selected owner, slug, version, changelog, and
+files. The server verifies that the actor can publish as that owner before it
+creates the release.
+
+## Plugins
+
+Plugins use npm-style package names. Scoped package names include the owner in
+the first part of the name:
+
+```text
+@owner/package-name
+```
+
+The scope must match the selected publish owner. If your package is named
+`@nodmix/dronzer`, it can only be published as `@nodmix`. If you publish as
+`@vintageayu`, rename the package to `@vintageayu/dronzer`.
+
+This prevents a package from claiming an org namespace that the publisher does
+not control.
+
+## Release Flow
+
+1. The UI, CLI, or GitHub workflow gathers package metadata and files.
+2. The publish request is sent to ClawHub with the selected owner.
+3. The server validates owner permissions, package scope, package name, version,
+   file limits, and source metadata.
+4. ClawHub stores the release and starts automated security checks.
+5. New releases are hidden from normal install/download surfaces until review
+   and verification finish.
+
+If validation fails, the release is not created.
+
+## FAQ
+
+### Package scope must match selected owner
+
+If the package scope and selected owner do not match, ClawHub rejects the
+publish:
+
+```text
+Package scope "@nodmix" must match selected owner "@vintageayu".
+Publish as "@nodmix" or rename this package to "@vintageayu/dronzer".
+```
+
+To fix it, either choose the owner named by the package scope, or rename the
+package so the scope matches the owner you can publish as.
+
+If the package name already has the right scope but the package is owned by the
+wrong publisher, transfer ownership instead:
+
+```sh
+clawhub package transfer @opik/opik-nodmix --to opik
+```
+
+Use package transfer only when you have admin access to both the current package
+owner and the destination publisher. It does not let you publish into a scope you
+cannot manage.
+
+This protects org namespaces. A package named `@nodmix/dronzer` claims the
+`@nodmix` namespace, so only publishers with access to the `@nodmix` owner
+can publish it.

package/docs/cli/acp.md

@@ -0,0 +1,370 @@
+---
+summary: "Run the ACP bridge for IDE integrations"
+read_when:
+  - Setting up ACP-based IDE integrations
+  - Debugging ACP session routing to the Gateway
+title: "ACP"
+---
+
+Run the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to an Nodmix Gateway.
+
+This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway
+over WebSocket. It keeps ACP sessions mapped to Gateway session keys.
+
+`nodmix acp` is a Gateway-backed ACP bridge, not a full ACP-native editor
+runtime. It focuses on session routing, prompt delivery, and basic streaming
+updates.
+
+If you want an external MCP client to talk directly to Nodmix channel
+conversations instead of hosting an ACP harness session, use
+[`nodmix mcp serve`](/cli/mcp) instead.
+
+## What this is not
+
+This page is often confused with ACP harness sessions.
+
+`nodmix acp` means:
+
+- Nodmix acts as an ACP server
+- an IDE or ACP client connects to Nodmix
+- Nodmix forwards that work into a Gateway session
+
+This is different from [ACP Agents](/tools/acp-agents), where Nodmix runs an
+external harness such as Codex or Claude Code through `acpx`.
+
+Quick rule:
+
+- editor/client wants to talk ACP to Nodmix: use `nodmix acp`
+- Nodmix should launch Codex/Claude/Gemini as an ACP harness: use `/acp spawn` and [ACP Agents](/tools/acp-agents)
+
+## Compatibility Matrix
+
+| ACP area                                                              | Status      | Notes                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `initialize`, `newSession`, `prompt`, `cancel`                        | Implemented | Core bridge flow over stdio to Gateway chat/send + abort.                                                                                                                                                                                        |
+| `listSessions`, slash commands                                        | Implemented | Session list works against Gateway session state with bounded cursor pagination and `cwd` filtering where Gateway session rows carry workspace metadata; commands are advertised via `available_commands_update`.                                |
+| Session lineage metadata                                              | Implemented | Session listings and session info snapshots include Nodmix parent and child lineage in `_meta` so ACP clients can render subagent graphs without private Gateway side channels.                                                                |
+| `resumeSession`, `closeSession`                                       | Implemented | Resume rebinds an ACP session to an existing Gateway session without replaying history. Close cancels active bridge work, resolves pending prompts as cancelled, and releases bridge session state.                                              |
+| `loadSession`                                                         | Partial     | Rebinds the ACP session to a Gateway session key and replays ACP event-ledger history for bridge-created sessions. Older/no-ledger sessions fall back to stored user/assistant text.                                                             |
+| Prompt content (`text`, embedded `resource`, images)                  | Partial     | Text/resources are flattened into chat input; images become Gateway attachments.                                                                                                                                                                 |
+| Session modes                                                         | Partial     | `session/set_mode` is supported and the bridge exposes initial Gateway-backed session controls for thought level, tool verbosity, reasoning, usage detail, and elevated actions. Broader ACP-native mode/config surfaces are still out of scope. |
+| Session info and usage updates                                        | Partial     | The bridge emits `session_info_update` and best-effort `usage_update` notifications from cached Gateway session snapshots. Usage is approximate and only sent when Gateway token totals are marked fresh.                                        |
+| Tool streaming                                                        | Partial     | `tool_call` / `tool_call_update` events include raw I/O, text content, and best-effort file locations when Gateway tool args/results expose them. Embedded terminals and richer diff-native output are still not exposed.                        |
+| Exec approvals                                                        | Partial     | Gateway exec approval prompts during active ACP prompt turns are relayed to the ACP client with `session/request_permission`.                                                                                                                    |
+| Per-session MCP servers (`mcpServers`)                                | Unsupported | Bridge mode rejects per-session MCP server requests. Configure MCP on the Nodmix gateway or agent instead.                                                                                                                                     |
+| Client filesystem methods (`fs/read_text_file`, `fs/write_text_file`) | Unsupported | The bridge does not call ACP client filesystem methods.                                                                                                                                                                                          |
+| Client terminal methods (`terminal/*`)                                | Unsupported | The bridge does not create ACP client terminals or stream terminal ids through tool calls.                                                                                                                                                       |
+| Session plans / thought streaming                                     | Unsupported | The bridge currently emits output text and tool status, not ACP plan or thought updates.                                                                                                                                                         |
+
+## Known Limitations
+
+- `loadSession` can replay complete ACP event-ledger history only for
+  bridge-created sessions. Older/no-ledger sessions still use transcript
+  fallback and do not reconstruct historic tool calls or system notices.
+- If multiple ACP clients share the same Gateway session key, event and cancel
+  routing are best-effort rather than strictly isolated per client. Prefer the
+  default isolated `acp:<uuid>` sessions when you need clean editor-local
+  turns.
+- Gateway stop states are translated into ACP stop reasons, but that mapping is
+  less expressive than a fully ACP-native runtime.
+- Initial session controls currently surface a focused subset of Gateway knobs:
+  thought level, tool verbosity, reasoning, usage detail, and elevated
+  actions. Model selection and exec-host controls are not yet exposed as ACP
+  config options.
+- `session_info_update` and `usage_update` are derived from Gateway session
+  snapshots, not live ACP-native runtime accounting. Usage is approximate,
+  carries no cost data, and is only emitted when the Gateway marks total token
+  data as fresh.
+- Tool follow-along data is best-effort. The bridge can surface file paths that
+  appear in known tool args/results, but it does not yet emit ACP terminals or
+  structured file diffs.
+- Exec approval relay is scoped to the active ACP prompt turn; approvals from
+  other Gateway sessions are ignored.
+
+## Usage
+
+```bash
+nodmix acp
+
+# Remote Gateway
+nodmix acp --url wss://gateway-host:18789 --token <token>
+
+# Remote Gateway (token from file)
+nodmix acp --url wss://gateway-host:18789 --token-file ~/.nodmix/gateway.token
+
+# Attach to an existing session key
+nodmix acp --session agent:main:main
+
+# Attach by label (must already exist)
+nodmix acp --session-label "support inbox"
+
+# Reset the session key before the first prompt
+nodmix acp --session agent:main:main --reset-session
+```
+
+## ACP client (debug)
+
+Use the built-in ACP client to sanity-check the bridge without an IDE.
+It spawns the ACP bridge and lets you type prompts interactively.
+
+```bash
+nodmix acp client
+
+# Point the spawned bridge at a remote Gateway
+nodmix acp client --server-args --url wss://gateway-host:18789 --token-file ~/.nodmix/gateway.token
+
+# Override the server command (default: nodmix)
+nodmix acp client --server "node" --server-args nodmix.mjs acp --url ws://127.0.0.1:19001
+```
+
+Permission model (client debug mode):
+
+- Auto-approval is allowlist-based and only applies to trusted core tool IDs.
+- `read` auto-approval is scoped to the current working directory (`--cwd` when set).
+- ACP only auto-approves narrow readonly classes: scoped `read` calls under the active cwd plus readonly search tools (`search`, `web_search`, `memory_search`). Unknown/non-core tools, out-of-scope reads, exec-capable tools, control-plane tools, mutating tools, and interactive flows always require explicit prompt approval.
+- Server-provided `toolCall.kind` is treated as untrusted metadata (not an authorization source).
+- This ACP bridge policy is separate from ACPX harness permissions. If you run Nodmix through the `acpx` backend, `plugins.entries.acpx.config.permissionMode=approve-all` is the break-glass "yolo" switch for that harness session.
+
+## Protocol smoke testing
+
+For protocol-level debugging, start a Gateway with isolated state and drive
+`nodmix acp` over stdio with an ACP JSON-RPC client. Cover `initialize`,
+`session/new`, `session/list` with an absolute `cwd`, `session/resume`,
+`session/close`, duplicate close, and missing resume.
+
+The proof should include the advertised lifecycle capabilities, a Gateway-backed
+session row, update notifications, and the Gateway `sessions.list` log:
+
+```json
+{
+  "initialize": {
+    "protocolVersion": 1,
+    "agentCapabilities": {
+      "sessionCapabilities": {
+        "list": {},
+        "resume": {},
+        "close": {}
+      }
+    }
+  },
+  "listSessions": {
+    "sessions": [
+      {
+        "sessionId": "agent:main:acp-smoke",
+        "cwd": "/path/to/workspace",
+        "_meta": {
+          "sessionKey": "agent:main:acp-smoke",
+          "kind": "direct"
+        }
+      }
+    ],
+    "nextCursor": null
+  },
+  "notifications": ["session_info_update", "available_commands_update", "usage_update"],
+  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]
+}
+```
+
+Avoid using `nodmix gateway call sessions.list` as the only ACP proof. That
+CLI path may request a fresh-token operator scope upgrade; ACP bridge
+correctness is proven by ACP stdio frames plus the Gateway `sessions.list` log.
+
+## How to use this
+
+Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want
+it to drive an Nodmix Gateway session.
+
+1. Ensure the Gateway is running (local or remote).
+2. Configure the Gateway target (config or flags).
+3. Point your IDE to run `nodmix acp` over stdio.
+
+Example config (persisted):
+
+```bash
+nodmix config set gateway.remote.url wss://gateway-host:18789
+nodmix config set gateway.remote.token <token>
+```
+
+Example direct run (no config write):
+
+```bash
+nodmix acp --url wss://gateway-host:18789 --token <token>
+# preferred for local process safety
+nodmix acp --url wss://gateway-host:18789 --token-file ~/.nodmix/gateway.token
+```
+
+## Selecting agents
+
+ACP does not pick agents directly. It routes by the Gateway session key.
+
+Use agent-scoped session keys to target a specific agent:
+
+```bash
+nodmix acp --session agent:main:main
+nodmix acp --session agent:design:main
+nodmix acp --session agent:qa:bug-123
+```
+
+Each ACP session maps to a single Gateway session key. One agent can have many
+sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override
+the key or label.
+
+Per-session `mcpServers` are not supported in bridge mode. If an ACP client
+sends them during `newSession` or `loadSession`, the bridge returns a clear
+error instead of silently ignoring them.
+
+If you want ACPX-backed sessions to see Nodmix plugin tools or selected
+built-in tools such as `cron`, enable the gateway-side ACPX MCP bridges instead
+of trying to pass per-session `mcpServers`. See
+[ACP Agents](/tools/acp-agents-setup#plugin-tools-mcp-bridge) and
+[Nodmix tools MCP bridge](/tools/acp-agents-setup#nodmix-tools-mcp-bridge).
+
+## Use from `acpx` (Codex, Claude, other ACP clients)
+
+If you want a coding agent such as Codex or Claude Code to talk to your
+Nodmix bot over ACP, use `acpx` with its built-in `nodmix` target.
+
+Typical flow:
+
+1. Run the Gateway and make sure the ACP bridge can reach it.
+2. Point `acpx nodmix` at `nodmix acp`.
+3. Target the Nodmix session key you want the coding agent to use.
+
+Examples:
+
+```bash
+# One-shot request into your default Nodmix ACP session
+acpx nodmix exec "Summarize the active Nodmix session state."
+
+# Persistent named session for follow-up turns
+acpx nodmix sessions ensure --name codex-bridge
+acpx nodmix -s codex-bridge --cwd /path/to/repo \
+  "Ask my Nodmix work agent for recent context relevant to this repo."
+```
+
+If you want `acpx nodmix` to target a specific Gateway and session key every
+time, override the `nodmix` agent command in `~/.acpx/config.json`:
+
+```json
+{
+  "agents": {
+    "nodmix": {
+      "command": "env NODMIX_HIDE_BANNER=1 NODMIX_SUPPRESS_NOTES=1 nodmix acp --url ws://127.0.0.1:18789 --token-file ~/.nodmix/gateway.token --session agent:main:main"
+    }
+  }
+}
+```
+
+For a repo-local Nodmix checkout, use the direct CLI entrypoint instead of the
+dev runner so the ACP stream stays clean. For example:
+
+```bash
+env NODMIX_HIDE_BANNER=1 NODMIX_SUPPRESS_NOTES=1 node nodmix.mjs acp ...
+```
+
+This is the easiest way to let Codex, Claude Code, or another ACP-aware client
+pull contextual information from an Nodmix agent without scraping a terminal.
+
+## Zed editor setup
+
+Add a custom ACP agent in `~/.config/zed/settings.json` (or use Zed's Settings UI):
+
+```json
+{
+  "agent_servers": {
+    "Nodmix ACP": {
+      "type": "custom",
+      "command": "nodmix",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+To target a specific Gateway or agent:
+
+```json
+{
+  "agent_servers": {
+    "Nodmix ACP": {
+      "type": "custom",
+      "command": "nodmix",
+      "args": [
+        "acp",
+        "--url",
+        "wss://gateway-host:18789",
+        "--token",
+        "<token>",
+        "--session",
+        "agent:design:main"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+In Zed, open the Agent panel and select "Nodmix ACP" to start a thread.
+
+## Session mapping
+
+By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix.
+To reuse a known session, pass a session key or label:
+
+- `--session <key>`: use a specific Gateway session key.
+- `--session-label <label>`: resolve an existing session by label.
+- `--reset-session`: mint a fresh session id for that key (same key, new transcript).
+
+If your ACP client supports metadata, you can override per session:
+
+```json
+{
+  "_meta": {
+    "sessionKey": "agent:main:main",
+    "sessionLabel": "support inbox",
+    "resetSession": true
+  }
+}
+```
+
+Learn more about session keys at [/concepts/session](/concepts/session).
+
+## Options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
+- `--token <token>`: Gateway auth token.
+- `--token-file <path>`: read Gateway auth token from file.
+- `--password <password>`: Gateway auth password.
+- `--password-file <path>`: read Gateway auth password from file.
+- `--session <key>`: default session key.
+- `--session-label <label>`: default session label to resolve.
+- `--require-existing`: fail if the session key/label does not exist.
+- `--reset-session`: reset the session key before first use.
+- `--no-prefix-cwd`: do not prefix prompts with the working directory.
+- `--provenance <off|meta|meta+receipt>`: include ACP provenance metadata or receipts.
+- `--verbose, -v`: verbose logging to stderr.
+
+Security note:
+
+- `--token` and `--password` can be visible in local process listings on some systems.
+- Prefer `--token-file`/`--password-file` or environment variables (`NODMIX_GATEWAY_TOKEN`, `NODMIX_GATEWAY_PASSWORD`).
+- Gateway auth resolution follows the shared contract used by other Gateway clients:
+  - local mode: env (`NODMIX_GATEWAY_*`) -> `gateway.auth.*` -> `gateway.remote.*` fallback only when `gateway.auth.*` is unset (configured-but-unresolved local SecretRefs fail closed)
+  - remote mode: `gateway.remote.*` with env/config fallback per remote precedence rules
+  - `--url` is override-safe and does not reuse implicit config/env credentials; pass explicit `--token`/`--password` (or file variants)
+- ACP runtime backend child processes receive `NODMIX_SHELL=acp`, which can be used for context-specific shell/profile rules.
+- `nodmix acp client` sets `NODMIX_SHELL=acp-client` on the spawned bridge process.
+
+### `acp client` options
+
+- `--cwd <dir>`: working directory for the ACP session.
+- `--server <command>`: ACP server command (default: `nodmix`).
+- `--server-args <args...>`: extra arguments passed to the ACP server.
+- `--server-verbose`: enable verbose logging on the ACP server.
+- `--verbose, -v`: verbose client logging.
+
+## Related
+
+- [CLI reference](/cli)
+- [ACP agents](/tools/acp-agents)

package/docs/cli/agent.md

@@ -0,0 +1,103 @@
+---
+summary: "CLI reference for `nodmix agent` (send one agent turn via the Gateway)"
+read_when:
+  - You want to run one agent turn from scripts (optionally deliver reply)
+title: "Agent"
+---
+
+# `nodmix agent`
+
+Run an agent turn via the Gateway (use `--local` for embedded).
+Use `--agent <id>` to target a configured agent directly.
+
+Pass at least one session selector:
+
+- `--to <dest>`
+- `--session-id <id>`
+- `--agent <id>`
+
+Related:
+
+- Agent send tool: [Agent send](/tools/agent-send)
+
+## Options
+
+- `-m, --message <text>`: required message body
+- `-t, --to <dest>`: recipient used to derive the session key
+- `--session-id <id>`: explicit session id
+- `--agent <id>`: agent id; overrides routing bindings
+- `--model <id>`: model override for this run (`provider/model` or model id)
+- `--thinking <level>`: agent thinking level (`off`, `minimal`, `low`, `medium`, `high`, plus provider-supported custom levels such as `xhigh`, `adaptive`, or `max`)
+- `--verbose <on|off>`: persist verbose level for the session
+- `--channel <channel>`: delivery channel; omit to use the main session channel
+- `--reply-to <target>`: delivery target override
+- `--reply-channel <channel>`: delivery channel override
+- `--reply-account <id>`: delivery account override
+- `--local`: run the embedded agent directly (after plugin registry preload)
+- `--deliver`: send the reply back to the selected channel/target
+- `--timeout <seconds>`: override agent timeout (default 600 or config value)
+- `--json`: output JSON
+
+## Examples
+
+```bash
+nodmix agent --to +15555550123 --message "status update" --deliver
+nodmix agent --agent ops --message "Summarize logs"
+nodmix agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"
+nodmix agent --session-id 1234 --message "Summarize inbox" --thinking medium
+nodmix agent --to +15555550123 --message "Trace logs" --verbose on --json
+nodmix agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+nodmix agent --agent ops --message "Run locally" --local
+```
+
+## Notes
+
+- Gateway mode falls back to the embedded agent when the Gateway request fails. Use `--local` to force embedded execution up front.
+- `--local` still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
+- `--local` and embedded fallback runs are treated as one-shot runs. Bundled MCP loopback resources and warm Claude stdio sessions opened for that local process are retired after the reply, so scripted invocations do not keep local child processes alive.
+- Gateway-backed runs leave Gateway-owned MCP loopback resources under the running Gateway process; older clients may still send the historical cleanup flag, but the Gateway accepts it as a compatibility no-op.
+- `--channel`, `--reply-channel`, and `--reply-account` affect reply delivery, not session routing.
+- `--json` keeps stdout reserved for the JSON response. Gateway, plugin, and embedded-fallback diagnostics are routed to stderr so scripts can parse stdout directly.
+- Embedded fallback JSON includes `meta.transport: "embedded"` and `meta.fallbackFrom: "gateway"` so scripts can distinguish fallback runs from Gateway runs.
+- If the Gateway accepts an agent run but the CLI times out waiting for the final reply, embedded fallback uses a fresh explicit `gateway-fallback-*` session/run id and reports `meta.fallbackReason: "gateway_timeout"` plus the fallback session fields. This avoids racing the Gateway-owned transcript lock or silently replacing the original routed conversation session.
+- When this command triggers `models.json` regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, `secretref-env:ENV_VAR_NAME`, or `secretref-managed`), not resolved secret plaintext.
+- Marker writes are source-authoritative: Nodmix persists markers from the active source config snapshot, not from resolved runtime secret values.
+
+## JSON delivery status
+
+When `--json --deliver` is used, the CLI JSON response may include top-level `deliveryStatus` so scripts can distinguish delivered, suppressed, partial, and failed sends:
+
+```json
+{
+  "payloads": [{ "text": "Report ready", "mediaUrl": null }],
+  "meta": { "durationMs": 1200 },
+  "deliveryStatus": {
+    "requested": true,
+    "attempted": true,
+    "status": "sent",
+    "succeeded": true,
+    "resultCount": 1
+  }
+}
+```
+
+`deliveryStatus.status` is one of `sent`, `suppressed`, `partial_failed`, or `failed`. `suppressed` means delivery was intentionally not sent, for example a message-sending hook cancelled it or there was no visible result; it is still a terminal no-retry outcome. `partial_failed` means at least one payload was sent before a later payload failed. `failed` means no durable send completed or delivery preflight failed.
+
+Gateway-backed CLI responses also preserve the raw Gateway result shape, where the same object is available at `result.deliveryStatus`.
+
+Common fields:
+
+- `requested`: always `true` when the object is present.
+- `attempted`: `true` after the durable send path ran; `false` for preflight failures or no visible payloads.
+- `succeeded`: `true`, `false`, or `"partial"`; `"partial"` pairs with `status: "partial_failed"`.
+- `reason`: a lowercase snake-case reason from durable delivery or preflight validation. Known reasons include `cancelled_by_message_sending_hook`, `no_visible_payload`, `no_visible_result`, `channel_resolved_to_internal`, `unknown_channel`, `invalid_delivery_target`, and `no_delivery_target`; failed durable sends may also report the failed stage. Treat unknown values as opaque because the set can expand.
+- `resultCount`: number of channel send results when available.
+- `sentBeforeError`: `true` when a partial failure sent at least one payload before the error.
+- `error`: boolean `true` for failed or partial-failed sends.
+- `errorMessage`: included only when an underlying delivery error message is captured. Preflight failures carry `error` and `reason` but no `errorMessage`.
+- `payloadOutcomes`: optional per-payload results with `index`, `status`, `reason`, `resultCount`, `error`, `stage`, `sentBeforeError`, or hook metadata when available.
+
+## Related
+
+- [CLI reference](/cli)
+- [Agent runtime](/concepts/agent)