@superdoc/cli 0.45.0-next.9 → 0.46.0-next.1

package/dist/prompts/mcp-prompt.md

@@ -18,6 +18,8 @@ These tools handle the OOXML format correctly and preserve document structure.
 
 **Edit with named actions.** `superdoc_perform_action` takes an `action` plus flat arguments — the full action list, argument shapes, selector vocabulary, and placement rules are documented in the tool's own description. Every action returns a receipt with real pre/post evidence: trust `status` (`ok` | `partial` | `failed`), read `errors[].message` for recovery guidance, and re-inspect after `partial`.
 
+**Target one repeated match.** For `replace_text`, scope to one block with a selector and set `occurrence` on the edit (1 = first match in that block) to change only that match. Also pass `expectedRevision` from your latest inspect or receipt; on `REVISION_CONFLICT`, inspect again and recount.
+
 **Tracked changes (redlining).** Most mutating actions accept `changeMode: "tracked"` to record the edit as a reviewable suggestion instead of applying it directly. Review with `accept_tracked_changes` / `reject_tracked_changes` (target one change with `id`, or an exact set with `id:[…]`; or filter by `author` or `changeType`). Do not combine exact IDs with filters. Recover with `undo_changes` / `redo_changes`.
 
 **Failures are safe.** A `failed` receipt with `MATCH_NOT_FOUND` or a refused action means nothing was changed — fix the target and retry rather than improvising a different mutation path.

package/dist/prompts/system-prompt.md

@@ -48,7 +48,7 @@ ACTIONS (superdoc_perform_action with flat args)
 - undo_changes: untilMarker (rendered marker from the original state, e.g. "2.1.") or steps (1-25). Deterministic revert — steps history back until the marker reappears; the receipt proves it. NEVER use steps > 1 blindly: prefer untilMarker, and after ANY undo verify (superdoc_inspect) that content you meant to KEEP still exists — if you overshot, redo_changes {steps:N} steps forward again to recover it.
 - 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.
+- replace_text: edits:[{find,replace,occurrence?}], caseSensitive default false. selector to scope. Keep find/replace spans MINIMAL. If the find appears more than once in the selected block and only one should change, give that edit occurrence (1 = first match in the block; needs selector; not selector.occurrence). With occurrence, also pass expectedRevision from your latest inspect or receipt; on REVISION_CONFLICT inspect again and recount. 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. 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.

package/dist/tools/catalog.json

@@ -4654,6 +4654,10 @@
             "type": "string",
             "description": "Text content for the new list item. Only for action 'insert'. Omit for other actions."
           },
+          "inheritFrom": {
+            "$ref": "#/$defs/ListItemAddress",
+            "description": "Optional same-story list item to inherit paragraph and run formatting from without changing placement or numbering. When omitted, existing paragraph-creation formatting behavior, including next-style handling, is preserved. Only for action 'insert'. Omit for other actions."
+          },
           "input": {
             "type": "object",
             "description": "Operation input as JSON object."
@@ -6539,7 +6543,7 @@
     },
     {
       "toolName": "superdoc_search",
-      "description": "Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Refs expire after any mutation that changes the document. Re-search before the next edit when using individual tools (superdoc_edit, superdoc_format). Within a superdoc_mutations batch, selectors in \"where\" clauses resolve automatically at compile time; no manual re-searching needed between steps. Text search returns handle.ref covering only the matched substring. Node search finds blocks by type (paragraph, heading, table, listItem, etc.). The \"require\" parameter controls match cardinality: \"first\" returns one match, \"all\" returns every match, \"exactlyOne\" fails if not exactly one match. Supports scoping via \"within\" to search inside a single block. Patterns are plain text by default; pass select.mode: \"regex\" for regular-expression search (g/gi semantics, 1024-char cap, no wholeWord, capture groups returned on matches). Invalid or unsafe patterns fail with INVALID_INPUT. Do NOT use markdown formatting markers (#, **, etc.) in search patterns. Do NOT use this tool when you already have a ref from superdoc_get_content blocks or superdoc_create; use that ref directly.\n\nEXAMPLES:\n  1. {\"select\":{\"type\":\"text\",\"pattern\":\"Introduction\"},\"require\":\"first\"}\n  2. {\"select\":{\"type\":\"text\",\"pattern\":\"total amount\"},\"require\":\"all\"}\n  3. {\"select\":{\"type\":\"node\",\"nodeType\":\"heading\"},\"require\":\"all\"}\n  4. {\"select\":{\"type\":\"text\",\"pattern\":\"contract\"},\"within\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"abc123\"},\"require\":\"first\"}",
+      "description": "Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Refs expire after any mutation that changes the document. Re-search before the next edit when using individual tools (superdoc_edit, superdoc_format). Within a superdoc_mutations batch, selectors in \"where\" clauses resolve automatically at compile time; no manual re-searching needed between steps. Text search returns handle.ref covering only the matched substring. Node search finds blocks by type (paragraph, heading, table, listItem, etc.). The \"require\" parameter controls match cardinality: \"first\" returns one match, \"last\" returns the final match (without limit/offset), \"all\" returns every match, \"exactlyOne\" fails if not exactly one match. Supports scoping via \"within\" to search inside a single block. Patterns are plain text by default; pass select.mode: \"regex\" for regular-expression search (g/gi semantics, 1024-char cap, no wholeWord, capture groups returned on matches). Invalid or unsafe patterns fail with INVALID_INPUT. Do NOT use markdown formatting markers (#, **, etc.) in search patterns. Do NOT use this tool when you already have a ref from superdoc_get_content blocks or superdoc_create; use that ref directly.\n\nEXAMPLES:\n  1. {\"select\":{\"type\":\"text\",\"pattern\":\"Introduction\"},\"require\":\"first\"}\n  2. {\"select\":{\"type\":\"text\",\"pattern\":\"total amount\"},\"require\":\"all\"}\n  3. {\"select\":{\"type\":\"node\",\"nodeType\":\"heading\"},\"require\":\"all\"}\n  4. {\"select\":{\"type\":\"text\",\"pattern\":\"contract\"},\"within\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"abc123\"},\"require\":\"first\"}",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -6646,10 +6650,11 @@
             "enum": [
               "any",
               "first",
+              "last",
               "exactlyOne",
               "all"
             ],
-            "description": "Match cardinality: 'any' (all matches), 'first' (only first), 'exactlyOne' (fail if != 1), 'all' (fail if 0)."
+            "description": "Match cardinality: 'any' (all matches), 'first' (only first), 'last' (final scoped match, without limit/offset), 'exactlyOne' (fail if != 1), 'all' (fail if 0). For 'last', page.offset reports the selected match's ordinal in the full set."
           },
           "mode": {
             "enum": [
@@ -9225,10 +9230,133 @@
                     "where",
                     "args"
                   ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "op": {
+                      "const": "comments.patch",
+                      "type": "string"
+                    },
+                    "args": {
+                      "type": "object",
+                      "properties": {
+                        "commentId": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "target": {
+                          "oneOf": [
+                            {
+                              "$ref": "#/$defs/TextAddress"
+                            },
+                            {
+                              "$ref": "#/$defs/SelectionTarget"
+                            }
+                          ]
+                        }
+                      },
+                      "additionalProperties": false,
+                      "required": [
+                        "commentId",
+                        "target"
+                      ]
+                    }
+                  },
+                  "additionalProperties": false,
+                  "required": [
+                    "id",
+                    "op",
+                    "args"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "op": {
+                      "const": "trackChanges.decide",
+                      "type": "string"
+                    },
+                    "args": {
+                      "type": "object",
+                      "properties": {
+                        "decision": {
+                          "enum": [
+                            "accept",
+                            "reject"
+                          ],
+                          "type": "string"
+                        },
+                        "target": {
+                          "oneOf": [
+                            {
+                              "type": "object",
+                              "properties": {
+                                "kind": {
+                                  "const": "id",
+                                  "type": "string"
+                                },
+                                "id": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              },
+                              "additionalProperties": false,
+                              "required": [
+                                "kind",
+                                "id"
+                              ]
+                            },
+                            {
+                              "type": "object",
+                              "properties": {
+                                "kind": {
+                                  "const": "ids",
+                                  "type": "string"
+                                },
+                                "ids": {
+                                  "type": "array",
+                                  "items": {
+                                    "type": "string",
+                                    "minLength": 1
+                                  },
+                                  "minItems": 1
+                                }
+                              },
+                              "additionalProperties": false,
+                              "required": [
+                                "kind",
+                                "ids"
+                              ]
+                            }
+                          ]
+                        }
+                      },
+                      "additionalProperties": false,
+                      "required": [
+                        "decision",
+                        "target"
+                      ]
+                    }
+                  },
+                  "additionalProperties": false,
+                  "required": [
+                    "id",
+                    "op",
+                    "args"
+                  ]
                 }
               ]
             },
-            "description": "Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, structural.replace, or assert) and a 'where' targeting clause. Check runtime capabilities for operation-specific content and targeting restrictions."
+            "description": "Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, structural.replace, assert, comments.patch, or trackChanges.decide). Core steps use 'where'; review steps use explicit native args and require direct body-only plans with relocations before decisions. Check runtime capabilities for operation-specific content and targeting restrictions."
           },
           "detail": {
             "type": "object",
@@ -9299,6 +9427,22 @@
               "exact"
             ]
           },
+          "Range": {
+            "type": "object",
+            "properties": {
+              "start": {
+                "type": "integer"
+              },
+              "end": {
+                "type": "integer"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "start",
+              "end"
+            ]
+          },
           "SectionAddress": {
             "type": "object",
             "properties": {
@@ -9590,6 +9734,30 @@
               }
             ]
           },
+          "TextAddress": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "text",
+                "type": "string"
+              },
+              "blockId": {
+                "type": "string"
+              },
+              "range": {
+                "$ref": "#/$defs/Range"
+              },
+              "story": {
+                "$ref": "#/$defs/StoryLocator"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "kind",
+              "blockId",
+              "range"
+            ]
+          },
           "TextCoordinateSpace": {
             "enum": [
               "visible",

package/dist/tools/system-prompt-mcp.md

@@ -475,6 +475,7 @@ When formatting newly created content, use the right source:
 - **`within` scopes to a single block**, not a section. To find text in a section, search the full document.
 - **Table cells are separate blocks.** Search for individual cell values, not patterns spanning multiple cells.
 - **Do NOT combine `limit`/`offset` with `require: "first"` or `require: "exactlyOne"`.** Use `require: "any"` with `limit` for paginated results.
+- **`require: "last"` returns the final match and rejects any `limit` or `offset`.**
 - **Do NOT hardcode formatting values.** Always read from blocks data and replicate.
 - **Do NOT copy heading/title formatting onto body paragraphs.** Read from body text blocks (alignment "justify" or "left"), not title blocks.
 - **Pass structured objects, not JSON-encoded strings.** Fields like `at`, `target`, and `inline` expect objects, not serialized JSON strings.

package/dist/tools/system-prompt.md

@@ -429,6 +429,7 @@ When formatting newly created content, use the right source:
 - **`within` scopes to a single block**, not a section. To find text in a section, search the full document.
 - **Table cells are separate blocks.** Search for individual cell values, not patterns spanning multiple cells.
 - **Do NOT combine `limit`/`offset` with `require: "first"` or `require: "exactlyOne"`.** Use `require: "any"` with `limit` for paginated results.
+- **`require: "last"` returns the final match and rejects any `limit` or `offset`.**
 - **Do NOT hardcode formatting values.** Always read from blocks data and replicate.
 - **Do NOT copy heading/title formatting onto body paragraphs.** Read from body text blocks (alignment "justify" or "left"), not title blocks.
 - **Pass structured objects, not JSON-encoded strings.** Fields like `at`, `target`, and `inline` expect objects, not serialized JSON strings.

package/dist/tools/tools.anthropic.json

@@ -4363,6 +4363,10 @@
             "type": "string",
             "description": "Text content for the new list item. Only for action 'insert'. Omit for other actions."
           },
+          "inheritFrom": {
+            "$ref": "#/$defs/ListItemAddress",
+            "description": "Optional same-story list item to inherit paragraph and run formatting from without changing placement or numbering. When omitted, existing paragraph-creation formatting behavior, including next-style handling, is preserved. Only for action 'insert'. Omit for other actions."
+          },
           "input": {
             "type": "object",
             "description": "Operation input as JSON object."
@@ -6101,7 +6105,7 @@
     },
     {
       "name": "superdoc_search",
-      "description": "Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Refs expire after any mutation that changes the document. Re-search before the next edit when using individual tools (superdoc_edit, superdoc_format). Within a superdoc_mutations batch, selectors in \"where\" clauses resolve automatically at compile time; no manual re-searching needed between steps. Text search returns handle.ref covering only the matched substring. Node search finds blocks by type (paragraph, heading, table, listItem, etc.). The \"require\" parameter controls match cardinality: \"first\" returns one match, \"all\" returns every match, \"exactlyOne\" fails if not exactly one match. Supports scoping via \"within\" to search inside a single block. Patterns are plain text by default; pass select.mode: \"regex\" for regular-expression search (g/gi semantics, 1024-char cap, no wholeWord, capture groups returned on matches). Invalid or unsafe patterns fail with INVALID_INPUT. Do NOT use markdown formatting markers (#, **, etc.) in search patterns. Do NOT use this tool when you already have a ref from superdoc_get_content blocks or superdoc_create; use that ref directly.\n\nEXAMPLES:\n  1. {\"select\":{\"type\":\"text\",\"pattern\":\"Introduction\"},\"require\":\"first\"}\n  2. {\"select\":{\"type\":\"text\",\"pattern\":\"total amount\"},\"require\":\"all\"}\n  3. {\"select\":{\"type\":\"node\",\"nodeType\":\"heading\"},\"require\":\"all\"}\n  4. {\"select\":{\"type\":\"text\",\"pattern\":\"contract\"},\"within\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"abc123\"},\"require\":\"first\"}",
+      "description": "Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Refs expire after any mutation that changes the document. Re-search before the next edit when using individual tools (superdoc_edit, superdoc_format). Within a superdoc_mutations batch, selectors in \"where\" clauses resolve automatically at compile time; no manual re-searching needed between steps. Text search returns handle.ref covering only the matched substring. Node search finds blocks by type (paragraph, heading, table, listItem, etc.). The \"require\" parameter controls match cardinality: \"first\" returns one match, \"last\" returns the final match (without limit/offset), \"all\" returns every match, \"exactlyOne\" fails if not exactly one match. Supports scoping via \"within\" to search inside a single block. Patterns are plain text by default; pass select.mode: \"regex\" for regular-expression search (g/gi semantics, 1024-char cap, no wholeWord, capture groups returned on matches). Invalid or unsafe patterns fail with INVALID_INPUT. Do NOT use markdown formatting markers (#, **, etc.) in search patterns. Do NOT use this tool when you already have a ref from superdoc_get_content blocks or superdoc_create; use that ref directly.\n\nEXAMPLES:\n  1. {\"select\":{\"type\":\"text\",\"pattern\":\"Introduction\"},\"require\":\"first\"}\n  2. {\"select\":{\"type\":\"text\",\"pattern\":\"total amount\"},\"require\":\"all\"}\n  3. {\"select\":{\"type\":\"node\",\"nodeType\":\"heading\"},\"require\":\"all\"}\n  4. {\"select\":{\"type\":\"text\",\"pattern\":\"contract\"},\"within\":{\"kind\":\"block\",\"nodeType\":\"paragraph\",\"nodeId\":\"abc123\"},\"require\":\"first\"}",
       "input_schema": {
         "type": "object",
         "properties": {
@@ -6208,10 +6212,11 @@
             "enum": [
               "any",
               "first",
+              "last",
               "exactlyOne",
               "all"
             ],
-            "description": "Match cardinality: 'any' (all matches), 'first' (only first), 'exactlyOne' (fail if != 1), 'all' (fail if 0)."
+            "description": "Match cardinality: 'any' (all matches), 'first' (only first), 'last' (final scoped match, without limit/offset), 'exactlyOne' (fail if != 1), 'all' (fail if 0). For 'last', page.offset reports the selected match's ordinal in the full set."
           },
           "mode": {
             "enum": [
@@ -8777,10 +8782,133 @@
                     "where",
                     "args"
                   ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "op": {
+                      "const": "comments.patch",
+                      "type": "string"
+                    },
+                    "args": {
+                      "type": "object",
+                      "properties": {
+                        "commentId": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "target": {
+                          "oneOf": [
+                            {
+                              "$ref": "#/$defs/TextAddress"
+                            },
+                            {
+                              "$ref": "#/$defs/SelectionTarget"
+                            }
+                          ]
+                        }
+                      },
+                      "additionalProperties": false,
+                      "required": [
+                        "commentId",
+                        "target"
+                      ]
+                    }
+                  },
+                  "additionalProperties": false,
+                  "required": [
+                    "id",
+                    "op",
+                    "args"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "op": {
+                      "const": "trackChanges.decide",
+                      "type": "string"
+                    },
+                    "args": {
+                      "type": "object",
+                      "properties": {
+                        "decision": {
+                          "enum": [
+                            "accept",
+                            "reject"
+                          ],
+                          "type": "string"
+                        },
+                        "target": {
+                          "oneOf": [
+                            {
+                              "type": "object",
+                              "properties": {
+                                "kind": {
+                                  "const": "id",
+                                  "type": "string"
+                                },
+                                "id": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              },
+                              "additionalProperties": false,
+                              "required": [
+                                "kind",
+                                "id"
+                              ]
+                            },
+                            {
+                              "type": "object",
+                              "properties": {
+                                "kind": {
+                                  "const": "ids",
+                                  "type": "string"
+                                },
+                                "ids": {
+                                  "type": "array",
+                                  "items": {
+                                    "type": "string",
+                                    "minLength": 1
+                                  },
+                                  "minItems": 1
+                                }
+                              },
+                              "additionalProperties": false,
+                              "required": [
+                                "kind",
+                                "ids"
+                              ]
+                            }
+                          ]
+                        }
+                      },
+                      "additionalProperties": false,
+                      "required": [
+                        "decision",
+                        "target"
+                      ]
+                    }
+                  },
+                  "additionalProperties": false,
+                  "required": [
+                    "id",
+                    "op",
+                    "args"
+                  ]
                 }
               ]
             },
-            "description": "Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, structural.replace, or assert) and a 'where' targeting clause. Check runtime capabilities for operation-specific content and targeting restrictions."
+            "description": "Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, structural.replace, assert, comments.patch, or trackChanges.decide). Core steps use 'where'; review steps use explicit native args and require direct body-only plans with relocations before decisions. Check runtime capabilities for operation-specific content and targeting restrictions."
           },
           "detail": {
             "type": "object",
@@ -8851,6 +8979,22 @@
               "exact"
             ]
           },
+          "Range": {
+            "type": "object",
+            "properties": {
+              "start": {
+                "type": "integer"
+              },
+              "end": {
+                "type": "integer"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "start",
+              "end"
+            ]
+          },
           "SectionAddress": {
             "type": "object",
             "properties": {
@@ -9142,6 +9286,30 @@
               }
             ]
           },
+          "TextAddress": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "text",
+                "type": "string"
+              },
+              "blockId": {
+                "type": "string"
+              },
+              "range": {
+                "$ref": "#/$defs/Range"
+              },
+              "story": {
+                "$ref": "#/$defs/StoryLocator"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "kind",
+              "blockId",
+              "range"
+            ]
+          },
           "TextCoordinateSpace": {
             "enum": [
               "visible",