free-coding-models 0.3.21 → 0.3.23

package/src/key-handler.js

@@ -31,7 +31,7 @@ import { loadChangelog } from './changelog-loader.js'
 import { loadConfig, replaceConfigContents } from './config.js'
 import { cleanupLegacyProxyArtifacts } from './legacy-proxy-cleanup.js'
 import { cycleThemeSetting, detectActiveTheme } from './theme.js'
-import { buildCommandPaletteEntries, filterCommandPaletteEntries } from './command-palette.js'
+import { buildCommandPaletteTree, flattenCommandTree, filterCommandPaletteEntries } from './command-palette.js'
 import { WIDTH_WARNING_MIN_COLS } from './constants.js'
 
 // 📖 Some providers need an explicit probe model because the first catalog entry
@@ -519,7 +519,9 @@ export function createKeyHandler(ctx) {
   // 📖 Shared table refresh helper so command-palette and hotkeys keep identical behavior.
   function refreshVisibleSorted({ resetCursor = true } = {}) {
     const visible = state.results.filter(r => !r.hidden)
-    state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+    state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection, {
+      pinFavorites: state.favoritesPinnedAndSticky,
+    })
     if (resetCursor) {
       state.cursor = 0
       state.scrollOffset = 0
@@ -600,15 +602,52 @@ export function createKeyHandler(ctx) {
     const modeOrder = getToolModeOrder()
     const currentIndex = modeOrder.indexOf(state.mode)
     const nextIndex = (currentIndex + 1) % modeOrder.length
-    state.mode = modeOrder[nextIndex]
+    setToolMode(modeOrder[nextIndex])
+  }
+
+  // 📖 Keep tool-mode changes centralized so keyboard shortcuts and command palette
+  // 📖 both persist to config exactly the same way.
+  function setToolMode(nextMode) {
+    if (!getToolModeOrder().includes(nextMode)) return
+    state.mode = nextMode
     if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
     state.config.settings.preferredToolMode = state.mode
     saveConfig(state.config)
   }
 
+  // 📖 Favorites display mode:
+  // 📖 - true  => favorites stay pinned + always visible (legacy behavior)
+  // 📖 - false => favorites are just starred rows and obey normal sort/filter rules
+  function setFavoritesDisplayMode(nextPinned, { preserveSelection = true } = {}) {
+    const normalizedNextPinned = nextPinned !== false
+    if (state.favoritesPinnedAndSticky === normalizedNextPinned) return
+
+    const selected = preserveSelection ? state.visibleSorted[state.cursor] : null
+    const selectedKey = selected ? toFavoriteKey(selected.providerKey, selected.modelId) : null
+
+    state.favoritesPinnedAndSticky = normalizedNextPinned
+    if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+    state.config.settings.favoritesPinnedAndSticky = state.favoritesPinnedAndSticky
+    saveConfig(state.config)
+
+    applyTierFilter()
+    refreshVisibleSorted({ resetCursor: false })
+
+    if (selectedKey) {
+      const selectedIdx = state.visibleSorted.findIndex((row) => toFavoriteKey(row.providerKey, row.modelId) === selectedKey)
+      if (selectedIdx >= 0) state.cursor = selectedIdx
+      adjustScrollOffset(state)
+    }
+  }
+
+  function toggleFavoritesDisplayMode() {
+    setFavoritesDisplayMode(!state.favoritesPinnedAndSticky)
+  }
+
   function resetViewSettings() {
     state.tierFilterMode = 0
     state.originFilterMode = 0
+    state.customTextFilter = null  // 📖 Clear ephemeral text filter on view reset
     state.sortColumn = 'avg'
     state.sortDirection = 'asc'
     if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
@@ -630,7 +669,7 @@ export function createKeyHandler(ctx) {
     applyTierFilter()
     refreshVisibleSorted({ resetCursor: false })
 
-    if (wasFavorite) {
+    if (wasFavorite && state.favoritesPinnedAndSticky) {
       state.cursor = 0
       state.scrollOffset = 0
       return
@@ -653,8 +692,50 @@ export function createKeyHandler(ctx) {
   }
 
   function refreshCommandPaletteResults() {
-    const commands = buildCommandPaletteEntries()
-    state.commandPaletteResults = filterCommandPaletteEntries(commands, state.commandPaletteQuery)
+    const query = (state.commandPaletteQuery || '').trim()
+    const tree = buildCommandPaletteTree(state.results || [])
+    // 📖 Keep collapsed view clean when query is empty, but search across the
+    // 📖 full tree when users type so hidden submenu commands still appear.
+    let flat
+    if (query.length > 0) {
+      const expandedIds = new Set()
+      const collectExpandedIds = (nodes) => {
+        for (const node of nodes || []) {
+          if (Array.isArray(node.children) && node.children.length > 0) {
+            expandedIds.add(node.id)
+            collectExpandedIds(node.children)
+          }
+        }
+      }
+      collectExpandedIds(tree)
+      flat = flattenCommandTree(tree, expandedIds)
+    } else {
+      flat = flattenCommandTree(tree, state.commandPaletteExpandedIds)
+    }
+    state.commandPaletteResults = filterCommandPaletteEntries(flat, query)
+
+    if (query.length > 0) {
+      state.commandPaletteResults.unshift({
+        id: 'filter-custom-text-apply',
+        label: `🔍 Apply text filter: ${query}`,
+        type: 'command',
+        depth: 0,
+        hasChildren: false,
+        isExpanded: false,
+        filterQuery: query,
+      })
+    } else if (state.customTextFilter) {
+      state.commandPaletteResults.unshift({
+        id: 'filter-custom-text-remove',
+        label: `❌ Remove custom filter: ${state.customTextFilter}`,
+        type: 'command',
+        depth: 0,
+        hasChildren: false,
+        isExpanded: false,
+        filterQuery: null,
+      })
+    }
+
     if (state.commandPaletteCursor >= state.commandPaletteResults.length) {
       state.commandPaletteCursor = Math.max(0, state.commandPaletteResults.length - 1)
     }
@@ -681,8 +762,59 @@ export function createKeyHandler(ctx) {
   function executeCommandPaletteEntry(entry) {
     if (!entry?.id) return
 
+    if (entry.id.startsWith('action-set-ping-') && entry.pingMode) {
+      setPingMode(entry.pingMode, 'manual')
+      return
+    }
+
+    if (entry.id.startsWith('action-set-tool-') && entry.toolMode) {
+      setToolMode(entry.toolMode)
+      return
+    }
+
+    if (entry.id.startsWith('action-favorites-mode-') && typeof entry.favoritesPinned === 'boolean') {
+      setFavoritesDisplayMode(entry.favoritesPinned)
+      return
+    }
+
     if (entry.id.startsWith('filter-tier-')) {
-      setTierFilterFromCommand(entry.tierValue ?? null)
+      setTierFilterFromCommand(entry.tier ?? null)
+      return
+    }
+
+    if (entry.id.startsWith('filter-provider-') && entry.id !== 'filter-provider-cycle') {
+      if (entry.providerKey === null || entry.providerKey === undefined) {
+        state.originFilterMode = 0 // All
+      } else {
+        state.originFilterMode = ORIGIN_CYCLE.findIndex(key => key === entry.providerKey) + 1
+        if (state.originFilterMode <= 0) state.originFilterMode = 0
+      }
+      applyTierFilter()
+      refreshVisibleSorted({ resetCursor: true })
+      persistUiSettings()
+      return
+    }
+
+    if (entry.id.startsWith('filter-model-')) {
+      if (entry.modelId && entry.providerKey) {
+        state.customTextFilter = `${entry.providerKey}/${entry.modelId}`
+        applyTierFilter()
+        refreshVisibleSorted({ resetCursor: true })
+      }
+      return
+    }
+
+    // 📖 Custom text filter — apply or remove the free-text filter from the command palette.
+    if (entry.id === 'filter-custom-text-apply') {
+      state.customTextFilter = entry.filterQuery || null
+      applyTierFilter()
+      refreshVisibleSorted({ resetCursor: true })
+      return
+    }
+    if (entry.id === 'filter-custom-text-remove') {
+      state.customTextFilter = null
+      applyTierFilter()
+      refreshVisibleSorted({ resetCursor: true })
       return
     }
 
@@ -731,6 +863,7 @@ export function createKeyHandler(ctx) {
         return
       }
       case 'action-toggle-favorite': return toggleFavoriteOnSelectedRow()
+      case 'action-toggle-favorite-mode': return toggleFavoritesDisplayMode()
       case 'action-reset-view': return resetViewSettings()
       default:
         return
@@ -758,6 +891,7 @@ export function createKeyHandler(ctx) {
       if (key.ctrl && key.name === 'c') { exit(0); return }
 
       const pageStep = Math.max(1, (state.terminalRows || 1) - 10)
+      const selected = state.commandPaletteResults[state.commandPaletteCursor]
 
       if (key.name === 'escape') {
         closeCommandPalette()
@@ -775,6 +909,23 @@ export function createKeyHandler(ctx) {
         state.commandPaletteCursor = state.commandPaletteCursor < count - 1 ? state.commandPaletteCursor + 1 : 0
         return
       }
+      if (key.name === 'left') {
+        if (selected?.hasChildren && selected.isExpanded) {
+          state.commandPaletteExpandedIds.delete(selected.id)
+          refreshCommandPaletteResults()
+        }
+        return
+      }
+      if (key.name === 'right') {
+        if (selected?.hasChildren && !selected.isExpanded) {
+          state.commandPaletteExpandedIds.add(selected.id)
+          refreshCommandPaletteResults()
+        } else if (selected?.type === 'command') {
+          closeCommandPalette()
+          executeCommandPaletteEntry(selected)
+        }
+        return
+      }
       if (key.name === 'pageup') {
         state.commandPaletteCursor = Math.max(0, state.commandPaletteCursor - pageStep)
         return
@@ -800,9 +951,17 @@ export function createKeyHandler(ctx) {
         return
       }
       if (key.name === 'return') {
-        const selectedCommand = state.commandPaletteResults[state.commandPaletteCursor]
-        closeCommandPalette()
-        executeCommandPaletteEntry(selectedCommand)
+        if (selected?.hasChildren) {
+          if (selected.isExpanded) {
+            state.commandPaletteExpandedIds.delete(selected.id)
+          } else {
+            state.commandPaletteExpandedIds.add(selected.id)
+          }
+          refreshCommandPaletteResults()
+        } else {
+          closeCommandPalette()
+          executeCommandPaletteEntry(selected)
+        }
         return
       }
       if (str && str.length === 1 && !key.ctrl && !key.meta) {
@@ -1354,7 +1513,8 @@ export function createKeyHandler(ctx) {
       const providerKeys = Object.keys(sources)
       const updateRowIdx = providerKeys.length
       const themeRowIdx = updateRowIdx + 1
-      const cleanupLegacyProxyRowIdx = themeRowIdx + 1
+      const favoritesModeRowIdx = themeRowIdx + 1
+      const cleanupLegacyProxyRowIdx = favoritesModeRowIdx + 1
       const changelogViewRowIdx = cleanupLegacyProxyRowIdx + 1
         // 📖 Profile system removed - API keys now persist permanently across all sessions
       const maxRowIdx = changelogViewRowIdx
@@ -1435,10 +1595,7 @@ export function createKeyHandler(ctx) {
         setResults(nextResults)
         syncFavoriteFlags(state.results, state.config)
         applyTierFilter()
-        const visible = state.results.filter(r => !r.hidden)
-        state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-        if (state.cursor >= state.visibleSorted.length) state.cursor = Math.max(0, state.visibleSorted.length - 1)
-        adjustScrollOffset(state)
+        refreshVisibleSorted({ resetCursor: false })
         // 📖 Re-ping all models that were 'noauth' (got 401 without key) but now have a key
         // 📖 This makes the TUI react immediately when a user adds an API key in settings
         const pingModel = getPingModel?.()
@@ -1503,6 +1660,11 @@ export function createKeyHandler(ctx) {
           return
         }
 
+        if (state.settingsCursor === favoritesModeRowIdx) {
+          toggleFavoritesDisplayMode()
+          return
+        }
+
         if (state.settingsCursor === cleanupLegacyProxyRowIdx) {
           runLegacyProxyCleanup()
           return
@@ -1541,6 +1703,10 @@ export function createKeyHandler(ctx) {
           cycleGlobalTheme()
           return
         }
+        if (state.settingsCursor === favoritesModeRowIdx) {
+          toggleFavoritesDisplayMode()
+          return
+        }
         // 📖 Profile system removed - API keys now persist permanently across all sessions
 
         // 📖 Toggle enabled/disabled for selected provider
@@ -1556,6 +1722,7 @@ export function createKeyHandler(ctx) {
         if (
           state.settingsCursor === updateRowIdx
           || state.settingsCursor === themeRowIdx
+          || state.settingsCursor === favoritesModeRowIdx
           || state.settingsCursor === cleanupLegacyProxyRowIdx
           || state.settingsCursor === changelogViewRowIdx
         ) return
@@ -1573,6 +1740,12 @@ export function createKeyHandler(ctx) {
         return
       }
 
+      // 📖 Y toggles favorites display mode directly from Settings.
+      if (key.name === 'y') {
+        toggleFavoritesDisplayMode()
+        return
+      }
+
         // 📖 Profile system removed - API keys now persist permanently across all sessions
 
       if (key.ctrl && key.name === 'c') { exit(0); return }
@@ -1619,9 +1792,18 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    // 📖 Y key: open Install Endpoints flow for configured providers.
-    if (key.name === 'y') {
-      openInstallEndpointsOverlay()
+    // 📖 Y key toggles favorites display mode (pinned+sticky vs normal rows).
+    if (key.name === 'y' && !key.ctrl && !key.meta) {
+      toggleFavoritesDisplayMode()
+      return
+    }
+
+    // 📖 X clears the active free-text filter set from the command palette.
+    if (key.name === 'x' && !key.ctrl && !key.meta) {
+      if (!state.customTextFilter) return
+      state.customTextFilter = null
+      applyTierFilter()
+      refreshVisibleSorted({ resetCursor: true })
       return
     }
 
@@ -1636,7 +1818,8 @@ export function createKeyHandler(ctx) {
     }
 
     // 📖 Sorting keys: R=rank, O=origin, M=model, L=latest ping, A=avg ping, S=SWE-bench, C=context, H=health, V=verdict, B=stability, U=uptime, G=usage
-    // 📖 T is reserved for tier filter cycling. Y now opens the install-endpoints flow.
+    // 📖 T is reserved for tier filter cycling. Y toggles favorites display mode.
+    // 📖 X clears the active custom text filter.
     // 📖 D is now reserved for provider filter cycling
     // 📖 Shift+R is reserved for reset view settings
     const sortKeys = {
@@ -1679,10 +1862,7 @@ export function createKeyHandler(ctx) {
       state.config.settings.hideUnconfiguredModels = state.hideUnconfiguredModels
       saveConfig(state.config)
       applyTierFilter()
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
+      refreshVisibleSorted({ resetCursor: true })
       return
     }
 
@@ -1691,10 +1871,7 @@ export function createKeyHandler(ctx) {
       state.tierFilterMode = (state.tierFilterMode + 1) % TIER_CYCLE.length
       applyTierFilter()
       // 📖 Recompute visible sorted list and reset cursor to avoid stale index into new filtered set
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
+      refreshVisibleSorted({ resetCursor: true })
       persistUiSettings()
       return
     }
@@ -1704,10 +1881,7 @@ export function createKeyHandler(ctx) {
       state.originFilterMode = (state.originFilterMode + 1) % ORIGIN_CYCLE.length
       applyTierFilter()
       // 📖 Recompute visible sorted list and reset cursor to avoid stale index into new filtered set
-      const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
-      state.cursor = 0
-      state.scrollOffset = 0
+      refreshVisibleSorted({ resetCursor: true })
       persistUiSettings()
       return
     }

package/src/overlays.js

@@ -94,7 +94,8 @@ export function createOverlayRenderers(state, deps) {
     const providerKeys = Object.keys(sources)
     const updateRowIdx = providerKeys.length
     const themeRowIdx = updateRowIdx + 1
-    const cleanupLegacyProxyRowIdx = themeRowIdx + 1
+    const favoritesModeRowIdx = themeRowIdx + 1
+    const cleanupLegacyProxyRowIdx = favoritesModeRowIdx + 1
     const changelogViewRowIdx = cleanupLegacyProxyRowIdx + 1
     const EL = '\x1b[K'
     const lines = []
@@ -224,6 +225,16 @@ export function createOverlayRenderers(state, deps) {
     const themeRow = `${bullet(state.settingsCursor === themeRowIdx)}${themeColors.textBold('Global Theme').padEnd(44)} ${themeStatusColor(themeStatus)}`
     cursorLineByRow[themeRowIdx] = lines.length
     lines.push(state.settingsCursor === themeRowIdx ? themeColors.bgCursor(themeRow) : themeRow)
+
+    // 📖 Favorites mode row mirrors Y-key behavior from the main table.
+    const favoritesModeEnabled = state.favoritesPinnedAndSticky === true
+    const favoritesModeStatus = favoritesModeEnabled
+      ? themeColors.warningBold('Pinned + always visible')
+      : themeColors.info('Normal rows (filter/sort)')
+    const favoritesModeRow = `${bullet(state.settingsCursor === favoritesModeRowIdx)}${themeColors.textBold('Favorites Display Mode').padEnd(44)} ${favoritesModeStatus}`
+    cursorLineByRow[favoritesModeRowIdx] = lines.length
+    lines.push(state.settingsCursor === favoritesModeRowIdx ? themeColors.bgCursorSettingsList(favoritesModeRow) : favoritesModeRow)
+
     if (updateState === 'error' && state.settingsUpdateError) {
       lines.push(themeColors.error(`      ${state.settingsUpdateError}`))
     }
@@ -244,7 +255,7 @@ export function createOverlayRenderers(state, deps) {
     if (state.settingsEditMode) {
       lines.push(themeColors.dim('  Type API key  •  Enter Save  •  Esc Cancel'))
     } else {
-      lines.push(themeColors.dim('  ↑↓ Navigate  •  Enter Edit/Run/Cycle  •  + Add key  •  - Remove key  •  Space Toggle/Cycle  •  T Test key  •  U Updates  •  G Global theme  •  Esc Close'))
+      lines.push(themeColors.dim('  ↑↓ Navigate  •  Enter Edit/Run/Cycle  •  + Add key  •  - Remove key  •  Space Toggle/Cycle  •  T Test key  •  U Updates  •  G Global theme  •  Y Favorites mode  •  Esc Close'))
     }
     // 📖 Show sync/restore status message if set
     if (state.settingsSyncStatus) {
@@ -283,7 +294,7 @@ export function createOverlayRenderers(state, deps) {
 
   // ─── Install Endpoints overlay renderer ───────────────────────────────────
   // 📖 renderInstallEndpoints drives the provider → tool → scope → model flow
-  // 📖 behind the `Y` hotkey. It deliberately reuses the same overlay viewport
+  // 📖 opened from Settings/Command Palette. It deliberately reuses the same overlay viewport
   // 📖 helpers as Settings so long provider/model lists stay navigable.
   function renderInstallEndpoints() {
     const EL = '\x1b[K'
@@ -528,18 +539,16 @@ export function createOverlayRenderers(state, deps) {
 
   // ─── Command palette renderer ──────────────────────────────────────────────
   // 📖 renderCommandPalette draws a centered floating modal over the live table.
-  // 📖 It returns cursor-positioned ANSI rows instead of replacing the full screen,
-  // 📖 so ping updates continue to animate in the background behind the palette.
+  // 📖 Supports hierarchical categories with expand/collapse and rich colors.
   function renderCommandPalette() {
     const terminalRows = state.terminalRows || 24
     const terminalCols = state.terminalCols || 80
-    const panelWidth = Math.max(44, Math.min(96, terminalCols - 8))
-    const panelInnerWidth = Math.max(28, panelWidth - 4)
+    const panelWidth = Math.max(52, Math.min(100, terminalCols - 8))
+    const panelInnerWidth = Math.max(32, panelWidth - 4)
     const panelPad = 2
     const panelOuterWidth = panelWidth + (panelPad * 2)
-    const footerRowCount = 2
-    const headerRowCount = 3
-    const bodyRows = Math.max(6, Math.min(16, terminalRows - 12))
+    const headerRowCount = 4
+    const bodyRows = Math.max(8, Math.min(18, terminalRows - 12))
 
     const truncatePlain = (text, width) => {
       if (width <= 1) return ''
@@ -559,30 +568,70 @@ export function createOverlayRenderers(state, deps) {
     }
 
     const allResults = Array.isArray(state.commandPaletteResults) ? state.commandPaletteResults.slice(0, 80) : []
-    const groupedLines = []
+    const panelLines = []
     const cursorLineByRow = {}
-    let category = null
 
     if (allResults.length === 0) {
-      groupedLines.push(themeColors.dim('  No command found. Try a broader query.'))
+      panelLines.push(themeColors.dim('  No commands found. Try a different search.'))
     } else {
       for (let idx = 0; idx < allResults.length; idx++) {
         const entry = allResults[idx]
-        if (entry.category !== category) {
-          category = entry.category
-          groupedLines.push(themeColors.textBold(` ${category}`))
+        const isCursor = idx === state.commandPaletteCursor
+        
+        const indent = '  '.repeat(entry.depth || 0)
+        const expandIndicator = entry.hasChildren
+          ? (entry.isExpanded ? themeColors.infoBold('▼') : themeColors.dim('▶'))
+          : themeColors.dim('•')
+        
+        // 📖 Only use icon from entry, label should NOT include emoji
+        const iconPrefix = entry.icon ? `${entry.icon} ` : ''
+        const plainLabel = truncatePlain(entry.label, panelInnerWidth - indent.length - iconPrefix.length - 4)
+        const label = entry.matchPositions ? highlightMatch(plainLabel, entry.matchPositions) : plainLabel
+        
+        let rowLine
+        if (entry.type === 'category') {
+          rowLine = `${indent}${expandIndicator} ${iconPrefix}${themeColors.headerBold(label)}`
+        } else if (entry.type === 'subcategory') {
+          rowLine = `${indent}${expandIndicator} ${iconPrefix}${themeColors.textBold(label)}`
+        } else if (entry.type === 'page') {
+          // 📖 Pages are at root level with icon + label + shortcut + description
+          const shortcut = entry.shortcut ? themeColors.dim(` (${entry.shortcut})`) : ''
+          const description = entry.description ? themeColors.dim(` — ${entry.description}`) : ''
+          rowLine = `${expandIndicator} ${iconPrefix}${themeColors.textBold(label)}${shortcut}${description}`
+        } else if (entry.type === 'action') {
+          // 📖 Actions are at root level with icon + label + shortcut + description
+          const shortcut = entry.shortcut ? themeColors.dim(` (${entry.shortcut})`) : ''
+          const description = entry.description ? themeColors.dim(` — ${entry.description}`) : ''
+          rowLine = `${expandIndicator} ${iconPrefix}${themeColors.textBold(label)}${shortcut}${description}`
+        } else {
+          // 📖 Regular commands in submenus
+          const shortcut = entry.shortcut ? themeColors.dim(` (${entry.shortcut})`) : ''
+          const description = entry.description ? themeColors.dim(` — ${entry.description}`) : ''
+          // 📖 Color tiers and providers
+          let coloredLabel = label
+          let prefixWithIcon = iconPrefix
+          
+          if (entry.providerKey && !entry.icon) {
+            // 📖 Model filter: add provider icon
+            const providerIcon = '🏢'
+            prefixWithIcon = `${providerIcon} `
+            coloredLabel = themeColors.provider(entry.providerKey, label, { bold: false })
+          } else if (entry.tier) {
+            coloredLabel = themeColors.tier(entry.tier, label)
+          } else if (entry.providerKey) {
+            coloredLabel = themeColors.provider(entry.providerKey, label, { bold: false })
+          }
+          
+          rowLine = `${indent}  ${expandIndicator} ${prefixWithIcon}${coloredLabel}${shortcut}${description}`
         }
 
-        const isCursor = idx === state.commandPaletteCursor
-        const pointer = isCursor ? themeColors.accentBold('  ❯ ') : themeColors.dim('    ')
-        const shortcutText = entry.shortcut ? themeColors.dim(entry.shortcut) : ''
-        const shortcutWidth = entry.shortcut ? Math.min(16, displayWidth(entry.shortcut)) : 0
-        const labelMax = Math.max(12, panelInnerWidth - 8 - shortcutWidth)
-        const plainLabel = truncatePlain(entry.label, labelMax)
-        const label = highlightMatch(plainLabel, entry.matchPositions)
-        const row = `${pointer}${padEndDisplay(label, labelMax)}${entry.shortcut ? ` ${shortcutText}` : ''}`
-        cursorLineByRow[idx] = groupedLines.length
-        groupedLines.push(isCursor ? themeColors.bgCursor(row) : row)
+        cursorLineByRow[idx] = panelLines.length
+        
+        if (isCursor) {
+          panelLines.push(themeColors.bgCursor(rowLine))
+        } else {
+          panelLines.push(rowLine)
+        }
       }
     }
 
@@ -590,44 +639,43 @@ export function createOverlayRenderers(state, deps) {
     state.commandPaletteScrollOffset = keepOverlayTargetVisible(
       state.commandPaletteScrollOffset,
       targetLine,
-      groupedLines.length,
+      panelLines.length,
       bodyRows
     )
-    const { visible, offset } = sliceOverlayLines(groupedLines, state.commandPaletteScrollOffset, bodyRows)
+    const { visible, offset } = sliceOverlayLines(panelLines, state.commandPaletteScrollOffset, bodyRows)
     state.commandPaletteScrollOffset = offset
 
     const query = state.commandPaletteQuery || ''
     const queryWithCursor = query.length > 0
-      ? themeColors.textBold(`${query}▏`)
-      : themeColors.dim('type a command…') + themeColors.accentBold('▏')
+      ? `${query}${themeColors.accentBold('▏')}`
+      : themeColors.accentBold('▏') + themeColors.dim(' Search commands…')
 
-    const panelLines = []
-    const title = themeColors.textBold('Command Palette')
+    const headerLines = []
+    const title = themeColors.headerBold('⚡️ Command Palette')
     const titleLeft = ` ${title}`
-    const titleRight = themeColors.dim('Esc close')
-    const titleWidth = Math.max(1, panelInnerWidth - 1 - displayWidth('Esc close'))
-    panelLines.push(`${padEndDisplay(titleLeft, titleWidth)} ${titleRight}`)
-    panelLines.push(` ${padEndDisplay(`> ${queryWithCursor}`, panelInnerWidth)}`)
-    panelLines.push(themeColors.dim(` ${'-'.repeat(Math.max(1, panelInnerWidth))}`))
-
-    for (const line of visible) {
-      panelLines.push(` ${padEndDisplay(line, panelInnerWidth)}`)
-    }
+    const titleRight = themeColors.dim('Esc')
+    const titleWidth = Math.max(1, panelInnerWidth - 1 - displayWidth('Esc'))
+    headerLines.push(`${padEndDisplay(titleLeft, titleWidth)} ${titleRight}`)
+    headerLines.push(` ${padEndDisplay(`> ${queryWithCursor}`, panelInnerWidth)}`)
+    headerLines.push(themeColors.dim(` ${'─'.repeat(Math.max(1, panelInnerWidth))}`))
+
+    const footerLines = [
+      themeColors.dim(` ${'─'.repeat(Math.max(1, panelInnerWidth))}`),
+      ` ${padEndDisplay(themeColors.dim('↵ Select • ← → Expand'), panelInnerWidth)}`,
+      ` ${padEndDisplay(themeColors.dim('↑↓ Navigate • Type search'), panelInnerWidth)}`,
+    ]
 
-    // 📖 Keep panel body stable by filling with blank rows when result list is short.
-    while (panelLines.length < bodyRows + headerRowCount) {
-      panelLines.push(` ${' '.repeat(panelInnerWidth)}`)
+    const allPanelLines = [...headerLines, ...visible, ...footerLines]
+    
+    while (allPanelLines.length < bodyRows + headerRowCount + 3) {
+      allPanelLines.splice(headerLines.length + visible.length, 0, ` ${' '.repeat(panelInnerWidth)}`)
     }
 
-    panelLines.push(themeColors.dim(` ${'-'.repeat(Math.max(1, panelInnerWidth))}`))
-    panelLines.push(` ${padEndDisplay(themeColors.dim('↑↓ navigate • Enter run • Type to search'), panelInnerWidth)}`)
-    panelLines.push(` ${padEndDisplay(themeColors.dim('PgUp/PgDn • Home/End'), panelInnerWidth)}`)
-
     const blankPaddedLine = ' '.repeat(panelOuterWidth)
     const paddedPanelLines = [
       blankPaddedLine,
       blankPaddedLine,
-      ...panelLines.map((line) => `${' '.repeat(panelPad)}${padEndDisplay(line, panelWidth)}${' '.repeat(panelPad)}`),
+      ...allPanelLines.map((line) => `${' '.repeat(panelPad)}${padEndDisplay(line, panelWidth)}${' '.repeat(panelPad)}`),
       blankPaddedLine,
       blankPaddedLine,
     ]
@@ -641,8 +689,6 @@ export function createOverlayRenderers(state, deps) {
       return themeColors.overlayBgCommandPalette(padded)
     })
 
-    // 📖 Absolute cursor positioning overlays the palette on top of the existing table.
-    // 📖 The next frame starts with ALT_HOME, so this remains stable without manual cleanup.
     return tintedLines
       .map((line, idx) => `\x1b[${top + idx};${left}H${line}`)
       .join('')
@@ -678,8 +724,8 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${label('CTX')}         Context window size (128k, 200k, 256k, 1m, etc.)  ${hint('Sort:')} ${key('C')}`)
     lines.push(`              ${hint('Bigger context = the model can read more of your codebase at once without forgetting.')}`)
     lines.push('')
-    lines.push(`  ${label('Model')}       Model name (⭐ = favorited, pinned at top)  ${hint('Sort:')} ${key('M')}  ${hint('Favorite:')} ${key('F')}`)
-    lines.push(`              ${hint('Star the ones you like — they stay pinned at the top across restarts.')}`)
+    lines.push(`  ${label('Model')}       Model name (⭐ = favorited)  ${hint('Sort:')} ${key('M')}  ${hint('Favorite:')} ${key('F')}`)
+    lines.push(`              ${hint('Star the ones you like. Press Y to switch between pinned mode and normal filter/sort mode.')}`)
     lines.push('')
     lines.push(`  ${label('Provider')}    Provider source (NIM, Groq, Cerebras, etc.)  ${hint('Sort:')} ${key('O')}  ${hint('Cycle:')} ${key('D')}`)
     lines.push(`              ${hint('Same model on different providers can have very different speed and uptime.')}`)
@@ -716,11 +762,12 @@ export function createOverlayRenderers(state, deps) {
     lines.push('')
     lines.push(`  ${heading('Controls')}`)
     lines.push(`  ${key('W')}  Toggle ping mode  ${hint('(speed 2s → normal 10s → slow 30s → forced 4s)')}`)
-    lines.push(`  ${key('Ctrl+P')}  Open command palette  ${hint('(search and run actions quickly)')}`)
+    lines.push(`  ${key('Ctrl+P')}  Open ⚡️ command palette  ${hint('(search and run actions quickly)')}`)
     lines.push(`  ${key('E')}  Toggle configured models only  ${hint('(enabled by default)')}`)
     lines.push(`  ${key('Z')}  Cycle tool mode  ${hint('(OpenCode → Desktop → OpenClaw → Crush → Goose → Pi → Aider → Qwen → OpenHands → Amp)')}`)
-    lines.push(`  ${key('F')}  Toggle favorite on selected row  ${hint('(⭐ pinned at top, persisted)')}`)
-    lines.push(`  ${key('Y')}  Install endpoints  ${hint('(provider catalog → compatible tools, direct provider only)')}`)
+    lines.push(`  ${key('F')}  Toggle favorite on selected row  ${hint('(⭐ persisted across sessions)')}`)
+    lines.push(`  ${key('Y')}  Toggle favorites mode  ${hint('(Pinned + always visible ↔ Normal filter/sort behavior)')}`)
+    lines.push(`  ${key('X')}  Clear active text filter  ${hint('(remove custom query applied from ⚡️ Command Palette)')}`)
     lines.push(`  ${key('Q')}  Smart Recommend  ${hint('(🎯 find the best model for your task — questionnaire + live analysis)')}`)
     lines.push(`  ${key('G')}  Cycle theme  ${hint('(auto → dark → light)')}`)
     lines.push(`  ${themeColors.errorBold('I')}  Feedback, bugs & requests  ${hint('(📝 send anonymous feedback, bug reports, or feature requests)')}`)
@@ -736,7 +783,8 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${key('PgUp/PgDn')}    Jump by page`)
     lines.push(`  ${key('Home/End')}     Jump first/last row`)
     lines.push(`  ${key('Enter')}        Edit key / run selected maintenance action`)
-    lines.push(`  ${key('Space')}        Toggle provider enable/disable`)
+    lines.push(`  ${key('Space')}        Toggle selected row option (provider/theme/favorites)`)
+    lines.push(`  ${key('Y')}            Toggle favorites mode (global)`)
     lines.push(`  ${key('T')}            Test selected provider key`)
     lines.push(`  ${key('U')}            Check updates manually`)
     lines.push(`  ${key('G')}            Cycle theme globally`)