用途：在 hive CLI 的 TUI 上做开发或改动，TUI 基于 Bubble Tea v2（charm.land/bubbletea/v2、bubbles/v2、lipgloss/v2）。界面不含业务逻辑，只调用 service 层与 internal 下的共享包；后者不得 import charm，否则 depguard 会使 lint 失败。
代码位置：cmd/hive/internal/tui 下有 model.go（Model、Update 循环、消息类型、键位路由）、model_handlers.go、model_render.go、keybindings.go、modal_coordinator.go、command_palette.go，以及 components、views、sourcepicker、testutil 等目录；cmd/hive/internal/styles 存放 lipgloss 样式与主题。
视图与键位：每个视图是 views 下独立包，拥有自己的 model、Update、View、SetSize 与消息类型，并通过小型 KeyResolver 接口解析键位（避免从视图 import tui）。ViewType 的 String() 值即配置中 cfg.Views.<View>.Keybindings 匹配的作用域名。用户可覆盖的键不能写成视图内的 if keyStr == "x"，需按步骤注册 action.Type 并运行 mise run generate:enums，添加默认 UserCommand、绑定默认视图配置、在 model_handlers.go 中分发；硬编码键仅限 ctrl+c、esc、tab、shift+tab 与关闭模态框，新默认键要写入 docs 中的键位文档。
模态框与异步：所有模态状态放在 ModalCoordinator 上（字段、UIState 值、按键处理器、Overlay 分支），不要放在视图里；破坏性操作使用 NewDangerousModal 要求输入动词确认。Update 不得阻塞，涉及 git、tmux、数据库或网络的操作用 tea.Cmd 返回消息；批量任务合并为单个完成消息，轮询用 tick 消息安排下一次。后台失败要记日志（预期或瞬时用 debug，配置问题用 warn），并显示降级状态。
测试与验证：通过公开接口测试，先 SetSize 再渲染；用金文件覆盖渲染输出，如 testutil.RequireGolden(t, testutil.StripANSI(view.View()))，注意固定主题与时间戳。更新金文件前须先查看 diff，命令形如 go test ./cmd/hive/internal/tui/views/review -run TestView_ListMode -update。不要断言外观细节。验证命令：go test ./cmd/hive/...、mise run lint、mise run cli:dev，需要真实 tmux 会话时用 mise run cli:container，端到端行为放在 Docker 集成测试（mise run cli:integration），不要在宿主机运行。