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

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
-./target/release/claw
+# Build the workspace
+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
-./target/release/claw --model sonnet prompt "fix the bug in main.rs"
+# JSON output for automation
+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)
-  --version, -V                    Print version info
+  --output-format FORMAT           Non-interactive output format (text or json)
+  --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
-  self-update        Update to latest version
+  status             Show the current workspace status snapshot
+  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`