diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7e30ea7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# SSH Configuration
+
+透過 iCloud Drive 同步 SSH 設定與公鑰，在多台 Mac 之間共享一致的 SSH 環境。
+
+## 架構
+
+```
+iCloud/.ssh/          ← 本 repo（實際檔案）
+├── config            # 主設定，Include config.d/*
+├── config.d/         # 依主機/用途分拆的設定檔
+├── *.pub             # 公鑰
+├── *.pem             # AWS 金鑰（gitignored）
+├── id_rsa, id_ecdsa  # 私鑰（gitignored）
+└── *.sh              # 管理腳本
+
+~/.ssh/               ← symlinks 指向 iCloud
+├── config → iCloud/.ssh/config
+├── config.d → iCloud/.ssh/config.d
+├── id_rsa → iCloud/.ssh/id_rsa
+├── id_ecdsa → iCloud/.ssh/id_ecdsa
+└── sockets/          # ControlMaster 連線 socket
+```
+
+## 設定新機器
+
+```bash
+# 建立 symlinks（從 iCloud 連結到 ~/.ssh）
+./create_ssh_symlinks.sh
+
+# 如需載入 AWS PEM 金鑰至 ssh-agent
+./ssh_key_management.sh
+```
+
+## 移除 symlinks
+
+```bash
+./delete_ssh_files.sh
+```
+
+## config.d 結構
+
+主設定透過 `Include config.d/*` 載入分拆設定，每個檔案對應不同主機群組：
+
+| 檔案 | 用途 |
+|------|------|
+| `acetech` | Acetech 相關主機 |
+| `digitalocean` | DigitalOcean 主機 |
+| `jason_hsieh` | jason_hsieh 相關主機 |
+| `ma` | ma 相關主機 |
+| `timmy` | 個人主機 |
+
+## 全域設定重點
+
+- **ControlMaster**：自動多工連線，socket 保留 5 分鐘
+- **KeepAlive**：每 60 秒探測，5 次無回應斷線
+- **IdentityAgent**：使用 [Secretive](https://github.com/maxgoedjen/secretive) 管理金鑰
+- **ExitOnForwardFailure**：轉發失敗立即退出
+
+## 安全注意事項
+
+- 私鑰和 PEM 檔案已在 `.gitignore` 中排除，**不會被提交**
+- `known_hosts` 為動態產生，不納入版控