CLI Tool UX Audit

# Goal: CLI Tool UX Audit

You are working inside this repo. Mission: judge this command-line tool the way its users meet it — a terminal, no docs open, one goal in mind — and find where the interface teaches and where it bites. The evidence is a transcript: real invocations, real output, annotated.

Read-only pass. Build and run the CLI freely — help flags, wrong flags, bad input, dry-runs — but execute nothing destructive. Your only write is the report file.

## Phase 1 — Be the stranger
- Build or install the tool as the README says, then run the first ten commands a newcomer would try: bare invocation, `--help`, `help <sub>`, a plausible task, a typo'd flag, a missing argument. Capture every response verbatim.
- Check each failure's exit code (`echo $?`) and which stream it wrote to.
- Map the command tree: subcommands, global vs local flags, where the depth lives.

## Phase 2 — Audit through 7 lenses
Every finding quotes actual output or cites the parser code (file:line).
1. **Help that answers** — does `--help` at every level lead with usage and the common case, or dump an alphabetized flag wall; is there an example per subcommand
2. **Flag grammar** — naming consistency across subcommands (`--output` here, `-o` there, `--out` elsewhere), short/long pairs, negation style; cite the contradictions
3. **Errors that coach** — a bad flag, bad value, or missing arg: does the message name what was wrong and the exact command to try; is there a did-you-mean
4. **Exit-code contract** — distinct codes for distinct failures, documented, stable enough to script against; test them, don't trust the docs
5. **Machine mode** — `--json`/`--quiet` for scripts: complete, valid, stable output with diagnostics kept on stderr; or prose a pipeline must scrape
6. **Stream discipline** — results on stdout, chatter on stderr; does `tool | jq` work, or does a progress bar poison the pipe
7. **Destructive safety** — the dangerous verbs: confirmation or `--force` semantics, a `--dry-run`, plurals that could eat more than intended

## Phase 3 — Curate
- Rank by who gets hurt: a scripting user silently misled by exit code 0 outranks an ugly help screen.
- Group fixes that share one root (a shared flag parser, one error formatter) — one fix, many symptoms.
- Keep the transcript honest: paste output as it appeared, annotate what a newcomer feels at each line.

## Phase 4 — Report
Create `CLI.md` at repo root:
1. **The transcript** — the newcomer's first session, verbatim, annotated where it teaches or bites
2. **Exit-code table** — scenario · code observed · stream used · scriptable verdict
3. **Findings** — each: lens · command · quoted output · the fix · effort S/M/L
4. **The first fix** — the one change that improves the most sessions, argued in three sentences

Start the report with today's date. If `CLI.md` already exists from a previous run, read it first and lead with what changed since.

## Rules
- Quote real output; a UX claim about a CLI is checkable by running it
- Judge for both audiences at once — the human at the prompt and the script that calls it at 3am
- No command-line interface in this repo? Say so in a one-paragraph null report and stop — a null result is a valid finding.
- If a `reports/` directory exists at the repo root, write the report there instead of the root.
- Before asking, present the top findings as a ranked list in plain words
- Report only — end by asking which fixes to make first