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:
diff --git a/Cargo.lock b/Cargo.lock
index c05992993..16e88979c 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"
@@ -1321,6 +1312,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 +1965,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 +1980,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"
@@ -2059,9 +2080,6 @@ name = "usage-cli"
 version = "5.1.0"
 dependencies = [
  "assert_cmd",
- "clap",
- "clap-sort",
- "clap_usage",
  "ctor",
  "env_logger",
  "exec",
@@ -2082,6 +2100,7 @@ dependencies = [
  "thiserror",
  "tokio",
  "usage-lib",
+ "usage-rs",
  "xx",
 ]
 
@@ -2119,6 +2138,7 @@ dependencies = [
 name = "usage-derive"
 version = "5.1.0"
 dependencies = [
+ "proc-macro-crate",
  "proc-macro2",
  "quote",
  "syn 3.0.3",
@@ -2152,6 +2172,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 +2563,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/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/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
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/argv/src/spec.rs b/argv/src/spec.rs
index 565eef04d..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,
     };
@@ -485,6 +489,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 +524,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 +568,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,
@@ -666,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) {
@@ -785,6 +798,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 +807,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/cli/Cargo.toml b/cli/Cargo.toml
index bb414550b..2ddc98c3f 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,10 @@ serde_with = "3"
 tera = "2"
 thiserror = "2"
 tokio = { version = "1", features = ["rt", "macros", "io-std"] }
+# 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"
 
@@ -51,7 +53,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..a4f3eaa38 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"],
@@ -715,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 5948c8c75..e9520ae18 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -1,19 +1,20 @@
-.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]
+\fBusage\fR <COMMAND>
+\fBusage\fR \-\-completions <COMPLETIONS>
+\fBusage\fR \-\-usage\-spec
 .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
@@ -65,6 +66,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
@@ -118,10 +120,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
@@ -193,6 +199,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 +228,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 +247,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 +263,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
@@ -271,9 +290,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
@@ -327,6 +348,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 +364,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 +442,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
@@ -460,6 +489,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 ZSH"
 Execute a shell script with the specified shell
 
@@ -483,3 +515,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..17db39aea 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_rs::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(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
-    #[clap(short, long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// Raw string spec input
-    #[clap(short, long, required_unless_present = "file", overrides_with = "file")]
+    #[usage(short, 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..ef525290c 100644
--- a/cli/src/cli/exec.rs
+++ b/cli/src/cli/exec.rs
@@ -2,35 +2,33 @@ use std::fmt::Debug;
 use std::path::PathBuf;
 use std::process::Stdio;
 
-use clap::Args;
 use itertools::Itertools;
 use miette::IntoDiagnostic;
+use usage_rs::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"
-)]
+// The words after the script are the script's, so a flag `usage` does not know is a value to
+// forward rather than a mistake to report — the root's `error` stops here.
+#[usage(alias = "x", unknown_flags = "value")]
 pub struct Exec {
     /// command to execute after parsing usage spec
     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: 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..4d2449039 100644
--- a/cli/src/cli/generate/completion.rs
+++ b/cli/src/cli/generate/completion.rs
@@ -1,45 +1,45 @@
-use clap::Args;
 use std::path::PathBuf;
 use usage::complete::CompleteOptions;
 use usage::Spec;
+use usage_rs::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(alias = "c", alias_hidden("complete", "completions"), 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, long)]
     file: Option<PathBuf>,
 
     /// A cache key to use for storing the results of calling the CLI with --usage-cmd
-    #[clap(long, requires = "usage_cmd")]
+    #[usage(long, requires = "--usage-cmd")]
     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, verbatim_doc_comment)]
     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")]
     usage_cmd: Option<String>,
 }
 
diff --git a/cli/src/cli/generate/completion_init.rs b/cli/src/cli/generate/completion_init.rs
index 908fe2f52..66e273268 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_rs::Args;
 
 /// Generate a shell init script that auto-completes any usage shebang script on $PATH
 ///
@@ -7,16 +7,20 @@ 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(
+    alias = "ci",
+    alias_hidden("init", "completions-init"),
+    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..b41486f87 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_rs::Args;
 
 use crate::cli::generate;
 use serde::{Deserialize, Serialize, Serializer};
@@ -46,18 +46,22 @@ 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, 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,
+        value_hint = usage_rs::ValueHint::FilePath,
+        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/go.rs b/cli/src/cli/generate/go.rs
index 060fb85df..76bfb7c47 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_rs::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_rs::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/json.rs b/cli/src/cli/generate/json.rs
index b4cbbbbd1..71e3b601a 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_rs::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, 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..ae5053918 100644
--- a/cli/src/cli/generate/json_schema.rs
+++ b/cli/src/cli/generate/json_schema.rs
@@ -7,27 +7,31 @@ 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_rs::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, long)]
     file: Option<PathBuf>,
 
     /// Write the schema here instead of to stdout
-    #[clap(long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(
+        long,
+        value_hint = usage_rs::ValueHint::FilePath,
+        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..4e03cf388 100644
--- a/cli/src/cli/generate/manpage.rs
+++ b/cli/src/cli/generate/manpage.rs
@@ -1,18 +1,24 @@
 use std::path::PathBuf;
 
 use super::{parse_file_or_stdin, write_or_stdout};
-use clap::Args;
 use usage::docs::manpage::ManpageRenderer;
+use usage_rs::Args;
 
+/// Generate a manpage from a usage spec
 #[derive(Args)]
-#[clap(visible_alias = "man")]
+#[usage(alias = "man", effect = "read")]
 pub struct Manpage {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short, long)]
     file: PathBuf,
 
     /// Output file path, or "-" for stdout (default)
-    #[clap(short, long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(
+        short,
+        long,
+        value_hint = usage_rs::ValueHint::FilePath,
+        effect = "write"
+    )]
     out_file: Option<PathBuf>,
 
     /// Manual section number (default: 1)
@@ -22,7 +28,7 @@ pub struct Manpage {
     /// - 5: File formats
     /// - 7: Miscellaneous
     /// - 8: System administration commands
-    #[clap(short, long, default_value = "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 72da13562..5a69e44cc 100644
--- a/cli/src/cli/generate/markdown.rs
+++ b/cli/src/cli/generate/markdown.rs
@@ -1,41 +1,51 @@
 use std::path::PathBuf;
 
 use super::{parse_file_or_stdin, write_or_stdout};
-use clap::Args;
 use usage::docs::markdown::MarkdownRenderer;
+use usage_rs::Args;
 
 /// Generate markdown documentation from usage specs
 #[derive(Args)]
-#[clap(visible_alias = "md")]
+#[usage(alias = "md", effect = "read")]
 pub struct Markdown {
     /// A usage spec taken in as a file, use "-" to read from stdin
-    #[clap(short, long)]
+    #[usage(short, 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, 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, long, conflicts = "--out-file")]
     multi: bool,
 
     /// Escape HTML in markdown
-    #[clap(long)]
+    #[usage(long)]
     html_encode: bool,
 
     /// Output markdown files to this directory (required when using --multi)
-    #[clap(long, value_hint = clap::ValueHint::DirPath, requires = "multi")]
+    #[usage(
+        long,
+        value_hint = usage_rs::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)
-    #[clap(long, value_hint = clap::ValueHint::FilePath)]
+    #[usage(
+        long,
+        value_hint = usage_rs::ValueHint::FilePath,
+        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..b6353f1bc 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -15,14 +15,19 @@ 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_rs::Args)]
+#[usage(alias = "g", 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_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 cbbcee32c..6fced9eb6 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_rs::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, long)]
     file: Option<PathBuf>,
 
     /// Target language for the SDK
-    #[clap(short, long, value_parser = ["typescript", "python"])]
+    #[usage(short, long, choices("typescript", "python"))]
     language: String,
 
     /// Output directory for generated SDK files
-    #[clap(short, long)]
+    #[usage(short, long)]
     output: PathBuf,
 
     /// Override the package/module name (defaults to spec bin name)
-    #[clap(short, long)]
+    #[usage(short, 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..1e4a75bcb 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_rs::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, 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_rs::ValueEnum)]
 enum OutputFormat {
     #[default]
     Text,
diff --git a/cli/src/cli/mcp.rs b/cli/src/cli/mcp.rs
index 16568b114..b23b8c989 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_rs::Args)]
+#[usage(alias = "mcp-server", verbatim_doc_comment, effect = "read")]
 pub struct Mcp {
     // Unlike other subcommands this cannot be "-": stdin is the transport, so
     // reading the spec from it would consume the session.
     /// Usage spec file (not "-": stdin is the MCP transport)
-    #[clap(short, long)]
+    #[usage(short, long)]
     file: Option<PathBuf>,
 
     /// Raw string spec input
-    #[clap(short, long, required_unless_present = "file", overrides_with = "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 13fde5183..ff52eb860 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_rs::{Cli as DeriveCli, Subcommands};
 
 pub mod complete_word;
 mod exec;
@@ -10,55 +11,132 @@ 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",
+    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.
+    //
+    // 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 {
-    #[clap(subcommand)]
+    #[usage(subcommand)]
     command: Command,
 
     /// Outputs completions for the specified shell for completing the `usage` CLI itself
+    // `--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.
+    #[usage(long)]
     completions: Option<String>,
 
     /// Outputs a `usage.kdl` spec for this CLI itself
-    #[clap(long)]
+    #[usage(long)]
     usage_spec: bool,
 }
 
-#[derive(Subcommand)]
+/// 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
+/// 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),
+    Bash(shell::Bash),
     CompleteWord(complete_word::CompleteWord),
     Exec(exec::Exec),
-    #[clap(about = "Execute a shell script using fish")]
-    Fish(shell::Shell),
+    Fish(shell::Fish),
     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),
+    #[usage(name = "powershell")]
+    PowerShell(shell::PowerShell),
+    /// Show the companies sponsoring usage and the jdx.dev open source tools
+    #[usage(effect = "read")]
+    Sponsors,
+    Zsh(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_rs::Error::Help { cmd, long }) => {
+                if let Some(page) = usage_rs::help::render(Self::spec(), cmd, long) {
+                    print!("{page}");
+                }
+                return Ok(());
+            }
+            Err(usage_rs::Error::Version) => {
+                println!("{}", version());
+                return Ok(());
+            }
+            Err(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);
+            }
+        };
+        if let Some(shell) = cli.completions.as_deref() {
+            return crate::usage_spec::complete(shell);
+        }
         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..3f308fd3c 100644
--- a/cli/src/cli/shell.rs
+++ b/cli/src/cli/shell.rs
@@ -2,37 +2,82 @@ use std::fmt::Debug;
 use std::path::PathBuf;
 use std::process::Stdio;
 
-use clap::Args;
 use itertools::Itertools;
 use miette::IntoDiagnostic;
+use usage_rs::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: 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: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 `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(
+            about = $about,
+            unknown_flags = "value",
+            verbatim_doc_comment
+        )]
+        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..091a28bfd 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_rs::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,45 @@ 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 go",
+            "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..e687ce41b 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;
@@ -31,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/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/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/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 de554ef04..3103e54b1 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -1,299 +1,251 @@
-// @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
+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>"
 }
-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.
-"""#
+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 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>"
+    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" {
+    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 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>"
+    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" subcommand_required=#true {
+    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>
+            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>
+        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" {
-            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 "--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"
         }
-        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-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 --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 "--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>"
         }
-        arg <SHELL> help="Shell to generate completions for" {
-            choices bash fish nu powershell 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"
+        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>
-        }
-        arg <SHELL> help="Shell to generate the init script for" {
-            choices bash fish zsh
+    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>"
+        }
+        arg "<SHELL>" help="Shell to generate the init script for" {
+            choices "bash" "fish" "zsh"
         }
     }
-    cmd fig help="Generate Fig completion spec for Amazon Q / Fig" effect=read unknown_flags=error {
+    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 --out-file help="File path where the generated Fig spec 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 --spec help="Raw string spec input" {
-            arg <SPEC>
+        flag "--spec" help="Raw string spec input" overrides="--file" required_unless="--file" {
+            arg "<SPEC>"
         }
+        complete "out_file" type="path"
     }
-    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 "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>
+            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 "-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>
+            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>"
         }
+        complete "out_file" type="path"
     }
-    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>"
         }
+        complete "out_file" type="path"
     }
-    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>"
         }
+        complete "out_file" type="path"
     }
-    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" requires="--multi" required_if="--multi" {
+            arg "<OUT_DIR>"
         }
-        flag --out-file help="Output file path for single-file markdown generation, or \"-\" for stdout (default)" effect=write {
-            arg <OUT_FILE>
+        flag "--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>"
         }
+        complete "out_dir" type="dir"
+        complete "out_file" type="path"
     }
-    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" {
+    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" {
+    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 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>"
+    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" {
+}
+cmd "zsh" help="Execute a shell script using zsh" unknown_flags="value" {
+    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>"
+    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/conformance/tests/completion.rs b/conformance/tests/completion.rs
index 988eaf086..ea18b0d1b 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 = usage_argv::ValueHint::FilePath)]
+    file: Option<std::path::PathBuf>,
+    /// A directory to write
+    #[usage(long, value_hint = usage_argv::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 usage_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/conformance/tests/metadata.rs b/conformance/tests/metadata.rs
index 80258ef36..62d124c99 100644
--- a/conformance/tests/metadata.rs
+++ b/conformance/tests/metadata.rs
@@ -212,6 +212,107 @@ struct Verbatim {
     command: Option<Commands>,
 }
 
+#[doc = " Ordinary first line\n    indented continuation"]
+#[derive(Cli)]
+#[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
+///
+///     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 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 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/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/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 d72f07511..6f396df97 100644
--- a/derive/src/codegen.rs
+++ b/derive/src/codegen.rs
@@ -13,12 +13,60 @@
 //! 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),
+        },
+    }
+}
+
+/// 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();
 
     let flags: Vec<&Field> = cli
         .fields
@@ -38,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
@@ -151,7 +200,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 +247,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 +266,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 +287,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 +314,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 +332,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 +345,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 +378,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,13 +391,14 @@ 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,
                 min_usage_version: #min_usage_version,
                 about: #about,
                 long_about: #long_about,
+                usage: #usage,
                 default_subcommand: #default_subcommand,
                 root: &ROOT_META,
             };
@@ -356,12 +408,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 +429,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 +453,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 +466,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 +495,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 +528,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 +547,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 +568,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 +576,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 +596,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 +607,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 +641,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 +670,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 +728,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 +751,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 +767,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 +802,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 +812,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 +822,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 +832,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,
                         );
@@ -802,6 +854,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;
@@ -833,9 +886,10 @@ 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,
             flag: &#table,
             help: #help,
             long_help: #long_help,
@@ -855,7 +909,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
         };
     }
 }
@@ -867,6 +921,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;
@@ -880,8 +935,9 @@ 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,
             help: #help,
             long_help: #long_help,
@@ -893,7 +949,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
         };
     }
 }
@@ -903,7 +959,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),*])
@@ -967,7 +1023,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)*
@@ -1067,10 +1123,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 { .. } => {}
         }
@@ -1102,25 +1158,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),
@@ -1317,7 +1373,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;
@@ -1391,10 +1447,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),
             )
@@ -1402,21 +1458,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
@@ -1434,9 +1490,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,
             }
         },
     }
@@ -1482,17 +1538,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,
                         )
@@ -1518,7 +1574,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
         }
     }
@@ -1558,7 +1614,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)*
@@ -1593,17 +1649,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
@@ -1612,7 +1668,7 @@ fn settings_layer() -> TokenStream {
                                 .collect(),
                         ),
                     ),
-                    ::usage_argv::spec::SettingGiven::NotText => {
+                    usage_argv::spec::SettingGiven::NotText => {
                         __usage_layer.with_unrepresentable(__usage_key)
                     }
                 };
@@ -1664,7 +1720,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;
@@ -1714,7 +1770,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 {
@@ -1763,12 +1819,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,
@@ -1842,8 +1898,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(),
@@ -1865,8 +1921,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),
@@ -1986,7 +2042,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;
             }
         })
@@ -2007,9 +2063,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
@@ -2076,7 +2132,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,
                 )?
@@ -2092,7 +2148,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,
                     );
                 }
             },
@@ -2100,7 +2156,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
@@ -2108,17 +2164,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.
@@ -2133,9 +2189,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))
                 {
@@ -2145,7 +2201,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,
@@ -2155,7 +2211,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,
                 )?;
@@ -2169,6 +2225,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 —
@@ -2186,7 +2243,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)
             }
         }
@@ -2287,13 +2344,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,
@@ -2301,14 +2360,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,
@@ -2324,7 +2383,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> {
@@ -2352,7 +2411,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.
@@ -2363,11 +2422,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 {
@@ -2376,14 +2435,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)
                 }
 
@@ -2391,7 +2450,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),*
@@ -2406,6 +2465,8 @@ 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();
+    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:
@@ -2425,7 +2486,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 {}
             }
@@ -2438,19 +2499,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)
             }
         }
     });
@@ -2469,15 +2530,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
             };
         }
     });
@@ -2508,11 +2569,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.
@@ -2522,19 +2583,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
                 };
         }
     });
@@ -2548,7 +2609,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
@@ -2556,7 +2617,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)| {
@@ -2564,7 +2625,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)
             }
         }
     });
@@ -2574,7 +2635,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 {
@@ -2611,6 +2672,8 @@ pub fn emit_subcommands(subs: &Subcommands) -> TokenStream {
             clippy::needless_update
         )]
         const _: () = {
+            use #runtime as usage_argv;
+
             pub struct Partial {
                 #(#partial_fields)*
             }
@@ -2624,20 +2687,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)*
@@ -2651,14 +2714,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.
@@ -2669,7 +2732,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
@@ -2683,7 +2746,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)*
@@ -2731,7 +2794,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| {
@@ -2740,7 +2803,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 },
                 );
             }
         }
@@ -2842,7 +2905,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 },
                 );
             }
         })
@@ -2859,7 +2922,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;
@@ -2889,7 +2952,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,
                         },
@@ -2909,7 +2972,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 },
                     );
                 }
             },
@@ -2934,7 +2997,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 },
                     );
                 }
             },
@@ -2971,7 +3034,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,
                         },
@@ -3008,7 +3071,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 },
                     );
                 }
             })
@@ -3045,7 +3108,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(|| {
@@ -3099,6 +3162,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
@@ -3114,22 +3178,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 ::std::str::FromStr for #ident {
-            type Err = ::std::string::String;
+            impl usage_argv::spec::ValueEnum for #ident {
+                const CHOICES: &'static [&'static str] = &[#(#words),*];
+            }
+
+            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 6f237419b..1dba460a5 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,11 +202,13 @@
 //! | `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) |
 //! | `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::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 a4395a747..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
@@ -163,6 +165,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
@@ -239,10 +243,39 @@ 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
     )))
 }
 
+/// 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 usage ValueHint variant, as in \
+             `value_hint = usage::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 {
@@ -336,7 +369,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(),
@@ -345,6 +378,7 @@ impl Cli {
             completion: false,
             settings: false,
             min_usage_version: None,
+            usage: None,
             effect: None,
             aliases: Vec::new(),
             hidden_aliases: Vec::new(),
@@ -354,8 +388,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,10 +417,12 @@ 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)?),
                     "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.
@@ -436,7 +472,7 @@ impl Cli {
                             path,
                             format!(
                                 "unknown option `{other}` on a struct; usage::Cli takes \
-                                 `name`, `bin`, `version`, `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"
                             ),
@@ -446,6 +482,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);
@@ -884,6 +922,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,
@@ -976,6 +1015,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,
@@ -1010,8 +1050,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,10 +1080,12 @@ 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();
         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;
@@ -1112,6 +1152,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(
@@ -1153,6 +1194,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)?;
@@ -1180,9 +1222,10 @@ 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`, \
                                  `required`, and `double_dash`"
                             ),
                         ));
@@ -1191,6 +1234,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
@@ -1334,6 +1379,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(
@@ -1683,6 +1740,7 @@ impl Field {
             required_collection,
             choices,
             complete,
+            complete_type,
             value_enum,
             var_min,
             var_max,
@@ -1971,10 +2029,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 +2048,39 @@ 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());
+                if verbatim {
+                    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
+                    // space per attribute. A newline inside one attribute does not.
+                    lines.push(raw.strip_prefix(' ').unwrap_or(&raw).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 +2302,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 +2333,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 +2348,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(
diff --git a/docs/cli/reference/bash.md b/docs/cli/reference/bash.md
index d6d0daa33..b52b2ae06 100644
--- a/docs/cli/reference/bash.md
+++ b/docs/cli/reference/bash.md
@@ -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..b1ab399ac 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -1,9 +1,9 @@
 {
-  "name": "usage-cli",
+  "name": "usage",
   "bin": "usage",
   "cmd": {
     "full_cmd": [],
-    "usage": "[--usage-spec] [COMPLETIONS] <SUBCOMMAND>",
+    "usage": "[--completions <COMPLETIONS>] [--usage-spec] <SUBCOMMAND>",
     "subcommands": {
       "bash": {
         "full_cmd": ["bash"],
@@ -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",
@@ -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
             }
           },
@@ -150,10 +153,10 @@
         ],
         "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 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",
@@ -343,7 +347,8 @@
                   "required": true,
                   "double_dash": "Optional",
                   "hide": false
-                }
+                },
+                "requires": ["--usage-cmd"]
               },
               {
                 "name": "include-bash-completion-lib",
@@ -373,15 +378,18 @@
                   "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_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,18 +519,25 @@
                   "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",
             "aliases": [],
             "hidden_aliases": [],
-            "examples": []
+            "examples": [],
+            "complete": {
+              "out_file": {
+                "name": "out_file",
+                "type_": "path"
+              }
+            }
           },
           "go": {
             "full_cmd": ["generate", "go"],
@@ -587,6 +604,7 @@
                 "help_first_line": "Raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -595,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"],
@@ -639,6 +664,7 @@
                 "help_first_line": "raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -647,12 +673,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 +735,7 @@
                 "help_first_line": "raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -716,7 +744,8 @@
                   "required": true,
                   "double_dash": "Optional",
                   "hide": false
-                }
+                },
+                "overrides": ["--file"]
               },
               {
                 "name": "title",
@@ -755,13 +784,19 @@
             ],
             "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",
             "aliases": [],
             "hidden_aliases": [],
-            "examples": []
+            "examples": [],
+            "complete": {
+              "out_file": {
+                "name": "out_file",
+                "type_": "path"
+              }
+            }
           },
           "manpage": {
             "full_cmd": ["generate", "manpage"],
@@ -809,7 +844,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,12 +862,19 @@
             ],
             "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": [],
-            "examples": []
+            "examples": [],
+            "complete": {
+              "out_file": {
+                "name": "out_file",
+                "type_": "path"
+              }
+            }
           },
           "markdown": {
             "full_cmd": ["generate", "markdown"],
@@ -886,6 +928,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": {
@@ -895,6 +938,7 @@
                   "double_dash": "Optional",
                   "hide": false
                 },
+                "requires": ["--multi"],
                 "effect": "write"
               },
               {
@@ -945,13 +989,23 @@
             ],
             "mounts": [],
             "effect": "read",
-            "unknown_flags": "error",
+            "unknown_flags": null,
             "hide": false,
             "help": "Generate markdown documentation from usage specs",
             "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"],
@@ -1039,6 +1093,7 @@
                 "help_first_line": "Raw string spec input",
                 "short": [],
                 "long": ["spec"],
+                "required_unless": ["--file"],
                 "hide": false,
                 "global": false,
                 "arg": {
@@ -1047,12 +1102,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,7 +1121,7 @@
         "flags": [],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "error",
+        "unknown_flags": null,
         "hide": false,
         "subcommand_required": true,
         "help": "Generate completions, documentation, and other artifacts from usage specs",
@@ -1125,7 +1181,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 +1191,7 @@
         ],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "error",
+        "unknown_flags": null,
         "hide": false,
         "help": "Lint a usage spec file for common issues",
         "name": "lint",
@@ -1173,6 +1229,7 @@
             "help_first_line": "Raw string spec input",
             "short": ["s"],
             "long": ["spec"],
+            "required_unless": ["--file"],
             "hide": false,
             "global": false,
             "arg": {
@@ -1181,12 +1238,13 @@
               "required": true,
               "double_dash": "Optional",
               "hide": false
-            }
+            },
+            "overrides": ["--file"]
           }
         ],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "error",
+        "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`.",
@@ -1211,6 +1269,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",
@@ -1258,7 +1317,7 @@
         "flags": [],
         "mounts": [],
         "effect": "read",
-        "unknown_flags": "error",
+        "unknown_flags": null,
         "hide": false,
         "help": "Show the companies sponsoring usage and the jdx.dev open source tools",
         "name": "sponsors",
@@ -1282,6 +1341,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",
@@ -1322,18 +1382,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",
@@ -1359,7 +1426,7 @@
     "files": []
   },
   "version": "5.1.0",
-  "usage": "Usage: usage-cli [OPTIONS] [COMPLETIONS] <COMMAND>",
+  "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/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..5bf1b6d4a 100644
--- a/docs/cli/reference/fish.md
+++ b/docs/cli/reference/fish.md
@@ -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/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
 
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/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
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..89efeb45d 100644
--- a/docs/cli/reference/powershell.md
+++ b/docs/cli/reference/powershell.md
@@ -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..42136601b 100644
--- a/docs/cli/reference/zsh.md
+++ b/docs/cli/reference/zsh.md
@@ -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/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 —
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..ff9b51b63
--- /dev/null
+++ b/usage-rs/tests/facade.rs
@@ -0,0 +1,48 @@
+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),
+    /// Print version information
+    Version,
+}
+
+/// 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 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));
+}