diff --git a/docs/cli/completions.md b/docs/cli/completions.md
index a27c4e44c..e194e5b84 100644
--- a/docs/cli/completions.md
+++ b/docs/cli/completions.md
@@ -1,5 +1,12 @@
 # Generating Completion Scripts
 
+::: tip Building with usage-rs or usage-go?
+Both frameworks generate and answer completions from the tables compiled into your binary, so
+there is no spec file to ship and no `usage` runtime dependency for your users. See
+[Rust completions](/rust/completions) and [Go completions](/go/completions). This page covers
+generating scripts with the `usage` CLI from a `.usage.kdl` spec or a `usage`-shebang script.
+:::
+
 ## Auto-completion for shebang scripts (bash)
 
 If you have shell scripts that use the `usage` shebang
diff --git a/docs/rust/index.md b/docs/rust/index.md
index 630a85f00..9489fc755 100644
--- a/docs/rust/index.md
+++ b/docs/rust/index.md
@@ -4,18 +4,24 @@
 Used by some of jdx's CLIs, but point releases may break.
 :::
 
-`usage-rs` is a fast, typed framework for building complete command-line applications in Rust.
+`usage-rs` is a CLI framework for Rust applications, and the reference implementation of the
+[usage spec](/spec/). It is fully featured — more of what a real CLI needs than clap offers —
+and its parser is up to thousands of times faster.
+
 Declare commands, flags, arguments, and settings with familiar structs and enums, and get
 first-class environment and config-file resolution, advanced shell completions, portable
-validation, negation flags, typed argument groups, categorized subcommands, and more.
-
-In the mise-scale benchmark it parses hundreds of times faster than clap, with no third-party
-runtime crates and a 1.3 MB stripped binary versus clap's 3.1 MB. See the
-[performance results](/rust/performance) and [clap migration guide](/rust/migrating-from-clap).
-
-The same declaration also becomes a portable [usage spec](/spec/) that the binary can print.
-`usage-cli` turns it into documentation, manpages, and completions — the same toolchain used
-across jdx's CLIs.
+validation, negation flags, typed argument groups, categorized subcommands, and more. The derive
+accepts most clap spellings, so a migration is largely mechanical.
+
+The speed comes from where the work happens: the derive lays the command tree out as static
+tables while your application compiles, so a parse never builds and validates a parser the way
+clap and bpaf do on every run. At mise scale that is 855x fewer instructions than clap and
+2,957x fewer than bpaf, in a 1.3 MB stripped binary against clap's 3.1 MB, with no third-party
+crates linked into your binary. See the [performance results](/rust/performance) and
+[clap migration guide](/rust/migrating-from-clap).
+
+The same declaration also becomes a portable spec that the binary can print. `usage-cli` turns
+it into documentation, manpages, and completions — the same toolchain used across jdx's CLIs.
 
 ```rust
 use usage::Cli;
diff --git a/docs/rust/performance.md b/docs/rust/performance.md
index 21dd2d130..870ee99e6 100644
--- a/docs/rust/performance.md
+++ b/docs/rust/performance.md
@@ -1,8 +1,10 @@
 # Parser performance
 
-usage's compiled Rust parser is designed so ordinary argv parsing reads static
-tables and writes directly into the result. Cold metadata for help, specs, and
-completions is not constructed on a successful parse.
+`usage-rs` has the fastest argument parser of the Rust frameworks measured here:
+at mise scale it parses in 0.7 µs, 855x fewer instructions than clap and 2,957x
+fewer than bpaf. The derive lays the command tree out as static tables while
+your application compiles, so a parse reads what the compiler already built
+instead of constructing and validating a parser on every run.
 
 ## Mise-scale result