@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/kernel/project/cli/globalFlags.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 import {
+  findValuedVerbose,
   parseGlobalFlags,
+  readRawDetail,
   readRawFormat,
   stripGlobalFlags,
 } from "./globalFlags.js";
@@ -30,7 +32,7 @@ describe("parseGlobalFlags", () => {
     expect(parseGlobalFlags(["--format=json"], TTY).format).toBe("json");
   });
 
-  it("renames --format text to plain", () => {
+  it("maps an unrecognized --format value to plain (the bin rejects it first)", () => {
     expect(parseGlobalFlags(["--format", "text"], PIPE).format).toBe("plain");
   });
 
@@ -68,6 +70,55 @@ describe("parseGlobalFlags", () => {
   it("reads --verbose", () => {
     expect(parseGlobalFlags(["--verbose"], TTY).verbose).toBe(true);
   });
+
+  it("reports the raw --detail value for validation, including valueless", () => {
+    expect(readRawDetail(["--detail", "detailed"])).toBe("detailed");
+    expect(readRawDetail(["--detail=bogus"])).toBe("bogus");
+    // "" so a valueless flag is rejected, never silently defaulted.
+    expect(readRawDetail(["--detail", "--category"])).toBe("");
+    expect(readRawDetail(["block", "list"])).toBeUndefined();
+    // Past the terminator it is data, not a flag of this program.
+    expect(readRawDetail(["lookup", "--", "--detail=x"])).toBeUndefined();
+  });
+
+  it("finds a valued --verbose token so the bin can reject it", () => {
+    expect(findValuedVerbose(["--verbose=true"])).toBe("--verbose=true");
+    expect(findValuedVerbose(["--verbose"])).toBeUndefined();
+    expect(findValuedVerbose(["lookup", "--", "--verbose=x"])).toBeUndefined();
+  });
+
+  it("reads --no-headers anywhere and strips it before Commander", () => {
+    expect(parseGlobalFlags(["--no-headers"], TTY).noHeaders).toBe(true);
+    expect(
+      parseGlobalFlags(["block", "list", "--no-headers"], TTY).noHeaders,
+    ).toBe(true);
+    expect(parseGlobalFlags(["block", "list"], TTY).noHeaders).toBeUndefined();
+    expect(stripGlobalFlags(["block", "list", "--no-headers"])).toEqual([
+      "block",
+      "list",
+    ]);
+    // Past the terminator it is the user's data, not this program's flag.
+    expect(
+      parseGlobalFlags(["block", "lookup", "--", "--no-headers"], TTY)
+        .noHeaders,
+    ).toBeUndefined();
+  });
+
+  it("reads --quiet anywhere and strips it before Commander", () => {
+    expect(parseGlobalFlags(["--quiet"], TTY).quiet).toBe(true);
+    expect(parseGlobalFlags(["sources", "update", "--quiet"], TTY).quiet).toBe(
+      true,
+    );
+    expect(parseGlobalFlags(["sources", "update"], TTY).quiet).toBeUndefined();
+    expect(stripGlobalFlags(["sources", "update", "--quiet"])).toEqual([
+      "sources",
+      "update",
+    ]);
+    // Past the terminator it is the user's data, not this program's flag.
+    expect(
+      parseGlobalFlags(["graph", "query", "--", "--quiet"], TTY).quiet,
+    ).toBeUndefined();
+  });
 });
 
 describe("stripGlobalFlags", () => {
@@ -105,3 +156,68 @@ describe("readRawFormat", () => {
     expect(readRawFormat(["block", "list"])).toBeUndefined();
   });
 });
+
+describe("the option terminator bounds every scan (PROTECTED)", () => {
+  // `--` means the rest is the user's data. A scanner that ignored it would
+  // both misread a flag and STRIP it, so a lookup for a block literally named
+  // `--format` would lose its own argument and change how the error rendered.
+  it("does not read a flag that appears after `--`", () => {
+    expect(readRawFormat(["block", "lookup", "--", "--format", "json"])).toBe(
+      undefined,
+    );
+    expect(
+      parseGlobalFlags(["block", "lookup", "--", "--verbose"], TTY).verbose,
+    ).toBe(false);
+    expect(
+      parseGlobalFlags(["block", "lookup", "--", "--detail", "detailed"], TTY)
+        .detail,
+    ).toBe(undefined);
+  });
+
+  it("hands everything from `--` onward through untouched", () => {
+    expect(
+      stripGlobalFlags(["block", "lookup", "--", "--format", "json"]),
+    ).toEqual(["block", "lookup", "--", "--format", "json"]);
+  });
+
+  it("still reads a flag that appears before `--`", () => {
+    expect(
+      readRawFormat(["--format", "json", "block", "lookup", "--", "x"]),
+    ).toBe("json");
+    expect(
+      stripGlobalFlags(["--format", "json", "block", "lookup", "--", "x"]),
+    ).toEqual(["block", "lookup", "--", "x"]);
+  });
+});
+
+describe("a flag's value is never another flag (PROTECTED)", () => {
+  // The defect this pins: a valueless `--detail` consumed the NEXT flag as its
+  // value and stripped it, so `--detail --category css` silently answered over
+  // the whole set instead of the filtered one — a wrong answer, no diagnostic.
+  it("leaves a following flag standing when the value is absent", () => {
+    expect(
+      stripGlobalFlags(["standard", "list", "--detail", "--category", "css"]),
+    ).toEqual(["standard", "list", "--category", "css"]);
+  });
+
+  it("reports no detail for a valueless --detail", () => {
+    expect(
+      parseGlobalFlags(["standard", "list", "--detail", "--category"], TTY)
+        .detail,
+    ).toBe(undefined);
+  });
+
+  it("still consumes a real value", () => {
+    expect(
+      stripGlobalFlags(["standard", "list", "--detail", "summary"]),
+    ).toEqual(["standard", "list"]);
+    expect(
+      parseGlobalFlags(["standard", "list", "--detail", "summary"], TTY).detail,
+    ).toBe("summary");
+  });
+
+  it("reports a valueless --format as empty so the caller rejects it", () => {
+    // `""`, not `undefined` — `undefined` would fall through to the default.
+    expect(readRawFormat(["--format", "--verbose"])).toBe("");
+  });
+});

package/src/kernel/project/cli/globalFlags.ts

@@ -1,18 +1,63 @@
 /**
  * Global-flag pre-parsing, ahead of Commander.
  *
- * `--format`, `--verbose`, and `--detail` may appear anywhere on the line, so
+ * `--format`, `--verbose`, `--no-headers`, and `--detail` may appear anywhere on the line, so
  * they are scanned and stripped before Commander sees argv — otherwise
  * `enablePositionalOptions()` scoping would reject a flag placed after a verb.
+ *
+ * ANYWHERE STOPS AT `--`. Everything after the option terminator is the user's
+ * data, not this program's flags: `block lookup -- --format` looks up a block
+ * literally named `--format`. Commander honours the terminator on its own, so
+ * a scan here that ignored it would parse — and strip — tokens Commander was
+ * about to hand through verbatim.
+ *
+ * A FLAG'S VALUE IS NEVER ANOTHER FLAG. `--detail --category css` supplies no
+ * detail; it is a valueless `--detail` followed by a separate flag. Reading the
+ * next token unconditionally would consume `--category` as the value and strip
+ * it, so the filter would vanish and the command would answer over the whole
+ * set instead — a wrong answer with no diagnostic.
  * Ported from the v1 `parseGlobalFlags`, with two v2 changes: a new `--detail`
- * flag and the `--format text` value renamed to `plain` (the kernel's
- * {@link OutputFormat}). The dedicated `--llm` flag was folded into
- * `--format llm`, leaving auto-detection as the sole implicit trigger. Both the
- * space (`--format json`) and equals (`--format=json`) forms are recognized.
+ * flag and the `--format text` value replaced by `plain` (the kernel's
+ * {@link OutputFormat}) — `text` is not accepted; the bin rejects it with the
+ * valid list. The dedicated `--llm` flag was folded into `--format llm`,
+ * leaving auto-detection as the sole implicit trigger. Both the space
+ * (`--format json`) and equals (`--format=json`) forms are recognized.
  */
 
 import { DETAIL_LEVELS, type DetailLevel } from "../../../constants.js";
-import type { GlobalFlags } from "../../runtime/types.js";
+import { stdoutIsCaptured } from "../../interactivity.js";
+import type { GlobalFlags } from "../../runtime/index.js";
+
+/** The end-of-options separator: nothing after it is a flag of this program. */
+const OPTION_TERMINATOR = "--";
+
+/**
+ * The span of argv this program's flags may occupy — everything before the
+ * option terminator, or all of argv when there is none. Exported for the
+ * bin's retired-flag detection: a retired spelling AFTER the terminator is
+ * an operand, not a flag, and must not trigger a migration message.
+ *
+ * @param argv - The user's arguments.
+ * @returns The scannable span; the same array when no terminator is present.
+ */
+export function selectScanSpan(argv: readonly string[]): readonly string[] {
+  const terminator = argv.indexOf(OPTION_TERMINATOR);
+  return terminator === -1 ? argv : argv.slice(0, terminator);
+}
+
+/**
+ * Whether a token can serve as a flag's value.
+ *
+ * A token starting with `-` is the next flag, not this one's value. Shared by
+ * every reader below so the space form cannot swallow a sibling flag at one
+ * call site while guarding against it at another.
+ *
+ * @param token - The token following a flag, if any.
+ * @returns True when the token is a value rather than another flag.
+ */
+function isFlagValue(token: string | undefined): token is string {
+  return token !== undefined && !token.startsWith("-");
+}
 
 /**
  * Read a `--flag`'s value, accepting both `--flag value` and `--flag=value`.
@@ -25,35 +70,74 @@ function readFlagValue(
   argv: readonly string[],
   flag: string,
 ): string | undefined {
+  const span = selectScanSpan(argv);
   const equalsPrefix = `${flag}=`;
-  const equalsArg = argv.find((arg) => arg.startsWith(equalsPrefix));
+  const equalsArg = span.find((arg) => arg.startsWith(equalsPrefix));
   if (equalsArg !== undefined) {
     return equalsArg.slice(equalsPrefix.length);
   }
-  const spaceIndex = argv.indexOf(flag);
-  return spaceIndex === -1 ? undefined : argv[spaceIndex + 1];
+  const spaceIndex = span.indexOf(flag);
+  if (spaceIndex === -1) return undefined;
+  const value = span.at(spaceIndex + 1);
+  return isFlagValue(value) ? value : undefined;
 }
 
 /**
- * Read the raw `--format` value exactly as typed, for validation.
+ * Read a value flag's raw value exactly as typed, for validation.
  *
  * Unlike {@link parseGlobalFlags} this does not normalize — the caller decides
- * how to reject an unknown value. A bare `--format` with no following value is
+ * how to reject an unknown value. A bare flag with no following value is
  * reported as `""` (not `undefined`) so it is rejected rather than silently
- * falling through.
+ * falling through. One reader for every validated global value flag, so a
+ * guard applied to one cannot silently miss its siblings.
  *
  * @param argv - Raw argv (the user's arguments).
- * @returns The raw value, `""` for a valueless `--format`, or `undefined`.
+ * @param flag - The flag including leading dashes (e.g. `--format`).
+ * @returns The raw value, `""` for a valueless flag, or `undefined`.
  */
-export function readRawFormat(argv: readonly string[]): string | undefined {
-  const equalsArg = argv.find((arg) => arg.startsWith("--format="));
-  if (equalsArg !== undefined) return equalsArg.slice("--format=".length);
+function readRawFlag(
+  argv: readonly string[],
+  flag: string,
+): string | undefined {
+  const span = selectScanSpan(argv);
+  const equalsPrefix = `${flag}=`;
+  const equalsArg = span.find((arg) => arg.startsWith(equalsPrefix));
+  if (equalsArg !== undefined) return equalsArg.slice(equalsPrefix.length);
 
-  const spaceIndex = argv.indexOf("--format");
+  const spaceIndex = span.indexOf(flag);
   if (spaceIndex === -1) return undefined;
 
-  const value = argv[spaceIndex + 1];
-  return value !== undefined && !value.startsWith("-") ? value : "";
+  // `""` rather than `undefined`: a valueless flag must be REJECTED by the
+  // caller, not fall through to the default.
+  const value = span.at(spaceIndex + 1);
+  return isFlagValue(value) ? value : "";
+}
+
+/** The raw `--format` value as typed (see {@link readRawFlag}). */
+export function readRawFormat(argv: readonly string[]): string | undefined {
+  return readRawFlag(argv, "--format");
+}
+
+/**
+ * The raw `--detail` value as typed (see {@link readRawFlag}). Validated by
+ * the bin exactly as `--format` is — an unrecognized level used to be
+ * dropped silently, which is the same defect class as a filter that
+ * evaporates: wrong output with no diagnostic.
+ */
+export function readRawDetail(argv: readonly string[]): string | undefined {
+  return readRawFlag(argv, "--detail");
+}
+
+/**
+ * The `--verbose=<x>` token, if present. `--verbose` takes no value — one
+ * flag, one spelling — and the program must not accept-and-ignore a second
+ * one: the bin rejects the token this finds.
+ *
+ * @param argv - Raw argv (the user's arguments).
+ * @returns The offending token, or `undefined`.
+ */
+export function findValuedVerbose(argv: readonly string[]): string | undefined {
+  return selectScanSpan(argv).find((arg) => arg.startsWith("--verbose="));
 }
 
 /**
@@ -70,7 +154,9 @@ export interface OutputEnvironment {
 /** Read the real stdout/env output environment. @note Impure — reads process. */
 function readOutputEnvironment(): OutputEnvironment {
   return {
-    isTty: process.stdout.isTTY === true,
+    // The OUTPUT-SHAPE question, on stdout — not the prompting one. A run whose
+    // stdout is captured may still have a terminal to prompt on (`canPrompt`).
+    isTty: !stdoutIsCaptured(),
     noAutoLlm: Boolean(process.env.PRAGMA_NO_AUTO_LLM),
   };
 }
@@ -108,11 +194,18 @@ export function parseGlobalFlags(
   const formatRequested = rawFormat !== undefined;
   const autoLlm = !formatRequested && !env.isTty && !env.noAutoLlm;
   const detail = readDetail(argv);
+  const span = selectScanSpan(argv);
   return {
     llm: format === "llm" || autoLlm,
     autoLlm,
     format,
-    verbose: argv.includes("--verbose"),
+    verbose: span.includes("--verbose"),
+    // `--no-headers` suppresses the plain-table header row; it is global so
+    // every list-shaped verb honors one spelling.
+    ...(span.includes("--no-headers") ? { noHeaders: true } : {}),
+    // `--quiet` silences success/progress (the report seam, interpreter logs,
+    // onboarding, calm notices) while error rendering stays untouched.
+    ...(span.includes("--quiet") ? { quiet: true } : {}),
     ...(detail !== undefined ? { detail } : {}),
   };
 }
@@ -122,7 +215,8 @@ export function parseGlobalFlags(
  *
  * Since {@link parseGlobalFlags} pre-parses these, they are dropped so they do
  * not collide with Commander's positional scoping, letting the user place them
- * anywhere on the line.
+ * anywhere on the line — anywhere before the option terminator, which this
+ * stops at and hands through whole.
  *
  * @param argv - The user's arguments.
  * @returns A new array with global flags stripped.
@@ -130,20 +224,29 @@ export function parseGlobalFlags(
 export function stripGlobalFlags(argv: readonly string[]): string[] {
   const result: string[] = [];
   for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--verbose") continue;
-    if (
-      arg?.startsWith("--format=") ||
-      arg?.startsWith("--verbose=") ||
-      arg?.startsWith("--detail=")
-    ) {
+    const arg = argv.at(i);
+    if (arg === undefined) continue;
+
+    // Past the terminator nothing is ours: hand the remainder over untouched,
+    // terminator included, so Commander still sees where options end.
+    if (arg === OPTION_TERMINATOR) {
+      result.push(...argv.slice(i));
+      return result;
+    }
+
+    if (arg === "--verbose" || arg === "--no-headers" || arg === "--quiet") {
+      continue;
+    }
+    if (arg.startsWith("--format=") || arg.startsWith("--detail=")) {
       continue;
     }
     if (arg === "--format" || arg === "--detail") {
-      i += 1; // skip the space-form value too
+      // Skip the value ONLY when the next token is one. A valueless flag before
+      // another flag must leave that flag standing.
+      if (isFlagValue(argv.at(i + 1))) i += 1;
       continue;
     }
-    result.push(arg as string);
+    result.push(arg);
   }
   return result;
 }

package/src/kernel/project/cli/helpFormat.ts

@@ -11,9 +11,8 @@
  */
 
 import chalk from "chalk";
+import { INDENT } from "../../render/vocabulary.js";
 
-/** Two-space indent for every list body row. */
-const INDENT = "  ";
 /** Two-space gap between a term column and its description. */
 const GAP = "  ";
 
@@ -32,6 +31,19 @@ export function helpTerm(text: string): string {
   return chalk.cyan(text);
 }
 
+/**
+ * The wordmark's colour.
+ *
+ * `yellow` is a PALETTE slot, not a fixed hue: the 16-colour ANSI palette has no
+ * orange, and this slot is the one terminal themes render as orange — Ubuntu's
+ * among them. Naming the slot rather than a 256-colour or truecolour orange is
+ * what lets the wordmark follow the user's own theme instead of fighting it, and
+ * keeps it legible on light backgrounds where a hardcoded orange would not be.
+ */
+export function helpLogo(text: string): string {
+  return chalk.yellow(text);
+}
+
 /** The `Usage:` line: a dim label followed by the given command shape. */
 export function helpUsage(body: string): string {
   return `${chalk.dim("Usage:")} ${body}`;

package/src/kernel/project/cli/rootHelp.ts

@@ -10,11 +10,14 @@
  * never heard of still surfaces.
  */
 
-import type { VerbSpec } from "../../spec/types.js";
+import { PROGRAM_LOGO } from "../../../constants.js";
+import type { GlobalFlags } from "../../runtime/index.js";
+import type { VerbSpec } from "../../spec/index.js";
 import {
   helpColumns,
   helpDim,
   helpHeading,
+  helpLogo,
   helpTerm,
   helpUsage,
 } from "./helpFormat.js";
@@ -79,6 +82,7 @@ function buildKernelGroups(programName: string): readonly HelpGroup[] {
           summary: `Read and write ${programName} configuration`,
         },
         { noun: "info", summary: "Show version, config, and update status" },
+        { noun: "version", summary: "Print the CLI version" },
         {
           noun: "upgrade",
           summary: `Upgrade the ${programName} CLI to the latest version`,
@@ -92,14 +96,16 @@ function buildKernelGroups(programName: string): readonly HelpGroup[] {
           noun: "capabilities",
           summary: "Discover conventions, tools, and the discovery sequence",
         },
-        {
-          noun: "colophon",
-          summary: `Read how ${programName} and the active domain are made`,
-        },
+        // A colophon is the note at the back of a book: the typeface, the
+        // press, the paper. Nothing depends on it, which is the point — so
+        // this line does not argue for it. Every other summary in this column
+        // promises work done; this one just invites you to look.
+        { noun: "colophon", summary: "Read the credits" },
         { noun: "skill", summary: "Browse agent skills from the active packs" },
         { noun: "prompt", summary: "Browse reusable prompt templates" },
-        // The one noun with no verb to speak for it (the bin special-cases it),
-        // so its summary is hand-written rather than derived.
+        // Curated for PLACEMENT, not for existence: `mcp serve` is an
+        // ordinary verb like every other, and this group is where a reader
+        // looks for it.
         { noun: "mcp", summary: "Start the MCP server over stdio" },
       ],
     },
@@ -127,23 +133,53 @@ function summarizeNoun(noun: string, verbs: readonly VerbSpec[]): string {
   return (first?.summary ?? `${noun} commands`).replace(/\.$/, "");
 }
 
+/**
+ * Whether this reader is worth spending the wordmark on.
+ *
+ * An AUDIENCE question, not a data question: the art is 11 lines and ~200
+ * tokens — roughly a third of what `--help` costs an agent — and it says
+ * nothing an agent can act on. Both captured shapes are excluded:
+ * `llm` (requested, or inferred from a non-interactive stdout — the shape an
+ * agent captures) and `json`. `--format plain` therefore keeps the art even
+ * down a pipe, and `--format llm` drops it even on a terminal: explicit beats
+ * inference, the same inferred-vs-explicit split `renderErrorForFormat` uses.
+ *
+ * The DECISION is passed in as data — both call sites already hold the parsed
+ * flags — so this module still reads no `process` state and stays testable.
+ *
+ * @param flags - The invocation's global flags.
+ * @returns `true` when a human is reading and the wordmark should print.
+ */
+function wordmarkSuitsReader(flags: GlobalFlags): boolean {
+  return flags.llm !== true && flags.format !== "json";
+}
+
 /**
  * Build the curated root help string.
  *
  * @param programName - The CLI binary name (the distribution's `name`).
  * @param description - The program description shown in the header.
  * @param verbs - All registered verbs, used to derive the live noun set.
+ * @param issuesUrl - Where the preview notice sends feedback; the
+ *   distribution's own, so a fork points at its own tracker.
+ * @param version - The version to stamp on the header. Passed in rather than
+ *   read here so it is the SAME string `--version` prints: `buildProgram`
+ *   resolves `options.version ?? VERSION`, and a host that overrides one must
+ *   not be able to leave the other saying something else.
+ * @param globalFlags - The invocation's global flags, read only to decide who
+ *   is reading (see {@link wordmarkSuitsReader}). Passed rather than probed: the
+ *   help layer must not learn to read `process`.
  * @returns The formatted, colorized help text.
  */
 export function formatRootHelp(
   programName: string,
   description: string,
   verbs: readonly VerbSpec[],
+  version: string,
+  issuesUrl: string,
+  globalFlags: GlobalFlags,
 ): string {
   const present = nounsFrom(verbs);
-  // `mcp` is served by the bin's special-case, not a projected verb, but is
-  // always available — surface it so the front door is complete.
-  present.add("mcp");
   const kernel = buildKernelGroups(programName);
   const curated = new Set(kernel.flatMap((g) => g.nouns.map((n) => n.noun)));
 
@@ -171,7 +207,31 @@ export function formatRootHelp(
   );
 
   const lines: string[] = [
-    `${helpHeading(programName)} — ${description}`,
+    // The wordmark leads when the distribution declares one AND a human is
+    // reading it. A fork ships its own art or none, so its front door is never
+    // branded with someone else's; and a captured run drops the art entirely
+    // rather than charging an agent ~200 tokens for a picture of the name it
+    // just typed (see `wordmarkSuitsReader`). The LINES go, not their colour:
+    // chalk already emits no escapes off a TTY, so dimming would save nobody
+    // anything.
+    ...(PROGRAM_LOGO.length > 0 && wordmarkSuitsReader(globalFlags)
+      ? [...PROGRAM_LOGO.map(helpLogo), ""]
+      : []),
+    // `<name> v<version> — <blurb>`, the spelling `info` and `capabilities`
+    // already use, so the front door names the build the same way every other
+    // surface does. Dimmed: it answers "which build am I on" for someone who
+    // is already here, and must not compete with the name.
+    `${helpHeading(programName)} ${helpDim(`v${version}`)} — ${description}`,
+    "",
+    // The preview notice. Dimmed and directly under the header, because it
+    // qualifies what the reader has just been told the tool IS — a version
+    // number alone does not say "expect this to move".
+    //
+    // The URL is the distribution's declared `issuesUrl`, never a literal:
+    // `kernel/copy.test.ts` forbids the kernel naming a distribution, and a
+    // fork inviting feedback to someone else's tracker would be worse than a
+    // missing line. It is passed in for the same reason `version` is.
+    helpDim(`This is a preview version. Issues and suggestions: ${issuesUrl}`),
     "",
     helpUsage(
       `${programName} ${helpTerm("<command>")} ${helpDim("[subcommand] [flags]")}`,
@@ -203,7 +263,9 @@ export function formatRootHelp(
       "--detail <level>",
       "Progressive-disclosure level (summary, standard, detailed)",
     ],
-    ["--verbose", "Diagnostic output on stderr"],
+    ["--no-headers", "Hide the table header row in plain output"],
+    ["--quiet", "Suppress success and progress output (errors still print)"],
+    ["--verbose", "Diagnostic output on stderr (sources update)"],
     ["--help", "Show help (works on any command)"],
     ["--version", "Show the CLI version"],
   ];

package/src/kernel/project/cli/suggest.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
+import { capabilities } from "../../../capabilities/index.js";
 import { fixtureModule } from "../../../testing/fixtures/fixtureCapability.js";
-import { nounVerbMap, resolveUnknownCommand } from "./suggest.js";
+import {
+  curatedSuggestions,
+  nounVerbMap,
+  resolveUnknownCommand,
+} from "./suggest.js";
 import { suggestNames } from "./suggestNames.js";
 
 const verbs = [...fixtureModule.verbs];
@@ -36,6 +41,33 @@ describe("resolveUnknownCommand", () => {
   });
 });
 
+describe("curatedSuggestions", () => {
+  it("answers the conventional spelling with the commands that own the job", () => {
+    // `status` is nowhere near `info` or `doctor` textually, so edit distance
+    // can never offer them. The table is the answer for a token whose JOB
+    // exists here under other names — and it stays a suggestion: `status` is
+    // not a command, because `info` already is.
+    expect(curatedSuggestions("status")).toEqual(["info", "doctor"]);
+  });
+
+  it("has nothing to say about a plain typo — that is ranking's job", () => {
+    expect(curatedSuggestions("infoo")).toBeUndefined();
+    expect(curatedSuggestions("")).toBeUndefined();
+  });
+
+  it("never names a command the program does not have", () => {
+    // A curated entry that outlived its target would send a confused user at
+    // nothing. Check every suggestion against the LIVE registry, so renaming
+    // `info` reddens here instead of shipping a dead hint.
+    const live = new Set(
+      capabilities.flatMap((m) => m.verbs.map((v) => v.path[0])),
+    );
+    for (const suggestion of curatedSuggestions("status") ?? []) {
+      expect(live.has(suggestion)).toBe(true);
+    }
+  });
+});
+
 describe("suggestNames", () => {
   it("ranks prefix matches ahead of edit-distance matches", () => {
     expect(suggestNames("con", ["config", "connect", "block"])).toEqual([

package/src/kernel/project/cli/suggest.ts

@@ -10,7 +10,31 @@
  * internals leak into the suggester.
  */
 
-import type { VerbSpec } from "../../spec/types.js";
+import type { VerbSpec } from "../../spec/index.js";
+
+/**
+ * Curated suggestions for a token whose JOB exists under other names. Edit
+ * distance cannot rank these — `status` is nowhere near `info` textually —
+ * but a user typing the conventional spelling deserves the commands that own
+ * the job here, not the nearest-looking noun. Consulted before fuzzy ranking;
+ * adding a second spelling as a real command is the one thing this table must
+ * never become.
+ */
+const CURATED_SUGGESTIONS: Readonly<Record<string, readonly string[]>> = {
+  status: ["info", "doctor"],
+};
+
+/**
+ * The curated suggestions for an unknown token, if any.
+ *
+ * @param token - The unresolved command token.
+ * @returns The commands that own the token's job, or `undefined`.
+ */
+export function curatedSuggestions(
+  token: string,
+): readonly string[] | undefined {
+  return CURATED_SUGGESTIONS[token];
+}
 
 /** An unresolved token and the sibling names to rank it against. */
 export interface UnknownCommand {