incur 0.3.25 → 0.4.1

package/README.md

@@ -40,7 +40,7 @@
 - [**`--llms` flag**](#agent-discovery): token-efficient command manifest in Markdown or JSON schema
 - [**Well-formed I/O**](#well-formed-io): Schemas schemas for arguments, options, environment variables, and output
 - [**Inferred types**](#inferred-types): generic type flow from schemas to `run` callbacks with zero manual annotations
-- [**Global options**](#global-options): `--format`, `--json`, `--verbose`, `--help`, `--version` on every CLI for free
+- [**Global options**](#global-options): `--format`, `--full-output`, `--help`, `--json`, `--version` on every CLI for free
 - [**Light API surface**](#light-api-surface): `Cli.create()`, `.command()`, `.serve()` – that's it
 - [**Middleware**](#middleware): composable before/after hooks with typed dependency injection via `cli.use()`
 
@@ -116,6 +116,7 @@ $ greet --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                              Print LLM-readable manifest
 #   --mcp                               Start as MCP stdio server
@@ -123,7 +124,6 @@ $ greet --help
 #   --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 (for pagination)
-#   --verbose                           Show full output envelope
 #   --version                           Show version
 ```
 
@@ -186,6 +186,7 @@ $ my-cli --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                              Print LLM-readable manifest
 #   --mcp                               Start as MCP stdio server
@@ -193,7 +194,6 @@ $ my-cli --help
 #   --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 (for pagination)
-#   --verbose                           Show full output envelope
 #   --version                           Show version
 ```
 
@@ -243,6 +243,7 @@ $ my-cli --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                              Print LLM-readable manifest
 #   --mcp                               Start as MCP stdio server
@@ -250,7 +251,6 @@ $ my-cli --help
 #   --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 (for pagination)
-#   --verbose                           Show full output envelope
 #   --version                           Show version
 ```
 
@@ -370,7 +370,7 @@ GET  /users/42         → my-cli users 42
 POST /users { "name": "Bob" }  → my-cli users --name Bob
 ```
 
-Responses use the same JSON envelope as `--verbose --format json`:
+Responses use the same JSON envelope as `--full-output --format json`:
 
 ```json
 { "ok": true, "data": { "users": [...] }, "meta": { "command": "users", "duration": "3ms" } }
@@ -411,7 +411,7 @@ my-cli --llms
 
 Most CLIs expose tools via MCP or a single monolithic skill file. incur combines on-demand skill loading with TOON output to cut token usage across the entire session – from discovery through invocation and response.
 
-The table below models a session with a 20-command CLI producing verbose output.
+The table below models a session with a 20-command CLI producing full output envelopes.
 
 - **Session start** – tokens consumed just by having the tool available. _MCP injects all tool schemas into every turn; skills only load frontmatter (name + description)._
 - **Discovery** – tokens to learn what commands exist and how to call them. _MCP gets this at session start; skills load the full skill file on demand; incur splits by command group so only relevant commands are loaded._
@@ -620,7 +620,7 @@ cli.command('greet', {
 
 ### Output policy
 
-Control whether output data is displayed to humans. By default, output goes to everyone (`'all'`). Set `outputPolicy: 'agent-only'` to suppress data in TTY mode while still returning it to agents via `--json`, `--format`, or `--verbose`.
+Control whether output data is displayed to humans. By default, output goes to everyone (`'all'`). Set `outputPolicy: 'agent-only'` to suppress data in TTY mode while still returning it to agents via `--json`, `--format`, or `--full-output`.
 
 ```ts
 cli.command('deploy', {
@@ -803,18 +803,18 @@ Every incur CLI includes these flags automatically:
 
 | Flag                     | Description                                            |
 | ------------------------ | ------------------------------------------------------ |
+| `--filter-output <keys>` | Filter output by key paths (e.g. `foo,bar.baz,a[0,3]`) |
+| `--format <fmt>`         | Output format: `toon`, `json`, `yaml`, `md`            |
+| `--full-output`          | Include full envelope (`ok`, `data`, `meta`)           |
 | `--help`, `-h`           | Show help for the CLI or a specific command            |
-| `--version`              | Print CLI version                                      |
 | `--llms`                 | Output agent-readable command manifest                 |
 | `--mcp`                  | Start as an MCP stdio server                           |
 | `--json`                 | Shorthand for `--format json`                          |
-| `--format <fmt>`         | Output format: `toon`, `json`, `yaml`, `md`            |
-| `--filter-output <keys>` | Filter output by key paths (e.g. `foo,bar.baz,a[0,3]`) |
 | `--schema`               | Show JSON Schema for command's args, options, output   |
 | `--token-count`          | Print token count of output instead of output          |
 | `--token-limit <n>`      | Limit output to n tokens (for pagination)              |
 | `--token-offset <n>`     | Skip first n tokens of output (for pagination)         |
-| `--verbose`              | Include full envelope (`ok`, `data`, `meta`)           |
+| `--version`              | Print CLI version                                      |
 
 ### Config file
 

package/SKILL.md

@@ -419,10 +419,10 @@ Control with `--format <fmt>` or `--json`:
 
 ### Envelope
 
-With `--verbose`, the full envelope is emitted:
+With `--full-output`, the full envelope is emitted:
 
 ```sh
-tool info express --verbose
+tool info express --full-output
 ```
 
 ```
@@ -435,7 +435,7 @@ meta:
   duration: 12ms
 ```
 
-Without `--verbose`, only `data` is emitted. On errors, only the `error` block is emitted.
+Without `--full-output`, only `data` is emitted. On errors, only the `error` block is emitted.
 
 ### Filtering output
 
@@ -482,7 +482,7 @@ tool users --token-limit 20
 tool users --token-offset 20 --token-limit 20
 ```
 
-With `--verbose`, truncated output includes `meta.nextOffset` for programmatic pagination.
+With `--full-output`, truncated output includes `meta.nextOffset` for programmatic pagination.
 
 ### Command schema
 
@@ -725,7 +725,7 @@ Use `--llms --format json` for JSON schema manifest:
 | `--mcp`          | Start as an MCP stdio server                 |
 | `--json`         | Shorthand for `--format json`                |
 | `--format <fmt>` | Output format: `toon`, `json`, `yaml`, `md`  |
-| `--verbose`      | Include full envelope (`ok`, `data`, `meta`) |
+| `--full-output`  | Include full envelope (`ok`, `data`, `meta`) |
 
 ## Examples
 
@@ -760,7 +760,7 @@ Hints are displayed after examples in help output and included in skill files.
 
 ### Output policy
 
-Control whether output data is displayed to humans. `'all'` (default) shows output to everyone. `'agent-only'` suppresses data in human/TTY mode while still returning it via `--json`, `--format`, or `--verbose`.
+Control whether output data is displayed to humans. `'all'` (default) shows output to everyone. `'agent-only'` suppresses data in human/TTY mode while still returning it via `--json`, `--format`, or `--full-output`.
 
 ```ts
 cli.command('deploy', {

package/dist/Cli.js

@@ -163,7 +163,7 @@ async function serveImpl(name, commands, argv, options = {}) {
         exit(1);
         return;
     }
-    const { verbose, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, configPath, configDisabled, rest: filtered, } = builtinFlags;
+    const { fullOutput, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, configPath, configDisabled, rest: filtered, } = builtinFlags;
     // --mcp: start as MCP stdio server
     if (mcpFlag) {
         await Mcp.serve(name, options.version ?? '0.0.0', commands, {
@@ -429,9 +429,9 @@ async function serveImpl(name, commands, argv, options = {}) {
             lines.push('');
             lines.push(`Run \`${name} --help\` to see the full command reference.`);
             writeln(lines.join('\n'));
-            if (verbose || formatExplicit) {
+            if (fullOutput || formatExplicit) {
                 const output = { skills: result.paths };
-                if (verbose && result.agents.length > 0)
+                if (fullOutput && result.agents.length > 0)
                     output.agents = result.agents;
                 writeln(Formatter.format(output, formatExplicit ? formatFlag : 'toon'));
             }
@@ -512,7 +512,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                     lines.push(`  "${s}"`);
             }
             writeln(lines.join('\n'));
-            if (verbose || formatExplicit)
+            if (fullOutput || formatExplicit)
                 writeln(Formatter.format({ name, command: result.command, agents: result.agents }, formatExplicit ? formatFlag : 'toon'));
         }
         catch (err) {
@@ -769,7 +769,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             return writeln(String(estimateTokenCount(formatted)));
         }
         const cta = output.meta.cta;
-        if (human && !verbose) {
+        if (human && !fullOutput) {
             if (output.ok && output.data != null && renderOutput) {
                 const t = truncate(Formatter.format(output.data, format));
                 writeln(t.text);
@@ -780,7 +780,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                 writeln(formatHumanCta(cta));
             return;
         }
-        if (verbose) {
+        if (fullOutput) {
             if (tokenLimit != null || tokenOffset != null) {
                 // Truncate data separately so meta (including nextOffset) is always visible
                 const dataFormatted = output.ok && output.data != null
@@ -832,7 +832,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             description: ctaCommands.length === 1 ? 'Suggested command:' : 'Suggested commands:',
             commands: ctaCommands,
         };
-        if (human && !verbose) {
+        if (human && !fullOutput) {
             writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }));
             const mergedCta = skillsCta
                 ? { ...cta, commands: [...cta.commands, ...skillsCta.commands] }
@@ -877,7 +877,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                     formatExplicit,
                     human,
                     renderOutput,
-                    verbose,
+                    fullOutput,
                     truncate,
                     write,
                     writeln,
@@ -1040,7 +1040,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             formatExplicit,
             human,
             renderOutput,
-            verbose,
+            fullOutput,
             truncate,
             write,
             writeln,
@@ -1414,10 +1414,10 @@ function resolveCommand(commands, tokens) {
         ...(outputPolicy ? { outputPolicy } : undefined),
     };
 }
-/** @internal Extracts built-in flags (--verbose, --format, --json, --llms, --help, --version) from argv. */
+/** @internal Extracts built-in flags (--full-output, --format, --json, --llms, --help, --version) from argv. */
 const validFormats = new Set(['toon', 'json', 'yaml', 'md', 'jsonl']);
 function extractBuiltinFlags(argv, options = {}) {
-    let verbose = false;
+    let fullOutput = false;
     let llms = false;
     let llmsFull = false;
     let mcp = false;
@@ -1438,8 +1438,8 @@ function extractBuiltinFlags(argv, options = {}) {
     const noCfgFlag = options.configFlag ? `--no-${options.configFlag}` : undefined;
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
-        if (token === '--verbose')
-            verbose = true;
+        if (token === '--full-output')
+            fullOutput = true;
         else if (token === '--llms')
             llms = true;
         else if (token === '--llms-full')
@@ -1508,7 +1508,7 @@ function extractBuiltinFlags(argv, options = {}) {
             rest.push(token);
     }
     return {
-        verbose,
+        fullOutput,
         format,
         formatExplicit,
         configPath,