First-contact UX: init preview, command grouping, version pinning

[kokevidaurre]

First-contact UX sim (2026-06)

Fed a fresh model only the README + squads --help (no prior context) and asked it to react as a skeptical first-time user. Comprehension passed — it understood the product in one sentence and picked a sensible first command (doctor → init). Remaining friction it surfaced:

• P1 — autopilot deprecated in --help but featured in README. Fixed in a separate docs PR.
• P0 — squads init gives no pre-run preview. A new user doesn't know what it creates, whether it needs API keys, or if it clobbers an existing .agents/. (It does print a manifest after running, but nothing before.) Consider a one-line "creates .agents/ with N starter squads; safe to re-run" note in init --help and/or a confirm on existing .agents/.
• P1 — command overlap with no "start here". log, exec, history, runs, progress all sound like execution history; --help lists ~40 flat commands. Consider grouping (or a short "Common commands" block at the top of --help).
• P2 — no version-pinning guidance. npm install -g squads-cli pulls latest; for a tool whose agents write to git, a note on pinning / @latest expectations would build trust.

Source: repeatable first-contact regression (README + --help → fresh-model comprehension). GPT lane blocked ($0 credit); ran the Claude lane.