@sjawhar/opencode-legion-envoy 8.16.0 → 8.17.1

package/skills/dispatch/references/api.md

@@ -1,53 +1,21 @@
 # Authentication and the HTTP API
 
-`skill://dispatch` sends you here when you set up a Dispatch token, or need a route the `dispatch`
-commands do not cover.
+Read this to set up a Dispatch token, or to call a route no `dispatch` command covers.
 
 ## 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` or `dispatch.token` in the `envoy.json` the agent's
-session reads. Under an Oh My Pi profile other than `default`, a Claude Code `CLAUDE_CONFIG_DIR` or
-an OpenCode `OPENCODE_CONFIG_DIR`, that is the `envoy.json` in the session's own directory; any
-other session reads the file `ENVOY_CONFIG_FILE` names when it is set, else
-`~/.config/legion/envoy.json` (under `$XDG_CONFIG_HOME` when set). The plugin hands the path it
-chose to the session's commands in `ENVOY_CONFIG_FILE` beside `DISPATCH_HOST`, and the `dispatch`
-command reads the file `ENVOY_CONFIG_FILE` names whenever `DISPATCH_HOST` is set, else its host
-plugin's rule; in a Claude Code Bash that lacks both, as a subagent's can,
-`CLAUDE_CODE_CHILD_SESSION=1` makes the host `claude`, so the command reads `CLAUDE_CONFIG_DIR`'s
-file. A `dispatch.token` written `!<command>` is a command whose output is the token. A checkout's
-`.envoy/envoy.json` may set `dispatch.serverUrl` only with the `dispatch.token` beside it, and
-`dispatch.token` only with its own `dispatch.serverUrl` beside it; an `envoy` section there is not
-read. The file's token goes only to its own `dispatch.serverUrl`: a
-`DISPATCH_URL` naming another server needs `DISPATCH_TOKEN` or `DISPATCH_TOKEN_FILE`. 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 sign-in callback origin: the value must be the
-exact URL humans type in their browser, and `<DISPATCH_SERVER_URL>/auth/callback`
-is the callback registered on Dispatch's sign-in client (`DISPATCH_SIGNIN_CLIENT_ID`):
-the sign-in pool's app client, or the Google web client.
-
-### Finding a route
-
-The `dispatch` commands 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.
-
-`GET /api/v1/issues` answers every matching issue as an array, or one page when you name `limit`
-(1–250) or `offset` (alone it pages 50): `{issues, total, limit, offset}`, where `total` counts
-every issue your filters match. Walking the pages with the next `offset` is exact only while the
-listing does not change: an issue that enters or leaves what the filters match, or whose status or
-rank changes, between two reads shifts rows across a page boundary, and one issue comes back twice
-and another never, even when you stop at `total`. The unpaged array is the only exact set one read
-gives. `cursor` is `400 INVALID_QUERY`. `dispatch issues` pages for you.
-The event logs page with `after` or `before` and `limit`, and `GET /api/v1/search` takes a `limit`
-of at most 50 and has no next page. Every other route answers without paging and ignores a paging
-parameter.
-
+- Use a personal token. A human mints it in Dispatch **Settings → Agent tokens**. Supply it as `DISPATCH_TOKEN` or as `dispatch.token` in the session's `envoy.json`. The server records that human as the owner of your writes.
+- Which `envoy.json`: the session's own directory under an Oh My Pi profile other than `default`, a Claude Code `CLAUDE_CONFIG_DIR` or an OpenCode `OPENCODE_CONFIG_DIR`. Otherwise the file `ENVOY_CONFIG_FILE` names, else `~/.config/legion/envoy.json` (under `$XDG_CONFIG_HOME` when set).
+- The plugin passes its choice in `ENVOY_CONFIG_FILE` with `DISPATCH_HOST`. In a Claude Code Bash that lacks both, `CLAUDE_CODE_CHILD_SESSION=1` makes the command read `CLAUDE_CONFIG_DIR`'s file. A Legion pane reads the `DISPATCH_TOKEN_FILE` path the daemon sets.
+- A `dispatch.token` written `!<command>` is a command that prints the token.
+- A checkout's `.envoy/envoy.json` sets `dispatch.serverUrl` and `dispatch.token` only together. Its `envoy` section is not read. A file's token goes only to its own server: a `DISPATCH_URL` for another server needs `DISPATCH_TOKEN` or `DISPATCH_TOKEN_FILE`.
+- Never configure `DISPATCH_AGENT_TOKEN` (the shared devbox fallback) for one agent.
+- Never set the sign-in callback origin in an agent's `envoy.json`. It is `DISPATCH_SERVER_URL` in the deployment `compose/.env`: the exact URL humans type. `<DISPATCH_SERVER_URL>/auth/callback` is registered on the sign-in client (`DISPATCH_SIGNIN_CLIENT_ID`).
+
+## Finding a route
+
+- `GET /api/v1` (no credential) lists every route as `{method, path, auth, description}`. `auth` is `public`, `any`, `human` (a bearer gets `403 HUMAN_ONLY`) or `bearer`.
+- `404 NOT_FOUND` with "GET /api/v1 lists every route" means a wrong path. Read the index, do not guess.
+- Branch on an error's `code`, never its text.
+- `GET /api/v1/issues` returns every match unpaged, or one page with `limit` (1–250) or `offset`: `{issues, total, limit, offset}`. Only the unpaged array is exact: a page walk can repeat or skip an issue that changes. `cursor` is `400 INVALID_QUERY`. `dispatch issues` pages for you.
+- Event logs page with `after` or `before` and `limit`. `GET /api/v1/search` takes `limit` up to 50 with no next page. Other routes do not page.

package/skills/dispatch/references/asks.md

@@ -1,22 +1,18 @@
 # 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`.
+Read this once an ask is open. Whether to ask, and how to write it, is "Before you ask" in `skill://dispatch`.
 
 ## Who answers an ask
 
-An ask goes to the issue's assignee: their Inbox opens on the asks on the issues they hold, so a question on an issue someone is assigned is in front of that person. An ask on an issue nobody is assigned is in nobody's default Inbox list and in nobody's `Needs you` count; it is reached by adding `Unassigned` to the Inbox's assignee filter, or from the issue's own page. Setting the issue's assignee is what puts a question in front of a person. Find out who Dispatch takes you for with `dispatch whoami`.
-It prints whom the session acts for: the lowercase email of the person whose personal token you run under, or, under the shared token or a verified service token, that it has no owner — naming the service as `<namespace>/<name>` for a service token (`system:serviceaccount:<namespace>:<name>`), which is also how 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.
+- An ask goes to the issue's assignee's Inbox. On an unassigned issue it is in nobody's default Inbox or `Needs you` count.
+- `dispatch whoami` prints whom you act for: your token owner's email, or no owner (a service token shows as `<namespace>/<name>`, as your writes do). An issue you create goes to your owner, else inherits its parent's assignee, else stays unassigned.
+- On an unassigned issue where the answer matters, assign it to your owner, or name in the question who should answer. Assign with `PATCH /api/v1/issues/{key}` and `{"assignee": "<email>"}`. An email nobody signed in with gets `ASSIGNEE_NOT_ALLOWED`.
+- Never reassign an issue a human holds to get a faster answer. 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:
+- A to-do follows the question-and-options contract of "Writing for the human". For a human-only action, what it changes and risks constrains the answer. No label is special. If an outcome needs a reason, say so in its description.
+
 ```bash
 dispatch ask --issue DSP-42 \
   --question 'The fix is merged but cannot run in production: the signing certificate it needs expired, and only its owner can renew it in the registrar console. Renewing replaces the certificate every client checks. How should we proceed? Recommendation: renew it now because the fix cannot run without it.' \
@@ -24,78 +20,23 @@ dispatch ask --issue DSP-42 \
   --option 'Leave it expired: Changes nothing now but leaves the fix unable to run.'
 ```
 
-Correct or refine an open ask in place instead of opening a second question, with
-`dispatch edit-ask --ask <id>` and any of `--question`, `--option` (repeated), `--multiple` and `--urgency`.
-At least one of them 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.
-A human can change an answer they gave. The change arrives as another `ask.answered` frame whose
-`previous_answer` names the answer it replaced, through the same route the first answer took, and
-`dispatch read --ref dispatch://KEY/ask/<id>` lists every earlier answer. Act on the newest answer.
-
-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 `--option` 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.
+- Correct an open ask in place with `dispatch edit-ask`, not a second ask, while the same decision stays open. The human then reconfirms. You cannot edit an answered or resolved ask. If the decision changed, retract it and open a new one.
+- `edit-ask` on a block ask writes the block too, so it mints a version and closes a spec's design gate until approved. Change anything else about the block with `dispatch doc-edit`. A retry with unchanged fields is safe.
+- A human can change an answer. A new `ask.answered` carries `previous_answer`. Act on the newest.
+- Retract a moot or superseded ask, or resolve one whose answer you found:
 
-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:
 ```bash
 dispatch resolve-ask --ask <id> --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 <id>`, 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 output 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`.
+- Use `retracted` for obsolete, `resolved` for found. Always give a reason: the question stays in its card. Resolution never records a human decision. An answered ask cannot be resolved.
+- `doc-edit` refuses to delete an open ask's block. A block deleted another way (an upload, the browser) closes its ask. Restoring it reopens the ask.
+- Reply under an ask with `dispatch comment --reply-to-ask <id>`. Close your review comment with `dispatch resolve-comment` ([Documents](skill://dispatch/references/documents.md#comments-and-suggestions)).
+- A human reply while the ask is open (`ask_state: open`) is a request for clarification, not an answer. Answer in the thread with `--reply-to-ask`, or reword with `edit-ask`. Do not open a second ask.
+- Each reply sets whose turn it is. Your default reply (`--turn human`) puts the ask in the human's `Waiting on you`. For any progress or working-on-it note, use `--turn agent`. A human reply hands the turn to you. Reads show 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 output says so (`You follow this ask: its answer and replies reach you directly.`) once per ask.
-Leave a thread you no longer need, or rejoin one, with:
-
-```bash
-dispatch follow --ask <id> --action unfollow   # or --action follow
-```
-
-`--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; a person's reply to
-a comment you started, and a person's new comment on a document you wrote or have a version crediting you, reach you directly as
-well; 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.
-
+- You follow an ask you opened or replied to, or one a human added you to. Its answer, edits, resolution and replies reach your agent topic directly.
+- Leave or rejoin: `dispatch follow --ask <id> --action unfollow` (or `follow`). `--ask` takes a full id, a `dispatch://KEY/ask/<id>`, or an 8+ hex prefix unique among your open asks. Removal arrives as `ask.follower_removed`, an add as `ask.follower_added`.
+- No write subscribes you to an owner. Replies to your comments and new comments on your documents also reach you. For everything else, subscribe: `envoy_subscribe notifications.dispatch.issue.<KEY>.>` or `envoy_subscribe notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The topic carries every event. `notify` controls only wake and routed delivery. A human can unsubscribe you (`subscription.removed`).

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

@@ -1,208 +1,59 @@
 # Editing a document
 
-Every document Dispatch holds — an issue's spec, a project document — is edited in place
-with `dispatch doc-edit`, never re-uploaded. "The Spec" in `skill://dispatch` sends you here for
-the command's shape, how to target the text you mean, what each operation costs a block, and how to
-reject a stale edit.
+Edit every Dispatch document (an issue's spec, a project document) in place with `dispatch doc-edit`. Never upload it again. `dispatch doc-edit --help` has the full rules for each operation: markers, task boxes, hard breaks, anchors and preconditions.
 
 ```bash
 dispatch doc-edit --issue <KEY> --artifact spec --summary '<names the version>' --ops-json-file - <<'EOF'
 [{"op": "replace", "find": "old sentence", "with": "new sentence"}]
 EOF
 ```
-`--project` replaces `--issue` for a project document, and `--precondition-json` guards against a
-stale edit (below). It prints whether the edit applied, the version it wrote, which operations
-changed nothing (`unchanged_ops`) or were lost to a concurrent change (`lost_ops`), and the document
-token this edit produced, as a `Document token: <token>` line. The ops are a JSON array of this exact `EditOp` shape:
 
-```ts
-type EditOp = {
-  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 command sends
-anything, naming the operation and its keys, because every key but `op` is optional: a
-misspelled `with` would otherwise be dropped and the `replace` would delete the text you meant to
-rewrite.
+- Ops: `replace`, `delete`, `insert`, `retype`, `move`, `delete_row`, `delete_column`. Keys: `op`, `find`, `with`, `occurrence`, `markdown`, `after`, `before`, `block`, `index`, `type`, `attributes`. An unknown key is refused before sending. A misspelled `with` would turn the `replace` into a delete.
+- The output names the version, `unchanged_ops`, `lost_ops`, and a `Document token:`.
+- Use `--summary` to name a version that records a decision.
 
-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.
+## Targeting text
 
-`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.
-`dispatch doc-read --issue <KEY> --blocks` (or `--project` and `--artifact`) lists every block of the live document in place of its
-markdown, one line each, in document order and indented under the block holding it: its id, its type, its token, how many comments
-and asks anchor to it (a table counts its cells' anchors) and its opening words. Under a table it lists each row by its index, what
-`delete_row` takes (0 is the header), and each cell by its row and its column, what `delete_column` takes, with the opening words
-of the header drawn above it. A cell spanning columns or rows counts once in its row, so its column is that index and not where
-the markdown writes it. A Dispatch that does not list table rows yet says so instead of an index. It takes no `--version`, since
-only the live document's ids and tokens address an edit, and an uploaded file has no blocks.
-`GET /api/v1/artifacts/<artifact UUID>/blocks` and `GET /api/v1/artifacts/<artifact UUID>/blocks/<block id>` answer the same
-facts for a reader outside the command. 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.
+- Quote text as rendered: inline code without backticks, bold without asterisks, link text without syntax, a cell by its text, code without fences. One quote stays in one textblock. Split changes that span blocks.
+- A miss names the three nearest blocks. A `heading:` anchor must match the whole heading. Use zero-based `occurrence` for a repeat. Re-read before you retry a missing or ambiguous target.
+- `dispatch doc-read --blocks` lists each live block's id, type, token, anchor count and opening words, and each table row and cell index. Only live ids address an edit.
 
-**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.
+## Rewriting paragraphs
 
-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.
+- **One `replace` per paragraph, then a read-back.** A `with` of two paragraphs is refused. Each `replace` keeps the block id and the anchors outside the text you change. An anchor on changed text loses its quote but keeps its pin.
+- More new paragraphs than old: add the rest as **one** `insert` holding them all, `after` the last rewritten paragraph as it now reads. Two inserts at one anchor come out reversed. An insert lands after the top-level block that holds the quote.
+- Fewer: `delete` each leftover paragraph by its whole text or `block` id.
+- `replace` keeps a block's kind. When the new text adds a non-paragraph block (heading, list, table, quote, rule, fence or typed block) beside paragraphs, `insert` it beside the paragraph you replaced. Only when no paragraph of the new text stays, `delete` the old block, then `insert` the new one, anchored on the block before or after it.
+- An empty `with` deletes the matched text on purpose and leaves an empty block. Read the passage and its neighbours back with `dispatch doc-read`. A grep for your new words is not a check.
+- Dispatch refuses block HTML (`<div>`, `<!-- -->`, a lone `<br>` paragraph) in `with`. Inline HTML stays.
+- To add a rule, `insert` `***`. A `---` in `with` is stored as `\---`.
 
-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.
+## Blocks and ids
 
-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 block loses its id only when deleted: by `delete`, by `delete_row` / `delete_column` (its cells), or by a `move` that empties its container. Its anchors go with it. `replace`, `insert`, `move` and `retype` keep ids.
+- `delete` of a block's whole text deletes the block. A partial match keeps it. A bullet with a nested list hoists the list. A bullet with other content needs `delete {block:"<item id>"}`.
+- Dispatch refuses a `delete` or `retype` that takes out an open ask's block, delete-then-insert included. Reword with `replace`, relocate with `move`, or use `dispatch edit-ask`. Moving an open block out of a container and deleting the container takes two calls.
+- `retype` turns a paragraph or typed block into a typed block in place, keeping its id. Use it when a paragraph is the question that should become a decision.
+- An ask block has two ids. The block id (`:::ask{#<id> …}`) goes bare in `block` for `move` / `delete` (`block:<id>` only in `before` / `after`). The ask id goes to `dispatch open-asks`, `dispatch read` and `--reply-to-ask`. `dispatch://KEY/ask/<block-id>` answers `not found`.
 
-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 output says nothing changed. A `--summary`
-does not force a version for such a batch; `POST /api/v1/artifacts/<id>/versions`, which names the current state on purpose, still does.
+## Tables
 
-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 ids `dispatch doc-read --blocks` lists. 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.
+- `delete_row` / `delete_column` take the table `block` and a zero-based `index`. Row 0 is the header. The last body row and a row's last column cannot go. Open asks or unresolved comments on the cells block it.
+- Inserting bare body rows (no header or delimiter) at a cell quote extends that table. A wider row is `TABLE_WIDTH`. A full table with a header pasted there becomes a second table.
 
-`dispatch doc-read --blocks` lists a full-state `token` on every block, including
-inline marks. To reject a stale edit, pass `--precondition-json` with exactly one of
-`{"document": "<document token>"}` or
-`{"blocks": [{"id": "<block id>", "token": "<block token>"}]}`. A document token comes from
-`dispatch doc-read` or from the previous `dispatch doc-edit`, whose output carries the token its
-own edit produced: a run of guarded edits passes each output's token to the next one and reads the
-document once, not once per edit. The server resolves the whole batch before
-mutation: a block guard must cover every content block it changes, or Dispatch returns
-`400 INVALID_PRECONDITION` without applying anything. Use a document token for insert and move because they
-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.
+## Stale and concurrent edits
 
-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.
+- Guard with `--precondition-json`: `{"document": "<token>"}` or `{"blocks": [{"id": "<id>", "token": "<token>"}]}`. Use a document token for `insert` and `move`. A block guard must cover every block the batch changes.
+- Chain guarded edits by passing each output's token to the next. Read once, not once per edit.
+- `409 PRECONDITION_FAILED` or `409 EDIT_LOST_TO_CONCURRENT_CHANGE`: nothing written. Re-read and decide again. Non-empty `lost_ops` on success: a browser deleted that text after the write. Re-read before you build on it. A result that could not check survival: re-read.
+- A batch that changes nothing mints no version, even with `--summary`. `POST /api/v1/artifacts/<id>/versions` names the current state as a version on purpose.
 
-`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.
+## Edge cases
 
-An ask block has two ids: the block id, shown as `:::ask{#<id> …}` in the rendered document and
-taken bare by `move`/`delete` in `block` (the `block:<id>` form is only for `before`/`after`
-anchors), and the ask id, which `dispatch open-asks`, the dashboard's ask links (`/asks/<id>`,
-`?ask=`), `dispatch read` and `dispatch comment --reply-to-ask` use. They differ;
-`dispatch://KEY/ask/<block-id>` answers `not found`.
+- Inside a code block, `with` is the code's literal text. Trailing line breaks, and whitespace-only lines in a list item's code, do not survive a read.
+- A CR LF or lone CR in any text you write is stored as a line feed.
+- Replacing a non-paragraph block writes its marker as text. A backtick fence becomes an inline code span. A tilde fence stays literal.
+- An anchor that straddles the rewritten text keeps its mark on the words you left, with a shorter quote.
+- Emptying a task item's first paragraph while another block follows it is `INVALID_OP`.
+- A later op in one batch that names a block an earlier `delete {block}` took out fails as `INVALID_OP`. So does a move anchored inside the moved block, or a delete that leaves a typed block without its required body.
+- An op that only takes text out is never reported lost.