@superdoc-dev/sdk 1.0.0-alpha.3 → 1.0.0-alpha.31

package/dist/tools.d.ts

@@ -0,0 +1,90 @@
+import type { InvokeOptions } from './runtime/process.js';
+export type ToolProvider = 'openai' | 'anthropic' | 'vercel' | 'generic';
+export type ToolGroup = 'core' | 'format' | 'create' | 'tables' | 'sections' | 'lists' | 'comments' | 'trackChanges' | 'toc' | 'images' | 'history' | 'session';
+export type ToolChooserMode = 'essential' | 'all';
+export type ToolChooserInput = {
+    provider: ToolProvider;
+    groups?: ToolGroup[];
+    /** Default: 'essential'. When 'essential', only essential tools are returned (plus any from `groups`). */
+    mode?: ToolChooserMode;
+    /** Whether to include the discover_tools meta-tool. Default: true when mode='essential', false when mode='all'. */
+    includeDiscoverTool?: boolean;
+};
+export type ToolCatalog = {
+    contractVersion: string;
+    generatedAt: string | null;
+    namePolicyVersion: string;
+    exposureVersion: string;
+    toolCount: number;
+    tools: ToolCatalogEntry[];
+};
+type ToolCatalogEntry = {
+    operationId: string;
+    toolName: string;
+    profile: string;
+    source: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    mutates: boolean;
+    category: string;
+    essential?: boolean;
+    capabilities: string[];
+    constraints?: Record<string, unknown>;
+    errors: string[];
+    examples: unknown[];
+    commandTokens: string[];
+    profileTags: string[];
+    requiredCapabilities: string[];
+    sessionRequirements: {
+        requiresOpenContext: boolean;
+        supportsSessionTargeting: boolean;
+    };
+    intentId?: string;
+};
+/** All available tool groups from the policy. */
+export declare function getAvailableGroups(): ToolGroup[];
+export declare function getToolCatalog(): Promise<ToolCatalog>;
+export declare function listTools(provider: ToolProvider): Promise<unknown[]>;
+export declare function resolveToolOperation(toolName: string): Promise<string | null>;
+/**
+ * Select tools for a specific provider.
+ *
+ * **mode='essential'** (default): Returns only essential tools + discover_tools.
+ * Pass `groups` to additionally load all tools from those categories.
+ *
+ * **mode='all'**: Returns all tools from requested groups (or all groups if
+ * `groups` is omitted). No discover_tools included by default.
+ *
+ * @example
+ * ```ts
+ * // Default: 5 essential tools + discover_tools
+ * const { tools } = await chooseTools({ provider: 'openai' });
+ *
+ * // Essential + all comment tools
+ * const { tools } = await chooseTools({ provider: 'openai', groups: ['comments'] });
+ *
+ * // All tools (old behavior)
+ * const { tools } = await chooseTools({ provider: 'openai', mode: 'all' });
+ * ```
+ */
+export declare function chooseTools(input: ToolChooserInput): Promise<{
+    tools: unknown[];
+    selected: Array<{
+        operationId: string;
+        toolName: string;
+        category: string;
+        mutates: boolean;
+    }>;
+    meta: {
+        provider: ToolProvider;
+        mode: string;
+        groups: string[];
+        selectedCount: number;
+    };
+}>;
+export declare function dispatchSuperDocTool(client: {
+    doc: Record<string, unknown>;
+}, toolName: string, args?: Record<string, unknown>, invokeOptions?: InvokeOptions): Promise<unknown>;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -0,0 +1,296 @@
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONTRACT } from './generated/contract.js';
+import { SuperDocCliError } from './runtime/errors.js';
+// Resolve tools directory relative to package root (works from both src/ and dist/)
+const toolsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'tools');
+const providerFileByName = {
+    openai: 'tools.openai.json',
+    anthropic: 'tools.anthropic.json',
+    vercel: 'tools.vercel.json',
+    generic: 'tools.generic.json',
+};
+let _policyCache = null;
+function loadPolicy() {
+    if (_policyCache)
+        return _policyCache;
+    const raw = readFileSync(path.join(toolsDir, 'tools-policy.json'), 'utf8');
+    _policyCache = JSON.parse(raw);
+    return _policyCache;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value != null && !Array.isArray(value);
+}
+function isPresent(value) {
+    if (value == null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+function extractProviderToolName(tool) {
+    // Anthropic / Generic: top-level name
+    if (typeof tool.name === 'string')
+        return tool.name;
+    // OpenAI / Vercel: nested under function.name
+    if (isRecord(tool.function) && typeof tool.function.name === 'string') {
+        return tool.function.name;
+    }
+    return null;
+}
+function invalidArgument(message, details) {
+    throw new SuperDocCliError(message, { code: 'INVALID_ARGUMENT', details });
+}
+async function readJson(fileName) {
+    const filePath = path.join(toolsDir, fileName);
+    let raw = '';
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        throw new SuperDocCliError('Unable to load packaged tool artifact.', {
+            code: 'TOOLS_ASSET_NOT_FOUND',
+            details: {
+                filePath,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new SuperDocCliError('Packaged tool artifact is invalid JSON.', {
+            code: 'TOOLS_ASSET_INVALID',
+            details: {
+                filePath,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+async function loadProviderBundle(provider) {
+    return readJson(providerFileByName[provider]);
+}
+async function loadToolNameMap() {
+    return readJson('tool-name-map.json');
+}
+async function loadCatalog() {
+    return readJson('catalog.json');
+}
+/** All available tool groups from the policy. */
+export function getAvailableGroups() {
+    const policy = loadPolicy();
+    return policy.groups;
+}
+const OPERATION_INDEX = Object.fromEntries(Object.entries(CONTRACT.operations).map(([id, op]) => [id, op]));
+function validateDispatchArgs(operationId, args) {
+    const operation = OPERATION_INDEX[operationId];
+    if (!operation) {
+        invalidArgument(`Unknown operation id ${operationId}.`);
+    }
+    // Unknown-param rejection
+    const allowedParams = new Set(operation.params.map((param) => String(param.name)));
+    for (const key of Object.keys(args)) {
+        if (!allowedParams.has(key)) {
+            invalidArgument(`Unexpected parameter ${key} for ${operationId}.`);
+        }
+    }
+    // Required-param enforcement
+    for (const param of operation.params) {
+        if ('required' in param && Boolean(param.required) && args[param.name] == null) {
+            invalidArgument(`Missing required parameter ${param.name} for ${operationId}.`);
+        }
+    }
+    // Constraint validation (CLI handles schema-level type validation authoritatively)
+    const constraints = 'constraints' in operation ? operation.constraints : undefined;
+    if (!constraints || !isRecord(constraints))
+        return;
+    const mutuallyExclusive = Array.isArray(constraints.mutuallyExclusive) ? constraints.mutuallyExclusive : [];
+    const requiresOneOf = Array.isArray(constraints.requiresOneOf) ? constraints.requiresOneOf : [];
+    const requiredWhen = Array.isArray(constraints.requiredWhen) ? constraints.requiredWhen : [];
+    for (const group of mutuallyExclusive) {
+        if (!Array.isArray(group))
+            continue;
+        const present = group.filter((name) => isPresent(args[name]));
+        if (present.length > 1) {
+            invalidArgument(`Arguments are mutually exclusive for ${operationId}: ${group.join(', ')}`, {
+                operationId,
+                group,
+            });
+        }
+    }
+    for (const group of requiresOneOf) {
+        if (!Array.isArray(group))
+            continue;
+        const hasAny = group.some((name) => isPresent(args[name]));
+        if (!hasAny) {
+            invalidArgument(`One of the following arguments is required for ${operationId}: ${group.join(', ')}`, {
+                operationId,
+                group,
+            });
+        }
+    }
+    for (const rule of requiredWhen) {
+        if (!isRecord(rule))
+            continue;
+        const whenValue = args[rule.whenParam];
+        let shouldRequire = false;
+        if (Object.prototype.hasOwnProperty.call(rule, 'equals')) {
+            shouldRequire = whenValue === rule.equals;
+        }
+        else if (Object.prototype.hasOwnProperty.call(rule, 'present')) {
+            const present = rule.present === true;
+            shouldRequire = present ? isPresent(whenValue) : !isPresent(whenValue);
+        }
+        else {
+            shouldRequire = isPresent(whenValue);
+        }
+        if (shouldRequire && !isPresent(args[rule.param])) {
+            invalidArgument(`Argument ${rule.param} is required by constraints for ${operationId}.`, {
+                operationId,
+                rule,
+            });
+        }
+    }
+}
+function resolveDocApiMethod(client, operationId) {
+    const tokens = operationId.split('.').slice(1);
+    let cursor = client.doc;
+    for (const token of tokens) {
+        if (!isRecord(cursor) || !(token in cursor)) {
+            throw new SuperDocCliError(`No SDK doc method found for operation ${operationId}.`, {
+                code: 'TOOL_DISPATCH_NOT_FOUND',
+                details: { operationId, token },
+            });
+        }
+        cursor = cursor[token];
+    }
+    if (typeof cursor !== 'function') {
+        throw new SuperDocCliError(`Resolved member for ${operationId} is not callable.`, {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+            details: { operationId },
+        });
+    }
+    return cursor;
+}
+export async function getToolCatalog() {
+    return loadCatalog();
+}
+export async function listTools(provider) {
+    const bundle = await loadProviderBundle(provider);
+    const tools = bundle.tools;
+    if (!Array.isArray(tools)) {
+        throw new SuperDocCliError('Tool provider bundle is missing tools array.', {
+            code: 'TOOLS_ASSET_INVALID',
+            details: { provider },
+        });
+    }
+    return tools;
+}
+export async function resolveToolOperation(toolName) {
+    const map = await loadToolNameMap();
+    return typeof map[toolName] === 'string' ? map[toolName] : null;
+}
+/**
+ * Select tools for a specific provider.
+ *
+ * **mode='essential'** (default): Returns only essential tools + discover_tools.
+ * Pass `groups` to additionally load all tools from those categories.
+ *
+ * **mode='all'**: Returns all tools from requested groups (or all groups if
+ * `groups` is omitted). No discover_tools included by default.
+ *
+ * @example
+ * ```ts
+ * // Default: 5 essential tools + discover_tools
+ * const { tools } = await chooseTools({ provider: 'openai' });
+ *
+ * // Essential + all comment tools
+ * const { tools } = await chooseTools({ provider: 'openai', groups: ['comments'] });
+ *
+ * // All tools (old behavior)
+ * const { tools } = await chooseTools({ provider: 'openai', mode: 'all' });
+ * ```
+ */
+export async function chooseTools(input) {
+    const catalog = await loadCatalog();
+    const policy = loadPolicy();
+    const mode = input.mode ?? policy.defaults.mode ?? 'essential';
+    const includeDiscover = input.includeDiscoverTool ?? mode === 'essential';
+    let selected;
+    if (mode === 'essential') {
+        // Essential tools + any explicitly requested groups
+        const essentialNames = new Set(policy.essentialTools ?? []);
+        const requestedGroups = input.groups ? new Set(input.groups) : null;
+        selected = catalog.tools.filter((tool) => {
+            if (essentialNames.has(tool.toolName))
+                return true;
+            if (requestedGroups && requestedGroups.has(tool.category))
+                return true;
+            return false;
+        });
+    }
+    else {
+        // mode='all': original behavior — filter by groups
+        const alwaysInclude = new Set(policy.defaults.alwaysInclude ?? ['core']);
+        let groups;
+        if (input.groups) {
+            groups = new Set([...input.groups, ...alwaysInclude]);
+        }
+        else {
+            groups = new Set(policy.groups);
+        }
+        selected = catalog.tools.filter((tool) => groups.has(tool.category));
+    }
+    // Build provider-formatted tools from the provider bundle
+    const bundle = await loadProviderBundle(input.provider);
+    const providerTools = Array.isArray(bundle.tools) ? bundle.tools : [];
+    const providerIndex = new Map(providerTools
+        .filter((tool) => isRecord(tool))
+        .map((tool) => [extractProviderToolName(tool), tool])
+        .filter((entry) => entry[0] !== null));
+    const selectedProviderTools = selected
+        .map((tool) => providerIndex.get(tool.toolName))
+        .filter((tool) => Boolean(tool));
+    // Append discover_tools if requested
+    if (includeDiscover) {
+        const discoverTool = providerIndex.get('discover_tools');
+        if (discoverTool) {
+            selectedProviderTools.push(discoverTool);
+        }
+    }
+    const resolvedGroups = mode === 'essential' ? (input.groups ?? []) : (input.groups ?? policy.groups);
+    return {
+        tools: selectedProviderTools,
+        selected: selected.map((tool) => ({
+            operationId: tool.operationId,
+            toolName: tool.toolName,
+            category: tool.category,
+            mutates: tool.mutates,
+        })),
+        meta: {
+            provider: input.provider,
+            mode,
+            groups: [...resolvedGroups],
+            selectedCount: selectedProviderTools.length,
+        },
+    };
+}
+export async function dispatchSuperDocTool(client, toolName, args = {}, invokeOptions) {
+    const operationId = await resolveToolOperation(toolName);
+    if (!operationId) {
+        throw new SuperDocCliError(`Unknown SuperDoc tool: ${toolName}`, {
+            code: 'TOOL_NOT_FOUND',
+            details: { toolName },
+        });
+    }
+    if (!isRecord(args)) {
+        invalidArgument(`Tool arguments for ${toolName} must be an object.`);
+    }
+    validateDispatchArgs(operationId, args);
+    const method = resolveDocApiMethod(client, operationId);
+    return method(args, invokeOptions);
+}

package/package.json

@@ -1,31 +1,41 @@
 {
   "name": "@superdoc-dev/sdk",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.31",
   "private": false,
   "type": "module",
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
   "files": [
-    "src",
+    "dist",
     "skills",
     "tools"
   ],
-  "optionalDependencies": {
-    "@superdoc-dev/sdk-darwin-arm64": "1.0.0-alpha.3",
-    "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.3",
-    "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.3",
-    "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.3",
-    "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.3"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.8",
     "@types/node": "22.19.2",
+    "rollup": "^4.31.0",
     "typescript": "^5.9.2"
   },
+  "optionalDependencies": {
+    "@superdoc-dev/sdk-darwin-arm64": "1.0.0-alpha.31",
+    "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.31",
+    "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.31",
+    "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.31",
+    "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.31"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "build": "tsc && rollup -c rollup.cjs.config.mjs",
     "typecheck": "tsc --noEmit"
   }
 }

package/skills/editing-docx.md

@@ -1,157 +1,31 @@
----
-name: superdoc
-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.
-- Deterministic tracked-change outcomes:
-  - unknown/stale ids -> `TRACK_CHANGE_NOT_FOUND`
-  - no applicable `accept-all`/`reject-all` change -> `NO_OP` receipt
-  - missing tracking capability -> `TRACK_CHANGE_COMMAND_UNAVAILABLE`
-
-## 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