free-coding-models 0.1.64 → 0.1.66

package/README.md

@@ -2,8 +2,8 @@
   <img src="https://img.shields.io/npm/v/free-coding-models?color=76b900&label=npm&logo=npm" alt="npm version">
   <img src="https://img.shields.io/node/v/free-coding-models?color=76b900&logo=node.js" alt="node version">
   <img src="https://img.shields.io/npm/l/free-coding-models?color=76b900" alt="license">
-  <img src="https://img.shields.io/badge/models-111-76b900?logo=nvidia" alt="models count">
-  <img src="https://img.shields.io/badge/providers-13-blue" alt="providers count">
+  <img src="https://img.shields.io/badge/models-134-76b900?logo=nvidia" alt="models count">
+  <img src="https://img.shields.io/badge/providers-17-blue" alt="providers count">
 </p>
 
 <h1 align="center">free-coding-models</h1>
@@ -24,7 +24,7 @@
 
 <p align="center">
   <strong>Find the fastest coding LLM models in seconds</strong><br>
-  <sub>Ping free coding models from 13 providers in real-time — pick the best one for OpenCode, OpenClaw, or any AI coding assistant</sub>
+  <sub>Ping free coding models from 17 providers in real-time — pick the best one for OpenCode, OpenClaw, or any AI coding assistant</sub>
 </p>
 
 <p align="center">
@@ -47,8 +47,8 @@
 ## ✨ Features
 
 - **🎯 Coding-focused** — Only LLM models optimized for code generation, not chat or vision
-- **🌐 Multi-provider** — 111 models from NVIDIA NIM, Groq, Cerebras, SambaNova, OpenRouter, Hugging Face Inference, Replicate, DeepInfra, Fireworks AI, Codestral, Hyperbolic, Scaleway, and Google AI — all free to use
-- **⚙️ Settings screen** — Press `P` to manage provider API keys, enable/disable providers, and test keys live
+- **🌐 Multi-provider** — 134 models from NVIDIA NIM, Groq, Cerebras, SambaNova, OpenRouter, Hugging Face Inference, Replicate, DeepInfra, Fireworks AI, Codestral, Hyperbolic, Scaleway, Google AI, SiliconFlow, Together AI, Cloudflare Workers AI, and Perplexity API
+- **⚙️ Settings screen** — Press `P` to manage provider API keys, enable/disable providers, test keys live, and manually check/install updates
 - **🚀 Parallel pings** — All models tested simultaneously via native `fetch`
 - **📊 Real-time animation** — Watch latency appear live in alternate screen buffer
 - **🏆 Smart ranking** — Top 3 fastest models highlighted with medals 🥇🥈🥉
@@ -64,6 +64,7 @@
 - **📶 Status indicators** — UP ✅ · No Key 🔑 · Timeout ⏳ · Overloaded 🔥 · Not Found 🚫
 - **🔍 Keyless latency** — Models are pinged even without an API key — a `🔑 NO KEY` status confirms the server is reachable with real latency shown, so you can compare providers before committing to a key
 - **🏷 Tier filtering** — Filter models by tier letter (S, A, B, C) with `--tier` flag or dynamically with `T` key
+- **⭐ Persistent favorites** — Press `F` on a selected row to pin/unpin it; favorites stay at top with a dark orange background and a star before the model name
 - **📊 Privacy-first analytics (optional)** — anonymous PostHog events with explicit consent + opt-out
 
 ---
@@ -87,10 +88,14 @@ Before using `free-coding-models`, make sure you have:
    - **Hyperbolic** — [app.hyperbolic.ai/settings](https://app.hyperbolic.ai/settings) → API Keys ($1 free trial)
    - **Scaleway** — [console.scaleway.com/iam/api-keys](https://console.scaleway.com/iam/api-keys) → IAM → API Keys (1M free tokens)
    - **Google AI Studio** — [aistudio.google.com/apikey](https://aistudio.google.com/apikey) → Get API key (free Gemma models, 14.4K req/day)
+   - **SiliconFlow** — [cloud.siliconflow.cn/account/ak](https://cloud.siliconflow.cn/account/ak) → API Keys (free-model quotas vary by model)
+   - **Together AI** — [api.together.ai/settings/api-keys](https://api.together.ai/settings/api-keys) → API Keys (credits/promotions vary)
+   - **Cloudflare Workers AI** — [dash.cloudflare.com](https://dash.cloudflare.com) → Create API token + set `CLOUDFLARE_ACCOUNT_ID` (Free: 10k neurons/day)
+   - **Perplexity API** — [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api) → API Key (tiered limits by spend)
 3. **OpenCode** *(optional)* — [Install OpenCode](https://github.com/opencode-ai/opencode) to use the OpenCode integration
 4. **OpenClaw** *(optional)* — [Install OpenClaw](https://openclaw.ai) to use the OpenClaw integration
 
-> 💡 **Tip:** You don't need all thirteen providers. One key is enough to get started. Add more later via the Settings screen (`P` key). Models without a key still show real latency (`🔑 NO KEY`) so you can evaluate providers before signing up.
+> 💡 **Tip:** You don't need all seventeen providers. One key is enough to get started. Add more later via the Settings screen (`P` key). Models without a key still show real latency (`🔑 NO KEY`) so you can evaluate providers before signing up.
 
 ---
 
@@ -171,13 +176,13 @@ When you run `free-coding-models` without `--opencode` or `--openclaw`, you get
 Use `↑↓` arrows to select, `Enter` to confirm. Then the TUI launches with your chosen mode shown in the header badge.
 
 **How it works:**
-1. **Ping phase** — All enabled models are pinged in parallel (up to 111 across 13 providers)
+1. **Ping phase** — All enabled models are pinged in parallel (up to 134 across 17 providers)
 2. **Continuous monitoring** — Models are re-pinged every 2 seconds forever
 3. **Real-time updates** — Watch "Latest", "Avg", and "Up%" columns update live
 4. **Select anytime** — Use ↑↓ arrows to navigate, press Enter on a model to act
 5. **Smart detection** — Automatically detects if NVIDIA NIM is configured in OpenCode or OpenClaw
 
-Setup wizard (first run — walks through all 13 providers):
+Setup wizard (first run — walks through all 17 providers):
 
 ```
   🔑 First-time setup — API keys
@@ -207,7 +212,7 @@ Setup wizard (first run — walks through all 13 providers):
   You can add or change keys anytime with the P key in the TUI.
 ```
 
-You don't need all thirteen — skip any provider by pressing Enter. At least one key is required.
+You don't need all seventeen — skip any provider by pressing Enter. At least one key is required.
 
 ### Adding or changing keys later
 
@@ -227,18 +232,21 @@ Press **`P`** to open the Settings screen at any time:
   2) Profile → API Keys → Generate
   3) Press T to test your key
 
-  ↑↓ Navigate  •  Enter Edit key  •  Space Toggle enabled  •  T Test key  •  Esc Close
+  ↑↓ Navigate  •  Enter Edit key / Check-or-Install update  •  Space Toggle enabled  •  T Test key  •  U Check updates  •  Esc Close
 ```
 
 - **↑↓** — navigate providers
 - **Enter** — enter inline key edit mode (type your key, Enter to save, Esc to cancel)
 - **Space** — toggle provider enabled/disabled
 - **T** — fire a real test ping to verify the key works (shows ✅/❌)
+- **U** — manually check npm for a newer version
 - **Esc** — close settings and reload models list
 
 Keys are saved to `~/.free-coding-models.json` (permissions `0600`).
 
 Analytics toggle is in the same Settings screen (`P`) as a dedicated row (toggle with Enter or Space).
+Manual update is in the same Settings screen (`P`) under **Maintenance** (Enter to check, Enter again to install when an update is available).
+Favorites are also persisted in the same config file and survive restarts.
 
 ### Environment variable overrides
 
@@ -253,6 +261,10 @@ HUGGINGFACE_API_KEY=hf_xxx free-coding-models
 REPLICATE_API_TOKEN=r8_xxx free-coding-models
 DEEPINFRA_API_KEY=di_xxx free-coding-models
 FIREWORKS_API_KEY=fw_xxx free-coding-models
+SILICONFLOW_API_KEY=sk_xxx free-coding-models
+TOGETHER_API_KEY=together_xxx free-coding-models
+CLOUDFLARE_API_TOKEN=cf_xxx CLOUDFLARE_ACCOUNT_ID=your_account_id free-coding-models
+PERPLEXITY_API_KEY=pplx_xxx free-coding-models
 FREE_CODING_MODELS_TELEMETRY=0 free-coding-models
 ```
 
@@ -302,13 +314,46 @@ When enabled, telemetry events include: event name, app version, selected mode,
 1. Sign up at [fireworks.ai](https://fireworks.ai)
 2. Open Settings → Access Tokens and create a token
 
+**Mistral Codestral**:
+1. Sign up at [codestral.mistral.ai](https://codestral.mistral.ai)
+2. Go to API Keys → Create
+
+**Hyperbolic**:
+1. Sign up at [app.hyperbolic.ai/settings](https://app.hyperbolic.ai/settings)
+2. Create an API key in Settings
+
+**Scaleway**:
+1. Sign up at [console.scaleway.com/iam/api-keys](https://console.scaleway.com/iam/api-keys)
+2. Go to IAM → API Keys
+
+**Google AI Studio**:
+1. Sign up at [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+2. Create an API key for Gemini/Gemma endpoints
+
+**SiliconFlow**:
+1. Sign up at [cloud.siliconflow.cn/account/ak](https://cloud.siliconflow.cn/account/ak)
+2. Create API key in Account → API Keys
+
+**Together AI**:
+1. Sign up at [api.together.ai/settings/api-keys](https://api.together.ai/settings/api-keys)
+2. Create an API key in Settings
+
+**Cloudflare Workers AI**:
+1. Sign up at [dash.cloudflare.com](https://dash.cloudflare.com)
+2. Create an API token with Workers AI permissions
+3. Export both `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`
+
+**Perplexity API**:
+1. Sign up at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
+2. Create API key (`PERPLEXITY_API_KEY`)
+
 > 💡 **Free tiers** — each provider exposes a dev/free tier with its own quotas.
 
 ---
 
 ## 🤖 Coding Models
 
-**111 coding models** across 13 providers and 8 tiers, ranked by [SWE-bench Verified](https://www.swebench.com) — the industry-standard benchmark measuring real GitHub issue resolution. Scores are self-reported by providers unless noted.
+**134 coding models** across 17 providers and 8 tiers, ranked by [SWE-bench Verified](https://www.swebench.com) — the industry-standard benchmark measuring real GitHub issue resolution. Scores are self-reported by providers unless noted.
 
 ### NVIDIA NIM (44 models)
 
@@ -323,7 +368,7 @@ When enabled, telemetry events include: event name, app version, selected mode,
 | **B** 20–30% | R1 Distill 8B (28.2%), R1 Distill 7B (22.6%) |
 | **C** <20% | Gemma 2 9B (18.0%), Phi 4 Mini (14.0%), Phi 3.5 Mini (12.0%) |
 
-### Groq (6 models)
+### Groq (10 models)
 
 | Tier | SWE-bench | Model |
 |------|-----------|-------|
@@ -332,7 +377,7 @@ When enabled, telemetry events include: event name, app version, selected mode,
 | **A** 40–50% | Llama 4 Scout (44.0%), R1 Distill 70B (43.9%) |
 | **A-** 35–40% | Llama 3.3 70B (39.5%) |
 
-### Cerebras (3 models)
+### Cerebras (7 models)
 
 | Tier | SWE-bench | Model |
 |------|-----------|-------|
@@ -578,6 +623,11 @@ This script:
 | `HYPERBOLIC_API_KEY` | Hyperbolic key |
 | `SCALEWAY_API_KEY` | Scaleway key |
 | `GOOGLE_API_KEY` | Google AI Studio key |
+| `SILICONFLOW_API_KEY` | SiliconFlow key |
+| `TOGETHER_API_KEY` | Together AI key |
+| `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_API_KEY` | Cloudflare Workers AI token/key |
+| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare account ID (required for Workers AI endpoint URL) |
+| `PERPLEXITY_API_KEY` / `PPLX_API_KEY` | Perplexity API key |
 | `FREE_CODING_MODELS_TELEMETRY` | `0` disables analytics, `1` enables analytics |
 | `FREE_CODING_MODELS_POSTHOG_KEY` | PostHog project API key used for anonymous event capture |
 | `FREE_CODING_MODELS_POSTHOG_HOST` | Optional PostHog ingest host (`https://eu.i.posthog.com` default) |
@@ -593,7 +643,11 @@ This script:
     "openrouter": "sk-or-xxx",
     "huggingface": "hf_xxx",
     "replicate": "r8_xxx",
-    "deepinfra": "di_xxx"
+    "deepinfra": "di_xxx",
+    "siliconflow": "sk_xxx",
+    "together": "together_xxx",
+    "cloudflare": "cf_xxx",
+    "perplexity": "pplx_xxx"
   },
   "providers": {
     "nvidia":   { "enabled": true },
@@ -602,8 +656,15 @@ This script:
     "openrouter": { "enabled": true },
     "huggingface": { "enabled": true },
     "replicate": { "enabled": true },
-    "deepinfra": { "enabled": true }
+    "deepinfra": { "enabled": true },
+    "siliconflow": { "enabled": true },
+    "together": { "enabled": true },
+    "cloudflare": { "enabled": true },
+    "perplexity": { "enabled": true }
   },
+  "favorites": [
+    "nvidia/deepseek-ai/deepseek-v3.2"
+  ],
   "telemetry": {
     "enabled": true,
     "consentVersion": 1,
@@ -637,18 +698,23 @@ This script:
 - **↑↓** — Navigate models
 - **Enter** — Select model (launches OpenCode or sets OpenClaw default, depending on mode)
 - **R/Y/O/M/L/A/S/N/H/V/U** — Sort by Rank/Tier/Origin/Model/LatestPing/Avg/SWE/Ctx/Health/Verdict/Uptime
+- **F** — Toggle favorite on selected model (⭐ in Model column, pinned at top)
 - **T** — Cycle tier filter (All → S+ → S → A+ → A → A- → B+ → B → C → All)
 - **Z** — Cycle mode (OpenCode CLI → OpenCode Desktop → OpenClaw)
-- **P** — Open Settings (manage API keys, provider toggles, analytics toggle)
+- **P** — Open Settings (manage API keys, provider toggles, analytics toggle, manual update)
 - **W** — Decrease ping interval (faster pings)
 - **X** — Increase ping interval (slower pings)
+- **K** / **Esc** — Show/hide help overlay
 - **Ctrl+C** — Exit
 
+Pressing **K** now shows a full in-app reference: main hotkeys, settings hotkeys, and CLI flags with usage examples.
+
 **Keyboard shortcuts (Settings screen — `P` key):**
-- **↑↓** — Navigate providers and analytics row
-- **Enter** — Edit API key inline, or toggle analytics on analytics row
+- **↑↓** — Navigate providers, analytics row, and maintenance row
+- **Enter** — Edit API key inline, toggle analytics on analytics row, or check/install update on maintenance row
 - **Space** — Toggle provider enabled/disabled, or toggle analytics on analytics row
 - **T** — Test current provider's API key (fires a live ping)
+- **U** — Check for updates manually from settings
 - **Esc** — Close settings and return to main TUI
 
 ---

package/bin/free-coding-models.js

@@ -20,7 +20,8 @@
  *   - 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/OpenRouter/Hugging Face/Replicate/DeepInfra/... — extensible)
- *   - Settings screen (P key) to manage API keys per provider, enable/disable, test keys
+ *   - 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,6 +33,7 @@
  *   - `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
+ *   - `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
  *   - `buildPingRequest` / `ping`: Build provider-specific probe requests and measure latency
@@ -58,7 +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, OPENROUTER_API_KEY, HUGGINGFACE_API_KEY/HF_TOKEN, REPLICATE_API_TOKEN, DEEPINFRA_API_KEY/DEEPINFRA_TOKEN, FIREWORKS_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, etc.
+ *   - 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
@@ -159,6 +162,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) {
@@ -416,14 +466,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) {
@@ -695,6 +756,52 @@ const FRAMES = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏']
 // 📖 Spinner cell: braille (1-wide) + padding to fill CELL_W visual chars
 const spinCell = (f, o = 0) => chalk.dim.yellow(FRAMES[(f + o) % FRAMES.length].padEnd(CELL_W))
 
+// 📖 Overlay-specific backgrounds so Settings (P) and Help (K) are visually distinct
+// 📖 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 OVERLAY_PANEL_WIDTH = 116
+
+// 📖 Strip ANSI color/control sequences to estimate visible text width before padding.
+function stripAnsi(input) {
+  return String(input).replace(/\x1b\[[0-9;]*m/g, '').replace(/\x1b\][^\x1b]*\x1b\\/g, '')
+}
+
+// 📖 Tint overlay lines with a fixed dark panel width so the background is clearly visible.
+function tintOverlayLines(lines, bgColor) {
+  return lines.map((line) => {
+    const text = String(line)
+    const visibleWidth = stripAnsi(text).length
+    const padding = ' '.repeat(Math.max(0, OVERLAY_PANEL_WIDTH - visibleWidth))
+    return bgColor(text + padding)
+  })
+}
+
+// 📖 Clamp overlay scroll to valid bounds for the current terminal height.
+function clampOverlayOffset(offset, totalLines, terminalRows) {
+  const viewportRows = Math.max(1, terminalRows || 1)
+  const maxOffset = Math.max(0, totalLines - viewportRows)
+  return Math.max(0, Math.min(maxOffset, offset))
+}
+
+// 📖 Ensure a target line is visible inside overlay viewport (used by Settings cursor).
+function keepOverlayTargetVisible(offset, targetLine, totalLines, terminalRows) {
+  const viewportRows = Math.max(1, terminalRows || 1)
+  let next = clampOverlayOffset(offset, totalLines, terminalRows)
+  if (targetLine < next) next = targetLine
+  else if (targetLine >= next + viewportRows) next = targetLine - viewportRows + 1
+  return clampOverlayOffset(next, totalLines, terminalRows)
+}
+
+// 📖 Slice overlay lines to terminal viewport and pad with blanks to avoid stale frames.
+function sliceOverlayLines(lines, offset, terminalRows) {
+  const viewportRows = Math.max(1, terminalRows || 1)
+  const nextOffset = clampOverlayOffset(offset, lines.length, terminalRows)
+  const visible = lines.slice(nextOffset, nextOffset + viewportRows)
+  while (visible.length < viewportRows) visible.push('')
+  return { visible, offset: nextOffset }
+}
+
 // ─── Table renderer ───────────────────────────────────────────────────────────
 
 // 📖 Core logic functions (getAvg, getVerdict, getUptime, sortResults, etc.)
@@ -723,6 +830,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
@@ -790,7 +907,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}   ` +
@@ -882,7 +999,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))
@@ -1012,8 +1132,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)
     }
@@ -1032,7 +1156,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\\') +
@@ -1062,6 +1186,15 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
 // 📖 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.
+function resolveCloudflareUrl(url) {
+  // 📖 Cloudflare's OpenAI-compatible endpoint is account-scoped.
+  // 📖 We resolve {account_id} from env so provider setup can stay simple in config.
+  const accountId = (process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()
+  if (!url.includes('{account_id}')) return url
+  if (!accountId) return url.replace('{account_id}', 'missing-account-id')
+  return url.replace('{account_id}', encodeURIComponent(accountId))
+}
+
 function buildPingRequest(apiKey, modelId, providerKey, url) {
   if (providerKey === 'replicate') {
     // 📖 Replicate uses /v1/predictions with a different payload than OpenAI chat-completions.
@@ -1074,6 +1207,17 @@ function buildPingRequest(apiKey, modelId, providerKey, url) {
     }
   }
 
+  if (providerKey === 'cloudflare') {
+    // 📖 Cloudflare Workers AI uses OpenAI-compatible payload but needs account_id in URL.
+    const headers = { 'Content-Type': 'application/json' }
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`
+    return {
+      url: resolveCloudflareUrl(url),
+      headers,
+      body: { model: modelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
+    }
+  }
+
   const headers = { 'Content-Type': 'application/json' }
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`
   if (providerKey === 'openrouter') {
@@ -1151,6 +1295,10 @@ const ENV_VAR_NAMES = {
   hyperbolic: 'HYPERBOLIC_API_KEY',
   scaleway:   'SCALEWAY_API_KEY',
   googleai:   'GOOGLE_API_KEY',
+  siliconflow:'SILICONFLOW_API_KEY',
+  together:   'TOGETHER_API_KEY',
+  cloudflare: 'CLOUDFLARE_API_TOKEN',
+  perplexity: 'PERPLEXITY_API_KEY',
 }
 
 // 📖 Provider metadata used by the setup wizard and Settings details panel.
@@ -1247,6 +1395,34 @@ const PROVIDER_METADATA = {
     signupHint: 'Get API key',
     rateLimits: '14.4K req/day, 30/min',
   },
+  siliconflow: {
+    label: 'SiliconFlow',
+    color: chalk.rgb(255, 120, 30),
+    signupUrl: 'https://cloud.siliconflow.cn/account/ak',
+    signupHint: 'API Keys → Create',
+    rateLimits: 'Free models: usually 100 RPM, varies by model',
+  },
+  together: {
+    label: 'Together AI',
+    color: chalk.rgb(0, 180, 255),
+    signupUrl: 'https://api.together.ai/settings/api-keys',
+    signupHint: 'Settings → API keys',
+    rateLimits: 'Credits/promos vary by account (check console)',
+  },
+  cloudflare: {
+    label: 'Cloudflare Workers AI',
+    color: chalk.rgb(242, 119, 36),
+    signupUrl: 'https://dash.cloudflare.com',
+    signupHint: 'Create AI API token + set CLOUDFLARE_ACCOUNT_ID',
+    rateLimits: 'Free: 10k neurons/day, text-gen 300 RPM',
+  },
+  perplexity: {
+    label: 'Perplexity API',
+    color: chalk.rgb(0, 210, 190),
+    signupUrl: 'https://www.perplexity.ai/settings/api',
+    signupHint: 'Generate API key (billing may be required)',
+    rateLimits: 'Tiered limits by spend (default ~50 RPM)',
+  },
 }
 
 // 📖 OpenCode config location varies by platform
@@ -1615,6 +1791,53 @@ After installation, you can use: opencode --model ${modelRef}`
           },
           models: {}
         }
+      } else if (providerKey === 'siliconflow') {
+        config.provider.siliconflow = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'SiliconFlow',
+          options: {
+            baseURL: 'https://api.siliconflow.com/v1',
+            apiKey: '{env:SILICONFLOW_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'together') {
+        config.provider.together = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Together AI',
+          options: {
+            baseURL: 'https://api.together.xyz/v1',
+            apiKey: '{env:TOGETHER_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'cloudflare') {
+        const cloudflareAccountId = (process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()
+        if (!cloudflareAccountId) {
+          console.log(chalk.yellow('  ⚠ Cloudflare Workers AI requires CLOUDFLARE_ACCOUNT_ID for OpenCode integration.'))
+          console.log(chalk.dim('    Export CLOUDFLARE_ACCOUNT_ID and retry this selection.'))
+          console.log()
+          return
+        }
+        config.provider.cloudflare = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Cloudflare Workers AI',
+          options: {
+            baseURL: `https://api.cloudflare.com/client/v4/accounts/${cloudflareAccountId}/ai/v1`,
+            apiKey: '{env:CLOUDFLARE_API_TOKEN}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'perplexity') {
+        config.provider.perplexity = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Perplexity API',
+          options: {
+            baseURL: 'https://api.perplexity.ai',
+            apiKey: '{env:PERPLEXITY_API_KEY}'
+          },
+          models: {}
+        }
       }
     }
 
@@ -2119,6 +2342,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))
@@ -2202,6 +2426,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.
@@ -2223,7 +2448,9 @@ async function main() {
       st.scrollOffset = st.cursor - modelSlots + 1
     }
     // Final clamp
-    const maxOffset = Math.max(0, total - maxSlots)
+    // 📖 Keep one extra scroll step when top indicator is visible,
+    // 📖 otherwise the last rows become unreachable at the bottom.
+    const maxOffset = Math.max(0, total - maxSlots + 1)
     if (st.scrollOffset > maxOffset) st.scrollOffset = maxOffset
     if (st.scrollOffset < 0) st.scrollOffset = 0
   }
@@ -2252,9 +2479,14 @@ 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
+    settingsScrollOffset: 0,      // 📖 Vertical scroll offset for Settings overlay viewport
+    helpScrollOffset: 0,          // 📖 Vertical scroll offset for Help overlay viewport
   }
 
   // 📖 Re-clamp viewport on terminal resize
@@ -2289,6 +2521,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
@@ -2305,8 +2542,10 @@ 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 = []
+    const cursorLineByRow = {}
 
     lines.push('')
     lines.push(`  ${chalk.bold('⚙  Settings')}  ${chalk.dim('— free-coding-models v' + LOCAL_VERSION)}`)
@@ -2349,6 +2588,7 @@ async function main() {
       const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
 
       const row = `${bullet}[ ${enabledBadge} ] ${providerName}  ${keyDisplay.padEnd(30)}  ${testBadge}  ${rateSummary}`
+      cursorLineByRow[i] = lines.length
       lines.push(isCursor ? chalk.bgRgb(30, 30, 60)(row) : row)
     }
 
@@ -2363,6 +2603,11 @@ async function main() {
       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}`))
+      if (selectedProviderKey === 'cloudflare') {
+        const hasAccountId = Boolean((process.env.CLOUDFLARE_ACCOUNT_ID || '').trim())
+        const accountIdStatus = hasAccountId ? chalk.green('CLOUDFLARE_ACCOUNT_ID detected ✅') : chalk.yellow('Set CLOUDFLARE_ACCOUNT_ID ⚠')
+        lines.push(chalk.dim(`  4) Export ${chalk.yellow('CLOUDFLARE_ACCOUNT_ID')} in your shell. Status: ${accountIdStatus}`))
+      }
       lines.push('')
     }
 
@@ -2379,19 +2624,55 @@ async function main() {
       ? chalk.dim('[Config]')
       : chalk.yellow('[Env override]')
     const telemetryRow = `${telemetryRowBullet}${chalk.bold('Anonymous usage analytics').padEnd(44)} ${telemetryStatus}  ${telemetrySource}`
+    cursorLineByRow[telemetryRowIdx] = lines.length
     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}`
+    cursorLineByRow[updateRowIdx] = lines.length
+    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('')
 
-    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)
+    // 📖 Keep selected Settings row visible on small terminals by scrolling the overlay viewport.
+    const targetLine = cursorLineByRow[state.settingsCursor] ?? 0
+    state.settingsScrollOffset = keepOverlayTargetVisible(
+      state.settingsScrollOffset,
+      targetLine,
+      lines.length,
+      state.terminalRows
+    )
+    const { visible, offset } = sliceOverlayLines(lines, state.settingsScrollOffset, state.terminalRows)
+    state.settingsScrollOffset = offset
+
+    const tintedLines = tintOverlayLines(visible, SETTINGS_OVERLAY_BG)
+    const cleared = tintedLines.map(l => l + EL)
     return cleared.join('\n')
   }
 
@@ -2402,8 +2683,9 @@ async function main() {
     const EL = '\x1b[K'
     const lines = []
     lines.push('')
-    lines.push(`  ${chalk.bold('❓ Keyboard Shortcuts')}  ${chalk.dim('— press K or Esc to close')}`)
+    lines.push(`  ${chalk.bold('❓ Keyboard Shortcuts')}  ${chalk.dim('— ↑↓ / PgUp / PgDn / Home / End scroll • K or Esc 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`)
@@ -2421,13 +2703,37 @@ 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('')
-    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)
+    lines.push(`  ${chalk.bold('Settings (P)')}`)
+    lines.push(`  ${chalk.yellow('↑↓')}           Navigate rows`)
+    lines.push(`  ${chalk.yellow('PgUp/PgDn')}    Jump by page`)
+    lines.push(`  ${chalk.yellow('Home/End')}     Jump first/last row`)
+    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('')
+    // 📖 Help overlay can be longer than viewport, so keep a dedicated scroll offset.
+    const { visible, offset } = sliceOverlayLines(lines, state.helpScrollOffset, state.terminalRows)
+    state.helpScrollOffset = offset
+    const tintedLines = tintOverlayLines(visible, HELP_OVERLAY_BG)
+    const cleared = tintedLines.map(l => l + EL)
     return cleared.join('\n')
   }
 
@@ -2448,11 +2754,47 @@ async function main() {
     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)
     })
   }
 
@@ -2466,9 +2808,20 @@ async function main() {
   const onKeyPress = async (str, key) => {
     if (!key) return
 
-    // 📖 Help overlay: Esc or K closes it — handle before everything else so Esc isn't swallowed elsewhere
-    if (state.helpVisible && (key.name === 'escape' || key.name === 'k')) {
-      state.helpVisible = false
+    // 📖 Help overlay: full keyboard navigation + key swallowing while overlay is open.
+    if (state.helpVisible) {
+      const pageStep = Math.max(1, (state.terminalRows || 1) - 2)
+      if (key.name === 'escape' || key.name === 'k') {
+        state.helpVisible = false
+        return
+      }
+      if (key.name === 'up') { state.helpScrollOffset = Math.max(0, state.helpScrollOffset - 1); return }
+      if (key.name === 'down') { state.helpScrollOffset += 1; return }
+      if (key.name === 'pageup') { state.helpScrollOffset = Math.max(0, state.helpScrollOffset - pageStep); return }
+      if (key.name === 'pagedown') { state.helpScrollOffset += pageStep; return }
+      if (key.name === 'home') { state.helpScrollOffset = 0; return }
+      if (key.name === 'end') { state.helpScrollOffset = Number.MAX_SAFE_INTEGER; return }
+      if (key.ctrl && key.name === 'c') { exit(0); return }
       return
     }
 
@@ -2476,6 +2829,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) {
@@ -2518,6 +2872,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
@@ -2537,11 +2896,33 @@ async function main() {
         return
       }
 
-      if (key.name === 'down' && state.settingsCursor < telemetryRowIdx) {
+      if (key.name === 'down' && state.settingsCursor < updateRowIdx) {
         state.settingsCursor++
         return
       }
 
+      if (key.name === 'pageup') {
+        const pageStep = Math.max(1, (state.terminalRows || 1) - 2)
+        state.settingsCursor = Math.max(0, state.settingsCursor - pageStep)
+        return
+      }
+
+      if (key.name === 'pagedown') {
+        const pageStep = Math.max(1, (state.terminalRows || 1) - 2)
+        state.settingsCursor = Math.min(updateRowIdx, state.settingsCursor + pageStep)
+        return
+      }
+
+      if (key.name === 'home') {
+        state.settingsCursor = 0
+        return
+      }
+
+      if (key.name === 'end') {
+        state.settingsCursor = updateRowIdx
+        return
+      }
+
       if (key.name === 'return') {
         if (state.settingsCursor === telemetryRowIdx) {
           ensureTelemetryConfig(state.config)
@@ -2550,6 +2931,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]
@@ -2566,6 +2955,7 @@ async function main() {
           saveConfig(state.config)
           return
         }
+        if (state.settingsCursor === updateRowIdx) return
 
         // 📖 Toggle enabled/disabled for selected provider
         const pk = providerKeys[state.settingsCursor]
@@ -2577,7 +2967,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]
@@ -2585,6 +2975,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
     }
@@ -2595,6 +2990,7 @@ async function main() {
       state.settingsCursor = 0
       state.settingsEditMode = false
       state.settingsEditBuffer = ''
+      state.settingsScrollOffset = 0
       return
     }
 
@@ -2617,12 +3013,38 @@ 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
+      const wasFavorite = selected.isFavorite
+      toggleFavoriteModel(state.config, selected.providerKey, selected.modelId)
+      syncFavoriteFlags(state.results, state.config)
+      applyTierFilter()
+      const visible = state.results.filter(r => !r.hidden)
+      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+
+      // 📖 UX rule: when unpinning a favorite, jump back to the top of the list.
+      if (wasFavorite) {
+        state.cursor = 0
+        state.scrollOffset = 0
+        return
+      }
+
+      const selectedKey = toFavoriteKey(selected.providerKey, selected.modelId)
+      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') {
@@ -2637,7 +3059,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
@@ -2649,7 +3071,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
@@ -2658,6 +3080,7 @@ async function main() {
     // 📖 Help overlay key: K = toggle help overlay
     if (key.name === 'k') {
       state.helpVisible = !state.helpVisible
+      if (state.helpVisible) state.helpScrollOffset = 0
       return
     }
 
@@ -2676,18 +3099,20 @@ async function main() {
     }
 
     if (key.name === 'up') {
-      if (state.cursor > 0) {
-        state.cursor--
-        adjustScrollOffset(state)
-      }
+      // 📖 Main list wrap navigation: top -> bottom on Up.
+      const count = state.visibleSorted.length
+      if (count === 0) return
+      state.cursor = state.cursor > 0 ? state.cursor - 1 : count - 1
+      adjustScrollOffset(state)
       return
     }
 
     if (key.name === 'down') {
-      if (state.cursor < state.visibleSorted.length - 1) {
-        state.cursor++
-        adjustScrollOffset(state)
-      }
+      // 📖 Main list wrap navigation: bottom -> top on Down.
+      const count = state.visibleSorted.length
+      if (count === 0) return
+      state.cursor = state.cursor < count - 1 ? state.cursor + 1 : 0
+      adjustScrollOffset(state)
       return
     }
 
@@ -2759,7 +3184,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()
@@ -2771,7 +3196,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))
 

package/lib/config.js

@@ -24,7 +24,11 @@
  *       "codestral":  "csk-xxx",
  *       "hyperbolic": "eyJ...",
  *       "scaleway":   "scw-xxx",
- *       "googleai":   "AIza..."
+ *       "googleai":   "AIza...",
+ *       "siliconflow":"sk-xxx",
+ *       "together":   "together-xxx",
+ *       "cloudflare": "cf-xxx",
+ *       "perplexity": "pplx-xxx"
  *     },
  *     "providers": {
  *       "nvidia":     { "enabled": true },
@@ -39,7 +43,14 @@
  *       "codestral":  { "enabled": true },
  *       "hyperbolic": { "enabled": true },
  *       "scaleway":   { "enabled": true },
- *       "googleai":   { "enabled": true }
+ *       "googleai":   { "enabled": true },
+ *       "siliconflow":{ "enabled": true },
+ *       "together":   { "enabled": true },
+ *       "cloudflare": { "enabled": true },
+ *       "perplexity": { "enabled": true }
+ *     },
+ *     "favorites": [
+ *       "nvidia/deepseek-ai/deepseek-v3.2"
  *     },
  *     "telemetry": {
  *       "enabled": true,
@@ -56,6 +67,7 @@
  *   → loadConfig() — Read ~/.free-coding-models.json; auto-migrate old plain-text config if needed
  *   → saveConfig(config) — Write config to ~/.free-coding-models.json with 0o600 permissions
  *   → getApiKey(config, providerKey) — Get effective API key (env var override > config > null)
+ *   → isProviderEnabled(config, providerKey) — Check if provider is enabled (defaults true)
  *
  * @exports loadConfig, saveConfig, getApiKey
  * @exports CONFIG_PATH — path to the JSON config file
@@ -90,6 +102,10 @@ const ENV_VARS = {
   hyperbolic: 'HYPERBOLIC_API_KEY',
   scaleway:   'SCALEWAY_API_KEY',
   googleai:   'GOOGLE_API_KEY',
+  siliconflow:'SILICONFLOW_API_KEY',
+  together:   'TOGETHER_API_KEY',
+  cloudflare: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_API_KEY'],
+  perplexity: ['PERPLEXITY_API_KEY', 'PPLX_API_KEY'],
 }
 
 /**
@@ -103,7 +119,7 @@ const ENV_VARS = {
  * 📖 The migration reads the old file as a plain nvidia API key and writes
  *    a proper JSON config. The old file is NOT deleted (safety first).
  *
- * @returns {{ apiKeys: Record<string,string>, providers: Record<string,{enabled:boolean}>, telemetry: { enabled: boolean | null, consentVersion: number, anonymousId: string | null } }}
+ * @returns {{ apiKeys: Record<string,string>, providers: Record<string,{enabled:boolean}>, favorites: string[], telemetry: { enabled: boolean | null, consentVersion: number, anonymousId: string | null } }}
  */
 export function loadConfig() {
   // 📖 Try new JSON config first
@@ -114,6 +130,9 @@ export function loadConfig() {
       // 📖 Ensure the shape is always complete — fill missing sections with defaults
       if (!parsed.apiKeys) parsed.apiKeys = {}
       if (!parsed.providers) parsed.providers = {}
+      // 📖 Favorites: list of "providerKey/modelId" pinned rows.
+      if (!Array.isArray(parsed.favorites)) parsed.favorites = []
+      parsed.favorites = parsed.favorites.filter((fav) => typeof fav === 'string' && fav.trim().length > 0)
       if (!parsed.telemetry || typeof parsed.telemetry !== 'object') parsed.telemetry = { enabled: null, consentVersion: 0, anonymousId: null }
       if (typeof parsed.telemetry.enabled !== 'boolean') parsed.telemetry.enabled = null
       if (typeof parsed.telemetry.consentVersion !== 'number') parsed.telemetry.consentVersion = 0
@@ -150,7 +169,7 @@ export function loadConfig() {
  * 📖 Uses mode 0o600 so the file is only readable by the owning user (API keys!).
  * 📖 Pretty-prints JSON for human readability.
  *
- * @param {{ apiKeys: Record<string,string>, providers: Record<string,{enabled:boolean}>, telemetry?: { enabled?: boolean | null, consentVersion?: number, anonymousId?: string | null } }} config
+ * @param {{ apiKeys: Record<string,string>, providers: Record<string,{enabled:boolean}>, favorites?: string[], telemetry?: { enabled?: boolean | null, consentVersion?: number, anonymousId?: string | null } }} config
  */
 export function saveConfig(config) {
   try {
@@ -208,6 +227,8 @@ function _emptyConfig() {
   return {
     apiKeys: {},
     providers: {},
+    // 📖 Pinned favorites rendered at top of the table ("providerKey/modelId").
+    favorites: [],
     // 📖 Telemetry consent is explicit. null = not decided yet.
     telemetry: {
       enabled: null,

package/package.json

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

package/sources.js

@@ -27,8 +27,8 @@
  *   📖 Secondary: https://swe-rebench.com (independent evals, scores are lower)
  *   📖 Leaderboard tracker: https://www.marc0.dev/en/leaderboard
  *
- *   @exports nvidiaNim, groq, cerebras, sambanova, openrouter, huggingface, replicate, deepinfra, fireworks, codestral, hyperbolic, scaleway, googleai — model arrays per provider
- *   @exports sources — map of { nvidia, groq, cerebras, sambanova, openrouter, huggingface, replicate, deepinfra, fireworks, codestral, hyperbolic, scaleway, googleai } each with { name, url, models }
+ *   @exports nvidiaNim, groq, cerebras, sambanova, openrouter, huggingface, replicate, deepinfra, fireworks, codestral, hyperbolic, scaleway, googleai, siliconflow, together, cloudflare, perplexity — model arrays per provider
+ *   @exports sources — map of { nvidia, groq, cerebras, sambanova, openrouter, huggingface, replicate, deepinfra, fireworks, codestral, hyperbolic, scaleway, googleai, siliconflow, together, cloudflare, perplexity } each with { name, url, models }
  *   @exports MODELS — flat array of [modelId, label, tier, sweScore, ctx, providerKey]
  *
  *   📖 MODELS now includes providerKey as 6th element so ping() knows which
@@ -230,6 +230,54 @@ export const googleai = [
   ['gemma-3-4b-it',                            'Gemma 3 4B',         'C',  '10.0%', '128k'],
 ]
 
+// 📖 SiliconFlow source - https://cloud.siliconflow.cn
+// 📖 OpenAI-compatible endpoint: https://api.siliconflow.com/v1/chat/completions
+// 📖 Free model quotas vary by model and can change over time.
+export const siliconflow = [
+  ['Qwen/Qwen3-Coder-480B-A35B-Instruct',      'Qwen3 Coder 480B',   'S+', '70.6%', '256k'],
+  ['deepseek-ai/DeepSeek-V3.2',                'DeepSeek V3.2',      'S+', '73.1%', '128k'],
+  ['Qwen/Qwen3-235B-A22B',                     'Qwen3 235B',         'S+', '70.0%', '128k'],
+  ['deepseek-ai/DeepSeek-R1',                  'DeepSeek R1',        'S',  '61.0%', '128k'],
+  ['Qwen/Qwen3-Coder-30B-A3B-Instruct',        'Qwen3 Coder 30B',    'A+', '55.0%', '32k'],
+  ['Qwen/Qwen2.5-Coder-32B-Instruct',          'Qwen2.5 Coder 32B',  'A',  '46.0%', '32k'],
+]
+
+// 📖 Together AI source - https://api.together.ai
+// 📖 OpenAI-compatible endpoint: https://api.together.xyz/v1/chat/completions
+// 📖 Credits/promotions vary by account and region; verify current quota in console.
+export const together = [
+  ['moonshotai/Kimi-K2.5',                     'Kimi K2.5',          'S+', '76.8%', '128k'],
+  ['Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8',  'Qwen3 Coder 480B',   'S+', '70.6%', '256k'],
+  ['deepseek-ai/DeepSeek-V3.1',                'DeepSeek V3.1',      'S',  '62.0%', '128k'],
+  ['deepseek-ai/DeepSeek-R1',                  'DeepSeek R1',        'S',  '61.0%', '128k'],
+  ['openai/gpt-oss-120b',                      'GPT OSS 120B',       'S',  '60.0%', '128k'],
+  ['openai/gpt-oss-20b',                       'GPT OSS 20B',        'A',  '42.0%', '128k'],
+  ['meta-llama/Llama-3.3-70B-Instruct-Turbo',  'Llama 3.3 70B',      'A-', '39.5%', '128k'],
+]
+
+// 📖 Cloudflare Workers AI source - https://developers.cloudflare.com/workers-ai
+// 📖 OpenAI-compatible endpoint requires account id:
+// 📖 https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1/chat/completions
+// 📖 Free plan includes daily neuron quota and provider-level request limits.
+export const cloudflare = [
+  ['@cf/openai/gpt-oss-120b',                  'GPT OSS 120B',       'S',  '60.0%', '128k'],
+  ['@cf/qwen/qwen2.5-coder-32b-instruct',      'Qwen2.5 Coder 32B',  'A',  '46.0%', '32k'],
+  ['@cf/deepseek-ai/deepseek-r1-distill-qwen-32b', 'R1 Distill 32B', 'A',  '43.9%', '128k'],
+  ['@cf/openai/gpt-oss-20b',                   'GPT OSS 20B',        'A',  '42.0%', '128k'],
+  ['@cf/meta/llama-3.3-70b-instruct-fp8-fast', 'Llama 3.3 70B',      'A-', '39.5%', '128k'],
+  ['@cf/meta/llama-3.1-8b-instruct',           'Llama 3.1 8B',       'B',  '28.8%', '128k'],
+]
+
+// 📖 Perplexity source - https://docs.perplexity.ai
+// 📖 Chat Completions endpoint: https://api.perplexity.ai/chat/completions
+// 📖 Sonar models focus on search/reasoning and have tiered API rate limits.
+export const perplexity = [
+  ['sonar-reasoning-pro',                      'Sonar Reasoning Pro', 'A+', '50.0%', '128k'],
+  ['sonar-reasoning',                          'Sonar Reasoning',     'A',  '45.0%', '128k'],
+  ['sonar-pro',                                'Sonar Pro',           'B+', '32.0%', '128k'],
+  ['sonar',                                    'Sonar',               'B',  '25.0%', '128k'],
+]
+
 // 📖 All sources combined - used by the main script
 // 📖 Each source has: name (display), url (API endpoint), models (array of model tuples)
 export const sources = {
@@ -298,6 +346,26 @@ export const sources = {
     url: 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions',
     models: googleai,
   },
+  siliconflow: {
+    name: 'SiliconFlow',
+    url: 'https://api.siliconflow.com/v1/chat/completions',
+    models: siliconflow,
+  },
+  together: {
+    name: 'Together AI',
+    url: 'https://api.together.xyz/v1/chat/completions',
+    models: together,
+  },
+  cloudflare: {
+    name: 'Cloudflare AI',
+    url: 'https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1/chat/completions',
+    models: cloudflare,
+  },
+  perplexity: {
+    name: 'Perplexity',
+    url: 'https://api.perplexity.ai/chat/completions',
+    models: perplexity,
+  },
 }
 
 // 📖 Flatten all models from all sources — each entry includes providerKey as 6th element