# src/tui2 KNOWLEDGE BASE
## OVERVIEW
Experimental Ratatui workspace shell behind `--tui-experimental`: vertical tab rail, workspace selector, workspace persistence, git worktree sidebar, placeholder Nexus tab. Execution/runtime truth still lives outside TUI2.
## STRUCTURE
```text
src/tui2/
├── mod.rs # Tui2App, event loop, tab rail, terminal/input bridge, runtime sink bridge
└── workspace.rs # WorkspaceState, workspace store, path input, worktree detection/rendering
```
## WHERE TO LOOK
| Launch path | `src/cli/mod.rs` | `--tui-experimental` selects `tui2::run_tui`. |
| TUI2 loop/render | `mod.rs` | Terminal setup, event select, tab navigation, footer, placeholder Nexus. |
| Workspace state | `workspace.rs` | Add/select/load workspace views and persistence. |
| Git worktrees | `workspace.rs::detect_worktrees` | Uses `git -C <path> worktree list --porcelain`. |
| Persistence | `workspace.rs::save_workspaces` | Writes `$MC_HOME/workspaces.json` through `persistence::atomic_write`. |
## CONVENTIONS
- TUI2 is display/input shell only; provider/session/tool execution stays in shared runtime.
- `workspaces.json` stores workspace paths, not secrets. Use atomic writes and create parent dir.
- Expand `~` and `~/...` for user-entered paths; validate path exists and is directory before storing.
- Keep git worktree detection best-effort. Non-git directory remains valid workspace with collapsed sidebar.
- Keep mouse/key handling local and explicit: q/Esc exits, Tab cycles tabs, workspace view consumes its keys first.
- Use ratatui-cheese widgets for workspace input/select/list state.
- Add focused tests before making workspace persistence or key handling more complex.
## ANTI-PATTERNS
- Do not serialize TUI2 tab/focus/render state into JSONL sessions or provider payloads.
- Do not start provider runs from TUI2 until wired through existing agent runner/worker contracts.
- Do not block draw/input loop on long git or filesystem scans.
- Do not store credentials or provider settings in `workspaces.json`.
- Do not duplicate stable Mission Control behavior here unless intentionally replacing it.