diff --git a/docs/auth/desktop-integration.md b/docs/auth/desktop-integration.md
new file mode 100644
index 00000000..a6a7faac
--- /dev/null
+++ b/docs/auth/desktop-integration.md
@@ -0,0 +1,76 @@
+# Desktop 登录集成
+
+## 登录流程
+
+```
+Desktop 点击登录
+    ↓
+启动本地 HTTP 服务器 (随机端口，如 54321)
+    ↓
+打开浏览器 → http://localhost:3000/api/desktop/session?port=54321&platform=web
+    ↓
+Web 重定向 → /login?next=...
+    ↓
+用户登录，调用 /api/v1/auth/login (代理到 api-dev.copilothub.ai)
+    ↓
+登录成功，回调 → http://127.0.0.1:54321/callback?sid=xxx&user=xxx
+    ↓
+Desktop 保存到 ~/.super-multica/auth.json
+```
+
+## 前端逻辑
+
+### Web 端
+
+- 端口：**3000**
+- 登录 API：`/api/v1/auth/login`（通过 Next.js rewrites 代理到后端）
+- 登录成功后回调：`http://127.0.0.1:{port}/callback?sid=xxx&user=xxx`
+
+### Desktop 端
+
+- 点击登录 → 启动本地服务器 → 打开浏览器
+- 收到回调 → 保存到本地文件
+
+## 存储
+
+```
+~/.super-multica/auth.json
+```
+
+```json
+{
+  "sid": "xxx",
+  "user": {
+    "uid": "xxx",
+    "name": "xxx",
+    "email": "xxx"
+  }
+}
+```
+
+## 退出登录
+
+**后端只需要返回错误，前端会自动处理退出。**
+
+前端收到认证错误后：
+1. 调用 `auth:clear` 清除本地数据
+2. 跳转到登录页
+
+## 本地调试
+
+```bash
+# 1. 启动代理 (devd)
+devd -l /=http://127.0.0.1:3000 /api/=https://api-dev.copilothub.ai/api
+
+# 2. 启动 Web
+pnpm dev:web
+
+# 3. 启动 Desktop
+pnpm dev:desktop
+```
+
+本地调试时，通过 devd 将 `/api/` 请求代理到 `api-dev.copilothub.ai`。
+
+## 参考
+
+- **Cap** - https://github.com/CapSoftware/Cap