diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..8e51b21
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  backend:
+    name: Backend (build / vet / test / cross-compile)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+
+      # `go:embed` 需要 internal/webui/dist 存在（前端先构建并拷贝）。
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Build frontend (produces internal/webui/dist)
+        working-directory: frontend/web
+        run: |
+          npm ci
+          npm run build
+
+      - name: go build
+        run: go build ./...
+
+      - name: go vet
+        run: go vet ./...
+
+      - name: go test (with coverage)
+        run: go test ./... -count=1 -coverprofile=coverage.out
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.out
+
+      - name: Cross-compile matrix
+        run: |
+          set -e
+          for t in "linux amd64 " "linux arm64 " "linux arm 7" "darwin amd64 " "darwin arm64 " "windows amd64 " "windows arm64 "; do
+            set -- $t
+            echo "== building $1/$2/$3 =="
+            GOOS=$1 GOARCH=$2 GOARM=$3 go build ./...
+          done
+
+  frontend:
+    name: Frontend (tsc + vite build)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Build
+        working-directory: frontend/web
+        run: |
+          npm ci
+          npm run build
diff --git a/README.md b/README.md
index 32ae431..09b3370 100644
--- a/README.md
+++ b/README.md
@@ -2,32 +2,36 @@
 
 > 自托管的「人格化通用智能体运行时」。一个 Go 单二进制，默认以「全能小女友」的人格陪伴你；在聊天/开发/家庭/工作等模式间无感切换；像 OpenClaw 一样接入多个聊天平台（QQ/微信/Telegram…）；各人格独立记忆与情绪、共享同一套能力。
 
-**状态**：重构中（v2 推倒重写）｜ **分支**：`dev` ｜ 设计文档见 `DevDocs/00-overview.md`
+**状态**：M0–M11 已完成，M12 收尾中 ｜ **分支**：`dev` ｜ 设计文档见 `DevDocs/00-overview.md`
 
 ---
 
 ## 核心特性
 
-- **单二进制、进程内协作** — 所有服务同进程打包，仅 gateway `:8080` 对外；模块间走进程内接口 + 事件总线，**零跨进程 IPC**（不重蹈 v1 多端口蜘蛛网）
+- **单二进制、进程内协作** — 所有服务同进程打包，仅 gateway `:8080` 对外；模块间走进程内接口 + 事件总线，**零跨进程 IPC**
 - **人格化陪伴** — 多人格 / 情绪状态机 / 好感度；per-persona 记忆隔离，能力全局共享
-- **通用 Agent 运行时** — 多供应商 LLM、工具调用、子代理编排、记忆/RAG、多模态（vision + 语音）
-- **多平台 IM（内置渠道插件）** — OneBot v11 QQ / ClawBot iLink 微信 / Telegram / Webhook，可配置、可热重载、随二进制分发
-- **语境感知 UI** — 同一会话上下文下切换 聊天/开发/家庭/工作/知识/语音/视觉/子代理监控/设置 模式
-- **超级详尽后台管理面板**（`/admin`）— 15 大模块统一管理
+- **通用 Agent 运行时** — 多供应商 LLM（per-role 路由 + 降级）、工具调用（8 轮上限）、子代理编排、记忆/RAG（三类作用域 + 向量）、多模态（vision 分层路由 + voice 降级链）
+- **多平台 IM（内置渠道插件）** — OneBot v11 QQ / ClawBot iLink 微信 / Telegram / Webhook，可配置、随二进制分发
+- **语境感知 UI** — 同一会话上下文下切换 聊天/开发/家庭/工作/知识/语音/视觉/子代理监控/设置 模式（Miuix 设计语言）
+- **超级详尽后台管理面板**（`/admin`）— 15 大模块统一管理（RBAC + 审计）
 - **单二进制、多平台** — Linux / Windows / macOS / ARM / Termux
 
 ---
 
 ## 快速开始
 
-> 骨架刚重建，以下为演进中的目标方式。
-
 ```bash
-# 配置
-cp .env.example .env   # 至少配置 LLM_API_KEY
+# 前端（go:embed 需要构建产物，先 build）
+cd frontend/web && npm ci && npm run build && cd ../..
 
-# 启动
-go run ./cmd/cyrene/    # 访问 http://localhost:8080
+# 配置
+cp .env.example .env   # 至少配置 LLM_API_KEY / JWT_SECRET
+
+# 启动（单二进制）
+go run ./cmd/cyrene/   # 访问 http://localhost:8080
+
+# 或构建发布用单文件
+go build -ldflags="-s -w" -trimpath -o cyrene ./cmd/cyrene/
 ```
 
 ---
@@ -36,11 +40,11 @@ go run ./cmd/cyrene/    # 访问 http://localhost:8080
 
 | 层 | 技术 |
 |----|------|
-| 后端 | Go 1.26（单二进制运行时）、进程内总线（可换 NATS）、slog |
-| 前端 | React 19、TypeScript、Vite 6、Tailwind 4、Zustand 5 |
-| 数据库 | PostgreSQL 16 + pgvector |
-| 多模态 | vision、realtime voice（STT→agent→TTS） |
-| LLM | 多供应商（云端/订阅/本地/网关） |
+| 后端 | Go 1.26（单二进制运行时）、进程内总线（可换 NATS）、slog（日志带 `source` 来源标注） |
+| 前端 | React 19、TypeScript、Vite 6、Tailwind 4、Zustand 5、PWA（Miuix 设计语言） |
+| 数据库 | **SQLite 默认**（纯 Go、单二进制）；PG + pgvector 可选增强（配置后真生效） |
+| 多模态 | vision（分层路由：主/视觉/OCR）、async voice（STT→agent→TTS 降级链） |
+| LLM | 多供应商（OpenAI 兼容/订阅/本地/网关）、per-role 路由 + 降级 |
 
 ---
 
@@ -48,16 +52,17 @@ go run ./cmd/cyrene/    # 访问 http://localhost:8080
 
 ```
 Cyrene_v2/
-├── cmd/cyrene/            # 唯一入口
-├── internal/              # config / logger / platform / db / bus /
-│                           # runtime(核心) / persona / capability / channel
-├── services/              # gateway / iot / automations
-├── plugins/               # skills(功能) + channels(内置渠道)
+├── cmd/cyrene/            # 唯一入口（mapping 全部子系统 + go:embed 前端）
+├── internal/              # config/logger/platform/db/bus/errors/auth/user/
+│                           # runtime(核心: model/agent/loop/tool/guardrail/trace/persist/
+│                           #   memory/embedding/multimodal/orchestration/exec/task)
+│                           # persona/capability/channel/services(gateway/automations/backthink)/iot/webui
+├── plugins/               # tools(basic/io) + channels(qq_obv11/weixin_ilink/telegram/webhook)
 ├── pkg/plugins/sdk/       # 插件 SDK（第三方）
-├── frontend/web/          # React SPA + /admin 面板
-├── Docs/                  # 用户文档
+├── frontend/web/          # React SPA（mode 系统）+ /admin 面板（Miuix）
+├── Docs/                  # 用户文档（含 api-client.md 客户端 API 契约）
 ├── DevDocs/               # 开发文档（本地，不入库）
-└── configs/               # 配置模板
+└── configs/               # 配置模板（personas/ + users/ 主人档案）
 ```
 
 ---
@@ -68,7 +73,8 @@ Cyrene_v2/
 |------|------|------|
 | 架构总览/重构蓝图 | `DevDocs/00-overview.md` | 产品定位、架构、渠道插件、后台面板、阶段计划 |
 | 开发约束 | `DevDocs/02-development-constraints.md` | 编码规范 + 性能要求 |
-| 用户文档 | `Docs/` | 使用指南/API |
+| **客户端 API** | `Docs/api-client.md` | 跨平台客户端 API 契约（REST/WS/admin，版本化） |
+| 开发铁律 | `AGENTS.md` | 每会话自动注入；含全球红线（单二进制/身份识别/前端 Miuix 等） |
 
 ---