Commit a3f82662f66b

@@ -18,9 +18,5 @@
   "mistral": {
     "type": "api_key",
     "key": "!passage show ai/mistralai/api_key"
-  },
-  "zai": {
-    "type": "api_key",
-    "key": "!passage show ai/zai/api_key"
   }
 }

@@ -86,13 +86,18 @@ Current passage-based API keys:
 - **`deepseek`** - DeepSeek API (`ai/deepseek/api_key`)
 - **`groq`** - Groq API (`ai/groq/wakasu`)
 - **`mistral`** - Mistral API (`ai/mistralai/api_key`)
-- **`zai`** - Z.AI/GLM API (`ai/zai/api_key`) - *Optional, GLM models also available via OpenRouter*
+- **`zai`** - Z.AI/GLM API (`ai/zai/api_key`) - *Optional, ONLY for GLM-4.7-Flash (free API)*
 
 OAuth providers (managed by pi):
 - **`github-copilot`** - via `/login github-copilot`
 - **`vertex-anthropic`** - via `/login vertex-anthropic`
 
-**Note:** Z.AI (GLM-5, GLM-4.7) models are accessible via OpenRouter without a direct Z.AI API key.
+**IMPORTANT - Z.AI Pricing Reality:** 
+- **GLM-4.7-Flash** - ✅ FREE API (only truly free GLM model)
+- **GLM-4.7** - ❌ Requires Lite subscription ($10/mo minimum)
+- **GLM-5** - ❌ Requires Pro subscription ($30/mo) or Max ($50+/mo)
+- **"Limited-time free"** is misleading marketing - models require paid subscriptions
+- Z.AI is NOT worth it - use free alternatives (DeepSeek-R1, Qwen, Gemini) instead
 
 ## Settings Management
 
@@ -165,3 +170,103 @@ Global agent instructions in `AGENTS.md`:
 - Skills integration
 
 Project-specific agents can be added to `.pi/agents/` (not in dots).
+
+## Provider Recommendations
+
+### Best Free Models (Confirmed Forever Free)
+
+1. **DeepSeek-R1** (OpenRouter) - Reasoning, matches OpenAI o1
+   ```bash
+   pi --provider openrouter --model "deepseek/deepseek-r1:free"
+   # or newer variant:
+   pi --provider openrouter --model "deepseek/deepseek-r1-0528:free"
+   ```
+   ⚠️ **Important:** Use the `:free` suffix - without it may route to paid providers!
+
+2. **Qwen2.5-Coder-32B** (OpenRouter) - Coding specialist
+   ```bash
+   pi --provider openrouter --model "qwen/qwen-2.5-coder-32b-instruct:free"
+   ```
+
+3. **GLM-4.7-Flash** (Z.AI direct) - Fast coding, free forever
+   ```bash
+   pi --provider zai --model "glm-4.7-flash"
+   ```
+
+4. **Llama 3.3 70B** (OpenRouter/Groq) - General purpose
+   ```bash
+   pi --provider groq --model "llama-3.3-70b-versatile"
+   ```
+
+5. **Gemini 2.0 Flash** (Google) - 1M context window
+   ```bash
+   pi --provider google --model "gemini-2.0-flash-exp"
+   ```
+
+### Z.AI Reality Check (NOT Recommended)
+
+Z.AI subscription plans are **expensive** and **not free**:
+
+| Plan | Price | Models | Worth It? |
+|------|-------|--------|-----------|
+| Free API | $0 | GLM-4.7-Flash only | ✅ Use this |
+| Lite | $27-30/quarter | GLM-4.7 (not GLM-5) | ❌ No - use DeepSeek instead |
+| Pro | $81-90/quarter | GLM-5 + GLM-4.7 | ❌ No - GitHub Copilot Pro is $10/mo |
+| Max | $150+/quarter | All models, high usage | ❌ No - way overpriced |
+
+**Avoid Z.AI subscriptions:** Use free alternatives instead (DeepSeek-R1, Qwen, Gemini)
+
+### Avoid
+
+- ❌ Paid subscription plans unless you need higher rate limits
+- ❌ Models marked "limited-time free" for production use
+- ❌ Using OpenRouter for models that are cheaper direct (check pricing)
+
+## Cost Comparison: Why Z.AI Plans Don't Make Sense
+
+| Service | Monthly Cost | What You Get | Value |
+|---------|--------------|--------------|-------|
+| **GitHub Copilot Pro** | **$10** | GPT-4o, Claude Sonnet 4.6, unlimited completions | ⭐⭐⭐⭐⭐ |
+| **Free Alternatives** | **$0** | DeepSeek-R1, Qwen2.5-Coder, Gemini Flash | ⭐⭐⭐⭐⭐ |
+| **OpenRouter Free** | **$0** | 31 models, 50 req/day | ⭐⭐⭐⭐ |
+| **Cursor** | $20 | GPT-4, Claude, unlimited | ⭐⭐⭐⭐ |
+| **Z.AI Lite** | $10 | GLM-4.7 only, 400/week limit | ⭐⭐ |
+| **Z.AI Pro** | **$30** | GLM-5 + GLM-4.7, 400/5hrs | ⭐ |
+| **Z.AI Max** | **$50+** | All models, high usage | ❌ |
+
+**Verdict:** Z.AI plans are **3-5× more expensive** than better alternatives. Use the free GLM-4.7-Flash API or stick with free alternatives.
+
+## OpenRouter Free Models: Important Notes
+
+### Always Use `:free` Suffix
+
+OpenRouter has both free and paid routing for many models. To ensure you're using the free tier:
+
+```bash
+# ✅ CORRECT - Explicitly free
+pi --provider openrouter --model "deepseek/deepseek-r1:free"
+pi --provider openrouter --model "qwen/qwen-2.5-coder-32b-instruct:free"
+pi --provider openrouter --model "meta-llama/llama-3.3-70b-instruct:free"
+
+# ❌ WRONG - May route to paid providers
+pi --provider openrouter --model "deepseek/deepseek-r1"
+pi --provider openrouter --model "qwen/qwen-2.5-coder-32b-instruct"
+```
+
+### Free Tier Rate Limits
+
+- **20 requests/minute**
+- **200 requests/day**  
+- No credit card required
+- No charges ever (with `:free` suffix)
+
+### List All Free Models
+
+```bash
+# In pi interactive mode
+pi --provider openrouter
+/model
+# Filter for "(free)" models
+```
+
+Or check: https://openrouter.ai/collections/free-models