@superdoc-dev/cli 0.5.0-next.15 → 0.5.0-next.16

package/dist/index.js

@@ -141,6 +141,7 @@ function parseGlobalArgs(argv) {
   let prettyFlag = false;
   let timeoutMs;
   let sessionId;
+  let quiet = false;
   let help = false;
   let version2 = false;
   const rest = [];
@@ -162,6 +163,10 @@ function parseGlobalArgs(argv) {
       help = true;
       continue;
     }
+    if (token === "--quiet") {
+      quiet = true;
+      continue;
+    }
     if (token === "--version" || token === "-v") {
       version2 = true;
       continue;
@@ -221,6 +226,7 @@ function parseGlobalArgs(argv) {
       output,
       timeoutMs,
       sessionId,
+      quiet,
       help,
       version: version2
     },
@@ -42278,6 +42284,42 @@ var init_cli_only_operation_definitions = __esm(() => {
         required: ["contextId", "closed"]
       }
     },
+    insertTab: {
+      category: "core",
+      description: "Insert a real Word tab node at a collapsed text insertion point. Accepts the same target/ref shortcuts as insert, but only for point inserts.",
+      requiresDocumentContext: false,
+      tokenOverride: ["insert", "tab"],
+      sdkMetadata: { mutates: true, idempotency: "non-idempotent", supportsTrackedMode: false, supportsDryRun: false },
+      outputSchema: {
+        type: "object",
+        properties: {
+          document: { type: "object" },
+          receipt: { type: "object" },
+          inserted: { type: "object" },
+          context: { type: "object" },
+          output: { type: "object" }
+        },
+        required: ["receipt", "inserted"]
+      }
+    },
+    insertLineBreak: {
+      category: "core",
+      description: "Insert a real Word line-break node at a collapsed text insertion point. Accepts the same target/ref shortcuts as insert, but only for point inserts.",
+      requiresDocumentContext: false,
+      tokenOverride: ["insert", "line-break"],
+      sdkMetadata: { mutates: true, idempotency: "non-idempotent", supportsTrackedMode: false, supportsDryRun: false },
+      outputSchema: {
+        type: "object",
+        properties: {
+          document: { type: "object" },
+          receipt: { type: "object" },
+          inserted: { type: "object" },
+          context: { type: "object" },
+          output: { type: "object" }
+        },
+        required: ["receipt", "inserted"]
+      }
+    },
     status: {
       category: "session",
       description: "Show the current session status and document metadata.",
@@ -42482,6 +42524,8 @@ var init_types4 = __esm(() => {
     "open",
     "save",
     "close",
+    "insertTab",
+    "insertLineBreak",
     "status",
     "describe",
     "describeCommand",
@@ -172449,7 +172493,7 @@ var init_remark_gfm_CjV8kaUy_es = __esm(() => {
   init_remark_gfm_z_sDF4ss_es();
 });
 
-// ../../packages/superdoc/dist/chunks/src-sOP3agXO.es.js
+// ../../packages/superdoc/dist/chunks/src-CeG3wOI4.es.js
 function deleteProps(obj, propOrProps) {
   const props = typeof propOrProps === "string" ? [propOrProps] : propOrProps;
   const removeNested = (target, pathParts, index2 = 0) => {
@@ -243359,11 +243403,16 @@ var Node$13 = class Node$14 {
     });
     return Object.fromEntries(markEntries);
   }
-}, Commands, handleEnter = (editor) => {
+}, Commands, dispatchHistoryBoundary = (view) => {
+  const tr = view?.state?.tr;
+  if (!tr)
+    return;
+  view.dispatch?.(closeHistory(tr));
+}, handleEnter = (editor) => {
   const { view } = editor;
-  view?.dispatch?.(closeHistory(view?.state?.tr));
+  dispatchHistoryBoundary(view);
   return editor.commands.first(({ commands: commands$1 }) => [
-    () => commands$1.splitRunToParagraph(),
+    () => commands$1.splitRunToParagraph?.() ?? false,
     () => commands$1.newlineInCode(),
     () => commands$1.createParagraphNear(),
     () => commands$1.liftEmptyBlock(),
@@ -243371,7 +243420,7 @@ var Node$13 = class Node$14 {
   ]);
 }, handleBackspace = (editor) => {
   const { view } = editor;
-  view?.dispatch?.(closeHistory(view?.state?.tr));
+  dispatchHistoryBoundary(view);
   return editor.commands.first(({ commands: commands$1, tr }) => [
     () => commands$1.undoInputRule(),
     () => {
@@ -243389,7 +243438,7 @@ var Node$13 = class Node$14 {
   ]);
 }, handleDelete2 = (editor) => {
   const { view } = editor;
-  view?.dispatch?.(closeHistory(view?.state?.tr));
+  dispatchHistoryBoundary(view);
   return editor.commands.first(({ commands: commands$1 }) => [
     () => commands$1.deleteSkipEmptyRun(),
     () => commands$1.deleteNextToRun(),
@@ -253853,7 +253902,7 @@ var Node$13 = class Node$14 {
     return;
   console.log(...args$1);
 }, HEADER_FOOTER_INIT_BUDGET_MS = 200, MAX_ZOOM_WARNING_THRESHOLD = 10, MAX_SELECTION_RECTS_PER_USER = 100, SEMANTIC_RESIZE_DEBOUNCE_MS = 120, MIN_SEMANTIC_CONTENT_WIDTH_PX = 1, GLOBAL_PERFORMANCE, PresentationEditor, ICONS, TEXTS, tableActionsOptions;
-var init_src_sOP3agXO_es = __esm(() => {
+var init_src_CeG3wOI4_es = __esm(() => {
   init_rolldown_runtime_B2q5OVn9_es();
   init_SuperConverter_CMIR0kxi_es();
   init_jszip_ChlR43oI_es();
@@ -287805,7 +287854,7 @@ var init_zipper_YmNpPIyc_es = __esm(() => {
 
 // ../../packages/superdoc/dist/super-editor.es.js
 var init_super_editor_es = __esm(() => {
-  init_src_sOP3agXO_es();
+  init_src_CeG3wOI4_es();
   init_SuperConverter_CMIR0kxi_es();
   init_jszip_ChlR43oI_es();
   init_xml_js_40FWvL78_es();
@@ -336225,6 +336274,25 @@ async function getFileChecksum(path2) {
   }
   return createHash2("sha256").update(bytes).digest("hex");
 }
+async function exportOptionalSessionOutput(editor, io, outPath, force) {
+  if (!outPath)
+    return;
+  try {
+    return { output: await exportToPath(editor, outPath, force) };
+  } catch (error4) {
+    const code7 = error4 instanceof CliError ? error4.code : "FILE_WRITE_ERROR";
+    const message = error4 instanceof Error ? error4.message : String(error4);
+    io.warn?.(`[warn] optional export to ${outPath} failed: ${message}
+`);
+    return {
+      warning: {
+        code: code7,
+        path: outPath,
+        message
+      }
+    };
+  }
+}
 async function exportToPath(editor, outputPath, force = false) {
   const exists = await pathExists(outputPath);
   if (exists && !force) {
@@ -337892,18 +337960,6 @@ function buildPrettyOutput2(operationId, document2, result2, outputPath) {
   const verb = SUCCESS_VERB[operationId];
   return outputPath ? `Revision ${document2.revision}: ${verb} -> ${outputPath}` : `Revision ${document2.revision}: ${verb}`;
 }
-async function exportOptionalSessionOutput(editor, outPath, force) {
-  if (!outPath)
-    return;
-  try {
-    return await exportToPath(editor, outPath, force);
-  } catch (error4) {
-    const message = error4 instanceof Error ? error4.message : String(error4);
-    process.stderr.write(`[warn] optional export to ${outPath} failed: ${message}
-`);
-    return;
-  }
-}
 async function executeMutationOperation(request) {
   const { operationId, input: input2, context } = request;
   const doc4 = readOptionalString(input2, "doc");
@@ -338014,7 +338070,7 @@ async function executeMutationOperation(request) {
         await writeContextMetadata(paths, updatedMetadata);
         byteLength3 = workingOutput.byteLength;
       }
-      const externalOutput = await exportOptionalSessionOutput(opened.editor, outPath, force);
+      const externalOutput = await exportOptionalSessionOutput(opened.editor, context.io, outPath, force);
       const document2 = {
         path: updatedMetadata.sourcePath,
         source: updatedMetadata.source,
@@ -338027,9 +338083,16 @@ async function executeMutationOperation(request) {
           changeMode,
           dryRun: false,
           context: { dirty: updatedMetadata.dirty, revision: updatedMetadata.revision },
-          output: externalOutput
+          output: externalOutput?.output ?? (externalOutput?.warning ? {
+            path: externalOutput.warning.path,
+            failed: true,
+            error: {
+              code: externalOutput.warning.code,
+              message: externalOutput.warning.message
+            }
+          } : undefined)
         }),
-        pretty: buildPrettyOutput2(operationId, document2, result2, externalOutput?.path)
+        pretty: buildPrettyOutput2(operationId, document2, result2, externalOutput?.output?.path)
       };
     } finally {
       opened.dispose();
@@ -338352,7 +338415,8 @@ var init_command_examples = __esm(() => {
     insert: [
       'superdoc insert --value "Hello, world!"',
       'superdoc insert --block-id abc123 --value "Appended text"',
-      'superdoc insert --type markdown --value "## New Section"'
+      'superdoc insert --type markdown --value "## New Section"',
+      'superdoc insert --block-id abc123 --offset 5 --type html --value "<br/>"'
     ],
     replace: [
       'superdoc replace --block-id abc123 --start 0 --end 5 --text "Updated"',
@@ -338412,7 +338476,10 @@ var init_command_examples = __esm(() => {
     "lists.setType": [
       `superdoc lists set-type --target-json '{"kind":"block","nodeType":"listItem","nodeId":"abc123"}' --kind bullet`
     ],
-    "format.apply": [`superdoc format apply --block-id abc123 --start 0 --end 10 --inline-json '{"bold":true}'`],
+    "format.apply": [
+      `superdoc format apply --block-id abc123 --start 0 --end 10 --inline-json '{"bold":true}'`,
+      `superdoc format apply --block-id abc123 --start 7 --end 14 --inline-json '{"fontSize":16,"fontFamily":"Times New Roman"}'`
+    ],
     "comments.create": ['superdoc comments create --block-id abc123 --start 0 --end 5 --text "Review this section"'],
     "comments.list": ["superdoc comments list"],
     "comments.get": ["superdoc comments get --id comment-123"],
@@ -338425,7 +338492,8 @@ var init_command_examples = __esm(() => {
     "history.undo": ["superdoc history undo"],
     "history.redo": ["superdoc history redo"],
     "mutations.apply": [
-      `superdoc mutations apply --atomic true --change-mode direct --steps-json '[{"id":"s1","op":"text.rewrite","where":{"by":"select","select":{"type":"text","pattern":"old"},"require":"first"},"args":{"replacement":{"text":"new"}}}]'`
+      `superdoc mutations apply --atomic true --change-mode direct --steps-json '[{"id":"s1","op":"text.rewrite","where":{"by":"select","select":{"type":"text","pattern":"old"},"require":"first"},"args":{"replacement":{"text":"new"}}}]'`,
+      `superdoc mutations apply --atomic true --change-mode direct --steps-json '[{"id":"s1","op":"text.insert","where":{"by":"target","target":{"kind":"selection","start":{"kind":"text","blockId":"abc123","offset":0},"end":{"kind":"text","blockId":"abc123","offset":0}}},"args":{"position":"before","content":{"text":"ALPHA01 "}}},{"id":"s2","op":"format.apply","where":{"by":"target","target":{"kind":"selection","start":{"kind":"text","blockId":"abc123","offset":8},"end":{"kind":"text","blockId":"abc123","offset":15}}},"args":{"inline":{"fontSize":16,"fontFamily":"Times New Roman"}}}]'`
     ],
     "mutations.preview": [
       `superdoc mutations preview --atomic true --change-mode direct --steps-json '[{"id":"s1","op":"text.rewrite","where":{"by":"select","select":{"type":"text","pattern":"old"},"require":"first"},"args":{"replacement":{"text":"new"}}}]'`
@@ -338491,9 +338559,11 @@ function buildHelpText() {
   const lines = ["Usage: superdoc <command> [options]", ""];
   lines.push("Common tasks:");
   lines.push("  Find mutation target    →  query match");
+  lines.push("  Seed a synthetic doc    →  open --content-override ...");
   lines.push("  Insert between list items  →  lists insert");
   lines.push("  Create a paragraph     →  create paragraph");
   lines.push("  Insert inline text     →  insert");
+  lines.push("  Insert a real tab      →  insert tab");
   lines.push("  Batch formatting changes  →  mutations apply");
   lines.push("");
   const categories = new Map;
@@ -338540,9 +338610,30 @@ var init_commands = __esm(() => {
   init_command_examples();
   init_operation_set();
   CLI_ONLY_OVERRIDES = {
-    open: { mutates: true, examples: ["superdoc open my-doc.docx", "superdoc open my-doc.docx --session my-session"] },
+    open: {
+      mutates: true,
+      examples: [
+        "superdoc open my-doc.docx",
+        'superdoc open --content-override "# Title\\n\\nBody text" --override-type markdown',
+        "superdoc open template.docx --content-override '<p>ALPHA01</p><p>BRAVO02</p>' --override-type html"
+      ]
+    },
     save: { mutates: true, examples: ["superdoc save", "superdoc save --out copy.docx"] },
     close: { mutates: true, examples: ["superdoc close"] },
+    insertTab: {
+      mutates: true,
+      examples: [
+        "superdoc insert tab --block-id abc123 --offset 5",
+        `superdoc insert tab --target-json '{"kind":"selection","start":{"kind":"text","blockId":"abc123","offset":5},"end":{"kind":"text","blockId":"abc123","offset":5}}'`
+      ]
+    },
+    insertLineBreak: {
+      mutates: true,
+      examples: [
+        "superdoc insert line-break --block-id abc123 --offset 5",
+        `superdoc insert line-break --target-json '{"kind":"selection","start":{"kind":"text","blockId":"abc123","offset":5},"end":{"kind":"text","blockId":"abc123","offset":5}}'`
+      ]
+    },
     status: { mutates: false, examples: ["superdoc status"] },
     describe: { mutates: false, examples: ["superdoc describe"] },
     describeCommand: { mutates: false, examples: ["superdoc describe command find"] },
@@ -338945,7 +339036,7 @@ function deriveOptionSpecs(operationId, params4) {
   }
   return specs;
 }
-var DOC_PARAM, SESSION_PARAM, OUT_PARAM, FORCE_PARAM, DRY_RUN_PARAM, CHANGE_MODE_PARAM, EXPECTED_REVISION_PARAM, USER_NAME_PARAM, USER_EMAIL_PARAM, PASSWORD_PARAM, AGENT_HIDDEN_PARAM_NAMES, OPERATION_CONSTRAINTS, PARAM_FLAG_OVERRIDES, DOC_FIND_SELECT_SCHEMA, PARAM_SCHEMA_OVERRIDES, PARAM_EXCLUSIONS, TEXT_TARGET_FLAT_PARAMS, TEXT_TARGET_FLAT_PARAMS_AGENT_HIDDEN, LIST_TARGET_FLAT_PARAMS, FORMAT_OPERATION_IDS, EXTRA_CLI_PARAMS, CLI_ONLY_METADATA, CLI_OPERATION_METADATA, OPTION_FLAG_ALIASES, CLI_OPERATION_OPTION_SPECS;
+var DOC_PARAM, SESSION_PARAM, OUT_PARAM, FORCE_PARAM, DRY_RUN_PARAM, CHANGE_MODE_PARAM, EXPECTED_REVISION_PARAM, USER_NAME_PARAM, USER_EMAIL_PARAM, PASSWORD_PARAM, AGENT_HIDDEN_PARAM_NAMES, OPERATION_CONSTRAINTS, PARAM_FLAG_OVERRIDES, DOC_FIND_SELECT_SCHEMA, PARAM_SCHEMA_OVERRIDES, PARAM_EXCLUSIONS, TEXT_TARGET_FLAT_PARAMS, TEXT_TARGET_FLAT_PARAMS_AGENT_HIDDEN, SELECTION_TARGET_JSON_PARAM, INSERT_REF_PARAM, 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_commands();
@@ -339091,6 +339182,19 @@ var init_operation_params = __esm(() => {
     ...p4,
     agentVisible: false
   }));
+  SELECTION_TARGET_JSON_PARAM = {
+    name: "target",
+    kind: "jsonFlag",
+    flag: "target-json",
+    type: "json",
+    description: "Collapsed text insertion point as SelectionTarget JSON."
+  };
+  INSERT_REF_PARAM = {
+    name: "ref",
+    kind: "flag",
+    type: "string",
+    description: "Mutation-ready ref returned by query.match or ranges.resolve."
+  };
   LIST_TARGET_FLAT_PARAMS = [
     { name: "nodeId", kind: "flag", flag: "node-id", type: "string", description: "Node ID of the target list item." }
   ];
@@ -339594,6 +339698,54 @@ var init_operation_params = __esm(() => {
       params: [SESSION_PARAM, { name: "discard", kind: "flag", type: "boolean" }],
       constraints: null
     },
+    "doc.insertTab": {
+      command: "insert tab",
+      positionalParams: ["doc"],
+      docRequirement: "none",
+      params: [
+        DOC_PARAM,
+        SESSION_PARAM,
+        OUT_PARAM,
+        FORCE_PARAM,
+        EXPECTED_REVISION_PARAM,
+        SELECTION_TARGET_JSON_PARAM,
+        INSERT_REF_PARAM,
+        ...TEXT_TARGET_FLAT_PARAMS,
+        {
+          name: "offset",
+          kind: "flag",
+          type: "number",
+          description: "Character offset for insertion (alias for --start/--end with the same value)."
+        }
+      ],
+      constraints: {
+        mutuallyExclusive: [["target", "ref"]]
+      }
+    },
+    "doc.insertLineBreak": {
+      command: "insert line-break",
+      positionalParams: ["doc"],
+      docRequirement: "none",
+      params: [
+        DOC_PARAM,
+        SESSION_PARAM,
+        OUT_PARAM,
+        FORCE_PARAM,
+        EXPECTED_REVISION_PARAM,
+        SELECTION_TARGET_JSON_PARAM,
+        INSERT_REF_PARAM,
+        ...TEXT_TARGET_FLAT_PARAMS,
+        {
+          name: "offset",
+          kind: "flag",
+          type: "number",
+          description: "Character offset for insertion (alias for --start/--end with the same value)."
+        }
+      ],
+      constraints: {
+        mutuallyExclusive: [["target", "ref"]]
+      }
+    },
     "doc.status": {
       command: "status",
       positionalParams: [],
@@ -340900,6 +341052,261 @@ var init_close = __esm(() => {
   init_context();
 });
 
+// src/commands/insert-inline-special.ts
+function isRecord7(value2) {
+  return typeof value2 === "object" && value2 != null && !Array.isArray(value2);
+}
+function isSelectionTarget3(value2) {
+  return isRecord7(value2) && value2.kind === "selection" && isRecord7(value2.start) && isRecord7(value2.end);
+}
+function isCollapsedTextSelectionTarget(target2) {
+  return target2.start.kind === "text" && target2.end.kind === "text" && target2.start.blockId === target2.end.blockId && target2.start.offset === target2.end.offset;
+}
+function buildPrettyOutput3(kind2, revision, outputPath) {
+  const label2 = COMMAND_BY_KIND[kind2].label;
+  return outputPath ? `Revision ${revision}: inserted ${label2} -> ${outputPath}` : `Revision ${revision}: inserted ${label2}`;
+}
+async function resolveInsertionPoint(editor, input2, kind2) {
+  const apiInput = extractInvokeInput("insert", input2);
+  if (!isRecord7(apiInput)) {
+    throw new CliError("INVALID_ARGUMENT", `insert ${COMMAND_BY_KIND[kind2].label}: invalid target input.`);
+  }
+  const ref4 = typeof apiInput.ref === "string" ? apiInput.ref : undefined;
+  const rawTarget = apiInput.target;
+  if (ref4) {
+    const resolved = editor.doc.invoke({
+      operationId: "ranges.resolve",
+      input: {
+        start: { kind: "ref", ref: ref4, boundary: "start" },
+        end: { kind: "ref", ref: ref4, boundary: "start" }
+      }
+    });
+    if (!isSelectionTarget3(resolved?.target) || !isCollapsedTextSelectionTarget(resolved.target)) {
+      throw new CliError("INVALID_TARGET", `insert ${COMMAND_BY_KIND[kind2].label}: ref must resolve to a collapsed text insertion point.`);
+    }
+    const collapsedTarget = {
+      kind: "text",
+      blockId: resolved.target.start.blockId,
+      range: { start: resolved.target.start.offset, end: resolved.target.start.offset }
+    };
+    const resolvedRange = resolveSelectionTarget(editor, resolved.target);
+    return {
+      target: collapsedTarget,
+      range: { from: resolvedRange.absFrom, to: resolvedRange.absTo }
+    };
+  }
+  if (rawTarget !== undefined) {
+    if (!isSelectionTarget3(rawTarget)) {
+      throw new CliError("INVALID_TARGET", `insert ${COMMAND_BY_KIND[kind2].label}: target must be a collapsed text selection.`);
+    }
+    const selectionTarget = rawTarget;
+    if (!isCollapsedTextSelectionTarget(selectionTarget)) {
+      throw new CliError("INVALID_TARGET", `insert ${COMMAND_BY_KIND[kind2].label}: target must be a collapsed text selection.`);
+    }
+    const resolvedRange = resolveSelectionTarget(editor, selectionTarget);
+    return {
+      target: {
+        kind: "text",
+        blockId: selectionTarget.start.blockId,
+        range: { start: selectionTarget.start.offset, end: selectionTarget.start.offset }
+      },
+      range: { from: resolvedRange.absFrom, to: resolvedRange.absTo }
+    };
+  }
+  const fallback = resolveDefaultInsertTarget(editor);
+  if (!fallback) {
+    throw new CliError("TARGET_NOT_FOUND", `insert ${COMMAND_BY_KIND[kind2].label}: no writable text block is available. Pass an explicit collapsed text target.`);
+  }
+  if (fallback.kind === "structural-end") {
+    return {
+      kind: "structural-end",
+      target: { kind: "text", blockId: "", range: { start: 0, end: 0 } },
+      insertPos: fallback.insertPos
+    };
+  }
+  return {
+    kind: "text-block",
+    target: fallback.target,
+    range: fallback.range
+  };
+}
+function executeInlineSpecialInsert(editor, kind2, insertionPoint) {
+  const commandName = kind2 === "tab" ? "insertTabNode" : "insertLineBreak";
+  const commands2 = editor.commands;
+  const command2 = commands2?.[commandName];
+  if (typeof command2 !== "function") {
+    throw new CliError("CAPABILITY_UNAVAILABLE", `insert ${COMMAND_BY_KIND[kind2].label}: ${commandName} is unavailable.`);
+  }
+  let chain = editor.chain();
+  if (insertionPoint.kind === "structural-end") {
+    if (typeof commands2?.insertParagraphAt !== "function") {
+      throw new CliError("CAPABILITY_UNAVAILABLE", `insert ${COMMAND_BY_KIND[kind2].label}: insertParagraphAt is unavailable.`);
+    }
+    chain = chain.insertParagraphAt({ pos: insertionPoint.insertPos, tracked: false }).setTextSelection({ from: insertionPoint.insertPos + 1, to: insertionPoint.insertPos + 1 });
+  } else {
+    const { from: from5, to } = insertionPoint.range;
+    if (from5 !== to) {
+      throw new CliError("INVALID_TARGET", `insert ${COMMAND_BY_KIND[kind2].label}: target must be collapsed to a single insertion point.`);
+    }
+    chain = chain.setMeta("inputType", "programmatic").setMeta("skipTrackChanges", true).setTextSelection({ from: from5, to });
+  }
+  chain = kind2 === "tab" ? chain.insertTabNode() : chain.insertLineBreak();
+  if (chain.run() !== true) {
+    throw new CliError("COMMAND_FAILED", `insert ${COMMAND_BY_KIND[kind2].label}: editor command returned false.`);
+  }
+}
+function buildSuccessData(kind2, document2, target2, revision, output) {
+  return {
+    document: document2,
+    receipt: {
+      success: true,
+      resolution: {
+        target: target2
+      }
+    },
+    inserted: { kind: kind2 },
+    context: { dirty: true, revision },
+    output: output?.output ?? (output?.warning ? {
+      path: output.warning.path,
+      failed: true,
+      error: {
+        code: output.warning.code,
+        message: output.warning.message
+      }
+    } : undefined)
+  };
+}
+async function runInsertInlineSpecial(kind2, tokens, context) {
+  const commandSpec = COMMAND_BY_KIND[kind2];
+  const { parsed, help } = parseOperationArgs(commandSpec.operationId, tokens, {
+    commandName: `insert ${kind2 === "tab" ? "tab" : "line-break"}`
+  });
+  if (help || getBooleanOption(parsed, "help")) {
+    return {
+      command: kind2 === "tab" ? "insert tab" : "insert line-break",
+      data: {
+        usage: [
+          `superdoc insert ${kind2 === "tab" ? "tab" : "line-break"} [doc] [--target-json '{...}'|--block-id <id> --offset <n>]`,
+          `superdoc insert ${kind2 === "tab" ? "tab" : "line-break"} [doc] [--ref <ref>] [--out <path>]`
+        ]
+      },
+      pretty: [
+        "Usage:",
+        `  superdoc insert ${kind2 === "tab" ? "tab" : "line-break"} [doc] [--target-json '{...}'|--block-id <id> --offset <n>]`,
+        `  superdoc insert ${kind2 === "tab" ? "tab" : "line-break"} [doc] [--ref <ref>] [--out <path>]`
+      ].join(`
+`)
+    };
+  }
+  const { doc: doc4 } = resolveDocArg(parsed, `insert ${COMMAND_BY_KIND[kind2].label}`);
+  const outPath = getStringOption(parsed, "out");
+  const force = getBooleanOption(parsed, "force");
+  const expectedRevisionRaw = parsed.options.expectedRevision;
+  const expectedRevision = typeof expectedRevisionRaw === "number" ? expectedRevisionRaw : undefined;
+  const commandName = kind2 === "tab" ? "insert tab" : "insert line-break";
+  const input2 = parsed.options;
+  if (doc4 && expectedRevision != null) {
+    throw new CliError("INVALID_ARGUMENT", `${commandName}: --expected-revision is only supported with an active open context.`);
+  }
+  if (doc4) {
+    if (!outPath) {
+      throw new CliError("MISSING_REQUIRED", `${commandName}: missing required --out.`);
+    }
+    const source = doc4 === "-" ? "stdin" : "path";
+    const opened = await openDocument(doc4, context.io);
+    try {
+      const resolved = await resolveInsertionPoint(opened.editor, input2, kind2);
+      executeInlineSpecialInsert(opened.editor, kind2, resolved);
+      const output = await exportToPath(opened.editor, outPath, force);
+      const document2 = {
+        path: source === "path" ? doc4 : undefined,
+        source,
+        byteLength: opened.meta.byteLength,
+        revision: 0
+      };
+      return {
+        command: commandName,
+        data: buildSuccessData(kind2, document2, resolved.target, 0, { output }),
+        pretty: buildPrettyOutput3(kind2, 0, output.path)
+      };
+    } finally {
+      opened.dispose();
+    }
+  }
+  return withActiveContext(context.io, commandName, async ({ metadata, paths }) => {
+    assertExpectedRevision(metadata, expectedRevision);
+    const isHostMode = context.executionMode === "host" && context.sessionPool != null;
+    const opened = await openSessionDocument(paths.workingDocPath, context.io, metadata, {
+      sessionId: context.sessionId ?? metadata.contextId,
+      executionMode: context.executionMode,
+      sessionPool: context.sessionPool
+    });
+    try {
+      const resolved = await resolveInsertionPoint(opened.editor, input2, kind2);
+      executeInlineSpecialInsert(opened.editor, kind2, resolved);
+      let updatedMetadata;
+      let byteLength3;
+      if (isHostMode) {
+        context.sessionPool.markDirty(metadata.contextId);
+        updatedMetadata = markContextUpdated(context.io, metadata, {
+          dirty: true,
+          revision: metadata.revision + 1
+        });
+        await writeContextMetadata(paths, updatedMetadata);
+        context.sessionPool.updateMetadataRevision(metadata.contextId, updatedMetadata.revision);
+        byteLength3 = opened.meta.byteLength;
+      } else if (metadata.sessionType === "collab") {
+        const synced = await syncCollaborativeSessionSnapshot(context.io, metadata, paths, opened.editor);
+        updatedMetadata = synced.updatedMetadata;
+        byteLength3 = synced.output.byteLength;
+      } else {
+        const workingOutput = await exportToPath(opened.editor, paths.workingDocPath, true);
+        updatedMetadata = markContextUpdated(context.io, metadata, {
+          dirty: true,
+          revision: metadata.revision + 1
+        });
+        await writeContextMetadata(paths, updatedMetadata);
+        byteLength3 = workingOutput.byteLength;
+      }
+      const externalOutput = await exportOptionalSessionOutput(opened.editor, context.io, outPath, force);
+      const document2 = {
+        path: updatedMetadata.sourcePath,
+        source: updatedMetadata.source,
+        byteLength: byteLength3,
+        revision: updatedMetadata.revision
+      };
+      return {
+        command: commandName,
+        data: buildSuccessData(kind2, document2, resolved.target, updatedMetadata.revision, externalOutput),
+        pretty: buildPrettyOutput3(kind2, updatedMetadata.revision, externalOutput?.output?.path)
+      };
+    } finally {
+      opened.dispose();
+    }
+  }, context.sessionId, context.executionMode);
+}
+function runInsertTab(tokens, context) {
+  return runInsertInlineSpecial("tab", tokens, context);
+}
+function runInsertLineBreak(tokens, context) {
+  return runInsertInlineSpecial("lineBreak", tokens, context);
+}
+var COMMAND_BY_KIND;
+var init_insert_inline_special = __esm(() => {
+  init_super_editor_es();
+  init_args();
+  init_context();
+  init_document();
+  init_errors();
+  init_invoke_input();
+  init_operation_args();
+  init_session_collab();
+  COMMAND_BY_KIND = {
+    tab: { operationId: "doc.insertTab", label: "tab" },
+    lineBreak: { operationId: "doc.insertLineBreak", label: "line break" }
+  };
+});
+
 // src/lib/open-password.ts
 function resolvePassword(explicit, allowEnvFallback = true) {
   if (explicit != null)
@@ -341429,6 +341836,7 @@ function getLegacyRunner(operationId) {
 var LEGACY_RUNNERS;
 var init_legacy_operation_dispatch = __esm(() => {
   init_close();
+  init_insert_inline_special();
   init_open();
   init_save();
   init_session_close();
@@ -341439,6 +341847,8 @@ var init_legacy_operation_dispatch = __esm(() => {
     "doc.open": runOpen,
     "doc.save": runSave,
     "doc.close": runClose,
+    "doc.insertTab": runInsertTab,
+    "doc.insertLineBreak": runInsertLineBreak,
     "doc.session.list": runSessionList,
     "doc.session.save": runSessionSave,
     "doc.session.close": runSessionClose,
@@ -341454,6 +341864,8 @@ var init_manual_command_allowlist = __esm(() => {
     "open",
     "save",
     "close",
+    "insert tab",
+    "insert line-break",
     "session list",
     "session save",
     "session close",
@@ -341464,6 +341876,8 @@ var init_manual_command_allowlist = __esm(() => {
     "doc.open",
     "doc.save",
     "doc.close",
+    "doc.insertTab",
+    "doc.insertLineBreak",
     "doc.session.list",
     "doc.session.save",
     "doc.session.close",
@@ -347595,35 +348009,61 @@ var init_uninstall = __esm(() => {
 import { readFileSync } from "node:fs";
 import { dirname as dirname3, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-function resolveCliPackagePath() {
-  const __filename3 = fileURLToPath2(import.meta.url);
-  const __dirname3 = dirname3(__filename3);
-  return resolve3(__dirname3, "../../package.json");
+function parsePackageJson(rawPackageJson) {
+  try {
+    return JSON.parse(rawPackageJson);
+  } catch {
+    return null;
+  }
+}
+function isSupportedCliPackageName(name2) {
+  return typeof name2 === "string" && (name2 === CLI_PACKAGE_NAME || name2.startsWith(`${CLI_PACKAGE_NAME}-`));
+}
+function resolveCliPackagePath(moduleUrl) {
+  let currentDir = dirname3(fileURLToPath2(moduleUrl));
+  while (true) {
+    const packageJsonPath = resolve3(currentDir, "package.json");
+    try {
+      const rawPackageJson = readFileSync(packageJsonPath, "utf8");
+      const parsed = parsePackageJson(rawPackageJson);
+      if (isSupportedCliPackageName(parsed?.name)) {
+        return packageJsonPath;
+      }
+    } catch {}
+    const parentDir = dirname3(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+    currentDir = parentDir;
+  }
 }
 function parsePackageVersion(rawPackageJson) {
+  const parsed = parsePackageJson(rawPackageJson);
+  if (typeof parsed?.version === "string" && parsed.version.length > 0) {
+    return parsed.version;
+  }
+  return null;
+}
+function resolveCliPackageVersionFromModuleUrl(moduleUrl) {
   try {
-    const parsed = JSON.parse(rawPackageJson);
-    if (typeof parsed.version === "string" && parsed.version.length > 0) {
-      return parsed.version;
+    const packageJsonPath = resolveCliPackagePath(moduleUrl);
+    if (!packageJsonPath) {
+      return FALLBACK_CLI_PACKAGE_VERSION;
     }
-  } catch {}
-  return null;
+    const packageJson = readFileSync(packageJsonPath, "utf8");
+    return parsePackageVersion(packageJson) ?? FALLBACK_CLI_PACKAGE_VERSION;
+  } catch {
+    return FALLBACK_CLI_PACKAGE_VERSION;
+  }
 }
 function resolveCliPackageVersion() {
   if (cachedCliPackageVersion) {
     return cachedCliPackageVersion;
   }
-  try {
-    const packageJson = readFileSync(resolveCliPackagePath(), "utf8");
-    const version4 = parsePackageVersion(packageJson);
-    cachedCliPackageVersion = version4 ?? FALLBACK_CLI_PACKAGE_VERSION;
-    return cachedCliPackageVersion;
-  } catch {
-    cachedCliPackageVersion = FALLBACK_CLI_PACKAGE_VERSION;
-    return cachedCliPackageVersion;
-  }
+  cachedCliPackageVersion = resolveCliPackageVersionFromModuleUrl(import.meta.url);
+  return cachedCliPackageVersion;
 }
-var FALLBACK_CLI_PACKAGE_VERSION = "0.0.0", cachedCliPackageVersion = null;
+var CLI_PACKAGE_NAME = "@superdoc-dev/cli", FALLBACK_CLI_PACKAGE_VERSION = "0.0.0", cachedCliPackageVersion = null;
 var init_version2 = () => {};
 
 // src/host/session-pool.ts
@@ -348212,6 +348652,9 @@ function defaultIo() {
     stderr(message) {
       process.stderr.write(message);
     },
+    warn(message) {
+      process.stderr.write(message);
+    },
     readStdinBytes() {
       if (stdinCache)
         return stdinCache;
@@ -348245,10 +348688,20 @@ function mergeIo(overrides) {
   return {
     stdout: overrides.stdout ?? base5.stdout,
     stderr: overrides.stderr ?? base5.stderr,
+    warn: overrides.warn ?? base5.warn,
     readStdinBytes: overrides.readStdinBytes ?? base5.readStdinBytes,
     now: overrides.now ?? base5.now
   };
 }
+function applyDiagnosticPolicy(io, globals) {
+  if (globals.output === "pretty" && !globals.quiet) {
+    return io;
+  }
+  return {
+    ...io,
+    warn() {}
+  };
+}
 function parseCommand(rest) {
   if (rest.length === 0) {
     throw new CliError("MISSING_REQUIRED", "Missing command.");
@@ -348355,7 +348808,8 @@ async function invokeCommand(argv, options2 = {}) {
   const startedAt = io.now();
   const { parsed, output } = await withStateDirOverride(options2.stateDir, async () => {
     const parsedInvocation = parseInvocation(argv);
-    const commandOutput = await executeParsedInvocation(parsedInvocation, io, options2.executionMode ?? "oneshot", options2.sessionPool);
+    const runtimeIo = applyDiagnosticPolicy(io, parsedInvocation.globals);
+    const commandOutput = await executeParsedInvocation(parsedInvocation, runtimeIo, options2.executionMode ?? "oneshot", options2.sessionPool);
     return { parsed: parsedInvocation, output: commandOutput };
   });
   return {
@@ -348378,6 +348832,7 @@ async function run2(argv, ioOverrides, options2 = {}) {
     try {
       const parsed = parseInvocation(argv);
       outputMode = parsed.globals.output;
+      const runtimeIo = applyDiagnosticPolicy(io, parsed.globals);
       if (parsed.globals.version && !parsed.globals.help) {
         io.stdout(`${resolveCliPackageVersion()}
 `);
@@ -348404,7 +348859,7 @@ async function run2(argv, ioOverrides, options2 = {}) {
           return legacyCompat.exitCode;
         }
       }
-      const output = await executeParsedInvocation(parsed, io, "oneshot");
+      const output = await executeParsedInvocation(parsed, runtimeIo, "oneshot");
       if (output.helpText) {
         io.stdout(output.helpText);
         return 0;
@@ -348436,6 +348891,7 @@ var init_src2 = __esm(async () => {
   init_input_readers();
   init_call();
   init_close();
+  init_insert_inline_special();
   init_open();
   init_session_close();
   init_session_list();
@@ -348468,6 +348924,7 @@ var init_src2 = __esm(async () => {
     "  --pretty",
     "  --session <id>",
     "  --timeout-ms <n>",
+    "  --quiet",
     "  --help, -h",
     "  --version, -v"
   ].join(`
@@ -348475,6 +348932,8 @@ var init_src2 = __esm(async () => {
   MANUAL_COMMANDS = {
     call: runCall,
     close: runClose,
+    "insert line-break": runInsertLineBreak,
+    "insert tab": runInsertTab,
     open: runOpen,
     save: runSave,
     "session list": runSessionList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli",
-  "version": "0.5.0-next.15",
+  "version": "0.5.0-next.16",
   "type": "module",
   "bin": {
     "superdoc": "./dist/index.js"
@@ -25,20 +25,20 @@
     "@types/ws": "^8.5.13",
     "typescript": "^5.9.2",
     "@superdoc/document-api": "0.0.1",
-    "@superdoc/pm-adapter": "0.0.0",
+    "superdoc": "1.23.0",
     "@superdoc/super-editor": "0.0.1",
-    "superdoc": "1.23.0"
+    "@superdoc/pm-adapter": "0.0.0"
   },
   "module": "src/index.ts",
   "publishConfig": {
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc-dev/cli-darwin-arm64": "0.5.0-next.15",
-    "@superdoc-dev/cli-darwin-x64": "0.5.0-next.15",
-    "@superdoc-dev/cli-windows-x64": "0.5.0-next.15",
-    "@superdoc-dev/cli-linux-arm64": "0.5.0-next.15",
-    "@superdoc-dev/cli-linux-x64": "0.5.0-next.15"
+    "@superdoc-dev/cli-darwin-arm64": "0.5.0-next.16",
+    "@superdoc-dev/cli-darwin-x64": "0.5.0-next.16",
+    "@superdoc-dev/cli-linux-x64": "0.5.0-next.16",
+    "@superdoc-dev/cli-linux-arm64": "0.5.0-next.16",
+    "@superdoc-dev/cli-windows-x64": "0.5.0-next.16"
   },
   "scripts": {
     "predev": "node scripts/ensure-superdoc-build.js",

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: editing-docx
+name: superdoc-edit-docx
 description: Edit, query, and transform Word documents with the SuperDoc CLI v1 operation surface. Use when the user asks to read, search, modify, comment, or review changes in .docx files.
 ---
 
@@ -24,7 +24,7 @@ Use `describe command` for per-command args and constraints.
 
 ## Preferred Workflows
 
-### 1) Stateful multi-step edits (recommended)
+### 1) Edit an existing document (recommended for targeted changes)
 
 ```bash
 superdoc open ./contract.docx
@@ -34,12 +34,51 @@ superdoc save --in-place
 superdoc close
 ```
 
-- Always use `query match` (not `find`) to discover mutation targets — it returns exact addresses with cardinality guarantees.
+- Use `query match` when you are modifying existing content and need an exact mutation target.
 - After `open`, commands run against the active/default session when `<doc>` is omitted.
 - Use `superdoc session list|set-default|save|close` for explicit session control.
 - `close` on dirty state requires `--discard` or a prior `save`.
 
-### 2) Stateless one-off reads
+### 2) Generate or seed a document body (recommended for synthetic/probe docs)
+
+Use `open --content-override` when you want to create a new body from Markdown, HTML, or plain text in one step.
+
+```bash
+superdoc open --content-override "# Probe Title\n\nALPHA01" --override-type markdown
+superdoc save --out ./probe.docx
+superdoc close
+```
+
+```bash
+superdoc open template.docx \
+  --content-override '<p>ALPHA01 <strong>BRAVO02</strong><br/>CHARLIE03</p>' \
+  --override-type html
+superdoc save --out ./probe.docx
+superdoc close
+```
+
+- `--content-override` is the fastest way to seed paragraphs, headings, lists, and `<br/>` line breaks.
+- Use `--override-type markdown|html|text` explicitly. `open` rejects `--content-override` without it.
+- For generation, do not start with `query match` unless you are modifying content that already exists.
+
+### 3) Generate incrementally, then reuse the insert receipt target
+
+When you need deterministic inline formatting after seeding text, insert first, then reuse the returned target block/range.
+
+```bash
+superdoc open
+superdoc insert --value "ALPHA01 BRAVO02 CHARLIE03"
+superdoc format apply --block-id <from-insert-receipt> --start 8 --end 15 --inline-json '{"fontSize":16,"fontFamily":"Times New Roman"}'
+superdoc format apply --block-id <from-insert-receipt> --start 16 --end 25 --inline-json '{"fontSize":10,"fontFamily":"Arial"}'
+superdoc save --out ./probe.docx
+superdoc close
+```
+
+- The insert receipt contains the resolved target under `receipt.resolution.target`.
+- For a simple one-paragraph synthetic doc, direct `--block-id --start --end` formatting is usually shorter than re-querying.
+- Use `query match` again only if later steps need to rediscover content by meaning, not by the range you just created.
+
+### 4) Stateless one-off reads
 
 ```bash
 superdoc get-text ./proposal.docx
@@ -47,7 +86,7 @@ superdoc get-markdown ./proposal.docx
 superdoc info ./proposal.docx
 ```
 
-### 3) Stateless one-off mutations
+### 5) Stateless one-off mutations
 
 ```bash
 superdoc replace ./proposal.docx \
@@ -58,6 +97,20 @@ superdoc replace ./proposal.docx \
 
 - In stateless mode (`<doc>` provided), mutating commands require `--out` unless using `--dry-run`.
 
+### 6) Inline special nodes: tabs vs line breaks
+
+- `insert line-break` inserts a real Word line break node inside the current paragraph.
+- `insert tab` inserts a real Word tab node inside the current paragraph.
+- Paragraph tab stops are different. Tab stops control layout positions; tab nodes are inline content characters that advance to the next tab stop.
+
+```bash
+superdoc insert line-break --block-id p1 --offset 12
+superdoc insert tab --block-id p1 --offset 12
+```
+
+- Use `format paragraph set-tab-stop` / related paragraph formatting commands when you need the tab stop definitions themselves.
+- Use the inline insert commands when you need actual `w:br` or `w:tab` content in exported DOCX.
+
 ### Safety: preview before apply
 
 - Use `--dry-run` to preview any mutation without applying it.
@@ -76,6 +129,7 @@ superdoc replace ./proposal.docx \
 
 - Replace text: `replace --target-json '{...}' --text "..."`
 - Insert inline text: `insert --block-id <id> --offset <n> --value "..."`
+- Insert inline tab/line break nodes: `insert tab`, `insert line-break`
 - Delete text/node: `delete --target-json '{...}'`
 - Delete blocks: `blocks delete`, `blocks delete-range`
 - Batch mutations: `mutations apply --steps-json '[...]' --atomic true --change-mode direct`
@@ -131,8 +185,10 @@ Always supported alongside their `-json` counterpart (use one, not both):
 ## Output and Global Flags
 
 - Default output is JSON envelope.
+- In JSON mode, command results are returned as a JSON envelope.
 - Use `--pretty` for human-readable output (not supported by `call`).
-- Global flags: `--output <json|pretty>`, `--session <id>`, `--timeout-ms <n>`.
+- Use `--quiet` to suppress non-essential warnings in pretty mode.
+- Global flags: `--output <json|pretty>`, `--session <id>`, `--timeout-ms <n>`, `--quiet`.
 - `<doc>` can be `-` to read DOCX bytes from stdin.
 
 ## Legacy Compatibility (Use Sparingly)