@ansonlai/docx-redline-js 0.7.2 → 0.8.1

package/README.md

@@ -15,65 +15,65 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Comment management: delete comments by author or for all authors
 - Highlights: apply highlight colors to runs
 - Markdown and OOXML conversion in both directions
-- Status/error result fields for parse, targeting, and existing-revision failures
-- Localized exact replacements against inspected targets, plus optional fail-closed speculative CLI edits
-- Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
-- Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
-
-## What's New in 0.7.0
-
-Version 0.7.0 adds contract-8 localized edits. Agents can send a small
-`find`/`replace` request against an inspected target instead of reproducing a
-complete paragraph. An optional speculative form may omit the strong target
-when the source literal resolves uniquely; advanced scoping is described below.
-
-Speculative edits fail without writing when the anchor, paragraph, or source
-span is missing or ambiguous. Successful localized results include a committed
-`change` object with the selected legal location, bounded before/after excerpts,
-and actual accepted-view verification. Existing full-paragraph operations,
-tracked-change semantics, validation, rollback, and review policies remain
-available unchanged. See the [complete 0.7.0 release notes](./docs/releases/0.7.0.md).
+- Status/error result fields for parse, targeting, and existing-revision failures
+- Localized exact replacements against inspected targets, plus optional fail-closed speculative CLI edits
+- Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
+- Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
+
+## What's New in 0.7.0
+
+Version 0.7.0 adds contract-8 localized edits. Agents can send a small
+`find`/`replace` request against an inspected target instead of reproducing a
+complete paragraph. An optional speculative form may omit the strong target
+when the source literal resolves uniquely; advanced scoping is described below.
+
+Speculative edits fail without writing when the anchor, paragraph, or source
+span is missing or ambiguous. Successful localized results include a committed
+`change` object with the selected legal location, bounded before/after excerpts,
+and actual accepted-view verification. Existing full-paragraph operations,
+tracked-change semantics, validation, rollback, and review policies remain
+available unchanged. See the [complete 0.7.0 release notes](./docs/releases/0.7.0.md).
 ## Documentation Index
 
-| Document | Description |
-|---|---|
-| **[README.md](./README.md)** | Library overview, installation, quick start, and public API reference |
-| **[docs/AGENT_FAST_START.md](./docs/AGENT_FAST_START.md)** | Compact ordinary-edit protocol for structured tools and shell-only agents |
-| **[AGENTS.md](./AGENTS.md)** | Short repository launch card for task routing and contributor verification |
-| **[docs/AGENT_KNOWLEDGE_BASE.md](./docs/AGENT_KNOWLEDGE_BASE.md)** | Full agent reference, CLI workflow, operation examples, error recovery, options, and gotchas |
+| Document | Description |
+|---|---|
+| **[README.md](./README.md)** | Library overview, installation, quick start, and public API reference |
+| **[docs/AGENT_FAST_START.md](./docs/AGENT_FAST_START.md)** | Compact ordinary-edit protocol for structured tools and shell-only agents |
+| **[AGENTS.md](./AGENTS.md)** | Short repository launch card for task routing and contributor verification |
+| **[docs/AGENT_KNOWLEDGE_BASE.md](./docs/AGENT_KNOWLEDGE_BASE.md)** | Full agent reference, CLI workflow, operation examples, error recovery, options, and gotchas |
 | **[ARCHITECTURE.md](./ARCHITECTURE.md)** | Contributor architecture, module responsibilities, end-to-end data flow, and contracts |
 | **[docs/TESTING.md](./docs/TESTING.md)** | Complete testing guide, test lanes, independent oracle validation, and Word visual review checklist |
-| **[CHANGELOG.md](./CHANGELOG.md)** | Release history, breaking changes, and migration notes |
-
-## Repository Layout
-
-The package exposes three levels of API:
-
-| Level | Entry point | Use it for |
-|---|---|---|
-| Host-independent OOXML API | `index.js` | Paragraph/range transforms and exported OOXML utilities in browsers, Node.js, or another DOM-capable runtime |
-| Standalone document XML runner | `services/standalone-operation-runner.js` | Applying operations to a complete `word/document.xml` string |
-| Node/DOCX API and CLI | `node/index.js`, `bin/docx-redline.js` | Reading, changing, validating, and writing complete `.docx` ZIP packages |
-
-Implementation folders have distinct roles: `core/` holds shared OOXML and
-targeting primitives; `pipeline/` handles ingestion, diffing, markdown, lists,
-and serialization; `engine/` performs reconciliation; `services/` coordinates
-document operations and package artifacts; `node/` contains Node-only ZIP and
-whole-document code. Tests are directly runnable `tests/*.mjs` files, while
-`tests/helpers/` and `tests/fixtures/` contain support code and data.
-
-Contributors and coding agents should start with the routing table in
-[AGENTS.md](./AGENTS.md#pick-the-route) before exploring the tree. The full
-dependency and ownership map is in [ARCHITECTURE.md](./ARCHITECTURE.md).
-
-For document-operation JSON, choose operations by the desired output structure,
-not by the everyday meaning of the type name. `redline` and `replace` provide
-ordinary text replacement; `list-change` and `table-reconciliation` provide
-structural intent; and ordinary `insert` is a compatibility alias of the
-redline path unless it includes a rejected-view target and anchor. In every
-ordinary text-bearing operation, `modified` is the complete desired content for
-the target. See the [operation model](./docs/AGENT_KNOWLEDGE_BASE.md#operation-model-choose-by-output-shape)
-and the [JSON schema](./docs/schemas/document-operations.schema.json).
+| **[CHANGELOG.md](./CHANGELOG.md)** | Release history, breaking changes, and migration notes |
+
+## Repository Layout
+
+The package exposes three levels of API:
+
+| Level | Entry point | Use it for |
+|---|---|---|
+| Host-independent OOXML API | `index.js` | Paragraph/range transforms and exported OOXML utilities in browsers, Node.js, or another DOM-capable runtime |
+| Standalone document XML runner | `services/standalone-operation-runner.js` | Applying operations to a complete `word/document.xml` string |
+| Node/DOCX API and CLI | `node/index.js`, `bin/docx-redline.js` | Reading, changing, validating, and writing complete `.docx` ZIP packages |
+
+Implementation folders have distinct roles: `core/` holds shared OOXML and
+targeting primitives; `pipeline/` handles ingestion, diffing, markdown, lists,
+and serialization; `engine/` performs reconciliation; `services/` coordinates
+document operations and package artifacts; `node/` contains Node-only ZIP and
+whole-document code. Tests are directly runnable `tests/*.mjs` files, while
+`tests/helpers/` and `tests/fixtures/` contain support code and data.
+
+Contributors and coding agents should start with the routing table in
+[AGENTS.md](./AGENTS.md#pick-the-route) before exploring the tree. The full
+dependency and ownership map is in [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+For document-operation JSON, choose operations by the desired output structure,
+not by the everyday meaning of the type name. `redline` and `replace` provide
+ordinary text replacement; `list-change` and `table-reconciliation` provide
+structural intent; and ordinary `insert` is a compatibility alias of the
+redline path unless it includes a rejected-view target and anchor. In every
+ordinary text-bearing operation, `modified` is the complete desired content for
+the target. See the [operation model](./docs/AGENT_KNOWLEDGE_BASE.md#operation-model-choose-by-output-shape)
+and the [JSON schema](./docs/schemas/document-operations.schema.json).
 
 ## Install
 
@@ -159,23 +159,23 @@ import { inspectDocumentParts } from '@ansonlai/docx-redline-js';
 const inventory = inspectDocumentParts({ documentXml, commentsXml, numberingXml });
 ```
 
-Inspection returns exact paragraph text, target IDs/fingerprints, headings,
-table/list context, revision authors, and joined comment anchors. Filters such
-as `search`, `indexes`, `range`, `revisedOnly`, `inTable`, and `skipEmpty`
-limit output. Search is a case-insensitive substring match; `around` adds nearby drafting
-context, while `limit` and `after` page direct hits. When a search yields 0
-matches in the active view, `selection.hint` provides guidance if matches exist
-in the alternate revision view (such as searching for deleted text to restore).
-Compact `extract --revised` output retains revision authors and marks paragraphs
-whose content is wholly hidden in the selected view as `deleted` or `inserted`.
-One such paragraph can be restored without restating it:
-`docx-redline apply input.docx --restore --target-id ID --output reviewed.docx`.
-Add one exact `--find`/`--replace` pair to make a localized correction while
-restoring. The shortcut requires a strong rejected-view paragraph ID and does
-not infer a range or adjacent content.
-`revisionView` accepts `accepted`, `rejected`, or `current`. Returned
-paragraphs identify matches versus context and include `humanReference` for
-user-facing summaries.
+Inspection returns exact paragraph text, target IDs/fingerprints, headings,
+table/list context, revision authors, and joined comment anchors. Filters such
+as `search`, `indexes`, `range`, `revisedOnly`, `inTable`, and `skipEmpty`
+limit output. Search is a case-insensitive substring match; `around` adds nearby drafting
+context, while `limit` and `after` page direct hits. When a search yields 0
+matches in the active view, `selection.hint` provides guidance if matches exist
+in the alternate revision view (such as searching for deleted text to restore).
+Compact `extract --revised` output retains revision authors and marks paragraphs
+whose content is wholly hidden in the selected view as `deleted` or `inserted`.
+One such paragraph can be restored without restating it:
+`docx-redline apply input.docx --restore --target-id ID --output reviewed.docx`.
+Add one exact `--find`/`--replace` pair to make a localized correction while
+restoring. The shortcut requires a strong rejected-view paragraph ID and does
+not infer a range or adjacent content.
+`revisionView` accepts `accepted`, `rejected`, or `current`. Returned
+paragraphs identify matches versus context and include `humanReference` for
+user-facing summaries.
 
 For complete `.docx` buffers in Node:
 
@@ -188,69 +188,69 @@ const result = await document.applyOperations(operations, {
 const outputBuffer = result.toBuffer();
 ```
 
-The Node facade performs edits, artifact merges, package wiring, validation,
-and commit as one transaction. It defaults to strict targets and returns the
-untouched input with `written: false` on atomic failure. It is isolated from
-the root/browser dependency graph.
-
-Install `@xmldom/xmldom` alongside the package when using the Node facade or
-CLI; it remains an optional peer so browser consumers do not install a DOM shim.
-
-#### Example agent session wrapper (development only)
-
-[`examples/agent-session-wrapper.mjs`](./examples/agent-session-wrapper.mjs)
-demonstrates how a custom agent harness can keep one `DocxDocument` open, return
-short revision-bound target handles, apply safe defaults once, and translate a
-narrow edit request into canonical document operations:
-
-```js
-import { readFile } from 'node:fs/promises';
-import { createExampleAgentSession } from './examples/agent-session-wrapper.mjs';
-
-const session = createExampleAgentSession(await readFile('contract.docx'), {
-  profile: { author: 'Editor' }
-});
-const inspection = session.inspect({ search: 'termination', around: 2 });
-const clause = inspection.targets.find(target => target.role === 'match');
-const result = await session.applyEdits([{
-  target: clause.handle,
-  replacements: [{
-    find: 'The Company may terminate',
-    replace: 'Either party may terminate'
-  }]
-}]);
-```
-
-This file is a testable sample, not a package export or supported alternate
-mutation engine. It delegates to `@ansonlai/docx-redline-js/node`, is excluded
-from the published package files, and is intended to help MCP servers, Claude
-skills, OpenCode tools, and other custom harnesses design thin integrations.
-The sample binds each handle to the inspected package revision and view, returns
-new handles after successful mutations, and expands localized exact replacements
-into complete desired paragraph text before delegating to the canonical redline
-operation. Duplicate matches require an explicit `occurrence`; missing,
-ambiguous, overlapping, and conflicting patches fail before document mutation.
-From a source checkout, run `npm run benchmark:agent` to compare its native
-execution and serialized request size with a canonical stateless Node workflow.
-The example and its benchmark are excluded from the published package. The
-benchmark explicitly does not claim to measure LLM reasoning or provider/tool
-latency. Checked comparative results are in the
-[agent protocol rollout audit](./docs/validation-reports/2026-09-12-agent-protocol-rollout.md).
-
-> **Pre-1.0 integration warning:** Agent skills, MCP servers, and harnesses
-> should pin the exact `@ansonlai/docx-redline-js` release they were tested
-> against and declare the CLI contract version/capabilities they require. Do
-> not treat a newly installed release or contract as verified until the
-> integration's compatibility tests pass. See the
-> [skill-authoring contract](./docs/SKILL_AUTHORING.md#runtime-negotiation).
-
-### Agent CLI
-
-```bash
-# Default agent workflow: inspect once, then apply once
-docx-redline extract contract.docx --search "termination" --around 3
-node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
-```
+The Node facade performs edits, artifact merges, package wiring, validation,
+and commit as one transaction. It defaults to strict targets and returns the
+untouched input with `written: false` on atomic failure. It is isolated from
+the root/browser dependency graph.
+
+Install `@xmldom/xmldom` alongside the package when using the Node facade or
+CLI; it remains an optional peer so browser consumers do not install a DOM shim.
+
+#### Example agent session wrapper (development only)
+
+[`examples/agent-session-wrapper.mjs`](./examples/agent-session-wrapper.mjs)
+demonstrates how a custom agent harness can keep one `DocxDocument` open, return
+short revision-bound target handles, apply safe defaults once, and translate a
+narrow edit request into canonical document operations:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { createExampleAgentSession } from './examples/agent-session-wrapper.mjs';
+
+const session = createExampleAgentSession(await readFile('contract.docx'), {
+  profile: { author: 'Editor' }
+});
+const inspection = session.inspect({ search: 'termination', around: 2 });
+const clause = inspection.targets.find(target => target.role === 'match');
+const result = await session.applyEdits([{
+  target: clause.handle,
+  replacements: [{
+    find: 'The Company may terminate',
+    replace: 'Either party may terminate'
+  }]
+}]);
+```
+
+This file is a testable sample, not a package export or supported alternate
+mutation engine. It delegates to `@ansonlai/docx-redline-js/node`, is excluded
+from the published package files, and is intended to help MCP servers, Claude
+skills, OpenCode tools, and other custom harnesses design thin integrations.
+The sample binds each handle to the inspected package revision and view, returns
+new handles after successful mutations, and expands localized exact replacements
+into complete desired paragraph text before delegating to the canonical redline
+operation. Duplicate matches require an explicit `occurrence`; missing,
+ambiguous, overlapping, and conflicting patches fail before document mutation.
+From a source checkout, run `npm run benchmark:agent` to compare its native
+execution and serialized request size with a canonical stateless Node workflow.
+The example and its benchmark are excluded from the published package. The
+benchmark explicitly does not claim to measure LLM reasoning or provider/tool
+latency. Checked comparative results are in the
+[agent protocol rollout audit](./docs/validation-reports/2026-09-12-agent-protocol-rollout.md).
+
+> **Pre-1.0 integration warning:** Agent skills, MCP servers, and harnesses
+> should pin the exact `@ansonlai/docx-redline-js` release they were tested
+> against and declare the CLI contract version/capabilities they require. Do
+> not treat a newly installed release or contract as verified until the
+> integration's compatibility tests pass. See the
+> [skill-authoring contract](./docs/SKILL_AUTHORING.md#runtime-negotiation).
+
+### Agent CLI
+
+```bash
+# Default agent workflow: inspect once, then apply once
+docx-redline extract contract.docx --search "termination" --around 3
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
+```
 
 ```bash
 # Inline one-liner edit (no operations file needed)
@@ -262,76 +262,78 @@ docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --n
 # Cross-author edit inside another reviewer's pending insertion
 docx-redline apply contract.docx --target "Another author's clause" --modified "Revised clause" --existing-revisions slice-cross-author --output reviewed.docx
 
-# High-assurance atomic batch with nonzero exit on any incomplete result
-docx-redline apply contract.docx --operations operations.json --atomic --require-complete --output reviewed.docx
-
-# Optional read-only audit before a deliberately staged batch
-docx-redline preflight contract.docx --operations operations.json --author "Editor"
-```
+# High-assurance atomic batch with nonzero exit on any incomplete result
+docx-redline apply contract.docx --operations operations.json --atomic --require-complete --output reviewed.docx
+
+# Optional read-only audit before a deliberately staged batch
+docx-redline preflight contract.docx --operations operations.json --author "Editor"
+```
 
-All commands emit JSON on stdout. `apply` defaults:
+All commands emit JSON on stdout. `apply` defaults:
 - **Author**: Defaults to `'AI Redliner'` (or `DOCX_REDLINE_AUTHOR` environment variable).
 - **Output overwrite**: Destination files provided via `--output` overwrite by default. Pass `--no-overwrite` or `--no-clobber` to safeguard existing destination files. The source input is never overwritten unless `--in-place` is specified.
 - **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.
-- **Transactionality**: Defaults to `atomic: false` (applies valid operations and reports any failures). Pass `--atomic` for all-or-nothing rollback on any operation error.
-- **Complete-success exit**: Pass `--require-complete` when a progressive `partial` result must exit with code `3`; errors exit with code `2`. Without the flag, partial results retain the legacy zero exit code, so always inspect `completion`.
-- **Agent profile**: `--profile agent` enables complete-success exit behavior while retaining the ordinary progressive transaction and existing-revision defaults. Compose it with `--atomic` or an explicit `--existing-revisions` policy when intended, and verify the resolved `effectiveOptions`.
-- **Operations from stdin**: `--operations -` reads the same array or `{ operations, expectedRevision }` envelope accepted from a file. Feed it from a JSON serializer or structured process API, not shell-interpolated legal text.
-- **Compact stdout**: `--compact` emits one-line mutation JSON. It changes serialization only, not operation semantics.
+- **Transactionality**: Defaults to `atomic: false` (applies valid operations and reports any failures). Pass `--atomic` for all-or-nothing rollback on any operation error.
+- **Complete-success exit**: Pass `--require-complete` when a progressive `partial` result must exit with code `3`; errors exit with code `2`. Without the flag, partial results retain the legacy zero exit code, so always inspect `completion`.
+- **Agent profile**: `--profile agent` enables complete-success exit behavior while retaining the ordinary progressive transaction and existing-revision defaults. Compose it with `--atomic` or an explicit `--existing-revisions` policy when intended, and verify the resolved `effectiveOptions`.
+- **Operations from stdin**: `--operations -` reads the same array or `{ operations, expectedRevision }` envelope accepted from a file. Feed it from a JSON serializer or structured process API, not shell-interpolated legal text.
+- **Compact stdout**: `--compact` emits one-line mutation JSON. It changes serialization only, not operation semantics.
 - **Tracked changes**: Defaults to `generateRedlines: true`. Pass `--no-redlines` when clean direct text edits are desired.
-- **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
-- **Localized edits**: After extraction, use `replacements` with the inspected `paragraphId` plus `fingerprint` to avoid restating a long paragraph. Retain `exactText` locally for drafting. Targetless `--find`/`--replace` is an optional speculative path described below.
-- **Invisible spaces**: Localized matching is case-sensitive and tries exact text first. If no exact span exists, ordinary spaces may match DOCX non-breaking spaces; ambiguous equivalent matches still fail closed, and `change.replacements[i].matchMode` reports `space_equivalent` when used.
-- **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. CLI operation results omit duplicate nested receipt bodies; the ordered top-level `receipts` array is authoritative. Successful exact target-match diagnostics are omitted and equivalent-whitespace matches retain only mode/count. Node and standalone-runner results remain unchanged. Use `validate` when full issue arrays are needed.
-
-Inspection commands default to 20 direct matches and a 48 KiB soft response
-budget when no explicit positional scope is supplied. When a search returns 0
-matches in the requested view, `selection.hint` provides immediate guidance if
-matches exist in the alternate view (such as searching for a deleted clause to
-restore). Use `--limit` with `--after <paragraph-index>` to continue, `--around N`
-(aliases `--context` and `-C`) to include nearby paragraphs, and `--all` only
-for deliberate unbounded inspection. Every retained target is complete; an
-individually oversized paragraph is returned whole with an `oversizeItem`
-marker. Machine `index` and `ref` fields are for targeting and pagination, not
-user-facing Word locations; use `humanReference`, `provision`, or
-`nearestHeading` in reports.
-
-`docx-redline version` reports contract version 8 and the additive
-`command-help-v1`, `inspection-context-v1`, `bounded-inspection-v1`,
-`human-document-references-v1`, `batch-start-source-binding`,
-`recovery-envelope-v1`, `require-complete-exit`, `operations-stdin`,
-`agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
-`compact-cli-json-v1`, `localized-replacements-v1`,
-`speculative-search-apply-v1`, `localized-change-summary-v1`, and
-`restore-shortcuts-v1`, plus `localized-space-equivalence-v1` capabilities.
-Wrappers should negotiate only the
-capabilities they use. Run `docx-redline <command> --help` for that command's
-machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
-
-#### Optional speculative CLI path
-
-Harnesses with a measured confidence policy may attempt a targetless localized
-edit. This is not the default 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 nearby 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
-```
-
-Generic or repeated anchors can widen the unioned scope until multiple
-paragraphs contain `find`, causing a safe `AMBIGUOUS_TARGET` failure and a
-recovery turn. `--around 3` is symmetric. On success,
-`change.context.anchorMatchCount > 1` signals a repeated anchor; confirm the
-returned location and bounded evidence. Matching remains case-sensitive and
-exact-first, with a narrow ordinary-space/NBSP fallback that still refuses
-ambiguity.
-
-See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
-[skill/harness authoring contract](./docs/SKILL_AUTHORING.md), and the
-[operation JSON Schema](docs/schemas/document-operations.schema.json).
+- **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
+- **Localized edits**: After extraction, use `replacements` with the inspected `paragraphId` plus `fingerprint` to avoid restating a long paragraph. Retain `exactText` locally for drafting. Targetless `--find`/`--replace` is an optional speculative path described below.
+- **Invisible spaces**: Localized matching is case-sensitive and tries exact text first. If no exact span exists, ordinary spaces may match DOCX non-breaking spaces; ambiguous equivalent matches still fail closed, and `change.replacements[i].matchMode` reports `space_equivalent` when used.
+- **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. CLI operation results omit duplicate nested receipt bodies; the ordered top-level `receipts` array is authoritative. Successful exact target-match diagnostics are omitted and equivalent-whitespace matches retain only mode/count. Node and standalone-runner results remain unchanged. Use `validate` when full issue arrays are needed.
+
+Inspection commands default to 20 direct matches and a 48 KiB soft response
+budget when no explicit positional scope is supplied. When a search returns 0
+matches in the requested view, `selection.hint` provides immediate guidance if
+matches exist in the alternate view (such as searching for a deleted clause to
+restore). Use `--limit` with `--after <paragraph-index>` to continue, `--around N`
+(aliases `--context` and `-C`) to include nearby paragraphs, and `--all` only
+for deliberate unbounded inspection. Every retained target is complete; an
+individually oversized paragraph is returned whole with an `oversizeItem`
+marker. Machine `index` and `ref` fields are for targeting and pagination, not
+user-facing Word locations; use `humanReference`, `provision`, or
+`nearestHeading` in reports.
+
+`docx-redline version` reports contract version 8 and the additive
+`command-help-v1`, `inspection-context-v1`, `bounded-inspection-v1`,
+`human-document-references-v1`, `batch-start-source-binding`,
+`recovery-envelope-v1`, `require-complete-exit`, `operations-stdin`,
+`agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
+`compact-cli-json-v1`, `localized-replacements-v1`,
+`speculative-search-apply-v1`, `localized-change-summary-v1`, and
+`restore-shortcuts-v1`, plus `localized-space-equivalence-v1` capabilities. Header/footer
+`part` targeting, the `comment_resolve` operation and `delete-comments --comment-id` are advertised as
+`header-footer-parts-v1`, `comment-resolve-operation-v1` and `delete-comments-by-id-v1`.
+Wrappers should negotiate only the
+capabilities they use. Run `docx-redline <command> --help` for that command's
+machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
+
+#### Optional speculative CLI path
+
+Harnesses with a measured confidence policy may attempt a targetless localized
+edit. This is not the default 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 nearby 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
+```
+
+Generic or repeated anchors can widen the unioned scope until multiple
+paragraphs contain `find`, causing a safe `AMBIGUOUS_TARGET` failure and a
+recovery turn. `--around 3` is symmetric. On success,
+`change.context.anchorMatchCount > 1` signals a repeated anchor; confirm the
+returned location and bounded evidence. Matching remains case-sensitive and
+exact-first, with a narrow ordinary-space/NBSP fallback that still refuses
+ambiguity.
+
+See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
+[skill/harness authoring contract](./docs/SKILL_AUTHORING.md), and the
+[operation JSON Schema](docs/schemas/document-operations.schema.json).
 
 ### Configuration (call once at startup)
 
@@ -365,10 +367,10 @@ Common result fields:
 | Field | Purpose |
 |-------|---------|
 | `status` | Operation status: `'ok'`, `'partial'`, `'no-op'`, or `'error'`. |
-| `error` | Present on failure; retains a stable `code` and adds recovery envelope version, stage, category, bounded context, and a machine-readable recovery action. |
-| `written` | CLI/facade boolean indicating whether the output file was successfully written to disk. |
-| `completion` | CLI-only boolean that is `true` only when a destination was written, top-level status is neither error nor partial, and no operation result failed. |
-| `rolledBack` | Present and `true` when an atomic batch encountered an error and rolled back all changes. |
+| `error` | Present on failure; retains a stable `code` and adds recovery envelope version, stage, category, bounded context, and a machine-readable recovery action. |
+| `written` | CLI/facade boolean indicating whether the output file was successfully written to disk. |
+| `completion` | CLI-only boolean that is `true` only when a destination was written, top-level status is neither error nor partial, and no operation result failed. |
+| `rolledBack` | Present and `true` when an atomic batch encountered an error and rolled back all changes. |
 
 Word diffs are deterministic by default (no wall-clock timeout). Inputs above
 the safe ceiling of 262,144 unique diff tokens return `DIFF_TOKEN_LIMIT` with
@@ -380,11 +382,11 @@ silent text loss.
 During multi-round legal negotiations, a reviewer often needs to edit text that was previously inserted by another reviewer whose revision is still pending. Pass `existingRevisions: 'slice-cross-author'` (or `--existing-revisions slice-cross-author` via CLI) to edit inside another author's pending insertion without erasing their attribution or requiring prior acceptance:
 
 ```js
-const result = await applyRedlineToOxml(paragraphOoxml, originalText, modifiedText, {
-  generateRedlines: true,
-  author: 'Reviewer B',
-  existingRevisions: 'slice-cross-author'
-});
+const result = await applyRedlineToOxml(paragraphOoxml, originalText, modifiedText, {
+  generateRedlines: true,
+  author: 'Reviewer B',
+  existingRevisions: 'slice-cross-author'
+});
 ```
 
 The engine applies Microsoft Word Desktop-native tracked change structures:
@@ -497,25 +499,25 @@ an earlier block has already replaced.
 | `ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXml)` | Add or replace modern Word comment-thread metadata in a `.docx` package. |
 | `validateDocxPackage(zip)` | Validate `.docx` structural consistency. |
 
-Malformed OOXML never escapes these public transform APIs as a raw parser
-exception. Transforms return `status: 'error'` with `error.code === 'PARSE_ERROR'`;
-validators return a `PARSE_ERROR` issue. Recoverable XML parser
-diagnostics are forwarded through the configured logger and included in
-`warnings` where the result shape supports them.
-
-Cross-author slicing also verifies its exact accepted-view text before success.
-If a structural boundary prevents exact reconstruction, the transform returns
-`status: 'error'` with `error.code === 'PATCH_ROUNDTRIP_MISMATCH'`,
-`hasChanges: false`, and the original OOXML unchanged.
-Pure insertion-only slicing uses an exact character-local diff so repeated words
-cannot move an insertion to a different occurrence. Leading/trailing spaces,
-tabs, and non-breaking spaces are treated as real changes rather than no-ops.
-For text-bearing replacements, the exact accepted-view text of the resolved
-paragraph—not a space-normalized caller target—defines mutation offsets. Word-level replacement
-hunks that differ only by ordinary spaces and NBSPs are refined to character
-edits so unchanged hyperlinks and their relationship attributes stay in place.
-Runner results expose bounded `resolvedTarget.targetTextMatch` code-point
-diagnostics when equivalent whitespace was used to identify the target.
+Malformed OOXML never escapes these public transform APIs as a raw parser
+exception. Transforms return `status: 'error'` with `error.code === 'PARSE_ERROR'`;
+validators return a `PARSE_ERROR` issue. Recoverable XML parser
+diagnostics are forwarded through the configured logger and included in
+`warnings` where the result shape supports them.
+
+Cross-author slicing also verifies its exact accepted-view text before success.
+If a structural boundary prevents exact reconstruction, the transform returns
+`status: 'error'` with `error.code === 'PATCH_ROUNDTRIP_MISMATCH'`,
+`hasChanges: false`, and the original OOXML unchanged.
+Pure insertion-only slicing uses an exact character-local diff so repeated words
+cannot move an insertion to a different occurrence. Leading/trailing spaces,
+tabs, and non-breaking spaces are treated as real changes rather than no-ops.
+For text-bearing replacements, the exact accepted-view text of the resolved
+paragraph—not a space-normalized caller target—defines mutation offsets. Word-level replacement
+hunks that differ only by ordinary spaces and NBSPs are refined to character
+edits so unchanged hyperlinks and their relationship attributes stay in place.
+Runner results expose bounded `resolvedTarget.targetTextMatch` code-point
+diagnostics when equivalent whitespace was used to identify the target.
 
 ### Deep Imports
 
@@ -531,17 +533,17 @@ import {
 import { getParagraphText } from '@ansonlai/docx-redline-js/core/paragraph-targeting.js';
 ```
 
-Use `applyOperationsToDocumentXml(...)` for mixed batches. It stably runs comments before text-changing operations so replacements cannot invalidate their original anchors. Other operation types retain their relative order. Batch results retain each operation's original 1-based index and expose the actual `executionOrder`.
-
-Before mutation, the runner resolves strong source descriptors against the
-immutable batch-start document and binds them to session-local source
-identities. Independent edits therefore do not need to be manually sorted when
-an earlier structural rewrite changes later paragraph indexes or fingerprints.
-Targets that deliberately refer to uniquely created paragraph text are compiled
-into an internal capture dependency. True overlap is not guessed: incompatible
-writes to one source fail before mutation with `OVERLAPPING_SOURCE_TARGETS` or
-`REVISION_ORDER_CONFLICT`, and mutating capture fan-out without distinct
-selectors fails with `CAPTURE_FANOUT_CONFLICT`.
+Use `applyOperationsToDocumentXml(...)` for mixed batches. It stably runs comments before text-changing operations so replacements cannot invalidate their original anchors. Other operation types retain their relative order. Batch results retain each operation's original 1-based index and expose the actual `executionOrder`.
+
+Before mutation, the runner resolves strong source descriptors against the
+immutable batch-start document and binds them to session-local source
+identities. Independent edits therefore do not need to be manually sorted when
+an earlier structural rewrite changes later paragraph indexes or fingerprints.
+Targets that deliberately refer to uniquely created paragraph text are compiled
+into an internal capture dependency. True overlap is not guessed: incompatible
+writes to one source fail before mutation with `OVERLAPPING_SOURCE_TARGETS` or
+`REVISION_ORDER_CONFLICT`, and mutating capture fan-out without distinct
+selectors fails with `CAPTURE_FANOUT_CONFLICT`.
 
 Threaded replies use a comment operation with no body target:
 
@@ -550,9 +552,29 @@ Threaded replies use a comment operation with no body target:
 ```
 
 For complete `.docx` files, use `openDocx(...).applyOperations(...)`; it reads
-the existing comments parts and writes the required `commentsExtended.xml`
-relationship and content type. Inspection reports `paraId` and
-`parentCommentId` so callers can discover and verify the thread hierarchy.
+the existing comments parts, writes the required `commentsExtended.xml`
+relationship and content type, adds the reply's own range/reference markers to the body
+(Word does not display a reply without them), and keeps `commentsIds.xml` and
+`commentsExtensible.xml` in step when they exist. Inspection reports `paraId`, `parentCommentId` and `done`
+so callers can discover and verify the thread hierarchy.
+
+Resolve or reopen a thread with an operation (usable from the CLI through `apply --operations`) or the API:
+
+```js
+{ type: 'comment_resolve', commentId: 8 }                  // resolve
+{ type: 'comment_resolve', commentId: 8, resolved: false } // reopen
+await doc.resolveComment(8, { resolved: true });
+```
+
+Resolved is a thread-level state in Word, so any id in the thread updates the root and all replies. Delete
+specific comments with `doc.deleteComments({ ids: [8] })` or `docx-redline delete-comments file.docx --comment-id 8`;
+deleting a thread root also deletes its replies.
+
+Headers and footers are edited by adding `part` to an operation: `{ type: 'replace', part: { kind: 'footer' }, target: { exactText: 'Draft v1' }, modified: 'Draft v2' }`.
+`openDocx(...).inspect().headersFooters` lists the parts (path, kind, type, sections, text, whether they contain
+fields). Fields such as `PAGE` are treated as atomic, comments are not allowed in headers or footers, and `accept`/`reject`
+also resolve revisions inside them. Creating a header or footer that does not exist is not supported; see
+[Known limitations](docs/plans/KNOWN_BUGS.md#4-headers-and-footers).
 
 A whole-paragraph `delete` that targets existing comment markup fails with
 `COMMENTED_CONTENT_DELETE`. In the Node facade and CLI, the error also includes
@@ -564,23 +586,23 @@ serialization. Accuracy remains the controlling constraint: each operation has
 an internal savepoint so an error or no-op cannot leak a partial edit or consumed
 revision ID into later operations.
 
-Batches are progressive by default (`atomic: false`): valid operations commit
-while failed operations remain unapplied and are reported in `results`. Pass
-`{ atomic: true }` when any operation error must return the original
-`documentXml`, `hasChanges: false`, empty package artifacts, and
-`rolledBack: true`. The default `continueOnError: true` still attempts the full
-batch so `results` describes every operation; use `{ continueOnError: false }`
-to stop after the first error.
-
-Every failed or partial mutation includes `retryPlan`. Its `base` is `original`
-after rollback/no commit and `output` after a progressive partial commit;
-`committedIndexes`, `failedIndexes`, and `unattemptedIndexes` identify the safe
-replay scope. Errors use recovery envelope version 1 and always report
-`sameArgumentsSafe: false`. Follow `error.recovery.action`; do not infer a retry
-from prose. Authorization-sensitive actions, such as resolving comments, are
-marked with `requiresUserAuthorization: true`. For `EXISTING_REVISIONS`, the
-non-normalizing surgical recommendation is `slice-cross-author`; accepting or
-rejecting prior revisions still requires explicit authority.
+Batches are progressive by default (`atomic: false`): valid operations commit
+while failed operations remain unapplied and are reported in `results`. Pass
+`{ atomic: true }` when any operation error must return the original
+`documentXml`, `hasChanges: false`, empty package artifacts, and
+`rolledBack: true`. The default `continueOnError: true` still attempts the full
+batch so `results` describes every operation; use `{ continueOnError: false }`
+to stop after the first error.
+
+Every failed or partial mutation includes `retryPlan`. Its `base` is `original`
+after rollback/no commit and `output` after a progressive partial commit;
+`committedIndexes`, `failedIndexes`, and `unattemptedIndexes` identify the safe
+replay scope. Errors use recovery envelope version 1 and always report
+`sameArgumentsSafe: false`. Follow `error.recovery.action`; do not infer a retry
+from prose. Authorization-sensitive actions, such as resolving comments, are
+marked with `requiresUserAuthorization: true`. For `EXISTING_REVISIONS`, the
+non-normalizing surgical recommendation is `slice-cross-author`; accepting or
+rejecting prior revisions still requires explicit authority.
 
 Comment anchors use exact matching first, then a unique ASCII-space/NBSP
 equivalent match that preserves source offsets and text. Missing anchors return
@@ -632,14 +654,14 @@ guidance. Callers should pass `{ strictTargets: true }` and use strict descripto
 
 ### Mutation Receipts
 
-Both single-operation (`applyOperationToDocumentXml`) and batch
-(`applyOperationsToDocumentXml`) results expose commit-aware **Mutation Receipts**
-(`result.receipt` on single results and per-item `results[i].receipt`, plus `result.receipts`
-for the full batch).
-
-This full receipt shape is retained by the Node facade and standalone runner.
-Only compact CLI JSON removes duplicate `results[i].receipt` bodies and keeps
-the ordered top-level `receipts` array.
+Both single-operation (`applyOperationToDocumentXml`) and batch
+(`applyOperationsToDocumentXml`) results expose commit-aware **Mutation Receipts**
+(`result.receipt` on single results and per-item `results[i].receipt`, plus `result.receipts`
+for the full batch).
+
+This full receipt shape is retained by the Node facade and standalone runner.
+Only compact CLI JSON removes duplicate `results[i].receipt` bodies and keeps
+the ordered top-level `receipts` array.
 
 ```js
 const result = await applyOperationsToDocumentXml(documentXml, operations, 'Agent');
@@ -715,49 +737,49 @@ import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/standalon
 const zip = await JSZip.loadAsync(docxBuffer);
 const documentXml = await zip.file('word/document.xml').async('string');
 
-const opResult = await applyOperationToDocumentXml(
+const opResult = await applyOperationToDocumentXml(
   documentXml,
   { type: 'redline', target: 'old text', modified: 'new text' },
   'Editor'
-);
-
-// Restoring another reviewer's pending whole-paragraph deletion requires
-// explicit intent. The restored counterproposal becomes a separately tracked
-// sibling paragraph; a normal redline operation remains fail-closed.
-const restoration = await applyOperationToDocumentXml(
-  documentXml,
-  {
-    type: 'restore',
-    // restore targets default to the rejected view, where deleted text exists
-    target: { paragraphId: '1A2B3C4D', exactText: 'Original deleted paragraph text.' },
-    modified: 'Restored or adjusted paragraph text.'
-  },
-  'Editor'
-);
-
-// A single restoration follows its deleted source paragraph. A range
-// restoration follows the complete deleted source block. Unchanged legacy
-// validation defects are retained as baseline issues; newly generated errors
-// fail closed before commit.
-// inspect/extract descriptors report their revisionView, and each fingerprint
-// is computed from the same view as exactText. Keep those fields together.
-
-// To insert run-level text at a location visible only in the rejected view,
-// provide explicit rejected-view intent and an exact anchor-relative offset.
-const deletedTextInsertion = await applyOperationToDocumentXml(
-  documentXml,
-  {
-    type: 'insert',
-    target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
-    anchor: { exactText: 'must pay', occurrence: 1, offset: 5 },
-    modified: '[clarification] ',
-    existingRevisions: 'slice-cross-author'
-  },
-  'Editor'
-);
+);
+
+// Restoring another reviewer's pending whole-paragraph deletion requires
+// explicit intent. The restored counterproposal becomes a separately tracked
+// sibling paragraph; a normal redline operation remains fail-closed.
+const restoration = await applyOperationToDocumentXml(
+  documentXml,
+  {
+    type: 'restore',
+    // restore targets default to the rejected view, where deleted text exists
+    target: { paragraphId: '1A2B3C4D', exactText: 'Original deleted paragraph text.' },
+    modified: 'Restored or adjusted paragraph text.'
+  },
+  'Editor'
+);
+
+// A single restoration follows its deleted source paragraph. A range
+// restoration follows the complete deleted source block. Unchanged legacy
+// validation defects are retained as baseline issues; newly generated errors
+// fail closed before commit.
+// inspect/extract descriptors report their revisionView, and each fingerprint
+// is computed from the same view as exactText. Keep those fields together.
+
+// To insert run-level text at a location visible only in the rejected view,
+// provide explicit rejected-view intent and an exact anchor-relative offset.
+const deletedTextInsertion = await applyOperationToDocumentXml(
+  documentXml,
+  {
+    type: 'insert',
+    target: { paragraphId: '1A2B3C4D', revisionView: 'rejected' },
+    anchor: { exactText: 'must pay', occurrence: 1, offset: 5 },
+    modified: '[clarification] ',
+    existingRevisions: 'slice-cross-author'
+  },
+  'Editor'
+);
 
 // applyOperationToDocumentXml(...) returns a full w:document payload.
-zip.file('word/document.xml', opResult.documentXml);
+zip.file('word/document.xml', opResult.documentXml);
 
 const fragmentResult = await applyRedlineToOxml(
   paragraphOoxml,
@@ -840,10 +862,10 @@ invariant with a fresh seed. See [Release validation in docs/TESTING.md](./docs/
 
 ## Architecture & Contributing
 
-- **[ARCHITECTURE.md](./ARCHITECTURE.md)**: Detailed module layout, end-to-end reconciliation flow, and contributor fast orientation.
-- **[AGENTS.md](./AGENTS.md)**: Fast-start routing and operational guardrails for AI coding agents.
-- **[docs/AGENT_FAST_START.md](./docs/AGENT_FAST_START.md)**: Minimal ordinary-edit contract for agent integrations.
-- **[docs/AGENT_KNOWLEDGE_BASE.md](./docs/AGENT_KNOWLEDGE_BASE.md)**: Full agent reference for APIs, operations, CLI automation, recovery, and gotchas.
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)**: Detailed module layout, end-to-end reconciliation flow, and contributor fast orientation.
+- **[AGENTS.md](./AGENTS.md)**: Fast-start routing and operational guardrails for AI coding agents.
+- **[docs/AGENT_FAST_START.md](./docs/AGENT_FAST_START.md)**: Minimal ordinary-edit contract for agent integrations.
+- **[docs/AGENT_KNOWLEDGE_BASE.md](./docs/AGENT_KNOWLEDGE_BASE.md)**: Full agent reference for APIs, operations, CLI automation, recovery, and gotchas.
 - **[docs/TESTING.md](./docs/TESTING.md)**: Comprehensive testing model, test lanes, independent oracle checks, and visual review checklist.
 - **[CHANGELOG.md](./CHANGELOG.md)**: Version history, migration guides, and deprecation schedules.