docs: README, CI workflow, CLAW.md guidance, assets, and contributing guide

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: instructkr

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+archive/
+.omx/
+.clawd-agents/
+# Claude Code local artifacts
+.claude/settings.local.json
+.claude/sessions/

CLAW.md

@@ -0,0 +1,21 @@
+# CLAW.md
+
+This file provides guidance to Claw Code when working with code in this repository.
+
+## Detected stack
+- Languages: Rust.
+- Frameworks: none detected from the supported starter markers.
+
+## Verification
+- Run Rust verification from `rust/`: `cargo fmt`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace`
+- `src/` and `tests/` are both present; update both surfaces together when behavior changes.
+
+## Repository shape
+- `rust/` contains the Rust workspace and active CLI/runtime implementation.
+- `src/` contains source files that should stay consistent with generated guidance and tests.
+- `tests/` contains validation surfaces that should be reviewed alongside code changes.
+
+## Working agreement
+- Prefer small, reviewable changes and keep generated bootstrap files aligned with actual repo workflows.
+- Keep shared defaults in `.claw.json`; reserve `.claw/settings.local.json` for machine-local overrides.
+- Do not overwrite existing `CLAW.md` content automatically; update it intentionally when repo workflows change.

PARITY.md

@@ -0,0 +1,214 @@
+# PARITY GAP ANALYSIS
+
+Scope: read-only comparison between the original TypeScript source at `/home/bellman/Workspace/claw-code/src/` and the Rust port under `rust/crates/`.
+
+Method: compared feature surfaces, registries, entrypoints, and runtime plumbing only. No TypeScript source was copied.
+
+## Executive summary
+
+The Rust port has a good foundation for:
+- Anthropic API/OAuth basics
+- local conversation/session state
+- a core tool loop
+- MCP stdio/bootstrap support
+- CLAW.md discovery
+- a small but usable built-in tool set
+
+It is **not feature-parity** with the TypeScript CLI.
+
+Largest gaps:
+- **plugins** are effectively absent in Rust
+- **hooks** are parsed but not executed in Rust
+- **CLI breadth** is much narrower in Rust
+- **skills** are local-file only in Rust, without the TS registry/bundled pipeline
+- **assistant orchestration** lacks TS hook-aware orchestration and remote/structured transports
+- **services** beyond core API/OAuth/MCP are mostly missing in Rust
+
+---
+
+## tools/
+
+### TS exists
+Evidence:
+- `src/tools/` contains broad tool families including `AgentTool`, `AskUserQuestionTool`, `BashTool`, `ConfigTool`, `FileReadTool`, `FileWriteTool`, `GlobTool`, `GrepTool`, `LSPTool`, `ListMcpResourcesTool`, `MCPTool`, `McpAuthTool`, `ReadMcpResourceTool`, `RemoteTriggerTool`, `ScheduleCronTool`, `SkillTool`, `Task*`, `Team*`, `TodoWriteTool`, `ToolSearchTool`, `WebFetchTool`, `WebSearchTool`.
+- Tool execution/orchestration is split across `src/services/tools/StreamingToolExecutor.ts`, `src/services/tools/toolExecution.ts`, `src/services/tools/toolHooks.ts`, and `src/services/tools/toolOrchestration.ts`.
+
+### Rust exists
+Evidence:
+- Tool registry is centralized in `rust/crates/tools/src/lib.rs` via `mvp_tool_specs()`.
+- Current built-ins include shell/file/search/web/todo/skill/agent/config/notebook/repl/powershell primitives.
+- Runtime execution is wired through `rust/crates/tools/src/lib.rs` and `rust/crates/runtime/src/conversation.rs`.
+
+### Missing or broken in Rust
+- No Rust equivalents for major TS tools such as `AskUserQuestionTool`, `LSPTool`, `ListMcpResourcesTool`, `MCPTool`, `McpAuthTool`, `ReadMcpResourceTool`, `RemoteTriggerTool`, `ScheduleCronTool`, `Task*`, `Team*`, and several workflow/system tools.
+- Rust tool surface is still explicitly an MVP registry, not a parity registry.
+- Rust lacks TS’s layered tool orchestration split.
+
+**Status:** partial core only.
+
+---
+
+## hooks/
+
+### TS exists
+Evidence:
+- Hook command surface under `src/commands/hooks/`.
+- Runtime hook machinery in `src/services/tools/toolHooks.ts` and `src/services/tools/toolExecution.ts`.
+- TS supports `PreToolUse`, `PostToolUse`, and broader hook-driven behaviors configured through settings and documented in `src/skills/bundled/updateConfig.ts`.
+
+### Rust exists
+Evidence:
+- Hook config is parsed and merged in `rust/crates/runtime/src/config.rs`.
+- Hook config can be inspected via Rust config reporting in `rust/crates/commands/src/lib.rs` and `rust/crates/claw-cli/src/main.rs`.
+- Prompt guidance mentions hooks in `rust/crates/runtime/src/prompt.rs`.
+
+### Missing or broken in Rust
+- No actual hook execution pipeline in `rust/crates/runtime/src/conversation.rs`.
+- No PreToolUse/PostToolUse mutation/deny/rewrite/result-hook behavior.
+- No Rust `/hooks` parity command.
+
+**Status:** config-only; runtime behavior missing.
+
+---
+
+## plugins/
+
+### TS exists
+Evidence:
+- Built-in plugin scaffolding in `src/plugins/builtinPlugins.ts` and `src/plugins/bundled/index.ts`.
+- Plugin lifecycle/services in `src/services/plugins/PluginInstallationManager.ts` and `src/services/plugins/pluginOperations.ts`.
+- CLI/plugin command surface under `src/commands/plugin/` and `src/commands/reload-plugins/`.
+
+### Rust exists
+Evidence:
+- No dedicated plugin subsystem appears under `rust/crates/`.
+- Repo-wide Rust references to plugins are effectively absent beyond text/help mentions.
+
+### Missing or broken in Rust
+- No plugin loader.
+- No marketplace install/update/enable/disable flow.
+- No `/plugin` or `/reload-plugins` parity.
+- No plugin-provided hook/tool/command/MCP extension path.
+
+**Status:** missing.
+
+---
+
+## skills/ and CLAW.md discovery
+
+### TS exists
+Evidence:
+- Skill loading/registry pipeline in `src/skills/loadSkillsDir.ts`, `src/skills/bundledSkills.ts`, and `src/skills/mcpSkillBuilders.ts`.
+- Bundled skills under `src/skills/bundled/`.
+- Skills command surface under `src/commands/skills/`.
+
+### Rust exists
+Evidence:
+- `Skill` tool in `rust/crates/tools/src/lib.rs` resolves and reads local `SKILL.md` files.
+- CLAW.md discovery is implemented in `rust/crates/runtime/src/prompt.rs`.
+- Rust supports `/memory` and `/init` via `rust/crates/commands/src/lib.rs` and `rust/crates/claw-cli/src/main.rs`.
+
+### Missing or broken in Rust
+- No bundled skill registry equivalent.
+- No `/skills` command.
+- No MCP skill-builder pipeline.
+- No TS-style live skill discovery/reload/change handling.
+- No comparable session-memory / team-memory integration around skills.
+
+**Status:** basic local skill loading only.
+
+---
+
+## cli/
+
+### TS exists
+Evidence:
+- Large command surface under `src/commands/` including `agents`, `hooks`, `mcp`, `memory`, `model`, `permissions`, `plan`, `plugin`, `resume`, `review`, `skills`, `tasks`, and many more.
+- Structured/remote transport stack in `src/cli/structuredIO.ts`, `src/cli/remoteIO.ts`, and `src/cli/transports/*`.
+- CLI handler split in `src/cli/handlers/*`.
+
+### Rust exists
+Evidence:
+- Shared slash command registry in `rust/crates/commands/src/lib.rs`.
+- Rust slash commands currently cover `help`, `status`, `compact`, `model`, `permissions`, `clear`, `cost`, `resume`, `config`, `memory`, `init`, `diff`, `version`, `export`, `session`.
+- Main CLI/repl/prompt handling lives in `rust/crates/claw-cli/src/main.rs`.
+
+### Missing or broken in Rust
+- Missing major TS command families: `/agents`, `/hooks`, `/mcp`, `/plugin`, `/skills`, `/plan`, `/review`, `/tasks`, and many others.
+- No Rust equivalent to TS structured IO / remote transport layers.
+- No TS-style handler decomposition for auth/plugins/MCP/agents.
+- JSON prompt mode is improved on this branch, but still not clean transport parity: empirical verification shows tool-capable JSON output can emit human-readable tool-result lines before the final JSON object.
+
+**Status:** functional local CLI core, much narrower than TS.
+
+---
+
+## assistant/ (agentic loop, streaming, tool calling)
+
+### TS exists
+Evidence:
+- Assistant/session surface at `src/assistant/sessionHistory.ts`.
+- Tool orchestration in `src/services/tools/StreamingToolExecutor.ts`, `src/services/tools/toolExecution.ts`, `src/services/tools/toolOrchestration.ts`.
+- Remote/structured streaming layers in `src/cli/structuredIO.ts` and `src/cli/remoteIO.ts`.
+
+### Rust exists
+Evidence:
+- Core loop in `rust/crates/runtime/src/conversation.rs`.
+- Stream/tool event translation in `rust/crates/claw-cli/src/main.rs`.
+- Session persistence in `rust/crates/runtime/src/session.rs`.
+
+### Missing or broken in Rust
+- No TS-style hook-aware orchestration layer.
+- No TS structured/remote assistant transport stack.
+- No richer TS assistant/session-history/background-task integration.
+- JSON output path is no longer single-turn only on this branch, but output cleanliness still lags TS transport expectations.
+
+**Status:** strong core loop, missing orchestration layers.
+
+---
+
+## services/ (API client, auth, models, MCP)
+
+### TS exists
+Evidence:
+- API services under `src/services/api/*`.
+- OAuth services under `src/services/oauth/*`.
+- MCP services under `src/services/mcp/*`.
+- Additional service layers for analytics, prompt suggestion, session memory, plugin operations, settings sync, policy limits, team memory sync, notifier, voice, and more under `src/services/*`.
+
+### Rust exists
+Evidence:
+- Core Anthropic API client in `rust/crates/api/src/{client,error,sse,types}.rs`.
+- OAuth support in `rust/crates/runtime/src/oauth.rs`.
+- MCP config/bootstrap/client support in `rust/crates/runtime/src/{config,mcp,mcp_client,mcp_stdio}.rs`.
+- Usage accounting in `rust/crates/runtime/src/usage.rs`.
+- Remote upstream-proxy support in `rust/crates/runtime/src/remote.rs`.
+
+### Missing or broken in Rust
+- Most TS service ecosystem beyond core messaging/auth/MCP is absent.
+- No TS-equivalent plugin service layer.
+- No TS-equivalent analytics/settings-sync/policy-limit/team-memory subsystems.
+- No TS-style MCP connection-manager/UI layer.
+- Model/provider ergonomics remain thinner than TS.
+
+**Status:** core foundation exists; broader service ecosystem missing.
+
+---
+
+## Critical bug status in this worktree
+
+### Fixed
+- **Prompt mode tools enabled**
+  - `rust/crates/claw-cli/src/main.rs` now constructs prompt mode with `LiveCli::new(model, true, ...)`.
+- **Default permission mode = DangerFullAccess**
+  - Runtime default now resolves to `DangerFullAccess` in `rust/crates/claw-cli/src/main.rs`.
+  - Clap default also uses `DangerFullAccess` in `rust/crates/claw-cli/src/args.rs`.
+  - Init template writes `dontAsk` in `rust/crates/claw-cli/src/init.rs`.
+- **Streaming `{}` tool-input prefix bug**
+  - `rust/crates/claw-cli/src/main.rs` now strips the initial empty object only for streaming tool input, while preserving legitimate `{}` in non-stream responses.
+- **Unlimited max_iterations**
+  - Verified at `rust/crates/runtime/src/conversation.rs` with `usize::MAX`.
+
+### Remaining notable parity issue
+- **JSON prompt output cleanliness**
+  - Tool-capable JSON mode now loops, but empirical verification still shows pre-JSON human-readable tool-result output when tools fire.

README.md

@@ -0,0 +1,191 @@
+# Rewriting Project Claw Code
+
+<p align="center">
+  <strong>⭐ The fastest repo in history to surpass 50K stars, reaching the milestone in just 2 hours after publication ⭐</strong>
+</p>
+
+<p align="center">
+  <a href="https://star-history.com/#instructkr/claw-code&Date">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=instructkr/claw-code&type=Date&theme=dark" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=instructkr/claw-code&type=Date" />
+      <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=instructkr/claw-code&type=Date" width="600" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <img src="assets/clawd-hero.jpeg" alt="Claw" width="300" />
+</p>
+
+<p align="center">
+  <strong>Better Harness Tools, not merely storing the archive of leaked Claw Code</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/sponsors/instructkr"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github&style=for-the-badge" alt="Sponsor on GitHub" /></a>
+</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.
+
+> If you find this work useful, consider [sponsoring @instructkr on GitHub](https://github.com/sponsors/instructkr) to support continued open-source harness engineering research.
+
+---
+
+## Backstory
+
+At 4 AM on March 31, 2026, I woke up to my phone blowing up with notifications. The Claw Code source had been exposed, and the entire dev community was in a frenzy. My girlfriend in Korea was genuinely worried I might face legal action from the original authors just for having the code on my machine — so I did what any engineer would do under pressure: I sat down, ported the core features to Python from scratch, and pushed it before the sun came up.
+
+The whole thing was orchestrated end-to-end using [oh-my-codex (OmX)](https://github.com/Yeachan-Heo/oh-my-codex) by [@bellman_ych](https://x.com/bellman_ych) — a workflow layer built on top of OpenAI's Codex ([@OpenAIDevs](https://x.com/OpenAIDevs)). I used `$team` mode for parallel code review and `$ralph` mode for persistent execution loops with architect-level verification. The entire porting session — from reading the original harness structure to producing a working Python tree with tests — was driven through OmX orchestration.
+
+The result is a clean-room Python rewrite that captures the architectural patterns of Claw Code's agent harness without copying any proprietary source. I'm now actively collaborating with [@bellman_ych](https://x.com/bellman_ych) — the creator of OmX himself — to push this further. The basic Python foundation is already in place and functional, but we're just getting started. **Stay tuned — a much more capable version is on the way.**
+
+https://github.com/instructkr/claw-code
+
+![Tweet screenshot](assets/tweet-screenshot.png)
+
+## The Creators Featured in Wall Street Journal For Avid Claw Code Fans
+
+I've been deeply interested in **harness engineering** — studying how agent systems wire tools, orchestrate tasks, and manage runtime context. This isn't a sudden thing. The Wall Street Journal featured my work earlier this month, documenting how I've been one of the most active power users exploring these systems:
+
+> AI startup worker Sigrid Jin, who attended the Seoul dinner, single-handedly used 25 billion of Claw Code tokens last year. At the time, usage limits were looser, allowing early enthusiasts to reach tens of billions of tokens at a very low cost.
+>
+> Despite his countless hours with Claw Code, Jin isn't faithful to any one AI lab. The tools available have different strengths and weaknesses, he said. Codex is better at reasoning, while Claw Code generates cleaner, more shareable code.
+>
+> Jin flew to San Francisco in February for Claw Code's first birthday party, where attendees waited in line to compare notes with Cherny. The crowd included a practicing cardiologist from Belgium who had built an app to help patients navigate care, and a California lawyer who made a tool for automating building permit approvals using Claw Code.
+>
+> "It was basically like a sharing party," Jin said. "There were lawyers, there were doctors, there were dentists. They did not have software engineering backgrounds."
+>
+> — *The Wall Street Journal*, March 21, 2026, [*"The Trillion Dollar Race to Automate Our Entire Lives"*](https://lnkd.in/gs9td3qd)
+
+![WSJ Feature](assets/wsj-feature.png)
+
+---
+
+## Porting Status
+
+The main source tree is now Python-first.
+
+- `src/` contains the active Python porting workspace
+- `tests/` verifies the current Python workspace
+- the exposed snapshot is no longer part of the tracked repository state
+
+The current Python workspace is not yet a complete one-to-one replacement for the original system, but the primary implementation surface is now Python.
+
+## Why this rewrite exists
+
+I originally studied the exposed codebase to understand its harness, tool wiring, and agent workflow. After spending more time with the legal and ethical questions—and after reading the essay linked below—I did not want the exposed snapshot itself to remain the main tracked source tree.
+
+This repository now focuses on Python porting work instead.
+
+## Repository Layout
+
+```text
+.
+├── src/                                # Python porting workspace
+│   ├── __init__.py
+│   ├── commands.py
+│   ├── main.py
+│   ├── models.py
+│   ├── port_manifest.py
+│   ├── query_engine.py
+│   ├── task.py
+│   └── tools.py
+├── tests/                              # Python verification
+├── assets/omx/                         # OmX workflow screenshots
+├── 2026-03-09-is-legal-the-same-as-legitimate-ai-reimplementation-and-the-erosion-of-copyleft.md
+└── README.md
+```
+
+## Python Workspace Overview
+
+The new Python `src/` tree currently provides:
+
+- **`port_manifest.py`** — summarizes the current Python workspace structure
+- **`models.py`** — dataclasses for subsystems, modules, and backlog state
+- **`commands.py`** — Python-side command port metadata
+- **`tools.py`** — Python-side tool port metadata
+- **`query_engine.py`** — renders a Python porting summary from the active workspace
+- **`main.py`** — a CLI entrypoint for manifest and summary output
+
+## Quickstart
+
+Render the Python porting summary:
+
+```bash
+python3 -m src.main summary
+```
+
+Print the current Python workspace manifest:
+
+```bash
+python3 -m src.main manifest
+```
+
+List the current Python modules:
+
+```bash
+python3 -m src.main subsystems --limit 16
+```
+
+Run verification:
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Run the parity audit against the local ignored archive (when present):
+
+```bash
+python3 -m src.main parity-audit
+```
+
+Inspect mirrored command/tool inventories:
+
+```bash
+python3 -m src.main commands --limit 10
+python3 -m src.main tools --limit 10
+```
+
+## Current Parity Checkpoint
+
+The port now mirrors the archived root-entry file surface, top-level subsystem names, and command/tool inventories much more closely than before. However, it is **not yet** a full runtime-equivalent replacement for the original TypeScript system; the Python tree still contains fewer executable runtime slices than the archived source.
+
+
+## Built with `oh-my-codex`
+
+The restructuring and documentation work on this repository was AI-assisted and orchestrated with Yeachan Heo's [oh-my-codex (OmX)](https://github.com/Yeachan-Heo/oh-my-codex), layered on top of Codex.
+
+- **`$team` mode:** used for coordinated parallel review and architectural feedback
+- **`$ralph` mode:** used for persistent execution, verification, and completion discipline
+- **Codex-driven workflow:** used to turn the main `src/` tree into a Python-first porting workspace
+
+### OmX workflow screenshots
+
+![OmX workflow screenshot 1](assets/omx/omx-readme-review-1.png)
+
+*Ralph/team orchestration view while the README and essay context were being reviewed in terminal panes.*
+
+![OmX workflow screenshot 2](assets/omx/omx-readme-review-2.png)
+
+*Split-pane review and verification flow during the final README wording pass.*
+
+## Community
+
+<p align="center">
+  <a href="https://instruct.kr/"><img src="assets/instructkr.png" alt="instructkr" width="400" /></a>
+</p>
+
+Join the [**instructkr Discord**](https://instruct.kr/) — the best Korean language model community. Come chat about LLMs, harness engineering, agent workflows, and everything in between.
+
+[![Discord](https://img.shields.io/badge/Join%20Discord-instruct.kr-5865F2?logo=discord&style=for-the-badge)](https://instruct.kr/)
+
+## Star History
+
+See the chart at the top of this README.
+
+## Ownership / Affiliation Disclaimer
+
+- This repository does **not** claim ownership of the original Claw Code source material.
+- This repository is **not affiliated with, endorsed by, or maintained by the original authors**.

rust/.gitignore

@@ -0,0 +1,3 @@
+target/
+.omx/
+.clawd-agents/

rust/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Thanks for contributing to Claw Code.
+
+## Development setup
+
+- Install the stable Rust toolchain.
+- Work from the repository root in this Rust workspace. If you started from the parent repo root, `cd rust/` first.
+
+## Build
+
+```bash
+cargo build
+cargo build --release
+```
+
+## Test and verify
+
+Run the full Rust verification set before you open a pull request:
+
+```bash
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo check --workspace
+cargo test --workspace
+```
+
+If you change behavior, add or update the relevant tests in the same pull request.
+
+## Code style
+
+- Follow the existing patterns in the touched crate instead of introducing a new style.
+- Format code with `rustfmt`.
+- Keep `clippy` clean for the workspace targets you changed.
+- Prefer focused diffs over drive-by refactors.
+
+## Pull requests
+
+- Branch from `main`.
+- Keep each pull request scoped to one clear change.
+- Explain the motivation, the implementation summary, and the verification you ran.
+- Make sure local checks pass before requesting review.
+- If review feedback changes behavior, rerun the relevant verification commands.

rust/Cargo.toml

@@ -0,0 +1,22 @@
+[workspace]
+members = ["crates/*"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+publish = false
+
+[workspace.dependencies]
+serde_json = "1"
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+module_name_repetitions = "allow"
+missing_panics_doc = "allow"
+missing_errors_doc = "allow"

rust/README.md

@@ -0,0 +1,149 @@
+# 🦞 Claw Code — Rust Implementation
+
+A high-performance Rust rewrite of the Claw Code CLI agent harness. Built for speed, safety, and native tool execution.
+
+## Quick Start
+
+```bash
+# Build
+cd rust/
+cargo build --release
+
+# Run interactive REPL
+./target/release/claw
+
+# One-shot prompt
+./target/release/claw prompt "explain this codebase"
+
+# With specific model
+./target/release/claw --model sonnet prompt "fix the bug in main.rs"
+```
+
+## Configuration
+
+Set your API credentials:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+# Or use a proxy
+export ANTHROPIC_BASE_URL="https://your-proxy.com"
+```
+
+Or authenticate via OAuth:
+
+```bash
+claw login
+```
+
+## Features
+
+| Feature | Status |
+|---------|--------|
+| 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 | ✅ |
+| CLAW.md / project memory | ✅ |
+| Config file hierarchy (.claw.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 CLAW.md contents |
+| `/diff` | Show git diff |
+| `/export [path]` | Export conversation |
+| `/session [id]` | Resume a previous session |
+| `/version` | Show version |
+
+## Workspace Layout
+
+```
+rust/
+├── Cargo.toml              # Workspace root
+├── Cargo.lock
+└── crates/
+    ├── api/                # API client + SSE streaming
+    ├── commands/           # Shared slash-command registry
+    ├── compat-harness/     # TS manifest extraction harness
+    ├── runtime/            # Session, config, permissions, MCP, prompts
+    ├── claw-cli/   # Main CLI binary (`claw`)
+    └── tools/              # Built-in tool implementations
+```
+
+### Crate Responsibilities
+
+- **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
+- **claw-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
+
+## Stats
+
+- **~20K lines** of Rust
+- **6 crates** in workspace
+- **Binary name:** `claw`
+- **Default model:** `claude-opus-4-6`
+- **Default permissions:** `danger-full-access`
+
+## License
+
+See repository root.