docs: add first-run user guide

[AresNing]

Summary

• Add docs/GUIDE.md as a first-run guide for new CodeWhale users.
• Link the guide from the README documentation table.
• Adapt the flash-branch GUIDE draft to current main docs and command/provider references.

Closes #2202.

Testing

• cargo fmt --all -- --check
• cargo check
• cargo clippy --workspace --all-targets --all-features (passes; reports two existing warnings in crates/tui unrelated to this docs-only change)
• HOME=/private/tmp/codewhale-test-home CARGO_HOME=/Users/aresning/.cargo cargo test --workspace --all-features
• git diff --check
• Verified local Markdown links in docs/GUIDE.md resolve

Checklist

• Updated docs or comments as needed
• Added or updated tests where relevant (not needed; docs-only change)
• Verified TUI behavior manually if UI changes (not needed; no UI changes)

Greptile Summary

This PR adds docs/GUIDE.md, a 501-line first-run walkthrough for new CodeWhale users, and links it from the README documentation table. The guide covers installation, first launch, modes, slash commands, tools, sub-agents, and skills, with "Next:" pointers to deeper reference docs at the end of each section.

• All internal relative links in docs/GUIDE.md resolve to existing files (ARCHITECTURE.md, INSTALL.md, CONFIGURATION.md, PROVIDERS.md, MODES.md, KEYBINDINGS.md, TOOL_SURFACE.md, SANDBOX.md, SUBAGENTS.md, MCP.md, OPERATIONS_RUNBOOK.md, ../README.md).
• Commands (codewhale auth set, codewhale doctor, Docker run) match the README exactly; the sub-agents roles table now includes the general role, and the Homebrew block includes the legacy-name clarifying comment — both items raised in previous review rounds are resolved.

Confidence Score: 5/5

Documentation-only change with no runtime code modifications — safe to merge.

Both changed files are pure Markdown. The new guide's content is accurate against the codebase: all linked docs exist, CLI commands match the README, mode descriptions match MODES.md, and the sub-agent roles table is complete. Previously flagged gaps (missing general role, missing Homebrew legacy-name note) are resolved in this revision.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Single-row addition to the documentation table, linking to the new GUIDE.md — correct path, correct position, no issues.
docs/GUIDE.md	New 501-line first-run guide; all linked docs exist, commands match README, the general role is present in the sub-agents table, and the Homebrew legacy-name comment is included — previously flagged items resolved.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[New User] --> B[Install\nnpm / Cargo / Homebrew / Docker]
    B --> C[codewhale auth set --provider deepseek]
    C --> D[codewhale doctor]
    D --> E{First task}
    E --> F[Plan mode\nRead-only exploration]
    E --> G[Agent mode\nTool use + approval gates]
    E --> H[YOLO mode\nTrusted repos only]
    F --> I[Propose change]
    I --> G
    G --> J[Sub-agents\nagent_open / agent_eval / agent_close]
    G --> K[Skills\n/skill, /skills]
    J --> L[Roles: general, explore, plan,\nreview, implementer, verifier]

Loading

Comments Outside Diff (2)

1. docs/GUIDE.md, line 72-74 (link)

   Missing legacy-name note on Homebrew install

   The README's Homebrew block includes the comment # The tap/formula name is legacy; it installs codewhale and codewhale-tui. This guide is explicitly aimed at first-run users, so encountering brew install deepseek-tui with no explanation will be confusing — they may wonder if they're installing the wrong product or a stale fork.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

2. docs/GUIDE.md, line 348-354 (link)

   general (default) role is absent from the sub-agent roles table

   SUBAGENTS.md describes general as the default flexible role and the right default "when the task is 'do this whole thing'". Omitting it leaves readers with an incomplete picture of the orchestration surface — they may not know what role is used when none is specified or when they just ask for parallel work in plain language.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

_{Reviews (2): Last reviewed commit: "docs: add first-run user guide" | Re-trigger Greptile}

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[Hmbown]

Approved for the v0.8.48 candidate queue. CI, Greptile, and GitGuardian are clean on the updated head, and the guide now keeps the legacy Homebrew tap wording explicit while covering the first-run model/tooling path. Thanks @AresNing for tightening the first-run docs and for addressing the review notes.

[Hmbown]

Verified against current main: simulated merge via temp worktree, then verified PR #2278 stacked on top of PR #2256 (v0.8.48) — both apply cleanly, no README conflict (2278 inserts at line 553-559 in the doc table; 2256 touches lines 111/331/477/600/633).

Spot-checks beyond greptile:

• agent_open / agent_eval / agent_close exist in crates/tui/src/prompts.rs:1920-1922.
• Tab cycle "Plan → Agent → YOLO" in §5 matches docs/KEYBINDINGS.md:15.
• All ten slash commands in the §6 table resolve in crates/tui/src/tui/command_palette.rs and crates/tui/src/commands/.
• Tone is consistent with MODES.md / SUBAGENTS.md.

One forward-looking signal: when #2256 lands, the safety story new users actually see in their transcript becomes the verification gate ([VERIFY PASS] / [VERIFY FAIL], added at docs/ARCHITECTURE.md:213 and the new README "Article V is now structural" paragraph). GUIDE.md §5 and §7 frame safety entirely around approval gates and sandbox — both true, but the guide will read as incomplete the moment a first-run user sees their first [VERIFY PASS] annotation with no mention in the onboarding doc. A two-sentence note in §7 ("Working with Tools") pointing at the verify line in transcripts would future-proof this against the v0.8.48 cut.

v0.8.48 (#2256) compatibility: clean.