incur 0.3.6 → 0.3.8

package/src/Cli.test.ts

@@ -691,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
       "
     `)
   })
@@ -708,8 +708,8 @@ 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
       "
     `)
   })
@@ -727,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', '--verbose'])
+    expect(output).toContain('test deploy --verbose')
+  })
+
+  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', {
@@ -1289,6 +1375,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', {
@@ -1422,9 +1516,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
       "
     `)
   })
@@ -1443,8 +1537,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
       "
     `)
   })
@@ -1746,7 +1840,7 @@ describe('cta', () => {
     const { output } = await serve(cli, ['pr', 'create', 'my-pr', '--verbose', '--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' }],
     })
   })
@@ -2449,6 +2543,25 @@ describe('built-in commands', () => {
     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 }) })
@@ -2469,15 +2582,32 @@ 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('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 () => {
@@ -2486,8 +2616,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 () => {
@@ -2495,8 +2625,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 () => {
@@ -2513,8 +2643,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')
   })
 })
 
@@ -3708,6 +3838,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(`
@@ -4057,7 +4195,7 @@ describe('fetch', () => {
   test('cta block is propagated', async () => {
     const cli = Cli.create('test')
     cli.command('done', {
-      run: (c) => c.ok({ id: 1 }, { cta: { commands: ['list'], description: 'Next steps:' } }),
+      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)
@@ -4068,7 +4206,7 @@ describe('fetch', () => {
             "command": "test list",
           },
         ],
-        "description": "Next steps:",
+        "description": "Suggested commands:",
       }
     `)
   })

package/src/Cli.ts

@@ -13,7 +13,7 @@ import * as Formatter from './Formatter.js'
 import * as Help from './Help.js'
 import { builtinCommands, type CommandMeta, type Shell, shells } from './internal/command.js'
 import * as Command from './internal/command.js'
-import { isRecord } from './internal/helpers.js'
+import { isRecord, suggest } from './internal/helpers.js'
 import { detectRunner } from './internal/pm.js'
 import type { OneOf } from './internal/types.js'
 import * as Mcp from './Mcp.js'
@@ -541,6 +541,7 @@ async function serveImpl(
   }
 
   // Skills staleness check (skip for built-in commands)
+  let skillsCta: FormattedCtaBlock | undefined
   if (!llms && !llmsFull && !schema && !help && !version) {
     const isSkillsAdd =
       filtered[0] === 'skills' || (filtered[0] === name && filtered[1] === 'skills')
@@ -553,9 +554,10 @@ async function serveImpl(
         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`,
-          )
+          skillsCta = {
+            description: 'Skills are out of date:',
+            commands: [{ command: `${runner} ${spec} skills add`, description: 'sync outdated skills' }],
+          }
         }
       }
     }
@@ -646,7 +648,26 @@ async function serveImpl(
   const skillsIdx =
     filtered[0] === 'skills' ? 0 : filtered[0] === name && filtered[1] === 'skills' ? 1 : -1
   if (skillsIdx !== -1 && filtered[skillsIdx] === 'skills') {
-    if (filtered[skillsIdx + 1] !== 'add') {
+    const skillsSub = filtered[skillsIdx + 1]
+    if (skillsSub && skillsSub !== 'add') {
+      const suggestion = suggest(skillsSub, ['add'])
+      const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
+      const message = `'${skillsSub}' is not a command for '${name} skills'.${didYouMean}`
+      const ctaCommands: FormattedCta[] = []
+      if (suggestion) {
+        const corrected = argv.map((t) => (t === skillsSub ? suggestion : t))
+        ctaCommands.push({ command: `${name} ${corrected.join(' ')}` })
+      }
+      ctaCommands.push({ command: `${name} skills --help`, description: 'see all available commands' })
+      const cta: FormattedCtaBlock = { description: ctaCommands.length === 1 ? 'Suggested command:' : 'Suggested commands:', commands: ctaCommands }
+      if (human) {
+        writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }))
+        writeln(formatHumanCta(cta))
+      } else writeln(Formatter.format({ code: 'COMMAND_NOT_FOUND', message, cta }, 'toon'))
+      exit(1)
+      return
+    }
+    if (!skillsSub) {
       const b = builtinCommands.find((c) => c.name === 'skills')!
       writeln(formatBuiltinHelp(name, b))
       return
@@ -718,7 +739,26 @@ async function serveImpl(
   // mcp add: register CLI as MCP server via `npx add-mcp`
   const mcpIdx = filtered[0] === 'mcp' ? 0 : filtered[0] === name && filtered[1] === 'mcp' ? 1 : -1
   if (mcpIdx !== -1 && filtered[mcpIdx] === 'mcp') {
-    if (filtered[mcpIdx + 1] !== 'add') {
+    const mcpSub = filtered[mcpIdx + 1]
+    if (mcpSub && mcpSub !== 'add') {
+      const suggestion = suggest(mcpSub, ['add'])
+      const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
+      const message = `'${mcpSub}' is not a command for '${name} mcp'.${didYouMean}`
+      const ctaCommands: FormattedCta[] = []
+      if (suggestion) {
+        const corrected = argv.map((t) => (t === mcpSub ? suggestion : t))
+        ctaCommands.push({ command: `${name} ${corrected.join(' ')}` })
+      }
+      ctaCommands.push({ command: `${name} mcp --help`, description: 'see all available commands' })
+      const cta: FormattedCtaBlock = { description: ctaCommands.length === 1 ? 'Suggested command:' : 'Suggested commands:', commands: ctaCommands }
+      if (human) {
+        writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }))
+        writeln(formatHumanCta(cta))
+      } else writeln(Formatter.format({ code: 'COMMAND_NOT_FOUND', message, cta }, 'toon'))
+      exit(1)
+      return
+    }
+    if (!mcpSub) {
       const b = builtinCommands.find((c) => c.name === 'mcp')!
       writeln(formatBuiltinHelp(name, b))
       return
@@ -938,7 +978,9 @@ async function serveImpl(
     }
     if ('error' in resolved) {
       const parent = resolved.path ? `${name} ${resolved.path}` : name
-      writeln(`Error: '${resolved.error}' is not a command for '${parent}'.`)
+      const suggestion = suggest(resolved.error, resolved.commands.keys())
+      const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
+      writeln(`Error: '${resolved.error}' is not a command for '${parent}'.${didYouMean}`)
       exit(1)
       return
     }
@@ -1022,6 +1064,21 @@ async function serveImpl(
   function write(output: Output) {
     if (filterPaths && output.ok && output.data != null)
       output = { ...output, data: Filter.apply(output.data, filterPaths) }
+    if (skillsCta) {
+      const existing = output.meta.cta
+      output = {
+        ...output,
+        meta: {
+          ...output.meta,
+          cta: existing
+            ? {
+                description: existing.description,
+                commands: [...existing.commands, ...skillsCta.commands],
+              }
+            : skillsCta,
+        },
+      }
+    }
     if (tokenCount) {
       const base = output.ok ? output.data : output.error
       const formatted = base != null ? Formatter.format(base, format) : ''
@@ -1072,14 +1129,24 @@ async function serveImpl(
   if ('error' in effective) {
     const helpCmd = effective.path ? `${name} ${effective.path} --help` : `${name} --help`
     const parent = effective.path ? `${name} ${effective.path}` : name
-    const message = `'${effective.error}' is not a command for '${parent}'.`
-    const cta: FormattedCtaBlock = {
-      description: 'See available commands:',
-      commands: [{ command: helpCmd }],
+    const candidates = 'commands' in effective ? [...effective.commands.keys()] : []
+    if (!effective.path) for (const b of builtinCommands) candidates.push(b.name)
+    const suggestion = suggest(effective.error, candidates)
+    const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
+    const message = `'${effective.error}' is not a command for '${parent}'.${didYouMean}`
+    const ctaCommands: FormattedCta[] = []
+    if (suggestion) {
+      const corrected = argv.map((t) => (t === effective.error ? suggestion : t))
+      ctaCommands.push({ command: `${name} ${corrected.join(' ')}` })
     }
+    ctaCommands.push({ command: helpCmd, description: 'see all available commands' })
+    const cta: FormattedCtaBlock = { description: ctaCommands.length === 1 ? 'Suggested command:' : 'Suggested commands:', commands: ctaCommands }
     if (human && !verbose) {
       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
     }
@@ -1544,18 +1611,22 @@ async function fetchImpl(
 
   const resolved = resolveCommand(commands, segments)
 
-  if ('error' in resolved)
+  if ('error' in resolved) {
+    const parent = resolved.path ? `${name} ${resolved.path}` : name
+    const suggestion = suggest(resolved.error, resolved.commands.keys())
+    const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : ''
     return jsonResponse(
       {
         ok: false,
         error: {
           code: 'COMMAND_NOT_FOUND',
-          message: `'${resolved.error}' is not a command for '${resolved.path ? `${name} ${resolved.path}` : name}'.`,
+          message: `'${resolved.error}' is not a command for '${parent}'.${didYouMean}`,
         },
         meta: { command: resolved.error, duration: `${Math.round(performance.now() - start)}ms` },
       },
       404,
     )
+  }
 
   if ('help' in resolved)
     return jsonResponse(
@@ -1754,10 +1825,10 @@ function resolveCommand(
       description?: string | undefined
       commands: Map<string, CommandEntry>
     }
-  | { error: string; path: string } {
+  | { error: string; path: string; commands: Map<string, CommandEntry>; rest: string[] } {
   const [first, ...rest] = tokens
 
-  if (!first || !commands.has(first)) return { error: first ?? '(none)', path: '' }
+  if (!first || !commands.has(first)) return { error: first ?? '(none)', path: '', commands, rest }
 
   let entry = commands.get(first)!
   const path = [first]
@@ -1791,7 +1862,7 @@ function resolveCommand(
 
     const child = entry.commands.get(next)
     if (!child) {
-      return { error: next, path: path.join(' ') }
+      return { error: next, path: path.join(' '), commands: entry.commands, rest: remaining.slice(1) }
     }
 
     path.push(next)
@@ -2237,7 +2308,7 @@ type ErrorResult = {
 type CtaBlock<commands extends CommandsMap = Commands> = {
   /** Commands to suggest. */
   commands: Cta<commands>[]
-  /** Human-readable label. Defaults to `"Suggested commands:"`. */
+  /** Human-readable label. Defaults to `"Suggested command:"` or `"Suggested commands:"` based on count. */
   description?: string | undefined
 }
 
@@ -2481,7 +2552,7 @@ async function handleStreaming(
 function formatCtaBlock(name: string, block: CtaBlock | undefined): FormattedCtaBlock | undefined {
   if (!block || block.commands.length === 0) return undefined
   return {
-    description: block.description ?? 'Suggested commands:',
+    description: block.description ?? (block.commands.length === 1 ? 'Suggested command:' : 'Suggested commands:'),
     commands: block.commands.map((c) => formatCta(name, c)),
   }
 }

package/src/Help.ts

@@ -389,6 +389,6 @@ function globalOptionsLines(root = false, configFlag?: string): string[] {
 
 /** Redacts a value, showing only the last 4 characters. */
 function redact(value: string): string {
-  if (value.length <= 4) return '****'
+  if (value.length <= 4) return `****${value.slice(-1)}`
   return `****${value.slice(-4)}`
 }

package/src/Openapi.test.ts

@@ -1,4 +1,9 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test, vi } from 'vitest'
+
+vi.mock('./SyncSkills.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./SyncSkills.js')>()
+  return { ...actual, readHash: () => undefined }
+})
 
 import { app as prefixedApp } from '../test/fixtures/hono-api-prefixed.js'
 import { app } from '../test/fixtures/hono-api.js'

package/src/e2e.test.ts

@@ -70,9 +70,9 @@ describe('routing', () => {
       "code: COMMAND_NOT_FOUND
       message: 'nonexistent' is not a command for 'app'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          app --help
+        description: "Suggested command:"
+        commands[1]{command,description}:
+          app --help,see all available commands
       "
     `)
   })
@@ -85,8 +85,8 @@ describe('routing', () => {
     expect(output).toMatchInlineSnapshot(`
       "Error: 'nonexistent' is not a command for 'app'.
 
-      See available commands:
-        app --help
+      Suggested command:
+        app --help  # see all available commands
       "
     `)
   })
@@ -98,9 +98,9 @@ describe('routing', () => {
       "code: COMMAND_NOT_FOUND
       message: 'whoami' is not a command for 'app auth'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          app auth --help
+        description: "Suggested command:"
+        commands[1]{command,description}:
+          app auth --help,see all available commands
       "
     `)
   })
@@ -112,9 +112,9 @@ describe('routing', () => {
       "code: COMMAND_NOT_FOUND
       message: 'nope' is not a command for 'app project deploy'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          app project deploy --help
+        description: "Suggested command:"
+        commands[1]{command,description}:
+          app project deploy --help,see all available commands
       "
     `)
   })
@@ -595,7 +595,7 @@ describe('error handling', () => {
                 "command": "app auth login",
               },
             ],
-            "description": "Suggested commands:",
+            "description": "Suggested command:",
           },
           "duration": "<stripped>",
         },
@@ -650,9 +650,10 @@ describe('error handling', () => {
             "commands": [
               {
                 "command": "app --help",
+                "description": "see all available commands",
               },
             ],
-            "description": "See available commands:",
+            "description": "Suggested command:",
           },
           "duration": "<stripped>",
         },
@@ -722,7 +723,7 @@ describe('cta', () => {
             "command": "app auth login",
           },
         ],
-        "description": "Suggested commands:",
+        "description": "Suggested command:",
       }
     `)
   })
@@ -868,7 +869,7 @@ describe('streaming', () => {
             "command": "app ping",
           },
         ],
-        "description": "Suggested commands:",
+        "description": "Suggested command:",
       }
     `)
   })
@@ -877,7 +878,7 @@ describe('streaming', () => {
     const { output } = await serve(createApp(), ['stream-ok'])
     expect(output).toContain('n: 1')
     expect(output).toContain('n: 2')
-    expect(output).toContain('Suggested commands:')
+    expect(output).toContain('Suggested command:')
     expect(output).toContain('app ping')
   })
 
@@ -1786,7 +1787,7 @@ describe('edge cases', () => {
               "description": "View "Alpha"",
             },
           ],
-          "description": "Suggested commands:",
+          "description": "Suggested command:",
         },
         "items": [
           {
@@ -1974,13 +1975,15 @@ describe('skills staleness', () => {
 
   afterEach(() => {
     stderrSpy.mockRestore()
+    __mockSkillsHash = undefined
   })
 
-  test('warns when running a command with stale skills', async () => {
+  test('includes skills CTA when stale', async () => {
     __mockSkillsHash = '0000000000000000'
     const { output } = await serve(createApp(), ['ping'])
     expect(output).toContain('pong: true')
-    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Skills are out of date.'))
+    expect(output).toContain('Skills are out of date:')
+    expect(output).toContain('skills add')
   })
 
   test('no warning when skills hash matches', async () => {
@@ -1991,20 +1994,20 @@ describe('skills staleness', () => {
 
     const { output } = await serve(cli, ['ping'])
     expect(output).toContain('pong: true')
-    expect(stderrSpy).not.toHaveBeenCalled()
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('no warning on first use (no hash stored)', async () => {
     __mockSkillsHash = undefined
     const { output } = await serve(createApp(), ['ping'])
     expect(output).toContain('pong: true')
-    expect(stderrSpy).not.toHaveBeenCalled()
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('no warning for --llms', async () => {
     __mockSkillsHash = '0000000000000000'
-    await serve(createApp(), ['--llms'])
-    expect(stderrSpy).not.toHaveBeenCalled()
+    const { output } = await serve(createApp(), ['--llms'])
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('no warning for --mcp', async () => {