@sjawhar/opencode-legion-envoy 3.13.0 → 3.14.0

package/skills/dispatch/SKILL.md

@@ -15,6 +15,23 @@ the 800-character limit (850/800)`); it never truncates it. A tool call with sev
 (`<tool> was not called: N problems`), so one corrected call lands. GitHub threads and markers no
 longer exist.
 
+## 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.
+
+| When you are about to | Read |
+| --- | --- |
+| call `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) |
+| 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 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 tools do not cover | [Authentication and the HTTP API](skill://dispatch/references/api.md) |
+
 ## Design changes are brainstormed here
 
 Sami, 2026-09-17, verbatim: "Make sure your agents know that they should be doing brainstorming with me
@@ -59,29 +76,6 @@ vocabulary, and is often on a phone. Write for that person.
 - 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. Inferred from the AGENTC-186 12-hour-cap incident (platform PO, 2026-09-17).
 - When a Dispatch message states a root cause, include the reproducing command or test in that same message. 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. Inferred from the astro lane's 2026-09-16 retro (platform PO, 2026-09-17).
 
-## Agent authentication
-
-Use a personal Dispatch token: a human mints it in Dispatch **Settings → Agent tokens** and supplies
-it to the agent through `dispatch.token` in `~/.config/opencode/envoy.json` or `DISPATCH_TOKEN`.
-The server records the minting human as the owner of that session's writes. `DISPATCH_AGENT_TOKEN`
-is the shared devbox fallback; do not configure it for an individual agent.
-
-The deployed Dispatch server's browser origin is configured separately with
-`DISPATCH_SERVER_URL` in the deployment `compose/.env`. Do not change an
-agent's `envoy.json` to set the GitHub OAuth callback origin: the value must
-be the exact URL humans type in their browser, and the GitHub App callback is
-`<DISPATCH_SERVER_URL>/auth/callback`.
-
-### Finding a route
-
-The tools cover the everyday surface. For anything else, ask the server: `GET /api/v1` (no
-credential) returns every route as `{method, path, auth, description}` sorted by path — `auth`
-is `public`, `any` (a human or a bearer), `human` (a bearer gets `403 HUMAN_ONLY`), or `bearer`.
-A path Dispatch does not serve under `/api` or `/v1` answers
-`404 {"code":"NOT_FOUND","error":"no route for GET /v1/issues","hint":"GET /api/v1 lists every
-route"}`; when you see that, you typed the path wrong — read the index rather than guessing. Every
-`/api/v1` error body carries a `code`; branch on the code, never on the text.
-
 ## Writing a spec
 
 A spec has two readers: the human who decides reads the **Summary** and **New since we talked** at the top, then each decision through its [`:::ask` block](#decision-blocks) where it arises; the implementer who builds reads the rest. Use these headings in this order.
@@ -150,164 +144,31 @@ See [Typed blocks](#typed-blocks) for the syntax and [Before you ask](#before-yo
 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 tool: `issue` for an issue, or `project` and `artifact` for an unlinked project document (see
-[References](#references) for the resulting ref shape). An external issue reference addresses the existing Dispatch issue linked to
+[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, call
 `dispatch_issue({ external: "owner/repo#n", project: "<project>", title: "<title>" })` before addressing it.
 
-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 GitHub login of the human who answers the issue's asks, or `null` when nobody holds it. `dispatch_read` of an issue prints it as `Assignee: <login>` or `Assignee: unassigned`.
-
-### Who answers an ask
-
-An ask goes to the issue's assignee: their Inbox opens on **Mine**, which lists asks on the issues they hold plus an Unassigned band; an ask on an unassigned issue waits in that band for someone to take it. Find out who Dispatch takes you for with:
-```ts
-dispatch_whoami({})
-```
-It returns `details` `{ session, owner, service }`: `owner` is the lowercase login of the human whose personal token you run under, or `null` under the shared token or a verified service token, in which case `service` is that token's subject (`system:serviceaccount:<namespace>:<name>`, `null` otherwise) and every write you make is rendered `(as <namespace>/<name>)` — the namespace is kept because every namespace has a `default` service account, and a subject that is not a Kubernetes one is shown whole. An issue you create without `assignee` goes to your owner; with no owner it inherits its parent's assignee, or stays unassigned without a parent. If an issue you are asking on is unassigned and the answer matters, assign it to your owner (`PATCH /api/v1/issues/{key}` with `{"assignee": "<login>"}`; any authenticated caller may reassign, and an unlisted login is refused with `ASSIGNEE_NOT_ALLOWED`) or name in the question who should answer it. Never reassign an issue a human holds to get an answer faster: that is the human's call.
-
-Architects create newly tracked child work with:
+Create an issue for newly tracked work with:
 ```ts
 dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: string[], priority?: 0 | 1 | 2 | 3, assignee?: string })
 ```
-`labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. `priority` is yours on creation too — see [Priority is yours to set](#priority-is-yours-to-set). Set `assignee` (a GitHub login on the sign-in allowlist) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. It returns
+`labels` are optional initial labels: 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` (a GitHub login on the sign-in allowlist) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. It returns
 `details` `{ issue }`; 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 `spec` is supplied,
 follow [Writing a spec](#writing-a-spec).
 
-## Choosing what to work on
-
-When you finish an issue, or are told to work on the next thing, take the top ready issue of the
-whole backlog, across every project: status `todo`, highest priority first, then board rank. There
-are no areas: a standing role, a product owner and a lane each take the top issue like everyone
-else (Sami, 2026-09-27, dispatch://AGENTC-34/ask/01ed2956-73cc-48d2-8ed4-7a86c6d439b1). `todo`
-means ready: specced, unblocked, and waiting on neither a deploy nor a decision. An issue that
-waits on one belongs in `backlog`, with what it waits on said on the issue.
-
-Hold at most three issues in flight (`in_progress`, `testing`, `needs_review` or `retro`), of any
-kind (Sami, 2026-09-27, answering dispatch://AGENTC-34/ask/1aeb8f2e-0950-4eaa-aaac-24286c9dd3ca;
-the question proposed two, and his answer set three). The limit is per agent and has nothing to do
-with the week's priorities (Sami, 2026-09-28, reply a7647eb0 on
-dispatch://AGENTC-393/ask/b773d9f6): the priorities decide only what you pull next. Past three:
-push any unfinished work, say where in one comment on the issue, move it to `backlog` and clear
-its route. Each issue counts on its own; a child does not ride under its parent's slot.
-In-flight issues with no owner at all go
-back to `backlog` as well: no claim or route held by a live session, no Dispatch activity in the
-last day, and no pull request moving on GitHub (an owner working there leaves no Dispatch trace).
-The order keeper sweeps those. Never write the status of an issue that carries the `legion`
-label, or of any issue under one: the Legion daemon writes those statuses, and moving one of its
-admitted roots out of its flow parks the tree and stops its workers.
-
-One agent keeps the backlog's order against those priorities, with Sami
-(dispatch://AGENTC-34/ask/f6780f9e-8b96-49eb-9be7-7c7f2036d5cc). Setting an issue's priority
-stays yours ([Priority is yours to set](#priority-is-yours-to-set)); reordering the board does not.
-When the top of the backlog looks wrong, or a priority's next step is not yet a ready issue,
-publish it to `notifications.role.backlog-order`, which the order keeper holds, instead of
-reordering the board yourself.
-
-## Claim the issue before you work it
-
-Two sessions once spent a night implementing the same issue, because nothing on it said who was
-on it (Sami, 2026-09-24, verbatim: "It seems like we need a better way of tracking what's already
-in progress"). So 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
-```
-
-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
-`· 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
-you find work nobody is on.
-
-- **`409 ISSUE_CLAIMED` means someone else holds this issue.** When it is another session, the
-  refusal names it and says it is still running: do not work the issue in parallel — message
-  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
-  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
-  refusal by a live holder.
-- **A claim whose session has ended is yours to take.** If the Envoy listener no longer lists
-  the holder, your claim simply succeeds; the takeover is recorded on the issue and the session
-  that lost it is told.
-- **Release it when you stop** — finished, handing over, or moving to something else. A claim is
-  released by its holder or any human — and by any agent once the holder's session is no longer
-  running, the same rule that lets you take it. Closing the issue releases it for you.
-- A claim is intent to implement, not contact: reading the issue, commenting, asking, or gating
-  its pull request claims nothing, so a coordinator never collides with an implementer.
-
-**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 (Sami, 2026-09-24, verbatim: "Keep them separate — Separate because humans might be
-using them to keep track of work"). So when you start: `dispatch_claim({ issue })` **and**
-`dispatch_issue_update({ issue, status: "in_progress" })`.
-
-## Issue status is yours to move
-
-The issue's status is how a human sees delivery without asking a session. Outside Legion (where
-the daemon writes it), the session doing the work moves it, the way a person moves a card:
-`in_progress` when implementation starts, `testing` when the change is being proven on a
-production-like surface, `needs_review` when its pull request is open and waiting on the merge
-queue, `done` when the change has been driven in production (a merge is not `done`). Move child
-issues you own as well as the root. An issue left at `triage` while work is underway is a defect:
-Sami, 2026-09-15, on the roadmap he could not read — "I'm not even sure what their development
-status is." 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: "AGENTC-175", status: "testing" })
-dispatch_issue_update({ issue: "AGENTC-175", status: "done", reason: "Shipped in owner/repo#7; verified on the production dashboard." })
-dispatch_issue_update({ issue: "AGENTC-175", priority: 1 }) // 0–3; see Priority is yours to set
-dispatch_issue_update({ issue: "AGENTC-175", external_links: ["https://github.com/owner/repo/pull/7"] })
-dispatch_issue_update({ issue: "AGENTC-175", parent: "AGENTC-170" }) // same-project key; "" clears the parent
-```
-
-Closing takes a `reason`, and the tool 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.
-
-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
-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
-when work has started.
-
-## Priority is yours to set
-
-Priority is the coarse bucket a backlog is read by: `0` is P0, the highest, through `3`, P3, the
-lowest, and `null` clears it. Sami ruled on 2026-09-24, answering "may agents set issue priority
-(P0–P3), or only propose it for you?" on `dispatch://LEGION/artifact/issue-status-conventions-md`:
-**"Agents may set"**. So set it — on creation, and on a grooming pass over issues that have none —
-and say what you set and why; he overrides anything he disagrees 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:
-reorder it the way [Issue reads](#your-owner) describes, through `PATCH /api/v1/issues/{key}`.
-
 ## Search first
 
-Before you create an issue or start a design document, search:
+`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:
 ```ts
 dispatch_search({ query, project?, limit? })
 ```
-It returns every issue, document, comment, ask, and message that contains the words. Issue-owned hit lines
-start with the issue key; standalone project-document hit lines start with
+Websearch syntax applies: `"merge queue"`, `-daemon`, `OR`. It returns the best `limit` hits (20
+by default, 50 at most) across issues, documents, comments, asks, and messages. Issue-owned hit
+lines start with the issue key; standalone project-document hit lines start with
 `dispatch://PROJECT/artifact/<slug>`, followed by the absolute link. Cite the hit you build on
-(`dispatch://KEY` or the document reference), or state "no prior issue" in the spec. Websearch syntax applies:
-`"merge queue"`, `-daemon`, `OR`.
+(`dispatch://KEY` or the document reference), or state "no prior issue" in the spec.
 
 `dispatch_issue` refuses a title that near-duplicates an issue in the same project and returns the candidates (`POSSIBLE_DUPLICATE`).
 Read them; reference the existing issue, or repeat the call with `force: true` when it is genuinely new work.
@@ -316,75 +177,6 @@ merge" pairs with "four CI gates that cannot fail a merge". So when you force pa
 the new issue a title that names what differs where you can, and open its spec's Summary with the
 distinction from the named issue, citing it (`dispatch://KEY`), for whoever reads the next pairing.
 
-## 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? })
-```
-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` caps the rows at 50 by
-default and 250 at most.
-
-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 })
-```
-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
-carries a claim, is work under way ([Issue status is yours to move](#issue-status-is-yours-to-move))
-and is not re-staffed. A todo with a finished spec reads as queued work that nobody is doing
-(LEGION-173 sat in todo for two weeks with a complete spec; AGENTC-1010's v4 plan sat in backlog
-with nobody building it).
-
-A close that says the defect cannot happen cites the code that makes it impossible. An issue
-closed because a rewrite forecloses it names the file and line in the rewrite that does so; a
-close that cannot name one is not foreclosed, it is unread. The cheapest way for a rewrite to reach
-parity is to port the code, defect included: LEGION-211's bare `git worktree prune`, filed against
-the TypeScript daemon, had been ported into the Go coordinator and was live in production.
-
-The audit finds four shapes:
-
-- **Unstaffed work.** A plan or measurement exists, and no one is building it.
-- **Unrecorded delivery.** An issue not yet in `testing` or `done`, claimed or not, has a merged PR
-  naming it. Check the change live, then move the issue (AGENTC-1033 sat at `triage` after its fix,
-  agent-c #20367, merged).
-- **Unrecorded practice.** Someone does the issue's work by hand, more than once, while the issue
-  sits in backlog (OPS-132, done by hand on every migration merge). It leaves no plan and no PR to
-  find; the tell is your own messages. Doing something by hand more than once means an issue is
-  wearing the wrong status.
-- **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 })
-  ```
-  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 is a restart gap as
-  often as a vacancy: an agent box that restarts or resumes keeps the session id, but the session
-  is absent from the listener for minutes, and its role with it. On 2026-09-27, 58 of 63 session
-  routes one read showed as unreachable pointed at a single session that was moving between boxes.
-  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
-  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 (AGENTC-1065, a P2 production listener
-  503, sat routed to an unheld `role:sre` with no assignee). `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.
-
-Run the audit as a step of a coordinator's loop, at each checkpoint, not as a habit: these shapes
-are found by running the check, not by noticing them.
-
 ### Symptom versus cause
 
 When a symptom and its cause sit on different issues, the work accrues to the cause's issue, and
@@ -394,6 +186,30 @@ the fix, not the one naming the symptom. A symptom issue gathering messages with
 is the tell. (The production freeze was iterated on AGENTC-546, the failing gate, while its cause
 and answer sat on AGENTC-1010.)
 
+## 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.
+```ts
+dispatch_claim({ issue: "LEGION-234" })                  // I am implementing this
+dispatch_claim({ issue: "LEGION-234", release: true })   // 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).
+
+## Issue status is yours to move
+
+Claiming and moving the status are two actions, and you do both: when you start,
+`dispatch_claim({ issue })` and `dispatch_issue_update({ issue, 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).
+
 ## Asking
 
 ### Before you ask
@@ -510,26 +326,7 @@ that follow from it:
 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).
 
-## 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.
-
-```
-dispatch_issue({ project: "CORE", title: "...", components: { mode: "explicit", ids: ["dispatch-server", "web"] } })
-dispatch_issue_update({ issue: "CORE-12", components: { mode: "explicit", ids: ["web"] } })   // this issue's own set, replacing what it inherited
-dispatch_issue_update({ issue: "CORE-13", components: { mode: "none", reason: "hiring, not code" } })
-dispatch_issue_update({ issue: "CORE-14", components: { mode: "inherit" } })                  // back to the parent chain's attachment
-```
-
-No native Dispatch tool 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.
-
-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" })
-```
-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`.
+### When you need a human
 
 Before saying you are waiting for human input, call `dispatch_open_asks`. With no arguments 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 })` it lists every open ask in that project — on its issues and on its documents, whoever authored them — which is how you audit what a whole project is waiting on rather than just your own asks.
 
@@ -546,73 +343,24 @@ blocker. Before asking, try to remove the step: a value already on the machine,
 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.
 
-A to-do handed to a human is an ordinary question: phrase the to-do as the question and give it
-the options that name its outcomes, in the human's words - there is no fixed vocabulary and the
-server treats no label specially. If an outcome needs a reason, say so in that option's
-description, and the human's free-text answer carries it:
-```ts
-dispatch_ask({ issue: "DSP-42",
-  question: "Run the production deploy for #19125?",
-  options: [{ label: "Deployed" }, { label: "Blocked", description: "Say what is missing." }] })
-```
+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), see
+[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.
 
-Correct or refine an open ask in place instead of opening a second question:
-```ts
-dispatch_edit_ask({
-  ask,
-  question?,
-  options?: { label, description? }[],
-  multiple?,
-  urgency?,
-})
 ```
-At least one field besides `ask` is required. Use this only while the same decision remains open: it keeps the prior text in the event
-log and invalidates any answer draft against the prior `edited_at` revision, so the human sees the new wording and explicitly reconfirms.
-An answered or resolved ask cannot be edited. If the decision is moot or superseded, retract the old ask and open a new one.
-
-An ask that lives as an `ask` block in a document keeps its question and options in the block, and `dispatch_edit_ask` writes the
-block along with the row, so the edit stands and the document reads the same. It changes only the fields you name: pass `urgency`
-alone and the question's own wording, formatting, links and comment anchors are untouched. Pass `question` or `options` and that part
-is rewritten, so anchors inside the text you replaced move as they would for any document edit. Either way it is a document edit: it
-writes a new version, which on a spec awaiting approval closes the design gate until the new version is approved. Editing the block
-with `dispatch_doc_edit` works too and is the way to change anything else about it, including adding formatting to a question.
-Re-sending a field unchanged rewrites nothing, so retrying the whole ask is safe.
-Text the block cannot carry back unchanged is refused outright, naming the field and writing nothing - an option label containing
-`": "`, the separator between a label and its description, is one example of text that cannot survive the round trip. Blank lines separate paragraphs;
-a single newline is kept as a line break.
-
-An ask stays open until a human answers, unless its question no longer needs that answer. Retract a moot or superseded question, or
-self-resolve one after finding the answer:
-```ts
-dispatch_resolve_ask({
-  ask,
-  kind: "retracted",
-  reason: "A newer ask supersedes this question.",
-})
+dispatch_issue({ project: "CORE", title: "...", components: { mode: "explicit", ids: ["dispatch-server", "web"] } })
+dispatch_issue_update({ issue: "CORE-12", components: { mode: "explicit", ids: ["web"] } })   // this issue's own set, replacing what it inherited
+dispatch_issue_update({ issue: "CORE-13", components: { mode: "none", reason: "hiring, not code" } })
+dispatch_issue_update({ issue: "CORE-14", components: { mode: "inherit" } })                  // back to the parent chain's attachment
 ```
-Use `retracted` when the question is obsolete and `resolved` when you found the answer. Include the reason because the question remains
-in its Conversation card and reply thread; a reason beginning `removed from the document in version` is refused, because that is how a
-retraction the document's own settlement wrote is recognised. Resolving a block ask records it in the block too, so it stays resolved
-however the document moves afterwards — while deleting the block from the document is the other way to close one, and putting the block
-back reopens it. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
-resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `reply_to_ask` on
-`dispatch_comment` (mutually exclusive with `reply_to`).
-A review comment you opened has its own closer, `dispatch_resolve_comment` — see
-[Comments and suggestions](#comments-and-suggestions).
-
-A human answers or asks back from the same field; a question-shaped free-text answer is offered as a clarification first. A human
-reply while your ask is still open (the delivered `comment.created` carries `ask_state: open`) is a request for clarification, not
-an answer: the human did not understand the question or needs more before choosing. The ask now waits on you in their Inbox. Answer
-in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with `dispatch_edit_ask` when the wording
-was the problem; either puts the ask back in front of them. Do not open a second ask.
-
-Every reply to an open ask says whose turn it is next, and the Inbox files the ask by that, not by who spoke last. Your plain reply
-(`turn` omitted, or `turn: "human"`) hands the turn to the human: the ask returns to their `Waiting on you`. When you are not done
-yet — "dispatched two auditors, back with results", "checking the release branch, back shortly", any working-on-it note — reply with
-`turn: "agent"`: the note lands in the thread, the ask stays under `Waiting on agents`, and the human is not told to act. Use
-`turn: "agent"` for every progress note and `turn: "human"` (the default) only when you need them. A human's reply always hands the
-turn to you. The result names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
-`ask_waiting_on`, and every ask read carries it as `waiting_on`.
+
+No native Dispatch tool 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)).
 
 ## Close what you opened
 
@@ -632,7 +380,7 @@ supersedes one, retract the old one with `dispatch_resolve_ask` and kind `retrac
 turn.
 
 See [Following](#following) for why you receive what happens to asks you open and
-[What comes back](#what-comes-back) for finding them again with `dispatch_open_asks`.
+[What comes back](skill://dispatch/references/reading.md) for finding them again with `dispatch_open_asks`.
 
 ## Approval of a spec
 
@@ -666,146 +414,17 @@ omitted `artifact` reads the issue specification; a project needs `artifact`; an
 `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).
 
-Editing one is [Editing a document](references/document-edits.md): the shape of `dispatch_doc_edit`,
+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.
 
-## A document that is reloading
-
-These calls can answer `DOC_SERVICE_UNAVAILABLE` (HTTP 503), because each writes a document inside its
-transaction: `dispatch_doc_edit`; `dispatch_ask` and `dispatch_comment` on a quote; a `dispatch_comment` reply
-in a thread whose first comment is anchored; `dispatch_suggest`; `dispatch_resolve_comment` on an anchored
-comment; `dispatch_artifact` replacing a document that already exists; and, on an ask that lives in a `:::ask`
-block, `dispatch_edit_ask` and `dispatch_resolve_ask`, which write that block. Creating an issue with a spec,
-uploading a new document, `dispatch_request_approval` and `dispatch_message` never answer it, and neither do
-`dispatch_edit_ask` and `dispatch_resolve_ask` on an ask that has no block. It means that document's live room
-failed and is reloading from its durable copy, so the server refused rather than wait for it; your call wrote
-nothing and the document is intact. Nothing retries it for you: the Dispatch client hands a 503 straight back.
-Wait a few seconds and make the same call again. A second refusal in a row is worth telling your human about,
-with the document's reference.
-
-`dispatch_doc_read` can answer it too, though it writes nothing: a read never opens a live room, and waits out
-a room that is reloading, so it is refused only when the document's durable copy cannot be read or decoded.
-Retry it the same way.
-
 ## Typed blocks
 
-The server declares typed document blocks at `GET /api/v1/schema/blocks`. Write one only with the
-container-directive form `:::name{#block-id key="value"}` on its own line, ordinary block children,
-and a closing line of as many colons at the same nesting. A typed block directly inside another needs the outer
-one's fence a colon longer (`::::callout{…}` around a `:::callout{…}`), and so does one whose code holds a `:::` line;
-Dispatch writes its fences that way. An unclosed typed block at document level is rejected. For
-a new typed block, omit `#block-id`; Dispatch mints it. When editing an existing typed block, retain
-its id and every rendered attribute. Never copy an existing block's id into new markdown: an id
-names one block, so an insert, upload or suggestion whose markdown names an id the document holds
-outside the text it replaces is refused naming the id: `INVALID_OP` for an insert,
-`INVALID_MARKDOWN` for any other write. To rewrite such a block whole, `delete` it and then
-`insert` the new one carrying its id, anchored on the block before or after it, in that order and
-in one batch: an insert carrying an id the document still holds is refused.
-
-Use only the type names, content rule, attributes, and enum values returned by the schema. Values are
-quoted: `:::callout{kind="warning" title="Risk"}`. Do not write Pandoc-style `::: {.callout}`, leaf
-`::name` directives, or text `:name` directives; those strings are literal when quoted inside a code
-block. Do not set attributes the schema marks `server: true`; the server ignores them and reasserts
-its authoritative value at settlement.
-
-Questions about a document must be `ask` blocks, never an `Open questions` prose section. An ask
-body is one or more question paragraphs followed by an optional bullet list of options, where each
-item is `Label: description`. A spec, an uploaded document or an uploaded version holding an ask that
-breaks that shape - a code block, heading or quote in it, a paragraph after its options, a second
-list - is refused with `INVALID_ASK_BLOCK`; so is an edit that writes one. An ask someone left
-unreadable in the browser refuses nothing it is carried through unchanged by. For example:
-
-```md
-:::ask{urgency="high" multiple="false"}
-Should we ship the migration?
-
-- Ship: Release the verified change.
-- Hold: Wait for another review.
-:::
-```
-
-When a human answers a decision written as an ask block, the answer lives on that ask. Use
-`dispatch_resolve_ask` when the decision is resolved without a human response, or preserve the
-human's answer; never rewrite the question into its answer or blank its options. An edit that leaves
-an ask block without a question or with a blank option is rejected with `INVALID_ASK_BLOCK`.
-
-## Comments and suggestions
-
-Add feedback with:
-
-```ts
-dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask?, turn? })
-```
-
-It returns issue or project-document owner details plus `comment`; a `reply_to_ask` reply also returns `ask` and `follows: { ask }`,
-because replying to an ask makes you one of its followers (see [Following](#following)).
-`ref` names the owner (an issue or project-document reference) in place of `issue`/`project`.
-`quote` requires `artifact`; its anchor is pinned to the containing block while retaining the quote
-for display. Omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no
-`quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server keeps
-threads flat. A reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a
-question asked with `dispatch_ask`; `turn` (only with `reply_to_ask`) says who holds the turn after
-the reply — `agent` for a progress note that keeps the ask waiting on you, `human` (the default) when
-the human needs to act; see [Asking](#asking). Comments are edited only by their author from the
-dashboard. A delivered `comment.created` event carries the comment `id`; reply to it with
-`dispatch_comment({ reply_to: <id> })`.
-
-Resolve your own review comment once you have addressed it:
-
-```ts
-dispatch_resolve_comment({ comment })
-```
-
-`comment` is the comment id, or a `dispatch://KEY/comment/<id>` or `dispatch://PROJECT/artifact/<slug>/comment/<id>` reference (an
-8+ character id prefix is resolved against the owner's comments). It returns the owner details plus `comment`, and takes no reason —
-say what you did in a `reply_to` first if the thread needs it. The server lets any session or human resolve any open comment, so
-resolve only threads you opened or were asked to close; reopening a resolved thread is human-only (from the dashboard), though your
-reply to it reopens it. Asks are closed with `dispatch_resolve_ask` instead.
-
-An exact replacement for document text is a suggestion (`dispatch_suggest`), never a comment; a
-comment is for a question or a note the human answers in words. A human accepts a suggestion with
-one click and cannot accept a comment, so propose the replacement instead of describing it:
-
-```ts
-dispatch_suggest({ issue?, project?, artifact, ref?, quote, replace_with, body?, occurrence? })
-```
-
-It returns issue or project-document owner details plus `comment`. A human accepts or rejects a suggestion.
-Errors: `TARGET_AMBIGUOUS` (add `occurrence`), `TARGET_NOT_FOUND` (re-read first), `INVALID_ANCHOR`/`ANCHOR_MISSING`/`ANCHOR_ORPHANED`
-(bad, unwritten, or stale quote), `INVALID_MARKDOWN`/`DOC_SCHEMA` (malformed content), `CAP_EXCEEDED`, `ISSUE_CLOSED`.
-Suggest only what the quoted block can hold. The accept, not the suggestion, checks that: an
-accept whose `replace_with` would break an ask block that was readable before it is refused with
-`INVALID_ASK_BLOCK` - a question given a code block, text after an ask's options, a second option
-list, or an emptied question; one that names an id the document holds outside the text it
-replaces, an ask under a held id included, with `INVALID_MARKDOWN`; and one no part of the
-document can hold where it sits (a code block over a table cell's whole text), or whose quote runs
-into an ask or callout from the text before it, with `INVALID_OP`. Either changes nothing: the human sees the reason with no Retry, and the suggestion
-stays open until someone rejects or replaces it.
+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.
 
 ## Artifacts
 
-Attach an image, diagram, or local file with:
-
-```ts
-dispatch_artifact({ issue?, project?, name, path, summary? })
-```
-
-Or, when the text is already in the call, post a Markdown document directly:
-
-```ts
-dispatch_artifact({ issue?, project?, name: "load-test-results.md", content: "# Load test\n..." })
-```
-
-Exactly one of `issue` and `project` is required. A project upload creates an unlinked project document; it must not include `artifact`.
-Exactly one of `path` and `content` is required. It returns issue or project-document owner details plus `artifact` and `version`.
-Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
-with your text. Never do that: the spec is edited in place with `dispatch_doc_edit` (see [Editing a document](references/document-edits.md)). Address an existing
-artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
-slug also arrives on `artifact.created` events. Dispatch suffixes a slug two documents would share, so one document's
-filename can be another's slug (`plan v2` takes `plan-v2`, then a document named `plan-v2` takes `plan-v2-2`): a bare
-`artifact` that names both is refused with each one's id, while a `dispatch://` reference's document part is always the slug.
-
 **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.
@@ -815,10 +434,8 @@ upload result; it renders as a link) at the place the reader needs it, and the a
 decision carries the same reference. A heading or a sentence naming the filename is not a
 reference.
 
-Documents are CommonMark. A bare `<https://example.com|text>` is a CommonMark autolink and is normalised: the angle brackets are
-dropped and the URL keeps `|text`. A backslash-escaped `\<https://example.com|text>` displays as `<https://example.com|text>` in the
-document but comes back re-escaped (`\<`) from `dispatch_doc_read`. A Slack mrkdwn draft, or any other payload that is not Markdown,
-still belongs inside a fenced code block, where it survives verbatim both ways.
+Uploading one (`dispatch_artifact`, its slugs, versions and Markdown rules) is in
+[Documents](skill://dispatch/references/documents.md).
 
 ## Structure over stream
 
@@ -832,7 +449,7 @@ high-signal, structured conversation"). The structure IS the product:
   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 a document artifact the dashboard renders with versions and margins; 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
@@ -856,216 +473,19 @@ dispatch_message({ issue, body })
 It returns `details` `{ issue, message }`. `body` is capped at 2,000 characters. A message is not a decision
 (`dispatch_ask`) or document feedback (`dispatch_comment`), and it does not wake anyone unless the issue is routed.
 
-### Targeted agent messages
-
-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 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:
-
-```ts
-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
-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
-through Envoy or the hub. 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 (`aside`, `btw`, `steer`);
-target only a session that advertises the mode you want. Sending to a session with no issue
-(`POST /api/v1/agents/{session_id}/messages`) stays human-only.
-
-### Answering a direct message
-
-A human can also message you directly from the **Agents** page, with no issue at all. 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:
-
-```ts
-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
-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`
-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
-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.
-
-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>" })
-```
+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.
 
 ## Following
 
-An ask has followers: every session that wrote to it — the session that opened it and every session that replied with
-`dispatch_comment({ reply_to_ask })` — plus any session a human adds from the ask card. The ask's answer, edits, resolution, and
-every reply on it reach each follower's own agent topic directly, whether or not the writer was a human and whatever the issue's
-route. The tool result says so (`You follow this ask: its answer and replies reach you directly.`) and carries `details.follows.ask`;
-the host tells you once per ask. Leave a thread you no longer need, or rejoin one, with:
-
-```ts
-dispatch_follow({ ask, action: "follow" | "unfollow" })
-```
-
-`ask` is the full ask id or a `dispatch://KEY/ask/<id>` reference; `dispatch_follow`, `dispatch_edit_ask`, and
-`dispatch_resolve_ask` also take an 8+ hex prefix that is unique among your own open asks, and refuse anything shorter by naming
-those asks. A human may also remove you from the ask card; either way you are
-told with an `ask.follower_removed` notice, and a human adding you arrives as `ask.follower_added`.
-
-No write subscribes you to an issue or document. Following covers your own asks and the threads you joined; everything else on the
-owner — other sessions' asks, comments, messages, status changes — reaches you only if you subscribe to the owner topic yourself.
-Every write result names that line: `envoy_subscribe notifications.dispatch.issue.<KEY>.>` for an issue,
-`envoy_subscribe notifications.dispatch.document.<PROJECT>.<SLUG>.>` for a project document. The owner topic carries every Dispatch
-event; `notify` only controls agent wake and routed delivery. A human may unsubscribe you from the issue or document header; you
-are told with a `subscription.removed` notice when that happens.
-
-## What comes back
-
-After a restart, catch up with:
-
-```ts
-dispatch_read({ issue?, project?, artifact?, ref? })
-```
-
-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.
-
-Every read ends with two sections from the reference graph. `Referenced by:` lists what points at the node — every document, ask,
-comment, or message that cites it, plus its structure: child issues, attached documents, anchored and owned asks and comments, replies,
-followers — and `Links:` lists what it cites. Each row is `- <edge kind> <node kind> dispatch://… (<excerpt> · <when>)`; for a
-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
-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.
+You follow every ask you open or reply to: its answer, edits, resolution and replies reach you
+directly. 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).
 
 ## References
 
-**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 below), 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.
-
-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
-either form — an issue key or a project key is never ambiguous, since a project key never
-contains a dash:
-
-```text
-dispatch://KEY
-dispatch://KEY/spec
-dispatch://KEY/artifact/<slug>[@vN]
-dispatch://KEY/ask/<id>
-dispatch://KEY/comment/<id>
-dispatch://KEY/message/<id>
-dispatch://PROJECT/artifact/<document-ref>[@vN]
-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
-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` /
-`COMMENT_ID_INPUT` / `MESSAGE_ID_INPUT`, never a 500.
-
-## Before / after
-
-Before — a wall of text hides the decision and makes the choices unclickable:
-
-```text
-We need to settle the release gate because the deploy branch has the migration and the
-dashboard changes, I checked the staging result and it is fine except the release notes are
-not reviewed, so should we ship today, wait for docs, or cut the dashboard from this release?
-I think waiting is safest but the customer demo is tomorrow and the list above is probably stale.
-```
+The `dispatch://` form for each kind of node, and what it resolves to, is under
+[Reference forms](skill://dispatch/references/reading.md).
 
-After — anchor the decision and make each option a button:
-
-```ts
-dispatch_ask({
-  issue: "LEGION-815",
-  question:
-    "Choose the release gate. Recommendation: ship after release-note review, since the tested deployment is otherwise ready.",
-  options: [
-    { label: "Review notes, then ship", description: "Keeps the release intact and reviewed." },
-    { label: "Ship now", description: "Meets the demo deadline; release notes follow later." },
-  ],
-  urgency: "high",
-  anchor: { artifact: "spec", quote: "Release requires reviewed operator instructions before deployment." },
-})
-```
-
-Before — a progress note that nobody needs, posted where humans look for decisions:
-
-```ts
-dispatch_message({ issue: "LEGION-815", body: "Merged the release PR, moving to docs next." })
-```
-
-After — nothing. The merge is visible on the pull request; the docs work shows up as its own deliverable. Post a message only when
-a human must act or a deliverable is theirs to use:
-
-```ts
-dispatch_message({
-  issue: "LEGION-815",
-  body: "Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.",
-})
-```
-
-Before — a draft the human must read is uploaded as a separate file, the spec only names it, and
-the ask does not point at it, so the reader has to go looking:
-
-```ts
-dispatch_artifact({ issue: "OPS-52", name: "cu-update-2026-09-15.md", content: "Hi team, ..." })
-dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
-  { op: "insert", after: "## Context", markdown: "## Draft (artifact cu-update-2026-09-15.md)" },
-]})
-dispatch_ask({ issue: "OPS-52", question: "Send the customer update as drafted?", options: [...] })
-```
-
-After — the draft is a section of the spec, and the ask anchors there. If it really must be a
-file (something to send as-is), the spec and the ask both link the slug from the upload result:
-
-```ts
-dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
-  { op: "insert", after: "## Context", markdown: "## Draft\n\nHi team, ..." },
-]})
-dispatch_ask({
-  issue: "OPS-52",
-  question: "Send the customer update as drafted?",
-  options: [...],
-  anchor: { artifact: "spec", quote: "Hi team," },
-})
-// or, for a real file — the spec links it where the reader needs it, and so does the ask:
-dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
-  { op: "insert", after: "## Context", markdown: "## Draft\n\nThe update to send as-is: dispatch://OPS-52/artifact/cu-update-2026-09-15-md" },
-]})
-dispatch_ask({
-  issue: "OPS-52",
-  question: "Send this customer update as-is? dispatch://OPS-52/artifact/cu-update-2026-09-15-md",
-  options: [...],
-})
-```
+**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.