revise 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 3.1.2
+
+### Changed
+
+- **`revise skill install` installs where the agent running it reads
+  skills:** `.claude/skills` from Claude Code or in a project with a
+  `.claude` folder, otherwise `.agents/skills`, which Codex, Cursor, Copilot,
+  and others read. It used to fall back to `.claude/skills`, which other
+  agents don't read.
+- **It ends by saying to read the installed SKILL.md now:** a running agent
+  session doesn't load a newly installed skill; new sessions do. The
+  quickest install for any agent with a terminal is
+  `npx -y revise@latest skill install`.
+
+## 3.1.1
+
+### Changed
+
+- **The agent skill is `revise-cli`.** `revise skill install` writes
+  `.agents/skills/revise-cli/` (or `.claude/skills/revise-cli/`) and replaces
+  the `revise/` folder earlier versions installed. As plugins it's
+  `cli@revise`: `claude plugin install cli@revise`,
+  `codex plugin add cli@revise`, or
+  `npx skills add reviseio/skills --skill revise-cli`.
+
 ## 3.1.0
 
 ### Added

package/LICENSE

@@ -19,6 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-This package depends on @reviseio/engine, which is distributed separately
-under its own license (free for any use, including commercial).

package/README.md

@@ -1,19 +1,41 @@
-# revise
+# revise <span style="font-style: italic; font-size: 18px; font-weight: normal; margin-left: 12px">The swiss army knife for documents</span>
 
-Read, edit, and redline Word documents from the command line or TypeScript.
+[![](https://img.shields.io/npm/v/revise)](https://www.npmjs.com/package/revise) [![](https://img.shields.io/badge/read_the-docs-blue)](https://revise.io/developer/docs/revise/cli)
+
+Read, edit, and redline Word documents. Available as CLI and TypeScript library.
 
 ```bash
-npm i -g revise  # or: npx revise <command>
+npx revise
 ```
 
-AI agents using `revise` can edit documents several times faster. Paste this into your agent:
+## For Agents
+
+AI agents using `revise` can work with Word documents several times faster.
+
+To get started, tell your agent:
 
 ```text
 Read https://revise.io/skills/cli.md and follow it.
 ```
 
+Or install the skill directly from a terminal:
+
+```bash
+npx -y revise@latest skill install
+```
+
+## Install
+
+You can also just install the `revise` CLI by itself:
+
+```bash
+npm i -g revise
+```
+
 ## CLI
 
+The `revise` CLI lets you inspect, edit, and convert .docx files.
+
 ```bash
 revise outline contract.docx                              # headings with block ranges
 revise read contract.docx 0                               # blocks as HTML, with ids
@@ -28,6 +50,8 @@ revise export contract.docx contract.pdf                  # .docx .pdf .md .html
 cat notes.md | revise convert - notes.docx
 ```
 
+`revise` was designed primarily for AI agents, and has a whole suite of agent-ready tools for granular editing:
+
 ```bash
 revise tools                        # every editing tool
 revise call contract.docx set_header_footer '{"side":"footer","center":"Page {PAGE} of {PAGES}"}'
@@ -39,15 +63,34 @@ revise examples                     # more
 
 ## Agent skills
 
+Quick install:
+
 ```bash
-claude plugin marketplace add reviseio/skills && claude plugin install revise@revise  # Claude Code
-codex plugin marketplace add reviseio/skills && codex plugin add revise@revise        # Codex
-npx skills add reviseio/skills --skill revise                                         # Cursor, Copilot, Windsurf…
-revise skill install                                                                  # anything else
+revise skill install                                                               # anything else
+```
+
+Claude:
+
+```bash
+claude plugin marketplace add reviseio/skills && claude plugin install cli@revise  # Claude Code
+```
+
+Codex:
+
+```bash
+codex plugin marketplace add reviseio/skills && codex plugin add cli@revise        # Codex
+```
+
+Via `skills`:
+
+```bash
+npx skills add reviseio/skills --skill revise-cli                                  # Cursor, Copilot, Windsurf…
 ```
 
 ## Library
 
+`revise` is also available as a [TypeScript library](https://revise.io/developer/docs/revise/library).
+
 ```ts
 import { ReviseDocument } from "revise";
 
@@ -92,13 +135,8 @@ await doc.replaceAll("draft", "final");
 const { bytes } = await doc.export({ format: "docx" });
 ```
 
-## Links
-
-[Docs](https://revise.io/developer/docs/revise/introduction) ·
-[Changelog](https://revise.io/developer/docs/revise/changelog) ·
-[Browser editor (`@reviseio/editor`)](https://www.npmjs.com/package/@reviseio/editor)
-
 ## License
 
-MIT. Runs on [`@reviseio/engine`](https://www.npmjs.com/package/@reviseio/engine),
-free for any use under its own license.
+`revise` is available under the MIT License.
+
+[`@reviseio/engine`](https://www.npmjs.com/package/@reviseio/engine) is free for any use under its own license.

package/cli.js

@@ -425,13 +425,13 @@ async function withFileLocks(files, work) {
   return take(0);
 }
 
-// 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 --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-cli/SKILL.md
+var SKILL_default = '---\nname: revise-cli\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
+// src/embed-sdk/cli/skills/revise-cli/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.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
+// src/embed-sdk/cli/skills/revise-cli/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';
 
 // src/embed-sdk/cli/skill.ts
@@ -870,8 +870,8 @@ var ui = PLAIN;
 var uiErr = PLAIN;
 function producer() {
   return {
-    version: true ? "3.1.0" : "dev",
-    build: true ? "7cded52c5" : null
+    version: true ? "3.1.2" : "dev",
+    build: true ? "c27d8b5a5" : null
   };
 }
 var warnings = [];
@@ -2846,9 +2846,13 @@ async function cmdSkill(args, install) {
       text: () => markdown.replace(/\n$/, "")
     };
   }
-  const base = flagString(args, "dir") ?? (fs2.existsSync(".agents/skills") ? ".agents/skills" : ".claude/skills");
-  const dir = path2.join(base, "revise");
+  const base = flagString(args, "dir") ?? skillsDirFor(io.env ?? {});
+  const dir = path2.join(base, "revise-cli");
   const file = path2.join(dir, "SKILL.md");
+  const older = path2.join(base, "revise");
+  const olderSkill = path2.join(older, "SKILL.md");
+  const replaced = fs2.existsSync(olderSkill) && /^---\nname: revise\n/.test(fs2.readFileSync(olderSkill, "utf8"));
+  if (replaced) fs2.rmSync(older, { recursive: true, force: true });
   fs2.mkdirSync(path2.join(dir, "reference"), { recursive: true });
   fs2.writeFileSync(file, SKILL_MARKDOWN);
   for (const [name, markdown] of Object.entries(SKILL_REFERENCES)) {
@@ -2856,9 +2860,20 @@ async function cmdSkill(args, install) {
   }
   return {
     data: { output: path2.resolve(file), outputWritten: true },
-    text: () => `${ui.green("Installed")} ${dir}/ (SKILL.md and reference/)`
+    text: () => [
+      `${ui.green("Installed")} ${dir}/ (SKILL.md and reference/)${replaced ? `, replacing the older ${older}/` : ""}.`,
+      // An agent's running session doesn't load a skill installed during
+      // it; new sessions do.
+      `Agents: read ${file} now and follow it. New sessions load it automatically.`
+    ].join("\n")
   };
 }
+function skillsDirFor(env) {
+  if (env.CLAUDECODE) return ".claude/skills";
+  if (fs2.existsSync(".agents/skills")) return ".agents/skills";
+  if (fs2.existsSync(".claude")) return ".claude/skills";
+  return ".agents/skills";
+}
 var RENAMED_COMMANDS = {
   "replace-text": "replace-all"
 };
@@ -3278,7 +3293,7 @@ var COMMAND_HELP = [
     name: "skill install",
     group: "Agents",
     usage: "revise skill install [--dir <dir>]",
-    summary: "Install the agent skill as <dir>/revise/SKILL.md",
+    summary: "Install the agent skill as <dir>/revise-cli/SKILL.md",
     options: [
       [
         "--dir <dir>",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "revise",
-  "version": "3.1.0",
-  "reviseBuild": "7cded52c5",
+  "version": "3.1.2",
+  "reviseBuild": "c27d8b5a5",
   "description": "Read, edit, and redline Word documents from the command line or TypeScript, with tracked changes, comments, and tools for AI agents.",
   "keywords": [
     "docx",
@@ -55,7 +55,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@reviseio/engine": "3.1.0",
+    "@reviseio/engine": "3.1.2",
     "jszip": "^3.10.1",
     "yjs": "^13.6.27"
   },