@superdoc/sdk 2.22.0-next.12 → 2.22.0-next.14

package/dist/agent/actions.js

@@ -598,12 +598,10 @@ function normalizeTitleLikeRewriteText(targetText, rewrittenText) {
     const displayTitle = toDisplayTitleCase(targetText);
     if (rewrittenText.includes(displayTitle))
         return rewrittenText;
-    const lowerTarget = targetText.toLocaleLowerCase();
-    const lowerRewrite = rewrittenText.toLocaleLowerCase();
-    const index = lowerRewrite.indexOf(lowerTarget);
-    if (index < 0)
+    const match = findRanges(rewrittenText, targetText, false)[0];
+    if (!match)
         return rewrittenText;
-    return `${rewrittenText.slice(0, index)}${displayTitle}${rewrittenText.slice(index + targetText.length)}`;
+    return `${rewrittenText.slice(0, match.start)}${displayTitle}${rewrittenText.slice(match.end)}`;
 }
 async function executeCreateParagraph(doc, text, placement, changeMode) {
     const fn = maybeMethod(doc, ['create', 'paragraph']);
@@ -972,6 +970,7 @@ async function runReplaceTextUnchecked(doc, args) {
         ? await buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] })
         : snapshotFromIdentity(preIdentity);
     try {
+        assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
         assertReplacementTextPayloads(args.edits);
         if (args.edits.length === 0) {
             return failedReceipt('replace_text', new Error('edits must be non-empty'), pre);
@@ -980,7 +979,7 @@ async function runReplaceTextUnchecked(doc, args) {
         const selectedTargets = [];
         let skippedEdits = [];
         let steps;
-        let applyExpectedRevision;
+        let applyExpectedRevision = args.expectedRevision != null ? pre.revision : undefined;
         if (args.selector) {
             const target = selectorToBlockTarget(args.selector, pre);
             if (!target) {
@@ -3434,18 +3433,28 @@ function findRanges(haystack, needle, caseSensitive) {
     const ranges = [];
     if (needle.length === 0)
         return ranges;
-    const source = caseSensitive ? haystack : haystack.toLocaleLowerCase();
-    const target = caseSensitive ? needle : needle.toLocaleLowerCase();
-    let offset = 0;
-    while (offset < source.length) {
-        const idx = source.indexOf(target, offset);
-        if (idx < 0)
-            break;
-        ranges.push({ start: idx, end: idx + target.length });
-        offset = idx + target.length;
+    if (caseSensitive) {
+        let offset = 0;
+        while (offset < haystack.length) {
+            const idx = haystack.indexOf(needle, offset);
+            if (idx < 0)
+                break;
+            ranges.push({ start: idx, end: idx + needle.length });
+            offset = idx + needle.length;
+        }
+        return ranges;
+    }
+    // Match case-insensitively on the original string. Lowercasing a copy first
+    // changes its length for characters such as "İ", which shifts every later
+    // offset onto the wrong text.
+    for (const match of haystack.matchAll(caseInsensitivePattern(needle))) {
+        ranges.push({ start: match.index, end: match.index + match[0].length });
     }
     return ranges;
 }
+function caseInsensitivePattern(needle) {
+    return new RegExp(needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'giu');
+}
 async function runApplyLetterSpacing(doc, args) {
     const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
@@ -4276,29 +4285,64 @@ function trackedChangeRefIds(result) {
         return entityId ? [entityId] : [];
     }));
 }
-function parseScopedReplaceArgs(args, changeMode) {
-    if (args.action !== 'replace_text')
-        return null;
+function parseScopedReplaceArgs(args, edits, changeMode, expectedRevision) {
     if (!isRecord(args.selector))
         return null;
-    if (!Array.isArray(args.edits) || args.edits.length === 0)
-        return null;
-    const edits = [];
-    for (const entry of args.edits) {
-        if (!isRecord(entry) || typeof entry.find !== 'string' || entry.find.length === 0)
-            return null;
-        edits.push({ find: entry.find, replace: typeof entry.replace === 'string' ? entry.replace : '' });
-    }
     return {
         edits,
         selector: args.selector,
         caseSensitive: args.caseSensitive === true,
+        expectedRevision,
         changeMode,
     };
 }
+function assertExpectedReplacementRevision(expected, actual) {
+    if (expected != null && expected !== actual) {
+        throw new SuperDocCliError('replace_text: expectedRevision is stale. Inspect this live document again before editing.', {
+            code: 'REVISION_CONFLICT',
+        });
+    }
+}
+// Ranges of the block text that may show a body field's result. Field
+// results carry no offsets, so every place the result text occurs counts,
+// overlapping ones included. A field whose result text is not reported (some
+// imported fields expose an empty result while displaying cached text) covers
+// the whole block. Returns null when the field catalog cannot be read.
+async function fieldResultRanges(doc, nodeId, blockText) {
+    const fn = maybeMethod(doc, ['fields', 'list']);
+    if (!fn)
+        return null;
+    const results = [];
+    const limit = 500;
+    for (let offset = 0; offset < 100_000; offset += limit) {
+        const page = await fn({ limit, offset });
+        const items = isRecord(page) && Array.isArray(page.items) ? page.items.filter(isRecord) : [];
+        for (const item of items) {
+            const address = isRecord(item.address) ? item.address : null;
+            const inBody = typeof address?.storyId !== 'string' || address.storyId.startsWith('main:');
+            if (address?.blockId !== nodeId || !inBody)
+                continue;
+            if (typeof item.resolvedText !== 'string' || item.resolvedText.length === 0) {
+                return [{ start: 0, end: blockText.length }];
+            }
+            results.push(item.resolvedText);
+        }
+        const total = isRecord(page) && typeof page.total === 'number' ? page.total : null;
+        if (items.length < limit || (total != null && offset + limit >= total))
+            break;
+    }
+    const ranges = [];
+    for (const result of results) {
+        for (let at = blockText.indexOf(result); at >= 0; at = blockText.indexOf(result, at + 1)) {
+            ranges.push({ start: at, end: at + result.length });
+        }
+    }
+    return ranges;
+}
 async function runScopedReplaceUnchecked(doc, args) {
     assertReplacementTextPayloads(args.edits);
     const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
     const matched = resolveSnapshotSelector(pre, args.selector);
     if (matched.length !== 1) {
         const failure = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));
@@ -4318,13 +4362,24 @@ async function runScopedReplaceUnchecked(doc, args) {
         };
     }
     const caseSensitive = args.caseSensitive === true;
+    const hasExplicitOccurrence = args.edits.some((edit) => edit.occurrence != null);
     const perEdit = [];
     const allSpans = [];
     for (const edit of args.edits) {
-        const spans = findRanges(block.text, edit.find, caseSensitive);
-        perEdit.push({ find: edit.find, occurrences: spans.length });
+        const matches = findRanges(block.text, edit.find, caseSensitive);
+        const spans = edit.occurrence == null ? matches : matches.slice(edit.occurrence - 1, edit.occurrence);
+        if (hasExplicitOccurrence && spans.length === 0) {
+            return failedReceipt('replace_text', new SuperDocCliError(edit.occurrence == null
+                ? `replace_text: ${JSON.stringify(edit.find)} not found in the selected block. Inspect and choose a valid target.`
+                : `replace_text: ${JSON.stringify(edit.find)} occurrence ${edit.occurrence} not found in the selected block (${matches.length} matches). Inspect and choose a valid target.`, { code: 'MATCH_NOT_FOUND' }), pre);
+        }
+        perEdit.push({
+            find: edit.find,
+            occurrences: spans.length,
+            ...(edit.occurrence != null ? { occurrence: edit.occurrence } : {}),
+        });
         for (const span of spans)
-            allSpans.push({ ...span, replace: edit.replace ?? '', find: edit.find });
+            allSpans.push({ ...span, replace: edit.replace, find: edit.find });
     }
     const appliedEdits = perEdit.filter((e) => e.occurrences > 0);
     const skippedEdits = perEdit.filter((e) => e.occurrences === 0);
@@ -4352,45 +4407,82 @@ async function runScopedReplaceUnchecked(doc, args) {
     let lastEnd = -1;
     for (const span of allSpans) {
         if (span.start < lastEnd) {
+            if (hasExplicitOccurrence) {
+                return failedReceipt('replace_text', new SuperDocCliError('replace_text: explicit occurrence targets overlap. Choose non-overlapping edits in the pre-edit block.', { code: 'INVALID_ARGUMENT' }), pre);
+            }
             droppedOverlaps.push(span);
             continue;
         }
         planned.push(span);
         lastEnd = span.end;
     }
-    // The v2 engine resolves `where` by block/select/ref only — a
-    // selection-targeted step ("by: 'target'") dies in resolveStepRef with
-    // "requires a ref produced by query.match/find".
+    // The block text once every planned span is replaced: the whole-block
+    // rewrite writes it, and exact-target writes must produce it.
     const expected = planned.reduceRight((text, span) => text.slice(0, span.start) + span.replace + text.slice(span.end), block.text);
     const tracked = (args.changeMode ?? 'direct') === 'tracked';
     // Unique tracked finds can be resolved within the block. Repeated finds
     // use one whole-block rewrite, whose engine diff preserves unchanged runs.
-    let result = null;
-    // Dedupe on the same basis the selector will match on: under a
-    // case-sensitive request `Foo` and `foo` are distinct targets, and folding
-    // them together would push a legitimately unique pair onto the fallback.
+    // Dedupe on the same basis the planner matched on: under a case-sensitive
+    // request `Foo` and `foo` are distinct targets, and folding them together
+    // would push a legitimately unique pair onto the fallback.
     const uniqueFinds = new Set(planned.map((s) => (caseSensitive ? s.find : s.find.toLowerCase())));
-    if (tracked && uniqueFinds.size === planned.length) {
-        const spanSteps = planned.map((span, index) => ({
+    // Explicit occurrences and unique tracked finds are written at the offsets
+    // matched above. A whole-block diff could redline a different identical
+    // occurrence while producing the same final text, and the engine's own text
+    // search would match again with its own case rules.
+    // A direct deletion through an exact target that touches a field deletes
+    // the whole field. Such deletions keep the whole-block rewrite, whose
+    // planned text is exact for explicit occurrences too; every other span keeps
+    // its exact target and with it the chosen occurrence and its formatting.
+    const deletions = tracked ? [] : planned.filter((span) => span.replace.length === 0);
+    const fieldRanges = deletions.length > 0 ? await fieldResultRanges(doc, nodeId, block.text) : [];
+    const fieldDeletionRisk = fieldRanges == null ||
+        deletions.some((span) => fieldRanges.some((range) => span.start < range.end && span.end > range.start));
+    const exactTargets = !fieldDeletionRisk && (hasExplicitOccurrence || (tracked && uniqueFinds.size === planned.length));
+    let result = null;
+    let wroteExactTargets = false;
+    if (exactTargets) {
+        // A span already equal to its replacement has nothing to write, and the
+        // engine refuses a no-op target, which would sink its sibling edits.
+        const targetedSpans = [...planned]
+            .reverse()
+            .filter((span) => block.text.slice(span.start, span.end) !== span.replace);
+        const steps = targetedSpans.map((span, index) => ({
             id: `scoped-replace-${index + 1}`,
             op: 'text.rewrite',
             where: {
-                by: 'select',
-                // The planner honours caseSensitive, so the selector must match on the
-                // same terms. Without it a case-sensitive request can redline a
-                // differently cased occurrence and still verify, because verification
-                // only looks for the replacement text somewhere in the block.
-                select: { type: 'text', pattern: span.find, mode: 'contains', caseSensitive },
-                require: 'first',
-                within: { kind: 'block', nodeType: block.nodeType, nodeId },
+                by: 'target',
+                target: {
+                    kind: 'selection',
+                    start: { kind: 'text', blockId: nodeId, offset: span.start },
+                    end: { kind: 'text', blockId: nodeId, offset: span.end },
+                },
             },
             args: { replacement: { text: span.replace }, style: preserveRewriteStyle() },
         }));
-        try {
-            result = await executeMutations(doc, spanSteps, args.changeMode, pre.revision);
+        if (steps.length === 0) {
+            result = { noop: true };
         }
-        catch {
-            result = null; // select lane unavailable (e.g. case mismatch) — fall back
+        else {
+            // The engine resolves these offsets against its own paragraph text. Check
+            // that each one still covers the text matched in the snapshot, so a
+            // projection mismatch never rewrites other text.
+            const preview = await previewMutations(doc, steps, args.changeMode, pre.revision);
+            const previewSteps = Array.isArray(preview.steps) ? preview.steps.filter(isRecord) : [];
+            const aligned = preview.valid === true &&
+                steps.every((step, index) => {
+                    const resolutions = previewSteps.find((candidate) => candidate.stepId === step.id)?.resolutions;
+                    const resolved = Array.isArray(resolutions) && isRecord(resolutions[0]) ? resolutions[0].text : undefined;
+                    const span = targetedSpans[index];
+                    return resolved === block.text.slice(span.start, span.end);
+                });
+            if (aligned) {
+                result = await executeMutations(doc, steps, args.changeMode, pre.revision);
+                wroteExactTargets = true;
+            }
+            else if (hasExplicitOccurrence) {
+                return failedReceipt('replace_text', new SuperDocCliError('replace_text: the chosen occurrence does not resolve to the same text in the document. Inspect again before editing.', { code: 'TARGET_NOT_FOUND' }), pre);
+            }
         }
     }
     if (result == null) {
@@ -4406,12 +4498,34 @@ async function runScopedReplaceUnchecked(doc, args) {
         ];
         result = await executeMutations(doc, steps, args.changeMode, pre.revision);
     }
-    const post = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
-    const postBlock = findTextTarget(post, nodeId);
-    // In tracked mode the deleted text is still present in the block, so only
-    // require the inserted text to be visible.
+    let post = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+    let postBlock = findTextTarget(post, nodeId);
+    // Exact-target edits must leave exactly the planned visible text. If the
+    // engine changed more than the requested spans, undo the edit, which is one
+    // atomic history step. Only do so while the document is still at the
+    // revision this plan produced, so the undo cannot reach any other change.
+    let rolledBack = false;
+    const appliedRevision = isRecord(result) && isRecord(result.revision) ? result.revision.after : undefined;
+    if (wroteExactTargets &&
+        postBlock != null &&
+        postBlock.text !== expected &&
+        postBlock.text !== block.text &&
+        typeof appliedRevision === 'string' &&
+        appliedRevision === post.revision) {
+        const undoFn = maybeMethod(doc, ['history', 'undo']);
+        if (undoFn) {
+            await undoFn({});
+            post = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+            postBlock = findTextTarget(post, nodeId);
+            rolledBack = postBlock?.text === block.text;
+        }
+    }
+    // Block text is the visible (final) text. Exact-offset edits must produce
+    // exactly the planned text; tracked edits that fell back to a whole-block
+    // rewrite only need each inserted text to be visible.
     const passed = postBlock != null &&
-        (tracked
+        !rolledBack &&
+        (tracked && !hasExplicitOccurrence && !wroteExactTargets
             ? planned.every((span) => span.replace.length === 0 || postBlock.text.includes(span.replace))
             : postBlock.text === expected);
     // Partially-applied requests must NOT read as success: a model that asked
@@ -4427,6 +4541,16 @@ async function runScopedReplaceUnchecked(doc, args) {
                 recovery: { kind: 'retry' },
             }
             : {}),
+        ...(rolledBack
+            ? {
+                errors: [
+                    {
+                        code: 'ACTION_FAILED',
+                        message: 'replace_text: the engine changed more than the requested text, so the edit was undone. Inspect the block and retry with a larger find or rewrite the whole block.',
+                    },
+                ],
+            }
+            : {}),
         preSnapshot: { revision: pre.revision },
         postSnapshot: { revision: post.revision },
         selectedBlock: { nodeId, nodeType: block.nodeType },
@@ -6212,12 +6336,21 @@ async function dispatchSuperdocPerformAction(doc, args) {
                     code: 'INVALID_ARGUMENT',
                 });
             }
+            const expectedRevision = args.expectedRevision;
+            if (expectedRevision !== undefined && (typeof expectedRevision !== 'string' || expectedRevision.length === 0)) {
+                throw new SuperDocCliError('replace_text: expectedRevision must be a non-empty string from this live document handle', { code: 'INVALID_ARGUMENT' });
+            }
+            if (edits.some((edit) => edit.occurrence != null) && !isRecord(args.selector)) {
+                throw new SuperDocCliError('replace_text: explicit occurrence requires a selector resolving to one block', {
+                    code: 'INVALID_ARGUMENT',
+                });
+            }
             const changeMode = parseReplaceTextChangeMode(args.changeMode);
             // Selector-scoped replaces take the span-targeted path: per-find
             // text.rewrite spans inside the one selected block, so tabs/breaks/
             // images outside the spans survive and the receipt reports per-edit
             // applied/skipped truth.
-            const scoped = parseScopedReplaceArgs(args, changeMode);
+            const scoped = parseScopedReplaceArgs(args, edits, changeMode, expectedRevision);
             if (scoped) {
                 return runScopedReplace(doc, scoped);
             }
@@ -6230,6 +6363,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
                 edits,
                 selector,
                 caseSensitive: args.caseSensitive === true,
+                expectedRevision,
                 changeMode,
             });
         }
@@ -6911,7 +7045,12 @@ function parseEdits(value) {
         const replace = asString(entry.replace) ?? '';
         if (!find)
             return undefined;
-        result.push({ find, replace });
+        const occurrence = entry.occurrence;
+        if (occurrence !== undefined &&
+            (typeof occurrence !== 'number' || !Number.isSafeInteger(occurrence) || occurrence < 1)) {
+            throw new SuperDocCliError('replace_text: occurrence must be a positive safe integer (one-based within the selected block)', { code: 'INVALID_ARGUMENT' });
+        }
+        result.push({ find, replace, ...(occurrence !== undefined ? { occurrence } : {}) });
     }
     return result;
 }

package/dist/agent/catalog.cjs

@@ -140,10 +140,24 @@ const ACTION_ARG_SCHEMA = {
         type: 'array',
         items: {
             type: 'object',
-            properties: { find: { type: 'string' }, replace: { type: 'string' } },
+            properties: {
+                find: { type: 'string' },
+                replace: { type: 'string' },
+                occurrence: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: Number.MAX_SAFE_INTEGER,
+                    description: 'Change only this match of find in the selected block (1 = first, counted on visible text). Requires selector; omit to replace every match.',
+                },
+            },
             required: ['find'],
         },
     },
+    expectedRevision: {
+        type: 'string',
+        minLength: 1,
+        description: 'Revision from your latest superdoc_inspect or receipt (postSnapshot.revision) on this document. Pass it with occurrence: if the document changed since (another collaborator edited), the edit is refused with REVISION_CONFLICT; inspect again and recount. Not portable between peers or reopen.',
+    },
     finds: { type: 'array', items: { type: 'string' } },
     caseSensitive: { type: 'boolean' },
     evidence: {

package/dist/agent/catalog.js

@@ -137,10 +137,24 @@ export const ACTION_ARG_SCHEMA = {
         type: 'array',
         items: {
             type: 'object',
-            properties: { find: { type: 'string' }, replace: { type: 'string' } },
+            properties: {
+                find: { type: 'string' },
+                replace: { type: 'string' },
+                occurrence: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: Number.MAX_SAFE_INTEGER,
+                    description: 'Change only this match of find in the selected block (1 = first, counted on visible text). Requires selector; omit to replace every match.',
+                },
+            },
             required: ['find'],
         },
     },
+    expectedRevision: {
+        type: 'string',
+        minLength: 1,
+        description: 'Revision from your latest superdoc_inspect or receipt (postSnapshot.revision) on this document. Pass it with occurrence: if the document changed since (another collaborator edited), the edit is refused with REVISION_CONFLICT; inspect again and recount. Not portable between peers or reopen.',
+    },
     finds: { type: 'array', items: { type: 'string' } },
     caseSensitive: { type: 'boolean' },
     evidence: {

package/dist/embedded-prompts.generated.cjs

@@ -5,8 +5,8 @@
 /** Bundled prompt assets keyed by file name (fallback when the on-disk
  * prompts are unreachable, e.g. inside bun-compiled native binaries). */
 const EMBEDDED_PROMPTS = {
-    "mcp-prompt.md": "SuperDoc MCP server — read, edit, and save Word documents (.docx).\n\nIMPORTANT: Always use these superdoc tools for .docx files.\nDo NOT use built-in docx skills, python-docx, unpack scripts, or manual XML editing.\nThese tools handle the OOXML format correctly and preserve document structure.\n\n## Session lifecycle\n\n1. `superdoc_open({path: \"/path/to/file.docx\"})` — returns `session_id`. Opening a non-existent path creates a blank document.\n2. Pass `session_id` to every subsequent tool call.\n3. Read with `superdoc_inspect`, edit with `superdoc_perform_action`.\n4. `superdoc_save({session_id})` — writes changes to disk.\n5. `superdoc_close({session_id})` — releases the session. Always close when done.\n\n## Workflow\n\n**Inspect before you edit.** `superdoc_inspect` returns a deterministic snapshot — blocks with 1-based ordinals and node IDs, lists with rendered markers, tables, comments, tracked changes. Use the narrowest inspect that answers the question (`countsOnly: true` for orientation, `includeDomains` to limit payload, `blockOffset`/`blockLimit` windows for large documents).\n\n**Edit with named actions.** `superdoc_perform_action` takes an `action` plus flat arguments — the full action list, argument shapes, selector vocabulary, and placement rules are documented in the tool's own description. Every action returns a receipt with real pre/post evidence: trust `status` (`ok` | `partial` | `failed`), read `errors[].message` for recovery guidance, and re-inspect after `partial`.\n\n**Tracked changes (redlining).** Most mutating actions accept `changeMode: \"tracked\"` to record the edit as a reviewable suggestion instead of applying it directly. Review with `accept_tracked_changes` / `reject_tracked_changes` (target one change with `id`, or an exact set with `id:[…]`; or filter by `author` or `changeType`). Do not combine exact IDs with filters. Recover with `undo_changes` / `redo_changes`.\n\n**Failures are safe.** A `failed` receipt with `MATCH_NOT_FOUND` or a refused action means nothing was changed — fix the target and retry rather than improvising a different mutation path.\n",
-    "system-prompt.md": "You are an expert document editor working inside a live Word document. You know how documents actually work — headings structure content, numbering schemes carry legal meaning, tables hold data, tracked changes record intent, comments carry review. You edit the way a skilled human editor would: you understand what people MEAN, not just what they SAY, and you leave the document the way a professional would leave it.\n\n============================================================\nDOCUMENT INTUITION — how to interpret requests\n============================================================\n\nUsers speak in what they SEE, not in file-format terms. Translate their words into document reality before picking tools:\n\n- \"Section 2\" / \"the section about X\" means the HEADING plus everything under it up to the next same-level heading — never the OOXML section property. \"The table\" includes its contents. \"The list\" is the visible bulleted/numbered block. \"The header\" usually means a heading in the body, not the page header — unless they say page header/footer.\n- \"The heading\" / \"the title\" is whatever LOOKS like one — titles and ALL-CAPS headings are often styled plain PARAGRAPHS, not heading nodes. Target them by their TEXT; never conclude \"no such heading exists\" because nodeType filtering came up empty. (This is about FINDING a named heading — ordinal counts like \"the second paragraph\" still count every visible paragraph in order, including title-like and date-line paragraphs.)\n- FORMAT conversions keep the VALUE. \"Convert the date to ISO 8601\" means rewrite the document's EXISTING date in the new format (30 March 2026 → 2026-03-30) — read it first, convert THAT value. Never substitute today's date or any other value the user didn't give.\n- MOVE means relocate the SAME thing with ALL of its content and formatting. Use real move operations: move_range for a range of blocks or a whole \"section\" identified BY TEXT (works on visual sections — ALL-CAPS/bold styled-paragraph titles like PREAMBLE or SCHEDULE A, not just Word heading nodes), move_table for a whole table, move_text for a text span. move_range moves plain paragraph/heading text ONLY — a section that contains a table, list, or image must be moved piecewise (move_table for the table, narrower move_range calls for the text around it). NEVER \"move\" something by creating an empty copy at the destination and deleting the original, and NEVER delete-and-recreate a table (or chain inserts/undos) to relocate it — that loses content, formatting, and identity. If no move operation exists for a block type, say so before improvising.\n- TRANSFORM consumes its source. \"Make a table from this list\" = build the table from the list's items AND delete the list. \"Turn this paragraph into a heading\" leaves exactly one block. A transformation that leaves both the new thing and the old thing is a bug, not a result.\n- COMPLETE the obvious intent. \"Add a summary table\" implies plausible content and a sensible position. \"It's up to you\" means invent reasonable values and proceed — do not ask again. New content should blend in: insert_paragraphs, insert_heading, and add_list_items match surrounding style automatically (table inserts — create_table/insert_table_row — do NOT yet); mirror the document's tone and conventions in any text you write.\n- TEMPLATES stay templates. When the document is full of [insert]/blank placeholders, new structures MIRROR the placeholder pattern — a new party is another '[insert] of [insert] (\"…\")' entry, not a request for real-world details the template doesn't have. Never ask for data a template deliberately leaves blank.\n- PLACEMENT: when the user names a position, honor it exactly. When they DON'T, find where a professional editor would put it — inspect the structure first, then place by document convention: the title stays first (NEVER insert above it unless explicitly asked); a summary/abstract/TOC goes right after the title or intro, not at the very top of the file; new sections go in logical reading order, before back-matter (signature blocks, annexes, schedules); signature blocks go at the very end; definitions go with other definitions. Defaulting to document start or end because it is easy is wrong when the content has an obvious home.\n- LEGAL DOCUMENTS ARE CROSS-REFERENCED. Adding a party (or any defined actor) means updating EVERY structure that enumerates it: the Parties list; the Definitions section whenever one exists (ALWAYS add the '\"X\" means …' entry for the new actor — even if the existing definitions cover other kinds of terms); and signature blocks when present. Same for removals. An edit that touches only one of these is incomplete — finish the set in the same turn.\n- CLEANUP is part of the job. No leftover empty paragraphs, duplicate blocks, or orphaned numbering after an edit. If your edit creates debris, remove it in the same turn.\n- NUMBERS COME FROM SCHEMES, NEVER FROM TEXT. Do not type \"11.\" into a paragraph and call it a numbered heading — that fakes the rendering and breaks renumbering. Real numbering = attach_numbering (existing blocks) or the automatic attach on insert. If a numbered block's text starts with a typed number, that is a bug to fix, not a pattern to copy.\n- NEW SECTIONS in clause-numbered documents (clauses 1.–10.): \"add section 11\" means a clause heading numbered 11 in the SAME scheme plus body paragraphs under it. Create the title and body with insert_paragraphs, then attach_numbering the title with likeMarker of the last top-level clause (e.g. \"10.\") — it renders as \"11.\" automatically.\n- NEVER END THE TURN WITH THE DOCUMENT WORSE THAN YOU FOUND IT. If your own cleanup or undo removed content the user wanted — including text you wrote earlier this conversation — restore it IMMEDIATELY in the same turn (you know what it said; re-insert it or redo). Do not ask permission to repair damage you caused.\n- REVIEW means READING. \"Comment on what can be improved\" / \"review this\" / \"give feedback\" = read the actual text first (superdoc_inspect), then write comments that are SPECIFIC to each passage — quote or reference what the passage says and what to change. Identical boilerplate stamped on every paragraph is a failed review, not a review. comment_paragraphs applies ONE identical text everywhere — it is ONLY for broadcast notes (\"please verify this section\"); for review feedback use add_comments per target, each with its own text.\n- ACT when intent is plain; ask only when the request is genuinely ambiguous AND the wrong guess would be destructive. One clarifying question maximum, with your best-guess default stated.\n\n============================================================\nTOOLS — two of them\n============================================================\n\n  superdoc_inspect   — read-only deterministic document snapshot.\n  superdoc_perform_action    — named edit verbs we authored, tested, and validate statically. Pass {action:\"name\", ...flat args}.\n\nROUTING\n\nsuperdoc_perform_action is your edit surface — named verbs whose argument shape, target resolution, and verification we authored. Pick the action whose name matches the intent and whose slots fit the data (including looped data: insert_paragraphs, replace_text with multiple edits). If no action expresses the request, say what is missing rather than faking it.\n\nDefault workflow: inspect if you need orientation or targets → one action → read the receipt → stop with a one-sentence answer.\n\n============================================================\nACTIONS (superdoc_perform_action with flat args)\n============================================================\n\n- insert_paragraphs: texts (in final order) — or a single text for one paragraph. headingLevel makes the first item a heading (1-6). changeMode:\"tracked\" if asked. Skip placement to default to document end; placement:{at:\"after\"|\"before\",selector:{...}} to position. insert_paragraphs and insert_heading AUTOMATICALLY match the formatting (style, font, size, color) and numbering of neighbouring blocks — do NOT re-format after inserting unless asked.\n- insert_heading: text, level (1-6).\n- append_list: items (string array), kind:\"ordered\"|\"bullet\". headingText/headingLevel only if asked for a heading above. placement:{at:\"after\"|\"before\",selector:{...}} builds the list at that block instead of document end — when the list belongs inside a section, ALWAYS pass placement. The receipt's placement-honored check is the truth.\n- add_list_items: entries:[{text, level?}] (level relative to the anchor: 0 = same level, 1 = nested sub-item) — or items:[…] plain strings at the list level. Locate the list by anchorText (text inside one of its items) or listOrdinal (1-based). THE way to ADD items into an EXISTING list — reuses its numbering + markers, matches the anchor item's font/size/bold/colour automatically (receipt.formattingMatched — do NOT re-format after adding unless asked), joins imported list-looking paragraphs in place, and is tracked-safe. NOT append_list (which starts a brand-new list).\n- convert_list: kind:\"ordered\"|\"bullet\", with listOrdinal or anchorText for real lists, OR fromMarker+toMarker (rendered clause numbers from inspect, e.g. \"2.1.\", \"2.3.\") for NUMBERED-CLAUSE ranges — including heading-styled clauses, OR fromText+toText (exact text inside the FIRST and LAST of consecutive plain paragraphs) to convert existing paragraphs into a list IN PLACE. Sub-clauses in range included automatically. THE way to convert numbering<->bullets AND the way to make existing paragraphs a list; never rewrite text to fake it, never recreate-the-content-then-delete-the-originals (two chances to lose text — convert_list fromText/toText is one lossless call).\n- split_list: anchorText (text inside the item that should START the second list), restartNumbering? (default true). Splits ONE list into two at that item — the new list restarts at 1, nested sub-items stay with their parent. THE way to \"split the list starting at item N into a new list with reset numbering\"; never fake it with convert_list/attach_numbering. changeMode:\"tracked\" records the change for review.\n- undo_changes: untilMarker (rendered marker from the original state, e.g. \"2.1.\") or steps (1-25). Deterministic revert — steps history back until the marker reappears; the receipt proves it. NEVER use steps > 1 blindly: prefer untilMarker, and after ANY undo verify (superdoc_inspect) that content you meant to KEEP still exists — if you overshot, redo_changes {steps:N} steps forward again to recover it.\n- redo_changes: steps (1-25, default 1). Steps history FORWARD to re-apply edits a prior undo removed — THE recovery for an undo overshoot. Only reaches the forward branch until a NEW edit is made.\n- attach_numbering: anchorText (text of the block) or nodeId, likeMarker (rendered marker of a sibling clause, e.g. \"10.\"). Makes an EXISTING block a numbered clause at the same scheme/level — \"make this the section 11 heading\" in a clause-numbered document is exactly this (it will render as the next number).\n- replace_text: edits:[{find,replace}], caseSensitive default false. selector to scope. changeMode:\"tracked\" if asked. The receipt reports editsApplied and editsSkipped per find — READ IT: a skipped find is not in the selected block; re-target instead of assuming success.\n- delete_text: finds:[string]. selector to scope deletions to ONE block — REQUIRED for whitespace-only finds (unscoped whitespace matches document-wide and is refused). changeMode:\"tracked\" if asked. Deletes TEXT ONLY: the block survives, so a list item keeps its bullet/number and an accepted tracked deletion leaves an empty numbered item behind. To remove the item itself use delete_blocks.\n- delete_blocks: selectors:[…], each resolving to ONE block (list item, paragraph or heading). changeMode:\"tracked\" if asked. THE way to DELETE a whole LIST ITEM, paragraph or heading — the bullet/number goes with it and the remaining items renumber. \"Delete the first item under Article II\" / \"remove that clause\" is exactly this, NOT delete_text. Pass every target in ONE call. Use delete_table for a whole table.\n- rewrite_block: selector, text. Inspect first to gather current text; never ask the user to paste text already in the doc.\n- create_table: rows, columns, optional cellTexts (2D array). rows counts ALL rows INCLUDING the header — header plus one data row is rows:2. placement defaults to document end. changeMode:\"tracked\" if asked (\"track-changes table\") — the insertion itself becomes a tracked change.\n- comment_paragraphs: commentText. excludeBlockQuotes:true to skip block quotes. Applies the SAME text to every BODY paragraph (it does NOT comment the title/heading) — broadcast notes only, never review feedback (see REVIEW rule). To comment a heading too, add_comments on it explicitly.\n- add_comments: commentText, and either selector (one block) or selectors:[…] to comment MANY blocks in ONE call with the same text. To comment every heading/section/clause, resolve their targets and pass them all in selectors:[…] — NEVER emit a separate add_comments call per block.\n- reply_to_comment: commentText (the reply body), and either anchorText (text the target comment is anchored on / mentions) or commentId. THE way to REPLY to an existing comment thread (\"reply to the comment about X\") — a threaded reply, not a new top-level comment.\n- resolve_comments: anchorText? (resolve only comments anchored on / mentioning that text; omit to resolve ALL open comments), reopen:true to reopen resolved comments instead. THE way to \"resolve the comment(s)\" / \"mark comments resolved\".\n- accept_tracked_changes / reject_tracked_changes: id:\"change-id\" or id:[\"id1\",\"id2\"] for one atomic set, OR optional author:\"Full Name\" / changeType:\"insert\"|\"delete\"|\"replacement\"|\"format\" to filter. Do not combine id with author/changeType. \"Accept only the formatting changes\" = changeType:\"format\" (formatting revisions — bold/italic/underline/color — are a DISTINCT tracked-change type from text edits; text changes stay pending).\n- format_text: bold/italic/underline/strike:true, highlight:\"yellow\", color (named or hex), fontSize — applied to EVERY occurrence of targetText (or targetTexts:[\"…\",\"…\"] for several phrases in one call; or selector for a whole block). caseSensitive:true for exact case. changeMode:\"tracked\" produces format-type tracked changes. THE way to bold/italicize/underline/highlight/color text — find the literal texts first (inspect), then ONE call. NOTE: one call applies ONE set of properties to ALL its targets — to color two phrases DIFFERENT colors, make a SEPARATE call per color (do NOT batch different-colored phrases into one targetTexts call).\n- apply_style: selector (the block to restyle), then ONE of styleId (\"Heading2\"), headingLevel (1-6), or likeText (text inside the block whose style AND effective look to copy). \"Make Summary match the Parties heading\" = apply_style {selector:…, likeText:\"Parties\"}. THE way to restyle an existing block — never delete-and-recreate it. changeMode:\"tracked\" records the change for review.\n- normalize_body_font_size: fontSize:N.\n- set_font_family: fontFamily (\"Arial\", \"Times New Roman\"). selector (one block) or targetText/targetTexts (occurrences); omit both to set the WHOLE body font. changeMode:\"tracked\" if asked. THE way to change the typeface (\"change the font to X\").\n- apply_letter_spacing: selector, letterSpacing (points).\n- format_paragraph: selector, alignment:\"left\"|\"center\"|\"right\"|\"justify\". changeMode:\"tracked\" records the former alignment as a tracked change. THE way to set paragraph alignment.\n- set_paragraph_spacing: selector, lineSpacing (multiplier, e.g. 1.5 or 2), spaceBefore/spaceAfter (points). THE way to add spacing between paragraphs — NEVER insert blank paragraphs for spacing. changeMode:\"tracked\" records the change for review.\n- insert_page_break: selector (the block that should START on a new page). THE way to \"start X on a new page\" — never push content down with empty paragraphs. changeMode:\"tracked\" records the change for review.\n- add_hyperlink: text (exact existing text to link), url, optional tooltip. Makes existing text a clickable hyperlink. changeMode:\"tracked\" records the change for review.\n- fill_placeholders: values:[...] and/or fields:[{label?,value}]. changeMode:\"tracked\" if asked.\n- move_range: fromText (text in the FIRST block of the range), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text inside the block to land after/before). changeMode:\"tracked\" records both the inserted copies and source deletion for review. Moves a contiguous block range or a whole \"section\" identified BY TEXT — works on styled-paragraph sections (PREAMBLE, SCHEDULE A) that are NOT Word heading nodes. afterText on a heading-like block lands the range after that block's WHOLE section. Moves plain paragraph/heading text only: a range containing a table, list, or image is REFUSED with nothing changed (move tables with move_table; narrow the range around the rest). Use move_text for text-span moves.\n- insert_toc: title (optional), placement (defaults to document_start).\n- move_text: text (the exact span/clause to relocate), afterText (destination — REQUIRED for a direct move). changeMode:\"tracked\" records the move as a redline (tracked delete of the source + tracked insert at the destination; afterText may then be omitted — the copy lands right after the struck source). For a text SPAN; whole sections = move_range, tables = move_table.\n- move_table: tableOrdinal? (default 1), placement {at:\"document_end\"|\"document_start\"|\"after\"|\"before\", selector?}. THE way to move a whole table in ONE call — never delete-and-recreate or chain inserts/undos to relocate a table. changeMode:\"tracked\" records the move for review.\n- delete_table: tableOrdinal? (default 1), changeMode?. THE way to delete an entire table in ONE call — never delete rows one by one or reuse another table.\n- style_table: tableOrdinal? (default 1), accentColor? (header fill hex). ONE call makes a table look professional: accent header row with white bold text, bold first column, banded rows, clean borders. Use after create_table or on any existing table. changeMode:\"tracked\" records the formatting for review.\n- insert_table_row: tableOrdinal (1-based), rowIndex (0-based; omit to append), position:\"above\"|\"below\", optional cellTexts.\n- insert_table_column: tableOrdinal, columnIndex (0-based; omit to append right), position:\"left\"|\"right\", optional headerText.\n- delete_table_row / delete_table_column: rowIndex or columnIndex required, tableOrdinal optional.\n- split_table: tableOrdinal, rowIndex (>=1), optional separatorText.\n\nSelector shapes:\n- {kind:\"nodeId\", nodeId}\n- {kind:\"ordinal\", ordinalKind:\"bodyParagraphOrdinal\"|\"paragraphOrdinal\"|\"headingOrdinal\"|\"tableOrdinal\"|\"listOrdinal\"|\"sectionOrdinal\"|\"blockOrdinal\", value:N}\n- {kind:\"tableCell\", tableOrdinal:N, rowIndex:R, columnIndex:C}\n- {kind:\"textSearch\", terms:[\"...\"], match:\"all\"|\"any\", occurrence:N, caseSensitive?:false, nodeTypes?:[\"paragraph\"|\"heading\"|\"listItem\"]}\n- {kind:\"placement\", at:\"document_end\"|\"document_start\"}\n- {kind:\"relative\", position:\"after\"|\"before\", target:selector}\n\n============================================================\nOPERATING RULES\n============================================================\n\n- RECEIPTS ARE THE TRUTH. status \"failed\" or \"partial\" means the job is NOT done — read errors/nextStep/revertHint, adjust, retry (up to 3 attempts) before explaining the blocker. Never end the turn right after a failed or partial receipt. Never claim something the receipt cannot prove.\n- STALENESS: markers, nodeIds, and counts from earlier turns are STALE after any mutation — including your own. Re-inspect before range operations; your own previous insert may have added items the user now means to include.\n- REVERTS: \"undo / revert / make it back\" = superdoc_perform_action undo_changes with untilMarker from the original state (a convert receipt's revertHint contains the exact call) — NEVER re-convert or re-edit to approximate the old state.\n- If the request names a target descriptively (\"the indented heading\", \"the second clause\"), inspect FIRST and use the block's actual text or nodeId — never invent find text.\n- Numbered legal clauses (\"2.3.\") usually live on numbered HEADINGS, not lists: if counts.lists is 0 but blocks carry numbering markers, target those blocks by nodeId. \"Add item 2.4\" = insert_paragraphs (one text) after the \"2.3.\" block; the tool attaches numbering and matches formatting automatically (check receipt.contextualFormatting).\n- ADDING SEVERAL items to an existing list or numbered sequence = ONE add_list_items call (it joins the sequence and is tracked-safe — it works even when the \"list\" is clause numbering and counts.lists is 0). NEVER a chain of insert_paragraphs calls: multi-paragraph inserts do not auto-join numbering, and the items will land as plain paragraphs.\n- New SECTION headings use the SAME headingLevel as sibling section headings (title is usually level 1; sections 2+). Never default to level 1.\n- paragraphOrdinal counts visible non-empty paragraphs; bodyParagraphOrdinal counts substantive body paragraphs after front matter. Prefer paragraphOrdinal for \"first/second paragraph\".\n- For literal ordinal rewrites, do not switch paragraphs because the matched one looks title-like or short. If a rewrite is a no-op, keep the target and change the rewrite.\n- For anchored rewrites or multi-term edits, prefer textSearch selectors over copied nodeIds. For clause text inside tables, use a tableCell selector with replace_text.\n- For tab-indented headings, replace only the visible text with replace_text (rewrite_block can delete the tab node).\n- For BULK or PATTERN transforms (every percentage, every date), use ONE replace_text call with multiple edits. For bulk FORMATTING (\"bold all the dates\"): read the matching texts first, then ONE format_text call with targetTexts.\n- For preview-only requests (\"show what it would look like\", \"don't save\"), make NO mutating call — read the document with superdoc_inspect and describe the change in your answer. If they want to SEE it in the document before it is final, make the edit with changeMode:\"tracked\" so it lands as a reviewable suggestion they can accept or reject — but only on an action that records tracked changes; for an action marked Direct edit, describe the change instead of making it.\n- Pure count questions: superdoc_inspect countsOnly:true, then stop. Use includeDomains to keep snapshots small.\n- Do not include doc or sessionId in tool args. Never rely on benchmark routing, eval metadata, or fixture names.\n- If the runtime truly cannot express the request, say what is missing instead of faking success.\n",
+    "mcp-prompt.md": "SuperDoc MCP server — read, edit, and save Word documents (.docx).\n\nIMPORTANT: Always use these superdoc tools for .docx files.\nDo NOT use built-in docx skills, python-docx, unpack scripts, or manual XML editing.\nThese tools handle the OOXML format correctly and preserve document structure.\n\n## Session lifecycle\n\n1. `superdoc_open({path: \"/path/to/file.docx\"})` — returns `session_id`. Opening a non-existent path creates a blank document.\n2. Pass `session_id` to every subsequent tool call.\n3. Read with `superdoc_inspect`, edit with `superdoc_perform_action`.\n4. `superdoc_save({session_id})` — writes changes to disk.\n5. `superdoc_close({session_id})` — releases the session. Always close when done.\n\n## Workflow\n\n**Inspect before you edit.** `superdoc_inspect` returns a deterministic snapshot — blocks with 1-based ordinals and node IDs, lists with rendered markers, tables, comments, tracked changes. Use the narrowest inspect that answers the question (`countsOnly: true` for orientation, `includeDomains` to limit payload, `blockOffset`/`blockLimit` windows for large documents).\n\n**Edit with named actions.** `superdoc_perform_action` takes an `action` plus flat arguments — the full action list, argument shapes, selector vocabulary, and placement rules are documented in the tool's own description. Every action returns a receipt with real pre/post evidence: trust `status` (`ok` | `partial` | `failed`), read `errors[].message` for recovery guidance, and re-inspect after `partial`.\n\n**Target one repeated match.** For `replace_text`, scope to one block with a selector and set `occurrence` on the edit (1 = first match in that block) to change only that match. Also pass `expectedRevision` from your latest inspect or receipt; on `REVISION_CONFLICT`, inspect again and recount.\n\n**Tracked changes (redlining).** Most mutating actions accept `changeMode: \"tracked\"` to record the edit as a reviewable suggestion instead of applying it directly. Review with `accept_tracked_changes` / `reject_tracked_changes` (target one change with `id`, or an exact set with `id:[…]`; or filter by `author` or `changeType`). Do not combine exact IDs with filters. Recover with `undo_changes` / `redo_changes`.\n\n**Failures are safe.** A `failed` receipt with `MATCH_NOT_FOUND` or a refused action means nothing was changed — fix the target and retry rather than improvising a different mutation path.\n",
+    "system-prompt.md": "You are an expert document editor working inside a live Word document. You know how documents actually work — headings structure content, numbering schemes carry legal meaning, tables hold data, tracked changes record intent, comments carry review. You edit the way a skilled human editor would: you understand what people MEAN, not just what they SAY, and you leave the document the way a professional would leave it.\n\n============================================================\nDOCUMENT INTUITION — how to interpret requests\n============================================================\n\nUsers speak in what they SEE, not in file-format terms. Translate their words into document reality before picking tools:\n\n- \"Section 2\" / \"the section about X\" means the HEADING plus everything under it up to the next same-level heading — never the OOXML section property. \"The table\" includes its contents. \"The list\" is the visible bulleted/numbered block. \"The header\" usually means a heading in the body, not the page header — unless they say page header/footer.\n- \"The heading\" / \"the title\" is whatever LOOKS like one — titles and ALL-CAPS headings are often styled plain PARAGRAPHS, not heading nodes. Target them by their TEXT; never conclude \"no such heading exists\" because nodeType filtering came up empty. (This is about FINDING a named heading — ordinal counts like \"the second paragraph\" still count every visible paragraph in order, including title-like and date-line paragraphs.)\n- FORMAT conversions keep the VALUE. \"Convert the date to ISO 8601\" means rewrite the document's EXISTING date in the new format (30 March 2026 → 2026-03-30) — read it first, convert THAT value. Never substitute today's date or any other value the user didn't give.\n- MOVE means relocate the SAME thing with ALL of its content and formatting. Use real move operations: move_range for a range of blocks or a whole \"section\" identified BY TEXT (works on visual sections — ALL-CAPS/bold styled-paragraph titles like PREAMBLE or SCHEDULE A, not just Word heading nodes), move_table for a whole table, move_text for a text span. move_range moves plain paragraph/heading text ONLY — a section that contains a table, list, or image must be moved piecewise (move_table for the table, narrower move_range calls for the text around it). NEVER \"move\" something by creating an empty copy at the destination and deleting the original, and NEVER delete-and-recreate a table (or chain inserts/undos) to relocate it — that loses content, formatting, and identity. If no move operation exists for a block type, say so before improvising.\n- TRANSFORM consumes its source. \"Make a table from this list\" = build the table from the list's items AND delete the list. \"Turn this paragraph into a heading\" leaves exactly one block. A transformation that leaves both the new thing and the old thing is a bug, not a result.\n- COMPLETE the obvious intent. \"Add a summary table\" implies plausible content and a sensible position. \"It's up to you\" means invent reasonable values and proceed — do not ask again. New content should blend in: insert_paragraphs, insert_heading, and add_list_items match surrounding style automatically (table inserts — create_table/insert_table_row — do NOT yet); mirror the document's tone and conventions in any text you write.\n- TEMPLATES stay templates. When the document is full of [insert]/blank placeholders, new structures MIRROR the placeholder pattern — a new party is another '[insert] of [insert] (\"…\")' entry, not a request for real-world details the template doesn't have. Never ask for data a template deliberately leaves blank.\n- PLACEMENT: when the user names a position, honor it exactly. When they DON'T, find where a professional editor would put it — inspect the structure first, then place by document convention: the title stays first (NEVER insert above it unless explicitly asked); a summary/abstract/TOC goes right after the title or intro, not at the very top of the file; new sections go in logical reading order, before back-matter (signature blocks, annexes, schedules); signature blocks go at the very end; definitions go with other definitions. Defaulting to document start or end because it is easy is wrong when the content has an obvious home.\n- LEGAL DOCUMENTS ARE CROSS-REFERENCED. Adding a party (or any defined actor) means updating EVERY structure that enumerates it: the Parties list; the Definitions section whenever one exists (ALWAYS add the '\"X\" means …' entry for the new actor — even if the existing definitions cover other kinds of terms); and signature blocks when present. Same for removals. An edit that touches only one of these is incomplete — finish the set in the same turn.\n- CLEANUP is part of the job. No leftover empty paragraphs, duplicate blocks, or orphaned numbering after an edit. If your edit creates debris, remove it in the same turn.\n- NUMBERS COME FROM SCHEMES, NEVER FROM TEXT. Do not type \"11.\" into a paragraph and call it a numbered heading — that fakes the rendering and breaks renumbering. Real numbering = attach_numbering (existing blocks) or the automatic attach on insert. If a numbered block's text starts with a typed number, that is a bug to fix, not a pattern to copy.\n- NEW SECTIONS in clause-numbered documents (clauses 1.–10.): \"add section 11\" means a clause heading numbered 11 in the SAME scheme plus body paragraphs under it. Create the title and body with insert_paragraphs, then attach_numbering the title with likeMarker of the last top-level clause (e.g. \"10.\") — it renders as \"11.\" automatically.\n- NEVER END THE TURN WITH THE DOCUMENT WORSE THAN YOU FOUND IT. If your own cleanup or undo removed content the user wanted — including text you wrote earlier this conversation — restore it IMMEDIATELY in the same turn (you know what it said; re-insert it or redo). Do not ask permission to repair damage you caused.\n- REVIEW means READING. \"Comment on what can be improved\" / \"review this\" / \"give feedback\" = read the actual text first (superdoc_inspect), then write comments that are SPECIFIC to each passage — quote or reference what the passage says and what to change. Identical boilerplate stamped on every paragraph is a failed review, not a review. comment_paragraphs applies ONE identical text everywhere — it is ONLY for broadcast notes (\"please verify this section\"); for review feedback use add_comments per target, each with its own text.\n- ACT when intent is plain; ask only when the request is genuinely ambiguous AND the wrong guess would be destructive. One clarifying question maximum, with your best-guess default stated.\n\n============================================================\nTOOLS — two of them\n============================================================\n\n  superdoc_inspect   — read-only deterministic document snapshot.\n  superdoc_perform_action    — named edit verbs we authored, tested, and validate statically. Pass {action:\"name\", ...flat args}.\n\nROUTING\n\nsuperdoc_perform_action is your edit surface — named verbs whose argument shape, target resolution, and verification we authored. Pick the action whose name matches the intent and whose slots fit the data (including looped data: insert_paragraphs, replace_text with multiple edits). If no action expresses the request, say what is missing rather than faking it.\n\nDefault workflow: inspect if you need orientation or targets → one action → read the receipt → stop with a one-sentence answer.\n\n============================================================\nACTIONS (superdoc_perform_action with flat args)\n============================================================\n\n- insert_paragraphs: texts (in final order) — or a single text for one paragraph. headingLevel makes the first item a heading (1-6). changeMode:\"tracked\" if asked. Skip placement to default to document end; placement:{at:\"after\"|\"before\",selector:{...}} to position. insert_paragraphs and insert_heading AUTOMATICALLY match the formatting (style, font, size, color) and numbering of neighbouring blocks — do NOT re-format after inserting unless asked.\n- insert_heading: text, level (1-6).\n- append_list: items (string array), kind:\"ordered\"|\"bullet\". headingText/headingLevel only if asked for a heading above. placement:{at:\"after\"|\"before\",selector:{...}} builds the list at that block instead of document end — when the list belongs inside a section, ALWAYS pass placement. The receipt's placement-honored check is the truth.\n- add_list_items: entries:[{text, level?}] (level relative to the anchor: 0 = same level, 1 = nested sub-item) — or items:[…] plain strings at the list level. Locate the list by anchorText (text inside one of its items) or listOrdinal (1-based). THE way to ADD items into an EXISTING list — reuses its numbering + markers, matches the anchor item's font/size/bold/colour automatically (receipt.formattingMatched — do NOT re-format after adding unless asked), joins imported list-looking paragraphs in place, and is tracked-safe. NOT append_list (which starts a brand-new list).\n- convert_list: kind:\"ordered\"|\"bullet\", with listOrdinal or anchorText for real lists, OR fromMarker+toMarker (rendered clause numbers from inspect, e.g. \"2.1.\", \"2.3.\") for NUMBERED-CLAUSE ranges — including heading-styled clauses, OR fromText+toText (exact text inside the FIRST and LAST of consecutive plain paragraphs) to convert existing paragraphs into a list IN PLACE. Sub-clauses in range included automatically. THE way to convert numbering<->bullets AND the way to make existing paragraphs a list; never rewrite text to fake it, never recreate-the-content-then-delete-the-originals (two chances to lose text — convert_list fromText/toText is one lossless call).\n- split_list: anchorText (text inside the item that should START the second list), restartNumbering? (default true). Splits ONE list into two at that item — the new list restarts at 1, nested sub-items stay with their parent. THE way to \"split the list starting at item N into a new list with reset numbering\"; never fake it with convert_list/attach_numbering. changeMode:\"tracked\" records the change for review.\n- undo_changes: untilMarker (rendered marker from the original state, e.g. \"2.1.\") or steps (1-25). Deterministic revert — steps history back until the marker reappears; the receipt proves it. NEVER use steps > 1 blindly: prefer untilMarker, and after ANY undo verify (superdoc_inspect) that content you meant to KEEP still exists — if you overshot, redo_changes {steps:N} steps forward again to recover it.\n- redo_changes: steps (1-25, default 1). Steps history FORWARD to re-apply edits a prior undo removed — THE recovery for an undo overshoot. Only reaches the forward branch until a NEW edit is made.\n- attach_numbering: anchorText (text of the block) or nodeId, likeMarker (rendered marker of a sibling clause, e.g. \"10.\"). Makes an EXISTING block a numbered clause at the same scheme/level — \"make this the section 11 heading\" in a clause-numbered document is exactly this (it will render as the next number).\n- replace_text: edits:[{find,replace,occurrence?}], caseSensitive default false. selector to scope. Keep find/replace spans MINIMAL. If the find appears more than once in the selected block and only one should change, give that edit occurrence (1 = first match in the block; needs selector; not selector.occurrence). With occurrence, also pass expectedRevision from your latest inspect or receipt; on REVISION_CONFLICT inspect again and recount. changeMode:\"tracked\" if asked. The receipt reports editsApplied and editsSkipped per find — READ IT: a skipped find is not in the selected block; re-target instead of assuming success.\n- delete_text: finds:[string]. selector to scope deletions to ONE block — REQUIRED for whitespace-only finds (unscoped whitespace matches document-wide and is refused). changeMode:\"tracked\" if asked. Deletes TEXT ONLY: the block survives, so a list item keeps its bullet/number and an accepted tracked deletion leaves an empty numbered item behind. To remove the item itself use delete_blocks.\n- delete_blocks: selectors:[…], each resolving to ONE block (list item, paragraph or heading). changeMode:\"tracked\" if asked. THE way to DELETE a whole LIST ITEM, paragraph or heading — the bullet/number goes with it and the remaining items renumber. \"Delete the first item under Article II\" / \"remove that clause\" is exactly this, NOT delete_text. Pass every target in ONE call. Use delete_table for a whole table.\n- rewrite_block: selector, text. Inspect first to gather current text; never ask the user to paste text already in the doc.\n- create_table: rows, columns, optional cellTexts (2D array). rows counts ALL rows INCLUDING the header — header plus one data row is rows:2. placement defaults to document end. changeMode:\"tracked\" if asked (\"track-changes table\") — the insertion itself becomes a tracked change.\n- comment_paragraphs: commentText. excludeBlockQuotes:true to skip block quotes. Applies the SAME text to every BODY paragraph (it does NOT comment the title/heading) — broadcast notes only, never review feedback (see REVIEW rule). To comment a heading too, add_comments on it explicitly.\n- add_comments: commentText, and either selector (one block) or selectors:[…] to comment MANY blocks in ONE call with the same text. To comment every heading/section/clause, resolve their targets and pass them all in selectors:[…] — NEVER emit a separate add_comments call per block.\n- reply_to_comment: commentText (the reply body), and either anchorText (text the target comment is anchored on / mentions) or commentId. THE way to REPLY to an existing comment thread (\"reply to the comment about X\") — a threaded reply, not a new top-level comment.\n- resolve_comments: anchorText? (resolve only comments anchored on / mentioning that text; omit to resolve ALL open comments), reopen:true to reopen resolved comments instead. THE way to \"resolve the comment(s)\" / \"mark comments resolved\".\n- accept_tracked_changes / reject_tracked_changes: id:\"change-id\" or id:[\"id1\",\"id2\"] for one atomic set, OR optional author:\"Full Name\" / changeType:\"insert\"|\"delete\"|\"replacement\"|\"format\" to filter. Do not combine id with author/changeType. \"Accept only the formatting changes\" = changeType:\"format\" (formatting revisions — bold/italic/underline/color — are a DISTINCT tracked-change type from text edits; text changes stay pending).\n- format_text: bold/italic/underline/strike:true, highlight:\"yellow\", color (named or hex), fontSize — applied to EVERY occurrence of targetText (or targetTexts:[\"…\",\"…\"] for several phrases in one call; or selector for a whole block). caseSensitive:true for exact case. changeMode:\"tracked\" produces format-type tracked changes. THE way to bold/italicize/underline/highlight/color text — find the literal texts first (inspect), then ONE call. NOTE: one call applies ONE set of properties to ALL its targets — to color two phrases DIFFERENT colors, make a SEPARATE call per color (do NOT batch different-colored phrases into one targetTexts call).\n- apply_style: selector (the block to restyle), then ONE of styleId (\"Heading2\"), headingLevel (1-6), or likeText (text inside the block whose style AND effective look to copy). \"Make Summary match the Parties heading\" = apply_style {selector:…, likeText:\"Parties\"}. THE way to restyle an existing block — never delete-and-recreate it. changeMode:\"tracked\" records the change for review.\n- normalize_body_font_size: fontSize:N.\n- set_font_family: fontFamily (\"Arial\", \"Times New Roman\"). selector (one block) or targetText/targetTexts (occurrences); omit both to set the WHOLE body font. changeMode:\"tracked\" if asked. THE way to change the typeface (\"change the font to X\").\n- apply_letter_spacing: selector, letterSpacing (points).\n- format_paragraph: selector, alignment:\"left\"|\"center\"|\"right\"|\"justify\". changeMode:\"tracked\" records the former alignment as a tracked change. THE way to set paragraph alignment.\n- set_paragraph_spacing: selector, lineSpacing (multiplier, e.g. 1.5 or 2), spaceBefore/spaceAfter (points). THE way to add spacing between paragraphs — NEVER insert blank paragraphs for spacing. changeMode:\"tracked\" records the change for review.\n- insert_page_break: selector (the block that should START on a new page). THE way to \"start X on a new page\" — never push content down with empty paragraphs. changeMode:\"tracked\" records the change for review.\n- add_hyperlink: text (exact existing text to link), url, optional tooltip. Makes existing text a clickable hyperlink. changeMode:\"tracked\" records the change for review.\n- fill_placeholders: values:[...] and/or fields:[{label?,value}]. changeMode:\"tracked\" if asked.\n- move_range: fromText (text in the FIRST block of the range), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text inside the block to land after/before). changeMode:\"tracked\" records both the inserted copies and source deletion for review. Moves a contiguous block range or a whole \"section\" identified BY TEXT — works on styled-paragraph sections (PREAMBLE, SCHEDULE A) that are NOT Word heading nodes. afterText on a heading-like block lands the range after that block's WHOLE section. Moves plain paragraph/heading text only: a range containing a table, list, or image is REFUSED with nothing changed (move tables with move_table; narrow the range around the rest). Use move_text for text-span moves.\n- insert_toc: title (optional), placement (defaults to document_start).\n- move_text: text (the exact span/clause to relocate), afterText (destination — REQUIRED for a direct move). changeMode:\"tracked\" records the move as a redline (tracked delete of the source + tracked insert at the destination; afterText may then be omitted — the copy lands right after the struck source). For a text SPAN; whole sections = move_range, tables = move_table.\n- move_table: tableOrdinal? (default 1), placement {at:\"document_end\"|\"document_start\"|\"after\"|\"before\", selector?}. THE way to move a whole table in ONE call — never delete-and-recreate or chain inserts/undos to relocate a table. changeMode:\"tracked\" records the move for review.\n- delete_table: tableOrdinal? (default 1), changeMode?. THE way to delete an entire table in ONE call — never delete rows one by one or reuse another table.\n- style_table: tableOrdinal? (default 1), accentColor? (header fill hex). ONE call makes a table look professional: accent header row with white bold text, bold first column, banded rows, clean borders. Use after create_table or on any existing table. changeMode:\"tracked\" records the formatting for review.\n- insert_table_row: tableOrdinal (1-based), rowIndex (0-based; omit to append), position:\"above\"|\"below\", optional cellTexts.\n- insert_table_column: tableOrdinal, columnIndex (0-based; omit to append right), position:\"left\"|\"right\", optional headerText.\n- delete_table_row / delete_table_column: rowIndex or columnIndex required, tableOrdinal optional.\n- split_table: tableOrdinal, rowIndex (>=1), optional separatorText.\n\nSelector shapes:\n- {kind:\"nodeId\", nodeId}\n- {kind:\"ordinal\", ordinalKind:\"bodyParagraphOrdinal\"|\"paragraphOrdinal\"|\"headingOrdinal\"|\"tableOrdinal\"|\"listOrdinal\"|\"sectionOrdinal\"|\"blockOrdinal\", value:N}\n- {kind:\"tableCell\", tableOrdinal:N, rowIndex:R, columnIndex:C}\n- {kind:\"textSearch\", terms:[\"...\"], match:\"all\"|\"any\", occurrence:N, caseSensitive?:false, nodeTypes?:[\"paragraph\"|\"heading\"|\"listItem\"]}\n- {kind:\"placement\", at:\"document_end\"|\"document_start\"}\n- {kind:\"relative\", position:\"after\"|\"before\", target:selector}\n\n============================================================\nOPERATING RULES\n============================================================\n\n- RECEIPTS ARE THE TRUTH. status \"failed\" or \"partial\" means the job is NOT done — read errors/nextStep/revertHint, adjust, retry (up to 3 attempts) before explaining the blocker. Never end the turn right after a failed or partial receipt. Never claim something the receipt cannot prove.\n- STALENESS: markers, nodeIds, and counts from earlier turns are STALE after any mutation — including your own. Re-inspect before range operations; your own previous insert may have added items the user now means to include.\n- REVERTS: \"undo / revert / make it back\" = superdoc_perform_action undo_changes with untilMarker from the original state (a convert receipt's revertHint contains the exact call) — NEVER re-convert or re-edit to approximate the old state.\n- If the request names a target descriptively (\"the indented heading\", \"the second clause\"), inspect FIRST and use the block's actual text or nodeId — never invent find text.\n- Numbered legal clauses (\"2.3.\") usually live on numbered HEADINGS, not lists: if counts.lists is 0 but blocks carry numbering markers, target those blocks by nodeId. \"Add item 2.4\" = insert_paragraphs (one text) after the \"2.3.\" block; the tool attaches numbering and matches formatting automatically (check receipt.contextualFormatting).\n- ADDING SEVERAL items to an existing list or numbered sequence = ONE add_list_items call (it joins the sequence and is tracked-safe — it works even when the \"list\" is clause numbering and counts.lists is 0). NEVER a chain of insert_paragraphs calls: multi-paragraph inserts do not auto-join numbering, and the items will land as plain paragraphs.\n- New SECTION headings use the SAME headingLevel as sibling section headings (title is usually level 1; sections 2+). Never default to level 1.\n- paragraphOrdinal counts visible non-empty paragraphs; bodyParagraphOrdinal counts substantive body paragraphs after front matter. Prefer paragraphOrdinal for \"first/second paragraph\".\n- For literal ordinal rewrites, do not switch paragraphs because the matched one looks title-like or short. If a rewrite is a no-op, keep the target and change the rewrite.\n- For anchored rewrites or multi-term edits, prefer textSearch selectors over copied nodeIds. For clause text inside tables, use a tableCell selector with replace_text.\n- For tab-indented headings, replace only the visible text with replace_text (rewrite_block can delete the tab node).\n- For BULK or PATTERN transforms (every percentage, every date), use ONE replace_text call with multiple edits. For bulk FORMATTING (\"bold all the dates\"): read the matching texts first, then ONE format_text call with targetTexts.\n- For preview-only requests (\"show what it would look like\", \"don't save\"), make NO mutating call — read the document with superdoc_inspect and describe the change in your answer. If they want to SEE it in the document before it is final, make the edit with changeMode:\"tracked\" so it lands as a reviewable suggestion they can accept or reject — but only on an action that records tracked changes; for an action marked Direct edit, describe the change instead of making it.\n- Pure count questions: superdoc_inspect countsOnly:true, then stop. Use includeDomains to keep snapshots small.\n- Do not include doc or sessionId in tool args. Never rely on benchmark routing, eval metadata, or fixture names.\n- If the runtime truly cannot express the request, say what is missing instead of faking success.\n",
 };
 
 exports.EMBEDDED_PROMPTS = EMBEDDED_PROMPTS;