incur 0.2.1 → 0.3.0

package/src/Cli.test.ts

@@ -378,12 +378,12 @@ describe('serve', () => {
   })
 })
 
-describe('--llms', () => {
+describe('--llms-full', () => {
   test('outputs manifest with version and commands', async () => {
     const cli = Cli.create('test')
     cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     const manifest = JSON.parse(output)
     expect(manifest.version).toBe('incur.v1')
     expect(manifest.commands).toHaveLength(1)
@@ -399,7 +399,7 @@ describe('--llms', () => {
       run: ({ args }) => ({ message: `hello ${args.name}` }),
     })
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     const manifest = JSON.parse(output)
     expect(manifest.commands[0].schema.args).toEqual({
       type: 'object',
@@ -423,7 +423,7 @@ describe('--llms', () => {
       run: ({ args }) => ({ message: `hello ${args.name}` }),
     })
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     const manifest = JSON.parse(output)
     expect(manifest.commands[0].schema.output).toEqual({
       type: 'object',
@@ -437,7 +437,7 @@ describe('--llms', () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({ pong: true }) })
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     const manifest = JSON.parse(output)
     expect(manifest.commands[0].schema).toBeUndefined()
   })
@@ -457,7 +457,7 @@ describe('--llms', () => {
       })
     cli.command(pr)
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     const manifest = JSON.parse(output)
     expect(manifest.commands).toHaveLength(2)
     expect(manifest.commands[0].name).toBe('pr create')
@@ -474,7 +474,7 @@ describe('--llms', () => {
     pr.command(review)
     cli.command(pr)
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     const manifest = JSON.parse(output)
     expect(manifest.commands[0].name).toBe('pr review approve')
     expect(manifest.commands[0].description).toBe('Approve a review')
@@ -484,7 +484,7 @@ describe('--llms', () => {
     const cli = Cli.create('test')
     cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
 
-    const { output } = await serve(cli, ['--llms'])
+    const { output } = await serve(cli, ['--llms-full'])
     expect(output).toContain('# test ping')
     expect(output).toContain('Health check')
   })
@@ -493,7 +493,7 @@ describe('--llms', () => {
     const cli = Cli.create('test')
     cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
 
-    const { output } = await serve(cli, ['--llms', '--format', 'yaml'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'yaml'])
     expect(output).toContain('version: incur.v1')
     expect(output).toContain('name: ping')
   })
@@ -508,7 +508,7 @@ describe('--llms', () => {
       run: ({ args }) => ({ message: `hello ${args.name}` }),
     })
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     expect(JSON.parse(output)).toMatchInlineSnapshot(`
       {
         "commands": [
@@ -572,7 +572,7 @@ describe('--llms', () => {
       run: ({ args }) => ({ message: `hello ${args.name}` }),
     })
 
-    const { output } = await serve(cli, ['--llms', '--format', 'md'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'md'])
     expect(output).toContain('# test greet')
     expect(output).toContain('## Arguments')
     expect(output).toContain('## Output')
@@ -580,6 +580,69 @@ describe('--llms', () => {
   })
 })
 
+describe('--llms', () => {
+  test('outputs compact command index', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { description: 'Health check', run: () => ({}) })
+    cli.command('greet', {
+      description: 'Greet someone',
+      args: z.object({ name: z.string() }),
+      run: () => ({}),
+    })
+
+    const { output } = await serve(cli, ['--llms-full'])
+    expect(output).toMatchInlineSnapshot(`
+      "# test greet
+
+      Greet someone
+
+      ## Arguments
+
+      | Name | Type | Required | Description |
+      |------|------|----------|-------------|
+      | \`name\` | \`string\` | yes |  |
+
+      # test ping
+
+      Health check
+      "
+    `)
+  })
+
+  test('--llms --json strips schemas', async () => {
+    const cli = Cli.create('test')
+    cli.command('greet', {
+      description: 'Greet someone',
+      args: z.object({ name: z.string() }),
+      output: z.object({ message: z.string() }),
+      run: () => ({ message: 'hi' }),
+    })
+
+    const { output } = await serve(cli, ['--llms', '--json'])
+    const manifest = JSON.parse(output)
+    expect(manifest.version).toBe('incur.v1')
+    expect(manifest.commands).toHaveLength(1)
+    expect(manifest.commands[0].name).toBe('greet')
+    expect(manifest.commands[0].description).toBe('Greet someone')
+    expect(manifest.commands[0].schema).toBeUndefined()
+    expect(manifest.commands[0].examples).toBeUndefined()
+  })
+
+  test('scopes to subtree', async () => {
+    const cli = Cli.create('test')
+    const group = Cli.create('auth', { description: 'Authentication' })
+    group.command('login', { description: 'Log in', run: () => ({}) })
+    group.command('logout', { description: 'Log out', run: () => ({}) })
+    cli.command(group)
+    cli.command('ping', { description: 'Health check', run: () => ({}) })
+
+    const { output } = await serve(cli, ['auth', '--llms'])
+    expect(output).toContain('test auth auth login')
+    expect(output).toContain('test auth auth logout')
+    expect(output).not.toContain('ping')
+  })
+})
+
 describe('--schema', () => {
   test('returns command schema in toon format', async () => {
     const cli = Cli.create('test')
@@ -857,8 +920,11 @@ describe('subcommands', () => {
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
-        --llms                              Print LLM-readable manifest
+        --llms, --llms-full                 Print LLM-readable manifest
         --schema                            Show JSON Schema for a 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
       "
     `)
@@ -1258,7 +1324,7 @@ describe('leaf cli', () => {
     const cli = Cli.create('app')
     cli.command(ping)
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     const manifest = JSON.parse(output)
     expect(manifest.commands).toHaveLength(1)
     expect(manifest.commands[0].name).toBe('ping')
@@ -1293,9 +1359,12 @@ describe('help', () => {
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
-        --llms                              Print LLM-readable manifest
+        --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
         --schema                            Show JSON Schema for a 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
       "
@@ -1328,9 +1397,12 @@ describe('help', () => {
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
-        --llms                              Print LLM-readable manifest
+        --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
         --schema                            Show JSON Schema for a 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
       "
@@ -1359,8 +1431,11 @@ describe('help', () => {
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
-        --llms                              Print LLM-readable manifest
+        --llms, --llms-full                 Print LLM-readable manifest
         --schema                            Show JSON Schema for a 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
       "
     `)
@@ -1390,8 +1465,11 @@ describe('help', () => {
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
-        --llms                              Print LLM-readable manifest
+        --llms, --llms-full                 Print LLM-readable manifest
         --schema                            Show JSON Schema for a 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
       "
     `)
@@ -1482,9 +1560,12 @@ describe('help', () => {
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
-        --llms                              Print LLM-readable manifest
+        --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
         --schema                            Show JSON Schema for a 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
       "
@@ -1511,8 +1592,11 @@ describe('help', () => {
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
-        --llms                              Print LLM-readable manifest
+        --llms, --llms-full                 Print LLM-readable manifest
         --schema                            Show JSON Schema for a 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
       "
     `)
@@ -1603,8 +1687,11 @@ describe('env', () => {
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
-        --llms                              Print LLM-readable manifest
+        --llms, --llms-full                 Print LLM-readable manifest
         --schema                            Show JSON Schema for a 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:
@@ -1638,8 +1725,11 @@ describe('env', () => {
           --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
           --format <toon|json|yaml|md|jsonl>  Output format
           --help                              Show help
-          --llms                              Print LLM-readable manifest
+          --llms, --llms-full                 Print LLM-readable manifest
           --schema                            Show JSON Schema for a 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:
@@ -1694,7 +1784,7 @@ describe('env', () => {
       },
     })
 
-    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const { output } = await serve(cli, ['--llms-full', '--format', 'json'])
     const cmd = JSON.parse(output).commands.find((c: any) => c.name === 'deploy')
     expect(cmd.schema.env).toMatchInlineSnapshot(`
       {
@@ -1724,7 +1814,7 @@ describe('env', () => {
       },
     })
 
-    const { output } = await serve(cli, ['--llms'])
+    const { output } = await serve(cli, ['--llms-full'])
     expect(output).toContain('Environment Variables')
     expect(output).toContain('`API_TOKEN`')
   })
@@ -2468,7 +2558,7 @@ test('--llms scoped to leaf command', async () => {
   cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
   cli.command('greet', { description: 'Greet someone', run: () => ({}) })
 
-  const { output } = await serve(cli, ['--llms', '--format', 'json', 'ping'])
+  const { output } = await serve(cli, ['--llms-full', '--format', 'json', 'ping'])
   const manifest = JSON.parse(output)
   expect(manifest.commands).toHaveLength(1)
   expect(manifest.commands[0].name).toBe('ping')
@@ -2482,7 +2572,7 @@ test('--llms scoped to group', async () => {
   cli.command(pr)
   cli.command('ping', { description: 'Health check', run: () => ({}) })
 
-  const { output } = await serve(cli, ['--llms', '--format', 'json', 'pr'])
+  const { output } = await serve(cli, ['--llms-full', '--format', 'json', 'pr'])
   const manifest = JSON.parse(output)
   expect(manifest.commands).toHaveLength(2)
   expect(manifest.commands.every((c: any) => c.name.startsWith('pr '))).toBe(true)
@@ -2684,7 +2774,7 @@ test('--llms includes hint in skill output', async () => {
     run: () => ({}),
   })
 
-  const { output } = await serve(cli, ['--llms'])
+  const { output } = await serve(cli, ['--llms-full'])
   expect(output).toContain('Always confirm before deploying to production')
 })
 
@@ -2877,7 +2967,7 @@ describe('fetch', async () => {
       description: 'Proxy to API',
       fetch: app.fetch,
     })
-    const { output } = await serve(cli, ['--llms'])
+    const { output } = await serve(cli, ['--llms-full'])
     expect(output).toContain('api')
     expect(output).toContain('Proxy to API')
   })

package/src/Cli.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod'
 
+import { estimateTokenCount, sliceByTokens } from 'tokenx'
 import * as Completions from './Completions.js'
 import * as Filter from './Filter.js'
 import type { FieldError } from './Errors.js'
@@ -419,7 +420,11 @@ async function serveImpl(
     format: formatFlag,
     formatExplicit,
     filterOutput,
+    tokenLimit,
+    tokenOffset,
+    tokenCount,
     llms,
+    llmsFull,
     mcp: mcpFlag,
     help,
     version,
@@ -460,7 +465,7 @@ async function serveImpl(
   }
 
   // Skills staleness check (skip for built-in commands)
-  if (!llms && !schema && !help && !version) {
+  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')
@@ -480,15 +485,17 @@ async function serveImpl(
     }
   }
 
-  if (llms) {
+  if (llms || llmsFull) {
     // Scope to a subtree if command tokens are provided
     let scopedCommands = commands
     const prefix: string[] = []
+    let scopedDescription: string | undefined = options.description
     for (const token of filtered) {
       const entry = scopedCommands.get(token)
       if (!entry) break
       if (isGroup(entry)) {
         scopedCommands = entry.commands
+        scopedDescription = entry.description
         prefix.push(token)
       } else {
         // Leaf command — scope to just this command
@@ -497,14 +504,26 @@ async function serveImpl(
       }
     }
 
+    if (llmsFull) {
+      if (!formatExplicit || formatFlag === 'md') {
+        const groups = new Map<string, string>()
+        const cmds = collectSkillCommands(scopedCommands, prefix, groups)
+        const scopedName = prefix.length > 0 ? `${name} ${prefix.join(' ')}` : name
+        writeln(Skill.generate(scopedName, cmds, groups))
+        return
+      }
+      writeln(Formatter.format(buildManifest(scopedCommands, prefix), formatFlag))
+      return
+    }
+
     if (!formatExplicit || formatFlag === 'md') {
       const groups = new Map<string, string>()
       const cmds = collectSkillCommands(scopedCommands, prefix, groups)
       const scopedName = prefix.length > 0 ? `${name} ${prefix.join(' ')}` : name
-      writeln(Skill.generate(scopedName, cmds, groups))
+      writeln(Skill.index(scopedName, cmds, scopedDescription))
       return
     }
-    writeln(Formatter.format(buildManifest(scopedCommands, prefix), formatFlag))
+    writeln(Formatter.format(buildIndexManifest(scopedCommands, prefix), formatFlag))
     return
   }
 
@@ -909,27 +928,69 @@ async function serveImpl(
 
   const filterPaths = filterOutput ? Filter.parse(filterOutput) : undefined
 
+  function truncate(s: string): { text: string; truncated: boolean; nextOffset?: number | undefined } {
+    if (tokenLimit == null && tokenOffset == null) return { text: s, truncated: false }
+    const total = estimateTokenCount(s)
+    const offset = tokenOffset ?? 0
+    const end = tokenLimit != null ? offset + tokenLimit : total
+    if (offset === 0 && end >= total) return { text: s, truncated: false }
+    const sliced = sliceByTokens(s, offset, end)
+    const actualEnd = Math.min(end, total)
+    const nextOffset = actualEnd < total ? actualEnd : undefined
+    return {
+      text: `${sliced}\n[truncated: showing tokens ${offset}–${actualEnd} of ${total}]`,
+      truncated: true,
+      nextOffset,
+    }
+  }
+
   function write(output: Output) {
     if (filterPaths && output.ok && output.data != null)
       output = { ...output, data: Filter.apply(output.data, filterPaths) }
+    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 (output.ok && output.data != null && renderOutput)
-        writeln(Formatter.format(output.data, format))
-      else if (!output.ok) writeln(formatHumanError(output.error))
+      if (output.ok && output.data != null && renderOutput) {
+        const t = truncate(Formatter.format(output.data, format))
+        writeln(t.text)
+      } else if (!output.ok) writeln(formatHumanError(output.error))
       if (cta) writeln(formatHumanCta(cta))
       return
     }
-    if (verbose) return writeln(Formatter.format(output, format))
+    if (verbose) {
+      if (tokenLimit != null || tokenOffset != null) {
+        // Truncate data separately so meta (including nextOffset) is always visible
+        const dataFormatted = output.ok && output.data != null
+          ? Formatter.format(output.data, format)
+          : !output.ok
+            ? Formatter.format(output.error, format)
+            : ''
+        const t = truncate(dataFormatted)
+        if (t.truncated) {
+          const envelope: Record<string, unknown> = output.ok
+            ? { ok: true, data: t.text }
+            : { ok: false, error: t.text }
+          const meta: Record<string, unknown> = { ...output.meta }
+          if (t.nextOffset != null) meta.nextOffset = t.nextOffset
+          envelope.meta = meta
+          return writeln(Formatter.format(envelope, format))
+        }
+      }
+      return writeln(Formatter.format(output, format))
+    }
     const base = output.ok ? output.data : output.error
     const formatted = Formatter.format(base, format)
     if (!cta) {
-      if (formatted) writeln(formatted)
+      if (formatted) writeln(truncate(formatted).text)
       return
     }
     const payload =
       typeof base === 'object' && base !== null ? { ...base, cta } : { data: base, cta }
-    writeln(Formatter.format(payload, format))
+    writeln(truncate(Formatter.format(payload, format)).text)
   }
 
   if ('error' in effective) {
@@ -985,6 +1046,7 @@ async function serveImpl(
           human,
           renderOutput,
           verbose,
+          truncate,
           write,
           writeln,
           exit,
@@ -1141,6 +1203,7 @@ async function serveImpl(
         human,
         renderOutput,
         verbose,
+        truncate,
         write,
         writeln,
         exit,
@@ -1752,6 +1815,7 @@ declare namespace serveImpl {
 function extractBuiltinFlags(argv: string[]) {
   let verbose = false
   let llms = false
+  let llmsFull = false
   let mcp = false
   let help = false
   let version = false
@@ -1759,12 +1823,16 @@ function extractBuiltinFlags(argv: string[]) {
   let format: Formatter.Format = 'toon'
   let formatExplicit = false
   let filterOutput: string | undefined
+  let tokenLimit: number | undefined
+  let tokenOffset: number | undefined
+  let tokenCount = false
   const rest: string[] = []
 
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i]!
     if (token === '--verbose') verbose = true
     else if (token === '--llms') llms = true
+    else if (token === '--llms-full') llmsFull = true
     else if (token === '--mcp') mcp = true
     else if (token === '--help' || token === '-h') help = true
     else if (token === '--version') version = true
@@ -1779,10 +1847,17 @@ function extractBuiltinFlags(argv: string[]) {
     } else if (token === '--filter-output' && argv[i + 1]) {
       filterOutput = argv[i + 1]!
       i++
-    } else rest.push(token)
+    } else if (token === '--token-limit' && argv[i + 1]) {
+      tokenLimit = Number(argv[i + 1])
+      i++
+    } else if (token === '--token-offset' && argv[i + 1]) {
+      tokenOffset = Number(argv[i + 1])
+      i++
+    } else if (token === '--token-count') tokenCount = true
+    else rest.push(token)
   }
 
-  return { verbose, format, formatExplicit, filterOutput, llms, mcp, help, version, schema, rest }
+  return { verbose, format, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp, help, version, schema, rest }
 }
 
 /** @internal Collects immediate child commands/groups for help output. */
@@ -1954,6 +2029,7 @@ async function handleStreaming(
     human: boolean
     renderOutput: boolean
     verbose: boolean
+    truncate: (s: string) => { text: string; truncated: boolean; nextOffset?: number | undefined }
     write: (output: Output) => void
     writeln: (s: string) => void
     exit: (code: number) => void
@@ -1997,7 +2073,7 @@ async function handleStreaming(
           }
         }
         if (useJsonl) ctx.writeln(JSON.stringify({ type: 'chunk', data: value }))
-        else if (ctx.renderOutput) ctx.writeln(Formatter.format(value, ctx.format))
+        else if (ctx.renderOutput) ctx.writeln(ctx.truncate(Formatter.format(value, ctx.format)).text)
       }
 
       // Handle return value — error() or ok() sentinel
@@ -2164,6 +2240,35 @@ function formatCta(name: string, cta: Cta): FormattedCta {
   return { command: cmd, ...(cta.description ? { description: cta.description } : undefined) }
 }
 
+/** @internal Builds the `--llms` index manifest (name + description only) from the command tree. */
+function buildIndexManifest(commands: Map<string, CommandEntry>, prefix: string[] = []) {
+  return {
+    version: 'incur.v1',
+    commands: collectIndexCommands(commands, prefix).sort((a, b) => a.name.localeCompare(b.name)),
+  }
+}
+
+/** @internal Recursively collects leaf commands with name + description only. */
+function collectIndexCommands(
+  commands: Map<string, CommandEntry>,
+  prefix: string[],
+): { name: string; description?: string | undefined }[] {
+  const result: { name: string; description?: string | undefined }[] = []
+  for (const [name, entry] of commands) {
+    const path = [...prefix, name]
+    if (isGroup(entry)) {
+      result.push(...collectIndexCommands(entry.commands, path))
+    } else {
+      const cmd: (typeof result)[number] = { name: path.join(' ') }
+      if (isFetchGateway(entry)) {
+        if (entry.description) cmd.description = entry.description
+      } else if (entry.description) cmd.description = entry.description
+      result.push(cmd)
+    }
+  }
+  return result
+}
+
 /** @internal Builds the `--llms` manifest from the command tree. */
 function buildManifest(commands: Map<string, CommandEntry>, prefix: string[] = []) {
   return {
@@ -2382,6 +2487,8 @@ declare namespace Output {
     cta?: FormattedCtaBlock | undefined
     /** Wall-clock duration of the command. */
     duration: string
+    /** Offset to pass as `--token-offset` to fetch the next page of truncated output. */
+    nextOffset?: number | undefined
   }
 }