From 09fcf8afb43a4ef1001043f92ce353ddfbb9619d Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Wed, 2 Sep 2026 13:09:58 +0000
Subject: [PATCH 1/5] docs(cli): rewrite cli help text and guide pages

The CLI's help text is the source for its reference pages, man page, and
completion scripts, so this rewrites the doc comments in `cli/src/cli/` and
regenerates everything downstream.

Beyond tone, it fixes claims that were wrong or missing:

- `--usage-cmd` documented a default of `$bin --usage`. It has none, and is
  required when `--file` is absent.
- `<SCRIPT>` on the four shell commands and `--shell` on `complete-word` had no
  help at all.
- `-h`/`--help` on the shell commands and `exec` said "Show help". They print
  the *script's* help page, not usage's.
- `-f --file` and `--spec` had five different wordings across commands, two of
  them lowercase. They now share one phrasing that mentions shebang scripts.
- `lint`, `mcp`, `generate completion`, `json`, `json-schema`, `markdown`,
  `sdk`, and the root command gained long help saying what they do and how they
  exit.

Guide pages: `docs/cli/index.md` was install instructions only and now says
what the tool is for, with a table from task to command. The completions,
manpages, markdown, and SDK guides are rewritten in the voice of the newer
pages. Two Rust examples in the markdown guide used rustdoc `#`-hidden lines,
which VitePress renders literally; they are complete programs now. The spec
landing page presents the spec as the contract behind the Rust and Go
frameworks rather than "a spec and CLI", and drops an unverifiable
"coming soon" bullet.

Adopters with snapshot tests over `usage`'s own help output will see diffs.
The perf gate's `markdown` benchmark parses `cli/usage.usage.kdl`, so its
instruction count may move with the spec text.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 cli/assets/fig.ts                             | 142 +++++----
 cli/assets/usage.1                            | 266 ++++++++++-------
 cli/src/cli/complete_word.rs                  |  14 +-
 cli/src/cli/exec.rs                           |  20 +-
 cli/src/cli/explain.rs                        |   4 +-
 cli/src/cli/generate/completion.rs            |  26 +-
 cli/src/cli/generate/completion_init.rs       |  16 +-
 cli/src/cli/generate/fig.rs                   |   8 +-
 cli/src/cli/generate/go.rs                    |   6 +-
 cli/src/cli/generate/json.rs                  |   9 +-
 cli/src/cli/generate/json_schema.rs           |   8 +-
 cli/src/cli/generate/manpage.rs               |   2 +-
 cli/src/cli/generate/markdown.rs              |  13 +-
 cli/src/cli/generate/mod.rs                   |   2 +-
 cli/src/cli/generate/sdk.rs                   |   9 +-
 cli/src/cli/lint.rs                           |  11 +-
 cli/src/cli/mcp.rs                            |   9 +-
 cli/src/cli/mod.rs                            |  13 +-
 cli/src/cli/shell.rs                          |  23 +-
 cli/src/test.rs                               |  30 +-
 cli/usage.usage.kdl                           | 266 +++++++++++------
 docs/cli/completions.md                       | 166 ++++++-----
 docs/cli/index.md                             |  34 ++-
 docs/cli/manpages.md                          |  69 ++---
 docs/cli/markdown.md                          |  86 +++---
 docs/cli/reference/bash.md                    |  24 +-
 docs/cli/reference/commands.json              | 277 ++++++++++--------
 docs/cli/reference/complete-word.md           |  12 +-
 docs/cli/reference/exec.md                    |  16 +-
 docs/cli/reference/explain.md                 |   4 +-
 docs/cli/reference/fish.md                    |  24 +-
 docs/cli/reference/generate.md                |   2 +-
 .../cli/reference/generate/completion-init.md |  10 +-
 docs/cli/reference/generate/completion.md     |  21 +-
 docs/cli/reference/generate/fig.md            |   8 +-
 docs/cli/reference/generate/go.md             |   6 +-
 docs/cli/reference/generate/json-schema.md    |   6 +-
 docs/cli/reference/generate/json.md           |   8 +-
 docs/cli/reference/generate/manpage.md        |   2 +-
 docs/cli/reference/generate/markdown.md       |  12 +-
 docs/cli/reference/generate/sdk.md            |   8 +-
 docs/cli/reference/index.md                   |   4 +-
 docs/cli/reference/lint.md                    |   8 +-
 docs/cli/reference/mcp.md                     |   9 +-
 docs/cli/reference/powershell.md              |  24 +-
 docs/cli/reference/zsh.md                     |  24 +-
 docs/cli/scripts.md                           |  43 ++-
 docs/cli/sdk.md                               | 110 +++----
 docs/spec/index.md                            |  67 +++--
 docs/spec/integrations.md                     |   4 +-
 50 files changed, 1142 insertions(+), 843 deletions(-)

diff --git a/cli/assets/fig.ts b/cli/assets/fig.ts
index 658f439f7..090a91e1b 100644
--- a/cli/assets/fig.ts
+++ b/cli/assets/fig.ts
@@ -93,22 +93,24 @@ const completionSpec: Fig.Spec = {
       options: [
         {
           name: "-h",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
         {
           name: "--help",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
       ],
       args: [
         {
           name: "script",
+          description:
+            "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
         },
         {
           name: "args",
-          description: "Arguments to pass to script",
+          description: "Arguments to pass to the script",
           isOptional: true,
           isVariadic: true,
         },
@@ -122,7 +124,7 @@ const completionSpec: Fig.Spec = {
         {
           name: ["-f", "--file"],
           description:
-            'Usage spec file or script with usage shebang, use "-" to read from stdin',
+            'A usage spec file, or a script with a usage shebang; "-" reads stdin',
           isRepeatable: false,
           args: {
             name: "file",
@@ -131,7 +133,7 @@ const completionSpec: Fig.Spec = {
         },
         {
           name: ["-s", "--spec"],
-          description: "Raw string spec input",
+          description: "The spec itself, as a string, instead of a file",
           isRepeatable: false,
           args: {
             name: "spec",
@@ -139,7 +141,8 @@ const completionSpec: Fig.Spec = {
         },
         {
           name: "--cword",
-          description: "Current word index",
+          description:
+            "Index of the word being completed; defaults to the last word",
           isRepeatable: false,
           args: {
             name: "cword",
@@ -147,6 +150,8 @@ const completionSpec: Fig.Spec = {
         },
         {
           name: "--shell",
+          description:
+            "The shell the candidates are for, which decides how they are quoted",
           isRepeatable: false,
           args: {
             name: "shell",
@@ -161,7 +166,7 @@ const completionSpec: Fig.Spec = {
       ],
       args: {
         name: "words",
-        description: "User's input from the command line",
+        description: "The words typed so far, starting with the program name",
         isOptional: true,
         isVariadic: true,
       },
@@ -213,31 +218,32 @@ const completionSpec: Fig.Spec = {
     {
       name: ["exec", "x"],
       description:
-        "Execute a script, parsing args and exposing them as environment variables",
+        "Run a script through any interpreter, with its parsed arguments as environment variables",
       options: [
         {
           name: "-h",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
         {
           name: "--help",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
       ],
       args: [
         {
           name: "command",
-          description: "Command to execute after parsing usage spec",
+          description:
+            "The interpreter to run the script with, such as `node` or `python3`",
         },
         {
           name: "bin",
-          description: "Path to script to execute",
+          description: "The script to run",
         },
         {
           name: "args",
-          description: "Arguments to pass to script",
+          description: "Arguments to pass to the script",
           isOptional: true,
           isVariadic: true,
         },
@@ -250,7 +256,7 @@ const completionSpec: Fig.Spec = {
         {
           name: ["-f", "--file"],
           description:
-            'A usage spec file or script with a usage shebang, use "-" to read from stdin',
+            'A usage spec file, or a script with a usage shebang; "-" reads stdin',
           isRepeatable: false,
           args: {
             name: "file",
@@ -259,7 +265,7 @@ const completionSpec: Fig.Spec = {
         },
         {
           name: ["-s", "--spec"],
-          description: "Raw string spec input",
+          description: "The spec itself, as a string, instead of a file",
           isRepeatable: false,
           args: {
             name: "spec",
@@ -311,22 +317,24 @@ const completionSpec: Fig.Spec = {
       options: [
         {
           name: "-h",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
         {
           name: "--help",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
       ],
       args: [
         {
           name: "script",
+          description:
+            "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
         },
         {
           name: "args",
-          description: "Arguments to pass to script",
+          description: "Arguments to pass to the script",
           isOptional: true,
           isVariadic: true,
         },
@@ -335,12 +343,12 @@ const completionSpec: Fig.Spec = {
     {
       name: ["generate", "g"],
       description:
-        "Generate completions, documentation, and other artifacts from usage specs",
+        "Generate completions, docs, manpages, SDKs, and parse tables from a usage spec",
       subcommands: [
         {
           name: ["completion", "c"],
           description:
-            "Generate shell completion scripts for bash, fish, nu, powershell, or zsh",
+            "Generate a shell completion script for bash, fish, nu, powershell, or zsh",
           options: [
             {
               name: "--install",
@@ -357,7 +365,7 @@ const completionSpec: Fig.Spec = {
             {
               name: ["-f", "--file"],
               description:
-                'A .usage.kdl spec file to use for generating completions, use "-" to read from stdin',
+                'A usage spec file, or a script with a usage shebang; "-" reads stdin',
               isRepeatable: false,
               args: {
                 name: "file",
@@ -367,7 +375,7 @@ const completionSpec: Fig.Spec = {
             {
               name: "--cache-key",
               description:
-                "A cache key to use for storing the results of calling the CLI with --usage-cmd",
+                "Cache what --usage-cmd prints under this key, so it runs once per key rather than on every Tab; the CLI's version is a good key",
               isRepeatable: false,
               args: {
                 name: "cache_key",
@@ -376,7 +384,7 @@ const completionSpec: Fig.Spec = {
             {
               name: "--usage-bin",
               description:
-                "Override the bin used for calling back to usage-cli",
+                "The `usage` executable the script calls back to, when it is not `usage` on PATH",
               isRepeatable: false,
               args: {
                 name: "usage_bin",
@@ -385,7 +393,7 @@ const completionSpec: Fig.Spec = {
             {
               name: "--usage-cmd",
               description:
-                'A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to "$bin --usage"',
+                "A command that prints the CLI's spec, run in place of reading --file",
               isRepeatable: false,
               args: {
                 name: "usage_cmd",
@@ -400,24 +408,25 @@ const completionSpec: Fig.Spec = {
           args: [
             {
               name: "shell",
-              description: "Shell to generate completions for",
+              description: "The shell to generate the script for",
               suggestions: ["bash", "fish", "nu", "powershell", "zsh"],
             },
             {
               name: "bin",
-              description: "The CLI which we're generating completions for",
+              description:
+                "The name of the CLI being completed, as it is typed at the prompt",
             },
           ],
         },
         {
           name: ["completion-init", "ci"],
           description:
-            "Generate a shell init script that auto-completes any usage shebang script on $PATH",
+            "Generate a shell init script that completes every usage-shebang script on PATH",
           options: [
             {
               name: "--usage-bin",
               description:
-                "Override the bin used for calling back to usage-cli",
+                "The `usage` executable the script calls back to, when it is not `usage` on PATH",
               isRepeatable: false,
               args: {
                 name: "usage_bin",
@@ -431,18 +440,18 @@ const completionSpec: Fig.Spec = {
           ],
           args: {
             name: "shell",
-            description: "Shell to generate the init script for",
+            description: "The shell to generate the script for",
             suggestions: ["bash", "fish", "zsh"],
           },
         },
         {
           name: "fig",
-          description: "Generate Fig completion spec for Amazon Q / Fig",
+          description: "Generate a Fig completion spec, for Amazon Q and Fig",
           options: [
             {
               name: ["-f", "--file"],
               description:
-                'A usage spec taken in as a file, use "-" to read from stdin',
+                'A usage spec file, or a script with a usage shebang; "-" reads stdin',
               isRepeatable: false,
               args: {
                 name: "file",
@@ -452,7 +461,7 @@ const completionSpec: Fig.Spec = {
             {
               name: "--out-file",
               description:
-                'File path where the generated Fig spec will be saved, or "-" for stdout',
+                'Where to write the spec, or "-" for stdout (default)',
               isRepeatable: false,
               args: {
                 name: "out_file",
@@ -461,7 +470,7 @@ const completionSpec: Fig.Spec = {
             },
             {
               name: "--spec",
-              description: "Raw string spec input",
+              description: "The spec itself, as a string, instead of a file",
               isRepeatable: false,
               args: {
                 name: "spec",
@@ -481,7 +490,7 @@ const completionSpec: Fig.Spec = {
             {
               name: ["-f", "--file"],
               description:
-                'A usage spec taken in as a file, use "-" to read from stdin',
+                'A usage spec file, or a script with a usage shebang; "-" reads stdin',
               isRepeatable: false,
               args: {
                 name: "file",
@@ -491,7 +500,7 @@ const completionSpec: Fig.Spec = {
             {
               name: ["-o", "--out-file"],
               description:
-                'File path where the generated Go source will be saved, or "-" for stdout',
+                'Where to write the Go source, or "-" for stdout (default)',
               isRepeatable: false,
               args: {
                 name: "out_file",
@@ -509,7 +518,7 @@ const completionSpec: Fig.Spec = {
             },
             {
               name: "--spec",
-              description: "Raw string spec input",
+              description: "The spec itself, as a string, instead of a file",
               isRepeatable: false,
               args: {
                 name: "spec",
@@ -524,12 +533,12 @@ const completionSpec: Fig.Spec = {
         },
         {
           name: "json",
-          description: "Outputs a usage spec in json format",
+          description: "Print a usage spec as JSON",
           options: [
             {
               name: ["-f", "--file"],
               description:
-                'A usage spec taken in as a file, use "-" to read from stdin',
+                'A usage spec file, or a script with a usage shebang; "-" reads stdin',
               isRepeatable: false,
               args: {
                 name: "file",
@@ -538,7 +547,7 @@ const completionSpec: Fig.Spec = {
             },
             {
               name: "--spec",
-              description: "Raw string spec input",
+              description: "The spec itself, as a string, instead of a file",
               isRepeatable: false,
               args: {
                 name: "spec",
@@ -567,7 +576,7 @@ const completionSpec: Fig.Spec = {
             {
               name: ["-f", "--file"],
               description:
-                'A usage spec taken in as a file, use "-" to read from stdin',
+                'A usage spec file, or a script with a usage shebang; "-" reads stdin',
               isRepeatable: false,
               args: {
                 name: "file",
@@ -585,7 +594,7 @@ const completionSpec: Fig.Spec = {
             },
             {
               name: "--spec",
-              description: "Raw string spec input",
+              description: "The spec itself, as a string, instead of a file",
               isRepeatable: false,
               args: {
                 name: "spec",
@@ -621,7 +630,7 @@ const completionSpec: Fig.Spec = {
             {
               name: ["-f", "--file"],
               description:
-                'A usage spec taken in as a file, use "-" to read from stdin',
+                'A usage spec file, or a script with a usage shebang; "-" reads stdin',
               isRepeatable: false,
               args: {
                 name: "file",
@@ -662,12 +671,12 @@ const completionSpec: Fig.Spec = {
         },
         {
           name: ["markdown", "md"],
-          description: "Generate markdown documentation from usage specs",
+          description: "Generate Markdown documentation from a usage spec",
           options: [
             {
               name: ["-f", "--file"],
               description:
-                'A usage spec taken in as a file, use "-" to read from stdin',
+                'A usage spec file, or a script with a usage shebang; "-" reads stdin',
               isRepeatable: false,
               args: {
                 name: "file",
@@ -695,7 +704,7 @@ const completionSpec: Fig.Spec = {
             {
               name: "--out-dir",
               description:
-                "Output markdown files to this directory (required when using --multi)",
+                "Directory for the per-command pages (required with --multi)",
               isRepeatable: false,
               args: {
                 name: "out_dir",
@@ -719,7 +728,8 @@ const completionSpec: Fig.Spec = {
             },
             {
               name: "--url-prefix",
-              description: "Prefix to add to all URLs",
+              description:
+                "Prefix for the links between pages, such as /cli/reference",
               isRepeatable: false,
               args: {
                 name: "url_prefix",
@@ -727,7 +737,8 @@ const completionSpec: Fig.Spec = {
             },
             {
               name: "--template",
-              description: "Override a Tera template with NAME=PATH",
+              description:
+                "Replace a built-in Tera template, as NAME=PATH; the names are spec, index, command, argument, flag, and config",
               isRepeatable: true,
               args: {
                 name: "template",
@@ -746,7 +757,8 @@ const completionSpec: Fig.Spec = {
           options: [
             {
               name: ["-f", "--file"],
-              description: "A usage spec taken in as a file",
+              description:
+                'A usage spec file, or a script with a usage shebang; "-" reads stdin',
               isRepeatable: false,
               args: {
                 name: "file",
@@ -764,7 +776,7 @@ const completionSpec: Fig.Spec = {
             },
             {
               name: ["-o", "--output"],
-              description: "Output directory for generated SDK files",
+              description: "Directory to write the SDK into",
               isRepeatable: false,
               args: {
                 name: "output",
@@ -781,7 +793,7 @@ const completionSpec: Fig.Spec = {
             },
             {
               name: "--spec",
-              description: "Raw string spec input",
+              description: "The spec itself, as a string, instead of a file",
               isRepeatable: false,
               args: {
                 name: "spec",
@@ -805,7 +817,7 @@ const completionSpec: Fig.Spec = {
     },
     {
       name: "lint",
-      description: "Lint a usage spec file for common issues",
+      description: "Lint a usage spec for mistakes that still parse",
       options: [
         {
           name: ["-f", "--format"],
@@ -835,7 +847,8 @@ const completionSpec: Fig.Spec = {
       ],
       args: {
         name: "file",
-        description: 'A usage spec file to lint, use "-" to read from stdin',
+        description:
+          'A usage spec file, or a script with a usage shebang; "-" reads stdin',
         template: "filepaths",
       },
     },
@@ -845,7 +858,8 @@ const completionSpec: Fig.Spec = {
       options: [
         {
           name: ["-f", "--file"],
-          description: 'Usage spec file (not "-": stdin is the MCP transport)',
+          description:
+            'A usage spec file, or a script with a usage shebang (not "-": stdin is the MCP transport)',
           isRepeatable: false,
           args: {
             name: "file",
@@ -854,7 +868,7 @@ const completionSpec: Fig.Spec = {
         },
         {
           name: ["-s", "--spec"],
-          description: "Raw string spec input",
+          description: "The spec itself, as a string, instead of a file",
           isRepeatable: false,
           args: {
             name: "spec",
@@ -873,22 +887,24 @@ const completionSpec: Fig.Spec = {
       options: [
         {
           name: "-h",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
         {
           name: "--help",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
       ],
       args: [
         {
           name: "script",
+          description:
+            "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
         },
         {
           name: "args",
-          description: "Arguments to pass to script",
+          description: "Arguments to pass to the script",
           isOptional: true,
           isVariadic: true,
         },
@@ -912,22 +928,24 @@ const completionSpec: Fig.Spec = {
       options: [
         {
           name: "-h",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
         {
           name: "--help",
-          description: "Show help",
+          description: "Print the script's help page instead of running it",
           isRepeatable: false,
         },
       ],
       args: [
         {
           name: "script",
+          description:
+            "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
         },
         {
           name: "args",
-          description: "Arguments to pass to script",
+          description: "Arguments to pass to the script",
           isOptional: true,
           isVariadic: true,
         },
@@ -938,7 +956,7 @@ const completionSpec: Fig.Spec = {
     {
       name: "--completions",
       description:
-        "Outputs completions for the specified shell for completing the `usage` CLI itself",
+        "Print a completion script for the `usage` CLI itself, for the named shell",
       isRepeatable: false,
       args: {
         name: "completions",
@@ -946,7 +964,7 @@ const completionSpec: Fig.Spec = {
     },
     {
       name: "--usage-spec",
-      description: "Outputs a `usage.kdl` spec for this CLI itself",
+      description: "Print the usage spec for the `usage` CLI itself",
       isRepeatable: false,
     },
     {
diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index 59e59edee..82575c5a8 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -1,20 +1,24 @@
 .TH USAGE 1
 .SH NAME
-usage \- CLI for working with usage\-based CLIs
+usage \- Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one
 .SH SYNOPSIS
 \fBusage\fR <COMMAND>
 \fBusage\fR \-\-completions <COMPLETIONS>
 \fBusage\fR \-\-usage\-spec
 .SH DESCRIPTION
-CLI for working with usage\-based CLIs
+Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one
+.PP
+A usage spec describes a CLI's commands, flags, and arguments once, in KDL. Most commands here read one: a `.usage.kdl` file given with `\-f`, a script whose `#USAGE` comments declare it, or `\-` for stdin. A binary built with the Rust framework prints its own spec, so a pipeline like `mycli __usage_spec__ | usage generate markdown \-f \-` needs no file at all.
+.PP
+Guides and a reference for every command: https://usage.jdx.dev/cli/
 .PP
 .SH OPTIONS
 .TP
 \fB\-\-completions\fR \fI<COMPLETIONS>\fR
-Outputs completions for the specified shell for completing the `usage` CLI itself
+Print a completion script for the `usage` CLI itself, for the named shell
 .TP
 \fB\-\-usage\-spec\fR
-Outputs a `usage.kdl` spec for this CLI itself
+Print the usage spec for the `usage` CLI itself
 .TP
 \fB\-h, \-\-help\fR
 Print help
@@ -24,7 +28,7 @@ Print version
 .SH COMMANDS
 .TP
 \fBbash\fR
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 .TP
 \fBcomplete\-word\fR
 Generate shell completion candidates for a partial command line
@@ -36,7 +40,7 @@ Generate shell completion candidates for a partial command line
 Compare two usage specs and report what changed about the interface
 .TP
 \fBexec\fR
-Execute a script, parsing args and exposing them as environment variables
+Run a script through any interpreter, with its parsed arguments as environment variables
 .RS
 \fIAliases: \fRx
 .RE
@@ -45,34 +49,34 @@ Execute a script, parsing args and exposing them as environment variables
 Explain what a command line binds to
 .TP
 \fBfish\fR
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 .TP
 \fBgenerate\fR
-Generate completions, documentation, and other artifacts from usage specs
+Generate completions, docs, manpages, SDKs, and parse tables from a usage spec
 .RS
 \fIAliases: \fRg
 .RE
 .TP
 \fBgenerate completion\fR
-Generate shell completion scripts for bash, fish, nu, powershell, or zsh
+Generate a shell completion script for bash, fish, nu, powershell, or zsh
 .RS
 \fIAliases: \fRc
 .RE
 .TP
 \fBgenerate completion\-init\fR
-Generate a shell init script that auto\-completes any usage shebang script on $PATH
+Generate a shell init script that completes every usage\-shebang script on PATH
 .RS
 \fIAliases: \fRci
 .RE
 .TP
 \fBgenerate fig\fR
-Generate Fig completion spec for Amazon Q / Fig
+Generate a Fig completion spec, for Amazon Q and Fig
 .TP
 \fBgenerate go\fR
 Generate Go parse tables from a usage spec
 .TP
 \fBgenerate json\fR
-Outputs a usage spec in json format
+Print a usage spec as JSON
 .TP
 \fBgenerate json\-schema\fR
 Generate a JSON Schema for a CLI's config file from its usage spec
@@ -84,7 +88,7 @@ Generate a manpage from a usage spec
 .RE
 .TP
 \fBgenerate markdown\fR
-Generate markdown documentation from usage specs
+Generate Markdown documentation from a usage spec
 .RS
 \fIAliases: \fRmd
 .RE
@@ -93,7 +97,7 @@ Generate markdown documentation from usage specs
 Generate a type\-safe SDK from a usage spec
 .TP
 \fBlint\fR
-Lint a usage spec file for common issues
+Lint a usage spec for mistakes that still parse
 .TP
 \fBmcp\fR
 Serve a usage spec over the Model Context Protocol
@@ -102,20 +106,28 @@ Serve a usage spec over the Model Context Protocol
 .RE
 .TP
 \fBpowershell\fR
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 .TP
 \fBsponsors\fR
 Show the companies sponsoring usage and the jdx.dev open source tools
 .TP
 \fBzsh\fR
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 .SH "USAGE BASH"
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env \-S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`\-\-force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`\-h` and `\-\-help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 .PP
 \fBUsage:\fR usage bash [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -123,21 +135,24 @@ to properly escape and quote values with spaces in them.
 .PP
 .TP
 \fB\-h\fR
-Show help
+Print the script's help page instead of running it
 .TP
 \fB\-\-help\fR
-Show help
+Print the script's help page instead of running it
 \fBArguments:\fR
 .PP
 .TP
+\fB<SCRIPT>\fR
+The script to run; its spec is read from the `#USAGE` comments at the top of the file
+.TP
 \fB<ARGS>\fR
-Arguments to pass to script
+Arguments to pass to the script
 
 Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 .SH "USAGE COMPLETE-WORD"
 Generate shell completion candidates for a partial command line
 
-This is used internally by shell completion scripts to provide intelligent completions for commands, flags, and arguments.
+What the scripts from `usage generate completion` run on every Tab: they pass the words typed so far and read back one candidate per line. Useful by hand, too, for checking what a spec offers at a given point without installing anything.
 .PP
 \fBUsage:\fR usage complete\-word [OPTIONS] [<WORDS>] ...
 .PP
@@ -145,15 +160,16 @@ This is used internally by shell completion scripts to provide intelligent compl
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-Usage spec file or script with usage shebang, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-s, \-\-spec\fR \fI<SPEC>\fR
-Raw string spec input
+The spec itself, as a string, instead of a file
 .TP
 \fB\-\-cword\fR \fI<CWORD>\fR
-Current word index
+Index of the word being completed; defaults to the last word
 .TP
 \fB\-\-shell\fR \fI<SHELL>\fR
+The shell the candidates are for, which decides how they are quoted
 .RS
 \fIDefault: \fRbash
 .RE
@@ -164,7 +180,7 @@ Print help
 .PP
 .TP
 \fB<WORDS>\fR
-User's input from the command line
+The words typed so far, starting with the program name
 .SH "USAGE DIFF"
 Compare two usage specs and report what changed about the interface
 
@@ -209,7 +225,11 @@ The spec as it was, typically the released one, use "\-" to read from stdin
 \fB<NEW>\fR
 The spec as it is now, use "\-" to read from stdin
 .SH "USAGE EXEC"
-Execute a script, parsing args and exposing them as environment variables
+Run a script through any interpreter, with its parsed arguments as environment variables
+
+For scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env \-S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.
+
+`\-h` and `\-\-help` print the script's help page rather than this one.
 .PP
 \fBUsage:\fR usage exec [OPTIONS] <COMMAND> <BIN> [<ARGS>] ...
 .PP
@@ -217,21 +237,21 @@ Execute a script, parsing args and exposing them as environment variables
 .PP
 .TP
 \fB\-h\fR
-Show help
+Print the script's help page instead of running it
 .TP
 \fB\-\-help\fR
-Show help
+Print the script's help page instead of running it
 \fBArguments:\fR
 .PP
 .TP
 \fB<COMMAND>\fR
-command to execute after parsing usage spec
+The interpreter to run the script with, such as `node` or `python3`
 .TP
 \fB<BIN>\fR
-path to script to execute
+The script to run
 .TP
 \fB<ARGS>\fR
-arguments to pass to script
+Arguments to pass to the script
 .SH "USAGE EXPLAIN"
 Explain what a command line binds to
 
@@ -245,10 +265,10 @@ command line does not parse: the report succeeded, and that is the case worth a
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A usage spec file or script with a usage shebang, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-s, \-\-spec\fR \fI<SPEC>\fR
-Raw string spec input
+The spec itself, as a string, instead of a file
 .TP
 \fB\-\-format\fR \fI<FORMAT>\fR
 Output format
@@ -274,12 +294,20 @@ The command line to explain, starting with the program name
 
 `usage`'s own flags come before it, and flag parsing ends at the program name, so both `explain \-f f.kdl mycli \-\-env=prod` and `explain \-f f.kdl \-\- mycli \-\-env=prod` work. Separate with `\-\-` when the explained line carries its own: the first `\-\-` is still `usage`'s separator, so `explain \-f f.kdl mycli a \-\- b` loses one.
 .SH "USAGE FISH"
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env \-S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`\-\-force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`\-h` and `\-\-help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 .PP
 \fBUsage:\fR usage fish [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -287,19 +315,22 @@ to properly escape and quote values with spaces in them.
 .PP
 .TP
 \fB\-h\fR
-Show help
+Print the script's help page instead of running it
 .TP
 \fB\-\-help\fR
-Show help
+Print the script's help page instead of running it
 \fBArguments:\fR
 .PP
 .TP
+\fB<SCRIPT>\fR
+The script to run; its spec is read from the `#USAGE` comments at the top of the file
+.TP
 \fB<ARGS>\fR
-Arguments to pass to script
+Arguments to pass to the script
 
 Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 .SH "USAGE GENERATE"
-Generate completions, documentation, and other artifacts from usage specs
+Generate completions, docs, manpages, SDKs, and parse tables from a usage spec
 .PP
 \fBUsage:\fR usage generate [OPTIONS] <COMMAND>
 .PP
@@ -309,7 +340,9 @@ Generate completions, documentation, and other artifacts from usage specs
 \fB\-h, \-\-help\fR
 Print help
 .SH "USAGE GENERATE COMPLETION"
-Generate shell completion scripts for bash, fish, nu, powershell, or zsh
+Generate a shell completion script for bash, fish, nu, powershell, or zsh
+
+The script is a shim: on each Tab it hands the words typed so far to `usage complete\-word`, so `usage` must be installed wherever the script is. The spec comes from `\-\-file`, or from running `\-\-usage\-cmd` at completion time, which keeps a CLI that prints its own spec from ever going stale.
 .PP
 \fBUsage:\fR usage generate completion [OPTIONS] <SHELL> <BIN>
 .PP
@@ -325,15 +358,13 @@ Writes the script file and nothing else: no shell rc file and no PowerShell prof
 Replace a file at the target path that usage did not write
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A .usage.kdl spec file to use for generating completions, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-\-cache\-key\fR \fI<CACHE_KEY>\fR
-A cache key to use for storing the results of calling the CLI with \-\-usage\-cmd
+Cache what \-\-usage\-cmd prints under this key, so it runs once per key rather than on every Tab; the CLI's version is a good key
 .TP
 \fB\-\-usage\-bin\fR \fI<USAGE_BIN>\fR
-Override the bin used for calling back to usage\-cli
-
-You may need to set this if you have a different bin named "usage"
+The `usage` executable the script calls back to, when it is not `usage` on PATH
 .RS
 \fIDefault: \fRusage
 .RE
@@ -342,7 +373,9 @@ You may need to set this if you have a different bin named "usage"
 .RE
 .TP
 \fB\-\-usage\-cmd\fR \fI<USAGE_CMD>\fR
-A command which generates a usage spec e.g.: `mycli \-\-usage` or `mycli completion usage` Defaults to "$bin \-\-usage"
+A command that prints the CLI's spec, run in place of reading \-\-file
+
+For a CLI that answers with its own spec, such as `mycli __usage_spec__`, so the script always completes the version that is installed. Required unless \-\-file is given.
 .TP
 \fB\-h, \-\-help\fR
 Print help
@@ -350,14 +383,14 @@ Print help
 .PP
 .TP
 \fB<SHELL>\fR
-Shell to generate completions for
+The shell to generate the script for
 .TP
 \fB<BIN>\fR
-The CLI which we're generating completions for
+The name of the CLI being completed, as it is typed at the prompt
 .SH "USAGE GENERATE COMPLETION-INIT"
-Generate a shell init script that auto\-completes any usage shebang script on $PATH
+Generate a shell init script that completes every usage\-shebang script on PATH
 
-Source the output once from your shell rc (e.g. ~/.bashrc) to enable tab\-completion for any executable whose first line is a `usage` shebang — no per\-script `usage g completion` step required.
+Source it once from the shell's rc file and Tab works on any executable whose first line is a `usage` shebang, with no per\-script `usage generate completion` step. bash and zsh register a fallback completer that asks `usage complete\-word` when the command has such a shebang; fish has no fallback, so it scans PATH once at startup and registers each script it finds.
 .PP
 \fBUsage:\fR usage generate completion\-init [OPTIONS] <SHELL>
 .PP
@@ -365,9 +398,7 @@ Source the output once from your shell rc (e.g. ~/.bashrc) to enable tab\-comple
 .PP
 .TP
 \fB\-\-usage\-bin\fR \fI<USAGE_BIN>\fR
-Override the bin used for calling back to usage\-cli
-
-You may need to set this if you have a different bin named "usage"
+The `usage` executable the script calls back to, when it is not `usage` on PATH
 .RS
 \fIDefault: \fRusage
 .RE
@@ -381,9 +412,9 @@ Print help
 .PP
 .TP
 \fB<SHELL>\fR
-Shell to generate the init script for
+The shell to generate the script for
 .SH "USAGE GENERATE FIG"
-Generate Fig completion spec for Amazon Q / Fig
+Generate a Fig completion spec, for Amazon Q and Fig
 .PP
 \fBUsage:\fR usage generate fig [OPTIONS]
 .PP
@@ -391,13 +422,13 @@ Generate Fig completion spec for Amazon Q / Fig
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A usage spec taken in as a file, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-\-out\-file\fR \fI<OUT_FILE>\fR
-File path where the generated Fig spec will be saved, or "\-" for stdout
+Where to write the spec, or "\-" for stdout (default)
 .TP
 \fB\-\-spec\fR \fI<SPEC>\fR
-Raw string spec input
+The spec itself, as a string, instead of a file
 .TP
 \fB\-h, \-\-help\fR
 Print help
@@ -414,21 +445,23 @@ The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A usage spec taken in as a file, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-o, \-\-out\-file\fR \fI<OUT_FILE>\fR
-File path where the generated Go source will be saved, or "\-" for stdout
+Where to write the Go source, or "\-" for stdout (default)
 .TP
 \fB\-p, \-\-package\fR \fI<PACKAGE>\fR
 Go package clause for the generated file (defaults to the spec's bin name)
 .TP
 \fB\-\-spec\fR \fI<SPEC>\fR
-Raw string spec input
+The spec itself, as a string, instead of a file
 .TP
 \fB\-h, \-\-help\fR
 Print help
 .SH "USAGE GENERATE JSON"
-Outputs a usage spec in json format
+Print a usage spec as JSON
+
+The same document the KDL describes, with included files merged and defaults filled in, for a tool that would rather not parse KDL itself.
 .PP
 \fBUsage:\fR usage generate json [OPTIONS]
 .PP
@@ -436,10 +469,10 @@ Outputs a usage spec in json format
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A usage spec taken in as a file, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-\-spec\fR \fI<SPEC>\fR
-raw string spec input
+The spec itself, as a string, instead of a file
 .TP
 \fB\-\-view\fR \fI<VIEW>\fR
 Render one spec\-declared executable view
@@ -448,6 +481,8 @@ Render one spec\-declared executable view
 Print help
 .SH "USAGE GENERATE JSON-SCHEMA"
 Generate a JSON Schema for a CLI's config file from its usage spec
+
+Built from the spec's `config` block: each `prop` becomes a property with its type, default, and help, so an editor can complete and validate the file the CLI reads. A spec whose settings cannot live in a file is an error rather than an empty schema.
 .PP
 \fBUsage:\fR usage generate json\-schema [OPTIONS]
 .PP
@@ -455,13 +490,13 @@ Generate a JSON Schema for a CLI's config file from its usage spec
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A usage spec taken in as a file, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-\-out\-file\fR \fI<OUT_FILE>\fR
 Write the schema here instead of to stdout
 .TP
 \fB\-\-spec\fR \fI<SPEC>\fR
-raw string spec input
+The spec itself, as a string, instead of a file
 .TP
 \fB\-\-title\fR \fI<TITLE>\fR
 The schema's title, shown by editors
@@ -480,7 +515,7 @@ Generate a manpage from a usage spec
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A usage spec taken in as a file, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-\-view\fR \fI<VIEW>\fR
 Render one spec\-declared executable view
@@ -499,7 +534,9 @@ Common sections: \- 1: User commands \- 5: File formats \- 7: Miscellaneous \- 8
 \fB\-h, \-\-help\fR
 Print help
 .SH "USAGE GENERATE MARKDOWN"
-Generate markdown documentation from usage specs
+Generate Markdown documentation from a usage spec
+
+One page by default, or a page per command with \-\-multi. Every part of the output comes from a Tera template that \-\-template can replace.
 .PP
 \fBUsage:\fR usage generate markdown [OPTIONS]
 .PP
@@ -507,7 +544,7 @@ Generate markdown documentation from usage specs
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A usage spec taken in as a file, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-\-view\fR \fI<VIEW>\fR
 Render one spec\-declared executable view
@@ -519,7 +556,7 @@ Render each subcommand as a separate markdown file
 Escape HTML in markdown
 .TP
 \fB\-\-out\-dir\fR \fI<OUT_DIR>\fR
-Output markdown files to this directory (required when using \-\-multi)
+Directory for the per\-command pages (required with \-\-multi)
 .TP
 \fB\-\-out\-file\fR \fI<OUT_FILE>\fR
 Output file path for single\-file markdown generation, or "\-" for stdout (default)
@@ -528,15 +565,17 @@ Output file path for single\-file markdown generation, or "\-" for stdout (defau
 Replace `<pre>` tags with markdown code fences
 .TP
 \fB\-\-url\-prefix\fR \fI<URL_PREFIX>\fR
-Prefix to add to all URLs
+Prefix for the links between pages, such as /cli/reference
 .TP
 \fB\-\-template\fR \fI<TEMPLATE>\fR
-Override a Tera template with NAME=PATH
+Replace a built\-in Tera template, as NAME=PATH; the names are spec, index, command, argument, flag, and config
 .TP
 \fB\-h, \-\-help\fR
 Print help
 .SH "USAGE GENERATE SDK"
 Generate a type\-safe SDK from a usage spec
+
+The SDK is a subprocess wrapper: typed arguments, flags, and choices for every command, and a client that builds the argument list and runs the binary.
 .PP
 \fBUsage:\fR usage generate sdk [OPTIONS]
 .PP
@@ -544,24 +583,28 @@ Generate a type\-safe SDK from a usage spec
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-A usage spec taken in as a file
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .TP
 \fB\-l, \-\-language\fR \fI<LANGUAGE>\fR
 Target language for the SDK
 .TP
 \fB\-o, \-\-output\fR \fI<OUTPUT>\fR
-Output directory for generated SDK files
+Directory to write the SDK into
 .TP
 \fB\-p, \-\-package\-name\fR \fI<PACKAGE_NAME>\fR
 Override the package/module name (defaults to spec bin name)
 .TP
 \fB\-\-spec\fR \fI<SPEC>\fR
-Raw string spec input
+The spec itself, as a string, instead of a file
 .TP
 \fB\-h, \-\-help\fR
 Print help
 .SH "USAGE LINT"
-Lint a usage spec file for common issues
+Lint a usage spec for mistakes that still parse
+
+A spec can be valid KDL and still be wrong: a flag or subcommand declared twice, a required argument after an optional one, a variadic argument that is not last, a command or flag with no help, an example its own spec cannot parse. Each finding carries a code such as `duplicate\-flag`, and `\-\-format json` prints the findings as a list for a script to act on.
+
+Exits 1 when there is an error, or a warning under `\-\-warnings\-as\-errors`.
 .PP
 \fBUsage:\fR usage lint [OPTIONS] <FILE>
 .PP
@@ -588,12 +631,17 @@ Print help
 .PP
 .TP
 \fB<FILE>\fR
-A usage spec file to lint, use "\-" to read from stdin
+A usage spec file, or a script with a usage shebang; "\-" reads stdin
 .SH "USAGE MCP"
 Serve a usage spec over the Model Context Protocol
 
 Reads JSON\-RPC over stdin and writes responses to stdout, which is how MCP
 clients launch a local server. Point one at `usage mcp \-f mycli.usage.kdl`.
+
+Two tools are served: `list_commands`, every command with its effect, and
+`describe_command`, one command's help, flags, and arguments. Together they
+let an agent learn what a CLI does, and what running it would touch, without
+running it.
 .PP
 \fBUsage:\fR usage mcp [OPTIONS]
 .PP
@@ -601,20 +649,28 @@ clients launch a local server. Point one at `usage mcp \-f mycli.usage.kdl`.
 .PP
 .TP
 \fB\-f, \-\-file\fR \fI<FILE>\fR
-Usage spec file (not "\-": stdin is the MCP transport)
+A usage spec file, or a script with a usage shebang (not "\-": stdin is the MCP transport)
 .TP
 \fB\-s, \-\-spec\fR \fI<SPEC>\fR
-Raw string spec input
+The spec itself, as a string, instead of a file
 .TP
 \fB\-h, \-\-help\fR
 Print help
 .SH "USAGE POWERSHELL"
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env \-S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`\-\-force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`\-h` and `\-\-help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 .PP
 \fBUsage:\fR usage powershell [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -622,15 +678,18 @@ to properly escape and quote values with spaces in them.
 .PP
 .TP
 \fB\-h\fR
-Show help
+Print the script's help page instead of running it
 .TP
 \fB\-\-help\fR
-Show help
+Print the script's help page instead of running it
 \fBArguments:\fR
 .PP
 .TP
+\fB<SCRIPT>\fR
+The script to run; its spec is read from the `#USAGE` comments at the top of the file
+.TP
 \fB<ARGS>\fR
-Arguments to pass to script
+Arguments to pass to the script
 
 Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 .SH "USAGE SPONSORS"
@@ -644,12 +703,20 @@ Show the companies sponsoring usage and the jdx.dev open source tools
 \fB\-h, \-\-help\fR
 Print help
 .SH "USAGE ZSH"
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env \-S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`\-\-force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`\-h` and `\-\-help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 .PP
 \fBUsage:\fR usage zsh [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -657,15 +724,18 @@ to properly escape and quote values with spaces in them.
 .PP
 .TP
 \fB\-h\fR
-Show help
+Print the script's help page instead of running it
 .TP
 \fB\-\-help\fR
-Show help
+Print the script's help page instead of running it
 \fBArguments:\fR
 .PP
 .TP
+\fB<SCRIPT>\fR
+The script to run; its spec is read from the `#USAGE` comments at the top of the file
+.TP
 \fB<ARGS>\fR
-Arguments to pass to script
+Arguments to pass to the script
 
 Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 .SH SOURCE
diff --git a/cli/src/cli/complete_word.rs b/cli/src/cli/complete_word.rs
index dcf5a9155..28cc50d75 100644
--- a/cli/src/cli/complete_word.rs
+++ b/cli/src/cli/complete_word.rs
@@ -55,26 +55,28 @@ fn render_completer_run(run: &str, ctx: &tera::Context) -> tera::TeraResult<Stri
 
 /// Generate shell completion candidates for a partial command line
 ///
-/// This is used internally by shell completion scripts to provide
-/// intelligent completions for commands, flags, and arguments.
+/// What the scripts from `usage generate completion` run on every Tab: they pass the words
+/// typed so far and read back one candidate per line. Useful by hand, too, for checking what
+/// a spec offers at a given point without installing anything.
 #[derive(Debug, Args)]
 #[usage(alias = "cw", effect = "read")]
 pub struct CompleteWord {
-    /// User's input from the command line
+    /// The words typed so far, starting with the program name
     words: Vec<String>,
 
-    /// Usage spec file or script with usage shebang, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: Option<PathBuf>,
 
-    /// Raw string spec input
+    /// The spec itself, as a string, instead of a file
     #[usage(short, long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 
-    /// Current word index
+    /// Index of the word being completed; defaults to the last word
     #[usage(long)]
     cword: Option<usize>,
 
+    /// The shell the candidates are for, which decides how they are quoted
     #[usage(
         long,
         default = "bash",
diff --git a/cli/src/cli/exec.rs b/cli/src/cli/exec.rs
index 805ee6875..c7ac0ce15 100644
--- a/cli/src/cli/exec.rs
+++ b/cli/src/cli/exec.rs
@@ -10,24 +10,32 @@ use usage::Spec;
 
 use crate::env;
 
-/// Execute a script, parsing args and exposing them as environment variables
+/// Run a script through any interpreter, with its parsed arguments as environment variables
+///
+/// For scripts in a language `usage` has no dedicated command for. A shebang of
+/// `#!/usr/bin/env -S usage exec node` parses the arguments against the `USAGE` comments at the
+/// top of the file, then runs `node <script> <args>` with each flag and argument exported as
+/// `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is
+/// read from it instead of from the comments.
+///
+/// `-h` and `--help` print the script's help page rather than this one.
 #[derive(Debug, Args)]
 // The words after the script are the script's, so a flag `usage` does not know is a value to
 // forward rather than a mistake to report — the root's `error` stops here.
 #[usage(alias = "x", unknown_flags = "value")]
 pub struct Exec {
-    /// command to execute after parsing usage spec
+    /// The interpreter to run the script with, such as `node` or `python3`
     command: String,
-    /// path to script to execute
+    /// The script to run
     bin: PathBuf,
-    /// arguments to pass to script
+    /// Arguments to pass to the script
     args: Vec<String>,
 
-    /// Show help
+    /// Print the script's help page instead of running it
     #[usage(short)]
     h: bool,
 
-    /// Show help
+    /// Print the script's help page instead of running it
     #[usage(long)]
     help: bool,
 }
diff --git a/cli/src/cli/explain.rs b/cli/src/cli/explain.rs
index 00ed5dacc..ed63ccd7c 100644
--- a/cli/src/cli/explain.rs
+++ b/cli/src/cli/explain.rs
@@ -37,11 +37,11 @@ use crate::cli::{empty_mount_answers, OutputFormat};
 // nothing.
 #[usage(effect = "read", verbatim_doc_comment)]
 pub struct Explain {
-    /// A usage spec file or script with a usage shebang, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long, value_hint = usage_rs::ValueHint::FilePath)]
     file: Option<PathBuf>,
 
-    /// Raw string spec input
+    /// The spec itself, as a string, instead of a file
     #[usage(short, long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 
diff --git a/cli/src/cli/generate/completion.rs b/cli/src/cli/generate/completion.rs
index dbb125efd..35d34b607 100644
--- a/cli/src/cli/generate/completion.rs
+++ b/cli/src/cli/generate/completion.rs
@@ -5,15 +5,20 @@ use usage_rs::Args;
 
 use super::parse_file_or_stdin;
 
-/// Generate shell completion scripts for bash, fish, nu, powershell, or zsh
+/// Generate a shell completion script for bash, fish, nu, powershell, or zsh
+///
+/// The script is a shim: on each Tab it hands the words typed so far to `usage complete-word`,
+/// so `usage` must be installed wherever the script is. The spec comes from `--file`, or from
+/// running `--usage-cmd` at completion time, which keeps a CLI that prints its own spec from
+/// ever going stale.
 #[derive(Args)]
 #[usage(alias = "c", alias_hidden("complete", "completions"), effect = "read")]
 pub struct Completion {
-    /// Shell to generate completions for
+    /// The shell to generate the script for
     #[usage(choices("bash", "fish", "nu", "powershell", "zsh"))]
     shell: String,
 
-    /// The CLI which we're generating completions for
+    /// The name of the CLI being completed, as it is typed at the prompt
     bin: String,
 
     /// Install the script where this shell looks for it, instead of printing it
@@ -28,23 +33,22 @@ pub struct Completion {
     #[usage(long, requires = "--install", effect = "write")]
     force: bool,
 
-    /// A .usage.kdl spec file to use for generating completions, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: Option<PathBuf>,
 
-    /// A cache key to use for storing the results of calling the CLI with --usage-cmd
+    /// Cache what --usage-cmd prints under this key, so it runs once per key rather than on every Tab; the CLI's version is a good key
     #[usage(long, requires = "--usage-cmd")]
     cache_key: Option<String>,
 
-    /// Override the bin used for calling back to usage-cli
-    ///
-    /// You may need to set this if you have a different bin named "usage"
+    /// The `usage` executable the script calls back to, when it is not `usage` on PATH
     #[usage(long, default = "usage", env = "JDX_USAGE_BIN")]
     usage_bin: String,
 
-    /// A command which generates a usage spec
-    /// e.g.: `mycli --usage` or `mycli completion usage`
-    /// Defaults to "$bin --usage"
+    /// A command that prints the CLI's spec, run in place of reading --file
+    ///
+    /// For a CLI that answers with its own spec, such as `mycli __usage_spec__`, so the script
+    /// always completes the version that is installed. Required unless --file is given.
     #[usage(long, required_unless = "--file")]
     usage_cmd: Option<String>,
 }
diff --git a/cli/src/cli/generate/completion_init.rs b/cli/src/cli/generate/completion_init.rs
index c61a64a5e..edcfa2449 100644
--- a/cli/src/cli/generate/completion_init.rs
+++ b/cli/src/cli/generate/completion_init.rs
@@ -1,11 +1,13 @@
 use usage::complete::complete_init;
 use usage_rs::Args;
 
-/// Generate a shell init script that auto-completes any usage shebang script on $PATH
+/// Generate a shell init script that completes every usage-shebang script on PATH
 ///
-/// Source the output once from your shell rc (e.g. ~/.bashrc) to enable
-/// tab-completion for any executable whose first line is a `usage` shebang —
-/// no per-script `usage g completion` step required.
+/// Source it once from the shell's rc file and Tab works on any executable whose first line
+/// is a `usage` shebang, with no per-script `usage generate completion` step. bash and zsh
+/// register a fallback completer that asks `usage complete-word` when the command has such a
+/// shebang; fish has no fallback, so it scans PATH once at startup and registers each script
+/// it finds.
 #[derive(Args)]
 #[usage(
     alias = "ci",
@@ -13,13 +15,11 @@ use usage_rs::Args;
     effect = "read"
 )]
 pub struct CompletionInit {
-    /// Shell to generate the init script for
+    /// The shell to generate the script for
     #[usage(choices("bash", "fish", "zsh"))]
     shell: String,
 
-    /// Override the bin used for calling back to usage-cli
-    ///
-    /// You may need to set this if you have a different bin named "usage"
+    /// The `usage` executable the script calls back to, when it is not `usage` on PATH
     #[usage(long, default = "usage", env = "JDX_USAGE_BIN")]
     usage_bin: String,
 }
diff --git a/cli/src/cli/generate/fig.rs b/cli/src/cli/generate/fig.rs
index a7d076b05..f3ce10b52 100644
--- a/cli/src/cli/generate/fig.rs
+++ b/cli/src/cli/generate/fig.rs
@@ -44,15 +44,15 @@ mod description_format {
     }
 }
 
-/// Generate Fig completion spec for Amazon Q / Fig
+/// Generate a Fig completion spec, for Amazon Q and Fig
 #[derive(Args)]
 #[usage(effect = "read")]
 pub struct Fig {
-    /// A usage spec taken in as a file, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: Option<PathBuf>,
 
-    /// File path where the generated Fig spec will be saved, or "-" for stdout
+    /// Where to write the spec, or "-" for stdout (default)
     #[usage(
         long,
         value_hint = usage_rs::ValueHint::FilePath,
@@ -60,7 +60,7 @@ pub struct Fig {
     )]
     out_file: Option<PathBuf>,
 
-    /// Raw string spec input
+    /// The spec itself, as a string, instead of a file
     #[usage(long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 }
diff --git a/cli/src/cli/generate/go.rs b/cli/src/cli/generate/go.rs
index 6e47eb075..339efca53 100644
--- a/cli/src/cli/generate/go.rs
+++ b/cli/src/cli/generate/go.rs
@@ -16,11 +16,11 @@ use crate::cli::generate;
 #[derive(Args)]
 #[usage(effect = "read")]
 pub struct Go {
-    /// A usage spec taken in as a file, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: Option<PathBuf>,
 
-    /// File path where the generated Go source will be saved, or "-" for stdout
+    /// Where to write the Go source, or "-" for stdout (default)
     #[usage(
         short,
         long,
@@ -33,7 +33,7 @@ pub struct Go {
     #[usage(short, long)]
     package: Option<String>,
 
-    /// Raw string spec input
+    /// The spec itself, as a string, instead of a file
     #[usage(long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 }
diff --git a/cli/src/cli/generate/json.rs b/cli/src/cli/generate/json.rs
index f66c7c4ff..625863e3e 100644
--- a/cli/src/cli/generate/json.rs
+++ b/cli/src/cli/generate/json.rs
@@ -3,15 +3,18 @@ use std::path::PathBuf;
 use usage::miette::IntoDiagnostic;
 use usage::miette::Result;
 
-/// Outputs a usage spec in json format
+/// Print a usage spec as JSON
+///
+/// The same document the KDL describes, with included files merged and defaults filled in,
+/// for a tool that would rather not parse KDL itself.
 #[derive(usage_rs::Args)]
 #[usage(effect = "read")]
 pub struct Json {
-    /// A usage spec taken in as a file, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: Option<PathBuf>,
 
-    /// raw string spec input
+    /// The spec itself, as a string, instead of a file
     #[usage(long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 
diff --git a/cli/src/cli/generate/json_schema.rs b/cli/src/cli/generate/json_schema.rs
index dba96da6d..d4be5edfb 100644
--- a/cli/src/cli/generate/json_schema.rs
+++ b/cli/src/cli/generate/json_schema.rs
@@ -7,10 +7,14 @@ use crate::schema::{config_schema, SchemaOptions};
 use usage::miette::Result;
 
 /// Generate a JSON Schema for a CLI's config file from its usage spec
+///
+/// Built from the spec's `config` block: each `prop` becomes a property with its type,
+/// default, and help, so an editor can complete and validate the file the CLI reads. A spec
+/// whose settings cannot live in a file is an error rather than an empty schema.
 #[derive(usage_rs::Args)]
 #[usage(effect = "read")]
 pub struct JsonSchema {
-    /// A usage spec taken in as a file, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: Option<PathBuf>,
 
@@ -22,7 +26,7 @@ pub struct JsonSchema {
     )]
     out_file: Option<PathBuf>,
 
-    /// raw string spec input
+    /// The spec itself, as a string, instead of a file
     #[usage(long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 
diff --git a/cli/src/cli/generate/manpage.rs b/cli/src/cli/generate/manpage.rs
index 9878cfec6..161a0ada2 100644
--- a/cli/src/cli/generate/manpage.rs
+++ b/cli/src/cli/generate/manpage.rs
@@ -8,7 +8,7 @@ use usage_rs::Args;
 #[derive(Args)]
 #[usage(alias = "man", effect = "read")]
 pub struct Manpage {
-    /// A usage spec taken in as a file, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: PathBuf,
 
diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs
index fa633cdf9..4695871a1 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -5,11 +5,14 @@ use usage::docs::markdown::{MarkdownRenderer, MarkdownTemplate};
 use usage::error::UsageErr;
 use usage_rs::Args;
 
-/// Generate markdown documentation from usage specs
+/// Generate Markdown documentation from a usage spec
+///
+/// One page by default, or a page per command with --multi. Every part of the output comes
+/// from a Tera template that --template can replace.
 #[derive(Args)]
 #[usage(alias = "md", effect = "read")]
 pub struct Markdown {
-    /// A usage spec taken in as a file, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: PathBuf,
 
@@ -27,7 +30,7 @@ pub struct Markdown {
     #[usage(long)]
     html_encode: bool,
 
-    /// Output markdown files to this directory (required when using --multi)
+    /// Directory for the per-command pages (required with --multi)
     #[usage(
         long,
         value_hint = usage_rs::ValueHint::DirPath,
@@ -49,11 +52,11 @@ pub struct Markdown {
     #[usage(long)]
     replace_pre_with_code_fences: bool,
 
-    /// Prefix to add to all URLs
+    /// Prefix for the links between pages, such as /cli/reference
     #[usage(long)]
     url_prefix: Option<String>,
 
-    /// Override a Tera template with NAME=PATH
+    /// Replace a built-in Tera template, as NAME=PATH; the names are spec, index, command, argument, flag, and config
     #[usage(long)]
     template: Vec<String>,
 }
diff --git a/cli/src/cli/generate/mod.rs b/cli/src/cli/generate/mod.rs
index 1f88226c9..a3b024cba 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -14,7 +14,7 @@ mod manpage;
 mod markdown;
 mod sdk;
 
-/// Generate completions, documentation, and other artifacts from usage specs
+/// Generate completions, docs, manpages, SDKs, and parse tables from a usage spec
 // Cannot run alone, and every child starts at `read`, so the parent is `read` too.
 #[derive(usage_rs::Args)]
 #[usage(alias = "g", effect = "read", run)]
diff --git a/cli/src/cli/generate/sdk.rs b/cli/src/cli/generate/sdk.rs
index 7ff532a4a..2db0bb7f0 100644
--- a/cli/src/cli/generate/sdk.rs
+++ b/cli/src/cli/generate/sdk.rs
@@ -7,13 +7,16 @@ use crate::cli::generate;
 use usage::sdk::{SdkLanguage, SdkOptions};
 
 /// Generate a type-safe SDK from a usage spec
+///
+/// The SDK is a subprocess wrapper: typed arguments, flags, and choices for every command,
+/// and a client that builds the argument list and runs the binary.
 // The only generator whose output flag is required: it cannot print an SDK to stdout, so
 // every invocation writes a directory, and the effect belongs on the command rather than on
 // a flag that raises it.
 #[derive(Args)]
 #[usage(effect = "write")]
 pub struct Sdk {
-    /// A usage spec taken in as a file
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     #[usage(short, long)]
     file: Option<PathBuf>,
 
@@ -21,7 +24,7 @@ pub struct Sdk {
     #[usage(short, long, choices("typescript", "python"))]
     language: String,
 
-    /// Output directory for generated SDK files
+    /// Directory to write the SDK into
     #[usage(short, long)]
     output: PathBuf,
 
@@ -29,7 +32,7 @@ pub struct Sdk {
     #[usage(short, long)]
     package_name: Option<String>,
 
-    /// Raw string spec input
+    /// The spec itself, as a string, instead of a file
     #[usage(long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 }
diff --git a/cli/src/cli/lint.rs b/cli/src/cli/lint.rs
index 248069af4..de9d85c45 100644
--- a/cli/src/cli/lint.rs
+++ b/cli/src/cli/lint.rs
@@ -8,11 +8,18 @@ use usage::{Parser, Spec, SpecArg, SpecCommand, SpecFlag, SpecFlagAction};
 use crate::cli::generate::parse_file_or_stdin;
 use crate::cli::{empty_mount_answers, OutputFormat};
 
-/// Lint a usage spec file for common issues
+/// Lint a usage spec for mistakes that still parse
+///
+/// A spec can be valid KDL and still be wrong: a flag or subcommand declared twice, a required
+/// argument after an optional one, a variadic argument that is not last, a command or flag
+/// with no help, an example its own spec cannot parse. Each finding carries a code such as
+/// `duplicate-flag`, and `--format json` prints the findings as a list for a script to act on.
+///
+/// Exits 1 when there is an error, or a warning under `--warnings-as-errors`.
 #[derive(usage_rs::Args)]
 #[usage(effect = "read")]
 pub struct Lint {
-    /// A usage spec file to lint, use "-" to read from stdin
+    /// A usage spec file, or a script with a usage shebang; "-" reads stdin
     file: PathBuf,
 
     /// Output format
diff --git a/cli/src/cli/mcp.rs b/cli/src/cli/mcp.rs
index 2b69824e7..e6b8e4b06 100644
--- a/cli/src/cli/mcp.rs
+++ b/cli/src/cli/mcp.rs
@@ -43,16 +43,21 @@ means unknown — treat it as needing confirmation, not as safe.";
 ///
 /// Reads JSON-RPC over stdin and writes responses to stdout, which is how MCP
 /// clients launch a local server. Point one at `usage mcp -f mycli.usage.kdl`.
+///
+/// Two tools are served: `list_commands`, every command with its effect, and
+/// `describe_command`, one command's help, flags, and arguments. Together they
+/// let an agent learn what a CLI does, and what running it would touch, without
+/// running it.
 #[derive(Debug, usage_rs::Args)]
 #[usage(alias = "mcp-server", verbatim_doc_comment, effect = "read")]
 pub struct Mcp {
     // Unlike other subcommands this cannot be "-": stdin is the transport, so
     // reading the spec from it would consume the session.
-    /// Usage spec file (not "-": stdin is the MCP transport)
+    /// A usage spec file, or a script with a usage shebang (not "-": stdin is the MCP transport)
     #[usage(short, long)]
     file: Option<PathBuf>,
 
-    /// Raw string spec input
+    /// The spec itself, as a string, instead of a file
     #[usage(short, long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 }
diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index 4f27ded4a..0dc36796d 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -14,7 +14,14 @@ mod mcp;
 mod shell;
 mod sponsors;
 
-/// CLI for working with usage-based CLIs
+/// Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one
+///
+/// A usage spec describes a CLI's commands, flags, and arguments once, in KDL. Most commands
+/// here read one: a `.usage.kdl` file given with `-f`, a script whose `#USAGE` comments declare
+/// it, or `-` for stdin. A binary built with the Rust framework prints its own spec, so a
+/// pipeline like `mycli __usage_spec__ | usage generate markdown -f -` needs no file at all.
+///
+/// Guides and a reference for every command: https://usage.jdx.dev/cli/
 // `usage` parses its own command line with the parser it ships: the tables below are the same
 // ones an adopter's CLI compiles into, and `--usage-spec` prints the spec they emit rather
 // than a transcription of a clap command. Said here rather than in the doc comment, which is
@@ -64,7 +71,7 @@ pub struct Cli {
     #[usage(subcommand)]
     command: Command,
 
-    /// Outputs completions for the specified shell for completing the `usage` CLI itself
+    /// Print a completion script for the `usage` CLI itself, for the named shell
     // `--completions <shell>` is normally answered in `crate::run` before a parse happens,
     // because a shell init script asks for it on every new shell and it does not need a
     // subcommand to answer. It remains a real parsed field so direct callers of `Cli::run`
@@ -78,7 +85,7 @@ pub struct Cli {
     #[usage(long)]
     completions: Option<String>,
 
-    /// Outputs a `usage.kdl` spec for this CLI itself
+    /// Print the usage spec for the `usage` CLI itself
     #[usage(long)]
     usage_spec: bool,
 }
diff --git a/cli/src/cli/shell.rs b/cli/src/cli/shell.rs
index 0d83c819c..10d4c2058 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -18,19 +18,20 @@ use crate::env;
 /// derive refuses two variants wrapping one — and the shell to run is the command that ran.
 #[derive(Debug, Args)]
 pub struct Shell {
+    /// The script to run; its spec is read from the `#USAGE` comments at the top of the file
     script: PathBuf,
 
-    /// Arguments to pass to script
+    /// Arguments to pass to the script
     ///
     /// Anything `usage` does not recognise is a value rather than a mistake, which is what
     /// lets a shebang script take flags of its own.
     args: Vec<String>,
 
-    /// Show help
+    /// Print the script's help page instead of running it
     #[usage(short)]
     h: bool,
 
-    /// Show help
+    /// Print the script's help page instead of running it
     #[usage(long)]
     help: bool,
 }
@@ -42,12 +43,20 @@ pub struct Shell {
 /// the derive reads it a macro call is not one.
 macro_rules! shell_command {
     ($ty:ident, $program:literal, $about:tt) => {
-        #[doc = "Execute a shell script with the specified shell"]
+        #[doc = "Run a script whose usage spec is written in its own comments"]
         #[doc = ""]
-        #[doc = "Typically, this will be called by a script's shebang."]
+        #[doc = "Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel"]
+        #[doc = "hands the script and its arguments to `usage`, which parses them against the `#USAGE`"]
+        #[doc = "lines at the top of the file and then runs the script with this shell. Each flag and"]
+        #[doc = "argument reaches the script as an environment variable named `usage_<name>`, so"]
+        #[doc = "`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared"]
+        #[doc = "`var=#true` arrives as one string, joined with `shell_words::join()` so that an element"]
+        #[doc = "containing a space stays quoted."]
         #[doc = ""]
-        #[doc = "If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`"]
-        #[doc = "to properly escape and quote values with spaces in them."]
+        #[doc = "`-h` and `--help` print the script's help page rather than this one. The shell is found"]
+        #[doc = "on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and"]
+        #[doc = "`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how"]
+        #[doc = "`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL."]
         #[derive(Debug, Args)]
         // The words after the script are the script's, so a flag `usage` does not know is a
         // value to forward rather than a mistake to report — the root's `error` stops here.
diff --git a/cli/src/test.rs b/cli/src/test.rs
index 646c865d7..1fac4c389 100644
--- a/cli/src/test.rs
+++ b/cli/src/test.rs
@@ -14,14 +14,24 @@ fn shell_commands_keep_their_verbatim_long_help() {
         .find(|cmd| cmd.cmd.name == "bash")
         .expect("bash command");
     assert_eq!(bash.about, Some("Execute a shell script using bash"));
-    assert_eq!(
-        bash.long_about,
-        Some(
-            "Execute a shell script with the specified shell\n\n\
-             Typically, this will be called by a script's shebang.\n\n\
-             If using `var=#true` on args/flags, they will be joined with spaces using \
-             `shell_words::join()`\n\
-             to properly escape and quote values with spaces in them."
-        )
-    );
+    // Every line break of the doc comment is kept, which is what `verbatim_doc_comment` promises;
+    // without it the derive would reflow each paragraph into one line.
+    let expected = [
+        "Run a script whose usage spec is written in its own comments",
+        "",
+        "Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel",
+        "hands the script and its arguments to `usage`, which parses them against the `#USAGE`",
+        "lines at the top of the file and then runs the script with this shell. Each flag and",
+        "argument reaches the script as an environment variable named `usage_<name>`, so",
+        "`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared",
+        "`var=#true` arrives as one string, joined with `shell_words::join()` so that an element",
+        "containing a space stays quoted.",
+        "",
+        "`-h` and `--help` print the script's help page rather than this one. The shell is found",
+        "on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and",
+        "`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how",
+        "`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
+    ]
+    .join("\n");
+    assert_eq!(bash.long_about, Some(expected.as_str()));
 }
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index f791b6244..c4f53a9bb 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -15,7 +15,14 @@ source_code_link_template #"""
 {%- endif -%}
 https://github.com/jdx/usage/blob/main/cli/src/cli/{{path}}
 """#
-about "CLI for working with usage-based CLIs"
+about "Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one"
+long_about #"""
+Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one
+
+A usage spec describes a CLI's commands, flags, and arguments once, in KDL. Most commands here read one: a `.usage.kdl` file given with `-f`, a script whose `#USAGE` comments declare it, or `-` for stdin. A binary built with the Rust framework prints its own spec, so a pipeline like `mycli __usage_spec__ | usage generate markdown -f -` needs no file at all.
+
+Guides and a reference for every command: https://usage.jdx.dev/cli/
+"""#
 usage #"""
 Usage: usage <COMMAND>
        usage --completions <COMPLETIONS>
@@ -24,29 +31,37 @@ Usage: usage <COMMAND>
 unknown_flags error
 subcommand_required #true
 flagset shell {
-    flag -h help="Show help"
-    flag --help help="Show help"
+    flag -h help="Print the script's help page instead of running it"
+    flag --help help="Print the script's help page instead of running it"
 }
-flag --completions help="Outputs completions for the specified shell for completing the `usage` CLI itself" {
+flag --completions help="Print a completion script for the `usage` CLI itself, for the named shell" {
     arg <COMPLETIONS>
 }
-flag --usage-spec help="Outputs a `usage.kdl` spec for this CLI itself"
+flag --usage-spec help="Print the usage spec for the `usage` CLI itself"
 flag "-h --help" help="Print help" action=help builtin=#true
 flag "-V --version" help="Print version" action=version builtin=#true
 cmd bash help="Execute a shell script using bash" unknown_flags=value {
     long_help #"""
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`-h` and `--help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 """#
     use shell
-    arg <SCRIPT>
-    arg "[ARGS]..." help="Arguments to pass to script" {
+    arg <SCRIPT> help="The script to run; its spec is read from the `#USAGE` comments at the top of the file"
+    arg "[ARGS]..." help="Arguments to pass to the script" {
         long_help #"""
-Arguments to pass to script
+Arguments to pass to the script
 
 Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 """#
@@ -57,24 +72,24 @@ cmd complete-word help="Generate shell completion candidates for a partial comma
     long_help #"""
 Generate shell completion candidates for a partial command line
 
-This is used internally by shell completion scripts to provide intelligent completions for commands, flags, and arguments.
+What the scripts from `usage generate completion` run on every Tab: they pass the words typed so far and read back one candidate per line. Useful by hand, too, for checking what a spec offers at a given point without installing anything.
 """#
-    flag "-f --file" help="Usage spec file or script with usage shebang, use \"-\" to read from stdin" {
+    flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" {
         arg <FILE>
     }
-    flag "-s --spec" help="Raw string spec input" overrides=--file required_unless=--file {
+    flag "-s --spec" help="The spec itself, as a string, instead of a file" overrides=--file required_unless=--file {
         arg <SPEC>
     }
-    flag --cword help="Current word index" {
+    flag --cword help="Index of the word being completed; defaults to the last word" {
         arg <CWORD>
     }
-    flag --shell default=bash {
+    flag --shell help="The shell the candidates are for, which decides how they are quoted" default=bash {
         arg <SHELL> {
             choices bash fish nu powershell zsh
         }
     }
     flag "-h --help" help="Print help" action=help builtin=#true
-    arg "[WORDS]..." help="User's input from the command line"
+    arg "[WORDS]..." help="The words typed so far, starting with the program name"
 }
 cmd diff help="Compare two usage specs and report what changed about the interface" effect=read {
     long_help #"""
@@ -109,13 +124,20 @@ every release does not get left switched on.
     complete old type=path
     complete new type=path
 }
-cmd exec help="Execute a script, parsing args and exposing them as environment variables" unknown_flags=value {
+cmd exec help="Run a script through any interpreter, with its parsed arguments as environment variables" unknown_flags=value {
     alias x
-    flag -h help="Show help"
-    flag --help help="Show help"
-    arg <COMMAND> help="command to execute after parsing usage spec"
-    arg <BIN> help="path to script to execute"
-    arg "[ARGS]..." help="arguments to pass to script"
+    long_help #"""
+Run a script through any interpreter, with its parsed arguments as environment variables
+
+For scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env -S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.
+
+`-h` and `--help` print the script's help page rather than this one.
+"""#
+    flag -h help="Print the script's help page instead of running it"
+    flag --help help="Print the script's help page instead of running it"
+    arg <COMMAND> help="The interpreter to run the script with, such as `node` or `python3`"
+    arg <BIN> help="The script to run"
+    arg "[ARGS]..." help="Arguments to pass to the script"
 }
 cmd explain help="Explain what a command line binds to" effect=read {
     long_help #"""
@@ -125,10 +147,10 @@ Prints a row per argv token saying what it became, then the values that came fro
 somewhere other than argv, then anything that went wrong. Exits 0 even when the explained
 command line does not parse: the report succeeded, and that is the case worth a report.
 """#
-    flag "-f --file" help="A usage spec file or script with a usage shebang, use \"-\" to read from stdin" {
+    flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" {
         arg <FILE>
     }
-    flag "-s --spec" help="Raw string spec input" overrides=--file required_unless=--file {
+    flag "-s --spec" help="The spec itself, as a string, instead of a file" overrides=--file required_unless=--file {
         arg <SPEC>
     }
     flag --format help="Output format" default=text {
@@ -163,30 +185,43 @@ The command line to explain, starting with the program name
 }
 cmd fish help="Execute a shell script using fish" unknown_flags=value {
     long_help #"""
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`-h` and `--help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 """#
     use shell
-    arg <SCRIPT>
-    arg "[ARGS]..." help="Arguments to pass to script" {
+    arg <SCRIPT> help="The script to run; its spec is read from the `#USAGE` comments at the top of the file"
+    arg "[ARGS]..." help="Arguments to pass to the script" {
         long_help #"""
-Arguments to pass to script
+Arguments to pass to the script
 
 Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 """#
     }
 }
-cmd generate help="Generate completions, documentation, and other artifacts from usage specs" effect=read subcommand_required=#true {
+cmd generate help="Generate completions, docs, manpages, SDKs, and parse tables from a usage spec" effect=read subcommand_required=#true {
     alias g
     flag "-h --help" help="Print help" action=help builtin=#true
-    cmd completion help="Generate shell completion scripts for bash, fish, nu, powershell, or zsh" effect=read {
+    cmd completion help="Generate a shell completion script for bash, fish, nu, powershell, or zsh" effect=read {
         alias c
         alias complete hide=#true
         alias completions hide=#true
+        long_help #"""
+Generate a shell completion script for bash, fish, nu, powershell, or zsh
+
+The script is a shim: on each Tab it hands the words typed so far to `usage complete-word`, so `usage` must be installed wherever the script is. The spec comes from `--file`, or from running `--usage-cmd` at completion time, which keeps a CLI that prints its own spec from ever going stale.
+"""#
         flag --install help="Install the script where this shell looks for it, instead of printing it" effect=write {
             long_help #"""
 Install the script where this shell looks for it, instead of printing it
@@ -195,59 +230,54 @@ Writes the script file and nothing else: no shell rc file and no PowerShell prof
 """#
         }
         flag --force help="Replace a file at the target path that usage did not write" effect=write requires=--install
-        flag "-f --file" help="A .usage.kdl spec file to use for generating completions, use \"-\" to read from stdin" {
+        flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" {
             arg <FILE>
         }
-        flag --cache-key help="A cache key to use for storing the results of calling the CLI with --usage-cmd" requires=--usage-cmd {
+        flag --cache-key help="Cache what --usage-cmd prints under this key, so it runs once per key rather than on every Tab; the CLI's version is a good key" requires=--usage-cmd {
             arg <CACHE_KEY>
         }
-        flag --usage-bin help="Override the bin used for calling back to usage-cli" env=JDX_USAGE_BIN default=usage {
+        flag --usage-bin help="The `usage` executable the script calls back to, when it is not `usage` on PATH" env=JDX_USAGE_BIN default=usage {
+            arg <USAGE_BIN>
+        }
+        flag --usage-cmd help="A command that prints the CLI's spec, run in place of reading --file" required_unless=--file {
             long_help #"""
-Override the bin used for calling back to usage-cli
+A command that prints the CLI's spec, run in place of reading --file
 
-You may need to set this if you have a different bin named "usage"
+For a CLI that answers with its own spec, such as `mycli __usage_spec__`, so the script always completes the version that is installed. Required unless --file is given.
 """#
-            arg <USAGE_BIN>
-        }
-        flag --usage-cmd help="A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"" required_unless=--file {
             arg <USAGE_CMD>
         }
         flag "-h --help" help="Print help" action=help builtin=#true
-        arg <SHELL> help="Shell to generate completions for" {
+        arg <SHELL> help="The shell to generate the script for" {
             choices bash fish nu powershell zsh
         }
-        arg <BIN> help="The CLI which we're generating completions for"
+        arg <BIN> help="The name of the CLI being completed, as it is typed at the prompt"
     }
-    cmd completion-init help="Generate a shell init script that auto-completes any usage shebang script on $PATH" effect=read {
+    cmd completion-init help="Generate a shell init script that completes every usage-shebang script on PATH" effect=read {
         alias ci
         alias init hide=#true
         alias completions-init hide=#true
         long_help #"""
-Generate a shell init script that auto-completes any usage shebang script on $PATH
-
-Source the output once from your shell rc (e.g. ~/.bashrc) to enable tab-completion for any executable whose first line is a `usage` shebang — no per-script `usage g completion` step required.
-"""#
-        flag --usage-bin help="Override the bin used for calling back to usage-cli" env=JDX_USAGE_BIN default=usage {
-            long_help #"""
-Override the bin used for calling back to usage-cli
+Generate a shell init script that completes every usage-shebang script on PATH
 
-You may need to set this if you have a different bin named "usage"
+Source it once from the shell's rc file and Tab works on any executable whose first line is a `usage` shebang, with no per-script `usage generate completion` step. bash and zsh register a fallback completer that asks `usage complete-word` when the command has such a shebang; fish has no fallback, so it scans PATH once at startup and registers each script it finds.
 """#
+        flag --usage-bin help="The `usage` executable the script calls back to, when it is not `usage` on PATH" env=JDX_USAGE_BIN default=usage {
             arg <USAGE_BIN>
         }
         flag "-h --help" help="Print help" action=help builtin=#true
-        arg <SHELL> help="Shell to generate the init script for" {
+        arg <SHELL> help="The shell to generate the script for" {
             choices bash fish zsh
         }
     }
-    cmd fig help="Generate Fig completion spec for Amazon Q / Fig" effect=read {
-        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
+    cmd fig help="Generate a Fig completion spec, for Amazon Q and Fig" effect=read {
+        flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" {
             arg <FILE>
         }
-        flag --out-file help="File path where the generated Fig spec will be saved, or \"-\" for stdout" effect=write {
+        flag --out-file help="Where to write the spec, or \"-\" for stdout (default)" effect=write {
             arg <OUT_FILE>
         }
-        flag --spec help="Raw string spec input" overrides=--file required_unless=--file {
+        flag --spec help="The spec itself, as a string, instead of a file" overrides=--file required_unless=--file {
             arg <SPEC>
         }
         flag "-h --help" help="Print help" action=help builtin=#true
@@ -261,26 +291,31 @@ The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a
 
   //go:generate usage generate go -f mycli.usage.kdl -o tables.go
 """#
-        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
+        flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" {
             arg <FILE>
         }
-        flag "-o --out-file" help="File path where the generated Go source will be saved, or \"-\" for stdout" effect=write {
+        flag "-o --out-file" help="Where to write the Go source, or \"-\" for stdout (default)" effect=write {
             arg <OUT_FILE>
         }
         flag "-p --package" help="Go package clause for the generated file (defaults to the spec's bin name)" {
             arg <PACKAGE>
         }
-        flag --spec help="Raw string spec input" overrides=--file required_unless=--file {
+        flag --spec help="The spec itself, as a string, instead of a file" overrides=--file required_unless=--file {
             arg <SPEC>
         }
         flag "-h --help" help="Print help" action=help builtin=#true
         complete out_file type=path
     }
-    cmd json help="Outputs a usage spec in json format" effect=read {
-        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
+    cmd json help="Print a usage spec as JSON" effect=read {
+        long_help #"""
+Print a usage spec as JSON
+
+The same document the KDL describes, with included files merged and defaults filled in, for a tool that would rather not parse KDL itself.
+"""#
+        flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" {
             arg <FILE>
         }
-        flag --spec help="raw string spec input" overrides=--file required_unless=--file {
+        flag --spec help="The spec itself, as a string, instead of a file" overrides=--file required_unless=--file {
             arg <SPEC>
         }
         flag --view help="Render one spec-declared executable view" {
@@ -289,13 +324,18 @@ The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a
         flag "-h --help" help="Print help" action=help builtin=#true
     }
     cmd json-schema help="Generate a JSON Schema for a CLI's config file from its usage spec" effect=read {
-        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
+        long_help #"""
+Generate a JSON Schema for a CLI's config file from its usage spec
+
+Built from the spec's `config` block: each `prop` becomes a property with its type, default, and help, so an editor can complete and validate the file the CLI reads. A spec whose settings cannot live in a file is an error rather than an empty schema.
+"""#
+        flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" {
             arg <FILE>
         }
         flag --out-file help="Write the schema here instead of to stdout" effect=write {
             arg <OUT_FILE>
         }
-        flag --spec help="raw string spec input" overrides=--file required_unless=--file {
+        flag --spec help="The spec itself, as a string, instead of a file" overrides=--file required_unless=--file {
             arg <SPEC>
         }
         flag --title help="The schema's title, shown by editors" {
@@ -309,7 +349,7 @@ The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a
     }
     cmd manpage help="Generate a manpage from a usage spec" effect=read {
         alias man
-        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" required=#true {
+        flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" required=#true {
             arg <FILE>
         }
         flag --view help="Render one spec-declared executable view" {
@@ -329,9 +369,14 @@ Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: Sy
         flag "-h --help" help="Print help" action=help builtin=#true
         complete out_file type=path
     }
-    cmd markdown help="Generate markdown documentation from usage specs" effect=read {
+    cmd markdown help="Generate Markdown documentation from a usage spec" effect=read {
         alias md
-        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" required=#true {
+        long_help #"""
+Generate Markdown documentation from a usage spec
+
+One page by default, or a page per command with --multi. Every part of the output comes from a Tera template that --template can replace.
+"""#
+        flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" required=#true {
             arg <FILE>
         }
         flag --view help="Render one spec-declared executable view" {
@@ -339,17 +384,17 @@ Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: Sy
         }
         flag "-m --multi" help="Render each subcommand as a separate markdown file" conflicts=--out-file
         flag --html-encode help="Escape HTML in markdown"
-        flag --out-dir help="Output markdown files to this directory (required when using --multi)" effect=write requires=--multi required_if=--multi {
+        flag --out-dir help="Directory for the per-command pages (required with --multi)" effect=write requires=--multi required_if=--multi {
             arg <OUT_DIR>
         }
         flag --out-file help="Output file path for single-file markdown generation, or \"-\" for stdout (default)" effect=write {
             arg <OUT_FILE>
         }
         flag --replace-pre-with-code-fences help="Replace `<pre>` tags with markdown code fences"
-        flag --url-prefix help="Prefix to add to all URLs" {
+        flag --url-prefix help="Prefix for the links between pages, such as /cli/reference" {
             arg <URL_PREFIX>
         }
-        flag --template help="Override a Tera template with NAME=PATH" var=#true {
+        flag --template help="Replace a built-in Tera template, as NAME=PATH; the names are spec, index, command, argument, flag, and config" var=#true {
             arg <TEMPLATE>
         }
         flag "-h --help" help="Print help" action=help builtin=#true
@@ -357,7 +402,12 @@ Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: Sy
         complete out_file type=path
     }
     cmd sdk help="Generate a type-safe SDK from a usage spec" effect=write {
-        flag "-f --file" help="A usage spec taken in as a file" {
+        long_help #"""
+Generate a type-safe SDK from a usage spec
+
+The SDK is a subprocess wrapper: typed arguments, flags, and choices for every command, and a client that builds the argument list and runs the binary.
+"""#
+        flag "-f --file" help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin" {
             arg <FILE>
         }
         flag "-l --language" help="Target language for the SDK" required=#true {
@@ -365,19 +415,26 @@ Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: Sy
                 choices typescript python
             }
         }
-        flag "-o --output" help="Output directory for generated SDK files" required=#true {
+        flag "-o --output" help="Directory to write the SDK into" required=#true {
             arg <OUTPUT>
         }
         flag "-p --package-name" help="Override the package/module name (defaults to spec bin name)" {
             arg <PACKAGE_NAME>
         }
-        flag --spec help="Raw string spec input" overrides=--file required_unless=--file {
+        flag --spec help="The spec itself, as a string, instead of a file" overrides=--file required_unless=--file {
             arg <SPEC>
         }
         flag "-h --help" help="Print help" action=help builtin=#true
     }
 }
-cmd lint help="Lint a usage spec file for common issues" effect=read {
+cmd lint help="Lint a usage spec for mistakes that still parse" effect=read {
+    long_help #"""
+Lint a usage spec for mistakes that still parse
+
+A spec can be valid KDL and still be wrong: a flag or subcommand declared twice, a required argument after an optional one, a variadic argument that is not last, a command or flag with no help, an example its own spec cannot parse. Each finding carries a code such as `duplicate-flag`, and `--format json` prints the findings as a list for a script to act on.
+
+Exits 1 when there is an error, or a warning under `--warnings-as-errors`.
+"""#
     flag "-f --format" help="Output format" default=text {
         arg <FORMAT> {
             choices {
@@ -395,7 +452,7 @@ Off by default: declaration order is a house convention rather than a correctnes
 """#
     }
     flag "-h --help" help="Print help" action=help builtin=#true
-    arg <FILE> help="A usage spec file to lint, use \"-\" to read from stdin"
+    arg <FILE> help="A usage spec file, or a script with a usage shebang; \"-\" reads stdin"
 }
 cmd mcp help="Serve a usage spec over the Model Context Protocol" effect=read {
     alias mcp-server
@@ -404,29 +461,42 @@ Serve a usage spec over the Model Context Protocol
 
 Reads JSON-RPC over stdin and writes responses to stdout, which is how MCP
 clients launch a local server. Point one at `usage mcp -f mycli.usage.kdl`.
+
+Two tools are served: `list_commands`, every command with its effect, and
+`describe_command`, one command's help, flags, and arguments. Together they
+let an agent learn what a CLI does, and what running it would touch, without
+running it.
 """#
-    flag "-f --file" help="Usage spec file (not \"-\": stdin is the MCP transport)" {
+    flag "-f --file" help="A usage spec file, or a script with a usage shebang (not \"-\": stdin is the MCP transport)" {
         arg <FILE>
     }
-    flag "-s --spec" help="Raw string spec input" overrides=--file required_unless=--file {
+    flag "-s --spec" help="The spec itself, as a string, instead of a file" overrides=--file required_unless=--file {
         arg <SPEC>
     }
     flag "-h --help" help="Print help" action=help builtin=#true
 }
 cmd powershell help="Execute a shell script using PowerShell" unknown_flags=value {
     long_help #"""
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`-h` and `--help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 """#
     use shell
-    arg <SCRIPT>
-    arg "[ARGS]..." help="Arguments to pass to script" {
+    arg <SCRIPT> help="The script to run; its spec is read from the `#USAGE` comments at the top of the file"
+    arg "[ARGS]..." help="Arguments to pass to the script" {
         long_help #"""
-Arguments to pass to script
+Arguments to pass to the script
 
 Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 """#
@@ -437,18 +507,26 @@ cmd sponsors help="Show the companies sponsoring usage and the jdx.dev open sour
 }
 cmd zsh help="Execute a shell script using zsh" unknown_flags=value {
     long_help #"""
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`-h` and `--help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 """#
     use shell
-    arg <SCRIPT>
-    arg "[ARGS]..." help="Arguments to pass to script" {
+    arg <SCRIPT> help="The script to run; its spec is read from the `#USAGE` comments at the top of the file"
+    arg "[ARGS]..." help="Arguments to pass to the script" {
         long_help #"""
-Arguments to pass to script
+Arguments to pass to the script
 
 Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 """#
diff --git a/docs/cli/completions.md b/docs/cli/completions.md
index a27c4e44c..34bee3fb9 100644
--- a/docs/cli/completions.md
+++ b/docs/cli/completions.md
@@ -1,66 +1,33 @@
 # Generating Completion Scripts
 
-## Auto-completion for shebang scripts (bash)
-
-If you have shell scripts that use the `usage` shebang
-(e.g. `#!/usr/bin/env -S usage bash`) and live on `$PATH`, you can enable
-tab-completion for all of them at once with a single init line — no per-script
-generation required.
-
-Add this to your `~/.bashrc`:
-
-```bash
-source <(usage g completion-init bash)
-```
-
-For zsh:
+A completion script generated by `usage` is a shim. On each Tab it hands the words typed so far
+to `usage complete-word`, which reads the spec and answers with the candidates. The script stays
+small, every shell gets the same answers, and the spec is the only thing that has to be right.
 
 ```bash
-# Add this to your ~/.zshrc
-source <(usage g completion-init zsh)
-```
-
-For fish:
-
-```bash
-# Add this to ~/.config/fish/conf.d/usage.fish
-usage g completion-init fish | source
+usage g completion bash mycli -f ./mycli.usage.kdl --install
+mycli --<TAB>
 ```
 
-After restarting your shell, `<Tab>` will work on any script whose first line
-is a `usage` shebang. Mechanism per shell:
+The two arguments are the shell and the name of the CLI as it is typed at the prompt. The spec
+comes from `--file`, or from `--usage-cmd`, a command that prints one: a binary built with the
+[Rust framework](/rust/) answers `mycli __usage_spec__`, so a script generated that way completes
+whatever version is installed.
 
-- **bash**: registers a `complete -D` default handler that dispatches to
-  `usage complete-word` for usage shebangs. Source this **after**
-  bash-completion so the existing default handler is chained to for non-usage
-  commands.
-- **zsh**: registers a `compdef -default-` fallback. Falls back to `_files`
-  for non-usage commands.
-- **fish**: scans `$PATH` once at shell startup (fish has no default-completer
-  fallback) and registers `complete -c <name>` per usage-shebang script.
+::: info
+`usage` is a runtime dependency of the generated scripts. Anyone using the completions needs it
+installed.
+:::
 
-This is the simplest setup if your CLIs are written as `usage`-shebang scripts.
-For `.usage.kdl` specs or binaries with `--usage`, generate per-binary
-completion scripts as shown below.
+## Installing the script
 
-## Per-binary completion scripts
+`--install` writes the script where the shell looks for it, and nothing else: no shell rc file
+and no PowerShell profile is edited. Where a shell needs a one-time line of its own — zsh's
+`fpath+=`, PowerShell's dot-source — the line is printed for you to add. Running it again when
+nothing has changed writes nothing, and a file `usage` did not write is reported rather than
+replaced; pass `--force` to replace one anyway.
 
-Usage can generate completion scripts for any shell, and put them where that shell looks.
-`--install` does the second part:
-
-```bash
-usage g completion bash mycli -f ./mycli.usage.kdl --install
-mycli --<TAB>
-```
-
-It writes the script file and nothing else: no shell rc file and no PowerShell profile is
-edited. Where a shell needs a one-time line of its own — zsh's `fpath+=`, PowerShell's
-dot-source — the line is printed for you to add. Running it again when nothing has changed
-writes nothing, and a file usage did not write is reported rather than replaced; pass
-`--force` to replace one anyway.
-
-Without `--install` the script goes to stdout, which is what to use when you want to choose the
-path yourself. For bash:
+Without `--install` the script goes to stdout, for when the path is yours to choose. bash:
 
 ```bash
 usage g completion bash mycli -f ./mycli.usage.kdl > ~/.bash_completions/mycli.bash
@@ -68,14 +35,6 @@ source ~/.bash_completions/mycli.bash
 mycli --<TAB>
 ```
 
-Generated bash completions call
-[bash-completion](https://github.com/scop/bash-completion)'s helper functions, so it
-must be installed and sourced before the generated script. Install it from your
-package manager (`apt install bash-completion`, `brew install bash-completion@2`, …);
-a generated completion that cannot find it says so instead of failing silently.
-Version 2.11 and newer are supported, which covers every current distribution
-release.
-
 zsh:
 
 ```bash
@@ -91,14 +50,7 @@ usage g completion fish mycli -f ./mycli.usage.kdl > ~/.config/fish/completions/
 mycli --<TAB>
 ```
 
-fig/Amazon Q:
-
-```bash
-usage g fig -f ./mycli.usage.kdl > ./mycli.fig.ts
-mycli --<TAB>
-```
-
-nushell:
+Nushell:
 
 ```nushell
 usage g completion nu mycli -f ./mycli.usage.kdl > ~/.config/nushell/autoload/mycli.nu
@@ -114,18 +66,29 @@ usage g completion powershell mycli -f ./mycli.usage.kdl > ./mycli.ps1
 mycli --<TAB>
 ```
 
-Spec-based generation with `usage g completion` supports bash, zsh, fish,
-PowerShell, and Nushell. Elvish is not among them — though the
-[Rust framework](/rust/completions)'s runtime completions do support it.
+Fig and Amazon Q read a spec of their own rather than a script:
 
-::: info
-Usage CLI is a runtime dependency for the generated completion scripts. Your users
-will need to have `usage` installed in order for the completion scripts to work.
-:::
+```bash
+usage g fig -f ./mycli.usage.kdl > ./mycli.fig.ts
+```
+
+Those are the shells `usage g completion` supports: bash, zsh, fish, PowerShell, and Nushell.
+Elvish is not among them, though the [Rust framework](/rust/completions)'s runtime completions
+do support it.
+
+## bash needs bash-completion
 
-New shells should be easy to add because the logic around completions is mostly handled by the Usage CLI.
-Typically, completion scripts will call usage like this to fetch completion choices (cword is the index of
-the current word):
+Generated bash scripts call [bash-completion](https://github.com/scop/bash-completion)'s helper
+functions, so it must be installed and sourced before the generated script. Install it from your
+package manager (`apt install bash-completion`, `brew install bash-completion@2`, …); a generated
+completion that cannot find it says so instead of failing silently. Version 2.11 and newer are
+supported, which covers every current distribution release.
+
+## What the script does
+
+Each script calls `usage complete-word` with the spec and the words typed so far, and prints
+what comes back. The same command works by hand, which is the quickest way to check what a spec
+offers at a given point:
 
 ```bash
 $ usage complete-word --file ./mycli.usage.kdl -- mycli cmd1 cmd2 --f
@@ -133,17 +96,52 @@ $ usage complete-word --file ./mycli.usage.kdl -- mycli cmd1 cmd2 --f
 --file
 ```
 
-## Completions for `usage` CLI itself
+Because the shell-specific part is this thin, adding a shell is mostly a matter of writing the
+shim.
+
+## Shebang scripts
+
+Scripts that use the `usage` shebang (`#!/usr/bin/env -S usage bash`, see
+[Scripts](/cli/scripts)) need no per-script completion file. One line in the shell's rc enables
+Tab on every such script on `$PATH`. bash, in `~/.bashrc`:
+
+```bash
+source <(usage g completion-init bash)
+```
+
+zsh, in `~/.zshrc`:
+
+```bash
+source <(usage g completion-init zsh)
+```
+
+fish, in `~/.config/fish/conf.d/usage.fish`:
+
+```bash
+usage g completion-init fish | source
+```
+
+After restarting the shell, `<Tab>` works on any executable whose first line is a `usage`
+shebang. Each shell gets there its own way:
+
+- **bash** registers a `complete -D` default handler that dispatches to `usage complete-word`
+  for usage shebangs. Source it **after** bash-completion, so the existing default handler is
+  chained to for everything else.
+- **zsh** registers a `compdef -default-` fallback, which falls back to `_files` for
+  everything else.
+- **fish** has no default-completer fallback, so it scans `$PATH` once at shell startup and
+  registers `complete -c <name>` for each usage-shebang script it finds.
+
+## Completions for `usage` itself
 
-For yourself, the general command works — `usage` is another CLI that can describe itself, so
-there is no special case:
+`usage` is another CLI that can describe itself, so the general command applies:
 
 ```bash
 usage g completion zsh usage --usage-cmd "command usage --usage-spec" --install
 ```
 
-For a package, keep the redirects below. Those are system directories the package manager owns,
-which is exactly why `--install` does not target them.
+A package should keep the redirects below instead. Those are system directories the package
+manager owns, which is exactly why `--install` does not target them.
 
 ```bash
 usage --completions bash > /etc/bash_completion.d/usage
diff --git a/docs/cli/index.md b/docs/cli/index.md
index 223c747b9..0cd8537af 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -1,5 +1,34 @@
 # CLI
 
+`usage` is the command-line utility around the [usage spec](/spec/). A spec describes a CLI's
+commands, flags, and arguments once, in KDL. This tool turns that one description into the
+things a CLI ships with, and runs scripts that carry a spec in their own comments.
+
+| To get                                                      | Run                          | Guide                                            |
+| ----------------------------------------------------------- | ---------------------------- | ------------------------------------------------ |
+| Tab completion for bash, zsh, fish, PowerShell, and Nushell | `usage generate completion`  | [Completions](/cli/completions)                  |
+| Markdown reference pages                                    | `usage generate markdown`    | [Markdown](/cli/markdown)                        |
+| Man pages                                                   | `usage generate manpage`     | [Manpages](/cli/manpages)                        |
+| Typed TypeScript and Python clients                         | `usage generate sdk`         | [SDK generation](/cli/sdk)                       |
+| Parse tables for a Go CLI                                   | `usage generate go`          | [Go framework](/go/)                             |
+| A JSON Schema for the CLI's config file                     | `usage generate json-schema` | [reference](/cli/reference/generate/json-schema) |
+| A shell script with parsed arguments and `--help`           | `usage bash`, `usage exec`   | [Scripts](/cli/scripts)                          |
+| What changed between two versions of an interface           | `usage diff`                 | [Comparing specs](/cli/diff)                     |
+| What a command line binds to, and why                       | `usage explain`              | [reference](/cli/reference/explain)              |
+| Mistakes a spec can have and still parse                    | `usage lint`                 | [reference](/cli/reference/lint)                 |
+| A CLI described to an AI agent, with each command's effect  | `usage mcp`                  | [reference](/cli/reference/mcp)                  |
+
+Every command that reads a spec takes it the same three ways: a `.usage.kdl` file with `-f`, a
+script whose `#USAGE` comments declare it, or `-` for stdin. A binary built with the
+[Rust framework](/rust/) prints its own spec, so documenting it needs no file at all:
+
+```sh
+mycli __usage_spec__ | usage generate markdown -f - --out-dir docs
+```
+
+The [reference](/cli/reference/) lists every command and flag. It is generated from `usage`'s
+own spec by the command it documents.
+
 ## Installation
 
 ### [mise-en-place](https://mise.jdx.dev)
@@ -14,7 +43,8 @@ mise use -g usage
 cargo install usage-cli
 ```
 
-You can also use [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall) to install quicker:
+[`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall) fetches a prebuilt binary
+instead of compiling one:
 
 ```sh
 cargo binstall usage-cli
@@ -28,7 +58,7 @@ brew install usage
 
 ### Arch Linux
 
-usage is available in [Extra](https://archlinux.org/packages/extra/x86_64/usage/)
+The package is in [Extra](https://archlinux.org/packages/extra/x86_64/usage/):
 
 ```sh
 pacman -S usage
diff --git a/docs/cli/manpages.md b/docs/cli/manpages.md
index a947afc04..44bf648ef 100644
--- a/docs/cli/manpages.md
+++ b/docs/cli/manpages.md
@@ -1,47 +1,47 @@
 # Generating Manpages
 
-Usage CLI can generate Unix man pages from a Usage definition in the standard roff format.
-
-## Basic Usage
-
-Generate a manpage and output to stdout:
+`usage generate manpage` renders a spec as roff, the format `man` reads. `g` and `man` are the
+short aliases, and without `-o` the page goes to stdout:
 
 ```bash
-$ usage generate manpage -f ./mycli.usage.kdl
+usage g man -f ./mycli.usage.kdl -o mycli.1
 ```
 
-Save to a file:
+Piping it straight into `man` previews the page without installing anything:
 
 ```bash
-$ usage generate manpage -f ./mycli.usage.kdl -o mycli.1
+usage g man -f ./mycli.usage.kdl | man -l -
 ```
 
-Install to the system man directory:
+## Installing
+
+A page lives in the directory for its section, and `mandb` has to be told it is there:
 
 ```bash
-$ usage generate manpage -f ./mycli.usage.kdl | sudo tee /usr/share/man/man1/mycli.1
-$ sudo mandb  # Update the man database
-$ man mycli
+usage g man -f ./mycli.usage.kdl | sudo tee /usr/share/man/man1/mycli.1 > /dev/null
+sudo mandb
+man mycli
 ```
 
-## Manual Sections
+## Sections
 
-You can specify the manual section with the `--section` flag (default is 1):
+The page is section 1, user commands, unless `--section` says otherwise:
 
 ```bash
-$ usage generate manpage -f ./myconfig.usage.kdl --section 5 -o myconfig.5
+usage g man -f ./myconfig.usage.kdl --section 5 -o myconfig.5
 ```
 
-Common manual sections:
+| Section | Contents                                                           |
+| ------- | ------------------------------------------------------------------ |
+| 1       | User commands (default)                                            |
+| 5       | File formats and conventions, such as a page about the config file |
+| 7       | Miscellaneous: overviews and conventions                           |
+| 8       | System administration commands and daemons                         |
 
-- **1**: User commands (default)
-- **5**: File formats and conventions
-- **7**: Miscellaneous (including macro packages and conventions)
-- **8**: System administration commands and daemons
+## What the page contains
 
-## Output Format
-
-The generated man page follows the standard Unix man page format:
+The spec's `about` and long help become NAME and DESCRIPTION, its flags and subcommands become
+OPTIONS and COMMANDS, and any `example` nodes become EXAMPLES:
 
 ```
 mycli(1)                    General Commands Manual                   mycli(1)
@@ -77,26 +77,3 @@ EXAMPLES
 AUTHOR
        Your Name <your.email@example.com>
 ```
-
-## Aliases
-
-The command has a short alias for convenience:
-
-```bash
-$ usage g man -f ./mycli.usage.kdl
-```
-
-## Viewing Generated Pages
-
-To preview the generated man page without installing it:
-
-```bash
-$ usage g man -f ./mycli.usage.kdl | man -l -
-```
-
-Or save and view:
-
-```bash
-$ usage g man -f ./mycli.usage.kdl -o mycli.1
-$ man ./mycli.1
-```
diff --git a/docs/cli/markdown.md b/docs/cli/markdown.md
index 73956c53f..2977ccb52 100644
--- a/docs/cli/markdown.md
+++ b/docs/cli/markdown.md
@@ -1,20 +1,24 @@
 # Generating Markdown Documentation
 
-Usage CLI can generate markdown documentation from a Usage definition either into a single file, or a directory.
+`usage generate markdown` renders a spec as Markdown reference pages: one page for the whole
+CLI, or one per command for a docs site with a sidebar. The [CLI reference](/cli/reference/) on
+this site is its output for `usage`'s own spec.
 
-Single file, written with `--out-file` (or to stdout, the default, so you can redirect it
-wherever you like):
+A single file goes to `--out-file`, or to stdout when there is none:
 
 ```sh
-$ usage g markdown -f ./mycli.usage.kdl --out-file ./docs/cli.md
-$ usage g markdown -f ./mycli.usage.kdl > ./docs/cli.md
+usage g markdown -f ./mycli.usage.kdl --out-file ./docs/cli.md
+usage g markdown -f ./mycli.usage.kdl > ./docs/cli.md
 ```
 
-Multiple files:
+`--multi` writes one page per command into `--out-dir`, nested the way the commands are:
 
 ```sh
-$ usage g markdown -mf ./mycli.usage.kdl --out-dir ./docs
-$ tree ./docs
+usage g markdown -mf ./mycli.usage.kdl --out-dir ./docs
+tree ./docs
+```
+
+```text
 docs
 ├── config
 │   ├── add.md
@@ -24,13 +28,19 @@ docs
 └── update.md
 ```
 
+Links between the pages are relative to that directory; `--url-prefix /cli/reference` roots
+them at a site path instead. Help text is wrapped in `<pre>` so that its line breaks survive
+any renderer; `--replace-pre-with-code-fences` swaps those for fenced code blocks, which is
+what a renderer with syntax highlighting wants.
+
 ## Custom templates from the CLI
 
-Each renderer template can be replaced with a Tera template file. For example, a custom
-single-file document can keep the built-in command template:
+Every part of the output comes from a [Tera](https://keats.github.io/tera/) template, and
+`--template NAME=PATH` replaces one. A custom single-file document can keep the built-in
+command template by including it:
 
 ```sh
-$ usage g markdown -f ./mycli.usage.kdl \
+usage g markdown -f ./mycli.usage.kdl \
     --template spec=./templates/spec.md.tera \
     --out-file ./docs/cli.md
 ```
@@ -42,42 +52,48 @@ $ usage g markdown -f ./mycli.usage.kdl \
 {% include "cmd_template.md.tera" %}
 ```
 
-The available names are `spec`, `index`, `command`, `argument`, `flag`, and `config`. Repeat
-`--template` to replace more than one. Templates that are not named keep their built-in
-definitions and remain available through Tera's `include`.
+The names are `spec`, `index`, `command`, `argument`, `flag`, and `config`. Repeat `--template`
+to replace more than one. Templates that are not named keep their built-in definitions and
+remain available through Tera's `include`.
 
 ## Custom templates from Rust
 
-`MarkdownRenderer` bundles a complete set of Tera templates. A Rust caller can replace one
-member without copying the rest:
+`MarkdownRenderer` in `usage-lib` bundles the same templates. A Rust caller replaces one member
+without copying the rest:
 
 ```rust
 use usage::docs::markdown::{MarkdownRenderer, MarkdownTemplate};
 
-let spec: usage::Spec = std::fs::read_to_string("mycli.usage.kdl")?.parse()?;
-let markdown = MarkdownRenderer::new(spec)
-    .with_template(
-        MarkdownTemplate::Spec,
-        "# {{ spec.bin }} reference\n{% set cmd = spec.cmd %}\n{% include \"cmd_template.md.tera\" %}",
-    )
-    .render_spec()?;
-# Ok::<(), Box<dyn std::error::Error>>(())
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let spec: usage::Spec = std::fs::read_to_string("mycli.usage.kdl")?.parse()?;
+    let markdown = MarkdownRenderer::new(spec)
+        .with_template(
+            MarkdownTemplate::Spec,
+            "# {{ spec.bin }} reference\n{% set cmd = spec.cmd %}\n{% include \"cmd_template.md.tera\" %}",
+        )
+        .render_spec()?;
+    print!("{markdown}");
+    Ok(())
+}
 ```
 
-The selectable members are `Spec`, `Index`, `Command`, `Argument`, `Flag`, and `Config`.
-Templates that are not replaced remain available through Tera's `include`; syntax and include
-errors are returned when the page is rendered.
+The members are `Spec`, `Index`, `Command`, `Argument`, `Flag`, and `Config`. Templates that are
+not replaced remain available through `include`; syntax and include errors are returned when
+the page is rendered, not when the template is set.
 
-Generated references use `MarkdownTheme::Compact`: arguments and flags are grouped into dense
-lists that remain easy to scan on a large page. To give each entry its own addressable heading,
-select the detailed theme:
+Pages use `MarkdownTheme::Compact` by default: arguments and flags are grouped into dense lists
+that stay easy to scan on a large page. `MarkdownTheme::Detailed` gives each entry its own
+heading, so that a flag can be linked to directly:
 
 ```rust
 use usage::docs::markdown::{MarkdownRenderer, MarkdownTheme};
 
-# let spec: usage::Spec = "bin \"mycli\"".parse()?;
-let markdown = MarkdownRenderer::new(spec)
-    .with_theme(MarkdownTheme::Detailed)
-    .render_spec()?;
-# Ok::<(), Box<dyn std::error::Error>>(())
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let spec: usage::Spec = std::fs::read_to_string("mycli.usage.kdl")?.parse()?;
+    let markdown = MarkdownRenderer::new(spec)
+        .with_theme(MarkdownTheme::Detailed)
+        .render_spec()?;
+    print!("{markdown}");
+    Ok(())
+}
 ```
diff --git a/docs/cli/reference/bash.md b/docs/cli/reference/bash.md
index 8bc235a6c..12b2bf2b1 100644
--- a/docs/cli/reference/bash.md
+++ b/docs/cli/reference/bash.md
@@ -5,21 +5,29 @@
 - **Usage:** `usage bash [-h] [--help] <SCRIPT> [ARGS]…`
 - **Source code:** [`cli/src/cli/shell.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/shell.rs)
 
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`-h` and `--help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 
 ## Arguments
 
-- **`<SCRIPT>`**
-- **`[ARGS]…`** — Arguments to pass to script
+- **`<SCRIPT>`** — The script to run; its spec is read from the `#USAGE` comments at the top of the file
+- **`[ARGS]…`** — Arguments to pass to the script
 
   Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 
 ## Flags
 
-- **`-h`** — Show help
-- **`--help`** — Show help
+- **`-h`** — Print the script's help page instead of running it
+- **`--help`** — Print the script's help page instead of running it
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index 87645536f..ddca85f19 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -13,6 +13,8 @@
           {
             "name": "SCRIPT",
             "usage": "<SCRIPT>",
+            "help": "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
+            "help_first_line": "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
             "required": true,
             "double_dash": "Optional",
             "hide": false
@@ -20,9 +22,9 @@
           {
             "name": "ARGS",
             "usage": "[ARGS]…",
-            "help": "Arguments to pass to script",
-            "help_long": "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.",
-            "help_first_line": "Arguments to pass to script",
+            "help": "Arguments to pass to the script",
+            "help_long": "Arguments to pass to the script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.",
+            "help_first_line": "Arguments to pass to the script",
             "required": false,
             "double_dash": "Optional",
             "var": true,
@@ -33,8 +35,8 @@
           {
             "name": "h",
             "usage": "-h",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": ["h"],
             "long": [],
             "hide": false,
@@ -43,8 +45,8 @@
           {
             "name": "help",
             "usage": "--help",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": [],
             "long": ["help"],
             "hide": false,
@@ -56,7 +58,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Execute a shell script using bash",
-        "help_long": "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them.",
+        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel\nhands the script and its arguments to `usage`, which parses them against the `#USAGE`\nlines at the top of the file and then runs the script with this shell. Each flag and\nargument reaches the script as an environment variable named `usage_<name>`, so\n`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared\n`var=#true` arrives as one string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one. The shell is found\non PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and\n`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how\n`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
         "name": "bash",
         "aliases": [],
         "hidden_aliases": [],
@@ -71,8 +73,8 @@
           {
             "name": "WORDS",
             "usage": "[WORDS]…",
-            "help": "User's input from the command line",
-            "help_first_line": "User's input from the command line",
+            "help": "The words typed so far, starting with the program name",
+            "help_first_line": "The words typed so far, starting with the program name",
             "required": false,
             "double_dash": "Optional",
             "var": true,
@@ -83,8 +85,8 @@
           {
             "name": "file",
             "usage": "-f --file <FILE>",
-            "help": "Usage spec file or script with usage shebang, use \"-\" to read from stdin",
-            "help_first_line": "Usage spec file or script with usage shebang, use \"-\" to read from stdin",
+            "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+            "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
             "short": ["f"],
             "long": ["file"],
             "hide": false,
@@ -100,8 +102,8 @@
           {
             "name": "spec",
             "usage": "-s --spec <SPEC>",
-            "help": "Raw string spec input",
-            "help_first_line": "Raw string spec input",
+            "help": "The spec itself, as a string, instead of a file",
+            "help_first_line": "The spec itself, as a string, instead of a file",
             "short": ["s"],
             "long": ["spec"],
             "required_unless": ["--file"],
@@ -119,8 +121,8 @@
           {
             "name": "cword",
             "usage": "--cword <CWORD>",
-            "help": "Current word index",
-            "help_first_line": "Current word index",
+            "help": "Index of the word being completed; defaults to the last word",
+            "help_first_line": "Index of the word being completed; defaults to the last word",
             "short": [],
             "long": ["cword"],
             "hide": false,
@@ -136,6 +138,8 @@
           {
             "name": "shell",
             "usage": "--shell <SHELL>",
+            "help": "The shell the candidates are for, which decides how they are quoted",
+            "help_first_line": "The shell the candidates are for, which decides how they are quoted",
             "short": [],
             "long": ["shell"],
             "hide": false,
@@ -171,7 +175,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Generate shell completion candidates for a partial command line",
-        "help_long": "Generate shell completion candidates for a partial command line\n\nThis is used internally by shell completion scripts to provide intelligent completions for commands, flags, and arguments.",
+        "help_long": "Generate shell completion candidates for a partial command line\n\nWhat the scripts from `usage generate completion` run on every Tab: they pass the words typed so far and read back one candidate per line. Useful by hand, too, for checking what a spec offers at a given point without installing anything.",
         "name": "complete-word",
         "aliases": ["cw"],
         "hidden_aliases": [],
@@ -296,8 +300,8 @@
           {
             "name": "COMMAND",
             "usage": "<COMMAND>",
-            "help": "command to execute after parsing usage spec",
-            "help_first_line": "command to execute after parsing usage spec",
+            "help": "The interpreter to run the script with, such as `node` or `python3`",
+            "help_first_line": "The interpreter to run the script with, such as `node` or `python3`",
             "required": true,
             "double_dash": "Optional",
             "hide": false
@@ -305,8 +309,8 @@
           {
             "name": "BIN",
             "usage": "<BIN>",
-            "help": "path to script to execute",
-            "help_first_line": "path to script to execute",
+            "help": "The script to run",
+            "help_first_line": "The script to run",
             "required": true,
             "double_dash": "Optional",
             "hide": false
@@ -314,8 +318,8 @@
           {
             "name": "ARGS",
             "usage": "[ARGS]…",
-            "help": "arguments to pass to script",
-            "help_first_line": "arguments to pass to script",
+            "help": "Arguments to pass to the script",
+            "help_first_line": "Arguments to pass to the script",
             "required": false,
             "double_dash": "Optional",
             "var": true,
@@ -326,8 +330,8 @@
           {
             "name": "h",
             "usage": "-h",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": ["h"],
             "long": [],
             "hide": false,
@@ -336,8 +340,8 @@
           {
             "name": "help",
             "usage": "--help",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": [],
             "long": ["help"],
             "hide": false,
@@ -348,7 +352,8 @@
         "unknown_flags": "value",
         "hide": false,
         "args_override_self": true,
-        "help": "Execute a script, parsing args and exposing them as environment variables",
+        "help": "Run a script through any interpreter, with its parsed arguments as environment variables",
+        "help_long": "Run a script through any interpreter, with its parsed arguments as environment variables\n\nFor scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env -S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.\n\n`-h` and `--help` print the script's help page rather than this one.",
         "name": "exec",
         "aliases": ["x"],
         "hidden_aliases": [],
@@ -376,8 +381,8 @@
           {
             "name": "file",
             "usage": "-f --file <FILE>",
-            "help": "A usage spec file or script with a usage shebang, use \"-\" to read from stdin",
-            "help_first_line": "A usage spec file or script with a usage shebang, use \"-\" to read from stdin",
+            "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+            "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
             "short": ["f"],
             "long": ["file"],
             "hide": false,
@@ -393,8 +398,8 @@
           {
             "name": "spec",
             "usage": "-s --spec <SPEC>",
-            "help": "Raw string spec input",
-            "help_first_line": "Raw string spec input",
+            "help": "The spec itself, as a string, instead of a file",
+            "help_first_line": "The spec itself, as a string, instead of a file",
             "short": ["s"],
             "long": ["spec"],
             "required_unless": ["--file"],
@@ -518,6 +523,8 @@
           {
             "name": "SCRIPT",
             "usage": "<SCRIPT>",
+            "help": "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
+            "help_first_line": "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
             "required": true,
             "double_dash": "Optional",
             "hide": false
@@ -525,9 +532,9 @@
           {
             "name": "ARGS",
             "usage": "[ARGS]…",
-            "help": "Arguments to pass to script",
-            "help_long": "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.",
-            "help_first_line": "Arguments to pass to script",
+            "help": "Arguments to pass to the script",
+            "help_long": "Arguments to pass to the script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.",
+            "help_first_line": "Arguments to pass to the script",
             "required": false,
             "double_dash": "Optional",
             "var": true,
@@ -538,8 +545,8 @@
           {
             "name": "h",
             "usage": "-h",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": ["h"],
             "long": [],
             "hide": false,
@@ -548,8 +555,8 @@
           {
             "name": "help",
             "usage": "--help",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": [],
             "long": ["help"],
             "hide": false,
@@ -561,7 +568,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Execute a shell script using fish",
-        "help_long": "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them.",
+        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel\nhands the script and its arguments to `usage`, which parses them against the `#USAGE`\nlines at the top of the file and then runs the script with this shell. Each flag and\nargument reaches the script as an environment variable named `usage_<name>`, so\n`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared\n`var=#true` arrives as one string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one. The shell is found\non PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and\n`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how\n`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
         "name": "fish",
         "aliases": [],
         "hidden_aliases": [],
@@ -580,8 +587,8 @@
               {
                 "name": "SHELL",
                 "usage": "<SHELL>",
-                "help": "Shell to generate completions for",
-                "help_first_line": "Shell to generate completions for",
+                "help": "The shell to generate the script for",
+                "help_first_line": "The shell to generate the script for",
                 "required": true,
                 "double_dash": "Optional",
                 "hide": false,
@@ -592,8 +599,8 @@
               {
                 "name": "BIN",
                 "usage": "<BIN>",
-                "help": "The CLI which we're generating completions for",
-                "help_first_line": "The CLI which we're generating completions for",
+                "help": "The name of the CLI being completed, as it is typed at the prompt",
+                "help_first_line": "The name of the CLI being completed, as it is typed at the prompt",
                 "required": true,
                 "double_dash": "Optional",
                 "hide": false
@@ -627,8 +634,8 @@
               {
                 "name": "file",
                 "usage": "-f --file <FILE>",
-                "help": "A .usage.kdl spec file to use for generating completions, use \"-\" to read from stdin",
-                "help_first_line": "A .usage.kdl spec file to use for generating completions, use \"-\" to read from stdin",
+                "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+                "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
                 "short": ["f"],
                 "long": ["file"],
                 "hide": false,
@@ -644,8 +651,8 @@
               {
                 "name": "cache-key",
                 "usage": "--cache-key <CACHE_KEY>",
-                "help": "A cache key to use for storing the results of calling the CLI with --usage-cmd",
-                "help_first_line": "A cache key to use for storing the results of calling the CLI with --usage-cmd",
+                "help": "Cache what --usage-cmd prints under this key, so it runs once per key rather than on every Tab; the CLI's version is a good key",
+                "help_first_line": "Cache what --usage-cmd prints under this key, so it runs once per key rather than on every Tab; the CLI's version is a good key",
                 "short": [],
                 "long": ["cache-key"],
                 "hide": false,
@@ -662,9 +669,8 @@
               {
                 "name": "usage-bin",
                 "usage": "--usage-bin <USAGE_BIN>",
-                "help": "Override the bin used for calling back to usage-cli",
-                "help_long": "Override the bin used for calling back to usage-cli\n\nYou may need to set this if you have a different bin named \"usage\"",
-                "help_first_line": "Override the bin used for calling back to usage-cli",
+                "help": "The `usage` executable the script calls back to, when it is not `usage` on PATH",
+                "help_first_line": "The `usage` executable the script calls back to, when it is not `usage` on PATH",
                 "short": [],
                 "long": ["usage-bin"],
                 "hide": false,
@@ -682,8 +688,9 @@
               {
                 "name": "usage-cmd",
                 "usage": "--usage-cmd <USAGE_CMD>",
-                "help": "A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"",
-                "help_first_line": "A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"",
+                "help": "A command that prints the CLI's spec, run in place of reading --file",
+                "help_long": "A command that prints the CLI's spec, run in place of reading --file\n\nFor a CLI that answers with its own spec, such as `mycli __usage_spec__`, so the script always completes the version that is installed. Required unless --file is given.",
+                "help_first_line": "A command that prints the CLI's spec, run in place of reading --file",
                 "short": [],
                 "long": ["usage-cmd"],
                 "required_unless": ["--file"],
@@ -715,7 +722,8 @@
             "unknown_flags": null,
             "hide": false,
             "args_override_self": true,
-            "help": "Generate shell completion scripts for bash, fish, nu, powershell, or zsh",
+            "help": "Generate a shell completion script for bash, fish, nu, powershell, or zsh",
+            "help_long": "Generate a shell completion script for bash, fish, nu, powershell, or zsh\n\nThe script is a shim: on each Tab it hands the words typed so far to `usage complete-word`, so `usage` must be installed wherever the script is. The spec comes from `--file`, or from running `--usage-cmd` at completion time, which keeps a CLI that prints its own spec from ever going stale.",
             "name": "completion",
             "aliases": ["c"],
             "hidden_aliases": ["complete", "completions"],
@@ -730,8 +738,8 @@
               {
                 "name": "SHELL",
                 "usage": "<SHELL>",
-                "help": "Shell to generate the init script for",
-                "help_first_line": "Shell to generate the init script for",
+                "help": "The shell to generate the script for",
+                "help_first_line": "The shell to generate the script for",
                 "required": true,
                 "double_dash": "Optional",
                 "hide": false,
@@ -744,9 +752,8 @@
               {
                 "name": "usage-bin",
                 "usage": "--usage-bin <USAGE_BIN>",
-                "help": "Override the bin used for calling back to usage-cli",
-                "help_long": "Override the bin used for calling back to usage-cli\n\nYou may need to set this if you have a different bin named \"usage\"",
-                "help_first_line": "Override the bin used for calling back to usage-cli",
+                "help": "The `usage` executable the script calls back to, when it is not `usage` on PATH",
+                "help_first_line": "The `usage` executable the script calls back to, when it is not `usage` on PATH",
                 "short": [],
                 "long": ["usage-bin"],
                 "hide": false,
@@ -779,8 +786,8 @@
             "unknown_flags": null,
             "hide": false,
             "args_override_self": true,
-            "help": "Generate a shell init script that auto-completes any usage shebang script on $PATH",
-            "help_long": "Generate a shell init script that auto-completes any usage shebang script on $PATH\n\nSource the output once from your shell rc (e.g. ~/.bashrc) to enable tab-completion for any executable whose first line is a `usage` shebang — no per-script `usage g completion` step required.",
+            "help": "Generate a shell init script that completes every usage-shebang script on PATH",
+            "help_long": "Generate a shell init script that completes every usage-shebang script on PATH\n\nSource it once from the shell's rc file and Tab works on any executable whose first line is a `usage` shebang, with no per-script `usage generate completion` step. bash and zsh register a fallback completer that asks `usage complete-word` when the command has such a shebang; fish has no fallback, so it scans PATH once at startup and registers each script it finds.",
             "name": "completion-init",
             "aliases": ["ci"],
             "hidden_aliases": ["init", "completions-init"],
@@ -796,8 +803,8 @@
               {
                 "name": "file",
                 "usage": "-f --file <FILE>",
-                "help": "A usage spec taken in as a file, use \"-\" to read from stdin",
-                "help_first_line": "A usage spec taken in as a file, use \"-\" to read from stdin",
+                "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+                "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
                 "short": ["f"],
                 "long": ["file"],
                 "hide": false,
@@ -813,8 +820,8 @@
               {
                 "name": "out-file",
                 "usage": "--out-file <OUT_FILE>",
-                "help": "File path where the generated Fig spec will be saved, or \"-\" for stdout",
-                "help_first_line": "File path where the generated Fig spec will be saved, or \"-\" for stdout",
+                "help": "Where to write the spec, or \"-\" for stdout (default)",
+                "help_first_line": "Where to write the spec, or \"-\" for stdout (default)",
                 "short": [],
                 "long": ["out-file"],
                 "hide": false,
@@ -831,8 +838,8 @@
               {
                 "name": "spec",
                 "usage": "--spec <SPEC>",
-                "help": "Raw string spec input",
-                "help_first_line": "Raw string spec input",
+                "help": "The spec itself, as a string, instead of a file",
+                "help_first_line": "The spec itself, as a string, instead of a file",
                 "short": [],
                 "long": ["spec"],
                 "required_unless": ["--file"],
@@ -865,7 +872,7 @@
             "unknown_flags": null,
             "hide": false,
             "args_override_self": true,
-            "help": "Generate Fig completion spec for Amazon Q / Fig",
+            "help": "Generate a Fig completion spec, for Amazon Q and Fig",
             "name": "fig",
             "aliases": [],
             "hidden_aliases": [],
@@ -887,8 +894,8 @@
               {
                 "name": "file",
                 "usage": "-f --file <FILE>",
-                "help": "A usage spec taken in as a file, use \"-\" to read from stdin",
-                "help_first_line": "A usage spec taken in as a file, use \"-\" to read from stdin",
+                "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+                "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
                 "short": ["f"],
                 "long": ["file"],
                 "hide": false,
@@ -904,8 +911,8 @@
               {
                 "name": "out-file",
                 "usage": "-o --out-file <OUT_FILE>",
-                "help": "File path where the generated Go source will be saved, or \"-\" for stdout",
-                "help_first_line": "File path where the generated Go source will be saved, or \"-\" for stdout",
+                "help": "Where to write the Go source, or \"-\" for stdout (default)",
+                "help_first_line": "Where to write the Go source, or \"-\" for stdout (default)",
                 "short": ["o"],
                 "long": ["out-file"],
                 "hide": false,
@@ -939,8 +946,8 @@
               {
                 "name": "spec",
                 "usage": "--spec <SPEC>",
-                "help": "Raw string spec input",
-                "help_first_line": "Raw string spec input",
+                "help": "The spec itself, as a string, instead of a file",
+                "help_first_line": "The spec itself, as a string, instead of a file",
                 "short": [],
                 "long": ["spec"],
                 "required_unless": ["--file"],
@@ -996,8 +1003,8 @@
               {
                 "name": "file",
                 "usage": "-f --file <FILE>",
-                "help": "A usage spec taken in as a file, use \"-\" to read from stdin",
-                "help_first_line": "A usage spec taken in as a file, use \"-\" to read from stdin",
+                "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+                "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
                 "short": ["f"],
                 "long": ["file"],
                 "hide": false,
@@ -1013,8 +1020,8 @@
               {
                 "name": "spec",
                 "usage": "--spec <SPEC>",
-                "help": "raw string spec input",
-                "help_first_line": "raw string spec input",
+                "help": "The spec itself, as a string, instead of a file",
+                "help_first_line": "The spec itself, as a string, instead of a file",
                 "short": [],
                 "long": ["spec"],
                 "required_unless": ["--file"],
@@ -1064,7 +1071,8 @@
             "unknown_flags": null,
             "hide": false,
             "args_override_self": true,
-            "help": "Outputs a usage spec in json format",
+            "help": "Print a usage spec as JSON",
+            "help_long": "Print a usage spec as JSON\n\nThe same document the KDL describes, with included files merged and defaults filled in, for a tool that would rather not parse KDL itself.",
             "name": "json",
             "aliases": [],
             "hidden_aliases": [],
@@ -1080,8 +1088,8 @@
               {
                 "name": "file",
                 "usage": "-f --file <FILE>",
-                "help": "A usage spec taken in as a file, use \"-\" to read from stdin",
-                "help_first_line": "A usage spec taken in as a file, use \"-\" to read from stdin",
+                "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+                "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
                 "short": ["f"],
                 "long": ["file"],
                 "hide": false,
@@ -1115,8 +1123,8 @@
               {
                 "name": "spec",
                 "usage": "--spec <SPEC>",
-                "help": "raw string spec input",
-                "help_first_line": "raw string spec input",
+                "help": "The spec itself, as a string, instead of a file",
+                "help_first_line": "The spec itself, as a string, instead of a file",
                 "short": [],
                 "long": ["spec"],
                 "required_unless": ["--file"],
@@ -1184,6 +1192,7 @@
             "hide": false,
             "args_override_self": true,
             "help": "Generate a JSON Schema for a CLI's config file from its usage spec",
+            "help_long": "Generate a JSON Schema for a CLI's config file from its usage spec\n\nBuilt from the spec's `config` block: each `prop` becomes a property with its type, default, and help, so an editor can complete and validate the file the CLI reads. A spec whose settings cannot live in a file is an error rather than an empty schema.",
             "name": "json-schema",
             "aliases": [],
             "hidden_aliases": [],
@@ -1205,8 +1214,8 @@
               {
                 "name": "file",
                 "usage": "-f --file <FILE>",
-                "help": "A usage spec taken in as a file, use \"-\" to read from stdin",
-                "help_first_line": "A usage spec taken in as a file, use \"-\" to read from stdin",
+                "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+                "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
                 "short": ["f"],
                 "long": ["file"],
                 "required": true,
@@ -1314,8 +1323,8 @@
               {
                 "name": "file",
                 "usage": "-f --file <FILE>",
-                "help": "A usage spec taken in as a file, use \"-\" to read from stdin",
-                "help_first_line": "A usage spec taken in as a file, use \"-\" to read from stdin",
+                "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+                "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
                 "short": ["f"],
                 "long": ["file"],
                 "required": true,
@@ -1370,8 +1379,8 @@
               {
                 "name": "out-dir",
                 "usage": "--out-dir <OUT_DIR>",
-                "help": "Output markdown files to this directory (required when using --multi)",
-                "help_first_line": "Output markdown files to this directory (required when using --multi)",
+                "help": "Directory for the per-command pages (required with --multi)",
+                "help_first_line": "Directory for the per-command pages (required with --multi)",
                 "short": [],
                 "long": ["out-dir"],
                 "required_if": ["--multi"],
@@ -1418,8 +1427,8 @@
               {
                 "name": "url-prefix",
                 "usage": "--url-prefix <URL_PREFIX>",
-                "help": "Prefix to add to all URLs",
-                "help_first_line": "Prefix to add to all URLs",
+                "help": "Prefix for the links between pages, such as /cli/reference",
+                "help_first_line": "Prefix for the links between pages, such as /cli/reference",
                 "short": [],
                 "long": ["url-prefix"],
                 "hide": false,
@@ -1435,8 +1444,8 @@
               {
                 "name": "template",
                 "usage": "--template <TEMPLATE>",
-                "help": "Override a Tera template with NAME=PATH",
-                "help_first_line": "Override a Tera template with NAME=PATH",
+                "help": "Replace a built-in Tera template, as NAME=PATH; the names are spec, index, command, argument, flag, and config",
+                "help_first_line": "Replace a built-in Tera template, as NAME=PATH; the names are spec, index, command, argument, flag, and config",
                 "short": [],
                 "long": ["template"],
                 "var": true,
@@ -1468,7 +1477,8 @@
             "unknown_flags": null,
             "hide": false,
             "args_override_self": true,
-            "help": "Generate markdown documentation from usage specs",
+            "help": "Generate Markdown documentation from a usage spec",
+            "help_long": "Generate Markdown documentation from a usage spec\n\nOne page by default, or a page per command with --multi. Every part of the output comes from a Tera template that --template can replace.",
             "name": "markdown",
             "aliases": ["md"],
             "hidden_aliases": [],
@@ -1494,8 +1504,8 @@
               {
                 "name": "file",
                 "usage": "-f --file <FILE>",
-                "help": "A usage spec taken in as a file",
-                "help_first_line": "A usage spec taken in as a file",
+                "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+                "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
                 "short": ["f"],
                 "long": ["file"],
                 "hide": false,
@@ -1532,8 +1542,8 @@
               {
                 "name": "output",
                 "usage": "-o --output <OUTPUT>",
-                "help": "Output directory for generated SDK files",
-                "help_first_line": "Output directory for generated SDK files",
+                "help": "Directory to write the SDK into",
+                "help_first_line": "Directory to write the SDK into",
                 "short": ["o"],
                 "long": ["output"],
                 "required": true,
@@ -1567,8 +1577,8 @@
               {
                 "name": "spec",
                 "usage": "--spec <SPEC>",
-                "help": "Raw string spec input",
-                "help_first_line": "Raw string spec input",
+                "help": "The spec itself, as a string, instead of a file",
+                "help_first_line": "The spec itself, as a string, instead of a file",
                 "short": [],
                 "long": ["spec"],
                 "required_unless": ["--file"],
@@ -1602,6 +1612,7 @@
             "hide": false,
             "args_override_self": true,
             "help": "Generate a type-safe SDK from a usage spec",
+            "help_long": "Generate a type-safe SDK from a usage spec\n\nThe SDK is a subprocess wrapper: typed arguments, flags, and choices for every command, and a client that builds the argument list and runs the binary.",
             "name": "sdk",
             "aliases": [],
             "hidden_aliases": [],
@@ -1630,7 +1641,7 @@
         "hide": false,
         "subcommand_required": true,
         "args_override_self": true,
-        "help": "Generate completions, documentation, and other artifacts from usage specs",
+        "help": "Generate completions, docs, manpages, SDKs, and parse tables from a usage spec",
         "name": "generate",
         "aliases": ["g"],
         "hidden_aliases": [],
@@ -1645,8 +1656,8 @@
           {
             "name": "FILE",
             "usage": "<FILE>",
-            "help": "A usage spec file to lint, use \"-\" to read from stdin",
-            "help_first_line": "A usage spec file to lint, use \"-\" to read from stdin",
+            "help": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
+            "help_first_line": "A usage spec file, or a script with a usage shebang; \"-\" reads stdin",
             "required": true,
             "double_dash": "Optional",
             "hide": false
@@ -1721,7 +1732,8 @@
         "unknown_flags": null,
         "hide": false,
         "args_override_self": true,
-        "help": "Lint a usage spec file for common issues",
+        "help": "Lint a usage spec for mistakes that still parse",
+        "help_long": "Lint a usage spec for mistakes that still parse\n\nA spec can be valid KDL and still be wrong: a flag or subcommand declared twice, a required argument after an optional one, a variadic argument that is not last, a command or flag with no help, an example its own spec cannot parse. Each finding carries a code such as `duplicate-flag`, and `--format json` prints the findings as a list for a script to act on.\n\nExits 1 when there is an error, or a warning under `--warnings-as-errors`.",
         "name": "lint",
         "aliases": [],
         "hidden_aliases": [],
@@ -1737,8 +1749,8 @@
           {
             "name": "file",
             "usage": "-f --file <FILE>",
-            "help": "Usage spec file (not \"-\": stdin is the MCP transport)",
-            "help_first_line": "Usage spec file (not \"-\": stdin is the MCP transport)",
+            "help": "A usage spec file, or a script with a usage shebang (not \"-\": stdin is the MCP transport)",
+            "help_first_line": "A usage spec file, or a script with a usage shebang (not \"-\": stdin is the MCP transport)",
             "short": ["f"],
             "long": ["file"],
             "hide": false,
@@ -1754,8 +1766,8 @@
           {
             "name": "spec",
             "usage": "-s --spec <SPEC>",
-            "help": "Raw string spec input",
-            "help_first_line": "Raw string spec input",
+            "help": "The spec itself, as a string, instead of a file",
+            "help_first_line": "The spec itself, as a string, instead of a file",
             "short": ["s"],
             "long": ["spec"],
             "required_unless": ["--file"],
@@ -1789,7 +1801,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Serve a usage spec over the Model Context Protocol",
-        "help_long": "Serve a usage spec over the Model Context Protocol\n\nReads JSON-RPC over stdin and writes responses to stdout, which is how MCP\nclients launch a local server. Point one at `usage mcp -f mycli.usage.kdl`.",
+        "help_long": "Serve a usage spec over the Model Context Protocol\n\nReads JSON-RPC over stdin and writes responses to stdout, which is how MCP\nclients launch a local server. Point one at `usage mcp -f mycli.usage.kdl`.\n\nTwo tools are served: `list_commands`, every command with its effect, and\n`describe_command`, one command's help, flags, and arguments. Together they\nlet an agent learn what a CLI does, and what running it would touch, without\nrunning it.",
         "name": "mcp",
         "aliases": ["mcp-server"],
         "hidden_aliases": [],
@@ -1804,6 +1816,8 @@
           {
             "name": "SCRIPT",
             "usage": "<SCRIPT>",
+            "help": "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
+            "help_first_line": "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
             "required": true,
             "double_dash": "Optional",
             "hide": false
@@ -1811,9 +1825,9 @@
           {
             "name": "ARGS",
             "usage": "[ARGS]…",
-            "help": "Arguments to pass to script",
-            "help_long": "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.",
-            "help_first_line": "Arguments to pass to script",
+            "help": "Arguments to pass to the script",
+            "help_long": "Arguments to pass to the script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.",
+            "help_first_line": "Arguments to pass to the script",
             "required": false,
             "double_dash": "Optional",
             "var": true,
@@ -1824,8 +1838,8 @@
           {
             "name": "h",
             "usage": "-h",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": ["h"],
             "long": [],
             "hide": false,
@@ -1834,8 +1848,8 @@
           {
             "name": "help",
             "usage": "--help",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": [],
             "long": ["help"],
             "hide": false,
@@ -1847,7 +1861,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Execute a shell script using PowerShell",
-        "help_long": "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them.",
+        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel\nhands the script and its arguments to `usage`, which parses them against the `#USAGE`\nlines at the top of the file and then runs the script with this shell. Each flag and\nargument reaches the script as an environment variable named `usage_<name>`, so\n`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared\n`var=#true` arrives as one string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one. The shell is found\non PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and\n`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how\n`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
         "name": "powershell",
         "aliases": [],
         "hidden_aliases": [],
@@ -1893,6 +1907,8 @@
           {
             "name": "SCRIPT",
             "usage": "<SCRIPT>",
+            "help": "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
+            "help_first_line": "The script to run; its spec is read from the `#USAGE` comments at the top of the file",
             "required": true,
             "double_dash": "Optional",
             "hide": false
@@ -1900,9 +1916,9 @@
           {
             "name": "ARGS",
             "usage": "[ARGS]…",
-            "help": "Arguments to pass to script",
-            "help_long": "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.",
-            "help_first_line": "Arguments to pass to script",
+            "help": "Arguments to pass to the script",
+            "help_long": "Arguments to pass to the script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.",
+            "help_first_line": "Arguments to pass to the script",
             "required": false,
             "double_dash": "Optional",
             "var": true,
@@ -1913,8 +1929,8 @@
           {
             "name": "h",
             "usage": "-h",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": ["h"],
             "long": [],
             "hide": false,
@@ -1923,8 +1939,8 @@
           {
             "name": "help",
             "usage": "--help",
-            "help": "Show help",
-            "help_first_line": "Show help",
+            "help": "Print the script's help page instead of running it",
+            "help_first_line": "Print the script's help page instead of running it",
             "short": [],
             "long": ["help"],
             "hide": false,
@@ -1936,7 +1952,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Execute a shell script using zsh",
-        "help_long": "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them.",
+        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel\nhands the script and its arguments to `usage`, which parses them against the `#USAGE`\nlines at the top of the file and then runs the script with this shell. Each flag and\nargument reaches the script as an environment variable named `usage_<name>`, so\n`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared\n`var=#true` arrives as one string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one. The shell is found\non PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and\n`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how\n`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
         "name": "zsh",
         "aliases": [],
         "hidden_aliases": [],
@@ -1949,8 +1965,8 @@
       {
         "name": "completions",
         "usage": "--completions <COMPLETIONS>",
-        "help": "Outputs completions for the specified shell for completing the `usage` CLI itself",
-        "help_first_line": "Outputs completions for the specified shell for completing the `usage` CLI itself",
+        "help": "Print a completion script for the `usage` CLI itself, for the named shell",
+        "help_first_line": "Print a completion script for the `usage` CLI itself, for the named shell",
         "short": [],
         "long": ["completions"],
         "hide": false,
@@ -1966,8 +1982,8 @@
       {
         "name": "usage-spec",
         "usage": "--usage-spec",
-        "help": "Outputs a `usage.kdl` spec for this CLI itself",
-        "help_first_line": "Outputs a `usage.kdl` spec for this CLI itself",
+        "help": "Print the usage spec for the `usage` CLI itself",
+        "help_first_line": "Print the usage spec for the `usage` CLI itself",
         "short": [],
         "long": ["usage-spec"],
         "hide": false,
@@ -2019,7 +2035,8 @@
   "complete": {},
   "source_code_link_template": "{%- set path = path | replace(from='-', to='_') -%}\n{%- if cmd.subcommands | length > 0 -%}\n{%- set path = path ~ \"/mod.rs\" -%}\n{%- elif path in [\"bash\", \"fish\", \"powershell\", \"zsh\"] -%}\n{%- set path = \"shell.rs\" -%}\n{%- else -%}\n{%- set path = path ~ \".rs\" -%}\n{%- endif -%}\nhttps://github.com/jdx/usage/blob/main/cli/src/cli/{{path}}",
   "repository": "https://github.com/jdx/usage",
-  "about": "CLI for working with usage-based CLIs",
+  "about": "Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one",
+  "about_long": "Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one\n\nA usage spec describes a CLI's commands, flags, and arguments once, in KDL. Most commands here read one: a `.usage.kdl` file given with `-f`, a script whose `#USAGE` comments declare it, or `-` for stdin. A binary built with the Rust framework prints its own spec, so a pipeline like `mycli __usage_spec__ | usage generate markdown -f -` needs no file at all.\n\nGuides and a reference for every command: https://usage.jdx.dev/cli/",
   "min_usage_version": "6.5",
   "unknown_flags": "error"
 }
diff --git a/docs/cli/reference/complete-word.md b/docs/cli/reference/complete-word.md
index 7309c1b74..74c3cd595 100644
--- a/docs/cli/reference/complete-word.md
+++ b/docs/cli/reference/complete-word.md
@@ -9,18 +9,18 @@
 
 Generate shell completion candidates for a partial command line
 
-This is used internally by shell completion scripts to provide intelligent completions for commands, flags, and arguments.
+What the scripts from `usage generate completion` run on every Tab: they pass the words typed so far and read back one candidate per line. Useful by hand, too, for checking what a spec offers at a given point without installing anything.
 
 ## Arguments
 
-- **`[WORDS]…`** — User's input from the command line
+- **`[WORDS]…`** — The words typed so far, starting with the program name
 
 ## Flags
 
-- **`-f --file <FILE>`** — Usage spec file or script with usage shebang, use "-" to read from stdin
-- **`-s --spec <SPEC>`** — Raw string spec input
-- **`--cword <CWORD>`** — Current word index
-- **`--shell <SHELL>`**
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
+- **`-s --spec <SPEC>`** — The spec itself, as a string, instead of a file
+- **`--cword <CWORD>`** — Index of the word being completed; defaults to the last word
+- **`--shell <SHELL>`** — The shell the candidates are for, which decides how they are quoted
 
   **Choices:** `bash`, `fish`, `nu`, `powershell`, `zsh`
 
diff --git a/docs/cli/reference/exec.md b/docs/cli/reference/exec.md
index 891e3d42d..148188f55 100644
--- a/docs/cli/reference/exec.md
+++ b/docs/cli/reference/exec.md
@@ -6,15 +6,19 @@
 - **Aliases:** `x`
 - **Source code:** [`cli/src/cli/exec.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/exec.rs)
 
-Execute a script, parsing args and exposing them as environment variables
+Run a script through any interpreter, with its parsed arguments as environment variables
+
+For scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env -S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.
+
+`-h` and `--help` print the script's help page rather than this one.
 
 ## Arguments
 
-- **`<COMMAND>`** — command to execute after parsing usage spec
-- **`<BIN>`** — path to script to execute
-- **`[ARGS]…`** — arguments to pass to script
+- **`<COMMAND>`** — The interpreter to run the script with, such as `node` or `python3`
+- **`<BIN>`** — The script to run
+- **`[ARGS]…`** — Arguments to pass to the script
 
 ## Flags
 
-- **`-h`** — Show help
-- **`--help`** — Show help
+- **`-h`** — Print the script's help page instead of running it
+- **`--help`** — Print the script's help page instead of running it
diff --git a/docs/cli/reference/explain.md b/docs/cli/reference/explain.md
index 2b6c97389..b42e3a8d9 100644
--- a/docs/cli/reference/explain.md
+++ b/docs/cli/reference/explain.md
@@ -20,8 +20,8 @@ command line does not parse: the report succeeded, and that is the case worth a
 
 ## Flags
 
-- **`-f --file <FILE>`** — A usage spec file or script with a usage shebang, use "-" to read from stdin
-- **`-s --spec <SPEC>`** — Raw string spec input
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
+- **`-s --spec <SPEC>`** — The spec itself, as a string, instead of a file
 - **`--format <FORMAT>`** — Output format
 
   **Choices:** `text`, `json`
diff --git a/docs/cli/reference/fish.md b/docs/cli/reference/fish.md
index 62247e793..8b34ca3fc 100644
--- a/docs/cli/reference/fish.md
+++ b/docs/cli/reference/fish.md
@@ -5,21 +5,29 @@
 - **Usage:** `usage fish [-h] [--help] <SCRIPT> [ARGS]…`
 - **Source code:** [`cli/src/cli/shell.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/shell.rs)
 
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`-h` and `--help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 
 ## Arguments
 
-- **`<SCRIPT>`**
-- **`[ARGS]…`** — Arguments to pass to script
+- **`<SCRIPT>`** — The script to run; its spec is read from the `#USAGE` comments at the top of the file
+- **`[ARGS]…`** — Arguments to pass to the script
 
   Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 
 ## Flags
 
-- **`-h`** — Show help
-- **`--help`** — Show help
+- **`-h`** — Print the script's help page instead of running it
+- **`--help`** — Print the script's help page instead of running it
diff --git a/docs/cli/reference/generate.md b/docs/cli/reference/generate.md
index 8d7d9d422..dca367797 100644
--- a/docs/cli/reference/generate.md
+++ b/docs/cli/reference/generate.md
@@ -7,7 +7,7 @@
 - **Effect:** read-only
 - **Source code:** [`cli/src/cli/generate/mod.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/mod.rs)
 
-Generate completions, documentation, and other artifacts from usage specs
+Generate completions, docs, manpages, SDKs, and parse tables from a usage spec
 
 ## Flags
 
diff --git a/docs/cli/reference/generate/completion-init.md b/docs/cli/reference/generate/completion-init.md
index b360a5bad..2b91146bf 100644
--- a/docs/cli/reference/generate/completion-init.md
+++ b/docs/cli/reference/generate/completion-init.md
@@ -7,21 +7,19 @@
 - **Effect:** read-only
 - **Source code:** [`cli/src/cli/generate/completion_init.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/completion_init.rs)
 
-Generate a shell init script that auto-completes any usage shebang script on $PATH
+Generate a shell init script that completes every usage-shebang script on PATH
 
-Source the output once from your shell rc (e.g. ~/.bashrc) to enable tab-completion for any executable whose first line is a `usage` shebang — no per-script `usage g completion` step required.
+Source it once from the shell's rc file and Tab works on any executable whose first line is a `usage` shebang, with no per-script `usage generate completion` step. bash and zsh register a fallback completer that asks `usage complete-word` when the command has such a shebang; fish has no fallback, so it scans PATH once at startup and registers each script it finds.
 
 ## Arguments
 
-- **`<SHELL>`** — Shell to generate the init script for
+- **`<SHELL>`** — The shell to generate the script for
 
   **Choices:** `bash`, `fish`, `zsh`
 
 ## Flags
 
-- **`--usage-bin <USAGE_BIN>`** — Override the bin used for calling back to usage-cli
-
-  You may need to set this if you have a different bin named "usage"
+- **`--usage-bin <USAGE_BIN>`** — The `usage` executable the script calls back to, when it is not `usage` on PATH
 
   **Default:** `usage`
 
diff --git a/docs/cli/reference/generate/completion.md b/docs/cli/reference/generate/completion.md
index a5f91ccf8..844011e29 100644
--- a/docs/cli/reference/generate/completion.md
+++ b/docs/cli/reference/generate/completion.md
@@ -7,15 +7,17 @@
 - **Effect:** read-only
 - **Source code:** [`cli/src/cli/generate/completion.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/completion.rs)
 
-Generate shell completion scripts for bash, fish, nu, powershell, or zsh
+Generate a shell completion script for bash, fish, nu, powershell, or zsh
+
+The script is a shim: on each Tab it hands the words typed so far to `usage complete-word`, so `usage` must be installed wherever the script is. The spec comes from `--file`, or from running `--usage-cmd` at completion time, which keeps a CLI that prints its own spec from ever going stale.
 
 ## Arguments
 
-- **`<SHELL>`** — Shell to generate completions for
+- **`<SHELL>`** — The shell to generate the script for
 
   **Choices:** `bash`, `fish`, `nu`, `powershell`, `zsh`
 
-- **`<BIN>`** — The CLI which we're generating completions for
+- **`<BIN>`** — The name of the CLI being completed, as it is typed at the prompt
 
 ## Flags
 
@@ -29,15 +31,16 @@ Generate shell completion scripts for bash, fish, nu, powershell, or zsh
 
   **Effect:** modifies state
 
-- **`-f --file <FILE>`** — A .usage.kdl spec file to use for generating completions, use "-" to read from stdin
-- **`--cache-key <CACHE_KEY>`** — A cache key to use for storing the results of calling the CLI with --usage-cmd
-- **`--usage-bin <USAGE_BIN>`** — Override the bin used for calling back to usage-cli
-
-  You may need to set this if you have a different bin named "usage"
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
+- **`--cache-key <CACHE_KEY>`** — Cache what --usage-cmd prints under this key, so it runs once per key rather than on every Tab; the CLI's version is a good key
+- **`--usage-bin <USAGE_BIN>`** — The `usage` executable the script calls back to, when it is not `usage` on PATH
 
   **Default:** `usage`
 
   **Environment Variable:** `JDX_USAGE_BIN`
 
-- **`--usage-cmd <USAGE_CMD>`** — A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to "$bin --usage"
+- **`--usage-cmd <USAGE_CMD>`** — A command that prints the CLI's spec, run in place of reading --file
+
+  For a CLI that answers with its own spec, such as `mycli __usage_spec__`, so the script always completes the version that is installed. Required unless --file is given.
+
 - **`-h --help`** — Print help
diff --git a/docs/cli/reference/generate/fig.md b/docs/cli/reference/generate/fig.md
index f49d0c64b..e5a5c8c6d 100644
--- a/docs/cli/reference/generate/fig.md
+++ b/docs/cli/reference/generate/fig.md
@@ -6,14 +6,14 @@
 - **Effect:** read-only
 - **Source code:** [`cli/src/cli/generate/fig.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/fig.rs)
 
-Generate Fig completion spec for Amazon Q / Fig
+Generate a Fig completion spec, for Amazon Q and Fig
 
 ## Flags
 
-- **`-f --file <FILE>`** — A usage spec taken in as a file, use "-" to read from stdin
-- **`--out-file <OUT_FILE>`** — File path where the generated Fig spec will be saved, or "-" for stdout
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
+- **`--out-file <OUT_FILE>`** — Where to write the spec, or "-" for stdout (default)
 
   **Effect:** modifies state
 
-- **`--spec <SPEC>`** — Raw string spec input
+- **`--spec <SPEC>`** — The spec itself, as a string, instead of a file
 - **`-h --help`** — Print help
diff --git a/docs/cli/reference/generate/go.md b/docs/cli/reference/generate/go.md
index 74752fc2c..81b3a593b 100644
--- a/docs/cli/reference/generate/go.md
+++ b/docs/cli/reference/generate/go.md
@@ -14,11 +14,11 @@ The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a
 
 ## Flags
 
-- **`-f --file <FILE>`** — A usage spec taken in as a file, use "-" to read from stdin
-- **`-o --out-file <OUT_FILE>`** — File path where the generated Go source will be saved, or "-" for stdout
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
+- **`-o --out-file <OUT_FILE>`** — Where to write the Go source, or "-" for stdout (default)
 
   **Effect:** modifies state
 
 - **`-p --package <PACKAGE>`** — Go package clause for the generated file (defaults to the spec's bin name)
-- **`--spec <SPEC>`** — Raw string spec input
+- **`--spec <SPEC>`** — The spec itself, as a string, instead of a file
 - **`-h --help`** — Print help
diff --git a/docs/cli/reference/generate/json-schema.md b/docs/cli/reference/generate/json-schema.md
index 6f48df79c..ec0461b28 100644
--- a/docs/cli/reference/generate/json-schema.md
+++ b/docs/cli/reference/generate/json-schema.md
@@ -8,14 +8,16 @@
 
 Generate a JSON Schema for a CLI's config file from its usage spec
 
+Built from the spec's `config` block: each `prop` becomes a property with its type, default, and help, so an editor can complete and validate the file the CLI reads. A spec whose settings cannot live in a file is an error rather than an empty schema.
+
 ## Flags
 
-- **`-f --file <FILE>`** — A usage spec taken in as a file, use "-" to read from stdin
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
 - **`--out-file <OUT_FILE>`** — Write the schema here instead of to stdout
 
   **Effect:** modifies state
 
-- **`--spec <SPEC>`** — raw string spec input
+- **`--spec <SPEC>`** — The spec itself, as a string, instead of a file
 - **`--title <TITLE>`** — The schema's title, shown by editors
 - **`--url <URL>`** — Where the schema is published, for its `$id`
 - **`-h --help`** — Print help
diff --git a/docs/cli/reference/generate/json.md b/docs/cli/reference/generate/json.md
index bdb7e8cde..002bb2683 100644
--- a/docs/cli/reference/generate/json.md
+++ b/docs/cli/reference/generate/json.md
@@ -6,11 +6,13 @@
 - **Effect:** read-only
 - **Source code:** [`cli/src/cli/generate/json.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/json.rs)
 
-Outputs a usage spec in json format
+Print a usage spec as JSON
+
+The same document the KDL describes, with included files merged and defaults filled in, for a tool that would rather not parse KDL itself.
 
 ## Flags
 
-- **`-f --file <FILE>`** — A usage spec taken in as a file, use "-" to read from stdin
-- **`--spec <SPEC>`** — raw string spec input
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
+- **`--spec <SPEC>`** — The spec itself, as a string, instead of a file
 - **`--view <VIEW>`** — Render one spec-declared executable view
 - **`-h --help`** — Print help
diff --git a/docs/cli/reference/generate/manpage.md b/docs/cli/reference/generate/manpage.md
index df67810c5..d95e1551b 100644
--- a/docs/cli/reference/generate/manpage.md
+++ b/docs/cli/reference/generate/manpage.md
@@ -11,7 +11,7 @@ Generate a manpage from a usage spec
 
 ## Flags
 
-- **`-f --file <FILE>`** — A usage spec taken in as a file, use "-" to read from stdin
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
 - **`--view <VIEW>`** — Render one spec-declared executable view
 - **`-o --out-file <OUT_FILE>`** — Output file path, or "-" for stdout (default)
 
diff --git a/docs/cli/reference/generate/markdown.md b/docs/cli/reference/generate/markdown.md
index fb9ab6e51..7edefdbbc 100644
--- a/docs/cli/reference/generate/markdown.md
+++ b/docs/cli/reference/generate/markdown.md
@@ -7,15 +7,17 @@
 - **Effect:** read-only
 - **Source code:** [`cli/src/cli/generate/markdown.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/markdown.rs)
 
-Generate markdown documentation from usage specs
+Generate Markdown documentation from a usage spec
+
+One page by default, or a page per command with --multi. Every part of the output comes from a Tera template that --template can replace.
 
 ## Flags
 
-- **`-f --file <FILE>`** — A usage spec taken in as a file, use "-" to read from stdin
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
 - **`--view <VIEW>`** — Render one spec-declared executable view
 - **`-m --multi`** — Render each subcommand as a separate markdown file
 - **`--html-encode`** — Escape HTML in markdown
-- **`--out-dir <OUT_DIR>`** — Output markdown files to this directory (required when using --multi)
+- **`--out-dir <OUT_DIR>`** — Directory for the per-command pages (required with --multi)
 
   **Effect:** modifies state
 
@@ -24,6 +26,6 @@ Generate markdown documentation from usage specs
   **Effect:** modifies state
 
 - **`--replace-pre-with-code-fences`** — Replace `<pre>` tags with markdown code fences
-- **`--url-prefix <URL_PREFIX>`** — Prefix to add to all URLs
-- **`--template <TEMPLATE>`** — Override a Tera template with NAME=PATH
+- **`--url-prefix <URL_PREFIX>`** — Prefix for the links between pages, such as /cli/reference
+- **`--template <TEMPLATE>`** — Replace a built-in Tera template, as NAME=PATH; the names are spec, index, command, argument, flag, and config
 - **`-h --help`** — Print help
diff --git a/docs/cli/reference/generate/sdk.md b/docs/cli/reference/generate/sdk.md
index d1d65eaa2..976122508 100644
--- a/docs/cli/reference/generate/sdk.md
+++ b/docs/cli/reference/generate/sdk.md
@@ -8,14 +8,16 @@
 
 Generate a type-safe SDK from a usage spec
 
+The SDK is a subprocess wrapper: typed arguments, flags, and choices for every command, and a client that builds the argument list and runs the binary.
+
 ## Flags
 
-- **`-f --file <FILE>`** — A usage spec taken in as a file
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
 - **`-l --language <LANGUAGE>`** — Target language for the SDK
 
   **Choices:** `typescript`, `python`
 
-- **`-o --output <OUTPUT>`** — Output directory for generated SDK files
+- **`-o --output <OUTPUT>`** — Directory to write the SDK into
 - **`-p --package-name <PACKAGE_NAME>`** — Override the package/module name (defaults to spec bin name)
-- **`--spec <SPEC>`** — Raw string spec input
+- **`--spec <SPEC>`** — The spec itself, as a string, instead of a file
 - **`-h --help`** — Print help
diff --git a/docs/cli/reference/index.md b/docs/cli/reference/index.md
index 9717a12a0..d5a4654ff 100644
--- a/docs/cli/reference/index.md
+++ b/docs/cli/reference/index.md
@@ -12,8 +12,8 @@
 
 ## Flags
 
-- **`--completions <COMPLETIONS>`** — Outputs completions for the specified shell for completing the `usage` CLI itself
-- **`--usage-spec`** — Outputs a `usage.kdl` spec for this CLI itself
+- **`--completions <COMPLETIONS>`** — Print a completion script for the `usage` CLI itself, for the named shell
+- **`--usage-spec`** — Print the usage spec for the `usage` CLI itself
 - **`-h --help`** — Print help
 - **`-V --version`** — Print version
 
diff --git a/docs/cli/reference/lint.md b/docs/cli/reference/lint.md
index 992445658..864e00863 100644
--- a/docs/cli/reference/lint.md
+++ b/docs/cli/reference/lint.md
@@ -6,11 +6,15 @@
 - **Effect:** read-only
 - **Source code:** [`cli/src/cli/lint.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/lint.rs)
 
-Lint a usage spec file for common issues
+Lint a usage spec for mistakes that still parse
+
+A spec can be valid KDL and still be wrong: a flag or subcommand declared twice, a required argument after an optional one, a variadic argument that is not last, a command or flag with no help, an example its own spec cannot parse. Each finding carries a code such as `duplicate-flag`, and `--format json` prints the findings as a list for a script to act on.
+
+Exits 1 when there is an error, or a warning under `--warnings-as-errors`.
 
 ## Arguments
 
-- **`<FILE>`** — A usage spec file to lint, use "-" to read from stdin
+- **`<FILE>`** — A usage spec file, or a script with a usage shebang; "-" reads stdin
 
 ## Flags
 
diff --git a/docs/cli/reference/mcp.md b/docs/cli/reference/mcp.md
index bb70a5150..116757813 100644
--- a/docs/cli/reference/mcp.md
+++ b/docs/cli/reference/mcp.md
@@ -12,8 +12,13 @@ Serve a usage spec over the Model Context Protocol
 Reads JSON-RPC over stdin and writes responses to stdout, which is how MCP
 clients launch a local server. Point one at `usage mcp -f mycli.usage.kdl`.
 
+Two tools are served: `list_commands`, every command with its effect, and
+`describe_command`, one command's help, flags, and arguments. Together they
+let an agent learn what a CLI does, and what running it would touch, without
+running it.
+
 ## Flags
 
-- **`-f --file <FILE>`** — Usage spec file (not "-": stdin is the MCP transport)
-- **`-s --spec <SPEC>`** — Raw string spec input
+- **`-f --file <FILE>`** — A usage spec file, or a script with a usage shebang (not "-": stdin is the MCP transport)
+- **`-s --spec <SPEC>`** — The spec itself, as a string, instead of a file
 - **`-h --help`** — Print help
diff --git a/docs/cli/reference/powershell.md b/docs/cli/reference/powershell.md
index 68710a572..9fed0bd01 100644
--- a/docs/cli/reference/powershell.md
+++ b/docs/cli/reference/powershell.md
@@ -5,21 +5,29 @@
 - **Usage:** `usage powershell [-h] [--help] <SCRIPT> [ARGS]…`
 - **Source code:** [`cli/src/cli/shell.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/shell.rs)
 
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`-h` and `--help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 
 ## Arguments
 
-- **`<SCRIPT>`**
-- **`[ARGS]…`** — Arguments to pass to script
+- **`<SCRIPT>`** — The script to run; its spec is read from the `#USAGE` comments at the top of the file
+- **`[ARGS]…`** — Arguments to pass to the script
 
   Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 
 ## Flags
 
-- **`-h`** — Show help
-- **`--help`** — Show help
+- **`-h`** — Print the script's help page instead of running it
+- **`--help`** — Print the script's help page instead of running it
diff --git a/docs/cli/reference/zsh.md b/docs/cli/reference/zsh.md
index 1d28f5c21..4dc6733fe 100644
--- a/docs/cli/reference/zsh.md
+++ b/docs/cli/reference/zsh.md
@@ -5,21 +5,29 @@
 - **Usage:** `usage zsh [-h] [--help] <SCRIPT> [ARGS]…`
 - **Source code:** [`cli/src/cli/shell.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/shell.rs)
 
-Execute a shell script with the specified shell
+Run a script whose usage spec is written in its own comments
 
-Typically, this will be called by a script's shebang.
+Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
+hands the script and its arguments to `usage`, which parses them against the `#USAGE`
+lines at the top of the file and then runs the script with this shell. Each flag and
+argument reaches the script as an environment variable named `usage_<name>`, so
+`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
+`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+containing a space stays quoted.
 
-If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
-to properly escape and quote values with spaces in them.
+`-h` and `--help` print the script's help page rather than this one. The shell is found
+on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
+`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
+`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
 
 ## Arguments
 
-- **`<SCRIPT>`**
-- **`[ARGS]…`** — Arguments to pass to script
+- **`<SCRIPT>`** — The script to run; its spec is read from the `#USAGE` comments at the top of the file
+- **`[ARGS]…`** — Arguments to pass to the script
 
   Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
 
 ## Flags
 
-- **`-h`** — Show help
-- **`--help`** — Show help
+- **`-h`** — Print the script's help page instead of running it
+- **`--help`** — Print the script's help page instead of running it
diff --git a/docs/cli/scripts.md b/docs/cli/scripts.md
index 7bf1eac38..ce934eda8 100644
--- a/docs/cli/scripts.md
+++ b/docs/cli/scripts.md
@@ -1,17 +1,17 @@
 # Usage Scripts
 
-Scripts can be used with the Usage CLI to display help, parse args, and autocomplete in
-any language.
-For this to work, we add comments to the script that describe the flags and arguments that the
-script accepts.
+A script can have `--help`, parsed arguments, and tab completion without a line of parsing code
+in it. The spec lives in comments at the top of the file, and a `usage` shebang runs the script
+through the parser first. Each flag and argument reaches the script as an environment variable
+named `usage_<name>`.
 
 ::: tip Enabling autocompletion
-Tab-completion for shebang scripts is opt-in: add
-`source <(usage g completion-init bash)` to your `~/.bashrc` (one-time setup)
-to enable `<Tab>` on every `usage`-shebang script on `$PATH`. See
-[Generating Completion Scripts](./completions.md) for details and other shells.
+Tab completion for shebang scripts is one line of setup: `source <(usage g completion-init bash)`
+in `~/.bashrc` enables `<Tab>` on every `usage`-shebang script on `$PATH`. See
+[Generating Completion Scripts](./completions.md#shebang-scripts) for zsh and fish.
 :::
-Here is an example in bash:
+
+In bash:
 
 ```bash
 #!/usr/bin/env -S usage bash
@@ -29,7 +29,7 @@ else
 fi
 ```
 
-Assuming this script was located at `./mycli`, it could be used like this:
+With the script at `./mycli`:
 
 ```bash
 $ ./mycli --help
@@ -40,7 +40,8 @@ $ cat output.txt
 Hello, alice
 ```
 
-For languages that use `//` for comments, like JavaScript, you can use `//USAGE` comments:
+A language without a dedicated command goes through `usage exec`, which names the interpreter to
+run. The comment prefix follows the language, so JavaScript uses `//USAGE`:
 
 ```js
 #!/usr/bin/env -S usage exec node
@@ -62,10 +63,7 @@ fs.appendFileSync(usage_file, `Hello, ${user}\n`);
 
 ## Short Flag Chaining
 
-Short flag chaining allows you to combine multiple single-character flags into a single argument.
-This can make command-line usage more concise and easier to type.
-
-For example, consider the following script:
+Single-character flags can be bundled into one word, so `-abc` means `-a -b -c`:
 
 ```bash
 #!/usr/bin/env -S usage bash
@@ -84,8 +82,6 @@ if [ "$usage_c" = "true" ]; then
 fi
 ```
 
-Assuming this script was located at `./mycli`, it could be used like this:
-
 ```bash
 $ ./mycli -abc
 Option A is set
@@ -93,18 +89,15 @@ Option B is set
 Option C is set
 ```
 
-In this example, the `-a`, `-b`, and `-c` flags are combined into a single `-abc` argument, enabling all three options at once.
-
 ## Shell Escaping
 
 ### `var=#true`
 
-When using `var=#true`, the value will be a single string (because that's all env vars can do)
-delimited
-by spaces. If an arg itself has a space, then it will have quotes around it. This logic is handled
-by [`shell_words::join()`](https://docs.rs/shell-words/latest/shell_words/fn.join.html). For now,
-this is not customizable behavior. It would be possible to
-support [alternatives](https://github.com/jdx/usage/issues/189) though.
+An environment variable holds one string, so a flag or argument declared `var=#true` arrives as
+its values joined with spaces. A value that itself contains a space is quoted, as
+[`shell_words::join()`](https://docs.rs/shell-words/latest/shell_words/fn.join.html) quotes it,
+so `eval set -- "$usage_files"` recovers the list in a POSIX shell. The joining is not
+configurable yet; [issue 189](https://github.com/jdx/usage/issues/189) tracks alternatives.
 
 ## Windows
 
diff --git a/docs/cli/sdk.md b/docs/cli/sdk.md
index 9becb6f95..9e4bf8a22 100644
--- a/docs/cli/sdk.md
+++ b/docs/cli/sdk.md
@@ -1,57 +1,47 @@
 # Generating Type-Safe SDKs
 
-Usage CLI can generate type-safe SDK client libraries from a Usage spec. The generated SDK is a
-**subprocess wrapper** -- it invokes your CLI binary via `subprocess.run` / `child_process.spawn`,
-not a native binding. It provides type definitions for arguments, flags,
-and choices, along with a client that constructs the correct CLI argument list for you.
-
-## When to Use This
-
-### CLIs without language bindings
-
-Popular tools like ffmpeg have hand-written bindings in many languages, but the vast majority of CLI
-tools don't. For tools like `restic`, `rclone`, `pandoc`, `age`, or any internal CLI, the only
-option has been to manually construct argument lists:
+A CLI without a client library is called the same way everywhere: a hand-built list of strings
+handed to `subprocess.run` or `child_process.spawn`, where a misspelled flag is found at runtime
+by whoever runs it. `usage generate sdk` derives the client from the spec instead. The result is
+a **subprocess wrapper**, not a native binding: typed definitions for every command's arguments,
+flags, and choices, and a client that builds the argument list and invokes the binary.
 
 ```python
-# before: stringly-typed, no autocomplete, typos slip through
+# before: stringly typed, no autocomplete, typos found at runtime
 subprocess.run(["rclone", "copy", src, dst, "--progress", "--transfers", "4"])
-```
-
-With a generated SDK:
 
-```python
-# after: typed, autocomplete, mistakes caught at lint time
+# after: typed, autocompleted, mistakes caught by the type checker
 rclone.copy(src, dst, progress=True, transfers=4)
 ```
 
-### Stay in sync with CLI versions
+## When it fits
+
+**CLIs without bindings.** A few tools such as ffmpeg have hand-written bindings in many
+languages. Most do not: `restic`, `rclone`, `pandoc`, `age`, and every internal CLI are called by
+assembling strings. A spec for the tool is enough to generate the binding.
 
-Hand-written bindings drift out of date when the CLI evolves. Generated SDKs solve this the same way
-Protobuf/gRPC does -- the spec is the source of truth, the SDK is a derived artifact:
+**Staying in sync.** Hand-written bindings drift as the CLI changes. A generated SDK is a derived
+artifact, the way Protobuf stubs are, so regenerating it on each release is the whole of the
+maintenance:
 
 ```sh
-# in CI, when you cut a new release:
 usage generate sdk -l python -o ./sdk/python/ -f ./mycli.usage.kdl
 git commit -m "chore: regenerate sdk from v2.3.0 spec"
 ```
 
-### Internal platform CLIs
-
-This is the strongest use case. Companies typically have internal CLIs for deployment, config
-management, database migrations, etc. Teams in different languages (Python scripts, TypeScript
-services, Rust tools) all need to call these CLIs, and each team independently writes fragile
-subprocess calls. With a Usage spec, you generate typed SDKs for all languages from a single source
-of truth:
+**Internal platform CLIs.** This is the strongest case. A company's deploy, config, and migration
+tools are called from Python scripts, TypeScript services, and Rust tools alike, and each team
+writes its own fragile subprocess calls. One spec generates a typed client for every language at
+once:
 
 ```ts
-// auto-generated, always in sync with the CLI
+// generated, and regenerated with the CLI
 import { deploy } from "@internal/platform-sdk";
 const result = await deploy({ env: "prod", service: "api", replicas: 3 });
-//                        ^ typed, choices-constrained, required-checked
+//                        ^ typed, choices constrained, required fields checked
 ```
 
-## Quick Start
+## Quick start
 
 Given a spec file `mycli.usage.kdl`:
 
@@ -59,7 +49,7 @@ Given a spec file `mycli.usage.kdl`:
 usage generate sdk -l typescript -o ./sdk -f ./mycli.usage.kdl
 ```
 
-This generates a complete SDK in the `./sdk` directory, ready to use:
+The `./sdk` directory is a complete package, ready to import:
 
 ```ts
 import { Mycli } from "./sdk";
@@ -74,13 +64,13 @@ if (result.ok) {
 }
 ```
 
-## Supported Languages
+## Supported languages
 
-| Language   | Flag            | Output Files                                         |
+| Language   | Flag            | Output files                                         |
 | ---------- | --------------- | ---------------------------------------------------- |
 | TypeScript | `-l typescript` | `types.ts`, `client.ts`, `runtime.ts`, `index.ts`    |
 | Python     | `-l python`     | `types.py`, `client.py`, `runtime.py`, `__init__.py` |
-| Rust       | Coming soon     |                                                      |
+| Rust       | planned         |                                                      |
 
 ### TypeScript
 
@@ -88,9 +78,8 @@ if (result.ok) {
 usage generate sdk -l typescript -o ./sdk -f ./mycli.usage.kdl
 ```
 
-Generates ES module files with full type annotations. The client uses `spawn` from
-`node:child_process` under the hood and all `exec()` methods are async, returning
-`Promise<CliResult>`.
+ES modules with full type annotations. The client spawns the binary with `node:child_process`,
+so every `exec()` is async and returns a `Promise<CliResult>`.
 
 ```ts
 import { Mycli, BuildArgs, BuildFlags } from "./sdk";
@@ -108,8 +97,8 @@ const result = await cli.build.exec(
 usage generate sdk -l python -o ./sdk -f ./mycli.usage.kdl
 ```
 
-Generates a Python package with `@dataclass` type definitions and type annotations. The client uses
-`subprocess.run` under the hood.
+A package of `@dataclass` types with annotations throughout. The client runs the binary with
+`subprocess.run`.
 
 ```python
 from sdk import Mycli, BuildArgs, BuildFlags
@@ -123,34 +112,29 @@ if result.ok:
     print(result.stdout)
 ```
 
-### Rust
-
-_Rust SDK support is coming soon._
-
-## How It Works
+## How it works
 
-Each generated SDK consists of three parts:
+Each SDK is three modules:
 
-1. **Types module** -- Type definitions for every command's args and flags. Choice constraints are
-   rendered as union types (TypeScript) or `Literal` types (Python).
-   Global flags are propagated to all subcommand flag types.
+1. **Types.** A definition for every command's args and flags. `choices` become union types in
+   TypeScript and `Literal` types in Python, and global flags are repeated on every subcommand's
+   flag type so that they can be passed where they are used.
 
-2. **Client module** -- A nested class/struct hierarchy mirroring the subcommand tree. Each node has
-   an `exec()` method that constructs the CLI argument list and invokes the binary. Flag arguments
-   are built via a helper method that handles value flags, boolean flags, count flags, negate flags,
-   and repeatable flags.
+2. **Client.** A nested class hierarchy mirroring the subcommand tree. Each node has an `exec()`
+   that assembles the argument list and runs the binary; one helper handles value flags, boolean
+   flags, count flags, negated flags, and repeatable flags.
 
-3. **Runtime module** -- A small, static module containing `CliResult` (stdout, stderr, exit code)
-   and `CliRunner` (the subprocess invocation logic). This module is identical across all SDKs
-   generated from the same language target.
+3. **Runtime.** A small static module holding `CliResult` (stdout, stderr, exit code) and
+   `CliRunner`, the subprocess call. It is identical across every SDK generated for the same
+   language.
 
 ## Structured and streaming outputs
 
 When a command [declares structured outputs](/spec/reference/output), the SDK keeps `exec()` for
-raw text and adds a method matching each wire format. A `json` output produces `execJson()` in
-TypeScript and `exec_json()` in Python; a `jsonl` output produces an async iterable or iterator
-that parses one document at a time. The generated result still carries stderr and the exit code,
-because a documented nonzero status may accompany valid structured output.
+raw text and adds a method per wire format. A `json` output produces `execJson()` in TypeScript
+and `exec_json()` in Python; a `jsonl` output produces an async iterable or an iterator that
+parses one document at a time. The result still carries stderr and the exit code, because a
+documented nonzero status may accompany valid structured output.
 
-Declared JSON Schemas are exported as string constants, and declared exit statuses become a table
-and a literal-union type in the generated types module.
+Declared JSON Schemas are exported as string constants, and declared exit statuses become a
+table and a literal-union type in the types module.
diff --git a/docs/spec/index.md b/docs/spec/index.md
index 9884ca15e..92a760740 100644
--- a/docs/spec/index.md
+++ b/docs/spec/index.md
@@ -1,23 +1,25 @@
 # Usage Specification
 
-Usage is a spec and CLI for defining CLI tools. Arguments, flags, environment variables, and config
-files can all be defined in a Usage spec. It can be thought of
-like [OpenAPI (swagger)](https://www.openapis.org/)
-for CLIs. Here are some potential reasons for defining your CLI with a Usage spec:
-
-- Generate autocompletion scripts
-- Generate markdown documentation
-- Generate man pages
-- Generate type-safe SDK client libraries for TypeScript and Python
-- Use an advanced arg parser in any language
-- Scaffold one spec into different CLI frameworks—even different languages
-- [coming soon] Host your CLI documentation on usage.sh
+A usage spec describes a command-line interface once: its commands, flags, arguments,
+environment variables, and config files, written in [KDL](https://kdl.dev/). It is the contract
+the rest of the project is built on. The [Rust](/rust/) and [Go](/go/) frameworks parse against
+it, and [the CLI](/cli/) generates from it. Think of it as [OpenAPI](https://www.openapis.org/)
+for CLIs: one declaration, from which everything a CLI ships with is derived rather than written
+again.
+
+- Shell completions for bash, zsh, fish, PowerShell, and Nushell
+- Markdown documentation and man pages
+- Type-safe TypeScript and Python client libraries
+- Argument parsing in any language, and typed parsers in Rust and Go
+- A machine-readable answer to what changed in a release, from [`usage diff`](/cli/diff)
+
+A spec need not be written by hand. A CLI built with the Rust framework prints its own, and
+[integrations](/spec/integrations) extract one from clap, Cobra, argparse, and a dozen other
+frameworks.
 
 ## Example Usage Spec
 
-Usage specs are written in [kdl](https://kdl.dev/) which is a newer document language that sort of
-combines
-the best of XML and JSON. Here is a basic example CLI definition:
+KDL reads like a config file and nests like XML. A basic CLI:
 
 ```kdl
 // optional metadata
@@ -158,22 +160,19 @@ cmd "uninstall" {
 
 ## Compatibility
 
-Usage is not designed to model every possible CLI. It's generally designed for CLIs that follow
-standard GNU-style
-options. While it is not high priority, adding support for CLIs that differ from the standard may be
-allowed.
-As an example, some CLIs may accept multiple options on a flag: `--flag option1 option2`. This is
-poor design
-as it's unclear to the user if "option2" is another positional arg or not. What we will likely do
-for behaviors
-like this is allow it, but show a warning that it is not recommended.
-
-## CLI Framework Developers
-
-You could think of Usage like an LSP (Language Server Protocol) for CLIs.
-
-Those building CLI frameworks can really benefit from Usage. Rather than building features like
-autocompletion
-for every shell, just output a Usage definition and use the Usage CLI to generate autocompletion
-scripts for all
-of the shells it supports.
+The spec models CLIs that follow GNU conventions: `--long` and `-s` flags, `--flag=value` and
+`--flag value`, bundled short flags, and `--` to end flag parsing. It does not set out to model
+every CLI that exists. A flag that takes several values in a row, `--flag one two`, is the usual
+example of what it leaves out: a reader of that line cannot tell whether `two` is the flag's
+second value or the next positional, and neither can a parser. The [argv grammar](/spec/argv)
+says exactly what is accepted.
+
+## For CLI Framework Authors
+
+A framework that can emit a usage spec gets everything downstream of it without building any of
+it. Completion for five shells, Markdown, man pages, and SDKs are each written once against the
+spec rather than once per framework, so emitting the spec is the whole integration. Every
+[integration](/spec/integrations) that exists is this shape. The same holds in reverse for a
+framework built on the spec: the [Rust](/rust/) and [Go](/go/) frameworks answer a shared
+conformance corpus, so a parser that passes it is known to agree with the reference
+implementation.
diff --git a/docs/spec/integrations.md b/docs/spec/integrations.md
index 8d053ebb9..357369901 100644
--- a/docs/spec/integrations.md
+++ b/docs/spec/integrations.md
@@ -1,6 +1,6 @@
 # Integrations
 
-Integrations extract CLI definitions from framework internals and output a [usage spec](/spec/) in KDL format. This enables shell completions, markdown docs, and man pages from your existing CLI framework — no manual spec authoring needed.
+An integration reads a CLI's definition out of the framework it was written in and prints a [usage spec](/spec/). An existing CLI gets completions, Markdown docs, man pages, and everything else the spec drives, without a hand-written spec and without changing frameworks.
 
 ## Available
 
@@ -23,7 +23,7 @@ Integrations extract CLI definitions from framework internals and output a [usag
 
 ## Planned
 
-Contributions welcome! Here are the frameworks we'd like to support next.
+Contributions are welcome. These are the frameworks worth covering next.
 
 ### High Priority
 

From 14abe0c67f5bfe16aa4509970f20c629dad7c3af Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Wed, 2 Sep 2026 13:14:24 +0000
Subject: [PATCH 2/5] docs(cli): fix a broken example and two wrong claims

Self-review of the previous commit against the actual behavior:

- The pipeline in the CLI index used `--out-dir` without `--multi`, which the
  spec declares as `required_if`, so the example errored out. It takes `-mf`.
- `--url-prefix` was described as switching relative links to site-rooted ones.
  Links are root-relative either way (`/bash.md`); the prefix is prepended.
- The claim that help text is wrapped in `<pre>` and that
  `--replace-pre-with-code-fences` converts those was wrong on both halves.
  Nothing emits `<pre>`, and the conversion targets four-space indented
  blocks. That sentence is gone rather than restated: the flag is a no-op as
  wired today, since `MarkdownRenderer::new` renders the help fields before
  the builder can set the option, and describing broken behavior is worse than
  describing none.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/cli/index.md    | 2 +-
 docs/cli/markdown.md | 7 +++----
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/docs/cli/index.md b/docs/cli/index.md
index 0cd8537af..73daa0731 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -23,7 +23,7 @@ script whose `#USAGE` comments declare it, or `-` for stdin. A binary built with
 [Rust framework](/rust/) prints its own spec, so documenting it needs no file at all:
 
 ```sh
-mycli __usage_spec__ | usage generate markdown -f - --out-dir docs
+mycli __usage_spec__ | usage generate markdown -mf - --out-dir docs
 ```
 
 The [reference](/cli/reference/) lists every command and flag. It is generated from `usage`'s
diff --git a/docs/cli/markdown.md b/docs/cli/markdown.md
index 2977ccb52..bd5c1d0b1 100644
--- a/docs/cli/markdown.md
+++ b/docs/cli/markdown.md
@@ -28,10 +28,9 @@ docs
 └── update.md
 ```
 
-Links between the pages are relative to that directory; `--url-prefix /cli/reference` roots
-them at a site path instead. Help text is wrapped in `<pre>` so that its line breaks survive
-any renderer; `--replace-pre-with-code-fences` swaps those for fenced code blocks, which is
-what a renderer with syntax highlighting wants.
+Links between the pages are written from the root of the output, as `/bash.md`.
+`--url-prefix /cli/reference` puts a path in front of them, `/cli/reference/bash.md`, which is
+what a docs site serving the pages under a subdirectory needs.
 
 ## Custom templates from the CLI
 

From 9fe3fd493c7ecb524677299372e5f3b26cabd06d Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Wed, 2 Sep 2026 13:30:41 +0000
Subject: [PATCH 3/5] docs(cli): give each shell command its own help text

Review feedback: the four shell commands share one long help block, and the
rewrite had put a `usage bash` shebang, the `bash` program name, and the Git
Bash/WSL note in it. Three commands out of four then told the reader to write
the wrong shebang.

The shared paragraphs are now shell-agnostic, and the macro takes a fourth
argument for the part that is not: the shebang to write, the program that ends
up running, and the variable that overrides it. Git Bash stays in bash's help,
where it belongs, since bash is the only one of the four that resolves to the
WSL launcher.

The shared text is hand-wrapped to 80 columns to match the other
`verbatim_doc_comment` help in this crate. Verbatim keeps the line breaks, so
wider source lines were being re-wrapped by the renderer into ragged output.

Also from review: the CLI index claimed every command reads a spec the same
three ways. `--spec` takes one as a string, `generate completion` takes a
command that prints one, and `mcp` will not read stdin at all, so it says
"most" and names the alternatives.

The collapsed `#[usage(...)]` attribute in the macro is deliberate: as a
multi-line attribute inside the macro body, rustfmt re-indented it further on
every run and never reached a fixed point, so `cargo fmt --check` could not pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 cli/assets/usage.1               | 90 ++++++++++++++++++--------------
 cli/src/cli/shell.rs             | 65 +++++++++++++++--------
 cli/src/test.rs                  | 52 +++++++++++++-----
 cli/usage.usage.kdl              | 90 ++++++++++++++++++--------------
 docs/cli/index.md                |  8 +--
 docs/cli/reference/bash.md       | 23 ++++----
 docs/cli/reference/commands.json |  8 +--
 docs/cli/reference/fish.md       | 22 ++++----
 docs/cli/reference/powershell.md | 23 ++++----
 docs/cli/reference/zsh.md        | 22 ++++----
 10 files changed, 240 insertions(+), 163 deletions(-)

diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index 82575c5a8..851151193 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -116,18 +116,21 @@ Run a script whose usage spec is written in its own comments
 .SH "USAGE BASH"
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env \-S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`\-\-force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `\-\-force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`\-h` and `\-\-help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`\-h` and `\-\-help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env \-S usage bash`, and the
+program it runs is `bash` from PATH. `USAGECLI_SHELL_BASH` names a
+different one, which is how it is pointed at Git Bash on a Windows
+machine where `bash` is the WSL launcher.
 .PP
 \fBUsage:\fR usage bash [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -296,18 +299,20 @@ The command line to explain, starting with the program name
 .SH "USAGE FISH"
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env \-S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`\-\-force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `\-\-force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`\-h` and `\-\-help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`\-h` and `\-\-help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env \-S usage fish`, and the
+program it runs is `fish` from PATH. `USAGECLI_SHELL_FISH` names a
+different one.
 .PP
 \fBUsage:\fR usage fish [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -659,18 +664,21 @@ Print help
 .SH "USAGE POWERSHELL"
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env \-S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`\-\-force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `\-\-force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`\-h` and `\-\-help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`\-h` and `\-\-help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env \-S usage powershell`, and
+the program it runs is `pwsh` from PATH. `USAGECLI_SHELL_PWSH` names a
+different one, which is also how it is pointed at `powershell.exe` on a
+machine that has only Windows PowerShell.
 .PP
 \fBUsage:\fR usage powershell [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -705,18 +713,20 @@ Print help
 .SH "USAGE ZSH"
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env \-S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`\-\-force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `\-\-force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`\-h` and `\-\-help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`\-h` and `\-\-help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env \-S usage zsh`, and the
+program it runs is `zsh` from PATH. `USAGECLI_SHELL_ZSH` names a
+different one.
 .PP
 \fBUsage:\fR usage zsh [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
diff --git a/cli/src/cli/shell.rs b/cli/src/cli/shell.rs
index 10d4c2058..4784fefad 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -38,33 +38,33 @@ pub struct Shell {
 
 /// One of the four commands that run a script, which differ only in the shell they name.
 ///
-/// The long help is the same paragraph four times over, so it is written here once. A
-/// `concat!` in a `long_about` would not do: the attribute takes a literal, and by the time
-/// the derive reads it a macro call is not one.
+/// Everything true of all four is written here once. What is not — the shebang to write, the
+/// program that ends up running, and the variable that overrides it — is passed in as
+/// `$shell_specific`, because a page that told a `usage zsh` reader to write a `usage bash`
+/// shebang would be wrong three times out of four.
+///
+/// One literal per shell rather than interpolation: a `concat!` in a doc attribute is still a
+/// macro call by the time the derive reads it, and the derive wants a literal.
 macro_rules! shell_command {
-    ($ty:ident, $program:literal, $about:tt) => {
+    ($ty:ident, $program:literal, $about:tt, $shell_specific:literal) => {
         #[doc = "Run a script whose usage spec is written in its own comments"]
         #[doc = ""]
-        #[doc = "Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel"]
-        #[doc = "hands the script and its arguments to `usage`, which parses them against the `#USAGE`"]
-        #[doc = "lines at the top of the file and then runs the script with this shell. Each flag and"]
-        #[doc = "argument reaches the script as an environment variable named `usage_<name>`, so"]
-        #[doc = "`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared"]
-        #[doc = "`var=#true` arrives as one string, joined with `shell_words::join()` so that an element"]
+        #[doc = "Usually reached through the script's shebang: the kernel hands the"]
+        #[doc = "script and its arguments to `usage`, which parses them against the"]
+        #[doc = "`#USAGE` lines at the top of the file, then runs the script with this"]
+        #[doc = "shell. Each flag and argument reaches the script as an environment"]
+        #[doc = "variable named `usage_<name>`, so `--force` becomes `usage_force` and"]
+        #[doc = "`<file>` becomes `usage_file`. A value declared `var=#true` arrives as"]
+        #[doc = "one string, joined with `shell_words::join()` so that an element"]
         #[doc = "containing a space stays quoted."]
         #[doc = ""]
-        #[doc = "`-h` and `--help` print the script's help page rather than this one. The shell is found"]
-        #[doc = "on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and"]
-        #[doc = "`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how"]
-        #[doc = "`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL."]
+        #[doc = "`-h` and `--help` print the script's help page rather than this one."]
+        #[doc = ""]
+        #[doc = $shell_specific]
         #[derive(Debug, Args)]
         // The words after the script are the script's, so a flag `usage` does not know is a
         // value to forward rather than a mistake to report — the root's `error` stops here.
-        #[usage(
-            about = $about,
-            unknown_flags = "value",
-            verbatim_doc_comment
-        )]
+        #[usage(about = $about, unknown_flags = "value", verbatim_doc_comment)]
         pub struct $ty {
             #[usage(flatten)]
             pub shell: Shell,
@@ -80,14 +80,33 @@ macro_rules! shell_command {
     };
 }
 
-shell_command!(Bash, "bash", "Execute a shell script using bash");
-shell_command!(Fish, "fish", "Execute a shell script using fish");
+shell_command!(
+    Bash,
+    "bash",
+    "Execute a shell script using bash",
+    // Hand-wrapped for an 80-column terminal, like every other `verbatim_doc_comment` in
+    // this crate: verbatim keeps these line breaks, so a longer line is re-wrapped by the
+    // help renderer and comes out ragged.
+    "This command's shebang is `#!/usr/bin/env -S usage bash`, and the\nprogram it runs is `bash` from PATH. `USAGECLI_SHELL_BASH` names a\ndifferent one, which is how it is pointed at Git Bash on a Windows\nmachine where `bash` is the WSL launcher."
+);
+shell_command!(
+    Fish,
+    "fish",
+    "Execute a shell script using fish",
+    "This command's shebang is `#!/usr/bin/env -S usage fish`, and the\nprogram it runs is `fish` from PATH. `USAGECLI_SHELL_FISH` names a\ndifferent one."
+);
 shell_command!(
     PowerShell,
     "pwsh",
-    "Execute a shell script using PowerShell"
+    "Execute a shell script using PowerShell",
+    "This command's shebang is `#!/usr/bin/env -S usage powershell`, and\nthe program it runs is `pwsh` from PATH. `USAGECLI_SHELL_PWSH` names a\ndifferent one, which is also how it is pointed at `powershell.exe` on a\nmachine that has only Windows PowerShell."
+);
+shell_command!(
+    Zsh,
+    "zsh",
+    "Execute a shell script using zsh",
+    "This command's shebang is `#!/usr/bin/env -S usage zsh`, and the\nprogram it runs is `zsh` from PATH. `USAGECLI_SHELL_ZSH` names a\ndifferent one."
 );
-shell_command!(Zsh, "zsh", "Execute a shell script using zsh");
 
 impl Shell {
     pub fn run(&mut self, shell: &str) -> usage::miette::Result<()> {
diff --git a/cli/src/test.rs b/cli/src/test.rs
index 1fac4c389..204e40e9c 100644
--- a/cli/src/test.rs
+++ b/cli/src/test.rs
@@ -14,24 +14,50 @@ fn shell_commands_keep_their_verbatim_long_help() {
         .find(|cmd| cmd.cmd.name == "bash")
         .expect("bash command");
     assert_eq!(bash.about, Some("Execute a shell script using bash"));
-    // Every line break of the doc comment is kept, which is what `verbatim_doc_comment` promises;
-    // without it the derive would reflow each paragraph into one line.
-    let expected = [
+    // Every line break of the doc comment is kept, which is what `verbatim_doc_comment`
+    // promises; without it the derive would reflow each paragraph into one line.
+    let shared = [
         "Run a script whose usage spec is written in its own comments",
         "",
-        "Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel",
-        "hands the script and its arguments to `usage`, which parses them against the `#USAGE`",
-        "lines at the top of the file and then runs the script with this shell. Each flag and",
-        "argument reaches the script as an environment variable named `usage_<name>`, so",
-        "`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared",
-        "`var=#true` arrives as one string, joined with `shell_words::join()` so that an element",
+        "Usually reached through the script's shebang: the kernel hands the",
+        "script and its arguments to `usage`, which parses them against the",
+        "`#USAGE` lines at the top of the file, then runs the script with this",
+        "shell. Each flag and argument reaches the script as an environment",
+        "variable named `usage_<name>`, so `--force` becomes `usage_force` and",
+        "`<file>` becomes `usage_file`. A value declared `var=#true` arrives as",
+        "one string, joined with `shell_words::join()` so that an element",
         "containing a space stays quoted.",
         "",
-        "`-h` and `--help` print the script's help page rather than this one. The shell is found",
-        "on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and",
-        "`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how",
-        "`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
+        "`-h` and `--help` print the script's help page rather than this one.",
+        "",
+        // Joining leaves the blank line that separates the shared text from the
+        // per-shell tail, so `shared` can be concatenated with either.
+        "",
     ]
     .join("\n");
+    let expected = format!(
+        "{shared}This command's shebang is `#!/usr/bin/env -S usage bash`, and the\n\
+         program it runs is `bash` from PATH. `USAGECLI_SHELL_BASH` names a\n\
+         different one, which is how it is pointed at Git Bash on a Windows\n\
+         machine where `bash` is the WSL launcher."
+    );
     assert_eq!(bash.long_about, Some(expected.as_str()));
+
+    // The shell-specific tail is per command, not shared: a `usage zsh` reader must not be
+    // told to write a `usage bash` shebang. This is what the macro's fourth argument is for.
+    let zsh = Cli::spec()
+        .root
+        .subcommands
+        .iter()
+        .find(|cmd| cmd.cmd.name == "zsh")
+        .expect("zsh command");
+    let zsh_long = zsh.long_about.expect("zsh long help");
+    assert!(zsh_long.starts_with(&shared), "{zsh_long}");
+    assert!(
+        zsh_long.contains("`#!/usr/bin/env -S usage zsh`"),
+        "{zsh_long}"
+    );
+    assert!(zsh_long.contains("USAGECLI_SHELL_ZSH"), "{zsh_long}");
+    assert!(!zsh_long.contains("bash"), "{zsh_long}");
+    assert!(!zsh_long.contains("Git Bash"), "{zsh_long}");
 }
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index c4f53a9bb..ada5be20d 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -44,18 +44,21 @@ cmd bash help="Execute a shell script using bash" unknown_flags=value {
     long_help #"""
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `--force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`-h` and `--help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`-h` and `--help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env -S usage bash`, and the
+program it runs is `bash` from PATH. `USAGECLI_SHELL_BASH` names a
+different one, which is how it is pointed at Git Bash on a Windows
+machine where `bash` is the WSL launcher.
 """#
     use shell
     arg <SCRIPT> help="The script to run; its spec is read from the `#USAGE` comments at the top of the file"
@@ -187,18 +190,20 @@ cmd fish help="Execute a shell script using fish" unknown_flags=value {
     long_help #"""
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `--force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`-h` and `--help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`-h` and `--help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env -S usage fish`, and the
+program it runs is `fish` from PATH. `USAGECLI_SHELL_FISH` names a
+different one.
 """#
     use shell
     arg <SCRIPT> help="The script to run; its spec is read from the `#USAGE` comments at the top of the file"
@@ -479,18 +484,21 @@ cmd powershell help="Execute a shell script using PowerShell" unknown_flags=valu
     long_help #"""
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `--force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`-h` and `--help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`-h` and `--help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env -S usage powershell`, and
+the program it runs is `pwsh` from PATH. `USAGECLI_SHELL_PWSH` names a
+different one, which is also how it is pointed at `powershell.exe` on a
+machine that has only Windows PowerShell.
 """#
     use shell
     arg <SCRIPT> help="The script to run; its spec is read from the `#USAGE` comments at the top of the file"
@@ -509,18 +517,20 @@ cmd zsh help="Execute a shell script using zsh" unknown_flags=value {
     long_help #"""
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `--force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`-h` and `--help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`-h` and `--help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env -S usage zsh`, and the
+program it runs is `zsh` from PATH. `USAGECLI_SHELL_ZSH` names a
+different one.
 """#
     use shell
     arg <SCRIPT> help="The script to run; its spec is read from the `#USAGE` comments at the top of the file"
diff --git a/docs/cli/index.md b/docs/cli/index.md
index 73daa0731..4a039103f 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -18,9 +18,11 @@ things a CLI ships with, and runs scripts that carry a spec in their own comment
 | Mistakes a spec can have and still parse                    | `usage lint`                 | [reference](/cli/reference/lint)                 |
 | A CLI described to an AI agent, with each command's effect  | `usage mcp`                  | [reference](/cli/reference/mcp)                  |
 
-Every command that reads a spec takes it the same three ways: a `.usage.kdl` file with `-f`, a
-script whose `#USAGE` comments declare it, or `-` for stdin. A binary built with the
-[Rust framework](/rust/) prints its own spec, so documenting it needs no file at all:
+Most of these read a spec the same way: `-f` takes a `.usage.kdl` file, a script whose `#USAGE`
+comments declare one, or `-` for stdin. `--spec` passes one as a string instead, and
+`generate completion` will run a command that prints one, so that a completion script follows
+whichever version of the CLI is installed. A binary built with the [Rust framework](/rust/)
+prints its own spec, so documenting it needs no file at all:
 
 ```sh
 mycli __usage_spec__ | usage generate markdown -mf - --out-dir docs
diff --git a/docs/cli/reference/bash.md b/docs/cli/reference/bash.md
index 12b2bf2b1..0426474d8 100644
--- a/docs/cli/reference/bash.md
+++ b/docs/cli/reference/bash.md
@@ -7,18 +7,21 @@
 
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `--force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`-h` and `--help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`-h` and `--help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env -S usage bash`, and the
+program it runs is `bash` from PATH. `USAGECLI_SHELL_BASH` names a
+different one, which is how it is pointed at Git Bash on a Windows
+machine where `bash` is the WSL launcher.
 
 ## Arguments
 
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index ddca85f19..b82ac80f2 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -58,7 +58,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Execute a shell script using bash",
-        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel\nhands the script and its arguments to `usage`, which parses them against the `#USAGE`\nlines at the top of the file and then runs the script with this shell. Each flag and\nargument reaches the script as an environment variable named `usage_<name>`, so\n`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared\n`var=#true` arrives as one string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one. The shell is found\non PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and\n`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how\n`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
+        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang: the kernel hands the\nscript and its arguments to `usage`, which parses them against the\n`#USAGE` lines at the top of the file, then runs the script with this\nshell. Each flag and argument reaches the script as an environment\nvariable named `usage_<name>`, so `--force` becomes `usage_force` and\n`<file>` becomes `usage_file`. A value declared `var=#true` arrives as\none string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one.\n\nThis command's shebang is `#!/usr/bin/env -S usage bash`, and the\nprogram it runs is `bash` from PATH. `USAGECLI_SHELL_BASH` names a\ndifferent one, which is how it is pointed at Git Bash on a Windows\nmachine where `bash` is the WSL launcher.",
         "name": "bash",
         "aliases": [],
         "hidden_aliases": [],
@@ -568,7 +568,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Execute a shell script using fish",
-        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel\nhands the script and its arguments to `usage`, which parses them against the `#USAGE`\nlines at the top of the file and then runs the script with this shell. Each flag and\nargument reaches the script as an environment variable named `usage_<name>`, so\n`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared\n`var=#true` arrives as one string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one. The shell is found\non PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and\n`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how\n`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
+        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang: the kernel hands the\nscript and its arguments to `usage`, which parses them against the\n`#USAGE` lines at the top of the file, then runs the script with this\nshell. Each flag and argument reaches the script as an environment\nvariable named `usage_<name>`, so `--force` becomes `usage_force` and\n`<file>` becomes `usage_file`. A value declared `var=#true` arrives as\none string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one.\n\nThis command's shebang is `#!/usr/bin/env -S usage fish`, and the\nprogram it runs is `fish` from PATH. `USAGECLI_SHELL_FISH` names a\ndifferent one.",
         "name": "fish",
         "aliases": [],
         "hidden_aliases": [],
@@ -1861,7 +1861,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Execute a shell script using PowerShell",
-        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel\nhands the script and its arguments to `usage`, which parses them against the `#USAGE`\nlines at the top of the file and then runs the script with this shell. Each flag and\nargument reaches the script as an environment variable named `usage_<name>`, so\n`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared\n`var=#true` arrives as one string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one. The shell is found\non PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and\n`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how\n`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
+        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang: the kernel hands the\nscript and its arguments to `usage`, which parses them against the\n`#USAGE` lines at the top of the file, then runs the script with this\nshell. Each flag and argument reaches the script as an environment\nvariable named `usage_<name>`, so `--force` becomes `usage_force` and\n`<file>` becomes `usage_file`. A value declared `var=#true` arrives as\none string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one.\n\nThis command's shebang is `#!/usr/bin/env -S usage powershell`, and\nthe program it runs is `pwsh` from PATH. `USAGECLI_SHELL_PWSH` names a\ndifferent one, which is also how it is pointed at `powershell.exe` on a\nmachine that has only Windows PowerShell.",
         "name": "powershell",
         "aliases": [],
         "hidden_aliases": [],
@@ -1952,7 +1952,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Execute a shell script using zsh",
-        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel\nhands the script and its arguments to `usage`, which parses them against the `#USAGE`\nlines at the top of the file and then runs the script with this shell. Each flag and\nargument reaches the script as an environment variable named `usage_<name>`, so\n`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared\n`var=#true` arrives as one string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one. The shell is found\non PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and\n`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how\n`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.",
+        "help_long": "Run a script whose usage spec is written in its own comments\n\nUsually reached through the script's shebang: the kernel hands the\nscript and its arguments to `usage`, which parses them against the\n`#USAGE` lines at the top of the file, then runs the script with this\nshell. Each flag and argument reaches the script as an environment\nvariable named `usage_<name>`, so `--force` becomes `usage_force` and\n`<file>` becomes `usage_file`. A value declared `var=#true` arrives as\none string, joined with `shell_words::join()` so that an element\ncontaining a space stays quoted.\n\n`-h` and `--help` print the script's help page rather than this one.\n\nThis command's shebang is `#!/usr/bin/env -S usage zsh`, and the\nprogram it runs is `zsh` from PATH. `USAGECLI_SHELL_ZSH` names a\ndifferent one.",
         "name": "zsh",
         "aliases": [],
         "hidden_aliases": [],
diff --git a/docs/cli/reference/fish.md b/docs/cli/reference/fish.md
index 8b34ca3fc..9119c32e1 100644
--- a/docs/cli/reference/fish.md
+++ b/docs/cli/reference/fish.md
@@ -7,18 +7,20 @@
 
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `--force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`-h` and `--help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`-h` and `--help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env -S usage fish`, and the
+program it runs is `fish` from PATH. `USAGECLI_SHELL_FISH` names a
+different one.
 
 ## Arguments
 
diff --git a/docs/cli/reference/powershell.md b/docs/cli/reference/powershell.md
index 9fed0bd01..20caca2e0 100644
--- a/docs/cli/reference/powershell.md
+++ b/docs/cli/reference/powershell.md
@@ -7,18 +7,21 @@
 
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `--force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`-h` and `--help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`-h` and `--help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env -S usage powershell`, and
+the program it runs is `pwsh` from PATH. `USAGECLI_SHELL_PWSH` names a
+different one, which is also how it is pointed at `powershell.exe` on a
+machine that has only Windows PowerShell.
 
 ## Arguments
 
diff --git a/docs/cli/reference/zsh.md b/docs/cli/reference/zsh.md
index 4dc6733fe..c07bd4bd5 100644
--- a/docs/cli/reference/zsh.md
+++ b/docs/cli/reference/zsh.md
@@ -7,18 +7,20 @@
 
 Run a script whose usage spec is written in its own comments
 
-Usually reached through the script's shebang, `#!/usr/bin/env -S usage bash`: the kernel
-hands the script and its arguments to `usage`, which parses them against the `#USAGE`
-lines at the top of the file and then runs the script with this shell. Each flag and
-argument reaches the script as an environment variable named `usage_<name>`, so
-`--force` becomes `usage_force` and `<file>` becomes `usage_file`. A value declared
-`var=#true` arrives as one string, joined with `shell_words::join()` so that an element
+Usually reached through the script's shebang: the kernel hands the
+script and its arguments to `usage`, which parses them against the
+`#USAGE` lines at the top of the file, then runs the script with this
+shell. Each flag and argument reaches the script as an environment
+variable named `usage_<name>`, so `--force` becomes `usage_force` and
+`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
+one string, joined with `shell_words::join()` so that an element
 containing a space stays quoted.
 
-`-h` and `--help` print the script's help page rather than this one. The shell is found
-on PATH; `USAGECLI_SHELL_BASH`, `USAGECLI_SHELL_ZSH`, `USAGECLI_SHELL_FISH` and
-`USAGECLI_SHELL_PWSH` each name a different program to run instead, which is how
-`usage bash` is pointed at Git Bash on a Windows machine where `bash` is WSL.
+`-h` and `--help` print the script's help page rather than this one.
+
+This command's shebang is `#!/usr/bin/env -S usage zsh`, and the
+program it runs is `zsh` from PATH. `USAGECLI_SHELL_ZSH` names a
+different one.
 
 ## Arguments
 

From 8fc79ecd17818b645be4c0bf1d420c4b98071426 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Wed, 2 Sep 2026 14:39:23 +0000
Subject: [PATCH 4/5] docs(cli): reconcile exec help with the bare-exec fix

Rebasing brought in #1361, which answers `usage exec -h` with the command's
own page instead of an error about the missing positionals. Two things follow:

- The help said `-h` and `--help` print the script's page "rather than this
  one", which is now only true once a script is named. It says both halves.
- The test that shipped with #1361 asserts the command's first help line, and
  this branch rewrote it. It now matches on a fragment rather than the whole
  sentence, because the renderer wraps the page to the terminal width and the
  full line arrives with a newline in it.

Generated artifacts are regenerated against the rebased tree, which also picks
up the 6.6.1 version bump.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 cli/assets/usage.1               | 2 +-
 cli/src/cli/exec.rs              | 3 ++-
 cli/tests/examples.rs            | 6 +++---
 cli/usage.usage.kdl              | 2 +-
 docs/cli/reference/commands.json | 2 +-
 docs/cli/reference/exec.md       | 2 +-
 6 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index 851151193..fd8485b9a 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -232,7 +232,7 @@ Run a script through any interpreter, with its parsed arguments as environment v
 
 For scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env \-S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.
 
-`\-h` and `\-\-help` print the script's help page rather than this one.
+`\-h` and `\-\-help` belong to the script once one is named, so they print its help page rather than this one. Asked with no script to describe, they print this page.
 .PP
 \fBUsage:\fR usage exec [OPTIONS] <COMMAND> <BIN> [<ARGS>] ...
 .PP
diff --git a/cli/src/cli/exec.rs b/cli/src/cli/exec.rs
index c7ac0ce15..6baef753c 100644
--- a/cli/src/cli/exec.rs
+++ b/cli/src/cli/exec.rs
@@ -18,7 +18,8 @@ use crate::env;
 /// `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is
 /// read from it instead of from the comments.
 ///
-/// `-h` and `--help` print the script's help page rather than this one.
+/// `-h` and `--help` belong to the script once one is named, so they print its help page
+/// rather than this one. Asked with no script to describe, they print this page.
 #[derive(Debug, Args)]
 // The words after the script are the script's, so a flag `usage` does not know is a value to
 // forward rather than a mistake to report — the root's `error` stops here.
diff --git a/cli/tests/examples.rs b/cli/tests/examples.rs
index 5c36d78bf..1399fafca 100644
--- a/cli/tests/examples.rs
+++ b/cli/tests/examples.rs
@@ -245,9 +245,9 @@ fn test_exec_help_without_a_script() {
 
             cmd.assert()
                 .success()
-                .stdout(contains(
-                    "Execute a script, parsing args and exposing them as environment variables",
-                ))
+                // A fragment rather than the whole first line: the renderer wraps the page to
+                // the terminal width, so a full sentence can arrive with a newline in it.
+                .stdout(contains("Run a script through any interpreter"))
                 .stdout(contains("Usage: usage exec"))
                 .stdout(contains("<COMMAND>"))
                 .stdout(contains("<BIN>"))
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index ada5be20d..54fd4cf4d 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -134,7 +134,7 @@ Run a script through any interpreter, with its parsed arguments as environment v
 
 For scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env -S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.
 
-`-h` and `--help` print the script's help page rather than this one.
+`-h` and `--help` belong to the script once one is named, so they print its help page rather than this one. Asked with no script to describe, they print this page.
 """#
     flag -h help="Print the script's help page instead of running it"
     flag --help help="Print the script's help page instead of running it"
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index b82ac80f2..63ce080af 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -353,7 +353,7 @@
         "hide": false,
         "args_override_self": true,
         "help": "Run a script through any interpreter, with its parsed arguments as environment variables",
-        "help_long": "Run a script through any interpreter, with its parsed arguments as environment variables\n\nFor scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env -S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.\n\n`-h` and `--help` print the script's help page rather than this one.",
+        "help_long": "Run a script through any interpreter, with its parsed arguments as environment variables\n\nFor scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env -S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.\n\n`-h` and `--help` belong to the script once one is named, so they print its help page rather than this one. Asked with no script to describe, they print this page.",
         "name": "exec",
         "aliases": ["x"],
         "hidden_aliases": [],
diff --git a/docs/cli/reference/exec.md b/docs/cli/reference/exec.md
index 148188f55..d68243ad4 100644
--- a/docs/cli/reference/exec.md
+++ b/docs/cli/reference/exec.md
@@ -10,7 +10,7 @@ Run a script through any interpreter, with its parsed arguments as environment v
 
 For scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env -S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.
 
-`-h` and `--help` print the script's help page rather than this one.
+`-h` and `--help` belong to the script once one is named, so they print its help page rather than this one. Asked with no script to describe, they print this page.
 
 ## Arguments
 

From 65f0f19568dcc72ef7a6a1933d823f477d45e4a6 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Wed, 2 Sep 2026 14:40:25 +0000
Subject: [PATCH 5/5] docs(cli): quote help output the examples actually print

Two illustrative snippets did not match the binary:

- The completion candidates for `mycli cmd1 cmd2 --f` were listed as
  `--force`, `--file`. They come back sorted, so `--file` is first.
- The scripts page showed `Usage: mycli [flags] [args]` followed by an
  ellipsis. The real page names the flags and arguments, which is the point
  the section is making, so it is quoted in full.

Both were checked by running the examples as written.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/cli/completions.md |  2 +-
 docs/cli/scripts.md     | 15 +++++++++++++--
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/docs/cli/completions.md b/docs/cli/completions.md
index 34bee3fb9..8813252c7 100644
--- a/docs/cli/completions.md
+++ b/docs/cli/completions.md
@@ -92,8 +92,8 @@ offers at a given point:
 
 ```bash
 $ usage complete-word --file ./mycli.usage.kdl -- mycli cmd1 cmd2 --f
---force
 --file
+--force
 ```
 
 Because the shell-specific part is this thin, adding a shell is mostly a matter of writing the
diff --git a/docs/cli/scripts.md b/docs/cli/scripts.md
index ce934eda8..8964dea47 100644
--- a/docs/cli/scripts.md
+++ b/docs/cli/scripts.md
@@ -33,13 +33,24 @@ With the script at `./mycli`:
 
 ```bash
 $ ./mycli --help
-Usage: mycli [flags] [args]
-...
+Usage: mycli [-f --force] [-u --user <user>] [file]
+
+Arguments:
+  [file]  The file to write
+          (default: file.txt)
+
+Flags:
+  -f, --force        Overwrite existing <file>
+  -u, --user <user>  User to run as
+  -h, --help         Print help
 $ ./mycli -f --user=alice output.txt
 $ cat output.txt
 Hello, alice
 ```
 
+The synopsis, the two sections, and `-h`/`--help` itself are all built from those three
+comment lines. Nothing in the script prints them.
+
 A language without a dedicated command goes through `usage exec`, which names the interpreter to
 run. The comment prefix follows the language, so JavaScript uses `//USAGE`: