diff --git a/.agents/skills/mcpp-contributing/SKILL.md b/.agents/skills/mcpp-contributing/SKILL.md
new file mode 100644
index 0000000..0880518
--- /dev/null
+++ b/.agents/skills/mcpp-contributing/SKILL.md
@@ -0,0 +1,157 @@
+---
+name: mcpp-contributing
+description: Use when contributing to the mcpp project — submitting bug fixes, new features, code optimizations, documentation improvements, or any PR. Covers issue creation, branch conventions, build verification, CI requirements, and PR workflow using gh and git.
+---
+
+# mcpp 项目开发贡献
+
+## Overview
+
+mcpp 项目的贡献流程：先创建 Issue → 实现改动 → 提交 PR → CI 通过 → Review 合入。
+
+- 仓库：https://github.com/mcpp-community/mcpp
+- 构建：`mcpp build`（C++23 模块自举）
+- 测试：`tests/e2e/` 下的 bash 脚本
+- CI：GitHub Actions，base 为 `main` 的 PR 自动触发
+
+## 贡献流程
+
+### 1. 创建 Issue（必须）
+
+所有贡献先创建 Issue，特别是新功能。避免重复工作，留下讨论记录。
+
+**Bug 修复**
+
+```bash
+gh issue create \
+  --title "fix: 简短描述" \
+  --body "## 复现步骤
+1. ...
+
+## 期望行为
+...
+
+## 实际行为
+...
+
+## 环境
+- mcpp 版本：\`mcpp --version\`
+- OS："
+```
+
+**新功能**
+
+```bash
+gh issue create \
+  --title "feat: 简短描述" \
+  --body "## 动机
+...
+
+## 设计思路
+...
+
+## 涉及模块
+..."
+```
+
+**代码优化**
+
+```bash
+gh issue create \
+  --title "refactor: 简短描述" \
+  --body "## 当前问题
+...
+
+## 优化方案
+..."
+```
+
+### 2. 实现改动
+
+**分支**
+
+```bash
+git checkout main && git pull origin main
+git checkout -b <type>/<short-description>
+# type: feat / fix / refactor / test / docs
+```
+
+**开发要求**
+- 遵循现有代码风格（查看相邻代码）
+- 模块导入用 `import std;` 和 `import mcpp.xxx;`
+- 只改需要改的，不顺手重构不相关代码
+
+**构建验证**
+
+```bash
+# 找到 mcpp 二进制
+ls target/x86_64-linux-gnu/*/bin/mcpp
+# 构建
+<mcpp-binary> build
+```
+
+**测试**
+
+```bash
+bash tests/e2e/01_help_and_version.sh    # 基础测试
+bash tests/e2e/<relevant-test>.sh        # 相关测试
+# 新功能应创建对应 E2E 测试
+```
+
+### 3. 提交 PR
+
+**提交信息**：`feat:` / `fix:` / `refactor:` / `test:` / `docs:` 前缀
+
+```bash
+git push -u origin <branch>
+gh pr create \
+  --title "<type>: 简短描述" \
+  --body "## Summary
+- 改动点
+
+Closes #<issue>
+
+## Test plan
+- [ ] mcpp build 通过
+- [ ] E2E 测试通过"
+```
+
+### 4. CI 必须通过
+
+CI 不通过的 PR 不会被合入。
+
+```bash
+gh pr checks <pr-number>           # 查看状态
+gh run view <run-id> --log-failed  # 查看失败日志
+```
+
+CI 内容：mcpp 自举构建 + E2E 测试。只有 base 为 `main` 的 PR 触发。
+
+### 5. Review & 合入
+
+维护者 review → 反馈修改 → CI 重跑 → Squash merge。
+
+## 项目结构
+
+```
+src/
+├── cli.cppm              ← 命令行入口
+├── config.cppm           ← 全局配置
+├── manifest.cppm         ← mcpp.toml 解析
+├── build/                ← 构建系统（ninja 后端）
+├── pm/                   ← 包管理子系统
+├── toolchain/            ← 编译器检测管理
+├── modgraph/             ← 模块图扫描验证
+├── pack/                 ← 打包发布
+└── xlings.cppm           ← xlings 抽象层
+tests/e2e/                ← E2E 测试脚本
+docs/                     ← 用户文档
+.agents/docs/             ← 设计文档
+.agents/skills/           ← Agent 技能文档
+```
+
+## 注意事项
+
+- C++23 模块项目，修改模块时注意 import 依赖顺序
+- E2E 测试应独立运行，不依赖网络
+- 不确定方向时先在 Issue 讨论再动手
diff --git a/.agents/skills/mcpp-usage/SKILL.md b/.agents/skills/mcpp-usage/SKILL.md
new file mode 100644
index 0000000..d5472dc
--- /dev/null
+++ b/.agents/skills/mcpp-usage/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: mcpp-usage
+description: Use when helping users install, configure, or use mcpp — the C++23 modular build tool. Covers installation, project creation, building, dependency management, toolchain management, workspace setup, packaging, diagnostics, and troubleshooting.
+---
+
+# mcpp 基础用法
+
+## Overview
+
+mcpp 是一个现代 C++ 模块化构建工具，纯 C++23 模块编写，已实现自举。一条命令安装，`import std` 开箱即用。
+
+- 仓库：https://github.com/mcpp-community/mcpp
+- 文档：https://github.com/mcpp-community/mcpp/tree/main/docs
+- 包索引：https://github.com/mcpp-community/mcpp-index
+- 模块化库：https://github.com/mcpplibs
+
+## Quick Reference
+
+| 命令 | 用途 |
+|---|---|
+| `mcpp new <name>` | 创建项目 |
+| `mcpp build` | 构建 |
+| `mcpp run [-- args]` | 构建并运行 |
+| `mcpp test [-- args]` | 运行测试 |
+| `mcpp add <pkg>[@ver]` | 添加依赖 |
+| `mcpp remove <pkg>` | 移除依赖 |
+| `mcpp update [pkg]` | 更新依赖 |
+| `mcpp search <keyword>` | 搜索包 |
+| `mcpp toolchain list` | 查看工具链 |
+| `mcpp toolchain install gcc 16` | 安装工具链 |
+| `mcpp pack` | 打包 |
+| `mcpp self doctor` | 环境诊断 |
+| `mcpp explain <CODE>` | 错误码解释 |
+
+## 安装
+
+```bash
+# 推荐
+xlings install mcpp -y
+
+# 或一键脚本
+curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
+```
+
+安装到 `~/.mcpp/`，自动加入 PATH。首次运行自动安装 GCC 工具链到隔离沙盒。
+
+## 创建项目
+
+```bash
+mcpp new hello && cd hello
+mcpp build
+mcpp run
+```
+
+生成的 `mcpp.toml`：
+
+```toml
+[package]
+name = "hello"
+
+[targets.hello]
+kind = "bin"
+main = "src/main.cpp"
+```
+
+## mcpp.toml 配置
+
+```toml
+[package]
+name = "myapp"
+version = "0.1.0"
+
+[targets.myapp]
+kind = "bin"                # bin / lib / shared / test
+main = "src/main.cpp"
+
+[dependencies]
+gtest = "1.15.2"            # SemVer: ^, ~, 范围, 精确
+
+[toolchain]
+default = "gcc@16.1.0"
+```
+
+更多配置：https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
+
+## 工具链
+
+```bash
+mcpp toolchain list                   # 查看已装
+mcpp toolchain install gcc 16         # 装 GCC 16
+mcpp toolchain install llvm 20        # 装 LLVM 20
+mcpp toolchain default gcc@16.1.0    # 设默认
+```
+
+## 工作空间
+
+```toml
+[workspace]
+members = ["libs/*", "apps/*"]
+
+[workspace.dependencies]
+gtest = "1.15.2"
+```
+
+```bash
+mcpp build -p member-name    # 构建指定成员
+```
+
+## 自定义索引
+
+```toml
+[indices]
+my-index = "git@gitlab.example.com:team/index.git"
+local = { path = "/path/to/index" }
+
+[dependencies.my-index]
+internal-lib = "1.0.0"
+```
+
+## 常见问题
+
+| 问题 | 解决 |
+|---|---|
+| 首次构建慢 | 正常，需下载工具链。后续使用缓存 |
+| command not found | 重启终端或 `source ~/.bashrc` |
+| 编译错误 | `mcpp clean && mcpp build`，确认 `mcpp toolchain list` |
+| 依赖找不到 | `mcpp index update`，确认 `mcpp search <name>` |
+
+## 问题反馈
+
+1. **项目 Issue**：https://github.com/mcpp-community/mcpp/issues
+   - 描述复现步骤、期望/实际行为、mcpp 版本和 OS
+   - 可用 `gh issue create` 提交
+
+2. **社区论坛**：https://forum.d2learn.org/category/20
+   - 使用疑问和讨论
+
+如果 AI Agent 无法直接创建 Issue，请提示用户手动创建并提供整理好的问题描述。
diff --git a/README.md b/README.md
index 5f83289..017c38d 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,83 @@
 # mcpp
 
-> 一个 **现代C++** 构建工具 - *`模块化 + 依赖/工具链管理 + 包索引 + 打包发布`*
+> 一个 现代C++ 模块化构建工具 — 纯 C++23 模块编写，已实现自举
 
+[![Release](https://img.shields.io/github/v/release/mcpp-community/mcpp)](https://github.com/mcpp-community/mcpp/releases)
 [![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
+[![Self-hosted](https://img.shields.io/badge/build-self--hosted-brightgreen)]()
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
 
-`mcpp` 使用 C++23 完全模块化的工程结构进行开发, 且已经初步完成自举 (使用工具本身从源码构建出自己). 具备 项目构建、依赖自动处理、工具链管理、构建产物打包导出、模块化包索引等基础功能.
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/6c85896e-9a37-4f62-acfb-d37a4eae2363" alt="mcpp demo" width="720">
+</p>
 
-> [!CAUTION]
-> **初步开发中（WIP）** — 工具任然处于探索阶段。
-> 接口、命令、行为可能在后续版本调整。问题 / 反馈 / 想法欢迎在
-> [issues](https://github.com/mcpp-community/mcpp/issues) 留言。
+## 核心特性
+
+- **C++23 模块原生支持** — `import std` 自动处理，文件级增量构建，模块依赖自动分析，零手动配置
+- **纯模块化自举** — mcpp 自身由 43+ 个 C++23 模块组成，用自己构建自己，模块系统经实战验证
+- **开箱即用** — 一条命令安装，内置 GCC 16 / LLVM 20 工具链，自动下载到隔离沙盒，不污染系统
+- **集成依赖管理** — SemVer 约束解析、锁文件、跨项目 BMI 缓存、自定义包索引
+- **多包工作空间** — Workspace 统一锁文件与版本管理，适合大型项目
+
+## 为什么选择 mcpp
+
+mcpp 专门为 **C++23 模块化开发** 打造。如果你想在项目中使用 `import std`、模块接口单元（`.cppm`）、模块分区等现代 C++ 特性，mcpp 在 Linux 上能为你提供便捷且友好的开发体验：
+
+- **默认模块化** — `mcpp new` 创建的项目模板直接使用 C++23 模块，`import std` 开箱即用
+- **文件级增量构建** — 基于 P1689 dyndep 的三层优化（前端脏检查 + 逐文件扫描 + BMI restat），只重编真正变化的模块
+- **一键创建 & 构建** — `mcpp new hello && cd hello && mcpp build`，工具链自动安装，无需手动配置编译器和构建系统
+- **模块化生态** — [mcpplibs](https://github.com/mcpplibs) 提供一系列可直接 `import` 的 C++ 模块化库，支持自定义包索引
+
+> [!NOTE]
+> **早期版本** — mcpp 仍在积极开发中，接口和行为可能在后续版本调整。
+> 欢迎对现代 C++ 模块化构建工具感兴趣的开发者[参与贡献](#参与贡献)。
+> 问题 / 反馈 / 想法欢迎在 [issues](https://github.com/mcpp-community/mcpp/issues) 留言。
 
 ## 快速开始
 
 ### 安装
 
-<details>
-  <summary>点击获取xlings安装命令</summary>
+**方式一：使用 xlings 安装（推荐）**
 
----
+```bash
+xlings install mcpp -y
+```
 
-#### Linux/MacOS
+<details>
+<summary>还没有 xlings？点击查看安装命令</summary>
 
+**Linux / macOS**
 ```bash
 curl -fsSL https://d2learn.org/xlings-install.sh | bash
 ```
 
-#### Windows - PowerShell
-
-```bash
+**Windows — PowerShell**
+```powershell
 irm https://d2learn.org/xlings-install.ps1.txt | iex
 ```
 
-> tips: xlings -> [details](https://xlings.d2learn.org)
-
----
+> xlings 详情 → [xlings.d2learn.org](https://xlings.d2learn.org)
 
 </details>
 
-**`方法一: 使用xlings包管理器进行安装(推荐)`**
+**方式二：一键安装脚本**
 
 ```bash
-xlings install mcpp -y
+curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
 ```
 
-**`方法二: 使用一键安装命令`**
+安装到 `~/.mcpp/`，自动加进 shell PATH。删除 `~/.mcpp` 即可干净卸载。
 
-```bash
-curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
-```
+**方式三：让 AI 助手帮你安装**
 
-注: 会装到 `~/.mcpp/`，自动加进 shell PATH。删除 `~/.mcpp` 即可卸载。
+将以下提示词复制给你的 AI 编码助手（Claude Code / Cursor / Copilot 等）：
+
+```
+阅读 https://github.com/mcpp-community/mcpp 的 README，
+帮我安装 mcpp 并创建一个 C++23 模块项目，构建并运行。
+项目的 .agents/skills/mcpp-usage/SKILL.md 有详细的使用指南。
+```
 
 ### 创建项目 & 构建运行
 
@@ -63,46 +88,185 @@ mcpp build
 mcpp run
 ```
 
-注: 初次构建需要初始化环境并获取工具链, 可能需要一些时间
+> 注：首次构建会初始化环境并获取工具链，可能需要一些时间。
+
+### 项目结构
+
+```
+hello/
+├── mcpp.toml             ← 工程描述
+└── src/
+    └── main.cpp          ← import std; 直接可用
+```
+
+```toml
+# mcpp.toml
+[package]
+name = "hello"
+
+[targets.hello]
+kind = "bin"
+main = "src/main.cpp"
+```
+
+### 使用模块化库
+
+在 `mcpp.toml` 中添加两行依赖，即可引用 [mcpplibs](https://github.com/mcpplibs) 社区模块化库：
+
+```toml
+[dependencies]
+cmdline = "0.0.2"
+```
+
+然后在代码中直接 `import`：
+
+```cpp
+import mcpplibs.cmdline;
+```
+
+> 更多依赖配置方式（版本约束、命名空间、Git 引用、本地路径等）参见 [mcpp.toml 指南 — 依赖管理](docs/05-mcpp-toml.md)。
+
+## 功能概览
+
+<details>
+<summary><b>构建系统</b></summary>
+
+- C++20/23 模块原生支持（接口单元、实现单元、模块分区）
+- `import std` / `import std.compat` 全自动预编译与缓存
+- 三层增量优化：前端脏检查 + 逐文件 P1689 dyndep + BMI copy-if-different restat
+- 指纹化 BMI 缓存：按编译器/标志/标准库哈希，跨项目共享
+- Ninja 后端：自动生成 build.ninja，并行编译
+- compile_commands.json 自动生成（clangd / ccls 即用）
+- C 语言一等支持：`.c` 文件自动检测，混合 C/C++ 项目
+- 用户自定义 cflags / cxxflags / c_standard
+
+</details>
+
+<details>
+<summary><b>工具链管理</b></summary>
+
+- 内置 GCC 16.1.0 + LLVM/Clang 20.1.7，一键安装
+- musl-gcc 全静态工具链（默认）
+- 多版本共存：`mcpp toolchain install gcc 16` / `mcpp toolchain install llvm 20`
+- 隔离沙盒：所有工具链在 `~/.mcpp/registry/`，不影响系统
+- 按平台指定：`linux = "gcc@16"`, `macos = "llvm@20"`
+- GCC + Clang 编译管线平权（`BmiTraits` 抽象层驱动）
+
+</details>
+
+<details>
+<summary><b>包管理与依赖</b></summary>
+
+- SemVer 约束解析：`^`、`~`、范围、精确版本
+- 三级解析：约束合并 → 多版本 mangling 回退 → 精确匹配
+- 锁文件 mcpp.lock（v2 格式：索引快照 + 命名空间）
+- 命名空间系统：`[dependencies.myteam] foo = "1.0"`
+- 自定义包索引：`[indices] acme = "git@..."` / `{ path = "..." }`
+- 项目级索引隔离（`.mcpp/` 目录，不污染全局）
+- 依赖来源：索引 / Git / 本地路径
+
+</details>
+
+<details>
+<summary><b>工作空间</b></summary>
+
+- `[workspace] members = ["libs/*", "apps/*"]`
+- 统一锁文件 + 统一 target 目录
+- 版本集中管理：`[workspace.dependencies]` + `.workspace = true`
+- 选择性构建：`mcpp build -p member-name`
+- 配置继承：工具链、构建标志、索引从根级联到成员
+
+</details>
+
+<details>
+<summary><b>打包与发布</b></summary>
+
+- `mcpp pack`：三种模式 — static（musl全静态）/ bundle-project / bundle-all
+- musl 全静态二进制：单文件可分发，无 glibc 依赖
+- `mcpp publish`：生成 xpkg.lua + 发布到包索引
+- 自动 patchelf 修正 RPATH
+
+</details>
+
+<details>
+<summary><b>开发体验</b></summary>
+
+- `mcpp new` — 创建模块化项目模板
+- `mcpp run [-- args]` — 构建并运行
+- `mcpp test [-- args]` — 自动发现并运行测试
+- `mcpp search` — 搜索包索引
+- `mcpp add / remove / update` — 依赖管理
+- `mcpp explain E0001` — 错误码详细解释
+- `mcpp self doctor` — 环境自诊断
+
+</details>
+
+## 平台支持
+
+| OS / arch        | GCC (glibc) | GCC (musl) | Clang / LLVM | MSVC |
+|------------------|:-----------:|:----------:|:------------:|:----:|
+| Linux x86_64     | ✅ | ✅ *默认* | ✅ | — |
+| Linux aarch64    | 🔄 | 🔄 | 🔄 | — |
+| macOS            | — | — | 🔄 | — |
+| Windows          | — | — | 🔄 | 🔄 |
+
+✅ 已支持 ｜ 🔄 计划中
+
+> *默认*：release 二进制走 musl 全静态，Linux x86_64 可直接运行，无 glibc 依赖。
 
 ## 文档
 
-- [快速开始](docs/00-getting-started.md)
+- [快速开始](docs/00-getting-started.md) — 5 分钟完成 install → new → build → run
 - [示例项目](docs/01-examples.md)
 - [发布打包](docs/02-pack-and-release.md)
 - [工具链管理](docs/03-toolchains.md)
-- [从源码构建 & 参与贡献](docs/04-build-from-source.md)
-- [mcpp.toml 工程文件指南](docs/05-mcpp-toml.md)
-- [工作空间 (Workspace)](docs/06-workspace.md)
+- [从源码构建](docs/04-build-from-source.md)
+- [mcpp.toml 指南](docs/05-mcpp-toml.md)
+- [工作空间](docs/06-workspace.md)
 
 任意命令的完整选项可通过 `mcpp <cmd> --help` 查阅。
 
-## 平台支持
+**AI 辅助学习**：你可以将以下提示词发给 AI 编码助手，让它帮你快速了解 mcpp：
 
-OS × 工具链矩阵：
+```
+阅读 https://github.com/mcpp-community/mcpp 仓库的
+.agents/skills/mcpp-usage/SKILL.md 和 docs/ 目录下的文档，
+告诉我如何用 mcpp 创建一个带依赖的 C++23 模块项目。
+```
 
-| OS / arch        | gcc (glibc) | gcc (musl) | clang / llvm | msvc |
-|------------------|:-----------:|:----------:|:------------:|:----:|
-| Linux x86_64     | ✅ | ✅ *默认* | 🔄 | — |
-| Linux aarch64    | 🔄 | 🔄 | 🔄 | — |
-| macOS x86_64     | — | — | 🔄 | — |
-| macOS aarch64    | — | — | 🔄 | — |
-| Windows x86_64   | — | — | 🔄 | 🔄 |
+## 参与贡献
+
+欢迎通过 Issue 和 PR 参与项目开发。项目接受开发者使用 AI Agent 参与开发与贡献。
+
+**基本流程**
 
-图例：✅ 已支持 ｜ 🔄 计划中 
+1. 创建 Issue — Bug 修复、新功能、优化等，先在 [issues](https://github.com/mcpp-community/mcpp/issues) 创建讨论
+2. 实现改动 — Fork 仓库，创建分支，实现并验证（`mcpp build` + E2E 测试）
+3. 提交 PR — 使用 `gh pr create`，确保 CI 通过
+4. CI 必须通过 — CI 不通过的 PR 不会被合入
 
-> *默认*：v0.0.1 release 二进制走 musl 全静态路径，Linux x86_64 可以直接运行。
+**提交信息规范**：`feat:` / `fix:` / `test:` / `docs:` / `refactor:` 前缀
+
+**AI Agent 贡献**：项目的 [`.agents/skills/mcpp-contributing/SKILL.md`](.agents/skills/mcpp-contributing/SKILL.md) 提供了完整的 Agent 贡献流程和项目结构说明。将以下提示词发给 AI 助手即可：
+
+```
+阅读 https://github.com/mcpp-community/mcpp 仓库的
+.agents/skills/mcpp-contributing/SKILL.md，
+按照指南帮我给 mcpp 项目提交一个贡献。
+```
 
 ## 社区 & 生态
 
-- [社区论坛](https://forum.d2learn.org/category/20) - 交流群(Q: 1067245099)
+- [社区论坛](https://forum.d2learn.org/category/20) — 交流群 (Q: 1067245099)
 - [mcpp-index](https://github.com/mcpp-community/mcpp-index) — 默认包索引
-- [mcpplibs](https://github.com/mcpplibs) - 一个"模块化"的现代C++库集合
+- [mcpplibs](https://github.com/mcpplibs) — 模块化 C++ 库集合
+
+### 致谢
 
-项目依赖的和部分有灵感启发来源的工具和库
+项目依赖和灵感来源：
 
-  - [xlings](https://github.com/d2learn/xlings) — 工具链 / 包管理底座
-  - [mcpplibs.cmdline](https://github.com/mcpplibs/cmdline) — mcpp 自身用的 CLI 框架
-  - [ninja](https://github.com/ninja-build/ninja) — a small build system with a focus on speed
-  - [xmake](https://github.com/xmake-io/xmake) — A cross-platform build utility based on Lua
-  - [cargo](https://github.com/rust-lang/cargo) — The Rust package manager
\ No newline at end of file
+- [xlings](https://github.com/d2learn/xlings) — 工具链 / 包管理底座
+- [mcpplibs.cmdline](https://github.com/mcpplibs/cmdline) — CLI 框架
+- [ninja](https://github.com/ninja-build/ninja) — 底层构建引擎
+- [xmake](https://github.com/xmake-io/xmake) — 跨平台构建工具
+- [cargo](https://github.com/rust-lang/cargo) — Rust 包管理器