diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
new file mode 100644
index 0000000..535fff9
--- /dev/null
+++ b/DEPLOYMENT.md
@@ -0,0 +1,123 @@
+# Yonexus 部署指南 (v1)
+
+本指南面向 **单主多从** 拓扑：
+- **主节点**：运行 `Yonexus.Server`
+- **从节点**：运行 `Yonexus.Client`
+
+> 说明：Yonexus 采用三仓库/子模块结构（Umbrella + Server + Client + Protocol）。
+
+---
+
+## 1. 拓扑与前置条件
+
+- **主节点**需要可被从节点访问的稳定地址（域名或固定 IP）
+- **从节点**只需能 outbound 访问主节点 WebSocket
+- 需要一个 Discord Bot Token，用于向管理员 DM 配对码
+- 需要管理员的 Discord User ID
+
+---
+
+## 2. 仓库结构与同步
+
+在 umbrella 仓库内：
+
+```
+Yonexus/
+├── Yonexus.Server
+├── Yonexus.Client
+├── Yonexus.Protocol
+```
+
+确保子模块已更新：
+
+```bash
+git submodule update --init --recursive
+```
+
+---
+
+## 3. 主节点部署（Yonexus.Server）
+
+### 3.1 安装与构建
+
+```bash
+cd Yonexus.Server
+npm install
+npm run build
+```
+
+### 3.2 配置
+
+示例配置（OpenClaw 配置中）：
+
+```json
+{
+  "followerIdentifiers": ["client-a", "client-b"],
+  "notifyBotToken": "<discord-bot-token>",
+  "adminUserId": "123456789012345678",
+  "listenHost": "0.0.0.0",
+  "listenPort": 8787,
+  "publicWsUrl": "wss://example.com/yonexus"
+}
+```
+
+### 3.3 启动
+
+- 将 `Yonexus.Server` 安装为 OpenClaw 插件
+- 启动 OpenClaw Gateway 后，Server 会自动启动 WebSocket 服务
+
+---
+
+## 4. 从节点部署（Yonexus.Client）
+
+### 4.1 安装与构建
+
+```bash
+cd Yonexus.Client
+npm install
+npm run build
+```
+
+### 4.2 配置
+
+```json
+{
+  "mainHost": "wss://example.com/yonexus",
+  "identifier": "client-a",
+  "notifyBotToken": "<discord-bot-token>",
+  "adminUserId": "123456789012345678"
+}
+```
+
+### 4.3 启动
+
+- 将 `Yonexus.Client` 安装为 OpenClaw 插件
+- 启动 OpenClaw Gateway 后，Client 会自动连接 Server
+
+---
+
+## 5. 首次配对流程
+
+1. Client 连接后发送 `hello`
+2. Server 检测未配对，生成配对码
+3. Server 通过 Discord DM 将配对码发送给管理员
+4. 管理员将配对码转交给 Client 操作员
+5. Client 提交 `pair_confirm` 完成配对
+6. Server 返回 `pair_success` 并下发 `secret`
+7. Client 进入认证流程并开始心跳
+
+---
+
+## 6. 版本与兼容性
+
+- 协议版本：`1`
+- 需要确保 `Yonexus.Protocol` 子模块与 Server/Client 使用的协议一致
+
+---
+
+## 7. 快速验证建议
+
+- 主节点启动后确认 WebSocket 监听端口可达
+- 从节点能建立连接且收到 `hello_ack`
+- 配对完成后收到 `auth_success`
+- 5 分钟内可看到心跳日志/状态更新
diff --git a/OPERATIONS.md b/OPERATIONS.md
new file mode 100644
index 0000000..6a045e7
--- /dev/null
+++ b/OPERATIONS.md
@@ -0,0 +1,113 @@
+# Yonexus 运维与排障指南 (v1)
+
+本指南覆盖常见运行状态、错误码与恢复步骤。
+
+---
+
+## 1. 运行状态速览
+
+### Client 侧状态
+- `connecting`：正在连接
+- `pairing_required`：需要配对
+- `waiting_pair_confirm`：等待提交配对码
+- `authenticating`：认证中
+- `authenticated`：已认证，心跳中
+
+### Server 侧状态
+- `online`：已认证且心跳正常
+- `unstable`：7 分钟未收到心跳
+- `offline`：11 分钟未收到心跳，已断开连接
+
+---
+
+## 2. 常见问题与处理
+
+### 2.1 Client 无法连接 Server
+**可能原因**
+- `mainHost` 配置错误
+- Server 未启动或端口不可达
+
+**处理**
+- 检查 `mainHost` 是否为 `ws://` 或 `wss://`
+- 验证 Server 监听端口是否对外开放
+
+---
+
+### 2.2 Client 一直停在 `pairing_required`
+**可能原因**
+- Server 未能发送 Discord DM
+- `notifyBotToken` 或 `adminUserId` 配置错误
+
+**处理**
+- 检查 Server 日志是否出现 `admin_notification_failed`
+- 确认 Bot 有向目标用户发送 DM 的权限
+
+---
+
+### 2.3 配对码无效 / 过期
+**可能原因**
+- 输入错误
+- 配对码超过 TTL
+
+**处理**
+- 重新触发配对流程（断线后重连）
+- 确保管理员转发的配对码最新
+
+---
+
+### 2.4 认证失败 (`auth_failed`)
+**可能原因**
+- Secret 不匹配
+- 时间漂移过大
+- Nonce 重放或格式错误
+
+**处理**
+- 检查系统时间是否正确
+- 清除 Client 本地 secret，触发重新配对
+
+---
+
+### 2.5 频繁触发 `re_pair_required`
+**可能原因**
+- 非法重放或高频认证尝试
+- Client 有并发连接/重连异常
+
+**处理**
+- 确认同一 `identifier` 只存在一个活跃 Client
+- 检查 Client 是否重复启动多个实例
+
+---
+
+## 3. 错误码参考
+
+常见协议错误码：
+- `MALFORMED_MESSAGE`
+- `UNSUPPORTED_PROTOCOL_VERSION`
+- `IDENTIFIER_NOT_ALLOWED`
+- `PAIRING_REQUIRED`
+- `PAIRING_EXPIRED`
+- `ADMIN_NOTIFICATION_FAILED`
+- `AUTH_FAILED`
+- `NONCE_COLLISION`
+- `RATE_LIMITED`
+- `RE_PAIR_REQUIRED`
+
+---
+
+## 4. 恢复步骤建议
+
+**场景：Client 无法恢复认证**
+1. 停止 Client
+2. 删除本地 state 中的 secret
+3. 重启 Client 触发重新配对
+
+**场景：Server 端状态异常**
+1. 检查持久化 store 文件是否损坏
+2. 必要时备份后清理 store 文件（会导致所有 Client 重新配对）
+
+---
+
+## 5. 日志建议
+
+- Server 日志中应避免输出 secret / 配对码明文
+- 建议在生产环境开启结构化日志并保留最小必要字段
diff --git a/TASKLIST.md b/TASKLIST.md
index 7ec16c5..d91b8c3 100644
--- a/TASKLIST.md
+++ b/TASKLIST.md
@@ -1065,13 +1065,25 @@
 - 已明确当前限制项（测试、配对输入 UX、生命周期集成等），方便后续交接和联调
 
 ### YNX-1203 输出部署文档
+**状态**
+- [x] 已完成（2026-04-08）
+
 **目标**
 - 写清楚单主多从部署方式、配置示例、配对流程
 
+**已完成内容**
+- 新增 `DEPLOYMENT.md`，覆盖拓扑、子模块同步、Server/Client 安装、配置示例与配对流程
+
 ### YNX-1204 输出运维排障文档
+**状态**
+- [x] 已完成（2026-04-08）
+
 **目标**
 - 写清楚常见报错、状态含义、恢复步骤
 
+**已完成内容**
+- 新增 `OPERATIONS.md`，覆盖状态说明、常见错误与恢复建议
+
 ### YNX-1205 输出协议测试与验收清单
 **状态**
 - [x] 已完成（2026-04-08）