@superdoc-dev/cli 0.5.0-next.8 → 0.5.0-next.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli",
-  "version": "0.5.0-next.8",
+  "version": "0.5.0-next.81",
   "type": "module",
   "bin": {
     "superdoc": "./dist/index.js"
@@ -11,8 +11,8 @@
   ],
   "dependencies": {
     "@hocuspocus/provider": "^2.13.6",
-    "@liveblocks/client": "^3.11.0",
-    "@liveblocks/yjs": "^3.11.0",
+    "@liveblocks/client": "^3.15.5",
+    "@liveblocks/yjs": "^3.15.5",
     "fast-glob": "^3.3.3",
     "happy-dom": "^20.3.4",
     "ws": "^8.18.0",
@@ -25,20 +25,20 @@
     "@types/ws": "^8.5.13",
     "typescript": "^5.9.2",
     "@superdoc/document-api": "0.0.1",
+    "@superdoc/super-editor": "0.0.1",
     "@superdoc/pm-adapter": "0.0.0",
-    "superdoc": "1.23.0",
-    "@superdoc/super-editor": "0.0.1"
+    "superdoc": "1.25.0"
   },
   "module": "src/index.ts",
   "publishConfig": {
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc-dev/cli-darwin-arm64": "0.5.0-next.8",
-    "@superdoc-dev/cli-darwin-x64": "0.5.0-next.8",
-    "@superdoc-dev/cli-linux-x64": "0.5.0-next.8",
-    "@superdoc-dev/cli-linux-arm64": "0.5.0-next.8",
-    "@superdoc-dev/cli-windows-x64": "0.5.0-next.8"
+    "@superdoc-dev/cli-darwin-arm64": "0.5.0-next.81",
+    "@superdoc-dev/cli-darwin-x64": "0.5.0-next.81",
+    "@superdoc-dev/cli-linux-x64": "0.5.0-next.81",
+    "@superdoc-dev/cli-linux-arm64": "0.5.0-next.81",
+    "@superdoc-dev/cli-windows-x64": "0.5.0-next.81"
   },
   "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)