diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2756242
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,56 @@
+# AGENTS.md - ostool
+
+## 适用范围
+
+本文件适用于整个仓库。子目录中的 `AGENTS.md` 只对对应目录生效，并覆盖或补充本文件规则。
+
+## 项目结构
+
+- `ostool/`: 主 CLI/库，覆盖 OS 构建、`menuconfig`、QEMU、U-Boot、TFTP、串口、
+  board-client 和 `cargo-osrun` 流程。
+- `ostool-server/`: 开发板管理服务器，包含 API、串口会话、TFTP 文件、电源管理和
+  面向 systemd 的部署脚本。
+- `ostool-server/webui/`: `ostool-server` 嵌入的 Vue/Vite/pnpm 前端。
+- `jkconfig/`: 基于 Ratatui 的 JSON Schema 配置编辑器库，并提供可选 web 功能。
+- `fitimage/`: 用于构建 U-Boot 兼容 FIT 镜像的库。
+- `uboot-shell/`: 异步 U-Boot shell 与 YMODEM 通信库。
+- `.github/workflows/check.yaml`: 当前格式化、clippy、构建和测试命令的 CI 来源。
+
+## 依赖与工具
+
+- 复现检查时，优先使用本仓库或 CI 声明的工具链和依赖版本。
+- 不要为了通过检查临时引入仓库未声明的工具、依赖或配置；需要新增或替换工具链、
+  包管理器、安装脚本等时，应作为独立变更并说明依据。
+- 当前环境缺少必要工具时，说明缺失工具和未能运行的检查。
+
+## Git 与提交
+
+- 除非用户明确要求留在当前分支，否则仓库改动应在功能分支上完成。
+- 遵循近期提交风格，使用 Conventional Commits，例如 `fix(ostool): ...`、
+  `chore(ostool-server): ...`、`docs: ...` 或 `refactor(jkconfig): ...`。
+- 不要把无关改动混入同一个提交。只暂存属于当前任务的文件。
+
+## 验证
+
+- 仓库级 Rust 改动应在可行时复现当前 CI target matrix 中的格式化、clippy、构建和
+  测试命令。当前 `.github/workflows/check.yaml` 使用
+  `x86_64-unknown-linux-gnu`。
+- 局部改动优先运行覆盖被修改区域的最小 package 或 web UI 检查，并明确说明实际运行
+  或未运行的命令。
+- CI 会安装 QEMU、U-Boot tools、libudev、Node.js 24 和 pnpm 10.33.0。把这些视为
+  CI 验证环境证据，不要据此要求贡献者准备同一批工具。
+
+## 文档
+
+- 用户可见的 CLI、服务器 API、配置格式、安装路径或工作流发生变化时，同步更新相关
+  README 或局部文档。
+- 根 README 同时有中文和英文版本。修改共享的用户文档时，保持两个版本一致。
+- changelog 按 package 拆分。只有发布或用户明确要求时才更新 changelog。
+
+## Rust 约定
+
+- 保持各 package 已采用的 edition 和公开 API 风格。
+- 配置数据优先使用已有 `serde`、`schemars`、TOML 和 JSON 类型进行结构化解析或序列化，
+  不要手写脆弱的字符串处理。
+- 串口、TFTP、QEMU、U-Boot 和开发板电源相关改动属于操作敏感路径。副作用必须明确，
+  并通过测试或记录过的手动验证覆盖。
diff --git a/fitimage/AGENTS.md b/fitimage/AGENTS.md
new file mode 100644
index 0000000..3f5590c
--- /dev/null
+++ b/fitimage/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md - fitimage crate
+
+## 适用范围
+
+适用于 `fitimage/`，即 U-Boot FIT 镜像构建库。
+
+## 局部规则
+
+- 生成的 FIT 结构、FDT token、load/entry 地址、hash 字段和压缩元数据都属于兼容性敏感
+  内容。
+- 保持纯库定位。除非用户明确要求调整 package 范围，否则不要在这里新增 CLI 行为。
+- 优先扩展现有 builder 和类型化配置结构，不要重复实现字节布局逻辑。
+- README 示例和测试应与公开 API 变化保持一致。
+
+## 验证
+
+- crate 改动优先运行 `cargo test -p fitimage`。
+- 格式变化应新增或更新 `fitimage/tests/` 下的测试；可行时，在受控环境中用 U-Boot 工具对照
+  行为。
diff --git a/jkconfig/AGENTS.md b/jkconfig/AGENTS.md
new file mode 100644
index 0000000..b58f30a
--- /dev/null
+++ b/jkconfig/AGENTS.md
@@ -0,0 +1,18 @@
+# AGENTS.md - jkconfig crate
+
+## 适用范围
+
+适用于 `jkconfig/`，即 Ratatui JSON Schema 配置编辑器。
+
+## 局部规则
+
+- 保持 schema 解析、resolver 行为和 UI 编辑语义在 TOML/JSON 输入之间一致。
+- 配置数据优先使用 `serde_json`、`schemars` 和 TOML 的结构化处理，不要手写文本替换。
+- 可选 `web` feature 属于 crate 对外表面。修改共享数据或路由处理时，检查 feature-gated
+  路径。
+- 公开用法、支持的 schema 行为或示例变化时，同步更新 `jkconfig/README.md`。
+
+## 验证
+
+- crate 改动优先运行 `cargo test -p jkconfig`。
+- 修改行为尚未被覆盖时，为 schema 边界、resolver 行为或 TUI 状态变化添加聚焦测试。
diff --git a/ostool-server/AGENTS.md b/ostool-server/AGENTS.md
new file mode 100644
index 0000000..4990c82
--- /dev/null
+++ b/ostool-server/AGENTS.md
@@ -0,0 +1,25 @@
+# AGENTS.md - ostool-server crate
+
+## 适用范围
+
+适用于 `ostool-server/`。`ostool-server/webui/` 有单独的局部规则。
+
+## 局部规则
+
+- `src/api/` 中的 REST/WebSocket 模型、会话生命周期、开发板租约、TFTP 文件处理和串口
+  访问都是跨组件契约。契约变化时，同步更新服务器测试和 web UI client/types。
+- 除非用户明确要求，不要在宿主机运行 `scripts/install.sh`、`scripts/update.sh`，不要修改
+  systemd unit，也不要触碰 `/etc/ostool-server`。
+- `build.rs` 会复制 web UI 并运行 pnpm 构建嵌入资源。保持该行为可复现，不要提交
+  `webui/dist`、`node_modules` 或其他生成的依赖输出。
+- 电源管理和串口发现改动应保持保守：保留稳定设备身份处理，并让失败模式对调用方可见。
+
+## 验证
+
+- 服务器改动优先运行 `cargo test -p ostool-server`。
+- 注意：该 crate 的 `build.rs` 会触发 `pnpm install --frozen-lockfile` 和
+  `pnpm run build`，依赖 Node.js 和 pnpm，并会在 Cargo target 目录下生成 web 依赖和
+  构建输出。工具不可用时，说明跳过了该检查，不要通过改变工具来源或提交生成产物来
+  掩盖环境差异。
+- API 契约、嵌入 web 资源或构建集成变化时，在 Node.js 和 pnpm 可用的环境中同步运行
+  `ostool-server/webui` 的局部检查。
diff --git a/ostool-server/webui/AGENTS.md b/ostool-server/webui/AGENTS.md
new file mode 100644
index 0000000..d9df596
--- /dev/null
+++ b/ostool-server/webui/AGENTS.md
@@ -0,0 +1,23 @@
+# AGENTS.md - ostool-server webui
+
+## 适用范围
+
+适用于 `ostool-server/webui/` 中的 Vue/Vite 前端。
+
+## 局部规则
+
+- 使用 `packageManager` 和 `pnpm-lock.yaml` 声明的 pnpm。不要切换到 npm、yarn 或其他
+  包管理器。
+- Node.js 或 pnpm 不可用时，说明哪些 web UI 检查无法运行，不要切换包管理器，也不要提交
+  生成的依赖输出。
+- 保持 `src/api/` 和 `src/types/` 中的 API client 类型与
+  `ostool-server/src/api/models.rs` 对齐。
+- 不要提交 `dist`、`node_modules`、coverage 输出或其他生成的 web 依赖产物。
+- 保持现有的运维型 UI 风格：紧凑的 board/session/server 状态视图、明确的错误状态，以及
+  直接映射到服务器动作的控件。
+
+## 验证
+
+- UI 逻辑改动优先运行 `pnpm --dir ostool-server/webui test`。
+- 修改路由、类型使用、构建配置或嵌入资源时，运行
+  `pnpm --dir ostool-server/webui build`。
diff --git a/ostool/AGENTS.md b/ostool/AGENTS.md
new file mode 100644
index 0000000..958f118
--- /dev/null
+++ b/ostool/AGENTS.md
@@ -0,0 +1,22 @@
+# AGENTS.md - ostool crate
+
+## 适用范围
+
+适用于 `ostool/`，也就是主 CLI/库和 `cargo-osrun` 二进制。
+
+## 局部规则
+
+- 命令行行为、配置 schema、生成的默认值和终端交互都是面向用户的公开契约。
+- 修改公开行为时，同步维护 `src/lib.rs` 导出、`src/main.rs` CLI 接线和 README 示例。
+- 配置改动应经过现有类型化配置结构和 schema 生成路径。除非当前模式已经要求，否则不要
+  为运行时行为加入静默 fallback 默认值。
+- 串口、QEMU、U-Boot、TFTP 和远程开发板流程可能影响真实设备。未实际运行硬件或对应
+  fixture 时，不要声称已经验证。
+
+## 验证
+
+- crate 内改动优先运行 `cargo test -p ostool` 等聚焦检查。
+- 修改 CLI 解析或 compile-fail 预期时，同步维护 `ostool/tests/` 下的相关测试，必要时
+  包括 `ostool/tests/ui/`。
+- 如果改动依赖 QEMU、串口硬件或 `ostool-server` 实例，说明具体的手动验证结果或无法
+  验证的原因，不要暗示已经运行。
diff --git a/uboot-shell/AGENTS.md b/uboot-shell/AGENTS.md
new file mode 100644
index 0000000..9b68949
--- /dev/null
+++ b/uboot-shell/AGENTS.md
@@ -0,0 +1,17 @@
+# AGENTS.md - uboot-shell crate
+
+## 适用范围
+
+适用于 `uboot-shell/`，即异步 U-Boot shell 与 YMODEM 库。
+
+## 局部规则
+
+- prompt 检测、中断处理、超时、字节流和 YMODEM 传输行为都属于协议敏感内容。
+- 除非要求更大范围的设计调整，否则围绕 `futures::io` 保持 runtime-neutral。
+- 未实际运行真实目标或明确的串口 fixture 时，不要声称已经验证硬件 U-Boot 行为。
+- 日志应有助于协议诊断，但不要淹没正常输出。
+
+## 验证
+
+- crate 改动优先运行 `cargo test -p uboot-shell`。
+- 修改超时、prompt、CRC 或 YMODEM 行为时，添加聚焦的字节流或协议测试。