docspack 1.1.0 → 1.3.0

package/src/help.ts

@@ -1,13 +1,23 @@
+import {
+  type CmdspecDocument,
+  commandPath,
+  commandSummary,
+  type ResolvedCommand,
+  type ResolvedOption,
+  resolveDocument,
+  synopsis,
+} from "@docspack/cmdspec";
+import { CLI } from "./cli-spec.js";
 import { AGENTS_SNIPPET, FEEDBACK_SNIPPET } from "./snippet.js";
 
 /**
- * The help text, per command.
+ * The help text, rendered from the CLI's cmdspec document (`cli-spec.ts`).
  *
- * `docspack <command> --help` printed the global help, so no flag was discoverable from the CLI
- * at all — `doctor --pedantic`, `ask --max-tokens` and `init --mirror` were findable only by
- * reading the source. That matters more than usual for a tool whose main user is an agent that
- * will not open a browser, and it is why the global page now points at these rather than trying
- * to list every flag of every command in one block.
+ * `docspack <command> --help` used to print the global help, so no flag was discoverable from the
+ * CLI at all; then it printed a hand-kept list that drifted from the parser — `build` accepted
+ * `--from-json` and `--local` and listed neither. Now the parser, this help and `docspack
+ * --cmdspec` read the same document, so a flag cannot be accepted without being listed, or listed
+ * without being accepted. The global page's prose is still written here; its lists are not.
  */
 export interface CommandHelp {
   readonly name: string;
@@ -21,393 +31,47 @@ export interface CommandHelp {
   readonly examples: readonly string[];
 }
 
-const LIMIT = 3;
-const MAX_TOKENS = 3000;
-
-const QUERY_OPTIONS: readonly (readonly [string, string])[] = [
-  ["-p, --package <s>", "only packages whose name contains this text"],
-  ["--limit <n>", `maximum chunks to return (default ${LIMIT})`],
-  ["--max-tokens <n>", `token ceiling for the result set (default ${MAX_TOKENS})`],
-  ["--all", "search the whole store, not just this project"],
-];
-
-export const COMMANDS: readonly CommandHelp[] = [
-  {
-    name: "sync",
-    summary: "Index the docs packages this project depends on",
-    group: "core",
-    usage: "docspack sync [options]",
-    options: [
-      ["--force", "re-index packages already in the store"],
-      ["--no-artifacts", "skip the declarations derived from installed libraries"],
-    ],
-    detail: [
-      "Reads node_modules and indexes every @vendor/docspack and @docspack-community/<name>",
-      "package this project declares. Makes no network requests.",
-      "",
-      "It 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.",
-    ],
-    examples: ["docspack sync", "docspack sync --force", "docspack sync --no-artifacts"],
-  },
-  {
-    name: "ask",
-    summary: "Answer from the local index — the command to give an agent",
-    group: "core",
-    usage: 'docspack ask "<question>"',
-    options: QUERY_OPTIONS,
-    detail: [
-      "Answers from the installed versions, in the Markdown an agent should read. Exits 0 when",
-      "chunks were returned, 3 when a docs package is installed but not indexed, and 4 when",
-      "everything installed is indexed and nothing matched.",
-      "",
-      "When 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.",
-    ],
-    examples: [
-      'docspack ask "how do I verify a webhook signature"',
-      'docspack ask "webhook signature" --package stripe --limit 5',
-    ],
-  },
-  {
-    name: "index",
-    summary: "Index this project's own sources, so an agent can ask them instead of reading them",
-    group: "core",
-    usage: "docspack index [--from <dir>] [--from-json <file|->]",
-    options: [
-      ["--from <dir>", "directory of Markdown to index"],
-      ["--from-json <f>", "JSON records to index, or `-` for standard input"],
-      ["--name <s>", "name for the corpus (default: derived from the source)"],
-      ["--force", "re-index even when no source has changed"],
-    ],
-    detail: [
-      "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.",
-      "",
-      "Records 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.",
-      "",
-      "What 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.",
-    ],
-    examples: [
-      "docspack index --from ./notes",
-      "sqlite3 -json shop.db 'select id, title, body as text from posts' | docspack index --from-json -",
-    ],
-  },
-  {
-    name: "recall",
-    summary: "Answer from this project's indexed corpus, not from its dependencies",
-    group: "core",
-    usage: 'docspack recall "<question>"',
-    options: [
-      ["--limit <n>", `maximum chunks to return (default ${LIMIT})`],
-      ["--max-tokens <n>", `token ceiling for the result set (default ${MAX_TOKENS})`],
-    ],
-    detail: [
-      "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.",
-      "",
-      "An answer leads with a warning when a source has changed since it was indexed. Exits 1",
-      "when nothing matched.",
-    ],
-    examples: ['docspack recall "what did we decide about retries"'],
-  },
-  {
-    name: "search",
-    summary: "Same index, formatted for a human reading the terminal",
-    group: "core",
-    usage: "docspack search <query>",
-    options: QUERY_OPTIONS,
-    detail: ["The same index and ranking as `ask`, printed as a list of hits with a preview."],
-    examples: ["docspack search webhook signature"],
-  },
-  {
-    name: "list",
-    summary: "Show this project's docs packages and their index state",
-    group: "core",
-    usage: "docspack list [options]",
-    options: [["--coverage", "how much of each documented library's exports the prose mentions"]],
-    detail: [
-      "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.",
-    ],
-    examples: ["docspack list", "docspack list --coverage", "docspack list --json"],
-  },
-  {
-    name: "agent",
-    summary: "Wire docspack into the agent tooling this project already uses",
-    group: "core",
-    usage: "docspack agent <install|check> [options]",
-    options: [
-      ["--feedback", "also include recording documentation problems"],
-      ["--hooks", "add a SessionStart hook that keeps the index in step"],
-      ["--mcp", "add the MCP server to .mcp.json"],
-      ["--dry-run", "print what would be written and write nothing"],
-    ],
-    detail: [
-      "`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.",
-      "",
-      "`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.",
-    ],
-    examples: [
-      "docspack agent install",
-      "docspack agent install --feedback --hooks",
-      "docspack agent check",
-    ],
-  },
-  {
-    name: "changed",
-    summary: "What a library's exports gained and lost between two versions",
-    group: "core",
-    usage: "docspack changed <library>[@version]",
-    options: [],
-    detail: [
-      "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.",
-      "",
-      "Upgrades 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.",
-    ],
-    examples: ["docspack changed hono", "docspack changed hono@4.0.0"],
-  },
-  {
-    name: "verify",
-    summary: "Check the docs still describe the code you installed",
-    group: "core",
-    usage: "docspack verify [options]",
-    options: [["--package-dir <d>", "verify one package directory instead of what is installed"]],
-    detail: [
-      "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.',
-      "Exits 1 when anything was reported.",
-    ],
-    examples: ["docspack verify", "docspack verify --json"],
-  },
-  {
-    name: "feedback",
-    summary: "Record documentation problems: add, list, submit, remove",
-    group: "core",
-    usage: "docspack feedback <add|list|submit|remove> [options]",
-    options: [
-      ["--chunk <id>", "add: the chunk the problem is in"],
-      ["--kind <k>", "add: drift, incorrect or missing"],
-      ["--evidence <text>", "add: the claim, in one line"],
-      ["--expected <text>", "add: what the documentation led you to expect"],
-      ["--actual <text>", "add: what happened instead"],
-      ["--repro <code>", "add: code that demonstrates it"],
-      ["-p, --package <s>", "submit: only findings from packages matching this text"],
-      ["--all", "remove: every recorded finding"],
-    ],
-    detail: [
-      "Writes to .docspack/feedback.jsonl in this project. Nothing is transmitted: docspack",
-      "contains no code that can send a report anywhere.",
-      "",
-      "`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.",
-    ],
-    examples: [
-      'docspack feedback add --chunk @acme/docspack@1.4.0/api-auth --kind drift --evidence "client.setKey is not exported; setApiKey is"',
-      "docspack feedback list",
-      "docspack feedback submit",
-      "docspack feedback remove <fingerprint>",
-    ],
-  },
-  {
-    name: "mcp",
-    summary: "Serve the index over MCP instead, as a long-lived process",
-    group: "core",
-    usage: "docspack mcp",
-    options: [],
-    detail: [
-      "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.",
-    ],
-    examples: ["docspack mcp"],
-  },
-  {
-    name: "sources",
-    summary: "List curated sources that `docspack build` can fetch",
-    group: "core",
-    usage: "docspack sources",
-    options: [],
-    examples: ["docspack sources", "docspack build hono --name @docspack-community/hono"],
-  },
-  {
-    name: "init",
-    summary: "Scaffold a documentation package, then build and check it",
-    group: "authoring",
-    usage: "docspack init [name] [options]",
-    options: [
-      ["-y, --yes", "skip the prompts and use flags plus detected defaults"],
-      ["--dry-run", "print the file tree and write nothing"],
-      ["--mirror <id|url>", "bootstrap from a published llms.txt"],
-      ["--community", "scaffold under @docspack-community"],
-      ["--template <t>", "full (default) or minimal"],
-      ["--mode <m>", "standalone or in-repo"],
-      ["--no-workflow", "skip the release workflow"],
-      ["--no-build", "scaffold only"],
-      ["--name <name>", "package name, e.g. @acme/docspack"],
-      ["--pkg-version <v>", "package version"],
-      ["--from <dir>", "directory of Markdown to package"],
-      ["--openapi <file>", "OpenAPI JSON to package"],
-      ["--out <dir>", "where to scaffold (default: ./docspack)"],
-      ["--force", "overwrite files that already exist"],
-    ],
-    detail: [
-      "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.",
-    ],
-    examples: [
-      "docspack init",
-      "docspack init --name @acme/docspack --from ./docs --yes",
-      "docspack init --mirror hono --community --yes",
-    ],
-  },
-  {
-    name: "build",
-    summary: "Generate the .llms/ payload for publishing",
-    group: "authoring",
-    usage: "docspack build [source] [options]",
-    options: [
-      ["--from <dir>", "directory of Markdown to package"],
-      ["--openapi <file>", "OpenAPI 3 document (JSON or YAML), one chunk per operation"],
-      ["--name <name>", "package name, e.g. @acme/docspack"],
-      ["--pkg-version <v>", "package version"],
-      ["--out <dir>", "output directory (default: the current directory)"],
-      ["--pages <n>", "maximum documents to fetch from a remote source"],
-      ["--max-chunk-tokens <n>", "split a section above this size (default 800)"],
-      ["--min-chunk-tokens <n>", "pack adjacent sections up to this size before splitting"],
-      ["--documents <p>", "library this package documents, repeatable: acme@1.4.0"],
-    ],
-    detail: [
-      "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.",
-      "",
-      "--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.",
-      "",
-      "With no flags, settings are read from the docspack key of the package.json in --out.",
-    ],
-    examples: [
-      "docspack build",
-      "docspack build --from ./docs --name @acme/docspack --pkg-version 1.4.0",
-      "docspack build --from ./reference --min-chunk-tokens 400 --max-chunk-tokens 900",
-      "docspack build --openapi ./openapi.json",
-      "docspack build --from ./docs --openapi ./openapi.json",
-    ],
-  },
-  {
-    name: "doctor",
-    summary: "Check a package the way the indexer and a reviewer would",
-    group: "authoring",
-    usage: "docspack doctor [options]",
-    options: [
-      ["--strict", "treat structural warnings as failures"],
-      ["--pedantic", "--strict, and fail on prose style as well"],
-      ["--package-dir <d>", "the package to inspect (default: .)"],
-    ],
-    detail: [
-      "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. Exits 1 when the package is not ready to publish.",
-    ],
-    examples: ["docspack doctor", "docspack doctor --strict", "docspack doctor --json"],
-  },
-  {
-    name: "preview",
-    summary: "Answer a query from the local package, as an agent would",
-    group: "authoring",
-    usage: "docspack preview <query> [options]",
-    options: [
-      ["--package-dir <d>", "the package to read (default: .)"],
-      ["--limit <n>", `maximum chunks to return (default ${LIMIT})`],
-      ["--max-tokens <n>", `token ceiling for the result set (default ${MAX_TOKENS})`],
-    ],
-    detail: [
-      "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.",
-    ],
-    examples: ['docspack preview "how do I authenticate"'],
-  },
-  {
-    name: "eval",
-    summary: "Measure retrieval against a set of questions",
-    group: "authoring",
-    usage: "docspack eval <queries.json> [options]",
-    options: [
-      ["--package-dir <d>", "the package to read (default: .)"],
-      ["--limit <n>", `chunks per answer, the window a hit must fall in (default ${LIMIT})`],
-      ["--max-tokens <n>", `token ceiling for each answer (default ${MAX_TOKENS})`],
-      ["--min-hit-rate <n>", "exit 1 below this percentage of questions answered"],
-    ],
-    detail: [
-      "The evaluation set is a JSON array of questions and the chunk ids that would answer them:",
-      "",
-      '  [{ "query": "how do I verify a webhook signature", "expect": "webhooks-signing" },',
-      '   { "query": "rate limits", "expect": ["rate-limits", "errors"] }]',
-      "",
-      "Reports 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.",
-    ],
-    examples: [
-      "docspack eval ./eval/queries.json",
-      "docspack eval ./eval/queries.json --min-hit-rate 90",
-      "docspack eval ./eval/queries.json --limit 1 --json",
-    ],
-  },
-];
-
-const GLOBAL_OPTIONS: readonly (readonly [string, string])[] = [
-  ["--store <path>", "Use a different index"],
-  ["--cwd <dir>", "Run in a different directory"],
-  ["--json", "Machine-readable output"],
-  ["-q, --quiet", "Only print errors"],
-  ["-h, --help", "Show this help, or a command's help"],
-  ["-v, --version", "Show the version"],
-];
+const WIDTH = 21;
+/** The width prose is wrapped to, which is what the hand-written help used. */
+const TEXT_WIDTH = 92;
+
+const RESOLVED = resolveDocument(CLI);
+
+/** The program's commands as a caller types them, in the order the document declares them. */
+export const COMMANDS: readonly CommandHelp[] = RESOLVED.commands
+  .filter((command) => command.path.length === 2 && !command.hidden)
+  .map(toHelp);
+
+const ROOT = RESOLVED.commands[0] as ResolvedCommand;
+
+/** Every option the root declares — the inherited ones every command takes, and its own. */
+const GLOBAL_OPTIONS: readonly (readonly [string, string])[] = ROOT.options.map(optionRow);
 
 export function findCommandHelp(name: string): CommandHelp | undefined {
   return COMMANDS.find((command) => command.name === name);
 }
 
-const WIDTH = 21;
+/** The document this help is rendered from, for `docspack --cmdspec`. */
+export function cliDocument(version: string): CmdspecDocument {
+  return { ...CLI, info: { ...CLI.info, version } };
+}
 
 function row([flag, description]: readonly [string, string]): string {
-  return `  ${flag.padEnd(WIDTH)} ${description}`;
+  return description.length === 0 ? `  ${flag}` : `  ${flag.padEnd(WIDTH)} ${description}`;
 }
 
 /** The page one command prints for `docspack <command> --help`. */
 export function commandHelpText(command: CommandHelp): string {
+  const resolved = RESOLVED.commands.find(
+    (candidate) => commandPath(candidate) === `docspack ${command.name}`,
+  );
   const blocks: string[] = [
     `docspack ${command.name} — ${command.summary}`,
     "",
     "Usage",
     `  ${command.usage}`,
   ];
+  for (const sub of subcommandsOf(resolved)) blocks.push(`  ${synopsis(sub)}`);
 
   if (command.detail !== undefined) {
     blocks.push("", ...command.detail.map((line) => (line.length === 0 ? "" : `  ${line}`)));
@@ -415,6 +79,13 @@ export function commandHelpText(command: CommandHelp): string {
   if (command.options.length > 0) {
     blocks.push("", "Options", ...command.options.map(row));
   }
+  for (const sub of subcommandsOf(resolved)) {
+    const rows = sub.options.filter((option) => option.hidden !== true).map(optionRow);
+    blocks.push("", `${commandPath(sub)} — ${commandSummary(sub) ?? ""}`);
+    if (rows.length > 0) blocks.push(...rows.map(row));
+  }
+  const exits = exitRows(resolved);
+  if (exits.length > 0) blocks.push("", "Exit status", ...exits.map(row));
   blocks.push(
     "",
     "Global options",
@@ -427,6 +98,92 @@ export function commandHelpText(command: CommandHelp): string {
   return blocks.join("\n");
 }
 
+function toHelp(command: ResolvedCommand): CommandHelp {
+  const description = command.declared.description;
+  return {
+    name: command.path[1] as string,
+    summary: commandSummary(command) ?? "",
+    group: command.declared.group === "authoring" ? "authoring" : "core",
+    usage: synopsis(command),
+    options: command.options.filter((option) => option.hidden !== true).map(optionRow),
+    ...(description === undefined ? {} : { detail: wrap(description) }),
+    examples: [command, ...subcommandsOf(command)]
+      .flatMap((each) => (each.declared.examples ?? []).map((example) => example.run))
+      .filter((run, index, all) => all.indexOf(run) === index),
+  };
+}
+
+function subcommandsOf(command: ResolvedCommand | undefined): ResolvedCommand[] {
+  if (command === undefined) return [];
+  return RESOLVED.commands.filter(
+    (candidate) =>
+      !candidate.hidden &&
+      candidate.path.length === command.path.length + 1 &&
+      commandPath(candidate).startsWith(`${commandPath(command)} `),
+  );
+}
+
+/** One option as a help row: its spellings and value, then what it does and its default. */
+function optionRow(option: ResolvedOption): readonly [string, string] {
+  const spellings = [option.name, ...(option.aliases ?? [])]
+    .sort((a, b) => a.length - b.length)
+    .join(", ");
+  const negation = option.negation === undefined ? "" : `, ${option.negation.join(", ")}`;
+  const placeholder = option.value === undefined ? "" : ` <${option.value.name ?? "value"}>`;
+  const value = option.value;
+  const notes = [
+    value?.enum === undefined ? undefined : value.enum.join(", "),
+    value?.default !== undefined
+      ? `default ${String(value.default)}`
+      : value?.defaultDescription === undefined
+        ? undefined
+        : `default: ${value.defaultDescription}`,
+    option.repeat === "list" ? "repeatable" : undefined,
+    option.required === true ? "required" : undefined,
+    option.env === undefined ? undefined : `env ${option.env.join(", ")}`,
+  ].filter((note) => note !== undefined);
+  const summary = option.summary ?? "";
+  const text =
+    notes.length === 0
+      ? summary
+      : `${summary}${summary.length > 0 ? " " : ""}(${notes.join("; ")})`;
+  return [`${spellings}${placeholder}${negation}`, text];
+}
+
+/** The statuses a command adds to the program's 0, 1 and 2, with its subcommands'. */
+function exitRows(command: ResolvedCommand | undefined): (readonly [string, string])[] {
+  if (command === undefined) return [];
+  const rows: (readonly [string, string])[] = [];
+  for (const each of [command, ...subcommandsOf(command)]) {
+    for (const [code, exit] of Object.entries(each.declared.exits ?? {})) {
+      const who = each === command ? "" : ` (${each.path.slice(2).join(" ")})`;
+      rows.push([code, `${exit.meaning}${who}`]);
+    }
+  }
+  return rows;
+}
+
+/** A description as help lines: paragraphs wrapped, indented blocks kept as written. */
+function wrap(text: string): string[] {
+  const lines: string[] = [];
+  for (const paragraph of text.split("\n\n")) {
+    if (lines.length > 0) lines.push("");
+    if (paragraph.startsWith("    ")) {
+      lines.push(...paragraph.split("\n").map((line) => line.slice(2)));
+      continue;
+    }
+    let current = "";
+    for (const word of paragraph.replace(/\s+/g, " ").trim().split(" ")) {
+      if (current.length > 0 && current.length + 1 + word.length > TEXT_WIDTH) {
+        lines.push(current);
+        current = word;
+      } else current = current.length === 0 ? word : `${current} ${word}`;
+    }
+    if (current.length > 0) lines.push(current);
+  }
+  return lines;
+}
+
 /**
  * The global page. It lists the commands and the options that apply to all of them, and points
  * at the per-command pages for the rest — one list of every flag of every command was what made
@@ -451,10 +208,11 @@ Authoring
 ${group("authoring")}
 
 How it works
-  Documentation ships as npm packages named @vendor/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.
+  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.
 
 Giving an agent access
   Any agent with a shell can run \`docspack ask\`, so one line in AGENTS.md or

package/src/index.ts

@@ -151,6 +151,7 @@ export {
   CHUNKS_DIR,
   type ChunkSpec,
   chunkId,
+  DISCOVERABLE_NAMES,
   type DocumentedLibrary,
   estimateTokens,
   formatDocumentedLibrary,

package/src/init/plan.ts

@@ -1,6 +1,6 @@
 import { posix } from "node:path";
 import { DocspackError } from "../errors.js";
-import { isCommunityPackage, isDocsPackage } from "../spec.js";
+import { DISCOVERABLE_NAMES, isCommunityPackage, isDocsPackage } from "../spec.js";
 import type { Detected } from "./detect.js";
 import { docSeeds, gitignore, packageJson, readme, workflow } from "./templates.js";
 
@@ -135,7 +135,7 @@ export function proposePackageName(detected: Detected, community: boolean): stri
 function assertPackageName(name: string): void {
   if (!isDocsPackage(name)) {
     throw new DocspackError(`"${name}" is not a name docspack will discover`, {
-      hint: "Use @vendor/docspack for a package you own, or @docspack-community/<name> otherwise.",
+      hint: `Use one of ${DISCOVERABLE_NAMES}.`,
     });
   }
 }
@@ -156,7 +156,8 @@ function resolveInput(
   if (options.mirror !== undefined) {
     if (!isCommunityPackage(options.name ?? "")) {
       notes.push(
-        "A mirror republishes someone else's documentation; publish it under @docspack-community rather than the vendor's scope.",
+        "A mirror republishes someone else's documentation; publish it under @docspack-community, " +
+          "or as @yourscope/<name>-docspack if you own the scope — not as the vendor's own @vendor/docspack.",
       );
     }
     return { kind: "mirror", value: options.mirror };

package/src/init/templates.ts

@@ -154,8 +154,10 @@ ${PLACEHOLDER} same shape as above.
 }
 
 export function workflow(name: string, buildArgs: string): string {
-  return `# Publishes ${name} on every release, so the documentation version always
-# matches the library version. Needs an NPM_TOKEN secret with publish rights.
+  return `# Publishes ${name} on every release, so the documentation version matches the
+# library version by default. That is a convention, not a constraint: to correct published
+# documentation between two releases, dispatch this workflow with a version of its own and
+# declare \`documents\` in the package. Needs an NPM_TOKEN secret with publish rights.
 
 name: Publish documentation package