Device mono-repo

Device mono-repo 表示一个仓库同时承载硬件资料、固件、Web/desktop UI、docs/specs、测试工具或发布流程。它强调边界协调：硬件、firmware、UI 和文档互相影响，不应把仓库当作单一应用。

这个 Topic 的核心是设备级知识不能被某一个技术栈吞掉。硬件 variant、pin map、电源/保护策略、MCU firmware、host UI、Storybook、release artifact 和 docs-site 都可能是同一个产品事实的不同投影；项目快照必须把这些边界并列记录，避免后续 Agent 只按 package.json 或 Cargo.toml 处理（projects/loadlynx.md、projects/flux-purr.md）。

当 repo tree 中同时存在 firmware/hardware/docs/web/tools，且 README 或 docs 明确描述设备产品时使用。单独 driver crate 或纯 Web app 不应使用。

如果一个改动可能同时影响硬件说明、固件 target、Web 控制台、设备协议、发布包或用户文档，就应使用本 Topic。若仓库只是单个 embedded-hal driver、单个 STM32 demo、或纯 Web 管理台，没有设备资料和跨 surface 协调需求，则不应套用（projects/gc9d01-rs.md 属于 driver crate，不是 mono-repo 代表）。

• 文档是设备项目的 current truth，尤其是硬件 variant、pin map、保护策略和 UI 行为。
• MCU 操作入口应配置化，优先使用 mcu-agentd.toml，减少一次性 flash 脚本。
• Web UI/Storybook 是辅助验证面，不能替代硬件验证。
• release workflow 应按 artifact/surface 拆分，例如 firmware、web、docs。
• 项目快照应把“设备事实”和“软件入口”分开写：硬件 variant、接口、电源路径、保护策略属于 current truth；firmware/web/docs 只是消费这些事实的实现面（projects/mains-aegis.md、projects/isolappurr-usb-hub.md）。
• 当 UI 暴露硬件控制能力时，Storybook 或浏览器预览只能证明界面状态，不证明真实硬件安全；需要在 Risks 中保留硬件验证缺口和误操作风险（projects/flux-purr.md、projects/loadlynx.md）。

• projects/loadlynx.md：双 MCU + Web UI + shared protocol。
• projects/flux-purr.md：firmware + React console + hardware research/specs。
• projects/mains-aegis.md：UPS 设计文档、firmware、web management UI、docs-site。
• projects/isolappurr-usb-hub.md：硬件 variants、ESP32 firmware、Web UI。
• projects/flux-purr.md 展示 firmware、React console、hardware research/specs 如何共同定义一个设备；适合检查 Topic 是否覆盖 Web、firmware 和硬件研究三条线。
• projects/loadlynx.md 是双 MCU 分工的代表，能提醒 Agent 不要把 ESP32-S3 digital surface 与 STM32G431 analog surface 合并成一个模糊 firmware。

• 只从 package.json 或 Cargo.toml 推断项目，会漏掉硬件事实。
• UI 控制功能如果先于 safety docs，会增加误操作风险。
• firmware/web/docs release 不拆分，容易让一个 surface 掩盖另一个 surface 失败。
• 把 docs 当成附属物会让硬件事实丢失。设备 mono-repo 的文档通常是安全边界、variant 和操作限制的来源；修改 UI/firmware 前应回读 projects/mains-aegis.md 或对应项目快照里的 Evidence index。
• 把所有 artifact 绑进单一 release gate，会导致某个 surface 失败时难以定位责任；更稳妥的做法是按 firmware、web、docs 或 hardware package 分清构建与通知边界（projects/flux-purr.md）。

• projects/loadlynx.md
• projects/flux-purr.md
• projects/mains-aegis.md
• projects/isolappurr-usb-hub.md