@superdoc-dev/cli 0.3.0-next.37 → 0.3.0-next.38

package/dist/index.js

@@ -7254,8 +7254,20 @@ function ref(name) {
 function targetLocatorWithPayload(payloadProperties, payloadRequired = []) {
   return {
     oneOf: [
-      objectSchema({ target: ref("SelectionTarget"), ...payloadProperties }, ["target", ...payloadRequired]),
-      objectSchema({ ref: { type: "string" }, ...payloadProperties }, ["ref", ...payloadRequired])
+      objectSchema({
+        target: {
+          ...ref("SelectionTarget"),
+          description: "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle."
+        },
+        ...payloadProperties
+      }, ["target", ...payloadRequired]),
+      objectSchema({
+        ref: {
+          type: "string",
+          description: "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting."
+        },
+        ...payloadProperties
+      }, ["ref", ...payloadRequired])
     ]
   };
 }
@@ -7907,6 +7919,7 @@ var init_schemas = __esm(() => {
       nodeId: { type: "string" }
     }, ["kind", "nodeType", "nodeId"]),
     SelectionPoint: {
+      description: "A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.",
       oneOf: [
         objectSchema({ kind: { const: "text" }, blockId: { type: "string" }, offset: { type: "integer", minimum: 0 } }, [
           "kind",
@@ -8191,15 +8204,18 @@ var init_schemas = __esm(() => {
     hint: { type: "string" }
   }, ["message"]);
   textSelectorSchema = objectSchema({
-    type: { const: "text" },
-    pattern: { type: "string" },
-    mode: { enum: ["contains", "regex"] },
-    caseSensitive: { type: "boolean" }
+    type: { const: "text", description: "Must be 'text' for text pattern search." },
+    pattern: { type: "string", description: "Text or regex pattern to match." },
+    mode: { enum: ["contains", "regex"], description: "Match mode: 'contains' (substring) or 'regex'." },
+    caseSensitive: { type: "boolean", description: "Case-sensitive matching. Default: false." }
   }, ["type", "pattern"]);
   nodeSelectorSchema = objectSchema({
-    type: { const: "node" },
-    nodeType: { enum: [...nodeTypeValues] },
-    kind: { enum: ["block", "inline"] }
+    type: { const: "node", description: "Must be 'node' for node type search." },
+    nodeType: {
+      enum: [...nodeTypeValues],
+      description: "Block type to match (paragraph, heading, table, listItem, etc.)."
+    },
+    kind: { enum: ["block", "inline"], description: "Filter: 'block' or 'inline'." }
   }, ["type"]);
   selectorShorthandSchema = objectSchema({
     nodeType: { enum: [...nodeTypeValues] }
@@ -8580,20 +8596,36 @@ var init_schemas = __esm(() => {
     oneOf: [{ type: "object" }, { type: "array", items: { type: "object" } }]
   };
   placementSchema = { enum: ["before", "after", "insideStart", "insideEnd"] };
-  nestingPolicySchema = objectSchema({
-    tables: { enum: ["forbid", "allow"] }
-  });
+  nestingPolicySchema = {
+    ...objectSchema({
+      tables: { enum: ["forbid", "allow"] }
+    }),
+    description: "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables."
+  };
   insertInputSchema = {
     oneOf: [
       objectSchema({
-        target: textAddressSchema,
-        value: { type: "string" },
-        type: { type: "string", enum: ["text", "markdown", "html"] }
+        target: {
+          ...textAddressSchema,
+          description: "Insertion point: {kind:'text', blockId:'...', range:{start, end}}."
+        },
+        value: { type: "string", description: "Text content to insert." },
+        type: {
+          type: "string",
+          enum: ["text", "markdown", "html"],
+          description: "Content format: 'text' (default), 'markdown', or 'html'."
+        }
       }, ["value"]),
       objectSchema({
-        target: blockNodeAddressSchema,
-        content: sdFragmentSchema,
-        placement: placementSchema,
+        target: {
+          ...blockNodeAddressSchema,
+          description: "Block address for structural insertion: {kind:'block', nodeType:'...', nodeId:'...'}."
+        },
+        content: { ...sdFragmentSchema, description: "Document fragment to insert (structured content)." },
+        placement: {
+          ...placementSchema,
+          description: "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'."
+        },
         nestingPolicy: nestingPolicySchema
       }, ["content"])
     ]
@@ -9066,7 +9098,10 @@ var init_schemas = __esm(() => {
     },
     getHtml: {
       input: objectSchema({
-        unflattenLists: { type: "boolean" }
+        unflattenLists: {
+          type: "boolean",
+          description: "When true, flattens nested list structures in output. Default: false."
+        }
       }),
       output: { type: "string" }
     },
@@ -9103,18 +9138,27 @@ var init_schemas = __esm(() => {
       input: {
         oneOf: [
           {
-            ...targetLocatorWithPayload({ text: { type: "string" } }, ["text"])
+            ...targetLocatorWithPayload({ text: { type: "string", description: "Replacement text content." } }, ["text"])
           },
           {
             oneOf: [
               objectSchema({
-                target: { oneOf: [blockNodeAddressSchema, selectionTargetSchema] },
-                content: sdFragmentSchema,
+                target: {
+                  oneOf: [blockNodeAddressSchema, selectionTargetSchema],
+                  description: "Target block or selection to replace."
+                },
+                content: {
+                  ...sdFragmentSchema,
+                  description: "Document fragment to replace with (structured content)."
+                },
                 nestingPolicy: nestingPolicySchema
               }, ["target", "content"]),
               objectSchema({
-                ref: { type: "string" },
-                content: sdFragmentSchema,
+                ref: { type: "string", description: "Reference handle from a previous search result." },
+                content: {
+                  ...sdFragmentSchema,
+                  description: "Document fragment to replace with (structured content)."
+                },
                 nestingPolicy: nestingPolicySchema
               }, ["ref", "content"])
             ]
@@ -9127,7 +9171,9 @@ var init_schemas = __esm(() => {
     },
     delete: {
       input: {
-        ...targetLocatorWithPayload({ behavior: deleteBehaviorSchema })
+        ...targetLocatorWithPayload({
+          behavior: { ...deleteBehaviorSchema, description: "Delete behavior: 'selection' (default) or 'exact'." }
+        })
       },
       output: textMutationResultSchemaFor("delete"),
       success: textMutationSuccessSchema,
@@ -9135,7 +9181,12 @@ var init_schemas = __esm(() => {
     },
     "format.apply": {
       input: {
-        ...targetLocatorWithPayload({ inline: buildInlineRunPatchSchema() }, ["inline"])
+        ...targetLocatorWithPayload({
+          inline: {
+            ...buildInlineRunPatchSchema(),
+            description: "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold."
+          }
+        }, ["inline"])
       },
       output: textMutationResultSchemaFor("format.apply"),
       success: textMutationSuccessSchema,
@@ -9261,10 +9312,18 @@ var init_schemas = __esm(() => {
       input: {
         ...objectSchema({
           target: paragraphTargetSchema,
-          left: { type: "integer", minimum: 0 },
-          right: { type: "integer", minimum: 0 },
-          firstLine: { type: "integer", minimum: 0 },
-          hanging: { type: "integer", minimum: 0 }
+          left: { type: "integer", minimum: 0, description: "Left indentation in twips (1440 = 1 inch)." },
+          right: { type: "integer", minimum: 0, description: "Right indentation in twips (1440 = 1 inch)." },
+          firstLine: {
+            type: "integer",
+            minimum: 0,
+            description: "First line indent in twips. Cannot be combined with hanging."
+          },
+          hanging: {
+            type: "integer",
+            minimum: 0,
+            description: "Hanging indent in twips. Cannot be combined with firstLine."
+          }
         }, ["target"]),
         anyOf: [{ required: ["left"] }, { required: ["right"] }, { required: ["firstLine"] }, { required: ["hanging"] }],
         not: { required: ["firstLine", "hanging"] }
@@ -9283,10 +9342,17 @@ var init_schemas = __esm(() => {
       input: {
         ...objectSchema({
           target: paragraphTargetSchema,
-          before: { type: "integer", minimum: 0 },
-          after: { type: "integer", minimum: 0 },
-          line: { type: "integer", minimum: 1 },
-          lineRule: { enum: [...LINE_RULES] }
+          before: { type: "integer", minimum: 0, description: "Space before paragraph in twips (20 twips = 1pt)." },
+          after: { type: "integer", minimum: 0, description: "Space after paragraph in twips (20 twips = 1pt)." },
+          line: {
+            type: "integer",
+            minimum: 1,
+            description: "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule."
+          },
+          lineRule: {
+            enum: [...LINE_RULES],
+            description: "Line spacing rule. Required when 'line' is set."
+          }
         }, ["target"]),
         anyOf: [{ required: ["before"] }, { required: ["after"] }, { required: ["line"] }, { required: ["lineRule"] }],
         if: { required: ["line"] },
@@ -9474,6 +9540,7 @@ var init_schemas = __esm(() => {
     "create.paragraph": {
       input: objectSchema({
         at: {
+          description: "Position: {kind:'documentEnd'} to append, {kind:'documentStart'} to prepend, or {kind:'before'|'after', target:{kind:'block', nodeType:'...', nodeId:'...'}} for relative placement.",
           oneOf: [
             objectSchema({ kind: { const: "documentStart" } }, ["kind"]),
             objectSchema({ kind: { const: "documentEnd" } }, ["kind"]),
@@ -9487,7 +9554,7 @@ var init_schemas = __esm(() => {
             }, ["kind", "target"])
           ]
         },
-        text: { type: "string" }
+        text: { type: "string", description: "Paragraph text content." }
       }),
       output: createParagraphResultSchemaFor("create.paragraph"),
       success: createParagraphSuccessSchema,
@@ -9495,8 +9562,9 @@ var init_schemas = __esm(() => {
     },
     "create.heading": {
       input: objectSchema({
-        level: headingLevelSchema,
+        level: { ...headingLevelSchema, description: "Heading level (1-6)." },
         at: {
+          description: "Position: {kind:'documentEnd'} to append, {kind:'documentStart'} to prepend, or {kind:'before'|'after', target:{kind:'block', nodeType:'...', nodeId:'...'}} for relative placement.",
           oneOf: [
             objectSchema({ kind: { const: "documentStart" } }, ["kind"]),
             objectSchema({ kind: { const: "documentEnd" } }, ["kind"]),
@@ -9510,7 +9578,7 @@ var init_schemas = __esm(() => {
             }, ["kind", "target"])
           ]
         },
-        text: { type: "string" }
+        text: { type: "string", description: "Heading text content." }
       }, ["level"]),
       output: createHeadingResultSchemaFor("create.heading"),
       success: createHeadingSuccessSchema,
@@ -9756,9 +9824,15 @@ var init_schemas = __esm(() => {
     },
     "lists.insert": {
       input: objectSchema({
-        target: listItemAddressSchema,
-        position: listInsertPositionSchema,
-        text: { type: "string" }
+        target: {
+          ...listItemAddressSchema,
+          description: "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:'<id>'}."
+        },
+        position: {
+          ...listInsertPositionSchema,
+          description: "Required. Insert position relative to target: 'before' or 'after'."
+        },
+        text: { type: "string", description: "Text content for the new list item." }
       }, ["target", "position"]),
       output: listsInsertResultSchemaFor("lists.insert"),
       success: listsInsertSuccessSchema,
@@ -9768,11 +9842,28 @@ var init_schemas = __esm(() => {
       input: {
         type: "object",
         properties: {
-          mode: { enum: ["empty", "fromParagraphs"] },
-          at: ref("BlockAddress"),
-          target: ref("BlockAddressOrRange"),
-          kind: listKindSchema,
-          level: { type: "integer", minimum: 0, maximum: 8 },
+          mode: {
+            enum: ["empty", "fromParagraphs"],
+            description: "Required. Creation mode: 'empty' creates a new empty list at the paragraph specified by 'at'; 'fromParagraphs' converts existing paragraph(s) specified by 'target' into list items."
+          },
+          at: {
+            ...ref("BlockAddress"),
+            description: "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}."
+          },
+          target: {
+            ...ref("BlockAddressOrRange"),
+            description: "Required when mode is 'fromParagraphs'. The paragraph(s) to convert into list items. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}."
+          },
+          kind: {
+            ...listKindSchema,
+            description: "List type: 'bullet' for bullet points, 'ordered' for numbered lists."
+          },
+          level: {
+            type: "integer",
+            minimum: 0,
+            maximum: 8,
+            description: "List nesting level (0-8). 0 is the top level."
+          },
           preset: {
             enum: [
               "decimal",
@@ -9785,7 +9876,8 @@ var init_schemas = __esm(() => {
               "circle",
               "square",
               "dash"
-            ]
+            ],
+            description: "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format."
           },
           style: objectSchema({
             version: { const: 1 },
@@ -10050,7 +10142,10 @@ var init_schemas = __esm(() => {
       input: objectSchema({
         target: listItemAddressSchema,
         kind: { enum: ["ordered", "bullet"] },
-        continuity: { enum: ["preserve", "none"] }
+        continuity: {
+          enum: ["preserve", "none"],
+          description: "Numbering continuity: 'preserve' keeps numbering; 'none' restarts."
+        }
       }, ["target", "kind"]),
       output: listsMutateItemResultSchemaFor("lists.setType"),
       success: listsMutateItemSuccessSchema,
@@ -10298,9 +10393,12 @@ var init_schemas = __esm(() => {
     },
     "comments.create": {
       input: objectSchema({
-        text: { type: "string" },
-        target: textAddressSchema,
-        parentCommentId: { type: "string" }
+        text: { type: "string", description: "Comment text content." },
+        target: {
+          ...textAddressSchema,
+          description: "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}."
+        },
+        parentCommentId: { type: "string", description: "Parent comment ID for creating a threaded reply." }
       }, ["text"]),
       output: receiptResultSchemaFor("comments.create"),
       success: receiptSuccessSchema,
@@ -10309,10 +10407,13 @@ var init_schemas = __esm(() => {
     "comments.patch": {
       input: objectSchema({
         commentId: { type: "string" },
-        text: { type: "string" },
+        text: { type: "string", description: "Updated comment text." },
         target: textAddressSchema,
-        status: { enum: ["resolved"] },
-        isInternal: { type: "boolean" }
+        status: { enum: ["resolved"], description: "Set comment status. Use 'resolved' to mark as resolved." },
+        isInternal: {
+          type: "boolean",
+          description: "When true, marks the comment as internal (hidden from external collaborators)."
+        }
       }, ["commentId"]),
       output: receiptResultSchemaFor("comments.patch"),
       success: receiptSuccessSchema,
@@ -10330,17 +10431,23 @@ var init_schemas = __esm(() => {
     },
     "comments.list": {
       input: objectSchema({
-        includeResolved: { type: "boolean" },
-        limit: { type: "integer" },
-        offset: { type: "integer" }
+        includeResolved: {
+          type: "boolean",
+          description: "When true, includes resolved comments in results. Default: false."
+        },
+        limit: { type: "integer", description: "Maximum number of comments to return." },
+        offset: { type: "integer", description: "Number of comments to skip for pagination." }
       }),
       output: commentsListResultSchema
     },
     "trackChanges.list": {
       input: objectSchema({
-        limit: { type: "integer" },
-        offset: { type: "integer" },
-        type: { enum: ["insert", "delete", "format"] }
+        limit: { type: "integer", description: "Maximum number of tracked changes to return." },
+        offset: { type: "integer", description: "Number of tracked changes to skip for pagination." },
+        type: {
+          enum: ["insert", "delete", "format"],
+          description: "Filter by change type: 'insert', 'delete', or 'format'."
+        }
       }),
       output: trackChangesListResultSchema
     },
@@ -10369,13 +10476,28 @@ var init_schemas = __esm(() => {
     },
     "query.match": {
       input: objectSchema({
-        select: { oneOf: [textSelectorSchema, nodeSelectorSchema] },
-        within: blockNodeAddressSchema,
-        require: { enum: ["any", "first", "exactlyOne", "all"] },
-        mode: { enum: ["strict", "candidates"] },
-        includeNodes: { type: "boolean" },
-        limit: { type: "integer", minimum: 1 },
-        offset: { type: "integer", minimum: 0 }
+        select: {
+          description: "Search selector. Use {type:'text', pattern:'...'} for text search or {type:'node', nodeType:'paragraph'|'heading'|...} for node search.",
+          oneOf: [textSelectorSchema, nodeSelectorSchema]
+        },
+        within: {
+          ...blockNodeAddressSchema,
+          description: "Limit search scope to within a specific block: {kind:'block', nodeType:'...', nodeId:'...'}."
+        },
+        require: {
+          enum: ["any", "first", "exactlyOne", "all"],
+          description: "Match cardinality: 'any' (all matches), 'first' (only first), 'exactlyOne' (fail if != 1), 'all' (fail if 0)."
+        },
+        mode: {
+          enum: ["strict", "candidates"],
+          description: "Search mode: 'strict' (default, exact matching) or 'candidates' (returns scored potential matches)."
+        },
+        includeNodes: {
+          type: "boolean",
+          description: "When true, includes full node data in results. Default: false."
+        },
+        limit: { type: "integer", minimum: 1, description: "Maximum number of matches to return." },
+        offset: { type: "integer", minimum: 0, description: "Number of matches to skip for pagination." }
       }, ["select"]),
       output: (() => {
         const textMatchItemSchema = discoveryItemSchema({
@@ -10507,10 +10629,23 @@ var init_schemas = __esm(() => {
         ]
       };
       const mutationsInputSchema = objectSchema({
-        expectedRevision: { type: "string" },
-        atomic: { const: true, type: "boolean" },
-        changeMode: { enum: ["direct", "tracked"] },
-        steps: arraySchema(mutationStepSchema)
+        expectedRevision: {
+          type: "string",
+          description: "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision."
+        },
+        atomic: {
+          const: true,
+          type: "boolean",
+          description: "Must be true. All steps execute as one atomic transaction."
+        },
+        changeMode: {
+          enum: ["direct", "tracked"],
+          description: "Required. Use 'direct' for immediate edits or 'tracked' for suggestions. Must always be provided."
+        },
+        steps: {
+          ...arraySchema(mutationStepSchema),
+          description: "Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, or assert) and a 'where' targeting clause."
+        }
       }, ["atomic", "changeMode", "steps"]);
       const documentEdgeAnchorSchema = objectSchema({
         kind: { const: "document" },
@@ -39787,7 +39922,7 @@ var init_remark_gfm_z_sDF4ss_es = __esm(() => {
   emptyOptions2 = {};
 });
 
-// ../../packages/superdoc/dist/chunks/SuperConverter-BsjuwDIO.es.js
+// ../../packages/superdoc/dist/chunks/SuperConverter-DarcJh0X.es.js
 function getExtensionConfigField(extension$1, field, context = { name: "" }) {
   const fieldValue = extension$1.config[field];
   if (typeof fieldValue === "function")
@@ -41516,10 +41651,16 @@ function ref2(name) {
 }
 function targetLocatorWithPayload2(payloadProperties, payloadRequired = []) {
   return { oneOf: [objectSchema2({
-    target: ref2("SelectionTarget"),
+    target: {
+      ...ref2("SelectionTarget"),
+      description: "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle."
+    },
     ...payloadProperties
   }, ["target", ...payloadRequired]), objectSchema2({
-    ref: { type: "string" },
+    ref: {
+      type: "string",
+      description: "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting."
+    },
     ...payloadProperties
   }, ["ref", ...payloadRequired])] };
 }
@@ -85856,7 +85997,7 @@ var isRegExp = (value) => {
       state.kern = kernNode.attributes["w:val"];
   }
 }, SuperConverter;
-var init_SuperConverter_BsjuwDIO_es = __esm(() => {
+var init_SuperConverter_DarcJh0X_es = __esm(() => {
   init_rolldown_runtime_B2q5OVn9_es();
   init_jszip_ChlR43oI_es();
   init_xml_js_BtmJ6bNs_es();
@@ -95266,15 +95407,36 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
     hint: { type: "string" }
   }, ["message"]);
   textSelectorSchema2 = objectSchema2({
-    type: { const: "text" },
-    pattern: { type: "string" },
-    mode: { enum: ["contains", "regex"] },
-    caseSensitive: { type: "boolean" }
+    type: {
+      const: "text",
+      description: "Must be 'text' for text pattern search."
+    },
+    pattern: {
+      type: "string",
+      description: "Text or regex pattern to match."
+    },
+    mode: {
+      enum: ["contains", "regex"],
+      description: "Match mode: 'contains' (substring) or 'regex'."
+    },
+    caseSensitive: {
+      type: "boolean",
+      description: "Case-sensitive matching. Default: false."
+    }
   }, ["type", "pattern"]);
   nodeSelectorSchema2 = objectSchema2({
-    type: { const: "node" },
-    nodeType: { enum: [...nodeTypeValues2] },
-    kind: { enum: ["block", "inline"] }
+    type: {
+      const: "node",
+      description: "Must be 'node' for node type search."
+    },
+    nodeType: {
+      enum: [...nodeTypeValues2],
+      description: "Block type to match (paragraph, heading, table, listItem, etc.)."
+    },
+    kind: {
+      enum: ["block", "inline"],
+      description: "Filter: 'block' or 'inline'."
+    }
   }, ["type"]);
   objectSchema2({ nodeType: { enum: [...nodeTypeValues2] } }, ["nodeType"]);
   objectSchema2({
@@ -95830,22 +95992,41 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
     "insideStart",
     "insideEnd"
   ] };
-  nestingPolicySchema2 = objectSchema2({ tables: { enum: ["forbid", "allow"] } });
+  nestingPolicySchema2 = {
+    ...objectSchema2({ tables: { enum: ["forbid", "allow"] } }),
+    description: "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables."
+  };
   objectSchema2({
-    target: textAddressSchema2,
-    value: { type: "string" },
+    target: {
+      ...textAddressSchema2,
+      description: "Insertion point: {kind:'text', blockId:'...', range:{start, end}}."
+    },
+    value: {
+      type: "string",
+      description: "Text content to insert."
+    },
     type: {
       type: "string",
       enum: [
         "text",
         "markdown",
         "html"
-      ]
+      ],
+      description: "Content format: 'text' (default), 'markdown', or 'html'."
     }
   }, ["value"]), objectSchema2({
-    target: blockNodeAddressSchema2,
-    content: sdFragmentSchema2,
-    placement: placementSchema2,
+    target: {
+      ...blockNodeAddressSchema2,
+      description: "Block address for structural insertion: {kind:'block', nodeType:'...', nodeId:'...'}."
+    },
+    content: {
+      ...sdFragmentSchema2,
+      description: "Document fragment to insert (structured content)."
+    },
+    placement: {
+      ...placementSchema2,
+      description: "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'."
+    },
     nestingPolicy: nestingPolicySchema2
   }, ["content"]);
   ({ ...objectSchema2({
@@ -96528,7 +96709,10 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
   }, ["modelVersion", "body"]), objectSchema2({
     nodeId: { type: "string" },
     nodeType: { enum: [...blockNodeTypeValues2] }
-  }, ["nodeId"]), objectSchema2({ unflattenLists: { type: "boolean" } }), objectSchema2({ markdown: { type: "string" } }, ["markdown"]), objectSchema2({
+  }, ["nodeId"]), objectSchema2({ unflattenLists: {
+    type: "boolean",
+    description: "When true, flattens nested list structures in output. Default: false."
+  } }), objectSchema2({ markdown: { type: "string" } }, ["markdown"]), objectSchema2({
     fragment: {},
     lossy: { type: "boolean" },
     diagnostics: arraySchema2(objectSchema2({
@@ -96552,15 +96736,36 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
     "fragment",
     "lossy",
     "diagnostics"
-  ]), receiptResultSchemaFor2("clearContent"), receiptFailureResultSchemaFor2("clearContent"), sdMutationResultSchemaFor2("insert"), sdMutationFailureSchemaFor2("insert"), { ...targetLocatorWithPayload2({ text: { type: "string" } }, ["text"]) }, objectSchema2({
-    target: { oneOf: [blockNodeAddressSchema2, selectionTargetSchema2] },
-    content: sdFragmentSchema2,
+  ]), receiptResultSchemaFor2("clearContent"), receiptFailureResultSchemaFor2("clearContent"), sdMutationResultSchemaFor2("insert"), sdMutationFailureSchemaFor2("insert"), { ...targetLocatorWithPayload2({ text: {
+    type: "string",
+    description: "Replacement text content."
+  } }, ["text"]) }, objectSchema2({
+    target: {
+      oneOf: [blockNodeAddressSchema2, selectionTargetSchema2],
+      description: "Target block or selection to replace."
+    },
+    content: {
+      ...sdFragmentSchema2,
+      description: "Document fragment to replace with (structured content)."
+    },
     nestingPolicy: nestingPolicySchema2
   }, ["target", "content"]), objectSchema2({
-    ref: { type: "string" },
-    content: sdFragmentSchema2,
+    ref: {
+      type: "string",
+      description: "Reference handle from a previous search result."
+    },
+    content: {
+      ...sdFragmentSchema2,
+      description: "Document fragment to replace with (structured content)."
+    },
     nestingPolicy: nestingPolicySchema2
-  }, ["ref", "content"]), sdMutationResultSchemaFor2("replace"), sdMutationFailureSchemaFor2("replace"), { ...targetLocatorWithPayload2({ behavior: deleteBehaviorSchema2 }) }, textMutationResultSchemaFor2("delete"), textMutationFailureSchemaFor2("delete"), { ...targetLocatorWithPayload2({ inline: buildInlineRunPatchSchema2() }, ["inline"]) }, textMutationResultSchemaFor2("format.apply"), textMutationFailureSchemaFor2("format.apply"), { ...formatInlineAliasOperationSchemas2 }, objectSchema2({
+  }, ["ref", "content"]), sdMutationResultSchemaFor2("replace"), sdMutationFailureSchemaFor2("replace"), { ...targetLocatorWithPayload2({ behavior: {
+    ...deleteBehaviorSchema2,
+    description: "Delete behavior: 'selection' (default) or 'exact'."
+  } }) }, textMutationResultSchemaFor2("delete"), textMutationFailureSchemaFor2("delete"), { ...targetLocatorWithPayload2({ inline: {
+    ...buildInlineRunPatchSchema2(),
+    description: "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold."
+  } }, ["inline"]) }, textMutationResultSchemaFor2("format.apply"), textMutationFailureSchemaFor2("format.apply"), { ...formatInlineAliasOperationSchemas2 }, objectSchema2({
     offset: {
       type: "number",
       minimum: 0
@@ -96673,35 +96878,45 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
     target: paragraphTargetSchema2,
     left: {
       type: "integer",
-      minimum: 0
+      minimum: 0,
+      description: "Left indentation in twips (1440 = 1 inch)."
     },
     right: {
       type: "integer",
-      minimum: 0
+      minimum: 0,
+      description: "Right indentation in twips (1440 = 1 inch)."
     },
     firstLine: {
       type: "integer",
-      minimum: 0
+      minimum: 0,
+      description: "First line indent in twips. Cannot be combined with hanging."
     },
     hanging: {
       type: "integer",
-      minimum: 0
+      minimum: 0,
+      description: "Hanging indent in twips. Cannot be combined with firstLine."
     }
   }, ["target"]) }, paragraphMutationResultSchemaFor2("format.paragraph.setIndentation"), paragraphMutationFailureSchemaFor2("format.paragraph.setIndentation"), objectSchema2({ target: paragraphTargetSchema2 }, ["target"]), paragraphMutationResultSchemaFor2("format.paragraph.clearIndentation"), paragraphMutationFailureSchemaFor2("format.paragraph.clearIndentation"), { ...objectSchema2({
     target: paragraphTargetSchema2,
     before: {
       type: "integer",
-      minimum: 0
+      minimum: 0,
+      description: "Space before paragraph in twips (20 twips = 1pt)."
     },
     after: {
       type: "integer",
-      minimum: 0
+      minimum: 0,
+      description: "Space after paragraph in twips (20 twips = 1pt)."
     },
     line: {
       type: "integer",
-      minimum: 1
+      minimum: 1,
+      description: "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule."
     },
-    lineRule: { enum: [...LINE_RULES2] }
+    lineRule: {
+      enum: [...LINE_RULES2],
+      description: "Line spacing rule. Required when 'line' is set."
+    }
   }, ["target"]) }, paragraphMutationResultSchemaFor2("format.paragraph.setSpacing"), paragraphMutationFailureSchemaFor2("format.paragraph.setSpacing"), objectSchema2({ target: paragraphTargetSchema2 }, ["target"]), paragraphMutationResultSchemaFor2("format.paragraph.clearSpacing"), paragraphMutationFailureSchemaFor2("format.paragraph.clearSpacing"), { ...objectSchema2({
     target: paragraphTargetSchema2,
     keepNext: { type: "boolean" },
@@ -96849,34 +97064,49 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
       failure: stylesFailureSchema
     };
   })(), objectSchema2({
-    at: { oneOf: [
-      objectSchema2({ kind: { const: "documentStart" } }, ["kind"]),
-      objectSchema2({ kind: { const: "documentEnd" } }, ["kind"]),
-      objectSchema2({
-        kind: { const: "before" },
-        target: blockNodeAddressSchema2
-      }, ["kind", "target"]),
-      objectSchema2({
-        kind: { const: "after" },
-        target: blockNodeAddressSchema2
-      }, ["kind", "target"])
-    ] },
-    text: { type: "string" }
+    at: {
+      description: "Position: {kind:'documentEnd'} to append, {kind:'documentStart'} to prepend, or {kind:'before'|'after', target:{kind:'block', nodeType:'...', nodeId:'...'}} for relative placement.",
+      oneOf: [
+        objectSchema2({ kind: { const: "documentStart" } }, ["kind"]),
+        objectSchema2({ kind: { const: "documentEnd" } }, ["kind"]),
+        objectSchema2({
+          kind: { const: "before" },
+          target: blockNodeAddressSchema2
+        }, ["kind", "target"]),
+        objectSchema2({
+          kind: { const: "after" },
+          target: blockNodeAddressSchema2
+        }, ["kind", "target"])
+      ]
+    },
+    text: {
+      type: "string",
+      description: "Paragraph text content."
+    }
   }), createParagraphResultSchemaFor2("create.paragraph"), createParagraphFailureSchemaFor2("create.paragraph"), objectSchema2({
-    level: headingLevelSchema2,
-    at: { oneOf: [
-      objectSchema2({ kind: { const: "documentStart" } }, ["kind"]),
-      objectSchema2({ kind: { const: "documentEnd" } }, ["kind"]),
-      objectSchema2({
-        kind: { const: "before" },
-        target: blockNodeAddressSchema2
-      }, ["kind", "target"]),
-      objectSchema2({
-        kind: { const: "after" },
-        target: blockNodeAddressSchema2
-      }, ["kind", "target"])
-    ] },
-    text: { type: "string" }
+    level: {
+      ...headingLevelSchema2,
+      description: "Heading level (1-6)."
+    },
+    at: {
+      description: "Position: {kind:'documentEnd'} to append, {kind:'documentStart'} to prepend, or {kind:'before'|'after', target:{kind:'block', nodeType:'...', nodeId:'...'}} for relative placement.",
+      oneOf: [
+        objectSchema2({ kind: { const: "documentStart" } }, ["kind"]),
+        objectSchema2({ kind: { const: "documentEnd" } }, ["kind"]),
+        objectSchema2({
+          kind: { const: "before" },
+          target: blockNodeAddressSchema2
+        }, ["kind", "target"]),
+        objectSchema2({
+          kind: { const: "after" },
+          target: blockNodeAddressSchema2
+        }, ["kind", "target"])
+      ]
+    },
+    text: {
+      type: "string",
+      description: "Heading text content."
+    }
   }, ["level"]), createHeadingResultSchemaFor2("create.heading"), createHeadingFailureSchemaFor2("create.heading"), objectSchema2({
     at: { oneOf: [
       objectSchema2({ kind: { const: "documentStart" } }, ["kind"]),
@@ -97037,10 +97267,19 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
     level: { type: "integer" },
     ordinal: { type: "integer" }
   }), objectSchema2({ address: listItemAddressSchema2 }, ["address"]), objectSchema2({
-    target: listItemAddressSchema2,
-    position: listInsertPositionSchema2,
-    text: { type: "string" }
-  }, ["target", "position"]), listsInsertResultSchemaFor2("lists.insert"), listsFailureSchemaFor2("lists.insert"), ref2("BlockAddress"), ref2("BlockAddressOrRange"), objectSchema2({
+    target: {
+      ...listItemAddressSchema2,
+      description: "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:'<id>'}."
+    },
+    position: {
+      ...listInsertPositionSchema2,
+      description: "Required. Insert position relative to target: 'before' or 'after'."
+    },
+    text: {
+      type: "string",
+      description: "Text content for the new list item."
+    }
+  }, ["target", "position"]), listsInsertResultSchemaFor2("lists.insert"), listsFailureSchemaFor2("lists.insert"), { ...ref2("BlockAddress") }, { ...ref2("BlockAddressOrRange") }, { ...listKindSchema2 }, objectSchema2({
     version: { const: 1 },
     levels: arraySchema2(objectSchema2({
       level: {
@@ -97244,7 +97483,10 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
   }, ["target", "preset"]), listsMutateItemResultSchemaFor2("lists.applyPreset"), listsFailureSchemaFor2("lists.applyPreset"), objectSchema2({
     target: listItemAddressSchema2,
     kind: { enum: ["ordered", "bullet"] },
-    continuity: { enum: ["preserve", "none"] }
+    continuity: {
+      enum: ["preserve", "none"],
+      description: "Numbering continuity: 'preserve' keeps numbering; 'none' restarts."
+    }
   }, ["target", "kind"]), listsMutateItemResultSchemaFor2("lists.setType"), listsFailureSchemaFor2("lists.setType"), (() => {
     const successSchema = objectSchema2({
       success: { const: true },
@@ -97540,45 +97782,98 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
     "level",
     "layout"
   ]), listsMutateItemResultSchemaFor2("lists.setLevelLayout"), listsFailureSchemaFor2("lists.setLevelLayout"), objectSchema2({
-    text: { type: "string" },
-    target: textAddressSchema2,
-    parentCommentId: { type: "string" }
+    text: {
+      type: "string",
+      description: "Comment text content."
+    },
+    target: {
+      ...textAddressSchema2,
+      description: "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}."
+    },
+    parentCommentId: {
+      type: "string",
+      description: "Parent comment ID for creating a threaded reply."
+    }
   }, ["text"]), receiptResultSchemaFor2("comments.create"), receiptFailureResultSchemaFor2("comments.create"), objectSchema2({
     commentId: { type: "string" },
-    text: { type: "string" },
+    text: {
+      type: "string",
+      description: "Updated comment text."
+    },
     target: textAddressSchema2,
-    status: { enum: ["resolved"] },
-    isInternal: { type: "boolean" }
+    status: {
+      enum: ["resolved"],
+      description: "Set comment status. Use 'resolved' to mark as resolved."
+    },
+    isInternal: {
+      type: "boolean",
+      description: "When true, marks the comment as internal (hidden from external collaborators)."
+    }
   }, ["commentId"]), receiptResultSchemaFor2("comments.patch"), receiptFailureResultSchemaFor2("comments.patch"), objectSchema2({ commentId: { type: "string" } }, ["commentId"]), receiptResultSchemaFor2("comments.delete"), receiptFailureResultSchemaFor2("comments.delete"), objectSchema2({ commentId: { type: "string" } }, ["commentId"]), objectSchema2({
-    includeResolved: { type: "boolean" },
-    limit: { type: "integer" },
-    offset: { type: "integer" }
+    includeResolved: {
+      type: "boolean",
+      description: "When true, includes resolved comments in results. Default: false."
+    },
+    limit: {
+      type: "integer",
+      description: "Maximum number of comments to return."
+    },
+    offset: {
+      type: "integer",
+      description: "Number of comments to skip for pagination."
+    }
   }), objectSchema2({
-    limit: { type: "integer" },
-    offset: { type: "integer" },
-    type: { enum: [
-      "insert",
-      "delete",
-      "format"
-    ] }
+    limit: {
+      type: "integer",
+      description: "Maximum number of tracked changes to return."
+    },
+    offset: {
+      type: "integer",
+      description: "Number of tracked changes to skip for pagination."
+    },
+    type: {
+      enum: [
+        "insert",
+        "delete",
+        "format"
+      ],
+      description: "Filter by change type: 'insert', 'delete', or 'format'."
+    }
   }), objectSchema2({ id: { type: "string" } }, ["id"]), objectSchema2({ id: { type: "string" } }, ["id"]), objectSchema2({ scope: { enum: ["all"] } }, ["scope"]), receiptResultSchemaFor2("trackChanges.decide"), receiptFailureResultSchemaFor2("trackChanges.decide"), objectSchema2({
-    select: { oneOf: [textSelectorSchema2, nodeSelectorSchema2] },
-    within: blockNodeAddressSchema2,
-    require: { enum: [
-      "any",
-      "first",
-      "exactlyOne",
-      "all"
-    ] },
-    mode: { enum: ["strict", "candidates"] },
-    includeNodes: { type: "boolean" },
+    select: {
+      description: "Search selector. Use {type:'text', pattern:'...'} for text search or {type:'node', nodeType:'paragraph'|'heading'|...} for node search.",
+      oneOf: [textSelectorSchema2, nodeSelectorSchema2]
+    },
+    within: {
+      ...blockNodeAddressSchema2,
+      description: "Limit search scope to within a specific block: {kind:'block', nodeType:'...', nodeId:'...'}."
+    },
+    require: {
+      enum: [
+        "any",
+        "first",
+        "exactlyOne",
+        "all"
+      ],
+      description: "Match cardinality: 'any' (all matches), 'first' (only first), 'exactlyOne' (fail if != 1), 'all' (fail if 0)."
+    },
+    mode: {
+      enum: ["strict", "candidates"],
+      description: "Search mode: 'strict' (default, exact matching) or 'candidates' (returns scored potential matches)."
+    },
+    includeNodes: {
+      type: "boolean",
+      description: "When true, includes full node data in results. Default: false."
+    },
     limit: {
       type: "integer",
-      minimum: 1
+      minimum: 1,
+      description: "Maximum number of matches to return."
     },
     offset: {
       type: "integer",
-      minimum: 0
+      minimum: 0,
+      description: "Number of matches to skip for pagination."
     }
   }, ["select"]), (() => {
     const textMatchItemSchema = discoveryItemSchema2({
@@ -97721,91 +98016,101 @@ var init_SuperConverter_BsjuwDIO_es = __esm(() => {
       setMarks: setMarksSchema
     }, ["mode"]) }, ["inline"]);
     const mutationsInputSchema = objectSchema2({
-      expectedRevision: { type: "string" },
+      expectedRevision: {
+        type: "string",
+        description: "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision."
+      },
       atomic: {
         const: true,
-        type: "boolean"
+        type: "boolean",
+        description: "Must be true. All steps execute as one atomic transaction."
       },
-      changeMode: { enum: ["direct", "tracked"] },
-      steps: arraySchema2({ oneOf: [
-        objectSchema2({
-          id: { type: "string" },
-          op: {
-            const: "text.rewrite",
-            type: "string"
-          },
-          where: stepWhereSchema,
-          args: objectSchema2({
-            replacement: replacementPayloadSchema,
-            style: stylePolicySchema
-          }, ["replacement"])
-        }, [
-          "id",
-          "op",
-          "where",
-          "args"
-        ]),
-        objectSchema2({
-          id: { type: "string" },
-          op: {
-            const: "text.insert",
-            type: "string"
-          },
-          where: insertWhereSchema,
-          args: objectSchema2({
-            position: { enum: ["before", "after"] },
-            content: objectSchema2({ text: { type: "string" } }, ["text"]),
-            style: insertStylePolicySchema
-          }, ["position", "content"])
-        }, [
-          "id",
-          "op",
-          "where",
-          "args"
-        ]),
-        objectSchema2({
-          id: { type: "string" },
-          op: {
-            const: "text.delete",
-            type: "string"
-          },
-          where: stepWhereSchema,
-          args: objectSchema2({ behavior: deleteBehaviorSchema2 })
-        }, [
-          "id",
-          "op",
-          "where",
-          "args"
-        ]),
-        objectSchema2({
-          id: { type: "string" },
-          op: {
-            const: "format.apply",
-            type: "string"
-          },
-          where: stepWhereSchema,
-          args: objectSchema2({ inline: buildInlineRunPatchSchema2() }, ["inline"])
-        }, [
-          "id",
-          "op",
-          "where",
-          "args"
-        ]),
-        objectSchema2({
-          id: { type: "string" },
-          op: {
-            const: "assert",
-            type: "string"
-          },
-          where: assertWhereSchema,
-          args: objectSchema2({ expectCount: { type: "number" } }, ["expectCount"])
-        }, [
-          "id",
-          "op",
-          "where",
-          "args"
-        ])
-      ] })
+      changeMode: {
+        enum: ["direct", "tracked"],
+        description: "Required. Use 'direct' for immediate edits or 'tracked' for suggestions. Must always be provided."
+      },
+      steps: {
+        ...arraySchema2({ oneOf: [
+          objectSchema2({
+            id: { type: "string" },
+            op: {
+              const: "text.rewrite",
+              type: "string"
+            },
+            where: stepWhereSchema,
+            args: objectSchema2({
+              replacement: replacementPayloadSchema,
+              style: stylePolicySchema
+            }, ["replacement"])
+          }, [
+            "id",
+            "op",
+            "where",
+            "args"
+          ]),
+          objectSchema2({
+            id: { type: "string" },
+            op: {
+              const: "text.insert",
+              type: "string"
+            },
+            where: insertWhereSchema,
+            args: objectSchema2({
+              position: { enum: ["before", "after"] },
+              content: objectSchema2({ text: { type: "string" } }, ["text"]),
+              style: insertStylePolicySchema
+            }, ["position", "content"])
+          }, [
+            "id",
+            "op",
+            "where",
+            "args"
+          ]),
+          objectSchema2({
+            id: { type: "string" },
+            op: {
+              const: "text.delete",
+              type: "string"
+            },
+            where: stepWhereSchema,
+            args: objectSchema2({ behavior: deleteBehaviorSchema2 })
+          }, [
+            "id",
+            "op",
+            "where",
+            "args"
+          ]),
+          objectSchema2({
+            id: { type: "string" },
+            op: {
+              const: "format.apply",
+              type: "string"
+            },
+            where: stepWhereSchema,
+            args: objectSchema2({ inline: buildInlineRunPatchSchema2() }, ["inline"])
+          }, [
+            "id",
+            "op",
+            "where",
+            "args"
+          ]),
+          objectSchema2({
+            id: { type: "string" },
+            op: {
+              const: "assert",
+              type: "string"
+            },
+            where: assertWhereSchema,
+            args: objectSchema2({ expectCount: { type: "number" } }, ["expectCount"])
+          }, [
+            "id",
+            "op",
+            "where",
+            "args"
+          ])
+        ] }),
+        description: "Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, or assert) and a 'where' targeting clause."
+      }
     }, [
       "atomic",
       "changeMode",
@@ -148508,7 +148813,7 @@ var init_remark_gfm_CjV8kaUy_es = __esm(() => {
   init_remark_gfm_z_sDF4ss_es();
 });
 
-// ../../packages/superdoc/dist/chunks/src-DH8mR7rX.es.js
+// ../../packages/superdoc/dist/chunks/src-Bf4fUvSx.es.js
 function deleteProps(obj, propOrProps) {
   const props = typeof propOrProps === "string" ? [propOrProps] : propOrProps;
   const removeNested = (target, pathParts, index2 = 0) => {
@@ -228674,9 +228979,9 @@ var Node$13 = class Node$14 {
     return false;
   return Boolean(checker(attrs));
 }, SuperToolbar, ICONS, TEXTS, tableActionsOptions;
-var init_src_DH8mR7rX_es = __esm(() => {
+var init_src_Bf4fUvSx_es = __esm(() => {
   init_rolldown_runtime_B2q5OVn9_es();
-  init_SuperConverter_BsjuwDIO_es();
+  init_SuperConverter_DarcJh0X_es();
   init_jszip_ChlR43oI_es();
   init_uuid_qzgm05fK_es();
   init_constants_ep1_Gwqi_es();
@@ -261979,8 +262284,8 @@ var init_zipper_DqXT7uTa_es = __esm(() => {
 
 // ../../packages/superdoc/dist/super-editor.es.js
 var init_super_editor_es = __esm(() => {
-  init_src_DH8mR7rX_es();
-  init_SuperConverter_BsjuwDIO_es();
+  init_src_Bf4fUvSx_es();
+  init_SuperConverter_DarcJh0X_es();
   init_jszip_ChlR43oI_es();
   init_xml_js_BtmJ6bNs_es();
   init_constants_ep1_Gwqi_es();
@@ -318451,40 +318756,43 @@ function isSimpleType2(schema, $defs) {
 }
 function jsonSchemaToTypeSpec(schema, $defs) {
   schema = resolveRef(schema, $defs);
-  if ("const" in schema)
-    return { const: schema.const };
-  if (schema.oneOf) {
-    return {
+  const desc = typeof schema.description === "string" ? schema.description : undefined;
+  let result2;
+  if ("const" in schema) {
+    result2 = { const: schema.const };
+  } else if (schema.oneOf) {
+    result2 = {
       oneOf: schema.oneOf.map((s2) => jsonSchemaToTypeSpec(s2, $defs))
     };
-  }
-  if (schema.enum && Array.isArray(schema.enum)) {
-    return {
+  } else if (schema.enum && Array.isArray(schema.enum)) {
+    result2 = {
       oneOf: schema.enum.map((v) => ({ const: v }))
     };
-  }
-  if (schema.type === "string")
-    return { type: "string" };
-  if (schema.type === "number" || schema.type === "integer")
-    return { type: "number" };
-  if (schema.type === "boolean")
-    return { type: "boolean" };
-  if (schema.type === "array") {
+  } else if (schema.type === "string") {
+    result2 = { type: "string" };
+  } else if (schema.type === "number" || schema.type === "integer") {
+    result2 = { type: "number" };
+  } else if (schema.type === "boolean") {
+    result2 = { type: "boolean" };
+  } else if (schema.type === "array") {
     const items2 = schema.items ?? {};
-    return { type: "array", items: jsonSchemaToTypeSpec(items2, $defs) };
-  }
-  if (schema.type === "object") {
+    result2 = { type: "array", items: jsonSchemaToTypeSpec(items2, $defs) };
+  } else if (schema.type === "object") {
     const properties = {};
     for (const [key2, propSchema] of Object.entries(schema.properties ?? {})) {
       properties[key2] = jsonSchemaToTypeSpec(propSchema, $defs);
     }
-    const result2 = { type: "object", properties };
+    result2 = { type: "object", properties };
     if (schema.required && Array.isArray(schema.required)) {
       result2.required = schema.required;
     }
-    return result2;
+  } else {
+    result2 = { type: "json" };
   }
-  return { type: "json" };
+  if (desc) {
+    result2.description = desc;
+  }
+  return result2;
 }
 function deriveParamsFromInputSchema(inputSchema, $defs) {
   const params4 = [];
@@ -318512,13 +318820,20 @@ function deriveParamsFromInputSchema(inputSchema, $defs) {
     const paramType = schemaToParamType(propSchema, $defs);
     const isComplex = !isSimpleType2(propSchema, $defs) && paramType === "json";
     const flagBase = camelToKebab4(name2);
+    const isRequired = required.has(name2);
     const param = {
       name: name2,
       kind: isComplex ? "jsonFlag" : "flag",
       flag: isComplex ? `${flagBase}-json` : flagBase,
       type: paramType,
-      required: required.has(name2)
+      required: isRequired
     };
+    const rawDesc = rawPropSchema.description;
+    const resolvedDesc = propSchema.description;
+    const desc = typeof rawDesc === "string" ? rawDesc : typeof resolvedDesc === "string" ? resolvedDesc : undefined;
+    if (desc) {
+      param.description = desc;
+    }
     if (AGENT_HIDDEN_PARAM_NAMES.has(name2)) {
       param.agentVisible = false;
     }
@@ -318572,9 +318887,9 @@ function buildDocBackedMetadata() {
     const envelope = envelopeParams(docApiId);
     const seenNames = new Set;
     const mergedParams = [];
-    for (const param of envelope) {
-      seenNames.add(param.name);
-      mergedParams.push(param);
+    for (const envelopeParam of envelope) {
+      seenNames.add(envelopeParam.name);
+      mergedParams.push(envelopeParam);
     }
     const overrides = PARAM_FLAG_OVERRIDES[cliOpId];
     const schemaOverrides = PARAM_SCHEMA_OVERRIDES[cliOpId];
@@ -318663,30 +318978,49 @@ function deriveOptionSpecs(operationId, params4) {
 var DOC_PARAM, SESSION_PARAM, OUT_PARAM, FORCE_PARAM, DRY_RUN_PARAM, CHANGE_MODE_PARAM, EXPECTED_REVISION_PARAM, USER_NAME_PARAM, USER_EMAIL_PARAM, AGENT_HIDDEN_PARAM_NAMES, OPERATION_CONSTRAINTS, PARAM_FLAG_OVERRIDES, PARAM_SCHEMA_OVERRIDES, PARAM_EXCLUSIONS, TEXT_TARGET_FLAT_PARAMS, INSERT_FLAT_PARAMS, LIST_TARGET_FLAT_PARAMS, FORMAT_OPERATION_IDS, EXTRA_CLI_PARAMS, CLI_ONLY_METADATA, CLI_OPERATION_METADATA, OPTION_FLAG_ALIASES, CLI_OPERATION_OPTION_SPECS;
 var init_operation_params = __esm(() => {
   init_src();
-  init_operation_set();
   init_commands();
-  DOC_PARAM = { name: "doc", kind: "doc", type: "string" };
-  SESSION_PARAM = { name: "sessionId", kind: "flag", flag: "session", type: "string" };
+  init_operation_set();
+  DOC_PARAM = {
+    name: "doc",
+    kind: "doc",
+    type: "string",
+    description: "Document path. Optional when a session is already open."
+  };
+  SESSION_PARAM = {
+    name: "sessionId",
+    kind: "flag",
+    flag: "session",
+    type: "string",
+    description: "Session ID for multi-session workflows. Optional when only one session is open."
+  };
   OUT_PARAM = { name: "out", kind: "flag", type: "string", agentVisible: false };
-  FORCE_PARAM = { name: "force", kind: "flag", type: "boolean" };
+  FORCE_PARAM = {
+    name: "force",
+    kind: "flag",
+    type: "boolean",
+    description: "Bypass confirmation checks."
+  };
   DRY_RUN_PARAM = {
     name: "dryRun",
     kind: "flag",
     flag: "dry-run",
-    type: "boolean"
+    type: "boolean",
+    description: "Preview the result without applying changes."
   };
   CHANGE_MODE_PARAM = {
     name: "changeMode",
     kind: "flag",
     flag: "change-mode",
     type: "string",
-    schema: { enum: ["direct", "tracked"] }
+    schema: { enum: ["direct", "tracked"] },
+    description: 'Edit mode: "direct" applies changes immediately, "tracked" records as suggestions.'
   };
   EXPECTED_REVISION_PARAM = {
     name: "expectedRevision",
     kind: "flag",
     flag: "expected-revision",
-    type: "number"
+    type: "number",
+    agentVisible: false
   };
   USER_NAME_PARAM = {
     name: "userName",
@@ -318742,94 +319076,325 @@ var init_operation_params = __esm(() => {
     "doc.find": new Set(["select"])
   };
   TEXT_TARGET_FLAT_PARAMS = [
-    { name: "blockId", kind: "flag", flag: "block-id", type: "string" },
-    { name: "start", kind: "flag", type: "number" },
-    { name: "end", kind: "flag", type: "number" }
+    { name: "blockId", kind: "flag", flag: "block-id", type: "string", description: "Block ID of the target paragraph." },
+    { name: "start", kind: "flag", type: "number", description: "Start offset within the block (character index)." },
+    { name: "end", kind: "flag", type: "number", description: "End offset within the block (character index)." }
   ];
   INSERT_FLAT_PARAMS = [
-    { name: "blockId", kind: "flag", flag: "block-id", type: "string" },
-    { name: "offset", kind: "flag", type: "number" }
+    { name: "blockId", kind: "flag", flag: "block-id", type: "string", description: "Block ID of the target paragraph." },
+    { name: "offset", kind: "flag", type: "number", description: "Character offset within the block for insertion." }
   ];
   LIST_TARGET_FLAT_PARAMS = [
-    { name: "nodeId", kind: "flag", flag: "node-id", type: "string" }
+    { name: "nodeId", kind: "flag", flag: "node-id", type: "string", description: "Node ID of the target list item." }
   ];
   FORMAT_OPERATION_IDS = CLI_DOC_OPERATIONS.filter((operationId) => operationId.startsWith("format."));
   EXTRA_CLI_PARAMS = {
     "doc.find": [
-      { name: "type", kind: "flag", type: "string" },
-      { name: "nodeType", kind: "flag", flag: "node-type", type: "string" },
-      { name: "kind", kind: "flag", type: "string" },
-      { name: "pattern", kind: "flag", type: "string" },
-      { name: "mode", kind: "flag", type: "string" },
-      { name: "caseSensitive", kind: "flag", flag: "case-sensitive", type: "boolean" },
-      { name: "select", kind: "jsonFlag", flag: "select-json", type: "json" },
-      { name: "query", kind: "jsonFlag", flag: "query-json", type: "json" }
+      {
+        name: "type",
+        kind: "flag",
+        type: "string",
+        description: "Selector type: 'text' for text search or 'node' for node type search."
+      },
+      {
+        name: "nodeType",
+        kind: "flag",
+        flag: "node-type",
+        type: "string",
+        description: "Node type to match (paragraph, heading, table, listItem, etc.)."
+      },
+      { name: "kind", kind: "flag", type: "string", description: "Filter: 'block' or 'inline'." },
+      { name: "pattern", kind: "flag", type: "string", description: "Text or regex pattern to match." },
+      { name: "mode", kind: "flag", type: "string", description: "Match mode: 'contains' (substring) or 'regex'." },
+      {
+        name: "caseSensitive",
+        kind: "flag",
+        flag: "case-sensitive",
+        type: "boolean",
+        description: "Case-sensitive matching. Default: false."
+      },
+      {
+        name: "select",
+        kind: "jsonFlag",
+        flag: "select-json",
+        type: "json",
+        description: "Search selector as JSON: {type:'text', pattern:'...'} or {type:'node', nodeType:'...'}."
+      },
+      { name: "query", kind: "jsonFlag", flag: "query-json", type: "json", description: "Query filter as JSON object." }
     ],
     "doc.lists.list": [{ name: "query", kind: "jsonFlag", flag: "query-json", type: "json" }],
-    "doc.getNode": [{ name: "address", kind: "jsonFlag", flag: "address-json", type: "json" }],
+    "doc.getNode": [
+      {
+        name: "address",
+        kind: "jsonFlag",
+        flag: "address-json",
+        type: "json",
+        description: "Node address to retrieve (block or inline address object)."
+      }
+    ],
     "doc.insert": [...INSERT_FLAT_PARAMS],
     "doc.replace": [...TEXT_TARGET_FLAT_PARAMS],
     "doc.delete": [...TEXT_TARGET_FLAT_PARAMS],
     "doc.styles.apply": [
-      { name: "target", kind: "jsonFlag", flag: "target-json", type: "json" },
-      { name: "patch", kind: "jsonFlag", flag: "patch-json", type: "json" }
+      {
+        name: "target",
+        kind: "jsonFlag",
+        flag: "target-json",
+        type: "json",
+        description: "Text address or block address to apply styles to."
+      },
+      {
+        name: "patch",
+        kind: "jsonFlag",
+        flag: "patch-json",
+        type: "json",
+        description: "Style patch object with run and/or paragraph properties to apply."
+      }
     ],
     "doc.comments.create": [...TEXT_TARGET_FLAT_PARAMS],
     "doc.comments.patch": [...TEXT_TARGET_FLAT_PARAMS],
     "doc.lists.insert": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
     "doc.lists.indent": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
     "doc.lists.outdent": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
-    "doc.lists.create": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.attach": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
+    "doc.lists.create": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.attach": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
     "doc.lists.detach": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
-    "doc.lists.join": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.canJoin": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
+    "doc.lists.join": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.canJoin": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
     "doc.lists.separate": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
     "doc.lists.setLevel": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
     "doc.lists.setValue": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
     "doc.lists.continuePrevious": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
     "doc.lists.canContinuePrevious": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
-    "doc.lists.setLevelRestart": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.applyTemplate": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.applyPreset": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.captureTemplate": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.setLevelNumbering": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.setLevelBullet": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.setLevelPictureBullet": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.setLevelAlignment": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.setLevelIndents": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.setLevelTrailingCharacter": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.setLevelMarkerFont": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.lists.clearLevelOverrides": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
+    "doc.lists.setLevelRestart": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.applyTemplate": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.applyPreset": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.captureTemplate": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.setLevelNumbering": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.setLevelBullet": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.setLevelPictureBullet": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.setLevelAlignment": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.setLevelIndents": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.setLevelTrailingCharacter": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.setLevelMarkerFont": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
+    "doc.lists.clearLevelOverrides": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      }
+    ],
     "doc.lists.convertToText": [
-      { name: "input", kind: "jsonFlag", flag: "input-json", type: "json" },
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Operation input as JSON object."
+      },
       ...LIST_TARGET_FLAT_PARAMS
     ],
     "doc.blocks.list": [
@@ -318838,15 +319403,49 @@ var init_operation_params = __esm(() => {
       { name: "nodeTypes", kind: "jsonFlag", flag: "node-types-json", type: "json" }
     ],
     "doc.blocks.delete": [
-      { name: "nodeType", kind: "flag", flag: "node-type", type: "string" },
-      { name: "nodeId", kind: "flag", flag: "node-id", type: "string" }
+      {
+        name: "nodeType",
+        kind: "flag",
+        flag: "node-type",
+        type: "string",
+        description: "Block type of the node to delete."
+      },
+      { name: "nodeId", kind: "flag", flag: "node-id", type: "string", description: "Node ID of the block to delete." }
     ],
     "doc.blocks.deleteRange": [
-      { name: "start", kind: "jsonFlag", flag: "start-json", type: "json" },
-      { name: "end", kind: "jsonFlag", flag: "end-json", type: "json" }
+      {
+        name: "start",
+        kind: "jsonFlag",
+        flag: "start-json",
+        type: "json",
+        description: "Block address of the first block in the range to delete."
+      },
+      {
+        name: "end",
+        kind: "jsonFlag",
+        flag: "end-json",
+        type: "json",
+        description: "Block address of the last block in the range to delete."
+      }
+    ],
+    "doc.create.paragraph": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Full paragraph input as JSON (alternative to individual text/at params)."
+      }
     ],
-    "doc.create.paragraph": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }],
-    "doc.create.heading": [{ name: "input", kind: "jsonFlag", flag: "input-json", type: "json" }]
+    "doc.create.heading": [
+      {
+        name: "input",
+        kind: "jsonFlag",
+        flag: "input-json",
+        type: "json",
+        description: "Full heading input as JSON (alternative to individual text/level/at params)."
+      }
+    ]
   };
   for (const operationId of FORMAT_OPERATION_IDS) {
     EXTRA_CLI_PARAMS[`doc.${operationId}`] = [...TEXT_TARGET_FLAT_PARAMS];