free-coding-models 0.1.62 → 0.1.64

package/bin/free-coding-models.js

@@ -10,7 +10,7 @@
  *   During benchmarking, users can navigate with arrow keys and press Enter to act on the selected model.
  *
  *   🎯 Key features:
- *   - Parallel pings across all models with animated real-time updates (3 providers: NIM, Groq, Cerebras)
+ *   - Parallel pings across all models with animated real-time updates (multi-provider)
  *   - Continuous monitoring with 2-second ping intervals (never stops)
  *   - Rolling averages calculated from ALL successful pings since start
  *   - Best-per-tier highlighting with medals (🥇🥈🥉)
@@ -19,7 +19,7 @@
  *   - Startup mode menu (OpenCode CLI vs OpenCode Desktop vs OpenClaw) when no flag is given
  *   - Automatic config detection and model setup for both tools
  *   - JSON config stored in ~/.free-coding-models.json (auto-migrates from old plain-text)
- *   - Multi-provider support via sources.js (NIM, Groq, Cerebras — extensible)
+ *   - 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
  *   - Uptime percentage tracking (successful pings / total pings)
  *   - Sortable columns (R/Y/O/M/L/A/S/N/H/V/U keys)
@@ -27,15 +27,21 @@
  *
  *   → Functions:
  *   - `loadConfig` / `saveConfig` / `getApiKey`: Multi-provider JSON config via lib/config.js
- *   - `promptApiKey`: Interactive wizard for first-time NVIDIA API key setup
+ *   - `promptTelemetryConsent`: First-run consent flow for anonymous analytics
+ *   - `getTelemetryDistinctId`: Generate/reuse a stable anonymous ID for telemetry
+ *   - `getTelemetryTerminal`: Infer terminal family (Terminal.app, iTerm2, kitty, etc.)
+ *   - `isTelemetryDebugEnabled` / `telemetryDebug`: Optional runtime telemetry diagnostics via env
+ *   - `sendUsageTelemetry`: Fire-and-forget anonymous app-start event
+ *   - `promptApiKey`: Interactive wizard for first-time multi-provider API key setup
  *   - `promptModeSelection`: Startup menu to choose OpenCode vs OpenClaw
- *   - `ping`: Perform HTTP request to NIM endpoint with timeout handling
+ *   - `buildPingRequest` / `ping`: Build provider-specific probe requests and measure latency
  *   - `renderTable`: Generate ASCII table with colored latency indicators and status emojis
  *   - `getAvg`: Calculate average latency from all successful pings
  *   - `getVerdict`: Determine verdict string based on average latency (Overloaded for 429)
  *   - `getUptime`: Calculate uptime percentage from ping history
  *   - `sortResults`: Sort models by various columns
  *   - `checkNvidiaNimConfig`: Check if NVIDIA NIM provider is configured in OpenCode
+ *   - `isTcpPortAvailable` / `resolveOpenCodeTmuxPort`: Pick a safe OpenCode port when running in tmux
  *   - `startOpenCode`: Launch OpenCode CLI with selected model (configures if needed)
  *   - `startOpenCodeDesktop`: Set model in shared config & open OpenCode Desktop app
  *   - `loadOpenClawConfig` / `saveOpenClawConfig`: Manage ~/.openclaw/openclaw.json
@@ -52,8 +58,8 @@
  *   ⚙️ Configuration:
  *   - API keys stored per-provider in ~/.free-coding-models.json (0600 perms)
  *   - Old ~/.free-coding-models plain-text auto-migrated as nvidia key on first run
- *   - Env vars override config: NVIDIA_API_KEY, GROQ_API_KEY, CEREBRAS_API_KEY
- *   - Models loaded from sources.js — 53 models across NIM, Groq, Cerebras
+ *   - Env vars override config: NVIDIA_API_KEY, GROQ_API_KEY, CEREBRAS_API_KEY, OPENROUTER_API_KEY, HUGGINGFACE_API_KEY/HF_TOKEN, REPLICATE_API_TOKEN, DEEPINFRA_API_KEY/DEEPINFRA_TOKEN, FIREWORKS_API_KEY, etc.
+ *   - Models loaded from sources.js — all provider/model definitions are centralized there
  *   - OpenCode config: ~/.config/opencode/opencode.json
  *   - OpenClaw config: ~/.openclaw/openclaw.json
  *   - Ping timeout: 15s per attempt
@@ -67,6 +73,7 @@
  *   - --openclaw: OpenClaw mode (set selected model as default in OpenClaw)
  *   - --best: Show only top-tier models (A+, S, S+)
  *   - --fiable: Analyze 10s and output the most reliable model
+ *   - --no-telemetry: Disable anonymous usage analytics for this run
  *   - --tier S/A/B/C: Filter models by tier letter (S=S+/S, A=A+/A/A-, B=B+/B, C=C)
  *
  *   @see {@link https://build.nvidia.com} NVIDIA API key generation
@@ -77,8 +84,10 @@
 import chalk from 'chalk'
 import { createRequire } from 'module'
 import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs'
+import { randomUUID } from 'crypto'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
+import { createServer } from 'net'
 import { MODELS, sources } from '../sources.js'
 import { patchOpenClawModelsJson } from '../patch-openclaw-models.js'
 import { getAvg, getVerdict, getUptime, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP } from '../lib/utils.js'
@@ -90,6 +99,322 @@ const readline = require('readline')
 // ─── Version check ────────────────────────────────────────────────────────────
 const pkg = require('../package.json')
 const LOCAL_VERSION = pkg.version
+const TELEMETRY_CONSENT_VERSION = 1
+const TELEMETRY_TIMEOUT = 1_200
+const POSTHOG_CAPTURE_PATH = '/i/v0/e/'
+const POSTHOG_DEFAULT_HOST = 'https://eu.i.posthog.com'
+// 📖 Consent ASCII banner shown before telemetry choice to make first-run intent explicit.
+const TELEMETRY_CONSENT_ASCII = [
+  '███████ ██████  ███████ ███████        ██████  ██████  ██████  ██ ███    ██  ██████        ███    ███  ██████  ██████  ███████ ██      ███████',
+  '██      ██   ██ ██      ██            ██      ██    ██ ██   ██ ██ ████   ██ ██             ████  ████ ██    ██ ██   ██ ██      ██      ██',
+  '█████   ██████  █████   █████   █████ ██      ██    ██ ██   ██ ██ ██ ██  ██ ██   ███ █████ ██ ████ ██ ██    ██ ██   ██ █████   ██      ███████',
+  '██      ██   ██ ██      ██            ██      ██    ██ ██   ██ ██ ██  ██ ██ ██    ██       ██  ██  ██ ██    ██ ██   ██ ██      ██           ██',
+  '██      ██   ██ ███████ ███████        ██████  ██████  ██████  ██ ██   ████  ██████        ██      ██  ██████  ██████  ███████ ███████ ███████',
+  '',
+  '',
+]
+// 📖 Maintainer defaults for global npm telemetry (safe to publish: project key is a public ingest token).
+const POSTHOG_PROJECT_KEY_DEFAULT = 'phc_5P1n8HaLof6nHM0tKJYt4bV5pj2XPb272fLVigwf1YQ'
+const POSTHOG_HOST_DEFAULT = 'https://eu.i.posthog.com'
+
+// 📖 parseTelemetryEnv: Convert env var strings into booleans.
+// 📖 Returns true/false when value is recognized, otherwise null.
+function parseTelemetryEnv(value) {
+  if (typeof value !== 'string') return null
+  const normalized = value.trim().toLowerCase()
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false
+  return null
+}
+
+// 📖 Optional debug switch for telemetry troubleshooting (disabled by default).
+function isTelemetryDebugEnabled() {
+  return parseTelemetryEnv(process.env.FREE_CODING_MODELS_TELEMETRY_DEBUG) === true
+}
+
+// 📖 Writes telemetry debug traces to stderr only when explicitly enabled.
+function telemetryDebug(message, meta = null) {
+  if (!isTelemetryDebugEnabled()) return
+  const prefix = '[telemetry-debug]'
+  if (meta === null) {
+    process.stderr.write(`${prefix} ${message}\n`)
+    return
+  }
+  try {
+    process.stderr.write(`${prefix} ${message} ${JSON.stringify(meta)}\n`)
+  } catch {
+    process.stderr.write(`${prefix} ${message}\n`)
+  }
+}
+
+// 📖 Ensure telemetry config shape exists even on old config files.
+function ensureTelemetryConfig(config) {
+  if (!config.telemetry || typeof config.telemetry !== 'object') {
+    config.telemetry = { enabled: null, consentVersion: 0, anonymousId: null }
+  }
+  if (typeof config.telemetry.enabled !== 'boolean') config.telemetry.enabled = null
+  if (typeof config.telemetry.consentVersion !== 'number') config.telemetry.consentVersion = 0
+  if (typeof config.telemetry.anonymousId !== 'string' || !config.telemetry.anonymousId.trim()) {
+    config.telemetry.anonymousId = null
+  }
+}
+
+// 📖 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) {
+  ensureTelemetryConfig(config)
+  if (config.telemetry.anonymousId) return config.telemetry.anonymousId
+
+  config.telemetry.anonymousId = `anon_${randomUUID()}`
+  saveConfig(config)
+  return config.telemetry.anonymousId
+}
+
+// 📖 Convert Node platform to human-readable system name for analytics segmentation.
+function getTelemetrySystem() {
+  if (process.platform === 'darwin') return 'macOS'
+  if (process.platform === 'win32') return 'Windows'
+  if (process.platform === 'linux') return 'Linux'
+  return process.platform
+}
+
+// 📖 Infer terminal family from environment hints for coarse usage segmentation.
+// 📖 Never sends full env dumps; only a normalized terminal label is emitted.
+function getTelemetryTerminal() {
+  const termProgramRaw = (process.env.TERM_PROGRAM || '').trim()
+  const termProgram = termProgramRaw.toLowerCase()
+  const term = (process.env.TERM || '').toLowerCase()
+
+  if (termProgram === 'apple_terminal') return 'Terminal.app'
+  if (termProgram === 'iterm.app') return 'iTerm2'
+  if (termProgram === 'warpterminal' || process.env.WARP_IS_LOCAL_SHELL_SESSION) return 'Warp'
+  if (process.env.WT_SESSION) return 'Windows Terminal'
+  if (process.env.KITTY_WINDOW_ID || term.includes('kitty')) return 'kitty'
+  if (process.env.GHOSTTY_RESOURCES_DIR || term.includes('ghostty')) return 'Ghostty'
+  if (process.env.WEZTERM_PANE || termProgram === 'wezterm') return 'WezTerm'
+  if (process.env.KONSOLE_VERSION || termProgram === 'konsole') return 'Konsole'
+  if (process.env.GNOME_TERMINAL_SCREEN || termProgram === 'gnome-terminal') return 'GNOME Terminal'
+  if (process.env.TERMINAL_EMULATOR === 'JetBrains-JediTerm') return 'JetBrains Terminal'
+  if (process.env.TABBY_CONFIG_DIRECTORY || termProgram === 'tabby') return 'Tabby'
+  if (termProgram === 'vscode' || process.env.VSCODE_GIT_IPC_HANDLE) return 'VS Code Terminal'
+  if (process.env.ALACRITTY_SOCKET || term.includes('alacritty') || termProgram === 'alacritty') return 'Alacritty'
+  if (term.includes('foot') || termProgram === 'foot') return 'foot'
+  if (termProgram === 'hyper' || process.env.HYPER) return 'Hyper'
+  if (process.env.TMUX) return 'tmux'
+  if (process.env.STY) return 'screen'
+  // 📖 Generic fallback for many terminals exposing TERM_PROGRAM (e.g., Rio, Contour, etc.).
+  if (termProgramRaw) return termProgramRaw
+  if (term) return term
+
+  return 'unknown'
+}
+
+// 📖 Prompt consent on first run (or when consent schema version changes).
+// 📖 This prompt is skipped when the env var explicitly controls telemetry.
+async function promptTelemetryConsent(config, cliArgs) {
+  if (cliArgs.noTelemetry) return
+
+  const envTelemetry = parseTelemetryEnv(process.env.FREE_CODING_MODELS_TELEMETRY)
+  if (envTelemetry !== null) return
+
+  ensureTelemetryConfig(config)
+  const hasStoredChoice = typeof config.telemetry.enabled === 'boolean'
+  const isConsentCurrent = config.telemetry.consentVersion >= TELEMETRY_CONSENT_VERSION
+  if (hasStoredChoice && isConsentCurrent) return
+
+  // 📖 Non-interactive runs should never hang waiting for input.
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    // 📖 Do not mutate persisted consent in headless runs.
+    // 📖 We simply skip the prompt; runtime telemetry remains governed by env/config precedence.
+    return
+  }
+
+  const options = [
+    { label: 'Accept & Continue', value: true, emoji: '💖🥰💖' },
+    { label: 'Reject and Continue', value: false, emoji: '😢' },
+  ]
+  let selected = 0 // 📖 Default selection is Accept & Continue.
+
+  const accepted = await new Promise((resolve) => {
+    const render = () => {
+      const EL = '\x1b[K'
+      const lines = []
+      for (const asciiLine of TELEMETRY_CONSENT_ASCII) {
+        lines.push(chalk.greenBright(asciiLine))
+      }
+      lines.push(chalk.greenBright(`free-coding-models (v${LOCAL_VERSION})`))
+      lines.push(chalk.greenBright('Welcome ! Would you like to help improve the app and fix bugs by activating PostHog telemetry (anonymous & secure)'))
+      lines.push(chalk.greenBright("anonymous telemetry analytics (we don't collect anything from you)"))
+      lines.push('')
+
+      for (let i = 0; i < options.length; i++) {
+        const isSelected = i === selected
+        const option = options[i]
+        const buttonText = `${option.emoji} ${option.label}`
+
+        let button
+        if (isSelected && option.value) button = chalk.black.bgGreenBright(`  ${buttonText}  `)
+        else if (isSelected && !option.value) button = chalk.black.bgRedBright(`  ${buttonText}  `)
+        else if (option.value) button = chalk.greenBright(`  ${buttonText}  `)
+        else button = chalk.redBright(`  ${buttonText}  `)
+
+        const prefix = isSelected ? chalk.cyan('  ❯ ') : chalk.dim('    ')
+        lines.push(prefix + button)
+      }
+
+      lines.push('')
+      lines.push(chalk.dim('  ↑↓ Navigate  •  Enter Select'))
+      lines.push(chalk.dim('  You can change this later in Settings (P).'))
+      lines.push('')
+
+      // 📖 Avoid full-screen clear escape here to prevent title/header offset issues in some terminals.
+      const cleared = lines.map(l => l + EL)
+      const terminalRows = process.stdout.rows || 24
+      const remaining = Math.max(0, terminalRows - cleared.length)
+      for (let i = 0; i < remaining; i++) cleared.push(EL)
+      process.stdout.write('\x1b[H' + cleared.join('\n'))
+    }
+
+    const cleanup = () => {
+      if (process.stdin.isTTY) process.stdin.setRawMode(false)
+      process.stdin.removeListener('keypress', onKeyPress)
+      process.stdin.pause()
+    }
+
+    const onKeyPress = (_str, key) => {
+      if (!key) return
+
+      if (key.ctrl && key.name === 'c') {
+        cleanup()
+        resolve(false)
+        return
+      }
+
+      if ((key.name === 'up' || key.name === 'left') && selected > 0) {
+        selected--
+        render()
+        return
+      }
+
+      if ((key.name === 'down' || key.name === 'right') && selected < options.length - 1) {
+        selected++
+        render()
+        return
+      }
+
+      if (key.name === 'return') {
+        cleanup()
+        resolve(options[selected].value)
+      }
+    }
+
+    readline.emitKeypressEvents(process.stdin)
+    process.stdin.setEncoding('utf8')
+    process.stdin.resume()
+    if (process.stdin.isTTY) process.stdin.setRawMode(true)
+    process.stdin.on('keypress', onKeyPress)
+    render()
+  })
+
+  config.telemetry.enabled = accepted
+  config.telemetry.consentVersion = TELEMETRY_CONSENT_VERSION
+  saveConfig(config)
+
+  console.log()
+  if (accepted) {
+    console.log(chalk.green('  ✅ Analytics enabled. You can disable it later in Settings (P) or with --no-telemetry.'))
+  } else {
+    console.log(chalk.yellow('  Analytics disabled. You can enable it later in Settings (P).'))
+  }
+  console.log()
+}
+
+// 📖 Resolve telemetry effective state with clear precedence:
+// 📖 CLI flag > env var > config file > disabled by default.
+function isTelemetryEnabled(config, cliArgs) {
+  if (cliArgs.noTelemetry) return false
+  const envTelemetry = parseTelemetryEnv(process.env.FREE_CODING_MODELS_TELEMETRY)
+  if (envTelemetry !== null) return envTelemetry
+  ensureTelemetryConfig(config)
+  return config.telemetry.enabled === true
+}
+
+// 📖 Fire-and-forget analytics ping: never blocks UX, never throws.
+async function sendUsageTelemetry(config, cliArgs, payload) {
+  if (!isTelemetryEnabled(config, cliArgs)) {
+    telemetryDebug('skip: telemetry disabled', {
+      cliNoTelemetry: cliArgs.noTelemetry === true,
+      envTelemetry: process.env.FREE_CODING_MODELS_TELEMETRY || null,
+      configEnabled: config?.telemetry?.enabled ?? null,
+    })
+    return
+  }
+
+  const apiKey = (
+    process.env.FREE_CODING_MODELS_POSTHOG_KEY ||
+    process.env.POSTHOG_PROJECT_API_KEY ||
+    POSTHOG_PROJECT_KEY_DEFAULT ||
+    ''
+  ).trim()
+  if (!apiKey) {
+    telemetryDebug('skip: missing api key')
+    return
+  }
+
+  const host = (
+    process.env.FREE_CODING_MODELS_POSTHOG_HOST ||
+    process.env.POSTHOG_HOST ||
+    POSTHOG_HOST_DEFAULT ||
+    POSTHOG_DEFAULT_HOST
+  ).trim().replace(/\/+$/, '')
+  if (!host) {
+    telemetryDebug('skip: missing host')
+    return
+  }
+
+  try {
+    const endpoint = `${host}${POSTHOG_CAPTURE_PATH}`
+    const distinctId = getTelemetryDistinctId(config)
+    const timestamp = typeof payload?.ts === 'string' ? payload.ts : new Date().toISOString()
+    const signal = (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function')
+      ? AbortSignal.timeout(TELEMETRY_TIMEOUT)
+      : undefined
+
+    const posthogBody = {
+      api_key: apiKey,
+      event: payload?.event || 'app_start',
+      distinct_id: distinctId,
+      timestamp,
+      properties: {
+        $process_person_profile: false,
+        source: 'cli',
+        app: 'free-coding-models',
+        version: payload?.version || LOCAL_VERSION,
+        app_version: payload?.version || LOCAL_VERSION,
+        mode: payload?.mode || 'opencode',
+        system: getTelemetrySystem(),
+        terminal: getTelemetryTerminal(),
+      },
+    }
+
+    await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(posthogBody),
+      signal,
+    })
+    telemetryDebug('sent', {
+      event: posthogBody.event,
+      endpoint,
+      mode: posthogBody.properties.mode,
+      system: posthogBody.properties.system,
+      terminal: posthogBody.properties.terminal,
+    })
+  } catch {
+    // 📖 Ignore failures silently: analytics must never break the CLI.
+    telemetryDebug('error: send failed')
+  }
+}
 
 async function checkForUpdate() {
   try {
@@ -163,7 +488,7 @@ function runUpdate(latestVersion) {
 
 // ─── First-run wizard ─────────────────────────────────────────────────────────
 // 📖 Shown when NO provider has a key configured yet.
-// 📖 Steps through all 3 providers sequentially — each is optional (Enter to skip).
+// 📖 Steps through all configured providers sequentially — each is optional (Enter to skip).
 // 📖 At least one key must be entered to proceed. Keys saved to ~/.free-coding-models.json.
 // 📖 Returns the nvidia key (or null) for backward-compat with the rest of main().
 async function promptApiKey(config) {
@@ -172,81 +497,17 @@ async function promptApiKey(config) {
   console.log(chalk.dim('  Enter keys for any provider you want to use. Press Enter to skip one.'))
   console.log()
 
-  // 📖 Provider definitions: label, key field, url for getting the key
-  const providers = [
-    {
-      key: 'nvidia',
-      label: 'NVIDIA NIM',
-      color: chalk.rgb(118, 185, 0),
-      url: 'https://build.nvidia.com',
-      hint: 'Profile → API Keys → Generate',
-      prefix: 'nvapi-',
-    },
-    {
-      key: 'groq',
-      label: 'Groq',
-      color: chalk.rgb(249, 103, 20),
-      url: 'https://console.groq.com/keys',
-      hint: 'API Keys → Create API Key',
-      prefix: 'gsk_',
-    },
-    {
-      key: 'cerebras',
-      label: 'Cerebras',
-      color: chalk.rgb(0, 180, 255),
-      url: 'https://cloud.cerebras.ai',
-      hint: 'API Keys → Create',
-      prefix: 'csk_ / cauth_',
-    },
-    {
-      key: 'sambanova',
-      label: 'SambaNova',
-      color: chalk.rgb(255, 165, 0),
-      url: 'https://cloud.sambanova.ai/apis',
-      hint: 'API Keys → Create ($5 free trial, 3 months)',
-      prefix: 'sn-',
-    },
-    {
-      key: 'openrouter',
-      label: 'OpenRouter',
-      color: chalk.rgb(120, 80, 255),
-      url: 'https://openrouter.ai/settings/keys',
-      hint: 'API Keys → Create key (50 free req/day, shared quota)',
-      prefix: 'sk-or-',
-    },
-    {
-      key: 'codestral',
-      label: 'Mistral Codestral',
-      color: chalk.rgb(255, 100, 100),
-      url: 'https://codestral.mistral.ai',
-      hint: 'API Keys → Create key (30 req/min, 2000/day — phone required)',
-      prefix: 'csk-',
-    },
-    {
-      key: 'hyperbolic',
-      label: 'Hyperbolic',
-      color: chalk.rgb(0, 200, 150),
-      url: 'https://app.hyperbolic.ai/settings',
-      hint: 'Settings → API Keys ($1 free trial)',
-      prefix: 'eyJ',
-    },
-    {
-      key: 'scaleway',
-      label: 'Scaleway',
-      color: chalk.rgb(130, 0, 250),
-      url: 'https://console.scaleway.com/iam/api-keys',
-      hint: 'IAM → API Keys (1M free tokens)',
-      prefix: 'scw-',
-    },
-    {
-      key: 'googleai',
-      label: 'Google AI Studio',
-      color: chalk.rgb(66, 133, 244),
-      url: 'https://aistudio.google.com/apikey',
-      hint: 'Get API key (free Gemma models, 14.4K req/day)',
-      prefix: 'AIza',
-    },
-  ]
+  // 📖 Build providers from sources to keep setup in sync with actual supported providers.
+  const providers = Object.keys(sources).map((key) => {
+    const meta = PROVIDER_METADATA[key] || {}
+    return {
+      key,
+      label: meta.label || sources[key]?.name || key,
+      color: meta.color || chalk.white,
+      url: meta.signupUrl || 'https://example.com',
+      hint: meta.signupHint || 'Create API key',
+    }
+  })
 
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
 
@@ -440,14 +701,17 @@ const spinCell = (f, o = 0) => chalk.dim.yellow(FRAMES[(f + o) % FRAMES.length].
 // 📖 are imported from lib/utils.js for testability
 
 // ─── Viewport calculation ────────────────────────────────────────────────────
+// 📖 Keep these constants in sync with renderTable() fixed shell lines.
+// 📖 If this drifts, model rows overflow and can push the title row out of view.
+const TABLE_HEADER_LINES = 4 // 📖 title, spacer, column headers, separator
+const TABLE_FOOTER_LINES = 6 // 📖 spacer, hints, spacer, credit+contributors, discord, spacer
+const TABLE_FIXED_LINES = TABLE_HEADER_LINES + TABLE_FOOTER_LINES
+
 // 📖 Computes the visible slice of model rows that fits in the terminal.
-// 📖 Fixed lines: 5 header + 5 footer = 10 lines always consumed.
-// 📖 Header: empty, title, empty, column headers, separator (5)
-// 📖 Footer: empty, hints, empty, credit, empty (5)
 // 📖 When scroll indicators are needed, they each consume 1 line from the model budget.
 function calculateViewport(terminalRows, scrollOffset, totalModels) {
   if (terminalRows <= 0) return { startIdx: 0, endIdx: totalModels, hasAbove: false, hasBelow: false }
-  let maxSlots = terminalRows - 10  // 5 header + 5 footer
+  let maxSlots = terminalRows - TABLE_FIXED_LINES
   if (maxSlots < 1) maxSlots = 1
   if (totalModels <= maxSlots) return { startIdx: 0, endIdx: totalModels, hasAbove: false, hasBelow: false }
 
@@ -486,7 +750,7 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
   if (mode === 'openclaw') {
     modeBadge = chalk.bold.rgb(255, 100, 50)(' [🦞 OpenClaw]')
   } else if (mode === 'opencode-desktop') {
-    modeBadge = chalk.bold.rgb(0, 200, 255)(' [🖥 Desktop]')
+    modeBadge = chalk.bold.rgb(0, 200, 255)(' [🖥  Desktop]')
   } else {
     modeBadge = chalk.bold.rgb(0, 200, 255)(' [💻 CLI]')
   }
@@ -529,7 +793,6 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
   const sorted = sortResults(visibleResults, sortColumn, sortDirection)
 
   const lines = [
-    '',
     `  ${chalk.bold('⚡ Free Coding Models')} ${chalk.dim('v' + LOCAL_VERSION)}${modeBadge}${modeHint}${tierBadge}${originBadge}   ` +
       chalk.greenBright(`✅ ${up}`) + chalk.dim(' up  ') +
       chalk.yellow(`⏳ ${timeout}`) + chalk.dim(' timeout  ') +
@@ -771,7 +1034,15 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
       : 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('')
-  lines.push(chalk.rgb(255, 150, 200)('  Made with 💖 & ☕ by \x1b]8;;https://github.com/vava-nessa\x1b\\vava-nessa\x1b]8;;\x1b\\') + chalk.dim('  •  ') + '⭐ ' + '\x1b]8;;https://github.com/vava-nessa/free-coding-models\x1b\\Star on GitHub\x1b]8;;\x1b\\')
+  lines.push(
+    chalk.rgb(255, 150, 200)('  Made with 💖 & ☕ by \x1b]8;;https://github.com/vava-nessa\x1b\\vava-nessa\x1b]8;;\x1b\\') +
+    chalk.dim('  •  ') +
+    '⭐ ' +
+    '\x1b]8;;https://github.com/vava-nessa/free-coding-models\x1b\\Star on GitHub\x1b]8;;\x1b\\' +
+    chalk.dim('  •  ') +
+    '🤝 ' +
+    '\x1b]8;;https://github.com/vava-nessa/free-coding-models/graphs/contributors\x1b\\Contributors\x1b]8;;\x1b\\'
+  )
   // 📖 Discord invite + BETA warning — always visible at the bottom of the TUI
   lines.push('  💬 ' + chalk.cyanBright('\x1b]8;;https://discord.gg/5MbTnDC3Md\x1b\\Join our Discord\x1b]8;;\x1b\\') + chalk.dim(' → ') + chalk.cyanBright('https://discord.gg/5MbTnDC3Md') + chalk.dim('  •  ') + chalk.yellow('⚠ BETA TUI') + chalk.dim(' — might crash or have problems'))
   lines.push('')
@@ -788,23 +1059,50 @@ function renderTable(results, pendingPings, frame, cursor = null, sortColumn = '
 // ─── HTTP ping ────────────────────────────────────────────────────────────────
 
 // 📖 ping: Send a single chat completion request to measure model availability and latency.
-// 📖 url param is the provider's endpoint URL — differs per provider (NIM, Groq, Cerebras).
+// 📖 providerKey and url determine provider-specific request format.
 // 📖 apiKey can be null — in that case no Authorization header is sent.
 // 📖 A 401 response still tells us the server is UP and gives us real latency.
-async function ping(apiKey, modelId, url) {
+function buildPingRequest(apiKey, modelId, providerKey, url) {
+  if (providerKey === 'replicate') {
+    // 📖 Replicate uses /v1/predictions with a different payload than OpenAI chat-completions.
+    const replicateHeaders = { 'Content-Type': 'application/json', Prefer: 'wait=4' }
+    if (apiKey) replicateHeaders.Authorization = `Token ${apiKey}`
+    return {
+      url,
+      headers: replicateHeaders,
+      body: { version: modelId, input: { prompt: 'hi' } },
+    }
+  }
+
+  const headers = { 'Content-Type': 'application/json' }
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`
+  if (providerKey === 'openrouter') {
+    // 📖 OpenRouter recommends optional app identification headers.
+    headers['HTTP-Referer'] = 'https://github.com/vava-nessa/free-coding-models'
+    headers['X-Title'] = 'free-coding-models'
+  }
+
+  return {
+    url,
+    headers,
+    body: { model: modelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
+  }
+}
+
+async function ping(apiKey, modelId, providerKey, url) {
   const ctrl  = new AbortController()
   const timer = setTimeout(() => ctrl.abort(), PING_TIMEOUT)
   const t0    = performance.now()
   try {
-    // 📖 Only attach Authorization header when a key is available
-    const headers = { 'Content-Type': 'application/json' }
-    if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`
-    const resp = await fetch(url, {
+    const req = buildPingRequest(apiKey, modelId, providerKey, url)
+    const resp = await fetch(req.url, {
       method: 'POST', signal: ctrl.signal,
-      headers,
-      body: JSON.stringify({ model: modelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 }),
+      headers: req.headers,
+      body: JSON.stringify(req.body),
     })
-    return { code: String(resp.status), ms: Math.round(performance.now() - t0) }
+    // 📖 Normalize all HTTP 2xx statuses to "200" so existing verdict/avg logic still works.
+    const code = resp.status >= 200 && resp.status < 300 ? '200' : String(resp.status)
+    return { code, ms: Math.round(performance.now() - t0) }
   } catch (err) {
     const isTimeout = err.name === 'AbortError'
     return {
@@ -845,12 +1143,112 @@ const ENV_VAR_NAMES = {
   cerebras:   'CEREBRAS_API_KEY',
   sambanova:  'SAMBANOVA_API_KEY',
   openrouter: 'OPENROUTER_API_KEY',
+  huggingface:'HUGGINGFACE_API_KEY',
+  replicate:  'REPLICATE_API_TOKEN',
+  deepinfra:  'DEEPINFRA_API_KEY',
+  fireworks:  'FIREWORKS_API_KEY',
   codestral:  'CODESTRAL_API_KEY',
   hyperbolic: 'HYPERBOLIC_API_KEY',
   scaleway:   'SCALEWAY_API_KEY',
   googleai:   'GOOGLE_API_KEY',
 }
 
+// 📖 Provider metadata used by the setup wizard and Settings details panel.
+// 📖 Keeps signup links + rate limits centralized so UI stays consistent.
+const PROVIDER_METADATA = {
+  nvidia: {
+    label: 'NVIDIA NIM',
+    color: chalk.rgb(118, 185, 0),
+    signupUrl: 'https://build.nvidia.com',
+    signupHint: 'Profile → API Keys → Generate',
+    rateLimits: 'Free tier (provider quota by model)',
+  },
+  groq: {
+    label: 'Groq',
+    color: chalk.rgb(249, 103, 20),
+    signupUrl: 'https://console.groq.com/keys',
+    signupHint: 'API Keys → Create API Key',
+    rateLimits: 'Free dev tier (provider quota)',
+  },
+  cerebras: {
+    label: 'Cerebras',
+    color: chalk.rgb(0, 180, 255),
+    signupUrl: 'https://cloud.cerebras.ai',
+    signupHint: 'API Keys → Create',
+    rateLimits: 'Free dev tier (provider quota)',
+  },
+  sambanova: {
+    label: 'SambaNova',
+    color: chalk.rgb(255, 165, 0),
+    signupUrl: 'https://sambanova.ai/developers',
+    signupHint: 'Developers portal → Create API key',
+    rateLimits: 'Dev tier generous quota',
+  },
+  openrouter: {
+    label: 'OpenRouter',
+    color: chalk.rgb(120, 80, 255),
+    signupUrl: 'https://openrouter.ai/keys',
+    signupHint: 'API Keys → Create',
+    rateLimits: '50 req/day, 20/min (:free shared quota)',
+  },
+  huggingface: {
+    label: 'Hugging Face Inference',
+    color: chalk.rgb(255, 182, 0),
+    signupUrl: 'https://huggingface.co/settings/tokens',
+    signupHint: 'Settings → Access Tokens',
+    rateLimits: 'Free monthly credits (~$0.10)',
+  },
+  replicate: {
+    label: 'Replicate',
+    color: chalk.rgb(120, 160, 255),
+    signupUrl: 'https://replicate.com/account/api-tokens',
+    signupHint: 'Account → API Tokens',
+    rateLimits: 'Developer free quota',
+  },
+  deepinfra: {
+    label: 'DeepInfra',
+    color: chalk.rgb(0, 180, 140),
+    signupUrl: 'https://deepinfra.com/login',
+    signupHint: 'Login → API keys',
+    rateLimits: 'Free dev tier (low-latency quota)',
+  },
+  fireworks: {
+    label: 'Fireworks AI',
+    color: chalk.rgb(255, 80, 50),
+    signupUrl: 'https://fireworks.ai',
+    signupHint: 'Create account → Generate API key',
+    rateLimits: '$1 free credits (new dev accounts)',
+  },
+  codestral: {
+    label: 'Mistral Codestral',
+    color: chalk.rgb(255, 100, 100),
+    signupUrl: 'https://codestral.mistral.ai',
+    signupHint: 'API Keys → Create',
+    rateLimits: '30 req/min, 2000/day',
+  },
+  hyperbolic: {
+    label: 'Hyperbolic',
+    color: chalk.rgb(0, 200, 150),
+    signupUrl: 'https://app.hyperbolic.ai/settings',
+    signupHint: 'Settings → API Keys',
+    rateLimits: '$1 free trial credits',
+  },
+  scaleway: {
+    label: 'Scaleway',
+    color: chalk.rgb(130, 0, 250),
+    signupUrl: 'https://console.scaleway.com/iam/api-keys',
+    signupHint: 'IAM → API Keys',
+    rateLimits: '1M free tokens',
+  },
+  googleai: {
+    label: 'Google AI Studio',
+    color: chalk.rgb(66, 133, 244),
+    signupUrl: 'https://aistudio.google.com/apikey',
+    signupHint: 'Get API key',
+    rateLimits: '14.4K req/day, 30/min',
+  },
+}
+
 // 📖 OpenCode config location varies by platform
 // 📖 Windows: %APPDATA%\opencode\opencode.json (or sometimes ~/.config/opencode)
 // 📖 macOS/Linux: ~/.config/opencode/opencode.json
@@ -860,6 +1258,45 @@ const OPENCODE_CONFIG = isWindows
 
 // 📖 Fallback to .config on Windows if AppData doesn't exist
 const OPENCODE_CONFIG_FALLBACK = join(homedir(), '.config', 'opencode', 'opencode.json')
+const OPENCODE_PORT_RANGE_START = 4096
+const OPENCODE_PORT_RANGE_END = 5096
+
+// 📖 isTcpPortAvailable: checks if a local TCP port is free for OpenCode.
+// 📖 Used to avoid tmux sub-agent port conflicts when multiple projects run in parallel.
+function isTcpPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = createServer()
+    server.once('error', () => resolve(false))
+    server.once('listening', () => {
+      server.close(() => resolve(true))
+    })
+    server.listen(port)
+  })
+}
+
+// 📖 resolveOpenCodeTmuxPort: selects a safe port for OpenCode when inside tmux.
+// 📖 Priority:
+// 📖 1) OPENCODE_PORT from env (if valid and available)
+// 📖 2) First available port in 4096-5095
+async function resolveOpenCodeTmuxPort() {
+  const envPortRaw = process.env.OPENCODE_PORT
+  const envPort = Number.parseInt(envPortRaw || '', 10)
+
+  if (Number.isInteger(envPort) && envPort > 0 && envPort <= 65535) {
+    if (await isTcpPortAvailable(envPort)) {
+      return { port: envPort, source: 'env' }
+    }
+    console.log(chalk.yellow(`  ⚠ OPENCODE_PORT=${envPort} is already in use; selecting another port for this run.`))
+  }
+
+  for (let port = OPENCODE_PORT_RANGE_START; port < OPENCODE_PORT_RANGE_END; port++) {
+    if (await isTcpPortAvailable(port)) {
+      return { port, source: 'auto' }
+    }
+  }
+
+  return null
+}
 
 function getOpenCodeConfigPath() {
   if (existsSync(OPENCODE_CONFIG)) return OPENCODE_CONFIG
@@ -910,10 +1347,30 @@ async function spawnOpenCode(args, providerKey, fcmConfig) {
   const envVarName = ENV_VAR_NAMES[providerKey]
   const resolvedKey = getApiKey(fcmConfig, providerKey)
   const childEnv = { ...process.env }
+  const finalArgs = [...args]
+  const hasExplicitPortArg = finalArgs.includes('--port')
   if (envVarName && resolvedKey) childEnv[envVarName] = resolvedKey
 
+  // 📖 In tmux, OpenCode sub-agents need a listening port to open extra panes.
+  // 📖 We auto-pick one if the user did not provide --port explicitly.
+  if (process.env.TMUX && !hasExplicitPortArg) {
+    const tmuxPort = await resolveOpenCodeTmuxPort()
+    if (tmuxPort) {
+      const portValue = String(tmuxPort.port)
+      childEnv.OPENCODE_PORT = portValue
+      finalArgs.push('--port', portValue)
+      if (tmuxPort.source === 'env') {
+        console.log(chalk.dim(`  📺 tmux detected — using OPENCODE_PORT=${portValue}.`))
+      } else {
+        console.log(chalk.dim(`  📺 tmux detected — using OpenCode port ${portValue} for sub-agent panes.`))
+      }
+    } else {
+      console.log(chalk.yellow(`  ⚠ tmux detected but no free OpenCode port found in ${OPENCODE_PORT_RANGE_START}-${OPENCODE_PORT_RANGE_END - 1}; launching without --port.`))
+    }
+  }
+
   const { spawn } = await import('child_process')
-  const child = spawn('opencode', args, {
+  const child = spawn('opencode', finalArgs, {
     stdio: 'inherit',
     shell: true,
     detached: false,
@@ -936,7 +1393,7 @@ async function spawnOpenCode(args, providerKey, fcmConfig) {
 
 // ─── Start OpenCode ────────────────────────────────────────────────────────────
 // 📖 Launches OpenCode with the selected model.
-// 📖 Handles all 3 providers: nvidia (needs custom provider config), groq & cerebras (built-in in OpenCode).
+// 📖 Handles nvidia + all OpenAI-compatible providers defined in sources.js.
 // 📖 For nvidia: checks if NIM is configured, sets provider.models entry, spawns with nvidia/model-id.
 // 📖 For groq/cerebras: OpenCode has built-in support -- just sets model in config and spawns.
 // 📖 Model format: { modelId, label, tier, providerKey }
@@ -1024,6 +1481,14 @@ After installation, you can use: opencode --model ${modelRef}`
       await spawnOpenCode([], providerKey, fcmConfig)
     }
   } else {
+    if (providerKey === 'replicate') {
+      console.log(chalk.yellow('  ⚠ Replicate models are monitor-only for now in OpenCode mode.'))
+      console.log(chalk.dim('    Reason: Replicate uses /v1/predictions instead of OpenAI chat-completions.'))
+      console.log(chalk.dim('    You can still benchmark this model in the TUI and use other providers for OpenCode launch.'))
+      console.log()
+      return
+    }
+
     // 📖 Groq: built-in OpenCode provider -- needs provider block with apiKey in opencode.json.
     // 📖 Cerebras: NOT built-in -- needs @ai-sdk/openai-compatible + baseURL, like NVIDIA.
     // 📖 Both need the model registered in provider.<key>.models so OpenCode can find it.
@@ -1080,6 +1545,36 @@ After installation, you can use: opencode --model ${modelRef}`
           },
           models: {}
         }
+      } else if (providerKey === 'huggingface') {
+        config.provider.huggingface = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Hugging Face Inference',
+          options: {
+            baseURL: 'https://router.huggingface.co/v1',
+            apiKey: '{env:HUGGINGFACE_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'deepinfra') {
+        config.provider.deepinfra = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'DeepInfra',
+          options: {
+            baseURL: 'https://api.deepinfra.com/v1/openai',
+            apiKey: '{env:DEEPINFRA_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'fireworks') {
+        config.provider.fireworks = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Fireworks AI',
+          options: {
+            baseURL: 'https://api.fireworks.ai/inference/v1',
+            apiKey: '{env:FIREWORKS_API_KEY}'
+          },
+          models: {}
+        }
       } else if (providerKey === 'codestral') {
         config.provider.codestral = {
           npm: '@ai-sdk/openai-compatible',
@@ -1155,7 +1650,7 @@ After installation, you can use: opencode --model ${modelRef}`
 // ─── Start OpenCode Desktop ─────────────────────────────────────────────────────
 // 📖 startOpenCodeDesktop: Same config logic as startOpenCode, but opens the Desktop app.
 // 📖 OpenCode Desktop shares config at the same location as CLI.
-// 📖 Handles all 3 providers: nvidia (needs custom provider config), groq & cerebras (built-in).
+// 📖 Handles nvidia + all OpenAI-compatible providers defined in sources.js.
 // 📖 No need to wait for exit — Desktop app stays open independently.
 async function startOpenCodeDesktop(model, fcmConfig) {
   const providerKey = model.providerKey ?? 'nvidia'
@@ -1256,6 +1751,14 @@ ${isWindows ? 'set NVIDIA_API_KEY=your_key_here' : 'export NVIDIA_API_KEY=your_k
       console.log()
     }
   } else {
+    if (providerKey === 'replicate') {
+      console.log(chalk.yellow('  ⚠ Replicate models are monitor-only for now in OpenCode Desktop mode.'))
+      console.log(chalk.dim('    Reason: Replicate uses /v1/predictions instead of OpenAI chat-completions.'))
+      console.log(chalk.dim('    You can still benchmark this model in the TUI and use other providers for Desktop launch.'))
+      console.log()
+      return
+    }
+
     // 📖 Groq: built-in OpenCode provider — needs provider block with apiKey in opencode.json.
     // 📖 Cerebras: NOT built-in — needs @ai-sdk/openai-compatible + baseURL, like NVIDIA.
     // 📖 Both need the model registered in provider.<key>.models so OpenCode can find it.
@@ -1310,6 +1813,36 @@ ${isWindows ? 'set NVIDIA_API_KEY=your_key_here' : 'export NVIDIA_API_KEY=your_k
           },
           models: {}
         }
+      } else if (providerKey === 'huggingface') {
+        config.provider.huggingface = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Hugging Face Inference',
+          options: {
+            baseURL: 'https://router.huggingface.co/v1',
+            apiKey: '{env:HUGGINGFACE_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'deepinfra') {
+        config.provider.deepinfra = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'DeepInfra',
+          options: {
+            baseURL: 'https://api.deepinfra.com/v1/openai',
+            apiKey: '{env:DEEPINFRA_API_KEY}'
+          },
+          models: {}
+        }
+      } else if (providerKey === 'fireworks') {
+        config.provider.fireworks = {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'Fireworks AI',
+          options: {
+            baseURL: 'https://api.fireworks.ai/inference/v1',
+            apiKey: '{env:FIREWORKS_API_KEY}'
+          },
+          models: {}
+        }
       } else if (providerKey === 'codestral') {
         config.provider.codestral = {
           npm: '@ai-sdk/openai-compatible',
@@ -1521,7 +2054,7 @@ async function runFiableMode(config) {
   const pingPromises = results.map(r => {
     const rApiKey = getApiKey(config, r.providerKey)
     const url = sources[r.providerKey]?.url
-    return ping(rApiKey, r.modelId, url).then(({ code, ms }) => {
+    return ping(rApiKey, r.modelId, r.providerKey, url).then(({ code, ms }) => {
       r.pings.push({ ms, code })
       if (code === '200') {
         r.status = 'up'
@@ -1585,6 +2118,7 @@ async function main() {
 
   // 📖 Load JSON config (auto-migrates old plain-text ~/.free-coding-models if needed)
   const config = loadConfig()
+  ensureTelemetryConfig(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))
@@ -1600,9 +2134,27 @@ async function main() {
     }
   }
 
+  // 📖 Ask analytics consent only when not explicitly controlled by env or CLI flag.
+  await promptTelemetryConsent(config, cliArgs)
+
   // 📖 Backward-compat: keep apiKey var for startOpenClaw() which still needs it
   let apiKey = getApiKey(config, 'nvidia')
 
+  // 📖 Default mode: OpenCode CLI
+  let mode = 'opencode'
+  if (cliArgs.openClawMode) mode = 'openclaw'
+  else if (cliArgs.openCodeDesktopMode) mode = 'opencode-desktop'
+  else if (cliArgs.openCodeMode) mode = 'opencode'
+
+  // 📖 Track app opening early so fast exits are still counted.
+  // 📖 Must run before update checks because npm registry lookups can add startup delay.
+  void sendUsageTelemetry(config, cliArgs, {
+    event: 'app_start',
+    version: LOCAL_VERSION,
+    mode,
+    ts: new Date().toISOString(),
+  })
+
   // 📖 Check for updates in the background
   let latestVersion = null
   try {
@@ -1611,9 +2163,6 @@ async function main() {
     // Silently fail - don't block the app if npm registry is unreachable
   }
 
-  // 📖 Default mode: OpenCode CLI
-  let mode = 'opencode'
-
   // 📖 Show update notification menu if a new version is available
   if (latestVersion) {
     const action = await promptUpdateNotification(latestVersion)
@@ -1643,6 +2192,7 @@ async function main() {
 
   // 📖 Build results from MODELS — only include enabled providers
   // 📖 Each result gets providerKey so ping() knows which URL + API key to use
+
   let results = MODELS
     .filter(([,,,,,providerKey]) => isProviderEnabled(config, providerKey))
     .map(([modelId, label, tier, sweScore, ctx, providerKey], i) => ({
@@ -1657,7 +2207,7 @@ async function main() {
   // 📖 Called after every cursor move, sort change, and terminal resize.
   const adjustScrollOffset = (st) => {
     const total = st.visibleSorted ? st.visibleSorted.length : st.results.filter(r => !r.hidden).length
-    let maxSlots = st.terminalRows - 10  // 5 header + 5 footer
+    let maxSlots = st.terminalRows - TABLE_FIXED_LINES
     if (maxSlots < 1) maxSlots = 1
     if (total <= maxSlots) { st.scrollOffset = 0; return }
     // Ensure cursor is not above the visible window
@@ -1754,18 +2304,21 @@ async function main() {
   // 📖 Key "T" in settings = test API key for selected provider.
   function renderSettings() {
     const providerKeys = Object.keys(sources)
+    const telemetryRowIdx = providerKeys.length
     const EL = '\x1b[K'
     const lines = []
 
     lines.push('')
     lines.push(`  ${chalk.bold('⚙  Settings')}  ${chalk.dim('— free-coding-models v' + LOCAL_VERSION)}`)
     lines.push('')
-    lines.push(`  ${chalk.bold('Providers')}`)
+    lines.push(`  ${chalk.bold('🧩 Providers')}`)
+    lines.push(`  ${chalk.dim('  ' + '─'.repeat(112))}`)
     lines.push('')
 
     for (let i = 0; i < providerKeys.length; i++) {
       const pk = providerKeys[i]
       const src = sources[pk]
+      const meta = PROVIDER_METADATA[pk] || {}
       const isCursor = i === state.settingsCursor
       const enabled = isProviderEnabled(state.config, pk)
       const keyVal = state.config.apiKeys?.[pk] ?? ''
@@ -1789,20 +2342,50 @@ async function main() {
       if (testResult === 'pending') testBadge = chalk.yellow('[Testing…]')
       else if (testResult === 'ok')   testBadge = chalk.greenBright('[Test ✅]')
       else if (testResult === 'fail') testBadge = chalk.red('[Test ❌]')
+      const rateSummary = chalk.dim((meta.rateLimits || 'No limit info').slice(0, 36))
 
-      const enabledBadge = enabled ? chalk.greenBright('✅') : chalk.dim('⬜')
-      const providerName = chalk.bold(src.name.padEnd(10))
+      const enabledBadge = enabled ? chalk.greenBright('✅') : chalk.redBright('❌')
+      const providerName = chalk.bold((meta.label || src.name || pk).slice(0, 22).padEnd(22))
       const bullet = isCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
 
-      const row = `${bullet}[ ${enabledBadge} ] ${providerName}  ${keyDisplay.padEnd(30)}  ${testBadge}`
+      const row = `${bullet}[ ${enabledBadge} ] ${providerName}  ${keyDisplay.padEnd(30)}  ${testBadge}  ${rateSummary}`
       lines.push(isCursor ? chalk.bgRgb(30, 30, 60)(row) : row)
     }
 
+    lines.push('')
+    const selectedProviderKey = providerKeys[Math.min(state.settingsCursor, providerKeys.length - 1)]
+    const selectedSource = sources[selectedProviderKey]
+    const selectedMeta = PROVIDER_METADATA[selectedProviderKey] || {}
+    if (selectedSource && state.settingsCursor < telemetryRowIdx) {
+      const selectedKey = getApiKey(state.config, selectedProviderKey)
+      const setupStatus = selectedKey ? chalk.green('API key detected ✅') : chalk.yellow('API key missing ⚠')
+      lines.push(`  ${chalk.bold('Setup Instructions')} — ${selectedMeta.label || selectedSource.name || selectedProviderKey}`)
+      lines.push(chalk.dim(`  1) Create a ${selectedMeta.label || selectedSource.name} account: ${selectedMeta.signupUrl || 'signup link missing'}`))
+      lines.push(chalk.dim(`  2) ${selectedMeta.signupHint || 'Generate an API key and paste it with Enter on this row'}`))
+      lines.push(chalk.dim(`  3) Press ${chalk.yellow('T')} to test your key. Status: ${setupStatus}`))
+      lines.push('')
+    }
+
+    lines.push(`  ${chalk.bold('📊 Analytics')}`)
+    lines.push(`  ${chalk.dim('  ' + '─'.repeat(112))}`)
+    lines.push('')
+
+    const telemetryCursor = state.settingsCursor === telemetryRowIdx
+    const telemetryEnabled = state.config.telemetry?.enabled === true
+    const telemetryStatus = telemetryEnabled ? chalk.greenBright('✅ Enabled') : chalk.redBright('❌ Disabled')
+    const telemetryRowBullet = telemetryCursor ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+    const telemetryEnv = parseTelemetryEnv(process.env.FREE_CODING_MODELS_TELEMETRY)
+    const telemetrySource = telemetryEnv === null
+      ? chalk.dim('[Config]')
+      : chalk.yellow('[Env override]')
+    const telemetryRow = `${telemetryRowBullet}${chalk.bold('Anonymous usage analytics').padEnd(44)} ${telemetryStatus}  ${telemetrySource}`
+    lines.push(telemetryCursor ? chalk.bgRgb(30, 30, 60)(telemetryRow) : telemetryRow)
+
     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  •  Space Toggle enabled  •  T Test key  •  Esc Close'))
+      lines.push(chalk.dim('  ↑↓ Navigate  •  Enter Edit key / Toggle analytics  •  Space Toggle enabled  •  T Test key  •  Esc Close'))
     }
     lines.push('')
 
@@ -1838,7 +2421,7 @@ 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 per provider, enable/disable, test)')}`)
+    lines.push(`  ${chalk.yellow('P')}  Open settings  ${chalk.dim('(manage API keys, provider toggles, analytics toggle)')}`)
     lines.push(`  ${chalk.yellow('K')} / ${chalk.yellow('Esc')}  Show/hide this help`)
     lines.push(`  ${chalk.yellow('Ctrl+C')}  Exit`)
     lines.push('')
@@ -1861,7 +2444,7 @@ async function main() {
     if (!testModel) { state.settingsTestResults[providerKey] = 'fail'; return }
 
     state.settingsTestResults[providerKey] = 'pending'
-    const { code } = await ping(testKey, testModel, src.url)
+    const { code } = await ping(testKey, testModel, providerKey, src.url)
     state.settingsTestResults[providerKey] = code === '200' ? 'ok' : 'fail'
   }
 
@@ -1892,6 +2475,7 @@ async function main() {
     // ─── Settings overlay keyboard handling ───────────────────────────────────
     if (state.settingsOpen) {
       const providerKeys = Object.keys(sources)
+      const telemetryRowIdx = providerKeys.length
 
       // 📖 Edit mode: capture typed characters for the API key
       if (state.settingsEditMode) {
@@ -1953,12 +2537,20 @@ async function main() {
         return
       }
 
-      if (key.name === 'down' && state.settingsCursor < providerKeys.length - 1) {
+      if (key.name === 'down' && state.settingsCursor < telemetryRowIdx) {
         state.settingsCursor++
         return
       }
 
       if (key.name === 'return') {
+        if (state.settingsCursor === telemetryRowIdx) {
+          ensureTelemetryConfig(state.config)
+          state.config.telemetry.enabled = state.config.telemetry.enabled !== true
+          state.config.telemetry.consentVersion = TELEMETRY_CONSENT_VERSION
+          saveConfig(state.config)
+          return
+        }
+
         // 📖 Enter edit mode for the selected provider's key
         const pk = providerKeys[state.settingsCursor]
         state.settingsEditBuffer = state.config.apiKeys?.[pk] ?? ''
@@ -1967,6 +2559,14 @@ async function main() {
       }
 
       if (key.name === 'space') {
+        if (state.settingsCursor === telemetryRowIdx) {
+          ensureTelemetryConfig(state.config)
+          state.config.telemetry.enabled = state.config.telemetry.enabled !== true
+          state.config.telemetry.consentVersion = TELEMETRY_CONSENT_VERSION
+          saveConfig(state.config)
+          return
+        }
+
         // 📖 Toggle enabled/disabled for selected provider
         const pk = providerKeys[state.settingsCursor]
         if (!state.config.providers) state.config.providers = {}
@@ -1977,6 +2577,8 @@ async function main() {
       }
 
       if (key.name === 't') {
+        if (state.settingsCursor === telemetryRowIdx) return
+
         // 📖 Test the selected provider's key (fires a real ping)
         const pk = providerKeys[state.settingsCursor]
         testProviderKey(pk)
@@ -2181,7 +2783,7 @@ async function main() {
   const pingModel = async (r) => {
     const providerApiKey = getApiKey(state.config, r.providerKey) ?? null
     const providerUrl = sources[r.providerKey]?.url ?? sources.nvidia.url
-    const { code, ms } = await ping(providerApiKey, r.modelId, providerUrl)
+    const { code, ms } = await ping(providerApiKey, r.modelId, r.providerKey, providerUrl)
 
     // 📖 Store ping result as object with ms and code
     // 📖 ms = actual response time (even for errors like 429)