Clarify zip password file diagnostics

docs/agent-install-runbook.md

@@ -85,6 +85,8 @@ INSTALL_VAULT_PASS_METHOD="archive"
 VAULT_PASS_ZIP_PASSWORD_FILE="/secure/path/zip-password.txt"
 ```
 
+注意：`VAULT_PASS_ZIP_PASSWORD_FILE` 必須指向「只包含 zip 密碼的一行純文字檔」。不要把它指到 `secrets/vault-pass.txt.zip`（zip 壓縮檔本身）、`~/.config/vault-pass.txt`（Ansible Vault password file）、私鑰、或任何二進位檔。若 installer 報告檔案含 NUL bytes，通常就是路徑指錯了；請改成正確的 zip 密碼文字檔，或改用 `VAULT_PASS_ZIP_PASSWORD` / `url` / `manual` 方法。
+
 若需要使用另一個 env 檔：
 
 ```bash
@@ -178,6 +180,8 @@ VAULT_PASS_URL="https://example.com/one-time/vault-pass.txt" \
 ./scripts/install-vault-pass.sh
 
 # 方式 B：從密碼保護 zip 解壓，zip 密碼放在本機安全檔案
+# /secure/path/zip-password.txt 必須是純文字，內容只有 zip 密碼本身；
+# 不可指到 secrets/vault-pass.txt.zip 或 ~/.config/vault-pass.txt。
 INSTALL_VAULT_PASS_METHOD=archive \
 VAULT_PASS_ZIP_PASSWORD_FILE=/secure/path/zip-password.txt \
 ./scripts/install-vault-pass.sh

install.env.example

@@ -24,7 +24,10 @@ VAULT_PASS_URL=""
 
 # Method: archive
 # Password-protected zip path defaults to secrets/vault-pass.txt.zip.
-# Put zip password in a local file when possible. Safer than putting it inline.
+# Put the ZIP ARCHIVE PASSWORD in a local plaintext file when possible.
+# This must be a small text file containing only the zip password.
+# Do NOT point this to secrets/vault-pass.txt.zip, ~/.config/vault-pass.txt,
+# a private key, or any binary/archive file.
 VAULT_PASS_ZIP_PASSWORD_FILE=""
 
 # Method: archive fallback

scripts/install-vault-pass.sh

@@ -196,7 +196,26 @@ read_zip_password_file() {
   original_size="$(wc -c < "$VAULT_PASS_ZIP_PASSWORD_FILE" | tr -d '[:space:]')"
   without_nul_size="$(LC_ALL=C tr -d '\000' < "$VAULT_PASS_ZIP_PASSWORD_FILE" | wc -c | tr -d '[:space:]')"
   if [ "$original_size" != "$without_nul_size" ]; then
-    echo "VAULT_PASS_ZIP_PASSWORD_FILE appears to contain NUL bytes; provide a text password file instead." >&2
+    file_desc="$(file -b "$VAULT_PASS_ZIP_PASSWORD_FILE" 2>/dev/null || echo "unknown file type")"
+    cat >&2 <<ERR
+VAULT_PASS_ZIP_PASSWORD_FILE appears to contain NUL bytes; provide a text password file instead.
+
+Configured password-file path:
+  $VAULT_PASS_ZIP_PASSWORD_FILE
+Detected file type:
+  $file_desc
+
+This variable must point to a small plaintext file containing ONLY the zip archive password.
+It must NOT point to:
+  - secrets/vault-pass.txt.zip (the archive itself)
+  - ~/.config/vault-pass.txt (the Ansible Vault password file)
+  - any binary/key/archive file
+
+Fix one of these ways:
+  1. Create a plaintext zip-password file and set VAULT_PASS_ZIP_PASSWORD_FILE to that path.
+  2. Or set VAULT_PASS_ZIP_PASSWORD directly in a private local shell/env.
+  3. Or use INSTALL_VAULT_PASS_METHOD=url/manual/create instead of archive.
+ERR
     exit 4
   fi