From 041b29432bded4a9872a5782ae1c01645841d165 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=B3=9B=E5=87=BD?=
 <71737444+Ivor-NCUT@users.noreply.github.com>
Date: Fri, 31 Jul 2026 16:50:49 +0800
Subject: [PATCH] docs: clarify Codex rules and AGENTS loading

---
 README.md    | 16 ++++++++++++++++
 README.zh.md | 16 ++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/README.md b/README.md
index 6c5c6689..b89a2a23 100644
--- a/README.md
+++ b/README.md
@@ -218,6 +218,22 @@ Mode mapping:
 
 The legacy `sandbox` field is still readable for old configs. After the bridge saves the profile, it migrates that setting to canonical `permissions`.
 
+## Codex rules and AGENTS.md
+
+Codex profiles default `codex.ignoreRules` to `true`, which starts Codex with `--ignore-rules`. That flag skips user and project execpolicy `.rules` files; it does not disable `AGENTS.md`.
+
+Set the field to `false` only when the profile should load execpolicy `.rules`:
+
+```json
+{
+  "codex": {
+    "ignoreRules": false
+  }
+}
+```
+
+Codex loads `AGENTS.md` independently from its effective `CODEX_HOME` and the selected working-directory hierarchy. For example, a profile that inherits `~/.codex` can use `~/.codex/AGENTS.md` for user instructions and `<workspace>/AGENTS.md` for project instructions regardless of `ignoreRules`. Restart the profile after manually editing its bridge configuration.
+
 ## Data directories
 
 | Path | Content |
diff --git a/README.zh.md b/README.zh.md
index fae27156..f3f6d67e 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -218,6 +218,22 @@ bridge 会检查所选目录存在、是目录，并且不是 `/`、Home 根、
 
 旧版 `sandbox` 字段仍可读取。bridge 保存 profile 后，会把该设置迁移为 canonical `permissions`。
 
+## Codex rules 与 AGENTS.md
+
+Codex profile 的 `codex.ignoreRules` 默认为 `true`，bridge 会用 `--ignore-rules` 启动 Codex。这个参数只跳过用户和项目的 execpolicy `.rules` 文件，不会禁用 `AGENTS.md`。
+
+只有在当前 profile 需要加载 execpolicy `.rules` 时，才把该字段设为 `false`：
+
+```json
+{
+  "codex": {
+    "ignoreRules": false
+  }
+}
+```
+
+Codex 会根据实际使用的 `CODEX_HOME` 和所选工作目录层级独立加载 `AGENTS.md`。例如，继承 `~/.codex` 的 profile 可以用 `~/.codex/AGENTS.md` 提供用户级要求，用 `<workspace>/AGENTS.md` 提供项目级要求；这与 `ignoreRules` 无关。手动修改 bridge 配置后，请重启对应 profile。
+
 ## 数据目录
 
 | 路径 | 内容 |