chore: cli improvements (#2570)

* chore: cli improvements

* fix: cli inline-special inserts at structural document end

* fix: cli and sdk validation

Author: harbournick

apps/cli/scripts/export-sdk-contract.ts

@@ -11,12 +11,12 @@
  * Check: bun run apps/cli/scripts/export-sdk-contract.ts --check
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { writeFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
-import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 
 import { COMMAND_CATALOG, INTENT_GROUP_META } from '@superdoc/document-api';
+import { buildContractSnapshot } from '@superdoc/document-api/scripts/lib/contract-snapshot.ts';
 
 import { CLI_OPERATION_METADATA } from '../src/cli/operation-params';
 import {
@@ -27,7 +27,7 @@ import {
   cliRequiresDocumentContext,
   toDocApiId,
 } from '../src/cli/operation-set';
-import type { CliOnlyOperation } from '../src/cli/types';
+import type { CliOnlyOperation, CliOperationParamSpec, CliTypeSpec } from '../src/cli/types';
 import { CLI_ONLY_OPERATION_DEFINITIONS } from '../src/cli/cli-only-operation-definitions';
 import { RESPONSE_ENVELOPE_KEY } from '../src/cli/operation-hints';
 import { HOST_PROTOCOL_VERSION, HOST_PROTOCOL_FEATURES, HOST_PROTOCOL_NOTIFICATIONS } from '../src/host/protocol';
@@ -48,29 +48,60 @@ function classifySdkSurface(operationId: string): SdkSurface {
   return 'document';
 }
 
+function buildParamSchema(param: CliOperationParamSpec): Record<string, unknown> {
+  let schema: Record<string, unknown>;
+
+  if (param.type === 'string' && param.schema) schema = { type: 'string', ...(param.schema as CliTypeSpec) };
+  else if (param.type === 'string') schema = { type: 'string' };
+  else if (param.type === 'number') schema = { type: 'number' };
+  else if (param.type === 'boolean') schema = { type: 'boolean' };
+  else if (param.type === 'string[]') schema = { type: 'array', items: { type: 'string' } };
+  else if (param.type === 'json' && param.schema && (param.schema as CliTypeSpec).type !== 'json') {
+    schema = { ...(param.schema as CliTypeSpec) };
+  } else {
+    schema = { type: 'object' };
+  }
+
+  if (param.description) schema.description = param.description;
+  return schema;
+}
+
+function buildCliOnlyInputSchema(
+  params: readonly CliOperationParamSpec[],
+  sdkSurface: SdkSurface,
+): Record<string, unknown> {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const required: string[] = [];
+
+  for (const param of params) {
+    if (param.agentVisible === false) continue;
+    if (sdkSurface === 'document' && (param.name === 'doc' || param.name === 'sessionId')) continue;
+
+    properties[param.name] = buildParamSchema(param);
+    if (param.required) required.push(param.name);
+  }
+
+  return {
+    type: 'object',
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+    additionalProperties: false,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
 
 const ROOT = resolve(import.meta.dir, '../../..');
 const CLI_DIR = resolve(ROOT, 'apps/cli');
-const CONTRACT_JSON_PATH = resolve(ROOT, 'packages/document-api/generated/schemas/document-api-contract.json');
 const OUTPUT_PATH = resolve(CLI_DIR, 'generated/sdk-contract.json');
 const CLI_PKG_PATH = resolve(CLI_DIR, 'package.json');
 
 // ---------------------------------------------------------------------------
 // Load inputs
 // ---------------------------------------------------------------------------
 
-function loadDocApiContract(): {
-  contractVersion: string;
-  $defs?: Record<string, unknown>;
-  operations: Record<string, Record<string, unknown>>;
-} {
-  const raw = readFileSync(CONTRACT_JSON_PATH, 'utf-8');
-  return JSON.parse(raw);
-}
-
 function loadCliPackage(): { name: string; version: string } {
   const raw = readFileSync(CLI_PKG_PATH, 'utf-8');
   return JSON.parse(raw);
@@ -81,10 +112,14 @@ function loadCliPackage(): { name: string; version: string } {
 // ---------------------------------------------------------------------------
 
 function buildSdkContract() {
-  const docApiContract = loadDocApiContract();
+  // Read the live document-api source snapshot instead of the generated JSON
+  // artifact. This keeps SDK export resilient when developers add operations
+  // before refreshing packages/document-api/generated/.
+  const docApiContract = buildContractSnapshot();
   const cliPkg = loadCliPackage();
-
-  const sourceHash = createHash('sha256').update(JSON.stringify(docApiContract)).digest('hex').slice(0, 16);
+  const docApiOperations = Object.fromEntries(
+    docApiContract.operations.map((operation) => [operation.operationId, operation]),
+  );
 
   const operations: Record<string, unknown> = {};
 
@@ -94,11 +129,12 @@ function buildSdkContract() {
     const stripped = cliOpId.slice(4) as CliOnlyOperation;
 
     const cliOnlyDef = docApiId ? null : CLI_ONLY_OPERATION_DEFINITIONS[stripped];
+    const sdkSurface = classifySdkSurface(cliOpId);
 
     // Base fields shared by all operations
     const entry: Record<string, unknown> = {
       operationId: cliOpId,
-      sdkSurface: classifySdkSurface(cliOpId),
+      sdkSurface,
       command: metadata.command,
       commandTokens: [...cliCommandTokens(cliOpId)],
       category: cliCategory(cliOpId),
@@ -135,21 +171,22 @@ function buildSdkContract() {
       entry.supportsTrackedMode = catalog.supportsTrackedMode;
       entry.supportsDryRun = catalog.supportsDryRun;
 
-      // Schema plane from document-api-contract.json
-      const docOp = docApiContract.operations[docApiId];
+      // Schema plane from the source snapshot.
+      const docOp = docApiOperations[docApiId];
       if (!docOp) {
-        throw new Error(`Missing document-api contract entry for ${docApiId}`);
+        throw new Error(`CLI operation ${cliOpId} maps to missing document-api source entry ${docApiId}.`);
       }
-      entry.inputSchema = docOp.inputSchema;
-      entry.outputSchema = docOp.outputSchema;
-      if (docOp.successSchema) entry.successSchema = docOp.successSchema;
-      if (docOp.failureSchema) entry.failureSchema = docOp.failureSchema;
+      entry.inputSchema = docOp.schemas.input;
+      entry.outputSchema = docOp.schemas.output;
+      if (docOp.schemas.success) entry.successSchema = docOp.schemas.success;
+      if (docOp.schemas.failure) entry.failureSchema = docOp.schemas.failure;
       if (docOp.skipAsATool) entry.skipAsATool = true;
       if (docOp.intentGroup) entry.intentGroup = docOp.intentGroup;
       if (docOp.intentAction) entry.intentAction = docOp.intentAction;
     } else {
       // CLI-only operation — metadata from canonical definitions
       const def = cliOnlyDef!;
+      entry.inputSchema = buildCliOnlyInputSchema(metadata.params, sdkSurface);
       entry.mutates = def.sdkMetadata.mutates;
       entry.idempotency = def.sdkMetadata.idempotency;
       entry.supportsTrackedMode = def.sdkMetadata.supportsTrackedMode;
@@ -168,7 +205,7 @@ function buildSdkContract() {
 
   return {
     contractVersion: docApiContract.contractVersion,
-    sourceHash,
+    sourceHash: docApiContract.sourceHash,
     ...(docApiContract.$defs ? { $defs: docApiContract.$defs } : {}),
     cli: {
       package: cliPkg.name,

apps/cli/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,20 +34,59 @@ 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
 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)