diff --git a/docs/api-skill.md b/docs/api-skill.md
index 0827528b..5d64ebf2 100644
--- a/docs/api-skill.md
+++ b/docs/api-skill.md
@@ -8,9 +8,10 @@
 
 1. `docs/api/XCEngine/**` 必须与 `engine/include/XCEngine/**` 保持平行。
 2. canonical API 文档只保留一套；迁移完成后必须删除旧目录与旧入口。
-3. 每个 public header 对应一个独立文档目录，每个类型页都使用 `{TypeName}/{TypeName}.md`。
+3. 默认情况下，每个 public header 对应一个独立文档目录，每个类型页都使用 `{TypeName}/{TypeName}.md`。
 4. 方法页优先使用源码中的原始函数名；不要改成 kebab-case、全小写或其它再命名形式。
 5. API 文档必须以源码、实现、测试和真实调用点为依据，禁止只根据名字猜测行为。
+6. 对于只承担聚合包含职责的 umbrella header，可以并入模块页说明，不强制再建一个同名类型目录。
 
 ## Canonical 目录结构
 
@@ -60,6 +61,7 @@ docs/api/
 - 每个 public header 对应一个独立文件夹。
 - 文件夹名必须与 header stem 或主要类型名一致。
 - 保留源码中的大小写，不做风格改写。
+- 如果 header 只是模块聚合入口，不声明独立类型，可以直接并入模块页，不单独建文件夹。
 
 示例：
 
@@ -122,6 +124,20 @@ docs/api/
 - 把“设计意图”当成“当前实现行为”来写。
 - 把测试里假设成立的场景，误写成通用保证。
 
+## umbrella header 例外规则
+
+以下情况通常应视为模块聚合头，而不是单独类型页：
+
+- 头文件主要由一组 `#include` 组成。
+- 不声明独立类、结构体、枚举或函数族。
+- 名称与模块目录同名，单独建页会造成 `Debug/Debug.md` 这类重复入口。
+
+处理方式：
+
+- 在模块页中增加“聚合头文件”或“包含入口”小节。
+- 使用 `**头文件**: \`...\`` 保留头文件覆盖记录。
+- 不再额外创建 `{HeaderStem}/{HeaderStem}.md`。
+
 ## 契约分层规则
 
 文档必须明确区分下面三层信息：
diff --git a/docs/api/XCEngine/Debug/Debug.md b/docs/api/XCEngine/Debug/Debug.md
index a9cf2078..ff14e31b 100644
--- a/docs/api/XCEngine/Debug/Debug.md
+++ b/docs/api/XCEngine/Debug/Debug.md
@@ -27,10 +27,18 @@
 - `Profiler` 和 `RenderDocCapture` 都采用单例，目的是让工具、测试和引擎运行时共享一套调试入口。
 - 该模块偏开发期工具能力，不追求零侵入；一些 API 会主动写日志、刷新文件或拉起窗口焦点。
 
+## 聚合头文件
+
+**头文件**: `XCEngine/Debug/Debug.h`
+
+`Debug.h` 是这个模块的 umbrella header。它本身不代表新的运行时类型，而是把 `Logger`、`Profiler`、`RenderDocCapture` 等常用 public header 聚合成一个便利入口。
+
+对读者来说，最合理的入口仍然是当前这页，而不是再进入一个同名的 `Debug/Debug.md` 类型页。
+
 ## 头文件
 
 - [ConsoleLogSink](ConsoleLogSink/ConsoleLogSink.md) - `ConsoleLogSink.h`，面向 `stdout` 的日志输出 sink。
-- [Debug](Debug/Debug.md) - `Debug.h`，聚合调试模块所有 public header 的便利入口。
+- `Debug.h` - 模块聚合头，说明已并入当前页。
 - [FileLogSink](FileLogSink/FileLogSink.md) - `FileLogSink.h`，将日志追加写入文件。
 - [ILogSink](ILogSink/ILogSink.md) - `ILogSink.h`，日志输出目标接口。
 - [LogCategory](LogCategory/LogCategory.md) - `LogCategory.h`，日志功能分类枚举。
diff --git a/docs/api/XCEngine/Debug/Debug/Debug.md b/docs/api/XCEngine/Debug/Debug/Debug.md
deleted file mode 100644
index 1c8a8813..00000000
--- a/docs/api/XCEngine/Debug/Debug/Debug.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# Debug
-
-**命名空间**: `XCEngine::Debug`
-
-**类型**: `header-umbrella`
-
-**头文件**: `XCEngine/Debug/Debug.h`
-
-**描述**: 聚合调试模块主要 public header 的便利包含入口。
-
-## 概述
-
-`Debug.h` 自身不定义新的核心类型，它的主要作用是把调试子系统的常用头文件集中包含进来，方便工具程序、测试程序或示例快速接入调试能力。
-
-当前头文件会聚合：
-
-- `LogLevel.h`
-- `LogCategory.h`
-- `LogEntry.h`
-- `ILogSink.h`
-- `ConsoleLogSink.h`
-- `FileLogSink.h`
-- `Logger.h`
-- `Profiler.h`
-- `RenderDocCapture.h`
-- `../Core/FileWriter.h`
-
-## 设计建议
-
-- 对于快速原型、测试或示例程序，直接包含 `Debug.h` 比逐个包含更方便。
-- 对于大型模块或编译敏感代码，建议只包含真正需要的具体头文件，避免不必要的编译依赖扩散。
-- `Logger.h` 与 `Profiler.h` 中定义的重要宏分别是 `XE_LOG`、`XE_ASSERT`、`XE_PROFILE_BEGIN`、`XE_PROFILE_END` 和 `XE_PROFILE_FUNCTION`。
-
-## 声明概览
-
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `Debug.h` | umbrella header | 调试模块的快速入口，而不是独立运行时对象。 |
-
-## 相关文档
-
-- [当前模块](../Debug.md)
-- [Logger](../Logger/Logger.md)
-- [Profiler](../Profiler/Profiler.md)
-- [RenderDocCapture](../RenderDocCapture/RenderDocCapture.md)
-- [Logging Architecture](../../../_guides/Debug/Logging-Architecture.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index 128365c7..d10a6a92 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,13 +1,13 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-26 17:20:45`
+**生成时间**: `2026-03-26 17:25:36`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`
 
 ## 摘要
 
-- Markdown 页面数（全部）: `2443`
-- Markdown 页面数（canonical）: `2437`
+- Markdown 页面数（全部）: `2442`
+- Markdown 页面数（canonical）: `2436`
 - Public headers 数: `185`
 - 有效头文件引用数（全部）: `185`
 - 有效头文件引用数（canonical）: `185`
@@ -45,7 +45,7 @@
 
 | 字段 | 页面数 |
 |------|--------|
-| `命名空间` | `209` |
-| `类型` | `209` |
-| `描述` | `209` |
+| `命名空间` | `208` |
+| `类型` | `208` |
+| `描述` | `208` |
 | `头文件` | `185` |