feat: ultraworkers#153 — add post-build binary location and verification guide to README

## Problem

Users frequently ask after building:
- "Where is the claw binary?"
- "Did the build actually work?"
- "Why can't I run \`claw\` from anywhere?"

This happens because \`cargo build\` puts the binary in \`rust/target/debug/claw\`
(or \`rust/target/release/claw\`), and new users don't know:
1. Where to find it
2. How to test it
3. How to add it to PATH (optional but common follow-up)

## Fix

Added new section "Post-build: locate the binary and verify" to README covering:

1. **Binary location table:** debug vs. release, macOS/Linux vs. Windows paths
2. **Verification commands:** Test the binary with \`--help\` and \`doctor\`
3. **Three ways to add to PATH:**
   - Symlink (macOS/Linux): \`ln -s ... /usr/local/bin/claw\`
   - cargo install: \`cargo install --path . --force\`
   - Shell profile update: add rust/target/debug to \$PATH
4. **Troubleshooting:** Common errors ("command not found", "permission denied",
   debug vs. release build speed)

## Impact

New users can now:
- Find the binary immediately after build
- Run it and verify with \`claw doctor\`
- Know their options for system-wide access

Also filed ROADMAP ultraworkers#153 documenting the gap.

Closes ROADMAP ultraworkers#153.

Author: code-yeongyu

README.md

@@ -98,10 +98,87 @@ export ANTHROPIC_API_KEY="sk-ant-..."
 
 **Git Bash / WSL** are optional alternatives, not requirements. If you prefer bash-style paths (`/c/Users/you/...` instead of `C:\Users\you\...`), Git Bash (ships with Git for Windows) works well. In Git Bash, the `MINGW64` prompt is expected and normal — not a broken install.
 
+## Post-build: locate the binary and verify
+
+After running `cargo build --workspace`, the `claw` binary is built but **not** automatically installed to your system. Here's where to find it and how to verify the build succeeded.
+
+### Binary location
+
+After `cargo build --workspace` in `claw-code/rust/`:
+
+**Debug build (default, faster compile):**
+- **macOS/Linux:** `rust/target/debug/claw`
+- **Windows:** `rust/target/debug/claw.exe`
+
+**Release build (optimized, slower compile):**
+- **macOS/Linux:** `rust/target/release/claw`
+- **Windows:** `rust/target/release/claw.exe`
+
+If you ran `cargo build` without `--release`, the binary is in the `debug/` folder.
+
+### Verify the build succeeded
+
+Test the binary directly using its path:
+
+```bash
+# macOS/Linux (debug build)
+./rust/target/debug/claw --help
+./rust/target/debug/claw doctor
+
+# Windows PowerShell (debug build)
+.\rust\target\debug\claw.exe --help
+.\rust\target\debug\claw.exe doctor
+```
+
+If these commands succeed, the build is working. `claw doctor` is your first health check — it validates your API key, model access, and tool configuration.
+
+### Optional: Add to PATH
+
+If you want to run `claw` from any directory without the full path, choose one of these approaches:
+
+**Option 1: Symlink (macOS/Linux)**
+```bash
+ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw
+```
+Then reload your shell and test:
+```bash
+claw --help
+```
+
+**Option 2: Use `cargo install` (all platforms)**
+
+Build and install to Cargo's default location (`~/.cargo/bin/`, which is usually on PATH):
+```bash
+# From the claw-code/rust/ directory
+cargo install --path . --force
+
+# Then from anywhere
+claw --help
+```
+
+**Option 3: Update shell profile (bash/zsh)**
+
+Add this line to `~/.bashrc` or `~/.zshrc`:
+```bash
+export PATH="$(pwd)/rust/target/debug:$PATH"
+```
+
+Reload your shell:
+```bash
+source ~/.bashrc  # or source ~/.zshrc
+claw --help
+```
+
+### Troubleshooting
+
+- **"command not found: claw"** — The binary is in `rust/target/debug/claw`, but it's not on your PATH. Use the full path `./rust/target/debug/claw` or symlink/install as above.
+- **"permission denied"** — On macOS/Linux, you may need `chmod +x rust/target/debug/claw` if the executable bit isn't set (rare).
+- **Debug vs. release** — If the build is slow, you're in debug mode (default). Add `--release` to `cargo build` for faster runtime, but the build itself will take 5–10 minutes.
+
 > [!NOTE]
 > **Auth:** claw requires an **API key** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) — Claude subscription login is not a supported auth path.
 
-Run the workspace test suite:
+Run the workspace test suite after verifying the binary works:
 
 ```bash
 cd rust

ROADMAP.md

@@ -5905,3 +5905,32 @@ pub fn from_cwd(cwd: impl AsRef<Path>) -> Result<Self, SessionControlError> {
 **Blocker.** None. Implementation exists on worktree `jobdori-127-verb-suffix` but needs rebase against main (conflicts with #141 which already shipped).
 
 **Source.** Clawhip nudge 2026-04-21 21:17 KST — "no excuses, always find something to ship" directive. Session tally: ROADMAP #152.
+
+## Pinpoint #153. README/USAGE missing "add binary to PATH" and "verify install" bridge
+
+**Gap.** After `cargo build --workspace`, new users don't know:
+1. Where the binary actually ends up (e.g., `rust/target/debug/claw` vs. expecting it in `/usr/local/bin`)
+2. How to verify the build succeeded (e.g., `claw --help`, `which claw`, `claw doctor`)
+3. How to add it to PATH for shell integration (optional but common follow-up)
+
+This creates a confusing gap: users build successfully but then get "command not found: claw" and assume the build failed, or they immediately ask "how do I install this properly?"
+
+**Real examples from #claw-code:**
+- "claw not found — did the build fail?"
+- "do I need to `cargo install` this?"
+- "why is the binary at `rust/target/debug/claw` and not just `claw`?"
+
+**Fix shape (~50 lines).** Add a new "Post-build verification and PATH" section in README (after Quick start) covering:
+1. **Where the binary lives:** `rust/target/debug/claw` (debug build) or `rust/target/release/claw` (release)
+2. **Verify it works:** Run `./rust/target/debug/claw --help` and `./rust/target/debug/claw doctor`
+3. **Optional: Add to PATH** — three approaches:
+   - symlink: `ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw`
+   - `cargo install --path ./rust` (builds and installs to `~/.cargo/bin/`)
+   - update shell profile to export PATH
+4. **Windows equivalent:** Point to `rust\target\debug\claw.exe` and `cargo install --path .\rust`
+
+**Acceptance:** New users can find the binary location, run it directly, and know their first verification step is `claw doctor`.
+
+**Blocker:** None. Pure documentation.
+
+**Source:** Clawhip nudge 2026-04-21 21:27 KST — onboarding gap from #claw-code observations earlier this month.