usage: starší verze ke stažení

This release reduces how much code usage-argv adds to CLIs that embed it. Help, -h, version, completion and parse-error output stay byte-for-byte the same, and startup and parse speed are unchanged.
Changed
- (lib) Help, completion and error rendering in usage-argv produce less machine code (#1551, #1553, #1554, @jdx). String appends, text wrapping, slicing, searching, completion splitting and error suggestions now go through shared helpers instead of being expanded at every call site. In stripped release builds of oxlint and oxfmt, the three PRs together removed about 85 KB from each binary. That covers most of the size those CLIs gained when they moved from bpaf to usage-rs.

Fixed
- (complete) Split::walked and Split::argv no longer panic when cword is out of range. They now return the whole word list and an empty slice (#1554, @jdx).

💚 Sponsor usage
usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.
If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

The derive macros now generate code against usage_rs directly instead of reading your Cargo.toml, usage generate fig has been removed, and the fields on argv metadata types are no longer public API. usage exec now accepts interpreter arguments, and this release also fixes how -- is handled by the shell runners and how multi-line examples are indented in help.
Breaking Changes
All of these come from #1532 (@jdx).
- The derive macros always generate paths through ::usage_rs. In 6.12, usage-derive parsed your Cargo.toml to work out how usage-rs was imported. That put toml and related crates into every downstream build. The macros no longer read the manifest, so toml is out of the dependency tree. If a derive can't find the facade crate, compilation fails with unresolved import usage_rs. To upgrade:
- Depend on usage-rs under its own name: usage-rs = { version = "7" }.
- If you import it under another name, such as usage = { package = "usage-rs", ... }, add #[usage(crate = usage)] to each derive that needs it. The attribute works on Cli, Args, Subcommands, ValueEnum, ArgGroup and Config, and you have to repeat it on every derive.
#[derive(usage::Cli)]
#[usage(crate = usage, bin = "ex")]
struct Ex { /* ... */ }
- If you depend directly on usage-argv, usage-derive, usage-config or usage-validation, also add usage-rs = { version = "7", default-features = false, features = ["spec"] }. Turn on the config or validation features if you use those crates, since they're now reached through usage_rs::config and usage_rs::validation.
- schema_from = T now always generates ::schemars. If you renamed the schemars dependency, change it back to its real name.
- The derives no longer look up workspace-inherited or target-specific dependencies.
- usage generate fig is removed. Fig shut down in 2024. Use usage generate completion <shell> instead.
- Fields on FlagMeta, CommandMeta and ArgMeta in usage-argv are now #[doc(hidden)]. Their struct layout is no longer covered by semver. Use the existing accessor methods instead, for example flag.env_fallback() rather than flag.env_fallback.

Added
- (cli) usage exec takes a quoted interpreter followed by its own arguments, and splits them the way a shell would (#1537, @jdx). Before this, there was no shebang form for interpreters that need flags before the script path, such as Deno's run and its permission flags. Values without whitespace, values that are paths to existing files, and the unquoted form all work as before.
#!/usr/bin/env -S usage exec "deno run --allow-env=usage_*"
//USAGE arg "<name>" help="Name to greet"

Fixed
- (cli) In usage bash, zsh, fish and powershell, words after -- now reach the script as values (#1541, @jdx). Previously, usage bash script.sh positional -- --help printed the script's help with an Error: prefix and exited with status 1. -h and --help still show help when they come before --.
- (cli) In --help output, every line of a multi-line example is now indented (#1548, @jdx). Before, sample output lines after the first started at column 0.

💚 Sponsor usage
usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.
If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

This release doesn't change runtime behavior or public APIs. It matters mainly to downstream packagers who test each optional feature of the crates separately.
Fixed
- (lib) The test suites now pass when an optional feature is enabled on its own (#1513, @jdx). Four configurations used to fail even though the all-features tests passed: usage-argv with only complete, only diagnostics or only spec, and usage-rs with only test. CI now tests each of these separately. This brings in the two test patches from Debian's packaging (debcargo-conf MR !1447), which packagers can drop starting with this release.

💚 Sponsor usage
usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.
If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

Wrapper CLIs can now pass completion of their trailing words to the wrapped tool's own shell completion. Argument values can come from a command's output with choices run=, and scripts get the chosen subcommand as $usage_cmd. The release also fixes several completion bugs in bash, zsh and fish, and two crashes in #[derive(Cli)] binaries.
Added
- (complete) complete … delegate="<command>" completes a wrapped command's arguments with that command's own shell completion (#1498, @jdx). With the spec below, wrapper layer1 plan -o<Tab> offers whatever terraform plan -o<Tab> would. delegate can carry fixed arguments (delegate="kubectl --context prod"), and it can't be combined with run or type. It works in fish, bash (requires bash-completion) and zsh. PowerShell and Nushell get no delegated candidates. Typed words are passed to the shell as arguments, not spliced into a script, so they are never run. If the shell can't answer within 3 seconds, completion falls back to files. Fig output leaves delegated args bare.
arg "<layer>"
arg "<command>" var=#true
complete "command" delegate="terraform"
- (spec) choices run="…" builds an argument's or flag's allowed values from a command that prints one value per line (#1497, @jdx). These values are used to check input (strict and ignore_case still apply), for Tab completion, and in --help handled by the parser, usage bash and usage exec. Any values written on the node are kept alongside them. Static outputs never run the command. render_help, Markdown and man pages describe it as output of `…` , Fig emits a generator, and Go tables and TypeScript/Python SDK types treat the value as an open string. During a parse, the command runs at most once and only when a declared value doesn't match. Parser::with_env values are passed to it. New library API includes SpecChoices::run, resolved_values(env), SpecArgBuilder::choices_run, usage::docs::cli::render_runtime_help and usage::sh::sh_with_env. Fig generator commands, from both choices run= and complete run=, now escape backslashes, backticks and ${.
arg "<service>" {
choices run="docker compose config --services"
}
- (spec) A complete node can now sit inside the arg it completes, including a flag's arg, or directly inside a flag as shorthand for its value (#1496, @jdx). The inline form takes run, type and descriptions but no name. It takes precedence over a named complete "<name>" for the same arg. The new Spec::completer(cmd, arg) applies this order, and complete-word, Fig, usage-dynamic and the Go generator all follow it.
flag "--out <path>" {
complete type="dir"
}
- (lib) Scripts run by usage bash, zsh, fish, powershell and exec get the chosen subcommand's canonical name in usage_cmd, with nested names joined by spaces, such as "db migrate" (#1505, @jdx). It is unset at the top level, and a usage_cmd inherited from a parent process is cleared. If the spec declares its own flag or arg named cmd, that one keeps the variable. The value comes from ParseOutput::as_env, so other embedders such as mise tasks get it too.
- (lib) FlagMeta, CommandMeta and ArgMeta in usage-rs/usage-argv have a const fn getter for every field, including the fields that 6.11.1 moved into extra (#1491, @jdx). For example, flag.env_fallback() works however the struct is laid out. The fields stay public for now, but v7 plans to hide them, so switch to the getters.
- (lib) Parser::without_running_commands() parses without starting any choices run= command (#1503, @jdx). A value outside the declared choices is accepted unchecked. usage explain now uses this mode, so explaining a command line against an untrusted spec never runs that spec's commands.
- (cli) Releases now ship a version-matched usage agent skill for writing specs, parsing script arguments, using usage explain, and generating completions and docs (#1509, @jdx). mise users can install it with mise use usage and then mise skills sync --dir .agents/skills.

Fixed
- (derive) A generated Cli::parse() no longer panics when 

The help, completion, parse-error and metadata code that usage-argv adds to a #[derive(Cli)] binary is substantially smaller, with byte-identical output, and coloured help pages no longer colour author text that happens to look like a heading or a flag row.
Fixed
- (help) Coloured help colours only the structure the renderer itself writes (#1480, @jdx). Colour used to be applied by matching every finished line against the page's headings, synopsis and row usages, so a line reading Flags: in after_help/before_help/about, or heading prose that began with a flag's spelling such as -f, --force overrides the *lock*, came out styled as a heading or a flag row. Headings, the synopsis, row usages and command names are now coloured as they are written, and the remaining pass over the page applies only Markdown emphasis (**bold**, *italic*, `code`, ~~strike~~), still skipping $ example lines. Plain (non-TTY) output was never affected and is unchanged.

Changed
- (argv) Less code and static data per derived CLI (#1469, #1471, #1476, #1475, #1477, #1478, @jdx). Help rows for -h and --help go through one renderer, coloured-help structure is collected while the page is written instead of by a second metadata walk, the __complete_word__ handler and the value-binding/error-exit code that the derive used to expand into every CLI now live in the runtime, the parse-error renderer builds messages from data instead of per-error formatting code, and cold-path lists (help rows, completion candidates, "did you mean" suggestions) share one stable sort instead of six monomorphised quicksorts. View-related branches fold away entirely for CLIs that declare no views. Help, error, spec and completion output was compared byte for byte before and after each change and is identical; a completion request now also walks the command line once instead of twice.
- (argv) Smaller metadata tables (#1470, #1472, #1474, @jdx). Rarely declared flag fields (relations, deprecation, validation, bounds, hidden aliases, spec-only metadata) moved into FlagExtra behind FlagMeta::extra, and rarely declared command fields (deprecation, help prose, examples, headings, outputs, layout settings, clause, exit codes) into CommandExtra behind CommandMeta::extra; every flag or command that declares none of them points at one shared static. Clauses are stored by reference and display_order, variadic bounds and terminal widths are narrowed to u32/u16. A FlagMeta shrinks from 664 to 168 bytes and a CommandMeta from about 600 to 472. Declared values too large for the narrower types now saturate rather than wrap (a display_order above u32::MAX sorts last; term_width = 0 still disables wrapping).
Measured on oxlint and oxfmt with their release profile (opt-level 3, fat LTO, one codegen unit, linux x86_64), the first two changes alone cut what usage-rs adds over bpaf from about 219 KB to 138 KB for oxlint (from 169 KB to 114 KB for oxfmt), and each of the remaining changes took a further 1 to 14 KB off.

Breaking Changes
Only code that reads or hand-writes usage-argv metadata tables directly is affected; CLIs built with #[derive(Cli)], Args or ArgGroup need no changes.
- Fields moved off FlagMeta and CommandMeta are reached through extra (#1470, #1472):
// before
if let Some(reason) = meta.deprecated { /* … */ }
// after
if let Some(reason) = meta.extra.deprecated { /* … */ }
// hand-written table
static META: CommandMeta = CommandMeta {
cmd: &CMD,
about: Some("…"),
extra: &CommandExtra {
deprecated: Some("use `new`"),
..CommandExtra::EMPTY
},
..CommandMeta::EMPTY
};
..FlagMeta::EMPTY and ..CommandMeta::EMPTY already point at the shared NO_FLAG_EXTRA/NO_COMMAND_EXTRA, so entries with no extras keep working unchanged.
- Command::clause is now Option<&Clause> and CommandMeta::clause (now under extra) is Option<&ClauseMeta>, so hand-written tables borrow the clause: clause: Some(&TASKS). display_order, var_min/var_max and value_var_min/value_var_max are Option<u32>, and term_width/max_term_widt

Help output now wraps to the real terminal width instead of a fixed 80 columns, a spec can put ASCII art on its root help page, and default_subcommand_on_empty routes a bare invocation to the default subcommand.
Added
- (parse) default_subcommand_on_empty selects the default subcommand on an empty invocation (#1458, @zeitlinger). Until now default_subcommand only fired on an unmatched word, so ex with no arguments stayed on the root. With this opt-in (Rust: #[usage(default_subcommand = "run", default_subcommand_on_empty)]), a bare ex or one carrying only parent/global flags such as ex --verbose parses as ex run, with child env values and defaults bound afterwards and the child validated exactly as if it had been named. Explicit commands, positional values, a syntactic --, --help, --version, and parse errors keep their normal precedence; root requirements still apply unless subcommand_negates_reqs is set. It requires default_subcommand (usage lint reports invalid-default-subcommand-on-empty otherwise) and is implemented in the Rust library, usage-argv, generated Go parsers, and the Go runtime.
default_subcommand "run"
default_subcommand_on_empty #true
cmd "run" { arg "[path]" }
- (spec) logo puts art on the root help page (#1455, @jdx). The optional style property takes the same +-combined vocabulary as help_template (for example "cyan+bold") and is validated when the spec is parsed, or at compile time for #[usage(logo = include_str!("logo.txt"), logo_style = "cyan+bold")]. Placement depends on terminal width: beside the page when at least 50 columns remain after the art and a two-column gutter, above it as a banner when they do not, and omitted entirely when the terminal is narrower than the art. The logo appears only on the root's -h/--help, never on subcommand pages or in generated Markdown, man pages, or SDKs, and plain (non-TTY) output strips its escapes. usage --help itself now shows the project's logo. The Rust library, usage-argv, and Go renderers share one placement rule.
logo #"""
/\
/ \
/____\
"""# style="cyan+bold"

Fixed
- (help) Help is laid out at the terminal's actual width (#1454, @jdx). Width came only from COLUMNS, which almost no process has set, so nearly every CLI built on usage wrapped at 80 columns regardless of the window. The renderers now probe the terminal (TIOCGWINSZ on unix, the console buffer on Windows) when COLUMNS is unset; output to a pipe or file still uses 80, and a declared term_width/max_term_width still wins. The probe is exposed as usage_argv::tty::columns(). The Go renderer still uses a fixed 80 columns.
- (help) Cli::render_help now colours its output by the same rule as parse(): ANSI on a terminal, plain elsewhere, NO_COLOR respected (#1454). CLIs that handled usage::Error::Help themselves were getting a monochrome page. Callers that keep the text rather than printing it can use the new Cli::render_help_styled(cmd, long, Style::PLAIN) to guarantee escape-free output; see Breaking Changes.
- (help) Examples are separated by a blank line on both -h and --help, in all three renderers, instead of running together as a single block (#1454).
- (cli) The published usage-cli crate now includes src/cli/logo.txt, which the initial 6.11.0 publish was missing and failed on (#1459, @jdx).

Breaking Changes
- Cli::render_help (the derive-generated method) may now return ANSI escape sequences when stdout is a terminal. Code that writes its result to a file, compares it in a snapshot, or embeds it in a document should switch to Cli::render_help_styled(cmd, long, Style::PLAIN); setting NO_COLOR also forces plain output with no code change. usage_argv::help::render is unchanged and still plain.
- Help pages rendered to a terminal now wrap at the detected width rather than 80 columns. Redirected output and specs that declare term_width are unaffected.

💚 Sponsor usage
usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.
If usage powers

Help output can now mark and append the default subcommand's page, usage generate go can emit typed struct fields, and the Go runtime gains argv.RenderRequest plus fixes so generated parsers actually surface --help and --version. Embedders that parse spec text also get proper diagnostics, a path for relative includes, and environment-variable expansion in include paths.
Added
- (help) Mark the default subcommand and optionally append its help page (#1424, @lu-zero). A visible default_subcommand is now listed with (default) in the command list. The new default_subcommand_help #true setting (Rust: #[usage(default_subcommand_help)]) appends the default child's own page after the parent's, so ex --help shows the default command's flags and args without hoisting them into the root grammar. Hidden defaults are neither marked nor appended, flatten_help skips the append since it already inlines every child, and usage lint reports default_subcommand_help without a default_subcommand. Supported in the Rust and Go help renderers. Fixes #1423.
default_subcommand "install"
default_subcommand_help #true
cmd "install" help="Put a package on the system" {
flag "-u --update"
arg "[package]"
}
- (go) Explicitly typed fields from usage generate go (#1441, @zeitlinger). The repeatable --field-type KEY=TYPE flag binds a generated flag or argument key constant (for example FlagTimeout or FlagRunTimeout) to int, int64, uint64, float64, bool, or duration (time.Duration); variadic entries become typed slices. Conversion happens once on the final resolved value after argv/env/default precedence and validation, and invalid values return argv.CodeInvalidValue. Unknown keys, duplicate bindings, unsupported types, and valueless or count flags are rejected at generation time. Library callers get usage::go::generate_with_types and ValueType; unconfigured output is unchanged. Typed output requires the runtime from this release (argv.NativeInt).
usage generate go -f mycli.usage.kdl -o tables.go \
--field-type FlagTimeout=duration --field-type FlagJobs=int
- (go) argv.RenderRequest renders help and version requests (#1439, @zeitlinger). Go applications no longer need to rebuild the command chain and pick a renderer themselves: pass the parser's CodeHelp/CodeVersion error, the help metadata, root command, and the same words given to the parser, and get back the rendered text. It handles short, long, and recursive help plus short/long version (falling back to Version when LongVersion is empty), preserves invoked aliases and shared-command ancestry, and includes inherited globals from the correct route. Output, write errors, and exit status stay with the caller; ordinary errors return ("", false).
meta := HelpMeta
meta.Version = buildVersion
if text, handled := argv.RenderRequest(request, meta, Root, args, HelpText); handled {
io.WriteString(os.Stdout, text)
}
- (spec) Environment variables in include paths (#1446, @jdx). Spec::parse_str_with_path_and_env accepts an environment map so include file="$CONFIG_ROOT/shared.usage.kdl" expands $NAME and ${NAME} (with $$ for a literal dollar sign) without mutating the process environment. Undefined variables return a diagnostic, nested includes inherit the same map, and relative paths still resolve from the declaring file. Expansion applies only to include paths.
- (spec) Spec::parse_str_with_path (#1443, @jdx). Callers that extract spec text from a larger file (script comments, a rendered template) can now say which file it came from, so relative include paths resolve against it. FromStr still rejects relative includes since it has no path to resolve them against.

Fixed
- (go) Generated Go parsers return help and version requests (#1437, @zeitlinger). Generated Parse previously ignored the built-in -h/--help and -V/--version flags, so a CLI with required arguments reported a missing argument and one without could continue into normal execution. They now become CodeHelp/CodeVersion errors that preserve the selected comma

A default-only flag now commits the rest of the line to the default subcommand even when a later word spells a sibling command, and the KDL parser scans strings in chunks so large generated specs load several times faster. The Go modules now require Go 1.26.
Fixed
- (parse) Keep the implicit default after a default-only flag (#1418, @lu-zero). With default_subcommand_flags, the lookahead cancelled default routing whenever any later word matched a sibling command or alias, so em -u pkg failed with UnknownFlag -u just because pkg is also a command. Once a default-only flag has been seen, later words are now the default command's arguments: em -u query parses as em install -u query, as do em -X foo query, em -pu query, and --output query search. A sibling name before any default-only flag still selects it (em query, em -p query), and parent-only flags, --help, and bare invocations stay on the parent. Applied consistently to the Rust library, usage-argv, and the Go runtime; fixes #1417.

Changed
- (parse) Faster KDL parsing for large specs (#1426, @jdx). Identifier, quoted-string, and raw-string runs are scanned as contiguous slices instead of one Unicode scalar at a time, with escapes, delimiters, newlines, and dedent handling preserved at the boundaries. Parsing the checked-in mise spec drops from 66.9 ms to 16.2 ms in an optimized build, and from roughly 800 ms to 250 ms in a debug build of mise's 321 KB generated spec. Parsed output is unchanged; a regression test covers embedded quotes in multiline raw strings.
- (go) The github.com/jdx/usage/go and integrations/cobra modules now declare go 1.26.0 (#1421, @sahidvelji). Projects importing the Go runtime or the Cobra integration need Go 1.26 or newer; expr-lang/expr is now listed as a direct dependency of the runtime module. No behavior changes.
- (go) usage generate go emits type X struct{} for a command with no flags, arguments, or subcommands instead of an empty two-line struct body, matching gofumpt output (#1425, @sahidvelji). Regenerating existing code will show this whitespace-only diff.

New Contributors
- @sahidvelji made their first contribution in #1421

💚 Sponsor usage
usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.
If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

Flags belonging to a default subcommand can now select it without typing its name, a derived Args type can be parsed on its own, help colours can be remapped, and a series of help-rendering changes trims binary size for usage-rs adopters. Bash completion also stops mangling colon-separated candidates.
Added
- (parse) Opt-in default-subcommand flag routing (#1413, @jdx). With default_subcommand_flags, leading flags that belong only to the configured default subcommand route to it, so em -ua @world parses as em install -ua @world. Explicit command names and aliases still win, parent-only flags and bare invocations stay on the parent, a mixed short bundle such as -pua keeps the parent's -p, and -- or an unknown flag stops the lookahead. Completion also offers the default command's flags at the root. Supported in KDL specs, the Rust derive, and the Go runtime; existing routing is unchanged without the opt-in. usage lint reports default_subcommand_flags declared without a default_subcommand.
default_subcommand "install"
default_subcommand_flags #true
#[usage(default_subcommand = "install", default_subcommand_flags)]
- (parse) Parse a derived Args type without an enclosing CLI (#1419, @jdx). usage::parse_args_from::<T> treats the slice as that command's words; usage::parse_args_from_argv::<T> strips argv0 first. Both reuse the command's compiled flags, positionals, defaults, validation, and nested subcommands, and return the ordinary parse errors, including help and version requests. Available behind the spec feature.
let install = usage::parse_args_from::<Install>(&args)?;
- (help) Remap semantic help colours with a Palette (#1414, @lu-zero). The heading, option, metavar, and command roles were previously fixed SGR colours. help::Palette remaps any of them using the existing {$…} tag vocabulary (for example "cyan+bold"), and Style::palette applies it; role names expand once, so mapping metavar to "heading" uses the built-in heading colour. Hosts that own the exit path get embedded_outcome_paletted / embedded_outcome_into_paletted (and embedded::outcome_paletted); parse() and plain rendering are unchanged.
let palette = usage::help::Palette::DEFAULT.metavar("cyan+bold");
match Ex::embedded_outcome_paletted(&argv, palette) { /* … */ }

Changed
- (cli) Smaller binaries and faster help rendering (#1396, #1399, #1400, #1401, @jdx). Help sorting and rendering do less work and share more code, plain (uncoloured) help skips colour-span analysis, and the flag diagnostics share one formatter. Help output is byte-identical; on the oxc binaries used for measurement this removed roughly 360 KiB combined, and plain --help rendered about 18% faster locally. Two new opt-ins let CLIs trim further:
- Flattened subcommand pages, HelpAll, and recursive render_all now live behind a help-advanced feature (enabled by default in usage-rs and usage-argv). A CLI that uses none of them can disable defaults and omit it:
usage = { package = "usage-rs", version = "6", default-features = false, features = ["help", "diagnostics", "completions"] }
- #[usage(spec_endpoint_file = "cli.usage.kdl")] answers __usage_spec__ from a KDL file included at compile time, keeping the endpoint without linking the runtime serializer. to_kdl() still generates from live metadata, so regenerate the file after CLI changes and test the two for drift.
Compatibility note: dependents that already set default-features = false and declare flatten_help or a HelpAll flag must add help-advanced; the derive now rejects those declarations at compile time, and hand-written metadata requesting advanced help panics when rendered instead of being silently ignored.

Fixed
- (bash) Preserve colon-prefixed completion words (#1405, @jdx). When : is in COMP_WORDBREAKS, Readline replaces only the fragment after the last colon, so candidates such as update:deps:no-cooldown were inserted with a duplicated update:deps: prefix. The generated Bash script now forwards the current Readline word and COMP_WORDBR

This release gives the usage CLI native shell completions (including PowerShell), adds a configurable link extension for Markdown docs, and fixes a batch of synopsis and Markdown rendering issues across docs and man pages.
Added
- (cli) Native shell completions (#1388, @jdx). usage --completions <shell> now emits native scripts that call the installed binary's compiled completion handler instead of caching a spec and relying on the bash-completion helpers. Bash, Zsh, Fish, and a new PowerShell script are all supported, and scripts use command usage so a shell function or alias can no longer shadow the executable. All four scripts are published alongside the CLI spec as signed Packslip resources. General usage generate completion behavior is unchanged.
- (docs) Configurable Markdown link extension (#1394, @jdx). Generated Markdown links previously always ended in .md, forcing consumers who serve HTML or extensionless pages to rewrite links after generation. A new --link-extension flag (and MarkdownRenderer::with_link_extension, default .md) controls the suffix on command and configuration links without changing output filenames:
usage generate markdown --file mycli.usage.kdl --link-extension .html
Custom templates now also receive link_extension and config_link in their context.

Fixed
- (docs) Render optional subcommands and mount synopses (#1393, @jdx). Generated synopses showed <SUBCOMMAND> even when a command could run without one; the shared usage string now honors subcommand_required (using [SUBCOMMAND] when optional) and custom placeholder names, keeping terminal help, Markdown, man pages, JSON, and SDK docs consistent. Unresolved mounts can also declare a display-only synopsis (for example mount run="mycli tasks --usage" synopsis="[TASK] [ARGS]…") to document dynamic arguments without running discovery; parsing and completion are unchanged.
- (docs) Preserve Markdown code blocks and headings (#1392, @jdx). Indented help text was converted to code fences by stripping four spaces from every matching line, which could corrupt nested lists and existing fenced examples. Markdown code-block boundaries are now parsed so only real indented code blocks are converted, fences are chosen longer than any embedded backtick runs, and HTML escaping recognizes longer fences. Hidden subcommands are now filtered out before the Subcommands heading, and the duplicate synopsis line was removed from the multipage index.
- (manpage) Render mount synopses and custom command names (#1395, @jdx). Completes the man-page side of the synopsis fixes above. The man-page renderer now carries declarative mount synopses and custom subcommand names into its own synopsis (instead of hard-coded <COMMAND>/[COMMAND]), includes mount fragments in root and subcommand synopses without running discovery, and emits a detail section for a command whose only documentation is a mount synopsis.

Changed
- (docs) Refreshed guides, navigation, and landing page (#1391, @jdx). A new getting-started guide walks from install through KDL, lint/explain, docs/man, completions, and diff. Navigation is reorganized into guides, framework docs, and references with route-specific sidebars; the landing page is simplified with clearer starting points for Rust apps, existing CLIs, and scripts. Installation commands, Rust and SDK examples, and completion setup were corrected, Go is now labeled a development preview, and broken links across all 171 Markdown files were fixed.

💚 Sponsor usage
usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.
If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

A parser-level fix that makes double_dash="required" actually behave as declared drives the major bump: values before -- are now rejected, and values after -- are routed past greedy variadics to the arg that was waiting for them. The release also fixes a cluster of long-standing Windows problems — usage bash losing every usage_* variable under WSL, run= scripts being handed to cmd /c, and completion guards being fooled by a shell function named usage — and lets generate markdown write to stdout like the other generators.
Added
- Override the shell binary with USAGE_SHELL_<SHELL> (#767 by @JamBalaya56562). Point usage bash, usage zsh, usage fish, and usage powershell at a specific interpreter — mainly so Windows users can escape the WSL bash.exe that Win32's search order picks up ahead of $PATH:
set USAGE_SHELL_BASH=C:\Program Files\Git\usr\bin\bash.exe
usage bash C:/work/mycli
The variable is keyed by the program (so powershell's override is USAGE_SHELL_PWSH). Unset, empty, or whitespace-only falls back to the default. Spawn failures now name the program that was tried and the variable it came from, and on Windows a bash exit 127 against a drive-letter path prints a hint pointing at this override.
- generate markdown writes to stdout (#766 by @JamBalaya56562). --out-file is now optional and defaults to stdout, matching manpage, fig, json, and completion. --out-file - also means stdout on markdown, manpage, and fig, mirroring the -f - input convention. The writing to … progress line moved to stderr on markdown, manpage, fig, and sdk, so it no longer ends up inside the generated document. --out-dir now requires --multi.

Fixed
- double_dash="required" is now enforced on both sides (#762 by @JamBalaya56562). The parser previously ignored SpecDoubleDashChoices::Required entirely — a word offered to such an arg without -- was accepted anyway, and a required arg sitting behind a greedy variadic was unreachable even with a separator. Now offering a value before -- is reported as ArgRequiresDoubleDash (once per variadic, not once per word), and an explicit -- routes the positional cursor onto the arg that required it, past earlier args. Completion learns about -- too: while an arg is locked behind a separator, -- itself is offered rather than values the parser would reject.
- Windows: usage_* variables reach WSL bash (#764 by @JamBalaya56562). On Windows the bash picked up from the system directory is WSL's launcher, and WSL only forwards a Win32 variable when WSLENV names it — so scripts saw every usage_* value unset. Both shell and exec now append the parsed argument names to WSLENV (bare, no /p or /l flags), preserving any entries the user had already configured.
- Windows: run= scripts use sh when available (#765 by @JamBalaya56562). complete run= already used sh -c everywhere, but mount run= used cmd /c on Windows, so the same POSIX one-liner behaved differently depending on which KDL node it lived in — and shebang scripts silently exited 0 with empty output. Both call sites now share one implementation: sh -c first, falling back to cmd /c only if sh is not found. Non-UTF-8 output from either shell is now reported as an error instead of panicking.
- Bash/fish completion guard ignores shell functions (#760 by @JamBalaya56562). The generated completion opens with a guard that bails out when the usage CLI is not installed, but type -p returns exit 0 for a shell function, so any environment defining a usage function (e.g. oh-my-bash) passed the guard and then failed further down with an unrelated error. Switched to type -P in both bash guards and the fish equivalent; zsh's type -p already forces a $PATH search and is unchanged.

Breaking Changes
- double_dash="required" positional args now reject values before -- (#762). Specs where such an arg previously happened to work without a separator will now error. In examples/mise.usage.kdl, post--- values also move from the preceding greedy variadic to the arg that declared the separator (