@ansonlai/docx-redline-js 0.6.0 → 0.6.1

package/node/cli-help.js

@@ -0,0 +1,209 @@
+const option = (key, name, description) => Object.freeze({ key, name, description });
+
+const HELP = option('help', '--help, -h', 'Return machine-readable help without opening a document.');
+const AUTHOR = option('author', '--author <name>, -a <name>', 'Reviewer name; falls back to DOCX_REDLINE_AUTHOR, then AI Redliner.');
+const OUTPUT = option('output', '--output <file>, -o <file>', 'Write to this destination; the source is not overwritten.');
+const IN_PLACE = option('inPlace', '--in-place, -i', 'Explicitly overwrite the source document.');
+const FORCE = option('force', '--force, -f', 'Allow replacement of an existing destination.');
+const NO_OVERWRITE = option('noOverwrite', '--no-overwrite, --no-clobber', 'Refuse replacement of an existing destination.');
+const ALL_AUTHORS = option('allAuthors', '--all-authors', 'Resolve review content for every author; requires explicit user authorization.');
+const COMPACT = option('compact', '--compact', 'Emit one-line JSON to reduce provider-visible output bytes.');
+
+const INSPECTION_OPTIONS = Object.freeze([
+    HELP,
+    option('search', '--search <text>', 'Case-insensitive substring search.'),
+    option('revised', '--revised', 'Select paragraphs containing tracked revisions.'),
+    option('table', '--table', 'Select paragraphs inside tables.'),
+    option('body', '--body', 'Select paragraphs outside tables.'),
+    option('nonEmpty', '--non-empty', 'Exclude empty paragraphs; this is not a narrow document scope.'),
+    option('index', '--index <N>', 'Select one 1-based machine paragraph index.'),
+    option('indexes', '--indexes <N,N,...>', 'Select comma-separated 1-based machine paragraph indexes.'),
+    option('range', '--range <START:END>', 'Select an inclusive range of 1-based machine paragraph indexes.'),
+    option('view', '--view <accepted|rejected|current>', 'Select the revision view; restore discovery normally uses rejected.'),
+    option('around', '--around <N>, --context <N>, -C <N>', 'With --search, include 0-20 physical paragraphs around each returned match.'),
+    option('limit', '--limit <N>', 'Return at most N direct matches; surrounding context does not count.'),
+    option('after', '--after <INDEX>', 'Continue after this exclusive 1-based source paragraph index.'),
+    option('all', '--all', 'Explicitly bypass default result and soft output limits.')
+]);
+
+const MUTATION_DESTINATION_OPTIONS = Object.freeze([
+    AUTHOR, OUTPUT, IN_PLACE, FORCE, NO_OVERWRITE
+]);
+
+const APPLY_EXAMPLES = Object.freeze([
+    {
+        description: 'Ordinary tracked replacement; modified is the complete desired accepted-view paragraph.',
+        operation: {
+            type: 'redline',
+            target: { exactText: 'Original clause.', paragraphId: '1A2B3C4D' },
+            modified: 'Revised clause.'
+        }
+    },
+    {
+        description: 'Comment the complete target paragraph.',
+        operation: {
+            type: 'comment',
+            target: { exactText: 'Clause to review.', paragraphId: '2A2B3C4D' },
+            commentContent: 'Please confirm this language.'
+        }
+    },
+    {
+        description: 'Counterpropose a wholly foreign-deleted paragraph found through --view rejected.',
+        operation: {
+            type: 'restore',
+            target: {
+                exactText: 'Deleted source paragraph.',
+                paragraphId: '3A2B3C4D',
+                revisionView: 'rejected'
+            },
+            modified: 'Restored and revised paragraph.'
+        }
+    }
+]);
+
+export const CLI_COMMAND_HELP = Object.freeze({
+    version: {
+        summary: 'Report the machine contract version and capabilities.',
+        usage: 'docx-redline version',
+        options: [HELP],
+        notes: ['Wrappers should require only the capabilities they use.'],
+        examples: [{ command: 'docx-redline version' }]
+    },
+    inspect: {
+        summary: 'Inspect detailed paragraph, revision, comment, and structure metadata.',
+        usage: 'docx-redline inspect <file.docx> [options]',
+        options: INSPECTION_OPTIONS,
+        notes: [
+            'Prefer a focused --search, --index, or --range. Use extract when only exact edit targets are needed.',
+            'P<number>, index, and paragraph ordinals are machine references, not user-facing Word locations.'
+        ],
+        examples: [
+            { command: 'docx-redline inspect contract.docx --search "force majeure" --around 3' },
+            { command: 'docx-redline inspect contract.docx --range 10:25 --view rejected' }
+        ]
+    },
+    extract: {
+        summary: 'Return compact exact targets and human-facing legal locations.',
+        usage: 'docx-redline extract <file.docx> [options]',
+        options: INSPECTION_OPTIONS,
+        notes: [
+            'Search is always case-insensitive.',
+            'Copy exactText plus paragraphId or fingerprint into operations; do not cite P<number> to users.',
+            'Broad results are paginated; follow selection.nextAfter or pass --all deliberately.'
+        ],
+        examples: [
+            { command: 'docx-redline extract contract.docx --search "force majeure" --around 3' },
+            { command: 'docx-redline extract contract.docx --range 10:25' }
+        ]
+    },
+    preflight: {
+        summary: 'Check an operation batch without mutating or writing a document.',
+        usage: 'docx-redline preflight <file.docx> --operations <file.json|-> [options]',
+        options: [
+            HELP,
+            option('operations', '--operations <file.json|->, --operations-file <file>', 'Read an operation array/envelope from a UTF-8 file or stdin.'),
+            AUTHOR,
+            option('strictTargets', '--strict-targets', 'Require strict target descriptors.'),
+            option('target', '--target <text>', 'Inline one-operation target text.'),
+            option('modified', '--modified <text>', 'Complete desired accepted-view target content.'),
+            option('comment', '--comment <text>', 'Create an inline comment operation.'),
+            option('textToComment', '--text-to-comment <text>', 'Anchor an inline comment to an exact subspan.'),
+            option('targetRef', '--target-ref <N>', 'Disambiguate an inline target with a 1-based machine index.'),
+            option('existingRevisions', '--existing-revisions <policy>', 'Select the explicit existing-revision policy.')
+        ],
+        notes: ['Normal apply already performs validation; preflight is optional.'],
+        examples: [{ command: 'docx-redline preflight contract.docx --operations operations.json --author "Editor"' }]
+    },
+    apply: {
+        summary: 'Apply canonical document operations and write a derived DOCX.',
+        usage: 'docx-redline apply <file.docx> --operations <file.json|-> [options]',
+        options: [
+            HELP,
+            option('operations', '--operations <file.json|->, --operations-file <file>', 'Read an operation array/envelope from a UTF-8 file or serializer-backed stdin.'),
+            ...MUTATION_DESTINATION_OPTIONS,
+            option('noClobber', '--no-clobber', 'Alias of --no-overwrite.'),
+            option('expectedRevision', '--expected-revision <token|json>', 'Reject a stale package revision.'),
+            option('target', '--target <text>', 'Inline one-operation target text.'),
+            option('modified', '--modified <text>', 'Complete desired accepted-view target content.'),
+            option('comment', '--comment <text>', 'Create an inline comment operation.'),
+            option('textToComment', '--text-to-comment <text>', 'Anchor an inline comment to an exact subspan.'),
+            option('targetRef', '--target-ref <N>', 'Disambiguate an inline target with a 1-based machine index.'),
+            option('existingRevisions', '--existing-revisions <policy>', 'Select revision handling; cross-author slicing must be deliberate.'),
+            option('atomic', '--atomic[=true|false]', 'Choose all-or-nothing or progressive batch execution.'),
+            option('generateRedlines', '--generate-redlines[=true|false]', 'Control tracked-change generation.'),
+            option('noRedlines', '--no-redlines', 'Apply clean text without tracked-change markup.'),
+            option('requireComplete', '--require-complete', 'Return exit code 3 for progressive partial completion.'),
+            option('profile', '--profile agent', 'Require complete machine execution without selecting atomic/progressive or revision policy; explicit flags compose with it.'),
+            COMPACT
+        ],
+        notes: [
+            'modified is complete desired accepted-view content, not only inserted words.',
+            'Use a structured JSON file or serializer-backed stdin; never interpolate legal text through raw shell quoting.',
+            'The source is never overwritten unless --in-place is explicit.',
+            'The agent profile keeps progressive execution unless --atomic is explicit and does not change existing-revision policy.',
+            'Do not accept/reject foreign revisions or remove comments without user authorization.',
+            'Inspect completion, written, outputPath, every result, error.recovery, and retryPlan.'
+        ],
+        examples: APPLY_EXAMPLES
+    },
+    accept: {
+        summary: 'Accept tracked revisions by one author or all authors.',
+        usage: 'docx-redline accept <file.docx> (--author <name>|--all-authors) [options]',
+        options: [HELP, ...MUTATION_DESTINATION_OPTIONS, option('allAuthors', '--all-authors', ALL_AUTHORS.description), option('noClobber', '--no-clobber', 'Alias of --no-overwrite.'), COMPACT],
+        notes: ['Accepting foreign review content requires explicit user authorization.'],
+        examples: [{ command: 'docx-redline accept reviewed.docx --author "Editor"' }]
+    },
+    reject: {
+        summary: 'Reject tracked revisions by one author or all authors.',
+        usage: 'docx-redline reject <file.docx> (--author <name>|--all-authors) [options]',
+        options: [HELP, ...MUTATION_DESTINATION_OPTIONS, option('allAuthors', '--all-authors', ALL_AUTHORS.description), option('noClobber', '--no-clobber', 'Alias of --no-overwrite.'), COMPACT],
+        notes: ['Rejecting foreign review content requires explicit user authorization.'],
+        examples: [{ command: 'docx-redline reject reviewed.docx --author "Editor"' }]
+    },
+    'delete-comments': {
+        summary: 'Delete comments by one author or all authors.',
+        usage: 'docx-redline delete-comments <file.docx> (--author <name>|--all-authors) [options]',
+        options: [HELP, ...MUTATION_DESTINATION_OPTIONS, option('allAuthors', '--all-authors', ALL_AUTHORS.description), option('noClobber', '--no-clobber', 'Alias of --no-overwrite.'), COMPACT],
+        notes: ['Removing reviewer comments requires explicit user authorization.'],
+        examples: [{ command: 'docx-redline delete-comments reviewed.docx --author "Reviewer"' }]
+    },
+    validate: {
+        summary: 'Validate revision markup and DOCX package wiring.',
+        usage: 'docx-redline validate <file.docx> [--baseline <file.docx>]',
+        options: [HELP, option('baseline', '--baseline <file.docx>', 'Report only validation issues introduced relative to a baseline package.')],
+        notes: ['Apply validates before writing; use this command for an explicit audit.'],
+        examples: [{ command: 'docx-redline validate reviewed.docx --baseline contract.docx' }]
+    }
+});
+
+export const CLI_COMMANDS = Object.freeze(Object.keys(CLI_COMMAND_HELP));
+
+export function commandOptionKeys(command) {
+    return (CLI_COMMAND_HELP[command]?.options || []).map(item => item.key);
+}
+
+export function buildCliHelp(command = null) {
+    if (!command) {
+        return {
+            status: 'ok',
+            command: 'help',
+            usage: 'docx-redline <command> [file.docx] [options]',
+            commands: CLI_COMMANDS.map(name => ({ name, summary: CLI_COMMAND_HELP[name].summary })),
+            notes: ['Run docx-redline <command> --help for flags, semantics, and bounded examples.'],
+            documentation: ['AGENTS.md', 'docs/AGENT_FAST_START.md', 'docs/SKILL_AUTHORING.md', 'docs/schemas/document-operations.schema.json']
+        };
+    }
+    const entry = CLI_COMMAND_HELP[command];
+    if (!entry) return null;
+    return {
+        status: 'ok',
+        command: 'help',
+        forCommand: command,
+        summary: entry.summary,
+        usage: entry.usage,
+        options: entry.options.map(({ key: _key, ...publicOption }) => publicOption),
+        notes: entry.notes,
+        examples: entry.examples,
+        documentation: ['AGENTS.md', 'docs/AGENT_FAST_START.md', 'docs/SKILL_AUTHORING.md', 'docs/schemas/document-operations.schema.json']
+    };
+}

package/node/cli.js

@@ -7,9 +7,12 @@ import { validateRedlineOoxml } from '../core/redline-validation.js';
 import { configureLogger } from '../adapters/logger.js';
 import { isExistingRevisionsPolicy } from '../services/document-operation-contract.js';
 import { normalizeErrorWithRecovery } from '../services/error-recovery.js';
-
-const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
-const CLI_CONTRACT_VERSION = 5;
+import { buildCliHelp, CLI_COMMANDS, commandOptionKeys } from './cli-help.js';
+
+const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
+const CLI_CONTRACT_VERSION = 7;
+const DEFAULT_INSPECTION_LIMIT = 20;
+const INSPECTION_SOFT_BYTE_LIMIT = 48 * 1024;
 const CLI_CAPABILITIES = [
     'atomic-batch-results-on-package-failure',
     'baseline-aware-validation',
@@ -20,19 +23,15 @@ const CLI_CAPABILITIES = [
     'recovery-envelope-v1',
     'require-complete-exit',
     'operations-stdin',
-    'agent-profile-v1'
+    'agent-safety-profile-v2',
+    'command-help-v1',
+    'inspection-context-v1',
+    'bounded-inspection-v1',
+    'human-document-references-v1',
+    'deduplicated-cli-receipts',
+    'compact-cli-json-v1'
 ];
-const commandOptions = {
-    version: new Set(['help']),
-    inspect: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
-    extract: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
-    preflight: new Set(['help', 'operations', 'author', 'strictTargets', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions']),
-    apply: new Set(['help', 'operations', 'author', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber', 'expectedRevision', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions', 'atomic', 'generateRedlines', 'noRedlines', 'requireComplete', 'profile']),
-    accept: new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
-    reject: new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
-    'delete-comments': new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
-    validate: new Set(['help', 'baseline'])
-};
+const commandOptions = Object.fromEntries(CLI_COMMANDS.map(command => [command, new Set(commandOptionKeys(command))]));
 
 function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: normalizeErrorWithRecovery({ code, message, ...(details ? { details } : {}) }), exitCode }; }
 const optionAliases = new Map([
@@ -46,8 +45,10 @@ const optionAliases = new Map([
     ['no-clobber', 'noClobber'],
     ['no-redlines', 'noRedlines'],
     ['generate-redlines', 'generateRedlines'],
-    ['require-complete', 'requireComplete']
-]);
+    ['require-complete', 'requireComplete'],
+    ['context', 'around'],
+    ['C', 'around']
+]);
 function parseArgs(argv) {
     const positionals = []; const flags = {};
     for (let index = 0; index < argv.length; index++) {
@@ -68,11 +69,19 @@ function positiveInteger(value) {
     const parsed = /^\d+$/.test(text) ? Number(text) : null;
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
 }
-function invalidFilter(message) {
-    const error = new Error(message);
-    error.code = 'INVALID_FILTER';
-    return error;
-}
+function invalidFilter(message) {
+    const error = new Error(message);
+    error.code = 'INVALID_FILTER';
+    return error;
+}
+function boundedPositiveInteger(value, optionName, maximum = Number.MAX_SAFE_INTEGER) {
+    const parsed = positiveInteger(value);
+    if (parsed == null || parsed > maximum) {
+        const upperBound = maximum < Number.MAX_SAFE_INTEGER ? ` no greater than ${maximum}` : '';
+        throw invalidFilter(`${optionName} must be a positive integer${upperBound}.`);
+    }
+    return parsed;
+}
 function parseIndexes(value) {
     const tokens = String(value).split(',');
     if (!tokens.length || tokens.some(token => positiveInteger(token) == null)) {
@@ -109,10 +118,22 @@ function inspectionOptions(flags) {
         const index = positiveInteger(flags.index);
         if (index == null) throw invalidFilter('--index must be a positive 1-based integer.');
         options.indexes = [index];
-    }
-    if (flags.indexes !== undefined) options.indexes = parseIndexes(flags.indexes);
-    if (flags.range !== undefined) options.range = parseRange(flags.range);
-    if (flags.view) {
+    }
+    if (flags.indexes !== undefined) options.indexes = parseIndexes(flags.indexes);
+    if (flags.range !== undefined) options.range = parseRange(flags.range);
+    if (flags.around !== undefined) {
+        const text = String(flags.around).trim();
+        if (!/^\d+$/.test(text) || Number(text) > 20) {
+            throw invalidFilter('--around must be an integer from 0 through 20.');
+        }
+        options.around = Number(text);
+        if (!flags.search) throw invalidFilter('--around requires --search.');
+    }
+    if (flags.limit !== undefined) options.limit = boundedPositiveInteger(flags.limit, '--limit', 200);
+    if (flags.after !== undefined) options.after = boundedPositiveInteger(flags.after, '--after');
+    if (flags.all && flags.limit !== undefined) throw invalidFilter('Use --all or --limit, not both.');
+    if (!flags.all && flags.limit === undefined && selectors.length === 0) options.limit = DEFAULT_INSPECTION_LIMIT;
+    if (flags.view) {
         if (!['accepted', 'rejected', 'current'].includes(String(flags.view))) {
             throw invalidFilter('--view must be accepted, rejected, or current.');
         }
@@ -191,6 +212,114 @@ function serializable(value) {
     return rest;
 }
 
+function compactExtractParagraph(paragraph) {
+    const {
+        humanReference, provision, nearestHeading, index, ref, paragraphId,
+        fingerprint, revisionView, exactText, inTable, list, selectionRole,
+        contextFor
+    } = paragraph;
+    return {
+        humanReference,
+        provision,
+        nearestHeading,
+        index,
+        ref,
+        paragraphId,
+        fingerprint,
+        revisionView,
+        exactText,
+        inTable,
+        list,
+        ...(selectionRole ? { selectionRole } : {}),
+        ...(Array.isArray(contextFor) ? { contextFor } : {})
+    };
+}
+
+function inspectionResponseBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value, null, 2), 'utf8') + 1;
+}
+
+function boundInspectionResponse(value, { bypass = false, broadDetailed = false } = {}) {
+    const base = {
+        ...value,
+        machineReferencesAreNotUserLocations: true,
+        ...(broadDetailed ? {
+            notes: [
+                'This detailed inspection was bounded. Prefer extract --search or an explicit --range for ordinary targeting.'
+            ]
+        } : {})
+    };
+    if (bypass) return base;
+
+    let paragraphs = [...(base.paragraphs || [])];
+    const sourceSelection = base.selection || {};
+    const totalMatches = Number.isInteger(sourceSelection.totalMatches)
+        ? sourceSelection.totalMatches
+        : paragraphs.filter(item => item.selectionRole !== 'context').length;
+    const initialReturnedMatches = Number.isInteger(sourceSelection.returnedMatches)
+        ? sourceSelection.returnedMatches
+        : paragraphs.filter(item => item.selectionRole !== 'context').length;
+    let contextTruncated = false;
+
+    const assemble = (oversizeItem = false) => {
+        const directIndexes = new Set(paragraphs
+            .filter(item => item.selectionRole !== 'context')
+            .map(item => item.index));
+        paragraphs = paragraphs
+            .map(item => item.selectionRole === 'context'
+                ? { ...item, contextFor: (item.contextFor || []).filter(index => directIndexes.has(index)) }
+                : item)
+            .filter(item => item.selectionRole !== 'context' || item.contextFor.length > 0);
+        const direct = paragraphs.filter(item => item.selectionRole !== 'context');
+        const lastDirect = direct[direct.length - 1] || null;
+        const paragraphIndexes = new Set(paragraphs.map(item => item.index));
+        const comments = Array.isArray(base.comments)
+            ? base.comments.filter(comment => paragraphIndexes.has(comment.paragraphIndex))
+            : base.comments;
+        const budgetTruncated = direct.length < initialReturnedMatches;
+        return {
+            ...base,
+            paragraphs,
+            ...(Array.isArray(base.comments) ? { comments } : {}),
+            selection: {
+                ...sourceSelection,
+                totalMatches,
+                returnedMatches: direct.length,
+                returnedParagraphs: paragraphs.length,
+                truncated: sourceSelection.truncated === true || budgetTruncated || contextTruncated,
+                nextAfter: sourceSelection.truncated === true || budgetTruncated
+                    ? (lastDirect?.index ?? sourceSelection.nextAfter ?? null)
+                    : null,
+                softByteLimit: INSPECTION_SOFT_BYTE_LIMIT,
+                oversizeItem,
+                ...(contextTruncated ? { contextTruncated: true } : {})
+            }
+        };
+    };
+
+    let result = assemble();
+    while (inspectionResponseBytes(result) > INSPECTION_SOFT_BYTE_LIMIT) {
+        const directPositions = paragraphs
+            .map((item, position) => item.selectionRole !== 'context' ? position : -1)
+            .filter(position => position >= 0);
+        if (directPositions.length > 1) {
+            paragraphs.splice(directPositions[directPositions.length - 1], 1);
+            result = assemble();
+            continue;
+        }
+        const contextPosition = paragraphs.findLastIndex(item => item.selectionRole === 'context');
+        if (contextPosition >= 0) {
+            paragraphs.splice(contextPosition, 1);
+            contextTruncated = true;
+            result = assemble();
+            continue;
+        }
+        result = assemble(true);
+        break;
+    }
+    return result;
+}
+
 function boundedText(value, limit = 512) {
     const text = String(value ?? '');
     return text.length > limit ? `${text.slice(0, limit)}…` : text;
@@ -219,7 +348,7 @@ function compactError(error) {
         compact.candidates = error.candidates.map(candidate => {
             if (!candidate || typeof candidate !== 'object') return candidate;
             const excerpt = boundedText(candidate.excerpt ?? candidate.exactText ?? candidate.text ?? '', 240);
-            return { ...compactResolvedTarget(candidate), ...(excerpt ? { excerpt } : {}) };
+            return { ...compactResolvedTarget(candidate, { preserveMatchDetails: true }), ...(excerpt ? { excerpt } : {}) };
         });
     }
     for (const field of ['recovery', 'issueSummary', 'expectedRevision', 'currentRevision']) {
@@ -230,7 +359,7 @@ function compactError(error) {
             ...error.context,
             ...(error.context.currentTarget ? {
                 currentTarget: {
-                    ...compactResolvedTarget(error.context.currentTarget),
+                    ...compactResolvedTarget(error.context.currentTarget, { preserveMatchDetails: true }),
                     excerpt: boundedText(
                         error.context.currentTarget.excerpt
                             ?? error.context.currentTarget.exactText
@@ -244,7 +373,7 @@ function compactError(error) {
     }
     if (error.sourceTarget && typeof error.sourceTarget === 'object') {
         compact.sourceTarget = {
-            ...compactResolvedTarget(error.sourceTarget),
+            ...compactResolvedTarget(error.sourceTarget, { preserveMatchDetails: true }),
             excerpt: boundedText(error.sourceTarget.text ?? error.sourceTarget.exactText ?? '', 240)
         };
     }
@@ -252,10 +381,32 @@ function compactError(error) {
     return compact;
 }
 
-function compactResolvedTarget(target) {
+function compactTargetTextMatch(match, preserveDetails = false) {
+    if (!match || typeof match !== 'object') return match;
+    if (preserveDetails) return match;
+    if (match.mode === 'exact') return undefined;
+    const differenceCount = Number.isInteger(match.differenceCount)
+        ? match.differenceCount
+        : (Array.isArray(match.differences) ? match.differences.length : 0);
+    return {
+        ...(match.mode ? { mode: match.mode } : {}),
+        differenceCount
+    };
+}
+
+function compactResolvedTarget(target, { preserveMatchDetails = false } = {}) {
     if (!target || typeof target !== 'object') return target;
-    const { text: _text, exactText: _exactText, ...compact } = target;
-    return compact;
+    const {
+        text: _text,
+        exactText: _exactText,
+        targetTextMatch,
+        ...compact
+    } = target;
+    const compactMatch = compactTargetTextMatch(targetTextMatch, preserveMatchDetails);
+    return {
+        ...compact,
+        ...(compactMatch ? { targetTextMatch: compactMatch } : {})
+    };
 }
 
 function compactReceipt(receipt) {
@@ -271,12 +422,13 @@ function compactReceipt(receipt) {
 
 function compactOperationResult(result) {
     if (!result || typeof result !== 'object') return result;
+    const { receipt: _receipt, ...withoutReceipt } = result;
+    const preserveMatchDetails = result.status === 'error' || !!result.error;
     return {
-        ...result,
-        ...(result.resolvedTarget ? { resolvedTarget: compactResolvedTarget(result.resolvedTarget) } : {}),
-        ...(result.resolvedAnchor ? { resolvedAnchor: compactResolvedTarget(result.resolvedAnchor) } : {}),
+        ...withoutReceipt,
+        ...(result.resolvedTarget ? { resolvedTarget: compactResolvedTarget(result.resolvedTarget, { preserveMatchDetails }) } : {}),
+        ...(result.resolvedAnchor ? { resolvedAnchor: compactResolvedTarget(result.resolvedAnchor, { preserveMatchDetails }) } : {}),
         ...(result.error ? { error: compactError(result.error) } : {}),
-        ...(result.receipt ? { receipt: compactReceipt(result.receipt) } : {}),
         ...(Array.isArray(result.warnings) ? { warnings: result.warnings.map(warning => boundedText(warning)) } : {})
     };
 }
@@ -370,10 +522,14 @@ function subtractValidationIssues(issues, baselineIssues) {
 }
 
 export async function executeCli(argv, io = process) {
-    const { command, input: rawInput, extraPositionals, flags } = parseArgs(argv);
-    if (command === 'help' || flags.help) return { status: 'ok', command: 'help', usage: 'docx-redline <version|inspect|extract|preflight|apply|accept|reject|delete-comments|validate> [file.docx] [options]' };
-    if (!command) return cliError('COMMAND_REQUIRED', 'A command is required.');
-    if (!['version','inspect','extract','preflight','apply','accept','reject','delete-comments','validate'].includes(command)) return cliError('UNKNOWN_COMMAND', `Unknown command: ${command}`);
+    const { command, input: rawInput, extraPositionals, flags } = parseArgs(argv);
+    if (command === 'help' || flags.help) {
+        const requestedCommand = command === 'help' ? rawInput : command;
+        const help = buildCliHelp(requestedCommand || null);
+        return help || cliError('UNKNOWN_COMMAND', `Unknown command: ${requestedCommand}`);
+    }
+    if (!command) return cliError('COMMAND_REQUIRED', 'A command is required.');
+    if (!CLI_COMMANDS.includes(command)) return cliError('UNKNOWN_COMMAND', `Unknown command: ${command}`);
     if (command === 'version') {
         if (rawInput || extraPositionals.length > 0) return cliError('UNEXPECTED_ARGUMENT', `Unexpected argument: ${rawInput || extraPositionals[0]}`);
         const optionError = validateCommandOptions(command, flags, []);
@@ -404,11 +560,27 @@ export async function executeCli(argv, io = process) {
     let buffer; try { buffer = await readFile(input); } catch (error) { return cliError('INPUT_READ_FAILED', error.message); }
     try {
         const document = openDocx(buffer);
-        if (command === 'inspect') return { ...document.inspect(inspectOptions), command, input, indexBase: 1 };
-        if (command === 'extract') {
-            const inspected = document.inspect(inspectOptions);
-            return { status: inspected.status, command, input, indexBase: 1, paragraphs: inspected.paragraphs.map(({ index, ref, paragraphId, fingerprint, exactText, inTable, list, nearestHeading }) => ({ index, ref, paragraphId, fingerprint, exactText, inTable, list, nearestHeading })), warnings: inspected.warnings };
-        }
+        if (command === 'inspect') {
+            const inspected = document.inspect(inspectOptions);
+            const broadDetailed = !flags.search && flags.index === undefined
+                && flags.indexes === undefined && flags.range === undefined;
+            return boundInspectionResponse(
+                { ...inspected, command, input, indexBase: 1 },
+                { bypass: !!flags.all, broadDetailed }
+            );
+        }
+        if (command === 'extract') {
+            const inspected = document.inspect(inspectOptions);
+            return boundInspectionResponse({
+                status: inspected.status,
+                command,
+                input,
+                indexBase: 1,
+                paragraphs: inspected.paragraphs.map(compactExtractParagraph),
+                ...(inspected.selection ? { selection: inspected.selection } : {}),
+                warnings: inspected.warnings
+            }, { bypass: !!flags.all });
+        }
         if (command === 'validate') {
             const issues = await collectValidationIssues(buffer);
             if (flags.baseline) {
@@ -470,7 +642,7 @@ export async function executeCli(argv, io = process) {
                 : (!flags.noRedlines);
             const atomic = flags.atomic !== undefined
                 ? (flags.atomic === true || flags.atomic === 'true')
-                : agentProfile;
+                : false;
             const requireComplete = flags.requireComplete !== undefined
                 ? (flags.requireComplete === true || flags.requireComplete === 'true')
                 : agentProfile;
@@ -514,7 +686,9 @@ export async function executeCli(argv, io = process) {
 
 export async function runCli(argv = process.argv.slice(2), io = process) {
     configureLogger({}, { level: 'silent' });
-    const result = await executeCli(argv, io); io.stdout.write(`${JSON.stringify(serializable(result), null, 2)}\n`);
+    const result = await executeCli(argv, io);
+    const compactJson = parseArgs(argv).flags.compact === true;
+    io.stdout.write(`${JSON.stringify(serializable(result), null, compactJson ? 0 : 2)}\n`);
     return Number.isInteger(result.exitCode) && result.exitCode !== 0
         ? result.exitCode
         : (result.status === 'error' ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",
@@ -45,12 +45,16 @@
     "orchestration/",
     "scripts/",
     "!scripts/benchmark-agent-workflow.mjs",
+    "!scripts/benchmark-agent-cli-discovery.mjs",
     "!scripts/lib/agent-performance-cases.mjs",
     "docs/AGENT_FAST_START.md",
     "docs/AGENT_KNOWLEDGE_BASE.md",
+    "docs/SKILL_AUTHORING.md",
     "docs/TESTING.md",
     "docs/schemas/document-operations.schema.json",
     "docs/validation-reports/2026-09-12-agent-protocol-rollout.md",
+    "docs/validation-reports/2026-09-12-agent-cli-discovery-baseline.md",
+    "docs/validation-reports/2026-09-13-agent-cli-efficiency-rollout.md",
     "index.js",
     "index.d.ts",
     "dist/",
@@ -88,6 +92,7 @@
     "coverage:gaps": "node scripts/report-coverage-gaps.mjs",
     "benchmark:session": "node scripts/benchmark-operation-session.mjs",
     "benchmark:agent": "node scripts/benchmark-agent-workflow.mjs",
+    "benchmark:agent-cli": "node scripts/benchmark-agent-cli-discovery.mjs",
     "benchmark:targeting": "node scripts/benchmark-targeting-hot-paths.mjs",
     "benchmark:tests": "node scripts/benchmark-test-runner.mjs",
     "profile:routes": "node scripts/profile-route-selection.mjs",