@superdoc/sdk 2.25.0-next.1 → 2.25.0-next.10

package/dist/presets/full.js

@@ -0,0 +1,1795 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONTRACT } from '../generated/contract.js';
+import { isRecord } from '../guards.js';
+import { SuperDocCliError } from '../runtime/errors.js';
+import { operationAcceptsTrackedMode } from '../runtime/tracked-support.js';
+import { ACTION_ARG_SCHEMA, AGENT_TOOL_DEFINITIONS, ALLOW_ALL_DIRECT_ACTIONS, listAgentTools, } from '../agent/catalog.js';
+import { getOperationCatalogEntry } from '../agent/operation-catalog.js';
+import { corePreset, readPromptFile, stripCorruptedToolArgKeys } from './core.js';
+export const HIDDEN_PARAMS = new Set(['doc', 'sessionId', 'out', 'expectedRevision', 'force']);
+const RESERVED_ARG_KEYS = new Set(['doc', 'sessionId', 'out', 'expectedRevision']);
+const RESULT_CHAR_CAP = 8_000;
+const SCHEMA_CHAR_CAP = 1_800;
+const NOT_CATALOGUED = new Set(['doc.save', 'doc.close', 'doc.executeCode']);
+const NOT_CATALOGUED_DOMAINS = new Set(['preset', 'session']);
+const OPAQUE_RESULT_OPS = new Set([
+    'doc.diff.capture',
+    'doc.diff.compare',
+    'doc.markdownToFragment',
+    'doc.htmlToFragment',
+    'doc.getMarkdown',
+    'doc.getHtml',
+    'doc.extract',
+    'doc.clipboard.parse',
+    'doc.mutations.preview',
+]);
+function domainOf(operationId) {
+    const parts = operationId.split('.');
+    return parts.length >= 3 ? parts[1] : 'document';
+}
+function isDocumentOp(op) {
+    return (op.sdkSurface === 'document' &&
+        !NOT_CATALOGUED.has(op.operationId) &&
+        !NOT_CATALOGUED_DOMAINS.has(domainOf(op.operationId)));
+}
+function isCallableOp(op) {
+    return isDocumentOp(op) && op.skipAsATool !== true;
+}
+function contractOps() {
+    return Object.values(CONTRACT.operations).filter(isCallableOp);
+}
+const CATALOG_SIZE = contractOps().length;
+const DEFAULT_OPTS = 'leanschema,leanaddendum,searchschemas,compactsearch,compactinspect,trustcalls,quickref';
+const FULL_OPTS = new Set((process.env.SUPERDOC_FULL_OPTS ?? DEFAULT_OPTS)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean));
+const opt = (name) => FULL_OPTS.has(name);
+const LEAN_ADDENDUM = `============================================================
+EXTENDED SURFACE — the whole Document API (full preset)
+============================================================
+
+superdoc_perform_action covers the common verbs; every other engine operation is one step away. Escalation ladder, always in this order:
+
+1. superdoc_perform_action — when a named action fits, use it. It matches surrounding formatting and numbering for you. Helper actions for the frequent gaps: insert_image {src, position?, anchorText?, caption?}, insert_footnote {anchorText, occurrence?, content, noteType?}, shade_cells {tableOrdinal?, rowIndex?, columnIndex?, color}, compare_with_file {path} (differences land here as tracked changes).
+2. superdoc_api_call — {operationId, args}, or several in ONE round trip: {calls:[{operationId, args}, …]} for repetitive work (shade eight cells, insert twelve paragraphs). Runs in order, stops at the first failure, returns per-call receipts. The operations under QUICK REFERENCE need no lookup: call them straight away; an argument the operation does not accept is refused with its parameter list and changes nothing.
+3. superdoc_api_search — only for an operation that is neither an action nor in QUICK REFERENCE: {query:"page margins"} or {domain:"sections"}. Hits include their parameter schema; look up the rest with ONE {operationIds:[…]} call (not one call per id). One search, then act.
+{{QUICK_REFERENCE}}
+
+Where things live (ids for superdoc_api_call):
+- Page layout: doc.sections.list → sectionId, then doc.sections.setPageMargins / setPageSetup / setColumns / setPageNumbering / setTitlePage / setPageBorders; doc.create.sectionBreak.
+- Header / footer text: doc.sections.list → doc.headerFooters.list → (if the slot has no explicit part) doc.headerFooters.parts.create {kind} → doc.headerFooters.refs.set {target:{kind:"headerFooterSlot", section:{kind:"section", sectionId}, headerFooterKind, variant}, refId}. A new part already holds ONE empty paragraph: write into it (doc.blocks.list {in:<story>} for its blockId, then doc.insert {value, type:"text", in:<story>, blockId, offset:0}); do not add a second paragraph. Header/footer doc.insert and doc.replace refuse block targets: use target:{kind:"selection", start:{kind:"text", blockId, offset}, end:{kind:"text", blockId, offset}} plus in:<story>. Story = {kind:"story", storyType:"headerFooterSlot", section:{kind:"section", sectionId}, headerFooterKind, variant}. Page number: doc.fields.insert {mode:"raw", instruction:"PAGE", at:{kind:"text", story:<same story>, segments:[{blockId, range:{start:N, end:N}}]}} after the text "Page " (N = its length); "Page N of M" adds " of " and a NUMPAGES field. Alignment: doc.format.paragraph.setAlignment with the story on the target. Odd/even variants need doc.sections.setOddEvenHeadersFooters {enabled:true} first, then one part per variant.
+- Section breaks: doc.create.sectionBreak {at:{kind:"after", target:{kind:"block", nodeType, nodeId:<last paragraph of the closing section>}}, representation:"attachToPreviousParagraph", breakType:"nextPage"} closes the section on that paragraph, as Word does; {at:{kind:"before", target:<first paragraph of the new section>}} is the same boundary; {kind:"documentEnd"} appends a new final section. Then doc.sections.list for the new sectionId and doc.sections.setPageNumbering {start:1} to restart numbering. Add one only when the task needs a new section; never delete the paragraph hosting a break to remove it.
+- Tables: doc.tables.setBorders / applyBorderPreset / setShading (table or cell background) / setCellProperties / setColumnWidth / setRowHeight / mergeCells / splitCell / sort / setStyle / setLayout; cell text formatting via doc.format.apply on the cell paragraph (new cells must match their siblings' run formatting — read a sibling with superdoc_inspect includeTableCellRuns:true). A NEW table (create_table, markdown) gets 1pt black borders: when the document already has tables, copy their convention (width, border colour and weight: superdoc_inspect / doc.tables.get a sibling) with doc.tables.setLayout and setBorders. A border weight the request leaves open is Word's 0.5pt. Table background = setShading on the table node, not shade_cells per cell.
+- Formatting: doc.format.apply {target|ref, inline:{bold, italic, underline, color, fontSize, fontFamily, highlight}}; paragraph: doc.format.paragraph.setAlignment / setIndentation / setSpacing / setBorder / setShading / setKeepOptions / setTabStop / setNumbering. Units: colours are bare hex ("0000FF"), fontSize and letterSpacing in points, paragraph indentation and spacing in twips (20 = 1pt, 1440 = 1 inch), setBorder size in eighths of a point (1pt = 8) and space in points (Word's default is 1), table widths in twips where the schema says dxa. Box border: ONE batch of four setBorder {target, side:top|bottom|left|right, style:"single", size, color}; no paragraph setBorders exists.
+- Whole-body font/size: ONE doc.format.apply with target {kind:"selection", start:{kind:"text", blockId:<first paragraph>, offset:0}, end:{kind:"text", blockId:<last paragraph>, offset:<length>}}, not set_font_family or per-paragraph calls; headers, footers and notes are separate story calls.
+- Style definitions: doc.styles.create {id, name, type, conflictPolicy:"replace", custom:false, paragraph:{…}, run:{fontFamily:{ascii, hAnsi}, fontSize:<HALF-points: 11pt = 22>, color:{val:"RRGGBB"}, bold…}} redefines an existing style. Replace keeps every property you do not send (spacing, indentation, keep options, outlineLvl, basedOn, next), so send only what changes; null removes a property. Body-text changes "through the style" go here, not to each paragraph.
+- Headings: insert_heading / doc.create.heading use the document's Heading N style. When superdoc_inspect shows the headings carry another style id (H1, Title2 …), create the paragraph and apply_style {styleId} (or doc.create.paragraph {styleId}) so no second heading style is minted. Promote an existing paragraph with apply_style {styleId} rather than headingLevel when such a style exists.
+- Reference documents: doc.templates.apply {source:{kind:"path", path:"reference.docx"}} copies styles, numbering, page setup and header/footer substrate from a file next to the open document (relative paths resolve there); compare_with_file {path} lands the text differences as tracked changes.
+- Lists: doc.lists.create / attach / detach / indent / outdent / setLevel / setValue / restartAt / setType / setLevelNumbering / setLevelBullet / split / join / merge.
+- Fields, bookmarks, cross-references, hyperlinks, TOC: doc.fields.insert {mode:"raw", instruction}, doc.bookmarks.insert, doc.crossRefs.insert, doc.hyperlinks.insert / wrap / patch, doc.create.tableOfContents, doc.toc.configure / update / remove.
+- Comments & tracked changes beyond the actions: doc.trackChanges.decide target is {kind:"id", id} | {kind:"all"}. Comment, footnote and user-quoted text go in exactly as written unless the task asks to rephrase.
+- Long or structured drafting (memos, multi-section drafts, a document from blank): ONE doc.insert {value:"# Title\\n\\nParagraph…\\n\\n- bullet\\n\\n| a | b |\\n|---|---|", type:"markdown", target:{kind:"block", nodeType, nodeId}, placement:"after"|"before"} — headings, lists and tables become real structures. Read back with doc.getMarkdown.
+- Content controls, protection, metadata, citations, index, captions: browse the matching domain.
+
+Targets for superdoc_api_call:
+- Block: {kind:"block", nodeType:"paragraph"|"heading"|"listItem"|"table"|"tableRow"|"tableCell"|"image"|"tableOfContents"|"sdt", nodeId} (nodeIds from superdoc_inspect).
+- Position (\`at\`): {kind:"documentEnd"} | {kind:"documentStart"} | {kind:"before"|"after", target:<block>}.
+- Text span: {kind:"text", segments:[{blockId, range:{start, end}}]} — character offsets inside that block's text. Add story:{…} inside headers/footers.
+- One locator per call: target OR nodeId, never both.
+- changeMode:"tracked" only where supportsTrackedMode ([tracked]; some refuse it for certain inputs, the error says why), dryRun only where supportsDryRun; otherwise the call is refused. Table and section property changes are direct-only.
+
+Rules for the extended surface:
+- The receipt is the truth. success:true (or a batch with completed === total) IS the verification: do not spend a superdoc_inspect call to confirm it. {success:false, failure} means nothing changed for that call — fix the args (usually a wrong target shape or missing nodeId), retry once. A thrown VALIDATION error also changed nothing. After a TIMEOUT, re-inspect before retrying an insert.
+- Plan the whole edit from one inspect, then send the mutations as ONE batch per phase; repetition is a batch, not a call per item. Save once, at the end.
+- Never claim a capability is missing without a superdoc_api_search first.
+`;
+const QUICK_REFERENCE_IDS = [
+    'doc.insert',
+    'doc.replace',
+    'doc.delete',
+    'doc.blocks.list',
+    'doc.create.paragraph',
+    'doc.create.sectionBreak',
+    'doc.format.apply',
+    'doc.format.paragraph.setAlignment',
+    'doc.format.paragraph.setIndentation',
+    'doc.format.paragraph.setSpacing',
+    'doc.format.paragraph.setKeepOptions',
+    'doc.styles.getCatalog',
+    'doc.styles.create',
+    'doc.comments.list',
+    'doc.comments.get',
+    'doc.comments.create',
+    'doc.comments.patch',
+    'doc.comments.delete',
+    'doc.trackChanges.list',
+    'doc.trackChanges.get',
+    'doc.trackChanges.decide',
+    'doc.tables.get',
+    'doc.tables.getProperties',
+    'doc.tables.getCells',
+    'doc.tables.setCellText',
+    'doc.tables.setColumnWidth',
+    'doc.tables.distributeColumns',
+    'doc.tables.setLayout',
+    'doc.tables.setBorders',
+    'doc.tables.setShading',
+    'doc.tables.mergeCells',
+    'doc.tables.insertRow',
+    'doc.tables.setRowHeight',
+    'doc.tables.setCellProperties',
+    'doc.sections.list',
+    'doc.headerFooters.list',
+    'doc.headerFooters.parts.list',
+    'doc.headerFooters.parts.create',
+    'doc.headerFooters.refs.set',
+    'doc.footnotes.list',
+    'doc.footnotes.get',
+    'doc.footnotes.insert',
+    'doc.footnotes.remove',
+    'doc.fields.insert',
+    'doc.bookmarks.insert',
+    'doc.hyperlinks.list',
+    'doc.hyperlinks.wrap',
+    'doc.lists.setLevelNumbering',
+    'doc.mutations.apply',
+];
+export const QUICK_REFERENCE_OMITTED = new Set([
+    'changeMode',
+    'changeTag',
+    'date',
+    'dryRun',
+    'supportCheck',
+    'namespaces',
+    'sourcePartUri',
+    'dependencies',
+    'nestingPolicy',
+    'capture',
+    'content',
+    'input',
+    'replaceMode',
+    'snapshotId',
+    'expectedSnapshotId',
+    'expectedText',
+    'aliases',
+    'priority',
+    'qFormat',
+    'hidden',
+    'semiHidden',
+    'unhideWhenUsed',
+    'locked',
+    'next',
+    'includeHidden',
+    'includeLatent',
+    'includeDiagnostics',
+    'reviewMode',
+    'commentId',
+    'externalId',
+    'authorId',
+    'authorEmail',
+    'authorImage',
+    'metadata',
+]);
+function shapeHint(schema) {
+    if (schema == null || typeof schema !== 'object')
+        return '';
+    const s = schema;
+    if (s.const !== undefined)
+        return JSON.stringify(s.const);
+    if (Array.isArray(s.oneOf)) {
+        const alts = s.oneOf;
+        const kinds = [
+            ...new Set(alts
+                .map((alt) => alt.properties?.kind?.const)
+                .filter((k) => typeof k === 'string')),
+        ];
+        if (kinds.length > 0 && alts.every((alt) => alt.properties?.kind))
+            return `{kind:${kinds.join('|')}}`;
+        const types = [
+            ...new Set(alts.map((alt) => (typeof alt.type === 'string' ? alt.type : alt.properties ? 'object' : '')).filter(Boolean)),
+        ];
+        return types.length ? types.map((t) => (t === 'object' ? '{…}' : t)).join('|') : '';
+    }
+    if (s.properties && typeof s.properties === 'object') {
+        const keys = Object.keys(s.properties);
+        return `{${keys.slice(0, 6).join(',')}${keys.length > 6 ? ',…' : ''}}`;
+    }
+    if (s.type === 'array')
+        return '[]';
+    return typeof s.type === 'string' && s.type !== 'json' && s.type !== 'object' ? s.type : '';
+}
+function unitHint(p) {
+    if (p.type !== 'number' && p.type !== 'integer')
+        return '';
+    const m = /\b(twips|half-points|points|eighths of a point|EMU|inches|percent)\b/i.exec(p.description ?? '');
+    return m ? m[1].toLowerCase() : '';
+}
+export function quickReference() {
+    const lines = QUICK_REFERENCE_IDS.flatMap((id) => {
+        const op = lookupOp(id);
+        if (!op)
+            return [];
+        const flags = [op.mutates === true ? '' : 'ro', operationAcceptsTrackedMode(op) ? 'tracked' : '']
+            .filter(Boolean)
+            .join(',');
+        const params = visibleParams(op)
+            .filter((p) => !QUICK_REFERENCE_OMITTED.has(p.name))
+            .map((p) => {
+            const hint = p.type && p.type !== 'json' ? unitHint(p) || p.type : shapeHint(p.schema);
+            return `${p.name}${p.required ? '*' : ''}${hint ? `:${hint}` : ''}`;
+        })
+            .join(', ');
+        return [`- ${op.operationId}${flags ? ` [${flags}]` : ''} {${params}}`];
+    });
+    return [
+        'QUICK REFERENCE (superdoc_api_call without a search; * = required; {a,b} = object with those keys; {kind:x|y} = one of the Targets shapes below; [ro] reads only; [tracked] accepts changeMode:"tracked"):',
+        ...lines,
+    ].join('\n');
+}
+function lookupOp(operationId) {
+    const op = CONTRACT.operations[operationId];
+    return op && isCallableOp(op) ? op : undefined;
+}
+function visibleParams(op) {
+    return op.params.filter((p) => !HIDDEN_PARAMS.has(p.name) && p.agentVisible !== false);
+}
+function normalizeId(id) {
+    const s = typeof id === 'string' ? id.trim() : '';
+    return s.startsWith('doc.') ? s : `doc.${s}`;
+}
+function forwardOptions(invokeOptions) {
+    if (!invokeOptions)
+        return undefined;
+    const { excludeActions: _ignored, ...rest } = invokeOptions;
+    return rest;
+}
+function resolveMethod(doc, operationId) {
+    const tokens = operationId.split('.').slice(1);
+    let cursor = doc;
+    for (const token of tokens) {
+        if (cursor == null ||
+            (typeof cursor !== 'object' && typeof cursor !== 'function') ||
+            !(token in cursor)) {
+            throw new SuperDocCliError(`No bound method found for operation ${operationId}.`, {
+                code: 'TOOL_DISPATCH_NOT_FOUND',
+                details: { operationId, token },
+            });
+        }
+        cursor = cursor[token];
+    }
+    if (typeof cursor !== 'function') {
+        throw new SuperDocCliError(`Resolved member for ${operationId} is not callable.`, {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+            details: { operationId },
+        });
+    }
+    const method = cursor;
+    return (args, options) => method(enforceTrackedChangeMode(operationId, args, trackedEnforcementOf(options)).args, options);
+}
+function trackedEnforcementOf(options) {
+    if (!isRecord(options) || options.enforceChangeMode !== 'tracked')
+        return null;
+    const allowDirect = options.allowDirectActions;
+    return {
+        directOperationsAllowed: Array.isArray(allowDirect) && allowDirect.includes(ALLOW_ALL_DIRECT_ACTIONS),
+    };
+}
+function withoutTrackedEnforcement(invokeOptions) {
+    if (!invokeOptions)
+        return undefined;
+    const { enforceChangeMode: _enforced, allowDirectActions: _allowed, ...rest } = invokeOptions;
+    return rest;
+}
+function enforceTrackedChangeMode(operationId, args, enforcement) {
+    if (!enforcement)
+        return { args, changeModeForced: false };
+    const op = CONTRACT.operations[operationId];
+    if (op?.mutates === false)
+        return { args, changeModeForced: false };
+    if (op && operationAcceptsTrackedMode(op)) {
+        return { args: { ...args, changeMode: 'tracked' }, changeModeForced: args.changeMode !== 'tracked' };
+    }
+    if (enforcement.directOperationsAllowed)
+        return { args, changeModeForced: false };
+    throw new SuperDocCliError(`${operationId} edits the document directly and is refused under enforceChangeMode: "tracked". Nothing was changed. Use an operation that supports tracked mode, or have the host permit direct-only edits with allowDirectActions: ["*"].`, {
+        code: 'INVALID_ARGUMENT',
+        details: { operationId, supportsTrackedMode: false, reason: 'enforce-change-mode' },
+    });
+}
+function changeModeReceipt(operationId, governed, enforcement) {
+    if (!enforcement || CONTRACT.operations[operationId]?.mutates !== true)
+        return {};
+    return {
+        changeMode: governed.args.changeMode === 'tracked' ? 'tracked' : 'direct',
+        changeModeForced: governed.changeModeForced,
+    };
+}
+function isFailureReceipt(value) {
+    return value != null && typeof value === 'object' && value.success === false;
+}
+function scoreOp(op, terms) {
+    const id = op.operationId.toLowerCase();
+    const desc = (op.description ?? '').toLowerCase();
+    const paramNames = op.params.map((p) => p.name.toLowerCase()).join(' ');
+    let score = 0;
+    for (const term of terms) {
+        if (id.includes(term))
+            score += 5;
+        if (desc.includes(term))
+            score += 2;
+        if (paramNames.includes(term))
+            score += 1;
+    }
+    return score;
+}
+function summarizeOp(op) {
+    return {
+        operationId: op.operationId,
+        description: (op.description ?? '').slice(0, opt('compactsearch') ? 110 : 180),
+        mutates: op.mutates === true,
+        tracked: operationAcceptsTrackedMode(op),
+        params: visibleParams(op).map((p) => (p.required ? `${p.name}*` : p.name)),
+    };
+}
+function summarizeOpWithSchema(op) {
+    const d = describeOp(op);
+    return {
+        operationId: d.operationId,
+        description: (op.description ?? '').slice(0, opt('compactsearch') ? 110 : 180),
+        mutates: d.mutates,
+        supportsTrackedMode: d.supportsTrackedMode,
+        supportsDryRun: d.supportsDryRun,
+        targetShape: d.targetShape,
+        params: d.params,
+    };
+}
+const SCHEMA_HITS = 3;
+function compactSchema(schema, depth = 0) {
+    if (schema == null || typeof schema !== 'object')
+        return schema;
+    const text = JSON.stringify(schema);
+    if (text.length <= SCHEMA_CHAR_CAP)
+        return schema;
+    const s = schema;
+    if (Array.isArray(s.oneOf)) {
+        return {
+            oneOf: s.oneOf
+                .slice(0, 12)
+                .map((alt) => (depth < 2 ? compactSchema(alt, depth + 1) : shapeOf(alt))),
+            ...(s.description ? { description: s.description } : {}),
+        };
+    }
+    return shapeOf(schema);
+}
+function shapeOf(schema) {
+    if (schema == null || typeof schema !== 'object')
+        return schema;
+    const s = schema;
+    if (s.const !== undefined)
+        return { const: s.const };
+    if (s.type === 'array')
+        return { type: 'array', items: shapeOf(s.items) };
+    if (s.properties && typeof s.properties === 'object') {
+        const props = {};
+        for (const [k, v] of Object.entries(s.properties)) {
+            const vv = v;
+            props[k] =
+                vv?.const !== undefined ? { const: vv.const } : (vv?.type ?? (Array.isArray(vv?.oneOf) ? 'oneOf' : 'object'));
+        }
+        return { type: 'object', properties: props, ...(s.required ? { required: s.required } : {}) };
+    }
+    if (s.type)
+        return { type: s.type };
+    return '[object]';
+}
+function describeOp(op) {
+    const params = visibleParams(op).map((p) => ({
+        name: p.name,
+        type: p.type,
+        required: p.required === true,
+        description: p.description,
+        schema: compactSchema(p.schema),
+    }));
+    const entry = getOperationCatalogEntry(op.operationId);
+    return {
+        operationId: op.operationId,
+        description: op.description,
+        mutates: op.mutates === true,
+        supportsTrackedMode: operationAcceptsTrackedMode(op),
+        supportsDryRun: op.supportsDryRun === true,
+        domain: entry?.domain ?? domainOf(op.operationId),
+        targetShape: entry?.targetShape,
+        params,
+        usage: 'Call superdoc_api_call with {operationId, args:{…params…}}. Block targets are {kind:"block", nodeType, nodeId} using nodeIds from superdoc_inspect / doc.blocks.list. Positions are {kind:"documentEnd"} | {kind:"documentStart"} | {kind:"before"|"after", target:{kind:"block", nodeType, nodeId}}. Text spans are {kind:"text", segments:[{blockId, range:{start,end}}]}. Pass changeMode:"tracked" only when supportsTrackedMode is true.',
+    };
+}
+function describeOne(ops, rawId) {
+    const id = normalizeId(rawId);
+    const op = ops.find((o) => o.operationId === id);
+    if (!op) {
+        const near = ops
+            .map((o) => ({
+            o,
+            s: scoreOp(o, id
+                .replace(/^doc\./, '')
+                .toLowerCase()
+                .split('.')),
+        }))
+            .filter((x) => x.s > 0)
+            .sort((a, b) => b.s - a.s)
+            .slice(0, 8)
+            .map((x) => x.o.operationId);
+        return { found: false, operationId: id, didYouMean: near };
+    }
+    return { found: true, operation: describeOp(op) };
+}
+function runCatalog(args) {
+    const ops = contractOps();
+    if (Array.isArray(args.operationIds) && args.operationIds.length > 0) {
+        const operations = args.operationIds
+            .slice(0, 8)
+            .filter((id) => typeof id === 'string' && id.trim().length > 0)
+            .map((id) => describeOne(ops, id))
+            .map((r) => (r.found ? r.operation : r));
+        return { operations };
+    }
+    if (typeof args.operationId === 'string' && args.operationId.trim().length > 0) {
+        return describeOne(ops, args.operationId);
+    }
+    const limit = Math.min(Math.max(Number(args.limit ?? (opt('compactsearch') ? 12 : 25)), 1), 24);
+    const domain = typeof args.domain === 'string' && args.domain.trim() ? args.domain.trim().toLowerCase() : undefined;
+    const terms = (args.query ?? '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1);
+    let candidates = ops;
+    if (domain)
+        candidates = candidates.filter((o) => domainOf(o.operationId).toLowerCase() === domain);
+    if (args.mutatingOnly === true)
+        candidates = candidates.filter((o) => o.mutates === true);
+    let ranked = candidates.map((o) => ({ o, s: terms.length ? scoreOp(o, terms) : 1 }));
+    if (terms.length)
+        ranked = ranked.filter((x) => x.s > 0);
+    ranked.sort((a, b) => b.s - a.s || a.o.operationId.localeCompare(b.o.operationId));
+    const domains = [...new Set(ops.map((o) => domainOf(o.operationId)))].sort();
+    const page = ranked.slice(0, limit);
+    if (opt('searchschemas') && (terms.length || domain)) {
+        const withSchema = page.slice(0, SCHEMA_HITS).map((x) => summarizeOpWithSchema(x.o));
+        const rest = page.slice(SCHEMA_HITS).map((x) => summarizeOp(x.o));
+        return {
+            total: ranked.length,
+            showing: page.length,
+            operations: [...withSchema, ...rest],
+            usage: 'The first hits include their params; call superdoc_api_call with {operationId, args} directly. Block targets are {kind:"block", nodeType, nodeId}; positions {kind:"documentEnd"|"documentStart"} or {kind:"before"|"after", target:<block>}; text spans {kind:"text", segments:[{blockId, range:{start,end}}]}. Pass changeMode:"tracked" only when supportsTrackedMode is true.',
+            next: rest.length
+                ? 'For an operation listed without params, call superdoc_api_search with {operationId}.'
+                : undefined,
+        };
+    }
+    return {
+        total: ranked.length,
+        showing: page.length,
+        domains: terms.length || domain ? undefined : domains,
+        operations: page.map((x) => summarizeOp(x.o)),
+        next: 'Call superdoc_api_search with {operationId} for the full parameter schema of one operation.',
+    };
+}
+const MIME_BY_EXT = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.bmp': 'image/bmp',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.tif': 'image/tiff',
+    '.tiff': 'image/tiff',
+};
+function documentDir(doc) {
+    const p = doc.openResult?.document?.path;
+    return typeof p === 'string' && p.length > 0 ? path.dirname(path.resolve(p)) : undefined;
+}
+async function toDataUri(src, baseDir) {
+    if (/^data:/i.test(src))
+        return src;
+    if (/^https?:\/\//i.test(src)) {
+        const res = await fetch(src);
+        if (!res.ok) {
+            throw new SuperDocCliError(`Image URL fetch failed: ${res.status} ${res.statusText}`, {
+                code: 'INVALID_ARGUMENT',
+                details: { src },
+            });
+        }
+        const mime = res.headers.get('content-type')?.split(';')[0] || 'image/png';
+        const bytes = Buffer.from(await res.arrayBuffer());
+        return `data:${mime};base64,${bytes.toString('base64')}`;
+    }
+    const raw = /^file:\/\//i.test(src) ? fileURLToPath(src) : src;
+    const filePath = resolveDocumentRelativePath(raw, baseDir);
+    if (!existsSync(filePath)) {
+        throw new SuperDocCliError(`Image file not found: ${src} (looked at ${filePath})`, {
+            code: 'INVALID_ARGUMENT',
+            details: { src, path: filePath },
+        });
+    }
+    const mime = MIME_BY_EXT[path.extname(filePath).toLowerCase()] ?? 'image/png';
+    const bytes = await readFile(filePath);
+    return `data:${mime};base64,${bytes.toString('base64')}`;
+}
+function resolveDocumentRelativePath(raw, baseDir) {
+    if (path.isAbsolute(raw) || /^(data:|https?:\/\/|file:)/i.test(raw))
+        return raw;
+    if (!baseDir) {
+        throw new SuperDocCliError(`Relative path "${raw}" resolves from the open document's folder, and this document was not opened from a file. Pass an absolute path.`, { code: 'INVALID_ARGUMENT', details: { path: raw } });
+    }
+    const resolved = path.resolve(baseDir, raw);
+    const inside = path.relative(baseDir, resolved);
+    if (inside === '..' || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside)) {
+        throw new SuperDocCliError(`Relative path "${raw}" leaves the open document's folder ${baseDir}. Pass an absolute path for a file elsewhere.`, { code: 'INVALID_ARGUMENT', details: { path: raw, documentFolder: baseDir } });
+    }
+    return resolved;
+}
+const COLOR_KEY = /(^|[a-z])(color|fill)$/i;
+function normalizeColors(value) {
+    if (Array.isArray(value))
+        return value.map(normalizeColors);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] =
+                typeof v === 'string' && COLOR_KEY.test(k) && /^#[0-9a-f]{6}$/i.test(v) ? v.slice(1) : normalizeColors(v);
+        }
+        return out;
+    }
+    return value;
+}
+function styleCreateSchema(channel) {
+    return lookupOp('doc.styles.create')?.params.find((p) => p.name === channel)?.schema;
+}
+function probeValue(schema) {
+    if (!schema)
+        return undefined;
+    if (schema.const !== undefined)
+        return schema.const;
+    if (Array.isArray(schema.oneOf))
+        return probeValue(schema.oneOf[0]);
+    if (schema.type === 'boolean')
+        return true;
+    if (schema.type === 'number' || schema.type === 'integer')
+        return 1;
+    if (schema.type === 'string')
+        return 'auto';
+    if (schema.type === 'array') {
+        const item = probeValue(schema.items);
+        return item === undefined ? undefined : [item];
+    }
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+        const value = probeValue(child);
+        if (value !== undefined)
+            return { [key]: value };
+    }
+    return undefined;
+}
+const RECEIPT_KEY_ALIASES = { sz: 'size' };
+const isSet = (state) => state != null && state !== 'inherit';
+function patchValue(schema, state, lost, at) {
+    if (!schema || !isSet(state))
+        return undefined;
+    if (Array.isArray(schema.oneOf))
+        return schema.oneOf.some((alt) => alt.const === state) ? state : undefined;
+    switch (schema.type) {
+        case 'boolean':
+            if (state === true || state === 'on' || state === '1' || state === 'true')
+                return true;
+            if (state === false || state === 'off' || state === '0' || state === 'false')
+                return false;
+            return undefined;
+        case 'number':
+        case 'integer': {
+            const n = typeof state === 'object' ? NaN : Number(state);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        case 'string':
+            if (typeof state === 'object')
+                return undefined;
+            return typeof state === 'boolean' ? (state ? '1' : '0') : String(state);
+        case 'array': {
+            if (!Array.isArray(state))
+                return undefined;
+            const items = state.map((item, i) => {
+                const before = lost.length;
+                const value = patchValue(schema.items, item, lost, `${at}[${i}]`);
+                if (value === undefined && isSet(item) && lost.length === before)
+                    lost.push(`${at}[${i}]`);
+                return value;
+            });
+            return items.filter((item) => item !== undefined);
+        }
+        case 'object': {
+            if (typeof state !== 'object' || Array.isArray(state))
+                return undefined;
+            const properties = schema.properties ?? {};
+            const out = {};
+            for (const [rawKey, child] of Object.entries(state)) {
+                const key = rawKey in properties ? rawKey : RECEIPT_KEY_ALIASES[rawKey];
+                const path = at ? `${at}.${rawKey}` : rawKey;
+                const before = lost.length;
+                const value = key && key in properties ? patchValue(properties[key], child, lost, path) : undefined;
+                if (value !== undefined)
+                    out[key] = value;
+                else if (isSet(child) && lost.length === before)
+                    lost.push(path);
+            }
+            return Object.keys(out).length ? out : undefined;
+        }
+    }
+    return undefined;
+}
+async function readStyleDefinition(doc, item, invokeOptions) {
+    const paragraphSchema = styleCreateSchema('paragraph');
+    const runSchema = styleCreateSchema('run');
+    if (!paragraphSchema?.properties || !runSchema?.properties)
+        return null;
+    const probe = (schema) => Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, child]) => [key, probeValue(child)]));
+    const receipt = (await resolveMethod(doc, 'doc.styles.create')({
+        id: item.id,
+        name: item.name ?? item.id,
+        type: item.type,
+        conflictPolicy: 'replace',
+        dryRun: true,
+        ...(item.type === 'paragraph' ? { paragraph: probe(paragraphSchema) } : {}),
+        run: probe(runSchema),
+    }, forwardOptions(invokeOptions)));
+    if (receipt?.success !== true || !receipt.before)
+        return null;
+    const lost = [];
+    const channel = (name, schema) => patchValue({ type: 'object', properties: schema.properties }, receipt.before[name], lost, name);
+    return { paragraph: channel('paragraph', paragraphSchema), run: channel('run', runSchema), lost };
+}
+const THEME_SIBLINGS = {
+    color: ['themeColor', 'themeTint', 'themeShade'],
+    fill: ['themeFill', 'themeFillShade', 'themeFillTint'],
+    ascii: ['asciiTheme'],
+    hAnsi: ['hAnsiTheme'],
+    eastAsia: ['eastAsiaTheme'],
+    cs: ['cstheme'],
+};
+function mergeStylePatch(existing, patch, parent) {
+    if (patch === null)
+        return undefined;
+    const out = { ...(isRecord(existing) ? existing : {}) };
+    if (isRecord(patch)) {
+        for (const [key, value] of Object.entries(patch)) {
+            if (parent) {
+                const siblings = THEME_SIBLINGS[parent === 'color' && key === 'val' ? 'color' : key] ?? [];
+                for (const sibling of siblings)
+                    delete out[sibling];
+            }
+            if (value === null)
+                delete out[key];
+            else if (isRecord(value)) {
+                const merged = mergeStylePatch(isRecord(out[key]) ? out[key] : undefined, value, key);
+                if (merged)
+                    out[key] = merged;
+                else
+                    delete out[key];
+            }
+            else
+                out[key] = value;
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+const KEPT_STYLE_FIELDS = [
+    'basedOn',
+    'next',
+    'aliases',
+    'priority',
+    'qFormat',
+    'hidden',
+    'semiHidden',
+    'unhideWhenUsed',
+    'locked',
+];
+async function keepUnsentStyleProperties(doc, args, invokeOptions) {
+    if (args.conflictPolicy !== 'replace' || typeof args.id !== 'string')
+        return args;
+    const refuse = (message, details = {}) => new SuperDocCliError(message, {
+        code: 'INVALID_ARGUMENT',
+        details: { operationId: 'doc.styles.create', styleId: args.id, ...details },
+    });
+    const unreadable = (reason) => refuse(`doc.styles.create could not read the current definition of style "${args.id}" (${reason}), so a replace could drop properties it cannot see. Nothing was changed. Create the style under a new id with conflictPolicy "fail", or ask the user how to proceed.`);
+    let item;
+    let existing;
+    try {
+        const catalog = (await resolveMethod(doc, 'doc.styles.getCatalog')({ view: 'currentDocument', includeHidden: true }, forwardOptions(invokeOptions)));
+        item = catalog?.items?.find((s) => s.id === args.id);
+        if (!item || item.link || item.type !== args.type || (item.type !== 'paragraph' && item.type !== 'character'))
+            return args;
+        existing = await readStyleDefinition(doc, item, invokeOptions);
+    }
+    catch (e) {
+        throw unreadable(e.message);
+    }
+    if (!existing)
+        throw unreadable('the definition read was refused');
+    const unsent = existing.lost.filter((path) => {
+        const [channel, key] = path.split('.');
+        return args[channel]?.[key.replace(/\[\d+\]$/, '')] === undefined;
+    });
+    if (unsent.length) {
+        const properties = [
+            ...new Set(unsent.map((path) => path
+                .split('.')
+                .slice(0, 2)
+                .join('.')
+                .replace(/\[\d+\]$/, ''))),
+        ];
+        throw refuse(`doc.styles.create could not read ${unsent.join(', ')} of style "${args.id}", so a replace would drop it. Nothing was changed. Resend the complete value of ${properties.join(', ')} in this call.`, { unreadable: unsent, resend: properties });
+    }
+    const out = { ...args };
+    for (const field of KEPT_STYLE_FIELDS) {
+        const value = item[field];
+        if (out[field] === undefined && value != null && value !== false && !(Array.isArray(value) && !value.length))
+            out[field] = value;
+    }
+    if (out.custom === undefined && typeof item.custom === 'boolean')
+        out.custom = item.custom;
+    for (const channel of item.type === 'paragraph' ? ['paragraph', 'run'] : ['run']) {
+        const merged = mergeStylePatch(existing[channel], args[channel]);
+        if (merged)
+            out[channel] = merged;
+        else
+            delete out[channel];
+    }
+    return out;
+}
+async function preprocessArgs(doc, operationId, args, invokeOptions) {
+    let out = normalizeColors(args);
+    if (operationId === 'doc.styles.create')
+        out = await keepUnsentStyleProperties(doc, out, invokeOptions);
+    if ((operationId === 'doc.create.image' || operationId === 'doc.images.replaceSource') &&
+        typeof out.src === 'string') {
+        out = { ...out, src: await toDataUri(out.src, documentDir(doc)) };
+    }
+    const source = out.source;
+    if (source && source.kind === 'path' && typeof source.path === 'string') {
+        out = { ...out, source: { ...source, path: resolveDocumentRelativePath(source.path, documentDir(doc)) } };
+    }
+    if (typeof out.path === 'string' && /\.(docx|png|jpe?g|gif|bmp|svg)$/i.test(out.path)) {
+        out = { ...out, path: resolveDocumentRelativePath(out.path, documentDir(doc)) };
+    }
+    return out;
+}
+function prepareCall(call) {
+    const operationId = normalizeId(call.operationId);
+    const op = lookupOp(operationId);
+    if (!op) {
+        throw new SuperDocCliError(`Unknown or non-callable operation: ${operationId}. Use superdoc_api_search to find the exact id.`, {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+            details: { operationId },
+        });
+    }
+    const args = { ...call.args };
+    for (const key of Object.keys(args))
+        if (RESERVED_ARG_KEYS.has(key))
+            delete args[key];
+    const paramNames = new Set(op.params.map((p) => p.name));
+    if (call.changeMode !== undefined) {
+        if (!paramNames.has('changeMode')) {
+            throw new SuperDocCliError(`${operationId} has no changeMode; it always applies directly.`, {
+                code: 'INVALID_ARGUMENT',
+                details: { operationId },
+            });
+        }
+        args.changeMode = call.changeMode;
+    }
+    if (call.dryRun !== undefined) {
+        if (!paramNames.has('dryRun') || op.supportsDryRun === false) {
+            throw new SuperDocCliError(`${operationId} does not support dryRun; it would apply for real. Call without dryRun when you mean it.`, {
+                code: 'INVALID_ARGUMENT',
+                details: { operationId, supportsDryRun: false },
+            });
+        }
+        args.dryRun = call.dryRun;
+    }
+    if (args.changeMode === 'tracked' && op.mutates === true && !operationAcceptsTrackedMode(op)) {
+        throw new SuperDocCliError(`${operationId} does not support tracked mode; call it without changeMode or pick an operation that does.`, {
+            code: 'INVALID_ARGUMENT',
+            details: { operationId, supportsTrackedMode: false },
+        });
+    }
+    const unknown = Object.keys(args).filter((k) => !paramNames.has(k));
+    if (unknown.length) {
+        throw new SuperDocCliError(`${operationId} does not accept: ${unknown.join(', ')}. Accepted: ${visibleParams(op)
+            .map((p) => p.name)
+            .join(', ')}.`, {
+            code: 'INVALID_ARGUMENT',
+            details: { operationId, unknown },
+        });
+    }
+    const missing = visibleParams(op)
+        .filter((p) => p.required && args[p.name] === undefined)
+        .map((p) => p.name);
+    if (missing.length) {
+        throw new SuperDocCliError(`${operationId} requires: ${missing.join(', ')}.`, {
+            code: 'INVALID_ARGUMENT',
+            details: { operationId, missing },
+        });
+    }
+    return { op, operationId, args };
+}
+function shapeResult(operationId, result) {
+    if (OPAQUE_RESULT_OPS.has(operationId))
+        return result;
+    const text = JSON.stringify(result);
+    if (text === undefined || text.length <= RESULT_CHAR_CAP)
+        return result;
+    return { truncated: true, chars: text.length, preview: text.slice(0, RESULT_CHAR_CAP) };
+}
+async function invokeCall(doc, call, invokeOptions) {
+    const { operationId, args } = prepareCall(call);
+    const enforcement = trackedEnforcementOf(invokeOptions);
+    const governed = enforceTrackedChangeMode(operationId, args, enforcement);
+    const prepared = await preprocessArgs(doc, operationId, governed.args, invokeOptions);
+    const result = shapeResult(operationId, await resolveMethod(doc, operationId)(prepared, forwardOptions(invokeOptions)));
+    const receipt = changeModeReceipt(operationId, governed, enforcement);
+    return isRecord(result) && receipt.changeMode !== undefined ? { ...result, ...receipt } : result;
+}
+async function runOperation(doc, raw, invokeOptions) {
+    if (Array.isArray(raw.calls) && raw.calls.length > 0) {
+        if (raw.calls.length > 40) {
+            throw new SuperDocCliError('superdoc_api_call batch is capped at 40 calls.', { code: 'INVALID_ARGUMENT' });
+        }
+        const batchLevel = ['dryRun', 'changeMode'].filter((key) => raw[key] !== undefined);
+        if (batchLevel.length) {
+            throw new SuperDocCliError(`superdoc_api_call applies ${batchLevel.join(' and ')} per call, not to a batch. Nothing was run. Put ${batchLevel.join(' and ')} on each entry of calls.`, { code: 'INVALID_ARGUMENT', details: { batchLevel } });
+        }
+        const prepared = raw.calls.map((c, i) => {
+            try {
+                return prepareCall(c);
+            }
+            catch (e) {
+                throw new SuperDocCliError(`calls[${i}]: ${e.message}`, {
+                    code: 'INVALID_ARGUMENT',
+                    details: { index: i },
+                });
+            }
+        });
+        const enforcement = trackedEnforcementOf(invokeOptions);
+        const governed = prepared.map(({ operationId, args }, i) => {
+            try {
+                return enforceTrackedChangeMode(operationId, args, enforcement);
+            }
+            catch (e) {
+                const refusal = e;
+                throw new SuperDocCliError(`calls[${i}]: ${refusal.message}`, {
+                    code: refusal.code,
+                    details: { index: i, ...(isRecord(refusal.details) ? refusal.details : {}) },
+                });
+            }
+        });
+        const receipts = [];
+        for (let i = 0; i < prepared.length; i++) {
+            const { operationId } = prepared[i];
+            try {
+                const args2 = await preprocessArgs(doc, operationId, governed[i].args, invokeOptions);
+                const result = await resolveMethod(doc, operationId)(args2, forwardOptions(invokeOptions));
+                receipts.push({
+                    index: i,
+                    operationId,
+                    ok: !isFailureReceipt(result),
+                    ...changeModeReceipt(operationId, governed[i], enforcement),
+                    result: shapeResult(operationId, result),
+                });
+                if (isFailureReceipt(result)) {
+                    return {
+                        completed: i,
+                        total: prepared.length,
+                        stoppedAt: i,
+                        reason: 'operation reported success:false',
+                        receipts,
+                    };
+                }
+            }
+            catch (e) {
+                receipts.push({ index: i, operationId, ok: false, error: e.message });
+                return { completed: i, total: prepared.length, stoppedAt: i, reason: 'operation threw', receipts };
+            }
+        }
+        return { completed: prepared.length, total: prepared.length, receipts };
+    }
+    if (typeof raw.operationId !== 'string' || raw.operationId.trim().length === 0) {
+        throw new SuperDocCliError('superdoc_api_call needs operationId (or calls:[…] for a batch).', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    return invokeCall(doc, raw, invokeOptions);
+}
+async function listBlocks(doc, args, invokeOptions) {
+    const res = (await resolveMethod(doc, 'doc.blocks.list')(args, forwardOptions(invokeOptions)));
+    return res.blocks ?? [];
+}
+const ANCHOR_PAGE_SIZE = 50;
+const AMBIGUOUS_CANDIDATES_SHOWN = 6;
+async function listAnchorMatches(doc, anchorText, wanted, invokeOptions) {
+    const list = resolveMethod(doc, 'doc.blocks.list');
+    const matches = [];
+    const limit = Math.max(6, Math.min(wanted, ANCHOR_PAGE_SIZE));
+    for (let offset = 0; matches.length < wanted;) {
+        const page = (await list({ textSearch: { terms: [anchorText], match: 'all' }, includeText: true, offset, limit }, forwardOptions(invokeOptions)));
+        const rows = page.blocks ?? [];
+        matches.push(...rows);
+        offset += rows.length;
+        if (rows.length === 0 || typeof page.total !== 'number' || offset >= page.total)
+            break;
+    }
+    return matches;
+}
+async function findBlock(doc, args, invokeOptions) {
+    if (args.nodeId) {
+        const [block] = await listBlocks(doc, { nodeIds: [args.nodeId], limit: 1, includeText: true }, invokeOptions);
+        if (block)
+            return block;
+        throw new SuperDocCliError(`No block with nodeId ${args.nodeId}.`, {
+            code: 'INVALID_ARGUMENT',
+            details: { nodeId: args.nodeId },
+        });
+    }
+    if (args.anchorText && args.anchorText.trim()) {
+        const wanted = args.occurrence != null ? Math.max(1, Math.floor(args.occurrence)) : Number.POSITIVE_INFINITY;
+        const matches = await listAnchorMatches(doc, args.anchorText, wanted, invokeOptions);
+        if (matches.length === 0) {
+            throw new SuperDocCliError(`No block contains "${args.anchorText}".`, {
+                code: 'INVALID_ARGUMENT',
+                details: { anchorText: args.anchorText },
+            });
+        }
+        if (args.occurrence != null) {
+            const block = matches[Math.max(0, Math.floor(args.occurrence) - 1)];
+            if (block)
+                return block;
+            throw new SuperDocCliError(`Only ${matches.length} block(s) contain "${args.anchorText}"; occurrence ${args.occurrence} does not exist.`, {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
+        if (matches.length > 1) {
+            const textOf = (m) => m.text ?? m.textPreview ?? '';
+            const exact = matches.filter((m) => textOf(m).trim() === args.anchorText.trim());
+            if (exact.length === 1)
+                return exact[0];
+            const caseSensitive = matches.filter((m) => textOf(m).includes(args.anchorText));
+            if (caseSensitive.length === 1)
+                return caseSensitive[0];
+            throw new SuperDocCliError(`"${args.anchorText}" matches ${matches.length} blocks; pass occurrence (1-based) or nodeId. Candidates: ${matches
+                .slice(0, AMBIGUOUS_CANDIDATES_SHOWN)
+                .map((m) => `${m.nodeId} "${(m.textPreview ?? m.text ?? '').slice(0, 50)}"`)
+                .join(' | ')}`, {
+                code: 'INVALID_ARGUMENT',
+                details: { matchCount: matches.length, candidates: matches.slice(0, ANCHOR_PAGE_SIZE).map((m) => m.nodeId) },
+            });
+        }
+        return matches[0];
+    }
+    throw new SuperDocCliError('Need anchorText or nodeId to locate the block.', { code: 'INVALID_ARGUMENT' });
+}
+async function runInsertImage(doc, args, invokeOptions) {
+    if (typeof args.src !== 'string' || args.src.length === 0) {
+        throw new SuperDocCliError('insert_image requires src (file path, URL, or data URI).', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const opts = forwardOptions(invokeOptions);
+    const placement = args.placement ?? 'document_end';
+    let at = { kind: placement === 'document_start' ? 'documentStart' : 'documentEnd' };
+    if (placement === 'after' || placement === 'before') {
+        const block = await findBlock(doc, args, invokeOptions);
+        at = { kind: placement, target: { kind: 'block', nodeType: block.nodeType, nodeId: block.nodeId } };
+    }
+    const before = new Set((await listBlocks(doc, {}, invokeOptions)).map((b) => b.nodeId));
+    const imageArgs = { src: await toDataUri(args.src, documentDir(doc)), at };
+    if (args.alt)
+        imageArgs.alt = args.alt;
+    if (args.width || args.height)
+        imageArgs.size = { ...(args.width ? { width: args.width } : {}), ...(args.height ? { height: args.height } : {}) };
+    if (args.changeMode)
+        imageArgs.changeMode = args.changeMode;
+    const imageResult = (await resolveMethod(doc, 'doc.create.image')(imageArgs, opts));
+    if (isFailureReceipt(imageResult))
+        return imageResult;
+    if (!args.caption)
+        return { success: true, image: imageResult.image };
+    const after = await listBlocks(doc, {}, invokeOptions);
+    const imageBlock = after.find((b) => !before.has(b.nodeId)) ?? (placement === 'document_start' ? after[0] : after[after.length - 1]);
+    const captionArgs = {
+        text: args.caption,
+        at: { kind: 'after', target: { kind: 'block', nodeType: imageBlock.nodeType, nodeId: imageBlock.nodeId } },
+    };
+    if (args.changeMode)
+        captionArgs.changeMode = args.changeMode;
+    try {
+        const captionResult = await resolveMethod(doc, 'doc.create.paragraph')(captionArgs, opts);
+        if (isFailureReceipt(captionResult)) {
+            return {
+                success: false,
+                image: imageResult.image,
+                imageInserted: true,
+                caption: 'failed',
+                captionFailure: captionResult,
+                hint: 'The picture IS in the document — do not insert it again. Add the caption with doc.create.paragraph after the image block.',
+            };
+        }
+        return { success: true, image: imageResult.image, imageBlockId: imageBlock.nodeId, caption: 'inserted' };
+    }
+    catch (e) {
+        return {
+            success: false,
+            image: imageResult.image,
+            imageInserted: true,
+            caption: 'failed',
+            captionError: e.message,
+            hint: 'The picture IS in the document — do not insert it again. Add the caption with doc.create.paragraph after the image block.',
+        };
+    }
+}
+async function runInsertFootnote(doc, args, invokeOptions) {
+    if (typeof args.anchorText !== 'string' || !args.anchorText.trim()) {
+        throw new SuperDocCliError('insert_footnote requires anchorText (the exact phrase the note mark follows).', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (typeof args.content !== 'string' || !args.content.trim()) {
+        throw new SuperDocCliError('insert_footnote requires content (the note text).', { code: 'INVALID_ARGUMENT' });
+    }
+    const opts = forwardOptions(invokeOptions);
+    const type = args.type ?? 'footnote';
+    const block = await findBlock(doc, args, invokeOptions);
+    const text = block.text ?? '';
+    const start = text.indexOf(args.anchorText);
+    if (start < 0) {
+        throw new SuperDocCliError(`Phrase "${args.anchorText}" not found inside block ${block.nodeId} text.`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const list = resolveMethod(doc, 'doc.footnotes.list');
+    const countBefore = (await list({}, opts)) ?? {};
+    const end = start + args.anchorText.length;
+    const noteArgs = {
+        type,
+        content: args.content,
+        at: { kind: 'text', segments: [{ blockId: block.nodeId, range: { start: end, end } }] },
+    };
+    if (args.changeMode)
+        noteArgs.changeMode = args.changeMode;
+    const result = (await resolveMethod(doc, 'doc.footnotes.insert')(noteArgs, opts));
+    if (isFailureReceipt(result))
+        return result;
+    const countAfter = (await list({}, opts)) ?? {};
+    const n = (x) => x.total ?? x.items?.length ?? x.footnotes?.length;
+    return {
+        success: true,
+        type,
+        anchoredOn: `${block.nodeId}[${start}..${end}]`,
+        note: result.footnote ?? result,
+        notesBefore: n(countBefore),
+        notesAfter: n(countAfter),
+    };
+}
+async function runShadeCells(doc, args, invokeOptions) {
+    if (typeof args.color !== 'string' || !args.color.trim()) {
+        throw new SuperDocCliError('shade_cells requires color (hex like "D9D9D9" or a name).', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const opts = forwardOptions(invokeOptions);
+    let tableNodeId = args.tableNodeId;
+    if (!tableNodeId) {
+        const tables = await listBlocks(doc, { nodeTypes: ['table'] }, invokeOptions);
+        const ordinal = Math.max(1, Math.floor(args.tableOrdinal ?? 1));
+        const table = tables[ordinal - 1];
+        if (!table) {
+            throw new SuperDocCliError(`Document has ${tables.length} table(s); tableOrdinal ${ordinal} does not exist.`, {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
+        tableNodeId = table.nodeId;
+    }
+    const cellsArgs = { target: { kind: 'block', nodeType: 'table', nodeId: tableNodeId } };
+    if (args.rowIndex != null)
+        cellsArgs.rowIndex = args.rowIndex;
+    if (args.columnIndex != null)
+        cellsArgs.columnIndex = args.columnIndex;
+    const cellsResult = (await resolveMethod(doc, 'doc.tables.getCells')(cellsArgs, opts));
+    const cells = (cellsResult.cells ?? []).filter((c) => (args.rowIndex == null || c.rowIndex === args.rowIndex) &&
+        (args.columnIndex == null || c.columnIndex === args.columnIndex));
+    if (cells.length === 0) {
+        throw new SuperDocCliError('No cells matched the requested row/column.', {
+            code: 'INVALID_ARGUMENT',
+            details: { tableNodeId, rowIndex: args.rowIndex, columnIndex: args.columnIndex },
+        });
+    }
+    const setShading = resolveMethod(doc, 'doc.tables.setShading');
+    const shaded = [];
+    const failures = [];
+    for (const cell of cells) {
+        try {
+            const r = await setShading({ target: { kind: 'block', nodeType: 'tableCell', nodeId: cell.nodeId }, color: args.color }, opts);
+            if (isFailureReceipt(r))
+                failures.push({
+                    nodeId: cell.nodeId,
+                    error: JSON.stringify(r.failure).slice(0, 160),
+                });
+            else
+                shaded.push(cell.nodeId);
+        }
+        catch (e) {
+            failures.push({ nodeId: cell.nodeId, error: e.message.slice(0, 160) });
+        }
+    }
+    return {
+        success: failures.length === 0,
+        tableNodeId,
+        color: args.color,
+        cellsShaded: shaded.length,
+        cellsTotal: cells.length,
+        failures,
+    };
+}
+const COMPONENTS_APPLIED_DIRECTLY = new Set(['comments', 'styles', 'numbering', 'parts']);
+function allowsDirectHelper(options, action) {
+    const allowDirect = isRecord(options) ? options.allowDirectActions : undefined;
+    return Array.isArray(allowDirect) && (allowDirect.includes(ALLOW_ALL_DIRECT_ACTIONS) || allowDirect.includes(action));
+}
+async function runCompareWithFile(doc, args, invokeOptions) {
+    if (typeof args.path === 'string')
+        args = { ...args, path: resolveDocumentRelativePath(args.path, documentDir(doc)) };
+    if (typeof args.path !== 'string' || !existsSync(args.path)) {
+        throw new SuperDocCliError(`Comparison file not found: ${args.path}`, {
+            code: 'INVALID_ARGUMENT',
+            details: { path: args.path },
+        });
+    }
+    const opts = forwardOptions(invokeOptions);
+    const client = doc.client;
+    if (!client || typeof client.open !== 'function') {
+        throw new SuperDocCliError('compare_with_file needs a handle from client.open() (no client reference on this handle).', {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+        });
+    }
+    const other = await client.open({ doc: args.path });
+    let snapshot;
+    try {
+        snapshot = await resolveMethod(other, 'doc.diff.capture')({}, opts);
+    }
+    finally {
+        try {
+            await other.close();
+        }
+        catch { }
+    }
+    const changeMode = args.changeMode ?? 'tracked';
+    const styleOptions = changeMode === 'tracked' &&
+        (!trackedEnforcementOf(invokeOptions) || allowsDirectHelper(invokeOptions, 'compare_with_file'))
+        ? { styleChangeMode: 'direct' }
+        : {};
+    const diff = (await resolveMethod(doc, 'doc.diff.compare')({ targetSnapshot: snapshot, ...styleOptions }, opts));
+    if (diff?.summary?.hasChanges === false) {
+        return {
+            changeMode: null,
+            applied: false,
+            reason: 'The two documents have no differences in the compared components.',
+            summary: diff.summary,
+        };
+    }
+    const directComponents = (diff?.summary?.changedComponents ?? []).filter((component) => COMPONENTS_APPLIED_DIRECTLY.has(component));
+    if (directComponents.length &&
+        trackedEnforcementOf(invokeOptions) &&
+        !allowsDirectHelper(invokeOptions, 'compare_with_file')) {
+        throw new SuperDocCliError(`compare_with_file would apply the ${directComponents.join(', ')} differences directly, and enforceChangeMode: "tracked" refuses direct edits. Nothing was changed. Have the host permit it with allowDirectActions: ["compare_with_file"], or carry over only the text differences by hand.`, {
+            code: 'INVALID_ARGUMENT',
+            details: {
+                toolName: 'superdoc_perform_action',
+                action: 'compare_with_file',
+                directComponents,
+                reason: 'enforce-change-mode',
+            },
+        });
+    }
+    const eligibility = diff?.applyEligibility?.[changeMode];
+    if (eligibility?.status === 'blocked') {
+        return {
+            applied: false,
+            changeMode,
+            reason: `The diff cannot be applied in ${changeMode} mode.`,
+            blockers: eligibility.blockers,
+            summary: diff.summary,
+            hint: changeMode === 'tracked'
+                ? 'Retry with changeMode:"direct" if a plain merge is acceptable, or apply the blocked parts by hand.'
+                : undefined,
+        };
+    }
+    const applied = (await resolveMethod(doc, 'doc.diff.apply')({ diff, changeMode, ...styleOptions }, opts));
+    const receipts = Array.isArray(applied?.operationReceipts)
+        ? applied.operationReceipts
+        : [];
+    return {
+        applied: true,
+        changeMode,
+        changedComponents: diff?.summary?.changedComponents,
+        appliedOperations: applied?.appliedOperations,
+        reviewCreated: receipts.filter((r) => r.disposition === 'review-created').length,
+        appliedDirectly: receipts.filter((r) => r.disposition === 'applied-directly').length,
+        note: 'Comments, styles and numbering differences apply directly even in tracked mode; body and header/footer text differences become tracked changes.',
+    };
+}
+const HELPER_ARG_SCHEMA = {
+    src: {
+        type: 'string',
+        description: 'Image: file path (absolute or relative to the working folder), http(s) URL, or data:image/... URI.',
+    },
+    caption: { type: 'string', description: 'Caption paragraph inserted right after the image.' },
+    alt: { type: 'string' },
+    width: { type: 'number', description: 'Pixels.' },
+    height: { type: 'number', description: 'Pixels.' },
+    occurrence: {
+        type: 'integer',
+        minimum: 1,
+        description: '1-based pick when anchorText matches several blocks (1 = first mention).',
+    },
+    content: { type: 'string', description: 'Footnote / endnote text.' },
+    noteType: { type: 'string', enum: ['footnote', 'endnote'] },
+    path: { type: 'string', description: 'Path to the other .docx to compare against.' },
+};
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+const mode = (v) => (v === 'direct' || v === 'tracked' ? v : undefined);
+function imagePlacement(a) {
+    if (a.position === 'before' || a.position === 'after')
+        return a.position;
+    const at = a.placement && typeof a.placement === 'object' ? a.placement.at : undefined;
+    if (at === 'document_end' || at === 'document_start' || at === 'before' || at === 'after')
+        return at;
+    return str(a.anchorText) || str(a.nodeId) ? 'after' : 'document_end';
+}
+const HELPER_ACTIONS = {
+    insert_image: {
+        hint: 'src (file path/URL/data URI), caption?, alt?, width?, height?; place with position "after"|"before" + anchorText (or nodeId), default document end; changeMode?',
+        args: ['src', 'caption', 'alt', 'width', 'height', 'position', 'anchorText', 'occurrence', 'nodeId', 'changeMode'],
+        disposition: 'tracked',
+        run: (doc, a, o) => runInsertImage(doc, {
+            src: str(a.src) ?? '',
+            alt: str(a.alt),
+            caption: str(a.caption),
+            width: num(a.width),
+            height: num(a.height),
+            occurrence: num(a.occurrence),
+            anchorText: str(a.anchorText),
+            nodeId: str(a.nodeId),
+            changeMode: mode(a.changeMode),
+            placement: imagePlacement(a),
+        }, o),
+    },
+    insert_footnote: {
+        hint: 'anchorText (exact phrase the note mark follows; unique, or occurrence/nodeId), content, noteType? footnote|endnote, changeMode?',
+        args: ['anchorText', 'occurrence', 'nodeId', 'content', 'noteType', 'changeMode'],
+        disposition: 'tracked',
+        run: (doc, a, o) => runInsertFootnote(doc, {
+            anchorText: str(a.anchorText) ?? '',
+            occurrence: num(a.occurrence),
+            nodeId: str(a.nodeId),
+            content: str(a.content) ?? '',
+            type: a.noteType === 'endnote' ? 'endnote' : 'footnote',
+            changeMode: mode(a.changeMode),
+        }, o),
+    },
+    shade_cells: {
+        hint: 'color (hex like "D9D9D9"), tableOrdinal? (default 1) or nodeId (table), rowIndex? (0 = header row), columnIndex?; whole table / one row / one column / one cell in one call',
+        args: ['tableOrdinal', 'nodeId', 'rowIndex', 'columnIndex', 'color'],
+        disposition: 'direct',
+        run: (doc, a, o) => runShadeCells(doc, {
+            tableOrdinal: num(a.tableOrdinal),
+            tableNodeId: str(a.nodeId),
+            rowIndex: num(a.rowIndex),
+            columnIndex: num(a.columnIndex),
+            color: str(a.color) ?? '',
+        }, o),
+    },
+    compare_with_file: {
+        hint: 'path to another .docx; its differences land HERE as tracked changes (changeMode tracked, default) or apply directly',
+        args: ['path', 'changeMode'],
+        disposition: 'tracked',
+        run: (doc, a, o) => runCompareWithFile(doc, { path: str(a.path) ?? '', changeMode: mode(a.changeMode) }, o),
+    },
+};
+const HELPER_ACTION_NAMES = Object.keys(HELPER_ACTIONS);
+function resolveHelperPolicy(options) {
+    const excluded = new Set(options?.excludeActions ?? []);
+    const allowDirect = new Set(options?.allowDirectActions ?? []);
+    const tracked = options?.enforceChangeMode === 'tracked';
+    const helpers = HELPER_ACTION_NAMES.filter((name) => {
+        if (excluded.has(name))
+            return false;
+        if (tracked && HELPER_ACTIONS[name].disposition === 'direct')
+            return allowDirect.has('*') || allowDirect.has(name);
+        return true;
+    });
+    const coreOptions = {
+        ...options,
+        excludeActions: [...excluded].filter((name) => !(name in HELPER_ACTIONS)),
+        ...(options?.allowDirectActions
+            ? { allowDirectActions: [...allowDirect].filter((name) => !(name in HELPER_ACTIONS)) }
+            : {}),
+    };
+    return { helpers, coreOptions };
+}
+const LEAN_ACTION_DESCRIPTION = 'High-level deterministic document edit. Pick an action and pass flat product-facing arguments. Actions wrap the most common doc.* operations and return real pre/post evidence and verification. Each action, its arguments and the selector shapes are documented in the ACTIONS section of the system prompt.';
+function withHelperActions(provider, tool, helpers) {
+    if (helpers.length === 0 && !opt('leanschema'))
+        return tool;
+    const outer = tool;
+    const fn = (provider === 'openai' ? outer.function : outer);
+    const schemaKey = provider === 'anthropic' ? 'input_schema' : provider === 'vercel' ? 'inputSchema' : 'parameters';
+    const schema = fn[schemaKey];
+    const action = schema.properties.action;
+    const properties = { action: { ...action, enum: [...action.enum, ...helpers] } };
+    for (const [key, value] of Object.entries(schema.properties))
+        if (key !== 'action')
+            properties[key] = value;
+    for (const name of helpers) {
+        for (const arg of HELPER_ACTIONS[name].args) {
+            if (arg in properties)
+                continue;
+            const argSchema = HELPER_ARG_SCHEMA[arg] ?? ACTION_ARG_SCHEMA[arg];
+            if (!argSchema)
+                throw new Error(`full preset: helper action ${name} declares arg "${arg}" with no schema.`);
+            properties[arg] = argSchema;
+        }
+    }
+    const base = opt('leanschema') ? LEAN_ACTION_DESCRIPTION : fn.description;
+    const description = helpers.length
+        ? `${base} Full-preset helpers: ${helpers.map((name) => `${name} (${HELPER_ACTIONS[name].hint})`).join(', ')}.`
+        : base;
+    const patched = { ...fn, description, [schemaKey]: { ...schema, properties } };
+    return provider === 'openai' ? { ...outer, function: patched } : patched;
+}
+const OBJ = (properties, required = []) => ({
+    type: 'object',
+    additionalProperties: false,
+    ...(required.length ? { required } : {}),
+    properties,
+});
+const CALL_SCHEMA = OBJ({
+    operationId: { type: 'string', description: 'Exact operation id, e.g. "doc.tables.setShading".' },
+    args: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {},
+        description: 'Operation parameters as documented by superdoc_api_search.',
+    },
+    changeMode: {
+        type: 'string',
+        enum: ['direct', 'tracked'],
+        description: 'Only for operations whose catalog entry says supportsTrackedMode.',
+    },
+    dryRun: { type: 'boolean', description: 'Only for operations whose catalog entry says supportsDryRun.' },
+}, ['operationId']);
+export const FULL_TOOL_DEFINITIONS = [
+    {
+        name: 'superdoc_api_search',
+        description: `Search the complete SuperDoc Document API catalog (${CATALOG_SIZE} operations: footnotes, images, table shading/borders, sections & page layout, headers/footers, TOC, fields, bookmarks, hyperlinks, content controls, comments, tracked changes, diff …). Use only when neither a superdoc_perform_action verb nor an operation under QUICK REFERENCE in the system prompt fits. {query} keyword search or {domain} browse returns operation ids with one-line descriptions; {operationId} returns the full parameter schema for one operation. Read-only.`,
+        inputSchema: OBJ({
+            query: {
+                type: 'string',
+                description: 'Keywords, e.g. "footnote insert", "cell shading", "page margins", "header text".',
+            },
+            domain: {
+                type: 'string',
+                description: 'Browse one namespace: tables, lists, format, sections, headerFooters, footnotes, images, toc, fields, bookmarks, hyperlinks, comments, trackChanges, contentControls, styles, blocks, diff, create, document (root ops like insert/replace/delete/getMarkdown).',
+            },
+            operationId: { type: 'string', description: 'Exact id (e.g. "doc.footnotes.insert") to get its parameters.' },
+            operationIds: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Up to 8 exact ids to describe in ONE call when a recipe needs several operations.',
+            },
+            mutatingOnly: { type: 'boolean' },
+            limit: { type: 'integer', minimum: 1, maximum: 24 },
+        }),
+    },
+    {
+        name: 'superdoc_api_call',
+        description: 'Invoke ANY Document API operation by id with its native arguments — the general-purpose edit surface behind superdoc_perform_action. Operations under QUICK REFERENCE in the system prompt are called directly; look any other up with superdoc_api_search first (exact params, mutates?, supportsTrackedMode?, supportsDryRun?). Pass ONE call as {operationId, args} or SEVERAL as {calls:[{operationId,args},…]} — a batch runs in order in one round trip and stops at the first failure, returning per-call receipts. Block targets: {kind:"block", nodeType, nodeId} (nodeIds from superdoc_inspect). Positions: {kind:"documentEnd"|"documentStart"} or {kind:"before"|"after", target:<block>}. Text spans: {kind:"text", segments:[{blockId, range:{start,end}}]}. Image src may be a file path, URL, or data URI. Never pass doc or sessionId.',
+        inputSchema: OBJ({
+            operationId: { type: 'string', description: 'Exact operation id for a single call.' },
+            args: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {},
+                description: 'Parameters for the single call.',
+            },
+            changeMode: { type: 'string', enum: ['direct', 'tracked'] },
+            dryRun: { type: 'boolean' },
+            calls: {
+                type: 'array',
+                minItems: 1,
+                maxItems: 40,
+                items: CALL_SCHEMA,
+                description: 'Batch: several operations executed in order in one round trip.',
+            },
+        }),
+    },
+];
+const EXECUTE_CODE_DEFINITION = AGENT_TOOL_DEFINITIONS.find((d) => d.name === 'superdoc_execute_code');
+if (!EXECUTE_CODE_DEFINITION)
+    throw new Error('full preset: superdoc_execute_code definition missing from agent catalog');
+const FULL_ONLY_TOOL_NAMES = new Set(FULL_TOOL_DEFINITIONS.map((d) => d.name));
+function extraDefinitions(includeExec) {
+    return includeExec
+        ? [...FULL_TOOL_DEFINITIONS, EXECUTE_CODE_DEFINITION]
+        : [...FULL_TOOL_DEFINITIONS];
+}
+function toProviderTool(provider, def) {
+    if (provider === 'anthropic')
+        return { name: def.name, description: def.description, input_schema: def.inputSchema };
+    if (provider === 'generic')
+        return { name: def.name, description: def.description, parameters: def.inputSchema };
+    if (provider === 'vercel')
+        return { name: def.name, description: def.description, inputSchema: def.inputSchema };
+    return { type: 'function', function: { name: def.name, description: def.description, parameters: def.inputSchema } };
+}
+async function fullGetTools(includeExec, provider, options) {
+    const { helpers, coreOptions } = resolveHelperPolicy(options);
+    const coreTools = listAgentTools(provider, coreOptions).map((tool) => {
+        const name = provider === 'openai'
+            ? tool.function?.name
+            : tool.name;
+        return name === 'superdoc_perform_action' ? withHelperActions(provider, tool, helpers) : tool;
+    });
+    const extra = extraDefinitions(includeExec).map((d) => toProviderTool(provider, d));
+    const tools = [...coreTools, ...extra];
+    if (options?.cache !== true)
+        return { tools, cacheStrategy: 'disabled' };
+    if (provider === 'anthropic') {
+        const last = { ...tools[tools.length - 1], cache_control: { type: 'ephemeral' } };
+        return { tools: [...tools.slice(0, -1), last], cacheStrategy: 'explicit' };
+    }
+    if (provider === 'openai')
+        return { tools, cacheStrategy: 'automatic' };
+    return { tools, cacheStrategy: 'unsupported' };
+}
+async function fullGetCatalog(includeExec) {
+    const core = await corePreset.getCatalog();
+    const extra = extraDefinitions(includeExec).map((d) => ({
+        toolName: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        mutates: d.name !== 'superdoc_api_search',
+        operations: [],
+    }));
+    const coreTools = core.tools.map((tool) => tool.toolName === 'superdoc_perform_action'
+        ? withHelperActions('vercel', tool, resolveHelperPolicy().helpers)
+        : tool);
+    const tools = [...coreTools, ...extra];
+    return {
+        contractVersion: includeExec ? 'full-exec/v3' : 'full/v3',
+        generatedAt: null,
+        toolCount: tools.length,
+        tools,
+    };
+}
+let _addendumCache = null;
+const EXEC_ADDENDUM = [
+    '',
+    'CODE EXECUTION (full-exec only)',
+    '',
+    '- superdoc_execute_code runs a JavaScript body IN-HOST against a SYNCHRONOUS `doc` (never `await` doc.* calls) — use it ONLY when a loop with per-item decisions cannot be expressed as a superdoc_api_call batch. Return a short summary. Do NOT call doc.save/close.',
+    '- Never re-implement with superdoc_execute_code what one operation or one batch does, and never use it to bypass a refused tracked mode.',
+].join('\n');
+const HELPER_PROMPT_MENTIONS = {
+    compare_with_file: [
+        ', compare_with_file {path} (differences land here as tracked changes)',
+        '; compare_with_file {path} lands the text differences as tracked changes',
+        ', compare_with_file',
+        '- Compare two documents: superdoc_perform_action {action:"compare_with_file", path:"…/other.docx"} — differences land in THIS document as tracked changes; comments/styles/numbering differences apply directly.\n',
+    ],
+};
+function withoutUnofferedHelpers(addendum, helpers) {
+    let text = addendum;
+    for (const [name, mentions] of Object.entries(HELPER_PROMPT_MENTIONS)) {
+        if (helpers.includes(name))
+            continue;
+        for (const mention of mentions)
+            text = text.replace(mention, '');
+    }
+    return text;
+}
+async function fullGetSystemPrompt(includeExec, options) {
+    const { helpers, coreOptions } = resolveHelperPolicy(options);
+    const base = await corePreset.getSystemPrompt(coreOptions);
+    if (_addendumCache == null) {
+        _addendumCache = await readPromptFile('full-addendum.md', 'Full preset addendum');
+    }
+    const helperNote = helpers.length
+        ? ` This preset adds the actions ${helpers.join(', ')} (see EXTENDED SURFACE).`
+        : '';
+    const toolLines = [
+        `  superdoc_perform_action    — named edit verbs we authored, tested, and validate statically. Pass {action:"name", ...flat args}.${helperNote}`,
+        `  superdoc_api_search        — search / describe the ${CATALOG_SIZE}-operation Document API when no action fits.`,
+        '  superdoc_api_call          — invoke any Document API operation by id, singly or as a batch.',
+    ];
+    if (includeExec)
+        toolLines.push('  superdoc_execute_code      — in-host JavaScript against the synchronous doc API for multi-step work.');
+    const count = includeExec ? 'five' : 'four';
+    const pruned = opt('leanprompt') ? withoutActionLines(base) : base;
+    const addendum = withoutUnofferedHelpers(opt('leanaddendum') ? LEAN_ADDENDUM : _addendumCache, helpers);
+    const rewritten = pruned
+        .replace('TOOLS — two of them', `TOOLS — ${count} of them`)
+        .replace('  superdoc_perform_action    — named edit verbs we authored, tested, and validate statically. Pass {action:"name", ...flat args}.', toolLines.join('\n'))
+        .replace('If no action expresses the request, say what is missing rather than faking it.', 'If no action expresses the request, escalate: superdoc_api_search → superdoc_api_call (see EXTENDED SURFACE below). Say something is impossible only after the catalog has no operation for it.');
+    const extended = (opt('trustcalls')
+        ? addendum.replace(/- After a structural superdoc_api_call[^\n]*\n/, '- A superdoc_api_call receipt with success:true (or a batch with completed === total) IS the verification; do not spend a superdoc_inspect call to confirm what the receipt already proves.\n')
+        : addendum).replace('{{QUICK_REFERENCE}}\n', opt('quickref') ? `\n${quickReference()}\n` : '');
+    const rules = opt('trustreceipts') ? withReceiptRule(rewritten) : rewritten;
+    return `${rules}\n\n${extended}${includeExec ? `\n${EXEC_ADDENDUM}` : ''}`;
+}
+const RECEIPT_RULE = '- A receipt with status "ok" IS the verification of that edit: do not call superdoc_inspect only to confirm it. Reads the task itself needs (answering a question, matching formatting) and the STALENESS rule below still apply.';
+function withReceiptRule(prompt) {
+    const anchor = prompt.indexOf('- RECEIPTS ARE THE TRUTH.');
+    if (anchor < 0)
+        return prompt;
+    const lineEnd = prompt.indexOf('\n', anchor);
+    if (lineEnd < 0)
+        return prompt;
+    return `${prompt.slice(0, lineEnd + 1)}${RECEIPT_RULE}\n${prompt.slice(lineEnd + 1)}`;
+}
+function withoutActionLines(prompt) {
+    const start = prompt.indexOf('ACTIONS (superdoc_perform_action with flat args)');
+    const end = prompt.indexOf('Selector shapes:');
+    if (start < 0 || end < 0 || end < start)
+        return prompt;
+    const headerEnd = prompt.indexOf('\n', prompt.indexOf('====', start + 10)) + 1;
+    if (headerEnd <= 0 || headerEnd > end)
+        return prompt;
+    return (prompt.slice(0, headerEnd) +
+        '\nEvery action, with its arguments and when to use it, is documented in the superdoc_perform_action tool description. Pass flat args; selector-taking args use the shapes below.\n\n' +
+        prompt.slice(end));
+}
+function compactInspect(result) {
+    if (result == null || typeof result !== 'object' || Array.isArray(result))
+        return result;
+    const out = {};
+    for (const [key, value] of Object.entries(result)) {
+        if (Array.isArray(value)) {
+            if (value.length === 0 && key !== 'blocks')
+                continue;
+            if (key === 'headerFooters') {
+                const kept = value.filter((slot) => !(slot &&
+                    typeof slot === 'object' &&
+                    Array.isArray(slot.blocks) &&
+                    slot.blocks.length === 0));
+                if (kept.length === 0)
+                    continue;
+                out[key] = kept;
+                continue;
+            }
+            out[key] = value.map((item) => compactRow(item));
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function compactRow(row) {
+    if (row == null || typeof row !== 'object' || Array.isArray(row))
+        return row;
+    const r = row;
+    const out = {};
+    for (const [key, value] of Object.entries(r)) {
+        if (value === null || value === undefined)
+            continue;
+        if (key === 'tabCount' && value === 0)
+            continue;
+        if (key === 'textPreview' && typeof value === 'string' && typeof r.text === 'string') {
+            const stem = value.endsWith('…') ? value.slice(0, -1) : value;
+            if (r.text.startsWith(stem))
+                continue;
+        }
+        out[key] = Array.isArray(value) ? value.map((item) => compactRow(item)) : value;
+    }
+    return out;
+}
+async function runHelperAction(documentHandle, action, args, invokeOptions) {
+    const helper = HELPER_ACTIONS[action];
+    if (!trackedEnforcementOf(invokeOptions))
+        return helper.run(documentHandle, args, invokeOptions);
+    if (helper.disposition === 'direct') {
+        if (!resolveHelperPolicy(invokeOptions).helpers.includes(action)) {
+            throw new SuperDocCliError(`Action ${action} edits the document directly and is refused under enforceChangeMode: "tracked". Pass it in allowDirectActions to permit it.`, {
+                code: 'INVALID_ARGUMENT',
+                details: { toolName: 'superdoc_perform_action', action, excluded: true, reason: 'direct-only' },
+            });
+        }
+        const result = await helper.run(documentHandle, args, withoutTrackedEnforcement(invokeOptions));
+        return isRecord(result)
+            ? { ...result, changeMode: 'direct', changeModeForced: args.changeMode === 'tracked' }
+            : result;
+    }
+    const result = await helper.run(documentHandle, { ...args, changeMode: 'tracked' }, invokeOptions);
+    return isRecord(result)
+        ? { ...result, changeMode: 'tracked', changeModeForced: args.changeMode !== 'tracked' }
+        : result;
+}
+async function fullDispatch(includeExec, documentHandle, toolName, args, invokeOptions) {
+    if (args == null || typeof args !== 'object' || Array.isArray(args)) {
+        throw new SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
+            code: 'INVALID_ARGUMENT',
+            details: { toolName },
+        });
+    }
+    if (!includeExec && toolName === 'superdoc_execute_code') {
+        throw new SuperDocCliError('superdoc_execute_code is disabled in the full preset. Use superdoc_api_call (a {calls:[…]} batch covers multi-step edits).', { code: 'TOOL_DISPATCH_NOT_FOUND', details: { toolName, preset: 'full' } });
+    }
+    refuseOperationsOutsideTheDocument(toolName, args);
+    if (toolName === 'superdoc_perform_action' && typeof args.action === 'string' && args.action in HELPER_ACTIONS) {
+        const excluded = invokeOptions?.excludeActions;
+        if (excluded?.includes(args.action)) {
+            throw new SuperDocCliError(`Action "${args.action}" is excluded on this surface.`, {
+                code: 'INVALID_ARGUMENT',
+                details: { action: args.action },
+            });
+        }
+        if (args.dryRun !== undefined && args.dryRun !== false) {
+            throw new SuperDocCliError(`Action ${args.action} has no dry run and would edit the document. Nothing was changed. Describe the planned change instead, or call it without dryRun.`, { code: 'INVALID_ARGUMENT', details: { action: args.action, supportsDryRun: false } });
+        }
+        return runHelperAction(documentHandle, args.action, args, invokeOptions);
+    }
+    if (!FULL_ONLY_TOOL_NAMES.has(toolName)) {
+        const level = toolName === 'superdoc_perform_action' ? headingLevelOf(args) : null;
+        const before = level && (await authoredHeadingStyle(documentHandle, level, invokeOptions).then(Boolean, () => true))
+            ? await headingIds(documentHandle, invokeOptions)
+            : null;
+        const result = await corePreset.dispatch(documentHandle, toolName, args, invokeOptions);
+        if (level && before)
+            await adoptAuthoredHeadingStyle(documentHandle, level, before, args.action !== 'apply_style', invokeOptions);
+        return toolName === 'superdoc_inspect' && opt('compactinspect') ? compactInspect(result) : result;
+    }
+    switch (toolName) {
+        case 'superdoc_api_search':
+            return runCatalog(args);
+        case 'superdoc_api_call':
+            return runOperation(documentHandle, args, invokeOptions);
+    }
+    throw new SuperDocCliError(`Unknown tool: ${toolName}`, {
+        code: 'TOOL_DISPATCH_NOT_FOUND',
+        details: { toolName, preset: 'full' },
+    });
+}
+function operationIdsNamedBy(toolName, args) {
+    if (!isRecord(args))
+        return [];
+    if (toolName === 'agent_operation')
+        return [args.operationId];
+    if (toolName !== 'agent_apply')
+        return [];
+    const steps = isRecord(args.plan) && Array.isArray(args.plan.steps) ? args.plan.steps : [];
+    return steps.flatMap((step) => isRecord(step) && (step.kind === 'apply' || step.kind === 'inspect' || step.operationId !== undefined)
+        ? [step.operationId]
+        : []);
+}
+function refuseOperationsOutsideTheDocument(toolName, args) {
+    for (const operationId of operationIdsNamedBy(toolName, stripCorruptedToolArgKeys(args))) {
+        const op = typeof operationId === 'string'
+            ? CONTRACT.operations[operationId]
+            : undefined;
+        if (op && isDocumentOp(op))
+            continue;
+        throw new SuperDocCliError(`${toolName} cannot run ${String(operationId)}: only document operations are callable here. Nothing was run. Call superdoc_api_call with an operation from superdoc_api_search.`, { code: 'TOOL_DISPATCH_NOT_FOUND', details: { toolName, operationId, reason: 'not-a-document-operation' } });
+    }
+}
+function headingLevelOf(args) {
+    const raw = args.action === 'insert_heading'
+        ? args.level
+        : args.action === 'insert_paragraphs' || args.action === 'apply_style'
+            ? args.headingLevel
+            : undefined;
+    const level = Number(raw);
+    return Number.isInteger(level) && level >= 1 && level <= 6 ? level : null;
+}
+async function headingIds(doc, invokeOptions) {
+    try {
+        const inspect = (await corePreset.dispatch(doc, 'superdoc_inspect', { blockOffset: 0, blockLimit: 400, omitEmptyBlocks: true, dropTextPreview: true }, invokeOptions));
+        return new Map((inspect?.blocks ?? []).filter((b) => b.headingLevel != null).map((b) => [b.nodeId, b]));
+    }
+    catch {
+        return null;
+    }
+}
+async function authoredHeadingStyle(doc, level, invokeOptions) {
+    const catalog = (await resolveMethod(doc, 'doc.styles.getCatalog')({ view: 'currentDocument', types: ['paragraph'] }, forwardOptions(invokeOptions)));
+    const items = catalog?.items ?? [];
+    const own = new RegExp(`^(?:h|heading[ _-]?)${level}$`, 'i');
+    const reserved = new RegExp(`^heading ?${level}$`, 'i');
+    const authored = items.filter((s) => s.provenance === 'authored' && (own.test(s.id) || own.test(s.name ?? '')) && !reserved.test(s.name ?? ''));
+    return authored.length === 1 ? { style: authored[0], items, reserved } : null;
+}
+async function adoptAuthoredHeadingStyle(doc, level, before, inserted, invokeOptions) {
+    try {
+        const found = await authoredHeadingStyle(doc, level, invokeOptions);
+        if (!found)
+            return;
+        const { items, reserved } = found;
+        const target = found.style.id;
+        const after = await headingIds(doc, invokeOptions);
+        if (!after)
+            return;
+        const strays = [...after.values()].filter((b) => b.headingLevel === level &&
+            b.styleId &&
+            b.styleId !== target &&
+            reserved.test(items.find((s) => s.id === b.styleId)?.name ?? '') &&
+            before.get(b.nodeId)?.styleId !== b.styleId);
+        const setStyle = resolveMethod(doc, 'doc.styles.paragraph.setStyle');
+        for (const block of strays) {
+            await setStyle({ target: { kind: 'block', nodeType: block.nodeType, nodeId: block.nodeId }, styleId: target }, forwardOptions(invokeOptions));
+        }
+        if (!inserted)
+            return;
+        const adopted = [...after.values()].filter((b) => b.headingLevel === level && !before.has(b.nodeId) && (b.styleId === target || strays.includes(b)));
+        await clearRedundantHeadingFormatting(doc, found.style, level, adopted, invokeOptions);
+    }
+    catch { }
+}
+export async function clearRedundantHeadingFormatting(doc, style, level, headings, invokeOptions) {
+    if (headings.length === 0)
+        return;
+    const definition = await readStyleDefinition(doc, style, invokeOptions);
+    if (!definition)
+        return;
+    const opts = forwardOptions(invokeOptions);
+    if (definition.paragraph?.outlineLvl === level - 1) {
+        const setOutlineLevel = resolveMethod(doc, 'doc.format.paragraph.setOutlineLevel');
+        for (const heading of headings) {
+            await setOutlineLevel({ target: { kind: 'block', nodeType: heading.nodeType, nodeId: heading.nodeId }, outlineLevel: null }, opts);
+        }
+    }
+    if (definition.run?.bold === true) {
+        const rows = await listBlocks(doc, { nodeIds: headings.map((h) => h.nodeId), includeText: true }, invokeOptions);
+        const match = resolveMethod(doc, 'doc.query.match');
+        const formatApply = resolveMethod(doc, 'doc.format.apply');
+        for (const row of rows) {
+            if (!row.text)
+                continue;
+            const found = (await match({
+                select: { type: 'text', pattern: row.text },
+                within: { kind: 'block', nodeType: row.nodeType, nodeId: row.nodeId },
+                require: 'first',
+            }, opts));
+            const direct = (found?.items ?? [])
+                .flatMap((item) => item.blocks ?? [])
+                .filter((block) => block.blockId === row.nodeId)
+                .flatMap((block) => block.runs ?? [])
+                .map((run) => run.styles?.direct?.bold);
+            if (!direct.includes('on') || direct.includes('off'))
+                continue;
+            const point = (offset) => ({ kind: 'text', blockId: row.nodeId, offset });
+            await formatApply({ target: { kind: 'selection', start: point(0), end: point(row.text.length) }, inline: { bold: null } }, opts);
+        }
+    }
+}
+function buildFullPreset(id, includeExec, description) {
+    return {
+        id,
+        description,
+        supportsCacheControl: true,
+        getTools: (provider, options) => fullGetTools(includeExec, provider, options),
+        getCatalog: () => fullGetCatalog(includeExec),
+        getSystemPrompt: (options) => fullGetSystemPrompt(includeExec, options),
+        getMcpPrompt: () => corePreset.getMcpPrompt(),
+        dispatch: (documentHandle, toolName, args, invokeOptions) => fullDispatch(includeExec, documentHandle, toolName, args, invokeOptions),
+    };
+}
+export const fullPreset = buildFullPreset('full', false, 'Experimental: core preset plus progressive disclosure of the entire Document API — superdoc_api_search (search the whole operation catalog), superdoc_api_call (call any op, batchable), and four helper actions on superdoc_perform_action (insert_image, insert_footnote, shade_cells, compare_with_file). No code execution.');
+export const fullExecPreset = buildFullPreset('full-exec', true, 'Internal A/B variant of `full` that also advertises superdoc_execute_code (unsandboxed in-host JavaScript). Not registered, not for production.');