diff --git a/docs/02-user-guide/03-teaching/05-learning-feedback.md b/docs/02-user-guide/03-teaching/05-learning-feedback.md
index cd837c8..05318e5 100644
--- a/docs/02-user-guide/03-teaching/05-learning-feedback.md
+++ b/docs/02-user-guide/03-teaching/05-learning-feedback.md
@@ -91,10 +91,54 @@ keywords: [学习反馈, 反馈卡片, 确认学习, 纠正, 知识验证]
 - 来源对话
 - 当前状态（生效中 / 已撤销 / 已修改）
 
+## 学习存储机制
+
+了解学习内容的存储方式，有助于理解反馈卡片各字段的含义：
+
+| 存储位置 | 内容 | 说明 |
+|---------|------|------|
+| `memory/` 目录 | 事实、偏好、经验教训 | 每条记忆一个 `.md` 文件，带类型标签 |
+| `principles.md` | 行为规则和约束 | 经你确认的"必须做 / 绝不做"规则写入此处 |
+| `relationship.md` | 协作契约 | 双方的沟通约定和工作方式 |
+
+当你确认一条学习反馈后，智能体会根据知识类型将其写入对应文件。**撤销操作**则是将该条目标记为无效或从文件中移除。
+
+:::note 记忆 vs 规则
+- **记忆**：智能体"知道"的事实（如"用户喜欢深色模式"），影响回答内容
+- **规则**：智能体"必须遵守"的行为约束（如"绝不在邮件中使用感叹号"），影响行为方式
+:::
+
+## 一次对话中的多条学习
+
+在一次较长的教学对话中，智能体可能同时学到多条内容。此时你会看到多张反馈卡片依次出现：
+
+```
+你："记住三件事：
+    1. 周报用 Markdown 格式
+    2. 发给客户的邮件必须抄送项目经理
+    3. 代码注释用中文"
+
+智能体：[生成 3 张反馈卡片，分别对应格式偏好、邮件规则、注释规范]
+```
+
+你可以逐张确认、修改或撤销，互不影响。
+
+## 有效教学的最佳实践
+
+| 做法 | 效果 |
+|------|------|
+| ✅ 给出具体示例，而非抽象描述 | 智能体理解更准确，反馈卡片质量更高 |
+| ✅ 一次教一个主题 | 避免混淆，每张卡片对应一条清晰知识 |
+| ✅ 确认前仔细阅读"理解内容"字段 | 发现理解偏差的最佳时机 |
+| ✅ 纠正时说明"为什么"和"边界条件" | 智能体能泛化到类似场景 |
+| ❌ 教了就走，不看反馈 | 可能积累错误理解 |
+| ❌ 一次灌输大量不相关规则 | 容易混淆适用范围 |
+
 :::tip 建立定期复审习惯
 建议定期（比如每周）花几分钟检查智能体新学到的内容，确保一切都在正轨上。就像定期跟徒弟沟通一样——越早发现问题，纠正成本越低。
 :::
 
 :::info 下一步
-如果发现智能体学错了某些东西，需要撤销或让它遗忘怎么办？前往 [撤销与遗忘](./06-undo-forget.md) 了解操作方法。
+- 发现智能体学错了？前往 [撤销与遗忘](./06-undo-forget.md) 了解如何回退
+- 想了解教学背后的完整原语体系？回到 [六大原语](./02-six-primitives.md) 复习
 :::
diff --git a/docs/02-user-guide/04-delegation/02-plan-confirmation.md b/docs/02-user-guide/04-delegation/02-plan-confirmation.md
index f7b577f..2a6455e 100644
--- a/docs/02-user-guide/04-delegation/02-plan-confirmation.md
+++ b/docs/02-user-guide/04-delegation/02-plan-confirmation.md
@@ -1,111 +1,259 @@
 ---
-title: 计划文件与自然协作
-description: 了解智能体如何在工作目录维护可版本化计划，以及如何通过自然对话审阅、修改和继续执行。
-keywords: [计划, Plan, 审阅, 修订, 步骤, 工作目录, 版本]
-last-reviewed: 2026-07-23
+title: 计划确认
+description: 了解智能体如何制定执行计划、计划中包含什么信息、如何审阅修改计划，以及如何主动要求"先想清楚再动手"。
+keywords: [计划, Plan, 确认, 审阅, 步骤, 执行计划, Plan Mode, 强制规划]
 ---
 
-# 计划文件与自然协作
+# 计划确认
 
-对于需要执行工具、修改文件、委派、多步交付或产生外部影响的任务，智能体会先在当前工作目录建立或读取一份 Plan，再开始行动。
+当你下达一个任务后，智能体不会立即开始执行——它会先制定一份计划，等你审阅确认后才动手。
 
-Plan 是普通 Markdown 工作文件，不是需要开启的模式，也不是执行授权。你可以随时用自然语言补充、修改或停止方案；真正涉及敏感或高风险动作时，DesireCore 仍会在具体动作发生前触发权限确认或人闸门。
+## 为什么需要确认计划
 
-## Plan 为什么保存在项目中
+在现实中，你也不会让一个新来的同事直接开干。好的做法是：先让他说说打算怎么做，你觉得没问题了再让他动手。
 
-- **透明**：可以直接在编辑器中打开，不依赖聊天界面。
-- **可修改**：你可以手工编辑，智能体继续前会重新读取。
-- **可追溯**：每次实质修订保留一个不可变历史版本。
-- **跟项目走**：可以按团队习惯选择是否纳入 Git。
+这样做的好处是：
+- **发现误解**：智能体可能理解错了你的意图
+- **补充遗漏**：智能体可能遗漏了某个重要步骤
+- **调整策略**：你可能有更好的执行思路
+- **设置边界**：提前标记哪些步骤需要你确认
 
-## 哪些请求会建立 Plan
+## 智能体什么时候会主动制定计划
 
-| 请求类型 | 智能体行为 |
-|---|---|
-| 修改文件、运行执行性工具或操作外部系统 | 先创建或读取 Plan |
-| 委派其他智能体或完成多步交付 | 先创建或读取 Plan |
-| 信息不足 | 先写包含“待澄清项”的微型 Plan，再向你提问并修订 |
-| 执行中目标、约束或策略发生变化 | 先产生新版本，再继续行动 |
-| 纯问答、解释或寒暄 | 不创建 Plan 文件 |
+智能体会**自动判断**何时该先制定计划，何时可以直接动手。判断的依据是：
 
-Plan 规则是一项智能体行为规范，而不是会话锁或只读模式。它不会隐藏工具，也不会因为文件存在就绕过权限检查。
+| 任务特征 | 智能体的处理 |
+|---------|------------|
+| 涉及修改 3 个以上文件，或预计要执行 5 步以上 | 先制定计划 |
+| 包含**不可逆操作**（删除文件、发布版本、迁移数据、对外发送邮件等） | 先制定计划 |
+| 你明确说"先做计划"/"先想清楚"/"列一下步骤" | 先制定计划 |
+| 智能体自己也不太确定该怎么做 | 先制定计划 |
+| 单个文件的小修改 | 直接做 |
+| 纯查询、解释、读取信息 | 直接答 |
+| 你明确说"直接做"/"不用计划" | 直接做 |
 
-## 文件位置
+这就像一个有经验的同事——简单的小事不会动不动来找你确认，但碰到大事或有歧义的事一定会先问。
 
-每项任务使用独立目录：
+:::tip 想让智能体每次都先做计划？
+往下看「主动要求先做计划」一节——你可以**强制要求**智能体本次会话里任何任务都先制定计划，不管大小。
+:::
+
+## 计划包含哪些内容
+
+智能体制定的计划通常包含以下信息：
+
+![执行计划](/img/user-guide/delegation/plan-confirmation.svg)
+
+完整的计划是一份结构化 Markdown 文档，自动保存在 **当前工作目录** 的 `.desirecore/plans/<plan-id>/PLAN.md`（例如 `.desirecore/plans/plan-review-contract/PLAN.md`）。即便你关掉对话，文件也会留在那里，方便后续查阅或纳入版本控制。每次修订计划都会在 `revisions/` 子目录保存不可变历史版本。
+
+### 计划文件的标准结构
+
+每份计划是一份标准 Markdown 文件，位于智能体工作目录的 `.desirecore/plans/<plan-id>/PLAN.md`，采用 **YAML frontmatter + 正文** 的格式：
+
+```yaml
+---
+schema: 1
+id: plan-review-contract
+title: 审查采购合同
+revision: 1
+parent_revision: null
+created_at: 2026-07-27T10:00:00+08:00
+updated_at: 2026-07-27T10:00:00+08:00
+workdir: /path/to/workspace
+plan_path: /path/to/workspace/.desirecore/plans/plan-review-contract/PLAN.md
+scope: agent
+related_workdirs: []
+---
+
+# 审查采购合同
+
+## 目标
+审查附件中的采购合同，识别法律和商务风险。
 
-```text
-<当前工作目录>/.desirecore/plans/<plan-id>/
-├── PLAN.md
-└── revisions/
-    ├── 000001.md
-    ├── 000002.md
-    └── ...
+## 约束
+- 参照已教的合同审查规则
+- 不修改原始合同文件
+
+## 步骤
+1. 解析合同 PDF，提取条款文本
+2. 按已教规则逐条检查（违约金、付款条件等）
+3. 灵活分析进口设备条款
+4. 生成审查报告
+5. 保存草稿并等待确认
+
+## 验证
+- 报告中覆盖所有已教规则
+- 无遗漏的高风险条款
 ```
 
-- `PLAN.md` 保存当前版本。
-- `revisions/` 保存不可变历史。
-- 首次创建时，`PLAN.md` 与 `revisions/000001.md` 内容一致。
-- 恢复旧内容也会创建新版本，不会改写历史。
+**frontmatter 必填字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `schema` | 固定为 `1` |
+| `id` | 计划唯一标识（kebab-case） |
+| `title` | 计划标题 |
+| `revision` | 当前版本号（从 1 开始递增） |
+| `parent_revision` | 上一版本号（首版为 `null`） |
+| `created_at` | 创建时间（ISO 8601） |
+| `updated_at` | 最后更新时间 |
+| `workdir` | 工作目录绝对路径 |
+| `plan_path` | 计划文件自身绝对路径 |
+| `scope` | 作用域（`agent` 或 `team`） |
+| `related_workdirs` | 关联工作目录列表 |
+
+**正文**是自由 Markdown，通常包含 `## 目标`、`## 约束`、`## 步骤`、`## 验证` 等章节，内容由智能体根据任务特性灵活组织。
 
-DesireCore 不会自动修改项目的 `.gitignore`，也不会替你暂存或提交这些文件。
+每次修订计划时，系统会创建新的不可变历史版本（保存在 `revisions/` 子目录），PLAN.md 始终保留最新版。
 
-### 多个工作目录和团队目录
+### 步骤类型说明
+
+| 图标 | 类型 | 含义 |
+|------|------|------|
+| ⚙️ | **固化步骤** | 规则明确、结果确定的步骤，像程序一样执行 |
+| 🧠 | **灵活步骤** | 需要 AI 理解和判断的步骤，结果可能因情况而异 |
+| 🚪 | **人闸门** | 执行到此步骤时暂停，等待你的确认（计划中标注为 `confirm: yes` 的步骤） |
+
+:::info 风险等级 = 自动决定要不要确认
+每个步骤会标注 `risk: low | med | high`。**高风险步骤会自动设为"人闸门"**——这是智能体的纪律，避免在你没看到的时候做不可逆的操作。
+:::
+
+## 主动要求"先做计划"
+
+如果你希望智能体**每次都先做计划**（即便是简单任务），有三种方式可以**强制开启计划模式**——开启后，本次会话里所有任务都会经过"计划→审批→执行"流程，直到你关闭它或计划被批准后自动退出。
+
+### 方式 1：点击 📋 按钮
+
+聊天界面顶部右侧有一个 📋 Plan 按钮，点击切换。开启后会有明显视觉提示：
+
+- 按钮高亮（紫色背景）
+- 输入框边框变为紫色
+- 输入框 placeholder 提示"Plan Mode 已开启：发送的任务会先制定计划再执行"
+
+### 方式 2：快捷键 `Shift + Tab`
+
+在主界面（光标不在输入框时）按 `Shift + Tab`，与点击 📋 按钮等价。这是与 Claude Code 对齐的快捷键习惯。
+
+### 方式 3：斜杠命令 `/plan`
+
+在输入框打 `/plan` 提交：
+
+- 单独发送 `/plan` → 开启计划模式，不发任何消息
+- 发送 `/plan 帮我重构用户模块` → 开启计划模式 + 把 "帮我重构用户模块" 作为任务发出去
+
+:::tip 三种入口效果完全相同
+你可以按习惯选用任何一种。计划被批准（或拒绝）后，强制模式会**自动关闭**，你会看到一条 toast 提示"✓ Plan 已批准，开始执行"，无需手动关闭。
+:::
 
-- 普通会话按“智能体主目录/第一个有效目录 → 全局主目录/第一个有效目录”选择 cwd。
-- 你可以在输入框的工作目录胶囊或资源面板中点击团队共享目录，显式激活该会话的团队作用域；再次点击同一团队会退出。
-- 团队选择属于当前具体会话。发送消息时 DesireCore 会携带 `teamId`，后端再次校验成员身份和共享目录，校验失败不会静默回落。
-- 同时存在多个可访问目录时，一个任务仍只有一份权威 Plan。它固定写在当前 cwd，其他目录记录在 `related_workdirs` 中，跨目录操作使用绝对路径。
-- 如果创建团队时开启了“仅使用团队工作目录”，团队目录就是唯一项目工作目录和唯一 Plan 根目录，成员/全局目录不会写入 `related_workdirs`；成员原有目录设置不会被删除。
-- 任务进行中切换普通主目录不会搬迁旧 Plan；跨团队继续时，会在新团队目录建立新 Plan，并通过 `continued_from` 链接旧 Plan。
+### 强制模式与自动判断的区别
 
-运行中的会话不能切换工作目录作用域。空闲会话切换后，下一条消息会同时使用新的 cwd、文件权限、项目指引和 Plan 根目录，避免新旧目录混用。
+| 场景 | 不开启强制模式（默认） | 开启强制模式 |
+|------|----------------------|-------------|
+| 你问"1+1=?" | 直接回答 2 | 仍然先制定（很简单的）计划走一遍流程 |
+| 你说"帮我加个注释" | 单文件小修改，直接做 | 仍然先制定计划 |
+| 你说"重构整个 auth 模块" | 自动触发计划 | 自动触发计划（结果相同） |
 
-## Plan 包含什么
+强制模式适用于**重要场景**：
 
-一份典型 Plan 包含：
+- 你正在让智能体改一个关键系统，要全程可控
+- 你刚教了智能体新规则，想确认它确实理解
+- 你打算让智能体连续做多件事，希望每件事都先看到计划
 
-| 部分 | 内容 |
-|---|---|
-| **目标** | 要解决的问题与完成标准 |
-| **约束与决策** | 已知边界、选择的方案、不能做的事情 |
-| **实施顺序** | 按依赖排列的步骤，而不是优先级列表 |
-| **待澄清项** | 当前信息不足的地方 |
-| **风险与验证** | 可能的风险、具体 Human Gate、如何确认结果 |
+不需要强制模式时，让智能体自己判断更高效。
 
-Plan 的 frontmatter 会记录 `id`、`revision`、`parent_revision`、`workdir`、绝对 `plan_path`、`scope`、`related_workdirs` 和更新时间等版本信息；团队 Plan 还会记录 `team_id`。它不会记录 `approved`、`rejected`、`mode` 或 `phase` 等流程状态。
+## 如何审阅计划
 
-## 如何审阅和修改
+审阅计划时，重点关注以下几点：
 
-不需要点击固定的“批准计划”按钮。直接告诉智能体你的意见即可：
+### 1. 步骤是否完整
 
-```text
-“先只写计划，不要执行。”
-“第二步改成先备份，再迁移。”
-“这个方案可以继续，但发送邮件前必须问我。”
-“方向不对，保留现有版本并重新规划。”
+看看是否有遗漏的重要步骤。比如你教过"进口设备必须检查中文说明书条款"，计划中是否包含了这一步？
+
+### 2. 步骤类型是否合理
+
+- 规则明确的步骤应该是"固化"的
+- 需要理解判断的步骤应该是"灵活"的
+- 高风险操作应该有"人闸门"
+
+### 3. 风险提示是否到位
+
+智能体会主动标注可能的风险。如果你觉得还有其他风险，可以补充。
+
+### 4. 人闸门的设置
+
+确认哪些步骤需要你中间确认。太多会影响效率，太少可能有风险。
+
+### 5. 关键文件清单是否合理
+
+计划列出的"Critical Files"应该是你预期会动到的文件。如果出现了你不希望被改动的文件，及时指出。
+
+## 审批的三个选项
+
+智能体把计划做好后，会通过结构化提问让你做选择：
+
+| 选项 | 含义 |
+|------|------|
+| **批准并执行** | 按当前计划执行；强制模式自动关闭 |
+| **需要修改** | 你描述修改点，智能体改完计划再让你审一次 |
+| **拒绝** | 任务终止；强制模式自动关闭 |
+
+## 修改计划
+
+如果计划需要调整，你可以直接说：
+
+```
+你："计划基本可以，但做两个修改：
+    1. 第 4 步改为固化步骤——进口设备条款的检查规则我之前
+       已经教过了，直接按规则检查就行
+    2. 在第 5 步和第 6 步之间加一个步骤：把报告先保存为
+       草稿，不要直接发送"
 ```
 
-如果修改影响目标、约束、策略、步骤或验证方式，智能体会创建新的 revision。普通进度变化不会产生 Plan 版本。
+智能体会更新计划文件并再次展示给你确认：
 
-你也可以直接打开 `PLAN.md` 修改。智能体继续前应重新读取文件；发现外部改动时先合并，不应静默覆盖。
+```
+智能体："已更新计划。变更如下：
+
+        步骤 4：🧠 [灵活] → ⚙️ [固化] 按已有规则检查进口设备条款
+        新增步骤 6：⚙️ [固化] 保存审查报告草稿
+
+        计划文件已更新至 .desirecore/plans/plan-review-contract/PLAN.md
+        确认按更新后的计划执行？"
+```
 
-## Plan 不等于授权
+## 快速确认
 
-下面三个概念相互独立：
+对于简单或你已经熟悉的任务，你可以跳过详细审阅：
 
-| 概念 | 作用 |
-|---|---|
-| **Plan** | 记录准备做什么、为什么和怎样验证 |
-| **自然对话** | 你表达修订、继续、暂停或改变方向 |
-| **Human Gate** | 对某个具体高风险动作作出允许或拒绝 |
+```
+你："计划没问题，直接开始。"
+```
 
-因此，“计划没问题，继续”不会永久放开权限；如果后面要删除数据、发布版本、发送邮件或执行其他高风险动作，DesireCore 仍会按当前审批策略处理。
+或者对于低风险的常规任务，你可以提前告知智能体不需要确认计划：
 
-## 与任务进度的区别
+```
+你："帮我审查这份合同，不用让我确认计划，按之前的流程做就行。"
+```
 
-Plan 负责策略，Task 负责可分派责任和执行状态。步骤多不等于必须创建任务清单。只有需要跨智能体分工、等待或阻塞、持续展示进度，或者你明确要求跟踪时，智能体才会使用 Task。
+:::warning 首次执行新类型任务时建议确认计划
+即使你很信任智能体，第一次执行某类新任务时，还是建议看一眼计划。等确认它确实理解了你的要求后，下次就可以放心跳过了。
+:::
+
+## 关于计划文件的位置
+
+每个智能体的计划文件落在**它自己的工作目录**下的 `.desirecore/plans/` 子目录——这是有意为之：
+
+- **可审阅**：计划是普通 Markdown 文件，你可以在编辑器里直接打开、对比版本
+- **自动版本化**：每次修订都创建不可变历史版本（`revisions/`），PLAN.md 保留最新状态
+- **可纳入版本控制**：如果工作目录是 git 仓库，计划会成为团队的"决策日志"
+- **跟项目走**：换台机器 / 拉一份仓库即可看到所有历史计划
+
+不同智能体之间**互相看不到**对方的计划——切换到另一个智能体，看到的就是它自己的计划库，不会混淆。
+
+:::info 不想让计划文件污染目录？
+你可以把 `.desirecore/plans/` 加进 `.gitignore`，让它只在本地保留、不进版本控制。
+:::
 
 :::info 下一步
-前往 [执行监控](./03-execution-monitoring.md) 了解如何查看正在执行的任务、工具调用和回执。
+确认计划后，智能体就开始执行了。前往 [执行监控](./03-execution-monitoring.md) 了解如何监控执行过程，以及智能体如何用**任务清单**透明展示每一步进度。
 :::
diff --git a/docs/02-user-guide/04-delegation/05-receipts.md b/docs/02-user-guide/04-delegation/05-receipts.md
index 4748657..65cb9b9 100644
--- a/docs/02-user-guide/04-delegation/05-receipts.md
+++ b/docs/02-user-guide/04-delegation/05-receipts.md
@@ -38,6 +38,76 @@ keywords: [回执, Receipt, 审计, 回滚, 执行记录, 追溯]
 
 ![执行回执示例](/img/user-guide/delegation/receipt-example.svg)
 
+### 基础信息
+
+```
+┌──────────────────────────────────────────────────────┐
+│  📋 执行回执                                           │
+├──────────────────────────────────────────────────────┤
+│                                                        │
+│  回执编号: RCPT-20250315-143022                       │
+│  任务: 审查采购合同 XX-2025-001                        │
+│  执行时间: 2025-03-15 14:30 - 14:35                   │
+│  总耗时: 5 分 12 秒                                    │
+│  状态: ✅ 已完成                                        │
+│                                                        │
+└──────────────────────────────────────────────────────┘
+```
+
+### 输入输出摘要
+
+```
+│  📥 输入                                               │
+│  用户指令: "帮我审查附件中的采购合同"                      │
+│  附件: XX科技采购合同.pdf (128KB)                       │
+│                                                        │
+│  📤 输出                                               │
+│  审查报告已保存至: docs/review-report-XX-2025-001.md   │
+│  发现 2 个风险项，4 个合规项                             │
+│  综合风险等级: 中等                                     │
+```
+
+### 步骤执行明细
+
+```
+│  📝 执行步骤                                           │
+│                                                        │
+│  1. ⚙️ [确定性] 解析合同文件                       ✅ 0.8s  │
+│  2. ⚙️ [确定性] 检查违约金比例                     ✅ 0.2s  │
+│     └─ 15% ≤ 20% → 合规                                │
+│  3. ⚙️ [确定性] 检查付款条件                       ⚠️ 0.2s  │
+│     └─ 15 天 < 30 天 → 风险                             │
+│  4. 🧠 [灵活] 分析进口设备条款                   ⚠️ 1.5min │
+│     └─ 缺少中文说明书条款                                │
+│  5. 🧠 [灵活] 综合风险评估                       ✅ 1.2min │
+│  6. 🚪 [人闸门] 确认后保存报告                   ✅ 3.5s   │
+│     └─ 用户确认: 已批准                                  │
+```
+
+### 依据追溯
+
+```
+│  📚 依据                                               │
+│                                                        │
+│  引用的规则:                                            │
+│  - 违约金标准 (≤20%) — 来自 3 月 1 日的教学             │
+│  - 付款条件标准 (≥30 天) — 来自 3 月 1 日的教学          │
+│  - 进口设备中文说明书 — 来自 3 月 5 日的教学             │
+│                                                        │
+│  引用的示例:                                            │
+│  - 审查报告模板 — 来自 3 月 2 日的教学                   │
+```
+
+### 变更记录
+
+```
+│  📂 文件变更                                            │
+│                                                        │
+│  新建文件: docs/review-report-XX-2025-001.md           │
+│  变更大小: 2.1KB                                       │
+│  [查看文件内容]                                         │
+```
+
 ## 如何查看回执
 
 ### 在对话中查看
@@ -82,7 +152,7 @@ keywords: [回执, Receipt, 审计, 回滚, 执行记录, 追溯]
 
 ## 通过回执追溯和恢复
 
-如果你对执行结果不满意，先用回执确认影响范围，再使用 Rewind / Checkpoint 恢复到合适状态。较新的 DesireCore 会优先基于检查点恢复，而不是依赖单个步骤的手工回滚。
+如果你对执行结果不满意，可以基于回执进行回滚。DesireCore 支持多种粒度的回滚，并且较新版本会优先基于检查点恢复，而不是依赖单个步骤的手工回滚。
 
 | 回滚级别 | 含义 | 适用场景 |
 |---------|------|---------|
diff --git a/docs/02-user-guide/06-agents/04-edit-persona.md b/docs/02-user-guide/06-agents/04-edit-persona.md
index fa45c50..1ce0dfe 100644
--- a/docs/02-user-guide/06-agents/04-edit-persona.md
+++ b/docs/02-user-guide/06-agents/04-edit-persona.md
@@ -20,7 +20,7 @@ keywords: [人格设定, Persona, 角色定位, 性格特征, 智能体配置]
 | **禁区** | 什么不该做 | "不要使用模板腔，不要回避给结论" |
 | **不确定处理** | 拿不准时怎么办 | "说明不确定点并给验证路径" |
 
-`persona.md` 是 **Agent 层提示词**的一部分。运行时还会叠加当前用户的全局提示词和智能体所属团队的团队提示词；你可以在 **资源管理器 → 提示词中心**中集中编辑并预览最终组合。详见[提示词中心与三层提示词](./11-prompt-center.md)。
+`persona.md` 是 **Agent 层提示词**的一部分。运行时还会叠加当前用户的全局提示词和智能体所属团队的团队提示词；你可以在 **资源管理器 → 提示词中心**中集中编辑并预览最终组合。详见[提示词中心与三层提示词](./12-prompt-center.md)。
 
 :::info 人格 vs 行为准则
 **人格设定**定义的是"怎么做"——语气、风格、回答方式。**行为准则**（Principles）定义的是"做什么和不做什么"——规则、边界、优先级。两者互补但不重叠。
@@ -103,5 +103,5 @@ keywords: [人格设定, Persona, 角色定位, 性格特征, 智能体配置]
 ## 下一步
 
 - [编辑行为准则](./05-edit-principles.md) — 为智能体设定行为边界
-- [提示词中心与三层提示词](./11-prompt-center.md) — 管理全局、团队和 Agent 提示词
+- [提示词中心与三层提示词](./12-prompt-center.md) — 管理全局、团队和 Agent 提示词
 - [创建自定义智能体](./03-create-agent.md) — 回顾创建流程
diff --git a/docs/02-user-guide/06-agents/05-edit-principles.md b/docs/02-user-guide/06-agents/05-edit-principles.md
index bed6796..0765756 100644
--- a/docs/02-user-guide/06-agents/05-edit-principles.md
+++ b/docs/02-user-guide/06-agents/05-edit-principles.md
@@ -95,4 +95,4 @@ L2 保存较长的解释、例外、示例和操作细节，默认不注入，
 
 - [文件资源管理器](./06-agent-files.md) — 浏览智能体的文件结构
 - [编辑人格设定](./04-edit-persona.md) — 调整智能体的语气和风格
-- [提示词中心与三层提示词](./11-prompt-center.md) — 理解全局、团队和 Agent 的组合顺序
+- [提示词中心与三层提示词](./12-prompt-center.md) — 理解全局、团队和 Agent 的组合顺序
diff --git a/docs/02-user-guide/06-agents/07-skills-management.md b/docs/02-user-guide/06-agents/07-skills-management.md
index 5e38160..e510aaa 100644
--- a/docs/02-user-guide/06-agents/07-skills-management.md
+++ b/docs/02-user-guide/06-agents/07-skills-management.md
@@ -63,8 +63,6 @@ DesireCore 会从多个来源发现技能：
 
 安装 Skill 时可以选择安装目标：全局、指定智能体，或项目级目录。全局市场技能安装后会写入全局技能目录，所有智能体都能发现；绑定到智能体的技能会写入对应智能体仓库；项目级 Skill 只在对应工作目录下生效，适合把团队规范、项目脚本和本地模板随项目一起维护。
 
-### 移除技能
-
 ### 本地导入
 
 技能管理中的 **导入技能** 支持三种本地格式：
diff --git a/docs/02-user-guide/06-agents/08-version-control.md b/docs/02-user-guide/06-agents/08-version-control.md
index c4a1493..263d94c 100644
--- a/docs/02-user-guide/06-agents/08-version-control.md
+++ b/docs/02-user-guide/06-agents/08-version-control.md
@@ -134,11 +134,11 @@ DesireCore 中的每个智能体都是一个 Git 仓库。你对智能体的每
 
 除了发布单个智能体，DesireCore 还支持克隆智能体和团队级版本管理：
 
-- [Clone 与同步](./clone-and-sync) — 复制智能体，选择是否复制私有数据，并处理后续同步
-- [团队版本管理](./team-version-control) — 团队远程托管、fork、release 和市场分发
+- [Clone 与同步](./09-clone-and-sync.md) — 复制智能体，选择是否复制私有数据，并处理后续同步
+- [团队版本管理](./10-team-version-management.md) — 团队远程托管、fork、release 和市场分发
 
 ## 下一步
 
-- [团队版本管理](./09-team-version-management.md) — 把整支智能体团队当作一个整体进行版本管理
+- [团队版本管理](./10-team-version-management.md) — 把整支智能体团队当作一个整体进行版本管理
 - [智能体类型](./01-agent-types.md) — 回顾智能体的类型和定位
 - [创建自定义智能体](./03-create-agent.md) — 创建你自己的智能体
diff --git a/docs/02-user-guide/06-agents/09-clone-and-sync.md b/docs/02-user-guide/06-agents/09-clone-and-sync.md
index ee410f1..37023b1 100644
--- a/docs/02-user-guide/06-agents/09-clone-and-sync.md
+++ b/docs/02-user-guide/06-agents/09-clone-and-sync.md
@@ -8,41 +8,93 @@ keywords: [Clone, 克隆智能体, 同步, 冲突解决, Agent Git]
 
 Clone 用于基于现有智能体创建一个新副本。它适合做实验、为不同项目准备变体，或把市场智能体调整成自己的版本。
 
-## 克隆方式
+## 何时需要克隆
 
-| 场景 | 行为 |
+| 场景 | 说明 |
 |------|------|
-| 本地智能体 | 复制 AgentFS，创建新的智能体 ID |
-| 带远程来源的智能体 | 可选择保留远程关系、fork 或作为纯本地副本 |
-| 市场智能体 | 复制核心配置，后续仍可检查远端更新 |
-
-核心 DesireCore 智能体通常不允许被克隆，以避免破坏主控入口。
+| **实验性改造** | 想大幅修改某智能体的人格或技能，但不确定效果，先克隆一个"试验田" |
+| **项目变体** | 同一个基础智能体需要适配不同项目（如不同客户的审查标准） |
+| **市场智能体本地化** | 从市场安装了智能体，想深度定制而不受远端更新干扰 |
+| **团队协作模板** | 创建一个标准化的团队智能体模板，成员各自克隆后按需调整 |
+
+## 克隆操作步骤
+
+1. 打开 **资源管理器 → 智能体列表**
+2. 右键目标智能体（或点击 `⋯` 菜单），选择 **克隆**
+3. 在弹出的对话框中设置：
+   - **新名称**：为克隆体取一个易区分的名字
+   - **远程关系**（仅当源智能体有远程来源时）：
+     - *保留远程*：后续可继续接收更新
+     - *Fork*：创建独立分支，与原远程解耦
+     - *纯本地*：完全断开远程关联
+   - **私有数据选项**（见下节）
+4. 点击 **确认克隆**，系统创建新的智能体 ID 并完成复制
+
+:::caution 注意
+核心 DesireCore 智能体（系统调度器）不允许被克隆，以避免破坏主控入口。如果菜单中克隆选项为灰色，说明该智能体受保护。
+:::
 
 ## 私有数据选项
 
-克隆时可以选择是否复制用户私有数据：
+克隆时可以选择是否复制当前用户与该智能体之间的私有数据：
 
-- 记忆
-- 偏好
-- 关系数据
-- 本地资源文件
+| 数据类型 | 说明 | 建议 |
+|---------|------|------|
+| 记忆（memory/） | 智能体在对话中学到的事实、偏好、经验 | 自用分身可保留，分享给他人时不勾选 |
+| 偏好（preferences/） | 用户个性化设置 | 视情况保留 |
+| 关系契约（relationship.md） | 你与智能体的协作约定 | 通常需要重新建立，不建议复制 |
+| 本地资源文件 | 工作目录中的文件 | 大型项目建议不复制，节省空间 |
 
-如果你只是想把一个智能体分享给别人，不建议复制私有数据。若你是给自己创建分身，可以按需保留这些内容。
+**经验法则**：给自己创建分身 → 可保留记忆和偏好；给别人或团队准备模板 → 不复制私有数据。
 
 ## 同步更新
 
-克隆后的智能体如果仍保留远程来源，可以继续检查更新。更新时会走 Git 合并流程，并在冲突时展示冲突文件列表。
+克隆后的智能体如果仍保留远程来源（即选择了"保留远程"），可以继续接收上游更新：
+
+1. 打开智能体详情页，在 **来源** 区域查看远程仓库地址
+2. 点击 **检查更新**，系统会拉取远端最新提交并与本地比较
+3. 如果有新内容，会显示变更文件列表和差异摘要
+4. 点击 **合并更新**，系统执行 Git 合并
+
+:::info 更新策略
+- **纯配置更新**（人格、原则、技能）：通常可以安全合并
+- **新增技能/工具**：自动添加，不影响已有配置
+- **删除或重命名**：需要手动确认，系统不会静默删除你本地已有的文件
+:::
 
 ## 冲突处理
 
 当本地和远端都修改了同一个文件时，DesireCore 会阻止直接覆盖，并提供冲突解决对话框：
 
-1. 查看冲突文件列表
-2. 打开 Diff 查看本地和远端差异
-3. 选择保留本地、使用远端、手动编辑或保留两者
-4. 保存后系统自动提交解决结果
+1. **查看冲突文件列表** — 标红的文件表示双方都有修改
+2. **打开 Diff 视图** — 左右对比本地版本和远端版本的差异
+3. **选择解决策略**：
+   - **保留本地**：丢弃远端更改，使用你的版本
+   - **使用远端**：接受上游更新，覆盖本地修改
+   - **手动编辑**：在编辑器中逐行决定保留哪些内容
+   - **保留两者**：将远端内容追加为新文件（如 `persona-remote.md`）
+4. 解决所有冲突后点击 **完成合并**，系统自动提交
+
+:::tip 长期改造建议
+如果你长期大幅改造市场智能体，建议 fork 成自己的远程仓库。这样：
+- 上游更新不会自动推送，由你主动选择何时同步
+- 冲突范围更可控，因为你清楚自己改了什么
+- 其他团队成员可以基于你的 fork 创建各自版本
+:::
+
+## 常见问题
+
+| 问题 | 解决方案 |
+|------|---------|
+| 克隆后智能体表现和原来不一样 | 检查是否遗漏了私有数据（记忆、偏好），或新 ID 导致关系数据未迁移 |
+| 同步时提示"无法合并" | 通常因为本地有未提交的修改，先在智能体文件页面手动提交或暂存 |
+| 想恢复克隆前的状态 | 克隆不会修改原智能体，原智能体始终不受影响 |
+| 克隆体能加入团队吗 | 可以。克隆后是独立智能体，可以像任何其他智能体一样加入团队 |
+
+---
 
-:::tip
-如果你长期大幅改造市场智能体，可以考虑 fork 成自己的远程仓库，这样后续更新策略更清晰。
+:::info 下一步
+- [版本控制](./08-version-control.md)：了解智能体的 Git 版本管理机制
+- [团队版本管理](./10-team-version-management.md)：在团队中共享和同步智能体配置
 :::
 
diff --git a/docs/02-user-guide/06-agents/10-team-version-control.md b/docs/02-user-guide/06-agents/10-team-version-control.md
deleted file mode 100644
index bb8e216..0000000
--- a/docs/02-user-guide/06-agents/10-team-version-control.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: 团队版本管理
-description: 使用 Git 远程托管团队、发布 release，并通过市场分发团队智能体。
-keywords: [团队, Git, Release, Fork, Market, 远程托管]
----
-
-# 团队版本管理
-
-团队也可以像智能体一样使用 Git 管理。团队版本管理适合多人维护一组智能体、统一发布版本，并通过市场或远程仓库分发。
-
-## 能力概览
-
-| 能力 | 说明 |
-|------|------|
-| 远程托管 | 为团队配置 Git remote，推送和拉取团队配置 |
-| Fork 安装 | 从远程团队创建自己的本地副本 |
-| Release | 为团队生成可安装的版本快照 |
-| 市场分发 | 把团队发布到市场，供其他用户安装 |
-| 成员锁定 | 团队内成员智能体可以跟随团队版本固定 |
-
-## 典型流程
-
-1. 团队负责人配置远程仓库
-2. 提交团队结构、成员智能体和共享资源
-3. 创建 release，填写版本说明
-4. 发布到市场或分享远程仓库地址
-5. 其他用户通过 fork 安装团队
-
-## 隐私边界
-
-团队发布默认只包含团队结构、智能体核心配置、技能和共享资源。个人对话、用户私有记忆、运行日志和本地缓存不会作为团队 release 的一部分发布。
-
-## 更新和冲突
-
-已安装团队可以检查远端更新。如果你本地修改了团队成员或共享资源，更新时可能触发冲突解决。处理方式与智能体同步类似：保留本地、使用远端、手动合并或保留两者。
-
diff --git a/docs/02-user-guide/06-agents/09-team-version-management.md b/docs/02-user-guide/06-agents/10-team-version-management.md
similarity index 100%
rename from docs/02-user-guide/06-agents/09-team-version-management.md
rename to docs/02-user-guide/06-agents/10-team-version-management.md
diff --git a/docs/02-user-guide/06-agents/11-team-version-control.md b/docs/02-user-guide/06-agents/11-team-version-control.md
new file mode 100644
index 0000000..eee8245
--- /dev/null
+++ b/docs/02-user-guide/06-agents/11-team-version-control.md
@@ -0,0 +1,107 @@
+---
+title: 团队版本管理 FAQ
+description: 团队版本管理常见问题解答与故障排除——权限、冲突、成员版本不一致等场景的处理方法。
+keywords: [团队版本, FAQ, 故障排除, 冲突, 成员版本, 权限]
+---
+
+# 团队版本管理 FAQ
+
+本页汇总团队版本管理中的常见问题。完整的操作指南请参阅[团队版本管理](./10-team-version-management.md)。
+
+## 连接与推送
+
+### 推送失败提示 "rejected - non-fast-forward"
+
+说明远端有你本地没有的新提交。先拉取（Pull）合并远端变化，再推送：
+
+1. 点击"拉取"
+2. 等待合并完成（大多数情况会自动合并）
+3. 再次点击"推送"
+
+### 连接远程仓库时提示 "authentication failed"
+
+- 检查 OAuth 账号是否过期：进入 **设置 → 连接账号**，重新授权 GitHub/Gitee
+- 如果使用 PAT（个人访问令牌），确认令牌未过期且有 `repo` 权限
+- 私有仓库需要确保令牌具备对应仓库的读写权限
+
+### 推送后远端看不到变化
+
+- 确认推送的目标分支是否正确（默认 `main`，部分仓库可能是 `master`）
+- 在远端网页刷新查看，有时存在缓存延迟
+
+## 成员与版本
+
+### 安装团队时提示"无法安装：缺少远程地址"
+
+该成员智能体是纯本机的（没有推送到任何 Git 仓库）。你需要：
+
+- 联系团队发布者，请对方把该成员发布到市场或推送到 Git
+- 或者自己创建一个同配置的本地智能体替代
+
+### 团队成员版本显示"已偏离"
+
+你本地修改过该成员智能体的配置（人格、技能等），与团队锁定的版本产生了差异。
+
+- **不影响使用**：本地版本照常工作
+- **不会被覆盖**：升级团队时不会强制覆盖你的修改
+- **如需同步**：在成员智能体的版本管理中手动推送你的修改，再升级团队
+
+### 换了队长后，旧队长的配置还在吗？
+
+在。换帅只改变"谁是组长"的组织关系，不影响任何成员的配置、记忆或技能。你可以在版本历史中看到换帅记录。
+
+## 冲突处理
+
+### 拉取时出现冲突文件列表
+
+通常发生在两人同时修改了团队共享资源（如共享技能或规则文件）。
+
+| 策略 | 适用场景 |
+|------|----------|
+| **保留本地** | 你的修改更新、更完整 |
+| **使用远端** | 对方的修改是你想要的 |
+| **手动编辑** | 需要合并双方的改动 |
+| **保留两者** | 不确定时先都留着，稍后整理 |
+
+### 两个人各加了新成员，会冲突吗？
+
+通常不会。成员列表的合并策略是**取并集**——A 加了 carol，B 加了 dave，合并后团队同时拥有 carol 和 dave。只有修改同一条记录（比如同时移除同一人）才会真正冲突。
+
+## 发布与安装
+
+### 发布时提示"成员缺少远程来源"
+
+团队中包含了纯本机智能体。发布前需要：
+
+1. 检查每个成员的来源（本地 / Git / 市场 / 内置）
+2. 把本机成员推送到 Git 或发布到市场
+3. 重新发布
+
+### 从链接安装后，和原作者还有关系吗？
+
+没有。安装时系统会自动断开与原始远程的连接。你得到的是一个完全独立的副本（类似 Git fork），后续修改不影响原作者。
+
+### 安装来的团队可以发布到市场吗？
+
+可以。只要所有成员都有远程来源，你就可以像原创团队一样发布。建议使用不同的团队名称以避免混淆。
+
+## 解散与恢复
+
+### 解散后数据会丢失吗？
+
+不会。解散是"归档"而非"删除"：
+
+- 团队目录被移到归档区，磁盘上完整保留
+- 版本历史、共享资源、成员清单全部保留
+- 成员智能体本身不受影响，它们只是不再属于该团队
+
+### 如何恢复已解散的团队？
+
+从归档区手动将团队目录移回活跃目录即可。系统会重新识别版本历史和成员关系。
+
+## 相关页面
+
+- [团队版本管理完整指南](./10-team-version-management.md)
+- [单个智能体版本管理](./08-version-control.md)
+- [Clone 与同步](./09-clone-and-sync.md)
+- [跨智能体协作](../04-delegation/06-cross-agent.md)
diff --git a/docs/02-user-guide/06-agents/11-prompt-center.md b/docs/02-user-guide/06-agents/12-prompt-center.md
similarity index 63%
rename from docs/02-user-guide/06-agents/11-prompt-center.md
rename to docs/02-user-guide/06-agents/12-prompt-center.md
index 8b3e51a..cbce29b 100644
--- a/docs/02-user-guide/06-agents/11-prompt-center.md
+++ b/docs/02-user-guide/06-agents/12-prompt-center.md
@@ -60,6 +60,59 @@ L0/L1/L2 表示加载粒度，不是权限或安全等级。保存全局、团
 - 把短小、常用内容放在 L0/L1，把长解释和示例放在 L2
 - 不要依靠提示词替代工具权限、审批策略或代码级安全限制
 
+## 实战示例
+
+以下是一个三层提示词的配合示例，展示如何避免重复和冲突：
+
+**全局提示词**（适用于所有智能体）：
+
+```md
+## L0
+用户偏好中文回复，技术术语保留英文原文。
+
+## L1
+- 输出格式优先使用 Markdown 表格和列表
+- 代码块标注语言类型
+```
+
+**团队提示词**（仅团队成员可见）：
+
+```md
+## L0
+文档团队：统一使用 Docusaurus 格式，图片放 static/img/ 对应章节目录。
+
+## L1
+- 提交前运行 npm run build 确认无断链
+- 配图使用 SVG 格式，支持暗色模式
+```
+
+**Agent 人格**（单个智能体独有）：
+
+```md
+## L0
+技术文档工程师，专注于 API 参考和用户指南。
+
+## L1
+- 写作风格：简洁、准确、面向开发者
+- 每个操作步骤配一个可复制的代码示例
+```
+
+运行时，这三层按顺序拼接，智能体同时知道用户偏好（全局）、团队规范（团队）和自身角色（Agent）。
+
+## 常见问题
+
+| 问题 | 原因与解决 |
+|------|-----------|
+| 保存后智能体行为没变化 | L2 内容默认不注入运行时；确认关键规则在 L0/L1 中 |
+| 预览中看到重复内容 | 全局和 Agent 层写了相似规则；精简其中一层 |
+| 团队提示词不生效 | 确认智能体已加入该团队；多团队时检查是否选对了团队 |
+| 源码模式提示"格式错误" | 检查二级标题是否严格为 `## L0`、`## L1`、`## L2`（注意空格） |
+| 字符数过长导致截断 | 把详细内容移到 L2，L0/L1 只保留摘要 |
+
+:::caution 提示词 ≠ 权限
+修改提示词不会改变智能体的工具权限、文件访问范围或审批策略。如需调整安全边界，请在 **资源管理器 → 智能体设置 → 权限** 中操作。
+:::
+
 ## 下一步
 
 - [编辑人格设定](./04-edit-persona.md)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/02-plan-confirmation.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/02-plan-confirmation.md
index 7ded48e..6f85643 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/02-plan-confirmation.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/04-delegation/02-plan-confirmation.md
@@ -1,111 +1,257 @@
 ---
-title: Plan Files and Natural Collaboration
-description: Learn how agents keep versioned plans in the working directory and how to review, revise, and continue through natural conversation.
-keywords: [plan, review, revision, steps, working directory, versioning]
-last-reviewed: 2026-07-22
+title: Plan Confirmation
+description: Learn how the agent creates execution plans, what information is included, how to review and modify them, and how to require the agent to "think before acting".
+keywords: [plan, confirmation, review, steps, execution plan, Plan Mode, force plan]
 ---
 
-# Plan Files and Natural Collaboration
+# Plan Confirmation
 
-For work that calls tools, changes files, delegates work, has multiple delivery steps, or affects an external system, the agent first creates or reads a Plan in the current working directory before acting.
+When you assign a task, the agent won't start executing immediately—it will first create a plan and wait for your review and confirmation before proceeding.
 
-A Plan is an ordinary Markdown work file. It is not a mode and does not grant permission to execute. You can revise, pause, or redirect it in natural language at any time. When a sensitive or high-risk action is actually about to happen, DesireCore still applies the relevant permission check or Human Gate.
+## Why Plan Confirmation is Needed
 
-## Why Plans Live in the Project
+In reality, you wouldn't let a new colleague start working immediately either. Good practice is: first have them explain what they plan to do, and only let them proceed when you think it's okay.
 
-- **Transparent**: open them in any editor without relying on the chat UI.
-- **Editable**: you can edit a Plan directly, and the agent should reread it before continuing.
-- **Traceable**: every substantive revision keeps an immutable historical version.
-- **Project-local**: your team decides whether Plan files belong in Git.
+The benefits are:
+- **Discover misunderstandings**: The agent may have misunderstood your intent
+- **Fill gaps**: The agent may have missed an important step
+- **Adjust strategy**: You may have a better execution approach
+- **Set boundaries**: Mark in advance which steps need your confirmation
 
-## Which Requests Create a Plan
+## When Does the Agent Automatically Make a Plan
 
-| Request type | Agent behavior |
-|---|---|
-| Change files, run action-oriented tools, or affect an external system | Create or read a Plan first |
-| Delegate to another agent or deliver multi-step work | Create or read a Plan first |
-| Missing information | Write a small Plan with open questions, ask for clarification, then revise it |
-| Goal, constraints, or strategy changes during execution | Create a new revision before continuing |
-| Pure Q&A, explanation, or casual conversation | Do not create a Plan file |
+The agent **judges automatically** when to make a plan first and when it can act directly. The criteria are:
 
-This is an agent behavior policy, not a session lock or read-only mode. It does not hide tools, and the presence of a Plan never bypasses permission checks.
+| Task characteristic | Agent behavior |
+|--------------------|----------------|
+| Modifying 3+ files, or anticipating 5+ tool calls | Plan first |
+| Includes **irreversible operations** (delete files, publish a release, migrate data, send email to external parties, etc.) | Plan first |
+| You explicitly say "make a plan first" / "think it through" / "list the steps" | Plan first |
+| The agent itself is uncertain how to proceed | Plan first |
+| Single-file small edits | Act directly |
+| Pure queries / explanations / reads | Answer directly |
+| You explicitly say "just do it" / "no plan needed" | Act directly |
 
-## File Location
+This works like an experienced colleague—they don't run plans by you for small things, but always check before big or ambiguous ones.
 
-Each task uses its own directory:
+:::tip Want the agent to plan every time?
+See "Asking the Agent to Always Plan First" below—you can **force** the agent to plan for any task in this session, regardless of size.
+:::
+
+## What the Plan Contains
+
+The plan created by the agent typically includes the following information:
+
+![Execution Plan](/img/user-guide/delegation/plan-confirmation.svg)
+
+The full plan is a structured Markdown document, automatically saved at **`.desirecore/plans/<plan-id>/PLAN.md`** in the current working directory (e.g. `.desirecore/plans/plan-review-contract/PLAN.md`). Even if you close the conversation, the file stays there for later review or version control. Each plan revision creates an immutable historical version under the `revisions/` subdirectory.
+
+### Plan File Structure
+
+Each plan is a standard Markdown file using **YAML frontmatter + body** format:
+
+```yaml
+---
+schema: 1
+id: plan-review-contract
+title: Review procurement contract
+revision: 1
+parent_revision: null
+created_at: 2026-07-27T10:00:00+08:00
+updated_at: 2026-07-27T10:00:00+08:00
+workdir: /path/to/workspace
+plan_path: /path/to/workspace/.desirecore/plans/plan-review-contract/PLAN.md
+scope: agent
+related_workdirs: []
+---
+
+# Review procurement contract
+
+## Goal
+Review the attached procurement contract, identifying legal and commercial risks.
+
+## Constraints
+- Follow previously taught contract review rules
+- Do not modify the original contract file
+
+## Steps
+1. Parse the contract PDF, extract clause text
+2. Check each clause against taught rules (penalties, payment terms, etc.)
+3. Adaptively analyze imported equipment clauses
+4. Generate review report
+5. Save draft and wait for confirmation
 
-```text
-<current-workdir>/.desirecore/plans/<plan-id>/
-├── PLAN.md
-└── revisions/
-    ├── 000001.md
-    ├── 000002.md
-    └── ...
+## Verification
+- Report covers all taught rules
+- No overlooked high-risk clauses
 ```
 
-- `PLAN.md` contains the current version.
-- `revisions/` contains immutable history.
-- On creation, `PLAN.md` and `revisions/000001.md` have the same content.
-- Restoring older content creates a new revision instead of rewriting history.
+**Required frontmatter fields**:
+
+| Field | Description |
+|-------|-------------|
+| `schema` | Always `1` |
+| `id` | Plan unique identifier (kebab-case) |
+| `title` | Plan title |
+| `revision` | Current version number (starting from 1) |
+| `parent_revision` | Previous version number (`null` for the first version) |
+| `created_at` | Creation time (ISO 8601) |
+| `updated_at` | Last update time |
+| `workdir` | Absolute path of the working directory |
+| `plan_path` | Absolute path of the plan file itself |
+| `scope` | Scope (`agent` or `team`) |
+| `related_workdirs` | List of related working directories |
+
+The **body** is free-form Markdown, typically containing `## Goal`, `## Constraints`, `## Steps`, `## Verification` sections, organized flexibly according to the task.
+
+### Step Type Explanation
+
+| Icon | Type | Meaning |
+|------|------|---------|
+| ⚙️ | **Deterministic Step** | Steps with clear rules and certain results, executed like a program |
+| 🧠 | **Adaptive Step** | Steps requiring AI understanding and judgment, results may vary by situation |
+| 🚪 | **Human Gate** | Pause when executing to this step, waiting for your confirmation (steps marked `confirm: yes` in the plan) |
+
+:::info Risk level decides confirmation automatically
+Each step carries a `risk: low | med | high` tag. **High-risk steps are automatically set as "human gates"** — this is the agent's discipline to avoid irreversible actions when you aren't watching.
+:::
+
+## Asking the Agent to Always Plan First
+
+If you want the agent to **plan every time** (even for simple tasks), there are three ways to **force Plan Mode** on. Once enabled, every task in this session goes through "plan → approval → execute" until you turn it off, or until a plan is approved and auto-exits.
+
+### Method 1: Click the 📋 button
+
+There is a 📋 Plan button on the right side of the chat header. Click it to toggle. When enabled, you'll see clear visual cues:
+
+- The button is highlighted (purple background)
+- The input box border turns purple
+- The placeholder reads "Plan Mode is on: the agent will draft a plan before executing"
+
+### Method 2: Keyboard shortcut `Shift + Tab`
+
+Press `Shift + Tab` on the main interface (when the cursor isn't in the input box). Equivalent to clicking the 📋 button. This matches Claude Code's habit.
+
+### Method 3: Slash command `/plan`
+
+Type `/plan` in the input box and submit:
+
+- Send `/plan` alone → enable Plan Mode without sending any message
+- Send `/plan refactor the user module` → enable Plan Mode + submit "refactor the user module" as the task
+
+:::tip All three entry points do the same thing
+Pick whichever fits your habit. After the plan is approved (or rejected), forced mode **auto-disables**—you'll see a toast "✓ Plan approved, executing". No need to turn it off manually.
+:::
+
+### Forced Mode vs Auto-Judgment
 
-DesireCore does not automatically change `.gitignore`, stage these files, or commit them.
+| Scenario | Without forced mode (default) | With forced mode |
+|----------|------------------------------|------------------|
+| You ask "1+1=?" | Direct answer: 2 | Still goes through the (very simple) plan flow |
+| You say "add a comment to this line" | Single-file edit, act directly | Still plans first |
+| You say "refactor the whole auth module" | Auto-triggers plan | Auto-triggers plan (same result) |
 
-### Multiple and Team Working Directories
+Forced mode is useful when:
 
-- A normal conversation resolves cwd from the agent primary/first valid directory, then the global primary/first valid directory.
-- Click a team shared directory in the input-area working-directory pill or resource panel to activate that team's scope for the conversation. Click the same team again to leave it.
-- Team selection belongs to the specific conversation. DesireCore sends its `teamId`, and the backend revalidates membership and the shared directory instead of silently falling back.
-- Even when several directories are accessible, a task has one authoritative Plan in the current cwd. Other directories are recorded in `related_workdirs`, and cross-directory work uses absolute paths.
-- If a team is created with "only use team working directory" enabled, the team directory becomes the sole project working directory and sole Plan root; member/global directories are not written to `related_workdirs`. The member's original directory settings are not deleted.
-- Changing a normal primary directory does not move an in-progress Plan. Continuing across teams creates a new Plan in the new team directory and links the old one through `continued_from`.
+- You're letting the agent change a critical system and want full control
+- You just taught the agent new rules and want to confirm it actually internalized them
+- You're about to delegate a series of tasks and want to see plans for each one
 
-The working-directory scope cannot change while a conversation is running. After an idle conversation switches scope, its next message uses the new cwd, file permissions, project instructions, and Plan root together so old and new directory context cannot be mixed.
+Otherwise, letting the agent decide on its own is more efficient.
 
-## What a Plan Contains
+## How to Review the Plan
 
-A typical Plan includes:
+When reviewing the plan, focus on the following points:
 
-| Section | Content |
-|---|---|
-| **Goal** | The problem and completion criteria |
-| **Constraints and decisions** | Known boundaries, chosen approach, and prohibited actions |
-| **Implementation order** | Dependency order, not a priority ranking |
-| **Open questions** | Information that is still missing |
-| **Risks and verification** | Risks, concrete Human Gates, and how the result will be checked |
+### 1. Are Steps Complete?
 
-Plan frontmatter records `id`, `revision`, `parent_revision`, `workdir`, the absolute `plan_path`, `scope`, `related_workdirs`, and timestamps; team Plans also record `team_id`. It does not store workflow states such as `approved`, `rejected`, `mode`, or `phase`.
+See if any important steps are missing. For example, if you taught "imported equipment must have Chinese instruction manual clause checked," is this step included in the plan?
 
-## Reviewing and Revising a Plan
+### 2. Are Step Types Reasonable?
 
-There is no required “approve plan” button. Just tell the agent what you want:
+- Steps with clear rules should be "deterministic"
+- Steps requiring understanding and judgment should be "adaptive"
+- High-risk operations should have "human gates"
+
+### 3. Are Risk Warnings in Place?
+
+The agent will proactively mark possible risks. If you think there are other risks, you can add them.
+
+### 4. Human Gate Settings
+
+Confirm which steps need your intermediate confirmation. Too many will affect efficiency, too few may pose risks.
+
+### 5. Is the Critical Files List Reasonable?
+
+The "Critical Files" section should match what you expect to be touched. If files you didn't intend to modify show up, raise it.
+
+## Three Approval Options
+
+When the agent finishes the plan, it asks you a structured question with three choices:
+
+| Option | Meaning |
+|--------|---------|
+| **Approve and execute** | Execute the current plan; forced mode auto-disables |
+| **Needs revision** | You describe what to change; the agent rewrites the plan and asks again |
+| **Reject** | Task terminated; forced mode auto-disables |
+
+## Modifying the Plan
+
+If the plan needs adjustment, you can simply say:
 
-```text
-“Write the Plan only; do not execute yet.”
-“Change step two so we back up before migrating.”
-“Continue with this approach, but ask me before sending the email.”
-“This direction is wrong. Keep the current revision and plan again.”
+```
+You: "The plan is basically fine, but make two changes:
+    1. Change step 4 to deterministic step—the rules for checking imported equipment clauses were already
+       taught before, just check according to the rules
+    2. Add a step between step 5 and step 6: save the report as a
+       draft first, don't send it directly"
 ```
 
-If your change affects the goal, constraints, strategy, steps, or verification, the agent creates a new revision. Ordinary progress updates do not create Plan versions.
+The agent will update the plan file and show it to you again for confirmation:
 
-You can also edit `PLAN.md` directly. Before continuing, the agent should reread the file and merge external edits instead of silently overwriting them.
+```
+Agent: "Plan updated. Changes as follows:
 
-## A Plan Is Not Authorization
+        Step 4: 🧠 [Adaptive] → ⚙️ [Deterministic] Check imported equipment clauses according to existing rules
+        New Step 6: ⚙️ [Deterministic] Save review report draft
 
-These concepts remain separate:
+        Plan file updated at .desirecore/plans/plan-review-contract/PLAN.md
+        Confirm execution according to updated plan?"
+```
 
-| Concept | Purpose |
-|---|---|
-| **Plan** | Records what is intended, why, and how it will be verified |
-| **Natural conversation** | Expresses revisions, continuation, pauses, or a change of direction |
-| **Human Gate** | Allows or rejects a specific high-risk action |
+## Quick Confirmation
 
-Saying “the Plan looks good, continue” does not permanently open permissions. If later work deletes data, publishes a release, sends an email, or performs another high-risk action, DesireCore still follows the active approval policy.
+For simple tasks or tasks you're already familiar with, you can skip detailed review:
 
-## Plans vs Task Progress
+```
+You: "The plan is fine, start directly."
+```
 
-Plans describe strategy. Tasks describe assignable ownership and execution state. A Plan with many steps does not automatically need a task list. Agents use Tasks when work needs cross-agent ownership, waiting or blocking, ongoing progress visibility, or when you explicitly request tracking.
+Or for low-risk routine tasks, you can inform the agent in advance that plan confirmation isn't needed:
+
+```
+You: "Help me review this contract, no need to confirm the plan with me, just follow the previous process."
+```
+
+:::warning Recommended to Confirm Plan for First-Time Execution of New Task Types
+Even if you trust the agent, it's recommended to take a look at the plan when executing a new type of task for the first time. After confirming it truly understands your requirements, you can confidently skip it next time.
+:::
+
+## Where Plan Files Live
+
+Each agent's plan files live in **its own working directory** under the `.desirecore/plans/` subdirectory—this is intentional:
+
+- **Reviewable**: Plans are plain Markdown files; you can open them in any editor and diff versions
+- **Auto-versioned**: Each revision creates an immutable historical version (`revisions/`); PLAN.md always holds the latest
+- **Version-controllable**: If the working directory is a git repo, plans become the team's "decision log"
+- **Tied to the project**: Switch machines or check out a fresh copy of the repo to see all historical plans
+
+Different agents **cannot see each other's plans**—switching to another agent shows you its own plan library, no confusion.
+
+:::info Don't want plans cluttering the directory?
+Add `.desirecore/plans/` to `.gitignore` to keep them local only and out of version control.
+:::
 
 :::info Next Step
-See [Execution Monitoring](./03-execution-monitoring.md) to learn how to inspect active tasks, tool calls, and receipts.
+After confirming the plan, the agent begins execution. Go to [Execution Monitoring](./03-execution-monitoring.md) to see how the agent uses a **task list** to make every step's progress transparent to you.
 :::
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/04-edit-persona.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/04-edit-persona.md
index 48ee906..027fab8 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/04-edit-persona.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/04-edit-persona.md
@@ -20,7 +20,7 @@ Persona is saved in the `persona.md` file in the Agent directory. It tells the A
 | **Forbidden Zones** | What not to do | "Don't use template clichés, don't avoid giving conclusions" |
 | **Uncertainty Handling** | What to do when unsure | "Explain uncertainty and provide verification path" |
 
-`persona.md` is part of the **Agent prompt layer**. At runtime, DesireCore also combines the current user's global prompt and prompts from every team the Agent belongs to. Open **Explorer -> Prompt Center** to edit these sources together and preview the result. See [Prompt Center and Prompt Layers](./11-prompt-center.md).
+`persona.md` is part of the **Agent prompt layer**. At runtime, DesireCore also combines the current user's global prompt and prompts from every team the Agent belongs to. Open **Explorer -> Prompt Center** to edit these sources together and preview the result. See [Prompt Center and Prompt Layers](./12-prompt-center.md).
 
 :::info Persona vs. Principles
 **Persona** defines "how to do it"—tone, style, response methods. **Principles** define "what to do and not do"—rules, boundaries, priorities. They complement each other without overlapping.
@@ -103,5 +103,5 @@ The Agent will record your preferences and apply them in subsequent conversation
 ## Next Steps
 
 - [Edit Principles](./05-edit-principles.md) — Set behavioral boundaries for the Agent
-- [Prompt Center and Prompt Layers](./11-prompt-center.md) — Manage global, team, and Agent prompts
+- [Prompt Center and Prompt Layers](./12-prompt-center.md) — Manage global, team, and Agent prompts
 - [Create Custom Agent](./03-create-agent.md) — Review the creation process
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/05-edit-principles.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/05-edit-principles.md
index 63255bb..5906e98 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/05-edit-principles.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/05-edit-principles.md
@@ -95,4 +95,4 @@ At runtime, DesireCore combines editable prompts in this order: **global -> team
 
 - [File Explorer](./06-agent-files.md) — Browse the Agent's file structure
 - [Edit Persona](./04-edit-persona.md) — Adjust the Agent's tone and style
-- [Prompt Center and Prompt Layers](./11-prompt-center.md) — Understand global, team, and Agent prompt composition
+- [Prompt Center and Prompt Layers](./12-prompt-center.md) — Understand global, team, and Agent prompt composition
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/07-skills-management.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/07-skills-management.md
index 9d62ed8..3eb9918 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/07-skills-management.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/07-skills-management.md
@@ -53,7 +53,7 @@ Skill cards can show name, description, source, version, author, status, direct-
 3. Review the skill description, dependencies, and risk notes
 4. Install and confirm when prompted
 
-Global marketplace skills are installed into the global skills directory. Agent-bound skills are written into the corresponding agent repository.
+When installing a skill, you can choose the install target: global, a specific agent, or a project-level directory. Global marketplace skills are installed into the global skills directory where all agents can discover them. Agent-bound skills are written into the corresponding agent repository. Project-level skills only take effect in the corresponding work directory, making them ideal for maintaining team conventions, project scripts, and local templates alongside the project.
 
 ### Local Import
 
@@ -124,6 +124,39 @@ These fields affect card display, command completion, automatic triggering, tool
 The clearer the skill description, the easier it is for the agent to choose it at the right time. State when to use it and when not to use it near the top of `SKILL.md`.
 :::
 
+## Skill Source Priority
+
+When multiple skills are available for the same task, the agent considers them in the following order:
+
+| Source | Typical Path | Scope |
+|--------|-------------|-------|
+| Project-level Skill | `<workdir>/.agents/skills/` | Current project or work directory |
+| Claude-compatible Skill | `<workdir>/.claude/skills/` | Compatible with existing Claude project configs |
+| Agent Skill | `agents/<agent_id>/skills/` | Current agent |
+| Global Skill | Global skills directory | All agents |
+
+When both `.agents/skills` and `.claude/skills` exist, DesireCore prefers `.agents/skills`. This lets you migrate to the native structure at your own pace without breaking older projects.
+
+## Skill Export
+
+You can export individual skills from the skill detail panel. The exported ZIP includes:
+
+- `SKILL.md`
+- Optional scripts, references, templates, and asset files
+- Metadata, input/output schemas, and localized content
+
+Exporting skills is useful for sharing a single capability between teams rather than exporting an entire agent.
+
+## Multi-language and Resource References
+
+Skills can declare localized content. When the UI language is set to Chinese, the agent prioritizes the Chinese description; when set to English, it loads the English version. This allows the same skill to behave consistently across multilingual teams.
+
+Skill documents can use `${SKILL_DIR}` or `{{SKILL_DIR}}` to reference resources within the skill directory, such as templates, scripts, or sample files. At runtime, the system resolves these placeholders to real paths, avoiding hardcoded absolute paths across different machines.
+
+:::info Auto-injection
+Not every skill is automatically injected into the model context. Only skills that are explicitly invoked, determined to be needed by the agent, or allowed for auto-injection in their metadata are loaded. This reduces context pollution and unnecessary tool exposure.
+:::
+
 ## Next Steps
 
 - [Skill Packs](../09-capabilities/04-skill-packs.md) - Understand skills vs. tools
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/08-version-control.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/08-version-control.md
index 1def910..5acf022 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/08-version-control.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/08-version-control.md
@@ -113,6 +113,6 @@ During export, you can select content by category, such as Agents, skills, memor
 
 ## Next Steps
 
-- [Team Version Management](./09-team-version-management.md) - Manage an entire Agent team as a single versioned unit
+- [Team Version Management](./10-team-version-management.md) - Manage an entire Agent team as a single versioned unit
 - [Agent Types](./01-agent-types.md) - Review Agent types and positioning
 - [Create Custom Agent](./03-create-agent.md) - Create your own Agent
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-clone-and-sync.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-clone-and-sync.md
index a2dae9e..6636078 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-clone-and-sync.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-clone-and-sync.md
@@ -6,23 +6,94 @@ keywords: [Clone, agent clone, sync, conflicts, Agent Git]
 
 # Clone and Sync
 
-Clone creates a new agent from an existing one. Use it for experiments, project-specific variants, or personalizing a marketplace agent.
+Clone creates a new copy based on an existing agent. It is useful for experiments, preparing variants for different projects, or customizing a marketplace agent into your own version.
 
-## Clone Modes
+## When to Clone
 
-| Scenario | Behavior |
-|----------|----------|
-| Local agent | Copies AgentFS and creates a new agent ID |
-| Agent with remote source | Can keep remote relation, fork, or become local-only |
-| Marketplace agent | Copies core configuration and can still check updates |
+| Scenario | Description |
+|----------|-------------|
+| **Experimental overhaul** | You want to make major changes to an agent's persona or skills but are unsure of the result — clone a "sandbox" first |
+| **Project variants** | The same base agent needs to adapt to different projects (e.g., different client review standards) |
+| **Marketplace localization** | You installed an agent from the marketplace and want deep customization without upstream interference |
+| **Team collaboration template** | Create a standardized team agent template; members clone it and customize individually |
 
-The primary DesireCore agent is usually not cloneable.
+## Clone Steps
 
-## Private Data
+1. Open **Explorer → Agent List**
+2. Right-click the target agent (or click the `⋯` menu) and select **Clone**
+3. In the dialog, configure:
+   - **New Name**: give the clone an easily distinguishable name
+   - **Remote Relation** (only when the source agent has a remote origin):
+     - *Keep Remote*: continue receiving upstream updates
+     - *Fork*: create an independent branch, decoupled from the original remote
+     - *Local Only*: completely disconnect from the remote
+   - **Private Data Options** (see below)
+4. Click **Confirm Clone** — the system creates a new agent ID and completes the copy
 
-You can choose whether to copy memory, preferences, relationship data, and local resources. Avoid copying private data when sharing an agent with others.
+:::caution
+The core DesireCore agent (the system scheduler) cannot be cloned, to avoid breaking the main control entry. If the clone option is greyed out in the menu, the agent is protected.
+:::
+
+## Private Data Options
+
+When cloning, you can choose whether to copy private data between the current user and that agent:
+
+| Data Type | Description | Recommendation |
+|-----------|-------------|----------------|
+| Memory (`memory/`) | Facts, preferences, and experience the agent learned during conversations | Keep for personal clones; uncheck when sharing with others |
+| Preferences (`preferences/`) | User personalization settings | Depends on situation |
+| Relationship contract (`relationship.md`) | Collaboration agreements between you and the agent | Usually needs to be re-established; not recommended to copy |
+| Local resource files | Files in the work directory | Not recommended for large projects to save space |
+
+**Rule of thumb**: creating a clone for yourself → keep memory and preferences; preparing a template for others or a team → do not copy private data.
+
+## Syncing Updates
+
+If a cloned agent still retains its remote source (i.e., you chose "Keep Remote"), it can continue receiving upstream updates:
+
+1. Open the agent details page and check the **Source** area for the remote repository URL
+2. Click **Check for Updates** — the system fetches the latest remote commits and compares them with local
+3. If new content is available, a list of changed files and a diff summary are displayed
+4. Click **Merge Updates** — the system performs a Git merge
+
+:::info Update Strategy
+- **Pure config updates** (persona, principles, skills): usually safe to merge
+- **New skills/tools**: added automatically without affecting existing configs
+- **Deletions or renames**: require manual confirmation; the system will not silently delete files you already have locally
+:::
 
 ## Conflict Resolution
 
-When local and remote changes touch the same file, DesireCore opens a conflict resolver. You can keep local, use remote, manually merge, or keep both. The resolved result is committed automatically.
+When both local and remote modify the same file, DesireCore prevents direct overwrite and opens a conflict resolver:
+
+1. **View conflict file list** — highlighted files indicate both sides made changes
+2. **Open Diff view** — side-by-side comparison of local and remote versions
+3. **Choose a resolution strategy**:
+   - **Keep Local**: discard remote changes, use your version
+   - **Use Remote**: accept upstream update, overwrite local changes
+   - **Manual Edit**: decide line by line in the editor which content to keep
+   - **Keep Both**: append remote content as a new file (e.g., `persona-remote.md`)
+4. After resolving all conflicts, click **Finish Merge** — the system commits automatically
+
+:::tip Long-term Customization
+If you plan to significantly modify a marketplace agent long-term, consider forking to your own remote repository. This way:
+- Upstream updates are not pushed automatically; you choose when to sync
+- Conflict scope is more controllable, since you know exactly what you changed
+- Other team members can create their own versions based on your fork
+:::
+
+## FAQ
+
+| Problem | Solution |
+|---------|----------|
+| Cloned agent behaves differently from the original | Check if you missed private data (memory, preferences), or the new ID caused relationship data not to migrate |
+| Sync shows "cannot merge" | Usually because local has uncommitted changes; manually commit or stash on the agent files page first |
+| Want to restore pre-clone state | Cloning does not modify the original agent — it remains unaffected at all times |
+| Can a clone join a team? | Yes. After cloning, it is an independent agent and can join teams like any other agent |
+
+---
 
+:::info Next Steps
+- [Version Control](./08-version-control.md): learn about the agent's Git version management
+- [Team Version Management](./10-team-version-management.md): share and sync agent configurations within a team
+:::
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/10-team-version-control.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/10-team-version-control.md
deleted file mode 100644
index d7ca78b..0000000
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/10-team-version-control.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: Team Version Control
-description: Host teams with Git, publish releases, and distribute team agents through the marketplace.
-keywords: [team, Git, release, fork, marketplace, remote]
----
-
-# Team Version Control
-
-Teams can be versioned with Git just like agents. This is useful when multiple people maintain a group of agents, publish releases, and distribute them through a marketplace or remote repository.
-
-## Capabilities
-
-| Capability | Description |
-|------------|-------------|
-| Remote hosting | Configure a Git remote for the team |
-| Fork install | Create a local copy from a remote team |
-| Release | Create an installable team snapshot |
-| Marketplace distribution | Publish a team for others to install |
-| Member locking | Keep member agents pinned to a team release |
-
-Personal conversations, private memory, run logs, and local caches are not part of a team release by default.
-
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/10-team-version-management.md
similarity index 100%
rename from i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md
rename to i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/10-team-version-management.md
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/11-team-version-control.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/11-team-version-control.md
new file mode 100644
index 0000000..142cb85
--- /dev/null
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/11-team-version-control.md
@@ -0,0 +1,107 @@
+---
+title: Team Version Management FAQ
+description: Frequently asked questions and troubleshooting for team version management — permissions, conflicts, member version divergence, and more.
+keywords: [team version, FAQ, troubleshooting, conflicts, member version, permissions]
+---
+
+# Team Version Management FAQ
+
+This page collects common questions about team version management. For the full operation guide, see [Team Version Management](./10-team-version-management.md).
+
+## Connection & Push
+
+### Push fails with "rejected - non-fast-forward"
+
+The remote has commits your local copy does not. Pull first, then push:
+
+1. Click **Pull**
+2. Wait for the merge to complete (most cases merge automatically)
+3. Click **Push** again
+
+### Connecting a remote shows "authentication failed"
+
+- Check whether your OAuth session has expired: go to **Settings → Connected Accounts** and re-authorize GitHub/Gitee
+- If you use a PAT (personal access token), confirm it has not expired and has `repo` scope
+- For private repositories, make sure the token has read/write access to that specific repository
+
+### Push succeeds but the remote shows no changes
+
+- Verify the target branch is correct (default is `main`; some repositories use `master`)
+- Refresh the remote web page — there may be a cache delay
+
+## Members & Versions
+
+### Installing a team shows "cannot install: missing remote address"
+
+The member agent is local-only (not pushed to any Git repository). You need to:
+
+- Ask the team publisher to push the member to the marketplace or a Git remote
+- Or create a local agent with the same configuration as a substitute
+
+### Team member version shows "diverged"
+
+You have locally modified that member agent's configuration (persona, skills, etc.), creating a difference from the team's locked version.
+
+- **No impact on usage**: the local version works as usual
+- **Not overwritten**: upgrading the team will not forcefully overwrite your changes
+- **To sync**: manually push your changes from the member agent's version control, then upgrade the team
+
+### After changing the team leader, is the old leader's config still there?
+
+Yes. Changing the leader only updates the organizational relationship; it does not affect any member's configuration, memory, or skills. The leader change is recorded in version history.
+
+## Conflict Resolution
+
+### Pulling shows a conflict file list
+
+This usually happens when two people modified the same team-shared resource (e.g., a shared skill or rule file).
+
+| Strategy | When to use |
+|----------|-------------|
+| **Keep Local** | Your changes are newer or more complete |
+| **Use Remote** | The other person's changes are what you want |
+| **Manual Edit** | You need to merge changes from both sides |
+| **Keep Both** | When unsure, keep both and clean up later |
+
+### Two members each added a new agent — will it conflict?
+
+Usually not. The member list merge strategy is **union** — if A added carol and B added dave, the merged team has both carol and dave. A true conflict only occurs when both modify the same record (e.g., both remove the same person).
+
+## Publishing & Installation
+
+### Publishing shows "member is missing a remote source"
+
+The team contains a local-only agent. Before publishing:
+
+1. Check each member's source (local / Git / marketplace / built-in)
+2. Push local-only members to Git or publish them to the marketplace
+3. Re-publish the team
+
+### After installing from a link, is there still a connection to the original author?
+
+No. The system automatically disconnects from the original remote during installation. You get a completely independent copy (similar to a Git fork); subsequent changes do not affect the original author.
+
+### Can I publish an installed team to the marketplace?
+
+Yes. As long as all members have remote sources, you can publish just like the original creator. Using a different team name is recommended to avoid confusion.
+
+## Dissolve & Recovery
+
+### Will dissolving a team lose data?
+
+No. Dissolving is **archiving**, not deleting:
+
+- The team directory is moved to an archive area and fully preserved on disk
+- Version history, shared resources, and the member list are all retained
+- Member agents themselves are unaffected — they simply no longer belong to that team
+
+### How do I restore a dissolved team?
+
+Move the team directory from the archive area back to the active directory. The system will re-recognize the version history and member relationships.
+
+## Related Pages
+
+- [Team Version Management Full Guide](./10-team-version-management.md)
+- [Single Agent Version Management](./08-version-control.md)
+- [Clone and Sync](./09-clone-and-sync.md)
+- [Cross-Agent Collaboration](../04-delegation/06-cross-agent.md)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/11-prompt-center.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/12-prompt-center.md
similarity index 100%
rename from i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/11-prompt-center.md
rename to i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/12-prompt-center.md