argsbarg 1.4.3 → 2.0.0

package/src/parse.ts

@@ -9,10 +9,13 @@ across every entry path.
 
 import { CliContext } from "./context.ts";
 import {
-  CliCommand,
+  type CliLeaf,
+  CliNode,
   CliFallbackMode,
   CliOption,
   CliOptionKind,
+  isCliLeaf,
+  isCliRouter,
 } from "./types.ts";
 import { fullStringIsDouble } from "./utils.ts";
 
@@ -69,7 +72,7 @@ function isSchemaTok(tok: string): boolean {
 }
 
 /** Looks up a subcommand or routing node by `key`. */
-function findChild(cmds: CliCommand[], name: string): CliCommand | undefined {
+function findChild(cmds: CliNode[], name: string): CliNode | undefined {
   return cmds.find((c) => c.key === name);
 }
 
@@ -217,15 +220,16 @@ function consumeOptions(
 // ── Positional Collection ─────────────────────────────────────────────────────
 
 /** Merges option defs from the program root along the routed command path. */
-export function collectOptionDefs(root: CliCommand, path: string[]): CliOption[] {
+export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
   let defs = [...(root.options ?? [])];
-  let cmds = root.commands ?? [];
+  let node: CliNode = root;
 
   for (const seg of path) {
-    const ch = findChild(cmds, seg);
+    if (!isCliRouter(node)) break;
+    const ch = findChild(node.commands, seg);
     if (!ch) break;
     defs.push(...(ch.options ?? []));
-    cmds = ch.commands ?? [];
+    node = ch;
   }
 
   return defs;
@@ -233,7 +237,7 @@ export function collectOptionDefs(root: CliCommand, path: string[]): CliOption[]
 
 /** Fills `args` for a leaf from `startIdx` according to `node.positionals`. */
 function finishLeaf(
-  node: CliCommand,
+  node: CliLeaf,
   startIdx: number,
   argv: string[],
   path: string[],
@@ -384,14 +388,16 @@ function schemaResult(): ParseResult {
 /**
  * Parses `argv` against the program root, routing into subcommands and filling `opts` / `args`.
  */
-export function parse(root: CliCommand, argv: string[]): ParseResult {
+export function parse(root: CliNode, argv: string[]): ParseResult {
   let i = 0;
   const path: string[] = [];
   const opts: Record<string, string> = {};
 
   const rootLenient =
+    isCliRouter(root) &&
     root.fallbackCommand !== undefined &&
-    ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown || (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
+    ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown ||
+      (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
 
   // Consume root-level options first
   const rootRep = consumeOptions(root.options ?? [], rootLenient, argv, i, opts);
@@ -420,16 +426,20 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 
   // Determine which subcommand to route to
   let cmdName: string;
-  let node: CliCommand | undefined;
+  let node: CliNode | undefined;
 
-  if (root.handler) {
-    return finishLeaf(root as CliCommand, i, argv, path, opts, root.options ?? [], forcePositionals);
+  if (isCliLeaf(root)) {
+    return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals);
   }
 
   if (i >= argv.length) {
-    if (root.fallbackCommand !== undefined && ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOnly || (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown)) {
+    if (
+      root.fallbackCommand !== undefined &&
+      ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOnly ||
+        (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown)
+    ) {
       cmdName = root.fallbackCommand;
-      node = findChild(root.commands ?? [], cmdName);
+      node = findChild(root.commands, cmdName);
       if (!node) {
         return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
       }
@@ -438,7 +448,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
   } else {
     const peek = argv[i];
-    const childPick = !forcePositionals ? findChild(root.commands ?? [], peek) : undefined;
+    const childPick = !forcePositionals ? findChild(root.commands, peek) : undefined;
 
     if (childPick !== undefined) {
       cmdName = peek;
@@ -452,14 +462,14 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 
       if (canRouteUnknown) {
         cmdName = root.fallbackCommand!;
-        node = findChild(root.commands ?? [], cmdName);
+        node = findChild(root.commands, cmdName);
         if (!node) {
           return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
         }
       } else {
         cmdName = peek;
         if (!forcePositionals) i += 1;
-        node = findChild(root.commands ?? [], cmdName);
+        node = findChild(root.commands, cmdName);
         if (!node) {
           return {
             kind: ParseKind.Error,
@@ -506,14 +516,14 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
 
     if (i >= argv.length) {
-      if ((current.commands ?? []).length > 0) {
+      if (isCliRouter(current) && current.commands.length > 0) {
         const fb = current.fallbackCommand;
         const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
         if (
           fb !== undefined &&
           (fm === CliFallbackMode.MissingOnly || fm === CliFallbackMode.MissingOrUnknown)
         ) {
-          const fbNode = findChild(current.commands ?? [], fb);
+          const fbNode = findChild(current.commands, fb);
           if (fbNode) {
             path.push(fb);
             current = fbNode;
@@ -522,6 +532,9 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
         }
         return helpResult(path, false);
       }
+      if (!isCliLeaf(current)) {
+        return helpResult(path, false);
+      }
       return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
     }
 
@@ -539,8 +552,8 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       };
     }
 
-    if (!forcePositionals) {
-      const childOpt = findChild(current.commands ?? [], tok);
+    if (!forcePositionals && isCliRouter(current)) {
+      const childOpt = findChild(current.commands, tok);
       if (childOpt !== undefined) {
         i += 1;
         path.push(tok);
@@ -549,7 +562,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       }
     }
 
-    if ((current.commands ?? []).length > 0) {
+    if (isCliRouter(current) && current.commands.length > 0) {
       const fb = current.fallbackCommand;
       const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
       const canRouteUnknown =
@@ -557,7 +570,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
         (fm === CliFallbackMode.MissingOrUnknown || fm === CliFallbackMode.UnknownOnly);
 
       if (canRouteUnknown) {
-        const fbNode = findChild(current.commands ?? [], fb!);
+        const fbNode = findChild(current.commands, fb!);
         if (fbNode) {
           path.push(fb!);
           current = fbNode;
@@ -577,6 +590,9 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       };
     }
 
+    if (!isCliLeaf(current)) {
+      return helpResult(path, false);
+    }
     return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
   }
 }
@@ -586,14 +602,26 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 /**
  * Validates option keys and numeric values for an Ok parse, merging in-scope options along `pr.path`.
  */
-export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResult {
+export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
   if (pr.kind !== ParseKind.Ok) return pr;
 
   let defs = [...(root.options ?? [])];
-  let cmds = root.commands ?? [];
+  let node: CliNode = root;
 
   for (const seg of pr.path) {
-    const ch = findChild(cmds, seg);
+    if (!isCliRouter(node)) {
+      return {
+        kind: ParseKind.Error,
+        path: pr.path,
+        opts: {},
+        args: [],
+        helpExplicit: false,
+        helpPath: [],
+        errorMsg: "Internal path error",
+        errorHelpPath: pr.path,
+      };
+    }
+    const ch = findChild(node.commands, seg);
     if (!ch) {
       return {
         kind: ParseKind.Error,
@@ -607,7 +635,7 @@ export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResul
       };
     }
     defs.push(...(ch.options ?? []));
-    cmds = ch.commands ?? [];
+    node = ch;
   }
 
   for (const d of defs) {

package/src/runtime.ts

@@ -1,41 +1,26 @@
 /*
 This module runs parsed commands, help, errors, completion, and leaf handlers.
-It owns the top-level control flow after parsing, including validation failures,
-shell completion dispatch, and leaf handler invocation.
-
-It keeps execution flow out of the public barrel so the exported API stays small and
-the runtime responsibilities remain easy to reason about.
 */
 
-import { cliBuiltinAiGroup, cliBuiltinCompletionGroup, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
+import { resolveCapabilities } from "./capabilities.ts";
+import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
+import { cliPresentationRoot } from "./builtins/presentation.ts";
+import type { CliRouter } from "./types.ts";
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
+import { isCompiledExecutable } from "./install/compiled.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
-import { cliSkillInstall } from "./skill/install.ts";
-import { cliMcpServeStdio } from "./mcp.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
-import { CliCommand } from "./types.ts";
-import { cliValidateRoot } from "./validate.ts";
-
-/**
- * Merges the caller's program root with the reserved `completion` subtree.
- */
-function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
-  if (root.handler) {
-    return root;
-  }
-  return cliPresentationRoot(root);
+import { cliValidateProgram } from "./validate.ts";
+
+function cliRootMergedWithBuiltins(program: CliProgram): CliRouter {
+  return cliPresentationRoot(program);
 }
 
-/**
- * Validates the schema, parses argv, prints help or errors, runs completion or the leaf handler, then exits.
- *
- * @param root The root CliCommand.
- * @param argv Override the default argv (process.argv.slice(2)).
- */
-export async function cliRun(root: CliCommand, argv: string[] = process.argv.slice(2)): Promise<never> {
+export async function cliRun(program: CliProgram, argv: string[] = process.argv.slice(2)): Promise<never> {
   try {
-    cliValidateRoot(root);
+    cliValidateProgram(program);
   } catch (err) {
     if (err instanceof Error) {
       process.stderr.write(err.message + "\n");
@@ -45,41 +30,47 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  if (argv.length >= 2 && argv[0] === "ai" && argv[1] === "mcp" && !root.mcpServer) {
+  const caps = resolveCapabilities(program);
+
+  if (argv.length >= 1 && argv[0] === "mcp" && !caps.mcp) {
     process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
     process.exit(1);
   }
 
-  let parseRoot = root;
+  if (argv.length >= 1 && argv[0] === "install" && !isCompiledExecutable()) {
+    process.stderr.write("install is only available in compiled binaries (bun build --compile).\n");
+    process.exit(1);
+  }
+
+  let parseRoot: CliNode;
+  let completionParseRoot: CliRouter = cliRootMergedWithBuiltins(program);
   let isLeafCompletionIntercept = false;
 
-  if (root.handler && argv.length >= 1 && argv[0] === "ai") {
-    parseRoot = {
-      key: root.key,
-      description: root.description,
-      commands: [cliBuiltinAiGroup(root)],
-    } as CliCommand;
-  } else if (root.handler && argv.length >= 1 && argv[0] === "completion") {
-    isLeafCompletionIntercept = true;
-    parseRoot = {
-      key: root.key,
-      description: root.description,
-      commands: [cliBuiltinCompletionGroup(root.key)],
-    } as any;
+  if (isCliLeaf(program)) {
+    const intercept = builtinInterceptRoot(program, argv);
+    if (intercept.isLeafCompletionIntercept || intercept.parseRoot !== program) {
+      parseRoot = intercept.parseRoot;
+      completionParseRoot = isCliRouter(intercept.parseRoot)
+        ? intercept.parseRoot
+        : cliRootMergedWithBuiltins(program);
+      isLeafCompletionIntercept = intercept.isLeafCompletionIntercept;
+    } else {
+      parseRoot = program;
+    }
   } else {
-    parseRoot = cliRootMergedWithBuiltins(root);
+    parseRoot = cliRootMergedWithBuiltins(program);
   }
 
   let pr = parse(parseRoot, argv);
   pr = postParseValidate(parseRoot, pr);
 
   if (pr.kind === ParseKind.Help) {
-    process.stdout.write(cliHelpRender(cliPresentationRoot(root), pr.helpPath, false));
+    process.stdout.write(cliHelpRender(cliPresentationRoot(program), pr.helpPath, false));
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 
   if (pr.kind === ParseKind.Schema) {
-    process.stdout.write(cliSchemaJson(root));
+    process.stdout.write(cliSchemaJson(program));
     process.exit(0);
   }
 
@@ -87,62 +78,21 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;
     process.stderr.write(msg + "\n");
-    process.stderr.write(cliHelpRender(cliPresentationRoot(root), pr.errorHelpPath, true));
+    process.stderr.write(cliHelpRender(cliPresentationRoot(program), pr.errorHelpPath, true));
     process.exit(1);
   }
 
-  // Leaf roots have an empty path; that's normal.
-
-  if (pr.path[0] === "completion") {
-    // If we intercepted a leaf, we MUST pass the original `root` to generate completions
-    // because `parseRoot` is just a dummy router!
-    const schemaForCompletion = isLeafCompletionIntercept ? root : parseRoot;
-
-    if (pr.path[1] === "bash") {
-      process.stdout.write(completionBashScript(schemaForCompletion));
-      process.exit(0);
-    }
-    if (pr.path[1] === "zsh") {
-      process.stdout.write(completionZshScript(schemaForCompletion));
-      process.exit(0);
-    }
+  if (pr.kind === ParseKind.Ok) {
+    await dispatchBuiltin(program, pr, { isLeafCompletionIntercept, parseRoot: completionParseRoot });
   }
 
-  if (pr.path[0] === "ai") {
-    if (pr.path[1] === "mcp") {
-      if (!root.mcpServer) {
-        process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
-        process.exit(1);
-      }
-      if (pr.path.length !== 2) {
-        process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
-        process.exit(1);
-      }
-      await cliMcpServeStdio(root);
-    } else if (pr.path[1] === "skill" && (pr.path[2] === "cursor" || pr.path[2] === "claude")) {
-      if (root.aiSkill?.enabled === false) {
-        process.stderr.write("AI skills are disabled. Remove aiSkill.enabled: false from the program root.\n");
-        process.exit(1);
-      }
-      if (pr.path.length !== 3) {
-        process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
-        process.exit(1);
-      }
-      const msg = cliSkillInstall(root, pr.path[2], {
-        global: pr.opts.global === "1",
-        force: pr.opts.force === "1",
-      });
-      process.stderr.write(msg + "\n");
-      process.exit(0);
-    } else {
-      process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
+  let current: CliNode = parseRoot;
+  for (const seg of pr.path) {
+    if (!isCliRouter(current)) {
+      process.stderr.write("Internal error: missing handler for path.\n");
       process.exit(1);
     }
-  }
-
-  let current = parseRoot;
-  for (const seg of pr.path) {
-    const ch = (current.commands ?? []).find((candidate: CliCommand) => candidate.key === seg);
+    const ch = current.commands.find((candidate) => candidate.key === seg);
     if (!ch) {
       process.stderr.write("Internal error: missing handler for path.\n");
       process.exit(1);
@@ -150,12 +100,12 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     current = ch;
   }
 
-  if (!current.handler) {
+  if (!isCliLeaf(current) || !current.handler) {
     process.stderr.write("Internal error: missing handler for path.\n");
     process.exit(1);
   }
 
-  const ctx = new CliContext(parseRoot.key, pr.path, pr.args, pr.opts, parseRoot, "cli");
+  const ctx = new CliContext(program.key, pr.path, pr.args, pr.opts, program, "cli");
   try {
     await Promise.resolve(current.handler(ctx));
     process.exit(0);
@@ -167,13 +117,10 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
   }
 }
 
-/**
- * Prints a red error line and contextual help on stderr, then exits with status 1.
- */
 export function cliErrWithHelp(ctx: CliContext, msg: string): never {
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
   process.stderr.write(line + "\n");
   process.stderr.write(cliHelpRender(cliPresentationRoot(ctx.schema), ctx.commandPath, true));
   process.exit(1);
-}
+}

package/src/schema.ts

@@ -1,56 +1,13 @@
 /*
 This module serializes the CLI schema tree to JSON for machine-readable introspection.
-It strips handlers and runtime-only nodes so agents can discover commands, options,
-and positionals in one shot.
-
-It keeps schema export aligned with the declarative CliCommand model that drives help
-and completion.
 */
 
-import {
-  CliCommand,
-  CliFallbackMode,
-  CliOption,
-  CliPositional,
-} from "./types.ts";
-import { cliBuiltinCompletionGroup } from "./completion.ts";
-
-/** JSON-safe command node (no handlers). */
-export interface CliSchemaExport {
-  /** Program or command key. */
-  key: string;
-  /** Short description shown in help. */
-  description: string;
-  /** Additional notes shown in help (supports {app} placeholder). */
-  notes?: string;
-  /** Global or command-level flags/options. */
-  options?: CliOption[];
-  /** Default top-level subcommand (program root only). */
-  fallbackCommand?: string;
-  /** How fallbackCommand is applied (program root only). */
-  fallbackMode?: CliFallbackMode;
-  /** Nested subcommands (routing nodes only). */
-  commands?: CliSchemaExport[];
-  /** Positional argument definitions (leaf nodes only). */
-  positionals?: CliPositional[];
-}
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
+import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
 
-/** JSON-safe export of the reserved `completion` subtree (no handler recursion). */
-function exportBuiltinCompletionGroup(appName: string): CliSchemaExport {
-  const group = cliBuiltinCompletionGroup(appName);
-  return {
-    key: group.key,
-    description: group.description,
-    commands: (group.commands ?? []).map((ch) => ({
-      key: ch.key,
-      description: ch.description,
-      ...((ch.notes ?? "").length > 0 ? { notes: ch.notes } : {}),
-    })),
-  };
-}
+const RESERVED = new Set(["completion", "install", "mcp"]);
 
-/** Converts one `CliCommand` node into a JSON-safe export (handlers omitted). */
-function exportCommand(cmd: CliCommand): CliSchemaExport {
+function exportCommand(cmd: CliNode): CliSchemaExport {
   const out: CliSchemaExport = {
     key: cmd.key,
     description: cmd.description,
@@ -64,11 +21,11 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
     out.options = cmd.options;
   }
 
-  if ("handler" in cmd && cmd.handler) {
+  if (isCliLeaf(cmd)) {
     if ((cmd.positionals ?? []).length > 0) {
       out.positionals = cmd.positionals;
     }
-    out.commands = [exportBuiltinCompletionGroup(cmd.key)];
+    out.commands = exportPresentationBuiltins(cmd as CliProgram);
     return out;
   }
 
@@ -79,7 +36,7 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
     out.fallbackMode = cmd.fallbackMode;
   }
 
-  const children = (cmd.commands ?? []).filter((ch) => ch.key !== "completion");
+  const children = isCliRouter(cmd) ? cmd.commands.filter((ch) => !RESERVED.has(ch.key)) : [];
   if (children.length > 0) {
     out.commands = children.map(exportCommand);
   }
@@ -87,7 +44,8 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
   return out;
 }
 
-/** Returns pretty-printed JSON for the full program schema (trailing newline). */
-export function cliSchemaJson(root: CliCommand): string {
+export function cliSchemaJson(root: CliProgram): string {
   return JSON.stringify(exportCommand(root), null, 2) + "\n";
 }
+
+export type { CliSchemaExport };

package/src/skill/generate.ts

@@ -5,7 +5,7 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 import { collectOptionDefs } from "../parse.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
-import { CliCommand, CliOptionKind } from "../types.ts";
+import { CliProgram, CliOptionKind } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
 
@@ -22,7 +22,7 @@ function truncate(text: string, maxLen: number): string {
 }
 
 /** Builds third-person skill description for YAML frontmatter. */
-function skillDescription(root: CliCommand): string {
+function skillDescription(root: CliProgram): string {
   const tools = collectMcpTools(root);
   const paths = tools.map((t) => (t.path.length > 0 ? t.path.join(" ") : root.key));
   const sample = paths.slice(0, 5).join(", ");
@@ -32,7 +32,7 @@ function skillDescription(root: CliCommand): string {
 }
 
 /** Formats one command line for the catalog section. */
-function formatCommandEntry(root: CliCommand, tool: ReturnType<typeof collectMcpTools>[number]): string {
+function formatCommandEntry(root: CliProgram, tool: ReturnType<typeof collectMcpTools>[number]): string {
   const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
   let line = `- **\`${cliPath}\`** — ${tool.description}`;
   const opts = collectOptionDefs(root, tool.path);
@@ -52,8 +52,8 @@ function formatCommandEntry(root: CliCommand, tool: ReturnType<typeof collectMcp
 }
 
 /** Builds SKILL.md body for the given target. */
-function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): string {
-  const name = root.aiSkill?.name ?? sanitizeToolSegment(root.key);
+function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): string {
+  const name = sanitizeToolSegment(root.key);
   const description = skillDescription(root);
   const tools = collectMcpTools(root);
 
@@ -80,7 +80,7 @@ function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): s
       "**Prefer MCP** when a host has the server connected:",
       "",
       "```bash",
-      `${root.key} ai mcp`,
+      `${root.key} mcp`,
       "```",
       "",
       "Example Cursor `mcp.json` entry:",
@@ -91,7 +91,7 @@ function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): s
           mcpServers: {
             [root.mcpServer.name ?? root.key]: {
               command: root.key,
-              args: ["ai", "mcp"],
+              args: ["mcp"],
             },
           },
         },
@@ -159,7 +159,7 @@ function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): s
 }
 
 /** Builds reference.md with pretty-printed schema JSON. */
-function buildReferenceMd(root: CliCommand): string {
+function buildReferenceMd(root: CliProgram): string {
   return [
     `# ${root.key} — CLI reference`,
     "",
@@ -173,8 +173,8 @@ function buildReferenceMd(root: CliCommand): string {
 }
 
 /** Generates SKILL.md and reference.md for Cursor or Claude Code. */
-export function generateSkillBundle(root: CliCommand, target: SkillTarget): SkillBundle {
-  const dirName = root.aiSkill?.name ?? sanitizeToolSegment(root.key);
+export function generateSkillBundle(root: CliProgram, target: SkillTarget): SkillBundle {
+  const dirName = sanitizeToolSegment(root.key);
   return {
     dirName,
     skillMd: buildSkillMd(root, target, dirName),