@sjawhar/pi-envoy 8.4.0 → 8.6.0

package/dist/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/dist/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.
 

package/dist/skills/dispatch/references/examples.md

@@ -17,90 +17,60 @@ dashboard from the release. Waiting is safest, but the list above may be stale.
 After — write the decision into the document section it concerns: state the problem, and make each
 genuinely different option a button, so the answer stays with the release design:
 
-```ts
-dispatch_doc_edit({
-  issue: "LEGION-815",
-  artifact: "spec",
-  ops: [{
-    op: "insert",
-    after: "Release requires reviewed operator instructions before deployment.",
-    markdown: `:::ask{#release-gate urgency="high"}
-Release notes are unreviewed, and tomorrow's customer demo means the release cannot wait for a later review. How should we proceed? Recommendation: review the notes, then ship, to keep the release complete and reviewed.
-
-- Review notes, then ship: Delays release for review but keeps the release complete and reviewed.
-- Ship now: Meets the demo deadline but leaves the release notes unreviewed.
-:::`,
-  }],
-})
+```bash
+dispatch doc-edit --issue LEGION-815 --artifact spec --ops-json-file - <<'EOF'
+[{
+  "op": "insert",
+  "after": "Release requires reviewed operator instructions before deployment.",
+  "markdown": ":::ask{#release-gate urgency=\"high\"}\nRelease notes are unreviewed, and tomorrow's customer demo means the release cannot wait for a later review. How should we proceed? Recommendation: review the notes, then ship, to keep the release complete and reviewed.\n\n- Review notes, then ship: Delays release for review but keeps the release complete and reviewed.\n- Ship now: Meets the demo deadline but leaves the release notes unreviewed.\n:::"
+}]
+EOF
 ```
 
 Before — a progress note that nobody needs, posted where humans look for decisions:
 
-```ts
-dispatch_message({ issue: "LEGION-815", body: "Merged the release PR, moving to docs next." })
+```bash
+dispatch message --issue LEGION-815 --body 'Merged the release PR, moving to docs next.'
 ```
 
 After — nothing. The merge is visible on the pull request; the docs work shows up as its own deliverable. Post a message only when
 a human must act or a deliverable is theirs to use:
 
-```ts
-dispatch_message({
-  issue: "LEGION-815",
-  body: "Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.",
-})
+```bash
+dispatch message --issue LEGION-815 --body 'Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.'
 ```
 
 Before — a draft the human must read is uploaded as a separate file, the spec only names it, and
 the ask does not point at it, so the reader has to go looking:
 
-```ts
-dispatch_artifact({ issue: "OPS-52", name: "cu-update-2026-09-15.md", content: "Hi team, ..." })
-dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
-  { op: "insert", after: "## Context", markdown: "## Draft (artifact cu-update-2026-09-15.md)" },
-]})
-dispatch_ask({
-  issue: "OPS-52",
-  question:
-    "Customers need an update today, but the draft is only in a separate file, so the reader cannot review it in context. How should we proceed? Recommendation: put the draft in the spec before sending it.",
-  options: [
-    { label: "Put the draft in the spec", description: "Adds a spec edit before sending but lets the reader review it in context." },
-    { label: "Keep the separate file", description: "Saves the spec edit but leaves the reader to find the draft." },
-  ],
-})
+```bash
+dispatch artifact --issue OPS-52 --name cu-update-2026-09-15.md --content 'Hi team, ...'
+dispatch doc-edit --issue OPS-52 --artifact spec \
+  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft (artifact cu-update-2026-09-15.md)"}]'
+dispatch ask --issue OPS-52 \
+  --question 'Customers need an update today, but the draft is only in a separate file, so the reader cannot review it in context. How should we proceed? Recommendation: put the draft in the spec before sending it.' \
+  --option 'Put the draft in the spec: Adds a spec edit before sending but lets the reader review it in context.' \
+  --option 'Keep the separate file: Saves the spec edit but leaves the reader to find the draft.'
 ```
 
 After — the draft is a section of the spec, and the ask anchors there. Sending it is a to-do only a
 human can complete, so it stays a standalone ask. If it really must be a file, the spec and the ask
-both link the slug from the upload result:
-
-```ts
-dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
-  { op: "insert", after: "## Context", markdown: "## Draft\n\nHi team, ..." },
-]})
-dispatch_ask({
-  issue: "OPS-52",
-  question:
-    "Customers need an update today, and the reviewed text is ready in the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.",
-  options: [
-    { label: "Send the reviewed update", description: "Delivers the update today but makes its text external." },
-    { label: "Hold the update", description: "Avoids sending now but leaves customers without the update." },
-  ],
-  anchor: { artifact: "spec", quote: "Hi team," },
-})
-// or, for a real file — the spec links it where the reader needs it, and so does the ask:
-dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
-  { op: "insert", after: "## Context", markdown: "## Draft\n\nThe update to send: dispatch://OPS-52/artifact/cu-update-2026-09-15-md" },
-]})
-dispatch_ask({
-  issue: "OPS-52",
-  question:
-    "Customers need an update today, and its reviewed text is linked from the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.",
-  options: [
-    { label: "Send the reviewed update", description: "Delivers the linked update today but makes its text external." },
-    { label: "Hold the update", description: "Avoids sending now but leaves customers without the update." },
-  ],
-  ref: "dispatch://OPS-52/artifact/cu-update-2026-09-15-md",
-})
+both link the slug the upload printed:
+
+```bash
+dispatch doc-edit --issue OPS-52 --artifact spec \
+  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft\n\nHi team, ..."}]'
+dispatch ask --issue OPS-52 --anchor-json '{"artifact":"spec","quote":"Hi team,"}' \
+  --question 'Customers need an update today, and the reviewed text is ready in the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.' \
+  --option 'Send the reviewed update: Delivers the update today but makes its text external.' \
+  --option 'Hold the update: Avoids sending now but leaves customers without the update.'
+# or, for a real file — the spec links it where the reader needs it, and so does the ask:
+dispatch doc-edit --issue OPS-52 --artifact spec \
+  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft\n\nThe update to send: dispatch://OPS-52/artifact/cu-update-2026-09-15-md"}]'
+dispatch ask --issue OPS-52 --ref dispatch://OPS-52/artifact/cu-update-2026-09-15-md \
+  --question 'Customers need an update today, and its reviewed text is linked from the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.' \
+  --option 'Send the reviewed update: Delivers the linked update today but makes its text external.' \
+  --option 'Hold the update: Avoids sending now but leaves customers without the update.'
 ```
 
 ## Naming the mechanism
@@ -123,7 +93,7 @@ takes today: it calls `register_gate` on its `legion` tool, which posts to the d
 `POST /legion/v1/gates/register` route and names the spec document and the version that gate the
 tree. The daemon opens the gate when Dispatch emits `artifact.approved` for that document at that
 version, which Dispatch does when you click Approve on the request the architect opened with
-`dispatch_request_approval`. Without `register_gate`, the daemon reads the issue's primary
+`dispatch request-approval`. Without `register_gate`, the daemon reads the issue's primary
 document from Dispatch itself and waits for the same event.
 ```