incur 0.4.0 → 0.4.2

package/dist/Cli.js

@@ -1,10 +1,17 @@
+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 { z } from 'zod';
 import * as Completions from './Completions.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, findBuiltin, 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 * as Mcp from './Mcp.js';
 import * as Openapi from './Openapi.js';
@@ -26,7 +33,6 @@ export function create(nameOrDefinition, definition) {
         name,
         description: def.description,
         env: def.env,
-        options: def.options,
         vars: def.vars,
         command(nameOrCli, def) {
             if (typeof nameOrCli === 'string') {
@@ -53,11 +59,18 @@ export function create(nameOrDefinition, definition) {
                     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;
@@ -77,10 +90,13 @@ export function create(nameOrDefinition, definition) {
             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,
             });
         },
         async serve(argv = process.argv.slice(2), serveOptions = {}) {
@@ -89,12 +105,12 @@ export function create(nameOrDefinition, definition) {
             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,
@@ -110,6 +126,12 @@ export function create(nameOrDefinition, definition) {
     };
     if (rootDef)
         toRootDefinition.set(cli, rootDef);
+    if (rootDef && def.aliases)
+        toRootAliases.set(cli, 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);
@@ -121,10 +143,35 @@ export function create(nameOrDefinition, definition) {
 async function serveImpl(name, commands, argv, options = {}) {
     const stdout = options.stdout ?? ((s) => process.stdout.write(s));
     const exit = options.exit ?? ((code) => process.exit(code));
-    const { verbose, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, rest: filtered, } = extractBuiltinFlags(argv);
+    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) {
+        stdout(s.endsWith('\n') ? s : `${s}\n`);
+    }
+    let builtinFlags;
+    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 { fullOutput, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, configPath, configDisabled, rest: filtered, } = 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)
@@ -141,30 +188,51 @@ async function serveImpl(name, commands, argv, options = {}) {
         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) {
-        stdout(s.endsWith('\n') ? s : `${s}\n`);
-    }
     // Skills staleness check (skip for built-in commands)
+    let skillsCta;
     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();
-                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' }],
+                    };
                 }
             }
         }
@@ -175,9 +243,10 @@ async function serveImpl(name, commands, argv, options = {}) {
         const prefix = [];
         let scopedDescription = options.description;
         for (const token of filtered) {
-            const entry = scopedCommands.get(token);
-            if (!entry)
+            const rawEntry = scopedCommands.get(token);
+            if (!rawEntry)
                 break;
+            const entry = resolveAlias(scopedCommands, rawEntry);
             if (isGroup(entry)) {
                 scopedCommands = entry.commands;
                 scopedDescription = entry.description;
@@ -189,10 +258,11 @@ async function serveImpl(name, commands, argv, options = {}) {
                 break;
             }
         }
+        const scopedRoot = prefix.length === 0 ? options.rootCommand : undefined;
         if (llmsFull) {
             if (!formatExplicit || formatFlag === 'md') {
                 const groups = new Map();
-                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;
@@ -202,7 +272,7 @@ async function serveImpl(name, commands, argv, options = {}) {
         }
         if (!formatExplicit || formatFlag === 'md') {
             const groups = new Map();
-            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;
@@ -211,51 +281,23 @@ async function serveImpl(name, commands, argv, options = {}) {
         return;
     }
     // 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) {
-            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'));
+    const completionsIdx = builtinIdx(filtered, name, 'completions');
+    if (completionsIdx !== -1) {
+        const shell = filtered[completionsIdx + 1];
+        if (help || !shell) {
+            const b = findBuiltin('completions');
+            writeln(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)) {
             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;
@@ -265,18 +307,84 @@ async function serveImpl(name, commands, argv, options = {}) {
         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 = [];
+            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 = {
+                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 = [];
+                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);
@@ -296,10 +404,11 @@ async function serveImpl(name, commands, argv, options = {}) {
                 description: options.description,
                 global,
                 include: options.sync?.include,
+                rootCommand: options.rootCommand,
             });
             stdout('\r\x1b[K');
             const lines = [];
-            const skillLabel = (s) => s.external || s.name === name ? s.name : `${name}-${s.name}`;
+            const skillLabel = (s) => s.name;
             const maxLen = Math.max(...result.skills.map((s) => skillLabel(s).length));
             for (const s of result.skills) {
                 const label = skillLabel(s);
@@ -320,9 +429,9 @@ async function serveImpl(name, commands, argv, options = {}) {
             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 = { skills: result.paths };
-                if (verbose && result.agents.length > 0)
+                if (fullOutput && result.agents.length > 0)
                     output.agents = result.agents;
                 writeln(Formatter.format(output, formatExplicit ? formatFlag : 'toon'));
             }
@@ -334,19 +443,40 @@ async function serveImpl(name, commands, argv, options = {}) {
         return;
     }
     // 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 = [];
+            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 = {
+                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);
@@ -382,7 +512,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                     lines.push(`  "${s}"`);
             }
             writeln(lines.join('\n'));
-            if (verbose || formatExplicit)
+            if (fullOutput || formatExplicit)
                 writeln(Formatter.format({ name, command: result.command, agents: result.agents }, formatExplicit ? formatFlag : 'toon'));
         }
         catch (err) {
@@ -406,6 +536,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             writeln(Help.formatCommand(name, {
                 alias: cmd.alias,
                 aliases: options.aliases,
+                configFlag,
                 description: cmd.description ?? options.description,
                 version: options.version,
                 args: cmd.args,
@@ -426,6 +557,7 @@ async function serveImpl(name, commands, argv, options = {}) {
         else {
             writeln(Help.formatRoot(name, {
                 aliases: options.aliases,
+                configFlag,
                 description: options.description,
                 version: options.version,
                 commands: collectHelpCommands(commands),
@@ -468,6 +600,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                 writeln(Help.formatCommand(name, {
                     alias: cmd.alias,
                     aliases: options.aliases,
+                    configFlag,
                     description: cmd.description ?? options.description,
                     version: options.version,
                     args: cmd.args,
@@ -484,6 +617,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             else {
                 writeln(Help.formatRoot(helpName, {
                     aliases: isRoot ? options.aliases : undefined,
+                    configFlag,
                     description: helpDesc,
                     version: isRoot ? options.version : undefined,
                     commands: collectHelpCommands(helpCmds),
@@ -500,7 +634,8 @@ async function serveImpl(name, commands, argv, options = {}) {
                 : undefined;
             writeln(Help.formatCommand(commandName, {
                 alias: cmd.alias,
-                aliases: isRootCmd ? options.aliases : undefined,
+                aliases: isRootCmd ? options.aliases : cmd.aliases,
+                configFlag,
                 description: cmd.description,
                 version: isRootCmd ? options.version : undefined,
                 args: cmd.args,
@@ -520,6 +655,7 @@ async function serveImpl(name, commands, argv, options = {}) {
     if (schema) {
         if ('help' in resolved) {
             writeln(Help.formatRoot(`${name} ${resolved.path}`, {
+                configFlag,
                 description: resolved.description,
                 commands: collectHelpCommands(resolved.commands),
             }));
@@ -527,7 +663,9 @@ async function serveImpl(name, commands, argv, options = {}) {
         }
         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;
         }
@@ -552,24 +690,27 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
     if ('help' in resolved) {
         writeln(Help.formatRoot(`${name} ${resolved.path}`, {
+            configFlag,
             description: resolved.description,
             commands: collectHelpCommands(resolved.commands),
         }));
         return;
     }
     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,
-            options: options.optionsSchema,
-        }).options
-        : {};
     // Resolve effective format: explicit --format/--json → command default → CLI default → toon
     const resolvedFormat = 'command' in resolved && resolved.command.format;
     const format = formatExplicit ? formatFlag : resolvedFormat || options.format || 'toon';
-    // Fall back to root fetch when no subcommand matches
-    const effective = 'error' in resolved && options.rootFetch && !resolved.path
+    // 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 && !rootFallbackBlocked
         ? {
             fetchGateway: {
                 _fetch: true,
@@ -580,7 +721,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             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;
     // Resolve outputPolicy: command/group → CLI-level → default ('all')
@@ -607,13 +748,28 @@ async function serveImpl(name, commands, argv, options = {}) {
     function write(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);
@@ -624,7 +780,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                 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 = output.ok && output.data != null
@@ -659,14 +815,29 @@ async function serveImpl(name, commands, argv, options = {}) {
     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 = [];
+        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 = {
-            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;
         }
@@ -706,7 +877,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                     formatExplicit,
                     human,
                     renderOutput,
-                    verbose,
+                    fullOutput,
                     truncate,
                     write,
                     writeln,
@@ -754,12 +925,12 @@ async function serveImpl(name, commands, argv, options = {}) {
                 const mwCtx = {
                     agent: !human,
                     command: path,
+                    displayName,
                     env: cliEnv,
                     error: errorFn,
                     format,
                     formatExplicit,
                     name,
-                    options: rootOptions,
                     set(key, value) {
                         varsMap[key] = value;
                     },
@@ -770,7 +941,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                     if (!isSentinel(result) || result[sentinel] !== 'error')
                         return;
                     const err = result;
-                    const cta = formatCtaBlock(name, err.cta);
+                    const cta = formatCtaBlock(displayName, err.cta);
                     write({
                         ok: false,
                         error: {
@@ -817,182 +988,113 @@ async function serveImpl(name, commands, argv, options = {}) {
             : []),
         ...(command.middleware ?? []),
     ];
-    // Initialize vars from schema defaults
-    const varsMap = options.vars ? options.vars.parse({}) : {};
-    const envSource = options.env ?? process.env;
-    const runCommand = async () => {
-        const { args, options: parsedOptions } = Parser.parse(rest, {
-            alias: command.alias,
-            args: command.args,
-            options: command.options,
-        });
-        if (human)
-            emitDeprecationWarnings(rest, command.options, command.alias);
-        const env = command.env ? Parser.parseEnv(command.env, envSource) : {};
-        const okFn = (data, meta = {}) => {
-            return { [sentinel]: 'ok', data, cta: meta.cta };
-        };
-        const errorFn = (opts) => {
-            return { [sentinel]: 'error', ...opts };
-        };
-        const result = command.run({
-            agent: !human,
-            args,
-            env,
-            error: errorFn,
-            format,
-            formatExplicit,
-            name,
-            ok: okFn,
-            options: parsedOptions,
-            var: varsMap,
-            version: options.version,
-        });
-        // Streaming path — async generator
-        if (isAsyncGenerator(result)) {
-            await handleStreaming(result, {
-                name,
-                path,
-                start,
-                format,
-                formatExplicit,
-                human,
-                renderOutput,
-                verbose,
-                truncate,
-                write,
-                writeln,
-                exit,
+    if (human)
+        emitDeprecationWarnings(rest, command.options, command.alias);
+    let defaults;
+    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;
-                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) : {};
-        if (allMiddleware.length > 0) {
-            const errorFn = (opts) => {
-                return { [sentinel]: 'error', ...opts };
-            };
-            const mwCtx = {
-                agent: !human,
+    }
+    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,
+    });
+    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);
+        write({
+            ok: true,
+            data: result.data,
+            meta: {
                 command: path,
-                env: cliEnv,
-                error: errorFn,
-                format,
-                formatExplicit,
-                name,
-                options: rootOptions,
-                set(key, value) {
-                    varsMap[key] = value;
-                },
-                var: varsMap,
-                version: options.version,
-            };
-            const handleMwSentinel = (result) => {
-                if (!isSentinel(result) || result[sentinel] !== 'error')
-                    return;
-                const err = result;
-                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, mw) => async () => {
-                handleMwSentinel(await mw(mwCtx, next));
-            }, runCommand);
-            await composed();
-        }
-        else {
-            await runCommand();
-        }
+                duration,
+                ...(cta ? { cta } : undefined),
+            },
+        });
     }
-    catch (error) {
-        const errorOutput = {
+    else {
+        const cta = formatCtaBlock(displayName, result.cta);
+        if (human && !formatExplicit && result.error.fieldErrors) {
+            writeln(formatHumanValidationError(displayName, path, command, new ValidationError({
+                message: result.error.message,
+                fieldErrors: result.error.fieldErrors,
+            }), options.env, configFlag));
+            exit(1);
+            return;
+        }
+        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 Creates a lazy MCP HTTP handler scoped to a CLI instance. */
 function createMcpHttpHandler(name, version) {
     let transport;
-    return async (req, commands) => {
+    return async (req, commands, mcpOptions) => {
         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 });
             for (const tool of Mcp.collectTools(commands, [])) {
                 const mergedShape = {
@@ -1002,10 +1104,16 @@ function createMcpHttpHandler(name, version) {
                 const hasInput = Object.keys(mergedShape).length > 0;
                 server.registerTool(tool.name, {
                     ...(tool.description ? { description: tool.description } : undefined),
-                    ...(hasInput ? { inputSchema: mergedShape } : undefined),
+                    ...(hasInput ? { inputSchema: z.object(mergedShape) } : undefined),
                 }, async (...callArgs) => {
                     const params = hasInput ? callArgs[0] : {};
-                    return Mcp.callTool(tool, params);
+                    return Mcp.callTool(tool, params, {
+                        name,
+                        version,
+                        middlewares: mcpOptions?.middlewares,
+                        env: mcpOptions?.env,
+                        vars: mcpOptions?.vars,
+                    });
                 });
             }
             transport = new WebStandardStreamableHTTPServerTransport({
@@ -1024,14 +1132,18 @@ async function fetchImpl(name, commands, req, options = {}) {
     const segments = url.pathname.split('/').filter(Boolean);
     // 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 (segments[0] === '.well-known' &&
         segments[1] === 'skills' &&
         segments.length >= 3 &&
         req.method === 'GET') {
         const groups = new Map();
-        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) {
             const files = Skill.split(name, cmds, 1, groups);
@@ -1093,15 +1205,19 @@ async function fetchImpl(name, commands, req, options = {}) {
         }, 404);
     }
     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({
             ok: false,
@@ -1114,7 +1230,11 @@ async function fetchImpl(name, commands, req, options = {}) {
     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. */
 async function executeCommand(path, command, rest, inputOptions, start, options) {
@@ -1124,157 +1244,90 @@ async function executeCommand(path, command, rest, inputOptions, start, options)
             headers: { 'content-type': 'application/json' },
         });
     }
-    const sentinel_ = Symbol.for('incur.sentinel');
-    const varsMap = options.vars ? options.vars.parse({}) : {};
-    let response;
-    const runCommand = async () => {
-        const { args } = Parser.parse(rest, { args: command.args });
-        const parsedOptions = command.options ? command.options.parse(inputOptions) : {};
-        const okFn = (data) => ({ [sentinel_]: 'ok', data });
-        const errorFn = (opts) => ({ [sentinel_]: 'error', ...opts });
-        const result = command.run({
-            agent: true,
-            args,
-            env: {},
-            error: errorFn,
-            format: 'json',
-            formatExplicit: true,
-            name: path,
-            ok: okFn,
-            options: parsedOptions,
-            var: varsMap,
-            version: undefined,
-        });
-        // Streaming path — async generator → NDJSON response
-        if (isAsyncGenerator(result)) {
-            const stream = new ReadableStream({
-                async start(controller) {
-                    const encoder = new TextEncoder();
-                    try {
-                        let returnValue;
-                        while (true) {
-                            const { value, done } = await result.next();
-                            if (done) {
-                                returnValue = value;
-                                break;
-                            }
-                            if (isSentinel(value) && value[sentinel] === 'error') {
-                                const tagged = value;
-                                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 = { command: path };
-                        if (isSentinel(returnValue) && returnValue[sentinel] === 'error') {
-                            const tagged = returnValue;
-                            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) {
-                        controller.enqueue(encoder.encode(JSON.stringify({
-                            type: 'error',
-                            ok: false,
-                            error: {
-                                code: 'UNKNOWN',
-                                message: error instanceof Error ? error.message : String(error),
-                            },
-                        }) + '\n'));
+    const allMiddleware = [
+        ...(options.middlewares ?? []),
+        ...(options.groupMiddlewares ?? []),
+        ...(command.middleware ?? []),
+    ];
+    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 duration = `${Math.round(performance.now() - start)}ms`;
+    // 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: '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;
-            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);
-    };
-    try {
-        const allMiddleware = options.middlewares ?? [];
-        if (allMiddleware.length > 0) {
-            const errorFn = (opts) => {
-                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;
-            };
-            const mwCtx = {
-                agent: true,
-                command: path,
-                env: {},
-                error: errorFn,
-                format: 'json',
-                formatExplicit: true,
-                name: path,
-                options: {},
-                set(key, value) {
-                    varsMap[key] = value;
-                },
-                var: varsMap,
-                version: undefined,
-            };
-            const composed = allMiddleware.reduceRight((next, mw) => async () => {
-                await mw(mwCtx, next);
-            }, runCommand);
-            await composed();
-        }
-        else {
-            await runCommand();
-        }
+                    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' },
+        });
     }
-    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);
         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);
+    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. */
-function formatHumanValidationError(cli, path, command, error, envSource) {
+function formatHumanValidationError(cli, path, command, error, envSource, configFlag) {
     const lines = [];
     for (const fe of error.fieldErrors)
         lines.push(`Error: missing required argument <${fe.path}>`);
@@ -1282,6 +1335,7 @@ function formatHumanValidationError(cli, path, command, error, envSource) {
     lines.push('');
     lines.push(Help.formatCommand(path === cli ? cli : `${cli} ${path}`, {
         alias: command.alias,
+        configFlag,
         description: command.description,
         args: command.args,
         env: command.env,
@@ -1297,8 +1351,8 @@ function formatHumanValidationError(cli, path, command, error, envSource) {
 function resolveCommand(commands, tokens) {
     const [first, ...rest] = tokens;
     if (!first || !commands.has(first))
-        return { error: first ?? '(none)', path: '' };
-    let entry = commands.get(first);
+        return { error: first ?? '(none)', path: '', commands, rest };
+    let entry = resolveAlias(commands, commands.get(first));
     const path = [first];
     let remaining = rest;
     let inheritedOutputPolicy;
@@ -1327,10 +1381,16 @@ function resolveCommand(commands, tokens) {
                 description: entry.description,
                 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);
         entry = child;
@@ -1354,9 +1414,10 @@ function resolveCommand(commands, tokens) {
         ...(outputPolicy ? { outputPolicy } : undefined),
     };
 }
-/** @internal Extracts built-in flags (--verbose, --format, --json, --llms, --help, --version) from argv. */
-function extractBuiltinFlags(argv) {
-    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']);
+function extractBuiltinFlags(argv, options = {}) {
+    let fullOutput = false;
     let llms = false;
     let llmsFull = false;
     let mcp = false;
@@ -1365,15 +1426,20 @@ function extractBuiltinFlags(argv) {
     let schema = false;
     let format = 'toon';
     let formatExplicit = false;
+    let configPath;
+    let configDisabled = false;
     let filterOutput;
     let tokenLimit;
     let tokenOffset;
     let tokenCount = false;
     const rest = [];
+    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')
@@ -1391,20 +1457,49 @@ function extractBuiltinFlags(argv) {
             formatExplicit = true;
         }
         else if (token === '--format' && argv[i + 1]) {
+            if (!validFormats.has(argv[i + 1]))
+                throw new ParseError({
+                    message: `Invalid format: "${argv[i + 1]}". Expected one of: ${[...validFormats].join(', ')}`,
+                });
             format = argv[i + 1];
             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')
@@ -1413,9 +1508,11 @@ function extractBuiltinFlags(argv) {
             rest.push(token);
     }
     return {
-        verbose,
+        fullOutput,
         format,
         formatExplicit,
+        configPath,
+        configDisabled,
         filterOutput,
         tokenLimit,
         tokenOffset,
@@ -1429,14 +1526,156 @@ function extractBuiltinFlags(argv) {
         rest,
     };
 }
+/** @internal Loads config-backed option defaults for the active command. */
+async function loadCommandOptionDefaults(cli, path, options = {}) {
+    if (options.configDisabled)
+        return undefined;
+    const { loader } = options;
+    // Resolve the target file path
+    let targetPath;
+    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;
+    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);
+}
+/** @internal Resolves a config file path, expanding `~` to home dir. */
+function resolveConfigPath(filePath) {
+    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) {
+    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, explicit) {
+    let raw;
+    try {
+        raw = await fs.readFile(targetPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            if (explicit)
+                throw new ParseError({ message: `Config file not found: ${targetPath}` });
+            return undefined;
+        }
+        throw error;
+    }
+    let parsed;
+    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, cli, path) {
+    const segments = path === cli ? [] : path.split(' ');
+    let node = 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) {
     const result = [];
     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, cliName, builtin) {
+    // 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, builtin) {
+    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, builtin, subName) {
+    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, description) {
     const lines = [];
@@ -1465,14 +1704,30 @@ function isGroup(entry) {
 function isFetchGateway(entry) {
     return '_fetch' in entry;
 }
+/** @internal Type guard for alias entries. */
+function isAlias(entry) {
+    return '_alias' in entry;
+}
+/** @internal Follows an alias entry to its canonical target. Returns the entry unchanged if not an alias. */
+function resolveAlias(commands, entry) {
+    if (isAlias(entry))
+        return commands.get(entry.target);
+    return entry;
+}
 /** @internal Maps CLI instances to their command maps. */
 export const toCommands = new WeakMap();
 /** @internal Maps CLI instances to their middleware arrays. */
 const toMiddlewares = new WeakMap();
 /** @internal Maps root CLI instances to their command definitions. */
-const toRootDefinition = new WeakMap();
+export const toRootDefinition = new WeakMap();
+/** @internal Maps CLI instances to their root options schema. */
+export const toRootOptions = new WeakMap();
+/** @internal Maps CLI instances to whether config file loading is enabled. */
+export const toConfigEnabled = new WeakMap();
 /** @internal Maps CLI instances to their output policy. */
 const toOutputPolicy = new WeakMap();
+/** @internal Maps root CLI instances to their command aliases. */
+const toRootAliases = new WeakMap();
 /** @internal Sentinel symbol for `ok()` and `error()` return values. */
 const sentinel = Symbol.for('incur.sentinel');
 /** @internal Formats an error for human-readable TTY output. */
@@ -1489,8 +1744,9 @@ function formatHumanError(error) {
 /** @internal Formats a CTA block for human-readable TTY output. */
 function formatHumanCta(cta) {
     const lines = ['', 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');
@@ -1502,13 +1758,6 @@ function hasRequiredArgs(args) {
 function isSentinel(value) {
     return typeof value === 'object' && value !== null && sentinel in value;
 }
-/** @internal Type guard for async generators returned by streaming `run` handlers. */
-function isAsyncGenerator(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        Symbol.asyncIterator in value &&
-        typeof value.next === 'function');
-}
 /** @internal Handles streaming output from an async generator `run` handler. */
 async function handleStreaming(generator, ctx) {
     // Incremental: no explicit format (default toon), or explicit jsonl
@@ -1686,7 +1935,8 @@ function formatCtaBlock(name, block) {
     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)),
     };
 }
@@ -1715,6 +1965,8 @@ function buildIndexManifest(commands, prefix = []) {
 function collectIndexCommands(commands, prefix) {
     const result = [];
     for (const [name, entry] of commands) {
+        if (isAlias(entry))
+            continue;
         const path = [...prefix, name];
         if (isGroup(entry)) {
             result.push(...collectIndexCommands(entry.commands, path));
@@ -1743,6 +1995,8 @@ function buildManifest(commands, prefix = []) {
 function collectCommands(commands, prefix) {
     const result = [];
     for (const [name, entry] of commands) {
+        if (isAlias(entry))
+            continue;
         const path = [...prefix, name];
         if (isFetchGateway(entry)) {
             const cmd = { name: path.join(' ') };
@@ -1784,9 +2038,30 @@ function collectCommands(commands, prefix) {
     return result;
 }
 /** @internal Recursively collects leaf commands as `Skill.CommandInfo` for `--llms --format md`. */
-function collectSkillCommands(commands, prefix, groups) {
+function collectSkillCommands(commands, prefix, groups, rootCommand) {
     const result = [];
+    if (rootCommand) {
+        const cmd = {};
+        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 = { name: path.join(' ') };
@@ -1825,7 +2100,7 @@ function collectSkillCommands(commands, prefix, groups) {
             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. */
 export function formatExamples(examples) {
@@ -1890,4 +2165,16 @@ function emitDeprecationWarnings(argv, optionsSchema, alias) {
         }
     }
 }
+/** @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, aliases) {
+    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;
+}
 //# sourceMappingURL=Cli.js.map