docs(sdk): context-driven formatting guidance for markdown inserts

Author: tupizz

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

@@ -148,10 +148,10 @@ export const INTENT_GROUP_META: Record<string, IntentGroupMeta> = {
       '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. ' +
-      '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. ' +
+      '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. ' +
       '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

@@ -130,12 +130,15 @@ Use preset "disc" for bullets, "decimal" for numbered. WARNING: the range conver
 
 ### Insert content into a document (new or existing)
 
-Markdown insert creates block structure but uses default formatting. You MUST follow up with formatting to match the document's existing style.
+Markdown insert creates block structure but uses default formatting. You MUST follow up with formatting so inserted content looks like it belongs in the document.
 
-**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 1: Understand the document context** from the get_content blocks response. Before inserting anything, analyze:
+- What kind of document is this? (contract, letter, certificate, report, etc.)
+- How are titles/headings styled? (centered? left? bold? underlined? what fontSize?)
+- How is body text styled? (fontFamily, fontSize, alignment, color)
+- What formatting conventions does the document follow?
+
+Your inserted content must be indistinguishable from the existing content. If titles are centered 10pt Times New Roman with no bold, your heading must be centered 10pt Times New Roman with no bold. If body text is justified 12pt with underline, your paragraphs must be justified 12pt with underline.
 
 **Step 2: Insert content with markdown:**
 
@@ -146,24 +149,20 @@ superdoc_edit({action: "insert", type: "markdown",
   value: "# Executive Summary\n\nThis agreement sets forth the principal terms..."})
 ```
 
-**Step 3: Apply ALL formatting in a SINGLE superdoc_mutations call.** Each format.apply step accepts `inline` (text styles), `alignment` (paragraph alignment), and `scope` — combine them all in one step per block.
+**Step 3: Format ALL inserted blocks in ONE superdoc_mutations call.** Each format.apply step accepts `inline`, `alignment`, and `scope: "block"`.
+
+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 use `scope: "block"` after markdown inserts. This makes the formatting cover the entire paragraph, not just the matched text pattern. The pattern only needs to uniquely identify which paragraph — a short prefix is enough.
+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.
 
-Example: if the document has centered, underlined, 12pt headings and justified 12pt body text:
+Example: document has centered, non-bold, 12pt titles and justified 12pt body text:
 ```
 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: "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: "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"}}
 ]})
 ```
 
-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.
 
 ### Batch multiple text edits atomically