LE0-Lin · Nov 5, 2026 · Nov 5, 2026
diff --git a/README.md b/README.md
@@ -26,6 +26,8 @@ decisions. No model API or runtime dependencies are needed.
   <img src="https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif" alt="A known instruction regression is reported and blocked in CI" width="100%" />
 </p>
 
+[Setup demo](#quick-start) · [Workflow diagram](#what-it-helps-you-review) · [Score history demo](#score-history-demo) · [Visual gallery](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/visual-tour.md)
+
 **A 100 means no active deterministic rule matched.** It does not certify
 instruction usefulness, semantic correctness or safety.
 [Read the score contract and limitations.](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/limitations.md)
@@ -43,6 +45,8 @@ Existing repositories can adopt the gate without first reaching 100.
 `init` enables new-error blocking and no score decrease; a passing comparison
 means no regression under the selected rules and policy.
 
+![Workflow diagram showing repository setup, PR checks against a baseline, and retained reports](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-workflow.svg)
+
 ## Quick start
 
 Run inside your repository with a supported instruction file:
@@ -65,6 +69,10 @@ without fetching; use `agent-config-score diff origin/main` when you want an
 explicit ref. The [user guide](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/user-guide.md)
 covers setup, exits and troubleshooting.
 
+![Terminal demo showing package installation, init, and doctor](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-setup.gif)
+
+*The v0.18 demo illustrates the install, initialize, and verify steps. Use the commands above for the current setup.*
+
 ## Release and source status
 
 | Version | Available capability |
@@ -181,18 +189,12 @@ and [privacy-minimized feedback drafts](https://github.com/LE0-Lin/AgentConfigSc
 | Keep score history | [History workflow](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/score-history.md) |
 | Browse all topics | [Documentation index](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/README.md) |
 
-## Visual tour
-
-<details>
-<summary>Setup, workflow and history demos</summary>
-
-![Setup](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-setup.gif)
-
-![Workflow](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-workflow.svg)
+## Score history demo
 
-![History](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-history.gif)
+![Illustrative score history showing the date, score, change, and commit for each snapshot](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-history.gif)
 
-</details>
+This example shows how recorded scores and commit IDs appear together in
+`agent-config-score history`. [Set up the history workflow.](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/score-history.md)
 
 The [visual tour](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/visual-tour.md)
 explains each demo. Choose [简体中文](https://github.com/LE0-Lin/AgentConfigScore/blob/main/README.simplified.md)

diff --git a/README.simplified.md b/README.simplified.md
@@ -6,6 +6,8 @@
 
 ![AgentConfigScore 演示](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif)
 
+[安装演示](#快速开始) · [分数历史演示](#分数历史演示) · [完整演示图集](docs/visual-tour.md)
+
 AgentConfigScore 检查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini 等配置，并比较改动前后的基线，回答一个具体问题：**这次改动是否引入了已知规则能检测到的风险？**
 
 | 改动 | 审查依据 |
@@ -15,6 +17,8 @@ AgentConfigScore 检查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini
 | PR 放宽自己的阈值或增加豁免 | 正常比较仍使用基线策略；调用方的显式覆盖需单独审核 |
 | 接受已知例外 | 必须填写原因和到期日期，并保留审计记录 |
 
+![工作流程图，展示仓库初始化、基线回归检查与报告留存](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-workflow.svg)
+
 它是确定性检查器，不是 AI 评委。**A 100 只表示没有命中生效的规则，不表示指令有用、语义完美或安全无误。** 中文文档也不意味着检测器已经能够理解任意中文指令。
 
 ## 快速开始
@@ -33,6 +37,10 @@ agent-config-score diff
 
 `acs` 是短命令别名。v0.23.0+ 还可以使用 `python -m agent_config_score`，避免终端 PATH 没有找到命令的问题。
 
+![终端演示，展示安装、初始化与 doctor 检查](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-setup.gif)
+
+*动图以 v0.18 为例展示接入步骤。当前版本请按上方命令安装。*
+
 - [简体中文使用指南](docs/simplified/user-guide.md)：安装、基线、报告、退出码与排错。
 - [分数含义与限制](docs/simplified/limitations.md)：先了解什么能检出、什么仍可能漏掉。
 - [完整英文文档索引](docs/README.md)：进阶接口与研究资料。
@@ -145,4 +153,10 @@ jobs:
 
 本页与英文首页对齐核心功能；使用指南和限制说明也提供中文。详细参考、规则语法、贡献及研究文档目前仍为英文。[翻译范围与维护说明](docs/translations.md)。命令、终端消息和 JSON 协议保持原样，English 仍是默认入口。
 
+## 分数历史演示
+
+![分数历史示例，逐条显示日期、分数、变化与提交](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-history.gif)
+
+示例展示 `agent-config-score history` 如何把每次评分和对应提交放在一起。[历史工作流（英文）](docs/score-history.md)
+
 项目采用 [MIT 协议](LICENSE)。[发布与升级说明](docs/releases/v0.24.0.md)目前为英文。
diff --git a/README.traditional.md b/README.traditional.md
@@ -6,6 +6,8 @@
 
 ![AgentConfigScore 示範](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif)
 
+[安裝示範](#快速開始) · [分數歷史示範](#分數歷史示範) · [完整示範圖集](docs/visual-tour.md)
+
 AgentConfigScore 檢查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini 等設定，並與改動前的基準比較，回答一個具體問題：**這次改動是否引入了已知規則能偵測到的風險？**
 
 | 改動 | 審閱依據 |
@@ -15,6 +17,8 @@ AgentConfigScore 檢查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini
 | PR 放寬自己的門檻或增加排除設定 | 一般比較仍使用基準策略；呼叫端的明確覆寫須另行審閱 |
 | 接受已知例外 | 必須填寫原因和到期日期，並保留稽核紀錄 |
 
+![工作流程圖，展示儲存庫初始化、基準回歸檢查與報告保存](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-workflow.svg)
+
 它是確定性的檢查工具，不是 AI 評審。**A 100 只表示沒有命中生效的規則，不代表指令實用、語意完美或完全安全。** 提供中文文件也不表示檢查工具已經能理解任意中文指令。
 
 ## 快速開始
@@ -33,6 +37,10 @@ agent-config-score diff
 
 `acs` 是較短的命令別名。v0.23.0+ 也能使用 `python -m agent_config_score`，不必依賴終端機 PATH 找到主命令。
 
+![終端機示範，展示安裝、初始化與 doctor 檢查](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-setup.gif)
+
+*動畫以 v0.18 為例展示整合步驟。目前版本請依照上方命令安裝。*
+
 - [繁體中文使用指南](docs/traditional/user-guide.md)：安裝、基準、報告、結束代碼與疑難排解。
 - [分數意義與限制](docs/traditional/limitations.md)：先了解能偵測哪些問題，以及可能遺漏什麼。
 - [完整英文文件索引](docs/README.md)：進階介面與研究資料。
@@ -145,4 +153,10 @@ jobs:
 
 本頁與英文首頁對齊核心功能；使用指南和限制說明也提供中文。詳細參考、規則語法、貢獻和研究文件目前仍為英文。[翻譯範圍與維護說明](docs/translations.md)。命令、終端機訊息和 JSON 協定維持原樣，English 仍為預設入口。
 
+## 分數歷史示範
+
+![分數歷史範例，逐筆顯示日期、分數、變化與提交](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-history.gif)
+
+範例展示 `agent-config-score history` 如何將每次評分與對應提交放在一起。[歷史工作流程（英文）](docs/score-history.md)
+
 專案採用 [MIT 授權](LICENSE)。[發布與升級說明](docs/releases/v0.24.0.md)目前為英文。