docspack 1.1.0 → 1.3.0

package/src/cli-spec.ts

@@ -0,0 +1,688 @@
+import type { CmdspecDocument, Option } from "@docspack/cmdspec";
+import { DEFAULT_LIMIT, DEFAULT_MAX_TOKENS } from "./search.js";
+
+/**
+ * The docspack CLI, described in cmdspec (`packages/cmdspec/SPEC.md`).
+ *
+ * This is the CLI's definition, not documentation of it. `cli.ts` builds each command's parser
+ * from it, so a flag one command reads is an error on another; `help.ts` renders `--help` from it;
+ * `docspack --cmdspec` prints it, and the build writes it to `dist/cmdspec.json`, which
+ * `package.json`'s `"cmdspec"` field names and the site imports. Before this there were three
+ * lists — the parser's, the help's and the site's — and they had drifted: `build` accepted
+ * `--from-json` and `--local`, and its help mentioned neither.
+ *
+ * A TypeScript constant rather than a YAML file, because the CLI reads it on every invocation and
+ * `docspack ask` pays for nothing it does not use; the compiler checks it against cmdspec's types,
+ * and `tests/cli-spec.test.ts` validates it against the schema and its rules.
+ *
+ * `info.version` is a placeholder: the CLI reports `package.json`'s, which is the one a release
+ * bumps.
+ */
+
+const option = (definition: Option): Option => definition;
+
+const components = {
+  package: option({
+    name: "--package",
+    aliases: ["-p"],
+    summary: "only packages whose name contains this text",
+    value: { name: "s" },
+  }),
+  limit: option({
+    name: "--limit",
+    summary: "maximum chunks to return",
+    value: { name: "n", type: "integer", minimum: 1, default: DEFAULT_LIMIT },
+  }),
+  "max-tokens": option({
+    name: "--max-tokens",
+    summary: "token ceiling for the result set",
+    value: { name: "n", type: "integer", minimum: 1, default: DEFAULT_MAX_TOKENS },
+  }),
+  all: option({ name: "--all", summary: "search the whole store, not just this project" }),
+  "package-dir": option({
+    name: "--package-dir",
+    summary: "the package to read",
+    value: { name: "d", format: "directory", default: "." },
+  }),
+  from: option({
+    name: "--from",
+    summary: "directory of Markdown to package",
+    value: { name: "dir", format: "directory" },
+  }),
+  openapi: option({
+    name: "--openapi",
+    summary: "OpenAPI 3 document (JSON or YAML), one chunk per operation",
+    value: { name: "file", format: "file" },
+  }),
+  name: option({
+    name: "--name",
+    summary: "package name, e.g. @acme/docspack",
+    value: { name: "name" },
+  }),
+  "pkg-version": option({
+    name: "--pkg-version",
+    summary: "package version",
+    value: { name: "v" },
+  }),
+};
+
+const ref = (key: keyof typeof components) => ({ $ref: `#/components/options/${key}` });
+
+export const CLI: CmdspecDocument = {
+  $schema: "https://docspack.dev/cmdspec/schema/v0.1.json",
+  cmdspec: "0.1",
+  info: {
+    name: "docspack",
+    version: "0.0.0",
+    summary: "Local, version-locked documentation for AI agents",
+    description:
+      "Documentation ships as npm packages named @vendor/docspack, @vendor/<name>-docspack or @docspack-community/<name>. Add them to package.json, run `docspack sync`, and every chunk is indexed into a shared SQLite database with FTS5. Agents query that index locally: no network, no scraping, always the installed version.",
+    homepage: "https://docspack.dev",
+    license: { identifier: "MIT" },
+  },
+  subcommandRequired: true,
+  options: [
+    {
+      name: "--store",
+      summary: "Use a different index",
+      value: { name: "path", format: "file", defaultDescription: "~/.docspack/store.db" },
+      env: ["DOCSPACK_STORE"],
+      inherited: true,
+    },
+    {
+      name: "--cwd",
+      summary: "Run in a different directory",
+      value: { name: "dir", format: "directory", defaultDescription: "the current directory" },
+      inherited: true,
+    },
+    { name: "--json", summary: "Machine-readable output", inherited: true },
+    { name: "--quiet", aliases: ["-q"], summary: "Only print errors", inherited: true },
+    {
+      name: "--help",
+      aliases: ["-h"],
+      summary: "Show this help, or a command's help",
+      inherited: true,
+    },
+    { name: "--version", aliases: ["-v"], summary: "Show the version" },
+    { name: "--cmdspec", summary: "Print this program's own cmdspec document, as JSON" },
+  ],
+  environment: [{ name: "NO_COLOR", summary: "Print without colour when set to anything" }],
+  files: [
+    {
+      path: "~/.docspack/store.db",
+      role: "data",
+      format: "sqlite",
+      summary: "The global index, shared by every project on this machine",
+    },
+    {
+      path: ".docspack/local.db",
+      role: "data",
+      format: "sqlite",
+      summary: "This project's own corpus, written by `index`",
+    },
+    {
+      path: ".docspack/feedback.jsonl",
+      role: "state",
+      format: "jsonl",
+      summary: "Documentation problems recorded by `feedback add`",
+    },
+  ],
+  exits: {
+    "0": { meaning: "success" },
+    "1": { meaning: "the command failed" },
+    "2": { meaning: "the command was used wrongly" },
+  },
+  components: { options: components },
+  commands: [
+    {
+      name: "sync",
+      group: "core",
+      summary: "Index the docs packages this project depends on",
+      description:
+        "Reads node_modules and indexes every @vendor/docspack and @docspack-community/<name> package this project declares. Makes no network requests.\n\nIt also reads each installed library's own type declarations and indexes one entry per exported name. Half of a well-documented library's exports are mentioned in no documentation anyone published, and those declarations are the only local answer for them. They are looked up by name, never ranked against prose, so they cannot crowd out the documentation that does exist.\n\nA library that describes its own command line, with `\"cmdspec\"` in its package.json, has that description indexed as well, for the version installed.",
+      effects: ["read", "write"],
+      idempotent: true,
+      options: [
+        { name: "--force", summary: "re-index packages already in the store" },
+        {
+          name: "--no-artifacts",
+          summary: "skip the declarations derived from installed libraries",
+        },
+      ],
+      examples: [
+        { run: "docspack sync" },
+        { run: "docspack sync --force" },
+        { run: "docspack sync --no-artifacts" },
+      ],
+    },
+    {
+      name: "ask",
+      group: "core",
+      summary: "Answer from the local index — the command to give an agent",
+      description:
+        "Answers from the installed versions, in the Markdown an agent should read.\n\nWhen the question names something an installed library exports and no documentation mentions, the answer leads with that name's declaration from the installed build and says the documentation does not cover it. Ranking alone cannot tell that apart from a match. A question that names an endpoint (`POST /v1/charges`) or a command (`git remote add`) gets that operation or command first.",
+      effects: ["read"],
+      idempotent: true,
+      arguments: [
+        {
+          name: "question",
+          required: true,
+          variadic: true,
+          summary: "words are joined with spaces",
+        },
+      ],
+      options: [ref("package"), ref("limit"), ref("max-tokens"), ref("all")],
+      io: {
+        stdout: [
+          { mediaType: "text/markdown", summary: "the answer" },
+          {
+            mediaType: "application/json",
+            selectedBy: "--json",
+            summary: "the chunks and their scores",
+          },
+        ],
+      },
+      exits: {
+        "3": {
+          meaning: "nothing matched, and a docs package is installed but not indexed",
+          description: "Run `docspack sync`, then ask again.",
+        },
+        "4": { meaning: "nothing matched, and everything installed is already indexed" },
+      },
+      examples: [
+        { run: 'docspack ask "how do I verify a webhook signature"' },
+        {
+          run: 'docspack ask "webhook signature" --package stripe --limit 5',
+          summary: "Look in one package only, and return more",
+        },
+      ],
+    },
+    {
+      name: "index",
+      group: "core",
+      summary: "Index this project's own sources, so an agent can ask them instead of reading them",
+      description:
+        "For a corpus this project already has rather than one somebody published: notes, an export, rows out of a query. The payload is built in a temporary directory and thrown away; what is kept is the index, in `.docspack/local.db`, which is a plaintext copy of whatever was indexed and is gitignored on the tool's behalf.\n\nRecords arrive as JSON so no database driver is needed: `sqlite3 -json … | docspack index --from-json -`. A record with an `id` becomes one chunk under that id, because a row's identity is its key.\n\nWhat was indexed is recorded with each source's size, mtime and hash, so a re-run does nothing when nothing has changed and `recall` can say when an answer may be superseded.",
+      effects: ["read", "write"],
+      idempotent: true,
+      options: [
+        ref("from"),
+        {
+          name: "--from-json",
+          summary: "JSON records to index, or `-` for standard input",
+          value: { name: "file", format: "file", stdio: true },
+        },
+        {
+          name: "--name",
+          summary: "name for the corpus",
+          value: { name: "s", defaultDescription: "derived from the source" },
+        },
+        { name: "--force", summary: "re-index even when no source has changed" },
+      ],
+      io: {
+        stdin: [
+          {
+            mediaType: "application/json",
+            selectedBy: "--from-json=-",
+            summary: "an array of records, each with text and optionally an id and a title",
+          },
+        ],
+      },
+      examples: [
+        { run: "docspack index --from ./notes" },
+        {
+          run: "sqlite3 -json shop.db 'select id, title, body as text from posts' | docspack index --from-json -",
+          summary: "Index rows straight out of a database",
+        },
+      ],
+    },
+    {
+      name: "recall",
+      group: "core",
+      summary: "Answer from this project's indexed corpus, not from its dependencies",
+      description:
+        "Separate from `ask` on purpose. `ask` answers from the versions this project installed, and a working corpus is never one of them — so a corpus cannot reach an answer about a dependency, and a dependency cannot reach an answer about your notes.\n\nAn answer leads with a warning when a source has changed since it was indexed.",
+      effects: ["read"],
+      idempotent: true,
+      arguments: [{ name: "question", required: true, variadic: true }],
+      options: [ref("limit"), ref("max-tokens")],
+      exits: { "1": { meaning: "nothing matched" } },
+      examples: [{ run: 'docspack recall "what did we decide about retries"' }],
+    },
+    {
+      name: "search",
+      group: "core",
+      summary: "Same index, formatted for a human reading the terminal",
+      description: "The same index and ranking as `ask`, printed as a list of hits with a preview.",
+      effects: ["read"],
+      idempotent: true,
+      arguments: [{ name: "query", required: true, variadic: true }],
+      options: [ref("package"), ref("limit"), ref("max-tokens"), ref("all")],
+      exits: {
+        "3": { meaning: "nothing matched, and a docs package is installed but not indexed" },
+        "4": { meaning: "nothing matched, and everything installed is already indexed" },
+      },
+      examples: [{ run: "docspack search webhook signature" }],
+    },
+    {
+      name: "list",
+      group: "core",
+      summary: "Show this project's docs packages and their index state",
+      description:
+        "Coverage is mechanical: the exported names a library declares, against the names its documentation mentions anywhere. It is reported, never gated on — a page listing every export and explaining none would score full marks.",
+      effects: ["read"],
+      idempotent: true,
+      options: [
+        {
+          name: "--coverage",
+          summary: "how much of each documented library's exports the prose mentions",
+        },
+      ],
+      examples: [
+        { run: "docspack list" },
+        { run: "docspack list --coverage" },
+        { run: "docspack list --json" },
+      ],
+    },
+    {
+      name: "agent",
+      group: "core",
+      summary: "Wire docspack into the agent tooling this project already uses",
+      description:
+        "`install` writes a marked block into AGENTS.md or CLAUDE.md — whichever the project already has — and a skill into .claude/skills/docspack/ when the project uses Claude Code. Everything outside the markers is left alone, and re-running rewrites the block rather than appending a second copy. With no subcommand, `agent` installs.\n\n`check` writes nothing and exits non-zero when the wiring is missing or out of date, so CI notices a pasted instruction that has drifted from what the tool now does.",
+      effects: ["read", "write"],
+      idempotent: true,
+      options: [
+        {
+          name: "--feedback",
+          summary: "also include recording documentation problems",
+          inherited: true,
+        },
+        {
+          name: "--hooks",
+          summary: "add a SessionStart hook that keeps the index in step",
+          inherited: true,
+        },
+        { name: "--mcp", summary: "add the MCP server to .mcp.json", inherited: true },
+        {
+          name: "--dry-run",
+          summary: "print what would be written and write nothing",
+          effects: ["read"],
+        },
+      ],
+      commands: [
+        {
+          name: "install",
+          summary: "Write the docspack block into AGENTS.md or CLAUDE.md",
+          effects: ["read", "write"],
+          idempotent: true,
+          options: [
+            {
+              name: "--dry-run",
+              summary: "print what would be written and write nothing",
+              effects: ["read"],
+            },
+          ],
+          examples: [
+            { run: "docspack agent install" },
+            { run: "docspack agent install --feedback --hooks" },
+          ],
+        },
+        {
+          name: "check",
+          summary: "Fail when the wiring is missing or out of date",
+          effects: ["read"],
+          idempotent: true,
+          exits: { "1": { meaning: "the wiring is missing or out of date" } },
+          examples: [{ run: "docspack agent check" }],
+        },
+      ],
+      examples: [{ run: "docspack agent install --feedback --hooks" }],
+    },
+    {
+      name: "changed",
+      group: "core",
+      summary: "What a library's exports gained and lost between two versions",
+      description:
+        "Compares two versions already in the global store, which is shared by every project on this machine, so nothing is fetched. Without a version it compares what is installed here against the most recently indexed other version.\n\nUpgrades are overwhelmingly additive: the useful answer is what exists now that an older release did not have, and which of those names no documentation here mentions — the ones a model can know from neither its training data nor the vendor's pages.",
+      effects: ["read"],
+      idempotent: true,
+      arguments: [{ name: "library", required: true, value: { name: "library[@version]" } }],
+      examples: [{ run: "docspack changed hono" }, { run: "docspack changed hono@4.0.0" }],
+    },
+    {
+      name: "verify",
+      group: "core",
+      summary: "Check the docs still describe the code you installed",
+      description:
+        'Compares the identifiers the chunks name against what the documented libraries declare, read from their .d.ts files. Nothing you depend on is imported or executed. The libraries come from the manifest\'s "documents", or from the docspack key when the manifest has none.',
+      effects: ["read"],
+      idempotent: true,
+      options: [
+        {
+          name: "--package-dir",
+          summary: "verify one package directory instead of what is installed",
+          value: { name: "d", format: "directory" },
+        },
+      ],
+      exits: { "1": { meaning: "anything was reported" } },
+      examples: [{ run: "docspack verify" }, { run: "docspack verify --json" }],
+    },
+    {
+      name: "feedback",
+      group: "core",
+      summary: "Record documentation problems: add, list, submit, remove",
+      description:
+        "Writes to .docspack/feedback.jsonl in this project. Nothing is transmitted: docspack contains no code that can send a report anywhere.\n\n`drift` must name the identifier that drifted. `incorrect` and `missing` must carry --expected, --actual and --repro, so a claim that cannot show its work cannot be recorded. `submit` prints a prefilled GitHub issue URL for a human to open and file.",
+      subcommandRequired: true,
+      commands: [
+        {
+          name: "add",
+          summary: "Record one problem",
+          effects: ["write"],
+          options: [
+            {
+              name: "--chunk",
+              required: true,
+              summary: "the chunk the problem is in",
+              value: { name: "id" },
+            },
+            {
+              name: "--kind",
+              value: { name: "k", enum: ["drift", "incorrect", "missing"], default: "drift" },
+            },
+            {
+              name: "--evidence",
+              required: true,
+              summary: "the claim, in one line",
+              value: { name: "text" },
+            },
+            {
+              name: "--expected",
+              summary: "what the documentation led you to expect",
+              value: { name: "text" },
+            },
+            { name: "--actual", summary: "what happened instead", value: { name: "text" } },
+            { name: "--repro", summary: "code that demonstrates it", value: { name: "code" } },
+          ],
+          constraints: [
+            { when: "--kind=incorrect", requires: ["--expected", "--actual", "--repro"] },
+            { when: "--kind=missing", requires: ["--expected", "--actual", "--repro"] },
+          ],
+          examples: [
+            {
+              run: 'docspack feedback add --chunk @acme/docspack@1.4.0/api-auth --kind drift --evidence "client.setKey is not exported; setApiKey is"',
+            },
+          ],
+        },
+        {
+          name: "list",
+          summary: "Show recorded problems",
+          effects: ["read"],
+          idempotent: true,
+          examples: [{ run: "docspack feedback list" }],
+        },
+        {
+          name: "submit",
+          summary: "Print a prefilled GitHub issue URL for a human to open",
+          effects: ["read"],
+          idempotent: true,
+          options: [
+            {
+              name: "--package",
+              aliases: ["-p"],
+              summary: "only findings from packages matching this text",
+              value: { name: "s" },
+            },
+          ],
+          examples: [{ run: "docspack feedback submit" }],
+        },
+        {
+          name: "remove",
+          summary: "Delete recorded problems",
+          effects: ["destructive"],
+          idempotent: true,
+          arguments: [{ name: "fingerprint", variadic: true }],
+          options: [{ name: "--all", summary: "every recorded finding" }],
+          constraints: [{ oneOf: ["fingerprint", "--all"] }],
+          examples: [{ run: "docspack feedback remove <fingerprint>" }],
+        },
+      ],
+    },
+    {
+      name: "mcp",
+      group: "core",
+      summary: "Serve the index over MCP instead, as a long-lived process",
+      description:
+        "Serves the same index over the Model Context Protocol, for clients that prefer a tool definition to a shell command. `query_local_docs` returns exactly what `ask` prints. stdout is the protocol channel, so nothing else is written to it.",
+      effects: ["read"],
+      longRunning: true,
+      io: {
+        stdin: [{ mediaType: "application/jsonl", summary: "MCP requests" }],
+        stdout: [{ mediaType: "application/jsonl", summary: "MCP responses" }],
+      },
+      examples: [{ run: "docspack mcp" }],
+    },
+    {
+      name: "sources",
+      group: "core",
+      summary: "List curated sources that `docspack build` can fetch",
+      effects: [],
+      idempotent: true,
+      examples: [
+        { run: "docspack sources" },
+        { run: "docspack build hono --name @docspack-community/hono" },
+      ],
+    },
+    {
+      name: "init",
+      group: "authoring",
+      summary: "Scaffold a documentation package, then build and check it",
+      description:
+        "Reads the surrounding project first — name, version, a docs directory, an OpenAPI document, the git remote, the license — and proposes a package built from what it found.",
+      effects: ["read", "write", "network"],
+      interactive: { when: "tty", disable: "--yes" },
+      arguments: [{ name: "name", summary: "package name" }],
+      options: [
+        {
+          name: "--yes",
+          aliases: ["-y"],
+          summary: "skip the prompts and use flags plus detected defaults",
+        },
+        {
+          name: "--dry-run",
+          summary: "print the file tree and write nothing",
+          effects: ["read"],
+        },
+        {
+          name: "--mirror",
+          summary: "bootstrap from a published llms.txt",
+          value: { name: "id|url" },
+        },
+        { name: "--community", summary: "scaffold under @docspack-community" },
+        { name: "--template", value: { name: "t", enum: ["full", "minimal"], default: "full" } },
+        { name: "--mode", value: { name: "m", enum: ["standalone", "in-repo"] } },
+        {
+          name: "--workflow",
+          negation: ["--no-workflow"],
+          summary: "write the release workflow (the default)",
+        },
+        {
+          name: "--build",
+          negation: ["--no-build"],
+          summary: "build and check after scaffolding (the default)",
+        },
+        ref("name"),
+        ref("pkg-version"),
+        ref("from"),
+        {
+          name: "--openapi",
+          summary: "OpenAPI JSON to package",
+          value: { name: "file", format: "file" },
+        },
+        {
+          name: "--out",
+          summary: "where to scaffold",
+          value: { name: "dir", format: "directory", default: "./docspack" },
+        },
+        { name: "--force", summary: "overwrite files that already exist" },
+      ],
+      examples: [
+        { run: "docspack init" },
+        { run: "docspack init --name @acme/docspack --from ./docs --yes" },
+        { run: "docspack init --mirror hono --community --yes" },
+      ],
+    },
+    {
+      name: "build",
+      group: "authoring",
+      summary: "Generate the .llms/ payload for publishing",
+      description:
+        'Splits each document at ## headings, then ###, then paragraphs, until every chunk fits the budget. --min-chunk-tokens packs the other way first, merging adjacent sections up to the budget: use it for generated reference, where a heading is a field name and one chunk per heading is hundreds of chunks too small to answer anything.\n\n--openapi writes one chunk per operation: the base URL, the credential, the inputs with their types, the response, the failures and a runnable curl call, in LAPIS notation. Each chunk answers to both `POST /v1/charges` and the operationId, so `docspack ask` can be given either. Combine it with --from to publish prose and an API in one package.\n\n--cmdspec writes one chunk per command of a command-line interface described in cmdspec, or in OpenCLI or Usage, converted: the synopsis, the inputs with their types and defaults, what the command changes, what it prints and what its exit status means. Each chunk answers to its command path, so `docspack ask "git remote add"` pins it.\n\nWith no flags, settings are read from the docspack key of the package.json in --out.',
+      effects: ["read", "write", "network"],
+      idempotent: true,
+      arguments: [
+        { name: "source", summary: "a curated source to fetch, from `docspack sources`" },
+      ],
+      options: [
+        ref("from"),
+        ref("openapi"),
+        {
+          name: "--cmdspec",
+          summary: "CLI description (cmdspec, OpenCLI or Usage), one chunk per command",
+          value: { name: "file", format: "file" },
+        },
+        {
+          name: "--from-json",
+          summary: "JSON records to package, or `-` for standard input",
+          value: { name: "file", format: "file", stdio: true },
+        },
+        ref("name"),
+        ref("pkg-version"),
+        {
+          name: "--out",
+          summary: "output directory",
+          value: { name: "dir", format: "directory", defaultDescription: "the current directory" },
+        },
+        {
+          name: "--pages",
+          summary: "maximum documents to fetch from a remote source",
+          value: { name: "n", type: "integer", minimum: 1 },
+        },
+        {
+          name: "--max-chunk-tokens",
+          summary: "split a section above this size",
+          value: { name: "n", type: "integer", minimum: 1, default: 800 },
+        },
+        {
+          name: "--min-chunk-tokens",
+          summary: "pack adjacent sections up to this size before splitting",
+          value: { name: "n", type: "integer", minimum: 1 },
+        },
+        {
+          name: "--documents",
+          summary: "library this package documents, such as acme@1.4.0",
+          repeat: "list",
+          value: { name: "p" },
+        },
+        {
+          name: "--local",
+          hidden: true,
+          summary: "build a working corpus rather than a publishable package, as `index` does",
+        },
+      ],
+      constraints: [
+        { exclusive: ["source", "--from"] },
+        { exclusive: ["source", "--openapi"] },
+        { exclusive: ["source", "--cmdspec"] },
+        { exclusive: ["source", "--from-json"] },
+      ],
+      examples: [
+        { run: "docspack build" },
+        { run: "docspack build --from ./docs --name @acme/docspack --pkg-version 1.4.0" },
+        { run: "docspack build --from ./reference --min-chunk-tokens 400 --max-chunk-tokens 900" },
+        { run: "docspack build --openapi ./openapi.json" },
+        {
+          run: "docspack build --from ./docs --openapi ./openapi.json",
+          summary: "Prose and an HTTP API in one package",
+        },
+        { run: "docspack build --from ./docs --cmdspec ./cmdspec.yaml" },
+      ],
+    },
+    {
+      name: "doctor",
+      group: "authoring",
+      summary: "Check a package the way the indexer and a reviewer would",
+      description:
+        "Errors are packages that will not index. Warnings are packages that will index and retrieve badly. Prose style is a note unless --pedantic, because writing by hand is not a reason to block a first publish.",
+      effects: ["read"],
+      idempotent: true,
+      options: [
+        { name: "--strict", summary: "treat structural warnings as failures" },
+        { name: "--pedantic", summary: "--strict, and fail on prose style as well" },
+        ref("package-dir"),
+      ],
+      exits: { "1": { meaning: "the package is not ready to publish" } },
+      examples: [
+        { run: "docspack doctor" },
+        { run: "docspack doctor --strict" },
+        { run: "docspack doctor --json" },
+      ],
+    },
+    {
+      name: "preview",
+      group: "authoring",
+      summary: "Answer a query from the local package, as an agent would",
+      description:
+        "Indexes the package in memory and answers through the same ranking and token budget an agent gets. Nothing is published, installed, or written to the global store.",
+      effects: ["read"],
+      idempotent: true,
+      arguments: [{ name: "query", required: true, variadic: true }],
+      options: [ref("package-dir"), ref("limit"), ref("max-tokens")],
+      examples: [{ run: 'docspack preview "how do I authenticate"' }],
+    },
+    {
+      name: "eval",
+      group: "authoring",
+      summary: "Measure retrieval against a set of questions",
+      description:
+        'The evaluation set is a JSON array of questions and the chunk ids that would answer them:\n\n    [{ "query": "how do I verify a webhook signature", "expect": "webhooks-signing" },\n     { "query": "rate limits", "expect": ["rate-limits", "errors"] }]\n\nReports hit rate, top-1 rate and mean answer size — the numbers that settle the chunk budget, which no structural check can see. With --min-hit-rate it gates a publish on retrieval quality the way `doctor --strict` gates it on structure.',
+      effects: ["read"],
+      idempotent: true,
+      arguments: [
+        { name: "queries", required: true, value: { name: "queries.json", format: "file" } },
+      ],
+      options: [
+        ref("package-dir"),
+        {
+          name: "--limit",
+          summary: "chunks per answer, the window a hit must fall in",
+          value: { name: "n", type: "integer", minimum: 1, default: DEFAULT_LIMIT },
+        },
+        {
+          name: "--max-tokens",
+          summary: "token ceiling for each answer",
+          value: { name: "n", type: "integer", minimum: 1, default: DEFAULT_MAX_TOKENS },
+        },
+        {
+          name: "--min-hit-rate",
+          summary: "exit 1 below this percentage of questions answered",
+          value: { name: "n", type: "number", minimum: 0, maximum: 100 },
+        },
+      ],
+      exits: { "1": { meaning: "the hit rate is below --min-hit-rate" } },
+      examples: [
+        { run: "docspack eval ./eval/queries.json" },
+        { run: "docspack eval ./eval/queries.json --min-hit-rate 90" },
+        { run: "docspack eval ./eval/queries.json --limit 1 --json" },
+      ],
+    },
+    {
+      name: "help",
+      hidden: true,
+      summary: "Show the help, or a command's help",
+      effects: [],
+      arguments: [{ name: "command" }],
+    },
+  ],
+};