feat: improve terminal navigation and UI behavior

- refine tree and history navigation behavior
- improve scrolling continuity in the terminal UI
- keep AI worklog and prompt log updated
- validate changes with project quality checks

docs/ai-prompts.md

@@ -26,3 +26,18 @@ Store only the user prompt and a short result summary.
 
 - prompt summary: Introduce a standard AI log entry format in `instructions-agent.md` and record the change in the repository AI logs.
 - result summary: Added a standardized `AI BUILD ENTRY` and `AI PLAN ENTRY` format, improved consistency expectations for AI logs, and updated the log files to reflect the new format.
+
+## 2026-03-15
+
+- prompt summary: Improve keyboard navigation in `src/app/ui.py` so Right expands or enters, Left collapses or goes to the parent, Enter confirms the selected destination, and ESC cancels back to the starting directory.
+- result summary: Updated the tree-mode key handling in the terminal UI, preserved history mode behavior, and added focused UI tests for the new navigation rules.
+
+## 2026-03-15
+
+- prompt summary: Improve vertical scrolling in `src/app/ui.py` so the selected entry always remains visible in tree mode and history mode when the list is taller than the screen.
+- result summary: Added UI scroll offset handling for tree and history views, kept existing navigation behavior unchanged, and added focused tests for the scroll helper logic.
+
+## 2026-03-16 00:27
+
+- prompt summary: Improve terminal UI navigation by refining tree and history keyboard behavior, adding scrolling continuity so selection stays visible, and preserving confirmation, cancellation, and history mode behavior.
+- result summary: Updated `src/app/ui.py` and `tests/test_ui.py` to support dedicated history selection, improved Right/Left/Enter/ESC behavior, and vertical scrolling for both tree and history views while keeping the AI logs current.

docs/ai-worklog.md

@@ -14,23 +14,80 @@ Each entry should include:
 
 Entries must be concise and chronological.
 
-## 2026-03-15 - build
+### AI BUILD ENTRY
+Date: 2026-03-15  
+Task: build  
+Objective: Replace the temporary history debug overlay with a dedicated history mode in the terminal UI.
 
-- objective: Replace the temporary history debug overlay with a dedicated history mode in the terminal UI.
-- files modified: `src/app/ui.py`, `tests/test_ui.py`
-- key decisions: Keep `b` and `f` unchanged, add separate history-mode selection state inside the UI, hide the tree while history mode is active, and use Enter to select a history entry and return to the tree view.
-- validation: `make fix`, `make quality`
-- result: History mode now shows only the history list, supports Up/Down selection, allows Enter to jump to a prior directory, and exits cleanly back to normal navigation.
-- open issues: None.
+Files Modified:
+- `src/app/ui.py`
+- `tests/test_ui.py`
 
-## 2026-03-15 - build
+Key Decisions:
+- Keep `b` and `f` unchanged.
+- Add separate history-mode selection state inside the UI.
+- Hide the tree while history mode is active.
+- Use Enter to select a history entry and return to the tree view.
 
-- objective: Introduce mandatory AI logging rules and document the repository logging workflow.
-- files modified: `instructions-agent.md`, `docs/ai-worklog.md`, `docs/ai-prompts.md`
-- key decisions: Require AI agents to log significant plan and build tasks, preserve separate logs for work performed and prompts received, and keep entries concise and user-facing.
-- validation: not run
-- result: The repository now defines mandatory AI logging in `instructions-agent.md` and includes dedicated log files for AI work history and prompt summaries.
-- open issues: None.
+Validation:
+- make fix
+- make quality
+
+Result:
+- History mode now shows only the history list, supports Up/Down selection, allows Enter to jump to a prior directory, and exits cleanly back to normal navigation.
+
+Open Issues:
+- None.
+
+### AI BUILD ENTRY
+Date: 2026-03-16 00:27  
+Task: build  
+Objective: Consolidate recent terminal UI navigation improvements and document the updated interaction behavior.
+
+Files Modified:
+- `src/app/ui.py`
+- `tests/test_ui.py`
+- `docs/ai-worklog.md`
+- `docs/ai-prompts.md`
+
+Key Decisions:
+- Keep dedicated history mode while refining tree-mode keyboard behavior for Right, Left, Enter, and ESC.
+- Add scroll continuity for both tree and history views so the selected row remains visible on long lists.
+- Cover the UI-focused behavior with helper-level tests instead of changing navigator or filesystem logic.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The terminal UI now combines dedicated history mode, clearer confirmation and cancellation behavior, improved tree navigation semantics, and vertical scrolling that keeps the current selection visible in both tree and history views.
+
+Open Issues:
+- None.
+
+### AI BUILD ENTRY
+Date: 2026-03-15  
+Task: build  
+Objective: Introduce mandatory AI logging rules and document the repository logging workflow.
+
+Files Modified:
+- `instructions-agent.md`
+- `docs/ai-worklog.md`
+- `docs/ai-prompts.md`
+
+Key Decisions:
+- Require AI agents to log significant plan and build tasks.
+- Preserve separate logs for work performed and prompts received.
+- Keep entries concise and user-facing.
+
+Validation:
+- not run
+
+Result:
+- The repository now defines mandatory AI logging in `instructions-agent.md` and includes dedicated log files for AI work history and prompt summaries.
+
+Open Issues:
+- None.
 
 ### AI BUILD ENTRY
 Date: 2026-03-15  
@@ -55,3 +112,53 @@ Result:
 
 Open Issues:
 - None.
+
+### AI BUILD ENTRY
+Date: 2026-03-15  
+Task: build  
+Objective: Improve vertical scrolling in the terminal UI so the selected row remains visible in tree mode and history mode.
+
+Files Modified:
+- `src/app/ui.py`
+- `tests/test_ui.py`
+- `docs/ai-worklog.md`
+- `docs/ai-prompts.md`
+
+Key Decisions:
+- Add separate scroll offsets for tree mode and history mode inside the UI state.
+- Introduce a small helper to clamp scroll offsets so the selected row always stays within the visible window.
+- Keep all existing navigation semantics unchanged while limiting the change to UI rendering behavior.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The terminal UI now scrolls vertically in both tree mode and history mode to keep the current selection visible when the list is taller than the screen.
+
+Open Issues:
+- None.
+
+### AI BUILD ENTRY
+Date: 2026-03-15  
+Task: build  
+Objective: Improve keyboard navigation behavior in the terminal UI for tree mode.
+
+Files Modified:
+- `src/app/ui.py`
+- `tests/test_ui.py`
+
+Key Decisions:
+- Make Right expand collapsed directories and enter already expanded directories.
+- Make Left collapse expanded directories and otherwise navigate to the parent directory.
+- Make Enter confirm the selected path as the final destination and make ESC return the original starting directory.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- Tree-mode keyboard navigation now supports expand-or-enter on Right, collapse-or-parent on Left, explicit selection confirmation on Enter, and cancel-to-start behavior on ESC.
+
+Open Issues:
+- None.