docs: rewrite rust/ README with full feature matrix and usage guide

rust/README.md

@@ -1,230 +1,149 @@
-# Rusty Claude CLI
+# 🦞 Claw Code — Rust Implementation
 
-`rust/` contains the Rust workspace for the integrated `rusty-claude-cli` deliverable.
-It is intended to be something you can clone, build, and run directly.
+A high-performance Rust rewrite of the Claude Code CLI agent harness. Built for speed, safety, and native tool execution.
 
-## Workspace layout
-
-```text
-rust/
-├── Cargo.toml
-├── Cargo.lock
-├── README.md
-└── crates/
-    ├── api/               # Anthropic API client + SSE streaming support
-    ├── commands/          # Shared slash-command metadata/help surfaces
-    ├── compat-harness/    # Upstream TS manifest extraction harness
-    ├── runtime/           # Session/runtime/config/prompt orchestration
-    ├── rusty-claude-cli/  # Main CLI binary
-    └── tools/             # Built-in tool implementations
-```
-
-## Prerequisites
-
-- Rust toolchain installed (`rustup`, stable toolchain)
-- Network access and Anthropic credentials for live prompt/REPL usage
-
-## Build
-
-From the repository root:
-
-```bash
-cd rust
-cargo build --release -p rusty-claude-cli
-```
-
-The optimized binary will be written to:
+## Quick Start
 
 ```bash
-./target/release/rusty-claude-cli
-```
+# Build
+cd rust/
+cargo build --release
 
-## Test
+# Run interactive REPL
+./target/release/claw
 
-Run the verified workspace test suite used for release-readiness:
+# One-shot prompt
+./target/release/claw prompt "explain this codebase"
 
-```bash
-cd rust
-cargo test --workspace --exclude compat-harness
+# With specific model
+./target/release/claw --model sonnet prompt "fix the bug in main.rs"
 ```
 
-## Quick start
+## Configuration
 
-### Show help
+Set your API credentials:
 
 ```bash
-cd rust
-cargo run -p rusty-claude-cli -- --help
+export ANTHROPIC_API_KEY="sk-ant-..."
+# Or use a proxy
+export ANTHROPIC_BASE_URL="https://your-proxy.com"
 ```
 
-### Print version
+Or authenticate via OAuth:
 
 ```bash
-cd rust
-cargo run -p rusty-claude-cli -- --version
-```
+claw login
+```
+
+## Features
+
+| Feature | Status |
+|---------|--------|
+| Anthropic API + streaming | ✅ |
+| OAuth login/logout | ✅ |
+| Interactive REPL (rustyline) | ✅ |
+| Tool system (bash, read, write, edit, grep, glob) | ✅ |
+| Web tools (search, fetch) | ✅ |
+| Sub-agent orchestration | ✅ |
+| Todo tracking | ✅ |
+| Notebook editing | ✅ |
+| CLAUDE.md / project memory | ✅ |
+| Config file hierarchy (.claude.json) | ✅ |
+| Permission system | ✅ |
+| MCP server lifecycle | ✅ |
+| Session persistence + resume | ✅ |
+| Extended thinking (thinking blocks) | ✅ |
+| Cost tracking + usage display | ✅ |
+| Git integration | ✅ |
+| Markdown terminal rendering (ANSI) | ✅ |
+| Model aliases (opus/sonnet/haiku) | ✅ |
+| Slash commands (/status, /compact, /clear, etc.) | ✅ |
+| Hooks (PreToolUse/PostToolUse) | 🔧 Config only |
+| Plugin system | 📋 Planned |
+| Skills registry | 📋 Planned |
+
+## Model Aliases
+
+Short names resolve to the latest model versions:
+
+| Alias | Resolves To |
+|-------|------------|
+| `opus` | `claude-opus-4-6` |
+| `sonnet` | `claude-sonnet-4-6` |
+| `haiku` | `claude-haiku-4-5-20251213` |
+
+## CLI Flags
+
+```
+claw [OPTIONS] [COMMAND]
+
+Options:
+  --model MODEL                    Set the model (alias or full name)
+  --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
+
+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
+```
+
+## Slash Commands (REPL)
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help |
+| `/status` | Show session status (model, tokens, cost) |
+| `/cost` | Show cost breakdown |
+| `/compact` | Compact conversation history |
+| `/clear` | Clear conversation |
+| `/model [name]` | Show or switch model |
+| `/permissions` | Show or switch permission mode |
+| `/config [section]` | Show config (env, hooks, model) |
+| `/memory` | Show CLAUDE.md contents |
+| `/diff` | Show git diff |
+| `/export [path]` | Export conversation |
+| `/session [id]` | Resume a previous session |
+| `/version` | Show version |
+
+## Workspace Layout
 
-### Login with OAuth
-
-Configure `settings.json` with an `oauth` block containing `clientId`, `authorizeUrl`, `tokenUrl`, optional `callbackPort`, and optional `scopes`, then run:
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- login
-```
-
-This opens the browser, listens on the configured localhost callback, exchanges the auth code for tokens, and stores OAuth credentials in `~/.claude/credentials.json` (or `$CLAUDE_CONFIG_HOME/credentials.json`).
-
-### Logout
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- logout
 ```
-
-This removes only the stored OAuth credentials and preserves unrelated JSON fields in `credentials.json`.
-
-### Self-update
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- self-update
-```
-
-The command checks the latest GitHub release for `instructkr/clawd-code`, compares it to the current binary version, downloads the matching binary asset plus checksum manifest, verifies SHA-256, replaces the current executable, and prints the release changelog. If no published release or matching asset exists, it exits safely with an explanatory message.
-
-## Usage examples
-
-### 1) Prompt mode
-
-Send one prompt, stream the answer, then exit:
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- prompt "Summarize the architecture of this repository"
-```
-
-Use a specific model:
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- --model claude-sonnet-4-20250514 prompt "List the key crates in this workspace"
-```
-
-Restrict enabled tools in an interactive session:
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- --allowedTools read,glob
-```
-
-Bootstrap Claude project files for the current repo:
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- init
-```
-
-### 2) REPL mode
-
-Start the interactive shell:
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli --
-```
-
-Inside the REPL, useful commands include:
-
-```text
-/help
-/status
-/model claude-sonnet-4-20250514
-/permissions workspace-write
-/cost
-/compact
-/memory
-/config
-/init
-/diff
-/version
-/export notes.txt
-/sessions
-/session list
-/exit
+rust/
+├── Cargo.toml              # Workspace root
+├── Cargo.lock
+└── crates/
+    ├── api/                # Anthropic API client + SSE streaming
+    ├── commands/           # Shared slash-command registry
+    ├── compat-harness/     # TS manifest extraction harness
+    ├── runtime/            # Session, config, permissions, MCP, prompts
+    ├── rusty-claude-cli/   # Main CLI binary (`claw`)
+    └── tools/              # Built-in tool implementations
 ```
 
-### 3) Resume an existing session
+### Crate Responsibilities
 
-Inspect or maintain a saved session file without entering the REPL:
+- **api** — HTTP client, SSE stream parser, request/response types, auth (API key + OAuth bearer)
+- **commands** — Slash command definitions and help text generation
+- **compat-harness** — Extracts tool/prompt manifests from upstream TS source
+- **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
+- **tools** — Tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, REPL runtimes
 
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- --resume session-123456 /status /compact /cost
-```
+## Stats
 
-You can also inspect memory/config state for a restored session:
+- **~20K lines** of Rust
+- **6 crates** in workspace
+- **Binary name:** `claw`
+- **Default model:** `claude-opus-4-6`
+- **Default permissions:** `danger-full-access`
 
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- --resume ~/.claude/sessions/session-123456.json /memory /config
-```
+## License
 
-## Available commands
-
-### Top-level CLI commands
-
-- `prompt <text...>` — run one prompt non-interactively
-- `--resume <session-id-or-path> [/commands...]` — inspect or maintain a saved session stored under `~/.claude/sessions/`
-- `dump-manifests` — print extracted upstream manifest counts
-- `bootstrap-plan` — print the current bootstrap skeleton
-- `system-prompt [--cwd PATH] [--date YYYY-MM-DD]` — render the synthesized system prompt
-- `self-update` — update the installed binary from the latest GitHub release when a matching asset is available
-- `--help` / `-h` — show CLI help
-- `--version` / `-V` — print the CLI version and build info locally (no API call)
-- `--output-format text|json` — choose non-interactive prompt output rendering
-- `--allowedTools <tool[,tool...]>` — restrict enabled tools for interactive sessions and prompt-mode tool use
-
-### Interactive slash commands
-
-- `/help` — show command help
-- `/status` — show current session status
-- `/compact` — compact local session history
-- `/model [model]` — inspect or switch the active model
-- `/permissions [read-only|workspace-write|danger-full-access]` — inspect or switch permissions
-- `/clear [--confirm]` — clear the current local session
-- `/cost` — show token usage totals
-- `/resume <session-id-or-path>` — load a saved session into the REPL
-- `/config [env|hooks|model]` — inspect discovered Claude config
-- `/memory` — inspect loaded instruction memory files
-- `/init` — bootstrap `.claude.json`, `.claude/`, `CLAUDE.md`, and local ignore rules
-- `/diff` — show the current git diff for the workspace
-- `/version` — print version and build metadata locally
-- `/export [file]` — export the current conversation transcript
-- `/sessions` — list recent managed local sessions from `~/.claude/sessions/`
-- `/session [list|switch <session-id>]` — inspect or switch managed local sessions
-- `/exit` — leave the REPL
-
-## Environment variables
-
-### Anthropic/API
-
-- `ANTHROPIC_API_KEY` — highest-precedence API credential
-- `ANTHROPIC_AUTH_TOKEN` — bearer-token override used when no API key is set
-- Persisted OAuth credentials in `~/.claude/credentials.json` — used when neither env var is set
-- `ANTHROPIC_BASE_URL` — override the Anthropic API base URL
-- `ANTHROPIC_MODEL` — default model used by selected live integration tests
-
-### CLI/runtime
-
-- `RUSTY_CLAUDE_PERMISSION_MODE` — default REPL permission mode (`read-only`, `workspace-write`, or `danger-full-access`)
-- `CLAUDE_CONFIG_HOME` — override Claude config discovery root
-- `CLAUDE_CODE_REMOTE` — enable remote-session bootstrap handling when supported
-- `CLAUDE_CODE_REMOTE_SESSION_ID` — remote session identifier when using remote mode
-- `CLAUDE_CODE_UPSTREAM` — override the upstream TS source path for compat-harness extraction
-- `CLAWD_WEB_SEARCH_BASE_URL` — override the built-in web search service endpoint used by tooling
-
-## Notes
-
-- `compat-harness` exists to compare the Rust port against the upstream TypeScript codebase and is intentionally excluded from the requested release test run.
-- The CLI currently focuses on a practical integrated workflow: prompt execution, REPL operation, session inspection/resume, config discovery, and tool/runtime plumbing.
+See repository root.