@superdoc/cli 0.23.0 → 0.25.0

package/dist/prompts/system-prompt.md

@@ -49,7 +49,8 @@ ACTIONS (superdoc_perform_action with flat args)
 - redo_changes: steps (1-25, default 1). Steps history FORWARD to re-apply edits a prior undo removed — THE recovery for an undo overshoot. Only reaches the forward branch until a NEW edit is made.
 - attach_numbering: anchorText (text of the block) or nodeId, likeMarker (rendered marker of a sibling clause, e.g. "10."). Makes an EXISTING block a numbered clause at the same scheme/level — "make this the section 11 heading" in a clause-numbered document is exactly this (it will render as the next number).
 - replace_text: edits:[{find,replace}], caseSensitive default false. selector to scope. changeMode:"tracked" if asked. The receipt reports editsApplied and editsSkipped per find — READ IT: a skipped find is not in the selected block; re-target instead of assuming success.
-- delete_text: finds:[string]. selector to scope deletions to ONE block — REQUIRED for whitespace-only finds (unscoped whitespace matches document-wide and is refused). changeMode:"tracked" if asked.
+- delete_text: finds:[string]. selector to scope deletions to ONE block — REQUIRED for whitespace-only finds (unscoped whitespace matches document-wide and is refused). changeMode:"tracked" if asked. Deletes TEXT ONLY: the block survives, so a list item keeps its bullet/number and an accepted tracked deletion leaves an empty numbered item behind. To remove the item itself use delete_blocks.
+- delete_blocks: selectors:[…], each resolving to ONE block (list item, paragraph or heading). changeMode:"tracked" if asked. THE way to DELETE a whole LIST ITEM, paragraph or heading — the bullet/number goes with it and the remaining items renumber. "Delete the first item under Article II" / "remove that clause" is exactly this, NOT delete_text. Pass every target in ONE call. Use delete_table for a whole table.
 - rewrite_block: selector, text. Inspect first to gather current text; never ask the user to paste text already in the doc.
 - create_table: rows, columns, optional cellTexts (2D array). rows counts ALL rows INCLUDING the header — header plus one data row is rows:2. placement defaults to document end. changeMode:"tracked" if asked ("track-changes table") — the insertion itself becomes a tracked change.
 - comment_paragraphs: commentText. excludeBlockQuotes:true to skip block quotes. Applies the SAME text to every BODY paragraph (it does NOT comment the title/heading) — broadcast notes only, never review feedback (see REVIEW rule). To comment a heading too, add_comments on it explicitly.

package/dist/tools/catalog.json

@@ -4725,7 +4725,7 @@
     },
     {
       "toolName": "superdoc_comment",
-      "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; only \"action\", \"text\", and \"target\" are needed.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
+      "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; \"action\", \"text\", and \"target\" are required, while commentId (the v1 compatibility alias for externalId), externalId, author fields, and metadata are optional correlation fields.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -4850,6 +4850,43 @@
             "type": "string",
             "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
           },
+          "commentId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024,
+            "description": "Compatibility alias for externalId, matching the caller-supplied commentId accepted by the v1 editor. V2 still generates a separate Word-compatible commentId. Only for action 'create'. Omit for other actions."
+          },
+          "externalId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024,
+            "description": "Caller-owned durable, document-unique integration id. Kept separate from the generated Word-compatible commentId. Only for action 'create'. Omit for other actions."
+          },
+          "author": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Author display name. Defaults to the configured session author. Only for action 'create'. Omit for other actions."
+          },
+          "authorId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable caller-owned author id. Only for action 'create'. Omit for other actions."
+          },
+          "authorEmail": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Caller-owned author email. Only for action 'create'. Omit for other actions."
+          },
+          "authorImage": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Caller-owned author image URL. Only for action 'create'. Omit for other actions."
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Caller-owned JSON metadata persisted with the comment. Only for action 'create'. Omit for other actions."
+          },
           "id": {
             "type": "string",
             "description": "Required for actions 'delete', 'get'."

package/dist/tools/tools.anthropic.json

@@ -4440,7 +4440,7 @@
     },
     {
       "name": "superdoc_comment",
-      "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; only \"action\", \"text\", and \"target\" are needed.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
+      "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; \"action\", \"text\", and \"target\" are required, while commentId (the v1 compatibility alias for externalId), externalId, author fields, and metadata are optional correlation fields.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
       "input_schema": {
         "type": "object",
         "properties": {
@@ -4565,6 +4565,43 @@
             "type": "string",
             "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
           },
+          "commentId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024,
+            "description": "Compatibility alias for externalId, matching the caller-supplied commentId accepted by the v1 editor. V2 still generates a separate Word-compatible commentId. Only for action 'create'. Omit for other actions."
+          },
+          "externalId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024,
+            "description": "Caller-owned durable, document-unique integration id. Kept separate from the generated Word-compatible commentId. Only for action 'create'. Omit for other actions."
+          },
+          "author": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Author display name. Defaults to the configured session author. Only for action 'create'. Omit for other actions."
+          },
+          "authorId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable caller-owned author id. Only for action 'create'. Omit for other actions."
+          },
+          "authorEmail": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Caller-owned author email. Only for action 'create'. Omit for other actions."
+          },
+          "authorImage": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Caller-owned author image URL. Only for action 'create'. Omit for other actions."
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Caller-owned JSON metadata persisted with the comment. Only for action 'create'. Omit for other actions."
+          },
           "id": {
             "type": "string",
             "description": "Required for actions 'delete', 'get'."

package/dist/tools/tools.generic.json

@@ -4550,7 +4550,7 @@
     },
     {
       "name": "superdoc_comment",
-      "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; only \"action\", \"text\", and \"target\" are needed.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
+      "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; \"action\", \"text\", and \"target\" are required, while commentId (the v1 compatibility alias for externalId), externalId, author fields, and metadata are optional correlation fields.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
       "parameters": {
         "type": "object",
         "properties": {
@@ -4675,6 +4675,43 @@
             "type": "string",
             "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
           },
+          "commentId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024,
+            "description": "Compatibility alias for externalId, matching the caller-supplied commentId accepted by the v1 editor. V2 still generates a separate Word-compatible commentId. Only for action 'create'. Omit for other actions."
+          },
+          "externalId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024,
+            "description": "Caller-owned durable, document-unique integration id. Kept separate from the generated Word-compatible commentId. Only for action 'create'. Omit for other actions."
+          },
+          "author": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Author display name. Defaults to the configured session author. Only for action 'create'. Omit for other actions."
+          },
+          "authorId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable caller-owned author id. Only for action 'create'. Omit for other actions."
+          },
+          "authorEmail": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Caller-owned author email. Only for action 'create'. Omit for other actions."
+          },
+          "authorImage": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Caller-owned author image URL. Only for action 'create'. Omit for other actions."
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Caller-owned JSON metadata persisted with the comment. Only for action 'create'. Omit for other actions."
+          },
           "id": {
             "type": "string",
             "description": "Required for actions 'delete', 'get'."

package/dist/tools/tools.openai.json

@@ -4457,7 +4457,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_comment",
-        "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; only \"action\", \"text\", and \"target\" are needed.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
+        "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; \"action\", \"text\", and \"target\" are required, while commentId (the v1 compatibility alias for externalId), externalId, author fields, and metadata are optional correlation fields.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
         "parameters": {
           "type": "object",
           "properties": {
@@ -4582,6 +4582,43 @@
               "type": "string",
               "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
             },
+            "commentId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "description": "Compatibility alias for externalId, matching the caller-supplied commentId accepted by the v1 editor. V2 still generates a separate Word-compatible commentId. Only for action 'create'. Omit for other actions."
+            },
+            "externalId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "description": "Caller-owned durable, document-unique integration id. Kept separate from the generated Word-compatible commentId. Only for action 'create'. Omit for other actions."
+            },
+            "author": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Author display name. Defaults to the configured session author. Only for action 'create'. Omit for other actions."
+            },
+            "authorId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Stable caller-owned author id. Only for action 'create'. Omit for other actions."
+            },
+            "authorEmail": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Caller-owned author email. Only for action 'create'. Omit for other actions."
+            },
+            "authorImage": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Caller-owned author image URL. Only for action 'create'. Omit for other actions."
+            },
+            "metadata": {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "Caller-owned JSON metadata persisted with the comment. Only for action 'create'. Omit for other actions."
+            },
             "id": {
               "type": "string",
               "description": "Required for actions 'delete', 'get'."

package/dist/tools/tools.vercel.json

@@ -4457,7 +4457,7 @@
       "type": "function",
       "function": {
         "name": "superdoc_comment",
-        "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; only \"action\", \"text\", and \"target\" are needed.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
+        "description": "Manage document comment threads: create, read, update, and delete. To create a comment, first use superdoc_search to find the target text, then pass action \"create\" with the comment text and a target built from items[0].blocks. For a single-block match use {kind:\"text\", blockId: items[0].blocks[0].blockId, range: items[0].blocks[0].range}. For a cross-block match use {kind:\"text\", segments: items[0].blocks.map(b => ({blockId: b.blockId, range: b.range}))}. Do NOT use items[0].highlightRange (snippet-relative, not block-relative) or items[0].target (a SelectionTarget, not accepted by comments.create). For threaded replies, pass \"parentId\" with the parent comment ID. Action \"list\" returns all comments with optional pagination (limit, offset) and filtering (includeResolved:true to include resolved). Action \"get\" retrieves a single comment by ID. Action \"update\" changes comment text, re-anchors the thread, changes status to \"resolved\", or toggles the legacy `sdcom:internal` flag for v1 compatibility. Action \"delete\" removes a comment or reply by ID. Do NOT pass \"ref\", \"id\", or \"parentId\" when creating a new top-level comment; \"action\", \"text\", and \"target\" are required, while commentId (the v1 compatibility alias for externalId), externalId, author fields, and metadata are optional correlation fields.\n\nEXAMPLES:\n  1. {\"action\":\"create\",\"text\":\"Please review this section.\",\"target\":{\"kind\":\"text\",\"blockId\":\"<blockId>\",\"range\":{\"start\":5,\"end\":25}}}\n  2. {\"action\":\"list\",\"limit\":20,\"offset\":0}\n  3. {\"action\":\"update\",\"id\":\"<commentId>\",\"status\":\"resolved\"}\n  4. {\"action\":\"delete\",\"id\":\"<commentId>\"}",
         "parameters": {
           "type": "object",
           "properties": {
@@ -4582,6 +4582,43 @@
               "type": "string",
               "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
             },
+            "commentId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "description": "Compatibility alias for externalId, matching the caller-supplied commentId accepted by the v1 editor. V2 still generates a separate Word-compatible commentId. Only for action 'create'. Omit for other actions."
+            },
+            "externalId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "description": "Caller-owned durable, document-unique integration id. Kept separate from the generated Word-compatible commentId. Only for action 'create'. Omit for other actions."
+            },
+            "author": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Author display name. Defaults to the configured session author. Only for action 'create'. Omit for other actions."
+            },
+            "authorId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Stable caller-owned author id. Only for action 'create'. Omit for other actions."
+            },
+            "authorEmail": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Caller-owned author email. Only for action 'create'. Omit for other actions."
+            },
+            "authorImage": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Caller-owned author image URL. Only for action 'create'. Omit for other actions."
+            },
+            "metadata": {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "Caller-owned JSON metadata persisted with the comment. Only for action 'create'. Omit for other actions."
+            },
             "id": {
               "type": "string",
               "description": "Required for actions 'delete', 'get'."

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@superdoc/cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
+  "description": "Command-line interface for SuperDoc: inspect, convert, and edit .docx files from a terminal or a script.",
   "type": "module",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superdoc/docx-editor.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://github.com/superdoc/docx-editor/tree/main/apps/cli#readme",
+  "bugs": {
+    "url": "https://github.com/superdoc/docx-editor/issues"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "bin": {
@@ -18,9 +29,9 @@
     "fast-glob": "^3.3.3",
     "happy-dom": "^20.3.4",
     "ws": "^8.18.0",
-    "superdoc": "2.3.0",
     "y-websocket": "^3.0.0",
-    "yjs": "13.6.31"
+    "yjs": "13.6.31",
+    "superdoc": "2.5.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.8",
@@ -29,20 +40,21 @@
     "jszip": "3.10.1",
     "lib0": "^0.2.114",
     "typescript": "^5.9.2",
+    "vite-plus": "0.2.8",
     "y-protocols": "^1.0.6",
     "@superdoc/document-api": "0.1.0-alpha.0",
-    "@superdoc/sdk": "2.0.0",
-    "@superdoc/docx-engine": "0.2.0-next.8"
+    "@superdoc/sdk": "2.2.0",
+    "@superdoc/docx-engine": "0.3.0-next.60"
   },
   "publishConfig": {
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc/cli-darwin-arm64": "0.23.0",
-    "@superdoc/cli-darwin-x64": "0.23.0",
-    "@superdoc/cli-linux-x64": "0.23.0",
-    "@superdoc/cli-windows-x64": "0.23.0",
-    "@superdoc/cli-linux-arm64": "0.23.0"
+    "@superdoc/cli-darwin-x64": "0.25.0",
+    "@superdoc/cli-darwin-arm64": "0.25.0",
+    "@superdoc/cli-linux-arm64": "0.25.0",
+    "@superdoc/cli-linux-x64": "0.25.0",
+    "@superdoc/cli-windows-x64": "0.25.0"
   },
   "scripts": {
     "predev": "node scripts/ensure-superdoc-build.js",
@@ -61,9 +73,9 @@
     "publish:platforms:dry": "node scripts/publish.js --tag latest --dry-run",
     "pretest": "node scripts/ensure-superdoc-build.js",
     "test": "NODE_ENV=test bun test",
-    "lint": "eslint .",
-    "lint:fix": "eslint --fix .",
-    "format": "prettier --write .",
+    "lint": "pnpm -w exec vp lint apps/cli",
+    "lint:fix": "pnpm -w exec vp lint --fix apps/cli",
+    "format": "pnpm -w exec vp fmt apps/cli",
     "pretypecheck": "node scripts/ensure-superdoc-build.js --types",
     "typecheck": "tsc --noEmit -p tsconfig.check.json",
     "release": "pnpx semantic-release",

package/skill/SKILL.md

@@ -8,7 +8,7 @@ description: Edit, query, and transform Word documents with the SuperDoc CLI v1
 Use SuperDoc CLI for DOCX work. Use v1 commands (canonical operations and their helper wrappers).
 Do not default to legacy commands unless explicitly needed for v0-style bulk workflows.
 
-Use `superdoc` if installed, or `npx @superdoc/cli@latest` as a fallback.
+Use `superdoc` if installed, or `npx @superdoc-dev/cli@latest` as a fallback.
 
 ## First Step: Discover Exact Params