@superdoc-dev/sdk 1.0.0-alpha.2 → 1.0.0-alpha.22

package/skills/editing-docx.md

@@ -1,153 +1,31 @@
----
-name: editing-docx
-description: Session-first SuperDoc CLI workflows for querying and editing DOCX files (find/inspect, comments lifecycle, text mutations, tracked-changes review, and close safely).
----
+# Editing DOCX Documents with SuperDoc SDK
 
-# SuperDoc Playground Skill
+You are a document editing assistant using the SuperDoc SDK. You have access to tools
+that let you open, read, search, and modify `.docx` files programmatically.
 
-Use this skill for manual DOCX exploration/editing in Codex CLI or Claude CLI.
+## Workflow
 
-## Interaction Rules (Must Follow)
+1. **Open** the document with `doc.open`
+2. **Inspect** it with `doc.info` to understand structure
+3. **Find** content with `doc.find` using text search or node type queries
+4. **Modify** content using `doc.insert`, `doc.replace`, `doc.delete`, or formatting operations
+5. **Save** changes with `doc.save`
+6. **Close** when done with `doc.close`
 
-1. Always run CLI commands in JSON mode: `--output json`.
-2. Prefer session mode: `open` once, then run commands without `<doc>`.
-3. Treat CLI envelopes as truth (`ok`, `data`, `error`).
-4. Re-query before mutating if target addresses might be stale.
-5. If matches are ambiguous, ask user which match(es) to modify.
-6. End every workflow with an explicit persistence + close decision:
-   - `save --out ...` then `close`
-   - `save --in-place` then `close`
-   - `close --discard`
+## Key Operations
 
-## CLI Invocation
+- `doc.find` — Search by text pattern, node type, or structured query
+- `doc.getNode` — Get a specific node by address
+- `doc.insert` — Insert text at a position
+- `doc.replace` — Replace content at a position
+- `doc.delete` — Delete content at a position
+- `doc.format.*` — Apply bold, italic, underline, strikethrough
+- `doc.comments.*` — Add, edit, resolve, remove comments
+- `doc.trackChanges.*` — Accept/reject tracked changes
 
-Use `superdoc ...` commands.
+## Best Practices
 
-If `superdoc` is not installed in this repo environment, use:
-`bun apps/cli-alpha/src/index.ts ...`
-
-## Canonical Session Workflow
-
-1. Open a session:
-```bash
-superdoc open ./contract.docx --output json
-```
-2. Query and inspect:
-```bash
-superdoc describe --output json
-superdoc describe command doc.find --output json
-superdoc info --output json
-superdoc find --type text --pattern "termination" --output json
-superdoc get-node --address-json '{"kind":"block","nodeType":"paragraph","nodeId":"p1"}' --output json
-```
-3. Mutate (using target JSON from `find` results):
-```bash
-superdoc comments add --target-json '{"kind":"text","blockId":"p1","range":{"start":10,"end":20}}' --text "Please clarify this clause." --output json
-superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":10,"end":20}}' --text "Updated clause text" --dry-run --output json
-superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":10,"end":20}}' --text "Updated clause text" --output json
-```
-4. Verify:
-```bash
-superdoc find --type text --pattern "Updated clause text" --output json
-```
-5. Save and close:
-```bash
-superdoc save --out ./contract.reviewed.docx --output json
-superdoc close --output json
-```
-
-## Command Patterns (Session Mode)
-
-### Session lifecycle
-- `superdoc open <doc> [--session <id>] --output json`
-- `superdoc status [--session <id>] --output json`
-- `superdoc save [--in-place] [--out <path>] [--force] --output json`
-- `superdoc close [--discard] --output json`
-- `superdoc session list --output json`
-- `superdoc session save <id> [--in-place] [--out <path>] [--force] --output json`
-- `superdoc session use <id> --output json`
-- `superdoc session set-default <id> --output json`
-- `superdoc session close <id> --discard --output json`
-
-### Query
-- `superdoc describe --output json`
-- `superdoc describe command <operationId> --output json`
-- `superdoc info --output json`
-- `superdoc find --type text --pattern "<text>" --output json`
-- `superdoc find --query-json '{...}' --output json`
-- `superdoc get-node --address-json '{...}' --output json`
-- `superdoc get-node-by-id --id <nodeId> [--node-type <type>] --output json`
-
-### Mutate
-- `superdoc create paragraph [--input-json '{...}'] [--text "..."] [--at document-start|document-end] [--before-address-json '{...}'] [--after-address-json '{...}'] [--dry-run] [--change-mode direct|tracked] --output json`
-- `superdoc comments add --target-json '{...}' --text "..." --output json`
-- `superdoc comments edit --id <commentId> --text "..." [--expected-revision <n>] [--force] --output json`
-- `superdoc comments reply --parent-id <commentId> --text "..." [--expected-revision <n>] [--force] --output json`
-- `superdoc comments move --id <commentId> --target-json '{...}' [--expected-revision <n>] [--force] --output json`
-- `superdoc comments resolve --id <commentId> [--expected-revision <n>] [--force] --output json`
-- `superdoc comments remove --id <commentId> [--expected-revision <n>] [--force] --output json`
-- `superdoc comments set-internal --id <commentId> --is-internal <true|false> [--expected-revision <n>] [--force] --output json`
-- `superdoc insert [--target-json '{...}'] --text "..." [--dry-run] [--change-mode direct|tracked] --output json`
-- `superdoc replace --target-json '{...}' --text "..." [--dry-run] [--change-mode direct|tracked] --output json`
-- `superdoc delete --target-json '{...}' [--dry-run] [--change-mode direct|tracked] --output json`
-- `superdoc format bold --target-json '{...}' [--dry-run] [--change-mode direct|tracked] --output json`
-
-### Comments read/navigation
-- `superdoc comments get --id <commentId> --output json`
-- `superdoc comments list [--include-resolved <true|false>] --output json`
-- `superdoc comments set-active --id <commentId> --output json`
-- `superdoc comments set-active --clear --output json`
-- `superdoc comments go-to --id <commentId> --output json`
-
-### Track changes
-- `superdoc track-changes list [--type insert|delete|format] [--limit <n>] [--offset <n>] --output json`
-- `superdoc track-changes get --id <trackedChangeId> --output json`
-- `superdoc track-changes accept --id <trackedChangeId> [--expected-revision <n>] [--force] --output json`
-- `superdoc track-changes reject --id <trackedChangeId> [--expected-revision <n>] [--force] --output json`
-- `superdoc track-changes accept-all [--expected-revision <n>] [--force] --output json`
-- `superdoc track-changes reject-all [--expected-revision <n>] [--force] --output json`
-
-### Stateless fallback
-If a command includes `<doc>` (or `--doc`), it runs statelessly for that call.
-For stateless mutate commands, provide `--out <path>`.
-
-## Target Selection Guidance
-
-- Prefer structural creation for new block insertion:
-  - `create paragraph` creates a new paragraph block and returns structural handles (`paragraph`, `insertionPoint`).
-- Prefer `find --type text --pattern ...` first.
-- Use `data.result.context[*].textRanges[*]` as `--target-json` for text edits/comments.
-- `insert` may omit `--target-json`; it defaults to the first editable insertion point (first paragraph start when available).
-- When multiple matches exist, apply a deterministic policy:
-  - first match only, or
-  - first N matches, or
-  - user-selected match indexes.
-- For uncertain targets, run `get-node` before mutate.
-
-## Mutation Mode Guidance
-
-- Use `--change-mode direct|tracked` to control whether edits create tracked changes.
-- `create paragraph` supports `--change-mode tracked` for tracked structural creation.
-- `replace`, `insert`, `delete`, and `format bold` support `--change-mode tracked`.
-- `track-changes *` commands are for review lifecycle (list/get/accept/reject), not content insertion.
-
-## Scenario Prompts (Copy/Paste)
-
-1. Open `./contracts/msa.docx`, find `termination`, add comments to the first 2 matches asking for clearer notice period, then save to `./contracts/msa.reviewed.docx`.
-2. Use the active session to find `governing law`, inspect the top match node, then add a concise legal-risk comment.
-3. Open two sessions (`vendor-a`, `vendor-b`) on different docs, switch between them, and add one comment in each.
-4. Run a redline pass replacing `shall` with `must` for the first 3 matches: dry-run first, then apply.
-5. Run `track-changes list`, inspect one change with `track-changes get`, then accept it by id.
-6. Open from stdin (`open -`), run `find`, add one comment, then `save --out` and `close`.
-
-## Collaboration (Node-Only, Optional)
-
-Use only when collaboration runtime is available in your environment.
-
-```bash
-superdoc open ./contract.docx --collaboration-json '{"providerType":"hocuspocus","url":"ws://localhost:1234","documentId":"contract-1","tokenEnv":"SUPERDOC_COLLAB_TOKEN"}' --output json
-```
-
-Notes:
-- Collaboration commands are command-scoped (connect -> sync -> operate -> disconnect).
-- Python collaboration is not supported; expect `NOT_SUPPORTED`.
+- Always open before operating, save when done
+- Use `doc.find` to locate content before modifying
+- Use `doc.info` to check document capabilities
+- Handle errors gracefully — operations may fail if targets are invalid