feat: update documentation for status line and help overlay

- add ? help keybinding to README and plugin usage reference
- add status line and help overlay to features list
- move plan to completed

Author: umputun

.claude-plugin/skills/revdiff/references/usage.md

@@ -46,6 +46,7 @@ revdiff HEAD~1       # review last commit
 | `v` | Toggle collapsed diff mode (shows final text with change markers) |
 | `.` | Expand/collapse individual hunk under cursor (collapsed mode only) |
 | `f` | Toggle filter: all files / annotated only |
+| `?` | Toggle help overlay showing all keybindings |
 | `q` | Quit, output annotations to stdout |
 | `Q` | Discard all annotations and quit (confirms if annotations exist) |
 

.claude-plugin/skills/revdiff/scripts/launch-revdiff.sh

@@ -20,9 +20,17 @@ trap 'rm -f "$OUTPUT_FILE"' EXIT
 REVDIFF_CMD="$REVDIFF_BIN --output=$OUTPUT_FILE $*"
 CWD="$(pwd)"
 
+# build descriptive title: "revdiff: dirname [ref]"
+DIR_NAME=$(basename "$CWD")
+TITLE_REF=""
+for arg in "$@"; do
+    case "$arg" in --*) ;; *) TITLE_REF="$arg"; break ;; esac
+done
+OVERLAY_TITLE="rd: ${DIR_NAME}${TITLE_REF:+ [$TITLE_REF]}"
+
 # tmux: display-popup -E blocks until command exits
 if [ -n "${TMUX:-}" ] && command -v tmux >/dev/null 2>&1; then
-    tmux display-popup -E -w 90% -h 90% -T " revdiff " -d "$CWD" -- sh -c "$REVDIFF_CMD"
+    tmux display-popup -E -w 90% -h 90% -T " $OVERLAY_TITLE " -d "$CWD" -- sh -c "$REVDIFF_CMD"
     cat "$OUTPUT_FILE"
     exit 0
 fi
@@ -33,7 +41,7 @@ if [ -n "$KITTY_SOCK" ] && command -v kitty >/dev/null 2>&1; then
     SENTINEL=$(mktemp /tmp/revdiff-done-XXXXXX)
     rm -f "$SENTINEL"
 
-    KITTY_ARGS=(kitty @ --to "$KITTY_SOCK" launch --type=overlay --title="revdiff" --cwd="$CWD")
+    KITTY_ARGS=(kitty @ --to "$KITTY_SOCK" launch --type=overlay --title="$OVERLAY_TITLE" --cwd="$CWD")
     if [ -n "${KITTY_WINDOW_ID:-}" ]; then
         KITTY_ARGS+=(--match "id:${KITTY_WINDOW_ID}")
     fi

README.md

@@ -13,6 +13,8 @@ Built for a specific use case: reviewing code changes without leaving a terminal
 - Two-pane TUI: file tree (left) + colorized diff viewport (right)
 - Hunk navigation to jump between change groups
 - Filter file tree to show only annotated files
+- Status line with filename, diff stats, hunk position, and mode indicators
+- Help overlay (`?`) showing all keybindings organized by section
 - Fully customizable colors via environment variables, CLI flags, or config file
 
 ![revdiff screenshot](screenshot.png)
@@ -233,6 +235,7 @@ revdiff HEAD~1
 | `v` | Toggle collapsed diff mode (shows final text with change markers) |
 | `.` | Expand/collapse individual hunk under cursor (collapsed mode only) |
 | `f` | Toggle filter: all files / annotated only (shown when annotations exist) |
+| `?` | Toggle help overlay showing all keybindings |
 | `q` | Quit, output annotations to stdout |
 | `Q` | Discard all annotations and quit (confirms if annotations exist) |
 

docs/plans/completed/20260402-status-line-help-overlay.md

@@ -0,0 +1,139 @@
+# Split Status Bar into Status Line + Help Overlay
+
+## Overview
+Replace the current single status bar (which mixes status info and shortcut hints) with two separate concerns:
+1. **Status line** — shows file info, diff stats, hunk position, mode indicators, annotation count
+2. **Help overlay** — a modal popup triggered by `?` showing all keybindings organized by section
+
+The current `statusBarText()` in `ui/model.go:488-551` is crowded and hard to scan. Splitting status from help makes both more useful: the status line becomes a clean info strip, and the help overlay provides comprehensive reference without cluttering the screen.
+
+## Context
+- **Primary file:** `ui/model.go` — `statusBarText()` (lines 488-551), `View()` (lines 442-486), `handleKey()` (lines 188-259)
+- **Styles:** `ui/styles.go` — `StatusBar` style, `Colors` struct
+- **Diff navigation:** `ui/diffview.go` — `currentHunk()`, `findHunks()`
+- **Collapsed mode:** `ui/collapsed.go` — `collapsedState`
+- **Model fields:** `ui/model.go` — `currFile`, `diffLines`, `store`, `collapsed`, etc.
+
+## Solution Overview
+
+### Status line layout (left to right)
+```
+filename  +N/-N  hunk X/Y  ▼ ◉                    3 annotations  ? help
+```
+- **filename** — current file path (truncated from left with `…` if too long)
+- **+N/-N** — additions/deletions count for the current file
+- **hunk X/Y** — current hunk position (only when cursor is on a changed line)
+- **▼** — collapsed mode indicator (only when active)
+- **◉** — filter active indicator (only when active)
+- **right-aligned:** annotation count + `? help` hint
+
+### Help overlay
+- Triggered by `?` key, dismissed by `?` or `esc`
+- Centered bordered box rendered on top of the main view
+- Sections: Navigation, Annotations, View, Quit
+- Uses lipgloss border styling consistent with existing pane borders
+
+## Technical Details
+
+### New fields in Model
+- `showHelp bool` — true when help overlay is visible
+- No new files needed — help rendering goes in a new `helpOverlay()` method in `model.go`
+
+### File stats computation
+- Count adds/removes from `m.diffLines` on file load (in `handleFileLoaded`)
+- Cache as `fileAdds int`, `fileRemoves int` fields on Model
+- Reset on file change
+
+### Status line segments
+Each segment is a small string. Segments are joined with double-space separators. Right-aligned section uses padding like current implementation.
+
+### Help overlay rendering
+- Build help text as a lipgloss-bordered box
+- When `m.showHelp` is true, `View()` replaces the main content area with the centered help popup (standard bubbletea modal pattern — no true compositing, the help box replaces tree+diff content)
+- Use `lipgloss.Place(m.width, paneHeight, lipgloss.Center, lipgloss.Center, helpBox)` + status bar below
+- Note: bubbletea reports `?` key correctly via `msg.String()` (shifted `/` key)
+
+### Narrow terminal handling
+- Truncate filename from left with `…` prefix when space is tight
+- Drop lower-priority segments (hunk, mode icons) if width is insufficient
+
+## Development Approach
+- **Testing approach:** regular (code first, then tests)
+- Complete each task fully before moving to the next
+- Run tests after each change
+- Maintain backward compatibility (existing CLI flags, config, styles all still work)
+
+## Implementation Steps
+
+### Task 1: Compute and cache file diff stats
+
+**Files:**
+- Modify: `ui/model.go`
+- Modify: `ui/model_test.go`
+
+- [x] add `fileAdds` and `fileRemoves` int fields to `Model` struct
+- [x] add `computeFileStats()` method that counts add/remove lines from `m.diffLines`
+- [x] call `computeFileStats()` in `handleFileLoaded` after setting `m.diffLines`
+- [x] write tests for `computeFileStats()` with various diff line combinations
+- [x] run `make test` — must pass before task 2
+
+### Task 2: Rewrite status line and update tests
+
+**Files:**
+- Modify: `ui/model.go`
+- Modify: `ui/model_test.go`
+
+- [x] rewrite `statusBarText()` to show: filename, +N/-N stats, hunk X/Y, mode icons (▼ ◉), right-aligned annotation count + `? help`
+- [x] keep special cases for `inConfirmDiscard` and `annotating` modes unchanged
+- [x] implement filename truncation with `…` prefix for narrow terminals
+- [x] drop hunk and mode icons gracefully when terminal is too narrow
+- [x] update existing `statusBarText` tests to match new format (no shortcut hints, has filename/stats)
+- [x] add test cases for: filename truncation, mode indicators present/absent, stats display
+- [x] add test cases for narrow terminal width graceful degradation
+- [x] run `make test` — must pass before task 3
+
+### Task 3: Add help overlay rendering
+
+**Files:**
+- Modify: `ui/model.go`
+
+- [x] add `showHelp bool` field to Model
+- [x] add `helpOverlay()` method returning the bordered help text with sections (Navigation, Annotations, View, Quit)
+- [x] modify `View()` to overlay help popup using `lipgloss.Place()` when `m.showHelp` is true
+- [x] write tests for `helpOverlay()` verifying section headers and key listings are present
+- [x] run `make test` — must pass before task 4
+
+### Task 4: Wire up `?` key handling
+
+**Files:**
+- Modify: `ui/model.go`
+- Modify: `ui/model_test.go`
+
+- [x] handle `?` key in `handleKey()` to toggle `m.showHelp`
+- [x] handle `esc` key to close help when `m.showHelp` is true
+- [x] block all other key handling when help overlay is showing (except `?` and `esc`)
+- [x] write tests for help toggle behavior (open, close with ?, close with esc)
+- [x] write test that other keys are blocked when help is showing
+- [x] run `make test` — must pass before task 5
+
+### Task 5: Verify acceptance criteria
+- [x] verify status line shows filename, stats, hunk, mode icons, annotations, help hint
+- [x] verify help overlay opens with `?` and closes with `?` or `esc`
+- [x] verify no shortcut hints in status bar anymore (all moved to help overlay)
+- [x] verify special modes (annotation input, discard confirm) still work in status bar
+- [x] run full test suite: `make test`
+- [x] run linter: `make lint`
+
+### Task 6: [Final] Update documentation
+- [x] update README.md with new `?` help shortcut and status line description
+- [x] update `.claude-plugin/skills/revdiff/references/usage.md` with `?` help keybinding
+- [x] update CLAUDE.md if any new patterns discovered
+- [x] move this plan to `docs/plans/completed/`
+
+## Post-Completion
+
+**Manual verification:**
+- test with narrow terminal widths (< 80 cols) to verify truncation
+- test with large diffs (many hunks) to verify hunk counter
+- test collapsed mode + filter active to verify both icons show
+- verify help overlay looks correct with different color themes

ui/model.go

@@ -11,6 +11,7 @@ import (
 	"github.com/charmbracelet/bubbles/viewport"
 	tea "github.com/charmbracelet/bubbletea"
 	"github.com/charmbracelet/lipgloss"
+	"github.com/mattn/go-runewidth"
 
 	"github.com/umputun/revdiff/annotation"
 	"github.com/umputun/revdiff/diff"
@@ -520,14 +521,9 @@ func (m Model) statusBarText() string {
 	// build left-side segments
 	var segments []string
 
-	// filename segment
+	// filename and diff stats segments
 	if m.currFile != "" {
-		segments = append(segments, m.currFile)
-	}
-
-	// diff stats segment
-	if m.currFile != "" {
-		segments = append(segments, fmt.Sprintf("+%d/-%d", m.fileAdds, m.fileRemoves))
+		segments = append(segments, m.currFile, fmt.Sprintf("+%d/-%d", m.fileAdds, m.fileRemoves))
 	}
 
 	// hunk position (only when cursor is on a changed line in diff pane)
@@ -548,41 +544,57 @@ func (m Model) statusBarText() string {
 	// build right-side segments
 	var rightParts []string
 	if cnt := m.store.Count(); cnt > 0 {
-		rightParts = append(rightParts, fmt.Sprintf("%d annotations", cnt))
+		suffix := "annotations"
+		if cnt == 1 {
+			suffix = "annotation"
+		}
+		rightParts = append(rightParts, fmt.Sprintf("%d %s", cnt, suffix))
 	}
 	rightParts = append(rightParts, "? help")
 
 	left := strings.Join(segments, "  ")
 	right := strings.Join(rightParts, "  ")
 
 	// truncate filename from left with … if status line is too wide
-	minRight := len(right) + 4 // 2 for status bar padding + 2 for separator
+	minRight := lipgloss.Width(right) + 4 // 2 for status bar padding + 2 for separator
 	available := max(m.width-minRight, 0)
 
 	// graceful degradation: drop segments from right to left when too narrow
-	if len(left) > available {
+	if lipgloss.Width(left) > available {
 		// rebuild without mode icons first
 		segments = m.statusSegmentsNoIcons()
 		left = strings.Join(segments, "  ")
 	}
-	if len(left) > available {
+	if lipgloss.Width(left) > available {
 		// rebuild without hunk info
 		segments = m.statusSegmentsMinimal()
 		left = strings.Join(segments, "  ")
 	}
-	if len(left) > available && m.currFile != "" {
-		// truncate filename
+	if lipgloss.Width(left) > available && m.currFile != "" {
+		// truncate filename from left, keeping end of path.
+		// uses display-width measurement to handle wide characters (CJK, emoji)
 		statsStr := fmt.Sprintf("+%d/-%d", m.fileAdds, m.fileRemoves)
-		nameMax := max(available-len(statsStr)-2, 4) // 2 for separator between name and stats
+		nameMax := max(available-lipgloss.Width(statsStr)-2, 4) // 2 for separator between name and stats
 		name := m.currFile
-		if len(name) > nameMax {
-			name = "…" + name[len(name)-nameMax+1:]
+		if lipgloss.Width(name) > nameMax {
+			budget := nameMax - 1 // reserve 1 cell for "…"
+			runes := []rune(name)
+			w, cutIdx := 0, len(runes)
+			for i := len(runes) - 1; i >= 0; i-- {
+				rw := runewidth.RuneWidth(runes[i])
+				if w+rw > budget {
+					break
+				}
+				w += rw
+				cutIdx = i
+			}
+			name = "…" + string(runes[cutIdx:])
 		}
 		left = name + "  " + statsStr
 	}
 
 	// pad left to push right section to the end
-	padding := m.width - len(left) - len(right) - 2 // 2 for status bar padding
+	padding := m.width - lipgloss.Width(left) - lipgloss.Width(right) - 2 // 2 for status bar padding
 	if padding > 0 {
 		return left + strings.Repeat(" ", padding) + right
 	}
@@ -619,28 +631,31 @@ func (m Model) statusSegmentsMinimal() []string {
 func (m Model) helpOverlay() string {
 	help := "" +
 		"Navigation\n" +
-		"  tab        switch pane\n" +
-		"  n / p      next / prev file\n" +
-		"  j / k      scroll down / up\n" +
-		"  g / G      top / bottom\n" +
-		"  h / l      scroll left / right\n" +
-		"  { / }      prev / next hunk\n" +
-		"  enter      focus diff pane\n" +
+		"  tab          switch pane\n" +
+		"  n / p        next / prev file\n" +
+		"  j / k        scroll down / up\n" +
+		"  PgDn/PgUp    page down / up\n" +
+		"  Ctrl+d/u     half-page down / up\n" +
+		"  Home/End     top / bottom\n" +
+		"  h / l        focus tree / diff pane\n" +
+		"  \u2190 / \u2192        scroll left / right (diff)\n" +
+		"  [ / ]        prev / next hunk\n" +
+		"  enter        focus diff pane\n" +
 		"\n" +
 		"Annotations\n" +
-		"  enter      annotate line (diff pane)\n" +
-		"  A          annotate file\n" +
-		"  f          filter annotated files\n" +
+		"  a / enter    annotate line (diff pane)\n" +
+		"  A            annotate file\n" +
+		"  d            delete annotation\n" +
 		"\n" +
 		"View\n" +
-		"  v          toggle collapsed mode\n" +
-		"  .          expand/collapse hunk\n" +
-		"  [ / ]      narrow / widen tree\n" +
+		"  v            toggle collapsed mode\n" +
+		"  .            expand/collapse hunk\n" +
+		"  f            filter annotated files\n" +
 		"\n" +
 		"Quit\n" +
-		"  q          quit\n" +
-		"  Q          discard annotations & quit\n" +
-		"  ? / esc    close help"
+		"  q            quit\n" +
+		"  Q            discard annotations & quit\n" +
+		"  ? / esc      close help"
 
 	border := lipgloss.NormalBorder()
 	boxStyle := lipgloss.NewStyle().