fix(document-api): improve AI tool definitions, add block refs, and fix formatting extraction

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

@@ -609,16 +609,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/available-operations.mdx

@@ -36,6 +36,8 @@ Use the tables below to see what operations are available and where each one is
 | Mutations | 2 | 0 | 2 | [Reference](/document-api/reference/mutations/index) |
 | Paragraph Formatting | 19 | 0 | 19 | [Reference](/document-api/reference/format/paragraph/index) |
 | Paragraph Styles | 2 | 0 | 2 | [Reference](/document-api/reference/styles/paragraph/index) |
+| Permission Ranges | 5 | 0 | 5 | [Reference](/document-api/reference/permission-ranges/index) |
+| Protection | 3 | 0 | 3 | [Reference](/document-api/reference/protection/index) |
 | Query | 1 | 0 | 1 | [Reference](/document-api/reference/query/index) |
 | Ranges | 1 | 0 | 1 | [Reference](/document-api/reference/ranges/index) |
 | Sections | 18 | 0 | 18 | [Reference](/document-api/reference/sections/index) |
@@ -335,6 +337,14 @@ Use the tables below to see what operations are available and where each one is
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.format.paragraph.clearDirection(...)</code></span> | [`format.paragraph.clearDirection`](/document-api/reference/format/paragraph/clear-direction) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.styles.paragraph.setStyle(...)</code></span> | [`styles.paragraph.setStyle`](/document-api/reference/styles/paragraph/set-style) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.styles.paragraph.clearStyle(...)</code></span> | [`styles.paragraph.clearStyle`](/document-api/reference/styles/paragraph/clear-style) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.permissionRanges.list(...)</code></span> | [`permissionRanges.list`](/document-api/reference/permission-ranges/list) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.permissionRanges.get(...)</code></span> | [`permissionRanges.get`](/document-api/reference/permission-ranges/get) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.permissionRanges.create(...)</code></span> | [`permissionRanges.create`](/document-api/reference/permission-ranges/create) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.permissionRanges.remove(...)</code></span> | [`permissionRanges.remove`](/document-api/reference/permission-ranges/remove) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.permissionRanges.updatePrincipal(...)</code></span> | [`permissionRanges.updatePrincipal`](/document-api/reference/permission-ranges/update-principal) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.protection.get(...)</code></span> | [`protection.get`](/document-api/reference/protection/get) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.protection.setEditingRestriction(...)</code></span> | [`protection.setEditingRestriction`](/document-api/reference/protection/set-editing-restriction) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.protection.clearEditingRestriction(...)</code></span> | [`protection.clearEditingRestriction`](/document-api/reference/protection/clear-editing-restriction) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.query.match(...)</code></span> | [`query.match`](/document-api/reference/query/match) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.ranges.resolve(...)</code></span> | [`ranges.resolve`](/document-api/reference/ranges/resolve) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.list(...)</code></span> | [`sections.list`](/document-api/reference/sections/list) |

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

@@ -320,6 +320,16 @@
     "apps/docs/document-api/reference/mutations/apply.mdx",
     "apps/docs/document-api/reference/mutations/index.mdx",
     "apps/docs/document-api/reference/mutations/preview.mdx",
+    "apps/docs/document-api/reference/permission-ranges/create.mdx",
+    "apps/docs/document-api/reference/permission-ranges/get.mdx",
+    "apps/docs/document-api/reference/permission-ranges/index.mdx",
+    "apps/docs/document-api/reference/permission-ranges/list.mdx",
+    "apps/docs/document-api/reference/permission-ranges/remove.mdx",
+    "apps/docs/document-api/reference/permission-ranges/update-principal.mdx",
+    "apps/docs/document-api/reference/protection/clear-editing-restriction.mdx",
+    "apps/docs/document-api/reference/protection/get.mdx",
+    "apps/docs/document-api/reference/protection/index.mdx",
+    "apps/docs/document-api/reference/protection/set-editing-restriction.mdx",
     "apps/docs/document-api/reference/query/index.mdx",
     "apps/docs/document-api/reference/query/match.mdx",
     "apps/docs/document-api/reference/ranges/index.mdx",
@@ -983,8 +993,28 @@
       "operationIds": ["diff.capture", "diff.compare", "diff.apply"],
       "pagePath": "apps/docs/document-api/reference/diff/index.mdx",
       "title": "Diff"
+    },
+    {
+      "aliasMemberPaths": [],
+      "key": "protection",
+      "operationIds": ["protection.get", "protection.setEditingRestriction", "protection.clearEditingRestriction"],
+      "pagePath": "apps/docs/document-api/reference/protection/index.mdx",
+      "title": "Protection"
+    },
+    {
+      "aliasMemberPaths": [],
+      "key": "permissionRanges",
+      "operationIds": [
+        "permissionRanges.list",
+        "permissionRanges.get",
+        "permissionRanges.create",
+        "permissionRanges.remove",
+        "permissionRanges.updatePrincipal"
+      ],
+      "pagePath": "apps/docs/document-api/reference/permission-ranges/index.mdx",
+      "title": "Permission Ranges"
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "d4231e3456244bc979f6e72db4da7ca682ec851ea2fefebb48689c299fbad039"
+  "sourceHash": "4a3601ee0f28a73c712fbe06e8b4913a9ae882a71152f9f6e892ea51137fc5e8"
 }

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 when explicitly set (e.g. '#000000').",
+            "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": [