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

package/dist/index.js

@@ -1155,8 +1155,17 @@ function camelToKebab(value) {
   return value.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
 }
 function formatInlineAliasDescription(key) {
+  if (key === "rtl") {
+    return "Set or clear the `rtl` inline run property on the target text range. This does not change paragraph direction; use `format.paragraph.setDirection` for paragraph-level RTL.";
+  }
   return `Set or clear the \`${key}\` inline run property on the target text range.`;
 }
+function formatInlineAliasExpectedResult(key) {
+  if (key === "rtl") {
+    return "Returns a TextMutationReceipt confirming only the inline run property patch was applied to the target range; paragraph direction is unchanged.";
+  }
+  return "Returns a TextMutationReceipt confirming the inline run property patch was applied to the target range.";
+}
 function projectFromDefinitions(fn) {
   return Object.fromEntries(OPERATION_IDS.map((id) => [id, fn(id, OPERATION_DEFINITIONS[id])]));
 }
@@ -1234,7 +1243,7 @@ var init_operation_definitions = __esm(() => {
     const definition = {
       memberPath: operationId,
       description: formatInlineAliasDescription(entry.key),
-      expectedResult: "Returns a TextMutationReceipt confirming the inline run property patch was applied to the target range.",
+      expectedResult: formatInlineAliasExpectedResult(entry.key),
       requiresDocumentContext: true,
       metadata: mutationOperation({
         idempotency: "conditional",
@@ -2175,6 +2184,38 @@ var init_operation_definitions = __esm(() => {
       referenceDocPath: "format/paragraph/clear-shading.mdx",
       referenceGroup: "format.paragraph"
     },
+    "format.paragraph.setDirection": {
+      memberPath: "format.paragraph.setDirection",
+      description: "Set paragraph base direction (LTR or RTL via w:bidi). Optionally align text to match.",
+      expectedResult: "Returns a ParagraphMutationResult; reports NO_OP if the direction already matches.",
+      requiresDocumentContext: true,
+      metadata: mutationOperation({
+        idempotency: "conditional",
+        supportsDryRun: true,
+        supportsTrackedMode: false,
+        possibleFailureCodes: ["NO_OP"],
+        throws: T_PARAGRAPH_MUTATION
+      }),
+      referenceDocPath: "format/paragraph/set-direction.mdx",
+      referenceGroup: "format.paragraph",
+      intentGroup: "format",
+      intentAction: "set_direction"
+    },
+    "format.paragraph.clearDirection": {
+      memberPath: "format.paragraph.clearDirection",
+      description: "Remove explicit paragraph direction, reverting to inherited or default (LTR).",
+      expectedResult: "Returns a ParagraphMutationResult; reports NO_OP if no direction is set.",
+      requiresDocumentContext: true,
+      metadata: mutationOperation({
+        idempotency: "conditional",
+        supportsDryRun: true,
+        supportsTrackedMode: false,
+        possibleFailureCodes: ["NO_OP"],
+        throws: T_PARAGRAPH_MUTATION
+      }),
+      referenceDocPath: "format/paragraph/clear-direction.mdx",
+      referenceGroup: "format.paragraph"
+    },
     "lists.list": {
       memberPath: "lists.list",
       description: "List all list nodes in the document, optionally filtered by scope.",
@@ -6125,7 +6166,7 @@ function executeWrite(adapter, request, options) {
 }
 
 // ../../packages/document-api/src/paragraphs/paragraphs.types.ts
-var PARAGRAPH_ALIGNMENTS, TAB_STOP_ALIGNMENTS, TAB_STOP_LEADERS, BORDER_SIDES, CLEAR_BORDER_SIDES, LINE_RULES;
+var PARAGRAPH_ALIGNMENTS, TAB_STOP_ALIGNMENTS, TAB_STOP_LEADERS, BORDER_SIDES, CLEAR_BORDER_SIDES, LINE_RULES, PARAGRAPH_DIRECTIONS, ALIGNMENT_POLICIES;
 var init_paragraphs_types = __esm(() => {
   PARAGRAPH_ALIGNMENTS = ["left", "center", "right", "justify"];
   TAB_STOP_ALIGNMENTS = ["left", "center", "right", "decimal", "bar"];
@@ -6133,6 +6174,8 @@ var init_paragraphs_types = __esm(() => {
   BORDER_SIDES = ["top", "bottom", "left", "right", "between", "bar"];
   CLEAR_BORDER_SIDES = ["top", "bottom", "left", "right", "between", "bar", "all"];
   LINE_RULES = ["auto", "exact", "atLeast"];
+  PARAGRAPH_DIRECTIONS = ["ltr", "rtl"];
+  ALIGNMENT_POLICIES = ["preserve", "matchDirection"];
 });
 
 // ../../packages/document-api/src/paragraphs/paragraphs.ts
@@ -6388,6 +6431,23 @@ function validateClearShading(input) {
   assertParagraphTarget(input, "format.paragraph.clearShading");
   assertNoUnknownFields(input, CLEAR_SHADING_KEYS, "format.paragraph.clearShading");
 }
+function validateSetDirection(input) {
+  const op = "format.paragraph.setDirection";
+  assertParagraphTarget(input, op);
+  assertNoUnknownFields(input, SET_DIRECTION_KEYS, op);
+  const rec = input;
+  if (rec.direction === undefined) {
+    throw new DocumentApiValidationError("INVALID_INPUT", `${op} requires a direction field.`);
+  }
+  assertOneOf(rec.direction, "direction", PARAGRAPH_DIRECTIONS, op);
+  if (rec.alignmentPolicy !== undefined) {
+    assertOneOf(rec.alignmentPolicy, "alignmentPolicy", ALIGNMENT_POLICIES, op);
+  }
+}
+function validateClearDirection(input) {
+  assertParagraphTarget(input, "format.paragraph.clearDirection");
+  assertNoUnknownFields(input, CLEAR_DIRECTION_KEYS, "format.paragraph.clearDirection");
+}
 function executeParagraphsSetStyle(adapter, input, options) {
   validateSetStyle(input);
   return adapter.setStyle(input, normalizeMutationOptions(options));
@@ -6464,7 +6524,15 @@ function executeParagraphsClearShading(adapter, input, options) {
   validateClearShading(input);
   return adapter.clearShading(input, normalizeMutationOptions(options));
 }
-var PARAGRAPH_BLOCK_TYPES, SET_STYLE_KEYS, CLEAR_STYLE_KEYS, RESET_DIRECT_FORMATTING_KEYS, SET_ALIGNMENT_KEYS, CLEAR_ALIGNMENT_KEYS, SET_INDENTATION_KEYS, CLEAR_INDENTATION_KEYS, SET_SPACING_KEYS, CLEAR_SPACING_KEYS, SET_KEEP_OPTIONS_KEYS, SET_OUTLINE_LEVEL_KEYS, SET_FLOW_OPTIONS_KEYS, SET_TAB_STOP_KEYS, CLEAR_TAB_STOP_KEYS, CLEAR_ALL_TAB_STOPS_KEYS, SET_BORDER_KEYS, CLEAR_BORDER_KEYS, SET_SHADING_KEYS, CLEAR_SHADING_KEYS;
+function executeParagraphsSetDirection(adapter, input, options) {
+  validateSetDirection(input);
+  return adapter.setDirection(input, normalizeMutationOptions(options));
+}
+function executeParagraphsClearDirection(adapter, input, options) {
+  validateClearDirection(input);
+  return adapter.clearDirection(input, normalizeMutationOptions(options));
+}
+var PARAGRAPH_BLOCK_TYPES, SET_STYLE_KEYS, CLEAR_STYLE_KEYS, RESET_DIRECT_FORMATTING_KEYS, SET_ALIGNMENT_KEYS, CLEAR_ALIGNMENT_KEYS, SET_INDENTATION_KEYS, CLEAR_INDENTATION_KEYS, SET_SPACING_KEYS, CLEAR_SPACING_KEYS, SET_KEEP_OPTIONS_KEYS, SET_OUTLINE_LEVEL_KEYS, SET_FLOW_OPTIONS_KEYS, SET_TAB_STOP_KEYS, CLEAR_TAB_STOP_KEYS, CLEAR_ALL_TAB_STOPS_KEYS, SET_BORDER_KEYS, CLEAR_BORDER_KEYS, SET_SHADING_KEYS, CLEAR_SHADING_KEYS, SET_DIRECTION_KEYS, CLEAR_DIRECTION_KEYS;
 var init_paragraphs = __esm(() => {
   init_errors2();
   init_validation_primitives();
@@ -6490,6 +6558,8 @@ var init_paragraphs = __esm(() => {
   CLEAR_BORDER_KEYS = new Set(["target", "side"]);
   SET_SHADING_KEYS = new Set(["target", "fill", "color", "pattern"]);
   CLEAR_SHADING_KEYS = new Set(["target"]);
+  SET_DIRECTION_KEYS = new Set(["target", "direction", "alignmentPolicy"]);
+  CLEAR_DIRECTION_KEYS = new Set(["target"]);
 });
 
 // ../../packages/document-api/src/inline-semantics/token-sets.ts
@@ -7184,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])
     ]
   };
 }
@@ -7837,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",
@@ -8121,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] }
@@ -8510,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"])
     ]
@@ -8996,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" }
     },
@@ -9033,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"])
             ]
@@ -9057,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,
@@ -9065,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,
@@ -9191,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"] }
@@ -9213,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"] },
@@ -9342,6 +9478,22 @@ var init_schemas = __esm(() => {
       success: paragraphMutationSuccessSchema,
       failure: paragraphMutationFailureSchemaFor("format.paragraph.clearShading")
     },
+    "format.paragraph.setDirection": {
+      input: objectSchema({
+        target: paragraphTargetSchema,
+        direction: { type: "string", enum: ["ltr", "rtl"] },
+        alignmentPolicy: { type: "string", enum: ["preserve", "matchDirection"] }
+      }, ["target", "direction"]),
+      output: paragraphMutationResultSchemaFor("format.paragraph.setDirection"),
+      success: paragraphMutationSuccessSchema,
+      failure: paragraphMutationFailureSchemaFor("format.paragraph.setDirection")
+    },
+    "format.paragraph.clearDirection": {
+      input: objectSchema({ target: paragraphTargetSchema }, ["target"]),
+      output: paragraphMutationResultSchemaFor("format.paragraph.clearDirection"),
+      success: paragraphMutationSuccessSchema,
+      failure: paragraphMutationFailureSchemaFor("format.paragraph.clearDirection")
+    },
     "styles.apply": (() => {
       const runInputSchema = objectSchema({
         target: objectSchema({ scope: { const: "docDefaults" }, channel: { const: "run" } }, ["scope", "channel"]),
@@ -9388,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"]),
@@ -9401,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,
@@ -9409,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"]),
@@ -9424,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,
@@ -9670,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,
@@ -9682,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",
@@ -9699,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 },
@@ -9964,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,
@@ -10212,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,
@@ -10223,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,
@@ -10244,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
     },
@@ -10283,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({
@@ -10421,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" },
@@ -14112,6 +14333,8 @@ function buildDispatchTable(api) {
     "format.paragraph.clearBorder": (input, options) => api.format.paragraph.clearBorder(input, options),
     "format.paragraph.setShading": (input, options) => api.format.paragraph.setShading(input, options),
     "format.paragraph.clearShading": (input, options) => api.format.paragraph.clearShading(input, options),
+    "format.paragraph.setDirection": (input, options) => api.format.paragraph.setDirection(input, options),
+    "format.paragraph.clearDirection": (input, options) => api.format.paragraph.clearDirection(input, options),
     "styles.apply": (input, options) => api.styles.apply(input, options),
     "create.paragraph": (input, options) => api.create.paragraph(input, options),
     "create.heading": (input, options) => api.create.heading(input, options),
@@ -16370,6 +16593,12 @@ function createDocumentApi(adapters) {
         },
         clearShading(input, options) {
           return executeParagraphsClearShading(adapters.paragraphs, input, options);
+        },
+        setDirection(input, options) {
+          return executeParagraphsSetDirection(adapters.paragraphs, input, options);
+        },
+        clearDirection(input, options) {
+          return executeParagraphsClearDirection(adapters.paragraphs, input, options);
         }
       }
     },
@@ -39693,7 +39922,7 @@ var init_remark_gfm_z_sDF4ss_es = __esm(() => {
   emptyOptions2 = {};
 });
 
-// ../../packages/superdoc/dist/chunks/SuperConverter-htgbtdmP.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")
@@ -40726,8 +40955,15 @@ function camelToKebab3(value) {
   return value.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
 }
 function formatInlineAliasDescription2(key) {
+  if (key === "rtl")
+    return "Set or clear the `rtl` inline run property on the target text range. This does not change paragraph direction; use `format.paragraph.setDirection` for paragraph-level RTL.";
   return `Set or clear the \`${key}\` inline run property on the target text range.`;
 }
+function formatInlineAliasExpectedResult2(key) {
+  if (key === "rtl")
+    return "Returns a TextMutationReceipt confirming only the inline run property patch was applied to the target range; paragraph direction is unchanged.";
+  return "Returns a TextMutationReceipt confirming the inline run property patch was applied to the target range.";
+}
 function projectFromDefinitions2(fn) {
   return Object.fromEntries(OPERATION_IDS2.map((id) => [id, fn(id, OPERATION_DEFINITIONS2[id])]));
 }
@@ -41006,6 +41242,21 @@ function validateClearShading2(input) {
   assertParagraphTarget2(input, "format.paragraph.clearShading");
   assertNoUnknownFields3(input, CLEAR_SHADING_KEYS2, "format.paragraph.clearShading");
 }
+function validateSetDirection2(input) {
+  const op = "format.paragraph.setDirection";
+  assertParagraphTarget2(input, op);
+  assertNoUnknownFields3(input, SET_DIRECTION_KEYS2, op);
+  const rec = input;
+  if (rec.direction === undefined)
+    throw new DocumentApiValidationError2("INVALID_INPUT", `${op} requires a direction field.`);
+  assertOneOf$2(rec.direction, "direction", PARAGRAPH_DIRECTIONS2, op);
+  if (rec.alignmentPolicy !== undefined)
+    assertOneOf$2(rec.alignmentPolicy, "alignmentPolicy", ALIGNMENT_POLICIES2, op);
+}
+function validateClearDirection2(input) {
+  assertParagraphTarget2(input, "format.paragraph.clearDirection");
+  assertNoUnknownFields3(input, CLEAR_DIRECTION_KEYS2, "format.paragraph.clearDirection");
+}
 function executeParagraphsSetStyle2(adapter, input, options) {
   validateSetStyle2(input);
   return adapter.setStyle(input, normalizeMutationOptions2(options));
@@ -41082,6 +41333,14 @@ function executeParagraphsClearShading2(adapter, input, options) {
   validateClearShading2(input);
   return adapter.clearShading(input, normalizeMutationOptions2(options));
 }
+function executeParagraphsSetDirection2(adapter, input, options) {
+  validateSetDirection2(input);
+  return adapter.setDirection(input, normalizeMutationOptions2(options));
+}
+function executeParagraphsClearDirection2(adapter, input, options) {
+  validateClearDirection2(input);
+  return adapter.clearDirection(input, normalizeMutationOptions2(options));
+}
 function getPropertyDefinition2(key, channel) {
   return PROPERTY_INDEX2.get(`${channel}:${key}`);
 }
@@ -41392,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])] };
 }
@@ -43476,6 +43741,8 @@ function buildDispatchTable2(api) {
     "format.paragraph.clearBorder": (input, options) => api.format.paragraph.clearBorder(input, options),
     "format.paragraph.setShading": (input, options) => api.format.paragraph.setShading(input, options),
     "format.paragraph.clearShading": (input, options) => api.format.paragraph.clearShading(input, options),
+    "format.paragraph.setDirection": (input, options) => api.format.paragraph.setDirection(input, options),
+    "format.paragraph.clearDirection": (input, options) => api.format.paragraph.clearDirection(input, options),
     "styles.apply": (input, options) => api.styles.apply(input, options),
     "create.paragraph": (input, options) => api.create.paragraph(input, options),
     "create.heading": (input, options) => api.create.heading(input, options),
@@ -45418,6 +45685,12 @@ function createDocumentApi2(adapters) {
         },
         clearShading(input, options) {
           return executeParagraphsClearShading2(adapters.paragraphs, input, options);
+        },
+        setDirection(input, options) {
+          return executeParagraphsSetDirection2(adapters.paragraphs, input, options);
+        },
+        clearDirection(input, options) {
+          return executeParagraphsClearDirection2(adapters.paragraphs, input, options);
         }
       }
     },
@@ -71693,7 +71966,7 @@ var isRegExp = (value) => {
   tracked: false,
   carrier: runAttributeCarrier2(runPropertyKey ?? key),
   schema
-}), INLINE_PROPERTY_REGISTRY2, INLINE_PROPERTY_KEY_SET2, INLINE_PROPERTY_BY_KEY2, UNDERLINE_OBJECT_ALLOWED_KEYS2, SHADING_ALLOWED_KEYS2, BORDER_ALLOWED_KEYS2, FIT_TEXT_ALLOWED_KEYS2, LANG_ALLOWED_KEYS2, RFONTS_ALLOWED_KEYS2, EAST_ASIAN_LAYOUT_ALLOWED_KEYS2, STYLISTIC_SET_ALLOWED_KEYS2, VERT_ALIGN_VALUES2, PROPERTY_VALIDATOR_MAP2, NONE_FAILURES2, NONE_THROWS2, T_NOT_FOUND2, T_NOT_FOUND_CAPABLE2, T_PLAN_ENGINE2, T_NOT_FOUND_COMMAND2, T_IMAGE_COMMAND2, T_CC_READ2, T_CC_MUTATION2, T_CC_TYPED2, T_CC_TYPED_READ2, T_CC_RAW2, T_QUERY_MATCH2, T_SECTION_CREATE2, T_SECTION_READ2, T_PARAGRAPH_MUTATION2, T_SECTION_MUTATION2, T_SECTION_SETTINGS_MUTATION2, T_HEADER_FOOTER_MUTATION2, T_REF_READ_LIST2, T_REF_MUTATION2, T_REF_MUTATION_REMOVE2, T_REF_INSERT2, FORMAT_INLINE_ALIAS_OPERATION_DEFINITIONS2, OPERATION_DEFINITIONS2, OPERATION_IDS2, COMMAND_CATALOG3, PARAGRAPH_ALIGNMENTS2, TAB_STOP_ALIGNMENTS2, TAB_STOP_LEADERS2, BORDER_SIDES2, CLEAR_BORDER_SIDES2, LINE_RULES2, PARAGRAPH_BLOCK_TYPES2, SET_STYLE_KEYS2, CLEAR_STYLE_KEYS2, RESET_DIRECT_FORMATTING_KEYS2, SET_ALIGNMENT_KEYS2, CLEAR_ALIGNMENT_KEYS2, SET_INDENTATION_KEYS2, CLEAR_INDENTATION_KEYS2, SET_SPACING_KEYS2, CLEAR_SPACING_KEYS2, SET_KEEP_OPTIONS_KEYS2, SET_OUTLINE_LEVEL_KEYS2, SET_FLOW_OPTIONS_KEYS2, SET_TAB_STOP_KEYS2, CLEAR_TAB_STOP_KEYS2, CLEAR_ALL_TAB_STOPS_KEYS2, SET_BORDER_KEYS2, CLEAR_BORDER_KEYS2, SET_SHADING_KEYS2, CLEAR_SHADING_KEYS2, ST_ON_OFF_ON_VALUES2, ST_ON_OFF_OFF_VALUES2, ST_UNDERLINE_VALUES2, ST_UNDERLINE_VALUE_SET2, ST_VERTICAL_ALIGN_RUN2, ST_EM2, ST_TEXT_ALIGNMENT2, ST_TEXT_DIRECTION2, ST_TEXTBOX_TIGHT_WRAP2, ST_TEXT_TRANSFORM2, ST_JUSTIFICATION2, FONT_FAMILY_SCHEMA2, COLOR_SCHEMA2, SPACING_SCHEMA2, INDENT_SCHEMA2, UNDERLINE_SCHEMA2, BORDER_PROPERTIES_SCHEMA2, SHADING_SCHEMA2, LANG_SCHEMA2, EAST_ASIAN_LAYOUT_SCHEMA2, FIT_TEXT_SCHEMA2, NUMBERING_PROPERTIES_SCHEMA2, FRAME_PR_SCHEMA2, PARAGRAPH_BORDERS_SCHEMA2, TAB_STOP_SCHEMA2, PROPERTY_REGISTRY2, ALLOWED_KEYS_BY_CHANNEL2, PROPERTY_INDEX2, EXCLUDED_KEYS2, INPUT_ALLOWED_KEYS2, TARGET_ALLOWED_KEYS2, OPTIONS_ALLOWED_KEYS2, VALID_CHANNELS2, Z_ORDER_RELATIVE_HEIGHT_MAX2 = 4294967295, nodeTypeValues2, blockNodeTypeValues2, deletableBlockNodeTypeValues2, inlineNodeTypeValues2, rangeSchema2, textAddressSchema2, textTargetSchema2, blockNodeAddressSchema2, deletableBlockNodeAddressSchema2, tableAddressSchema2, tableRowAddressSchema2, tableCellAddressSchema2, tableOrCellAddressSchema2, paragraphAddressSchema2, headingAddressSchema2, listItemAddressSchema2, paragraphTargetSchema2, sectionAddressSchema2, nodeAddressSchema2, commentAddressSchema2, trackedChangeAddressSchema2, entityAddressSchema2, selectionTargetSchema2, deleteBehaviorSchema2, resolvedHandleSchema2, pageInfoSchema2, receiptSuccessSchema2, textMutationRangeSchema2, textMutationResolutionSchema2, textMutationSuccessSchema2, matchBlockSchema2, trackChangeRefSchema2, createParagraphSuccessSchema2, createHeadingSuccessSchema2, headingLevelSchema2, listsInsertSuccessSchema2, listsMutateItemSuccessSchema2, textSelectorSchema2, nodeSelectorSchema2, sdMutationResolutionSchema2, sdMutationSuccessSchema2, documentInfoCountsSchema2, documentInfoOutlineItemSchema2, documentInfoCapabilitiesSchema2, listKindSchema2, listInsertPositionSchema2, sectionBreakTypeSchema2, sectionOrientationSchema2, sectionVerticalAlignSchema2, sectionDirectionSchema2, sectionHeaderFooterKindSchema2, sectionHeaderFooterVariantSchema2, sectionLineNumberRestartSchema2, sectionPageNumberFormatSchema2, sectionRangeDomainSchema2, sectionPageMarginsSchema2, sectionHeaderFooterMarginsSchema2, sectionPageSetupSchema2, sectionColumnsSchema2, sectionLineNumberingSchema2, sectionPageNumberingSchema2, sectionHeaderFooterRefsSchema2, sectionBorderSpecSchema2, sectionPageBordersSchema2, sectionMutationSuccessSchema2, documentMutationSuccessSchema2, paragraphMutationTargetSchema2, paragraphMutationSuccessSchema2, createSectionBreakSuccessSchema2, capabilityReasonsSchema2, capabilityFlagSchema2, operationRuntimeCapabilitySchema2, operationCapabilitiesSchema2, inlinePropertyCapabilitySchema2, formatCapabilitiesSchema2, planEngineCapabilitiesSchema2, nullableTableBorderSpecSchema2, sdFragmentSchema2, placementSchema2, nestingPolicySchema2, tableCreateLocationSchema2, formatInlineAliasOperationSchemas2, tocMutationFailureSchema2, tocMutationSuccessSchema2, tocEntryMutationFailureSchema2, tocEntryMutationSuccessSchema2, hyperlinkTargetSchema2, hyperlinkReadPropertiesSchema2, hyperlinkSpecSchema2, hyperlinkPatchSchema2, hyperlinkDomainSchema2, hyperlinkMutationSuccessSchema2, hyperlinkMutationFailureSchema2, contentControlTargetSchema2, contentControlMutationSuccessSchema2, contentControlMutationFailureSchema2, ccListResultSchema2, ccInfoSchema2, refFailureSchema2, bookmarkAddressSchema2, bookmarkMutation2, footnoteAddressSchema2, footnoteConfigScopeSchema2, footnoteNumberingSchema2, footnoteMutation2, footnoteConfig2, crossRefAddressSchema2, crossRefTargetSchema2, crossRefDisplaySchema2, crossRefMutation2, indexAddressSchema2, indexEntryAddressSchema2, indexConfigSchema2, indexEntryDataSchema2, indexEntryPatchSchema2, indexMutation2, indexEntryMutation2, captionAddressSchema2, captionMutation2, captionConfig2, fieldAddressSchema2, fieldMutation2, citationAddressSchema2, citationSourceAddressSchema2, bibliographyAddressSchema2, citationMutation2, citationSourceMutation2, bibliographyMutation2, citationPersonSchema2, citationSourceFieldsSchema2, tocCreateLocationSchema2, authoritiesAddressSchema2, authorityEntryAddressSchema2, authoritiesConfigSchema2, authorityEntryDataSchema2, authorityEntryPatchSchema2, authoritiesMutation2, authorityEntryMutation2, diffCoverageSchema2, diffSummarySchema2, diffSnapshotSchema2, diffPayloadSchema2, GROUP_METADATA2, STEP_OP_CATALOG_UNFROZEN2, PUBLIC_STEP_OP_CATALOG_UNFROZEN2, PUBLIC_MUTATION_STEP_OP_IDS2, PUBLIC_MUTATION_STEP_OP_SET2, CAPABILITY_REASON_CODES, VALID_EDGE_VALUES2, VALID_EDGE_NODE_TYPES2, VALID_DOCUMENT_EDGES2, VALID_REF_BOUNDARIES2, VALID_ANCHOR_KINDS2, RESOLVE_RANGE_ALLOWED_KEYS2, CREATE_COMMENT_ALLOWED_KEYS2, PATCH_COMMENT_ALLOWED_KEYS2, STYLE_APPLY_INPUT_ALLOWED_KEYS2, INLINE_ALIAS_INPUT_ALLOWED_KEYS2, DELETE_INPUT_ALLOWED_KEYS2, VALID_BEHAVIORS2, CONTENT_KIND_SET2, INLINE_KIND_SET2, LEGACY_TOP_LEVEL_TYPES2, LEGACY_INSERT_ALLOWED_KEYS2, STRUCTURAL_INSERT_ALLOWED_KEYS2, VALID_INSERT_TYPES2, TEXT_REPLACE_ALLOWED_KEYS2, STRUCTURAL_REPLACE_ALLOWED_KEYS2, SECTION_BREAK_TYPES$1, SUPPORTED_DELETE_NODE_TYPES2, REJECTED_DELETE_NODE_TYPES2, VALID_BLOCK_NODE_TYPES2, SNAPSHOT_VERSION2 = "sd-diff-snapshot/v1", PAYLOAD_VERSION2 = "sd-diff-payload/v1", VALID_STYLE_OPTION_FLAGS2, TABLE_BORDER_COLOR_PATTERN2, VALID_APPLY_TO_VALUES2, VALID_BORDER_EDGE_KEYS2, HEADER_FOOTER_KINDS$1, HEADER_FOOTER_VARIANTS$1, DEFAULT_SECTIONS_LIST_LIMIT2 = 250, SECTION_BREAK_TYPES3, SECTION_ORIENTATIONS2, SECTION_VERTICAL_ALIGNS2, SECTION_DIRECTIONS2, HEADER_FOOTER_KINDS3, HEADER_FOOTER_VARIANTS3, LINE_NUMBER_RESTARTS2, PAGE_NUMBER_FORMATS2, PAGE_BORDER_DISPLAYS2, PAGE_BORDER_OFFSET_FROM_VALUES2, PAGE_BORDER_Z_ORDER_VALUES2, VALID_WRAP_TYPES2, VALID_WRAP_SIDES2, VALID_IMAGE_SIZE_UNITS2, PATCH_FIELDS2, ADAPTER_GATED_PREFIXES2, _buffers, _defaultCollectionId = null, _nextCollectionId = 1, generateV2HandlerEntity = (handlerName, translator$216) => ({
+}), INLINE_PROPERTY_REGISTRY2, INLINE_PROPERTY_KEY_SET2, INLINE_PROPERTY_BY_KEY2, UNDERLINE_OBJECT_ALLOWED_KEYS2, SHADING_ALLOWED_KEYS2, BORDER_ALLOWED_KEYS2, FIT_TEXT_ALLOWED_KEYS2, LANG_ALLOWED_KEYS2, RFONTS_ALLOWED_KEYS2, EAST_ASIAN_LAYOUT_ALLOWED_KEYS2, STYLISTIC_SET_ALLOWED_KEYS2, VERT_ALIGN_VALUES2, PROPERTY_VALIDATOR_MAP2, NONE_FAILURES2, NONE_THROWS2, T_NOT_FOUND2, T_NOT_FOUND_CAPABLE2, T_PLAN_ENGINE2, T_NOT_FOUND_COMMAND2, T_IMAGE_COMMAND2, T_CC_READ2, T_CC_MUTATION2, T_CC_TYPED2, T_CC_TYPED_READ2, T_CC_RAW2, T_QUERY_MATCH2, T_SECTION_CREATE2, T_SECTION_READ2, T_PARAGRAPH_MUTATION2, T_SECTION_MUTATION2, T_SECTION_SETTINGS_MUTATION2, T_HEADER_FOOTER_MUTATION2, T_REF_READ_LIST2, T_REF_MUTATION2, T_REF_MUTATION_REMOVE2, T_REF_INSERT2, FORMAT_INLINE_ALIAS_OPERATION_DEFINITIONS2, OPERATION_DEFINITIONS2, OPERATION_IDS2, COMMAND_CATALOG3, PARAGRAPH_ALIGNMENTS2, TAB_STOP_ALIGNMENTS2, TAB_STOP_LEADERS2, BORDER_SIDES2, CLEAR_BORDER_SIDES2, LINE_RULES2, PARAGRAPH_DIRECTIONS2, ALIGNMENT_POLICIES2, PARAGRAPH_BLOCK_TYPES2, SET_STYLE_KEYS2, CLEAR_STYLE_KEYS2, RESET_DIRECT_FORMATTING_KEYS2, SET_ALIGNMENT_KEYS2, CLEAR_ALIGNMENT_KEYS2, SET_INDENTATION_KEYS2, CLEAR_INDENTATION_KEYS2, SET_SPACING_KEYS2, CLEAR_SPACING_KEYS2, SET_KEEP_OPTIONS_KEYS2, SET_OUTLINE_LEVEL_KEYS2, SET_FLOW_OPTIONS_KEYS2, SET_TAB_STOP_KEYS2, CLEAR_TAB_STOP_KEYS2, CLEAR_ALL_TAB_STOPS_KEYS2, SET_BORDER_KEYS2, CLEAR_BORDER_KEYS2, SET_SHADING_KEYS2, CLEAR_SHADING_KEYS2, SET_DIRECTION_KEYS2, CLEAR_DIRECTION_KEYS2, ST_ON_OFF_ON_VALUES2, ST_ON_OFF_OFF_VALUES2, ST_UNDERLINE_VALUES2, ST_UNDERLINE_VALUE_SET2, ST_VERTICAL_ALIGN_RUN2, ST_EM2, ST_TEXT_ALIGNMENT2, ST_TEXT_DIRECTION2, ST_TEXTBOX_TIGHT_WRAP2, ST_TEXT_TRANSFORM2, ST_JUSTIFICATION2, FONT_FAMILY_SCHEMA2, COLOR_SCHEMA2, SPACING_SCHEMA2, INDENT_SCHEMA2, UNDERLINE_SCHEMA2, BORDER_PROPERTIES_SCHEMA2, SHADING_SCHEMA2, LANG_SCHEMA2, EAST_ASIAN_LAYOUT_SCHEMA2, FIT_TEXT_SCHEMA2, NUMBERING_PROPERTIES_SCHEMA2, FRAME_PR_SCHEMA2, PARAGRAPH_BORDERS_SCHEMA2, TAB_STOP_SCHEMA2, PROPERTY_REGISTRY2, ALLOWED_KEYS_BY_CHANNEL2, PROPERTY_INDEX2, EXCLUDED_KEYS2, INPUT_ALLOWED_KEYS2, TARGET_ALLOWED_KEYS2, OPTIONS_ALLOWED_KEYS2, VALID_CHANNELS2, Z_ORDER_RELATIVE_HEIGHT_MAX2 = 4294967295, nodeTypeValues2, blockNodeTypeValues2, deletableBlockNodeTypeValues2, inlineNodeTypeValues2, rangeSchema2, textAddressSchema2, textTargetSchema2, blockNodeAddressSchema2, deletableBlockNodeAddressSchema2, tableAddressSchema2, tableRowAddressSchema2, tableCellAddressSchema2, tableOrCellAddressSchema2, paragraphAddressSchema2, headingAddressSchema2, listItemAddressSchema2, paragraphTargetSchema2, sectionAddressSchema2, nodeAddressSchema2, commentAddressSchema2, trackedChangeAddressSchema2, entityAddressSchema2, selectionTargetSchema2, deleteBehaviorSchema2, resolvedHandleSchema2, pageInfoSchema2, receiptSuccessSchema2, textMutationRangeSchema2, textMutationResolutionSchema2, textMutationSuccessSchema2, matchBlockSchema2, trackChangeRefSchema2, createParagraphSuccessSchema2, createHeadingSuccessSchema2, headingLevelSchema2, listsInsertSuccessSchema2, listsMutateItemSuccessSchema2, textSelectorSchema2, nodeSelectorSchema2, sdMutationResolutionSchema2, sdMutationSuccessSchema2, documentInfoCountsSchema2, documentInfoOutlineItemSchema2, documentInfoCapabilitiesSchema2, listKindSchema2, listInsertPositionSchema2, sectionBreakTypeSchema2, sectionOrientationSchema2, sectionVerticalAlignSchema2, sectionDirectionSchema2, sectionHeaderFooterKindSchema2, sectionHeaderFooterVariantSchema2, sectionLineNumberRestartSchema2, sectionPageNumberFormatSchema2, sectionRangeDomainSchema2, sectionPageMarginsSchema2, sectionHeaderFooterMarginsSchema2, sectionPageSetupSchema2, sectionColumnsSchema2, sectionLineNumberingSchema2, sectionPageNumberingSchema2, sectionHeaderFooterRefsSchema2, sectionBorderSpecSchema2, sectionPageBordersSchema2, sectionMutationSuccessSchema2, documentMutationSuccessSchema2, paragraphMutationTargetSchema2, paragraphMutationSuccessSchema2, createSectionBreakSuccessSchema2, capabilityReasonsSchema2, capabilityFlagSchema2, operationRuntimeCapabilitySchema2, operationCapabilitiesSchema2, inlinePropertyCapabilitySchema2, formatCapabilitiesSchema2, planEngineCapabilitiesSchema2, nullableTableBorderSpecSchema2, sdFragmentSchema2, placementSchema2, nestingPolicySchema2, tableCreateLocationSchema2, formatInlineAliasOperationSchemas2, tocMutationFailureSchema2, tocMutationSuccessSchema2, tocEntryMutationFailureSchema2, tocEntryMutationSuccessSchema2, hyperlinkTargetSchema2, hyperlinkReadPropertiesSchema2, hyperlinkSpecSchema2, hyperlinkPatchSchema2, hyperlinkDomainSchema2, hyperlinkMutationSuccessSchema2, hyperlinkMutationFailureSchema2, contentControlTargetSchema2, contentControlMutationSuccessSchema2, contentControlMutationFailureSchema2, ccListResultSchema2, ccInfoSchema2, refFailureSchema2, bookmarkAddressSchema2, bookmarkMutation2, footnoteAddressSchema2, footnoteConfigScopeSchema2, footnoteNumberingSchema2, footnoteMutation2, footnoteConfig2, crossRefAddressSchema2, crossRefTargetSchema2, crossRefDisplaySchema2, crossRefMutation2, indexAddressSchema2, indexEntryAddressSchema2, indexConfigSchema2, indexEntryDataSchema2, indexEntryPatchSchema2, indexMutation2, indexEntryMutation2, captionAddressSchema2, captionMutation2, captionConfig2, fieldAddressSchema2, fieldMutation2, citationAddressSchema2, citationSourceAddressSchema2, bibliographyAddressSchema2, citationMutation2, citationSourceMutation2, bibliographyMutation2, citationPersonSchema2, citationSourceFieldsSchema2, tocCreateLocationSchema2, authoritiesAddressSchema2, authorityEntryAddressSchema2, authoritiesConfigSchema2, authorityEntryDataSchema2, authorityEntryPatchSchema2, authoritiesMutation2, authorityEntryMutation2, diffCoverageSchema2, diffSummarySchema2, diffSnapshotSchema2, diffPayloadSchema2, GROUP_METADATA2, STEP_OP_CATALOG_UNFROZEN2, PUBLIC_STEP_OP_CATALOG_UNFROZEN2, PUBLIC_MUTATION_STEP_OP_IDS2, PUBLIC_MUTATION_STEP_OP_SET2, CAPABILITY_REASON_CODES, VALID_EDGE_VALUES2, VALID_EDGE_NODE_TYPES2, VALID_DOCUMENT_EDGES2, VALID_REF_BOUNDARIES2, VALID_ANCHOR_KINDS2, RESOLVE_RANGE_ALLOWED_KEYS2, CREATE_COMMENT_ALLOWED_KEYS2, PATCH_COMMENT_ALLOWED_KEYS2, STYLE_APPLY_INPUT_ALLOWED_KEYS2, INLINE_ALIAS_INPUT_ALLOWED_KEYS2, DELETE_INPUT_ALLOWED_KEYS2, VALID_BEHAVIORS2, CONTENT_KIND_SET2, INLINE_KIND_SET2, LEGACY_TOP_LEVEL_TYPES2, LEGACY_INSERT_ALLOWED_KEYS2, STRUCTURAL_INSERT_ALLOWED_KEYS2, VALID_INSERT_TYPES2, TEXT_REPLACE_ALLOWED_KEYS2, STRUCTURAL_REPLACE_ALLOWED_KEYS2, SECTION_BREAK_TYPES$1, SUPPORTED_DELETE_NODE_TYPES2, REJECTED_DELETE_NODE_TYPES2, VALID_BLOCK_NODE_TYPES2, SNAPSHOT_VERSION2 = "sd-diff-snapshot/v1", PAYLOAD_VERSION2 = "sd-diff-payload/v1", VALID_STYLE_OPTION_FLAGS2, TABLE_BORDER_COLOR_PATTERN2, VALID_APPLY_TO_VALUES2, VALID_BORDER_EDGE_KEYS2, HEADER_FOOTER_KINDS$1, HEADER_FOOTER_VARIANTS$1, DEFAULT_SECTIONS_LIST_LIMIT2 = 250, SECTION_BREAK_TYPES3, SECTION_ORIENTATIONS2, SECTION_VERTICAL_ALIGNS2, SECTION_DIRECTIONS2, HEADER_FOOTER_KINDS3, HEADER_FOOTER_VARIANTS3, LINE_NUMBER_RESTARTS2, PAGE_NUMBER_FORMATS2, PAGE_BORDER_DISPLAYS2, PAGE_BORDER_OFFSET_FROM_VALUES2, PAGE_BORDER_Z_ORDER_VALUES2, VALID_WRAP_TYPES2, VALID_WRAP_SIDES2, VALID_IMAGE_SIZE_UNITS2, PATCH_FIELDS2, ADAPTER_GATED_PREFIXES2, _buffers, _defaultCollectionId = null, _nextCollectionId = 1, generateV2HandlerEntity = (handlerName, translator$216) => ({
   handlerName,
   handler: (params) => {
     const { nodes } = params;
@@ -85724,7 +85997,7 @@ var isRegExp = (value) => {
       state.kern = kernNode.attributes["w:val"];
   }
 }, SuperConverter;
-var init_SuperConverter_htgbtdmP_es = __esm(() => {
+var init_SuperConverter_DarcJh0X_es = __esm(() => {
   init_rolldown_runtime_B2q5OVn9_es();
   init_jszip_ChlR43oI_es();
   init_xml_js_BtmJ6bNs_es();
@@ -88704,7 +88977,7 @@ var init_SuperConverter_htgbtdmP_es = __esm(() => {
     return [operationId, {
       memberPath: operationId,
       description: formatInlineAliasDescription2(entry.key),
-      expectedResult: "Returns a TextMutationReceipt confirming the inline run property patch was applied to the target range.",
+      expectedResult: formatInlineAliasExpectedResult2(entry.key),
       requiresDocumentContext: true,
       metadata: mutationOperation2({
         idempotency: "conditional",
@@ -89729,6 +90002,38 @@ var init_SuperConverter_htgbtdmP_es = __esm(() => {
       referenceDocPath: "format/paragraph/clear-shading.mdx",
       referenceGroup: "format.paragraph"
     },
+    "format.paragraph.setDirection": {
+      memberPath: "format.paragraph.setDirection",
+      description: "Set paragraph base direction (LTR or RTL via w:bidi). Optionally align text to match.",
+      expectedResult: "Returns a ParagraphMutationResult; reports NO_OP if the direction already matches.",
+      requiresDocumentContext: true,
+      metadata: mutationOperation2({
+        idempotency: "conditional",
+        supportsDryRun: true,
+        supportsTrackedMode: false,
+        possibleFailureCodes: ["NO_OP"],
+        throws: T_PARAGRAPH_MUTATION2
+      }),
+      referenceDocPath: "format/paragraph/set-direction.mdx",
+      referenceGroup: "format.paragraph",
+      intentGroup: "format",
+      intentAction: "set_direction"
+    },
+    "format.paragraph.clearDirection": {
+      memberPath: "format.paragraph.clearDirection",
+      description: "Remove explicit paragraph direction, reverting to inherited or default (LTR).",
+      expectedResult: "Returns a ParagraphMutationResult; reports NO_OP if no direction is set.",
+      requiresDocumentContext: true,
+      metadata: mutationOperation2({
+        idempotency: "conditional",
+        supportsDryRun: true,
+        supportsTrackedMode: false,
+        possibleFailureCodes: ["NO_OP"],
+        throws: T_PARAGRAPH_MUTATION2
+      }),
+      referenceDocPath: "format/paragraph/clear-direction.mdx",
+      referenceGroup: "format.paragraph"
+    },
     "lists.list": {
       memberPath: "lists.list",
       description: "List all list nodes in the document, optionally filtered by scope.",
@@ -93936,6 +94241,8 @@ var init_SuperConverter_htgbtdmP_es = __esm(() => {
     "exact",
     "atLeast"
   ];
+  PARAGRAPH_DIRECTIONS2 = ["ltr", "rtl"];
+  ALIGNMENT_POLICIES2 = ["preserve", "matchDirection"];
   PARAGRAPH_BLOCK_TYPES2 = new Set([
     "paragraph",
     "heading",
@@ -93999,6 +94306,12 @@ var init_SuperConverter_htgbtdmP_es = __esm(() => {
     "pattern"
   ]);
   CLEAR_SHADING_KEYS2 = new Set(["target"]);
+  SET_DIRECTION_KEYS2 = new Set([
+    "target",
+    "direction",
+    "alignmentPolicy"
+  ]);
+  CLEAR_DIRECTION_KEYS2 = new Set(["target"]);
   ST_ON_OFF_ON_VALUES2 = new Set([
     "true",
     "1",
@@ -95094,15 +95407,36 @@ var init_SuperConverter_htgbtdmP_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({
@@ -95658,22 +95992,41 @@ var init_SuperConverter_htgbtdmP_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({
@@ -96356,7 +96709,10 @@ var init_SuperConverter_htgbtdmP_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({
@@ -96380,15 +96736,36 @@ var init_SuperConverter_htgbtdmP_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
@@ -96501,35 +96878,45 @@ var init_SuperConverter_htgbtdmP_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" },
@@ -96605,7 +96992,17 @@ var init_SuperConverter_htgbtdmP_es = __esm(() => {
       type: "string",
       minLength: 1
     }
-  }, ["target"]) }, paragraphMutationResultSchemaFor2("format.paragraph.setShading"), paragraphMutationFailureSchemaFor2("format.paragraph.setShading"), objectSchema2({ target: paragraphTargetSchema2 }, ["target"]), paragraphMutationResultSchemaFor2("format.paragraph.clearShading"), paragraphMutationFailureSchemaFor2("format.paragraph.clearShading"), (() => {
+  }, ["target"]) }, paragraphMutationResultSchemaFor2("format.paragraph.setShading"), paragraphMutationFailureSchemaFor2("format.paragraph.setShading"), objectSchema2({ target: paragraphTargetSchema2 }, ["target"]), paragraphMutationResultSchemaFor2("format.paragraph.clearShading"), paragraphMutationFailureSchemaFor2("format.paragraph.clearShading"), objectSchema2({
+    target: paragraphTargetSchema2,
+    direction: {
+      type: "string",
+      enum: ["ltr", "rtl"]
+    },
+    alignmentPolicy: {
+      type: "string",
+      enum: ["preserve", "matchDirection"]
+    }
+  }, ["target", "direction"]), paragraphMutationResultSchemaFor2("format.paragraph.setDirection"), paragraphMutationFailureSchemaFor2("format.paragraph.setDirection"), objectSchema2({ target: paragraphTargetSchema2 }, ["target"]), paragraphMutationResultSchemaFor2("format.paragraph.clearDirection"), paragraphMutationFailureSchemaFor2("format.paragraph.clearDirection"), (() => {
     const runInputSchema = objectSchema2({
       target: objectSchema2({
         scope: { const: "docDefaults" },
@@ -96667,34 +97064,49 @@ var init_SuperConverter_htgbtdmP_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"]),
@@ -96855,10 +97267,19 @@ var init_SuperConverter_htgbtdmP_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: {
@@ -97062,7 +97483,10 @@ var init_SuperConverter_htgbtdmP_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 },
@@ -97358,45 +97782,98 @@ var init_SuperConverter_htgbtdmP_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({
@@ -97539,91 +98016,101 @@ var init_SuperConverter_htgbtdmP_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",
@@ -148326,7 +148813,7 @@ var init_remark_gfm_CjV8kaUy_es = __esm(() => {
   init_remark_gfm_z_sDF4ss_es();
 });
 
-// ../../packages/superdoc/dist/chunks/src-D2teG0gz.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) => {
@@ -153993,8 +154480,8 @@ function extractParagraphProps(attrs) {
     props.shading = ppAny.shading;
     hasProps = true;
   }
-  if (ppAny.bidi !== undefined) {
-    props.bidi = ppAny.bidi;
+  if (ppAny.rightToLeft !== undefined) {
+    props.bidi = ppAny.rightToLeft;
     hasProps = true;
   }
   if (ppAny.markRunProps) {
@@ -159198,7 +159685,7 @@ function buildParagraphProperties(styleRef, props) {
   if (props.shading)
     result.shading = props.shading;
   if (props.bidi !== undefined)
-    result.bidi = props.bidi;
+    result.rightToLeft = props.bidi;
   if (props.outlineLevel !== undefined)
     result.outlineLevel = props.outlineLevel;
   if (props.markRunProps)
@@ -162000,6 +162487,24 @@ function paragraphsClearShadingWrapper(editor, input2, options) {
     return result;
   }, options);
 }
+function paragraphsSetDirectionWrapper(editor, input2, options) {
+  rejectTrackedMode("format.paragraph.setDirection", options);
+  return mutateParagraphProperties(editor, resolveParagraphBlock(editor, input2.target), "format.paragraph.setDirection", input2.target, (pPr) => {
+    const result = { ...pPr };
+    result.rightToLeft = input2.direction === "rtl";
+    if (input2.alignmentPolicy === "matchDirection")
+      result.justification = input2.direction === "rtl" ? "right" : "left";
+    return result;
+  }, options);
+}
+function paragraphsClearDirectionWrapper(editor, input2, options) {
+  rejectTrackedMode("format.paragraph.clearDirection", options);
+  return mutateParagraphProperties(editor, resolveParagraphBlock(editor, input2.target), "format.paragraph.clearDirection", input2.target, (pPr) => {
+    const result = { ...pPr };
+    delete result.rightToLeft;
+    return result;
+  }, options);
+}
 function buildTrackChangeInfo(editor, change) {
   const excerpt = normalizeExcerpt(editor.state.doc.textBetween(change.from, change.to, " ", ""));
   const type = resolveTrackedChangeType(change);
@@ -179972,7 +180477,9 @@ function assembleDocumentApiAdapters(editor) {
       setBorder: (input2, options) => paragraphsSetBorderWrapper(editor, input2, options),
       clearBorder: (input2, options) => paragraphsClearBorderWrapper(editor, input2, options),
       setShading: (input2, options) => paragraphsSetShadingWrapper(editor, input2, options),
-      clearShading: (input2, options) => paragraphsClearShadingWrapper(editor, input2, options)
+      clearShading: (input2, options) => paragraphsClearShadingWrapper(editor, input2, options),
+      setDirection: (input2, options) => paragraphsSetDirectionWrapper(editor, input2, options),
+      clearDirection: (input2, options) => paragraphsClearDirectionWrapper(editor, input2, options)
     },
     trackChanges: {
       list: (input2) => trackChangesListWrapper(editor, input2),
@@ -215914,7 +216421,8 @@ var Node$13 = class Node$14 {
     keepNext: resolvedParagraphProperties.keepNext,
     keepLines: resolvedParagraphProperties.keepLines,
     floatAlignment,
-    pageBreakBefore: resolvedParagraphProperties.pageBreakBefore
+    pageBreakBefore: resolvedParagraphProperties.pageBreakBefore,
+    direction: resolvedParagraphProperties.rightToLeft ? "rtl" : undefined
   };
   if (normalizedNumberingProperties && normalizedListRendering)
     paragraphAttrs.wordLayout = computeWordParagraphLayout({
@@ -228471,9 +228979,9 @@ var Node$13 = class Node$14 {
     return false;
   return Boolean(checker(attrs));
 }, SuperToolbar, ICONS, TEXTS, tableActionsOptions;
-var init_src_D2teG0gz_es = __esm(() => {
+var init_src_Bf4fUvSx_es = __esm(() => {
   init_rolldown_runtime_B2q5OVn9_es();
-  init_SuperConverter_htgbtdmP_es();
+  init_SuperConverter_DarcJh0X_es();
   init_jszip_ChlR43oI_es();
   init_uuid_qzgm05fK_es();
   init_constants_ep1_Gwqi_es();
@@ -261776,8 +262284,8 @@ var init_zipper_DqXT7uTa_es = __esm(() => {
 
 // ../../packages/superdoc/dist/super-editor.es.js
 var init_super_editor_es = __esm(() => {
-  init_src_D2teG0gz_es();
-  init_SuperConverter_htgbtdmP_es();
+  init_src_Bf4fUvSx_es();
+  init_SuperConverter_DarcJh0X_es();
   init_jszip_ChlR43oI_es();
   init_xml_js_BtmJ6bNs_es();
   init_constants_ep1_Gwqi_es();
@@ -318248,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 = [];
@@ -318309,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;
     }
@@ -318369,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];
@@ -318460,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",
@@ -318539,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": [
@@ -318635,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];