diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c79dd4b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,60 @@
+# Patchbay
+
+一个跑在服务器上的网页，用来编辑那台机器上 mihomo 的 `config.yaml` 并让改动生效。
+
+核心动作是把某一路入站接到某一个出站上——名字取自录音棚的插线板。典型用途是给每个容器开一个端口，各自指定走哪条线路。
+
+聚合订阅不在范围内（那是 Sub-Store 的活），安装升级内核也不在（那是 `mihomo-up.sh` 的活）。
+
+术语以 [CONTEXT.md](./CONTEXT.md) 为准。为什么这么设计记在仓库外面的 `docs/adr/`。
+
+## 跑起来
+
+需要 [Bun](https://bun.com) 1.3 以上。
+
+```bash
+bun install
+cp .env.example .env   # 按里面的注释填
+bun run start          # 打包前端并启动，默认 http://127.0.0.1:7580
+```
+
+首次启动会生成一个访问令牌，打印在控制台上，同时存到配置文件旁边的 `.patchbay-token`。
+
+**内核不在线也能用**，只是看不到订阅里有哪些线路、也没法让改动立刻生效。这是有意的——配置写坏导致内核起不来的时候，正是最需要这个界面的时候。
+
+## 开发
+
+改前端时用 Vite，它会把接口请求转发给后端：
+
+```bash
+bun run dev        # 后端，带热重载
+bun run dev:web    # 前端，http://localhost:5173
+```
+
+本地有一份测试用的内核配置（`dev/config.yaml`，全是占位地址，端口刻意避开 mihomo 的默认值），可以对着它跑完整的「写回 → 校验 → 重载 → 失败还原」：
+
+```bash
+bun run dev:kernel   # 启动本地测试内核，管理接口 19090
+bun run dev:reset    # 把测试配置恢复成模板的样子
+```
+
+## 检查
+
+```bash
+bun test        # 单元测试，不需要内核
+bun run smoke   # 接口冒烟测试，需要内核和后端都在跑
+bun run typecheck
+```
+
+另有两个一次性脚本：`scripts/roundtrip.ts` 验证改一处配置之后 diff 里只出现那一处，`scripts/safety-net.ts` 验证配置写坏时能不能把用户救回来。
+
+## 目录
+
+```
+server/    后端。config-store.ts 是核心，那条保护链路在里面
+web/       前端。styles/tokens.css 顶部写着设计基调的三条规则
+shared/    两边共用的领域逻辑，纯函数，带测试
+vendor/    从别的项目复制来的代码，来源和本地改动记在各自的 ORIGIN.md
+scripts/   验证用的脚本，不参与打包
+dev/       本地测试内核的配置
+```
diff --git a/package.json b/package.json
index 17eb981..7e942a7 100644
--- a/package.json
+++ b/package.json
@@ -5,10 +5,14 @@
   "type": "module",
   "description": "mihomo 配置的网页界面：把每一路入站接到它自己的出站上",
   "scripts": {
+    "start": "vite build && bun run server/index.ts",
     "dev": "bun run --hot server/index.ts",
     "dev:web": "vite",
+    "dev:kernel": "../binary/mihomo-windows-amd64-v3-go125.exe -d dev/home -f dev/home/config.yaml",
+    "dev:reset": "cp dev/config.yaml dev/home/config.yaml",
     "build": "vite build",
     "test": "bun test",
+    "smoke": "bun run scripts/api-smoke.ts",
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {