@superdoc-dev/cli 0.2.0-next.99 → 0.3.0-next.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli",
-  "version": "0.2.0-next.99",
+  "version": "0.3.0-next.1",
   "type": "module",
   "bin": {
     "superdoc": "./dist/index.js"
@@ -21,20 +21,20 @@
     "@types/node": "22.19.2",
     "typescript": "^5.9.2",
     "@superdoc/pm-adapter": "0.0.0",
-    "superdoc": "1.18.0",
+    "@superdoc/document-api": "0.0.1",
     "@superdoc/super-editor": "0.0.1",
-    "@superdoc/document-api": "0.0.1"
+    "superdoc": "1.19.0"
   },
   "module": "src/index.ts",
   "publishConfig": {
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc-dev/cli-darwin-arm64": "0.2.0-next.99",
-    "@superdoc-dev/cli-darwin-x64": "0.2.0-next.99",
-    "@superdoc-dev/cli-linux-x64": "0.2.0-next.99",
-    "@superdoc-dev/cli-linux-arm64": "0.2.0-next.99",
-    "@superdoc-dev/cli-windows-x64": "0.2.0-next.99"
+    "@superdoc-dev/cli-darwin-arm64": "0.3.0-next.1",
+    "@superdoc-dev/cli-darwin-x64": "0.3.0-next.1",
+    "@superdoc-dev/cli-windows-x64": "0.3.0-next.1",
+    "@superdoc-dev/cli-linux-arm64": "0.3.0-next.1",
+    "@superdoc-dev/cli-linux-x64": "0.3.0-next.1"
   },
   "scripts": {
     "dev": "bun run src/index.ts",

package/skill/SKILL.md

@@ -1,45 +1,96 @@
 ---
 name: editing-docx
-description: Searches, replaces, and reads text in Word documents. Use when the user asks to edit, search, or extract text from .docx files.
+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.
 ---
 
-# SuperDoc CLI
+# SuperDoc CLI (v1)
 
-Edit Word documents from the command line. Use instead of python-docx.
+Use SuperDoc CLI for DOCX work. Prefer canonical v1 commands.
+Do not default to legacy commands unless explicitly needed for v0-style bulk workflows.
 
-## Commands
+Use `superdoc` if installed, or `npx @superdoc-dev/cli@latest` as a fallback.
 
-| Command | Description |
-|---------|-------------|
-| `npx @superdoc-dev/cli@latest search <pattern> <files...>` | Find text across documents |
-| `npx @superdoc-dev/cli@latest replace-legacy <find> <to> <files...>` | Find and replace text |
-| `npx @superdoc-dev/cli@latest read <file>` | Extract plain text |
+## First Step: Discover Exact Params
 
-## When to Use
+For unknown commands or flags, inspect runtime metadata first:
 
-Use superdoc when the user asks to:
-- Search text in .docx files
-- Find and replace text in Word documents
-- Extract text content from .docx files
-- Bulk edit multiple Word documents
+```bash
+superdoc describe
+superdoc describe command find
+superdoc describe command "comments add"
+```
+
+Use `describe command` for per-command args and constraints.
 
-## Examples
+## Preferred Workflows
+
+### 1) Stateful multi-step edits (recommended)
 
 ```bash
-# Search across documents
-npx @superdoc-dev/cli@latest search "indemnification" ./contracts/*.docx
+superdoc open ./contract.docx
+superdoc find --type text --pattern "termination"
+superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":11}}' --text "expiration"
+superdoc save --in-place
+superdoc close
+```
 
-# Find and replace
-npx @superdoc-dev/cli@latest replace-legacy "ACME Corp" "Globex Inc" ./merger/*.docx
+- 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`.
 
-# Extract text
-npx @superdoc-dev/cli@latest read ./proposal.docx
+### 2) Stateless one-off reads
 
-# JSON output for scripting
-npx @superdoc-dev/cli@latest search "Article 7" ./**/*.docx --json
+```bash
+superdoc get-text ./proposal.docx
+superdoc get-markdown ./proposal.docx
+superdoc info ./proposal.docx
 ```
 
-## Options
+### 3) Stateless one-off mutations
+
+```bash
+superdoc replace ./proposal.docx \
+  --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":5}}' \
+  --text "Updated" \
+  --out ./proposal.updated.docx
+```
+
+- In stateless mode (`<doc>` provided), mutating commands require `--out` unless using `--dry-run`.
+
+## Common v1 Commands
+
+- Search text/nodes: `find --type text --pattern "..."` or `find --query-json '{...}'`
+- Replace text: `replace --target-json '{...}' --text "..."`
+- Add/edit comments: `comments add|reply|edit|resolve|remove`
+- Review tracked changes: `track-changes list|accept|reject|accept-all|reject-all`
+- Extract content: `get-text`, `get-markdown`, `get-html`
+- Low-level direct invoke: `call <operationId> --input-json '{...}'`
+
+## JSON/File Payload Flags
+
+Use one of each pair (not both):
+
+- `--query-json` or `--query-file`
+- `--target-json` or `--target-file`
+- `--address-json` or `--address-file`
+- `--input-json` or `--input-file` (for `call`)
+
+## Output and Global Flags
+
+- Default output is JSON envelope.
+- Use `--pretty` for human-readable output.
+- Global flags: `--output <json|pretty>`, `--session <id>`, `--timeout-ms <n>`.
+- `<doc>` can be `-` to read DOCX bytes from stdin.
+
+## Legacy Compatibility (Use Sparingly)
+
+Legacy v0.x bridge commands still exist:
+
+```bash
+superdoc search <pattern> <files...>
+superdoc replace-legacy <find> <to> <files...>
+superdoc read <file>
+```
 
-- `--json` — Machine-readable output
-- `--help` — Show help
+Use these only when you specifically need v0-style behavior (especially multi-file glob search/replace).
+For new automations, prefer v1 operations.