cli: regroup root --help and unify domain verbs

[kunallanjewar]

Summary

The content of guild --help is good but the structure undercuts it. Six concrete cleanups would make first-run readers grasp the tool faster.

Findings

1. Cobra alphabetization buries the lede

The first commands a new user sees are completion, help, hints, not lore, quest, mcp, init. The intro paragraph already establishes lore/quest/mcp as the headline; the command list should reinforce that.

Fix: use Cobra command groups via AddGroup. Suggested:

• Core: lore, quest, mcp, init, status
• Inspection: hints, telemetry, version
• Shell: completion, help

2. Verb mismatch between intro and command lines

The intro lists (inscribe, appraise, study, ...) for lore. The command-list one-liner says (read/write/decay/supersede). Two different vocabularies for the same surface.

Fix: pick the MCP verbs (the words users actually type) and use them everywhere. Drop "decay/supersede" from user-facing copy: they are internal state-machine jargon that costs a reader more than they pay back.

3. hints and telemetry are visually peer to lore/quest, but they are not

They are inspection surfaces, not domains. Right now they have equal visual weight to the two things guild is actually for.

Fix: either group them under "Inspection" (per #1) or mark one Hidden: true and document inside its parent's --help.

4. status description forward-references quest bounties

"alias of quest bounties" assumes the reader has already read the quest section. They have not, since status is what they are reading first.

Fix: lead with the function ("dashboard: last briefing, oath, top bounty"), drop the alias note or move it to a trailing paren.

5. Three-mode framing compares unlike categories

The intro calls lore, quest, and MCP three modes. Lore and quest are domains (what); MCP is a surface (how it is served). Calling MCP a third mode alongside the other two compares categories that do not match.

Fix: re-frame as "two domains (lore + quest), two surfaces (CLI + MCP), one store at `~/.guild/`."

6. "static binary" is source-install jargon

Brew/cask/install.sh users do not care about CGO. "single binary" reads cleaner without losing accuracy for the source-install audience.

Acceptance

• Root guild --help groups commands by function (Core / Inspection / Shell or similar)
• Single set of domain verbs across intro paragraph and per-command Short descriptions
• status Short does not forward-reference quest bounties
• Intro framing distinguishes domains from surfaces (or unifies on a clean alternative)
• "single" replaces "static" in the lead paragraph

Out of scope

• Restructuring subcommand help (lore --help, quest --help): file separately if wanted.
• Renaming any command or MCP verb: vocabulary alignment only, not a rename.