bin/vh <command> -h prints its usage instead of running the command

[ZLHad]

Why

bin/vh sheet -h failed with basename: illegal option -- h. Review found the same class of bug across the CLI: -h and --help reached the command as an ordinary argument.

command	before (main)	after
setup -h	ran the whole install (npm install, references/fetch.sh, the swatch renderer)	header usage, exit 0
sync-agents -h	rewrote AGENTS.md	header usage, exit 0
doctor -h, types -h	ran as usual	header usage, exit 0
sheet -h	basename error, exit 1	header usage, exit 0
check -h	ffprobe's own help	header usage, exit 0
gif -h	ffmpeg Unrecognized option 'h.gif', exit 8	header usage, exit 0
hf-init -h	no such project: -h, exit 1	header usage, exit 0
mux -h	bash line 573: 2: usage: …, exit 1	header usage, exit 0
beats -h	libsndfile error opening -h, exit 1	header usage, exit 0
qa -h / qa --help / qa mix -h	JSONDecodeError traceback / the docstring with exit 1 / qa mix: no such folder: -h, exit 1	the docstring (78 lines), exit 0
style -h	checked the swatch renderer's npm install, then printed render.sh's help	header usage (now with a pointer to render.sh -h), exit 0
style check -h	reached determinism.sh as a preset name	its own usage line, exit 0
new, effort, install-skill, music with -h	a usage, but exit 1 (music --help: "unknown option")	header usage, exit 0
tts -h	built the mlx-audio environment, then argparse's help	header usage + tts.py's option list via the plain python3, exit 0, nothing installed
sfx, captions, readcheck, review, storyboard, rhythm, cover-preview, voices, mix, recipes	their own help	unchanged

Changes

• bin/vh: before dispatch, bin/vh <command> -h|--help prints that command's lines from the help header at the top of bin/vh (cmd_usage, continuation lines included) and exits 0. The header already lists every command and its arguments, so this usage cannot drift from bin/vh help. Commands with a fuller help of their own (the last row, plus qa) keep it. An unknown command with -h still exits 1; without -h, every command behaves as before. cmd_usage reads the name through ENVIRON, since awk -v expands backslashes.
• tools/audio/qa.py: -h or --help anywhere in the arguments prints the docstring and exits 0.
• tools/ci.sh: the smoke test reads the list of dispatched commands from bin/vh, drops the own-help list (and fails if that list names a command that is not dispatched), then runs -h and --help for the remaining 16 and for style check. It expects exit 0 and output starting with usage: bin/vh <command> . It runs on a copy of bin/vh in a temp folder whose only content is a link to tools/, with uv and npm stubbed out on PATH, so nothing is downloaded and if the check ever regressed, setup would stop at its first cd and sync-agents would write the temp folder's AGENTS.md. I checked this with main's bin/vh: the real AGENTS.md was unchanged.
• CHANGELOG.md: an entry.

Four commits. The first fixed six commands one at a time. The second moved the check into the dispatcher after the review found the rows above. The third keeps the fuller help of sfx, qa and tts and makes the CI test safe and complete, after the second review. The fourth stubs uv and npm in that test and loosens its command-count floor, after the third review (approve).

Checked

• tools/ci.sh and VH_BASH=/bin/bash tools/ci.sh --committed (bash 3.2, clean checkout of HEAD): all checks passed.
• By hand, each row of the table; bin/vh nosuch -h and bin/vh 'ne\w' -h exit 1; bin/vh -h and bin/vh help -h print the full help.
• Second review: cmd_usage gives identical output on macOS awk, mawk and BusyBox awk; 51 invocations without -h match main under both bashes.

Not changed

• I first suspected that styles/product-keynote/STYLE.md cites lemo-opuscar under the wrong licence (CC BY 4.0, while the current LICENSE is MIT). It is correct as written: the preset was adapted on 2026-09-29 from the snapshot before the MIT switch, and references/community-skills.md says such adaptations keep their CC BY attribution, as 22 other presets do.
• Pre-existing, left alone: hf-init passes its resolution to hyperframes init unchecked, so a typo reports "init failed (offline?)"; sheet on a missing video creates out/check/ next to it and shows a Python traceback; bin/vh tts <project> -h takes -h as the provider.