diff --git a/docs/frontend_architecture.md b/docs/frontend_architecture.md
new file mode 100644
index 0000000..fa1cc9b
--- /dev/null
+++ b/docs/frontend_architecture.md
@@ -0,0 +1,96 @@
+# 前端架构约定与回归清单（tools/ Web 界面）
+
+> 2026-07 网页框架化重构产物。本文档固化 tools/ 目录的模块化约定，
+> 所有新增页面/模块必须遵循；同时提供改动后的回归验证清单。
+
+## 1. 架构总览
+
+- **托管方式**：Web 资源不嵌入固件，由 `tools/serve.bat`（`python -m http.server 8080`）本地托管；
+ 浏览器跨源调用 ESP32 REST API（路由表见 `main/server/wifi_ota.cpp` kHttpRoutes）。
+ 改动 web 文件无需重编译固件。
+- **零构建**：原生 ES Modules，无打包器/无 CDN 依赖；页面必须经 http 访问（ES module 有 file:// CORS 限制）。
+
+### 页面薄入口范式
+
+每个页面 = HTML（纯结构，无内联 script/style/事件）+ 单个 `type="module"` 入口：
+
+| 页面 | 入口 | 说明 |
+|---|---|---|
+| index.html | js/app.js + js/ota/console-mode.js + js/ble_ota.js | OTA 控制台（WiFi/BLE 双通道，三入口历史原因保留） |
+| motor.html | js/motor/main.js | 电机控制台（独立 seed 主题，见 §4） |
+| can.html | js/can.js | CAN 工具 |
+| can_monitor.html | js/can_monitor.js | CAN 接收监控 |
+
+### JS 分层
+
+```
+js/
+├── common/ 跨页面公共层：base-url(IP存取) / toast / log / polling / connection / utils
+├── ota/ OTA 状态机与上传流程（高风险区，见 §5）
+├── ble/ BLE OTA 传输时序（高风险区，见 §5）
+├── can/ CAN 子系统（dbc 为基础层，导出共享 state/el）
+├── motor/ 电机控制台
+└── *.js 页面入口（薄装配层）
+```
+
+## 2. 缓存戳约定（强制）
+
+- **JS 间 import 一律不带 `?v=`**——同一模块带不同 query 会被浏览器实例化两次，
+ 导致模块级单例（state/toast 去抖等）分裂。
+- 版本戳只出现在 HTML 的 `
+