docs(sdk): require fontSize on headings after markdown insert

Author: tupizz

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

@@ -151,6 +151,7 @@ export const INTENT_GROUP_META: Record<string, IntentGroupMeta> = {
       '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. ' +
+      'ALWAYS include fontSize on headings — markdown headings inherit a large default size that must be overridden to match the document. Use scope: "block" so formatting covers the entire paragraph. ' +
       '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

@@ -158,7 +158,11 @@ superdoc_mutations({action: "apply", atomic: true, steps: [
 ]})
 ```
 
-CRITICAL: Do NOT guess formatting values. Copy them from the existing document blocks you read in step 1. Use `scope: "block"` so the formatting covers the ENTIRE paragraph, not just the matched text.
+CRITICAL rules for formatting after insert:
+- Do NOT guess formatting values. Copy them from the existing document blocks you read in step 1.
+- Use `scope: "block"` so the formatting covers the ENTIRE paragraph, not just the matched text.
+- ALWAYS include `fontSize` on headings. Markdown headings inherit a large default font size from the Heading1 style. You MUST override it with the fontSize used by existing titles/headings in the document (typically the same as body text, e.g., 10pt or 12pt).
+- If the document blocks don't show a fontSize, use the fontSize from the nearest block that does have one.
 
 Total: 3 calls (read + insert + format-all-in-one-batch). Never more.
 

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 — `scope: "block"` formats the entire paragraph, not just the matched text.
+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.
 
 **When to use which tool:**
 - Creating headings, paragraphs, or any block content → `superdoc_edit` with type "markdown" (preferred, even for a single heading + paragraph)