# stetdoc: editing Word documents with tracked changes > The skill stetdoc gives an agent: how to read a .docx, edit it with tracked changes, comment, review a returned draft and act on a refusal. Source: https://stetdoc.clauseo.chat/docs/skill · stetdoc 0.9.1 stetdoc 0.9.1 turns a .docx into a **working copy** of plain text files, and turns your edits back into the same .docx with **real Word tracked changes**. Everything you do not touch stays byte-identical. Every change is a revision with an author and a date, so a reviewer sees exactly what you did. ## The loop 1. **Unpack once per document**, and keep the folder for the whole task: `stetdoc unpack contract.docx` writes `contract.stet/`. Never unpack the .docx you packed in the middle of a task: the refs and the base would start again. 2. **Read.** `stetdoc view contract.stet` shows the whole body if it fits in a page, otherwise an outline. Then narrow it: `--range p40..p60`, `--find "limitation of liability"`, `--clause 12.3` (repeat it for several clauses), `--revisions`, `--comments`. A long answer comes in pages (see "Reading a long document"). `stetdoc lookup contract.stet Losses` finds a defined term and its uses, and `stetdoc inspect contract.stet p42` shows a paragraph's formatting, tracked changes and comments. 3. **Edit.** Change text with `stetdoc replace` and comment with `stetdoc comment` (below). For anything else, change the readable files or send a batch of operations. 4. **Check, for hand edits only.** `stetdoc check contract.stet` shows the redline that pack will write from edited readable files, by author, and validates it. `replace`, `comment`, `edit` and `pack` validate what they write, and their receipt's `validated` line says so: do not run check after them, nor on a document you only read. 5. **Pack.** `stetdoc pack contract.stet` writes `contract.edited.docx`, or the file `-o` names, and brings the working copy up to date, so you can carry on editing. On the last pack of the task, add `--done` (with MCP, `done: true`): it removes the working copy once the .docx is written and validated, and keeps it when the pack fails. 6. **Finish.** Tell the user the path of the .docx you wrote. If you kept the working copy, because the user may want more edits, say where it is (the pack receipt names it). If the document holds tracked changes you did not make in this task, tell the user who made them and what they change. stetdoc takes the author from `--author`, then `STETDOC_AUTHOR`, then the name saved by `stetdoc init` (`stetdoc init --list` shows it). If the user asked for a particular name, pass it with `--author` on each edit, pack and compare. Ask the user only when stetdoc refuses for lack of an author and they have not said whose name to use. Never invent one. In a shared or hosted setup, always pass `--author`. `pack` overwrites an existing file only when it is the document you unpacked or one this working copy packed. Anything else is someone's newer version, and pack refuses (`stale_target`): unpack that file again and redo the edits, rather than reaching for `--force`. ## Reading a long document A view shows one page of about 3000 tokens (about 12 KB). Its `{position: ...}` line says where the page stops and how much is left, and a `-- more:` line ends it with the exact command for the next page. Run that command, and repeat until no `-- more:` line follows: only then have you seen the whole range. Never use `view --all` (the same as `--budget 0`) on a long document. It prints everything at once, which for a long contract is tens of thousands of tokens, and a tool output that large may be kept in a file you are not allowed to read. Page with `-- more:`, or narrow with `--find` or `--range`. A body too long for one page shows its outline instead, with an `outline_shown` warning that names the range of the whole body (`--range p1..p251`). The outline gives each heading's range, so view the part you need. `--find TEXT` prints one line per matching paragraph: its ref, its clause (`{§11.1}`) and about 100 characters of its exact text around the match, grouped under a `{in pN "Clause ..."}` line for each top-level clause. A heading that matches adds a `{tip: ...}` that names the clause to view or look up whole. Repeat `--find` to look for several texts at once: each line says which matched. `--context N` (1 or more) shows the matching blocks whole. It pages like a range, and with `--range a..b` it searches only that range. ## What is document text and what is markup Use stetdoc to see inside a document. Never unzip a .docx or read its XML, not even to check something. A real tracked change is a marker in braces followed by its id, such as `{++new text++}{#38 A}` or `{--old text--}{#39 A}`, and `--revisions` lists it by that id. Text such as `[DELETED: ...]` without braces and an id is literal document text that someone typed, not a revision. When in doubt, `stetdoc inspect contract.stet p95` lists the block's tracked changes and comments, or says it has none. ## Reading and editing a .docx without a working copy To read a .docx, view it directly: `stetdoc view contract.docx`, `--revisions`, `--find` and the rest work on a .docx as on a working copy. Unpack only to edit the files. `stetdoc edit contract.docx`, `replace` and `comment` edit a .docx with no working copy. Without `-o` or `--in-place` they write `contract.edited.docx` beside the input and leave the input unchanged. When that file exists they write `contract.edited-2.docx`, then `-3` and so on: they never overwrite. The receipt names the file. Make the next edit on the file you wrote, with `--in-place`: another edit of `contract.docx` starts a new file without your earlier edits. `-o OUT` names the file instead. Keep it next to the input, in the user's folder (for `/work/contract.docx`, `-o /work/contract.redline.docx`), never in a temporary folder. `--in-place` writes the result back to the file it read. Use it only when the user asks you to update that file, or the file is one this task already wrote. It writes atomically and refuses with `stale_target` if someone wrote the file meanwhile (view again and rewrite the batch). Never write to a temporary file and move it over the original. With `--dry-run`, `-o` and `--in-place` are accepted and ignored. `--in-place` is refused on a working copy, which an edit always updates itself. A written .docx numbers its blocks again when it is opened, and the receipt says what to do next. Its `base` is the written file's, so the next batch on that file can start from it. When the edit added or removed blocks, the receipt has no base and a `next: stetdoc view ...` line instead: view the file, then write the next batch from that view. ## Changing text and commenting in one step `replace` is the default way to change text, and `comment` the way to comment. Each finds its text and edits in one call, on a .docx or a working copy, with no ref or base to copy: ``` stetdoc replace contract.docx 'net 30' 'net 45' 'England and Wales' 'Singapore' stetdoc comment contract.edited.docx 'Liability Cap' 'Is this cap mutual?' --in-place ``` The first writes `contract.edited.docx`, and the second adds the comment to that file. - **Pairs.** `replace FILE OLD NEW [OLD NEW ...]` applies every pair as one edit, all or nothing. An empty NEW (`''`) is a tracked deletion. Pairs whose texts overlap are refused. Put `--` before the pairs when a text starts with `-`. - **Matching.** OLD (and a comment's ANCHOR) is matched in the text as the final view reads it, across runs and formatting, case-sensitive, with curly and straight quotes the same. It must be there exactly once. If it is not there (`not_found`) or is there more than once (`ambiguous_match`), nothing is written and the refusal lists each place (ref, clause or `(under "HEADING")`, and the text around it): use a longer OLD, or narrow the search with `--clause 11.1` or `--range p40..p60`. `--ignore-case` matches whatever the case. A `not_found` refusal lists the places that match in another case: rerun with `--ignore-case` if those are the ones you meant. - **Finding OLD first.** `stetdoc view contract.docx --find 'net 30' --find 'governing law'` prints one line per matching paragraph, with its ref, its clause and the text around the match, which you can copy as OLD. A hit in a table cell ends with the row's other cells, such as `{row: p36 "Greater than 4.25 to 1.00", p38 "2.25%"}`, so you can edit them by ref. - **Every occurrence.** `--all` replaces every occurrence of each OLD and says how many. `--expect N` does the same only when there are exactly N, and otherwise refuses with `count_mismatch` (exit 3). Use it when the user said how many. `comment --all` and `comment --expect N` put one comment on each place. - **Where it writes.** On a .docx, the default is `NAME.edited.docx` beside it, `-o OUT` writes the file you name, and `--in-place` writes the file back (see above). A working copy is always written in place, and `-o` or `--in-place` is refused there. `--dry-run` shows the receipt and writes nothing. `--author NAME` names the author, as for every edit. - **Quoting.** Put each text in single quotes. For a text with an apostrophe, use double quotes when it has no `$`, backtick or backslash, or a batch. - **Several comments.** `stetdoc comment FILE ANCHOR TEXT ANCHOR TEXT ...` adds them in one edit, all or none. - With MCP, edit the .docx itself, one call per document with every change in it: the `replace` tool takes `pairs: [{old, new}]`, the `comment` tool `anchor` and `text`, or `comments: [{anchor, text}]` for several. No `unpack`, `pack` or `check` is needed, and every write is validated, as its receipt says. A receipt is cut to about 2 KB; `detail: true` returns all of it. ## Manual markup, without tracked changes Some readers want a manual redline: old text struck through and new text underlined, with no Track Changes. Changes are tracked unless manual markup is asked for. Use `--manual` when the user asks for manual markup or no Track Changes. Also use it when a document or note the user points you to asks for that, such as an email from the client, a client note or a playbook. Read those before your first edit. The user chose to point you to them, so their request is the user's request: follow it, and do not reply that it was not the user's. Use tracked changes otherwise. ``` stetdoc replace contract.docx 'thirty days' 'sixty days' --manual ``` `--manual` on `replace` or `edit` keeps the old text, struck through, and adds the new text underlined after it, as plain formatting. An empty NEW leaves struck text only, and an insertion is underlined text only. `--manual-color` also makes deleted text red and new text blue. The receipt says `struck "...", underlined "..."` for each change, and `view` shows old and new run together without the formatting, with no tracked change. `stetdoc inspect FILE p4` shows the strike and the underline on the paragraph. Splitting, merging and table rows are refused under `--manual`: make them in a separate tracked edit. Text inside another author's pending tracked change is refused too. When you report, tell the user the file is a manual markup, not Track Changes, so it cannot be accepted or rejected in Word. Use a batch (Way 2) to insert or delete paragraphs, accept or reject revisions, reply to or resolve comments, change formatting, or for text that is long or holds many quotes. ## Receipts and problems already in the document A receipt lists the problems your change added, if any. Problems that were already in the input are summed up in one line (`no new problem, ... 66 problems were already in the input`). They are not yours to fix, so mention them only if the user asks. `stetdoc check FILE --all` (with MCP, `all: true`) lists them. One kind is repaired for you, because Word refuses to open a file that has it: a prefix that `mc:Ignorable` names and nothing declares. The receipt says so in a `repaired` warning, such as `declared w14, wp14 in word/document.xml so Word can open the file`. Tell the user that the input did not open in Word and the output does. When the document holds tracked changes you did not make, receipts and views say so in a line such as `4 tracked changes by others (Jane Doe 2, Eric White 2) you did not make: #0 insert p1 "shall pay ", ...`, followed by `Tell the user about them.` Do it: name who made them and what they change. `stetdoc view FILE --revisions --context 1` shows each of them in its paragraph. Without a saved author, a view says the changes are `already in the document`: tell the user about them if you did not make them. ## Way 1: edit the readable files `document.md` holds the body, `notes.md` the footnotes and endnotes, `headers.md` the headers and footers. Each paragraph is one line that starts with its **ref** (`p42`); tables show `t` and `r` lines. - Change the text after a ref with your own edit tool. stetdoc diffs it word by word into insertions and deletions. - Delete a paragraph by deleting its whole line. Add paragraphs as new lines **without** a ref after the line they follow. - Keep refs, their order and every marker in braces as they are. Clause numbers (`{§"12.3"}`), field results and other people's tracked changes are read-only, and a change to them is refused with the file and line. - `comments.md` is read-only: comment with operations. Never touch `.stet/`. - `view` shows the last pack, not your unpacked edits. Run `check` to see what your edits will do. - An operation batch waits until the file edits are packed (`pending_edits`), so pack between the two ways. ## Way 2: a batch of operations Send operations on stdin with a quoted heredoc, so no text needs escaping: ``` stetdoc edit contract.stet <<'EOF' base: 5737b772923cf8d3:0:5737b772923cf8d3 --- @replace ref: p4 find: thirty days with: sixty days --- @insert ref: p4 place: after paragraphs: <