Keybindings: page-dependent shortcut listing and a way to change them

[santoshkumarradha]

What exists today

Every binding is hard-coded where it is used. 20 files in internal/tui3 handle keys directly, each surface with its own switch statement: the settings sheet (enter, space and esc on rows, arrows, typing-to-search, sheetKey in internal/tui3/settings.go), the approval card (1 allow once, 2 always, 3 deny, esc later, internal/session/answers.go:218-222), the model picker, the harness picker, hop, folder search, the rewind sheet. A grep for keybind or keymap or hotkey across internal/ and cmd/ finds no infrastructure at all: the only "shortcut" hits are comments about work-plan shortcuts.

Nothing lists what is pressable on the page you are on. No ? overlay exists anywhere (the "?" glyph in the TUI is the consent mark, not help), and the manual's key list is prose in docs/GUIDE.md, free to drift from the code. Nothing can be changed: a person on a non-QWERTY layout, on a keyboard without arrow keys, or colliding with their terminal or multiplexer has no lever but the source.

The collision class has already bitten: #1295's space-key bug (space activating a row instead of reaching the search box while search is live) is a binding colliding with typing, resolved per-surface in code. A keymap system is where that class of bug gets a name.

Proposal

1. Page-dependent listing: the ? overlay. Pressing ? on any page overlays that page's own shortcuts. This is the TUI standard (vim, fzf, lazygit, helix). Pages already own their key routing through the place router (pages.go's place.owns seam; placeSettings.owns reads it), so each place declares its keymap once, the ? overlay renders from that declaration, and the listing cannot drift from the handlers because it is the same table.
2. Changing them: a Keybindings group under General in /settings, nesting into the approved IA from /settings: search can't take spaces and isn't fuzzy, approval wording drifts across four vocabularies, and the project layer silently outranks the sheet #1295. One row per binding, grouped by page; the same cycle and edit grammar as every other row; overrides stored in the profile with defaults from the code declaration; conflict detection refusing two actions on one key on the same page; per-row reset; the effective binding shown, since a terminal can inject sequences that are facts rather than settings.
3. Text boxes never act. While a text box is live, printable keys type and never trigger actions, the same law the /settings: search can't take spaces and isn't fuzzy, approval wording drifts across four vocabularies, and the project layer silently outranks the sheet #1295 space-key fix gives the settings search.

Open questions

• Do the numbered card answers (1 / 2 / 3) remap, or stay fixed like vim counts?
• Keymap stacking when pages compose (a picker open over the composer): the declaration order should mirror place.owns.
• Chords: single keys first, a chord grammar later?

Related

• /settings: search can't take spaces and isn't fuzzy, approval wording drifts across four vocabularies, and the project layer silently outranks the sheet #1295: the settings DX issue (search, wording, permission wiring) whose approved hierarchy this nests under; the search-first front door in flight there changes what search finds, not what keys do.

—

_{Co-Authored-By: codeaf agentfield-bot@users.noreply.github.com}