refactor(derive): remove clap compatibility spellings

## Summary

- require `#[usage(...)]` metadata across usage CLI derives and emit
targeted errors for legacy clap helper namespaces
- reject clap-only inner synonyms with their native replacements and
remove implicit clap group generation
- migrate derive fixtures, conformance coverage, generated shadows,
rustdoc, and migration documentation to native syntax

## Testing

- `cargo test -p usage-derive`
- `cargo test -p usage-rs --all-features --tests`
- `cargo test -p usage-conformance --all-features`
- `cargo test -p xtask`
- `cargo test --all --all-features`
- `mise run gen-shadow`
- `mise run ci`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Breaking public derive API: clap-compatible attributes and implicit
Args groups no longer compile. Runtime parse behavior is otherwise
unchanged.
> 
> **Overview**
> **Breaking:** usage CLI derives now accept only native `#[usage(...)]`
metadata. `#[command]`, `#[arg]`, `#[value]`, and `#[group]` are still
registered so they fail at the source span with a rewrite to
`#[usage(...)]`. Inner clap synonyms (`id`, `default_value`,
`conflicts_with`, `value_parser`, `last`, etc.) are rejected the same
way.
> 
> Implicit clap `#[group(...)]` generation is gone. Requiredness comes
only from field types/`required`, not one-member implicit groups.
> 
> Docs, README, conformance tests, and generated shadow CLIs are
rewritten to native syntax. Clap migration examples are explicit
before/after rewrites rather than “keep the old spelling.”
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
840fd41. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added comprehensive support for native `#[usage(...)]` CLI metadata
across commands, arguments, values, aliases, groups, and subcommands.
* Improved handling of required flags and argument groups, including
single-member groups.

* **Bug Fixes**
* Legacy attribute spellings now provide clearer replacement guidance
when unsupported.

* **Documentation**
* Updated migration and subcommand guides with native syntax and
expanded behavior examples.

* **Tests**
* Updated conformance and compatibility coverage for native attribute
behavior.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: jdx

AGENTS.md

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to coding agents working in this repository.
 
 ## Conventional Commits
 
@@ -103,6 +103,16 @@ conformance, generation, and performance tooling:
 
 ## Architecture
 
+### Rust Derives (`derive/`, `usage-rs/`)
+
+The Rust framework uses `#[derive(Cli)]`, `Args`, `Subcommands`, `ValueEnum`, and
+`ArgGroup` to compile typed declarations into argv parse tables and portable spec
+metadata. All derive metadata uses the native `#[usage(...)]` helper attribute.
+Legacy clap helper namespaces such as `#[command(...)]`, `#[arg(...)]`,
+`#[value(...)]`, and `#[group(...)]` are rejected with migration diagnostics; do
+not add compatibility spellings back. Keep clap migration examples as explicit
+before/after rewrites to `#[usage(...)]`.
+
 ### Spec Model (`lib/src/spec/`)
 
 The spec model represents a CLI definition parsed from KDL:

README.md

@@ -1,18 +1,53 @@
 # Usage
 
-Usage is a spec and CLI for defining CLI tools. Arguments, flags, environment variables, and config files
-can all be defined in a Usage spec. It can be thought of like [OpenAPI (swagger)](https://www.openapis.org/)
-for CLIs. Here are some potential reasons for defining your CLI with a Usage spec:
+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.
 
-- Generate autocompletion scripts
-- Generate markdown documentation
-- Generate man pages
-- Use an advanced arg parser in any language
-- Scaffold one spec into different CLI frameworks—even different languages
-- [coming soon] Host your CLI documentation on usage.sh
+- 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
 
 See more at [usage.jdx.dev](https://usage.jdx.dev/).
 
+## Rust framework
+
+Applications can use `usage-rs` to derive a typed parser and a portable Usage
+spec from the same Rust declaration:
+
+```toml
+[dependencies]
+usage = { package = "usage-rs", version = "6" }
+```
+
+```rust
+use usage::Cli;
+
+#[derive(Cli)]
+#[usage(bin = "example", version)]
+struct App {
+    /// Print more detail.
+    #[usage(short = 'v', long, count)]
+    verbose: u8,
+
+    /// Files to process.
+    files: Vec<String>,
+}
+
+fn main() {
+    let app = App::parse();
+    // app.verbose and app.files are ready to use
+}
+```
+
+Usage has its own derive vocabulary: use `#[usage(...)]` on commands, fields,
+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.
+
 ## Sponsors
 
 usage is sponsored by [entire.io](https://entire.io) and [37signals](https://37signals.com).
@@ -21,10 +56,10 @@ usage is sponsored by [entire.io](https://entire.io) and [37signals](https://37s
 
 ## Acknowledgements
 
-Usage's design owes a great deal to [clap](https://github.com/clap-rs/clap) — the
-derive attribute vocabulary, the help output shape, and the diagnostic conventions
-all follow it deliberately so clap CLIs can be ported field by field. clap's
-license is reproduced in [NOTICE.md](NOTICE.md).
+Usage's design owes a great deal to [clap](https://github.com/clap-rs/clap). Its
+help output and diagnostic conventions make clap migrations familiar, while
+Usage's native derive attributes reflect its portable spec model. clap's license
+is reproduced in [NOTICE.md](NOTICE.md).
 
 ## License
 

benches/shadows/aube/src/lib.rs

@@ -536,25 +536,25 @@ pub struct AuditArgs {
 
 #[derive(ValueEnum)]
 pub enum AuditAuditLevelValue {
-    #[value(name = "info")]
+    #[usage(name = "info")]
     Info,
-    #[value(name = "low")]
+    #[usage(name = "low")]
     Low,
-    #[value(name = "moderate")]
+    #[usage(name = "moderate")]
     Moderate,
-    #[value(name = "high")]
+    #[usage(name = "high")]
     High,
-    #[value(name = "critical")]
+    #[usage(name = "critical")]
     Critical,
 }
 
 #[derive(ValueEnum)]
 pub enum AuditFixValue {
     /// Refresh the lockfile to patched versions allowed by existing ranges.
-    #[value(name = "update")]
+    #[usage(name = "update")]
     Update,
     /// Write package.json overrides that force patched versions.
-    #[value(name = "override")]
+    #[usage(name = "override")]
     Override,
 }
 
@@ -904,13 +904,13 @@ pub struct ConfigDeleteArgs {
 #[derive(ValueEnum)]
 pub enum ConfigDeleteLocationValue {
     /// User config (`~/.config/aube/config.toml` for known aube settings, `~/.npmrc` for registry/auth and unknown keys)
-    #[value(name = "user")]
+    #[usage(name = "user")]
     User,
     /// `<cwd>/.npmrc`
-    #[value(name = "project")]
+    #[usage(name = "project")]
     Project,
     /// Alias for `user` — aube has no separate global config file.
-    #[value(name = "global")]
+    #[usage(name = "global")]
     Global,
 }
 
@@ -964,16 +964,16 @@ pub struct ConfigGetArgs {
 #[derive(ValueEnum)]
 pub enum ConfigGetLocationValue {
     /// Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses).
-    #[value(name = "merged")]
+    #[usage(name = "merged")]
     Merged,
     /// Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)
-    #[value(name = "user")]
+    #[usage(name = "user")]
     User,
     /// Only `<cwd>/.npmrc`
-    #[value(name = "project")]
+    #[usage(name = "project")]
     Project,
     /// Alias for `user`.
-    #[value(name = "global")]
+    #[usage(name = "global")]
     Global,
 }
 
@@ -1008,16 +1008,16 @@ pub struct ConfigListArgs {
 #[derive(ValueEnum)]
 pub enum ConfigListLocationValue {
     /// Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses).
-    #[value(name = "merged")]
+    #[usage(name = "merged")]
     Merged,
     /// Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)
-    #[value(name = "user")]
+    #[usage(name = "user")]
     User,
     /// Only `<cwd>/.npmrc`
-    #[value(name = "project")]
+    #[usage(name = "project")]
     Project,
     /// Alias for `user`.
-    #[value(name = "global")]
+    #[usage(name = "global")]
     Global,
 }
 
@@ -1051,13 +1051,13 @@ pub struct ConfigSetArgs {
 #[derive(ValueEnum)]
 pub enum ConfigSetLocationValue {
     /// User config (`~/.config/aube/config.toml` for known aube settings, `~/.npmrc` for registry/auth and unknown keys)
-    #[value(name = "user")]
+    #[usage(name = "user")]
     User,
     /// `<cwd>/.npmrc`
-    #[value(name = "project")]
+    #[usage(name = "project")]
     Project,
     /// Alias for `user` — aube has no separate global config file.
-    #[value(name = "global")]
+    #[usage(name = "global")]
     Global,
 }
 
@@ -1099,16 +1099,16 @@ pub struct ConfigArgs {
 #[derive(ValueEnum)]
 pub enum ConfigLocationValue {
     /// Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses).
-    #[value(name = "merged")]
+    #[usage(name = "merged")]
     Merged,
     /// Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)
-    #[value(name = "user")]
+    #[usage(name = "user")]
     User,
     /// Only `<cwd>/.npmrc`
-    #[value(name = "project")]
+    #[usage(name = "project")]
     Project,
     /// Alias for `user`.
-    #[value(name = "global")]
+    #[usage(name = "global")]
     Global,
 }
 
@@ -2134,16 +2134,16 @@ pub struct GetArgs {
 #[derive(ValueEnum)]
 pub enum GetLocationValue {
     /// Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses).
-    #[value(name = "merged")]
+    #[usage(name = "merged")]
     Merged,
     /// Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)
-    #[value(name = "user")]
+    #[usage(name = "user")]
     User,
     /// Only `<cwd>/.npmrc`
-    #[value(name = "project")]
+    #[usage(name = "project")]
     Project,
     /// Alias for `user`.
-    #[value(name = "global")]
+    #[usage(name = "global")]
     Global,
 }
 
@@ -2625,11 +2625,11 @@ pub struct LaArgs {
 
 #[derive(ValueEnum)]
 pub enum LaFormatValue {
-    #[value(name = "default")]
+    #[usage(name = "default")]
     Default,
-    #[value(name = "json")]
+    #[usage(name = "json")]
     Json,
-    #[value(name = "parseable")]
+    #[usage(name = "parseable")]
     Parseable,
 }
 
@@ -2766,11 +2766,11 @@ pub struct ListArgs {
 
 #[derive(ValueEnum)]
 pub enum ListFormatValue {
-    #[value(name = "default")]
+    #[usage(name = "default")]
     Default,
-    #[value(name = "json")]
+    #[usage(name = "json")]
     Json,
-    #[value(name = "parseable")]
+    #[usage(name = "parseable")]
     Parseable,
 }
 
@@ -2825,11 +2825,11 @@ pub struct LlArgs {
 
 #[derive(ValueEnum)]
 pub enum LlFormatValue {
-    #[value(name = "default")]
+    #[usage(name = "default")]
     Default,
-    #[value(name = "json")]
+    #[usage(name = "json")]
     Json,
-    #[value(name = "parseable")]
+    #[usage(name = "parseable")]
     Parseable,
 }
 
@@ -3916,9 +3916,9 @@ pub struct SbomArgs {
 
 #[derive(ValueEnum)]
 pub enum SbomFormatValue {
-    #[value(name = "cyclonedx")]
+    #[usage(name = "cyclonedx")]
     Cyclonedx,
-    #[value(name = "spdx")]
+    #[usage(name = "spdx")]
     Spdx,
 }
 
@@ -4009,13 +4009,13 @@ pub struct SetArgs {
 #[derive(ValueEnum)]
 pub enum SetLocationValue {
     /// User config (`~/.config/aube/config.toml` for known aube settings, `~/.npmrc` for registry/auth and unknown keys)
-    #[value(name = "user")]
+    #[usage(name = "user")]
     User,
     /// `<cwd>/.npmrc`
-    #[value(name = "project")]
+    #[usage(name = "project")]
     Project,
     /// Alias for `user` — aube has no separate global config file.
-    #[value(name = "global")]
+    #[usage(name = "global")]
     Global,
 }
 
@@ -5245,29 +5245,29 @@ pub struct Cli {
 
 #[derive(ValueEnum)]
 pub enum LoglevelValue {
-    #[value(name = "trace")]
+    #[usage(name = "trace")]
     Trace,
-    #[value(name = "debug")]
+    #[usage(name = "debug")]
     Debug,
-    #[value(name = "info")]
+    #[usage(name = "info")]
     Info,
-    #[value(name = "warn")]
+    #[usage(name = "warn")]
     Warn,
-    #[value(name = "error")]
+    #[usage(name = "error")]
     Error,
-    #[value(name = "silent")]
+    #[usage(name = "silent")]
     Silent,
 }
 
 #[derive(ValueEnum)]
 pub enum ReporterValue {
-    #[value(name = "default")]
+    #[usage(name = "default")]
     Default,
-    #[value(name = "append-only")]
+    #[usage(name = "append-only")]
     AppendOnly,
-    #[value(name = "ndjson")]
+    #[usage(name = "ndjson")]
     Ndjson,
-    #[value(name = "silent")]
+    #[usage(name = "silent")]
     Silent,
 }