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..fd8485b9a 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,31 @@ 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
+
+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.
 
-Typically, this will be called by a script's shebang.
+`\-h` and `\-\-help` print the script's help page rather than this one.
 
-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.
+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
@@ -123,21 +138,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 +163,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 +183,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 +228,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` 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
@@ -217,21 +240,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 +268,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 +297,22 @@ 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: 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.
 
-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.
+
+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
@@ -287,19 +320,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 +345,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 +363,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 +378,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 +388,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 +403,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 +417,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 +427,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 +450,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 +474,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 +486,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 +495,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 +520,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 +539,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 +549,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 +561,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 +570,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 +588,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 +636,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 +654,31 @@ 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
+
+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.
 
-Typically, this will be called by a script's shebang.
+`\-h` and `\-\-help` print the script's help page rather than this one.
 
-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.
+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
@@ -622,15 +686,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 +711,22 @@ 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: 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.
 
-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.
+
+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
@@ -657,15 +734,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..6baef753c 100644
--- a/cli/src/cli/exec.rs
+++ b/cli/src/cli/exec.rs
@@ -10,24 +10,33 @@ 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` 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.
 #[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..4784fefad 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -18,44 +18,53 @@ 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,
 }
 
 /// 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) => {
-        #[doc = "Execute a shell script with the specified shell"]
+    ($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: 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 = "Typically, this will be called by a script's shebang."]
+        #[doc = "`-h` and `--help` print the script's help page rather than this one."]
         #[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 = $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,
@@ -71,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 646c865d7..204e40e9c 100644
--- a/cli/src/test.rs
+++ b/cli/src/test.rs
@@ -14,14 +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"));
-    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 shared = [
+        "Run a script whose usage spec is written in its own comments",
+        "",
+        "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.",
+        "",
+        // 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/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 f791b6244..54fd4cf4d 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,40 @@ 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: 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.
 
-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.
+
+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>
-    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 +75,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 +127,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` 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"
+    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 +150,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 +188,45 @@ 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: 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.
 
-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.
+
+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>
-    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 +235,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 +296,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 +329,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 +354,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 +374,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 +389,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 +407,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 +420,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 +457,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 +466,45 @@ 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: 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.
 
-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.
+
+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>
-    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 +515,28 @@ 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
+
+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.
 
-Typically, this will be called by a script's shebang.
+`-h` and `--help` print the script's help page rather than this one.
 
-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.
+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>
-    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..8813252c7 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:
-
-```bash
-# Add this to your ~/.zshrc
-source <(usage g completion-init zsh)
-```
-
-For fish:
+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 ~/.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:
-
-- **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.
+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.
 
-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.
-
-## Per-binary completion scripts
-
-Usage can generate completion scripts for any shell, and put them where that shell looks.
-`--install` does the second part:
+::: info
+`usage` is a runtime dependency of the generated scripts. Anyone using the completions needs it
+installed.
+:::
 
-```bash
-usage g completion bash mycli -f ./mycli.usage.kdl --install
-mycli --<TAB>
-```
+## Installing the script
 
-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.
+`--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.
 
-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,36 +66,82 @@ 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
+
+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.
 
-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):
+## 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
---force
 --file
+--force
+```
+
+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)
 ```
 
-## Completions for `usage` CLI itself
+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..4a039103f 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -1,5 +1,36 @@
 # 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)                  |
+
+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
+```
+
+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 +45,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 +60,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..bd5c1d0b1 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,18 @@ docs
 └── update.md
 ```
 
+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
 
-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 +51,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..0426474d8 100644
--- a/docs/cli/reference/bash.md
+++ b/docs/cli/reference/bash.md
@@ -5,21 +5,32 @@
 - **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: 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.
 
-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.
+
+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
 
-- **`<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..63ce080af 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: 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": [],
@@ -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` 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": [],
@@ -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: 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": [],
@@ -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: 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": [],
@@ -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: 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": [],
@@ -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..d68243ad4 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` 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
 
-- **`<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..9119c32e1 100644
--- a/docs/cli/reference/fish.md
+++ b/docs/cli/reference/fish.md
@@ -5,21 +5,31 @@
 - **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: 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.
 
-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.
+
+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
 
-- **`<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..20caca2e0 100644
--- a/docs/cli/reference/powershell.md
+++ b/docs/cli/reference/powershell.md
@@ -5,21 +5,32 @@
 - **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: 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.
 
-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.
+
+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
 
-- **`<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..c07bd4bd5 100644
--- a/docs/cli/reference/zsh.md
+++ b/docs/cli/reference/zsh.md
@@ -5,21 +5,31 @@
 - **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: 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.
 
-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.
+
+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
 
-- **`<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..8964dea47 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,18 +29,30 @@ else
 fi
 ```
 
-Assuming this script was located at `./mycli`, it could be used like this:
+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
 ```
 
-For languages that use `//` for comments, like JavaScript, you can use `//USAGE` comments:
+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`:
 
 ```js
 #!/usr/bin/env -S usage exec node
@@ -62,10 +74,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 +93,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 +100,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