diff --git a/docs/README.md b/docs/README.md
index b32a2cd..7d9517e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -16,3 +16,14 @@
 跨产品契约以 aiops/opsxcli 的 `13-运行结果状态与可续跑契约.md` 为准。
 
 - [02-运行中消息排队](02-运行中消息排队.md) — 忙时排队 / 立即 / 编辑 / 撤销
+
+## SDD（何时必填）
+
+模板：[sdd-template.md](sdd-template.md)。成品落点：[sdd/](sdd/)（`docs/sdd/`）。
+
+| 级别    | 何时                                                         | 要不要 SDD                                   |
+| ------- | ------------------------------------------------------------ | -------------------------------------------- |
+| S0 / S1 | 文案、图标、换链、单点小修                                   | 免。BACKLOG 或提交说明够用                   |
+| S2 / S3 | 跨模块、有契约 / 风险 / 发布（新能力、协议、存储、安全边界） | **必填**。从模板拷到 `docs/sdd/`，填完再开工 |
+
+UI 刀在模板「验收标准」里加一行观感 / 交互过线口径即可，不必另起设计专章。
diff --git a/docs/architecture-refactor.md b/docs/architecture-refactor.md
index 6afca77..0cc34c4 100644
--- a/docs/architecture-refactor.md
+++ b/docs/architecture-refactor.md
@@ -4,6 +4,18 @@
 
 已落地：本地文件业务下沉至无 Tauri 依赖的 `services/files.rs`；`AppError` 部分接入；前端 IPC 拒绝错误统一映射；settings 功能模型、Hook 和控件提取；设置串行保存与失败回退；系统主题同步修复。实现位置与限制见 [架构说明](architecture.md)。
 
+## 已完成（勿再当待办）
+
+下列已在代码里，不再算轨道 A/B/C 的工作项。A/B/C 本身**未完成**，保持下方原文。
+
+- [x] 本地文件业务下沉到无 Tauri 依赖的 `services/files.rs`（DTO：`domain/files.rs`）
+- [x] 前端 IPC 拒绝错误统一映射（`src/platform/invoke.ts`）
+- [x] settings 功能模型、Hook、控件提取；设置串行保存与失败回退
+- [x] 系统主题同步修复（`useTheme`）
+- [x] `AppError` / 稳定错误码：文件操作已部分接入（**未**覆盖全部业务错误，不要勾成全量完成）
+
+未勾、仍是目标：EventSink、`bind_app_handle` 拆除、specta/ts-rs、infrastructure 端口。
+
 当前真实分层是 **commands → services → domain DTO**。目录里虽有 `application/`、`infrastructure/`，但：
 
 - `infrastructure/` 只有 `file_log`，services 并不走它。
diff --git a/docs/architecture.md b/docs/architecture.md
index 7364b8c..3ae51fb 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -192,3 +192,20 @@ Release 使用 LTO、单 codegen unit、`panic = abort` 和符号剥离。平台
 `./run.sh gui` 走 `tauri dev`，macOS 启动的是 `src-tauri/target/debug/` 下的裸二进制。Dock 对非 `.app` 进程显示默认齿轮图标——这是 Tauri 通病，不是 `bundle.icon` 没配。正式 `tauri build` 的 `.app` / DMG 三族图标一致。
 
 安装包与校验和只放在 `src-tauri/target/<triple>/release/bundle/`，由 `build.sh` / `release.py` 直接读写，不再拷到仓库根 `release/`。opsxapi 开发态正确 Dock 图标来自临时 `.app` 壳（`src-tauri/target/gui-app/`，刷 `icon.icns`）。要对齐开发态 Dock 图标应复用该壳，而不是另建发版目录。
+
+## 近期已落地（补记）
+
+- **AI 会话**：对话、提示词、终端上下文和工具输出只在当前面板内存；关闭面板即清空，不落盘。本轮运行的安全模式在开始时锁定；需要确认的命令可「本会话允许」，该允许只活在当前面板，不跨重启。Provider / 模型路由仍走 `ai-providers-v1`，API Key 不进 WebView。详见上文「SSH Agent CLI 边界」。
+- **关于页外链**：设置 → 关于里的官网、微信群、GitHub 走 `opsxApi.openExternal`（Tauri opener，系统浏览器）。桌面不可用时才回退 `window.open`。不在 WebView 内嵌打开，也不把链接当应用内路由。
+
+## 最后核对（已落地 vs 目标）
+
+核对日以本文件提交为准。产品行为以代码为准；重构目标仍以 [架构重构](architecture-refactor.md) 为准，不在这里再开第三份总览。
+
+| 项                                                             | 状态                             |
+| -------------------------------------------------------------- | -------------------------------- |
+| 本地文件 service 无 Tauri 依赖、设置串行保存、IPC 拒绝错误映射 | 已落地（见「已落地的职责边界」） |
+| AI 会话仅内存、关于外链走系统浏览器                            | 已落地（见上节）                 |
+| EventSink：services 不再持 `AppHandle` / `bind_app_handle`     | 目标，未做（轨道 A）             |
+| specta / ts-rs 契约生成                                        | 目标，未做（轨道 B）             |
+| infrastructure 端口（SessionStore / SecretStore）              | 目标，未做（轨道 C）             |
diff --git a/docs/sdd-template.md b/docs/sdd-template.md
new file mode 100644
index 0000000..63a5eb4
--- /dev/null
+++ b/docs/sdd-template.md
@@ -0,0 +1,74 @@
+# SDD 模板路径: docs/sdd-template.md
+
+# SDD 模板（S2 / S3 使用）
+
+# SDD-xxx：<功能名称>
+
+| 字段            | 内容                |
+| --------------- | ------------------- |
+| 版本 / 变更级别 | 0.1 / S2 或 S3      |
+| 设计状态        | Draft               |
+| 实现状态        | Not Started         |
+| 负责人 / 日期   | 待指定 / YYYY-MM-DD |
+| 关联需求        | -                   |
+| 批准状态        | 未批准              |
+
+## 1. 背景、目标与范围
+
+- **当前行为与证据**：
+- **本次目标**：
+- **非目标**：
+- **必须保留的行为**：
+
+## 2. 需求与约束
+
+- FR-01：当 <条件> 时，系统必须 <行为>。
+- NFR-01：<性能 / 安全 / 兼容要求及测量方式>
+- 边界条件、异常场景、权限要求
+
+## 3. 架构与方案
+
+- 涉及模块及职责
+- 关键数据流 / 调用关系
+- 复用哪些现有能力
+- 关键取舍及理由
+- Agent 可自主决定的实现细节
+
+## 4. 接口、数据与配置契约
+
+（已有权威文件时直接引用路径，仅说明差异）
+
+- 接口变更：
+- 数据模型 / 迁移：
+- 配置变更：
+- 兼容性：
+
+## 5. 风险与验收
+
+### 风险
+
+| 风险或失败场景 | 防护 / 降级 / 恢复 | 可观察信号 |
+| -------------- | ------------------ | ---------- |
+|                |                    |            |
+
+### 验收标准
+
+| AC    | 对应需求 | 前置条件与操作                                           | 预期结果     | 验证方式         | 结果    |
+| ----- | -------- | -------------------------------------------------------- | ------------ | ---------------- | ------- |
+| AC-01 | FR-01    |                                                          |              |                  | Not Run |
+| AC-UI | （可选） | UI 刀：对照设计过一遍观感 / 交互（图标、外链、确认条等） | 过线口径满足 | 目视或针对性测试 | Not Run |
+
+UI 刀：在上表 FR→AC 加一行观感 / 交互过线口径即可（图标、外链、确认条等），不必另起设计专章。
+
+## 6. 发布与恢复（S3 必填）
+
+- 前置条件（配置、迁移、备份等）
+- 发布顺序与健康检查
+- 回滚或前向修复步骤
+- 不可逆操作说明
+
+## 7. 待决问题
+
+| 问题 | 是否阻塞 | 推荐方案 |
+| ---- | -------- | -------- |
+|      |          |          |
diff --git a/docs/sdd/README.md b/docs/sdd/README.md
new file mode 100644
index 0000000..ab37b55
--- /dev/null
+++ b/docs/sdd/README.md
@@ -0,0 +1,7 @@
+# docs/sdd/
+
+S2 / S3 变更的 SDD 成品落这里。
+
+- 拷贝模板：[`../sdd-template.md`](../sdd-template.md)
+- 命名建议：`SDD-<短名>.md` 或 `YYYYMMDD-<短名>.md`
+- S0 / S1（文案、图标、换链、小修）不必开 SDD