## Summary
- The `coverage` CI job fails with `E0639: cannot create non-exhaustive
struct using struct expression` in `lib/benches/parse.rs`
- Benchmarks are compiled as separate crates, so `#[non_exhaustive]` on
`Spec` prevents struct literal construction
- Fix: use `Spec::default()` with field assignment instead of struct
literal syntax

## Test plan
- [x] `cargo build --benches` compiles successfully
- [ ] Coverage CI job passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: changes are confined to benchmark setup code and only adjust
`Spec` construction to compile with `#[non_exhaustive]` types.
> 
> **Overview**
> Fixes `lib/benches/parse.rs` to stop using `Spec {
..Default::default() }` struct literals (which fail for
`#[non_exhaustive]` types when benches compile as a separate crate).
Bench specs are now created with `Spec::default()` followed by explicit
field assignment for `name`, `bin`, and `cmd`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
c3424dc. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

…4d46 (#550)

This PR contains the following updates:

| Package | Type | Update | Change |
|---|---|---|---|
|
[apple-actions/import-codesign-certs](https://redirect.github.com/apple-actions/import-codesign-certs)
([changelog](https://redirect.github.com/apple-actions/import-codesign-certs/compare/b610f78488812c1e56b20e6df63ec42d833f2d14..fe74d46e82474f87e1ba79832ad28a4013d0e33a))
| action | digest | `b610f78` → `fe74d46` |

---

### Configuration

📅 **Schedule**: Branch creation - "before 4am on friday" in timezone
America/Chicago, Automerge - At any time (no schedule defined).

🚦 **Automerge**: Enabled.

♻ **Rebasing**: Whenever PR is behind base branch, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update
again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR was generated by [Mend Renovate](https://mend.io/renovate/).
View the [repository job
log](https://developer.mend.io/github/jdx/usage).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My42Ni40IiwidXBkYXRlZEluVmVyIjoiNDMuNjYuNCIsInRhcmdldEJyYW5jaCI6Im1haW4iLCJsYWJlbHMiOltdfQ==-->

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

This PR contains the following updates:

| Package | Type | Update | Change |
|---|---|---|---|
|
[codecov/codecov-action](https://redirect.github.com/codecov/codecov-action)
([changelog](https://redirect.github.com/codecov/codecov-action/compare/671740ac38dd9b0130fbe1cec585b89eea48d3de..1af58845a975a7985b0beb0cbe6fbbb71a41dbad))
| action | digest | `671740a` → `1af5884` |

---

### Configuration

📅 **Schedule**: Branch creation - "before 4am on friday" in timezone
America/Chicago, Automerge - At any time (no schedule defined).

🚦 **Automerge**: Enabled.

♻ **Rebasing**: Whenever PR is behind base branch, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update
again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR was generated by [Mend Renovate](https://mend.io/renovate/).
View the [repository job
log](https://developer.mend.io/github/jdx/usage).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My42Ni40IiwidXBkYXRlZEluVmVyIjoiNDMuNjYuNCIsInRhcmdldEJyYW5jaCI6Im1haW4iLCJsYWJlbHMiOltdfQ==-->

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

This PR contains the following updates:

| Update | Change |
|---|---|
| lockFileMaintenance | All locks refreshed |

🔧 This Pull Request updates lock files to use the latest dependency
versions.

---

### Configuration

📅 **Schedule**: Branch creation - "before 4am on monday" in timezone
America/Chicago, Automerge - At any time (no schedule defined).

🚦 **Automerge**: Enabled.

♻ **Rebasing**: Whenever PR is behind base branch, or you tick the
rebase/retry checkbox.

👻 **Immortal**: This PR will be recreated if closed unmerged. Get
[config
help](https://redirect.github.com/renovatebot/renovate/discussions) if
that's undesired.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR was generated by [Mend Renovate](https://mend.io/renovate/).
View the [repository job
log](https://developer.mend.io/github/jdx/usage).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My42Ni40IiwidXBkYXRlZEluVmVyIjoiNDMuNjYuNCIsInRhcmdldEJyYW5jaCI6Im1haW4iLCJsYWJlbHMiOltdfQ==-->

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

## Summary
- Renders `before_help`, `after_help`, `before_help_long`,
`after_help_long` in CLI `-h`/`--help` output
- Shows `name` + `version` header at the top of help output
- Shows `author` and `license` in the long help (`--help`) footer
- Shows `[deprecated: reason]` marker on subcommands
- Renders `examples` with headers, help text, and `$`-prefixed commands
- Short help (`-h`) uses base variants; long help (`--help`) prefers
`_long` variants with fallback

Closes #549

## Test plan
- [x] Tests for `before_help`/`after_help` rendering (short and long)
- [x] Tests for `before_help_long`/`after_help_long` fallback behavior
- [x] Tests for examples rendering (short and long, with headers and
help text)
- [x] Tests for `version` header display
- [x] Tests for `author`/`license` in long help footer
- [x] Tests for `deprecated` marker on subcommands
- [x] All existing tests pass (`cargo test --all --all-features`)
- [x] Clippy clean

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: changes are limited to CLI `--help`/`-h` rendering templates
and snapshot tests, affecting formatting/output only.
> 
> **Overview**
> **Help output is expanded** to render `before_help`/`after_help` (with
`_long` variants preferred for `--help`), plus an `Examples` section
sourced from command- or spec-level examples.
> 
> The templates now also show name+version headers, annotate deprecated
subcommands with `[deprecated: ...]`, and include author/license lines
in long help. Snapshot tests were added/updated to cover the new
rendering behaviors.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
b2967cc. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

## Summary
- Adds support for `--file -` to read specs from stdin on all generate
subcommands, lint, and complete-word
- Enables piping specs from other tools (e.g., `jbang usage | usage
generate markdown --file -`)
- Updates `--file` help text to document stdin support
- Not supported for exec/shell subcommands which pass stdin through to
the child process

Closes #546

## Test plan
- [x] `echo 'name "test" flag "-v --verbose" help="verbose"' | usage
generate json --file -` produces valid JSON output
- [ ] Verify `--file /path/to/file` still works as before
- [ ] Verify `usage generate markdown --file - --out-file out.md` works
with piped input

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low-risk CLI enhancement that only affects how usage specs are read
when `--file` is set to `-`; primary risk is unintended behavior changes
for edge-case file paths or stdin handling.
> 
> **Overview**
> Adds support for piping a usage spec via stdin by treating `--file -`
as “read spec from stdin” across `complete-word`, `generate
completion/manpage/markdown`, and `lint` (via new shared helpers in
`cli/src/cli/generate/mod.rs`).
> 
> Updates generated metadata/docs (`usage.usage.kdl`, manpage, reference
JSON/markdown, Fig spec) to document the stdin behavior, and adjusts
generated output labeling to use `stdin` instead of `-` where a source
filename is surfaced (e.g., completion `source_file` and Fig
`@generated` header).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
98d3919. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

…ash (#556)

## Summary
- Use `_describe` with `-S ''` instead of `_arguments` in zsh completion
template to prevent unwanted trailing spaces after completions (e.g.,
`node@` no longer gets a space appended)
- Append trailing `/` to directory entries in `complete_path` so
directory completions show `/opt/homebrew/` instead of `/opt/homebrew`
- Change zsh `complete-word` output format from `'val'\:'desc'` to
`val:desc` to match `_describe` expectations

Closes #67

## Test plan
- [x] Added `test_zsh_complete_word_output_format` — verifies new
`name:description` output format
- [x] Added `test_complete_path_adds_trailing_slash_for_directories` —
verifies dirs get `/` suffix, files don't
- [x] Updated zsh completion snapshots
- [x] All existing tests pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes zsh completion generation and `complete-word` output
formatting, which can break shell completion behavior if the new format
is not accepted across zsh setups. Also tweaks path completion output
(adds `/` for directories), affecting user-visible CLI suggestions.
> 
> **Overview**
> Fixes zsh completions to avoid unwanted trailing spaces by switching
the generated zsh completion scripts from `_arguments` command
substitution to collecting candidates and feeding them into `_describe`
with `-S ''`.
> 
> Updates `usage complete-word --shell zsh` to emit `value:description`
(with `:` escaped) to match `_describe` expectations, and enhances path
completion to append `/` to directory candidates. Adds integration tests
covering the new zsh output format and directory-slash behavior, and
updates zsh completion snapshots accordingly.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
fc5ec7a. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

### 🚀 Features

- **(cli)** render all doc-related fields in --help output by
[@jdx](https://github.com/jdx) in
[#554](#554)
- **(cli)** support reading spec from stdin via --file - by
[@jdx](https://github.com/jdx) in
[#555](#555)

### 🐛 Bug Fixes

- **(zsh)** remove trailing space from completions and add directory
slash by [@jdx](https://github.com/jdx) in
[#556](#556)
- use field assignment for non-exhaustive Spec in benchmarks by
[@jdx](https://github.com/jdx) in
[#552](#552)

### 📦️ Dependency Updates

- update apple-actions/import-codesign-certs digest to fe74d46 by
[@renovate[bot]](https://github.com/renovate[bot]) in
[#550](#550)
- update codecov/codecov-action digest to 1af5884 by
[@renovate[bot]](https://github.com/renovate[bot]) in
[#551](#551)
- lock file maintenance by
[@renovate[bot]](https://github.com/renovate[bot]) in
[#547](#547)

…559)

## Summary

- Escape `(`, `)`, `[`, `]` in zsh completion output to prevent
`_describe` from interpreting them as glob qualifiers/character classes
- Extract a `zsh_escape()` helper that handles all zsh-special
characters (colons, parens, brackets)
- Add test fixture and integration test verifying the escaping

Fixes #558

## Test plan

- [x] New test `complete_word_zsh_escapes_parens_and_brackets` verifies
escaped output
- [x] Verified test fails without the fix (parentheses/brackets passed
through unescaped)
- [x] Full test suite passes
- [x] Clippy clean

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: only adjusts zsh completion output formatting by adding
additional escaping, with coverage via a new integration test.
> 
> **Overview**
> Fixes zsh completion output for `_describe` by escaping additional
special characters in `name:description` entries. The previous inline
colon escaping is replaced with a shared `zsh_escape()` helper that also
escapes `(`, `)`, `[` and `]` to prevent glob/character-class
interpretation.
> 
> Adds an integration test plus a new example spec to verify zsh output
is correctly escaped for descriptions containing parentheses/brackets
(and colons).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
f165847. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

## Summary
- add `env` support to `choices` so specs can source allowed values from
an environment variable
- honor `Parser::with_env(...)` without falling back to the process
environment when a custom env map is provided
- reject explicit values when `choices env=...` resolves to no values
instead of silently disabling validation
- preserve `choices env=...` when `SpecArgBuilder::choices()` is called
after `choices_env(...)`
- resolve env-backed choices for interactive shell completion at
completion time
- preserve `choices env=...` in help/docs instead of snapshotting live
env-backed values into generated output
- keep Fig suggestions literal-only so `usage generate fig` does not
bake generation-time environment values into a static file

## Example
```kdl
arg "<env>" {
  choices env="DEPLOY_ENVS"
}
```

With `DEPLOY_ENVS="foo,bar baz"`, valid values become `foo`, `bar`, and
`baz`.

## Implementation notes
- `choices` now accepts an optional `env` property and preserves it when
serializing back to KDL
- env-backed values are split on commas and/or whitespace, with empty
entries ignored
- env-backed values are appended after literal choices and deduplicated
against existing entries
- parsing uses the caller-provided env map when `Parser::with_env(...)`
is used; it only consults the process environment when no custom env map
is provided
- env-backed choices that resolve to no values now fail validation for
explicit CLI input with a targeted error message instead of accepting
any value
- `SpecArgBuilder::choices()` now preserves any previously configured
`choices_env(...)`
- help/docs render literal choices as before and also surface the
controlling env var for env-backed choices

## Tests
- unit tests for env choice splitting and deduplication
- parser tests covering arg/flag validation with `Parser::with_env(...)`
- parser test covering the empty env-backed choice set case
- builder test covering `.choices_env(...).choices(...)` ordering
- completion test covering env-backed choices
- dump test covering KDL round-tripping

### 🚀 Features

- Support env-backed choices with `choices env=...` by
[@mustafa0x](https://github.com/mustafa0x) in
[#548](#548)

### 🐛 Bug Fixes

- **(zsh)** escape parentheses and brackets in completion descriptions
by [@jdx](https://github.com/jdx) in
[#559](#559)

### New Contributors

- @mustafa0x made their first contribution in
[#548](#548)