@sjawhar/pi-envoy 10.14.0 → 10.14.1

package/dist/skills/dispatch/SKILL.md

@@ -1,471 +1,181 @@
 ---
 name: dispatch
-description: "Use before posting a message, a status update, or a periodic status update; before asking a question that references another message, artifact, or eval; before asking a design question or brainstorming a change; and when asking the human a question, updating the spec, commenting on a document, attaching an artifact, or running a dispatch command."
+description: "Use when posting to Dispatch: a message, status update, comment, artifact, spec or document edit, claim or status change. Use when asking a human a question, also one that cites another message, artifact or eval. Use when brainstorming or asking about a design change, or when running any dispatch command."
 ---
 
 # Dispatch
 
-Dispatch is your issue's or project document's living spec, asks, comments, and artifacts — a high-signal record for the humans who
-decide, never a log of your work. The transcript is your scratch pad; progress and status stay there. Anything meant for a human
-goes through the `dispatch` command, which runs in your shell: `dispatch --help` lists the commands, and `dispatch <command> --help`
-each one's flags and an example. A field is a flag (`--issue LEGION-3`); long text goes on stdin with `--<field>-file -` and a
-quoted here-document (`<<'EOF'` … `EOF`), and an object or list field takes JSON (`--ops-json`). What it prints is the result; it
-exits 0 when it wrote or read, 1 when Dispatch refused, and 2 on a usage error.
+Dispatch holds an issue's or project document's spec, asks, comments and artifacts. It is a high-signal record for the humans who decide, never a log of your work. Narrate progress in your transcript, not here.
 
-The server enforces high signal: an ask question is at most 800 characters with at most eight options; comment and message bodies are at
-most 2,000 characters; a markdown document is at most 1 MiB and any other file at most 25 MiB. It refuses over-limit input with the number
-to trim (`question is 50 characters over the 800-character limit (850/800)`); it never truncates it. A command with several problems is
-refused once, every problem listed (`dispatch <command> was not called: N problems`), so one corrected call lands.
+- Write to Dispatch only with the `dispatch` command in your shell. `dispatch --help` lists the commands. `dispatch <command> --help` gives the flags, the limits and an example.
+- Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'` … `EOF`). Give object and list fields as JSON (`--ops-json`).
+- Exit code 0 means it wrote or read, 1 means Dispatch refused, 2 means a usage error.
+- Dispatch refuses over-limit input with the number to trim. It never truncates. It lists every problem of a call in one refusal, so fix them all and call once again.
 
 ## Where the detail lives
 
-This file is the workflow. The detail for a step is in a reference file: open it when you reach
-that step, not before. On a host with no `skill://` scheme (Claude Code, OpenCode), a link's path
-after `skill://dispatch/` is relative to this skill's base directory.
+Open a reference when you reach its step, not before. On a host with no `skill://` scheme (Claude Code, OpenCode), the path after `skill://dispatch/` is relative to this skill's directory.
 
-| When you are about to | Read |
+| Before you | Read |
 | --- | --- |
-| run `dispatch doc-edit`: rewrite a paragraph, insert or move a block, change a table's cells, rows or columns | [Editing a document](skill://dispatch/references/document-edits.md) |
-| write a typed block (an `:::ask`, a callout), comment on or suggest a change to a document, upload an artifact, or retry after `DOC_SERVICE_UNAVAILABLE` | [Documents](skill://dispatch/references/documents.md) |
-| choose your next issue, claim one, move its status or priority, reorder a board, or audit a project's backlog | [Working an issue](skill://dispatch/references/issues.md) |
-| find who answers an ask, edit, retract or resolve one, reply with the turn, or follow a thread | [Asks after they open](skill://dispatch/references/asks.md) |
+| run `dispatch doc-edit` | [Editing a document](skill://dispatch/references/document-edits.md) |
+| write a typed block, comment, suggest, upload an artifact, request approval, or retry `DOC_SERVICE_UNAVAILABLE` | [Documents](skill://dispatch/references/documents.md) |
+| choose, claim or move an issue, set priority, reorder a board, or audit a backlog | [Working an issue](skill://dispatch/references/issues.md) |
+| route, edit, retract, resolve or reply to an open ask, or follow its thread | [Asks after they open](skill://dispatch/references/asks.md) |
 | catch up after a restart, trace what cites a node, or write a `dispatch://` reference | [Reading back](skill://dispatch/references/reading.md) |
-| answer a BTW, Aside or Steer frame, or a message from the Agents page | [Targeted and direct messages](skill://dispatch/references/messages.md) |
-| see a worked ask, a reply that names its mechanism, a message not to send, and where a draft goes | [Before and after](skill://dispatch/references/examples.md) |
-| set up a token, or call a route the commands do not cover | [Authentication and the HTTP API](skill://dispatch/references/api.md) |
+| answer a BTW, Aside or Steer frame, or an Agents-page message | [Targeted and direct messages](skill://dispatch/references/messages.md) |
+| want a worked example | [Before and after](skill://dispatch/references/examples.md) |
+| set up a token, or call a route no command covers | [Authentication and the HTTP API](skill://dispatch/references/api.md) |
 
 ## Design changes are brainstormed here
 
-When a session has Dispatch, a design change needing the human's choices is brainstormed in its
-issue's spec, not chat or a repository design document, and its plan is the issue's `plan.md`
-document. `skill://dispatch-brainstorming` holds the process: read it before a spec's first
-version, before each next turn, and before you write a plan.
+A design change that needs the human's choices is brainstormed in its issue's spec, not in chat or a repository design document. Its plan is the issue's `plan.md` document. Read `skill://dispatch-brainstorming` before a spec's first version, before each next turn, and before you write a plan.
 
 ## Writing for the human
 
-Every spec, ask, comment, message, and PR body is read by a person who has not read the code, does
-not share this session's vocabulary, and is often on a phone. Write for that person.
-
-- Plain English, full sentences, one idea per sentence. Never repo shorthand or nouns you coined:
-  not "fix 8c", "READY-target", "PR B", "spec@v3", "the pair", "the packet" — say what the thing is.
-- A real name is not a coined noun: name a product, a tool and its operation
-  (`dispatch request-approval`), an event type (`artifact.approved`), a route, a setting or a
-  status exactly, and say how it works in a clause ("the daemon opens the gate when Dispatch emits
-  `artifact.approved` for that document at that version"), never with a vague verb such as
-  "notice", "accept", "tell" or "pick up" ([before and after](skill://dispatch/references/examples.md#naming-the-mechanism)).
-- Expand every identifier the first time it appears: an issue key gets its title, a PR number its
-  title, a file what it is for, a session id who it is. Link a URL rather than pasting a bare id.
-- A question lives in the spec or discussion it came from, placed as
-  [Decision blocks](#decision-blocks) says, never as a compressed standalone ask. The question
-  carries the problem the reader recognises and why it matters now, what constrains the answer, and
-  the recommendation with its reason. It asks how to solve the problem or which outcome is wanted;
-  never enumerate choices in the question. The options carry the genuinely different approaches.
-  Each option has a label, and its description says what that approach costs.
-- Describe a change first by what its reader stands to lose — who can do what today, what they
-  will not be able to do after it, what still works, and what you cannot tell — then by what the
-  system does, each mechanism named exactly. The reader's sentence is a different sentence, not a
-  shorter engineering one: shortening keeps the system as its subject. Test that the first sentence
-  has a human subject, even on a sentence you already simplified; a lead naming what a change does
-  inside a system leaves the reader nothing to act on. Where the judgment rule below applies, the
-  judgment leads and this rule shapes the sentence under it.
-- Before posting, test it: could the human, reading only this text on their phone, know what they are being
-  told or asked? If not, rewrite it. Length is not the problem; density is.
-- When an ask or message communicates a judgment, lead with that judgment in one sentence and put the mechanism underneath it. Do not make the reader ask a second time whether the result is a win. This shapes communication only when a judgment exists; it does not pre-decide an open question or remove its genuine options.
-- When an ask, comment or message states a root cause or a blocker, include the command, error output or record that shows it, with its time, in that same text. Without it, label the diagnosis a hypothesis; a diagnosis still in progress may say so plainly. This boundary applies to causal claims, not to reporting that an investigation has started.
+Every spec, ask, comment, message and PR body goes to a person who has not read the code. They do not share your vocabulary, and often read on a phone.
 
-## Writing a spec
-
-A spec is the design conversation with the human, written down. It starts as the problem and the
-evidence for it, in plain words: what goes wrong, for whom, and the counts or cases that show it.
-It grows in place as the conversation goes. It is the issue's one primary document: extend it with
-a new version that keeps the human's own text, never a second "spec" artifact beside it.
-
-- **Each open question is a decision block**, shaped and placed as [Decision blocks](#decision-blocks)
-  says. Because it is an ask, it reaches the human's Inbox, and the answer lands next to its context.
-- **An answered decision block is itself the record of the decision.** It already renders the
-  person's chosen option and their own words, with who answered it and when; never add text
-  restating it. A point you inferred says so, with the reasoning — a security concern, a
-  restriction, or a cost nobody measured is exactly this, not a settled constraint; during a live
-  brainstorming conversation, `skill://dispatch-brainstorming` is stricter and keeps an inference
-  out of the spec until the human has agreed to it. One carried in from another document keeps its
-  provenance: an agent's inference there is marked one here, or stays out until the human raises
-  it.
-- **A decision that arrives another way carries no rendered record.** A comment that answers a
-  question, a conversation, or a waiver is written into the text in the person's own words and the
-  date, quoted, naming them from `dispatch whoami` or the conversation, or "the person" when the
-  token names no owner — never a name you were not given.
-- **Sections follow the topic.** No heading is required and none has a fixed place; name each
-  section for what it discusses.
-- **A changed point is rewritten, not appended to.** When an answer or a new fact changes design
-  text outside its decision block, rewrite that text; the block stays where it is as the record of
-  the answer. The document's versions keep the history.
-- **No placeholders.** No TBD, TODO, or hedging ("might", "could consider"): an open item is a
-  decision block, a technical decision your lane makes where the work happens, outside the spec,
-  or, for a contract between two lanes, a question you settle with the other lane over Envoy (see
-  [Before you ask](#before-you-ask) under Asking).
-- **No progress.** The spec records the design and its decisions, never status, timestamps, an
-  "Update HH:MMZ" section, a pull-request list, or handoff notes. Progress is not a Dispatch
-  object at all; it lives in your transcript and your pull request (see [Messages](#messages)).
-- **No commentary.** The spec talks about the design, never about the spec or the conversation: no
-  sentence calls it a draft, a conversation, a version or a turn; says what a later version will
-  add; describes an earlier version or correction; or narrates the exchange that produced it.
-
-Before a new version goes out, read it as the human will: no two passages conflict, each point has
-one reading, and every decision block passes the phone test above. A worked example is
-`dispatch://LEGION-386/artifact/spec@v5`: the problem and its counts, what the human settled in his
-own words, a section for each part of the design, and its one open question as a decision block
-after the section on models.
+- Write plain English in full sentences, one idea each. Never use repo shorthand or nouns you coined ("fix 8c", "PR B", "spec@v3", "the pair"). Say what the thing is.
+- Name a real product, tool operation (`dispatch request-approval`), event (`artifact.approved`), route, setting or status exactly. Say in a clause how it works. Never use a vague verb such as "notice", "accept", "tell" or "pick up" ([example](skill://dispatch/references/examples.md#naming-the-mechanism)).
+- Expand each identifier on first use. Give an issue key or PR number its title, a file its purpose, a session id who it is. Link a URL, not a bare id.
+- Describe a change first by what its reader stands to lose. Say who can do what today, what they cannot do after it, what still works, and what you cannot tell. Then name each mechanism. Write that first sentence with a human subject. A shorter engineering sentence is not a reader's sentence.
+- When the text carries a judgment, lead with it in one sentence and put the mechanism under it. Then the judgment comes first, and the rule above shapes the sentence under it. This never pre-decides an open question or drops its real options.
+- When you state a root cause or a blocker, include the command, error output or record that shows it, with its time. Without it, call the diagnosis a hypothesis. A diagnosis in progress can say so.
+- Phone test before you post: can the human, reading only this text on a phone, know what they are told or asked? If not, rewrite. Density is the problem, not length.
 
-## Decision blocks
+A question lives in the spec or discussion it came from, as [Decision blocks](#decision-blocks) says, never as a compressed standalone ask. It carries the problem the reader recognises, why it matters now, what constrains the answer, and your recommendation with its reason. It asks how to solve the problem or which outcome is wanted. It never lists the choices: the options carry the different approaches, each a label and a description of what it costs.
 
-A decision a human must make is an `:::ask` block at the end of the section that discusses it,
-shaped as [Writing for the human](#writing-for-the-human) says for a question, with what
-constrains the answer split into measured, known and unknown. It asks how to solve the problem,
-never whether to apply a change already chosen. Never gather decisions into a list, at the top,
-at the bottom or in an "open questions" section, and never ask one as a standalone `dispatch ask`
-that points at the spec.
+## Writing a spec
 
-The block is what reaches the human's Inbox. A question phrased as prose in the spec reaches
-nobody. A spec with no ask blocks is fine only when the issue genuinely needs no human decision.
-What `dispatch issue` and `dispatch artifact` answer about a spec's blocks, and how to check an edit
-wrote one, is in [Typed blocks](skill://dispatch/references/documents.md#typed-blocks).
+A spec is the design conversation with the human, written down. It starts as the problem and its evidence: what goes wrong, for whom, and the counts or cases that show it. It grows in place. It is the issue's one primary document: extend it with a new version that keeps the human's text, never a second "spec" artifact.
 
-**Wrong:** a **Decisions needed** list at the top of the spec with three bullets.
-**Right:** each decision an `:::ask{#slug}` block at the end of the design section that discusses
-it, with 2–4 options, a recommendation, and surrounding prose that explains the trade-off.
+- **Each open question is a decision block** ([Decision blocks](#decision-blocks)).
+- **An answered decision block is the record.** It shows the chosen option, the person's words, who and when. Never restate it.
+- **Mark an inference as one**, with its reasoning. A security concern, a restriction or a cost nobody measured is an inference, not a settled constraint. A point carried from another document keeps its provenance. `skill://dispatch-brainstorming` keeps an inference out of a live brainstorm's spec until the human agrees to it.
+- **A decision from a comment, conversation or waiver has no rendered record.** Write it into the text in the person's words, quoted and dated. Name them from `dispatch whoami` or the conversation. If neither names them, write "the person". Never use a name you were not given.
+- **Sections follow the topic.** No heading is required or fixed.
+- **Rewrite a changed point. Do not append.** The decision block stays as the record. Versions keep the history.
+- **No placeholders**: no TBD, TODO or hedging. An open item is a decision block or a two-lane contract you settle over Envoy. Or it is a technical decision your lane makes where the work happens, outside the spec.
+- **No progress**: no status, timestamps, "Update HH:MMZ" sections, PR lists or handoff notes.
+- **No commentary**: never call it a draft, version or turn, preview a later version, describe a correction, or narrate the exchange.
 
-A spec that already has the pile is repaired with `move`, not rewritten: `dispatch doc-edit` with
-`--ops-json '[{"op":"move","block":"<block-uuid>","after":"<the last sentence of the section that discusses it>"}]'` relocates
-the block and keeps its ask, its answer and its followers; the context paragraphs that were lifted
-out of Design move the same way, and the emptied section is deleted. An ask block has two ids that
-differ; [Editing a document](skill://dispatch/references/document-edits.md) says which.
+Before a version goes out, read it as the human will. No two passages conflict, each point has one reading, and each decision block passes the phone test.
 
-See [Typed blocks](#typed-blocks) for the syntax and [Before you ask](#before-you-ask) under
-[Asking](#asking) to decide whether the question is a real decision at all.
+## Decision blocks
 
-## Your owner
+A decision a human must make is an `:::ask{#slug}` block at the end of the section that discusses it. Shape it as [Writing for the human](#writing-for-the-human) says. Split what constrains it into measured, known and unknown. Give 2–4 options and a recommendation, with the trade-off in the prose around it. It asks how to solve the problem, never whether to apply a change already chosen.
 
-Every session works on an issue or project document. Legion pre-fills `--issue` from `LEGION_ISSUE`: use a native issue key such as
-`LEGION-3`, an external `owner/repo#n` reference, or a bare positive number (resolved against the cwd repository). Otherwise pass
-exactly one owner to every owner-scoped command: `--issue` for an issue, or `--project` and `--artifact` for an unlinked project document (see
-[Reference forms](skill://dispatch/references/reading.md) for the resulting ref shape). An external issue reference addresses the existing Dispatch issue linked to
-that GitHub issue or pull request. Only `dispatch issue` with `--external` creates a native issue; if no issue is linked, run
-`dispatch issue --external owner/repo#n --project <project> --title '<title>'` before addressing it.
+- Never gather decisions in a list, at the top, at the bottom, or in an "open questions" section. Never ask one as a standalone `dispatch ask` that points at the spec.
+- Prose questions reach nobody. Only the block reaches the Inbox. A spec with no blocks is right only when no human decision is needed.
+- Fix a pile with `move`, not a rewrite. `dispatch doc-edit --ops-json '[{"op":"move","block":"<block-uuid>","after":"<last sentence of its section>"}]'` keeps the ask, its answer and its followers. Move the lifted context the same way and delete the empty section. An ask block has two different ids ([Editing a document](skill://dispatch/references/document-edits.md)).
+- Syntax and checks: [Typed blocks](skill://dispatch/references/documents.md#typed-blocks). Whether to ask at all: [Before you ask](#before-you-ask).
 
-Create an issue for newly tracked work with `dispatch issue --project <KEY> --title '<title>'` (`dispatch issue --help` lists `--parent`, `--spec-file`, `--label`, `--priority` and the rest).
-Labels are optional: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. `--priority` is yours on creation too — see [Priority is yours to set](skill://dispatch/references/issues.md). Set `--assignee` (the email of a person who has signed in to Dispatch) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. Set `--repo <owner/name>` when the issue targets a repository other than the one it would inherit: its parent's, else the project's default; the repository must be mapped to the project in Settings, and `dispatch read` shows the one the issue resolves to on its `Repository:` line. It prints
-the new key; creating an issue does not subscribe you to it (see [Following](#following)). Use `dispatch issue` only to create an issue; never use it to park a question. When you pass a spec,
-follow [Writing a spec](#writing-a-spec).
+## Your owner
 
-Work goes in a project that exists: `dispatch projects` lists them, and work that spans projects goes in the one that owns most of it. Create a project only when the human asks for one, with `dispatch project --key <KEY> --name '<name>'`. Projects cannot be renamed or deleted, so a mistyped key stays for good. A key that already exists is refused with `PROJECT_EXISTS`.
+- Every owner-scoped command takes exactly one owner. That is `--issue` (a key such as `LEGION-3`, `owner/repo#n`, or a bare number for the cwd repository), or `--project` with `--artifact`. Legion pre-fills `--issue` from `LEGION_ISSUE`.
+- An external reference addresses the Dispatch issue linked to it. If none is linked, create one: `dispatch issue --external owner/repo#n --project <project> --title '<title>'`.
+- Create an issue for new work with `dispatch issue --project <KEY> --title '<title>'`. Set `--priority` ([issues.md](skill://dispatch/references/issues.md#priority-is-yours-to-set)). Set `--assignee` only when the human said who owns it. Set `--repo` only when it differs from what the issue inherits. Creating an issue does not subscribe you. Never create an issue to park a question.
+- File work in a project that exists (`dispatch projects`). Work across projects goes in the one that owns most of it. Create a project only when the human asks. You cannot rename or delete a project.
 
 ## Search first
 
-`skill://dispatch-first`, which every session with Dispatch carries, says how to search before
-you plan, start a design document, file an issue, ask, post a finding or start work, and what to
-do with each hit. What it leaves out (`dispatch search --help` has `--project`, `--limit` and `--offset`):
-Websearch syntax applies: `"merge queue"`, `-daemon`, `OR`. Issues, documents, asks, comments, and messages rank separately; the
-merged page orders each kind's best in turn — issue, document, ask, comment, message — and a bare issue key ranks first. Each
-kind's list also merges a query embedding's meaning match with keyword hits (LEGION-549): a paraphrase with no shared word can
-still match; without an embedder, it says so and ranks by keyword alone. A page holds `--limit` hits (20 default, 50 max); the first
-line gives the total (`showing 1-20 of 312`); see [Search paging](skill://dispatch/references/issues.md#search-paging) for more.
-Queries over 1,000 characters are refused: use the few words `skill://dispatch-first` names, never a pasted passage. Issue hits
-start with the issue key; document hits start with `dispatch://PROJECT/artifact/<slug>`, then the link. Cite the hit (`dispatch://KEY` or the doc ref) or say "no prior issue".
-
-`dispatch issue` refuses a title that near-duplicates an issue in the same project and prints the candidates (`POSSIBLE_DUPLICATE`). Read them; reference the existing issue, or run it again with `--force` when it is genuinely new work.
-The check compares title words only (shared stemmed terms), never meaning: "four tests that fail a
-merge" pairs with "four CI gates that cannot fail a merge". So when you force past a candidate, give
-the new issue a title that names what differs where you can, and open its spec with the
-distinction from the named issue, citing it (`dispatch://KEY`), for whoever reads the next pairing.
-
-### Symptom versus cause
-
-When a symptom and its cause sit on different issues, the work accrues to the cause's issue, and
-the symptom's issue carries a pointer to it. Before posting a measurement or finding, search
-Dispatch for the failing identity's or component's name, and post on the issue whose title names
-the fix, not the one naming the symptom. A symptom issue gathering messages with no human response
-is the tell.
+- Search as `skill://dispatch-first` says before you plan, file, ask, post, start a design document or start work. `dispatch search --help` has the syntax and paging. A paraphrase can match by meaning. Without an embedder, search says so and ranks by keyword. Never paste a passage: a query over 1,000 characters is refused. Cite the hit (`dispatch://KEY`) or say "no prior issue".
+- `POSSIBLE_DUPLICATE` compares title words only. Read the candidates. Reference the existing issue, or use `--force` for new work. Then give the new title the difference, and open its spec with the distinction, citing the named issue.
+- **Symptom versus cause.** Work goes on the issue whose title names the fix. The symptom's issue gets a pointer. Before you post a finding, search for the failing component's name. A symptom issue that gathers messages with no human reply is the sign.
 
 ## Claim the issue before you work it
 
-Before you start implementing an issue, claim it, and release the claim when you stop: finished,
-handing over, or moving to something else. Closing the issue releases it for you.
-```bash
-dispatch claim --issue LEGION-234             # I am implementing this
-dispatch claim --issue LEGION-234 --release   # I have stopped; it is free
-```
-A claim is intent to implement: reading, commenting, asking, or gating a pull request claims
-nothing. `409 ISSUE_CLAIMED` means someone else holds the issue; never work it in parallel. What
-each refusal means, and when a claim is yours to take, is in
-[Working an issue](skill://dispatch/references/issues.md).
+- Before you implement, `dispatch claim --issue <KEY>` and `dispatch issue-update --issue <KEY> --status in_progress`. Release with `--release` when you finish, hand over or switch. Closing releases it.
+- Reading, commenting, asking or gating a PR claims nothing.
+- `409 ISSUE_CLAIMED`: someone else holds it. Never work it in parallel. Refusals and takeovers: [issues.md](skill://dispatch/references/issues.md).
 
 ## Issue status is yours to move
 
-Claiming and moving the status are two actions, and you do both: when you start,
-`dispatch claim --issue <KEY>` and `dispatch issue-update --issue <KEY> --status in_progress`. Outside
-Legion the session doing the work moves its issue and the children it owns: `in_progress` when
-implementation starts, `testing` while the change is proven on a production-like surface,
-`needs_review` when its pull request waits on the merge queue, and `done`, with a `--reason`, once
-the change has been driven in production. Never write the status of an issue that carries the
-`legion` label, or of any issue under one: the Legion daemon writes those. Closing, clearing a
-field, and choosing your next issue are in [Working an issue](skill://dispatch/references/issues.md).
+Outside Legion, the session doing the work moves its issue and the children it owns. Use `in_progress` at implementation and `testing` while proven on a production-like surface. Use `needs_review` while its PR waits on the merge queue, and `done` with `--reason` once driven in production. Never write the status of an issue with the `legion` label or under one. The daemon writes those.
 
 ## Asking
 
-Two kinds of question reach a human. A decision about the design a document records is a decision
-block in that document ([Decision blocks](#decision-blocks)), at every phase, approved or not: a
-block in an approved document leaves the approval stale until the answer, which carries it
-forward when it is the whole change (below). A Legion phase worker sends it to its architect,
-which writes the block (`skill://legion-worker`). A to-do or permission only a human can give, or
-a decision with no document to live in, is a `dispatch ask`. The gates below apply to both.
+A design decision a document records is a decision block in it, at every phase, approved or not. A block in an approved document makes the approval stale until its answer. A Legion phase worker sends the decision to its architect (`skill://legion-worker`). A to-do or permission only a human can give, or a decision with no document, is a `dispatch ask`. The gates apply to both.
 
 ### Before you ask
 
-Every `dispatch ask` passes four gates first:
-
-1. **Does it need his authority, taste, or risk appetite?** This is the bar for a decision
-   written as an `:::ask` block in context ([Decision blocks](#decision-blocks)). Technical
-   decisions inside your outcome do not: schema shapes, table layouts, field names, and migration
-   internals are your lane's to decide where the work happens, in the plan or the code, not in the
-   spec. A contract between two lanes is settled by those two lanes over Envoy, and you open no ask
-   for it. A halt condition (a change to IAM, deletion or exposure of production data, anything
-   that reaches a customer) passes this gate: it is your own `dispatch ask` to the human on your own
-   issue.
-2. **Is there genuine uncertainty, and have you measured what you can?** If there is none, it is
-   a plan you execute. The one legitimate ask without uncertainty is permission for an action
-   only a human can authorise — a production write, an external send, a console action. Start it
-   with the problem and why the action is needed, then state what the action changes and risks;
-   its options name the outcomes.
-   Measure before you write: how many are affected, whether anything reaches the path, what the
-   current state already is. The measurement decides whether a human is needed at all, and when
-   one is, it turns a research request he cannot answer into a decision he can. Put the
-   measurement and the size of the affected population in the ask. When the measurement shows one
-   fix cannot repair most of that population and another fix can, drop the first, rather than
-   offering it cut down to the part it reaches. An option not to act, such as a permission ask's
-   Hold, is not a fix, and it stays.
-   Report what the measurement could **not** establish, with its own control: "I found no
-   evidence" and "there is no evidence to find" read alike and mean opposite things, and a
-   control that shares the query's blind spot proves neither. Before you say you are waiting on
-   him, run `dispatch open-asks` (below) — and the test for a new ask is not whether you asked on
-   this issue before, but whether it asks him to re-report something he has already answered.
-3. **Can someone who has not read the code answer it on a phone?** Write it as
-   [Writing for the human](#writing-for-the-human) says — who can do what today and what changes
-   for them, then two options with what each costs and your recommendation — with no slice or
-   decision numbers, no coined nouns, and each real tool, event, route or setting named exactly with
-   what it does. If you cannot write it that way, you do not understand it well enough to ask.
-4. **Is it outside what he has already told you he wants?** If not, that want is settled, and so
-   is every choice inside it his words do not make: build it and ask nothing about it or beside it
-   until it is delivered, whatever the ask says about the build. Afterwards, ask only about a choice his own
-   message raises and leaves open, quoting his words and naming what you delivered. A cause you
-   diagnosed, or a behaviour next to the one he named, is not in his message: neither ask about
-   it nor build it — fixing the cause of the thing he named is delivering what he asked for, and
-   is not what this forbids; changing something else is. An ask that turns his complaint about
-   one control into a choice about another does not address what he asked, and changing that
-   other control is a change he never asked for. What is still an ask the moment you know it,
-   even before delivery, is anything "Anything you are blocked on a human for is visible in
-   Dispatch" (further down) lists that the delivery waits on — including a conflict between what
-   he asked for and another of his rules, which this gate would otherwise bury as settled.
-
-Nobody audits or retracts another session's asks: passing every gate, and carrying the content
-instead of pointing at another message in prose (below), is the asking session's own check.
-
-Open a standalone ask with `dispatch ask` (`dispatch ask --help` lists its flags), one `--option` per choice:
+1. **Does it need the human's authority, taste or risk appetite?** Your lane decides schema shapes, field names and migration internals. Decide them in the plan or code, not in the spec. Settle a two-lane contract over Envoy, with no ask. A halt condition passes the gate. That is an IAM change, deleting or exposing production data, or anything that reaches a customer. Ask on your own issue.
+2. **Is there real uncertainty, and did you measure what you can?** With none, execute. The one ask without uncertainty is permission only a human can give: a production write, an external send, a console action. Start it with the problem and why, then what it changes and risks. Options name outcomes. Measure first: how many are affected, what reaches the path, the current state. Put the measurement and the population size in the ask. One fix cannot fix most of that population and another can? Drop the first. Never offer it cut down. An option not to act (Hold) stays. Report what the measurement could not establish, with its own control. "I found no evidence" and "there is none to find" differ. A control with the query's blind spot proves neither. The test for a new ask is not whether you asked on this issue before. It is whether it makes the human report again an answer they already gave.
+3. **Can someone who has not read the code answer it on a phone?** Say who can do what today and what changes. Give two options with costs, and your recommendation. No slice or decision numbers, no coined nouns. If you cannot write it so, you do not understand it yet.
+4. **Is it outside what the human already said they want?** If not, it is settled, with every choice inside it their words leave open. Build it and ask nothing about it or beside it until delivered, whatever the ask says about the build. After that, ask only about a choice their message raised and left open, quoting it and naming what you delivered. A cause you diagnosed or a neighbouring behaviour is not in their message: do not ask about it or build it. Fixing the cause of the thing they named is delivery. Do not turn a complaint about one control into a choice about another. Still ask at once about any blocker in [When you need a human](#when-you-need-a-human), including a conflict between their request and another of their rules.
+
+Nobody else audits or retracts your asks. Passing the gates is your own check.
+
 ```bash
 dispatch ask --issue <KEY> --question-file - --option 'Label: what it costs' --option 'Other: what it costs' <<'EOF'
-<the problem, what constrains the answer (each answer of his you rely on, linked), and your recommendation with its reason>
+<the problem, what constrains the answer (each answer of theirs you rely on, linked), your recommendation and why>
 EOF
 ```
-It prints the ask's id; you follow the ask you opened (see [Following](#following)).
-
-References belong in the question text; `--ref` is sugar that appends its `dispatch://` value to the question as a rendered link.
-
-An ask is read on a phone by someone who has not read the code. Write its question and options as
-[Writing for the human](#writing-for-the-human) says, and apply its phone test before posting.
-Never lead a question with a file path, line number, sequence number, document version or role token: its own text explains the problem.
-Evidence below it may cite one where the reader checks it, or anchor the ask to the passage with `--anchor-json '{"artifact":"spec","quote":"…"}'`; an optional `occurrence` is zero-based and selects a repeated quote.
-A quote anchor is pinned to its lowest complete
-containing block while retaining its quote as display text, so rewording the passage keeps it
-attached; a quote spanning top-level blocks, and existing anchors without a block, stay readable
-against their original document version if their quote disappears.
-
-An ask must be answerable from its own text and its anchor alone. Anchor a to-do about a document
-passage with `--anchor-json`. Follow up on an ask or comment with `dispatch comment`; cite anything else
-with a `dispatch://` reference (see [References](#references)). Never write "see above", "the
-message above", or "as attached".
-
-**Pointing at another message is a defect, not a shortcut:** the ask view does not show the
-issue's comments. The rules:
-
-- An ask that names another message in prose — "my comment above", "the procedure I posted",
-  "see the earlier message" — fails the gates. Put the content IN the ask. If it does not fit the
-  800-character budget, the step is too big: split the step, never point elsewhere. The only
-  pointers an ask may carry are a `dispatch://` reference or a document `anchor`, and they cite —
-  the ask still says in one line what the reader will find there and can be answered without
-  following them.
-- A runbook the human must execute is one ask per step, each self-contained: what to do, where,
-  what result proves it, and options that name the step's outcomes. Each later step opens only
-  after the previous is answered and states that step's verified result in one line ("Step 1
-  done: the licence shows Cloud Identity Free on the admin console.") — never a pointer to the
-  earlier ask.
-
-**A decision about an uploaded artifact links it.** If the human must read an artifact to answer,
-the question carries `dispatch://KEY/artifact/<slug>` (or `ref`), never just its filename. Text
-they must read to decide belongs in the spec in the first place — see [Artifacts](#artifacts).
 
-### When you need a human
+- You follow the ask you open. `--ref` appends a `dispatch://` link to the question.
+- Never lead with a file path, line number, sequence number, version or role token. Evidence under it can cite one. Anchor it to a passage with `--anchor-json '{"artifact":"spec","quote":"…"}'` (optional zero-based `occurrence`).
+- The ask must be answerable from its own text and anchor. The ask view does not show the issue's comments. Never write "see above", "my comment above" or "as attached". Put the content in the ask. If it does not fit in 800 characters, split the step. A `dispatch://` reference or an anchor may cite, with one line on what it holds.
+- A runbook for the human is one self-contained ask per step: what, where, what result proves it, and outcome options. Open each step after the previous is answered, with its verified result in one line.
+- If the human must read an artifact to decide, link `dispatch://KEY/artifact/<slug>`, never a filename. Text needed to decide belongs in the spec ([Artifacts](#artifacts)).
 
-Before saying you are waiting for human input, run `dispatch open-asks`. With no flags it lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply. With `dispatch open-asks --project <KEY>` it lists every open ask in that project — on its issues and on its documents, whoever authored them — which is how you see what a whole project is waiting on rather than just your own asks.
-
-**Unsettled product shape needs a decision before implementation.** When a page, navigation entry, table key, customer-scoping rule, or persisted sidecar would set product shape that the human has not already settled, write a decision block in the document that records the work before the first implementation commit; in a Legion tree the architect writes it, and a phase worker sends the decision to its architect. A lane's schema decision or a contract two lanes agree does not settle product shape. This does not turn a user-specified decision or routine implementation into an approval request. A control or behaviour the human asked for in words is settled by those words, together with every choice inside it that his words do not make (where it sits, its defaults, …
-
-**Anything you are blocked on a human for is visible in Dispatch.** An agent waits on a human only
-through an open ask. A to-do, permission, credential or grant renewal, setting only they can
-change, review click, or conflict between two of their own rules is a `dispatch ask` the moment you
-know. Start with the problem and why it matters, then the constraints, options and their costs, and
-your recommendation. For an action only the human can perform, state what it changes and risks;
-never make the action itself the question (a design decision is a decision block, as above). Never
-write a human to-do only into a spec, a comment reply, a message, or a pull-request body: nothing
-in those paths reaches the human's Inbox, and a human who is not reading the document does not
-know they are the blocker. Before asking, try to remove the step: a value already on the machine, a
-permission you already hold, an API that replaces the click. One ask per item, `--urgency high`
-when work is stopped on it; while it is open, keep working on everything that is not.
+### When you need a human
 
-Once an ask is open (who answers it, handing a human a to-do, editing, retracting or resolving it,
-answering a clarification, whose turn a reply gives, an answer the human changes), see
-[Asks after they open](skill://dispatch/references/asks.md).
+- Before you say you wait on a human, run `dispatch open-asks`. Add `--project <KEY>` to see every open ask in a project.
+- **Unsettled product shape needs a decision before implementation.** Product shape can come from a page, navigation entry, table key, customer-scoping rule or persisted sidecar. If the human has not settled it, write a decision block in the work's document before the first implementation commit. In a Legion tree the architect writes it. A lane's schema choice or a two-lane contract does not settle product shape. A behaviour the human asked for in words is settled, with each choice inside it. Routine work needs no approval.
+- **Anything you are blocked on a human for is visible in Dispatch.** An agent waits on a human only through an open ask. Make each blocker a `dispatch ask` the moment you know. Blockers are a to-do, a permission, a credential or grant renewal, a human-only setting, a review click, or a conflict between two of their rules. Start with the problem and why, then constraints, options with costs, and your recommendation. For a human-only action, state what it changes and risks. Never make the action the question. A to-do only in a spec, comment, message or PR body reaches no Inbox.
+- First try to make the step unnecessary: a value on the machine, a permission you hold, an API that replaces the click.
+- One ask per item, `--urgency high` when work halts on it. Keep working on everything else.
+- **Ask once.** Do not raise an open ask again in each message. The open ask is the request.
+- After it opens: [Asks after they open](skill://dispatch/references/asks.md).
 
 ## Architecture components
 
-Attach every architectural issue to the components it changes. Attach the root before decomposing it: children inherit the root's effective attachment unless they deliberately set their own, so one root attachment classifies the whole tree.
-
-```bash
-dispatch issue --project CORE --title '...' --components-json '{"mode":"explicit","ids":["dispatch-server","web"]}'
-dispatch issue-update --issue CORE-12 --components-json '{"mode":"explicit","ids":["web"]}'  # its own set, replacing what it inherited
-dispatch issue-update --issue CORE-13 --components-json '{"mode":"none","reason":"hiring, not code"}'
-dispatch issue-update --issue CORE-14 --components-json '{"mode":"inherit"}'                 # back to the parent chain's attachment
-```
-
-No `dispatch` command lists component ids. Read the configured model with `GET /api/v1/projects/{key}/architecture` and use each non-external `components[].id`; when its source repository is your checkout, those ids are the file names under `.dispatch/architecture/` (`web.md` → `web`). An id absent from the model, or an `external` component, is refused with `COMPONENTS_INPUT`.
-
-Use `"mode":"none"` with a concrete reason only when the work is genuinely non-architectural (for example hiring, process, or operations work). A closed issue can be classified without reopening. Change code and its architecture description (`.dispatch/architecture/<id>.md`) in the same review. When the model you read is behind your checkout, `dispatch architecture-sync` imports it now ([Syncing a project's architecture model](skill://dispatch/references/issues.md)).
+- Attach every architectural issue to the components it changes. Attach the root before you decompose it: children inherit.
+- `--components-json '{"mode":"explicit","ids":["web"]}'`, `'{"mode":"none","reason":"hiring, not code"}'` (only for non-architectural work, with a concrete reason), or `'{"mode":"inherit"}'`.
+- Component ids: each non-external `components[].id` from `GET /api/v1/projects/{key}/architecture`, or the file names under `.dispatch/architecture/` in its source repository. Others are refused `COMPONENTS_INPUT`. A closed issue can be classified without reopening.
+- Change code and `.dispatch/architecture/<id>.md` in the same review. A stale model: `dispatch architecture-sync` ([issues.md](skill://dispatch/references/issues.md#syncing-a-projects-architecture-model)).
 
 ## Close what you opened
 
-An ask you opened is yours until it is answered or you resolve it. When the answer arrives some
-other way — the human said it live, a later comment settled it, or the question became moot because the
-design moved — resolve it yourself with `dispatch resolve-ask` in the same turn you learn that.
-Never leave it for the human to clear.
-
-Every later write on the issue answers `You still have an open ask on …` and names it. Treat that
-as the checklist: if it is still needed, leave it; if it was answered elsewhere, resolve it with
-the resolving fact as the reason. Before posting a new ask, inspect your open ones. If the new ask
-supersedes one, retract the old one with `dispatch resolve-ask --kind retracted` in the same
-turn.
-
-See [Following](#following) for why you receive what happens to asks you open and
-[What comes back](skill://dispatch/references/reading.md) for finding them again with `dispatch open-asks`.
+- An ask you opened is yours until answered or resolved. When the answer arrives another way, or the design made it moot, `dispatch resolve-ask` in the same turn. Never leave it for the human.
+- Each later write names your open asks (`You still have an open ask on …`). Keep the ones still needed. Resolve the rest with the resolving fact as the reason.
+- Before a new ask, check your open ones. Retract one it supersedes with `--kind retracted` in the same turn.
 
 ## Approval of a spec
 
-Approval is a property of a document, not a question you phrase: a human approves a specific
-version, the way a pull-request review approves a commit, and a later version leaves that approval
-stale, unless the human's own answer to a decision block is the whole change since the version
-they approved; then Dispatch records an `approved` review in their name at that version and emits
-`artifact.approved`, so request nothing. When the answer changes text outside its block, rewrite
-that text, run the fresh reader below on it and request again. A later version also moves an open
-request with it, waiting on you until you request again. Request only when all three hold: every
-decision block is settled (answered or waived, below); the human has agreed to every point in the
-spec; and the current version has not been approved. A Legion root spec under an armed design gate
-always goes to approval once all three hold (`skill://legion-architect`).
-
-Before calling `dispatch request-approval`, have a fresh read-only reader check the current spec
-against the code and the human's words, then resolve every finding. A Legion architect uses
-`plan-gap-analyst`, another session the read-only reader its host supplies. When all three hold,
-request in the pass that finishes the spec: a design waiting with nothing in the human's Inbox
-waits on nobody. When a human asks for approval while a block is open, neither request it nor hold
-it silently: name each open block and ask them to answer or waive it. For a waiver, close it with
-`dispatch resolve-ask --kind resolved` (their words as `--reason`), write their decision into the
-text in their words and request. `dispatch request-approval` refuses while any block is open.
-
-An approval request carries nothing new: a point the human has not agreed to gets its own decision
-block first, with your recommendation, or, when it is a choice you can make yourself
-([Before you ask](#before-you-ask), gate 1) and the human will not want a say in it, comes out of
-the spec and is made where the work happens; an inference you cannot defend in a decision block
-comes out of the spec. `--summary` says in one to three sentences what the human is approving and
-nothing else: no commentary on itself or on the conversation, and no open question; after an
-earlier approval, one sentence naming what changed since it, since the card shows that approval
-and its `Show diff` control carries the detail. Never write "Approve" options into an ordinary
-`dispatch ask`; only humans approve. The call, its result and its answer:
-[Approval requests](skill://dispatch/references/documents.md#approval-requests).
+A human approves one version. A later version makes the approval stale, unless the human's own answer to a decision block is the whole change. Then Dispatch records the approval and emits `artifact.approved`: request nothing. If the answer changes text outside its block, rewrite that text, run the fresh reader, and request again. A new version also moves an open request, which then waits on you.
+
+- Request only when all three hold: every block is answered or waived, the human agreed to every point, and this version is not approved. A Legion root spec under an armed design gate always goes to approval then (`skill://legion-architect`).
+- First have a fresh read-only reader check the spec against the code and the human's words, and resolve every finding. A Legion architect uses `plan-gap-analyst`. Then request in the same pass: a finished design with nothing in the Inbox waits on nobody.
+- If the human asks for approval while a block is open, name each open block and ask them to answer or waive it. For a waiver, `dispatch resolve-ask --kind resolved` with their words as `--reason`, write the decision into the text, then request.
+- A request carries nothing new. An unagreed point first gets a decision block with your recommendation. A choice that is yours (gate 1), where the human will not want a say, leaves the spec. An inference you cannot defend in a block leaves the spec.
+- `--summary` is one to three sentences on what they approve, with no commentary and no question. After an earlier approval, one sentence on what changed.
+- Only humans approve. Never put "Approve" options in a `dispatch ask`. Details: [Approval requests](skill://dispatch/references/documents.md#approval-requests).
 
 ## The Spec
 
-The spec holds the design and the decisions that shaped it, written as [Writing a spec](#writing-a-spec)
-says, which also lists what it never carries. It changes when the conversation changes it, and
-every version that records a decision is named with `dispatch doc-edit --summary`.
-
-Read the current document before changing it with `dispatch doc-read` (`--issue`, or `--project`
-and `--artifact`, an optional `--version`, or `--ref`).
-It prints live or versioned markdown with open marks. A live read ends with a document token; `--blocks` lists the live
-document's block ids, tokens and table rows instead, which `dispatch doc-edit` takes to address a block that is not a typed
-block. `--issue` with no
-`--artifact` reads the issue specification; a project needs `--artifact`; and a `dispatch://PROJECT/artifact/<document-ref>`
-ref supplies both, where `document-ref` is the slug (an id or a filename resolves when no document has that slug). A file
-`dispatch artifact` uploaded reads its text at the latest or named version, or a description when it is not UTF-8 text.
-A picture (PNG, JPEG, GIF or WebP under 3,750,000 bytes, 5 MB of base64) is written to a file, and the command prints a
-`- picture: <path>` line with its type and size: open it with your file-read tool. That includes
-`dispatch://agent/<session id>/artifact/<slug>@vN`, one a person sent you on the Agents page. A session is shown each picture once,
-since the provider refuses a request over 32 MB: later reads and deliveries name it, and `dispatch doc-read` shows it again (after compaction too).
-
-Editing one is [Editing a document](skill://dispatch/references/document-edits.md): the shape of `dispatch doc-edit`,
-how to quote the text you mean, one `replace` per paragraph, preconditions against a stale edit, and
-what each operation costs a block's id and its anchors.
+- Name each version that records a decision with `dispatch doc-edit --summary`.
+- Read the current document with `dispatch doc-read` before you change it. `--blocks` lists block ids and tokens for edits. It also shows pictures: open a written picture file with your file-read tool.
+- Edit in place as [Editing a document](skill://dispatch/references/document-edits.md) says.
 
 ## Typed blocks
 
-A typed block (an `:::ask`, a callout) has its own syntax, attributes and refusals: write one only
-as [Documents](skill://dispatch/references/documents.md) says.
+Write an `:::ask` or a callout only as [Documents](skill://dispatch/references/documents.md#typed-blocks) says.
 
 ## Artifacts
 
-**Where a deliverable goes.** Text the human must read to decide — a draft message, a proposal,
-a summary — goes in the spec as a section: the spec is the one document they open. A separate
-artifact is for a real file: something sent as-is, a long report, a binary, a screenshot.
-
-When you do upload one, the spec links it as `dispatch://KEY/artifact/<slug>` (the slug the
-upload prints; it renders as a link) at the place the reader needs it, and the ask that needs the
-decision carries the same reference. A heading or a sentence naming the filename is not a
-reference.
-
-Uploading one (`dispatch artifact`, its slugs, versions and Markdown rules) is in
-[Documents](skill://dispatch/references/documents.md).
+- Text the human must read to decide (a draft, a proposal, a summary) is a section of the spec. An artifact is for a real file: sent as-is, a long report, a binary, a screenshot.
+- Link an uploaded artifact as `dispatch://KEY/artifact/<slug>` where the reader needs it, and in the ask that needs it. A filename is not a reference. Uploading: [Documents](skill://dispatch/references/documents.md#artifacts).
 
 ## Structure over stream
 
-Dispatch is a structured workspace, never a message stream. The structure IS the product:
-
-- **One issue per piece of work.** A new deliverable — an email to send, a document to review, a
-  decision with its own lifecycle — gets its own issue with the content as the issue's document
-  (spec artifact), not a message pile on an existing issue. If you are about to post a message
-  carrying a draft, a spec, or anything over a couple of paragraphs, stop: that is an issue with a
-  document, or an artifact on the issue it belongs to.
-- **Content lives in documents; decisions live in asks; messages only announce.** A draft the
-  human must read goes in the issue's spec (see [Artifacts](#artifacts)), which the dashboard renders with versions and margins; the
-  ask that needs their word references it (`--ref`, or the `dispatch://` link inline) instead of
-  restating it. A message never carries a body a human has to scroll.
-- **Never split one deliverable across a message + an ask that points at it.** Ask the question
-  with the document reference in the question text; the reader lands on the content in one click.
-
-The command answers your third consecutive message on an issue with no human reply with
-`You've sent N messages …`. That is the ledger pattern being named; stop and either wait or ask
-once.
+- One issue per deliverable (an email to send, a document to review, a decision with its own life), with the content as its document. A message that carries a draft, a spec or more than a couple of paragraphs is an issue or an artifact instead.
+- Content lives in documents, decisions in asks. Messages only announce. Never split one deliverable into a message and an ask that points at it: put the reference in the question.
+- `You've sent N messages …` means three messages in a row with no human reply. Then wait, or ask once.
 
 ## Messages
 
-Dispatch is a high-signal record for humans, not a log of what you are doing. A message is a reply to a human's message, or a
-change a human must know about now: a deliverable landed. Nothing else — no progress updates, no
-"starting X", no "still working", no restating the spec, no status on a timer. Your transcript is where work is narrated; the
-pull request is where it is summarised. One message that a human reads beats ten that train them to skip you.
+A message is a reply to a human's message, or a change a human must know now, such as a deliverable that landed. Never progress, "starting X", "still working", spec restatements or timed status. The PR summarises the work.
 
 ```bash
 dispatch message --issue <KEY> --body-file - <<'EOF'
@@ -473,26 +183,14 @@ dispatch message --issue <KEY> --body-file - <<'EOF'
 EOF
 ```
 
-The body is capped at 2,000 characters. A message is not a decision
-(a decision block, or `dispatch ask` for a human to-do) or document feedback (`dispatch comment`), and it does not wake anyone unless the issue is routed.
-
-**Pictures.** To show a screenshot inline, pass its path with `--image` (`dispatch message`, `dispatch comment`, `dispatch ask`);
-`dispatch read` writes the pictures what it shows embeds to files and prints their paths. Both are in [Documents](skill://dispatch/references/documents.md), "Artifacts".
-
-A BTW, Aside or Steer frame, or a message from the Agents page, is answered as
-[Targeted and direct messages](skill://dispatch/references/messages.md) says.
+- A message is not a decision or document feedback (`dispatch comment`). It wakes nobody unless the issue is routed.
+- Show a screenshot inline with `--image` on `message`, `comment` or `ask` ([Documents](skill://dispatch/references/documents.md#artifacts)).
+- Answer BTW, Aside, Steer and Agents-page messages as [messages.md](skill://dispatch/references/messages.md) says.
 
 ## Following
 
-You follow every ask you open or reply to: its answer, edits, resolution and replies reach you
-directly. A person's reply to a comment you started, and a person's new comment on a document you
-wrote, reach you directly too. Nothing else on an issue reaches you unless you subscribe to its
-topic. Leaving or rejoining a thread, and the topic to subscribe to, are in
-[Asks after they open](skill://dispatch/references/asks.md).
+You follow each ask you open or reply to. Replies to your comments and new comments on documents you wrote also reach you. Nothing else on an issue reaches you unless you subscribe ([asks.md](skill://dispatch/references/asks.md#following)).
 
 ## References
 
-The `dispatch://` form for each kind of node, and what it resolves to, is under
-[Reference forms](skill://dispatch/references/reading.md).
-
-**Every reference is a link, never an unlinked mention.** If you name a thing that has an address, link it: another issue, ask, comment, spec, or message (the `dispatch://` forms in [Reading back](skill://dispatch/references/reading.md)), an artifact (`dispatch://KEY/artifact/<slug>`), an eval (its viewer URL), a Slack message (its permalink), a Drive file (its share link). Bare phrases like "see this eval", "his 09-04 run", "the comment above", or "per the spec" with no link are banned: they make the reader hunt for what you already had in hand, and nothing can be traversed from them. Linking every reference is what makes a body both consumable and navigable. If a thing genuinely has no linkable address, say so; otherwise the link is not optional.
+Link every reference: an issue, ask, comment, spec or message ([reference forms](skill://dispatch/references/reading.md#reference-forms)), or an artifact. Link an eval by its viewer URL, a Slack message by its permalink, a Drive file by its share link. Never write "see this eval", "the comment above" or "per the spec" without a link. If a thing has no address, say so.