docs: add a current claw CLI usage guide

The root and Rust-facing docs now point readers at a single task-oriented usage guide with build, auth, CLI, session, and parity-harness examples. This also fixes stale workspace references and updates the Rust workspace inventory to match the current crate set.

Constraint: Existing README copy still referenced the old dev/rust status and needed to stay lightweight
Rejected: Fold all usage details into README.md only | too much noise for the landing page
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep USAGE examples aligned with  when CLI flags change
Tested: cargo build --workspace; cargo test --workspace
Not-tested: External links and rendered Markdown in GitHub UI

README.md

@@ -27,7 +27,7 @@
 </p>
 
 > [!IMPORTANT]
-> **Rust port is now in progress** on the [`dev/rust`](https://github.com/instructkr/claw-code/tree/dev/rust) branch and is expected to be merged into main today. The Rust implementation aims to deliver a faster, memory-safe harness runtime. Stay tuned — this will be the definitive version of the project.
+> 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.
 
 > If you find this work useful, consider [sponsoring @instructkr on GitHub](https://github.com/sponsors/instructkr) to support continued open-source harness engineering research.
 

USAGE.md

@@ -0,0 +1,159 @@
+# Claw Code Usage
+
+This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary.
+
+## Prerequisites
+
+- Rust toolchain with `cargo`
+- One of:
+  - `ANTHROPIC_API_KEY` for direct API access
+  - `claw login` for OAuth-based auth
+- Optional: `ANTHROPIC_BASE_URL` when targeting a proxy or local service
+
+## Build the workspace
+
+```bash
+cd rust
+cargo build --workspace
+```
+
+The CLI binary is available at `rust/target/debug/claw` after a debug build.
+
+## Quick start
+
+### Interactive REPL
+
+```bash
+cd rust
+./target/debug/claw
+```
+
+### One-shot prompt
+
+```bash
+cd rust
+./target/debug/claw prompt "summarize this repository"
+```
+
+### Shorthand prompt mode
+
+```bash
+cd rust
+./target/debug/claw "explain rust/crates/runtime/src/lib.rs"
+```
+
+### JSON output for scripting
+
+```bash
+cd rust
+./target/debug/claw --output-format json prompt "status"
+```
+
+## Model and permission controls
+
+```bash
+cd rust
+./target/debug/claw --model sonnet prompt "review this diff"
+./target/debug/claw --permission-mode read-only prompt "summarize Cargo.toml"
+./target/debug/claw --permission-mode workspace-write prompt "update README.md"
+./target/debug/claw --allowedTools read,glob "inspect the runtime crate"
+```
+
+Supported permission modes:
+
+- `read-only`
+- `workspace-write`
+- `danger-full-access`
+
+Model aliases currently supported by the CLI:
+
+- `opus` → `claude-opus-4-6`
+- `sonnet` → `claude-sonnet-4-6`
+- `haiku` → `claude-haiku-4-5-20251213`
+
+## Authentication
+
+### API key
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+### OAuth
+
+```bash
+cd rust
+./target/debug/claw login
+./target/debug/claw logout
+```
+
+## Common operational commands
+
+```bash
+cd rust
+./target/debug/claw status
+./target/debug/claw sandbox
+./target/debug/claw agents
+./target/debug/claw mcp
+./target/debug/claw skills
+./target/debug/claw system-prompt --cwd .. --date 2026-04-04
+```
+
+## Session management
+
+REPL turns are persisted under `.claw/sessions/` in the current workspace.
+
+```bash
+cd rust
+./target/debug/claw --resume latest
+./target/debug/claw --resume latest /status /diff
+```
+
+Useful interactive commands include `/help`, `/status`, `/cost`, `/config`, `/session`, `/model`, `/permissions`, and `/export`.
+
+## Config file resolution order
+
+Runtime config is loaded in this order, with later entries overriding earlier ones:
+
+1. `~/.claw.json`
+2. `~/.config/claw/settings.json`
+3. `<repo>/.claw.json`
+4. `<repo>/.claw/settings.json`
+5. `<repo>/.claw/settings.local.json`
+
+## Mock parity harness
+
+The workspace includes a deterministic Anthropic-compatible mock service and parity harness.
+
+```bash
+cd rust
+./scripts/run_mock_parity_harness.sh
+```
+
+Manual mock service startup:
+
+```bash
+cd rust
+cargo run -p mock-anthropic-service -- --bind 127.0.0.1:0
+```
+
+## Verification
+
+```bash
+cd rust
+cargo test --workspace
+```
+
+## Workspace overview
+
+Current Rust crates:
+
+- `api`
+- `commands`
+- `compat-harness`
+- `mock-anthropic-service`
+- `plugins`
+- `runtime`
+- `rusty-claude-cli`
+- `telemetry`
+- `tools`

rust/README.md

@@ -2,21 +2,26 @@
 
 A high-performance Rust rewrite of the Claw Code CLI agent harness. Built for speed, safety, and native tool execution.
 
+For a task-oriented guide with copy/paste examples, see [`../USAGE.md`](../USAGE.md).
+
 ## Quick Start
 
 ```bash
-# Build
+# Inspect available commands
 cd rust/
-cargo build --release
+cargo run -p rusty-claude-cli -- --help
 
-# Run interactive REPL
+# Build the workspace
-./target/release/claw
+cargo build --workspace
+
+# Run the interactive REPL
+cargo run -p rusty-claude-cli -- --model claude-opus-4-6
 
 # One-shot prompt
-./target/release/claw prompt "explain this codebase"
+cargo run -p rusty-claude-cli -- prompt "explain this codebase"
 
-# With specific model
+# JSON output for automation
-./target/release/claw --model sonnet prompt "fix the bug in main.rs"
+cargo run -p rusty-claude-cli -- --output-format json prompt "summarize src/main.rs"
 ```
 
 ## Configuration
@@ -29,10 +34,10 @@ export ANTHROPIC_API_KEY="sk-ant-..."
 export ANTHROPIC_BASE_URL="https://your-proxy.com"
 ```
 
-Or authenticate via OAuth:
+Or authenticate via OAuth and let the CLI persist credentials locally:
 
 ```bash
-claw login
+cargo run -p rusty-claude-cli -- login
 ```
 
 ## Mock parity harness
@@ -113,25 +118,32 @@ Short names resolve to the latest model versions:
 claw [OPTIONS] [COMMAND]
 
 Options:
-  --model MODEL                    Set the model (alias or full name)
+  --model MODEL                    Override the active model
   --dangerously-skip-permissions   Skip all permission checks
   --permission-mode MODE           Set read-only, workspace-write, or danger-full-access
   --allowedTools TOOLS             Restrict enabled tools
-  --output-format FORMAT           Output format (text or json)
+  --output-format FORMAT           Non-interactive output format (text or json)
-  --version, -V                    Print version info
+  --resume SESSION                 Re-open a saved session or inspect it with slash commands
+  --version, -V                    Print version and build information locally
 
 Commands:
   prompt <text>      One-shot prompt (non-interactive)
   login              Authenticate via OAuth
   logout             Clear stored credentials
   init               Initialize project config
-  doctor             Check environment health
+  status             Show the current workspace status snapshot
-  self-update        Update to latest version
+  sandbox            Show the current sandbox isolation snapshot
+  agents             Inspect agent definitions
+  mcp                Inspect configured MCP servers
+  skills             Inspect installed skills
+  system-prompt      Render the assembled system prompt
 ```
 
+For the current canonical help text, run `cargo run -p rusty-claude-cli -- --help`.
+
 ## Slash Commands (REPL)
 
-Tab completion now expands not just slash command names, but also common workflow arguments like model aliases, permission modes, and recent session IDs.
+Tab completion expands slash commands, model aliases, permission modes, and recent session IDs.
 
 | Command | Description |
 |---------|-------------|
@@ -146,9 +158,12 @@ Tab completion now expands not just slash command names, but also common workflo
 | `/memory` | Show CLAUDE.md contents |
 | `/diff` | Show git diff |
 | `/export [path]` | Export conversation |
+| `/resume [id]` | Resume a saved conversation |
 | `/session [id]` | Resume a previous session |
 | `/version` | Show version |
 
+See [`../USAGE.md`](../USAGE.md) for examples covering interactive use, JSON automation, sessions, permissions, and the mock parity harness.
+
 ## Workspace Layout
 
 ```
@@ -160,8 +175,10 @@ rust/
     ├── commands/           # Shared slash-command registry
     ├── compat-harness/     # TS manifest extraction harness
     ├── mock-anthropic-service/ # Deterministic local Anthropic-compatible mock
+    ├── plugins/            # Plugin registry and hook wiring primitives
     ├── runtime/            # Session, config, permissions, MCP, prompts
     ├── rusty-claude-cli/   # Main CLI binary (`claw`)
+    ├── telemetry/          # Session tracing and usage telemetry types
     └── tools/              # Built-in tool implementations
 ```
 
@@ -171,14 +188,16 @@ rust/
 - **commands** — Slash command definitions and help text generation
 - **compat-harness** — Extracts tool/prompt manifests from upstream TS source
 - **mock-anthropic-service** — Deterministic `/v1/messages` mock for CLI parity tests and local harness runs
+- **plugins** — Plugin metadata, registries, and hook integration surfaces
 - **runtime** — `ConversationRuntime` agentic loop, `ConfigLoader` hierarchy, `Session` persistence, permission policy, MCP client, system prompt assembly, usage tracking
 - **rusty-claude-cli** — REPL, one-shot prompt, streaming display, tool call rendering, CLI argument parsing
+- **telemetry** — Session trace events and supporting telemetry payloads
 - **tools** — Tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, REPL runtimes
 
 ## Stats
 
 - **~20K lines** of Rust
-- **7 crates** in workspace
+- **9 crates** in workspace
 - **Binary name:** `claw`
 - **Default model:** `claude-opus-4-6`
 - **Default permissions:** `danger-full-access`

rust/USAGE.md

@@ -0,0 +1,11 @@
+# Rust usage guide
+
+The canonical task-oriented usage guide lives at [`../USAGE.md`](../USAGE.md).
+
+Use that guide for:
+
+- workspace build and test commands
+- authentication setup
+- interactive and one-shot `claw` examples
+- session resume workflows
+- mock parity harness commands