free-coding-models 0.1.67 → 0.1.69

package/bin/free-coding-models.js

@@ -11,7 +11,7 @@
  *
  *   🎯 Key features:
  *   - Parallel pings across all models with animated real-time updates (multi-provider)
- *   - Continuous monitoring with 2-second ping intervals (never stops)
+ *   - Continuous monitoring with 60-second ping intervals (never stops)
  *   - Rolling averages calculated from ALL successful pings since start
  *   - Best-per-tier highlighting with medals (🥇🥈🥉)
  *   - Interactive navigation with arrow keys directly in the table
@@ -60,13 +60,14 @@
  *   ⚙️ Configuration:
  *   - API keys stored per-provider in ~/.free-coding-models.json (0600 perms)
  *   - Old ~/.free-coding-models plain-text auto-migrated as nvidia key on first run
- *   - Env vars override config: NVIDIA_API_KEY, GROQ_API_KEY, CEREBRAS_API_KEY, OPENROUTER_API_KEY, HUGGINGFACE_API_KEY/HF_TOKEN, REPLICATE_API_TOKEN, DEEPINFRA_API_KEY/DEEPINFRA_TOKEN, FIREWORKS_API_KEY, SILICONFLOW_API_KEY, TOGETHER_API_KEY, PERPLEXITY_API_KEY, etc.
+ *   - Env vars override config: NVIDIA_API_KEY, GROQ_API_KEY, CEREBRAS_API_KEY, OPENROUTER_API_KEY, HUGGINGFACE_API_KEY/HF_TOKEN, REPLICATE_API_TOKEN, DEEPINFRA_API_KEY/DEEPINFRA_TOKEN, FIREWORKS_API_KEY, SILICONFLOW_API_KEY, TOGETHER_API_KEY, PERPLEXITY_API_KEY, ZAI_API_KEY, etc.
+ *   - ZAI (z.ai) uses a non-standard base path; cloudflare needs CLOUDFLARE_ACCOUNT_ID in env.
  *   - Cloudflare Workers AI requires both CLOUDFLARE_API_TOKEN (or CLOUDFLARE_API_KEY) and CLOUDFLARE_ACCOUNT_ID
  *   - Models loaded from sources.js — all provider/model definitions are centralized there
  *   - OpenCode config: ~/.config/opencode/opencode.json
  *   - OpenClaw config: ~/.openclaw/openclaw.json
  *   - Ping timeout: 15s per attempt
- *   - Ping interval: 2 seconds (continuous monitoring mode)
+ *   - Ping interval: 60 seconds (continuous monitoring mode)
  *   - Animation: 12 FPS with braille spinners
  *
  *   🚀 CLI flags:
@@ -91,10 +92,12 @@ import { randomUUID } from 'crypto'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
 import { createServer } from 'net'
+import { createServer as createHttpServer } from 'http'
+import { request as httpsRequest } from 'https'
 import { MODELS, sources } from '../sources.js'
 import { patchOpenClawModelsJson } from '../patch-openclaw-models.js'
-import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP } from '../lib/utils.js'
-import { loadConfig, saveConfig, getApiKey, isProviderEnabled } from '../lib/config.js'
+import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS } from '../lib/utils.js'
+import { loadConfig, saveConfig, getApiKey, isProviderEnabled, saveAsProfile, loadProfile, listProfiles, deleteProfile, getActiveProfileName, setActiveProfile, _emptyProfileSettings } from '../lib/config.js'
 
 const require = createRequire(import.meta.url)
 const readline = require('readline')
@@ -717,7 +720,7 @@ const ALT_HOME   = '\x1b[H'
 // 📖 This allows easy addition of new model sources beyond NVIDIA NIM
 
 const PING_TIMEOUT  = 15_000   // 📖 15s per attempt before abort - slow models get more time
-const PING_INTERVAL = 3_000    // 📖 Ping all models every 3 seconds in continuous mode
+const PING_INTERVAL = 60_000   // 📖 60s between pings — avoids provider rate-limit bans
 
 const FPS          = 12
 const COL_MODEL    = 22
@@ -760,6 +763,7 @@ const spinCell = (f, o = 0) => chalk.dim.yellow(FRAMES[(f + o) % FRAMES.length].
 // 📖 from the main table and from each other.
 const SETTINGS_OVERLAY_BG = chalk.bgRgb(14, 20, 30)
 const HELP_OVERLAY_BG = chalk.bgRgb(24, 16, 32)
+const RECOMMEND_OVERLAY_BG = chalk.bgRgb(10, 25, 15)  // 📖 Green tint for Smart Recommend
 const OVERLAY_PANEL_WIDTH = 116
 
 // 📖 Strip ANSI color/control sequences to estimate visible text width before padding.
@@ -852,7 +856,7 @@ function sliceOverlayLines(lines, offset, terminalRows) {
 // 📖 Keep these constants in sync with renderTable() fixed shell lines.
 // 📖 If this drifts, model rows overflow and can push the title row out of view.
 const TABLE_HEADER_LINES = 4 // 📖 title, spacer, column headers, separator
-const TABLE_FOOTER_LINES = 6 // 📖 spacer, hints, spacer, credit+contributors, discord, spacer
+const TABLE_FOOTER_LINES = 7 // 📖 spacer, hints line 1, hints line 2, spacer, credit+contributors, discord, spacer
 const TABLE_FIXED_LINES = TABLE_HEADER_LINES + TABLE_FOOTER_LINES
 
 // 📖 Computes the visible slice of model rows that fits in the terminal.
@@ -871,18 +875,27 @@ function calculateViewport(terminalRows, scrollOffset, totalModels) {
   return { startIdx: scrollOffset, endIdx, hasAbove, hasBelow }
 }
 
-// 📖 Favorites are always pinned at the top and keep insertion order.
-// 📖 Non-favorites still use the active sort column/direction.
+// 📖 Recommended models are pinned above favorites, favorites above non-favorites.
+// 📖 Recommended: sorted by recommendation score (highest first).
+// 📖 Favorites: keep insertion order (favoriteRank).
+// 📖 Non-favorites: active sort column/direction.
 function sortResultsWithPinnedFavorites(results, sortColumn, sortDirection) {
+  const recommendedRows = results
+    .filter((r) => r.isRecommended && !r.isFavorite)
+    .sort((a, b) => (b.recommendScore || 0) - (a.recommendScore || 0))
   const favoriteRows = results
-    .filter((r) => r.isFavorite)
+    .filter((r) => r.isFavorite && !r.isRecommended)
     .sort((a, b) => a.favoriteRank - b.favoriteRank)
-  const nonFavoriteRows = sortResults(results.filter((r) => !r.isFavorite), sortColumn, sortDirection)
-  return [...favoriteRows, ...nonFavoriteRows]
+  // 📖 Models that are both recommended AND favorite — show in recommended section
+  const bothRows = results
+    .filter((r) => r.isRecommended && r.isFavorite)
+    .sort((a, b) => (b.recommendScore || 0) - (a.recommendScore || 0))
+  const nonSpecialRows = sortResults(results.filter((r) => !r.isFavorite && !r.isRecommended), sortColumn, sortDirection)
+  return [...bothRows, ...recommendedRows, ...favoriteRows, ...nonSpecialRows]
 }
 
 // 📖 renderTable: mode param controls footer hint text (opencode vs openclaw)
-function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, originFilterMode = 0) {
+function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, originFilterMode = 0, activeProfile = null, profileSaveMode = false, profileSaveBuffer = '') {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
 
@@ -934,6 +947,12 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
     }
   }
 
+  // 📖 Profile badge — shown when a named profile is active (Shift+P to cycle, Shift+S to save)
+  let profileBadge = ''
+  if (activeProfile) {
+    profileBadge = chalk.bold.rgb(200, 150, 255)(` [📋 ${activeProfile}]`)
+  }
+
   // 📖 Column widths (generous spacing with margins)
   const W_RANK = 6
   const W_TIER = 6
@@ -952,7 +971,7 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
   const sorted = sortResultsWithPinnedFavorites(visibleResults, sortColumn, sortDirection)
 
   const lines = [
-    `  ${chalk.bold('⚡ Free Coding Models')} ${chalk.dim('v' + LOCAL_VERSION)}${modeBadge}${modeHint}${tierBadge}${originBadge}   ` +
+    `  ${chalk.bold('⚡ Free Coding Models')} ${chalk.dim('v' + LOCAL_VERSION)}${modeBadge}${modeHint}${tierBadge}${originBadge}${profileBadge}   ` +
       chalk.greenBright(`✅ ${up}`) + chalk.dim(' up  ') +
       chalk.yellow(`⏳ ${timeout}`) + chalk.dim(' timeout  ') +
       chalk.red(`❌ ${down}`) + chalk.dim(' down  ') +
@@ -1054,8 +1073,8 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
     const providerName = sources[r.providerKey]?.name ?? r.providerKey ?? 'NIM'
     const source = chalk.green(providerName.padEnd(W_SOURCE))
     // 📖 Favorites: always reserve 2 display columns at the start of Model column.
-    // 📖 ⭐ (2 cols) for favorites, '  ' (2 spaces) for non-favorites — keeps alignment stable.
-    const favoritePrefix = r.isFavorite ? '⭐' : '  '
+    // 📖 🎯 (2 cols) for recommended, ⭐ (2 cols) for favorites, '  ' (2 spaces) for non-favorites — keeps alignment stable.
+    const favoritePrefix = r.isRecommended ? '🎯' : r.isFavorite ? '⭐' : '  '
     const prefixDisplayWidth = 2
     const nameWidth = Math.max(0, W_MODEL - prefixDisplayWidth)
     const name = favoritePrefix + r.label.slice(0, nameWidth).padEnd(nameWidth)
@@ -1241,6 +1260,9 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
 
     if (isCursor) {
       lines.push(chalk.bgRgb(50, 0, 60)(row))
+    } else if (r.isRecommended) {
+      // 📖 Medium green background for recommended models (distinguishable from favorites)
+      lines.push(chalk.bgRgb(15, 40, 15)(row))
     } else if (r.isFavorite) {
       lines.push(chalk.bgRgb(35, 20, 0)(row))
     } else {
@@ -1252,7 +1274,12 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
     lines.push(chalk.dim(`  ... ${sorted.length - vp.endIdx} more below ...`))
   }
 
-  lines.push('')
+  // 📖 Profile save inline prompt — shown when Shift+S is pressed, replaces spacer line
+  if (profileSaveMode) {
+    lines.push(chalk.bgRgb(40, 20, 60)(`  📋 Save profile as: ${chalk.cyanBright(profileSaveBuffer + '▏')}  ${chalk.dim('Enter save  •  Esc cancel')}`))
+  } else {
+    lines.push('')
+  }
   const intervalSec = Math.round(pingInterval / 1000)
 
   // 📖 Footer hints adapt based on active mode
@@ -1261,7 +1288,10 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
     : mode === 'opencode-desktop'
       ? chalk.rgb(0, 200, 255)('Enter→OpenDesktop')
       : chalk.rgb(0, 200, 255)('Enter→OpenCode')
-  lines.push(chalk.dim(`  ↑↓ Navigate  •  `) + actionHint + chalk.dim(`  •  F Favorite  •  R/Y/O/M/L/A/S/C/H/V/B/U Sort  •  T Tier  •  N Origin  •  W↓/X↑ (${intervalSec}s)  •  `) + chalk.rgb(255, 100, 50).bold('Z Mode') + chalk.dim(`  •  `) + chalk.yellow('P') + chalk.dim(` Settings  •  `) + chalk.rgb(0, 255, 80).bold('K Help'))
+  // 📖 Line 1: core navigation + sorting shortcuts
+  lines.push(chalk.dim(`  ↑↓ Navigate  •  `) + actionHint + chalk.dim(`  •  `) + chalk.yellow('F') + chalk.dim(` Favorite  •  R/Y/O/M/L/A/S/C/H/V/B/U Sort  •  `) + chalk.yellow('T') + chalk.dim(` Tier  •  `) + chalk.yellow('N') + chalk.dim(` Origin  •  W↓/X↑ (${intervalSec}s)  •  `) + chalk.rgb(255, 100, 50).bold('Z') + chalk.dim(` Mode  •  `) + chalk.yellow('P') + chalk.dim(` Settings  •  `) + chalk.rgb(0, 255, 80).bold('K') + chalk.dim(` Help`))
+  // 📖 Line 2: profiles, recommend, and extended hints — gives visibility to less-obvious features
+  lines.push(chalk.dim(`  `) + chalk.rgb(200, 150, 255).bold('⇧P') + chalk.dim(` Cycle profile  •  `) + chalk.rgb(200, 150, 255).bold('⇧S') + chalk.dim(` Save profile  •  `) + chalk.rgb(0, 200, 180).bold('Q') + chalk.dim(` Smart Recommend  •  `) + chalk.yellow('E') + chalk.dim(`/`) + chalk.yellow('D') + chalk.dim(` Tier ↑↓  •  `) + chalk.yellow('Esc') + chalk.dim(` Close overlay  •  Ctrl+C Exit`))
   lines.push('')
   lines.push(
     chalk.rgb(255, 150, 200)('  Made with 💖 & ☕ by \x1b]8;;https://github.com/vava-nessa\x1b\\vava-nessa\x1b]8;;\x1b\\') +
@@ -1271,6 +1301,7 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
     chalk.dim('  •  ') +
     '🤝 ' +
     chalk.rgb(255, 165, 0)('\x1b]8;;https://github.com/vava-nessa/free-coding-models/graphs/contributors\x1b\\Contributors\x1b]8;;\x1b\\') +
+    chalk.dim(' (vava-nessa • erwinh22 • whit3rabbit • skylaweber)') +
     chalk.dim('  •  ') +
     '💬 ' +
     chalk.rgb(200, 150, 255)('\x1b]8;;https://discord.gg/5MbTnDC3Md\x1b\\Discord\x1b]8;;\x1b\\') +
@@ -1306,6 +1337,9 @@ function resolveCloudflareUrl(url) {
 }
 
 function buildPingRequest(apiKey, modelId, providerKey, url) {
+  // 📖 ZAI models are stored as "zai/glm-..." in sources.js but the API expects just "glm-..."
+  const apiModelId = providerKey === 'zai' ? modelId.replace(/^zai\//, '') : modelId
+
   if (providerKey === 'replicate') {
     // 📖 Replicate uses /v1/predictions with a different payload than OpenAI chat-completions.
     const replicateHeaders = { 'Content-Type': 'application/json', Prefer: 'wait=4' }
@@ -1324,7 +1358,7 @@ function buildPingRequest(apiKey, modelId, providerKey, url) {
     return {
       url: resolveCloudflareUrl(url),
       headers,
-      body: { model: modelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
+      body: { model: apiModelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
     }
   }
 
@@ -1339,7 +1373,7 @@ function buildPingRequest(apiKey, modelId, providerKey, url) {
   return {
     url,
     headers,
-    body: { model: modelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
+    body: { model: apiModelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
   }
 }
 
@@ -1387,6 +1421,8 @@ const OPENCODE_MODEL_MAP = {
 }
 
 function getOpenCodeModelId(providerKey, modelId) {
+  // 📖 ZAI models stored as "zai/glm-..." but OpenCode expects just "glm-..."
+  if (providerKey === 'zai') return modelId.replace(/^zai\//, '')
   return OPENCODE_MODEL_MAP[providerKey]?.[modelId] || modelId
 }
 
@@ -1409,6 +1445,7 @@ const ENV_VAR_NAMES = {
   together:   'TOGETHER_API_KEY',
   cloudflare: 'CLOUDFLARE_API_TOKEN',
   perplexity: 'PERPLEXITY_API_KEY',
+  zai:        'ZAI_API_KEY',
 }
 
 // 📖 Provider metadata used by the setup wizard and Settings details panel.
@@ -1533,17 +1570,25 @@ const PROVIDER_METADATA = {
     signupHint: 'Generate API key (billing may be required)',
     rateLimits: 'Tiered limits by spend (default ~50 RPM)',
   },
+  zai: {
+    label: 'ZAI (z.ai)',
+    color: chalk.rgb(0, 150, 255),
+    signupUrl: 'https://z.ai',
+    signupHint: 'Sign up and generate an API key',
+    rateLimits: 'Free tier (generous quota)',
+  },
+  iflow: {
+    label: 'iFlow',
+    color: chalk.rgb(100, 200, 255),
+    signupUrl: 'https://platform.iflow.cn',
+    signupHint: 'Register → Personal Information → Generate API Key (7-day expiry)',
+    rateLimits: 'Free for individuals (no request limits)',
+  },
 }
 
-// 📖 OpenCode config location varies by platform
-// 📖 Windows: %APPDATA%\opencode\opencode.json (or sometimes ~/.config/opencode)
-// 📖 macOS/Linux: ~/.config/opencode/opencode.json
-const OPENCODE_CONFIG = isWindows 
-  ? join(homedir(), 'AppData', 'Roaming', 'opencode', 'opencode.json')
-  : join(homedir(), '.config', 'opencode', 'opencode.json')
-
-// 📖 Fallback to .config on Windows if AppData doesn't exist
-const OPENCODE_CONFIG_FALLBACK = join(homedir(), '.config', 'opencode', 'opencode.json')
+// 📖 OpenCode config location: ~/.config/opencode/opencode.json on ALL platforms.
+// 📖 OpenCode uses xdg-basedir which resolves to %USERPROFILE%\.config on Windows.
+const OPENCODE_CONFIG = join(homedir(), '.config', 'opencode', 'opencode.json')
 const OPENCODE_PORT_RANGE_START = 4096
 const OPENCODE_PORT_RANGE_END = 5096
 
@@ -1585,8 +1630,6 @@ async function resolveOpenCodeTmuxPort() {
 }
 
 function getOpenCodeConfigPath() {
-  if (existsSync(OPENCODE_CONFIG)) return OPENCODE_CONFIG
-  if (isWindows && existsSync(OPENCODE_CONFIG_FALLBACK)) return OPENCODE_CONFIG_FALLBACK
   return OPENCODE_CONFIG
 }
 
@@ -1629,14 +1672,68 @@ function checkNvidiaNimConfig() {
 // 📖 Resolves the actual API key from config/env and passes it as an env var
 // 📖 to the child process so OpenCode's {env:GROQ_API_KEY} references work
 // 📖 even when the key is only in ~/.free-coding-models.json (not in shell env).
-async function spawnOpenCode(args, providerKey, fcmConfig) {
+// 📖 createZaiProxy: Localhost reverse proxy that bridges ZAI's non-standard API paths
+// 📖 to OpenCode's expected /v1/* OpenAI-compatible format.
+// 📖 OpenCode's local provider calls GET /v1/models for discovery and POST /v1/chat/completions
+// 📖 for inference. ZAI's API lives at /api/coding/paas/v4/* instead — this proxy rewrites.
+// 📖 Returns { server, port } — caller must server.close() when done.
+async function createZaiProxy(apiKey) {
+  const server = createHttpServer((req, res) => {
+    let targetPath = req.url
+    // 📖 Rewrite /v1/* → /api/coding/paas/v4/*
+    if (targetPath.startsWith('/v1/')) {
+      targetPath = '/api/coding/paas/v4/' + targetPath.slice(4)
+    } else if (targetPath.startsWith('/v1')) {
+      targetPath = '/api/coding/paas/v4' + targetPath.slice(3)
+    } else {
+      // 📖 Non /v1 paths (e.g. /api/v0/ health checks) — reject
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    const headers = { ...req.headers, host: 'api.z.ai' }
+    if (apiKey) headers.authorization = `Bearer ${apiKey}`
+    // 📖 Remove transfer-encoding to avoid chunked encoding issues with https.request
+    delete headers['transfer-encoding']
+    const proxyReq = httpsRequest({
+      hostname: 'api.z.ai',
+      port: 443,
+      path: targetPath,
+      method: req.method,
+      headers,
+    }, (proxyRes) => {
+      res.writeHead(proxyRes.statusCode, proxyRes.headers)
+      proxyRes.pipe(res)
+    })
+    proxyReq.on('error', () => { res.writeHead(502); res.end() })
+    req.pipe(proxyReq)
+  })
+  await new Promise(r => server.listen(0, '127.0.0.1', r))
+  return { server, port: server.address().port }
+}
+
+async function spawnOpenCode(args, providerKey, fcmConfig, existingZaiProxy = null) {
   const envVarName = ENV_VAR_NAMES[providerKey]
   const resolvedKey = getApiKey(fcmConfig, providerKey)
   const childEnv = { ...process.env }
+  // 📖 Suppress MaxListenersExceededWarning from @modelcontextprotocol/sdk
+  // 📖 when 7+ MCP servers cause drain listener count to exceed default 10
+  childEnv.NODE_NO_WARNINGS = '1'
   const finalArgs = [...args]
   const hasExplicitPortArg = finalArgs.includes('--port')
   if (envVarName && resolvedKey) childEnv[envVarName] = resolvedKey
 
+  // 📖 ZAI proxy: OpenCode's Go binary doesn't know about ZAI as a provider.
+  // 📖 We spin up a localhost proxy that rewrites /v1/* → /api/coding/paas/v4/*
+  // 📖 and register ZAI as a custom openai-compatible provider in opencode.json.
+  // 📖 If startOpenCode already started the proxy, reuse it (existingZaiProxy).
+  let zaiProxy = existingZaiProxy
+  if (providerKey === 'zai' && resolvedKey && !zaiProxy) {
+    const { server, port } = await createZaiProxy(resolvedKey)
+    zaiProxy = server
+    console.log(chalk.dim(`  🔀 ZAI proxy listening on port ${port} (rewrites /v1/* → ZAI API)`))
+  }
+
   // 📖 In tmux, OpenCode sub-agents need a listening port to open extra panes.
   // 📖 We auto-pick one if the user did not provide --port explicitly.
   if (process.env.TMUX && !hasExplicitPortArg) {
@@ -1664,8 +1761,22 @@ async function spawnOpenCode(args, providerKey, fcmConfig) {
   })
 
   return new Promise((resolve, reject) => {
-    child.on('exit', resolve)
+    child.on('exit', (code) => {
+      if (zaiProxy) zaiProxy.close()
+      // 📖 ZAI cleanup: remove the ephemeral proxy provider from opencode.json
+      // 📖 so a stale baseURL doesn't cause "Model zai/… is not valid" on next launch
+      if (providerKey === 'zai') {
+        try {
+          const cfg = loadOpenCodeConfig()
+          if (cfg.provider?.zai) delete cfg.provider.zai
+          if (typeof cfg.model === 'string' && cfg.model.startsWith('zai/')) delete cfg.model
+          saveOpenCodeConfig(cfg)
+        } catch { /* best-effort cleanup */ }
+      }
+      resolve(code)
+    })
     child.on('error', (err) => {
+      if (zaiProxy) zaiProxy.close()
       if (err.code === 'ENOENT') {
         console.error(chalk.red('\n  X Could not find "opencode" -- is it installed and in your PATH?'))
         console.error(chalk.dim('    Install: npm i -g opencode   or see https://opencode.ai'))
@@ -1775,8 +1886,72 @@ After installation, you can use: opencode --model ${modelRef}`
       return
     }
 
-    // 📖 Groq: built-in OpenCode provider -- needs provider block with apiKey in opencode.json.
-    // 📖 Cerebras: NOT built-in -- needs @ai-sdk/openai-compatible + baseURL, like NVIDIA.
+    // 📖 ZAI: OpenCode's Go binary has no built-in ZAI provider.
+    // 📖 We start a localhost proxy that rewrites /v1/* → /api/coding/paas/v4/*
+    // 📖 and register ZAI as a custom openai-compatible provider pointing to the proxy.
+    // 📖 This gives OpenCode a standard provider/model format (zai/glm-5) it understands.
+    if (providerKey === 'zai') {
+      const resolvedKey = getApiKey(fcmConfig, providerKey)
+      if (!resolvedKey) {
+        console.log(chalk.yellow('  ⚠ ZAI API key not found. Set ZAI_API_KEY environment variable.'))
+        console.log()
+        return
+      }
+
+      // 📖 Start proxy FIRST to get the port for config
+      const { server: zaiProxyServer, port: zaiProxyPort } = await createZaiProxy(resolvedKey)
+      console.log(chalk.dim(`  🔀 ZAI proxy listening on port ${zaiProxyPort} (rewrites /v1/* → ZAI API)`))
+
+      console.log(chalk.green(`  🚀 Setting ${chalk.bold(model.label)} as default…`))
+      console.log(chalk.dim(`  Model: ${modelRef}`))
+      console.log()
+
+      const config = loadOpenCodeConfig()
+      const backupPath = `${getOpenCodeConfigPath()}.backup-${Date.now()}`
+
+      if (existsSync(getOpenCodeConfigPath())) {
+        copyFileSync(getOpenCodeConfigPath(), backupPath)
+        console.log(chalk.dim(`  💾 Backup: ${backupPath}`))
+      }
+
+      // 📖 Register ZAI as an openai-compatible provider pointing to our localhost proxy
+      // 📖 apiKey is required by @ai-sdk/openai-compatible SDK — the proxy handles real auth internally
+      if (!config.provider) config.provider = {}
+      config.provider.zai = {
+        npm: '@ai-sdk/openai-compatible',
+        name: 'ZAI',
+        options: {
+          baseURL: `http://127.0.0.1:${zaiProxyPort}/v1`,
+          apiKey: 'zai-proxy',
+        },
+        models: {}
+      }
+      config.provider.zai.models[ocModelId] = { name: model.label }
+      config.model = modelRef
+
+      saveOpenCodeConfig(config)
+
+      const savedConfig = loadOpenCodeConfig()
+      console.log(chalk.dim(`  📝 Config saved to: ${getOpenCodeConfigPath()}`))
+      console.log(chalk.dim(`  📝 Default model in config: ${savedConfig.model || 'NOT SET'}`))
+      console.log()
+
+      if (savedConfig.model === config.model) {
+        console.log(chalk.green(`  ✓ Default model set to: ${modelRef}`))
+      } else {
+        console.log(chalk.yellow(`  ⚠ Config might not have been saved correctly`))
+      }
+      console.log()
+      console.log(chalk.dim('  Starting OpenCode…'))
+      console.log()
+
+      // 📖 Pass existing proxy to spawnOpenCode so it doesn't start a second one
+      await spawnOpenCode(['--model', modelRef], providerKey, fcmConfig, zaiProxyServer)
+      return
+    }
+
+    // 📖 Groq: built-in OpenCode provider — needs provider block with apiKey in opencode.json.
+    // 📖 Cerebras: NOT built-in — needs @ai-sdk/openai-compatible + baseURL, like NVIDIA.
     // 📖 Both need the model registered in provider.<key>.models so OpenCode can find it.
     console.log(chalk.green(`  🚀 Setting ${chalk.bold(model.label)} as default…`))
     console.log(chalk.dim(`  Model: ${modelRef}`))
@@ -2092,6 +2267,16 @@ ${isWindows ? 'set NVIDIA_API_KEY=your_key_here' : 'export NVIDIA_API_KEY=your_k
       return
     }
 
+    // 📖 ZAI: Desktop mode can't use the localhost proxy (Desktop is a standalone app).
+    // 📖 Direct the user to use OpenCode CLI mode instead, which supports ZAI via proxy.
+    if (providerKey === 'zai') {
+      console.log(chalk.yellow('  ⚠ ZAI models are supported in OpenCode CLI mode only (not Desktop).'))
+      console.log(chalk.dim('    Reason: ZAI requires a localhost proxy that only works with the CLI spawn.'))
+      console.log(chalk.dim('    Use OpenCode CLI mode (default) to launch ZAI models.'))
+      console.log()
+      return
+    }
+
     // 📖 Groq: built-in OpenCode provider — needs provider block with apiKey in opencode.json.
     // 📖 Cerebras: NOT built-in — needs @ai-sdk/openai-compatible + baseURL, like NVIDIA.
     // 📖 Both need the model registered in provider.<key>.models so OpenCode can find it.
@@ -2454,6 +2639,16 @@ async function main() {
   ensureTelemetryConfig(config)
   ensureFavoritesConfig(config)
 
+  // 📖 If --profile <name> was passed, load that profile into the live config
+  if (cliArgs.profileName) {
+    const profileSettings = loadProfile(config, cliArgs.profileName)
+    if (!profileSettings) {
+      console.error(chalk.red(`  Unknown profile "${cliArgs.profileName}". Available: ${listProfiles(config).join(', ') || '(none)'}`))
+      process.exit(1)
+    }
+    saveConfig(config)
+  }
+
   // 📖 Check if any provider has a key — if not, run the first-time setup wizard
   const hasAnyKey = Object.keys(sources).some(pk => !!getApiKey(config, pk))
 
@@ -2597,6 +2792,22 @@ async function main() {
     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
+    // 📖 Smart Recommend overlay state (Q key opens it)
+    recommendOpen: false,         // 📖 Whether the recommend overlay is active
+    recommendPhase: 'questionnaire', // 📖 'questionnaire'|'analyzing'|'results' — current phase
+    recommendCursor: 0,           // 📖 Selected question option (0-based index within current question)
+    recommendQuestion: 0,         // 📖 Which question we're on (0=task, 1=priority, 2=context)
+    recommendAnswers: { taskType: null, priority: null, contextBudget: null }, // 📖 User's answers
+    recommendProgress: 0,         // 📖 Analysis progress percentage (0–100)
+    recommendResults: [],         // 📖 Top N recommendations from getTopRecommendations()
+    recommendScrollOffset: 0,     // 📖 Vertical scroll offset for Recommend overlay viewport
+    recommendAnalysisTimer: null, // 📖 setInterval handle for the 10s analysis phase
+    recommendPingTimer: null,     // 📖 setInterval handle for 2 pings/sec during analysis
+    recommendedKeys: new Set(),   // 📖 Set of "providerKey/modelId" for recommended models (shown in main table)
+    // 📖 Config Profiles state
+    activeProfile: getActiveProfileName(config), // 📖 Currently loaded profile name (or null)
+    profileSaveMode: false,       // 📖 Whether the inline "Save profile" name input is active
+    profileSaveBuffer: '',        // 📖 Typed characters for the profile name being saved
   }
 
   // 📖 Re-clamp viewport on terminal resize
@@ -2762,11 +2973,39 @@ async function main() {
       lines.push(chalk.red(`      ${state.settingsUpdateError}`))
     }
 
+    // 📖 Profiles section — list saved profiles with active indicator + delete support
+    const savedProfiles = listProfiles(state.config)
+    const profileStartIdx = updateRowIdx + 1
+    const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : updateRowIdx
+
+    lines.push('')
+    lines.push(`  ${chalk.bold('📋 Profiles')}  ${chalk.dim(savedProfiles.length > 0 ? `(${savedProfiles.length} saved)` : '(none — press Shift+S in main view to save)')}`)
+    lines.push(`  ${chalk.dim('  ' + '─'.repeat(112))}`)
+    lines.push('')
+
+    if (savedProfiles.length === 0) {
+      lines.push(chalk.dim('    No saved profiles. Press Shift+S in the main table to save your current settings as a profile.'))
+    } else {
+      for (let i = 0; i < savedProfiles.length; i++) {
+        const pName = savedProfiles[i]
+        const rowIdx = profileStartIdx + i
+        const isCursor = state.settingsCursor === rowIdx
+        const isActive = state.activeProfile === pName
+        const activeBadge = isActive ? chalk.greenBright(' ✅ active') : ''
+        const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+        const profileLabel = chalk.rgb(200, 150, 255).bold(pName.padEnd(30))
+        const deleteHint = isCursor ? chalk.dim('  Enter→Load  •  Backspace→Delete') : ''
+        const row = `${bullet}${profileLabel}${activeBadge}${deleteHint}`
+        cursorLineByRow[rowIdx] = lines.length
+        lines.push(isCursor ? chalk.bgRgb(40, 20, 60)(row) : row)
+      }
+    }
+
     lines.push('')
     if (state.settingsEditMode) {
       lines.push(chalk.dim('  Type API key  •  Enter Save  •  Esc Cancel'))
     } else {
-      lines.push(chalk.dim('  ↑↓ Navigate  •  Enter Edit key / Toggle analytics / Check-or-Install update  •  Space Toggle enabled  •  T Test key  •  U Check updates  •  Esc Close'))
+      lines.push(chalk.dim('  ↑↓ Navigate  •  Enter Edit key / Toggle / Load profile  •  Space Toggle  •  T Test key  •  U Updates  •  ⌫ Delete profile  •  Esc Close'))
     }
     lines.push('')
 
@@ -2800,7 +3039,7 @@ async function main() {
     lines.push(`  ${chalk.cyan('Rank')}        SWE-bench rank (1 = best coding score)  ${chalk.dim('Sort:')} ${chalk.yellow('R')}`)
     lines.push(`              ${chalk.dim('Quick glance at which model is objectively the best coder right now.')}`)
     lines.push('')
-    lines.push(`  ${chalk.cyan('Tier')}        S+ / S / A+ / A / A- / B+ / B / C based on SWE-bench score  ${chalk.dim('Sort:')} ${chalk.yellow('Y')}`)
+    lines.push(`  ${chalk.cyan('Tier')}        S+ / S / A+ / A / A- / B+ / B / C based on SWE-bench score  ${chalk.dim('Sort:')} ${chalk.yellow('Y')}  ${chalk.dim('Cycle:')} ${chalk.yellow('T')}`)
     lines.push(`              ${chalk.dim('Skip the noise — S/S+ models solve real GitHub issues, C models are for light tasks.')}`)
     lines.push('')
     lines.push(`  ${chalk.cyan('SWE%')}        SWE-bench score — coding ability benchmark (color-coded)  ${chalk.dim('Sort:')} ${chalk.yellow('S')}`)
@@ -2812,7 +3051,7 @@ async function main() {
     lines.push(`  ${chalk.cyan('Model')}       Model name (⭐ = favorited, pinned at top)  ${chalk.dim('Sort:')} ${chalk.yellow('M')}  ${chalk.dim('Favorite:')} ${chalk.yellow('F')}`)
     lines.push(`              ${chalk.dim('Star the ones you like — they stay pinned at the top across restarts.')}`)
     lines.push('')
-    lines.push(`  ${chalk.cyan('Origin')}      Provider source (NIM, Groq, Cerebras, etc.)  ${chalk.dim('Sort:')} ${chalk.yellow('O')}  ${chalk.dim('Filter:')} ${chalk.yellow('N')}`)
+    lines.push(`  ${chalk.cyan('Origin')}      Provider source (NIM, Groq, Cerebras, etc.)  ${chalk.dim('Sort:')} ${chalk.yellow('O')}  ${chalk.dim('Cycle:')} ${chalk.yellow('N')}`)
     lines.push(`              ${chalk.dim('Same model on different providers can have very different speed and uptime.')}`)
     lines.push('')
     lines.push(`  ${chalk.cyan('Latest')}      Most recent ping response time (ms)  ${chalk.dim('Sort:')} ${chalk.yellow('L')}`)
@@ -2839,16 +3078,17 @@ async function main() {
     lines.push(`  ${chalk.yellow('↑↓')}           Navigate rows`)
     lines.push(`  ${chalk.yellow('Enter')}        Select model and launch`)
     lines.push('')
-    lines.push(`  ${chalk.bold('Filters')}`)
-    lines.push(`  ${chalk.yellow('T')}  Cycle tier filter  ${chalk.dim('(All → S+ → S → A+ → A → A- → B+ → B → C → All)')}`)
-    lines.push(`  ${chalk.yellow('N')}  Cycle origin filter  ${chalk.dim('(All → NIM → Groq → Cerebras → ... each provider → All)')}`)
-    lines.push('')
     lines.push(`  ${chalk.bold('Controls')}`)
     lines.push(`  ${chalk.yellow('W')}  Decrease ping interval (faster)`)
     lines.push(`  ${chalk.yellow('X')}  Increase ping interval (slower)`)
     lines.push(`  ${chalk.yellow('Z')}  Cycle launch mode  ${chalk.dim('(OpenCode CLI → OpenCode Desktop → OpenClaw)')}`)
     lines.push(`  ${chalk.yellow('F')}  Toggle favorite on selected row  ${chalk.dim('(⭐ pinned at top, persisted)')}`)
+    lines.push(`  ${chalk.yellow('Q')}  Smart Recommend  ${chalk.dim('(🎯 find the best model for your task — questionnaire + live analysis)')}`)
     lines.push(`  ${chalk.yellow('P')}  Open settings  ${chalk.dim('(manage API keys, provider toggles, analytics, manual update)')}`)
+    lines.push(`  ${chalk.yellow('Shift+P')}  Cycle config profile  ${chalk.dim('(switch between saved profiles live)')}`)
+    lines.push(`  ${chalk.yellow('Shift+S')}  Save current config as a named profile  ${chalk.dim('(inline prompt — type name + Enter)')}`)
+    lines.push(`             ${chalk.dim('Profiles store: favorites, sort, tier filter, ping interval, API keys.')}`)
+    lines.push(`             ${chalk.dim('Use --profile <name> to load a profile on startup.')}`)
     lines.push(`  ${chalk.yellow('K')} / ${chalk.yellow('Esc')}  Show/hide this help`)
     lines.push(`  ${chalk.yellow('Ctrl+C')}  Exit`)
     lines.push('')
@@ -2871,6 +3111,8 @@ async function main() {
     lines.push(`  ${chalk.cyan('free-coding-models --fiable')}             ${chalk.dim('10s reliability analysis')}`)
     lines.push(`  ${chalk.cyan('free-coding-models --tier S|A|B|C')}       ${chalk.dim('Filter by tier letter')}`)
     lines.push(`  ${chalk.cyan('free-coding-models --no-telemetry')}       ${chalk.dim('Disable telemetry for this run')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --recommend')}          ${chalk.dim('Auto-open Smart Recommend on start')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --profile <name>')}     ${chalk.dim('Load a saved config profile')}`)
     lines.push(`  ${chalk.dim('Flags can be combined: --openclaw --tier S')}`)
     lines.push('')
     // 📖 Help overlay can be longer than viewport, so keep a dedicated scroll offset.
@@ -2881,6 +3123,211 @@ async function main() {
     return cleared.join('\n')
   }
 
+  // ─── Smart Recommend overlay renderer ─────────────────────────────────────
+  // 📖 renderRecommend: Draw the Smart Recommend overlay with 3 phases:
+  //   1. 'questionnaire' — ask 3 questions (task type, priority, context budget)
+  //   2. 'analyzing' — loading screen with progress bar (10s, 2 pings/sec)
+  //   3. 'results' — show Top 3 recommendations with scores
+  function renderRecommend() {
+    const EL = '\x1b[K'
+    const lines = []
+
+    lines.push('')
+    lines.push(`  ${chalk.bold('🎯 Smart Recommend')}  ${chalk.dim('— find the best model for your task')}`)
+    lines.push('')
+
+    if (state.recommendPhase === 'questionnaire') {
+      // 📖 Question definitions — each has a title, options array, and answer key
+      const questions = [
+        {
+          title: 'What are you working on?',
+          options: Object.entries(TASK_TYPES).map(([key, val]) => ({ key, label: val.label })),
+          answerKey: 'taskType',
+        },
+        {
+          title: 'What matters most?',
+          options: Object.entries(PRIORITY_TYPES).map(([key, val]) => ({ key, label: val.label })),
+          answerKey: 'priority',
+        },
+        {
+          title: 'How big is your context?',
+          options: Object.entries(CONTEXT_BUDGETS).map(([key, val]) => ({ key, label: val.label })),
+          answerKey: 'contextBudget',
+        },
+      ]
+
+      const q = questions[state.recommendQuestion]
+      const qNum = state.recommendQuestion + 1
+      const qTotal = questions.length
+
+      // 📖 Progress breadcrumbs showing answered questions
+      let breadcrumbs = ''
+      for (let i = 0; i < questions.length; i++) {
+        const answered = state.recommendAnswers[questions[i].answerKey]
+        if (i < state.recommendQuestion && answered) {
+          const answeredLabel = questions[i].options.find(o => o.key === answered)?.label || answered
+          breadcrumbs += chalk.greenBright(`  ✓ ${questions[i].title} ${chalk.bold(answeredLabel)}`) + '\n'
+        }
+      }
+      if (breadcrumbs) {
+        lines.push(breadcrumbs.trimEnd())
+        lines.push('')
+      }
+
+      lines.push(`  ${chalk.bold(`Question ${qNum}/${qTotal}:`)} ${chalk.cyan(q.title)}`)
+      lines.push('')
+
+      for (let i = 0; i < q.options.length; i++) {
+        const opt = q.options[i]
+        const isCursor = i === state.recommendCursor
+        const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+        const label = isCursor ? chalk.bold.white(opt.label) : chalk.white(opt.label)
+        lines.push(`${bullet}${label}`)
+      }
+
+      lines.push('')
+      lines.push(chalk.dim('  ↑↓ navigate  •  Enter select  •  Esc cancel'))
+
+    } else if (state.recommendPhase === 'analyzing') {
+      // 📖 Loading screen with progress bar
+      const pct = Math.min(100, Math.round(state.recommendProgress))
+      const barWidth = 40
+      const filled = Math.round(barWidth * pct / 100)
+      const empty = barWidth - filled
+      const bar = chalk.greenBright('█'.repeat(filled)) + chalk.dim('░'.repeat(empty))
+
+      lines.push(`  ${chalk.bold('Analyzing models...')}`)
+      lines.push('')
+      lines.push(`  ${bar}  ${chalk.bold(String(pct) + '%')}`)
+      lines.push('')
+
+      // 📖 Show what we're doing
+      const taskLabel = TASK_TYPES[state.recommendAnswers.taskType]?.label || '—'
+      const prioLabel = PRIORITY_TYPES[state.recommendAnswers.priority]?.label || '—'
+      const ctxLabel = CONTEXT_BUDGETS[state.recommendAnswers.contextBudget]?.label || '—'
+      lines.push(chalk.dim(`  Task: ${taskLabel}  •  Priority: ${prioLabel}  •  Context: ${ctxLabel}`))
+      lines.push('')
+
+      // 📖 Spinning indicator
+      const spinIdx = state.frame % FRAMES.length
+      lines.push(`  ${chalk.yellow(FRAMES[spinIdx])} Pinging models at 2 pings/sec to gather fresh latency data...`)
+      lines.push('')
+      lines.push(chalk.dim('  Esc to cancel'))
+
+    } else if (state.recommendPhase === 'results') {
+      // 📖 Show Top 3 results with detailed info
+      const taskLabel = TASK_TYPES[state.recommendAnswers.taskType]?.label || '—'
+      const prioLabel = PRIORITY_TYPES[state.recommendAnswers.priority]?.label || '—'
+      const ctxLabel = CONTEXT_BUDGETS[state.recommendAnswers.contextBudget]?.label || '—'
+      lines.push(chalk.dim(`  Task: ${taskLabel}  •  Priority: ${prioLabel}  •  Context: ${ctxLabel}`))
+      lines.push('')
+
+      if (state.recommendResults.length === 0) {
+        lines.push(`  ${chalk.yellow('No models could be scored. Try different criteria or wait for more pings.')}`)
+      } else {
+        lines.push(`  ${chalk.bold('Top Recommendations:')}`)
+        lines.push('')
+
+        for (let i = 0; i < state.recommendResults.length; i++) {
+          const rec = state.recommendResults[i]
+          const r = rec.result
+          const medal = i === 0 ? '🥇' : i === 1 ? '🥈' : '🥉'
+          const providerName = sources[r.providerKey]?.name ?? r.providerKey
+          const tierFn = TIER_COLOR[r.tier] ?? (t => chalk.white(t))
+          const avg = getAvg(r)
+          const avgStr = avg === Infinity ? '—' : Math.round(avg) + 'ms'
+          const sweStr = r.sweScore ?? '—'
+          const ctxStr = r.ctx ?? '—'
+          const stability = getStabilityScore(r)
+          const stabStr = stability === -1 ? '—' : String(stability)
+
+          const isCursor = i === state.recommendCursor
+          const highlight = isCursor ? chalk.bgRgb(20, 50, 25) : (s => s)
+
+          lines.push(highlight(`  ${medal} ${chalk.bold('#' + (i + 1))}  ${chalk.bold.white(r.label)}  ${chalk.dim('(' + providerName + ')')}`))
+          lines.push(highlight(`       Score: ${chalk.bold.greenBright(String(rec.score) + '/100')}  │  Tier: ${tierFn(r.tier)}  │  SWE: ${chalk.cyan(sweStr)}  │  Avg: ${chalk.yellow(avgStr)}  │  CTX: ${chalk.cyan(ctxStr)}  │  Stability: ${chalk.cyan(stabStr)}`))
+          lines.push('')
+        }
+      }
+
+      lines.push('')
+      lines.push(`  ${chalk.dim('These models are now')} ${chalk.greenBright('highlighted')} ${chalk.dim('and')} 🎯 ${chalk.dim('pinned in the main table.')}`)
+      lines.push('')
+      lines.push(chalk.dim('  ↑↓ navigate  •  Enter select & close  •  Esc close  •  Q new search'))
+    }
+
+    lines.push('')
+    const { visible, offset } = sliceOverlayLines(lines, state.recommendScrollOffset, state.terminalRows)
+    state.recommendScrollOffset = offset
+    const tintedLines = tintOverlayLines(visible, RECOMMEND_OVERLAY_BG)
+    const cleared2 = tintedLines.map(l => l + EL)
+    return cleared2.join('\n')
+  }
+
+  // ─── Smart Recommend: analysis phase controller ────────────────────────────
+  // 📖 startRecommendAnalysis: begins the 10-second analysis phase.
+  // 📖 Pings a random subset of visible models at 2 pings/sec while advancing progress.
+  // 📖 After 10 seconds, computes recommendations and transitions to results phase.
+  function startRecommendAnalysis() {
+    state.recommendPhase = 'analyzing'
+    state.recommendProgress = 0
+    state.recommendResults = []
+
+    const startTime = Date.now()
+    const ANALYSIS_DURATION = 10_000 // 📖 10 seconds
+    const PING_RATE = 500            // 📖 2 pings per second (every 500ms)
+
+    // 📖 Progress updater — runs every 200ms to update the progress bar
+    state.recommendAnalysisTimer = setInterval(() => {
+      const elapsed = Date.now() - startTime
+      state.recommendProgress = Math.min(100, (elapsed / ANALYSIS_DURATION) * 100)
+
+      if (elapsed >= ANALYSIS_DURATION) {
+        // 📖 Analysis complete — compute recommendations
+        clearInterval(state.recommendAnalysisTimer)
+        clearInterval(state.recommendPingTimer)
+        state.recommendAnalysisTimer = null
+        state.recommendPingTimer = null
+
+        const recs = getTopRecommendations(
+          state.results,
+          state.recommendAnswers.taskType,
+          state.recommendAnswers.priority,
+          state.recommendAnswers.contextBudget,
+          3
+        )
+        state.recommendResults = recs
+        state.recommendPhase = 'results'
+        state.recommendCursor = 0
+
+        // 📖 Mark recommended models so the main table can highlight them
+        state.recommendedKeys = new Set(recs.map(rec => toFavoriteKey(rec.result.providerKey, rec.result.modelId)))
+        // 📖 Tag each result object so sortResultsWithPinnedFavorites can pin them
+        state.results.forEach(r => {
+          const key = toFavoriteKey(r.providerKey, r.modelId)
+          const rec = recs.find(rec => toFavoriteKey(rec.result.providerKey, rec.result.modelId) === key)
+          r.isRecommended = !!rec
+          r.recommendScore = rec ? rec.score : 0
+        })
+      }
+    }, 200)
+
+    // 📖 Targeted pinging — ping random visible models at 2/sec for fresh data
+    state.recommendPingTimer = setInterval(() => {
+      const visible = state.results.filter(r => !r.hidden && r.status !== 'noauth')
+      if (visible.length === 0) return
+      // 📖 Pick a random model to ping — spreads load across all models over 10s
+      const target = visible[Math.floor(Math.random() * visible.length)]
+      pingModel(target).catch(() => {})
+    }, PING_RATE)
+  }
+
+  // 📖 stopRecommendAnalysis: cleanup timers if user cancels during analysis
+  function stopRecommendAnalysis() {
+    if (state.recommendAnalysisTimer) { clearInterval(state.recommendAnalysisTimer); state.recommendAnalysisTimer = null }
+    if (state.recommendPingTimer) { clearInterval(state.recommendPingTimer); state.recommendPingTimer = null }
+  }
+
   // ─── Settings key test helper ───────────────────────────────────────────────
   // 📖 Fires a single ping to the selected provider to verify the API key works.
   async function testProviderKey(providerKey) {
@@ -2952,6 +3399,45 @@ async function main() {
   const onKeyPress = async (str, key) => {
     if (!key) return
 
+    // 📖 Profile save mode: intercept ALL keys while inline name input is active.
+    // 📖 Enter → save, Esc → cancel, Backspace → delete char, printable → append to buffer.
+    if (state.profileSaveMode) {
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+      if (key.name === 'escape') {
+        // 📖 Cancel profile save — discard typed name
+        state.profileSaveMode = false
+        state.profileSaveBuffer = ''
+        return
+      }
+      if (key.name === 'return') {
+        // 📖 Confirm profile save — persist current TUI settings under typed name
+        const name = state.profileSaveBuffer.trim()
+        if (name.length > 0) {
+          saveAsProfile(state.config, name, {
+            tierFilter: TIER_CYCLE[tierFilterMode],
+            sortColumn: state.sortColumn,
+            sortAsc: state.sortDirection === 'asc',
+            pingInterval: state.pingInterval,
+          })
+          setActiveProfile(state.config, name)
+          state.activeProfile = name
+          saveConfig(state.config)
+        }
+        state.profileSaveMode = false
+        state.profileSaveBuffer = ''
+        return
+      }
+      if (key.name === 'backspace') {
+        state.profileSaveBuffer = state.profileSaveBuffer.slice(0, -1)
+        return
+      }
+      // 📖 Append printable characters (str is the raw character typed)
+      if (str && str.length === 1 && !key.ctrl && !key.meta) {
+        state.profileSaveBuffer += str
+      }
+      return
+    }
+
     // 📖 Help overlay: full keyboard navigation + key swallowing while overlay is open.
     if (state.helpVisible) {
       const pageStep = Math.max(1, (state.terminalRows || 1) - 2)
@@ -2969,11 +3455,122 @@ async function main() {
       return
     }
 
+    // 📖 Smart Recommend overlay: full keyboard handling while overlay is open.
+    if (state.recommendOpen) {
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+
+      if (state.recommendPhase === 'questionnaire') {
+        const questions = [
+          { options: Object.keys(TASK_TYPES), answerKey: 'taskType' },
+          { options: Object.keys(PRIORITY_TYPES), answerKey: 'priority' },
+          { options: Object.keys(CONTEXT_BUDGETS), answerKey: 'contextBudget' },
+        ]
+        const q = questions[state.recommendQuestion]
+
+        if (key.name === 'escape') {
+          // 📖 Cancel recommend — close overlay
+          state.recommendOpen = false
+          state.recommendPhase = 'questionnaire'
+          state.recommendQuestion = 0
+          state.recommendCursor = 0
+          state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
+          return
+        }
+        if (key.name === 'up') {
+          state.recommendCursor = state.recommendCursor > 0 ? state.recommendCursor - 1 : q.options.length - 1
+          return
+        }
+        if (key.name === 'down') {
+          state.recommendCursor = state.recommendCursor < q.options.length - 1 ? state.recommendCursor + 1 : 0
+          return
+        }
+        if (key.name === 'return') {
+          // 📖 Record answer and advance to next question or start analysis
+          state.recommendAnswers[q.answerKey] = q.options[state.recommendCursor]
+          if (state.recommendQuestion < questions.length - 1) {
+            state.recommendQuestion++
+            state.recommendCursor = 0
+          } else {
+            // 📖 All questions answered — start analysis phase
+            startRecommendAnalysis()
+          }
+          return
+        }
+        return // 📖 Swallow all other keys
+      }
+
+      if (state.recommendPhase === 'analyzing') {
+        if (key.name === 'escape') {
+          // 📖 Cancel analysis — stop timers, return to questionnaire
+          stopRecommendAnalysis()
+          state.recommendOpen = false
+          state.recommendPhase = 'questionnaire'
+          state.recommendQuestion = 0
+          state.recommendCursor = 0
+          state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
+          return
+        }
+        return // 📖 Swallow all keys during analysis (except Esc and Ctrl+C)
+      }
+
+      if (state.recommendPhase === 'results') {
+        if (key.name === 'escape') {
+          // 📖 Close results — recommendations stay highlighted in main table
+          state.recommendOpen = false
+          return
+        }
+        if (key.name === 'q') {
+          // 📖 Start a new search
+          state.recommendPhase = 'questionnaire'
+          state.recommendQuestion = 0
+          state.recommendCursor = 0
+          state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
+          state.recommendResults = []
+          state.recommendScrollOffset = 0
+          return
+        }
+        if (key.name === 'up') {
+          const count = state.recommendResults.length
+          if (count === 0) return
+          state.recommendCursor = state.recommendCursor > 0 ? state.recommendCursor - 1 : count - 1
+          return
+        }
+        if (key.name === 'down') {
+          const count = state.recommendResults.length
+          if (count === 0) return
+          state.recommendCursor = state.recommendCursor < count - 1 ? state.recommendCursor + 1 : 0
+          return
+        }
+        if (key.name === 'return') {
+          // 📖 Select the highlighted recommendation — close overlay, jump cursor to it
+          const rec = state.recommendResults[state.recommendCursor]
+          if (rec) {
+            const recKey = toFavoriteKey(rec.result.providerKey, rec.result.modelId)
+            state.recommendOpen = false
+            // 📖 Jump to the recommended model in the main table
+            const idx = state.visibleSorted.findIndex(r => toFavoriteKey(r.providerKey, r.modelId) === recKey)
+            if (idx >= 0) {
+              state.cursor = idx
+              adjustScrollOffset(state)
+            }
+          }
+          return
+        }
+        return // 📖 Swallow all other keys
+      }
+
+      return // 📖 Catch-all swallow
+    }
+
     // ─── Settings overlay keyboard handling ───────────────────────────────────
     if (state.settingsOpen) {
       const providerKeys = Object.keys(sources)
       const telemetryRowIdx = providerKeys.length
       const updateRowIdx = providerKeys.length + 1
+      // 📖 Profile rows start after update row — one row per saved profile
+      const savedProfiles = listProfiles(state.config)
+      const profileStartIdx = updateRowIdx + 1
+      const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : updateRowIdx
 
       // 📖 Edit mode: capture typed characters for the API key
       if (state.settingsEditMode) {
@@ -3040,7 +3637,7 @@ async function main() {
         return
       }
 
-      if (key.name === 'down' && state.settingsCursor < updateRowIdx) {
+      if (key.name === 'down' && state.settingsCursor < maxRowIdx) {
         state.settingsCursor++
         return
       }
@@ -3053,7 +3650,7 @@ async function main() {
 
       if (key.name === 'pagedown') {
         const pageStep = Math.max(1, (state.terminalRows || 1) - 2)
-        state.settingsCursor = Math.min(updateRowIdx, state.settingsCursor + pageStep)
+        state.settingsCursor = Math.min(maxRowIdx, state.settingsCursor + pageStep)
         return
       }
 
@@ -3063,7 +3660,7 @@ async function main() {
       }
 
       if (key.name === 'end') {
-        state.settingsCursor = updateRowIdx
+        state.settingsCursor = maxRowIdx
         return
       }
 
@@ -3084,6 +3681,33 @@ async function main() {
           return
         }
 
+        // 📖 Profile row: Enter → load the selected profile (apply its settings live)
+        if (state.settingsCursor >= profileStartIdx && savedProfiles.length > 0) {
+          const profileIdx = state.settingsCursor - profileStartIdx
+          const profileName = savedProfiles[profileIdx]
+          if (profileName) {
+            const settings = loadProfile(state.config, profileName)
+            if (settings) {
+              state.sortColumn = settings.sortColumn || 'avg'
+              state.sortDirection = settings.sortAsc ? 'asc' : 'desc'
+              state.pingInterval = settings.pingInterval || PING_INTERVAL
+              if (settings.tierFilter) {
+                const tierIdx = TIER_CYCLE.indexOf(settings.tierFilter)
+                if (tierIdx >= 0) tierFilterMode = tierIdx
+              } else {
+                tierFilterMode = 0
+              }
+              state.activeProfile = profileName
+              syncFavoriteFlags(state.results, state.config)
+              applyTierFilter()
+              const visible = state.results.filter(r => !r.hidden)
+              state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+              saveConfig(state.config)
+            }
+          }
+          return
+        }
+
         // 📖 Enter edit mode for the selected provider's key
         const pk = providerKeys[state.settingsCursor]
         state.settingsEditBuffer = state.config.apiKeys?.[pk] ?? ''
@@ -3100,6 +3724,8 @@ async function main() {
           return
         }
         if (state.settingsCursor === updateRowIdx) return
+        // 📖 Profile rows don't respond to Space
+        if (state.settingsCursor >= profileStartIdx) return
 
         // 📖 Toggle enabled/disabled for selected provider
         const pk = providerKeys[state.settingsCursor]
@@ -3112,6 +3738,8 @@ async function main() {
 
       if (key.name === 't') {
         if (state.settingsCursor === telemetryRowIdx || state.settingsCursor === updateRowIdx) return
+        // 📖 Profile rows don't respond to T (test key)
+        if (state.settingsCursor >= profileStartIdx) return
 
         // 📖 Test the selected provider's key (fires a real ping)
         const pk = providerKeys[state.settingsCursor]
@@ -3124,12 +3752,34 @@ async function main() {
         return
       }
 
+      // 📖 Backspace on a profile row → delete that profile
+      if (key.name === 'backspace' && state.settingsCursor >= profileStartIdx && savedProfiles.length > 0) {
+        const profileIdx = state.settingsCursor - profileStartIdx
+        const profileName = savedProfiles[profileIdx]
+        if (profileName) {
+          deleteProfile(state.config, profileName)
+          // 📖 If the deleted profile was active, clear active state
+          if (state.activeProfile === profileName) {
+            setActiveProfile(state.config, null)
+            state.activeProfile = null
+          }
+          saveConfig(state.config)
+          // 📖 Re-clamp cursor after deletion (profile list just got shorter)
+          const newProfiles = listProfiles(state.config)
+          const newMaxRowIdx = newProfiles.length > 0 ? profileStartIdx + newProfiles.length - 1 : updateRowIdx
+          if (state.settingsCursor > newMaxRowIdx) {
+            state.settingsCursor = Math.max(0, newMaxRowIdx)
+          }
+        }
+        return
+      }
+
       if (key.ctrl && key.name === 'c') { exit(0); return }
       return // 📖 Swallow all other keys while settings is open
     }
 
     // 📖 P key: open settings screen
-    if (key.name === 'p') {
+    if (key.name === 'p' && !key.shift) {
       state.settingsOpen = true
       state.settingsCursor = 0
       state.settingsEditMode = false
@@ -3138,6 +3788,77 @@ async function main() {
       return
     }
 
+    // 📖 Q key: open Smart Recommend overlay
+    if (key.name === 'q') {
+      state.recommendOpen = true
+      state.recommendPhase = 'questionnaire'
+      state.recommendQuestion = 0
+      state.recommendCursor = 0
+      state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
+      state.recommendResults = []
+      state.recommendScrollOffset = 0
+      return
+    }
+
+    // 📖 Shift+P: cycle through profiles (or show profile picker)
+    if (key.name === 'p' && key.shift) {
+      const profiles = listProfiles(state.config)
+      if (profiles.length === 0) {
+        // 📖 No profiles saved — save current config as 'default' profile
+        saveAsProfile(state.config, 'default', {
+          tierFilter: TIER_CYCLE[tierFilterMode],
+          sortColumn: state.sortColumn,
+          sortAsc: state.sortDirection === 'asc',
+          pingInterval: state.pingInterval,
+        })
+        setActiveProfile(state.config, 'default')
+        state.activeProfile = 'default'
+        saveConfig(state.config)
+      } else {
+        // 📖 Cycle to next profile (or back to null = raw config)
+        const currentIdx = state.activeProfile ? profiles.indexOf(state.activeProfile) : -1
+        const nextIdx = (currentIdx + 1) % (profiles.length + 1) // +1 for "no profile"
+        if (nextIdx === profiles.length) {
+          // 📖 Back to raw config (no profile)
+          setActiveProfile(state.config, null)
+          state.activeProfile = null
+          saveConfig(state.config)
+        } else {
+          const nextProfile = profiles[nextIdx]
+          const settings = loadProfile(state.config, nextProfile)
+          if (settings) {
+            // 📖 Apply profile's TUI settings to live state
+            state.sortColumn = settings.sortColumn || 'avg'
+            state.sortDirection = settings.sortAsc ? 'asc' : 'desc'
+            state.pingInterval = settings.pingInterval || PING_INTERVAL
+            if (settings.tierFilter) {
+              const tierIdx = TIER_CYCLE.indexOf(settings.tierFilter)
+              if (tierIdx >= 0) tierFilterMode = tierIdx
+            } else {
+              tierFilterMode = 0
+            }
+            state.activeProfile = nextProfile
+            // 📖 Rebuild favorites from profile data
+            syncFavoriteFlags(state.results, 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
+            saveConfig(state.config)
+          }
+        }
+      }
+      return
+    }
+
+    // 📖 Shift+S: enter profile save mode — inline text prompt for typing a profile name
+    if (key.name === 's' && key.shift) {
+      state.profileSaveMode = true
+      state.profileSaveBuffer = ''
+      return
+    }
+
     // 📖 Sorting keys: R=rank, Y=tier, O=origin, M=model, L=latest ping, A=avg ping, S=SWE-bench, C=context, H=health, V=verdict, B=stability, U=uptime
     // 📖 T is reserved for tier filter cycling — tier sort moved to Y
     // 📖 N is now reserved for origin filter cycling
@@ -3146,7 +3867,7 @@ async function main() {
       'l': 'ping', 'a': 'avg', 's': 'swe', 'c': 'ctx', 'h': 'condition', 'v': 'verdict', 'b': 'stability', 'u': 'uptime'
     }
 
-    if (sortKeys[key.name] && !key.ctrl) {
+    if (sortKeys[key.name] && !key.ctrl && !key.shift) {
       const col = sortKeys[key.name]
       // 📖 Toggle direction if same column, otherwise reset to asc
       if (state.sortColumn === col) {
@@ -3322,19 +4043,21 @@ async function main() {
 
   process.stdin.on('keypress', onKeyPress)
 
-  // 📖 Animation loop: render settings overlay OR main table based on state
+  // 📖 Animation loop: render settings overlay, recommend overlay, help overlay, OR main table
   const ticker = setInterval(() => {
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen) {
+    if (!state.settingsOpen && !state.recommendOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
     const content = state.settingsOpen
       ? renderSettings()
-      : state.helpVisible
-        ? renderHelp()
-        : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, tierFilterMode, state.scrollOffset, state.terminalRows, originFilterMode)
+      : state.recommendOpen
+        ? renderRecommend()
+        : state.helpVisible
+          ? renderHelp()
+          : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, tierFilterMode, state.scrollOffset, state.terminalRows, originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer)
     process.stdout.write(ALT_HOME + content)
   }, Math.round(1000 / FPS))
 
@@ -3342,7 +4065,19 @@ async function main() {
   const initialVisible = state.results.filter(r => !r.hidden)
   state.visibleSorted = sortResultsWithPinnedFavorites(initialVisible, state.sortColumn, state.sortDirection)
 
-  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, tierFilterMode, state.scrollOffset, state.terminalRows, originFilterMode))
+  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, tierFilterMode, state.scrollOffset, state.terminalRows, originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer))
+
+  // 📖 If --recommend was passed, auto-open the Smart Recommend overlay on start
+  if (cliArgs.recommendMode) {
+    state.recommendOpen = true
+    state.recommendPhase = 'questionnaire'
+    state.recommendCursor = 0
+    state.recommendQuestion = 0
+    state.recommendAnswers = { taskType: null, priority: null, contextBudget: null }
+    state.recommendProgress = 0
+    state.recommendResults = []
+    state.recommendScrollOffset = 0
+  }
 
   // ── Continuous ping loop — ping all models every N seconds forever ──────────