@superdoc/cli 0.36.0-next.5 → 0.36.0-next.6

package/README.md

@@ -64,6 +64,16 @@ If the password is missing or incorrect, the CLI returns a structured error with
 
 ## Choosing the Right Command
 
+Search the CLI contract when you know the intent but not the operation name:
+
+```bash
+superdoc discover "create a footnote"
+superdoc discover "add an sdt"
+superdoc discover "change table cell padding"
+```
+
+`discover` uses the generated Document API contract plus CLI vocabulary and operation relationships. It returns an adaptive relevant set with at most ten results. The leading result includes a compact input shape, CLI parameters, a command template, and the exact `describe command` follow-up. Use `--limit <1-10>` to request a smaller ceiling.
+
 ### Which command should I use?
 
 | I want to... | Use this command |
@@ -159,7 +169,7 @@ superdoc save --in-place
 | history | `history get`, `history undo`, `history redo` |
 | lifecycle | `open`, `save`, `close` |
 | session | `session list`, `session save`, `session close`, `session set-default`, `session use` |
-| introspection | `status`, `describe`, `describe command` |
+| introspection | `status`, `discover`, `describe`, `describe command` |
 | low-level | `call <operationId>` |
 | legacy compat | `search`, `replace-legacy <find> <to> <files...>`, `read` |
 
@@ -167,6 +177,7 @@ For full command help and examples, run:
 
 ```bash
 superdoc --help
+superdoc discover "<natural-language intent>"
 superdoc save --help
 superdoc create paragraph --help
 superdoc describe command <command-name>
@@ -210,15 +221,30 @@ superdoc host --stdio
 ## API introspection commands
 
 ```bash
+superdoc discover "set padding on one table cell"
 superdoc describe
 superdoc describe command doc.find
 superdoc status
 ```
 
-- `describe` returns contract + protocol metadata and the operation catalog.
+- `discover <intent>` ranks relevant operations and expands the leading input shape without opening a document.
+- `describe` returns contract + protocol metadata and the exhaustive operation catalog.
 - `describe command <operationId>` returns one operation definition (inputs, response schema, errors, examples).
 - `status` shows current session status and document metadata.
 
+## Discovery evaluation
+
+The repository includes a canonical intent corpus with expected operations in `eval/discovery-cases.json`.
+
+```bash
+pnpm eval:discovery
+pnpm eval:discovery -- --case sdt-ambiguous-add
+pnpm eval:discovery -- --query "add a repeating section control"
+pnpm eval:discovery -- --json
+```
+
+The suite reports Top-1 accuracy, MRR, Recall@3, Recall@10, mean result count, payload size, and p95 search latency. It exits nonzero when an expected ranking, result-set bound, command helper, or ambiguity classification fails.
+
 ## Stateful session commands
 
 ```bash

package/dist/index.js

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/index.js
-size: 36505031 bytes
-sha256: 44fc3ee227526847c4e93f7860966c6680e08893fc5a589ec168ef357776a735
+size: 36550942 bytes
+sha256: 25d1070b3376607e2e2f4f78c78be877843f1eca8dee81f6d1bd9361778b27fa

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/cli",
-  "version": "0.36.0-next.5",
+  "version": "0.36.0-next.6",
   "description": "Command-line interface for SuperDoc: inspect, convert, and edit .docx files from a terminal or a script.",
   "type": "module",
   "license": "AGPL-3.0",
@@ -35,7 +35,7 @@
   },
   "devDependencies": {
     "@hocuspocus/server": "^2.13.6",
-    "@superdoc/sdk": "2.13.0-next.5",
+    "@superdoc/sdk": "2.13.0-next.6",
     "@superdoc/document-api": "0.1.0-alpha.0",
     "@superdoc/docx-engine": "0.15.0-next.5",
     "@types/bun": "^1.3.8",
@@ -51,11 +51,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc/cli-darwin-arm64": "0.36.0-next.5",
-    "@superdoc/cli-darwin-x64": "0.36.0-next.5",
-    "@superdoc/cli-linux-x64": "0.36.0-next.5",
-    "@superdoc/cli-linux-arm64": "0.36.0-next.5",
-    "@superdoc/cli-windows-x64": "0.36.0-next.5"
+    "@superdoc/cli-darwin-arm64": "0.36.0-next.6",
+    "@superdoc/cli-darwin-x64": "0.36.0-next.6",
+    "@superdoc/cli-linux-x64": "0.36.0-next.6",
+    "@superdoc/cli-linux-arm64": "0.36.0-next.6",
+    "@superdoc/cli-windows-x64": "0.36.0-next.6"
   },
   "scripts": {
     "predev": "node scripts/ensure-superdoc-build.js",
@@ -78,6 +78,7 @@
     "test:docx-reference-integrity": "node --test scripts/docx-reference-integrity.mjs",
     "test:sdk-collaborative-close": "NODE_ENV=test bun test src/__tests__/sdk-collaborative-close.e2e.test.ts",
     "test:sdk-replace-file": "NODE_ENV=test bun test src/__tests__/sdk-replace-file.e2e.test.ts",
+    "eval:discovery": "bun run scripts/evaluate-discovery.ts",
     "lint": "pnpm -w exec vp lint apps/cli",
     "lint:fix": "pnpm -w exec vp lint --fix apps/cli",
     "format": "pnpm -w exec vp fmt apps/cli",

package/skill/SKILL.md

@@ -10,17 +10,25 @@ Do not default to legacy commands unless explicitly needed for v0-style bulk wor
 
 Use `superdoc` if installed, or `npx @superdoc/cli@latest` as a fallback.
 
-## First Step: Discover Exact Params
+## First Step: Discover the Operation
 
-For unknown commands or flags, inspect runtime metadata first:
+When the operation is not already known, search by the user's exact intent:
 
 ```bash
-superdoc describe
-superdoc describe command find
-superdoc describe command "comments add"
+superdoc discover "create a footnote"
+superdoc discover "add an sdt"
+superdoc discover "change table cell padding"
 ```
 
-Use `describe command` for per-command args and constraints.
+Discovery returns an adaptive set of relevant operations, capped at ten. A clear intent may return one result. An ambiguous or broad intent may return more. The leading result includes its compact input shape and a command template.
+
+Use the returned `schemaCommand` when the compact shape is not enough:
+
+```bash
+superdoc describe command doc.footnotes.insert
+```
+
+Do not run the full `superdoc describe` catalogue to discover an operation. Use it only when an exhaustive inventory is explicitly needed.
 
 ## Preferred Workflows