Document agent secret vault installation

docs/agent-install-runbook.md

@@ -0,0 +1,163 @@
+# Agent 安裝 Runbook：agent-secret-vault
+
+這份文件給 AI agent / cron worker / automation 使用。目標：把 `agent-secret-vault` 安裝好、缺檔時建立 placeholder、並能安全讀取 secrets。
+
+## 安全規則
+
+- 不要把 secret value、vault password、token、private key 印到 chat / log / 工單 comment。
+- 不要 dump 整份解密後的 `secrets/vault.yml`。
+- 只讀取任務所需的單一欄位。
+- 所有暫存解密檔用完立即刪除。
+
+## 目標路徑
+
+- Repo：`~/projects/agent-secret-vault`
+- Vault 檔：`~/projects/agent-secret-vault/secrets/vault.yml`
+- Vault password file：`~/.config/vault-pass.txt`
+- 可覆寫環境變數：`VAULT_PASS_FILE=/custom/path`
+
+## 1. 安裝系統依賴
+
+```bash
+sudo apt update
+sudo apt install -y git ansible unzip
+```
+
+驗證：
+
+```bash
+command -v git
+command -v ansible-vault
+command -v unzip
+```
+
+## 2. Clone repo
+
+```bash
+mkdir -p ~/projects
+cd ~/projects
+if [ ! -d agent-secret-vault/.git ]; then
+  git clone ssh://git@gitea.cowbay.org:2203/hermes/agent-secret-vault.git
+fi
+cd agent-secret-vault
+```
+
+若 clone 失敗，建立 placeholder 讓後續步驟可明確回報缺什麼：
+
+```bash
+mkdir -p ~/projects/agent-secret-vault/{scripts,secrets,docs}
+cat > ~/projects/agent-secret-vault/README.PLACEHOLDER.md <<'PLACEHOLDER'
+# Placeholder
+
+agent-secret-vault repo 尚未成功 clone。
+需要 Gitea SSH 權限：ssh://git@gitea.cowbay.org:2203/hermes/agent-secret-vault.git
+PLACEHOLDER
+```
+
+然後回報人類：需要把此 agent / 機器的 SSH public key 加到 Gitea 或 deploy key。
+
+## 3. 安裝 vault password file
+
+標準位置：
+
+```text
+~/.config/vault-pass.txt
+```
+
+安裝來源是 repo 內的密碼保護壓縮檔：
+
+```text
+secrets/vault-pass.txt.zip
+```
+
+執行：
+
+```bash
+cd ~/projects/agent-secret-vault
+./scripts/install-vault-pass.sh
+```
+
+安裝過程會要求使用者手動輸入壓縮檔密碼；解壓成功後會寫入：
+
+```text
+~/.config/vault-pass.txt
+```
+
+權限應為 `600`。
+
+### 若壓縮檔不存在
+
+建立 placeholder，不要自行編造密碼：
+
+```bash
+mkdir -p ~/projects/agent-secret-vault/secrets
+cat > ~/projects/agent-secret-vault/secrets/vault-pass.txt.zip.PLACEHOLDER <<'PLACEHOLDER'
+Missing file: secrets/vault-pass.txt.zip
+Purpose: password-protected archive containing vault-pass.txt
+Action: ask human maintainer to provide this archive or commit it to the private repo.
+PLACEHOLDER
+```
+
+然後回報人類：缺 `secrets/vault-pass.txt.zip`，需要提供。
+
+### 若要用非預設路徑
+
+```bash
+export VAULT_PASS_FILE=/path/to/vault-pass.txt
+./scripts/install-vault-pass.sh /path/to/vault-pass.txt.zip
+```
+
+## 4. 驗證安裝
+
+```bash
+cd ~/projects/agent-secret-vault
+ansible-vault view secrets/vault.yml --vault-password-file ~/.config/vault-pass.txt >/dev/null
+```
+
+成功：exit code 0。失敗時只回報錯誤摘要，不要輸出密碼或 vault 內容。
+
+## 5. 讀取單一 secret
+
+```bash
+cd ~/projects/agent-secret-vault
+./scripts/get-secret.sh <dot.path>
+```
+
+範例：
+
+```bash
+./scripts/get-secret.sh gitea.api_token
+./scripts/get-secret.sh openclaw_alice.http_nodes.gitea.password
+```
+
+把輸出直接交給需要 secret 的動作使用；不要貼到 chat / log。
+
+## 6. Worker 需要 env 時
+
+```bash
+cd ~/projects/agent-secret-vault
+umask 077
+./scripts/render-env.sh gitea > /tmp/gitea.env
+set -a
+. /tmp/gitea.env
+set +a
+rm -f /tmp/gitea.env
+```
+
+使用完如果擔心環境被 dump，執行 `unset` 清掉相關變數。
+
+## 7. 更新 secret 的 agent 流程
+
+只有在人類明確要求更新 secrets 時才做：
+
+```bash
+cd ~/projects/agent-secret-vault
+git pull --ff-only
+./scripts/vault.sh edit
+ansible-vault view secrets/vault.yml --vault-password-file ~/.config/vault-pass.txt >/dev/null
+git add secrets/vault.yml
+git commit -m "Update secret <key-name>"
+git push
+```
+
+回報只包含 key 名稱、commit hash、驗證方式；不要包含 secret value。