diff --git a/docs/gpui-build.md b/docs/gpui-build.md
new file mode 100644
index 0000000..c0dd367
--- /dev/null
+++ b/docs/gpui-build.md
@@ -0,0 +1,169 @@
+# GPUI 客户端制作文档
+
+> 2026-10-17 制订。**这是施工顺序的权威**：文档 → 依赖补齐 → 逐板块（先功能、后前端）。
+> 旧前端的视觉与交互以 `docs/ui-spec.md` 与 Playwright 实测真值为准；本文管的是
+> 「旧前端的每个能力，在 GPUI 里用什么来顶」。
+
+---
+
+## 一、流程（不可越级）
+
+1. **本文档定稿**——能力清单、依赖清单、板块顺序一次列全，之后按它执行。
+2. **依赖补齐**——一次性把所有"替代旧前端能力"的东西装进来并逐个冒烟验证；缺什么在这里发现，而不是做到一半再发现。
+3. **逐板块施工**：每个板块 = ①功能链路（后端已有则跳过）→ ②前端还原 → ③验收 → ④下一块。**一个板块验收通过才允许碰下一个板块。**
+
+**每块前端的施工纪律**
+
+- 动手前：用 Playwright 打开旧前端（守护进程 18800 一直在跑），点开该板块的每个状态，读 computed style（尺寸/间距/字号/颜色/圆角/阴影/行高），并截图存档到 `artifacts/ui-reference/`。
+- 实现时：所有数值来自实测，不来自记忆或目测；旧前端的 SVG 一律原样移植，不用字符或近似图形代替。
+- 完成后：逐元素核对（尺寸、颜色、间距、图标、悬停态），写无头 UI 测试，最后交用户目视。
+- **禁止语**："差不多""近似""占位"——除第二节 2.4 列明的不可还原项。
+
+---
+
+## 二、能力与资源清单（"依赖" = 旧前端每个能力的 GPUI 对应物）
+
+### 2.1 视觉资源（必须原样移植，不允许字符近似）
+
+| 资源 | 旧实现 | GPUI 方案 | 状态 |
+|---|---|---|---|
+| **OS 图标**（Ubuntu 圆环+三点、Debian 螺旋、Alpine 山、Windows 四格、其余两字母） | `OsBadge.vue` 内联 SVG，品牌色（Ubuntu #e95420 / Debian #e11d48） | 4 个 SVG 原子化到 `gpui-client/assets/icons/os/*.svg`，`svg()` 单色遮罩 + 品牌色；两字母回退保留 | **未做（现在是字符近似，必须替换）** |
+| **品牌 Logo**（黑底圆角方块 + 白色双向 L 形滑块 + 中心圆点，三档尺寸 28/36/48） | `BrandLogo.vue` 内联 SVG + shadow + ring | 同源 SVG 到 `assets/logo.svg`，尺寸 sm/md/lg 三档 | **未做（现在是字符近似）** |
+| UI 图标（房子/漏斗/刷新/太阳/月亮/齿轮/加号/×/星/置顶箭头/铅笔/拖拽手柄/分屏/文件夹/图表/外链） | 内联 Lucide SVG（stroke 2 / 1.8） | gpui-kit 图标集（Lucide 同源），逐图标核对名称、描边、尺寸 | 已用 Lucide，**待逐图标核对** |
+| 字体 | `Inter → PingFang SC → Microsoft YaHei → sans-serif`（本机无 Inter，实测回退浏览器默认 sans） | 主题显式 `Segoe UI`；如仍不像，打包 Inter 字体文件用 `add_fonts` | 已定 Segoe UI（折中，记录差异） |
+
+### 2.2 UI 能力 → gpui-kit 组件
+
+| 旧前端能力 | 旧实现 | GPUI 组件（gpui-kit 0.7.3） |
+|---|---|---|
+| 输入框 / 搜索框 | `` | `Input` / `InputState`（已用） |
+| 下拉选择（跳板机、认证方式） | `