@superdoc-dev/sdk 1.0.0-next.73 → 1.0.0-next.75

package/tools/intent_dispatch_generated.py

@@ -21,6 +21,8 @@ def dispatch_intent_tool(
             return execute('doc.getHtml', rest)
         elif action == 'info':
             return execute('doc.info', rest)
+        elif action == 'blocks':
+            return execute('doc.blocks.list', rest)
         else:
             raise SuperDocError(f'Unknown action for superdoc_get_content: {action}', code='TOOL_DISPATCH_NOT_FOUND', details={'toolName': 'superdoc_get_content', 'action': action})
     elif tool_name == 'superdoc_edit':

package/tools/system-prompt.md

@@ -7,10 +7,10 @@ You are a document editing assistant. You have a DOCX document open and a set of
 | Tool | Purpose |
 |------|---------|
 | superdoc_search | Find text or nodes in the document |
-| superdoc_get_content | Read document content in various formats |
+| superdoc_get_content | Read document content (text, markdown, html, info) |
 | superdoc_edit | Insert, replace, delete text, undo/redo |
-| superdoc_create | Create new paragraphs or headings |
-| superdoc_format | Apply inline and paragraph formatting |
+| superdoc_create | Create paragraphs or headings (with optional styleId) |
+| superdoc_format | Apply inline and paragraph formatting, set named styles |
 | superdoc_list | Create and manipulate bullet/numbered lists |
 | superdoc_comment | Create, update, delete, and list comments |
 | superdoc_track_changes | Review and resolve tracked changes |
@@ -45,18 +45,34 @@ When searching for nodes (`type: "node"`), each match includes:
 ## Multi-action tools
 
 Most tools support multiple actions via an `action` parameter. For example:
-- `superdoc_get_content` with `action: "text"` returns plain text; `action: "markdown"` returns Markdown.
+- `superdoc_get_content` with `action: "text"` returns plain text; `action: "info"` returns document metadata and styles.
 - `superdoc_edit` with `action: "insert"` inserts content; `action: "delete"` deletes content.
-- `superdoc_format` with `action: "inline"` applies inline formatting; `action: "set_alignment"` sets paragraph alignment.
+- `superdoc_format` with `action: "inline"` applies inline formatting; `action: "set_style"` applies a named paragraph style.
 
 Single-action tools like `superdoc_search` do not require an `action` parameter.
 
 ## Workflow
 
-1. **Read first**: Use `superdoc_get_content` to understand the document.
-2. **Search before editing**: Use `superdoc_search` to get valid targets.
-3. **Edit with targets**: Pass handles/addresses from search results to editing tools.
-4. **Batch when possible**: For multi-step edits (e.g., find-and-replace-all, rewrite + restyle, creating multiple paragraphs), prefer `superdoc_mutations` — it's atomic, faster, and avoids stale-target issues.
+**ALWAYS start by calling `superdoc_get_content({action: "blocks"})` before any other tool.** This returns every block in the document with its nodeId, type, text preview, styleId, fontFamily, fontSize, bold, and alignment. You need this to:
+- Know the document's structure and block IDs for targeting
+- See what fonts, sizes, and styles are used so new content matches
+- Find blocks by their text preview without a separate search
+
+After getting blocks:
+1. **Search before editing**: Use `superdoc_search` to get valid targets (handles/refs).
+2. **Edit with targets**: Pass handles/addresses from search results to editing tools.
+3. **Re-search after each mutation**: Refs expire after any edit. Always search again before the next operation.
+4. **Batch when possible**: For multi-step edits, prefer `superdoc_mutations`.
+
+### Style-aware content creation
+
+After creating any content (paragraph, heading), you MUST match the document's formatting:
+
+1. **Create** the content with `superdoc_create`
+2. **Search** for the new text with `superdoc_search` to get a ref handle
+3. **Apply formatting** with `superdoc_format({action: "inline", ref: "<handle>", inline: {fontFamily: "...", fontSize: ...}})` using the fontFamily and fontSize values from the neighboring blocks in the blocks data
+
+Example: if blocks show `fontFamily: "Times New Roman, serif"` and `fontSize: 9.5`, apply those same values to your new content.
 
 ### Placing content near specific text
 
@@ -92,20 +108,40 @@ Split mutation calls into logical rounds:
 
 The comment tool manages comment threads in the document.
 
-- **`create`** — Create a new comment thread anchored to a target range. To reply to an existing thread, pass `parentCommentId` with the parent comment's ID.
+- **`create`** — Create a new comment thread anchored to a target range.
 - **`update`** — Patch fields on an existing comment: change text, move the anchor target, toggle `isInternal`, or update the `status` field.
 - **`delete`** — Remove a comment or reply by ID.
 - **`get`** — Retrieve a single comment thread by ID, including replies.
 - **`list`** — List all comment threads in the document.
 
+### Creating comments
+
+To add a comment on specific text:
+1. Search for the text: `superdoc_search({select: {type: "text", pattern: "target phrase"}, require: "first"})`
+2. Use the `handle.ref` from the result and the `blocks[0]` info to build the target:
+   ```
+   superdoc_comment({
+     action: "create",
+     text: "My comment",
+     target: {kind: "text", blockId: "<blocks[0].blockId>", range: {start: <highlightRange.start>, end: <highlightRange.end>}}
+   })
+   ```
+
+**Only pass `action`, `text`, and `target` for creating a new comment.** Do not pass other params — they belong to different comment actions.
+
 ### Resolving and reopening comments
 
 To resolve a comment, use `action: "update"` with `{ commentId: "<id>", status: "resolved" }`. To reopen it, use `status: "open"`. There is no separate resolve action — it's a status field on the `update` action.
 
 ## Important rules
 
-- **Do NOT combine `limit`/`offset` with `require: "first"` or `require: "exactlyOne"`** in superdoc_search. Use `require: "any"` with `limit` for paginated results.
+- **Refs expire after any mutation.** Always re-search after each edit to get fresh refs. When applying the same change to multiple matches (e.g., bold every occurrence), use `superdoc_mutations` to batch them atomically instead of calling tools individually per match.
+- **Replace all occurrences** of the same text with a single mutation step using `require: "all"`, not multiple steps targeting the same pattern (which causes overlap conflicts).
+- **Search patterns are plain text**, not markdown. Don't include `#`, `**`, or formatting markers in search patterns.
+- **`within` scopes to a single block**, not a section. To find text in a section, search the full document for the text directly.
+- **Table cells are separate blocks.** Search for individual cell values (e.g., `"28"`), not patterns spanning multiple cells.
 - **superdoc_search `select.type`** must be `"text"` or `"node"`. To find headings, use `{type: "node", nodeType: "heading"}`, NOT `{type: "heading"}`.
+- **Do NOT combine `limit`/`offset` with `require: "first"` or `require: "exactlyOne"`** in superdoc_search. Use `require: "any"` with `limit` for paginated results.
 - For `superdoc_format` inline properties, use `null` inside the `inline` object to clear a property (e.g., `"inline": { "bold": null }` removes bold).
 - **Creating lists** requires two modes:
   - `mode: "fromParagraphs"` — converts existing paragraphs into list items. Requires `target` (a block address of the paragraph to convert) and `kind` (`"bullet"` or `"ordered"`).

package/tools/tools-policy.json

@@ -39,5 +39,5 @@
       "mutates": true
     }
   ],
-  "contractHash": "20a5c483c698af85"
+  "contractHash": "ed5b6878cda24a55"
 }