docs: formalize Vault configuration into a complete step-by-step Runbook

README.md

@@ -56,10 +56,12 @@ If you are running the GitHub Actions workflow (`deploy-env-migration.yaml`), pl
 - **Vault Role**: The required role name is `github-actions-site-migration-toolkit`.
 - **Role Binding**: Ensure the JWT `bound_claims` match the new repository name (`repo:ai-workspace-infra/site-migration-toolkit:ref:refs/heads/main` or similar).
 
-**Vault Role Provisioning Script**:
-To avoid CLI parsing issues, use the following JSON payload format to create or update the role. This also binds the correct policy to the role.
+### 🔐 Vault Provisioning & Verification Runbook
 
-1. **Create the Vault Policy** (Grants read access to required secrets):
+To avoid CLI parsing issues and ensure the CI pipeline has the exact permissions it needs, follow this step-by-step runbook to provision the Vault environment.
+
+#### Step 1: Create the Vault Policy
+Create a policy that explicitly grants read access to the required secrets:
 ```bash
 vault policy write github-actions-site-migration-toolkit - <<EOF
 path "kv/data/CICD" {
@@ -71,7 +73,18 @@ path "kv/data/openclaw" {
 EOF
 ```
 
-2. **Create the Vault JWT Role** (Binds the repository claim to the policy):
+#### Step 2: Verify Policy Creation
+Ensure the policy was successfully written to the Vault server:
+```bash
+vault policy list
+# Expected output should include: github-actions-site-migration-toolkit
+
+# (Optional) Read the policy to verify its rules:
+vault policy read github-actions-site-migration-toolkit
+```
+
+#### Step 3: Create the Vault JWT Role
+Bind the GitHub repository identity directly to the newly created policy:
 ```bash
 vault write auth/jwt/role/github-actions-site-migration-toolkit - <<EOF
 {
@@ -92,10 +105,10 @@ EOF
 
 - **`400 Bad Request` (role could not be found)**: 
   - *Cause*: The `VAULT_ROLE` defined in `.github/workflows/deploy-env-migration.yaml` does not match any existing role in your Vault server.
-  - *Fix*: Create the role using the script above, ensuring the name is exactly `github-actions-site-migration-toolkit`.
+  - *Fix*: Create the role using Step 3 above. Ensure the name is exactly `github-actions-site-migration-toolkit`.
 - **`403 Forbidden` (during Get Vault Secrets)**: 
   - *Cause*: The JWT authenticated successfully, but the token lacks read permissions for the requested KV paths (e.g., `kv/data/CICD`). This happens if the assigned `policies` in your Role do not exist or lack the `read` capability.
-  - *Fix*: Run `vault policy list` to verify. If missing, create the `github-actions-site-migration-toolkit` policy as shown above and bind it to the role.
+  - *Fix*: Run `vault policy list` to verify. If missing, follow Step 1 and 2 to create the policy, then re-run Step 3 to ensure the Role binds to it.
 
 ---
 
@@ -155,10 +168,12 @@ EOF
 - **Vault 角色 (Role)**: 所需的角色名为 `github-actions-site-migration-toolkit`。
 - **角色绑定 (Role Binding)**: 请确保 JWT 的 `bound_claims` 匹配新的代码库名称（例如 `repo:ai-workspace-infra/site-migration-toolkit:ref:refs/heads/main`）。
 
-**Vault 角色配置脚本**:
-为了避免 Vault CLI 在解析命令行 Map 类型时出现报错，推荐使用以下 JSON payload 的格式直接创建或更新角色，并同时配齐必需的 Policy。
+### 🔐 Vault 鉴权配置与验证手册 (Runbook)
 
-1. **创建 Vault Policy** (授予访问必需敏感信息的读权限)：
+为了避免 Vault CLI 在解析命令行 Map 类型时出现报错，并确保流水线拥有精确且正确的权限，请按照以下标准手册 (Runbook) 逐步配置 Vault 环境。
+
+#### 步骤 1：创建 Vault Policy
+创建一个专门的 Policy，显式授予访问必需敏感信息的读权限：
 ```bash
 vault policy write github-actions-site-migration-toolkit - <<EOF
 path "kv/data/CICD" {
@@ -170,7 +185,18 @@ path "kv/data/openclaw" {
 EOF
 ```
 
-2. **创建 Vault JWT Role** (将代码库的身份标识与权限 Policy 绑定)：
+#### 步骤 2：验证 Policy 是否生效
+确认该 Policy 已经被成功写入 Vault 服务器：
+```bash
+vault policy list
+# 正常预期下，输出结果中必须包含: github-actions-site-migration-toolkit
+
+# (可选) 你可以进一步读取该 Policy 的内容以确认权限细节:
+vault policy read github-actions-site-migration-toolkit
+```
+
+#### 步骤 3：创建 Vault JWT Role
+将 Github 代码库的身份标识（JWT Claim）与刚刚创建的权限 Policy 进行强绑定：
 ```bash
 vault write auth/jwt/role/github-actions-site-migration-toolkit - <<EOF
 {
@@ -191,7 +217,7 @@ EOF
 
 - **报错 `400 Bad Request` (role could not be found)**: 
   - *原因*: Github Actions 流水线中定义的 `VAULT_ROLE` 在你的 Vault 服务器上不存在。
-  - *解法*: 请使用上方脚本创建名为 `github-actions-site-migration-toolkit` 的角色。
+  - *解法*: 请使用上方【步骤 3】的脚本创建名为 `github-actions-site-migration-toolkit` 的角色。
 - **报错 `403 Forbidden` (发生在 Get Vault Secrets 阶段)**: 
   - *原因*: JWT 登录成功，但是签发的 Token 没有对应路径（如 `kv/data/CICD`）的读权限。这通常是因为绑定在 Role 上的 `policies` 不存在，或者里面的权限配置不包含 `read`。
-  - *解法*: 在服务端运行 `vault policy list` 检查。如果缺少对应策略，请执行上方的【创建 Vault Policy】步骤补充权限，并确保 Role 正确绑定了该 Policy。
+  - *解法*: 在服务端运行 `vault policy list` 检查。如果缺少对应策略，请完整执行上方的【步骤 1 到 步骤 3】，补充权限并确保 Role 正确绑定了该 Policy。