free-coding-models 0.5.1 → 0.5.5

package/README.md

@@ -9,14 +9,14 @@
   Track ~153 models across 16 trusted free or free-limited AI providers in real time<br><br>
   <strong>Install Free API endpoints to your favorite AI coding tools:</strong><br>
   OpenCode CLI / Desktop / WebUI, OpenClaw, Crush, Goose, Aider, Kilo CLI, Qwen Code, OpenHands, Amp, Hermes, Continue, Cline, Xcode, Pi, Rovo, Gemini and more...<br><br>
-  <strong>Use Kimi K2, DeepSeek V3, GPT-OSS, Qwen3, MiniMax M2, GLM, Llama 4, Gemma 4, Devstral and more — for free</strong>
+  <strong>Use Kimi K2, DeepSeek V3, GPT-OSS, Qwen3, MiniMax M3, GLM, Llama 4, Gemma 4, Devstral and more — for free</strong>
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/free-coding-models?color=3d6b00&label=npm&logo=npm" alt="npm version" width="200"><br>
   <img src="https://img.shields.io/node/v/free-coding-models?color=3d6b00&logo=node.js" alt="node version" width="200"><br>
   <img src="https://img.shields.io/npm/l/free-coding-models?color=3d6b00" alt="license" width="200"><br>
-  <img src="https://img.shields.io/badge/models-153+-3d6b00?logo=nvidia" alt="models count" width="200"><br>
+  <img src="https://img.shields.io/badge/models-154+-3d6b00?logo=nvidia" alt="models count" width="200"><br>
   <img src="https://img.shields.io/badge/providers-16-1a56db" alt="providers count" width="200">
 </p>
 
@@ -155,6 +155,31 @@ free-coding-models web
 
 This starts the realtime Web Dashboard locally, opens it in your browser, and uses `http://localhost:3333/` by default. Override the port with `FCM_WEB_PORT=3334 free-coding-models web`.
 
+#### Web Dashboard features (M1 parity with TUI)
+
+The local Web Dashboard is a real-time control center for the model catalog
+— not just a static table. The header holds every navigation entry, the
+model table uses **100% of the viewport width** (no left rail, no right rail),
+and every TUI capability that's safe to port ships behind a button or chip.
+
+| Area | What's there |
+|---|---|
+| **Header** | Logo + version · primary nav (Dashboard, Settings, Analytics, Recommend, Router) · kebab menu (Help, Changelog, Install Endpoints, Installed Models) · `⌘K` command palette · AI Latency · theme · export |
+| **Model table** | Full-bleed (no left/right border, no margin) under the sticky header + filter bar · 16 columns, resizable widths persisted in localStorage, ⭐ star per row, medal borders for top-3, dark-red row class for tool-incompatible models, click AI Lat. cell to run a per-row benchmark · table header row stays sticky while scrolling |
+| **Filter bar** | Sticky right below the header (always visible) · Tier / Status / Verdict / Health chip rows · Visibility dropdown (Normal / Configured only / Usable only) · Provider select · custom text filter chip with `X` clear · Reset button (TUI `N`) · ping mode (Speed / Normal / Slow / Forced) · "next ping in Xs" countdown (TUI style, always shown) |
+| **Stats bar** | Removed in M1 (users found it noisy; the table + chips carry the same info at a glance) |
+| **Detail panel** | Slide-in from the right on row click · per-row benchmark button (TUI `Ctrl+A`) · favorite toggle (TUI `F`) + up/down reorder (TUI `Shift+↑↓`) · latency trend chart · all stats |
+| **Command palette** | `⌘K` / `Ctrl+P` (the only global keyboard shortcut) · fuzzy search across views, theme, ping mode, reset, export |
+| **Keyboard** | `Esc` closes any modal · `Cmd+K` toggles the palette — that's it. Everything else is mouse-first. |
+| **URL deep-linking** | `?tier=S+&sort=verdict&origin=groq&view=dashboard&q=…` hydrates the dashboard on load. CLI flags become shareable links. |
+| **Favorites** | Shared with the TUI through `~/.free-coding-models.json` — a star in the Web is a star in the TUI. Includes pinned+sticky display mode (TUI `Y`). |
+| **Theme** | Tri-state `auto / dark / light` cycle (TUI `G`) — auto follows the OS preference. |
+
+Roadmap items (header menu badges show "M2 / M3 / M4" until they land):
+- **M2** — Help modal, Changelog viewer, Settings parity (theme toggle, test key, shell-env, legacy cleanup, startup AI scan), Update flow, URL write-back, full command palette backed by the TUI registry.
+- **M3** — Smart Recommend (3-question wizard → 10s analysis → Top 3), tool mode picker, per-row Launch, missing-tool install prompt, incompatible-fallback modal.
+- **M4** — Router Dashboard, Token Usage, Install Endpoints wizard, Installed Models manager.
+
 ### Available Image Tags
 
 | Tag | Description |
@@ -387,7 +412,7 @@ Press **`Z`** in the TUI to cycle between tools without restarting.
 
 ### OpenCode Zen Free Models
 
-[OpenCode Zen](https://opencode.ai/zen) is a hosted AI gateway offering **4 free coding models** exclusively through OpenCode CLI and OpenCode Desktop. These models are **not** available through other tools.
+[OpenCode Zen](https://opencode.ai/zen) is a hosted AI gateway offering **5 free coding models** exclusively through OpenCode CLI and OpenCode Desktop. These models are **not** available through other tools.
 
 | Model | Tier | SWE-bench | Context |
 |-------|------|-----------|---------|
@@ -395,6 +420,7 @@ Press **`Z`** in the TUI to cycle between tools without restarting.
 | DeepSeek V4 Flash Free | S+ | 79.0% | 200k |
 | MiMo-V2.5 Free | S+ | - | 200k |
 | Nemotron 3 Super Free | A+ | 52.0% | 200k |
+| MiniMax M3 Free | S+ | 59.0% | 1M |
 
 To use Zen models: sign up at [opencode.ai/auth](https://opencode.ai/auth) and enter your Zen API key via `P` (Settings). Zen models appear in the main table and auto-switch to OpenCode CLI on launch.
 
@@ -522,9 +548,9 @@ For every model in this tool, **you own the generated output** — code, text, o
 | **Llama Community License** | Llama 3.3 70B, Llama 4 Scout/Maverick | ✅ Attribution required. >700M MAU → separate Meta license |
 | **DeepSeek License** | DeepSeek V3/V3.1/V3.2/V4 family | ✅ Use restrictions on model (no military, no harm) — output is yours |
 | **NVIDIA Nemotron License** | Nemotron Super/Ultra/Nano | ✅ Updated Mar 2026, now near-Apache 2.0 permissive |
-| **MiniMax Model License** | MiniMax M2, M2.5 | ✅ Royalty-free, non-exclusive. Prohibited uses policy applies to model |
+| **MiniMax Model License** | MiniMax M2, M2.5, M3 | ✅ Royalty-free, non-exclusive. Prohibited uses policy applies to model |
 | **Proprietary / hosted API terms** | Gemini, GitHub Models, Mistral/Codestral, OpenRouter-hosted models | ✅ Provider ToS applies |
-| **OpenCode Zen** | Big Pickle, GPT 5 Nano, MiniMax M2.5 Free, Nemotron 3 Super Free, HY3/Ling/Trinity previews | ✅ Per OpenCode Zen ToS |
+| **OpenCode Zen** | Big Pickle, GPT 5 Nano, MiniMax M3 Free, Nemotron 3 Super Free, HY3/Ling/Trinity previews | ✅ Per OpenCode Zen ToS |
 
 ### Key Points
 

package/bin/free-coding-models.js

@@ -11,11 +11,12 @@ if (process.argv.includes('--dev')) {
 
 import chalk from 'chalk';
 import { parseArgs, TIER_LETTER_MAP } from '../src/core/utils.js';
-import { loadConfig } from '../src/core/config.js';
+import { loadConfig, saveConfig } from '../src/core/config.js';
 import { ensureTelemetryConfig } from '../src/core/telemetry.js';
 import { ensureFavoritesConfig } from '../src/core/favorites.js';
 import { buildCliHelpText } from '../src/tui/cli-help.js';
 import { ALT_LEAVE } from '../src/core/constants.js';
+import { enforceMandatoryStartupUpdate, isPackageDevMode } from '../src/core/updater.js';
 import { runApp } from '../src/tui/app.js';
 
 // Global error handlers to ensure terminal is restored if something crashes catastrophically
@@ -53,13 +54,32 @@ async function main() {
     process.exit(0);
   }
 
+  // Load JSON config before operational modes so the mandatory update policy can
+  // 📖 persist failure counters for TUI, Web Dashboard, Docker daemon, and Desktop sidecar launches.
+  const config = loadConfig();
+  ensureTelemetryConfig(config);
+  ensureFavoritesConfig(config);
+
+  const isDevMode = isPackageDevMode();
+  const shouldEnforceUpdate = !cliArgs.daemonStopMode && !cliArgs.daemonStatusMode;
+  const startupUpdate = shouldEnforceUpdate
+    ? await enforceMandatoryStartupUpdate(config, {
+      saveConfig,
+      isDevMode,
+      surface: cliArgs.webMode ? 'web dashboard' : cliArgs.daemonMode ? 'router daemon' : 'TUI',
+    })
+    : { latestVersion: null, allowedOutdated: false, warningMessage: null, failures: 0, checked: false, updated: false, blocked: false };
+
+  if (startupUpdate.updated) return;
+  if (startupUpdate.blocked) process.exit(1);
+
   // 📖 Standalone web dashboard: same full-catalog ping UI as the TUI, served
   // 📖 locally with Socket.IO/SSE/REST realtime updates.
   if (cliArgs.webMode) {
     const { startWebServer } = await import('../web/server.js');
     const parsedPort = Number.parseInt(process.env.FCM_WEB_PORT || process.env.FCM_PORT || '3333', 10);
     const port = Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : 3333;
-    await startWebServer(port, { open: true, startPingLoop: true });
+    await startWebServer(port, { open: true, startPingLoop: true, updateStatus: startupUpdate });
     return;
   }
 
@@ -102,12 +122,7 @@ async function main() {
     process.exit(1);
   }
 
-  // Load JSON config
-  const config = loadConfig();
-  ensureTelemetryConfig(config);
-  ensureFavoritesConfig(config);
-
-  await runApp(cliArgs, config);
+  await runApp(cliArgs, config, { startupUpdate, isDevMode });
 }
 
 main().catch((err) => {

package/changelog/v0.5.4.md

@@ -0,0 +1,24 @@
+# Changelog v0.5.4 - 2026-06-01
+
+### Added
+- Added `minimax-m3-free` to the OpenCode Zen provider — **MiniMax M3 Free**, the flagship free Zen coding model with **1M token context** and MiniMax Sparse Attention for long-context inference.
+- Added the MiniMax M3 model license row to the README license breakdown table, covering M2, M2.5, and M3 under the same permissive royalty-free terms.
+- Added the Web Dashboard favicon/PWA asset pipeline: `icon.png` is now the single source of truth for classic `.ico`, browser PNG sizes, Apple touch icon, Android/PWA icons, Microsoft tiles, `site.webmanifest`, and `browserconfig.xml`.
+- Added provider logo assets and Web Dashboard atoms for provider wordmarks, the `NO KEY` icon, resizable persisted table columns, and stronger health/status iconography.
+
+### Changed
+- Merged the unreleased `0.5.2` and failed `0.5.3` release notes into this real `0.5.4` release so GitHub Releases and npm history match what actually shipped.
+- Updated the OpenCode Zen README section to list 5 free models and bumped the catalog badge to `154+ models`.
+- Updated the README hero to reference **MiniMax M3** as a headline supported model.
+- Improved Web Dashboard light-theme contrast across latency, TPS, tier, verdict, health, stability, sparkline, status dot, toast, and analytics chart visuals.
+- Improved Web Dashboard model table polish with provider logos, an explicit missing-key icon, and column sizing persistence through `localStorage`.
+
+### Fixed
+- Fixed the npm release workflow failure from `build:favicons`: CI installed ImageMagick, but Ubuntu exposes the v6 `convert` binary while the script only searched for the v7 `magick` binary. The script now supports both `magick` and `convert`.
+- Fixed the Docker image workflow so it installs ImageMagick before running `pnpm build:web`; tag-triggered Docker publishing now has the same prerequisite as npm publishing.
+- Fixed the release pre-flight health check so an empty/truncated GitHub Status response becomes `unknown` instead of crashing the workflow before checkout.
+- Fixed the commit-log Discord workflow so multiline commit bodies containing apostrophes or quotes no longer break shell parsing.
+- Kept generated favicon files in `web/public/` so the published npm tarball and Docker image contain the expected dashboard icons.
+
+### Why
+Versions `0.5.2` and `0.5.3` never reached npm/GitHub Release successfully, so `0.5.4` is the consolidation release: it ships the MiniMax M3 catalog update, the Web Dashboard visual/icon polish, and the CI fixes needed for npm + Docker publishing to complete reliably.

package/changelog/v0.5.5.md

@@ -0,0 +1,15 @@
+# Changelog v0.5.5 - 2026-06-01
+
+### Changed
+- ⬆️ **deps-dev**: bump `vite` from `8.0.14` → `8.0.16` (#105)
+- ⬆️ **deps-dev**: bump `vite-plus` from `0.1.20` → `0.1.23` (#106)
+- ⬆️ **deps-dev**: bump `@vitejs/plugin-react` from `6.0.1` → `6.0.2` (#107)
+
+### CI
+- ⬆️ bump `docker/setup-buildx-action` from `3` → `4` (#104)
+- ⬆️ bump `docker/login-action` from `3` → `4` (#103)
+- ⬆️ bump `pnpm/action-setup` from `4` → `6` (#102)
+
+### Notes
+- All 6 dependabot PRs merged in a single batch with conflict resolution on `pnpm-lock.yaml`.
+- 440/440 tests passing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.1",
+  "version": "0.5.5",
   "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",
@@ -42,6 +42,8 @@
     "bin/",
     "src/",
     "web/",
+    "!web/node_modules/",
+    "!web/node_modules/**",
     "sources.js",
     "patch-openclaw.js",
     "patch-openclaw-models.js",
@@ -55,7 +57,8 @@
     "prepack": "npm run build:web",
     "dev": "node scripts/dev-web.mjs",
     "dev:web": "node scripts/dev-web.mjs",
-    "build:web": "vite build",
+    "build:favicons": "node scripts/build-favicons.mjs",
+    "build:web": "npm run build:favicons && vite build",
     "preview:web": "vite preview",
     "test:fcm": "node scripts/testfcm-runner.mjs",
     "test:fcm:mock": "node scripts/testfcm-runner.mjs --tool crush --tool-bin-dir test/fixtures/mock-bin"

package/sources.js

@@ -360,6 +360,7 @@ export const opencodeZen = [
   ['deepseek-v4-flash-free',           'DeepSeek V4 Flash Free',  'S+', '79.0%', '200k'],
   ['mimo-v2.5-free',                   'MiMo-V2.5 Free',          'S+', '-',     '200k'],
   ['nemotron-3-super-free',            'Nemotron 3 Super Free',   'A+', '52.0%', '200k'],
+  ['minimax-m3-free',                  'MiniMax M3 Free',         'S+', '59.0%', '1M'],
   // Removed (2026-05-28): qwen3.6-plus-free (free promotion ended — now requires OpenCode Go)
   // Removed (2026-05-28): minimax-m2.5-free (7-day launch promo expired — now paid)
   // Removed (2026-05-28): gpt-5-nano (was never free — incorrectly cataloged as free, requires Zen PAYG)
@@ -368,6 +369,7 @@ export const opencodeZen = [
   // Removed (2026-05-26): trinity-mini-free (deleted from Zen)
   // Removed (2026-05-26): trinity-large-preview-free (deleted from Zen)
   // Fix (2026-05-26): nematron-3-super-free ctx 1M → 200k (Zen limits it)
+  // Added (2026-06-01): minimax-m3-free — MiniMax M3, 1M context, MSA attention (SWE-Bench Pro 59.0%)
 ]
 
 // 📖 All sources combined - used by the main script

package/src/core/updater.js

@@ -32,22 +32,29 @@
  *   → getManualInstallCmd(pm, version)   — Human-readable install command string for error messages
  *   → checkForUpdateDetailed()           — Fetch npm latest with explicit error info
  *   → checkForUpdate()                   — Startup wrapper, returns version string or null
+ *   → isPackageDevMode()                 — Detect git/dev checkouts that must not self-update
+ *   → enforceMandatoryStartupUpdate()    — Mandatory startup self-update with two-failure fallback
  *   → runUpdate(latestVersion)           — Install new version via detected PM + relaunch
  * @exports
  *   detectPackageManager, getInstallArgs, getManualInstallCmd,
- *   checkForUpdateDetailed, checkForUpdate, runUpdate, fetchLastReleaseDate
+ *   checkForUpdateDetailed, checkForUpdate, isPackageDevMode,
+ *   enforceMandatoryStartupUpdate, runUpdate, fetchLastReleaseDate
  *
  * @see bin/free-coding-models.js — calls checkForUpdate() at startup and runUpdate() on confirm
  */
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
-import { accessSync, constants } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { accessSync, constants, existsSync } from 'fs'
 
 const require = createRequire(import.meta.url)
 const readline = require('readline')
 const pkg = require('../../package.json')
 const LOCAL_VERSION = pkg.version
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+export const UPDATE_FAILURE_THRESHOLD = 2
 
 /**
  * 📖 detectPackageManager: figure out which package manager owns the current installation.
@@ -65,6 +72,70 @@ export function detectPackageManager() {
   return 'npm'
 }
 
+/**
+ * 📖 isPackageDevMode: true for repo checkouts and explicit --dev runs.
+ * 📖 Self-updating a git checkout creates noisy loops during local development,
+ * 📖 while published npm installs do not ship a .git directory and can update safely.
+ * @returns {boolean}
+ */
+export function isPackageDevMode() {
+  return process.env.FCM_DEV === '1' || existsSync(join(PACKAGE_ROOT, '.git'))
+}
+
+/**
+ * 📖 getUpdateInstallFailureCount: sanitized persistent failure counter.
+ * @param {object} config
+ * @returns {number}
+ */
+export function getUpdateInstallFailureCount(config) {
+  const raw = Number(config?.settings?.updateInstallFailures || 0)
+  if (!Number.isFinite(raw) || raw < 0) return 0
+  return Math.floor(raw)
+}
+
+function ensureUpdateSettings(config) {
+  if (!config.settings || typeof config.settings !== 'object') config.settings = {}
+  return config.settings
+}
+
+function persistUpdateSettings(config, saveConfig) {
+  if (typeof saveConfig !== 'function') return
+  try { saveConfig(config) } catch {}
+}
+
+function resetUpdateInstallFailures(config, saveConfig) {
+  const settings = ensureUpdateSettings(config)
+  if (!settings.updateInstallFailures && !settings.updateLastFailureAt && !settings.updateLastFailureMessage) return
+  settings.updateInstallFailures = 0
+  delete settings.updateLastFailureAt
+  delete settings.updateLastFailureMessage
+  delete settings.updateInstallFailureVersion
+  persistUpdateSettings(config, saveConfig)
+}
+
+function recordUpdateInstallFailure(config, latestVersion, error, saveConfig) {
+  const settings = ensureUpdateSettings(config)
+  const nextFailures = Math.min(getUpdateInstallFailureCount(config) + 1, UPDATE_FAILURE_THRESHOLD)
+  settings.updateInstallFailures = nextFailures
+  settings.updateInstallFailureVersion = latestVersion
+  settings.updateLastFailureAt = new Date().toISOString()
+  settings.updateLastFailureMessage = error instanceof Error ? error.message : String(error || 'Unknown update error')
+  persistUpdateSettings(config, saveConfig)
+  return nextFailures
+}
+
+/**
+ * 📖 buildOutdatedWarningMessage: one-line message shown when mandatory updates
+ * 📖 failed twice and FCM must let the UI start instead of trapping the user.
+ * @param {string|null} latestVersion
+ * @param {number} failures
+ * @returns {string}
+ */
+export function buildOutdatedWarningMessage(latestVersion, failures = UPDATE_FAILURE_THRESHOLD) {
+  const target = latestVersion ? `v${LOCAL_VERSION} → v${latestVersion}` : `v${LOCAL_VERSION}`
+  return `⚠️ OUTDATED VERSION (${target}) — automatic update failed ${failures} times. Models and free quotas change often; update as soon as possible for the freshest catalog.`
+}
+
 /**
  * 📖 getInstallArgs: return the correct binary and argument list for a given PM.
  * 📖 Each PM has different syntax for global install — this normalises them.
@@ -120,6 +191,89 @@ export async function checkForUpdate() {
   return latestVersion
 }
 
+/**
+ * 📖 enforceMandatoryStartupUpdate: startup policy for every user-facing surface.
+ * 📖 If npm has a newer release, FCM installs it immediately without asking.
+ * 📖 The first failed install blocks startup so the next launch retries. After two
+ * 📖 consecutive install failures, startup is allowed with a loud outdated warning
+ * 📖 so offline/proxy/permission users are not permanently locked out.
+ *
+ * @param {object} config
+ * @param {{ saveConfig?: Function, isDevMode?: boolean, surface?: string }} [options]
+ * @returns {Promise<{ latestVersion: string|null, allowedOutdated: boolean, warningMessage: string|null, failures: number, checked: boolean, updated: boolean, blocked: boolean }>}
+ */
+export async function enforceMandatoryStartupUpdate(config, options = {}) {
+  const { saveConfig, surface = 'app' } = options
+  const devMode = typeof options.isDevMode === 'boolean' ? options.isDevMode : isPackageDevMode()
+  const base = {
+    latestVersion: null,
+    allowedOutdated: false,
+    warningMessage: null,
+    failures: getUpdateInstallFailureCount(config),
+    checked: false,
+    updated: false,
+    blocked: false,
+  }
+
+  if (devMode) return base
+
+  const { latestVersion, error } = await checkForUpdateDetailed()
+  base.checked = true
+
+  if (error) {
+    const settings = ensureUpdateSettings(config)
+    settings.updateCheckFailures = Math.min(Number(settings.updateCheckFailures || 0) + 1, UPDATE_FAILURE_THRESHOLD)
+    persistUpdateSettings(config, saveConfig)
+    return base
+  }
+
+  const settings = ensureUpdateSettings(config)
+  if (settings.updateCheckFailures) {
+    settings.updateCheckFailures = 0
+    persistUpdateSettings(config, saveConfig)
+  }
+
+  if (!latestVersion) {
+    resetUpdateInstallFailures(config, saveConfig)
+    return base
+  }
+
+  base.latestVersion = latestVersion
+  const failuresBeforeInstall = getUpdateInstallFailureCount(config)
+  if (failuresBeforeInstall >= UPDATE_FAILURE_THRESHOLD) {
+    base.allowedOutdated = true
+    base.failures = failuresBeforeInstall
+    base.warningMessage = buildOutdatedWarningMessage(latestVersion, failuresBeforeInstall)
+    return base
+  }
+
+  console.log(chalk.dim(`  ⬆ New version v${latestVersion} detected for ${surface}; updating automatically...`))
+  const updateResult = runUpdate(latestVersion, { exitOnFailure: false })
+  if (updateResult?.ok) {
+    resetUpdateInstallFailures(config, saveConfig)
+    base.updated = true
+    return base
+  }
+
+  const failures = recordUpdateInstallFailure(config, latestVersion, updateResult?.error, saveConfig)
+  base.failures = failures
+
+  if (failures >= UPDATE_FAILURE_THRESHOLD) {
+    base.allowedOutdated = true
+    base.warningMessage = buildOutdatedWarningMessage(latestVersion, failures)
+    console.log(chalk.red(`  ${base.warningMessage}`))
+    console.log(chalk.dim(`  Manual update: ${getManualInstallCmd(detectPackageManager(), latestVersion)}`))
+    console.log()
+    return base
+  }
+
+  base.blocked = true
+  console.log(chalk.red('  ✖ Mandatory update failed. FCM will retry on the next launch.'))
+  console.log(chalk.dim(`  Attempt ${failures}/${UPDATE_FAILURE_THRESHOLD}. Manual update: ${getManualInstallCmd(detectPackageManager(), latestVersion)}`))
+  console.log()
+  return base
+}
+
 /**
  * 📖 fetchLastReleaseDate: Get the human-readable publish date of the latest npm release.
  * 📖 Used in the TUI footer to show users how fresh the package is.
@@ -265,10 +419,15 @@ function installUpdateCommand(latestVersion, useSudo) {
 /**
  * 📖 runUpdate: Run npm global install to update to latestVersion.
  * 📖 Retries with sudo on permission errors.
- * 📖 Relaunches the process on success, exits with code 1 on failure.
+ * 📖 Relaunches the process on success. Manual update actions keep the historic
+ * 📖 behavior and exit on failure; mandatory startup checks pass exitOnFailure=false
+ * 📖 so they can persist failure counters and decide whether to let the UI start.
  * @param {string} latestVersion
+ * @param {{ exitOnFailure?: boolean, relaunchOnSuccess?: boolean }} [options]
+ * @returns {{ ok: boolean, error?: unknown }}
  */
-export function runUpdate(latestVersion) {
+export function runUpdate(latestVersion, options = {}) {
+  const { exitOnFailure = true, relaunchOnSuccess = true } = options
   console.log()
   console.log(chalk.bold.cyan('  ⬆ Updating free-coding-models to v' + latestVersion + '...'))
   console.log()
@@ -276,6 +435,7 @@ export function runUpdate(latestVersion) {
   const pm = detectPackageManager()
   const { needsSudo, checkedPath } = detectGlobalInstallPermission(pm)
   const sudoAvailable = process.platform !== 'win32' && hasSudoCommand()
+  let lastError = null
 
   if (needsSudo && checkedPath && sudoAvailable) {
     console.log(chalk.yellow(`  ⚠ Global ${pm} path is not writable: ${checkedPath}`))
@@ -288,9 +448,10 @@ export function runUpdate(latestVersion) {
     console.log()
     console.log(chalk.green(`  ✅ Update complete! Version ${latestVersion} installed.`))
     console.log()
-    relaunchCurrentProcess()
-    return
+    if (relaunchOnSuccess) relaunchCurrentProcess()
+    return { ok: true }
   } catch (err) {
+    lastError = err
     const manualCmd = getManualInstallCmd(pm, latestVersion)
     console.log()
     if (isPermissionError(err) && !needsSudo && sudoAvailable) {
@@ -301,9 +462,10 @@ export function runUpdate(latestVersion) {
         console.log()
         console.log(chalk.green(`  ✅ Update complete with sudo! Version ${latestVersion} installed.`))
         console.log()
-        relaunchCurrentProcess()
-        return
-      } catch {
+        if (relaunchOnSuccess) relaunchCurrentProcess()
+        return { ok: true }
+      } catch (sudoErr) {
+        lastError = sudoErr
         console.log()
         console.log(chalk.red('  ✖ Update failed even with sudo. Try manually:'))
         console.log(chalk.dim(`    sudo ${manualCmd}`))
@@ -318,7 +480,9 @@ export function runUpdate(latestVersion) {
       console.log()
     }
   }
-  process.exit(1)
+
+  if (exitOnFailure) process.exit(1)
+  return { ok: false, error: lastError }
 }
 
 

package/src/tui/app.js

@@ -91,11 +91,7 @@
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
-import { fileURLToPath } from 'url'
-import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs'
 import { randomUUID } from 'crypto'
-import { homedir } from 'os'
-import { join, dirname } from 'path'
 import { MODELS, sources } from '../../sources.js'
 import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS, formatCtxWindow, labelFromId, formatResultsAsJSON } from '../core/utils.js'
 import { loadConfig, saveConfig, getApiKey, resolveApiKeys, addApiKey, removeApiKey, isProviderEnabled, persistApiKeysForProvider } from '../core/config.js'
@@ -181,7 +177,7 @@ const LOCAL_VERSION = pkg.version
 // ─── OpenCode integration ──────────────────────────────────────────────────────
 // 📖 OpenCode helpers are imported from ../src/opencode.js
 
-export async function runApp(cliArgs, config) {
+export async function runApp(cliArgs, config, startupOptions = {}) {
 
   // 📖 Detect user active terminal theme
   detectActiveTheme(config.settings?.theme || 'auto')
@@ -278,32 +274,12 @@ export async function runApp(cliArgs, config) {
     },
   })
 
-  // 📖 Auto-update detection: check npm registry for new versions at startup.
-  // 📖 If a new version is available, show an interactive prompt (Update / Changelogs / Skip).
-  // 📖 Dev mode (git checkout) skips auto-update to avoid infinite relaunch loops.
-  let latestVersion = null
-  const isDevMode = existsSync(join(dirname(fileURLToPath(import.meta.url)), '..', '.git'))
-  try {
-    latestVersion = await checkForUpdate()
-    // 📖 Reset failure counter on successful check
-    if (config.settings?.updateCheckFailures) {
-      config.settings.updateCheckFailures = 0
-      saveConfig(config)
-    }
-  } catch (err) {
-    const failures = (config.settings?.updateCheckFailures || 0) + 1
-    if (!config.settings) config.settings = {}
-    config.settings.updateCheckFailures = Math.min(failures, 3)
-    saveConfig(config)
-  }
-
-  // 📖 Auto-update: if a new version is available, install it immediately (skip in dev mode)
-  // 📖 runUpdate() will relaunch the process with the new version after install completes
-  if (latestVersion && !isDevMode) {
-    console.log(chalk.dim(`  ⬆ New version v${latestVersion} detected, updating...`))
-    runUpdate(latestVersion)
-    return // 📖 runUpdate relaunches the process — this line is a safety guard
-  }
+  // 📖 Mandatory startup update is enforced in the bin entry before any user-facing
+  // 📖 surface starts. runApp receives the result so the TUI can display the
+  // 📖 two-failure fallback warning without repeating npm registry/install work.
+  const startupUpdate = startupOptions.startupUpdate || {}
+  const latestVersion = startupUpdate.latestVersion || null
+  const isDevMode = startupOptions.isDevMode === true
 
   // 📖 Dynamic OpenRouter free model discovery — fetch live free models from API
   // 📖 Replaces static openrouter entries in MODELS with fresh data.
@@ -363,6 +339,8 @@ export async function runApp(cliArgs, config) {
     sessionId,
     latestVersion,
     isDevMode,
+    updateWarningMessage: startupUpdate.warningMessage || null,
+    updateInstallFailures: startupUpdate.failures || 0,
   })
 
   // 📖 Apply the pre-fetched last release date now that state is initialized
@@ -823,6 +801,7 @@ export async function runApp(cliArgs, config) {
       settingsUpdateLatestVersion: state.settingsUpdateLatestVersion,
       startupLatestVersion: state.startupLatestVersion,
       versionAlertsEnabled: state.versionAlertsEnabled,
+      updateWarningMessage: state.updateWarningMessage,
       favoritesPinnedAndSticky: state.favoritesPinnedAndSticky,
       customTextFilter: state.customTextFilter,
       lastReleaseDate: state.lastReleaseDate,
@@ -914,6 +893,7 @@ export async function runApp(cliArgs, config) {
     settingsUpdateLatestVersion: state.settingsUpdateLatestVersion,
     startupLatestVersion: state.startupLatestVersion,
     versionAlertsEnabled: state.versionAlertsEnabled,
+    updateWarningMessage: state.updateWarningMessage,
     favoritesPinnedAndSticky: state.favoritesPinnedAndSticky,
     customTextFilter: state.customTextFilter,
     lastReleaseDate: state.lastReleaseDate,

package/src/tui/key-handler.js

@@ -82,7 +82,7 @@ const PROVIDER_AUTH_ENDPOINTS = {
   groq:         { url: 'https://api.groq.com/v1/models',             method: 'GET' },
   cerebras:     { url: 'https://api.cerebras.ai/v1/models',          method: 'GET' },
   sambanova:    { url: 'https://api.sambanova.ai/v1/models',         method: 'GET' },
-  openrouter:   { url: 'https://openrouter.ai/api/v1/models',        method: 'GET' },
+  openrouter:   { url: 'https://openrouter.ai/api/v1/key',             method: 'GET' },
   mistral:      { url: 'https://api.mistral.ai/v1/models',           method: 'GET' },
   huggingface:  { url: 'https://router.huggingface.co/v1/models',    method: 'GET' },
   deepinfra:    { url: 'https://api.deepinfra.com/v1/models',        method: 'GET' },

package/src/tui/render-table.js

@@ -136,6 +136,7 @@ export const PROVIDER_COLOR = new Proxy({}, {
  *   settingsUpdateLatestVersion: string|null,
  *   startupLatestVersion: string|null,
  *   versionAlertsEnabled: boolean,
+ *   updateWarningMessage?: string|null,
  *   favoritesPinnedAndSticky: boolean,
  *   customTextFilter: string|null,
  *   lastReleaseDate: string|null,
@@ -174,6 +175,7 @@ export function renderTable({
   settingsUpdateLatestVersion = null,
   startupLatestVersion = null,
   versionAlertsEnabled = true,
+  updateWarningMessage = null,
   favoritesPinnedAndSticky = false,
   customTextFilter = null,
   lastReleaseDate = null,
@@ -1073,15 +1075,19 @@ export function renderTable({
   )
 
   if (versionStatus.isOutdated) {
-    const updateMsg = `  🚀⬆️ UPDATE AVAILABLE — v${LOCAL_VERSION} → v${versionStatus.latestVersion}  •  Click here or press Shift+U to update  🚀⬆️  `
+    const updateMsg = updateWarningMessage
+      ? `  ${updateWarningMessage}  •  Press Shift+U to retry update  `
+      : `  🚀⬆️ UPDATE AVAILABLE — v${LOCAL_VERSION} → v${versionStatus.latestVersion}  •  Click here or press Shift+U to update  🚀⬆️  `
     const paddedBanner = terminalCols > 0
       ? updateMsg + ' '.repeat(Math.max(0, terminalCols - displayWidth(updateMsg)))
       : updateMsg
-    const fluoGreenBanner = chalk.bgRgb(57, 255, 20).rgb(0, 0, 0).bold(paddedBanner)
+    const updateBanner = updateWarningMessage
+      ? chalk.bgRed.white.bold(paddedBanner)
+      : chalk.bgRgb(57, 255, 20).rgb(0, 0, 0).bold(paddedBanner)
     const updateBannerRow = lines.length + 1
     _lastLayout.updateBannerRow = updateBannerRow
     footerHotkeys.push({ key: 'update-click', row: updateBannerRow, xStart: 1, xEnd: Math.max(terminalCols, displayWidth(updateMsg)) })
-    lines.push(fluoGreenBanner)
+    lines.push(updateBanner)
   } else {
     _lastLayout.updateBannerRow = 0
   }

package/src/tui/tui-state.js

@@ -70,6 +70,8 @@ export function intervalToPingMode(intervalMs) {
  *   sessionId: string,
  *   latestVersion: string|null,
  *   isDevMode: boolean,
+ *   updateWarningMessage?: string|null,
+ *   updateInstallFailures?: number,
  * }} opts
  * @returns {object} The complete TUI state (mutable)
  */
@@ -80,6 +82,8 @@ export function createTuiState({
   sessionId,
   latestVersion,
   isDevMode,
+  updateWarningMessage = null,
+  updateInstallFailures = 0,
 }) {
   const now = Date.now()
 
@@ -110,6 +114,8 @@ export function createTuiState({
 
     // 📖 Version tracking — startup auto-check + periodic re-check
     startupLatestVersion: latestVersion,
+    updateWarningMessage,
+    updateInstallFailures,
     lastReleaseDate: null,
     versionAlertsEnabled: !isDevMode,