UAT: TUI Hotkey Reference screen not implemented — spec requires a dedicated hotkey reference screen accessible via ? global hotkey #3042

Open
opened 2026-04-05 04:14:53 +00:00 by freemo · 1 comment
Owner

Metadata

  • Branch: feat/tui-hotkey-reference-screen
  • Commit Message: feat(tui): implement dedicated Hotkey Reference screen accessible via ? global hotkey
  • Milestone: v3.7.0
  • Parent Epic: #868

Description

The spec states: "The TUI provides a built-in hotkey reference screen that displays all available key bindings for the current context. This screen is accessible via a global hotkey (e.g., ?) and provides a quick and easy way for users to discover and learn the TUI's keyboard shortcuts."

Current behavior: The TUI has a HelpPanelOverlay widget (src/cleveragents/tui/widgets/help_panel_overlay.py) accessible via F1, which shows context-sensitive help text. However:

  1. The spec requires a dedicated hotkey reference screen accessible via ? — this is different from the F1 help panel
  2. The ? key is not bound in the TUI app (BINDINGS only has ctrl+q, f1, ctrl+t)
  3. The HelpPanelOverlay is a simple static overlay, not a dedicated full screen
  4. The help panel only shows a limited set of hotkeys for the current context — it does not show ALL available key bindings

Expected behavior per spec: A dedicated hotkey reference screen (or comprehensive overlay) should be accessible via ? that displays ALL available key bindings for the current context, providing a comprehensive keyboard shortcut reference.

Steps to reproduce:

  1. Launch the TUI: agents tui
  2. Press ?
  3. Nothing happens — no hotkey reference screen appears

Code locations:

  • src/cleveragents/tui/app.py lines 92–96: BINDINGS has ctrl+q, f1, ctrl+t — no ? binding
  • src/cleveragents/tui/widgets/help_panel_overlay.py: HelpPanelOverlay shows limited context help, not a full hotkey reference
  • src/cleveragents/tui/widgets/help_panel_overlay.py lines 26–56: Only 3 global items and 4–6 context items shown — not a comprehensive reference

Subtasks

  • Add ? key binding to CleverAgentsTuiApp.BINDINGS in src/cleveragents/tui/app.py
  • Implement action_hotkey_reference() method in the TUI app
  • Expand the hotkey reference to show ALL available key bindings (not just context-specific ones)
  • Consider creating a dedicated HotkeyReferenceScreen class or expanding HelpPanelOverlay
  • Write BDD scenarios in features/tui_hotkey_reference.feature

Definition of Done

  • ? key opens the hotkey reference screen/overlay
  • All available key bindings are displayed
  • BDD scenarios cover hotkey reference functionality
  • nox -e typecheck passes
  • nox -e unit_tests passes
  • All nox stages pass
  • Coverage >= 97%

This issue was filed by the UAT Testing agent (ca-uat-tester) as part of automated acceptance testing.


Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `feat/tui-hotkey-reference-screen` - **Commit Message**: `feat(tui): implement dedicated Hotkey Reference screen accessible via ? global hotkey` - **Milestone**: v3.7.0 - **Parent Epic**: #868 ## Description The spec states: "The TUI provides a built-in hotkey reference screen that displays all available key bindings for the current context. This screen is accessible via a global hotkey (e.g., `?`) and provides a quick and easy way for users to discover and learn the TUI's keyboard shortcuts." **Current behavior:** The TUI has a `HelpPanelOverlay` widget (`src/cleveragents/tui/widgets/help_panel_overlay.py`) accessible via `F1`, which shows context-sensitive help text. However: 1. The spec requires a dedicated hotkey reference screen accessible via `?` — this is different from the `F1` help panel 2. The `?` key is not bound in the TUI app (`BINDINGS` only has `ctrl+q`, `f1`, `ctrl+t`) 3. The `HelpPanelOverlay` is a simple static overlay, not a dedicated full screen 4. The help panel only shows a limited set of hotkeys for the current context — it does not show ALL available key bindings **Expected behavior per spec:** A dedicated hotkey reference screen (or comprehensive overlay) should be accessible via `?` that displays ALL available key bindings for the current context, providing a comprehensive keyboard shortcut reference. **Steps to reproduce:** 1. Launch the TUI: `agents tui` 2. Press `?` 3. Nothing happens — no hotkey reference screen appears **Code locations:** - `src/cleveragents/tui/app.py` lines 92–96: `BINDINGS` has `ctrl+q`, `f1`, `ctrl+t` — no `?` binding - `src/cleveragents/tui/widgets/help_panel_overlay.py`: `HelpPanelOverlay` shows limited context help, not a full hotkey reference - `src/cleveragents/tui/widgets/help_panel_overlay.py` lines 26–56: Only 3 global items and 4–6 context items shown — not a comprehensive reference ## Subtasks - [ ] Add `?` key binding to `CleverAgentsTuiApp.BINDINGS` in `src/cleveragents/tui/app.py` - [ ] Implement `action_hotkey_reference()` method in the TUI app - [ ] Expand the hotkey reference to show ALL available key bindings (not just context-specific ones) - [ ] Consider creating a dedicated `HotkeyReferenceScreen` class or expanding `HelpPanelOverlay` - [ ] Write BDD scenarios in `features/tui_hotkey_reference.feature` ## Definition of Done - [ ] `?` key opens the hotkey reference screen/overlay - [ ] All available key bindings are displayed - [ ] BDD scenarios cover hotkey reference functionality - [ ] `nox -e typecheck` passes - [ ] `nox -e unit_tests` passes - [ ] All nox stages pass - [ ] Coverage >= 97% --- This issue was filed by the UAT Testing agent (ca-uat-tester) as part of automated acceptance testing. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.7.0 milestone 2026-04-05 04:15:13 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Confirmed
  • MoSCoW: Should Have

Valid finding verified during batch triage.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
Reference
cleveragents/cleveragents-core#3042
No description provided.