@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -1,18 +1,62 @@
 /**
  * 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 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 +69,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="));
 }
 
 /**
@@ -108,11 +191,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 +212,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 +221,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

@@ -17,7 +17,7 @@ const INDENT = "  ";
 /** Two-space gap between a term column and its description. */
 const GAP = "  ";
 
-/** A bold section header (`Flags`, `Verbs`, `Explore the design system`). */
+/** A bold section header (`Flags`, `Verbs`, `Set up & maintain`). */
 export function helpHeading(text: string): string {
   return chalk.bold(text);
 }
@@ -32,6 +32,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

@@ -1,19 +1,22 @@
 /**
- * Curated root `--help` for `pragma`.
+ * The curated root `--help` page.
  *
- * The front door is hand-curated, not auto-generated: nouns are grouped into
- * task-oriented sections with real one-line summaries, and each section is
- * reconciled against the *live* nouns (from the registered verbs) so a noun
- * that is not built yet is dropped and an uncatalogued one still surfaces under
- * "Other" rather than vanishing. Ported from the v1 root help, retargeted at
- * the grammar and the v2 noun set (no `llm`/`graphql`/`trace`/`tokens`).
+ * The kernel curates the nouns it ships — and only those. It names no domain:
+ * the nouns it does NOT curate lead the page untitled (the header one line up
+ * already carries the distribution's blurb) and describe themselves through
+ * their own verbs, so the front door follows the content instead of naming it.
+ * Every section is reconciled against the *live* nouns (from the registered
+ * verbs), so a noun that is not built yet is dropped and one the kernel has
+ * never heard of still surfaces.
  */
 
-import type { VerbSpec } from "../../spec/types.js";
+import { PROGRAM_LOGO } from "../../../constants.js";
+import type { VerbSpec } from "../../spec/index.js";
 import {
   helpColumns,
   helpDim,
   helpHeading,
+  helpLogo,
   helpTerm,
   helpUsage,
 } from "./helpFormat.js";
@@ -24,88 +27,89 @@ interface NounSummary {
 }
 
 interface HelpGroup {
-  readonly title: string;
+  /**
+   * Absent for the leading uncurated group: its rows sit directly under the
+   * usage line, since repeating the header's blurb as a heading three lines
+   * below it says the same thing twice.
+   */
+  readonly title?: string;
   readonly nouns: readonly NounSummary[];
 }
 
 /**
- * Task-oriented grouping with curated summaries. Order is intentional: what
- * people reach for most (exploring, generating) comes first; agent tooling
- * comes last.
+ * The kernel's own nouns, grouped by task with curated summaries. Order is
+ * intentional: what people reach for most comes first; agent tooling comes last.
+ *
+ * @param programName - The CLI binary name (the distribution's `name`).
+ * @returns The task-oriented groups, in display order.
  */
-const HELP_GROUPS: readonly HelpGroup[] = [
-  {
-    title: "Explore the design system",
-    nouns: [
-      {
-        noun: "block",
-        summary: "Inspect components & patterns and their anatomy",
-      },
-      { noun: "token", summary: "Look up design tokens and their values" },
-      { noun: "modifier", summary: "Inspect modifiers and modifier families" },
-      { noun: "standard", summary: "Browse code standards and categories" },
-      {
-        noun: "ontology",
-        summary: "Explore the loaded ontologies (classes, properties)",
-      },
-      { noun: "tier", summary: "List the design-system tiers" },
-    ],
-  },
-  {
-    title: "Generate code",
-    nouns: [
-      { noun: "create", summary: "Scaffold components, packages, and apps" },
-    ],
-  },
-  {
-    title: "Query & serve the graph",
-    nouns: [
-      {
-        noun: "graph",
-        summary: "Run SPARQL queries or inspect a URI directly",
-      },
-    ],
-  },
-  {
-    title: "Set up & maintain",
-    nouns: [
-      { noun: "doctor", summary: "Check environment health" },
-      {
-        noun: "setup",
-        summary: "Configure MCP, skills, completions, and the LSP",
-      },
-      {
-        noun: "sources",
-        summary: "Build and refresh the local store from packages",
-      },
-      { noun: "config", summary: "Read and write pragma configuration" },
-      { noun: "info", summary: "Show version, config, and update status" },
-      {
-        noun: "upgrade",
-        summary: "Upgrade the pragma CLI to the latest version",
-      },
-    ],
-  },
-  {
-    title: "For AI agents",
-    nouns: [
-      {
-        noun: "capabilities",
-        summary: "Discover conventions, tools, and the discovery sequence",
-      },
-      {
-        noun: "colophon",
-        summary: "Read how pragma and the active domain are made",
-      },
-      {
-        noun: "skill",
-        summary: "Browse agent skills from design-system packages",
-      },
-      { noun: "prompt", summary: "Browse reusable prompt templates" },
-      { noun: "mcp", summary: "Start the MCP server over stdio" },
-    ],
-  },
-];
+function buildKernelGroups(programName: string): readonly HelpGroup[] {
+  return [
+    {
+      title: "Generate code",
+      nouns: [
+        { noun: "create", summary: "Scaffold components, packages, and apps" },
+      ],
+    },
+    {
+      title: "Query & serve the graph",
+      nouns: [
+        {
+          noun: "graph",
+          summary: "Run SPARQL queries or inspect a URI directly",
+        },
+        {
+          noun: "ontology",
+          summary: "Explore the loaded ontologies (classes, properties)",
+        },
+      ],
+    },
+    {
+      title: "Set up & maintain",
+      nouns: [
+        { noun: "doctor", summary: "Check environment health" },
+        {
+          noun: "setup",
+          summary: "Configure MCP, skills, completions, and the LSP",
+        },
+        {
+          noun: "sources",
+          summary: "Build and refresh the local store from packs",
+        },
+        {
+          noun: "config",
+          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`,
+        },
+      ],
+    },
+    {
+      title: "For AI agents",
+      nouns: [
+        {
+          noun: "capabilities",
+          summary: "Discover conventions, tools, and the discovery sequence",
+        },
+        // 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" },
+        // 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" },
+      ],
+    },
+  ];
+}
 
 /** All distinct, non-hidden top-level nouns present in the registered verbs. */
 function nounsFrom(verbs: readonly VerbSpec[]): Set<string> {
@@ -117,50 +121,56 @@ function nounsFrom(verbs: readonly VerbSpec[]): Set<string> {
   return nouns;
 }
 
-/** The summary to show for an uncatalogued but live noun. */
-function fallbackSummary(noun: string, verbs: readonly VerbSpec[]): string {
+/**
+ * Summarise an uncurated noun from its first live verb — which is the pack's own
+ * `description` whenever the pack ships a `list` (`compilePack` compiles that
+ * verb first). The terminal period a pack sentence carries is dropped so the
+ * column reads as one voice with the kernel's own fragments.
+ */
+function summarizeNoun(noun: string, verbs: readonly VerbSpec[]): string {
   const first = verbs.find((v) => v.path[0] === noun && !v.hidden);
-  return first?.summary ?? `${noun} commands`;
+  return (first?.summary ?? `${noun} commands`).replace(/\.$/, "");
 }
 
 /**
  * Build the curated root help string.
  *
- * @param programName - The CLI binary name (`pragma`).
+ * @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.
  * @returns The formatted, colorized help text.
  */
 export function formatRootHelp(
   programName: string,
   description: string,
   verbs: readonly VerbSpec[],
+  version: string,
+  issuesUrl: string,
 ): 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 catalogued = new Set(
-    HELP_GROUPS.flatMap((g) => g.nouns.map((n) => n.noun)),
-  );
+  const kernel = buildKernelGroups(programName);
+  const curated = new Set(kernel.flatMap((g) => g.nouns.map((n) => n.noun)));
 
-  const uncatalogued = [...present].filter((n) => !catalogued.has(n)).sort();
   const groups: HelpGroup[] = [
-    ...HELP_GROUPS.map((g) => ({
+    // Everything the kernel's curated table does not claim — in the shipped
+    // binary the bundled domain packs, in a fork whatever it ships. Untitled
+    // and first, so the domain leads the page without the kernel naming it.
+    {
+      nouns: [...present]
+        .filter((n) => !curated.has(n))
+        .sort()
+        .map((noun) => ({ noun, summary: summarizeNoun(noun, verbs) })),
+    },
+    ...kernel.map((g) => ({
       ...g,
       nouns: g.nouns.filter((n) => present.has(n.noun)),
     })),
-    ...(uncatalogued.length > 0
-      ? [
-          {
-            title: "Other",
-            nouns: uncatalogued.map((noun) => ({
-              noun,
-              summary: fallbackSummary(noun, verbs),
-            })),
-          },
-        ]
-      : []),
   ].filter((g) => g.nouns.length > 0);
 
   // One column width across ALL groups so the noun column aligns section to
@@ -171,7 +181,24 @@ export function formatRootHelp(
   );
 
   const lines: string[] = [
-    `${helpHeading(programName)} — ${description}`,
+    // The wordmark leads when the distribution declares one. A fork ships its
+    // own art or none, so its front door is never branded with someone else's.
+    ...(PROGRAM_LOGO.length > 0 ? [...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]")}`,
@@ -180,7 +207,7 @@ export function formatRootHelp(
   ];
 
   for (const group of groups) {
-    lines.push(helpHeading(group.title));
+    if (group.title) lines.push(helpHeading(group.title));
     lines.push(
       ...helpColumns(
         group.nouns.map((n) => [n.noun, n.summary] as const),
@@ -203,7 +230,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 {