diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md
index 7a496c5b..d1ea7d4f 100644
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@@ -13,6 +13,8 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 2. 再进专题页确认安装、生命周期和推荐接线方式
 3. 最后回到源码中的 XML 文档核对具体契约
 
+如果你在阅读 AI-First 配置工作流相关 API，先把 `GFramework.Game` Runtime 与 `GFramework.Game.SourceGenerators` 视为正式契约入口，再把 `VS Code` 配置工具视为辅助层。当前默认采用路径围绕共享 schema 子集展开，其中 `additionalProperties: false` 表示闭合对象边界，`oneOf` / `anyOf` 不在默认入口范围内；更复杂的 shape 应回到 raw YAML 与 schema 设计本体处理。
+
 ## 阅读顺序
 
 ### 安装与选包入口
@@ -30,7 +32,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 | --- | --- | --- | --- |
 | `Core` / `Core.Abstractions` | [Core 模块](../core/index.md) | [Core 抽象层说明](../abstractions/core-abstractions.md)、[快速开始](../getting-started/quick-start.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
 | `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md) | [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)、[协程系统](../core/coroutine.md) | request / notification / handler / pipeline / generated registry / targeted fallback contract |
-| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 模块总览](../game/index.md) | [Game 抽象层说明](../abstractions/game-abstractions.md)、[配置系统](../game/config-system.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
+| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 模块总览](../game/index.md) | [Game 抽象层说明](../abstractions/game-abstractions.md)、[配置系统](../game/config-system.md) | 配置、数据、设置、场景、UI、存储、序列化契约；其中 AI-First 配置工作流的正式支持边界以 Runtime + Generator 共享 schema 子集为准 |
 | `Godot` / `Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md) | [Godot 项目生成器](../source-generators/godot-project-generator.md)、[GetNode 生成器](../source-generators/get-node-generator.md)、[BindNodeSignal 生成器](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
 | `Ecs.Arch` / `Ecs.Arch.Abstractions` | [ECS 模块总览](../ecs/index.md) | [Arch ECS 集成](../ecs/arch.md)、[Ecs.Arch 抽象层说明](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
 
@@ -60,6 +62,9 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 - 最佳实践：[最佳实践](../best-practices/index.md)
 - 故障排查：[故障排查](../troubleshooting.md)
 
+如果你阅读的是 AI-First 配置相关 API，请直接把 [配置系统](../game/config-system.md) 视为边界说明页：
+像 `additionalProperties: false`、`oneOf` / `anyOf` rejection 这类采用约束不会由 VS Code 工具或 abstractions 页面单独改写。
+
 ## 共享支撑层怎么看
 
 - `GFramework.Core.SourceGenerators.Abstractions`
diff --git a/docs/zh-CN/getting-started/index.md b/docs/zh-CN/getting-started/index.md
index addf0b4e..49c3ca59 100644
--- a/docs/zh-CN/getting-started/index.md
+++ b/docs/zh-CN/getting-started/index.md
@@ -70,12 +70,18 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
 - Scene / UI / Routing 抽象与运行时
 - 文件存储和序列化
 
+AI-First 配置工作流的正式契约以 `GFramework.Game` Runtime 与 `GFramework.Game.SourceGenerators` 的共享 schema 子集为准，`VS Code` 配置工具只负责辅助编辑与预览。默认采用路径当前以 `additionalProperties: false` 作为闭合对象边界，`oneOf` / `anyOf` 不在默认入口范围内；如果你的 schema shape 超出这组共享边界，优先回到 raw YAML 与 schema 设计本体继续建模。
+
 对应文档：
 
 - [Game 模块总览](../game/index.md)
 - [配置系统](../game/config-system.md)
 - [安装配置](./installation.md)
 
+如果你准备采用 AI-First 配置工作流，建议尽早确认当前采用边界：对象闭合只收口到
+`additionalProperties: false`，而 `oneOf` / `anyOf` 这类会改变生成类型形状的组合关键字当前不属于默认路径。
+超过这组共享子集的复杂 schema shape，应回到 raw YAML 与 schema 本体设计，而不是把差异理解成工具遗漏。
+
 ### Godot 项目接入
 
 继续叠加：
@@ -104,6 +110,8 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
 - 为 CQRS handlers 生成注册表
 - 生成 Godot 节点、场景和 UI 包装代码
 
+如果你要处理的是更复杂的 schema 设计，而不是编译期生成代码本身，先确认它是否仍在 `Game` Runtime 与生成器共享子集内；超出时应优先调整 raw YAML / schema 方案，而不是假定编辑器入口少了某个开关。
+
 继续阅读：
 
 - [源码生成器总览](../source-generators/index.md)
diff --git a/docs/zh-CN/index.md b/docs/zh-CN/index.md
index 7ce41a08..00291001 100644
--- a/docs/zh-CN/index.md
+++ b/docs/zh-CN/index.md
@@ -38,8 +38,10 @@ features:
     details: 在保持 Core / Game 运行时边界的前提下，补齐节点扩展、场景与 UI 接线、协程桥接和生成器辅助。
 
   - title: 🧩 AI-First 配置工作流
-    details: 通过 YAML + JSON Schema + Source Generator + VS Code 工具，把静态内容配置、校验、表单预览和批量编辑串成一条链路。
+    details: 通过 YAML + JSON Schema + Source Generator + VS Code 工具，把静态内容配置、校验、表单预览和批量编辑串成一条链路；正式契约来自 `GFramework.Game` Runtime 与 `GFramework.Game.SourceGenerators` 的共享 schema 子集，编辑器工具只负责辅助编辑与预览。
 
   - title: ⚡ Roslyn 源码生成器
     details: 自动生成日志、上下文注入、配置类型、CQRS registry 和 Godot 辅助代码，并复用共享 diagnostics 约束生成行为。
 ---
+
+AI-First 配置工作流的默认采用路径以闭合对象模型为前提：当前使用 `additionalProperties: false` 作为对象边界，`oneOf` / `anyOf` 不在默认入口范围内。遇到超出共享 schema 子集的复杂 shape，请直接回到 raw YAML 与 schema 设计本体处理，而不是把它当成编辑器能力遗漏。