bun-docx 0.19.1 → 0.20.0

package/README.md

@@ -8,6 +8,27 @@
 - Agents address text by **stable locators** with character offsets (`p3:5-20`); humans see normal Word formatting on disk.
 - Custom styles, theme colors, embedded objects — all of it survives. The CLI mutates XML in place rather than re-emitting from a lossy model.
 
+## Why docx-cli?
+
+The default way agents edit Word docs is to unzip the `.docx` and hand-write the OOXML inside. That takes a strong model to get right, burns tokens, and routinely produces a file Word won't open. `docx-cli` hands the agent plain commands plus an annotated-Markdown read view, so it never has to reason about the XML.
+
+We measured it — a controlled A/B bake-off: **six real document tasks** (fill an NDA, fill an invoice, restyle a résumé, redline a contract, finalize a contract, author a journal), the same starting files, and one independent judge grading every result from the **Word-rendered pages**. Three runs per arm at each of two model tiers:
+
+|                           | Haiku (weak, cheap) |                       | Sonnet (strong) |                       |
+| :------------------------ | ------------------: | --------------------: | --------------: | --------------------: |
+|                           |        **docx-cli** |         default skill |    **docx-cli** |         default skill |
+| Tasks solved (of 6)       |       **4.3** (4–5) |             0.7 (0–1) |   **6.0** (6–6) |             4.0 (4–4) |
+| Rendered correctly (of 6) |                 5.7 |                   3.7 |             6.0 |                   4.7 |
+| Outright-broken documents |               **0** |      ~1/run (up to 2) |           **0** |                     0 |
+| Input tokens              |            **2.4M** |           6.1M (2.6×) |        **1.6M** |           3.6M (2.2×) |
+| Wall-clock                |           **924 s** | 1,882 s (2.0× slower) |     **1,175 s** | 2,029 s (1.7× slower) |
+
+- **The correctness gap is widest on the cheap Haiku tier (~6×)**, and a frontier model never closes it — the default skill caps at 4/6, losing the contract redline and the résumé every Sonnet run.
+- **The cost and speed penalties are model-independent** — ~2.2–2.6× more tokens and ~1.7–2× slower at *both* tiers, with token/time ranges that never overlap.
+- **Word couldn't reliably open the default skill's work** — it failed to open 5 of 36 of its outputs; all 36 of docx-cli's opened on the first try.
+
+Full methodology, per-task rubric, and side-by-side renders: **[the bake-off writeup](https://kklimuk.github.io/docx-cli/)**.
+
 ## Install
 
 **npm** — the simplest path (requires Bun >= 1.3):
@@ -366,7 +387,7 @@ The CLI is built for non-interactive agents. **Exit code is the success signal**
 | Command class                                                                                                                                                                                                                                                              | Default stdout on success                                                                                                                                                                   | `--verbose`                                                               |
 | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
 | **Mutator that mints a new handle** — `comments add`→`cN`, `comments reply`→`cN`, `footnotes/endnotes add`→`fnN`/`enN`, `hyperlinks add`→`linkN`, `insert`→the new `pN`                                                                                                    | the bare locator(s), **one per line** (a multi-block `--markdown` insert prints several)                                                                                                    | full `{ok:true,…}` ack                                                    |
-| **Mutator with no new handle** — `edit`, `delete`, `replace`, `create`, `comments resolve/delete`, `images replace/delete`, `hyperlinks replace/delete`, `footnotes/endnotes edit/delete`, `headers/footers set/clear`, `tables *`, `track-changes accept/reject` & toggle | **one-line confirmation** — `<operation> <target>` (e.g. `edit t1:r0c1:p0`, `edit 7 changes`, `replace 0 occurrences replaced`) (exit `0`)                                                  | full `{ok:true,…}` ack                                                    |
+| **Mutator with no new handle** — `edit`, `delete`, `replace`, `create`, `comments resolve/delete`, `images replace/delete`, `hyperlinks replace/delete`, `footnotes/endnotes edit/delete`, `headers/footers set/clear`, `tables *`, `track-changes accept/reject` & toggle | **one-line confirmation** — `<operation> <target>` (e.g. `edit t1:r0c1:p0`, `edit 7 changes`, `replace 3 occurrences replaced`) (exit `0`)                                                  | full `{ok:true,…}` ack                                                    |
 | `find`                                                                                                                                                                                                                                                                     | matched span locators, one per line (no matches → nothing, exit `0`)                                                                                                                        | `--json` → `{ totalMatches, query, view, matches:[…], normalizedQuery? }` |
 | `wc`                                                                                                                                                                                                                                                                       | the bare count (whole-doc adds a tab-separated `sections` column, like `wc`)                                                                                                                | `--json` → `{ words, scope, view, sections? }`                            |
 | `outline`                                                                                                                                                                                                                                                                  | indented `LOCATOR⇥TEXT` tree (two spaces per level)                                                                                                                                         | `--json` → nested `[{ id, locator, level, style, text, children }]`       |

package/dist/index.js

@@ -4435,6 +4435,20 @@ class XmlNode2 {
     }
     return out;
   }
+  collectTextWithBreaks() {
+    if (this.isText)
+      return this.text ?? "";
+    if (this.tag === "w:br" || this.tag === "w:cr")
+      return `
+`;
+    if (this.tag === "w:tab")
+      return "\t";
+    let out = "";
+    for (const child of this.children) {
+      out += child.collectTextWithBreaks();
+    }
+    return out;
+  }
   clone() {
     const cloned = new XmlNode2(this.tag, { ...this.attributes });
     if (this.text !== undefined)
@@ -5290,6 +5304,11 @@ function RunElement({ run }) {
   }
   return null;
 }
+function textToRunElements(text) {
+  return textToRuns(text, {}).map((run) => /* @__PURE__ */ jsxDEV(RunElement, {
+    run
+  }, undefined, false, undefined, this)).filter((node) => node !== null);
+}
 function applyParagraphOptionsInPlace(rebuilt, options) {
   if (!options.style && !options.alignment && !options.tabs && !options.spacing && !options.indent)
     return;
@@ -17744,14 +17763,7 @@ function noteFirstParagraphRuns({
     return runs;
   if (text2 === undefined)
     return [];
-  return [
-    /* @__PURE__ */ jsxDEV(w.r, {
-      children: /* @__PURE__ */ jsxDEV(w.t, {
-        "xml:space": "preserve",
-        children: ` ${text2}`
-      }, undefined, false, undefined, this)
-    }, undefined, false, undefined, this)
-  ];
+  return textToRunElements(` ${text2}`);
 }
 function TrackedNoteBody({
   config,
@@ -17761,6 +17773,19 @@ function TrackedNoteBody({
 }) {
   const Note = config.kind === "footnote" ? w.footnote : w.endnote;
   const BodyRef = config.kind === "footnote" ? w.footnoteRef : w.endnoteRef;
+  const insRuns = [
+    /* @__PURE__ */ jsxDEV(w.r, {
+      children: [
+        /* @__PURE__ */ jsxDEV(w.rPr, {
+          children: /* @__PURE__ */ jsxDEV(w.rStyle, {
+            "w-val": config.referenceStyle
+          }, undefined, false, undefined, this)
+        }, undefined, false, undefined, this),
+        /* @__PURE__ */ jsxDEV(BodyRef, {}, undefined, false, undefined, this)
+      ]
+    }, undefined, true, undefined, this),
+    ...textToRunElements(` ${text2}`)
+  ];
   return /* @__PURE__ */ jsxDEV(Note, {
     "w-id": id,
     children: /* @__PURE__ */ jsxDEV(w.p, {
@@ -17772,25 +17797,8 @@ function TrackedNoteBody({
         }, undefined, false, undefined, this),
         /* @__PURE__ */ jsxDEV(Ins, {
           meta,
-          children: [
-            /* @__PURE__ */ jsxDEV(w.r, {
-              children: [
-                /* @__PURE__ */ jsxDEV(w.rPr, {
-                  children: /* @__PURE__ */ jsxDEV(w.rStyle, {
-                    "w-val": config.referenceStyle
-                  }, undefined, false, undefined, this)
-                }, undefined, false, undefined, this),
-                /* @__PURE__ */ jsxDEV(BodyRef, {}, undefined, false, undefined, this)
-              ]
-            }, undefined, true, undefined, this),
-            /* @__PURE__ */ jsxDEV(w.r, {
-              children: /* @__PURE__ */ jsxDEV(w.t, {
-                "xml:space": "preserve",
-                children: ` ${text2}`
-              }, undefined, false, undefined, this)
-            }, undefined, false, undefined, this)
-          ]
-        }, undefined, true, undefined, this)
+          children: insRuns
+        }, undefined, false, undefined, this)
       ]
     }, undefined, true, undefined, this)
   }, undefined, false, undefined, this);
@@ -17831,15 +17839,9 @@ function wrapNoteBodyAsEdited(noteBody, newText, insMeta, delMeta) {
       continue;
     }
     if (!inserted) {
-      const newRun = /* @__PURE__ */ jsxDEV(w.r, {
-        children: /* @__PURE__ */ jsxDEV(w.t, {
-          "xml:space": "preserve",
-          children: newText
-        }, undefined, false, undefined, this)
-      }, undefined, false, undefined, this);
       result.push(/* @__PURE__ */ jsxDEV(Ins, {
         meta: insMeta,
-        children: newRun
+        children: textToRunElements(newText)
       }, undefined, false, undefined, this));
       inserted = true;
     }
@@ -17849,15 +17851,9 @@ function wrapNoteBodyAsEdited(noteBody, newText, insMeta, delMeta) {
     }, undefined, false, undefined, this));
   }
   if (!inserted) {
-    const newRun = /* @__PURE__ */ jsxDEV(w.r, {
-      children: /* @__PURE__ */ jsxDEV(w.t, {
-        "xml:space": "preserve",
-        children: newText
-      }, undefined, false, undefined, this)
-    }, undefined, false, undefined, this);
     result.push(/* @__PURE__ */ jsxDEV(Ins, {
       meta: insMeta,
-      children: newRun
+      children: textToRunElements(newText)
     }, undefined, false, undefined, this));
   }
   paragraph.children = result;
@@ -17885,6 +17881,7 @@ function isBareWhitespaceRun(run) {
   return saw;
 }
 var init_emit3 = __esm(() => {
+  init_blocks();
   init_jsx();
   init_track_changes();
   init_emit2();
@@ -21138,6 +21135,9 @@ function nodeText(node) {
         out += child2.collectText();
       else if (child2.tag === "w:tab")
         out += "\t";
+      else if (child2.tag === "w:br" || child2.tag === "w:cr")
+        out += `
+`;
     }
     return out;
   }
@@ -23700,7 +23700,7 @@ class CommentsView {
       const author = child2.getAttribute("w:author") ?? "";
       const date = child2.getAttribute("w:date") ?? "";
       const initials = child2.getAttribute("w:initials");
-      const text2 = child2.collectText();
+      const text2 = child2.collectTextWithBreaks();
       const anchor = anchors.get(commentId) ?? {
         startBlockId: "",
         startOffset: 0,
@@ -24218,7 +24218,7 @@ class NotesView {
       const numericId = child2.getAttribute("w:id");
       if (numericId == null)
         continue;
-      const text2 = child2.collectText().replace(/\s+/g, " ").trim();
+      const text2 = child2.collectTextWithBreaks().trim();
       out.push({ id: `${config.idPrefix}${numericId}`, text: text2 });
     }
     return out;
@@ -35447,12 +35447,7 @@ function CommentBody({
     children: /* @__PURE__ */ jsxDEV(w.p, {
       "w14:paraId": options.paraId,
       "w14:textId": "00000000",
-      children: /* @__PURE__ */ jsxDEV(w.r, {
-        children: /* @__PURE__ */ jsxDEV(w.t, {
-          "xml:space": "preserve",
-          children: options.text
-        }, undefined, false, undefined, this)
-      }, undefined, false, undefined, this)
+      children: textToRunElements(options.text)
     }, undefined, false, undefined, this)
   }, undefined, false, undefined, this);
 }
@@ -35519,6 +35514,7 @@ function containsCommentReference(run, numericId) {
 var SpanOutOfRangeError;
 var init_markers = __esm(() => {
   init_comments();
+  init_blocks();
   init_jsx();
   init_parser();
   init_jsx_dev_runtime();
@@ -74332,7 +74328,7 @@ function buildContentParagraph(spec, contentWidth) {
             }, undefined, false, undefined, this)
           }, undefined, false, undefined, this)
         }, undefined, false, undefined, this),
-        textRun(spec.text),
+        textToRunElements(spec.text),
         /* @__PURE__ */ jsxDEV(w.r, {
           children: /* @__PURE__ */ jsxDEV(w.tab, {}, undefined, false, undefined, this)
         }, undefined, false, undefined, this),
@@ -74357,7 +74353,7 @@ function buildContentParagraph(spec, contentWidth) {
       alignment ? /* @__PURE__ */ jsxDEV(w.pPr, {
         children: alignment
       }, undefined, false, undefined, this) : null,
-      hasText ? textRun(spec.text) : null
+      hasText ? textToRunElements(spec.text) : null
     ]
   }, undefined, true, undefined, this);
 }
@@ -74368,22 +74364,14 @@ function alignChild(align) {
     "w-val": align
   }, undefined, false, undefined, this);
 }
-function textRun(text6) {
-  return /* @__PURE__ */ jsxDEV(w.r, {
-    children: /* @__PURE__ */ jsxDEV(w.t, {
-      "xml:space": "preserve",
-      children: text6
-    }, undefined, false, undefined, this)
-  }, undefined, false, undefined, this);
-}
 function fieldRuns(field) {
   switch (field.type) {
     case "page":
       if (field.ofPages) {
         return [
-          textRun("Page "),
+          ...textToRunElements("Page "),
           fieldSimple(" PAGE ", "1"),
-          textRun(" of "),
+          ...textToRunElements(" of "),
           fieldSimple(" NUMPAGES ", "1")
         ];
       }
@@ -74445,6 +74433,7 @@ function relationshipTarget(partName) {
 }
 var NS_W3 = "http://schemas.openxmlformats.org/wordprocessingml/2006/main", NS_R2 = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
 var init_marginals2 = __esm(() => {
+  init_blocks();
   init_jsx();
   init_sections();
   init_track_changes();
@@ -82797,6 +82786,12 @@ async function rejectShellMangledValue(text6, help, label = "this value") {
   return await fail("USAGE", `${label} contains "${fragment}" \u2014 a number with no integer part, the signature of a "$" amount gutted by the shell (bash turns double-quoted "$300.00" into ".00" and "$10,000" into ",000"). docx would write the corrupted value verbatim.`, `Wrap any "$"-bearing value in SINGLE quotes ('$300.00') so bash leaves it alone, or supply it via --batch FILE (JSONL never touches the shell). If you really mean "${fragment}", write its integer part (0${fragment}) or use --batch. Help:
 ${help}`);
 }
+function decodeInlineEscapes(value) {
+  if (value === undefined)
+    return;
+  return value.replace(/\\r\\n|\\[nrt]/g, (match) => match === "\\t" ? "\t" : `
+`);
+}
 function parseTaskFlag(value) {
   const normalized = value.toLowerCase();
   if (normalized === "checked" || normalized === "true" || normalized === "1")
@@ -83206,7 +83201,7 @@ async function run(args) {
   const atInput = parsed.values.at;
   const anchorInput = parsed.values.anchor;
   const batchInput = parsed.values.batch;
-  const text6 = parsed.values.text;
+  const text6 = decodeInlineEscapes(parsed.values.text);
   const occurrenceRaw = parsed.values.occurrence;
   const defaultAuthor = resolveAuthor(parsed.values.author);
   const outputPath = parsed.values.output;
@@ -83690,7 +83685,7 @@ async function run4(args) {
   if (!path2)
     return fail("USAGE", "Missing FILE argument", HELP4);
   const parentInput = parsed.values.at;
-  const text6 = parsed.values.text;
+  const text6 = decodeInlineEscapes(parsed.values.text);
   if (!parentInput)
     return fail("USAGE", "Missing --at cN", HELP4);
   if (!text6)
@@ -83764,6 +83759,7 @@ Examples:
 `;
 var init_reply = __esm(() => {
   init_core2();
+  init_parse_helpers();
   init_respond();
 });
 
@@ -84077,12 +84073,7 @@ function DocumentBody({ text: text6 }) {
     children: /* @__PURE__ */ jsxDEV(w.body, {
       children: [
         text6 !== undefined ? /* @__PURE__ */ jsxDEV(w.p, {
-          children: /* @__PURE__ */ jsxDEV(w.r, {
-            children: /* @__PURE__ */ jsxDEV(w.t, {
-              "xml:space": "preserve",
-              children: text6
-            }, undefined, false, undefined, this)
-          }, undefined, false, undefined, this)
+          children: textToRunElements(text6)
         }, undefined, false, undefined, this) : /* @__PURE__ */ jsxDEV(w.p, {}, undefined, false, undefined, this),
         /* @__PURE__ */ jsxDEV(DefaultSectionProperties, {}, undefined, false, undefined, this)
       ]
@@ -84180,6 +84171,7 @@ function serializeWithDeclaration(root2) {
 }
 var DOC_NAMESPACES, CONTENT_TYPES, ROOT_RELS, DOCUMENT_RELS;
 var init_template = __esm(() => {
+  init_blocks();
   init_jsx();
   init_parser();
   init_canonical_parts();
@@ -84260,7 +84252,7 @@ async function run7(args) {
   if (!path2) {
     return fail("USAGE", "Missing FILE argument", HELP7);
   }
-  const text6 = parsed.values.text;
+  const text6 = decodeInlineEscapes(parsed.values.text);
   const fromPath = parsed.values.from;
   const textFilePath = parsed.values["text-file"];
   const contentSources = [text6, fromPath, textFilePath].filter((value) => value !== undefined);
@@ -85841,7 +85833,7 @@ async function validateParagraphEdit(values2, paragraphOptions) {
       return { kind: "clear", tags };
     }
   }
-  const text6 = values2.text;
+  const text6 = decodeInlineEscapes(values2.text);
   const runsJson = values2.runs;
   const codeInline = values2.code;
   const codeFile = values2["code-file"];
@@ -85895,7 +85887,7 @@ async function validateParagraphEdit(values2, paragraphOptions) {
     }
     return { kind: "task", checked };
   }
-  const markdownInline = values2.markdown;
+  const markdownInline = decodeInlineEscapes(values2.markdown);
   const markdownFile = values2["markdown-file"];
   const contentFlags = [
     text6 !== undefined,
@@ -86442,9 +86434,9 @@ async function runAddNote(args, kind) {
   if (anchorCount > 1) {
     return fail("USAGE", "--at and --anchor are mutually exclusive", help);
   }
-  const text6 = parsed.values.text;
+  const text6 = decodeInlineEscapes(parsed.values.text);
   const runsJson = parsed.values.runs;
-  const markdown2 = parsed.values.markdown;
+  const markdown2 = decodeInlineEscapes(parsed.values.markdown);
   const markdownFile = parsed.values["markdown-file"];
   const bodyCount = (text6 !== undefined ? 1 : 0) + (runsJson !== undefined ? 1 : 0) + (markdown2 !== undefined ? 1 : 0) + (markdownFile !== undefined ? 1 : 0);
   if (bodyCount === 0) {
@@ -86868,9 +86860,9 @@ async function runEditNote(args, kind) {
   const config = noteConfig(kind);
   if (!idInput)
     return fail("USAGE", `Missing --at ${config.idPrefix}N`, help);
-  const text6 = parsed.values.text;
+  const text6 = decodeInlineEscapes(parsed.values.text);
   const runsJson = parsed.values.runs;
-  const markdown2 = parsed.values.markdown;
+  const markdown2 = decodeInlineEscapes(parsed.values.markdown);
   const markdownFile = parsed.values["markdown-file"];
   const bodyCount = (text6 !== undefined ? 1 : 0) + (runsJson !== undefined ? 1 : 0) + (markdown2 !== undefined ? 1 : 0) + (markdownFile !== undefined ? 1 : 0);
   if (bodyCount === 0) {
@@ -87645,7 +87637,7 @@ async function runSetMarginal(args, kind) {
   if (align !== undefined && !isAlign(align)) {
     return fail("USAGE", `Invalid --align: ${align}`, "Valid: left, center, right.");
   }
-  const text6 = parsed.values.text;
+  const text6 = decodeInlineEscapes(parsed.values.text);
   if (text6 === undefined && field === undefined) {
     return fail("USAGE", `Nothing to set \u2014 pass --text and/or a field (--page-number/--date/--style-ref/--field).`, helpFor7(kind));
   }
@@ -87740,6 +87732,7 @@ var OPTION_SPEC4, SAVE_FLAGS_HELP = `Output:
   -h, --help         Show this help`;
 var init_set = __esm(() => {
   init_core2();
+  init_parse_helpers();
   init_respond();
   init_shared();
   OPTION_SPEC4 = {
@@ -88879,10 +88872,10 @@ async function buildSingleShotOptions(filePath, values2) {
   if (typeof spec === "number")
     return spec;
   if (spec.kind === "text") {
-    const rejected = await rejectMarkdownInText(values2.text, HELP20);
+    const rejected = await rejectMarkdownInText(spec.text, HELP20);
     if (typeof rejected === "number")
       return rejected;
-    const mangled = await rejectShellMangledValue(values2.text, HELP20, "--text");
+    const mangled = await rejectShellMangledValue(spec.text, HELP20, "--text");
     if (typeof mangled === "number")
       return mangled;
   }
@@ -89022,7 +89015,7 @@ async function chooseContentSpec(values2) {
 }
 async function resolveMarkdownSpec(values2, flag) {
   if (flag === "markdown") {
-    const source2 = values2.markdown;
+    const source2 = decodeInlineEscapes(values2.markdown);
     return { kind: "markdown", source: source2 };
   }
   const path2 = values2["markdown-file"];
@@ -89067,7 +89060,7 @@ async function parseImageFlags(values2) {
   const alt = values2.alt;
   if (alt !== undefined)
     out.alt = alt;
-  const caption = values2.caption;
+  const caption = decodeInlineEscapes(values2.caption);
   if (caption !== undefined)
     out.caption = caption;
   const widthRaw = values2.width;
@@ -89092,7 +89085,7 @@ function buildTextSpec(values2) {
   const url = values2.url;
   return {
     kind: "text",
-    text: values2.text,
+    text: decodeInlineEscapes(values2.text),
     format: {
       color: values2.color,
       bold: values2.bold,
@@ -91608,7 +91601,7 @@ function formatNote(type, pairs, bareTokens = []) {
   return `<!-- ${parts.join(" ")} -->`;
 }
 function htmlAttr(key, value) {
-  const escaped = value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  const escaped = value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/\n/g, "&#10;").replace(/\r/g, "&#13;").replace(/\t/g, "&#9;");
   return `${key}="${escaped}"`;
 }
 function twipsToInches(twips) {
@@ -93257,6 +93250,13 @@ async function runReplaceBatch(filePath, batchSource, values2) {
     return EXIT2.OK;
   }
   await document4.save(outputPath);
+  const noops = results.filter((entry) => entry.replaced === 0);
+  if (noops.length > 0) {
+    const list3 = noops.map((entry) => JSON.stringify(entry.pattern)).join(", ");
+    const applied = results.length - noops.length;
+    const savedNote = applied === 0 ? "No entry matched, so the document is unchanged." : `The other ${applied} ${applied === 1 ? "entry was" : "entries were"} applied and SAVED \u2014 this nonzero exit means "some entries missed," not "nothing changed."`;
+    return await fail("MATCH_NOT_FOUND", `${noops.length} of ${results.length} replace ${results.length === 1 ? "entry" : "entries"} matched nothing (0 occurrences): ${list3}. ${savedNote}`, `Those patterns weren't found as LITERAL document text \u2014 check for read-view markup (\`<mark>\`/\`<u>\`) or a locator in the pattern. \`docx find\` locates the real text; --ignore-case/--regex/--at scope the search.`);
+  }
   await respondAck({
     ok: true,
     operation: "replace",
@@ -93459,22 +93459,8 @@ async function run40(args) {
     return EXIT2.OK;
   }
   if (selected.length === 0) {
-    await respondAck({
-      ok: true,
-      operation: "replace",
-      path: path2,
-      pattern,
-      replacement,
-      regex: useRegex,
-      ignoreCase,
-      view: findView,
-      ...atScope ? { at: atScope } : {},
-      totalMatches: 0,
-      replaced: 0,
-      matches: [],
-      ...normalizationFields
-    });
-    return EXIT2.OK;
+    const scopeNote = atScope ? ` within ${atScope}` : "";
+    return await fail("MATCH_NOT_FOUND", `Pattern not found${scopeNote}: ${JSON.stringify(pattern)} \u2014 0 occurrences, nothing changed.`, `Match LITERAL document text, not read-view markup (\`<mark>\`/\`<u>\`/\`**\`\u2026) or a locator. Run \`docx find ${JSON.stringify(pattern)} ${path2}\` to see if/where it occurs; add --ignore-case, --regex, --at <locator> to scope, or --current/--baseline to search tracked-change text.`);
   }
   const reversed = [...selected].sort((leftMatch, rightMatch) => {
     if (leftMatch.blockId !== rightMatch.blockId) {
@@ -93580,6 +93566,10 @@ Output:
   addressable handle (matched-span locators shift as text changes; re-read or
   use --dry-run to see them). --verbose / --dry-run print
   {ok:true, operation, totalMatches, replaced, matches:[{locator,\u2026}], \u2026}.
+  A PATTERN that matches NOTHING is an error, not a silent success \u2014 0 occurrences
+  exits nonzero (MATCH_NOT_FOUND), so a no-op replace can't read as "done." Unsure it
+  matches? Probe with \`docx find PATTERN FILE\` or --dry-run and READ the reported count
+  \u2014 both exit 0 whether or not it matches; only the real replace exits nonzero on 0.
   Errors print {code, error, hint?} with a nonzero exit.
 
 Examples:
@@ -98024,7 +98014,7 @@ Examples:
 // package.json
 var package_default = {
   name: "bun-docx",
-  version: "0.19.1",
+  version: "0.20.0",
   description: "Read, edit, redline, and comment on Microsoft Word .docx files from the command line \u2014 built for AI agents.",
   keywords: [
     "docx",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bun-docx",
-	"version": "0.19.1",
+	"version": "0.20.0",
 	"description": "Read, edit, redline, and comment on Microsoft Word .docx files from the command line — built for AI agents.",
 	"keywords": [
 		"docx",