free-coding-models 0.3.21 → 0.3.23

package/src/command-palette.js

@@ -1,64 +1,295 @@
 /**
  * @file command-palette.js
  * @description Command palette registry and fuzzy search helpers for the main TUI.
+ *          Now supports hierarchical categories with expandable/collapsible groups.
  *
  * @functions
- *   → `buildCommandPaletteEntries` — builds the current command list with dynamic provider/tier context
+ *   → `buildCommandPaletteTree` — builds the hierarchical command tree with categories and subcategories
+ *   → `flattenCommandTree` — converts tree to flat list for filtering (respects expansion state)
  *   → `fuzzyMatchCommand` — scores a query against one string and returns match positions
  *   → `filterCommandPaletteEntries` — returns sorted command matches for a query
  *
- * @exports { COMMAND_CATEGORY_ORDER, buildCommandPaletteEntries, fuzzyMatchCommand, filterCommandPaletteEntries }
+ * @exports { buildCommandPaletteTree, flattenCommandTree, fuzzyMatchCommand, filterCommandPaletteEntries }
  *
  * @see src/key-handler.js
  * @see src/overlays.js
  */
 
-export const COMMAND_CATEGORY_ORDER = ['Filters', 'Sort', 'Pages', 'Actions']
-
-const COMMANDS = [
-  // 📖 Filters
-  { id: 'filter-tier-all', category: 'Filters', label: 'Filter tiers: all', shortcut: 'T', keywords: ['filter', 'tier', 'all'] },
-  { id: 'filter-tier-splus', category: 'Filters', label: 'Filter tiers: S+', shortcut: null, keywords: ['filter', 'tier', 's+'] },
-  { id: 'filter-tier-s', category: 'Filters', label: 'Filter tiers: S', shortcut: null, keywords: ['filter', 'tier', 's'] },
-  { id: 'filter-tier-aplus', category: 'Filters', label: 'Filter tiers: A+', shortcut: null, keywords: ['filter', 'tier', 'a+'] },
-  { id: 'filter-tier-a', category: 'Filters', label: 'Filter tiers: A', shortcut: null, keywords: ['filter', 'tier', 'a'] },
-  { id: 'filter-tier-aminus', category: 'Filters', label: 'Filter tiers: A-', shortcut: null, keywords: ['filter', 'tier', 'a-'] },
-  { id: 'filter-tier-bplus', category: 'Filters', label: 'Filter tiers: B+', shortcut: null, keywords: ['filter', 'tier', 'b+'] },
-  { id: 'filter-tier-b', category: 'Filters', label: 'Filter tiers: B', shortcut: null, keywords: ['filter', 'tier', 'b'] },
-  { id: 'filter-tier-c', category: 'Filters', label: 'Filter tiers: C', shortcut: null, keywords: ['filter', 'tier', 'c'] },
-  { id: 'filter-provider-cycle', category: 'Filters', label: 'Filter provider: cycle', shortcut: 'D', keywords: ['filter', 'provider', 'origin'] },
-  { id: 'filter-configured-toggle', category: 'Filters', label: 'Toggle configured-only models', shortcut: 'E', keywords: ['filter', 'configured', 'keys'] },
-
-  // 📖 Sorting
-  { id: 'sort-rank', category: 'Sort', label: 'Sort by rank', shortcut: 'R', keywords: ['sort', 'rank'] },
-  { id: 'sort-tier', category: 'Sort', label: 'Sort by tier', shortcut: null, keywords: ['sort', 'tier'] },
-  { id: 'sort-provider', category: 'Sort', label: 'Sort by provider', shortcut: 'O', keywords: ['sort', 'origin', 'provider'] },
-  { id: 'sort-model', category: 'Sort', label: 'Sort by model name', shortcut: 'M', keywords: ['sort', 'model', 'name'] },
-  { id: 'sort-latest-ping', category: 'Sort', label: 'Sort by latest ping', shortcut: 'L', keywords: ['sort', 'latest', 'ping'] },
-  { id: 'sort-avg-ping', category: 'Sort', label: 'Sort by average ping', shortcut: 'A', keywords: ['sort', 'avg', 'average', 'ping'] },
-  { id: 'sort-swe', category: 'Sort', label: 'Sort by SWE score', shortcut: 'S', keywords: ['sort', 'swe', 'score'] },
-  { id: 'sort-ctx', category: 'Sort', label: 'Sort by context window', shortcut: 'C', keywords: ['sort', 'context', 'ctx'] },
-  { id: 'sort-health', category: 'Sort', label: 'Sort by health', shortcut: 'H', keywords: ['sort', 'health', 'condition'] },
-  { id: 'sort-verdict', category: 'Sort', label: 'Sort by verdict', shortcut: 'V', keywords: ['sort', 'verdict'] },
-  { id: 'sort-stability', category: 'Sort', label: 'Sort by stability', shortcut: 'B', keywords: ['sort', 'stability'] },
-  { id: 'sort-uptime', category: 'Sort', label: 'Sort by uptime', shortcut: 'U', keywords: ['sort', 'uptime'] },
-
-  // 📖 Pages / overlays
-  { id: 'open-settings', category: 'Pages', label: 'Open settings', shortcut: 'P', keywords: ['settings', 'config', 'api key'] },
-  { id: 'open-help', category: 'Pages', label: 'Open help', shortcut: 'K', keywords: ['help', 'shortcuts', 'hotkeys'] },
-  { id: 'open-changelog', category: 'Pages', label: 'Open changelog', shortcut: 'N', keywords: ['changelog', 'release'] },
-  { id: 'open-feedback', category: 'Pages', label: 'Open feedback', shortcut: 'I', keywords: ['feedback', 'bug', 'request'] },
-  { id: 'open-recommend', category: 'Pages', label: 'Open smart recommend', shortcut: 'Q', keywords: ['recommend', 'best model'] },
-  { id: 'open-install-endpoints', category: 'Pages', label: 'Open install endpoints', shortcut: 'Y', keywords: ['install', 'endpoints', 'providers'] },
-
-  // 📖 Actions
-  { id: 'action-cycle-theme', category: 'Actions', label: 'Cycle theme', shortcut: 'G', keywords: ['theme', 'dark', 'light', 'auto'] },
-  { id: 'action-cycle-tool-mode', category: 'Actions', label: 'Cycle tool mode', shortcut: 'Z', keywords: ['tool', 'mode', 'launcher'] },
-  { id: 'action-cycle-ping-mode', category: 'Actions', label: 'Cycle ping mode', shortcut: 'W', keywords: ['ping', 'cadence', 'speed', 'slow'] },
-  { id: 'action-toggle-favorite', category: 'Actions', label: 'Toggle favorite on selected model', shortcut: 'F', keywords: ['favorite', 'star'] },
-  { id: 'action-reset-view', category: 'Actions', label: 'Reset view settings', shortcut: 'Shift+R', keywords: ['reset', 'view', 'sort', 'filters'] },
+import { TOOL_METADATA, TOOL_MODE_ORDER } from './tool-metadata.js'
+
+const TOOL_MODE_DESCRIPTIONS = {
+  opencode: 'Launch in OpenCode CLI with the selected model.',
+  'opencode-desktop': 'Set model in shared config, then open OpenCode Desktop.',
+  openclaw: 'Set default model in OpenClaw and launch it.',
+  crush: 'Launch Crush with this provider/model pair.',
+  goose: 'Launch Goose and preselect the active model.',
+  pi: 'Launch Pi with model/provider flags.',
+  aider: 'Launch Aider configured on the selected model.',
+  qwen: 'Launch Qwen Code using the selected provider model.',
+  openhands: 'Launch OpenHands with the selected model endpoint.',
+  amp: 'Launch Amp with this model as active target.',
+}
+
+const TOOL_MODE_COMMANDS = TOOL_MODE_ORDER.map((toolMode) => {
+  const meta = TOOL_METADATA[toolMode] || { label: toolMode, emoji: '🧰' }
+  return {
+    id: `action-set-tool-${toolMode}`,
+    label: meta.label,
+    toolMode,
+    icon: meta.emoji,
+    description: TOOL_MODE_DESCRIPTIONS[toolMode] || 'Set this as the active launch target.',
+    keywords: ['tool', 'target', 'mode', toolMode, meta.label.toLowerCase()],
+  }
+})
+
+const PING_MODE_COMMANDS = [
+  {
+    id: 'action-cycle-ping-mode',
+    label: 'Cycle ping mode',
+    shortcut: 'W',
+    icon: '⚡',
+    description: 'Rotate speed → normal → slow → forced.',
+    keywords: ['ping', 'mode', 'cycle', 'speed', 'normal', 'slow', 'forced'],
+  },
+  {
+    id: 'action-set-ping-speed',
+    label: 'Speed mode (2s)',
+    pingMode: 'speed',
+    description: 'Fast 2s bursts for short live checks.',
+    keywords: ['ping', 'mode', 'speed', '2s', 'fast'],
+  },
+  {
+    id: 'action-set-ping-normal',
+    label: 'Normal mode (10s)',
+    pingMode: 'normal',
+    description: 'Balanced default cadence for daily use.',
+    keywords: ['ping', 'mode', 'normal', '10s', 'default'],
+  },
+  {
+    id: 'action-set-ping-slow',
+    label: 'Slow mode (30s)',
+    pingMode: 'slow',
+    description: 'Lower refresh cost when you are mostly idle.',
+    keywords: ['ping', 'mode', 'slow', '30s', 'idle'],
+  },
+  {
+    id: 'action-set-ping-forced',
+    label: 'Forced mode (4s)',
+    pingMode: 'forced',
+    description: 'Keeps 4s cadence until manually changed.',
+    keywords: ['ping', 'mode', 'forced', '4s', 'manual'],
+  },
 ]
 
+// 📖 Base command tree template (will be enhanced with dynamic model list)
+const BASE_COMMAND_TREE = [
+  {
+    id: 'filters',
+    label: 'Filters',
+    icon: '🔍',
+    children: [
+      {
+        id: 'filter-tier',
+        label: 'Filter by tier',
+        icon: '📊',
+        children: [
+          { id: 'filter-tier-all', label: 'All tiers', tier: null, shortcut: 'T', description: 'Show all models', keywords: ['filter', 'tier', 'all'] },
+          { id: 'filter-tier-splus', label: 'S+ tier', tier: 'S+', description: 'Best coding models', keywords: ['filter', 'tier', 's+'] },
+          { id: 'filter-tier-s', label: 'S tier', tier: 'S', description: 'Excellent models', keywords: ['filter', 'tier', 's'] },
+          { id: 'filter-tier-aplus', label: 'A+ tier', tier: 'A+', description: 'Very good models', keywords: ['filter', 'tier', 'a+'] },
+          { id: 'filter-tier-a', label: 'A tier', tier: 'A', description: 'Good models', keywords: ['filter', 'tier', 'a'] },
+          { id: 'filter-tier-aminus', label: 'A- tier', tier: 'A-', description: 'Solid models', keywords: ['filter', 'tier', 'a-'] },
+          { id: 'filter-tier-bplus', label: 'B+ tier', tier: 'B+', description: 'Fair models', keywords: ['filter', 'tier', 'b+'] },
+          { id: 'filter-tier-b', label: 'B tier', tier: 'B', description: 'Basic models', keywords: ['filter', 'tier', 'b'] },
+          { id: 'filter-tier-c', label: 'C tier', tier: 'C', description: 'Limited models', keywords: ['filter', 'tier', 'c'] },
+        ]
+      },
+      {
+        id: 'filter-provider',
+        label: 'Filter by provider',
+        icon: '🏢',
+        children: [
+          { id: 'filter-provider-cycle', label: 'Cycle provider', shortcut: 'D', description: 'Switch between providers', keywords: ['filter', 'provider', 'origin'] },
+          { id: 'filter-provider-all', label: 'All providers', providerKey: null, description: 'Show all providers', keywords: ['filter', 'provider', 'all'] },
+          { id: 'filter-provider-nvidia', label: 'NVIDIA NIM', providerKey: 'nvidiaNim', description: 'NVIDIA models', keywords: ['filter', 'provider', 'nvidia', 'nim'] },
+          { id: 'filter-provider-groq', label: 'Groq', providerKey: 'groq', description: 'Groq models', keywords: ['filter', 'provider', 'groq'] },
+          { id: 'filter-provider-cerebras', label: 'Cerebras', providerKey: 'cerebras', description: 'Cerebras models', keywords: ['filter', 'provider', 'cerebras'] },
+          { id: 'filter-provider-sambanova', label: 'SambaNova', providerKey: 'sambanova', description: 'SambaNova models', keywords: ['filter', 'provider', 'sambanova'] },
+          { id: 'filter-provider-openrouter', label: 'OpenRouter', providerKey: 'openrouter', description: 'OpenRouter models', keywords: ['filter', 'provider', 'openrouter'] },
+          { id: 'filter-provider-together', label: 'Together AI', providerKey: 'together', description: 'Together models', keywords: ['filter', 'provider', 'together'] },
+          { id: 'filter-provider-deepinfra', label: 'DeepInfra', providerKey: 'deepinfra', description: 'DeepInfra models', keywords: ['filter', 'provider', 'deepinfra'] },
+          { id: 'filter-provider-fireworks', label: 'Fireworks AI', providerKey: 'fireworks', description: 'Fireworks models', keywords: ['filter', 'provider', 'fireworks'] },
+          { id: 'filter-provider-hyperbolic', label: 'Hyperbolic', providerKey: 'hyperbolic', description: 'Hyperbolic models', keywords: ['filter', 'provider', 'hyperbolic'] },
+          { id: 'filter-provider-google', label: 'Google AI', providerKey: 'google', description: 'Google models', keywords: ['filter', 'provider', 'google'] },
+          { id: 'filter-provider-huggingface', label: 'Hugging Face', providerKey: 'huggingface', description: 'Hugging Face models', keywords: ['filter', 'provider', 'huggingface'] },
+        ]
+      },
+      {
+        id: 'filter-model',
+        label: 'Filter by model',
+        icon: '🤖',
+        children: []
+      },
+      {
+        id: 'filter-other',
+        label: 'Other filters',
+        icon: '⚙️',
+        children: [
+          { id: 'filter-configured-toggle', label: 'Toggle configured-only', shortcut: 'E', description: 'Show only configured providers', keywords: ['filter', 'configured', 'keys'] },
+        ]
+      },
+    ]
+  },
+  {
+    id: 'sort',
+    label: 'Sort',
+    icon: '📶',
+    children: [
+      { id: 'sort-rank', label: 'Sort by rank', shortcut: 'R', description: 'Rank by SWE score', keywords: ['sort', 'rank'] },
+      { id: 'sort-tier', label: 'Sort by tier', description: 'Group by quality tier', keywords: ['sort', 'tier'] },
+      { id: 'sort-provider', label: 'Sort by provider', shortcut: 'O', description: 'Group by provider', keywords: ['sort', 'origin', 'provider'] },
+      { id: 'sort-model', label: 'Sort by model', shortcut: 'M', description: 'Alphabetical order', keywords: ['sort', 'model', 'name'] },
+      { id: 'sort-latest-ping', label: 'Sort by latest ping', shortcut: 'L', description: 'Recent response time', keywords: ['sort', 'latest', 'ping'] },
+      { id: 'sort-avg-ping', label: 'Sort by avg ping', shortcut: 'A', description: 'Average response time', keywords: ['sort', 'avg', 'average', 'ping'] },
+      { id: 'sort-swe', label: 'Sort by SWE score', shortcut: 'S', description: 'Coding ability score', keywords: ['sort', 'swe', 'score'] },
+      { id: 'sort-ctx', label: 'Sort by context', shortcut: 'C', description: 'Context window size', keywords: ['sort', 'context', 'ctx'] },
+      { id: 'sort-health', label: 'Sort by health', shortcut: 'H', description: 'Current model status', keywords: ['sort', 'health', 'condition'] },
+      { id: 'sort-verdict', label: 'Sort by verdict', shortcut: 'V', description: 'Overall assessment', keywords: ['sort', 'verdict'] },
+      { id: 'sort-stability', label: 'Sort by stability', shortcut: 'B', description: 'Reliability score', keywords: ['sort', 'stability'] },
+      { id: 'sort-uptime', label: 'Sort by uptime', shortcut: 'U', description: 'Success rate', keywords: ['sort', 'uptime'] },
+    ]
+  },
+  {
+    id: 'actions',
+    label: 'Actions',
+    icon: '⚙️',
+    children: [
+      {
+        id: 'action-target-tool',
+        label: 'Target tool',
+        icon: '🧰',
+        children: [
+          { id: 'action-cycle-tool-mode', label: 'Cycle target tool', shortcut: 'Z', icon: '🔄', description: 'Rotate through every launcher mode.', keywords: ['tool', 'mode', 'cycle', 'target'] },
+          ...TOOL_MODE_COMMANDS,
+        ],
+      },
+      {
+        id: 'action-ping-mode',
+        label: 'Ping mode',
+        icon: '📶',
+        children: PING_MODE_COMMANDS,
+      },
+      {
+        id: 'action-favorites-mode',
+        label: 'Favorites mode',
+        icon: '⭐',
+        children: [
+          { id: 'action-toggle-favorite-mode', label: 'Toggle favorites mode', shortcut: 'Y', icon: '⭐', description: 'Switch pinned+sticky ↔ normal list behavior.', keywords: ['favorite', 'favorites', 'mode', 'toggle', 'y'] },
+          { id: 'action-favorites-mode-pinned', label: 'Pinned + always visible', favoritesPinned: true, description: 'Favorites stay on top and bypass current filters.', keywords: ['favorite', 'favorites', 'pinned', 'sticky', 'always visible'] },
+          { id: 'action-favorites-mode-normal', label: 'Normal rows (starred only)', favoritesPinned: false, description: 'Favorites keep ⭐ but follow active filters and sort.', keywords: ['favorite', 'favorites', 'normal', 'sort', 'filter'] },
+          { id: 'action-toggle-favorite', label: 'Toggle favorite on selected row', shortcut: 'F', icon: '⭐', description: 'Star/unstar the highlighted model.', keywords: ['favorite', 'star', 'toggle'] },
+        ],
+      },
+      { id: 'action-cycle-theme', label: 'Cycle theme', shortcut: 'G', icon: '🌗', description: 'Switch dark/light/auto', keywords: ['theme', 'dark', 'light', 'auto'] },
+      { id: 'action-reset-view', label: 'Reset view', shortcut: 'Shift+R', icon: '🔄', description: 'Reset filters and sort', keywords: ['reset', 'view', 'sort', 'filters'] },
+    ],
+  },
+  // 📖 Pages - directly at root level, not in submenu
+  { id: 'open-settings', label: 'Settings', shortcut: 'P', icon: '⚙️', type: 'page', description: 'API keys and preferences', keywords: ['settings', 'config', 'api key'] },
+  { id: 'open-help', label: 'Help', shortcut: 'K', icon: '❓', type: 'page', description: 'Show all shortcuts', keywords: ['help', 'shortcuts', 'hotkeys'] },
+  { id: 'open-changelog', label: 'Changelog', shortcut: 'N', icon: '📋', type: 'page', description: 'Version history', keywords: ['changelog', 'release'] },
+  { id: 'open-feedback', label: 'Feedback', shortcut: 'I', icon: '📝', type: 'page', description: 'Report bugs or requests', keywords: ['feedback', 'bug', 'request'] },
+  { id: 'open-recommend', label: 'Smart recommend', shortcut: 'Q', icon: '🎯', type: 'page', description: 'Find best model for task', keywords: ['recommend', 'best model'] },
+  { id: 'open-install-endpoints', label: 'Install endpoints', icon: '🔌', type: 'page', description: 'Install provider catalogs', keywords: ['install', 'endpoints', 'providers'] },
+]
+
+/**
+ * 📖 Build the command palette tree with dynamic model filters.
+ * @param {Array} visibleModels - Optional list of visible models to create model filter entries
+ * @returns {Array} The command tree with model filters added
+ */
+export function buildCommandPaletteTree(visibleModels = []) {
+  // 📖 Clone the base tree
+  const tree = JSON.parse(JSON.stringify(BASE_COMMAND_TREE))
+  
+  // 📖 Find the filter-model category and add dynamic model entries
+  const filterModelCategory = tree.find(cat => cat.id === 'filters')
+    ?.children.find(sub => sub.id === 'filter-model')
+  
+  if (filterModelCategory && Array.isArray(visibleModels) && visibleModels.length > 0) {
+    // 📖 Add top 20 most-used or most relevant models
+    const topModels = visibleModels
+      .filter(m => !m.hidden && m.status !== 'noauth')
+      .slice(0, 20)
+    
+    for (const model of topModels) {
+      filterModelCategory.children.push({
+        id: `filter-model-${model.providerKey}-${model.modelId}`,
+        label: model.label,
+        modelId: model.modelId,
+        providerKey: model.providerKey,
+        keywords: ['filter', 'model', model.label.toLowerCase(), model.modelId.toLowerCase()],
+      })
+    }
+  }
+  
+  return tree
+}
+
+/**
+ * 📖 Flatten the command tree into a list, respecting which nodes are expanded.
+ * @param {Array} tree - The command tree
+ * @param {Set} expandedIds - Set of IDs that are expanded
+ * @returns {Array} Flat list with type markers ('category' | 'subcategory' | 'command' | 'page' | 'action')
+ */
+export function flattenCommandTree(tree, expandedIds = new Set()) {
+  const result = []
+  
+  function traverse(nodes, depth = 0) {
+    for (const node of nodes) {
+      // 📖 Check if this is a direct page/action (not in a submenu)
+      if (node.type === 'page' || node.type === 'action') {
+        result.push({
+          ...node,
+          type: node.type,
+          depth: 0,
+          hasChildren: false,
+          isExpanded: false,
+        })
+        continue
+      }
+      
+      const isExpanded = expandedIds.has(node.id)
+      const hasChildren = Array.isArray(node.children) && node.children.length > 0
+      
+      if (hasChildren) {
+        result.push({
+          ...node,
+          type: depth === 0 ? 'category' : 'subcategory',
+          depth,
+          hasChildren,
+          isExpanded,
+        })
+        
+        if (isExpanded) {
+          traverse(node.children, depth + 1)
+        }
+      } else {
+        result.push({
+          ...node,
+          type: 'command',
+          depth,
+          hasChildren: false,
+          isExpanded: false,
+        })
+      }
+    }
+  }
+  
+  traverse(tree)
+  return result
+}
+
 const ID_TO_TIER = {
   'filter-tier-all': null,
   'filter-tier-splus': 'S+',
@@ -71,11 +302,31 @@ const ID_TO_TIER = {
   'filter-tier-c': 'C',
 }
 
-export function buildCommandPaletteEntries() {
-  return COMMANDS.map((entry) => ({
-    ...entry,
-    tierValue: Object.prototype.hasOwnProperty.call(ID_TO_TIER, entry.id) ? ID_TO_TIER[entry.id] : undefined,
-  }))
+/**
+ * 📖 Legacy function for backward compatibility - builds flat list from tree.
+ * 📖 Expands all categories so every command is searchable by fuzzyMatchCommand.
+ * @param {Array} visibleModels - Optional list of visible models for model filter entries
+ */
+export function buildCommandPaletteEntries(visibleModels = []) {
+  const tree = buildCommandPaletteTree(visibleModels)
+  // 📖 Collect every node id that has children so flattenCommandTree traverses into them.
+  const allIds = new Set()
+  function collectIds(nodes) {
+    for (const n of nodes) {
+      allIds.add(n.id)
+      if (Array.isArray(n.children)) collectIds(n.children)
+    }
+  }
+  collectIds(tree)
+  const flat = flattenCommandTree(tree, allIds)
+  return flat.map((entry) => {
+    // 📖 Copy tier and providerKey properties to tierValue for backward compatibility
+    const result = { ...entry }
+    if (entry.tier !== undefined) {
+      result.tierValue = entry.tier
+    }
+    return result
+  })
 }
 
 /**
@@ -126,15 +377,20 @@ export function fuzzyMatchCommand(query, text) {
 
 /**
  * 📖 Filter and rank command palette entries by fuzzy score.
- * @param {Array<{ id: string, label: string, category: string, keywords?: string[] }>} entries
+ * Now handles hierarchical structure with expandable categories.
+ * @param {Array} flatEntries - Flattened command tree entries
  * @param {string} query
- * @returns {Array<{ id: string, label: string, category: string, shortcut?: string|null, keywords?: string[], score: number, matchPositions: number[] }>}
+ * @returns {Array} Sorted and filtered entries with match scores
  */
-export function filterCommandPaletteEntries(entries, query) {
+export function filterCommandPaletteEntries(flatEntries, query) {
   const normalizedQuery = (query || '').trim()
+  
+  if (!normalizedQuery) {
+    return flatEntries
+  }
 
   const ranked = []
-  for (const entry of entries) {
+  for (const entry of flatEntries) {
     const labelMatch = fuzzyMatchCommand(normalizedQuery, entry.label)
     let bestScore = labelMatch.score
     let matchPositions = labelMatch.positions
@@ -145,7 +401,6 @@ export function filterCommandPaletteEntries(entries, query) {
         const keywordMatch = fuzzyMatchCommand(normalizedQuery, keyword)
         if (!keywordMatch.matched) continue
         matched = true
-        // 📖 Keyword matches should rank below direct label matches.
         const keywordScore = Math.max(1, keywordMatch.score - 7)
         if (keywordScore > bestScore) {
           bestScore = keywordScore
@@ -158,11 +413,24 @@ export function filterCommandPaletteEntries(entries, query) {
     ranked.push({ ...entry, score: bestScore, matchPositions })
   }
 
+  // Auto-expand categories that contain matches
+  const result = []
+  const idsToExpand = new Set()
+  
+  // First pass: mark all categories containing matched items
+  for (const entry of ranked) {
+    if (entry.type === 'command' && entry.matchPositions) {
+      // Find parent categories
+      let current = result.find(r => r.id === entry.id)
+      if (current) {
+        idsToExpand.add(entry.parentId)
+      }
+    }
+  }
+
   ranked.sort((a, b) => {
     if (b.score !== a.score) return b.score - a.score
-    const aCat = COMMAND_CATEGORY_ORDER.indexOf(a.category)
-    const bCat = COMMAND_CATEGORY_ORDER.indexOf(b.category)
-    if (aCat !== bCat) return aCat - bCat
+    if (a.depth !== b.depth) return a.depth - b.depth
     return a.label.localeCompare(b.label)
   })
 

package/src/config.js

@@ -209,6 +209,7 @@ function normalizeSettingsSection(settings) {
   return {
     ...safeSettings,
     hideUnconfiguredModels: typeof safeSettings.hideUnconfiguredModels === 'boolean' ? safeSettings.hideUnconfiguredModels : true,
+    favoritesPinnedAndSticky: typeof safeSettings.favoritesPinnedAndSticky === 'boolean' ? safeSettings.favoritesPinnedAndSticky : false,
     theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
@@ -831,7 +832,7 @@ export function isProviderEnabled(config, providerKey) {
 /**
  * 📖 _emptyProfileSettings: Default TUI settings.
  *
- * @returns {{ tierFilter: string|null, sortColumn: string, sortAsc: boolean, pingInterval: number, hideUnconfiguredModels: boolean, preferredToolMode: string }}
+ * @returns {{ tierFilter: string|null, sortColumn: string, sortAsc: boolean, pingInterval: number, hideUnconfiguredModels: boolean, favoritesPinnedAndSticky: boolean, preferredToolMode: string }}
  */
 export function _emptyProfileSettings() {
   return {
@@ -840,6 +841,7 @@ export function _emptyProfileSettings() {
     sortAsc: true,        // 📖 true = ascending (fastest first for latency)
     pingInterval: 10000,  // 📖 default ms between pings in the steady "normal" mode
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
+    favoritesPinnedAndSticky: false, // 📖 default mode keeps favorites as normal starred rows; press Y to pin+stick them.
     preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
     theme: 'auto',        // 📖 'auto' follows the terminal/OS theme, override with 'dark' or 'light' if needed
   }
@@ -848,7 +850,7 @@ export function _emptyProfileSettings() {
 /**
  * 📖 normalizeEndpointInstalls keeps the endpoint-install tracking list safe to replay.
  *
- * 📖 Each entry represents one managed catalog install performed through the `Y` flow:
+ * 📖 Each entry represents one managed catalog install performed through Install Endpoints:
  *   - `providerKey`: FCM provider identifier (`nvidia`, `groq`, ...)
  *   - `toolMode`: canonical tool id (`opencode`, `openclaw`, `crush`, `goose`)
  *   - `scope`: `all` or `selected`

package/src/endpoint-installer.js

@@ -3,7 +3,7 @@
  * @description Install and refresh FCM-managed provider catalogs inside external tool configs.
  *
  * @details
- *   📖 This module powers the `Y` hotkey flow in the TUI.
+ *   📖 This module powers the Install Endpoints flow in the TUI.
  *   It lets users pick one configured provider, choose a target tool, then install either:
  *   - the full provider catalog (`all` models), or
  *   - a curated subset of specific models (`selected`)