From 73bdbd7a207714cc2748352833e4248125b80601 Mon Sep 17 00:00:00 2001
From: hermes <hermes@ntu.edu.rs>
Date: Thu, 14 May 2026 20:31:58 +0800
Subject: [PATCH] Clarify env-first install docs

---
 README.md                     | 28 +++++++++++++++++++++++-----
 docs/agent-install-runbook.md |  7 ++++---
 docs/human-guide.md           |  8 ++++++--
 3 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index ae170c7..6d87b21 100644
--- a/README.md
+++ b/README.md
@@ -26,14 +26,32 @@ Repo 內提供：
 
 `install.env` 不應填入真實 secrets 後再 commit；若要保存本機私密設定，使用 `install.local.env` 並透過 `INSTALL_ENV_FILE=install.local.env` 指定。
 
-## 全自動 agent 安裝
+## 安裝流程（先設定 env）
+
+安裝前請先設定 `install.env`，再檢查 env 是否足夠，最後才正式安裝：
+
+```bash
+cp -n install.env.example install.env
+editor install.env
+./scripts/install-vault-pass.sh --check-env
+./scripts/install-vault-pass.sh
+```
+
+`install.env` 範例：
 
 ```bash
 # 例：用一次性 URL 安裝 vault-pass.txt
-INSTALL_VAULT_PASS_METHOD=url \
-VAULT_PASS_URL="https://example.com/one-time/vault-pass.txt" \
-./scripts/install-vault-pass.sh --check-env
-./scripts/install-vault-pass.sh
+INSTALL_VAULT_PASS_METHOD="url"
+VAULT_PASS_URL="https://example.com/one-time/vault-pass.txt"
+```
+
+## 全自動 agent 安裝
+
+Agent / CI 也應優先設定 `install.env` 或 `INSTALL_ENV_FILE`，不要直接進互動選單：
+
+```bash
+INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh --check-env
+INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh
 ```
 
 ## 常用指令
diff --git a/docs/agent-install-runbook.md b/docs/agent-install-runbook.md
index 97c701d..37c12ba 100644
--- a/docs/agent-install-runbook.md
+++ b/docs/agent-install-runbook.md
@@ -65,7 +65,7 @@ install.env.example  # 範本
 install.env          # 安裝用 placeholder
 ```
 
-安裝前先設定 `install.env`：
+安裝前必須先設定 `install.env`（或指定 `INSTALL_ENV_FILE`），不要跳過這一步：
 
 ```bash
 cd ~/projects/agent-secret-vault
@@ -99,7 +99,7 @@ INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh
 ./scripts/install-vault-pass.sh --check-env
 ```
 
-若輸出顯示 env 不足，installer 會在正式安裝時進入互動提示或列出缺少欄位。
+若輸出顯示 env 不足，先補齊 env；只有人類在本機 terminal 操作時才允許進入互動提示。AI agent / CI 不應直接進互動流程。
 
 ## 3. 安裝 vault password file
 
@@ -109,10 +109,11 @@ INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh
 ~/.config/vault-pass.txt
 ```
 
-執行 installer：
+執行 installer 前再次確認 env，然後安裝：
 
 ```bash
 cd ~/projects/agent-secret-vault
+./scripts/install-vault-pass.sh --check-env
 ./scripts/install-vault-pass.sh
 ```
 
diff --git a/docs/human-guide.md b/docs/human-guide.md
index d6e1fc1..128f9a3 100644
--- a/docs/human-guide.md
+++ b/docs/human-guide.md
@@ -25,13 +25,17 @@ git clone ssh://git@gitea.cowbay.org:2203/hermes/agent-secret-vault.git
 cd agent-secret-vault
 ```
 
-接著安裝 vault password file：
+接著先設定 installer env，再安裝 vault password file：
 
 ```bash
+cp -n install.env.example install.env
+editor install.env
 ./scripts/install-vault-pass.sh --check-env
 ./scripts/install-vault-pass.sh
 ```
 
+重點：先填 `install.env`。若 `--check-env` 顯示資訊不足，先補齊 `INSTALL_VAULT_PASS_METHOD` 與對應欄位，不要直接進互動流程。
+
 installer 會先檢查：
 
 ```text
@@ -69,7 +73,7 @@ git push
 
 ## 安裝時設定 vault-pass
 
-安裝流程建議先填 repo 內的 env 檔：
+安裝流程要求先填 repo 內的 env 檔：
 
 ```bash
 cd ~/projects/agent-secret-vault