@superdoc-dev/sdk 1.3.0-next.43 → 1.3.0-next.44

package/tools/catalog.json

@@ -5,7 +5,7 @@
   "tools": [
     {
       "toolName": "superdoc_get_content",
-      "description": "Read document content. Use action \"info\" for structure and styles, \"blocks\" for all block IDs and types, \"text\" or \"markdown\" for content. Call info or blocks before editing.",
+      "description": "Read document content in various formats. Call this first in any workflow to understand document structure before making edits. Action \"blocks\" returns structured block data with nodeId, nodeType, textPreview, formatting properties (fontFamily, fontSize, color, bold, underline, alignment), and ref handles for immediate use with superdoc_edit or superdoc_format. Action \"text\" and \"markdown\" return the full document as plain text or Markdown. Action \"html\" returns HTML. Action \"info\" returns document metadata: word count, paragraph count, page count, outline, available styles, and capability flags. The \"blocks\" action supports pagination via \"offset\" and \"limit\", and filtering via \"nodeTypes\". Other actions ignore these parameters. This tool never modifies the document. Do NOT call superdoc_edit or superdoc_format without first reading blocks to get valid refs and formatting reference values.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -81,7 +81,7 @@
     },
     {
       "toolName": "superdoc_edit",
-      "description": "Insert, replace, delete text, or undo/redo",
+      "description": "Refs expire after any mutation; always re-search before the next edit. Modify document text: insert new content, replace existing text, delete a range, or undo/redo. Use this for single text modifications. For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. 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. Insert supports plain text (default), markdown, or html via the \"type\" parameter. Use \"placement\" (before, after, insideStart, insideEnd) to control position relative to the target. Supports \"dryRun\" to preview changes and \"changeMode: tracked\" to record edits as tracked changes. Do NOT build \"target\" objects manually when a ref is available; prefer \"ref\" for simpler, more reliable targeting.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -303,7 +303,7 @@
                 ]
               }
             ],
-            "description": "Target address object. Use 'ref' instead if you have a search handle. Format: {kind:'text', blockId, range:{start,end}} or {kind:'block', nodeType, nodeId}."
+            "description": "Target address. For inline/set_style: prefer 'ref' from superdoc_search, or use {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. For paragraph actions (set_alignment, set_indentation, set_spacing, set_direction, set_flow_options): use {kind:'block', nodeType:'paragraph'|'heading'|'listItem', nodeId:'<nodeId from blocks list>'}."
           },
           "value": {
             "type": "string",
@@ -320,7 +320,7 @@
           },
           "ref": {
             "type": "string",
-            "description": "Handle ref string returned by a prior search/query result."
+            "description": "Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object."
           },
           "content": {
             "oneOf": [
@@ -360,22 +360,6 @@
             },
             "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions."
           },
-          "blockId": {
-            "type": "string",
-            "description": "Block ID of the target paragraph."
-          },
-          "start": {
-            "type": "number",
-            "description": "Start offset within the block (character index)."
-          },
-          "end": {
-            "type": "number",
-            "description": "End offset within the block (character index)."
-          },
-          "offset": {
-            "type": "number",
-            "description": "Character offset for insertion (alias for --start/--end with same value). Only for action 'insert'. Omit for other actions."
-          },
           "text": {
             "type": "string",
             "description": "Replacement text content. Only for action 'replace'. Omit for other actions."
@@ -462,7 +446,7 @@
     },
     {
       "toolName": "superdoc_format",
-      "description": "Change text and paragraph formatting. Use action \"inline\" with a search ref for bold/italic/etc. Use action \"set_style\" with a styleId from superdoc_get_content info to apply a named paragraph style.",
+      "description": "Change text and paragraph formatting. Use this after superdoc_create to style new content, or with a search ref to restyle existing text. Action \"inline\" applies character formatting (bold, italic, underline, color, fontSize, fontFamily, highlight, strike, vertAlign) to a text range via \"ref\". Action \"set_style\" applies a named paragraph style by styleId (get available styles from superdoc_get_content info). Actions \"set_alignment\", \"set_indentation\", \"set_spacing\", \"set_direction\", and \"set_flow_options\" change paragraph-level properties and require a block target: {kind:\"block\", nodeType:\"paragraph\", nodeId:\"<nodeId>\"}, NOT a ref. Use \"set_flow_options\" with pageBreakBefore:true to start a paragraph on a new page. Supports \"dryRun\" and \"changeMode: tracked\" for inline formatting. Paragraph-level actions do NOT support tracked changes. Do NOT use a search ref for paragraph-level actions; they require a block target with nodeId. Do NOT use {kind:\"block\", start:{kind:\"nodeEdge\",...}} or selection-like structures for paragraph actions. ONLY {kind:\"block\", nodeType, nodeId} is accepted. Do NOT issue multiple superdoc_format calls in parallel; each call invalidates refs for subsequent calls. Format one block at a time. Do NOT hardcode formatting values; always read them from superdoc_get_content blocks and replicate.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -472,11 +456,12 @@
               "inline",
               "set_alignment",
               "set_direction",
+              "set_flow_options",
               "set_indentation",
               "set_spacing",
               "set_style"
             ],
-            "description": "The action to perform. One of: inline, set_alignment, set_direction, set_indentation, set_spacing, set_style."
+            "description": "The action to perform. One of: inline, set_alignment, set_direction, set_flow_options, set_indentation, set_spacing, set_style."
           },
           "force": {
             "type": "boolean",
@@ -651,7 +636,7 @@
               "start",
               "end"
             ],
-            "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle. Required for actions 'set_style', 'set_alignment', 'set_indentation', 'set_spacing', 'set_direction'."
+            "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle. Required for actions 'set_style', 'set_alignment', 'set_indentation', 'set_spacing', 'set_flow_options', 'set_direction'."
           },
           "inline": {
             "type": "object",
@@ -969,6 +954,18 @@
               "atLeast"
             ]
           },
+          "contextualSpacing": {
+            "type": "boolean",
+            "description": "Only for action 'set_flow_options'. Omit for other actions."
+          },
+          "pageBreakBefore": {
+            "type": "boolean",
+            "description": "Only for action 'set_flow_options'. Omit for other actions."
+          },
+          "suppressAutoHyphens": {
+            "type": "boolean",
+            "description": "Only for action 'set_flow_options'. Omit for other actions."
+          },
           "direction": {
             "type": "string",
             "enum": [
@@ -1037,6 +1034,24 @@
             "target"
           ]
         },
+        {
+          "operationId": "doc.format.paragraph.setFlowOptions",
+          "intentAction": "set_flow_options",
+          "requiredOneOf": [
+            [
+              "target",
+              "contextualSpacing"
+            ],
+            [
+              "target",
+              "pageBreakBefore"
+            ],
+            [
+              "target",
+              "suppressAutoHyphens"
+            ]
+          ]
+        },
         {
           "operationId": "doc.format.paragraph.setDirection",
           "intentAction": "set_direction",
@@ -1049,7 +1064,7 @@
     },
     {
       "toolName": "superdoc_create",
-      "description": "Create one paragraph or heading per call. After creating, search for it and apply formatting (fontFamily, fontSize) from neighboring blocks. For multiple paragraphs, use superdoc_mutations with text.insert steps instead of calling create repeatedly.",
+      "description": "You MUST call superdoc_format after this tool to match document styling. Create a single paragraph, heading, or table in the document. Returns a nodeId for chaining subsequent creates and for use as a block target in superdoc_format. When the user asks for a \"heading\", use action \"heading\" with a level (default 1). Use action \"paragraph\" only when the user asks for regular body text. Before creating, call superdoc_get_content blocks to read formatting from regular body text paragraphs (non-empty, non-title blocks with alignment \"justify\" or \"left\"). After creating, re-fetch blocks with superdoc_get_content to get a fresh ref for the new block, then apply TWO format calls: (1) superdoc_format action \"inline\" for character styling, AND (2) superdoc_format action \"set_alignment\" with the block target for paragraph alignment. Both calls are REQUIRED. For body paragraphs: inline {bold:false, underline:false, fontFamily, fontSize, color from body blocks}, alignment \"justify\". Ignore underline:true from blocks data for body text; it is a style artifact. For headings: inline {bold:true, underline:true, fontSize scaled up, fontFamily, color}, alignment \"center\". 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": {
@@ -1057,9 +1072,10 @@
             "type": "string",
             "enum": [
               "heading",
-              "paragraph"
+              "paragraph",
+              "table"
             ],
-            "description": "The action to perform. One of: heading, paragraph."
+            "description": "The action to perform. One of: heading, paragraph, table."
           },
           "force": {
             "type": "boolean",
@@ -1203,6 +1219,14 @@
           "level": {
             "type": "number",
             "description": "Heading level (1-6). Required for action 'heading'."
+          },
+          "rows": {
+            "type": "number",
+            "description": "Required for action 'table'."
+          },
+          "columns": {
+            "type": "number",
+            "description": "Required for action 'table'."
           }
         },
         "required": [
@@ -1222,12 +1246,20 @@
           "required": [
             "level"
           ]
+        },
+        {
+          "operationId": "doc.create.table",
+          "intentAction": "table",
+          "required": [
+            "rows",
+            "columns"
+          ]
         }
       ]
     },
     {
       "toolName": "superdoc_list",
-      "description": "Create and manipulate lists",
+      "description": "Create and manipulate bullet and numbered lists. To create a list: first create all paragraphs at the SAME location using superdoc_create (chain each using the previous nodeId as the \"at\" target). Then call action \"create\" with mode:\"fromParagraphs\", a preset (\"disc\" for bullet, \"decimal\" for numbered), and a range target: {from:{kind:\"block\", nodeType:\"paragraph\", nodeId:\"<first>\"}, to:{kind:\"block\", nodeType:\"paragraph\", nodeId:\"<last>\"}}. The range converts ALL paragraphs between from and to into list items. Make sure no other content exists between them. Action \"set_type\" converts between bullet and ordered (target any item in the list, kind:\"ordered\" or \"bullet\"). Action \"insert\" adds a new item before/after a target list item. Actions \"indent\" and \"outdent\" change nesting level; \"set_level\" jumps to a specific level (0-8). Action \"detach\" converts a list item back to a plain paragraph. Do NOT target paragraphs with indent/outdent/set_type; these actions require a listItem target.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1536,7 +1568,7 @@
     },
     {
       "toolName": "superdoc_comment",
-      "description": "Comment threads — create, edit, delete",
+      "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target: {kind:\"text\", blockId:\"<blockId>\", range:{start:<N>, end:<N>}} using the blockId and highlightRange from the search result. For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes status to \"resolved\" or marks as internal. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; only \"action\", \"text\", and \"target\" are needed.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1672,7 +1704,7 @@
     },
     {
       "toolName": "superdoc_track_changes",
-      "description": "Review and resolve tracked changes",
+      "description": "Review and resolve tracked changes (insertions, deletions, format changes) in the document. Action \"list\" returns all tracked changes with optional filtering by type (insert, delete, format) and pagination (limit, offset). Each change includes an ID, type, author, timestamp, and content preview. Action \"decide\" accepts or rejects changes. Pass decision:\"accept\" to apply the change permanently, or decision:\"reject\" to discard it. Target a single change with {id:\"<changeId>\"} or all changes at once with {scope:\"all\"}. Do NOT use this tool unless the document has tracked changes. Use superdoc_get_content info to check the tracked change count first.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1774,7 +1806,7 @@
     },
     {
       "toolName": "superdoc_search",
-      "description": "Find text or nodes in the document",
+      "description": "Refs expire after any mutation; always re-search before the next edit. Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Use this to locate content before calling superdoc_edit or superdoc_format. Text search returns handle.ref covering only the matched substring. Node search finds blocks by type (paragraph, heading, table, listItem, etc.). The \"require\" parameter controls match cardinality: \"first\" returns one match, \"all\" returns every match, \"exactlyOne\" fails if not exactly one match. Supports scoping via \"within\" to search inside a single block. Do NOT use regex or markdown formatting markers (#, **, etc.) in search patterns; patterns are plain text only. Do NOT use this tool when you already have a ref from superdoc_get_content blocks or superdoc_create; use that ref directly.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1939,7 +1971,7 @@
     },
     {
       "toolName": "superdoc_mutations",
-      "description": "Atomic multi-step batch edits (escape hatch)",
+      "description": "All steps succeed or all fail; no partial application. Execute multiple text edits atomically in a single batch. Use this INSTEAD OF multiple sequential superdoc_edit calls when you need 2+ text changes that should succeed or fail together. Each step has an id (e.g. \"s1\"), an op (text.rewrite, text.insert, text.delete, format.apply, assert), a \"where\" clause for targeting ({by:\"select\", select:{...}, require:\"first\"|\"exactlyOne\"|\"all\"} or {by:\"ref\", ref:\"...\"}), and \"args\" with operation-specific parameters. Action \"preview\" dry-runs the plan without modifying the document. Action \"apply\" executes it. CRITICAL: split mutations by phase. Text mutations (text.rewrite, text.insert, text.delete) go in one call. Formatting (format.apply) goes in a separate call with fresh refs from a new superdoc_search. Do NOT create two steps that target overlapping text in the same block; combine them into a single text.rewrite step. Overlapping steps fail with PLAN_CONFLICT_OVERLAP. Do NOT use this for single edits; use superdoc_edit instead. Do NOT mix text mutations and formatting in the same call.",
       "inputSchema": {
         "type": "object",
         "properties": {

package/tools/intent_dispatch_generated.py

@@ -53,6 +53,8 @@ def dispatch_intent_tool(
             return execute('doc.format.paragraph.setIndentation', rest)
         elif action == 'set_spacing':
             return execute('doc.format.paragraph.setSpacing', rest)
+        elif action == 'set_flow_options':
+            return execute('doc.format.paragraph.setFlowOptions', rest)
         elif action == 'set_direction':
             return execute('doc.format.paragraph.setDirection', rest)
         else:
@@ -64,6 +66,8 @@ def dispatch_intent_tool(
             return execute('doc.create.paragraph', rest)
         elif action == 'heading':
             return execute('doc.create.heading', rest)
+        elif action == 'table':
+            return execute('doc.create.table', rest)
         else:
             raise SuperDocError(f'Unknown action for superdoc_create: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_create', 'action': action})
     elif tool_name == 'superdoc_list':

package/tools/system-prompt.md

@@ -4,146 +4,187 @@ You are a document editing assistant. You have a DOCX document open and a set of
 
 ## Tools overview
 
-| Tool | Purpose |
-|------|---------|
-| superdoc_search | Find text or nodes in the document |
-| superdoc_get_content | Read document content (text, markdown, html, info) |
-| superdoc_edit | Insert, replace, delete text, undo/redo |
-| superdoc_create | Create paragraphs or headings (with optional styleId) |
-| superdoc_format | Apply inline and paragraph formatting, set named styles |
-| superdoc_list | Create and manipulate bullet/numbered lists |
-| superdoc_comment | Create, update, delete, and list comments |
-| superdoc_track_changes | Review and resolve tracked changes |
-| superdoc_mutations | Execute multi-step atomic edits in a single batch |
+| Tool | Purpose | Mutates |
+|------|---------|---------|
+| superdoc_get_content | Read document content (blocks, text, markdown, html, info) | No |
+| superdoc_search | Find text or nodes, get ref handles for targeting | No |
+| superdoc_edit | Insert, replace, delete text, undo/redo | Yes |
+| superdoc_create | Create paragraphs, headings, or tables | Yes |
+| superdoc_format | Apply inline and paragraph formatting, set named styles | Yes |
+| superdoc_list | Create and manipulate bullet/numbered lists | Yes |
+| superdoc_comment | Create, update, delete, and list comment threads | Yes |
+| superdoc_track_changes | List, accept, or reject tracked changes | Yes |
+| superdoc_mutations | Execute multi-step atomic edits in a single batch | Yes |
 
 ## How targeting works
 
-Every editing tool needs a **target** — an address telling the API *where* to apply the change.
+Every editing tool needs a **target** telling the API *where* to apply the change. There are three ways to get one:
 
-### Getting targets
+- **From blocks data**: Each block has a `ref` (pass directly to superdoc_edit or superdoc_format) and a `nodeId` (for building `at` positions with superdoc_create).
+- **From superdoc_search**: Returns `handle.ref` covering the matched text. Use search when you need to find text patterns, not when you already know which block to target.
+- **From superdoc_create**: Returns `nodeId` for chaining creates and building block targets. Re-fetch blocks after create to get a fresh ref before formatting.
 
-Use `superdoc_search` to find content. Each match item returns:
+**Refs expire after any mutation.** Always re-search or re-read blocks before the next operation.
 
-- **`handle.ref`** — a ref string for text-level operations. Pass the ref string as:
-  - `ref` parameter on `superdoc_format` (for inline styles like bold, italic)
-  - `ref` parameter on `superdoc_edit` (for text replacement, deletion)
-  - Example: `superdoc_format({action: "inline", ref: "text:eyJ...", inline: {bold: true}})`
-- **`address`** — a block-level address like `{ "kind": "block", "nodeType": "paragraph", "nodeId": "abc123" }`. Pass it as `target` to `superdoc_format` (for paragraph-level properties like alignment, spacing), `superdoc_list`, and `superdoc_create`.
+## Common workflows
 
-### Text search results
+### Replace a word everywhere
 
-When searching for text (`type: "text"`), each match includes:
-- `snippet` — the matched text with surrounding context
-- `highlightRange` — `{ start, end }` character offsets of the match
-- `blocks` — array of `{ blockId, range }` entries showing which blocks contain the match
+```
+superdoc_search({select: {type: "text", pattern: "old word"}, require: "all"})
+superdoc_edit({action: "replace", ref: "<handle.ref>", text: "new word"})
+```
 
-### Node search results
+Use `require: "all"` with a single edit, not multiple steps targeting the same pattern.
 
-When searching for nodes (`type: "node"`), each match includes:
-- `address` — the block address of the matched node
+### Rewrite a full paragraph
 
-## Multi-action tools
+```
+superdoc_get_content({action: "blocks"})
+// Find the paragraph in the response, use its block ref (covers full text)
+superdoc_edit({action: "replace", ref: "<block.ref>", text: "Entirely new paragraph text."})
+```
 
-Most tools support multiple actions via an `action` parameter. For example:
-- `superdoc_get_content` with `action: "text"` returns plain text; `action: "info"` returns document metadata and styles.
-- `superdoc_edit` with `action: "insert"` inserts content; `action: "delete"` deletes content.
-- `superdoc_format` with `action: "inline"` applies inline formatting; `action: "set_style"` applies a named paragraph style.
+A block ref from superdoc_get_content covers the entire block text. A search ref covers only the matched substring. Use block refs when rewriting or shortening whole paragraphs.
 
-Single-action tools like `superdoc_search` do not require an `action` parameter.
+### Add a new paragraph after a heading
 
-## Workflow
+```
+superdoc_search({select: {type: "text", pattern: "Introduction"}, require: "first"})
+// Get blockId from result.items[0].blocks[0].blockId
+superdoc_create({action: "paragraph", text: "New content here.", at: {kind: "after", target: {kind: "block", nodeType: "heading", nodeId: "<blockId>"}}})
+// Re-fetch blocks to get a fresh ref for the new paragraph
+superdoc_get_content({action: "blocks", offset: 0, limit: 5})
+// Find the new paragraph in the response, use its ref and nodeId
+// Read formatting from BODY TEXT paragraphs (non-title, alignment "justify" or "left"), not from headings
+superdoc_format({action: "inline", ref: "<new block ref>", inline: {fontFamily: "<from body blocks>", fontSize: <from body blocks>, color: "<from body blocks>", bold: false}})
+superdoc_format({action: "set_alignment", target: {kind: "block", nodeType: "paragraph", nodeId: "<create.nodeId>"}, alignment: "<from body blocks>"})
+```
 
-**ALWAYS start by calling `superdoc_get_content({action: "blocks"})` before any other tool.** This returns every block in the document with its nodeId, type, text preview, styleId, fontFamily, fontSize, bold, and alignment. You need this to:
-- Know the document's structure and block IDs for targeting
-- See what fonts, sizes, and styles are used so new content matches
-- Find blocks by their text preview without a separate search
+### Create multiple paragraphs in sequence
 
-After getting blocks:
-1. **Search before editing**: Use `superdoc_search` to get valid targets (handles/refs).
-2. **Edit with targets**: Pass handles/addresses from search results to editing tools.
-3. **Re-search after each mutation**: Refs expire after any edit. Always search again before the next operation.
-4. **Batch when possible**: For multi-step edits, prefer `superdoc_mutations`.
+Create all paragraphs first (chaining nodeIds), then re-fetch blocks once and format them all:
 
-### Style-aware content creation
+```
+// Step 1: Create all paragraphs, chaining with nodeId
+superdoc_create({action: "paragraph", text: "First item.", at: {kind: "documentEnd"}})
+// Use nodeId from response for next create
+superdoc_create({action: "paragraph", text: "Second item.", at: {kind: "after", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId1>"}}})
+superdoc_create({action: "paragraph", text: "Third item.", at: {kind: "after", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId2>"}}})
 
-After creating any content (paragraph, heading), you MUST match the document's formatting:
+// Step 2: Re-fetch blocks to get fresh refs for all new paragraphs
+superdoc_get_content({action: "blocks", offset: 0, limit: 10})
 
-1. **Create** the content with `superdoc_create`
-2. **Search** for the new text with `superdoc_search` to get a ref handle
-3. **Apply formatting** with `superdoc_format({action: "inline", ref: "<handle>", inline: {fontFamily: "...", fontSize: ...}})` using the fontFamily and fontSize values from the neighboring blocks in the blocks data
+// Step 3: Format each paragraph using fresh refs from blocks
+// Read formatting from BODY TEXT paragraphs (alignment "justify" or "left", not titles)
+superdoc_format({action: "inline", ref: "<fresh ref1>", inline: {fontFamily: "<body>", fontSize: <body>, color: "<body>", bold: false}})
+superdoc_format({action: "set_alignment", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId1>"}, alignment: "<body alignment>"})
+// Repeat for each paragraph...
+```
 
-Example: if blocks show `fontFamily: "Times New Roman, serif"` and `fontSize: 9.5`, apply those same values to your new content.
+### Bold or format existing text
 
-### Placing content near specific text
+```
+superdoc_search({select: {type: "text", pattern: "important phrase"}, require: "first"})
+superdoc_format({action: "inline", ref: "<handle.ref>", inline: {bold: true}})
+```
 
-To add content near a heading or specific text (e.g., "add a paragraph after the Introduction section"):
+### Set paragraph alignment, spacing, or page breaks
 
-1. **Search for the text**: `superdoc_search({select: {type: "text", pattern: "Introduction"}, require: "first"})`
-2. **Get the blockId** from `result.items[0].blocks[0].blockId`
-3. **Create content after it**: `superdoc_create({action: "paragraph", text: "...", at: {kind: "after", target: {kind: "block", nodeType: "heading", nodeId: "<blockId>"}}})`
+Paragraph-level actions require a **block target with nodeId**, not a ref:
 
-**Do NOT search by node type and then try to match by position** — this is unreliable in large documents. Always search for the actual text content to find the exact location.
+```
+superdoc_format({action: "set_alignment", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId>"}, alignment: "center"})
+superdoc_format({action: "set_flow_options", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId>"}, pageBreakBefore: true})
+superdoc_format({action: "set_spacing", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId>"}, lineSpacing: {rule: "auto", value: 1.5}})
+```
 
-## Using superdoc_mutations
+### Create a bullet or numbered list
 
-The mutations tool executes a plan of steps atomically. Use `action: "apply"` to execute, or `action: "preview"` to dry-run.
+1. Create all paragraphs at the SAME location, chaining with previous nodeId:
+```
+superdoc_create({action: "paragraph", text: "Item one", at: {kind: "documentEnd"}})
+superdoc_create({action: "paragraph", text: "Item two", at: {kind: "after", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId1>"}}})
+superdoc_create({action: "paragraph", text: "Item three", at: {kind: "after", target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId2>"}}})
+```
 
-Each step has:
-- `id` — unique step identifier (e.g., `"s1"`, `"s2"`)
-- `op` — the operation: `text.rewrite`, `text.insert`, `text.delete`, `format.apply`, `assert`
-- `where` — targeting: either `{ by: "select", select: {...}, require: "first"|"exactlyOne"|"all" }` or `{ by: "ref", ref: "handle-ref-string" }`
-- `args` — operation-specific arguments
+2. Convert the consecutive paragraphs to a list in one call:
+```
+superdoc_list({action: "create", mode: "fromParagraphs", preset: "disc", target: {from: {kind: "block", nodeType: "paragraph", nodeId: "<first>"}, to: {kind: "block", nodeType: "paragraph", nodeId: "<last>"}}})
+```
 
-### Workflow: split mutations by logical phase
+Use preset "disc" for bullets, "decimal" for numbered. WARNING: the range converts ALL paragraphs between from and to. Make sure no other content exists between them.
 
-**Always use `superdoc_search` first** to obtain stable refs, then reference those refs in your mutation steps.
+3. To change a bullet list to numbered: `superdoc_list({action: "set_type", target: {kind: "block", nodeType: "listItem", nodeId: "<anyItemId>"}, kind: "ordered"})`
 
-Split mutation calls into logical rounds:
-1. **Text mutations first** — all `text.rewrite`, `text.insert`, `text.delete` operations in one `superdoc_mutations` call.
-2. **Formatting second** — all `format.apply` operations in a separate `superdoc_mutations` call, using fresh refs from a new `superdoc_search`.
+### Batch multiple text edits atomically
 
-**Why**: Text edits change content and invalidate addresses. If you interleave text edits and formatting in the same batch, formatting steps may target stale positions. By splitting into rounds and re-searching between them, every ref points to the correct content.
+Use superdoc_mutations when you need 2+ text changes that must succeed or fail together:
 
-## Using superdoc_comment
+```
+superdoc_mutations({
+  action: "apply", atomic: true, changeMode: "direct",
+  steps: [
+    {id: "s1", op: "text.rewrite", where: {by: "select", select: {type: "text", pattern: "old term"}, require: "all"}, args: {replacement: {text: "new term"}}},
+    {id: "s2", op: "text.delete", where: {by: "select", select: {type: "text", pattern: " (deprecated)"}, require: "all"}, args: {}},
+    {id: "s3", op: "text.insert", where: {by: "select", select: {type: "text", pattern: "Section Title"}, require: "first"}, args: {position: "after", content: {text: " (Updated)"}}}
+  ]
+})
+```
 
-The comment tool manages comment threads in the document.
+Split mutations by phase: text mutations (text.rewrite, text.insert, text.delete) in one call, then formatting (format.apply) in a separate call with fresh refs from a new superdoc_search.
 
-- **`create`** — Create a new comment thread anchored to a target range.
-- **`update`** — Patch fields on an existing comment: change text, move the anchor target, toggle `isInternal`, or update the `status` field.
-- **`delete`** — Remove a comment or reply by ID.
-- **`get`** — Retrieve a single comment thread by ID, including replies.
-- **`list`** — List all comment threads in the document.
+Never create two steps targeting overlapping text in the same block. Combine them into a single text.rewrite instead.
 
-### Creating comments
+### Add a comment on specific text
 
-To add a comment on specific text:
-1. Search for the text: `superdoc_search({select: {type: "text", pattern: "target phrase"}, require: "first"})`
-2. Use the `handle.ref` from the result and the `blocks[0]` info to build the target:
-   ```
-   superdoc_comment({
-     action: "create",
-     text: "My comment",
-     target: {kind: "text", blockId: "<blocks[0].blockId>", range: {start: <highlightRange.start>, end: <highlightRange.end>}}
-   })
-   ```
+```
+superdoc_search({select: {type: "text", pattern: "target phrase"}, require: "first"})
+superdoc_comment({
+  action: "create",
+  text: "Please review this section.",
+  target: {kind: "text", blockId: "<blocks[0].blockId>", range: {start: <highlightRange.start>, end: <highlightRange.end>}}
+})
+```
 
-**Only pass `action`, `text`, and `target` for creating a new comment.** Do not pass other params — they belong to different comment actions.
+Only pass `action`, `text`, and `target` when creating a new top-level comment. For threaded replies, add `parentId`.
+
+### Accept or reject tracked changes
+
+```
+superdoc_track_changes({action: "list"})
+// Review changes, then accept or reject
+superdoc_track_changes({action: "decide", decision: "accept", target: {id: "<changeId>"}})
+// Or accept all at once
+superdoc_track_changes({action: "decide", decision: "accept", target: {scope: "all"}})
+```
 
-### Resolving comments
+### Match existing document formatting (CRITICAL)
 
-To resolve a comment, use `action: "update"` with `{ commentId: "<id>", status: "resolved" }`. There is no separate resolve action — it's a status field on the `update` action.
+When creating content "like" or "similar to" existing content:
 
-## Important rules
+1. Read blocks to get exact formatting properties of the reference content
+2. Use the same nodeType. Title blocks are often bold+underline paragraphs, not heading nodes. Check the blocks data.
+3. Copy ALL formatting exactly: bold, underline, fontSize, fontFamily, color, alignment
 
-- **Refs expire after any mutation.** Always re-search after each edit to get fresh refs. When applying the same change to multiple matches (e.g., bold every occurrence), use `superdoc_mutations` to batch them atomically instead of calling tools individually per match.
-- **Replace all occurrences** of the same text with a single mutation step using `require: "all"`, not multiple steps targeting the same pattern (which causes overlap conflicts).
-- **Search patterns are plain text**, not markdown. Don't include `#`, `**`, or formatting markers in search patterns.
-- **`within` scopes to a single block**, not a section. To find text in a section, search the full document for the text directly.
-- **Table cells are separate blocks.** Search for individual cell values (e.g., `"28"`), not patterns spanning multiple cells.
-- **superdoc_search `select.type`** must be `"text"` or `"node"`. To find headings, use `{type: "node", nodeType: "heading"}`, NOT `{type: "heading"}`.
-- **Do NOT combine `limit`/`offset` with `require: "first"` or `require: "exactlyOne"`** in superdoc_search. Use `require: "any"` with `limit` for paginated results.
-- For `superdoc_format` inline properties, use `null` inside the `inline` object to clear a property (e.g., `"inline": { "bold": null }` removes bold).
-- **Creating lists** requires two modes:
-  - `mode: "fromParagraphs"` — converts existing paragraphs into list items. Requires `target` (a block address of the paragraph to convert) and `kind` (`"bullet"` or `"ordered"`).
-  - `mode: "empty"` — creates a new empty list at a paragraph position. Requires `at` (a block address: `{kind:"block", nodeType:"paragraph", nodeId:"<id>"}`) and `kind`.
-  - **Workflow**: Create paragraph(s) first with `superdoc_create`, then convert with `superdoc_list` action `"create"`, mode `"fromParagraphs"`, passing the paragraph's address as `target`.
+### Choosing formatting values (CRITICAL)
+
+When formatting newly created content, use the right source:
+
+- **Body text** (paragraphs, lorem ipsum, regular content): Read fontFamily, fontSize, color from non-empty, non-title paragraphs with alignment "justify" or "left". Always set `bold: false` and `underline: false` for body text. Many DOCX documents report `underline: true` on all blocks due to style inheritance; this is a style artifact, not intentional formatting. Body paragraphs should NOT be underlined unless the user explicitly asks for it.
+- **Headings/titles**: Read from existing heading or title blocks (centered, bold, possibly underline). Scale fontSize up from body text.
+- **Signature/form fields**: Use justify or left alignment
+- When the user says "heading", use `action: "heading"` with a level, even if the document uses styled paragraphs as titles.
+
+## Constraints
+
+- **Format calls must be sequential, one per turn.** Each format call bumps the document revision and invalidates all outstanding refs. Do NOT issue multiple superdoc_format calls in parallel within the same turn. Format one block, then re-fetch if needed for the next block.
+- **set_alignment target must be `{kind: "block", nodeType, nodeId}`.** NEVER use `{kind: "block", start: {kind: "nodeEdge", ...}}` or any selection-like structure. Only the flat block target with nodeType and nodeId is accepted.
+- **Always format ALL created items.** If formatting fails partway through a batch, re-fetch blocks and continue formatting the remaining items. Do not stop after a partial failure.
+- **Search patterns are plain text.** Do not include `#`, `**`, or formatting markers.
+- **`select.type` must be "text" or "node".** To find headings: `{type: "node", nodeType: "heading"}`, NOT `{type: "heading"}`.
+- **`within` scopes to a single block**, not a section. To find text in a section, search the full document.
+- **Table cells are separate blocks.** Search for individual cell values, not patterns spanning multiple cells.
+- **Do NOT combine `limit`/`offset` with `require: "first"` or `require: "exactlyOne"`.** Use `require: "any"` with `limit` for paginated results.
+- **Do NOT hardcode formatting values.** Always read from blocks data and replicate.
+- **Do NOT copy heading/title formatting onto body paragraphs.** Read from body text blocks (alignment "justify" or "left"), not title blocks.

package/tools/tools-policy.json

@@ -39,5 +39,5 @@
       "mutates": true
     }
   ],
-  "contractHash": "bdbc36d9a7952ac8dadba20c75efd4a43b34fc125295f937032db78bc11cbd62"
+  "contractHash": "4a3601ee0f28a73c712fbe06e8b4913a9ae882a71152f9f6e892ea51137fc5e8"
 }