free-coding-models 0.3.17 → 0.3.19

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ---
 
+## 0.3.19
+
+### Added
+- **Command palette overlay (`Ctrl+P`)**: Added a searchable floating palette with fuzzy matching so users can quickly run filters, sorts, overlays, and global actions.
+
+### Changed
+- **Main footer and help discoverability**: surfaced `Ctrl+P` in table hints and Help overlay so the new command launcher is visible immediately.
+- **Command palette spacing polish**: added two-character inner padding around the floating palette so the overlay feels less cramped and visually cleaner.
+
+### Fixed
+- **Command palette visual jitter**: background ping cycles now pause while the command palette is open so table rows stop reshuffling during command search.
+- **Command palette background freeze**: while the palette is open, the full table behind it is now frozen (spinner glyphs, ping countdown, and dynamic row updates) and resumes instantly on close.
+
+## 0.3.18
+
+### Added
+- **Missing tool bootstrap flow**: FCM now detects when a target CLI is absent, offers a minimal in-TUI install confirmation, runs the official global install command, then resumes the selected model launch automatically.
+
+### Changed
+- **TUI readability overhaul across every screen**: the main table, Settings, Help, Smart Recommend, Feedback, and Changelog overlays now share a semantic high-contrast theme system instead of a patchwork of hardcoded colors.
+- **Global theme switching now works for real**: press `G` to cycle `auto → dark → light` live, and the Settings screen now exposes a visible `Global Theme` row for the same control.
+- **Launcher binary resolution**: direct tool launches now search PATH plus common user bin directories so a freshly installed CLI can be reused immediately in the same FCM session.
+
+### Fixed
+- **Theme repaint bugs**: provider colors, tier colors, separators, badges, cursor highlights, and overlay backgrounds now update immediately when the theme changes instead of keeping stale import-time colors.
+
 ## 0.3.17
 
 ### Added

package/README.md

@@ -103,6 +103,8 @@ free-coding-models
 
 On first run, you'll be prompted to enter your API key(s). You can skip providers and add more later with **`P`**.
 
+Need to fix contrast because your terminal theme is fighting the TUI? Press **`G`** at any time to cycle **Auto → Dark → Light**. The switch recolors the full interface live: table, Settings, Help, Smart Recommend, Feedback, and Changelog.
+
 **③ Pick a model and launch your tool:**
 
 ```
@@ -111,6 +113,8 @@ On first run, you'll be prompted to enter your API key(s). You can skip provider
 
 The model you select is automatically written into your tool's config (OpenCode, OpenClaw, Crush, etc.) and the tool opens immediately. Done.
 
+If the active CLI tool is missing, FCM now catches it before launch, offers a tiny Yes/No install prompt, installs the tool with its official global command, then resumes the same model launch automatically.
+
 > 💡 You can also run `free-coding-models --goose --tier S` to pre-filter to S-tier models for Goose before the TUI even opens.
 
 
@@ -171,8 +175,10 @@ Press **`Z`** in the TUI to cycle between tools without restarting.
 | `D` | Cycle provider filter |
 | `E` | Toggle configured-only mode |
 | `F` | Favorite / unfavorite model |
+| `G` | Cycle global theme (`Auto → Dark → Light`) |
+| `Ctrl+P` | Open command palette (search + run actions) |
 | `R/S/C/M/O/L/A/H/V/B/U` | Sort columns |
-| `P` | Settings (API keys, providers, updates) |
+| `P` | Settings (API keys, providers, updates, theme) |
 | `Y` | Install Endpoints (push provider into tool config) |
 | `Q` | Smart Recommend overlay |
 | `N` | Changelog |
@@ -195,8 +201,12 @@ Press **`Z`** in the TUI to cycle between tools without restarting.
 - **Configured-only default** — only shows providers you have keys for
 - **Keyless latency** — models ping even without an API key (show 🔑 NO KEY)
 - **Smart Recommend** — questionnaire picks the best model for your task type
+- **Command Palette** — `Ctrl+P` opens a searchable action launcher for filters, sorting, overlays, and quick toggles
 - **Install Endpoints** — push a full provider catalog into any tool's config (`Y`)
+- **Missing tool bootstrap** — detect absent CLIs, offer one-click install, then continue the selected launch automatically
 - **Width guardrail** — shows a warning instead of a broken table in narrow terminals
+- **Readable everywhere** — semantic theme palette keeps table rows, overlays, badges, and help screens legible in dark and light terminals
+- **Global theme switch** — `G` cycles `auto`, `dark`, and `light` live without restarting
 - **Auto-retry** — timeout models keep getting retried
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",

package/src/app.js

@@ -122,6 +122,7 @@ import { createOverlayRenderers } from '../src/overlays.js'
 import { createKeyHandler } from '../src/key-handler.js'
 import { getToolModeOrder, getToolMeta } from '../src/tool-metadata.js'
 import { startExternalTool } from '../src/tool-launchers.js'
+import { getToolInstallPlan, installToolWithPlan, isToolInstalled } from '../src/tool-bootstrap.js'
 import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../src/endpoint-installer.js'
 import { loadCache, saveCache, clearCache, getCacheAge } from '../src/cache.js'
 import { checkConfigSecurity } from '../src/security.js'
@@ -176,7 +177,7 @@ const LOCAL_VERSION = pkg.version
 export async function runApp(cliArgs, config) {
 
   // 📖 Detect user active terminal theme
-  detectActiveTheme(config.settings?.theme || 'dark')
+  detectActiveTheme(config.settings?.theme || 'auto')
 
   // 📖 Check config file security — warn and offer auto-fix if permissions are too open
   const securityCheck = checkConfigSecurity()
@@ -405,6 +406,12 @@ export async function runApp(cliArgs, config) {
     settingsUpdateError: null,    // 📖 Last update-check error message for maintenance row
     config,                       // 📖 Live reference to the config object (updated on save)
     visibleSorted: [],            // 📖 Cached visible+sorted models — shared between render loop and key handlers
+    commandPaletteOpen: false,    // 📖 Whether the Ctrl+P command palette overlay is active.
+    commandPaletteQuery: '',      // 📖 Current command palette search query.
+    commandPaletteCursor: 0,      // 📖 Selected command index in the filtered command list.
+    commandPaletteScrollOffset: 0, // 📖 Vertical scroll offset for the command palette result viewport.
+    commandPaletteResults: [],    // 📖 Cached fuzzy-filtered command entries for the command palette.
+    commandPaletteFrozenTable: null, // 📖 Frozen table snapshot rendered behind the command palette overlay.
     helpVisible: false,           // 📖 Whether the help overlay (K key) is active
     settingsScrollOffset: 0,      // 📖 Vertical scroll offset for Settings overlay viewport
     helpScrollOffset: 0,          // 📖 Vertical scroll offset for Help overlay viewport
@@ -420,6 +427,14 @@ export async function runApp(cliArgs, config) {
     installEndpointsSelectedModelIds: new Set(), // 📖 Multi-select buffer for the selected-models phase
     installEndpointsErrorMsg: null, // 📖 Temporary validation/error message inside the install flow
     installEndpointsResult: null, // 📖 Final install result shown in the result phase
+    // 📖 Missing-tool bootstrap overlay — confirms a one-click install before retrying the launch.
+    toolInstallPromptOpen: false,
+    toolInstallPromptCursor: 0,
+    toolInstallPromptScrollOffset: 0,
+    toolInstallPromptMode: null,
+    toolInstallPromptModel: null,
+    toolInstallPromptPlan: null,
+    toolInstallPromptErrorMsg: null,
     // 📖 Smart Recommend overlay state (Q key opens it)
     recommendOpen: false,         // 📖 Whether the recommend overlay is active
     recommendPhase: 'questionnaire', // 📖 'questionnaire'|'analyzing'|'results' — current phase
@@ -750,6 +765,9 @@ export async function runApp(cliArgs, config) {
     getInstallTargetModes,
     getProviderCatalogModels,
     getToolMeta,
+    getToolInstallPlan,
+    padEndDisplay,
+    displayWidth,
   })
 
   onKeyPress = createKeyHandler({
@@ -785,6 +803,9 @@ export async function runApp(cliArgs, config) {
     startOpenCode,
     startExternalTool,
     getToolModeOrder,
+    getToolInstallPlan,
+    isToolInstalled,
+    installToolWithPlan,
     startRecommendAnalysis: overlays.startRecommendAnalysis,
     stopRecommendAnalysis: overlays.stopRecommendAnalysis,
     sendBugReport,
@@ -844,14 +865,87 @@ export async function runApp(cliArgs, config) {
     refreshAutoPingMode()
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.toolInstallPromptOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen && !state.commandPaletteOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
+    let tableContent = null
+    if (state.commandPaletteOpen) {
+      if (!state.commandPaletteFrozenTable) {
+        // 📖 Freeze the full table (including countdown and spinner glyphs) while
+        // 📖 the command palette is open so the background remains perfectly static.
+        state.commandPaletteFrozenTable = renderTable(
+          state.results,
+          state.pendingPings,
+          state.frame,
+          state.cursor,
+          state.sortColumn,
+          state.sortDirection,
+          state.pingInterval,
+          state.lastPingTime,
+          state.mode,
+          state.tierFilterMode,
+          state.scrollOffset,
+          state.terminalRows,
+          state.terminalCols,
+          state.originFilterMode,
+          null,
+          state.pingMode,
+          state.pingModeSource,
+          state.hideUnconfiguredModels,
+          state.widthWarningStartedAt,
+          state.widthWarningDismissed,
+          state.widthWarningShowCount,
+          state.settingsUpdateState,
+          state.settingsUpdateLatestVersion,
+          false,
+          state.startupLatestVersion,
+          state.versionAlertsEnabled,
+          state.config.settings?.disableWidthsWarning ?? false
+        )
+      }
+      tableContent = state.commandPaletteFrozenTable
+    } else {
+      state.commandPaletteFrozenTable = null
+      tableContent = renderTable(
+        state.results,
+        state.pendingPings,
+        state.frame,
+        state.cursor,
+        state.sortColumn,
+        state.sortDirection,
+        state.pingInterval,
+        state.lastPingTime,
+        state.mode,
+        state.tierFilterMode,
+        state.scrollOffset,
+        state.terminalRows,
+        state.terminalCols,
+        state.originFilterMode,
+        null,
+        state.pingMode,
+        state.pingModeSource,
+        state.hideUnconfiguredModels,
+        state.widthWarningStartedAt,
+        state.widthWarningDismissed,
+        state.widthWarningShowCount,
+        state.settingsUpdateState,
+        state.settingsUpdateLatestVersion,
+        false,
+        state.startupLatestVersion,
+        state.versionAlertsEnabled,
+        state.config.settings?.disableWidthsWarning ?? false
+      )
+    }
+
     const content = state.settingsOpen
       ? overlays.renderSettings()
       : state.installEndpointsOpen
         ? overlays.renderInstallEndpoints()
+      : state.toolInstallPromptOpen
+        ? overlays.renderToolInstallPrompt()
+      : state.commandPaletteOpen
+        ? tableContent + overlays.renderCommandPalette()
       : state.recommendOpen
         ? overlays.renderRecommend()
         : state.feedbackOpen
@@ -860,7 +954,7 @@ export async function runApp(cliArgs, config) {
                 ? overlays.renderHelp()
               : state.changelogOpen
                 ? overlays.renderChangelog()
-                 : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, null, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, false, state.startupLatestVersion, state.versionAlertsEnabled, state.config.settings?.disableWidthsWarning ?? false)
+                 : tableContent
     process.stdout.write(ALT_HOME + content)
     if (process.stdout.isTTY) {
       process.stdout.flush && process.stdout.flush()
@@ -904,6 +998,15 @@ export async function runApp(cliArgs, config) {
   const runPingCycle = async () => {
     try {
     refreshAutoPingMode()
+
+    // 📖 Command palette intentionally pauses background ping bursts to avoid
+    // 📖 visible row jitter while users type and navigate commands.
+    if (state.commandPaletteOpen) {
+      state.lastPingTime = Date.now()
+      scheduleNextPing()
+      return
+    }
+
     state.lastPingTime = Date.now()
 
     // 📖 Refresh persisted usage snapshots each cycle so background usage data appears live in table.

package/src/command-palette.js

@@ -0,0 +1,170 @@
+/**
+ * @file command-palette.js
+ * @description Command palette registry and fuzzy search helpers for the main TUI.
+ *
+ * @functions
+ *   → `buildCommandPaletteEntries` — builds the current command list with dynamic provider/tier context
+ *   → `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 }
+ *
+ * @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'] },
+]
+
+const ID_TO_TIER = {
+  'filter-tier-all': null,
+  'filter-tier-splus': 'S+',
+  'filter-tier-s': 'S',
+  'filter-tier-aplus': 'A+',
+  'filter-tier-a': 'A',
+  'filter-tier-aminus': 'A-',
+  'filter-tier-bplus': 'B+',
+  'filter-tier-b': 'B',
+  '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,
+  }))
+}
+
+/**
+ * 📖 Fuzzy matching optimized for short command labels and keyboard aliases.
+ * @param {string} query
+ * @param {string} text
+ * @returns {{ matched: boolean, score: number, positions: number[] }}
+ */
+export function fuzzyMatchCommand(query, text) {
+  const q = (query || '').trim().toLowerCase()
+  const t = (text || '').toLowerCase()
+
+  if (!q) return { matched: true, score: 0, positions: [] }
+  if (!t) return { matched: false, score: 0, positions: [] }
+
+  let qIdx = 0
+  const positions = []
+  for (let i = 0; i < t.length && qIdx < q.length; i++) {
+    if (q[qIdx] === t[i]) {
+      positions.push(i)
+      qIdx++
+    }
+  }
+
+  if (qIdx !== q.length) return { matched: false, score: 0, positions: [] }
+
+  let score = q.length * 10
+
+  // 📖 Bonus when matches are contiguous.
+  for (let i = 1; i < positions.length; i++) {
+    if (positions[i] === positions[i - 1] + 1) score += 5
+  }
+
+  // 📖 Bonus for word boundaries and prefix matches.
+  for (const pos of positions) {
+    if (pos === 0) score += 8
+    else {
+      const prev = t[pos - 1]
+      if (prev === ' ' || prev === ':' || prev === '-' || prev === '/') score += 6
+    }
+  }
+
+  // 📖 Small penalty for very long labels so focused labels float up.
+  score -= Math.max(0, t.length - q.length)
+
+  return { matched: true, score, positions }
+}
+
+/**
+ * 📖 Filter and rank command palette entries by fuzzy score.
+ * @param {Array<{ id: string, label: string, category: string, keywords?: string[] }>} entries
+ * @param {string} query
+ * @returns {Array<{ id: string, label: string, category: string, shortcut?: string|null, keywords?: string[], score: number, matchPositions: number[] }>}
+ */
+export function filterCommandPaletteEntries(entries, query) {
+  const normalizedQuery = (query || '').trim()
+
+  const ranked = []
+  for (const entry of entries) {
+    const labelMatch = fuzzyMatchCommand(normalizedQuery, entry.label)
+    let bestScore = labelMatch.score
+    let matchPositions = labelMatch.positions
+    let matched = labelMatch.matched
+
+    if (!matched && Array.isArray(entry.keywords)) {
+      for (const keyword of entry.keywords) {
+        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
+          matchPositions = []
+        }
+      }
+    }
+
+    if (!matched) continue
+    ranked.push({ ...entry, score: bestScore, matchPositions })
+  }
+
+  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
+    return a.label.localeCompare(b.label)
+  })
+
+  return ranked
+}

package/src/config.js

@@ -210,7 +210,7 @@ function normalizeSettingsSection(settings) {
     ...safeSettings,
     hideUnconfiguredModels: typeof safeSettings.hideUnconfiguredModels === 'boolean' ? safeSettings.hideUnconfiguredModels : true,
     disableWidthsWarning: safeSettings.disableWidthsWarning === true,
-    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'dark',
+    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
 
@@ -231,7 +231,7 @@ function normalizeProfileSettings(settings) {
     ..._emptyProfileSettings(),
     ...safeSettings,
     disableWidthsWarning: safeSettings.disableWidthsWarning === true,
-    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'dark',
+    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
 
@@ -844,7 +844,7 @@ export function _emptyProfileSettings() {
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
     preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
     disableWidthsWarning: false, // 📖 Disable widths warning (default off)
-    theme: 'dark',        // 📖 'dark', 'light', or 'auto'
+    theme: 'auto',        // 📖 'auto' follows the terminal/OS theme, override with 'dark' or 'light' if needed
   }
 }