@sjawhar/opencode-legion-envoy 6.4.2 → 6.5.1

package/skills/dispatch/references/asks.md

@@ -7,11 +7,8 @@ thread. Whether to ask at all, and how to write the question, is "Before you ask
 
 ## Who answers an ask
 
-An ask goes to the issue's assignee: their Inbox opens on **Mine**, which lists asks on the issues they hold plus an Unassigned band; an ask on an unassigned issue waits in that band for someone to take it. Find out who Dispatch takes you for with:
-```ts
-dispatch_whoami({})
-```
-It returns `details` `{ session, owner, service }`: `owner` is the lowercase email of the person whose personal token you run under, or `null` under the shared token or a verified service token, in which case `service` is that token's subject (`system:serviceaccount:<namespace>:<name>`, `null` otherwise) and every write you make is rendered `(as <namespace>/<name>)` — the namespace is kept because every namespace has a `default` service account, and a subject that is not a Kubernetes one is shown whole. An issue you create without `assignee` goes to your owner; with no owner it inherits its parent's assignee, or stays unassigned without a parent. If an issue you are asking on is unassigned and the answer matters, assign it to your owner (`PATCH /api/v1/issues/{key}` with `{"assignee": "<email>"}`; any authenticated caller may reassign, and an email nobody has signed in with is refused with `ASSIGNEE_NOT_ALLOWED`) or name in the question who should answer it. Never reassign an issue a human holds to get an answer faster: that is the human's call.
+An ask goes to the issue's assignee: their Inbox opens on **Mine**, which lists asks on the issues they hold plus an Unassigned band; an ask on an unassigned issue waits in that band for someone to take it. Find out who Dispatch takes you for with `dispatch whoami`.
+It prints whom the session acts for: the lowercase email of the person whose personal token you run under, or, under the shared token or a verified service token, that it has no owner — naming the service as `<namespace>/<name>` for a service token (`system:serviceaccount:<namespace>:<name>`), which is also how every write you make is rendered (`(as <namespace>/<name>)`) — the namespace is kept because every namespace has a `default` service account, and a subject that is not a Kubernetes one is shown whole. An issue you create without `--assignee` goes to your owner; with no owner it inherits its parent's assignee, or stays unassigned without a parent. If an issue you are asking on is unassigned and the answer matters, assign it to your owner (`PATCH /api/v1/issues/{key}` with `{"assignee": "<email>"}`; any authenticated caller may reassign, and an email nobody has signed in with is refused with `ASSIGNEE_NOT_ALLOWED`) or name in the question who should answer it. Never reassign an issue a human holds to get an answer faster: that is the human's call.
 
 ## Handing a human a to-do, editing, resolving, and replying
 
@@ -20,41 +17,28 @@ A to-do handed to a human still follows the question and options contract that `
 answer. There is no fixed vocabulary and the server treats no label specially.
 If an outcome needs a reason, say so in that option's description, and the human's free-text answer
 carries it:
-```ts
-dispatch_ask({
-  issue: "DSP-42",
-  question:
-    "The verified fix remains unavailable in production because deployment is pending. Deploying changes production and could expose a deployment problem. How should we proceed? Recommendation: deploy the verified fix now because it restores the intended behavior.",
-  options: [
-    { label: "Deploy the verified fix", description: "Restores the fix but can expose a deployment problem." },
-    { label: "Hold the deploy", description: "Avoids a production change now but leaves production without the fix." },
-  ],
-})
+```bash
+dispatch ask --issue DSP-42 \
+  --question 'The verified fix remains unavailable in production because deployment is pending. Deploying changes production and could expose a deployment problem. How should we proceed? Recommendation: deploy the verified fix now because it restores the intended behavior.' \
+  --option 'Deploy the verified fix: Restores the fix but can expose a deployment problem.' \
+  --option 'Hold the deploy: Avoids a production change now but leaves production without the fix.'
 ```
 
-Correct or refine an open ask in place instead of opening a second question:
-```ts
-dispatch_edit_ask({
-  ask,
-  question?,
-  options?: { label, description? }[],
-  multiple?,
-  urgency?,
-})
-```
-At least one field besides `ask` is required. Use this only while the same decision remains open: it keeps the prior text in the event
+Correct or refine an open ask in place instead of opening a second question, with
+`dispatch edit-ask --ask <id>` and any of `--question`, `--option` (repeated), `--multiple` and `--urgency`.
+At least one of them is required. Use this only while the same decision remains open: it keeps the prior text in the event
 log and invalidates any answer draft against the prior `edited_at` revision, so the human sees the new wording and explicitly reconfirms.
 An answered or resolved ask cannot be edited. If the decision is moot or superseded, retract the old ask and open a new one.
 A human can change an answer they gave. The change arrives as another `ask.answered` frame whose
 `previous_answer` names the answer it replaced, through the same route the first answer took, and
-`dispatch_read` of the ask lists every earlier answer. Act on the newest answer.
+`dispatch read --ref dispatch://KEY/ask/<id>` lists every earlier answer. Act on the newest answer.
 
-An ask that lives as an `ask` block in a document keeps its question and options in the block, and `dispatch_edit_ask` writes the
-block along with the row, so the edit stands and the document reads the same. It changes only the fields you name: pass `urgency`
-alone and the question's own wording, formatting, links and comment anchors are untouched. Pass `question` or `options` and that part
+An ask that lives as an `ask` block in a document keeps its question and options in the block, and `dispatch edit-ask` writes the
+block along with the row, so the edit stands and the document reads the same. It changes only the fields you name: pass `--urgency`
+alone and the question's own wording, formatting, links and comment anchors are untouched. Pass `--question` or `--option` and that part
 is rewritten, so anchors inside the text you replaced move as they would for any document edit. Either way it is a document edit: it
 writes a new version, which on a spec awaiting approval closes the design gate until the new version is approved. Editing the block
-with `dispatch_doc_edit` works too and is the way to change anything else about it, including adding formatting to a question.
+with `dispatch doc-edit` works too and is the way to change anything else about it, including adding formatting to a question.
 Re-sending a field unchanged rewrites nothing, so retrying the whole ask is safe.
 Text the block cannot carry back unchanged is refused outright, naming the field and writing nothing - an option label containing
 `": "`, the separator between a label and its description, is one example of text that cannot survive the round trip. Blank lines separate paragraphs;
@@ -62,51 +46,47 @@ a single newline is kept as a line break.
 
 An ask stays open until a human answers, unless its question no longer needs that answer. Retract a moot or superseded question, or
 self-resolve one after finding the answer:
-```ts
-dispatch_resolve_ask({
-  ask,
-  kind: "retracted",
-  reason: "A newer ask supersedes this question.",
-})
+```bash
+dispatch resolve-ask --ask <id> --kind retracted --reason 'A newer ask supersedes this question.'
 ```
 Use `retracted` when the question is obsolete and `resolved` when you found the answer. Include the reason because the question remains
 in its Conversation card and reply thread; a reason beginning `removed from the document in version` is refused, because that is how a
 retraction the document's own settlement wrote is recognised. Resolving a block ask records it in the block too, so it stays resolved
-however the document moves afterwards. `dispatch_doc_edit` refuses deleting the block of an open ask; a block removed another way, by a
-whole-document `dispatch_artifact` replace or by a person in the browser, closes its ask, and putting the block back reopens it. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
-resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `reply_to_ask` on
-`dispatch_comment` (mutually exclusive with `reply_to`).
-A review comment you opened has its own closer, `dispatch_resolve_comment` — see
+however the document moves afterwards. `dispatch doc-edit` refuses deleting the block of an open ask; a block removed another way, by a
+whole-document `dispatch artifact` replace or by a person in the browser, closes its ask, and putting the block back reopens it. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
+resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `--reply-to-ask` on
+`dispatch comment` (mutually exclusive with `--reply-to`).
+A review comment you opened has its own closer, `dispatch resolve-comment` — see
 [Comments and suggestions](skill://dispatch/references/documents.md).
 
 A human answers or asks back from the same field; a question-shaped free-text answer is offered as a clarification first. A human
 reply while your ask is still open (the delivered `comment.created` carries `ask_state: open`) is a request for clarification, not
 an answer: the human did not understand the question or needs more before choosing. The ask now waits on you in their Inbox. Answer
-in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with `dispatch_edit_ask` when the wording
+in the same thread with `dispatch comment --reply-to-ask <id>`, or reword the question itself with `dispatch edit-ask` when the wording
 was the problem; either puts the ask back in front of them. Do not open a second ask.
 
 Every reply to an open ask says whose turn it is next, and the Inbox files the ask by that, not by who spoke last. Your plain reply
-(`turn` omitted, or `turn: "human"`) hands the turn to the human: the ask returns to their `Waiting on you`. When you are not done
+(`--turn` omitted, or `--turn human`) hands the turn to the human: the ask returns to their `Waiting on you`. When you are not done
 yet — "dispatched two auditors, back with results", "checking the release branch, back shortly", any working-on-it note — reply with
-`turn: "agent"`: the note lands in the thread, the ask stays under `Waiting on agents`, and the human is not told to act. Use
-`turn: "agent"` for every progress note and `turn: "human"` (the default) only when you need them. A human's reply always hands the
-turn to you. The result names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
+`--turn agent`: the note lands in the thread, the ask stays under `Waiting on agents`, and the human is not told to act. Use
+`--turn agent` for every progress note and `--turn human` (the default) only when you need them. A human's reply always hands the
+turn to you. The output names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
 `ask_waiting_on`, and every ask read carries it as `waiting_on`.
 
 ## Following
 
 An ask has followers: every session that wrote to it — the session that opened it and every session that replied with
-`dispatch_comment({ reply_to_ask })` — plus any session a human adds from the ask card. The ask's answer, edits, resolution, and
+`dispatch comment --reply-to-ask` — plus any session a human adds from the ask card. The ask's answer, edits, resolution, and
 every reply on it reach each follower's own agent topic directly, whether or not the writer was a human and whatever the issue's
-route. The tool result says so (`You follow this ask: its answer and replies reach you directly.`) and carries `details.follows.ask`;
-the host tells you once per ask. Leave a thread you no longer need, or rejoin one, with:
+route. The output says so (`You follow this ask: its answer and replies reach you directly.`) once per ask.
+Leave a thread you no longer need, or rejoin one, with:
 
-```ts
-dispatch_follow({ ask, action: "follow" | "unfollow" })
+```bash
+dispatch follow --ask <id> --action unfollow   # or --action follow
 ```
 
-`ask` is the full ask id or a `dispatch://KEY/ask/<id>` reference; `dispatch_follow`, `dispatch_edit_ask`, and
-`dispatch_resolve_ask` also take an 8+ hex prefix that is unique among your own open asks, and refuse anything shorter by naming
+`--ask` is the full ask id or a `dispatch://KEY/ask/<id>` reference; `dispatch follow`, `dispatch edit-ask`, and
+`dispatch resolve-ask` also take an 8+ hex prefix that is unique among your own open asks, and refuse anything shorter by naming
 those asks. A human may also remove you from the ask card; either way you are
 told with an `ask.follower_removed` notice, and a human adding you arrives as `ask.follower_added`.
 

package/skills/dispatch/references/document-edits.md

@@ -1,16 +1,19 @@
 # Editing a document
 
-Every document a Dispatch tool writes — an issue's spec, a project document — is edited in place
-with `dispatch_doc_edit`, never re-uploaded. "The Spec" in `skill://dispatch` sends you here for
-the tool's shape, how to target the text you mean, what each operation costs a block, and how to
+Every document Dispatch holds — an issue's spec, a project document — is edited in place
+with `dispatch doc-edit`, never re-uploaded. "The Spec" in `skill://dispatch` sends you here for
+the command's shape, how to target the text you mean, what each operation costs a block, and how to
 reject a stale edit.
 
-```ts
-dispatch_doc_edit({ issue?, project?, artifact, ops, precondition?, summary? })
+```bash
+dispatch doc-edit --issue <KEY> --artifact spec --summary '<names the version>' --ops-json-file - <<'EOF'
+[{"op": "replace", "find": "old sentence", "with": "new sentence"}]
+EOF
 ```
-It returns issue or project-document owner details plus `applied`, optional `version`, `changed`,
-`unchanged_ops`, `lost_ops`, and the document token this edit produced, rendered as a
-`Document token: <token>` line. `ops` is an array of this exact `EditOp` shape:
+`--project` replaces `--issue` for a project document, and `--precondition-json` guards against a
+stale edit (below). It prints whether the edit applied, the version it wrote, which operations
+changed nothing (`unchanged_ops`) or were lost to a concurrent change (`lost_ops`), and the document
+token this edit produced, as a `Document token: <token>` line. The ops are a JSON array of this exact `EditOp` shape:
 
 ```ts
 type EditOp = {
@@ -28,8 +31,8 @@ type EditOp = {
 };
 ```
 
-An operation takes only these keys. A key it does not declare is refused before the call leaves
-your process, naming the operation and its keys, because every key but `op` is optional: a
+An operation takes only these keys. A key it does not declare is refused before the command sends
+anything, naming the operation and its keys, because every key but `op` is optional: a
 misspelled `with` would otherwise be dropped and the `replace` would delete the text you meant to
 rewrite.
 
@@ -93,7 +96,7 @@ paragraph is stored `\---`, not a rule, so to add a rule, `insert` it beside the
 `***`). A CR LF or a lone carriage return in any text you write - an insert's markdown, a `with` in text or in code,
 a suggestion, an upload or a spec - is stored as a line feed, as the browser editor reads both. Use zero-based
 `occurrence` for a
-repeated target; re-read a missing or ambiguous target before retrying. Pass `summary` to name the version when recording a decision.
+repeated target; re-read a missing or ambiguous target before retrying. Pass `--summary` to name the version when recording a decision.
 
 **Rewriting several paragraphs is one `replace` per paragraph, then a read-back.** `replace` is inline:
 each `with` is the new text of one paragraph, and outside a code block a `with` that forms two paragraphs is
@@ -131,17 +134,17 @@ the old block's place is it a `delete` of the old block and then an `insert` of
 block before or after it. The delete is what costs the id (below); a typed block keeps its id when the insert
 carries it, which works only in that order, because an insert carrying an id the document still holds is refused.
 The tools refuse a `delete` or `retype` that would take out an `ask` block whose ask is still open, delete-then-insert included:
-reword it with `replace`, relocate it with `move`, or change its question, options, urgency or `multiple` with `dispatch_edit_ask` if you asked it. A single
+reword it with `replace`, relocate it with `move`, or change its question, options, urgency or `multiple` with `dispatch edit-ask` if you asked it. A single
 batch that moves an open block out of a container and then deletes the container is refused; make them two calls (the check reads
 the document as it stood before the batch).
 Then read the document back with
-`dispatch_doc_read` and read the passage and its neighbours, not a grep for the words you added: an empty
+`dispatch doc-read` and read the passage and its neighbours, not a grep for the words you added: an empty
 `with` deletes the matched text on purpose, so a `replace` whose `with` you meant to fill
 empties that paragraph — the block and its id stay, holding nothing — and only a read shows what the document now says.
 
 A batch that leaves the document's semantic identity unchanged — including its inline anchor marks, so an edit that only orphans a
 comment or ask anchor still mints its version — mints no version, named or not: the response carries
-`changed: false` with `unchanged_ops` naming each operation that did nothing, and the tool result says nothing changed. A `summary`
+`changed: false` with `unchanged_ops` naming each operation that did nothing, and the output says nothing changed. A `--summary`
 does not force a version for such a batch; `POST /api/v1/artifacts/<id>/versions`, which names the current state on purpose, still does.
 
 A `delete` whose `find` is a block's entire text removes the block itself — the bullet, paragraph, or heading, not just its words — and
@@ -165,11 +168,11 @@ whose anchor lies inside the moved block, or a delete that would leave a typed b
 `INVALID_OP` naming the field and the rule.
 
 `GET /api/v1/artifacts/<artifact UUID>/blocks` includes a full-state `token` on every block, including
-inline marks. To reject a stale edit, pass `precondition` with exactly one of
-`{ document: "<document token>" }` or
-`{ blocks: [{ id: "<block id>", token: "<block token>" }] }`. A document token comes from
-`dispatch_doc_read` or from the previous `dispatch_doc_edit`, whose result carries the token its
-own edit produced: a run of guarded edits passes each result's token to the next one and reads the
+inline marks. To reject a stale edit, pass `--precondition-json` with exactly one of
+`{"document": "<document token>"}` or
+`{"blocks": [{"id": "<block id>", "token": "<block token>"}]}`. A document token comes from
+`dispatch doc-read` or from the previous `dispatch doc-edit`, whose output carries the token its
+own edit produced: a run of guarded edits passes each output's token to the next one and reads the
 document once, not once per edit. The server resolves the whole batch before
 mutation: a block guard must cover every content block it changes, or Dispatch returns
 `400 INVALID_PRECONDITION` without applying anything. Use a document token for insert and move because they
@@ -197,6 +200,6 @@ an existing paragraph is the question that should become a decision.
 
 An ask block has two ids: the block id, shown as `:::ask{#<id> …}` in the rendered document and
 taken bare by `move`/`delete` in `block` (the `block:<id>` form is only for `before`/`after`
-anchors), and the ask id, which `dispatch_open_asks`, the dashboard's ask links (`/asks/<id>`,
-`?ask=`), `dispatch_read` and `dispatch_comment({ reply_to_ask })` use. They differ;
+anchors), and the ask id, which `dispatch open-asks`, the dashboard's ask links (`/asks/<id>`,
+`?ask=`), `dispatch read` and `dispatch comment --reply-to-ask` use. They differ;
 `dispatch://KEY/ask/<block-id>` answers `not found`.

package/skills/dispatch/references/documents.md

@@ -15,7 +15,7 @@ Dispatch writes its fences that way. An unclosed typed block at document level i
 opening line that continues a paragraph instead of standing on its own (indented four or more
 columns under the paragraph's text) is refused, naming the line's number and text - `INVALID_OP` on an edit's `markdown` or `with`, `INVALID_MARKDOWN` on any other write - since it
 would be stored as the paragraph's text; start the block on its own line. An opening written inside
-a line is stored as text, and `dispatch_issue` and `dispatch_artifact` quote it back as a
+a line is stored as text, and `dispatch issue` and `dispatch artifact` quote it back as a
 typed-block opening that is text, not a block. For
 a new typed block, omit `#block-id`; Dispatch mints it. When editing an existing typed block, retain
 its id and every rendered attribute. Never copy an existing block's id into new markdown: an id
@@ -24,9 +24,9 @@ outside the text it replaces is refused naming the id: `INVALID_OP` for an inser
 `INVALID_MARKDOWN` for any other write. To rewrite such a block whole, `delete` it and then
 `insert` the new one carrying its id, anchored on the block before or after it, in that order and
 in one batch: an insert carrying an id the document still holds is refused. An `ask` block whose ask
-is still open cannot be rewritten that way: the tools refuse the `delete`, so reword it with
+is still open cannot be rewritten that way: `dispatch doc-edit` refuses the `delete`, so reword it with
 `replace`, relocate it with `move`, or change its question, options, urgency or `multiple` with
-`dispatch_edit_ask` if you asked it ([Editing a document](skill://dispatch/references/document-edits.md)).
+`dispatch edit-ask` if you asked it ([Editing a document](skill://dispatch/references/document-edits.md)).
 
 Use only the type names, content rule, attributes, and enum values returned by the schema. Values are
 quoted: `:::callout{kind="warning" title="Risk"}`. Do not write Pandoc-style `::: {.callout}`, leaf
@@ -55,67 +55,67 @@ unknown cost before production while keeping today's release possible.
 ```
 
 When a human answers a decision written as an ask block, the answer lives on that ask. Use
-`dispatch_resolve_ask` when the decision is resolved without a human response, or preserve the
+`dispatch resolve-ask` when the decision is resolved without a human response, or preserve the
 human's answer; never rewrite the question into its answer or blank its options. An edit that leaves
 an ask block without a question or with a blank option is rejected with `INVALID_ASK_BLOCK`.
 
-When `dispatch_issue` or `dispatch_artifact` answers `This spec holds no ask blocks …`, read it as a
+When `dispatch issue` or `dispatch artifact` answers `This spec holds no ask blocks …`, read it as a
 question: either no decision is needed and you say nothing, or you forgot to make it a block. When
 it answers `… typed-block openings in this document are text, not blocks`, the quoted openings are
 blocks stored as prose (inside a line, or a paste with something before every line): fix the markdown
 and upload again; a mention on purpose belongs in code. Neither answer sees a spec wrapped whole in a
 code fence (take the fence off), a malformed opening inside a line (`::ask{`, `:::ask {`: an ask opens
-only as `:::ask{…}` on a line of its own), or any `dispatch_doc_edit`: after an edit that writes an
-ask, `dispatch_doc_read` the section and check it renders as `:::ask{#<id> …}` on its own line.
+only as `:::ask{…}` on a line of its own), or any `dispatch doc-edit`: after an edit that writes an
+ask, `dispatch doc-read` the section and check it renders as `:::ask{#<id> …}` on its own line.
 
 ## Comments and suggestions
 
-Add feedback with:
+Add feedback with `dispatch comment` (`dispatch comment --help` lists its flags):
 
-```ts
-dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask?, turn? })
+```bash
+dispatch comment --issue <KEY> --artifact spec --quote '<the passage>' --body '<the question or note>'
 ```
 
-It returns issue or project-document owner details plus `comment`; a `reply_to_ask` reply also returns `ask` and `follows: { ask }`,
-because replying to an ask makes you one of its followers (see [Following](skill://dispatch/references/asks.md)).
-`ref` names the owner (an issue or project-document reference) in place of `issue`/`project`.
-`quote` requires `artifact`; its anchor is pinned to the containing block while retaining the quote
-for display. Omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no
-`quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server keeps
+It prints the comment's id; a `--reply-to-ask` reply also makes you one of the ask's followers
+(see [Following](skill://dispatch/references/asks.md)).
+`--ref` names the owner (an issue or project-document reference) in place of `--issue`/`--project`.
+`--quote` requires `--artifact`; its anchor is pinned to the containing block while retaining the quote
+for display. Omit both for a floating issue comment. A reply (`--reply-to`/`--reply-to-ask`) takes no
+`--quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server keeps
 threads flat. A reply to a resolved thread reopens it, except a decided suggestion's: a reply joins
-that thread and the suggestion stays accepted or rejected. Use `reply_to_ask` to reply directly under a
-question asked with `dispatch_ask`; `turn` (only with `reply_to_ask`) says who holds the turn after
+that thread and the suggestion stays accepted or rejected. Use `--reply-to-ask` to reply directly under a
+question asked with `dispatch ask`; `--turn` (only with `--reply-to-ask`) says who holds the turn after
 the reply — `agent` for a progress note that keeps the ask waiting on you, `human` (the default) when
 the human needs to act; see "Asking" in `skill://dispatch`. Comments are edited only by their author from the
 dashboard. A delivered `comment.created` event carries the comment `id`; reply to it with
-`dispatch_comment({ reply_to: <id> })`.
+`dispatch comment --reply-to <id>`.
 
 Resolve your own review comment once you have addressed it:
 
-```ts
-dispatch_resolve_comment({ comment })
+```bash
+dispatch resolve-comment --comment <id>
 ```
 
-`comment` is the comment id, or a `dispatch://KEY/comment/<id>` or `dispatch://PROJECT/artifact/<slug>/comment/<id>` reference (an
-8+ character id prefix is resolved against the owner's comments). It returns the owner details plus `comment`, and takes no reason —
-say what you did in a `reply_to` first if the thread needs it. The server lets any session or human resolve any open comment, so
+`--comment` is the comment id, or a `dispatch://KEY/comment/<id>` or `dispatch://PROJECT/artifact/<slug>/comment/<id>` reference (an
+8+ character id prefix is resolved against the owner's comments). It takes no reason —
+say what you did in a `--reply-to` first if the thread needs it. The server lets any session or human resolve any open comment, so
 resolve only threads you opened or were asked to close; reopening a resolved thread is human-only (from the dashboard), though your
 reply to it reopens it - except a decided suggestion's, which your reply joins and leaves accepted or rejected. A reply to a pending
-suggestion whose text an edit removed lands as well. Asks are closed with `dispatch_resolve_ask` instead.
+suggestion whose text an edit removed lands as well. Asks are closed with `dispatch resolve-ask` instead.
 
-An exact replacement for document text is a suggestion (`dispatch_suggest`), never a comment; a
+An exact replacement for document text is a suggestion (`dispatch suggest`), never a comment; a
 comment is for a question or a note the human answers in words. A human accepts a suggestion with
 one click and cannot accept a comment, so propose the replacement instead of describing it:
 
-```ts
-dispatch_suggest({ issue?, project?, artifact, ref?, quote, replace_with, body?, occurrence? })
+```bash
+dispatch suggest --issue <KEY> --artifact spec --quote '<exact text>' --replace-with '<replacement>'
 ```
 
-It returns issue or project-document owner details plus `comment`. A human accepts or rejects a suggestion.
-Errors: `TARGET_AMBIGUOUS` (add `occurrence`), `TARGET_NOT_FOUND` (re-read first), `INVALID_ANCHOR`/`ANCHOR_MISSING`/`ANCHOR_ORPHANED`
+It prints the suggestion's id; `--body` adds a note and `--occurrence` picks a repeated quote. A human accepts or rejects a suggestion.
+Errors: `TARGET_AMBIGUOUS` (add `--occurrence`), `TARGET_NOT_FOUND` (re-read first), `INVALID_ANCHOR`/`ANCHOR_MISSING`/`ANCHOR_ORPHANED`
 (bad, unwritten, or stale quote), `INVALID_MARKDOWN`/`DOC_SCHEMA` (malformed content), `CAP_EXCEEDED`, `ISSUE_CLOSED`.
 Suggest only what the quoted block can hold. The accept, not the suggestion, checks that: an
-accept whose `replace_with` would break an ask block that was readable before it is refused with
+accept whose replacement would break an ask block that was readable before it is refused with
 `INVALID_ASK_BLOCK` - a question given a code block, text after an ask's options, a second option
 list, or an emptied question; one that names an id the document holds outside the text it
 replaces, an ask under a held id included, with `INVALID_MARKDOWN`; and one no part of the
@@ -127,51 +127,54 @@ stays open until someone rejects or replaces it.
 
 Attach an image, diagram, or local file with:
 
-```ts
-dispatch_artifact({ issue?, project?, name, path, summary? })
+```bash
+dispatch artifact --issue <KEY> --name diagram.png --path ./diagram.png
 ```
 
-Or, when the text is already in the call, post a Markdown document directly:
+Or, when the text is already at hand, post a Markdown document directly:
 
-```ts
-dispatch_artifact({ issue?, project?, name: "load-test-results.md", content: "# Load test\n..." })
+```bash
+dispatch artifact --issue <KEY> --name load-test-results.md --content-file - <<'EOF'
+# Load test
+...
+EOF
 ```
 
-Exactly one of `issue` and `project` is required. A project upload creates an unlinked project document; it must not include `artifact`.
-Exactly one of `path` and `content` is required. It returns issue or project-document owner details plus `artifact` and `version`.
-Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
-with your text. Never do that: the spec is edited in place with `dispatch_doc_edit` (see [Editing a document](skill://dispatch/references/document-edits.md)). Address an existing
-artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
+Exactly one of `--issue` and `--project` is required. A project upload creates an unlinked project document; it takes no `--artifact`.
+Exactly one of `--path` and `--content` is required. It prints the document's slug and version.
+Uploading the same `--name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
+with your text. Never do that: the spec is edited in place with `dispatch doc-edit` (see [Editing a document](skill://dispatch/references/document-edits.md)). Address an existing
+artifact by the slug the upload printed or by its filename, and a project document by its artifact id, slug, or filename; the
 slug also arrives on `artifact.created` events. Dispatch suffixes a slug two documents would share, so one document's
 filename can be another's slug (`plan v2` takes `plan-v2`, then a document named `plan-v2` takes `plan-v2-2`): a bare
-`artifact` that names both is refused with each one's id, while a `dispatch://` reference's document part is always the slug.
+`--artifact` that names both is refused with each one's id, while a `dispatch://` reference's document part is always the slug.
 
-A picture meant to be seen inline in a message, comment or ask is not uploaded with `dispatch_artifact`: pass its local
-path in that tool's `images` (PNG, JPEG, GIF or WebP by its bytes, at most 25 MiB each). Each is uploaded to the issue (a
+A picture meant to be seen inline in a message, comment or ask is not uploaded with `dispatch artifact`: pass its local
+path with that command's `--image`, once per picture (PNG, JPEG, GIF or WebP by its bytes, at most 25 MiB each). Each is uploaded to the issue (a
 project document's project; for a reply to a direct message, your own conversation) and appended after a blank line as
 one `![<file name>](dispatch://<owner>/artifact/<slug>@vN)` line, about 60 characters that count toward the body or
-question cap; a call the lines would carry over the cap is refused with the count before anything uploads, and again,
+question cap; a command the lines would carry over the cap is refused with the count before anything uploads, and again,
 with nothing posted, in the rare case where Dispatch gives an upload a longer address than that (a later version of a
 name the owner already holds, or a slug another file took first). The `@vN` pins the version the upload made (the same
 file name again makes the next version). A plain `dispatch://KEY/artifact/<slug>` reference to an image stays a link
 with a thumbnail.
 
-`dispatch_read` hands you the pictures the messages, asks and comments it shows embed, newest first, at most 8 and
-10 MiB per read, and its `Pictures:` section names each one shown, in order, and the rest by reference for
-`dispatch_doc_read`, which shows one picture (at most 3,750,000 bytes, the 5 MB of base64 a model provider takes; a
-larger one or an SVG is described). A picture in a
+`dispatch read` writes the pictures the messages, asks and comments it shows embed to files, newest first, at most 8 and
+10 MiB per read, prints a `- picture: <path>` line for each, and its `Pictures:` section names each one shown, in order, and the rest by reference for
+`dispatch doc-read`, which shows one picture (at most 3,750,000 bytes, the 5 MB of base64 a model provider takes; a
+larger one or an SVG is described). Open each written file with your file-read tool. A picture in a
 conversation on the Agents page belongs to that conversation, `dispatch://agent/<session id>/artifact/<slug>@vN`, and
-`dispatch_doc_read` reads it by that reference alone. On Oh My Pi an Inbox delivery carries its pictures the same way; in
+`dispatch doc-read` reads it by that reference alone. On Oh My Pi an Inbox delivery carries its pictures as images; in
 Claude Code it stays text with the reference.
 
 A session is shown each picture once. A later read or delivery that embeds a picture you were already shown names it in
 `Pictures:` as `shown earlier this session` and sends no bytes, since every request carries the session's whole history
-and a model provider refuses one over 32 MB; `dispatch_doc_read` always shows the picture, so ask it for one you need
+and a model provider refuses one over 32 MB; `dispatch doc-read` always shows the picture, so ask it for one you need
 again, after compaction too.
 
 Documents are CommonMark. A bare `<https://example.com|text>` is a CommonMark autolink and is normalised: the angle brackets are
 dropped and the URL keeps `|text`. A backslash-escaped `\<https://example.com|text>` displays as `<https://example.com|text>` in the
-document but comes back re-escaped (`\<`) from `dispatch_doc_read`. A Slack mrkdwn draft, or any other payload that is not Markdown,
+document but comes back re-escaped (`\<`) from `dispatch doc-read`. A Slack mrkdwn draft, or any other payload that is not Markdown,
 still belongs inside a fenced code block, where it survives verbatim both ways.
 
 A table cell ends at every `|` not written `\|`, inside inline code and links too, so write
@@ -184,27 +187,27 @@ of bare table rows `TABLE_WIDTH`, which names the cell counts only.
 
 ## Approval requests
 
-```
-dispatch_request_approval({ issue?, project?, artifact?, summary })
+```bash
+dispatch request-approval --issue <KEY> --summary '<what the human is approving>'
 ```
 
-The call opens an approval ask with the options `Approve` and `Request changes`, its question
-"Approve spec.md (version N)?" followed by `summary`, where N is the document's latest version. It
+The command opens an approval ask with the options `Approve` and `Request changes`, its question
+"Approve spec.md (version N)?" followed by the summary, where N is the document's latest version. It
 is refused, with nothing sent, while that version holds a decision block open, and the refusal
-names each block and its ask. An answer or a `dispatch_resolve_ask` closes the ask at once but
+names each block and its ask. An answer or a `dispatch resolve-ask` closes the ask at once but
 reaches a version only when the document settles, about two seconds later, or with your next
-`dispatch_doc_edit`: fold the answer into the text (or, for a waiver, write the human's decision
+`dispatch doc-edit`: fold the answer into the text (or, for a waiver, write the human's decision
 in) before you request. A block written in the last few seconds counts as open before Dispatch has
 opened its ask. A document holds one open request. A new version moves it to that version, keeping
 its thread and summary, and leaves it waiting on you, as a human's reply in its thread does; a move
-your own edit made sends you no event, and `dispatch_read` and `dispatch_doc_read` show it as
-`Approval: awaiting, waiting on agent`. Call again when "Approval of a spec" in `skill://dispatch`
-allows: that hands the same request back to the human, reworded first when `summary` is new. Your
-own reply in its thread hands it back too, with no call and the summary it already holds, unless
-you post it with `reply_to_ask` and `turn: "agent"` (`reply_to` carries no turn, so its reply takes
+your own edit made sends you no event, and `dispatch read` and `dispatch doc-read` show it as
+`Approval: awaiting, waiting on agent`. Run it again when "Approval of a spec" in `skill://dispatch`
+allows: that hands the same request back to the human, reworded first when `--summary` is new. Your
+own reply in its thread hands it back too, with no command and the summary it already holds, unless
+you post it with `--reply-to-ask` and `--turn agent` (`--reply-to` carries no turn, so its reply takes
 the default, `human`) or a new version has moved the request since your last
-`dispatch_request_approval`. While it waits on the human, a call with the same `summary` changes
-nothing, and one with a different `summary` is refused, since it would rewrite the card they are
+`dispatch request-approval`. While it waits on the human, the same `--summary` changes
+nothing, and a different `--summary` is refused, since it would rewrite the card they are
 reading. The answer reaches you as `artifact.approved` or `artifact.changes_requested` with the
 pinned `version` and closes the request, so the next call opens a new one; `changes_requested`
 carries the reason, which is your next piece of work. Those reads show the document's approval
@@ -213,18 +216,18 @@ state; `stale` means it was approved and then edited.
 ## A document that is reloading
 
 These calls can answer `DOC_SERVICE_UNAVAILABLE` (HTTP 503), because each writes a document inside its
-transaction: `dispatch_doc_edit`; `dispatch_ask` and `dispatch_comment` on a quote; a `dispatch_comment` reply
-in a thread whose first comment is anchored; `dispatch_suggest`; `dispatch_resolve_comment` on an anchored
-comment; `dispatch_artifact` replacing a document that already exists; and, on an ask that lives in a `:::ask`
-block, `dispatch_edit_ask` and `dispatch_resolve_ask`, which write that block. Creating an issue with a spec,
-uploading a new document, `dispatch_request_approval` and `dispatch_message` never answer it, and neither do
-`dispatch_edit_ask` and `dispatch_resolve_ask` on an ask that has no block. It means that document's live room
+transaction: `dispatch doc-edit`; `dispatch ask` and `dispatch comment` on a quote; a `dispatch comment` reply
+in a thread whose first comment is anchored; `dispatch suggest`; `dispatch resolve-comment` on an anchored
+comment; `dispatch artifact` replacing a document that already exists; and, on an ask that lives in a `:::ask`
+block, `dispatch edit-ask` and `dispatch resolve-ask`, which write that block. Creating an issue with a spec,
+uploading a new document, `dispatch request-approval` and `dispatch message` never answer it, and neither do
+`dispatch edit-ask` and `dispatch resolve-ask` on an ask that has no block. It means that document's live room
 failed and is reloading from its durable copy, so the server refused rather than wait for it; your call wrote
 nothing and the document is intact. Nothing retries it for you: the Dispatch client hands a 503 straight back.
 Wait a few seconds and make the same call again. A second refusal in a row is worth telling your human about,
 with the document's reference.
 
-`dispatch_doc_read` can answer it too, though it writes nothing: a read never opens a live room, and waits out
+`dispatch doc-read` can answer it too, though it writes nothing: a read never opens a live room, and waits out
 a room that is reloading, so it is refused only when the document's durable copy cannot be read or decoded.
 Retry it the same way.