@superdoc-dev/mcp 0.3.0-next.30 → 0.3.0-next.32

package/dist/index.js

@@ -51837,7 +51837,7 @@ var init_remark_gfm_BhnWr3yf_es = __esm(() => {
   emptyOptions2 = {};
 });
 
-// ../../packages/superdoc/dist/chunks/SuperConverter-DklB-kc9.es.js
+// ../../packages/superdoc/dist/chunks/SuperConverter-25gYGkyK.es.js
 function getExtensionConfigField(extension$1, field, context = { name: "" }) {
   const fieldValue = extension$1.config[field];
   if (typeof fieldValue === "function")
@@ -58147,7 +58147,7 @@ function executeCreateContentControl(adapter, input, options) {
       value: input.lockMode
     });
   if (input.at !== undefined && input.target !== undefined)
-    throw new DocumentApiValidationError("INVALID_INPUT", `create.contentControl: "at" and "target" are mutually exclusive — provide one or neither.`, { field: "at" });
+    throw new DocumentApiValidationError("INVALID_INPUT", `create.contentControl: "at" and "target" are mutually exclusive: provide one or neither.`, { field: "at" });
   if (input.target !== undefined)
     validateCCTarget(input.target, "create.contentControl");
   if (input.at !== undefined && !isSelectionTarget(input.at))
@@ -104302,7 +104302,7 @@ var isRegExp = (value) => {
       state.kern = kernNode.attributes["w:val"];
   }
 }, SuperConverter;
-var init_SuperConverter_DklB_kc9_es = __esm(() => {
+var init_SuperConverter_25gYGkyK_es = __esm(() => {
   init_rolldown_runtime_Bg48TavK_es();
   init_jszip_C49i9kUs_es();
   init_xml_js_CqGKpaft_es();
@@ -107350,7 +107350,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
     },
     find: {
       memberPath: "find",
-      description: "Search the document for text or node matches using SDM/1 selectors. Returns discovery-grade results — for mutation targeting, use query.match instead.",
+      description: "Search the document for text or node matches using SDM/1 selectors. Returns discovery-grade results: for mutation targeting, use query.match instead.",
       expectedResult: "Returns an SDFindResult envelope ({ total, limit, offset, items }). Each item is an SDNodeResult ({ node, address }).",
       requiresDocumentContext: true,
       metadata: readOperation({
@@ -107446,7 +107446,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
     },
     extract: {
       memberPath: "extract",
-      description: "Extract all document content with stable IDs for RAG pipelines. Returns blocks with full text, comments, and tracked changes — each with an ID compatible with scrollToElement().",
+      description: "Extract all document content with stable IDs for RAG pipelines. Returns blocks with full text, comments, and tracked changes: each with an ID compatible with scrollToElement().",
       expectedResult: "Returns an ExtractResult with blocks (nodeId, type, text, headingLevel), comments (entityId, text, anchoredText, blockId, status, author), tracked changes (entityId, type, excerpt, author, date), and revision.",
       requiresDocumentContext: true,
       metadata: readOperation(),
@@ -108446,7 +108446,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
     },
     "lists.create": {
       memberPath: "lists.create",
-      description: 'Create a new list from one or more paragraphs. Supports optional preset or style for new sequences. When sequence.mode is "continuePrevious", preset and style are not allowed — the new items inherit formatting from the previous sequence.',
+      description: 'Create a new list from one or more paragraphs. Supports optional preset or style for new sequences. When sequence.mode is "continuePrevious", preset and style are not allowed: the new items inherit formatting from the previous sequence.',
       expectedResult: "Returns a ListsCreateResult with the new listId and the first item address.",
       requiresDocumentContext: true,
       metadata: mutationOperation({
@@ -108599,7 +108599,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
     },
     "lists.merge": {
       memberPath: "lists.merge",
-      description: 'Compound: merge two adjacent list sequences into one. Reassigns numId on the absorbed sequence (no strict abstractNumId check — absorbed items adopt the absorbing definition) and deletes empty paragraphs between the two sequences. Use this instead of lists.join for the user-facing "merge these lists" intent.',
+      description: 'Compound: merge two adjacent list sequences into one. Reassigns numId on the absorbed sequence (no strict abstractNumId check: absorbed items adopt the absorbing definition) and deletes empty paragraphs between the two sequences. Use this instead of lists.join for the user-facing "merge these lists" intent.',
       expectedResult: "Returns a ListsMergeResult with the merged listId, absorbedCount, and removedEmptyBlocks count.",
       requiresDocumentContext: true,
       metadata: mutationOperation({
@@ -109074,7 +109074,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
     },
     "lists.setLevelNumberStyle": {
       memberPath: "lists.setLevelNumberStyle",
-      description: 'Set the numbering style (e.g. decimal, lowerLetter, upperRoman) for a specific list level. Rejects "bullet" — use setLevelBullet instead. Sequence-local: clones shared definitions.',
+      description: 'Set the numbering style (e.g. decimal, lowerLetter, upperRoman) for a specific list level. Rejects "bullet": use setLevelBullet instead. Sequence-local: clones shared definitions.',
       expectedResult: "Returns a ListsMutateItemResult receipt; reports NO_OP if the value already matches.",
       requiresDocumentContext: true,
       metadata: mutationOperation({
@@ -109145,7 +109145,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
     },
     "lists.setLevelLayout": {
       memberPath: "lists.setLevelLayout",
-      description: "Set the layout properties (alignment, indentation, trailing character, tab stop) for a specific list level. Accepts partial updates — omitted fields are left unchanged. Sequence-local: clones shared definitions.",
+      description: "Set the layout properties (alignment, indentation, trailing character, tab stop) for a specific list level. Accepts partial updates: omitted fields are left unchanged. Sequence-local: clones shared definitions.",
       expectedResult: "Returns a ListsMutateItemResult receipt; reports NO_OP if all values already match.",
       requiresDocumentContext: true,
       metadata: mutationOperation({
@@ -115410,7 +115410,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
       items: objectSchema({
         nodeId: {
           type: "string",
-          description: "Stable block ID — pass to scrollToElement() for navigation."
+          description: "Stable block ID: pass to scrollToElement() for navigation."
         },
         type: {
           type: "string",
@@ -115503,7 +115503,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
       items: objectSchema({
         entityId: {
           type: "string",
-          description: "Comment entity ID — pass to scrollToElement() for navigation."
+          description: "Comment entity ID: pass to scrollToElement() for navigation."
         },
         text: {
           type: "string",
@@ -115987,7 +115987,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
     },
     text: {
       type: "string",
-      description: "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item — do NOT use newlines to put multiple items in one paragraph."
+      description: "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item: do NOT use newlines to put multiple items in one paragraph."
     }
   }), createParagraphResultSchemaFor("create.paragraph"), createParagraphFailureSchemaFor("create.paragraph"), objectSchema({
     in: storyLocatorSchema,
@@ -141903,7 +141903,7 @@ var init_SuperConverter_DklB_kc9_es = __esm(() => {
   };
 });
 
-// ../../packages/superdoc/dist/chunks/create-headless-toolbar-lTVVsGdE.es.js
+// ../../packages/superdoc/dist/chunks/create-headless-toolbar-B93DeWrb.es.js
 function parseSizeUnit(val = "0") {
   const length = val.toString() || "0";
   const value = Number.parseFloat(length);
@@ -144539,8 +144539,8 @@ var CSS_DIMENSION_REGEX, DOM_SIZE_UNITS, Extension = class Extension2 {
     }
   };
 };
-var init_create_headless_toolbar_lTVVsGdE_es = __esm(() => {
-  init_SuperConverter_DklB_kc9_es();
+var init_create_headless_toolbar_B93DeWrb_es = __esm(() => {
+  init_SuperConverter_25gYGkyK_es();
   init_constants_DrU4EASo_es();
   init_dist_B8HfvhaK_es();
   CSS_DIMENSION_REGEX = /[\d-.]+(\w+)$/;
@@ -198749,7 +198749,7 @@ var init_remark_gfm_eZN6yzWQ_es = __esm(() => {
   init_remark_gfm_BhnWr3yf_es();
 });
 
-// ../../packages/superdoc/dist/chunks/src-97w5ApZ8.es.js
+// ../../packages/superdoc/dist/chunks/src-B4HBe1_K.es.js
 function deleteProps(obj, propOrProps) {
   const props = typeof propOrProps === "string" ? [propOrProps] : propOrProps;
   const removeNested = (target, pathParts, index2 = 0) => {
@@ -289981,12 +289981,12 @@ menclose::after {
     return;
   console.log(...args$1);
 }, HEADER_FOOTER_INIT_BUDGET_MS = 200, MAX_ZOOM_WARNING_THRESHOLD = 10, MAX_SELECTION_RECTS_PER_USER = 100, SEMANTIC_RESIZE_DEBOUNCE_MS = 120, MIN_SEMANTIC_CONTENT_WIDTH_PX = 1, GLOBAL_PERFORMANCE, PresentationEditor, ICONS, TEXTS, tableActionsOptions;
-var init_src_97w5ApZ8_es = __esm(() => {
+var init_src_B4HBe1_K_es = __esm(() => {
   init_rolldown_runtime_Bg48TavK_es();
-  init_SuperConverter_DklB_kc9_es();
+  init_SuperConverter_25gYGkyK_es();
   init_jszip_C49i9kUs_es();
   init_uuid_qzgm05fK_es();
-  init_create_headless_toolbar_lTVVsGdE_es();
+  init_create_headless_toolbar_B93DeWrb_es();
   init_constants_DrU4EASo_es();
   init_dist_B8HfvhaK_es();
   init_unified_Dsuw2be5_es();
@@ -327379,11 +327379,11 @@ function print() { __p += __j.call(arguments, '') }
   ];
 });
 
-// ../../packages/superdoc/dist/chunks/create-super-doc-ui-BX9GeQ4R.es.js
+// ../../packages/superdoc/dist/chunks/create-super-doc-ui-HQsnQdt0.es.js
 var ALL_TOOLBAR_COMMAND_IDS, EMPTY_ACTIVE_IDS;
-var init_create_super_doc_ui_BX9GeQ4R_es = __esm(() => {
-  init_SuperConverter_DklB_kc9_es();
-  init_create_headless_toolbar_lTVVsGdE_es();
+var init_create_super_doc_ui_HQsnQdt0_es = __esm(() => {
+  init_SuperConverter_25gYGkyK_es();
+  init_create_headless_toolbar_B93DeWrb_es();
   ALL_TOOLBAR_COMMAND_IDS = Object.keys(createToolbarRegistry());
   EMPTY_ACTIVE_IDS = Object.freeze([]);
 });
@@ -327401,16 +327401,16 @@ var init_zipper_BxRAi0_5_es = __esm(() => {
 
 // ../../packages/superdoc/dist/super-editor.es.js
 var init_super_editor_es = __esm(() => {
-  init_src_97w5ApZ8_es();
-  init_SuperConverter_DklB_kc9_es();
+  init_src_B4HBe1_K_es();
+  init_SuperConverter_25gYGkyK_es();
   init_jszip_C49i9kUs_es();
   init_xml_js_CqGKpaft_es();
-  init_create_headless_toolbar_lTVVsGdE_es();
+  init_create_headless_toolbar_B93DeWrb_es();
   init_constants_DrU4EASo_es();
   init_dist_B8HfvhaK_es();
   init_unified_Dsuw2be5_es();
   init_DocxZipper_CUX64E5K_es();
-  init_create_super_doc_ui_BX9GeQ4R_es();
+  init_create_super_doc_ui_HQsnQdt0_es();
   init_ui_CGB3qmy3_es();
   init_eventemitter3_BJrNoN9D_es();
   init_errors_C_DoKMoN_es();
@@ -328926,7 +328926,7 @@ var init_operation_definitions = __esm(() => {
     },
     edit: {
       toolName: "superdoc_edit",
-      description: "The primary tool for inserting content into documents. " + 'ALWAYS use action "insert" with type "markdown" to create headings, paragraphs, or any block content — this is faster and creates proper document structure in one call. Do NOT use superdoc_create for headings or paragraphs. ' + "The markdown parser creates headings from # markers (# = Heading1, ## = Heading2), bold from **text**, italic from *text*, and numbered/bullet lists. " + 'Position markdown inserts with "target" (a BlockNodeAddress like {kind:"block", nodeType, nodeId}) and "placement" (before, after, insideStart, insideEnd). Without a target, content appends at the end of the document. ' + "IMPORTANT: After a markdown insert, analyze the document context (what kind of document, how titles and body text are styled) and follow up with ONE superdoc_mutations call to format inserted blocks so they look like they belong. " + 'Each format.apply step accepts "inline" (fontFamily, fontSize, bold, underline, color), "alignment", and "scope" in the same step. ' + 'Use scope: "block" so formatting covers the entire paragraph. ' + "Copy the exact property values from the existing get_content blocks (fontFamily, fontSize, color, alignment, bold, underline). Do NOT invent values — use what the blocks show. " + 'Also supports replace, delete, and undo/redo. For replace and delete, pass a "ref" from superdoc_search or superdoc_get_content blocks. ' + "A search ref covers only the matched substring; a block ref covers the entire block text, so use block refs when rewriting or shortening whole paragraphs. " + 'For multi-step redlines or whole-clause rewrites, prefer superdoc_mutations with where:{by:"block", nodeType, nodeId} from superdoc_get_content action "blocks" includeText:true rather than relying on text selectors. ' + "Refs expire after any mutation; always re-search before the next edit. " + "For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. " + 'Supports "dryRun" to preview changes and "changeMode: tracked" to record edits as tracked changes (not supported for markdown/html inserts). ' + 'Do NOT build "target" objects manually when a ref is available; prefer "ref" for simpler, more reliable targeting.',
+      description: "The primary tool for inserting content into documents. " + 'ALWAYS use action "insert" with type "markdown" to create headings, paragraphs, or any block content: this is faster and creates proper document structure in one call. Do NOT use superdoc_create for headings or paragraphs. ' + "The markdown parser creates headings from # markers (# = Heading1, ## = Heading2), bold from **text**, italic from *text*, and numbered/bullet lists. " + 'Position markdown inserts with "target" (a BlockNodeAddress like {kind:"block", nodeType, nodeId}) and "placement" (before, after, insideStart, insideEnd). Without a target, content appends at the end of the document. ' + "IMPORTANT: After a markdown insert, analyze the document context (what kind of document, how titles and body text are styled) and follow up with ONE superdoc_mutations call to format inserted blocks so they look like they belong. " + 'Each format.apply step accepts "inline" (fontFamily, fontSize, bold, underline, color), "alignment", and "scope" in the same step. ' + 'Use scope: "block" so formatting covers the entire paragraph. ' + "Copy the exact property values from the existing get_content blocks (fontFamily, fontSize, color, alignment, bold, underline). Do NOT invent values: use what the blocks show. " + 'Also supports replace, delete, and undo/redo. For replace and delete, pass a "ref" from superdoc_search or superdoc_get_content blocks. ' + "A search ref covers only the matched substring; a block ref covers the entire block text, so use block refs when rewriting or shortening whole paragraphs. " + 'For multi-step redlines or whole-clause rewrites, prefer superdoc_mutations with where:{by:"block", nodeType, nodeId} from superdoc_get_content action "blocks" includeText:true rather than relying on text selectors. ' + "Refs expire after any mutation; always re-search before the next edit. " + "For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. " + 'Supports "dryRun" to preview changes and "changeMode: tracked" to record edits as tracked changes (not supported for markdown/html inserts). ' + 'Do NOT build "target" objects manually when a ref is available; prefer "ref" for simpler, more reliable targeting.',
       inputExamples: [
         {
           action: "insert",
@@ -328955,7 +328955,7 @@ More content with **bold** and *italic*.`
     },
     create: {
       toolName: "superdoc_create",
-      description: 'IMPORTANT: For headings and paragraphs, use superdoc_edit with type "markdown" instead — it is faster, creates proper styles, and handles positioning via target + placement. ' + "Only use superdoc_create for tables or when markdown cannot express the content. " + "Creates a single paragraph, heading, or table. Returns nodeId and ref for the created block. " + "After creating, the returned ref is valid for ONE immediate superdoc_format call. For subsequent operations, re-fetch blocks with superdoc_get_content to get fresh refs (refs expire after any mutation). " + 'When the user asks for a "heading", use action "heading" with a level (default 1). Use action "paragraph" for regular body text. ' + 'Position with "at": {kind:"documentEnd"} (default), {kind:"documentStart"}, or {kind:"after"/"before", target:{kind:"block", nodeType, nodeId}} for relative placement. ' + 'When creating multiple items in sequence, use the previous response nodeId as the next "at" target to maintain correct ordering. ' + 'Do NOT use newlines in "text" to create multiple paragraphs; call this tool separately for each one.',
+      description: 'IMPORTANT: For headings and paragraphs, use superdoc_edit with type "markdown" instead: it is faster, creates proper styles, and handles positioning via target + placement. ' + "Only use superdoc_create for tables or when markdown cannot express the content. " + "Creates a single paragraph, heading, or table. Returns nodeId and ref for the created block. " + "After creating, the returned ref is valid for ONE immediate superdoc_format call. For subsequent operations, re-fetch blocks with superdoc_get_content to get fresh refs (refs expire after any mutation). " + 'When the user asks for a "heading", use action "heading" with a level (default 1). Use action "paragraph" for regular body text. ' + 'Position with "at": {kind:"documentEnd"} (default), {kind:"documentStart"}, or {kind:"after"/"before", target:{kind:"block", nodeType, nodeId}} for relative placement. ' + 'When creating multiple items in sequence, use the previous response nodeId as the next "at" target to maintain correct ordering. ' + 'Do NOT use newlines in "text" to create multiple paragraphs; call this tool separately for each one.',
       inputExamples: [
         { action: "paragraph", text: "New paragraph content.", at: { kind: "documentEnd" } },
         {
@@ -329002,26 +329002,26 @@ More content with **bold** and *italic*.`
     table: { toolName: "superdoc_table", description: "Table structure and cell operations" },
     list: {
       toolName: "superdoc_list",
-      description: "Create and manipulate bullet and numbered lists. " + 'Most actions require a list-item target: {kind:"block", nodeType:"listItem", nodeId:"<id>"}. ' + 'Exceptions: "create" and "attach" operate on paragraph targets (they turn paragraphs into list items). ' + `Find nodeIds via superdoc_get_content({action:"blocks"}) — pick listItem blocks for most actions, paragraph blocks for create/attach.
+      description: "Create and manipulate bullet and numbered lists. " + 'Most actions require a list-item target: {kind:"block", nodeType:"listItem", nodeId:"<id>"}. ' + 'Exceptions: "create" and "attach" operate on paragraph targets (they turn paragraphs into list items). ' + `Find nodeIds via superdoc_get_content({action:"blocks"}): pick listItem blocks for most actions, paragraph blocks for create/attach.
 ` + `
 ` + `CREATE & CONVERT:
-` + '• "create" — make a NEW list from paragraphs. Two modes: ' + 'mode:"empty" with at:{kind:"block", nodeType:"paragraph", nodeId} converts a single paragraph; ' + 'mode:"fromParagraphs" with target:{from:{...paragraph block address}, to:{...paragraph block address}} converts a range — ALL paragraphs between from and to become items, so make sure no other content sits between them. ' + 'Pass a preset ("disc"|"circle"|"square"|"dash" for bullets; "decimal"|"decimalParenthesis"|"lowerLetter"|"upperLetter"|"lowerRoman"|"upperRoman" for ordered) or a custom style. ' + `Use "create" to start a fresh list — NOT to extend an existing one (use "attach" for that).
-` + `• "attach" — add paragraphs to an EXISTING list, inheriting its numbering definition. Pass target:{paragraph block address} (or {from, to} range of paragraphs) + attachTo:{kind:"block", nodeType:"listItem", nodeId:"<any item in destination list>"} + optional level:0..8. Use this to extend a list or as the second half of a merge workflow (see "join" below).
-` + `• "set_type" — convert an existing list between ordered and bullet. Pass target:{listItem} + kind:"ordered" or "bullet". Adjacent compatible sequences are merged automatically to preserve continuous numbering.
-` + `• "detach" — convert a list item back to a plain paragraph. Pass target:{listItem}.
+` + '• "create": make a NEW list from paragraphs. Two modes: ' + 'mode:"empty" with at:{kind:"block", nodeType:"paragraph", nodeId} converts a single paragraph; ' + 'mode:"fromParagraphs" with target:{from:{...paragraph block address}, to:{...paragraph block address}} converts a range: ALL paragraphs between from and to become items, so make sure no other content sits between them. ' + 'Pass a preset ("disc"|"circle"|"square"|"dash" for bullets; "decimal"|"decimalParenthesis"|"lowerLetter"|"upperLetter"|"lowerRoman"|"upperRoman" for ordered) or a custom style. ' + `Use "create" to start a fresh list: NOT to extend an existing one (use "attach" for that).
+` + `• "attach": add paragraphs to an EXISTING list, inheriting its numbering definition. Pass target:{paragraph block address} (or {from, to} range of paragraphs) + attachTo:{kind:"block", nodeType:"listItem", nodeId:"<any item in destination list>"} + optional level:0..8. Use this to extend a list or as the second half of a merge workflow (see "join" below).
+` + `• "set_type": convert an existing list between ordered and bullet. Pass target:{listItem} + kind:"ordered" or "bullet". Adjacent compatible sequences are merged automatically to preserve continuous numbering.
+` + `• "detach": convert a list item back to a plain paragraph. Pass target:{listItem}.
 ` + `
 ` + `ITEMS & NESTING:
-` + `• "insert" — add a new list item adjacent to an existing item in the same list. Pass target:{listItem} + position:"before"|"after" + optional text. Use this (NOT superdoc_create) to add items to an existing list.
-` + `• "indent" / "outdent" — bump the target item's nesting level by one (0-8 range). Pass target:{listItem}.
-` + `• "set_level" — jump the target item to an explicit level. Pass target:{listItem} + level:0..8.
+` + `• "insert": add a new list item adjacent to an existing item in the same list. Pass target:{listItem} + position:"before"|"after" + optional text. Use this (NOT superdoc_create) to add items to an existing list.
+` + `• "indent" / "outdent": bump the target item's nesting level by one (0-8 range). Pass target:{listItem}.
+` + `• "set_level": jump the target item to an explicit level. Pass target:{listItem} + level:0..8.
 ` + `
 ` + `NUMBERING (ordered lists):
-` + `• "set_value" — restart numbering at the target. Pass target:{listItem} + value:<number> (e.g. value:1 to start over) or value:null to clear a previous override. Mid-sequence targets are atomically split off into their own sequence.
-` + `• "continue_previous" — make the target's sequence continue numbering from the nearest compatible previous sequence (same abstract definition). Pass target:{listItem of the sequence you want to renumber}. Fails with NO_COMPATIBLE_PREVIOUS or INCOMPATIBLE_DEFINITIONS if no matching prior sequence exists.
+` + `• "set_value": restart numbering at the target. Pass target:{listItem} + value:<number> (e.g. value:1 to start over) or value:null to clear a previous override. Mid-sequence targets are atomically split off into their own sequence.
+` + `• "continue_previous": make the target's sequence continue numbering from the nearest compatible previous sequence (same abstract definition). Pass target:{listItem of the sequence you want to renumber}. Fails with NO_COMPATIBLE_PREVIOUS or INCOMPATIBLE_DEFINITIONS if no matching prior sequence exists.
 ` + `
 ` + `SEQUENCE SHAPE (merge / split):
-` + `• "merge" — merge the target's sequence with an adjacent one into one continuous list. Pass target:{listItem} + direction:"withPrevious" or "withNext". Absorbed items adopt the absorbing sequence's numbering definition, and empty paragraphs between the two sequences are removed so numbering flows continuously.
-` + `• "split" — split the target's sequence at the target item into two independent lists. The target and everything after become a new sequence that restarts numbering at 1. Pass target:{listItem}; add restartNumbering:false to keep the count continuing instead of restarting.`,
+` + `• "merge": merge the target's sequence with an adjacent one into one continuous list. Pass target:{listItem} + direction:"withPrevious" or "withNext". Absorbed items adopt the absorbing sequence's numbering definition, and empty paragraphs between the two sequences are removed so numbering flows continuously.
+` + `• "split": split the target's sequence at the target item into two independent lists. The target and everything after become a new sequence that restarts numbering at 1. Pass target:{listItem}; add restartNumbering:false to keep the count continuing instead of restarting.`,
       inputExamples: [
         {
           action: "create",
@@ -329242,7 +329242,7 @@ More content with **bold** and *italic*.`
     },
     find: {
       memberPath: "find",
-      description: "Search the document for text or node matches using SDM/1 selectors. Returns discovery-grade results — for mutation targeting, use query.match instead.",
+      description: "Search the document for text or node matches using SDM/1 selectors. Returns discovery-grade results: for mutation targeting, use query.match instead.",
       expectedResult: "Returns an SDFindResult envelope ({ total, limit, offset, items }). Each item is an SDNodeResult ({ node, address }).",
       requiresDocumentContext: true,
       metadata: readOperation2({
@@ -329339,7 +329339,7 @@ More content with **bold** and *italic*.`
     },
     extract: {
       memberPath: "extract",
-      description: "Extract all document content with stable IDs for RAG pipelines. Returns blocks with full text, comments, and tracked changes — each with an ID compatible with scrollToElement().",
+      description: "Extract all document content with stable IDs for RAG pipelines. Returns blocks with full text, comments, and tracked changes: each with an ID compatible with scrollToElement().",
       expectedResult: "Returns an ExtractResult with blocks (nodeId, type, text, headingLevel), comments (entityId, text, anchoredText, blockId, status, author), tracked changes (entityId, type, excerpt, author, date), and revision.",
       requiresDocumentContext: true,
       metadata: readOperation2(),
@@ -330252,7 +330252,7 @@ More content with **bold** and *italic*.`
     },
     "lists.create": {
       memberPath: "lists.create",
-      description: 'Create a new list from one or more paragraphs. Supports optional preset or style for new sequences. When sequence.mode is "continuePrevious", preset and style are not allowed — the new items inherit formatting from the previous sequence.',
+      description: 'Create a new list from one or more paragraphs. Supports optional preset or style for new sequences. When sequence.mode is "continuePrevious", preset and style are not allowed: the new items inherit formatting from the previous sequence.',
       expectedResult: "Returns a ListsCreateResult with the new listId and the first item address.",
       requiresDocumentContext: true,
       metadata: mutationOperation2({
@@ -330384,7 +330384,7 @@ More content with **bold** and *italic*.`
     },
     "lists.merge": {
       memberPath: "lists.merge",
-      description: 'Compound: merge two adjacent list sequences into one. Reassigns numId on the absorbed sequence (no strict abstractNumId check — absorbed items adopt the absorbing definition) and deletes empty paragraphs between the two sequences. Use this instead of lists.join for the user-facing "merge these lists" intent.',
+      description: 'Compound: merge two adjacent list sequences into one. Reassigns numId on the absorbed sequence (no strict abstractNumId check: absorbed items adopt the absorbing definition) and deletes empty paragraphs between the two sequences. Use this instead of lists.join for the user-facing "merge these lists" intent.',
       expectedResult: "Returns a ListsMergeResult with the merged listId, absorbedCount, and removedEmptyBlocks count.",
       requiresDocumentContext: true,
       metadata: mutationOperation2({
@@ -330741,7 +330741,7 @@ More content with **bold** and *italic*.`
     },
     "lists.setLevelNumberStyle": {
       memberPath: "lists.setLevelNumberStyle",
-      description: 'Set the numbering style (e.g. decimal, lowerLetter, upperRoman) for a specific list level. Rejects "bullet" — use setLevelBullet instead. Sequence-local: clones shared definitions.',
+      description: 'Set the numbering style (e.g. decimal, lowerLetter, upperRoman) for a specific list level. Rejects "bullet": use setLevelBullet instead. Sequence-local: clones shared definitions.',
       expectedResult: "Returns a ListsMutateItemResult receipt; reports NO_OP if the value already matches.",
       requiresDocumentContext: true,
       metadata: mutationOperation2({
@@ -330786,7 +330786,7 @@ More content with **bold** and *italic*.`
     },
     "lists.setLevelLayout": {
       memberPath: "lists.setLevelLayout",
-      description: "Set the layout properties (alignment, indentation, trailing character, tab stop) for a specific list level. Accepts partial updates — omitted fields are left unchanged. Sequence-local: clones shared definitions.",
+      description: "Set the layout properties (alignment, indentation, trailing character, tab stop) for a specific list level. Accepts partial updates: omitted fields are left unchanged. Sequence-local: clones shared definitions.",
       expectedResult: "Returns a ListsMutateItemResult receipt; reports NO_OP if all values already match.",
       requiresDocumentContext: true,
       metadata: mutationOperation2({
@@ -337383,7 +337383,7 @@ var init_schemas4 = __esm(() => {
         blocks: {
           type: "array",
           items: objectSchema2({
-            nodeId: { type: "string", description: "Stable block ID — pass to scrollToElement() for navigation." },
+            nodeId: { type: "string", description: "Stable block ID: pass to scrollToElement() for navigation." },
             type: {
               type: "string",
               description: "Block type: paragraph, heading, listItem, image, tableOfContents."
@@ -337440,7 +337440,7 @@ var init_schemas4 = __esm(() => {
           items: objectSchema2({
             entityId: {
               type: "string",
-              description: "Comment entity ID — pass to scrollToElement() for navigation."
+              description: "Comment entity ID: pass to scrollToElement() for navigation."
             },
             text: { type: "string", description: "Comment body text." },
             anchoredText: { type: "string", description: "The document text the comment is anchored to." },
@@ -337951,7 +337951,7 @@ var init_schemas4 = __esm(() => {
         },
         text: {
           type: "string",
-          description: "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item — do NOT use newlines to put multiple items in one paragraph."
+          description: "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item: do NOT use newlines to put multiple items in one paragraph."
         }
       }),
       output: createParagraphResultSchemaFor2("create.paragraph"),
@@ -338243,7 +338243,7 @@ var init_schemas4 = __esm(() => {
         properties: {
           mode: {
             enum: ["empty", "fromParagraphs"],
-            description: "Required. 'fromParagraphs' converts existing paragraphs into list items — each paragraph becomes one item, so create one paragraph per item first. 'empty' creates a new empty list at 'at'."
+            description: "Required. 'fromParagraphs' converts existing paragraphs into list items: each paragraph becomes one item, so create one paragraph per item first. 'empty' creates a new empty list at 'at'."
           },
           at: {
             ...ref3("BlockAddress"),
@@ -345619,7 +345619,7 @@ function executeCreateContentControl2(adapter, input2, options) {
     throw new DocumentApiValidationError3("INVALID_INPUT", `create.contentControl lockMode must be one of: ${[...VALID_LOCK_MODES2].join(", ")}.`, { field: "lockMode", value: input2.lockMode });
   }
   if (input2.at !== undefined && input2.target !== undefined) {
-    throw new DocumentApiValidationError3("INVALID_INPUT", `create.contentControl: "at" and "target" are mutually exclusive — provide one or neither.`, { field: "at" });
+    throw new DocumentApiValidationError3("INVALID_INPUT", `create.contentControl: "at" and "target" are mutually exclusive: provide one or neither.`, { field: "at" });
   }
   if (input2.target !== undefined) {
     validateCCTarget2(input2.target, "create.contentControl");
@@ -458306,7 +458306,7 @@ var init_catalog = __esm(() => {
       },
       {
         toolName: "superdoc_edit",
-        description: 'The primary tool for inserting content into documents. ALWAYS use action "insert" with type "markdown" to create headings, paragraphs, or any block content — this is faster and creates proper document structure in one call. Do NOT use superdoc_create for headings or paragraphs. The markdown parser creates headings from # markers (# = Heading1, ## = Heading2), bold from **text**, italic from *text*, and numbered/bullet lists. Position markdown inserts with "target" (a BlockNodeAddress like {kind:"block", nodeType, nodeId}) and "placement" (before, after, insideStart, insideEnd). Without a target, content appends at the end of the document. IMPORTANT: After a markdown insert, analyze the document context (what kind of document, how titles and body text are styled) and follow up with ONE superdoc_mutations call to format inserted blocks so they look like they belong. Each format.apply step accepts "inline" (fontFamily, fontSize, bold, underline, color), "alignment", and "scope" in the same step. Use scope: "block" so formatting covers the entire paragraph. Copy the exact property values from the existing get_content blocks (fontFamily, fontSize, color, alignment, bold, underline). Do NOT invent values — use what the blocks show. Also supports replace, delete, and undo/redo. For replace and delete, pass a "ref" from superdoc_search or superdoc_get_content blocks. A search ref covers only the matched substring; a block ref covers the entire block text, so use block refs when rewriting or shortening whole paragraphs. For multi-step redlines or whole-clause rewrites, prefer superdoc_mutations with where:{by:"block", nodeType, nodeId} from superdoc_get_content action "blocks" includeText:true rather than relying on text selectors. Refs expire after any mutation; always re-search before the next edit. For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. Supports "dryRun" to preview changes and "changeMode: tracked" to record edits as tracked changes (not supported for markdown/html inserts). Do NOT build "target" objects manually when a ref is available; prefer "ref" for simpler, more reliable targeting.',
+        description: 'The primary tool for inserting content into documents. ALWAYS use action "insert" with type "markdown" to create headings, paragraphs, or any block content: this is faster and creates proper document structure in one call. Do NOT use superdoc_create for headings or paragraphs. The markdown parser creates headings from # markers (# = Heading1, ## = Heading2), bold from **text**, italic from *text*, and numbered/bullet lists. Position markdown inserts with "target" (a BlockNodeAddress like {kind:"block", nodeType, nodeId}) and "placement" (before, after, insideStart, insideEnd). Without a target, content appends at the end of the document. IMPORTANT: After a markdown insert, analyze the document context (what kind of document, how titles and body text are styled) and follow up with ONE superdoc_mutations call to format inserted blocks so they look like they belong. Each format.apply step accepts "inline" (fontFamily, fontSize, bold, underline, color), "alignment", and "scope" in the same step. Use scope: "block" so formatting covers the entire paragraph. Copy the exact property values from the existing get_content blocks (fontFamily, fontSize, color, alignment, bold, underline). Do NOT invent values: use what the blocks show. Also supports replace, delete, and undo/redo. For replace and delete, pass a "ref" from superdoc_search or superdoc_get_content blocks. A search ref covers only the matched substring; a block ref covers the entire block text, so use block refs when rewriting or shortening whole paragraphs. For multi-step redlines or whole-clause rewrites, prefer superdoc_mutations with where:{by:"block", nodeType, nodeId} from superdoc_get_content action "blocks" includeText:true rather than relying on text selectors. Refs expire after any mutation; always re-search before the next edit. For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. Supports "dryRun" to preview changes and "changeMode: tracked" to record edits as tracked changes (not supported for markdown/html inserts). Do NOT build "target" objects manually when a ref is available; prefer "ref" for simpler, more reliable targeting.',
         inputSchema: {
           type: "object",
           properties: {
@@ -459289,7 +459289,7 @@ var init_catalog = __esm(() => {
       },
       {
         toolName: "superdoc_create",
-        description: 'IMPORTANT: For headings and paragraphs, use superdoc_edit with type "markdown" instead — it is faster, creates proper styles, and handles positioning via target + placement. Only use superdoc_create for tables or when markdown cannot express the content. Creates a single paragraph, heading, or table. Returns nodeId and ref for the created block. After creating, the returned ref is valid for ONE immediate superdoc_format call. For subsequent operations, re-fetch blocks with superdoc_get_content to get fresh refs (refs expire after any mutation). When the user asks for a "heading", use action "heading" with a level (default 1). Use action "paragraph" for regular body text. Position with "at": {kind:"documentEnd"} (default), {kind:"documentStart"}, or {kind:"after"/"before", target:{kind:"block", nodeType, nodeId}} for relative placement. When creating multiple items in sequence, use the previous response nodeId as the next "at" target to maintain correct ordering. Do NOT use newlines in "text" to create multiple paragraphs; call this tool separately for each one.',
+        description: 'IMPORTANT: For headings and paragraphs, use superdoc_edit with type "markdown" instead: it is faster, creates proper styles, and handles positioning via target + placement. Only use superdoc_create for tables or when markdown cannot express the content. Creates a single paragraph, heading, or table. Returns nodeId and ref for the created block. After creating, the returned ref is valid for ONE immediate superdoc_format call. For subsequent operations, re-fetch blocks with superdoc_get_content to get fresh refs (refs expire after any mutation). When the user asks for a "heading", use action "heading" with a level (default 1). Use action "paragraph" for regular body text. Position with "at": {kind:"documentEnd"} (default), {kind:"documentStart"}, or {kind:"after"/"before", target:{kind:"block", nodeType, nodeId}} for relative placement. When creating multiple items in sequence, use the previous response nodeId as the next "at" target to maintain correct ordering. Do NOT use newlines in "text" to create multiple paragraphs; call this tool separately for each one.',
         inputSchema: {
           type: "object",
           properties: {
@@ -459435,7 +459435,7 @@ var init_catalog = __esm(() => {
             },
             text: {
               type: "string",
-              description: "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item — do NOT use newlines to put multiple items in one paragraph."
+              description: "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item: do NOT use newlines to put multiple items in one paragraph."
             },
             input: {
               type: "object",
@@ -459484,26 +459484,26 @@ var init_catalog = __esm(() => {
       },
       {
         toolName: "superdoc_list",
-        description: `Create and manipulate bullet and numbered lists. Most actions require a list-item target: {kind:"block", nodeType:"listItem", nodeId:"<id>"}. Exceptions: "create" and "attach" operate on paragraph targets (they turn paragraphs into list items). Find nodeIds via superdoc_get_content({action:"blocks"}) — pick listItem blocks for most actions, paragraph blocks for create/attach.
+        description: `Create and manipulate bullet and numbered lists. Most actions require a list-item target: {kind:"block", nodeType:"listItem", nodeId:"<id>"}. Exceptions: "create" and "attach" operate on paragraph targets (they turn paragraphs into list items). Find nodeIds via superdoc_get_content({action:"blocks"}): pick listItem blocks for most actions, paragraph blocks for create/attach.
 
 CREATE & CONVERT:
-• "create" — make a NEW list from paragraphs. Two modes: mode:"empty" with at:{kind:"block", nodeType:"paragraph", nodeId} converts a single paragraph; mode:"fromParagraphs" with target:{from:{...paragraph block address}, to:{...paragraph block address}} converts a range — ALL paragraphs between from and to become items, so make sure no other content sits between them. Pass a preset ("disc"|"circle"|"square"|"dash" for bullets; "decimal"|"decimalParenthesis"|"lowerLetter"|"upperLetter"|"lowerRoman"|"upperRoman" for ordered) or a custom style. Use "create" to start a fresh list — NOT to extend an existing one (use "attach" for that).
-• "attach" — add paragraphs to an EXISTING list, inheriting its numbering definition. Pass target:{paragraph block address} (or {from, to} range of paragraphs) + attachTo:{kind:"block", nodeType:"listItem", nodeId:"<any item in destination list>"} + optional level:0..8. Use this to extend a list or as the second half of a merge workflow (see "join" below).
-• "set_type" — convert an existing list between ordered and bullet. Pass target:{listItem} + kind:"ordered" or "bullet". Adjacent compatible sequences are merged automatically to preserve continuous numbering.
-• "detach" — convert a list item back to a plain paragraph. Pass target:{listItem}.
+• "create": make a NEW list from paragraphs. Two modes: mode:"empty" with at:{kind:"block", nodeType:"paragraph", nodeId} converts a single paragraph; mode:"fromParagraphs" with target:{from:{...paragraph block address}, to:{...paragraph block address}} converts a range: ALL paragraphs between from and to become items, so make sure no other content sits between them. Pass a preset ("disc"|"circle"|"square"|"dash" for bullets; "decimal"|"decimalParenthesis"|"lowerLetter"|"upperLetter"|"lowerRoman"|"upperRoman" for ordered) or a custom style. Use "create" to start a fresh list: NOT to extend an existing one (use "attach" for that).
+• "attach": add paragraphs to an EXISTING list, inheriting its numbering definition. Pass target:{paragraph block address} (or {from, to} range of paragraphs) + attachTo:{kind:"block", nodeType:"listItem", nodeId:"<any item in destination list>"} + optional level:0..8. Use this to extend a list or as the second half of a merge workflow (see "join" below).
+• "set_type": convert an existing list between ordered and bullet. Pass target:{listItem} + kind:"ordered" or "bullet". Adjacent compatible sequences are merged automatically to preserve continuous numbering.
+• "detach": convert a list item back to a plain paragraph. Pass target:{listItem}.
 
 ITEMS & NESTING:
-• "insert" — add a new list item adjacent to an existing item in the same list. Pass target:{listItem} + position:"before"|"after" + optional text. Use this (NOT superdoc_create) to add items to an existing list.
-• "indent" / "outdent" — bump the target item's nesting level by one (0-8 range). Pass target:{listItem}.
-• "set_level" — jump the target item to an explicit level. Pass target:{listItem} + level:0..8.
+• "insert": add a new list item adjacent to an existing item in the same list. Pass target:{listItem} + position:"before"|"after" + optional text. Use this (NOT superdoc_create) to add items to an existing list.
+• "indent" / "outdent": bump the target item's nesting level by one (0-8 range). Pass target:{listItem}.
+• "set_level": jump the target item to an explicit level. Pass target:{listItem} + level:0..8.
 
 NUMBERING (ordered lists):
-• "set_value" — restart numbering at the target. Pass target:{listItem} + value:<number> (e.g. value:1 to start over) or value:null to clear a previous override. Mid-sequence targets are atomically split off into their own sequence.
-• "continue_previous" — make the target's sequence continue numbering from the nearest compatible previous sequence (same abstract definition). Pass target:{listItem of the sequence you want to renumber}. Fails with NO_COMPATIBLE_PREVIOUS or INCOMPATIBLE_DEFINITIONS if no matching prior sequence exists.
+• "set_value": restart numbering at the target. Pass target:{listItem} + value:<number> (e.g. value:1 to start over) or value:null to clear a previous override. Mid-sequence targets are atomically split off into their own sequence.
+• "continue_previous": make the target's sequence continue numbering from the nearest compatible previous sequence (same abstract definition). Pass target:{listItem of the sequence you want to renumber}. Fails with NO_COMPATIBLE_PREVIOUS or INCOMPATIBLE_DEFINITIONS if no matching prior sequence exists.
 
 SEQUENCE SHAPE (merge / split):
-• "merge" — merge the target's sequence with an adjacent one into one continuous list. Pass target:{listItem} + direction:"withPrevious" or "withNext". Absorbed items adopt the absorbing sequence's numbering definition, and empty paragraphs between the two sequences are removed so numbering flows continuously.
-• "split" — split the target's sequence at the target item into two independent lists. The target and everything after become a new sequence that restarts numbering at 1. Pass target:{listItem}; add restartNumbering:false to keep the count continuing instead of restarting.`,
+• "merge": merge the target's sequence with an adjacent one into one continuous list. Pass target:{listItem} + direction:"withPrevious" or "withNext". Absorbed items adopt the absorbing sequence's numbering definition, and empty paragraphs between the two sequences are removed so numbering flows continuously.
+• "split": split the target's sequence at the target item into two independent lists. The target and everything after become a new sequence that restarts numbering at 1. Pass target:{listItem}; add restartNumbering:false to keep the count continuing instead of restarting.`,
         inputSchema: {
           type: "object",
           properties: {
@@ -459585,7 +459585,7 @@ SEQUENCE SHAPE (merge / split):
             },
             mode: {
               type: "string",
-              description: "Required. 'fromParagraphs' converts existing paragraphs into list items — each paragraph becomes one item, so create one paragraph per item first. 'empty' creates a new empty list at 'at'. Required for action 'create'.",
+              description: "Required. 'fromParagraphs' converts existing paragraphs into list items: each paragraph becomes one item, so create one paragraph per item first. 'empty' creates a new empty list at 'at'. Required for action 'create'.",
               enum: [
                 "empty",
                 "fromParagraphs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/mcp",
-  "version": "0.3.0-next.30",
+  "version": "0.3.0-next.32",
   "type": "module",
   "engines": {
     "node": ">=20"