LE0-Lin · Nov 4, 2026 · Nov 4, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Documentation
+
+- Refocus the English/Simplified/Traditional project overviews on instruction-change review and baseline-governed checks. Separate published v0.24.0 from unreleased Cursor analysis, add a concrete attachment-loss example, and move detailed policy/CLI/integration material into a reference page while retaining the visual demos. Point to the current pinned-corpus status: five scans and an expected Reaparr source rejection with no score, rather than presenting its historic A 100 as current. Runtime rules, artifacts and frozen evidence are unchanged.
+
 ### Added
 
 - Unreleased `scope compare` and Git-backed `scope diff` for the same declared Cursor file context: file lifecycle, trigger matches and aggregated exact-directive availability, with original line evidence and captured source hashes. Optional caller-owned flags gate recognized active losses and unknowns separately; active duplicate/renamed sources and remaining multi-file triggers retain availability. Includes four runnable synthetic examples and source-build CI guidance. This is bounded attachment/recognition analysis, not general semantic impact or runtime enforcement; normal scoring, policy schema, published packages and Action refs are unchanged.

diff --git a/README.md b/README.md
diff --git a/README.simplified.md b/README.simplified.md
@@ -2,12 +2,19 @@
 
 [English](README.md) | 简体中文 | [繁體中文](README.traditional.md)
 
-为 AI 编程助手的指令文件提供本地检查与 PR 回归门禁。
+在合并前发现 AI 编程助手指令中的已知退化。
 
 ![AgentConfigScore 演示](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif)
 
 AgentConfigScore 检查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini 等配置，并比较改动前后的基线，回答一个具体问题：**这次改动是否引入了已知规则能检测到的风险？**
 
+| 改动 | 审查依据 |
+|---|---|
+| 加入已知危险命令、凭据或失效路径 | 规则 ID、说明及可用的来源位置 |
+| 删除指令文件或反转精确指令 | 独立于总分的回归发现，即使分数相同也能报告 |
+| PR 放宽自己的阈值或增加豁免 | 正常比较仍使用基线策略；调用方的显式覆盖需单独审核 |
+| 接受已知例外 | 必须填写原因和到期日期，并保留审计记录 |
+
 它是确定性检查器，不是 AI 评委。**A 100 只表示没有命中生效的规则，不表示指令有用、语义完美或安全无误。** 中文文档也不意味着检测器已经能够理解任意中文指令。
 
 ## 快速开始
@@ -29,6 +36,33 @@ agent-config-score diff
 - [简体中文使用指南](docs/simplified/user-guide.md)：安装、基线、报告、退出码与排错。
 - [分数含义与限制](docs/simplified/limitations.md)：先了解什么能检出、什么仍可能漏掉。
 - [完整英文文档索引](docs/README.md)：进阶接口与研究资料。
+- [详细参考（英文）](docs/reference.md)：策略、CLI、Action 参数、SARIF 和审计格式。
+
+## 发布版与源码版
+
+| 版本 | 可用能力 |
+|---|---|
+| 已发布 v0.24.0 | 本地检查、基线回归门禁、可审计豁免、报告及可选删除保护审核 |
+| `main` 上尚未发布的源码 | Cursor 文件上下文加载预测、修改前后加载变化审核，以及变更日志中的修复 |
+
+PyPI 包和滚动 `v0` Action **不包含尚未发布的 Cursor 命令**。安装和选择 Action 引用前，请查看[发布说明（英文）](docs/releases/v0.24.0.md)和[变更日志（英文）](CHANGELOG.md)。
+
+## Cursor 加载变化审核——尚未发布的源码功能
+
+对于只声明后端文件 `src/api/service.py` 的任务，保持 `Never delete files without approval.` 正文不变，仅把 Cursor glob 从 `src/**` 改为 `src/web/**`，两侧普通评分仍是 **100**，预计自动加载却从活动变为不活动。
+
+在源码仓库目录中运行合成示例：
+
+```bash
+python -m pip install -e .
+agent-config-score scope compare \
+  examples/cursor-scope-impact/base examples/cursor-scope-impact/narrowed \
+  --target src/api/service.py --fail-on-lost-directives --fail-on-unknown
+```
+
+预期退出码为 **1**：已识别的活动指令失去自动加载来源，需要审核。报告给出元数据与指令行号；另一条活动规则中的相同指令，或任务中其他仍匹配的文件，可以保留可用性。手动／模型选择加载及不支持的输入保留为未知。
+
+比较两侧使用同一组声明的文件上下文，不观察实际 Agent 行为，也不证明语义等价。默认比较只给建议；两个标志显式启用调用方的审核门禁，不扩展现有基线评分策略格式。详见[四个对照（英文）](examples/cursor-scope-impact/README.md)和[Git 基线比较与 CI 示例（英文）](docs/cursor-scope-impact.md)。
 
 ## 为什么采用回归检查
 
@@ -105,8 +139,10 @@ jobs:
 
 运行时没有第三方依赖；本地扫描不调用 AI API，也不执行指令文件中的命令。包安装需要访问所选软件包索引；GitHub Actions 是单独的 CI 环境，报告访问权限由你的工作流控制。
 
-跨平台测试、维护的规则用例和安装验收证明程序符合指定的工程预期，**不证明它比直接问 AI 更准，也不证明它已经有真实用户价值**。独立对照评测尚未完成，已知语义漏报仍保留。详见[限制说明](docs/simplified/limitations.md)与[评测资料（英文）](benchmarks/README.md)。
+跨平台测试、维护的合成用例和安装验收验证指定的工程行为；已知语义漏报仍保留。当前固定版本的真实仓库回放中，5 个完成扫描，1 个按预期拒绝来源：Reaparr 的失效指令链接导致拒绝扫描，**没有分数**；历史 A 100 早于严格来源验证，不是当前结果。
+
+独立 AI 对照评测尚未完成。这些开发与兼容性结果不是现实准确率、AI 优势或用户采用证据。详见[限制说明](docs/simplified/limitations.md)与[当前评测记录（英文）](benchmarks/README.md)。
 
-本页是核心入门的中文概览，不是完整英文 README 的逐行翻译。使用指南和限制说明已提供中文；高级 Action 参数、规则语法细节、贡献及研究文档目前仍为英文。[翻译范围与维护说明](docs/translations.md)。命令、终端消息和 JSON 协议保持原样，English 仍是默认入口。
+本页与英文首页对齐核心功能；使用指南和限制说明也提供中文。详细参考、规则语法、贡献及研究文档目前仍为英文。[翻译范围与维护说明](docs/translations.md)。命令、终端消息和 JSON 协议保持原样，English 仍是默认入口。
 
 项目采用 [MIT 协议](LICENSE)。[发布与升级说明](docs/releases/v0.24.0.md)目前为英文。
diff --git a/README.traditional.md b/README.traditional.md
@@ -2,12 +2,19 @@
 
 [English](README.md) | [简体中文](README.simplified.md) | 繁體中文
 
-為 AI 程式開發助手的指令檔提供本機檢查與 PR 回歸檢查。
+在合併前發現 AI 程式開發助手指令中的已知退化。
 
 ![AgentConfigScore 示範](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif)
 
 AgentConfigScore 檢查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini 等設定，並與改動前的基準比較，回答一個具體問題：**這次改動是否引入了已知規則能偵測到的風險？**
 
+| 改動 | 審閱依據 |
+|---|---|
+| 加入已知危險命令、憑證或失效路徑 | 規則 ID、說明及可用的來源位置 |
+| 刪除指令檔或反轉精確指令 | 獨立於總分的回歸發現，即使分數相同也能回報 |
+| PR 放寬自己的門檻或增加排除設定 | 一般比較仍使用基準策略；呼叫端的明確覆寫須另行審閱 |
+| 接受已知例外 | 必須填寫原因和到期日期，並保留稽核紀錄 |
+
 它是確定性的檢查工具，不是 AI 評審。**A 100 只表示沒有命中生效的規則，不代表指令實用、語意完美或完全安全。** 提供中文文件也不表示檢查工具已經能理解任意中文指令。
 
 ## 快速開始
@@ -29,6 +36,33 @@ agent-config-score diff
 - [繁體中文使用指南](docs/traditional/user-guide.md)：安裝、基準、報告、結束代碼與疑難排解。
 - [分數意義與限制](docs/traditional/limitations.md)：先了解能偵測哪些問題，以及可能遺漏什麼。
 - [完整英文文件索引](docs/README.md)：進階介面與研究資料。
+- [詳細參考（英文）](docs/reference.md)：策略、CLI、Action 參數、SARIF 和稽核格式。
+
+## 發布版與原始碼版
+
+| 版本 | 可用能力 |
+|---|---|
+| 已發布 v0.24.0 | 本機檢查、基準回歸檢查、可稽核的例外、報告及選用刪除保護審閱 |
+| `main` 上尚未發布的原始碼 | Cursor 檔案上下文載入預測、修改前後載入變化審閱，以及變更紀錄中的修正 |
+
+PyPI 套件和滾動 `v0` Action **不包含尚未發布的 Cursor 命令**。安裝及選擇 Action 參照前，請查看[發布說明（英文）](docs/releases/v0.24.0.md)和[變更紀錄（英文）](CHANGELOG.md)。
+
+## Cursor 載入變化審閱——尚未發布的原始碼功能
+
+對於只宣告後端檔案 `src/api/service.py` 的任務，保持 `Never delete files without approval.` 正文不變，僅把 Cursor glob 從 `src/**` 改為 `src/web/**`，兩側一般評分仍是 **100**，預測自動載入卻從活動變為不活動。
+
+在原始碼儲存庫目錄中執行合成範例：
+
+```bash
+python -m pip install -e .
+agent-config-score scope compare \
+  examples/cursor-scope-impact/base examples/cursor-scope-impact/narrowed \
+  --target src/api/service.py --fail-on-lost-directives --fail-on-unknown
+```
+
+預期結束代碼為 **1**：已識別的活動指令失去自動載入來源，需要審閱。報告給出中繼資料與指令行號；另一條活動規則中的相同指令，或任務中其他仍符合的檔案，可以保留可用性。手動／模型選擇載入及不支援的輸入保留為未知。
+
+比較兩側使用同一組宣告的檔案上下文，不觀察實際 Agent 行為，也不證明語意等價。預設比較只給建議；兩個旗標明確啟用呼叫端的審閱檢查，不擴充現有基準評分策略格式。詳見[四個對照（英文）](examples/cursor-scope-impact/README.md)和[Git 基準比較與 CI 範例（英文）](docs/cursor-scope-impact.md)。
 
 ## 為什麼使用回歸檢查
 
@@ -105,8 +139,10 @@ jobs:
 
 執行時沒有第三方相依套件；本機掃描不呼叫 AI API，也不執行指令檔內的命令。安裝套件需存取選定的套件索引；GitHub Actions 是獨立的 CI 環境，報告存取權限由你的工作流程決定。
 
-跨平台測試、持續維護的規則案例與安裝驗收，證明程式符合指定的工程預期，**不代表它比直接詢問 AI 更準確，也不代表已經具備真實使用者價值**。獨立對照評測尚未完成，已知的語意漏報仍保留。請見[限制說明](docs/traditional/limitations.md)與[評測資料（英文）](benchmarks/README.md)。
+跨平台測試、持續維護的合成案例與安裝驗收驗證指定的工程行為；已知語意漏報仍保留。目前固定版本的真實儲存庫回放中，5 個完成掃描，1 個依預期拒絕來源：Reaparr 的失效指令連結導致拒絕掃描，**沒有分數**；歷史 A 100 早於嚴格來源驗證，不是目前結果。
+
+獨立 AI 對照評測尚未完成。這些開發與相容性結果不是現實準確率、AI 優勢或使用者採用證據。詳見[限制說明](docs/traditional/limitations.md)與[目前評測紀錄（英文）](benchmarks/README.md)。
 
-本頁是核心入門的中文概覽，不是完整英文 README 的逐行翻譯。使用指南與限制說明已提供中文；進階 Action 參數、規則語法細節、貢獻和研究文件目前仍為英文。[翻譯範圍與維護說明](docs/translations.md)。命令、終端機訊息和 JSON 協定維持原樣，English 仍為預設入口。
+本頁與英文首頁對齊核心功能；使用指南和限制說明也提供中文。詳細參考、規則語法、貢獻和研究文件目前仍為英文。[翻譯範圍與維護說明](docs/translations.md)。命令、終端機訊息和 JSON 協定維持原樣，English 仍為預設入口。
 
 專案採用 [MIT 授權](LICENSE)。[發布與升級說明](docs/releases/v0.24.0.md)目前為英文。
diff --git a/docs/README.md b/docs/README.md
@@ -8,6 +8,7 @@ read the result, and troubleshoot a failing gate.
 ## Using the tool
 
 - [User guide and exit codes](user-guide.md)
+- [CLI, policy, suppressions and integration reference](reference.md)
 - [Maintainer setup, actionable next steps and PR results](maintainer-workflow.md) (v0.24.0+)
 - [Unscored instruction-file best-practice checklist](best-practices.md)
 - [Visual tour](visual-tour.md)