[miguel-heygen]

What

An unknown flag now answers with the command's real long flags, plus a "Did you mean" when one is close or means the same. --search on catalog points to --query.

$ hyperframes snapshot . --at 1 --width 360 --json
{"ok":false,"error":{"code":"unknown_flag","message":"Unknown flag: --width","hint":"Its flags: --output, --frames, --at, --range, --composition, --timeout, --angle, --end, --keep, --zoom, --zoom-scale, --against, --review, --json, --describe, --proxy, --browser-gpu. Run 'hyperframes snapshot --help' for what each does."}}

Why

The hint used to say only "Run 'hyperframes snapshot --help' to see its flags." Agents usually guess a second flag instead of reading help (snapshot --width, then --scale; catalog --search instead of --query), so each wrong guess cost another failed round. Listing the flags in the error lets the next call be right.

Related work

None.

How

• packages/cli/src/utils/reject-unknown-flags.ts, the one place every command's unknown-flag error is built: the hint lists the long flags from the command's own args (positionals left out), so the list cannot drift from the command.
• FLAG_SYNONYMS gains search -> query.
• snapshot still has no size option; this change only makes the error say what it does take.
• docs/packages/cli.mdx: the JSON error example is the real output for catalog --search.

Test plan

• New tests in reject-unknown-flags.test.ts: lists the command's own flags, not its positionals, when nothing close matches and points --search at the query flag. The two tests that pinned the old hint now pin the new one.
• fails without the fix: with the reject-unknown-flags.ts change reverted, 4 fail (the 2 new, the 2 updated); with it, 35 passed, 3 runs in a row.
• Real CLI, before and after: snapshot <project> --at 1 --width 360 --json, catalog --search light-leak --json, render <project> --out x.mp4 --json; before, each hint said only to run --help; after, each lists the flags, and --search and --out get "Did you mean --query?" and "Did you mean --output?".
• oxfmt --check, oxlint on both files, tsc --noEmit for packages/cli: clean.
• Documentation updated: the JSON error example in docs/packages/cli.mdx.
• Comments follow CONTRIBUTING.md "Comments".

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Nov 14, 2026, 2:29 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Edit accuracy: accurate 267 (base branch 267), smooth 112 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (8)

• seqplainkeys-none-center-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-center-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-center-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-pct-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-pct-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-px-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-px-r30-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-px-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 1 nit

• nit: the list includes every declared arg, so init now advertises its rename shims (--template, --video-legacy, --agent) to agents. That matches --help today. Skipping args whose description starts with [renamed]/Deprecated would keep agents off them.

Scope

Read all 3 files. Locally 35/35 pass at head, and reverting reject-unknown-flags.ts fails exactly the 4 named tests, so the fails-without-the-fix line holds. The old hint text has no other pins in the repo. The docs example matches catalog's declared args in order. CI on this head is all green.