Rename global --verbose flag to --full-output

.changeset/pretty-ads-fry.md

@@ -0,0 +1,5 @@
+---
+'incur': minor
+---
+
+**Breaking:** Renamed the global full-envelope flag from `--verbose` to `--full-output`, allowing `--verbose` to be used as a normal command option.

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,14 +116,14 @@ $ 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
 #   --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 (for pagination)
-#   --verbose                           Show full output envelope
 #   --version                           Show version
 ```
 
@@ -186,14 +186,14 @@ $ 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
 #   --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 (for pagination)
-#   --verbose                           Show full output envelope
 #   --version                           Show version
 ```
 
@@ -243,14 +243,14 @@ $ 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
 #   --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 (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
 

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', {