@ansonlai/docx-redline-js 0.7.2 → 0.8.0

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -1,78 +1,81 @@
-# Agent Knowledge Base
-
-> Detailed reference for @ansonlai/docx-redline-js. All code and command paths
-> are relative to the repository root. Start with `../AGENTS.md` for repository
-> work or `AGENT_FAST_START.md` for ordinary document edits; open this file only
-> when the quick guide points here or the task needs deeper behavior.
-
-## Start Here: Repository Layout
-
-This is one JavaScript package with three supported public surfaces. Choose the
-surface before following imports:
-
-| Use case | Public entry point | Primary implementation |
-|---|---|---|
-| Paragraph, range, list, table, comment, and OOXML transforms in any DOM-capable runtime | `index.js` (`@ansonlai/docx-redline-js`) | `engine/`, `pipeline/`, `core/`, and focused `services/` |
-| Operations against complete `word/document.xml` strings | `services/standalone-operation-runner.js` (`@ansonlai/docx-redline-js/standalone-runner`) | `services/document-operation-*.js` and `services/batch-operation-orchestrator.js` |
-| Complete `.docx` buffers and the CLI in Node.js | `node/index.js` (`@ansonlai/docx-redline-js/node`) and `bin/docx-redline.js` | `node/docx-document.js`, `node/zip-archive.js`, and package-plumbing services |
-
-The source tree is layered as follows:
-
-```text
-index.js                 root, host-independent public exports
-adapters/                injected XML, configuration, and logging adapters
-core/                    shared OOXML primitives, text views, targeting, validation
-pipeline/                ingestion, diffing, markdown, lists, and serialization stages
-engine/                  paragraph/range reconciliation and surgical/reconstruction modes
-orchestration/           route planning and structural list operation conversion
-services/                document operations, comments, receipts, package artifacts
-node/                    Node-only ZIP and whole-DOCX facade; keep out of root imports
-bin/                     CLI launcher; behavior belongs in node/ or services/
-tests/*.mjs              directly runnable suites discovered by scripts/run-tests.mjs
-tests/helpers/           shared test utilities; not standalone suites
-tests/fixtures/          checked-in synthetic/golden inputs and expected outputs
-scripts/                 build, fixture generation, benchmarks, and Word automation
-docs/                    schemas, testing guidance, plans, and generated reports
-dist/                    generated bundle; do not edit by hand
-```
-
-`AGENTS.md` is the committed repository-wide agent guide. `.agent/` is ignored
-local-only agent configuration and must not be treated as package source or as
-instructions that will exist in another clone or in CI.
-
-### Route Changes Without Exploring Everything
-
-1. Identify the public surface in the table above.
-2. Read its entry point, then follow only the symbol being changed.
-3. Start from the closest existing test named for the behavior. Do not scan all
-   of `tests/` or unpack every fixture to understand one code path.
-4. Use `rg` for symbols and filenames. Consult `ARCHITECTURE.md` for ownership
-   and `docs/TESTING.md` for test-lane selection before inventing a new route,
-   helper, test harness, or fixture generator.
-5. Keep dependency direction inward: shared implementation modules must not
-   import `index.js`, and host-independent code must not import `node/`.
-6. Do not inspect `dist/`, a vendored CLI bundle, or an installed plugin bundle
-   to discover public behavior. Use this file, `README.md`,
-   `docs/schemas/document-operations.schema.json`, and the unbundled source.
-
-### Task-to-Module Shortcuts
-
-| Task | Start here | Common focused tests |
-|---|---|---|
-| Basic text redline, formatting, or route choice | `engine/oxml-engine.js`, then the selected `engine/*-mode.js` | `tests/engine_reliability_tests.mjs`, `tests/formatting_tests.mjs` |
-| Run splitting or edits inside revisions | `engine/surgical-mode.js`, `engine/surgical-run-splitting.js`, `engine/surgical-diff-application.js` | `tests/revision_split_injection_tests.mjs`, `tests/cross_author_slicing_synthetic_tests.mjs` |
-| Accepted/rejected/current text or paragraph targeting | `core/paragraph-text.js`, `core/paragraph-targeting.js` | `tests/canonical_paragraph_text_tests.mjs`, `tests/revision_view_target_tests.mjs` |
-| Lists, numbering, or markdown structure | `pipeline/list-generation.js`, `pipeline/structured-content.js`, `services/numbering-helpers.js` | `tests/list_tests.mjs`, `tests/list_replacement_structure_tests.mjs`, `tests/structured_content_planner_tests.mjs` |
-| Tables | `engine/table-mode.js`, `core/table-targeting.js`, `services/table-reconciliation.js` | `tests/table_tests.mjs`, `tests/table_targeting_and_format_flags.mjs` |
-| Comments and replies | `services/comment-engine.js`, `services/comment-replies.js`, `services/comment-package.js` | `tests/comment_tests.mjs`, `tests/comment_reply_tests.mjs` |
-| Full-document operation scheduling or rollback | `services/document-operation-applier.js`, `services/batch-operation-orchestrator.js`, `services/document-operation-session.js` | `tests/standalone_operation_runner_tests.mjs`, `tests/performance_phase1_session_tests.mjs` |
-| DOCX ZIP wiring or CLI behavior | `node/docx-document.js`, `node/zip-archive.js`, `node/cli.js` | `tests/docx_package_facade_tests.mjs`, `tests/node_zip_archive_tests.mjs`, `tests/agent_cli_tests.mjs` |
-| Validation, receipts, and lifecycle oracles | `core/redline-validation.js`, `services/receipt-collector.js`, `services/revision-comment-management.js` | `tests/redline_validation_tests.mjs`, `tests/mutation_receipt_tests.mjs`, `tests/roundtrip_oracle_tests.mjs` |
-
-Run one focused suite with `node tests/<name>.mjs`. Run `npm test` only when the
-change crosses several subsystems or before release-level handoff. The Word COM,
-visual, corpus, coverage, and fixture-export commands are separate lanes; use
-them only when `docs/TESTING.md` says that lane proves the behavior in question.
+# Agent Knowledge Base
+
+> Detailed reference for @ansonlai/docx-redline-js. All code and command paths
+> are relative to the repository root. Start with `../AGENTS.md` for repository
+> work or `AGENT_FAST_START.md` for ordinary document edits; open this file only
+> when the quick guide points here or the task needs deeper behavior.
+
+## Start Here: Repository Layout
+
+This is one JavaScript package with three supported public surfaces. Choose the
+surface before following imports:
+
+| Use case | Public entry point | Primary implementation |
+|---|---|---|
+| Paragraph, range, list, table, comment, and OOXML transforms in any DOM-capable runtime | `index.js` (`@ansonlai/docx-redline-js`) | `engine/`, `pipeline/`, `core/`, and focused `services/` |
+| Operations against complete `word/document.xml` strings | `services/standalone-operation-runner.js` (`@ansonlai/docx-redline-js/standalone-runner`) | `services/document-operation-*.js` and `services/batch-operation-orchestrator.js` |
+| Universal complete `.docx` packages (`Uint8Array`) across Node, browsers, edge, and sandboxes | `index.js` (`@ansonlai/docx-redline-js`) or `document/docx-document.js` | `document/docx-document.js`, `document/zip-archive.js`, `core/sha256.js` |
+| Zero-dependency standalone sandbox bundles (n8n, Cloudflare Workers, edge) | `dist/docx-redline.bundle.js` / `.cjs` (`@ansonlai/docx-redline-js/bundle`) | Standalone inlined bundle (no Node built-ins) |
+| Complete `.docx` buffers and the CLI in Node.js (backward compatibility) | `node/index.js` (`@ansonlai/docx-redline-js/node`) and `bin/docx-redline.js` | `node/docx-document.js`, `node/zip-archive.js`, and package-plumbing services |
+
+The source tree is layered as follows:
+
+```text
+index.js                 root, host-independent public exports & universal facade
+adapters/                XML (auto DOMParser fallback), config, and logging adapters
+core/                    shared OOXML primitives, text views, targeting, SHA-256, validation
+document/                universal Uint8Array DOCX facade & fflate ZIP container
+pipeline/                ingestion, diffing, markdown, lists, and serialization stages
+engine/                  paragraph/range reconciliation and surgical/reconstruction modes
+orchestration/           route planning and structural list operation conversion
+services/                document operations, comments, receipts, package artifacts
+node/                    Node CLI and backward-compatibility facade re-exports
+bin/                     CLI launcher; behavior belongs in node/ or services/
+tests/*.mjs              directly runnable suites discovered by scripts/run-tests.mjs
+tests/helpers/           shared test utilities; not standalone suites
+tests/fixtures/          checked-in synthetic/golden inputs and expected outputs
+scripts/                 build, fixture generation, benchmarks, and Word automation
+docs/                    schemas, testing guidance, plans, and generated reports
+dist/                    generated universal ESM and zero-dependency sandbox bundles
+```
+
+`AGENTS.md` is the committed repository-wide agent guide. `.agent/` is ignored
+local-only agent configuration and must not be treated as package source or as
+instructions that will exist in another clone or in CI.
+
+### Route Changes Without Exploring Everything
+
+1. Identify the public surface in the table above.
+2. Read its entry point, then follow only the symbol being changed.
+3. Start from the closest existing test named for the behavior. Do not scan all
+   of `tests/` or unpack every fixture to understand one code path.
+4. Use `rg` for symbols and filenames. Consult `ARCHITECTURE.md` for ownership
+   and `docs/TESTING.md` for test-lane selection before inventing a new route,
+   helper, test harness, or fixture generator.
+5. Keep dependency direction inward: shared implementation modules must not
+   import `index.js`, and host-independent code must not import `node/`.
+6. Do not inspect `dist/`, a vendored CLI bundle, or an installed plugin bundle
+   to discover public behavior. Use this file, `README.md`,
+   `docs/schemas/document-operations.schema.json`, and the unbundled source.
+
+### Task-to-Module Shortcuts
+
+| Task | Start here | Common focused tests |
+|---|---|---|
+| Basic text redline, formatting, or route choice | `engine/oxml-engine.js`, then the selected `engine/*-mode.js` | `tests/engine_reliability_tests.mjs`, `tests/formatting_tests.mjs` |
+| Run splitting or edits inside revisions | `engine/surgical-mode.js`, `engine/surgical-run-splitting.js`, `engine/surgical-diff-application.js` | `tests/revision_split_injection_tests.mjs`, `tests/cross_author_slicing_synthetic_tests.mjs` |
+| Accepted/rejected/current text or paragraph targeting | `core/paragraph-text.js`, `core/paragraph-targeting.js` | `tests/canonical_paragraph_text_tests.mjs`, `tests/revision_view_target_tests.mjs` |
+| Lists, numbering, or markdown structure | `pipeline/list-generation.js`, `pipeline/structured-content.js`, `services/numbering-helpers.js` | `tests/list_tests.mjs`, `tests/list_replacement_structure_tests.mjs`, `tests/structured_content_planner_tests.mjs` |
+| Tables | `engine/table-mode.js`, `core/table-targeting.js`, `services/table-reconciliation.js` | `tests/table_tests.mjs`, `tests/table_targeting_and_format_flags.mjs` |
+| Comments and replies | `services/comment-engine.js`, `services/comment-replies.js`, `services/comment-package.js` | `tests/comment_tests.mjs`, `tests/comment_reply_tests.mjs` |
+| Full-document operation scheduling or rollback | `services/document-operation-applier.js`, `services/batch-operation-orchestrator.js`, `services/document-operation-session.js` | `tests/standalone_operation_runner_tests.mjs`, `tests/performance_phase1_session_tests.mjs` |
+| DOCX ZIP wiring or CLI behavior | `node/docx-document.js`, `node/zip-archive.js`, `node/cli.js` | `tests/docx_package_facade_tests.mjs`, `tests/node_zip_archive_tests.mjs`, `tests/agent_cli_tests.mjs` |
+| Validation, receipts, and lifecycle oracles | `core/redline-validation.js`, `services/receipt-collector.js`, `services/revision-comment-management.js` | `tests/redline_validation_tests.mjs`, `tests/mutation_receipt_tests.mjs`, `tests/roundtrip_oracle_tests.mjs` |
+
+Run one focused suite with `node tests/<name>.mjs`. Run `npm test` only when the
+change crosses several subsystems or before release-level handoff. The Word COM,
+visual, corpus, coverage, and fixture-export commands are separate lanes; use
+them only when `docs/TESTING.md` says that lane proves the behavior in question.
 
 ## What This Package Does
 
@@ -97,21 +100,44 @@ back to `word/document.xml`.
 ## Entry Point
 
 ```js
-import { applyRedlineToOxml, configureXmlProvider } from '@ansonlai/docx-redline-js';
+import { applyRedlineToOxml, openDocx, configureXmlProvider } from '@ansonlai/docx-redline-js';
 ```
 
-`index.js` is the primary host-independent entry point. Complete document XML
-and `.docx` package workflows use the standalone runner and Node facade listed
-in the repository-layout table above.
+`index.js` is the primary host-independent entry point, exposing both paragraph-level
+reconciliation (`applyRedlineToOxml`) and universal complete-document operations
+(`openDocx`, `DocxDocument`, `computePackageRevisionToken`).
+
+## XML Provider Setup (Zero Configuration)
+
+Zero configuration is required out of the box. The library automatically:
+1. Uses `globalThis.DOMParser` and `globalThis.XMLSerializer` when available in standard web runtimes.
+2. Transparently falls back to pure-JS `@xmldom/xmldom` in Node.js, edge workers, and sandboxes.
 
-## Required Setup (Node.js only)
+Consumers can optionally override these providers if a custom DOM implementation is desired:
 
 ```js
-import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
-configureXmlProvider({ DOMParser, XMLSerializer });
+import { configureXmlProvider } from '@ansonlai/docx-redline-js';
+configureXmlProvider({ DOMParser: MyDOMParser, XMLSerializer: MyXMLSerializer });
 ```
 
-Browsers have native DOM APIs, so no provider injection is typically needed.
+## Universal Complete-DOCX Operations (`openDocx`)
+
+Complete `.docx` documents can be opened directly from a `Uint8Array` (or Node `Buffer`) across all environments without Node built-in dependencies:
+
+```js
+import { openDocx } from '@ansonlai/docx-redline-js';
+
+const doc = openDocx(docxUint8Array);
+const inspection = doc.inspect();
+const result = await doc.applyOperations([
+  { type: 'replace', target: { paragraphId: '00000001' }, modified: 'Updated clause text' }
+], { author: 'AI Editor' });
+
+if (result.written) {
+  const outputBytes = doc.toUint8Array(); // canonical Uint8Array
+  // In Node.js: const outputBuf = doc.toBuffer();
+}
+```
 
 ## Key APIs by Use Case
 
@@ -217,57 +243,57 @@ const result = await applyOperationsToDocumentXml(documentXml, operations, 'Agen
 The operation runner uses these field names:
 
 ```js
-const operations = [
+const operations = [
   { type: 'redline', target: 'Old paragraph text', modified: 'New paragraph text', targetRef: 12 },
   { type: 'comment', target: 'Paragraph text', textToComment: 'anchor text', commentContent: 'Comment body', targetRef: 18 },
   { type: 'highlight', target: 'Paragraph text', textToHighlight: 'anchor text', color: 'yellow', targetRef: 24 }
-];
-```
-
-To counterpropose text for a paragraph wholly deleted by another reviewer,
-use explicit restoration intent. A normal `redline` remains fail-closed with
-`FOREIGN_PARAGRAPH_MARK_DELETION`:
-
-```js
-const restoration = {
-  type: 'restore',
-  target: { paragraphId: '1A2B3C4D', exactText: 'Original deleted paragraph text.' },
-  modified: 'Restored or adjusted paragraph text.',
-  author: 'Editor'
-};
-```
-
-`restore` targets default to `revisionView: 'rejected'`, because that is where
-the deleted source text is visible. Inspection/extraction fingerprints are
-view-scoped and returned with a matching `revisionView`; copy the fingerprint,
-exact text, and view together. Set `revisionView: 'accepted'` explicitly only
-when intentionally using an accepted-view descriptor.
-
-For a contiguous range, provide `targetEnd`/`targetEndRef` and one string per
-source paragraph in `modified`. Restoration always uses tracked changes,
-preserves the deleted source paragraph, and inserts the counterproposal after
-the complete deleted source block with a fresh paragraph ID. Unchanged
-pre-existing validation defects remain baseline diagnostics; a restore fails
-with `GENERATED_OOXML_INVALID` only when it introduces a new validation error.
-
-To insert run-level text inside content visible only in the rejected view, use
-an explicit rejected-view `insert` operation:
-
-```js
-const insertion = {
-  type: 'insert',
-  target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
-  anchor: { exactText: 'must pay', occurrence: 1, offset: 5 },
-  modified: '[clarification] ',
-  author: 'Editor',
-  existingRevisions: 'slice-cross-author'
-};
-```
-
-The anchor offset is relative to `anchor.exactText`. Repeated anchors require an
-explicit `occurrence`. The engine preserves the foreign deletion as sibling
-`w:del` carriers around a top-level `w:ins`; unsupported comments, bookmarks,
-fields, hyperlinks, moves, or non-text split boundaries fail closed.
+];
+```
+
+To counterpropose text for a paragraph wholly deleted by another reviewer,
+use explicit restoration intent. A normal `redline` remains fail-closed with
+`FOREIGN_PARAGRAPH_MARK_DELETION`:
+
+```js
+const restoration = {
+  type: 'restore',
+  target: { paragraphId: '1A2B3C4D', exactText: 'Original deleted paragraph text.' },
+  modified: 'Restored or adjusted paragraph text.',
+  author: 'Editor'
+};
+```
+
+`restore` targets default to `revisionView: 'rejected'`, because that is where
+the deleted source text is visible. Inspection/extraction fingerprints are
+view-scoped and returned with a matching `revisionView`; copy the fingerprint,
+exact text, and view together. Set `revisionView: 'accepted'` explicitly only
+when intentionally using an accepted-view descriptor.
+
+For a contiguous range, provide `targetEnd`/`targetEndRef` and one string per
+source paragraph in `modified`. Restoration always uses tracked changes,
+preserves the deleted source paragraph, and inserts the counterproposal after
+the complete deleted source block with a fresh paragraph ID. Unchanged
+pre-existing validation defects remain baseline diagnostics; a restore fails
+with `GENERATED_OOXML_INVALID` only when it introduces a new validation error.
+
+To insert run-level text inside content visible only in the rejected view, use
+an explicit rejected-view `insert` operation:
+
+```js
+const insertion = {
+  type: 'insert',
+  target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
+  anchor: { exactText: 'must pay', occurrence: 1, offset: 5 },
+  modified: '[clarification] ',
+  author: 'Editor',
+  existingRevisions: 'slice-cross-author'
+};
+```
+
+The anchor offset is relative to `anchor.exactText`. Repeated anchors require an
+explicit `occurrence`. The engine preserves the foreign deletion as sibling
+`w:del` carriers around a top-level `w:ins`; unsupported comments, bookmarks,
+fields, hyperlinks, moves, or non-text split boundaries fail closed.
 
 `targetRef` is an optional 1-based paragraph reference used to disambiguate
 duplicate text. An operation-level `author` overrides the batch author; batch
@@ -296,9 +322,9 @@ read-only inspection of an agent-generated batch before applying it. Preflight i
 read-only and strict by default: duplicate exact text returns `AMBIGUOUS_TARGET`,
 approximate text is not selected, and the result reports candidate targets,
 missing anchors, existing revisions, authors, required artifacts, and
-same-paragraph conflicts. Direct execution is progressive by default
-(`atomic: false`); pass `{ atomic: true }` when the batch must roll back as a
-unit. When permissive resolution
+same-paragraph conflicts. Direct execution is progressive by default
+(`atomic: false`); pass `{ atomic: true }` when the batch must roll back as a
+unit. When permissive resolution
 encounters duplicate candidate paragraphs, it emits an
 `AMBIGUOUS_TARGET_HEURISTIC_USED` warning; migrate to `{ strictTargets: true }`
 with strict descriptors (`paragraphId`, `index`, `occurrence`, or `fingerprint`)
@@ -349,7 +375,7 @@ const inspection = inspectDocumentParts({ documentXml, commentsXml, numberingXml
 Reuse `exactText` plus `paragraphId` or `fingerprint` in an operation. Computed
 list labels and excerpts are for display, not replacements for exact targets.
 
-### Safely edit a complete DOCX in Node
+### Safely edit a complete DOCX in Node
 
 ```js
 import { openDocx } from '@ansonlai/docx-redline-js/node';
@@ -361,197 +387,197 @@ if (!result.written) throw new Error(result.error?.message || 'No output written
 const outputBuffer = result.toBuffer();
 ```
 
-This facade defaults to strict targets, allocates package-safe comment IDs,
-merges numbering, updates relationships/content types, and rolls back to the
-original buffer when an atomic transaction fails.
-
-### Designing a thin agent wrapper
-
-New wrappers should delegate at a package boundary instead of copying internal
-algorithms:
-
-- Shell/file wrappers invoke the `docx-redline` CLI and preserve its JSON stdout
-  and exit code.
-- Node byte-oriented wrappers use `openDocx`, `inspect`, `applyOperations`,
-  `resolveRevisions`, `deleteComments`, and `toBuffer`.
-- XML-only hosts use the standalone runner and remain responsible for package
-  artifacts returned beside `documentXml`.
-- Paragraph/range hosts use root exports and remain responsible for deciding how
-  the returned OOXML is inserted into a larger document.
-
-A wrapper that vendors the CLI should perform a startup compatibility handshake
-with `docx-redline version`. Pin the minimum CLI `contractVersion` and only the
-capabilities that the wrapper's workflow actually requires. If the runtime is
-too old, fail closed with an upgrade instruction; do not inspect the bundled
-implementation or fall back to direct ZIP/XML mutation.
-
-A wrapper may choose product defaults for author, atomic mode, output naming,
-and accepted operation subsets. It must preserve strict targeting, exact text,
-structured errors, per-operation results, receipts, warnings, validation, and
-rollback behavior. It must not infer success from `hasChanges` alone or turn a
-partial progressive result into an unconditional success.
-
-Document those choices as wrapper policy and pass them explicitly. In
-particular, do not describe a wrapper's preferred revision or atomicity policy
-as though it were the underlying CLI or facade default.
-
-Target handles are scoped to the exact package version that produced them. A
-Node wrapper should return the package-scoped token from
-`document.getRevisionToken()` with every inspection and pass it back as
-`expectedRevision` when applying the planned operations. Do not substitute the
-document-parts token included in `document.inspect()`; that token has a different
-scope and the Node facade rejects it. A shell wrapper should ensure extraction
-and application use the same unchanged path, and re-extract after switching to a
-derived working copy.
-
-For agent-facing function tools, prefer separate inspection, application, and
-review-resolution tools. Describe each tool's use case, required inputs, side
-effects, retry safety, success criteria, and common error codes. Convenience
-tools should build operations defined by
-`docs/schemas/document-operations.schema.json` and delegate to the same apply
-path rather than implementing custom mutations.
-
-For a `restore_deleted_paragraph` convenience tool, force inspection to
-`revisionView: 'rejected'`, copy the exact target descriptor from that view, and
-emit a canonical `restore` operation with the same explicit revision view.
-Wholly foreign-deleted paragraphs appear empty in accepted/current inspection;
-this is expected, not evidence that the paragraph is untargetable. Never reuse a
-restore descriptor from a different source or earlier working-copy version. On
-`TARGET_TEXT_MISMATCH`, re-extract from the exact package being applied rather
-than inspecting implementation bundles or retrying the same operation.
-
-### Agent Document Workflow (CLI)
-
-Use the `docx-redline` CLI for complete `.docx` files. It emits JSON on stdout,
-keeps exact text intact, and never overwrites the source unless `--in-place` is
-explicitly supplied.
-
-#### Operation Model: Choose by Output Shape
-
-Every text-bearing operation targets existing content. Its `modified` field is
-the complete desired accepted-view content for that target, not merely the new
-fragment to insert. Do not choose a type from its English name alone.
-
-| Requested result | Operation shape |
-|---|---|
-| Change text within one paragraph or replace its content | `{ type: 'redline', target, modified }` (`replace` is a compatibility alias) |
-| Delete a whole paragraph | `{ type: 'delete', target }` (normalized to a redline with `modified: ''`) |
-| Change native list structure | `{ type: 'list-change', target, modified: '<complete Markdown list>' }` |
-| Reconcile a Word table | `{ type: 'table-reconciliation', target, modified: '<complete Markdown table>' }` |
-| Comment or highlight existing text | `comment` with `commentContent`, or `highlight` with `textToHighlight` |
-| Change character or paragraph formatting | `character-format`/`format` with `textToFormat` and `properties`, or `paragraph-format` with `properties` |
-| Counterpropose a paragraph wholly deleted by another author | `restore` with a rejected-view target |
-| Insert text inside another author's rejected-view content | `insert` with `target.revisionView: 'rejected'`, an exact `anchor`, and `existingRevisions: 'slice-cross-author'` |
-
-`insert`, `list-change`, `table-reconciliation`, `replace`, and text-bearing
-`format` are accepted compatibility types, but they normally normalize to the
-same redline operation path. In particular, ordinary `{ type: 'insert' }` does
-not mean “create a new sibling paragraph”; without a rejected-view target and
-anchor, `modified` is still interpreted as the complete replacement text.
-
-To append a native sibling item after an existing list item, prefer an explicit
-`list-change` whose `modified` value contains the complete affected list block:
-
-```json
-{
-  "type": "list-change",
-  "target": {
-    "exactText": "Review the report.",
-    "paragraphId": "1A2B3C4D"
-  },
-  "modified": "1. Review the report.\n2. Record the approval decision."
-}
-```
-
-The Markdown markers describe structure; visible labels are generated from the
-document's numbering. Do not put `m)` or another computed label into target text.
-For a single adjacent item in an existing list, the runner also accepts a
-one-line `redline` where `modified` is the exact current item followed by the
-new item's unnumbered text. Preserve the current item verbatim, omit the new
-label, and make the new item at least six words so the adjacency form is
-unambiguous. Use the explicit Markdown list form when adding multiple items,
-nesting, or changing levels.
-
-The canonical machine-readable contract is
-`docs/schemas/document-operations.schema.json`. Read that schema or the examples
-here instead of grepping bundled implementation code.
-
-#### Standard Workflow (Extract Then Apply)
-
-Use this for ordinary edits. `apply` validates the resulting package and
-revision markup internally before writing, so do not add `preflight` or baseline
-`validate` merely for reassurance.
-
-1. Run one focused `extract`. Add `--around 3` when surrounding context is
-   needed. Retain `exactText` for drafting and target with `paragraphId` plus
-   `fingerprint`.
-2. Build one final operation per target. Use complete `modified` text for broad
-   semantic revisions or localized `replacements` for small literal changes in
-   an inspected target. Consolidate multiple changes to one paragraph.
-3. Run `apply` once per stable batch. Independent strong targets bind against
-   the batch-start document and do not need bottom-up sorting. Use captures only
-   for intentional created-content dependencies.
-4. Require `completion: true` and a non-null `outputPath`. The CLI derives
-   completion from write status, operation outcomes, commit disposition, and
-   localized accepted-view verification.
-5. Run a focused post-apply extraction only when placement or structural output
-   needs confirmation.
-
-If `apply` returns an error, follow the recovery envelope below and make one
-cause-specific correction. Do not probe behavior with disposable mutations or
-read a vendor bundle.
-
-```bash
-# 1. Focused contextual discovery
-docx-redline extract contract.docx --search "termination" --around 3
-
-# 2. Serializer-backed apply against the inspected target
-node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
-
-# Optional clean edit without tracked changes
-docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
-```
+This facade defaults to strict targets, allocates package-safe comment IDs,
+merges numbering, updates relationships/content types, and rolls back to the
+original buffer when an atomic transaction fails.
+
+### Designing a thin agent wrapper
+
+New wrappers should delegate at a package boundary instead of copying internal
+algorithms:
+
+- Shell/file wrappers invoke the `docx-redline` CLI and preserve its JSON stdout
+  and exit code.
+- Node byte-oriented wrappers use `openDocx`, `inspect`, `applyOperations`,
+  `resolveRevisions`, `deleteComments`, and `toBuffer`.
+- XML-only hosts use the standalone runner and remain responsible for package
+  artifacts returned beside `documentXml`.
+- Paragraph/range hosts use root exports and remain responsible for deciding how
+  the returned OOXML is inserted into a larger document.
+
+A wrapper that vendors the CLI should perform a startup compatibility handshake
+with `docx-redline version`. Pin the minimum CLI `contractVersion` and only the
+capabilities that the wrapper's workflow actually requires. If the runtime is
+too old, fail closed with an upgrade instruction; do not inspect the bundled
+implementation or fall back to direct ZIP/XML mutation.
+
+A wrapper may choose product defaults for author, atomic mode, output naming,
+and accepted operation subsets. It must preserve strict targeting, exact text,
+structured errors, per-operation results, receipts, warnings, validation, and
+rollback behavior. It must not infer success from `hasChanges` alone or turn a
+partial progressive result into an unconditional success.
+
+Document those choices as wrapper policy and pass them explicitly. In
+particular, do not describe a wrapper's preferred revision or atomicity policy
+as though it were the underlying CLI or facade default.
+
+Target handles are scoped to the exact package version that produced them. A
+Node wrapper should return the package-scoped token from
+`document.getRevisionToken()` with every inspection and pass it back as
+`expectedRevision` when applying the planned operations. Do not substitute the
+document-parts token included in `document.inspect()`; that token has a different
+scope and the Node facade rejects it. A shell wrapper should ensure extraction
+and application use the same unchanged path, and re-extract after switching to a
+derived working copy.
+
+For agent-facing function tools, prefer separate inspection, application, and
+review-resolution tools. Describe each tool's use case, required inputs, side
+effects, retry safety, success criteria, and common error codes. Convenience
+tools should build operations defined by
+`docs/schemas/document-operations.schema.json` and delegate to the same apply
+path rather than implementing custom mutations.
+
+For a `restore_deleted_paragraph` convenience tool, force inspection to
+`revisionView: 'rejected'`, copy the exact target descriptor from that view, and
+emit a canonical `restore` operation with the same explicit revision view.
+Wholly foreign-deleted paragraphs appear empty in accepted/current inspection;
+this is expected, not evidence that the paragraph is untargetable. Never reuse a
+restore descriptor from a different source or earlier working-copy version. On
+`TARGET_TEXT_MISMATCH`, re-extract from the exact package being applied rather
+than inspecting implementation bundles or retrying the same operation.
+
+### Agent Document Workflow (CLI)
+
+Use the `docx-redline` CLI for complete `.docx` files. It emits JSON on stdout,
+keeps exact text intact, and never overwrites the source unless `--in-place` is
+explicitly supplied.
+
+#### Operation Model: Choose by Output Shape
+
+Every text-bearing operation targets existing content. Its `modified` field is
+the complete desired accepted-view content for that target, not merely the new
+fragment to insert. Do not choose a type from its English name alone.
+
+| Requested result | Operation shape |
+|---|---|
+| Change text within one paragraph or replace its content | `{ type: 'redline', target, modified }` (`replace` is a compatibility alias) |
+| Delete a whole paragraph | `{ type: 'delete', target }` (normalized to a redline with `modified: ''`) |
+| Change native list structure | `{ type: 'list-change', target, modified: '<complete Markdown list>' }` |
+| Reconcile a Word table | `{ type: 'table-reconciliation', target, modified: '<complete Markdown table>' }` |
+| Comment or highlight existing text | `comment` with `commentContent`, or `highlight` with `textToHighlight` |
+| Change character or paragraph formatting | `character-format`/`format` with `textToFormat` and `properties`, or `paragraph-format` with `properties` |
+| Counterpropose a paragraph wholly deleted by another author | `restore` with a rejected-view target |
+| Insert text inside another author's rejected-view content | `insert` with `target.revisionView: 'rejected'`, an exact `anchor`, and `existingRevisions: 'slice-cross-author'` |
+
+`insert`, `list-change`, `table-reconciliation`, `replace`, and text-bearing
+`format` are accepted compatibility types, but they normally normalize to the
+same redline operation path. In particular, ordinary `{ type: 'insert' }` does
+not mean “create a new sibling paragraph”; without a rejected-view target and
+anchor, `modified` is still interpreted as the complete replacement text.
+
+To append a native sibling item after an existing list item, prefer an explicit
+`list-change` whose `modified` value contains the complete affected list block:
+
+```json
+{
+  "type": "list-change",
+  "target": {
+    "exactText": "Review the report.",
+    "paragraphId": "1A2B3C4D"
+  },
+  "modified": "1. Review the report.\n2. Record the approval decision."
+}
+```
+
+The Markdown markers describe structure; visible labels are generated from the
+document's numbering. Do not put `m)` or another computed label into target text.
+For a single adjacent item in an existing list, the runner also accepts a
+one-line `redline` where `modified` is the exact current item followed by the
+new item's unnumbered text. Preserve the current item verbatim, omit the new
+label, and make the new item at least six words so the adjacency form is
+unambiguous. Use the explicit Markdown list form when adding multiple items,
+nesting, or changing levels.
+
+The canonical machine-readable contract is
+`docs/schemas/document-operations.schema.json`. Read that schema or the examples
+here instead of grepping bundled implementation code.
+
+#### Standard Workflow (Extract Then Apply)
+
+Use this for ordinary edits. `apply` validates the resulting package and
+revision markup internally before writing, so do not add `preflight` or baseline
+`validate` merely for reassurance.
+
+1. Run one focused `extract`. Add `--around 3` when surrounding context is
+   needed. Retain `exactText` for drafting and target with `paragraphId` plus
+   `fingerprint`.
+2. Build one final operation per target. Use complete `modified` text for broad
+   semantic revisions or localized `replacements` for small literal changes in
+   an inspected target. Consolidate multiple changes to one paragraph.
+3. Run `apply` once per stable batch. Independent strong targets bind against
+   the batch-start document and do not need bottom-up sorting. Use captures only
+   for intentional created-content dependencies.
+4. Require `completion: true` and a non-null `outputPath`. The CLI derives
+   completion from write status, operation outcomes, commit disposition, and
+   localized accepted-view verification.
+5. Run a focused post-apply extraction only when placement or structural output
+   needs confirmation.
+
+If `apply` returns an error, follow the recovery envelope below and make one
+cause-specific correction. Do not probe behavior with disposable mutations or
+read a vendor bundle.
+
+```bash
+# 1. Focused contextual discovery
+docx-redline extract contract.docx --search "termination" --around 3
+
+# 2. Serializer-backed apply against the inspected target
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
+
+# Optional clean edit without tracked changes
+docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
+```
 
 Key CLI defaults and behaviors:
 - **Author**: Automatically defaults to `'AI Redliner'` (overridable via `--author` or `DOCX_REDLINE_AUTHOR` environment variable).
 - **Existing revisions**: Defaults to `'merge-same-author'`. Pass `--existing-revisions slice-cross-author` to edit inside another reviewer's pending insertions with native carrier slicing.
 - **Overwrite behavior**: Destination files provided via `--output` overwrite by default. To protect existing destination files, pass `--no-overwrite` or `--no-clobber`. The source document is never overwritten unless `--in-place` is specified.
 - **Tracked changes**: Defaults to `generateRedlines: true`. When clean direct text is needed, pass `--no-redlines`.
-- **Atomic rollback (optional)**: Operations apply progressively by default (`atomic: false`). For all-or-nothing transactional rollback where any error halts and reverts all changes, pass `--atomic`.
-- **Complete-success exit (optional)**: Pass `--require-complete` when `partial` must exit nonzero (`3`). Errors exit `2`; the legacy zero exit for partial results remains when the flag is omitted.
-- **Agent profile**: `--profile agent` enables complete-success exit behavior but preserves progressive execution and the ordinary revision policy. Compose it with `--atomic` or an explicit `--existing-revisions` choice when intended; resolved values appear in `effectiveOptions`.
-- **Operation transport**: A UTF-8 operations file and serializer-backed `--operations -` are peers. Use whichever the host can construct without interpolating legal text in the shell.
-- **Compact mutation JSON**: `apply`, `accept`, `reject`, and `delete-comments` omit document/package XML, full validation arrays, and duplicate nested receipts. Top-level `receipts` is authoritative. Pass `--compact` for one-line JSON; run `validate` for full issue records.
-- Check `completion: true` and a non-null `outputPath` on stdout. Failed,
-  partial, rolled-back, unverified, and unwritten work cannot appear complete.
-  If an error occurs, follow `error.recovery.action` before correcting the cause.
-
-For multi-clause or multi-page reviews, use focused batches rather than one
-massive batch. This keeps context compact and simplifies error diagnosis.
-
-#### Optional Speculative Localized Apply
-
-Targetless localized apply remains available to expert users and harnesses with
-a measured confidence policy. It is not the ordinary agent workflow:
-
-```bash
-# Globally unique literal
-docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-
-# Optional directional scope using a longer, fairly unique phrase
-docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-```
-
-Omitting a target asks the CLI to resolve one eligible paragraph. Generic or
-repeated anchors union their windows and may produce `AMBIGUOUS_TARGET`, costing
-a recovery turn. `--around 3` is symmetric; `--occurrence` disambiguates only
-inside an already selected paragraph. `anchorMatchCount > 1` signals a repeated
-anchor even after a successful edit. Matching is exact and case-sensitive first,
-then permits only ASCII-space/NBSP equivalence; ambiguity still fails closed.
-
-Localized `change` evidence retains bounded before/after excerpts, commit
-disposition, and accepted-view verification for audit consumers. Ordinary
-agents rely on the computed top-level `completion` signal.
+- **Atomic rollback (optional)**: Operations apply progressively by default (`atomic: false`). For all-or-nothing transactional rollback where any error halts and reverts all changes, pass `--atomic`.
+- **Complete-success exit (optional)**: Pass `--require-complete` when `partial` must exit nonzero (`3`). Errors exit `2`; the legacy zero exit for partial results remains when the flag is omitted.
+- **Agent profile**: `--profile agent` enables complete-success exit behavior but preserves progressive execution and the ordinary revision policy. Compose it with `--atomic` or an explicit `--existing-revisions` choice when intended; resolved values appear in `effectiveOptions`.
+- **Operation transport**: A UTF-8 operations file and serializer-backed `--operations -` are peers. Use whichever the host can construct without interpolating legal text in the shell.
+- **Compact mutation JSON**: `apply`, `accept`, `reject`, and `delete-comments` omit document/package XML, full validation arrays, and duplicate nested receipts. Top-level `receipts` is authoritative. Pass `--compact` for one-line JSON; run `validate` for full issue records.
+- Check `completion: true` and a non-null `outputPath` on stdout. Failed,
+  partial, rolled-back, unverified, and unwritten work cannot appear complete.
+  If an error occurs, follow `error.recovery.action` before correcting the cause.
+
+For multi-clause or multi-page reviews, use focused batches rather than one
+massive batch. This keeps context compact and simplifies error diagnosis.
+
+#### Optional Speculative Localized Apply
+
+Targetless localized apply remains available to expert users and harnesses with
+a measured confidence policy. It is not the ordinary agent workflow:
+
+```bash
+# Globally unique literal
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# Optional directional scope using a longer, fairly unique phrase
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+Omitting a target asks the CLI to resolve one eligible paragraph. Generic or
+repeated anchors union their windows and may produce `AMBIGUOUS_TARGET`, costing
+a recovery turn. `--around 3` is symmetric; `--occurrence` disambiguates only
+inside an already selected paragraph. `anchorMatchCount > 1` signals a repeated
+anchor even after a successful edit. Matching is exact and case-sensitive first,
+then permits only ASCII-space/NBSP equivalence; ambiguity still fails closed.
+
+Localized `change` evidence retains bounded before/after excerpts, commit
+disposition, and accepted-view verification for audit consumers. Ordinary
+agents rely on the computed top-level `completion` signal.
 
 #### High-Assurance / Staged Verification Workflow (Optional)
 
@@ -574,7 +600,7 @@ targets. For most unique clauses, `"target": "exact paragraph text"` is
 sufficient; use discriminators (`paragraphId`, `fingerprint`, `index`, or
 `occurrence`) when duplicate paragraph text appears in the document. Never
 normalize or reconstruct `exactText`. Operation files follow
-[`docs/schemas/document-operations.schema.json`](schemas/document-operations.schema.json).
+[`docs/schemas/document-operations.schema.json`](schemas/document-operations.schema.json).
 
 #### Commands
 
@@ -589,33 +615,33 @@ normalize or reconstruct `exactText`. Operation files follow
   text for human follow-up; do not silently convert this into comment removal.
 - `validate` audits revision markup and DOCX package wiring, optionally comparing against a `--baseline`.
 
-Paragraph indexes are 1-based. Inspection filters are `--index 12`,
-`--range 10:30`, `--indexes 2,5,8`, `--search text`, `--revised`, `--table`,
-`--body`, `--non-empty`, and `--view accepted|rejected|current`. Search is
-case-insensitive. When a search returns 0 matches in the active view but matches
-exist in the alternate view (such as searching for a deleted clause to restore),
-`selection.hint` provides immediate guidance to re-run with `--view rejected`.
-Compact `extract --revised` results retain `hasRevisions`, `revisionAuthors`,
-and `deleted`/`inserted` cues, so an empty `exactText` is identifiable as content
-hidden by the selected revision view rather than a failed filter.
-For one strongly identified rejected-view paragraph, `apply --restore
---target-id ID` restores the rejected text verbatim. One exact
-`--find`/`--replace` pair may adjust it without restating the paragraph. The
-shortcut refuses ranges, captures, weak targets, and inferred adjacent content.
-Add `--around N` (`--context N` or `-C N`) to a search;
-context records are labeled separately and do not consume the direct-hit
-`--limit`. Continue a bounded result with `--after <paragraph-index>`. Ordinary
-unscoped CLI inspection defaults to 20 direct records and a 48 KiB soft budget;
-`--all` deliberately opts out. A malformed filter or unknown option is an error
-rather than an unfiltered fallback. CLI help commands (`apply --help`,
-`extract --help`, `--help`) report canonical GitHub repository URLs in their
-`documentation` array.
-
-Mutating commands use `--author`, operation-level authors, then
-`DOCX_REDLINE_AUTHOR`, falling back visibly to `AI Redliner`; review-resolution
-commands may use `--all-authors` where applicable. Without `--output`, a sibling
-such as `contract.redlined.docx` is chosen. Existing outputs are refused unless
-`--force` is present. `--in-place` is the only way to overwrite the input.
+Paragraph indexes are 1-based. Inspection filters are `--index 12`,
+`--range 10:30`, `--indexes 2,5,8`, `--search text`, `--revised`, `--table`,
+`--body`, `--non-empty`, and `--view accepted|rejected|current`. Search is
+case-insensitive. When a search returns 0 matches in the active view but matches
+exist in the alternate view (such as searching for a deleted clause to restore),
+`selection.hint` provides immediate guidance to re-run with `--view rejected`.
+Compact `extract --revised` results retain `hasRevisions`, `revisionAuthors`,
+and `deleted`/`inserted` cues, so an empty `exactText` is identifiable as content
+hidden by the selected revision view rather than a failed filter.
+For one strongly identified rejected-view paragraph, `apply --restore
+--target-id ID` restores the rejected text verbatim. One exact
+`--find`/`--replace` pair may adjust it without restating the paragraph. The
+shortcut refuses ranges, captures, weak targets, and inferred adjacent content.
+Add `--around N` (`--context N` or `-C N`) to a search;
+context records are labeled separately and do not consume the direct-hit
+`--limit`. Continue a bounded result with `--after <paragraph-index>`. Ordinary
+unscoped CLI inspection defaults to 20 direct records and a 48 KiB soft budget;
+`--all` deliberately opts out. A malformed filter or unknown option is an error
+rather than an unfiltered fallback. CLI help commands (`apply --help`,
+`extract --help`, `--help`) report canonical GitHub repository URLs in their
+`documentation` array.
+
+Mutating commands use `--author`, operation-level authors, then
+`DOCX_REDLINE_AUTHOR`, falling back visibly to `AI Redliner`; review-resolution
+commands may use `--all-authors` where applicable. Without `--output`, a sibling
+such as `contract.redlined.docx` is chosen. Existing outputs are refused unless
+`--force` is present. `--in-place` is the only way to overwrite the input.
 
 Treat a nonzero exit code or JSON `status: "error"` as failure. A failed atomic
 operation reports `written: false` and does not write an output file.
@@ -653,7 +679,7 @@ must use the JSON status and process exit code; failed atomic work has
 
 #### Safe Operations File Creation (JSON vs. Shell Heredocs)
 
-When composing batch operation JSON, whether for a file or stdin:
+When composing batch operation JSON, whether for a file or stdin:
 
 - **Use structured file-writing tools or JSON serializers**: Write operations files via your environment's file-creation tools or a language JSON serializer (`JSON.stringify`).
 - **Never compose operations in raw shell heredocs** (e.g., `cat << 'EOF'` in bash or PowerShell `@" ... "@`): Legal clauses routinely contain curly quotes (`“ ”`), smart apostrophes (`’`), em-dashes (`—`), section symbols (`§`), non-breaking spaces, and backslashes. Shell heredocs frequently mangle Unicode character encodings, quote escaping, and whitespace formatting, causing immediate `TARGET_NOT_FOUND` failures.
@@ -664,9 +690,9 @@ In default progressive mode (`atomic: false`), operations execute independently:
 
 - **Do not rely solely on top-level `written: true` or `status !== "error"`**: A progressive batch can return `status: "partial"` with `written: true` when some operations succeed and others fail.
 - **Walk every entry in `results`**: Check `results[i].status` and `results[i].error`. Any `status: "error"` entry in `results` represents an unapplied change that must be investigated and resolved.
-- **`written: false`**: Indicates that zero operations were committed (or an atomic rollback occurred). Never treat or present an unwritten or partial output file as complete.
-- **Follow `retryPlan`**: `base: "original"` means use the unchanged source and replay the corrected batch. `base: "output"` means retain committed progressive edits and submit only failed/unattempted indexes. `sameArgumentsSafe` is always false for failures.
-- **Follow the recovery envelope**: Use `error.recovery.action`, `requiresReinspection`, and `requiresUserAuthorization` rather than deriving a retry from the prose message. The envelope is versioned by `recoveryVersion`.
+- **`written: false`**: Indicates that zero operations were committed (or an atomic rollback occurred). Never treat or present an unwritten or partial output file as complete.
+- **Follow `retryPlan`**: `base: "original"` means use the unchanged source and replay the corrected batch. `base: "output"` means retain committed progressive edits and submit only failed/unattempted indexes. `sameArgumentsSafe` is always false for failures.
+- **Follow the recovery envelope**: Use `error.recovery.action`, `requiresReinspection`, and `requiresUserAuthorization` rather than deriving a retry from the prose message. The envelope is versioned by `recoveryVersion`.
 
 #### Human-Readable References vs. Internal Machine Handles
 
@@ -687,19 +713,19 @@ When the CLI or runner returns an error code, follow these specific recovery act
 |---|---|---|
 | `TARGET_NOT_FOUND` | Target text did not match any paragraph. | **Do NOT retry with paraphrased text.** Re-run `extract`/`inspect`, copy `exactText` verbatim (including exact whitespace/punctuation), and add a discriminator (`paragraphId`, `fingerprint`, or `occurrence`). |
 | `AMBIGUOUS_TARGET` | Multiple paragraphs match identical text. | Disambiguate by supplying `paragraphId`, `fingerprint`, `occurrence`, or `index` in the target descriptor. |
-| `ANCHOR_NOT_FOUND` / `AMBIGUOUS_ANCHOR` | A comment or rejected-view insertion anchor was not uniquely matched. | For comments, narrow `textToComment` or omit it to anchor the whole paragraph. For rejected-view insertion, copy exact rejected text and provide `anchor.occurrence`. |
-| `OVERLAPPING_SOURCE_TARGETS` / `OVERLAPPING_TEXT_EDITS` | Multiple complete text operations target the same batch-start source. | Consolidate all changes to that paragraph into one `redline` or `replace`; the library cannot choose between incompatible complete desired states. |
-| `REVISION_ORDER_CONFLICT` | A text rewrite and formatting/highlight operation overlap the same source. | Consolidate or split the work at an intentional created-content dependency; do not try a different arbitrary order. |
-| `CAPTURE_FANOUT_CONFLICT` | Multiple mutating consumers share one capture without distinct selectors. | Give consumers distinct selectors, chain them explicitly, or split the batch. |
-| `EXISTING_REVISIONS` | Target paragraph contains tracked changes from another author. | Fails closed to protect third-party review marks. If editing inside that reviewer's pending insertion is intended, pass `--existing-revisions slice-cross-author` (or `existingRevisions: 'slice-cross-author'`). Do not pass `accept-all-first` without explicit user authorization. |
-| `PATCH_ROUNDTRIP_MISMATCH` | A cross-author surgical edit did not reconstruct the requested modified text exactly. | Treat the operation as unapplied. Re-extract the exact paragraph text and split the edit into a narrower operation that does not cross the reported structural boundary. |
-| `FOREIGN_PARAGRAPH_MARK_DELETION` | A normal edit attempted to write into a paragraph wholly deleted by another reviewer. | Use an explicit `restore` operation if the user intends to counterpropose that paragraph; otherwise leave the deletion unresolved. |
-| `RESTORATION_STATE_REQUIRED` / `RESTORATION_COUNT_MISMATCH` | A `restore` target is not a wholly foreign-deleted paragraph, or its replacement count does not match the paragraph range. | Re-inspect the document and target the deleted paragraph by stable descriptor; provide exactly one replacement string per source paragraph. |
-| `REJECTED_INSERTION_STATE_REQUIRED` / `UNSAFE_REVISION_BOUNDARY` | An explicit rejected-view insertion did not resolve to supported plain run text inside a wholly foreign-deleted paragraph. | Do not fall back to a generic edit. Narrow the exact anchor/offset, or handle comments, bookmarks, fields, hyperlinks, moves, or other structural boundaries manually. |
-| `GENERATED_OOXML_INVALID` | The operation introduced a new validation error relative to its baseline. | Treat the operation as unapplied and inspect `generatedIssues`; correct the generating operation or builder rather than repairing or accepting the source document's unrelated baseline defects. |
-| `UNSAFE_DELETED_TABLE_ROW` / `UNSUPPORTED_MOVE_REVISION` / `SECTION_BREAK_PARAGRAPH` / `UNSAFE_PARAGRAPH_PLACEMENT` | Paragraph restoration cannot preserve the source structural boundary safely. | Do not retry as an ordinary redline. Resolve the row/move/section/placement condition manually or narrow the restoration to a safe paragraph. |
+| `ANCHOR_NOT_FOUND` / `AMBIGUOUS_ANCHOR` | A comment or rejected-view insertion anchor was not uniquely matched. | For comments, narrow `textToComment` or omit it to anchor the whole paragraph. For rejected-view insertion, copy exact rejected text and provide `anchor.occurrence`. |
+| `OVERLAPPING_SOURCE_TARGETS` / `OVERLAPPING_TEXT_EDITS` | Multiple complete text operations target the same batch-start source. | Consolidate all changes to that paragraph into one `redline` or `replace`; the library cannot choose between incompatible complete desired states. |
+| `REVISION_ORDER_CONFLICT` | A text rewrite and formatting/highlight operation overlap the same source. | Consolidate or split the work at an intentional created-content dependency; do not try a different arbitrary order. |
+| `CAPTURE_FANOUT_CONFLICT` | Multiple mutating consumers share one capture without distinct selectors. | Give consumers distinct selectors, chain them explicitly, or split the batch. |
+| `EXISTING_REVISIONS` | Target paragraph contains tracked changes from another author. | Fails closed to protect third-party review marks. If editing inside that reviewer's pending insertion is intended, pass `--existing-revisions slice-cross-author` (or `existingRevisions: 'slice-cross-author'`). Do not pass `accept-all-first` without explicit user authorization. |
+| `PATCH_ROUNDTRIP_MISMATCH` | A cross-author surgical edit did not reconstruct the requested modified text exactly. | Treat the operation as unapplied. Re-extract the exact paragraph text and split the edit into a narrower operation that does not cross the reported structural boundary. |
+| `FOREIGN_PARAGRAPH_MARK_DELETION` | A normal edit attempted to write into a paragraph wholly deleted by another reviewer. | Use an explicit `restore` operation if the user intends to counterpropose that paragraph; otherwise leave the deletion unresolved. |
+| `RESTORATION_STATE_REQUIRED` / `RESTORATION_COUNT_MISMATCH` | A `restore` target is not a wholly foreign-deleted paragraph, or its replacement count does not match the paragraph range. | Re-inspect the document and target the deleted paragraph by stable descriptor; provide exactly one replacement string per source paragraph. |
+| `REJECTED_INSERTION_STATE_REQUIRED` / `UNSAFE_REVISION_BOUNDARY` | An explicit rejected-view insertion did not resolve to supported plain run text inside a wholly foreign-deleted paragraph. | Do not fall back to a generic edit. Narrow the exact anchor/offset, or handle comments, bookmarks, fields, hyperlinks, moves, or other structural boundaries manually. |
+| `GENERATED_OOXML_INVALID` | The operation introduced a new validation error relative to its baseline. | Treat the operation as unapplied and inspect `generatedIssues`; correct the generating operation or builder rather than repairing or accepting the source document's unrelated baseline defects. |
+| `UNSAFE_DELETED_TABLE_ROW` / `UNSUPPORTED_MOVE_REVISION` / `SECTION_BREAK_PARAGRAPH` / `UNSAFE_PARAGRAPH_PLACEMENT` | Paragraph restoration cannot preserve the source structural boundary safely. | Do not retry as an ordinary redline. Resolve the row/move/section/placement condition manually or narrow the restoration to a safe paragraph. |
 | `COMMENTED_CONTENT_MERGE` / `COMMENTED_CONTENT_DELETE` | Operation would overwrite, revert, or delete content with comments. | Fails closed to prevent orphaned comment threads. Report the comment author and text to the user; resolve the comment before re-editing. |
-| `INVALID_OPERATION` | Operation object violates schema or has incompatible fields. | Validate the JSON structure against [`document-operations.schema.json`](schemas/document-operations.schema.json) before targeting is attempted. |
+| `INVALID_OPERATION` | Operation object violates schema or has incompatible fields. | Validate the JSON structure against [`document-operations.schema.json`](schemas/document-operations.schema.json) before targeting is attempted. |
 | `STRUCTURED_CONTENT_INVALID` | Malformed Markdown table or structure in replacement text. | Ensure tables include a separator row (`\| --- \| --- \|`) and consistent column counts; do not downgrade to raw text. |
 
 **Important Rule:** Never repeat the exact same failing command without correcting the reported cause. If an error persists after one correction attempt, stop and report the diagnostic code to the user.
@@ -763,12 +789,12 @@ import { reconcileMarkdownTableOoxml } from '@ansonlai/docx-redline-js';
 const result = await reconcileMarkdownTableOoxml(tableOoxml, originalText, markdownTable);
 ```
 
-## Detailed Architecture
-
-Use the layout and task shortcuts at the top of this file for normal work.
-`ARCHITECTURE.md` is the maintained detailed module-ownership map and describes
-the end-to-end dependency flow. Do not infer ownership from directory names or
-reconstruct the architecture by repeatedly listing the repository.
+## Detailed Architecture
+
+Use the layout and task shortcuts at the top of this file for normal work.
+`ARCHITECTURE.md` is the maintained detailed module-ownership map and describes
+the end-to-end dependency flow. Do not infer ownership from directory names or
+reconstruct the architecture by repeatedly listing the repository.
 
 ## Common Patterns
 
@@ -826,22 +852,22 @@ retain their string-only return type and return `''` for parse failures.
 
 ### Target text versus replacement text
 
-Target resolution may normalize surrounding or repeated whitespace while
-matching a paragraph. Replacement text is not normalized: tabs, line breaks,
-non-breaking spaces, repeated spaces, and leading/trailing whitespace become
-part of the requested edit. When editing extracted document text, copy the
-exact paragraph text and modify it in place rather than round-tripping it
-through a formatter that may change whitespace.
-
-The normalized caller target is never used for mutation offsets in a text-bearing
-edit. After target selection, the engine uses the resolved paragraph's byte-exact
-JavaScript string as the source coordinate system. The legacy format-only
-fallback for field-code paragraphs with no extractable accepted-view spans is
-not a text-replacement path. If an ASCII-space target selected an NBSP
-source, `resolvedTarget.targetTextMatch` reports `space_equivalent`, escaped
-source/request excerpts, and differing code points. An NBSP-to-space request is
-tracked as a replacement; it must not retain the NBSP and append another space.
-The CLI keeps these bounded diagnostics but removes resolved clause text.
+Target resolution may normalize surrounding or repeated whitespace while
+matching a paragraph. Replacement text is not normalized: tabs, line breaks,
+non-breaking spaces, repeated spaces, and leading/trailing whitespace become
+part of the requested edit. When editing extracted document text, copy the
+exact paragraph text and modify it in place rather than round-tripping it
+through a formatter that may change whitespace.
+
+The normalized caller target is never used for mutation offsets in a text-bearing
+edit. After target selection, the engine uses the resolved paragraph's byte-exact
+JavaScript string as the source coordinate system. The legacy format-only
+fallback for field-code paragraphs with no extractable accepted-view spans is
+not a text-replacement path. If an ASCII-space target selected an NBSP
+source, `resolvedTarget.targetTextMatch` reports `space_equivalent`, escaped
+source/request excerpts, and differing code points. An NBSP-to-space request is
+tracked as a replacement; it must not retain the NBSP and append another space.
+The CLI keeps these bounded diagnostics but removes resolved clause text.
 
 For ordinary insertions and deletions, target the visible accepted view:
 inserted `w:t` text is visible and deleted `w:delText` is not. Move revisions