UAT: Help panel title is wrong and missing required shortcut categories (Navigation, Actions, TUI-Specific) #1356

New issue

Open

opened 2026-04-02 16:58:03 +00:00 by freemo · 0 comments

freemo commented

2026-04-02 16:58:03 +00:00

Owner

Bug Report: [tui/help-panel] — Wrong title and missing spec-required shortcut categories

Severity Assessment

Impact: High. The help panel is the primary user reference for keyboard shortcuts. Missing entire categories (Navigation, Actions, TUI-Specific) and showing the wrong title means users cannot discover most of the app's keyboard shortcuts.
Likelihood: 100% reproducible — the content is hardcoded.
Priority: High

Location

File: src/cleveragents/tui/widgets/help_panel_overlay.py

Description

The spec (§10.2 Help Panel) defines the following requirements for the help panel content:

Title: Must be "Help & Keyboard Shortcuts"
Categories: Must include four sections: Global, Navigation, Actions, TUI-Specific
Global shortcuts must include: F1, Ctrl+Q, Ctrl+L, Ctrl+S, Ctrl+O
Navigation shortcuts must include: Tab, Shift+Tab, ↑/↓, PgUp/PgDn
Actions shortcuts must include: Enter, Esc, Ctrl+C, Ctrl+X, Ctrl+V
TUI-Specific shortcuts must include: Ctrl+T, Ctrl+W, Ctrl+Tab, Ctrl+Shift+Tab

Actual Behavior

Wrong title (render_help_panel() in help_panel_overlay.py, line 60):

lines = [f"Help: {context_name}", "", "Global"]

This produces "Help: Main Screen" instead of the required "Help & Keyboard Shortcuts".

Missing categories — the _CONTEXT_ITEMS dict only defines:

"Main Screen", "Slash Commands", "Reference Picker", "Shell Mode"

None of the spec-required categories (Navigation, Actions, TUI-Specific) exist.

Missing Global shortcuts — _GLOBAL_ITEMS only contains:

_GLOBAL_ITEMS = (
    ("ctrl+q", "Quit TUI immediately"),
    ("F1", "Toggle help panel"),
    ("escape", "Close current overlay / return to prompt"),
)

Missing: Ctrl+L (Lock screen), Ctrl+S (Save session), Ctrl+O (Open session)

Missing Navigation shortcuts — No Navigation section exists. Missing: Shift+Tab, ↑/↓, PgUp/PgDn

Missing Actions shortcuts — No Actions section exists. Missing: Ctrl+C, Ctrl+X, Ctrl+V

Missing TUI-Specific shortcuts — No TUI-Specific section exists. Missing: Ctrl+W, Ctrl+Shift+Tab

Missing two-column layout headers — The rendered output has no Key(s) / Description column headers.

Expected Behavior (from spec §10.2)

The rendered help panel should:

Show title "Help & Keyboard Shortcuts"
Have a Global section with: F1, Ctrl+Q, Ctrl+L, Ctrl+S, Ctrl+O
Have a Navigation section with: Tab, Shift+Tab, ↑/↓, PgUp/PgDn
Have an Actions section with: Enter, Esc, Ctrl+C, Ctrl+X, Ctrl+V
Have a TUI-Specific section with: Ctrl+T, Ctrl+W, Ctrl+Tab, Ctrl+Shift+Tab
Use a two-column layout with Key(s) and Description headers

Steps to Reproduce

from cleveragents.tui.widgets.help_panel_overlay import render_help_panel, _GLOBAL_ITEMS, _CONTEXT_ITEMS
print(render_help_panel("Main Screen"))
# Output shows "Help: Main Screen" (wrong title)
# No Navigation, Actions, or TUI-Specific sections
print([k for k, _ in _GLOBAL_ITEMS])
# ['ctrl+q', 'F1', 'escape'] — missing Ctrl+L, Ctrl+S, Ctrl+O
print(list(_CONTEXT_ITEMS.keys()))
# ['Main Screen', 'Slash Commands', 'Reference Picker', 'Shell Mode']
# Missing: Navigation, Actions, TUI-Specific

#1290 (UAT: TUI help panel key bindings are inconsistent with actual app bindings)
#1335 (UAT: TUI MainScreen missing escape-cascading navigation)

References

Spec §10.1.1 Global Keybindings
Spec §10.1.2 Navigation Keybindings
Spec §10.1.3 Action Keybindings
Spec §10.1.4 TUI-Specific Keybindings
Spec §10.2 Help Panel (F1)
src/cleveragents/tui/widgets/help_panel_overlay.py lines 22–30 (_GLOBAL_ITEMS), lines 33–58 (_CONTEXT_ITEMS), lines 60–75 (render_help_panel)

## Bug Report: [tui/help-panel] — Wrong title and missing spec-required shortcut categories ### Severity Assessment - **Impact**: High. The help panel is the primary user reference for keyboard shortcuts. Missing entire categories (Navigation, Actions, TUI-Specific) and showing the wrong title means users cannot discover most of the app's keyboard shortcuts. - **Likelihood**: 100% reproducible — the content is hardcoded. - **Priority**: High ### Location - **File**: `src/cleveragents/tui/widgets/help_panel_overlay.py` ### Description The spec (§10.2 Help Panel) defines the following requirements for the help panel content: 1. **Title**: Must be `"Help & Keyboard Shortcuts"` 2. **Categories**: Must include four sections: **Global**, **Navigation**, **Actions**, **TUI-Specific** 3. **Global shortcuts** must include: `F1`, `Ctrl+Q`, `Ctrl+L`, `Ctrl+S`, `Ctrl+O` 4. **Navigation shortcuts** must include: `Tab`, `Shift+Tab`, `↑`/`↓`, `PgUp`/`PgDn` 5. **Actions shortcuts** must include: `Enter`, `Esc`, `Ctrl+C`, `Ctrl+X`, `Ctrl+V` 6. **TUI-Specific shortcuts** must include: `Ctrl+T`, `Ctrl+W`, `Ctrl+Tab`, `Ctrl+Shift+Tab` ### Actual Behavior **Wrong title** (`render_help_panel()` in `help_panel_overlay.py`, line 60): ```python lines = [f"Help: {context_name}", "", "Global"] ``` This produces `"Help: Main Screen"` instead of the required `"Help & Keyboard Shortcuts"`. **Missing categories** — the `_CONTEXT_ITEMS` dict only defines: - `"Main Screen"`, `"Slash Commands"`, `"Reference Picker"`, `"Shell Mode"` None of the spec-required categories (`Navigation`, `Actions`, `TUI-Specific`) exist. **Missing Global shortcuts** — `_GLOBAL_ITEMS` only contains: ```python _GLOBAL_ITEMS = ( ("ctrl+q", "Quit TUI immediately"), ("F1", "Toggle help panel"), ("escape", "Close current overlay / return to prompt"), ) ``` Missing: `Ctrl+L` (Lock screen), `Ctrl+S` (Save session), `Ctrl+O` (Open session) **Missing Navigation shortcuts** — No `Navigation` section exists. Missing: `Shift+Tab`, `↑`/`↓`, `PgUp`/`PgDn` **Missing Actions shortcuts** — No `Actions` section exists. Missing: `Ctrl+C`, `Ctrl+X`, `Ctrl+V` **Missing TUI-Specific shortcuts** — No `TUI-Specific` section exists. Missing: `Ctrl+W`, `Ctrl+Shift+Tab` **Missing two-column layout headers** — The rendered output has no `Key(s)` / `Description` column headers. ### Expected Behavior (from spec §10.2) The rendered help panel should: 1. Show title `"Help & Keyboard Shortcuts"` 2. Have a `Global` section with: `F1`, `Ctrl+Q`, `Ctrl+L`, `Ctrl+S`, `Ctrl+O` 3. Have a `Navigation` section with: `Tab`, `Shift+Tab`, `↑`/`↓`, `PgUp`/`PgDn` 4. Have an `Actions` section with: `Enter`, `Esc`, `Ctrl+C`, `Ctrl+X`, `Ctrl+V` 5. Have a `TUI-Specific` section with: `Ctrl+T`, `Ctrl+W`, `Ctrl+Tab`, `Ctrl+Shift+Tab` 6. Use a two-column layout with `Key(s)` and `Description` headers ### Steps to Reproduce ```python from cleveragents.tui.widgets.help_panel_overlay import render_help_panel, _GLOBAL_ITEMS, _CONTEXT_ITEMS print(render_help_panel("Main Screen")) # Output shows "Help: Main Screen" (wrong title) # No Navigation, Actions, or TUI-Specific sections print([k for k, _ in _GLOBAL_ITEMS]) # ['ctrl+q', 'F1', 'escape'] — missing Ctrl+L, Ctrl+S, Ctrl+O print(list(_CONTEXT_ITEMS.keys())) # ['Main Screen', 'Slash Commands', 'Reference Picker', 'Shell Mode'] # Missing: Navigation, Actions, TUI-Specific ``` ### Related Issues - #1290 (UAT: TUI help panel key bindings are inconsistent with actual app bindings) - #1335 (UAT: TUI MainScreen missing escape-cascading navigation) ### References - Spec §10.1.1 Global Keybindings - Spec §10.1.2 Navigation Keybindings - Spec §10.1.3 Action Keybindings - Spec §10.1.4 TUI-Specific Keybindings - Spec §10.2 Help Panel (F1) - `src/cleveragents/tui/widgets/help_panel_overlay.py` lines 22–30 (`_GLOBAL_ITEMS`), lines 33–58 (`_CONTEXT_ITEMS`), lines 60–75 (`render_help_panel`)

freemo referenced this issue

2026-04-02 16:58:20 +00:00

UAT: Help panel is context-sensitive but spec requires it to always show the same global shortcuts #1359

freemo referenced this issue

2026-04-02 16:58:41 +00:00

UAT: Help panel is an inline Static widget, not a modal overlay as required by spec #1361

freemo referenced this issue

2026-04-02 16:59:00 +00:00

UAT: Help panel styling does not match spec (missing #FFFFFF background, drop shadow, and semi-transparent backdrop) #1364

freemo added the

State

Unverified