Skip to content

docs/tui: rewrite Navigation section to match actual screens #309

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ooloth merged 6 commits into from
Jun 15, 2026
Merged

docs/tui: rewrite Navigation section to match actual screens #309

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6d4d6c6
docs/tui: rewrite Navigation section to match actual screens
ooloth Jun 11, 2026
9edec2c
Potential fix for pull request finding
ooloth Jun 15, 2026
75497c7
Potential fix for pull request finding
ooloth Jun 15, 2026
80148d7
Potential fix for pull request finding
ooloth Jun 15, 2026
8e3c90d
Potential fix for pull request finding
ooloth Jun 15, 2026
ad2b071
Potential fix for pull request finding
ooloth Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 45 additions & 45 deletions ui/tui/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ is mutated:
1. `key_to_action(app, key) -> Option<Action>` (`input.rs`) — maps a raw
key event to an `Action` variant. Universal keys (quit, help, back) are
handled first; the remainder delegates to a per-view function
(`home_keys` or `list_keys`). Returns `None` for unmapped keys.
(`unified_list_keys` or `merge_confirm_key`). Returns `None` for unmapped keys.
2. `App::update(action) -> Vec<Effect>` (`state.rs`) — applies the action
to app state and returns zero or more `Effect` values describing required
side effects (`OpenUrl`, `LaunchCi`, `Quit`).
Expand All @@ -46,7 +46,7 @@ is mutated:

1. Add a variant to `Action` in `state.rs`
2. Map one or more keys to it in the appropriate per-view function in
`input.rs` (`home_keys`, `list_keys`, or a new function for a new view)
`input.rs` (`unified_list_keys`, `merge_confirm_key`, or a new function for a new view)
3. Handle it in `App::update()` in `state.rs` — mutate state and/or return
one or more `Effect` values
4. If a new `Effect` variant is needed, add it to the enum in `state.rs`,
Expand Down Expand Up @@ -211,49 +211,49 @@ Rules of thumb:

## Navigation

Three levels. `Enter` drills in; `Esc` backs out one level.

**Home** — category preview tiles

| Key | Action |
| ---------- | -------------------- |
| h | left tile (or prev) |
| j | down tile (or next) |
| k | up tile (or prev) |
| l | right tile (or next) |
| Tab | next tile |
| Shift-Tab | prev tile |
| Enter | drill into category |
| ? | toggle help |
| q / Ctrl-C | quit |

**Category** — full-screen item list

| Key | Action |
| ---------- | ------------------------------- |
| h | up |
| j | down |
| k | up |
| l | down |
| Enter | open / drill into group |
| i | investigate (auto-routes by item type) |
| Esc | back to home |
| ? | toggle help |
| q / Ctrl-C | quit |

**Detail** — items within a group

| Key | Action |
| ---------- | ------------------------------- |
| h | up |
| j | down |
| k | up |
| l | down |
| Enter | open URL |
| i | investigate (auto-routes by item type) |
| Esc | back to category |
| ? | toggle help |
| q / Ctrl-C | quit |
One screen (`UnifiedList`) with an optional split detail pane. `Enter` opens the pane; `Esc` closes it.

**UnifiedList** — urgency-ranked flat list of all signals

| Key | Action |
| ---------- | ----------------------------------------------- |
| j / ↓ | next item |
| k / ↑ | prev item |
| l | expand group |
| h | collapse group |
| g g | move to top |
| G | move to bottom |
| Ctrl-d | page down |
| Ctrl-u | page up |
| Enter | open split detail pane (or no-op if already open) |
| Esc | close split detail pane (if open), otherwise clear filter |
| i | investigate (auto-routes by item type) |
| o | open URL in browser |
| N | open blank task creation form |
| s | open task status submenu (task or badged signal) |
| p | filter to PRs |
Comment on lines +231 to +233
| O | filter to issues |
| e | filter to errors |
| t | filter to tasks |
| a | clear filter |
Comment thread
Copilot marked this conversation as resolved.
| / | start query filter |
| r | refresh |
| ? | toggle help |
| q / Ctrl-C | quit |

**Split detail pane** — additional keys while the detail pane is open

| Key | Action |
| ---------- | ----------------------------------------------- |
| J | scroll detail down |
| K | scroll detail up |
| Tab | toggle between signal detail and session detail |
| Esc | close split detail pane |
| v | open review picker (PR only) |
| m | merge PR (PR only) |
| d | open PR diff submenu (PR only) |
| a | approve for agent (issue only; otherwise clears filter) |
| s | open task status submenu (task or badged signal) |

## Terminal cleanup

Expand Down
Loading