pi-free 2.0.0 → 2.0.2

package/README.md

@@ -6,21 +6,23 @@ Free AI model providers for [Pi](https://pi.dev). Access **free models** from mu
 
 ## What does pi-free do
 
-**pi-free is a Pi extension that unlocks free AI models from 9 providers — and adds 2 paid providers for convenience.**
+**pi-free is a Pi extension that unlocks free AI models from multiple providers.**
 
 When you install pi-free, it:
 
-1. **Registers 10+ AI providers** with Pi's model picker — 9 unique free-tier providers plus dynamic providers for Pi's built-in services when API keys are configured
+1. **Registers free-tier providers** with Pi's model picker — Kilo, Cline, NVIDIA, Cloudflare, Modal, Ollama Cloud, and more
 
-2. **Filters to show only free models by default** — You see only the models that cost $0 to use, no API key required for some providers. Paid-only providers are hidden until you explicitly enable them.
+2. **Fetches models dynamically** from provider APIs — Cloudflare Workers AI (30+ models), NVIDIA NIM, and Pi's built-in providers (Mistral, Groq, Cerebras, xAI, Hugging Face, OpenRouter) when API keys are configured
 
-3. **Provides a toggle command** — Run `/{provider}-toggle` (e.g., `/zen-toggle`, `/kilo-toggle`) to switch between free-only mode and showing all models including paid ones
+3. **Filters to show only free models by default** for providers that expose pricing — You see only the models that cost $0 to use. Paid models are hidden until you explicitly toggle them on.
 
-4. **Handles authentication for you** — OAuth flows (Kilo, Cline) open your browser automatically; API keys are read from `~/.pi/free.json` or environment variables
+4. **Provides per-provider toggle commands** — Run `/toggle-{provider}` (e.g., `/toggle-kilo`, `/toggle-opencode`) to switch between free-only mode and showing all models including paid ones. Changes apply immediately and your preference is saved for the next Pi restart.
 
-5. **Adds Coding Index scores** — Model names include a coding benchmark score (CI: 45.2) to help you pick capable coding models at a glance
+5. **Handles authentication for you** — OAuth flows (Kilo, Cline) open your browser automatically; API keys are read from `~/.pi/free.json` or environment variables
 
-6. **Persists your preferences** — Your toggle choices (free vs all models) are saved to `~/.pi/free.json` and remembered across Pi restarts
+6. **Adds Coding Index scores** — Model names include a coding benchmark score (CI: 45.2) to help you pick capable coding models at a glance
+
+7. **Persists your preferences** — Your toggle choices (free vs all models) are saved to `~/.pi/free.json` and remembered across Pi restarts
 
 ---
 
@@ -39,24 +41,26 @@ Start Pi and press `Ctrl+L` to open the model picker.
 Free models are shown by default — look for the provider prefixes:
 
 **✅ Offers Free Models (no usage limits, no payment required):**
-- `zen/` — OpenCode Zen models (no setup required)
+
+- `opencode/` — OpenCode models (no setup required; toggle with `/toggle-opencode`)
 - `kilo/` — Kilo models (free models available immediately, more after `/login kilo`)
 - `openrouter/` — OpenRouter models (free account required)
 - `cline/` — Cline models (run `/login cline` to use)
 
 **🔄 Freemium (free tier with limits, then paid):**
+
 - `nvidia/` — NVIDIA NIM models (1,000 free requests/month, then credits)
 - `cloudflare/` — Cloudflare Workers AI (10K Neurons/day free tier, then $0.011/1K Neurons)
 - `modal/` — GLM-5.1 FP8 via Modal (free promotional period until April 30, 2026)
-- `ollama/` — Ollama Cloud models (usage-based free tier, resets every 5 hours + 7 days)
+- `ollama-cloud/` — Ollama Cloud models (usage-based free tier, resets every 5 hours + 7 days)
 
-**🔧 Dynamic API Providers (free models when API key configured):**
-- `mistral/` — Mistral models (free models via API when `MISTRAL_API_KEY` set)
-- `groq/` — Groq models (free models via API when `GROQ_API_KEY` set)
-- `cerebras/` — Cerebras models (free models via API when `CEREBRAS_API_KEY` set)
+**🔧 Dynamic API Providers (fetched when API key configured):**
 
-**💳 Paid Only (no free tier):**
-- `go/` — OpenCode Go models (requires subscription — $5 first month, then $10/month)
+- `mistral/` — Mistral models (when `MISTRAL_API_KEY` set)
+- `groq/` — Groq models (when `GROQ_API_KEY` set)
+- `cerebras/` — Cerebras models (when `CEREBRAS_API_KEY` set)
+- `xai/` — xAI models (when `XAI_API_KEY` set)
+- `huggingface/` — Hugging Face models (when `HF_TOKEN` set)
 
 **Note:** Fireworks is now a [built-in Pi provider](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/CHANGELOG.md#0681---2026-04-22) — no extension needed. Set `FIREWORKS_API_KEY` to use it directly.
 
@@ -65,27 +69,34 @@ Free models are shown by default — look for the provider prefixes:
 Want to see paid models too? Run the toggle command for your provider:
 
 ```
-/zen-toggle         # Toggle Zen (✅ offers free models)
-/kilo-toggle        # Toggle Kilo (✅ offers free models)
-/openrouter-toggle  # Toggle OpenRouter (✅ offers free models)
-/cline-toggle      # Toggle Cline (✅ offers free models)
-/mistral-toggle     # Toggle Mistral (🔧 dynamic - needs API key)
-/groq-toggle        # Toggle Groq (🔧 dynamic - needs API key)
-/cerebras-toggle   # Toggle Cerebras (🔧 dynamic - needs API key)
+/toggle-opencode   # Toggle OpenCode (✅ offers free models)
+/toggle-kilo       # Toggle Kilo (✅ offers free models)
+/toggle-openrouter # Toggle OpenRouter (✅ offers free models)
+/toggle-cline      # Toggle Cline (✅ offers free models)
+/toggle-nvidia     # Toggle NVIDIA (🔄 freemium)
+/toggle-cloudflare # Toggle Cloudflare (🔄 freemium)
+/toggle-ollama     # Toggle Ollama Cloud (🔄 freemium)
+/toggle-mistral    # Toggle Mistral (🔧 dynamic - needs API key)
+/toggle-groq       # Toggle Groq (🔧 dynamic - needs API key)
+/toggle-cerebras   # Toggle Cerebras (🔧 dynamic - needs API key)
 ```
 
 **Notes:**
-- **Toggle commands are mainly for ✅ Offers Free Models providers** — to switch between "free models only" vs "show paid models too"
-- **🔄 Freemium providers** (NVIDIA, Cloudflare, Ollama, Modal) show all models by default — you manage your usage limits via their dashboards
-- **💳 Paid-only providers** (Go) have no toggle since all models require payment
 
-You'll see a notification like: `zen: showing free models` or `zen: showing all models (including paid)`
+- **Toggle commands are mainly for ✅ and 🔄 providers** — to switch between "free models only" vs "show paid models too"
+- **🔧 Dynamic providers** show all fetched models by default — the toggle filters the list when you have an API key configured
+- **Freemium providers** show all models by default; you manage your usage limits via their dashboards
+
+You'll see a notification like: `opencode: showing free models` or `opencode: showing all models`
+
+**Note:** Built-in provider toggles such as OpenCode and OpenRouter update in the current session — no restart needed.
 
 ### 4. Add API keys for more providers (optional)
 
 Some providers require a free account or API key.
 
 **The first time you run Pi after installing this extension, a config file is automatically created:**
+
 - **Linux/Mac:** `~/.pi/free.json`
 - **Windows:** `%USERPROFILE%\.pi\free.json`
 
@@ -96,74 +107,109 @@ Add your API keys to this file:
   "openrouter_api_key": "sk-or-v1-...",
   "nvidia_api_key": "nvapi-...",
   "cloudflare_api_token": "...",
+  "cloudflare_account_id": "...",
   "ollama_api_key": "...",
   "mistral_api_key": "...",
   "modal_api_key": "sk-modal-..."
 }
 ```
 
-**Note:** Fireworks is now a [built-in Pi provider](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/CHANGELOG.md#0681---2026-04-22) — no extension needed. Set `FIREWORKS_API_KEY` to use it directly.
-
 Or set environment variables instead (same names, uppercase: `OPENROUTER_API_KEY`, `NVIDIA_API_KEY`, etc.)
 
+If `~/.pi/free.json` contains invalid JSON, pi-free now logs the parse error to `~/.pi/free.log` so you can fix the file quickly.
+
 See the [Providers That Need Authentication](#providers-that-need-authentication) section below for detailed setup instructions per provider.
 
 ### 5. Quick commands reference
 
-| Command | What it does |
-|---------|-------------|
-| `/{provider}-toggle` | Switch between free-only and all models for that provider |
-| `/login kilo` | Start OAuth flow for Kilo |
-| `/login cline` | Start OAuth flow for Cline |
-| `/logout kilo` | Clear Kilo OAuth credentials |
-| `/logout cline` | Clear Cline OAuth credentials |
+| Command              | What it does                                              |
+| -------------------- | --------------------------------------------------------- |
+| `/toggle-{provider}` | Switch between free-only and all models for that provider |
+| `/free-providers`    | Show free/paid model counts for all providers             |
+| `/login kilo`        | Start OAuth flow for Kilo                                 |
+| `/login cline`       | Start OAuth flow for Cline                                |
+| `/logout kilo`       | Clear Kilo OAuth credentials                              |
+| `/logout cline`      | Clear Cline OAuth credentials                             |
 
 ---
 
-## Using Free Models (No Setup Required)
+## Features
 
-### OpenCode Zen — Easiest Start
+### 🔍 NVIDIA: Pre-Filtering + 404 Detection
 
-Works immediately with zero setup:
+NVIDIA's API lists 130+ models, but 57+ return 404 "Function not found" when you try to use them. pi-free solves this:
 
-1. Press `Ctrl+L`
-2. Search for `zen/`
-3. Pick any model (e.g., `zen/mimo-v2-omni-free`)
-4. Start chatting
+- **57 known 404s hard-filtered** — Discontinued models (`dbrx-instruct`, `codellama-70b`), embedding models mislabeled as chat-capable (`nv-embed-*`), and stale catalog entries are silently excluded
+- **Auto-discovery from NVIDIA's API** — Queries `integrate.api.nvidia.com/v1/models` directly for the ground-truth list
+- **`/probe-nvidia` command** — On-demand health check: tests every model with a minimal request, auto-hides new 404s, and re-registers immediately
 
-No account, no API key, no OAuth.
+### 🌩️ Cloudflare: Dynamic Model Discovery
 
-### Ollama Cloud
+Cloudflare Workers AI offers 80+ models including embeddings, image generation, and speech. pi-free automatically finds the chat models:
 
-Get an API key from [ollama.com/settings/keys](https://ollama.com/settings/keys), then:
+- **Live API fetching** — Calls Cloudflare's `/ai/models` endpoint on startup to get the current catalog
+- **Smart filtering** — Automatically excludes embeddings (`bge-*`, `embed-*`), image generation (`flux`, `stable-diffusion`), speech (`whisper`, `aura-*`), translation, and vision-only models via regex patterns
+- **Metadata inference** — Detects vision support (`llava`, `vision` in name), reasoning (`r1`, `thinking`, `qwq`), context windows, and estimated costs from model IDs
+- **Expanding fallback** — 18 hand-curated models (Kimi K2.6, GPT-OSS, Qwen 2.5 Coder, QwQ, Llama 3.2 Vision, etc.) if API is unreachable
 
-**Option A: Environment variable**
-```bash
-export OLLAMA_API_KEY="..."
-export OLLAMA_SHOW_PAID=true
-```
+### 🎯 Coding Index (CI) Scores
 
-**Option B: Config file** (`~/.pi/free.json`)
-```json
-{
-  "ollama_api_key": "YOUR_KEY",
-  "ollama_show_paid": true
-}
-```
+Every model shows a **Coding Index score** (e.g., `CI: 52.3`) in the model picker:
 
-**Note:** Ollama requires `OLLAMA_SHOW_PAID=true` because they have usage limits on their cloud API.
+- **Benchmark-based** — Scores derived from Artificial Analysis coding benchmarks (HumanEval, MBPP, etc.)
+- **Quality indicator** — Higher scores = better coding performance
+- **All providers** — Applied to every model from every provider (NVIDIA, Cloudflare, Mistral, Groq, etc.)
 
-Free tier resets every 5 hours + 7 days.
+**Missing CI scores?** Provider model IDs often don't match benchmark database keys exactly. pi-free applies provider-specific normalization to improve matching:
 
----
+| Provider       | Normalization Applied                                              |
+| -------------- | ------------------------------------------------------------------ |
+| **NVIDIA**     | Strips vendor prefixes (`meta/`, `mistralai/`, `microsoft/`, etc.) |
+| **Cloudflare** | Strips `@cf/namespace/` prefixes                                   |
+| **Groq**       | Removes `-versatile` and numeric suffixes (`-32768`)               |
+| **Cerebras**   | Normalizes `llama3.1` → `llama-3.1`, adds `instruct` suffix        |
+| **Mistral**    | Strips `-latest` suffix                                            |
+| **Ollama**     | Converts `model:tag` → `model-tag`                                 |
 
-## Providers That Need Authentication
+**Debug missing scores:** Check `~/.pi/modelmatch.log` to see which models matched/didn't match and what normalization was applied.
+
+### 🔄 Free/Paid Model Toggling
+
+Providers have different pricing models. pi-free handles them all:
+
+- **Free-only by default** — Shows only zero-cost models initially
+- **Per-provider toggles** — Run `/toggle-{provider}` to switch between "free only" vs "all models"
+- **Persists across sessions** — Your preference is saved to `~/.pi/free.json`
+- **Instant updates** — Changes apply immediately; no Pi restart needed
+
+**Provider types:**
 
-Some providers require free accounts or OAuth to access their free tiers. **Go is a paid-only provider — it has no free tier.**
+- ✅ **Free providers** (OpenCode, Kilo, Cline) — Toggle between free-only vs paid models
+- 🔄 **Freemium** (NVIDIA, Cloudflare, Modal, Ollama) — Free tier with limits, toggle shows all
+- 🔧 **Dynamic API** (Mistral, Groq, Cerebras, xAI) — Fetched when API key configured, toggle filters the list
+
+### 🔐 OAuth + API Key Handling
+
+Authentication is handled automatically:
+
+- **OAuth flows** — `/login kilo` and `/login cline` open your browser, wait for authorization, and complete automatically
+- **Multiple auth sources** — API keys read from `~/.pi/free.json`, environment variables, or standard Pi auth files (`~/.pi/agent/auth.json`)
+- **Smart fallbacks** — New env var names (e.g., `CF_API_TOKEN`) with legacy support (`CLOUDFLARE_API_TOKEN`)
 
 ---
 
-### 🆓 Free Providers
+## Using Free Models (No Setup Required)
+
+### OpenCode
+
+Works immediately with zero setup:
+
+1. Press `Ctrl+L`
+2. Search for `opencode/`
+3. Pick any model (e.g., `opencode/big-pickle`)
+4. Start chatting
+
+No account, no API key, no OAuth. Run `/toggle-opencode` to switch between free and paid OpenCode models.
 
 ### Kilo (free models, more after login)
 
@@ -174,6 +220,7 @@ Kilo shows free models immediately. To unlock all models, authenticate with Kilo
 ```
 
 This command will:
+
 1. Open your browser to Kilo's authorization page
 2. Show a device code in Pi's UI
 3. Wait for you to authorize in the browser
@@ -181,52 +228,83 @@ This command will:
 
 - No credit card required
 - Free tier: 200 requests/hour
-- After login, run `/kilo-toggle` to switch between free-only and all models
+- After login, run `/toggle-kilo` to switch between free-only and all models
+
+### Cline (free account)
+
+Cline models appear immediately in the model picker. To use them, authenticate with Cline's free account:
+
+```
+/login cline
+```
+
+This command will:
+
+1. Open your browser to Cline's sign-in page
+2. Wait for you to complete sign-in
+3. Automatically complete login once approved
+
+- Free account required (no credit card)
+- Uses local ports 48801-48811 for OAuth callback
+
+---
+
+## Providers That Need Authentication
+
+Some providers require a free account or API key to access their free tiers.
+
+---
+
+### 🆓 Free Providers
 
 ### OpenRouter (free models available)
 
 Get a free API key at [openrouter.ai/keys](https://openrouter.ai/keys), then either:
 
 **Option A: Environment variable**
+
 ```bash
 export OPENROUTER_API_KEY="sk-or-v1-..."
 ```
 
 **Option B: Config file** (`~/.pi/free.json`)
+
 ```json
 {
   "openrouter_api_key": "sk-or-v1-..."
 }
 ```
 
-Then in Pi:
-```
-/openrouter-all   # Show all models (free + paid)
-```
+Then use `/toggle-openrouter` to switch between free-only and all models.
 
 ### NVIDIA NIM (Free Credits System)
 
 NVIDIA provides **free monthly credits** (1000 requests/month) at [build.nvidia.com](https://build.nvidia.com).
 
 **Important:** Models have different "costs" per token:
+
 - **Zero-cost models**: Don't consume your credit balance (shown by default)
 - **Credit-costing models**: Consume credits faster (hidden by default)
 
 Get your API key and optionally enable all models:
 
 **Option A: Show only free models (default)**
+
 ```bash
 export NVIDIA_API_KEY="nvapi-..."
 ```
+
 Uses only zero-cost models → your 1000 credits last the full month
 
 **Option B: Show all models (uses credits faster)**
+
 ```bash
 export NVIDIA_API_KEY="nvapi-..."
 export NVIDIA_SHOW_PAID=true
 ```
 
 Or in `~/.pi/free.json`:
+
 ```json
 {
   "nvidia_api_key": "nvapi-...",
@@ -234,58 +312,49 @@ Or in `~/.pi/free.json`:
 }
 ```
 
-Toggle anytime with `/nvidia-toggle`
+Toggle anytime with `/toggle-nvidia`
 
 ### Cloudflare Workers AI (10K Neurons/day Free Tier)
 
-Cloudflare provides **50+ open-source AI models** with a generous free tier:
+Cloudflare provides **30+ text generation models** (auto-discovered from their API) with a generous free tier:
+
 - **10,000 Neurons per day FREE** (resets daily at 00:00 UTC)
 - **$0.011 per 1,000 Neurons** beyond the free allocation
+- **Models auto-fetched** — All available chat models are discovered dynamically from Cloudflare's API
 
 Get your API token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens):
+
 1. Create a token with "Cloudflare AI" → "Read" permission
 2. Or use "My Account" → "Read" for broader access
 
 **Setup:**
-```bash
-export CLOUDFLARE_API_TOKEN="your_token_here"
-```
 
-The account ID is automatically derived from your token. Optionally, you can also set:
 ```bash
-export CLOUDFLARE_ACCOUNT_ID="your_account_id"  # Optional
-```
+# New short env vars (recommended)
+export CF_API_TOKEN="your_token_here"
+export CF_ACCOUNT_ID="your_account_id"
 
-**Models available:** Llama 4, Mistral Small 3.1, DeepSeek R1, Gemma 4, Kimi K2.5/2.6, and more.
-
-Toggle with `/cloudflare-toggle`
-
-### Cline (free account)
-
-Cline models appear immediately in the model picker. To use them, authenticate with Cline's free account:
-
-```
-/login cline
+# Legacy env vars also work
+export CLOUDFLARE_API_TOKEN="your_token_here"
+export CLOUDFLARE_ACCOUNT_ID="your_account_id"
 ```
 
-This command will:
-1. Open your browser to Cline's sign-in page
-2. Wait for you to complete sign-in
-3. Automatically complete login once approved
+**Models available:** Llama 4/3.x, Mistral Small 3.1, DeepSeek R1, Gemma 4, Kimi K2.5/2.6, Qwen 3/2.5, OpenAI GPT-OSS, and more.
 
-- Free account required (no credit card)
-- Uses local ports 48801-48811 for OAuth callback
+Toggle with `/toggle-cloudflare`
 
 ### Modal (GLM-5.1 FP8 — free promotional period until April 30, 2026)
 
 Modal hosts GLM-5.1 FP8 with a free promotional period. Get an API key at [modal.com](https://modal.com), then:
 
 **Option A: Environment variable**
+
 ```bash
 export MODAL_API_KEY="sk-modal-..."
 ```
 
 **Option B: Config file** (`~/.pi/free.json`)
+
 ```json
 {
   "modal_api_key": "sk-modal-..."
@@ -295,41 +364,42 @@ export MODAL_API_KEY="sk-modal-..."
 Then select a `modal/` model in the model picker.
 
 **Details:**
+
 - Free promotional period until April 30, 2026
 - Model: GLM-5.1 FP8 (128k context, 16k max output)
 - No credit card required during the promotional period
 
-### Mistral (free API key)
+### Ollama Cloud
 
-Add API key to `~/.pi/free.json` or environment variables:
+Get an API key from [ollama.com/settings/keys](https://ollama.com/settings/keys), then:
+
+**Option A: Environment variable**
 
 ```bash
-export MISTRAL_API_KEY="..."
+export OLLAMA_API_KEY="..."
+export OLLAMA_SHOW_PAID=true
 ```
 
----
-
-### 💳 Paid-Only Providers
-
-> **⚠️ These providers have no free tier. All usage incurs costs.**
+**Option B: Config file** (`~/.pi/free.json`)
 
-### OpenCode Go (subscription — $5 first month, then $10/month)
+```json
+{
+  "ollama_api_key": "YOUR_KEY",
+  "ollama_show_paid": true
+}
+```
 
-Go provides access to curated open coding models via a monthly subscription. There is no free tier.
+**Note:** Ollama requires `OLLAMA_SHOW_PAID=true` because they have usage limits on their cloud API.
 
-Set `OPENCODE_GO_API_KEY` (or `opencode_go_api_key` in `~/.pi/free.json`) and `GO_SHOW_PAID=true` to enable.
+Free tier resets every 5 hours + 7 days.
 
-**Models available:**
-- GLM-5
-- Kimi K2.5
-- MiMo-V2-Pro
-- MiMo-V2-Omni
-- MiniMax M2.7
-- MiniMax M2.5
+### Mistral (free API key)
 
-**Pricing:** $5 first month, then $10/month. See [opencode.ai/docs/go](https://opencode.ai/docs/go).
+Add API key to `~/.pi/free.json` or environment variables:
 
-Toggle with `/go-toggle`.
+```bash
+export MISTRAL_API_KEY="..."
+```
 
 ---
 
@@ -337,23 +407,45 @@ Toggle with `/go-toggle`.
 
 Each provider has toggle commands to switch between free and all models:
 
-| Command | Action |
-|---------|--------|
-| `/zen-toggle` | Toggle between free/all Zen models |
-| `/kilo-toggle` | Toggle between free/all Kilo models |
-| `/openrouter-toggle` | Toggle between free/all OpenRouter models |
-| `/cline-toggle` | Toggle between free/all Cline models (✅ offers free models) |
-| `/mistral-toggle` | Toggle between free/all Mistral models (🔧 dynamic) |
-| `/groq-toggle` | Toggle between free/all Groq models (🔧 dynamic) |
-| `/cerebras-toggle` | Toggle between free/all Cerebras models (🔧 dynamic) |
+| Command              | Action                                               |
+| -------------------- | ---------------------------------------------------- |
+| `/toggle-opencode`   | Toggle between free/all OpenCode models              |
+| `/toggle-kilo`       | Toggle between free/all Kilo models                  |
+| `/toggle-openrouter` | Toggle between free/all OpenRouter models            |
+| `/toggle-cline`      | Toggle between free/all Cline models                 |
+| `/toggle-nvidia`     | Toggle between free/all NVIDIA models                |
+| `/toggle-cloudflare` | Toggle between free/all Cloudflare models            |
+| `/toggle-ollama`     | Toggle between free/all Ollama Cloud models          |
+| `/toggle-mistral`    | Toggle between free/all Mistral models (🔧 dynamic)  |
+| `/toggle-groq`       | Toggle between free/all Groq models (🔧 dynamic)     |
+| `/toggle-cerebras`   | Toggle between free/all Cerebras models (🔧 dynamic) |
 
 **The toggle command:**
-- **For ✅ Offers Free Models providers**: Switches between showing only free models vs. all available models (including paid)
-- **For 🔧 Dynamic API providers**: Filters the model list when you have an API key configured
+
+- **For ✅ free providers**: Switches between showing only free models vs. all available models (including paid)
+- **For 🔄 freemium providers**: Shows all models by default; toggle switches between filtered and full list
+- **For 🔧 dynamic API providers**: Filters the model list when you have an API key configured
 - **Persists your preference** to `~/.pi/free.json` for next startup
-- Shows a notification: "zen: showing free models" or "zen: showing all models (including paid)"
+- Shows a notification: "opencode: showing free models" or "opencode: showing all models"
+
+### Probe Commands (Health Check)
+
+Test models for 404/403 errors and auto-hide broken ones:
+
+| Command         | What it does                                                |
+| --------------- | ----------------------------------------------------------- |
+| `/probe-nvidia` | Test all NVIDIA models, auto-hide 404s in `~/.pi/free.json` |
+| `/probe-ollama` | Test all Ollama models, auto-hide 403s in `~/.pi/free.json` |
+
+**How it works:**
+
+1. Sends a minimal test request to every model
+2. Identifies broken models (404/403 responses)
+3. **Auto-hides** broken models in your config (provider-scoped: `"ollama/kimi-k2.6"`)
+4. Re-registers the provider so broken models disappear immediately
+5. Hidden models persist across Pi restarts
 
-**Note:** 🔄 Freemium providers (NVIDIA, Cloudflare, Ollama Cloud, Modal) don't have toggle commands — they show all models and you manage usage via their dashboards. 💳 Paid-only providers (Go) also have no toggle since all models require payment.
+Use these when you see models that appear in the picker but fail when you try to use them.
 
 ---
 
@@ -365,9 +457,10 @@ Create `~/.pi/free.json` in your home directory:
 {
   "openrouter_api_key": "YOUR_OPENROUTER_KEY",
   "nvidia_api_key": "YOUR_NVIDIA_KEY",
+  "cloudflare_api_token": "YOUR_CLOUDFLARE_TOKEN",
+  "cloudflare_account_id": "YOUR_ACCOUNT_ID",
   "mistral_api_key": "YOUR_MISTRAL_KEY",
-  "opencode_api_key": "YOUR_ZEN_KEY",
-  "opencode_go_api_key": "YOUR_GO_KEY",
+  "opencode_api_key": "YOUR_OPENCODE_KEY",
   "ollama_api_key": "YOUR_OLLAMA_KEY",
   "ollama_show_paid": true,
   "modal_api_key": "YOUR_MODAL_KEY",
@@ -386,12 +479,12 @@ export NVIDIA_API_KEY="..."
 
 ## Logging & Debugging
 
-pi-free now writes extension logs to:
+pi-free writes extension logs to:
 
 - **Windows:** `%USERPROFILE%\.pi\free.log`
 - **Linux/macOS:** `~/.pi/free.log`
 
-Useful env vars:
+If the extension fails to read `~/.pi/free.json`, check this log first — config parse errors are written here.
 
 ```bash
 # Console log verbosity (default: error)
@@ -407,6 +500,45 @@ PI_FREE_LOG_PATH=/tmp/pi-free.log
 PI_FREE_FILE_LOG=false
 ```
 
+### Model Matching Debug Log
+
+To diagnose why some models don't show Coding Index scores, pi-free writes detailed matching diagnostics to:
+
+- **Windows:** `%USERPROFILE%\.pi\modelmatch.log`
+- **Linux/macOS:** `~/.pi/modelmatch.log`
+
+**Log format:**
+
+```
+timestamp|provider|modelId|modelName|action|strategy|normalizedId|matchKey|codingIndex|details
+```
+
+**Example entries:**
+
+```
+2026-04-26T10:30:00Z|nvidia|meta/llama-3.1-405b-instruct|Llama 3.1 405B|match|provider-normalized:strip-nvidia-prefix|llama-3.1-405b-instruct|llama-3.1-instruct-405b|52.3|
+2026-04-26T10:30:01Z|groq|llama-3.1-70b-versatile|Llama 3.1 70B Versatile|match|strip-groq-versatile|llama-3.1-70b|llama-3.1-instruct-70b|48.5|
+2026-04-26T10:30:02Z|cloudflare|@cf/meta/llama-3.1-70b|Llama 3.1 70B|miss|all-strategies-failed|llama-3.1-70b|||
+```
+
+**Common mismatch patterns:**
+
+- `miss` + `all-strategies-failed` = Model not in benchmark database or ID format not recognized
+- Check `normalizedId` column to see what the lookup tried against
+
+**View the log:**
+
+```bash
+# Pretty-print with column alignment
+cat ~/.pi/modelmatch.log | column -t -s '|'
+
+# See only misses (models without CI scores)
+grep '|miss|' ~/.pi/modelmatch.log
+
+# See stats for specific provider
+grep '|nvidia|' ~/.pi/modelmatch.log | grep -c '|match|'
+```
+
 ---
 
 ## License