| name | readme-reference |
| description | Use when making code, workflow, testing, deployment, or documentation changes in this repository and you need targeted project-specific facts from README files before editing. Read only the relevant section, verify it against code, and repair stale documentation when the task includes documentation. |
README Reference
README 是导航线索，不是代码真相。先按任务读取相关小片段，再用 tracked paths、imports、package scripts 和实现文件确认；发现旧路径时顺手修正文档或明确标记它。
Source selection
- 产品能力、脚本、Electron、Vercel、API：
README.md（根 README 只读，不在本任务中修改）。
src/ 入口、模块职责、app-level 装配：src/README.md。- visualizer 共享入口、模式、背景、性能约定：
src/components/visualizer/README.md。
- Partita layout、sticky punctuation、预热和缓存：
src/components/visualizer/partita/README.md。
- 在线歌曲 Omni/provider 边界：
src/services/onlineMusic/README.md + src/services/onlineMusic/omni.ts。
- 同步 API、Node/Cloudflare/Docker 部署：
sync-server/README.md。
- Docker Web stack、端口、环境变量和 smoke test：
deploy/docker/README.md。
- Linux 便携包和 Electron 图形模式：
packaging/linux/README-LINUX.txt + electron/main.cjs。
- Cappella 内置头像/表情资源：相邻
cappella/avatar/README.md 或 emo/README.md，只在涉及这些资源时读取。
test/manual/**/README.md 属于测试/联调文档；按“排除测试文件”的任务要求不要把它们当作生产架构依据。
Targeted reading
先用 rg -n 搜标题、脚本名、当前符号或路径，再打开命中位置附近 20-80 行。不要为了保险全文读取长 README。
rg -n "components/app|services/|visualizer|scripts|部署|Node|Docker" src/README.md README.md
rg -n "VisualizerRenderer|registry|pendolo|sonnet|background" src/components/visualizer/README.md
rg -n "Omni|provider|lyrics|playback|catalog" src/services/onlineMusic/README.md
rg -n "Node|/health|/settings|/themes|compose" sync-server/README.md deploy/docker/README.md
Verification protocol
- 文档给出路径时，用
git ls-files -- <path> 验证路径存在。
- 文档给出脚本时，核对根
package.json、领域 package.json 和 vite.config.* / wrangler.*。
- 文档给出入口时，先看该文件的 imports 和 export，再沿一层调用关系，不要直接扫描整个目录。
- 文档给出 API 时，核对
sync-server/src/app.ts、worker/index.ts、api/ 或对应 bridge。
- 文档给出 provider 能力时，先看
src/services/onlineMusic/omni.ts 和 src/types/onlineMusic.ts，再看 adapter/transport。
- 代码与 README 冲突时，以代码为准，并在本次文档改动中更新对应说明。
Repository-specific traps
- 当前 app-level 目录是
src/components/app/*，旧的 components/app/views/*、SearchResultsOverlay、src/components/LocalMusicView.tsx、src/components/local/* 和 src/components/navidrome/* 不应作为新入口。
- Visualizer 模式由
src/components/visualizer/registry.tsx 从各模式 entry.tsx 发现；当前不能只按旧文档中的 classic/cadenza/partita 列表理解。
- 在线歌曲普通调用必须经过
src/services/onlineMusic/omni.ts；Navidrome 是独立 src/services/navidromeService.ts，不能仅凭“在线”一词混为一谈。
src/App.tsx 是历史大型编排文件；README 只提供入口关系，不代表新逻辑应继续写入其中。- Sync Server 的 Node engine 当前以
sync-server/package.json 和根 package.json 为准，不要复制旧的 Node 18 说明。
Editing rules
- 只更新与当前代码/部署状态有关的段落；保持 README 可搜索、短路径明确。
- 不要把完整源代码或大段接口响应复制进 README；给出第一入口和下一层即可。
- 保留所有
@note 注释原文，不翻译、不缩短、不删除。
- 文档任务的验证重点是路径、符号、命令、端口和配置值；不要为了 README 改动误跑完整构建。
