docs(sdk): only set properties explicitly present in document blocks

Author: tupizz

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

@@ -150,8 +150,8 @@ export const INTENT_GROUP_META: Record<string, IntentGroupMeta> = {
       '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. ALWAYS include fontSize — especially on headings, which inherit a large default size that must be overridden. ' +
-      'Copy exact formatting from nearby blocks in the get_content response. Do NOT invent values. Your inserted content must be visually indistinguishable from the rest of the document. ' +
+      'Use scope: "block" so formatting covers the entire paragraph. ' +
+      'ONLY set inline properties that are explicitly shown in the existing get_content blocks. If blocks do not show fontSize, do NOT set fontSize (it inherits the document default). Do NOT invent values — mirror exactly what the document 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. ' +
       'Refs expire after any mutation; always re-search before the next edit. ' +

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

@@ -153,12 +153,20 @@ superdoc_edit({action: "insert", type: "markdown",
 
 Use `scope: "block"` so the formatting covers the entire paragraph (not just the matched text). The text pattern only needs to identify which block.
 
-ALWAYS include `fontSize` on every block, especially headings. Markdown headings inherit a large default font size that must be overridden. If a block in get_content doesn't show fontSize, use the fontSize from the nearest block that does.
+ONLY include inline properties that are explicitly present in the existing blocks. If the document blocks don't show `fontSize`, do NOT set fontSize (it will inherit the document's default, which is correct). If they don't show `bold`, don't set bold. Mirror exactly what you see, nothing more. Inventing values (like assuming fontSize: 12) causes mismatches.
 
-Example: document has centered, non-bold, 12pt titles and justified 12pt body text:
+Example: document blocks show fontFamily and color but NO fontSize, titles are centered:
 ```
 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}, alignment: "center", scope: "block"}},
+  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "Executive Summary"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", color: "#000000"}, alignment: "center", scope: "block"}},
+  {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", color: "#000000"}, scope: "block"}}
+]})
+```
+
+Example: document blocks explicitly show fontSize: 12, titles are centered and underlined:
+```
+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", scope: "block"}},
   {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", scope: "block"}}
 ]})
 ```

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

@@ -37,7 +37,7 @@ superdoc_mutations({action: "apply", atomic: true, steps: [
   {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}, alignment: "justify", scope: "block"}}
 ]})
 ```
-One format.apply step per block. Combine `inline`, `alignment`, and `scope: "block"` in each step. The pattern only needs to identify which paragraph. ALWAYS include `fontSize` on headings — markdown headings inherit a large default size that must be overridden to match the document.
+One format.apply step per block. Combine `inline`, `alignment`, and `scope: "block"` in each step. ONLY set properties that are explicitly shown in the existing document blocks. If blocks don't show fontSize, don't set it (the document default will apply correctly). Do NOT invent values.
 
 **When to use which tool:**
 - Creating headings, paragraphs, or any block content → `superdoc_edit` with type "markdown" (preferred, even for a single heading + paragraph)