@pellux/goodvibes-tui 0.26.0 → 0.28.0

package/src/panels/hooks-panel.ts

@@ -9,6 +9,8 @@ import type { HookChain, HookDefinition } from '@pellux/goodvibes-sdk/platform/h
 import type { HookWorkbench } from '@pellux/goodvibes-sdk/platform/hooks';
 import { truncateDisplay } from '../utils/terminal-width.ts';
 import {
+  buildKeyValueLine,
+  buildKeyboardHints,
   buildPanelLine,
   buildStatusPill,
   DEFAULT_PANEL_PALETTE,
@@ -68,9 +70,17 @@ export class HooksPanel extends ScrollableListPanel<HookEntry> {
   ) {
     super('hooks', 'Hooks', 'H', 'monitoring');
     this.showSelectionGutter = true; // I5: non-color selection affordance
+    this.filterEnabled = true;
+    this.filterLabel = 'Filter hooks';
     this.dataSource = dataSource;
   }
 
+  protected override filterMatches(entry: HookEntry, q: string): boolean {
+    return (entry.hook.name ?? '').toLowerCase().includes(q)
+      || entry.pattern.toLowerCase().includes(q)
+      || entry.hook.type.toLowerCase().includes(q);
+  }
+
   protected override getPalette() { return C; }
   protected override getEmptyStateMessage() { return ' No hooks are currently registered.'; }
   protected override getEmptyStateActions() {
@@ -96,7 +106,7 @@ export class HooksPanel extends ScrollableListPanel<HookEntry> {
   }
 
   public handleInput(key: string): boolean {
-    if (key === 'r') {
+    if (!this.filterActive && key === 'r') {
       this.markDirty();
       return true;
     }
@@ -224,15 +234,39 @@ export class HooksPanel extends ScrollableListPanel<HookEntry> {
       });
     }
 
+    // Summary header — surface registration + activity counts first so the most
+    // important "what's firing" signal is visible without scrolling to the footer.
+    const denials = recentActivity.filter((r) => r.ok && r.decision === 'deny').length;
+    const errors = recentActivity.filter((r) => !r.ok).length;
+    const headerLines: Line[] = [
+      buildKeyValueLine(width, [
+        { label: 'hooks', value: String(hooks.length), valueColor: C.info },
+        { label: 'chains', value: String(chains.length), valueColor: C.value },
+        { label: 'contracts', value: String(contracts.length), valueColor: C.value },
+        { label: 'recent denials', value: String(denials), valueColor: denials > 0 ? C.warn : C.dim },
+        { label: 'errors', value: String(errors), valueColor: errors > 0 ? C.error : C.dim },
+      ], C),
+    ];
+
+    const hints = this.filterActive
+      ? [{ keys: 'type', label: 'filter' }, { keys: 'Enter', label: 'apply' }, { keys: 'Esc', label: 'clear' }]
+      : [
+          { keys: 'Up/Down', label: 'move' },
+          { keys: 'r', label: 'refresh' },
+          { keys: '/hooks', label: 'full listing' },
+          { keys: '/', label: 'filter' },
+        ];
+
     return this.renderList(width, height, {
       title: 'Hooks Control Room',
+      header: headerLines,
       footer: [
         ...detailLines,
         buildPanelLine(width, [['  Recent Activity', C.label]]),
         ...activityLines,
         buildPanelLine(width, [['  Authoring', C.label]]),
         ...authoringLines,
-        buildPanelLine(width, [['  Up/Down move  r refresh  /hooks for full contract listing', C.dim]]),
+        buildKeyboardHints(width, hints, C),
       ],
     });
   }

package/src/panels/incident-review-panel.ts

@@ -1,4 +1,5 @@
 import type { Line } from '../types/grid.ts';
+import { fitDisplay, truncateDisplay } from '../utils/terminal-width.ts';
 import type { ForensicsRegistry } from '@/runtime/index.ts';
 import { ScrollableListPanel } from './scrollable-list-panel.ts';
 import {
@@ -42,6 +43,8 @@ export class IncidentReviewPanel extends ScrollableListPanel<FailureReport> {
   public constructor(registry?: ForensicsRegistry) {
     super('incident', 'Incident Review', 'N', 'monitoring');
     this.showSelectionGutter = true; // I5: non-color selection affordance
+    this.filterEnabled = true;
+    this.filterLabel = 'Filter incidents';
     this.registry = registry;
     this.unsub = registry ? registry.subscribe(() => this.markDirty()) : null;
   }
@@ -58,13 +61,19 @@ export class IncidentReviewPanel extends ScrollableListPanel<FailureReport> {
     return this.registry?.getAll() ?? [];
   }
 
+  protected override filterMatches(report: FailureReport, q: string): boolean {
+    return report.classification.toLowerCase().includes(q)
+      || report.id.toLowerCase().includes(q)
+      || (report.summary ?? '').toLowerCase().includes(q);
+  }
+
   protected renderItem(report: FailureReport, index: number, selected: boolean, width: number): Line {
     const bg = selected ? C.selectBg : undefined;
     return buildPanelLine(width, [
       [' ', C.label, bg],
-      [report.id.slice(0, 8).padEnd(9), C.dim, bg],
-      [report.classification.padEnd(20), classificationColor(report.classification), bg],
-      [report.summary.slice(0, Math.max(0, width - 31)), C.value, bg],
+      [fitDisplay(report.id, 9), C.dim, bg],
+      [fitDisplay(report.classification, 20), classificationColor(report.classification), bg],
+      [truncateDisplay(report.summary, Math.max(0, width - 31)), C.value, bg],
     ]);
   }
 
@@ -117,7 +126,6 @@ export class IncidentReviewPanel extends ScrollableListPanel<FailureReport> {
         { label: 'selected', value: `${this.selectedIndex + 1}/${reports.length}`, valueColor: C.info },
         { label: 'classification', value: selected.classification, valueColor: classificationColor(selected.classification) },
       ], C),
-      buildPanelLine(width, [['  Up/Down move  Home/End jump  selected incident drives the action rail below', C.dim]]),
     ];
 
     const footerLines: Line[] = [];
@@ -134,26 +142,26 @@ export class IncidentReviewPanel extends ScrollableListPanel<FailureReport> {
       ], C));
       footerLines.push(buildPanelLine(width, [
         ['  Related IDs: ', C.label],
-        [`turn=${bundle.evidence.relatedIds.turnId ?? 'n/a'} task=${bundle.evidence.relatedIds.taskId ?? 'n/a'} agent=${bundle.evidence.relatedIds.agentId ?? 'n/a'}`.slice(0, Math.max(0, width - 14)), C.info],
+        [truncateDisplay(`turn=${bundle.evidence.relatedIds.turnId ?? 'n/a'} task=${bundle.evidence.relatedIds.taskId ?? 'n/a'} agent=${bundle.evidence.relatedIds.agentId ?? 'n/a'}`, Math.max(0, width - 14)), C.info],
       ]));
       if (bundle.evidence.slowPhases.length > 0) {
         footerLines.push(buildPanelLine(width, [
           ['  Slow phases: ', C.label],
-          ...buildStatusPill('warn', bundle.evidence.slowPhases.join(', ').slice(0, Math.max(0, width - 15))),
+          ...buildStatusPill('warn', truncateDisplay(bundle.evidence.slowPhases.join(', '), Math.max(0, width - 15))),
         ]));
       }
       const rootCause = selected.causalChain.find((entry) => entry.isRootCause);
       if (rootCause) {
         footerLines.push(buildPanelLine(width, [
           ['  Root event: ', C.label],
-          [`${rootCause.sourceEventType} - ${rootCause.description}`.slice(0, Math.max(0, width - 14)), C.dim],
+          [truncateDisplay(`${rootCause.sourceEventType} - ${rootCause.description}`, Math.max(0, width - 14)), C.dim],
         ]));
       }
       const denied = selected.permissionEvidence.find((entry) => entry.approved === false);
       if (denied) {
         footerLines.push(buildPanelLine(width, [
           ['  Permission: ', C.label],
-          [`${denied.tool} denied${denied.riskLevel ? ` (${denied.riskLevel})` : ''}${denied.summary ? ` - ${denied.summary}` : ''}`.slice(0, Math.max(0, width - 14)), C.warn],
+          [truncateDisplay(`${denied.tool} denied${denied.riskLevel ? ` (${denied.riskLevel})` : ''}${denied.summary ? ` - ${denied.summary}` : ''}`, Math.max(0, width - 14)), C.warn],
         ]));
       }
       if (bundle.replay.relatedMismatches.length > 0) {
@@ -168,7 +176,7 @@ export class IncidentReviewPanel extends ScrollableListPanel<FailureReport> {
           : `Replay link: ${mismatch.kind}${mismatch.ownerDomain ? `/${mismatch.ownerDomain}` : ''} - ${mismatch.description}`;
         footerLines.push(buildPanelLine(width, [
           ['  ', C.label],
-          ...buildStatusPill('bad', replayDetail.slice(0, Math.max(0, width - 2))),
+          ...buildStatusPill('bad', truncateDisplay(replayDetail, Math.max(0, width - 2))),
         ]));
       } else {
         const ownerBreakdown = Object.entries(bundle.replay.mismatchBreakdown.byOwnerDomain)
@@ -179,7 +187,7 @@ export class IncidentReviewPanel extends ScrollableListPanel<FailureReport> {
         if (ownerBreakdown.length > 0) {
           footerLines.push(buildPanelLine(width, [
             ['  Replay owners: ', C.label],
-            [ownerBreakdown.slice(0, Math.max(0, width - 17)), C.info],
+            [truncateDisplay(ownerBreakdown, Math.max(0, width - 17)), C.info],
           ]));
         }
       }
@@ -188,10 +196,23 @@ export class IncidentReviewPanel extends ScrollableListPanel<FailureReport> {
     footerLines.push(buildPanelLine(width, [[`  /incident latest   /incident export ${selected.id}   /recall capture incident ${selected.id}`, C.info]]));
     footerLines.push(buildGuidanceLine(width, '/security', 'open the broader trust and incident posture control room', C));
 
+    const hints = this.filterActive
+      ? [
+          { keys: 'type', label: 'filter incidents' },
+          { keys: 'Enter', label: 'apply' },
+          { keys: 'Esc', label: 'clear' },
+        ]
+      : [
+          { keys: '↑/↓', label: 'select incident' },
+          { keys: 'Home/End', label: 'jump' },
+          { keys: '/', label: 'filter' },
+        ];
+
     return this.renderList(width, height, {
       title: 'Incident Review Workspace',
       header: headerLines,
       footer: footerLines,
+      hints,
     });
   }
 }

package/src/panels/intelligence-panel.ts

@@ -1,15 +1,20 @@
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine } from '../types/grid.ts';
+import { truncateDisplay } from '../utils/terminal-width.ts';
 import { BasePanel } from './base-panel.ts';
 import type { UiIntelligenceSnapshot, UiReadModel } from '../runtime/ui-read-models.ts';
 import {
+  buildDetailBlock,
   buildEmptyState,
   buildGuidanceLine,
+  buildKeyboardHints,
   buildKeyValueLine,
   buildPanelLine,
   buildPanelWorkspace,
+  buildStatusPill,
   DEFAULT_PANEL_PALETTE,
   type PanelWorkspaceSection,
+  type StyledPanelSegment,
 } from './polish.ts';
 
 const C = {
@@ -21,22 +26,29 @@ const C = {
   headerBg: '#1e293b',
 } as const;
 
-function statusColor(status: string): string {
-  switch (status) {
-    case 'ready':
-      return C.good;
-    case 'loading':
-      return C.info;
-    case 'degraded':
-      return C.warn;
-    case 'unavailable':
-    default:
-      return C.bad;
-  }
+interface DiagnosticFile {
+  readonly filePath: string;
+  readonly errors: number;
+  readonly warnings: number;
+  readonly diagnostics: ReadonlyArray<{
+    readonly line: number;
+    readonly column: number;
+    readonly severity: string;
+    readonly message: string;
+    readonly source?: string | undefined;
+    readonly code?: string | undefined;
+  }>;
+}
+
+/** Map an intelligence-surface status string to a status-pill segment. */
+function postureSegments(label: string, status: string): StyledPanelSegment[] {
+  const state = status === 'ready' ? 'good' : status === 'degraded' ? 'warn' : status === 'loading' ? 'info' : 'bad';
+  return buildStatusPill(state, `${label} ${status}`);
 }
 
 export class IntelligencePanel extends BasePanel {
   private readonly unsub: (() => void) | null;
+  private selectedIndex = 0;
 
   public constructor(private readonly readModel?: UiReadModel<UiIntelligenceSnapshot>) {
     super('intelligence', 'Intelligence', 'J', 'development');
@@ -47,6 +59,53 @@ export class IntelligencePanel extends BasePanel {
     this.unsub?.();
   }
 
+  /** Diagnostic files sorted error-first so the most actionable file is first. */
+  private diagnosticFiles(): DiagnosticFile[] {
+    if (!this.readModel) return [];
+    const state = this.readModel.getSnapshot();
+    return [...state.diagnostics.entries()]
+      .map(([filePath, diagnostics]) => ({
+        filePath,
+        errors: diagnostics.filter((entry) => entry.severity === 'error').length,
+        warnings: diagnostics.filter((entry) => entry.severity === 'warning').length,
+        diagnostics: diagnostics.map((entry) => ({
+          line: entry.line,
+          column: entry.column,
+          severity: entry.severity,
+          message: entry.message,
+          source: entry.source,
+          code: entry.code,
+        })),
+      }))
+      .sort((a, b) => (b.errors - a.errors) || (b.warnings - a.warnings) || a.filePath.localeCompare(b.filePath));
+  }
+
+  public handleInput(key: string): boolean {
+    const files = this.diagnosticFiles();
+    if (files.length === 0) return false;
+    if (key === 'up' || key === 'k') {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      this.markDirty();
+      return true;
+    }
+    if (key === 'down' || key === 'j') {
+      this.selectedIndex = Math.min(files.length - 1, this.selectedIndex + 1);
+      this.markDirty();
+      return true;
+    }
+    if (key === 'home' || key === 'g') {
+      this.selectedIndex = 0;
+      this.markDirty();
+      return true;
+    }
+    if (key === 'end' || key === 'G') {
+      this.selectedIndex = files.length - 1;
+      this.markDirty();
+      return true;
+    }
+    return false;
+  }
+
   public render(width: number, height: number): Line[] {
     this.needsRender = false;
     if (!this.readModel) {
@@ -76,16 +135,25 @@ export class IntelligencePanel extends BasePanel {
       state.hoverStatus,
     ].filter((status) => status !== 'ready').length;
 
+    const diagnosticFiles = this.diagnosticFiles();
+    this.selectedIndex = Math.max(0, Math.min(this.selectedIndex, Math.max(0, diagnosticFiles.length - 1)));
+
     const sections: PanelWorkspaceSection[] = [
       {
         title: 'Intelligence posture',
         lines: [
-          buildKeyValueLine(width, [
-            { label: 'diagnostics', value: state.diagnosticsStatus, valueColor: statusColor(state.diagnosticsStatus) },
-            { label: 'symbols', value: state.symbolSearchStatus, valueColor: statusColor(state.symbolSearchStatus) },
-            { label: 'completions', value: state.completionsStatus, valueColor: statusColor(state.completionsStatus) },
-            { label: 'hover', value: state.hoverStatus, valueColor: statusColor(state.hoverStatus) },
-          ], C),
+          buildPanelLine(width, [
+            { text: ' ', fg: C.dim },
+            ...postureSegments('diagnostics', state.diagnosticsStatus),
+            { text: '   ', fg: C.dim },
+            ...postureSegments('symbols', state.symbolSearchStatus),
+          ]),
+          buildPanelLine(width, [
+            { text: ' ', fg: C.dim },
+            ...postureSegments('completions', state.completionsStatus),
+            { text: '   ', fg: C.dim },
+            ...postureSegments('hover', state.hoverStatus),
+          ]),
           buildKeyValueLine(width, [
             { label: 'errors', value: String(state.errorCount), valueColor: state.errorCount > 0 ? C.bad : C.dim },
             { label: 'warnings', value: String(state.warningCount), valueColor: state.warningCount > 0 ? C.warn : C.dim },
@@ -94,80 +162,93 @@ export class IntelligencePanel extends BasePanel {
           ], C),
         ],
       },
-      {
-        title: 'Next Actions',
-        lines: [
-          buildGuidanceLine(width, '/intelligence diagnostics', 'review readiness posture and current diagnostics activity', C),
-          buildGuidanceLine(width, '/intelligence repair', 'surface repair-oriented guidance when symbols, hover, or completions degrade', C),
-        ],
-      },
-      {
-        title: 'Readiness',
-        lines: [
-          buildPanelLine(width, [[` Diagnostics are ${state.diagnosticsStatus}. Symbol search is ${state.symbolSearchStatus}.`, state.diagnosticsStatus === 'ready' && state.symbolSearchStatus === 'ready' ? C.dim : C.warn]]),
-          buildPanelLine(width, [[` Hover is ${state.hoverStatus}. Completions are ${state.completionsStatus}.`, state.hoverStatus === 'ready' && state.completionsStatus === 'ready' ? C.dim : C.warn]]),
-          ...(state.hover.active && state.hover.filePath
-            ? [buildPanelLine(width, [[` Active hover: ${state.hover.filePath}`, C.info]])]
-            : []),
-        ],
-      },
     ];
 
-    const diagnosticFiles = [...state.diagnostics.entries()]
-      .map(([filePath, diagnostics]) => ({
-        filePath,
-        errors: diagnostics.filter((entry) => entry.severity === 'error').length,
-        warnings: diagnostics.filter((entry) => entry.severity === 'warning').length,
-      }))
-      .sort((a, b) => (b.errors - a.errors) || (b.warnings - a.warnings) || a.filePath.localeCompare(b.filePath))
-      .slice(0, 4);
-    sections.push({
-      title: 'Diagnostics',
-      lines: diagnosticFiles.length > 0
-        ? diagnosticFiles.map((entry) => buildPanelLine(width, [[
-            ` ${entry.filePath}  errors=${entry.errors} warnings=${entry.warnings}`,
-            entry.errors > 0 ? C.bad : entry.warnings > 0 ? C.warn : C.dim,
-          ]]))
-        : [buildPanelLine(width, [[' No tracked diagnostics yet.', C.dim]])],
-    });
+    // Diagnostics — the most actionable surface. Render as a selectable list so
+    // the operator can drill into a specific file's findings.
+    const visibleFiles = diagnosticFiles.slice(0, 6);
+    const diagnosticsLines: Line[] = diagnosticFiles.length > 0
+      ? visibleFiles.map((entry, idx) => {
+          const selected = idx === this.selectedIndex;
+          const tone = entry.errors > 0 ? C.bad : entry.warnings > 0 ? C.warn : C.dim;
+          const counts = `  ${entry.errors} err  ${entry.warnings} warn`;
+          const pathBudget = Math.max(8, width - counts.length - 4);
+          return buildPanelLine(width, [
+            [selected ? ' ▸ ' : '   ', selected ? C.info : C.dim, selected ? C.headerBg : undefined],
+            [truncateDisplay(entry.filePath, pathBudget), selected ? C.value : C.label, selected ? C.headerBg : undefined],
+            [counts, tone, selected ? C.headerBg : undefined],
+          ]);
+        })
+      : [buildPanelLine(width, [[' No tracked diagnostics. Symbol/diagnostic surfaces are clear.', C.dim]])];
+    if (diagnosticFiles.length > visibleFiles.length) {
+      diagnosticsLines.push(buildPanelLine(width, [[`   +${diagnosticFiles.length - visibleFiles.length} more files`, C.dim]]));
+    }
+    sections.push({ title: `Diagnostics (${diagnosticFiles.length})`, lines: diagnosticsLines });
 
-    sections.push({
-      title: 'Workflows',
-      lines: [
-        buildGuidanceLine(width, '/intelligence symbols <file>', 'inspect document symbols for a file and verify symbol-surface readiness', C),
-        buildGuidanceLine(width, '/intelligence outline <file>', 'review structural outline extraction without leaving the control room', C),
-        buildGuidanceLine(width, '/intelligence definition <file> <line> <column>', 'check definition lookup for an exact source position', C),
-        buildGuidanceLine(width, '/intelligence references <file> <line> <column>', 'review reference lookup for a symbol under the cursor', C),
-        buildGuidanceLine(width, '/intelligence hover <file> <line> <column>', 'inspect hover/details posture for a specific source position', C),
-      ],
-    });
+    // Drill-down detail for the selected diagnostic file.
+    const selectedFile = diagnosticFiles[this.selectedIndex];
+    if (selectedFile) {
+      const detailRows: Line[] = [
+        buildKeyValueLine(width, [
+          { label: 'errors', value: String(selectedFile.errors), valueColor: selectedFile.errors > 0 ? C.bad : C.dim },
+          { label: 'warnings', value: String(selectedFile.warnings), valueColor: selectedFile.warnings > 0 ? C.warn : C.dim },
+        ], C),
+      ];
+      const topFindings = [...selectedFile.diagnostics]
+        .sort((a, b) => (a.severity === 'error' ? 0 : 1) - (b.severity === 'error' ? 0 : 1))
+        .slice(0, 3);
+      for (const finding of topFindings) {
+        const loc = `${finding.line + 1}:${finding.column + 1}`;
+        const tag = finding.source ? `${finding.source}${finding.code ? `(${finding.code})` : ''}` : finding.severity;
+        const prefix = ` ${loc} ${tag}: `;
+        detailRows.push(buildPanelLine(width, [
+          [prefix, finding.severity === 'error' ? C.bad : C.warn],
+          [truncateDisplay(finding.message, Math.max(8, width - prefix.length - 1)), C.value],
+        ]));
+      }
+      if (selectedFile.diagnostics.length > topFindings.length) {
+        detailRows.push(buildPanelLine(width, [[`  +${selectedFile.diagnostics.length - topFindings.length} more findings`, C.dim]]));
+      }
+      detailRows.push(buildGuidanceLine(width, `/intelligence diagnostics ${selectedFile.filePath}`, 'open the full diagnostic list for this file', C));
+      sections.push({ lines: buildDetailBlock(width, truncateDisplay(selectedFile.filePath, Math.max(8, width - 4)), detailRows, C) });
+    }
 
     if (degraded > 0) {
       sections.push({
         title: 'Recovery',
         lines: [
-          buildPanelLine(width, [[' Workspace intelligence is not fully ready. Review LSP/tree-sitter setup and workspace language configuration.', C.warn]]),
-          buildGuidanceLine(width, '/health review', 'check setup and readiness failures that could block diagnostics and symbol search', C),
-          buildGuidanceLine(width, '/setup review', 'review startup and environment posture for intelligence dependencies', C),
-          buildGuidanceLine(width, '/intelligence repair', 'show repair-oriented commands for diagnostics, symbols, hover, and completions', C),
-          buildGuidanceLine(width, '/health repair intelligence', 'show repair commands plus post-repair verification for the intelligence domain', C),
+          buildPanelLine(width, [[' Workspace intelligence is not fully ready. Review LSP/tree-sitter setup and language configuration.', C.warn]]),
+          buildGuidanceLine(width, '/intelligence repair', 'show repair commands for diagnostics, symbols, hover, and completions', C),
+          buildGuidanceLine(width, '/health repair intelligence', 'show repair commands plus post-repair verification', C),
         ],
       });
     } else {
       sections.push({
-        title: 'Recovery',
+        title: 'Workflows',
         lines: [
-          buildPanelLine(width, [[' Intelligence surfaces are healthy and ready for code-aware workflows.', C.dim]]),
-          buildGuidanceLine(width, '/health intelligence', 'verify readiness posture after setup changes or dependency recovery', C),
+          buildGuidanceLine(width, '/intelligence symbols <file>', 'inspect document symbols and verify symbol-surface readiness', C),
+          buildGuidanceLine(width, '/intelligence definition <file> <line> <column>', 'check definition lookup for an exact source position', C),
+          buildGuidanceLine(width, '/intelligence hover <file> <line> <column>', 'inspect hover/details posture for a source position', C),
         ],
       });
     }
 
+    const footerLines = diagnosticFiles.length > 0
+      ? [buildKeyboardHints(width, [
+          { keys: '↑/↓', label: 'select file' },
+          { keys: 'Home/End', label: 'jump' },
+          { keys: '/intelligence', label: 'commands' },
+        ], C)]
+      : [buildKeyboardHints(width, [
+          { keys: '/intelligence diagnostics', label: 'review' },
+          { keys: '/intelligence symbols <file>', label: 'inspect symbols' },
+        ], C)];
+
     const lines = buildPanelWorkspace(width, height, {
       title: 'Intelligence Control Room',
       intro: 'Workspace intelligence posture across diagnostics, symbol search, hover, and completion readiness.',
       sections,
-      footerLines: [buildPanelLine(width, [[' /symbols  /intelligence diagnostics  /intelligence symbols <file>  /intelligence definition <file> <line> <column> ', C.dim]])],
+      footerLines,
       palette: C,
     });
     while (lines.length < height) lines.push(createEmptyLine(width));

package/src/panels/knowledge-graph-panel.ts

@@ -8,13 +8,20 @@
  * This panel is a thin information surface that explains the graph's capabilities
  * and routes the user to the /knowledge command suite for ingest/RAG operations.
  * The full graph UI is command-driven (/knowledge ask, ingest-url, list, search…).
+ *
+ * It is selectable: the operator can move a cursor across the command catalogue
+ * so the currently-highlighted command is unambiguous and a one-line "what this
+ * does" detail is surfaced for it.
  */
 
 import type { Line } from '../types/grid.ts';
+import { createEmptyLine } from '../types/grid.ts';
 import { BasePanel } from './base-panel.ts';
 import {
   buildBodyText,
+  buildDetailBlock,
   buildGuidanceLine,
+  buildKeyboardHints,
   buildPanelLine,
   buildPanelWorkspace,
   DEFAULT_PANEL_PALETTE,
@@ -26,59 +33,114 @@ const C = {
   headerBg: '#1e293b',
 } as const;
 
+interface CommandEntry {
+  readonly command: string;
+  readonly summary: string;
+  readonly detail: string;
+}
+
+const GRAPH_COMMANDS: readonly CommandEntry[] = [
+  { command: '/knowledge status', summary: 'check the graph status and source counts', detail: 'Reports node/edge totals, ingested source count, and embedding-provider readiness.' },
+  { command: '/knowledge ask <query>', summary: 'ask a question against the ingested knowledge', detail: 'Runs retrieval-augmented Q&A over ingested sources and returns a cited answer.' },
+  { command: '/knowledge ingest-url <url>', summary: 'ingest a URL as a knowledge source', detail: 'Fetches a URL, extracts content, and stores it as graph nodes and edges.' },
+  { command: '/knowledge list', summary: 'list ingested sources or graph nodes', detail: 'Enumerates the current sources and top-level nodes in the graph.' },
+  { command: '/knowledge search <query>', summary: 'search the graph for nodes and sources', detail: 'Keyword/semantic search across stored nodes without generating an answer.' },
+  { command: '/knowledge packet <task>', summary: 'build a compact prompt packet for a task', detail: 'Assembles a token-budgeted context packet of the most relevant facts for a task.' },
+];
+
+const MEMORY_COMMANDS: readonly CommandEntry[] = [
+  { command: '/recall add <class> <summary>', summary: 'capture a new memory record', detail: 'Stores a durable decision, risk, runbook, incident, or architecture record.' },
+  { command: '/recall queue', summary: 'show the operator review queue', detail: 'Lists stale and contradicted records awaiting operator review.' },
+  { command: '/project-memory (pmem)', summary: 'project-memory alias for /recall front-door', detail: 'Shorthand entry point to the same durable project-memory surface.' },
+];
+
 export class KnowledgeGraphPanel extends BasePanel {
+  private selectedIndex = 0;
+
   constructor() {
     super('knowledge', 'Knowledge', 'K', 'agent');
   }
 
-  handleInput(_key: string): boolean {
+  private get entries(): readonly CommandEntry[] {
+    return [...GRAPH_COMMANDS, ...MEMORY_COMMANDS];
+  }
+
+  handleInput(key: string): boolean {
+    const count = this.entries.length;
+    if (key === 'up' || key === 'k') {
+      this.selectedIndex = (this.selectedIndex - 1 + count) % count;
+      this.markDirty();
+      return true;
+    }
+    if (key === 'down' || key === 'j') {
+      this.selectedIndex = (this.selectedIndex + 1) % count;
+      this.markDirty();
+      return true;
+    }
+    if (key === 'home' || key === 'g') {
+      this.selectedIndex = 0;
+      this.markDirty();
+      return true;
+    }
+    if (key === 'end' || key === 'G') {
+      this.selectedIndex = count - 1;
+      this.markDirty();
+      return true;
+    }
     return false;
   }
 
+  private commandLines(width: number, group: readonly CommandEntry[], offset: number): Line[] {
+    return group.map((entry, idx) => {
+      const absIdx = offset + idx;
+      const selected = absIdx === this.selectedIndex;
+      if (selected) {
+        return buildPanelLine(width, [
+          [' ▸ ', C.info, C.headerBg],
+          [`${entry.command}  `, C.value, C.headerBg],
+          [entry.summary, C.dim, C.headerBg],
+        ]);
+      }
+      return buildGuidanceLine(width, entry.command, entry.summary, C);
+    });
+  }
+
   render(width: number, height: number): Line[] {
+    this.selectedIndex = Math.max(0, Math.min(this.selectedIndex, this.entries.length - 1));
+    const selected = this.entries[this.selectedIndex]!;
+
     const sections = [
       {
         title: 'SDK Knowledge Graph',
         lines: [
-          ...buildBodyText(
-            width,
-            'The knowledge graph stores ingested URLs, bookmarks, and structured facts as nodes and edges. ' +
-            'Use /knowledge commands to ingest sources, search the graph, and build task-context packets.',
-            C,
-            C.value,
-          ),
-          buildPanelLine(width, [['', C.dim]]),
-          buildGuidanceLine(width, '/knowledge status', 'check the graph status and source counts', C),
-          buildGuidanceLine(width, '/knowledge ask <query>', 'ask a question against the ingested knowledge', C),
-          buildGuidanceLine(width, '/knowledge ingest-url <url>', 'ingest a URL as a knowledge source', C),
-          buildGuidanceLine(width, '/knowledge list', 'list ingested sources or graph nodes', C),
-          buildGuidanceLine(width, '/knowledge search <query>', 'search the graph for nodes and sources', C),
-          buildGuidanceLine(width, '/knowledge packet <task>', 'build a compact prompt packet for a task', C),
+          buildPanelLine(width, [[' Ingest URLs and facts as graph nodes; search and build task-context packets.', C.dim]]),
+          ...this.commandLines(width, GRAPH_COMMANDS, 0),
         ],
       },
       {
         title: 'Project Memory',
         lines: [
-          ...buildBodyText(
-            width,
-            'For durable decisions, risks, runbooks, incidents, and architecture records, use the Memory panel ' +
-            'or the /recall command surface. Durable memory is a sub-namespace of the knowledge graph.',
-            C,
-            C.dim,
-          ),
-          buildPanelLine(width, [['', C.dim]]),
-          buildGuidanceLine(width, '/recall add <class> <summary>', 'capture a new memory record', C),
-          buildGuidanceLine(width, '/recall queue', 'show the operator review queue', C),
-          buildGuidanceLine(width, '/project-memory (pmem)', 'project-memory alias for /recall front-door', C),
+          buildPanelLine(width, [[' Durable decisions, risks, runbooks, and incidents — a sub-namespace of the graph.', C.dim]]),
+          ...this.commandLines(width, MEMORY_COMMANDS, GRAPH_COMMANDS.length),
         ],
       },
+      {
+        lines: buildDetailBlock(width, selected.command, buildBodyText(width, selected.detail, C, C.value), C),
+      },
     ];
 
-    return buildPanelWorkspace(width, height, {
+    const lines = buildPanelWorkspace(width, height, {
       title: 'Knowledge Graph',
       intro: 'Ingested sources, graph nodes, and the durable memory bridge.',
       sections,
+      footerLines: [buildKeyboardHints(width, [
+        { keys: '↑/↓', label: 'browse commands' },
+        { keys: 'Home/End', label: 'jump' },
+        { keys: 'M', label: 'Memory panel' },
+      ], C)],
       palette: C,
     });
+    while (lines.length < height) lines.push(createEmptyLine(width));
+    return lines.slice(0, height);
   }
 }