incur 0.4.0 → 0.4.2

package/src/Cli.ts

@@ -1,13 +1,25 @@
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
 import { estimateTokenCount, sliceByTokens } from 'tokenx'
-import type { z } from 'zod'
+import { z } from 'zod'
 
 import * as Completions from './Completions.js'
 import type { FieldError } from './Errors.js'
-import { IncurError, ValidationError } from './Errors.js'
+import { IncurError, ParseError, ValidationError } from './Errors.js'
 import * as Fetch from './Fetch.js'
 import * as Filter from './Filter.js'
 import * as Formatter from './Formatter.js'
 import * as Help from './Help.js'
+import {
+  builtinCommands,
+  type CommandMeta,
+  findBuiltin,
+  type Shell,
+  shells,
+} from './internal/command.js'
+import * as Command from './internal/command.js'
+import { isRecord, suggest } from './internal/helpers.js'
 import { detectRunner } from './internal/pm.js'
 import type { OneOf } from './internal/types.js'
 import * as Mcp from './Mcp.js'
@@ -26,7 +38,6 @@ export type Cli<
   commands extends CommandsMap = {},
   vars extends z.ZodObject<any> | undefined = undefined,
   env extends z.ZodObject<any> | undefined = undefined,
-  opts extends z.ZodObject<any> | undefined = undefined,
 > = {
   /** Registers a root command or mounts a sub-CLI as a command group. */
   command: {
@@ -43,30 +54,23 @@ export type Cli<
     ): Cli<
       commands & { [key in name]: { args: InferOutput<args>; options: InferOutput<options> } },
       vars,
-      env,
-      opts
+      env
     >
     /** Mounts a sub-CLI as a command group. */
     <const name extends string, const sub extends CommandsMap>(
-      cli: Cli<sub, any, any, any> & { name: name },
-    ): Cli<
-      commands & { [key in keyof sub & string as `${name} ${key}`]: sub[key] },
-      vars,
-      env,
-      opts
-    >
+      cli: Cli<sub, any, any> & { name: name },
+    ): Cli<commands & { [key in keyof sub & string as `${name} ${key}`]: sub[key] }, vars, env>
     /** Mounts a root CLI as a single command. */
     <
       const name extends string,
       const args extends z.ZodObject<any> | undefined,
-      const cmdOpts extends z.ZodObject<any> | undefined,
+      const opts extends z.ZodObject<any> | undefined,
     >(
-      cli: Root<args, cmdOpts> & { name: name },
+      cli: Root<args, opts> & { name: name },
     ): Cli<
-      commands & { [key in name]: { args: InferOutput<args>; options: InferOutput<cmdOpts> } },
+      commands & { [key in name]: { args: InferOutput<args>; options: InferOutput<opts> } },
       vars,
-      env,
-      opts
+      env
     >
     /** Mounts a fetch handler as a command, optionally with OpenAPI spec for typed subcommands. */
     <const name extends string>(
@@ -78,7 +82,7 @@ export type Cli<
         openapi?: Openapi.OpenAPISpec | undefined
         outputPolicy?: OutputPolicy | undefined
       },
-    ): Cli<commands, vars, env, opts>
+    ): Cli<commands, vars, env>
   }
   /** A short description of the CLI. */
   description?: string | undefined
@@ -90,10 +94,8 @@ export type Cli<
   fetch(req: Request): Promise<Response>
   /** Parses argv, runs the matched command, and writes the output envelope to stdout. */
   serve(argv?: string[], options?: serve.Options): Promise<void>
-  /** The options schema, if declared. Use `typeof cli.options` with `middleware<vars, env, options>()` for typed middleware. */
-  options: opts
   /** Registers middleware that runs around every command. */
-  use(handler: MiddlewareHandler<vars, env, opts>): Cli<commands, vars, env, opts>
+  use(handler: MiddlewareHandler<vars, env>): Cli<commands, vars, env>
   /** The vars schema, if declared. Use `typeof cli.vars` with `middleware<vars, env>()` for typed middleware. */
   vars: vars
 }
@@ -161,12 +163,7 @@ export function create<
 >(
   name: string,
   definition: create.Options<args, env, opts, output, vars> & { run: Function },
-): Cli<
-  { [key in typeof name]: { args: InferOutput<args>; options: InferOutput<opts> } },
-  vars,
-  env,
-  opts
->
+): Cli<{ [key in typeof name]: { args: InferOutput<args>; options: InferOutput<opts> } }, vars, env>
 /** Creates a router CLI that registers subcommands. */
 export function create<
   const args extends z.ZodObject<any> | undefined = undefined,
@@ -174,10 +171,7 @@ export function create<
   const opts extends z.ZodObject<any> | undefined = undefined,
   const output extends z.ZodType | undefined = undefined,
   const vars extends z.ZodObject<any> | undefined = undefined,
->(
-  name: string,
-  definition?: create.Options<args, env, opts, output, vars>,
-): Cli<{}, vars, env, opts>
+>(name: string, definition?: create.Options<args, env, opts, output, vars>): Cli<{}, vars, env>
 /** Creates a CLI with a root handler from a single options object. Can still register subcommands. */
 export function create<
   const args extends z.ZodObject<any> | undefined = undefined,
@@ -192,8 +186,7 @@ export function create<
     [key in (typeof definition)['name']]: { args: InferOutput<args>; options: InferOutput<opts> }
   },
   vars,
-  env,
-  opts
+  env
 >
 /** Creates a router CLI from a single options object (e.g. package.json). */
 export function create<
@@ -202,9 +195,7 @@ export function create<
   const opts extends z.ZodObject<any> | undefined = undefined,
   const output extends z.ZodType | undefined = undefined,
   const vars extends z.ZodObject<any> | undefined = undefined,
->(
-  definition: create.Options<args, env, opts, output, vars> & { name: string },
-): Cli<{}, vars, env, opts>
+>(definition: create.Options<args, env, opts, output, vars> & { name: string }): Cli<{}, vars, env>
 export function create(
   nameOrDefinition: string | (any & { name: string }),
   definition?: any,
@@ -223,7 +214,6 @@ export function create(
     name,
     description: def.description,
     env: def.env,
-    options: def.options,
     vars: def.vars,
 
     command(nameOrCli: any, def?: any): any {
@@ -255,11 +245,16 @@ export function create(
           return cli
         }
         commands.set(nameOrCli, def)
+        if (def.aliases)
+          for (const a of def.aliases) commands.set(a, { _alias: true, target: nameOrCli })
         return cli
       }
       const mountedRootDef = toRootDefinition.get(nameOrCli)
       if (mountedRootDef) {
         commands.set(nameOrCli.name, mountedRootDef)
+        const rootAliases = toRootAliases.get(nameOrCli)
+        if (rootAliases)
+          for (const a of rootAliases) commands.set(a, { _alias: true, target: nameOrCli.name })
         return cli
       }
       const sub = nameOrCli as Cli
@@ -279,10 +274,13 @@ export function create(
     async fetch(req: Request) {
       if (pending.length > 0) await Promise.all(pending)
       return fetchImpl(name, commands, req, {
+        envSchema: def.env,
         mcpHandler,
         middlewares,
+        name,
         rootCommand: rootDef,
         vars: def.vars,
+        version: def.version,
       })
     },
 
@@ -291,12 +289,12 @@ export function create(
       return serveImpl(name, commands, argv, {
         ...serveOptions,
         aliases: def.aliases,
+        config: def.config,
         description: def.description,
         envSchema: def.env,
         format: def.format,
         mcp: def.mcp,
         middlewares,
-        optionsSchema: def.options,
         outputPolicy: def.outputPolicy,
         rootCommand: rootDef,
         rootFetch,
@@ -313,6 +311,9 @@ export function create(
   }
 
   if (rootDef) toRootDefinition.set(cli as unknown as Root, rootDef)
+  if (rootDef && def.aliases) toRootAliases.set(cli as unknown as Root, def.aliases)
+  if (def.options) toRootOptions.set(cli, def.options)
+  if (def.config !== undefined) toConfigEnabled.set(cli, true)
   if (def.outputPolicy) toOutputPolicy.set(cli, def.outputPolicy)
   toMiddlewares.set(cli, middlewares)
   toCommands.set(cli, commands)
@@ -336,6 +337,24 @@ export declare namespace create {
     aliases?: string[] | undefined
     /** Zod schema for positional arguments. */
     args?: args | undefined
+    /** Enable config-file defaults for command options. */
+    config?:
+      | {
+          /** Global flag name for specifying a config file path (e.g. `'config'` → `--config <path>`). Omit to auto-load only, with no CLI flag. */
+          flag?: string | undefined
+          /** Ordered list of file paths to search. First existing file wins. Supports `~` for home dir. Defaults to `['<cli>.json']` relative to cwd. */
+          files?: string[] | undefined
+          /** Custom config loader. Receives the resolved file path (or `undefined` if no file was found). Returns the parsed config tree, or `undefined` for no defaults. When omitted, the framework reads and parses JSON. */
+          loader?:
+            | ((
+                path: string | undefined,
+              ) =>
+                | Record<string, unknown>
+                | undefined
+                | Promise<Record<string, unknown> | undefined>)
+            | undefined
+        }
+      | undefined
     /** A short description of what the CLI does. */
     description?: string | undefined
     /** Zod schema for environment variables. Keys are the variable names (e.g. `NPM_TOKEN`). */
@@ -370,6 +389,8 @@ export declare namespace create {
           agent: boolean
           /** Positional arguments. */
           args: InferOutput<args>
+          /** The binary name the user invoked (e.g. an alias). Falls back to `name` when not resolvable. */
+          displayName: string
           /** Parsed environment variables. */
           env: InferOutput<env>
           /** Return an error result with optional CTAs. */
@@ -445,9 +466,28 @@ async function serveImpl(
 ) {
   const stdout = options.stdout ?? ((s: string) => process.stdout.write(s))
   const exit = options.exit ?? ((code: number) => process.exit(code))
+  const human = process.stdout.isTTY === true
+  const configEnabled = options.config !== undefined
+  const configFlag = options.config?.flag
+  const displayName = resolveDisplayName(name, options.aliases)
+
+  function writeln(s: string) {
+    stdout(s.endsWith('\n') ? s : `${s}\n`)
+  }
+
+  let builtinFlags: ReturnType<typeof extractBuiltinFlags>
+  try {
+    builtinFlags = extractBuiltinFlags(argv, { configFlag })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (human) writeln(formatHumanError({ code: 'UNKNOWN', message }))
+    else writeln(Formatter.format({ code: 'UNKNOWN', message }, 'toon'))
+    exit(1)
+    return
+  }
 
   const {
-    verbose,
+    fullOutput,
     format: formatFlag,
     formatExplicit,
     filterOutput,
@@ -460,17 +500,24 @@ async function serveImpl(
     help,
     version,
     schema,
+    configPath,
+    configDisabled,
     rest: filtered,
-  } = extractBuiltinFlags(argv)
+  } = builtinFlags
 
   // --mcp: start as MCP stdio server
   if (mcpFlag) {
-    await Mcp.serve(name, options.version ?? '0.0.0', commands)
+    await Mcp.serve(name, options.version ?? '0.0.0', commands, {
+      middlewares: options.middlewares,
+      env: options.envSchema,
+      vars: options.vars,
+      version: options.version,
+    })
     return
   }
 
   // COMPLETE: dynamic shell completions (called by shell hook at tab-press)
-  const completeShell = process.env.COMPLETE as Completions.Shell | undefined
+  const completeShell = process.env.COMPLETE as Shell | undefined
   if (completeShell) {
     // Remove separator `--` from argv
     const sepIdx = argv.indexOf('--')
@@ -482,35 +529,51 @@ async function serveImpl(
     } else {
       const index = Number(process.env._COMPLETE_INDEX ?? words.length - 1)
       const candidates = Completions.complete(commands, options.rootCommand, words, index)
+      // Add built-in commands (completions, mcp, skills) to completions
+      const current = words[index] ?? ''
+      const nonFlags = words.slice(0, index).filter((w) => !w.startsWith('-'))
+      if (nonFlags.length <= 1) {
+        for (const b of builtinCommands) {
+          if (b.name.startsWith(current) && !candidates.some((c) => c.value === b.name))
+            candidates.push({
+              value: b.name,
+              description: b.description,
+              ...(b.subcommands ? { noSpace: true } : undefined),
+            })
+        }
+      } else if (nonFlags.length === 2) {
+        const parent = nonFlags[nonFlags.length - 1]!
+        const builtin = findBuiltin(parent)
+        if (builtin?.subcommands)
+          for (const sub of builtin.subcommands)
+            if (sub.name.startsWith(current))
+              candidates.push({ value: sub.name, description: sub.description })
+      }
       const out = Completions.format(completeShell, candidates)
       if (out) stdout(out)
     }
     return
   }
 
-  // Human mode: stdout is a TTY.
-  const human = process.stdout.isTTY === true
-
-  function writeln(s: string) {
-    stdout(s.endsWith('\n') ? s : `${s}\n`)
-  }
-
   // Skills staleness check (skip for built-in commands)
+  let skillsCta: FormattedCtaBlock | undefined
   if (!llms && !llmsFull && !schema && !help && !version) {
-    const isSkillsAdd =
-      filtered[0] === 'skills' || (filtered[0] === name && filtered[1] === 'skills')
-    const isMcpAdd = filtered[0] === 'mcp' || (filtered[0] === name && filtered[1] === 'mcp')
+    const isSkillsAdd = builtinIdx(filtered, name, 'skills') !== -1
+    const isMcpAdd = builtinIdx(filtered, name, 'mcp') !== -1
     if (!isSkillsAdd && !isMcpAdd) {
       const stored = SyncSkills.readHash(name)
-      if (stored) {
+      if (stored && SyncSkills.hasInstalledSkills(name, { cwd: options.sync?.cwd })) {
         const groups = new Map<string, string>()
-        const entries = collectSkillCommands(commands, [], groups)
+        const entries = collectSkillCommands(commands, [], groups, options.rootCommand)
         if (Skill.hash(entries) !== stored) {
-          const runner = detectRunner()
-          const spec = SyncMcp.detectPackageSpecifier(name)
-          process.stderr.write(
-            `⚠ Skills are out of date. Run '${runner} ${spec} skills add' to update.\n\n`,
-          )
+          const command =
+            process.env.npm_config_user_agent || process.env.npm_execpath
+              ? `${detectRunner()} ${SyncMcp.detectPackageSpecifier(name)} skills add`
+              : `${displayName} skills add`
+          skillsCta = {
+            description: 'Skills are out of date:',
+            commands: [{ command, description: 'sync outdated skills' }],
+          }
         }
       }
     }
@@ -522,8 +585,9 @@ async function serveImpl(
     const prefix: string[] = []
     let scopedDescription: string | undefined = options.description
     for (const token of filtered) {
-      const entry = scopedCommands.get(token)
-      if (!entry) break
+      const rawEntry = scopedCommands.get(token)
+      if (!rawEntry) break
+      const entry = resolveAlias(scopedCommands, rawEntry)
       if (isGroup(entry)) {
         scopedCommands = entry.commands
         scopedDescription = entry.description
@@ -535,10 +599,12 @@ async function serveImpl(
       }
     }
 
+    const scopedRoot = prefix.length === 0 ? options.rootCommand : undefined
+
     if (llmsFull) {
       if (!formatExplicit || formatFlag === 'md') {
         const groups = new Map<string, string>()
-        const cmds = collectSkillCommands(scopedCommands, prefix, groups)
+        const cmds = collectSkillCommands(scopedCommands, prefix, groups, scopedRoot)
         const scopedName = prefix.length > 0 ? `${name} ${prefix.join(' ')}` : name
         writeln(Skill.generate(scopedName, cmds, groups))
         return
@@ -549,7 +615,7 @@ async function serveImpl(
 
     if (!formatExplicit || formatFlag === 'md') {
       const groups = new Map<string, string>()
-      const cmds = collectSkillCommands(scopedCommands, prefix, groups)
+      const cmds = collectSkillCommands(scopedCommands, prefix, groups, scopedRoot)
       const scopedName = prefix.length > 0 ? `${name} ${prefix.join(' ')}` : name
       writeln(Skill.index(scopedName, cmds, scopedDescription))
       return
@@ -559,81 +625,119 @@ async function serveImpl(
   }
 
   // completions <shell>: print shell hook script to stdout
-  const completionsIdx = (() => {
-    // e.g. `completions bash`
-    if (filtered[0] === 'completions') return 0
-    // e.g. `my-cli completions bash`
-    if (filtered[0] === name && filtered[1] === 'completions') return 1
-    // not a completions invocation
-    return -1
-  })()
-  if (completionsIdx !== -1 && filtered[completionsIdx] === 'completions') {
-    if (help) {
+  const completionsIdx = builtinIdx(filtered, name, 'completions')
+  if (completionsIdx !== -1) {
+    const shell = filtered[completionsIdx + 1]
+    if (help || !shell) {
+      const b = findBuiltin('completions')!
       writeln(
-        [
-          `${name} completions — Generate shell completion script`,
-          '',
-          `Usage: ${name} completions <shell>`,
-          '',
-          'Shells:',
-          '  bash',
-          '  fish',
-          '  nushell',
-          '  zsh',
-          '',
-          'Setup:',
-          ...(() => {
-            const rows = [
-              ['bash', `eval "$(${name} completions bash)"`, '# add to ~/.bashrc'],
-              ['zsh', `eval "$(${name} completions zsh)"`, '# add to ~/.zshrc'],
-              ['fish', `${name} completions fish | source`, '# add to ~/.config/fish/config.fish'],
-              ['nushell', `see \`${name} completions nushell\``, '# add to config.nu'],
-            ]
-            const shellW = Math.max(...rows.map((r) => r[0]!.length))
-            const cmdW = Math.max(...rows.map((r) => r[1]!.length))
-            return rows.map(
-              ([shell, cmd, comment]) =>
-                `  ${shell!.padEnd(shellW)}  ${cmd!.padEnd(cmdW)}  ${comment}`,
-            )
-          })(),
-        ].join('\n'),
+        Help.formatCommand(`${name} completions`, {
+          args: b.args,
+          description: b.description,
+          hideGlobalOptions: true,
+          hint: b.hint?.(name),
+        }),
       )
       return
     }
-    const shell = filtered[completionsIdx + 1]
-    if (!shell || !['bash', 'fish', 'nushell', 'zsh'].includes(shell)) {
+    if (!shells.includes(shell as any)) {
       writeln(
         formatHumanError({
           code: 'INVALID_SHELL',
-          message: shell
-            ? `Unknown shell '${shell}'. Supported: bash, fish, nushell, zsh`
-            : `Missing shell argument. Usage: ${name} completions <bash|fish|nushell|zsh>`,
+          message: `Unknown shell '${shell}'. Supported: ${shells.join(', ')}`,
         }),
       )
       exit(1)
       return
     }
     const names = [name, ...(options.aliases ?? [])]
-    writeln(names.map((n) => Completions.register(shell as Completions.Shell, n)).join('\n'))
+    writeln(names.map((n) => Completions.register(shell as Shell, n)).join('\n'))
     return
   }
 
   // skills add: generate skill files and install via `<pm>x skills add` (only when sync is configured)
-  const skillsIdx =
-    filtered[0] === 'skills' ? 0 : filtered[0] === name && filtered[1] === 'skills' ? 1 : -1
-  if (skillsIdx !== -1 && filtered[skillsIdx] === 'skills' && filtered[skillsIdx + 1] === 'add') {
+  const skillsIdx = builtinIdx(filtered, name, 'skills')
+  if (skillsIdx !== -1) {
+    const skillsSub = filtered[skillsIdx + 1]
+    if (skillsSub && skillsSub !== 'add' && skillsSub !== 'list') {
+      const suggestion = suggest(skillsSub, ['add', 'list'])
+      const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
+      const message = `'${skillsSub}' is not a command for '${name} skills'.${didYouMean}`
+      const ctaCommands: FormattedCta[] = []
+      if (suggestion) {
+        const corrected = argv.map((t) => (t === skillsSub ? suggestion : t))
+        ctaCommands.push({ command: `${name} ${corrected.join(' ')}` })
+      }
+      ctaCommands.push({
+        command: `${name} skills --help`,
+        description: 'see all available commands',
+      })
+      const cta: FormattedCtaBlock = {
+        description: ctaCommands.length === 1 ? 'Suggested command:' : 'Suggested commands:',
+        commands: ctaCommands,
+      }
+      if (human) {
+        writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }))
+        writeln(formatHumanCta(cta))
+      } else writeln(Formatter.format({ code: 'COMMAND_NOT_FOUND', message, cta }, 'toon'))
+      exit(1)
+      return
+    }
+    if (!skillsSub) {
+      const b = findBuiltin('skills')!
+      writeln(formatBuiltinHelp(name, b))
+      return
+    }
+    if (skillsSub === 'list') {
+      if (help) {
+        const b = findBuiltin('skills')!
+        writeln(formatBuiltinSubcommandHelp(name, b, 'list'))
+        return
+      }
+      try {
+        const result = await SyncSkills.list(name, commands, {
+          cwd: options.sync?.cwd,
+          depth: options.sync?.depth ?? 1,
+          description: options.description,
+          include: options.sync?.include,
+          rootCommand: options.rootCommand,
+        })
+        if (result.length === 0) {
+          writeln('No skills found.')
+          return
+        }
+        const lines: string[] = []
+        const maxLen = Math.max(...result.map((s) => s.name.length))
+        for (const s of result) {
+          const icon = s.installed ? '✓' : '✗'
+          const padding = s.description
+            ? `${' '.repeat(maxLen - s.name.length)}  ${s.description}`
+            : ''
+          lines.push(`  ${icon} ${s.name}${padding}`)
+        }
+        const installedCount = result.filter((s) => s.installed).length
+        lines.push('')
+        lines.push(
+          `${result.length} skill${result.length === 1 ? '' : 's'} (${installedCount} installed)`,
+        )
+        writeln(lines.join('\n'))
+      } catch (err) {
+        writeln(
+          Formatter.format(
+            {
+              code: 'LIST_SKILLS_FAILED',
+              message: err instanceof Error ? err.message : String(err),
+            },
+            formatExplicit ? formatFlag : 'toon',
+          ),
+        )
+        exit(1)
+      }
+      return
+    }
     if (help) {
-      writeln(
-        [
-          `${name} skills add — Sync skill files to your agent`,
-          '',
-          `Usage: ${name} skills add [options]`,
-          '',
-          'Options:',
-          '  --depth <number>  Grouping depth for skill files (default: 1)',
-          '  --no-global       Install to project instead of globally',
-        ].join('\n'),
-      )
+      const b = findBuiltin('skills')!
+      writeln(formatBuiltinSubcommandHelp(name, b, 'add'))
       return
     }
     const rest = filtered.slice(skillsIdx + 2)
@@ -654,11 +758,11 @@ async function serveImpl(
         description: options.description,
         global,
         include: options.sync?.include,
+        rootCommand: options.rootCommand,
       })
       stdout('\r\x1b[K')
       const lines: string[] = []
-      const skillLabel = (s: (typeof result.skills)[number]) =>
-        s.external || s.name === name ? s.name : `${name}-${s.name}`
+      const skillLabel = (s: (typeof result.skills)[number]) => s.name
       const maxLen = Math.max(...result.skills.map((s) => skillLabel(s).length))
       for (const s of result.skills) {
         const label = skillLabel(s)
@@ -678,9 +782,9 @@ async function serveImpl(
       lines.push('')
       lines.push(`Run \`${name} --help\` to see the full command reference.`)
       writeln(lines.join('\n'))
-      if (verbose || formatExplicit) {
+      if (fullOutput || formatExplicit) {
         const output: Record<string, unknown> = { skills: result.paths }
-        if (verbose && result.agents.length > 0) output.agents = result.agents
+        if (fullOutput && result.agents.length > 0) output.agents = result.agents
         writeln(Formatter.format(output, formatExplicit ? formatFlag : 'toon'))
       }
     } catch (err) {
@@ -696,21 +800,38 @@ async function serveImpl(
   }
 
   // mcp add: register CLI as MCP server via `npx add-mcp`
-  const mcpIdx = filtered[0] === 'mcp' ? 0 : filtered[0] === name && filtered[1] === 'mcp' ? 1 : -1
-  if (mcpIdx !== -1 && filtered[mcpIdx] === 'mcp' && filtered[mcpIdx + 1] === 'add') {
+  const mcpIdx = builtinIdx(filtered, name, 'mcp')
+  if (mcpIdx !== -1) {
+    const mcpSub = filtered[mcpIdx + 1]
+    if (mcpSub && mcpSub !== 'add') {
+      const suggestion = suggest(mcpSub, ['add'])
+      const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
+      const message = `'${mcpSub}' is not a command for '${name} mcp'.${didYouMean}`
+      const ctaCommands: FormattedCta[] = []
+      if (suggestion) {
+        const corrected = argv.map((t) => (t === mcpSub ? suggestion : t))
+        ctaCommands.push({ command: `${name} ${corrected.join(' ')}` })
+      }
+      ctaCommands.push({ command: `${name} mcp --help`, description: 'see all available commands' })
+      const cta: FormattedCtaBlock = {
+        description: ctaCommands.length === 1 ? 'Suggested command:' : 'Suggested commands:',
+        commands: ctaCommands,
+      }
+      if (human) {
+        writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }))
+        writeln(formatHumanCta(cta))
+      } else writeln(Formatter.format({ code: 'COMMAND_NOT_FOUND', message, cta }, 'toon'))
+      exit(1)
+      return
+    }
+    if (!mcpSub) {
+      const b = findBuiltin('mcp')!
+      writeln(formatBuiltinHelp(name, b))
+      return
+    }
     if (help) {
-      writeln(
-        [
-          `${name} mcp add — Register as an MCP server for your agent`,
-          '',
-          `Usage: ${name} mcp add [options]`,
-          '',
-          'Options:',
-          '  -c, --command <cmd>  Override the command agents will run (e.g. "pnpm my-cli --mcp")',
-          '  --no-global          Install to project instead of globally',
-          '  --agent <agent>      Target a specific agent (e.g. claude-code, cursor)',
-        ].join('\n'),
-      )
+      const b = findBuiltin('mcp')!
+      writeln(formatBuiltinSubcommandHelp(name, b, 'add'))
       return
     }
     const rest = filtered.slice(mcpIdx + 2)
@@ -744,7 +865,7 @@ async function serveImpl(
         for (const s of suggestions) lines.push(`  "${s}"`)
       }
       writeln(lines.join('\n'))
-      if (verbose || formatExplicit)
+      if (fullOutput || formatExplicit)
         writeln(
           Formatter.format(
             { name, command: result.command, agents: result.agents },
@@ -782,6 +903,7 @@ async function serveImpl(
         Help.formatCommand(name, {
           alias: cmd.alias as Record<string, string> | undefined,
           aliases: options.aliases,
+          configFlag,
           description: cmd.description ?? options.description,
           version: options.version,
           args: cmd.args,
@@ -803,6 +925,7 @@ async function serveImpl(
       writeln(
         Help.formatRoot(name, {
           aliases: options.aliases,
+          configFlag,
           description: options.description,
           version: options.version,
           commands: collectHelpCommands(commands),
@@ -851,6 +974,7 @@ async function serveImpl(
           Help.formatCommand(name, {
             alias: cmd.alias as Record<string, string> | undefined,
             aliases: options.aliases,
+            configFlag,
             description: cmd.description ?? options.description,
             version: options.version,
             args: cmd.args,
@@ -868,6 +992,7 @@ async function serveImpl(
         writeln(
           Help.formatRoot(helpName, {
             aliases: isRoot ? options.aliases : undefined,
+            configFlag,
             description: helpDesc,
             version: isRoot ? options.version : undefined,
             commands: collectHelpCommands(helpCmds),
@@ -886,7 +1011,8 @@ async function serveImpl(
       writeln(
         Help.formatCommand(commandName, {
           alias: cmd.alias as Record<string, string> | undefined,
-          aliases: isRootCmd ? options.aliases : undefined,
+          aliases: isRootCmd ? options.aliases : cmd.aliases,
+          configFlag,
           description: cmd.description,
           version: isRootCmd ? options.version : undefined,
           args: cmd.args,
@@ -909,6 +1035,7 @@ async function serveImpl(
     if ('help' in resolved) {
       writeln(
         Help.formatRoot(`${name} ${resolved.path}`, {
+          configFlag,
           description: resolved.description,
           commands: collectHelpCommands(resolved.commands),
         }),
@@ -917,7 +1044,9 @@ async function serveImpl(
     }
     if ('error' in resolved) {
       const parent = resolved.path ? `${name} ${resolved.path}` : name
-      writeln(`Error: '${resolved.error}' is not a command for '${parent}'.`)
+      const suggestion = suggest(resolved.error, resolved.commands.keys())
+      const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
+      writeln(`Error: '${resolved.error}' is not a command for '${parent}'.${didYouMean}`)
       exit(1)
       return
     }
@@ -940,6 +1069,7 @@ async function serveImpl(
   if ('help' in resolved) {
     writeln(
       Help.formatRoot(`${name} ${resolved.path}`, {
+        configFlag,
         description: resolved.description,
         commands: collectHelpCommands(resolved.commands),
       }),
@@ -949,21 +1079,22 @@ async function serveImpl(
 
   const start = performance.now()
 
-  // Parse root CLI-level options (available to middleware via c.options)
-  const rootOptions = options.optionsSchema
-    ? Parser.parse(filtered, {
-        alias: options.rootCommand?.alias as Record<string, string> | undefined,
-        options: options.optionsSchema,
-      }).options
-    : {}
-
   // Resolve effective format: explicit --format/--json → command default → CLI default → toon
   const resolvedFormat = 'command' in resolved && (resolved as any).command.format
   const format = formatExplicit ? formatFlag : resolvedFormat || options.format || 'toon'
 
-  // Fall back to root fetch when no subcommand matches
+  // Fall back to root fetch/command when no subcommand matches,
+  // but only if the token doesn't look like a typo of a known command.
+  const rootFallbackBlocked =
+    'error' in resolved &&
+    !resolved.path &&
+    (() => {
+      const candidates = [...resolved.commands.keys()]
+      for (const b of builtinCommands) candidates.push(b.name)
+      return suggest(resolved.error, candidates) !== undefined
+    })()
   const effective =
-    'error' in resolved && options.rootFetch && !resolved.path
+    'error' in resolved && options.rootFetch && !resolved.path && !rootFallbackBlocked
       ? {
           fetchGateway: {
             _fetch: true as const,
@@ -974,7 +1105,7 @@ async function serveImpl(
           path: name,
           rest: filtered,
         }
-      : 'error' in resolved && options.rootCommand && !resolved.path
+      : 'error' in resolved && options.rootCommand && !resolved.path && !rootFallbackBlocked
         ? { command: options.rootCommand, path: name, rest: filtered }
         : resolved
 
@@ -1008,13 +1139,28 @@ async function serveImpl(
   function write(output: Output) {
     if (filterPaths && output.ok && output.data != null)
       output = { ...output, data: Filter.apply(output.data, filterPaths) }
+    if (skillsCta) {
+      const existing = output.meta.cta
+      output = {
+        ...output,
+        meta: {
+          ...output.meta,
+          cta: existing
+            ? {
+                description: existing.description,
+                commands: [...existing.commands, ...skillsCta.commands],
+              }
+            : skillsCta,
+        },
+      }
+    }
     if (tokenCount) {
       const base = output.ok ? output.data : output.error
       const formatted = base != null ? Formatter.format(base, format) : ''
       return writeln(String(estimateTokenCount(formatted)))
     }
     const cta = output.meta.cta
-    if (human && !verbose) {
+    if (human && !fullOutput) {
       if (output.ok && output.data != null && renderOutput) {
         const t = truncate(Formatter.format(output.data, format))
         writeln(t.text)
@@ -1022,7 +1168,7 @@ async function serveImpl(
       if (cta) writeln(formatHumanCta(cta))
       return
     }
-    if (verbose) {
+    if (fullOutput) {
       if (tokenLimit != null || tokenOffset != null) {
         // Truncate data separately so meta (including nextOffset) is always visible
         const dataFormatted =
@@ -1058,14 +1204,27 @@ async function serveImpl(
   if ('error' in effective) {
     const helpCmd = effective.path ? `${name} ${effective.path} --help` : `${name} --help`
     const parent = effective.path ? `${name} ${effective.path}` : name
-    const message = `'${effective.error}' is not a command for '${parent}'.`
+    const candidates = 'commands' in effective ? [...effective.commands.keys()] : []
+    if (!effective.path) for (const b of builtinCommands) candidates.push(b.name)
+    const suggestion = suggest(effective.error, candidates)
+    const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
+    const message = `'${effective.error}' is not a command for '${parent}'.${didYouMean}`
+    const ctaCommands: FormattedCta[] = []
+    if (suggestion) {
+      const corrected = argv.map((t) => (t === effective.error ? suggestion : t))
+      ctaCommands.push({ command: `${name} ${corrected.join(' ')}` })
+    }
+    ctaCommands.push({ command: helpCmd, description: 'see all available commands' })
     const cta: FormattedCtaBlock = {
-      description: 'See available commands:',
-      commands: [{ command: helpCmd }],
+      description: ctaCommands.length === 1 ? 'Suggested command:' : 'Suggested commands:',
+      commands: ctaCommands,
     }
-    if (human && !verbose) {
+    if (human && !fullOutput) {
       writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }))
-      writeln(formatHumanCta(cta))
+      const mergedCta = skillsCta
+        ? { ...cta, commands: [...cta.commands, ...skillsCta.commands] }
+        : cta
+      writeln(formatHumanCta(mergedCta))
       exit(1)
       return
     }
@@ -1107,7 +1266,7 @@ async function serveImpl(
           formatExplicit,
           human,
           renderOutput,
-          verbose,
+          fullOutput,
           truncate,
           write,
           writeln,
@@ -1164,12 +1323,12 @@ async function serveImpl(
         const mwCtx: MiddlewareContext = {
           agent: !human,
           command: path,
+          displayName,
           env: cliEnv,
           error: errorFn,
           format,
           formatExplicit,
           name,
-          options: rootOptions,
           set(key: string, value: unknown) {
             varsMap[key] = value
           },
@@ -1179,7 +1338,7 @@ async function serveImpl(
         const handleMwSentinel = (result: unknown) => {
           if (!isSentinel(result) || result[sentinel] !== 'error') return
           const err = result as ErrorResult
-          const cta = formatCtaBlock(name, err.cta)
+          const cta = formatCtaBlock(displayName, err.cta)
           write({
             ok: false,
             error: {
@@ -1230,212 +1389,151 @@ async function serveImpl(
     ...((command.middleware as MiddlewareHandler[] | undefined) ?? []),
   ]
 
-  // Initialize vars from schema defaults
-  const varsMap: Record<string, unknown> = options.vars ? options.vars.parse({}) : {}
-  const envSource = options.env ?? process.env
-
-  const runCommand = async () => {
-    const { args, options: parsedOptions } = Parser.parse(rest, {
-      alias: command.alias as Record<string, string> | undefined,
-      args: command.args,
-      options: command.options,
-    })
-
-    if (human)
-      emitDeprecationWarnings(
-        rest,
-        command.options,
-        command.alias as Record<string, string> | undefined,
-      )
-
-    const env = command.env ? Parser.parseEnv(command.env, envSource) : {}
-
-    const okFn = (data: unknown, meta: { cta?: CtaBlock | undefined } = {}): never => {
-      return { [sentinel]: 'ok', data, cta: meta.cta } as never
-    }
-    const errorFn = (opts: {
-      code: string
-      exitCode?: number | undefined
-      message: string
-      retryable?: boolean | undefined
-      cta?: CtaBlock | undefined
-    }): never => {
-      return { [sentinel]: 'error', ...opts } as never
-    }
-
-    const result = command.run({
-      agent: !human,
-      args,
-      env,
-      error: errorFn,
-      format,
-      formatExplicit,
-      name,
-      ok: okFn,
-      options: parsedOptions,
-      var: varsMap,
-      version: options.version,
-    })
+  if (human)
+    emitDeprecationWarnings(
+      rest,
+      command.options,
+      command.alias as Record<string, string> | undefined,
+    )
 
-    // Streaming path — async generator
-    if (isAsyncGenerator(result)) {
-      await handleStreaming(result, {
-        name,
-        path,
-        start,
-        format,
-        formatExplicit,
-        human,
-        renderOutput,
-        verbose,
-        truncate,
-        write,
-        writeln,
-        exit,
+  let defaults: Record<string, unknown> | undefined
+  if (configEnabled) {
+    try {
+      defaults = await loadCommandOptionDefaults(name, path, {
+        configDisabled,
+        configPath,
+        files: options.config?.files,
+        loader: options.config?.loader,
       })
-      return
-    }
-
-    const awaited = await result
-
-    if (isSentinel(awaited)) {
-      const cta = formatCtaBlock(name, awaited.cta)
-      if (awaited[sentinel] === 'ok') {
-        write({
-          ok: true,
-          data: awaited.data,
-          meta: {
-            command: path,
-            duration: `${Math.round(performance.now() - start)}ms`,
-            ...(cta ? { cta } : undefined),
-          },
-        })
-      } else {
-        const err = awaited as ErrorResult
-        write({
-          ok: false,
-          error: {
-            code: err.code,
-            message: err.message,
-            ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
-          },
-          meta: {
-            command: path,
-            duration: `${Math.round(performance.now() - start)}ms`,
-            ...(cta ? { cta } : undefined),
-          },
-        })
-        exit(err.exitCode ?? 1)
-      }
-    } else {
+    } catch (error) {
       write({
-        ok: true,
-        data: awaited,
-        meta: {
-          command: path,
-          duration: `${Math.round(performance.now() - start)}ms`,
+        ok: false,
+        error: {
+          code: error instanceof IncurError ? error.code : 'UNKNOWN',
+          message: error instanceof Error ? error.message : String(error),
         },
+        meta: { command: path, duration: `${Math.round(performance.now() - start)}ms` },
       })
+      exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1)
+      return
     }
   }
 
-  try {
-    const cliEnv = options.envSchema ? Parser.parseEnv(options.envSchema, envSource) : {}
+  const result = await Command.execute(command, {
+    agent: !human,
+    argv: rest,
+    defaults,
+    displayName,
+    env: options.envSchema,
+    envSource: options.env,
+    format,
+    formatExplicit,
+    inputOptions: {},
+    middlewares: allMiddleware,
+    name,
+    path,
+    vars: options.vars,
+    version: options.version,
+  })
 
-    if (allMiddleware.length > 0) {
-      const errorFn = (opts: {
-        code: string
-        exitCode?: number | undefined
-        message: string
-        retryable?: boolean | undefined
-        cta?: CtaBlock | undefined
-      }): never => {
-        return { [sentinel]: 'error', ...opts } as never
-      }
-      const mwCtx: MiddlewareContext = {
-        agent: !human,
+  const duration = `${Math.round(performance.now() - start)}ms`
+
+  // Streaming path — async generator
+  if ('stream' in result) {
+    await handleStreaming(result.stream, {
+      name: displayName,
+      path,
+      start,
+      format,
+      formatExplicit,
+      human,
+      renderOutput,
+      fullOutput,
+      truncate,
+      write,
+      writeln,
+      exit,
+    })
+    return
+  }
+
+  if (result.ok) {
+    const cta = formatCtaBlock(displayName, result.cta as CtaBlock | undefined)
+    write({
+      ok: true,
+      data: result.data,
+      meta: {
         command: path,
-        env: cliEnv,
-        error: errorFn,
-        format,
-        formatExplicit,
-        name,
-        options: rootOptions,
-        set(key: string, value: unknown) {
-          varsMap[key] = value
-        },
-        var: varsMap,
-        version: options.version,
-      }
-      const handleMwSentinel = (result: unknown) => {
-        if (!isSentinel(result) || result[sentinel] !== 'error') return
-        const err = result as ErrorResult
-        const cta = formatCtaBlock(name, err.cta)
-        write({
-          ok: false,
-          error: {
-            code: err.code,
-            message: err.message,
-            ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
-          },
-          meta: {
-            command: path,
-            duration: `${Math.round(performance.now() - start)}ms`,
-            ...(cta ? { cta } : undefined),
-          },
-        })
-        exit(err.exitCode ?? 1)
-      }
-      const composed = allMiddleware.reduceRight(
-        (next: () => Promise<void>, mw) => async () => {
-          handleMwSentinel(await mw(mwCtx, next))
-        },
-        runCommand,
+        duration,
+        ...(cta ? { cta } : undefined),
+      },
+    })
+  } else {
+    const cta = formatCtaBlock(displayName, result.cta as CtaBlock | undefined)
+
+    if (human && !formatExplicit && result.error.fieldErrors) {
+      writeln(
+        formatHumanValidationError(
+          displayName,
+          path,
+          command,
+          new ValidationError({
+            message: result.error.message,
+            fieldErrors: result.error.fieldErrors,
+          }),
+          options.env,
+          configFlag,
+        ),
       )
-      await composed()
-    } else {
-      await runCommand()
+      exit(1)
+      return
     }
-  } catch (error) {
-    const errorOutput: Output = {
+
+    write({
       ok: false,
       error: {
-        code:
-          error instanceof IncurError
-            ? error.code
-            : error instanceof ValidationError
-              ? 'VALIDATION_ERROR'
-              : 'UNKNOWN',
-        message: error instanceof Error ? error.message : String(error),
-        ...(error instanceof IncurError ? { retryable: error.retryable } : undefined),
-        ...(error instanceof ValidationError ? { fieldErrors: error.fieldErrors } : undefined),
+        code: result.error.code,
+        message: result.error.message,
+        ...(result.error.retryable !== undefined
+          ? { retryable: result.error.retryable }
+          : undefined),
+        ...(result.error.fieldErrors ? { fieldErrors: result.error.fieldErrors } : undefined),
       },
       meta: {
         command: path,
-        duration: `${Math.round(performance.now() - start)}ms`,
+        duration,
+        ...(cta ? { cta } : undefined),
       },
-    }
-
-    if (human && !formatExplicit && error instanceof ValidationError) {
-      writeln(formatHumanValidationError(name, path, command, error, options.env))
-      exit(1)
-      return
-    }
-
-    write(errorOutput)
-    exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1)
+    })
+    exit(result.exitCode ?? 1)
   }
 }
 
 /** @internal Options for fetchImpl. */
 declare namespace fetchImpl {
   type Options = {
+    /** CLI-level env schema. */
+    envSchema?: z.ZodObject<any> | undefined
+    /** Group-level middleware collected during command resolution. */
+    groupMiddlewares?: MiddlewareHandler[] | undefined
     mcpHandler?:
-      | ((req: Request, commands: Map<string, CommandEntry>) => Promise<Response>)
+      | ((
+          req: Request,
+          commands: Map<string, CommandEntry>,
+          mcpOptions?: {
+            middlewares?: MiddlewareHandler[] | undefined
+            env?: z.ZodObject<any> | undefined
+            vars?: z.ZodObject<any> | undefined
+          },
+        ) => Promise<Response>)
       | undefined
     middlewares?: MiddlewareHandler[] | undefined
+    /** CLI name. */
+    name?: string | undefined
     rootCommand?: CommandDefinition<any, any, any> | undefined
     vars?: z.ZodObject<any> | undefined
+    /** CLI version string. */
+    version?: string | undefined
   }
 }
 
@@ -1443,11 +1541,18 @@ declare namespace fetchImpl {
 function createMcpHttpHandler(name: string, version: string) {
   let transport: any
 
-  return async (req: Request, commands: Map<string, CommandEntry>): Promise<Response> => {
+  return async (
+    req: Request,
+    commands: Map<string, CommandEntry>,
+    mcpOptions?: {
+      middlewares?: MiddlewareHandler[] | undefined
+      env?: z.ZodObject<any> | undefined
+      vars?: z.ZodObject<any> | undefined
+    },
+  ): Promise<Response> => {
     if (!transport) {
-      const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js')
-      const { WebStandardStreamableHTTPServerTransport } =
-        await import('@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js')
+      const { McpServer, WebStandardStreamableHTTPServerTransport } =
+        await import('@modelcontextprotocol/server')
 
       const server = new McpServer({ name, version })
 
@@ -1462,11 +1567,17 @@ function createMcpHttpHandler(name: string, version: string) {
           tool.name,
           {
             ...(tool.description ? { description: tool.description } : undefined),
-            ...(hasInput ? { inputSchema: mergedShape } : undefined),
+            ...(hasInput ? { inputSchema: z.object(mergedShape) } : undefined),
           },
           async (...callArgs: any[]) => {
             const params = hasInput ? (callArgs[0] as Record<string, unknown>) : {}
-            return Mcp.callTool(tool, params)
+            return Mcp.callTool(tool, params, {
+              name,
+              version,
+              middlewares: mcpOptions?.middlewares,
+              env: mcpOptions?.env,
+              vars: mcpOptions?.vars,
+            })
           },
         )
       }
@@ -1495,7 +1606,11 @@ async function fetchImpl(
 
   // MCP over HTTP: route /mcp to the MCP transport
   if (segments[0] === 'mcp' && segments.length === 1 && options.mcpHandler)
-    return options.mcpHandler(req, commands)
+    return options.mcpHandler(req, commands, {
+      middlewares: options.middlewares,
+      env: options.envSchema,
+      vars: options.vars,
+    })
 
   // .well-known/skills/ — Agent Skills Discovery (RFC)
   if (
@@ -1505,7 +1620,7 @@ async function fetchImpl(
     req.method === 'GET'
   ) {
     const groups = new Map<string, string>()
-    const cmds = collectSkillCommands(commands, [], groups)
+    const cmds = collectSkillCommands(commands, [], groups, options.rootCommand)
 
     // GET /.well-known/skills/index.json
     if (segments[2] === 'index.json' && segments.length === 3) {
@@ -1575,18 +1690,22 @@ async function fetchImpl(
 
   const resolved = resolveCommand(commands, segments)
 
-  if ('error' in resolved)
+  if ('error' in resolved) {
+    const parent = resolved.path ? `${name} ${resolved.path}` : name
+    const suggestion = suggest(resolved.error, resolved.commands.keys())
+    const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
     return jsonResponse(
       {
         ok: false,
         error: {
           code: 'COMMAND_NOT_FOUND',
-          message: `'${resolved.error}' is not a command for '${resolved.path ? `${name} ${resolved.path}` : name}'.`,
+          message: `'${resolved.error}' is not a command for '${parent}'.${didYouMean}`,
         },
         meta: { command: resolved.error, duration: `${Math.round(performance.now() - start)}ms` },
       },
       404,
     )
+  }
 
   if ('help' in resolved)
     return jsonResponse(
@@ -1604,7 +1723,11 @@ async function fetchImpl(
   if ('fetchGateway' in resolved) return resolved.fetchGateway.fetch(req)
 
   const { command, path, rest } = resolved
-  return executeCommand(path, command, rest, inputOptions, start, options)
+  const groupMiddlewares = 'middlewares' in resolved ? resolved.middlewares : []
+  return executeCommand(path, command, rest, inputOptions, start, {
+    ...options,
+    groupMiddlewares,
+  })
 }
 
 /** @internal Executes a resolved command for the fetch handler and returns a JSON Response. */
@@ -1623,201 +1746,107 @@ async function executeCommand(
     })
   }
 
-  const sentinel_ = Symbol.for('incur.sentinel')
-  const varsMap: Record<string, unknown> = options.vars ? options.vars.parse({}) : {}
-  let response: Response | undefined
+  const allMiddleware = [
+    ...(options.middlewares ?? []),
+    ...((options.groupMiddlewares as MiddlewareHandler[] | undefined) ?? []),
+    ...((command.middleware as MiddlewareHandler[] | undefined) ?? []),
+  ]
 
-  const runCommand = async () => {
-    const { args } = Parser.parse(rest, { args: command.args })
-    const parsedOptions = command.options ? command.options.parse(inputOptions) : {}
+  const result = await Command.execute(command, {
+    agent: true,
+    argv: rest,
+    env: options.envSchema,
+    format: 'json',
+    formatExplicit: true,
+    inputOptions,
+    middlewares: allMiddleware,
+    name: options.name ?? path,
+    parseMode: 'split',
+    path,
+    vars: options.vars,
+    version: options.version,
+  })
 
-    const okFn = (data: unknown): never => ({ [sentinel_]: 'ok', data }) as never
-    const errorFn = (opts: {
-      code: string
-      message: string
-      exitCode?: number | undefined
-    }): never => ({ [sentinel_]: 'error', ...opts }) as never
-
-    const result = command.run({
-      agent: true,
-      args,
-      env: {},
-      error: errorFn,
-      format: 'json',
-      formatExplicit: true,
-      name: path,
-      ok: okFn,
-      options: parsedOptions,
-      var: varsMap,
-      version: undefined,
-    })
+  const duration = `${Math.round(performance.now() - start)}ms`
 
-    // Streaming path — async generator → NDJSON response
-    if (isAsyncGenerator(result)) {
-      const stream = new ReadableStream({
-        async start(controller) {
-          const encoder = new TextEncoder()
-          try {
-            let returnValue: unknown
-            while (true) {
-              const { value, done } = await result.next()
-              if (done) {
-                returnValue = value
-                break
-              }
-              if (isSentinel(value) && (value as any)[sentinel] === 'error') {
-                const tagged = value as any
-                controller.enqueue(
-                  encoder.encode(
-                    JSON.stringify({
-                      type: 'error',
-                      ok: false,
-                      error: { code: tagged.code, message: tagged.message },
-                    }) + '\n',
-                  ),
-                )
-                controller.close()
-                return
-              }
-              controller.enqueue(
-                encoder.encode(JSON.stringify({ type: 'chunk', data: value }) + '\n'),
-              )
-            }
-            const meta: Record<string, unknown> = { command: path }
-            if (isSentinel(returnValue) && (returnValue as any)[sentinel] === 'error') {
-              const tagged = returnValue as any
-              controller.enqueue(
-                encoder.encode(
-                  JSON.stringify({
-                    type: 'error',
-                    ok: false,
-                    error: { code: tagged.code, message: tagged.message },
-                  }) + '\n',
-                ),
-              )
-            } else {
-              controller.enqueue(
-                encoder.encode(JSON.stringify({ type: 'done', ok: true, meta }) + '\n'),
-              )
-            }
-          } catch (error) {
+  // Streaming path — async generator → NDJSON response
+  if ('stream' in result) {
+    const stream = new ReadableStream({
+      async start(controller) {
+        const encoder = new TextEncoder()
+        try {
+          for await (const value of result.stream) {
             controller.enqueue(
-              encoder.encode(
-                JSON.stringify({
-                  type: 'error',
-                  ok: false,
-                  error: {
-                    code: 'UNKNOWN',
-                    message: error instanceof Error ? error.message : String(error),
-                  },
-                }) + '\n',
-              ),
+              encoder.encode(JSON.stringify({ type: 'chunk', data: value }) + '\n'),
             )
           }
-          controller.close()
-        },
-      })
-      response = new Response(stream, {
-        status: 200,
-        headers: { 'content-type': 'application/x-ndjson' },
-      })
-      return
-    }
-
-    const awaited = await result
-    const duration = `${Math.round(performance.now() - start)}ms`
-
-    if (typeof awaited === 'object' && awaited !== null && sentinel_ in awaited) {
-      const tagged = awaited as any
-      if (tagged[sentinel_] === 'error')
-        response = jsonResponse(
-          {
-            ok: false,
-            error: { code: tagged.code, message: tagged.message },
-            meta: { command: path, duration },
-          },
-          500,
-        )
-      else
-        response = jsonResponse(
-          { ok: true, data: tagged.data, meta: { command: path, duration } },
-          200,
-        )
-      return
-    }
-
-    response = jsonResponse({ ok: true, data: awaited, meta: { command: path, duration } }, 200)
+          controller.enqueue(
+            encoder.encode(
+              JSON.stringify({
+                type: 'done',
+                ok: true,
+                meta: { command: path },
+              }) + '\n',
+            ),
+          )
+        } catch (error) {
+          controller.enqueue(
+            encoder.encode(
+              JSON.stringify({
+                type: 'error',
+                ok: false,
+                error: {
+                  code: 'UNKNOWN',
+                  message: error instanceof Error ? error.message : String(error),
+                },
+              }) + '\n',
+            ),
+          )
+        }
+        controller.close()
+      },
+    })
+    return new Response(stream, {
+      status: 200,
+      headers: { 'content-type': 'application/x-ndjson' },
+    })
   }
 
-  try {
-    const allMiddleware = options.middlewares ?? []
-    if (allMiddleware.length > 0) {
-      const errorFn = (opts: {
-        code: string
-        message: string
-        exitCode?: number | undefined
-      }): never => {
-        const duration = `${Math.round(performance.now() - start)}ms`
-        response = jsonResponse(
-          {
-            ok: false,
-            error: { code: opts.code, message: opts.message },
-            meta: { command: path, duration },
-          },
-          500,
-        )
-        return undefined as never
-      }
-      const mwCtx: MiddlewareContext = {
-        agent: true,
-        command: path,
-        env: {},
-        error: errorFn,
-        format: 'json',
-        formatExplicit: true,
-        name: path,
-        options: {},
-        set(key: string, value: unknown) {
-          varsMap[key] = value
-        },
-        var: varsMap,
-        version: undefined,
-      }
-      const composed = allMiddleware.reduceRight(
-        (next: () => Promise<void>, mw) => async () => {
-          await mw(mwCtx, next)
-        },
-        runCommand,
-      )
-      await composed()
-    } else {
-      await runCommand()
-    }
-  } catch (error) {
-    const duration = `${Math.round(performance.now() - start)}ms`
-    if (error instanceof ValidationError)
-      return jsonResponse(
-        {
-          ok: false,
-          error: { code: 'VALIDATION_ERROR', message: error.message },
-          meta: { command: path, duration },
-        },
-        400,
-      )
+  if (!result.ok) {
+    const cta = formatCtaBlock(options.name ?? path, result.cta as CtaBlock | undefined)
     return jsonResponse(
       {
         ok: false,
         error: {
-          code: error instanceof IncurError ? error.code : 'UNKNOWN',
-          message: error instanceof Error ? error.message : String(error),
+          code: result.error.code,
+          message: result.error.message,
+          ...(result.error.retryable !== undefined
+            ? { retryable: result.error.retryable }
+            : undefined),
+        },
+        meta: {
+          command: path,
+          duration,
+          ...(cta ? { cta } : undefined),
         },
-        meta: { command: path, duration },
       },
-      500,
+      result.error.code === 'VALIDATION_ERROR' ? 400 : 500,
     )
   }
 
-  return response!
+  const cta = formatCtaBlock(options.name ?? path, result.cta as CtaBlock | undefined)
+  return jsonResponse(
+    {
+      ok: true,
+      data: result.data,
+      meta: {
+        command: path,
+        duration,
+        ...(cta ? { cta } : undefined),
+      },
+    },
+    200,
+  )
 }
 
 /** @internal Formats a validation error for TTY with usage hint. */
@@ -1827,6 +1856,7 @@ function formatHumanValidationError(
   command: CommandDefinition<any, any, any>,
   error: ValidationError,
   envSource?: Record<string, string | undefined>,
+  configFlag?: string,
 ): string {
   const lines: string[] = []
   for (const fe of error.fieldErrors) lines.push(`Error: missing required argument <${fe.path}>`)
@@ -1835,6 +1865,7 @@ function formatHumanValidationError(
   lines.push(
     Help.formatCommand(path === cli ? cli : `${cli} ${path}`, {
       alias: command.alias as Record<string, string> | undefined,
+      configFlag,
       description: command.description,
       args: command.args,
       env: command.env,
@@ -1873,12 +1904,12 @@ function resolveCommand(
       description?: string | undefined
       commands: Map<string, CommandEntry>
     }
-  | { error: string; path: string } {
+  | { error: string; path: string; commands: Map<string, CommandEntry>; rest: string[] } {
   const [first, ...rest] = tokens
 
-  if (!first || !commands.has(first)) return { error: first ?? '(none)', path: '' }
+  if (!first || !commands.has(first)) return { error: first ?? '(none)', path: '', commands, rest }
 
-  let entry = commands.get(first)!
+  let entry = resolveAlias(commands, commands.get(first)!)
   const path = [first]
   let remaining = rest
   let inheritedOutputPolicy: OutputPolicy | undefined
@@ -1908,10 +1939,16 @@ function resolveCommand(
         commands: entry.commands,
       }
 
-    const child = entry.commands.get(next)
-    if (!child) {
-      return { error: next, path: path.join(' ') }
+    const rawChild = entry.commands.get(next)
+    if (!rawChild) {
+      return {
+        error: next,
+        path: path.join(' '),
+        commands: entry.commands,
+        rest: remaining.slice(1),
+      }
     }
+    let child = resolveAlias(entry.commands, rawChild)
 
     path.push(next)
     remaining = remaining.slice(1)
@@ -1944,6 +1981,20 @@ declare namespace serveImpl {
   type Options = serve.Options & {
     /** Alternative binary names for this CLI. */
     aliases?: string[] | undefined
+    config?:
+      | {
+          flag?: string | undefined
+          files?: string[] | undefined
+          loader?:
+            | ((
+                path: string | undefined,
+              ) =>
+                | Record<string, unknown>
+                | undefined
+                | Promise<Record<string, unknown> | undefined>)
+            | undefined
+        }
+      | undefined
     description?: string | undefined
     /** CLI-level env schema. Parsed before middleware runs. */
     envSchema?: z.ZodObject<any> | undefined
@@ -1951,8 +2002,6 @@ declare namespace serveImpl {
     format?: Formatter.Format | undefined
     /** Middleware handlers registered on the root CLI. */
     middlewares?: MiddlewareHandler[] | undefined
-    /** CLI-level options schema. Parsed before middleware runs. */
-    optionsSchema?: z.ZodObject<any> | undefined
     /** CLI-level default output policy. */
     outputPolicy?: OutputPolicy | undefined
     mcp?:
@@ -1979,9 +2028,11 @@ declare namespace serveImpl {
   }
 }
 
-/** @internal Extracts built-in flags (--verbose, --format, --json, --llms, --help, --version) from argv. */
-function extractBuiltinFlags(argv: string[]) {
-  let verbose = false
+/** @internal Extracts built-in flags (--full-output, --format, --json, --llms, --help, --version) from argv. */
+const validFormats = new Set(['toon', 'json', 'yaml', 'md', 'jsonl'] as const)
+
+function extractBuiltinFlags(argv: string[], options: extractBuiltinFlags.Options = {}) {
+  let fullOutput = false
   let llms = false
   let llmsFull = false
   let mcp = false
@@ -1990,15 +2041,21 @@ function extractBuiltinFlags(argv: string[]) {
   let schema = false
   let format: Formatter.Format = 'toon'
   let formatExplicit = false
+  let configPath: string | undefined
+  let configDisabled = false
   let filterOutput: string | undefined
   let tokenLimit: number | undefined
   let tokenOffset: number | undefined
   let tokenCount = false
   const rest: string[] = []
 
+  const cfgFlag = options.configFlag ? `--${options.configFlag}` : undefined
+  const cfgFlagEq = options.configFlag ? `--${options.configFlag}=` : undefined
+  const noCfgFlag = options.configFlag ? `--no-${options.configFlag}` : undefined
+
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i]!
-    if (token === '--verbose') verbose = true
+    if (token === '--full-output') fullOutput = true
     else if (token === '--llms') llms = true
     else if (token === '--llms-full') llmsFull = true
     else if (token === '--mcp') mcp = true
@@ -2009,26 +2066,54 @@ function extractBuiltinFlags(argv: string[]) {
       format = 'json'
       formatExplicit = true
     } else if (token === '--format' && argv[i + 1]) {
+      if (!validFormats.has(argv[i + 1]! as any))
+        throw new ParseError({
+          message: `Invalid format: "${argv[i + 1]}". Expected one of: ${[...validFormats].join(', ')}`,
+        })
       format = argv[i + 1] as Formatter.Format
       formatExplicit = true
       i++
+    } else if (cfgFlag && token === cfgFlag) {
+      const value = argv[i + 1]
+      if (value === undefined)
+        throw new ParseError({ message: `Missing value for flag: ${cfgFlag}` })
+      configPath = value
+      configDisabled = false
+      i++
+    } else if (cfgFlagEq && token.startsWith(cfgFlagEq)) {
+      const value = token.slice(cfgFlagEq.length)
+      if (value.length === 0)
+        throw new ParseError({ message: `Missing value for flag: ${cfgFlag}` })
+      configPath = value
+      configDisabled = false
+    } else if (noCfgFlag && token === noCfgFlag) {
+      configPath = undefined
+      configDisabled = true
     } else if (token === '--filter-output' && argv[i + 1]) {
       filterOutput = argv[i + 1]!
       i++
     } else if (token === '--token-limit' && argv[i + 1]) {
-      tokenLimit = Number(argv[i + 1])
+      const n = Number(argv[i + 1])
+      if (!Number.isFinite(n) || argv[i + 1]!.trim() === '')
+        throw new ParseError({ message: `Invalid value for --token-limit: "${argv[i + 1]}"` })
+      tokenLimit = n
       i++
     } else if (token === '--token-offset' && argv[i + 1]) {
-      tokenOffset = Number(argv[i + 1])
+      const n = Number(argv[i + 1])
+      if (!Number.isFinite(n) || argv[i + 1]!.trim() === '')
+        throw new ParseError({ message: `Invalid value for --token-offset: "${argv[i + 1]}"` })
+      tokenOffset = n
       i++
     } else if (token === '--token-count') tokenCount = true
     else rest.push(token)
   }
 
   return {
-    verbose,
+    fullOutput,
     format,
     formatExplicit,
+    configPath,
+    configDisabled,
     filterOutput,
     tokenLimit,
     tokenOffset,
@@ -2043,17 +2128,191 @@ function extractBuiltinFlags(argv: string[]) {
   }
 }
 
+declare namespace extractBuiltinFlags {
+  type Options = {
+    configFlag?: string | undefined
+  }
+}
+
+/** @internal Loads config-backed option defaults for the active command. */
+async function loadCommandOptionDefaults(
+  cli: string,
+  path: string,
+  options: loadCommandOptionDefaults.Options = {},
+): Promise<Record<string, unknown> | undefined> {
+  if (options.configDisabled) return undefined
+
+  const { loader } = options
+
+  // Resolve the target file path
+  let targetPath: string | undefined
+  if (options.configPath) {
+    targetPath = resolveConfigPath(options.configPath)
+  } else {
+    const searchPaths = options.files ?? [`${cli}.json`]
+    targetPath = await findFirstExisting(searchPaths)
+  }
+
+  // Load and parse the config
+  let parsed: Record<string, unknown>
+  if (loader) {
+    const result = await loader(targetPath)
+    if (result === undefined) return undefined
+    if (!isRecord(result))
+      throw new ParseError({ message: 'Config loader must return a plain object or undefined' })
+    parsed = result
+  } else {
+    if (!targetPath) return undefined
+    const result = await readJsonConfig(targetPath, !!options.configPath)
+    if (!result) return undefined
+    parsed = result
+  }
+
+  // Extract the command section from the config tree
+  return extractCommandSection(parsed, cli, path)
+}
+
+declare namespace loadCommandOptionDefaults {
+  type Options = {
+    configDisabled?: boolean | undefined
+    configPath?: string | undefined
+    files?: string[] | undefined
+    loader?:
+      | ((
+          path: string | undefined,
+        ) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>)
+      | undefined
+  }
+}
+
+/** @internal Resolves a config file path, expanding `~` to home dir. */
+function resolveConfigPath(filePath: string): string {
+  if (filePath.startsWith('~/') || filePath === '~') {
+    return path.join(os.homedir(), filePath.slice(1))
+  }
+  return path.resolve(process.cwd(), filePath)
+}
+
+/** @internal Returns the first readable file from a list of paths, or `undefined`. */
+async function findFirstExisting(paths: string[]): Promise<string | undefined> {
+  for (const p of paths) {
+    const resolved = resolveConfigPath(p)
+    try {
+      await fs.access(resolved, fs.constants.R_OK)
+      return resolved
+    } catch {}
+  }
+  return undefined
+}
+
+/** @internal Reads and parses a JSON config file. */
+async function readJsonConfig(
+  targetPath: string,
+  explicit: boolean,
+): Promise<Record<string, unknown> | undefined> {
+  let raw: string
+  try {
+    raw = await fs.readFile(targetPath, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      if (explicit) throw new ParseError({ message: `Config file not found: ${targetPath}` })
+      return undefined
+    }
+    throw error
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new ParseError({
+      message: `Invalid JSON config file: ${targetPath}`,
+      cause: error instanceof Error ? error : undefined,
+    })
+  }
+
+  if (!isRecord(parsed))
+    throw new ParseError({
+      message: `Invalid config file: expected a top-level object in ${targetPath}`,
+    })
+  return parsed
+}
+
+/** @internal Walks the nested config tree to extract option defaults for a command path. */
+function extractCommandSection(
+  parsed: Record<string, unknown>,
+  cli: string,
+  path: string,
+): Record<string, unknown> | undefined {
+  const segments = path === cli ? [] : path.split(' ')
+  let node: unknown = parsed
+  for (const seg of segments) {
+    if (!isRecord(node)) return undefined
+    const commands = node.commands
+    if (!isRecord(commands)) return undefined
+    node = commands[seg]
+    if (node === undefined) return undefined
+  }
+  if (!isRecord(node))
+    throw new ParseError({
+      message: `Invalid config section for '${path}': expected an object`,
+    })
+
+  const options = node.options
+  if (options === undefined) return undefined
+  if (!isRecord(options))
+    throw new ParseError({
+      message: `Invalid config 'options' for '${path}': expected an object`,
+    })
+  return Object.keys(options).length > 0 ? options : undefined
+}
+
 /** @internal Collects immediate child commands/groups for help output. */
 function collectHelpCommands(
   commands: Map<string, CommandEntry>,
 ): { name: string; description?: string | undefined }[] {
   const result: { name: string; description?: string | undefined }[] = []
   for (const [name, entry] of commands) {
+    if (isAlias(entry)) continue
     result.push({ name, description: entry.description })
   }
   return result.sort((a, b) => a.name.localeCompare(b.name))
 }
 
+/** @internal Finds the index of a builtin command token in the filtered argv. Returns -1 if not found. */
+function builtinIdx(filtered: string[], cliName: string, builtin: string): number {
+  // e.g. `skills add` or `skill add`
+  if (findBuiltin(filtered[0]!)?.name === builtin) return 0
+  // e.g. `my-cli skills add`
+  if (filtered[0] === cliName && findBuiltin(filtered[1]!)?.name === builtin) return 1
+  // not a match
+  return -1
+}
+
+/** @internal Formats group-level help for a built-in command (e.g. `cli skills`). */
+function formatBuiltinHelp(cli: string, builtin: (typeof builtinCommands)[number]): string {
+  return Help.formatRoot(`${cli} ${builtin.name}`, {
+    aliases: builtin.aliases,
+    description: builtin.description,
+    commands: builtin.subcommands?.map((s) => ({ name: s.name, description: s.description })),
+  })
+}
+
+/** @internal Formats subcommand-level help for a built-in command (e.g. `cli skills add --help`). */
+function formatBuiltinSubcommandHelp(
+  cli: string,
+  builtin: (typeof builtinCommands)[number],
+  subName: string,
+): string {
+  const sub = builtin.subcommands?.find((s) => s.name === subName)
+  return Help.formatCommand(`${cli} ${builtin.name} ${subName}`, {
+    alias: sub?.alias,
+    description: sub?.description,
+    hideGlobalOptions: true,
+    options: sub?.options,
+  })
+}
+
 /** @internal Formats help text for a fetch gateway command. */
 function formatFetchHelp(name: string, description?: string): string {
   const lines: string[] = []
@@ -2080,7 +2339,11 @@ export type CommandsMap = Record<
 >
 
 /** @internal Entry stored in a command map — either a leaf definition, a group, or a fetch gateway. */
-type CommandEntry = CommandDefinition<any, any, any> | InternalGroup | InternalFetchGateway
+type CommandEntry =
+  | CommandDefinition<any, any, any>
+  | InternalGroup
+  | InternalFetchGateway
+  | InternalAlias
 
 /** Controls when output data is displayed. `'all'` displays to both humans and agents. `'agent-only'` suppresses data output in human/TTY mode. */
 export type OutputPolicy = 'agent-only' | 'all'
@@ -2116,6 +2379,27 @@ function isFetchGateway(entry: CommandEntry): entry is InternalFetchGateway {
   return '_fetch' in entry
 }
 
+/** @internal An alias entry that points to another command by name. */
+type InternalAlias = {
+  _alias: true
+  /** The canonical command name this alias resolves to. */
+  target: string
+}
+
+/** @internal Type guard for alias entries. */
+function isAlias(entry: CommandEntry): entry is InternalAlias {
+  return '_alias' in entry
+}
+
+/** @internal Follows an alias entry to its canonical target. Returns the entry unchanged if not an alias. */
+function resolveAlias(
+  commands: Map<string, CommandEntry>,
+  entry: CommandEntry,
+): Exclude<CommandEntry, InternalAlias> {
+  if (isAlias(entry)) return commands.get(entry.target)! as Exclude<CommandEntry, InternalAlias>
+  return entry
+}
+
 /** @internal Maps CLI instances to their command maps. */
 export const toCommands = new WeakMap<Cli, Map<string, CommandEntry>>()
 
@@ -2123,11 +2407,20 @@ export const toCommands = new WeakMap<Cli, Map<string, CommandEntry>>()
 const toMiddlewares = new WeakMap<Cli, MiddlewareHandler[]>()
 
 /** @internal Maps root CLI instances to their command definitions. */
-const toRootDefinition = new WeakMap<Root, CommandDefinition<any, any, any>>()
+export const toRootDefinition = new WeakMap<Root, CommandDefinition<any, any, any>>()
+
+/** @internal Maps CLI instances to their root options schema. */
+export const toRootOptions = new WeakMap<Cli, z.ZodObject<any>>()
+
+/** @internal Maps CLI instances to whether config file loading is enabled. */
+export const toConfigEnabled = new WeakMap<Cli, boolean>()
 
 /** @internal Maps CLI instances to their output policy. */
 const toOutputPolicy = new WeakMap<Cli, OutputPolicy>()
 
+/** @internal Maps root CLI instances to their command aliases. */
+const toRootAliases = new WeakMap<Root, string[]>()
+
 /** @internal Sentinel symbol for `ok()` and `error()` return values. */
 const sentinel = Symbol.for('incur.sentinel')
 
@@ -2152,7 +2445,7 @@ type ErrorResult = {
 type CtaBlock<commands extends CommandsMap = Commands> = {
   /** Commands to suggest. */
   commands: Cta<commands>[]
-  /** Human-readable label. Defaults to `"Suggested commands:"`. */
+  /** Human-readable label. Defaults to `"Suggested command:"` or `"Suggested commands:"` based on count. */
   description?: string | undefined
 }
 
@@ -2174,8 +2467,9 @@ function formatHumanError(error: {
 /** @internal Formats a CTA block for human-readable TTY output. */
 function formatHumanCta(cta: FormattedCtaBlock): string {
   const lines: string[] = ['', cta.description]
+  const maxLen = Math.max(...cta.commands.map((c) => c.command.length))
   for (const c of cta.commands) {
-    const desc = c.description ? `  # ${c.description}` : ''
+    const desc = c.description ? `  ${''.padEnd(maxLen - c.command.length)}# ${c.description}` : ''
     lines.push(`  ${c.command}${desc}`)
   }
   return lines.join('\n')
@@ -2190,16 +2484,6 @@ function isSentinel(value: unknown): value is OkResult | ErrorResult {
   return typeof value === 'object' && value !== null && sentinel in value
 }
 
-/** @internal Type guard for async generators returned by streaming `run` handlers. */
-function isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown, unknown, unknown> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    Symbol.asyncIterator in value &&
-    typeof (value as any).next === 'function'
-  )
-}
-
 /** @internal Handles streaming output from an async generator `run` handler. */
 async function handleStreaming(
   generator: AsyncGenerator<unknown, unknown, unknown>,
@@ -2211,7 +2495,7 @@ async function handleStreaming(
     formatExplicit: boolean
     human: boolean
     renderOutput: boolean
-    verbose: boolean
+    fullOutput: boolean
     truncate: (s: string) => { text: string; truncated: boolean; nextOffset?: number | undefined }
     write: (output: Output) => void
     writeln: (s: string) => void
@@ -2405,7 +2689,9 @@ async function handleStreaming(
 function formatCtaBlock(name: string, block: CtaBlock | undefined): FormattedCtaBlock | undefined {
   if (!block || block.commands.length === 0) return undefined
   return {
-    description: block.description ?? 'Suggested commands:',
+    description:
+      block.description ??
+      (block.commands.length === 1 ? 'Suggested command:' : 'Suggested commands:'),
     commands: block.commands.map((c) => formatCta(name, c)),
   }
 }
@@ -2439,6 +2725,7 @@ function collectIndexCommands(
 ): { name: string; description?: string | undefined }[] {
   const result: { name: string; description?: string | undefined }[] = []
   for (const [name, entry] of commands) {
+    if (isAlias(entry)) continue
     const path = [...prefix, name]
     if (isGroup(entry)) {
       result.push(...collectIndexCommands(entry.commands, path))
@@ -2473,6 +2760,7 @@ function collectCommands(
 }[] {
   const result: ReturnType<typeof collectCommands> = []
   for (const [name, entry] of commands) {
+    if (isAlias(entry)) continue
     const path = [...prefix, name]
     if (isFetchGateway(entry)) {
       const cmd: (typeof result)[number] = { name: path.join(' ') }
@@ -2513,9 +2801,23 @@ function collectSkillCommands(
   commands: Map<string, CommandEntry>,
   prefix: string[],
   groups: Map<string, string>,
+  rootCommand?: CommandDefinition<any, any, any> | undefined,
 ): Skill.CommandInfo[] {
   const result: Skill.CommandInfo[] = []
+  if (rootCommand) {
+    const cmd: Skill.CommandInfo = {}
+    if (rootCommand.description) cmd.description = rootCommand.description
+    if (rootCommand.args) cmd.args = rootCommand.args
+    if (rootCommand.env) cmd.env = rootCommand.env
+    if (rootCommand.hint) cmd.hint = rootCommand.hint
+    if (rootCommand.options) cmd.options = rootCommand.options
+    if (rootCommand.output) cmd.output = rootCommand.output
+    const examples = formatExamples(rootCommand.examples)
+    if (examples) cmd.examples = examples
+    result.push(cmd)
+  }
   for (const [name, entry] of commands) {
+    if (isAlias(entry)) continue
     const path = [...prefix, name]
     if (isFetchGateway(entry)) {
       const cmd: Skill.CommandInfo = { name: path.join(' ') }
@@ -2544,7 +2846,7 @@ function collectSkillCommands(
       result.push(cmd)
     }
   }
-  return result.sort((a, b) => a.name.localeCompare(b.name))
+  return result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''))
 }
 
 /** @internal Formats examples into `{ command, description }` objects. `command` is the args/options suffix only. */
@@ -2684,15 +2986,11 @@ type CommandDefinition<
   output extends z.ZodType | undefined = undefined,
   vars extends z.ZodObject<any> | undefined = undefined,
   cliEnv extends z.ZodObject<any> | undefined = undefined,
-> = {
-  /** Map of option names to single-char aliases. */
-  alias?: options extends z.ZodObject<any>
-    ? Partial<Record<keyof z.output<options>, string>>
-    : Record<string, string> | undefined
+> = CommandMeta<options> & {
+  /** Alternative names for this command (e.g. `['extensions', 'ext']` for an `extension` command). */
+  aliases?: string[] | undefined
   /** Zod schema for positional arguments. */
   args?: args | undefined
-  /** A short description of what the command does. */
-  description?: string | undefined
   /** Zod schema for environment variables. Keys are the variable names (e.g. `NPM_TOKEN`). */
   env?: env | undefined
   /** Usage examples for this command. */
@@ -2701,8 +2999,6 @@ type CommandDefinition<
   format?: Formatter.Format | undefined
   /** Plain text hint displayed after examples and before global options. */
   hint?: string | undefined
-  /** Zod schema for named options/flags. */
-  options?: options | undefined
   /** Zod schema for the command's return value. */
   output?: output | undefined
   /**
@@ -2724,6 +3020,8 @@ type CommandDefinition<
     agent: boolean
     /** Positional arguments. */
     args: InferOutput<args>
+    /** The binary name the user invoked (e.g. an alias). Falls back to `name` when not resolvable. */
+    displayName: string
     /** Parsed environment variables. */
     env: InferOutput<env>
     /** Return an error result with optional CTAs. */
@@ -2801,3 +3099,13 @@ function emitDeprecationWarnings(
     }
   }
 }
+
+/** @internal Resolves the display name from `process.argv[1]` basename. Returns the basename if it matches `name` or one of the `aliases`, otherwise falls back to `name`. */
+function resolveDisplayName(name: string, aliases?: string[]): string {
+  const bin = process.argv[1]
+  if (!bin) return name
+  const basename = path.basename(bin)
+  if (basename === name) return name
+  if (aliases?.includes(basename)) return basename
+  return name
+}