docs(redesign): add Logi reference spec and capture catalog

.gitignore

@@ -72,3 +72,6 @@ logs/
 # Local model / runtime payloads
 internal/
 .gstack/
+
+# Internal capture working set (do not commit raw screenshot batches)
+platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/raw-local/

platforms/macos/client/docs/redesign/00-glossary.md

@@ -0,0 +1,188 @@
+# AhaKey Studio 概念词汇表
+
+更新时间：2026-05-02
+状态：规范文档（所有 redesign 文档应以本文为准）
+
+---
+
+## 原则
+
+本文档的目的是消除 AhaKey Studio 设计和开发过程中的概念混淆。每个词条给出：
+- **定义**：这个词指什么
+- **不要混淆**：容易和哪些词混用
+- **用户可见文案**：UI 里应该用什么词
+
+---
+
+## 一、进程与运行时
+
+### AhaKey Studio
+**定义：** 用户打开的主 macOS 应用程序。负责配置编辑、按键映射写入、OLED 上传、UI 展示。
+
+**用户可见文案：** "AhaKey Studio"
+
+---
+
+### ahakeyconfig-agent（后台守护进程）
+**定义：** 一个独立的后台进程（macOS LaunchAgent），由 AhaKey Studio 安装和管理。负责监听 Claude/Cursor/Codex 的 Hook 事件，通过 BLE 向键盘发送灯效状态、读取拨杆位置。用户不直接操作它。
+
+**不要混淆：**
+- 不要叫"Agent 模式"——这不是一种使用模式，是一个后台进程
+- 不要叫"AI Agent"——它不是 AI，是一个状态桥接进程
+- 不要在 UI 里暴露"ahakeyconfig-agent"这个技术名称
+
+**用户可见文案：** "后台服务"或"状态同步服务"（如果必须提及）
+
+---
+
+### AI 工具 / AI 平台（Claude Code / Cursor / Codex 等）
+**定义：** 用户在电脑上运行的 AI 编程工具。AhaKey 通过 Hook 机制感知这些工具的状态，并把状态映射到键盘灯效和按键行为。
+
+**不要混淆：**
+- 不要叫"Agent"——Claude Code / Cursor 本身不是 AhaKey 的 Agent
+- 不要叫"模式"——这是"平台"或"工具上下文"
+
+**用户可见文案：** "Claude Code"、"Cursor"、"Codex"（直接用产品名）
+
+---
+
+### 通用智能体（Hermes / OpenClaw 等）
+**定义：** 用户本地运行的通用 AI Agent 运行时，不绑定特定 IDE。可能同时运行多个实例，通过 app id / port 区分。
+
+**不要混淆：**
+- 和 ahakeyconfig-agent（后台守护进程）是完全不同的东西
+- 和 Claude Code / Cursor（IDE 工具）也不同——通用智能体没有固定的 Hook 协议
+
+**用户可见文案：** "本地 Agent"（作为类别名），具体实例用产品名（"Hermes"、"OpenClaw"）
+
+---
+
+## 二、BLE 连接
+
+### BLE 连接持有方
+**定义：** CoreBluetooth 限制同一时刻只能有一个进程持有与键盘的 GATT 连接。持有方可以是 AhaKey Studio（主 App）或 ahakeyconfig-agent（后台守护进程）。
+
+**不要混淆：**
+- 不要叫"App 模式 / Agent 模式"——这不是模式，是底层资源的持有状态
+- 不要把这个概念暴露给用户——用户不需要知道"谁持有 BLE"
+
+**用户可见文案：** 不直接暴露。翻译成用户能理解的两种状态（见下）
+
+---
+
+### 配置模式（App 持有 BLE）
+**定义：** AhaKey Studio 持有 BLE 连接，可以向键盘写入配置。此时后台守护进程断开，灯效不跟随 AI 工具状态。
+
+**触发：** 用户点击"编辑配置"按钮
+
+**用户可见文案：** "配置中"（顶栏 chip）
+
+---
+
+### 运行模式（后台守护进程持有 BLE）
+**定义：** 后台守护进程持有 BLE 连接，灯效跟随 AI 工具状态，拨杆生效。此时 AhaKey Studio 无法向键盘发送 BLE 命令。
+
+**触发：** 用户点击"完成配置"/ App 启动默认状态
+
+**用户可见文案：** "运行中"（顶栏 chip）
+
+---
+
+## 三、配置状态
+
+### 草稿（Draft）
+**定义：** 用户在 AhaKey Studio 里正在编辑的配置，存储在本地，尚未写入键盘。草稿在 App 关闭后持久化。
+
+**不要混淆：**
+- 不要叫"本地配置"——容易和"已同步配置"混淆
+- 不要叫"当前配置"——"当前"有歧义（是草稿还是设备上的？）
+
+**用户可见文案：** 不直接暴露"草稿"这个词。通过"未同步改动 N 项"间接表达。
+
+---
+
+### 已同步配置（Last Synced）
+**定义：** 上一次成功写入键盘的配置快照，存储在本地。是 App 知道的"键盘应该是什么状态"。
+
+**不要混淆：**
+- 不等于"设备真实状态"——键盘可能在 App 不知情的情况下被其他工具修改
+- 不等于"草稿"——草稿是用户正在编辑的，已同步配置是上次写入的
+
+**用户可见文案：** 不直接暴露。通过"已同步"状态标注间接表达。
+
+---
+
+### 设备真实状态（Device Ground Truth）
+**定义：** 键盘此刻实际运行的配置。只有在 App 持有 BLE 且主动查询时才可知。运行模式下（后台守护进程持有 BLE）对 App 不可观测。
+
+**不要混淆：**
+- 不等于"已同步配置"——两者可能因为固件更新、其他工具写入等原因产生差异
+
+**用户可见文案：** 不直接暴露。仅在切换到配置模式时触发一次查询，差异通过 banner 提示。
+
+---
+
+## 四、平台与模式
+
+### 平台（Platform）
+**定义：** 用户当前使用的 AI 工具上下文，决定了键盘按键的行为映射。对应固件层的 Mode 0/1/2，但用户不需要知道 Mode 编号。
+
+**不要混淆：**
+- 不要叫"模式"——"模式"在 AhaKey 里有太多含义（固件 Mode、配置模式、运行模式）
+- 不要叫"场景"——太模糊
+
+**用户可见文案：** 直接用产品名（"Claude Code"、"Cursor"、"Codex"）
+
+---
+
+### 固件 Mode（Mode 0 / 1 / 2）
+**定义：** 键盘固件内部的工作档位，决定了按键发出的 HID 码。是技术实现细节，不是用户概念。
+
+**不要混淆：**
+- 不要在 UI 里暴露"Mode 0 / 1 / 2"——用平台名替代
+- 不要叫"模式"（在用户文案里）
+
+**用户可见文案：** 不暴露。内部映射：Mode 0 = Claude Code，Mode 1 = Cursor，Mode 2 = Codex（默认，可配置）
+
+---
+
+### Hook
+**定义：** 安装在 AI 工具（Claude Code / Cursor / Codex）里的脚本，在工具执行特定操作时触发，向后台守护进程发送状态事件。
+
+**用户可见文案：** "Hook"（技术用户可以理解），或"状态感知"（面向普通用户时）
+
+---
+
+## 五、操作
+
+### 同步（Sync）
+**定义：** 把草稿写入键盘的操作。需要 App 持有 BLE 连接。
+
+**用户可见文案：** "同步到键盘"（主按钮）
+
+---
+
+### 编辑配置
+**定义：** 切换到配置模式的操作（App 抢占 BLE）。
+
+**用户可见文案：** "编辑配置"（按钮）
+
+---
+
+### 完成配置
+**定义：** 切换回运行模式的操作（App 释放 BLE，后台守护进程重新连接）。可以选择同步后切换，也可以不同步直接切换。
+
+**用户可见文案：** "完成"或"同步并完成"（按钮，根据是否有未同步改动动态变化）
+
+---
+
+## 六、禁止使用的词
+
+| 禁止词 | 原因 | 替代词 |
+|--------|------|--------|
+| Agent 模式 | 混淆"后台守护进程"和"AI Agent"两个概念 | 运行模式 |
+| App 模式 | 不直观，用户不理解"App"在这里的含义 | 配置模式 |
+| 模式（单独使用） | 在 AhaKey 里有四种不同含义，必须加限定词 | 加限定词：固件 Mode / 配置模式 / 运行模式 / 平台 |
+| 当前配置 | 歧义：是草稿还是已同步？ | 草稿 / 已同步配置（明确区分） |
+| Agent 控制中 | 暴露了技术实现细节 | 运行中 |
+| 设备信息 · Agent | 把设备信息和 Agent 混在一起 | 设备信息（独立）/ 后台服务（独立） |

platforms/macos/client/docs/redesign/00-redesign-index.md

@@ -0,0 +1,54 @@
+# AhaKey Studio macOS — 重设计文档索引
+
+更新时间：2026-05-02
+
+## 目录定位
+
+本目录存放 AhaKey Studio macOS 客户端的 UI/UX 重设计过程中产生的**决策文档、设计规范和架构思考**。
+
+与 `docs/` 根目录下的文档的区别：
+- 根目录文档（`ahakey-native-director-brief.md`、`02-ux-blueprint.md`）是**当前已落地实现的规范**
+- 本目录文档是**正在演进中的重设计方向**，经过审批后会合并或替换根目录文档
+
+## 设计参考基准
+
+| 参考产品 | 借鉴维度 | 不借鉴维度 |
+|---------|---------|----------|
+| Logi Options+ | 首页设备 hero、信息架构分层、Settings 层级、右上角操作区 | 多设备生态复杂度、Flow 跨设备功能 |
+| Typeless | 侧栏克制、试用卡样式、权限引导优雅度 | 仪表盘指标、历史记录页 |
+| Via / QMK Configurator | 画布点击配置交互、按键映射 UX | 工程师向的信息密度 |
+
+## 文档列表
+
+| 文件 | 内容 | 状态 |
+|------|------|------|
+| [00-glossary.md](./00-glossary.md) | **概念词汇表（所有文档的用词基准）** | 规范 |
+| [01-home-page.md](./01-home-page.md) | 首页（设备 Hero 页）重设计规范 | 草稿 |
+| [02-device-studio-page.md](./02-device-studio-page.md) | 设备配置页（Studio）重设计规范 | 草稿 |
+| [03-ux-state-machine.md](./03-ux-state-machine.md) | UX 状态机：连接/控制权/草稿同步三层状态 | 草稿 |
+| [04-navigation-architecture.md](./04-navigation-architecture.md) | 全局导航架构与页面拆分方案 | 待写 |
+| [04-settings-hierarchy.md](./04-settings-hierarchy.md) | Settings 面板层级规范 | 待写 |
+| [05-voice-page.md](./05-voice-page.md) | 语音设置页重设计规范 | 待写 |
+| [06-agent-page.md](./06-agent-page.md) | Agent 控制台页重设计规范 | 待写 |
+| [logi-options-plus-reference-spec/09-web-electron-prototype-spec.md](./logi-options-plus-reference-spec/09-web-electron-prototype-spec.md) | **下一轮 Web / Electron 原型交付 spec** | 草稿 |
+| [logi-options-plus-reference-spec/10-inspector-content-spec.md](./logi-options-plus-reference-spec/10-inspector-content-spec.md) | **Inspector 逐部件内容边界与信息披露层次** | 草稿 |
+
+## 专题目录
+
+| 目录 | 内容 | 状态 |
+|------|------|------|
+| [logi-options-plus-reference-spec/](./logi-options-plus-reference-spec/00-index.md) | 以 Logi Options+ 为高保真参考样本的前台壳重构专题 spec | 草稿 |
+
+## 下一轮执行口径
+
+截至 2026-05-03，下一轮优先做 **Web 前端原型**，必要时再用薄 Electron 壳包装给合作者体验；不在本轮完整构建 macOS 桌面应用。SwiftUI 拆分方案保留为后续原生迁移参考。
+
+## 核心设计判断（持续更新）
+
+1. **首页是设备选择器，不是功能入口。** 用户打开 App 的第一个问题是"我要配置哪个设备"，而不是"我要用哪个功能"。即使当前只有一个设备，首页也应该以设备 hero 为中心，为生态扩展预留结构。
+
+2. **三条产品主线必须分离。** 配置主线（键盘编辑）、状态反馈主线（Agent/Hook/灯效）、控制权主线（App vs Agent 蓝牙占用）不能混在同一个页面。每个导航目的地只回答一个问题。
+
+3. **Inspector 只做属性编辑。** 语音配置、Agent 状态、权限管理不属于 Inspector 的职责范围，应该迁移到独立页面。Inspector 的职责是：当前选中硬件部件的属性编辑面板。
+
+4. **Settings 是元操作的容器。** 只有"不属于任何具体功能页面、但影响全局行为"的操作才进 Settings。具体功能的配置（语音预设、Agent 选择）留在对应功能页面。