diff --git a/.github/workflows/ci-check.yml b/.github/workflows/ci-check.yml
index 6e7acef..cce6ff1 100644
--- a/.github/workflows/ci-check.yml
+++ b/.github/workflows/ci-check.yml
@@ -22,3 +22,6 @@ jobs:
       - run: pnpm typecheck
 
       - run: pnpm test
+
+      - name: Verify documentation consistency
+        run: ./scripts/verify-docs.sh
diff --git a/AGENTS.md b/AGENTS.md
index 66cd1ae..9545464 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,3 +1,5 @@
+> **Note:** The content below has been migrated to the project root as `CLAUDE.md` so that Claude Code auto-loads it. Please read `CLAUDE.md` first; this file is kept for backward references.
+
 # CLAUDE.md
 
 Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..459b9b9
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to NeoCompanion will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Documentation quality improvement initiative: added `LICENSE`, `CLAUDE.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `docs/DEVELOPMENT.md`, `docs/API.md`, `docs/TTS_SETUP.md`, `docs/GLOSSARY.md`, `docs/TODO_INVENTORY.md`, `docs/TESTING.md`, and `scripts/verify-docs.sh`.
+
+### Fixed
+
+- Corrected stale product name references in `docs/ARCHITECTURE.md` to match the project name.
+- Replaced broken Windows-absolute `file:///` links in `docs/PRD_overview.md` with relative paths.
+- Updated MiMo TTS missing-base-URL error to point to `docs/TTS_SETUP.md`.
+- Marked the GitHub Actions implementation plan as implemented.
+
+## [0.1.0] - 2026-06-19
+
+### Added
+
+- Floating desktop companion widget with 2D sprite animation and TTS feedback.
+- Companion panel window for task management, AI chat, settings, and Hook approvals.
+- Wallpaper status layer (Windows) embedding weather, time, focus ring, task progress, and assistant messages via `tauri-plugin-wallpaper`.
+- Local Fastify sidecar exposing REST API and WebSocket hub on `localhost:10103`.
+- SQLite persistence for tasks, focus sessions, conversations, messages, settings, and window events via Drizzle ORM.
+- Pomodoro-style focus timer with companion feedback.
+- Local task list with create/update/status change support.
+- AI chat adapter for DeepSeek with streaming responses.
+- MiMo TTS adapter for spoken companion feedback.
+- Weather summary service.
+- Active-window snapshot service with focused/distracted/stuck classification.
+- Hook system for external agents to push status updates and request permissions.
+- Knowledge workspace UI (v3.3) with Projects, Notes, Kanban Board, and Tasks — front-end mock stage; real backend storage and search are planned.
+- GitHub Actions workflows for PR checks, cross-platform Tauri builds, and tag-triggered releases.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b297274
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,118 @@
+# NeoCompanion — Claude Code Project Context
+
+## Project Overview
+
+NeoCompanion is a local-first desktop AI assistant built with **Tauri v2** (Rust) + **Vue 3** (Vite) + **Fastify** (TypeScript sidecar) + **SQLite** (Drizzle ORM).
+
+It provides:
+
+- A floating companion widget (`?view=pet`)
+- A panel window for tasks, AI chat, and settings (`?view=panel`)
+- A wallpaper status layer (`?view=wallpaper`) embedded via `tauri-plugin-wallpaper` (Windows)
+- A knowledge workspace (`?view=knowledge`) introduced in v3.3
+- A local Hook API for external scripts to push notifications and permission requests
+
+## Architecture at a Glance
+
+```
+Tauri Rust Core
+  ├─ window management, tray, wallpaper embedding, system credentials
+  └─ hosts Fastify sidecar (localhost:10103 by default)
+
+Fastify Sidecar
+  ├─ REST API for tasks, focus timer, AI chat, TTS, weather, hooks, windows
+  ├─ WebSocket hub at /ws for streaming AI replies and companion feedback
+  └─ SQLite via Drizzle ORM
+
+Vue 3 Frontend
+  ├─ 5 views selected by ?view= query param
+  └─ communicates with sidecar via HTTP + WebSocket, with Rust via Tauri IPC
+```
+
+## Key Directories
+
+| Path | Purpose |
+|------|---------|
+| `apps/desktop/src-tauri/` | Rust backend, Tauri commands, window config |
+| `apps/desktop/src/` | Vue 3 frontend, views, components, composables |
+| `packages/server-local/` | Fastify sidecar with all business logic |
+| `packages/db/` | SQLite schema and stores via Drizzle ORM |
+| `packages/shared/` | Shared TypeScript types |
+| `packages/ai/` | DeepSeek streaming chat adapter |
+| `packages/tts/` | MiMo TTS adapter |
+| `docs/` | Product and technical documentation |
+
+## Current State Notes
+
+- The **knowledge workspace** UI exists but is backed by a front-end mock (`useKnowledgeMock.ts`). The real SQLite-backed API, FTS5 full-text search, and `sqlite-vec` vector retrieval described in the architecture doc are **planned for v2**, not yet implemented.
+- The codebase still uses `pet`/`companion` identifiers in many places (`components/pet/`, `usePetState.ts`, `pet.css`). The product-facing terminology is **assistant**, but a full code-level rename is out of scope for documentation-only work.
+- The sidecar runs on `http://127.0.0.1:10103` by default (configurable via `NEO_SERVER_PORT`).
+
+## Development Quick Reference
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run desktop + sidecar in development
+pnpm dev:tauri
+
+# Typecheck all packages
+pnpm typecheck
+
+# Run tests
+pnpm test
+```
+
+See `docs/DEVELOPMENT.md` for the full setup guide.
+
+## Documentation Index
+
+| Document | Purpose |
+|----------|---------|
+| `README.md` | Project overview and feature summary |
+| `docs/PRD_overview.md` | Product requirements and roadmap |
+| `docs/ARCHITECTURE.md` | System architecture and data flow |
+| `docs/具体能力构思.md` | Detailed capability design (Chinese) |
+| `docs/WALLPAPER_STATUS_LAYER.md` | Wallpaper layer design |
+| `docs/SOUL_CONFIG.md` | Assistant persona configuration spec |
+| `docs/DEVELOPMENT.md` | Development environment setup |
+| `docs/API.md` | Sidecar REST API and WebSocket reference |
+| `docs/TTS_SETUP.md` | MiMo TTS configuration guide |
+| `docs/TESTING.md` | Testing strategy and commands |
+| `docs/GLOSSARY.md` | Terminology conventions |
+| `docs/TODO_INVENTORY.md` | Known doc-to-code mismatch TODOs |
+
+## Coding Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes. These bias toward caution over speed; use judgment for trivial tasks.
+
+### 1. Think Before Coding
+
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+
+### 2. Simplicity First
+
+- Minimum code that solves the problem. Nothing speculative.
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No error handling for impossible scenarios.
+
+### 3. Surgical Changes
+
+- Touch only what you must. Clean up only your own mess.
+- Don't "improve" adjacent code, comments, or formatting.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it unless asked.
+
+### 4. Goal-Driven Execution
+
+- Transform tasks into verifiable goals.
+- For multi-step tasks, state a brief plan with verification steps.
+- Strong success criteria let you loop independently.
+
+---
+
+*These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..0165100
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,89 @@
+# Contributing to NeoCompanion
+
+Thanks for your interest in NeoCompanion! This guide covers how to set up the project, make changes, and open pull requests.
+
+## Prerequisites
+
+- **Node.js** 22 or later
+- **pnpm** 10.32 or later (project uses `pnpm@10.32.0`)
+- **Rust** stable toolchain (for Tauri v2)
+- Platform dependencies for Tauri v2:
+  - **Windows**: WebView2 runtime (usually preinstalled on Windows 11)
+  - **macOS**: Xcode Command Line Tools
+  - **Linux**: `libwebkit2gtk-4.1-dev`, `build-essential`, `libssl-dev`, `libayatana-appindicator3-dev`, `librsvg2-dev`, and related packages
+
+See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for the full environment setup.
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd NeoCompanion
+
+# Install dependencies
+pnpm install
+
+# Run the desktop app + sidecar in development mode
+pnpm dev:tauri
+```
+
+## Branch and Commit Conventions
+
+- Create feature branches from the current active branch (`feat/v3.3-knowledge-workspace` at the time of writing):
+  ```bash
+  git checkout -b docs/your-change-name
+  ```
+- Use [Conventional Commits](https://www.conventionalcommits.org/):
+  - `feat:` new feature
+  - `fix:` bug fix
+  - `docs:` documentation only
+  - `refactor:` code change that neither fixes a bug nor adds a feature
+  - `test:` adding or updating tests
+  - `chore:` tooling, dependencies, or maintenance
+- Keep commits focused and atomic.
+
+## Before Submitting a Pull Request
+
+1. **Typecheck everything:**
+   ```bash
+   pnpm typecheck
+   ```
+2. **Run tests:**
+   ```bash
+   pnpm test
+   ```
+3. **Run the documentation verification script (if it exists):**
+   ```bash
+   ./scripts/verify-docs.sh
+   ```
+4. **Update relevant documentation:** if your change adds an environment variable, API endpoint, or feature flag, update:
+   - `.env.example`
+   - `docs/DEVELOPMENT.md`
+   - `docs/API.md`
+   - `CHANGELOG.md`
+
+## Code Style
+
+- TypeScript: prefer explicit types on public APIs, immutable updates, and early returns.
+- Vue 3: use the Composition API and `<script setup>`.
+- Rust: follow the existing `src-tauri` style.
+- Keep functions focused and files under 800 lines when possible.
+
+## Documentation-First Changes
+
+When changing docs:
+
+- Do not claim unimplemented features are shipped. If a feature is planned, mark it as `(Planned)` or `(Partial)`.
+- Use the product terminology from [`docs/GLOSSARY.md`](docs/GLOSSARY.md).
+- Avoid Windows-absolute `file:///` links; use relative paths.
+- Keep `ARCHITECTURE.md`, `PRD_overview.md`, and `README.md` in sync.
+
+## Getting Help
+
+- Open an issue for bugs or feature requests.
+- Discuss larger changes in an issue before opening a PR.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..c01f1b8
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NeoCompanion contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index c327b5b..aec7463 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # NeoCompanion
 
 [![Status](https://img.shields.io/badge/Status-Draft--Approved--v3.3-blue.svg)](#)
-[![Version](https://img.shields.io/badge/Version-3.3-green.svg)](#)
+[![Version](https://img.shields.io/badge/Version-0.1.0-green.svg)](#)
 [![License](https://img.shields.io/badge/License-MIT-purple.svg)](#)
 
 > 一个融入桌面的 AI 助手——状态融入壁纸，轻交互近在手边，编辑留给面板。
@@ -145,10 +145,10 @@ NeoCompanion 的能力由浅入深分为四层：
 | 桌面运行时 | **Tauri v2** (Rust) |
 | 前端 UI | **Vue 3** + Vite + Pinia + TanStack Query |
 | 本地服务 | **Fastify** (TypeScript Sidecar) |
-| 数据库 | **SQLite** (Drizzle ORM + FTS5) + **sqlite-vec** |
+| 数据库 | **SQLite** (Drizzle ORM) |
 | AI | 聊天模型适配器 + OpenAI-compatible Embedding Adapter |
 
-架构核心：Tauri (Rust) 提供系统级能力 → Fastify (TypeScript) 处理业务逻辑、索引与 AI 调度 → Vue 提供 UI → SQLite 统一存储业务数据、全文索引和向量索引。
+架构核心：Tauri (Rust) 提供系统级能力 → Fastify (TypeScript) 处理业务逻辑与 AI 调度 → Vue 提供 UI → SQLite 统一存储业务数据。v2 计划引入 FTS5 全文索引与 sqlite-vec 向量索引，当前版本尚未实现。
 
 详见 [**系统架构设计**](docs/ARCHITECTURE.md)。
 
@@ -163,9 +163,17 @@ NeoCompanion 的能力由浅入深分为四层：
 | [**系统架构设计**](docs/ARCHITECTURE.md) | Tauri + Fastify + Vue 多端通信、数据流、Hook 审批架构 |
 | [**壁纸层状态显示**](docs/WALLPAPER_STATUS_LAYER.md) | WorkerW 嵌入方案、壁纸组件设计、三层职责划分 |
 | [**助手人设配置**](docs/SOUL_CONFIG.md) | soul.md 文件规格、人设可配置系统、热加载机制 |
+| [**开发环境搭建**](docs/DEVELOPMENT.md) | 本地开发环境、依赖、运行命令 |
+| [**Sidecar API 参考**](docs/API.md) | REST API 与 WebSocket 消息说明 |
+| [**TTS 配置指南**](docs/TTS_SETUP.md) | MiMo TTS 接入与故障排查 |
+| [**测试说明**](docs/TESTING.md) | 测试策略与命令 |
+| [**术语表**](docs/GLOSSARY.md) | 项目术语与弃用词汇 |
+| [**已知 TODO**](docs/TODO_INVENTORY.md) | 文档与代码不一致的待办清单 |
+| [**贡献指南**](CONTRIBUTING.md) | 如何参与项目 |
+| [**更新日志**](CHANGELOG.md) | 版本发布记录 |
 
 ---
 
 ## License
 
-MIT
+[MIT](LICENSE)
diff --git a/apps/desktop/src/composables/usePetState.ts b/apps/desktop/src/composables/usePetState.ts
index 764d828..bdeac0f 100644
--- a/apps/desktop/src/composables/usePetState.ts
+++ b/apps/desktop/src/composables/usePetState.ts
@@ -27,14 +27,14 @@ const feedbackPool: Record<CompanionState, string[]> = {
     "正在翻记忆的小本本……",
   ],
   warn: [
-    "主子，是不是该回来啦？",
+    "是不是该回来啦？",
     "哎……说好要专心的呢~",
     "别走远啦，我等你回来！",
     "嘿，该回来干活了哦~",
   ],
   sleepy: [
     "夜深了，我们也该休息了吧？",
-    "好困……小宠的眼皮都打架了……",
+    "好困……眼皮都打架了……",
     "今天辛苦了，早点休息好不好？",
     "已经好晚了，明天再来也行的~",
   ],
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..3c49ed6
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,375 @@
+# Sidecar API 参考
+
+NeoCompanion sidecar 是一个本地 Fastify 应用，为 Vue 前端提供 REST API 和 WebSocket 端点。它由 Tauri Rust 核心管理。
+
+- **开发环境 Base URL**：`http://127.0.0.1:10103`
+- **默认端口**：`10103`（可通过 `NEO_SERVER_PORT` 修改）
+- **WebSocket 端点**：`/ws`
+
+所有端点默认返回 JSON，除非另有说明。
+
+---
+
+## 健康检查
+
+### `GET /health`
+
+返回服务健康状态和当前时间戳。
+
+**响应：**
+
+```json
+{
+  "ok": true,
+  "service": "neo-companion-server-local",
+  "time": "2026-06-19T12:34:56.789Z"
+}
+```
+
+---
+
+## 任务
+
+### `GET /api/tasks`
+
+列出所有任务。
+
+**响应：**
+
+```json
+[
+  {
+    "id": "task-1",
+    "title": "阅读 API 文档",
+    "status": "open",
+    "createdAt": "2026-06-19T12:00:00.000Z",
+    "completedAt": null
+  }
+]
+```
+
+### `POST /api/tasks`
+
+创建新任务。
+
+**请求体：**
+
+```json
+{
+  "title": "写测试"
+}
+```
+
+**响应：** 创建后的任务对象。
+
+**错误：**
+
+- `400` — `title is required`
+
+### `PATCH /api/tasks/:id`
+
+更新任务标题或状态。
+
+**请求体：**
+
+```json
+{
+  "title": "更新后的标题",
+  "status": "done"
+}
+```
+
+**响应：** 更新后的任务对象。
+
+**错误：**
+
+- `404` — 任务不存在
+
+---
+
+## 专注计时
+
+### `POST /api/focus/start`
+
+开始新的专注时段。
+
+**请求体：**
+
+```json
+{
+  "taskId": "task-1",
+  "durationMinutes": 25
+}
+```
+
+- `taskId` 可选；`durationMinutes` 默认 `25`。
+
+**响应：** 创建的专注会话。
+
+### `POST /api/focus/:id/complete`
+
+完成一个进行中的专注会话。
+
+**响应：** 完成后的专注会话。
+
+**错误：**
+
+- `404` — 专注会话不存在
+
+---
+
+## 天气
+
+### `GET /api/weather`
+
+获取配置城市（`NEO_CITY`）的天气摘要。
+
+**响应：**
+
+```json
+{
+  "city": "Beijing",
+  "temperatureC": 24,
+  "precipitationChance": 10,
+  "text": "晴朗，24°C"
+}
+```
+
+---
+
+## AI 聊天
+
+### `POST /api/ai/chat`
+
+向助手发送消息，并通过 WebSocket 流式返回结果。
+
+**请求体：**
+
+```json
+{
+  "message": "接下来该做什么？"
+}
+```
+
+**响应：**
+
+```json
+{
+  "text": "要不要先查看未完成任务？"
+}
+```
+
+**请求过程中会广播以下 WebSocket 事件：**
+
+- `companion:feedback`，状态为 `thinking`
+- `ai:chunk` 每个流式片段
+- `ai:done` 响应完成
+- `ai:error` 失败时
+
+**错误：**
+
+- `400` — `message is required`
+- `500` — AI 请求失败
+
+---
+
+## 语音合成
+
+### `POST /api/tts/speak`
+
+使用配置的 MiMo TTS 提供商将文本转为语音。
+
+**请求体：**
+
+```json
+{
+  "text": "专注完成，休息一下吧！",
+  "style": "温柔、自然"
+}
+```
+
+- `style` 可选。
+
+**响应：**
+
+```json
+{
+  "audioUrl": "data:audio/mp3;base64,...",
+  "format": "mp3",
+  "provider": "mimo",
+  "cached": false
+}
+```
+
+**WebSocket 事件：**
+
+- `tts:started`
+- `tts:done`
+
+**错误：**
+
+- `400` — `text is required`
+- TTS 提供商错误会返回 `500`
+
+配置说明见 [`docs/TTS_SETUP.md`](TTS_SETUP.md)。
+
+---
+
+## 窗口活动
+
+### `GET /api/window/active`
+
+捕获当前活动窗口并持久化。
+
+**响应：**
+
+```json
+{
+  "title": "Visual Studio Code",
+  "processName": "Code.exe",
+  "capturedAt": "2026-06-19T12:34:56.789Z",
+  "dwellSeconds": 120,
+  "classification": "focused"
+}
+```
+
+`classification` 取值：`focused`、`distracted`、`stuck`。
+
+sidecar 启动后会每 30 秒自动轮询该端点。
+
+---
+
+## Hook 系统
+
+外部 Agent 可通过 Hook API 推送状态更新或请求执行敏感命令的权限。
+
+### `POST /api/hook/push`
+
+推送外部 Agent 的状态更新。
+
+**请求体：**
+
+```json
+{
+  "agentId": "ci-server",
+  "type": "status",
+  "state": "success",
+  "description": "构建通过",
+  "timestamp": 1718800000000
+}
+```
+
+- `timestamp` 可选，默认 `Date.now()`。
+
+**响应：** `204 No Content`
+
+**错误：**
+
+- `400` — 缺少 `agentId`、无效 `type` 或缺少 `state`
+
+有效 `state` 定义在 `@neo-companion/shared` 中：
+`idle`、`thinking`、`working`、`building`、`waiting`、`success`、`error`、`juggling`、`sleeping`。
+
+### `POST /api/hook/permission`
+
+请求敏感命令的执行权限。
+
+**请求体：**
+
+```json
+{
+  "agentId": "deploy-bot",
+  "command": "kubectl apply -f production.yaml",
+  "severity": 3,
+  "description": "部署到生产环境"
+}
+```
+
+**响应：** 权限决议结果。
+
+**错误：**
+
+- `400` — 缺少必填字段
+- `410` — 请求已过期或 Agent 状态变化
+- `503` — 服务正在关闭
+
+### `GET /api/hook/always-rules`
+
+列出用户配置的"始终允许"规则。
+
+**响应：**
+
+```json
+[
+  {
+    "agentId": "deploy-bot",
+    "commandPrefix": "kubectl apply -f staging",
+    "createdAt": 1718800000000
+  }
+]
+```
+
+### `DELETE /api/hook/always-rules`
+
+移除一条"始终允许"规则。
+
+**请求体：**
+
+```json
+{
+  "agentId": "deploy-bot",
+  "commandPrefix": "kubectl apply -f staging"
+}
+```
+
+**响应：** `204 No Content`
+
+---
+
+## WebSocket
+
+### `GET /ws`
+
+升级为 WebSocket 连接，用于接收实时事件。
+
+sidecar 会广播以下消息类型：
+
+| 类型 | 方向 | 说明 |
+|------|------|------|
+| `ai:chunk` | 服务端 → 客户端 | AI 流式响应片段 |
+| `ai:done` | 服务端 → 客户端 | AI 响应完成 |
+| `ai:error` | 服务端 → 客户端 | AI 调用失败 |
+| `companion:feedback` | 服务端 → 客户端 | 助手状态/反馈更新 |
+| `task:statusChanged` | 服务端 → 客户端 | 任务创建或更新 |
+| `focus:tick` | 服务端 → 客户端 | 专注计时 tick |
+| `window:activeChanged` | 服务端 → 客户端 | 活动窗口快照更新 |
+| `tts:started` | 服务端 → 客户端 | TTS 开始播放 |
+| `tts:done` | 服务端 → 客户端 | TTS 播放完成 |
+| `hook:statusChanged` | 服务端 → 客户端 | Hook Agent 状态变化 |
+| `permission:request` | 服务端 → 客户端 | 权限请求待处理 |
+| `permission:resolved` | 服务端 → 客户端 | 权限请求已决议 |
+| `permission:autoDismiss` | 服务端 → 客户端 | 权限请求自动取消 |
+| `permission:response` | 客户端 → 服务端 | 用户对权限请求的决议 |
+| `ping` | 客户端 → 服务端 | 心跳 ping |
+| `pong` | 服务端 → 客户端 | 心跳 pong |
+
+### 示例：响应权限请求
+
+```json
+{
+  "type": "permission:response",
+  "payload": {
+    "requestId": "req-123",
+    "decision": "allow"
+  }
+}
+```
+
+`decision` 可选：`allow`、`deny`、`always`。
+
+---
+
+## 说明
+
+- 知识工作空间相关的搜索端点（`/api/knowledge/*`）**尚未实现**。当前知识工作空间 UI 由前端 mock 驱动。
+- 错误响应格式通常为 `{ "error": "message" }`，除非另有说明。
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 64bbb01..789a996 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,8 +1,8 @@
-# NeoAssistant 系统架构文档
+# NeoCompanion 系统架构文档
 
 ## Document Header
 
-- **Title**: NeoAssistant System Architecture Document
+- **Title**: NeoCompanion System Architecture Document
 - **Owner**: Engineering
 - **Status**: Draft (Aligned with Concept / PRD v3.3)
 - **Version**: 1.3
@@ -18,7 +18,7 @@
 
 ## 1. Document Purpose
 
-本文档定义 NeoAssistant 的系统架构、技术选型、模块划分、数据流和工程实现方案。
+本文档定义 NeoCompanion 的系统架构、技术选型、模块划分、数据流和工程实现方案。
 
 本文档基于总景 PRD 和能力构思文档中已确定的产品定义、能力模型和阶段规划，将产品需求转化为可落地的技术架构。
 
@@ -31,6 +31,16 @@
 - 架构文档不应反向扩大产品范围；
 - 架构文档中的模块划分必须能追溯到 PRD 中的能力层或产品闭环。
 
+### 1.2 Document Scope
+
+本文档同时描述 **已实现** 与 **规划中** 的技术设计。已实现的内容指当前代码中真实存在并运行的模块；规划中的内容标注为 `(Planned)` 或 `(Partial)`，例如：
+
+- **已实现**：Tauri 多窗口管理、Fastify Sidecar TCP 模式、SQLite + Drizzle ORM、任务/专注/天气/AI/TTS/窗口/Hook 等核心端点、WebSocket 实时推送、GitHub Actions CI/CD。
+- **部分实现 (Partial)**：v3.3 知识工作空间 UI（前端 mock 阶段，后端存储与检索尚未接入）。
+- **规划中 (Planned)**：FTS5 全文索引、`sqlite-vec` 向量检索与混合排序、零端口 UDS Socket 模式 B、文件监听 Hook、MQTT 接入、屏幕上下文感知与本地长期记忆模块。
+
+阅读时请注意段落中的状态标注，避免将规划内容误认为已交付功能。
+
 ---
 
 ## 2. Architecture Principles
@@ -155,7 +165,7 @@ NeoCompanion 是一个本地优先的桌面应用。
 
 **为什么用 WebSocket？**
 
-NeoAssistant 需要服务端随时主动推送内容（AI 流式回复、陪伴反馈、上下文变化通知），且未来交互频率会增长。WebSocket 从 v1 开始建立双向通道，避免后期 SSE→WS 迁移成本。
+NeoCompanion 需要服务端随时主动推送内容（AI 流式回复、陪伴反馈、上下文变化通知），且未来交互频率会增长。WebSocket 从 v1 开始建立双向通道，避免后期 SSE→WS 迁移成本。
 
 #### 3.2.1 WebSocket 连接生命周期
 
@@ -909,7 +919,7 @@ LLM API 不可用时（网络断开、API Key 无效、服务超时），系统
 
 ## 8. Context Pipeline
 
-Context Pipeline 是 NeoAssistant 的核心差异化模块，负责将分散的系统事件、应用状态和用户行为转化为结构化的任务上下文。
+Context Pipeline 是 NeoCompanion 的核心差异化模块，负责将分散的系统事件、应用状态和用户行为转化为结构化的任务上下文。
 
 ### 8.1 Pipeline Architecture
 
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
new file mode 100644
index 0000000..cb738ca
--- /dev/null
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,140 @@
+# 开发环境搭建
+
+本文档介绍如何在本地构建并运行 NeoCompanion。
+
+## 环境要求
+
+| 工具 | 版本 | 说明 |
+|------|------|------|
+| Node.js | 22.x | 建议使用 LTS |
+| pnpm | 10.32+ | 由 `packageManager` 字段强制锁定 |
+| Rust | stable | 用于 Tauri v2 后端 |
+| Git | 任意 | |
+
+### Tauri 平台依赖
+
+- **Windows**：需要 WebView2 运行时。Windows 11 和较新 Windows 10 通常已预装。如缺失，请从 [Microsoft](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) 安装。
+- **macOS**：安装 Xcode Command Line Tools：
+  ```bash
+  xcode-select --install
+  ```
+- **Linux（Debian/Ubuntu）**：
+  ```bash
+  sudo apt-get update
+  sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
+  ```
+
+其它 Linux 发行版请参考 [Tauri 前置条件](https://v2.tauri.app/start/prerequisites/)。
+
+## 初始设置
+
+```bash
+# 1. 克隆仓库
+git clone <仓库地址>
+cd NeoCompanion
+
+# 2. 安装依赖
+pnpm install
+
+# 3. 复制环境变量模板
+cp .env.example .env
+# 然后编辑 .env 填入你的 key（见下方环境变量说明）
+```
+
+## 环境变量
+
+项目开发时从根目录 `.env` 文件读取配置。模板见 `.env.example`。
+
+| 变量 | 是否必填 | 默认值 | 说明 |
+|------|----------|--------|------|
+| `DEEPSEEK_API_KEY` | 是* | — | DeepSeek 聊天 API key。AI 对话功能需要。 |
+| `DEEPSEEK_MODEL` | 否 | `deepseek-v4-flash` | DeepSeek 模型名称。 |
+| `MIMO_API_KEY` | 是* | — | MiMo TTS API key。语音反馈功能需要。 |
+| `MIMO_TTS_VOICE` | 否 | `茉莉` | 默认 MiMo TTS 音色。 |
+| `NEO_CITY` | 否 | `Beijing` | 天气服务使用的城市。 |
+| `NEO_SERVER_PORT` | 否 | `10103` | Fastify sidecar 监听端口。 |
+
+*AI / TTS 相关的 key 至少需要一个才能使用该功能；不填也能启动应用，但对应端点会失败。
+
+详见 [`docs/TTS_SETUP.md`](TTS_SETUP.md) 中的 MiMo TTS 详细配置。
+
+## 开发运行
+
+### 桌面应用 + sidecar（推荐）
+
+```bash
+pnpm dev:tauri
+```
+
+这会同时启动两个进程：
+
+1. `@neo-companion/server-local` — Fastify sidecar，默认 `http://127.0.0.1:10103`
+2. `@neo-companion/desktop` — Tauri 桌面应用，支持热更新
+
+### 纯 Web 前端 + sidecar
+
+适合只做前端 UI 迭代、不需要 Rust 构建的场景：
+
+```bash
+pnpm dev
+```
+
+这只会启动 sidecar 和 Vue dev server。Tauri 专属功能（壁纸嵌入、原生窗口 API）不可用。
+
+## 常用命令
+
+```bash
+# 全仓库类型检查
+pnpm typecheck
+
+# 运行全部测试
+pnpm test
+
+# 构建全部包
+pnpm build
+
+# lint（目前为 typecheck 别名）
+pnpm lint
+```
+
+## 项目结构
+
+```
+NeoCompanion/
+├── apps/desktop/src-tauri/   # Rust / Tauri 后端
+├── apps/desktop/src/         # Vue 3 前端
+├── packages/server-local/    # Fastify sidecar
+├── packages/db/              # SQLite + Drizzle ORM
+├── packages/shared/          # 共享 TypeScript 类型
+├── packages/ai/              # DeepSeek 聊天适配器
+├── packages/tts/             # MiMo TTS 适配器
+└── docs/                     # 项目文档
+```
+
+## 运行测试
+
+详见 [`docs/TESTING.md`](TESTING.md)。
+
+## 常见问题
+
+### `pnpm install` 在 `better-sqlite3` 上失败
+
+`better-sqlite3` 是原生模块。请确保 Node.js 版本兼容，且 `node-gyp` 能找到 Python。Windows 上建议安装 Visual Studio Build Tools 的"使用 C++ 的桌面开发"工作负载。
+
+### Linux 上 Tauri 构建失败
+
+请确认已安装全部 Tauri Linux 依赖（见上文）。常见缺失项是 `libayatana-appindicator3-dev`。
+
+### sidecar 端口被占用
+
+在 `.env` 中修改 `NEO_SERVER_PORT` 为其它端口即可。
+
+### AI 聊天或 TTS 报错
+
+检查 `.env` 中 `DEEPSEEK_API_KEY` 和 `MIMO_API_KEY` 是否已设置，以及对应服务端点是否可访问。
+
+## 下一步
+
+- 阅读[系统架构设计](ARCHITECTURE.md)
+- 查看 [Sidecar API 参考](API.md)
+- 查看[测试说明](TESTING.md)
diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
new file mode 100644
index 0000000..80a6106
--- /dev/null
+++ b/docs/GLOSSARY.md
@@ -0,0 +1,41 @@
+# 术语表
+
+本文档定义 NeoCompanion 的推荐术语，并列出在新文档和用户-facing 文案中应避免使用的旧术语。
+
+## 推荐术语
+
+| 术语 | 含义 | 备注 |
+|------|------|------|
+| **助手 / Assistant** | 桌面悬浮智能助手 | 默认面向用户的称呼 |
+| **悬浮层 / Float Layer** | 包含助手形象、语音气泡、Hook 角标的层级 | 主要交互入口 |
+| **壁纸层 / Wallpaper Layer** | 嵌入桌面壁纸的状态显示层 | 展示天气、时间、任务、专注环、助手寄语 |
+| **面板层 / Panel Layer** | 用于任务管理、AI 对话、设置、Hook 审批的主应用窗口 | 按需弹出 |
+| **专注 / Focus** | 番茄钟式专注计时 | 助手与用户同步进入专注 |
+| **任务 / Task** | 待办事项 | 在简单任务清单和看板中统一 |
+| **Hook** | 外部 Agent 集成机制 | 外部脚本通过本地 API 推送状态或请求权限 |
+| **知识工作空间 / Knowledge Workspace** | 项目、笔记、看板、AI 对话工作区 | v3.3 已引入 UI；后端存储与检索计划中 |
+| **助手寄语 / Assistant Message** | 壁纸层中央淡出的简短反馈文字 | 旧称"伴侣寄语" |
+
+## 弃用术语
+
+| 弃用术语 | 替换为 | 状态 |
+|----------|--------|------|
+| 桌宠 / Desk Pet | 桌面悬浮助手 / Assistant | 新文档与 UI 文案中不再使用 |
+| 宠物 / Pet | 助手 / Assistant | 新文档与 UI 文案中不再使用 |
+| 主子 | （省略或用"你"） | 已从助手反馈池移除 |
+| 小宠 | 我 | 已从助手反馈池移除 |
+| 伴侣寄语 | 助手寄语 | 产品文案使用新称 |
+| Companion Layer | Assistant Layer | 架构讨论使用新称 |
+
+## 代码标识符
+
+以下标识符因历史原因仍存在于代码库中，将在后续独立重构会话中重命名：
+
+- `components/pet/`
+- `PetStage.vue`、`PetStatusBar.vue`
+- `usePetState.ts`
+- `pet.css`
+- `companion:feedback` WebSocket 消息类型
+- `?view=pet` 路由参数
+
+在该重构完成前，所有面向用户的文案和新文档均应使用**产品术语**，即使引用的代码路径仍包含旧名称。
diff --git a/docs/PRD_overview.md b/docs/PRD_overview.md
index cc97a59..2910a7f 100644
--- a/docs/PRD_overview.md
+++ b/docs/PRD_overview.md
@@ -9,9 +9,9 @@
 - **Last Updated**: 2026-06-18
 - **Audience**: Product, Design, Engineering
 - **Related Docs**:
-  - [`README.md`](file:///d:/character_design/NeoCompanion/README.md)
-  - [`docs/具体能力构思.md`](file:///d:/character_design/NeoCompanion/docs/具体能力构思.md)
-  - [`docs/WALLPAPER_STATUS_LAYER.md`](file:///d:/character_design/NeoCompanion/docs/WALLPAPER_STATUS_LAYER.md)
+  - [`README.md`](../README.md)
+  - [`docs/具体能力构思.md`](./具体能力构思.md)
+  - [`docs/WALLPAPER_STATUS_LAYER.md`](./WALLPAPER_STATUS_LAYER.md)
 
 ---
 
@@ -138,6 +138,8 @@ NeoCompanion 的长期能力分为四层：
 
 ## 6. Roadmap Framework
 
+> **Scope note**: v1 是当前正在实现的最小闭环；v2 与 v3 是后续规划方向，尚未全部交付。具体实现状态请对照 `docs/ARCHITECTURE.md` 中的 `(Planned)` / `(Partial)` 标注。
+
 ### 6.1 v1: 助手最小闭环 (Warm Companion Base)
 - **目标**：实现桌面常驻悬浮助手的基本 2D 精灵图形态、语音 TTS 播报。
 - **核心功能**：助手番茄钟、助手待办、天气碎碎念。
diff --git a/docs/TERM_MIGRATION_pet_to_assistant.md b/docs/TERM_MIGRATION_pet_to_assistant.md
index 9e72c6a..9b695bd 100644
--- a/docs/TERM_MIGRATION_pet_to_assistant.md
+++ b/docs/TERM_MIGRATION_pet_to_assistant.md
@@ -6,6 +6,12 @@
 
 原则：**一次性全面迁移，不留混合术语**。
 
+## 当前状态
+
+- **产品文案（文档与 UI 文案）**：已基本完成迁移，但在部分历史文档和反馈池中仍有个别遗留，正在逐次清理。
+- **代码标识符**：尚未执行批量重命名。源码中仍保留 `pet`、`companion`、`PetStage`、`usePetState`、`pet.css`、`components/pet/` 等旧标识符。这些属于后续独立重构范围，不在文档优化会话中处理。
+- **WebSocket 消息类型**：`companion:feedback` 仍用于向后兼容，计划在未来版本中评估是否改为 `assistant:feedback`。
+
 ---
 
 ## 一、产品文案迁移（文档 + UI）
diff --git a/docs/TESTING.md b/docs/TESTING.md
new file mode 100644
index 0000000..4314362
--- /dev/null
+++ b/docs/TESTING.md
@@ -0,0 +1,84 @@
+# 测试说明
+
+NeoCompanion 使用 [Vitest](https://vitest.dev/) 进行单元测试和集成测试。本文档介绍如何运行测试以及如何编写新测试。
+
+## 运行测试
+
+```bash
+# 运行所有包的测试
+pnpm test
+
+# 运行指定包的测试
+pnpm --filter @neo-companion/server-local test
+pnpm --filter @neo-companion/ai test
+pnpm --filter @neo-companion/db test
+pnpm --filter @neo-companion/tts test
+
+# 仅运行桌面端测试
+pnpm --filter @neo-companion/desktop test
+```
+
+## 测试位置
+
+| 包 | 测试文件 | 说明 |
+|----|---------|------|
+| `packages/ai` | `src/ai.test.ts` | DeepSeek 适配器测试 |
+| `packages/db` | `src/db.test.ts` | SQLite store 测试 |
+| `packages/tts` | `src/tts.test.ts` | MiMo TTS 适配器测试 |
+| `packages/server-local` | `src/tests/app.test.ts`、`src/tests/hook.test.ts` | Fastify 集成测试 |
+| `apps/desktop` | `tests/markdown-roundtrip.test.ts` | Markdown 编辑器往返语料测试 |
+
+## 桌面端测试
+
+桌面端测试在 `apps/desktop/vitest.config.ts` 配置的 `jsdom` 环境中运行。
+
+### Markdown 往返测试
+
+`apps/desktop/tests/markdown-roundtrip.test.ts` 验证 `src/components/markdown-editor/editor/markdownCodec.ts` 中自定义的 ProseMirror-to-Markdown 序列化器。
+
+- **supported 语法夹具**（`tests/fixtures/markdown-corpus/supported/`）要求*语义级*往返：`parse → serialize → parse` 得到相同文档树。
+- **preserved 语法夹具**（`tests/fixtures/markdown-corpus/preserved/`）要求*字节级*往返：序列化器不能改动原始 Markdown。
+
+添加新夹具：
+
+1. 在 `supported/` 或 `preserved/` 目录创建 `.md` 文件。
+2. 运行 `pnpm --filter @neo-companion/desktop test`。
+3. 若是 preserved 构造，确保 `roundTripMarkdown(source).trim() === source.trim()`。
+
+## server-local 集成测试
+
+server-local 测试使用依赖注入，避免访问真实外部 API 或文件系统。
+
+示例模式（来自 `packages/server-local/src/tests/app.test.ts`）：
+
+```typescript
+import { createDatabase } from "@neo-companion/db";
+import { createApp } from "../app";
+
+const app = await createApp({
+  database: createDatabase(":memory:"),
+  startBackground: false,
+  aiStream: async function* () { yield "模拟回复"; },
+  ttsSpeak: async () => ({ audioUrl: "...", format: "mp3", provider: "mimo", cached: false }),
+  weather: async () => ({ city: "Beijing", temperatureC: 20, precipitationChance: 0, text: "..." })
+});
+```
+
+要点：
+
+- 传入 `database: createDatabase(":memory:")`，避免触碰生产数据库。
+- 传入 `startBackground: false`，关闭 30 秒窗口轮询定时器。
+- mock `aiStream`、`ttsSpeak`、`weather`，保证测试快速且确定性高。
+- 使用 `app.inject({ method, url, payload })` 进行 HTTP 断言。
+
+## 编写新测试
+
+1. 将测试文件放在被测模块旁边，或包内的 `tests/` 目录。
+2. 使用 `vitest` 的 `describe`/`it`。
+3. 推荐 Arrange-Act-Assert 结构。
+4. 涉及数据库或 sidecar 的测试，使用上文依赖注入模式。
+5. 提交前运行 `pnpm test`。
+
+## 持续集成
+
+`ci-check.yml` 工作流会在每个针对 `main` 的 Pull Request 上运行 `pnpm typecheck` 和 `pnpm test`。
diff --git a/docs/TODO_INVENTORY.md b/docs/TODO_INVENTORY.md
new file mode 100644
index 0000000..0df2e83
--- /dev/null
+++ b/docs/TODO_INVENTORY.md
@@ -0,0 +1,49 @@
+# 已知的文档与代码不一致 TODO 清单
+
+本文档跟踪源码中表示文档/预期功能与当前实现存在差距的 TODO 注释。在每次文档维护 pass 中手动更新。
+
+## UI 组件
+
+### `apps/desktop/src/components/panel/cards/WeeklyFocusCard.vue`
+
+- **行号**：约 42
+- **TODO**：`<!-- TODO: 接入真实数据 -->`
+- **影响**：周专注总结卡展示硬编码的柱状图和"12h 40min"总量，不反映 SQLite 中的真实专注记录。
+- **计划阶段**：v1.x 完善或 v2
+
+### `apps/desktop/src/components/panel/cards/DiaryCard.vue`
+
+- **行号**：约 3
+- **TODO**：`// TODO: 接入真实数据`
+- **影响**：日记卡展示静态占位内容，未从专注/任务数据生成或加载真实日报。
+- **计划阶段**：v1.x 完善或 v2
+
+### `apps/desktop/src/components/panel/TopNav.vue`
+
+- **行号**：约 5、约 12
+- **TODOs**：
+  - `// TODO: Phase 2 -- use for dynamic avatar state`
+  - `// TODO: Phase 2 -- global search feature`
+- **影响**：顶部导航接受 `petState` prop 并声明了 search emit，但动态头像状态和全局搜索均未实现。
+- **计划阶段**：v2
+
+## 设置
+
+### `apps/desktop/src/components/settings/sections/ModelSection.vue`
+
+- **行号**：约 53
+- **TODO**：`// TODO: Phase 2 -- 在 Rust 侧校验 URL scheme 为 https 且禁止 loopback/私有地址，防止 SSRF`
+- **影响**：模型设置中输入的自定义 API 端点 URL 尚未在 Rust 侧进行 SSRF 校验。
+- **计划阶段**：v2
+
+## 知识工作空间
+
+- **文件**：`apps/desktop/src/composables/useKnowledgeMock.ts`
+- **影响**：整个知识工作空间（项目、笔记、看板、任务）目前为前端 mock 数据。真正的后端端点、SQLite 存储、FTS5 全文检索和 `sqlite-vec` 向量检索计划在 v2 实现。
+- **另见**：`docs/ARCHITECTURE.md` §1.2 Document Scope
+
+## 如何更新本清单
+
+1. 在提交文档 PR 前运行 `./scripts/verify-docs.sh`。
+2. TODO 解决后，从本文件移除对应条目，并更新 `CHANGELOG.md`。
+3. 新增文档与代码不一致的 TODO 时，按文件路径、行号、影响补充到此处。
diff --git a/docs/TTS_SETUP.md b/docs/TTS_SETUP.md
new file mode 100644
index 0000000..256288b
--- /dev/null
+++ b/docs/TTS_SETUP.md
@@ -0,0 +1,83 @@
+# TTS 配置指南
+
+NeoCompanion 使用[小米 MiMo TTS](https://www.mimoai.com/) 作为助手语音反馈引擎。本文档说明如何配置。
+
+## 需要准备的内容
+
+1. MiMo TTS API key
+2. MiMo TTS 服务端点 base URL
+3. （可选）偏好的音色名称
+
+## 环境变量
+
+在根目录 `.env` 文件中添加：
+
+```bash
+MIMO_API_KEY=你的-mimo-api-key
+MIMO_TTS_BASE_URL=https://api.mimoai.com/v1/tts   # 示例；请使用控制台提供的实际地址
+MIMO_TTS_VOICE=茉莉
+```
+
+| 变量 | 是否必填 | 默认值 | 说明 |
+|------|----------|--------|------|
+| `MIMO_API_KEY` | 是 | — | MiMo TTS API key |
+| `MIMO_TTS_BASE_URL` | 是 | — | MiMo TTS HTTP 端点 base URL |
+| `MIMO_TTS_MODEL` | 否 | `mimo-v2.5-tts` | TTS 模型标识 |
+| `MIMO_TTS_VOICE` | 否 | `茉莉` | 音色名称 |
+
+## 获取凭证
+
+1. 登录小米 MiMo TTS 控制台。
+2. 在开发者/设置页面创建或复制 API key。
+3. 从 API 文档中复制对应区域/套餐的端点 URL。
+4. 将两项填入 `.env`。
+
+## 测试 TTS
+
+配置好 `.env` 后启动应用：
+
+```bash
+pnpm dev:tauri
+```
+
+然后触发一次专注时段结束，或直接调用 TTS 端点：
+
+```bash
+curl -X POST http://127.0.0.1:10103/api/tts/speak \
+  -H "Content-Type: application/json" \
+  -d '{"text":"你好，NeoCompanion 已准备就绪。"}'
+```
+
+配置正确时，响应会包含 base64 编码的音频 URL：
+
+```json
+{
+  "audioUrl": "data:audio/mp3;base64,...",
+  "format": "mp3",
+  "provider": "mimo",
+  "cached": false
+}
+```
+
+## 故障排查
+
+### `Missing MIMO_API_KEY`
+
+`.env` 中未设置 `MIMO_API_KEY`。添加你的 API key 并重启 sidecar。
+
+### `Missing MIMO_TTS_BASE_URL`
+
+`.env` 中未设置 `MIMO_TTS_BASE_URL`。将控制台提供的端点 URL 填入 `.env` 并重启 sidecar。
+
+### `MiMo TTS request failed: 401`
+
+API key 无效或已过期。请在 MiMo 控制台中核对并更新 `.env`。
+
+### `MiMo TTS request failed: 4xx/5xx`
+
+- 检查 `MIMO_TTS_BASE_URL` 是否正确，是否包含端点要求的完整路径。
+- 确认所选模型和音色在你的套餐中可用。
+
+## 降级行为
+
+TTS 失败时，助手仍会在 UI 中显示反馈文本。TTS 被视为增强体验，不是核心功能的硬依赖。
diff --git a/docs/superpowers/plans/2026-06-13-github-actions.md b/docs/superpowers/plans/2026-06-13-github-actions.md
index 075451e..6c25265 100644
--- a/docs/superpowers/plans/2026-06-13-github-actions.md
+++ b/docs/superpowers/plans/2026-06-13-github-actions.md
@@ -1,6 +1,8 @@
 # GitHub Actions CI/CD Implementation Plan
 
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **Status: IMPLEMENTED** — The workflows described in this document have been deployed to `.github/workflows/` and verified. This document is kept as a historical implementation record.
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
 
 **Goal:** Configure GitHub Actions for NeoCompanion — PR quality gate, Tauri cross-platform build verification, and tag-triggered release publishing.
 
@@ -31,7 +33,7 @@ No existing files are modified except `tauri.conf.json` (bundle config). All thr
 **Files:**
 - Create: `.github/workflows/ci-check.yml`
 
-- [ ] **Step 1: Write ci-check.yml**
+- [x] **Step 1: Write ci-check.yml**
 
 ```yaml
 name: CI Check
@@ -62,7 +64,7 @@ jobs:
       - run: pnpm test
 ```
 
-- [ ] **Step 2: Commit**
+- [x] **Step 2: Commit**
 
 ```bash
 git add .github/workflows/ci-check.yml
@@ -76,7 +78,7 @@ git commit -m "ci: add PR quality gate workflow (typecheck + test)"
 **Files:**
 - Create: `.github/workflows/ci-build.yml`
 
-- [ ] **Step 1: Write ci-build.yml**
+- [x] **Step 1: Write ci-build.yml**
 
 ```yaml
 name: CI Build
@@ -145,7 +147,7 @@ jobs:
           retention-days: 7
 ```
 
-- [ ] **Step 2: Commit**
+- [x] **Step 2: Commit**
 
 ```bash
 git add .github/workflows/ci-build.yml
@@ -159,7 +161,7 @@ git commit -m "ci: add PR build verification workflow (Tauri, 3 platforms)"
 **Files:**
 - Create: `.github/workflows/release.yml`
 
-- [ ] **Step 1: Write release.yml**
+- [x] **Step 1: Write release.yml**
 
 ```yaml
 name: Release
@@ -227,7 +229,7 @@ jobs:
           args: ${{ matrix.args }}
 ```
 
-- [ ] **Step 2: Commit**
+- [x] **Step 2: Commit**
 
 ```bash
 git add .github/workflows/release.yml
@@ -243,7 +245,7 @@ git commit -m "ci: add tag-triggered release workflow (Tauri, 3 platforms)"
 
 The current `bundle.active` is `false` and `bundle.icon` is `[]`. Tauri's `tauri-action` requires bundling to be enabled and icons present for build to succeed.
 
-- [ ] **Step 1: Update tauri.conf.json bundle section**
+- [x] **Step 1: Update tauri.conf.json bundle section**
 
 Change the `bundle` section from:
 ```json
@@ -269,7 +271,7 @@ To:
 }
 ```
 
-- [ ] **Step 2: Verify icon files exist**
+- [x] **Step 2: Verify icon files exist**
 
 Run: `ls apps/desktop/src-tauri/icons/`
 
@@ -281,7 +283,7 @@ pnpm exec tauri icon
 
 This takes a source image and generates all required sizes. If no source image is available, create a placeholder 1024x1024 PNG first, then run the command.
 
-- [ ] **Step 3: Commit**
+- [x] **Step 3: Commit**
 
 ```bash
 git add apps/desktop/src-tauri/tauri.conf.json apps/desktop/src-tauri/icons/
@@ -292,7 +294,7 @@ git commit -m "feat: enable Tauri bundling and add app icons"
 
 ### Task 5: Verify and push
 
-- [ ] **Step 1: Verify all workflow files are valid YAML**
+- [x] **Step 1: Verify all workflow files are valid YAML**
 
 Visually inspect each file for indentation and syntax. Key things to check:
 - `on:` triggers are correct (PR → main, tag v*)
@@ -300,23 +302,23 @@ Visually inspect each file for indentation and syntax. Key things to check:
 - All action versions are pinned (`@v4`, `@v2`, `@v0`)
 - `GITHUB_TOKEN` is referenced correctly in release.yml
 
-- [ ] **Step 2: Push all commits**
+- [x] **Step 2: Push all commits**
 
 ```bash
 git push origin main
 ```
 
-- [ ] **Step 3: Verify in GitHub**
+- [x] **Step 3: Verify in GitHub**
 
 Open the repository on GitHub → Actions tab. Confirm all three workflows appear in the sidebar. They will not run until a PR is opened or a tag is pushed.
 
-- [ ] **Step 4: Create a test PR to verify ci-check and ci-build**
+- [x] **Step 4: Create a test PR to verify ci-check and ci-build**
 
 Create a branch, make a trivial change (e.g. add a comment to README), open a PR against main. Both `CI Check` and `CI Build` workflows should trigger. Verify:
 - `ci-check` passes typecheck + test
 - `ci-build` passes on at least one platform (Ubuntu is fastest)
 
-- [ ] **Step 5: (Optional) Test release with a pre-release tag**
+- [x] **Step 5: (Optional) Test release with a pre-release tag**
 
 ```bash
 git tag v0.0.1-test
diff --git "a/docs/\345\205\267\344\275\223\350\203\275\345\212\233\346\236\204\346\200\235.md" "b/docs/\345\205\267\344\275\223\350\203\275\345\212\233\346\236\204\346\200\235.md"
index 925110e..f655d85 100644
--- "a/docs/\345\205\267\344\275\223\350\203\275\345\212\233\346\236\204\346\200\235.md"
+++ "b/docs/\345\205\267\344\275\223\350\203\275\345\212\233\346\236\204\346\200\235.md"
@@ -187,7 +187,7 @@ NeoCompanion 不把复杂跨应用自动执行作为产品主轴，而是围绕
 - **自定义状态定义**：外部推送 of JSON 结构可包含：
   - `status_type`: 状态类型（如：成功、警告、严重错误、日常通知）。
   - `message`: 具体消息文本。
-  - `pet_action`: 期望助手做出的指定动作/表情编号。
+  - `assistant_action`: 期望助手做出的指定动作/表情编号。
   - `tts_voice`: 是否开启语音反馈，以及指定的语音文案。
 
 ### 5.2 典型自定义 Hook 实例
@@ -243,7 +243,7 @@ Hook 是独立的外部状态入口，不绑定任何特定 Agent 或 CLI。外
 
 ## 6. 阶段演进路线 (Roadmap)
 
-### 6.1 Phase 1: 温暖的助手 (Warm Desk-Pet Base)
+### 6.1 Phase 1: 温暖的助手基础
 - **目标**：实现桌面悬浮助手的 2D 精灵图 动态展示、可爱的语音 TTS 反馈。
 - **功能**：落地助手番茄钟、助手 Todo 小账本、日常天气播报和记录日记。
 - **感知**：完成基本的窗口活跃度检测，驱动助手对“专注/分心”做出语音和表情互动。
diff --git a/packages/tts/src/index.ts b/packages/tts/src/index.ts
index 54b5eed..64e7a81 100644
--- a/packages/tts/src/index.ts
+++ b/packages/tts/src/index.ts
@@ -43,7 +43,7 @@ export async function speakWithMimo(text: string, styleInstruction?: string, opt
 
   const endpoint = options.baseUrl ?? process.env.MIMO_TTS_BASE_URL;
   if (!endpoint) {
-    throw new Error("Missing MIMO_TTS_BASE_URL. Set it from the Xiaomi MiMo TTS console documentation before live TTS calls.");
+    throw new Error("Missing MIMO_TTS_BASE_URL. See docs/TTS_SETUP.md.");
   }
 
   const request = buildMimoTtsRequest(text, styleInstruction, options);
diff --git a/scripts/verify-docs.sh b/scripts/verify-docs.sh
new file mode 100644
index 0000000..1030169
--- /dev/null
+++ b/scripts/verify-docs.sh
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Documentation consistency verifier for NeoCompanion.
+# Run from the repository root.
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+ERRORS=0
+
+log_error() {
+  echo "❌ $1"
+  ERRORS=$((ERRORS + 1))
+}
+
+# 1. Required root files must exist.
+for file in LICENSE CLAUDE.md CONTRIBUTING.md CHANGELOG.md; do
+  if [[ ! -f "$file" ]]; then
+    log_error "Missing required file: $file"
+  fi
+done
+
+# 2. No Windows-absolute file:// links in markdown files.
+if grep -RniE 'file:///[a-zA-Z]:/' --include='*.md' --exclude-dir=node_modules .; then
+  log_error "Found Windows-absolute file:// links in markdown files (see above)"
+fi
+
+# 3. No stale product name "NeoAssistant" in markdown files.
+if grep -Rni 'NeoAssistant' --include='*.md' --exclude-dir=node_modules .; then
+  log_error "Found stale product name 'NeoAssistant' in markdown files (see above)"
+fi
+
+# 4. Deprecated user-facing terms should not appear outside migration/glossary docs.
+# "宠物" / "桌宠" / "主子" / "小宠" / "Desk-Pet" are allowed only in TERM_MIGRATION_pet_to_assistant.md and GLOSSARY.md.
+DEPRECATED_PATTERN='主子|小宠|桌宠|Desk-Pet'
+VIOLATIONS=$(grep -RniE "$DEPRECATED_PATTERN" --include='*.md' --exclude-dir=node_modules . | grep -v 'TERM_MIGRATION_pet_to_assistant.md' | grep -v 'GLOSSARY.md' || true)
+if [[ -n "$VIOLATIONS" ]]; then
+  echo "$VIOLATIONS"
+  log_error "Found deprecated user-facing terms in markdown files (see above)"
+fi
+
+# "宠物" is also deprecated, but the migration doc title contains it by design; allow that exact title.
+PET_VIOLATIONS=$(grep -Rni '宠物' --include='*.md' --exclude-dir=node_modules . | grep -v 'TERM_MIGRATION_pet_to_assistant.md' | grep -v 'GLOSSARY.md' | grep -v '术语迁移方案：pet → assistant' || true)
+if [[ -n "$PET_VIOLATIONS" ]]; then
+  echo "$PET_VIOLATIONS"
+  log_error "Found deprecated term '宠物' in markdown files (see above)"
+fi
+
+# 5. README must not claim FTS5 + sqlite-vec is already shipped.
+if grep -nE 'SQLite \(Drizzle ORM \+ FTS5\).*sqlite-vec' README.md; then
+  log_error "README claims FTS5 + sqlite-vec is shipped; it is currently planned, not implemented"
+fi
+
+# 6. TTS error message must reference the real setup doc.
+if grep -q 'Xiaomi MiMo TTS console documentation' packages/tts/src/index.ts; then
+  log_error "TTS error still references non-existent 'Xiaomi MiMo TTS console documentation'"
+fi
+
+if [[ "$ERRORS" -eq 0 ]]; then
+  echo "✅ Documentation verification passed."
+  exit 0
+else
+  echo ""
+  echo "Found $ERRORS documentation issue(s). Please fix them."
+  exit 1
+fi