# TUI first-pass design The terminal user interface is a separate `efo-tui` binary over `lib_efo`. It does not replace the `efo` CLI, invent another persistence path, or make the library depend on terminal rendering. The CLI remains the complete, scriptable interface and the reference recovery surface. ## First checkpoint The first checkpoint is deliberately read-only. It must make a repository repository easy to understand before interactive mutations are introduced: - open the repository rooted at the current directory; - show HEAD, staged state, worktree state, and entity totals without relying on colour or icons; - browse every entity collection and inspect an entity's stable UUID, description, and serialized details; - explain all active keys in an in-application help overlay; - reload state from disk without restarting; and - leave the terminal usable after normal exit, an application error, or a panic. Unsupported repository versions receive an actionable error. Repository discovery above the current directory and mutating actions are explicitly outside this checkpoint. ## Interaction contract The application has three focus areas: collection list, entity list, and details. The focused area is named in text and visually emphasized. | Key | Action | | --- | --- | | `Tab`, `Shift-Tab` | Move focus forward or backward | | arrows, `h`/`j`/`k`/`l` | Navigate focus and selected rows | | `?` | Toggle contextual help | | `r` | Reload repository state | | `q`, `Esc` | Close help first, then quit | Every essential state is expressed in words. Colour may reinforce meaning but is never the only signal. Borders and ordinary Unicode are the baseline; Nerd Font glyphs are optional decoration, never controls or status vocabulary. Layouts must degrade to a useful compact message in small terminals, and text must be clipped safely rather than wrapped into neighbouring panels. ## Architecture ```text efo-tui input/render loop │ ▼ pure application state and navigation │ ▼ lib_efo::workspace::Workspace ``` The binary owns terminal setup, key mapping, view state, and rendering. Pure state transitions and rendering through Ratatui's test backend are unit tested. `lib_efo` continues to own repository validation and all future mutations. A terminal guard must enter raw mode and the alternate screen only after setup succeeds, and undo both in `Drop`. A panic hook restores the terminal before delegating to the previous hook. No command changes the process working directory. ## Later interactive mutations Write operations require a second design checkpoint. The first candidates are stage/unstage, restore, and commit because Phase 4 already makes them atomic and reversible. Before exposure, each action needs: - an explicit preview of the affected layer and entities; - confirmation for discarding or history-changing operations; - success text naming the recovery command; - lock and interrupted-transaction guidance; and - integration tests proving the TUI invokes the same library operation as the CLI. Entity editing, recovery, and future pruning remain CLI-only until their interactive failure and recovery flows are equally clear. ## Acceptance gate The checkpoint is complete when `efo-tui --help` is self-documenting, startup and repository failures are actionable, navigation and rendering have tests, the terminal lifecycle is guarded, and the full workspace passes formatting, tests, strict Clippy, and release builds with default and portable features. ## Running the first checkpoint Install both interfaces, then start the browser from a repository or name its path explicitly: ```bash cargo install --locked --path bin_efo cargo install --locked --path tui_efo efo-tui # or: efo-tui --repository /path/to/world ``` The header reports HEAD, staged and unstaged state, and any active writer lock. The browser reloads only when `r` is pressed; it never writes or silently refreshes underneath a selection. Use `efo status`, `efo lock status`, or `efo recover` when its diagnostic recommends that CLI recovery path.