docs: improve guides, navigation, and landing page

Entire-Checkpoint: 01M1TH0VF6GAKBD4QC4V849FQ0

Author: jdx

CONTRIBUTING.md

@@ -1,6 +1,17 @@
 # Contributing
 
-See the [contributing guide](https://usage.jdx.dev/contributing).
+The [contributing guide](https://usage.jdx.dev/contributing) covers project scope,
+review expectations, and checks. Start from the repository root:
+
+```sh
+mise install
+mise run build
+mise run test
+```
+
+For website changes, run `mise run docs:dev` for a live preview and
+`mise exec -- aube run docs:build` for the production build. Guides live in
+`docs/`; `docs/cli/reference/` is generated from command help in the Rust source.
 
 ## mbx build cache
 
@@ -9,12 +20,12 @@ See the [contributing guide](https://usage.jdx.dev/contributing).
 its transparent Cargo wrapper and therefore use the cache while invoking Cargo
 normally. Standalone Cargo commands require an activated mise shell. To bypass
 mbx without skipping or weakening a check, prefix the
-equivalent Cargo command with `MBX_DISABLE=1`:
+equivalent Cargo command with `MBX_DISABLE=1` and keep the mise tool environment:
 
 ```sh
-MBX_DISABLE=1 cargo build --all
-MBX_DISABLE=1 cargo test --all --all-features
-MBX_DISABLE=1 cargo clippy --all --all-features --all-targets -- -D warnings
+MBX_DISABLE=1 mise exec -- cargo build --all
+MBX_DISABLE=1 mise exec -- cargo test --all --all-features
+MBX_DISABLE=1 mise exec -- cargo clippy --all --all-features --all-targets -- -D warnings
 ```
 
 If bypassed Cargo succeeds where the wrapper fails, or mbx introduces a papercut, please start a

NOTICE.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-Usage itself is licensed under the MIT License; see [LICENSE](LICENSE). This file
+Usage itself is licensed under the MIT License; see [LICENSE](https://github.com/jdx/usage/blob/main/LICENSE). This file
 records the third-party work that Usage vendors, derives from, or is closely
 modeled on, together with the license each is used under.
 
@@ -44,7 +44,7 @@ warrant attribution:
 - `usage-derive` / `usage-rs` deliberately mirror `clap_derive`'s attribute
   vocabulary and semantics (`long`, `short`, `env`, `default_value`, `flatten`,
   `value_enum`, `rename_all`, and friends) so a clap declaration can be ported
-  field by field. See [docs/rust/migrating-from-clap.md](docs/rust/migrating-from-clap.md).
+  field by field. See [docs/rust/migrating-from-clap.md](https://github.com/jdx/usage/blob/main/docs/rust/migrating-from-clap.md).
 - The rendered help, usage line, and diagnostic conventions follow clap's output
   shape so migrated CLIs keep their existing user-facing text.
 - `clap_usage` reads a `clap::Command` through clap's public API to generate a
@@ -84,7 +84,7 @@ The Apache-2.0 option is available upstream at
 
 `benches/shadows/external-*` and `conformance/tests/external_clap_adopters.rs`
 are reductions of three real clap-based CLIs, pinned to the revisions recorded in
-[benches/external/README.md](benches/external/README.md). They are reduced rather
+[benches/external/README.md](https://github.com/jdx/usage/blob/main/benches/external/README.md). They are reduced rather
 than vendored, but they do carry each upstream's declaration shapes and help text,
 so each upstream's license is reproduced below.
 

README.md

@@ -1,17 +1,23 @@
 # Usage
 
-Usage is a spec, CLI, and Rust framework for defining command-line interfaces.
-Arguments, flags, environment variables, and config files can all be described in
-a portable KDL spec. Think of it as [OpenAPI](https://www.openapis.org/) for CLIs:
-one declaration can drive parsing and every user-facing artifact.
+**Define your CLI once. Generate the tools around it.**
 
-- Generate shell completions
-- Generate Markdown documentation and man pages
-- Parse arguments from any language
-- Scaffold a spec into CLI frameworks in different languages
-- Build a typed Rust CLI with a zero-dependency runtime
+Usage is a portable [KDL](https://kdl.dev/) specification, a command-line utility,
+and a Rust framework. Describe commands, flags, arguments, and settings in one
+place, then use that definition for parsing, help, shell completions, Markdown
+docs, man pages, and typed clients.
 
-See more at [usage.jdx.dev](https://usage.jdx.dev/).
+[Get started](https://usage.jdx.dev/guide/getting-started) ·
+[Rust framework](https://usage.jdx.dev/rust/) ·
+[Spec reference](https://usage.jdx.dev/spec/reference/) ·
+[CLI reference](https://usage.jdx.dev/cli/reference/)
+
+| Your starting point   | How Usage fits                                                                               |
+| --------------------- | -------------------------------------------------------------------------------------------- |
+| A new Rust CLI        | Derive a typed parser and exportable spec from structs and enums.                            |
+| An existing CLI       | [Export a spec](https://usage.jdx.dev/spec/integrations) from your framework, or write KDL.  |
+| A script              | [Declare arguments in comments](https://usage.jdx.dev/cli/scripts) and let Usage parse them. |
+| Code that calls a CLI | [Generate a TypeScript or Python SDK](https://usage.jdx.dev/cli/sdk).                        |
 
 ## Rust framework
 
@@ -48,6 +54,46 @@ and value variants. See the [Rust framework guide](https://usage.jdx.dev/rust/)
 and [clap migration guide](https://usage.jdx.dev/rust/migrating-from-clap) for
 the supported mappings and intentional differences.
 
+## Standalone CLI
+
+Choose one installation method:
+
+```sh
+# mise
+mise use -g usage
+
+# Homebrew
+brew install usage
+
+# Cargo
+cargo install usage-cli --locked
+```
+
+The package is `usage-cli`; the executable is `usage`.
+[Other installation options](https://usage.jdx.dev/cli/#installation).
+
+With a spec saved as `mycli.usage.kdl`:
+
+```sh
+usage lint mycli.usage.kdl
+usage generate completion zsh mycli --file mycli.usage.kdl --install
+usage generate markdown --file mycli.usage.kdl --out-file reference.md
+usage generate manpage --file mycli.usage.kdl --out-file mycli.1
+```
+
+The generated shell scripts need `usage` at completion time. The Rust framework
+can also [provide completions directly](https://usage.jdx.dev/rust/completions)
+from your binary.
+
+Follow the [spec walkthrough](https://usage.jdx.dev/guide/getting-started) for a
+complete example. The [Go framework](https://usage.jdx.dev/go/) is a development
+preview and is not ready for adoption or testing.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, checks, and generated
+files.
+
 ## Sponsors
 
 <p align="center">

clap_usage/README.md

@@ -1,30 +1,55 @@
 # clap_usage
 
-Generates [usage spec](https://usage.jdx.dev) for CLIs written with [clap](https://crates.io/crates/clap).
+Export a [Usage spec](https://usage.jdx.dev/spec/) from a
+[clap](https://crates.io/crates/clap) command definition. Use the spec to generate
+shell completions, Markdown documentation, man pages, and SDKs.
 
-## Usage
+## Add the integration
+
+```toml
+[dependencies]
+clap = "4"
+clap_usage = "5"
+```
+
+Expose a hidden flag that prints the spec:
 
 ```rust
-use clap::{arg, Command, ValueHint};
-use clap_usage::generate;
-use std::io::BufWriter;
+use clap::{Arg, ArgAction, Command};
 
 fn build_cli() -> Command {
     Command::new("example")
-        .arg(arg!(--file <FILE> "some input file").value_hint(ValueHint::AnyPath))
-        .arg(arg!(--usage))
+        .arg(Arg::new("file").long("file"))
+        .arg(
+            Arg::new("usage-spec")
+                .long("usage-spec")
+                .hide(true)
+                .action(ArgAction::SetTrue),
+        )
 }
 
 fn main() {
-    let matches = build_cli().get_matches();
-
-    if matches.get_flag("usage") {
-        let mut cmd = build_cli();
-        eprintln!("Generating usage spec...");
-        clap_usage::generate(&mut cmd, "example", &mut std::io::stdout()).unwrap();
+    let mut cmd = build_cli();
+    let matches = cmd.clone().get_matches();
+    if matches.get_flag("usage-spec") {
+        clap_usage::generate(&mut cmd, "example", &mut std::io::stdout());
         return;
     }
-
-    // Your CLI code here...
+    // Run the application using `matches`.
 }
 ```
+
+With the executable and the [Usage CLI](https://usage.jdx.dev/cli/#installation)
+on `PATH`:
+
+```sh
+example --usage-spec > example.usage.kdl
+usage generate markdown --file example.usage.kdl --out-file reference.md
+usage generate completion zsh example --usage-cmd "example --usage-spec" --install
+```
+
+The exporter can only read behavior exposed by clap's public getters. Use
+`spec_with_report` or `generate_with_report` to inspect detectable losses before
+relying on the generated interface. See the
+[integration guide](https://usage.jdx.dev/spec/integrations/clap) for reports,
+compatibility limits, and completion setup.

corpus/README.md

@@ -1,9 +1,7 @@
 # The argv conformance corpus
 
-> Two neighbours have corpora of their own: resolving a CLI's _configuration_ —
-> layers, precedence, merge policies — is [`config/`](config/README.md), and what a
-> spec _reads as_ — the usage line, `-h`, `--help` — is
-> [`render/`](render/README.md). This file is about parsing a command line.
+Related corpora cover [configuration resolution](config/README.md),
+[help rendering](render/README.md), and [completion](complete/README.md).
 
 Test vectors for [the argv grammar](https://usage.jdx.dev/spec/argv). Each one
 pairs a spec with a command line and the result parsing them must produce.

corpus/complete/README.md

@@ -1,6 +1,6 @@
 # The completion corpus
 
-> The corpus two directories up is about what a command line _binds_;
+> The corpus one directory up is about what a command line _binds_;
 > [`render/`](../render/README.md) is about what a spec _reads as_; [`config/`](../config/README.md)
 > is about resolving a CLI's settings. This one is about what could go where the cursor is.
 
@@ -11,22 +11,16 @@ Plain JSON, for the same reason the others are: an implementation in any languag
 without reimplementing a test format. If you are answering `complete` from a usage spec — in Go,
 in JavaScript, or as a second Rust implementation — this directory is the definition of correct.
 
-## Why this exists
+## Scope
 
-Completion is the one area with three implementations and no shared fixture. Parsing has the
-corpus above; rendering got one in `render/`; completion has `argv/src/complete.rs` tested by its
-own unit tests, `cli/src/cli/complete_word.rs` tested by its own, and a Go implementation landed
-in #984 tested by a third set. Three sets of tests written against three readings of the same
-rules is the arrangement that produced every drift this project has had to chase — the help
-renderers agreed on mise and differed on five of the other six CLIs until #972 held them to one
-fixture.
+The Rust and Go completion implementations share these expectations instead of
+maintaining separate interpretations of candidate selection. Vectors cover
+incomplete input, cursor position, restart tokens, and boundaries where a command
+forwards input to an external program.
 
-It also closes the two easier thirds of the corpus gaps that were still open: completion
-parsing, which is `parse_partial` over deliberately incomplete input, and restart tokens, which
-only matter at a cursor. Mounts remain uncovered, and deliberately — resolving one _runs a
-command_, which a corpus cannot do hermetically. The differential fuzzer learned that the
-expensive way: its first draft spawned real `mise` processes that fetched vfox metadata and
-shelled out to `apt-cache`.
+Mount resolution is excluded because it runs a command. Filesystem and dynamic
+completion are represented by their kind rather than by running external
+commands or depending on the test machine's files.
 
 ## What a vector says
 
@@ -81,3 +75,15 @@ Every vector carries a `reference` label, defaulting to `agrees`, saying whether
 the reference implementation — produces exactly this. A vector the reference disagrees with must
 say so and why, so a divergence is a recorded decision rather than a mystery. That is the same
 rule the argv corpus runs on, and `conformance/tests/complete.rs` is what enforces it.
+
+## Run the corpus
+
+From the repository root:
+
+```sh
+mise exec -- cargo test -p usage-conformance --test complete
+```
+
+Add vectors for new completion rules and run the suite before changing a recorded
+reference result. See the [argv corpus](../README.md) for the shared divergence
+contract.