diff --git a/AGENTS.md b/AGENTS.md
index c92c83b..419df6a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,12 +76,14 @@
 
 ## 发版本流程
 
+本节是通用流程；本项目的版本文件、发版命令和配置细节见 `docs/architecture.md`「发版」。
+
 - 发版本只在用户明确确认后触发；触发前工作区必须干净（见「收尾」）。
 - 先把 `CHANGELOG.md` 的 `Unreleased` 变更整理成新的版本记录，保留空的 `Unreleased` 标题，并作为一个普通提交先提交。
-- 发版前跑一次 `uv lock` 自检：它若改动了 `uv.lock`，说明某个任务漏提交了锁文件——补进那次任务，不为它单开提交。
-- 工作区干净后执行 `uv tool run bump-my-version bump patch`：它一次完成「改 `metadata.yaml` / `pyproject.toml` / `uv.lock` 三处 `version` + 自动提交 + 自动打 tag」，**不要再手动 commit 或 `git tag`**。普通提交不动版本号。
-- 发完用 `git log -1` 和 `git tag -l` 确认 tag 存在、HEAD 正确；打 tag 前工具会失败于同名 tag，不覆盖已有 tag。
-- 发版本流程中不要执行编译、测试或构建，除非用户明确要求；前端改动仍需 `pnpm build` 并把 `static/` 一起提交（在发版前的普通提交里完成）。
+- 发版前先做依赖锁文件自检：锁文件若有变化，说明某个任务漏提交了它——补进那次任务，不为它单开提交。
+- 版本号只在发版时提升，普通提交不动版本号；用项目配置好的发版工具一次完成「改版本号 + 提交 + 打 tag」，**不要再手动 commit 或打 tag**。
+- 打 tag 前确认没有同名 tag，不覆盖已有 tag；发完确认 tag 存在、HEAD 正确。
+- 发版本流程中不要执行编译、测试或构建，除非用户明确要求；产物（如前端构建）在发版前的普通提交里完成。
 
 ## 项目契约
 
diff --git a/docs/agent_workflow.md b/docs/agent_workflow.md
index cd82be0..a3d1291 100644
--- a/docs/agent_workflow.md
+++ b/docs/agent_workflow.md
@@ -88,7 +88,8 @@
 - 为什么：行为规则和项目契约混在一个文件里，改契约时没人会想到 review 规则文件，两边都不好维护。
 - 证据：
   - `v0.0.8 (aa48145)`：`AGENTS.md` 93 行，其中「日志规范」+「代码结构 / 平台插件」约 4KB 是项目契约，而 `docs/architecture.md` 已在维护同一套分层与插件契约。
-- Seen：1×
+  - `d8808e6`：`AGENTS.md`「发版本流程」里写死了本项目的文件名和命令（`metadata.yaml`、`uv tool run bump-my-version …`），用户指出这些该放进 `docs/architecture.md`，`AGENTS.md` 只留通用流程；手写命令还出现过 `runm` / `etadata.yaml` 这类笔误。
+- Seen：2×
 - 状态：已升级 → AGENTS.md「项目契约」（两节已并入 `docs/architecture.md`，AGENTS.md 降到 79 行）
 
 ### 一个文件只留一份权威账本
diff --git a/docs/architecture.md b/docs/architecture.md
index fe14cb1..8c404af 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -255,3 +255,15 @@ NOTIFY = notify.register(DaidaiPush())  # 插件 main.py 末尾注册
 - key 约定：账号相关用账号 id（页面卡片「课程日志」直接显示）；全局 / 系统事件用 `"system"`（右上角「系统日志」弹窗显示）。
 - 时间戳、级别、格式都由 `runtime.log` 统一拼（`时间 [级别] 内容`），模块里不要自己加时间前缀。
 - 前端读日志统一用 `/api/log?key=&since=`（实时）+ `/api/log/history?key=&tail=`（历史兜底），不要另起一套日志接口。
+
+## 发版
+
+通用流程见 `AGENTS.md`「发版本流程」；本项目的具体做法：
+
+- 版本号三处：`metadata.yaml`、`pyproject.toml`、`uv.lock`（其中 `study-tool` 那一段），由 `pyproject.toml` 的 `[tool.bumpversion]` 统一改，不要手改。
+- 发版前先 `uv lock` 自检；它若改动了 `uv.lock`，说明某个任务漏提交了锁文件，补进那次任务。
+- 命令：`uv tool run bump-my-version bump patch`。工作区需干净；它一次完成改三处版本、提交 `chore(release): vX.Y.Z`、打 tag `vX.Y.Z`，不要再手动 commit 或 `git tag`。
+- 发完用 `git log -1` 和 `git tag -l` 确认 tag 存在、HEAD 正确；同名 tag 已存在时工具会失败，不会覆盖。
+- 前端有改动时，`pnpm build` 并提交 `static/` 要在发版前的普通提交里完成，发版步骤本身不构建。
+- 改了 `[tool.bumpversion]` 配置后，先跑 `uv tool run bump-my-version bump patch --dry-run --allow-dirty -vv`，确认三个文件都会被改。
+- 仓库文件是 CRLF，且 bump-my-version 默认按字面量搜索：用正则的条目必须写 `regex = true`，并且不要用 `$` 锚定行尾（`uv.lock` 那条用 `\r?\n` 兼容换行）。