From eaba23774eb7449bc493d9af8b404cd9abdb8d91 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 00:01:00 +0000
Subject: [PATCH 01/13] feat(cli): parse usage's own command line with the
 parser usage ships
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`usage` is now its own first adopter. The ten command structs, the root and the
two command enums are declared with `usage-derive` instead of clap, and
`--usage-spec` prints `Cli::to_kdl()` — the same tables that parsed the command
line, rather than a transcription of a clap `Command` through `clap_usage`.

Smaller than mise and far less forgiving of a lossy spec, because this CLI's
spec is what generates its own docs, manpage and completions: anything the
derive cannot say shows up in the checked-in output.

- `clap`, `clap_usage` and the `clap-sort` dev-dependency, plus `tests/clap_sort.rs`
  — declaration order is held by the spec since #915.
- `command_effects.rs`'s two tables, 60 lines that existed because "clap has no
  way to express this". Each command declares `#[usage(effect = "…")]` where it
  is defined; the file keeps `UNCLASSIFIED` and the coverage tests, which now
  read the derived metadata. A stale entry is no longer possible for the effects
  themselves — an effect moves with the command it is written on.

- The four shell commands shared one `Shell` struct, which the derive refuses:
  a command collects into the struct that declares it. They are four structs
  flattening a shared group now, written by a macro so the paragraph of long
  help is not copied four times. Their docs improve as a side effect — all four
  used to say "Execute a shell script with the specified shell".
- `sponsors` is a bare variant (#923), so its empty struct is gone.
- `requires` has no positive form in the spec, so the two constraints that used
  it are stated as `required_if` on the other flag. `--out-dir requires --multi`
  is a positive requirement on a `bool` and has no spelling at all; jdx/usage#925
  adds `requires`, and it belongs here when it lands.

Gains `JDX_USAGE_BIN` on `--usage-bin` (the bridge dropped `env`), long help that
keeps its line breaks, an `about` for `generate manpage`, and `name "usage"`
rather than `name "usage-cli"`.

Loses `subcommand_required`, which the spec can hold and the derive knows from a
bare `T` subcommand field but does not emit, and strictness on subcommands:
`unknown_flags` is accepted on an `Args` and ignored, and the root's is not
inherited, so only the root is strict. Both are derive gaps worth their own fix
rather than a workaround here.

Workspace suite green, clippy clean, docs and assets re-rendered.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 Cargo.lock                                    |  16 +-
 cli/Cargo.toml                                |   9 +-
 cli/assets/fig.ts                             |   1 +
 cli/assets/usage.1                            |  78 ++--
 cli/src/cli/complete_word.rs                  |  16 +-
 cli/src/cli/exec.rs                           |  13 +-
 cli/src/cli/generate/completion.rs            |  18 +-
 cli/src/cli/generate/completion_init.rs       |   8 +-
 cli/src/cli/generate/fig.rs                   |  10 +-
 cli/src/cli/generate/json.rs                  |   8 +-
 cli/src/cli/generate/json_schema.rs           |  14 +-
 cli/src/cli/generate/manpage.rs               |  11 +-
 cli/src/cli/generate/markdown.rs              |  25 +-
 cli/src/cli/generate/mod.rs                   |  36 +-
 cli/src/cli/generate/sdk.rs                   |  18 +-
 cli/src/cli/lint.rs                           |  12 +-
 cli/src/cli/mcp.rs                            |   8 +-
 cli/src/cli/mod.rs                            | 115 ++++--
 cli/src/cli/shell.rs                          |  58 ++-
 cli/src/cli/sponsors.rs                       |  20 +-
 cli/src/command_effects.rs                    | 194 +++------
 cli/src/lib.rs                                |   3 +
 cli/src/usage_spec.rs                         |  19 +-
 cli/tests/clap_sort.rs                        |   7 -
 cli/tests/shell_completions_integration.rs    |   8 +-
 cli/usage.usage.kdl                           | 372 +++++++-----------
 docs/cli/reference/bash.md                    |   9 +-
 docs/cli/reference/commands.json              |  86 ++--
 docs/cli/reference/complete-word.md           |   3 +-
 docs/cli/reference/fish.md                    |   9 +-
 .../cli/reference/generate/completion-init.md |   6 +-
 docs/cli/reference/generate/completion.md     |   6 +-
 docs/cli/reference/generate/manpage.md        |   9 +-
 docs/cli/reference/lint.md                    |   4 +-
 docs/cli/reference/powershell.md              |   9 +-
 docs/cli/reference/zsh.md                     |   9 +-
 36 files changed, 647 insertions(+), 600 deletions(-)
 delete mode 100644 cli/tests/clap_sort.rs

diff --git a/Cargo.lock b/Cargo.lock
index e9f3b17f3..1172b5a4a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1,6 +1,6 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
-version = 3
+version = 4
 
 [[package]]
 name = "addr2line"
@@ -290,15 +290,6 @@ dependencies = [
  "clap_derive",
 ]
 
-[[package]]
-name = "clap-sort"
-version = "1.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c9f374a541bd277ba6f4ccd08d955024ba09fda8dfc69ca1a750799ebed97a9"
-dependencies = [
- "clap",
-]
-
 [[package]]
 name = "clap_builder"
 version = "4.6.6"
@@ -2089,9 +2080,6 @@ name = "usage-cli"
 version = "5.1.0"
 dependencies = [
  "assert_cmd",
- "clap",
- "clap-sort",
- "clap_usage",
  "ctor",
  "env_logger",
  "exec",
@@ -2111,6 +2099,8 @@ dependencies = [
  "tera",
  "thiserror",
  "tokio",
+ "usage-argv",
+ "usage-derive",
  "usage-lib",
  "xx",
 ]
diff --git a/cli/Cargo.toml b/cli/Cargo.toml
index bb414550b..ecff73933 100644
--- a/cli/Cargo.toml
+++ b/cli/Cargo.toml
@@ -26,8 +26,6 @@ name = "usage_cli"
 path = "src/lib.rs"
 
 [dependencies]
-clap = { version = "4", features = ["derive", "string", "env"] }
-clap_usage = { workspace = true }
 env_logger = "0.11"
 indexmap = "2"
 itertools = "0.15"
@@ -43,6 +41,12 @@ serde_with = "3"
 tera = "2"
 thiserror = "2"
 tokio = { version = "1", features = ["rt", "macros", "io-std"] }
+# The CLI is its own first adopter: `usage` parses its own command line with the
+# parser it ships. `spec` because `--usage-spec` emits this CLI's own KDL, and
+# `diagnostics` because a person types these commands and has to be told what
+# went wrong.
+usage-argv = { workspace = true, features = ["spec", "diagnostics"] }
+usage-derive = { workspace = true }
 usage-lib = { workspace = true, features = ["clap", "docs", "unstable_choices_env"] }
 xx = "2"
 
@@ -51,7 +55,6 @@ exec = "0.3"
 
 [dev-dependencies]
 assert_cmd = { version = "2", features = ["color-auto"] }
-clap-sort = "1"
 ctor = "1"
 insta = "1"
 predicates = "3"
diff --git a/cli/assets/fig.ts b/cli/assets/fig.ts
index c2b857f02..8f426aeb9 100644
--- a/cli/assets/fig.ts
+++ b/cli/assets/fig.ts
@@ -460,6 +460,7 @@ const completionSpec: Fig.Spec = {
         },
         {
           name: ["manpage", "man"],
+          description: "Generate a manpage from a usage spec",
           options: [
             {
               name: ["-f", "--file"],
diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index 5948c8c75..d1f080954 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -1,6 +1,6 @@
-.TH USAGE-CLI 1
+.TH USAGE 1
 .SH NAME
-usage\-cli \- CLI for working with usage\-based CLIs
+usage \- CLI for working with usage\-based CLIs
 .SH SYNOPSIS
 \fBusage\fR [OPTIONS] [<COMPLETIONS>] [COMMAND]
 .SH DESCRIPTION
@@ -17,7 +17,7 @@ Outputs completions for the specified shell for completing the `usage` CLI itsel
 .SH COMMANDS
 .TP
 \fBbash\fR
-Execute a shell script with the specified shell
+Execute a shell script using bash
 .TP
 \fBcomplete\-word\fR
 Generate shell completion candidates for a partial command line
@@ -32,7 +32,7 @@ Execute a script, parsing args and exposing them as environment variables
 .RE
 .TP
 \fBfish\fR
-Execute a shell script with the specified shell
+Execute a shell script using fish
 .TP
 \fBgenerate\fR
 Generate completions, documentation, and other artifacts from usage specs
@@ -65,6 +65,7 @@ Outputs a usage spec in json format
 Generate a JSON Schema for a CLI's config file from its usage spec
 .TP
 \fBgenerate manpage\fR
+Generate a manpage from a usage spec
 .RS
 \fIAliases: \fRman
 .RE
@@ -88,20 +89,20 @@ Serve a usage spec over the Model Context Protocol
 .RE
 .TP
 \fBpowershell\fR
-Execute a shell script with the specified shell
+Execute a shell script using PowerShell
 .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
+Execute a shell script using zsh
 .SH "USAGE BASH"
-Execute a shell script with the specified shell
+Execute a shell script using bash
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 .PP
 \fBUsage:\fR usage bash [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -118,10 +119,14 @@ Show help
 .TP
 \fB<ARGS>\fR
 Arguments to pass to 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.
+This is used internally by shell completion scripts to provide
+intelligent completions for commands, flags, and arguments.
 .PP
 \fBUsage:\fR usage complete\-word [OPTIONS] [<WORDS>] ...
 .PP
@@ -171,12 +176,12 @@ path to script to execute
 \fB<ARGS>\fR
 arguments to pass to script
 .SH "USAGE FISH"
-Execute a shell script with the specified shell
+Execute a shell script using fish
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 .PP
 \fBUsage:\fR usage fish [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -193,6 +198,9 @@ Show help
 .TP
 \fB<ARGS>\fR
 Arguments to pass to 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 COMPLETION"
 Generate shell completion scripts for bash, fish, nu, powershell, or zsh
 .PP
@@ -219,9 +227,14 @@ You may need to set this if you have a different bin named "usage"
 .RS
 \fIDefault: \fRusage
 .RE
+.RS
+\fIEnvironment: \fR\fBJDX_USAGE_BIN\fR
+.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 which generates a usage spec
+e.g.: `mycli \-\-usage` or `mycli completion usage`
+Defaults to "$bin \-\-usage"
 \fBArguments:\fR
 .PP
 .TP
@@ -233,7 +246,9 @@ The CLI which we're generating completions for
 .SH "USAGE GENERATE COMPLETION-INIT"
 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.
+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.
 .PP
 \fBUsage:\fR usage generate completion\-init [OPTIONS] <SHELL>
 .PP
@@ -247,6 +262,9 @@ You may need to set this if you have a different bin named "usage"
 .RS
 \fIDefault: \fRusage
 .RE
+.RS
+\fIEnvironment: \fR\fBJDX_USAGE_BIN\fR
+.RE
 \fBArguments:\fR
 .PP
 .TP
@@ -327,6 +345,8 @@ The schema's title, shown by editors
 \fB\-\-url\fR \fI<URL>\fR
 Where the schema is published, for its `$id`
 .SH "USAGE GENERATE MANPAGE"
+Generate a manpage from a usage spec
+.PP
 \fBUsage:\fR usage generate manpage [OPTIONS]
 .PP
 \fBOptions:\fR
@@ -341,7 +361,11 @@ Output file path, or "\-" for stdout (default)
 \fB\-s, \-\-section\fR \fI<SECTION>\fR
 Manual section number (default: 1)
 
-Common sections: \- 1: User commands \- 5: File formats \- 7: Miscellaneous \- 8: System administration commands
+Common sections:
+\- 1: User commands
+\- 5: File formats
+\- 7: Miscellaneous
+\- 8: System administration commands
 .RS
 \fIDefault: \fR1
 .RE
@@ -415,7 +439,9 @@ Treat warnings as errors
 \fB\-\-sorted\fR
 Also check that subcommands and flags are declared in sorted order
 
-Off by default: declaration order is a house convention rather than a correctness question, so a spec that keeps a different order is not wrong. Pair it with \-\-warnings\-as\-errors to hold the order in CI.
+Off by default: declaration order is a house convention rather than a
+correctness question, so a spec that keeps a different order is not wrong.
+Pair it with \-\-warnings\-as\-errors to hold the order in CI.
 \fBArguments:\fR
 .PP
 .TP
@@ -438,12 +464,12 @@ Usage spec file (not "\-": stdin is the MCP transport)
 \fB\-s, \-\-spec\fR \fI<SPEC>\fR
 Raw string spec input
 .SH "USAGE POWERSHELL"
-Execute a shell script with the specified shell
+Execute a shell script using PowerShell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 .PP
 \fBUsage:\fR usage powershell [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -460,13 +486,16 @@ Show help
 .TP
 \fB<ARGS>\fR
 Arguments to pass to 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 ZSH"
-Execute a shell script with the specified shell
+Execute a shell script using zsh
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 .PP
 \fBUsage:\fR usage zsh [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -483,3 +512,6 @@ Show help
 .TP
 \fB<ARGS>\fR
 Arguments to pass to 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/cli/src/cli/complete_word.rs b/cli/src/cli/complete_word.rs
index 7f1850d6f..5e323fa11 100644
--- a/cli/src/cli/complete_word.rs
+++ b/cli/src/cli/complete_word.rs
@@ -4,10 +4,10 @@ use std::fmt::Debug;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 
-use clap::Args;
 use itertools::Itertools;
 use miette::IntoDiagnostic;
 use std::sync::LazyLock;
+use usage_derive::Args;
 use xx::regex;
 
 use usage::parse::{ParseOutput, ParseValue};
@@ -23,24 +23,28 @@ use crate::cli::generate;
 /// This is used internally by shell completion scripts to provide
 /// intelligent completions for commands, flags, and arguments.
 #[derive(Debug, Args)]
-#[clap(visible_alias = "cw")]
+#[usage(effect = "read")]
 pub struct CompleteWord {
     /// User's input from the command line
     words: Vec<String>,
 
     /// Usage spec file or script with usage shebang, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: Option<PathBuf>,
 
     /// Raw string spec input
-    #[clap(short, long, required_unless_present = "file", overrides_with = "file")]
+    #[usage(short = 's', long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 
     /// Current word index
-    #[clap(long, allow_hyphen_values = true)]
+    #[usage(long)]
     cword: Option<usize>,
 
-    #[clap(long, default_value = "bash", value_parser = ["bash", "fish", "nu", "powershell", "zsh"])]
+    #[usage(
+        long,
+        default = "bash",
+        choices("bash", "fish", "nu", "powershell", "zsh")
+    )]
     shell: String,
 }
 
diff --git a/cli/src/cli/exec.rs b/cli/src/cli/exec.rs
index c56c621f5..0dfbcd8c1 100644
--- a/cli/src/cli/exec.rs
+++ b/cli/src/cli/exec.rs
@@ -2,35 +2,30 @@ use std::fmt::Debug;
 use std::path::PathBuf;
 use std::process::Stdio;
 
-use clap::Args;
 use itertools::Itertools;
 use miette::IntoDiagnostic;
+use usage_derive::Args;
 
 use usage::Spec;
 
 use crate::env;
 
+/// Execute a script, parsing args and exposing them as environment variables
 #[derive(Debug, Args)]
-#[clap(
-    disable_help_flag = true,
-    visible_alias = "x",
-    about = "Execute a script, parsing args and exposing them as environment variables"
-)]
 pub struct Exec {
     /// command to execute after parsing usage spec
     command: String,
     /// path to script to execute
     bin: PathBuf,
     /// arguments to pass to script
-    #[clap(allow_hyphen_values = true)]
     args: Vec<String>,
 
     /// Show help
-    #[clap(short)]
+    #[usage(short = 'h')]
     h: bool,
 
     /// Show help
-    #[clap(long)]
+    #[usage(long)]
     help: bool,
 }
 
diff --git a/cli/src/cli/generate/completion.rs b/cli/src/cli/generate/completion.rs
index b39deb3a8..c1601973d 100644
--- a/cli/src/cli/generate/completion.rs
+++ b/cli/src/cli/generate/completion.rs
@@ -1,45 +1,47 @@
-use clap::Args;
 use std::path::PathBuf;
 use usage::complete::CompleteOptions;
 use usage::Spec;
+use usage_derive::Args;
 
 use super::parse_file_or_stdin;
 
 /// Generate shell completion scripts for bash, fish, nu, powershell, or zsh
 #[derive(Args)]
-#[clap(visible_alias = "c", aliases = ["complete", "completions"])]
+#[usage(effect = "read")]
 pub struct Completion {
     /// Shell to generate completions for
-    #[clap(value_parser = ["bash", "fish", "nu", "powershell", "zsh"])]
+    #[usage(choices("bash", "fish", "nu", "powershell", "zsh"))]
     shell: String,
 
     /// The CLI which we're generating completions for
     bin: String,
 
     /// A .usage.kdl spec file to use for generating completions, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: Option<PathBuf>,
 
+    // clap said `requires = "usage_cmd"`; the spec has no positive form yet, so the same
+    // rule is stated from the other end, on the flag that has to be there.
     /// A cache key to use for storing the results of calling the CLI with --usage-cmd
-    #[clap(long, requires = "usage_cmd")]
+    #[usage(long)]
     cache_key: Option<String>,
 
     /// Include https://github.com/scop/bash-completion
     ///
     /// This is required for usage completions to work in bash, but the user may already provide it
-    #[clap(long, verbatim_doc_comment)]
+    #[usage(long)]
     include_bash_completion_lib: bool,
 
     /// Override the bin used for calling back to usage-cli
     ///
     /// You may need to set this if you have a different bin named "usage"
-    #[clap(long, default_value = "usage", env = "JDX_USAGE_BIN")]
+    #[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"
-    #[clap(long, required_unless_present = "file")]
+    #[usage(long, required_unless = "--file", required_if = "--cache-key")]
     usage_cmd: Option<String>,
 }
 
diff --git a/cli/src/cli/generate/completion_init.rs b/cli/src/cli/generate/completion_init.rs
index 908fe2f52..08d8e1bd5 100644
--- a/cli/src/cli/generate/completion_init.rs
+++ b/cli/src/cli/generate/completion_init.rs
@@ -1,5 +1,5 @@
-use clap::Args;
 use usage::complete::complete_init;
+use usage_derive::Args;
 
 /// Generate a shell init script that auto-completes any usage shebang script on $PATH
 ///
@@ -7,16 +7,16 @@ use usage::complete::complete_init;
 /// tab-completion for any executable whose first line is a `usage` shebang —
 /// no per-script `usage g completion` step required.
 #[derive(Args)]
-#[clap(visible_alias = "ci", aliases = ["init", "completions-init"])]
+#[usage(effect = "read")]
 pub struct CompletionInit {
     /// Shell to generate the init script for
-    #[clap(value_parser = ["bash", "fish", "zsh"])]
+    #[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"
-    #[clap(long, default_value = "usage", env = "JDX_USAGE_BIN")]
+    #[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 0f80bfe8c..16d9e909a 100644
--- a/cli/src/cli/generate/fig.rs
+++ b/cli/src/cli/generate/fig.rs
@@ -1,10 +1,10 @@
 use std::path::PathBuf;
 use std::vec;
 
-use clap::Args;
 use indexmap::IndexMap;
 use itertools::Itertools;
 use usage::{SpecArg, SpecCommand, SpecComplete, SpecFlag};
+use usage_derive::Args;
 
 use crate::cli::generate;
 use serde::{Deserialize, Serialize, Serializer};
@@ -46,18 +46,18 @@ mod description_format {
 
 /// Generate Fig completion spec for Amazon Q / Fig
 #[derive(Args)]
-#[clap()]
+#[usage(effect = "read")]
 pub struct Fig {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: Option<PathBuf>,
 
     /// File path where the generated Fig spec will be saved, or "-" for stdout
-    #[clap(long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(long, effect = "write")]
     out_file: Option<PathBuf>,
 
     /// Raw string spec input
-    #[clap(long, required_unless_present = "file", overrides_with = "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 b4cbbbbd1..19dab57b2 100644
--- a/cli/src/cli/generate/json.rs
+++ b/cli/src/cli/generate/json.rs
@@ -4,15 +4,15 @@ use miette::IntoDiagnostic;
 use std::path::PathBuf;
 
 /// Outputs a usage spec in json format
-#[derive(clap::Args)]
-#[clap()]
+#[derive(usage_derive::Args)]
+#[usage(effect = "read")]
 pub struct Json {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: Option<PathBuf>,
 
     /// raw string spec input
-    #[clap(long, required_unless_present = "file", overrides_with = "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 e6811f166..bc2a0fdb1 100644
--- a/cli/src/cli/generate/json_schema.rs
+++ b/cli/src/cli/generate/json_schema.rs
@@ -7,27 +7,27 @@ use crate::schema::{config_schema, SchemaOptions};
 use crate::Result;
 
 /// Generate a JSON Schema for a CLI's config file from its usage spec
-#[derive(clap::Args)]
-#[clap()]
+#[derive(usage_derive::Args)]
+#[usage(effect = "read")]
 pub struct JsonSchema {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: Option<PathBuf>,
 
     /// Write the schema here instead of to stdout
-    #[clap(long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(long, effect = "write")]
     out_file: Option<PathBuf>,
 
     /// raw string spec input
-    #[clap(long, required_unless_present = "file", overrides_with = "file")]
+    #[usage(long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 
     /// The schema's title, shown by editors
-    #[clap(long)]
+    #[usage(long)]
     title: Option<String>,
 
     /// Where the schema is published, for its `$id`
-    #[clap(long)]
+    #[usage(long)]
     url: Option<String>,
 }
 
diff --git a/cli/src/cli/generate/manpage.rs b/cli/src/cli/generate/manpage.rs
index 218c5db5f..3ec97cd48 100644
--- a/cli/src/cli/generate/manpage.rs
+++ b/cli/src/cli/generate/manpage.rs
@@ -1,18 +1,19 @@
 use std::path::PathBuf;
 
 use super::{parse_file_or_stdin, write_or_stdout};
-use clap::Args;
 use usage::docs::manpage::ManpageRenderer;
+use usage_derive::Args;
 
+/// Generate a manpage from a usage spec
 #[derive(Args)]
-#[clap(visible_alias = "man")]
+#[usage(effect = "read")]
 pub struct Manpage {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: PathBuf,
 
     /// Output file path, or "-" for stdout (default)
-    #[clap(short, long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(short = 'o', long, effect = "write")]
     out_file: Option<PathBuf>,
 
     /// Manual section number (default: 1)
@@ -22,7 +23,7 @@ pub struct Manpage {
     /// - 5: File formats
     /// - 7: Miscellaneous
     /// - 8: System administration commands
-    #[clap(short, long, default_value = "1")]
+    #[usage(short = 's', long, default = "1")]
     section: u8,
 }
 
diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs
index 72da13562..c24a98f21 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -1,41 +1,46 @@
 use std::path::PathBuf;
 
 use super::{parse_file_or_stdin, write_or_stdout};
-use clap::Args;
 use usage::docs::markdown::MarkdownRenderer;
+use usage_derive::Args;
 
 /// Generate markdown documentation from usage specs
 #[derive(Args)]
-#[clap(visible_alias = "md")]
+#[usage(effect = "read")]
 pub struct Markdown {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: PathBuf,
     // /// Pass a usage spec in an argument instead of a file
-    // #[clap(short, long, required_unless_present = "file", overrides_with = "file")]
+    // #[usage(short = 's', long, required_unless = "--file", overrides = "--file")]
     // spec: Option<String>,
     /// Render each subcommand as a separate markdown file
-    #[clap(short, long, requires = "out_dir", conflicts_with = "out_file")]
+    #[usage(short = 'm', long, conflicts = "--out-file")]
     multi: bool,
 
     /// Escape HTML in markdown
-    #[clap(long)]
+    #[usage(long)]
     html_encode: bool,
 
+    // clap said this both ways: `--multi requires --out-dir` and `--out-dir requires
+    // --multi`. `required_if` says the first, which is the direction that matters — a
+    // multi-file render with nowhere to write. The second is a positive requirement on a
+    // `bool`, which nothing in the spec can state; jdx/usage#925 adds `requires`, and it
+    // belongs here when it lands.
     /// Output markdown files to this directory (required when using --multi)
-    #[clap(long, value_hint = clap::ValueHint::DirPath, requires = "multi")]
+    #[usage(long, required_if = "--multi", effect = "write")]
     out_dir: Option<PathBuf>,
 
     /// Output file path for single-file markdown generation, or "-" for stdout (default)
-    #[clap(long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(long, effect = "write")]
     out_file: Option<PathBuf>,
 
     /// Replace `<pre>` tags with markdown code fences
-    #[clap(long)]
+    #[usage(long)]
     replace_pre_with_code_fences: bool,
 
     /// Prefix to add to all URLs
-    #[clap(long)]
+    #[usage(long)]
     url_prefix: Option<String>,
 }
 
diff --git a/cli/src/cli/generate/mod.rs b/cli/src/cli/generate/mod.rs
index 7f6c23072..b416e0f39 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -7,7 +7,6 @@ use usage::Spec;
 mod completion;
 mod completion_init;
 mod fig;
-mod go;
 mod json;
 mod json_schema;
 mod manpage;
@@ -15,24 +14,32 @@ mod markdown;
 mod sdk;
 
 /// Generate completions, documentation, and other artifacts from usage specs
-#[derive(clap::Args)]
-#[clap(visible_alias = "g")]
+// Cannot run alone, and every child starts at `read`, so the parent is `read` too.
+#[derive(usage_derive::Args)]
+#[usage(effect = "read")]
 pub struct Generate {
-    #[clap(subcommand)]
+    #[usage(subcommand)]
     pub command: Command,
 }
 
-#[derive(clap::Subcommand)]
+/// The generators.
+///
+/// Each command's help is its struct's doc comment rather than a second one here, which the
+/// derive would let win: one description, in the file that owns the command.
+#[derive(usage_derive::Subcommands)]
 pub enum Command {
-    Completion(completion::Completion),
-    CompletionInit(completion_init::CompletionInit),
-    Fig(fig::Fig),
-    Go(go::Go),
-    Json(json::Json),
-    JsonSchema(json_schema::JsonSchema),
-    Manpage(manpage::Manpage),
-    Markdown(markdown::Markdown),
-    Sdk(sdk::Sdk),
+    #[usage(alias = "c", alias_hidden("complete", "completions"))]
+    Completion(Box<completion::Completion>),
+    #[usage(alias = "ci", alias_hidden("init", "completions-init"))]
+    CompletionInit(Box<completion_init::CompletionInit>),
+    Fig(Box<fig::Fig>),
+    Json(Box<json::Json>),
+    JsonSchema(Box<json_schema::JsonSchema>),
+    #[usage(alias = "man")]
+    Manpage(Box<manpage::Manpage>),
+    #[usage(alias = "md")]
+    Markdown(Box<markdown::Markdown>),
+    Sdk(Box<sdk::Sdk>),
 }
 
 impl Generate {
@@ -41,7 +48,6 @@ impl Generate {
             Command::Completion(cmd) => cmd.run(),
             Command::CompletionInit(cmd) => cmd.run(),
             Command::Fig(cmd) => cmd.run(),
-            Command::Go(cmd) => cmd.run(),
             Command::Json(cmd) => cmd.run(),
             Command::JsonSchema(cmd) => cmd.run(),
             Command::Manpage(cmd) => cmd.run(),
diff --git a/cli/src/cli/generate/sdk.rs b/cli/src/cli/generate/sdk.rs
index cbbcee32c..00d2d962f 100644
--- a/cli/src/cli/generate/sdk.rs
+++ b/cli/src/cli/generate/sdk.rs
@@ -1,32 +1,36 @@
 use std::path::PathBuf;
 
-use clap::Args;
+use usage_derive::Args;
 
 use crate::cli::generate;
 
 use usage::sdk::{SdkLanguage, SdkOptions};
 
+/// Generate a type-safe SDK from a usage spec
+// 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)]
-#[clap(about = "Generate a type-safe SDK from a usage spec")]
+#[usage(effect = "write")]
 pub struct Sdk {
     /// A usage spec taken in as a file
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: Option<PathBuf>,
 
     /// Target language for the SDK
-    #[clap(short, long, value_parser = ["typescript", "python"])]
+    #[usage(short = 'l', long, choices("typescript", "python"))]
     language: String,
 
     /// Output directory for generated SDK files
-    #[clap(short, long)]
+    #[usage(short = 'o', long)]
     output: PathBuf,
 
     /// Override the package/module name (defaults to spec bin name)
-    #[clap(short, long)]
+    #[usage(short = 'p', long)]
     package_name: Option<String>,
 
     /// Raw string spec input
-    #[clap(long, required_unless_present = "file", overrides_with = "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 328878d86..f83415157 100644
--- a/cli/src/cli/lint.rs
+++ b/cli/src/cli/lint.rs
@@ -5,18 +5,18 @@ use usage::{Spec, SpecArg, SpecCommand, SpecFlag};
 use crate::cli::generate::parse_file_or_stdin;
 
 /// Lint a usage spec file for common issues
-#[derive(clap::Args)]
+#[derive(usage_derive::Args)]
+#[usage(effect = "read")]
 pub struct Lint {
     /// A usage spec file to lint, use "-" to read from stdin
-    #[clap(required = true)]
     file: PathBuf,
 
     /// Output format
-    #[clap(long, short, default_value = "text")]
+    #[usage(long, short = 'f', default = "text", value_enum)]
     format: OutputFormat,
 
     /// Treat warnings as errors
-    #[clap(long, short = 'W')]
+    #[usage(long, short = 'W')]
     warnings_as_errors: bool,
 
     /// Also check that subcommands and flags are declared in sorted order
@@ -24,7 +24,7 @@ pub struct Lint {
     /// Off by default: declaration order is a house convention rather than a
     /// correctness question, so a spec that keeps a different order is not wrong.
     /// Pair it with --warnings-as-errors to hold the order in CI.
-    #[clap(long)]
+    #[usage(long)]
     sorted: bool,
 }
 
@@ -35,7 +35,7 @@ pub struct LintOptions {
     pub sorted: bool,
 }
 
-#[derive(Clone, Copy, Default, clap::ValueEnum)]
+#[derive(Clone, Copy, Default, usage_derive::ValueEnum)]
 enum OutputFormat {
     #[default]
     Text,
diff --git a/cli/src/cli/mcp.rs b/cli/src/cli/mcp.rs
index 16568b114..6387d1881 100644
--- a/cli/src/cli/mcp.rs
+++ b/cli/src/cli/mcp.rs
@@ -42,17 +42,17 @@ 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`.
-#[derive(Debug, clap::Args)]
-#[clap(visible_alias = "mcp-server", verbatim_doc_comment)]
+#[derive(Debug, usage_derive::Args)]
+#[usage(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)
-    #[clap(short, long)]
+    #[usage(short = 'f', long)]
     file: Option<PathBuf>,
 
     /// Raw string spec input
-    #[clap(short, long, required_unless_present = "file", overrides_with = "file")]
+    #[usage(short = 's', long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 }
 
diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index 13fde5183..c146a3ced 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -1,6 +1,7 @@
-use crate::usage_spec;
-use clap::{Parser, Subcommand};
+use std::ffi::OsStr;
+
 use miette::Result;
+use usage_derive::{Cli as DeriveCli, Subcommands};
 
 pub mod complete_word;
 mod exec;
@@ -10,55 +11,113 @@ mod mcp;
 mod shell;
 mod sponsors;
 
-#[derive(Parser)]
-#[clap(author, version, about)]
+/// CLI for working with usage-based CLIs
+// `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
+// the help page a user reads.
+//
+// 3.6 added `effect=` and 4.0 added it on flags and args; older `usage` CLIs reject the spec
+// outright with "unsupported cmd prop effect", so this moves in lockstep with the fields the
+// spec actually carries.
+#[derive(DeriveCli)]
+#[usage(
+    bin = "usage",
+    version,
+    min_usage_version = "4.0",
+    // Every flag the root accepts is one it declares, so an unrecognised one is a mistake and
+    // saying so beats binding it to `[COMPLETIONS]`.
+    //
+    // Only the root, which is as far as the derive carries this today: the attribute is
+    // accepted on an `Args` and then ignored, and a subcommand does not inherit the root's.
+    // So `usage lint --nope f.kdl` still makes `--nope` the file and calls the real file
+    // unexpected, where clap named the flag. The five commands that hand a command line to
+    // somebody else's script want the lenient reading and get it by default, which is why
+    // this is worth fixing in the derive rather than working around here.
+    unknown_flags = "error"
+)]
 pub struct Cli {
-    #[clap(subcommand)]
+    #[usage(subcommand)]
     command: Command,
 
     /// Outputs completions for the specified shell for completing the `usage` CLI itself
+    // Declaration only, as it was under clap: `--completions <shell>` is 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 command line understood to answer. It is declared so
+    // that help, the spec and the completions know it exists.
+    #[allow(dead_code)]
     completions: Option<String>,
 
     /// Outputs a `usage.kdl` spec for this CLI itself
-    #[clap(long)]
+    #[usage(long)]
     usage_spec: bool,
 }
 
-#[derive(Subcommand)]
+/// What `usage` can be asked to do.
+///
+/// Each command's description is its struct's doc comment, in the file that owns it, except
+/// where a variant holds nothing and there is no struct to carry one.
+#[derive(Subcommands)]
 enum Command {
-    #[clap(about = "Execute a shell script using bash")]
-    Bash(shell::Shell),
-    CompleteWord(complete_word::CompleteWord),
-    Exec(exec::Exec),
-    #[clap(about = "Execute a shell script using fish")]
-    Fish(shell::Shell),
-    Generate(generate::Generate),
-    Lint(lint::Lint),
-    Mcp(mcp::Mcp),
-    #[clap(name = "powershell", about = "Execute a shell script using PowerShell")]
-    PowerShell(shell::Shell),
-    Sponsors(sponsors::Sponsors),
-    #[clap(about = "Execute a shell script using zsh")]
-    Zsh(shell::Shell),
+    Bash(Box<shell::Bash>),
+    #[usage(alias = "cw")]
+    CompleteWord(Box<complete_word::CompleteWord>),
+    #[usage(alias = "x")]
+    Exec(Box<exec::Exec>),
+    Fish(Box<shell::Fish>),
+    #[usage(alias = "g")]
+    Generate(Box<generate::Generate>),
+    Lint(Box<lint::Lint>),
+    #[usage(alias = "mcp-server")]
+    Mcp(Box<mcp::Mcp>),
+    #[usage(name = "powershell")]
+    PowerShell(Box<shell::PowerShell>),
+    /// Show the companies sponsoring usage and the jdx.dev open source tools
+    #[usage(effect = "read")]
+    Sponsors,
+    Zsh(Box<shell::Zsh>),
 }
 
 impl Cli {
     pub fn run(argv: &[String]) -> Result<()> {
-        let cli = Self::parse_from(argv);
+        // `parse_from` takes the command line without the program name, and hands back what
+        // went wrong instead of ending the process — which is what lets the error come out
+        // through the same path as every other failure here.
+        let words: Vec<&OsStr> = argv.iter().skip(1).map(OsStr::new).collect();
+        let cli = match Self::parse_from(&words) {
+            Ok(cli) => cli,
+            // Not failures: someone asked a question, and the answer goes to stdout.
+            Err(usage_argv::Error::Help { cmd, long }) => {
+                if let Some(page) = usage_argv::help::render(Self::spec(), cmd, long) {
+                    print!("{page}");
+                }
+                return Ok(());
+            }
+            Err(usage_argv::Error::Version) => {
+                println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
+                return Ok(());
+            }
+            Err(err) => {
+                eprint!("{}", usage_argv::render_failure(Self::spec(), &words, &err));
+                // clap's status for a command line it could not parse, which is what the
+                // scripts that call this have been checking for.
+                std::process::exit(2);
+            }
+        };
         if cli.usage_spec {
-            return usage_spec::generate();
+            return crate::usage_spec::generate();
         }
         match cli.command {
-            Command::Bash(mut cmd) => cmd.run("bash"),
-            Command::Fish(mut cmd) => cmd.run("fish"),
-            Command::PowerShell(mut cmd) => cmd.run("pwsh"),
-            Command::Zsh(mut cmd) => cmd.run("zsh"),
+            Command::Bash(mut cmd) => cmd.run(),
+            Command::Fish(mut cmd) => cmd.run(),
+            Command::PowerShell(mut cmd) => cmd.run(),
+            Command::Zsh(mut cmd) => cmd.run(),
             Command::Generate(cmd) => cmd.run(),
             Command::Exec(mut cmd) => cmd.run(),
             Command::CompleteWord(cmd) => cmd.run(),
             Command::Lint(cmd) => cmd.run(),
             Command::Mcp(cmd) => cmd.run(),
-            Command::Sponsors(cmd) => cmd.run(),
+            Command::Sponsors => sponsors::run(),
         }
     }
 }
diff --git a/cli/src/cli/shell.rs b/cli/src/cli/shell.rs
index f5880ee17..b4b44fd45 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -2,37 +2,75 @@ use std::fmt::Debug;
 use std::path::PathBuf;
 use std::process::Stdio;
 
-use clap::Args;
 use itertools::Itertools;
 use miette::IntoDiagnostic;
+use usage_derive::Args;
 
 use usage::Spec;
 
 use crate::env;
 
-/// Execute a shell script with the specified shell
+/// What the four shell commands accept, declared once.
 ///
-/// Typically, this will be called by a script's shebang.
-///
-/// 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.
+/// Not a command itself: each of `bash`, `fish`, `powershell` and `zsh` flattens it, so the
+/// emitted spec lists these on all four exactly as a hand-written spec would. They cannot
+/// share one struct instead — a command collects into the struct that declares it, so the
+/// derive refuses two variants wrapping one — and the shell to run is the command that ran.
 #[derive(Debug, Args)]
-#[clap(disable_help_flag = true, verbatim_doc_comment)]
 pub struct Shell {
     script: PathBuf,
+
     /// Arguments to pass to script
-    #[clap(allow_hyphen_values = true)]
+    ///
+    /// 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
-    #[clap(short)]
+    #[usage(short = 'h')]
     h: bool,
 
     /// Show help
-    #[clap(long)]
+    #[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.
+macro_rules! shell_command {
+    ($ty:ident, $program:literal, $about:literal) => {
+        #[doc = $about]
+        #[doc = ""]
+        #[doc = "Typically, this will be called by a script's shebang."]
+        #[doc = ""]
+        #[doc = "If using `var=#true` on args/flags, they will be joined with spaces using"]
+        #[doc = "`shell_words::join()` to properly escape and quote values with spaces in them."]
+        #[derive(Debug, Args)]
+        pub struct $ty {
+            #[usage(flatten)]
+            pub shell: Shell,
+        }
+
+        impl $ty {
+            pub fn run(&mut self) -> miette::Result<()> {
+                self.shell.run($program)
+            }
+        }
+    };
+}
+
+shell_command!(Bash, "bash", "Execute a shell script using bash");
+shell_command!(Fish, "fish", "Execute a shell script using fish");
+shell_command!(
+    PowerShell,
+    "pwsh",
+    "Execute a shell script using PowerShell"
+);
+shell_command!(Zsh, "zsh", "Execute a shell script using zsh");
+
 impl Shell {
     pub fn run(&mut self, shell: &str) -> miette::Result<()> {
         let spec = Spec::parse_file(&self.script)?;
diff --git a/cli/src/cli/sponsors.rs b/cli/src/cli/sponsors.rs
index c34c5b9a0..11a712a64 100644
--- a/cli/src/cli/sponsors.rs
+++ b/cli/src/cli/sponsors.rs
@@ -1,12 +1,12 @@
-/// Show the companies sponsoring usage and the jdx.dev open source tools
-#[derive(clap::Args)]
-pub struct Sponsors;
+//! Show the companies sponsoring usage and the jdx.dev open source tools.
+//!
+//! A command that takes nothing, so it is a bare variant of the command enum rather than a
+//! struct with no fields: the derive writes the struct such a variant implies, and the help
+//! text and `effect` are declared on the variant.
 
-impl Sponsors {
-    pub fn run(&self) -> miette::Result<()> {
-        println!(
-            "usage and the jdx.dev open source tools are sponsored by:\n\n  entire.io - https://entire.io\n  37signals - https://37signals.com\n\nView all sponsors: https://jdx.dev/sponsors.html"
-        );
-        Ok(())
-    }
+pub fn run() -> miette::Result<()> {
+    println!(
+        "usage and the jdx.dev open source tools are sponsored by:\n\n  entire.io - https://entire.io\n  37signals - https://37signals.com\n\nView all sponsors: https://jdx.dev/sponsors.html"
+    );
+    Ok(())
 }
diff --git a/cli/src/command_effects.rs b/cli/src/command_effects.rs
index 1184eb3f8..2342d36ff 100644
--- a/cli/src/command_effects.rs
+++ b/cli/src/command_effects.rs
@@ -1,60 +1,21 @@
 //! What each `usage` command does to the world.
 //!
-//! clap has no way to express this, so it is applied to the derived spec on the
-//! way out. The same shape mise, hk, pitchfork, aube and communique use.
+//! Declared where the command is, as `#[usage(effect = "…")]`. It used to be a table applied
+//! to the spec on the way out, because clap had no way to express it; the derive does, so the
+//! table is gone and what is left here is the coverage that kept it honest.
 //!
-//! The rule is what the command does to *state the user would miss*, not how
-//! much work it does. Reading a spec file and printing a manpage is `read` no
-//! matter how much parsing happens in between; writing that manpage to a path
-//! the user named is `write`, because something on disk changed.
+//! The rule is what the command does to *state the user would miss*, not how much work it
+//! does. Reading a spec file and printing a manpage is `read` no matter how much parsing
+//! happens in between; writing that manpage to a path the user named is `write`, because
+//! something on disk changed.
 //!
-//! Most commands here print to stdout and take an optional flag to write to a
-//! file instead, so they are `read` with the flag raising them — which is the
-//! composition rule doing its job: the effect of an invocation is the highest
-//! of the command's and those of the flags and args actually supplied.
+//! Most commands print to stdout and take an optional flag to write to a file instead, so
+//! they are `read` with the flag raising them — which is the composition rule doing its job:
+//! the effect of an invocation is the highest of the command's and those of the flags and
+//! args actually supplied.
 //!
-//! A command that runs code the user supplied is left unset rather than
-//! guessed at. See [`UNCLASSIFIED`].
-
-use usage::SpecCommandEffect::{self, Read, Write};
-
-/// Commands whose effect is fixed, keyed by their full path under `usage`.
-const EFFECTS: &[(&str, SpecCommandEffect)] = &[
-    ("complete-word", Read),
-    // Cannot run alone (`subcommand_required`), and every child starts at
-    // `read`, so the parent is `read` too.
-    ("generate", Read),
-    ("generate completion", Read),
-    ("generate completion-init", Read),
-    ("generate fig", Read),
-    ("generate go", Read),
-    ("generate json", Read),
-    ("generate json-schema", Read),
-    ("generate manpage", Read),
-    ("generate markdown", Read),
-    // The only generator whose output flag is required: it cannot print an SDK
-    // to stdout, so every invocation writes a directory.
-    ("generate sdk", Write),
-    ("lint", Read),
-    // Long-running, but every tool it serves only reads the spec it was given.
-    // Unlike `mise mcp`, which is unclassified because it serves a tool that
-    // runs tasks, nothing here can act on the CLI it describes.
-    ("mcp", Read),
-    ("sponsors", Read),
-];
-
-/// Flags that raise the effect of the command they are passed to, keyed by
-/// `<command path>` and the flag's name.
-///
-/// All of these redirect output that would otherwise go to stdout.
-const FLAG_EFFECTS: &[(&str, &str, SpecCommandEffect)] = &[
-    ("generate fig", "out-file", Write),
-    ("generate go", "out-file", Write),
-    ("generate json-schema", "out-file", Write),
-    ("generate manpage", "out-file", Write),
-    ("generate markdown", "out-dir", Write),
-    ("generate markdown", "out-file", Write),
-];
+//! A command that runs code the user supplied is left unset rather than guessed at. See
+//! [`UNCLASSIFIED`].
 
 /// Commands with no fixed effect, and why.
 ///
@@ -72,50 +33,23 @@ const UNCLASSIFIED: &[(&str, &str)] = &[
     ("zsh", "runs a user-supplied script"),
 ];
 
-/// Apply the tables above to a derived spec.
-///
-/// A path that no longer exists is skipped rather than panicking — the stale
-/// entry is caught by the test below, where a failure is readable, instead of
-/// at runtime in a user's shell.
-pub(crate) fn apply(spec: &mut usage::Spec) {
-    for (path, effect) in EFFECTS {
-        if let Some(cmd) = find_mut(spec, path) {
-            cmd.effect = Some(*effect);
-        }
-    }
-    for (path, flag_name, effect) in FLAG_EFFECTS {
-        if let Some(cmd) = find_mut(spec, path) {
-            if let Some(flag) = cmd.flags.iter_mut().find(|f| f.name == *flag_name) {
-                flag.effect = Some(*effect);
-            }
-        }
-    }
-}
-
-fn find_mut<'a>(spec: &'a mut usage::Spec, path: &str) -> Option<&'a mut usage::SpecCommand> {
-    let mut cmd = &mut spec.cmd;
-    for segment in path.split(' ') {
-        cmd = cmd.subcommands.get_mut(segment)?;
-    }
-    Some(cmd)
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
     use std::collections::HashSet;
+    use usage_argv::spec::{CommandMeta, Effect};
+
+    use crate::cli::Cli;
 
-    fn spec() -> usage::Spec {
-        let mut cli = <crate::cli::Cli as clap::CommandFactory>::command();
-        let mut spec = clap_usage::spec(&mut cli, "usage");
-        apply(&mut spec);
-        spec
+    /// The static metadata the derive compiled, which is what `--usage-spec` prints.
+    fn root() -> &'static CommandMeta<'static> {
+        Cli::spec().root
     }
 
-    /// Every command path in the spec, deepest-first order irrelevant.
-    fn walk(cmd: &usage::SpecCommand, path: &mut Vec<String>, out: &mut Vec<(String, bool)>) {
-        for (name, sub) in &cmd.subcommands {
-            path.push(name.clone());
+    /// Every command path under the root, with whether it declares an effect.
+    fn walk(cmd: &CommandMeta, path: &mut Vec<String>, out: &mut Vec<(String, bool)>) {
+        for sub in cmd.subcommands {
+            path.push(sub.cmd.name.to_string());
             out.push((path.join(" "), sub.effect.is_some()));
             walk(sub, path, out);
             path.pop();
@@ -123,40 +57,33 @@ mod tests {
     }
 
     fn commands() -> Vec<(String, bool)> {
-        let spec = spec();
         let mut out = vec![];
-        walk(&spec.cmd, &mut vec![], &mut out);
+        walk(root(), &mut vec![], &mut out);
         out
     }
 
+    fn find(path: &str) -> Option<&'static CommandMeta<'static>> {
+        let mut cmd = root();
+        for segment in path.split(' ') {
+            cmd = cmd.subcommands.iter().find(|s| s.cmd.name == segment)?;
+        }
+        Some(cmd)
+    }
+
     #[test]
-    fn no_entry_points_at_a_command_that_does_not_exist() {
-        // `apply` skips a stale path silently so a rename cannot break the CLI.
-        // This is where that shows up instead.
+    fn nothing_names_a_command_that_does_not_exist() {
+        // The effects themselves can no longer go stale — a `#[usage(effect)]` on a command
+        // that was renamed moves with it, and one on a command that was deleted is deleted
+        // too. `UNCLASSIFIED` is a list of names again, so this is where it reports itself.
         let real: HashSet<_> = commands().into_iter().map(|(path, _)| path).collect();
-        let stale: Vec<_> = EFFECTS
+        let stale: Vec<_> = UNCLASSIFIED
             .iter()
             .map(|(path, _)| *path)
-            .chain(FLAG_EFFECTS.iter().map(|(path, _, _)| *path))
-            .chain(UNCLASSIFIED.iter().map(|(path, _)| *path))
             .filter(|path| !real.contains(*path))
             .collect();
         assert!(stale.is_empty(), "no such commands: {stale:?}");
     }
 
-    #[test]
-    fn no_flag_entry_points_at_a_flag_that_does_not_exist() {
-        let spec = spec();
-        let missing: Vec<_> = FLAG_EFFECTS
-            .iter()
-            .filter(|(path, flag_name, _)| {
-                find(&spec, path).is_none_or(|cmd| !cmd.flags.iter().any(|f| f.name == *flag_name))
-            })
-            .map(|(path, flag_name, _)| format!("{path} --{flag_name}"))
-            .collect();
-        assert!(missing.is_empty(), "no such flags: {missing:?}");
-    }
-
     #[test]
     fn nothing_is_unclassified_by_accident() {
         // An unset effect means "unknown, ask", which is right for the shell
@@ -178,31 +105,40 @@ mod tests {
         // The composition rule is the reason flags carry effects at all:
         // `usage g markdown -f x.kdl` only reads, the same command with
         // `--out-file` writes.
-        let spec = spec();
-        let md = find(&spec, "generate markdown").unwrap();
-        assert_eq!(md.effect, Some(Read));
-        let out_file = md.flags.iter().find(|f| f.name == "out-file").unwrap();
-        assert_eq!(out_file.effect, Some(Write));
+        let md = find("generate markdown").unwrap();
+        assert_eq!(md.effect, Some(Effect::Read));
+        let flag = |name: &str| md.flags.iter().find(|f| f.flag.name == name).unwrap();
+        assert_eq!(flag("out-file").effect, Some(Effect::Write));
+        assert_eq!(flag("out-dir").effect, Some(Effect::Write));
         // A flag that changes only the rendering stays unset.
-        let html = md.flags.iter().find(|f| f.name == "html-encode").unwrap();
-        assert_eq!(html.effect, None);
+        assert_eq!(flag("html-encode").effect, None);
+    }
+
+    #[test]
+    fn every_generator_that_can_redirect_its_output_says_so() {
+        // The four generators that print to stdout unless told otherwise. Kept as one list
+        // because the risk is a new `--out-file` arriving without an effect, which reads to
+        // an agent as a command that only ever prints.
+        for path in ["generate fig", "generate json-schema", "generate manpage"] {
+            let cmd = find(path).unwrap_or_else(|| panic!("no such command: {path}"));
+            let out_file = cmd
+                .flags
+                .iter()
+                .find(|f| f.flag.name == "out-file")
+                .unwrap_or_else(|| panic!("{path} has no --out-file"));
+            assert_eq!(out_file.effect, Some(Effect::Write), "{path} --out-file");
+        }
     }
 
     #[test]
     fn a_required_output_flag_makes_the_command_write() {
         // `generate sdk` cannot print to stdout, so there is no read-only way
         // to invoke it and the effect belongs on the command.
-        let spec = spec();
-        let sdk = find(&spec, "generate sdk").unwrap();
-        assert_eq!(sdk.effect, Some(Write));
-        assert!(sdk.flags.iter().any(|f| f.name == "output" && f.required));
-    }
-
-    fn find<'a>(spec: &'a usage::Spec, path: &str) -> Option<&'a usage::SpecCommand> {
-        let mut cmd = &spec.cmd;
-        for segment in path.split(' ') {
-            cmd = cmd.subcommands.get(segment)?;
-        }
-        Some(cmd)
+        let sdk = find("generate sdk").unwrap();
+        assert_eq!(sdk.effect, Some(Effect::Write));
+        assert!(sdk
+            .flags
+            .iter()
+            .any(|f| f.flag.name == "output" && f.required));
     }
 }
diff --git a/cli/src/lib.rs b/cli/src/lib.rs
index 82309db76..4e76f073a 100644
--- a/cli/src/lib.rs
+++ b/cli/src/lib.rs
@@ -13,6 +13,9 @@ pub use cli::complete_word::candidates as complete_candidates;
 pub use cli::Cli;
 
 mod cli;
+// Nothing but coverage now: each command declares its own effect, so what is left is the
+// check that none of them forgot to.
+#[cfg(test)]
 mod command_effects;
 pub mod env;
 mod schema;
diff --git a/cli/src/usage_spec.rs b/cli/src/usage_spec.rs
index 3474a3d76..633fc53e6 100644
--- a/cli/src/usage_spec.rs
+++ b/cli/src/usage_spec.rs
@@ -1,21 +1,12 @@
 use crate::cli::Cli;
-use clap::CommandFactory;
 use miette::Result;
 
 pub(crate) fn generate() -> Result<()> {
-    let mut cli = Cli::command().version(env!("CARGO_PKG_VERSION"));
-    let mut spec = clap_usage::spec(&mut cli, "usage");
-
-    // Declare what each command does to the world. clap cannot express this,
-    // so it is applied to the derived spec; see command_effects.
-    crate::command_effects::apply(&mut spec);
-
-    println!("// @generated by usage-cli from clap metadata");
-    // 3.6 added `effect=` and 4.0 added it on flags and args; older `usage`
-    // CLIs reject the spec outright with "unsupported cmd prop effect", so this
-    // moves in lockstep with the fields the spec actually carries.
-    println!(r#"min_usage_version "4.0""#);
-    println!("{spec}");
+    // The declaration *is* the spec: the same tables that parsed the command line print it,
+    // with no bridge and no second model in between. `effect` in particular is now declared
+    // on each command rather than patched in here afterwards, since clap could not say it.
+    println!("// @generated by usage-cli from its own parse tables");
+    println!("{}", Cli::to_kdl().trim());
     println!("{}", include_str!("../assets/usage-extra.usage.kdl").trim());
 
     Ok(())
diff --git a/cli/tests/clap_sort.rs b/cli/tests/clap_sort.rs
deleted file mode 100644
index 5bb909652..000000000
--- a/cli/tests/clap_sort.rs
+++ /dev/null
@@ -1,7 +0,0 @@
-use clap::CommandFactory;
-use usage_cli::Cli;
-
-#[test]
-fn verify_cli_sorted() {
-    clap_sort::assert_sorted(&Cli::command());
-}
diff --git a/cli/tests/shell_completions_integration.rs b/cli/tests/shell_completions_integration.rs
index cfa422510..5c9d2a602 100644
--- a/cli/tests/shell_completions_integration.rs
+++ b/cli/tests/shell_completions_integration.rs
@@ -1609,7 +1609,9 @@ cat "$XDG_CACHE_HOME/usage/usage__usage_spec_usage.spec"
         "spec file was written by the shell function instead of the CLI.\nstdout:\n{stdout}\nstderr:\n{stderr}"
     );
     assert!(
-        stdout.contains("bin usage"),
+        // Quoted, which is how the parse tables write a spec: `usage --usage-spec` is
+        // emitted by the CLI's own derive rather than by the clap bridge.
+        stdout.contains(r#"bin "usage""#),
         "spec file should hold the real usage spec.\nstdout:\n{stdout}\nstderr:\n{stderr}"
     );
 
@@ -1763,7 +1765,9 @@ cat "$XDG_CACHE_HOME/usage/usage__usage_spec_usage.spec"
         "spec file was written by the shell function instead of the CLI.\nstdout:\n{stdout}\nstderr:\n{stderr}"
     );
     assert!(
-        stdout.contains("bin usage"),
+        // Quoted, which is how the parse tables write a spec: `usage --usage-spec` is
+        // emitted by the CLI's own derive rather than by the clap bridge.
+        stdout.contains(r#"bin "usage""#),
         "spec file should hold the real usage spec.\nstdout:\n{stdout}\nstderr:\n{stderr}"
     );
 
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index de554ef04..fd18e30b5 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -1,299 +1,227 @@
-// @generated by usage-cli from clap metadata
+// @generated by usage-cli from its own parse tables
 min_usage_version "4.0"
-name usage-cli
-bin usage
+name "usage"
+bin "usage"
 version "5.1.0"
 about "CLI for working with usage-based CLIs"
-unknown_flags error
-usage "Usage: usage-cli [OPTIONS] [COMPLETIONS] <COMMAND>"
-flag --usage-spec help="Outputs a `usage.kdl` spec for this CLI itself"
-arg "[COMPLETIONS]" help="Outputs completions for the specified shell for completing the `usage` CLI itself" required=#false
-cmd bash help="Execute a shell script using bash" unknown_flags=value {
-    long_help #"""
-Execute a shell script with the specified shell
-
-Typically, this will be called by a script's shebang.
-
-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.
-"""#
-    flag -h help="Show help"
-    flag --help help="Show help"
-    arg <SCRIPT>
-    arg "[ARGS]…" help="Arguments to pass to script" required=#false var=#true
+unknown_flags "error"
+flag "--usage-spec" help="Outputs a `usage.kdl` spec for this CLI itself"
+arg "[COMPLETIONS]" help="Outputs completions for the specified shell for completing the `usage` CLI itself"
+cmd "bash" help="Execute a shell script using bash" unknown_flags="value" {
+    long_help "Execute a shell script using bash\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
+    flag "-h" help="Show help"
+    flag "--help" help="Show help"
+    arg "<SCRIPT>"
+    arg "[ARGS]..." help="Arguments to pass to script" {
+        long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
+    }
 }
-cmd complete-word help="Generate shell completion candidates for a partial command line" effect=read unknown_flags=value {
-    alias cw
-    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.
-"""#
+cmd "complete-word" help="Generate shell completion candidates for a partial command line" effect="read" unknown_flags="value" {
+    alias "cw"
+    long_help "Generate shell completion candidates for a partial command line\n\nThis is used internally by shell completion scripts to provide\nintelligent completions for commands, flags, and arguments."
     flag "-f --file" help="Usage spec file or script with usage shebang, use \"-\" to read from stdin" {
-        arg <FILE>
+        arg "<FILE>"
     }
-    flag "-s --spec" help="Raw string spec input" {
-        arg <SPEC>
+    flag "-s --spec" help="Raw string spec input" overrides="--file" required_unless="--file" {
+        arg "<SPEC>"
     }
-    flag --cword help="Current word index" allow_hyphen_values=#true {
-        arg <CWORD>
+    flag "--cword" help="Current word index" {
+        arg "<CWORD>"
     }
-    flag --shell default=bash {
-        arg <SHELL> {
-            choices bash fish nu powershell zsh
+    flag "--shell" required=#true default="bash" {
+        arg "<SHELL>" {
+            choices "bash" "fish" "nu" "powershell" "zsh"
         }
     }
-    arg "[WORDS]…" help="User's input from the command line" required=#false var=#true
+    arg "[WORDS]..." help="User's input from the command line"
 }
-cmd exec help="Execute a script, parsing args and exposing them 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" required=#false var=#true
+cmd "exec" help="Execute a script, parsing args and exposing them 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"
 }
-cmd fish help="Execute a shell script using fish" unknown_flags=value {
-    long_help #"""
-Execute a shell script with the specified shell
-
-Typically, this will be called by a script's shebang.
-
-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.
-"""#
-    flag -h help="Show help"
-    flag --help help="Show help"
-    arg <SCRIPT>
-    arg "[ARGS]…" help="Arguments to pass to script" required=#false var=#true
+cmd "fish" help="Execute a shell script using fish" unknown_flags="value" {
+    long_help "Execute a shell script using fish\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
+    flag "-h" help="Show help"
+    flag "--help" help="Show help"
+    arg "<SCRIPT>"
+    arg "[ARGS]..." help="Arguments to pass to script" {
+        long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
+    }
 }
-cmd generate subcommand_required=#true help="Generate completions, documentation, and other artifacts from usage specs" effect=read unknown_flags=error {
-    alias g
-    cmd completion help="Generate shell completion scripts for bash, fish, nu, powershell, or zsh" effect=read unknown_flags=error {
-        alias c
-        alias complete completions hide=#true
+cmd "generate" help="Generate completions, documentation, and other artifacts from usage specs" effect="read" unknown_flags="value" {
+    alias "g"
+    cmd "completion" help="Generate shell completion scripts for bash, fish, nu, powershell, or zsh" effect="read" {
+        alias "c"
+        alias "complete" hide=#true
+        alias "completions" hide=#true
         flag "-f --file" help="A .usage.kdl spec file to use for generating completions, use \"-\" to read from stdin" {
-            arg <FILE>
-        }
-        flag --cache-key help="A cache key to use for storing the results of calling the CLI with --usage-cmd" {
-            arg <CACHE_KEY>
+            arg "<FILE>"
         }
-        flag --include-bash-completion-lib help="Include https://github.com/scop/bash-completion" {
-            long_help #"""
-Include https://github.com/scop/bash-completion
-
-This is required for usage completions to work in bash, but the user may already provide it
-"""#
-        }
-        flag --usage-bin help="Override the bin used for calling back to usage-cli" default=usage {
-            long_help #"""
-Override the bin used for calling back to usage-cli
-
-You may need to set this if you have a different bin named "usage"
-"""#
-            arg <USAGE_BIN>
+        flag "--cache-key" help="A cache key to use for storing the results of calling the CLI with --usage-cmd" {
+            arg "<CACHE_KEY>"
         }
-        flag --usage-cmd help="A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"" {
-            arg <USAGE_CMD>
+        flag "--include-bash-completion-lib" help="Include https://github.com/scop/bash-completion" {
+            long_help "Include https://github.com/scop/bash-completion\n\nThis is required for usage completions to work in bash, but the user may already provide it"
         }
-        arg <SHELL> help="Shell to generate completions for" {
-            choices bash fish nu powershell zsh
+        flag "--usage-bin" help="Override the bin used for calling back to usage-cli" required=#true env="JDX_USAGE_BIN" default="usage" {
+            long_help "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\""
+            arg "<USAGE_BIN>"
         }
-        arg <BIN> help="The CLI which we're generating completions for"
-    }
-    cmd completion-init help="Generate a shell init script that auto-completes any usage shebang script on $PATH" effect=read unknown_flags=error {
-        alias ci
-        alias init 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" default=usage {
-            long_help #"""
-Override the bin used for calling back to usage-cli
-
-You may need to set this if you have a different bin named "usage"
-"""#
-            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_if="--cache-key" required_unless="--file" {
+            long_help "A command which generates a usage spec\ne.g.: `mycli --usage` or `mycli completion usage`\nDefaults to \"$bin --usage\""
+            arg "<USAGE_CMD>"
         }
-        arg <SHELL> help="Shell to generate the init script for" {
-            choices bash fish zsh
+        arg "<SHELL>" help="Shell to generate completions for" {
+            choices "bash" "fish" "nu" "powershell" "zsh"
         }
+        arg "<BIN>" help="The CLI which we're generating completions for"
     }
-    cmd fig help="Generate Fig completion spec for Amazon Q / Fig" effect=read unknown_flags=error {
-        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
-            arg <FILE>
-        }
-        flag --out-file help="File path where the generated Fig spec will be saved, or \"-\" for stdout" effect=write {
-            arg <OUT_FILE>
+    cmd "completion-init" help="Generate a shell init script that auto-completes any 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\n\nSource the output once from your shell rc (e.g. ~/.bashrc) to enable\ntab-completion for any executable whose first line is a `usage` shebang —\nno per-script `usage g completion` step required."
+        flag "--usage-bin" help="Override the bin used for calling back to usage-cli" required=#true env="JDX_USAGE_BIN" default="usage" {
+            long_help "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\""
+            arg "<USAGE_BIN>"
         }
-        flag --spec help="Raw string spec input" {
-            arg <SPEC>
+        arg "<SHELL>" help="Shell to generate the init script for" {
+            choices "bash" "fish" "zsh"
         }
     }
-    cmd go help="Generate Go parse tables from a usage spec" effect=read unknown_flags=error {
-        long_help #"""
-Generate Go parse tables from a usage spec
-
-The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a Rust CLI gets from a derive at compile time, a Go CLI gets from this at build time — typically from a `go:generate` line:
-
-//go:generate usage generate go -f mycli.usage.kdl -o tables.go
-"""#
+    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" {
-            arg <FILE>
+            arg "<FILE>"
         }
-        flag "-o --out-file" help="File path where the generated Go source will be saved, or \"-\" for stdout" effect=write {
-            arg <OUT_FILE>
+        flag "--out-file" help="File path where the generated Fig spec will be saved, or \"-\" for stdout" 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" {
-            arg <SPEC>
+        flag "--spec" help="Raw string spec input" overrides="--file" required_unless="--file" {
+            arg "<SPEC>"
         }
     }
-    cmd json help="Outputs a usage spec in json format" effect=read unknown_flags=error {
+    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" {
-            arg <FILE>
+            arg "<FILE>"
         }
-        flag --spec help="raw string spec input" {
-            arg <SPEC>
+        flag "--spec" help="raw string spec input" overrides="--file" required_unless="--file" {
+            arg "<SPEC>"
         }
     }
-    cmd json-schema help="Generate a JSON Schema for a CLI's config file from its usage spec" effect=read unknown_flags=error {
+    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" {
-            arg <FILE>
+            arg "<FILE>"
         }
-        flag --out-file help="Write the schema here instead of to stdout" effect=write {
-            arg <OUT_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" {
-            arg <SPEC>
+        flag "--spec" help="raw string spec input" overrides="--file" required_unless="--file" {
+            arg "<SPEC>"
         }
-        flag --title help="The schema's title, shown by editors" {
-            arg <TITLE>
+        flag "--title" help="The schema's title, shown by editors" {
+            arg "<TITLE>"
         }
-        flag --url help="Where the schema is published, for its `$id`" {
-            arg <URL>
+        flag "--url" help="Where the schema is published, for its `$id`" {
+            arg "<URL>"
         }
     }
-    cmd manpage effect=read unknown_flags=error {
-        alias man
+    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 {
-            arg <FILE>
+            arg "<FILE>"
         }
-        flag "-o --out-file" help="Output file path, or \"-\" for stdout (default)" effect=write {
-            arg <OUT_FILE>
+        flag "-o --out-file" help="Output file path, or \"-\" for stdout (default)" effect="write" {
+            arg "<OUT_FILE>"
         }
-        flag "-s --section" help="Manual section number (default: 1)" default="1" {
-            long_help #"""
-Manual section number (default: 1)
-
-Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: System administration commands
-"""#
-            arg <SECTION>
+        flag "-s --section" help="Manual section number (default: 1)" required=#true default="1" {
+            long_help "Manual section number (default: 1)\n\nCommon sections:\n- 1: User commands\n- 5: File formats\n- 7: Miscellaneous\n- 8: System administration commands"
+            arg "<SECTION>"
         }
     }
-    cmd markdown help="Generate markdown documentation from usage specs" effect=read unknown_flags=error {
-        alias md
+    cmd "markdown" help="Generate markdown documentation from usage specs" effect="read" {
+        alias "md"
         flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" required=#true {
-            arg <FILE>
+            arg "<FILE>"
         }
-        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 {
-            arg <OUT_DIR>
+        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" 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 "--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" {
-            arg <URL_PREFIX>
+        flag "--replace-pre-with-code-fences" help="Replace `<pre>` tags with markdown code fences"
+        flag "--url-prefix" help="Prefix to add to all URLs" {
+            arg "<URL_PREFIX>"
         }
     }
-    cmd sdk help="Generate a type-safe SDK from a usage spec" effect=write unknown_flags=error {
+    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" {
-            arg <FILE>
+            arg "<FILE>"
         }
         flag "-l --language" help="Target language for the SDK" required=#true {
-            arg <LANGUAGE> {
-                choices typescript python
+            arg "<LANGUAGE>" {
+                choices "typescript" "python"
             }
         }
         flag "-o --output" help="Output directory for generated SDK files" required=#true {
-            arg <OUTPUT>
+            arg "<OUTPUT>"
         }
         flag "-p --package-name" help="Override the package/module name (defaults to spec bin name)" {
-            arg <PACKAGE_NAME>
+            arg "<PACKAGE_NAME>"
         }
-        flag --spec help="Raw string spec input" {
-            arg <SPEC>
+        flag "--spec" help="Raw string spec input" overrides="--file" required_unless="--file" {
+            arg "<SPEC>"
         }
     }
 }
-cmd lint help="Lint a usage spec file for common issues" effect=read unknown_flags=error {
-    flag "-f --format" help="Output format" default=text {
-        arg <FORMAT> {
-            choices text json
+cmd "lint" help="Lint a usage spec file for common issues" effect="read" unknown_flags="value" {
+    flag "-f --format" help="Output format" required=#true default="text" {
+        arg "<FORMAT>" {
+            choices "text" "json"
         }
     }
     flag "-W --warnings-as-errors" help="Treat warnings as errors"
-    flag --sorted help="Also check that subcommands and flags are declared in sorted order" {
-        long_help #"""
-Also check that subcommands and flags are declared in sorted order
-
-Off by default: declaration order is a house convention rather than a correctness question, so a spec that keeps a different order is not wrong. Pair it with --warnings-as-errors to hold the order in CI.
-"""#
+    flag "--sorted" help="Also check that subcommands and flags are declared in sorted order" {
+        long_help "Also check that subcommands and flags are declared in sorted order\n\nOff by default: declaration order is a house convention rather than a\ncorrectness question, so a spec that keeps a different order is not wrong.\nPair it with --warnings-as-errors to hold the order in CI."
     }
-    arg <FILE> help="A usage spec file to lint, use \"-\" to read from stdin"
+    arg "<FILE>" help="A usage spec file to lint, use \"-\" to read from stdin"
 }
-cmd mcp help="Serve a usage spec over the Model Context Protocol" effect=read unknown_flags=error {
-    alias mcp-server
-    long_help #"""
-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`.
-"""#
+cmd "mcp" help="Serve a usage spec over the Model Context Protocol" effect="read" unknown_flags="value" {
+    alias "mcp-server"
+    long_help "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`."
     flag "-f --file" help="Usage spec file (not \"-\": stdin is the MCP transport)" {
-        arg <FILE>
+        arg "<FILE>"
     }
-    flag "-s --spec" help="Raw string spec input" {
-        arg <SPEC>
+    flag "-s --spec" help="Raw string spec input" overrides="--file" required_unless="--file" {
+        arg "<SPEC>"
     }
 }
-cmd powershell help="Execute a shell script using PowerShell" unknown_flags=value {
-    long_help #"""
-Execute a shell script with the specified shell
-
-Typically, this will be called by a script's shebang.
-
-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.
-"""#
-    flag -h help="Show help"
-    flag --help help="Show help"
-    arg <SCRIPT>
-    arg "[ARGS]…" help="Arguments to pass to script" required=#false var=#true
+cmd "powershell" help="Execute a shell script using PowerShell" unknown_flags="value" {
+    long_help "Execute a shell script using PowerShell\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
+    flag "-h" help="Show help"
+    flag "--help" help="Show help"
+    arg "<SCRIPT>"
+    arg "[ARGS]..." help="Arguments to pass to script" {
+        long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
+    }
 }
-cmd sponsors help="Show the companies sponsoring usage and the jdx.dev open source tools" effect=read unknown_flags=error
-cmd zsh help="Execute a shell script using zsh" unknown_flags=value {
-    long_help #"""
-Execute a shell script with the specified shell
-
-Typically, this will be called by a script's shebang.
-
-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.
-"""#
-    flag -h help="Show help"
-    flag --help help="Show help"
-    arg <SCRIPT>
-    arg "[ARGS]…" help="Arguments to pass to script" required=#false var=#true
+cmd "sponsors" help="Show the companies sponsoring usage and the jdx.dev open source tools" effect="read" unknown_flags="value" {
+}
+cmd "zsh" help="Execute a shell script using zsh" unknown_flags="value" {
+    long_help "Execute a shell script using zsh\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
+    flag "-h" help="Show help"
+    flag "--help" help="Show help"
+    arg "<SCRIPT>"
+    arg "[ARGS]..." help="Arguments to pass to script" {
+        long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
+    }
 }
-
 repository "https://github.com/jdx/usage"
 // The command path is not the file path: command names are hyphenated where the files
 // that implement them are snake_case, a command with subcommands lives in its directory's
diff --git a/docs/cli/reference/bash.md b/docs/cli/reference/bash.md
index d6d0daa33..73097ff5b 100644
--- a/docs/cli/reference/bash.md
+++ b/docs/cli/reference/bash.md
@@ -5,12 +5,12 @@
 - **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
+Execute a shell script using bash
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 
 ## Arguments
 
@@ -20,6 +20,9 @@ to properly escape and quote values with spaces in them.
 
 Arguments to pass to 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`
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index e425ce399..bb40f1986 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -1,5 +1,5 @@
 {
-  "name": "usage-cli",
+  "name": "usage",
   "bin": "usage",
   "cmd": {
     "full_cmd": [],
@@ -21,6 +21,7 @@
             "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\nlets a shebang script take flags of its own.",
             "help_first_line": "Arguments to pass to script",
             "required": false,
             "double_dash": "Optional",
@@ -54,7 +55,7 @@
         "unknown_flags": "value",
         "hide": false,
         "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": "Execute a shell script using bash\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\n`shell_words::join()` to properly escape and quote values with spaces in them.",
         "name": "bash",
         "aliases": [],
         "hidden_aliases": [],
@@ -101,6 +102,7 @@
             "help_first_line": "Raw string spec input",
             "short": ["s"],
             "long": ["spec"],
+            "required_unless": ["--file"],
             "hide": false,
             "global": false,
             "arg": {
@@ -109,7 +111,8 @@
               "required": true,
               "double_dash": "Optional",
               "hide": false
-            }
+            },
+            "overrides": ["--file"]
           },
           {
             "name": "cword",
@@ -124,7 +127,7 @@
               "name": "CWORD",
               "usage": "<CWORD>",
               "required": true,
-              "double_dash": "Automatic",
+              "double_dash": "Optional",
               "hide": false
             }
           },
@@ -153,7 +156,7 @@
         "unknown_flags": "value",
         "hide": false,
         "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\nThis is used internally by shell completion scripts to provide\nintelligent completions for commands, flags, and arguments.",
         "name": "complete-word",
         "aliases": ["cw"],
         "hidden_aliases": [],
@@ -240,6 +243,7 @@
             "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\nlets a shebang script take flags of its own.",
             "help_first_line": "Arguments to pass to script",
             "required": false,
             "double_dash": "Optional",
@@ -273,7 +277,7 @@
         "unknown_flags": "value",
         "hide": false,
         "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": "Execute a shell script using fish\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\n`shell_words::join()` to properly escape and quote values with spaces in them.",
         "name": "fish",
         "aliases": [],
         "hidden_aliases": [],
@@ -373,15 +377,19 @@
                   "double_dash": "Optional",
                   "hide": false
                 },
-                "default": ["usage"]
+                "default": ["usage"],
+                "env": "JDX_USAGE_BIN"
               },
               {
                 "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_long": "A command which generates a usage spec\ne.g.: `mycli --usage` or `mycli completion usage`\nDefaults 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\"",
                 "short": [],
                 "long": ["usage-cmd"],
+                "required_if": ["--cache-key"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -395,7 +403,7 @@
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "help": "Generate shell completion scripts for bash, fish, nu, powershell, or zsh",
             "name": "completion",
@@ -439,15 +447,16 @@
                   "double_dash": "Optional",
                   "hide": false
                 },
-                "default": ["usage"]
+                "default": ["usage"],
+                "env": "JDX_USAGE_BIN"
               }
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "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_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\ntab-completion for any executable whose first line is a `usage` shebang —\nno per-script `usage g completion` step required.",
             "name": "completion-init",
             "aliases": ["ci"],
             "hidden_aliases": ["init", "completions-init"],
@@ -501,6 +510,7 @@
                 "help_first_line": "Raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -509,12 +519,13 @@
                   "required": true,
                   "double_dash": "Optional",
                   "hide": false
-                }
+                },
+                "overrides": ["--file"]
               }
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "help": "Generate Fig completion spec for Amazon Q / Fig",
             "name": "fig",
@@ -639,6 +650,7 @@
                 "help_first_line": "raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -647,12 +659,13 @@
                   "required": true,
                   "double_dash": "Optional",
                   "hide": false
-                }
+                },
+                "overrides": ["--file"]
               }
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "help": "Outputs a usage spec in json format",
             "name": "json",
@@ -708,6 +721,7 @@
                 "help_first_line": "raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -716,7 +730,8 @@
                   "required": true,
                   "double_dash": "Optional",
                   "hide": false
-                }
+                },
+                "overrides": ["--file"]
               },
               {
                 "name": "title",
@@ -755,7 +770,7 @@
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "help": "Generate a JSON Schema for a CLI's config file from its usage spec",
             "name": "json-schema",
@@ -809,7 +824,7 @@
                 "name": "section",
                 "usage": "-s --section <SECTION>",
                 "help": "Manual section number (default: 1)",
-                "help_long": "Manual section number (default: 1)\n\nCommon sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: System administration commands",
+                "help_long": "Manual section number (default: 1)\n\nCommon sections:\n- 1: User commands\n- 5: File formats\n- 7: Miscellaneous\n- 8: System administration commands",
                 "help_first_line": "Manual section number (default: 1)",
                 "short": ["s"],
                 "long": ["section"],
@@ -827,8 +842,9 @@
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
+            "help": "Generate a manpage from a usage spec",
             "name": "manpage",
             "aliases": ["man"],
             "hidden_aliases": [],
@@ -886,6 +902,7 @@
                 "help_first_line": "Output markdown files to this directory (required when using --multi)",
                 "short": [],
                 "long": ["out-dir"],
+                "required_if": ["--multi"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -945,7 +962,7 @@
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "help": "Generate markdown documentation from usage specs",
             "name": "markdown",
@@ -1039,6 +1056,7 @@
                 "help_first_line": "Raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -1047,12 +1065,13 @@
                   "required": true,
                   "double_dash": "Optional",
                   "hide": false
-                }
+                },
+                "overrides": ["--file"]
               }
             ],
             "mounts": [],
             "effect": "write",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "help": "Generate a type-safe SDK from a usage spec",
             "name": "sdk",
@@ -1065,9 +1084,8 @@
         "flags": [],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "error",
+        "unknown_flags": "value",
         "hide": false,
-        "subcommand_required": true,
         "help": "Generate completions, documentation, and other artifacts from usage specs",
         "name": "generate",
         "aliases": ["g"],
@@ -1125,7 +1143,7 @@
             "name": "sorted",
             "usage": "--sorted",
             "help": "Also check that subcommands and flags are declared in sorted order",
-            "help_long": "Also check that subcommands and flags are declared in sorted order\n\nOff by default: declaration order is a house convention rather than a correctness question, so a spec that keeps a different order is not wrong. Pair it with --warnings-as-errors to hold the order in CI.",
+            "help_long": "Also check that subcommands and flags are declared in sorted order\n\nOff by default: declaration order is a house convention rather than a\ncorrectness question, so a spec that keeps a different order is not wrong.\nPair it with --warnings-as-errors to hold the order in CI.",
             "help_first_line": "Also check that subcommands and flags are declared in sorted order",
             "short": [],
             "long": ["sorted"],
@@ -1135,7 +1153,7 @@
         ],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "error",
+        "unknown_flags": "value",
         "hide": false,
         "help": "Lint a usage spec file for common issues",
         "name": "lint",
@@ -1173,6 +1191,7 @@
             "help_first_line": "Raw string spec input",
             "short": ["s"],
             "long": ["spec"],
+            "required_unless": ["--file"],
             "hide": false,
             "global": false,
             "arg": {
@@ -1181,12 +1200,13 @@
               "required": true,
               "double_dash": "Optional",
               "hide": false
-            }
+            },
+            "overrides": ["--file"]
           }
         ],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "error",
+        "unknown_flags": "value",
         "hide": false,
         "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`.",
@@ -1211,6 +1231,7 @@
             "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\nlets a shebang script take flags of its own.",
             "help_first_line": "Arguments to pass to script",
             "required": false,
             "double_dash": "Optional",
@@ -1244,7 +1265,7 @@
         "unknown_flags": "value",
         "hide": false,
         "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": "Execute a shell script using PowerShell\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\n`shell_words::join()` to properly escape and quote values with spaces in them.",
         "name": "powershell",
         "aliases": [],
         "hidden_aliases": [],
@@ -1258,7 +1279,7 @@
         "flags": [],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "error",
+        "unknown_flags": "value",
         "hide": false,
         "help": "Show the companies sponsoring usage and the jdx.dev open source tools",
         "name": "sponsors",
@@ -1282,6 +1303,7 @@
             "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\nlets a shebang script take flags of its own.",
             "help_first_line": "Arguments to pass to script",
             "required": false,
             "double_dash": "Optional",
@@ -1315,7 +1337,7 @@
         "unknown_flags": "value",
         "hide": false,
         "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": "Execute a shell script using zsh\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\n`shell_words::join()` to properly escape and quote values with spaces in them.",
         "name": "zsh",
         "aliases": [],
         "hidden_aliases": [],
@@ -1359,7 +1381,7 @@
     "files": []
   },
   "version": "5.1.0",
-  "usage": "Usage: usage-cli [OPTIONS] [COMPLETIONS] <COMMAND>",
+  "usage": "",
   "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",
diff --git a/docs/cli/reference/complete-word.md b/docs/cli/reference/complete-word.md
index 83bc74546..714ba17c3 100644
--- a/docs/cli/reference/complete-word.md
+++ b/docs/cli/reference/complete-word.md
@@ -9,7 +9,8 @@
 
 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.
+This is used internally by shell completion scripts to provide
+intelligent completions for commands, flags, and arguments.
 
 ## Arguments
 
diff --git a/docs/cli/reference/fish.md b/docs/cli/reference/fish.md
index 7a349ba08..c6d06106b 100644
--- a/docs/cli/reference/fish.md
+++ b/docs/cli/reference/fish.md
@@ -5,12 +5,12 @@
 - **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
+Execute a shell script using fish
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 
 ## Arguments
 
@@ -20,6 +20,9 @@ to properly escape and quote values with spaces in them.
 
 Arguments to pass to 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`
diff --git a/docs/cli/reference/generate/completion-init.md b/docs/cli/reference/generate/completion-init.md
index 8cafde27a..f551990bb 100644
--- a/docs/cli/reference/generate/completion-init.md
+++ b/docs/cli/reference/generate/completion-init.md
@@ -9,7 +9,9 @@
 
 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.
+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.
 
 ## Arguments
 
@@ -32,3 +34,5 @@ Override the bin used for calling back to usage-cli
 You may need to set this if you have a different bin named "usage"
 
 **Default:** `usage`
+
+**Environment Variable:** `JDX_USAGE_BIN`
diff --git a/docs/cli/reference/generate/completion.md b/docs/cli/reference/generate/completion.md
index 82489afc9..d911fdcf4 100644
--- a/docs/cli/reference/generate/completion.md
+++ b/docs/cli/reference/generate/completion.md
@@ -51,6 +51,10 @@ You may need to set this if you have a different bin named "usage"
 
 **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"
+A command which generates a usage spec
+e.g.: `mycli --usage` or `mycli completion usage`
+Defaults to "$bin --usage"
diff --git a/docs/cli/reference/generate/manpage.md b/docs/cli/reference/generate/manpage.md
index 7f0d4e271..bc22f6d99 100644
--- a/docs/cli/reference/generate/manpage.md
+++ b/docs/cli/reference/generate/manpage.md
@@ -7,6 +7,8 @@
 - **Effect**: read-only
 - **Source code**: [`cli/src/cli/generate/manpage.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/manpage.rs)
 
+Generate a manpage from a usage spec
+
 ## Flags
 
 ### `-f --file <FILE>`
@@ -23,6 +25,11 @@ Output file path, or "-" for stdout (default)
 
 Manual section number (default: 1)
 
-Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: System administration commands
+Common sections:
+
+- 1: User commands
+- 5: File formats
+- 7: Miscellaneous
+- 8: System administration commands
 
 **Default:** `1`
diff --git a/docs/cli/reference/lint.md b/docs/cli/reference/lint.md
index 0a4e055f4..acf4c72e9 100644
--- a/docs/cli/reference/lint.md
+++ b/docs/cli/reference/lint.md
@@ -35,4 +35,6 @@ Treat warnings as errors
 
 Also check that subcommands and flags are declared in sorted order
 
-Off by default: declaration order is a house convention rather than a correctness question, so a spec that keeps a different order is not wrong. Pair it with --warnings-as-errors to hold the order in CI.
+Off by default: declaration order is a house convention rather than a
+correctness question, so a spec that keeps a different order is not wrong.
+Pair it with --warnings-as-errors to hold the order in CI.
diff --git a/docs/cli/reference/powershell.md b/docs/cli/reference/powershell.md
index f97eff4bb..64abd928a 100644
--- a/docs/cli/reference/powershell.md
+++ b/docs/cli/reference/powershell.md
@@ -5,12 +5,12 @@
 - **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
+Execute a shell script using PowerShell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 
 ## Arguments
 
@@ -20,6 +20,9 @@ to properly escape and quote values with spaces in them.
 
 Arguments to pass to 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`
diff --git a/docs/cli/reference/zsh.md b/docs/cli/reference/zsh.md
index 90ff59f54..7a3d42d2d 100644
--- a/docs/cli/reference/zsh.md
+++ b/docs/cli/reference/zsh.md
@@ -5,12 +5,12 @@
 - **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
+Execute a shell script using zsh
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 
 ## Arguments
 
@@ -20,6 +20,9 @@ to properly escape and quote values with spaces in them.
 
 Arguments to pass to 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`

From 7fc702b53fc7dfa5f279133fb8c587837fd392fa Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 01:51:04 +0000
Subject: [PATCH 02/13] fix(cli): take the two derive fixes, and say what this
 CLI actually accepts

Follow-up to the conversion, now stacked on the two gaps it found rather than
describing them as open.

`unknown_flags` reaches the whole tree. The root declares `error` once and every
subcommand inherits it, so `usage lint --nope f.kdl` names the flag again
instead of making `--nope` the file and calling the real file unexpected. The
five commands that hand a command line to somebody else's script declare
`value` for themselves, which is the half that needs a subcommand to be able to
say something.

## From review

`--version` says `usage 5.1.0`, not `usage-cli 5.1.0`. The crate is `usage-cli`
and the binary is `usage`; everything else this CLI says about itself now comes
from the spec, where the name is `usage`, so the version line was contradicting
the help banner printed directly above it. Read from the spec by `version()`,
which `-v` shares, so the two cannot drift.

`--out-dir` without `--multi` is refused. clap said this as a `requires` in both
directions; the spec can only state the direction that makes `--multi` need a
destination, so without a check the other way `usage g markdown --out-dir docs`
quietly wrote a single file somewhere else. Enforced in `run()` until
jdx/usage#925's `requires` can carry it.

`--completions` is a flag, which is how it is typed. The clap declaration made
it a *positional*, so the spec, the docs, the manpage and the generated
completions all described a `[COMPLETIONS]` argument that nothing accepts, while
the flag that does work went undocumented. The conversion carried that over
faithfully, wrong included. The point of emitting the spec from the declaration
is that the two cannot disagree, so the declaration is what changes.

Declined one: CodeRabbit read the `man` alias on `generate manpage` as removed.
It is declared, in the emitted spec, and on the rendered page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 cli/assets/fig.ts                | 15 ++++++-----
 cli/assets/usage.1               |  9 +++----
 cli/src/cli/exec.rs              |  3 +++
 cli/src/cli/generate/markdown.rs |  7 +++++
 cli/src/cli/mod.rs               | 46 +++++++++++++++++++++++---------
 cli/src/cli/shell.rs             |  3 +++
 cli/src/lib.rs                   |  4 ++-
 cli/usage.usage.kdl              | 14 +++++-----
 docs/cli/reference/commands.json | 38 +++++++++++++++-----------
 docs/cli/reference/index.md      | 10 +++----
 10 files changed, 97 insertions(+), 52 deletions(-)

diff --git a/cli/assets/fig.ts b/cli/assets/fig.ts
index 8f426aeb9..a4f3eaa38 100644
--- a/cli/assets/fig.ts
+++ b/cli/assets/fig.ts
@@ -716,18 +716,21 @@ const completionSpec: Fig.Spec = {
     },
   ],
   options: [
+    {
+      name: "--completions",
+      description:
+        "Outputs completions for the specified shell for completing the `usage` CLI itself",
+      isRepeatable: false,
+      args: {
+        name: "completions",
+      },
+    },
     {
       name: "--usage-spec",
       description: "Outputs a `usage.kdl` spec for this CLI itself",
       isRepeatable: false,
     },
   ],
-  args: {
-    name: "completions",
-    description:
-      "Outputs completions for the specified shell for completing the `usage` CLI itself",
-    isOptional: true,
-  },
 };
 
 export default completionSpec;
diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index d1f080954..2acba63f2 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -2,18 +2,17 @@
 .SH NAME
 usage \- CLI for working with usage\-based CLIs
 .SH SYNOPSIS
-\fBusage\fR [OPTIONS] [<COMPLETIONS>] [COMMAND]
+\fBusage\fR [OPTIONS] [COMMAND]
 .SH DESCRIPTION
 CLI for working with usage\-based CLIs
 .PP
 .SH OPTIONS
 .TP
+\fB\-\-completions\fR \fI<COMPLETIONS>\fR
+Outputs completions for the specified shell for completing the `usage` CLI itself
+.TP
 \fB\-\-usage\-spec\fR
 Outputs a `usage.kdl` spec for this CLI itself
-.SH ARGUMENTS
-.TP
-\fB<COMPLETIONS>\fR
-Outputs completions for the specified shell for completing the `usage` CLI itself
 .SH COMMANDS
 .TP
 \fBbash\fR
diff --git a/cli/src/cli/exec.rs b/cli/src/cli/exec.rs
index 0dfbcd8c1..fd46c6959 100644
--- a/cli/src/cli/exec.rs
+++ b/cli/src/cli/exec.rs
@@ -12,6 +12,9 @@ use crate::env;
 
 /// Execute a script, parsing args and exposing them as environment variables
 #[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(unknown_flags = "value")]
 pub struct Exec {
     /// command to execute after parsing usage spec
     command: String,
diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs
index c24a98f21..15db1d1c1 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -46,6 +46,13 @@ pub struct Markdown {
 
 impl Markdown {
     pub fn run(&self) -> miette::Result<()> {
+        // The half of the `--multi`/`--out-dir` pair the spec cannot state. Checked here
+        // rather than left out: without it, `--out-dir docs` with no `--multi` writes a
+        // single file somewhere else entirely and says nothing, where clap refused the
+        // command line. Belongs in the spec once jdx/usage#925's `requires` lands.
+        if self.out_dir.is_some() && !self.multi {
+            miette::bail!("--out-dir is only used with --multi");
+        }
         // The banner belongs to every generated document, so build it in one place rather
         // than once per output path.
         let render = |md: &str| {
diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index c146a3ced..56769961a 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -25,15 +25,13 @@ mod sponsors;
     bin = "usage",
     version,
     min_usage_version = "4.0",
-    // Every flag the root accepts is one it declares, so an unrecognised one is a mistake and
-    // saying so beats binding it to `[COMPLETIONS]`.
+    // Every flag `usage` accepts is one it declares, so an unrecognised one is a mistake and
+    // saying so beats offering it to a positional — `usage lint --nope f.kdl` would otherwise
+    // make `--nope` the file and call the real file unexpected.
     //
-    // Only the root, which is as far as the derive carries this today: the attribute is
-    // accepted on an `Args` and then ignored, and a subcommand does not inherit the root's.
-    // So `usage lint --nope f.kdl` still makes `--nope` the file and calls the real file
-    // unexpected, where clap named the flag. The five commands that hand a command line to
-    // somebody else's script want the lenient reading and get it by default, which is why
-    // this is worth fixing in the derive rather than working around here.
+    // Declared once, on the root: every subcommand inherits it. The five that hand a command
+    // line to somebody else's script say `value` for themselves, which is the whole reason
+    // both halves are needed.
     unknown_flags = "error"
 )]
 pub struct Cli {
@@ -41,11 +39,18 @@ pub struct Cli {
     command: Command,
 
     /// Outputs completions for the specified shell for completing the `usage` CLI itself
-    // Declaration only, as it was under clap: `--completions <shell>` is 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 command line understood to answer. It is declared so
-    // that help, the spec and the completions know it exists.
+    // Declaration only: `--completions <shell>` is 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 command line understood to answer. It is declared so that help, the spec and
+    // the completions know it exists.
+    //
+    // A flag, which is how it is typed. The clap declaration made it a *positional* — so the
+    // spec, the docs and the generated completions all described a `[COMPLETIONS]` argument
+    // that nothing accepts, while the flag that does work went undocumented. Carried over
+    // faithfully at first, wrong included; the point of emitting the spec from the
+    // declaration is that the two cannot disagree, so the declaration is what changes.
     #[allow(dead_code)]
+    #[usage(long)]
     completions: Option<String>,
 
     /// Outputs a `usage.kdl` spec for this CLI itself
@@ -53,6 +58,21 @@ pub struct Cli {
     usage_spec: bool,
 }
 
+/// What `--version` and `-v` answer with.
+///
+/// The binary's name, not the crate's. They differ here — `usage-cli` ships `usage` — and
+/// everything else this CLI says about itself now comes from the spec, where the name is
+/// `usage`. Read from the spec rather than written out again, so a rename cannot leave the
+/// version line saying something the help page above it contradicts.
+pub(crate) fn version() -> String {
+    let spec = Cli::spec();
+    format!(
+        "{} {}",
+        spec.bin.unwrap_or(spec.name),
+        spec.version.unwrap_or(env!("CARGO_PKG_VERSION"))
+    )
+}
+
 /// What `usage` can be asked to do.
 ///
 /// Each command's description is its struct's doc comment, in the file that owns it, except
@@ -94,7 +114,7 @@ impl Cli {
                 return Ok(());
             }
             Err(usage_argv::Error::Version) => {
-                println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
+                println!("{}", version());
                 return Ok(());
             }
             Err(err) => {
diff --git a/cli/src/cli/shell.rs b/cli/src/cli/shell.rs
index b4b44fd45..33699526f 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -49,6 +49,9 @@ macro_rules! shell_command {
         #[doc = "If using `var=#true` on args/flags, they will be joined with spaces using"]
         #[doc = "`shell_words::join()` to properly escape and quote values with spaces in them."]
         #[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(unknown_flags = "value")]
         pub struct $ty {
             #[usage(flatten)]
             pub shell: Shell,
diff --git a/cli/src/lib.rs b/cli/src/lib.rs
index 4e76f073a..e687ce41b 100644
--- a/cli/src/lib.rs
+++ b/cli/src/lib.rs
@@ -34,7 +34,9 @@ pub fn run(args: &[String]) -> Result<()> {
     // } else if let Some(script) = args.get(1) {
     if let Some(script) = args.get(1) {
         if script.to_lowercase() == "-v" {
-            println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
+            // The same line `--version` prints, from the same place. These used to be two
+            // copies of the crate name, which is not what this binary is called.
+            println!("{}", cli::version());
             return Ok(());
         } else if script == "--usage-spec" {
             return usage_spec::generate();
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index fd18e30b5..d4cd8eaa3 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -5,8 +5,10 @@ bin "usage"
 version "5.1.0"
 about "CLI for working with usage-based CLIs"
 unknown_flags "error"
+flag "--completions" help="Outputs completions for the specified shell for completing the `usage` CLI itself" {
+    arg "<COMPLETIONS>"
+}
 flag "--usage-spec" help="Outputs a `usage.kdl` spec for this CLI itself"
-arg "[COMPLETIONS]" help="Outputs completions for the specified shell for completing the `usage` CLI itself"
 cmd "bash" help="Execute a shell script using bash" unknown_flags="value" {
     long_help "Execute a shell script using bash\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
     flag "-h" help="Show help"
@@ -16,7 +18,7 @@ cmd "bash" help="Execute a shell script using bash" unknown_flags="value" {
         long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
     }
 }
-cmd "complete-word" help="Generate shell completion candidates for a partial command line" effect="read" unknown_flags="value" {
+cmd "complete-word" help="Generate shell completion candidates for a partial command line" effect="read" {
     alias "cw"
     long_help "Generate shell completion candidates for a partial command line\n\nThis is used internally by shell completion scripts to provide\nintelligent completions for commands, flags, and arguments."
     flag "-f --file" help="Usage spec file or script with usage shebang, use \"-\" to read from stdin" {
@@ -52,7 +54,7 @@ cmd "fish" help="Execute a shell script using fish" unknown_flags="value" {
         long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
     }
 }
-cmd "generate" help="Generate completions, documentation, and other artifacts from usage specs" effect="read" unknown_flags="value" {
+cmd "generate" help="Generate completions, documentation, and other artifacts from usage specs" effect="read" subcommand_required=#true {
     alias "g"
     cmd "completion" help="Generate shell completion scripts for bash, fish, nu, powershell, or zsh" effect="read" {
         alias "c"
@@ -180,7 +182,7 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
         }
     }
 }
-cmd "lint" help="Lint a usage spec file for common issues" effect="read" unknown_flags="value" {
+cmd "lint" help="Lint a usage spec file for common issues" effect="read" {
     flag "-f --format" help="Output format" required=#true default="text" {
         arg "<FORMAT>" {
             choices "text" "json"
@@ -192,7 +194,7 @@ cmd "lint" help="Lint a usage spec file for common issues" effect="read" unknown
     }
     arg "<FILE>" help="A usage spec file to lint, use \"-\" to read from stdin"
 }
-cmd "mcp" help="Serve a usage spec over the Model Context Protocol" effect="read" unknown_flags="value" {
+cmd "mcp" help="Serve a usage spec over the Model Context Protocol" effect="read" {
     alias "mcp-server"
     long_help "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`."
     flag "-f --file" help="Usage spec file (not \"-\": stdin is the MCP transport)" {
@@ -211,7 +213,7 @@ cmd "powershell" help="Execute a shell script using PowerShell" unknown_flags="v
         long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
     }
 }
-cmd "sponsors" help="Show the companies sponsoring usage and the jdx.dev open source tools" effect="read" unknown_flags="value" {
+cmd "sponsors" help="Show the companies sponsoring usage and the jdx.dev open source tools" effect="read" {
 }
 cmd "zsh" help="Execute a shell script using zsh" unknown_flags="value" {
     long_help "Execute a shell script using zsh\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index bb40f1986..14fe03f5e 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -3,7 +3,7 @@
   "bin": "usage",
   "cmd": {
     "full_cmd": [],
-    "usage": "[--usage-spec] [COMPLETIONS] <SUBCOMMAND>",
+    "usage": "[--completions <COMPLETIONS>] [--usage-spec] <SUBCOMMAND>",
     "subcommands": {
       "bash": {
         "full_cmd": ["bash"],
@@ -153,7 +153,7 @@
         ],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "value",
+        "unknown_flags": null,
         "hide": false,
         "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\nintelligent completions for commands, flags, and arguments.",
@@ -1084,8 +1084,9 @@
         "flags": [],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "value",
+        "unknown_flags": null,
         "hide": false,
+        "subcommand_required": true,
         "help": "Generate completions, documentation, and other artifacts from usage specs",
         "name": "generate",
         "aliases": ["g"],
@@ -1153,7 +1154,7 @@
         ],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "value",
+        "unknown_flags": null,
         "hide": false,
         "help": "Lint a usage spec file for common issues",
         "name": "lint",
@@ -1206,7 +1207,7 @@
         ],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "value",
+        "unknown_flags": null,
         "hide": false,
         "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`.",
@@ -1279,7 +1280,7 @@
         "flags": [],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "value",
+        "unknown_flags": null,
         "hide": false,
         "help": "Show the companies sponsoring usage and the jdx.dev open source tools",
         "name": "sponsors",
@@ -1344,18 +1345,25 @@
         "examples": []
       }
     },
-    "args": [
+    "args": [],
+    "flags": [
       {
-        "name": "COMPLETIONS",
-        "usage": "[COMPLETIONS]",
+        "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",
-        "required": false,
-        "double_dash": "Optional",
-        "hide": false
-      }
-    ],
-    "flags": [
+        "short": [],
+        "long": ["completions"],
+        "hide": false,
+        "global": false,
+        "arg": {
+          "name": "COMPLETIONS",
+          "usage": "<COMPLETIONS>",
+          "required": true,
+          "double_dash": "Optional",
+          "hide": false
+        }
+      },
       {
         "name": "usage-spec",
         "usage": "--usage-spec",
diff --git a/docs/cli/reference/index.md b/docs/cli/reference/index.md
index fc8f417a7..21a3892d2 100644
--- a/docs/cli/reference/index.md
+++ b/docs/cli/reference/index.md
@@ -2,20 +2,18 @@
 
 # `usage`
 
-**Usage**: `usage [--usage-spec] [COMPLETIONS] <SUBCOMMAND>`
+**Usage**: `usage [--completions <COMPLETIONS>] [--usage-spec] <SUBCOMMAND>`
 
 **Version**: 5.1.0
 
-- **Usage**: `usage [--usage-spec] [COMPLETIONS] <SUBCOMMAND>`
+- **Usage**: `usage [--completions <COMPLETIONS>] [--usage-spec] <SUBCOMMAND>`
 
-## Arguments
+## Flags
 
-### `[COMPLETIONS]`
+### `--completions <COMPLETIONS>`
 
 Outputs completions for the specified shell for completing the `usage` CLI itself
 
-## Flags
-
 ### `--usage-spec`
 
 Outputs a `usage.kdl` spec for this CLI itself

From 8b660c2420f2a5d47f4c010031f182b6e3f32df5 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:09:33 +0000
Subject: [PATCH 03/13] refactor(cli): reduce derive migration churn

---
 cli/src/cli/complete_word.rs            |  6 +++---
 cli/src/cli/exec.rs                     |  4 ++--
 cli/src/cli/generate/completion.rs      | 10 ++++------
 cli/src/cli/generate/completion_init.rs |  6 +++++-
 cli/src/cli/generate/fig.rs             |  2 +-
 cli/src/cli/generate/json.rs            |  2 +-
 cli/src/cli/generate/json_schema.rs     |  2 +-
 cli/src/cli/generate/manpage.rs         |  8 ++++----
 cli/src/cli/generate/markdown.rs        | 22 +++++-----------------
 cli/src/cli/generate/mod.rs             |  6 +-----
 cli/src/cli/generate/sdk.rs             |  8 ++++----
 cli/src/cli/lint.rs                     |  2 +-
 cli/src/cli/mcp.rs                      |  6 +++---
 cli/src/cli/mod.rs                      |  4 ----
 cli/src/cli/shell.rs                    |  2 +-
 cli/usage.usage.kdl                     |  6 +++---
 docs/cli/reference/commands.json        |  5 +++--
 17 files changed, 42 insertions(+), 59 deletions(-)

diff --git a/cli/src/cli/complete_word.rs b/cli/src/cli/complete_word.rs
index 5e323fa11..3adcd6faa 100644
--- a/cli/src/cli/complete_word.rs
+++ b/cli/src/cli/complete_word.rs
@@ -23,17 +23,17 @@ use crate::cli::generate;
 /// This is used internally by shell completion scripts to provide
 /// intelligent completions for commands, flags, and arguments.
 #[derive(Debug, Args)]
-#[usage(effect = "read")]
+#[usage(alias = "cw", effect = "read")]
 pub struct CompleteWord {
     /// User's input from the command line
     words: Vec<String>,
 
     /// Usage spec file or script with usage shebang, use "-" to read from stdin
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// Raw string spec input
-    #[usage(short = 's', long, required_unless = "--file", overrides = "--file")]
+    #[usage(short, long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 
     /// Current word index
diff --git a/cli/src/cli/exec.rs b/cli/src/cli/exec.rs
index fd46c6959..333d2bea4 100644
--- a/cli/src/cli/exec.rs
+++ b/cli/src/cli/exec.rs
@@ -14,7 +14,7 @@ use crate::env;
 #[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(unknown_flags = "value")]
+#[usage(alias = "x", unknown_flags = "value")]
 pub struct Exec {
     /// command to execute after parsing usage spec
     command: String,
@@ -24,7 +24,7 @@ pub struct Exec {
     args: Vec<String>,
 
     /// Show help
-    #[usage(short = 'h')]
+    #[usage(short)]
     h: bool,
 
     /// Show help
diff --git a/cli/src/cli/generate/completion.rs b/cli/src/cli/generate/completion.rs
index c1601973d..e4c427848 100644
--- a/cli/src/cli/generate/completion.rs
+++ b/cli/src/cli/generate/completion.rs
@@ -7,7 +7,7 @@ use super::parse_file_or_stdin;
 
 /// Generate shell completion scripts for bash, fish, nu, powershell, or zsh
 #[derive(Args)]
-#[usage(effect = "read")]
+#[usage(alias = "c", alias_hidden("complete", "completions"), effect = "read")]
 pub struct Completion {
     /// Shell to generate completions for
     #[usage(choices("bash", "fish", "nu", "powershell", "zsh"))]
@@ -17,13 +17,11 @@ pub struct Completion {
     bin: String,
 
     /// A .usage.kdl spec file to use for generating completions, use "-" to read from stdin
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
-    // clap said `requires = "usage_cmd"`; the spec has no positive form yet, so the same
-    // rule is stated from the other end, on the flag that has to be there.
     /// A cache key to use for storing the results of calling the CLI with --usage-cmd
-    #[usage(long)]
+    #[usage(long, requires = "--usage-cmd")]
     cache_key: Option<String>,
 
     /// Include https://github.com/scop/bash-completion
@@ -41,7 +39,7 @@ pub struct Completion {
     /// A command which generates a usage spec
     /// e.g.: `mycli --usage` or `mycli completion usage`
     /// Defaults to "$bin --usage"
-    #[usage(long, required_unless = "--file", required_if = "--cache-key")]
+    #[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 08d8e1bd5..b406111d1 100644
--- a/cli/src/cli/generate/completion_init.rs
+++ b/cli/src/cli/generate/completion_init.rs
@@ -7,7 +7,11 @@ use usage_derive::Args;
 /// tab-completion for any executable whose first line is a `usage` shebang —
 /// no per-script `usage g completion` step required.
 #[derive(Args)]
-#[usage(effect = "read")]
+#[usage(
+    alias = "ci",
+    alias_hidden("init", "completions-init"),
+    effect = "read"
+)]
 pub struct CompletionInit {
     /// Shell to generate the init script for
     #[usage(choices("bash", "fish", "zsh"))]
diff --git a/cli/src/cli/generate/fig.rs b/cli/src/cli/generate/fig.rs
index 16d9e909a..a57560e6d 100644
--- a/cli/src/cli/generate/fig.rs
+++ b/cli/src/cli/generate/fig.rs
@@ -49,7 +49,7 @@ mod description_format {
 #[usage(effect = "read")]
 pub struct Fig {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// File path where the generated Fig spec will be saved, or "-" for stdout
diff --git a/cli/src/cli/generate/json.rs b/cli/src/cli/generate/json.rs
index 19dab57b2..22fe5c2e7 100644
--- a/cli/src/cli/generate/json.rs
+++ b/cli/src/cli/generate/json.rs
@@ -8,7 +8,7 @@ use std::path::PathBuf;
 #[usage(effect = "read")]
 pub struct Json {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// raw string spec input
diff --git a/cli/src/cli/generate/json_schema.rs b/cli/src/cli/generate/json_schema.rs
index bc2a0fdb1..0627e2fee 100644
--- a/cli/src/cli/generate/json_schema.rs
+++ b/cli/src/cli/generate/json_schema.rs
@@ -11,7 +11,7 @@ use crate::Result;
 #[usage(effect = "read")]
 pub struct JsonSchema {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// Write the schema here instead of to stdout
diff --git a/cli/src/cli/generate/manpage.rs b/cli/src/cli/generate/manpage.rs
index 3ec97cd48..29fb772b7 100644
--- a/cli/src/cli/generate/manpage.rs
+++ b/cli/src/cli/generate/manpage.rs
@@ -6,14 +6,14 @@ use usage_derive::Args;
 
 /// Generate a manpage from a usage spec
 #[derive(Args)]
-#[usage(effect = "read")]
+#[usage(alias = "man", effect = "read")]
 pub struct Manpage {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: PathBuf,
 
     /// Output file path, or "-" for stdout (default)
-    #[usage(short = 'o', long, effect = "write")]
+    #[usage(short, long, effect = "write")]
     out_file: Option<PathBuf>,
 
     /// Manual section number (default: 1)
@@ -23,7 +23,7 @@ pub struct Manpage {
     /// - 5: File formats
     /// - 7: Miscellaneous
     /// - 8: System administration commands
-    #[usage(short = 's', long, default = "1")]
+    #[usage(short, long, default = "1")]
     section: u8,
 }
 
diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs
index 15db1d1c1..8fab484b6 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -6,29 +6,24 @@ use usage_derive::Args;
 
 /// Generate markdown documentation from usage specs
 #[derive(Args)]
-#[usage(effect = "read")]
+#[usage(alias = "md", effect = "read")]
 pub struct Markdown {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: PathBuf,
     // /// Pass a usage spec in an argument instead of a file
-    // #[usage(short = 's', long, required_unless = "--file", overrides = "--file")]
+    // #[usage(short, long, required_unless = "--file", overrides = "--file")]
     // spec: Option<String>,
     /// Render each subcommand as a separate markdown file
-    #[usage(short = 'm', long, conflicts = "--out-file")]
+    #[usage(short, long, conflicts = "--out-file")]
     multi: bool,
 
     /// Escape HTML in markdown
     #[usage(long)]
     html_encode: bool,
 
-    // clap said this both ways: `--multi requires --out-dir` and `--out-dir requires
-    // --multi`. `required_if` says the first, which is the direction that matters — a
-    // multi-file render with nowhere to write. The second is a positive requirement on a
-    // `bool`, which nothing in the spec can state; jdx/usage#925 adds `requires`, and it
-    // belongs here when it lands.
     /// Output markdown files to this directory (required when using --multi)
-    #[usage(long, required_if = "--multi", effect = "write")]
+    #[usage(long, requires = "--multi", required_if = "--multi", effect = "write")]
     out_dir: Option<PathBuf>,
 
     /// Output file path for single-file markdown generation, or "-" for stdout (default)
@@ -46,13 +41,6 @@ pub struct Markdown {
 
 impl Markdown {
     pub fn run(&self) -> miette::Result<()> {
-        // The half of the `--multi`/`--out-dir` pair the spec cannot state. Checked here
-        // rather than left out: without it, `--out-dir docs` with no `--multi` writes a
-        // single file somewhere else entirely and says nothing, where clap refused the
-        // command line. Belongs in the spec once jdx/usage#925's `requires` lands.
-        if self.out_dir.is_some() && !self.multi {
-            miette::bail!("--out-dir is only used with --multi");
-        }
         // The banner belongs to every generated document, so build it in one place rather
         // than once per output path.
         let render = |md: &str| {
diff --git a/cli/src/cli/generate/mod.rs b/cli/src/cli/generate/mod.rs
index b416e0f39..da4af4c36 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -16,7 +16,7 @@ mod sdk;
 /// Generate completions, documentation, and other artifacts from usage specs
 // Cannot run alone, and every child starts at `read`, so the parent is `read` too.
 #[derive(usage_derive::Args)]
-#[usage(effect = "read")]
+#[usage(alias = "g", effect = "read")]
 pub struct Generate {
     #[usage(subcommand)]
     pub command: Command,
@@ -28,16 +28,12 @@ pub struct Generate {
 /// derive would let win: one description, in the file that owns the command.
 #[derive(usage_derive::Subcommands)]
 pub enum Command {
-    #[usage(alias = "c", alias_hidden("complete", "completions"))]
     Completion(Box<completion::Completion>),
-    #[usage(alias = "ci", alias_hidden("init", "completions-init"))]
     CompletionInit(Box<completion_init::CompletionInit>),
     Fig(Box<fig::Fig>),
     Json(Box<json::Json>),
     JsonSchema(Box<json_schema::JsonSchema>),
-    #[usage(alias = "man")]
     Manpage(Box<manpage::Manpage>),
-    #[usage(alias = "md")]
     Markdown(Box<markdown::Markdown>),
     Sdk(Box<sdk::Sdk>),
 }
diff --git a/cli/src/cli/generate/sdk.rs b/cli/src/cli/generate/sdk.rs
index 00d2d962f..3e8647a69 100644
--- a/cli/src/cli/generate/sdk.rs
+++ b/cli/src/cli/generate/sdk.rs
@@ -14,19 +14,19 @@ use usage::sdk::{SdkLanguage, SdkOptions};
 #[usage(effect = "write")]
 pub struct Sdk {
     /// A usage spec taken in as a file
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// Target language for the SDK
-    #[usage(short = 'l', long, choices("typescript", "python"))]
+    #[usage(short, long, choices("typescript", "python"))]
     language: String,
 
     /// Output directory for generated SDK files
-    #[usage(short = 'o', long)]
+    #[usage(short, long)]
     output: PathBuf,
 
     /// Override the package/module name (defaults to spec bin name)
-    #[usage(short = 'p', long)]
+    #[usage(short, long)]
     package_name: Option<String>,
 
     /// Raw string spec input
diff --git a/cli/src/cli/lint.rs b/cli/src/cli/lint.rs
index f83415157..e60628944 100644
--- a/cli/src/cli/lint.rs
+++ b/cli/src/cli/lint.rs
@@ -12,7 +12,7 @@ pub struct Lint {
     file: PathBuf,
 
     /// Output format
-    #[usage(long, short = 'f', default = "text", value_enum)]
+    #[usage(long, short, default = "text", value_enum)]
     format: OutputFormat,
 
     /// Treat warnings as errors
diff --git a/cli/src/cli/mcp.rs b/cli/src/cli/mcp.rs
index 6387d1881..65bec80b2 100644
--- a/cli/src/cli/mcp.rs
+++ b/cli/src/cli/mcp.rs
@@ -43,16 +43,16 @@ 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`.
 #[derive(Debug, usage_derive::Args)]
-#[usage(effect = "read")]
+#[usage(alias = "mcp-server", 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)
-    #[usage(short = 'f', long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// Raw string spec input
-    #[usage(short = 's', long, required_unless = "--file", overrides = "--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 56769961a..7073b8fd0 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -80,15 +80,11 @@ pub(crate) fn version() -> String {
 #[derive(Subcommands)]
 enum Command {
     Bash(Box<shell::Bash>),
-    #[usage(alias = "cw")]
     CompleteWord(Box<complete_word::CompleteWord>),
-    #[usage(alias = "x")]
     Exec(Box<exec::Exec>),
     Fish(Box<shell::Fish>),
-    #[usage(alias = "g")]
     Generate(Box<generate::Generate>),
     Lint(Box<lint::Lint>),
-    #[usage(alias = "mcp-server")]
     Mcp(Box<mcp::Mcp>),
     #[usage(name = "powershell")]
     PowerShell(Box<shell::PowerShell>),
diff --git a/cli/src/cli/shell.rs b/cli/src/cli/shell.rs
index 33699526f..b2c1b9057 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -27,7 +27,7 @@ pub struct Shell {
     args: Vec<String>,
 
     /// Show help
-    #[usage(short = 'h')]
+    #[usage(short)]
     h: bool,
 
     /// Show help
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index d4cd8eaa3..b95de4e00 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -63,7 +63,7 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
         flag "-f --file" help="A .usage.kdl spec file to use for generating completions, use \"-\" to read from stdin" {
             arg "<FILE>"
         }
-        flag "--cache-key" help="A cache key to use for storing the results of calling the CLI with --usage-cmd" {
+        flag "--cache-key" help="A cache key to use for storing the results of calling the CLI with --usage-cmd" requires="--usage-cmd" {
             arg "<CACHE_KEY>"
         }
         flag "--include-bash-completion-lib" help="Include https://github.com/scop/bash-completion" {
@@ -73,7 +73,7 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
             long_help "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\""
             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_if="--cache-key" required_unless="--file" {
+        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" {
             long_help "A command which generates a usage spec\ne.g.: `mycli --usage` or `mycli completion usage`\nDefaults to \"$bin --usage\""
             arg "<USAGE_CMD>"
         }
@@ -151,7 +151,7 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
         }
         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" required_if="--multi" {
+        flag "--out-dir" help="Output markdown files to this directory (required when using --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" {
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index 14fe03f5e..d623dcfdb 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -347,7 +347,8 @@
                   "required": true,
                   "double_dash": "Optional",
                   "hide": false
-                }
+                },
+                "requires": ["--usage-cmd"]
               },
               {
                 "name": "include-bash-completion-lib",
@@ -388,7 +389,6 @@
                 "help_first_line": "A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"",
                 "short": [],
                 "long": ["usage-cmd"],
-                "required_if": ["--cache-key"],
                 "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
@@ -912,6 +912,7 @@
                   "double_dash": "Optional",
                   "hide": false
                 },
+                "requires": ["--multi"],
                 "effect": "write"
               },
               {

From c71ed35b799ccb697539175d64f277cc7e6383e6 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:18:12 +0000
Subject: [PATCH 04/13] refactor(cli): retain verbatim doc comments

---
 cli/src/cli/generate/completion.rs | 2 +-
 cli/src/cli/mcp.rs                 | 2 +-
 cli/src/cli/shell.rs               | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/cli/src/cli/generate/completion.rs b/cli/src/cli/generate/completion.rs
index e4c427848..90b7f9be9 100644
--- a/cli/src/cli/generate/completion.rs
+++ b/cli/src/cli/generate/completion.rs
@@ -27,7 +27,7 @@ pub struct Completion {
     /// Include https://github.com/scop/bash-completion
     ///
     /// This is required for usage completions to work in bash, but the user may already provide it
-    #[usage(long)]
+    #[usage(long, verbatim_doc_comment)]
     include_bash_completion_lib: bool,
 
     /// Override the bin used for calling back to usage-cli
diff --git a/cli/src/cli/mcp.rs b/cli/src/cli/mcp.rs
index 65bec80b2..16eb50217 100644
--- a/cli/src/cli/mcp.rs
+++ b/cli/src/cli/mcp.rs
@@ -43,7 +43,7 @@ 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`.
 #[derive(Debug, usage_derive::Args)]
-#[usage(alias = "mcp-server", effect = "read")]
+#[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.
diff --git a/cli/src/cli/shell.rs b/cli/src/cli/shell.rs
index b2c1b9057..7506e9769 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -51,7 +51,7 @@ macro_rules! shell_command {
         #[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(unknown_flags = "value")]
+        #[usage(unknown_flags = "value", verbatim_doc_comment)]
         pub struct $ty {
             #[usage(flatten)]
             pub shell: Shell,

From 31e57d107cf2ccd1af104cf2aa92dcc952daa79f Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:25:36 +0000
Subject: [PATCH 05/13] refactor(cli): retain path value hints

---
 cli/src/cli/generate/fig.rs         |  2 +-
 cli/src/cli/generate/json_schema.rs |  2 +-
 cli/src/cli/generate/manpage.rs     |  7 +++++-
 cli/src/cli/generate/markdown.rs    | 10 ++++++--
 cli/usage.usage.kdl                 |  5 ++++
 docs/cli/reference/commands.json    | 36 +++++++++++++++++++++++++----
 6 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/cli/src/cli/generate/fig.rs b/cli/src/cli/generate/fig.rs
index a57560e6d..62b2c51e6 100644
--- a/cli/src/cli/generate/fig.rs
+++ b/cli/src/cli/generate/fig.rs
@@ -53,7 +53,7 @@ pub struct Fig {
     file: Option<PathBuf>,
 
     /// File path where the generated Fig spec will be saved, or "-" for stdout
-    #[usage(long, effect = "write")]
+    #[usage(long, value_hint = clap::ValueHint::FilePath, effect = "write")]
     out_file: Option<PathBuf>,
 
     /// Raw string spec input
diff --git a/cli/src/cli/generate/json_schema.rs b/cli/src/cli/generate/json_schema.rs
index 0627e2fee..25d20bb0b 100644
--- a/cli/src/cli/generate/json_schema.rs
+++ b/cli/src/cli/generate/json_schema.rs
@@ -15,7 +15,7 @@ pub struct JsonSchema {
     file: Option<PathBuf>,
 
     /// Write the schema here instead of to stdout
-    #[usage(long, effect = "write")]
+    #[usage(long, value_hint = clap::ValueHint::FilePath, effect = "write")]
     out_file: Option<PathBuf>,
 
     /// raw string spec input
diff --git a/cli/src/cli/generate/manpage.rs b/cli/src/cli/generate/manpage.rs
index 29fb772b7..0b195b1fb 100644
--- a/cli/src/cli/generate/manpage.rs
+++ b/cli/src/cli/generate/manpage.rs
@@ -13,7 +13,12 @@ pub struct Manpage {
     file: PathBuf,
 
     /// Output file path, or "-" for stdout (default)
-    #[usage(short, long, effect = "write")]
+    #[usage(
+        short,
+        long,
+        value_hint = clap::ValueHint::FilePath,
+        effect = "write"
+    )]
     out_file: Option<PathBuf>,
 
     /// Manual section number (default: 1)
diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs
index 8fab484b6..eab8c39b2 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -23,11 +23,17 @@ pub struct Markdown {
     html_encode: bool,
 
     /// Output markdown files to this directory (required when using --multi)
-    #[usage(long, requires = "--multi", required_if = "--multi", effect = "write")]
+    #[usage(
+        long,
+        value_hint = clap::ValueHint::DirPath,
+        requires = "--multi",
+        required_if = "--multi",
+        effect = "write"
+    )]
     out_dir: Option<PathBuf>,
 
     /// Output file path for single-file markdown generation, or "-" for stdout (default)
-    #[usage(long, effect = "write")]
+    #[usage(long, value_hint = clap::ValueHint::FilePath, effect = "write")]
     out_file: Option<PathBuf>,
 
     /// Replace `<pre>` tags with markdown code fences
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index b95de4e00..8a999cdfb 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -105,6 +105,7 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
         flag "--spec" help="Raw string spec input" overrides="--file" required_unless="--file" {
             arg "<SPEC>"
         }
+        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" {
@@ -130,6 +131,7 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
         flag "--url" help="Where the schema is published, for its `$id`" {
             arg "<URL>"
         }
+        complete "out_file" type="path"
     }
     cmd "manpage" help="Generate a manpage from a usage spec" effect="read" {
         alias "man"
@@ -143,6 +145,7 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
             long_help "Manual section number (default: 1)\n\nCommon sections:\n- 1: User commands\n- 5: File formats\n- 7: Miscellaneous\n- 8: System administration commands"
             arg "<SECTION>"
         }
+        complete "out_file" type="path"
     }
     cmd "markdown" help="Generate markdown documentation from usage specs" effect="read" {
         alias "md"
@@ -161,6 +164,8 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
         flag "--url-prefix" help="Prefix to add to all URLs" {
             arg "<URL_PREFIX>"
         }
+        complete "out_dir" type="dir"
+        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" {
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index d623dcfdb..f998a1afb 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -531,7 +531,13 @@
             "name": "fig",
             "aliases": [],
             "hidden_aliases": [],
-            "examples": []
+            "examples": [],
+            "complete": {
+              "out_file": {
+                "name": "out_file",
+                "type_": "path"
+              }
+            }
           },
           "go": {
             "full_cmd": ["generate", "go"],
@@ -776,7 +782,13 @@
             "name": "json-schema",
             "aliases": [],
             "hidden_aliases": [],
-            "examples": []
+            "examples": [],
+            "complete": {
+              "out_file": {
+                "name": "out_file",
+                "type_": "path"
+              }
+            }
           },
           "manpage": {
             "full_cmd": ["generate", "manpage"],
@@ -848,7 +860,13 @@
             "name": "manpage",
             "aliases": ["man"],
             "hidden_aliases": [],
-            "examples": []
+            "examples": [],
+            "complete": {
+              "out_file": {
+                "name": "out_file",
+                "type_": "path"
+              }
+            }
           },
           "markdown": {
             "full_cmd": ["generate", "markdown"],
@@ -969,7 +987,17 @@
             "name": "markdown",
             "aliases": ["md"],
             "hidden_aliases": [],
-            "examples": []
+            "examples": [],
+            "complete": {
+              "out_dir": {
+                "name": "out_dir",
+                "type_": "dir"
+              },
+              "out_file": {
+                "name": "out_file",
+                "type_": "path"
+              }
+            }
           },
           "sdk": {
             "full_cmd": ["generate", "sdk"],

From f25ef2d1ef4d14a96c4a5a2a743b8f97c2b3c704 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:25:36 +0000
Subject: [PATCH 06/13] refactor(cli): keep subcommands unboxed

---
 cli/src/cli/generate/mod.rs | 16 ++++++++--------
 cli/src/cli/mod.rs          | 18 +++++++++---------
 2 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/cli/src/cli/generate/mod.rs b/cli/src/cli/generate/mod.rs
index da4af4c36..4ea428e30 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -28,14 +28,14 @@ pub struct Generate {
 /// derive would let win: one description, in the file that owns the command.
 #[derive(usage_derive::Subcommands)]
 pub enum Command {
-    Completion(Box<completion::Completion>),
-    CompletionInit(Box<completion_init::CompletionInit>),
-    Fig(Box<fig::Fig>),
-    Json(Box<json::Json>),
-    JsonSchema(Box<json_schema::JsonSchema>),
-    Manpage(Box<manpage::Manpage>),
-    Markdown(Box<markdown::Markdown>),
-    Sdk(Box<sdk::Sdk>),
+    Completion(completion::Completion),
+    CompletionInit(completion_init::CompletionInit),
+    Fig(fig::Fig),
+    Json(json::Json),
+    JsonSchema(json_schema::JsonSchema),
+    Manpage(manpage::Manpage),
+    Markdown(markdown::Markdown),
+    Sdk(sdk::Sdk),
 }
 
 impl Generate {
diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index 7073b8fd0..37f0c525a 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -79,19 +79,19 @@ pub(crate) fn version() -> String {
 /// where a variant holds nothing and there is no struct to carry one.
 #[derive(Subcommands)]
 enum Command {
-    Bash(Box<shell::Bash>),
-    CompleteWord(Box<complete_word::CompleteWord>),
-    Exec(Box<exec::Exec>),
-    Fish(Box<shell::Fish>),
-    Generate(Box<generate::Generate>),
-    Lint(Box<lint::Lint>),
-    Mcp(Box<mcp::Mcp>),
+    Bash(shell::Bash),
+    CompleteWord(complete_word::CompleteWord),
+    Exec(exec::Exec),
+    Fish(shell::Fish),
+    Generate(generate::Generate),
+    Lint(lint::Lint),
+    Mcp(mcp::Mcp),
     #[usage(name = "powershell")]
-    PowerShell(Box<shell::PowerShell>),
+    PowerShell(shell::PowerShell),
     /// Show the companies sponsoring usage and the jdx.dev open source tools
     #[usage(effect = "read")]
     Sponsors,
-    Zsh(Box<shell::Zsh>),
+    Zsh(shell::Zsh),
 }
 
 impl Cli {

From 9e42beb9c4824503d52ae8560f2694c79c02825c Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:34:03 +0000
Subject: [PATCH 07/13] refactor(cli): handle parsed completions field

---
 cli/src/cli/mod.rs | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index 37f0c525a..a9b3bfd3f 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -39,17 +39,16 @@ pub struct Cli {
     command: Command,
 
     /// Outputs completions for the specified shell for completing the `usage` CLI itself
-    // Declaration only: `--completions <shell>` is 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 command line understood to answer. It is declared so that help, the spec and
-    // the completions know it exists.
+    // `--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`
+    // and the help, spec, and completions all read the same declaration.
     //
     // A flag, which is how it is typed. The clap declaration made it a *positional* — so the
     // spec, the docs and the generated completions all described a `[COMPLETIONS]` argument
     // that nothing accepts, while the flag that does work went undocumented. Carried over
     // faithfully at first, wrong included; the point of emitting the spec from the
     // declaration is that the two cannot disagree, so the declaration is what changes.
-    #[allow(dead_code)]
     #[usage(long)]
     completions: Option<String>,
 
@@ -120,6 +119,9 @@ impl Cli {
                 std::process::exit(2);
             }
         };
+        if let Some(shell) = cli.completions.as_deref() {
+            return crate::usage_spec::complete(shell);
+        }
         if cli.usage_spec {
             return crate::usage_spec::generate();
         }

From ffccbd8bf4ecfe31c8bfe20a06256bdb3416e427 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:41:38 +0000
Subject: [PATCH 08/13] refactor(cli): use usage value hints

---
 cli/src/cli/generate/fig.rs         | 6 +++++-
 cli/src/cli/generate/json_schema.rs | 6 +++++-
 cli/src/cli/generate/manpage.rs     | 2 +-
 cli/src/cli/generate/markdown.rs    | 8 ++++++--
 4 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/cli/src/cli/generate/fig.rs b/cli/src/cli/generate/fig.rs
index 62b2c51e6..a3ccb562b 100644
--- a/cli/src/cli/generate/fig.rs
+++ b/cli/src/cli/generate/fig.rs
@@ -53,7 +53,11 @@ pub struct Fig {
     file: Option<PathBuf>,
 
     /// File path where the generated Fig spec will be saved, or "-" for stdout
-    #[usage(long, value_hint = clap::ValueHint::FilePath, effect = "write")]
+    #[usage(
+        long,
+        value_hint = usage_argv::ValueHint::FilePath,
+        effect = "write"
+    )]
     out_file: Option<PathBuf>,
 
     /// Raw string spec input
diff --git a/cli/src/cli/generate/json_schema.rs b/cli/src/cli/generate/json_schema.rs
index 25d20bb0b..c717cc6ab 100644
--- a/cli/src/cli/generate/json_schema.rs
+++ b/cli/src/cli/generate/json_schema.rs
@@ -15,7 +15,11 @@ pub struct JsonSchema {
     file: Option<PathBuf>,
 
     /// Write the schema here instead of to stdout
-    #[usage(long, value_hint = clap::ValueHint::FilePath, effect = "write")]
+    #[usage(
+        long,
+        value_hint = usage_argv::ValueHint::FilePath,
+        effect = "write"
+    )]
     out_file: Option<PathBuf>,
 
     /// raw string spec input
diff --git a/cli/src/cli/generate/manpage.rs b/cli/src/cli/generate/manpage.rs
index 0b195b1fb..b4a5e7cc8 100644
--- a/cli/src/cli/generate/manpage.rs
+++ b/cli/src/cli/generate/manpage.rs
@@ -16,7 +16,7 @@ pub struct Manpage {
     #[usage(
         short,
         long,
-        value_hint = clap::ValueHint::FilePath,
+        value_hint = usage_argv::ValueHint::FilePath,
         effect = "write"
     )]
     out_file: Option<PathBuf>,
diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs
index eab8c39b2..90c974508 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -25,7 +25,7 @@ pub struct Markdown {
     /// Output markdown files to this directory (required when using --multi)
     #[usage(
         long,
-        value_hint = clap::ValueHint::DirPath,
+        value_hint = usage_argv::ValueHint::DirPath,
         requires = "--multi",
         required_if = "--multi",
         effect = "write"
@@ -33,7 +33,11 @@ pub struct Markdown {
     out_dir: Option<PathBuf>,
 
     /// Output file path for single-file markdown generation, or "-" for stdout (default)
-    #[usage(long, value_hint = clap::ValueHint::FilePath, effect = "write")]
+    #[usage(
+        long,
+        value_hint = usage_argv::ValueHint::FilePath,
+        effect = "write"
+    )]
     out_file: Option<PathBuf>,
 
     /// Replace `<pre>` tags with markdown code fences

From 017ce1828c6a1c6477a3e7edd2ed84f5e5d703c1 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:41:38 +0000
Subject: [PATCH 09/13] fix(cli): preserve shell help verbatim

---
 cli/assets/usage.1               | 32 ++++++++++++++++----------------
 cli/src/cli/shell.rs             | 14 +++++++++-----
 cli/src/test.rs                  | 23 ++++++++++++++++++++++-
 cli/usage.usage.kdl              |  8 ++++----
 docs/cli/reference/bash.md       |  6 +++---
 docs/cli/reference/commands.json |  8 ++++----
 docs/cli/reference/fish.md       |  6 +++---
 docs/cli/reference/powershell.md |  6 +++---
 docs/cli/reference/zsh.md        |  6 +++---
 9 files changed, 67 insertions(+), 42 deletions(-)

diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index 2acba63f2..9a196d358 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -16,7 +16,7 @@ Outputs a `usage.kdl` spec for this CLI itself
 .SH COMMANDS
 .TP
 \fBbash\fR
-Execute a shell script using bash
+Execute a shell script with the specified shell
 .TP
 \fBcomplete\-word\fR
 Generate shell completion candidates for a partial command line
@@ -31,7 +31,7 @@ Execute a script, parsing args and exposing them as environment variables
 .RE
 .TP
 \fBfish\fR
-Execute a shell script using fish
+Execute a shell script with the specified shell
 .TP
 \fBgenerate\fR
 Generate completions, documentation, and other artifacts from usage specs
@@ -88,20 +88,20 @@ Serve a usage spec over the Model Context Protocol
 .RE
 .TP
 \fBpowershell\fR
-Execute a shell script using PowerShell
+Execute a shell script with the specified shell
 .TP
 \fBsponsors\fR
 Show the companies sponsoring usage and the jdx.dev open source tools
 .TP
 \fBzsh\fR
-Execute a shell script using zsh
+Execute a shell script with the specified shell
 .SH "USAGE BASH"
-Execute a shell script using bash
+Execute a shell script with the specified shell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 .PP
 \fBUsage:\fR usage bash [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -175,12 +175,12 @@ path to script to execute
 \fB<ARGS>\fR
 arguments to pass to script
 .SH "USAGE FISH"
-Execute a shell script using fish
+Execute a shell script with the specified shell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 .PP
 \fBUsage:\fR usage fish [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -463,12 +463,12 @@ Usage spec file (not "\-": stdin is the MCP transport)
 \fB\-s, \-\-spec\fR \fI<SPEC>\fR
 Raw string spec input
 .SH "USAGE POWERSHELL"
-Execute a shell script using PowerShell
+Execute a shell script with the specified shell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 .PP
 \fBUsage:\fR usage powershell [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
@@ -489,12 +489,12 @@ Arguments to pass to 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 ZSH"
-Execute a shell script using zsh
+Execute a shell script with the specified shell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 .PP
 \fBUsage:\fR usage zsh [OPTIONS] <SCRIPT> [<ARGS>] ...
 .PP
diff --git a/cli/src/cli/shell.rs b/cli/src/cli/shell.rs
index 7506e9769..21f2e30dd 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -41,17 +41,21 @@ pub struct Shell {
 /// `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.
 macro_rules! shell_command {
-    ($ty:ident, $program:literal, $about:literal) => {
-        #[doc = $about]
+    ($ty:ident, $program:literal, $about:tt) => {
+        #[doc = "Execute a shell script with the specified shell"]
         #[doc = ""]
         #[doc = "Typically, this will be called by a script's shebang."]
         #[doc = ""]
-        #[doc = "If using `var=#true` on args/flags, they will be joined with spaces using"]
-        #[doc = "`shell_words::join()` to properly escape and quote values with spaces in them."]
+        #[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."]
         #[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(unknown_flags = "value", verbatim_doc_comment)]
+        #[usage(
+            about = $about,
+            unknown_flags = "value",
+            verbatim_doc_comment
+        )]
         pub struct $ty {
             #[usage(flatten)]
             pub shell: Shell,
diff --git a/cli/src/test.rs b/cli/src/test.rs
index 51d46154c..646c865d7 100644
--- a/cli/src/test.rs
+++ b/cli/src/test.rs
@@ -1,6 +1,27 @@
-use crate::env;
+use crate::{cli::Cli, env};
 
 #[ctor::ctor(unsafe)]
 fn init() {
     env::set_var("USAGE_BIN", "usage");
 }
+
+#[test]
+fn shell_commands_keep_their_verbatim_long_help() {
+    let bash = Cli::spec()
+        .root
+        .subcommands
+        .iter()
+        .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."
+        )
+    );
+}
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index 8a999cdfb..3ea42c49a 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -10,7 +10,7 @@ flag "--completions" help="Outputs completions for the specified shell for compl
 }
 flag "--usage-spec" help="Outputs a `usage.kdl` spec for this CLI itself"
 cmd "bash" help="Execute a shell script using bash" unknown_flags="value" {
-    long_help "Execute a shell script using bash\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
+    long_help "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."
     flag "-h" help="Show help"
     flag "--help" help="Show help"
     arg "<SCRIPT>"
@@ -46,7 +46,7 @@ cmd "exec" help="Execute a script, parsing args and exposing them as environment
     arg "[ARGS]..." help="arguments to pass to script"
 }
 cmd "fish" help="Execute a shell script using fish" unknown_flags="value" {
-    long_help "Execute a shell script using fish\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
+    long_help "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."
     flag "-h" help="Show help"
     flag "--help" help="Show help"
     arg "<SCRIPT>"
@@ -210,7 +210,7 @@ cmd "mcp" help="Serve a usage spec over the Model Context Protocol" effect="read
     }
 }
 cmd "powershell" help="Execute a shell script using PowerShell" unknown_flags="value" {
-    long_help "Execute a shell script using PowerShell\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
+    long_help "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."
     flag "-h" help="Show help"
     flag "--help" help="Show help"
     arg "<SCRIPT>"
@@ -221,7 +221,7 @@ cmd "powershell" help="Execute a shell script using PowerShell" unknown_flags="v
 cmd "sponsors" help="Show the companies sponsoring usage and the jdx.dev open source tools" effect="read" {
 }
 cmd "zsh" help="Execute a shell script using zsh" unknown_flags="value" {
-    long_help "Execute a shell script using zsh\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\n`shell_words::join()` to properly escape and quote values with spaces in them."
+    long_help "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."
     flag "-h" help="Show help"
     flag "--help" help="Show help"
     arg "<SCRIPT>"
diff --git a/docs/cli/reference/bash.md b/docs/cli/reference/bash.md
index 73097ff5b..b52b2ae06 100644
--- a/docs/cli/reference/bash.md
+++ b/docs/cli/reference/bash.md
@@ -5,12 +5,12 @@
 - **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 using bash
+Execute a shell script with the specified shell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 
 ## Arguments
 
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index f998a1afb..93a164098 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -55,7 +55,7 @@
         "unknown_flags": "value",
         "hide": false,
         "help": "Execute a shell script using bash",
-        "help_long": "Execute a shell script using bash\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\n`shell_words::join()` to properly escape and quote values with spaces in them.",
+        "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.",
         "name": "bash",
         "aliases": [],
         "hidden_aliases": [],
@@ -277,7 +277,7 @@
         "unknown_flags": "value",
         "hide": false,
         "help": "Execute a shell script using fish",
-        "help_long": "Execute a shell script using fish\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\n`shell_words::join()` to properly escape and quote values with spaces in them.",
+        "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.",
         "name": "fish",
         "aliases": [],
         "hidden_aliases": [],
@@ -1295,7 +1295,7 @@
         "unknown_flags": "value",
         "hide": false,
         "help": "Execute a shell script using PowerShell",
-        "help_long": "Execute a shell script using PowerShell\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\n`shell_words::join()` to properly escape and quote values with spaces in them.",
+        "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.",
         "name": "powershell",
         "aliases": [],
         "hidden_aliases": [],
@@ -1367,7 +1367,7 @@
         "unknown_flags": "value",
         "hide": false,
         "help": "Execute a shell script using zsh",
-        "help_long": "Execute a shell script using zsh\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\n`shell_words::join()` to properly escape and quote values with spaces in them.",
+        "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.",
         "name": "zsh",
         "aliases": [],
         "hidden_aliases": [],
diff --git a/docs/cli/reference/fish.md b/docs/cli/reference/fish.md
index c6d06106b..5bf1b6d4a 100644
--- a/docs/cli/reference/fish.md
+++ b/docs/cli/reference/fish.md
@@ -5,12 +5,12 @@
 - **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 using fish
+Execute a shell script with the specified shell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 
 ## Arguments
 
diff --git a/docs/cli/reference/powershell.md b/docs/cli/reference/powershell.md
index 64abd928a..89efeb45d 100644
--- a/docs/cli/reference/powershell.md
+++ b/docs/cli/reference/powershell.md
@@ -5,12 +5,12 @@
 - **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 using PowerShell
+Execute a shell script with the specified shell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 
 ## Arguments
 
diff --git a/docs/cli/reference/zsh.md b/docs/cli/reference/zsh.md
index 7a3d42d2d..42136601b 100644
--- a/docs/cli/reference/zsh.md
+++ b/docs/cli/reference/zsh.md
@@ -5,12 +5,12 @@
 - **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 using zsh
+Execute a shell script with the specified shell
 
 Typically, this will be called by a script's shebang.
 
-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.
+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.
 
 ## Arguments
 

From cdd5cad70d4294e21697f06c6761a6751b8870b8 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 04:38:18 +0000
Subject: [PATCH 10/13] refactor(cli): migrate go generator

---
 cli/assets/usage.1                |  6 ++++--
 cli/src/cli/generate/go.rs        | 17 +++++++++++------
 cli/src/cli/generate/mod.rs       |  3 +++
 cli/src/command_effects.rs        |  7 ++++++-
 cli/usage.usage.kdl               | 16 ++++++++++++++++
 docs/cli/reference/commands.json  | 16 ++++++++++++----
 docs/cli/reference/generate/go.md |  4 +++-
 7 files changed, 55 insertions(+), 14 deletions(-)

diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index 9a196d358..4d18f6600 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -288,9 +288,11 @@ Raw string spec input
 .SH "USAGE GENERATE GO"
 Generate Go parse tables from a usage spec
 
-The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a Rust CLI gets from a derive at compile time, a Go CLI gets from this at build time — typically from a `go:generate` line:
+The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what
+a Rust CLI gets from a derive at compile time, a Go CLI gets from this at build
+time — typically from a `go:generate` line:
 
-//go:generate usage generate go \-f mycli.usage.kdl \-o tables.go
+  //go:generate usage generate go \-f mycli.usage.kdl \-o tables.go
 .PP
 \fBUsage:\fR usage generate go [OPTIONS]
 .PP
diff --git a/cli/src/cli/generate/go.rs b/cli/src/cli/generate/go.rs
index 060fb85df..9685519b5 100644
--- a/cli/src/cli/generate/go.rs
+++ b/cli/src/cli/generate/go.rs
@@ -1,8 +1,8 @@
 use std::path::PathBuf;
 
-use clap::Args;
 use miette::Result;
 use usage::go::GoOptions;
+use usage_derive::Args;
 
 use crate::cli::generate;
 
@@ -14,22 +14,27 @@ use crate::cli::generate;
 ///
 ///   //go:generate usage generate go -f mycli.usage.kdl -o tables.go
 #[derive(Args)]
-#[clap()]
+#[usage(effect = "read")]
 pub struct Go {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// File path where the generated Go source will be saved, or "-" for stdout
-    #[clap(short, long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(
+        short,
+        long,
+        value_hint = usage_argv::ValueHint::FilePath,
+        effect = "write"
+    )]
     out_file: Option<PathBuf>,
 
     /// Go package clause for the generated file (defaults to the spec's bin name)
-    #[clap(short, long)]
+    #[usage(short, long)]
     package: Option<String>,
 
     /// Raw string spec input
-    #[clap(long, required_unless_present = "file", overrides_with = "file")]
+    #[usage(long, required_unless = "--file", overrides = "--file")]
     spec: Option<String>,
 }
 
diff --git a/cli/src/cli/generate/mod.rs b/cli/src/cli/generate/mod.rs
index 4ea428e30..b5abc095b 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -7,6 +7,7 @@ use usage::Spec;
 mod completion;
 mod completion_init;
 mod fig;
+mod go;
 mod json;
 mod json_schema;
 mod manpage;
@@ -31,6 +32,7 @@ pub enum Command {
     Completion(completion::Completion),
     CompletionInit(completion_init::CompletionInit),
     Fig(fig::Fig),
+    Go(go::Go),
     Json(json::Json),
     JsonSchema(json_schema::JsonSchema),
     Manpage(manpage::Manpage),
@@ -44,6 +46,7 @@ impl Generate {
             Command::Completion(cmd) => cmd.run(),
             Command::CompletionInit(cmd) => cmd.run(),
             Command::Fig(cmd) => cmd.run(),
+            Command::Go(cmd) => cmd.run(),
             Command::Json(cmd) => cmd.run(),
             Command::JsonSchema(cmd) => cmd.run(),
             Command::Manpage(cmd) => cmd.run(),
diff --git a/cli/src/command_effects.rs b/cli/src/command_effects.rs
index 2342d36ff..89160dec5 100644
--- a/cli/src/command_effects.rs
+++ b/cli/src/command_effects.rs
@@ -119,7 +119,12 @@ mod tests {
         // The four generators that print to stdout unless told otherwise. Kept as one list
         // because the risk is a new `--out-file` arriving without an effect, which reads to
         // an agent as a command that only ever prints.
-        for path in ["generate fig", "generate json-schema", "generate manpage"] {
+        for path in [
+            "generate fig",
+            "generate go",
+            "generate json-schema",
+            "generate manpage",
+        ] {
             let cmd = find(path).unwrap_or_else(|| panic!("no such command: {path}"));
             let out_file = cmd
                 .flags
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index 3ea42c49a..338f21fae 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -107,6 +107,22 @@ cmd "generate" help="Generate completions, documentation, and other artifacts fr
         }
         complete "out_file" type="path"
     }
+    cmd "go" help="Generate Go parse tables from a usage spec" effect="read" {
+        long_help "Generate Go parse tables from a usage spec\n\nThe tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what\na Rust CLI gets from a derive at compile time, a Go CLI gets from this at build\ntime — typically from a `go:generate` line:\n\n  //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" {
+            arg "<FILE>"
+        }
+        flag "-o --out-file" help="File path where the generated Go source will be saved, or \"-\" for stdout" 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" {
+            arg "<SPEC>"
+        }
+        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" {
             arg "<FILE>"
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index 93a164098..1a7e664e1 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -604,6 +604,7 @@
                 "help_first_line": "Raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -612,19 +613,26 @@
                   "required": true,
                   "double_dash": "Optional",
                   "hide": false
-                }
+                },
+                "overrides": ["--file"]
               }
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "help": "Generate Go parse tables from a usage spec",
-            "help_long": "Generate Go parse tables from a usage spec\n\nThe tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a Rust CLI gets from a derive at compile time, a Go CLI gets from this at build time — typically from a `go:generate` line:\n\n//go:generate usage generate go -f mycli.usage.kdl -o tables.go",
+            "help_long": "Generate Go parse tables from a usage spec\n\nThe tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what\na Rust CLI gets from a derive at compile time, a Go CLI gets from this at build\ntime — typically from a `go:generate` line:\n\n  //go:generate usage generate go -f mycli.usage.kdl -o tables.go",
             "name": "go",
             "aliases": [],
             "hidden_aliases": [],
-            "examples": []
+            "examples": [],
+            "complete": {
+              "out_file": {
+                "name": "out_file",
+                "type_": "path"
+              }
+            }
           },
           "json": {
             "full_cmd": ["generate", "json"],
diff --git a/docs/cli/reference/generate/go.md b/docs/cli/reference/generate/go.md
index 78333b9be..5b203d817 100644
--- a/docs/cli/reference/generate/go.md
+++ b/docs/cli/reference/generate/go.md
@@ -8,7 +8,9 @@
 
 Generate Go parse tables from a usage spec
 
-The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a Rust CLI gets from a derive at compile time, a Go CLI gets from this at build time — typically from a `go:generate` line:
+The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what
+a Rust CLI gets from a derive at compile time, a Go CLI gets from this at build
+time — typically from a `go:generate` line:
 
 //go:generate usage generate go -f mycli.usage.kdl -o tables.go
 

From 21f255b9811c00525fdb7cd347c07fac95a23a03 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 10:23:42 +0000
Subject: [PATCH 11/13] refactor(cli): use usage-rs facade

---
 Cargo.lock                              |  3 +--
 cli/Cargo.toml                          | 10 ++++------
 cli/src/cli/complete_word.rs            |  2 +-
 cli/src/cli/exec.rs                     |  2 +-
 cli/src/cli/generate/completion.rs      |  2 +-
 cli/src/cli/generate/completion_init.rs |  2 +-
 cli/src/cli/generate/fig.rs             |  4 ++--
 cli/src/cli/generate/go.rs              |  4 ++--
 cli/src/cli/generate/json.rs            |  2 +-
 cli/src/cli/generate/json_schema.rs     |  4 ++--
 cli/src/cli/generate/manpage.rs         |  4 ++--
 cli/src/cli/generate/markdown.rs        |  6 +++---
 cli/src/cli/generate/mod.rs             |  4 ++--
 cli/src/cli/generate/sdk.rs             |  2 +-
 cli/src/cli/lint.rs                     |  4 ++--
 cli/src/cli/mcp.rs                      |  2 +-
 cli/src/cli/mod.rs                      | 10 +++++-----
 cli/src/cli/shell.rs                    |  2 +-
 cli/src/command_effects.rs              |  2 +-
 19 files changed, 34 insertions(+), 37 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 1172b5a4a..16e88979c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2099,9 +2099,8 @@ dependencies = [
  "tera",
  "thiserror",
  "tokio",
- "usage-argv",
- "usage-derive",
  "usage-lib",
+ "usage-rs",
  "xx",
 ]
 
diff --git a/cli/Cargo.toml b/cli/Cargo.toml
index ecff73933..2ddc98c3f 100644
--- a/cli/Cargo.toml
+++ b/cli/Cargo.toml
@@ -41,12 +41,10 @@ serde_with = "3"
 tera = "2"
 thiserror = "2"
 tokio = { version = "1", features = ["rt", "macros", "io-std"] }
-# The CLI is its own first adopter: `usage` parses its own command line with the
-# parser it ships. `spec` because `--usage-spec` emits this CLI's own KDL, and
-# `diagnostics` because a person types these commands and has to be told what
-# went wrong.
-usage-argv = { workspace = true, features = ["spec", "diagnostics"] }
-usage-derive = { workspace = true }
+# The CLI is the facade's first adopter: `usage` parses its own command line with
+# the parser it ships. `diagnostics` includes spec emission for `--usage-spec` and
+# the errors a person needs when a command line does not parse.
+usage-rs = { workspace = true, features = ["diagnostics"] }
 usage-lib = { workspace = true, features = ["clap", "docs", "unstable_choices_env"] }
 xx = "2"
 
diff --git a/cli/src/cli/complete_word.rs b/cli/src/cli/complete_word.rs
index 3adcd6faa..17db39aea 100644
--- a/cli/src/cli/complete_word.rs
+++ b/cli/src/cli/complete_word.rs
@@ -7,7 +7,7 @@ use std::sync::Arc;
 use itertools::Itertools;
 use miette::IntoDiagnostic;
 use std::sync::LazyLock;
-use usage_derive::Args;
+use usage_rs::Args;
 use xx::regex;
 
 use usage::parse::{ParseOutput, ParseValue};
diff --git a/cli/src/cli/exec.rs b/cli/src/cli/exec.rs
index 333d2bea4..ef525290c 100644
--- a/cli/src/cli/exec.rs
+++ b/cli/src/cli/exec.rs
@@ -4,7 +4,7 @@ use std::process::Stdio;
 
 use itertools::Itertools;
 use miette::IntoDiagnostic;
-use usage_derive::Args;
+use usage_rs::Args;
 
 use usage::Spec;
 
diff --git a/cli/src/cli/generate/completion.rs b/cli/src/cli/generate/completion.rs
index 90b7f9be9..4d2449039 100644
--- a/cli/src/cli/generate/completion.rs
+++ b/cli/src/cli/generate/completion.rs
@@ -1,7 +1,7 @@
 use std::path::PathBuf;
 use usage::complete::CompleteOptions;
 use usage::Spec;
-use usage_derive::Args;
+use usage_rs::Args;
 
 use super::parse_file_or_stdin;
 
diff --git a/cli/src/cli/generate/completion_init.rs b/cli/src/cli/generate/completion_init.rs
index b406111d1..66e273268 100644
--- a/cli/src/cli/generate/completion_init.rs
+++ b/cli/src/cli/generate/completion_init.rs
@@ -1,5 +1,5 @@
 use usage::complete::complete_init;
-use usage_derive::Args;
+use usage_rs::Args;
 
 /// Generate a shell init script that auto-completes any usage shebang script on $PATH
 ///
diff --git a/cli/src/cli/generate/fig.rs b/cli/src/cli/generate/fig.rs
index a3ccb562b..b41486f87 100644
--- a/cli/src/cli/generate/fig.rs
+++ b/cli/src/cli/generate/fig.rs
@@ -4,7 +4,7 @@ use std::vec;
 use indexmap::IndexMap;
 use itertools::Itertools;
 use usage::{SpecArg, SpecCommand, SpecComplete, SpecFlag};
-use usage_derive::Args;
+use usage_rs::Args;
 
 use crate::cli::generate;
 use serde::{Deserialize, Serialize, Serializer};
@@ -55,7 +55,7 @@ pub struct Fig {
     /// File path where the generated Fig spec will be saved, or "-" for stdout
     #[usage(
         long,
-        value_hint = usage_argv::ValueHint::FilePath,
+        value_hint = usage_rs::ValueHint::FilePath,
         effect = "write"
     )]
     out_file: Option<PathBuf>,
diff --git a/cli/src/cli/generate/go.rs b/cli/src/cli/generate/go.rs
index 9685519b5..76bfb7c47 100644
--- a/cli/src/cli/generate/go.rs
+++ b/cli/src/cli/generate/go.rs
@@ -2,7 +2,7 @@ use std::path::PathBuf;
 
 use miette::Result;
 use usage::go::GoOptions;
-use usage_derive::Args;
+use usage_rs::Args;
 
 use crate::cli::generate;
 
@@ -24,7 +24,7 @@ pub struct Go {
     #[usage(
         short,
         long,
-        value_hint = usage_argv::ValueHint::FilePath,
+        value_hint = usage_rs::ValueHint::FilePath,
         effect = "write"
     )]
     out_file: Option<PathBuf>,
diff --git a/cli/src/cli/generate/json.rs b/cli/src/cli/generate/json.rs
index 22fe5c2e7..71e3b601a 100644
--- a/cli/src/cli/generate/json.rs
+++ b/cli/src/cli/generate/json.rs
@@ -4,7 +4,7 @@ use miette::IntoDiagnostic;
 use std::path::PathBuf;
 
 /// Outputs a usage spec in json format
-#[derive(usage_derive::Args)]
+#[derive(usage_rs::Args)]
 #[usage(effect = "read")]
 pub struct Json {
     /// A usage spec taken in as a file, use "-" to read from stdin
diff --git a/cli/src/cli/generate/json_schema.rs b/cli/src/cli/generate/json_schema.rs
index c717cc6ab..ae5053918 100644
--- a/cli/src/cli/generate/json_schema.rs
+++ b/cli/src/cli/generate/json_schema.rs
@@ -7,7 +7,7 @@ use crate::schema::{config_schema, SchemaOptions};
 use crate::Result;
 
 /// Generate a JSON Schema for a CLI's config file from its usage spec
-#[derive(usage_derive::Args)]
+#[derive(usage_rs::Args)]
 #[usage(effect = "read")]
 pub struct JsonSchema {
     /// A usage spec taken in as a file, use "-" to read from stdin
@@ -17,7 +17,7 @@ pub struct JsonSchema {
     /// Write the schema here instead of to stdout
     #[usage(
         long,
-        value_hint = usage_argv::ValueHint::FilePath,
+        value_hint = usage_rs::ValueHint::FilePath,
         effect = "write"
     )]
     out_file: Option<PathBuf>,
diff --git a/cli/src/cli/generate/manpage.rs b/cli/src/cli/generate/manpage.rs
index b4a5e7cc8..4e03cf388 100644
--- a/cli/src/cli/generate/manpage.rs
+++ b/cli/src/cli/generate/manpage.rs
@@ -2,7 +2,7 @@ use std::path::PathBuf;
 
 use super::{parse_file_or_stdin, write_or_stdout};
 use usage::docs::manpage::ManpageRenderer;
-use usage_derive::Args;
+use usage_rs::Args;
 
 /// Generate a manpage from a usage spec
 #[derive(Args)]
@@ -16,7 +16,7 @@ pub struct Manpage {
     #[usage(
         short,
         long,
-        value_hint = usage_argv::ValueHint::FilePath,
+        value_hint = usage_rs::ValueHint::FilePath,
         effect = "write"
     )]
     out_file: Option<PathBuf>,
diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs
index 90c974508..5a69e44cc 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -2,7 +2,7 @@ use std::path::PathBuf;
 
 use super::{parse_file_or_stdin, write_or_stdout};
 use usage::docs::markdown::MarkdownRenderer;
-use usage_derive::Args;
+use usage_rs::Args;
 
 /// Generate markdown documentation from usage specs
 #[derive(Args)]
@@ -25,7 +25,7 @@ pub struct Markdown {
     /// Output markdown files to this directory (required when using --multi)
     #[usage(
         long,
-        value_hint = usage_argv::ValueHint::DirPath,
+        value_hint = usage_rs::ValueHint::DirPath,
         requires = "--multi",
         required_if = "--multi",
         effect = "write"
@@ -35,7 +35,7 @@ pub struct Markdown {
     /// Output file path for single-file markdown generation, or "-" for stdout (default)
     #[usage(
         long,
-        value_hint = usage_argv::ValueHint::FilePath,
+        value_hint = usage_rs::ValueHint::FilePath,
         effect = "write"
     )]
     out_file: Option<PathBuf>,
diff --git a/cli/src/cli/generate/mod.rs b/cli/src/cli/generate/mod.rs
index b5abc095b..b6353f1bc 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -16,7 +16,7 @@ mod sdk;
 
 /// Generate completions, documentation, and other artifacts from usage specs
 // Cannot run alone, and every child starts at `read`, so the parent is `read` too.
-#[derive(usage_derive::Args)]
+#[derive(usage_rs::Args)]
 #[usage(alias = "g", effect = "read")]
 pub struct Generate {
     #[usage(subcommand)]
@@ -27,7 +27,7 @@ pub struct Generate {
 ///
 /// Each command's help is its struct's doc comment rather than a second one here, which the
 /// derive would let win: one description, in the file that owns the command.
-#[derive(usage_derive::Subcommands)]
+#[derive(usage_rs::Subcommands)]
 pub enum Command {
     Completion(completion::Completion),
     CompletionInit(completion_init::CompletionInit),
diff --git a/cli/src/cli/generate/sdk.rs b/cli/src/cli/generate/sdk.rs
index 3e8647a69..6fced9eb6 100644
--- a/cli/src/cli/generate/sdk.rs
+++ b/cli/src/cli/generate/sdk.rs
@@ -1,6 +1,6 @@
 use std::path::PathBuf;
 
-use usage_derive::Args;
+use usage_rs::Args;
 
 use crate::cli::generate;
 
diff --git a/cli/src/cli/lint.rs b/cli/src/cli/lint.rs
index e60628944..1e4a75bcb 100644
--- a/cli/src/cli/lint.rs
+++ b/cli/src/cli/lint.rs
@@ -5,7 +5,7 @@ use usage::{Spec, SpecArg, SpecCommand, SpecFlag};
 use crate::cli::generate::parse_file_or_stdin;
 
 /// Lint a usage spec file for common issues
-#[derive(usage_derive::Args)]
+#[derive(usage_rs::Args)]
 #[usage(effect = "read")]
 pub struct Lint {
     /// A usage spec file to lint, use "-" to read from stdin
@@ -35,7 +35,7 @@ pub struct LintOptions {
     pub sorted: bool,
 }
 
-#[derive(Clone, Copy, Default, usage_derive::ValueEnum)]
+#[derive(Clone, Copy, Default, usage_rs::ValueEnum)]
 enum OutputFormat {
     #[default]
     Text,
diff --git a/cli/src/cli/mcp.rs b/cli/src/cli/mcp.rs
index 16eb50217..b23b8c989 100644
--- a/cli/src/cli/mcp.rs
+++ b/cli/src/cli/mcp.rs
@@ -42,7 +42,7 @@ 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`.
-#[derive(Debug, usage_derive::Args)]
+#[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
diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index a9b3bfd3f..06e5f0bea 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -1,7 +1,7 @@
 use std::ffi::OsStr;
 
 use miette::Result;
-use usage_derive::{Cli as DeriveCli, Subcommands};
+use usage_rs::{Cli as DeriveCli, Subcommands};
 
 pub mod complete_word;
 mod exec;
@@ -102,18 +102,18 @@ impl Cli {
         let cli = match Self::parse_from(&words) {
             Ok(cli) => cli,
             // Not failures: someone asked a question, and the answer goes to stdout.
-            Err(usage_argv::Error::Help { cmd, long }) => {
-                if let Some(page) = usage_argv::help::render(Self::spec(), cmd, long) {
+            Err(usage_rs::Error::Help { cmd, long }) => {
+                if let Some(page) = usage_rs::help::render(Self::spec(), cmd, long) {
                     print!("{page}");
                 }
                 return Ok(());
             }
-            Err(usage_argv::Error::Version) => {
+            Err(usage_rs::Error::Version) => {
                 println!("{}", version());
                 return Ok(());
             }
             Err(err) => {
-                eprint!("{}", usage_argv::render_failure(Self::spec(), &words, &err));
+                eprint!("{}", usage_rs::render_failure(Self::spec(), &words, &err));
                 // clap's status for a command line it could not parse, which is what the
                 // scripts that call this have been checking for.
                 std::process::exit(2);
diff --git a/cli/src/cli/shell.rs b/cli/src/cli/shell.rs
index 21f2e30dd..3f308fd3c 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -4,7 +4,7 @@ use std::process::Stdio;
 
 use itertools::Itertools;
 use miette::IntoDiagnostic;
-use usage_derive::Args;
+use usage_rs::Args;
 
 use usage::Spec;
 
diff --git a/cli/src/command_effects.rs b/cli/src/command_effects.rs
index 89160dec5..091a28bfd 100644
--- a/cli/src/command_effects.rs
+++ b/cli/src/command_effects.rs
@@ -37,7 +37,7 @@ const UNCLASSIFIED: &[(&str, &str)] = &[
 mod tests {
     use super::*;
     use std::collections::HashSet;
-    use usage_argv::spec::{CommandMeta, Effect};
+    use usage_rs::spec::{CommandMeta, Effect};
 
     use crate::cli::Cli;
 

From 5613ea1ea2b39cf1cdefdcf3bb4ec3b0eb4a6188 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 10:33:41 +0000
Subject: [PATCH 12/13] fix(manpage): render explicit usage alternatives

---
 argv/src/spec.rs                              |  7 +++++
 cli/assets/usage.1                            |  4 ++-
 cli/src/cli/mod.rs                            |  1 +
 .../manpage__generate_manpage_with_flags.snap |  2 +-
 ...anpage__manpage_output_first_50_lines.snap |  2 +-
 cli/usage.usage.kdl                           |  1 +
 conformance/tests/spec_roundtrip.rs           |  4 +++
 derive/src/codegen.rs                         |  2 ++
 derive/src/model.rs                           |  6 +++-
 docs/cli/reference/commands.json              |  2 +-
 lib/src/docs/manpage/renderer.rs              | 28 +++++++++++++++++++
 11 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/argv/src/spec.rs b/argv/src/spec.rs
index 4335b5ac0..57734d06a 100644
--- a/argv/src/spec.rs
+++ b/argv/src/spec.rs
@@ -269,6 +269,9 @@ pub struct Spec<'a> {
     pub min_usage_version: Option<&'a str>,
     pub about: Option<&'a str>,
     pub long_about: Option<&'a str>,
+    /// An exact usage synopsis, including the `Usage:` prefix, when the generated
+    /// shape needs alternatives that cannot be inferred from one command grammar.
+    pub usage: Option<&'a str>,
     /// Which command the root falls back to when a word matches no subcommand.
     /// mise uses this so `mise foo` completes as `mise run foo`.
     pub default_subcommand: Option<&'a str>,
@@ -293,6 +296,7 @@ impl Spec<'_> {
         min_usage_version: None,
         about: None,
         long_about: None,
+        usage: None,
         default_subcommand: None,
         root: &CommandMeta::EMPTY,
     };
@@ -672,6 +676,9 @@ impl Spec<'_> {
         if let Some(long_about) = self.long_about.or(self.root.long_about) {
             prop(out, "long_about", long_about)?;
         }
+        if let Some(usage) = self.usage {
+            prop(out, "usage", usage)?;
+        }
         // Written only when it is not the default, so an ordinary spec stays quiet
         // about it.
         if self.root.cmd.unknown_flags == Some(UnknownFlags::Error) {
diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index 4d18f6600..e9520ae18 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -2,7 +2,9 @@
 .SH NAME
 usage \- CLI for working with usage\-based CLIs
 .SH SYNOPSIS
-\fBusage\fR [OPTIONS] [COMMAND]
+\fBusage\fR <COMMAND>
+\fBusage\fR \-\-completions <COMPLETIONS>
+\fBusage\fR \-\-usage\-spec
 .SH DESCRIPTION
 CLI for working with usage\-based CLIs
 .PP
diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index 06e5f0bea..ff52eb860 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -25,6 +25,7 @@ mod sponsors;
     bin = "usage",
     version,
     min_usage_version = "4.0",
+    usage = "Usage: usage <COMMAND>\n       usage --completions <COMPLETIONS>\n       usage --usage-spec",
     // Every flag `usage` accepts is one it declares, so an unrecognised one is a mistake and
     // saying so beats offering it to a positional — `usage lint --nope f.kdl` would otherwise
     // make `--nope` the file and call the real file unexpected.
diff --git a/cli/tests/snapshots/manpage__generate_manpage_with_flags.snap b/cli/tests/snapshots/manpage__generate_manpage_with_flags.snap
index 71f061814..5817627df 100644
--- a/cli/tests/snapshots/manpage__generate_manpage_with_flags.snap
+++ b/cli/tests/snapshots/manpage__generate_manpage_with_flags.snap
@@ -6,7 +6,7 @@ expression: stdout
 .SH NAME
 mise \- The front\-end to your dev env
 .SH SYNOPSIS
-\fBmise\fR [OPTIONS] [<TASK>] [<TASK_ARGS>] ... [<TASK_ARGS_LAST>] ... [COMMAND]
+\fBmise\fR [OPTIONS] [TASK] [COMMAND]
 .SH DESCRIPTION
 mise is a tool for managing runtime versions. https://github.com/jdx/mise
 .PP
diff --git a/cli/tests/snapshots/manpage__manpage_output_first_50_lines.snap b/cli/tests/snapshots/manpage__manpage_output_first_50_lines.snap
index a5324e146..a2ed24fe2 100644
--- a/cli/tests/snapshots/manpage__manpage_output_first_50_lines.snap
+++ b/cli/tests/snapshots/manpage__manpage_output_first_50_lines.snap
@@ -6,7 +6,7 @@ expression: "first_lines.join(\"\\n\")"
 .SH NAME
 mise \- The front\-end to your dev env
 .SH SYNOPSIS
-\fBmise\fR [OPTIONS] [<TASK>] [<TASK_ARGS>] ... [<TASK_ARGS_LAST>] ... [COMMAND]
+\fBmise\fR [OPTIONS] [TASK] [COMMAND]
 .SH DESCRIPTION
 mise is a tool for managing runtime versions. https://github.com/jdx/mise
 .PP
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index 338f21fae..3103e54b1 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -4,6 +4,7 @@ name "usage"
 bin "usage"
 version "5.1.0"
 about "CLI for working with usage-based CLIs"
+usage "Usage: usage <COMMAND>\n       usage --completions <COMPLETIONS>\n       usage --usage-spec"
 unknown_flags "error"
 flag "--completions" help="Outputs completions for the specified shell for completing the `usage` CLI itself" {
     arg "<COMPLETIONS>"
diff --git a/conformance/tests/spec_roundtrip.rs b/conformance/tests/spec_roundtrip.rs
index 15fef1db6..f6d3539ea 100644
--- a/conformance/tests/spec_roundtrip.rs
+++ b/conformance/tests/spec_roundtrip.rs
@@ -325,6 +325,7 @@ static SPEC: Spec = Spec {
     min_usage_version: None,
     about: Some("does things"),
     long_about: Some("Does things, at length."),
+    usage: None,
     default_subcommand: Some("run"),
     root: &ROOT_META,
 };
@@ -755,6 +756,7 @@ fn a_declared_completer_becomes_a_run_the_reference_can_read() {
         min_usage_version: None,
         about: None,
         long_about: None,
+        usage: None,
         default_subcommand: None,
         root: &META,
     };
@@ -886,6 +888,7 @@ fn two_commands_can_mean_different_things_by_one_name() {
         min_usage_version: None,
         about: None,
         long_about: None,
+        usage: None,
         default_subcommand: None,
         root: &ROOT_META_TWO,
     };
@@ -938,6 +941,7 @@ fn two_commands_can_mean_different_things_by_one_name() {
         min_usage_version: None,
         about: None,
         long_about: None,
+        usage: None,
         default_subcommand: None,
         root: &ROOT_META_THREE,
     };
diff --git a/derive/src/codegen.rs b/derive/src/codegen.rs
index 806490527..6036c545c 100644
--- a/derive/src/codegen.rs
+++ b/derive/src/codegen.rs
@@ -86,6 +86,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
     let unknown_flags = unknown_flags_tokens(cli);
 
     let default_subcommand = option_str(cli.default_subcommand.as_deref());
+    let usage = option_str(cli.usage.as_deref());
     let restart_token = option_str(cli.restart_token.as_deref());
     let mount = option_str(cli.mount.as_deref());
     // A bare `T` subcommand field says the command cannot run alone; an `Option<T>` says it
@@ -397,6 +398,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
                 min_usage_version: #min_usage_version,
                 about: #about,
                 long_about: #long_about,
+                usage: #usage,
                 default_subcommand: #default_subcommand,
                 root: &ROOT_META,
             };
diff --git a/derive/src/model.rs b/derive/src/model.rs
index 0a138835f..0363bf8f3 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -49,6 +49,8 @@ pub struct Cli {
     /// produces a spec claiming to be readable by a `usage` that chokes on it, which is worse
     /// than saying nothing. The CLI knows which consumers it has to keep working.
     pub min_usage_version: Option<String>,
+    /// An exact usage synopsis for shapes with explicit alternatives.
+    pub usage: Option<String>,
     /// What running this command does to the world, when it says.
     ///
     /// Held as the tokens for an `Option<Effect>`, since the only thing it becomes is a field of
@@ -376,6 +378,7 @@ impl Cli {
             completion: false,
             settings: false,
             min_usage_version: None,
+            usage: None,
             effect: None,
             aliases: Vec::new(),
             hidden_aliases: Vec::new(),
@@ -419,6 +422,7 @@ impl Cli {
                     "alias" => cli.aliases.extend(selectors(&meta)?),
                     "alias_hidden" => cli.hidden_aliases.extend(selectors(&meta)?),
                     "min_usage_version" => cli.min_usage_version = Some(string_value(&meta)?),
+                    "usage" => cli.usage = Some(string_value(&meta)?),
                     "version" => {
                         cli.version = Some(match &meta {
                             // `version` on its own: whatever the adopter's package says.
@@ -468,7 +472,7 @@ impl Cli {
                             path,
                             format!(
                                 "unknown option `{other}` on a struct; usage::Cli takes \
-                                 `name`, `bin`, `version`, `verbatim_doc_comment`, `unknown_flags`, \
+                                 `name`, `bin`, `version`, `usage`, `verbatim_doc_comment`, `unknown_flags`, \
                                  `default_subcommand`, `restart_token`, and `mount` here, \
                                  and the description comes from the doc comment"
                             ),
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index 1a7e664e1..b1ab399ac 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -1426,7 +1426,7 @@
     "files": []
   },
   "version": "5.1.0",
-  "usage": "",
+  "usage": "Usage: usage <COMMAND>\n       usage --completions <COMPLETIONS>\n       usage --usage-spec",
   "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",
diff --git a/lib/src/docs/manpage/renderer.rs b/lib/src/docs/manpage/renderer.rs
index dfc534b34..17c3d2481 100644
--- a/lib/src/docs/manpage/renderer.rs
+++ b/lib/src/docs/manpage/renderer.rs
@@ -195,6 +195,18 @@ impl ManpageRenderer {
     fn render_synopsis(&self, roff: &mut Roff) {
         roff.control("SH", ["SYNOPSIS"]);
 
+        if !self.spec.usage.trim().is_empty() {
+            for line in self.spec.usage.lines() {
+                let line = line.trim().strip_prefix("Usage: ").unwrap_or(line.trim());
+                if let Some(rest) = line.strip_prefix(&self.spec.bin) {
+                    roff.text([bold(&self.spec.bin), roman(rest)]);
+                } else {
+                    roff.text([roman(line)]);
+                }
+            }
+            return;
+        }
+
         let synopsis = self.build_synopsis(&self.spec.cmd, &self.spec.bin);
         roff.text([bold(&self.spec.bin), roman(" "), roman(&synopsis)]);
     }
@@ -597,6 +609,22 @@ config {
         assert!(!page.contains("CONFIGURATION"), "{page}");
     }
 
+    #[test]
+    fn an_explicit_usage_renders_each_alternative_in_the_synopsis() {
+        let spec: Spec = r#"
+name "ex"
+bin "ex"
+usage "Usage: ex <COMMAND>\n       ex --print-spec"
+cmd "run"
+"#
+        .parse()
+        .unwrap();
+        let page = ManpageRenderer::new(spec).render().unwrap();
+        assert!(page.contains("\\fBex\\fR <COMMAND>"), "{page}");
+        assert!(page.contains("\\fBex\\fR \\-\\-print\\-spec"), "{page}");
+        assert!(!page.contains("[COMMAND]"), "{page}");
+    }
+
     #[test]
     fn where_the_files_live_is_documented_even_with_nothing_to_put_in_them() {
         // A CLI can describe its config file chain before it declares a single setting —

From 3aba1aa70ec11abe5eaff427f32fcbb59cb126a7 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 12:20:47 +0000
Subject: [PATCH 13/13] fix(help): honor explicit usage synopsis

---
 argv/src/help.rs                              | 18 +++++++++++--
 conformance/tests/help_request.rs             | 25 +++++++++++++++++++
 ...roundtrip__the_emitted_spec_is_stable.snap |  1 +
 conformance/tests/spec_roundtrip.rs           |  6 ++++-
 4 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/argv/src/help.rs b/argv/src/help.rs
index 1175ccef8..5ba9872eb 100644
--- a/argv/src/help.rs
+++ b/argv/src/help.rs
@@ -110,6 +110,20 @@ pub fn usage_line(path: &[&str], meta: &CommandMeta<'_>) -> String {
     out
 }
 
+/// Write the synopsis for a page, preferring the root's explicit alternatives.
+///
+/// An explicit synopsis belongs to the program rather than every command below it. Subcommand
+/// pages still derive their own invocation from the route and command metadata.
+fn usage_section(out: &mut String, spec: &Spec<'_>, path: &[&str], meta: &CommandMeta<'_>) {
+    if path.len() <= 1 {
+        if let Some(usage) = spec.usage.filter(|usage| !usage.trim().is_empty()) {
+            let _ = writeln!(out, "{}", usage.trim());
+            return;
+        }
+    }
+    let _ = writeln!(out, "Usage: {}", usage_line(path, meta));
+}
+
 /// How one flag appears in the usage line: `-f --force`, plus its value if it takes one.
 fn flag_usage(meta: &FlagMeta<'_>) -> String {
     flag_usage_masked(meta, &Shown::all(meta))
@@ -327,7 +341,7 @@ pub fn short_help(spec: &Spec<'_>, path: &[&str], chain: &[&CommandMeta<'_>]) ->
     if let Some(about) = about {
         let _ = writeln!(out, "{about}\n");
     }
-    let _ = writeln!(out, "Usage: {}", usage_line(path, meta));
+    usage_section(&mut out, spec, path, meta);
 
     // The path without the binary, which is what a listed subcommand shows: usage-lib prints
     // `tool-alias get <TOOL>` under `mise tool-alias`, the whole path from the root rather
@@ -668,7 +682,7 @@ pub fn long_help(spec: &Spec<'_>, path: &[&str], chain: &[&CommandMeta<'_>]) ->
     if let Some(about) = about {
         let _ = writeln!(out, "{about}\n");
     }
-    let _ = writeln!(out, "Usage: {}", usage_line(path, meta));
+    usage_section(&mut out, spec, path, meta);
 
     long_commands_section(&mut out, &path[1.min(path.len())..], meta);
 
diff --git a/conformance/tests/help_request.rs b/conformance/tests/help_request.rs
index 4d3d87fb9..d3ad0c434 100644
--- a/conformance/tests/help_request.rs
+++ b/conformance/tests/help_request.rs
@@ -39,6 +39,13 @@ struct Ex {
     command: Option<Commands>,
 }
 
+#[derive(Debug, Cli)]
+#[usage(
+    bin = "alternate",
+    usage = "Usage: alternate <COMMAND>\n       alternate --version"
+)]
+struct Alternate {}
+
 fn ask(tokens: &[&str]) -> (bool, String) {
     let argv: Vec<&OsStr> = tokens.iter().map(OsStr::new).collect();
     match Ex::parse_from(&argv) {
@@ -65,6 +72,24 @@ fn the_long_and_short_forms_ask_for_different_pages() {
     );
 }
 
+#[test]
+fn root_help_uses_an_explicit_multiline_synopsis() {
+    for token in ["-h", "--help"] {
+        let argv = [OsStr::new(token)];
+        let err = Alternate::parse_from(&argv).expect_err("help was requested");
+        let Error::Help { cmd, long } = err else {
+            panic!("expected help, got {err:?}");
+        };
+        let page = usage_argv::help::render(Alternate::spec(), cmd, long)
+            .expect("the command is this CLI's");
+        assert!(
+            page.contains("Usage: alternate <COMMAND>\n       alternate --version"),
+            "{page}"
+        );
+        assert!(!page.contains("Usage: alternate <SUBCOMMAND>"), "{page}");
+    }
+}
+
 #[test]
 fn help_is_asked_about_the_command_the_words_reached() {
     // `ex ls --help` is a question about `ls`, not about `ex` — which is why the request carries
diff --git a/conformance/tests/snapshots/spec_roundtrip__the_emitted_spec_is_stable.snap b/conformance/tests/snapshots/spec_roundtrip__the_emitted_spec_is_stable.snap
index aded98f7c..1680c1f0b 100644
--- a/conformance/tests/snapshots/spec_roundtrip__the_emitted_spec_is_stable.snap
+++ b/conformance/tests/snapshots/spec_roundtrip__the_emitted_spec_is_stable.snap
@@ -7,6 +7,7 @@ bin "ex"
 version "1.2.3"
 about "does things"
 long_about "Does things, at length."
+usage "Usage: ex <COMMAND>\n       ex --version \"quoted\""
 default_subcommand "run"
 example "ex a.txt" header="Basic" help="the simplest thing"
 flag "-j --jobs" help="how many jobs, and a quote: \"" global=#true help_heading="Performance" env="EX_JOBS" default="4" {
diff --git a/conformance/tests/spec_roundtrip.rs b/conformance/tests/spec_roundtrip.rs
index f6d3539ea..cf5078fab 100644
--- a/conformance/tests/spec_roundtrip.rs
+++ b/conformance/tests/spec_roundtrip.rs
@@ -325,7 +325,7 @@ static SPEC: Spec = Spec {
     min_usage_version: None,
     about: Some("does things"),
     long_about: Some("Does things, at length."),
-    usage: None,
+    usage: Some("Usage: ex <COMMAND>\n       ex --version \"quoted\""),
     default_subcommand: Some("run"),
     root: &ROOT_META,
 };
@@ -345,6 +345,10 @@ fn the_program_itself_survives() {
     assert_eq!(spec.about.as_deref(), Some("does things"));
     assert_eq!(spec.about_long.as_deref(), Some("Does things, at length."));
     assert_eq!(spec.default_subcommand.as_deref(), Some("run"));
+    assert_eq!(
+        spec.usage,
+        "Usage: ex <COMMAND>\n       ex --version \"quoted\""
+    );
 }
 
 #[test]