@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/mcp/tools/registerTools.test.ts

@@ -9,9 +9,19 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestMcpClient } from "#testing";
+import {
+  createTestMcpClient,
+  RECIPE_PREFIXES,
+  RECIPE_STORY,
+  RECIPE_TTL,
+} from "#testing";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../domains/token/featureFlag.js";
 import type { McpErrorPayload } from "../types.js";
 
+// token_list, token_lookup, and token_sample are gated behind the token
+// read-surface feature flag.
+const EXPECTED_TOOL_COUNT = TOKEN_READ_SURFACE_ENABLED ? 34 : 31;
+
 let client: Client;
 let cleanup: () => Promise<void>;
 
@@ -52,9 +62,9 @@ function parseData(result: Record<string, unknown>): unknown {
 // =============================================================================
 
 describe("tool listing", () => {
-  it("registers 29 tools", async () => {
+  it("registers the expected number of tools", async () => {
     const { tools } = await client.listTools();
-    expect(tools).toHaveLength(29);
+    expect(tools).toHaveLength(EXPECTED_TOOL_COUNT);
   });
 
   it("all tools have descriptions", async () => {
@@ -75,8 +85,10 @@ describe("tool listing", () => {
     expect(names).toContain("standard_categories");
     expect(names).toContain("modifier_list");
     expect(names).toContain("modifier_lookup");
-    expect(names).toContain("token_list");
-    expect(names).toContain("token_lookup");
+    if (TOKEN_READ_SURFACE_ENABLED) {
+      expect(names).toContain("token_list");
+      expect(names).toContain("token_lookup");
+    }
     expect(names).toContain("tier_list");
     expect(names).toContain("config_show");
     expect(names).toContain("config_tier");
@@ -97,7 +109,9 @@ describe("tool listing", () => {
     // Sample tools
     expect(names).toContain("block_sample");
     expect(names).toContain("standard_sample");
-    expect(names).toContain("token_sample");
+    if (TOKEN_READ_SURFACE_ENABLED) {
+      expect(names).toContain("token_sample");
+    }
     expect(names).toContain("modifier_sample");
   });
 
@@ -107,6 +121,67 @@ describe("tool listing", () => {
       expect(tool.name).not.toMatch(/^pragma_/);
     }
   });
+
+  // Golden surface: the full built-in tool set plus bundled packs, in
+  // registration order. The per-(noun, verb) reserved-guard flip must leave
+  // this byte-identical AND order-identical — registration order is the tool
+  // surface a client sees.
+  it("has a stable built-in tool surface", async () => {
+    const names = (await client.listTools()).tools.map((tool) => tool.name);
+
+    expect(names).toEqual([
+      "block_list",
+      "block_lookup",
+      "block_sample",
+      "modifier_list",
+      "modifier_lookup",
+      "modifier_sample",
+      ...(TOKEN_READ_SURFACE_ENABLED ? ["token_list", "token_lookup"] : []),
+      "tokens_add_config",
+      ...(TOKEN_READ_SURFACE_ENABLED ? ["token_sample"] : []),
+      "config_show",
+      "config_tier",
+      "config_channel",
+      "ontology_list",
+      "ontology_show",
+      "graph_query",
+      "graph_inspect",
+      "skill_list",
+      "skill_lookup",
+      "doctor",
+      "info",
+      "capabilities",
+      "llm",
+      "create_component",
+      "create_package",
+      "create_application",
+      "create_domain",
+      "create_route",
+      "create_wrapper",
+      // Bundled packs register after the built-in tools: `tier_list` and the
+      // whole `standard` noun are served by bundled story packs — the
+      // hand-written tier and standard domains were deleted.
+      "tier_list",
+      "standard_list",
+      "standard_lookup",
+      "standard_categories",
+      "standard_sample",
+    ]);
+  });
+
+  it("serves the standard tools from the bundled pack, not built-ins", async () => {
+    const { tools } = await client.listTools();
+    const standardList = tools.find((tool) => tool.name === "standard_list");
+    // Pack-compiled tool descriptions carry no story-pack suffix here only
+    // because the bundled pack curates them; the giveaway is the derived
+    // `search`/`category` params on the pack projection.
+    const params = Object.keys(
+      (standardList?.inputSchema as { properties?: object })?.properties ?? {},
+    );
+    expect(params).toContain("category");
+    expect(params).toContain("search");
+    expect(params).toContain("condensed");
+  });
 });
 
 // =============================================================================
@@ -414,7 +489,7 @@ describe("modifier_lookup", () => {
 // Token tools
 // =============================================================================
 
-describe("token_list", () => {
+describe.skipIf(!TOKEN_READ_SURFACE_ENABLED)("token_list", () => {
   it("returns tokens", async () => {
     const result = await client.callTool({
       name: "token_list",
@@ -425,7 +500,7 @@ describe("token_list", () => {
   });
 });
 
-describe("token_lookup", () => {
+describe.skipIf(!TOKEN_READ_SURFACE_ENABLED)("token_lookup", () => {
   it("returns token with theme values", async () => {
     const result = await client.callTool({
       name: "token_lookup",
@@ -463,10 +538,11 @@ describe("tier_list", () => {
       name: "tier_list",
       arguments: {},
     });
-    const data = parseData(result) as { path: string }[];
+    // The bundled tier pack names the field `name` (its `ds:name` value).
+    const data = parseData(result) as { name: string }[];
     expect(data.length).toBeGreaterThan(0);
-    const paths = data.map((t) => t.path);
-    expect(paths).toContain("global");
+    const names = data.map((t) => t.name);
+    expect(names).toContain("global");
   });
 });
 
@@ -508,6 +584,8 @@ describe("config_show", () => {
 describe("config_tier", () => {
   it("sets, queries, and resets tier in workspace config", async () => {
     const dir = mkdtempSync(join(tmpdir(), "pragma-mcp-tier-"));
+    // Seed a project file so global-first writes stay in this workspace.
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
 
     try {
       const scoped = await createTestMcpClient({ cwd: dir });
@@ -517,7 +595,10 @@ describe("config_tier", () => {
           name: "config_tier",
           arguments: { path: "global" },
         });
-        expect(parseData(setResult)).toEqual({ tier: "global", action: "set" });
+        expect(parseData(setResult)).toMatchObject({
+          tier: "global",
+          action: "set",
+        });
 
         const queryResult = await scoped.client.callTool({
           name: "config_tier",
@@ -532,7 +613,10 @@ describe("config_tier", () => {
           name: "config_tier",
           arguments: { reset: true },
         });
-        expect(parseData(resetResult)).toEqual({ tier: null, action: "reset" });
+        expect(parseData(resetResult)).toMatchObject({
+          tier: null,
+          action: "reset",
+        });
 
         const queriedAfterReset = await scoped.client.callTool({
           name: "config_tier",
@@ -554,6 +638,8 @@ describe("config_tier", () => {
 describe("config_channel", () => {
   it("sets, queries, and resets channel in workspace config", async () => {
     const dir = mkdtempSync(join(tmpdir(), "pragma-mcp-channel-"));
+    // Seed a project file so global-first writes stay in this workspace.
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
 
     try {
       const scoped = await createTestMcpClient({ cwd: dir });
@@ -563,7 +649,7 @@ describe("config_channel", () => {
           name: "config_channel",
           arguments: { value: "experimental" },
         });
-        expect(parseData(setResult)).toEqual({
+        expect(parseData(setResult)).toMatchObject({
           channel: "experimental",
           action: "set",
         });
@@ -581,7 +667,7 @@ describe("config_channel", () => {
           name: "config_channel",
           arguments: { reset: true },
         });
-        expect(parseData(resetResult)).toEqual({
+        expect(parseData(resetResult)).toMatchObject({
           channel: "normal",
           action: "reset",
         });
@@ -699,7 +785,7 @@ describe("create_component", () => {
     const result = await client.callTool({
       name: "create_component",
       arguments: {
-        framework: "react",
+        variant: "react",
         componentPath: "src/components/Button",
       },
     });
@@ -714,7 +800,7 @@ describe("create_component", () => {
     const result = await client.callTool({
       name: "create_component",
       arguments: {
-        framework: "svelte",
+        variant: "svelte",
         componentPath: "src/lib/components/Toggle",
       },
     });
@@ -723,11 +809,11 @@ describe("create_component", () => {
     expect((data.generator as { name: string }).name).toBe("component/svelte");
   });
 
-  it("returns error for invalid framework", async () => {
+  it("returns error for invalid variant", async () => {
     const result = await client.callTool({
       name: "create_component",
       arguments: {
-        framework: "angular",
+        variant: "angular",
         componentPath: "src/components/Button",
       },
     });
@@ -769,7 +855,7 @@ describe("llm", () => {
     expect(data.context.counts.blocks).toBeGreaterThan(0);
     expect(data.context.counts.standards).toBeGreaterThan(0);
     expect(data.context.namespaces.length).toBeGreaterThan(0);
-    expect(data.decisionTrees).toHaveLength(5);
+    expect(data.decisionTrees).toHaveLength(TOKEN_READ_SURFACE_ENABLED ? 5 : 4);
     expect(data.commandReference.length).toBeGreaterThan(0);
   });
 });
@@ -783,7 +869,9 @@ describe("error handling", () => {
     const notFoundCalls = [
       { name: "block_lookup", arguments: { names: ["X"] } },
       { name: "modifier_lookup", arguments: { names: ["X"] } },
-      { name: "token_lookup", arguments: { names: ["X"] } },
+      ...(TOKEN_READ_SURFACE_ENABLED
+        ? [{ name: "token_lookup", arguments: { names: ["X"] } }]
+        : []),
       { name: "standard_lookup", arguments: { names: ["X"] } },
     ] as const;
 
@@ -857,7 +945,7 @@ describe("ontology_show", () => {
     const envelope = parseEnvelope(result);
     expect(envelope.ok).toBe(true);
     expect(envelope.condensed).toBe(true);
-    expect(envelope.text).toEqual(expect.stringContaining("## ds:"));
+    expect(envelope.text).toEqual(expect.stringContaining("## Ontology ds:"));
   });
 });
 
@@ -964,6 +1052,48 @@ describe("graph_inspect", () => {
 // Skill tools
 // =============================================================================
 
+describe("story-pack tools", () => {
+  it("registers <noun>_list and <noun>_lookup from a stories config", async () => {
+    const scoped = await createTestMcpClient({
+      ttl: RECIPE_TTL,
+      config: {
+        tier: undefined,
+        channel: "normal",
+        stories: [RECIPE_STORY],
+        prefixes: RECIPE_PREFIXES,
+      },
+    });
+
+    try {
+      const tools = (await scoped.client.listTools()).tools.map(
+        (tool) => tool.name,
+      );
+      expect(tools).toHaveLength(EXPECTED_TOOL_COUNT + 2);
+      expect(tools).toContain("recipe_list");
+      expect(tools).toContain("recipe_lookup");
+
+      const listResult = await scoped.client.callTool({
+        name: "recipe_list",
+        arguments: {},
+      });
+      const rows = parseData(listResult) as { name: string }[];
+      expect(rows.map((row) => row.name)).toEqual(["Gazpacho", "Pancakes"]);
+
+      const lookupResult = await scoped.client.callTool({
+        name: "recipe_lookup",
+        arguments: { names: ["pancakes"] },
+      });
+      const data = parseData(lookupResult) as {
+        results: { name: string; instructions: string }[];
+      };
+      expect(data.results.at(0)?.name).toBe("Pancakes");
+      expect(data.results.at(0)?.instructions).toBe("Mix, fry, flip.");
+    } finally {
+      await scoped.cleanup();
+    }
+  });
+});
+
 describe("skill_list", () => {
   it("returns skills data", async () => {
     const result = await client.callTool({
@@ -1048,9 +1178,9 @@ describe("capabilities", () => {
     expect(toolNames).toContain("block_list");
     expect(toolNames).toContain("capabilities");
     expect(data.tools.every((t) => t.use_when.length > 0)).toBe(true);
-    expect(data.counts.total).toBe(29);
+    expect(data.counts.total).toBe(EXPECTED_TOOL_COUNT);
     expect(data.counts.read).toBeGreaterThan(0);
-    expect(data.counts.write).toBe(5);
+    expect(data.counts.write).toBe(9);
     expect(data.counts.orientation).toBe(2);
     expect(data.counts.diagnostic).toBe(2);
     expect(data.version).toBeDefined();
@@ -1131,14 +1261,17 @@ describe("condensed parameter", () => {
     expect((envelope.text as string).length).toBeGreaterThan(0);
   });
 
-  it("token_lookup returns condensed text", async () => {
-    const result = await client.callTool({
-      name: "token_lookup",
-      arguments: { names: ["color.primary"], condensed: true },
-    });
-    const envelope = parseEnvelope(result);
-    expect(envelope.ok).toBe(true);
-    expect(envelope.condensed).toBe(true);
-    expect(typeof envelope.text).toBe("string");
-  });
+  it.skipIf(!TOKEN_READ_SURFACE_ENABLED)(
+    "token_lookup returns condensed text",
+    async () => {
+      const result = await client.callTool({
+        name: "token_lookup",
+        arguments: { names: ["color.primary"], condensed: true },
+      });
+      const envelope = parseEnvelope(result);
+      expect(envelope.ok).toBe(true);
+      expect(envelope.condensed).toBe(true);
+      expect(typeof envelope.text).toBe("string");
+    },
+  );
 });

package/src/mcp/types.ts

@@ -25,6 +25,8 @@ export type ToolPayload =
       readonly meta?: {
         readonly count?: number;
         readonly filters?: Record<string, string>;
+        /** Queries that failed unexpectedly (surfaced only when > 0). */
+        readonly internalErrorCount?: number;
       };
     }
   | {
@@ -47,6 +49,8 @@ export interface ToolResponse<T = unknown> {
   readonly meta: {
     readonly count?: number;
     readonly filters?: Record<string, string>;
+    /** Queries that failed unexpectedly (surfaced only when > 0). */
+    readonly internalErrorCount?: number;
   };
 }
 

package/src/pipeline/collectCommands.test.ts

@@ -1,8 +1,16 @@
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import type { PragmaContext } from "../domains/shared/context.js";
 import type { PragmaRuntime } from "../domains/shared/runtime.js";
+import {
+  deriveReservedVerbs,
+  isReserved,
+  nounVerbFromPath,
+  nounVerbFromToolName,
+} from "../domains/shared/stories/pack/index.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../domains/token/featureFlag.js";
+import { allSpecs } from "../mcp/tools/index.js";
 import createTestRuntime from "../testing/helpers/createTestRuntime.js";
-import collectCommands from "./collectCommands.js";
+import collectCommands, { builtInCommands } from "./collectCommands.js";
 
 let runtime: PragmaRuntime;
 
@@ -34,4 +42,146 @@ describe("collectCommands", () => {
     expect(paths).toContain("graph query");
     expect(paths).toContain("graph inspect");
   });
+
+  // Golden surface: the full built-in command set, in emission order. The
+  // per-(noun, verb) reserved-guard flip must not add, drop, rename, or REORDER
+  // a single built-in command — order drives help output and registration.
+  // `tier list` and the whole `standard` noun are no longer here: the
+  // hand-written domains were deleted and are served by bundled story packs
+  // (asserted below).
+  it("has a stable built-in command surface", () => {
+    const paths = builtInCommands(makeCtx()).map((command) =>
+      command.path.join(" "),
+    );
+
+    expect(paths).toEqual([
+      "config tier",
+      "config channel",
+      "config trace",
+      "config framework",
+      "config show",
+      "create component",
+      "create package",
+      "create application",
+      "create domain",
+      "create route",
+      "create wrapper",
+      "setup",
+      "setup lsp",
+      "setup mcp",
+      "setup completions",
+      "setup skills",
+      "modifier list",
+      "modifier lookup",
+      "modifier sample",
+      ...(TOKEN_READ_SURFACE_ENABLED ? ["token list", "token lookup"] : []),
+      "tokens add-config",
+      ...(TOKEN_READ_SURFACE_ENABLED ? ["token sample"] : []),
+      "block list",
+      "block lookup",
+      "block sample",
+      "ontology list",
+      "ontology show",
+      "graph query",
+      "graph inspect",
+      "graphql build",
+      "graphql check",
+      "graphql serve",
+      "skill list",
+      "skill lookup",
+      "doctor",
+      "info",
+      "upgrade",
+      "llm",
+      "capabilities",
+    ]);
+  });
+
+  it("serves `tier list` from the bundled pack, not a built-in", () => {
+    const builtInPaths = builtInCommands(makeCtx()).map((c) =>
+      c.path.join(" "),
+    );
+    const allPaths = collectCommands(makeCtx()).map((c) => c.path.join(" "));
+
+    expect(builtInPaths).not.toContain("tier list");
+    expect(allPaths).toContain("tier list");
+  });
+
+  it("serves the whole `standard` noun from the bundled pack", () => {
+    const builtInPaths = builtInCommands(makeCtx()).map((c) =>
+      c.path.join(" "),
+    );
+    const allPaths = collectCommands(makeCtx()).map((c) => c.path.join(" "));
+
+    const standardVerbs = [
+      "standard list",
+      "standard lookup",
+      "standard categories",
+      "standard sample",
+    ];
+    for (const path of standardVerbs) {
+      expect(builtInPaths).not.toContain(path);
+      expect(allPaths).toContain(path);
+    }
+  });
+});
+
+// Cross-surface skew invariant (FIX 2 / R4-F1): the CLI and MCP surfaces both
+// derive their reserved map through the single shared deriveReservedVerbs, so
+// they MUST agree on every leaf read (noun, verb) reservation. If they drifted,
+// a pack migrating a `list`/`lookup` verb could be admitted on one surface and
+// blocked on the other. Operational nouns legitimately differ (graphql/setup/
+// upgrade are CLI-only), so the invariant is scoped to the read verbs that
+// packs actually emit.
+describe("cross-surface reserved-verb parity", () => {
+  const READ_VERBS = ["list", "lookup"] as const;
+
+  it("CLI and MCP reserve the same list/lookup verbs for every leaf read noun", () => {
+    // Both surfaces derive reservations from BUILT-INS only (production reserves
+    // from built-ins, before appending packs), so a bundled/config/package pack
+    // never inflates the reserved map. Using collectCommands here would fold the
+    // bundled tier pack into the CLI side and break the symmetry.
+    const cliPairs = builtInCommands(makeCtx()).map((command) =>
+      nounVerbFromPath(command.path),
+    );
+    const mcpPairs = allSpecs.map((spec) => nounVerbFromToolName(spec.name));
+
+    const cliReserved = deriveReservedVerbs(cliPairs);
+    const mcpReserved = deriveReservedVerbs(mcpPairs);
+
+    // FIX 1 on the real CLI surface: operational nouns own no list/lookup, so
+    // they are reserved wholesale — a pack emitting `list` stays blocked.
+    for (const noun of ["config", "graph", "graphql", "setup", "create"]) {
+      expect(isReserved(cliReserved, noun, "list")).toBe(true);
+    }
+
+    // Leaf read nouns: those that own a `list`/`lookup` verb on either surface.
+    const readNouns = new Set(
+      [...cliPairs, ...mcpPairs]
+        .filter(([, verb]) => verb === "list" || verb === "lookup")
+        .map(([noun]) => noun),
+    );
+
+    // Sanity: the real leaf-migration targets are present, so this asserts
+    // something (a silently empty set would make the test vacuous). `tier`
+    // and `standard` are no longer here — both were cut over to bundled
+    // packs, so they are correctly absent from the built-in reserved
+    // surface on both sides. The token noun only owns read verbs while its
+    // feature flag is on.
+    const expectedReadNouns = ["block", "modifier"];
+    if (TOKEN_READ_SURFACE_ENABLED) expectedReadNouns.push("token");
+    for (const noun of expectedReadNouns) {
+      expect(readNouns.has(noun)).toBe(true);
+    }
+    expect(readNouns.has("standard")).toBe(false);
+
+    for (const noun of readNouns) {
+      for (const verb of READ_VERBS) {
+        expect(
+          isReserved(cliReserved, noun, verb),
+          `CLI/MCP disagree on ${noun} ${verb}`,
+        ).toBe(isReserved(mcpReserved, noun, verb));
+      }
+    }
+  });
 });

package/src/pipeline/collectCommands.ts

@@ -14,30 +14,27 @@ import { commands as modifierCommands } from "../domains/modifier/index.js";
 import { commands as ontologyCommands } from "../domains/ontology/index.js";
 import { commands as setupCommands } from "../domains/setup/index.js";
 import type { PragmaContext } from "../domains/shared/context.js";
+import {
+  compilePackCommands,
+  deriveReservedVerbs,
+  nounVerbFromPath,
+} from "../domains/shared/stories/pack/index.js";
 import { commands as skillCommands } from "../domains/skill/index.js";
-import { commands as standardCommands } from "../domains/standard/index.js";
-import { commands as tierCommands } from "../domains/tier/index.js";
 import { commands as tokenCommands } from "../domains/token/index.js";
 
 /**
- * Collect all CLI command definitions from domain modules.
- *
- * Extracted from runCli so the completions server can import
- * the command list independently without running the full CLI pipeline.
+ * The built-in (hand-written domain) command surface, in emission order.
  *
- * @param ctx - The pragma context providing store, config, and global flags.
- * @returns The full array of command definitions for all domains.
+ * Excludes story-pack commands (bundled, config, or package). Exported so the
+ * reserved-verb derivation and its tests share the exact input production uses
+ * — the reserved map is built from built-ins only, never from packs.
  */
-export default function collectCommands(
-  ctx: PragmaContext,
-): CommandDefinition[] {
+export function builtInCommands(ctx: PragmaContext): CommandDefinition[] {
   return [
     ...configCommands(ctx),
     ...createCommands(),
     ...setupCommands(),
-    ...standardCommands(ctx),
     ...modifierCommands(ctx),
-    ...tierCommands(ctx),
     ...tokenCommands(ctx),
     ...blockCommands(ctx),
     ...ontologyCommands(ctx),
@@ -51,3 +48,28 @@ export default function collectCommands(
     buildCapabilitiesCommand(),
   ];
 }
+
+/**
+ * Collect all CLI command definitions: built-in domains plus story packs.
+ *
+ * Extracted from runCli so the completions server can import the command list
+ * independently without running the full CLI pipeline.
+ *
+ * Story packs (bundled transitional packs, plus config- and package-declared
+ * stories) project onto the same surface. Leaf read nouns reserve only the
+ * (noun, verb) pairs they own, so a pack can add a verb no built-in owns and,
+ * once a built-in leaf is deleted, its bundled pack takes over the freed noun;
+ * operational nouns (config, graph, setup, …) stay reserved wholesale.
+ *
+ * @param ctx - The pragma context providing store, config, and global flags.
+ * @returns The full array of command definitions for all domains.
+ */
+export default function collectCommands(
+  ctx: PragmaContext,
+): CommandDefinition[] {
+  const builtIn = builtInCommands(ctx);
+  const reserved = deriveReservedVerbs(
+    builtIn.map((command) => nounVerbFromPath(command.path)),
+  );
+  return [...builtIn, ...compilePackCommands(ctx, reserved)];
+}

package/src/pipeline/createProgram.test.ts

@@ -36,9 +36,13 @@ describe("createProgram", () => {
       }
     )._events.beforeAllHelp({ command: program, write });
 
+    // Assert on single-chalk-span strings so the check is robust whether or
+    // not color is enabled (CI renders with color; ANSI resets would otherwise
+    // split a multi-word phrase like "Usage: pragma").
     expect(write).toHaveBeenCalledWith(
-      expect.stringContaining("Usage: pragma <command> [options]"),
+      expect.stringContaining("For AI agents"),
     );
+    expect(write).toHaveBeenCalledWith(expect.stringContaining("Global flags"));
   });
 
   it("uses llm root help when llm is enabled", async () => {

package/src/pipeline/createProgram.ts

@@ -1,7 +1,6 @@
 import {
   type CommandDefinition,
   detectRenderMode,
-  formatHelp,
   formatLlmHelp,
   type HandleResultOptions,
   registerAll,
@@ -9,6 +8,7 @@ import {
 import { Command } from "commander";
 import { PROGRAM_DESCRIPTION, PROGRAM_NAME, VERSION } from "../constants.js";
 import type { PragmaContext } from "../domains/shared/context.js";
+import formatRootHelp from "./rootHelp.js";
 
 /**
  * Build and configure the top-level Commander program.
@@ -57,7 +57,7 @@ export default function createProgram(
     if (ctx.globalFlags.llm) {
       return formatLlmHelp(PROGRAM_NAME, commands);
     }
-    return formatHelp(PROGRAM_NAME, PROGRAM_DESCRIPTION, commands);
+    return formatRootHelp(PROGRAM_NAME, PROGRAM_DESCRIPTION, commands);
   });
 
   program.helpOption("-h, --help", "Show help");