From 6212f17c93957446614497196473b7332ff386a9 Mon Sep 17 00:00:00 2001
From: YeonGyu-Kim <code.yeon.gyu@gmail.com>
Date: Thu, 23 Apr 2026 07:52:16 +0900
Subject: [PATCH] docs(#153): add binary PATH installation instructions and
 verification steps

Pinpoint #153 closure. USAGE.md was missing practical instructions for:
1. Adding the claw binary to PATH (symlink vs export PATH)
2. Verifying the install works (version, doctor, --help)
3. Troubleshooting PATH issues (which, echo $PATH, ls -la)

New subsections:
- "Add binary to PATH" with two common options
- "Verify install" with post-install health checks
- Troubleshooting guide for common failures

Target audience: developers building from source who want to run `claw`
from any directory without typing `./rust/target/debug/claw`.

Discovered during cycle #96 dogfood (10-min reminder cycle).
Tests: 225/225 still pass (doc-only change).
---
 USAGE.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/USAGE.md b/USAGE.md
index 9795929..03f6d1f 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -36,6 +36,60 @@ cargo build --workspace
 
 The CLI binary is available at `rust/target/debug/claw` after a debug build. Make the doctor check above your first post-build step.
 
+### Add binary to PATH
+
+To run `claw` from anywhere without typing the full path:
+
+**Option 1: Symlink to a directory already in your PATH**
+
+```bash
+# Find a PATH directory (usually ~/.local/bin or /usr/local/bin)
+echo $PATH
+
+# Create symlink (adjust path and PATH-dir as needed)
+ln -s /Users/yeongyu/clawd/claw-code/rust/target/debug/claw ~/.local/bin/claw
+
+# Verify it's in PATH
+which claw
+```
+
+**Option 2: Add the binary directory to PATH directly**
+
+Add this to your shell rc file (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+export PATH="$PATH:/Users/yeongyu/clawd/claw-code/rust/target/debug"
+```
+
+Then reload:
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### Verify install
+
+After adding to PATH, verify the binary works:
+
+```bash
+# Should print version and exit successfully
+claw version
+
+# Should run health check (shows which components are initialized)
+claw doctor
+
+# Should show available commands
+claw --help
+```
+
+If `claw: command not found`, the PATH addition didn't take. Re-check:
+
+```bash
+echo $PATH                    # verify your PATH directory is listed
+which claw                    # should show full path to binary
+ls -la ~/.local/bin/claw      # if using symlink, verify it exists and points to target/debug/claw
+```
+
 ## Quick start
 
 ### First-run doctor check