feat(sdk): browser SDK + AI tool quality improvements

apps/cli/src/cli/operation-params.ts

@@ -539,16 +539,17 @@ const EXTRA_CLI_PARAMS: Partial<Record<string, CliOperationParamSpec[]>> = {
   ],
   // Text-range operations: flat flags (--block-id, --start, --end) as shortcuts for --target-json
   'doc.insert': [
-    ...TEXT_TARGET_FLAT_PARAMS,
+    ...TEXT_TARGET_FLAT_PARAMS_AGENT_HIDDEN,
     {
       name: 'offset',
       kind: 'flag',
       type: 'number',
       description: 'Character offset for insertion (alias for --start/--end with same value).',
+      agentVisible: false as const,
     },
   ],
-  'doc.replace': [...TEXT_TARGET_FLAT_PARAMS],
-  'doc.delete': [...TEXT_TARGET_FLAT_PARAMS],
+  'doc.replace': [...TEXT_TARGET_FLAT_PARAMS_AGENT_HIDDEN],
+  'doc.delete': [...TEXT_TARGET_FLAT_PARAMS_AGENT_HIDDEN],
   'doc.styles.apply': [
     {
       name: 'target',

apps/docs/document-api/reference/_generated-manifest.json

@@ -986,5 +986,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "d4231e3456244bc979f6e72db4da7ca682ec851ea2fefebb48689c299fbad039"
+  "sourceHash": "cd730056677977f863b9e7bf54f9e372f7ea9aefb18246cc99bb3d04eda405e5"
 }

apps/docs/document-api/reference/blocks/list.mdx

@@ -130,6 +130,10 @@ Returns a BlocksListResult with total block count, an ordered array of block ent
             "description": "True if text is bold.",
             "type": "boolean"
           },
+          "color": {
+            "description": "Text color (e.g. '#000000'). Defaults to black when not set.",
+            "type": "string"
+          },
           "fontFamily": {
             "description": "Font family from first text run.",
             "type": "string"
@@ -165,6 +169,10 @@ Returns a BlocksListResult with total block count, an ordered array of block ent
           "ordinal": {
             "type": "number"
           },
+          "ref": {
+            "description": "Ref handle for this block. Pass directly to superdoc_format or superdoc_edit ref param. Only present for non-empty blocks.",
+            "type": "string"
+          },
           "styleId": {
             "description": "Named paragraph style.",
             "oneOf": [

apps/docs/document-api/reference/create/heading.mdx

@@ -62,6 +62,7 @@ Returns a CreateHeadingResult with the new heading block ID and address.
 | `insertionPoint.range` | Range | yes | Range |
 | `insertionPoint.range.end` | integer | yes |  |
 | `insertionPoint.range.start` | integer | yes |  |
+| `ref` | string | no |  |
 | `success` | `true` | yes | Constant: `true` |
 | `trackedChangeRefs` | TrackedChangeAddress[] | no |  |
 
@@ -92,6 +93,7 @@ Returns a CreateHeadingResult with the new heading block ID and address.
       "start": 0
     }
   },
+  "ref": "handle:abc123",
   "success": true,
   "trackedChangeRefs": [
     {
@@ -222,6 +224,10 @@ Returns a CreateHeadingResult with the new heading block ID and address.
         "insertionPoint": {
           "$ref": "#/$defs/TextAddress"
         },
+        "ref": {
+          "description": "Ref handle for the created block. Pass directly to superdoc_format or superdoc_edit ref param without searching.",
+          "type": "string"
+        },
         "success": {
           "const": true
         },
@@ -287,6 +293,10 @@ Returns a CreateHeadingResult with the new heading block ID and address.
     "insertionPoint": {
       "$ref": "#/$defs/TextAddress"
     },
+    "ref": {
+      "description": "Ref handle for the created block. Pass directly to superdoc_format or superdoc_edit ref param without searching.",
+      "type": "string"
+    },
     "success": {
       "const": true
     },

apps/docs/document-api/reference/create/paragraph.mdx

@@ -60,6 +60,7 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
 | `paragraph.kind` | `"block"` | yes | Constant: `"block"` |
 | `paragraph.nodeId` | string | yes |  |
 | `paragraph.nodeType` | `"paragraph"` | yes | Constant: `"paragraph"` |
+| `ref` | string | no |  |
 | `success` | `true` | yes | Constant: `true` |
 | `trackedChangeRefs` | TrackedChangeAddress[] | no |  |
 
@@ -90,6 +91,7 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
     "nodeId": "node-def456",
     "nodeType": "paragraph"
   },
+  "ref": "handle:abc123",
   "success": true,
   "trackedChangeRefs": [
     {
@@ -211,6 +213,10 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
         "paragraph": {
           "$ref": "#/$defs/ParagraphAddress"
         },
+        "ref": {
+          "description": "Ref handle for the created block. Pass directly to superdoc_format or superdoc_edit ref param without searching.",
+          "type": "string"
+        },
         "success": {
           "const": true
         },
@@ -276,6 +282,10 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
     "paragraph": {
       "$ref": "#/$defs/ParagraphAddress"
     },
+    "ref": {
+      "description": "Ref handle for the created block. Pass directly to superdoc_format or superdoc_edit ref param without searching.",
+      "type": "string"
+    },
     "success": {
       "const": true
     },

apps/docs/document-api/reference/index.mdx

@@ -70,7 +70,7 @@ The tables below are grouped by namespace.
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/info"><code>info</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.info(...)</code></span> | Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/clear-content"><code>clearContent</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.clearContent(...)</code></span> | Clear all document body content, leaving a single empty paragraph. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/insert"><code>insert</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.insert(...)</code></span> | Insert content into the document. Two input shapes: text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target/ref is omitted, content appends at the end of the document. Text mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block. |
-| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/replace"><code>replace</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.replace(...)</code></span> | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content. |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/replace"><code>replace</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.replace(...)</code></span> | Replace text using a ref. To replace an entire block, use its ref from superdoc_get_content blocks. To replace a text match, use handle.ref from superdoc_search. Do NOT use {kind:"block"} as target — it only works with structural content, not text. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/delete"><code>delete</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.delete(...)</code></span> | Delete content at a contiguous document selection. Accepts a SelectionTarget or mutation-ready ref. Supports cross-block deletion and optional block-edge expansion via behavior mode. |
 
 #### Blocks

apps/docs/document-api/reference/insert.mdx

@@ -233,7 +233,7 @@ Returns an SDMutationReceipt with applied status; resolution reports the inserte
               "$ref": "#/$defs/StoryLocator"
             },
             "ref": {
-              "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.",
               "type": "string"
             },
             "type": {

apps/docs/document-api/reference/replace.mdx

@@ -1,14 +1,14 @@
 ---
 title: replace
 sidebarTitle: replace
-description: Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content.
+description: "Replace text using a ref. To replace an entire block, use its ref from superdoc_get_content blocks. To replace a text match, use handle.ref from superdoc_search. Do NOT use {kind:\"block\"} as target — it only works with structural content, not text."
 ---
 
 {/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}
 
 ## Summary
 
-Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content.
+Replace text using a ref. To replace an entire block, use its ref from superdoc_get_content blocks. To replace a text match, use handle.ref from superdoc_search. Do NOT use \{kind:"block"\} as target — it only works with structural content, not text.
 
 - Operation ID: `replace`
 - API member path: `editor.doc.replace(...)`

apps/docs/document-engine/sdks.mdx

@@ -383,7 +383,7 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.info` | `info` | Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities. |
 | `doc.clearContent` | `clear-content` | Clear all document body content, leaving a single empty paragraph. |
 | `doc.insert` | `insert` | Insert content into the document. Two input shapes: text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target/ref is omitted, content appends at the end of the document. Text mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block. |
-| `doc.replace` | `replace` | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content. |
+| `doc.replace` | `replace` | Replace text using a ref. To replace an entire block, use its ref from superdoc_get_content blocks. To replace a text match, use handle.ref from superdoc_search. Do NOT use {kind:"block"} as target — it only works with structural content, not text. |
 | `doc.delete` | `delete` | Delete content at a contiguous document selection. Accepts a SelectionTarget or mutation-ready ref. Supports cross-block deletion and optional block-edge expansion via behavior mode. |
 | `doc.blocks.list` | `blocks list` | List top-level blocks in document order with IDs, types, and text previews. Supports pagination via offset/limit and optional nodeType filtering. |
 | `doc.blocks.delete` | `blocks delete` | Delete an entire block node (paragraph, heading, list item, table, image, or sdt) deterministically. |
@@ -833,7 +833,7 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.info` | `info` | Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities. |
 | `doc.clear_content` | `clear-content` | Clear all document body content, leaving a single empty paragraph. |
 | `doc.insert` | `insert` | Insert content into the document. Two input shapes: text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target/ref is omitted, content appends at the end of the document. Text mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block. |
-| `doc.replace` | `replace` | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content. |
+| `doc.replace` | `replace` | Replace text using a ref. To replace an entire block, use its ref from superdoc_get_content blocks. To replace a text match, use handle.ref from superdoc_search. Do NOT use {kind:"block"} as target — it only works with structural content, not text. |
 | `doc.delete` | `delete` | Delete content at a contiguous document selection. Accepts a SelectionTarget or mutation-ready ref. Supports cross-block deletion and optional block-edge expansion via behavior mode. |
 | `doc.blocks.list` | `blocks list` | List top-level blocks in document order with IDs, types, and text previews. Supports pagination via offset/limit and optional nodeType filtering. |
 | `doc.blocks.delete` | `blocks delete` | Delete an entire block node (paragraph, heading, list item, table, image, or sdt) deterministically. |

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

@@ -95,13 +95,17 @@ export const INTENT_GROUP_META: Record<string, IntentGroupMeta> = {
   get_content: {
     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.',
+      'Read document content. Use action "blocks" to get all blocks with nodeId, formatting, and ref handles for immediate use with superdoc_format or superdoc_edit. Use "text" or "markdown" for full content. Use "info" for document metadata.',
+  },
+  edit: {
+    toolName: 'superdoc_edit',
+    description:
+      'Insert, replace, delete text, or undo/redo. For replace/delete: use ref param. A search handle.ref only covers the matched text. To replace an entire block (rewrite/shorten), use the block ref from superdoc_get_content blocks instead — it covers the full text.',
   },
-  edit: { toolName: 'superdoc_edit', description: 'Insert, replace, delete text, or undo/redo' },
   create: {
     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.',
+      'Create one paragraph or heading. Response includes a ref and nodeId. After creating, call superdoc_format with the ref to match the document style: copy fontFamily and color from nearby blocks. For headings: only set fontFamily and color (NOT fontSize). For paragraphs: set fontFamily, fontSize, and color. Use superdoc_get_content blocks to read existing formatting. When creating multiple items, use the previous nodeId as the next at target.',
   },
   format: {
     toolName: 'superdoc_format',
@@ -494,9 +498,9 @@ export const OPERATION_DEFINITIONS = {
   replace: {
     memberPath: 'replace',
     description:
-      'Replace content at a contiguous document selection. ' +
-      'Text path accepts a SelectionTarget or ref plus replacement text. ' +
-      'Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content.',
+      'Replace text using a ref. To replace an entire block, use its ref from superdoc_get_content blocks. ' +
+      'To replace a text match, use handle.ref from superdoc_search. ' +
+      'Do NOT use {kind:"block"} as target — it only works with structural content, not text.',
     expectedResult:
       'Returns an SDMutationReceipt with applied status; receipt reports NO_OP if the target range already contains identical content.',
     requiresDocumentContext: true,

packages/document-api/src/contract/schemas.ts

@@ -127,7 +127,8 @@ function optionalTargetLocatorWithPayload(
         {
           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.',
           },
           ...payloadProperties,
         },
@@ -767,6 +768,11 @@ const createParagraphSuccessSchema = objectSchema(
     paragraph: paragraphAddressSchema,
     insertionPoint: textAddressSchema,
     trackedChangeRefs: arraySchema(trackChangeRefSchema),
+    ref: {
+      type: 'string',
+      description:
+        'Ref handle for the created block. Pass directly to superdoc_format or superdoc_edit ref param without searching.',
+    },
   },
   ['success', 'paragraph', 'insertionPoint'],
 );
@@ -793,6 +799,11 @@ const createHeadingSuccessSchema = objectSchema(
     heading: headingAddressSchema,
     insertionPoint: textAddressSchema,
     trackedChangeRefs: arraySchema(trackChangeRefSchema),
+    ref: {
+      type: 'string',
+      description:
+        'Ref handle for the created block. Pass directly to superdoc_format or superdoc_edit ref param without searching.',
+    },
   },
   ['success', 'heading', 'insertionPoint'],
 );
@@ -3031,8 +3042,14 @@ const operationSchemas: Record<OperationId, OperationSchemaSet> = {
               fontFamily: { type: 'string', description: 'Font family from first text run.' },
               fontSize: { type: 'number', description: 'Font size from first text run.' },
               bold: { type: 'boolean', description: 'True if text is bold.' },
+              color: { type: 'string', description: "Text color (e.g. '#000000'). Defaults to black when not set." },
               alignment: { type: 'string', description: 'Paragraph alignment.' },
               headingLevel: { type: 'number', description: 'Heading level (1-6).' },
+              ref: {
+                type: 'string',
+                description:
+                  'Ref handle for this block. Pass directly to superdoc_format or superdoc_edit ref param. Only present for non-empty blocks.',
+              },
             },
             ['ordinal', 'nodeId', 'nodeType'],
           ),

packages/document-api/src/types/blocks.types.ts

@@ -18,10 +18,14 @@ export interface BlockListEntry {
   fontSize?: number;
   /** True if the block's text is bold. */
   bold?: boolean;
+  /** Text color (defaults to '#000000' when not explicitly set). */
+  color?: string;
   /** Paragraph alignment. */
   alignment?: string;
   /** Heading level (1-6). Only for headings. */
   headingLevel?: number;
+  /** Ref handle targeting the block's full text. Pass to superdoc_format or superdoc_edit. */
+  ref?: string;
 }
 
 export interface BlocksListInput {