# Changelog

> Release history for revise, the CLI and TypeScript library.

## 3.1.7

Released with `@reviseio/editor` 3.1.7, the editor's first release in
lockstep with revise: one version and one build for all three packages. A
Y.Doc or .docx moves between the editor and revise unchanged.

### Changed

- **`remove_blocks` takes up to 200 ids** (was 50). Past the limit it removes
  nothing and says how to proceed: pass a search's `search_result_id` to
  remove every match, or send the ids in batches.

### Fixed

- **Page numbers next to an existing header or footer.** `set_page_layout`
  with a page-number position, or a preset that numbers pages (APA puts them
  top right), used to report success while a hand-authored header or footer
  kept the number from appearing. The number now goes into that header's or
  footer's empty zone at the requested side, in the authored text's font. When
  the zone already holds text or the header already shows a page number, the
  result says so and lists the headers and footers instead of claiming the
  layout changed.
- **A `replace` whose `find` and `replace` are identical** fails with an error
  that says so, instead of the generic "no changes detected".

## 3.1.6

### Changed

- **The agent skill knows when revise can't run.** In the Claude and ChatGPT
  apps, a document attached to the chat lives in a sandbox that can't install
  revise. The skill now stops before running anything there and offers the
  Revise app, which opens the document as an editable editor in the chat. If
  the app is connected, it uses it. Agents with a terminal are unaffected, and
  an install that fails on a network error is treated the same way instead of
  being worked around.

## 3.1.5

Agents finish document tasks in fewer commands. Measured on the revise
benchmark, Claude Code and Codex finish its tasks for about 40% less with
revise than without it.

### Added

- **`revise batch <file> '[...]'`** runs several tool calls (for example a
  table row and the total under it, or a `replace_all` and a `replace`) as one
  edit with one save. If any step fails, nothing is saved.
- **`read --section 4,7,9`** reads several sections at once, `--blocks a..b`
  reads a range of ids, and `--count N` limits how many blocks are shown.
- **`grep` takes several phrases** and shows about 80 characters around each
  match instead of the whole block (at most 40 blocks).
- **`outline` lists headings typed as bold body text** first, each with the
  command that turns it into a real heading.
- **PDF exports print the page count and paper size.**

### Changed

- **One `replace` call can edit several blocks:** leave out `id` and each
  `find` edits the one block you've read or grepped that contains it.
- **Saves say what they rewrote:** "Rewrote N edited blocks; the rest of the
  file is copied byte for byte."
- **`read` output is shorter:** it leaves out formatting that writing the
  block back restores anyway (a heading's own style, default table cell
  borders and padding, and the like).
- **`outline` shows one id range per section** (`first..last`) and its word
  count.
- **`compare` says what differs outside the redline:** header and footer
  text and page setup, or that the rest is formatting only.
- **`--dry-run` with `--out`** previews instead of failing.
- **The agent skill is a third shorter** and lists every field of `replace`
  and `leave_comment`, so agents don't need to look them up.

### Fixed

- **`read --blocks a,b`** shows only those blocks, not every block between
  them.
- **`outline` and `read --section`** see every section, not just the first
  100.
- **Rows added with `insert_table_row`** take the alignment, spacing,
  indents, and font of the row they're copied from.

## 3.1.4

### Fixed

- **The package README's heading** reads `revise`.

## 3.1.3

### Changed

- **The package README** has a plain heading and tagline. No changes to the
  CLI or the library.

## 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

- **`--blocks` on `changes`, `accept`, and `reject`.** Select tracked
  changes by block: ids (`--blocks a1B2c3,d4E5f6`) or a range in document
  order (`--blocks a1B2c3..d4E5f6`). Ids of list items, table cells, and
  paragraphs inside them work. In the library: `{ blocks: [...] }`, with
  ranges as `{ from, to }`.
- **`--view tracked|accepted|original`** on `read`, `grep`, `search`,
  `export`, and `convert`. `read` now shows pending changes inline as
  `<del>` and `<ins>` with their change ids and authors; `grep` and `search`
  find text on both sides of a change and say which side it's on. `export`
  and `convert` with `--view original` write the document as it was before
  every pending change. `--final` still means `--view accepted`.
- **`replace-all --ignore-case` and `--exact`.**

### Changed

- **`replace-text` is now `replace-all`** (`replaceAll` in the library). It
  replaces in page headers and footers and in footnotes and endnotes as well
  as the body, and says where. Curly and straight quotes, no-break and plain
  spaces, and no-break and plain hyphens match each other unless `--exact`,
  and the replacement keeps the document's characters: `"net 30"` →
  `"net 45"` keeps its no-break space. Matches it leaves alone, like other
  capitalization, are reported as `nearMisses`. `replace-text` and
  `replaceText` still work, and JSON output run under `replace-text` still
  names it.
- **`--section` is a heading and everything under it.** `--section 8`
  includes 8.1 and 8.2. Numbers match whether typed or Word's automatic
  numbering. A title matches in full, or by text in only one heading; text in
  several headings is an error (`section_ambiguous`), and a section that
  doesn't exist is `section_not_found` instead of an empty result.
- **Clearer flag names:** `new --content` (was `--from`), `new --page-size`
  (was `--page`), `search --results-page` (was `--page`), and `--blocks` for
  block ids on `read` and `replace-all` (was `--ids`). The old names still
  work.
- **`changes` lists header, footer, and note changes as such** ("Header",
  "Footnote 1"), with their text.

### Fixed

- **Word-numbered headings.** Headings numbered by Word's heading styles, how
  most contracts number clauses, are headings again: `outline` lists them
  with their numbers ("8.1 Cap on liability") and `--section 8` finds them.
- **Comparing numbered documents.** Two copies of the same numbered document
  compare as unchanged, instead of every numbered clause deleted and
  reinserted.
- **Comparing against a file revise edited.** A one-word edit compares as a
  one-word change, not a whole paragraph replaced: editing a paragraph no
  longer adds fonts and sizes to it or its neighbors.
- **Tracked changes in headers and footers** are saved as Word revisions, and
  ones made in Word open as pending changes.
- **Markdown export** numbers nested list items per level (8.1 was written
  as "9."), and writes numbered headings as headings: `## 8.1 Cap on
  liability`.

## 3.0.1

### Fixed

- **Windows-1252 text on Node 20.** Text that isn't UTF-8, like a .txt file
  from a Windows editor piped to `convert`, and RTF files read € “ ” ‘ ’ – —
  and the other characters Windows-1252 stores in bytes 0x80–0x9F as
  invisible control characters. Node 22 and later were not affected.

## 3.0.0

The first release of `revise` as a command-line tool and TypeScript library
for reading, editing, and redlining Word documents.

Versions 2.x of this package were the Revise editor for React. The editor is
now [`@reviseio/editor`](https://www.npmjs.com/package/@reviseio/editor); 2.x
stays installable.

### Added

- **The `revise` CLI.** Read a document as HTML with block ids, search it,
  edit it with the same tools the Revise agent uses, and save the file in
  place, as tracked changes by default in .docx. Review with `changes`,
  `diff`, `accept`, and `reject`; `undo` and `restore` work across edits;
  `render` draws pages as images; `export`, `convert`, `compare`, and `new`
  write .docx, PDF, Markdown, HTML, and text. `convert` also works in a
  pipe: `-` reads stdin (the format is recognized from its bytes) or writes
  stdout. `--out new.docx` on an edit saves the result as a new file and
  leaves the original as it is. Every command has its own
  `--help`, and colored output on a terminal (not in pipes unless
  `FORCE_COLOR` is set; never with `--json`).
- **`--json` on every command**: one envelope (`schema`, `ok`, `command`,
  `meta`, `data`, `warnings`, `error`) with stable error codes, structured
  partial results, and exit codes that say whether anything was saved.
  Specified in [JSON output](https://revise.io/developer/docs/revise/json) and shipped as a JSON Schema,
  `revise/cli-output.schema.json`.
- **`ReviseDocument`**, the same operations as a library: open a file or
  bytes, run typed tools, review changes, export with a fidelity report,
  and snapshot and restore state.
- **`agentTools(doc, { provider })`**: the editing tools in the shapes the
  Anthropic and OpenAI SDKs expect, with a matching result formatter.
- **Collaboration rooms.** `seedYDoc(room, file)` seeds a sync server's
  Y.Doc on every connection (idempotent, repairs two peers that seeded at
  once, keeps the original Word file in the room), and
  `ReviseDocument.fromYDoc(room)` edits and exports a live room.
- **Word fidelity.** Untouched content in a .docx exports byte for byte;
  `xml` commands read and patch the raw package for what the tools don't
  cover (styles, numbering, settings).
- **An agent skill**: `revise skill install` writes a SKILL.md that teaches
  coding agents the CLI.

### Removed

- **The editor entry points of 2.x.** `revise/editor`, `revise/editor/full`,
  and `revise/server` now throw an error pointing to `@reviseio/editor`, and
  `revise/style.css` is an empty stylesheet that says the same.