docs: onboarding UX consolidation (first-run friction signals) #383

Context

Doc-intelligence identified converging signals from Teams and GitHub around first-run friction:

• Teams users repeatedly confused about --yolo necessity ("Why is Squad asking me to edit every file?")
• Issue squad init: agent invisible when CWD is inside a parent git repo #374: parent git repo initialization trap
• PR docs: recommend --yolo in README Quick Start #375: proposes --yolo in README Quick Start (awaiting review)
• Multiple "Taking a long time" reports resolved by --yolo

Suggested Scope

1. Merge PR docs: recommend --yolo in README Quick Start #375 (--yolo in README Quick Start)
2. Update Squad init docs to warn about parent git repos (cross-ref squad init: agent invisible when CWD is inside a parent git repo #374)
3. Create a "Before You Start" checklist page: --yolo, init environment checks, recovery steps
4. Update CONTRIBUTING.md if needed for squad init setup pattern

Source

Doc-intelligence digest signal #4 (2026-03-13 scan). High confidence — multiple independent sources converge on the same friction points.

Created by Squad activity-aggregator from doc-intelligence signals