Promote doctor check in onboarding docs

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, use [`rust/README.md`](./rust/README.md) for crate-level details, and see [`docs/container.md`](./docs/container.md) for Docker/Podman container-first usage.
+> The active Rust workspace now lives in [`rust/`](./rust). Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows, make the doctor health check your first run, use [`rust/README.md`](./rust/README.md) for crate-level details, and see [`docs/container.md`](./docs/container.md) for Docker/Podman container-first usage.
 
 > 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:
 

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