incur 0.4.0 → 0.4.1

package/src/Cli.test.ts

@@ -1,4 +1,7 @@
 import { Cli, Errors, z } from 'incur'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
 
 const originalIsTTY = process.stdout.isTTY
 beforeAll(() => {
@@ -37,6 +40,42 @@ async function serve(
   }
 }
 
+function createConfigCli(flag?: string) {
+  const project = Cli.create('project').command('list', {
+    options: z.object({
+      label: z.array(z.string()).default([]),
+      limit: z.number().default(10),
+    }),
+    run(c) {
+      return c.options
+    },
+  })
+
+  const cli = Cli.create('test', {
+    config: flag !== undefined ? { flag } : {},
+    options: z.object({
+      rootValue: z.string().default('root-default'),
+    }),
+    run(c) {
+      return c.options
+    },
+  })
+
+  cli.command('echo', {
+    options: z.object({
+      prefix: z.string().default(''),
+      upper: z.boolean().default(false),
+    }),
+    run(c) {
+      return c.options
+    },
+  })
+
+  cli.command(project)
+
+  return cli
+}
+
 describe('create', () => {
   test('returns cli instance with name', () => {
     const cli = Cli.create('test')
@@ -62,6 +101,518 @@ describe('command', () => {
   })
 })
 
+describe('config defaults', () => {
+  let cwd: string
+  let dir: string
+
+  beforeEach(async () => {
+    cwd = process.cwd()
+    dir = await mkdtemp(join(tmpdir(), 'incur-config-'))
+    process.chdir(dir)
+  })
+
+  afterEach(async () => {
+    process.chdir(cwd)
+    await rm(dir, { force: true, recursive: true })
+  })
+
+  test('auto-loads <cli>.json for leaf commands', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: {
+          echo: {
+            options: {
+              prefix: 'cfg',
+              upper: true,
+            },
+          },
+        },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli(), ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'cfg', upper: true })
+  })
+
+  test('ignores a missing auto config file', async () => {
+    const { output } = await serve(createConfigCli(), ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '', upper: false })
+  })
+
+  test('root options coexist with subcommand keys', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        options: { rootValue: 'cfg-root' },
+        commands: {
+          echo: { options: { prefix: 'cfg' } },
+        },
+      }),
+    )
+
+    const rootResult = await serve(createConfigCli(), ['--json'])
+    expect(JSON.parse(rootResult.output)).toEqual({ rootValue: 'cfg-root' })
+
+    const echoResult = await serve(createConfigCli(), ['echo', '--json'])
+    expect(JSON.parse(echoResult.output)).toEqual({ prefix: 'cfg', upper: false })
+  })
+
+  test('walks nested command sections in config tree', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: {
+          project: {
+            commands: {
+              list: {
+                options: {
+                  label: ['cfg'],
+                  limit: 25,
+                },
+              },
+            },
+          },
+        },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli(), ['project', 'list', '--json'])
+    expect(JSON.parse(output)).toEqual({ label: ['cfg'], limit: 25 })
+  })
+
+  test('uses an explicit --config path instead of the auto file', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'auto' } } },
+      }),
+    )
+    await writeFile(
+      join(dir, 'custom.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'custom', upper: true } } },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli('config'), [
+      'echo',
+      '--config',
+      'custom.json',
+      '--json',
+    ])
+    expect(JSON.parse(output)).toEqual({ prefix: 'custom', upper: true })
+  })
+
+  test('--no-config disables earlier config flags, and a later --config wins again', async () => {
+    await writeFile(
+      join(dir, 'one.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'one' } } },
+      }),
+    )
+    await writeFile(
+      join(dir, 'two.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'two' } } },
+      }),
+    )
+
+    const first = await serve(createConfigCli('config'), [
+      'echo',
+      '--config',
+      'one.json',
+      '--no-config',
+      '--json',
+    ])
+    expect(JSON.parse(first.output)).toEqual({ prefix: '', upper: false })
+
+    const second = await serve(createConfigCli('config'), [
+      'echo',
+      '--config',
+      'one.json',
+      '--no-config',
+      '--config=two.json',
+      '--json',
+    ])
+    expect(JSON.parse(second.output)).toEqual({ prefix: 'two', upper: false })
+  })
+
+  test('fails when an explicit config file is missing', async () => {
+    const { exitCode, output } = await serve(createConfigCli('config'), [
+      'echo',
+      '--config',
+      'missing.json',
+    ])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Config file not found')
+  })
+
+  test('fails on invalid JSON config files', async () => {
+    await writeFile(join(dir, 'test.json'), '{ invalid')
+
+    const { exitCode, output } = await serve(createConfigCli(), ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Invalid JSON config file')
+  })
+
+  test('fails when the config file top level is not an object', async () => {
+    await writeFile(join(dir, 'test.json'), JSON.stringify(['bad']))
+
+    const { exitCode, output } = await serve(createConfigCli(), ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('expected a top-level object')
+  })
+
+  test('fails when the selected config section is not an object', async () => {
+    await writeFile(join(dir, 'test.json'), JSON.stringify({ commands: { echo: true } }))
+
+    const { exitCode, output } = await serve(createConfigCli(), ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Invalid config section for 'echo'")
+  })
+
+  test('fails validation when config option values are invalid', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: { echo: { options: { upper: 'nope' } } },
+      }),
+    )
+
+    const { exitCode, output } = await serve(createConfigCli(), ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('VALIDATION_ERROR')
+  })
+
+  test('argv overrides invalid config values at the CLI layer', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 123 } } },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli(), ['echo', '--prefix', 'cli', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'cli', upper: false })
+  })
+
+  test('built-in commands ignore config loading', async () => {
+    await writeFile(join(dir, 'test.json'), '{ invalid')
+
+    const { output, exitCode } = await serve(createConfigCli(), ['--help'])
+    expect(exitCode).toBeUndefined()
+    expect(output).toContain('Global Options:')
+  })
+
+  test('config without flag does not reserve --config', async () => {
+    const cli = Cli.create('test', { config: {} })
+    cli.command('echo', {
+      options: z.object({ config: z.string().default('') }),
+      run(c) {
+        return c.options
+      },
+    })
+
+    const { output } = await serve(cli, ['echo', '--config', 'my-value', '--json'])
+    expect(JSON.parse(output)).toEqual({ config: 'my-value' })
+  })
+
+  test('--help shows config flags only when flag name is set', async () => {
+    const { output } = await serve(createConfigCli('config'), ['--help'])
+    expect(output).toContain('--config <path>')
+    expect(output).toContain('--no-config')
+
+    const { output: noFlagOutput } = await serve(createConfigCli(), ['--help'])
+    expect(noFlagOutput).not.toContain('--config')
+  })
+
+  test('custom flag name is used for config path override', async () => {
+    await writeFile(
+      join(dir, 'custom.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'custom' } } },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli('settings'), [
+      'echo',
+      '--settings',
+      'custom.json',
+      '--json',
+    ])
+    expect(JSON.parse(output)).toEqual({ prefix: 'custom', upper: false })
+  })
+
+  test('searches files list in order, first match wins', async () => {
+    await writeFile(
+      join(dir, '.testrc.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'rc' } } } }),
+    )
+
+    const cli = Cli.create('test', {
+      config: { files: ['test.json', '.testrc.json'] },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'rc' })
+  })
+
+  test('files: [] disables auto-discovery', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'should-not-load' } } } }),
+    )
+
+    const cli = Cli.create('test', {
+      config: { files: [] },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '' })
+  })
+
+  test('files supports ~ for home directory', async () => {
+    const configDir = join(homedir(), '.config', 'test-incur-files-tilde')
+    await mkdir(configDir, { recursive: true })
+    try {
+      await writeFile(
+        join(configDir, 'config.json'),
+        JSON.stringify({ commands: { echo: { options: { prefix: 'home' } } } }),
+      )
+
+      const cli = Cli.create('test', {
+        config: { files: ['test.json', '~/.config/test-incur-files-tilde/config.json'] },
+      })
+      cli.command('echo', {
+        options: z.object({ prefix: z.string().default('') }),
+        run: (c) => c.options,
+      })
+
+      const { output } = await serve(cli, ['echo', '--json'])
+      expect(JSON.parse(output)).toEqual({ prefix: 'home' })
+    } finally {
+      await rm(configDir, { recursive: true, force: true })
+    }
+  })
+
+  test('explicit --flag overrides files list', async () => {
+    await writeFile(
+      join(dir, '.testrc.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'rc' } } } }),
+    )
+    await writeFile(
+      join(dir, 'override.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'override' } } } }),
+    )
+
+    const cli = Cli.create('test', {
+      config: { flag: 'config', files: ['.testrc.json'] },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--config', 'override.json', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'override' })
+  })
+
+  test('custom loader replaces JSON parsing', async () => {
+    await writeFile(join(dir, 'test.ini'), 'prefix=ini-value')
+
+    const cli = Cli.create('test', {
+      config: {
+        files: ['test.ini'],
+        async loader(path) {
+          if (!path) return undefined
+          const raw = await readFile(path, 'utf8')
+          const obj: Record<string, unknown> = {}
+          for (const line of raw.split('\n')) {
+            const eq = line.indexOf('=')
+            if (eq !== -1) obj[line.slice(0, eq).trim()] = line.slice(eq + 1).trim()
+          }
+          return { commands: { echo: { options: obj } } }
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'ini-value' })
+  })
+
+  test('loader with files: [] receives undefined path', async () => {
+    const cli = Cli.create('test', {
+      config: {
+        files: [],
+        loader: async (path) => {
+          expect(path).toBeUndefined()
+          return { commands: { echo: { options: { prefix: 'from-loader' } } } }
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'from-loader' })
+  })
+
+  test('loader returning undefined applies no defaults', async () => {
+    const cli = Cli.create('test', {
+      config: { files: [], loader: async () => undefined },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '' })
+  })
+
+  test('--no-flag skips loader entirely', async () => {
+    let loaderCalled = false
+    const cli = Cli.create('test', {
+      config: {
+        flag: 'config',
+        files: [],
+        loader: async () => {
+          loaderCalled = true
+          return { commands: { echo: { options: { prefix: 'should-not-load' } } } }
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--no-config', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '' })
+    expect(loaderCalled).toBe(false)
+  })
+
+  test('loader errors propagate', async () => {
+    const cli = Cli.create('test', {
+      config: {
+        files: [],
+        loader: async () => {
+          throw new Error('Remote config server unreachable')
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { exitCode, output } = await serve(cli, ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Remote config server unreachable')
+  })
+
+  test('--no-flag disables auto-discovery without prior --flag', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'auto-loaded' } } } }),
+    )
+
+    const { output } = await serve(createConfigCli('config'), ['echo', '--no-config', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '', upper: false })
+  })
+
+  test('--config without a value produces an error', async () => {
+    const { exitCode, output } = await serve(createConfigCli('config'), ['echo', '--config'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Missing value for flag')
+  })
+
+  test('--config= (empty value) produces an error', async () => {
+    const { exitCode, output } = await serve(createConfigCli('config'), ['echo', '--config='])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Missing value for flag')
+  })
+
+  test('--no-settings works with custom flag name', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'auto' } } } }),
+    )
+
+    const { output } = await serve(createConfigCli('settings'), ['echo', '--no-settings', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '', upper: false })
+  })
+
+  test('camelCase config keys are accepted at cli level', async () => {
+    const cli = Cli.create('test', { config: {} })
+    cli.command('echo', {
+      options: z.object({ saveDev: z.boolean().default(false) }),
+      run: (c) => c.options,
+    })
+
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({ commands: { echo: { options: { 'save-dev': true } } } }),
+    )
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ saveDev: true })
+  })
+
+  test('config defaults with only subcommand namespaces yields no option defaults', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: {
+          echo: { options: { prefix: 'child' } },
+          project: { commands: { list: { options: { limit: 50 } } } },
+        },
+      }),
+    )
+
+    const rootResult = await serve(createConfigCli(), ['--json'])
+    expect(JSON.parse(rootResult.output)).toEqual({ rootValue: 'root-default' })
+  })
+
+  test('explicit --flag path is forwarded to custom loader', async () => {
+    await writeFile(join(dir, 'custom.dat'), 'prefix=custom-loader')
+
+    const cli = Cli.create('test', {
+      config: {
+        flag: 'config',
+        async loader(path) {
+          if (!path) return undefined
+          const raw = await readFile(path, 'utf8')
+          const [, value] = raw.split('=')
+          return { commands: { echo: { options: { prefix: value!.trim() } } } }
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--config', 'custom.dat', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'custom-loader' })
+  })
+})
+
 describe('serve', () => {
   test('outputs data only by default', async () => {
     const cli = Cli.create('test')
@@ -79,7 +630,7 @@ describe('serve', () => {
     `)
   })
 
-  test('--verbose outputs full envelope', async () => {
+  test('--full-output outputs full envelope', async () => {
     const cli = Cli.create('test')
     cli.command('greet', {
       args: z.object({ name: z.string() }),
@@ -88,7 +639,7 @@ describe('serve', () => {
       },
     })
 
-    const { output } = await serve(cli, ['greet', 'world', '--verbose'])
+    const { output } = await serve(cli, ['greet', 'world', '--full-output'])
     expect(output).toMatchInlineSnapshot(`
       "ok: true
       data:
@@ -140,9 +691,9 @@ describe('serve', () => {
       "code: COMMAND_NOT_FOUND
       message: 'nonexistent' is not a command for 'test'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          test --help
+        description: "Suggested command:"
+        commands[1]{command,description}:
+          test --help,see all available commands
       "
     `)
   })
@@ -157,16 +708,16 @@ describe('serve', () => {
     expect(output).toMatchInlineSnapshot(`
       "Error: 'nonexistent' is not a command for 'test'.
 
-      See available commands:
-        test --help
+      Suggested command:
+        test --help  # see all available commands
       "
     `)
   })
 
-  test('--verbose outputs full error envelope for unknown command', async () => {
+  test('--full-output outputs full error envelope for unknown command', async () => {
     const cli = Cli.create('test')
 
-    const { output, exitCode } = await serve(cli, ['nonexistent', '--verbose'])
+    const { output, exitCode } = await serve(cli, ['nonexistent', '--full-output'])
     expect(exitCode).toBe(1)
     expect(output).toMatchInlineSnapshot(`
       "ok: false
@@ -176,14 +727,100 @@ describe('serve', () => {
       meta:
         command: nonexistent
         cta:
-          description: "See available commands:"
-          commands[1]{command}:
-            test --help
+          description: "Suggested command:"
+          commands[1]{command,description}:
+            test --help,see all available commands
         duration: <stripped>
       "
     `)
   })
 
+  test('suggests similar command for typos', async () => {
+    const cli = Cli.create('test')
+    cli.command('deploy', { run: () => ({}) })
+    cli.command('status', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['deplyo'])
+    expect(exitCode).toBe(1)
+    expect(output).toMatchInlineSnapshot(`
+      "code: COMMAND_NOT_FOUND
+      message: 'deplyo' is not a command for 'test'. Did you mean 'deploy'?
+      cta:
+        description: "Suggested commands:"
+        commands[2]:
+          - command: test deploy
+          - command: test --help
+            description: see all available commands
+      "
+    `)
+  })
+
+  test('suggests similar command for typos in TTY', async () => {
+    ;(process.stdout as any).isTTY = true
+    const cli = Cli.create('test')
+    cli.command('deploy', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['deplyo'])
+    ;(process.stdout as any).isTTY = false
+    expect(exitCode).toBe(1)
+    expect(output).toMatchInlineSnapshot(`
+      "Error: 'deplyo' is not a command for 'test'. Did you mean 'deploy'?
+
+      Suggested commands:
+        test deploy
+        test --help  # see all available commands
+      "
+    `)
+  })
+
+  test('suggests builtin commands for typos', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['mpc'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Did you mean 'mcp'?")
+    expect(output).toContain('test mcp')
+  })
+
+  test('preserves flags in suggestion CTA', async () => {
+    const cli = Cli.create('test')
+    cli.command('deploy', { run: () => ({}) })
+
+    const { output } = await serve(cli, ['deplyo', '--full-output'])
+    expect(output).toContain('test deploy --full-output')
+  })
+
+  test('no suggestion when input is too far from any command', async () => {
+    const cli = Cli.create('test')
+    cli.command('deploy', { run: () => ({}) })
+
+    const { output } = await serve(cli, ['xyz'])
+    expect(output).not.toContain('Did you mean')
+  })
+
+  test('suggests similar subcommand for typos', async () => {
+    const cli = Cli.create('test')
+    const pr = Cli.create('pr')
+      .command('list', { run: () => ({}) })
+      .command('create', { run: () => ({}) })
+    cli.command(pr)
+
+    const { output, exitCode } = await serve(cli, ['pr', 'craete'])
+    expect(exitCode).toBe(1)
+    expect(output).toMatchInlineSnapshot(`
+      "code: COMMAND_NOT_FOUND
+      message: 'craete' is not a command for 'test pr'. Did you mean 'create'?
+      cta:
+        description: "Suggested commands:"
+        commands[2]:
+          - command: test pr create
+          - command: test pr --help
+            description: see all available commands
+      "
+    `)
+  })
+
   test('wraps handler errors in error output', async () => {
     const cli = Cli.create('test')
     cli.command('fail', {
@@ -353,10 +990,10 @@ describe('serve', () => {
     expect(JSON.parse(output)).toEqual({ pong: true })
   })
 
-  test('--verbose --format json outputs full envelope as JSON', async () => {
+  test('--full-output --format json outputs full envelope as JSON', async () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({ pong: true }) })
-    const { output } = await serve(cli, ['ping', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['ping', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.ok).toBe(true)
     expect(parsed.data).toEqual({ pong: true })
@@ -641,6 +1278,38 @@ describe('--llms', () => {
     expect(output).toContain('test auth auth logout')
     expect(output).not.toContain('ping')
   })
+
+  test('--llms includes root command', async () => {
+    const cli = Cli.create('my-cli', {
+      description: 'Fetch URLs',
+      args: z.object({ url: z.string().describe('URL to fetch') }),
+      options: z.object({ objective: z.string().optional().describe('Narrow content') }),
+      run: ({ args }) => args.url,
+    })
+    cli.command('auth', { description: 'Auth commands', run: () => ({}) })
+
+    const { output } = await serve(cli, ['--llms'])
+    expect(output).toContain('| `my-cli <url>` | Fetch URLs |')
+    expect(output).toContain('| `my-cli auth` | Auth commands |')
+  })
+
+  test('--llms-full includes root command with args/options', async () => {
+    const cli = Cli.create('my-cli', {
+      description: 'Fetch URLs',
+      args: z.object({ url: z.string().describe('URL to fetch') }),
+      options: z.object({ objective: z.string().optional().describe('Narrow content') }),
+      output: z.string().describe('Page content'),
+      run: ({ args }) => args.url,
+    })
+    cli.command('auth', { description: 'Auth commands', run: () => ({}) })
+
+    const { output } = await serve(cli, ['--llms-full'])
+    expect(output).toContain('# my-cli\n\nFetch URLs')
+    expect(output).toContain('| `url` | `string` | yes | URL to fetch |')
+    expect(output).toContain('| `--objective` | `string` |  | Narrow content |')
+    expect(output).toContain('# my-cli auth')
+    expect(output).not.toContain('# my-cli \n')
+  })
 })
 
 describe('--schema', () => {
@@ -738,6 +1407,14 @@ describe('--schema', () => {
     expect(exitCode).toBe(1)
   })
 
+  test('on unknown command suggests similar', async () => {
+    const cli = Cli.create('test')
+    cli.command('greet', { run: () => ({}) })
+    const { output, exitCode } = await serve(cli, ['grete', '--schema'])
+    expect(output).toContain("Did you mean 'greet'?")
+    expect(exitCode).toBe(1)
+  })
+
   test('on group shows available commands', async () => {
     const cli = Cli.create('test')
     const pr = Cli.create('pr', { description: 'PR management' }).command('list', {
@@ -802,14 +1479,14 @@ describe('subcommands', () => {
     `)
   })
 
-  test('--verbose shows full command path in meta', async () => {
+  test('--full-output shows full command path in meta', async () => {
     const cli = Cli.create('test')
     const pr = Cli.create('pr', { description: 'PR management' }).command('list', {
       run: () => ({ count: 0 }),
     })
     cli.command(pr)
 
-    const { output } = await serve(cli, ['pr', 'list', '--verbose'])
+    const { output } = await serve(cli, ['pr', 'list', '--full-output'])
     expect(output).toMatchInlineSnapshot(`
       "ok: true
       data:
@@ -837,7 +1514,7 @@ describe('subcommands', () => {
     `)
   })
 
-  test('nested group shows full path in verbose meta', async () => {
+  test('nested group shows full path in full-output meta', async () => {
     const cli = Cli.create('test')
     const review = Cli.create('review', { description: 'Reviews' }).command('approve', {
       run: () => ({ approved: true }),
@@ -846,7 +1523,7 @@ describe('subcommands', () => {
     pr.command(review)
     cli.command(pr)
 
-    const { output } = await serve(cli, ['pr', 'review', 'approve', '--verbose'])
+    const { output } = await serve(cli, ['pr', 'review', 'approve', '--full-output'])
     expect(output).toMatchInlineSnapshot(`
       "ok: true
       data:
@@ -871,9 +1548,9 @@ describe('subcommands', () => {
       "code: COMMAND_NOT_FOUND
       message: 'unknown' is not a command for 'test pr'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          test pr --help
+        description: "Suggested command:"
+        commands[1]{command,description}:
+          test pr --help,see all available commands
       "
     `)
   })
@@ -892,8 +1569,8 @@ describe('subcommands', () => {
     expect(output).toMatchInlineSnapshot(`
       "Error: 'unknown' is not a command for 'test pr'.
 
-      See available commands:
-        test pr --help
+      Suggested command:
+        test pr --help  # see all available commands
       "
     `)
   })
@@ -919,13 +1596,13 @@ describe('subcommands', () => {
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
-        --verbose                           Show full output envelope
       "
     `)
   })
@@ -1008,7 +1685,7 @@ describe('cta', () => {
       },
     })
 
-    const { output } = await serve(cli, ['list', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['list', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta).toEqual({
       description: 'Suggested commands:',
@@ -1029,7 +1706,7 @@ describe('cta', () => {
       },
     })
 
-    const { output } = await serve(cli, ['list', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['list', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta.commands).toEqual([
       { command: 'test get 1', description: 'View item 1' },
@@ -1058,7 +1735,7 @@ describe('cta', () => {
       },
     })
 
-    const { output } = await serve(cli, ['create', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['create', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta.commands).toEqual([
       { command: 'test get 1 --limit 10', description: 'View the item' },
@@ -1078,7 +1755,7 @@ describe('cta', () => {
       },
     })
 
-    const { output } = await serve(cli, ['list', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['list', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta.commands).toEqual([{ command: 'test get <id> --format <format>' }])
   })
@@ -1096,7 +1773,7 @@ describe('cta', () => {
       },
     })
 
-    const { output } = await serve(cli, ['create', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['create', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta.description).toBe('View the created item:')
   })
@@ -1105,7 +1782,7 @@ describe('cta', () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({ pong: true }) })
 
-    const { output } = await serve(cli, ['ping', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['ping', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta).toBeUndefined()
   })
@@ -1118,7 +1795,7 @@ describe('cta', () => {
       },
     })
 
-    const { output } = await serve(cli, ['noop', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['noop', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta).toBeUndefined()
   })
@@ -1138,7 +1815,7 @@ describe('cta', () => {
       },
     })
 
-    const { output, exitCode } = await serve(cli, ['fail', '--verbose', '--format', 'json'])
+    const { output, exitCode } = await serve(cli, ['fail', '--full-output', '--format', 'json'])
     expect(exitCode).toBe(1)
     const parsed = JSON.parse(output)
     expect(parsed.ok).toBe(false)
@@ -1156,7 +1833,7 @@ describe('cta', () => {
       },
     })
 
-    const { output, exitCode } = await serve(cli, ['fail', '--verbose', '--format', 'json'])
+    const { output, exitCode } = await serve(cli, ['fail', '--full-output', '--format', 'json'])
     expect(exitCode).toBe(1)
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta).toBeUndefined()
@@ -1170,7 +1847,7 @@ describe('cta', () => {
       },
     })
 
-    const { output } = await serve(cli, ['fail', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['fail', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.ok).toBe(false)
     expect(parsed.meta.cta).toBeUndefined()
@@ -1192,10 +1869,17 @@ describe('cta', () => {
     })
     cli.command(pr)
 
-    const { output } = await serve(cli, ['pr', 'create', 'my-pr', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, [
+      'pr',
+      'create',
+      'my-pr',
+      '--full-output',
+      '--format',
+      'json',
+    ])
     const parsed = JSON.parse(output)
     expect(parsed.meta.cta).toEqual({
-      description: 'Suggested commands:',
+      description: 'Suggested command:',
       commands: [{ command: 'test pr get 42', description: 'View the PR' }],
     })
   })
@@ -1232,9 +1916,25 @@ describe('leaf cli', () => {
     `)
   })
 
-  test('--verbose outputs full envelope', async () => {
-    const cli = Cli.create('ping', { run: () => ({ pong: true }) })
+  test('command option named verbose is parsed by the command', async () => {
+    const cli = Cli.create('ping', {
+      options: z.object({ verbose: z.boolean().default(false) }),
+      run({ options }) {
+        return options
+      },
+    })
+
     const { output } = await serve(cli, ['--verbose'])
+
+    expect(output).toMatchInlineSnapshot(`
+      "verbose: true
+      "
+    `)
+  })
+
+  test('--full-output outputs full envelope', async () => {
+    const cli = Cli.create('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['--full-output'])
     expect(output).toMatchInlineSnapshot(`
       "ok: true
       data:
@@ -1350,22 +2050,22 @@ describe('help', () => {
       Commands:
         ping  Health check
 
-      Built-in Commands:
+      Integrations:
         completions  Generate shell completion script
-        mcp add      Register as an MCP server
-        skills add   Sync skill files to your agent
+        mcp add      Register as MCP server
+        skills       Sync skill files to agents (add, list)
 
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
-        --verbose                           Show full output envelope
         --version                           Show version
       "
     `)
@@ -1388,22 +2088,22 @@ describe('help', () => {
       Commands:
         ping  Health check
 
-      Built-in Commands:
+      Integrations:
         completions  Generate shell completion script
-        mcp add      Register as an MCP server
-        skills add   Sync skill files to your agent
+        mcp add      Register as MCP server
+        skills       Sync skill files to agents (add, list)
 
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
-        --verbose                           Show full output envelope
         --version                           Show version
       "
     `)
@@ -1430,13 +2130,13 @@ describe('help', () => {
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
-        --verbose                           Show full output envelope
       "
     `)
   })
@@ -1464,13 +2164,13 @@ describe('help', () => {
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
-        --verbose                           Show full output envelope
       "
     `)
   })
@@ -1551,22 +2251,22 @@ describe('help', () => {
       Commands:
         ping  Ping
 
-      Built-in Commands:
+      Integrations:
         completions  Generate shell completion script
-        mcp add      Register as an MCP server
-        skills add   Sync skill files to your agent
+        mcp add      Register as MCP server
+        skills       Sync skill files to agents (add, list)
 
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
-        --verbose                           Show full output envelope
         --version                           Show version
       "
     `)
@@ -1591,13 +2291,13 @@ describe('help', () => {
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
-        --verbose                           Show full output envelope
       "
     `)
   })
@@ -1686,13 +2386,13 @@ describe('env', () => {
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
-        --verbose                           Show full output envelope
 
       Environment Variables:
         API_TOKEN  Auth token
@@ -1724,16 +2424,16 @@ describe('env', () => {
         Global Options:
           --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
           --format <toon|json|yaml|md|jsonl>  Output format
+          --full-output                       Show full output envelope
           --help                              Show help
           --llms, --llms-full                 Print LLM-readable manifest
-          --schema                            Show JSON Schema for a command
+          --schema                            Show JSON Schema for command
           --token-count                       Print token count of output (instead of output)
           --token-limit <n>                   Limit output to n tokens
           --token-offset <n>                  Skip first n tokens of output
-          --verbose                           Show full output envelope
 
         Environment Variables:
-          API_TOKEN  Auth token (set: ••••ret)
+          API_TOKEN  Auth token (set: ****cret)
           API_URL    API URL (default: https://api.example.com)
         "
       `)
@@ -1742,7 +2442,7 @@ describe('env', () => {
       process.env.API_URL = 'https://custom.example.com'
       const { output: output2 } = await serve(cli, ['deploy', '--help'])
       expect(output2).toContain(
-        'API_URL    API URL (set: ••••com, default: https://api.example.com)',
+        'API_URL    API URL (set: ****.com, default: https://api.example.com)',
       )
     } finally {
       delete process.env.API_TOKEN
@@ -1770,7 +2470,7 @@ describe('env', () => {
     const { output: output2 } = await serve(cli, ['deploy', '--help'], {
       env: { API_TOKEN: 'secret' },
     })
-    expect(output2).toContain('set: ••••ret')
+    expect(output2).toContain('set: ****cret')
   })
 
   test('--llms json includes schema.env', async () => {
@@ -1838,6 +2538,114 @@ describe('env', () => {
   })
 })
 
+describe('built-in commands', () => {
+  test('bare completions shows help', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['completions'])
+    expect(output).toContain('Generate shell completion script')
+  })
+
+  test('completions --help shows help', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['completions', '--help'])
+    expect(output).toContain('test completions')
+    expect(output).toContain('Generate shell completion script')
+  })
+
+  test('bare mcp shows help with subcommands', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['mcp'])
+    expect(output).toContain('test mcp')
+    expect(output).toContain('Register as MCP server')
+    expect(output).toContain('add')
+  })
+
+  test('mcp --help shows help with subcommands', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['mcp', '--help'])
+    expect(output).toContain('test mcp')
+    expect(output).toContain('add')
+  })
+
+  test('mcp add --help shows options', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['mcp', 'add', '--help'])
+    expect(output).toContain('test mcp add')
+    expect(output).toContain('--command')
+    expect(output).toContain('--no-global')
+    expect(output).toContain('--agent')
+  })
+
+  test('bare skills shows help with subcommands', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['skills'])
+    expect(output).toContain('test skills')
+    expect(output).toContain('Sync skill files to agents')
+    expect(output).toContain('add')
+  })
+
+  test('skills --help shows help with subcommands', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['skills', '--help'])
+    expect(output).toContain('test skills')
+    expect(output).toContain('add')
+  })
+
+  test('skills typo suggests add', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({}) })
+    const { output, exitCode } = await serve(cli, ['skills', 'addd'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Did you mean 'add'?")
+    expect(output).toContain('test skills add')
+    expect(output).toContain('test skills --help')
+  })
+
+  test('mcp typo suggests add', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({}) })
+    const { output, exitCode } = await serve(cli, ['mcp', 'addd'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Did you mean 'add'?")
+    expect(output).toContain('test mcp add')
+  })
+
+  test('skills add --help shows options', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['skills', 'add', '--help'])
+    expect(output).toContain('test skills add')
+    expect(output).toContain('--depth')
+    expect(output).toContain('--no-global')
+  })
+
+  test('skills list --help shows description', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['skills', 'list', '--help'])
+    expect(output).toContain('test skills list')
+    expect(output).toContain('List skills')
+  })
+
+  test('skills list shows skills with install status', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
+    cli.command('greet', { description: 'Say hello', run: () => ({ hi: true }) })
+    const { output } = await serve(cli, ['skills', 'list'])
+    expect(output).toContain('✗')
+    expect(output).toContain('test-ping')
+    expect(output).toContain('test-greet')
+    expect(output).toContain('installed')
+  })
+})
+
 describe('skills staleness', () => {
   let stderrSpy: ReturnType<typeof vi.spyOn>
 
@@ -1848,15 +2656,57 @@ describe('skills staleness', () => {
 
   afterEach(() => {
     stderrSpy.mockRestore()
+    __mockSkillsHash = undefined
   })
 
-  test('warns on stderr when skills are stale', async () => {
+  test('includes skills CTA when stale', async () => {
     __mockSkillsHash = '0000000000000000'
     const cli = Cli.create('test')
     cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
 
-    await serve(cli, ['ping'])
-    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining("Skills are out of date. Run '"))
+    const { output } = await serve(cli, ['ping'])
+    expect(output).toContain('Skills are out of date:')
+    expect(output).toContain('skills add')
+  })
+
+  test('uses displayName for stale skills CTA when invoked directly', async () => {
+    const savedArgv1 = process.argv[1]
+    const savedAgent = process.env.npm_config_user_agent
+    const savedExec = process.env.npm_execpath
+    try {
+      process.argv[1] = '/usr/local/bin/mc'
+      delete process.env.npm_config_user_agent
+      delete process.env.npm_execpath
+
+      __mockSkillsHash = '0000000000000000'
+      const cli = Cli.create({ name: 'my-cli', aliases: ['mc'] })
+      cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
+
+      const { output } = await serve(cli, ['ping'])
+
+      expect(output).toContain('mc skills add')
+      expect(output).not.toContain('npx my-cli skills add')
+    } finally {
+      if (savedArgv1 === undefined) process.argv[1] = undefined as any
+      else process.argv[1] = savedArgv1
+      process.env.npm_config_user_agent = savedAgent
+      process.env.npm_execpath = savedExec
+    }
+  })
+
+  test('merges skills CTA with command CTA', async () => {
+    __mockSkillsHash = '0000000000000000'
+    ;(process.stdout as any).isTTY = true
+    const cli = Cli.create('test')
+    cli.command('ping', {
+      description: 'Health check',
+      run: (c) => c.ok({ pong: true }, { cta: { commands: ['status'] } }),
+    })
+
+    const { output } = await serve(cli, ['ping'])
+    ;(process.stdout as any).isTTY = false
+    expect(output).toContain('status')
+    expect(output).toContain('skills add')
   })
 
   test('does not warn when hash matches', async () => {
@@ -1865,8 +2715,8 @@ describe('skills staleness', () => {
     const cli = Cli.create('test')
     cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
 
-    await serve(cli, ['ping'])
-    expect(stderrSpy).not.toHaveBeenCalled()
+    const { output } = await serve(cli, ['ping'])
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('does not warn when no hash stored', async () => {
@@ -1874,8 +2724,8 @@ describe('skills staleness', () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({ pong: true }) })
 
-    await serve(cli, ['ping'])
-    expect(stderrSpy).not.toHaveBeenCalled()
+    const { output } = await serve(cli, ['ping'])
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('does not warn for skills add', async () => {
@@ -1892,8 +2742,8 @@ describe('skills staleness', () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({ pong: true }) })
 
-    await serve(cli, ['--help'])
-    expect(stderrSpy).not.toHaveBeenCalled()
+    const { output } = await serve(cli, ['--help'])
+    expect(output).not.toContain('Skills are out of date')
   })
 })
 
@@ -2114,10 +2964,10 @@ describe('outputPolicy', () => {
     expect(deploy.output).not.toContain('deploy-123')
     expect(deploy.output).toContain('Check status')
 
-    // deploy --verbose: agent mode shows everything
-    const deployVerbose = await serve(cli, ['deploy', 'staging', '--verbose'])
-    expect(deployVerbose.output).toContain('deploy-123')
-    expect(deployVerbose.output).toContain('staging.example.com')
+    // deploy --full-output: agent mode shows everything
+    const deployFullOutput = await serve(cli, ['deploy', 'staging', '--full-output'])
+    expect(deployFullOutput.output).toContain('deploy-123')
+    expect(deployFullOutput.output).toContain('staging.example.com')
 
     // deploy --json: agent mode shows data
     const deployJson = await serve(cli, ['deploy', 'staging', '--json'])
@@ -2270,24 +3120,6 @@ describe('outputPolicy', () => {
     expect(capturedEnv).toEqual({ API_TOKEN: 'secret-123', API_URL: 'https://api.example.com' })
   })
 
-  test('e2e: middleware receives parsed CLI-level options', async () => {
-    let capturedOptions: any
-    const cli = Cli.create('test', {
-      options: z.object({
-        token: z.string().default(''),
-        dry: z.boolean().default(false),
-      }),
-    })
-      .use(async (c, next) => {
-        capturedOptions = c.options
-        await next()
-      })
-      .command('deploy', { run: () => ({ ok: true }) })
-
-    await serve(cli, ['deploy', '--token', 'abc123', '--dry'])
-    expect(capturedOptions).toEqual({ token: 'abc123', dry: true })
-  })
-
   test('e2e: CLI-level env validation error before middleware runs', async () => {
     const cli = Cli.create('test', {
       env: z.object({ API_TOKEN: z.string() }),
@@ -2891,11 +3723,11 @@ describe('fetch', async () => {
     expect(JSON.parse(output)).toEqual({ ok: true })
   })
 
-  test('--verbose includes request/response meta', async () => {
+  test('--full-output includes request/response meta', async () => {
     const cli = Cli.create('test', { description: 'test' }).command('api', {
       fetch: app.fetch,
     })
-    const { output } = await serve(cli, ['api', 'health', '--verbose', '--format', 'json'])
+    const { output } = await serve(cli, ['api', 'health', '--full-output', '--format', 'json'])
     const parsed = JSON.parse(output)
     expect(parsed.ok).toBe(true)
     expect(parsed.data).toEqual({ ok: true })
@@ -2923,6 +3755,15 @@ describe('fetch', async () => {
     `)
   })
 
+  test('root-level fetch with typo of known command → did you mean', async () => {
+    const cli = Cli.create('api', { description: 'API', fetch: app.fetch }).command('upgrade', {
+      run: () => ({ upgraded: true }),
+    })
+    const { output, exitCode } = await serve(cli, ['upgra'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Did you mean 'upgrade'?")
+  })
+
   test('root-level fetch with no args → root path', async () => {
     const cli = Cli.create('api', { description: 'API', fetch: app.fetch })
     // Hono returns 404 for / since we don't have a root route
@@ -3105,6 +3946,14 @@ describe('fetch', () => {
     `)
   })
 
+  test('GET /helath → 404 with suggestion', async () => {
+    const cli = Cli.create('test')
+    cli.command('health', { run: () => ({}) })
+    const res = await fetchJson(cli, new Request('http://localhost/helath'))
+    expect(res.status).toBe(404)
+    expect(res.body.error.message).toContain("Did you mean 'health'?")
+  })
+
   test('GET / with root command → 200', async () => {
     const cli = Cli.create('test', { run: () => ({ root: true }) })
     expect(await fetchJson(cli, new Request('http://localhost/'))).toMatchInlineSnapshot(`
@@ -3393,6 +4242,84 @@ describe('fetch', () => {
     `)
   })
 
+  test('group middleware runs for nested commands', async () => {
+    const sub = Cli.create('admin', {
+      vars: z.object({ role: z.string().default('none') }),
+    })
+    sub.use(async (c, next) => {
+      c.set('role', 'admin')
+      await next()
+    })
+    sub.command('status', {
+      run: (c) => ({ role: c.var.role }),
+    })
+    const cli = Cli.create('test', {
+      vars: z.object({ role: z.string().default('none') }),
+    })
+    cli.command(sub)
+    expect(await fetchJson(cli, new Request('http://localhost/admin/status')))
+      .toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "role": "admin",
+          },
+          "meta": {
+            "command": "admin status",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('cli-level env schema is parsed', async () => {
+    const cli = Cli.create('test', {
+      env: z.object({ APP_TOKEN: z.string().default('fallback') }),
+    })
+    cli.use(async (c, next) => {
+      // env should be parsed from envSchema
+      ;(globalThis as any).__testEnv = c.env
+      await next()
+    })
+    cli.command('check', { run: () => ({ ok: true }) })
+    await cli.fetch(new Request('http://localhost/check'))
+    expect((globalThis as any).__testEnv).toEqual({ APP_TOKEN: 'fallback' })
+    delete (globalThis as any).__testEnv
+  })
+
+  test('retryable error is propagated', async () => {
+    const cli = Cli.create('test')
+    cli.command('rate-limit', {
+      run: (c) => c.error({ code: 'RATE_LIMITED', message: 'slow down', retryable: true }),
+    })
+    const { body } = await fetchJson(cli, new Request('http://localhost/rate-limit'))
+    expect(body.ok).toBe(false)
+    expect(body.error.retryable).toBe(true)
+  })
+
+  test('cta block is propagated', async () => {
+    const cli = Cli.create('test')
+    cli.command('done', {
+      run: (c) =>
+        c.ok({ id: 1 }, { cta: { commands: ['list'], description: 'Suggested commands:' } }),
+    })
+    const { body } = await fetchJson(cli, new Request('http://localhost/done'))
+    expect(body.ok).toBe(true)
+    expect(body.meta.cta).toMatchInlineSnapshot(`
+      {
+        "commands": [
+          {
+            "command": "test list",
+          },
+        ],
+        "description": "Suggested commands:",
+      }
+    `)
+  })
+
   describe('mcp over http', () => {
     function mcpCli() {
       const cli = Cli.create('test', { version: '1.0.0' })
@@ -3539,3 +4466,189 @@ describe('fetch', () => {
     })
   })
 })
+
+describe('displayName', () => {
+  beforeEach(() => {
+    const savedArgv1 = process.argv[1]
+    return () => {
+      process.argv[1] = savedArgv1!
+    }
+  })
+
+  test('defaults to name when argv[1] is not an alias', async () => {
+    process.argv[1] = '/usr/local/bin/my-cli'
+    const cli = Cli.create({
+      name: 'my-cli',
+      aliases: ['mc'],
+    }).command('ping', {
+      run: (c) => c.ok({ displayName: c.displayName }),
+    })
+    const { output } = await serve(cli, ['ping', '--json'])
+    expect(JSON.parse(output).displayName).toBe('my-cli')
+  })
+
+  test('resolves alias from argv[1]', async () => {
+    process.argv[1] = '/usr/local/bin/mc'
+    const cli = Cli.create({
+      name: 'my-cli',
+      aliases: ['mc'],
+    }).command('ping', {
+      run: (c) => c.ok({ displayName: c.displayName }),
+    })
+    const { output } = await serve(cli, ['ping', '--json'])
+    expect(JSON.parse(output).displayName).toBe('mc')
+  })
+
+  test('falls back to name when argv[1] is undefined', async () => {
+    process.argv[1] = undefined as any
+    const cli = Cli.create({
+      name: 'my-cli',
+      aliases: ['mc'],
+    }).command('ping', {
+      run: (c) => c.ok({ displayName: c.displayName }),
+    })
+    const { output } = await serve(cli, ['ping', '--json'])
+    expect(JSON.parse(output).displayName).toBe('my-cli')
+  })
+
+  test('available in middleware context', async () => {
+    process.argv[1] = '/usr/local/bin/mc'
+    let middlewareDisplayName: string | undefined
+    const cli = Cli.create({
+      name: 'my-cli',
+      aliases: ['mc'],
+    })
+      .use((c, next) => {
+        middlewareDisplayName = c.displayName
+        return next()
+      })
+      .command('ping', {
+        run: (c) => c.ok({ ok: true }),
+      })
+    await serve(cli, ['ping', '--json'])
+    expect(middlewareDisplayName).toBe('mc')
+  })
+
+  test('available in root run context', async () => {
+    process.argv[1] = '/usr/local/bin/mc'
+    const cli = Cli.create({
+      name: 'my-cli',
+      aliases: ['mc'],
+      run: (c) => c.ok({ displayName: c.displayName }),
+    })
+    const { output } = await serve(cli, ['--json'])
+    expect(JSON.parse(output).displayName).toBe('mc')
+  })
+
+  test('cta commands use displayName', async () => {
+    process.argv[1] = '/usr/local/bin/mc'
+    const cli = Cli.create({
+      name: 'my-cli',
+      aliases: ['mc'],
+    }).command('ping', {
+      run: (c) => c.ok({ ok: true }, { cta: { commands: ['login'] } }),
+    })
+    const { output } = await serve(cli, ['ping', '--json', '--full-output'])
+    const parsed = JSON.parse(output)
+    expect(parsed.meta.cta.commands[0].command).toBe('mc login')
+  })
+})
+
+test('--format rejects invalid format values', async () => {
+  const cli = Cli.create('test').command('hello', {
+    run: (c) => c.ok({ message: 'hi' }),
+  })
+
+  const { exitCode, output } = await serve(cli, ['hello', '--format', 'xml'])
+  expect(exitCode).toBe(1)
+  expect(output).toMatch(/invalid|unsupported|unknown.*format/i)
+})
+
+test('--token-limit with non-numeric value errors', async () => {
+  const cli = Cli.create('test').command('hello', {
+    run: (c) => c.ok({ message: 'hello world' }),
+  })
+
+  const { exitCode, output } = await serve(cli, ['hello', '--token-limit', 'foo', '--json'])
+  expect(exitCode).toBe(1)
+  expect(output).not.toContain('NaN')
+})
+
+test('--token-offset with non-numeric value errors', async () => {
+  const cli = Cli.create('test').command('hello', {
+    run: (c) => c.ok({ message: 'hello world' }),
+  })
+
+  const { exitCode, output } = await serve(cli, ['hello', '--token-offset', 'foo', '--json'])
+  expect(exitCode).toBe(1)
+  expect(output).not.toContain('NaN')
+})
+
+describe('command aliases', () => {
+  function makeAliasedCli() {
+    return Cli.create('gh').command('extension', {
+      aliases: ['extensions', 'ext'],
+      description: 'Manage extensions',
+      run: () => ({ result: 'ok' }),
+    })
+  }
+
+  test('resolves canonical command name', async () => {
+    const { output } = await serve(makeAliasedCli(), ['extension'])
+    expect(output).toContain('ok')
+  })
+
+  test('resolves alias name', async () => {
+    const { output } = await serve(makeAliasedCli(), ['extensions'])
+    expect(output).toContain('ok')
+  })
+
+  test('resolves short alias name', async () => {
+    const { output } = await serve(makeAliasedCli(), ['ext'])
+    expect(output).toContain('ok')
+  })
+
+  test('root help does not show aliases', async () => {
+    const { output } = await serve(makeAliasedCli(), ['--help'])
+    const commandsSection = output.split('Commands:')[1]!.split('Integrations:')[0]!
+    const names = commandsSection
+      .trim()
+      .split('\n')
+      .map((l) => l.trim().split(/\s{2,}/)[0]!)
+    expect(names).toContain('extension')
+    expect(names).not.toContain('extensions')
+    expect(names).not.toContain('ext')
+  })
+
+  test('command help shows aliases line', async () => {
+    const { output } = await serve(makeAliasedCli(), ['extension', '--help'])
+    expect(output).toContain('Aliases: extensions, ext')
+  })
+
+  test('aliases work inside command groups', async () => {
+    const sub = Cli.create('repo', { description: 'Manage repos' }).command('list', {
+      aliases: ['ls'],
+      description: 'List repos',
+      run: () => ({ repos: [] }),
+    })
+    const cli = Cli.create('gh').command(sub)
+    const { output } = await serve(cli, ['repo', 'ls'])
+    expect(output).toContain('repos')
+  })
+
+  test('did-you-mean suggests aliases', async () => {
+    const { output } = await serve(makeAliasedCli(), ['exten'])
+    expect(output).toMatch(/did you mean.*extension/i)
+  })
+
+  test('root CLI aliases register as command aliases', async () => {
+    const update = Cli.create('update', {
+      aliases: ['upgrade'],
+      description: 'Update packages',
+      run: () => ({ result: 'updated' }),
+    })
+    const cli = Cli.create('pkg').command(update)
+    const { output } = await serve(cli, ['upgrade'])
+    expect(output).toContain('updated')
+  })
+})