From ae19f7bbca20bfd71ada8fa13860e1579283e365 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:05:40 +0000
Subject: [PATCH 01/21] fix(argv): show choices when a subcommand is required

---
 argv/src/diagnostic.rs | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/argv/src/diagnostic.rs b/argv/src/diagnostic.rs
index 8fb024c1a..a6709fd2a 100644
--- a/argv/src/diagnostic.rs
+++ b/argv/src/diagnostic.rs
@@ -508,6 +508,13 @@ pub fn render(
             );
         }
         Error::MissingSubcommand => {
+            // A bare command that can do nothing on its own is a request for orientation.
+            // clap prints the command's help page here, including the available subcommands,
+            // while keeping exit 2; an error plus only `<SUBCOMMAND>` tells the reader what is
+            // missing and withholds the list they need to fix it.
+            if let Some(help) = crate::help::render_at(spec, &taken, false) {
+                return help;
+            }
             with_usage = true;
             let _ = writeln!(
                 out,
@@ -811,6 +818,15 @@ mod tests {
         assert_eq!(line, crate::help::usage_line(&["ex", "use"], &USE_META));
     }
 
+    #[test]
+    fn a_missing_subcommand_prints_the_choices() {
+        let message = rendered(&[], Error::MissingSubcommand);
+        assert!(message.contains("Commands:"), "{message}");
+        assert!(message.contains("use"), "{message}");
+        assert!(message.contains("user"), "{message}");
+        assert!(!message.contains("requires a subcommand"), "{message}");
+    }
+
     #[test]
     fn a_missing_value_names_what_it_wanted() {
         // No usage block: the shape of the command line was right, one value was missing — which

From 7ec6ca26b2e19b9696601f294ed8513f444709a6 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:17:42 +0000
Subject: [PATCH 02/21] feat(derive): preserve verbatim doc comments

---
 conformance/tests/metadata.rs | 66 +++++++++++++++++++++++++++++++++++
 derive/src/lib.rs             |  2 ++
 derive/src/model.rs           | 59 ++++++++++++++++++++++++-------
 3 files changed, 114 insertions(+), 13 deletions(-)

diff --git a/conformance/tests/metadata.rs b/conformance/tests/metadata.rs
index 80258ef36..77f9fbca9 100644
--- a/conformance/tests/metadata.rs
+++ b/conformance/tests/metadata.rs
@@ -212,6 +212,72 @@ struct Verbatim {
     command: Option<Commands>,
 }
 
+/// First root line
+/// second root line
+///
+///     root example
+#[derive(Cli)]
+#[usage(bin = "verbatim-comments", verbatim_doc_comment)]
+struct VerbatimComments {
+    /// First field line
+    /// second field line
+    ///
+    ///     field example
+    #[usage(long, verbatim_doc_comment)]
+    layout: bool,
+    #[usage(subcommand)]
+    command: Option<VerbatimCommands>,
+}
+
+#[derive(Args)]
+struct Paint {}
+
+#[derive(Subcommands)]
+enum VerbatimCommands {
+    /// First command line
+    /// second command line
+    #[usage(verbatim_doc_comment)]
+    Paint(Paint),
+}
+
+#[test]
+fn doc_comments_can_preserve_their_layout() {
+    let spec: LibSpec = VerbatimComments::to_kdl().parse().expect("valid spec");
+    assert_eq!(
+        spec.about.as_deref(),
+        Some("First root line\nsecond root line")
+    );
+    assert_eq!(
+        spec.about_long.as_deref(),
+        Some("First root line\nsecond root line\n\n    root example")
+    );
+
+    let layout = spec.cmd.flags.iter().find(|f| f.name == "layout").unwrap();
+    assert_eq!(
+        layout.help.as_deref(),
+        Some("First field line\nsecond field line")
+    );
+    assert_eq!(
+        layout.help_long.as_deref(),
+        Some("First field line\nsecond field line\n\n    field example")
+    );
+
+    let paint = spec.cmd.subcommands.get("paint").expect("paint");
+    assert_eq!(
+        paint.help.as_deref(),
+        Some("First command line\nsecond command line")
+    );
+    assert!(paint.help_long.is_none());
+
+    let argv = [
+        std::ffi::OsStr::new("--layout"),
+        std::ffi::OsStr::new("paint"),
+    ];
+    let parsed = VerbatimComments::parse_from(&argv).expect("the metadata still parses");
+    assert!(parsed.layout);
+    assert!(matches!(parsed.command, Some(VerbatimCommands::Paint(_))));
+}
+
 #[test]
 fn help_text_can_keep_line_breaks_a_comment_would_flow() {
     // A doc comment's first paragraph is read the way Rust reads one, so a line break inside
diff --git a/derive/src/lib.rs b/derive/src/lib.rs
index 6f237419b..8e7ab3e11 100644
--- a/derive/src/lib.rs
+++ b/derive/src/lib.rs
@@ -179,6 +179,7 @@
 //! here the declaration simply wins and the other spelling still answers.
 //!
 //! On the struct itself: `bin`, `version`, `about`, `long_about`, `before_help`, `after_help`,
+//! `verbatim_doc_comment` — preserve doc-comment line breaks and whitespace —
 //! `default_subcommand`, `min_usage_version` — the oldest `usage` that can read the emitted
 //! spec, declared rather than worked out — `effect` — what running this command does to the world, on an `Args`
 //! rather than on the root, which does nothing itself — `completion`, which adds the hidden command a generated shell
@@ -201,6 +202,7 @@
 //! | `env = "X"` | an environment variable that can supply the value |
 //! | `default = "x"` | the value when the command line does not supply one; a `Vec` may be given several, and starts out holding all of them |
 //! | `help_heading = "x"` | the section to list this under in help output |
+//! | `verbatim_doc_comment` | preserve line breaks and whitespace in the doc comment instead of flowing its first paragraph |
 //! | `hide` | keep it out of help and completions |
 //! | `effect = "write"` | what supplying this flag does to the world: `read`, `write` or `destructive`. Also goes on an `Args`, where it says what *running* the command does |
 //! | `double_dash = "…"` | how a positional relates to `--`: `optional` (the default), `required` (fillable only after one), `preserve` (the `--` is a value), `automatic` (filling it ends flag parsing, so a wrapper forwards) |
diff --git a/derive/src/model.rs b/derive/src/model.rs
index a4395a747..60aca02f1 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -336,7 +336,7 @@ impl Cli {
         }
 
         let mut name_given = false;
-        let (about, long_about) = doc_comment(&input.attrs)?;
+        let mut verbatim_doc_comment = false;
         let mut cli = Cli {
             ident: input.ident.clone(),
             fingerprint: quote::ToTokens::to_token_stream(input).to_string(),
@@ -354,8 +354,8 @@ impl Cli {
                 .find(|a| a.path().is_ident("usage"))
                 .map(|a| a.path().span()),
             version: None,
-            about,
-            long_about,
+            about: None,
+            long_about: None,
             unknown_flags: None,
             default_subcommand: None,
             about_attr: None,
@@ -383,6 +383,7 @@ impl Cli {
                     // decorative after it.
                     "completion" => cli.completion = flag_value(&meta)?,
                     "settings" => cli.settings = flag_value(&meta)?,
+                    "verbatim_doc_comment" => verbatim_doc_comment = flag_value(&meta)?,
                     "effect" => cli.effect = Some(effect_value(&meta)?),
                     "alias" => cli.aliases.extend(selectors(&meta)?),
                     "alias_hidden" => cli.hidden_aliases.extend(selectors(&meta)?),
@@ -436,7 +437,7 @@ impl Cli {
                             path,
                             format!(
                                 "unknown option `{other}` on a struct; usage::Cli takes \
-                                 `name`, `bin`, `version`, `unknown_flags`, \
+                                 `name`, `bin`, `version`, `verbatim_doc_comment`, `unknown_flags`, \
                                  `default_subcommand`, `restart_token`, and `mount` here, \
                                  and the description comes from the doc comment"
                             ),
@@ -446,6 +447,8 @@ impl Cli {
             }
         }
 
+        (cli.about, cli.long_about) = doc_comment(&input.attrs, verbatim_doc_comment)?;
+
         // Declared descriptions win over the comment, which is the point of declaring them.
         if let Some(about) = cli.about_attr.take() {
             cli.about = Some(about);
@@ -1010,8 +1013,6 @@ impl Field {
             .clone()
             .expect("named fields were checked by the caller");
         let span = field.span();
-        let (help, long_help) = doc_comment(&field.attrs)?;
-
         // A subcommand field is neither a flag nor an argument, and shares none of
         // their options, so it is recognized before any of them are read.
         if let Some(subcommand) = Self::subcommand(field, &ident, span)? {
@@ -1042,6 +1043,7 @@ impl Field {
         let mut required_collection = false;
         let mut help_attr: Option<String> = None;
         let mut long_help_attr: Option<String> = None;
+        let mut verbatim_doc_comment = false;
         let mut hide = false;
         let mut is_arg = false;
         let mut choices: Vec<String> = Vec::new();
@@ -1153,6 +1155,7 @@ impl Field {
                     // help whose breaks are meant literally has to be given directly.
                     "help" => help_attr = Some(string_value(&meta)?),
                     "long_help" => long_help_attr = Some(string_value(&meta)?),
+                    "verbatim_doc_comment" => verbatim_doc_comment = flag_value(&meta)?,
                     "required" => required_collection = flag_value(&meta)?,
                     "double_dash" => {
                         let mode = string_value(&meta)?;
@@ -1183,6 +1186,7 @@ impl Field {
                                  `var_min`, `var_max`, `value_enum`, `overrides`, \
                                  `conflicts`, `requires`, `required_if`, \
                                  `required_unless`, `help_heading`, `value_name`, \
+                                 `verbatim_doc_comment`, \
                                  `required`, and `double_dash`"
                             ),
                         ));
@@ -1191,6 +1195,8 @@ impl Field {
             }
         }
 
+        let (help, long_help) = doc_comment(&field.attrs, verbatim_doc_comment)?;
+
         // A bare `long` or `short` written before `name` would have captured the
         // field name rather than the renamed one, so resolve both once everything
         // has been read. Counted rather than rewritten, so a field carrying both a
@@ -1971,10 +1977,13 @@ fn flag_value(meta: &Meta) -> syn::Result<bool> {
 
 /// Split a doc comment into the short help and the long help.
 ///
-/// The first paragraph is the short form, matching what every Rust CLI framework
-/// does and what an author expects from writing one; the whole comment is the long
-/// form, and is only reported when it says more than the short one.
-fn doc_comment(attrs: &[Attribute]) -> syn::Result<(Option<String>, Option<String>)> {
+/// The first paragraph is the short form; the whole comment is the long form and is only
+/// reported when it says more than the short one. Prose is flowed by default, while
+/// `verbatim` keeps line breaks and whitespace for tables, examples, and ASCII art.
+fn doc_comment(
+    attrs: &[Attribute],
+    verbatim: bool,
+) -> syn::Result<(Option<String>, Option<String>)> {
     let mut lines: Vec<String> = Vec::new();
     for attr in attrs.iter().filter(|a| a.path().is_ident("doc")) {
         if let Meta::NameValue(nv) = &attr.meta {
@@ -1987,14 +1996,35 @@ fn doc_comment(attrs: &[Attribute]) -> syn::Result<(Option<String>, Option<Strin
                 // mise's help is full of them, since an indented block is how a spec shows a
                 // command to type.
                 let raw = s.value();
-                lines.push(raw.strip_prefix(' ').unwrap_or(&raw).trim_end().to_string());
+                lines.extend(raw.split('\n').map(|line| {
+                    let line = line.strip_prefix(' ').unwrap_or(line);
+                    if verbatim {
+                        line.to_string()
+                    } else {
+                        line.trim_end().to_string()
+                    }
+                }));
             }
         }
     }
+    while lines.first().is_some_and(|line| line.trim().is_empty()) {
+        lines.remove(0);
+    }
+    while lines.last().is_some_and(|line| line.trim().is_empty()) {
+        lines.pop();
+    }
     if lines.is_empty() {
         return Ok((None, None));
     }
 
+    if verbatim {
+        let first_blank = lines.iter().position(|line| line.trim().is_empty());
+        let short_lines = first_blank.map_or(lines.as_slice(), |i| &lines[..i]);
+        let short = short_lines.join("\n");
+        let long = first_blank.map(|_| lines.join("\n"));
+        return Ok(((!short.is_empty()).then_some(short), long));
+    }
+
     let full = lines.join("\n").trim().to_string();
     let short = full
         .split("\n\n")
@@ -2216,7 +2246,7 @@ impl Subcommands {
 
 impl Variant {
     fn from_variant(variant: &syn::Variant, enum_ident: &syn::Ident) -> syn::Result<Self> {
-        let (help, long_help) = doc_comment(&variant.attrs)?;
+        let mut verbatim_doc_comment = false;
         // `unraw` first: `r#type` is how a variant named after a keyword prints, and a command
         // called `r#type` is one no user could type. `type` is what they meant.
         let mut name = to_kebab(&variant.ident.unraw().to_string());
@@ -2247,12 +2277,14 @@ impl Variant {
                     // breaks matter is declared instead.
                     "help" => help_attr = Some(string_value(&meta)?),
                     "long_help" => long_help_attr = Some(string_value(&meta)?),
+                    "verbatim_doc_comment" => verbatim_doc_comment = flag_value(&meta)?,
                     other => {
                         return Err(syn::Error::new_spanned(
                             path,
                             format!(
                                 "unknown option `{other}` on a variant; a subcommand \
-                                 variant takes `name`, `alias` and `alias_hidden` here, \
+                                 variant takes `name`, `alias`, `alias_hidden` and \
+                                 `verbatim_doc_comment` here, \
                                  and its description comes from the doc comment"
                             ),
                         ));
@@ -2260,6 +2292,7 @@ impl Variant {
                 }
             }
         }
+        let (help, long_help) = doc_comment(&variant.attrs, verbatim_doc_comment)?;
         for alias in aliases.iter().chain(&hidden_aliases) {
             if alias.is_empty() {
                 return Err(syn::Error::new_spanned(

From 522909b555d11dc1e63ed24f97c1c690921fe3ba Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:33:07 +0000
Subject: [PATCH 03/21] fix(derive): preserve ordinary doc indentation

---
 conformance/tests/metadata.rs | 18 ++++++++++++++++++
 derive/src/model.rs           | 19 +++++++++++--------
 2 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/conformance/tests/metadata.rs b/conformance/tests/metadata.rs
index 77f9fbca9..127be0f99 100644
--- a/conformance/tests/metadata.rs
+++ b/conformance/tests/metadata.rs
@@ -212,6 +212,11 @@ struct Verbatim {
     command: Option<Commands>,
 }
 
+#[doc = " Ordinary first line\n    indented continuation"]
+#[derive(Cli)]
+#[usage(bin = "ordinary-comments")]
+struct OrdinaryComments {}
+
 /// First root line
 /// second root line
 ///
@@ -278,6 +283,19 @@ fn doc_comments_can_preserve_their_layout() {
     assert!(matches!(parsed.command, Some(VerbatimCommands::Paint(_))));
 }
 
+#[test]
+fn ordinary_multiline_doc_attributes_keep_their_indentation() {
+    let spec: LibSpec = OrdinaryComments::to_kdl().parse().expect("valid spec");
+    assert_eq!(
+        spec.about.as_deref(),
+        Some("Ordinary first line     indented continuation")
+    );
+    assert_eq!(
+        spec.about_long.as_deref(),
+        Some("Ordinary first line\n    indented continuation")
+    );
+}
+
 #[test]
 fn help_text_can_keep_line_breaks_a_comment_would_flow() {
     // A doc comment's first paragraph is read the way Rust reads one, so a line break inside
diff --git a/derive/src/model.rs b/derive/src/model.rs
index 60aca02f1..81a743c33 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -1996,14 +1996,17 @@ fn doc_comment(
                 // mise's help is full of them, since an indented block is how a spec shows a
                 // command to type.
                 let raw = s.value();
-                lines.extend(raw.split('\n').map(|line| {
-                    let line = line.strip_prefix(' ').unwrap_or(line);
-                    if verbatim {
-                        line.to_string()
-                    } else {
-                        line.trim_end().to_string()
-                    }
-                }));
+                if verbatim {
+                    lines.extend(
+                        raw.split('\n')
+                            .map(|line| line.strip_prefix(' ').unwrap_or(line).to_string()),
+                    );
+                } else {
+                    // Preserve the pre-verbatim behaviour for an explicitly written,
+                    // multiline `#[doc = "..."]`: only `///` contributes one leading
+                    // space per attribute. A newline inside one attribute does not.
+                    lines.push(raw.strip_prefix(' ').unwrap_or(&raw).trim_end().to_string());
+                }
             }
         }
     }

From 641c80c6efb6933c09cf23e83a1205f933263e04 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 04:34:29 +0000
Subject: [PATCH 04/21] fix(derive): preserve verbatim continuation indentation

---
 conformance/tests/metadata.rs | 17 +++++++++++++++++
 derive/src/model.rs           |  9 +++++----
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/conformance/tests/metadata.rs b/conformance/tests/metadata.rs
index 127be0f99..62d124c99 100644
--- a/conformance/tests/metadata.rs
+++ b/conformance/tests/metadata.rs
@@ -217,6 +217,11 @@ struct Verbatim {
 #[usage(bin = "ordinary-comments")]
 struct OrdinaryComments {}
 
+#[doc = " Verbatim first line\n    indented continuation"]
+#[derive(Cli)]
+#[usage(bin = "verbatim-attribute-comments", verbatim_doc_comment)]
+struct VerbatimAttributeComments {}
+
 /// First root line
 /// second root line
 ///
@@ -296,6 +301,18 @@ fn ordinary_multiline_doc_attributes_keep_their_indentation() {
     );
 }
 
+#[test]
+fn verbatim_multiline_doc_attributes_keep_their_indentation() {
+    let spec: LibSpec = VerbatimAttributeComments::to_kdl()
+        .parse()
+        .expect("valid spec");
+    assert_eq!(
+        spec.about.as_deref(),
+        Some("Verbatim first line\n    indented continuation")
+    );
+    assert!(spec.about_long.is_none());
+}
+
 #[test]
 fn help_text_can_keep_line_breaks_a_comment_would_flow() {
     // A doc comment's first paragraph is read the way Rust reads one, so a line break inside
diff --git a/derive/src/model.rs b/derive/src/model.rs
index 81a743c33..91cb47eec 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -1997,10 +1997,11 @@ fn doc_comment(
                 // command to type.
                 let raw = s.value();
                 if verbatim {
-                    lines.extend(
-                        raw.split('\n')
-                            .map(|line| line.strip_prefix(' ').unwrap_or(line).to_string()),
-                    );
+                    let mut raw_lines = raw.split('\n');
+                    if let Some(first) = raw_lines.next() {
+                        lines.push(first.strip_prefix(' ').unwrap_or(first).to_string());
+                    }
+                    lines.extend(raw_lines.map(str::to_string));
                 } else {
                     // Preserve the pre-verbatim behaviour for an explicitly written,
                     // multiline `#[doc = "..."]`: only `///` contributes one leading

From 4df0208bfd0f7f23dfd7b8492fb67b2c05cd7790 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:24:39 +0000
Subject: [PATCH 05/21] feat(derive): support path value hints

---
 argv/src/complete.rs            | 15 +++++++---
 argv/src/spec.rs                | 37 +++++++++++++++++++++++
 conformance/tests/completion.rs | 43 ++++++++++++++++++++++++++
 derive/src/codegen.rs           |  4 +++
 derive/src/lib.rs               |  1 +
 derive/src/model.rs             | 53 ++++++++++++++++++++++++++++++++-
 6 files changed, 148 insertions(+), 5 deletions(-)

diff --git a/argv/src/complete.rs b/argv/src/complete.rs
index 3a17ee7a3..b7f6f4725 100644
--- a/argv/src/complete.rs
+++ b/argv/src/complete.rs
@@ -428,19 +428,26 @@ pub fn complete<'a>(spec: &'a Spec<'a>, split: &Split) -> Completions<'a> {
 
     // The name a value here would have, which is what says whether paths belong, and whether
     // that value declares its own set.
-    let (named, declares_choices) = if let Some(flag) = position.awaiting_value {
+    let (named, declares_choices, complete_type) = if let Some(flag) = position.awaiting_value {
         let meta = flag_meta(spec.root, flag);
         (
             meta.and_then(|m| m.value_name).or(Some(flag.name)),
             meta.is_some_and(|m| !m.choices.is_empty()),
+            meta.and_then(|m| m.complete_type),
         )
     } else if let Some(arg) = at_cursor {
         let meta = arg_meta(spec.root, arg);
-        (Some(arg.name), meta.is_some_and(|m| !m.choices.is_empty()))
+        (
+            Some(arg.name),
+            meta.is_some_and(|m| !m.choices.is_empty()),
+            meta.and_then(|m| m.complete_type),
+        )
     } else {
-        (None, false)
+        (None, false, None)
     };
-    let asked_for = named.and_then(files_for);
+    let asked_for = complete_type
+        .and_then(files_for)
+        .or_else(|| named.and_then(files_for));
 
     // An argument that requires a separator is not fillable yet, so nothing else belongs here —
     // not even a path, which the parser would reject exactly as it rejects a value.
diff --git a/argv/src/spec.rs b/argv/src/spec.rs
index 565eef04d..4335b5ac0 100644
--- a/argv/src/spec.rs
+++ b/argv/src/spec.rs
@@ -485,6 +485,8 @@ pub struct FlagMeta<'a> {
     /// that asks *this binary*, so a spec stays complete for every other consumer while the
     /// binary answers itself.
     pub complete: Option<Completer>,
+    /// A built-in completion class such as `path` or `dir`.
+    pub complete_type: Option<&'a str>,
     /// Whether the flag may be given more than once. Distinct from
     /// [`Flag::variadic`], which is one occurrence taking several values.
     pub repeatable: bool,
@@ -518,6 +520,7 @@ impl FlagMeta<'_> {
     /// Metadata for a flag with nothing declared, for struct update syntax.
     pub const EMPTY: FlagMeta<'static> = FlagMeta {
         complete: None,
+        complete_type: None,
         flag: &Flag::BOOL,
         help: None,
         long_help: None,
@@ -561,12 +564,15 @@ pub struct ArgMeta<'a> {
     pub help_heading: Option<&'a str>,
     /// What answers for this argument when a shell asks. See [`FlagMeta::complete`].
     pub complete: Option<Completer>,
+    /// A built-in completion class such as `path` or `dir`.
+    pub complete_type: Option<&'a str>,
 }
 
 impl ArgMeta<'_> {
     /// Metadata for an argument with nothing declared, for struct update syntax.
     pub const EMPTY: ArgMeta<'static> = ArgMeta {
         complete: None,
+        complete_type: None,
         arg: &Arg::REQUIRED,
         help: None,
         long_help: None,
@@ -785,6 +791,7 @@ fn write_body(
         );
         write_arg(out, arg, depth)?;
     }
+    write_completion_types(out, meta, depth)?;
     #[cfg(feature = "complete")]
     write_completers(out, meta, bin, depth)?;
     for sub in meta.subcommands {
@@ -793,6 +800,36 @@ fn write_body(
     Ok(())
 }
 
+/// Built-in completion types declared by this command, written in the spec's vocabulary.
+fn write_completion_types(
+    out: &mut String,
+    meta: &CommandMeta<'_>,
+    depth: usize,
+) -> core::fmt::Result {
+    for arg in meta.args {
+        if let Some(type_) = arg.complete_type {
+            indent(out, depth)?;
+            writeln!(
+                out,
+                "complete {} type={}",
+                quoted(&arg.arg.name.to_ascii_lowercase()),
+                quoted(type_)
+            )?;
+        }
+    }
+    for flag in meta.flags {
+        if let Some(type_) = flag.complete_type {
+            let name = flag
+                .value_name
+                .unwrap_or(flag.flag.name)
+                .to_ascii_lowercase();
+            indent(out, depth)?;
+            writeln!(out, "complete {} type={}", quoted(&name), quoted(type_))?;
+        }
+    }
+    Ok(())
+}
+
 fn write_command(
     out: &mut String,
     meta: &CommandMeta<'_>,
diff --git a/conformance/tests/completion.rs b/conformance/tests/completion.rs
index 988eaf086..c811f920e 100644
--- a/conformance/tests/completion.rs
+++ b/conformance/tests/completion.rs
@@ -59,6 +59,49 @@ fn ask(shell: &str, line: &str) -> String {
     Ex::completion_request(&argv).expect("this is a completion request")
 }
 
+#[derive(Cli)]
+#[usage(bin = "hinted", completion)]
+struct Hinted {
+    /// A file to read
+    #[usage(long, value_hint = clap::ValueHint::FilePath)]
+    file: Option<std::path::PathBuf>,
+    /// A directory to write
+    #[usage(long, value_hint = clap::ValueHint::DirPath)]
+    dir: Option<std::path::PathBuf>,
+}
+
+fn ask_hinted(line: &str) -> String {
+    let argv: Vec<OsString> = ["__complete_word__", "--shell", "bash", "--line", line]
+        .iter()
+        .map(OsString::from)
+        .collect();
+    Hinted::completion_request(&argv).expect("this is a completion request")
+}
+
+#[test]
+fn clap_path_value_hints_reach_native_and_emitted_completions() {
+    assert_eq!(
+        ask_hinted("hinted --file "),
+        format!("{}\n", usage_argv::complete::FILES_MARKER)
+    );
+    assert_eq!(
+        ask_hinted("hinted --dir "),
+        format!("{}\n", usage_argv::complete::DIRS_MARKER)
+    );
+
+    let kdl = Hinted::to_kdl();
+    assert!(kdl.contains("complete \"file\" type=\"path\""), "{kdl}");
+    assert!(kdl.contains("complete \"dir\" type=\"dir\""), "{kdl}");
+
+    let argv = [OsStr::new("--file"), OsStr::new("input.kdl")];
+    let parsed = Hinted::parse_from(&argv).expect("the hinted flag still parses");
+    assert_eq!(
+        parsed.file.as_deref(),
+        Some(std::path::Path::new("input.kdl"))
+    );
+    assert!(parsed.dir.is_none());
+}
+
 #[test]
 fn a_request_is_answered_from_the_same_tables_the_parse_uses() {
     assert_eq!(ask("bash", "ex "), "install\nrm\nrun\nuninstall\n");
diff --git a/derive/src/codegen.rs b/derive/src/codegen.rs
index d72f07511..374af1784 100644
--- a/derive/src/codegen.rs
+++ b/derive/src/codegen.rs
@@ -802,6 +802,7 @@ fn flag_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
     let env = option_str(field.env.as_deref());
     let help_heading = option_str(field.help_heading.as_deref());
     let value_name = option_str(field.value_name.as_deref());
+    let complete_type = option_str(field.complete_type.as_deref());
     let defaults = &field.default;
     let default = quote!(&[#(#defaults),*]);
     let hide = field.hide;
@@ -836,6 +837,7 @@ fn flag_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
         pub static #name: ::usage_argv::spec::FlagMeta = ::usage_argv::spec::FlagMeta {
             effect: #effect,
             complete: #completer,
+            complete_type: #complete_type,
             flag: &#table,
             help: #help,
             long_help: #long_help,
@@ -867,6 +869,7 @@ fn arg_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
     let long_help = option_str(field.long_help.as_deref());
     let env = option_str(field.env.as_deref());
     let help_heading = option_str(field.help_heading.as_deref());
+    let complete_type = option_str(field.complete_type.as_deref());
     let defaults = &field.default;
     let default = quote!(&[#(#defaults),*]);
     let hide = field.hide;
@@ -882,6 +885,7 @@ fn arg_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
         #completer_decl
         pub static #name: ::usage_argv::spec::ArgMeta = ::usage_argv::spec::ArgMeta {
             complete: #completer,
+            complete_type: #complete_type,
             arg: &#table,
             help: #help,
             long_help: #long_help,
diff --git a/derive/src/lib.rs b/derive/src/lib.rs
index 8e7ab3e11..b9f8fa532 100644
--- a/derive/src/lib.rs
+++ b/derive/src/lib.rs
@@ -208,6 +208,7 @@
 //! | `double_dash = "…"` | how a positional relates to `--`: `optional` (the default), `required` (fillable only after one), `preserve` (the `--` is a value), `automatic` (filling it ends flag parsing, so a wrapper forwards) |
 //! | `complete = my_fn` | a function that answers for this value when a shell asks |
 //! | `value_enum` | the words come from the field's type, which derives [`ValueEnum`] |
+//! | `value_hint = clap::ValueHint::FilePath` | ask the shell for paths; `AnyPath` and `DirPath` are also supported without retaining a clap dependency |
 //! | `arg` | force a field to be positional |
 //! | `overrides = "--other"` | a flag this one displaces, the last given winning |
 //! | `conflicts = "--other"` | a flag this one cannot be given with |
diff --git a/derive/src/model.rs b/derive/src/model.rs
index 91cb47eec..f3f39e351 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -163,6 +163,8 @@ pub struct Field {
     /// The counterpart of a spec's `run=`, and the source it is generated from: declaring the
     /// function is the only place a completer is said to exist.
     pub complete: Option<syn::Path>,
+    /// A built-in completion class, in the spec's vocabulary (`path` or `dir`).
+    pub complete_type: Option<String>,
     pub var_min: Option<usize>,
     pub var_max: Option<usize>,
     /// Flags this one displaces. Applied while parsing rather than after it: the
@@ -243,6 +245,38 @@ fn effect_value(meta: &Meta) -> syn::Result<proc_macro2::TokenStream> {
     )))
 }
 
+/// Clap's path-oriented `ValueHint`s lowered into the completion types the usage spec has.
+///
+/// The path is consumed syntactically, so accepting `clap::ValueHint::FilePath` does not keep
+/// clap as a dependency after a declaration migrates to `#[usage(...)]`.
+fn value_hint(meta: &Meta) -> syn::Result<String> {
+    let value = &meta.require_name_value()?.value;
+    let Expr::Path(path) = value else {
+        return Err(syn::Error::new_spanned(
+            value,
+            "`value_hint` takes a ValueHint variant, as in \
+             `value_hint = clap::ValueHint::FilePath`",
+        ));
+    };
+    let Some(variant) = path.path.segments.last() else {
+        return Err(syn::Error::new_spanned(
+            value,
+            "`value_hint` needs a variant",
+        ));
+    };
+    match variant.ident.to_string().as_str() {
+        "FilePath" | "AnyPath" => Ok("path".to_string()),
+        "DirPath" => Ok("dir".to_string()),
+        other => Err(syn::Error::new_spanned(
+            value,
+            format!(
+                "`ValueHint::{other}` has no usage completion type yet; supported hints are \
+                 `FilePath`, `AnyPath`, and `DirPath`"
+            ),
+        )),
+    }
+}
+
 /// Whether a field is a flag or a positional, and how it is addressed.
 pub enum Kind {
     Flag {
@@ -887,6 +921,7 @@ impl Field {
             // place rather than a command.
             effect: None,
             complete: None,
+            complete_type: None,
             // A flattened field holds declarations, not a value, so none of what describes a
             // value applies — the same as a subcommand field.
             shape: Shape::Bool,
@@ -979,6 +1014,7 @@ impl Field {
             kind: Kind::Subcommand { ty, optional },
             effect: None,
             complete: None,
+            complete_type: None,
             // A subcommand field holds a command, not a value, so none of what
             // describes a value applies to it.
             shape: Shape::Bool,
@@ -1048,6 +1084,7 @@ impl Field {
         let mut is_arg = false;
         let mut choices: Vec<String> = Vec::new();
         let mut complete: Option<syn::Path> = None;
+        let mut complete_type: Option<String> = None;
         let mut value_enum = false;
         let mut var_min: Option<usize> = None;
         let mut var_max: Option<usize> = None;
@@ -1114,6 +1151,7 @@ impl Field {
                         };
                         complete = Some(path.path.clone());
                     }
+                    "value_hint" => complete_type = Some(value_hint(&meta)?),
                     "choices" => {
                         let Meta::List(list) = &meta else {
                             return Err(syn::Error::new_spanned(
@@ -1183,7 +1221,7 @@ impl Field {
                                 "unknown option `{other}`; a field takes `name`, `long`, \
                                  `short`, `negate`, `global`, `var`, `variadic`, \
                                  `count`, `hide`, `arg`, `env`, `default`, `choices`, \
-                                 `var_min`, `var_max`, `value_enum`, `overrides`, \
+                                 `var_min`, `var_max`, `value_enum`, `value_hint`, `overrides`, \
                                  `conflicts`, `requires`, `required_if`, \
                                  `required_unless`, `help_heading`, `value_name`, \
                                  `verbatim_doc_comment`, \
@@ -1340,6 +1378,18 @@ impl Field {
                 "a `bool` or counting field has no value to check against `choices`",
             ));
         }
+        if complete_type.is_some() && matches!(shape, Shape::Bool | Shape::Count) {
+            return Err(syn::Error::new(
+                span,
+                "`value_hint` describes a value to complete, and this field takes no value",
+            ));
+        }
+        if complete_type.is_some() && complete.is_some() {
+            return Err(syn::Error::new(
+                span,
+                "`value_hint` and `complete` both answer completion for this value; use one",
+            ));
+        }
         if let (Some(min), Some(max)) = (var_min, var_max) {
             if min > max {
                 return Err(syn::Error::new(
@@ -1689,6 +1739,7 @@ impl Field {
             required_collection,
             choices,
             complete,
+            complete_type,
             value_enum,
             var_min,
             var_max,

From 26fa45574d488b369f7c32fdbc683d21b76cada6 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:39:11 +0000
Subject: [PATCH 06/21] refactor(derive): use usage value hints

---
 argv/src/lib.rs                 | 15 +++++++++++++++
 conformance/tests/completion.rs |  6 +++---
 derive/src/lib.rs               |  2 +-
 derive/src/model.rs             |  9 +++------
 4 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/argv/src/lib.rs b/argv/src/lib.rs
index 5bf1850d3..fd077e237 100644
--- a/argv/src/lib.rs
+++ b/argv/src/lib.rs
@@ -83,6 +83,21 @@
 
 use std::ffi::{OsStr, OsString};
 
+/// A value's filesystem completion class for `#[usage(value_hint = ...)]`.
+///
+/// This lives in the runtime crate so a declaration never needs clap merely to describe what
+/// kind of path a shell should offer. It is metadata only and adds no work to a successful
+/// parse.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ValueHint {
+    /// A path to a file.
+    FilePath,
+    /// A path to either a file or a directory.
+    AnyPath,
+    /// A path to a directory.
+    DirPath,
+}
+
 #[cfg(feature = "complete")]
 pub mod complete;
 #[cfg(feature = "diagnostics")]
diff --git a/conformance/tests/completion.rs b/conformance/tests/completion.rs
index c811f920e..ea18b0d1b 100644
--- a/conformance/tests/completion.rs
+++ b/conformance/tests/completion.rs
@@ -63,10 +63,10 @@ fn ask(shell: &str, line: &str) -> String {
 #[usage(bin = "hinted", completion)]
 struct Hinted {
     /// A file to read
-    #[usage(long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(long, value_hint = usage_argv::ValueHint::FilePath)]
     file: Option<std::path::PathBuf>,
     /// A directory to write
-    #[usage(long, value_hint = clap::ValueHint::DirPath)]
+    #[usage(long, value_hint = usage_argv::ValueHint::DirPath)]
     dir: Option<std::path::PathBuf>,
 }
 
@@ -79,7 +79,7 @@ fn ask_hinted(line: &str) -> String {
 }
 
 #[test]
-fn clap_path_value_hints_reach_native_and_emitted_completions() {
+fn usage_path_value_hints_reach_native_and_emitted_completions() {
     assert_eq!(
         ask_hinted("hinted --file "),
         format!("{}\n", usage_argv::complete::FILES_MARKER)
diff --git a/derive/src/lib.rs b/derive/src/lib.rs
index b9f8fa532..b6d99cb7b 100644
--- a/derive/src/lib.rs
+++ b/derive/src/lib.rs
@@ -208,7 +208,7 @@
 //! | `double_dash = "…"` | how a positional relates to `--`: `optional` (the default), `required` (fillable only after one), `preserve` (the `--` is a value), `automatic` (filling it ends flag parsing, so a wrapper forwards) |
 //! | `complete = my_fn` | a function that answers for this value when a shell asks |
 //! | `value_enum` | the words come from the field's type, which derives [`ValueEnum`] |
-//! | `value_hint = clap::ValueHint::FilePath` | ask the shell for paths; `AnyPath` and `DirPath` are also supported without retaining a clap dependency |
+//! | `value_hint = usage_argv::ValueHint::FilePath` | ask the shell for paths; `AnyPath` and `DirPath` are also supported |
 //! | `arg` | force a field to be positional |
 //! | `overrides = "--other"` | a flag this one displaces, the last given winning |
 //! | `conflicts = "--other"` | a flag this one cannot be given with |
diff --git a/derive/src/model.rs b/derive/src/model.rs
index f3f39e351..8bbe8673a 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -245,17 +245,14 @@ fn effect_value(meta: &Meta) -> syn::Result<proc_macro2::TokenStream> {
     )))
 }
 
-/// Clap's path-oriented `ValueHint`s lowered into the completion types the usage spec has.
-///
-/// The path is consumed syntactically, so accepting `clap::ValueHint::FilePath` does not keep
-/// clap as a dependency after a declaration migrates to `#[usage(...)]`.
+/// usage's path-oriented `ValueHint`s lowered into the completion types the spec has.
 fn value_hint(meta: &Meta) -> syn::Result<String> {
     let value = &meta.require_name_value()?.value;
     let Expr::Path(path) = value else {
         return Err(syn::Error::new_spanned(
             value,
-            "`value_hint` takes a ValueHint variant, as in \
-             `value_hint = clap::ValueHint::FilePath`",
+            "`value_hint` takes a usage ValueHint variant, as in \
+             `value_hint = usage_argv::ValueHint::FilePath`",
         ));
     };
     let Some(variant) = path.path.segments.last() else {

From 567d41aa9eec567a483b679232fba1565b03dccc Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:53:41 +0000
Subject: [PATCH 07/21] feat(lib): add usage-rs facade

---
 Cargo.lock               |  44 ++++-
 Cargo.toml               |   2 +
 derive/Cargo.toml        |   1 +
 derive/src/codegen.rs    | 418 +++++++++++++++++++++------------------
 derive/src/lib.rs        |   2 +-
 derive/src/model.rs      |   4 +-
 usage-rs/Cargo.toml      |  28 +++
 usage-rs/src/lib.rs      |  32 +++
 usage-rs/tests/facade.rs |  38 ++++
 9 files changed, 376 insertions(+), 193 deletions(-)
 create mode 100644 usage-rs/Cargo.toml
 create mode 100644 usage-rs/src/lib.rs
 create mode 100644 usage-rs/tests/facade.rs

diff --git a/Cargo.lock b/Cargo.lock
index c05992993..e9f3b17f3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1321,6 +1321,15 @@ dependencies = [
  "yansi",
 ]
 
+[[package]]
+name = "proc-macro-crate"
+version = "3.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
+dependencies = [
+ "toml_edit",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -1965,7 +1974,7 @@ dependencies = [
  "indexmap 2.14.0",
  "serde_core",
  "serde_spanned",
- "toml_datetime",
+ "toml_datetime 0.7.5+spec-1.1.0",
  "toml_parser",
  "toml_writer",
  "winnow 0.7.15",
@@ -1980,6 +1989,27 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "toml_datetime"
+version = "1.1.1+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.25.13+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6975367e4d2ef766d86af01ffad14b622fecc8d4357a998fbc4deb6e9bacaf9b"
+dependencies = [
+ "indexmap 2.14.0",
+ "toml_datetime 1.1.1+spec-1.1.0",
+ "toml_parser",
+ "winnow 1.0.4",
+]
+
 [[package]]
 name = "toml_parser"
 version = "1.1.3+spec-1.1.0"
@@ -2119,6 +2149,7 @@ dependencies = [
 name = "usage-derive"
 version = "5.1.0"
 dependencies = [
+ "proc-macro-crate",
  "proc-macro2",
  "quote",
  "syn 3.0.3",
@@ -2152,6 +2183,14 @@ dependencies = [
  "xx",
 ]
 
+[[package]]
+name = "usage-rs"
+version = "5.1.0"
+dependencies = [
+ "usage-argv",
+ "usage-derive",
+]
+
 [[package]]
 name = "utf8parse"
 version = "0.2.2"
@@ -2535,6 +2574,9 @@ name = "winnow"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
+dependencies = [
+ "memchr",
+]
 
 [[package]]
 name = "xtask"
diff --git a/Cargo.toml b/Cargo.toml
index e82693b74..1dc771e7d 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,6 +5,7 @@ members = [
     "config",
     "config-build",
     "derive",
+    "usage-rs",
     "clap_usage",
     "cli",
     "conformance",
@@ -33,6 +34,7 @@ usage-argv = { path = "./argv", version = "5.1.0" }
 usage-config = { path = "./config", version = "5.1.0" }
 usage-derive = { path = "./derive", version = "5.1.0" }
 usage-lib = { path = "./lib", version = "5.1.0", features = ["clap"] }
+usage-rs = { path = "./usage-rs", version = "5.1.0" }
 
 [workspace.metadata.release]
 allow-branch = ["main"]
diff --git a/derive/Cargo.toml b/derive/Cargo.toml
index 910f37f46..cad5f848f 100644
--- a/derive/Cargo.toml
+++ b/derive/Cargo.toml
@@ -19,6 +19,7 @@ release = true
 
 [dependencies]
 proc-macro2 = "1"
+proc-macro-crate = "3"
 quote = "1"
 # syn 2 rather than 3, which is already in the tree via clap_derive: nothing here
 # needs the newer API, and matching what is there avoids a second copy.
diff --git a/derive/src/codegen.rs b/derive/src/codegen.rs
index 374af1784..b3020763d 100644
--- a/derive/src/codegen.rs
+++ b/derive/src/codegen.rs
@@ -13,12 +13,38 @@
 //! do not collide with anything, and so `cargo expand` shows them together.
 
 use proc_macro2::TokenStream;
+use proc_macro_crate::{crate_name, FoundCrate};
 use quote::{format_ident, quote};
 
 use crate::model::{rendered_path, Cli, DoubleDash, Field, Kind, Shape, Subcommands, ValueEnum};
 
+/// The runtime as the adopter depended on it.
+///
+/// A direct `usage-argv` dependency remains supported for the low-level crates and existing
+/// users. The `usage-rs` facade re-exports that runtime as `usage::argv`, which lets an
+/// application keep derives, tables, and their versions behind one dependency.
+fn runtime_path() -> TokenStream {
+    match crate_name("usage-rs") {
+        Ok(FoundCrate::Itself) => quote!(::usage_rs::argv),
+        Ok(FoundCrate::Name(name)) => {
+            let facade = format_ident!("{}", name.replace('-', "_"));
+            quote!(::#facade::argv)
+        }
+        Err(_) => match crate_name("usage-argv") {
+            Ok(FoundCrate::Name(name)) => {
+                let runtime = format_ident!("{}", name.replace('-', "_"));
+                quote!(::#runtime)
+            }
+            // Deriving inside an integration target of `usage-argv`, or preserving the old
+            // useful compiler error when neither dependency was declared.
+            _ => quote!(::usage_argv),
+        },
+    }
+}
+
 pub fn emit(cli: &Cli) -> TokenStream {
     let ident = &cli.ident;
+    let runtime = runtime_path();
 
     let flags: Vec<&Field> = cli
         .fields
@@ -151,7 +177,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
                 argv: &'v [&'v ::std::ffi::OsStr],
             ) -> ::std::result::Result<
                 (Self, ::usage_config::CliLayer),
-                ::usage_argv::Error<'static, 'v>,
+                usage_argv::Error<'static, 'v>,
             > {
                 // The layer from what argv left, and only then the rest: `check` fills a field
                 // from its `env` and marks it given, and a variable's value contributed here
@@ -198,13 +224,15 @@ pub fn emit(cli: &Cli) -> TokenStream {
             clippy::needless_update
         )]
         const _: () = {
+            use #runtime as usage_argv;
+
             #flatten_checks
             #keys
             #(#flag_tables)*
             #(#arg_tables)*
             #table_decls
 
-            pub static ROOT: ::usage_argv::Command = ::usage_argv::Command {
+            pub static ROOT: usage_argv::Command = usage_argv::Command {
                 // Only where a version was declared, which is when clap adds the flag: a
                 // `--version` that answers with nothing is worse than one that is not there.
                 version: #has_version,
@@ -215,14 +243,14 @@ pub fn emit(cli: &Cli) -> TokenStream {
                 args: #arg_table_ref,
                 #sub_commands
                 #sub_default
-                ..::usage_argv::Command::EMPTY
+                ..usage_argv::Command::EMPTY
             };
 
             #(#flag_metas)*
             #(#arg_metas)*
             #meta_table_decls
 
-            pub static ROOT_META: ::usage_argv::spec::CommandMeta = ::usage_argv::spec::CommandMeta {
+            pub static ROOT_META: usage_argv::spec::CommandMeta = usage_argv::spec::CommandMeta {
                 cmd: &ROOT,
                 about: #about,
                 long_about: #long_about,
@@ -236,7 +264,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
                 flags: #flag_meta_table_ref,
                 args: #arg_meta_table_ref,
                 #sub_metas
-                ..::usage_argv::spec::CommandMeta::EMPTY
+                ..usage_argv::spec::CommandMeta::EMPTY
             };
 
             // Values arrive as the bytes that were on the command line. This version
@@ -263,7 +291,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
             /// nested command generate the same code here.
             pub fn check<'t, 'v>(
                 partial: &mut Partial,
-            ) -> ::std::result::Result<(), ::usage_argv::Error<'t, 'v>> {
+            ) -> ::std::result::Result<(), usage_argv::Error<'t, 'v>> {
                 // Read unconditionally: a command that declares nothing to check would
                 // otherwise leave the parameter unused in the user's crate, where
                 // nobody can silence it.
@@ -281,12 +309,12 @@ pub fn emit(cli: &Cli) -> TokenStream {
             /// and marks them given, which would hand a variable's value to the layer that
             /// outranks every other and name it after a flag nobody typed.
             pub fn read_argv<'v>(
-                command: &'static ::usage_argv::Command<'static>,
+                command: &'static usage_argv::Command<'static>,
                 argv: &'v [&'v ::std::ffi::OsStr],
-            ) -> ::std::result::Result<Partial, ::usage_argv::Error<'static, 'v>> {
+            ) -> ::std::result::Result<Partial, usage_argv::Error<'static, 'v>> {
                 #defaults
 
-                let mut __usage_parser = ::usage_argv::Parser::new(command, argv);
+                let mut __usage_parser = usage_argv::Parser::new(command, argv);
                 while let ::std::option::Option::Some(__usage_event) =
                     __usage_parser.next_event()
                 {
@@ -294,20 +322,20 @@ pub fn emit(cli: &Cli) -> TokenStream {
                     // Asked *before* the event is applied, and answered with the command in
                     // scope: `mise config --help` is a question about `config`, and the parser
                     // is what knows how deep the words reached.
-                    if let ::usage_argv::Event::Flag { flag, .. } = &__usage_event {
-                        if flag.key == ::usage_argv::HELP_LONG_KEY
-                            || flag.key == ::usage_argv::HELP_SHORT_KEY
+                    if let usage_argv::Event::Flag { flag, .. } = &__usage_event {
+                        if flag.key == usage_argv::HELP_LONG_KEY
+                            || flag.key == usage_argv::HELP_SHORT_KEY
                         {
-                            return ::std::result::Result::Err(::usage_argv::Error::Help {
+                            return ::std::result::Result::Err(usage_argv::Error::Help {
                                 cmd: __usage_parser.command(),
-                                long: flag.key == ::usage_argv::HELP_LONG_KEY,
+                                long: flag.key == usage_argv::HELP_LONG_KEY,
                             });
                         }
                         // Same shape, and for the same reason: a question rather than a
                         // failure, answered by whoever knows the version string.
-                        if ::usage_argv::is_version_flag(flag) {
+                        if usage_argv::is_version_flag(flag) {
                             return ::std::result::Result::Err(
-                                ::usage_argv::Error::Version,
+                                usage_argv::Error::Version,
                             );
                         }
                     }
@@ -327,9 +355,9 @@ pub fn emit(cli: &Cli) -> TokenStream {
             /// whether the flag was absent or negated — so the entry point that wants that reads
             /// the two halves apart instead.
             pub fn read<'v>(
-                command: &'static ::usage_argv::Command<'static>,
+                command: &'static usage_argv::Command<'static>,
                 argv: &'v [&'v ::std::ffi::OsStr],
-            ) -> ::std::result::Result<Partial, ::usage_argv::Error<'static, 'v>> {
+            ) -> ::std::result::Result<Partial, usage_argv::Error<'static, 'v>> {
                 let mut partial = read_argv(command, argv)?;
                 check(&mut partial)?;
                 ::std::result::Result::Ok(partial)
@@ -340,7 +368,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
             #settings_layer
             #settings_guard
 
-            pub static SPEC: ::usage_argv::spec::Spec = ::usage_argv::spec::Spec {
+            pub static SPEC: usage_argv::spec::Spec = usage_argv::spec::Spec {
                 name: #name,
                 bin: #bin,
                 version: #version,
@@ -356,12 +384,12 @@ pub fn emit(cli: &Cli) -> TokenStream {
                 ///
                 /// `static`, so reaching them costs nothing: there is no command tree
                 /// to build before a parse can start.
-                pub fn command() -> &'static ::usage_argv::Command<'static> {
+                pub fn command() -> &'static usage_argv::Command<'static> {
                     &ROOT
                 }
 
                 /// This CLI's spec, for emitting, documenting, or completing.
-                pub fn spec() -> &'static ::usage_argv::spec::Spec<'static> {
+                pub fn spec() -> &'static usage_argv::spec::Spec<'static> {
                     &SPEC
                 }
 
@@ -377,7 +405,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
                 /// Parse a command line, excluding the program name.
                 pub fn parse_from<'v>(
                     argv: &'v [&'v ::std::ffi::OsStr],
-                ) -> ::std::result::Result<Self, ::usage_argv::Error<'static, 'v>> {
+                ) -> ::std::result::Result<Self, usage_argv::Error<'static, 'v>> {
                     let partial = read(Self::command(), argv)?;
                     ::std::result::Result::Ok(Self {
                         #sub_build
@@ -401,7 +429,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
                     match Self::parse_from(&__usage_argv) {
                         ::std::result::Result::Ok(parsed) => parsed,
                         // Not failures: someone asked a question, and the answer goes to stdout.
-                        ::std::result::Result::Err(::usage_argv::Error::Version) => {
+                        ::std::result::Result::Err(usage_argv::Error::Version) => {
                             match (Self::spec().bin.unwrap_or(Self::spec().name), Self::spec().version) {
                                 (bin, ::std::option::Option::Some(version)) => {
                                     ::std::println!("{bin} {version}");
@@ -414,21 +442,21 @@ pub fn emit(cli: &Cli) -> TokenStream {
                                 }
                             }
                         }
-                        ::std::result::Result::Err(::usage_argv::Error::Help { cmd, long }) => {
+                        ::std::result::Result::Err(usage_argv::Error::Help { cmd, long }) => {
                             // By the route the words took, not by the command's address: one
                             // `Subcommands` type mounted under two parents is one address, and a
                             // page found by searching for it carries the first mount's path and
                             // globals. Falls back where the route cannot be rebuilt.
-                            let __usage_page = match ::usage_argv::help::route_to(
+                            let __usage_page = match usage_argv::help::route_to(
                                 Self::command(),
                                 &__usage_argv,
                                 cmd,
                             ) {
                                 ::std::option::Option::Some(route) => {
-                                    ::usage_argv::help::render_at(Self::spec(), &route, long)
+                                    usage_argv::help::render_at(Self::spec(), &route, long)
                                 }
                                 ::std::option::Option::None => {
-                                    ::usage_argv::help::render(Self::spec(), cmd, long)
+                                    usage_argv::help::render(Self::spec(), cmd, long)
                                 }
                             };
                             match __usage_page {
@@ -443,7 +471,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
                         ::std::result::Result::Err(e) => {
                             ::std::eprint!(
                                 "{}",
-                                ::usage_argv::render_failure(Self::spec(), &__usage_argv, &e)
+                                usage_argv::render_failure(Self::spec(), &__usage_argv, &e)
                             );
                             // clap's, so a script that checks for it keeps working.
                             ::std::process::exit(2);
@@ -476,7 +504,7 @@ fn flatten_checks(cli: &Cli) -> TokenStream {
         };
         Some(quote! {
             const _: () = ::core::assert!(
-                <#ty as ::usage_argv::spec::CommandArgs>::COMMAND.subcommands.is_empty(),
+                <#ty as usage_argv::spec::CommandArgs>::COMMAND.subcommands.is_empty(),
                 "a flattened group cannot declare subcommands: flatten joins flags and \
                  arguments into the parent's tables and leaves subcommands behind, so the \
                  command would require one that no word could select. Declare the \
@@ -495,10 +523,10 @@ fn flatten_checks(cli: &Cli) -> TokenStream {
 fn unknown_flags_tokens(cli: &Cli) -> TokenStream {
     match cli.unknown_flags.as_deref() {
         Some("error") => quote!(::core::option::Option::Some(
-            ::usage_argv::UnknownFlags::Error
+            usage_argv::UnknownFlags::Error
         )),
         Some(_) => quote!(::core::option::Option::Some(
-            ::usage_argv::UnknownFlags::Value
+            usage_argv::UnknownFlags::Value
         )),
         None => quote!(::core::option::Option::None),
     }
@@ -516,7 +544,7 @@ fn completion_fns(cli: &Cli) -> (TokenStream, TokenStream) {
     let functions = quote! {
         // Says what is missing, where the alternative is `unresolved module complete` — which
         // names the symptom and not the attribute that asked for it.
-        ::usage_argv::__usage_needs_complete_feature!();
+        usage_argv::__usage_needs_complete_feature!();
 
         /// This CLI's completion script for `shell`, to be written to a file or sourced.
         ///
@@ -524,10 +552,10 @@ fn completion_fns(cli: &Cli) -> (TokenStream, TokenStream) {
         /// script that names a command the binary does not answer a compile error instead of a
         /// silence at the prompt.
         pub fn completion_script(
-            shell: ::usage_argv::complete::Shell,
+            shell: usage_argv::complete::Shell,
         ) -> ::std::string::String {
             let spec = Self::spec();
-            ::usage_argv::script::script(spec.bin.unwrap_or(spec.name), shell)
+            usage_argv::script::script(spec.bin.unwrap_or(spec.name), shell)
         }
 
         /// The word a shell is completing, answered from this CLI's own tables.
@@ -544,7 +572,7 @@ fn completion_fns(cli: &Cli) -> (TokenStream, TokenStream) {
             }
             // Its own flags, read by hand: three of them, and reading them with the parser
             // would mean putting them in the tables this is deliberately outside of.
-            let mut shell = ::usage_argv::complete::Shell::Bash;
+            let mut shell = usage_argv::complete::Shell::Bash;
             let mut line = ::std::string::String::new();
             let mut cursor = ::std::option::Option::None;
             let mut candidates_for: ::std::option::Option<::std::string::String> =
@@ -555,7 +583,7 @@ fn completion_fns(cli: &Cli) -> (TokenStream, TokenStream) {
                     "--shell" => {
                         if let ::std::option::Option::Some(name) = rest.next() {
                             if let ::std::option::Option::Some(found) =
-                                ::usage_argv::complete::Shell::from_name(
+                                usage_argv::complete::Shell::from_name(
                                     &name.to_string_lossy(),
                                 )
                             {
@@ -589,23 +617,23 @@ fn completion_fns(cli: &Cli) -> (TokenStream, TokenStream) {
             // No cursor means the end of the line, which is where a shell puts it when it has
             // no way to say — nushell, whose completer only ever sees the words.
             let cursor = cursor.unwrap_or(line.len());
-            let split = ::usage_argv::complete::split(&line, cursor, shell);
+            let split = usage_argv::complete::split(&line, cursor, shell);
             if let ::std::option::Option::Some(name) = candidates_for {
                 // Walked here as well, because a `--candidates` request names a completer and
                 // says nothing about where the cursor is — and the completer still wants the
                 // words its own command was given.
                 let position =
-                    ::usage_argv::complete::walk(Self::spec().root.cmd, split.argv());
+                    usage_argv::complete::walk(Self::spec().root.cmd, split.argv());
                 let __usage_words = split.argv();
                 let __usage_path: ::std::vec::Vec<(
-                    &::usage_argv::Command<'_>,
+                    &usage_argv::Command<'_>,
                     &[::std::string::String],
                 )> = position
                     .path
                     .iter()
                     .map(|(cmd, start)| (*cmd, __usage_words.get(*start..).unwrap_or(&[])))
                     .collect();
-                let ctx = ::usage_argv::complete::CompleteCtx {
+                let ctx = usage_argv::complete::CompleteCtx {
                     words: &split.words,
                     cword: split.cword,
                     prefix: &split.prefix,
@@ -618,15 +646,15 @@ fn completion_fns(cli: &Cli) -> (TokenStream, TokenStream) {
                 // against a newer version of this CLI is a stale script, and a stale script
                 // should complete nothing rather than print a message into the user's prompt.
                 let found =
-                    ::usage_argv::complete::for_name(Self::spec(), &name, &ctx).unwrap_or_default();
-                let answer = ::usage_argv::complete::Completions {
+                    usage_argv::complete::for_name(Self::spec(), &name, &ctx).unwrap_or_default();
+                let answer = usage_argv::complete::Completions {
                     candidates: found,
                     files: ::std::option::Option::None,
                 };
-                return ::std::option::Option::Some(::usage_argv::complete::render(&answer, shell));
+                return ::std::option::Option::Some(usage_argv::complete::render(&answer, shell));
             }
-            let answer = ::usage_argv::complete::complete(Self::spec(), &split);
-            ::std::option::Option::Some(::usage_argv::complete::render(&answer, shell))
+            let answer = usage_argv::complete::complete(Self::spec(), &split);
+            ::std::option::Option::Some(usage_argv::complete::render(&answer, shell))
         }
     };
     let intercept = quote! {
@@ -676,7 +704,7 @@ fn flag_table(i: usize, field: &Field) -> TokenStream {
     };
 
     quote! {
-        pub static #name: ::usage_argv::Flag = ::usage_argv::Flag {
+        pub static #name: usage_argv::Flag = usage_argv::Flag {
             key: #key,
             name: #field_name,
             longs: &[#(#longs),*],
@@ -699,10 +727,10 @@ fn arg_table(i: usize, field: &Field) -> TokenStream {
         unreachable!("filtered by the caller");
     };
     let double_dash = match double_dash {
-        DoubleDash::Optional => quote!(::usage_argv::DoubleDash::Optional),
-        DoubleDash::Required => quote!(::usage_argv::DoubleDash::Required),
-        DoubleDash::Preserve => quote!(::usage_argv::DoubleDash::Preserve),
-        DoubleDash::Automatic => quote!(::usage_argv::DoubleDash::Automatic),
+        DoubleDash::Optional => quote!(usage_argv::DoubleDash::Optional),
+        DoubleDash::Required => quote!(usage_argv::DoubleDash::Required),
+        DoubleDash::Preserve => quote!(usage_argv::DoubleDash::Preserve),
+        DoubleDash::Automatic => quote!(usage_argv::DoubleDash::Automatic),
     };
     // A bound stops the variadic while binding, so the argument after it is reachable.
     let var_max = match field.var_max.filter(|_| var) {
@@ -715,7 +743,7 @@ fn arg_table(i: usize, field: &Field) -> TokenStream {
     };
 
     quote! {
-        pub static #name: ::usage_argv::Arg = ::usage_argv::Arg {
+        pub static #name: usage_argv::Arg = usage_argv::Arg {
             key: #key,
             name: #field_name,
             var: #var,
@@ -750,8 +778,8 @@ fn completer_tokens(
     let completer_path = path;
     let decl = quote! {
         fn #wrapper(
-            ctx: &::usage_argv::complete::CompleteCtx<'_>,
-        ) -> ::std::vec::Vec<::usage_argv::complete::Candidate<'static>> {
+            ctx: &usage_argv::complete::CompleteCtx<'_>,
+        ) -> ::std::vec::Vec<usage_argv::complete::Candidate<'static>> {
             // The words this command was given, parsed against this command's own tables — so
             // what the callback reads is what the parser would have bound, rather than a slice
             // of the line it has to interpret itself.
@@ -760,7 +788,7 @@ fn completer_tokens(
             // subcommand's words against the ancestor's tables would drop everything the
             // ancestor was given before the subcommand's name.
             let __usage_declaration =
-                <#owner as ::usage_argv::spec::CommandArgs>::COMMAND;
+                <#owner as usage_argv::spec::CommandArgs>::COMMAND;
             let (__usage_command, __usage_words) = ctx
                 .command_for(__usage_declaration)
                 .unwrap_or((__usage_declaration, ctx.command_words));
@@ -770,8 +798,8 @@ fn completer_tokens(
                 .collect();
             let __usage_argv: ::std::vec::Vec<&::std::ffi::OsStr> =
                 __usage_owned.iter().map(|a| a.as_os_str()).collect();
-            let mut partial = <#owner as ::usage_argv::spec::CommandArgs>::start();
-            let mut parser = ::usage_argv::Parser::new(
+            let mut partial = <#owner as usage_argv::spec::CommandArgs>::start();
+            let mut parser = usage_argv::Parser::new(
                 __usage_command,
                 &__usage_argv,
             );
@@ -780,7 +808,7 @@ fn completer_tokens(
             while let ::std::option::Option::Some(event) = parser.next_event() {
                 match event {
                     ::std::result::Result::Ok(event) => {
-                        let _ = <#owner as ::usage_argv::spec::CommandArgs>::apply(
+                        let _ = <#owner as usage_argv::spec::CommandArgs>::apply(
                             &mut partial,
                             &event,
                         );
@@ -834,7 +862,7 @@ fn flag_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
         .unwrap_or_else(|| quote!(::core::option::Option::None));
     quote! {
         #completer_decl
-        pub static #name: ::usage_argv::spec::FlagMeta = ::usage_argv::spec::FlagMeta {
+        pub static #name: usage_argv::spec::FlagMeta = usage_argv::spec::FlagMeta {
             effect: #effect,
             complete: #completer,
             complete_type: #complete_type,
@@ -857,7 +885,7 @@ fn flag_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
             requires: &[#(#requires),*],
             required_if: &[#(#required_if),*],
             required_unless: &[#(#required_unless),*],
-            ..::usage_argv::spec::FlagMeta::EMPTY
+            ..usage_argv::spec::FlagMeta::EMPTY
         };
     }
 }
@@ -883,7 +911,7 @@ fn arg_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
 
     quote! {
         #completer_decl
-        pub static #name: ::usage_argv::spec::ArgMeta = ::usage_argv::spec::ArgMeta {
+        pub static #name: usage_argv::spec::ArgMeta = usage_argv::spec::ArgMeta {
             complete: #completer,
             complete_type: #complete_type,
             arg: &#table,
@@ -897,7 +925,7 @@ fn arg_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
             choices: #choices,
             var_min: #var_min,
             var_max: #var_max,
-            ..::usage_argv::spec::ArgMeta::EMPTY
+            ..usage_argv::spec::ArgMeta::EMPTY
         };
     }
 }
@@ -907,7 +935,7 @@ fn choices_tokens(field: &Field) -> TokenStream {
     // From the type when the field says `value_enum`, so the spec, the help and the check
     // all read the list the type declares rather than a copy of it.
     if let (true, Some(ty)) = (field.value_enum, field.value_ty.as_ref()) {
-        return quote!(<#ty as ::usage_argv::spec::ValueEnum>::CHOICES);
+        return quote!(<#ty as usage_argv::spec::ValueEnum>::CHOICES);
     }
     let choices = &field.choices;
     quote!(&[#(#choices),*])
@@ -971,7 +999,7 @@ fn key_consts(fingerprint: &str, flags: usize, args: usize) -> TokenStream {
     });
     quote! {
         const __USAGE_KEY_BASE: u64 =
-            ::usage_argv::key_base(::core::module_path!(), #declaration);
+            usage_argv::key_base(::core::module_path!(), #declaration);
         const #command: u64 = __USAGE_KEY_BASE | #KIND_COMMAND;
         #(#flag_keys)*
         #(#arg_keys)*
@@ -1071,10 +1099,10 @@ fn tables(cli: &Cli) -> Tables {
                 flattened = true;
                 flush_flags(&mut own_flags, &mut flag_groups, &mut flag_meta_groups);
                 flush_args(&mut own_args, &mut arg_groups, &mut arg_meta_groups);
-                flag_groups.push(quote!(<#ty as ::usage_argv::spec::CommandArgs>::COMMAND.flags));
-                arg_groups.push(quote!(<#ty as ::usage_argv::spec::CommandArgs>::COMMAND.args));
-                flag_meta_groups.push(quote!(<#ty as ::usage_argv::spec::CommandArgs>::META.flags));
-                arg_meta_groups.push(quote!(<#ty as ::usage_argv::spec::CommandArgs>::META.args));
+                flag_groups.push(quote!(<#ty as usage_argv::spec::CommandArgs>::COMMAND.flags));
+                arg_groups.push(quote!(<#ty as usage_argv::spec::CommandArgs>::COMMAND.args));
+                flag_meta_groups.push(quote!(<#ty as usage_argv::spec::CommandArgs>::META.flags));
+                arg_meta_groups.push(quote!(<#ty as usage_argv::spec::CommandArgs>::META.args));
             }
             Kind::Subcommand { .. } => {}
         }
@@ -1106,25 +1134,25 @@ fn tables(cli: &Cli) -> Tables {
 
     Tables {
         decls: quote! {
-            const FLAG_GROUPS: &[&[&::usage_argv::Flag<'static>]] = &[#(#flag_groups),*];
-            const ARG_GROUPS: &[&[&::usage_argv::Arg<'static>]] = &[#(#arg_groups),*];
-            static FLAGS: [&::usage_argv::Flag<'static>;
-                ::usage_argv::table_len(FLAG_GROUPS)] =
-                ::usage_argv::concat_flags(FLAG_GROUPS);
-            static ARGS: [&::usage_argv::Arg<'static>; ::usage_argv::table_len(ARG_GROUPS)] =
-                ::usage_argv::concat_args(ARG_GROUPS);
+            const FLAG_GROUPS: &[&[&usage_argv::Flag<'static>]] = &[#(#flag_groups),*];
+            const ARG_GROUPS: &[&[&usage_argv::Arg<'static>]] = &[#(#arg_groups),*];
+            static FLAGS: [&usage_argv::Flag<'static>;
+                usage_argv::table_len(FLAG_GROUPS)] =
+                usage_argv::concat_flags(FLAG_GROUPS);
+            static ARGS: [&usage_argv::Arg<'static>; usage_argv::table_len(ARG_GROUPS)] =
+                usage_argv::concat_args(ARG_GROUPS);
         },
         meta_decls: quote! {
-            const FLAG_META_GROUPS: &[&[::usage_argv::spec::FlagMeta<'static>]] =
+            const FLAG_META_GROUPS: &[&[usage_argv::spec::FlagMeta<'static>]] =
                 &[#(#flag_meta_groups),*];
-            const ARG_META_GROUPS: &[&[::usage_argv::spec::ArgMeta<'static>]] =
+            const ARG_META_GROUPS: &[&[usage_argv::spec::ArgMeta<'static>]] =
                 &[#(#arg_meta_groups),*];
-            static FLAG_METAS: [::usage_argv::spec::FlagMeta<'static>;
-                ::usage_argv::table_len(FLAG_META_GROUPS)] =
-                ::usage_argv::spec::concat_flag_metas(FLAG_META_GROUPS);
-            static ARG_METAS: [::usage_argv::spec::ArgMeta<'static>;
-                ::usage_argv::table_len(ARG_META_GROUPS)] =
-                ::usage_argv::spec::concat_arg_metas(ARG_META_GROUPS);
+            static FLAG_METAS: [usage_argv::spec::FlagMeta<'static>;
+                usage_argv::table_len(FLAG_META_GROUPS)] =
+                usage_argv::spec::concat_flag_metas(FLAG_META_GROUPS);
+            static ARG_METAS: [usage_argv::spec::ArgMeta<'static>;
+                usage_argv::table_len(ARG_META_GROUPS)] =
+                usage_argv::spec::concat_arg_metas(ARG_META_GROUPS);
         },
         flags: quote!(&FLAGS),
         args: quote!(&ARGS),
@@ -1321,7 +1349,7 @@ fn partial_struct(cli: &Cli) -> TokenStream {
         if let Kind::Flatten { ty } = &f.kind {
             let ident = &f.ident;
             return Some(quote! {
-                pub #ident: <#ty as ::usage_argv::spec::CommandArgs>::Partial,
+                pub #ident: <#ty as usage_argv::spec::CommandArgs>::Partial,
             });
         }
         let ident = &f.ident;
@@ -1395,10 +1423,10 @@ fn given_value(field: &Field) -> TokenStream {
         // The bool the parser landed on, which is `false` for a negation and `true` for the flag
         // itself: what the user said, rather than that they said something.
         Shape::Bool => quote! {
-            ::usage_argv::spec::SettingGiven::Bool(partial.#ident)
+            usage_argv::spec::SettingGiven::Bool(partial.#ident)
         },
         Shape::Count => quote! {
-            ::usage_argv::spec::SettingGiven::Int(
+            usage_argv::spec::SettingGiven::Int(
                 ::std::convert::TryFrom::try_from(partial.#ident)
                     .unwrap_or(::std::primitive::i64::MAX),
             )
@@ -1406,21 +1434,21 @@ fn given_value(field: &Field) -> TokenStream {
         Shape::Optional => quote! {
             match ::std::str::from_utf8(partial.#ident.as_deref().unwrap_or_default()) {
                 ::std::result::Result::Ok(__usage_text) => {
-                    ::usage_argv::spec::SettingGiven::Text(
+                    usage_argv::spec::SettingGiven::Text(
                         ::std::string::ToString::to_string(__usage_text),
                     )
                 }
-                ::std::result::Result::Err(_) => ::usage_argv::spec::SettingGiven::NotText,
+                ::std::result::Result::Err(_) => usage_argv::spec::SettingGiven::NotText,
             }
         },
         Shape::Required => quote! {
             match ::std::str::from_utf8(&partial.#ident) {
                 ::std::result::Result::Ok(__usage_text) => {
-                    ::usage_argv::spec::SettingGiven::Text(
+                    usage_argv::spec::SettingGiven::Text(
                         ::std::string::ToString::to_string(__usage_text),
                     )
                 }
-                ::std::result::Result::Err(_) => ::usage_argv::spec::SettingGiven::NotText,
+                ::std::result::Result::Err(_) => usage_argv::spec::SettingGiven::NotText,
             }
         },
         // Item by item, rather than joined and re-split: an item holding the separator would come
@@ -1438,9 +1466,9 @@ fn given_value(field: &Field) -> TokenStream {
                 .collect::<::std::option::Option<::std::vec::Vec<_>>>()
             {
                 ::std::option::Option::Some(__usage_items) => {
-                    ::usage_argv::spec::SettingGiven::List(__usage_items)
+                    usage_argv::spec::SettingGiven::List(__usage_items)
                 }
-                ::std::option::Option::None => ::usage_argv::spec::SettingGiven::NotText,
+                ::std::option::Option::None => usage_argv::spec::SettingGiven::NotText,
             }
         },
     }
@@ -1486,17 +1514,17 @@ fn children(cli: &Cli) -> Vec<(TokenStream, TokenStream)> {
             let ident = &field.ident;
             match &field.kind {
                 Kind::Flatten { ty } => Some((
-                    quote!(<#ty as ::usage_argv::spec::CommandArgs>::SETTINGS_BINDINGS),
+                    quote!(<#ty as usage_argv::spec::CommandArgs>::SETTINGS_BINDINGS),
                     quote! {
-                        <#ty as ::usage_argv::spec::CommandArgs>::settings_given(
+                        <#ty as usage_argv::spec::CommandArgs>::settings_given(
                             &partial.#ident,
                         )
                     },
                 )),
                 Kind::Subcommand { ty, .. } => Some((
-                    quote!(<#ty as ::usage_argv::spec::Subcommands>::SETTINGS_BINDINGS),
+                    quote!(<#ty as usage_argv::spec::Subcommands>::SETTINGS_BINDINGS),
                     quote! {
-                        <#ty as ::usage_argv::spec::Subcommands>::settings_given(
+                        <#ty as usage_argv::spec::Subcommands>::settings_given(
                             &partial.__usage_sub,
                             partial.__usage_selected,
                         )
@@ -1522,7 +1550,7 @@ fn joined_bindings(own: &[TokenStream], children: &[TokenStream]) -> TokenStream
             const PARTS: &[&'static [(&'static str, &'static str)]] = &[OWN #(, #children)*];
             const N: usize = OWN.len() #(+ #children.len())*;
             const JOINED: [(&'static str, &'static str); N] =
-                ::usage_argv::spec::concat_bindings(PARTS);
+                usage_argv::spec::concat_bindings(PARTS);
             &JOINED
         }
     }
@@ -1562,7 +1590,7 @@ fn settings(cli: &Cli) -> Option<Settings> {
         /// The settings this command line gave values for.
         pub fn settings_given(
             partial: &Partial,
-        ) -> ::std::vec::Vec<(&'static str, ::usage_argv::spec::SettingGiven)> {
+        ) -> ::std::vec::Vec<(&'static str, usage_argv::spec::SettingGiven)> {
             let mut __usage_given = ::std::vec::Vec::new();
             #(#contributions)*
             #(#from_children)*
@@ -1597,17 +1625,17 @@ fn settings_layer() -> TokenStream {
             );
             for (__usage_key, __usage_given) in settings_given(partial) {
                 __usage_layer = match __usage_given {
-                    ::usage_argv::spec::SettingGiven::Bool(__usage_value) => {
+                    usage_argv::spec::SettingGiven::Bool(__usage_value) => {
                         __usage_layer.with_value(__usage_key, ::usage_config::Value::Bool(__usage_value))
                     }
-                    ::usage_argv::spec::SettingGiven::Int(__usage_value) => {
+                    usage_argv::spec::SettingGiven::Int(__usage_value) => {
                         __usage_layer.with_value(__usage_key, ::usage_config::Value::Int(__usage_value))
                     }
-                    ::usage_argv::spec::SettingGiven::Text(__usage_value) => {
+                    usage_argv::spec::SettingGiven::Text(__usage_value) => {
                         __usage_layer
                             .with_value(__usage_key, ::usage_config::Value::String(__usage_value))
                     }
-                    ::usage_argv::spec::SettingGiven::List(__usage_items) => __usage_layer.with_value(
+                    usage_argv::spec::SettingGiven::List(__usage_items) => __usage_layer.with_value(
                         __usage_key,
                         ::usage_config::Value::List(
                             __usage_items
@@ -1616,7 +1644,7 @@ fn settings_layer() -> TokenStream {
                                 .collect(),
                         ),
                     ),
-                    ::usage_argv::spec::SettingGiven::NotText => {
+                    usage_argv::spec::SettingGiven::NotText => {
                         __usage_layer.with_unrepresentable(__usage_key)
                     }
                 };
@@ -1668,7 +1696,7 @@ fn partial_defaults(cli: &Cli) -> TokenStream {
         if let Kind::Flatten { ty } = &f.kind {
             let ident = &f.ident;
             return Some(quote! {
-                #ident: <#ty as ::usage_argv::spec::CommandArgs>::start(),
+                #ident: <#ty as usage_argv::spec::CommandArgs>::start(),
             });
         }
         let ident = &f.ident;
@@ -1718,7 +1746,7 @@ fn field_final(field: &Field) -> TokenStream {
         // the same call at every level.
         //
         return quote! {
-            #ident: <#ty as ::usage_argv::spec::CommandArgs>::build(partial.#ident)?
+            #ident: <#ty as usage_argv::spec::CommandArgs>::build(partial.#ident)?
         };
     }
     let Some(ty) = field.value_ty.as_ref() else {
@@ -1767,12 +1795,12 @@ fn field_final(field: &Field) -> TokenStream {
         // replaced by a different filename.
         let one = |value: TokenStream| {
             quote! {
-                match ::usage_argv::os_string_from_bytes(#value) {
+                match usage_argv::os_string_from_bytes(#value) {
                     ::std::result::Result::Ok(__usage_os) => #build(__usage_os),
                     ::std::result::Result::Err(__usage_bytes) => {
                         return ::std::result::Result::Err(
-                            ::usage_argv::Error::InvalidValue(::std::boxed::Box::new(
-                                ::usage_argv::InvalidValue {
+                            usage_argv::Error::InvalidValue(::std::boxed::Box::new(
+                                usage_argv::InvalidValue {
                                     name: #name,
                                     value: ::std::string::String::from_utf8_lossy(
                                         &__usage_bytes,
@@ -1846,8 +1874,8 @@ fn field_final(field: &Field) -> TokenStream {
                 ::std::result::Result::Ok(text) => text,
                 ::std::result::Result::Err(bad) => {
                     return ::std::result::Result::Err(
-                        ::usage_argv::Error::InvalidValue(::std::boxed::Box::new(
-                            ::usage_argv::InvalidValue {
+                        usage_argv::Error::InvalidValue(::std::boxed::Box::new(
+                            usage_argv::InvalidValue {
                                 name: #name,
                                 value: ::std::string::String::from_utf8_lossy(
                                     bad.as_bytes(),
@@ -1869,8 +1897,8 @@ fn field_final(field: &Field) -> TokenStream {
                 ::std::result::Result::Ok(parsed) => parsed,
                 ::std::result::Result::Err(reason) => {
                     return ::std::result::Result::Err(
-                        ::usage_argv::Error::InvalidValue(::std::boxed::Box::new(
-                            ::usage_argv::InvalidValue {
+                        usage_argv::Error::InvalidValue(::std::boxed::Box::new(
+                            usage_argv::InvalidValue {
                                 name: #name,
                                 value: __usage_text,
                                 reason: ::std::string::ToString::to_string(&reason),
@@ -1990,7 +2018,7 @@ fn apply_fn(cli: &Cli) -> TokenStream {
         };
         let ident = &f.ident;
         Some(quote! {
-            if <#ty as ::usage_argv::spec::CommandArgs>::apply(&mut partial.#ident, event) {
+            if <#ty as usage_argv::spec::CommandArgs>::apply(&mut partial.#ident, event) {
                 return true;
             }
         })
@@ -2011,9 +2039,9 @@ fn apply_fn(cli: &Cli) -> TokenStream {
     quote! {
         pub fn apply(
             partial: &mut Partial,
-            event: &::usage_argv::Event<'_, '_>,
+            event: &usage_argv::Event<'_, '_>,
         ) -> bool {
-            use ::usage_argv::Event;
+            use usage_argv::Event;
             #route
             #(#flattened)*
             // Each arm evaluates to whether it claimed the event, rather than
@@ -2080,7 +2108,7 @@ fn subcommand_parts(cli: &Cli) -> Option<SubcommandParts> {
     let selected = quote! {
         match partial.__usage_selected {
             ::std::option::Option::Some(__usage_at) => {
-                <#ty as ::usage_argv::spec::Subcommands>::select(
+                <#ty as usage_argv::spec::Subcommands>::select(
                     partial.__usage_sub,
                     __usage_at,
                 )?
@@ -2096,7 +2124,7 @@ fn subcommand_parts(cli: &Cli) -> Option<SubcommandParts> {
                 ::std::option::Option::Some(__usage_cmd) => __usage_cmd,
                 ::std::option::Option::None => {
                     return ::std::result::Result::Err(
-                        ::usage_argv::Error::MissingSubcommand,
+                        usage_argv::Error::MissingSubcommand,
                     );
                 }
             },
@@ -2104,7 +2132,7 @@ fn subcommand_parts(cli: &Cli) -> Option<SubcommandParts> {
     };
 
     Some(SubcommandParts {
-        commands: quote!(subcommands: <#ty as ::usage_argv::spec::Subcommands>::COMMANDS,),
+        commands: quote!(subcommands: <#ty as usage_argv::spec::Subcommands>::COMMANDS,),
         // Resolved from the name at compile time. The variants are another expansion, so the
         // name is all there is to go on here — but `find_subcommand` searches the list during
         // const evaluation, which means a name no subcommand answers to fails to compile
@@ -2112,17 +2140,17 @@ fn subcommand_parts(cli: &Cli) -> Option<SubcommandParts> {
         default: match cli.default_subcommand.as_deref() {
             ::std::option::Option::Some(name) => quote! {
                 default_subcommand: ::std::option::Option::Some(
-                    ::usage_argv::find_subcommand(
-                        <#ty as ::usage_argv::spec::Subcommands>::COMMANDS,
+                    usage_argv::find_subcommand(
+                        <#ty as usage_argv::spec::Subcommands>::COMMANDS,
                         #name,
                     ),
                 ),
             },
             ::std::option::Option::None => TokenStream::new(),
         },
-        metas: quote!(subcommands: <#ty as ::usage_argv::spec::Subcommands>::METAS,),
+        metas: quote!(subcommands: <#ty as usage_argv::spec::Subcommands>::METAS,),
         partial_fields: quote! {
-            pub __usage_sub: <#ty as ::usage_argv::spec::Subcommands>::Partial,
+            pub __usage_sub: <#ty as usage_argv::spec::Subcommands>::Partial,
             /// Which of this command's subcommands was reached, as a position in
             /// `COMMANDS`. Found from the table's own address, so it cannot be
             /// confused by a key collision.
@@ -2137,9 +2165,9 @@ fn subcommand_parts(cli: &Cli) -> Option<SubcommandParts> {
             // subcommands answers to it: a deeper descent belongs to whoever owns
             // that command, and recording it here would make the wrong variant look
             // selected.
-            if let ::usage_argv::Event::Command(__usage_cmd) = event {
+            if let usage_argv::Event::Command(__usage_cmd) = event {
                 if let ::std::option::Option::Some(__usage_at) =
-                    <#ty as ::usage_argv::spec::Subcommands>::COMMANDS
+                    <#ty as usage_argv::spec::Subcommands>::COMMANDS
                         .iter()
                         .position(|candidate| ::core::ptr::eq(*candidate, *__usage_cmd))
                 {
@@ -2149,7 +2177,7 @@ fn subcommand_parts(cli: &Cli) -> Option<SubcommandParts> {
             // Only the selected one is asked — see `Subcommands::apply`. The selection is
             // set just above, so a command word reaches the command it named on the same
             // event that selected it.
-            if <#ty as ::usage_argv::spec::Subcommands>::apply(
+            if <#ty as usage_argv::spec::Subcommands>::apply(
                 &mut partial.__usage_sub,
                 partial.__usage_selected,
                 event,
@@ -2159,7 +2187,7 @@ fn subcommand_parts(cli: &Cli) -> Option<SubcommandParts> {
         },
         check: quote! {
             if let ::std::option::Option::Some(__usage_at) = partial.__usage_selected {
-                <#ty as ::usage_argv::spec::Subcommands>::check(
+                <#ty as usage_argv::spec::Subcommands>::check(
                     &mut partial.__usage_sub,
                     __usage_at,
                 )?;
@@ -2173,6 +2201,7 @@ fn subcommand_parts(cli: &Cli) -> Option<SubcommandParts> {
 /// parent reach them.
 pub fn emit_args(cli: &Cli) -> TokenStream {
     let ident = &cli.ident;
+    let runtime = runtime_path();
     // A group carries settings the same way a root does, minus the layer: `SettingGiven` is
     // usage-argv's own vocabulary, so a flattened group can hand its parent what it was given
     // without either of them naming the config crate. Emitted whenever it has anything to say —
@@ -2190,7 +2219,7 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
 
             fn settings_given(
                 partial: &Self::Partial,
-            ) -> ::std::vec::Vec<(&'static str, ::usage_argv::spec::SettingGiven)> {
+            ) -> ::std::vec::Vec<(&'static str, usage_argv::spec::SettingGiven)> {
                 settings_given(partial)
             }
         }
@@ -2291,13 +2320,15 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
             clippy::needless_update
         )]
         const _: () = {
+            use #runtime as usage_argv;
+
             #flatten_checks
             #keys
             #(#flag_tables)*
             #(#arg_tables)*
             #table_decls
 
-            pub static COMMAND: ::usage_argv::Command = ::usage_argv::Command {
+            pub static COMMAND: usage_argv::Command = usage_argv::Command {
                 name: #name,
                 aliases: &[#(#aliases),*],
                 key: #command_key,
@@ -2305,14 +2336,14 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
                 flags: #flag_table_ref,
                 args: #arg_table_ref,
                 #sub_commands
-                ..::usage_argv::Command::EMPTY
+                ..usage_argv::Command::EMPTY
             };
 
             #(#flag_metas)*
             #(#arg_metas)*
             #meta_table_decls
 
-            pub static COMMAND_META: ::usage_argv::spec::CommandMeta = ::usage_argv::spec::CommandMeta {
+            pub static COMMAND_META: usage_argv::spec::CommandMeta = usage_argv::spec::CommandMeta {
                 cmd: &COMMAND,
                 effect: #effect,
                 about: #about,
@@ -2328,7 +2359,7 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
                 flags: #flag_meta_table_ref,
                 args: #arg_meta_table_ref,
                 #sub_metas
-                ..::usage_argv::spec::CommandMeta::EMPTY
+                ..usage_argv::spec::CommandMeta::EMPTY
             };
 
             pub fn __usage_text(value: &[u8]) -> ::std::vec::Vec<u8> {
@@ -2356,7 +2387,7 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
             /// an invocation that ran `run`.
             pub fn check<'t, 'v>(
                 partial: &mut Partial,
-            ) -> ::std::result::Result<(), ::usage_argv::Error<'t, 'v>> {
+            ) -> ::std::result::Result<(), usage_argv::Error<'t, 'v>> {
                 // Read unconditionally: a command that declares nothing to check would
                 // otherwise leave the parameter unused in the user's crate, where
                 // nobody can silence it.
@@ -2367,11 +2398,11 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
 
             #settings_defs
 
-            impl ::usage_argv::spec::CommandArgs for #ident {
+            impl usage_argv::spec::CommandArgs for #ident {
                 type Partial = Partial;
 
-                const COMMAND: &'static ::usage_argv::Command<'static> = &COMMAND;
-                const META: &'static ::usage_argv::spec::CommandMeta<'static> =
+                const COMMAND: &'static usage_argv::Command<'static> = &COMMAND;
+                const META: &'static usage_argv::spec::CommandMeta<'static> =
                     &COMMAND_META;
 
                 fn start() -> Self::Partial {
@@ -2380,14 +2411,14 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
 
                 fn apply(
                     partial: &mut Self::Partial,
-                    event: &::usage_argv::Event<'_, '_>,
+                    event: &usage_argv::Event<'_, '_>,
                 ) -> bool {
                     apply(partial, event)
                 }
 
                 fn check<'t, 'v>(
                     partial: &mut Self::Partial,
-                ) -> ::std::result::Result<(), ::usage_argv::Error<'t, 'v>> {
+                ) -> ::std::result::Result<(), usage_argv::Error<'t, 'v>> {
                     check(partial)
                 }
 
@@ -2395,7 +2426,7 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
 
                 fn build<'t, 'v>(
                     partial: Self::Partial,
-                ) -> ::std::result::Result<Self, ::usage_argv::Error<'t, 'v>> {
+                ) -> ::std::result::Result<Self, usage_argv::Error<'t, 'v>> {
                     ::std::result::Result::Ok(Self {
                         #sub_build
                         #(#field_finals),*
@@ -2410,6 +2441,7 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
 /// parent uses to route events into them.
 pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
     let ident = &subs.ident;
+    let runtime = runtime_path();
 
     // The structs the bare variants imply, written here so everything downstream keeps
     // speaking to a struct. `Args` is derived on them rather than the impl being written out:
@@ -2442,19 +2474,19 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
     let partial_fields = subs.variants.iter().enumerate().map(|(i, v)| {
         let field = format_ident!("v{i}");
         let ty = &v.ty;
-        quote!(pub #field: <#ty as ::usage_argv::spec::CommandArgs>::Partial,)
+        quote!(pub #field: <#ty as usage_argv::spec::CommandArgs>::Partial,)
     });
     let partial_starts = subs.variants.iter().enumerate().map(|(i, v)| {
         let field = format_ident!("v{i}");
         let ty = &v.ty;
-        quote!(#field: <#ty as ::usage_argv::spec::CommandArgs>::start(),)
+        quote!(#field: <#ty as usage_argv::spec::CommandArgs>::start(),)
     });
     let applies = subs.variants.iter().enumerate().map(|(i, v)| {
         let field = format_ident!("v{i}");
         let ty = &v.ty;
         quote! {
             ::std::option::Option::Some(#i) => {
-                <#ty as ::usage_argv::spec::CommandArgs>::apply(&mut partial.#field, event)
+                <#ty as usage_argv::spec::CommandArgs>::apply(&mut partial.#field, event)
             }
         }
     });
@@ -2473,15 +2505,15 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
         let aliases = v.aliases.iter().chain(&v.hidden_aliases);
         quote! {
             const #alias_groups: &[&[&str]] = &[
-                <#ty as ::usage_argv::spec::CommandArgs>::COMMAND.aliases,
+                <#ty as usage_argv::spec::CommandArgs>::COMMAND.aliases,
                 &[#(#aliases),*],
             ];
-            static #aliases_name: [&str; ::usage_argv::table_len(#alias_groups)] =
-                ::usage_argv::spec::concat_aliases(#alias_groups);
-            pub static #name: ::usage_argv::Command = ::usage_argv::Command {
+            static #aliases_name: [&str; usage_argv::table_len(#alias_groups)] =
+                usage_argv::spec::concat_aliases(#alias_groups);
+            pub static #name: usage_argv::Command = usage_argv::Command {
                 name: #cmd_name,
                 aliases: &#aliases_name,
-                ..*<#ty as ::usage_argv::spec::CommandArgs>::COMMAND
+                ..*<#ty as usage_argv::spec::CommandArgs>::COMMAND
             };
         }
     });
@@ -2512,11 +2544,11 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
         // long form went missing from help for every command written that way.
         let about = match v.help.as_deref() {
             Some(help) => option_str(Some(help)),
-            None => quote!(<#ty as ::usage_argv::spec::CommandArgs>::META.about),
+            None => quote!(<#ty as usage_argv::spec::CommandArgs>::META.about),
         };
         let long_about = match v.long_help.as_deref() {
             Some(long) => option_str(Some(long)),
-            None => quote!(<#ty as ::usage_argv::spec::CommandArgs>::META.long_about),
+            None => quote!(<#ty as usage_argv::spec::CommandArgs>::META.long_about),
         };
         // Which of the table's aliases are hidden. The visible ones are not listed
         // anywhere: `cmd.aliases` minus these is what help and completions show.
@@ -2526,19 +2558,19 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
         let hide = v.hide;
         quote! {
             const #hidden_groups: &[&[&str]] = &[
-                <#ty as ::usage_argv::spec::CommandArgs>::META.hidden_aliases,
+                <#ty as usage_argv::spec::CommandArgs>::META.hidden_aliases,
                 &[#(#hidden),*],
             ];
-            static #hidden_name: [&str; ::usage_argv::table_len(#hidden_groups)] =
-                ::usage_argv::spec::concat_aliases(#hidden_groups);
-            pub static #name: ::usage_argv::spec::CommandMeta =
-                ::usage_argv::spec::CommandMeta {
+            static #hidden_name: [&str; usage_argv::table_len(#hidden_groups)] =
+                usage_argv::spec::concat_aliases(#hidden_groups);
+            pub static #name: usage_argv::spec::CommandMeta =
+                usage_argv::spec::CommandMeta {
                     cmd: &#cmd,
                     about: #about,
                     long_about: #long_about,
                     hide: #hide,
                     hidden_aliases: &#hidden_name,
-                    ..*<#ty as ::usage_argv::spec::CommandArgs>::META
+                    ..*<#ty as usage_argv::spec::CommandArgs>::META
                 };
         }
     });
@@ -2552,7 +2584,7 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
         let field = format_ident!("v{i}");
         let ty = &v.ty;
         quote! {
-            #i => <#ty as ::usage_argv::spec::CommandArgs>::check(&mut partial.#field),
+            #i => <#ty as usage_argv::spec::CommandArgs>::check(&mut partial.#field),
         }
     });
     // Every variant's bindings, because a table says what the CLI *can* do and is compared
@@ -2560,7 +2592,7 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
     // those are about one invocation. A command nobody ran did not give anything.
     let binding_parts = subs.variants.iter().map(|v| {
         let ty = &v.ty;
-        quote!(<#ty as ::usage_argv::spec::CommandArgs>::SETTINGS_BINDINGS)
+        quote!(<#ty as usage_argv::spec::CommandArgs>::SETTINGS_BINDINGS)
     });
     let binding_lens = binding_parts.clone().map(|part| quote!(+ #part.len()));
     let givens = subs.variants.iter().enumerate().map(|(i, v)| {
@@ -2568,7 +2600,7 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
         let ty = &v.ty;
         quote! {
             ::std::option::Option::Some(#i) => {
-                <#ty as ::usage_argv::spec::CommandArgs>::settings_given(&partial.#field)
+                <#ty as usage_argv::spec::CommandArgs>::settings_given(&partial.#field)
             }
         }
     });
@@ -2578,7 +2610,7 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
         let ty = &v.ty;
         // The one place the box matters: everything else — tables, partial, `build` —
         // speaks to the struct itself.
-        let built = quote!(<#ty as ::usage_argv::spec::CommandArgs>::build(partial.#field)?);
+        let built = quote!(<#ty as usage_argv::spec::CommandArgs>::build(partial.#field)?);
         let built = if v.boxed {
             quote!(::std::boxed::Box::new(#built))
         } else {
@@ -2615,6 +2647,8 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
             clippy::needless_update
         )]
         const _: () = {
+            use #runtime as usage_argv;
+
             pub struct Partial {
                 #(#partial_fields)*
             }
@@ -2628,20 +2662,20 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
             #(#command_overrides)*
             #(#meta_overrides)*
 
-            const _: () = ::usage_argv::assert_unique_subcommand_names(&[#(#unique_commands),*]);
+            const _: () = usage_argv::assert_unique_subcommand_names(&[#(#unique_commands),*]);
 
-            impl ::usage_argv::spec::Subcommands for #ident {
+            impl usage_argv::spec::Subcommands for #ident {
                 type Partial = Partial;
 
-                const COMMANDS: &'static [&'static ::usage_argv::Command<'static>] =
+                const COMMANDS: &'static [&'static usage_argv::Command<'static>] =
                     &[#(#commands),*];
-                const METAS: &'static [&'static ::usage_argv::spec::CommandMeta<'static>] =
+                const METAS: &'static [&'static usage_argv::spec::CommandMeta<'static>] =
                     &[#(#metas),*];
 
                 fn apply(
                     partial: &mut Self::Partial,
                     selected: ::std::option::Option<usize>,
-                    event: &::usage_argv::Event<'_, '_>,
+                    event: &usage_argv::Event<'_, '_>,
                 ) -> bool {
                     match selected {
                         #(#applies)*
@@ -2655,14 +2689,14 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
                     const PARTS: &[&'static [(&'static str, &'static str)]] = &[#(#binding_parts),*];
                     const N: usize = 0 #(#binding_lens)*;
                     const JOINED: [(&'static str, &'static str); N] =
-                        ::usage_argv::spec::concat_bindings(PARTS);
+                        usage_argv::spec::concat_bindings(PARTS);
                     &JOINED
                 };
 
                 fn settings_given(
                     partial: &Self::Partial,
                     selected: ::std::option::Option<usize>,
-                ) -> ::std::vec::Vec<(&'static str, ::usage_argv::spec::SettingGiven)> {
+                ) -> ::std::vec::Vec<(&'static str, usage_argv::spec::SettingGiven)> {
                     match selected {
                         #(#givens)*
                         // No subcommand was reached, so none of them was given anything.
@@ -2673,7 +2707,7 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
                 fn check<'t, 'v>(
                     partial: &mut Self::Partial,
                     selected: usize,
-                ) -> ::std::result::Result<(), ::usage_argv::Error<'t, 'v>> {
+                ) -> ::std::result::Result<(), usage_argv::Error<'t, 'v>> {
                     match selected {
                         #(#checks)*
                         // A position that is not one of these cannot be produced: it comes
@@ -2687,7 +2721,7 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
                     selected: usize,
                 ) -> ::std::result::Result<
                     ::std::option::Option<Self>,
-                    ::usage_argv::Error<'t, 'v>,
+                    usage_argv::Error<'t, 'v>,
                 > {
                     match selected {
                         #(#selects)*
@@ -2735,7 +2769,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
         };
         let ident = &f.ident;
         Some(quote! {
-            <#ty as ::usage_argv::spec::CommandArgs>::check(&mut partial.#ident)?;
+            <#ty as usage_argv::spec::CommandArgs>::check(&mut partial.#ident)?;
         })
     });
     let duplicate_checks = cli.fields.iter().filter(|f| rejects_duplicate(f)).map(|f| {
@@ -2744,7 +2778,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
         quote! {
             if partial.#duplicated {
                 return ::std::result::Result::Err(
-                    ::usage_argv::Error::DuplicateFlag { name: #name },
+                    usage_argv::Error::DuplicateFlag { name: #name },
                 );
             }
         }
@@ -2846,7 +2880,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
         Some(quote! {
             if !partial.#given #standing {
                 return ::std::result::Result::Err(
-                    ::usage_argv::Error::MissingRequired { name: #name },
+                    usage_argv::Error::MissingRequired { name: #name },
                 );
             }
         })
@@ -2863,7 +2897,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
         // lists what was expected, instead of a message about a type the user did not name.
         let choices: TokenStream = match (f.value_enum, f.value_ty.as_ref()) {
             (true, Some(ty)) => {
-                quote!(<#ty as ::usage_argv::spec::ValueEnum>::CHOICES)
+                quote!(<#ty as usage_argv::spec::ValueEnum>::CHOICES)
             }
             _ => {
                 let list = &f.choices;
@@ -2893,7 +2927,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
                 };
                 if !#choices.contains(&__usage_text) {
                     return ::std::result::Result::Err(
-                        ::usage_argv::Error::InvalidChoice {
+                        usage_argv::Error::InvalidChoice {
                             name: #name,
                             choices: #choices,
                         },
@@ -2913,7 +2947,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
             Some(min) => quote! {
                 if got < #min {
                     return ::std::result::Result::Err(
-                        ::usage_argv::Error::VarTooFew { name: #name, min: #min, got },
+                        usage_argv::Error::VarTooFew { name: #name, min: #min, got },
                     );
                 }
             },
@@ -2938,7 +2972,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
             Some(max) => quote! {
                 if got > #max {
                     return ::std::result::Result::Err(
-                        ::usage_argv::Error::VarTooMany { name: #name, max: #max, got },
+                        usage_argv::Error::VarTooMany { name: #name, max: #max, got },
                     );
                 }
             },
@@ -2975,7 +3009,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
             Some(quote! {
                 if partial.#given && partial.#other_given {
                     return ::std::result::Result::Err(
-                        ::usage_argv::Error::ConflictingFlags {
+                        usage_argv::Error::ConflictingFlags {
                             name: #name,
                             other: #other_name,
                         },
@@ -3012,7 +3046,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
             Some(quote! {
                 if partial.#given && !partial.#other_given {
                     return ::std::result::Result::Err(
-                        ::usage_argv::Error::MissingRequired { name: #other_name },
+                        usage_argv::Error::MissingRequired { name: #other_name },
                     );
                 }
             })
@@ -3049,7 +3083,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
         // variable has already filled the field and set `__given_*`.
         let missing = quote! {
             return ::std::result::Result::Err(
-                ::usage_argv::Error::MissingRequired { name: #name },
+                usage_argv::Error::MissingRequired { name: #name },
             );
         };
         let required_if = (!if_given.is_empty()).then(|| {
@@ -3103,6 +3137,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
 /// hand-written list.
 pub fn emit_value_enum(value_enum: &ValueEnum) -> TokenStream {
     let ident = &value_enum.ident;
+    let runtime = runtime_path();
     let words: Vec<&String> = value_enum.variants.iter().map(|(_, name)| name).collect();
     let arms = value_enum
         .variants
@@ -3118,22 +3153,27 @@ pub fn emit_value_enum(value_enum: &ValueEnum) -> TokenStream {
         .join(", ");
 
     quote! {
-        impl ::usage_argv::spec::ValueEnum for #ident {
-            const CHOICES: &'static [&'static str] = &[#(#words),*];
-        }
+        #[doc(hidden)]
+        const _: () = {
+            use #runtime as usage_argv;
+
+            impl usage_argv::spec::ValueEnum for #ident {
+                const CHOICES: &'static [&'static str] = &[#(#words),*];
+            }
 
-        impl ::std::str::FromStr for #ident {
-            type Err = ::std::string::String;
+            impl ::std::str::FromStr for #ident {
+                type Err = ::std::string::String;
 
-            fn from_str(value: &str) -> ::std::result::Result<Self, Self::Err> {
-                match value {
-                    #(#arms)*
-                    other => ::std::result::Result::Err(::std::format!(
-                        "`{other}` is not one of: {}",
-                        #expected
-                    )),
+                fn from_str(value: &str) -> ::std::result::Result<Self, Self::Err> {
+                    match value {
+                        #(#arms)*
+                        other => ::std::result::Result::Err(::std::format!(
+                            "`{other}` is not one of: {}",
+                            #expected
+                        )),
+                    }
                 }
             }
-        }
+        };
     }
 }
diff --git a/derive/src/lib.rs b/derive/src/lib.rs
index b6d99cb7b..1dba460a5 100644
--- a/derive/src/lib.rs
+++ b/derive/src/lib.rs
@@ -208,7 +208,7 @@
 //! | `double_dash = "…"` | how a positional relates to `--`: `optional` (the default), `required` (fillable only after one), `preserve` (the `--` is a value), `automatic` (filling it ends flag parsing, so a wrapper forwards) |
 //! | `complete = my_fn` | a function that answers for this value when a shell asks |
 //! | `value_enum` | the words come from the field's type, which derives [`ValueEnum`] |
-//! | `value_hint = usage_argv::ValueHint::FilePath` | ask the shell for paths; `AnyPath` and `DirPath` are also supported |
+//! | `value_hint = usage::ValueHint::FilePath` | ask the shell for paths; `AnyPath` and `DirPath` are also supported |
 //! | `arg` | force a field to be positional |
 //! | `overrides = "--other"` | a flag this one displaces, the last given winning |
 //! | `conflicts = "--other"` | a flag this one cannot be given with |
diff --git a/derive/src/model.rs b/derive/src/model.rs
index 8bbe8673a..0a138835f 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -241,7 +241,7 @@ fn effect_value(meta: &Meta) -> syn::Result<proc_macro2::TokenStream> {
         }
     };
     Ok(quote::quote!(::core::option::Option::Some(
-        ::usage_argv::spec::Effect::#variant
+        usage_argv::spec::Effect::#variant
     )))
 }
 
@@ -252,7 +252,7 @@ fn value_hint(meta: &Meta) -> syn::Result<String> {
         return Err(syn::Error::new_spanned(
             value,
             "`value_hint` takes a usage ValueHint variant, as in \
-             `value_hint = usage_argv::ValueHint::FilePath`",
+             `value_hint = usage::ValueHint::FilePath`",
         ));
     };
     let Some(variant) = path.path.segments.last() else {
diff --git a/usage-rs/Cargo.toml b/usage-rs/Cargo.toml
new file mode 100644
index 000000000..753cc9290
--- /dev/null
+++ b/usage-rs/Cargo.toml
@@ -0,0 +1,28 @@
+[package]
+name = "usage-rs"
+description = "A compiled CLI parser for Rust, built on usage specs"
+version = "5.1.0"
+edition = "2021"
+rust-version = "1.91"
+homepage = { workspace = true }
+documentation = { workspace = true }
+repository = { workspace = true }
+authors = { workspace = true }
+license = { workspace = true }
+
+[dependencies]
+usage-argv = { workspace = true }
+usage-derive = { workspace = true, optional = true }
+
+[features]
+default = ["spec", "help"]
+spec = ["usage-argv/spec", "dep:usage-derive"]
+help = ["spec"]
+completions = ["spec", "usage-argv/complete"]
+# Kept as a spelling close to the runtime feature for low-level adopters.
+complete = ["completions"]
+diagnostics = ["spec", "usage-argv/diagnostics"]
+
+[package.metadata.release]
+shared-version = true
+release = true
diff --git a/usage-rs/src/lib.rs b/usage-rs/src/lib.rs
new file mode 100644
index 000000000..b0be59389
--- /dev/null
+++ b/usage-rs/src/lib.rs
@@ -0,0 +1,32 @@
+//! The facade for building compiled Rust CLIs with usage.
+//!
+//! Depend on `usage-rs` under the short crate name `usage`; the derive macros and their runtime
+//! then come from one versioned package, while cold-path functionality stays behind features:
+//!
+//! ```toml
+//! [dependencies]
+//! usage = { package = "usage-rs", version = "5.1" }
+//! ```
+//!
+//! ```
+//! use usage_rs as usage;
+//! use usage::Cli;
+//!
+//! #[derive(Cli)]
+//! #[usage(bin = "ex")]
+//! struct Ex {
+//!     #[usage(long, value_hint = usage::ValueHint::FilePath)]
+//!     file: Option<std::path::PathBuf>,
+//! }
+//!
+//! let argv = [std::ffi::OsStr::new("--file"), std::ffi::OsStr::new("input.txt")];
+//! let ex = Ex::parse_from(&argv).expect("valid command line");
+//! assert_eq!(ex.file.as_deref(), Some(std::path::Path::new("input.txt")));
+//! ```
+
+#![forbid(unsafe_code)]
+
+pub use usage_argv as argv;
+pub use usage_argv::*;
+#[cfg(feature = "spec")]
+pub use usage_derive::{Args, Cli, Subcommands, ValueEnum};
diff --git a/usage-rs/tests/facade.rs b/usage-rs/tests/facade.rs
new file mode 100644
index 000000000..cca41397a
--- /dev/null
+++ b/usage-rs/tests/facade.rs
@@ -0,0 +1,38 @@
+use std::ffi::OsStr;
+use std::path::{Path, PathBuf};
+
+use usage_rs as usage;
+use usage_rs::{Args, Cli, Subcommands};
+
+#[derive(Cli)]
+#[usage(bin = "ex")]
+struct Ex {
+    #[usage(subcommand)]
+    command: Command,
+}
+
+#[derive(Subcommands)]
+enum Command {
+    Show(Show),
+}
+
+/// Show one file
+#[derive(Args)]
+struct Show {
+    #[usage(long, value_hint = usage::ValueHint::FilePath)]
+    file: PathBuf,
+}
+
+#[test]
+fn one_dependency_provides_derives_runtime_and_value_hints() {
+    let _hint_from_facade = usage::ValueHint::FilePath;
+    let argv = [
+        OsStr::new("show"),
+        OsStr::new("--file"),
+        OsStr::new("input.txt"),
+    ];
+    let cli = Ex::parse_from(&argv).expect("valid command line");
+    let Command::Show(show) = cli.command;
+    assert_eq!(show.file, Path::new("input.txt"));
+    assert!(Ex::to_kdl().contains("complete \"file\" type=\"path\""));
+}

From b352cef44cb53419d4bbe3befcc439811fb5185a Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 03:58:01 +0000
Subject: [PATCH 08/21] chore: include usage-rs in msrv checks

---
 .github/workflows/test.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index e81cb40f4..f7f164ca0 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -89,7 +89,7 @@ jobs:
       matrix:
         include:
           - version: "1.91"
-            crates: usage-argv usage-derive usage-config
+            crates: usage-argv usage-derive usage-config usage-rs
           - version: "1.95"
             crates: usage-lib usage-config-build clap_usage usage-cli
     steps:

From 5c280bf4f04e63abaf44073b8a4419708e8a5cfa Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Mon, 17 Aug 2026 10:23:16 +0000
Subject: [PATCH 09/21] fix(derive): route unit commands through facade

---
 derive/src/codegen.rs    | 25 ++++++++++++++++++++++++-
 usage-rs/tests/facade.rs | 12 +++++++++++-
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/derive/src/codegen.rs b/derive/src/codegen.rs
index b3020763d..b392cae15 100644
--- a/derive/src/codegen.rs
+++ b/derive/src/codegen.rs
@@ -42,6 +42,28 @@ fn runtime_path() -> TokenStream {
     }
 }
 
+/// The derive package as the adopter depended on it.
+///
+/// Most emitted code only needs the runtime path. Unit subcommands synthesize an empty `Args`
+/// struct, though, so that derive must come through the facade too when it is the application's
+/// only dependency.
+fn derive_path() -> TokenStream {
+    match crate_name("usage-rs") {
+        Ok(FoundCrate::Itself) => quote!(::usage_rs),
+        Ok(FoundCrate::Name(name)) => {
+            let facade = format_ident!("{}", name.replace('-', "_"));
+            quote!(::#facade)
+        }
+        Err(_) => match crate_name("usage-derive") {
+            Ok(FoundCrate::Name(name)) => {
+                let derive = format_ident!("{}", name.replace('-', "_"));
+                quote!(::#derive)
+            }
+            _ => quote!(::usage_derive),
+        },
+    }
+}
+
 pub fn emit(cli: &Cli) -> TokenStream {
     let ident = &cli.ident;
     let runtime = runtime_path();
@@ -2442,6 +2464,7 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
 pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
     let ident = &subs.ident;
     let runtime = runtime_path();
+    let derive = derive_path();
 
     // The structs the bare variants imply, written here so everything downstream keeps
     // speaking to a struct. `Args` is derived on them rather than the impl being written out:
@@ -2461,7 +2484,7 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
                 .map(|word| quote!(#[usage(effect = #word)]));
             quote! {
                 #[doc(hidden)]
-                #[derive(::usage_derive::Args)]
+                #[derive(#derive::Args)]
                 #effect
                 pub struct #name {}
             }
diff --git a/usage-rs/tests/facade.rs b/usage-rs/tests/facade.rs
index cca41397a..ff9b51b63 100644
--- a/usage-rs/tests/facade.rs
+++ b/usage-rs/tests/facade.rs
@@ -14,6 +14,8 @@ struct Ex {
 #[derive(Subcommands)]
 enum Command {
     Show(Show),
+    /// Print version information
+    Version,
 }
 
 /// Show one file
@@ -32,7 +34,15 @@ fn one_dependency_provides_derives_runtime_and_value_hints() {
         OsStr::new("input.txt"),
     ];
     let cli = Ex::parse_from(&argv).expect("valid command line");
-    let Command::Show(show) = cli.command;
+    let Command::Show(show) = cli.command else {
+        panic!("show command should be selected");
+    };
     assert_eq!(show.file, Path::new("input.txt"));
     assert!(Ex::to_kdl().contains("complete \"file\" type=\"path\""));
 }
+
+#[test]
+fn unit_subcommands_use_the_facade_derive() {
+    let cli = Ex::parse_from(&[OsStr::new("version")]).expect("valid unit subcommand");
+    assert!(matches!(cli.command, Command::Version));
+}

From 9eec6227d807d77ca0a86baea5b0a533d40c4be3 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 10/21] 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 0c2467cbd195385a5ed63ce367d79a27ebcb25cf 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 11/21] 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 1c2a62b416338a985fc44fb603ab87c69b06f4de 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 12/21] 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 bf626b26c438d5089847c05e15f06745b9322c5e 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 13/21] 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 728bd6338a1e2ffec19706f7ec1aae133e288abf 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 14/21] 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 83a4a3fe3f335f102f4b2a0296669a6cdcec590a 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 15/21] 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 7cdaefe131f45a8235d9ca0bb275e6b79d0f1105 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 16/21] 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 a690e1815e4760426a463ea4d329a32715a42eb8 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 17/21] 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 d454982a8e0a616bd0aaf5ab5a228c94791da66b 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 18/21] 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 ff6f195f3ecfb9cd39b53637673f2c9f774193d6 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 19/21] 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 83ffa6c8b5cfe74b90161ce6757e343922329521 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 20/21] 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 7ccd8e31f7fd90ef29e0ecc5415eb614bad831d0 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 21/21] 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 b392cae15..6f396df97 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 —