pi-free 2.2.2 → 2.2.4

package/README.md

@@ -14,574 +14,83 @@ Free and paid AI model providers for [Pi](https://pi.dev). Access **free and pai
 
 When you install pi-free, it:
 
-1. **Registers free-tier providers** with Pi's model picker — Kilo (free), Cline (free), LLM7 (free), TokenRouter (1 free model), ZenMux (paid), CrofAI (paid), b.ai (paid, 1 free promo model), Ollama Cloud (freemium), SambaNova (freemium), Codestral (freemium), DeepInfra (trial credit), Together AI (trial credit), Novita (paid), Routeway (paid), and more
-
-2. **Captures Pi's built-in OpenCode and OpenRouter providers** with a free/paid toggle — OpenCode and OpenRouter are now built into Pi; pi-free adds `/toggle-opencode` and `/toggle-openrouter` so you can switch between free-only and all models without restart
-
-3. **Fetches models dynamically** from provider APIs — ZenMux, CrofAI, and Pi's built-in providers (Mistral, Groq, Cerebras, xAI, Hugging Face, OpenRouter) when API keys are configured
-
-4. **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.
-
-5. **Provides per-provider toggle commands** — Run `/toggle-{provider}` (e.g., `/toggle-kilo`) 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.
-
-6. **Handles authentication for you** — OAuth flows (Kilo, Cline) open your browser automatically; API keys are read from `~/.pi/free.json` or environment variables
-
-7. **Adds Coding Index scores** — Model names include a coding benchmark score (CI: 45.2) to help you pick capable coding models at a glance
-
-8. **Persists your preferences** — Your toggle choices (free vs all models) are saved to `~/.pi/free.json` and remembered across Pi restarts
+1. **Registers free-tier providers** — Kilo, Cline, LLM7, OpenModel, TokenRouter, and more
+2. **Captures Pi's built-in providers** with free/paid toggles — OpenCode, OpenRouter
+3. **Fetches models dynamically** — ZenMux, CrofAI, Mistral, Groq, Cerebras, xAI, Hugging Face when API keys are configured
+4. **Filters to show only free models by default** — paid models hidden until explicitly toggled on
+5. **Provides per-provider toggle commands** — `/toggle-{provider}` switches free ↔ all immediately
+6. **Handles authentication** — OAuth flows open your browser; API keys from `~/.pi/free.json` or env vars
+7. **Adds Coding Index scores** — model names include benchmark scores (`CI: 45.2`) for quick comparison
+8. **Auto-probes and hides broken models** — expired free tiers and decommissioned models detected automatically
 
 ---
 
-## How to use
-
-### 1. Install the extension
+## Install
 
 ```bash
 pi install git:github.com/apmantza/pi-free
 ```
 
-### 2. Open the model picker
-
-Start Pi and press `Ctrl+L` to open the model picker.
-
-Free models are shown by default — look for the provider prefixes:
-
-**✅ Free Models (no payment required):**
-
-- `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)
-- `llm7/` — LLM7 gateway models (free tier: default/fast selectors, 100 req/hr)
-- `tokenrouter/` — TokenRouter gateway (1 free model: `MiniMax-M3`; requires API key with credits for the rest)
-
-**🔄 Freemium (free tier with limits, then paid):**
-
-- `ollama-cloud/` — Ollama Cloud models (usage-based free tier, resets every 5 hours + 7 days)
-- `sambanova/` — SambaNova Cloud models (20-480 RPM free, no credit card required)
-- `codestral/` — Codestral via Mistral (free Experiment plan: 2 req/min, 1B tokens/month)
-
-**💳 Paid Providers (API key with credits required):**
-
-- `zenmux/` — ZenMux AI gateway (200+ models from OpenAI, Anthropic, Google, etc.)
-- `crofai/` — CrofAI OpenAI-compatible API (streaming, reasoning models)
-- `deepinfra/` — DeepInfra inference cloud ($5 one-time trial credit, no credit card)
-- `novita/` — Novita AI (100+ open-source models, OpenAI-compatible, 3 free models)
-- `routeway/` — Routeway AI gateway (OpenAI-compatible, `:free` models)
-- `together/` — Together AI ($1 one-time trial credit, 200+ open-source models)
-
-> **Note:** Paid providers may occasionally offer free models or promotional credits. The `isFreeModel` helper automatically detects free models based on provider pricing data or model names containing "free". For providers that don't expose pricing (like CrofAI), only models with "free" in their names are marked as free.
-
-**🔧 Dynamic API Providers (fetched when API key configured):**
-
-- `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)
-- `openrouter/` — OpenRouter models (fetched from openrouter.ai, when `OPENROUTER_API_KEY` set)
-- `fastrouter/` — FastRouter models (always discovered, 170+ models, no auth for listing)
-
-**Note:** Fireworks and NVIDIA NIM are now [built-in Pi providers](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/CHANGELOG.md#0681---2026-04-22) — no extension needed. Set `FIREWORKS_API_KEY` or `NVIDIA_API_KEY` to use them directly.
-
-### 3. Toggle between free and paid models
-
-Want to see paid models too? Run the toggle command for your provider:
-
-```
-/toggle-kilo       # Toggle Kilo (✅ offers free models)
-/toggle-openrouter # Toggle OpenRouter (✅ offers free models)
-/toggle-opencode   # Toggle OpenCode (✅ offers free models)
-/toggle-cline      # Toggle Cline (✅ offers free models)
-/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)
-/toggle-xai        # Toggle xAI (🔧 dynamic - needs API key)
-/toggle-huggingface # Toggle Hugging Face (🔧 dynamic - needs HF_TOKEN)
-/toggle-zenmux    # Toggle ZenMux (💳 paid - needs API key with credits)
-/toggle-crofai    # Toggle CrofAI (💳 paid - needs API key with credits)
-/toggle-codestral # Toggle Codestral (🔄 free Experiment plan)
-/toggle-deepinfra # Toggle DeepInfra (💳 trial credit provider)
-/toggle-together  # Toggle Together AI (💳 trial credit provider)
-/toggle-sambanova # Toggle SambaNova (🔄 freemium)
-/toggle-llm7      # Toggle LLM7 (✅ free gateway)
-/toggle-novita    # Toggle Novita AI (💳 paid — 3 free models)
-/toggle-routeway  # Toggle Routeway AI (💳 paid — has :free models)
-/toggle-fastrouter # Toggle FastRouter (🔧 dynamic — always discovered)
-/toggle-tokenrouter # Toggle TokenRouter (💳 paid — 1 free model)
-```
-
-**Notes:**
-
-- **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
-
-### 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`
-
-Add your API keys to this file:
-
-```json
-{
-  "ollama_api_key": "...",
-  "mistral_api_key": "...",
-  "codestral_api_key": "...",
-  "deepinfra_api_key": "...",
-  "sambanova_api_key": "...",
-  "llm7_api_key": "...",
-  "zenmux_api_key": "...",
-  "crofai_api_key": "...",
-  "routeway_api_key": "sk-..."
-}
-```
-
-Or set environment variables instead (same names, uppercase: `OPENROUTER_API_KEY`, `OLLAMA_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                                              |
-| -------------------------- | --------------------------------------------------------- |
-| `/toggle-{provider}`       | Switch between free-only and all models for that provider |
-| `/toggle-free`             | Toggle global free-only mode for ALL providers            |
-| `/free-providers`          | Show free/paid model counts for all providers             |
-| `/free-telemetry`          | Show real-world performance data (tokens/s, latency, success rate) for free models |
-| `/clear-free-telemetry`    | Clear all stored telemetry data                           |
-| `/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                             |
-
----
-
-## Features
-
-### 🔍 Model Availability Probing
-
-Some provider APIs list models that return errors when you try to use them (expired free promotions, decommissioned models, server spin-down). pi-free automatically detects and hides broken models:
-
-- **Ollama Cloud**: `/probe-ollama` — probes for 403 errors, auto-hides inaccessible models
-- **Routeway**: `/probe-routeway` — probes for 5xx/404 errors, auto-hides broken models
-- **OpenCode**: `/probe-opencode`, `/probe-opencode-go` — probes for expired free promotions (reports only, no auto-hide)
-- **DeepInfra**: `/probe-deepinfra` — probes for 404/5xx errors, auto-hides broken models
-- **SambaNova**: `/probe-sambanova` — probes for 404/5xx errors, auto-hides broken models
-- **Together AI**: `/probe-together` — probes for 404/5xx errors, auto-hides broken models
-- **Novita AI**: `/probe-novita` — probes for 404/5xx errors, auto-hides broken models
-
-All probes use a **24-hour probe cache** to avoid re-checking recently-verified models. Run any probe command manually to force a full re-check, or let the lazy auto-probe on first `session_start` handle it.
-
-### 🎯 Coding Index (CI) Scores
-
-Every model shows a **Coding Index score** (e.g., `CI: 52.3`) in the model picker:
-
-- **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 (Mistral, Groq, Cerebras, etc.)
-
-**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                                              |
-| ------------ | ------------------------------------------------------------------ |
-| **Fireworks**   | Strips vendor prefixes (`meta/`, `mistralai/`, `microsoft/`, etc.) |
-| **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`                                 |
-
-**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
-- **Auto-probe on session_start** — Lazy background probes detect broken models automatically on your first session; no manual command needed
-- **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:**
-
-- ✅ **Free providers** (Kilo, Cline) — Toggle between free-only vs paid models
-- 🔄 **Freemium** (Ollama, SambaNova) — 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`)
-
----
-
-## Using Free Models (No Setup Required)
-
-### Kilo (free models, more after login)
-
-Kilo shows free models immediately. To unlock all models, authenticate with Kilo's free OAuth:
-
-```
-/login 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
-4. Automatically complete login once approved
-
-- No credit card required
-- Free tier: 200 requests/hour
-- 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: Pi's auth file** (`~/.pi/agent/auth.json`)
-
-OpenRouter reads its key from Pi's built-in auth storage. Set it via:
-
-```bash
-export OPENROUTER_API_KEY="sk-or-v1-..."
-```
-
-Then use `/toggle-openrouter` to switch between free-only and all models.
-
-**Note:** `openrouter_api_key` in `~/.pi/free.json` is ignored. OpenRouter always reads from Pi's auth system to avoid stale keys.
-
-### NVIDIA NIM (now built-in)
-
-NVIDIA NIM is now a **built-in Pi provider** — no extension needed. Set `NVIDIA_API_KEY` to use it directly with Pi's built-in model picker.
-
-### Ollama Cloud
-
-Get an API key from [ollama.com/settings/keys](https://ollama.com/settings/keys), then:
-
-**Option A: Environment variable**
-
-```bash
-export OLLAMA_API_KEY="..."
-export OLLAMA_SHOW_PAID=true
-```
-
-**Option B: Config file** (`~/.pi/free.json`)
-
-```json
-{
-  "ollama_api_key": "YOUR_KEY",
-  "ollama_show_paid": true
-}
-```
-
-**Note:** Ollama requires `OLLAMA_SHOW_PAID=true` because they have usage limits on their cloud API.
-
-Free tier resets every 5 hours + 7 days.
-
-### Mistral (free API key)
-
-Add API key to `~/.pi/free.json` or environment variables:
-
-```bash
-export MISTRAL_API_KEY="..."
-```
+Press `Ctrl+L` to open the model picker. Free models are shown by default.
 
 ---
 
-### 💳 Paid Providers
+## Quick Start
 
-### Codestral (free Experiment plan)
+### 1. Use free models (no setup)
 
-Codestral is Mistral's code-focused model via `codestral.mistral.ai`:
+Kilo and Cline models appear immediately. To unlock all models:
 
-- Free tier (Experiment plan): 2 req/min, 500K tokens/min, 1B tokens/month
-- No credit card — phone verification only
-- Sign up at <https://console.mistral.ai/codestral>
-
-```bash
-export CODESTRAL_API_KEY="..."
 ```
-
-Or add to `~/.pi/free.json`:
-
-```json
-{
-  "codestral_api_key": "YOUR_KEY"
-}
+/login kilo      # Kilo free OAuth
+/login cline     # Cline free OAuth
 ```
 
-**Note:** Codestral uses Mistral's SDK (`mistral-conversations` API type), not OpenAI-completions.
+### 2. Toggle between free and paid
 
-### LLM7.io (free gateway)
-
-LLM7 routes across multiple providers through a single OpenAI-compatible endpoint:
-
-- Free tier: default/fast selectors, 100 req/hr, 20 req/min
-- No credit card required
-- Get free token at <https://token.llm7.io/>
-
-```bash
-export LLM7_API_KEY="..."
 ```
-
-### DeepInfra ($5 trial credit)
-
-AI inference cloud with 100+ open-source models:
-
-- $5 one-time credit on signup (no credit card)
-- ~5M tokens, expires after 90 days
-- 60 RPM (varies by model)
-
-```bash
-export DEEPINFRA_TOKEN="..."
-```
-
-### Together AI ($1 trial credit)
-
-Fast inference on 200+ open-source models:
-
-- $1 one-time credit on signup (no credit card)
-- 138 chat models (Llama, DeepSeek, Qwen, Mixtral, etc.)
-- 60 RPM, 600 RPD (varies by model)
-
-```bash
-export TOGETHER_AI_API_KEY="..."
-```
-
-### SambaNova Cloud (free tier)
-
-Fast inference on custom RDU hardware:
-
-- Free tier: 20-480 RPM, 400-9600 RPD (no credit card)
-- Models include Llama 3.3 70B, DeepSeek-V3/R1, Llama 4 Maverick
-
-```bash
-export SAMBANOVA_API_KEY="..."
+/toggle-kilo       # Kilo free ↔ all
+/toggle-openrouter # OpenRouter free ↔ all
+/toggle-free       # global free-only mode
+/free-providers    # show model counts
 ```
 
-### b.ai (paid gateway with 1 free promo model)
-
-OpenAI-compatible gateway at `api.b.ai/v1` providing access to 29 frontier models:
+### 3. Add API keys (optional)
 
-- **Anthropic**: Claude Opus 4.5–4.8, Claude Sonnet 4.5–4.6, Claude Haiku 4.5
-- **OpenAI**: GPT-5.5, GPT-5.5 Instant, GPT-5.4, GPT-5.4 Pro/Mini/Nano, GPT-5.2, GPT-5 Mini/Nano
-- **Google**: Gemini 3.1 Pro, Gemini 3 Flash, Gemini 3.5 Flash
-- **DeepSeek**: V4 Pro, V4 Flash, V3.2
-- **GLM**: GLM-5.x family
-- **Other**: Kimi K2.5, Qwen 3.6-27B, MiniMax M3 / M2.7
-
-Currently advertises `MiniMax-M3` as a limited-time free promotional model. All other models are paid — they're visible by default (toggle with `/toggle-bai` to show free-only).
-
-```bash
-export BAI_API_KEY="sk-..."
-```
-
-Or add to `~/.pi/free.json`:
+First run creates `~/.pi/free.json` automatically. Add keys there or use environment variables:
 
 ```json
 {
-  "bai_api_key": "sk-...",
-  "bai_show_paid": true
+  "ollama_api_key": "...",
+  "sambanova_api_key": "...",
+  "deepinfra_api_key": "..."
 }
 ```
 
-Get a key at <https://b.ai/>.
-
 ---
 
-## Slash Commands
-
-Each provider has toggle commands to switch between free and all models:
-
-| Command                 | Action                                                   |
-| ----------------------- | -------------------------------------------------------- |
-| `/toggle-kilo`          | Toggle between free/all Kilo models                      |
-| `/toggle-openrouter`    | Toggle between free/all OpenRouter models                |
-| `/toggle-opencode`      | Toggle between free/all OpenCode models                  |
-| `/toggle-cline`         | Toggle between free/all Cline 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)     |
-| `/toggle-xai`           | Toggle between free/all xAI models (🔧 dynamic)          |
-| `/toggle-huggingface`   | Toggle between free/all Hugging Face models (🔧 dynamic)  |
-| `/toggle-codestral`     | Toggle Codestral (🔄 freemium)                           |
-| `/toggle-deepinfra`     | Toggle DeepInfra (💳 trial credit)                       |
-| `/toggle-together`      | Toggle Together AI (💳 trial credit)                     |
-| `/toggle-sambanova`     | Toggle SambaNova (🔄 freemium)                           |
-| `/toggle-bai`           | Toggle b.ai (💳 paid — 1 free promo model)                |
-| `/toggle-llm7`          | Toggle LLM7 (✅ free gateway)                            |
-| `/toggle-zenmux`        | Toggle ZenMux (💳 paid)                                  |
-| `/toggle-crofai`        | Toggle CrofAI (💳 paid)                                  |
-| `/toggle-novita`        | Toggle Novita AI (💳 paid)                               |
-| `/toggle-routeway`      | Toggle Routeway AI (💳 paid)                             |
-| `/toggle-fastrouter`    | Toggle FastRouter (🔧 dynamic)                           |
-| `/toggle-tokenrouter`   | Toggle TokenRouter (💳 paid — 1 free model)              |
-| `/ollama-cloud-refresh` | Re-fetch Ollama Cloud models live (no restart needed)    |
-| `/probe-ollama`         | Test Ollama Cloud models for 403 errors (auto-hide)      |
-
-**The toggle command:**
-
-- **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
-
-### Probe Commands (Health Check)
-
-Test models for errors and auto-hide broken ones:
-
-| Command                | What it does                                                |
-| ---------------------- | ----------------------------------------------------------- |
-| `/probe-ollama`        | Test all Ollama Cloud models, auto-hide 403s                 |
-| `/probe-routeway`      | Test all Routeway models, auto-hide 5xx/404s                |
-| `/probe-opencode`      | Test all OpenCode free models for expired promotions        |
-| `/probe-opencode-go`   | Test all OpenCode Go free models for expired promotions     |
-| `/probe-deepinfra`     | Test all DeepInfra models for availability, auto-hide broken|
-| `/probe-sambanova`     | Test all SambaNova models for availability, auto-hide broken|
-| `/probe-together`      | Test all Together AI models for availability, auto-hide broken|
-| `/probe-novita`        | Test all Novita AI models for availability, auto-hide broken|
-
-**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
-
-Use these when you see models that appear in the picker but fail when you try to use them.
+## Provider Catalog
 
----
+| Category | Providers |
+|---|---|
+| ✅ **Free** | Kilo, Cline, OpenRouter, OpenCode, LLM7, OpenModel, TokenRouter (1 free) |
+| 🔄 **Freemium** | Ollama Cloud, SambaNova, Codestral, AgentRouter |
+| 💳 **Paid** | ZenMux, CrofAI, DeepInfra, Together, Novita, Routeway, b.ai |
+| 🔧 **Dynamic** | Mistral, Groq, Cerebras, xAI, Hugging Face, FastRouter |
 
-## Configuration
-
-Create `~/.pi/free.json` in your home directory:
-
-```json
-{
-  "mistral_api_key": "YOUR_MISTRAL_KEY",
-  "ollama_api_key": "YOUR_OLLAMA_KEY",
-  "ollama_show_paid": true,
-  "hidden_models": ["model-id-to-hide"]
-}
-```
-
-Or use environment variables (same names, uppercase):
-
-```bash
-export MISTRAL_API_KEY="..."
-export OLLAMA_API_KEY="..."
-```
+**Full catalog and setup instructions:** [docs/providers.md](docs/providers.md)
 
 ---
 
-## Logging & Debugging
-
-pi-free writes extension logs to:
-
-- **Windows:** `%USERPROFILE%\.pi\free.log`
-- **Linux/macOS:** `~/.pi/free.log`
+## Docs
 
-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)
-LOG_LEVEL=debug
-
-# File log verbosity (default: debug)
-PI_FREE_LOG_LEVEL=debug
-
-# Custom log path (optional)
-PI_FREE_LOG_PATH=/tmp/pi-free.log
-
-# Disable file logging
-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|groq|mixtral-8x7b-instruct|Mixtral 8x7B|miss|all-strategies-failed|mixtral-8x7b-instruct|||
-```
-
-**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|'
-```
+| Topic | Link |
+|---|---|
+| Provider catalog & auth | [docs/providers.md](docs/providers.md) |
+| Slash commands | [docs/commands.md](docs/commands.md) |
+| Configuration & logging | [docs/configuration.md](docs/configuration.md) |
+| Features deep dive | [docs/features.md](docs/features.md) |
+| Adding new providers | [CONTRIBUTING.md](CONTRIBUTING.md) |
 
 ---