diff --git a/README.md b/README.md
index f64498c..7e261ac 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,35 @@ export ANTHROPIC_API_KEY="sk-ant-..."
 > [!NOTE]
 > **Windows (PowerShell):** the binary is `claw.exe`, not `claw`. Use `.\target\debug\claw.exe` or run `cargo run -- prompt "say hello"` to skip the path lookup.
 
+### Windows setup (Git Bash / WSL)
+
+If you are on Windows, the recommended shell is **Git Bash** (ships with Git for Windows) or **WSL**. Full sequence:
+
+1. **Install Rust** — download from <https://rustup.rs/> and run the installer. Close and reopen the terminal when it finishes.
+2. **Open Git Bash** — search for "Git Bash" in the Start menu (not PowerShell, not cmd). The prompt shows `MINGW64` — this is normal and expected, not a broken install.
+3. **Verify Rust is on PATH:**
+   ```bash
+   cargo --version
+   ```
+   If you see `bash: cargo: command not found`, run `. ~/.cargo/env` or restart Git Bash, then retry.
+4. **Use bash-style paths** — in Git Bash, `C:\Users\you` becomes `/c/Users/you`:
+   ```bash
+   cd /c/Users/you/projects
+   ```
+5. **Clone and build:**
+   ```bash
+   git clone https://github.com/ultraworkers/claw-code
+   cd claw-code/rust
+   cargo build --workspace
+   ```
+6. **Run:**
+   ```bash
+   export ANTHROPIC_API_KEY="sk-ant-..."
+   ./target/debug/claw prompt "say hello"
+   ```
+
+> **WSL tip:** WSL2 (`wsl --install` from an admin PowerShell) is the most friction-free Windows path — follow the Linux quick-start steps inside the WSL terminal.
+
 > [!NOTE]
 > **Auth:** claw requires an **API key** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) — Claude subscription login is not a supported auth path.
 
diff --git a/ROADMAP.md b/ROADMAP.md
index 3104fa8..9afc52c 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -526,3 +526,5 @@ Model name prefix now wins unconditionally over env-var presence. Regression tes
 49. **Resumed slash command errors emitted as prose in `--output-format json` mode** — dogfooded 2026-04-09. `claw --output-format json --resume <session> /commit` called `eprintln!()` and `exit(2)` directly, bypassing the JSON formatter. Both the slash-command parse-error path and the `run_resume_command` Err path now check `output_format` and emit `{"type":"error","error":"...","command":"..."}`. **Done at `da42421` 2026-04-09**. Source: gaebal-gajae ROADMAP #26 track; Jobdori dogfood.
 
 50. **PowerShell tool is registered as `danger-full-access` — workspace-aware reads still require escalation** — dogfooded 2026-04-10. User running `workspace-write` session mode (tanishq_devil in #claw-code) had to use `danger-full-access` even for simple in-workspace reads via PowerShell (e.g. `Get-Content`). Root cause traced by gaebal-gajae: `PowerShell` tool spec is registered with `required_permission: PermissionMode::DangerFullAccess` (same as the `bash` tool in `mvp_tool_specs`), not with per-command workspace-awareness. Bash shell and PowerShell execute arbitrary commands, so blanket promotion to `danger-full-access` is conservative — but it over-escalates read-only in-workspace operations. Fix shape: (a) add command-level heuristic analysis to the PowerShell executor (read-only commands like `Get-Content`, `Get-ChildItem`, `Test-Path` that target paths inside CWD → `WorkspaceWrite` required; everything else → `DangerFullAccess`); (b) mirror the same workspace-path check that the bash executor uses; (c) add tests covering the permission boundary for PowerShell read vs write vs network commands. Note: the `bash` tool in `mvp_tool_specs` is also `DangerFullAccess` and has the same gap — both should be fixed together. Source: tanishq_devil in #claw-code 2026-04-10; root cause identified by gaebal-gajae.
+
+51. **Windows first-run onboarding missing: no explicit Rust + shell prerequisite branch** — dogfooded 2026-04-10 via #claw-code. User hit `bash: cargo: command not found`, `C:\...` vs `/c/...` path confusion in Git Bash, and misread `MINGW64` prompt as a broken MinGW install rather than normal Git Bash. Root cause: README/docs have no Windows-specific install path that says (1) install Rust first via rustup, (2) open Git Bash or WSL (not PowerShell or cmd), (3) use `/c/Users/...` style paths in bash, (4) then `cargo install claw-code`. Users can reach chat mode confusion before realizing claw was never installed. Fix shape: add a **Windows setup** section to README.md (or INSTALL.md) with explicit prerequisite steps, Git Bash vs WSL guidance, and a note that `MINGW64` in the prompt is expected and normal. Source: tanishq_devil in #claw-code 2026-04-10; traced by gaebal-gajae.