Document agent secret vault installation

README.md

@@ -1,19 +1,43 @@
 # Agent Secret Vault
 
-這個 repo 專門存放本地 AI agent 開發會用到的機密管理機制。
+本 repo 專門管理本地 AI agent / worker 需要的機密資料。
 
-核心設計：
-- 使用 `ansible-vault` 作為加密格式
-- 加密檔可進 git
-- vault password file 只放在本機
-- 多個 agent 透過統一腳本存取 secrets
+## 核心設計
 
-## 內容
-- `scripts/vault.sh`：初始化、檢視、編輯、加密、解密、rekey
-- `docs/secret-vault.md`：使用說明與設計原則
-- `secrets/vault.yml`：加密後 secrets 檔
+- 使用 `ansible-vault` 加密 `secrets/vault.yml`
+- 加密後的 `secrets/vault.yml` 可以進 git
+- vault password file 放在本機：`~/.config/vault-pass.txt`
+- 新機器可透過 repo 內的密碼保護壓縮檔 `secrets/vault-pass.txt.zip` 安裝 password file
+- 多個 agent 透過統一腳本讀取 secrets，不各自發明 credential 管理方式
 
-## 目標
-- 讓 Hermes / OpenClaw / cron worker / 其他本地 agent 共用同一套 secret storage contract
-- 不把明文 secret 留在 repo
-- 不讓每個 agent 各自發明一套 credential 管理方式
+## 主要文件
+
+- 人類使用指南：[`docs/human-guide.md`](docs/human-guide.md)
+- Agent 安裝 Runbook：[`docs/agent-install-runbook.md`](docs/agent-install-runbook.md)
+- Agent 整合補充：[`docs/agent-integration.md`](docs/agent-integration.md)
+- Vault 基礎說明：[`docs/secret-vault.md`](docs/secret-vault.md)
+
+## 常用指令
+
+```bash
+# 安裝 vault password file（會要求輸入壓縮檔密碼）
+./scripts/install-vault-pass.sh
+
+# 維護者建立密碼保護壓縮檔
+./scripts/create-vault-pass-archive.sh
+
+# 檢視 vault
+./scripts/vault.sh view
+
+# 編輯 vault
+./scripts/vault.sh edit
+
+# 讀單一 secret
+./scripts/get-secret.sh openclaw_alice.http_nodes.gitea.password
+```
+
+## 安全原則
+
+- 不要把 `~/.config/vault-pass.txt` commit 到 git
+- 不要把解密後完整 YAML 貼到 chat/log
+- Agent 回報時只回報 key path、commit hash、驗證方式，不回報 secret value