@superdoc/cli 0.26.0 → 0.27.0

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

@@ -29,6 +29,7 @@ superdoc_edit({action: "insert", type: "markdown",
   value: "# Executive Summary\n\nThis agreement sets forth the principal terms..."})
 ```
 Valid placements: "before", "after", "insideStart", "insideEnd". Without target, content appends at document end.
+Add `changeMode: "tracked"` to an HTML or Markdown insert or replacement when the result should remain reviewable. These formats support bounded document structure, not arbitrary CSS or complete DOCX package fragments; inspect conversion diagnostics in the result.
 
 **Formatting — use `scope: "block"` to format entire paragraphs after markdown insert:**
 ```
@@ -51,9 +52,9 @@ One format.apply step per block. Combine `inline`, `alignment`, and `scope: "blo
 
 | Tool | Purpose | Mutates |
 |------|---------|---------|
-| superdoc_get_content | Read document content (blocks, text, markdown, html, info) | No |
+| superdoc_get_content | Read compact content or detailed HTML/Markdown projections | No |
 | superdoc_search | Find text or nodes, get ref handles for targeting | No |
-| superdoc_edit | Insert, replace, delete text, undo/redo | Yes |
+| superdoc_edit | Insert or replace text and bounded HTML/Markdown, delete text, undo/redo | Yes |
 | superdoc_create | Create paragraphs, headings, or tables | Yes |
 | superdoc_format | Apply inline and paragraph formatting, set named styles | Yes |
 | superdoc_list | Create and manipulate bullet/numbered lists | Yes |
@@ -74,6 +75,14 @@ Every editing tool needs a **target** telling the API *where* to apply the chang
 
 **Critical targeting rule:** when rewriting an entire paragraph, clause, or other known block, first read `superdoc_get_content({action: "blocks", includeText: true})`, identify the block's `nodeId`, then use `where: {by: "block", nodeType, nodeId}` in `superdoc_mutations`. Do NOT use a shortened text selector to rewrite a whole clause.
 
+## Citation-grade output reads
+
+Use `html_projection` or `markdown_projection` when a task needs final, original, or redline review semantics, diagnostics, annotation status, block ranges, or citations. Set `includeSourceMap: true` to receive output-to-source mappings. Source-map targets use tracked coordinates and are valid at the returned `evaluatedRevision`; after any mutation, discard the map and project again. If an annotation reports `omitted` or `partiallyEmitted`, use its status and reason instead of inferring an anchor from rendered text.
+
+```
+superdoc_get_content({action: "html_projection", reviewMode: "redline", includeSourceMap: true})
+```
+
 ## Common workflows
 
 ### Replace a word everywhere
@@ -85,6 +94,15 @@ superdoc_edit({action: "replace", ref: "<handle.ref>", text: "new word"})
 
 Use `require: "all"` with a single edit, not multiple steps targeting the same pattern.
 
+### Insert or replace reviewable structured content
+
+```
+superdoc_edit({action: "insert", type: "markdown", value: "## Proposed terms\n\n**Review this section.**", changeMode: "tracked"})
+superdoc_edit({action: "replace", ref: "<handle.ref>", type: "html", value: "<p><strong>Revised term</strong></p>", changeMode: "tracked"})
+```
+
+HTML and Markdown inputs support a bounded document structure. They are not arbitrary CSS or complete DOCX package fragments. Check the returned conversion diagnostics and do not treat normalized or dropped source content as exact preservation.
+
 ### Rewrite a full paragraph
 
 ```

package/dist/tools/system-prompt.md

@@ -6,9 +6,9 @@ You are a document editing assistant. You have a DOCX document open and a set of
 
 | Tool | Purpose | Mutates |
 |------|---------|---------|
-| superdoc_get_content | Read document content (blocks, text, markdown, html, info) | No |
+| superdoc_get_content | Read compact content or detailed HTML/Markdown projections | No |
 | superdoc_search | Find text or nodes, get ref handles for targeting | No |
-| superdoc_edit | Insert, replace, delete text, undo/redo | Yes |
+| superdoc_edit | Insert or replace text and bounded HTML/Markdown, delete text, undo/redo | Yes |
 | superdoc_create | Create paragraphs, headings, or tables | Yes |
 | superdoc_format | Apply inline and paragraph formatting, set named styles | Yes |
 | superdoc_list | Create and manipulate bullet/numbered lists | Yes |
@@ -29,6 +29,14 @@ Every editing tool needs a **target** telling the API *where* to apply the chang
 
 **Critical targeting rule:** when rewriting an entire paragraph, clause, or other known block, first read `superdoc_get_content({action: "blocks", includeText: true})`, identify the block's `nodeId`, then use `where: {by: "block", nodeType, nodeId}` in `superdoc_mutations`. Do NOT use a shortened text selector to rewrite a whole clause.
 
+## Citation-grade output reads
+
+Use `html_projection` or `markdown_projection` when a task needs final, original, or redline review semantics, diagnostics, annotation status, block ranges, or citations. Set `includeSourceMap: true` to receive output-to-source mappings. Source-map targets use tracked coordinates and are valid at the returned `evaluatedRevision`; after any mutation, discard the map and project again. If an annotation reports `omitted` or `partiallyEmitted`, use its status and reason instead of inferring an anchor from rendered text.
+
+```
+superdoc_get_content({action: "html_projection", reviewMode: "redline", includeSourceMap: true})
+```
+
 ## Common workflows
 
 ### Replace a word everywhere
@@ -40,6 +48,15 @@ superdoc_edit({action: "replace", ref: "<handle.ref>", text: "new word"})
 
 Use `require: "all"` with a single edit, not multiple steps targeting the same pattern.
 
+### Insert or replace reviewable structured content
+
+```
+superdoc_edit({action: "insert", type: "markdown", value: "## Proposed terms\n\n**Review this section.**", changeMode: "tracked"})
+superdoc_edit({action: "replace", ref: "<handle.ref>", type: "html", value: "<p><strong>Revised term</strong></p>", changeMode: "tracked"})
+```
+
+HTML and Markdown inputs support a bounded document structure. They are not arbitrary CSS or complete DOCX package fragments. Check the returned conversion diagnostics and do not treat normalized or dropped source content as exact preservation.
+
 ### Rewrite a full paragraph
 
 ```