diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md
index 7c7d338f..543b1f54 100644
--- a/.github/ISSUE_TEMPLATE/question.md
+++ b/.github/ISSUE_TEMPLATE/question.md
@@ -9,7 +9,7 @@ assignees: ''
## ⚠️ 提交前确认
- [ ] 我已经仔细阅读了 [README 常见问题](https://github.com/NanmiCoder/cc-haha#常见问题) 部分
-- [ ] 我已经阅读了[第三方模型使用指南](https://github.com/NanmiCoder/cc-haha/blob/main/docs/third-party-models.md)
+- [ ] 我已经阅读了[第三方模型使用指南](https://github.com/NanmiCoder/cc-haha/blob/main/docs/guide/third-party-models.md)
- [ ] 我已经搜索并查看了[已关闭的 issues](https://github.com/NanmiCoder/cc-haha/issues?q=is%3Aissue+is%3Aclosed)
## ❓ 问题描述
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 00000000..198f0ce8
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,38 @@
+DISCLAIMER AND LICENSE
+
+Copyright (c) 2026 Anthropic, PBC. All rights reserved for the original source code.
+
+This repository is based on the Claude Code source code leaked from the Anthropic
+npm registry on 2026-03-31. All original source code copyrights belong to Anthropic.
+
+THIS SOFTWARE IS PROVIDED FOR EDUCATIONAL AND RESEARCH PURPOSES ONLY.
+
+The purpose of this repository is to facilitate the study and research of AI Agent
+engineering, including but not limited to:
+- Agent architecture and design patterns
+- Tool use and function calling mechanisms
+- Multi-agent orchestration
+- Terminal UI (TUI) implementation for AI applications
+- MCP (Model Context Protocol) integration
+
+RESTRICTIONS:
+
+1. This software SHALL NOT be used for any commercial purposes.
+2. This software SHALL NOT be used to compete with or replicate Anthropic's
+ commercial products or services.
+3. This software SHALL NOT be redistributed, sublicensed, or sold in any form.
+4. Users SHALL comply with all applicable laws and regulations in their jurisdiction.
+
+NO WARRANTY:
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+By using this software, you acknowledge that:
+- You understand this is leaked source code and all original rights belong to Anthropic.
+- You will use it solely for learning and research of Agent engineering.
+- You assume all legal risks and responsibilities arising from the use of this software.
diff --git a/README.en.md b/README.en.md
index d2e608e7..2db41e03 100644
--- a/README.en.md
+++ b/README.en.md
@@ -1,28 +1,28 @@
# Claude Code Haha
-中文 | English
+
+
+[](https://github.com/NanmiCoder/cc-haha/stargazers)
+[](https://github.com/NanmiCoder/cc-haha/network/members)
+[](https://github.com/NanmiCoder/cc-haha/issues)
+[](https://github.com/NanmiCoder/cc-haha/pulls)
+[](https://github.com/NanmiCoder/cc-haha/blob/main/LICENSE)
+[](README.md)
+[](README.en.md)
+
+
A **locally runnable version** repaired from the leaked Claude Code source, with support for any Anthropic-compatible API endpoint such as MiniMax and OpenRouter.
> The original leaked source does not run as-is. This repository fixes multiple blocking issues in the startup path so the full Ink TUI can work locally.
- 
+ 
-## Table of Contents
-
-- [Features](#features)
-- [Architecture Overview](#architecture-overview)
-- [Quick Start](#quick-start)
-- [Environment Variables](#environment-variables)
-- [Fallback Mode](#fallback-mode)
-- [Computer Use Desktop Control](#computer-use-desktop-control)
-- [Memory System](#memory-system)
-- [FAQ](#faq)
-- [Fixes Compared with the Original Leaked Source](#fixes-compared-with-the-original-leaked-source)
-- [Project Structure](#project-structure)
-- [Tech Stack](#tech-stack)
+
+ Features · Architecture · Quick Start · Env Vars · FAQ · Global Usage · More Docs
+
---
@@ -31,12 +31,10 @@ A **locally runnable version** repaired from the leaked Claude Code source, with
- Full Ink TUI experience (matching the official Claude Code interface)
- `--print` headless mode for scripts and CI
- MCP server, plugin, and Skills support
-- Custom API endpoint and model support ([Third-Party Models Guide](docs/third-party-models.en.md))
-- **Computer Use desktop control** (screenshots, mouse, keyboard, app management) — [Guide](docs/computer-use.en.md)
-- **Memory System** (cross-session persistent memory with auto-extraction and smart retrieval) — [Usage Guide](docs/memory/01-usage-guide.md) | [Implementation](docs/memory/02-implementation.md)
-- Fallback Recovery CLI mode
-
-> **Computer Use Note**: This project includes a **modified version of Computer Use**. The official implementation relies on Anthropic's private native modules. We replaced the entire underlying operation layer with a Python bridge (`pyautogui` + `mss` + `pyobjc`), enabling anyone to use Computer Use on macOS. See the [Computer Use Guide](docs/computer-use.en.md) for details.
+- Custom API endpoint and model support ([Third-Party Models Guide](docs/guide/third-party-models.en.md))
+- **Computer Use desktop control** — [Guide](docs/features/computer-use.en.md)
+- **Memory System** (cross-session persistent memory) — [Usage Guide](docs/memory/01-usage-guide.md)
+- Fallback Recovery CLI mode (`CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha`)
---
@@ -44,16 +42,16 @@ A **locally runnable version** repaired from the leaked Claude Code source, with
- 
Overall architecture |
- 
Request lifecycle |
- 
Tool system |
- 
Multi-agent architecture |
+ 
Overall architecture |
+ 
Request lifecycle |
+ 
Tool system |
+ 
Multi-agent architecture |
- 
Terminal UI |
- 
Permissions and security |
- 
Services layer |
- 
State and data flow |
+ 
Terminal UI |
+ 
Permissions and security |
+ 
Services layer |
+ 
State and data flow |
@@ -63,238 +61,55 @@ A **locally runnable version** repaired from the leaked Claude Code source, with
### 1. Install Bun
-This project requires [Bun](https://bun.sh). If Bun is not installed on the target machine yet, use one of the following methods first:
-
```bash
-# macOS / Linux (official install script)
+# macOS / Linux
curl -fsSL https://bun.sh/install | bash
-```
-If a minimal Linux image reports `unzip is required to install bun`, install `unzip` first:
-
-```bash
-# Ubuntu / Debian
-apt update && apt install -y unzip
-```
-
-```bash
# macOS (Homebrew)
brew install bun
-```
-```powershell
# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"
```
-After installation, reopen the terminal and verify:
+> On minimal Linux images, if you see `unzip is required`, run `apt update && apt install -y unzip` first.
-```bash
-bun --version
-```
-
-### 2. Install project dependencies
+### 2. Install Dependencies and Configure
```bash
bun install
-```
-
-### 3. Configure environment variables
-
-Copy the example file and fill in your API key:
-
-```bash
cp .env.example .env
+# Edit .env with your API key — see docs/guide/env-vars.en.md for details
```
-Edit `.env` (the example below uses [MiniMax](https://platform.minimaxi.com/subscribe/token-plan?code=1TG2Cseab2&source=link) as the API provider — you can replace it with any compatible service):
-
-```env
-# API authentication (choose one)
-ANTHROPIC_API_KEY=sk-xxx # Standard API key via x-api-key header
-ANTHROPIC_AUTH_TOKEN=sk-xxx # Bearer token via Authorization header
-
-# API endpoint (optional, defaults to Anthropic)
-ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
-
-# Model configuration
-ANTHROPIC_MODEL=MiniMax-M2.7-highspeed
-ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.7-highspeed
-ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.7-highspeed
-ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.7-highspeed
-
-# Timeout in milliseconds
-API_TIMEOUT_MS=3000000
-
-# Disable telemetry and non-essential network traffic
-DISABLE_TELEMETRY=1
-CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
-```
-
-> **Tip**: You can also configure environment variables via the `env` field in `~/.claude/settings.json`. This is consistent with the official Claude Code configuration:
->
-> ```json
-> {
-> "env": {
-> "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
-> "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
-> "ANTHROPIC_MODEL": "MiniMax-M2.7-highspeed"
-> }
-> }
-> ```
->
-> Priority: Environment variables > `.env` file > `~/.claude/settings.json`
-
-### 4. Start
+### 3. Start
#### macOS / Linux
```bash
-# Interactive TUI mode (full interface)
-./bin/claude-haha
-
-# Headless mode (single prompt)
-./bin/claude-haha -p "your prompt here"
-
-# Pipe input
-echo "explain this code" | ./bin/claude-haha -p
-
-# Show all options
-./bin/claude-haha --help
+./bin/claude-haha # Interactive TUI mode
+./bin/claude-haha -p "your prompt here" # Headless mode
+./bin/claude-haha --help # Show all options
```
#### Windows
-> **Prerequisite**: [Git for Windows](https://git-scm.com/download/win) must be installed (provides Git Bash, which the project's internal shell execution depends on).
-
-The startup script `bin/claude-haha` is a bash script and cannot run directly in cmd or PowerShell. Use one of the following methods:
-
-**Option 1: PowerShell / cmd — call Bun directly (recommended)**
+> **Prerequisite**: [Git for Windows](https://git-scm.com/download/win) must be installed.
```powershell
-# Interactive TUI mode
+# PowerShell / cmd — call Bun directly
bun --env-file=.env ./src/entrypoints/cli.tsx
-# Headless mode
-bun --env-file=.env ./src/entrypoints/cli.tsx -p "your prompt here"
-
-# Fallback Recovery CLI
-bun --env-file=.env ./src/localRecoveryCli.ts
-```
-
-**Option 2: Run inside Git Bash**
-
-```bash
-# Same usage as macOS / Linux
+# Or run inside Git Bash
./bin/claude-haha
```
-> **Note**: Some features (voice input, Computer Use, sandbox isolation, etc.) are not available on Windows. This does not affect the core TUI interaction.
+### 4. Global Usage (Optional)
----
-
-## Environment Variables
-
-| Variable | Required | Description |
-|------|------|------|
-| `ANTHROPIC_API_KEY` | One of two | API key sent via the `x-api-key` header |
-| `ANTHROPIC_AUTH_TOKEN` | One of two | Auth token sent via the `Authorization: Bearer` header |
-| `ANTHROPIC_BASE_URL` | No | Custom API endpoint, defaults to Anthropic |
-| `ANTHROPIC_MODEL` | No | Default model |
-| `ANTHROPIC_DEFAULT_SONNET_MODEL` | No | Sonnet-tier model mapping |
-| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | No | Haiku-tier model mapping |
-| `ANTHROPIC_DEFAULT_OPUS_MODEL` | No | Opus-tier model mapping |
-| `API_TIMEOUT_MS` | No | API request timeout, default `600000` (10min) |
-| `DISABLE_TELEMETRY` | No | Set to `1` to disable telemetry |
-| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | No | Set to `1` to disable non-essential network traffic |
-
----
-
-## Fallback Mode
-
-If the full TUI has issues, use the simplified readline-based interaction mode:
+Add `bin/` to your PATH to run from any directory. See [Global Usage Guide](docs/guide/global-usage.en.md):
```bash
-CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha
-```
-
----
-
-## Computer Use Desktop Control
-
-This project enables and modifies Claude Code's Computer Use feature (internal codename "Chicago"), allowing AI models to directly control your macOS desktop — screenshots, mouse clicks, keyboard input, app management.
-
-**Underlying modification**: The official implementation depends on Anthropic's private native modules (`@ant/computer-use-swift`, `@ant/computer-use-input`). This project replaces them entirely with a Python bridge using `pyautogui` (mouse/keyboard), `mss` (screenshots), and `pyobjc` (macOS APIs) — no closed-source binaries required.
-
-```bash
-# Ensure Python 3 and macOS Accessibility/Screen Recording permissions, then:
-./bin/claude-haha
-> Take a screenshot
-> Open Safari and search for something
-```
-
-For supported platforms, technical architecture, and approaches we tried, see: **[Computer Use Guide](docs/computer-use.en.md)**
-
----
-
-## Memory System
-
-Claude Code includes a **file-based persistent memory system** that accumulates understanding of users and projects across sessions. Core principle: only remember what cannot be inferred from the code.
-
-**Four memory types**:
-
-| Type | Purpose | Example |
-|------|---------|---------|
-| **User** | Role, skills, preferences | "Deep Go expertise, new to React" |
-| **Feedback** | Corrections or confirmations of Claude's approach | "Don't mock the database in tests" |
-| **Project** | Project context not derivable from code | "Merge freeze starts Thursday" |
-| **Reference** | Pointers to external systems | "Pipeline bugs tracked in Linear INGEST" |
-
-**Core capabilities**:
-
-- **Auto-extraction**: After each conversation, a background forked agent automatically analyzes and saves noteworthy information
-- **Smart retrieval**: When the user asks a question, a Sonnet model selects the most relevant memories (up to 5) to inject into context
-- **Freshness management**: Memories older than 1 day carry staleness warnings and are verified before citation
-
-Documentation: **[Usage Guide](docs/memory/01-usage-guide.md)** | **[Implementation Details](docs/memory/02-implementation.md)**
-
----
-
-## Fixes Compared with the Original Leaked Source
-
-The leaked source could not run directly. This repository mainly fixes the following issues:
-
-| Issue | Root cause | Fix |
-|------|------|------|
-| TUI does not start | The entry script routed no-argument startup to the recovery CLI | Restored the full `cli.tsx` entry |
-| Startup hangs | The `verify` skill imports a missing `.md` file, causing Bun's text loader to hang indefinitely | Added stub `.md` files |
-| `--print` hangs | `filePersistence/types.ts` was missing | Added type stub files |
-| `--print` hangs | `ultraplan/prompt.txt` was missing | Added resource stub files |
-| **Enter key does nothing** | The `modifiers-napi` native package was missing, `isModifierPressed()` threw, `handleEnter` was interrupted, and `onSubmit` never ran | Added try/catch fault tolerance |
-| Setup was skipped | `preload.ts` automatically set `LOCAL_RECOVERY=1`, skipping all initialization | Removed the default setting |
-
----
-
-## Project Structure
-
-```text
-bin/claude-haha # Entry script
-preload.ts # Bun preload (sets MACRO globals)
-.env.example # Environment variable template
-src/
-├── entrypoints/cli.tsx # Main CLI entry
-├── main.tsx # Main TUI logic (Commander.js + React/Ink)
-├── localRecoveryCli.ts # Fallback Recovery CLI
-├── setup.ts # Startup initialization
-├── screens/REPL.tsx # Interactive REPL screen
-├── ink/ # Ink terminal rendering engine
-├── components/ # UI components
-├── tools/ # Agent tools (Bash, Edit, Grep, etc.)
-├── commands/ # Slash commands (/commit, /review, etc.)
-├── skills/ # Skill system
-├── services/ # Service layer (API, MCP, OAuth, etc.)
-├── hooks/ # React hooks
-└── utils/ # Utility functions
+export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
```
---
@@ -312,39 +127,18 @@ src/
---
-## FAQ
+## More Documentation
-### Q: `undefined is not an object (evaluating 'usage.input_tokens')`
-
-**Cause**: `ANTHROPIC_BASE_URL` is misconfigured. The API endpoint is returning HTML or another non-JSON format instead of a valid Anthropic protocol response.
-
-This project uses the **Anthropic Messages API protocol**. `ANTHROPIC_BASE_URL` must point to an endpoint compatible with Anthropic's `/v1/messages` interface. The Anthropic SDK automatically appends `/v1/messages` to the base URL, so:
-
-- MiniMax: `ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic` ✅
-- OpenRouter: `ANTHROPIC_BASE_URL=https://openrouter.ai/api` ✅
-- OpenRouter (wrong): `ANTHROPIC_BASE_URL=https://openrouter.ai/anthropic` ❌ (returns HTML)
-
-If your model provider only supports the OpenAI protocol, you need a proxy like LiteLLM for protocol translation. See the [Third-Party Models Guide](docs/third-party-models.en.md).
-
-### Q: `Cannot find package 'bundle'`
-
-```
-error: Cannot find package 'bundle' from '.../claude-code-haha/src/entrypoints/cli.tsx'
-```
-
-**Cause**: Your Bun version is too old and doesn't support the required `bun:bundle` built-in module.
-
-**Fix**: Upgrade Bun to the latest version:
-
-```bash
-bun upgrade
-```
-
-### Q: How to use OpenAI / DeepSeek / Ollama or other non-Anthropic models?
-
-This project only supports the Anthropic protocol. If your model provider doesn't natively support the Anthropic protocol, you need a proxy like [LiteLLM](https://github.com/BerriAI/litellm) for protocol translation (OpenAI → Anthropic).
-
-See the [Third-Party Models Guide](docs/third-party-models.en.md) for detailed setup instructions.
+| Document | Description |
+|------|------|
+| [Environment Variables](docs/guide/env-vars.en.md) | Full env var reference and configuration methods |
+| [Third-Party Models](docs/guide/third-party-models.en.md) | Using OpenAI / DeepSeek / Ollama and other non-Anthropic models |
+| [Computer Use](docs/features/computer-use.en.md) | Desktop control (screenshots, mouse, keyboard) |
+| [Memory System](docs/memory/01-usage-guide.md) | Cross-session persistent memory usage and implementation |
+| [Global Usage](docs/guide/global-usage.en.md) | Run claude-haha from any directory |
+| [FAQ](docs/guide/faq.en.md) | Common error troubleshooting |
+| [Source Fixes](docs/reference/fixes.en.md) | Fixes compared with the original leaked source |
+| [Project Structure](docs/reference/project-structure.en.md) | Code directory structure |
---
diff --git a/README.md b/README.md
index adcf375f..bc4313bf 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,28 @@
# Claude Code Haha
-中文 | English
+
+
+[](https://github.com/NanmiCoder/cc-haha/stargazers)
+[](https://github.com/NanmiCoder/cc-haha/network/members)
+[](https://github.com/NanmiCoder/cc-haha/issues)
+[](https://github.com/NanmiCoder/cc-haha/pulls)
+[](https://github.com/NanmiCoder/cc-haha/blob/main/LICENSE)
+[](README.md)
+[](README.en.md)
+
+
基于 Claude Code 泄露源码修复的**本地可运行版本**，支持接入任意 Anthropic 兼容 API（如 MiniMax、OpenRouter 等）。
> 原始泄露源码无法直接运行。本仓库修复了启动链路中的多个阻塞问题，使完整的 Ink TUI 交互界面可以在本地工作。
-
+
-## 目录
-
-- [功能](#功能)
-- [架构概览](#架构概览)
-- [快速开始](#快速开始)
-- [环境变量说明](#环境变量说明)
-- [降级模式](#降级模式)
-- [Computer Use 桌面控制](#computer-use-桌面控制)
-- [记忆系统](#记忆系统)
-- [常见问题](#常见问题)
-- [相对于原始泄露源码的修复](#相对于原始泄露源码的修复)
-- [项目结构](#项目结构)
-- [技术栈](#技术栈)
+
+ 功能 · 架构概览 · 快速开始 · 环境变量 · FAQ · 全局使用 · 更多文档
+
---
@@ -31,12 +31,10 @@
- 完整的 Ink TUI 交互界面（与官方 Claude Code 一致）
- `--print` 无头模式（脚本/CI 场景）
- 支持 MCP 服务器、插件、Skills
-- 支持自定义 API 端点和模型（[第三方模型使用指南](docs/third-party-models.md)）
-- **Computer Use 桌面控制**（截屏、鼠标、键盘、应用管理）— [使用指南](docs/computer-use.md)
-- **记忆系统**（跨会话持久化记忆，自动提取 + 智能检索）— [使用指南](docs/memory/01-usage-guide.md) | [实现原理](docs/memory/02-implementation.md)
-- 降级 Recovery CLI 模式
-
-> **Computer Use 说明**：本项目包含**魔改版的 Computer Use** 功能。官方实现依赖 Anthropic 私有原生模块，我们替换了整个底层操作层，使用 Python bridge（`pyautogui` + `mss` + `pyobjc`）实现，使得任何人都可以在 macOS 上使用。详见 [Computer Use 功能指南](docs/computer-use.md)。
+- 支持自定义 API 端点和模型（[第三方模型使用指南](docs/guide/third-party-models.md)）
+- **Computer Use 桌面控制** — [使用指南](docs/features/computer-use.md)
+- **记忆系统**（跨会话持久化记忆）— [使用指南](docs/memory/01-usage-guide.md)
+- 降级 Recovery CLI 模式（`CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha`）
---
@@ -44,16 +42,16 @@
-
整体架构 |
-
请求生命周期 |
-
工具系统 |
-
多 Agent 架构 |
+
整体架构 |
+
请求生命周期 |
+
工具系统 |
+
多 Agent 架构 |
-
终端 UI |
-
权限与安全 |
-
服务层 |
-
状态与数据流 |
+
终端 UI |
+
权限与安全 |
+
服务层 |
+
状态与数据流 |
@@ -63,238 +61,55 @@
### 1. 安装 Bun
-本项目运行依赖 [Bun](https://bun.sh)。如果你的电脑还没有安装 Bun，可以先执行下面任一方式：
-
```bash
-# macOS / Linux（官方安装脚本）
+# macOS / Linux
curl -fsSL https://bun.sh/install | bash
-```
-如果在精简版 Linux 环境里提示 `unzip is required to install bun`，先安装 `unzip`：
-
-```bash
-# Ubuntu / Debian
-apt update && apt install -y unzip
-```
-
-```bash
-# macOS（Homebrew）
+# macOS (Homebrew)
brew install bun
-```
-```powershell
-# Windows（PowerShell）
+# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"
```
-安装完成后，重新打开终端并确认：
+> 精简版 Linux 如提示 `unzip is required`，先运行 `apt update && apt install -y unzip`
-```bash
-bun --version
-```
-
-### 2. 安装项目依赖
+### 2. 安装依赖并配置
```bash
bun install
-```
-
-### 3. 配置环境变量
-
-复制示例文件并填入你的 API Key：
-
-```bash
cp .env.example .env
+# 编辑 .env 填入你的 API Key，详见 docs/guide/env-vars.md
```
-编辑 `.env`（以下示例使用 [MiniMax](https://platform.minimaxi.com/subscribe/token-plan?code=1TG2Cseab2&source=link) 作为 API 提供商，也可替换为其他兼容服务）：
-
-```env
-# API 认证（二选一）
-ANTHROPIC_API_KEY=sk-xxx # 标准 API Key（x-api-key 头）
-ANTHROPIC_AUTH_TOKEN=sk-xxx # Bearer Token（Authorization 头）
-
-# API 端点（可选，默认 Anthropic 官方）
-ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
-
-# 模型配置
-ANTHROPIC_MODEL=MiniMax-M2.7-highspeed
-ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.7-highspeed
-ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.7-highspeed
-ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.7-highspeed
-
-# 超时（毫秒）
-API_TIMEOUT_MS=3000000
-
-# 禁用遥测和非必要网络请求
-DISABLE_TELEMETRY=1
-CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
-```
-
-> **提示**：除了 `.env` 文件，你也可以通过 `~/.claude/settings.json` 的 `env` 字段配置环境变量。这与官方 Claude Code 的配置方式一致：
->
-> ```json
-> {
-> "env": {
-> "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
-> "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
-> "ANTHROPIC_MODEL": "MiniMax-M2.7-highspeed"
-> }
-> }
-> ```
->
-> 配置优先级：环境变量 > `.env` 文件 > `~/.claude/settings.json`
-
-### 4. 启动
+### 3. 启动
#### macOS / Linux
```bash
-# 交互 TUI 模式（完整界面）
-./bin/claude-haha
-
-# 无头模式（单次问答）
-./bin/claude-haha -p "your prompt here"
-
-# 管道输入
-echo "explain this code" | ./bin/claude-haha -p
-
-# 查看所有选项
-./bin/claude-haha --help
+./bin/claude-haha # 交互 TUI 模式
+./bin/claude-haha -p "your prompt here" # 无头模式
+./bin/claude-haha --help # 查看所有选项
```
#### Windows
-> **前置要求**：必须安装 [Git for Windows](https://git-scm.com/download/win)（提供 Git Bash，项目内部 Shell 执行依赖它）。
-
-Windows 下启动脚本 `bin/claude-haha` 是 bash 脚本，无法在 cmd / PowerShell 中直接运行。请使用以下方式：
-
-**方式一：PowerShell / cmd 直接调用 Bun（推荐）**
+> **前置要求**：必须安装 [Git for Windows](https://git-scm.com/download/win)
```powershell
-# 交互 TUI 模式
+# PowerShell / cmd 直接调用 Bun
bun --env-file=.env ./src/entrypoints/cli.tsx
-# 无头模式
-bun --env-file=.env ./src/entrypoints/cli.tsx -p "your prompt here"
-
-# 降级 Recovery CLI
-bun --env-file=.env ./src/localRecoveryCli.ts
-```
-
-**方式二：Git Bash 中运行**
-
-```bash
-# 在 Git Bash 终端中，与 macOS/Linux 用法一致
+# 或在 Git Bash 中运行
./bin/claude-haha
```
-> **注意**：部分功能（语音输入、Computer Use、Sandbox 隔离等）在 Windows 上不可用，不影响核心 TUI 交互。
+### 4. 全局使用（可选）
----
-
-## 环境变量说明
-
-| 变量 | 必填 | 说明 |
-|------|------|------|
-| `ANTHROPIC_API_KEY` | 二选一 | API Key，通过 `x-api-key` 头发送 |
-| `ANTHROPIC_AUTH_TOKEN` | 二选一 | Auth Token，通过 `Authorization: Bearer` 头发送 |
-| `ANTHROPIC_BASE_URL` | 否 | 自定义 API 端点，默认 Anthropic 官方 |
-| `ANTHROPIC_MODEL` | 否 | 默认模型 |
-| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 否 | Sonnet 级别模型映射 |
-| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 否 | Haiku 级别模型映射 |
-| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 否 | Opus 级别模型映射 |
-| `API_TIMEOUT_MS` | 否 | API 请求超时，默认 600000 (10min) |
-| `DISABLE_TELEMETRY` | 否 | 设为 `1` 禁用遥测 |
-| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 否 | 设为 `1` 禁用非必要网络请求 |
-
----
-
-## 降级模式
-
-如果完整 TUI 出现问题，可以使用简化版 readline 交互模式：
+将 `bin/` 加入 PATH 后可在任意目录启动，详见 [全局使用指南](docs/guide/global-usage.md)：
```bash
-CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha
-```
-
----
-
-## Computer Use 桌面控制
-
-本项目启用并改造了 Claude Code 的 Computer Use 功能（内部代号 "Chicago"），让 AI 模型可以直接控制你的 macOS 桌面——截屏、鼠标点击、键盘输入、应用管理。
-
-**底层改造**：官方实现依赖 Anthropic 私有原生模块（`@ant/computer-use-swift`、`@ant/computer-use-input`），本项目用 Python bridge 完全替代，使用 `pyautogui`（鼠标键盘）、`mss`（截图）、`pyobjc`（macOS API），无需任何闭源二进制。
-
-```bash
-# 确保有 Python 3 和 macOS 辅助功能/屏幕录制权限，然后直接使用：
-./bin/claude-haha
-> 帮我截个屏
-> 打开网易云音乐搜索一首歌
-```
-
-详细说明、支持的设备列表、技术架构和尝试过的方案请参考：**[Computer Use 功能指南](docs/computer-use.md)**
-
----
-
-## 记忆系统
-
-Claude Code 内置了一套**基于文件的持久化记忆系统**，能够跨会话积累对用户和项目的理解。核心理念：只记住无法从代码中推断出来的东西。
-
-**四种记忆类型**：
-
-| 类型 | 用途 | 示例 |
-|------|------|------|
-| **User** | 用户角色、技能、偏好 | "深厚 Go 经验，React 新手" |
-| **Feedback** | 对 Claude 工作方式的纠正或肯定 | "不要 mock 数据库" |
-| **Project** | 无法从代码推导的项目上下文 | "周四后冻结非关键合并" |
-| **Reference** | 外部系统的指针 | "Bug 追踪在 Linear INGEST 项目" |
-
-**核心能力**：
-
-- **自动提取**：每次对话结束后，后台分叉代理自动分析并保存值得记住的信息
-- **智能检索**：用户提问时，Sonnet 模型从所有记忆中选择最相关的（最多 5 个）注入上下文
-- **新鲜度管理**：超过 1 天的记忆附带陈旧警告，引用前自动验证
-
-详细文档：**[使用指南](docs/memory/01-usage-guide.md)** | **[实现原理](docs/memory/02-implementation.md)**
-
----
-
-## 相对于原始泄露源码的修复
-
-泄露的源码无法直接运行，主要修复了以下问题：
-
-| 问题 | 根因 | 修复 |
-|------|------|------|
-| TUI 不启动 | 入口脚本把无参数启动路由到了 recovery CLI | 恢复走 `cli.tsx` 完整入口 |
-| 启动卡死 | `verify` skill 导入缺失的 `.md` 文件，Bun text loader 无限挂起 | 创建 stub `.md` 文件 |
-| `--print` 卡死 | `filePersistence/types.ts` 缺失 | 创建类型桩文件 |
-| `--print` 卡死 | `ultraplan/prompt.txt` 缺失 | 创建资源桩文件 |
-| **Enter 键无响应** | `modifiers-napi` native 包缺失，`isModifierPressed()` 抛异常导致 `handleEnter` 中断，`onSubmit` 永远不执行 | 加 try-catch 容错 |
-| setup 被跳过 | `preload.ts` 自动设置 `LOCAL_RECOVERY=1` 跳过全部初始化 | 移除默认设置 |
-
----
-
-## 项目结构
-
-```
-bin/claude-haha # 入口脚本
-preload.ts # Bun preload（设置 MACRO 全局变量）
-.env.example # 环境变量模板
-src/
-├── entrypoints/cli.tsx # CLI 主入口
-├── main.tsx # TUI 主逻辑（Commander.js + React/Ink）
-├── localRecoveryCli.ts # 降级 Recovery CLI
-├── setup.ts # 启动初始化
-├── screens/REPL.tsx # 交互 REPL 界面
-├── ink/ # Ink 终端渲染引擎
-├── components/ # UI 组件
-├── tools/ # Agent 工具（Bash, Edit, Grep 等）
-├── commands/ # 斜杠命令（/commit, /review 等）
-├── skills/ # Skill 系统
-├── services/ # 服务层（API, MCP, OAuth 等）
-├── hooks/ # React hooks
-└── utils/ # 工具函数
+export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
```
---
@@ -312,39 +127,18 @@ src/
---
-## 常见问题
+## 更多文档
-### Q: `undefined is not an object (evaluating 'usage.input_tokens')`
-
-**原因**：`ANTHROPIC_BASE_URL` 配置不正确，API 端点返回的不是 Anthropic 协议格式的 JSON，而是 HTML 页面或其他格式。
-
-本项目使用 **Anthropic Messages API 协议**，`ANTHROPIC_BASE_URL` 必须指向一个兼容 Anthropic `/v1/messages` 接口的端点。Anthropic SDK 会自动在 base URL 后面拼接 `/v1/messages`，所以：
-
-- MiniMax：`ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic` ✅
-- OpenRouter：`ANTHROPIC_BASE_URL=https://openrouter.ai/api` ✅
-- OpenRouter 错误写法：`ANTHROPIC_BASE_URL=https://openrouter.ai/anthropic` ❌（返回 HTML）
-
-如果你的模型供应商只支持 OpenAI 协议，需要通过 LiteLLM 等代理做协议转换，详见 [第三方模型使用指南](docs/third-party-models.md)。
-
-### Q: `Cannot find package 'bundle'`
-
-```
-error: Cannot find package 'bundle' from '.../claude-code-haha/src/entrypoints/cli.tsx'
-```
-
-**原因**：Bun 版本过低，不支持项目所需的 `bun:bundle` 等内置模块。
-
-**解决**：升级 Bun 到最新版本：
-
-```bash
-bun upgrade
-```
-
-### Q: 怎么接入 OpenAI / DeepSeek / Ollama 等非 Anthropic 模型？
-
-本项目只支持 Anthropic 协议。如果模型供应商不直接支持 Anthropic 协议，需要用 [LiteLLM](https://github.com/BerriAI/litellm) 等代理做协议转换（OpenAI → Anthropic）。
-
-详细配置步骤请参考：[第三方模型使用指南](docs/third-party-models.md)
+| 文档 | 说明 |
+|------|------|
+| [环境变量](docs/guide/env-vars.md) | 完整环境变量参考和配置方式 |
+| [第三方模型](docs/guide/third-party-models.md) | 接入 OpenAI / DeepSeek / Ollama 等非 Anthropic 模型 |
+| [Computer Use](docs/features/computer-use.md) | 桌面控制功能（截屏、鼠标、键盘） |
+| [记忆系统](docs/memory/01-usage-guide.md) | 跨会话持久化记忆的使用与实现 |
+| [全局使用](docs/guide/global-usage.md) | 在任意目录启动 claude-haha |
+| [常见问题](docs/guide/faq.md) | 常见错误排查 |
+| [源码修复记录](docs/reference/fixes.md) | 相对于原始泄露源码的修复内容 |
+| [项目结构](docs/reference/project-structure.md) | 代码目录结构说明 |
---
diff --git a/docs/computer-use.en.md b/docs/features/computer-use.en.md
similarity index 100%
rename from docs/computer-use.en.md
rename to docs/features/computer-use.en.md
diff --git a/docs/computer-use.md b/docs/features/computer-use.md
similarity index 100%
rename from docs/computer-use.md
rename to docs/features/computer-use.md
diff --git a/docs/guide/env-vars.en.md b/docs/guide/env-vars.en.md
new file mode 100644
index 00000000..91a8b576
--- /dev/null
+++ b/docs/guide/env-vars.en.md
@@ -0,0 +1,62 @@
+# Environment Variables
+
+中文 | Back to README
+
+| Variable | Required | Description |
+|------|------|------|
+| `ANTHROPIC_API_KEY` | One of two | API key sent via the `x-api-key` header |
+| `ANTHROPIC_AUTH_TOKEN` | One of two | Auth token sent via the `Authorization: Bearer` header |
+| `ANTHROPIC_BASE_URL` | No | Custom API endpoint, defaults to Anthropic |
+| `ANTHROPIC_MODEL` | No | Default model |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | No | Sonnet-tier model mapping |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | No | Haiku-tier model mapping |
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` | No | Opus-tier model mapping |
+| `API_TIMEOUT_MS` | No | API request timeout, default `600000` (10min) |
+| `DISABLE_TELEMETRY` | No | Set to `1` to disable telemetry |
+| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | No | Set to `1` to disable non-essential network traffic |
+
+## Configuration Methods
+
+### Option 1: `.env` File
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` (the example below uses [MiniMax](https://platform.minimaxi.com/subscribe/token-plan?code=1TG2Cseab2&source=link) as the API provider — you can replace it with any compatible service):
+
+```env
+# API authentication (choose one)
+ANTHROPIC_API_KEY=sk-xxx # Standard API key via x-api-key header
+ANTHROPIC_AUTH_TOKEN=sk-xxx # Bearer token via Authorization header
+
+# API endpoint (optional, defaults to Anthropic)
+ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
+
+# Model configuration
+ANTHROPIC_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.7-highspeed
+
+# Timeout in milliseconds
+API_TIMEOUT_MS=3000000
+
+# Disable telemetry and non-essential network traffic
+DISABLE_TELEMETRY=1
+CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+```
+
+### Option 2: `~/.claude/settings.json`
+
+```json
+{
+ "env": {
+ "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
+ "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
+ "ANTHROPIC_MODEL": "MiniMax-M2.7-highspeed"
+ }
+}
+```
+
+> Priority: Environment variables > `.env` file > `~/.claude/settings.json`
diff --git a/docs/guide/env-vars.md b/docs/guide/env-vars.md
new file mode 100644
index 00000000..44dddca0
--- /dev/null
+++ b/docs/guide/env-vars.md
@@ -0,0 +1,62 @@
+# 环境变量说明
+
+English | 返回 README
+
+| 变量 | 必填 | 说明 |
+|------|------|------|
+| `ANTHROPIC_API_KEY` | 二选一 | API Key，通过 `x-api-key` 头发送 |
+| `ANTHROPIC_AUTH_TOKEN` | 二选一 | Auth Token，通过 `Authorization: Bearer` 头发送 |
+| `ANTHROPIC_BASE_URL` | 否 | 自定义 API 端点，默认 Anthropic 官方 |
+| `ANTHROPIC_MODEL` | 否 | 默认模型 |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 否 | Sonnet 级别模型映射 |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 否 | Haiku 级别模型映射 |
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 否 | Opus 级别模型映射 |
+| `API_TIMEOUT_MS` | 否 | API 请求超时，默认 600000 (10min) |
+| `DISABLE_TELEMETRY` | 否 | 设为 `1` 禁用遥测 |
+| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 否 | 设为 `1` 禁用非必要网络请求 |
+
+## 配置方式
+
+### 方式一：`.env` 文件
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env`（以下示例使用 [MiniMax](https://platform.minimaxi.com/subscribe/token-plan?code=1TG2Cseab2&source=link) 作为 API 提供商，也可替换为其他兼容服务）：
+
+```env
+# API 认证（二选一）
+ANTHROPIC_API_KEY=sk-xxx # 标准 API Key（x-api-key 头）
+ANTHROPIC_AUTH_TOKEN=sk-xxx # Bearer Token（Authorization 头）
+
+# API 端点（可选，默认 Anthropic 官方）
+ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
+
+# 模型配置
+ANTHROPIC_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.7-highspeed
+
+# 超时（毫秒）
+API_TIMEOUT_MS=3000000
+
+# 禁用遥测和非必要网络请求
+DISABLE_TELEMETRY=1
+CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+```
+
+### 方式二：`~/.claude/settings.json`
+
+```json
+{
+ "env": {
+ "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
+ "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
+ "ANTHROPIC_MODEL": "MiniMax-M2.7-highspeed"
+ }
+}
+```
+
+> 配置优先级：环境变量 > `.env` 文件 > `~/.claude/settings.json`
diff --git a/docs/guide/faq.en.md b/docs/guide/faq.en.md
new file mode 100644
index 00000000..a02452ba
--- /dev/null
+++ b/docs/guide/faq.en.md
@@ -0,0 +1,35 @@
+# FAQ
+
+中文 | Back to README
+
+## Q: `undefined is not an object (evaluating 'usage.input_tokens')`
+
+**Cause**: `ANTHROPIC_BASE_URL` is misconfigured. The API endpoint is returning HTML or another non-JSON format instead of a valid Anthropic protocol response.
+
+This project uses the **Anthropic Messages API protocol**. `ANTHROPIC_BASE_URL` must point to an endpoint compatible with Anthropic's `/v1/messages` interface. The Anthropic SDK automatically appends `/v1/messages` to the base URL, so:
+
+- MiniMax: `ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic` ✅
+- OpenRouter: `ANTHROPIC_BASE_URL=https://openrouter.ai/api` ✅
+- OpenRouter (wrong): `ANTHROPIC_BASE_URL=https://openrouter.ai/anthropic` ❌ (returns HTML)
+
+If your model provider only supports the OpenAI protocol, you need a proxy like LiteLLM for protocol translation. See the [Third-Party Models Guide](./third-party-models.en.md).
+
+## Q: `Cannot find package 'bundle'`
+
+```
+error: Cannot find package 'bundle' from '.../claude-code-haha/src/entrypoints/cli.tsx'
+```
+
+**Cause**: Your Bun version is too old and doesn't support the required `bun:bundle` built-in module.
+
+**Fix**: Upgrade Bun to the latest version:
+
+```bash
+bun upgrade
+```
+
+## Q: How to use OpenAI / DeepSeek / Ollama or other non-Anthropic models?
+
+This project only supports the Anthropic protocol. If your model provider doesn't natively support the Anthropic protocol, you need a proxy like [LiteLLM](https://github.com/BerriAI/litellm) for protocol translation (OpenAI → Anthropic).
+
+See the [Third-Party Models Guide](./third-party-models.en.md) for detailed setup instructions.
diff --git a/docs/guide/faq.md b/docs/guide/faq.md
new file mode 100644
index 00000000..1e5f3358
--- /dev/null
+++ b/docs/guide/faq.md
@@ -0,0 +1,35 @@
+# 常见问题
+
+English | 返回 README
+
+## Q: `undefined is not an object (evaluating 'usage.input_tokens')`
+
+**原因**：`ANTHROPIC_BASE_URL` 配置不正确，API 端点返回的不是 Anthropic 协议格式的 JSON，而是 HTML 页面或其他格式。
+
+本项目使用 **Anthropic Messages API 协议**，`ANTHROPIC_BASE_URL` 必须指向一个兼容 Anthropic `/v1/messages` 接口的端点。Anthropic SDK 会自动在 base URL 后面拼接 `/v1/messages`，所以：
+
+- MiniMax：`ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic` ✅
+- OpenRouter：`ANTHROPIC_BASE_URL=https://openrouter.ai/api` ✅
+- OpenRouter 错误写法：`ANTHROPIC_BASE_URL=https://openrouter.ai/anthropic` ❌（返回 HTML）
+
+如果你的模型供应商只支持 OpenAI 协议，需要通过 LiteLLM 等代理做协议转换，详见 [第三方模型使用指南](./third-party-models.md)。
+
+## Q: `Cannot find package 'bundle'`
+
+```
+error: Cannot find package 'bundle' from '.../claude-code-haha/src/entrypoints/cli.tsx'
+```
+
+**原因**：Bun 版本过低，不支持项目所需的 `bun:bundle` 等内置模块。
+
+**解决**：升级 Bun 到最新版本：
+
+```bash
+bun upgrade
+```
+
+## Q: 怎么接入 OpenAI / DeepSeek / Ollama 等非 Anthropic 模型？
+
+本项目只支持 Anthropic 协议。如果模型供应商不直接支持 Anthropic 协议，需要用 [LiteLLM](https://github.com/BerriAI/litellm) 等代理做协议转换（OpenAI → Anthropic）。
+
+详细配置步骤请参考：[第三方模型使用指南](./third-party-models.md)
diff --git a/docs/guide/global-usage.en.md b/docs/guide/global-usage.en.md
new file mode 100644
index 00000000..1577f17b
--- /dev/null
+++ b/docs/guide/global-usage.en.md
@@ -0,0 +1,41 @@
+# Global Usage (Run from Any Directory)
+
+中文 | Back to README
+
+If you want to run `claude-haha` directly from any project directory, set up one of the following. Once configured, `claude-haha` will automatically recognize your current working directory.
+
+## macOS / Linux
+
+Add to `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# Option 1: Add to PATH (recommended)
+export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
+
+# Option 2: Alias
+alias claude-haha="$HOME/path/to/claude-code-haha/bin/claude-haha"
+```
+
+Then reload the config:
+
+```bash
+source ~/.bashrc # or source ~/.zshrc
+```
+
+## Windows (Git Bash)
+
+Add to `~/.bashrc`:
+
+```bash
+export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
+```
+
+## Verify
+
+After setup, navigate to any project directory and test:
+
+```bash
+cd ~/your-other-project
+claude-haha
+# Ask "What is the current directory?" — it should show ~/your-other-project
+```
diff --git a/docs/guide/global-usage.md b/docs/guide/global-usage.md
new file mode 100644
index 00000000..f4ffee92
--- /dev/null
+++ b/docs/guide/global-usage.md
@@ -0,0 +1,41 @@
+# 全局使用（任意目录启动）
+
+English | 返回 README
+
+如果你希望在任意项目目录直接运行 `claude-haha`，可以通过以下方式配置。配置完成后，`claude-haha` 会自动识别你当前所在的工作目录。
+
+## macOS / Linux
+
+在 `~/.bashrc` 或 `~/.zshrc` 中添加：
+
+```bash
+# 方式一：添加 PATH（推荐）
+export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
+
+# 方式二：alias
+alias claude-haha="$HOME/path/to/claude-code-haha/bin/claude-haha"
+```
+
+然后重新加载配置：
+
+```bash
+source ~/.bashrc # 或 source ~/.zshrc
+```
+
+## Windows (Git Bash)
+
+在 `~/.bashrc` 中添加：
+
+```bash
+export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
+```
+
+## 验证
+
+配置完成后，进入任意项目目录测试：
+
+```bash
+cd ~/your-other-project
+claude-haha
+# 启动后询问「当前目录是什么？」，应显示 ~/your-other-project
+```
diff --git a/docs/third-party-models.en.md b/docs/guide/third-party-models.en.md
similarity index 100%
rename from docs/third-party-models.en.md
rename to docs/guide/third-party-models.en.md
diff --git a/docs/third-party-models.md b/docs/guide/third-party-models.md
similarity index 100%
rename from docs/third-party-models.md
rename to docs/guide/third-party-models.md
diff --git a/docs/00runtime.png b/docs/images/00runtime.png
similarity index 100%
rename from docs/00runtime.png
rename to docs/images/00runtime.png
diff --git a/docs/01-overall-architecture.png b/docs/images/01-overall-architecture.png
similarity index 100%
rename from docs/01-overall-architecture.png
rename to docs/images/01-overall-architecture.png
diff --git a/docs/02-request-lifecycle.png b/docs/images/02-request-lifecycle.png
similarity index 100%
rename from docs/02-request-lifecycle.png
rename to docs/images/02-request-lifecycle.png
diff --git a/docs/03-tool-system.png b/docs/images/03-tool-system.png
similarity index 100%
rename from docs/03-tool-system.png
rename to docs/images/03-tool-system.png
diff --git a/docs/04-multi-agent.png b/docs/images/04-multi-agent.png
similarity index 100%
rename from docs/04-multi-agent.png
rename to docs/images/04-multi-agent.png
diff --git a/docs/05-terminal-ui.png b/docs/images/05-terminal-ui.png
similarity index 100%
rename from docs/05-terminal-ui.png
rename to docs/images/05-terminal-ui.png
diff --git a/docs/06-permission-security.png b/docs/images/06-permission-security.png
similarity index 100%
rename from docs/06-permission-security.png
rename to docs/images/06-permission-security.png
diff --git a/docs/07-services-layer.png b/docs/images/07-services-layer.png
similarity index 100%
rename from docs/07-services-layer.png
rename to docs/images/07-services-layer.png
diff --git a/docs/08-state-data-flow.png b/docs/images/08-state-data-flow.png
similarity index 100%
rename from docs/08-state-data-flow.png
rename to docs/images/08-state-data-flow.png
diff --git a/docs/reference/fixes.en.md b/docs/reference/fixes.en.md
new file mode 100644
index 00000000..8116c27f
--- /dev/null
+++ b/docs/reference/fixes.en.md
@@ -0,0 +1,14 @@
+# Fixes Compared with the Original Leaked Source
+
+中文 | Back to README
+
+The leaked source could not run directly. This repository mainly fixes the following issues:
+
+| Issue | Root cause | Fix |
+|------|------|------|
+| TUI does not start | The entry script routed no-argument startup to the recovery CLI | Restored the full `cli.tsx` entry |
+| Startup hangs | The `verify` skill imports a missing `.md` file, causing Bun's text loader to hang indefinitely | Added stub `.md` files |
+| `--print` hangs | `filePersistence/types.ts` was missing | Added type stub files |
+| `--print` hangs | `ultraplan/prompt.txt` was missing | Added resource stub files |
+| **Enter key does nothing** | The `modifiers-napi` native package was missing, `isModifierPressed()` threw, `handleEnter` was interrupted, and `onSubmit` never ran | Added try/catch fault tolerance |
+| Setup was skipped | `preload.ts` automatically set `LOCAL_RECOVERY=1`, skipping all initialization | Removed the default setting |
diff --git a/docs/reference/fixes.md b/docs/reference/fixes.md
new file mode 100644
index 00000000..97424b32
--- /dev/null
+++ b/docs/reference/fixes.md
@@ -0,0 +1,14 @@
+# 相对于原始泄露源码的修复
+
+English | 返回 README
+
+泄露的源码无法直接运行，主要修复了以下问题：
+
+| 问题 | 根因 | 修复 |
+|------|------|------|
+| TUI 不启动 | 入口脚本把无参数启动路由到了 recovery CLI | 恢复走 `cli.tsx` 完整入口 |
+| 启动卡死 | `verify` skill 导入缺失的 `.md` 文件，Bun text loader 无限挂起 | 创建 stub `.md` 文件 |
+| `--print` 卡死 | `filePersistence/types.ts` 缺失 | 创建类型桩文件 |
+| `--print` 卡死 | `ultraplan/prompt.txt` 缺失 | 创建资源桩文件 |
+| **Enter 键无响应** | `modifiers-napi` native 包缺失，`isModifierPressed()` 抛异常导致 `handleEnter` 中断，`onSubmit` 永远不执行 | 加 try-catch 容错 |
+| setup 被跳过 | `preload.ts` 自动设置 `LOCAL_RECOVERY=1` 跳过全部初始化 | 移除默认设置 |
diff --git a/docs/reference/project-structure.en.md b/docs/reference/project-structure.en.md
new file mode 100644
index 00000000..2aeff8b0
--- /dev/null
+++ b/docs/reference/project-structure.en.md
@@ -0,0 +1,23 @@
+# Project Structure
+
+中文 | Back to README
+
+```text
+bin/claude-haha # Entry script
+preload.ts # Bun preload (sets MACRO globals)
+.env.example # Environment variable template
+src/
+├── entrypoints/cli.tsx # Main CLI entry
+├── main.tsx # Main TUI logic (Commander.js + React/Ink)
+├── localRecoveryCli.ts # Fallback Recovery CLI
+├── setup.ts # Startup initialization
+├── screens/REPL.tsx # Interactive REPL screen
+├── ink/ # Ink terminal rendering engine
+├── components/ # UI components
+├── tools/ # Agent tools (Bash, Edit, Grep, etc.)
+├── commands/ # Slash commands (/commit, /review, etc.)
+├── skills/ # Skill system
+├── services/ # Service layer (API, MCP, OAuth, etc.)
+├── hooks/ # React hooks
+└── utils/ # Utility functions
+```
diff --git a/docs/reference/project-structure.md b/docs/reference/project-structure.md
new file mode 100644
index 00000000..5403d5fe
--- /dev/null
+++ b/docs/reference/project-structure.md
@@ -0,0 +1,23 @@
+# 项目结构
+
+English | 返回 README
+
+```
+bin/claude-haha # 入口脚本
+preload.ts # Bun preload（设置 MACRO 全局变量）
+.env.example # 环境变量模板
+src/
+├── entrypoints/cli.tsx # CLI 主入口
+├── main.tsx # TUI 主逻辑（Commander.js + React/Ink）
+├── localRecoveryCli.ts # 降级 Recovery CLI
+├── setup.ts # 启动初始化
+├── screens/REPL.tsx # 交互 REPL 界面
+├── ink/ # Ink 终端渲染引擎
+├── components/ # UI 组件
+├── tools/ # Agent 工具（Bash, Edit, Grep 等）
+├── commands/ # 斜杠命令（/commit, /review 等）
+├── skills/ # Skill 系统
+├── services/ # 服务层（API, MCP, OAuth 等）
+├── hooks/ # React hooks
+└── utils/ # 工具函数
+```