@ansonlai/docx-redline-js 0.6.0 → 0.6.1

package/docs/AGENT_FAST_START.md

@@ -20,23 +20,23 @@ It is a development sample, not a package API.
 1. Extract only the relevant clause or range:
 
    ```bash
-   docx-redline extract contract.docx --search "termination"
+   docx-redline extract contract.docx --search "termination" --around 3
    ```
 
-2. Copy `exactText` with `paragraphId` or `fingerprint`. Serialize the final
-   operation array directly to stdin, then apply once:
+   Search is case-insensitive. Direct hits are capped; follow `selection.nextAfter` with `--after`, and cite `humanReference`, not `P42`.
+
+2. Copy `exactText` with `paragraphId` or `fingerprint`. Use a UTF-8 operations
+   file or serializer-backed stdin, then apply once:
 
    ```bash
-   node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --output reviewed.docx
+   node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
    ```
 
    `emit-operations.mjs` should use `JSON.stringify`; do not interpolate legal
    text through shell quoting. `modified` is the complete desired accepted-view
    paragraph, not only the inserted words.
 
-The `agent` profile is explicit and reproducible. It uses atomic rollback,
-strict targets, validation, tracked changes, `merge-same-author`, and nonzero
-exit codes for incomplete work. The result reports `effectiveOptions`.
+The `agent` profile preserves progressive execution and the ordinary revision policy while making incomplete work exit nonzero. Add `--atomic` deliberately; check `effectiveOptions`. Run `docx-redline apply --help` for redline, comment, and rejected-view restore shapes.
 
 ## Batch and result rules
 

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -482,8 +482,9 @@ Use this for everything by default. `apply` is fast, progressive, and self-valid
 
 The short route for a document-editing request is:
 
-1. Run one focused `extract` for the clauses or range being edited and copy
-   `exactText` plus `paragraphId` or `fingerprint`.
+1. Run one focused `extract` for the clauses or range being edited. Search is a
+   case-insensitive substring match; add `--around 3` when surrounding drafting
+   context is needed. Copy `exactText` plus `paragraphId` or `fingerprint`.
 2. Build the final operations from the operation table above. Use one operation
    per target paragraph, and consolidate multiple changes to that paragraph.
 3. Run `apply` once per stable batch. Strong inspected targets are bound against
@@ -501,21 +502,24 @@ Do not probe operation behavior with disposable apply commands or read a vendor
 bundle before this route. If `apply` returns an error, use the recovery matrix
 below and make one cause-specific correction.
 
-```bash
-# 1. Inline one-liner edit (fastest for 1–2 edits; no JSON file needed)
-docx-redline apply contract.docx --target "Original clause" --modified "New clause" --output reviewed.docx
-
-# 2. Direct edit without tracked changes (clean text, no revision clutter)
+```bash
+# 1. Focused contextual discovery
+docx-redline extract contract.docx --search "termination" --around 3
+
+# 2. Inline one-liner edit (fastest for 1–2 edits; no JSON file needed)
+docx-redline apply contract.docx --target "Original clause" --modified "New clause" --output reviewed.docx
+
+# 3. Direct edit without tracked changes (clean text, no revision clutter)
 docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
 
-# 3. Cross-author edit inside another reviewer's pending insertion
+# 4. Cross-author edit inside another reviewer's pending insertion
 docx-redline apply contract.docx --target "Pending clause text" --modified "Updated clause text" --existing-revisions slice-cross-author --output reviewed.docx
 
-# 4. Batch operations with ops.json
+# 5. Batch operations with ops.json
 docx-redline apply contract.docx --operations operations.json --output reviewed.docx
 
-# 5. Shell-agent batch without an operations file
-node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --output reviewed.docx
+# 6. Serializer-backed stdin with compact stdout
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
 ```
 
 Key CLI defaults and behaviors:
@@ -525,9 +529,9 @@ Key CLI defaults and behaviors:
 - **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` explicitly defaults `atomic` and complete-success behavior to true and reports `effectiveOptions`. Call flags override the profile. It does not enable authorization-sensitive revision normalization.
-- **Stdin operations**: `--operations -` accepts the same JSON array or `{ operations, expectedRevision }` envelope as a file. Supply UTF-8 JSON through a serializer/structured process API; do not interpolate legal text in the shell.
-- **Compact mutation JSON**: `apply`, `accept`, `reject`, and `delete-comments` omit document/package XML and full validation arrays. `validation.originalIssues` and `validation.generatedIssues` are code/count summaries; run `validate` for full issue records.
+- **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`, `written: true`, and a non-null `outputPath` on stdout. `completion` is derived from the write result, top-level status, and every operation status, so failed, partial, and unwritten work cannot appear complete. If an error occurs, inspect `error.code` or `results[i].error.code` (e.g. `TARGET_NOT_FOUND`, `ANCHOR_NOT_FOUND`) before correcting the cause and re-applying.
 
 For multi-clause or multi-page reviews, apply edits **section-by-section** or clause-by-clause (e.g., using `--in-place` on a working copy) rather than bundling dozens of edits into one massive batch. This keeps context compact, simplifies error diagnosis, and prevents cascading anchor drift.
@@ -568,15 +572,21 @@ 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`. A malformed
-filter or unknown option is an error rather than an unfiltered fallback.
-
-Mutating commands require `--author`, authors on every operation, or
-`--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. 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.
+
+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.

package/docs/SKILL_AUTHORING.md

@@ -0,0 +1,126 @@
+# Skill and Harness Authoring Contract
+
+Use this page when creating or updating an agent skill, MCP server, or custom
+harness for `@ansonlai/docx-redline-js`. Ordinary document-editing agents should
+load [Agent Fast Start](AGENT_FAST_START.md), not this design contract.
+
+## Runtime negotiation
+
+Run this before the first document operation when the skill vendors or invokes
+the CLI:
+
+```bash
+docx-redline version
+```
+
+Require contract version 7 and only the capabilities the integration uses. A
+typical shell skill should require `command-help-v1`, `inspection-context-v1`,
+`bounded-inspection-v1`, `human-document-references-v1`,
+`agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
+`recovery-envelope-v1`. Require `operations-stdin` or `compact-cli-json-v1` only
+when the host uses those features. Fail closed with an upgrade instruction when
+a required capability is absent. Never inspect `dist/`, minified source, or ZIP
+parts to compensate for a stale runtime.
+
+## Safety invariants
+
+Every generated integration must preserve these rules:
+
+- Inspect narrowly and copy `exactText` plus `paragraphId` or `fingerprint`.
+- Treat `modified` as the complete desired accepted-view target content.
+- Use strict targeting, package validation, and a derived output path; never
+  overwrite the source unless the caller explicitly requests `--in-place`.
+- Require `completion: true`, `written: true`, a non-null `outputPath`, and no
+  per-operation error before reporting completion.
+- Never accept or reject another reviewer's work or delete comments without
+  explicit user authorization.
+- Never retry unchanged failed arguments.
+
+The `agent` profile enables complete-success exit behavior and retains the
+ordinary progressive default. It does not select atomic execution or a special
+existing-revision policy. A skill must state those choices explicitly when its
+workflow needs them.
+
+## Workflow policy choices
+
+Choose and document these separately from safety invariants:
+
+| Choice | Options | Guidance |
+|---|---|---|
+| Transaction | progressive default or `--atomic` | Use progressive for independent edits; use atomic when partial output is unacceptable. |
+| Existing revisions | `merge-same-author` default or explicit policy | Use `slice-cross-author` only when editing inside another reviewer's pending insertion is intended. |
+| Reviewer identity | flag, operation author, environment, or fallback | `AI Redliner` is a valid visible fallback. `DOCX_REDLINE_AUTHOR` is an optional harness preference, not a guard. |
+| Output naming | derived sibling or explicit destination | Keep source immutability unless in-place mutation is deliberately authorized. |
+
+Examples of valid profile composition:
+
+```bash
+docx-redline apply input.docx --operations operations.json --profile agent --output reviewed.docx
+docx-redline apply input.docx --operations operations.json --profile agent --atomic --output reviewed.docx
+docx-redline apply input.docx --operations operations.json --profile agent --existing-revisions slice-cross-author --output reviewed.docx
+```
+
+Check `effectiveOptions` rather than assuming the resolved transaction,
+revision, author, or redline policy.
+
+## Transport choices
+
+A UTF-8 operations file and serializer-backed stdin are peer transports. Choose
+the form the host can construct safely:
+
+```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 legal text. `--compact` changes stdout formatting,
+not result semantics. A Node byte-oriented wrapper should call `openDocx` and
+return the full structured result rather than recreating the CLI serializer.
+
+## Ordinary generated workflow
+
+The first executable document-editing example in a generated skill should be a
+focused contextual extraction:
+
+```bash
+docx-redline extract input.docx --search "force majeure" --around 3
+```
+
+Use `selection.nextAfter` with `--after` when truncated. Apply once per stable
+batch. Run `docx-redline apply --help` for canonical redline, whole-paragraph
+comment, and rejected-view restore shapes; the operation schema remains
+[document-operations.schema.json](schemas/document-operations.schema.json).
+
+## Recovery contract
+
+Lead error handling with exactly 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 generate a second prose decision tree for every error
+code; error messages and bounded diagnostics explain the cause, while the four
+fields above determine the next action.
+
+## Presentation rules
+
+Use `humanReference`, `provision`, or `nearestHeading` in user-facing completion
+reports. `P55`, `index: 55`, and phrases such as “the 55th paragraph” are machine
+targeting and pagination coordinates, not locations a Word user can follow.
+When no formal heading exists, use the returned short text lead. Never replace
+an exact machine target with a human-facing reference.
+
+## Generation checklist
+
+- Runtime version and required capabilities are checked once.
+- The first ordinary edit command is focused `extract --search ... --around`.
+- Safety invariants are not mixed with transaction or revision-policy choices.
+- Operations-file and stdin examples use structured serialization.
+- The four-field recovery contract precedes any diagnostic commentary.
+- Completion prose uses legal references rather than machine ordinals.
+- The wrapper delegates mutation, validation, rollback, comments, numbering,
+  receipts, and OOXML packaging to the library.

package/docs/TESTING.md

@@ -22,10 +22,10 @@ fixtures rarely contain.
 | Multimodal LLM visual spot check | On-demand / sampled | Evaluates rendered real-document pages with vision models for layout, table alignment, and typography regressions | Full-corpus automated coverage (intentionally decoupled and sampled due to cost/time) |
 | XSD and LibreOffice | See [Release validation and independent oracles](#release-validation-and-independent-oracles) | Schema conformance and acceptance by a second consumer | Word-specific revision semantics |
 | Agent inspection and package facade | `node tests/document_inspection_tests.mjs`, `node tests/docx_package_facade_tests.mjs` | Canonical text, comment/list resolution, package-scoped IDs, untouched-part preservation, and atomic rollback | Desktop Word rendering |
-| Agent CLI | `node tests/agent_cli_tests.mjs`, `node tests/agent_cli_protocol_tests.mjs` | JSON contracts, exact-text extraction, stdin operations, named agent-profile defaults, UTF-8 fidelity, complete-success exits, source safety, all command families, and operation-schema readability | Cross-platform CI beyond the current runner |
+| Agent CLI | `node tests/agent_cli_tests.mjs`, `node tests/agent_cli_protocol_tests.mjs`, `node tests/agent_cli_help_tests.mjs`, `node tests/agent_cli_inspection_context_tests.mjs`, `node tests/agent_cli_output_budget_tests.mjs` | JSON contracts, command-specific help, contextual pagination, composable progressive/atomic profiles, deduplicated receipts, compact stdout, file/stdin Unicode fidelity, complete-success exits, source safety, command families, and schema readability | Cross-platform CI beyond the current runner |
 | Example agent session | `node tests/agent_session_example_tests.mjs`, `node tests/localized_edit_example_tests.mjs` | A non-package sample wrapper delegates to the Node facade, binds and refreshes opaque handles across package revisions, returns context windows, compiles exact localized edits, preserves accepted/rejected lifecycle and atomic rollback, and supports review resolution | LLM/provider latency or a production tool-server transport |
 | Batch compilation and recovery | `node tests/batch_source_binding_tests.mjs`, `node tests/error_recovery_contract_tests.mjs`, `node tests/capture_dependency_graph_tests.mjs` | Batch-start source identity survives structural index drift and savepoint restoration; true overlap and capture fan-out fail before mutation; recovery envelopes, retry bases, bounded CLI diagnostics, and complete-success exits remain stable | Whether a model follows the returned recovery action correctly |
-| Agent documentation contract | `node tests/agent_documentation_contract_tests.mjs` | The ordinary fast start stays within its 40–60 line/600-word budget, retains required safety contracts, and the launch card routes to detailed sources while the development wrapper stays outside package files | Whether a particular model reads or follows the instructions |
+| Agent documentation contract | `node tests/agent_documentation_contract_tests.mjs` | The ordinary fast start stays within its 40–60 line/600-word budget, examples lead with scoped contextual extraction, and packaged skill-authoring guidance separates invariants, policies, transports, recovery, and presentation while the development wrapper stays outside package files | Whether a particular model reads or follows the instructions |
 | Agent edge cases | `node tests/canonical_paragraph_text_tests.mjs`, `node tests/document_inspection_edge_tests.mjs`, `node tests/docx_package_transaction_edge_tests.mjs`, `node tests/node_zip_archive_tests.mjs`, `node tests/agent_cli_edge_tests.mjs` | Revision-view semantics, cross-paragraph anchors, nested numbering, transaction reuse, multi-author cleanup, malformed ZIP handling, and destructive CLI safeguards | Desktop Word rendering and non-Windows CI |
 | Performance boundary regression | `node tests/performance_phase2_boundary_tests.mjs` | Stable facade re-exports, leaf imports, session rollback, isolated context commit, and comment-first scheduling | The Phase 1 one-parse/one-serialize performance target |
 | Live-session accuracy and instrumentation | `node tests/performance_phase1_session_tests.mjs` | One full parse/serialization, sequential semantic equivalence, exact accepted/rejected text, valid revisions, list/table/comment/highlight preservation, savepoint no-ops, and zero-serialization rollback | Desktop Word rendering |
@@ -98,6 +98,21 @@ tokens, tool transport, Claude, or OpenCode wall time; collect those separately
 in the calling harness. The checked WP-07 results are summarized in the
 [agent protocol rollout audit](validation-reports/2026-09-12-agent-protocol-rollout.md).
 
+Run the CLI discovery/output benchmark with:
+
+```powershell
+npm run benchmark:agent-cli
+```
+
+It records command-specific help size, broad inspect/search response size,
+context-window call count, pagination metadata, case-insensitive match parity,
+and native elapsed time in `tmp/benchmarks/agent-cli-discovery-latest.json`.
+The checked WP-00 through WP-02 before/after measurements are in the
+[agent CLI discovery baseline](validation-reports/2026-09-12-agent-cli-discovery-baseline.md).
+WP-03 through WP-05 profile, output-size, workflow, documentation, and package
+results are in the
+[agent CLI efficiency rollout audit](validation-reports/2026-09-13-agent-cli-efficiency-rollout.md).
+
 ## Cross-author revision slicing test suite
 
 The cross-author revision slicing subsystem introduces six complementary test lanes:

package/docs/validation-reports/2026-09-12-agent-cli-discovery-baseline.md

@@ -0,0 +1,56 @@
+# Agent CLI Discovery Baseline
+
+**Date:** 2026-09-12
+
+**Scope:** WP-00 baseline for command discovery, inspection breadth, contextual
+search, and compact mutation output
+
+## Before-state
+
+Measurements were captured from the source CLI immediately before WP-01/WP-02,
+using `tests/fixtures/sample_doc_test.docx` and pretty-printed CLI JSON:
+
+| Case | Result |
+|---|---:|
+| Global help | 171 bytes |
+| `apply --help` | 171 bytes; identical to global help |
+| `inspect --non-empty` | 72,387 bytes / 63 paragraphs |
+| Broad `extract --search "the"` | 13,968 bytes / 31 paragraphs |
+| Context retrieval | Search plus range: 2 commands |
+| Successful one-operation receipt | 464 bytes nested plus the same 464 bytes at root |
+
+The help payload did not describe command flags, search case behavior, or
+redline/comment/restore shapes. The detailed unscoped inspection exceeded the
+observed 64 KiB harness ceiling. Receipt deduplication is recorded here but is
+owned by WP-04, not WP-00 through WP-02.
+
+## WP-01/WP-02 result
+
+The checked post-change run produced:
+
+| Case | Result |
+|---|---:|
+| Global command-index help | 1,390 bytes |
+| Command-specific apply help | 4,400 bytes with flags and three operation shapes |
+| Bounded `inspect --non-empty` | 25,093 bytes / first 20 of 63 paragraphs |
+| Bounded `extract --search "the"` | 12,855 bytes / first 20 of 31 matches |
+| `extract --search "agreement" --around 2 --limit 1` | 2,178 bytes / one command / three paragraphs |
+
+Both formerly broad responses remain valid JSON below the 48 KiB soft limit and
+include stable continuation metadata. Search case variants returned identical
+indexes. A paragraph that individually exceeds the soft limit is returned whole
+and marked `oversizeItem` rather than truncating `exactText`.
+
+## Reproduction
+
+Run:
+
+```bash
+npm run benchmark:agent-cli
+```
+
+The benchmark retains the observed before-state constants and records the active
+post-change results in `tmp/benchmarks/agent-cli-discovery-latest.json`. It
+measures CLI response bytes, calls, paragraphs, selection metadata, and native
+elapsed time. It does not estimate model tokens, provider wall time, or tool
+transport latency.

package/docs/validation-reports/2026-09-12-agent-protocol-rollout.md

@@ -60,11 +60,15 @@ win.
 
 ## Configuration decision
 
+> Historical note: this section records CLI contract version 5. Contract version
+> 7 decomposes `--profile agent`: it now supplies complete-success execution
+> without forcing atomic mode. Skills choose `--atomic` separately.
+
 No project or auto-discovered configuration file was added. The CLI already
 defaults author, strict targeting, validation, tracked changes, revision safety,
-and output naming. The explicit `--profile agent` flag captures the remaining
-atomic/complete-success policy and reports `effectiveOptions`. Removing that one
-flag would not justify hidden configuration discovery or precedence reasoning.
+and output naming. The explicit `--profile agent` flag reports
+`effectiveOptions`; hidden configuration discovery still would not justify its
+additional precedence reasoning.
 
 ## Remaining external measurement
 

package/docs/validation-reports/2026-09-13-agent-cli-efficiency-rollout.md

@@ -0,0 +1,86 @@
+# Agent CLI Efficiency Rollout Audit
+
+**Date:** 2026-09-13  
+**Scope:** WP-03 through WP-05 profile composition, compact mutation output,
+skill-authoring guidance, and package parity
+
+## Outcome
+
+CLI contract version 7 separates complete-success behavior from workflow
+policy. `--profile agent` now retains progressive execution and the ordinary
+`merge-same-author` policy; `--atomic` and explicit revision policies compose
+with it and appear in `effectiveOptions`. Reviewer precedence and the visible
+`AI Redliner` fallback are unchanged.
+
+Compact CLI mutation output now contains one authoritative top-level receipt per
+operation and no nested receipt copy. Successful exact-match diagnostics are
+omitted; successful space-equivalent matches retain `{ mode, differenceCount }`.
+Errors keep their bounded recovery evidence. The Node facade and standalone
+runner retain their complete per-result receipt and target-match structures.
+
+## Measured output
+
+`npm run benchmark:agent-cli` uses the same one-operation sample established in
+the WP-00 baseline:
+
+| Mutation response | Bytes | Change from pre-WP-04 |
+|---|---:|---:|
+| Pre-WP-04 pretty JSON | 2,968 | — |
+| Contract-7 pretty JSON | 2,216 | 25.34% smaller |
+| Contract-7 `--compact` JSON | 1,557 | 47.54% smaller |
+
+One-line serialization is 29.74% smaller than the structurally deduplicated
+pretty response, so contract version 7 exposes it explicitly through `--compact`
+and `compact-cli-json-v1`. It changes whitespace only.
+
+## Representative workflow audit
+
+The checked repository run records:
+
+- one relevant command-help lookup;
+- zero source, distribution-bundle, or ZIP-part inspection calls;
+- one contextual clause search and one apply attempt;
+- progressive agent-profile execution with complete-success exits;
+- exact accepted text and exact source restoration after rejection;
+- unchanged comment count and byte-identical source input; and
+- one top-level receipt with no nested copy.
+
+The existing agent workflow benchmark separately covers mixed comment/redline
+work, independent batch permutations, stale and ambiguous targeting recovery,
+and cross-author attribution. File-based and serializer-backed stdin operations
+are both exercised with the same Unicode payload by the CLI protocol suite.
+
+## Documentation and package parity
+
+The shipped documentation now includes `docs/SKILL_AUTHORING.md`. It separates
+safety invariants, workflow policy, transport choices, four-field recovery, and
+presentation rules. Executable documentation tests require each ordinary-use
+section to lead with focused contextual extraction and require skills to cite
+`humanReference`, provisions, or headings rather than machine paragraph
+ordinals.
+
+The npm allowlist includes the launch card, fast start, knowledge base,
+skill-authoring contract, schema, testing guide, and checked rollout reports.
+Development-only session examples and benchmark scripts remain excluded.
+
+The checked `npm pack --dry-run` contains 152 files (approximately 1.07 MB).
+It includes `node/cli-help.js`, the fast start, skill-authoring contract, and this
+audit; it excludes both agent benchmark scripts and the development session
+example.
+An unpacked tarball invocation reported contract version 7 and the same 16
+capabilities as the source CLI.
+
+## Automated verification
+
+- `npm test`: 110 passed, 0 failed.
+- `npm run check:types`: 123 runtime exports have declarations.
+- `npm run test:isolation`: dependency and Word-API isolation passed.
+- Focused ESLint for every WP-03 through WP-05 source, test, and benchmark file
+  passed.
+- `npm run build` and `npm pack --dry-run`: passed.
+
+## Measurement boundary
+
+These are native runtime, serialized-byte, command-count, and correctness
+measurements. They do not estimate Claude/OpenCode tokens, model reasoning time,
+provider transport latency, or end-to-end harness wall time.

package/index.d.ts

@@ -278,13 +278,15 @@ export function getTrackedChangeAuthors(xmlDocOrElement: Document | Element | nu
 export interface InspectedParagraph {
   index: number; ref: string; paragraphId: string | null; fingerprint: string | null;
   text: string; exactText: string; excerpt: string; inTable: boolean;
-  humanReference: string; styleId: string | null;
+  humanReference: string; provision: string | null; styleId: string | null;
   table: { tableIndex: number; rowIndex: number; cellIndex: number } | null;
   structuralReferences: Array<{ type: 'footnote' | 'endnote' | 'comment'; id: string | null }>;
   headingLevel: number | null; nearestHeading: { level: number; text: string } | null;
   list: { numId: string; level: number; label: string | null; format: string | null } | null;
   hasRevisions: boolean; revisionAuthors: string[]; commentIds: string[];
   segments: RevisionTextSegment[];
+  selectionRole?: 'match' | 'context';
+  contextFor?: number[];
 }
 export interface RevisionToken {
   algorithm: 'sha256';
@@ -295,10 +297,17 @@ export interface RevisionToken {
 }
 
 export interface InspectedComment { id: string; author: string | null; date: string | null; text: string; paraId?: string | null; parentParaId?: string; parentCommentId?: string | null; done?: boolean; paragraphIndex?: number; targetRef?: string; anchoredText?: string; }
-export interface DocumentInspectionOptions { revisionView?: 'accepted' | 'rejected' | 'current'; excerptLength?: number; revisedOnly?: boolean; inTable?: boolean; skipEmpty?: boolean; search?: string; indexes?: number[]; range?: { start: number; end: number } | [number, number]; digestFn?: (bytes: Uint8Array) => string; }
+export interface DocumentInspectionOptions { revisionView?: 'accepted' | 'rejected' | 'current'; excerptLength?: number; revisedOnly?: boolean; inTable?: boolean; skipEmpty?: boolean; search?: string; indexes?: number[]; range?: { start: number; end: number } | [number, number]; around?: number; limit?: number; after?: number; digestFn?: (bytes: Uint8Array) => string; }
+export interface DocumentInspectionSelection {
+  search?: string; caseSensitive?: false; totalMatches: number; returnedMatches: number;
+  returnedParagraphs: number; truncated: boolean; nextAfter: number | null;
+  limit?: number; after?: number; around?: number; softByteLimit?: number;
+  oversizeItem?: boolean; contextTruncated?: boolean;
+}
 export interface DocumentInspectionResult {
   status: 'ok' | 'error'; paragraphs: InspectedParagraph[]; comments: InspectedComment[];
   revisionAuthors?: string[]; commentAuthors?: string[]; counts?: { paragraphs: number; comments: number; revisedParagraphs: number };
+  selection?: DocumentInspectionSelection;
   revisionToken?: RevisionToken | null;
   coveredParts?: string[];
   warnings: string[]; error?: RedlineError;