docs(sdk): update tool descriptions to show alignment inside format.apply step

Author: tupizz

packages/document-api/src/contract/operation-definitions.ts

@@ -144,38 +144,44 @@ export const INTENT_GROUP_META: Record<string, IntentGroupMeta> = {
   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, follow up with ONE superdoc_mutations call using format.apply steps to match the document style. ' +
+      'Each format.apply step accepts "inline" (fontFamily, fontSize, bold, underline, color) AND "alignment" ("left","center","right","justify") in the same step — combine both in one step per block. ' +
+      'Look at nearby headings and paragraphs in the get_content response and copy their exact formatting. Do NOT invent values — match what is already in the document. ' +
+      '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. ' +
       '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. ' +
-      'To create a document with multiple headings and paragraphs, use action "insert" with type "markdown" and placement "end". ' +
-      'The markdown parser creates proper Heading styles from # markers (# = Heading1, ## = Heading2), bold from **text**, italic from *text*, and numbered/bullet lists. ' +
-      'This is the most efficient way to build document structure: one call creates all sections. Follow up with superdoc_mutations format.apply steps to apply formatting (color, font, alignment) that markdown cannot express. ' +
-      'Use "placement" (before, after, insideStart, insideEnd) to control position relative to the target. ' +
+      '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: 'replace', ref: '<handle.ref>', text: 'new text here' },
-      { action: 'insert', value: 'Appended paragraph.', placement: 'insideEnd' },
-      { action: 'insert', ref: '<block.ref>', value: 'Inserted before.', placement: 'before' },
       {
         action: 'insert',
         type: 'markdown',
-        placement: 'end',
+        target: { kind: 'block', nodeType: 'paragraph', nodeId: '<nodeId>' },
+        placement: 'before',
+        value: '# Executive Summary\n\nThis agreement sets forth the principal terms...',
+      },
+      {
+        action: 'insert',
+        type: 'markdown',
         value:
           '# Section Title\n\nParagraph content here.\n\n# Another Section\n\nMore content with **bold** and *italic*.',
       },
+      { action: 'replace', ref: '<handle.ref>', text: 'new text here' },
       { action: 'delete', ref: '<handle.ref>' },
       { action: 'undo' },
     ],
   },
   create: {
     toolName: 'superdoc_create',
     description:
-      'Create a single paragraph, heading, or table. Returns nodeId and ref for the created block. ' +
-      'For creating multiple headings and paragraphs at once, prefer superdoc_edit with type "markdown" (one call for all structure) instead of calling superdoc_create repeatedly. ' +
-      'Use superdoc_create when you need to add one block at a specific position relative to another block. ' +
+      '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. ' +

packages/sdk/tools/prompt-templates/system-prompt-core.md

@@ -128,29 +128,37 @@ Use preset "disc" for bullets, "decimal" for numbered. WARNING: the range conver
 
 3. To change a bullet list to numbered: `superdoc_list({action: "set_type", target: {kind: "block", nodeType: "listItem", nodeId: "<anyItemId>"}, kind: "ordered"})`
 
-### Create a multi-section document efficiently
+### Insert content into a document (new or existing)
 
-**Step 1: Create all structure in one call using markdown insert:**
+Markdown insert creates block structure but uses default formatting. You MUST follow up with formatting to match the document's existing style.
+
+**Step 1: Read existing formatting** from the initial get_content blocks response. Pay special attention to:
+- **Nearby headings/titles**: look at their fontFamily, fontSize, bold, underline, alignment (especially center vs justify vs left). Your new headings must match these exactly.
+- **Body paragraphs**: note fontFamily, fontSize, color, alignment. Your new paragraphs must match.
+- Match the style of the nearest similar element, not arbitrary values.
+
+**Step 2: Insert content with markdown:**
 
 ```
-superdoc_edit({action: "insert", type: "markdown", placement: "end",
-  value: "# Definitions\n\n\"Confidential Information\" means any non-public information...\n\n# Obligations\n\nThe Receiving Party agrees to maintain confidentiality...\n\n# Governing Law\n\nThis Agreement shall be governed by the laws of..."})
+superdoc_edit({action: "insert", type: "markdown",
+  target: {kind: "block", nodeType: "paragraph", nodeId: "<first-block-nodeId>"},
+  placement: "before",
+  value: "# Executive Summary\n\nThis agreement sets forth the principal terms..."})
 ```
 
-This creates headings with proper Heading1 style, paragraphs, bold (**text**), italic (*text*), lists, and tables in one call. Markdown cannot express color, font-size, or alignment — those require step 2.
-
-**Step 2: Apply formatting in one batch:**
+**Step 3: Apply ALL formatting in a SINGLE superdoc_mutations call.** Each format.apply step accepts both `inline` (text styles) AND `alignment` (paragraph alignment) — one step per block.
 
+Example: if the document has centered, underlined, 12pt headings and justified 12pt body text:
 ```
-superdoc_mutations({action: "apply", steps: [
-  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "node", nodeType: "heading"}, require: "all"}, args: {inline: {color: "#FF0000"}}},
-  {id: "f2", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "Confidential Information"}, require: "all"}, args: {inline: {bold: true}}}
+superdoc_mutations({action: "apply", atomic: true, steps: [
+  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "Executive Summary"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, underline: true}, alignment: "center"}},
+  {id: "f2", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "This agreement sets forth"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, color: "#000000"}, alignment: "justify"}}
 ]})
 ```
 
-Use `require: "all"` with a node selector to format every heading at once instead of formatting one at a time.
+CRITICAL: Do NOT guess formatting values. Copy them from the existing document blocks you read in step 1. Use ONE format.apply step per block with both `inline` and `alignment` combined.
 
-Total: 4 calls (open, insert, format batch, save) instead of 40+.
+Total: 3 calls (read + insert + format-all-in-one-batch). Never more.
 
 ### Batch multiple text edits atomically
 

packages/sdk/tools/prompt-templates/system-prompt-mcp-header.md

@@ -14,27 +14,36 @@ These tools handle the OOXML format correctly and preserve document structure.
 
 ## Efficient patterns (use these instead of calling tools one at a time)
 
-**Creating multiple headings and paragraphs — use markdown insert (one call):**
+**Creating headings and paragraphs — ALWAYS use markdown insert (one call):**
 ```
-superdoc_edit({action: "insert", type: "markdown", placement: "end",
+superdoc_edit({action: "insert", type: "markdown",
   value: "# Section Title\n\nParagraph content.\n\n# Another Section\n\nMore content with **bold**."})
 ```
 This creates proper Heading styles from # markers. One call replaces many superdoc_create calls.
 
-**Formatting multiple items at once — use mutations batch (one call):**
+**Inserting at a specific position — use target + placement:**
 ```
-superdoc_mutations({action: "apply", steps: [
-  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "node", nodeType: "heading"}, require: "all"}, args: {inline: {color: "#FF0000"}}},
-  {id: "f2", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "important term"}, require: "all"}, args: {inline: {bold: true}}}
+superdoc_edit({action: "insert", type: "markdown",
+  target: {kind: "block", nodeType: "paragraph", nodeId: "<nodeId>"},
+  placement: "before",
+  value: "# Executive Summary\n\nThis agreement sets forth the principal terms..."})
+```
+Valid placements: "before", "after", "insideStart", "insideEnd". Without target, content appends at document end.
+
+**Formatting — each format.apply step accepts both `inline` AND `alignment`:**
+```
+superdoc_mutations({action: "apply", atomic: true, steps: [
+  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "Executive Summary"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, underline: true}, alignment: "center"}},
+  {id: "f2", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "body paragraph text"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12}, alignment: "justify"}}
 ]})
 ```
-Use require "all" to format every match at once. Selectors resolve before execution, so format targets must exist in the document before the batch runs.
+One format.apply step per block. Combine `inline` (text styles) and `alignment` (paragraph alignment) in the same step. Do NOT use separate superdoc_format calls.
 
 **When to use which tool:**
-- Creating multiple blocks → `superdoc_edit` with type "markdown"
-- Creating one block at a specific position → `superdoc_create`
-- Formatting multiple items → `superdoc_mutations` with format.apply steps
-- Formatting one item → `superdoc_format`
+- Creating headings, paragraphs, or any block content → `superdoc_edit` with type "markdown" (preferred, even for a single heading + paragraph)
+- Creating one block only when markdown is insufficient → `superdoc_create`
+- ALL formatting after insert → `superdoc_mutations` with format.apply (inline + alignment in one step per block)
+- Single quick format (no insert before it) → `superdoc_format`
 - Multiple text edits → `superdoc_mutations`
 - Single text edit → `superdoc_edit`