@ansonlai/docx-redline-js 0.8.3 → 0.9.0

package/docs/AGENT_FAST_START.md

@@ -41,6 +41,8 @@ If the user requests deleted text, search with `--view rejected` first. Otherwis
 
 - Require `completion: true` and a non-null `outputPath`; the CLI computes this from write, operation, commit, and localized-verification results.
 - On failure, follow `error.recovery.action`; never retry unchanged arguments.
+- `REVISION_FIDELITY_VIOLATION` (Reject All would not restore the source): retry
+  narrower per `recovery.retryGuidance`; never pass `--revision-fidelity off`.
 - Use `retryPlan.base: "original"` to replay a batch and `"output"` to retain
   committed progressive work and retry the reported indexes.
 - The source is not overwritten unless `--in-place` is explicit.

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -462,10 +462,14 @@ fragment to insert. Do not choose a type from its English name alone.
 |---|---|
 | 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>' }` |
+| Change native list structure | `{ type: 'list-change', target, modified: '<complete Markdown list>' }`. It inserts, removes and nests items; it never changes the list's kind or numbering format (retyped markers warn `LIST_FORMAT_NOT_APPLIED` or fail `UNSUPPORTED_LIST_FORMAT_CHANGE` with a `change-format` `suggestedOperation`): use `list-format` `change-format` for that |
 | 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` |
+| Change character or paragraph formatting | `character-format`/`format` with `textToFormat` and `properties`, or `paragraph-format` with `properties`; add `textOccurrence` (1-based, default 1) to format a later match of `textToFormat` inside the targeted paragraph (out of range fails `PATCH_SOURCE_NOT_FOUND`; independent of `target.occurrence`, which selects the paragraph; legacy calls without `textOccurrence` still read `target.occurrence`; capability `format-text-occurrence-v1`) |
+| Put an existing paragraph in (or out of) an existing list | `{ type: 'paragraph-format', target, properties: { numbering: { numId, level } } }` with `numId`/`level` copied from an inspected list paragraph of the target list, or `numbering: null` to remove the paragraph's direct list binding. A tracked `w:pPrChange` keeps the previous `w:numPr`, so Reject All restores the old membership and Accept All shows the new one. It binds only: it never creates a list, marker text is not stripped, and sibling numbering is not remapped. Refused `PARAGRAPH_NUMBERING_NOT_FOUND` (unknown `numId` or undefined level) and `PARAGRAPH_FORMAT_REVISION_CONFLICT` (another author's pending paragraph-property change). Capability `paragraph-numbering-binding-v1` |
+| Turn typed headers (`A.`, `1.`, `I.`, `-` typed as text) into a real list | `{ type: 'list-format', target, targetEnd?, list: { mode: 'convert-plain' } }` on the plain paragraphs that carry the typed markers. Each marker becomes a tracked deletion and the paragraph a list item with that label (tracked `w:pPrChange`, same paragraph); the marker's value is the start value, consecutive markers share one list, body paragraphs in the range stay plain, and a later `list-format` in the batch continuing the count joins the list. A lone `I.`/`C.` is ambiguous (letter or roman): pass `list.format`. `strip: 'none'` with `format` (and `start`) binds a paragraph without a typed marker and leaves its text alone. Do not express this as a `redline` that adds or keeps marker text. A changed-text header (`1. Old` -> `1. New`) is a `redline` of that paragraph that keeps the typed marker exactly (`modified: '1. New'`, or `replacements`) plus this `list-format` in the same batch, in either order: the redline runs first and the list-format strips the unchanged marker, so Accept All shows label `1.` with `New` and Reject All the literal `1. Old`. A redline in that batch that adds, removes or changes the marker, spans paragraphs, or leaves the text unchanged is refused before mutation (`LIST_FORMAT_COMPOSITION_CONFLICT`). Capability `list-format-v1` (contract version 9) |
+| Change a list's kind or numbering style (bullets to `1.`, `1.` to `A.`, a nested level to `(i)`) | `{ type: 'list-format', target, list: { mode: 'change-format', format, lvlText?, level?, start?, scope? } }` with `target` on any item of the list. A NEW definition is allocated (levels, indentation and fonts copied from the list; only `level`, default the target's level, is redefined) and every item is rebound with a tracked `w:pPrChange`: Reject All restores the old labels, Accept All shows the new ones; the shared definition is never edited. `scope: 'list'` (default) rebinds every item, including items outside `target` (`result.list.items[].inTarget`); `scope: 'range'` with `targetEnd` changes only a range that runs to the end of the list and continues its count. `lvlText` keeps the source text unless given (`"%1."`, `"(%2)"`; a bullet's character). Do not express this as a `list-change`/`redline` that retypes the markers. `scope: 'list'` counts as a write to every item it rebinds: in the same batch each of those items may also carry one single-paragraph `redline` that adds no marker (it runs first); any other write to them fails `LIST_FORMAT_COMPOSITION_CONFLICT` (`reason: list-rebind`), so send it in a separate apply or use `scope: 'range'`. Capability `list-format-change-v1` (contract version 9) |
+| Make a list continue an earlier list (`1. 2.` / `1. 2.` -> `1. 2.` / `3. 4.`) | `{ type: 'list-format', target, list: { mode: 'join', continueFrom: { paragraphId, fingerprint } } }` with `target` on the later list and `continueFrom` on an item of the earlier one; items keep their levels and take the earlier list's format. `scope: 'range'` joins only a range that runs to the end of the later list. Capability `list-format-change-v1` |
 | 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'` |
 
@@ -514,6 +518,9 @@ revision markup internally before writing, so do not add `preflight` or baseline
 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.
+   Paragraphs with soft line breaks (`\n` in `exactText`) accept `replacements`
+   whose `find` lies within one line; the breaks are preserved. A `find` or
+   `replace` that spans or adds a line break is refused.
 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.
@@ -767,13 +774,25 @@ When the CLI or runner returns an error code, follow these specific recovery act
 | `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. |
+| `LIST_FORMAT_COMPOSITION_CONFLICT` | A `redline` and a `list-format` on the same paragraph do not compose (`reason`: `marker-changed` with `sourceMarker`/`modifiedMarker`, `redline-unchanged`, `redline-shape` for a multi-paragraph, ranged, anchored, `list-change` or structured redline), or a `list-format` with `scope: 'list'` rebinds an item another operation also writes (`list-rebind`, `rebindingOperationIndexes`). Detected at batch compilation; nothing was written. | `recovery.action: split_text_and_list_changes` (`recovery.hint`). Keep the typed marker byte-identical in the redline (the list-format strips it) and express a new label through `list-format`; drop a no-op redline; send other writes to rebound items in a separate apply or use `scope: 'range'`. |
 | `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. |
+| `PATCH_ROUNDTRIP_MISMATCH` | A cross-author surgical edit did not reconstruct the requested modified text exactly, or a localized `replacements` operation would not leave the compiled accepted text in the target (checked before commit on every path). | 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. |
+| `LIST_MARKER_NOT_BOUND` (warning) / `UNSUPPORTED_LIST_CONVERSION` (error) | A plain paragraph was edited so its text starts with a list marker (`A.`, `1.`, `iv.`, `-`) its original did not carry, but text edits cannot bind a list: the marker would be literal text and `list` stays `null`. Warning (`diagnostics[]` plus a `CODE: message` string in `warnings`) by default; error under the strict policy (`--profile agent`, `--atomic`, or `strictListConversion: true`). Separate from `REVISION_FIDELITY_VIOLATION`. Fields: `listMarker`, `requestedList`, `targetExcerpt`. Capability `list-conversion-diagnostics-v1`. | The error applied nothing. To create the list item, send `recovery.suggestedOperation` (a `list-format` `convert-plain` request) with the same target and leave the text unmarked (`recovery.action: use_list_format_convert_plain`); if the original already carries another marker, retype it with a `redline` first and convert with `strip: "marker"` in a later batch. If literal marker text is intended, repeat with `listMarkers: "literal"`. Do not treat a warning-only `ok` as a list conversion. |
+| `LIST_MARKER_NOT_FOUND` / `LIST_MARKER_AMBIGUOUS` / `LIST_MARKER_UNSUPPORTED` (error) | `list-format` `convert-plain` found no typed marker to strip; a lone roman-looking letter (`I.`, `C.`, `D.`) reads as letter or roman (`formats` lists both); or the marker shape is unsupported (`reason`: `mixed` markers in one range, `multilevel` `2.1.`, `parenthesized` `(a)`, `zero`, `format-mismatch`, `marker-shape` when the marker sits in a hyperlink, field, content control or pending revision). Nothing was written. | NOT_FOUND: target the marker paragraphs, or use `strip: "none"` with `list.format`. AMBIGUOUS: repeat with `list.format` from `recovery.allowedValues`. UNSUPPORTED: split mixed ranges into one operation per format; leave other shapes literal or convert them in the host. |
+| `LIST_FORMAT_TARGET_IS_LIST` / `LIST_FORMAT_STYLE_NUMBERED` (error) | `convert-plain` converts plain paragraphs only: the paragraph already has a direct `w:numPr`, or its paragraph style (or a `basedOn` ancestor) carries numbering. Nothing was written. | Narrow the range to plain paragraphs. To move an existing list item, use `paragraph-format` `numbering`; style-linked numbering is changed in the host. |
+| `LIST_FORMAT_NOT_APPLIED` (warning) / `UNSUPPORTED_LIST_FORMAT_CHANGE` (error) | A multi-line `list-change`/`redline` kept a list item's text with a marker whose kind or format (bullet vs numbered, decimal vs `A.`) differs from the numbering definition the item keeps (`sourceList.{numId,level,kind,format}`); the old definition is not replaced. Same warning/strict policy as above. Inserted items are not compared. | `recovery.action: use_list_format_change_format`: send `recovery.suggestedOperation` (a `list-format` `change-format` request, scope `list`) with a target on one item of the list; `list-change` never applies a format change itself. Text changes go in single-paragraph `redline`s without the new markers, which may share the batch with the `change-format` (they run first). Or pass `listMarkers: "literal"` to accept the result. |
+| `LIST_FORMAT_TARGET_NOT_LIST` / `LIST_FORMAT_MIXED_RANGE` (error) | `change-format`/`join`: the target range has no list item; or it mixes list items with plain paragraphs (`reason: non-list`), spans several lists (`several-lists`, `numIds`), or, for `change-format` without `list.level`, several levels (`levels`, `recovery.allowedValues`). Tracked-deleted paragraphs are skipped, never rebound. Nothing was written. | NOT_LIST: use `convert-plain` (typed markers) or `paragraph-format` `numbering`. MIXED: target one item of the list (scope `list`), one operation per list, or pass `list.level`. |
+| `LIST_FORMAT_STYLE_LINKED` / `LIST_FORMAT_DEFINITION_UNSUPPORTED` (error) | The list's definition is style-linked (`w:numStyleLink`/`w:styleLink`, a level `w:pStyle` such as heading numbering, or a paragraph style that binds it), so items can belong to it without a direct binding; or the definition cannot be rebound exactly (`reason`: `missing` numbering part or numId, `level-override` `w:lvlOverride/w:lvl`, `level-restart` `w:lvlRestart` in a `scope: 'range'` split, `undefined-level`). Nothing was written. | Change these lists in the host. `missing` on a bare call: pass the package's `word/numbering.xml` as `numberingXml`. `level-restart`: use `scope: 'list'`. |
+| `LIST_FORMAT_SPLIT_UNSUPPORTED` / `LIST_FORMAT_JOIN_INVALID` (error) | The rebinding would renumber paragraphs it does not name, or Word could not show the same count: `mid-sequence` (a `scope: 'range'` that stops before the list's last item; `followingParagraphIndexes`, `lastListParagraphIndex`), `nested-restart` (a split that starts below a level that later restarts inside the range), `shared-definition` (another list shares the abstract definition, which Word counts as one list), `interleaved` (the continued list has items after the joined ones), `textbox-member`; join: `continueFrom` `after-target`, `not-a-list`, `deleted`, `inside-target`. Nothing was written. | Extend `targetEnd` to `lastListParagraphIndex` or use `scope: 'list'`; start a split at a top-level item; join a list to the list that immediately precedes it. A `LIST_FORMAT_UNCHANGED` warning (`ok`, no change) means the list already has the requested format or already continues `continueFrom`. |
+| `INVALID_OPERATION` with `field: properties.<key>` (error) | `paragraph-format.properties` contained keys outside `alignment`, `keepNext`, `keepLines`, `pageBreakBefore`, `style`, `numbering` (0.9.0; it was the `UNKNOWN_PARAGRAPH_FORMAT_PROPERTY` warning in 0.8.x). Nothing was applied; `properties` lists the rejected keys. | Remove the unsupported key, or use the dedicated operation (`list-format`, `format`). |
+| `PARAGRAPH_NUMBERING_NOT_FOUND` (error) | `paragraph-format` `numbering.numId` is not defined in the document's numbering part (and was not allocated earlier in the batch), its `abstractNum` is missing, or the level is not defined. `reason` is `unknown-num`, `missing-abstract` or `undefined-level`. Nothing was changed. | Inspect a paragraph already in the target list and copy its `list.numId` and `list.level`. A binding never creates a list. |
+| `PARAGRAPH_FORMAT_REVISION_CONFLICT` (error) | The target paragraph already has a pending `w:pPrChange` by another author; overwriting its snapshot would change what Reject All restores. A pending change by the same author keeps its earliest snapshot. | Ask the user to accept or reject the existing formatting change first. |
+| `REVISION_FIDELITY_VIOLATION` | Word's Reject All of the operation's output would not reproduce the source (`violations[].invariant`: `REJECT_PARAGRAPH_COUNT`, `REJECT_PARAGRAPH_TEXT`, `REJECT_PARAGRAPH_PROPS`, `REJECT_NUMBERING_REFS` (also: a bound or restored numId with no `w:num`/`w:abstractNum`/`w:lvl` in the output numbering), `REJECT_WRAPPERS`, `ACCEPT_INTENT` (a plain-text `redline`'s Accept All target does not equal its complete `modified` text); for `generateRedlines: false` operations also `ACCEPT_NEIGHBORS` and `UNTRACKED_CREATED_REVISION`, the latter meaning the untracked edit wrote a tracked revision the source lacked). Refused by default (`enforce`); `verifyRevisionFidelity: 'warn'` / `--revision-fidelity warn` applies and appends the same text to `warnings`. Each violation has `explanation`, `expected`/`actual` excerpts and `source.sourceParagraphIndex` (the 1-based extraction index) with a text excerpt. | Nothing was applied. Follow `recovery.retryGuidance` for the reported invariant: target one paragraph, use `replacements` for literal edits, keep breaks/tabs and hyperlink boundaries, and move formatting or list changes into their own operation. If a narrower retry is also refused, report the operation and `violations`; never disable verification to force it through. For `UNTRACKED_CREATED_REVISION`, retry once with the fresh extraction; if it repeats, report it (or make the edit tracked with `generateRedlines: true` if a reviewable change is acceptable). |
 | `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. |
 | `PART_NOT_FOUND` / `PART_AMBIGUOUS` | The `part` selector matched no header/footer, or several. | Re-run `inspect` and use `headersFooters[].path`, or add `section`. |
 | `FIELD_EDIT_REFUSED` | The edit would change a field (PAGE, NUMPAGES, DATE) in a header or footer. | Edit the text around the field. |
@@ -960,7 +979,7 @@ directly into `word/document.xml`.
 1. Call `configureXmlProvider` first in Node.js.
 2. `applyRedlineToOxml` is async.
 3. Paragraph APIs expect paragraph-level OOXML, not full `word/document.xml` in all cases.
-4. List operations may return `numberingXml` that must be merged into package parts. When `word/numbering.xml` already exists, pass `mergeNumberingXmlBySchemaOrder` to `ensureNumberingArtifactsInZip`; without a merge callback the helper replaces the prior payload.
+4. List operations may return `numberingXml` that must be merged into package parts. `ensureNumberingArtifactsInZip` always merges them into an existing `word/numbering.xml` (the former `mergeNumberingXml` option is ignored); a conflicting id fails with `NUMBERING_ID_CONFLICT`, so pass `numberingXml` or a shared `numberingIdState` to every call.
    That replacement behavior is deprecated and will become an error in the next major version.
 5. `useNativeApi: true` means standalone mode cannot fully handle that operation path.
 6. `deleteCommentsByAuthorInOoxml` removes definitions and linked anchors only when they are present in the same OOXML payload. In a real `.docx`, `word/comments.xml` and `word/document.xml` are separate parts and must both be updated by the package integration layer.

package/docs/SKILL_AUTHORING.md

@@ -1,150 +1,165 @@
-# Skill and Harness Authoring Contract
-
-Use this page to create or update an agent skill, MCP server, or custom harness
-for `@ansonlai/docx-redline-js`. Ordinary editing agents should load
-[Agent Fast Start](AGENT_FAST_START.md), not this design contract.
-
-> [!WARNING]
-> Before 1.0, every integration must identify and pin its exact tested library
-> release and required CLI contract/capabilities. Treat any different release or
-> contract as unverified until compatibility tests pass.
-
-Example declaration for a contract-8 shell integration that uses localized
-operations over stdin:
-
-```json
-{
-  "testedLibraryRelease": "0.7.1",
-  "requiredCliContractVersion": 8,
-  "requiredCapabilities": [
-    "operations-stdin",
-    "agent-safety-profile-v2",
-    "recovery-envelope-v1",
-    "localized-replacements-v1"
-  ]
-}
-```
-
-## Runtime negotiation
-
-Run `docx-redline version` before the first document operation. Require CLI
-contract version 8 and only the capabilities the integration actually uses. Check once per stable
-runtime, fail closed when a requirement is absent, and never inspect bundles or
-ZIP parts as a fallback.
-
-Do not expose negotiated but unused capabilities as choices in the editing
-prompt. `command-help-v1`, restore shortcuts, speculative apply, and localized
-change summaries are optional requirements only for integrations that use them.
-
-## Safety invariants
-
-Every generated integration must:
-
-- inspect narrowly, retain `exactText`, and target with `paragraphId` plus
-  `fingerprint`;
-- use strict targeting, package validation, and a derived output path;
-- never overwrite the source unless `--in-place` is explicitly requested;
-- require `completion: true` and a non-null `outputPath` before reporting
-  success;
-- follow `error.recovery.action` and never retry unchanged failed arguments; and
-- require explicit authorization before accepting/rejecting another reviewer's
-  work or deleting comments.
-
-The CLI computes `completion` from write status, operation outcomes, commit
-disposition, and localized accepted-view verification. Preserve the detailed
-results for audit and recovery, but do not make the editing agent re-evaluate
-those fields during ordinary success handling.
-
-## Workflow policy choices
-
-Keep these exceptions separate from the default workflow:
-
-| Choice | Default | Override only when |
-|---|---|---|
-| Transaction | progressive | Partial output is unacceptable (`--atomic`). |
-| Existing revisions | `merge-same-author` | Editing inside another reviewer's pending insertion is intended (`slice-cross-author`). |
-| Reviewer identity | `AI Redliner` is a valid visible fallback | The host supplies a preferred flag, operation author, or environment value. |
-| Output | derived sibling | The caller deliberately selects another destination. |
-
-Check `effectiveOptions` when an integration deliberately sets a policy.
-
-## Transport choices
-
-A UTF-8 operations file and serializer-backed stdin are peer transports:
-
-```bash
-docx-redline apply input.docx --operations operations.json --profile agent --output reviewed.docx
-node emit-operations.mjs | docx-redline apply input.docx --operations - --profile agent --compact --output reviewed.docx
-```
-
-Use `JSON.stringify` or a structured tool API. Never demonstrate `echo`, a
-heredoc, or shell-interpolated document text. In JavaScript/TypeScript runtimes
-(Node.js, browsers, Cloudflare Workers, Deno, Bun, or sandboxed environments like
-n8n), an in-process wrapper should call `openDocx(uint8Array)` directly from
-`@ansonlai/docx-redline-js` (or `@ansonlai/docx-redline-js/bundle` for zero-dependency
-standalone sandboxes) and return the structured result instead of recreating CLI
-serialization, ZIP handling, targeting, validation, or rollback.
-
-## Ordinary generated workflow
-
-The first executable editing example in a generated skill must be focused
-extraction:
-
-```bash
-docx-redline extract input.docx --search "renewal notice" --around 3
-```
-
-Then apply once using the inspected strong target. Use complete `modified` text
-for a broad semantic revision or `replacements` for a small literal change in
-that target. Keep requested relative wording relative unless the user asks for
-a concrete value.
-
-Follow `selection.nextAfter` when extraction is truncated. Output projections must retain
-`selection`, target descriptors, `humanReference`, and revision
-cues.
-
-### Observed restore branch
-
-If the user requests restoration, search `--view rejected` first. Otherwise
-follow an alternate-view `selection.hint` when returned. Restore only the
-inspected strong target. Require `restore-shortcuts-v1` only if the integration
-uses inline `--restore`; canonical operations remain available.
-
-### Optional speculative execution
-
-Do not make speculative apply part of an ordinary generated workflow. A harness
-may opt into `speculative-search-apply-v1` only when it owns a measured confidence
-policy and accepts the recovery cost of a miss. Keep anchor selection,
-directional windows, occurrence handling, and exact matching semantics out of
-the ordinary editing prompt; link to the knowledge base or CLI help instead.
-
-## Recovery contract
-
-Lead failure handling with these runtime fields:
-
-1. `error.recovery.action`
-2. `error.recovery.requiresReinspection`
-3. `error.recovery.requiresUserAuthorization`
-4. `error.recovery.sameArgumentsSafe`
-
-Use `retryPlan.base` and its operation indexes to select the original or partial
-output package. Do not reproduce an error-code decision tree in the skill.
-
-## Presentation rules
-
-Use `humanReference`, `provision`, or `nearestHeading` in completion reports.
-Paragraph indexes and `P55`-style references are machine coordinates, not
-locations a document user can follow. Keep the exact machine target internally.
-
-## Generation checklist
-
-- Exact tested release, contract 8, and the minimum capability set are pinned.
-- Runtime compatibility is checked once.
-- The first ordinary command is focused extraction.
-- Apply uses the inspected target with `modified` or localized `replacements`.
-- Restore appears only as a user-requested or observed-view branch.
-- Speculative execution is absent unless the harness owns a measured policy.
-- Ordinary success requires `completion: true` and a non-null `outputPath`.
-- Recovery, authorization, source immutability, and structured serialization
-  invariants are preserved.
-- Wrappers delegate mutation and OOXML packaging to the library.
+# Skill and Harness Authoring Contract
+
+Use this page to create or update an agent skill, MCP server, or custom harness
+for `@ansonlai/docx-redline-js`. Ordinary editing agents should load
+[Agent Fast Start](AGENT_FAST_START.md), not this design contract.
+
+> [!WARNING]
+> Before 1.0, every integration must identify and pin its exact tested library
+> release and required CLI contract/capabilities. Treat any different release or
+> contract as unverified until compatibility tests pass.
+
+Example declaration for a contract-8 shell integration that uses localized
+operations over stdin:
+
+```json
+{
+  "testedLibraryRelease": "0.7.1",
+  "requiredCliContractVersion": 8,
+  "requiredCapabilities": [
+    "operations-stdin",
+    "agent-safety-profile-v2",
+    "recovery-envelope-v1",
+    "localized-replacements-v1"
+  ]
+}
+```
+
+## Runtime negotiation
+
+Run `docx-redline version` before the first document operation. Require CLI
+contract version 9 only when the integration sends `list-format` operations (see
+List structure); otherwise contract version 8 suffices. Require
+only the capabilities the integration actually uses. Check once per stable
+runtime, fail closed when a requirement is absent, and never inspect bundles or
+ZIP parts as a fallback.
+
+### List structure (optional)
+
+Keep list structure out of an ordinary editing prompt. A wrapper that converts typed headers, changes a list's
+format, or joins lists:
+
+- negotiates `list-format-v1` (`convert-plain`) and, only if used, `list-format-change-v1` (`change-format`,
+  `join`);
+- without the capability keeps its host path, never a `redline` or `list-change` that retypes markers (that
+  warns, or fails under the agent profile, and binds nothing);
+- follows `use_list_format_*` recovery by sending `recovery.suggestedOperation` with the inspected target;
+- sends a changed-text header (`1. Old` -> `1. New`) as a marker-preserving `redline` plus a `list-format` of that
+  paragraph in one batch, and splits them on `LIST_FORMAT_COMPOSITION_CONFLICT`.
+
+Do not expose negotiated but unused capabilities as choices in the editing
+prompt. `command-help-v1`, restore shortcuts, speculative apply, and localized
+change summaries are optional requirements only for integrations that use them.
+
+## Safety invariants
+
+Every generated integration must:
+
+- inspect narrowly, retain `exactText`, and target with `paragraphId` plus
+  `fingerprint`;
+- use strict targeting, package validation, and a derived output path;
+- never overwrite the source unless `--in-place` is explicitly requested;
+- require `completion: true` and a non-null `outputPath` before reporting
+  success;
+- follow `error.recovery.action` and never retry unchanged failed arguments; and
+- require explicit authorization before accepting/rejecting another reviewer's
+  work or deleting comments.
+
+The CLI computes `completion` from write status, operation outcomes, commit
+disposition, and localized accepted-view verification. Preserve the detailed
+results for audit and recovery, but do not make the editing agent re-evaluate
+those fields during ordinary success handling.
+
+## Workflow policy choices
+
+Keep these exceptions separate from the default workflow:
+
+| Choice | Default | Override only when |
+|---|---|---|
+| Transaction | progressive | Partial output is unacceptable (`--atomic`). |
+| Existing revisions | `merge-same-author` | Editing inside another reviewer's pending insertion is intended (`slice-cross-author`). |
+| Reviewer identity | `AI Redliner` is a valid visible fallback | The host supplies a preferred flag, operation author, or environment value. |
+| Output | derived sibling | The caller deliberately selects another destination. |
+
+Check `effectiveOptions` when an integration deliberately sets a policy.
+
+## Transport choices
+
+A UTF-8 operations file and serializer-backed stdin are peer transports:
+
+```bash
+docx-redline apply input.docx --operations operations.json --profile agent --output reviewed.docx
+node emit-operations.mjs | docx-redline apply input.docx --operations - --profile agent --compact --output reviewed.docx
+```
+
+Use `JSON.stringify` or a structured tool API. Never demonstrate `echo`, a
+heredoc, or shell-interpolated document text. In JavaScript/TypeScript runtimes
+(Node.js, browsers, Cloudflare Workers, Deno, Bun, or sandboxed environments like
+n8n), an in-process wrapper should call `openDocx(uint8Array)` directly from
+`@ansonlai/docx-redline-js` (or `@ansonlai/docx-redline-js/bundle` for zero-dependency
+standalone sandboxes) and return the structured result instead of recreating CLI
+serialization, ZIP handling, targeting, validation, or rollback.
+
+## Ordinary generated workflow
+
+The first executable editing example in a generated skill must be focused
+extraction:
+
+```bash
+docx-redline extract input.docx --search "renewal notice" --around 3
+```
+
+Then apply once using the inspected strong target. Use complete `modified` text
+for a broad semantic revision or `replacements` for a small literal change in
+that target. Keep requested relative wording relative unless the user asks for
+a concrete value.
+
+Follow `selection.nextAfter` when extraction is truncated. Output projections must retain
+`selection`, target descriptors, `humanReference`, and revision
+cues.
+
+### Observed restore branch
+
+If the user requests restoration, search `--view rejected` first. Otherwise
+follow an alternate-view `selection.hint` when returned. Restore only the
+inspected strong target. Require `restore-shortcuts-v1` only if the integration
+uses inline `--restore`; canonical operations remain available.
+
+### Optional speculative execution
+
+Do not make speculative apply part of an ordinary generated workflow. A harness
+may opt into `speculative-search-apply-v1` only when it owns a measured confidence
+policy and accepts the recovery cost of a miss. Keep anchor selection,
+directional windows, occurrence handling, and exact matching semantics out of
+the ordinary editing prompt; link to the knowledge base or CLI help instead.
+
+## Recovery contract
+
+Lead failure handling with these runtime fields:
+
+1. `error.recovery.action`
+2. `error.recovery.requiresReinspection`
+3. `error.recovery.requiresUserAuthorization`
+4. `error.recovery.sameArgumentsSafe`
+
+Use `retryPlan.base` and its operation indexes to select the original or partial
+output package. Do not reproduce an error-code decision tree in the skill.
+
+## Presentation rules
+
+Use `humanReference`, `provision`, or `nearestHeading` in completion reports.
+Paragraph indexes and `P55`-style references are machine coordinates, not
+locations a document user can follow. Keep the exact machine target internally.
+
+## Generation checklist
+
+- Exact tested release, contract 8 (9 only with `list-format`), and the minimum capability set are pinned.
+- Runtime compatibility is checked once.
+- The first ordinary command is focused extraction.
+- Apply uses the inspected target with `modified` or localized `replacements`.
+- Restore appears only as a user-requested or observed-view branch.
+- Speculative execution is absent unless the harness owns a measured policy.
+- Ordinary success requires `completion: true` and a non-null `outputPath`.
+- Recovery, authorization, source immutability, and structured serialization
+  invariants are preserved.
+- Wrappers delegate mutation and OOXML packaging to the library.