| Goal | Primary files |
|---|---|
| Change shell layout/titlebar/panes | MainWindowView.swift, WindowChromeConfigurator.swift |
| Change sidebar/projects/chat selection | ProjectSidebarView.swift, AppModel.swift |
| Change runtime ownership/persistence | AppModel.swift |
| Add or interpret Pi RPC commands/events | PiRPCClient.swift, PiConversationModel.swift |
| Change transcript/composer/model picker | PiConversationView.swift |
| Change attachments | AttachmentSupport.swift |
| Change promotion safety/handoff | PromoteToProject.swift, AppModel.swift |
| Change Git/browser/plugins/archive panes | RightPaneView.swift, DiffPaneView.swift, BrowserPaneView.swift |
- Route asynchronous callbacks by
ConversationKey; never assume the selected chat owns incoming work. - Keep Pi as the execution/runtime boundary—do not scrape terminal output.
- Keep ephemeral expansion/hover/navigation presentation state out of persisted transcript models.
- Do not erase cached transcript while attempting live hydration or recovery.
- Treat Stop as server-side cancellation plus stale-event fencing, scoped to one runtime.
- Keep filesystem promotion writes derived, contained, non-overwriting, and retry-safe.
- Preserve deliberate native polish: mounted pane state, immediate hover response, focused composer behavior, and hand-tuned AppKit bridges.