@sjawhar/pi-envoy 8.4.0 → 8.6.0

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

@@ -37,17 +37,17 @@ reordering the board yourself.
 
 Before you start implementing an issue, claim it:
 
-```ts
-dispatch_claim({ issue: "LEGION-234" })                  // I am implementing this
-dispatch_claim({ issue: "LEGION-234", release: true })   // I have stopped; it is free
+```bash
+dispatch claim --issue LEGION-234             # I am implementing this
+dispatch claim --issue LEGION-234 --release   # I have stopped; it is free
 ```
 
 A claim records **your** session — the one making the call, never another — and shows on every
-read of the issue: the dashboard header, the issue list and board, `dispatch_read` (a
-`Claimed by:` line) and `dispatch_issues` (a claim on the row). A session's claim there ends
+read of the issue: the dashboard header, the issue list and board, `dispatch read` (a
+`Claimed by:` line) and `dispatch issues` (a claim on the row). A session's claim there ends
 `· not running` when the live agent registry does not list that session, as the dashboard's chip
 does — that claim is free to take — and `· liveness unknown` when the registry could not be read,
-which says nothing either way. `dispatch_issues` plus the dashboard's **Unclaimed** filter is how
+which says nothing either way. `dispatch issues` plus the dashboard's **Unclaimed** filter is how
 you find work nobody is on.
 
 - **`409 ISSUE_CLAIMED` means someone else holds this issue.** When it is another session, the
@@ -55,7 +55,7 @@ you find work nobody is on.
   that session (its id is in the message; `envoy_send` reaches it) or pick up something else,
   and tell the human if you believe the work should be yours. When a **human** holds it, the
   refusal names the person and says nothing about a session running, because there is none to
-  message: ask them with `dispatch_ask` instead, so the open ask appears in their Inbox, and
+  message: ask them with `dispatch ask` instead, so the open ask appears in their Inbox, and
   never assume their claim has lapsed — only a human releases or forces a human's claim.
 - **`409 CLAIM_CONTENDED` means the issue changed hands twice while your call ran**, so nothing
   was applied and nobody's liveness was checked. Read the issue and decide again; it is not a
@@ -71,8 +71,8 @@ you find work nobody is on.
 
 **Claiming and moving the status are two separate actions, and you do both.** A claim says which
 session is on the work; the status says where the work has got to, and humans use it to track
-that too. So when you start: `dispatch_claim({ issue })` **and**
-`dispatch_issue_update({ issue, status: "in_progress" })`.
+that too. So when you start: `dispatch claim --issue <KEY>` **and**
+`dispatch issue-update --issue <KEY> --status in_progress`.
 
 ## Issue status is yours to move
 
@@ -84,29 +84,29 @@ queue, `done` when the change has been driven in production (a merge is not `don
 issues you own as well as the root. An issue left at `triage` while work is underway is a defect.
 Waiting for the deploy lane is not a status and is never announced.
 
-```ts
-// PATCH /api/v1/issues/{key} — status, title, labels, priority, external_links (merged by URL), route, parent
-dispatch_issue_update({ issue: "PROJ-175", status: "testing" })
-dispatch_issue_update({ issue: "PROJ-175", status: "done", reason: "Shipped in owner/repo#7; verified on the production dashboard." })
-dispatch_issue_update({ issue: "PROJ-175", priority: 1 }) // 0–3; see Priority is yours to set
-dispatch_issue_update({ issue: "PROJ-175", external_links: ["https://github.com/owner/repo/pull/7"] })
-dispatch_issue_update({ issue: "PROJ-175", parent: "PROJ-170" }) // same-project key; "" clears the parent
+```bash
+# PATCH /api/v1/issues/{key} — status, title, labels, priority, external links (merged by URL), route, parent
+dispatch issue-update --issue PROJ-175 --status testing
+dispatch issue-update --issue PROJ-175 --status done --reason 'Shipped in owner/repo#7; verified on the production dashboard.'
+dispatch issue-update --issue PROJ-175 --priority 1   # 0–3; see Priority is yours to set
+dispatch issue-update --issue PROJ-175 --external-link https://github.com/owner/repo/pull/7
+dispatch issue-update --issue PROJ-175 --parent PROJ-170   # same-project key; --parent '' clears it
 ```
 
-Closing takes a `reason`, and the tool refuses `status: "done"` without one: it posts the reason on
+Closing takes a `--reason`, and the command refuses `--status done` without one: it posts the reason on
 the issue as a message, then closes it, because a closed issue refuses messages, comments, and
 artifacts, so a reason left for later has nowhere to go. When the close fails after the post, the
 error names the posted message; after a timeout or a server error it also says the close may have
 landed, so read the issue's status first. A retry points its reason at the posted message rather
 than repeating it.
 
-The two clears differ: `priority` clears with `null`, while `parent` and `route` clear with `""`.
-Guessing the other one is a refusal either way.
+The two clears differ: `--clear-priority` sends null, while `--parent ''` and `--route ''` clear with an
+empty string. Guessing the other one is a refusal either way.
 
-Link the pull request that delivers the issue in `external_links` when you open it; the issue page
-renders its state and checks from that link, and `dispatch_read` lists it under `External links:`.
-The call is authenticated with the same bearer as every
-other `dispatch_*` tool: a Legion pane reads it from the `DISPATCH_TOKEN_FILE` path the daemon sets on
+Link the pull request that delivers the issue with `--external-link` when you open it; the issue page
+renders its state and checks from that link, and `dispatch read` lists it under `External links:`.
+The command is authenticated with the same bearer as every
+other `dispatch` command: a Legion pane reads it from the `DISPATCH_TOKEN_FILE` path the daemon sets on
 the pane; an OMP session outside Legion reads `dispatch.token` from `~/.config/opencode/envoy.json`.
 
 A write to an issue still in `triage` answers once with `… is still in triage …`; move the status
@@ -120,39 +120,39 @@ lowest, and `null` clears it. Agents set it (`dispatch://LEGION/artifact/issue-s
 the human overrides anything they disagree with from the dashboard. A closed
 issue takes only `rank`, `components`, and a reopening `status` (any status but `done`);
 everything else, `priority` included, waits for the reopen (`409 ISSUE_CLOSED`). So reopen it
-first, then set the priority — the two cannot go in one call. `rank` itself is not a tool field:
+first, then set the priority — the two cannot go in one command. `rank` itself is not a flag:
 reorder it the way [Issue reads](#board-rank-priority-and-assignee-on-a-read) describes, through `PATCH /api/v1/issues/{key}`.
 
 ## Board rank, priority, and assignee on a read
 
-Issue reads include `rank`, the server-owned ordering key used by project boards; reorder through `PATCH /api/v1/issues/{key}` with `{"rank": {"before": "<key>", "after": "<key>"}}`, either neighbor optional and both in the issue's project. A bearer caller also names its own session in that body, `"actor": {"kind": "session", "id": "<your session id>"}`, or the server refuses with `ACTOR_KIND`. They also include nullable coarse priority (`P0` highest through `P3` lowest) and `assignee`: the lowercase email of the person who answers the issue's asks, or `null` when nobody holds it. `dispatch_read` of an issue prints it as `Assignee: <email>` or `Assignee: unassigned`.
+Issue reads include `rank`, the server-owned ordering key used by project boards; reorder through `PATCH /api/v1/issues/{key}` with `{"rank": {"before": "<key>", "after": "<key>"}}`, either neighbor optional and both in the issue's project. A bearer caller also names its own session in that body, `"actor": {"kind": "session", "id": "<your session id>"}`, or the server refuses with `ACTOR_KIND`. They also include nullable coarse priority (`P0` highest through `P3` lowest) and `assignee`: the lowercase email of the person who answers the issue's asks, or `null` when nobody holds it. `dispatch read` of an issue prints it as `Assignee: <email>` or `Assignee: unassigned`.
 
 ## Reading a project's backlog
 
 To see the shape of a project rather than find a phrase, list its issues:
-```ts
-dispatch_issues({ project, status?, parent?, label?, priority?, route_status?, updated_since?, limit?, offset? })
+```bash
+dispatch issues --project <KEY>
 ```
 Each row carries the issue key, title, status, priority, parent, labels, its open-ask count, and
-when it last changed — a roadmap or backlog pass without opening every issue. Filter with `status`
-(a lifecycle status), `parent` (one issue's children), `label`, `priority` (a list of `0`–`3`, with
-`null` for an issue with no priority: `[0, 1]` is every P0 and P1), `route_status` (below), or
-`updated_since` (an RFC3339 timestamp, for "what moved this week"). `limit` is the page size, 50 by
-default and 250 at most, and `offset` is where the page starts; the answer says how many issues
+when it last changed — a roadmap or backlog pass without opening every issue. Filter with `--status`
+(a lifecycle status), `--parent` (one issue's children), `--label`, `--priority` (repeated, `0`–`3`, with
+`none` for an issue with no priority: `--priority 0 --priority 1` is every P0 and P1), `--route-status` (below), or
+`--updated-since` (an RFC3339 timestamp, for "what moved this week"). `--limit` is the page size, 50 by
+default and 250 at most, and `--offset` is where the page starts; the output says how many issues
 match. Repeating with the next offset walks every matching issue only while the list does not
 change: an issue that enters or leaves what your filters match, or whose status or rank changes,
 between two pages shifts rows across a page boundary, and the walk then shows one issue twice and
 misses another.
 
-This is not search: it matches no text. Use `dispatch_search` for a keyword or phrase, and
-`dispatch_issues` when you want every issue in a project and its current state.
+This is not search: it matches no text. Use `dispatch search` for a keyword or phrase, and
+`dispatch issues` when you want every issue in a project and its current state.
 
 ### The owner audit
 
 As the owner of a surface, list the project's P0 and P1 issues and staff or close each one nobody
 has started:
-```ts
-dispatch_issues({ project, priority: [0, 1], limit: 250 })
+```bash
+dispatch issues --project <KEY> --priority 0 --priority 1 --limit 250
 ```
 Every unclaimed row in `triage`, `icebox`, `backlog` or `todo` is a decision: someone takes it and
 builds it, or it closes. A row in `in_progress`, `testing`, `needs_review` or `retro`, or one that
@@ -175,8 +175,8 @@ The audit finds four shapes:
 - **Unreachable route.** An open issue whose route names a role nobody holds, or a session that is
   not running, reaches nobody, whatever its priority, and the priority filter above never finds
   it. List it on its own:
-  ```ts
-  dispatch_issues({ project, route_status: "no_holder", limit: 250 })
+  ```bash
+  dispatch issues --project <KEY> --route-status no_holder --limit 250
   ```
   Each row reads `route role:sre (nobody holds it right now)` or `route session:<id> (that session
   is not running right now)`. That is one read of the listener, and one read cannot tell a
@@ -184,9 +184,9 @@ The audit finds four shapes:
   session is absent from the listener for minutes, and its role with it.
   So a route is unowned only when it is `no_holder` on two reads at least ten minutes apart: list
   again after ten minutes and act on the issues both lists name. Confirm with the second
-  `dispatch_issues` read, not `envoy_role_get`: a role lookup releases the claim of a holder whose
+  `dispatch issues` read, not `envoy_role_get`: a role lookup releases the claim of a holder whose
   session is absent from the registry as it answers. Then staff the role, re-route the
-  issue to a live holder, or clear the route and assign it. `route_status: "unknown"` means the
+  issue to a live holder, or clear the route and assign it. `--route-status unknown` means the
   listener did not answer, so a route could not be judged; a `no_holder` filter refuses rather
   than answer an empty list then.
 
@@ -195,19 +195,19 @@ are found by running the check, not by noticing them.
 
 ## Search paging
 
-`skill://dispatch` sends you here when a `dispatch_search` page is not enough: more hits remain,
+`skill://dispatch` sends you here when a `dispatch search` page is not enough: more hits remain,
 or a kind runs out before the page does.
 
-A page holds `limit` hits (20 by default, 50 at most); the first line names how many match
-(`showing 1-20 of 312`), and, while more can be reached, the last line names the next `offset`.
-Each kind lists at most its best 100, so when the result says the rest cannot be paged to, narrow
-the query or name a `project`.
+A page holds `--limit` hits (20 by default, 50 at most); the first line names how many match
+(`showing 1-20 of 312`), and, while more can be reached, the last line names the next `--offset`.
+Each kind lists at most its best 100, so when the output says the rest cannot be paged to, narrow
+the query or name a `--project`.
 
 ## Syncing a project's architecture model
 
 Import a project's architecture model from its configured source repository now (a human configures the source in Settings):
-```ts
-dispatch_architecture_sync({ project: "CORE" })
+```bash
+dispatch architecture-sync --project CORE
 ```
-It returns the imported commit, or the recorded error when the model was rejected — the previous model stays up. Without a configured source it answers 404 `SOURCE_NOT_FOUND`.
+It prints the imported commit, or the recorded error when the model was rejected — the previous model stays up. Without a configured source it answers 404 `SOURCE_NOT_FOUND`.
 

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

@@ -8,23 +8,19 @@ human messages you directly from the Agents page.
 A human — or any bearer caller over HTTP, such as a test rig — can target the issue message at a
 live Envoy session or role as **BTW**, **Aside**, or **Steer** (the dashboard calls a steer
 **Send**). The incoming Dispatch frame names
-the issue and includes a `reply_with` hint (`{ tool, args }`, ready to issue on any host); reply on the same open issue with the existing
-tool, never a new targeted send:
+the issue and includes a `reply_with` hint (`{ command }`, the `dispatch` command line that answers it, with `...` for
+the body); reply on the same open issue with that command, never a new targeted send:
 
-```ts
-dispatch_message({
-  issue: "CORE-1",
-  in_reply_to: "<targeted-message-id>",
-  body: "The requested answer.",
-})
+```bash
+dispatch message --issue CORE-1 --in-reply-to <targeted-message-id> --body 'The requested answer.'
 ```
 
-`in_reply_to` correlates the answer under the asker's message in its Conversation card. A BTW
+`--in-reply-to` correlates the answer under the asker's message in its Conversation card. A BTW
 delivery can post its answer automatically; use this call when the frame asks the primary agent to
 reply. A human may reply to your message in turn — the follow-up arrives as a targeted frame whose
 `in_reply_to` names your message and whose `reply_body` quotes it; answer it the same way,
-`dispatch_message({ issue, in_reply_to: "<their reply id>", body })`, so the exchange reads as one
-thread. `dispatch_message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
+`dispatch message --issue <KEY> --in-reply-to <their reply id> --body-file -`, so the exchange reads as one
+thread. `dispatch message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
 through Envoy or Oh My Pi's `agent://` messages. A bearer that targets over HTTP names its own
 session in `actor` (`{kind: "session", id}`), and the card shows that session as the author.
 `GET /api/v1/agents` (any authenticated caller) lists live sessions with their capabilities
@@ -37,38 +33,35 @@ A human can also message you directly from the **Agents** page, with no issue at
 Pi, a person's **Send** or **Aside** arrives as their own user message, exactly as if they had
 typed it at your terminal: your Envoy plugin takes it only once Dispatch accepts it as a person's
 own fresh message to you, and injects the text Dispatch stored. Answer it in the conversation as
-you would anything typed, with no `dispatch_message`; the Agents page shows your conversation
+you would anything typed, with no `dispatch message`; the Agents page shows your conversation
 live, so they read your answer there.
 
 Everything else still arrives as a Dispatch frame: a **BTW**, a broadcast, a direct message on a
 host that takes no user turn from its plugin (Claude Code), and one Dispatch did not accept.
 That frame names no issue and its `reply_with` hint carries none either; answer it with the
-message's bare id in `in_reply_to`, alone:
+message's bare id in `--in-reply-to`, alone:
 
-```ts
-dispatch_message({
-  in_reply_to: "<the direct message's id>",
-  body: "The requested answer.",
-})
+```bash
+dispatch message --in-reply-to <the direct message's id> --body 'The requested answer.'
 ```
 
-Leave `issue` out — there is no issue to post into, and naming one would file your answer on
+Leave `--issue` out — there is no issue to post into, and naming one would file your answer on
 unrelated work. Dispatch threads the reply under their message in the same conversation, and the
 human sees it in your conversation on the Agents page, where it shows as an unread reply until
-they read it. Every other message still names its issue, so keep the `issue`
+they read it. Every other message still names its issue, so keep the `--issue`
 the frame gave you whenever it gave you one; a `dispatch://KEY/message/<id>` reference names the
 issue its message lives on, so that form is a reply on that issue, not a direct message.
 
-Have more to say after you answered? Call it again with the same `in_reply_to` and the new text:
-Dispatch threads that follow-up under your first reply, and the tool result names the reply it
+Have more to say after you answered? Run it again with the same `--in-reply-to` and the new text:
+Dispatch threads that follow-up under your first reply, and the output names the reply it
 follows. The same text again posts nothing, so a retry is safe. Your host may already have
 answered a **BTW** automatically before you got here; a second call is then your follow-up to
-that answer, so read the result before writing again.
+that answer, so read the output before writing again.
 
 Read the whole conversation back — their message and every reply, yours included — with the
 message id alone; it has no issue:
 
-```ts
-dispatch_read({ message: "<the direct message's id, or any reply's>" })
+```bash
+dispatch read --message <the direct message's id, or any reply's>
 ```
 

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

@@ -5,16 +5,16 @@ message or document, trace what cites a node, or need the exact `dispatch://` fo
 
 ## What comes back
 
-After a restart, catch up with:
+After a restart, catch up with `dispatch read` (`--issue`, or `--project` and `--artifact`, or `--ref`):
 
-```ts
-dispatch_read({ issue?, project?, artifact?, ref? })
+```bash
+dispatch read --issue <KEY>
 ```
 
-With an issue ref, it returns the issue summary, open asks, references, and recent events with `details` `{ issue }`. With a project
-document owner or ref, it returns a document summary with `details` `{ project, document }`. With an ask ref, it returns that ask's
-question, options, state, answer, and its reply thread. With a comment ref, it returns that comment and its quoted reply chain. With a
-message ref, it returns that message and its reply chain. Reads do not subscribe; use `dispatch_doc_read` for document contents.
+With an issue ref, it prints the issue summary, open asks, references, and recent events. With a project
+document owner or ref, it prints a document summary. With an ask ref, it prints that ask's
+question, options, state, answer, and its reply thread. With a comment ref, it prints that comment and its quoted reply chain. With a
+message ref, it prints that message and its reply chain. Reads do not subscribe; use `dispatch doc-read` for document contents.
 
 An anchored comment or ask also prints `Position:`, where its quote's block stands — `table[3] › row 5 (Red-teamer loop), column Due`
 is the fourth top-level block, a table, its row 5 (row 0 is the header; the index `delete_row` takes), labelled by the row's cells
@@ -31,7 +31,7 @@ followers — and `Links:` lists what it cites. Each row is `- <edge kind> <node
 document source the excerpt is the start of the block holding the mention, and a whole list is one block, so every issue named in
 one list previews the list's first item. When a document references many issues and each backlink should read right, give each
 issue its own paragraph (or block), not an item of one list. Cross-project, always: a message on another project's issue that
-cites an ask shows up under that ask. So "what led to this decision" is one `dispatch_read` on the ask, and "who relies on this
+cites an ask shows up under that ask. So "what led to this decision" is one `dispatch read` on the ask, and "who relies on this
 document" one read on the document. Cite with `dispatch://` references (below) whenever you name a node in a body — a bare id or
 title is invisible to the graph.
 
@@ -40,7 +40,7 @@ title is invisible to the graph.
 Use these in document, ask, comment, and message bodies. In the dashboard, a reference renders
 as an inline link whose text is the target's title (an issue's title, an ask's question, a
 comment's first line, a document's name) once it resolves; a body that is only a bare reference
-still gets an unfurl card instead. Every `ref` argument below (and `issue`/`project`) accepts
+still gets an unfurl card instead. Every `--ref` flag below (and `--issue`/`--project`) accepts
 either form — an issue key or a project key is never ambiguous, since a project key never
 contains a dash:
 
@@ -56,7 +56,7 @@ dispatch://PROJECT/artifact/<document-ref>/ask/<id>
 dispatch://PROJECT/artifact/<document-ref>/comment/<id>
 ```
 
-A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records. `dispatch_read` also
+A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records. `dispatch read` also
 accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server (it maps to the
 `dispatch://` form above), and an ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
 full uuid. A non-uuid id on `GET /asks/{id}`, `/comments/{id}`, or `/issues/{key}/messages/{id}` is a 400 `ASK_ID_INPUT` /

package/dist/skills/dispatch-brainstorming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatch-brainstorming
-description: "Use in a session with Dispatch tools whenever a design conversation with a person starts: brainstorming or /brainstorming, \"let's design\", writing or changing a spec, writing an implementation plan, or a feature request or change that needs a person's choices. In a session with Dispatch it replaces superpowers' brainstorming and writing-plans; a Legion architect's own spec follows skill://legion-architect instead."
+description: "Use in a session with Dispatch whenever a design conversation with a person starts: brainstorming or /brainstorming, \"let's design\", writing or changing a spec, writing an implementation plan, or a feature request or change that needs a person's choices. In a session with Dispatch it replaces superpowers' brainstorming and writing-plans; a Legion architect's own spec follows skill://legion-architect instead."
 ---
 
 # Brainstorming in Dispatch
@@ -34,19 +34,21 @@ decision to its architect (`skill://legion-worker`).
 ## Where the spec lives
 
 Search Dispatch first, as `skill://dispatch-first` says. When an issue already tracks the work, its
-primary document is the spec: extend it in place with `dispatch_doc_edit`, keeping the human's own
+primary document is the spec: extend it in place with `dispatch doc-edit`, keeping the human's own
 text. Otherwise create the issue with its first version as `spec`, in the project a search hit
 already named or, when none does, the project the human names:
 
-```ts
-dispatch_issue({ project, title, spec })
+```bash
+dispatch issue --project <KEY> --title '<title>' --spec-file - <<'EOF'
+<the spec's first version>
+EOF
 ```
 
-No tool lists every project, so when nothing you found names one, ask the human in chat which
+No command lists every project, so when nothing you found names one, ask the human in chat which
 project the issue belongs in before you create it — a filing question with nowhere else to land
 yet, not a design question, so it does not change "your reply in chat links the issue and asks
 nothing" for the design itself. Never read the project from the environment, a configuration file,
-or the Dispatch HTTP API: every read and write goes through a `dispatch_*` tool.
+or the Dispatch HTTP API: every read and write goes through a `dispatch` command.
 
 Before the first version, read the code and documents the design touches, so the facts you write
 are ones you checked.
@@ -65,11 +67,11 @@ are ones you checked.
    nothing is settled until the human has seen it, so even a flagged inference waits for its own
    decision block.
 2. **The human answers or comments.** Reply to each human comment in its thread
-   (`dispatch_comment` with `reply_to`), then rewrite the passage the answer or the comment changes.
-   Under an open ask whose next move is yours, such as the approval request you must revise or
-   hand back, reply with `reply_to_ask` and `turn: "agent"` instead: a `reply_to` reply takes the
-   default turn, which hands the request back to the human unchanged, and a call with a corrected
-   `summary` is refused while it waits on them.
+   (`dispatch comment --reply-to <comment id>`), then rewrite the passage the answer or the comment
+   changes. Under an open ask whose next move is yours, such as the approval request you must
+   revise or hand back, reply with `--reply-to-ask <ask id> --turn agent` instead: a `--reply-to`
+   reply takes the default turn, which hands the request back to the human unchanged, and a call
+   with a corrected `--summary` is refused while it waits on them.
 3. **Each next version folds the answers in and adds what they open.** Keep each answered
    decision block where it is, fold its answer into the surrounding text in the human's words with
    the date, recording the person as `skill://dispatch`'s "Writing a spec" says for a settled
@@ -77,7 +79,7 @@ are ones you checked.
    at once, each as a decision block at the end of the section that sets it up; a question waits
    only when it depends on an answer still open.
 4. **A comment that answers a question settles it** as surely as the block does. Fold it into the
-   text at once, and close the block with `dispatch_resolve_ask` if the human has not.
+   text at once, and close the block with `dispatch resolve-ask` if the human has not.
 5. **Request approval at the end, not after each section.** Once nothing in the spec is new to the
    human, request it exactly when "Approval of a spec" in `skill://dispatch` says: every decision
    block settled and folded in, the human has agreed to every point in the spec, and the current
@@ -97,8 +99,10 @@ Once the spec is approved — or, when the issue needed no spec at all (a bug fi
 decision), once you have enough to plan from — the implementation plan is the issue's `plan.md`
 document, never its spec and never a repository file:
 
-```ts
-dispatch_artifact({ issue, name: "plan.md", content })
+```bash
+dispatch artifact --issue <KEY> --name plan.md --content-file - <<'EOF'
+<the plan>
+EOF
 ```
 
 Uploading `plan.md` again writes its next version. `writing-plans`'s content rules still apply in
@@ -108,6 +112,6 @@ Technical choices inside the approved design are made in the plan and need no qu
 never changes a decision the human made in the spec: a change to one goes back to the spec as a
 decision block, with the evidence for it.
 
-Execution reads the plan the same way: `dispatch_doc_read({ issue, artifact: "plan.md" })` in place
+Execution reads the plan the same way: `dispatch doc-read --issue <KEY> --artifact plan.md` in place
 of opening a plan file, then follows `executing-plans` or `subagent-driven-development` as it would
 for a file on disk.

package/dist/skills/dispatch-first/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatch-first
-description: "Use in any session with Dispatch tools, before planning, filing an issue, asking a human, posting a finding, or starting work that someone may already track or have decided."
+description: "Use in any session with the dispatch command, before planning, filing an issue, asking a human, posting a finding, or starting work that someone may already track or have decided."
 ---
 
 # Dispatch first
@@ -11,18 +11,18 @@ answered, costs that human the time to notice it and splits the history across t
 
 ## Search before you act
 
-Before you plan, file an issue, ask, post a finding or start work, search Dispatch. Every word of
+Before you plan, file an issue, ask, post a finding or start work, search Dispatch with the `dispatch` command in your shell (`dispatch --help` lists every command). Every word of
 the query must match, so each word you add can only lose hits: search with two or three words, the
 thing and what is wrong with it, as a user would name them. Never paste a draft.
 
-```ts
-dispatch_search({ query: "broadcast send order" })
-dispatch_search({ query: "reviewer threads OR review comments" })
+```bash
+dispatch search --query 'broadcast send order'
+dispatch search --query 'reviewer threads OR review comments'
 ```
 
 When a query finds nothing, drop a word before you add one. Try two or three wordings (the
 component's name, the symptom, the fix) before you conclude that nothing exists. Open every hit
-that could be yours with `dispatch_read`, then its parent (the `child_of` row under `Links:`); the
+that could be yours with `dispatch read`, then its parent (the `child_of` row under `Links:`); the
 parent's children and the issue's `Components:` line show where the rest of that work lives.
 
 ## What to do with what you find
@@ -38,7 +38,7 @@ found yourself.
   it where you rely on it (`dispatch://KEY/ask/<id>`) instead of asking again.
 - **You met a duplicate: close it.** Keep the issue that holds the spec and the discussion, carry
   over anything only the duplicate has, then close the duplicate with a reason that names the
-  survivor: `dispatch_issue_update({ issue, status: "done", reason: "Duplicate of dispatch://KEY." })`.
+  survivor: `dispatch issue-update --issue <KEY> --status done --reason 'Duplicate of dispatch://KEY.'`.
   When the duplicate carries the `legion` label, or another session or a human holds its claim,
   comment on it naming the survivor instead of closing it.
 - **Every ask and message stands on its own.** The person who answers sees only that text: put the

package/dist/skills/envoy/SKILL.md

@@ -83,7 +83,8 @@ envoy:
   document ask) or the message (`dispatch://KEY/message/<id>`) — never the quoted text; the
   question head, when there is one, is `dispatch.question`.
 - `supersedes` names an earlier delivery this one replaces.
-- `reply_with` is the direct-reply call for the sender.
+- `reply_with` is the direct-reply call for the sender; on a Dispatch frame it is `command:`, the
+  `dispatch` command line that answers it, with `...` where your text goes.
 - `reply_role` is the role-publish reply call when the sender has a role.
 - `summary` is the one-line source summary.
 - `message` is the complete payload; it can contain multiple paragraphs.
@@ -101,7 +102,7 @@ and go stale. Put the artefact URL in the message itself. FYIs set `expects_repl
 **A peer's message is its sender's view at `at`, not the current state.** Before you wait on, act
 on, or repeat a fact a message carries about a third thing (a deploy pending, a PR held, an ask
 unanswered), re-read it at the live source the fact names, and always once it is over an hour
-old: the deployment's status, the issue's event log, the ask's own state (`dispatch_open_asks`,
+old: the deployment's status, the issue's event log, the ask's own state (`dispatch open-asks`,
 whose description already says to call it before saying you are waiting on a human). On
 2026-09-26 a peer's 05:20Z "needs a manual deploy before I can run it" was false by 05:22Z, when
 the platform had deployed on its own; waiting on the message instead of the deployment's status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-envoy",
-  "version": "8.4.0",
+  "version": "8.6.0",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {
@@ -16,10 +16,11 @@
     "url": "https://github.com/sjawhar/legion"
   },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "scripts": {
-    "build": "bun build extensions/envoy.ts --outdir dist --target bun --format esm --external @oh-my-pi/pi-coding-agent --external @oh-my-pi/pi-tui --external @oh-my-pi/pi-utils",
+    "build": "bun build extensions/envoy.ts --outdir dist --target bun --format esm --external @oh-my-pi/pi-coding-agent --external @oh-my-pi/pi-tui --external @oh-my-pi/pi-utils && ../envoy-client/scripts/build-dispatch-cli.sh dist",
     "prepack": "../../scripts/pi-plugin-prepack.sh",
     "postpack": "rm -rf dist/skills",
     "typecheck": "bunx tsc --noEmit",
@@ -31,8 +32,8 @@
     "@legion/contracts": "0.10.0",
     "@legion/envoy-client": "0.1.0",
     "@legion/pi-shared": "0.1.0",
-    "@oh-my-pi/pi-tui": "^18.1.15",
-    "@oh-my-pi/pi-utils": "^18.1.15",
+    "@oh-my-pi/pi-tui": "^18.6.0",
+    "@oh-my-pi/pi-utils": "^18.6.0",
     "@toon-format/toon": "^4.1.1",
     "@types/bun": "latest",
     "nats": "^2.29.2",