diff --git a/README.md b/README.md
index 936ac3c..f520414 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,7 @@ mcpp run
 - [发布打包](docs/02-pack-and-release.md)
 - [工具链管理](docs/03-toolchains.md)
 - [从源码构建 & 参与贡献](docs/04-build-from-source.md)
+- [mcpp.toml 工程文件指南](docs/05-mcpp-toml.md)
 
 任意命令的完整选项可通过 `mcpp <cmd> --help` 查阅。
 
diff --git a/docs/05-mcpp-toml.md b/docs/05-mcpp-toml.md
new file mode 100644
index 0000000..ae53aab
--- /dev/null
+++ b/docs/05-mcpp-toml.md
@@ -0,0 +1,292 @@
+# mcpp.toml 工程文件指南
+
+`mcpp.toml` 是 mcpp 构建工具的项目配置文件,类似 Cargo 的 `Cargo.toml` 或 Node 的 `package.json`。放在项目根目录下,`mcpp build` 会自动发现并读取它。
+
+## 1. 最小化示例
+
+mcpp 的设计原则是 **约定优于配置** —— 大多数字段都有合理默认值,最简单的 `mcpp.toml` 只需几行:
+
+### 1.1 可执行程序（最简）
+
+```toml
+[package]
+name    = "hello"
+version = "0.1.0"
+```
+
+mcpp 自动推断:
+- 源文件: `src/**/*.{cppm,cpp,cc,c}`
+- 入口: `src/main.cpp` → 生成 `hello` 二进制
+- 标准: C++23
+- 模块: 扫描 `export module ...` 声明自动建立依赖图
+
+### 1.2 库项目（最简）
+
+```toml
+[package]
+name    = "mylib"
+version = "0.1.0"
+
+[targets.mylib]
+kind = "lib"
+```
+
+lib-root 约定:主模块接口默认在 `src/mylib.cppm`(包名的最后一段)。
+
+## 2. 完整字段参考
+
+### 2.1 `[package]` — 包元数据
+
+```toml
+[package]
+name        = "myapp"              # 包名(必填)
+version     = "0.1.0"              # 语义化版本(必填)
+description = "My awesome app"     # 简介(可选)
+license     = "MIT"                # 许可证(可选)
+authors     = ["Alice", "Bob"]     # 作者列表(可选)
+repo        = "https://github.com/user/myapp"  # 仓库地址(可选)
+```
+
+### 2.2 `[targets.<name>]` — 构建目标
+
+```toml
+# 可执行程序(默认,有 src/main.cpp 时自动推断)
+[targets.myapp]
+kind = "bin"
+main = "src/main.cpp"       # 可选,默认 src/main.cpp
+
+# 静态库
+[targets.mylib]
+kind = "lib"
+
+# 共享库
+[targets.mylib]
+kind = "shared"
+```
+
+### 2.3 `[build]` — 构建配置
+
+```toml
+[build]
+sources      = ["src/**/*.cppm", "src/**/*.cpp"]  # 源文件 glob(默认: src/**/*.{cppm,cpp,cc,c})
+include_dirs = ["include", "third_party/include"]  # 头文件搜索路径
+c_standard   = "c11"              # C 源文件的标准(默认 c11)
+cflags       = ["-DFOO=1"]        # 额外 C 编译参数
+cxxflags     = ["-DBAR=2"]        # 额外 C++ 编译参数
+static_stdlib = true               # 静态链接 libstdc++(默认 true)
+```
+
+**glob 排除**(`!` 前缀,mcpp 0.0.4+):
+
+```toml
+[build]
+sources = [
+    "src/**/*.cpp",
+    "!src/**/*_test.cpp",       # 排除测试文件
+    "!src/**/*_fuzzer.cpp",     # 排除 fuzzer
+]
+```
+
+### 2.4 `[lib]` — 库根模块约定
+
+```toml
+[lib]
+path = "src/capi/lua.cppm"    # 覆盖默认的 lib-root 位置
+```
+
+默认约定:`src/<包名最后一段>.cppm`(如包名 `mcpplibs.cmdline` → `src/cmdline.cppm`）。
+
+### 2.5 `[dependencies]` — 运行时依赖
+
+```toml
+# 默认命名空间(mcpp)下的包
+[dependencies]
+gtest   = "1.15.2"              # 精确版本
+mbedtls = "3.6.1"
+ftxui   = "6.1.9"
+
+# 命名空间子表写法
+[dependencies.mcpplibs]
+cmdline   = "0.0.2"
+tinyhttps = "0.2.2"
+llmapi    = "0.2.5"
+
+# 路径依赖(本地开发)
+[dependencies]
+mylib = { path = "../mylib" }
+
+# Git 依赖
+[dependencies]
+mylib = { git = "https://github.com/user/mylib.git", tag = "v1.0.0" }
+```
+
+**SemVer 约束**:
+
+```toml
+[dependencies]
+foo = "^1.2.3"      # >= 1.2.3, < 2.0.0 (caret,默认)
+bar = "~1.2.3"      # >= 1.2.3, < 1.3.0 (tilde)
+baz = "=1.2.3"      # 精确匹配
+qux = ">=1.0, <2.0" # 范围组合
+```
+
+### 2.6 `[dev-dependencies]` — 测试依赖
+
+```toml
+[dev-dependencies]
+gtest = "1.15.2"
+```
+
+`mcpp build` 忽略这些;`mcpp test` 解析并使用。`mcpp test` 会自动发现 `tests/**/*.cpp` 并编译为测试二进制。
+
+### 2.7 `[toolchain]` — 工具链配置
+
+```toml
+[toolchain]
+default = "gcc@16.1.0"
+
+# 跨编译目标覆盖
+[target.x86_64-linux-musl]
+toolchain = "gcc@15.1.0-musl"
+linkage   = "static"
+```
+
+## 3. 实战示例
+
+### 3.1 简单 Hello World
+
+```toml
+[package]
+name    = "hello"
+version = "0.1.0"
+```
+
+```cpp
+// src/main.cpp
+import std;
+int main() { std::println("Hello, mcpp!"); }
+```
+
+```bash
+mcpp build && mcpp run
+```
+
+### 3.2 模块化库 + 测试
+
+```toml
+[package]
+name    = "mymath"
+version = "1.0.0"
+
+[targets.mymath]
+kind = "lib"
+
+[dev-dependencies]
+gtest = "1.15.2"
+```
+
+```cpp
+// src/mymath.cppm
+export module mymath;
+export int add(int a, int b) { return a + b; }
+```
+
+```cpp
+// tests/test_add.cpp
+#include <gtest/gtest.h>
+import mymath;
+TEST(Math, Add) { EXPECT_EQ(add(1, 2), 3); }
+```
+
+```bash
+mcpp build   # 编译库
+mcpp test    # 编译 + 跑测试
+```
+
+### 3.3 依赖其他包的应用
+
+```toml
+[package]
+name    = "myapp"
+version = "0.1.0"
+
+[dependencies]
+ftxui = "6.1.9"
+
+[dependencies.mcpplibs]
+cmdline = "0.0.2"
+llmapi  = "0.2.5"
+```
+
+mcpp 自动:
+1. 从 mcpp-index 下载源码 tarball
+2. 按 `[build].include_dirs` 传播头文件路径
+3. 传递依赖自动入图(llmapi → tinyhttps → mbedtls 全自动)
+
+### 3.4 纯 C 库
+
+```toml
+[package]
+name    = "myc"
+version = "0.1.0"
+
+[build]
+c_standard   = "c99"
+include_dirs = ["include"]
+sources      = ["src/**/*.c"]
+
+[targets.myc]
+kind = "lib"
+```
+
+### 3.5 混合 C / C++23 模块项目
+
+```toml
+[package]
+name    = "hybrid"
+version = "0.1.0"
+
+[build]
+include_dirs = ["include"]
+c_standard   = "c11"
+
+[dependencies]
+lua = "5.4.7"     # 纯 C 库,mcpp 自动用 C 编译器编译 .c 文件
+
+[targets.hybrid]
+kind = "bin"
+```
+
+### 3.6 跨编译静态发布
+
+```toml
+[package]
+name    = "mytool"
+version = "1.0.0"
+
+[toolchain]
+default = "gcc@16.1.0"
+
+[target.x86_64-linux-musl]
+toolchain = "gcc@15.1.0-musl"
+linkage   = "static"
+```
+
+```bash
+mcpp build --target x86_64-linux-musl
+# → 产出完全静态链接的二进制,可直接 scp 到任意 Linux x86_64 机器运行
+```
+
+## 4. 约定与默认值速查
+
+| 项目 | 默认值 | 说明 |
+|---|---|---|
+| 源文件 | `src/**/*.{cppm,cpp,cc,c}` | 自动递归扫描 |
+| 入口 | `src/main.cpp` | 有这个文件就推断为 `bin` 目标 |
+| 库根 | `src/<pkg-tail>.cppm` | 可用 `[lib].path` 覆盖 |
+| 标准 | `c++23` | C++23 模块是一等公民 |
+| C 标准 | `c11` | `.c` 文件自动走 C 编译器 |
+| 静态 stdlib | `true` | 便携二进制 |
+| 头文件 | `include/`(如果存在） | 自动加到 `-I` |
+| 测试 | `tests/**/*.cpp` | `mcpp test` 自动发现 |
+| 依赖命名空间 | `mcpp`（默认) | 平铺写法走默认 ns |
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..9cc8b67
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,8 @@
+# 用户文档目录
+
+- [00 - 快速开始](00-getting-started.md)
+- [01 - 示例项目](01-examples.md)
+- [02 - 发布打包](02-pack-and-release.md)
+- [03 - 工具链管理](03-toolchains.md)
+- [04 - 从源码构建 & 参与贡献](04-build-from-source.md)
+- [05 - mcpp.toml 工程文件指南](05-mcpp-toml.md)