Docs/quality improvement

.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

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.

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.

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.*

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).

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.

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)

apps/desktop/src/composables/usePetState.ts

@@ -27,14 +27,14 @@ const feedbackPool: Record<CompanionState, string[]> = {
     "正在翻记忆的小本本……",
   ],
   warn: [
-    "主子，是不是该回来啦？",
+    "是不是该回来啦？",
     "哎……说好要专心的呢~",
     "别走远啦，我等你回来！",
     "嘿，该回来干活了哦~",
   ],
   sleepy: [
     "夜深了，我们也该休息了吧？",
-    "好困……小宠的眼皮都打架了……",
+    "好困……眼皮都打架了……",
     "今天辛苦了，早点休息好不好？",
     "已经好晚了，明天再来也行的~",
   ],