free-coding-models 0.1.63 → 0.1.65

package/bin/free-coding-models.js

@@ -10,7 +10,7 @@
  *   During benchmarking, users can navigate with arrow keys and press Enter to act on the selected model.
  *
  *   🎯 Key features:
- *   - Parallel pings across all models with animated real-time updates (3 providers: NIM, Groq, Cerebras)
+ *   - Parallel pings across all models with animated real-time updates (multi-provider)
  *   - Continuous monitoring with 2-second ping intervals (never stops)
  *   - Rolling averages calculated from ALL successful pings since start
  *   - Best-per-tier highlighting with medals (🥇🥈🥉)
@@ -19,8 +19,9 @@
  *   - Startup mode menu (OpenCode CLI vs OpenCode Desktop vs OpenClaw) when no flag is given
  *   - Automatic config detection and model setup for both tools
  *   - JSON config stored in ~/.free-coding-models.json (auto-migrates from old plain-text)
- *   - Multi-provider support via sources.js (NIM, Groq, Cerebras — extensible)
- *   - Settings screen (P key) to manage API keys per provider, enable/disable, test keys
+ *   - Multi-provider support via sources.js (NIM/Groq/Cerebras/OpenRouter/Hugging Face/Replicate/DeepInfra/... — extensible)
+ *   - Settings screen (P key) to manage API keys, provider toggles, analytics, and manual updates
+ *   - Favorites system: toggle with F, pin rows to top, persist between sessions
  *   - Uptime percentage tracking (successful pings / total pings)
  *   - Sortable columns (R/Y/O/M/L/A/S/N/H/V/U keys)
  *   - Tier filtering via T key (cycles S+→S→A+→A→A-→B+→B→C→All)
@@ -32,15 +33,17 @@
  *   - `getTelemetryTerminal`: Infer terminal family (Terminal.app, iTerm2, kitty, etc.)
  *   - `isTelemetryDebugEnabled` / `telemetryDebug`: Optional runtime telemetry diagnostics via env
  *   - `sendUsageTelemetry`: Fire-and-forget anonymous app-start event
- *   - `promptApiKey`: Interactive wizard for first-time NVIDIA API key setup
+ *   - `ensureFavoritesConfig` / `toggleFavoriteModel`: Persist and toggle pinned favorites
+ *   - `promptApiKey`: Interactive wizard for first-time multi-provider API key setup
  *   - `promptModeSelection`: Startup menu to choose OpenCode vs OpenClaw
- *   - `ping`: Perform HTTP request to NIM endpoint with timeout handling
+ *   - `buildPingRequest` / `ping`: Build provider-specific probe requests and measure latency
  *   - `renderTable`: Generate ASCII table with colored latency indicators and status emojis
  *   - `getAvg`: Calculate average latency from all successful pings
  *   - `getVerdict`: Determine verdict string based on average latency (Overloaded for 429)
  *   - `getUptime`: Calculate uptime percentage from ping history
  *   - `sortResults`: Sort models by various columns
  *   - `checkNvidiaNimConfig`: Check if NVIDIA NIM provider is configured in OpenCode
+ *   - `isTcpPortAvailable` / `resolveOpenCodeTmuxPort`: Pick a safe OpenCode port when running in tmux
  *   - `startOpenCode`: Launch OpenCode CLI with selected model (configures if needed)
  *   - `startOpenCodeDesktop`: Set model in shared config & open OpenCode Desktop app
  *   - `loadOpenClawConfig` / `saveOpenClawConfig`: Manage ~/.openclaw/openclaw.json
@@ -57,8 +60,8 @@
  *   ⚙️ 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
- *   - Models loaded from sources.js — 53 models across NIM, Groq, Cerebras
+ *   - 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, etc.
+ *   - 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
@@ -86,6 +89,7 @@ import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from
 import { randomUUID } from 'crypto'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
+import { createServer } from 'net'
 import { MODELS, sources } from '../sources.js'
 import { patchOpenClawModelsJson } from '../patch-openclaw-models.js'
 import { getAvg, getVerdict, getUptime, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP } from '../lib/utils.js'
@@ -157,6 +161,53 @@ function ensureTelemetryConfig(config) {
   }
 }
 
+// 📖 Ensure favorites config shape exists and remains clean.
+// 📖 Stored format: ["providerKey/modelId", ...] in insertion order.
+function ensureFavoritesConfig(config) {
+  if (!Array.isArray(config.favorites)) config.favorites = []
+  const seen = new Set()
+  config.favorites = config.favorites.filter((entry) => {
+    if (typeof entry !== 'string' || entry.trim().length === 0) return false
+    if (seen.has(entry)) return false
+    seen.add(entry)
+    return true
+  })
+}
+
+// 📖 Build deterministic key used to persist one favorite model row.
+function toFavoriteKey(providerKey, modelId) {
+  return `${providerKey}/${modelId}`
+}
+
+// 📖 Sync per-row favorite metadata from config (used by renderer and sorter).
+function syncFavoriteFlags(results, config) {
+  ensureFavoritesConfig(config)
+  const favoriteRankMap = new Map(config.favorites.map((entry, index) => [entry, index]))
+  for (const row of results) {
+    const favoriteKey = toFavoriteKey(row.providerKey, row.modelId)
+    const rank = favoriteRankMap.get(favoriteKey)
+    row.favoriteKey = favoriteKey
+    row.isFavorite = rank !== undefined
+    row.favoriteRank = rank !== undefined ? rank : Number.MAX_SAFE_INTEGER
+  }
+}
+
+// 📖 Toggle favorite state and persist immediately.
+// 📖 Returns true when row is now favorite, false when removed.
+function toggleFavoriteModel(config, providerKey, modelId) {
+  ensureFavoritesConfig(config)
+  const favoriteKey = toFavoriteKey(providerKey, modelId)
+  const existingIndex = config.favorites.indexOf(favoriteKey)
+  if (existingIndex >= 0) {
+    config.favorites.splice(existingIndex, 1)
+    saveConfig(config)
+    return false
+  }
+  config.favorites.push(favoriteKey)
+  saveConfig(config)
+  return true
+}
+
 // 📖 Create or reuse a persistent anonymous distinct_id for PostHog.
 // 📖 Stored locally in config so one user is stable over time without personal data.
 function getTelemetryDistinctId(config) {
@@ -414,14 +465,25 @@ async function sendUsageTelemetry(config, cliArgs, payload) {
   }
 }
 
-async function checkForUpdate() {
+// 📖 checkForUpdateDetailed: Fetch npm latest version with explicit error details.
+// 📖 Used by settings manual-check flow to display meaningful status in the UI.
+async function checkForUpdateDetailed() {
   try {
     const res = await fetch('https://registry.npmjs.org/free-coding-models/latest', { signal: AbortSignal.timeout(5000) })
-    if (!res.ok) return null
+    if (!res.ok) return { latestVersion: null, error: `HTTP ${res.status}` }
     const data = await res.json()
-    if (data.version && data.version !== LOCAL_VERSION) return data.version
-  } catch {}
-  return null
+    if (data.version && data.version !== LOCAL_VERSION) return { latestVersion: data.version, error: null }
+    return { latestVersion: null, error: null }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    return { latestVersion: null, error: message }
+  }
+}
+
+// 📖 checkForUpdate: Backward-compatible wrapper for startup update prompt.
+async function checkForUpdate() {
+  const { latestVersion } = await checkForUpdateDetailed()
+  return latestVersion
 }
 
 function runUpdate(latestVersion) {
@@ -486,7 +548,7 @@ function runUpdate(latestVersion) {
 
 // ─── First-run wizard ─────────────────────────────────────────────────────────
 // 📖 Shown when NO provider has a key configured yet.
-// 📖 Steps through all 3 providers sequentially — each is optional (Enter to skip).
+// 📖 Steps through all configured providers sequentially — each is optional (Enter to skip).
 // 📖 At least one key must be entered to proceed. Keys saved to ~/.free-coding-models.json.
 // 📖 Returns the nvidia key (or null) for backward-compat with the rest of main().
 async function promptApiKey(config) {
@@ -495,81 +557,17 @@ async function promptApiKey(config) {
   console.log(chalk.dim('  Enter keys for any provider you want to use. Press Enter to skip one.'))
   console.log()
 
-  // 📖 Provider definitions: label, key field, url for getting the key
-  const providers = [
-    {
-      key: 'nvidia',
-      label: 'NVIDIA NIM',
-      color: chalk.rgb(118, 185, 0),
-      url: 'https://build.nvidia.com',
-      hint: 'Profile → API Keys → Generate',
-      prefix: 'nvapi-',
-    },
-    {
-      key: 'groq',
-      label: 'Groq',
-      color: chalk.rgb(249, 103, 20),
-      url: 'https://console.groq.com/keys',
-      hint: 'API Keys → Create API Key',
-      prefix: 'gsk_',
-    },
-    {
-      key: 'cerebras',
-      label: 'Cerebras',
-      color: chalk.rgb(0, 180, 255),
-      url: 'https://cloud.cerebras.ai',
-      hint: 'API Keys → Create',
-      prefix: 'csk_ / cauth_',
-    },
-    {
-      key: 'sambanova',
-      label: 'SambaNova',
-      color: chalk.rgb(255, 165, 0),
-      url: 'https://cloud.sambanova.ai/apis',
-      hint: 'API Keys → Create ($5 free trial, 3 months)',
-      prefix: 'sn-',
-    },
-    {
-      key: 'openrouter',
-      label: 'OpenRouter',
-      color: chalk.rgb(120, 80, 255),
-      url: 'https://openrouter.ai/settings/keys',
-      hint: 'API Keys → Create key (50 free req/day, shared quota)',
-      prefix: 'sk-or-',
-    },
-    {
-      key: 'codestral',
-      label: 'Mistral Codestral',
-      color: chalk.rgb(255, 100, 100),
-      url: 'https://codestral.mistral.ai',
-      hint: 'API Keys → Create key (30 req/min, 2000/day — phone required)',
-      prefix: 'csk-',
-    },
-    {
-      key: 'hyperbolic',
-      label: 'Hyperbolic',
-      color: chalk.rgb(0, 200, 150),
-      url: 'https://app.hyperbolic.ai/settings',
-      hint: 'Settings → API Keys ($1 free trial)',
-      prefix: 'eyJ',
-    },
-    {
-      key: 'scaleway',
-      label: 'Scaleway',
-      color: chalk.rgb(130, 0, 250),
-      url: 'https://console.scaleway.com/iam/api-keys',
-      hint: 'IAM → API Keys (1M free tokens)',
-      prefix: 'scw-',
-    },
-    {
-      key: 'googleai',
-      label: 'Google AI Studio',
-      color: chalk.rgb(66, 133, 244),
-      url: 'https://aistudio.google.com/apikey',
-      hint: 'Get API key (free Gemma models, 14.4K req/day)',
-      prefix: 'AIza',
-    },
-  ]
+  // 📖 Build providers from sources to keep setup in sync with actual supported providers.
+  const providers = Object.keys(sources).map((key) => {
+    const meta = PROVIDER_METADATA[key] || {}
+    return {
+      key,
+      label: meta.label || sources[key]?.name || key,
+      color: meta.color || chalk.white,
+      url: meta.signupUrl || 'https://example.com',
+      hint: meta.signupHint || 'Create API key',
+    }
+  })
 
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
 
@@ -785,6 +783,16 @@ 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.
+function sortResultsWithPinnedFavorites(results, sortColumn, sortDirection) {
+  const favoriteRows = results
+    .filter((r) => r.isFavorite)
+    .sort((a, b) => a.favoriteRank - b.favoriteRank)
+  const nonFavoriteRows = sortResults(results.filter((r) => !r.isFavorite), sortColumn, sortDirection)
+  return [...favoriteRows, ...nonFavoriteRows]
+}
+
 // 📖 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) {
   // 📖 Filter out hidden models for display
@@ -852,7 +860,7 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
   const W_UPTIME = 6
 
   // 📖 Sort models using the shared helper
-  const sorted = sortResults(visibleResults, sortColumn, sortDirection)
+  const sorted = sortResultsWithPinnedFavorites(visibleResults, sortColumn, sortDirection)
 
   const lines = [
     `  ${chalk.bold('⚡ Free Coding Models')} ${chalk.dim('v' + LOCAL_VERSION)}${modeBadge}${modeHint}${tierBadge}${originBadge}   ` +
@@ -944,7 +952,10 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
     // 📖 Show provider name from sources map (NIM / Groq / Cerebras)
     const providerName = sources[r.providerKey]?.name ?? r.providerKey ?? 'NIM'
     const source = chalk.green(providerName.padEnd(W_SOURCE))
-    const name = r.label.slice(0, W_MODEL).padEnd(W_MODEL)
+    // 📖 Favorites get a leading star in Model column.
+    const favoritePrefix = r.isFavorite ? '⭐ ' : ''
+    const nameWidth = Math.max(0, W_MODEL - favoritePrefix.length)
+    const name = favoritePrefix + r.label.slice(0, nameWidth).padEnd(nameWidth)
     const sweScore = r.sweScore ?? '—'
     const sweCell = sweScore !== '—' && parseFloat(sweScore) >= 50 
       ? chalk.greenBright(sweScore.padEnd(W_SWE))
@@ -1074,8 +1085,12 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
     // 📖 Build row with double space between columns (order: Rank, Tier, SWE%, CTX, Model, Origin, Latest Ping, Avg Ping, Health, Verdict, Up%)
     const row = '  ' + num + '  ' + tier + '  ' + sweCell + '  ' + ctxCell + '  ' + name + '  ' + source + '  ' + pingCell + '  ' + avgCell + '  ' + status + '  ' + speedCell + '  ' + uptimeCell
 
-    if (isCursor) {
+    if (isCursor && r.isFavorite) {
+      lines.push(chalk.bgRgb(120, 60, 0)(row))
+    } else if (isCursor) {
       lines.push(chalk.bgRgb(139, 0, 139)(row))
+    } else if (r.isFavorite) {
+      lines.push(chalk.bgRgb(90, 45, 0)(row))
     } else {
       lines.push(row)
     }
@@ -1094,7 +1109,7 @@ 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(`  •  R/Y/O/M/L/A/S/C/H/V/U Sort  •  T Tier  •  N Origin  •  W↓/X↑ (${intervalSec}s)  •  Z Mode  •  `) + chalk.yellow('P') + chalk.dim(` Settings  •  `) + chalk.bgGreenBright.black.bold(' K Help ') + chalk.dim(`  •  Ctrl+C Exit`))
+  lines.push(chalk.dim(`  ↑↓ Navigate  •  `) + actionHint + chalk.dim(`  •  F Favorite  •  R/Y/O/M/L/A/S/C/H/V/U Sort  •  T Tier  •  N Origin  •  W↓/X↑ (${intervalSec}s)  •  Z Mode  •  `) + chalk.yellow('P') + chalk.dim(` Settings  •  `) + chalk.bgGreenBright.black.bold(' K Help ') + chalk.dim(`  •  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\\') +
@@ -1121,23 +1136,50 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
 // ─── HTTP ping ────────────────────────────────────────────────────────────────
 
 // 📖 ping: Send a single chat completion request to measure model availability and latency.
-// 📖 url param is the provider's endpoint URL — differs per provider (NIM, Groq, Cerebras).
+// 📖 providerKey and url determine provider-specific request format.
 // 📖 apiKey can be null — in that case no Authorization header is sent.
 // 📖 A 401 response still tells us the server is UP and gives us real latency.
-async function ping(apiKey, modelId, url) {
+function buildPingRequest(apiKey, modelId, providerKey, url) {
+  if (providerKey === 'replicate') {
+    // 📖 Replicate uses /v1/predictions with a different payload than OpenAI chat-completions.
+    const replicateHeaders = { 'Content-Type': 'application/json', Prefer: 'wait=4' }
+    if (apiKey) replicateHeaders.Authorization = `Token ${apiKey}`
+    return {
+      url,
+      headers: replicateHeaders,
+      body: { version: modelId, input: { prompt: 'hi' } },
+    }
+  }
+
+  const headers = { 'Content-Type': 'application/json' }
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`
+  if (providerKey === 'openrouter') {
+    // 📖 OpenRouter recommends optional app identification headers.
+    headers['HTTP-Referer'] = 'https://github.com/vava-nessa/free-coding-models'
+    headers['X-Title'] = 'free-coding-models'
+  }
+
+  return {
+    url,
+    headers,
+    body: { model: modelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
+  }
+}
+
+async function ping(apiKey, modelId, providerKey, url) {
   const ctrl  = new AbortController()
   const timer = setTimeout(() => ctrl.abort(), PING_TIMEOUT)
   const t0    = performance.now()
   try {
-    // 📖 Only attach Authorization header when a key is available
-    const headers = { 'Content-Type': 'application/json' }
-    if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`
-    const resp = await fetch(url, {
+    const req = buildPingRequest(apiKey, modelId, providerKey, url)
+    const resp = await fetch(req.url, {
       method: 'POST', signal: ctrl.signal,
-      headers,
-      body: JSON.stringify({ model: modelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 }),
+      headers: req.headers,
+      body: JSON.stringify(req.body),
     })
-    return { code: String(resp.status), ms: Math.round(performance.now() - t0) }
+    // 📖 Normalize all HTTP 2xx statuses to "200" so existing verdict/avg logic still works.
+    const code = resp.status >= 200 && resp.status < 300 ? '200' : String(resp.status)
+    return { code, ms: Math.round(performance.now() - t0) }
   } catch (err) {
     const isTimeout = err.name === 'AbortError'
     return {
@@ -1178,12 +1220,112 @@ const ENV_VAR_NAMES = {
   cerebras:   'CEREBRAS_API_KEY',
   sambanova:  'SAMBANOVA_API_KEY',
   openrouter: 'OPENROUTER_API_KEY',
+  huggingface:'HUGGINGFACE_API_KEY',
+  replicate:  'REPLICATE_API_TOKEN',
+  deepinfra:  'DEEPINFRA_API_KEY',
+  fireworks:  'FIREWORKS_API_KEY',
   codestral:  'CODESTRAL_API_KEY',
   hyperbolic: 'HYPERBOLIC_API_KEY',
   scaleway:   'SCALEWAY_API_KEY',
   googleai:   'GOOGLE_API_KEY',
 }
 
+// 📖 Provider metadata used by the setup wizard and Settings details panel.
+// 📖 Keeps signup links + rate limits centralized so UI stays consistent.
+const PROVIDER_METADATA = {
+  nvidia: {
+    label: 'NVIDIA NIM',
+    color: chalk.rgb(118, 185, 0),
+    signupUrl: 'https://build.nvidia.com',
+    signupHint: 'Profile → API Keys → Generate',
+    rateLimits: 'Free tier (provider quota by model)',
+  },
+  groq: {
+    label: 'Groq',
+    color: chalk.rgb(249, 103, 20),
+    signupUrl: 'https://console.groq.com/keys',
+    signupHint: 'API Keys → Create API Key',
+    rateLimits: 'Free dev tier (provider quota)',
+  },
+  cerebras: {
+    label: 'Cerebras',
+    color: chalk.rgb(0, 180, 255),
+    signupUrl: 'https://cloud.cerebras.ai',
+    signupHint: 'API Keys → Create',
+    rateLimits: 'Free dev tier (provider quota)',
+  },
+  sambanova: {
+    label: 'SambaNova',
+    color: chalk.rgb(255, 165, 0),
+    signupUrl: 'https://sambanova.ai/developers',
+    signupHint: 'Developers portal → Create API key',
+    rateLimits: 'Dev tier generous quota',
+  },
+  openrouter: {
+    label: 'OpenRouter',
+    color: chalk.rgb(120, 80, 255),
+    signupUrl: 'https://openrouter.ai/keys',
+    signupHint: 'API Keys → Create',
+    rateLimits: '50 req/day, 20/min (:free shared quota)',
+  },
+  huggingface: {
+    label: 'Hugging Face Inference',
+    color: chalk.rgb(255, 182, 0),
+    signupUrl: 'https://huggingface.co/settings/tokens',
+    signupHint: 'Settings → Access Tokens',
+    rateLimits: 'Free monthly credits (~$0.10)',
+  },
+  replicate: {
+    label: 'Replicate',
+    color: chalk.rgb(120, 160, 255),
+    signupUrl: 'https://replicate.com/account/api-tokens',
+    signupHint: 'Account → API Tokens',
+    rateLimits: 'Developer free quota',
+  },
+  deepinfra: {
+    label: 'DeepInfra',
+    color: chalk.rgb(0, 180, 140),
+    signupUrl: 'https://deepinfra.com/login',
+    signupHint: 'Login → API keys',
+    rateLimits: 'Free dev tier (low-latency quota)',
+  },
+  fireworks: {
+    label: 'Fireworks AI',
+    color: chalk.rgb(255, 80, 50),
+    signupUrl: 'https://fireworks.ai',
+    signupHint: 'Create account → Generate API key',
+    rateLimits: '$1 free credits (new dev accounts)',
+  },
+  codestral: {
+    label: 'Mistral Codestral',
+    color: chalk.rgb(255, 100, 100),
+    signupUrl: 'https://codestral.mistral.ai',
+    signupHint: 'API Keys → Create',
+    rateLimits: '30 req/min, 2000/day',
+  },
+  hyperbolic: {
+    label: 'Hyperbolic',
+    color: chalk.rgb(0, 200, 150),
+    signupUrl: 'https://app.hyperbolic.ai/settings',
+    signupHint: 'Settings → API Keys',
+    rateLimits: '$1 free trial credits',
+  },
+  scaleway: {
+    label: 'Scaleway',
+    color: chalk.rgb(130, 0, 250),
+    signupUrl: 'https://console.scaleway.com/iam/api-keys',
+    signupHint: 'IAM → API Keys',
+    rateLimits: '1M free tokens',
+  },
+  googleai: {
+    label: 'Google AI Studio',
+    color: chalk.rgb(66, 133, 244),
+    signupUrl: 'https://aistudio.google.com/apikey',
+    signupHint: 'Get API key',
+    rateLimits: '14.4K req/day, 30/min',
+  },
+}
+
 // 📖 OpenCode config location varies by platform
 // 📖 Windows: %APPDATA%\opencode\opencode.json (or sometimes ~/.config/opencode)
 // 📖 macOS/Linux: ~/.config/opencode/opencode.json
@@ -1193,6 +1335,45 @@ const OPENCODE_CONFIG = isWindows
 
 // 📖 Fallback to .config on Windows if AppData doesn't exist
 const OPENCODE_CONFIG_FALLBACK = join(homedir(), '.config', 'opencode', 'opencode.json')
+const OPENCODE_PORT_RANGE_START = 4096
+const OPENCODE_PORT_RANGE_END = 5096
+
+// 📖 isTcpPortAvailable: checks if a local TCP port is free for OpenCode.
+// 📖 Used to avoid tmux sub-agent port conflicts when multiple projects run in parallel.
+function isTcpPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = createServer()
+    server.once('error', () => resolve(false))
+    server.once('listening', () => {
+      server.close(() => resolve(true))
+    })
+    server.listen(port)
+  })
+}
+
+// 📖 resolveOpenCodeTmuxPort: selects a safe port for OpenCode when inside tmux.
+// 📖 Priority:
+// 📖 1) OPENCODE_PORT from env (if valid and available)
+// 📖 2) First available port in 4096-5095
+async function resolveOpenCodeTmuxPort() {
+  const envPortRaw = process.env.OPENCODE_PORT
+  const envPort = Number.parseInt(envPortRaw || '', 10)
+
+  if (Number.isInteger(envPort) && envPort > 0 && envPort <= 65535) {
+    if (await isTcpPortAvailable(envPort)) {
+      return { port: envPort, source: 'env' }
+    }
+    console.log(chalk.yellow(`  ⚠ OPENCODE_PORT=${envPort} is already in use; selecting another port for this run.`))
+  }
+
+  for (let port = OPENCODE_PORT_RANGE_START; port < OPENCODE_PORT_RANGE_END; port++) {
+    if (await isTcpPortAvailable(port)) {
+      return { port, source: 'auto' }
+    }
+  }
+
+  return null
+}
 
 function getOpenCodeConfigPath() {
   if (existsSync(OPENCODE_CONFIG)) return OPENCODE_CONFIG
@@ -1243,10 +1424,30 @@ async function spawnOpenCode(args, providerKey, fcmConfig) {
   const envVarName = ENV_VAR_NAMES[providerKey]
   const resolvedKey = getApiKey(fcmConfig, providerKey)
   const childEnv = { ...process.env }
+  const finalArgs = [...args]
+  const hasExplicitPortArg = finalArgs.includes('--port')
   if (envVarName && resolvedKey) childEnv[envVarName] = resolvedKey
 
+  // 📖 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) {
+    const tmuxPort = await resolveOpenCodeTmuxPort()
+    if (tmuxPort) {
+      const portValue = String(tmuxPort.port)
+      childEnv.OPENCODE_PORT = portValue
+      finalArgs.push('--port', portValue)
+      if (tmuxPort.source === 'env') {
+        console.log(chalk.dim(`  📺 tmux detected — using OPENCODE_PORT=${portValue}.`))
+      } else {
+        console.log(chalk.dim(`  📺 tmux detected — using OpenCode port ${portValue} for sub-agent panes.`))
+      }
+    } else {
+      console.log(chalk.yellow(`  ⚠ tmux detected but no free OpenCode port found in ${OPENCODE_PORT_RANGE_START}-${OPENCODE_PORT_RANGE_END - 1}; launching without --port.`))
+    }
+  }
+
   const { spawn } = await import('child_process')
-  const child = spawn('opencode', args, {
+  const child = spawn('opencode', finalArgs, {
     stdio: 'inherit',
     shell: true,
     detached: false,
@@ -1269,7 +1470,7 @@ async function spawnOpenCode(args, providerKey, fcmConfig) {
 
 // ─── Start OpenCode ────────────────────────────────────────────────────────────
 // 📖 Launches OpenCode with the selected model.
-// 📖 Handles all 3 providers: nvidia (needs custom provider config), groq & cerebras (built-in in OpenCode).
+// 📖 Handles nvidia + all OpenAI-compatible providers defined in sources.js.
 // 📖 For nvidia: checks if NIM is configured, sets provider.models entry, spawns with nvidia/model-id.
 // 📖 For groq/cerebras: OpenCode has built-in support -- just sets model in config and spawns.
 // 📖 Model format: { modelId, label, tier, providerKey }
@@ -1357,6 +1558,14 @@ After installation, you can use: opencode --model ${modelRef}`
       await spawnOpenCode([], providerKey, fcmConfig)
     }
   } else {
+    if (providerKey === 'replicate') {
+      console.log(chalk.yellow('  ⚠ Replicate models are monitor-only for now in OpenCode mode.'))
+      console.log(chalk.dim('    Reason: Replicate uses /v1/predictions instead of OpenAI chat-completions.'))
+      console.log(chalk.dim('    You can still benchmark this model in the TUI and use other providers for OpenCode launch.'))
+      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.
@@ -1413,6 +1622,36 @@ After installation, you can use: opencode --model ${modelRef}`
           },
           models: {}
         }
+      } else if (providerKey === 'huggingface') {
+        config.provider.huggingface = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Hugging Face Inference',
+          options: {
+            baseURL: 'https://router.huggingface.co/v1',
+            apiKey: '{env:HUGGINGFACE_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'deepinfra') {
+        config.provider.deepinfra = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'DeepInfra',
+          options: {
+            baseURL: 'https://api.deepinfra.com/v1/openai',
+            apiKey: '{env:DEEPINFRA_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'fireworks') {
+        config.provider.fireworks = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Fireworks AI',
+          options: {
+            baseURL: 'https://api.fireworks.ai/inference/v1',
+            apiKey: '{env:FIREWORKS_API_KEY}'
+          },
+          models: {}
+        }
       } else if (providerKey === 'codestral') {
         config.provider.codestral = {
           npm: '@ai-sdk/openai-compatible',
@@ -1488,7 +1727,7 @@ After installation, you can use: opencode --model ${modelRef}`
 // ─── Start OpenCode Desktop ─────────────────────────────────────────────────────
 // 📖 startOpenCodeDesktop: Same config logic as startOpenCode, but opens the Desktop app.
 // 📖 OpenCode Desktop shares config at the same location as CLI.
-// 📖 Handles all 3 providers: nvidia (needs custom provider config), groq & cerebras (built-in).
+// 📖 Handles nvidia + all OpenAI-compatible providers defined in sources.js.
 // 📖 No need to wait for exit — Desktop app stays open independently.
 async function startOpenCodeDesktop(model, fcmConfig) {
   const providerKey = model.providerKey ?? 'nvidia'
@@ -1589,6 +1828,14 @@ ${isWindows ? 'set NVIDIA_API_KEY=your_key_here' : 'export NVIDIA_API_KEY=your_k
       console.log()
     }
   } else {
+    if (providerKey === 'replicate') {
+      console.log(chalk.yellow('  ⚠ Replicate models are monitor-only for now in OpenCode Desktop mode.'))
+      console.log(chalk.dim('    Reason: Replicate uses /v1/predictions instead of OpenAI chat-completions.'))
+      console.log(chalk.dim('    You can still benchmark this model in the TUI and use other providers for Desktop launch.'))
+      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.
@@ -1643,6 +1890,36 @@ ${isWindows ? 'set NVIDIA_API_KEY=your_key_here' : 'export NVIDIA_API_KEY=your_k
           },
           models: {}
         }
+      } else if (providerKey === 'huggingface') {
+        config.provider.huggingface = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Hugging Face Inference',
+          options: {
+            baseURL: 'https://router.huggingface.co/v1',
+            apiKey: '{env:HUGGINGFACE_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'deepinfra') {
+        config.provider.deepinfra = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'DeepInfra',
+          options: {
+            baseURL: 'https://api.deepinfra.com/v1/openai',
+            apiKey: '{env:DEEPINFRA_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'fireworks') {
+        config.provider.fireworks = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Fireworks AI',
+          options: {
+            baseURL: 'https://api.fireworks.ai/inference/v1',
+            apiKey: '{env:FIREWORKS_API_KEY}'
+          },
+          models: {}
+        }
       } else if (providerKey === 'codestral') {
         config.provider.codestral = {
           npm: '@ai-sdk/openai-compatible',
@@ -1854,7 +2131,7 @@ async function runFiableMode(config) {
   const pingPromises = results.map(r => {
     const rApiKey = getApiKey(config, r.providerKey)
     const url = sources[r.providerKey]?.url
-    return ping(rApiKey, r.modelId, url).then(({ code, ms }) => {
+    return ping(rApiKey, r.modelId, r.providerKey, url).then(({ code, ms }) => {
       r.pings.push({ ms, code })
       if (code === '200') {
         r.status = 'up'
@@ -1919,6 +2196,7 @@ async function main() {
   // 📖 Load JSON config (auto-migrates old plain-text ~/.free-coding-models if needed)
   const config = loadConfig()
   ensureTelemetryConfig(config)
+  ensureFavoritesConfig(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))
@@ -2002,6 +2280,7 @@ async function main() {
       httpCode: null,
       hidden: false,  // 📖 Simple flag to hide/show models
     }))
+  syncFavoriteFlags(results, config)
 
   // 📖 Clamp scrollOffset so cursor is always within the visible viewport window.
   // 📖 Called after every cursor move, sort change, and terminal resize.
@@ -2052,6 +2331,9 @@ async function main() {
     settingsEditMode: false,      // 📖 Whether we're in inline key editing mode
     settingsEditBuffer: '',       // 📖 Typed characters for the API key being edited
     settingsTestResults: {},      // 📖 { providerKey: 'pending'|'ok'|'fail'|null }
+    settingsUpdateState: 'idle',  // 📖 'idle'|'checking'|'available'|'up-to-date'|'error'|'installing'
+    settingsUpdateLatestVersion: null, // 📖 Latest npm version discovered from manual check
+    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
     helpVisible: false,           // 📖 Whether the help overlay (K key) is active
@@ -2089,6 +2371,11 @@ async function main() {
     const activeTier = TIER_CYCLE[tierFilterMode]
     const activeOrigin = ORIGIN_CYCLE[originFilterMode]
     state.results.forEach(r => {
+      // 📖 Favorites stay visible regardless of tier/origin filters.
+      if (r.isFavorite) {
+        r.hidden = false
+        return
+      }
       // 📖 Apply both tier and origin filters — model is hidden if it fails either
       const tierHide = activeTier !== null && r.tier !== activeTier
       const originHide = activeOrigin !== null && r.providerKey !== activeOrigin
@@ -2105,18 +2392,21 @@ async function main() {
   function renderSettings() {
     const providerKeys = Object.keys(sources)
     const telemetryRowIdx = providerKeys.length
+    const updateRowIdx = providerKeys.length + 1
     const EL = '\x1b[K'
     const lines = []
 
     lines.push('')
     lines.push(`  ${chalk.bold('⚙  Settings')}  ${chalk.dim('— free-coding-models v' + LOCAL_VERSION)}`)
     lines.push('')
-    lines.push(`  ${chalk.bold('Providers')}`)
+    lines.push(`  ${chalk.bold('🧩 Providers')}`)
+    lines.push(`  ${chalk.dim('  ' + '─'.repeat(112))}`)
     lines.push('')
 
     for (let i = 0; i < providerKeys.length; i++) {
       const pk = providerKeys[i]
       const src = sources[pk]
+      const meta = PROVIDER_METADATA[pk] || {}
       const isCursor = i === state.settingsCursor
       const enabled = isProviderEnabled(state.config, pk)
       const keyVal = state.config.apiKeys?.[pk] ?? ''
@@ -2140,22 +2430,37 @@ async function main() {
       if (testResult === 'pending') testBadge = chalk.yellow('[Testing…]')
       else if (testResult === 'ok')   testBadge = chalk.greenBright('[Test ✅]')
       else if (testResult === 'fail') testBadge = chalk.red('[Test ❌]')
+      const rateSummary = chalk.dim((meta.rateLimits || 'No limit info').slice(0, 36))
 
-      const enabledBadge = enabled ? chalk.greenBright('✅') : chalk.dim('⬜')
-      const providerName = chalk.bold(src.name.padEnd(10))
+      const enabledBadge = enabled ? chalk.greenBright('✅') : chalk.redBright('❌')
+      const providerName = chalk.bold((meta.label || src.name || pk).slice(0, 22).padEnd(22))
       const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
 
-      const row = `${bullet}[ ${enabledBadge} ] ${providerName}  ${keyDisplay.padEnd(30)}  ${testBadge}`
+      const row = `${bullet}[ ${enabledBadge} ] ${providerName}  ${keyDisplay.padEnd(30)}  ${testBadge}  ${rateSummary}`
       lines.push(isCursor ? chalk.bgRgb(30, 30, 60)(row) : row)
     }
 
     lines.push('')
-    lines.push(`  ${chalk.bold('Analytics')}`)
+    const selectedProviderKey = providerKeys[Math.min(state.settingsCursor, providerKeys.length - 1)]
+    const selectedSource = sources[selectedProviderKey]
+    const selectedMeta = PROVIDER_METADATA[selectedProviderKey] || {}
+    if (selectedSource && state.settingsCursor < telemetryRowIdx) {
+      const selectedKey = getApiKey(state.config, selectedProviderKey)
+      const setupStatus = selectedKey ? chalk.green('API key detected ✅') : chalk.yellow('API key missing ⚠')
+      lines.push(`  ${chalk.bold('Setup Instructions')} — ${selectedMeta.label || selectedSource.name || selectedProviderKey}`)
+      lines.push(chalk.dim(`  1) Create a ${selectedMeta.label || selectedSource.name} account: ${selectedMeta.signupUrl || 'signup link missing'}`))
+      lines.push(chalk.dim(`  2) ${selectedMeta.signupHint || 'Generate an API key and paste it with Enter on this row'}`))
+      lines.push(chalk.dim(`  3) Press ${chalk.yellow('T')} to test your key. Status: ${setupStatus}`))
+      lines.push('')
+    }
+
+    lines.push(`  ${chalk.bold('📊 Analytics')}`)
+    lines.push(`  ${chalk.dim('  ' + '─'.repeat(112))}`)
     lines.push('')
 
     const telemetryCursor = state.settingsCursor === telemetryRowIdx
     const telemetryEnabled = state.config.telemetry?.enabled === true
-    const telemetryStatus = telemetryEnabled ? chalk.greenBright('✅ Enabled') : chalk.dim('⬜ Disabled')
+    const telemetryStatus = telemetryEnabled ? chalk.greenBright('✅ Enabled') : chalk.redBright('❌ Disabled')
     const telemetryRowBullet = telemetryCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
     const telemetryEnv = parseTelemetryEnv(process.env.FREE_CODING_MODELS_TELEMETRY)
     const telemetrySource = telemetryEnv === null
@@ -2164,11 +2469,35 @@ async function main() {
     const telemetryRow = `${telemetryRowBullet}${chalk.bold('Anonymous usage analytics').padEnd(44)} ${telemetryStatus}  ${telemetrySource}`
     lines.push(telemetryCursor ? chalk.bgRgb(30, 30, 60)(telemetryRow) : telemetryRow)
 
+    lines.push('')
+    lines.push(`  ${chalk.bold('🛠 Maintenance')}`)
+    lines.push(`  ${chalk.dim('  ' + '─'.repeat(112))}`)
+    lines.push('')
+
+    const updateCursor = state.settingsCursor === updateRowIdx
+    const updateBullet = updateCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+    const updateState = state.settingsUpdateState
+    const latestFound = state.settingsUpdateLatestVersion
+    const updateActionLabel = updateState === 'available' && latestFound
+      ? `Install update (v${latestFound})`
+      : 'Check for updates manually'
+    let updateStatus = chalk.dim('Press Enter or U to check npm registry')
+    if (updateState === 'checking') updateStatus = chalk.yellow('Checking npm registry…')
+    if (updateState === 'available' && latestFound) updateStatus = chalk.greenBright(`Update available: v${latestFound} (Enter to install)`)
+    if (updateState === 'up-to-date') updateStatus = chalk.green('Already on latest version')
+    if (updateState === 'error') updateStatus = chalk.red('Check failed (press U to retry)')
+    if (updateState === 'installing') updateStatus = chalk.cyan('Installing update…')
+    const updateRow = `${updateBullet}${chalk.bold(updateActionLabel).padEnd(44)} ${updateStatus}`
+    lines.push(updateCursor ? chalk.bgRgb(30, 30, 60)(updateRow) : updateRow)
+    if (updateState === 'error' && state.settingsUpdateError) {
+      lines.push(chalk.red(`      ${state.settingsUpdateError}`))
+    }
+
     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  •  Space Toggle enabled  •  T Test key  •  Esc Close'))
+      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('')
 
@@ -2187,6 +2516,7 @@ async function main() {
     lines.push('')
     lines.push(`  ${chalk.bold('❓ Keyboard Shortcuts')}  ${chalk.dim('— press K or Esc to close')}`)
     lines.push('')
+    lines.push(`  ${chalk.bold('Main TUI')}`)
     lines.push(`  ${chalk.bold('Navigation')}`)
     lines.push(`  ${chalk.yellow('↑↓')}           Navigate rows`)
     lines.push(`  ${chalk.yellow('Enter')}        Select model and launch`)
@@ -2204,10 +2534,30 @@ async function main() {
     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('P')}  Open settings  ${chalk.dim('(manage API keys, provider toggles, analytics toggle)')}`)
+    lines.push(`  ${chalk.yellow('F')}  Toggle favorite on selected row  ${chalk.dim('(⭐ pinned at top, persisted)')}`)
+    lines.push(`  ${chalk.yellow('P')}  Open settings  ${chalk.dim('(manage API keys, provider toggles, analytics, manual update)')}`)
     lines.push(`  ${chalk.yellow('K')} / ${chalk.yellow('Esc')}  Show/hide this help`)
     lines.push(`  ${chalk.yellow('Ctrl+C')}  Exit`)
     lines.push('')
+    lines.push(`  ${chalk.bold('Settings (P)')}`)
+    lines.push(`  ${chalk.yellow('↑↓')}           Navigate rows`)
+    lines.push(`  ${chalk.yellow('Enter')}        Edit key / toggle analytics / check-install update`)
+    lines.push(`  ${chalk.yellow('Space')}        Toggle provider enable/disable`)
+    lines.push(`  ${chalk.yellow('T')}            Test selected provider key`)
+    lines.push(`  ${chalk.yellow('U')}            Check updates manually`)
+    lines.push(`  ${chalk.yellow('Esc')}          Close settings`)
+    lines.push('')
+    lines.push(`  ${chalk.bold('CLI Flags')}`)
+    lines.push(`  ${chalk.dim('Usage: free-coding-models [options]')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --opencode')}           ${chalk.dim('OpenCode CLI mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --opencode-desktop')}   ${chalk.dim('OpenCode Desktop mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --openclaw')}           ${chalk.dim('OpenClaw mode')}`)
+    lines.push(`  ${chalk.cyan('free-coding-models --best')}               ${chalk.dim('Only top tiers (A+, S, S+)')}`)
+    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.dim('Flags can be combined: --openclaw --tier S')}`)
+    lines.push('')
     const cleared = lines.map(l => l + EL)
     const remaining = state.terminalRows > 0 ? Math.max(0, state.terminalRows - cleared.length) : 0
     for (let i = 0; i < remaining; i++) cleared.push(EL)
@@ -2227,15 +2577,51 @@ async function main() {
     if (!testModel) { state.settingsTestResults[providerKey] = 'fail'; return }
 
     state.settingsTestResults[providerKey] = 'pending'
-    const { code } = await ping(testKey, testModel, src.url)
+    const { code } = await ping(testKey, testModel, providerKey, src.url)
     state.settingsTestResults[providerKey] = code === '200' ? 'ok' : 'fail'
   }
 
+  // 📖 Manual update checker from settings; keeps status visible in maintenance row.
+  async function checkUpdatesFromSettings() {
+    if (state.settingsUpdateState === 'checking' || state.settingsUpdateState === 'installing') return
+    state.settingsUpdateState = 'checking'
+    state.settingsUpdateError = null
+    const { latestVersion, error } = await checkForUpdateDetailed()
+    if (error) {
+      state.settingsUpdateState = 'error'
+      state.settingsUpdateLatestVersion = null
+      state.settingsUpdateError = error
+      return
+    }
+    if (latestVersion) {
+      state.settingsUpdateState = 'available'
+      state.settingsUpdateLatestVersion = latestVersion
+      state.settingsUpdateError = null
+      return
+    }
+    state.settingsUpdateState = 'up-to-date'
+    state.settingsUpdateLatestVersion = null
+    state.settingsUpdateError = null
+  }
+
+  // 📖 Leaves TUI cleanly, then runs npm global update command.
+  function launchUpdateFromSettings(latestVersion) {
+    if (!latestVersion) return
+    state.settingsUpdateState = 'installing'
+    clearInterval(ticker)
+    clearTimeout(state.pingIntervalObj)
+    process.stdin.removeListener('keypress', onKeyPress)
+    if (process.stdin.isTTY) process.stdin.setRawMode(false)
+    process.stdin.pause()
+    process.stdout.write(ALT_LEAVE)
+    runUpdate(latestVersion)
+  }
+
   // Apply CLI --tier filter if provided
   if (cliArgs.tierFilter) {
     const allowed = TIER_LETTER_MAP[cliArgs.tierFilter]
     state.results.forEach(r => {
-      r.hidden = !allowed.includes(r.tier)
+      r.hidden = r.isFavorite ? false : !allowed.includes(r.tier)
     })
   }
 
@@ -2259,6 +2645,7 @@ async function main() {
     if (state.settingsOpen) {
       const providerKeys = Object.keys(sources)
       const telemetryRowIdx = providerKeys.length
+      const updateRowIdx = providerKeys.length + 1
 
       // 📖 Edit mode: capture typed characters for the API key
       if (state.settingsEditMode) {
@@ -2301,6 +2688,11 @@ async function main() {
         // 📖 Re-index results
         results.forEach((r, i) => { r.idx = i + 1 })
         state.results = results
+        syncFavoriteFlags(state.results, state.config)
+        applyTierFilter()
+        const visible = state.results.filter(r => !r.hidden)
+        state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+        if (state.cursor >= state.visibleSorted.length) state.cursor = Math.max(0, state.visibleSorted.length - 1)
         adjustScrollOffset(state)
         // 📖 Re-ping all models that were 'noauth' (got 401 without key) but now have a key
         // 📖 This makes the TUI react immediately when a user adds an API key in settings
@@ -2320,7 +2712,7 @@ async function main() {
         return
       }
 
-      if (key.name === 'down' && state.settingsCursor < telemetryRowIdx) {
+      if (key.name === 'down' && state.settingsCursor < updateRowIdx) {
         state.settingsCursor++
         return
       }
@@ -2333,6 +2725,14 @@ async function main() {
           saveConfig(state.config)
           return
         }
+        if (state.settingsCursor === updateRowIdx) {
+          if (state.settingsUpdateState === 'available' && state.settingsUpdateLatestVersion) {
+            launchUpdateFromSettings(state.settingsUpdateLatestVersion)
+            return
+          }
+          checkUpdatesFromSettings()
+          return
+        }
 
         // 📖 Enter edit mode for the selected provider's key
         const pk = providerKeys[state.settingsCursor]
@@ -2349,6 +2749,7 @@ async function main() {
           saveConfig(state.config)
           return
         }
+        if (state.settingsCursor === updateRowIdx) return
 
         // 📖 Toggle enabled/disabled for selected provider
         const pk = providerKeys[state.settingsCursor]
@@ -2360,7 +2761,7 @@ async function main() {
       }
 
       if (key.name === 't') {
-        if (state.settingsCursor === telemetryRowIdx) return
+        if (state.settingsCursor === telemetryRowIdx || state.settingsCursor === updateRowIdx) return
 
         // 📖 Test the selected provider's key (fires a real ping)
         const pk = providerKeys[state.settingsCursor]
@@ -2368,6 +2769,11 @@ async function main() {
         return
       }
 
+      if (key.name === 'u') {
+        checkUpdatesFromSettings()
+        return
+      }
+
       if (key.ctrl && key.name === 'c') { exit(0); return }
       return // 📖 Swallow all other keys while settings is open
     }
@@ -2400,12 +2806,29 @@ async function main() {
       }
       // 📖 Recompute visible sorted list and reset cursor to top to avoid stale index
       const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResults(visible, state.sortColumn, state.sortDirection)
+      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
       return
     }
 
+    // 📖 F key: toggle favorite on the currently selected row and persist to config.
+    if (key.name === 'f') {
+      const selected = state.visibleSorted[state.cursor]
+      if (!selected) return
+      toggleFavoriteModel(state.config, selected.providerKey, selected.modelId)
+      syncFavoriteFlags(state.results, state.config)
+      applyTierFilter()
+      const selectedKey = toFavoriteKey(selected.providerKey, selected.modelId)
+      const visible = state.results.filter(r => !r.hidden)
+      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+      const newCursor = state.visibleSorted.findIndex(r => toFavoriteKey(r.providerKey, r.modelId) === selectedKey)
+      if (newCursor >= 0) state.cursor = newCursor
+      else if (state.cursor >= state.visibleSorted.length) state.cursor = Math.max(0, state.visibleSorted.length - 1)
+      adjustScrollOffset(state)
+      return
+    }
+
     // 📖 Interval adjustment keys: W=decrease (faster), X=increase (slower)
     // 📖 Minimum 1s, maximum 60s
     if (key.name === 'w') {
@@ -2420,7 +2843,7 @@ async function main() {
       applyTierFilter()
       // 📖 Recompute visible sorted list and reset cursor to avoid stale index into new filtered set
       const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResults(visible, state.sortColumn, state.sortDirection)
+      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
       return
@@ -2432,7 +2855,7 @@ async function main() {
       applyTierFilter()
       // 📖 Recompute visible sorted list and reset cursor to avoid stale index into new filtered set
       const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResults(visible, state.sortColumn, state.sortDirection)
+      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
       return
@@ -2542,7 +2965,7 @@ async function main() {
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
     if (!state.settingsOpen) {
       const visible = state.results.filter(r => !r.hidden)
-      state.visibleSorted = sortResults(visible, state.sortColumn, state.sortDirection)
+      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
     const content = state.settingsOpen
       ? renderSettings()
@@ -2554,7 +2977,7 @@ async function main() {
 
   // 📖 Populate visibleSorted before the first frame so Enter works immediately
   const initialVisible = state.results.filter(r => !r.hidden)
-  state.visibleSorted = sortResults(initialVisible, state.sortColumn, state.sortDirection)
+  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))
 
@@ -2566,7 +2989,7 @@ async function main() {
   const pingModel = async (r) => {
     const providerApiKey = getApiKey(state.config, r.providerKey) ?? null
     const providerUrl = sources[r.providerKey]?.url ?? sources.nvidia.url
-    const { code, ms } = await ping(providerApiKey, r.modelId, providerUrl)
+    const { code, ms } = await ping(providerApiKey, r.modelId, r.providerKey, providerUrl)
 
     // 📖 Store ping result as object with ms and code
     // 📖 ms = actual response time (even for errors like 429)