UAT: Help panel (F1) missing "Block Cursor" context — alt+up/alt+down and block navigation keys not documented #1358

New issue

Open

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

freemo commented

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

Owner

Severity Assessment

Impact: Medium. Users who press F1 while navigating blocks will see the generic "Main Screen" help context, which does not document the block cursor keys (alt+up, alt+down, space, enter, escape). This makes the feature undiscoverable.
Likelihood: 100% reproducible.
Priority: Medium

Location

File: src/cleveragents/tui/widgets/help_panel_overlay.py — _CONTEXT_ITEMS dict (lines 27–52)
File: src/cleveragents/tui/widgets/help_panel_overlay.py — resolve_help_context() function (lines 55–65)
Spec reference: docs/specification.md, lines 29583–29595 (Help Panel F1 section)

Description

The specification states that F1 opens a context-sensitive help overlay showing available hotkeys for the current screen/widget. When the conversation Window widget has focus (i.e., during block cursor navigation), the help panel should show the block cursor navigation keys.

The current help_panel_overlay.py defines only 4 contexts:

"Main Screen" — general prompt keys
"Slash Commands" — slash command overlay keys
"Reference Picker" — reference picker overlay keys
"Shell Mode" — shell mode keys

There is no "Block Cursor" context. The resolve_help_context() function only checks the prompt text content to determine context — it has no awareness of whether the conversation widget has focus or the block cursor is active.

Additionally, the "Main Screen" context in the help panel does not include the block cursor navigation keys (alt+up, alt+down) even as a secondary section.

Evidence

Current _CONTEXT_ITEMS (src/cleveragents/tui/widgets/help_panel_overlay.py, lines 27–52):

_CONTEXT_ITEMS: dict[str, tuple[tuple[str, str], ...]] = {
    "Main Screen": (
        ("enter", "Submit prompt"),
        ("tab", "Cycle to next persona"),
        ("ctrl+tab", "Cycle to next argument preset"),
        ("@", "Open Reference Picker overlay"),
        ("/", "Open Slash Command overlay"),
        ("! / $", "Activate shell mode"),
    ),
    "Slash Commands": (...),
    "Reference Picker": (...),
    "Shell Mode": (...),
}

No "Block Cursor" context exists. The block cursor keys (alt+up, alt+down, space, enter, escape) are completely absent from the help panel.

Spec requirement (docs/specification.md, line 29585):

F1 opens a context-sensitive help overlay showing available hotkeys for the current screen/widget

Spec keyboard shortcut table (docs/specification.md, lines 30212–30219):

MainScreen — Conversation / Block Cursor

| alt+up | Move block cursor to previous block |
| alt+down | Move block cursor to next block |
| space | Expand / collapse focused block |
| enter | Open context menu for focused block |
| escape | Clear block cursor, return focus to prompt |
| Any printable character | Forward to prompt (key passthrough) |

Steps to Reproduce

Run the TUI app
Navigate to a conversation block using alt+up/alt+down
Press F1 to open the help panel
Observe: the help panel shows "Main Screen" context with prompt-focused keys, not block cursor keys
alt+up, alt+down, space, enter (for context menu) are not documented

Expected Behavior

When the block cursor is active (conversation widget has focus), pressing F1 should show a "Block Cursor" help context with the navigation keys: alt+up, alt+down, space, enter, escape, and "any printable character → forward to prompt".

Actual Behavior

The help panel shows the generic "Main Screen" context regardless of whether the block cursor is active. Block cursor navigation keys are not documented anywhere in the help panel.

Issue #1290 (UAT: TUI help panel key bindings are inconsistent with actual app bindings) covers a different problem — the mismatch between documented and registered bindings. This issue is specifically about the missing "Block Cursor" help context.

Metadata

Branch: feat/tui-help-panel-block-cursor-context
Commit Message: feat(tui): add Block Cursor context to help panel overlay
Milestone: v3.7.0
Parent Epic: #694

Subtasks

Add "Block Cursor" entry to _CONTEXT_ITEMS in help_panel_overlay.py with keys: alt+up, alt+down, space, enter, escape, and "any printable char"
Update resolve_help_context() to accept an optional conversation_focused: bool parameter (or equivalent) so it can return "Block Cursor" when appropriate
Update action_help in MainScreen (or app.py) to pass the conversation focus state to resolve_help_context()
Write Behave BDD scenarios: pressing F1 during block cursor navigation shows "Block Cursor" context
Run nox -e typecheck, nox -e unit_tests, nox -e coverage_report

Definition of Done

_CONTEXT_ITEMS["Block Cursor"] exists with all 6 navigation keys documented
resolve_help_context() returns "Block Cursor" when the conversation widget has focus
BDD scenarios verify the correct context is shown
All nox stages pass
Coverage ≥ 97%

## Bug Report: [tui] — Help panel missing "Block Cursor" context for conversation navigation keys ### Severity Assessment - **Impact**: Medium. Users who press F1 while navigating blocks will see the generic "Main Screen" help context, which does not document the block cursor keys (`alt+up`, `alt+down`, `space`, `enter`, `escape`). This makes the feature undiscoverable. - **Likelihood**: 100% reproducible. - **Priority**: Medium ### Location - **File**: `src/cleveragents/tui/widgets/help_panel_overlay.py` — `_CONTEXT_ITEMS` dict (lines 27–52) - **File**: `src/cleveragents/tui/widgets/help_panel_overlay.py` — `resolve_help_context()` function (lines 55–65) - **Spec reference**: `docs/specification.md`, lines 29583–29595 (Help Panel F1 section) ### Description The specification states that `F1` opens a **context-sensitive** help overlay showing available hotkeys for the **current screen/widget**. When the conversation `Window` widget has focus (i.e., during block cursor navigation), the help panel should show the block cursor navigation keys. The current `help_panel_overlay.py` defines only 4 contexts: - `"Main Screen"` — general prompt keys - `"Slash Commands"` — slash command overlay keys - `"Reference Picker"` — reference picker overlay keys - `"Shell Mode"` — shell mode keys There is no `"Block Cursor"` context. The `resolve_help_context()` function only checks the prompt text content to determine context — it has no awareness of whether the conversation widget has focus or the block cursor is active. Additionally, the "Main Screen" context in the help panel does not include the block cursor navigation keys (`alt+up`, `alt+down`) even as a secondary section. ### Evidence **Current `_CONTEXT_ITEMS`** (`src/cleveragents/tui/widgets/help_panel_overlay.py`, lines 27–52): ```python _CONTEXT_ITEMS: dict[str, tuple[tuple[str, str], ...]] = { "Main Screen": ( ("enter", "Submit prompt"), ("tab", "Cycle to next persona"), ("ctrl+tab", "Cycle to next argument preset"), ("@", "Open Reference Picker overlay"), ("/", "Open Slash Command overlay"), ("! / $", "Activate shell mode"), ), "Slash Commands": (...), "Reference Picker": (...), "Shell Mode": (...), } ``` No `"Block Cursor"` context exists. The block cursor keys (`alt+up`, `alt+down`, `space`, `enter`, `escape`) are completely absent from the help panel. **Spec requirement** (`docs/specification.md`, line 29585): > `F1` opens a context-sensitive help overlay showing available hotkeys for the current screen/widget **Spec keyboard shortcut table** (`docs/specification.md`, lines 30212–30219): > #### MainScreen — Conversation / Block Cursor > | `alt+up` | Move block cursor to previous block | > | `alt+down` | Move block cursor to next block | > | `space` | Expand / collapse focused block | > | `enter` | Open context menu for focused block | > | `escape` | Clear block cursor, return focus to prompt | > | Any printable character | Forward to prompt (key passthrough) | ### Steps to Reproduce 1. Run the TUI app 2. Navigate to a conversation block using `alt+up`/`alt+down` 3. Press `F1` to open the help panel 4. Observe: the help panel shows "Main Screen" context with prompt-focused keys, not block cursor keys 5. `alt+up`, `alt+down`, `space`, `enter` (for context menu) are not documented ### Expected Behavior When the block cursor is active (conversation widget has focus), pressing `F1` should show a "Block Cursor" help context with the navigation keys: `alt+up`, `alt+down`, `space`, `enter`, `escape`, and "any printable character → forward to prompt". ### Actual Behavior The help panel shows the generic "Main Screen" context regardless of whether the block cursor is active. Block cursor navigation keys are not documented anywhere in the help panel. ### Note on Related Issue Issue #1290 (UAT: TUI help panel key bindings are inconsistent with actual app bindings) covers a different problem — the mismatch between documented and registered bindings. This issue is specifically about the missing "Block Cursor" help context. ### Category tui / block-cursor / help-panel / uat --- ## Metadata - **Branch**: `feat/tui-help-panel-block-cursor-context` - **Commit Message**: `feat(tui): add Block Cursor context to help panel overlay` - **Milestone**: v3.7.0 - **Parent Epic**: #694 ## Subtasks - [ ] Add `"Block Cursor"` entry to `_CONTEXT_ITEMS` in `help_panel_overlay.py` with keys: `alt+up`, `alt+down`, `space`, `enter`, `escape`, and "any printable char" - [ ] Update `resolve_help_context()` to accept an optional `conversation_focused: bool` parameter (or equivalent) so it can return `"Block Cursor"` when appropriate - [ ] Update `action_help` in `MainScreen` (or `app.py`) to pass the conversation focus state to `resolve_help_context()` - [ ] Write Behave BDD scenarios: pressing F1 during block cursor navigation shows "Block Cursor" context - [ ] Run `nox -e typecheck`, `nox -e unit_tests`, `nox -e coverage_report` ## Definition of Done - [ ] `_CONTEXT_ITEMS["Block Cursor"]` exists with all 6 navigation keys documented - [ ] `resolve_help_context()` returns `"Block Cursor"` when the conversation widget has focus - [ ] BDD scenarios verify the correct context is shown - [ ] All nox stages pass - [ ] Coverage ≥ 97%

freemo added the

labels

2026-04-02 18:17:25 +00:00

freemo referenced this issue

2026-04-02 18:19:39 +00:00

[Automated] Product Build Session State #1314

freemo self-assigned this

2026-04-02 18:45:19 +00:00