@pellux/goodvibes-tui 0.27.0 → 0.29.0

package/src/renderer/compositor.ts

@@ -6,9 +6,15 @@ import type { SearchManager } from '../input/search.ts';
 import { allowTerminalWrite } from '../runtime/terminal-output-guard.ts';
 import { probeTermCaps, type TermColorCaps } from './term-caps.ts';
 import { DARK_THEME } from './theme.ts';
+import { UI_TONES } from './ui-primitives.ts';
 
 const T = DARK_THEME;
 
+// Accent / dim colors for the panel focus border. The focused pane's left
+// border column is drawn in the accent tone; the unfocused pane stays dim.
+const PANEL_FOCUS_ACCENT = UI_TONES.state.active; // bright blue
+const PANEL_BORDER_DIM = '238';
+
 export interface SelectionInfo {
   isCellSelected: (col: number, absoluteRow: number) => boolean;
   scrollTop: number;
@@ -22,16 +28,18 @@ export interface SearchInfo {
 }
 
 export interface PanelCompositeData {
-  /** Workspace-level tab bar spanning all open panels. */
+  /**
+   * The single consolidated workspace tab bar spanning all open panels across
+   * both panes. There are no per-pane tab bars — pane focus is shown by the
+   * accent border (see `topFocused`/`bottomFocused`).
+   */
   workspaceBar: Line;
-  /** Top pane: tab bar */
-  topTabBar?: Line;
   /** Top pane: panel content lines */
   topContent: Line[];
-  /** Whether the top pane is focused (affects separator color) */
+  /** Whether the top pane is focused (drives the accent border) */
   topFocused: boolean;
-  /** Bottom pane tab bar. Undefined = no bottom pane. */
-  bottomTabBar?: Line;
+  /** Whether a bottom pane is present (splits the panel area). */
+  hasBottomPane: boolean;
   /** Bottom pane content lines. Undefined = no bottom pane. */
   bottomContent?: Line[];
   /** Whether the bottom pane is focused */
@@ -113,29 +121,31 @@ export class Compositor {
     const offset = Math.max(0, vHeight - lineCount);
 
     // --- Pre-compute panel row layout when split pane is active ---
-    // When both top and bottom panes are visible, the panel area is split:
+    // A single consolidated workspace bar heads the panel area; there are no
+    // per-pane tab bars. When both panes are visible the layout is:
     //   row 0:              workspace tab bar
-    //   row 1:              top tab bar
-    //   rows 2..topH+1:     top content
-    //   row topH+2:         horizontal separator (───)
-    //   row topH+3:         bottom tab bar
-    //   rows topH+4..end:   bottom content
-    const hasBottomPane = hasPanel && panel!.bottomTabBar !== undefined;
+    //   rows 1..topH:       top content
+    //   row topH+1:         horizontal separator (───)
+    //   rows topH+2..end:   bottom content
+    const hasBottomPane = hasPanel && panel!.hasBottomPane;
     let topPaneHeight = 0;   // number of content rows in top pane
-    let bottomPaneHeight = 0;
     let hSepRow = -1;        // viewport row of the horizontal separator
     if (hasPanel && hasBottomPane) {
-      const panelAreaRows = Math.max(0, vHeight - 1); // subtract workspace tab bar
-      // top: 1 (tabbar) + topContent rows; bottom: 1 (sep) + 1 (tabbar) + bottomContent
-      const contentRows = Math.max(0, panelAreaRows - 3); // subtract top-tabbar + h-sep + bottom-tabbar
+      const panelAreaRows = Math.max(0, vHeight - 1); // subtract workspace bar
+      const contentRows = Math.max(0, panelAreaRows - 1); // subtract h-separator
       topPaneHeight = Math.max(1, Math.floor(contentRows * panel!.verticalSplitRatio));
-      bottomPaneHeight = Math.max(1, contentRows - topPaneHeight);
-      hSepRow = 2 + topPaneHeight; // workspace bar + top tab bar + top content rows
+      hSepRow = 1 + topPaneHeight; // workspace bar + top content rows
     }
 
-    const sepFg = hasPanel && panel!.separator
-      ? (panel!.topFocused || panel!.bottomFocused ? '244' : '238')
-      : '238';
+    const panelFocused = hasPanel && (panel!.topFocused || panel!.bottomFocused);
+    // Per-row left-border color: the focused pane's rows get the accent tone.
+    const borderFgForRow = (i: number): string => {
+      if (!hasPanel || !panel!.separator || !panelFocused) return PANEL_BORDER_DIM;
+      if (!hasBottomPane) return panel!.topFocused ? PANEL_FOCUS_ACCENT : PANEL_BORDER_DIM;
+      if (i === 0) return PANEL_FOCUS_ACCENT; // workspace bar — panel is focused
+      if (i <= topPaneHeight) return panel!.topFocused ? PANEL_FOCUS_ACCENT : PANEL_BORDER_DIM;
+      return panel!.bottomFocused ? PANEL_FOCUS_ACCENT : PANEL_BORDER_DIM;
+    };
 
     viewport.forEach((line, i) => {
       const screenY = viewportStartY + i;
@@ -163,9 +173,10 @@ export class Compositor {
 
         const p = panel!;
 
-        // Separator column (vertical bar between left and panel area)
+        // Separator column (vertical bar between left and panel area).
+        // Colored per-row so the focused pane shows a bright accent border.
         if (p.separator) {
-          newBuffer.setCell(sepX, screenY, createStyledCell('│', { fg: sepFg }));
+          newBuffer.setCell(sepX, screenY, createStyledCell('│', { fg: borderFgForRow(i) }));
         }
 
         const panelStartX = sepX + 1;
@@ -195,39 +206,31 @@ export class Compositor {
           const panelLine = i === 0 ? p.workspaceBar : p.topContent[i - 1];
           drawPanelLine(panelLine);
         } else {
-          // --- Two pane mode ---
+          // --- Two pane mode (single consolidated workspace bar) ---
           // Row layout (by viewport row i):
           //   i = 0:                      workspace tab bar
-          //   i = 1:                      top tab bar
-          //   2 <= i <= topPaneHeight+1:  top content[i-2]
+          //   1 <= i <= topPaneHeight:    top content[i-1]
           //   i = hSepRow:                horizontal separator
-          //   i = hSepRow+1:              bottom tab bar
-          //   i >= hSepRow+2:             bottom content[i - (hSepRow+2)]
+          //   i >= hSepRow+1:             bottom content[i - (hSepRow+1)]
           let panelLine: Line | undefined;
 
           if (i === 0) {
             panelLine = p.workspaceBar;
-          } else if (i === 1) {
-            panelLine = p.topTabBar;
-          } else if (i <= topPaneHeight + 1) {
-            panelLine = p.topContent[i - 2];
+          } else if (i <= topPaneHeight) {
+            panelLine = p.topContent[i - 1];
           } else if (i === hSepRow) {
-            // Horizontal separator between the two panes
-            // Render ─ chars across the panel width
-            const focusFg = p.bottomFocused ? '36' : '238'; // cyan if bottom pane focused
+            // Horizontal separator between the two panes. Accent when the bottom
+            // pane has focus so the divider reinforces the focus border.
+            const focusFg = p.bottomFocused ? PANEL_FOCUS_ACCENT : PANEL_BORDER_DIM;
             for (let x = 0; x < panelWidth; x++) {
               newBuffer.setCell(panelStartX + x, screenY, createStyledCell('─', { fg: focusFg }));
             }
-            // Also update the separator column char to T-junction (├):
-            // ├ connects the vertical left-separator with the horizontal pane divider,
-            // forming a clean T-shaped joint at the split point.
+            // T-junction (├) joins the vertical left-border with the pane divider.
             if (p.separator) {
               newBuffer.setCell(sepX, screenY, createStyledCell('├', { fg: focusFg }));
             }
-          } else if (i === hSepRow + 1) {
-            panelLine = p.bottomTabBar;
           } else {
-            panelLine = p.bottomContent?.[i - (hSepRow + 2)];
+            panelLine = p.bottomContent?.[i - (hSepRow + 1)];
           }
 
           if (i !== hSepRow) {
@@ -269,7 +272,7 @@ export class Compositor {
       for (let i = viewport.length; i < vHeight; i++) {
         const screenY = viewportStartY + i;
         if (screenY >= height) break;
-        newBuffer.setCell(sepX, screenY, createStyledCell('│', { fg: sepFg }));
+        newBuffer.setCell(sepX, screenY, createStyledCell('│', { fg: borderFgForRow(i) }));
       }
     }
 

package/src/renderer/conversation-overlays.ts

@@ -40,12 +40,21 @@ export function applyConversationOverlays(
   let next = viewport;
   const bottomDockInset = 1 + (input.searchManager.active || input.historySearch.active ? 1 : 0);
 
+  // Overlay posture rule: workspaces (onboarding, model, settings, mcp, help,
+  // shortcuts) claim the full viewport and are mutually exclusive with docked
+  // pickers/modals. Once a fullscreen workspace claims the screen, no docked
+  // overlay is drawn on top of it — enforcing a single visible overlay even if
+  // stray state survives the handler's clearModalStack. The input layer keeps
+  // the modal stack to one entry; this is the renderer-side backstop.
+  let fullscreenClaimed = false;
+
   if (input.onboardingWizard.active) {
     const lines = renderOnboardingWizard(input.onboardingWizard, conversationWidth, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
-  if (input.filePicker.active) {
+  if (!fullscreenClaimed && input.filePicker.active) {
     const lines = renderFilePickerOverlay(input.filePicker, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
@@ -53,9 +62,10 @@ export function applyConversationOverlays(
   if (input.modelPicker.active) {
     const lines = renderModelWorkspace(input.modelPicker, conversationWidth, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
-  if (input.selectionModal.active) {
+  if (!fullscreenClaimed && input.selectionModal.active) {
     const lines = renderSelectionModalOverlay(input.selectionModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
@@ -68,22 +78,22 @@ export function applyConversationOverlays(
     next.push(...renderHistorySearchOverlay(input.historySearch, conversationWidth));
   }
 
-  if (input.processModal.active) {
+  if (!fullscreenClaimed && input.processModal.active) {
     const lines = renderProcessModal(input.processModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.agentDetailModal.active) {
-    const lines = renderAgentDetailModal(input.agentDetailModal, conversationWidth);
+  if (!fullscreenClaimed && input.agentDetailModal.active) {
+    const lines = renderAgentDetailModal(input.agentDetailModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.liveTailModal.active) {
+  if (!fullscreenClaimed && input.liveTailModal.active) {
     const lines = renderLiveTailModal(input.liveTailModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.contextInspectorModal.active) {
+  if (!fullscreenClaimed && input.contextInspectorModal.active) {
     const lines = renderContextInspector(conversation, conversationWidth, viewportHeight, contextWindow);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
@@ -91,24 +101,26 @@ export function applyConversationOverlays(
   if (input.settingsModal.active) {
     const lines = renderSettingsModal(input.settingsModal, conversationWidth, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
   if (input.mcpWorkspace.active) {
     const lines = renderMcpWorkspace(input.mcpWorkspace, conversationWidth, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
-  if (input.sessionPickerModal.active) {
+  if (!fullscreenClaimed && input.sessionPickerModal.active) {
     const lines = renderSessionPickerModal(input.sessionPickerModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.profilePickerModal.active) {
+  if (!fullscreenClaimed && input.profilePickerModal.active) {
     const lines = renderProfilePickerModal(input.profilePickerModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.bookmarkModal.active) {
+  if (!fullscreenClaimed && input.bookmarkModal.active) {
     const lines = renderBookmarkModal(input.bookmarkModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
@@ -116,14 +128,16 @@ export function applyConversationOverlays(
   if (input.helpOverlayActive) {
     const lines = renderHelpOverlay(conversationWidth, keybindingsManager, commandRegistry.getAll(), input.helpScrollOffset, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
   if (input.shortcutsOverlayActive) {
     const lines = renderShortcutsOverlay(conversationWidth, keybindingsManager, input.shortcutsScrollOffset, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
-  if (input.commandMode && input.autocomplete?.isActive) {
+  if (!fullscreenClaimed && input.commandMode && input.autocomplete?.isActive) {
     const lines = renderAutocompleteOverlay(input.autocomplete, conversationWidth, viewportHeight);
     if (lines.length > 0) {
       next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);

package/src/renderer/footer-tips.ts

@@ -0,0 +1,41 @@
+/**
+ * footer-tips.ts — the persistent discoverability hint shown in the shell
+ * footer's tip slot.
+ *
+ * WO-151: instead of a single frozen "/help for commands" line, the footer
+ * surfaces a rotating set of the highest-value affordances (panels, process
+ * monitor, help, quit). Rotation is *contextual, not timed*: when an agent turn
+ * is actively running, the process-monitor tip is promoted to the front so the
+ * operator can jump to F2 while work is in flight. Selection is a pure function
+ * of context so the footer renders deterministically (golden frames stay
+ * stable) — no wall-clock input.
+ */
+
+export interface FooterTipContext {
+  /** True while an agent turn is actively running (streaming / tools / hooks). */
+  readonly agentActive: boolean;
+}
+
+/** Composer status labels that mean an agent turn is actively in flight. */
+const ACTIVE_TURN_STATUSES = new Set(['preflight', 'streaming', 'tools', 'post-hooks']);
+
+/** Derive agent-active state from the composer status label passed to the footer. */
+export function isAgentActive(composerStatus: string | undefined): boolean {
+  return composerStatus !== undefined && ACTIVE_TURN_STATUSES.has(composerStatus);
+}
+
+const TIP_PANELS = 'Ctrl+P panels';
+const TIP_PROCESSES = 'F2 processes';
+const TIP_HELP = '? help';
+const TIP_QUIT = 'Ctrl+C quit';
+
+/**
+ * Build the footer discoverability tip. Segments join with the shared middle
+ * dot. Agent-active state promotes the process-monitor tip to the front.
+ */
+export function buildFooterTip(ctx: FooterTipContext): string {
+  const lead = ctx.agentActive
+    ? [TIP_PROCESSES, TIP_PANELS, TIP_HELP]
+    : [TIP_PANELS, TIP_PROCESSES, TIP_HELP];
+  return [...lead, TIP_QUIT].join(' · ');
+}

package/src/renderer/fullscreen-primitives.ts

@@ -1,24 +1,30 @@
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { getDisplayWidth } from '../utils/terminal-width.ts';
-import { GLYPHS, UI_TONES } from './ui-primitives.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import { resolveUiTones } from './theme.ts';
+
+// FULLSCREEN_PALETTE is built from the mode-resolved chrome tones
+// (resolveUiTones) rather than the static UI_TONES constant — WO-001 single
+// read path. Mode is fixed to 'dark' until the terminal-bg-probe lands.
+const TONES = resolveUiTones('dark');
 
 export const FULLSCREEN_PALETTE = {
-  border: '#64748b',
-  title: '#67e8f9',
-  subtitle: '#93c5fd',
-  text: '#e2e8f0',
-  muted: '#94a3b8',
-  dim: '#64748b',
-  selectedBg: '#223049',
-  categoryBg: '#141b25',
-  contextBg: '#121923',
-  controlsBg: '#0f141d',
-  footerBg: '#111827',
-  good: UI_TONES.state.good,
-  warn: UI_TONES.state.warn,
-  bad: UI_TONES.state.bad,
-  info: UI_TONES.state.info,
+  border: TONES.border,
+  title: TONES.accent.browser,
+  subtitle: TONES.accent.conversation,
+  text: TONES.fg.primary,
+  muted: TONES.fg.muted,
+  dim: TONES.border,
+  selectedBg: TONES.bg.selected,
+  categoryBg: TONES.bg.section,
+  contextBg: TONES.bg.surface,
+  controlsBg: TONES.bg.base,
+  footerBg: TONES.bg.footer,
+  good: TONES.state.good,
+  warn: TONES.state.warn,
+  bad: TONES.state.bad,
+  info: TONES.state.info,
 } as const;
 
 export type FullscreenTextStyle = Partial<Omit<Line[number], 'char'>>;

package/src/renderer/help-overlay.ts

@@ -10,6 +10,7 @@ import type { SlashCommand } from '../input/command-registry.ts';
 import type { KeybindingsManager } from '../input/keybindings.ts';
 import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
 import { getVisibleWindow } from './surface-layout.ts';
+import { formatHints } from './hint-grammar.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
 function toModalSections(rows: readonly string[]): import('./modal-factory.ts').ModalSection[] {
@@ -40,7 +41,28 @@ export function renderHelpOverlay(
 ): Line[] {
   const kb = (action: Parameters<typeof keybindingsManager.getComboLabel>[0]) => keybindingsManager.getComboLabel(action);
 
-  const hasCommand = (name: string): boolean => Boolean(commands?.some((command) => command.name === name || (command.aliases ?? []).includes(name)));
+  const hasCommand = (name: string): boolean => {
+    if (!commands) return false;
+    for (const command of commands) {
+      // A broken plugin may expose a throwing `aliases` getter; skip it rather
+      // than crash the overlay (mirrors the Quick Start traversal guard below).
+      try {
+        if (command.name === name || (command.aliases ?? []).includes(name)) return true;
+      } catch { /* skip this command */ }
+    }
+    return false;
+  };
+
+  const shortcutLine = (label: string, desc: string): string => `  ${label.padEnd(20)}  ${desc}`;
+
+  // Enumerate EVERY workspace/panel binding straight from the live keybindings
+  // table so each rebindable action (including user overrides) is discoverable
+  // here and stays in lockstep with /keybindings. Any action id prefixed
+  // `panel-` is a workspace affordance.
+  const panelBindingRows: string[] = keybindingsManager
+    .getAll()
+    .filter((entry) => entry.action.startsWith('panel-'))
+    .map((entry) => shortcutLine(keybindingsManager.getComboLabel(entry.action), entry.description));
 
   // Keyboard shortcut sections
   const shortcutRows: string[] = [
@@ -59,9 +81,20 @@ export function renderHelpOverlay(
     '',
     '  Overlays And Panels',
     '  ' + '\u2500'.repeat(40),
-    `  ${'?'.padEnd(20)}  Toggle help`,
-    `  ${'/shortcuts'.padEnd(20)}  Full keyboard shortcuts`,
-    `  ${kb('panel-picker').padEnd(20)}  Open or focus the panel workspace`,
+    shortcutLine('?', 'Toggle help'),
+    shortcutLine('/shortcuts', 'Full keyboard shortcuts'),
+    shortcutLine('Tab', 'Swap focus between input and workspace'),
+    ...panelBindingRows,
+    '',
+    // The shared in-panel contract every workspace panel honors. These are not
+    // rebindable global actions \u2014 they are the common controls a focused panel
+    // interprets \u2014 so they are documented here rather than pulled from getAll().
+    '  In-Panel Controls',
+    '  ' + '\u2500'.repeat(40),
+    shortcutLine('j / k', 'Move selection down / up'),
+    shortcutLine('g / G', 'Jump to top / bottom'),
+    shortcutLine('Enter / Esc', 'Activate / dismiss or leave panel'),
+    shortcutLine('/', 'Filter the list'),
     '',
   ];
 
@@ -109,7 +142,33 @@ export function renderHelpOverlay(
     }
   }
 
+  // Essentials \u2014 the handful of commands worth memorizing, listed first and
+  // filtered to what the live registry actually exposes.
+  const ESSENTIAL_COMMANDS: Array<[name: string, desc: string]> = [
+    ['model',       'Select provider or model'],
+    ['sessions',    'Browse and resume saved sessions'],
+    ['save',        'Save the current session'],
+    ['compact',     'Compact the conversation history'],
+    ['clear',       'Clear the conversation'],
+    ['keybindings', 'List and customize key bindings'],
+    ['panel',       'Open, focus, or manage panels'],
+  ];
+
   const commandRows: string[] = [];
+  // Track command names already surfaced in a curated group so the exhaustive
+  // list below does not repeat them.
+  const seen = new Set<string>();
+
+  const essentialRows: string[] = [];
+  for (const [name, desc] of ESSENTIAL_COMMANDS) {
+    if (!hasCommand(name)) continue;
+    seen.add(name);
+    essentialRows.push(`  ${`/${name}`.padEnd(18)}  ${desc}`);
+  }
+  if (essentialRows.length > 0) {
+    commandRows.push('  Essentials', '  ' + '\u2500'.repeat(40), ...essentialRows, '');
+  }
+
   if (quickStartRows.length > 0) {
     commandRows.push('  Quick Start', '  ' + '\u2500'.repeat(40), ...quickStartRows, '');
   }
@@ -117,18 +176,18 @@ export function renderHelpOverlay(
   if (commands && commands.length > 0) {
     commandRows.push('', '  Available Slash Commands', '  ' + '\u2500'.repeat(40));
     const preferred = ['setup', 'cockpit', 'settings', 'provider', 'subscription', 'marketplace', 'remote', 'sandbox', 'security', 'policy', 'incident', 'knowledge', 'hooks', 'orchestration', 'communication', 'tasks'];
-    const seen = new Set<string>();
     for (const name of preferred) {
       const cmd = commands.find((entry) => entry.name === name);
-      if (!cmd) continue;
+      if (!cmd || seen.has(cmd.name)) continue;
       seen.add(cmd.name);
       const nameCol = `/${cmd.name}`.padEnd(18);
       commandRows.push(`  ${nameCol}  ${cmd.description}`);
     }
+    // No command cap: the overlay windows and scrolls (getVisibleWindow below),
+    // so the full remaining registry is listed rather than truncated at 24.
     const remainder = [...commands]
       .filter((cmd) => !seen.has(cmd.name))
-      .sort((a, b) => a.name.localeCompare(b.name))
-      .slice(0, 24);
+      .sort((a, b) => a.name.localeCompare(b.name));
     if (remainder.length > 0) {
       commandRows.push('', '  More Commands', '  ' + '\u2500'.repeat(40));
       for (const cmd of remainder) {
@@ -163,15 +222,19 @@ export function renderHelpOverlay(
       width: metrics.boxWidth,
       margin: metrics.margin,
       targetContentRows: metrics.contentRows,
-      tabs: [
-        { label: 'Overview', active: true },
-        { label: 'Commands' },
-      ],
+      // Single tab: the old second 'Commands' tab had no switch handler (Left/
+      // Right did nothing), so it was a dead affordance. The overlay is one
+      // scrolling surface, so it advertises exactly one tab.
+      tabs: [{ label: 'Overview', active: true }],
       sections: toModalSections(visibleRows),
       helpers: allRows.length > maxVisible
         ? [{ content: `[${window.start + 1}-${Math.min(allRows.length, clampedOffset + visibleRows.length)} of ${allRows.length}]` }]
         : undefined,
-      hints: ['? or Esc Close', 'Up/Down Scroll'],
+      hints: [formatHints([
+        { key: 'Up/Down', verb: 'Scroll' },
+        { key: '?', verb: 'Help' },
+        { key: 'Esc', verb: 'Close' },
+      ])],
     },
     width,
   );
@@ -236,6 +299,17 @@ export function renderShortcutsOverlay(
     row(kb('panel-picker'), 'Open / focus / hide panel workspace'),
     row(kb('panel-tab-next'), 'Next workspace panel tab'),
     row(kb('panel-tab-prev'), 'Previous workspace panel tab'),
+    row(`${kb('panel-tab-1')}\u2026${kb('panel-tab-9')}`, 'Jump to workspace tab 1-9'),
+    row(kb('panel-focus-toggle'), 'Swap focus between top / bottom pane'),
+    row(kb('panel-close'), 'Close active panel'),
+    row(kb('panel-close-all'), 'Close all panels'),
+    row(kb('panel-ops'), 'Open the Ops Control panel'),
+    '',
+    '  In-Panel Controls',
+    '  ' + '\u2500'.repeat(40),
+    row('j / k', 'Move selection down / up'),
+    row('g / G', 'Jump to top / bottom'),
+    row('/', 'Filter the list'),
     '',
     `  Config: /keybindings to list and customize`,
   ];
@@ -261,7 +335,10 @@ export function renderShortcutsOverlay(
       helpers: allRows.length > maxVisible
         ? [{ content: `[${window.start + 1}-${Math.min(allRows.length, clampedOffset + visibleRows.length)} of ${allRows.length}]` }]
         : undefined,
-      hints: ['Esc Close', 'Up/Down Scroll'],
+      hints: [formatHints([
+        { key: 'Up/Down', verb: 'Scroll' },
+        { key: 'Esc', verb: 'Close' },
+      ])],
     },
     width,
   );

package/src/renderer/hint-grammar.ts

@@ -0,0 +1,52 @@
+/**
+ * hint-grammar.ts — the single hint-bar grammar for every overlay footer.
+ *
+ * WO-151: one grammar across the model picker, settings modal, help/shortcuts
+ * overlays, and ModalFactory variants so footers stop drifting into three
+ * different dialects (verbless brackets, prose sentences, ad-hoc separators).
+ *
+ * The grammar is:
+ *   - each hint renders as `[Key] Verb` (a bracketed key followed by its verb),
+ *   - hints are joined by a middle-dot separator (` · `),
+ *   - any Escape hint is always sorted last (the conventional "way out").
+ *
+ * State segments that are not key hints (e.g. `Filter: All`) can be appended
+ * verbatim via {@link joinHints}; they are never reordered.
+ */
+
+/** A single key hint. `verb` may be omitted for a bare key affordance. */
+export interface HintSpec {
+  key: string;
+  verb?: string;
+}
+
+/** The canonical separator between hint segments. */
+export const HINT_SEPARATOR = ' · ';
+
+function isEscapeHint(spec: HintSpec): boolean {
+  return spec.key.trim().toLowerCase() === 'esc';
+}
+
+/** Render one hint as `[Key] Verb` (or `[Key]` when it has no verb). */
+export function formatHint(spec: HintSpec): string {
+  return spec.verb ? `[${spec.key}] ${spec.verb}` : `[${spec.key}]`;
+}
+
+/**
+ * Format a list of key hints into a single footer string using the shared
+ * grammar. Escape hints are moved to the end (stable for everything else).
+ */
+export function formatHints(specs: readonly HintSpec[]): string {
+  // Stable partition: non-escape hints keep their order, escape hints trail.
+  const ordered = [...specs].sort((a, b) => Number(isEscapeHint(a)) - Number(isEscapeHint(b)));
+  return ordered.map(formatHint).join(HINT_SEPARATOR);
+}
+
+/**
+ * Join already-rendered segments (hint bars, state tags) with the shared
+ * separator, dropping empties. Order is preserved — use this to append state
+ * indicators after a {@link formatHints} bar.
+ */
+export function joinHints(...segments: Array<string | null | undefined>): string {
+  return segments.filter((s): s is string => !!s && s.length > 0).join(HINT_SEPARATOR);
+}

package/src/renderer/layout.ts

@@ -1,4 +1,4 @@
-import { GLYPHS } from './ui-primitives.ts';
+import { GLYPHS, SPINNER_FRAMES, UI_TONES } from './ui-primitives.ts';
 
 /**
  * Layout constants — single source of truth for margins and content width.
@@ -14,19 +14,19 @@ export const LAYOUT = {
 
 export const TOOL_STATUS = {
   SUCCESS_ICON: GLYPHS.status.success,
-  SPINNER_FRAMES: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  SPINNER_FRAMES,
   FAIL_ICON: GLYPHS.status.failure,
   PENDING_ICON: GLYPHS.status.pending,
   TOOL_NAME_PAD: 8,
 } as const;
 
 export const COLORS = {
-  DIM_TEXT: '244',
+  DIM_TEXT: UI_TONES.fg.dim,
 } as const;
 
 export const BORDERS = {
-  THINKING: { char: '▌', color: '#9945FF' },
-  ERROR:    { char: '▌', color: '#ef4444' },
-  WARNING:  { char: '▌', color: '#eab308' },
-  INFO:     { char: '▌', color: '#22d3ee' },
+  THINKING: { char: '▌', color: UI_TONES.state.reasoning },
+  ERROR:    { char: '▌', color: UI_TONES.state.bad },
+  WARNING:  { char: '▌', color: UI_TONES.state.warn },
+  INFO:     { char: '▌', color: UI_TONES.state.info },
 } as const;