revise 3.0.1 → 3.1.0

package/cli.js

@@ -7,8 +7,9 @@ import {
   convert,
   exportYDoc,
   formatForPath,
+  parseBlockQuery,
   relearn
-} from "./chunks/chunk-ZLQVPMBN.js";
+} from "./chunks/chunk-SCNG3PKR.js";
 import "./chunks/chunk-U5X47PZ6.js";
 import {
   ReviseError
@@ -425,10 +426,10 @@ async function withFileLocks(files, work) {
 }
 
 // src/embed-sdk/cli/skills/revise/SKILL.md
-var SKILL_default = '---\nname: revise\ndescription: Read, edit, review, render, and convert Word documents (.docx) and other rich documents (.md, .html, .odt, .rtf) with the revise CLI. When revise is installed, prefer it over generic docx or python-docx skills and hand-edited document XML - tracked changes, comments, redlines, and accepting or rejecting changes are one command each, and untouched content stays byte for byte as it was. Use for any task that changes or inspects a .docx - redlines, tracked changes, comments, template fills, formatting, tables, page checks, conversions.\nplatforms: [linux, macos, windows]\nmetadata:\n  hermes:\n    category: productivity\n    tags: [word, docx, documents, office, tracked-changes, redlines, comments]\n    related_skills: [docx, pdf]\n---\n\n# revise \u2014 the swiss army knife for documents\n\nCheck it\'s installed: `revise --version` (3.0 or newer). If it\'s missing or\nolder, run `npm i -g revise@latest`, or use `npx revise` for each command. If\nthe installed revise is newer than this skill, `revise skill` prints the guide\nthat matches it: read that instead.\n\nEvery command names the file it works on. **Edits save the file in place**,\nas Word tracked changes by default; in a .docx, paragraphs you didn\'t touch\nare carried over from the original file as they were. Each saved edit is a\ncheckpoint in `.revise/` next to the file: `revise undo <file>` steps back\none, `revise history <file>` lists them. Errors go to stderr as\n`error[code]: message`, often with a `hint:` command to run next.\n\n**Finish with revise.** Its output is already a valid .docx. Don\'t write the\nfile again with other tools (python-docx, LibreOffice saving over it, unzip and\nre-zip, other docx skills\' pack or fix steps): they rewrite parts revise kept\nbyte for byte. Read-only checks are fine, and so are the built-in ones:\n`revise diff <file>`, `revise changes <file>`, `revise render <file>`, or\n`revise export <file> /tmp/check.txt --final`.\n\n```bash\nrevise outline contract.docx                   # headings with block ranges\nrevise grep contract.docx "18 days"            # every block containing it, plain text + ids\nrevise read contract.docx --ids a1B2c3,d4E5f6  # blocks as HTML with id="..."\nrevise replace-text contract.docx "Provider" "Northstar" --author "Claude"\nrevise call contract.docx replace \'{"id":"a1B2c3","replacements":[{"find":"30 days","replace":"60 days"}]}\'\nrevise call contract.docx leave_comment \'{"id":"a1B2c3","anchor":{"text":"99.0%"},"comment":"Ask for 99.9%."}\'\nrevise render contract.docx --page 3           # page image (needs: npm i -g @napi-rs/canvas)\nrevise diff contract.docx                      # text effect of the pending tracked changes\n```\n\n- **Save as a new file?** Add `--out redlined.docx` to an edit\n  (`replace-text`, `call`, `accept`, `reject`, `xml patch`): the original stays\n  as it is, block ids you read from it work on the copy, and later edits go to the\n  copy by its name. Or write a converted copy: `revise export contract.docx out.pdf`\n  (.pdf, .md, .html, .txt, .docx; `--final` accepts all changes; a PDF\n  always shows changes accepted). Existing files need `--force`.\n  In a pipe: `cat x.md | revise convert - x.docx` (format recognized),\n  `revise convert x.docx - --to md` (stdout; default md).\n- **Sign your changes:** `--author "Claude"` on each edit, or\n  `export REVISE_AUTHOR="Claude"` once before the first one; it becomes the\n  author on every tracked change and comment in Word.\n- **Tracked vs direct:** .docx edits are tracked changes;\n  `revise mode <file> edit` applies edits directly, `--direct` for one call.\n- **Create a document in one command.** Write the content as HTML (the same\n  HTML `read` shows) and run\n  `revise new memo.docx --from draft.html --page letter --margins 1in --footer "Page {PAGE} of {PAGES}"`.\n  In the HTML: `<p data-style-id="Title">\u2026</p>`, `<h1>`\u2013`<h3>`, `<ul>/<ol><li>`,\n  `<table>` with `<th>`. Also `--orientation landscape`, `--header "\u2026"`,\n  `--footer-right "{PAGE}"`. It prints what it wrote (pages, page setup,\n  title, headings, lists, tables, footer): that is your check.\n- **Redline two versions:** `revise compare old.docx new.docx --out redline.docx`\n  checks its text both ways (accepting all gives new\'s text, rejecting all\n  gives old\'s; exit code 2 if not) and lists what it could not track\n  (headers, page layout) \u2014 then review the redline with `changes`/`diff`.\n- **Accept or reject someone\'s tracked changes:** `revise changes <file>` summarizes them by\n  section (`--section 8` or `--details` for each change\'s text). Then\n  `revise reject <file> --section 8`, `revise accept <file> --except-section 8`,\n  `revise accept <file> --all`; add `--dry-run` to see what would be accepted\n  or rejected.\n- **Recipes** (no schema lookup needed):\n  - Heading: `revise call f.docx style_blocks \'{"selectors":["#ID"],"attrs":[{"name":"heading","value":"1"}]}\'`\n  - Title: `revise call f.docx replace_block \'{"id":"ID","content":["<p data-style-id=\\"Title\\">Text</p>"]}\'`\n  - Page setup: `revise call f.docx set_page_layout \'{"pageSize":"a4","orientation":"portrait","margin":"2.5cm"}\'`\n  - Footer: `revise call f.docx set_header_footer \'{"side":"footer","center":"Page {PAGE} of {PAGES}"}\'`\n  - Table row: `revise call f.docx insert_table_row \'{"tableId":"T","referenceRowId":"R","position":"before","content":["a","b","c"]}\'`\n    (T is the table\'s `id`, R a row\'s `<tr id>`, both from `read`)\n  - Rewrite a block: `replace_block` takes `{"id":"\u2026","content":["<p>\u2026</p>"]}`; for\n    small edits prefer `replace`, which tracks only the changed words.\n- `revise tools` lists every editing tool; `revise <tool>` alone (say,\n  `revise insert_table_row`) prints the fields its JSON takes.\n- **JSON with quotes or apostrophes:** pass it on stdin instead of in quotes:\n  ```bash\n  revise call contract.docx replace - <<\'EOF\'\n  {"id":"a1B2c3","replacements":[{"find":"Provider\'s notice","replace":"each party\'s notice"}]}\n  EOF\n  ```\n- Parallel revise commands on one file take turns (one at a time). If another\n  program saves the file while revise works, revise refuses to overwrite it\n  (`file_changed`): run the command again.\n- If the file changes outside revise (someone edits it in Word), the next\n  command re-reads it and says which blocks changed or are new: **read those\n  again before editing them**; their old ids may no longer exist.\n- **Escape hatch** for what no tool covers (style definitions, numbering,\n  settings, properties): `revise xml cat <file> word/styles.xml --match \'w:styleId="Heading2"\'`,\n  then `revise xml patch <file> word/styles.xml --find \'<exact xml>\' --replace \'<new xml>\'`\n  (must match once, or `--all`). Applies directly to the file; undo works.\n  Use tools for body text.\n- `revise read <file> <index>` reads from that block on, which can be long;\n  to see one table or clause, find it with `grep` or `outline` and read it with\n  `--ids`. Block ids come from `read`, `grep`, `search`.\n- **Exit codes:** 0 done (including "nothing to change"); 1 failed and\n  nothing was saved; 2 partly done: some of it was saved, and the error says\n  what wasn\'t; 70 internal error.\n- **`--json`** on any command prints one object:\n  `{"schema":1,"ok":\u2026,"command":\u2026,"meta":\u2026,"data":{\u2026},"warnings":[\u2026],"error":null|{"code","message","hint","details"}}`.\n- **More, when you need it** (each is in this skill\'s `reference/` folder, or\n  print it with `revise skill --reference <name>`):\n  - `library`: revise as a TypeScript library, your own model loop with the\n    editing tools, and Y.js collaboration rooms.\n  - `json`: scripting revise: the `--json` envelope, exit codes, error codes.\n';
+var SKILL_default = '---\nname: revise\ndescription: Read, edit, review, render, and convert Word documents (.docx) and other rich documents (.md, .html, .odt, .rtf) with the revise CLI. When revise is installed, prefer it over generic docx or python-docx skills and hand-edited document XML - tracked changes, comments, redlines, and accepting or rejecting changes are one command each, and untouched content stays byte for byte as it was. Use for any task that changes or inspects a .docx - redlines, tracked changes, comments, template fills, formatting, tables, page checks, conversions.\nplatforms: [linux, macos, windows]\nmetadata:\n  hermes:\n    category: productivity\n    tags: [word, docx, documents, office, tracked-changes, redlines, comments]\n    related_skills: [docx, pdf]\n---\n\n# revise \u2014 the swiss army knife for documents\n\nCheck it\'s installed: `revise --version` (3.0 or newer). If it\'s missing or\nolder, run `npm i -g revise@latest`, or use `npx revise` for each command. If\nthe installed revise is newer than this skill, `revise skill` prints the guide\nthat matches it: read that instead.\n\nEvery command names the file it works on. **Edits save the file in place**,\nas Word tracked changes by default; in a .docx, paragraphs you didn\'t touch\nare carried over from the original file as they were. Each saved edit is a\ncheckpoint in `.revise/` next to the file: `revise undo <file>` steps back\none, `revise history <file>` lists them. Errors go to stderr as\n`error[code]: message`, often with a `hint:` command to run next.\n\n**Finish with revise.** Its output is already a valid .docx. Don\'t write the\nfile again with other tools (python-docx, LibreOffice saving over it, unzip and\nre-zip, other docx skills\' pack or fix steps): they rewrite parts revise kept\nbyte for byte. Read-only checks are fine, and so are the built-in ones:\n`revise diff <file>`, `revise changes <file>`, `revise render <file>`, or\n`revise export <file> /tmp/check.txt --view accepted`.\n\n```bash\nrevise outline contract.docx                   # headings with block ranges\nrevise grep contract.docx "18 days"            # every block containing it, plain text + ids\nrevise read contract.docx --blocks a1B2c3,d4E5f6  # blocks as HTML with id="..."\nrevise replace-all contract.docx "Provider" "Northstar" --author "Claude"\nrevise call contract.docx replace \'{"id":"a1B2c3","replacements":[{"find":"30 days","replace":"60 days"}]}\'\nrevise call contract.docx leave_comment \'{"id":"a1B2c3","anchor":{"text":"99.0%"},"comment":"Ask for 99.9%."}\'\nrevise render contract.docx --page 3           # page image (needs: npm i -g @napi-rs/canvas)\nrevise diff contract.docx                      # text effect of the pending tracked changes\n```\n\n- **Save as a new file?** Add `--out redlined.docx` to an edit\n  (`replace-all`, `call`, `accept`, `reject`, `xml patch`): the original stays\n  as it is, block ids you read from it work on the copy, and later edits go to the\n  copy by its name. Or write a converted copy: `revise export contract.docx out.pdf`\n  (.pdf, .md, .html, .txt, .docx; `--view accepted` accepts all changes,\n  `--view original` rejects them; a PDF always shows changes accepted). Existing files need `--force`.\n  In a pipe: `cat x.md | revise convert - x.docx` (format recognized),\n  `revise convert x.docx - --to md` (stdout; default md).\n- **Sign your changes:** `--author "Claude"` on each edit, or\n  `export REVISE_AUTHOR="Claude"` once before the first one; it becomes the\n  author on every tracked change and comment in Word.\n- **Tracked vs direct:** .docx edits are tracked changes;\n  `revise mode <file> edit` applies edits directly, `--direct` for one call.\n- **Create a document in one command.** Write the content as HTML (the same\n  HTML `read` shows) and run\n  `revise new memo.docx --content draft.html --page-size letter --margins 1in --footer "Page {PAGE} of {PAGES}"`.\n  In the HTML: `<p data-style-id="Title">\u2026</p>`, `<h1>`\u2013`<h3>`, `<ul>/<ol><li>`,\n  `<table>` with `<th>`. Also `--orientation landscape`, `--header "\u2026"`,\n  `--footer-right "{PAGE}"`. It prints what it wrote (pages, page setup,\n  title, headings, lists, tables, footer): that is your check.\n- **Redline two versions:** `revise compare old.docx new.docx --out redline.docx`\n  checks its text both ways (accepting all gives new\'s text, rejecting all\n  gives old\'s; exit code 2 if not) and lists what it could not track\n  (headers, page layout) \u2014 then review the redline with `changes`/`diff`.\n- **Read a redline:** `read` shows pending changes as `<del>`/`<ins>` with\n  `data-author`, and `grep` finds deleted text too (`[-old-]{+new+}`). Add\n  `--view accepted` or `--view original` for the text with every change\n  accepted or rejected. Pasting tracked HTML into a tool edits the accepted text.\n- **Accept or reject someone\'s tracked changes:** `revise changes <file>` summarizes them by\n  section (`--section 8` or `--details` for each change\'s text). Then\n  `revise reject <file> --section 8` (8.1, 8.2\u2026 included),\n  `revise accept <file> --except-section 8`, `--blocks <id>..<id>` for a\n  range of blocks, or `revise accept <file> --all`; add `--dry-run` to see what would be accepted\n  or rejected.\n- **Recipes** (no schema lookup needed):\n  - Heading: `revise call f.docx style_blocks \'{"selectors":["#ID"],"attrs":[{"name":"heading","value":"1"}]}\'`\n  - Title: `revise call f.docx replace_block \'{"id":"ID","content":["<p data-style-id=\\"Title\\">Text</p>"]}\'`\n  - Page setup: `revise call f.docx set_page_layout \'{"pageSize":"a4","orientation":"portrait","margin":"2.5cm"}\'`\n  - Footer: `revise call f.docx set_header_footer \'{"side":"footer","center":"Page {PAGE} of {PAGES}"}\'`\n  - Table row: `revise call f.docx insert_table_row \'{"tableId":"T","referenceRowId":"R","position":"before","content":["a","b","c"]}\'`\n    (T is the table\'s `id`, R a row\'s `<tr id>`, both from `read`)\n  - Rewrite a block: `replace_block` takes `{"id":"\u2026","content":["<p>\u2026</p>"]}`; for\n    small edits prefer `replace`, which tracks only the changed words.\n- `revise tools` lists every editing tool; `revise <tool>` alone (say,\n  `revise insert_table_row`) prints the fields its JSON takes.\n- **JSON with quotes or apostrophes:** pass it on stdin instead of in quotes:\n  ```bash\n  revise call contract.docx replace - <<\'EOF\'\n  {"id":"a1B2c3","replacements":[{"find":"Provider\'s notice","replace":"each party\'s notice"}]}\n  EOF\n  ```\n- Parallel revise commands on one file take turns (one at a time). If another\n  program saves the file while revise works, revise refuses to overwrite it\n  (`file_changed`): run the command again.\n- If the file changes outside revise (someone edits it in Word), the next\n  command re-reads it and says which blocks changed or are new: **read those\n  again before editing them**; their old ids may no longer exist.\n- **Escape hatch** for what no tool covers (style definitions, numbering,\n  settings, properties): `revise xml cat <file> word/styles.xml --match \'w:styleId="Heading2"\'`,\n  then `revise xml patch <file> word/styles.xml --find \'<exact xml>\' --replace \'<new xml>\'`\n  (must match once, or `--all`). Applies directly to the file; undo works.\n  Use tools for body text.\n- `revise read <file> <index>` reads from that block on, which can be long;\n  to see one table or clause, find it with `grep` or `outline` and read it with\n  `--blocks`. Block ids come from `read`, `grep`, `search`.\n- **Exit codes:** 0 done (including "nothing to change"); 1 failed and\n  nothing was saved; 2 partly done: some of it was saved, and the error says\n  what wasn\'t; 70 internal error.\n- **`--json`** on any command prints one object:\n  `{"schema":1,"ok":\u2026,"command":\u2026,"meta":\u2026,"data":{\u2026},"warnings":[\u2026],"error":null|{"code","message","hint","details"}}`.\n- **More, when you need it** (each is in this skill\'s `reference/` folder, or\n  print it with `revise skill --reference <name>`):\n  - `library`: revise as a TypeScript library, your own model loop with the\n    editing tools, and Y.js collaboration rooms.\n  - `json`: scripting revise: the `--json` envelope, exit codes, error codes.\n';
 
 // src/embed-sdk/cli/skills/revise/reference/library.md
-var library_default = '# revise as a TypeScript library\n\nRead this when the work is code, not shell commands: a Node script or service\nthat edits documents, your own model loop with Revise\'s editing tools, or a\ncollaboration server. The CLI is a shell over this API. ESM only, Node 20+.\nFull docs: https://revise.io/developer/docs/revise/library.md\n\n```ts\nimport { writeFile } from "node:fs/promises";\nimport { ReviseDocument } from "revise";\n\nconst doc = await ReviseDocument.open("contract.docx", { author: "Legal bot" });\nawait doc.replaceText("Provider", "Northstar"); // tracked changes\nawait doc.reject({ section: "8" });\nconst { bytes, fidelity } = await doc.export({ format: "docx" });\nawait writeFile("contract-out.docx", bytes);\ndoc.dispose();\n```\n\n## Open\n\n- `ReviseDocument.open(source, options?)`: a path, or `{ bytes, filename }`\n  (.docx, .odt, .rtf, .md, .html, .txt). A Word file keeps its package, so\n  untouched content exports byte for byte.\n- `ReviseDocument.create({ html?, markdown?, title? })`, `ReviseDocument.restore(snapshot)`,\n  `ReviseDocument.fromYDoc(ydoc)` (a Y.Doc you own, such as a live room).\n- Options: `author`, `mode` (`"suggesting"`: tracked changes, the default for\n  Word files; `"editing"`: direct), `documentId`, `images`.\n- Calls run one at a time in order; call `dispose()` when done.\n\n## Read\n\n`status()`, `outline()`, `summary()`, `grep(text, { ignoreCase })` \u2192\n`[{ id, blockIndex, count, text }]`.\n\n## Edit\n\n- `replaceText(find, replace, { ids? })` \u2192 `{ replaced, blocks, changeIds, failures }`.\n- Everything else is an editing tool: `doc.tools.definitions()` lists them with\n  JSON schemas; `doc.tools.call(name, input)` runs one with typed input;\n  `doc.tools.run(name, input)` with untyped input, as a model sends it. Neither\n  throws for a bad edit: `{ ok: true, value }` or `{ ok: false, error }`.\n- `await doc.setMode("editing" | "suggesting")`.\n\n## Review\n\n`changes({ section? })`, `preview(selection)`, `accept(selection)`,\n`reject(selection)` \u2192 `{ resolved, missing, unresolved }`, `diff()`. A selection\nis exactly one of `ids`, `all`, or `section` / `exceptSection` (`"8"`, `"8."`,\nor the heading text).\n\n## Output\n\n`export({ format, mode? })` with `docx`, `pdf`, `markdown`, `html`, `txt`;\n`mode: "final"` accepts everything. Returns `bytes`, `mode`,\n`pendingTrackedChanges`, `fidelity` (.docx: `"graft"` kept untouched content\nbyte for byte, `"regenerated"` wrote it fresh), `warnings`.\n`renderPages({ startPage, pageCount, view })` \u2192 one PNG (needs `@napi-rs/canvas`).\n`compare(a, b)` \u2192 a redline document; `convert(source, format)` \u2192 bytes.\nRaw package: `listParts`, `catPart`, `patchPackage`.\n\n## Your own model loop\n\n`agentTools(doc, { provider })` returns the tools in the shape a model API\nexpects and a `handle` that runs one call and returns the result message.\nProviders: `"anthropic"` (Messages `tool_use` \u2192 `tool_result`), `"openai"` (Chat\nCompletions `tool_calls` \u2192 `role: "tool"`), `"openai-responses"`\n(`function_call` \u2192 `function_call_output`). No model SDK is a dependency.\n\n```ts\nimport Anthropic from "@anthropic-ai/sdk";\nimport { ReviseDocument, agentTools } from "revise";\n\nconst anthropic = new Anthropic();\nconst doc = await ReviseDocument.open("contract.docx", {\n  author: "Contract bot",\n});\nconst agent = agentTools(doc, { provider: "anthropic" });\nconst messages: Anthropic.MessageParam[] = [\n  { role: "user", content: "Change the governing law to New York." },\n];\nfor (;;) {\n  const reply = await anthropic.messages.create({\n    model: "claude-sonnet-5-5",\n    max_tokens: 4096,\n    tools: agent.tools,\n    messages,\n  });\n  messages.push({ role: "assistant", content: reply.content });\n  const calls = reply.content.filter((block) => block.type === "tool_use");\n  if (calls.length === 0) break;\n  messages.push({\n    role: "user",\n    content: await Promise.all(calls.map(agent.handle)),\n  });\n}\n```\n\n`handle` never throws for a bad call; the model gets the error and corrects\nitself. Options: `include`, `exclude`, `maxResultChars`. After compacting the\ntranscript, call `agent.reset()`. Docs: https://revise.io/developer/docs/revise/agents.md\n\n## Collaboration rooms\n\nEvery Revise document is a Y.js document. On a sync server:\n`seedYDoc(room, "contract.docx")` seeds an empty room (safe on every\nconnection); `ReviseDocument.fromYDoc(room, { author })` edits a live room as\ntracked changes that appear in every open `@reviseio/editor`; `export()` downloads\nit. Dispose the ReviseDocument, not the room. Docs:\nhttps://revise.io/developer/docs/revise/collaboration.md\n\n## Errors\n\nExpected failures (missing file, unsupported format, malformed patch) throw\n`ReviseError` with a stable `code`. Tool calls return errors as values.\n';
+var library_default = '# revise as a TypeScript library\n\nRead this when the work is code, not shell commands: a Node script or service\nthat edits documents, your own model loop with Revise\'s editing tools, or a\ncollaboration server. The CLI is a shell over this API. ESM only, Node 20+.\nFull docs: https://revise.io/developer/docs/revise/library.md\n\n```ts\nimport { writeFile } from "node:fs/promises";\nimport { ReviseDocument } from "revise";\n\nconst doc = await ReviseDocument.open("contract.docx", { author: "Legal bot" });\nawait doc.replaceAll("Provider", "Northstar"); // tracked changes\nawait doc.reject({ section: "8" });\nconst { bytes, fidelity } = await doc.export({ format: "docx" });\nawait writeFile("contract-out.docx", bytes);\ndoc.dispose();\n```\n\n## Open\n\n- `ReviseDocument.open(source, options?)`: a path, or `{ bytes, filename }`\n  (.docx, .odt, .rtf, .md, .html, .txt). A Word file keeps its package, so\n  untouched content exports byte for byte.\n- `ReviseDocument.create({ html?, markdown?, title? })`, `ReviseDocument.restore(snapshot)`,\n  `ReviseDocument.fromYDoc(ydoc)` (a Y.Doc you own, such as a live room).\n- Options: `author`, `mode` (`"suggesting"`: tracked changes, the default for\n  Word files; `"editing"`: direct), `documentId`, `images`.\n- Calls run one at a time in order; call `dispose()` when done.\n\n## Read\n\n`status()`, `outline()`, `summary()`, `grep(text, { ignoreCase })` \u2192\n`[{ id, blockIndex, count, text }]`.\n\n## Edit\n\n- `replaceAll(find, replace, { ids? })` \u2192 `{ replaced, blocks, changeIds, failures }`.\n- Everything else is an editing tool: `doc.tools.definitions()` lists them with\n  JSON schemas; `doc.tools.call(name, input)` runs one with typed input;\n  `doc.tools.run(name, input)` with untyped input, as a model sends it. Neither\n  throws for a bad edit: `{ ok: true, value }` or `{ ok: false, error }`.\n- `await doc.setMode("editing" | "suggesting")`.\n\n## Review\n\n`changes({ section? })`, `preview(selection)`, `accept(selection)`,\n`reject(selection)` \u2192 `{ resolved, missing, unresolved }`, `diff()`. A selection\nis exactly one of `ids`, `all`, or `section` / `exceptSection` (`"8"`, `"8."`,\nor the heading text).\n\n## Output\n\n`export({ format, view? })` with `docx`, `pdf`, `markdown`, `html`, `txt`;\n`view: "accepted"` accepts everything, `"original"` rejects it. Returns `bytes`, `mode`, `view`,\n`pendingTrackedChanges`, `fidelity` (.docx: `"graft"` kept untouched content\nbyte for byte, `"regenerated"` wrote it fresh), `warnings`.\n`renderPages({ startPage, pageCount, view })` \u2192 one PNG (needs `@napi-rs/canvas`).\n`compare(a, b)` \u2192 a redline document; `convert(source, format)` \u2192 bytes.\nRaw package: `listParts`, `catPart`, `patchPackage`.\n\n## Your own model loop\n\n`agentTools(doc, { provider })` returns the tools in the shape a model API\nexpects and a `handle` that runs one call and returns the result message.\nProviders: `"anthropic"` (Messages `tool_use` \u2192 `tool_result`), `"openai"` (Chat\nCompletions `tool_calls` \u2192 `role: "tool"`), `"openai-responses"`\n(`function_call` \u2192 `function_call_output`). No model SDK is a dependency.\n\n```ts\nimport Anthropic from "@anthropic-ai/sdk";\nimport { ReviseDocument, agentTools } from "revise";\n\nconst anthropic = new Anthropic();\nconst doc = await ReviseDocument.open("contract.docx", {\n  author: "Contract bot",\n});\nconst agent = agentTools(doc, { provider: "anthropic" });\nconst messages: Anthropic.MessageParam[] = [\n  { role: "user", content: "Change the governing law to New York." },\n];\nfor (;;) {\n  const reply = await anthropic.messages.create({\n    model: "claude-sonnet-5-5",\n    max_tokens: 4096,\n    tools: agent.tools,\n    messages,\n  });\n  messages.push({ role: "assistant", content: reply.content });\n  const calls = reply.content.filter((block) => block.type === "tool_use");\n  if (calls.length === 0) break;\n  messages.push({\n    role: "user",\n    content: await Promise.all(calls.map(agent.handle)),\n  });\n}\n```\n\n`handle` never throws for a bad call; the model gets the error and corrects\nitself. Options: `include`, `exclude`, `maxResultChars`. After compacting the\ntranscript, call `agent.reset()`. Docs: https://revise.io/developer/docs/revise/agents.md\n\n## Collaboration rooms\n\nEvery Revise document is a Y.js document. On a sync server:\n`seedYDoc(room, "contract.docx")` seeds an empty room (safe on every\nconnection); `ReviseDocument.fromYDoc(room, { author })` edits a live room as\ntracked changes that appear in every open `@reviseio/editor`; `export()` downloads\nit. Dispose the ReviseDocument, not the room. Docs:\nhttps://revise.io/developer/docs/revise/collaboration.md\n\n## Errors\n\nExpected failures (missing file, unsupported format, malformed patch) throw\n`ReviseError` with a stable `code`. Tool calls return errors as values.\n';
 
 // src/embed-sdk/cli/skills/revise/reference/json.md
 var json_default = '# Scripting revise: --json, exit codes, error codes\n\nRead this when a script or program runs revise and needs to branch on the\nresult. Full contract: https://revise.io/developer/docs/revise/json.md (also\nshipped as a JSON Schema: `revise/cli-output.schema.json`).\n\n## The envelope\n\nWith `--json`, every command prints exactly one JSON object on stdout and\nnothing on stderr:\n\n```json\n{"schema":1,"ok":true,"command":"status","meta":{"version":"3.0.0","build":"\u2026"},\n "data":{\u2026},"warnings":[],"error":null}\n```\n\n- `ok` is true exactly when `error` is null. `data` can be present on failure\n  (what was saved before the failure) and null on success with nothing to say.\n- `command` is the canonical name (`xml patch`, `skill install`; `call` for\n  `revise <tool> <file>`; `help` for any `--help`).\n- Within schema 1, fields are only added. Ignore unknown fields; handle unknown\n  codes generically.\n- Inside `data`: camelCase keys, counts end in `Count`, paths are absolute,\n  n/a values are `null`, empty lists are `[]`.\n- Writing a document to stdout (`revise convert x.docx -`) can\'t combine with\n  `--json`.\n\n## Exit codes\n\n| Code | Meaning                                                                                       |\n| ---- | --------------------------------------------------------------------------------------------- |\n| 0    | Done, including "nothing to change".                                                          |\n| 1    | Failed, nothing saved. Human mode prints nothing on stdout.                                   |\n| 2    | Partly done: `data` says what happened, `error` what didn\'t.                                  |\n| 70   | Internal error, or `save_uncertain`: check the file; the next command on it settles the save. |\n\n## Errors and warnings\n\n`error`: `code` (stable, branch on it), `message` (for people and models;\nwording may change), `hint` (a shell command to run next, or null),\n`details` (structured, or null). Warnings have the same shape minus `hint`.\n\nCommon error codes: `usage`, `unknown_command`, `unknown_tool`,\n`file_not_found`, `unsupported_format`, `import_failed`, `would_overwrite`\n(add `--force`), `same_file`, `file_busy`, `file_changed` (another program saved\nit; run again), `tool_error` (a tool refused: `details.toolCode`),\n`unknown_search_result` / `stale_search_result` (search again),\n`change_not_found`, `find_not_found` / `find_ambiguous` (xml patch),\n`body_shape_changed` (use the tools for body text), `save_uncertain`,\n`internal`.\n\nWarnings worth acting on: `file_changed_outside` (re-read the blocks in\n`details.changedBlockIds` before editing them), `changes_accepted` (the output\nformat can\'t hold tracked changes), `font_fallback`, `untracked_regions`\n(compare).\n\n## Saving\n\nCommands that change a document report `file`, `saved` (did this command\nwrite it), and `checkpoint` (where the file is now; `revise undo <file>` steps\nback). Commands that write another file report `output` and `outputWritten`.\nWith `--out`, edits report `copiedFrom` (the original) and `file` (the copy).\nTool calls also report `changeIds` (tracked changes created), `html` (blocks\nreturned, with ids), and `result` (the tool\'s own result; snake_case keys like\n`search_result_id`).\n';
@@ -662,6 +663,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "dry-run",
   "regex",
   "ignore-case",
+  "exact",
   "json",
   "all",
   "final",
@@ -675,6 +677,10 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
 ]);
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "author",
+  "blocks",
+  "content",
+  "page-size",
+  "results-page",
   "dir",
   "except-section",
   "file",
@@ -739,6 +745,33 @@ function flagString(args, name) {
   const value = args.flags[name];
   return typeof value === "string" ? value : void 0;
 }
+function blockIdsFlag(args, command) {
+  const value = flagString(args, "blocks") ?? flagString(args, "ids");
+  if (value === void 0) return void 0;
+  const blocks = parseBlockQuery(value);
+  if (blocks.some((b) => typeof b !== "string")) {
+    throw fail(
+      `revise ${command} takes block ids, not ranges.`,
+      "usage",
+      `revise ${command} --help`
+    );
+  }
+  return blocks;
+}
+var VIEWS = ["tracked", "accepted", "original"];
+function viewFlag(args, fallback) {
+  const view = flagString(args, "view");
+  if (view !== void 0 && !VIEWS.includes(view)) {
+    throw fail("--view must be tracked, accepted, or original.", "usage");
+  }
+  if (args.flags.final === true) {
+    if (view !== void 0 && view !== "accepted") {
+      throw fail(`--final means --view accepted, not --view ${view}.`, "usage");
+    }
+    return "accepted";
+  }
+  return view ?? fallback;
+}
 function flagInt(args, name) {
   const value = flagString(args, name);
   if (value === void 0) return void 0;
@@ -837,8 +870,8 @@ var ui = PLAIN;
 var uiErr = PLAIN;
 function producer() {
   return {
-    version: true ? "3.0.1" : "dev",
-    build: true ? "7ef88f310" : null
+    version: true ? "3.1.0" : "dev",
+    build: true ? "7cded52c5" : null
   };
 }
 var warnings = [];
@@ -1249,7 +1282,7 @@ async function restoreReadContext(loaded, input) {
   }
 }
 function cliVocabulary(message, file) {
-  return message.replace(/read_blocks_from_index\(index=(\d+)\)/g, `revise read ${file} $1`).replace(/read_specific_blocks\b/g, `revise read ${file} --ids`).replace(/search_document\b/g, `revise search ${file}`);
+  return message.replace(/read_blocks_from_index\(index=(\d+)\)/g, `revise read ${file} $1`).replace(/read_specific_blocks\b/g, `revise read ${file} --blocks`).replace(/search_document\b/g, `revise search ${file}`);
 }
 function toolData(loaded, tool, fields) {
   return { file: loaded.meta.file, tool, ...fields };
@@ -1309,7 +1342,7 @@ async function runTool(loaded, name, input, options = {}) {
   const { result, checkpoint } = await mutate(
     loaded,
     name,
-    () => loaded.doc.tools.run(name, input, options),
+    () => loaded.doc.tools.run(name, input, { direct: options.direct }),
     (r) => "error" in r ? r.error.message : r.value.message ?? name,
     { saveIf: (r) => !("error" in r) }
   );
@@ -1360,16 +1393,19 @@ async function runTool(loaded, name, input, options = {}) {
     value = persistSearch(loaded.meta, input, value);
   if (value.context?.html) rememberReadBlocks(loaded.meta, value.context.html);
   const changeIds = value.suggestionIds ?? [];
-  const html = value.context?.html ?? null;
+  const html = value.context?.html && options.view && options.view !== "accepted" ? await loaded.doc.viewHtml(value.context.html, options.view) : value.context?.html ?? null;
   return {
-    data: toolData(loaded, name, {
-      saved: checkpoint !== null,
-      checkpoint: now,
-      message: value.message,
-      changeIds,
-      html,
-      result: value.data ?? null
-    }),
+    data: {
+      ...toolData(loaded, name, {
+        saved: checkpoint !== null,
+        checkpoint: now,
+        message: value.message,
+        changeIds,
+        html,
+        result: value.data ?? null
+      }),
+      ...options.view ? { view: options.view } : {}
+    },
     text: () => {
       const lines = [];
       if (value.message)
@@ -1455,7 +1491,7 @@ async function cmdNew(args) {
   if (requestedMode && !["suggest", "edit"].includes(requestedMode)) {
     throw fail("--mode must be suggest or edit.", "usage", "revise new --help");
   }
-  const from = flagString(args, "from");
+  const from = flagString(args, "content") ?? flagString(args, "from");
   if (from !== void 0 && !fs2.existsSync(from)) {
     throw fail(`No such file: ${from}`, "file_not_found");
   }
@@ -1510,11 +1546,11 @@ function newDocumentSteps(args, probe) {
   const layout = probe.tools.definitions().find((tool) => tool.name === "set_page_layout");
   const allowed = (property) => layout?.inputSchema.properties?.[property]?.enum ?? [];
   const layoutInput = {};
-  const page = flagString(args, "page")?.toLowerCase();
+  const page = (flagString(args, "page-size") ?? flagString(args, "page"))?.toLowerCase();
   if (page !== void 0) {
     if (!allowed("pageSize").includes(page)) {
       throw fail(
-        `--page must be one of: ${allowed("pageSize").join(", ")}.`,
+        `--page-size must be one of: ${allowed("pageSize").join(", ")}.`,
         "usage",
         "revise new --help"
       );
@@ -1657,22 +1693,111 @@ async function cmdStatus(args) {
 }
 async function cmdRead(args) {
   const loaded = await loadDocument(args);
-  const ids = flagString(args, "ids");
+  const ids = blockIdsFlag(args, "read");
+  const view = viewFlag(args, "tracked");
   if (ids) {
-    return runTool(loaded, "read_specific_blocks", {
-      block_ids: ids.split(",").map((id) => id.trim()).filter(Boolean)
-    });
+    return runTool(
+      loaded,
+      "read_specific_blocks",
+      { block_ids: ids },
+      { view }
+    );
   }
   const index = strictInt(args.positional[0] ?? "0", "The block index");
-  return runTool(loaded, "read_blocks_from_index", { index });
+  return runTool(loaded, "read_blocks_from_index", { index }, { view });
 }
 async function cmdSearch(args) {
   if (!args.positional.length) throw usageError("search");
+  const view = viewFlag(args, "tracked");
   const loaded = await loadDocument(args);
-  return runTool(loaded, "search_document", {
-    queries: args.positional,
-    page: flagInt(args, "page") ?? 1
+  const textMatches = (only) => args.positional.flatMap((query) => {
+    const matcher = query.startsWith("regex:") ? safeRegExp(query.slice(6)) : query;
+    return loaded.doc.grep(matcher, { ignoreCase: true, view: "original" }).filter(
+      (hit) => only ? hit.matches.some((m) => m.change === only) : true
+    ).map((hit) => ({
+      query,
+      blockId: hit.id,
+      blockIndex: hit.blockIndex,
+      text: hit.text,
+      changeIds: [
+        ...new Set(
+          hit.matches.filter((m) => m.change === "deleted").map((m) => m.changeId ?? "")
+        )
+      ].filter(Boolean)
+    }));
   });
+  const viewLines = (matches, heading) => matches.length ? [
+    "",
+    heading,
+    ...matches.map(
+      (m) => `${ui.cyan(m.blockId)}  ${highlight(m.text, m.query.startsWith("regex:") ? safeRegExp(m.query.slice(6)) : m.query, true)}`
+    )
+  ] : [];
+  if (view === "original") {
+    const matches = textMatches(null);
+    rememberReadBlocks(
+      loaded.meta,
+      matches.map((m) => `<p id="${m.blockId}">`).join("")
+    );
+    return {
+      data: {
+        ...toolData(loaded, "search_document", {
+          saved: false,
+          checkpoint: currentCheckpoint(loaded.meta),
+          message: null,
+          changeIds: [],
+          html: null,
+          result: null
+        }),
+        view,
+        viewMatches: matches
+      },
+      text: () => matches.length ? [
+        ...viewLines(
+          matches,
+          `${plural(matches.length, "block")} match in the original text (before the pending changes):`
+        ).slice(1),
+        "",
+        ui.dim(
+          "No search_result_id: it names blocks of the current text. Search without --view original for one."
+        )
+      ].join("\n") : `No matches in the original text for ${args.positional.map((q) => `"${q}"`).join(", ")}.`
+    };
+  }
+  const outcome = await runTool(
+    loaded,
+    "search_document",
+    {
+      queries: args.positional,
+      // --page is the 3.0 name.
+      page: flagInt(args, "results-page") ?? flagInt(args, "page") ?? 1
+    },
+    { view }
+  );
+  if (view !== "tracked" || outcome.error) return outcome;
+  const deleted = textMatches("deleted");
+  rememberReadBlocks(
+    loaded.meta,
+    deleted.map((m) => `<p id="${m.blockId}">`).join("")
+  );
+  return {
+    ...outcome,
+    data: { ...outcome.data, viewMatches: deleted },
+    text: () => [
+      outcome.text(),
+      ...viewLines(
+        deleted,
+        `Also in deleted text (pending changes; ${ui.dim("[-deleted-]{+inserted+}")}):`
+      )
+    ].join("\n")
+  };
+}
+function safeRegExp(pattern) {
+  try {
+    return new RegExp(pattern, "gi");
+  } catch {
+    return pattern;
+  }
 }
 async function cmdOutline(args) {
   const loaded = await loadDocument(args);
@@ -1807,8 +1932,11 @@ var BEFORE_FIRST_HEADING = "(before the first heading)";
 async function cmdChanges(args) {
   const loaded = await loadDocument(args);
   const section = flagString(args, "section");
-  const changes = await loaded.doc.changes({ section });
-  const details = args.flags.details === true || Boolean(section);
+  const blocksFlag = flagString(args, "blocks");
+  const blocks = blocksFlag ? parseBlockQuery(blocksFlag) : void 0;
+  const changes = await loaded.doc.changes({ section, blocks });
+  const filtered = Boolean(section || blocks);
+  const details = args.flags.details === true || filtered;
   const entries = changes.map((c) => ({
     changeId: c.id,
     type: c.type,
@@ -1824,17 +1952,18 @@ async function cmdChanges(args) {
     `revise accept ${loaded.shown} <change-id...>`,
     `revise reject ${loaded.shown} <change-id...>`
   ) + `
-${ui.dim(`      (or --all, --section <number or title>; add --dry-run to preview)`)}`;
+${ui.dim(`      (or --all, --section <number or title>, --blocks <id,id or first..last>; add --dry-run to preview)`)}`;
   return {
     data: {
       file: loaded.meta.file,
       section: section ?? null,
+      blocks: blocksFlag ?? null,
       trackedChangeCount: entries.length,
       changes: entries
     },
     text: () => {
       if (!entries.length) {
-        return section ? `No tracked changes in section "${section}".` : "No tracked changes.";
+        return section ? `No tracked changes in section "${section}"${blocks ? " and those blocks" : ""}.` : blocks ? "No tracked changes in those blocks." : "No tracked changes.";
       }
       if (!details && entries.length > 30) {
         return [
@@ -1885,10 +2014,18 @@ async function cmdSettle(args, accept) {
   const all = args.flags.all === true;
   const section = flagString(args, "section");
   const exceptSection = flagString(args, "except-section");
-  if (!all && !section && !exceptSection && !args.positional.length) {
+  const blocksFlag = flagString(args, "blocks");
+  const blocks = blocksFlag ? parseBlockQuery(blocksFlag) : void 0;
+  if (!all && !section && !exceptSection && !blocks && !args.positional.length) {
     throw usageError(action);
   }
-  const selection = { ids: args.positional, all, section, exceptSection };
+  const selection = {
+    ids: args.positional,
+    all,
+    section,
+    exceptSection,
+    blocks
+  };
   const base = {
     file: loaded.meta.file,
     action
@@ -1955,7 +2092,7 @@ async function cmdSettle(args, accept) {
   const done = accept ? "Accepted" : "Rejected";
   const failedOutright = !result.resolved.length && (result.missing.length || failed.length);
   const text = () => failedOutright ? "" : [
-    result.resolved.length ? `${ui.green(done)} ${plural(result.resolved.length, "tracked change")}.` : section || exceptSection ? "No tracked changes matched." : "No tracked changes to " + action + ".",
+    result.resolved.length ? `${ui.green(done)} ${plural(result.resolved.length, "tracked change")}.` : section || exceptSection || blocks ? "No tracked changes matched." : "No tracked changes to " + action + ".",
     ...checkpoint !== null ? [savedLine(loaded, checkpoint)] : []
   ].join("\n");
   if (result.missing.length || failed.length) {
@@ -2154,7 +2291,7 @@ async function cmdExport(args) {
   assertCanOverwrite(args, out2);
   const result = await loaded.doc.export({
     format,
-    mode: args.flags.final === true ? "final" : "review"
+    view: viewFlag(args, "tracked")
   });
   writeOutput(args, out2, result.bytes);
   let summary = null;
@@ -2194,15 +2331,16 @@ async function cmdExport(args) {
       format: formatName(format),
       byteCount: result.bytes.length,
       final: result.mode === "final",
+      view: result.view,
       trackedChangeCount,
       docxExport,
       summary
     },
     text: () => [
-      `${ui.green("Wrote")} ${shellArg(target)} (${sizeText(result.bytes.length)}${result.mode === "final" ? ", tracked changes accepted" : ""}).`,
+      `${ui.green("Wrote")} ${shellArg(target)} (${sizeText(result.bytes.length)}${result.view === "original" ? ", as it was before the tracked changes" : result.mode === "final" ? ", tracked changes accepted" : ""}).`,
       ...summary ? [summaryText(summary)] : [],
       ...format === "docx" && trackedChangeCount ? [
-        `Keeps the tracked changes and comments for review. ${ui.dim("For a clean copy, add --final.")}`
+        `Keeps the tracked changes and comments for review. ${ui.dim("For a clean copy, add --view accepted.")}`
       ] : []
     ].join("\n")
   };
@@ -2283,11 +2421,13 @@ async function cmdConvert(args) {
       `revise convert ${shellArg(input)} ${shellArg(target)}`
     );
   }
-  const final = args.flags.final === true || format !== "docx";
+  const asked = viewFlag(args, "tracked");
+  const view = asked === "tracked" && format !== "docx" ? "accepted" : asked;
+  const final = view !== "tracked";
   const bytes = await convert(
     source ? { bytes: source.bytes, filename: `document.${source.format}` } : input,
     format,
-    { mode: final ? "final" : "review" }
+    { view }
   );
   if (out2 === null) await (io.writeStdout ?? defaultIo().writeStdout)(bytes);
   else writeOutput(args, out2, bytes);
@@ -2299,7 +2439,8 @@ async function cmdConvert(args) {
       outputWritten: out2 !== null,
       format: formatName(format),
       byteCount: bytes.length,
-      final
+      final,
+      view
     },
     // The document is the output; a report on stdout would corrupt it.
     text: () => out2 === null ? "" : `${ui.green("Wrote")} ${shellArg(target)} (${sizeText(bytes.length)})${source ? ` from stdin (${source.format})` : ""}.`
@@ -2427,7 +2568,8 @@ async function cmdGrep(args) {
       );
     }
   }
-  const hits = loaded.doc.grep(matcher, { ignoreCase });
+  const view = viewFlag(args, "tracked");
+  const hits = loaded.doc.grep(matcher, { ignoreCase, view });
   rememberReadBlocks(
     loaded.meta,
     hits.map((hit) => `<p id="${hit.id}">`).join("")
@@ -2439,28 +2581,38 @@ async function cmdGrep(args) {
       pattern,
       regex,
       ignoreCase,
+      view,
       matchCount,
       blocks: hits.map((hit) => ({
         blockId: hit.id,
         blockIndex: hit.blockIndex,
         matchCount: hit.count,
-        text: hit.text
+        text: hit.text,
+        matches: hit.matches
       }))
     },
     text: () => hits.length ? [
       ...hits.map(
-        (hit) => `${ui.cyan(hit.id)}  ${highlight(hit.text, matcher, ignoreCase)}`
+        (hit) => `${ui.cyan(hit.id)}  ${highlight(hit.text, matcher, ignoreCase)}${inChanges(hit.matches)}`
       ),
       "",
       `${plural(matchCount, "match", "matches")} in ${plural(hits.length, "block")}.`,
       nextLine(
         "Edit",
-        `revise replace-text ${loaded.shown} "<find>" "<replace>"`,
+        `revise replace-all ${loaded.shown} "<find>" "<replace>"`,
         `revise call ${loaded.shown} replace '{"id":"<block-id>","replacements":[{"find":"\u2026","replace":"\u2026"}]}'`
       )
     ].join("\n") : `No matches for "${pattern}".`
   };
 }
+function inChanges(matches) {
+  const count = (change) => matches.filter((m) => m.change === change).length;
+  const parts = [
+    count("deleted") ? `${count("deleted")} in deleted text` : "",
+    count("inserted") ? `${count("inserted")} in inserted text` : ""
+  ].filter(Boolean);
+  return parts.length ? ui.dim(`  (${parts.join(", ")})`) : "";
+}
 function highlight(text, matcher, ignoreCase) {
   if (!ui.enabled) return text;
   const re = typeof matcher === "string" ? new RegExp(
@@ -2469,15 +2621,19 @@ function highlight(text, matcher, ignoreCase) {
   ) : matcher;
   return text.replace(re, (m) => m ? ui.bold(ui.yellow(m)) : m);
 }
-async function cmdReplaceText(args) {
+async function cmdReplaceAll(args) {
   const [find, replacement] = args.positional;
-  if (!find || replacement === void 0) throw usageError("replace-text");
+  if (!find || replacement === void 0) throw usageError("replace-all");
   const loaded = await loadDocument(args);
-  const ids = flagString(args, "ids")?.split(",").map((id) => id.trim());
+  const blocks = blockIdsFlag(args, "replace-all");
   const { result, checkpoint } = await mutate(
     loaded,
-    "replace-text",
-    () => loaded.doc.replaceText(find, replacement, { ids }),
+    "replace-all",
+    () => loaded.doc.replaceAll(find, replacement, {
+      blocks,
+      ignoreCase: args.flags["ignore-case"] === true,
+      exact: args.flags.exact === true
+    }),
     (r) => `Replaced "${find}" with "${replacement}" in ${plural(r.blocks.length - r.failures.length, "block")}`
   );
   const data = {
@@ -2486,19 +2642,33 @@ async function cmdReplaceText(args) {
     replace: replacement,
     matchedBlockIds: result.blocks,
     replacedOccurrences: result.replaced,
+    regions: result.regions,
+    nearMisses: result.nearMisses,
     changeIds: result.changeIds,
     failures: result.failures,
     saved: checkpoint !== null,
     checkpoint: currentCheckpoint(loaded.meta)
   };
   const edited = result.blocks.length - result.failures.length;
+  const elsewhere = [
+    ["header", "the header"],
+    ["footer", "the footer"],
+    ["footnote", "footnotes"],
+    ["endnote", "endnotes"]
+  ].filter(([region]) => result.regions[region]).map(([region, label]) => `${result.regions[region]} in ${label}`);
+  const missedLines = result.nearMisses.map(
+    (m) => `${ui.yellow("Not replaced:")} ${plural(m.count, "match", "matches")} of "${m.text}" (${m.reason === "case" ? "different capitalization; add --ignore-case" : "different characters; drop --exact"}).`
+  );
   const text = () => {
-    if (!result.blocks.length) return `No block contains "${find}".`;
+    if (!result.blocks.length) {
+      return [`No block contains "${find}".`, ...missedLines].join("\n");
+    }
     if (find === replacement || !result.replaced) {
       return result.failures.length ? "" : "Already matches: nothing to change. File not rewritten.";
     }
     return [
-      `${ui.green("Replaced")} ${plural(result.replaced, "occurrence")} of "${find}" in ${plural(edited, "block")}${loaded.meta.mode === "suggesting" ? " as tracked changes" : ""}.`,
+      `${ui.green("Replaced")} ${plural(result.replaced, "occurrence")} of "${find}" in ${plural(edited, "block")}${elsewhere.length ? ` (${elsewhere.join(", ")})` : ""}${loaded.meta.mode === "suggesting" ? " as tracked changes" : ""}.`,
+      ...missedLines,
       ...result.changeIds.length ? [
         result.changeIds.length <= 6 ? `Tracked changes: ${result.changeIds.map((id) => ui.cyan(id)).join(", ")}` : `${plural(result.changeIds.length, "tracked change")}. ${ui.dim("List:")} ${ui.cyan(`revise changes ${loaded.shown}`)}`
       ] : [],
@@ -2513,7 +2683,7 @@ async function cmdReplaceText(args) {
       error: {
         code: "replace_failed",
         message: `Could not edit ${plural(result.failures.length, "block")}: ${result.failures.map((f) => `${f.blockId} (${f.message})`).join("; ")}${checkpoint !== null ? ` ${plural(edited, "other block was", "other blocks were")} edited and saved.` : " Nothing was saved."}`,
-        hint: `revise read ${loaded.shown} --ids ${result.failures.map((f) => f.blockId).join(",")}`,
+        hint: `revise read ${loaded.shown} --blocks ${result.failures.map((f) => f.blockId).join(",")}`,
         details: { failures: result.failures }
       }
     };
@@ -2624,7 +2794,7 @@ var EXAMPLES = [
   },
   {
     description: "Rename a party everywhere, as tracked changes",
-    command: 'revise replace-text contract.docx "Acme" "Northstar" --author "Legal bot"'
+    command: 'revise replace-all contract.docx "Acme" "Northstar" --author "Legal bot"'
   },
   {
     description: "Run any editing tool (revise tools lists them): here, a page-numbered footer",
@@ -2689,8 +2859,11 @@ async function cmdSkill(args, install) {
     text: () => `${ui.green("Installed")} ${dir}/ (SKILL.md and reference/)`
   };
 }
+var RENAMED_COMMANDS = {
+  "replace-text": "replace-all"
+};
 var OUT_COMMANDS = /* @__PURE__ */ new Set([
-  "replace-text",
+  "replace-all",
   "call",
   "accept",
   "reject",
@@ -2816,6 +2989,18 @@ var FORCE = [
   "--force",
   "Replace the output file if it exists"
 ];
+var SECTION_OPTION = [
+  "--section <s>",
+  'A heading and its subsections: "8", "8.1", or its title'
+];
+var BLOCKS_OPTION = [
+  "--blocks <b>",
+  "Block ids and ranges: id,id or first..last"
+];
+var VIEW_OPTION = [
+  "--view <view>",
+  "tracked (default): pending changes marked; accepted; or original"
+];
 var OUT_OPTION = [
   "--out <file>",
   "Save the result as a new file (same format) and leave this one untouched; --force replaces an existing one"
@@ -2840,36 +3025,55 @@ var COMMAND_HELP = [
   {
     name: "read",
     group: "Reading",
-    usage: "revise read <file> [<index>] [--ids <id,id>]",
-    summary: "Blocks as HTML with block ids",
+    usage: "revise read <file> [<index>] [--blocks <id,id>] [--view <view>]",
+    summary: "Blocks as HTML with block ids; pending changes as <ins>/<del>",
     options: [
       ["<index>", "Block index to start from (0-based, default 0)"],
-      ["--ids <id,id>", "Read these blocks instead"]
+      ["--blocks <id,id>", "Read these blocks instead"],
+      VIEW_OPTION
     ]
   },
   {
     name: "grep",
     group: "Reading",
-    usage: 'revise grep <file> "<text>" [--regex] [--ignore-case]',
+    usage: 'revise grep <file> "<text>" [--regex] [--ignore-case] [--view <view>]',
     summary: "Matching blocks as plain text with ids",
     options: [
       ["--regex", "Treat the text as a JavaScript regular expression"],
-      ["--ignore-case", "Match regardless of case"]
+      ["--ignore-case", "Match regardless of case"],
+      [
+        "--view <view>",
+        "tracked (default): matches deleted and inserted text, [-marked-]{+inline+}; accepted; or original"
+      ]
     ]
   },
   {
     name: "search",
     group: "Reading",
-    usage: 'revise search <file> "<text>" ["<text>" ...] [--page <n>]',
+    usage: 'revise search <file> "<text>" ["<text>" ...] [--results-page <n>] [--view <view>]',
     summary: "Matching blocks as HTML, with a search result id",
-    options: [["--page <n>", "Page of results (1-based)"]]
+    options: [
+      ["--results-page <n>", "Page of results (1-based)"],
+      [
+        "--view <view>",
+        "tracked (default): also lists matches in deleted text; accepted; or original (no result id)"
+      ]
+    ]
   },
   {
-    name: "replace-text",
+    name: "replace-all",
     group: "Editing (saves the file)",
-    usage: 'revise replace-text <file> "<find>" "<replace>" [--ids <id,id>]',
-    summary: "Replace every exact occurrence",
-    options: [["--ids <id,id>", "Only in these blocks"], OUT_OPTION]
+    usage: 'revise replace-all <file> "<find>" "<replace>" [--ignore-case] [--exact] [--blocks <id,id>]',
+    summary: "Replace every occurrence: body, headers, footers, notes",
+    options: [
+      ["--ignore-case", "Also PROVIDER and provider"],
+      [
+        "--exact",
+        'Quotes and spaces must match too (by default \u201C and ", no-break and plain spaces match)'
+      ],
+      ["--blocks <id,id>", "Only in these blocks"],
+      OUT_OPTION
+    ]
   },
   {
     name: "call",
@@ -2897,10 +3101,11 @@ var COMMAND_HELP = [
   {
     name: "changes",
     group: "Review",
-    usage: "revise changes <file> [--section <s>] [--details]",
+    usage: "revise changes <file> [--section <s>] [--blocks <b>] [--details]",
     summary: "Tracked changes: where, and what text",
     options: [
-      ["--section <s>", 'Only in one section: "8", "8.", or its title'],
+      SECTION_OPTION,
+      BLOCKS_OPTION,
       ["--details", "List every change, even when there are many"]
     ]
   },
@@ -2919,12 +3124,13 @@ var COMMAND_HELP = [
   {
     name: "accept",
     group: "Review",
-    usage: "revise accept <file> (<change-id> ... | --all | --section <s> | --except-section <s>) [--dry-run]",
+    usage: "revise accept <file> (<change-id> ... | --all | --section <s> | --except-section <s> | --blocks <b>) [--dry-run]",
     summary: "Accept tracked changes",
     options: [
       ["--all", "Every tracked change"],
-      ["--section <s>", 'Changes in one section: "8", "8.", or its title'],
+      SECTION_OPTION,
       ["--except-section <s>", "Every change outside one section"],
+      BLOCKS_OPTION,
       ["--dry-run", "Show what would be accepted; change nothing"],
       OUT_OPTION
     ]
@@ -2932,12 +3138,13 @@ var COMMAND_HELP = [
   {
     name: "reject",
     group: "Review",
-    usage: "revise reject <file> (<change-id> ... | --all | --section <s> | --except-section <s>) [--dry-run]",
+    usage: "revise reject <file> (<change-id> ... | --all | --section <s> | --except-section <s> | --blocks <b>) [--dry-run]",
     summary: "Reject tracked changes",
     options: [
       ["--all", "Every tracked change"],
-      ["--section <s>", 'Changes in one section: "8", "8.", or its title'],
+      SECTION_OPTION,
       ["--except-section <s>", "Every change outside one section"],
+      BLOCKS_OPTION,
       ["--dry-run", "Show what would be rejected; change nothing"],
       OUT_OPTION
     ]
@@ -2968,7 +3175,7 @@ var COMMAND_HELP = [
     options: [
       ["--page <n>", "Page to render (1-based, default 1)"],
       ["--pages <n-m>", "Up to 6 pages in one image"],
-      ["--view <view>", "tracked (default), accepted, or original"],
+      VIEW_OPTION,
       ["--layout", "Outline layout boxes"],
       ["--detailed", "Full resolution for several pages"],
       ["--out <file>", "Where to save it (default: inside .revise/)"]
@@ -2977,20 +3184,26 @@ var COMMAND_HELP = [
   {
     name: "export",
     group: "Output",
-    usage: "revise export <file> <output> [--final] [--force]",
+    usage: "revise export <file> <output> [--view <view>] [--force]",
     summary: "Write a copy as .docx, .pdf, .md, .html, or .txt",
-    options: [["--final", "Accept every tracked change in the copy"], FORCE]
+    options: [
+      [
+        "--view <view>",
+        "tracked (default; only .docx keeps changes), accepted, or original"
+      ],
+      FORCE
+    ]
   },
   {
     name: "new",
     group: "Create and convert",
-    usage: "revise new <output> [--from <draft.html|.md>] [options]",
+    usage: "revise new <output> [--content <draft.html|.md>] [options]",
     summary: "Create a document, in edit mode",
     options: [
-      ["--from <file>", "Start from HTML or Markdown"],
+      ["--content <file>", "Start from HTML or Markdown"],
       ["--title <text>", "Document title"],
       ["--mode suggest", "Start in suggest mode instead"],
-      ["--page <size>", "letter, a4, legal, ..."],
+      ["--page-size <size>", "letter, a4, legal, ..."],
       ["--orientation <o>", "portrait or landscape"],
       ["--margins <length>", "For example 1in or 2.5cm"],
       ["--header <text>", "Header text (also --header-left/-center/-right)"],
@@ -3012,10 +3225,13 @@ var COMMAND_HELP = [
   {
     name: "convert",
     group: "Create and convert",
-    usage: "revise convert <input|-> <output|-> [--final] [--force]",
-    summary: "Convert between .docx, .md, .html, .odt, .rtf, .txt, .pdf",
+    usage: "revise convert <input|-> <output|-> [--view <view>] [--force]",
+    summary: "Convert .docx .md .html .odt .rtf .txt to .docx .md .html .txt .pdf",
     options: [
-      ["--final", "Accept every tracked change"],
+      [
+        "--view <view>",
+        "tracked (default; only .docx keeps changes), accepted, or original"
+      ],
       FORCE,
       [
         "--from <format>",
@@ -3151,7 +3367,7 @@ var FILE_COMMANDS = /* @__PURE__ */ new Set([
   "read",
   "grep",
   "search",
-  "replace-text",
+  "replace-all",
   "call",
   "mode",
   "changes",
@@ -3318,7 +3534,11 @@ async function main(argv, cliIo) {
   };
   try {
     const args = parseArgs(argv);
-    const first = args.positional.shift();
+    const typed = args.positional.shift();
+    const first = typed && RENAMED_COMMANDS[typed] ? RENAMED_COMMANDS[typed] : typed;
+    if (first === "help" && args.positional[0]) {
+      args.positional[0] = RENAMED_COMMANDS[args.positional[0]] ?? args.positional[0];
+    }
     if ((args.flags.version || first === "version") && !args.flags.help) {
       command = "version";
       const { version, build } = producer();
@@ -3379,7 +3599,7 @@ async function main(argv, cliIo) {
       resolved = "skill install";
     }
     if (args.flags.version) resolved = "version";
-    command = resolved;
+    command = typed && RENAMED_COMMANDS[typed] ? typed : resolved;
     currentCommand = resolved;
     if (shorthandTool) {
       const definition = await toolDefinition(shorthandTool);
@@ -3463,8 +3683,8 @@ ${optionLines(GLOBAL_OPTIONS).join("\n")}`
           return cmdCompare(args);
         case "grep":
           return cmdGrep(args);
-        case "replace-text":
-          return cmdReplaceText(args);
+        case "replace-all":
+          return cmdReplaceAll(args);
         case "xml ls":
           return cmdXml(args, "ls");
         case "xml cat":