Feat : Gitbook

2026-05-11 11:50:24 +07:00
parent 7ad538bcf2
commit fd92af77a0
124 changed files with 34154 additions and 4 deletions
--- a/gitbook/content/en/deployment/cloud.md
+++ b/gitbook/content/en/deployment/cloud.md
@@ -0,0 +1,473 @@
+# ☁️ Cloud Deployment
+
+Deploy 9Router on VPS or Docker for remote access and production use.
+
+---
+
+## 🖥️ VPS Deployment
+
+### Prerequisites
+
+- Ubuntu 20.04+ or similar Linux distribution
+- Node.js 20+
+- Git
+- Root or sudo access
+
+### Step 1: Clone Repository
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+### Step 3: Build Application
+
+```bash
+npm run build
+```
+
+### Step 4: Configure Environment Variables
+
+Create a `.env` file or export variables:
+
+```bash
+export JWT_SECRET="your-secure-secret-change-this-to-random-string"
+export INITIAL_PASSWORD="your-secure-password"
+export DATA_DIR="/var/lib/9router"
+export NODE_ENV="production"
+```
+
+**Environment Variables:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JWT_SECRET` | Auto-generated | **MUST change in production!** Used for JWT token signing |
+| `INITIAL_PASSWORD` | `123456` | Dashboard login password |
+| `DATA_DIR` | `~/.9router` | Database and data storage path |
+| `NODE_ENV` | `development` | Set to `production` for deployment |
+| `ENABLE_REQUEST_LOGS` | `false` | Enable debug request/response logs |
+
+### Step 5: Create Data Directory
+
+```bash
+sudo mkdir -p /var/lib/9router
+sudo chown $USER:$USER /var/lib/9router
+```
+
+### Step 6: Start Application
+
+```bash
+npm run start
+```
+
+### Step 7: Setup PM2 for Production
+
+PM2 keeps your application running and restarts it on crashes:
+
+```bash
+# Install PM2 globally
+npm install -g pm2
+
+# Start 9Router with PM2
+pm2 start npm --name 9router -- start
+
+# Save PM2 configuration
+pm2 save
+
+# Setup PM2 to start on system boot
+pm2 startup
+# Follow the instructions printed by the command above
+```
+
+**PM2 Management Commands:**
+
+```bash
+# View logs
+pm2 logs 9router
+
+# Restart application
+pm2 restart 9router
+
+# Stop application
+pm2 stop 9router
+
+# View status
+pm2 status
+
+# Monitor resources
+pm2 monit
+```
+
+---
+
+## 🐳 Docker Deployment
+
+### Option 1: Using Dockerfile
+
+Create a `Dockerfile` in the `app` directory:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application files
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Expose ports
+EXPOSE 3000 20128
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Start application
+CMD ["npm", "run", "start"]
+```
+
+**Build and Run:**
+
+```bash
+# Build image
+docker build -t 9router .
+
+# Run container
+docker run -d \
+  --name 9router \
+  -p 3000:3000 \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret-change-this" \
+  -e INITIAL_PASSWORD="your-secure-password" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Option 2: Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  9router:
+    build: .
+    container_name: 9router
+    ports:
+      - "3000:3000"
+      - "20128:20128"
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=your-secure-secret-change-this
+      - INITIAL_PASSWORD=your-secure-password
+      - DATA_DIR=/app/data
+    volumes:
+      - 9router-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  9router-data:
+```
+
+**Run with Docker Compose:**
+
+```bash
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+
+# Rebuild and restart
+docker-compose up -d --build
+```
+
+---
+
+## 🌐 Reverse Proxy with Nginx
+
+### Why Use Nginx?
+
+- SSL/TLS termination
+- Domain name mapping
+- Load balancing
+- Better security
+
+### Step 1: Install Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx
+```
+
+### Step 2: Configure Nginx
+
+Create `/etc/nginx/sites-available/9router`:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    # SSL certificates (use certbot to generate)
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Proxy to 9Router
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+
+    # API endpoint
+    location /v1 {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### Step 3: Enable Site
+
+```bash
+# Create symbolic link
+sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
+
+# Test configuration
+sudo nginx -t
+
+# Reload Nginx
+sudo systemctl reload nginx
+```
+
+### Step 4: Setup SSL with Let's Encrypt
+
+```bash
+# Install certbot
+sudo apt install certbot python3-certbot-nginx
+
+# Obtain SSL certificate
+sudo certbot --nginx -d your-domain.com
+
+# Auto-renewal is configured automatically
+# Test renewal
+sudo certbot renew --dry-run
+```
+
+---
+
+## 🔒 Security Considerations
+
+### 1. Change Default Credentials
+
+**CRITICAL:** Change `JWT_SECRET` and `INITIAL_PASSWORD` before deployment:
+
+```bash
+# Generate secure JWT secret
+openssl rand -base64 32
+
+# Use this value for JWT_SECRET
+export JWT_SECRET="generated-secret-here"
+```
+
+### 2. Firewall Configuration
+
+```bash
+# Allow SSH
+sudo ufw allow 22/tcp
+
+# Allow HTTP/HTTPS (if using Nginx)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# If NOT using reverse proxy, allow 9Router ports
+sudo ufw allow 3000/tcp
+sudo ufw allow 20128/tcp
+
+# Enable firewall
+sudo ufw enable
+```
+
+### 3. Restrict Dashboard Access
+
+If you only need API access, restrict dashboard port:
+
+```bash
+# Only allow localhost access to dashboard
+sudo ufw deny 3000/tcp
+```
+
+Access dashboard via SSH tunnel:
+
+```bash
+ssh -L 3000:localhost:3000 user@your-server.com
+# Then open http://localhost:3000 in your browser
+```
+
+### 4. Regular Updates
+
+```bash
+# Update system packages
+sudo apt update && sudo apt upgrade -y
+
+# Update 9Router
+cd /path/to/9router/app
+git pull
+npm install
+npm run build
+pm2 restart 9router
+```
+
+### 5. Backup Strategy
+
+```bash
+# Backup data directory
+tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
+
+# Automated daily backup (add to crontab)
+0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
+```
+
+---
+
+## 📊 Monitoring
+
+### Check Application Status
+
+```bash
+# PM2 status
+pm2 status
+
+# View logs
+pm2 logs 9router --lines 100
+
+# Monitor resources
+pm2 monit
+```
+
+### Nginx Logs
+
+```bash
+# Access logs
+sudo tail -f /var/log/nginx/access.log
+
+# Error logs
+sudo tail -f /var/log/nginx/error.log
+```
+
+### System Resources
+
+```bash
+# CPU and memory usage
+htop
+
+# Disk usage
+df -h
+
+# Network connections
+netstat -tulpn | grep -E '3000|20128'
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### Application Won't Start
+
+```bash
+# Check logs
+pm2 logs 9router
+
+# Check if ports are in use
+sudo lsof -i :3000
+sudo lsof -i :20128
+
+# Check environment variables
+pm2 env 9router
+```
+
+### Nginx 502 Bad Gateway
+
+```bash
+# Check if 9Router is running
+pm2 status
+
+# Check Nginx error logs
+sudo tail -f /var/log/nginx/error.log
+
+# Test Nginx configuration
+sudo nginx -t
+```
+
+### SSE Streaming Not Working
+
+Ensure `proxy_buffering off` is set in Nginx configuration for SSE support.
+
+### Permission Denied Errors
+
+```bash
+# Fix data directory permissions
+sudo chown -R $USER:$USER /var/lib/9router
+chmod 755 /var/lib/9router
+```
+
+---
+
+## 🔗 Next Steps
+
+- [Connect Providers](/providers/subscription.md)
+- [Setup Combos](/features/combos.md)
+- [Integrate with Tools](/integration/cursor.md)
--- a/gitbook/content/en/deployment/localhost.md
+++ b/gitbook/content/en/deployment/localhost.md
@@ -0,0 +1,164 @@
+# 🏠 Localhost Deployment
+
+Run 9Router on your local machine for development and personal use.
+
+---
+
+## 📦 Installation
+
+Install 9Router globally via npm:
+
+```bash
+npm install -g 9router
+```
+
+**Requirements:**
+- Node.js 20 or higher
+- npm 9 or higher
+
+---
+
+## 🚀 Starting the Server
+
+Start 9Router with a single command:
+
+```bash
+9router
+```
+
+The dashboard will automatically open in your browser at `http://localhost:3000`
+
+**Default Configuration:**
+- **Dashboard**: `http://localhost:3000`
+- **API Endpoint**: `http://localhost:20128/v1`
+- **Data Directory**: `~/.9router`
+
+---
+
+## 🔧 Configuration
+
+### Custom Data Directory
+
+Set a custom data directory using environment variable:
+
+```bash
+DATA_DIR=/path/to/data 9router
+```
+
+### Custom Port
+
+The API port (20128) and dashboard port (3000) are configured in the application. To change them, you'll need to modify the source code or use environment variables if supported.
+
+---
+
+## 🛑 Stopping the Server
+
+Press `Ctrl+C` in the terminal where 9Router is running.
+
+```bash
+# In the terminal running 9router
+^C  # Press Ctrl+C
+```
+
+The server will gracefully shut down and save all data.
+
+---
+
+## 🔄 Restarting the Server
+
+Simply run the start command again:
+
+```bash
+9router
+```
+
+All your configurations, API keys, and combos are preserved in the data directory.
+
+---
+
+## 📊 Updating 9Router
+
+Update to the latest version:
+
+```bash
+npm update -g 9router
+```
+
+Check your current version:
+
+```bash
+npm list -g 9router
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Port Already in Use
+
+If port 20128 or 3000 is already in use:
+
+```bash
+# Find process using the port (macOS/Linux)
+lsof -i :20128
+lsof -i :3000
+
+# Kill the process
+kill -9 <PID>
+```
+
+### Permission Errors
+
+If you encounter permission errors during installation:
+
+```bash
+# Use sudo (not recommended)
+sudo npm install -g 9router
+
+# Or fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Data Directory Issues
+
+If the data directory is not accessible:
+
+```bash
+# Check permissions
+ls -la ~/.9router
+
+# Fix permissions
+chmod 755 ~/.9router
+```
+
+---
+
+## 📁 Data Directory Structure
+
+```
+~/.9router/
+├── db.json           # Main database (providers, combos, settings)
+├── logs/             # Application logs
+└── cache/            # Temporary cache files
+```
+
+**Backup Your Data:**
+
+```bash
+# Backup
+cp -r ~/.9router ~/.9router.backup
+
+# Restore
+cp -r ~/.9router.backup ~/.9router
+```
+
+---
+
+## 🔗 Next Steps
+
+- [Connect Providers](/providers/subscription.md)
+- [Create Combos](/features/combos.md)
+- [Integrate with CLI Tools](/integration/cursor.md)
--- a/gitbook/content/en/faq.md
+++ b/gitbook/content/en/faq.md
@@ -0,0 +1,387 @@
+# Frequently Asked Questions
+
+Common questions about 9Router.
+
+---
+
+## What is 9Router?
+
+**9Router is an AI model router that maximizes your subscription value and minimizes costs.**
+
+It intelligently routes requests across multiple AI providers using a 3-tier fallback system:
+1. **Subscription tier** - Maximize Claude Code, Codex, Gemini quotas you already pay for
+2. **Cheap tier** - Ultra-cheap alternatives ($0.20-$0.60 per 1M tokens)
+3. **Free tier** - Emergency backup with unlimited free models
+
+**Key benefits:**
+- Never waste subscription quota
+- Automatic fallback when quota exhausted
+- Real-time quota tracking
+- 90% cost savings vs direct API usage
+
+---
+
+## How does pricing work?
+
+**9Router uses a 3-tier pricing strategy:**
+
+### Tier 1: Subscription (Maximize First)
+- **Claude Code** (Pro/Max): $20-100/month - 5-hour + weekly quota
+- **OpenAI Codex** (Plus/Pro): $20-200/month - 5-hour + weekly quota
+- **Gemini CLI**: FREE - 180K completions/month + 1K/day
+- **GitHub Copilot**: $10-19/month - Monthly reset
+- **Antigravity**: FREE - Similar to Gemini
+
+**Goal:** Use every bit of quota before it resets!
+
+### Tier 2: Cheap (Backup)
+- **GLM-4.7**: $0.60/$2.20 per 1M tokens - Daily reset 10AM
+- **MiniMax M2.1**: $0.20/$1.00 per 1M tokens - 5-hour rolling
+- **Kimi K2**: $9/month flat (10M tokens)
+
+**Goal:** 90% cheaper than ChatGPT API ($20/1M)!
+
+### Tier 3: Free (Emergency)
+- **iFlow**: 8 models FREE (Kimi K2, Qwen3, GLM, MiniMax...)
+- **Qwen**: 3 models FREE (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro**: 2 models FREE (Claude Sonnet 4.5, Haiku 4.5)
+
+**Goal:** Zero cost fallback when everything else is quota-limited!
+
+---
+
+## Is 9Router free?
+
+**Yes, 9Router itself is 100% free and open source.**
+
+**Free tier providers available:**
+- **Gemini CLI** - 180K completions/month (FREE Google account)
+- **iFlow** - 8 models unlimited (FREE OAuth)
+- **Qwen** - 3 models unlimited (FREE OAuth)
+- **Kiro** - Claude Sonnet/Haiku (FREE AWS Builder ID)
+
+**You can code for FREE forever using only free tier providers!**
+
+**Optional paid providers:**
+- Subscription services you may already have (Claude Code, Codex, Copilot)
+- Ultra-cheap alternatives ($0.20-$0.60 per 1M tokens)
+
+---
+
+## Which providers are supported?
+
+### Subscription Providers
+- **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
+- **Gemini CLI** (FREE) - Gemini 3 Flash/Pro, 2.5 Pro/Flash
+- **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
+- **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
+
+### Cheap Providers
+- **GLM** (Zhipu AI) - GLM 4.7, GLM 4.6V Vision
+- **MiniMax** - MiniMax M2.1
+- **Kimi** (Moonshot AI) - Kimi Latest
+- **OpenRouter** - Passthrough to any OpenRouter model
+
+### Free Providers
+- **iFlow** - 8 models (Kimi K2, Qwen3, GLM, MiniMax, DeepSeek...)
+- **Qwen** - 3 models (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro** - 2 models (Claude Sonnet 4.5, Haiku 4.5)
+
+**Total: 15+ providers, 50+ models**
+
+See [providers documentation](providers/subscription.md) for details.
+
+---
+
+## Can I use multiple providers?
+
+**Yes! This is 9Router's core feature.**
+
+**Combos allow you to chain multiple providers with automatic fallback:**
+
+```
+Example combo: "premium-coding"
+1. cc/claude-opus-4-5 (Subscription primary)
+2. glm/glm-4.7 (Cheap backup)
+3. if/kimi-k2 (Free emergency)
+
+→ Auto-switches when quota exhausted
+→ Never stops coding
+→ Minimal extra cost
+```
+
+**How to create combos:**
+```
+Dashboard → Combos → Create New
+→ Add models in priority order
+→ Use combo name in CLI: "premium-coding"
+```
+
+**Benefits:**
+- Zero downtime when quota runs out
+- Automatic cost optimization
+- Single model name for all tools
+
+See [combos documentation](features/combos.md) for examples.
+
+---
+
+## How does quota tracking work?
+
+**9Router tracks quota in real-time for all providers:**
+
+**Features:**
+- **Token consumption** - Input/output tokens per request
+- **Reset countdown** - Time until quota refreshes
+- **Usage stats** - Daily/weekly/monthly reports
+- **Cost estimation** - Projected spending (paid tiers)
+- **Quota alerts** - Notifications when quota low
+
+**Quota types:**
+- **5-hour rolling** - Claude Code, Codex, MiniMax
+- **Daily reset** - Gemini CLI (1K/day), GLM (10AM)
+- **Weekly reset** - Claude Code, Codex (additional quota)
+- **Monthly reset** - Gemini CLI (180K), GitHub Copilot (1st)
+
+**View quota:**
+```
+Dashboard → Providers → Quota Tracking
+→ Real-time usage + reset countdown
+```
+
+See [quota tracking documentation](features/quota-tracking.md) for details.
+
+---
+
+## Does 9Router work with Cursor?
+
+**Yes, but Cursor requires a cloud endpoint.**
+
+**Problem:** Cursor IDE doesn't support localhost endpoints.
+
+**Solution:** Use 9Router cloud deployment:
+
+```
+Cursor Settings → Models → Advanced:
+  OpenAI API Base URL: https://9router.com/v1
+  OpenAI API Key: [from dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+**Alternative:** Self-host on VPS with public domain:
+```bash
+# Deploy to VPS
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+npm start
+
+# Configure Nginx reverse proxy
+# Point Cursor to: https://your-domain.com/v1
+```
+
+**Other CLI tools work with localhost:**
+- Cline ✅
+- Claude Desktop ✅
+- Codex CLI ✅
+- Continue ✅
+- RooCode ✅
+
+See [Cursor integration guide](integration/cursor.md) for details.
+
+---
+
+## Can I self-host 9Router?
+
+**Yes! 9Router supports multiple deployment options:**
+
+### Localhost (Default)
+```bash
+npm install -g 9router
+9router
+→ Dashboard: http://localhost:3000
+→ API: http://localhost:20128/v1
+```
+
+### VPS/Cloud
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+npm start
+```
+
+### Docker
+```bash
+docker build -t 9router .
+docker run -d \
+  -p 3000:3000 \
+  -e JWT_SECRET="your-secret" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Cloudflare Workers
+```bash
+cd 9router/app
+npm run deploy:cloudflare
+```
+
+**Environment variables:**
+- `JWT_SECRET` - **MUST change in production!**
+- `DATA_DIR` - Database storage path (default: `~/.9router`)
+- `INITIAL_PASSWORD` - Dashboard login (default: `123456`)
+- `NODE_ENV` - Set to `production` for deploy
+
+See [deployment guide](getting-started/installation.md#deployment) for details.
+
+---
+
+## Is my data secure?
+
+**Yes, 9Router prioritizes security and privacy:**
+
+**Local storage:**
+- All data stored locally in `~/.9router` (or custom `DATA_DIR`)
+- No data sent to 9Router servers
+- OAuth tokens encrypted with JWT
+
+**No telemetry:**
+- No usage tracking
+- No analytics
+- No phone-home
+
+**Open source:**
+- Full source code available on GitHub
+- Audit security yourself
+- Community-reviewed
+
+**Best practices:**
+- Change `JWT_SECRET` in production
+- Use strong `INITIAL_PASSWORD`
+- Enable HTTPS for cloud deployments
+- Rotate API keys regularly
+
+**What 9Router stores:**
+- Provider OAuth tokens (encrypted)
+- API keys (encrypted)
+- Usage statistics (local only)
+- Combo configurations
+
+**What 9Router does NOT store:**
+- Your prompts or responses
+- Code you generate
+- Personal information
+
+---
+
+## How do I update 9Router?
+
+**Update methods depend on installation type:**
+
+### Global NPM Install
+```bash
+npm update -g 9router
+```
+
+### Local Install
+```bash
+cd 9router/app
+git pull origin main
+npm install
+npm run build
+npm start
+```
+
+### Docker
+```bash
+docker pull 9router:latest
+docker stop 9router
+docker rm 9router
+docker run -d \
+  -p 3000:3000 \
+  -v 9router-data:/app/data \
+  9router:latest
+```
+
+**Check version:**
+```bash
+9router --version
+```
+
+**Breaking changes:**
+- Check [CHANGELOG.md](https://github.com/decolua/9router/blob/main/CHANGELOG.md)
+- Backup `~/.9router` before major updates
+- Review migration guides for major versions
+
+---
+
+## How can I contribute?
+
+**We welcome contributions!**
+
+### Ways to contribute:
+
+1. **Report bugs:**
+   - [GitHub Issues](https://github.com/decolua/9router/issues)
+   - Include error logs, steps to reproduce
+
+2. **Request features:**
+   - [GitHub Discussions](https://github.com/decolua/9router/discussions)
+   - Describe use case and benefits
+
+3. **Submit code:**
+   ```bash
+   # Fork repo
+   git clone https://github.com/YOUR_USERNAME/9router.git
+   cd 9router
+   
+   # Create branch
+   git checkout -b feature/your-feature
+   
+   # Make changes
+   npm install
+   npm run dev
+   
+   # Test
+   npm test
+   
+   # Commit and push
+   git add .
+   git commit -m "Add your feature"
+   git push origin feature/your-feature
+   
+   # Create Pull Request on GitHub
+   ```
+
+4. **Improve docs:**
+   - Fix typos, add examples
+   - Translate to other languages
+   - Write tutorials
+
+5. **Add providers:**
+   - Implement new provider adapters
+   - See `app/lib/providers/` for examples
+
+**Contribution guidelines:**
+- Follow existing code style
+- Add tests for new features
+- Update documentation
+- Keep commits atomic and descriptive
+
+See [CONTRIBUTING.md](https://github.com/decolua/9router/blob/main/CONTRIBUTING.md) for details.
+
+---
+
+## Need More Help?
+
+- **Documentation:** [9router.com/docs](https://9router.com/docs)
+- **GitHub:** [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Troubleshooting:** [troubleshooting.md](troubleshooting.md)
--- a/gitbook/content/en/features/combos.md
+++ b/gitbook/content/en/features/combos.md
@@ -0,0 +1,537 @@
+# Combos - Custom Fallback Chains
+
+Create custom model combinations with automatic fallback. Combos let you define your own routing strategy based on cost, quality, and availability.
+
+---
+
+## What Are Combos?
+
+Combos are **custom fallback chains** that you create in the dashboard. Instead of using a single model, you define a sequence of models that 9Router tries in order.
+
+**Example:**
+```
+Combo name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (try first)
+  2. glm/glm-4.7 (if #1 quota exhausted)
+  3. minimax/MiniMax-M2.1 (if #2 quota exhausted)
+```
+
+**Usage in CLI:**
+```
+Model: premium-coding
+```
+
+9Router automatically tries each model in sequence until one succeeds.
+
+---
+
+## Why Use Combos?
+
+### 1. Maximize Subscription Value
+```
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ Use subscription first, cheap backup, free emergency
+→ Get full value from subscriptions you already pay for
+```
+
+### 2. Minimize Costs
+```
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+
+→ Start with cheapest paid option ($0.60/1M)
+→ Fallback to even cheaper ($0.20/1M)
+→ Emergency free tier
+→ Total cost: ~$5-10/month vs $2000 on ChatGPT API
+```
+
+### 3. Ensure 24/7 Availability
+```
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ Always include free tier at the end
+→ Never run out of quota
+→ Code anytime, anywhere
+```
+
+### 4. Optimize for Quality
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro
+
+→ Best models first
+→ Fallback to other premium models
+→ Maintain high quality across fallback chain
+```
+
+---
+
+## How to Create Combos
+
+### Step 1: Open Dashboard
+
+```
+http://localhost:20128
+→ Login with your password
+```
+
+### Step 2: Navigate to Combos
+
+```
+Dashboard → Combos → Create New Combo
+```
+
+### Step 3: Configure Combo
+
+**Combo Name:**
+```
+premium-coding
+```
+
+**Description (optional):**
+```
+Subscription first, cheap backup, free emergency
+```
+
+**Select Models:**
+```
+1. cc/claude-opus-4-5-20251101
+2. glm/glm-4.7
+3. minimax/MiniMax-M2.1
+```
+
+**Drag to reorder** - Priority from top to bottom.
+
+### Step 4: Save
+
+```
+Click "Save Combo"
+→ Combo appears in model list
+```
+
+### Step 5: Use in CLI
+
+```
+Cursor/Cline/Any tool:
+  Model: premium-coding
+```
+
+---
+
+## Example Combos
+
+### Example 1: Premium Coding (Subscription → Cheap → Free)
+
+**Goal**: Maximize subscription value, minimize extra costs.
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. glm/glm-4.7
+  3. minimax/MiniMax-M2.1
+```
+
+**Usage:**
+```
+Cursor IDE:
+  Model: premium-coding
+```
+
+**Behavior:**
+```
+Morning (fresh quota):
+  Request → cc/claude-opus-4-5 ✅
+
+Afternoon (Claude quota out):
+  Request → glm/glm-4.7 ✅ (auto switched)
+
+Evening (GLM quota out):
+  Request → minimax/MiniMax-M2.1 ✅ (auto switched)
+```
+
+**Monthly cost (100M tokens):**
+```
+80M via Claude Code: $0 (subscription)
+15M via GLM: $9
+5M via MiniMax: $1
+Total: $10 + your subscription
+```
+
+**Savings**: ~99% vs ChatGPT API ($2000).
+
+---
+
+### Example 2: Budget Combo (Cheap → Free)
+
+**Goal**: Minimize costs, use free tier as backup.
+
+```
+Dashboard → Combos → Create New
+
+Name: budget-combo
+Models:
+  1. glm/glm-4.7
+  2. minimax/MiniMax-M2.1
+  3. if/kimi-k2-thinking
+```
+
+**Usage:**
+```
+Cline:
+  Provider: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  Model: budget-combo
+```
+
+**Behavior:**
+```
+Request → glm/glm-4.7
+  ✅ Daily quota available → Use GLM ($0.60/1M)
+  ❌ Quota exhausted → Try MiniMax ($0.20/1M)
+  ❌ MiniMax quota out → Use iFlow (FREE)
+```
+
+**Monthly cost (100M tokens):**
+```
+70M via GLM: $42
+20M via MiniMax: $4
+10M via iFlow: $0
+Total: $46 vs $2000 on ChatGPT API
+```
+
+**Savings**: 97%.
+
+---
+
+### Example 3: Free Combo (Zero Cost)
+
+**Goal**: 100% free, no costs ever.
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking
+  2. qw/qwen3-coder-plus
+  3. kr/claude-sonnet-4.5
+```
+
+**Usage:**
+```
+Claude Desktop:
+  Model: free-combo
+```
+
+**Behavior:**
+```
+Request → if/kimi-k2-thinking
+  ✅ Available → Use iFlow
+  ❌ Error → Try Qwen
+  ❌ Error → Try Kiro
+```
+
+**Monthly cost:**
+```
+100M tokens via free providers: $0
+Total: $0 forever
+```
+
+**Use case**: Personal projects, learning, experimentation.
+
+---
+
+### Example 4: Quality First (Premium Models Only)
+
+**Goal**: Best quality, no cheap fallback.
+
+```
+Dashboard → Combos → Create New
+
+Name: quality-first
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. cx/gpt-5.2-codex
+  3. gc/gemini-3-pro-preview
+```
+
+**Usage:**
+```
+Codex CLI:
+  export OPENAI_BASE_URL="http://localhost:20128"
+  Model: quality-first
+```
+
+**Behavior:**
+```
+Request → cc/claude-opus-4-5
+  ❌ Quota out → cx/gpt-5.2-codex
+  ❌ Quota out → gc/gemini-3-pro-preview
+  ❌ All out → Return error (no cheap fallback)
+```
+
+**Use case**: Critical production code, complex refactoring.
+
+---
+
+### Example 5: Multi-Subscription (Maximize All)
+
+**Goal**: Use all subscriptions before paying extra.
+
+```
+Dashboard → Combos → Create New
+
+Name: multi-sub
+Models:
+  1. gc/gemini-3-flash-preview (FREE 180K/month)
+  2. cc/claude-opus-4-5-20251101 (Pro subscription)
+  3. cx/gpt-5.2-codex (Plus subscription)
+  4. gh/gpt-5 (Copilot subscription)
+  5. glm/glm-4.7 (Cheap backup)
+  6. if/kimi-k2-thinking (Free emergency)
+```
+
+**Monthly cost (200M tokens):**
+```
+50M via Gemini CLI: $0 (free tier)
+80M via Claude Code: $0 (subscription)
+40M via Codex: $0 (subscription)
+20M via Copilot: $0 (subscription)
+8M via GLM: $4.80
+2M via iFlow: $0
+Total: $4.80 + existing subscriptions
+```
+
+**Result**: Use 190M tokens from subscriptions, only $4.80 extra.
+
+---
+
+### Example 6: Quota Reset Optimization
+
+**Goal**: Distribute usage based on reset times.
+
+```
+Dashboard → Combos → Create New
+
+Name: reset-optimized
+Models:
+  1. cc/claude-opus-4-5 (5h reset, use morning)
+  2. gc/gemini-3-flash (1K/day, use afternoon)
+  3. glm/glm-4.7 (daily 10AM reset, use evening)
+  4. minimax/MiniMax-M2.1 (5h rolling, use night)
+  5. if/kimi-k2-thinking (unlimited, emergency)
+```
+
+**Daily routine:**
+```
+08:00 - 13:00: Claude Code (fresh 5h quota)
+13:00 - 18:00: Gemini CLI (1K/day quota)
+18:00 - 22:00: GLM (resets 10AM next day)
+22:00 - 08:00: MiniMax (5h rolling) or iFlow
+```
+
+**Result**: Code 24/7 with minimal costs.
+
+---
+
+## Use Combos in CLI Tools
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from dashboard]
+  Model: premium-coding
+```
+
+### Claude Desktop
+
+Edit `~/.claude/config.json`:
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key",
+  "model": "budget-combo"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex --model quality-first "your prompt"
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: free-combo
+```
+
+### API Request
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "premium-coding",
+    "messages": [
+      {"role": "user", "content": "Write a function to..."}
+    ],
+    "stream": true
+  }'
+```
+
+---
+
+## Best Practices
+
+### 1. Always Include Free Tier
+
+```
+✅ Good:
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+❌ Bad:
+cc/claude-opus → glm/glm-4.7
+(no free fallback, can run out of quota)
+```
+
+**Why**: Ensures 24/7 availability, never blocked by quota.
+
+### 2. Order by Cost (Cheap to Expensive)
+
+```
+✅ Good:
+glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus
+
+❌ Bad:
+cc/claude-opus → glm/glm-4.7
+(wastes subscription quota on simple tasks)
+```
+
+**Exception**: If you want to maximize subscription value, put subscription first.
+
+### 3. Match Quality Requirements
+
+```
+For production code:
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7
+
+For quick tasks:
+glm/glm-4.7 → if/kimi-k2-thinking
+
+For experimentation:
+if/kimi-k2-thinking → qw/qwen3-coder-plus
+```
+
+### 4. Consider Quota Reset Times
+
+```
+Morning combo (fresh quotas):
+cc/claude-opus → cx/gpt-5.2-codex
+
+Evening combo (quotas likely exhausted):
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+### 5. Create Multiple Combos for Different Use Cases
+
+```
+premium-coding: For complex tasks
+budget-combo: For simple tasks
+free-combo: For experimentation
+quality-first: For production code
+```
+
+**Switch between combos** based on task requirements.
+
+### 6. Monitor Combo Performance
+
+```
+Dashboard → Analytics → Combo Usage:
+  premium-coding:
+    80% via cc/claude-opus (good, using subscription)
+    15% via glm/glm-4.7 (acceptable backup)
+    5% via minimax (rare fallback)
+```
+
+**Optimize**: If too much fallback usage, increase primary quota or reorder models.
+
+---
+
+## Advanced Configuration
+
+### Set Budget Limits per Combo
+
+```
+Dashboard → Combos → Edit → Budget:
+  Daily limit: $5
+  Monthly limit: $50
+```
+
+When limit reached, 9Router skips paid models and uses free tier only.
+
+### Enable/Disable Models in Combo
+
+```
+Dashboard → Combos → Edit → Models:
+  ✅ cc/claude-opus-4-5 (enabled)
+  ❌ glm/glm-4.7 (temporarily disabled)
+  ✅ if/kimi-k2-thinking (enabled)
+```
+
+**Use case**: Temporarily disable expensive models without deleting combo.
+
+### Clone Existing Combo
+
+```
+Dashboard → Combos → Clone "premium-coding"
+→ Creates copy with "-copy" suffix
+→ Modify and save as new combo
+```
+
+**Use case**: Create variations for different scenarios.
+
+---
+
+## Troubleshooting
+
+**Issue: Combo not appearing in model list**
+
+**Solution:**
+1. Refresh dashboard
+2. Check combo is saved (green checkmark)
+3. Restart CLI tool to refresh model list
+
+**Issue: Combo always uses last model (free tier)**
+
+**Solution:**
+1. Check quota for primary models (Dashboard → Quota)
+2. Verify API keys are valid (Dashboard → Providers)
+3. Check budget limits not exceeded
+
+**Issue: Combo costs more than expected**
+
+**Solution:**
+1. Dashboard → Analytics → Review combo usage
+2. Check if primary models are quota-exhausted
+3. Reorder models (put cheaper first)
+4. Set budget limits
+
+---
+
+## Related
+
+- [Smart Routing](./smart-routing.md) - How auto fallback works
+- [Quota Tracking](./quota-tracking.md) - Monitor usage and costs
--- a/gitbook/content/en/features/quota-tracking.md
+++ b/gitbook/content/en/features/quota-tracking.md
@@ -0,0 +1,687 @@
+# Quota Tracking & Usage Monitoring
+
+Track real-time token consumption, monitor quota limits, estimate costs, and get alerts before running out. Never waste subscription quota or exceed budget limits.
+
+---
+
+## Overview
+
+9Router provides comprehensive quota tracking for all providers:
+
+- **Real-time token consumption** - See tokens used per request
+- **Quota limits & remaining** - Track usage vs limits
+- **Reset countdown** - Know when quota refreshes
+- **Cost estimation** - Calculate spending for paid tiers
+- **Monthly reports** - Analyze usage patterns
+- **Alerts & notifications** - Get warned before limits
+
+---
+
+## Dashboard Overview
+
+### Quota Summary
+
+```
+Dashboard → Home → Quota Overview
+
+┌─────────────────────────────────────────────┐
+│ Claude Code (cc/)                           │
+│ ████████████░░░░░░░░ 2.5h / 5h (50%)       │
+│ Resets in: 2h 30m                           │
+│ Cost: $0 (subscription)                     │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ Gemini CLI (gc/)                            │
+│ ████████░░░░░░░░░░░░ 450 / 1000 (45%)      │
+│ Daily reset in: 18h 30m                     │
+│ Monthly: 45K / 180K (25%)                   │
+│ Cost: $0 (free tier)                        │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ GLM-4.7 (glm/)                              │
+│ ██████████████░░░░░░ 7M / 10M tokens (70%)  │
+│ Resets: Daily 10:00 AM (in 5h 35m)         │
+│ Cost today: $4.20                           │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ MiniMax M2.1 (minimax/)                     │
+│ ████████████████░░░░ 4M / 5M tokens (80%)   │
+│ Rolling 5h window                           │
+│ Cost (5h): $0.80                            │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ iFlow (if/)                                 │
+│ ████████████████████ Unlimited              │
+│ Cost: $0 (free forever)                     │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Real-Time Token Consumption
+
+### Per-Request Tracking
+
+Every request shows detailed token usage:
+
+```
+Dashboard → Activity → Recent Requests
+
+Request #1234
+Model: cc/claude-opus-4-5-20251101
+Timestamp: 2026-02-04 04:15:32
+
+Tokens:
+  Input: 1,250 tokens
+  Output: 850 tokens
+  Total: 2,100 tokens
+
+Cost: $0 (subscription quota)
+Duration: 3.2s
+Status: ✅ Success
+```
+
+### Live Usage Monitor
+
+```
+Dashboard → Live Monitor
+
+Current request:
+  Model: glm/glm-4.7
+  Tokens streamed: 450 / ~800 estimated
+  Cost so far: $0.0009
+  Duration: 1.8s
+```
+
+### Token Breakdown by Model
+
+```
+Dashboard → Analytics → Token Usage
+
+Today (Feb 4, 2026):
+  cc/claude-opus-4-5: 15M tokens ($0, subscription)
+  glm/glm-4.7: 8M tokens ($4.80)
+  if/kimi-k2-thinking: 3M tokens ($0, free)
+  
+Total: 26M tokens
+Cost: $4.80
+```
+
+---
+
+## Quota Limits & Reset Times
+
+### Subscription Providers
+
+**Claude Code (Pro/Max)**
+```
+Quota type: Time-based (5-hour rolling)
+Limit: 5 hours of usage
+Reset: Rolling 5-hour window + Weekly refresh
+Tracking: Usage time per model
+
+Dashboard shows:
+  Opus: 2.5h / 5h used
+  Sonnet: 1.2h / 5h used
+  Haiku: 0.8h / 5h used
+  
+Weekly reset: Every Monday 00:00 UTC
+```
+
+**OpenAI Codex (Plus/Pro)**
+```
+Quota type: Time-based (5-hour rolling)
+Limit: 5 hours (Plus) / 10 hours (Pro)
+Reset: Rolling 5-hour window + Weekly refresh
+
+Dashboard shows:
+  GPT-5.2 Codex: 3.5h / 5h used
+  Resets in: 1h 30m
+```
+
+**Gemini CLI (FREE)**
+```
+Quota type: Request count + Monthly tokens
+Daily limit: 1,000 requests
+Monthly limit: 180,000 completions
+Reset: Daily 00:00 UTC + Monthly 1st
+
+Dashboard shows:
+  Today: 450 / 1,000 requests (45%)
+  This month: 45K / 180K completions (25%)
+  Daily reset in: 18h 30m
+  Monthly reset in: 26 days
+```
+
+**GitHub Copilot**
+```
+Quota type: Monthly usage
+Limit: Varies by plan
+Reset: 1st of each month
+
+Dashboard shows:
+  Usage: 60% of monthly quota
+  Resets: March 1, 2026 (in 25 days)
+```
+
+### Cheap Providers
+
+**GLM-4.7**
+```
+Quota type: Daily token limit
+Limit: 10M tokens/day (Coding Plan)
+Reset: Daily 10:00 AM Beijing Time (UTC+8)
+
+Dashboard shows:
+  Used: 7M / 10M tokens (70%)
+  Remaining: 3M tokens
+  Resets in: 5h 35m
+  Cost today: $4.20
+```
+
+**MiniMax M2.1**
+```
+Quota type: Rolling 5-hour window
+Limit: 5M tokens per 5 hours
+Reset: Continuous rolling window
+
+Dashboard shows:
+  Used (5h): 4M / 5M tokens (80%)
+  Oldest usage expires in: 45m
+  Cost (5h): $0.80
+```
+
+**Kimi K2**
+```
+Quota type: Monthly subscription
+Limit: 10M tokens/month ($9 flat)
+Reset: Monthly on subscription date
+
+Dashboard shows:
+  Used: 6M / 10M tokens (60%)
+  Resets: Feb 15, 2026 (in 11 days)
+  Cost: $9/month (prepaid)
+```
+
+### Free Providers
+
+**iFlow / Qwen / Kiro**
+```
+Quota type: Unlimited (rate-limited)
+Limit: No hard limit
+Reset: N/A
+
+Dashboard shows:
+  Used today: 5M tokens
+  Cost: $0 (free forever)
+  Status: ✅ Available
+```
+
+---
+
+## Cost Estimation
+
+### Real-Time Cost Tracking
+
+```
+Dashboard → Costs → Today
+
+Subscription providers: $0
+  Claude Code: 15M tokens ($0, included)
+  Gemini CLI: 3M tokens ($0, free tier)
+
+Paid providers: $4.80
+  GLM-4.7: 8M tokens ($4.80)
+    Input: 6M × $0.60/1M = $3.60
+    Output: 2M × $2.20/1M = $4.40
+    Total: $4.80
+
+Free providers: $0
+  iFlow: 3M tokens ($0)
+
+Total today: $4.80
+```
+
+### Monthly Spending Report
+
+```
+Dashboard → Costs → This Month (February 2026)
+
+Week 1 (Feb 1-7):
+  Subscription: $0 (80M tokens)
+  Paid: $15.20 (25M tokens)
+  Free: $0 (10M tokens)
+  Total: $15.20
+
+Week 2 (Feb 8-14):
+  Subscription: $0 (75M tokens)
+  Paid: $12.80 (20M tokens)
+  Free: $0 (8M tokens)
+  Total: $12.80
+
+Month to date: $28.00
+Projected (30 days): ~$120
+
+Breakdown by provider:
+  GLM-4.7: $22.00 (78%)
+  MiniMax M2.1: $6.00 (22%)
+  
+Average cost per 1M tokens: $0.62
+Savings vs ChatGPT API: 97% ($4,000 → $120)
+```
+
+### Cost Projection
+
+```
+Dashboard → Costs → Projections
+
+Based on last 7 days usage:
+  Daily average: 50M tokens
+  Daily cost: $4.50
+
+Monthly projection:
+  Tokens: 1,500M (1.5B)
+  Cost: $135
+  
+Breakdown:
+  Subscription: 900M tokens ($0)
+  GLM-4.7: 450M tokens ($90)
+  MiniMax: 120M tokens ($24)
+  Free: 30M tokens ($0)
+
+Budget status:
+  Daily limit: $5 → 90% used today
+  Monthly limit: $150 → 90% projected
+  ⚠️ Warning: May exceed monthly budget
+```
+
+---
+
+## Usage Dashboard
+
+### Overview Stats
+
+```
+Dashboard → Analytics → Overview
+
+Today (Feb 4, 2026):
+  Requests: 1,234
+  Tokens: 26M
+  Cost: $4.80
+  Avg response time: 2.1s
+
+This week:
+  Requests: 8,456
+  Tokens: 180M
+  Cost: $28.00
+  Success rate: 99.2%
+
+This month:
+  Requests: 15,234
+  Tokens: 320M
+  Cost: $52.00
+  Top model: cc/claude-opus-4-5 (45%)
+```
+
+### Usage by Model
+
+```
+Dashboard → Analytics → Models
+
+Top models (this month):
+1. cc/claude-opus-4-5: 145M tokens (45%)
+2. glm/glm-4.7: 95M tokens (30%)
+3. if/kimi-k2-thinking: 50M tokens (16%)
+4. minimax/MiniMax-M2.1: 20M tokens (6%)
+5. gc/gemini-3-flash: 10M tokens (3%)
+
+Cost breakdown:
+  cc/claude-opus: $0 (subscription)
+  glm/glm-4.7: $45.00
+  if/kimi-k2-thinking: $0 (free)
+  minimax/MiniMax-M2.1: $7.00
+  gc/gemini-3-flash: $0 (free)
+```
+
+### Usage by Time
+
+```
+Dashboard → Analytics → Timeline
+
+Hourly usage (today):
+00:00 - 01:00: 0.5M tokens
+01:00 - 02:00: 0.2M tokens
+...
+08:00 - 09:00: 3.2M tokens (peak)
+09:00 - 10:00: 2.8M tokens
+...
+23:00 - 00:00: 0.8M tokens
+
+Peak hours: 08:00 - 12:00 (morning coding)
+Low hours: 00:00 - 06:00 (night)
+```
+
+### Usage by Combo
+
+```
+Dashboard → Analytics → Combos
+
+premium-coding:
+  Requests: 456
+  Tokens: 12M
+  Cost: $2.40
+  
+  Breakdown:
+    cc/claude-opus: 8M tokens (67%, $0)
+    glm/glm-4.7: 3M tokens (25%, $1.80)
+    minimax/MiniMax-M2.1: 1M tokens (8%, $0.20)
+
+budget-combo:
+  Requests: 234
+  Tokens: 6M
+  Cost: $1.20
+  
+  Breakdown:
+    glm/glm-4.7: 4M tokens (67%, $2.40)
+    if/kimi-k2-thinking: 2M tokens (33%, $0)
+```
+
+---
+
+## Alerts & Notifications
+
+### Quota Alerts
+
+```
+Dashboard → Settings → Alerts
+
+Quota warnings:
+  ✅ Alert at 80% quota used
+  ✅ Alert at 90% quota used
+  ✅ Alert when quota exhausted
+  ✅ Notify when quota resets
+
+Delivery:
+  ✅ Dashboard notification
+  ✅ Email (optional)
+  ✅ Webhook (optional)
+```
+
+**Example notifications:**
+```
+⚠️ Claude Code quota 80% used
+   2.5h remaining (resets in 1h 30m)
+   
+⚠️ GLM-4.7 quota 90% used
+   1M tokens remaining (resets in 5h)
+   
+✅ Gemini CLI quota reset
+   1,000 requests available (daily limit)
+```
+
+### Budget Alerts
+
+```
+Dashboard → Settings → Budget Alerts
+
+Daily budget: $5
+  ✅ Alert at 80% ($4)
+  ✅ Alert at 100% ($5)
+  ✅ Auto-switch to free tier when exceeded
+
+Monthly budget: $150
+  ✅ Alert at 50% ($75)
+  ✅ Alert at 80% ($120)
+  ✅ Alert at 100% ($150)
+```
+
+**Example notifications:**
+```
+⚠️ Daily budget 80% used
+   $4.00 / $5.00 spent today
+   
+⚠️ Monthly budget 50% reached
+   $75 / $150 spent this month
+   Projected: $135 (within budget)
+   
+🚨 Daily budget exceeded
+   $5.20 / $5.00 spent today
+   Auto-switched to free tier
+```
+
+### Cost Anomaly Detection
+
+```
+Dashboard → Settings → Anomaly Detection
+
+✅ Detect unusual spending patterns
+✅ Alert on cost spikes (>2× daily average)
+✅ Warn on quota exhaustion patterns
+
+Example alert:
+⚠️ Cost spike detected
+   Today: $12.50 (2.5× daily average)
+   Reason: High GLM-4.7 usage (20M tokens)
+   Suggestion: Check if primary models quota-exhausted
+```
+
+---
+
+## Best Practices
+
+### 1. Monitor Quota Daily
+
+```
+Daily routine:
+1. Check dashboard quota overview (30 seconds)
+2. Review reset times
+3. Plan usage around quota availability
+```
+
+**Example:**
+```
+Morning check:
+  ✅ Claude Code: 5h available (fresh reset)
+  ✅ Gemini CLI: 1K requests available
+  ⚠️ GLM-4.7: 2M tokens left (resets 10AM)
+  
+Action: Use Claude Code for morning work
+```
+
+### 2. Set Budget Limits
+
+```
+Dashboard → Settings → Budget:
+  Daily: $5 (prevents overspending)
+  Monthly: $150 (aligns with budget)
+```
+
+**Result**: Auto-switch to free tier when limit reached.
+
+### 3. Optimize Combo Usage
+
+```
+Dashboard → Analytics → Combos:
+  Review which models are used most
+  Adjust combo order to minimize costs
+```
+
+**Example:**
+```
+Current: cc/claude-opus → glm/glm-4.7
+  80% via Claude (good)
+  20% via GLM ($12/month)
+
+Optimized: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
+  50% via Gemini (free)
+  40% via Claude (subscription)
+  10% via GLM ($6/month)
+  
+Savings: $6/month
+```
+
+### 4. Track Reset Times
+
+```
+Dashboard → Quota → Reset Schedule:
+  Claude Code: 5h rolling + Weekly Monday
+  Gemini CLI: Daily 00:00 UTC + Monthly 1st
+  GLM-4.7: Daily 10:00 AM Beijing Time
+  MiniMax: Rolling 5h window
+```
+
+**Strategy**: Use providers when quota is fresh.
+
+### 5. Review Monthly Reports
+
+```
+Dashboard → Analytics → Monthly Report:
+  Total tokens: 1.5B
+  Total cost: $120
+  Savings: 97% vs ChatGPT API
+  
+Insights:
+  - 60% usage via subscriptions ($0)
+  - 30% via GLM ($90)
+  - 10% via free tier ($0)
+  
+Optimization:
+  - Increase Gemini CLI usage (free)
+  - Reduce GLM usage (expensive)
+```
+
+---
+
+## API Access
+
+### Get Quota Status
+
+```bash
+GET http://localhost:20128/api/quota
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "providers": [
+    {
+      "id": "cc",
+      "name": "Claude Code",
+      "quota": {
+        "used": 2.5,
+        "limit": 5,
+        "unit": "hours",
+        "percentage": 50
+      },
+      "reset": {
+        "type": "rolling",
+        "window": "5h",
+        "nextReset": "2026-02-04T06:45:00Z"
+      },
+      "cost": {
+        "today": 0,
+        "month": 0,
+        "currency": "USD"
+      }
+    },
+    {
+      "id": "glm",
+      "name": "GLM-4.7",
+      "quota": {
+        "used": 7000000,
+        "limit": 10000000,
+        "unit": "tokens",
+        "percentage": 70
+      },
+      "reset": {
+        "type": "daily",
+        "time": "10:00 AM UTC+8",
+        "nextReset": "2026-02-04T10:00:00+08:00"
+      },
+      "cost": {
+        "today": 4.20,
+        "month": 52.00,
+        "currency": "USD"
+      }
+    }
+  ]
+}
+```
+
+### Get Usage Stats
+
+```bash
+GET http://localhost:20128/api/usage?period=today
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "period": "today",
+  "date": "2026-02-04",
+  "summary": {
+    "requests": 1234,
+    "tokens": 26000000,
+    "cost": 4.80
+  },
+  "byModel": [
+    {
+      "model": "cc/claude-opus-4-5",
+      "requests": 456,
+      "tokens": 15000000,
+      "cost": 0
+    },
+    {
+      "model": "glm/glm-4.7",
+      "requests": 234,
+      "tokens": 8000000,
+      "cost": 4.80
+    }
+  ]
+}
+```
+
+---
+
+## Troubleshooting
+
+**Issue: Quota shows 0% but requests failing**
+
+**Solution:**
+1. Check provider connection (Dashboard → Providers)
+2. Verify API keys are valid
+3. Check if provider is down (status page)
+4. Try reconnecting OAuth providers
+
+**Issue: Cost estimation incorrect**
+
+**Solution:**
+1. Dashboard → Settings → Pricing
+2. Verify pricing per provider matches current rates
+3. Update pricing if provider changed rates
+4. Contact support if discrepancy persists
+
+**Issue: Reset time not updating**
+
+**Solution:**
+1. Refresh dashboard (F5)
+2. Check system time is correct
+3. Verify timezone settings
+4. Restart 9Router if issue persists
+
+**Issue: Alerts not received**
+
+**Solution:**
+1. Dashboard → Settings → Alerts
+2. Verify email address is correct
+3. Check spam folder
+4. Test notification (Send Test button)
+
+---
+
+## Related
+
+- [Smart Routing](./smart-routing.md) - Auto fallback based on quota
+- [Combos](./combos.md) - Create custom fallback chains
--- a/gitbook/content/en/features/smart-routing.md
+++ b/gitbook/content/en/features/smart-routing.md
@@ -0,0 +1,407 @@
+# Smart Routing & Auto Fallback
+
+9Router automatically routes your requests through the best available provider using a 3-tier fallback system. Never stop coding due to quota limits or rate limiting.
+
+---
+
+## How It Works
+
+9Router uses intelligent routing to maximize your existing subscriptions, minimize costs, and ensure 24/7 availability:
+
+```
+Request → 9Router → Check Tier 1 (Subscription)
+                     ↓ quota exhausted
+                     Check Tier 2 (Cheap)
+                     ↓ budget limit
+                     Check Tier 3 (Free)
+                     ↓
+                     Response
+```
+
+### 3-Tier Fallback System
+
+**Tier 1: SUBSCRIPTION (Primary)**
+- Claude Code (Pro/Max)
+- OpenAI Codex (Plus/Pro)
+- Gemini CLI (FREE 180K/month)
+- GitHub Copilot
+- Antigravity (Google)
+
+**Goal**: Maximize value from subscriptions you already pay for.
+
+**Tier 2: CHEAP (Backup)**
+- GLM-4.7 ($0.60/1M input)
+- MiniMax M2.1 ($0.20/1M input)
+- Kimi K2 ($9/month flat)
+
+**Goal**: Ultra-cheap backup when subscription quota runs out (~90% cheaper than ChatGPT API).
+
+**Tier 3: FREE (Emergency)**
+- iFlow (8 models)
+- Qwen (3 models)
+- Kiro (Claude FREE)
+
+**Goal**: Zero-cost fallback for unlimited coding.
+
+---
+
+## Automatic Switching
+
+9Router monitors quota in real-time and switches providers automatically:
+
+### Scenario 1: Subscription Quota Exhausted
+
+```
+User request → cc/claude-opus-4-5
+               ↓ quota exhausted (5-hour limit reached)
+               Auto switch → glm/glm-4.7
+               ↓ daily quota exhausted
+               Auto switch → minimax/MiniMax-M2.1
+               ↓ 5-hour quota exhausted
+               Auto switch → if/kimi-k2-thinking (FREE)
+               ↓
+               Response delivered ✅
+```
+
+**Result**: Zero downtime, seamless experience.
+
+### Scenario 2: Rate Limiting
+
+```
+User request → cx/gpt-5.2-codex
+               ↓ rate limited (too many requests)
+               Auto switch → glm/glm-4.7
+               ↓
+               Response delivered ✅
+```
+
+### Scenario 3: Provider Unavailable
+
+```
+User request → cc/claude-opus-4-5
+               ↓ provider error (503)
+               Auto switch → next available model
+               ↓
+               Response delivered ✅
+```
+
+---
+
+## Model Selection Logic
+
+9Router selects the best model based on:
+
+1. **Quota availability** - Check if provider has remaining quota
+2. **Cost tier** - Prefer subscription → cheap → free
+3. **Reset timing** - Consider when quota resets
+4. **Provider health** - Skip providers with errors
+
+### Priority Order Example
+
+For a request to `cc/claude-opus-4-5`:
+
+```
+1. Check Claude Code quota
+   ✅ Available → Use cc/claude-opus-4-5
+   ❌ Exhausted → Continue to step 2
+
+2. Check fallback tier (if configured)
+   ✅ GLM quota available → Use glm/glm-4.7
+   ❌ Exhausted → Continue to step 3
+
+3. Check free tier
+   ✅ iFlow available → Use if/kimi-k2-thinking
+   ❌ All exhausted → Return quota error
+```
+
+---
+
+## Configuration Options
+
+### Dashboard Settings
+
+**1. Enable/Disable Auto Fallback**
+
+```
+Dashboard → Settings → Smart Routing
+→ Toggle "Auto Fallback" ON/OFF
+```
+
+- **ON** (default): Automatic tier switching
+- **OFF**: Strict mode, return error if primary model unavailable
+
+**2. Set Budget Limits**
+
+```
+Dashboard → Settings → Budget Control
+→ Daily limit: $5
+→ Monthly limit: $50
+```
+
+When budget reached, 9Router automatically switches to free tier.
+
+**3. Configure Fallback Order**
+
+```
+Dashboard → Settings → Fallback Priority
+→ Drag to reorder providers within each tier
+```
+
+Example custom order:
+```
+Tier 1: Gemini CLI → Claude Code → Codex
+Tier 2: MiniMax → GLM → Kimi
+Tier 3: iFlow → Kiro → Qwen
+```
+
+**4. Quota Reset Notifications**
+
+```
+Dashboard → Settings → Notifications
+→ Email when quota resets
+→ Alert when 80% quota used
+```
+
+---
+
+## Examples
+
+### Example 1: Basic Auto Fallback
+
+**Setup:**
+```
+Model: cc/claude-opus-4-5-20251101
+Fallback: Auto (default 3-tier)
+```
+
+**Behavior:**
+```
+Morning (fresh quota):
+  Request → cc/claude-opus-4-5 ✅
+
+Afternoon (quota exhausted):
+  Request → glm/glm-4.7 ✅ (auto switched)
+
+Evening (GLM quota out):
+  Request → minimax/MiniMax-M2.1 ✅ (auto switched)
+
+Late night (all paid quota out):
+  Request → if/kimi-k2-thinking ✅ (free tier)
+```
+
+**Cost**: ~$5-10/month extra (mostly covered by subscription).
+
+### Example 2: Budget-Conscious Routing
+
+**Setup:**
+```
+Dashboard → Settings:
+  Daily budget: $2
+  Monthly budget: $20
+  Fallback: Enabled
+```
+
+**Behavior:**
+```
+Day 1-15 (within budget):
+  Requests → glm/glm-4.7 (cheap tier)
+  Cost: $1.50/day
+
+Day 16 (budget reached):
+  Requests → if/kimi-k2-thinking (free tier)
+  Cost: $0
+
+Next month (budget resets):
+  Requests → glm/glm-4.7 again
+```
+
+**Result**: Never exceed $20/month, always available.
+
+### Example 3: Subscription-Only Mode
+
+**Setup:**
+```
+Dashboard → Settings:
+  Auto Fallback: OFF
+  Strict mode: ON
+```
+
+**Behavior:**
+```
+Request → cc/claude-opus-4-5
+  ✅ Quota available → Success
+  ❌ Quota exhausted → Return error (no fallback)
+```
+
+**Use case**: When you only want to use paid subscriptions, no extra costs.
+
+### Example 4: Free-Only Mode
+
+**Setup:**
+```
+Model: if/kimi-k2-thinking
+Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5
+```
+
+**Behavior:**
+```
+All requests → Free tier only
+Cost: $0 forever
+```
+
+**Use case**: Personal projects, learning, experimentation.
+
+---
+
+## Best Practices
+
+### 1. Maximize Subscription Value
+
+```
+Strategy:
+- Set subscription models as Tier 1
+- Monitor quota usage in dashboard
+- Use cheap tier only when subscription exhausted
+```
+
+**Example combo:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 2. Optimize for Cost
+
+```
+Strategy:
+- Use Gemini CLI free tier first (180K/month)
+- Fallback to GLM/MiniMax (ultra-cheap)
+- Emergency: iFlow (free)
+```
+
+**Example combo:**
+```
+gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 3. Optimize for Quality
+
+```
+Strategy:
+- Use best models (Claude Opus, GPT-5.2)
+- Fallback to good cheap models (GLM-4.7)
+- Last resort: Free tier
+```
+
+**Example combo:**
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7
+```
+
+### 4. 24/7 Availability
+
+```
+Strategy:
+- Always include free tier in fallback
+- Monitor quota reset times
+- Distribute usage across providers
+```
+
+**Example combo:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+**Result**: Never run out of quota, code anytime.
+
+---
+
+## Quota Reset Strategy
+
+Plan your usage around quota reset times:
+
+| Provider | Quota Reset | Strategy |
+|----------|-------------|----------|
+| **Claude Code** | 5-hour + weekly | Use in morning, fresh quota |
+| **Codex** | 5-hour + weekly | Use after Claude quota out |
+| **Gemini CLI** | Daily (1K) + Monthly (180K) | Use throughout day |
+| **GLM-4.7** | Daily 10:00 AM | Use evening, resets next morning |
+| **MiniMax M2.1** | 5-hour rolling | Use anytime, tracks rolling window |
+| **iFlow/Qwen/Kiro** | No limit | Emergency backup |
+
+**Daily routine example:**
+```
+08:00 - 13:00: Claude Code (fresh 5h quota)
+13:00 - 18:00: Gemini CLI (1K/day quota)
+18:00 - 22:00: GLM-4.7 (cheap, resets 10AM)
+22:00 - 08:00: MiniMax or iFlow (5h rolling or free)
+```
+
+---
+
+## Monitoring & Alerts
+
+### Dashboard Quota Tracker
+
+```
+Dashboard → Quota Overview:
+  Claude Code: 2.5h / 5h remaining (50%)
+  Gemini CLI: 450 / 1000 requests today
+  GLM-4.7: 5M / 10M tokens (resets in 8h)
+  MiniMax: 3M / 5M tokens (rolling 5h)
+```
+
+### Real-Time Notifications
+
+```
+Dashboard → Notifications:
+  ⚠️ Claude Code quota 80% used (1h remaining)
+  ✅ GLM-4.7 quota reset (10M tokens available)
+  💰 Daily budget 50% used ($2.50 / $5)
+```
+
+### Usage Analytics
+
+```
+Dashboard → Analytics:
+  Today: 50M tokens
+    - 30M via Claude Code (subscription)
+    - 15M via GLM-4.7 ($9)
+    - 5M via iFlow (free)
+  
+  Cost: $9 (vs $1000 on ChatGPT API)
+  Savings: 99%
+```
+
+---
+
+## Troubleshooting
+
+**Issue: "All providers quota exhausted"**
+
+**Solution:**
+1. Check dashboard quota tracker
+2. Wait for quota reset (see countdown)
+3. Add free tier to fallback chain
+4. Or increase budget limit
+
+**Issue: "Too many fallback switches"**
+
+**Solution:**
+1. Check if primary provider is down
+2. Increase quota limits (upgrade subscription)
+3. Use cheaper primary model (GLM instead of Claude)
+
+**Issue: "Unexpected costs"**
+
+**Solution:**
+1. Dashboard → Analytics → Review usage
+2. Set daily/monthly budget limits
+3. Switch to free tier for non-critical tasks
+4. Use combos with free fallback
+
+---
+
+## Related
+
+- [Combos](./combos.md) - Create custom fallback chains
+- [Quota Tracking](./quota-tracking.md) - Monitor usage and costs
--- a/gitbook/content/en/getting-started/installation.md
+++ b/gitbook/content/en/getting-started/installation.md
@@ -0,0 +1,478 @@
+# Installation
+
+Detailed installation guide for 9Router with troubleshooting tips.
+
+---
+
+## Requirements
+
+### System Requirements
+
+- **Node.js**: Version 20.0.0 or higher
+- **npm**: Version 10.0.0 or higher (comes with Node.js)
+- **OS**: macOS, Linux, Windows (WSL recommended)
+- **Disk Space**: ~200MB for installation
+
+### Check Your Version
+
+```bash
+node --version
+# Should show v20.x.x or higher
+
+npm --version
+# Should show 10.x.x or higher
+```
+
+**Don't have Node.js?** Install from [nodejs.org](https://nodejs.org/)
+
+---
+
+## Installation Methods
+
+### Method 1: Global Installation (Recommended)
+
+Install 9Router globally to use from anywhere:
+
+```bash
+npm install -g 9router
+```
+
+**Start 9Router:**
+
+```bash
+9router
+```
+
+**Benefits:**
+- ✅ Run from any directory
+- ✅ Simple command: `9router`
+- ✅ Auto-updates with `npm update -g 9router`
+
+### Method 2: Local Installation
+
+Install in a specific project:
+
+```bash
+mkdir my-9router
+cd my-9router
+npm install 9router
+```
+
+**Start 9Router:**
+
+```bash
+npx 9router
+```
+
+**Benefits:**
+- ✅ Isolated per project
+- ✅ Version control per project
+- ✅ No global namespace pollution
+
+### Method 3: From Source (Development)
+
+Clone and build from GitHub:
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install
+npm run build
+npm start
+```
+
+**Benefits:**
+- ✅ Latest development features
+- ✅ Contribute to development
+- ✅ Custom modifications
+
+---
+
+## First Run
+
+### Start the Server
+
+```bash
+9router
+```
+
+**What happens:**
+1. Server starts on `http://localhost:20128`
+2. Dashboard opens automatically in browser
+3. Data directory created at `~/.9router`
+4. API key generated automatically
+
+### Dashboard Login
+
+**Default credentials:**
+- Password: `123456`
+
+**⚠️ Change password immediately:**
+1. Login to dashboard
+2. Settings → Change Password
+3. Use strong password
+
+### Get Your API Key
+
+```
+Dashboard → Settings → API Keys
+→ Copy your API key
+→ Use in CLI tools
+```
+
+**Example API key format:**
+```
+9r_1234567890abcdef1234567890abcdef
+```
+
+---
+
+## Verify Installation
+
+### Check Server Status
+
+```bash
+curl http://localhost:20128/health
+```
+
+**Expected response:**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+### List Available Models
+
+```bash
+curl http://localhost:20128/v1/models \
+  -H "Authorization: Bearer your-api-key"
+```
+
+**Expected response:**
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "cc/claude-opus-4-5-20251101",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "claude-code"
+    }
+  ]
+}
+```
+
+### Test Chat Completion
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "cc/claude-opus-4-5-20251101",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+Create `.env` file or set environment variables:
+
+```bash
+# Security (REQUIRED in production)
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+
+# Storage
+export DATA_DIR="~/.9router"
+
+# Server
+export PORT="20128"
+export NODE_ENV="production"
+
+# Logging
+export ENABLE_REQUEST_LOGS="false"
+```
+
+### Data Directory
+
+**Default location:** `~/.9router`
+
+**Contents:**
+```
+~/.9router/
+  ├── db.json           # Database (providers, combos, usage)
+  ├── api-keys.json     # API keys
+  └── logs/             # Request logs (if enabled)
+```
+
+**Change location:**
+
+```bash
+export DATA_DIR="/custom/path"
+9router
+```
+
+### Port Configuration
+
+**Default port:** `20128`
+
+**Change port:**
+
+```bash
+export PORT="3000"
+9router
+```
+
+**Or use command line:**
+
+```bash
+9router --port 3000
+```
+
+---
+
+## Troubleshooting
+
+### Port Already in Use
+
+**Error:**
+```
+Error: listen EADDRINUSE: address already in use :::20128
+```
+
+**Solution 1: Kill existing process**
+
+```bash
+# Find process using port 20128
+lsof -i :20128
+
+# Kill process
+kill -9 <PID>
+```
+
+**Solution 2: Use different port**
+
+```bash
+9router --port 3000
+```
+
+### Permission Denied
+
+**Error:**
+```
+Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
+```
+
+**Solution: Use sudo (not recommended) or fix npm permissions**
+
+```bash
+# Fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# Then install again
+npm install -g 9router
+```
+
+### Node.js Version Too Old
+
+**Error:**
+```
+Error: The engine "node" is incompatible with this module
+```
+
+**Solution: Update Node.js**
+
+```bash
+# Using nvm (recommended)
+nvm install 20
+nvm use 20
+
+# Or download from nodejs.org
+```
+
+### Dashboard Not Opening
+
+**Issue:** Dashboard doesn't open automatically
+
+**Solution 1: Open manually**
+
+```
+http://localhost:20128
+```
+
+**Solution 2: Check firewall**
+
+```bash
+# macOS: Allow Node.js in System Preferences → Security
+# Linux: Check iptables
+# Windows: Check Windows Firewall
+```
+
+### Cannot Connect to Providers
+
+**Issue:** OAuth login fails or API key invalid
+
+**Solution 1: Check internet connection**
+
+```bash
+ping google.com
+```
+
+**Solution 2: Check provider status**
+
+- Claude Code: [status.anthropic.com](https://status.anthropic.com)
+- OpenAI: [status.openai.com](https://status.openai.com)
+- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
+
+**Solution 3: Regenerate API key**
+
+```
+Dashboard → Provider → Disconnect → Reconnect
+```
+
+### High Memory Usage
+
+**Issue:** 9Router using too much RAM
+
+**Solution: Restart server**
+
+```bash
+# Stop
+pkill -f 9router
+
+# Start
+9router
+```
+
+**Or use PM2 for auto-restart:**
+
+```bash
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+```
+
+---
+
+## Deployment Options
+
+### Local Development
+
+```bash
+npm install -g 9router
+9router
+```
+
+**Use case:** Personal coding, testing
+
+### VPS/Cloud Server
+
+```bash
+# Install
+npm install -g 9router
+
+# Configure
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+# Start with PM2
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+pm2 startup
+```
+
+**Use case:** Team access, remote coding
+
+### Docker
+
+```bash
+docker pull 9router/9router:latest
+
+docker run -d \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret" \
+  -e INITIAL_PASSWORD="your-password" \
+  -v 9router-data:/root/.9router \
+  --name 9router \
+  9router/9router:latest
+```
+
+**Use case:** Containerized deployment, Kubernetes
+
+### Reverse Proxy (Nginx)
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        
+        # SSE support for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+**Use case:** HTTPS, custom domain, load balancing
+
+---
+
+## Uninstallation
+
+### Remove Global Installation
+
+```bash
+npm uninstall -g 9router
+```
+
+### Remove Data Directory
+
+```bash
+rm -rf ~/.9router
+```
+
+### Remove Configuration
+
+```bash
+# Remove environment variables from shell config
+nano ~/.bashrc  # or ~/.zshrc
+# Delete 9router-related exports
+```
+
+---
+
+## Next Steps
+
+- [Getting Started Guide](../getting-started.md) - Connect providers and start coding
+- [Features](../features/) - Explore quota tracking, combos, deployment
+- [Troubleshooting](../troubleshooting.md) - Fix common issues
+
+---
+
+## Need Help?
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
--- a/gitbook/content/en/getting-started/quick-start.md
+++ b/gitbook/content/en/getting-started/quick-start.md
@@ -0,0 +1,247 @@
+# Getting Started
+
+Get 9Router running in 5 minutes and start routing AI requests intelligently.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g 9router
+```
+
+**Requirements:** Node.js 20+ ([Installation details](getting-started/installation.md))
+
+### 2. Start
+
+```bash
+9router
+```
+
+🎉 **Dashboard opens automatically** at `http://localhost:20128`
+
+- Default password: `123456` (change in dashboard)
+- API key generated automatically
+- Ready to connect providers
+
+### 3. Connect Providers
+
+You have 3 ways to connect providers:
+
+#### Option A: OAuth (Subscription Providers)
+
+**Best for:** Claude Code, Codex, Gemini CLI, GitHub Copilot
+
+```
+Dashboard → Providers → Connect [Provider]
+→ OAuth login → Auto token refresh
+→ Quota tracking enabled
+```
+
+**Example: Claude Code**
+1. Click "Connect Claude Code"
+2. Login with your Claude account
+3. Authorize 9Router
+4. ✅ Done! Use model: `cc/claude-opus-4-5-20251101`
+
+#### Option B: API Key (Cheap Providers)
+
+**Best for:** GLM, MiniMax, Kimi, OpenRouter
+
+```
+Dashboard → Providers → Add API Key
+→ Select provider
+→ Paste API key
+→ Save
+```
+
+**Example: GLM-4.7**
+1. Sign up at [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key → Provider: `glm` → Paste key
+4. ✅ Done! Use model: `glm/glm-4.7`
+
+#### Option C: Free Providers (No Cost)
+
+**Best for:** iFlow, Qwen, Kiro
+
+```
+Dashboard → Providers → Connect [Free Provider]
+→ Device code or OAuth
+→ Unlimited usage
+```
+
+**Example: iFlow**
+1. Click "Connect iFlow"
+2. Login with iFlow account
+3. Authorize
+4. ✅ Done! Use 8 models: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, etc.
+
+---
+
+## 4. Use in CLI Tools
+
+Point your coding tool to 9Router:
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Claude Desktop
+
+Edit `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+---
+
+## 5. Create Smart Combos (Optional)
+
+Combos enable automatic fallback between models:
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. if/kimi-k2-thinking (Free fallback)
+
+Use in CLI: premium-coding
+```
+
+**How it works:**
+1. Tries Claude Opus first (your subscription)
+2. If quota exhausted → GLM-4.7 (ultra-cheap)
+3. If budget limit → iFlow (free)
+4. Zero downtime, automatic switching!
+
+---
+
+## Available Models
+
+### Subscription Models (Maximize First)
+
+**Claude Code (`cc/`)** - Pro/Max subscription:
+- `cc/claude-opus-4-5-20251101` - Claude 4.5 Opus
+- `cc/claude-sonnet-4-5-20250929` - Claude 4.5 Sonnet
+- `cc/claude-haiku-4-5-20251001` - Claude 4.5 Haiku
+
+**Codex (`cx/`)** - Plus/Pro subscription:
+- `cx/gpt-5.2-codex` - GPT 5.2 Codex
+- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
+
+**Gemini CLI (`gc/`)** - FREE 180K/month:
+- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
+- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
+
+**GitHub Copilot (`gh/`)** - Subscription:
+- `gh/gpt-5` - GPT-5
+- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
+
+### Cheap Models (Backup)
+
+**GLM (`glm/`)** - $0.6/$2.2 per 1M:
+- `glm/glm-4.7` - GLM 4.7 (daily reset 10AM)
+
+**MiniMax (`minimax/`)** - $0.20/$1.00 per 1M:
+- `minimax/MiniMax-M2.1` - MiniMax M2.1 (5h reset)
+
+**Kimi (`kimi/`)** - $9/month (10M tokens):
+- `kimi/kimi-latest` - Kimi Latest
+
+### FREE Models (Emergency)
+
+**iFlow (`if/`)** - 8 models FREE:
+- `if/kimi-k2-thinking` - Kimi K2 Thinking
+- `if/qwen3-coder-plus` - Qwen3 Coder Plus
+- `if/glm-4.7` - GLM 4.7
+- `if/deepseek-r1` - DeepSeek R1
+
+**Qwen (`qw/`)** - 3 models FREE:
+- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
+- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
+
+**Kiro (`kr/`)** - 2 models FREE:
+- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
+- `kr/claude-haiku-4.5` - Claude Haiku 4.5
+
+---
+
+## Cost Optimization Strategy
+
+### Monthly Budget: $10-20/month
+
+```
+1. Use Gemini CLI free tier (180K/month) for quick tasks
+2. Use Claude Code subscription quota fully (you already pay)
+3. Fallback to GLM ($0.6/1M) when quota out
+4. Emergency: MiniMax M2.1 ($0.20/1M) or iFlow (free)
+
+Real example (100M tokens/month):
+  60M via Gemini CLI: $0 (free tier)
+  30M via Claude Code: $0 (subscription you already have)
+  8M via GLM: $4.80
+  2M via MiniMax: $0.40
+  Total: $5.20/month + existing subscriptions
+```
+
+### Quota Reset Strategy
+
+```
+Daily routine:
+1. Morning: Fresh Claude Code quota (5h reset)
+2. Afternoon: Switch to Gemini CLI (1K/day)
+3. Evening: GLM daily quota (reset 10AM next day)
+4. Late night: MiniMax (5h rolling) or iFlow (free)
+
+→ Code 24/7 with minimal extra cost!
+```
+
+---
+
+## Next Steps
+
+- [Installation Details](getting-started/installation.md) - Requirements, troubleshooting
+- [Features](features/) - Explore quota tracking, combos, deployment
+- [FAQ](faq.md) - Common questions and answers
+- [Troubleshooting](troubleshooting.md) - Fix common issues
+
+---
+
+## Need Help?
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
--- a/gitbook/content/en/index.md
+++ b/gitbook/content/en/index.md
@@ -0,0 +1,164 @@
+# Welcome to 9Router
+
+**Use Claude, Codex, Gemini for FREE • Ultra-cheap alternatives from $0.20/1M tokens**
+
+9Router is an AI model router that maximizes your subscription value and minimizes costs through intelligent routing and automatic fallback.
+
+---
+
+## What is 9Router?
+
+9Router is a smart proxy that sits between your coding tools (Cursor, Cline, Claude Desktop) and AI providers. It automatically routes requests to the best available model based on quota, cost, and availability.
+
+**Stop wasting money:**
+- ❌ Subscription quota expires unused every month
+- ❌ Rate limits stop you mid-coding
+- ❌ Expensive APIs ($20-50/month per provider)
+- ❌ Manual switching between providers
+
+**Start maximizing value:**
+- ✅ **Maximize Subscriptions** - Track and use every bit of Claude Code, Codex, Gemini quota
+- ✅ **FREE Available** - Access iFlow, Qwen, Kiro models via CLI
+- ✅ **Ultra-Cheap Backup** - GLM ($0.6/1M), MiniMax M2.1 ($0.20/1M)
+- ✅ **Smart Fallback** - Subscription → Cheap → Free, automatic switching
+
+---
+
+## Key Features
+
+### 🔄 Smart 3-Tier Fallback
+
+```
+Setup once, never stop coding:
+
+Tier 1 (SUBSCRIPTION): Claude Code → Codex → Gemini
+  ↓ quota exhausted
+Tier 2 (CHEAP): GLM-4.7 → MiniMax M2.1 → Kimi
+  ↓ budget limit
+Tier 3 (FREE): iFlow → Qwen → Kiro
+
+→ Automatic switching, zero downtime!
+```
+
+### 📊 Quota Tracking
+
+- Real-time token consumption per provider
+- Reset countdown (5-hour, daily, weekly, monthly)
+- Cost estimation for paid tiers
+- Monthly spending reports
+
+### 🎯 Universal CLI Support
+
+Works with any tool that supports custom OpenAI endpoints:
+
+✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **Any OpenAI-compatible tool**
+
+### 💰 Cost Optimization
+
+**Real example (100M tokens/month):**
+```
+60M via Gemini CLI: $0 (free tier)
+30M via Claude Code: $0 (subscription you already have)
+8M via GLM: $4.80
+2M via MiniMax: $0.40
+Total: $5.20/month vs $2000 on ChatGPT API!
+```
+
+---
+
+## Why Choose 9Router?
+
+### Maximize Subscriptions
+
+Already paying for Claude Code ($20-100/month) or Codex ($20-200/month)? Get full value:
+
+- Track quota usage in real-time
+- Auto-switch when quota resets (5-hour, weekly)
+- Use every token before it expires
+- Gemini CLI: 180K completions/month **FREE**
+
+### Ultra-Cheap Backup
+
+When subscription quota runs out, pay pennies:
+
+| Provider | Cost per 1M tokens | Reset |
+|----------|-------------------|-------|
+| **GLM-4.7** | $0.60 input / $2.20 output | Daily 10:00 AM |
+| **MiniMax M2.1** | $0.20 input / $1.00 output | 5-hour rolling |
+| **Kimi K2** | $9/month (10M tokens) | Monthly |
+
+**~90% cheaper than ChatGPT API ($20/1M)!**
+
+### Free Forever Fallback
+
+Emergency backup when everything else is quota-limited:
+
+- **iFlow**: 8 models (Kimi K2, Qwen3 Coder Plus, GLM 4.7, MiniMax M2)
+- **Qwen**: 3 models (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro**: Claude Sonnet 4.5, Haiku 4.5 (AWS Builder ID)
+
+---
+
+## Quick Start
+
+Get started in 2 minutes:
+
+```bash
+# Install globally
+npm install -g 9router
+
+# Start (dashboard opens automatically)
+9router
+```
+
+🎉 **Dashboard opens** → Connect providers → Start coding!
+
+**Use in your CLI tool:**
+
+```
+Endpoint: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+[→ Full Getting Started Guide](getting-started.md)
+
+---
+
+## Use Cases
+
+### For Individual Developers
+
+- Maximize your Claude Code/Codex subscription
+- Use Gemini CLI free tier (180K/month)
+- Fallback to ultra-cheap models ($0.20/1M)
+- Code 24/7 without rate limits
+
+### For Teams
+
+- Deploy on VPS/Cloud for shared access
+- Track team spending in real-time
+- Set budget limits per tier
+- Centralized provider management
+
+### For Mobile/Remote Coding
+
+- Use cloud deployment (https://9router.com)
+- Access from iPad, phone, anywhere
+- No localhost limitations
+- Cloudflare edge network (300+ locations)
+
+---
+
+## What's Next?
+
+- [Getting Started](getting-started.md) - Install and configure in 5 minutes
+- [Installation Guide](getting-started/installation.md) - Detailed setup instructions
+- [Features](features/) - Explore all capabilities
+- [FAQ](faq.md) - Common questions
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ for developers maximizing AI value</sub>
+</div>
--- a/gitbook/content/en/integration/claude-code.md
+++ b/gitbook/content/en/integration/claude-code.md
@@ -0,0 +1,109 @@
+# Claude Code Integration
+
+Integrate 9Router with Claude Code CLI to route your Anthropic API requests through 9Router's intelligent routing system.
+
+## Prerequisites
+
+- Claude Code CLI installed
+- 9Router running locally or cloud endpoint configured
+- API key from 9Router dashboard
+
+## Setup
+
+### 1. Configure Environment Variables
+
+Set the following environment variables in your shell configuration file (`~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`):
+
+```bash
+# Base URL for 9Router
+export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
+
+# Optional: Set default models for aliases
+export ANTHROPIC_DEFAULT_OPUS_MODEL="cc/claude-opus-4-5-20251101"
+export ANTHROPIC_DEFAULT_SONNET_MODEL="cc/claude-sonnet-4-5-20250929"
+export ANTHROPIC_DEFAULT_HAIKU_MODEL="cc/claude-haiku-4-5-20251001"
+```
+
+### 2. Reload Shell Configuration
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### 3. Verify Configuration
+
+Check that the environment variables are set correctly:
+
+```bash
+echo $ANTHROPIC_BASE_URL
+```
+
+## Model Aliases
+
+Claude Code supports the following model aliases that map to 9Router models:
+
+| Alias | Model | Environment Variable |
+|-------|-------|---------------------|
+| `opus` | Claude Opus 4.5 | `ANTHROPIC_DEFAULT_OPUS_MODEL` |
+| `sonnet` | Claude Sonnet 4.5 | `ANTHROPIC_DEFAULT_SONNET_MODEL` |
+| `haiku` | Claude Haiku 4.5 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
+
+## Usage Examples
+
+### Using Model Aliases
+
+```bash
+# Use Opus model
+claude --model opus "Explain quantum computing"
+
+# Use Sonnet model
+claude --model sonnet "Write a Python function"
+
+# Use Haiku model
+claude --model haiku "Quick code review"
+```
+
+### Using Full Model Names
+
+```bash
+claude --model cc/claude-opus-4-5-20251101 "Your prompt here"
+```
+
+## Settings File
+
+Claude Code stores its configuration in `~/.claude/settings.json`. You can manually edit this file if needed:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "defaultModel": "sonnet"
+}
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+If you encounter connection errors:
+
+1. Verify 9Router is running: `curl http://localhost:20128/health`
+2. Check environment variables are set correctly
+3. Ensure no firewall is blocking port 20128
+
+### Model Not Found
+
+If you get "model not found" errors:
+
+1. Verify the model name matches your 9Router configuration
+2. Check that the provider connection is active in 9Router dashboard
+3. Ensure the model is available in your connected providers
+
+## Cloud Endpoint
+
+To use 9Router cloud endpoint instead of localhost:
+
+```bash
+export ANTHROPIC_BASE_URL="https://9router.com"
+```
+
+Make sure you have configured your API key in the 9Router cloud dashboard.
--- a/gitbook/content/en/integration/cline.md
+++ b/gitbook/content/en/integration/cline.md
@@ -0,0 +1,201 @@
+# Cline Integration
+
+Integrate 9Router with Cline VSCode extension to route your AI requests through 9Router's intelligent routing system.
+
+## Prerequisites
+
+- Visual Studio Code installed
+- Cline extension installed from VSCode marketplace
+- 9Router running locally or cloud endpoint configured
+- API key from 9Router dashboard
+
+## Setup
+
+### 1. Open Cline Settings
+
+1. Open Visual Studio Code
+2. Open the Cline extension panel (click the Cline icon in the sidebar)
+3. Click the **Settings** icon (gear icon) in the Cline panel
+
+### 2. Select API Provider
+
+1. In the Cline settings, find **API Provider** dropdown
+2. Select **Ollama** from the list
+   - Note: We use Ollama provider type because it's compatible with OpenAI-style APIs
+
+### 3. Configure Base URL
+
+Set the base URL to your 9Router endpoint:
+
+**For Local 9Router:**
+```
+http://localhost:20128/v1
+```
+
+**For Cloud 9Router:**
+```
+https://9router.com
+```
+
+**Steps:**
+1. In the **Base URL** field, enter your 9Router endpoint
+2. Make sure to include `/v1` at the end
+
+### 4. Add API Key
+
+1. In the **API Key** field, enter your 9Router API key
+2. You can find your API key in the 9Router dashboard under **Settings → API Keys**
+3. The key should start with `sk-9router-`
+
+### 5. Select Model
+
+1. In the **Model** dropdown, you can either:
+   - Select from available models (if Cline auto-detects them)
+   - Manually enter the model name from your 9Router configuration
+
+2. Common model names:
+   - `gpt-4`
+   - `gpt-4o`
+   - `claude-opus-4-5`
+   - `claude-sonnet-4-5`
+   - `gemini-2.0-flash`
+
+### 6. Save Configuration
+
+Click **Save** or close the settings panel. Cline will automatically save your configuration.
+
+## Configuration Example
+
+Your Cline settings should look like this:
+
+```
+API Provider: Ollama
+Base URL: http://localhost:20128/v1
+API Key: sk-9router-xxxxxxxxxxxxx
+Model: gpt-4
+```
+
+## Available Models
+
+You can use any model configured in your 9Router dashboard. Common examples:
+
+| Model Name | Provider | Description |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## Usage
+
+### Chat with AI
+
+1. Open the Cline panel in VSCode
+2. Type your message in the chat input
+3. Press Enter to send
+4. Cline will use 9Router to process your request
+
+### Code Generation
+
+1. Ask Cline to generate code: "Create a React component for a login form"
+2. Cline will generate code using 9Router
+3. Review and accept the generated code
+
+### Code Explanation
+
+1. Select code in your editor
+2. Ask Cline: "Explain this code"
+3. Get AI-powered explanations through 9Router
+
+### File Operations
+
+1. Ask Cline to create, modify, or delete files
+2. Cline will use 9Router to understand context and make changes
+3. Review changes before accepting
+
+## Troubleshooting
+
+### "Connection Failed" Error
+
+1. Verify 9Router is running: `curl http://localhost:20128/health`
+2. Check that the base URL is correct and includes `/v1`
+3. Ensure no firewall is blocking port 20128
+4. Try restarting VSCode
+
+### "Invalid API Key" Error
+
+1. Verify your API key in 9Router dashboard
+2. Make sure you copied the entire key including the `sk-9router-` prefix
+3. Check that the API key has not expired
+4. Try regenerating a new API key
+
+### "Model Not Found" Error
+
+1. Verify the model name matches exactly with your 9Router configuration
+2. Check that the provider connection is active in 9Router dashboard
+3. Ensure the model is available in your connected providers
+4. Try using the full model name (e.g., `openai/gpt-4` instead of `gpt-4`)
+
+### Cline Not Responding
+
+1. Check the Cline output panel for error messages
+2. Verify your 9Router instance is running and healthy
+3. Try reloading VSCode window (Cmd/Ctrl + Shift + P → "Reload Window")
+4. Check 9Router logs for any errors
+
+## Advanced Configuration
+
+### Using Cloud Endpoint
+
+To use 9Router cloud endpoint instead of localhost:
+
+1. In Cline settings, set Base URL to: `https://9router.com`
+2. Make sure you have configured your API key in the 9Router cloud dashboard
+3. Ensure your cloud endpoint is active and accessible
+
+### Multiple Models
+
+You can quickly switch between models:
+
+1. Open Cline settings
+2. Change the **Model** field to a different model
+3. Save and continue chatting with the new model
+
+### Custom Timeout
+
+If you experience timeout issues with large requests:
+
+1. Open VSCode settings (Cmd/Ctrl + ,)
+2. Search for "Cline timeout"
+3. Increase the timeout value (default is usually 30 seconds)
+
+## Best Practices
+
+1. **Use Appropriate Models**: Choose faster models (like Haiku or Flash) for simple tasks, and more powerful models (like Opus or GPT-4) for complex tasks
+2. **Monitor Usage**: Check 9Router dashboard for usage statistics and costs
+3. **Context Management**: Keep your conversations focused to reduce token usage
+4. **Model Switching**: Switch models based on task complexity to optimize cost and performance
+5. **API Key Security**: Never commit your API key to version control
+
+## Integration with 9Router Features
+
+### Model Routing
+
+9Router automatically routes your requests to the best available provider based on:
+- Model availability
+- Provider health status
+- Cost optimization
+- Load balancing
+
+### Fallback Support
+
+If a provider fails, 9Router automatically falls back to alternative providers configured in your dashboard.
+
+### Usage Tracking
+
+Monitor your Cline usage through 9Router dashboard:
+- Total requests
+- Token usage
+- Cost per model
+- Provider distribution
--- a/gitbook/content/en/integration/codex.md
+++ b/gitbook/content/en/integration/codex.md
@@ -0,0 +1,136 @@
+# OpenAI Codex CLI Integration
+
+Integrate 9Router with OpenAI Codex CLI to route your OpenAI API requests through 9Router's intelligent routing system.
+
+## Prerequisites
+
+- OpenAI Codex CLI installed
+- 9Router running locally or cloud endpoint configured
+- API key from 9Router dashboard
+
+## Setup
+
+### 1. Configure Environment Variables
+
+Set the following environment variables in your shell configuration file (`~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`):
+
+```bash
+# Base URL for 9Router
+export OPENAI_BASE_URL="http://localhost:20128/v1"
+
+# API Key from 9Router dashboard
+export OPENAI_API_KEY="your-9router-api-key"
+```
+
+### 2. Reload Shell Configuration
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### 3. Verify Configuration
+
+Check that the environment variables are set correctly:
+
+```bash
+echo $OPENAI_BASE_URL
+echo $OPENAI_API_KEY
+```
+
+## Available Models
+
+9Router provides the following Codex models:
+
+| Model ID | Description |
+|----------|-------------|
+| `cx/gpt-5.2-codex` | GPT-5.2 Codex - Latest version |
+| `cx/gpt-5.1-codex-max` | GPT-5.1 Codex Max - Extended context |
+
+## Usage Examples
+
+### Basic Usage
+
+```bash
+# Use GPT-5.2 Codex
+codex --model cx/gpt-5.2-codex "Write a function to sort an array"
+
+# Use GPT-5.1 Codex Max
+codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"
+```
+
+### Code Generation
+
+```bash
+codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"
+```
+
+### Code Explanation
+
+```bash
+codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"
+```
+
+## Configuration File
+
+You can also configure Codex CLI using a configuration file. Create or edit `~/.codex/config.json`:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "apiKey": "your-9router-api-key",
+  "defaultModel": "cx/gpt-5.2-codex"
+}
+```
+
+## Troubleshooting
+
+### Authentication Errors
+
+If you encounter authentication errors:
+
+1. Verify your API key is correct in 9Router dashboard
+2. Check that `OPENAI_API_KEY` environment variable is set
+3. Ensure the API key has not expired
+
+### Connection Issues
+
+If you encounter connection errors:
+
+1. Verify 9Router is running: `curl http://localhost:20128/health`
+2. Check environment variables are set correctly
+3. Ensure no firewall is blocking port 20128
+
+### Model Not Available
+
+If you get "model not available" errors:
+
+1. Verify the model name matches your 9Router configuration
+2. Check that the OpenAI provider connection is active in 9Router dashboard
+3. Ensure the model is available in your connected providers
+
+## Cloud Endpoint
+
+To use 9Router cloud endpoint instead of localhost:
+
+```bash
+export OPENAI_BASE_URL="https://9router.com"
+```
+
+Make sure you have configured your API key in the 9Router cloud dashboard.
+
+## Advanced Configuration
+
+### Custom Timeout
+
+```bash
+export OPENAI_TIMEOUT=60  # seconds
+```
+
+### Debug Mode
+
+Enable debug mode to see detailed request/response logs:
+
+```bash
+export CODEX_DEBUG=true
+codex --model cx/gpt-5.2-codex "Your prompt"
+```
--- a/gitbook/content/en/integration/continue.md
+++ b/gitbook/content/en/integration/continue.md
@@ -0,0 +1,249 @@
+# Continue VSCode Extension Integration
+
+Integrate 9Router with Continue extension to bring AI assistance directly into Visual Studio Code.
+
+## Prerequisites
+
+- Visual Studio Code installed
+- Continue extension installed from VSCode marketplace
+- 9Router API key from [dashboard](https://9router.com/dashboard)
+- 9Router running (local or cloud)
+
+## Configuration Steps
+
+### 1. Open Continue Configuration
+
+1. Open VSCode
+2. Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
+3. Type "Continue: Open Config" and select it
+4. This opens `~/.continue/config.json`
+
+### 2. Add 9Router Model Configuration
+
+Add the following configuration to your `config.json`:
+
+**Single Model Setup:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**Multiple Models Setup:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus (Best)",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Sonnet (Balanced)",
+      "provider": "openai",
+      "model": "cc/claude-sonnet-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - DeepSeek Chat (Code)",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Haiku (Fast)",
+      "provider": "openai",
+      "model": "cc/claude-haiku-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**For Cloud 9Router:**
+Replace `apiBase` with:
+```json
+"apiBase": "https://9router.com/v1"
+```
+
+### 3. Save and Reload
+
+1. Save the configuration file
+2. Reload VSCode window: `Cmd+Shift+P` → "Developer: Reload Window"
+3. Continue extension will load the new configuration
+
+### 4. Select Model
+
+1. Open Continue sidebar (click Continue icon in left panel)
+2. Click model selector dropdown at the top
+3. Choose your preferred 9Router model
+
+## Available Models
+
+### Claude Models (Anthropic)
+- `cc/claude-opus-4-5-20251101` - Most capable, best for complex tasks
+- `cc/claude-sonnet-4-20250514` - Balanced performance and speed
+- `cc/claude-haiku-4-20250514` - Fastest, good for simple tasks
+
+### DeepSeek Models
+- `cx/deepseek-chat` - Excellent for code generation
+- `cx/deepseek-reasoner` - Best for complex problem solving
+
+### GLM Models (Zhipu AI)
+- `glm/glm-4-plus` - Advanced Chinese and English
+- `glm/glm-4-flash` - Fast responses
+
+## Usage Examples
+
+### Code Explanation
+1. Select code in editor
+2. Open Continue sidebar
+3. Type: "Explain this code"
+4. Model: `cc/claude-sonnet-4-20250514`
+
+### Code Generation
+1. Open Continue sidebar
+2. Type: "Create a React component for user profile card"
+3. Model: `cx/deepseek-chat`
+
+### Refactoring
+1. Select code to refactor
+2. Type: "Refactor this to use async/await"
+3. Model: `cc/claude-sonnet-4-20250514`
+
+### Bug Fixing
+1. Select problematic code
+2. Type: "Find and fix the bug in this code"
+3. Model: `cx/deepseek-reasoner`
+
+## Advanced Configuration
+
+### Custom System Prompts
+
+Add custom system prompts for specific behaviors:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Code Expert",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "systemMessage": "You are an expert programmer. Always provide clean, well-documented code with best practices."
+    }
+  ]
+}
+```
+
+### Temperature and Parameters
+
+Adjust model behavior with parameters:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Creative Writer",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "temperature": 0.9,
+      "topP": 0.95
+    }
+  ]
+}
+```
+
+### Context Providers
+
+Configure what context Continue sends to the model:
+
+```json
+{
+  "contextProviders": [
+    {
+      "name": "code",
+      "params": {
+        "maxLines": 100
+      }
+    },
+    {
+      "name": "diff",
+      "params": {}
+    },
+    {
+      "name": "terminal",
+      "params": {}
+    }
+  ]
+}
+```
+
+## Keyboard Shortcuts
+
+- `Cmd+L` (Mac) / `Ctrl+L` (Windows/Linux) - Open Continue chat
+- `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - Inline edit
+- `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows/Linux) - Regenerate response
+
+## Troubleshooting
+
+### Model Not Responding
+- Check 9Router is running: `curl http://localhost:20128/health`
+- Verify API key in config.json
+- Check VSCode Developer Console for errors: `Help` → `Toggle Developer Tools`
+
+### Wrong Model Selected
+- Click model dropdown in Continue sidebar
+- Select correct 9Router model
+- Model name must match exactly (case-sensitive)
+
+### Configuration Not Loading
+- Verify JSON syntax is valid (use JSON validator)
+- Check file location: `~/.continue/config.json`
+- Reload VSCode window after changes
+
+### Slow Performance
+- Switch to faster models (haiku, flash)
+- Reduce context size in contextProviders
+- Check network latency to 9Router
+
+## Best Practices
+
+### Model Selection Strategy
+- **Quick edits**: Use `cc/claude-haiku-4-20250514`
+- **Code generation**: Use `cx/deepseek-chat`
+- **Complex refactoring**: Use `cc/claude-opus-4-5-20251101`
+- **Problem solving**: Use `cx/deepseek-reasoner`
+
+### Context Management
+- Select only relevant code before asking
+- Use specific, clear prompts
+- Break complex tasks into smaller steps
+
+### Cost Optimization
+- Use faster/cheaper models for simple tasks
+- Limit context size when possible
+- Cache frequently used responses
+
+## Next Steps
+
+- [Configure Cursor](cursor.md) for enhanced IDE integration
+- [Set up Roo](roo.md) for AI assistant
+- [Explore CLI usage](../cli/basic-usage.md)
+- [Learn about model selection](../models/overview.md)
--- a/gitbook/content/en/integration/cursor.md
+++ b/gitbook/content/en/integration/cursor.md
@@ -0,0 +1,149 @@
+# Cursor Integration
+
+Integrate 9Router with Cursor IDE to route your AI requests through 9Router's intelligent routing system.
+
+## Prerequisites
+
+- Cursor IDE installed
+- Cursor Pro account (required for custom API endpoints)
+- 9Router cloud endpoint configured
+- API key from 9Router dashboard
+
+## ⚠️ Important Notes
+
+> **Cloud Endpoint Required**: Cursor routes requests through its own server and does not support localhost endpoints. You must use the 9Router cloud endpoint: `https://9router.com`
+
+> **Cursor Pro Required**: This feature requires a Cursor Pro account to use custom API endpoints.
+
+## Setup
+
+### 1. Open Cursor Settings
+
+1. Open Cursor IDE
+2. Go to **Settings** (Cmd/Ctrl + ,)
+3. Navigate to **Models** section
+
+### 2. Enable OpenAI API
+
+1. Find the **OpenAI API key** option
+2. Enable the toggle to activate custom API configuration
+
+### 3. Configure Base URL
+
+Set the base URL to 9Router cloud endpoint:
+
+```
+https://9router.com
+```
+
+**Steps:**
+1. In the Models settings, locate the **Base URL** field
+2. Enter: `https://9router.com`
+3. Click **Save**
+
+### 4. Add API Key
+
+1. In the **API Key** field, enter your 9Router API key
+2. You can find your API key in the 9Router dashboard under **Settings → API Keys**
+3. Click **Save**
+
+### 5. Add Custom Model
+
+1. Click **View All Models** button
+2. Click **Add Custom Model**
+3. Enter the model name from your 9Router configuration (e.g., `gpt-4`, `claude-opus-4-5`, etc.)
+4. Click **Add**
+
+### 6. Select Model
+
+1. In the Cursor chat interface, click the model selector dropdown
+2. Choose your custom model from the list
+3. Start using 9Router with Cursor!
+
+## Configuration Example
+
+Your Cursor settings should look like this:
+
+```
+OpenAI API: ✓ Enabled
+Base URL: https://9router.com
+API Key: sk-9router-xxxxxxxxxxxxx
+Custom Models: gpt-4, claude-opus-4-5, gemini-2.0-flash
+```
+
+## Available Models
+
+You can use any model configured in your 9Router dashboard. Common examples:
+
+| Model Name | Provider | Description |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## Usage
+
+### Chat Interface
+
+1. Open Cursor chat (Cmd/Ctrl + L)
+2. Select your model from the dropdown
+3. Start chatting with AI through 9Router
+
+### Inline Code Generation
+
+1. Select code in your editor
+2. Press Cmd/Ctrl + K
+3. Enter your prompt
+4. Cursor will use 9Router to generate code
+
+### Code Explanation
+
+1. Select code in your editor
+2. Press Cmd/Ctrl + L
+3. Ask "Explain this code"
+4. Get AI-powered explanations through 9Router
+
+## Troubleshooting
+
+### "Invalid API Key" Error
+
+1. Verify your API key in 9Router dashboard
+2. Make sure you copied the entire key including the `sk-9router-` prefix
+3. Check that the API key has not expired
+4. Try regenerating a new API key
+
+### "Model Not Found" Error
+
+1. Verify the model name matches exactly with your 9Router configuration
+2. Check that the provider connection is active in 9Router dashboard
+3. Ensure the model is available in your connected providers
+4. Try using the full model name (e.g., `openai/gpt-4` instead of `gpt-4`)
+
+### Connection Issues
+
+1. Verify you are using the cloud endpoint: `https://9router.com`
+2. Check your internet connection
+3. Ensure 9Router cloud service is operational
+4. Try disabling VPN or proxy if enabled
+
+### Localhost Not Working
+
+> **Remember**: Cursor does not support localhost endpoints. You must use the cloud endpoint `https://9router.com`. If you need to use a local 9Router instance, consider using a tunneling service like ngrok to expose your local endpoint.
+
+## Cloud Endpoint Setup
+
+If you're running 9Router locally and want to use it with Cursor:
+
+1. Enable cloud endpoint in 9Router settings
+2. Configure your cloud endpoint URL in 9Router dashboard
+3. Use the cloud URL in Cursor settings
+4. Ensure your local 9Router instance is accessible from the internet
+
+## Best Practices
+
+1. **Use Model Aliases**: Create short aliases for frequently used models in 9Router
+2. **Monitor Usage**: Check 9Router dashboard for usage statistics and costs
+3. **Rotate API Keys**: Regularly rotate your API keys for security
+4. **Test Models**: Try different models to find the best one for your use case
--- a/gitbook/content/en/integration/other-tools.md
+++ b/gitbook/content/en/integration/other-tools.md
@@ -0,0 +1,416 @@
+# Other Tools Integration
+
+9Router is compatible with any tool that supports the OpenAI API format. This guide covers generic integration patterns for various tools and custom applications.
+
+## Overview
+
+9Router provides an OpenAI-compatible API endpoint that works with:
+- Custom scripts and applications
+- API clients and testing tools
+- CLI tools and utilities
+- Third-party integrations
+- Development frameworks
+
+## Generic Setup Pattern
+
+Any OpenAI-compatible tool can connect to 9Router using these settings:
+
+**Local 9Router:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+Model: any 9Router model (cc/*, cx/*, glm/*, etc.)
+```
+
+**Cloud 9Router:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+Model: any 9Router model (cc/*, cx/*, glm/*, etc.)
+```
+
+## Available Models
+
+### Claude Models (Anthropic)
+- `cc/claude-opus-4-5-20251101`
+- `cc/claude-sonnet-4-20250514`
+- `cc/claude-haiku-4-20250514`
+
+### DeepSeek Models
+- `cx/deepseek-chat`
+- `cx/deepseek-reasoner`
+
+### GLM Models (Zhipu AI)
+- `glm/glm-4-plus`
+- `glm/glm-4-flash`
+
+## Integration Examples
+
+### Python with OpenAI SDK
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+response = client.chat.completions.create(
+    model="cc/claude-sonnet-4-20250514",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Node.js with OpenAI SDK
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+const response = await client.chat.completions.create({
+  model: "cc/claude-sonnet-4-20250514",
+  messages: [
+    { role: "user", content: "Hello, how are you?" }
+  ]
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### cURL Command
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-api-key-from-dashboard" \
+  -d '{
+    "model": "cc/claude-sonnet-4-20250514",
+    "messages": [
+      {"role": "user", "content": "Hello, how are you?"}
+    ]
+  }'
+```
+
+### HTTP Client (Postman, Insomnia)
+
+**Request:**
+```
+POST http://localhost:20128/v1/chat/completions
+```
+
+**Headers:**
+```
+Content-Type: application/json
+Authorization: Bearer your-api-key-from-dashboard
+```
+
+**Body:**
+```json
+{
+  "model": "cc/claude-sonnet-4-20250514",
+  "messages": [
+    {"role": "user", "content": "Hello, how are you?"}
+  ],
+  "temperature": 0.7,
+  "max_tokens": 1000
+}
+```
+
+### LangChain Integration
+
+```python
+from langchain.chat_models import ChatOpenAI
+from langchain.schema import HumanMessage
+
+llm = ChatOpenAI(
+    model_name="cc/claude-sonnet-4-20250514",
+    openai_api_key="your-api-key-from-dashboard",
+    openai_api_base="http://localhost:20128/v1",
+    temperature=0.7
+)
+
+messages = [HumanMessage(content="Explain quantum computing")]
+response = llm(messages)
+print(response.content)
+```
+
+### LlamaIndex Integration
+
+```python
+from llama_index.llms import OpenAI
+
+llm = OpenAI(
+    model="cc/claude-sonnet-4-20250514",
+    api_key="your-api-key-from-dashboard",
+    api_base="http://localhost:20128/v1"
+)
+
+response = llm.complete("What is machine learning?")
+print(response.text)
+```
+
+## Custom Script Examples
+
+### Batch Processing Script
+
+```python
+import openai
+import json
+
+openai.api_key = "your-api-key-from-dashboard"
+openai.api_base = "http://localhost:20128/v1"
+
+def process_batch(prompts, model="cx/deepseek-chat"):
+    results = []
+    for prompt in prompts:
+        response = openai.ChatCompletion.create(
+            model=model,
+            messages=[{"role": "user", "content": prompt}]
+        )
+        results.append({
+            "prompt": prompt,
+            "response": response.choices[0].message.content
+        })
+    return results
+
+prompts = [
+    "Explain AI in one sentence",
+    "What is machine learning?",
+    "Define neural networks"
+]
+
+results = process_batch(prompts)
+print(json.dumps(results, indent=2))
+```
+
+### Streaming Response Handler
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+async function streamResponse(prompt) {
+  const stream = await client.chat.completions.create({
+    model: "cc/claude-sonnet-4-20250514",
+    messages: [{ role: "user", content: prompt }],
+    stream: true
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content || "";
+    process.stdout.write(content);
+  }
+}
+
+streamResponse("Write a short story about AI");
+```
+
+### Multi-Model Comparison
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+models = [
+    "cc/claude-sonnet-4-20250514",
+    "cx/deepseek-chat",
+    "glm/glm-4-plus"
+]
+
+prompt = "Explain quantum computing in simple terms"
+
+for model in models:
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}]
+    )
+    print(f"\n=== {model} ===")
+    print(response.choices[0].message.content)
+```
+
+## Common Integration Patterns
+
+### Environment Variables
+
+Store credentials securely:
+
+```bash
+# .env file
+ROUTER_API_KEY=your-api-key-from-dashboard
+ROUTER_BASE_URL=http://localhost:20128/v1
+ROUTER_MODEL=cc/claude-sonnet-4-20250514
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.getenv("ROUTER_API_KEY"),
+    base_url=os.getenv("ROUTER_BASE_URL")
+)
+```
+
+### Error Handling
+
+```python
+from openai import OpenAI, OpenAIError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+try:
+    response = client.chat.completions.create(
+        model="cc/claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+    print(response.choices[0].message.content)
+except OpenAIError as e:
+    print(f"Error: {e}")
+```
+
+### Retry Logic
+
+```python
+import time
+from openai import OpenAI, RateLimitError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+def chat_with_retry(prompt, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = client.chat.completions.create(
+                model="cc/claude-sonnet-4-20250514",
+                messages=[{"role": "user", "content": prompt}]
+            )
+            return response.choices[0].message.content
+        except RateLimitError:
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)  # Exponential backoff
+            else:
+                raise
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+**Problem:** Cannot connect to 9Router
+```bash
+# Check if 9Router is running
+curl http://localhost:20128/health
+
+# Expected response:
+{"status": "ok"}
+```
+
+**Solution:**
+- Verify 9Router is running
+- Check port 20128 is not blocked
+- Ensure correct base URL (include `/v1`)
+
+### Authentication Errors
+
+**Problem:** 401 Unauthorized
+```
+Error: Invalid API key
+```
+
+**Solution:**
+- Verify API key from dashboard
+- Check Authorization header format: `Bearer your-api-key`
+- Ensure no extra spaces or newlines in API key
+
+### Model Not Found
+
+**Problem:** 404 Model not found
+```
+Error: Model 'cc/claude-opus' not found
+```
+
+**Solution:**
+- Use exact model name (case-sensitive)
+- Check available models: `curl http://localhost:20128/v1/models`
+- Verify model is enabled in your plan
+
+### Timeout Issues
+
+**Problem:** Request timeout
+```
+Error: Request timed out after 30s
+```
+
+**Solution:**
+- Increase timeout in client configuration
+- Use faster models for time-sensitive tasks
+- Check network connection to 9Router
+
+### Rate Limiting
+
+**Problem:** 429 Too Many Requests
+```
+Error: Rate limit exceeded
+```
+
+**Solution:**
+- Implement exponential backoff
+- Reduce request frequency
+- Check rate limits in dashboard
+- Consider upgrading plan
+
+## Best Practices
+
+### Security
+- Store API keys in environment variables
+- Never commit API keys to version control
+- Use HTTPS for cloud deployments
+- Rotate API keys regularly
+
+### Performance
+- Use appropriate models for task complexity
+- Implement caching for repeated queries
+- Use streaming for long responses
+- Batch requests when possible
+
+### Error Handling
+- Always implement try-catch blocks
+- Add retry logic with exponential backoff
+- Log errors for debugging
+- Provide fallback mechanisms
+
+### Cost Optimization
+- Choose cost-effective models for simple tasks
+- Cache responses when appropriate
+- Monitor usage in dashboard
+- Set request limits in code
+
+## Next Steps
+
+- [Configure Cursor](cursor.md) for IDE integration
+- [Set up Continue](continue.md) for VSCode
+- [Explore CLI usage](../cli/basic-usage.md)
+- [Learn about model selection](../models/overview.md)
+- [API Reference](../api/reference.md)
--- a/gitbook/content/en/integration/roo.md
+++ b/gitbook/content/en/integration/roo.md
@@ -0,0 +1,127 @@
+# Roo AI Assistant Integration
+
+Integrate 9Router with Roo AI Assistant to access multiple AI models through a unified interface.
+
+## Prerequisites
+
+- Roo AI Assistant installed
+- 9Router API key from [dashboard](https://9router.com/dashboard)
+- 9Router running (local or cloud)
+
+## Configuration Steps
+
+### 1. Open Roo Settings
+
+Launch Roo AI Assistant and open the settings panel.
+
+### 2. Configure API Provider
+
+1. Navigate to **API Provider** settings
+2. Select **Ollama** as the provider type
+3. Configure the following settings:
+
+**For Local 9Router:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+```
+
+**For Cloud 9Router:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+```
+
+### 3. Select Model
+
+Choose from available 9Router models:
+
+**Claude Models:**
+- `cc/claude-opus-4-5-20251101` - Most capable
+- `cc/claude-sonnet-4-20250514` - Balanced
+- `cc/claude-haiku-4-20250514` - Fast
+
+**DeepSeek Models:**
+- `cx/deepseek-chat` - General purpose
+- `cx/deepseek-reasoner` - Complex reasoning
+
+**GLM Models:**
+- `glm/glm-4-plus` - Advanced
+- `glm/glm-4-flash` - Fast responses
+
+### 4. Test Connection
+
+Send a test message to verify the integration:
+
+```
+Hello! Can you confirm you're connected through 9Router?
+```
+
+## Usage Examples
+
+### Basic Chat
+```
+Ask Roo: "Explain quantum computing in simple terms"
+Model: cc/claude-sonnet-4-20250514
+```
+
+### Code Generation
+```
+Ask Roo: "Write a Python function to calculate Fibonacci numbers"
+Model: cx/deepseek-chat
+```
+
+### Complex Reasoning
+```
+Ask Roo: "Analyze the trade-offs between microservices and monolithic architecture"
+Model: cx/deepseek-reasoner
+```
+
+## Model Selection Tips
+
+- **Quick tasks**: Use `cc/claude-haiku-4-20250514` or `glm/glm-4-flash`
+- **Balanced performance**: Use `cc/claude-sonnet-4-20250514` or `cx/deepseek-chat`
+- **Complex reasoning**: Use `cc/claude-opus-4-5-20251101` or `cx/deepseek-reasoner`
+- **Cost optimization**: Use DeepSeek or GLM models
+
+## Troubleshooting
+
+### Connection Failed
+- Verify 9Router is running: `curl http://localhost:20128/health`
+- Check API key is correct
+- Ensure Base URL includes `/v1` suffix
+
+### Model Not Available
+- Check model name matches exactly (case-sensitive)
+- Verify model is enabled in your 9Router plan
+- Try a different model from the list
+
+### Slow Responses
+- Switch to faster models (haiku, flash)
+- Check network connection
+- Monitor 9Router logs for issues
+
+## Advanced Configuration
+
+### Custom Model Aliases
+
+You can create shortcuts for frequently used models in Roo settings:
+
+```
+Alias: "fast" → cc/claude-haiku-4-20250514
+Alias: "smart" → cc/claude-opus-4-5-20251101
+Alias: "code" → cx/deepseek-chat
+```
+
+### Multiple Profiles
+
+Set up different profiles for different use cases:
+- **Development**: DeepSeek models for code
+- **Writing**: Claude models for content
+- **Research**: Reasoner models for analysis
+
+## Next Steps
+
+- [Configure Cursor](cursor.md) for IDE integration
+- [Set up Continue](continue.md) for VSCode
+- [Explore CLI usage](../cli/basic-usage.md)
--- a/gitbook/content/en/providers/cheap.md
+++ b/gitbook/content/en/providers/cheap.md
@@ -0,0 +1,462 @@
+# Cheap Providers - Ultra-Cheap Backup
+
+When subscription quota runs out, pay pennies instead of dollars. ~90% cheaper than ChatGPT API!
+
+---
+
+## Overview
+
+Cheap tier providers are your **backup** when subscription quota exhausted:
+
+- 💰 **GLM-4.7** - $0.6/$2.2 per 1M tokens (daily reset)
+- 💰 **MiniMax M2.1** - $0.2/$1.0 per 1M tokens (5h reset)
+- 💰 **Kimi K2** - $9/month flat (10M tokens)
+
+**Strategy:** Use after subscription quota out, before free tier. Massive cost savings vs ChatGPT API ($20/1M).
+
+---
+
+## GLM-4.7 (Daily Reset)
+
+### Pricing
+
+| Tier | Input | Output | Reset |
+|------|-------|--------|-------|
+| Standard | $0.60/1M | $2.20/1M | Daily 10:00 AM |
+| Coding Plan | $0.60/1M | $2.20/1M | Daily 10:00 AM (3× quota) |
+
+**Cost Example (10M tokens):**
+- Input: 10M × $0.60 = $6
+- Output: 10M × $2.20 = $22
+- **Total: $6-22** vs $200 on ChatGPT API!
+
+### Setup
+
+**Step 1: Sign Up**
+
+1. Visit [Zhipu AI](https://open.bigmodel.cn/)
+2. Create account (phone verification)
+3. Choose **Coding Plan** for 3× quota at same price
+
+**Step 2: Get API Key**
+
+```bash
+Dashboard → API Keys → Create New
+→ Copy API key (starts with "zhipu-")
+```
+
+**Step 3: Add to 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: glm
+API Key: zhipu-your-api-key-here
+```
+
+**Step 4: Use in CLI**
+
+```
+Model: glm/glm-4.7
+       glm/glm-4.6v (vision)
+```
+
+### Available Models
+
+| Model ID | Description | Context | Best For |
+|----------|-------------|---------|----------|
+| `glm/glm-4.7` | GLM 4.7 | 128K | Coding, general tasks |
+| `glm/glm-4.6v` | GLM 4.6V Vision | 128K | Image analysis |
+
+### Pro Tips
+
+- **Coding Plan** - 3× quota at same price ($0.6/$2.2)
+- **Daily reset** - Fresh quota at 10:00 AM Beijing time
+- **Best for coding** - Optimized for code generation
+- **128K context** - Handle large files
+
+### Quota Reset
+
+```
+Daily reset: 10:00 AM Beijing Time (UTC+8)
+→ 2:00 AM UTC
+→ 6:00 PM PST (previous day)
+→ 9:00 PM EST (previous day)
+
+Plan your heavy tasks around reset time!
+```
+
+---
+
+## MiniMax M2.1 (5-Hour Reset)
+
+### Pricing
+
+| Tier | Input | Output | Reset |
+|------|-------|--------|-------|
+| Standard | $0.20/1M | $1.00/1M | 5-hour rolling |
+
+**Cost Example (10M tokens):**
+- Input: 10M × $0.20 = $2
+- Output: 10M × $1.00 = $10
+- **Total: $2-10** - Cheapest option!
+
+### Setup
+
+**Step 1: Sign Up**
+
+1. Visit [MiniMax](https://www.minimax.io/)
+2. Create account
+3. Verify email/phone
+
+**Step 2: Get API Key**
+
+```bash
+Dashboard → API Management → Create Key
+→ Copy API key
+```
+
+**Step 3: Add to 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: minimax
+API Key: your-minimax-api-key
+```
+
+**Step 4: Use in CLI**
+
+```
+Model: minimax/MiniMax-M2.1
+```
+
+### Available Models
+
+| Model ID | Description | Context | Best For |
+|----------|-------------|---------|----------|
+| `minimax/MiniMax-M2.1` | MiniMax M2.1 | 1M tokens | Long context, coding |
+
+### Pro Tips
+
+- **Cheapest option** - $0.20/1M input (90% cheaper than ChatGPT)
+- **5-hour rolling** - Quota resets every 5 hours
+- **1M context** - Massive context window
+- **Best for long files** - Handle entire codebases
+
+### Quota Reset
+
+```
+5-hour rolling window:
+→ Use quota → Wait 5 hours → Fresh quota
+
+Example:
+10:00 AM - Use 5M tokens
+3:00 PM - Fresh quota available
+8:00 PM - Fresh quota available
+
+Code 24/7 with minimal cost!
+```
+
+---
+
+## Kimi K2 (Flat $9/month)
+
+### Pricing
+
+| Plan | Monthly Cost | Included Tokens | Effective Cost |
+|------|--------------|-----------------|----------------|
+| Subscription | $9 | 10M tokens | $0.90/1M |
+
+**Cost Example:**
+- $9/month flat
+- 10M tokens included
+- **Effective: $0.90/1M** - Best value for consistent usage!
+
+### Setup
+
+**Step 1: Subscribe**
+
+1. Visit [Moonshot AI](https://platform.moonshot.ai/)
+2. Create account
+3. Subscribe to $9/month plan
+
+**Step 2: Get API Key**
+
+```bash
+Dashboard → API Keys → Create New
+→ Copy API key
+```
+
+**Step 3: Add to 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: kimi
+API Key: your-kimi-api-key
+```
+
+**Step 4: Use in CLI**
+
+```
+Model: kimi/kimi-latest
+```
+
+### Available Models
+
+| Model ID | Description | Context | Best For |
+|----------|-------------|---------|----------|
+| `kimi/kimi-latest` | Kimi Latest | 200K | General coding |
+
+### Pro Tips
+
+- **Fixed cost** - $9/month regardless of usage (up to 10M)
+- **Best for consistent usage** - If you use 10M/month, only $0.90/1M
+- **Monthly reset** - 10M tokens reset monthly
+- **Predictable billing** - No surprise costs
+
+### Quota Reset
+
+```
+Monthly reset: 1st of each month
+→ 10M tokens refresh
+
+Example monthly usage:
+Week 1: 3M tokens
+Week 2: 2M tokens
+Week 3: 3M tokens
+Week 4: 2M tokens
+Total: 10M tokens = $9 flat
+```
+
+---
+
+## Pricing Comparison
+
+| Provider | Input/1M | Output/1M | Reset | 10M Cost | Best For |
+|----------|----------|-----------|-------|----------|----------|
+| **GLM-4.7** | $0.60 | $2.20 | Daily 10AM | $6-22 | Daily quota users |
+| **MiniMax M2.1** | $0.20 | $1.00 | 5-hour | $2-10 | **Cheapest!** |
+| **Kimi K2** | $0.90 | $0.90 | Monthly | **$9 flat** | Consistent usage |
+| ChatGPT API | $20.00 | $20.00 | None | $200 | ❌ Expensive |
+
+**Savings:** 90-95% cheaper than ChatGPT API!
+
+---
+
+## Usage Example
+
+### Cursor IDE Setup
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: glm/glm-4.7
+```
+
+### Create Combo (Recommended)
+
+```
+Dashboard → Combos → Create New
+
+Name: cheap-backup
+Models:
+  1. cc/claude-opus-4-5 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, daily reset)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback)
+  4. if/kimi-k2-thinking (FREE emergency)
+
+Use in CLI: cheap-backup
+```
+
+**Result:** Subscription → Cheap → Cheapest → Free
+
+---
+
+## Cost Optimization
+
+### Strategy 1: Daily Reset Routine
+
+```
+Morning (10AM): Fresh GLM quota
+→ Use GLM for heavy tasks
+→ Save subscription quota
+
+Afternoon: Subscription quota
+→ Use Claude/Codex for complex tasks
+
+Evening: MiniMax (5h reset)
+→ Cheap fallback for late work
+
+Night: Free tier (iFlow)
+→ Zero cost emergency backup
+```
+
+### Strategy 2: Budget-First
+
+```
+Set monthly budget: $20
+
+Allocation:
+- $9 Kimi K2 (10M tokens flat)
+- $6 GLM daily quota (10M tokens)
+- $5 MiniMax overflow (25M tokens)
+
+Total: 45M tokens for $20
+vs 1M tokens for $20 on ChatGPT API!
+```
+
+### Strategy 3: Maximize Subscriptions First
+
+```
+Priority:
+1. Gemini CLI (180K/month FREE)
+2. Claude Code (subscription you already pay)
+3. GLM-4.7 (cheap backup, $0.6/1M)
+4. MiniMax M2.1 (cheapest, $0.2/1M)
+5. iFlow (FREE emergency)
+
+Monthly cost example (100M tokens):
+- 60M via Gemini CLI: $0 (free)
+- 30M via Claude Code: $0 (subscription)
+- 8M via GLM: $4.80
+- 2M via MiniMax: $0.40
+Total: $5.20/month!
+```
+
+---
+
+## Real-World Examples
+
+### Example 1: Heavy Coding Month (100M tokens)
+
+```
+Breakdown:
+- 60M via subscription (Claude/Codex): $0 extra
+- 30M via GLM-4.7: $18
+- 10M via MiniMax M2.1: $2
+
+Total: $20/month
+vs $2000 on ChatGPT API!
+
+Savings: 99% cheaper!
+```
+
+### Example 2: Budget Coder ($10/month)
+
+```
+Strategy:
+- $9 Kimi K2 (10M tokens)
+- $1 MiniMax overflow (5M tokens)
+
+Total: 15M tokens for $10
+vs 0.5M tokens for $10 on ChatGPT API!
+
+30× more tokens!
+```
+
+### Example 3: Freelancer (Variable Usage)
+
+```
+Light month (20M tokens):
+- 15M via subscription: $0
+- 5M via GLM: $3
+Total: $3
+
+Heavy month (150M tokens):
+- 60M via subscription: $0
+- 60M via GLM: $36
+- 30M via MiniMax: $6
+Total: $42
+
+Average: $22.50/month
+vs $3400 on ChatGPT API!
+```
+
+---
+
+## Best Practices
+
+### 1. Track Daily Quota
+
+```
+Dashboard shows:
+- GLM quota: 75% used (reset in 6h)
+- MiniMax quota: 50% used (reset in 2h)
+- Kimi quota: 8M/10M used (reset in 15 days)
+
+Plan heavy tasks around reset times!
+```
+
+### 2. Use Coding Plan (GLM)
+
+```
+Standard: 1× quota
+Coding Plan: 3× quota (same price!)
+
+→ Always choose Coding Plan
+```
+
+### 3. Combine with Free Tier
+
+```
+Combo:
+1. gc/gemini-3-flash (FREE primary)
+2. glm/glm-4.7 (cheap backup)
+3. minimax/MiniMax-M2.1 (cheapest)
+4. if/kimi-k2-thinking (FREE emergency)
+
+Result: Minimize costs, maximize uptime
+```
+
+### 4. Set Budget Alerts
+
+```
+Dashboard → Settings → Budget Alerts
+
+Daily: $2 limit
+Weekly: $10 limit
+Monthly: $30 limit
+
+→ Auto switch to free tier when limit reached
+```
+
+---
+
+## Troubleshooting
+
+### "Quota exhausted"
+
+**Solution:**
+- GLM: Wait until 10:00 AM Beijing time
+- MiniMax: Wait 5 hours from first use
+- Kimi: Wait until 1st of next month
+- Use combo fallback to free tier
+
+### "API key invalid"
+
+**Solution:**
+- Check API key copied correctly
+- Verify account has credits
+- Regenerate API key if needed
+
+### "High costs"
+
+**Solution:**
+- Check usage stats in Dashboard
+- Set budget alerts
+- Switch to MiniMax ($0.2/1M cheapest)
+- Use free tier for non-critical tasks
+
+---
+
+## Next Steps
+
+- **Add free fallback:** [Free Providers](./free.md)
+- **Setup subscriptions:** [Subscription Providers](./subscription.md)
+- **Create combos:** Dashboard → Combos → Create New
--- a/gitbook/content/en/providers/free.md
+++ b/gitbook/content/en/providers/free.md
@@ -0,0 +1,442 @@
+# Free Providers - Zero Cost Fallback
+
+Emergency backup when everything else is quota-limited. Code 24/7 with zero cost!
+
+---
+
+## Overview
+
+Free tier providers are your **fallback** when subscription and cheap quota exhausted:
+
+- 🆓 **iFlow** - 8 models FREE (Kimi K2, Qwen3, GLM 4.7, MiniMax M2...)
+- 🆓 **Qwen** - 3 models FREE (Qwen3 Coder Plus/Flash, Vision)
+- 🆓 **Kiro** - 2 models FREE (Claude Sonnet 4.5, Haiku 4.5)
+
+**Strategy:** Use as emergency backup. Unlimited usage, zero cost forever!
+
+---
+
+## iFlow (8 FREE Models)
+
+### Pricing
+
+| Plan | Monthly Cost | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | 8 models | Unlimited |
+
+**Best Value:** Most models in free tier! Kimi K2, Qwen3, GLM, MiniMax, DeepSeek.
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect iFlow
+```
+
+**Step 2: iFlow OAuth Login**
+
+- Click "Connect iFlow"
+- Browser opens → iFlow login page
+- Create account or login
+- Grant permissions
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: if/kimi-k2-thinking
+       if/kimi-k2
+       if/qwen3-coder-plus
+       if/glm-4.7
+       if/minimax-m2
+       if/deepseek-r1
+       if/deepseek-v3.2-chat
+       if/deepseek-v3.2-reasoner
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `if/kimi-k2-thinking` | Kimi K2 Thinking | Complex reasoning |
+| `if/kimi-k2` | Kimi K2 | General coding |
+| `if/qwen3-coder-plus` | Qwen3 Coder Plus | Code generation |
+| `if/glm-4.7` | GLM 4.7 | Chinese + English |
+| `if/minimax-m2` | MiniMax M2 | Long context |
+| `if/deepseek-r1` | DeepSeek R1 | Reasoning tasks |
+| `if/deepseek-v3.2-chat` | DeepSeek V3.2 Chat | Conversational |
+| `if/deepseek-v3.2-reasoner` | DeepSeek V3.2 Reasoner | Complex logic |
+
+### Pro Tips
+
+- **8 models FREE** - Most variety in free tier
+- **Unlimited usage** - No quota limits
+- **Kimi K2 Thinking** - Best for complex reasoning
+- **DeepSeek R1** - Strong reasoning capabilities
+
+---
+
+## Qwen (3 FREE Models)
+
+### Pricing
+
+| Plan | Monthly Cost | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | 3 models | Unlimited |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Qwen
+```
+
+**Step 2: Device Code Authorization**
+
+- Click "Connect Qwen"
+- Dashboard shows device code
+- Visit authorization URL
+- Enter device code
+- Login to Qwen account
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: qw/qwen3-coder-plus
+       qw/qwen3-coder-flash
+       qw/vision-model
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `qw/qwen3-coder-plus` | Qwen3 Coder Plus | Advanced coding |
+| `qw/qwen3-coder-flash` | Qwen3 Coder Flash | Fast responses |
+| `qw/vision-model` | Qwen3 Vision | Image analysis |
+
+### Pro Tips
+
+- **Qwen3 Coder Plus** - Strong coding capabilities
+- **Qwen3 Coder Flash** - Fast for quick tasks
+- **Vision model** - FREE image analysis
+- **Unlimited usage** - No quota limits
+
+---
+
+## Kiro (Claude FREE)
+
+### Pricing
+
+| Plan | Monthly Cost | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | Claude Sonnet 4.5, Haiku 4.5 | Unlimited |
+
+**Best Value:** FREE Claude! Same quality as paid Claude Code.
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Kiro
+```
+
+**Step 2: AWS Builder ID or OAuth**
+
+- Click "Connect Kiro"
+- Choose login method:
+  - AWS Builder ID (recommended)
+  - Google account
+  - GitHub account
+- Grant permissions
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: kr/claude-sonnet-4.5
+       kr/claude-haiku-4.5
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `kr/claude-sonnet-4.5` | Claude Sonnet 4.5 | Balanced quality/speed |
+| `kr/claude-haiku-4.5` | Claude Haiku 4.5 | Fast responses |
+
+### Pro Tips
+
+- **FREE Claude** - Same quality as paid tier
+- **AWS Builder ID** - Easy setup with AWS account
+- **Unlimited usage** - No quota limits
+- **Best quality** - Claude 4.5 for free!
+
+---
+
+## Feature Comparison
+
+| Provider | Models | Best Model | Setup | Quota |
+|----------|--------|------------|-------|-------|
+| **iFlow** | 8 | Kimi K2 Thinking | OAuth | Unlimited |
+| **Qwen** | 3 | Qwen3 Coder Plus | Device Code | Unlimited |
+| **Kiro** | 2 | Claude Sonnet 4.5 | AWS Builder ID | Unlimited |
+
+**Winner:** iFlow for variety, Kiro for quality!
+
+---
+
+## Usage Example
+
+### Cursor IDE Setup
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: if/kimi-k2-thinking
+```
+
+### Create Combo (Recommended)
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking (iFlow primary)
+  2. qw/qwen3-coder-plus (Qwen backup)
+  3. kr/claude-sonnet-4.5 (Kiro quality)
+
+Use in CLI: free-combo
+```
+
+**Result:** Zero cost, maximum uptime!
+
+---
+
+## Full Fallback Strategy
+
+### Complete 3-Tier Combo
+
+```
+Dashboard → Combos → Create New
+
+Name: complete-fallback
+Models:
+  1. gc/gemini-3-flash-preview (FREE subscription)
+  2. cc/claude-opus-4-5 (Paid subscription)
+  3. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  4. minimax/MiniMax-M2.1 (Cheapest, $0.2/1M)
+  5. if/kimi-k2-thinking (FREE fallback)
+  6. kr/claude-sonnet-4.5 (FREE quality)
+
+Use in CLI: complete-fallback
+```
+
+**Result:**
+- Tier 1: FREE subscription (Gemini CLI)
+- Tier 2: Paid subscription (Claude Code)
+- Tier 3: Cheap backup (GLM, MiniMax)
+- Tier 4: FREE fallback (iFlow, Kiro)
+
+**Never stop coding!**
+
+---
+
+## Best Practices
+
+### 1. Use as Emergency Backup
+
+```
+Priority:
+1. Subscription tier (maximize paid quota)
+2. Cheap tier (pennies per 1M tokens)
+3. FREE tier (unlimited, zero cost)
+
+Only use free tier when:
+- Subscription quota exhausted
+- Budget limit reached
+- Testing/non-critical tasks
+```
+
+### 2. Choose Right Model
+
+```
+Complex reasoning: if/kimi-k2-thinking
+Fast coding: qw/qwen3-coder-flash
+Best quality: kr/claude-sonnet-4.5
+Long context: if/minimax-m2
+Vision tasks: qw/vision-model
+```
+
+### 3. Create Free-Only Combo
+
+```
+For zero-cost coding:
+
+Name: zero-cost
+Models:
+  1. kr/claude-sonnet-4.5 (Best quality)
+  2. if/kimi-k2-thinking (Complex tasks)
+  3. qw/qwen3-coder-plus (Fast coding)
+
+Cost: $0 forever!
+```
+
+### 4. Test Before Production
+
+```
+Use free tier to:
+- Test prompts
+- Prototype features
+- Learn new frameworks
+- Non-critical tasks
+
+Save paid quota for:
+- Production code
+- Complex refactoring
+- Critical features
+```
+
+---
+
+## Real-World Examples
+
+### Example 1: Student/Learner (Zero Budget)
+
+```
+Setup:
+1. kr/claude-sonnet-4.5 (Best quality)
+2. if/kimi-k2-thinking (Complex reasoning)
+3. qw/qwen3-coder-plus (Fast coding)
+
+Monthly cost: $0
+Usage: Unlimited
+
+Perfect for:
+- Learning to code
+- Personal projects
+- Homework/assignments
+```
+
+### Example 2: Freelancer (Budget-Conscious)
+
+```
+Setup:
+1. gc/gemini-3-flash-preview (FREE 180K/month)
+2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+3. if/kimi-k2-thinking (FREE fallback)
+
+Monthly cost: $5-10
+Usage: 100M+ tokens
+
+Perfect for:
+- Client projects (paid tier)
+- Testing (free tier)
+- Emergency backup
+```
+
+### Example 3: Heavy User (Maximize Everything)
+
+```
+Setup:
+1. gc/gemini-3-flash-preview (FREE 180K/month)
+2. cc/claude-opus-4-5 (Subscription $20-100)
+3. cx/gpt-5.2-codex (Subscription $20-200)
+4. glm/glm-4.7 (Cheap $0.6/1M)
+5. minimax/MiniMax-M2.1 (Cheapest $0.2/1M)
+6. if/kimi-k2-thinking (FREE unlimited)
+7. kr/claude-sonnet-4.5 (FREE quality)
+
+Monthly cost: $40-320 (subscriptions) + $10-20 (cheap tier)
+Usage: 500M+ tokens
+
+Perfect for:
+- Professional development
+- Team projects
+- 24/7 coding
+```
+
+---
+
+## Cost Comparison
+
+### Scenario: 100M tokens/month
+
+**Option 1: ChatGPT API Only**
+```
+100M × $20/1M = $2,000/month
+```
+
+**Option 2: 9Router Free Tier Only**
+```
+100M via free tier = $0/month
+Savings: $2,000/month (100%)
+```
+
+**Option 3: 9Router Complete Strategy**
+```
+60M via Gemini CLI (FREE): $0
+30M via Claude Code (subscription): $0 extra
+8M via GLM (cheap): $4.80
+2M via iFlow (FREE): $0
+Total: $4.80/month + subscriptions you already have
+Savings: $1,995/month (99.76%)
+```
+
+---
+
+## Troubleshooting
+
+### "OAuth failed"
+
+**Solution:**
+- Check internet connection
+- Try different browser
+- Clear browser cache
+- Reconnect in dashboard
+
+### "Model not available"
+
+**Solution:**
+- Check provider connected in dashboard
+- Verify OAuth token valid
+- Reconnect provider if needed
+
+### "Slow responses"
+
+**Solution:**
+- Free tier may have lower priority
+- Use during off-peak hours
+- Switch to different free provider
+- Upgrade to cheap tier for speed
+
+---
+
+## Limitations
+
+### Free Tier Considerations
+
+- **Speed** - May be slower than paid tiers
+- **Priority** - Lower priority during peak hours
+- **Rate limits** - Possible rate limiting (but unlimited quota)
+- **Availability** - May have occasional downtime
+
+**Solution:** Use 3-tier fallback strategy for reliability!
+
+---
+
+## Next Steps
+
+- **Setup subscriptions:** [Subscription Providers](./subscription.md)
+- **Add cheap backup:** [Cheap Providers](./cheap.md)
+- **Create combos:** Dashboard → Combos → Create New
+- **Start coding:** Use `complete-fallback` combo for maximum reliability
--- a/gitbook/content/en/providers/subscription.md
+++ b/gitbook/content/en/providers/subscription.md
@@ -0,0 +1,404 @@
+# Subscription Providers - Maximize Your Value
+
+Maximize your existing AI subscriptions with smart quota tracking and automatic fallback. Use every bit of your subscription before it resets!
+
+---
+
+## Overview
+
+Subscription tier providers are your **primary** choice - you're already paying for them, so get full value:
+
+- ✅ **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- ✅ **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
+- ✅ **Gemini CLI** (FREE tier!) - 180K completions/month
+- ✅ **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
+- ✅ **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
+
+**Strategy:** Use these first, track quota in real-time, fallback to cheap/free when exhausted.
+
+---
+
+## Claude Code (Pro/Max)
+
+### Pricing
+
+| Plan | Monthly Cost | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Pro | $20 | 5-hour + Weekly | Opus, Sonnet, Haiku |
+| Max | $100 | 5-hour + Weekly | Opus, Sonnet, Haiku |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard opens → Providers → Connect Claude Code
+```
+
+**Step 2: OAuth Login**
+
+- Click "Connect Claude Code"
+- Browser opens → Login to Claude.ai
+- Auto token refresh enabled
+- Quota tracking starts
+
+**Step 3: Use in CLI**
+
+```
+Model: cc/claude-opus-4-5-20251101
+       cc/claude-sonnet-4-5-20250929
+       cc/claude-haiku-4-5-20251001
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `cc/claude-opus-4-5-20251101` | Claude 4.5 Opus | Complex tasks, architecture |
+| `cc/claude-sonnet-4-5-20250929` | Claude 4.5 Sonnet | Balanced speed/quality |
+| `cc/claude-haiku-4-5-20251001` | Claude 4.5 Haiku | Fast responses |
+
+### Pro Tips
+
+- **Use Opus for complex tasks** - Architecture decisions, refactoring
+- **Use Sonnet for speed** - Quick edits, code generation
+- **Track quota per model** - Dashboard shows usage per model
+- **5-hour reset** - Fresh quota every 5 hours + weekly reset
+
+---
+
+## OpenAI Codex (Plus/Pro)
+
+### Pricing
+
+| Plan | Monthly Cost | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Plus | $20 | 5-hour + Weekly | GPT 5.2, GPT 5.1 |
+| Pro | $200 | 5-hour + Weekly | GPT 5.2 Codex, GPT 5.1 Max |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Codex
+```
+
+**Step 2: OAuth Login**
+
+- Click "Connect Codex"
+- Browser opens to `http://localhost:1455`
+- Login to OpenAI account
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: cx/gpt-5.2-codex
+       cx/gpt-5.1-codex-max
+       cx/gpt-5.2
+       cx/gpt-5.1-codex
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `cx/gpt-5.2-codex` | GPT 5.2 Codex | Latest coding model |
+| `cx/gpt-5.1-codex-max` | GPT 5.1 Codex Max | Maximum context |
+| `cx/gpt-5.2` | GPT 5.2 | General tasks |
+| `cx/gpt-5.1-codex` | GPT 5.1 Codex | Stable coding |
+
+### Pro Tips
+
+- **5-hour rolling quota** - Fresh quota every 5 hours
+- **Weekly reset** - Full quota reset weekly
+- **Pro tier** - 10× more quota than Plus
+
+---
+
+## Gemini CLI (FREE 180K/month!)
+
+### Pricing
+
+| Plan | Monthly Cost | Quota | Reset |
+|------|--------------|-------|-------|
+| FREE | $0 | 180K completions/month + 1K/day | Daily + Monthly |
+
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Gemini CLI
+```
+
+**Step 2: Google OAuth**
+
+- Click "Connect Gemini CLI"
+- Browser opens → Login to Google account
+- Grant permissions
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: gc/gemini-3-flash-preview
+       gc/gemini-3-pro-preview
+       gc/gemini-2.5-pro
+       gc/gemini-2.5-flash
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `gc/gemini-3-flash-preview` | Gemini 3 Flash Preview | Fast responses |
+| `gc/gemini-3-pro-preview` | Gemini 3 Pro Preview | Complex tasks |
+| `gc/gemini-2.5-pro` | Gemini 2.5 Pro | Stable production |
+| `gc/gemini-2.5-flash` | Gemini 2.5 Flash | Quick tasks |
+
+### Pro Tips
+
+- **180K completions/month** - Massive free tier
+- **1K/day limit** - Daily quota resets at midnight
+- **Use first** - Free tier, use before paid subscriptions
+- **No credit card** - Completely free with Google account
+
+---
+
+## GitHub Copilot
+
+### Pricing
+
+| Plan | Monthly Cost | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Individual | $10 | Monthly (1st) | GPT-5, Claude 4.5, Gemini 3 |
+| Business | $19 | Monthly (1st) | GPT-5, Claude 4.5, Gemini 3 |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect GitHub
+```
+
+**Step 2: OAuth via GitHub**
+
+- Click "Connect GitHub"
+- Browser opens → Login to GitHub
+- Authorize GitHub Copilot
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: gh/gpt-5
+       gh/gpt-5.1-codex-max
+       gh/claude-4.5-sonnet
+       gh/gemini-3-pro
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `gh/gpt-5` | GPT-5 | Latest OpenAI model |
+| `gh/gpt-5.1-codex-max` | GPT-5.1 Codex Max | Maximum context |
+| `gh/claude-4.5-sonnet` | Claude 4.5 Sonnet | Anthropic quality |
+| `gh/gemini-3-pro` | Gemini 3 Pro | Google quality |
+
+### Pro Tips
+
+- **Monthly reset** - Full quota reset on 1st of month
+- **Multiple models** - Access GPT, Claude, Gemini in one subscription
+- **Business tier** - Higher quota for teams
+
+---
+
+## Antigravity (Google Account)
+
+### Pricing
+
+| Plan | Monthly Cost | Quota | Models |
+|------|--------------|-------|--------|
+| FREE | $0 | Similar to Gemini CLI | Gemini 3 Pro, Claude Sonnet 4.5 |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Antigravity
+```
+
+**Step 2: Google OAuth**
+
+- Click "Connect Antigravity"
+- Browser opens → Login to Google account
+- Grant permissions
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: ag/gemini-3-pro-high
+       ag/claude-sonnet-4-5
+       ag/claude-opus-4-5-thinking
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `ag/gemini-3-pro-high` | Gemini 3 Pro High | High-quality responses |
+| `ag/claude-sonnet-4-5` | Claude Sonnet 4.5 | Anthropic quality |
+| `ag/claude-opus-4-5-thinking` | Claude Opus 4.5 Thinking | Complex reasoning |
+
+### Pro Tips
+
+- **Free tier** - No cost with Google account
+- **Claude access** - Free Claude Sonnet/Opus
+- **Quota similar to Gemini CLI** - Daily/monthly limits
+
+---
+
+## Pricing Comparison
+
+| Provider | Monthly Cost | Quota Reset | Value |
+|----------|--------------|-------------|-------|
+| **Claude Code Pro** | $20 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ Best quality |
+| **Claude Code Max** | $100 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ Highest quota |
+| **Codex Plus** | $20 | 5-hour + Weekly | ⭐⭐⭐⭐ Good value |
+| **Codex Pro** | $200 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ 10× quota |
+| **Gemini CLI** | **$0** | Daily + Monthly | ⭐⭐⭐⭐⭐ FREE 180K/month! |
+| **GitHub Copilot** | $10-19 | Monthly (1st) | ⭐⭐⭐⭐ Multi-model |
+| **Antigravity** | **$0** | Daily + Monthly | ⭐⭐⭐⭐ FREE Claude! |
+
+---
+
+## Usage Example
+
+### Cursor IDE Setup
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Create Combo (Recommended)
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. gc/gemini-3-flash-preview (FREE, use first)
+  2. cc/claude-opus-4-5-20251101 (Subscription)
+  3. cx/gpt-5.2-codex (Subscription backup)
+
+Use in CLI: premium-coding
+```
+
+**Result:** Maximize free tier → Use subscription → Auto fallback
+
+---
+
+## Quota Tracking
+
+9Router tracks quota in real-time:
+
+- **Token consumption** - Input/output tokens per request
+- **Reset countdown** - Time until next quota reset
+- **Usage percentage** - How much quota used
+- **Auto fallback** - Switch to next tier when exhausted
+
+**Dashboard view:**
+
+```
+Claude Code Pro
+├─ Quota: 75% used
+├─ Reset: 2h 15m (5-hour)
+├─ Weekly reset: 3 days
+└─ Fallback: glm/glm-4.7 (cheap tier)
+```
+
+---
+
+## Best Practices
+
+### 1. Use Free Tier First
+
+```
+Priority:
+1. Gemini CLI (180K/month FREE)
+2. Antigravity (FREE Claude)
+3. Claude Code/Codex (paid subscriptions)
+```
+
+### 2. Track Quota Daily
+
+- Check dashboard every morning
+- Plan heavy tasks around quota resets
+- Use cheap/free tier for non-critical tasks
+
+### 3. Create Smart Combos
+
+```
+Example combo:
+1. gc/gemini-3-flash-preview (FREE primary)
+2. cc/claude-opus-4-5 (Complex tasks)
+3. glm/glm-4.7 (Cheap backup)
+4. if/kimi-k2-thinking (FREE fallback)
+```
+
+### 4. Optimize by Time
+
+```
+Morning: Fresh 5-hour quota (Claude/Codex)
+Afternoon: Gemini CLI (1K/day)
+Evening: Subscription quota
+Night: Cheap/free tier
+```
+
+---
+
+## Troubleshooting
+
+### "Quota exhausted"
+
+**Solution:**
+- Check dashboard quota tracker
+- Wait for reset (5-hour or daily)
+- Use combo fallback to cheap/free tier
+
+### "OAuth token expired"
+
+**Solution:**
+- Auto-refreshed by 9Router
+- If issues: Dashboard → Provider → Reconnect
+
+### "Rate limiting"
+
+**Solution:**
+- Subscription quota out
+- Add fallback: `cc/claude-opus → glm/glm-4.7`
+- Use free tier: `if/kimi-k2-thinking`
+
+---
+
+## Next Steps
+
+- **Setup cheap backup:** [Cheap Providers](./cheap.md)
+- **Add free fallback:** [Free Providers](./free.md)
+- **Create combos:** Dashboard → Combos → Create New
--- a/gitbook/content/en/troubleshooting.md
+++ b/gitbook/content/en/troubleshooting.md
@@ -0,0 +1,351 @@
+# Troubleshooting
+
+Common issues and solutions when using 9Router.
+
+---
+
+## "Language model did not provide messages"
+
+**Problem:** Request fails with empty response or error message.
+
+**Causes:**
+- Provider quota exhausted
+- API key invalid or expired
+- Model not available
+
+**Solutions:**
+
+1. **Check quota status:**
+   ```
+   Dashboard → Providers → View quota tracker
+   ```
+   If quota is exhausted, wait for reset or switch provider.
+
+2. **Use combo fallback:**
+   ```
+   Dashboard → Combos → Create fallback chain
+   Example: cc/claude-opus → glm/glm-4.7 → if/kimi-k2
+   ```
+
+3. **Verify provider connection:**
+   ```
+   Dashboard → Providers → Reconnect if needed
+   ```
+
+---
+
+## Rate Limiting
+
+**Problem:** "Rate limit exceeded" or "Too many requests" errors.
+
+**Causes:**
+- Subscription quota depleted (5-hour/daily/weekly limits)
+- API rate limits hit
+- Too many concurrent requests
+
+**Solutions:**
+
+1. **Check reset time:**
+   ```
+   Dashboard → Quota Tracking → View reset countdown
+   ```
+
+2. **Switch to cheap tier:**
+   ```
+   Use: glm/glm-4.7 ($0.6/1M tokens)
+        minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Add fallback combo:**
+   ```
+   Dashboard → Combos → Add backup models
+   Primary: cc/claude-opus (subscription)
+   Backup: glm/glm-4.7 (cheap)
+   Emergency: if/kimi-k2 (free)
+   ```
+
+---
+
+## OAuth Token Expired
+
+**Problem:** "Unauthorized" or "Token expired" errors.
+
+**Causes:**
+- OAuth token expired (auto-refresh failed)
+- Provider session invalidated
+- Network issues during refresh
+
+**Solutions:**
+
+1. **Auto-refresh (default):**
+   9Router automatically refreshes tokens. Wait 30 seconds and retry.
+
+2. **Manual reconnect:**
+   ```
+   Dashboard → Providers → [Provider Name] → Reconnect
+   → Complete OAuth flow again
+   ```
+
+3. **Check provider status:**
+   Verify provider service is online (Claude Code, Codex, etc.)
+
+---
+
+## High Costs
+
+**Problem:** Unexpected high usage or costs.
+
+**Causes:**
+- Using expensive models unnecessarily
+- No fallback to cheaper tiers
+- Large context windows
+
+**Solutions:**
+
+1. **Check usage stats:**
+   ```
+   Dashboard → Usage Stats → View token consumption
+   → Identify high-cost models
+   ```
+
+2. **Switch to cheaper models:**
+   ```
+   Replace: cc/claude-opus ($20-100/month subscription)
+   With: glm/glm-4.7 ($0.6/1M tokens)
+         minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Use free tier:**
+   ```
+   if/kimi-k2-thinking (FREE)
+   qw/qwen3-coder-plus (FREE)
+   kr/claude-sonnet-4.5 (FREE)
+   gc/gemini-3-flash-preview (FREE 180K/month)
+   ```
+
+4. **Optimize prompts:**
+   - Reduce context size
+   - Use streaming for long responses
+   - Cache common prompts
+
+---
+
+## Connection Refused
+
+**Problem:** "ECONNREFUSED" or "Cannot connect to localhost:20128".
+
+**Causes:**
+- 9Router not running
+- Port 20128 blocked
+- Firewall blocking connection
+
+**Solutions:**
+
+1. **Start 9Router:**
+   ```bash
+   9router
+   ```
+   Dashboard should open at http://localhost:3000
+
+2. **Verify port 20128:**
+   ```bash
+   # Check if port is listening
+   lsof -i :20128
+   
+   # Or on Windows
+   netstat -ano | findstr :20128
+   ```
+
+3. **Check firewall:**
+   - macOS: System Settings → Network → Firewall
+   - Windows: Windows Defender Firewall → Allow app
+   - Linux: `sudo ufw allow 20128`
+
+4. **Use cloud endpoint:**
+   If localhost doesn't work (e.g., Cursor IDE):
+   ```
+   Endpoint: https://9router.com/v1
+   ```
+
+---
+
+## Dashboard Not Opening
+
+**Problem:** Dashboard doesn't load at http://localhost:3000.
+
+**Causes:**
+- Port 3000 already in use
+- 9Router crashed
+- Browser cache issues
+
+**Solutions:**
+
+1. **Check if 9Router is running:**
+   ```bash
+   # Check process
+   ps aux | grep 9router
+   
+   # Check port 3000
+   lsof -i :3000
+   ```
+
+2. **Kill conflicting process:**
+   ```bash
+   # macOS/Linux
+   lsof -ti:3000 | xargs kill -9
+   
+   # Windows
+   netstat -ano | findstr :3000
+   taskkill /PID <PID> /F
+   ```
+
+3. **Restart 9Router:**
+   ```bash
+   # Stop
+   pkill -f 9router
+   
+   # Start
+   9router
+   ```
+
+4. **Clear browser cache:**
+   - Chrome: Ctrl+Shift+Delete → Clear cache
+   - Try incognito mode
+
+5. **Check firewall settings:**
+   Ensure port 3000 is not blocked.
+
+---
+
+## Model Not Found
+
+**Problem:** "Model not found" or "Invalid model" errors.
+
+**Causes:**
+- Provider not connected
+- Model ID typo
+- Provider inactive
+
+**Solutions:**
+
+1. **Verify provider connection:**
+   ```
+   Dashboard → Providers → Check status (green = active)
+   ```
+
+2. **Check model ID format:**
+   ```
+   Correct: cc/claude-opus-4-5-20251101
+   Wrong: claude-opus-4-5-20251101
+   
+   Format: [provider-prefix]/[model-name]
+   ```
+
+3. **List available models:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer your-api-key"
+   ```
+
+4. **Reconnect provider:**
+   ```
+   Dashboard → Providers → [Provider] → Reconnect
+   ```
+
+---
+
+## Slow Response
+
+**Problem:** Requests take too long or timeout.
+
+**Causes:**
+- Provider latency
+- Network issues
+- Large context/response
+- Provider rate limiting
+
+**Solutions:**
+
+1. **Check provider status:**
+   ```
+   Dashboard → Providers → View latency stats
+   ```
+
+2. **Switch to faster model:**
+   ```
+   Fast: cc/claude-haiku-4-5 (Haiku is faster than Opus)
+         gc/gemini-3-flash-preview
+         qw/qwen3-coder-flash
+   ```
+
+3. **Use streaming:**
+   ```json
+   {
+     "model": "cc/claude-opus-4-5",
+     "messages": [...],
+     "stream": true
+   }
+   ```
+
+4. **Check network:**
+   ```bash
+   # Test latency
+   ping api.anthropic.com
+   ping api.openai.com
+   ```
+
+5. **Reduce context size:**
+   - Trim message history
+   - Use smaller prompts
+   - Enable context pruning in CLI tool
+
+---
+
+## API Key Invalid
+
+**Problem:** "Invalid API key" or "Authentication failed" errors.
+
+**Causes:**
+- Wrong API key copied
+- API key expired
+- API key not generated
+
+**Solutions:**
+
+1. **Regenerate API key:**
+   ```
+   Dashboard → Settings → API Keys → Generate New Key
+   → Copy and use new key
+   ```
+
+2. **Verify key format:**
+   ```
+   Correct: 9r_xxxxxxxxxxxxxxxxxxxxxxxx
+   Wrong: Missing 9r_ prefix
+   ```
+
+3. **Check key in CLI config:**
+   ```bash
+   # Cursor
+   Settings → Models → OpenAI API Key
+   
+   # Cline
+   Settings → API Key
+   
+   # Environment variable
+   export OPENAI_API_KEY="9r_your_key"
+   ```
+
+4. **Test API key:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer 9r_your_key"
+   ```
+
+---
+
+## Need More Help?
+
+- **GitHub Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Documentation:** [9router.com/docs](https://9router.com/docs)
+- **FAQ:** [faq.md](faq.md)