@superdoc/sdk 2.20.1-next.9 → 2.21.0-next.2

package/dist/action-primitives/tools/list-transform.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var contract = require('../../generated/contract.cjs');
 var engine = require('../engine.cjs');
 var resolve = require('../resolve.cjs');
 
@@ -41,9 +42,19 @@ function parseListKind(raw, fallback) {
     }
     return LIST_KINDS.find((kind) => kind === raw);
 }
+function isListCreatePreset(value) {
+    const schema = contract.CONTRACT.operations['doc.lists.create'].params.find((parameter) => parameter.name === 'preset')?.schema;
+    if (schema == null || typeof schema !== 'object')
+        return false;
+    if ('enum' in schema && Array.isArray(schema.enum))
+        return schema.enum.includes(value);
+    return ('oneOf' in schema &&
+        Array.isArray(schema.oneOf) &&
+        schema.oneOf.some((variant) => variant != null && typeof variant === 'object' && 'const' in variant && variant.const === value));
+}
 function parsePreset(raw, kind) {
     if (typeof raw === 'string' && raw.length > 0) {
-        return raw;
+        return isListCreatePreset(raw) ? raw : undefined;
     }
     return kind === 'bullet' ? 'disc' : 'decimal';
 }
@@ -253,6 +264,15 @@ function resolveStep(context) {
         });
     }
     const preset = parsePreset(context.args.preset, listKind);
+    if (preset == null) {
+        return engine.workflowStepFailure({
+            status: 'failed',
+            phase: 'resolve',
+            code: 'WORKFLOW_LIST_PRESET_INVALID',
+            message: 'preset must be a supported list preset.',
+            details: { received: context.args.preset },
+        });
+    }
     const headingText = parseOptionalText(context.args.headingText);
     const headingLevel = parseHeadingLevel(context.args.headingLevel);
     if (Number.isNaN(headingLevel)) {

package/dist/action-primitives/tools/list-transform.d.ts

@@ -12,6 +12,7 @@ type SuperdocListTransformPosition = (typeof POSITIONS)[number];
 type SuperdocListKind = (typeof LIST_KINDS)[number];
 type ListInsertParams = NonNullable<Parameters<BoundDocApi['lists']['insert']>[0]>;
 type ListInsertTarget = NonNullable<ListInsertParams['target']>;
+type ListCreatePreset = NonNullable<NonNullable<Parameters<BoundDocApi['lists']['create']>[0]>['preset']>;
 type TrackedChangeRef = NonNullable<DocListsInsertResult['trackedChangeRefs']>[number];
 type SuperdocListTransformResolved = {
     action: SuperdocListTransformAction;
@@ -28,7 +29,7 @@ type SuperdocListTransformResolved = {
     targetSource: 'provided' | 'auto_single_list' | 'apparent_textual_list' | 'document_end';
     deterministicTarget: boolean;
     listKind: SuperdocListKind;
-    preset: string;
+    preset: ListCreatePreset;
     headingText?: string;
     headingLevel?: number;
     listId?: string;
@@ -47,7 +48,7 @@ type SuperdocListTransformPlan = {
     targetSource: SuperdocListTransformResolved['targetSource'];
     deterministicTarget: boolean;
     listKind: SuperdocListKind;
-    preset: string;
+    preset: ListCreatePreset;
     headingText?: string;
     headingLevel?: number;
     listId?: string;
@@ -59,7 +60,7 @@ type SuperdocListTransformExecution = {
     targetSource: SuperdocListTransformResolved['targetSource'];
     deterministicTarget: boolean;
     listKind: SuperdocListKind;
-    preset: string;
+    preset: ListCreatePreset;
     headingText?: string;
     headingLevel?: number;
     headingNodeId?: string;

package/dist/action-primitives/tools/list-transform.js

@@ -1,3 +1,4 @@
+import { CONTRACT } from '../../generated/contract.js';
 import { runWorkflowEngine, workflowStepFailure, workflowStepSuccess, } from '../engine.js';
 import { resolveWorkflowTargetFromUnknown, } from '../resolve.js';
 const LIST_TRANSFORM_ACTIONS = ['insert_many', 'append_new_list'];
@@ -38,9 +39,19 @@ function parseListKind(raw, fallback) {
     }
     return LIST_KINDS.find((kind) => kind === raw);
 }
+function isListCreatePreset(value) {
+    const schema = CONTRACT.operations['doc.lists.create'].params.find((parameter) => parameter.name === 'preset')?.schema;
+    if (schema == null || typeof schema !== 'object')
+        return false;
+    if ('enum' in schema && Array.isArray(schema.enum))
+        return schema.enum.includes(value);
+    return ('oneOf' in schema &&
+        Array.isArray(schema.oneOf) &&
+        schema.oneOf.some((variant) => variant != null && typeof variant === 'object' && 'const' in variant && variant.const === value));
+}
 function parsePreset(raw, kind) {
     if (typeof raw === 'string' && raw.length > 0) {
-        return raw;
+        return isListCreatePreset(raw) ? raw : undefined;
     }
     return kind === 'bullet' ? 'disc' : 'decimal';
 }
@@ -250,6 +261,15 @@ function resolveStep(context) {
         });
     }
     const preset = parsePreset(context.args.preset, listKind);
+    if (preset == null) {
+        return workflowStepFailure({
+            status: 'failed',
+            phase: 'resolve',
+            code: 'WORKFLOW_LIST_PRESET_INVALID',
+            message: 'preset must be a supported list preset.',
+            details: { received: context.args.preset },
+        });
+    }
     const headingText = parseOptionalText(context.args.headingText);
     const headingLevel = parseHeadingLevel(context.args.headingLevel);
     if (Number.isNaN(headingLevel)) {

package/dist/agent/action-descriptors.json

@@ -0,0 +1,308 @@
+{
+    "insert_paragraphs": {
+        "hint": "texts[] (or text for a single paragraph), placement?, headingLevel? (first item as heading 1-6), changeMode? — THE way to ADD a new paragraph/clause; never replace_text/rewrite_block an existing paragraph to append content. Each texts entry is a plain string OR a STYLED object {runs:[{text,marks}], marks?} (marks: bold/italic/underline/strikethrough/fontFamily/fontSize(points)/color(hex)/highlight). MATCH THE SECTION'S PATTERN: when siblings share intra-paragraph formatting (e.g. lettered clauses with a bold '(m)' lead-in), inspect a narrow block window with includeBlockRuns:true, read the sibling runs, and reproduce the pattern with runs on the new text IN THIS CALL — e.g. runs:[{text:'(n)',marks:{bold:true}},{text:' rest of the clause…'}]. Do not add plain and format_text afterward",
+        "group": "Text/structure actions",
+        "groupOrder": 0,
+        "args": ["text", "texts", "headingLevel", "placement", "changeMode", "evidence"],
+        "operations": ["create.paragraph"]
+    },
+    "insert_heading": {
+        "hint": "text, level, placement?, changeMode?",
+        "group": "Text/structure actions",
+        "groupOrder": 1,
+        "args": ["text", "level", "placement", "changeMode"],
+        "operations": ["create.heading"]
+    },
+    "replace_text": {
+        "hint": "edits[{find,replace}], optional selector to scope replacements to one inspected block, caseSensitive?, changeMode? — for EDITING existing wording only; the replaced span is rewritten as PLAIN text (intra-span bold/italic is dropped), so keep find/replace spans MINIMAL (the words that change, not the whole paragraph) and NEVER use it to append a new sentence/clause/paragraph (use insert_paragraphs)",
+        "group": "Text/structure actions",
+        "groupOrder": 2,
+        "args": ["edits", "selector", "caseSensitive", "changeMode"],
+        "operations": ["replace"]
+    },
+    "delete_text": {
+        "hint": "finds[], optional selector to scope deletions to ONE inspected block (required to delete stray whitespace — an unscoped whitespace find matches document-wide), caseSensitive?, changeMode? — deletes TEXT ONLY, leaving the block (and a list item's bullet/number) in place. To remove a whole list item, paragraph or heading use delete_blocks",
+        "group": "Text/structure actions",
+        "groupOrder": 3,
+        "args": ["finds", "selector", "caseSensitive", "changeMode"],
+        "operations": ["delete"]
+    },
+    "delete_blocks": {
+        "hint": "selectors[] (each resolving to ONE inspected block: list item, paragraph or heading), changeMode? — THE way to DELETE a whole LIST ITEM, paragraph or heading, bullet/number included. Use for \"remove the first item under Article II\" / \"delete that clause\". delete_text only strikes the text and leaves an empty numbered item behind. Deletes several blocks in ONE call; use delete_table for a whole table and delete_text to clear a table cell (a cell must keep a paragraph)",
+        "group": "Text/structure actions",
+        "groupOrder": 4,
+        "args": ["selectors", "selector", "changeMode"],
+        "operations": ["blocks.delete"]
+    },
+    "append_list": {
+        "hint": "items[], kind?: ordered|bullet, headingText?, headingLevel?, placement? {at:\"after\"|\"before\",selector} builds the list at that block instead of document end",
+        "group": "Text/structure actions",
+        "groupOrder": 5,
+        "args": ["items", "kind", "headingText", "headingLevel", "placement", "changeMode"],
+        "operations": ["lists.create", "lists.insert"],
+        "trackedOverrideReason": "The V2 list adapter guarantees native tracked creation and insertion."
+    },
+    "create_table": {
+        "hint": "rows, columns, cellTexts? (2D: rows of cells; each cell is a plain string OR a STYLED object {runs:[{text,marks}], marks?} to format the cell — marks: bold/italic/underline/strikethrough/fontFamily/fontSize(points)/color(hex)/highlight), placement?, changeMode? — style cells HERE, do not format_text afterward; changeMode:\"tracked\" makes the table insertion itself a tracked change",
+        "group": "Text/structure actions",
+        "groupOrder": 6,
+        "args": ["rows", "columns", "cellTexts", "placement", "changeMode", "evidence"],
+        "operations": ["create.table"]
+    },
+    "comment_paragraphs": {
+        "hint": "commentText, scope?: all|body, excludeBlockQuotes?",
+        "group": "Comment actions",
+        "groupOrder": 0,
+        "args": ["commentText", "scope", "excludeBlockQuotes"],
+        "operations": ["comments.create"]
+    },
+    "add_comments": {
+        "hint": "commentText, selector (one block) OR selectors[] to comment MANY blocks in ONE call (same text) — use selectors[] for \"comment every heading/section/clause\"; NEVER emit multiple add_comments calls, batch the targets into selectors[]",
+        "group": "Comment actions",
+        "groupOrder": 1,
+        "args": ["commentText", "selector", "selectors"],
+        "operations": ["comments.create"]
+    },
+    "resolve_comments": {
+        "hint": "anchorText? (resolve only comments anchored on text containing this; omit to resolve ALL open comments), reopen? (true = reopen resolved comments instead) — THE way to resolve (or reopen) comments. Use for \"resolve the comment(s)\" / \"mark comments resolved\".",
+        "group": "Comment actions",
+        "groupOrder": 2,
+        "args": ["anchorText", "reopen"],
+        "operations": ["comments.patch"]
+    },
+    "reply_to_comment": {
+        "hint": "commentText (the reply body), anchorText (text the target comment is anchored on / mentions) OR commentId — THE way to REPLY to an existing comment thread. Use for \"reply to the comment about X\" / \"respond to Reviewer's comment\". Adds a threaded reply, not a new top-level comment.",
+        "group": "Comment actions",
+        "groupOrder": 3,
+        "args": ["commentText", "anchorText", "commentId"],
+        "operations": ["comments.create"]
+    },
+    "rewrite_block": {
+        "hint": "selector, text, changeMode? — REPLACES the whole block text. Omitted tab controls are deleted: for a tab-aligned paragraph, use replace_text with a minimal find span to change a name/placeholder instead. For appending a NEW paragraph/clause use insert_paragraphs",
+        "group": "Text/structure actions",
+        "groupOrder": 7,
+        "args": ["text", "selector", "changeMode", "evidence"],
+        "operations": ["replace"]
+    },
+    "accept_tracked_changes": {
+        "hint": "id? (string or string[]) OR author?/changeType?: insert|delete|replacement|format — a string[] decides that exact set atomically; e.g. changeType:\"format\" accepts ONLY formatting revisions (bold/italic/color), leaving text edits pending",
+        "group": "Tracked-change review",
+        "groupOrder": 0,
+        "args": ["id", "author", "changeType"],
+        "operations": ["trackChanges.decide"]
+    },
+    "reject_tracked_changes": {
+        "hint": "id? (string or string[]) OR author?/changeType?: insert|delete|replacement|format — a string[] decides that exact set atomically",
+        "group": "Tracked-change review",
+        "groupOrder": 1,
+        "args": ["id", "author", "changeType"],
+        "operations": ["trackChanges.decide"]
+    },
+    "normalize_body_font_size": {
+        "hint": "fontSize, changeMode?",
+        "group": "Formatting actions",
+        "groupOrder": 4,
+        "args": ["fontSize", "changeMode"],
+        "operations": ["format.apply"]
+    },
+    "set_font_family": {
+        "hint": "fontFamily (e.g. \"Arial\"), selector? (one block) OR targetText/targetTexts[] (occurrences) — omit both to set the WHOLE body font, caseSensitive?, changeMode? — THE way to change the typeface. Use for \"change the font to X\" / \"set the heading font to Y\".",
+        "group": "Formatting actions",
+        "groupOrder": 5,
+        "args": ["fontFamily", "selector", "targetText", "targetTexts", "caseSensitive", "changeMode"],
+        "operations": ["format.apply"]
+    },
+    "apply_letter_spacing": {
+        "hint": "selector, letterSpacing, changeMode?",
+        "group": "Formatting actions",
+        "groupOrder": 6,
+        "args": ["selector", "letterSpacing", "changeMode"],
+        "operations": ["format.apply"]
+    },
+    "fill_placeholders": {
+        "hint": "values[] and/or fields[{label?,value}], changeMode?",
+        "group": "Text/structure actions",
+        "groupOrder": 8,
+        "args": ["values", "fields", "changeMode"],
+        "operations": ["replace"]
+    },
+    "move_range": {
+        "hint": "fromText (text in the FIRST block of the range to move), 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 in the block to land after/before). changeMode:\"tracked\" records both the copies and source deletion for review. Moves plain paragraph/heading text only; a range containing a table, list, or image is refused with nothing changed. THE way to MOVE a contiguous block range or a visual \"section\" identified BY TEXT (works on styled-paragraph sections like PREAMBLE / SCHEDULE A that are NOT Word heading nodes). afterText on a heading-like block lands the range after that block's WHOLE section.",
+        "group": "Text/structure actions",
+        "groupOrder": 9,
+        "args": ["fromText", "toText", "afterText", "beforeText", "changeMode"],
+        "operations": ["blocks.move"]
+    },
+    "insert_toc": {
+        "hint": "title?, placement?, changeMode?",
+        "group": "Media / TOC",
+        "groupOrder": 0,
+        "args": ["title", "placement", "changeMode"],
+        "operations": ["create.tableOfContents"],
+        "trackedOverrideReason": "The V2 TOC adapter guarantees native tracked creation."
+    },
+    "insert_table_row": {
+        "hint": "tableOrdinal?, rowIndex?, position?: before|after|above|below, cellTexts? (one per column; each a plain string OR a STYLED {runs, marks?} cell to reproduce the table's cell formatting), changeMode? — to match existing cell styling, inspect the table with includeTableCellRuns:true first, then style each new cell HERE. PLACEMENT: when the user does not say WHERE the row goes, append it after the LAST existing row (rowIndex = last row's index, position: below); never pick a middle position on your own",
+        "group": "Table edits",
+        "groupOrder": 3,
+        "args": ["tableOrdinal", "rowIndex", "position", "cellTexts", "changeMode"],
+        "operations": ["tables.insertRow"]
+    },
+    "insert_table_column": {
+        "hint": "tableOrdinal?, columnIndex?, position?: left|right, headerText? OR cellTexts? (one per row; each a plain string OR a STYLED {runs, marks?} cell), changeMode? — style the new column cells HERE, not with format_text",
+        "group": "Table edits",
+        "groupOrder": 4,
+        "args": ["tableOrdinal", "columnIndex", "position", "headerText", "cellTexts", "changeMode"],
+        "operations": ["tables.insertColumn"]
+    },
+    "delete_table_row": {
+        "hint": "tableOrdinal?, rowIndex, changeMode?",
+        "group": "Table edits",
+        "groupOrder": 5,
+        "args": ["tableOrdinal", "rowIndex", "changeMode"],
+        "operations": ["tables.deleteRow"]
+    },
+    "delete_table_column": {
+        "hint": "tableOrdinal?, columnIndex, changeMode?",
+        "group": "Table edits",
+        "groupOrder": 6,
+        "args": ["tableOrdinal", "columnIndex", "changeMode"],
+        "operations": ["tables.deleteColumn"]
+    },
+    "split_table": {
+        "hint": "tableOrdinal?, rowIndex, separatorText?, changeMode?",
+        "group": "Table edits",
+        "groupOrder": 7,
+        "args": ["tableOrdinal", "rowIndex", "separatorText", "changeMode"],
+        "operations": ["tables.split"],
+        "trackedOverrideReason": "The V2 table adapter guarantees native tracked table splitting."
+    },
+    "convert_list": {
+        "hint": "kind: ordered|bullet, listOrdinal? 1-based or anchorText? text inside an item of the target list, OR fromMarker+toMarker rendered clause numbers like \"2.1.\"/\"2.3.\" to convert a numbered-clause range, OR fromText+toText exact text inside the first/last of consecutive plain paragraphs to convert them into a list IN PLACE, changeMode? — converts lists, clause ranges, or plain paragraphs to a list without touching text; never recreate-and-delete to make existing paragraphs a list",
+        "group": "List/numbering actions",
+        "groupOrder": 0,
+        "args": ["kind", "fromMarker", "toMarker", "fromText", "toText", "listOrdinal", "anchorText", "changeMode"],
+        "operations": ["lists.apply"]
+    },
+    "split_list": {
+        "hint": "anchorText (text inside the item that should START the second list), restartNumbering? (default true — the new list restarts at 1; false keeps continuous numbering) — THE way to SPLIT one list into two at an item (\"split the list starting at item 7 into a new list with reset numbering\"). Nested sub-items stay with their parent. changeMode? records the change for review.",
+        "group": "List/numbering actions",
+        "groupOrder": 3,
+        "args": ["anchorText", "restartNumbering", "changeMode"],
+        "operations": ["lists.separate"],
+        "trackedOverrideReason": "The V2 list adapter guarantees native tracked list separation."
+    },
+    "undo_changes": {
+        "hint": "untilMarker? rendered marker to restore e.g. \"2.1.\", steps? 1-25 — deterministic revert that steps document history back until the marker reappears",
+        "group": "History",
+        "groupOrder": 0,
+        "args": ["untilMarker", "steps"],
+        "operations": ["history.undo"]
+    },
+    "redo_changes": {
+        "hint": "steps? 1-25 (default 1) — the inverse of undo_changes: steps history FORWARD to re-apply edits a prior undo removed. THE recovery when an undo overshot. Only works right after an undo, before any new edit.",
+        "group": "History",
+        "groupOrder": 1,
+        "args": ["steps"],
+        "operations": ["history.redo"]
+    },
+    "attach_numbering": {
+        "hint": "anchorText|nodeId, likeMarker e.g. \"10.\", changeMode? — make an existing block a numbered clause at the same scheme/level as the sibling rendering likeMarker; changeMode:\"tracked\" records the former unnumbered state as a w:pPrChange",
+        "group": "List/numbering actions",
+        "groupOrder": 1,
+        "args": ["likeMarker", "nodeId", "anchorText", "changeMode"],
+        "operations": ["lists.attach"]
+    },
+    "add_list_items": {
+        "hint": "THE way to ADD items into an EXISTING list (reusing its numbering + markers) — NOT append_list (which starts a brand-new list). Locate the list with anchorText (text inside an existing item) or listOrdinal (from inspect). Each item in entries/items is EITHER a plain string / {text, level?}, OR a STYLED object {runs, marks?, level?}. STYLING IN THIS ONE CALL — if any part of the new item needs inline formatting (bold/italic/underline/color/font/size on some or all of it), you MUST express it with `runs` and/or `marks` HERE. Do NOT add the item plain and then call format_text/format_paragraph on it afterward — that is the wrong tool for a just-added item and risks matching stray text elsewhere. `runs` = ordered segments [{text, marks?}] whose texts concatenate to the item text; put the pattern on each segment (marks: bold/italic/underline/strikethrough/fontFamily/fontSize(points)/color(hex e.g. #1a1a1a)/highlight). `marks` on the item = a whole-item default (e.g. Arial 16pt) applied under the per-run marks. Example — pattern 'first word bold, rest italic': runs:[{text:\"Term:\",marks:{bold:true}},{text:\" the rest\",marks:{italic:true}}]. MATCHING THE LIST'S FORMATTING IS THE DEFAULT EXPECTATION, and it means per-run inline formatting — NOT numbering (numbering is always reused automatically). superdoc_inspect returns each list item's `runs` (its inline segments with marks) by default: READ the sibling items' runs, infer the rule (which segment is bold/italic/etc., the font/size), and REPRODUCE that run structure with `runs` on the new item's OWN words IN THIS CALL. If the siblings are uniformly styled, a plain add already inherits their font/size/colour, so no marks are needed; but if any sibling has intra-item formatting, you MUST supply `runs`. level is RELATIVE to the anchor (0 = same level, positive nests deeper, NEGATIVE promotes toward the top e.g. anchor \"12(e)\" + level:-1 → new top-level item 13); only anchorText can set explicit level (listOrdinal appends at the trailing level). PLACEMENT: anchorText inserts the new item RIGHT AFTER the item containing that text — this is how you position within a list. One Word list often spans SEVERAL visual groups (the same numbering id continues past e.g. \"Label: value\" entries into unrelated paragraphs), so when the new item belongs to a visible GROUP of similar siblings, anchor the LAST item OF THAT GROUP — tail-append (listOrdinal, or anchoring the list's final item) can land it in the wrong region. Only when there is no such group and the user gives no placement signal append at the END of the list. The receipt's note/addedItems echo the rendered marker AND the immediate neighbor items — verify placement from the receipt; do NOT re-inspect wide block windows after a successful add. receipt.formattingMatched reports what was applied.",
+        "group": "List/numbering actions",
+        "groupOrder": 2,
+        "args": ["anchorText", "listOrdinal", "entries", "items", "changeMode"],
+        "operations": ["lists.insert"]
+    },
+    "format_text": {
+        "hint": "bold?/italic?/underline?/strike? booleans, highlight? color name, color?, fontSize?, applied to EVERY occurrence of targetText (or targetTexts[] for several phrases in one call, or a selector'd block), caseSensitive?, changeMode? — THE way to bold/italicize/underline/highlight text, tracked-safe",
+        "group": "Formatting actions",
+        "groupOrder": 0,
+        "args": [
+            "targetText",
+            "targetTexts",
+            "selector",
+            "caseSensitive",
+            "bold",
+            "italic",
+            "underline",
+            "strike",
+            "highlight",
+            "color",
+            "fontSize",
+            "changeMode"
+        ],
+        "operations": ["format.apply"]
+    },
+    "apply_style": {
+        "hint": "selector (block to restyle), then ONE of: styleId (e.g. \"Heading2\"), headingLevel (1-6), or likeText (text inside another block whose style AND effective look to copy) — THE way to restyle an EXISTING block (\"make Summary match the Parties heading\"). Never delete-and-recreate a block to change its style",
+        "group": "Formatting actions",
+        "groupOrder": 1,
+        "args": ["selector", "styleId", "headingLevel", "likeText", "changeMode"],
+        "operations": ["styles.paragraph.setStyle"]
+    },
+    "format_paragraph": {
+        "hint": "selector (block to align), alignment: left|center|right|justify, changeMode? — THE way to set paragraph alignment; changeMode:\"tracked\" records the former alignment as a w:pPrChange so accept/reject toggles it (never apply alignment untracked when tracking is on)",
+        "group": "Formatting actions",
+        "groupOrder": 2,
+        "args": ["selector", "alignment", "changeMode", "evidence"],
+        "operations": ["format.paragraph.setAlignment"]
+    },
+    "move_text": {
+        "hint": "text (exact clause/phrase to relocate), afterText? (relocate to immediately after this text), changeMode? — THE way to MOVE a text span. Direct by default (physically relocates; REQUIRES afterText). changeMode:\"tracked\" records it as a redline (tracked delete of the source + tracked insert at the destination; accept keeps the move, reject restores the order) and may omit afterText (lands right after the struck source).",
+        "group": "Tracked move",
+        "groupOrder": 0,
+        "args": ["text", "afterText", "changeMode"],
+        "operations": ["blocks.move"]
+    },
+    "style_table": {
+        "hint": "tableOrdinal? (1-based, default 1), accentColor? (header fill hex, default dark navy) — THE way to make a table look professional: filled accent header row with white bold text, bold first-column labels, banded rows, clean borders. Use after create_table or on any existing table.",
+        "group": "Table edits",
+        "groupOrder": 0,
+        "args": ["tableOrdinal", "accentColor", "changeMode"],
+        "operations": ["tables.applyPreset"],
+        "trackedOverrideReason": "The V2 table adapter guarantees native tracked preset application."
+    },
+    "move_table": {
+        "hint": "tableOrdinal? (1-based, default 1), placement {at:\"document_end\"|\"document_start\"|\"after\"|\"before\", selector?} — THE way to MOVE a whole table (with all its content) to a new position IN ONE call. Use for \"move the table to the end / under section X\". NEVER delete-and-recreate a table to relocate it, and never chain inserts/undos to fake a move.",
+        "group": "Table edits",
+        "groupOrder": 1,
+        "args": ["tableOrdinal", "placement", "changeMode"],
+        "operations": ["tables.move"],
+        "trackedOverrideReason": "The V2 table adapter guarantees native tracked table moves."
+    },
+    "delete_table": {
+        "hint": "tableOrdinal? (1-based, default 1), changeMode? — THE way to DELETE an entire table in one call. Use for \"remove/delete the table\". Do NOT delete rows one by one or hijack another table.",
+        "group": "Table edits",
+        "groupOrder": 2,
+        "args": ["tableOrdinal", "changeMode"],
+        "operations": ["tables.delete"]
+    },
+    "set_paragraph_spacing": {
+        "hint": "selector (block/blocks to space), lineSpacing? (multiplier e.g. 1.5 or 2), spaceBefore? / spaceAfter? (points) — THE way to set line spacing or space before/after paragraphs. Use this for \"add spacing\" / \"1.5 line spacing\" / \"more room between paragraphs\" — NEVER insert blank paragraphs for spacing. changeMode? records the change for review.",
+        "group": "Formatting actions",
+        "groupOrder": 3,
+        "args": ["selector", "lineSpacing", "spaceBefore", "spaceAfter", "changeMode"],
+        "operations": ["format.paragraph.setSpacing"]
+    },
+    "insert_page_break": {
+        "hint": "selector (block that should start on a new page) — THE way to \"start X on a new page\" / add a page break before a block (sets pageBreakBefore). Use instead of inserting empty paragraphs to push content down. changeMode? records the change for review.",
+        "group": "Layout",
+        "groupOrder": 0,
+        "args": ["selector", "changeMode"],
+        "operations": ["format.paragraph.setFlowOptions"]
+    },
+    "add_hyperlink": {
+        "hint": "text (exact text to turn into a link), url, tooltip? — THE way to make existing text a clickable hyperlink to a URL. changeMode? records the change for review.",
+        "group": "Links",
+        "groupOrder": 0,
+        "args": ["text", "url", "tooltip", "changeMode"],
+        "operations": ["hyperlinks.insert"]
+    }
+}