@pi-unipi/footer 0.1.3 → 0.1.4

package/README.md

@@ -1,78 +1,65 @@
 # @pi-unipi/footer
 
-Persistent status bar for the Unipi extension suite.
+Persistent status bar at the bottom of the terminal. Shows live stats from all Unipi packages — compactor tokens saved, memory count, MCP status, Ralph loops, workflow state, kanboard tasks, notifications.
 
-Subscribes to `UNIPI_EVENTS` and renders key stats from all unipi packages using pi's `setFooter` + `setWidget` APIs with responsive layout, presets, and per-segment toggling.
+Subscribes to events from every package and renders segments using Pi's `setFooter` + `setWidget` APIs. Responsive layout adjusts to terminal width, with a secondary row for narrow terminals.
 
-## Features
+## Commands
 
-- **Persistent status bar** — always-visible footer showing key stats from all unipi packages
-- **Segment groups** — organized by package (core, compactor, memory, MCP, ralph, workflow, kanboard, notify)
-- **Presets** — default, minimal, compact, full, nerd, ascii
-- **Responsive layout** — adjusts to terminal width with secondary row overflow
-- **Per-segment toggling** — enable/disable individual segments or entire groups
-- **Theme integration** — uses pi's theme system with semantic colors
-- **Nerd Font support** — auto-detection with ASCII fallback
-- **Separator styles** — powerline, powerline-thin, slash, pipe, dot, ascii
+| Command | Description |
+|---------|-------------|
+| `/unipi:footer` | Toggle footer on/off |
+| `/unipi:footer <preset>` | Switch preset (default, minimal, compact, full, nerd, ascii) |
+| `/unipi:footer sep:<style>` | Change separator style |
+| `/unipi:footer icon:<style>` | Change icon style (nerd, emoji, text) |
+| `/unipi:footer on` / `/unipi:footer off` | Enable/disable explicitly |
+| `/unipi:footer-settings` | Open settings TUI for per-group/per-segment toggles |
 
-## Architecture
+## Special Triggers
 
-```
-┌─────────────────────────────────────────────────────┐
-│  FooterRenderer (setFooter + setWidget)             │  ← Renders to screen
-│  - Responsive layout (top + secondary rows)          │
-│  - Preset system, separators, theming                │
-├─────────────────────────────────────────────────────┤
-│  FooterRegistry (segment groups)                     │  ← Manages segments
-│  - Subscribes to UNIPI_EVENTS                       │
-│  - Per-segment enable/disable                       │
-│  - Reactive data caching                            │
-├─────────────────────────────────────────────────────┤
-│  Event Sources (existing packages)                   │  ← Data providers
-│  - compactor, memory, workflow, ralph, mcp,          │
-│    kanboard, notify, core                           │
-└─────────────────────────────────────────────────────┘
-```
+Footer subscribes to events from every Unipi package:
 
-## Usage
+| Group | Events | Segments |
+|-------|--------|----------|
+| core | Pi SDK | model, thinking, path, git, context_pct, cost, tokens, session |
+| compactor | `COMPACTOR_STATS_UPDATED` | session_events, compactions, tokens_saved, compression_ratio |
+| memory | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` | project_count, total_count, consolidations |
+| mcp | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` | servers_total, servers_active, tools_total |
+| ralph | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` | active_loops, total_iterations, loop_status |
+| workflow | `WORKFLOW_START`/`END` | current_command, sandbox_level, command_duration |
+| kanboard | Direct registry read | docs_count, tasks_done, tasks_total, task_pct |
+| notify | `NOTIFICATION_SENT` | platforms_enabled, last_sent |
 
-The footer is automatically enabled when unipi loads. Use commands to control it:
+Footer works even if packages load after it — late-arriving events update the cache.
 
-- `/unipi:footer` — toggle footer on/off
-- `/unipi:footer <preset>` — switch preset (default, minimal, compact, full, nerd, ascii)
-- `/unipi:footer sep:<style>` — change separator style (powerline, powerline-thin, slash, pipe, dot, ascii)
-- `/unipi:footer icon:<style>` — change icon style (nerd, emoji, text)
-- `/unipi:footer on` / `/unipi:footer off` — enable/disable explicitly
-- `/unipi:footer-settings` — open settings TUI for per-group/per-segment toggles
-
-## Segment Groups
+## Presets
 
-| Group | Segments | Default | Data Source |
-|-------|----------|---------|-------------|
-| **core** | `model`, `thinking`, `path`, `git`, `context_pct`, `cost`, `tokens_total`, `tokens_in`, `tokens_out`, `session`, `hostname`, `time` | ON (except hostname, time, tokens variants) | pi SDK (ctx.sessionManager, footerData) |
-| **compactor** | `session_events`, `compactions`, `tokens_saved`, `compression_ratio`, `indexed_docs`, `sandbox_runs`, `search_queries` | ON (key stats only) | `COMPACTOR_STATS_UPDATED` event |
-| **memory** | `project_count`, `total_count`, `consolidations` | ON | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` events |
-| **mcp** | `servers_total`, `servers_active`, `tools_total`, `servers_failed` | ON | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` events |
-| **ralph** | `active_loops`, `total_iterations`, `loop_status` | ON | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` events |
-| **workflow** | `current_command`, `sandbox_level`, `command_duration` | ON | `WORKFLOW_START`/`END` events |
-| **kanboard** | `docs_count`, `tasks_done`, `tasks_total`, `task_pct` | ON | Kanboard registry (direct read) |
-| **notify** | `platforms_enabled`, `last_sent` | OFF | `NOTIFICATION_SENT` event |
-| **status_ext** | `extension_statuses` | ON | `footerData.getExtensionStatuses()` |
+| Preset | Description |
+|--------|-------------|
+| `default` | Balanced: model, thinking, path, git, context, cost + compactor + memory + ralph |
+| `minimal` | Essentials only: path, git, context |
+| `compact` | Core + key stats: model, git, cost, context + compactor + memory |
+| `full` | Everything from all groups |
+| `nerd` | Full + hostname + time + session + extensions |
+| `ascii` | Core segments with ASCII icons |
 
-## Presets
+## Segment Groups
 
-| Preset | Description | Key Segments |
-|--------|-------------|-------------|
-| `default` | Balanced view | model, thinking, path, git, context, cost + compactor + memory + ralph |
-| `minimal` | Just the essentials | path, git, context |
-| `compact` | Core + key stats | model, git, cost, context + compactor + memory |
-| `full` | Everything | All segments from all groups |
-| `nerd` | Maximum detail for Nerd Font users | full + hostname + time + session + extensions |
-| `ascii` | Safe for any terminal | Core segments with ASCII icons |
+| Group | Default | Data Source |
+|-------|---------|-------------|
+| **core** | ON | Pi SDK (ctx.sessionManager, footerData) |
+| **compactor** | ON | `COMPACTOR_STATS_UPDATED` event |
+| **memory** | ON | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` events |
+| **mcp** | ON | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` events |
+| **ralph** | ON | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` events |
+| **workflow** | ON | `WORKFLOW_START`/`END` events |
+| **kanboard** | ON | Kanboard registry (direct read) |
+| **notify** | OFF | `NOTIFICATION_SENT` event |
+| **status_ext** | ON | `footerData.getExtensionStatuses()` |
 
-## Configuration
+## Configurables
 
-Settings are stored in `~/.pi/agent/settings.json` under `unipi.footer`:
+Settings in `~/.pi/agent/settings.json` under `unipi.footer`:
 
 ```json
 {
@@ -88,19 +75,7 @@ Settings are stored in `~/.pi/agent/settings.json` under `unipi.footer`:
           "segments": {
             "session_events": true,
             "compactions": true,
-            "tokens_saved": true,
-            "compression_ratio": false,
-            "indexed_docs": false,
-            "sandbox_runs": false,
-            "search_queries": false
-          }
-        },
-        "memory": {
-          "show": true,
-          "segments": {
-            "project_count": true,
-            "total_count": true,
-            "consolidations": false
+            "tokens_saved": true
           }
         }
       }
@@ -109,98 +84,38 @@ Settings are stored in `~/.pi/agent/settings.json` under `unipi.footer`:
 }
 ```
 
-## Responsive Layout
+### Separator Styles
 
-```
-Wide terminal (>120 cols):
-  ┌─ model │ thinking │ path │ git │ context │ cost │ compactions │ tokens_saved │ project_count ─┐
-  └──────────────────────────────────────────────────────────────────────────────────────────────┘
+| Style | Look |
+|-------|------|
+| `powerline` | Thick powerline arrows |
+| `powerline-thin` | Thin powerline arrows (default) |
+| `slash` | / |
+| `pipe` | \| |
+| `dot` | Middle dot |
+| `ascii` | > < |
 
-Narrow terminal (<120 cols):
-  ┌─ model │ thinking │ path │ git │ context │ cost ───────────────────────────────────────────────┐
-  └─ compactions │ tokens_saved │ project_count │ ralph │ workflow ────────────────────────────────┘
-```
-
-## Separator Styles
-
-| Style | Look | Description |
-|-------|------|-------------|
-| `powerline` | ◀ ▶ | Thick powerline arrows |
-| `powerline-thin` |   | Thin powerline arrows (default) |
-| `slash` | / | Slash separator |
-| `pipe` | \| | Pipe separator |
-| `dot` | · | Middle dot separator |
-| `ascii` | > < | ASCII angle brackets |
-
-## Icon Styles
-
-Three icon styles are available, controlled by `/unipi:footer icon:<style>` or the `iconStyle` setting:
-
-| Style | Description | Example |
--------|-------------|--------|
-| `nerd` | Nerd Font glyphs (default, requires Nerd Font terminal) |  , ,  |
-| `emoji` | Unicode emoji/symbols (works on most terminals) | ⚡, ◧, $] |
-| `text` | Plain text abbreviations (works everywhere, most compact) | evt, cmp, $] |
+### Icon Styles
 
-When `iconStyle` is not explicitly set, the footer auto-detects Nerd Font support and
-defaults to `nerd` if available, `emoji` otherwise.
+| Style | Description |
+|-------|-------------|
+| `nerd` | Nerd Font glyphs (auto-detected) |
+| `emoji` | Unicode symbols (works on most terminals) |
+| `text` | Plain text abbreviations (works everywhere) |
 
-## Error Handling
+When `iconStyle` is not set, footer auto-detects Nerd Font support and defaults to `nerd` if available, `emoji` otherwise.
 
-- **Event subscription failures:** Each handler wrapped in try/catch — one failing handler doesn't break others
-- **Data provider failures:** Segments hide when data unavailable (graceful degradation)
-- **Config parse failures:** Fall back to default preset with warning
-- **Module loading order:** Footer works even if packages load after it — late-arriving events update cache
+### Responsive Layout
 
-## Development
-
-```bash
-# Run tests
-pnpm test
+```
+Wide terminal (>120 cols):
+  model | thinking | path | git | context | cost | compactions | tokens_saved | project_count
 
-# Type check
-pnpm tsc --noEmit
+Narrow terminal (<120 cols):
+  Row 1: model | thinking | path | git | context | cost
+  Row 2: compactions | tokens_saved | project_count | ralph | workflow
 ```
 
-## Package Structure
+## License
 
-```
-packages/footer/
-├── index.ts          # Re-exports
-├── types.ts          # Re-exports from src/types.ts
-├── package.json      # Package manifest
-├── tsconfig.json     # TypeScript config
-├── README.md         # This file
-├── src/
-│   ├── index.ts          # Extension entry point
-│   ├── types.ts          # Type definitions
-│   ├── config.ts         # Settings load/save
-│   ├── events.ts         # Event subscription wiring
-│   ├── commands.ts       # Command registration
-│   ├── presets.ts        # Preset definitions
-│   ├── registry/         # FooterRegistry
-│   │   └── index.ts
-│   ├── rendering/        # Rendering engine
-│   │   ├── renderer.ts   # FooterRenderer class
-│   │   ├── separators.ts # Separator system
-│   │   ├── theme.ts      # Theme color resolution
-│   │   └── icons.ts      # Icon system with Nerd Font detection
-│   ├── segments/         # Segment implementations
-│   │   ├── core.ts       # Core segments (model, path, git, etc.)
-│   │   ├── compactor.ts  # Compactor segments
-│   │   ├── memory.ts     # Memory segments
-│   │   ├── mcp.ts        # MCP segments
-│   │   ├── ralph.ts      # Ralph segments
-│   │   ├── workflow.ts   # Workflow segments
-│   │   ├── kanboard.ts   # Kanboard segments
-│   │   ├── notify.ts     # Notify segments
-│   │   └── status-ext.ts # Extension statuses segment
-│   └── tui/
-│       └── settings-tui.ts # Settings overlay TUI
-└── tests/               # Unit tests
-    ├── separators.test.ts
-    ├── registry.test.ts
-    ├── config.test.ts
-    ├── segments.test.ts
-    └── events.test.ts
-```
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
   "type": "module",
   "license": "MIT",

package/src/commands.ts

@@ -8,34 +8,9 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { UNIPI_PREFIX, FOOTER_COMMANDS } from "@pi-unipi/core";
 import { loadFooterSettings, saveFooterSettings } from "./config.js";
-import { PRESET_NAMES } from "./presets.js";
 import { showFooterSettings } from "./tui/settings-tui.js";
-import type { FooterGroup, SeparatorStyle, IconStyle } from "./types.js";
-import { setIconStyle } from "./rendering/icons.js";
-
-/** Minimal autocomplete item (compatible with pi-tui AutocompleteItem) */
-interface ArgSuggestion {
-  value: string;
-  label: string;
-  description?: string;
-}
-
-/** All valid separator styles */
-const SEPARATOR_STYLES: SeparatorStyle[] = [
-  "powerline",
-  "powerline-thin",
-  "slash",
-  "pipe",
-  "dot",
-  "ascii",
-];
-
-/** All valid icon styles */
-const ICON_STYLES: IconStyle[] = [
-  "nerd",
-  "emoji",
-  "text",
-];
+import { showFooterHelp } from "./help.js";
+import type { FooterGroup, FooterSegment } from "./types.js";
 
 /** Extension state interface */
 interface FooterState {
@@ -46,6 +21,7 @@ interface FooterState {
     getPresetName(): string;
     resetLayoutCache(): void;
   };
+  segmentLookup: Map<string, FooterSegment>;
   piContext: unknown;
   setupUI: ((pi: ExtensionAPI, ctx: any) => void) | null;
 }
@@ -58,69 +34,13 @@ export function registerCommands(
   state: FooterState,
   groups?: FooterGroup[],
 ): void {
-  // /unipi:footer — toggle or switch preset
+  // /unipi:footer — toggle on/off only
   pi.registerCommand(`${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER}`, {
-    description: "Toggle footer or switch preset (default, minimal, compact, full, nerd, ascii)",
-    getArgumentCompletions(argumentPrefix: string): ArgSuggestion[] | null {
-      const allOptions: ArgSuggestion[] = [
-        ...PRESET_NAMES.map(p => ({
-          value: p,
-          label: p,
-          description: `Switch to ${p} preset`,
-        })),
-        ...SEPARATOR_STYLES.map(s => ({
-          value: `sep:${s}`,
-          label: `sep:${s}`,
-          description: `Set separator style: ${s}`,
-        })),
-        ...ICON_STYLES.map(s => ({
-          value: `icon:${s}`,
-          label: `icon:${s}`,
-          description: `Set icon style: ${s}`,
-        })),
-        {
-          value: "on",
-          label: "on",
-          description: "Enable footer",
-        },
-        {
-          value: "off",
-          label: "off",
-          description: "Disable footer",
-        },
-      ];
-
-      if (!argumentPrefix) return allOptions;
-
-      const prefix = argumentPrefix.toLowerCase();
-      const filtered = allOptions.filter(o =>
-        o.value.toLowerCase().startsWith(prefix),
-      );
-      return filtered.length > 0 ? filtered : null;
-    },
+    description: "Toggle footer on/off",
     handler: async (args, ctx) => {
-      if (!args?.trim()) {
-        // Toggle on/off
-        state.enabled = !state.enabled;
-        state.renderer.setActive(state.enabled);
-
-        if (state.enabled) {
-          state.setupUI?.(pi, ctx);
-          ctx.ui.notify("Footer enabled", "info");
-        } else {
-          ctx.ui.setFooter(undefined);
-          ctx.ui.setWidget("footer-top", undefined);
-          ctx.ui.setWidget("footer-secondary", undefined);
-          ctx.ui.notify("Footer disabled", "info");
-        }
+      const arg = args?.trim().toLowerCase();
 
-        saveFooterSettings({ enabled: state.enabled });
-        return;
-      }
-
-      const arg = args.trim().toLowerCase();
-
-      // on / off
+      // on
       if (arg === "on") {
         state.enabled = true;
         state.renderer.setActive(true);
@@ -129,6 +49,8 @@ export function registerCommands(
         ctx.ui.notify("Footer enabled", "info");
         return;
       }
+
+      // off
       if (arg === "off") {
         state.enabled = false;
         state.renderer.setActive(false);
@@ -140,42 +62,21 @@ export function registerCommands(
         return;
       }
 
-      // sep:<style> — change separator
-      if (arg.startsWith("sep:")) {
-        const style = arg.slice(4) as SeparatorStyle;
-        if (SEPARATOR_STYLES.includes(style)) {
-          saveFooterSettings({ separator: style });
-          state.renderer.resetLayoutCache();
-          ctx.ui.notify(`Separator: ${style}`, "info");
-          return;
-        }
-        ctx.ui.notify(`Unknown separator. Available: ${SEPARATOR_STYLES.join(", ")}`, "warning");
-        return;
-      }
-
-      // icon:<style> — change icon style
-      if (arg.startsWith("icon:")) {
-        const style = arg.slice(5) as IconStyle;
-        if (ICON_STYLES.includes(style)) {
-          saveFooterSettings({ iconStyle: style });
-          setIconStyle(style);
-          state.renderer.resetLayoutCache();
-          ctx.ui.notify(`Icon style: ${style}`, "info");
-          return;
-        }
-        ctx.ui.notify(`Unknown icon style. Available: ${ICON_STYLES.join(", ")}`, "warning");
-        return;
-      }
+      // Toggle (no args or unknown args)
+      state.enabled = !state.enabled;
+      state.renderer.setActive(state.enabled);
 
-      // Preset name
-      if (PRESET_NAMES.includes(arg)) {
-        state.renderer.setPreset(arg);
-        saveFooterSettings({ preset: arg });
-        ctx.ui.notify(`Footer preset: ${arg}`, "info");
-        return;
+      if (state.enabled) {
+        state.setupUI?.(pi, ctx);
+        ctx.ui.notify("Footer enabled", "info");
+      } else {
+        ctx.ui.setFooter(undefined);
+        ctx.ui.setWidget("footer-top", undefined);
+        ctx.ui.setWidget("footer-secondary", undefined);
+        ctx.ui.notify("Footer disabled", "info");
       }
 
-      ctx.ui.notify(`Unknown argument. Use a preset (${PRESET_NAMES.join(", ")}), sep:<style>, icon:<style>, on, or off`, "info");
+      saveFooterSettings({ enabled: state.enabled });
     },
   });
 
@@ -189,7 +90,12 @@ export function registerCommands(
       }
 
       if (groups && groups.length > 0) {
-        showFooterSettings(ctx, groups);
+        showFooterSettings(ctx, groups, () => {
+          // Re-read settings and update renderer
+          const updated = loadFooterSettings();
+          state.renderer.setPreset(updated.preset);
+          state.renderer.resetLayoutCache();
+        });
       } else {
         // Fallback: show text summary
         const settings = loadFooterSettings();
@@ -204,4 +110,13 @@ export function registerCommands(
       }
     },
   });
+
+  // /unipi:footer-help — show help overlay
+  pi.registerCommand(`${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER_HELP}`, {
+    description: "Show footer segment guide (icons, labels, descriptions)",
+    handler: async (_args, _ctx) => {
+      const allSegments = Array.from(state.segmentLookup.values());
+      showFooterHelp(pi, allSegments, state.renderer.getPresetName());
+    },
+  });
 }

package/src/config.ts

@@ -17,6 +17,8 @@ export const DEFAULT_FOOTER_SETTINGS: FooterSettings = {
   preset: "default",
   separator: "powerline-thin",
   iconStyle: "nerd",
+  zoneSeparator: "\u2502", // │
+  showFullLabels: false,
   groups: {
     core: { show: true, segments: {} },
     compactor: { show: true, segments: {} },
@@ -92,6 +94,8 @@ export function loadFooterSettings(): FooterSettings {
       preset: typeof footer.preset === "string" ? footer.preset : DEFAULT_FOOTER_SETTINGS.preset,
       separator: isValidSeparator(footer.separator) ? footer.separator as SeparatorStyle : DEFAULT_FOOTER_SETTINGS.separator,
       iconStyle: isValidIconStyle(footer.iconStyle) ? footer.iconStyle as IconStyle : DEFAULT_FOOTER_SETTINGS.iconStyle,
+      zoneSeparator: typeof footer.zoneSeparator === "string" ? footer.zoneSeparator : DEFAULT_FOOTER_SETTINGS.zoneSeparator,
+      showFullLabels: typeof footer.showFullLabels === "boolean" ? footer.showFullLabels : DEFAULT_FOOTER_SETTINGS.showFullLabels,
       groups: mergeGroupSettings(
         DEFAULT_FOOTER_SETTINGS.groups,
         footer.groups as Record<string, FooterGroupSettings> | undefined,

package/src/help.ts

@@ -0,0 +1,160 @@
+/**
+ * @pi-unipi/footer — Footer help overlay
+ *
+ * Shows an overlay listing all enabled segments grouped by zone,
+ * with icons, short labels, and descriptions.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FooterSegment, SegmentZone } from "./types.js";
+import { getIcon } from "./rendering/icons.js";
+import { loadFooterSettings, isSegmentEnabled } from "./config.js";
+import { getPreset } from "./presets.js";
+
+/** Zone display names and order */
+const ZONE_META: Record<SegmentZone, { title: string; order: number }> = {
+  left: { title: "LEFT ZONE (Identity)", order: 0 },
+  center: { title: "CENTER ZONE (Metrics)", order: 1 },
+  right: { title: "RIGHT ZONE (Time)", order: 2 },
+};
+
+/** Build the help content lines */
+function buildHelpLines(
+  segments: FooterSegment[],
+  presetName: string,
+): string[] {
+  const settings = loadFooterSettings();
+  const preset = getPreset(presetName);
+  const enabledIds = new Set([
+    ...preset.leftSegments,
+    ...preset.rightSegments,
+    ...preset.secondarySegments,
+  ]);
+
+  // Filter to enabled segments only
+  const enabled = segments.filter(seg => {
+    if (!enabledIds.has(seg.id)) return false;
+    return isSegmentEnabled(getGroupForSegment(seg.id), seg.id);
+  });
+
+  if (enabled.length === 0) {
+    return ["No segments enabled."];
+  }
+
+  // Group by zone
+  const zones: Record<SegmentZone, FooterSegment[]> = { left: [], center: [], right: [] };
+  for (const seg of enabled) {
+    zones[seg.zone].push(seg);
+  }
+
+  const lines: string[] = [];
+
+  for (const zoneKey of (["left", "center", "right"] as SegmentZone[])) {
+    const zoneSegs = zones[zoneKey];
+    if (zoneSegs.length === 0) continue;
+
+    const meta = ZONE_META[zoneKey];
+    lines.push(`  ${meta.title}`);
+    lines.push("");
+
+    for (const seg of zoneSegs) {
+      const icon = getIcon(seg.id);
+      const label = seg.shortLabel;
+      const desc = seg.description;
+      const iconStr = icon ? `${icon} ` : "  ";
+      lines.push(`    ${iconStr}${label.padEnd(6)} ${desc}`);
+    }
+
+    lines.push("");
+  }
+
+  return lines;
+}
+
+/** Simple group lookup for help */
+function getGroupForSegment(segId: string): string {
+  const coreIds = ["model", "api_state", "tool_count", "git", "context_pct", "cost", "tokens_total", "tokens_in", "tokens_out", "session", "hostname", "time", "tps", "clock", "duration", "thinking_level"];
+  if (coreIds.includes(segId)) return "core";
+  const compactorIds = ["session_events", "compactions", "tokens_saved", "compression_ratio", "indexed_docs", "sandbox_runs", "search_queries"];
+  if (compactorIds.includes(segId)) return "compactor";
+  if (["project_count", "total_count", "consolidations"].includes(segId)) return "memory";
+  if (["servers_total", "servers_active", "tools_total", "servers_failed"].includes(segId)) return "mcp";
+  if (["active_loops", "total_iterations", "loop_status"].includes(segId)) return "ralph";
+  if (["current_command", "sandbox_level", "command_duration"].includes(segId)) return "workflow";
+  if (["docs_count", "tasks_done", "tasks_total", "task_pct"].includes(segId)) return "kanboard";
+  if (["platforms_enabled", "last_sent"].includes(segId)) return "notify";
+  if (segId === "extension_statuses") return "status_ext";
+  return "core";
+}
+
+/**
+ * Show the footer help overlay.
+ * Lists all enabled segments grouped by zone with descriptions.
+ */
+export function showFooterHelp(
+  pi: ExtensionAPI,
+  segments: FooterSegment[],
+  presetName: string,
+): void {
+  const lines = buildHelpLines(segments, presetName);
+
+  // Use pi's custom UI overlay
+  const ctx = (pi as any)._ctx;
+  if (ctx?.ui?.custom) {
+    ctx.ui.custom((tui: any) => {
+      let scrollOffset = 0;
+
+      return {
+        dispose() {},
+        render(width: number, height: number): string[] {
+          const maxVisible = height - 2; // border lines
+          const visibleLines = lines.slice(scrollOffset, scrollOffset + maxVisible);
+
+          const result: string[] = [];
+
+          // Top border
+          const title = " ? Footer Segment Guide ";
+          const borderLen = Math.max(width - 2, title.length + 4);
+          result.push(`\x1b[2m┌${"─".repeat(borderLen)}┐\x1b[0m`);
+
+          // Title
+          result.push(`\x1b[2m│\x1b[0m \x1b[1m${title}\x1b[0m${" ".repeat(Math.max(0, borderLen - title.length - 1))}\x1b[2m│\x1b[0m`);
+
+          // Content
+          for (const line of visibleLines) {
+            const padded = line.length > borderLen - 2
+              ? line.slice(0, borderLen - 2)
+              : line + " ".repeat(Math.max(0, borderLen - 2 - line.length));
+            result.push(`\x1b[2m│\x1b[0m ${padded} \x1b[2m│\x1b[0m`);
+          }
+
+          // Bottom border
+          result.push(`\x1b[2m├${"─".repeat(borderLen)}┤\x1b[0m`);
+          result.push(`\x1b[2m│\x1b[0m \x1b[2m↑↓ scroll · q close\x1b[0m${" ".repeat(Math.max(0, borderLen - 20))} \x1b[2m│\x1b[0m`);
+          result.push(`\x1b[2m└${"─".repeat(borderLen)}┘\x1b[0m`);
+
+          return result;
+        },
+        handleInput(key: string): boolean {
+          if (key === "q" || key === "Escape" || key === "Enter") {
+            return false; // Close overlay
+          }
+          if (key === "ArrowUp" || key === "k") {
+            scrollOffset = Math.max(0, scrollOffset - 1);
+            return true;
+          }
+          if (key === "ArrowDown" || key === "j") {
+            scrollOffset = Math.min(Math.max(0, lines.length - 5), scrollOffset + 1);
+            return true;
+          }
+          return true; // Consume all other keys
+        },
+      };
+    });
+  } else {
+    // Fallback: print to console
+    for (const line of lines) {
+      console.log(line);
+    }
+  }
+}