Core CLI help metadata is stale and incomplete (#835)

[philcunliffe]

What drifted

Dispatch renders summary / usage / help straight off the command
registration (LLP 0009 #central-help-interception), so the registration is the
entire published interface of a command, and nothing was checking that it still
matched the handler. Four registrations had stopped matching, and three working
surfaces had no place to be listed.

surface	claimed	actual
hyp init --help	walkthrough asks for a retention window	LLP 0137 removed that question; the pathway picks 90 (team) / 120 (local)
hyp remote login --help	<name> required, no --org/--host/--browser/--no-browser	bare login resolves the default target (LLP 0062 #bare-remote); all four flags are accepted
hyp daemon restart --help	stops the daemon, operator relaunches	restarts the installed launchd/systemd service; the relaunch line is the no-service fallback
hyp skills install --help	[--client <name>]	parser defaults --client to all
hyp daemon install	--platform undocumented	accepted by the parser, used only to render another platform's unit
top-level help	no rows	--version, -V, and the unattach alias all work
hyp help query	-	silently rendered the top-level table

What changed

• The four stale registrations now describe their handlers, with @refs to the
  LLPs that constrain them (0137, 0062).
• daemon install --platform darwin|linux is public and documented, and is now
  refused outside --dry-run. A real install writes into this host's service
  directory and then calls this host's service manager, so a cross-platform
  install can only produce a broken one. Same shape as the existing
  --json requires --dry-run rule; no in-repo caller used it any other way.
• hyp help <command...> is rewritten to hyp <command...> --help and routed
  through ordinary dispatch. Routing rather than re-answering is what makes it
  reach plugin-contributed commands, which only exist after boot. Bare
  hyp help still renders the top-level table.
• Top-level help gains Global options: and Aliases: sections after the
  command table. Alias rows are read off the registry, so a new alias lists
  itself. The one-row-per-top-level-token rule for commands is unchanged.

Regression test

test/core/cli/help-metadata.test.js (new, 11 assertions). It asserts semantic
claims, not flag presence: for example "init help does not say the walkthrough
asks for a retention window" was the actual defect, while "init help mentions
--retention-days" was already true inside a false sentence.

Before this change 10 of the 11 fail on master; all 11 pass after.
npm test locally shows 4207 pass / 22 fail, the same 22 failures a clean
origin/master run produces in this environment (parquet pushdown and report
render, unrelated). npm run typecheck is clean, and
npm run smoke -- daemon_install_render and -- command_dispatch are green.

Design record

LLP 0265 (Decision, Systems: CLI) records what a registration owes its handler,
the --platform call, the help <command> routing, and the global-options /
aliases sections. LLP 0009 gains the Extended-by: forward-ref; nothing it
settled is edited.

Fixes #835

[philcunliffe]

Neutral review round - head 649f02b3

Verdict: approve with fixes applied. The four stale registrations really were stale, the
new claims match their handlers, LLP 0265 records the decision honestly, and LLP 0009 gained
nothing but a Extended-by: forward-ref (1 line added, 0 removed - nothing it settled was
edited). Two user-visible defects in the new hyp help <command> routing, and three smaller
cleanups, are fixed and pushed (1c725aec, a65dabcc). One finding is left open on purpose.

Verified locally in a clean worktree (npm install per worktree, no borrowed node_modules).
At 649f02b3: npm test 4269 pass / 0 fail. At a65dabcc: 4271 pass / 0 fail, npm run typecheck reports nothing in any changed file, and hyp smoke command_dispatch,
daemon_install_render, package_bin_boot, cli_bundled_plugins_activated are all green.

---

Findings

1. [high, FIXED] hyp help <command> <arg> ran the command instead of rendering help

The rewrite at src/core/cli/dispatch.js:242 appends --help to the end of argv, but the
central interception only fired on a leading help flag (isHelpFlag(matched.rest[0]),
src/core/cli/dispatch.js:499). Any token the user wrote after the command name pushes the
injected flag past that test, so the request fell through to the handler. Reproduced at
649f02b3:

$ hyp help attach claude
error: unknown argument: --help          # exit 2
$ hyp help query sql "select 1"
hyp query sql: unknown flag --help       # exit 2
$ hyp help purge /tmp/x
error: usage: hyp purge <path> | ...     # exit 2

Core parsers happen to reject the stray flag, so today this only produces a wrong, confusing
error where the top-level table used to print. What makes it high rather than medium is the
failure mode one lenient parser away: nothing in the design stops a command that ignores
unknown flags from executing on a help request, and the third example above is hyp purge,
which deletes cached rows. A help verb must not be able to reach a destructive handler.

Fixed by carrying the rewrite as a helpVerb flag and letting it satisfy the interception, so
the spelled-out form renders the matched command help however many positionals follow it. The
rewrite itself is unchanged, so the boot profile, registry.match, and the group / unknown
branches all still see the real command argv. LLP 0265 #help-verb says the form is
"rewritten ... and routed through ordinary dispatch"; that is now true of every input rather
than only of inputs with no trailing positional, so the Accepted text needs no change. Two
tests added: a spy command asserting run() is never called for hyp help spy target, and
hyp help attach claude rendering attach help with an empty stderr.

Credit: caught by the second reviewer pass, not the first.

2. [medium, FIXED] The help rewrite leaked into the unknown-command diagnostic

src/core/cli/dispatch.js:242 rewrites hyp help <command...> to [...argv.slice(1), '--help'],
but the miss path at src/core/cli/dispatch.js:396 echoed the rewritten argv:

$ hyp help bogus
hyp: unknown command 'bogus --help'
run 'hyp --help' for the list of available commands

The appended --help is ours, not the user's, so the diagnostic named a flag nobody typed -
and did it while telling a user who just mistyped a command name to go read help. This is a
regression introduced by this PR (hyp help bogus previously printed the top-level table).

Fixed by keeping the pre-rewrite argv (typedArgv) for that one message; the rewritten argv
still drives decideBootProfile, registry.match, and the group/inactive-plugin branches,
which all want the real command token. hyp help bogus now says
unknown command 'help bogus'. Regression test added in
test/core/cli/help-metadata.test.js (hyp help <unknown> reports the argv the user typed).

3. [low, FIXED] Global options: restated the flag spellings instead of reading them

src/core/cli/dispatch.js:807-809 hardcoded '--help, -h' / '--version, -V' next to the
HELP_FLAGS / VERSION_FLAGS sets dispatch actually matches on. That is the exact drift
vector LLP 0265 was minted to close, and it sits three lines below an alias section whose
whole point is that "a new alias lists itself". Now derived from the two sets via a small
flagList() helper (dropping the command-shaped bare help token). Rendered output is
byte-identical - the existing assertions in help-metadata.test.js cover it.

4. [low, FIXED] README does not document the newly-public --platform

LLP 0265 #platform-is-a-render-override says the flag "is documented", but the only place it
became documented is --help. README.md:434 is where daemon install --dry-run --json is
explained; it now names --platform darwin|linux and its --dry-run requirement too.

5. [low, FIXED] runSkillsInstall JSDoc still carried the stale usage

src/core/commands/clients.js:2208 still said hyp skills install [--client <name>] - the
same claim the PR corrected on the registration and that the issue cites as evidence. Updated
to [--client <name>|all] with the default called out.

6. [low, OPEN - design call, deliberately not fixed] --platform is refused even when it names this host

The refusal is p.platform !== undefined && !p['dry-run']
(src/core/commands/daemon.js:376), so hyp daemon install --platform linux is now rejected
on Linux, where it was a correct no-op-equivalent. LLP 0265's rationale only justifies
refusing a mismatched platform ("the install writes into this host's service directory and
then calls this host's service manager, so a cross-platform install can only produce a broken
one"); a rule of p.platform !== process.platform would be exactly as safe and would break
nothing. The blanket form is defensible (it mirrors --json requires --dry-run, and naming
your own platform outside a dry run buys you nothing), and it is now settled in an Accepted
LLP, so I have not touched it. Flagging it so the decision is made knowingly rather than by
omission: if the blanket form is intended, LLP 0265 #platform-is-a-render-override would be
more honest saying "any --platform, matching or not" rather than resting the whole argument
on cross-platform breakage.

7. [informational] runDaemonInstall still prints its own usage string

src/core/commands/daemon.js:178 keeps a hand-maintained usage: line, reachable when
--help is not the first token after the command (hyp daemon install --dry-run --help).
That is a pre-existing tension with LLP 0009 §Central help interception ("a command body never
prints its own usage"); the PR correctly kept the two strings in sync rather than letting them
diverge, but it is a second source of truth for the same claim. Out of scope here - it is a
cross-command cleanup (parseCommandArgv's help branch), not a #835 fix.

8. [informational] Branch is 7 commits behind origin/master

merge-base is a14246d9, origin/master is ec3361bb. No conflict at the file level, and
LLP number 0265 is free on master (master reaches 0263) and unclaimed by any other open PR.
Worth a rebase before merge given sibling PRs #848 (repo-wide CLI consistency gate) and #850
(reject unknown arguments on every visible core command) come from the same audit and touch
the same surface.

---

The --platform narrowing

I checked the author's claim independently rather than taking it. It holds. Every in-repo
caller of daemon install --platform passes --dry-run:

• hypaware-core/smoke/flows/daemon_install_render.js:216-225 - ['daemon','install','--dry-run','--json','--bin',…,'--platform','darwin']
• test/core/daemon-install-durable-bin.test.js:144 - ['--dry-run','--bin',NPX_BIN,'--platform','darwin']

Those are the only two. --platform appears nowhere in docs/ACCEPTANCE.md, nowhere in the
release checklist or smoke battery in CLAUDE.md, and nowhere in README.md. Both callers
still pass after the change (daemon_install_render smoke and the durable-bin test are green).

The technical argument also holds: installServiceDaemon in src/core/daemon/install.js:200
selects the plan by options.platform ?? process.platform, then writes into this host's
service directory and hands off to this host's service manager, so a genuinely cross-platform
install produces a systemd unit on macOS (or a plist on Linux) that nothing will ever load.

Does it belong in this PR? Yes, narrowly. Issue #835 does not merely mention the flag in
passing - it makes the call an explicit acceptance criterion ("Decide whether
daemon install --platform is public; document it or remove it from public argv parsing") and
anticipates a behaviour change ("if desired behavior changes, mint the required new LLP").
The PR takes the middle option, keeps the useful half, and records it under its own anchor in
LLP 0265 with a Consequences paragraph that states the exit-code change plainly rather than
burying it. That is the process the issue asked for, so splitting it out would separate the
decision from the document that records it for no gain.

Two caveats for whoever merges. First, the PR title and the issue title both read as
documentation work, and this is a CLI behaviour change: it deserves a line in the release
notes, not just an LLP. Second, see finding 6 - the implemented rule is broader than the
rationale that justifies it, and the over-broad half (--platform <this host> outside
--dry-run) is the only case where a real external caller could be broken.

docs/CLI_COMMAND_AUDIT.md

Confirmed absent from master and from this branch, and confirmed that nothing in the PR
depends on it: grep -rn CLI_COMMAND_AUDIT over the worktree returns no hit outside the
issue body, and neither LLP 0265 nor any code comment cites it. Every claim the PR corrects is
independently checkable against the handler, and I re-checked all four:
init retention (LLP 0137 #pathway-defaults, 90 team / 120 local - both numbers in the doc),
remote login optional name and flag set (LLP 0062 D2 #bare-remote; --org/--host/
--token-file/--browser/--no-browser/--no-forward/--no-daemon all parsed in
src/core/cli/remote_commands.js:433-463), daemon restart (src/core/commands/daemon.js:143
restarts the installed service and only falls back to the relaunch hint), and skills install
(parseSkillsArgs defaults client to 'all').

Repo-rule conformance

No em dash (U+2014) in any added line. No semicolons. No @typedef, no inline import()
types. New @refs check out: LLP 0137#pathway-defaults and LLP 0062#bare-remote are real
explicit anchors; LLP 0265#platform-is-a-render-override, #help-verb, #global-options,
#registration-is-the-contract are all defined in the new doc; the LLP 0009 anchors 0265
cites (#layered-help, #central-help-interception,
#top-level-help-lists-plugin-commands-without-booting) are heading slugs that exist. Each
@ref says something the code and filename do not. LLP 0009 was touched only on its
Extended-by: header line, which is the sanctioned mechanical edit.

---

Fixed and pushed: 1c725aec (findings 2-5), a65dabcc (finding 1).
Open: finding 6 (design call on the blanket --platform refusal), findings 7-8
(informational).

[philcunliffe]

Renumbered this PR's LLP from 0265 to 0270 (mechanical, no content change).

While this PR was open, two LLPs merged to master: llp/0264-grep-search-mirrors-the-server.decision.md (#856) and llp/0265-grep-search-implementation.plan.md (#865). That left master and this branch both claiming LLP 0265 for entirely different documents, which the duplicate-numbers job in .github/workflows/llp-check.yml fails on, and which would have corrupted the corpus on merge.

Per CLAUDE.md, "renumbering that does not change meaning (LLP 0156)" is an allowed mechanical edit on an Accepted doc, so the doc that landed second (this one) was moved to the next free number.

0270 was chosen as the next number free across every remote branch, not just master: master tops out at 0265, and 0266 / 0267 / 0268 are held by sibling PRs #850 / #849 / #847, with 0269 held by llp/0269-grep-search-client-plan.

Renamed:

• llp/0265-help-metadata-is-part-of-the-contract.decision.md -> llp/0270-help-metadata-is-part-of-the-contract.decision.md (100% similarity rename)

References retargeted:

• llp/0270-help-metadata-is-part-of-the-contract.decision.md - its own # LLP 0265: title heading
• llp/0009-cli-registry.spec.md - the Extended-by: line this PR appended (both the LLP 0265 label and the ./0265-... link target)
• src/core/cli/dispatch.js - 3 @ref LLP 0265# annotations (#help-verb x2, #global-options)
• src/core/cli/core_commands.js - 1 (#platform-is-a-render-override)
• src/core/commands/daemon.js - 1 (#platform-is-a-render-override)
• test/core/cli/help-metadata.test.js - 3 (#registration-is-the-contract, #help-verb, #global-options)

Not one word of the document's context, decisions, or consequences changed - only the four digits and the links that point at them. master's own LLP 0264 and 0265 references (all inside the two grep-search documents) were deliberately left untouched; each hit was checked in context after the merge rather than blanket-rewritten.

origin/master was merged in and resolved cleanly with no conflicts, which also picks up #853, so the earlier repo-scratch-hygiene failure is gone.

Verification in a clean worktree with a fresh npm install:

• duplicate-numbers check run locally: no duplicates.
• HYP_HOME=$(mktemp -d) npm test: 4497 passing, 0 failing, 1 skipped.
• npm run typecheck: clean.
• @ref validation across the tree: 2575 annotations resolved, and all four LLP 0270 anchors (#registration-is-the-contract, #platform-is-a-render-override, #help-verb, #global-options) exist in the renamed document. The 19 pre-existing anchor-slug warnings are byte-identical to the same run against origin/master, so this change introduces no new dangling refs.

[philcunliffe]

Verdict: approve, with one low-severity behaviour finding and two nits. Nothing pushed; the branch stays at 590d4f4.

The change does what it claims. I re-derived every claim the four corrected registrations make against the handlers behind them, and all of them hold.

Verification (worktree at 590d4f4)

• npm test: 4497 pass / 0 fail / 1 skipped (4498 total). Fully green in this environment.
• npm run typecheck: clean.
• npm run smoke -- command_dispatch: ok. npm run smoke -- daemon_install_render: ok.
• Style: no em dashes and no semicolons in the added lines; types stay in JSDoc.
• @ref targets all resolve: LLP 0137#pathway-defaults, LLP 0062#bare-remote (llp/0062:43), LLP 0009#layered-help / #central-help-interception (heading slugs at llp/0009-cli-registry.spec.md:58 and :84), and the four anchors in the new LLP 0270. Number 0270 is free on master (highest there is 0265).
• Real CLI exercised for the rewrite paths: hyp help query, hyp help daemon install, hyp help attach claude, hyp help backfill claude, hyp help report get 5, hyp help graph bogus, hyp help zzz, hyp help, hyp --help. hyp help init takes 0.23s, identical to hyp init --help, so routing through dispatch adds no measurable boot cost.

Claim-by-claim check of the corrected help text: all accurate

• init: LLP 0137 gives 90 (team) / 120 (local), and the code agrees: DEFAULT_RETENTION_DAYS = 90 and LOCAL_INSTALL_RETENTION_DAYS = 120 at src/core/cli/walkthrough.js:63-64, wired at src/core/cli/wizard/index.js:463. No retention question survives in the pick phase (src/core/cli/wizard/pick.js:366).
• remote login: the target name really is optional (src/core/cli/remote_commands.js:457), and --org, --host, --token-file, --browser, --no-browser, --no-forward, --no-daemon are all parsed. The new help's claim that --browser forces the flow past a piped stdin matches the useStatic expression.
• daemon restart: restarts the installed service in place, and only falls back to stop plus a relaunch hint when none is installed (src/core/commands/daemon.js:224-245). The new summary and the qualified fallback in help are both right.
• skills install: the parser default really is all (src/core/commands/clients.js:2328).
• daemon install --platform: enum-constrained to darwin|linux (src/core/commands/daemon.js:445) and now refused outside --dry-run (src/core/commands/daemon.js:457). Every in-repo caller already passes --dry-run (hypaware-core/smoke/flows/daemon_install_render.js:222, test/core/daemon-install-durable-bin.test.js:144), so the new exit 2 breaks no caller. The handler's own --help usage line (src/core/commands/daemon.js:259) was kept in sync with the registration, which is easy to forget.
• The package_bin_boot smoke parses command rows with ^ {2}(\S+) {2,}\S (hypaware-core/smoke/flows/package_bin_boot.js:85). The new Global options: rows do not match it (--help, -h has a single space inside the pair), and the new Aliases: section adds only a harmless extra unattach row to a list asserted for daemon, status, and length >= 10. No smoke breakage.

Findings

1. LOW, not fixed. src/core/cli/dispatch.js:509 - hyp help <group> <typo> renders the group help and exits 0, where every other spelling of the same mistake exits 2.

Evidence, all reproduced against the built CLI on this head:

• hyp help query bogus prints the query group table and exits 0. Nothing says bogus is not a subcommand.
• hyp query bogus --help prints hyp query: unknown subcommand 'bogus' and exits 2 (src/core/cli/group_help.js:157).
• hyp help graph bogus exits 2, because a plugin namespace has no bare command and falls through to resolveGroupHelp (src/core/cli/dispatch.js:353).

So the same user error gets three different answers depending on spelling, and the hyp help spelling is the one that stays silent. That is the shape of failure LLP 0270 #help-verb calls out one level up, though it is much milder here: the page shown is the right command's page and it lists the valid subcommands, so the typo is still self-correcting.

Why I did not fix it: the obvious guard (force help only when matched.rest has no leftover non-flag token) is wrong on this codebase. backfill is a group parent that legitimately takes positionals (hyp backfill [provider...], src/core/cli/core_commands.js:150-153), and hyp help backfill claude correctly renders backfill help today. Letting the group command run instead is worse: runBackfill does not handle a stray --help (src/core/commands/backfill.js:50), which is exactly the hyp help purge <path> hazard the branch already guards against. Telling a pure group (built by makeGroupCommand) apart from a group whose bare command takes positionals is not derivable from the registration, so a correct fix needs a new marker on CommandRegistration (or a WeakSet exported from group_help.js). That is public API surface plus a design decision LLP 0270 does not settle, which belongs in a follow-up rather than a review round on an otherwise clean PR.

2. NIT, not fixed. src/core/cli/dispatch.js:404 - hyp help zzz reports hyp: unknown command 'help zzz'.

The token that is actually unknown is zzz, and quoting the pair reads as though a help namespace exists. Against that, the message does echo exactly what the user typed, and the branch tests this wording deliberately (test/core/cli/help-metadata.test.js:195). Judgment call, not a defect. If you want the other spelling, typedArgv.slice(1) on this path is the whole change.

3. NIT, description only. The PR body understates the new test file and misreports the suite baseline.

It says 11 assertions with 10 of 11 failing on master; test/core/cli/help-metadata.test.js contains 14 test(...) cases. It also reports 4207 pass / 22 fail with 22 pre-existing failures; this environment runs 4497 pass / 0 fail on the same head, so those 22 look environmental rather than a property of master. Worth correcting in the body of a PR whose subject is stale claims, but no code impact.

What I fixed

Nothing. No commit pushed to fix/issue-835; head remains 590d4f4. Finding 1 is left open for a follow-up that can introduce the group marker properly; findings 2 and 3 are judgment calls for the author.

[philcunliffe]

Triage at head 590d4f438466daeca01285d5d270a8fe13814903: every residual review finding is non-blocking; deferred to #873.

Classification of the open findings from the exhausted review rounds:

• Round 2 finding 1 (low): hyp help <group> <typo> exits 0 with the group table. Preference-grade UX inconsistency: the right page renders, the typo is self-correcting, and nothing wrong executes. A correct fix needs new CommandRegistration surface to tell pure groups from positional-taking group parents, which is follow-up work, not a merge risk.
• Round 2 finding 2 (nit): unknown command 'help zzz' wording. Deliberate, tested, judgment call.
• Round 2 finding 3 (nit): PR body test-count and baseline inaccuracies. Description only, no code impact.
• Round 1 finding 6 (design call): blanket --platform refusal also rejects the matching host. Clean exit 2, no caller broken, settled in Accepted LLP 0270; revisiting it means a new LLP, tracked in the follow-up.
• Round 1 finding 7 (informational): hand-maintained usage string in runDaemonInstall. Pre-existing, cross-command cleanup.
• Round 1 finding 8 (informational): branch behind master. Resolved: head is a merge of origin/master, 0 commits behind at triage time.

No finding could cause wrong behaviour, data loss, a security hole, a crash, or a performance regression in production, so the PR can merge safely with #873 carrying the deferrals.

[philcunliffe]

Closing as superseded by #857 and #862. The task-oriented registry, help metadata, CLI guide, and generated CLI reference replaced this pre-rollover help surface.