From 1746f84c79c9b96bd992010ef6eb4f56ae4dca0d Mon Sep 17 00:00:00 2001
From: Yeachan-Heo <hurrc04@gmail.com>
Date: Sun, 5 Apr 2026 17:41:48 +0000
Subject: [PATCH] Promote doctor check in onboarding docs

---
 README.md | 20 ++++++++++++++++++--
 USAGE.md  | 28 +++++++++++++++++++++++++---
 2 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index d8b7039..d48b82a 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@
 </p>
 
 > [!IMPORTANT]
-> The active Rust workspace now lives in [`rust/`](./rust). Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows, then use [`rust/README.md`](./rust/README.md) for crate-level details.
+> The active Rust workspace now lives in [`rust/`](./rust). Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows, and make the doctor health check your first run: start `claw`, then run `/doctor`. Use [`rust/README.md`](./rust/README.md) for crate-level details.
 
 > Want the bigger idea behind this repo? Read [`PHILOSOPHY.md`](./PHILOSOPHY.md) and Sigrid Jin's public explanation: https://x.com/realsigridjin/status/2039472968624185713
 
@@ -57,6 +57,22 @@ https://x.com/realsigridjin/status/2039472968624185713
 
 ---
 
+## New user onboarding
+
+If you are here to try the Rust CLI, make the doctor check the first thing you run after building:
+
+```bash
+cd rust
+cargo build --workspace
+./target/debug/claw
+# first command inside the REPL
+/doctor
+```
+
+`/doctor` is the built-in setup and preflight diagnostic. After your first session, you can rerun the same health check with `./target/debug/claw --resume latest /doctor`.
+
+For the rest of the install, auth, session, and parity-harness workflow, continue in [`USAGE.md`](./USAGE.md).
+
 ## Porting Status
 
 The main source tree is now Python-first.
@@ -103,7 +119,7 @@ The new Python `src/` tree currently provides:
 - **`query_engine.py`** — renders a Python porting summary from the active workspace
 - **`main.py`** — a CLI entrypoint for manifest and summary output
 
-## Quickstart
+## Python workspace quickstart
 
 Render the Python porting summary:
 
diff --git a/USAGE.md b/USAGE.md
index f8232d6..24e142a 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -1,6 +1,20 @@
 # Claw Code Usage
 
-This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary.
+This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary. If you are brand new, make the doctor health check your first run: start `claw`, then run `/doctor`.
+
+## Quick-start health check
+
+Run this before prompts, sessions, or automation:
+
+```bash
+cd rust
+cargo build --workspace
+./target/debug/claw
+# first command inside the REPL
+/doctor
+```
+
+`/doctor` is the built-in setup and preflight diagnostic. Once you have a saved session, you can rerun it with `./target/debug/claw --resume latest /doctor`.
 
 ## Prerequisites
 
@@ -10,17 +24,25 @@ This guide covers the current Rust workspace under `rust/` and the `claw` CLI bi
   - `claw login` for OAuth-based auth
 - Optional: `ANTHROPIC_BASE_URL` when targeting a proxy or local service
 
-## Build the workspace
+## Install / build the workspace
 
 ```bash
 cd rust
 cargo build --workspace
 ```
 
-The CLI binary is available at `rust/target/debug/claw` after a debug build.
+The CLI binary is available at `rust/target/debug/claw` after a debug build. Make the doctor check above your first post-build step.
 
 ## Quick start
 
+### First-run doctor check
+
+```bash
+cd rust
+./target/debug/claw
+/doctor
+```
+
 ### Interactive REPL
 
 ```bash