diff --git a/docs/flowchart.md b/docs/flowchart.md
new file mode 100644
index 0000000..91156e4
--- /dev/null
+++ b/docs/flowchart.md
@@ -0,0 +1,78 @@
+# Agent Secret Vault 流程圖
+
+## 安裝流程
+
+```mermaid
+flowchart TD
+    A[開始] --> B[git clone repo]
+    B --> C{vault-pass.txt 存在?}
+    C -->|是| D[驗證 vault 可解密]
+    C -->|否| E[選擇安裝方式]
+    
+    E --> E1[建立新密碼]
+    E --> E2[手動輸入]
+    E --> E3[從 URL 下載]
+    E --> E4[從 zip 解壓]
+    
+    E1 --> F[產生 vault-pass.txt]
+    E2 --> F
+    E3 --> F
+    E4 --> F
+    
+    F --> D
+    D -->|成功| G[安裝完成]
+    D -->|失敗| H[檢查 vault-pass.txt 內容]
+    H --> F
+```
+
+## 日常使用流程
+
+```mermaid
+flowchart TD
+    A[開始] --> B[cd agent-secret-vault]
+    B --> C{要做什么?}
+    
+    C -->|查看 vault| D[./scripts/vault.sh view]
+    C -->|讀取單一 secret| E[./scripts/get-secret.sh key.path]
+    C -->|編輯 vault| F[./scripts/vault.sh edit]
+    C -->|更新 secret| G[git pull → edit → git push]
+    
+    F --> H[編輯完成]
+    H --> I[git add secrets/vault.yml]
+    I --> J[git commit]
+    J --> K[git push]
+```
+
+## 加密格式變更流程
+
+```mermaid
+flowchart TD
+    A[發現 vault.yml 是 age 加密] --> B[scripts 用 ansible-vault 無法解密]
+    B --> C[用 age 私鑰解密 vault.yml]
+    C --> D[暫存明文到 /tmp]
+    D --> E[用 ansible-vault 重新加密]
+    E --> F[驗證 vault.sh view 正常]
+    F --> G[驗證 get-secret.sh 正常]
+    G --> H[git commit + push]
+```
+
+## Secret 結構
+
+```mermaid
+flowchart LR
+    Vault[vault.yml] --> HTTP[http_nodes]
+    Vault --> KUMON[kumon_com_tw]
+    
+    HTTP --> BYNARA[bynara]
+    HTTP --> GOOGLE[google_ai_studio]
+    
+    BYNARA --> BY_KEY[api_key]
+    BYNARA --> BY_URL[base_url]
+    
+    KUMON --> R2[cloudflare_r2]
+    R2 --> ACC[account_id]
+    R2 --> ZONE[zone_id]
+    R2 --> AK[access_key_id]
+    R2 --> EP[endpoint]
+    R2 --> SK[secret_access_key]
+```