Reorganize CLI around task-oriented journeys

[philcunliffe]

Summary

• reorganize top-level help around setup, exploration, sharing, capture, privacy, and movement journeys, with operational families kept direct
• add canonical setup, client, privacy, cache, MCP, enrichment, graph, vector, and dev routes while preserving changed spellings as hidden aliases with identical runners and boot profiles
• project Claude OTEL attach mode, endpoint drift, and capture health through status and client status, and aggregate session ignore state across live recorders
• update manifests, walkthroughs, diagnostics, docs, bundled skills, LLP rationale, and command-semantics research
• add a repository-wide CLI consistency gate and OTEL client-status coverage

Deliberately deferred

• setup update, setup repair, and setup rollback remain documented future lifecycle work
• source gascity canonical routes remain withheld until attach and detach persist configuration
• the real-Claude claude_otel_shape_check remains a required release acceptance gate

Verification

• npm test: 4,505 passed, 2 skipped, 0 failed
• npm run typecheck
• CLI consistency and repository hygiene gates
• required CLI, walkthrough, attach, package boot, Claude telemetry, session-ignore, and capture-health smoke flows

[philcunliffe]

Review of b8a1085 (adopted PR, fixes pushed to the branch)

Verdict: findings. Five actionable findings, four of them user-visible
defects, all fixed on the branch in 17026c9. Baseline on the reviewed head was
green (4493 pass / 0 fail, npm run typecheck clean), so nothing here is
pre-existing breakage.

Reviewed with the code-review skill at high (dual-review is unavailable on
this host: no codex), then every finding was re-verified by hand against a
temp HYP_HOME and compared to origin/master behavior before it was fixed.

---

1. hyp session on an install without @hypaware/ai-gateway answers with an empty table (medium, fixed)

src/core/cli/core_commands.js:116 registers session as a core-owned task
group, but every one of its subcommands is contributed by
@hypaware/ai-gateway. With that plugin inactive the group shell still matches,
so the dispatch-miss repair path never runs. Reproduced against an empty config:

argv	master	b8a1085
hyp session	hyp: 'session' is provided by @hypaware/ai-gateway, which is not in the active config + repair, exit 2	group help with an empty Subcommands: list, exit 0
hyp session zzz	same repair, exit 2	hyp session: unknown subcommand 'zzz' / expected one of: (literally empty), exit 2

The new inactive-plugin check at src/core/cli/dispatch.js:401 is guarded by
matched.rest.length > 0, so bare hyp session skips it, and
longestCommandPrefix returns undefined for ['session','zzz'] so that case
falls through too. This also contradicts the epilogue hyp --help prints in
this same PR: "run it anyway: hyp names the plugin that provides it and prints
how to enable it."

test/core/cli-consistency-gate.test.js cannot catch it: the group test does
if (children.length === 0) continue, and the unknown-subcommand test iterates
an empty child list.

Fix: an empty core-owned group is probed on its own canonical tokens, so
hyp session, hyp session ignore, hyp session zzz, and hyp session --help
all report the owning plugin and the repair. Regression test added in
test/core/dispatch-inactive-plugin.test.js; confirmed it fails on b8a1085
and passes after.

2. hyp client status claims endpoint drift from a dead daemon's snapshot (medium, fixed)

src/core/commands/status.js:260 (listenerEndpointFromReport, used at :181)
reads details.listen_port straight off report.sources with no liveness gate.
The equivalent hyp status diagnostic is deliberately gated
(src/core/daemon/status.js:1230), with a comment explaining that "the listener
was last bound to X" is not a claim a dead daemon's snapshot can support.

hyp client status boots with bootProfile: 'none', so report.sources falls
back to the persisted status.json. Daemon stopped, last snapshot holding an
ephemeral listener port, client marker holding the default: hyp status
correctly stays silent while hyp client status prints [endpoint drift] and
endpoint_drift: true. The two surfaces this projection exists to reconcile
disagree.

Fix: the projection now carries the same daemon.running gate, so a stopped
daemon reports listener not running and endpoint_drift: null. Fixture in
test/core/client-status-otel.test.js gained the daemon field it was missing,
plus a dead-daemon case.

3. hyp session status drops one recorder's answer and prints another twice (low, fixed)

hypaware-core/plugins-workspace/ai-gateway/src/session_command.js:302-320
picks primary = outcomes.find(o => o.status === 'not_ignored'), which is not
necessarily outcomes[0], but writeStatus renders the remaining rows from
report.recorders.slice(1). With outcomes = [gateway: ignored, openclaw: not_ignored] the headline and endpoint/endpoint_source describe openclaw,
slice(1) reprints openclaw, and the gateway's ignored answer never appears.
The ignored branch was safe only because that status implies every outcome is
ignored.

Same file, runSessionStatus: resolvedTargets.gatewayError was surfaced only
when targets.length === 0, so an unresolvable gateway plus a resolvable extra
recorder yielded a plain ignored / exit 0. runMutation writes
hyp session: gateway not addressed: ... to stderr for the identical condition.

Fix: a secondaryRecorders(report) helper drops the outcome the headline
already spoke for (matched by endpoint, which is unique because
resolveAdvertisedRecordersForCli dedupes against the gateway), and status now
reports an unaddressed gateway on stderr like the mutations do. The JSON
recorders array keeps its gateway-first inventory order, so no consumer shape
changes. Covered in test/plugins/ai-gateway-session-both-recorders.test.js.

4. hyp query vector's own blurb points at a route that loops (low, fixed)

vector search moved to query vector search but vector status did not,
while runVector (hypaware-core/plugins-workspace/vector-search/src/commands.js:26)
prints a subcommand table listing status. query vector status was not
registered, so longest-prefix matching resolved hyp query vector status back
to query vector, which ignores argv and reprints the same blurb with exit 0: a
user following the printed guidance loops. The manifest summary ("see
subcommand: search") and the registration summary ("see subcommands: search,
status") also disagreed.

Fix: vector status stays the canonical direct operation, because
LLP 0248 lists it among the
direct operations and vector keeps its top-level help row because of it. It
now answers to query vector status as an alias, so the group's advertised
table is navigable, and both summaries were reconciled. The user-facing usage
and error strings for search were canonicalized to hyp query vector search.

5. An unrecognized help category silently vanishes from hyp --help (low/latent, guarded)

src/core/registry/commands.js:59 invents
command.category ??= command.plugin ? 'additional' : command.name.split(' ')[0],
while orderedHelpNames (src/core/cli/dispatch.js:858) only ever emits four
categories. Any command whose category is none of them is dropped from
hyp --help with no error and no test coverage. Harmless today (every visible
top-level core command carries an explicit category, verified by enumerating the
registry), but dev smoke already demonstrates the mechanism with
category: 'dev' and only escapes notice because it is hidden.

Fix: helpSectionFor() buckets an unrecognized category into "Additional
commands" rather than matching nothing. No output changes today; it removes the
silent-drop failure mode. The registry's fallback and audience derivation were
left alone deliberately, since changing them would move existing subcommands
between audiences for no benefit.

---

Checked and clean

• Alias plumbing (registry.match longest-prefix + aliasIndex): hyp policy set,
  hyp detach, hyp backfill --help, hyp mcp --remote, hyp smoke, hyp init
  all still resolve; collision detection covers both directions.
• Nested-group navigation in makeGroupCommand: hyp client history,
  hyp client history bogus, hyp client bogus, hyp cache render/error correctly.
• Inactive-plugin reporting through the new canonical paths:
  hyp client claude-desktop [install], hyp client claude-account status,
  hyp query vector, hyp graph all name the owning plugin and the repair.
• ctx.commands.run seam after activateSeamCommandPlugins switched from
  head-token to full-name matching: every caller matches a manifest name/alias
  exactly.
• decideBootProfile(argv, registry): the explicit bootProfile fields plus the
  name fallbacks reproduce the old argv-prefix behavior for setup/init,
  status, version, smoke, and all daemon *.
• resetCentralLayerToSeed symlink unlink fix (src/core/config/apply.js:231) is
  correct and ENOENT-tolerant.
• The claude picker/preset change (dropping gateway_proxy_mode, the anthropic
  upstream, and required_upstreams) is consistent with claude's OTEL-only attach
  mode already on master, and is what makes the claude_attach_detach smoke's new
  empty-stderr assertion correct.

Nothing left open

No finding was deliberately left unfixed. Note that the release still owes the
real-Claude claude_otel_shape_check acceptance procedure, as the PR body
already says; the hermetic smokes do not substitute for it.

Verification after the fixes

• npm test: 4508 passed, 1 skipped, 0 failed (baseline on b8a1085: 4493 / 0).
• npm run typecheck: clean.
• Smokes green: cli_bundled_plugins_activated, package_bin_boot,
  status_diagnostics, client_attach_idempotent, claude_telemetry_capture,
  hypignore_capture_drop, vector_search_local_fixture,
  walkthrough_picker_to_first_query, claude_attach_detach.
• All new @ref anchors resolve to existing LLP sections.

[philcunliffe]

neutral resolved the conflict with master in c08ce17. npm test: 4,551 passed, 1 skipped, 0 failed. npm run typecheck: clean. The branch is now MERGEABLE.

Three conflicts, all resolved on the merits:

• docs/PRIVACY.md - kept master's new "What else macOS attach leaves behind" paragraph and its expanded CA-lifetime paragraph (permitted hosts, launchd variable), respelled to this branch's canonical hyp client detach claude route.
• hypaware-core/plugins-workspace/ai-gateway/src/source.js - kept master's corrected stale-CA remedy from The stale-CA warning names a remedy that cannot work, and AGENTS.md omits openclaw_capture (#831) #833 (a plain re-attach cannot clear the CA, so the warning must name --purge or turning proxy_mode back on) with this branch's hyp client detach spelling. test/plugins/ai-gateway-proxy-mode.test.js was updated to pin the new spelling.

Two calls worth a human's eye:

1. test/core/attach-proxy-migration.test.js (modify/delete) - this branch deletes it; master's Proxy mode by default: design of record for LLP 0242, plus the missing --json non-interactive pin #817 had just added two --json non-interactive pins to it. neutral honored the deletion. Reason: this branch implements accepted LLP 0262 by dropping compose.gateway_proxy_mode from the claude picker row, so no client declares it and maybeOfferProxyModeMigration can never fire. Restoring the file (tried first) fails 8 of 11 tests for exactly that reason. Note the side effect: maybeOfferProxyModeMigration in src/core/commands/clients.js is now unreachable on this branch and has no test coverage. If that is intended, it is probably dead code to retire in a follow-up; if the claude row was meant to keep proxy mode, this is the line to look at.
2. LLP 0249 number collision - both branches minted 0249 independently (master: 0249-proxy-mode-default-attach.plan.md via Proxy mode by default: design of record for LLP 0242, plus the missing --json non-interactive pin #817; this branch: 0249-cli-compatibility-rollover.plan.md). git merged both files silently. Master's is the published record, so this branch's plan was renumbered to LLP 0266, along with its two @ref LLP 0249#milestones annotations in ai-gateway/src/session_command.js and the research handoff that names it. test/core/llp-ref-hygiene.test.js passes on the result.

No other change was made; no merge, no ready-flip.

[philcunliffe]

Review round: c08ce17 (task-oriented CLI rollover)

Verdict: approve with fixes applied. The rollover itself is sound and unusually well covered:
npm test (4551 pass), npm run typecheck, and the cli_bundled_plugins_activated,
package_bin_boot, client_attach_idempotent, status_diagnostics smokes are all green at
this head. I exercised the real binary against a temp HYP_HOME and confirmed the new tree
behaves: journey sections render in LLP 0248 order, hyp policy / hyp attach / hyp backfill
/ hyp skills / hyp smoke all resolve to their canonical registrations, hyp session with the
gateway inactive gives the LLP 0153 "unavailable, here is the repair" answer instead of an empty
group table, and nested groups (hyp client history, hyp cache, hyp query graph) route and
report unknown subcommands with exit 2. test/core/cli-consistency-gate.test.js is a good
structural gate for this surface.

Two actionable findings. Both are fixed and pushed to codex/cli-reorg as 5540e4e.

---

1. test/core/attach-proxy-migration.test.js deleted, nothing put in its place - medium

test/core/attach-proxy-migration.test.js (360 lines) is removed by commit 97860ef. It is
green on master (11/11, verified in a clean origin/master worktree). Restored onto this
branch it fails 8 of 11 - and the cause is this branch's own change, not a rename:

• hypaware-core/plugins-workspace/claude/hypaware.plugin.json:52-56 drops
  gateway_proxy_mode, gateway_upstream, and plugin.config.proxy from the claude picker
  row (the LLP 0262 reconciliation LLP 0266 M4 asks for).
• The migration offer's only gate is
  descriptor?.compose?.gateway_proxy_mode !== true at
  src/core/commands/clients.js:832. After this branch, no bundled picker row declares that
  flag (grep -rn gateway_proxy_mode hypaware-core/plugins-workspace/*/hypaware.plugin.json
  returns nothing), so maybeOfferProxyModeMigration (~130 lines,
  src/core/commands/clients.js:822) and the walkthrough's gatewayProxyMode fold
  (src/core/cli/walkthrough.js:915,931,972) are unreachable for every bundled client.

So the deletion is consistent with the change, but it leaves the new contract with zero
coverage: nothing pins that hyp client attach claude no longer asks the proxy question, and
nothing would notice if the offer came back by accident on a picker-row edit. A silent offer and
a broken offer look identical from the outside.

Fixed by rewriting the file at the same path with six pins that assert the new outcome from
both ends: structurally, that no bundled picker row declares the gate flag (read from the real
manifests via discoverBundledPlugins + buildPluginCatalog, not a fixture); behaviorally, that
a real runAttach against a pre-rollover base-URL config asks nothing, points at nothing, and
writes nothing in each shape that used to get a question or a pointer (interactive TTY, --json
on a TTY, non-TTY, all), plus the surviving codex negative. The file's header points at the git
history for the behavior pins to restore if the flag is ever re-declared.

Verified it has teeth, not just green: temporarily re-adding gateway_proxy_mode: true to the
claude picker row fails 5 of the 6 (not ok 1, 2, 4, 5, 6), and it was restored afterwards
(git diff --stat on the manifest clean).

2. README.md was not rolled over, and documents a diagnostic this branch removes - low/medium

README.md is not in the diff at all, though LLP 0266 M4 puts docs in scope. Two problems:

• Factually wrong row. README.md:507 documented gateway_missing_anthropic_upstream as
  "@hypaware/claude enabled but no Anthropic upstream is registered on the gateway". This
  branch removes required_upstreams: ["anthropic"] from both the claude manifest
  (hypaware-core/plugins-workspace/claude/hypaware.plugin.json:45) and the hardcoded fallback
  in src/core/config/validate.js:644, so that condition can no longer fire for
  @hypaware/claude. The kind itself survives, because @hypaware/openclaw still declares
  required_upstreams: ["anthropic", "openai"], so the row is corrected rather than deleted.
• 51 pre-rollover spellings (hyp init, hyp attach, hyp detach, hyp policy ...,
  hyp ignore, hyp purge, hyp backfill codex, hyp query status, hyp graph neighbors,
  hyp plugin doctor|new, hyp claude-desktop install) in the project's front door. They all
  still work through the aliases, so this is drift rather than breakage - but the README is where
  a new user learns the surface this PR exists to reorganize.

Fixed: README rolled onto the canonical spellings, the diagnostic row corrected, and the
still-accepted hyp attach / hyp detach / hyp unattach forms kept visible in the attach
section (labelled as the pre-rollover spellings) rather than silently dropped. One phrase
adjusted for accuracy: client_attach_missing's follow-on no longer says attach "wires a client
into the local gateway", which stopped being true for claude at LLP 0262.

---

Non-blocking observations (not fixed)

• CommandRegistry.register mutates its argument. src/core/registry/commands.js:59-62
  does command.category ??= ... / command.audience ??= / command.bootProfile ??= on the
  caller's object, and does it before the duplicate-name and alias-collision checks. A
  rejected registration therefore leaves the caller's object mutated, and a third-party plugin
  that passes a frozen module-level constant would get a TypeError from the defaulting rather
  than a registry error. Copying into a local record before defaulting would be strictly safer.
  No bundled caller is affected today.
• Metadata-only groups render help without a header. hyp cache and hyp client history
  print usage: plus the subcommand table with no hyp <group> - <summary> line, unlike every
  group that has a bare command or a registerGroup entry (hyp client, hyp privacy,
  hyp query graph). cache is a brand-new top-level token in Additional commands, so it has
  no summary anywhere in help. A registry.registerGroup({ name: 'cache', ... }) and one for
  client history would close it - the same gap LLP 0214 exists to prevent, in the new tree.
• AGENTS.md (16) and CONTEXT.md (3) still use hyp smoke. Developer-facing, alias-backed,
  and npm run smoke -- <flow> is the documented path anyway, so left alone.
• LLP 0248 and LLP 0266 are both Status: Draft. Worth confirming that is intentional for a
  merge, given the repo convention that shipped design lands as Accepted.
• Scope note, not a defect: this PR carries more than help reorganization - the LLP 0262
  claude picker/preset reconciliation, the LLP 0266 multi-recorder hyp session status, and an
  unrelated symlink fix in resetCentralLayerToSeed (src/core/config/apply.js:230-243, which
  is a genuine improvement: rmSync(..., { force: true }) leaves a dangling or looping symlink
  in place). LLP 0266 M4 does call for the claude reconciliation, so this is disclosed rather
  than smuggled; flagging it so the merge notes say so.

Verification of the pushed fixes

• git diff c08ce17..5540e4e --stat -> README.md (109 lines), test/core/attach-proxy-migration.test.js (237 lines, new).
• git show 5540e4e:test/core/attach-proxy-migration.test.js contains the structural pin at line 160.
• git show 5540e4e:README.md:507 carries the corrected diagnostic row.
• npm test: 4557 pass / 0 fail (up 6 from 4551). npm run typecheck: clean.
• Negative check on the new test performed and reverted, as described above.

[philcunliffe]

Triage at head 5540e4e0: no blockers remain. The last review round (c08ce17) fixed both of its actionable findings on the branch; every residual finding is a preference (argument-mutation robustness in CommandRegistry.register, missing group-help headers for hyp cache / hyp client history, stale hyp smoke spellings in AGENTS.md, LLP 0248/0266 still Draft). Each was re-verified against the head worktree during triage: npm test 4557 pass / 0 fail, npm run typecheck clean.

Deferred findings are tracked in follow-up issue #946: #946

This PR can merge safely.