oirge/mineradio/readme-reference

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

1. 文档给出路径时，用 git ls-files -- <path> 验证路径存在。
2. 文档给出脚本时，核对根 package.json、领域 package.json 和 vite.config.* / wrangler.*。
3. 文档给出入口时，先看该文件的 imports 和 export，再沿一层调用关系，不要直接扫描整个目录。
4. 文档给出 API 时，核对 sync-server/src/app.ts、worker/index.ts、api/ 或对应 bridge。
5. 文档给出 provider 能力时，先看 src/services/onlineMusic/omni.ts 和 src/types/onlineMusic.ts，再看 adapter/transport。
6. 代码与 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 改动误跑完整构建。