@sjawhar/pi-envoy 0.0.0 → 8.1.0

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

@@ -0,0 +1,116 @@
+# Asks after they open: who answers, editing, resolving, replying, and following
+
+`skill://dispatch` sends you here once you are asking: to find who answers an ask, hand a human a
+to-do, edit or retract an ask, answer a clarification, say whose turn it is, or follow or leave its
+thread. Whether to ask at all, and how to write the question, is "Before you ask" in
+`skill://dispatch`.
+
+## Who answers an ask
+
+An ask goes to the issue's assignee: their Inbox opens on **Mine**, which lists asks on the issues they hold plus an Unassigned band; an ask on an unassigned issue waits in that band for someone to take it. Find out who Dispatch takes you for with:
+```ts
+dispatch_whoami({})
+```
+It returns `details` `{ session, owner, service }`: `owner` is the lowercase email of the person whose personal token you run under, or `null` under the shared token or a verified service token, in which case `service` is that token's subject (`system:serviceaccount:<namespace>:<name>`, `null` otherwise) and every write you make is rendered `(as <namespace>/<name>)` — the namespace is kept because every namespace has a `default` service account, and a subject that is not a Kubernetes one is shown whole. An issue you create without `assignee` goes to your owner; with no owner it inherits its parent's assignee, or stays unassigned without a parent. If an issue you are asking on is unassigned and the answer matters, assign it to your owner (`PATCH /api/v1/issues/{key}` with `{"assignee": "<email>"}`; any authenticated caller may reassign, and an email nobody has signed in with is refused with `ASSIGNEE_NOT_ALLOWED`) or name in the question who should answer it. Never reassign an issue a human holds to get an answer faster: that is the human's call.
+
+## Handing a human a to-do, editing, resolving, and replying
+
+A to-do handed to a human still follows the question and options contract that `skill://dispatch`'s
+"Writing for the human" states. For a human-only action, what it changes and risks constrains the
+answer. There is no fixed vocabulary and the server treats no label specially.
+If an outcome needs a reason, say so in that option's description, and the human's free-text answer
+carries it:
+```ts
+dispatch_ask({
+  issue: "DSP-42",
+  question:
+    "The verified fix remains unavailable in production because deployment is pending. Deploying changes production and could expose a deployment problem. How should we proceed? Recommendation: deploy the verified fix now because it restores the intended behavior.",
+  options: [
+    { label: "Deploy the verified fix", description: "Restores the fix but can expose a deployment problem." },
+    { label: "Hold the deploy", description: "Avoids a production change now but leaves production without the fix." },
+  ],
+})
+```
+
+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.",
+})
+```
+Use `retracted` when the question is obsolete and `resolved` when you found the answer. Include the reason because the question remains
+in its Conversation card and reply thread; a reason beginning `removed from the document in version` is refused, because that is how a
+retraction the document's own settlement wrote is recognised. Resolving a block ask records it in the block too, so it stays resolved
+however the document moves afterwards. `dispatch_doc_edit` refuses deleting the block of an open ask; a block removed another way, by a
+whole-document `dispatch_artifact` replace or by a person in the browser, closes its ask, and putting the block back reopens it. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
+resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `reply_to_ask` on
+`dispatch_comment` (mutually exclusive with `reply_to`).
+A review comment you opened has its own closer, `dispatch_resolve_comment` — see
+[Comments and suggestions](skill://dispatch/references/documents.md).
+
+A human answers or asks back from the same field; a question-shaped free-text answer is offered as a clarification first. A human
+reply while your ask is still open (the delivered `comment.created` carries `ask_state: open`) is a request for clarification, not
+an answer: the human did not understand the question or needs more before choosing. The ask now waits on you in their Inbox. Answer
+in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with `dispatch_edit_ask` when the wording
+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`.
+
+## 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.
+

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

@@ -0,0 +1,202 @@
+# Editing a document
+
+Every document a Dispatch tool writes — an issue's spec, a project document — is edited in place
+with `dispatch_doc_edit`, never re-uploaded. "The Spec" in `skill://dispatch` sends you here for
+the tool's shape, how to target the text you mean, what each operation costs a block, and how to
+reject a stale edit.
+
+```ts
+dispatch_doc_edit({ issue?, project?, artifact, ops, precondition?, summary? })
+```
+It returns issue or project-document owner details plus `applied`, optional `version`, `changed`,
+`unchanged_ops`, `lost_ops`, and the document token this edit produced, rendered as a
+`Document token: <token>` line. `ops` is an array of this exact `EditOp` shape:
+
+```ts
+type EditOp = {
+  op: "replace" | "delete" | "insert" | "retype" | "move" | "delete_row" | "delete_column";
+  find?: string;
+  with?: string;
+  occurrence?: number;
+  markdown?: string;
+  after?: string;
+  before?: string;
+  block?: string;
+  index?: number;
+  type?: string;
+  attributes?: Record<string, unknown>;
+};
+```
+
+An operation takes only these keys. A key it does not declare is refused before the call leaves
+your process, naming the operation and its keys, because every key but `op` is optional: a
+misspelled `with` would otherwise be dropped and the `replace` would delete the text you meant to
+rewrite.
+
+Target `replace`, `delete`, and quote insert anchors by a block's text as rendered: write inline
+code without backticks, bold without asterisks, and link text without link syntax. A table-cell
+anchor is its cell text. Quote code-block contents without their Markdown fences. A quote must stay
+within one textblock; split changes that span separate blocks into separate operations.
+
+`replace` requires `find` and `with`; `delete` requires `find` or `block`; `insert` requires `markdown` and exactly one of `after` or
+`before`; `move` requires `block` and exactly one of `after` or `before`; and `delete_row` / `delete_column` each require a table
+`block` plus a zero-based `index`. An insert or move anchor is a quote, `"start"`, `"end"`, `"heading:Title"`, or `"block:<id>"`.
+Ordinary inserts create a sibling block before or after the quote, heading, or block's enclosing document block, and a move lands the
+block at that same boundary; `"start"` and `"end"` select the document edges. At a table-cell quote, a body-row fragment (no header or
+delimiter rows) extends that table before or after the matched row instead, decided in three steps. A fragment whose every line yields
+a cell and an unescaped `|` (a lone `|` yields no cell, and a line whose only pipe is `\|` has no separator), with no line a delimiter
+row of three hyphens or more a cell, is parsed as rows of that table. What that parse refuses is refused: a row holding text past the
+table's width as `TABLE_WIDTH` (blank cells there are dropped), a line the table cannot hold as a row (indented code, `2. | a | b |`)
+as `INVALID_OP`. When it refuses nothing and reads every line as a row, the rows are inserted, short ones padded. Any other fragment is
+read on its own as blocks, which are inserted after the table or refused as such blocks would be: a whole table you paste there, its
+delimiter row three hyphens or more a cell, becomes a second table, while one with any delimiter cell of one or two hyphens (`| - |`,
+`| --- | - |`) passes the first step, so its header and delimiter rows are inserted as rows of the table, or refused as `TABLE_WIDTH`
+where it is wider than the table. Deleting
+a cell's quoted text removes only that text. `delete_row` / `delete_column` instead mutate their named table in place, keeping the
+table's block id. A row index includes the header: row `0` is the header and its deletion promotes the first body row. The last body
+row and any row's last column cannot be deleted. An index is required. A missing, non-integer, negative, or out-of-range index is
+`INVALID_OP` on `index`, naming the supplied value and the table's actual dimensions before making any change. Markdown parsing
+canonicalizes short ragged rows by padding missing cells, so column deletion preserves every non-selected cell in the canonical table.
+`GET /api/v1/artifacts/<artifact UUID>/blocks` reports a table's own references plus its descendant cell anchors.
+`GET /api/v1/artifacts/<artifact UUID>/blocks/<block id>` places one block: its path from the top-level block down, and for a cell
+the row index (0 is the header, what `delete_row` takes), the column index (what `delete_column` takes), the text of the header cell
+drawn above it (with colspans or rowspans, the column the cell is drawn in) and the row's cells. A row or column
+deletion that would remove an open ask or unresolved comment anchor is `INVALID_OP` on `index`, naming the axis and anchor ids;
+answered asks and resolved comments are history and do not block it. A `find` or quote anchor tolerates inline Markdown
+(`**bold**`, `` `code` ``) and a leading `# ` selects a heading by its text; a miss names the quote and the three nearest blocks so
+the next quote lands, and a `find` cut before a closing `**` or `` ` `` is refused as an unbalanced inline mark rather than reported
+as a miss. A `heading:` anchor matches the whole heading text exactly — a prefix of a longer heading is a miss, naming the anchor and
+the nearest headings. `replace` is inline: `with` is the new text of the matched span inside its block, so a marker of a *different*
+kind from the block's own (`4. Design` written into a heading, `# Title` into a paragraph) stays literal text and never turns the
+block into a list or heading. A `with` that opens with a marker of the *same* kind as the matched block's own would write it twice and
+is rejected (`INVALID_OP` on `with`) — including prose that merely looks like a marker (`1999. was a year` into an ordered item),
+which is written as text with a backslash escape (`1999\. was a year`) — omit the marker to replace the block's text, or use `insert`
+plus `delete` to change the block's kind, level or number. The one exception is a heading rename whose `find` carried a heading
+marker: `replace(find="## Old", with="## New")` gives `## New`. A different level in `with` applies only when `find` named the
+heading's actual level — `find="## Old"`, `with="### New"` retitles and makes it an h3 — because `# ` is the level-blind selector,
+so `find="# Old"` renames the text and keeps whatever level it selected. A task item (`- [ ]` / `- [x]`) is ticked the same way:
+when `find` matches from the start of the item's text and `with` opens with `[x] ` or `[ ] `, the opening sets the item's
+checkbox and the rest is its new text — `replace(find="Write it", with="[x] Write it")` ticks it, keeping its block id — since
+the box is the item's attribute, not text, and written as text it would read `- [ ] [x] …`. The same opening over a plain list
+item or a paragraph stays literal text, as any marker of another kind does. `with` that forms more than one
+paragraph is rejected (`INVALID_OP` on `with`) — see the recipe for a multi-paragraph rewrite below; so is any non-empty `with` that
+renders to no text, which a line indented four spaces or a tab does (markdown reads that as a code block), as does whitespace
+alone. An empty `with` deletes the matched text on purpose; a list item, quote, typed block or footnote definition left
+holding only the emptied paragraph keeps it, and reads back holding it. Emptying a task item's first paragraph while
+another block follows it in the item is `INVALID_OP`, since the browser editor reads no such item as a task. Inside a code
+block none of this applies: `with` is the code's literal text, written as sent, whitespace, markdown syntax and
+references included, except that line breaks at the end of the code's text, and a line holding only whitespace in a
+list item's code, do not survive the next read. A line of colons in code inside a typed block is kept: Dispatch writes
+that typed block's fence longer than any such line the browser editor would end it at. Text a `replace` writes that
+would read as block syntax at a line start is stored escaped and reads back as the characters you sent: `---` over a
+paragraph is stored `\---`, not a rule, so to add a rule, `insert` it beside the paragraph (`insert` with markdown
+`***`). A CR LF or a lone carriage return in any text you write - an insert's markdown, a `with` in text or in code,
+a suggestion, an upload or a spec - is stored as a line feed, as the browser editor reads both. Use zero-based
+`occurrence` for a
+repeated target; re-read a missing or ambiguous target before retrying. Pass `summary` to name the version when recording a decision.
+
+**Rewriting several paragraphs is one `replace` per paragraph, then a read-back.** `replace` is inline:
+each `with` is the new text of one paragraph, and outside a code block a `with` that forms two paragraphs is
+refused whatever the text says. Give each paragraph you rewrite its own `replace`, which keeps that paragraph's block id and every
+anchor outside the text you rewrite. A comment or ask anchored to the text you rewrite loses its quote but keeps
+its pin to the block, so the dashboard still shows it beside that paragraph; a delete (below) loses both. An
+anchor that straddles the boundary keeps its mark over the words you left alone, with its quote shortened to
+them: rewriting `charlie delta.` under a comment on `bravo charlie` leaves that comment quoting `bravo `. When
+the new text has more paragraphs than the old, write them as **one** `insert` whose `markdown` holds them all,
+anchored on the last paragraph you rewrote with `after` quoting it exactly as it now reads (the operations in
+one batch apply in order): each separate `insert` at the same anchor lands directly after it, so two of them
+come out in the reverse of the order you wrote. An insert lands after the top-level block that holds the quote,
+so beside a paragraph inside a list item or a typed block it goes after the whole list or block. When it has fewer,
+`delete` each leftover paragraph, with its whole text as `find` or its id as `block`. All of that holds while
+the new text is paragraphs: `replace` keeps a block's kind, so any block that is not a paragraph — a heading,
+list, table, blockquote, rule, code fence or typed block — cannot be replaced into place. Its marker is written
+as literal text, except a backtick fence, which becomes an inline code span whose text is everything inside it,
+info string and line breaks included (```` ```go\nx := 1``` ```` becomes the code span `go` + a line break +
+`x := 1`), and a tilde fence, which stays literal.
+
+Outside a code block, HTML is not written as text at all, and a `replace` whose HTML would open a block where it lands is refused
+(`INVALID_OP` on `with`), because the schema carries no block HTML. `<div>x</div>` and `<!-- note -->` open one
+at the start of a paragraph or a list item and on the line after a hard break; a tag such as `<br>` opens one
+only when it stands alone as a paragraph or a list item. The same HTML inside a line, in a table cell or in a
+heading is inline HTML and is kept as written.
+
+A hard line break in `with` (two trailing spaces or a backslash before a newline) is refused in a heading or a
+table cell (`INVALID_OP` on `with`): both are written on one line, so the break would end the block there. A line
+break inside a code span or inline HTML there is refused the same way. Write the text without the break, or
+`insert` a new block after this one.
+
+When the new text adds a block that is not a paragraph beside paragraphs, `insert` it beside the
+paragraph you replaced, which keeps that paragraph's id; only when no paragraph of the new text is left to take
+the old block's place is it a `delete` of the old block and then an `insert` of the new one, anchored on the
+block before or after it. The delete is what costs the id (below); a typed block keeps its id when the insert
+carries it, which works only in that order, because an insert carrying an id the document still holds is refused.
+The tools refuse a `delete` or `retype` that would take out an `ask` block whose ask is still open, delete-then-insert included:
+reword it with `replace`, relocate it with `move`, or change its question, options, urgency or `multiple` with `dispatch_edit_ask` if you asked it. A single
+batch that moves an open block out of a container and then deletes the container is refused; make them two calls (the check reads
+the document as it stood before the batch).
+Then read the document back with
+`dispatch_doc_read` and read the passage and its neighbours, not a grep for the words you added: an empty
+`with` deletes the matched text on purpose, so a `replace` whose `with` you meant to fill
+empties that paragraph — the block and its id stay, holding nothing — and only a read shows what the document now says.
+
+A batch that leaves the document's semantic identity unchanged — including its inline anchor marks, so an edit that only orphans a
+comment or ask anchor still mints its version — mints no version, named or not: the response carries
+`changed: false` with `unchanged_ops` naming each operation that did nothing, and the tool result says nothing changed. A `summary`
+does not force a version for such a batch; `POST /api/v1/artifacts/<id>/versions`, which names the current state on purpose, still does.
+
+A `delete` whose `find` is a block's entire text removes the block itself — the bullet, paragraph, or heading, not just its words — and
+a list emptied of every item disappears with it; a partial match keeps the block with its remaining text. Deleting the text of a bullet
+that holds a nested list hoists that list's items into the bullet's place (as an outliner does); a bullet with any other content
+(paragraphs, code, tables) is refused with `INVALID_OP` naming `delete {block:"<item id>"}`, which removes the item with its content.
+`delete` with `block` removes any block by id (paragraph, heading, list, list item, table, or typed block; an answered `ask` block keeps
+its answer as the record, and a resolved one, which carries no answer, its resolution), and `move` with `block` relocates one, keeping its id and
+attributes — a moved `ask` keeps its ask and answer. **A block loses its id only when it is removed**, and its anchors go with it:
+`delete` by text or by id removes the block and any container it empties; `delete_row` / `delete_column` remove their cells' ids,
+which is why they are refused while an open ask or unresolved comment sits on them; and a `move` that takes the last block out of a
+blockquote or list item removes that emptied container, the list too when no item remains, and each enclosing container that
+held nothing else (`> - Only.` loses the blockquote as well as the item and the list). The moved block itself keeps its id,
+as do `replace` (an accepted empty `with` and a heading-level change included), `insert` and `retype`; `retype` carries the
+paragraph's id onto the typed block it becomes. Block ids are the `#id` a typed block renders
+(`:::ask{#5467e5ce-…}`) and, for every block including untyped ones, the `id` rows from
+`GET /api/v1/artifacts/<artifact UUID>/blocks` (or `/api/v1/issues/{key}/artifacts/{slug}/blocks`), each with its `type` and byte range
+in canonical markdown; the UUID route does not accept a slug. A later operation in the same atomic batch that names a block removed by
+an earlier `delete {block}` fails as `INVALID_OP` naming the earlier operation and the parent block that cascaded the removal. A move
+whose anchor lies inside the moved block, or a delete that would leave a typed block without the body its content rule requires, is
+`INVALID_OP` naming the field and the rule.
+
+`GET /api/v1/artifacts/<artifact UUID>/blocks` includes a full-state `token` on every block, including
+inline marks. To reject a stale edit, pass `precondition` with exactly one of
+`{ document: "<document token>" }` or
+`{ blocks: [{ id: "<block id>", token: "<block token>" }] }`. A document token comes from
+`dispatch_doc_read` or from the previous `dispatch_doc_edit`, whose result carries the token its
+own edit produced: a run of guarded edits passes each result's token to the next one and reads the
+document once, not once per edit. The server resolves the whole batch before
+mutation: a block guard must cover every content block it changes, or Dispatch returns
+`400 INVALID_PRECONDITION` without applying anything. Use a document token for insert and move because they
+depend on document order. A block token lets other sections change concurrently; a new anchored ask or comment
+changes the relevant token. A stale guard returns `409 PRECONDITION_FAILED` with each mismatch and current
+token; Dispatch applies no part of that batch. It is the hashline `#TAG` property applied to stable block ids,
+not line numbers: canonical Markdown lines shift under concurrent edits and rendering changes, while block ids
+survive moves and retyping.
+
+A browser editing the same document while your edit is in flight never makes your edit a silent
+no-op. The two changes merge, and a human's deletion of the paragraph you are rewriting wins — but
+you are told. `409 EDIT_LOST_TO_CONCURRENT_CHANGE` means the whole batch was refused and nothing
+was written: re-read the document and decide again, as with `PRECONDITION_FAILED`. A success whose
+`lost_ops` names operations means the version was written and the live document already lacks what
+those operations wrote, because the deletion landed after the version: re-read before building on
+it. `lost_ops: []` is the ordinary outcome, and a result that says it could not confirm the edit
+survived means the room is reloading or holds a tree too deep to read — re-read, and a read that
+answers `DOC_SCHEMA` says which. An operation that only removes text (`delete`, `delete_row`,
+`delete_column`, a `replace` that shortens) is never reported lost: a concurrent deletion cannot
+undo a removal.
+
+`retype` turns the paragraph or typed block with `block` into the named typed `type` in place. It keeps the
+block id, keeps a typed block's body, and uses `attributes` for client-owned typed attributes. Use it when
+an existing paragraph is the question that should become a decision.
+
+An ask block has two ids: the block id, shown as `:::ask{#<id> …}` in the rendered document and
+taken bare by `move`/`delete` in `block` (the `block:<id>` form is only for `before`/`after`
+anchors), and the ask id, which `dispatch_open_asks`, the dashboard's `?ask=` link, `dispatch_read`
+and `dispatch_comment({ reply_to_ask })` use. They differ; `dispatch://KEY/ask/<block-id>` answers
+`not found`.

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

@@ -0,0 +1,230 @@
+# Documents: typed blocks, comments, suggestions, and artifacts
+
+`skill://dispatch` sends you here when you write a typed block (an `:::ask` or a callout), comment on
+or suggest a change to a document, upload an artifact, request a document's approval, or get
+`DOC_SCHEMA`, `INVALID_ASK_BLOCK` or `DOC_SERVICE_UNAVAILABLE` back. Changing a document's text,
+tables included, is [Editing a document](skill://dispatch/references/document-edits.md).
+
+## 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. An
+opening line that continues a paragraph instead of standing on its own (indented four or more
+columns under the paragraph's text) is refused, naming the line's number and text - `INVALID_OP` on an edit's `markdown` or `with`, `INVALID_MARKDOWN` on any other write - since it
+would be stored as the paragraph's text; start the block on its own line. An opening written inside
+a line is stored as text, and `dispatch_issue` and `dispatch_artifact` quote it back as a
+typed-block opening that is text, not a block. For
+a new typed block, omit `#block-id`; Dispatch mints it. When editing an existing typed block, retain
+its id and every rendered attribute. Never copy an existing block's id into new markdown: an id
+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. An `ask` block whose ask
+is still open cannot be rewritten that way: the tools refuse the `delete`, so reword it with
+`replace`, relocate it with `move`, or change its question, options, urgency or `multiple` with
+`dispatch_edit_ask` if you asked it ([Editing a document](skill://dispatch/references/document-edits.md)).
+
+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"}
+Today's release is blocked by a database migration. The maintenance window closes in two hours;
+whether production data needs an index rebuild is unknown. How should we complete the migration?
+Recommendation: rehearse on a production snapshot, then apply in the window, because it finds the
+unknown cost before production while keeping today's release possible.
+
+- Apply now: Meets today's release, but recovery may be slower if the index rebuild is needed.
+- Rehearse then apply: Costs rehearsal time, but exposes the rebuild and rollback cost before production.
+- Defer the release: Avoids migration risk today, but leaves the release and its fixes unavailable.
+:::
+```
+
+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`.
+
+When `dispatch_issue` or `dispatch_artifact` answers `This spec holds no ask blocks …`, read it as a
+question: either no decision is needed and you say nothing, or you forgot to make it a block. When
+it answers `… typed-block openings in this document are text, not blocks`, the quoted openings are
+blocks stored as prose (inside a line, or a paste with something before every line): fix the markdown
+and upload again; a mention on purpose belongs in code. Neither answer sees a spec wrapped whole in a
+code fence (take the fence off), a malformed opening inside a line (`::ask{`, `:::ask {`: an ask opens
+only as `:::ask{…}` on a line of its own), or any `dispatch_doc_edit`: after an edit that writes an
+ask, `dispatch_doc_read` the section and check it renders as `:::ask{#<id> …}` on its own line.
+
+## 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](skill://dispatch/references/asks.md)).
+`ref` names the owner (an issue or project-document reference) in place of `issue`/`project`.
+`quote` requires `artifact`; its anchor is pinned to the containing block while retaining the quote
+for display. Omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no
+`quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server keeps
+threads flat. A reply to a resolved thread reopens it, except a decided suggestion's: a reply joins
+that thread and the suggestion stays accepted or rejected. Use `reply_to_ask` to reply directly under a
+question asked with `dispatch_ask`; `turn` (only with `reply_to_ask`) says who holds the turn after
+the reply — `agent` for a progress note that keeps the ask waiting on you, `human` (the default) when
+the human needs to act; see "Asking" in `skill://dispatch`. Comments are edited only by their author from the
+dashboard. A delivered `comment.created` event carries the comment `id`; reply to it with
+`dispatch_comment({ reply_to: <id> })`.
+
+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 - except a decided suggestion's, which your reply joins and leaves accepted or rejected. A reply to a pending
+suggestion whose text an edit removed lands as well. Asks are closed with `dispatch_resolve_ask` instead.
+
+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.
+
+## 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](skill://dispatch/references/document-edits.md)). Address an existing
+artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
+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.
+
+A picture meant to be seen inline in a message, comment or ask is not uploaded with `dispatch_artifact`: pass its local
+path in that tool's `images` (PNG, JPEG, GIF or WebP by its bytes, at most 25 MiB each). Each is uploaded to the issue (a
+project document's project; for a reply to a direct message, your own conversation) and appended after a blank line as
+one `![<file name>](dispatch://<owner>/artifact/<slug>@vN)` line, about 60 characters that count toward the body or
+question cap; a call the lines would carry over the cap is refused with the count before anything uploads, and again,
+with nothing posted, in the rare case where Dispatch gives an upload a longer address than that (a later version of a
+name the owner already holds, or a slug another file took first). The `@vN` pins the version the upload made (the same
+file name again makes the next version). A plain `dispatch://KEY/artifact/<slug>` reference to an image stays a link
+with a thumbnail.
+
+`dispatch_read` hands you the pictures the messages, asks and comments it shows embed, newest first, at most 8 and
+10 MiB per read, and its `Pictures:` section names each one shown, in order, and the rest by reference for
+`dispatch_doc_read`, which shows one picture (at most 3,750,000 bytes, the 5 MB of base64 a model provider takes; a
+larger one or an SVG is described). A picture in a
+conversation on the Agents page belongs to that conversation, `dispatch://agent/<session id>/artifact/<slug>@vN`, and
+`dispatch_doc_read` reads it by that reference alone. On Oh My Pi an Inbox delivery carries its pictures the same way; in
+Claude Code it stays text with the reference.
+
+A session is shown each picture once. A later read or delivery that embeds a picture you were already shown names it in
+`Pictures:` as `shown earlier this session` and sends no bytes, since every request carries the session's whole history
+and a model provider refuses one over 32 MB; `dispatch_doc_read` always shows the picture, so ask it for one you need
+again, after compaction too.
+
+Documents are CommonMark. A bare `<https://example.com|text>` is a CommonMark autolink and is normalised: the angle brackets are
+dropped and the URL keeps `|text`. A backslash-escaped `\<https://example.com|text>` displays as `<https://example.com|text>` in the
+document but comes back re-escaped (`\<`) from `dispatch_doc_read`. A Slack mrkdwn draft, or any other payload that is not Markdown,
+still belongs inside a fenced code block, where it survives verbatim both ways.
+
+A table cell ends at every `|` not written `\|`, inside inline code and links too, so write
+`` `x: Promise<void> \| undefined` ``, never `` `x: Promise<void> | undefined` ``, in a cell. A row
+holding text in a cell past its table's width is refused rather than stored without it, naming the
+row: write a `|` inside a cell as `\|`, or, where the row really has more cells, give the header and
+delimiter rows as many. Blank cells past the width are dropped, on every path. A spec, an upload or
+a version answers `INVALID_MARKDOWN`, an insert of blocks `INVALID_OP` on `markdown`, and an insert
+of bare table rows `TABLE_WIDTH`, which names the cell counts only.
+
+## Approval requests
+
+```
+dispatch_request_approval({ issue?, project?, artifact?, summary })
+```
+
+The call opens an approval ask with the options `Approve` and `Request changes`, its question
+"Approve spec.md (version N)?" followed by `summary`, where N is the document's latest version. It
+is refused, with nothing sent, while that version holds a decision block open, and the refusal
+names each block and its ask. An answer or a `dispatch_resolve_ask` closes the ask at once but
+reaches a version only when the document settles, about two seconds later, or with your next
+`dispatch_doc_edit`: fold the answer into the text (or, for a waiver, write the human's decision
+in) before you request. A block written in the last few seconds counts as open before Dispatch has
+opened its ask. A document holds one open request. A new version moves it to that version, keeping
+its thread and summary, and leaves it waiting on you, as a human's reply in its thread does; a move
+your own edit made sends you no event, and `dispatch_read` and `dispatch_doc_read` show it as
+`Approval: awaiting, waiting on agent`. Call again when "Approval of a spec" in `skill://dispatch`
+allows: that hands the same request back to the human, reworded first when `summary` is new. Your
+own reply in its thread hands it back too, with no call and the summary it already holds, unless
+you post it with `reply_to_ask` and `turn: "agent"` (`reply_to` carries no turn, so its reply takes
+the default, `human`) or a new version has moved the request since your last
+`dispatch_request_approval`. While it waits on the human, a call with the same `summary` changes
+nothing, and one with a different `summary` is refused, since it would rewrite the card they are
+reading. The answer reaches you as `artifact.approved` or `artifact.changes_requested` with the
+pinned `version` and closes the request, so the next call opens a new one; `changes_requested`
+carries the reason, which is your next piece of work. Those reads show the document's approval
+state; `stale` means it was approved and then edited.
+
+## A document that is reloading
+
+These calls can answer `DOC_SERVICE_UNAVAILABLE` (HTTP 503), because each writes a document inside its
+transaction: `dispatch_doc_edit`; `dispatch_ask` and `dispatch_comment` on a quote; a `dispatch_comment` reply
+in a thread whose first comment is anchored; `dispatch_suggest`; `dispatch_resolve_comment` on an anchored
+comment; `dispatch_artifact` replacing a document that already exists; and, on an ask that lives in a `:::ask`
+block, `dispatch_edit_ask` and `dispatch_resolve_ask`, which write that block. Creating an issue with a spec,
+uploading a new document, `dispatch_request_approval` and `dispatch_message` never answer it, and neither do
+`dispatch_edit_ask` and `dispatch_resolve_ask` on an ask that has no block. It means that document's live room
+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.
+