[jrusso1020]

What

Third of four stacked PRs (base: #6617). Fixes the two P1 findings about help and nags:

• hyperframes help printed Unknown command help with raw ANSI codes, no suggestion, and could be followed by update/skills nags. help [cmd...] is now an alias for [cmd...] --help.
• An unknown command, at the root or inside a group like cloud, prints Unknown command: rendr, Did you mean 'hyperframes render'? and that group's usage, all on stderr, and exits 2. An unknown flag suggests the flag it most likely means (Did you mean --output?). Usage printed for a usage error now goes to stderr, not stdout.
• No update, skills or app-history notice is appended to a usage error.
• The skills notice ("N HyperFrames skills out of date or missing") printed on every run, even under --json and without a TTY. It now shows at most once a day per project, and in an unattended run only when a core skill is missing.
• citty's own colors are stripped from --help whenever this CLI's colors are off (they leaked into piped output inside an agent unless CI was set).

Why

An agent that types hyperframes help or a near miss should get the answer, or the right command name, not a colored error. A notice an agent sees on every call is noise it has to filter out of every result.

Related work

Stack: #6616 → #6617 → this PR → JSON envelope.

How

• cli.ts rewrites help ... to ... --help before anything reads argv, so help is reserved and behaves exactly like --help.
• utils/didYouMean.ts: closestMatch() (prefix match first, then edit distance with a small threshold). Used for commands and for long flags.
• commandUsageResolution.ts now also returns the command path and the first word that is not a subcommand of a group, which is what the suggestion and the group usage need.
• help.ts showUsage takes the print function, so the same renderer writes help to stdout and usage-error output to stderr.
• finalizeCli skips the notices when the result is a usage error.
• skillsUpdateCheck.ts: one small JSON file, skills-notice.json in the CLI config folder (.hyperframes in the home folder), maps project directory to the last time the notice was shown; entries older than a day are dropped on write. Unattended, outdated-only skills are not mentioned.

Behavior change for a person at a terminal: help works, and the skills notice shows once a day per project instead of on every run.

Test plan

• Unit tests added/updated: didYouMean.test.ts, commandUsageResolution.test.ts, skillsUpdateCheck.test.ts (once a day per project; unattended outdated-only is silent; missing still shows), reject-unknown-flags.test.ts
• Contract test cases: help, help render, help cloud render; unknown commands at the root, in a group and via help; the --out suggestion; help without CI inside an agent has no ANSI
• CLI unit suite passes locally; typecheck, oxlint, oxfmt --check, fallow audit, comment ratchet pass
• Manual testing performed (below)
• Documentation updated: help, suggestions and the skills notice in docs/packages/cli.mdx
• Comments follow CONTRIBUTING.md "Comments"

Manual runs of the built CLI, CLAUDECODE=1, stdin from /dev/null:

$ hyperframes help </dev/null
# before: exit 1, stdout empty, stderr "Unknown command \e[36mhelp\e[39m"
# after:  exit 0, root help on stdout, stderr empty, no escape codes

$ hyperframes rendr </dev/null
# before: exit 1, stderr "Unknown command \e[36mrendr\e[39m"
# after:  exit 2, stdout empty, stderr:
Unknown command: rendr
Did you mean 'hyperframes render'?

(root usage follows on stderr)

$ hyperframes render --out x.mp4 </dev/null
# after: exit 2, stdout empty, stderr:
Unknown flag: --out
Did you mean --output? Run 'hyperframes render --help' to see its flags.

🤖 Generated with Claude Code

[heygengenesis]

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

This approval covers this diff at aeb5991 only. As a stacked PR it gets no CI run, so I ran the agent-mode suite and the touched unit tests locally at the top of the stack. I also checked by hand: help rendr and cloud rendr exit 2 with the suggestion and usage on stderr. Full CI runs once this is retargeted to main. The blocker on #6616/#6617 (isUnattended()) also affects this PR's skills-notice gating, but the fix belongs there.

— Genesis

[heygengenesis]

Verdict: APPROVE — 1 resolved, 0 open, 0 new · aeb5991 → b741bd5

— Genesis

The base branch was changed.

[mintlify]

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

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 28, 2026, 8:57 AM

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

[github-actions]

Edit accuracy: accurate 271 (base branch 271), smooth 145 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 (0)

Unstable (1)

• seqplainkeys-none-px-r0-nested-z100: tracking 0.07, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.07, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.07, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true

[heygengenesis]

Verdict: APPROVE — 0 resolved, 0 open, 0 new · b741bd5 → 75e80e4. Rebase only: the patch matches b741bd5 apart from a one-line hunk offset in cli.ts (main added an import). CI on this head passed every required job; the run shows cancelled only because edit-accuracy shard 1/5 was cancelled, and its retry and the gate passed.

— Genesis