help: singular commands, hidden plural aliases, one spelling per concept

[hbrooks]

Summary

The primary reader of agent --help is a coding agent deciding its next call: it reads once, cold, with no memory of the last release. The help surface had drifted into several spellings per concept, so this normalizes it and writes the rules down.

• Singular command names, hidden plural aliases. agent asset is what help shows; agent assets still works but never renders. Same for delete (shown) vs rm (hidden) and list vs ls. Read-only integration browsers keep a bare plural leaf (github repos, slack channels) since they have no other verb to disambiguate against.
• Routes out of descriptions. Descriptions say what the caller gets; the REST route moves to a trailing API: line in the long help.
• Short-flag collisions untangled. -o is only an output path (was also output format on config get, and --config-override on session start). -d is only --detach (was also --days). -f is only an input file (was also --force on config init).
• One time-window vocabulary. --since / --until plus --days <n>, natural language accepted everywhere. --start / --end are gone.
• Grouped top-level help — Sessions, Agents, Platform, Integrations, Spend, Account — instead of a flat list of 20.
• New skills/cli-conventions encodes all of the above as a checklist, plus the reserved short-flag table, so the next command added does not reintroduce the drift.

New shared plumbing is src/lib/help.ts: configureCliHelp, alsoKnownAs, apiRoutes.

Drive-by fixes

Two callers were already broken before this branch and are fixed here since it touches the same files:

• scripts/smoke.sh and smoke-local.sh invoked agent run list, dead since the run → session rename, which aborted both scripts under set -e.
• skills/ellipsis/SKILL.md instructed agents to run agent sandbox build, removed in Protocol v3 + session log: agent session log, remove sandbox build + session transcript, sandbox_output renames #68.

Test plan

• npm run typecheck clean; npm test 298/298 pass
• Hidden aliases resolve and render the canonical name: agent assets list, agent sandbox variable rm, agent analytics prs, agent hooks status
• Against a local stub server, --since "3 days ago" reaches the wire as start=<iso> on both session list and analytics pr; analytics prs hits the same route as analytics pr
• Removed flags rejected: config get -o json, session list --start, analytics reviewers -d 7, config init -f
• config init exercised end to end in a scratch dir: writes the file, refuses on re-run, --force overwrites
• The bare-agent/agent "prompt" shorthand still dispatches to session start --connect; --version and help unchanged
• scripts/smoke-local.sh against a local backend (not run here; needs docker compose)

Notes for review

• Aliases are silent by design: no stderr hint, so scripted/agent stdout stays parseable.
• analytics stays plural. It is a mass noun with no singular form, so there is nothing to alias.
• One stale reference left alone as out of scope: docs/RUN_STREAMING_SPEC.md still says agent run get --watch.