docs: add comprehensive system architecture, deployment guide, and OmniRoute feature specification

ARCHITECTURE.md

@@ -1,143 +1,134 @@
-# Architecture Specification: Opencode-Cli
+# OpenCode Space — Production System Architecture & Design Specification
 
-This document details the software architecture, network routing, multi-service orchestration, and data persistence models for **Opencode-Cli** deployed on [Hugging Face Spaces (`Jishnupg/Opencode-Cli`)](https://huggingface.co/spaces/Jishnupg/Opencode-Cli).
+This document provides a comprehensive technical overview of the **`Jishnupg/Opencode-Cli`** multi-service gateway architecture, service discovery, database persistence model, security boundaries, and protocol proxies.
 
 ---
 
-## 1. System Overview
+## 1. System Ingress Topology & Port Matrix
 
-**Opencode-Cli** is an enterprise-grade multi-service web container running on Debian Bookworm Slim. It orchestrates six integrated services into a unified web application exposed via a single public ingress port (`4096`):
+All client traffic terminates at **Port 4096** (the exposed public port on Hugging Face Spaces). The system operates a dual-layer reverse proxy architecture to guarantee sub-second platform readiness and unified routing.
 
-1. **FastAPI Reverse Proxy & Gateway Router**: Ingress path-routing, CORS, WebSocket proxying, and service isolation.
-2. **Open WebUI**: Primary ChatGPT-style frontend pre-configured to use OmniRoute's dedicated API server (`127.0.0.1:20129/v1`).
-3. **OmniRoute v3.8.50 Multi-Port AI Gateway**:
-   - **Dashboard**: Port `20128` (Web UI & settings at `/omniroute`)
-   - **Dedicated API Server**: Port `20129` (OpenAI `/v1` & Gemini `/v1beta` compatibility)
-   - **Live WebSocket Server**: Port `20132` (Real-time monitoring)
-4. **Redis Cache & Rate Limiter**: Port `6379` (In-memory cache and distributed rate limiting for OmniRoute).
-5. **Jellyfin Media Server**: Port `8096` (Media streaming server at `/jellyfin`).
-6. **Telegram 5G Stream Proxy**: Port `8080` (High-speed MTProto streaming daemon at `/tg-stream`).
+```
+                                  [🌐 Public Internet Client]
+                                               │
+                                 [Nginx Edge Proxy (Port 4096)]
+                                               │
+                                 [FastAPI Master Gateway (:8000)]
+                                               │
+  ┌──────────────────┬─────────────────────────┼────────────────────────┬──────────────────┐
+  │                  │                         │                        │                  │
+[Open WebUI]  [OmniRoute Dashboard]   [OmniRoute Dedicated API] [Jellyfin Media]  [TG 5G Streamer]
+(Port 8098)    (Port 20128)             (Port 20129)             (Port 8096)        (Port 8080)
+  Path: /       Path: /dashboard         Path: /v1, /v1beta       Path: /jellyfin    Path: /tg-stream
+```
+
+### Complete Ingress Routing Matrix
+
+| Ingress Path / Pattern | Upstream Host:Port | Microservice | Protocol / Handler | Header Sanitization |
+| :--- | :--- | :--- | :--- | :--- |
+| `GET /health/live` | Internal Gateway | FastAPI Gateway | Native ASGI JSON | Instant 200 OK (<1ms) |
+| `/` (Default Fallback) | `127.0.0.1:8098` | Open WebUI | HTTP / Socket.IO WS | HTML base rewrite (`/`) |
+| `/omniroute`, `/omniroute/`| `127.0.0.1:8000` | FastAPI Gateway | HTTP 307 Redirect | Redirects to `/dashboard` |
+| `/dashboard/*` | `127.0.0.1:20128` | OmniRoute Dashboard | HTTP / Next.js SSR | Strip X-Frame-Options |
+| `/v1/*`, `/api/v1/*` | `127.0.0.1:20129` | Dedicated OpenAI API | OpenAI SSE Stream | CORS `*`, `Host` forward |
+| `/v1beta/*`, `/api/v1beta/*`| `127.0.0.1:20129` | Dedicated Gemini API | Gemini JSON / Stream | CORS `*`, `Host` forward |
+| `/api/providers/*` | `127.0.0.1:20128` | OmniRoute Management | REST JSON API | Encrypted DB read |
+| `/api/custom-models/*` | `127.0.0.1:20128` | OmniRoute Management | REST JSON API | Referer-based proxy |
+| `/api/connections/*` | `127.0.0.1:20128` | OmniRoute Management | REST JSON API | Referer-based proxy |
+| `/api/oauth/*` | `127.0.0.1:20128` | OmniRoute OAuth | Remote OAuth Flow | `ALLOW_REMOTE_OAUTH` |
+| `/live-ws/*` | `127.0.0.1:20132` | Live Telemetry WS | WebSocket Stream | `Host`, `X-Forwarded-*` |
+| `/jellyfin/*` | `127.0.0.1:8096` | Jellyfin Media Server | Range Video / HTTP | `X-Forwarded-Prefix` |
+| `/tg-stream/*`, `/tg_stream/*`| `127.0.0.1:8080` | Pyrogram 5G Streamer | 5G Chunk Streamer | Direct Pyrogram Stream |
 
 ---
 
-## 2. Production Architecture Diagram
-
-```mermaid
-flowchart TD
-    User([🌐 Public Web Client]) -->|HTTPS Port 443| Ingress[FastAPI Gateway Proxy - Port 4096]
-
-    subgraph Container ["🐳 Docker Container (Debian Bookworm Slim)"]
-        Ingress -->|Path: / , /api/config, /ws/socket.io | OWUI[Open WebUI - Port 8098]
-        Ingress -->|Path: /dashboard/* , /login, /callback | OmniDash[OmniRoute Dashboard - Port 20128]
-        Ingress -->|Path: /v1/* , /v1beta/* | OmniAPI[OmniRoute Dedicated API - Port 20129]
-        Ingress -->|Path: /live-ws/* | OmniWS[OmniRoute Live WS - Port 20132]
-        Ingress -->|Path: /jellyfin/* | JF[Jellyfin Media Server - Port 8096]
-        Ingress -->|Path: /tg-stream/* | TG[Telegram 5G Streamer - Port 8080]
-
-        OWUI -->|Internal OpenAI API /v1| OmniAPI
-        OmniDash -->|Distributed Cache & Limits| Redis[(Redis Server - Port 6379)]
-        OmniAPI -->|Distributed Cache & Limits| Redis
-        TG -->|Auto-Generate .strm Files| JF
-    end
-
-    subgraph Persistence ["💾 Persistence & Storage Model"]
-        Ext4["Local Container Ext4 (/root/.omniroute/storage.sqlite)"] <-->|SQLite .backup API (Every 120s)| HFData["HF FUSE Persistent Mount (/data/omniroute/storage.sqlite)"]
-        OmniDash -->|Fast POSIX SQLite Locks| Ext4
-        OWUI -->|User Accounts & DB| HFData
-        JF -->|Media & Metadata| HFData
-    end
+## 2. Gateway Core Engine Architecture (`gateway/`)
+
+The master gateway (`gateway/main.py`, `gateway/utils.py`, `gateway/omniroute.py`) provides intelligent request classification and routing.
+
+```
+                           [Incoming HTTP Request]
+                                      │
+                         [Security Path Traversal Check]
+                                      │
+                        [Lightweight Probe /health/live?] ──(Yes)──> 200 OK
+                                      │ (No)
+                         [Referer Header Inspection]
+                        /                                \
+           (Referer has /dashboard)            (No OmniRoute Referer)
+                      │                                    │
+           [Route to OmniRoute :20128]             [Match Path Prefix Matrix]
+                                                  /        │         \
+                                        (OmniRoute)   (Jellyfin)  (TG Stream)
+                                            │              │           │
+                                         [:20128]       [:8096]     [:8080]
+                                                           │
+                                                  [Default Fallback]
+                                                           │
+                                                    [Open WebUI :8098]
 ```
 
+### Key Gateway Design Patterns:
+1. **Async Connection Pooling (`httpx.AsyncClient`)**: Managed via FastAPI `@asynccontextmanager` lifespan. Connection keep-alive prevents TCP handshake overhead across internal microservice proxies.
+2. **Referer-Aware Routing**: Requests originating from OmniRoute UI pages (`Referer` containing `/dashboard` or `/omniroute`) are routed directly to OmniRoute port `20128`. This prevents auxiliary requests (`/api/custom-models`, `/api/connections`, `/providers/*.svg`) from falling through to Open WebUI.
+3. **CORS & iFrame Security Normalization**: Automatically strips restrictive `X-Frame-Options` headers and injects `Content-Security-Policy: frame-ancestors 'self' https://huggingface.co https://*.hf.space;` to enable embedding on Hugging Face Spaces.
+
 ---
 
-## 3. Microservice Specifications
-
-### 3.1 FastAPI Ingress Gateway (`proxy.py`, `gateway/`)
-- **Port**: `4096` (Exposed as container entrypoint)
-- **Role**:
-  - Single-port ingress on Hugging Face Spaces.
-  - Option A route classification with exact prefix boundaries.
-  - Proxies HTTP requests and bidirectional WebSockets (`/ws/socket.io` & `/live-ws`).
-
-### 3.2 Open WebUI (`open-webui`)
-- **Port**: `8098`
-- **Path**: `/` (Root Native Application)
-- **Environment**:
-  - `OPENAI_API_BASE_URL="http://127.0.0.1:20129/v1"`
-  - `ENABLE_OPENAI_API="true"`
-  - `RAG_AUTO_UPDATE_INDEX="false"`
-- **Optimization**: SentenceTransformer embeddings (`all-MiniLM-L6-v2`) pre-cached in Docker image.
-
-### 3.3 OmniRoute AI Gateway v3.8.50
-- **Ports**:
-  - **Dashboard**: `20128` (Path `/dashboard`, `/login`, `/callback`, `/api/providers`)
-  - **Dedicated API**: `20129` (Endpoints `/v1`, `/v1beta`)
-  - **Live WebSocket**: `20132` (Path `/live-ws`)
-- **Environment**:
-  - `NEXT_PUBLIC_BASE_URL="https://jishnupg-opencode-cli.hf.space"`
-  - `AUTH_COOKIE_SECURE="true"`
-  - `REDIS_URL="redis://127.0.0.1:6379"`
-  - `DATA_DIR="/root/.omniroute"`
-- **Auto-Fix**: `fix_omniroute.py` auto-resolves migration version collisions at build time and container boot.
-
-### 3.4 Redis Server (`redis-server`)
-- **Port**: `6379`
-- **Role**: In-memory rate limiting and distributed caching for OmniRoute.
-
-### 3.5 Jellyfin Media Server (`jellyfin`)
-- **Port**: `8096`
-- **Path**: `/jellyfin`
-- **Engine**: Jellyfin 10.11 + FFmpeg 5.1.
-
-### 3.6 Telegram Direct Stream Proxy (`tg_streamer.py`)
-- **Port**: `8080`
-- **Path**: `/tg-stream`
-- **Engine**: Python Pyrogram MTProto Client.
+## 3. Storage Persistence & SQLite Synchronization Model
 
----
+OmniRoute uses `better-sqlite3`. To bypass FUSE network drive lock limitations while maintaining persistence, a dual-layer storage architecture is implemented:
+
+```
+┌──��───────────────────────────────────────────┐     120s Cron Daemon /      ┌──────────────────────────────────────────────┐
+│  High-Speed Ext4 Container Disk              │     Shutdown Backup Loop    │  Persistent Volume Mount                      │
+│  (/root/.omniroute/storage.sqlite)           ├────────────────────────────>│  (/data/omniroute/storage.sqlite)            │
+│  - Active runtime POSIX file locks (fcntl)   │                             │  - Persistent across Space rebuilds & sleep   │
+│  - Active WAL (-wal) & SHM (-shm) sidecars   │<────────────────────────────┤  - Rotating backups (/data/omniroute/backups) │
+└──────────────────────────────────────────────┘     Boot Restoration Sync   └──────────────────────────────────────────────┘
+```
 
-## 4. Port & Path Routing Matrix
-
-| Public Request Path | Target Upstream Port | Target Service | Function |
-| :--- | :--- | :--- | :--- |
-| `/` | `8098` | Open WebUI | Main Root Web UI |
-| `/dashboard/*` | `20128` | OmniRoute Dashboard | Management Panel |
-| `/v1/*` | `20129` | OmniRoute API Server | Dedicated OpenAI API |
-| `/v1beta/*` | `20129` | OmniRoute API Server | Dedicated Gemini API |
-| `/api/providers/*` | `20128` | OmniRoute Dashboard | Provider API |
-| `/api/oauth/*` | `20128` | OmniRoute Dashboard | OAuth API |
-| `/callback` | `20128` | OmniRoute Dashboard | OAuth Callback Handler |
-| `/live-ws/*` | `20132` | OmniRoute WebSocket | Live Monitoring WS |
-| `/jellyfin/*` | `8096` | Jellyfin Media Server | Media Streaming |
-| `/tg-stream/*` | `8080` | TG Stream Proxy | Telegram Direct Streamer |
+### Database Lifecycle & Safety Guarantees:
+1. **Boot Initialization**:
+   - `entrypoint.sh` checks for persistent snapshot at `/data/omniroute/storage.sqlite`.
+   - Validates integrity using `sqlite3 "PRAGMA quick_check;"`.
+   - Restores clean snapshot into `/root/.omniroute/storage.sqlite`.
+2. **Runtime Backup Loop**:
+   - Every 120 seconds, a background daemon executes `sync_omniroute_db()`.
+   - Issues `PRAGMA wal_checkpoint(PASSIVE);` and `sqlite3 .backup`.
+   - Syncs `-wal` and `-shm` sidecars to preserve uncommitted transactions.
+   - Rotates up to 5 rolling backups in `/data/omniroute/backups/storage-YYYYMMDD-HHMM.sqlite`.
+3. **Shutdown Hook**:
+   - Shell traps (`trap sync_omniroute_db EXIT INT TERM`) flush runtime state before container termination.
 
 ---
 
-## 5. Storage & Persistence Model
+## 4. Encryption & Security Model
 
-- **Active Execution (`/root/.omniroute/storage.sqlite`)**: Runs on local Ext4 container disk to support `better-sqlite3` POSIX file locking.
-- **Safe SQLite Backup (`/data/omniroute/storage.sqlite`)**: Background daemon uses `sqlite3 .backup` API every 5 minutes and on shutdown to write consistent snapshots to the HF FUSE mount.
+- **AES-256-GCM Encryption**: All provider credentials (API keys, OAuth access tokens, refresh tokens) are encrypted at rest with `STORAGE_ENCRYPTION_KEY`.
+- **Secrets Fallback Engine**: If secrets are not passed via Hugging Face Space Secrets during local development, safe default fallbacks prevent container crash:
+  - `STORAGE_ENCRYPTION_KEY`
+  - `JWT_SECRET`
+  - `API_KEY_SECRET`
+  - `INITIAL_PASSWORD`
+- **Path Traversal Gate**: The gateway inspects all requested paths and rejects directory traversal patterns (`..`, `.env`, `.sqlite`, `.git`) with HTTP 403.
 
 ---
 
-## 6. Repository File Structure
+## 5. Process Lifecycle & Self-Healing Supervisor
+
+The container supervisor (`entrypoint.sh`) maintains 24/7 uptime for all background daemons:
 
 ```
-.
-├── Dockerfile              # Multi-stage Docker image with Redis & pre-cached models
-├── ARCHITECTURE.md         # Architecture specification (this document)
-├── README.md               # User quickstart guide
-├── entrypoint.sh           # Concurrent service startup, Redis daemon & SQLite backup
-├── fix_omniroute.py        # Migration version collision auto-repair script
-├── nginx.conf              # Nginx configuration reference
-├── proxy.py                # FastAPI gateway entrypoint script
-├── tg_streamer.py          # Pyrogram Telegram 5G stream proxy
-└── gateway/                # FastAPI Modular Router Package
-    ├── __init__.py
-    ├── main.py             # App router aggregator
-    ├── utils.py            # Async HTTP & WebSocket proxy engine
-    ├── openwebui.py        # Open WebUI path routing
-    ├── omniroute.py        # OmniRoute API & asset routing
-    ├── jellyfin.py         # Jellyfin path routing
-    └── tg_stream.py        # Telegram proxy routing
+                        [PID 1 Process Supervisor Loop]
+                                       │ (every 5s)
+         ┌─────────────────────────────┼─────────────────────────────┐
+         ▼                             ▼                             ▼
+ [Kill -0 $FASTAPI_PID]        [Kill -0 $NGINX_PID]        [Kill -0 $OMNIROUTE_PID]
+         │                             │                             │
+    (Dead? Restart)               (Dead? Restart)               (Dead? Restart)
+ python3 -m uvicorn proxy:app    nginx -g 'daemon off;'      cd /omniroute && node server.js
 ```
+
+- **Fast Gateway Readiness**: FastAPI (`:8000`) and Nginx (`:4096`) start within **300ms**, allowing Hugging Face to report `RUNNING` status instantly.
+- **Asynchronous Heavy Boot**: OmniRoute Next.js server, Open WebUI, Jellyfin, and TG Streamer initialize in parallel background tasks without blocking public ingress.

DEPLOYMENT_GUIDE.md

@@ -0,0 +1,122 @@
+# OpenCode Space — Production Deployment & Operations Manual
+
+This guide provides step-by-step instructions for deploying, updating, scaling, and maintaining the **`Jishnupg/Opencode-Cli`** multi-service environment on Hugging Face Spaces or standard Docker / Kubernetes environments.
+
+---
+
+## 1. Prerequisites & Repository Remotes Setup
+
+### Primary Repository Endpoints:
+- **GitHub Source Repo**: `https://github.com/JishnuPG-tech/Project.git`
+- **Hugging Face Space**: `https://huggingface.co/spaces/Jishnupg/Opencode-Cli`
+
+### Git Remote Configuration:
+To ensure updates are pushed cleanly to both GitHub and Hugging Face Space:
+
+```bash
+# Add Hugging Face Space remote
+git remote add hf https://huggingface.co/spaces/Jishnupg/Opencode-Cli
+
+# Verify remotes list
+git remote -v
+# Output should show:
+# hf     https://huggingface.co/spaces/Jishnupg/Opencode-Cli (fetch)
+# hf     https://huggingface.co/spaces/Jishnupg/Opencode-Cli (push)
+# origin https://github.com/JishnuPG-tech/Project.git (fetch)
+# origin https://github.com/JishnuPG-tech/Project.git (push)
+```
+
+---
+
+## 2. Hugging Face Space Configuration & Secrets
+
+In your Hugging Face Space settings (**Settings > Secrets**), configure the following environment secrets:
+
+| Secret Key | Description | Example / Recommended Value |
+| :--- | :--- | :--- |
+| `STORAGE_ENCRYPTION_KEY` | Master AES-256-GCM key for encrypting provider credentials | 32-character random string |
+| `JWT_SECRET` | Secret key for JWT token signing across services | 32-character random string |
+| `API_KEY_SECRET` | Secret key for OmniRoute API key authorization | 32-character random string |
+| `INITIAL_PASSWORD` | Default admin password for OmniRoute UI login | User-defined password |
+
+> [!NOTE]
+> If any secret is omitted during local Docker testing, `entrypoint.sh` automatically supplies safe default fallback values to prevent container crashes.
+
+---
+
+## 3. Build & Deployment Commands
+
+### Standard Deployment Workflow:
+
+```bash
+# 1. Stage all modified code changes
+git add .
+
+# 2. Commit with conventional commit message
+git commit -m "feat(omniroute): update gateway routing and provider persistence"
+
+# 3. Push to GitHub repository
+git push origin main
+
+# 4. Push to Hugging Face Space repository (triggers automatic Docker build)
+git push hf main
+```
+
+---
+
+## 4. Local Testing with Docker
+
+To build and run the entire multi-service container locally:
+
+```bash
+# Build the Docker image
+docker build -t opencode-cli:latest .
+
+# Run the container mapping public ingress port 4096
+docker run -d \
+  -p 4096:4096 \
+  -e STORAGE_ENCRYPTION_KEY="my_secure_encryption_key_32bytes" \
+  -e JWT_SECRET="my_secure_jwt_secret_key_32bytes" \
+  -e API_KEY_SECRET="my_secure_api_key_secret_32bytes" \
+  -e INITIAL_PASSWORD="admin_password_123" \
+  --name opencode-space \
+  opencode-cli:latest
+
+# Check container logs
+docker logs -f opencode-space
+```
+
+### Access Local Endpoints:
+- **Unified Gateway**: `http://localhost:4096/`
+- **OmniRoute Dashboard**: `http://localhost:4096/dashboard`
+- **OpenAI API Base URL**: `http://localhost:4096/v1`
+- **Jellyfin Media**: `http://localhost:4096/jellyfin`
+- **TG Streamer**: `http://localhost:4096/tg-stream`
+
+---
+
+## 5. Maintenance & Troubleshooting
+
+### Issue 1: `SyntaxError: Unexpected token '<'` in Frontend
+- **Symptom**: Dashboard page shows "0 connections" or console logs `<JSON.parse error>`.
+- **Cause**: Gateway routed an `/api/` request to Open WebUI instead of OmniRoute.
+- **Fix**: Verify `gateway/main.py` has Referer-based routing enabled:
+  ```python
+  is_omniroute_referer = "/dashboard" in referer or "/omniroute" in referer or "/providers" in referer
+  ```
+
+### Issue 2: Duplicate Process Restarts (`FastAPI Gateway process died!`)
+- **Symptom**: Container logs show repeated restart messages every 5s.
+- **Cause**: Variable name mismatch between start command (`FASTAPI_PID=$!`) and supervisor check (`kill -0 $FASTAPI_PID`).
+- **Fix**: Verify `FASTAPI_PID` is correctly set and checked in `entrypoint.sh`.
+
+### Issue 3: Database Snapshot Restoration Check
+- **Symptom**: Provider keys disappear after space rebuild.
+- **Verification Command**:
+  ```bash
+  # Check if persistent volume snapshot exists
+  ls -lh /data/omniroute/storage.sqlite
+  
+  # Manually trigger snapshot sync
+  python3 -c "import sqlite3; conn = sqlite3.connect('/data/omniroute/storage.sqlite'); print(conn.execute('PRAGMA quick_check;').fetchall())"
+  ```

OMNIROUTE_INTEGRATION_PLAN.md

@@ -0,0 +1,93 @@
+# OmniRoute AI Gateway — Feature Specification & Integration Roadmap
+
+This document outlines the detailed feature architecture of **OmniRoute** integrated within the `Jishnupg/Opencode-Cli` project, detailing the token compression pipeline, 290+ AI providers, CLI compatibility modes, and API endpoints.
+
+---
+
+## 1. Core Engine Subsystems
+
+### A. Dual Token Compression Pipeline (RTK + Caveman)
+OmniRoute features an inline token optimization engine that reduces prompt length by **15% to 95%** prior to forwarding requests to upstream LLM providers:
+
+```
+  [Client Prompt Payload]
+             │
+   [RTK (Recursive Token Killer)]  ──> Strips system prompt boilerplate, repeated context, & tool output noise
+             │
+   [Caveman Compression Engine]   ──> Compresses JSON schemas & system instructions into dense structural format
+             │
+  [Compressed API Request]       ──> Sent to Target Provider (e.g. Anthropic, OpenAI, DeepSeek, Kimi)
+```
+
+### B. Quota-Share Auto-Fallback Cascade
+OmniRoute maintains real-time rate limit and quota tracking across 290+ providers and 500+ models.
+
+```
+                  [Client LLM Request]
+                           │
+                  [Provider Choice: Primary]
+                           │
+                 (Rate Limit 429 / 402?)
+                /                       \
+           (No: 200 OK)              (Yes: 429 Error)
+                │                         │
+     [Return Stream Response]    [Auto-Fallback Cascade]
+                                          │
+                                 [Select Next Key / Provider]
+                                          │
+                                 [Execute Request Seamlessly]
+```
+
+---
+
+## 2. Supported AI Providers (290+ Integrations)
+
+OmniRoute supports both direct API keys and OAuth single sign-on across top AI providers:
+
+### Major Supported OAuth & API Providers:
+- **Anthropic / Claude Code**: Claude 3.7 Sonnet, Claude 3.5 Haiku, Opus.
+- **OpenAI**: GPT-4o, GPT-4o-mini, o1, o3-mini.
+- **Google Antigravity & Gemini**: Gemini 2.5 Pro, Gemini 2.0 Flash, Flash-Lite.
+- **Moonshot / Kimi Coding**: Kimi K1.5, Kimi CLI.
+- **DeepSeek**: DeepSeek R1, DeepSeek V3.
+- **Amazon Q / Bedrock**: Claude 3.5 Sonnet Bedrock endpoints.
+- **GitHub Copilot / Copilot Enterprise**: Copilot Chat & Editor completions.
+- **Cline / ClinePass**: Open-source coding agent integrations.
+- **Cerebras & Groq**: Ultra-low latency Llama-3 70B inference.
+- **Mistral, Cohere, Together, Replicate, Fireworks, OpenRouter**.
+
+---
+
+## 3. CLI Compatibility Layer (`CLI_COMPAT_*`)
+
+To allow terminal coding assistants and IDE extensions to connect directly to OmniRoute without changing client code, OmniRoute emulates provider-specific CLI endpoints when environment flags are active:
+
+| Compatibility Flag | Emulated Client Tool | Endpoint Behavior |
+| :--- | :--- | :--- |
+| `CLI_COMPAT_CLAUDE=1` | Anthropic Claude Code CLI | Translates `/v1/messages` requests |
+| `CLI_COMPAT_ANTIGRAVITY=1` | Google Antigravity / Gemini CLI | Emulates Antigravity authentication & streaming |
+| `CLI_COMPAT_CURSOR=1` | Cursor IDE | Translates Cursor autocomplete & chat headers |
+| `CLI_COMPAT_GITHUB=1` | GitHub Copilot CLI / VSCode | Emulates Copilot token exchange |
+| `CLI_COMPAT_KIMI_CODING=1` | Kimi Coding Assistant | Emulates Kimi OAuth handshake |
+| `CLI_COMPAT_CODEX=1` | OpenAI Codex / Aider | Translates legacy code completion endpoints |
+
+---
+
+## 4. API Endpoints Reference
+
+### OpenAI Compatible API (`/v1`)
+- **Base URL**: `https://jishnupg-opencode-cli.hf.space/v1` or `/api/v1`
+- **Endpoints**:
+  - `POST /v1/chat/completions`: Streaming and non-streaming chat completions.
+  - `GET /v1/models`: List all available and active models across connected providers.
+  - `POST /v1/embeddings`: Vector embedding generation.
+
+### Gemini Compatible API (`/v1beta`)
+- **Base URL**: `https://jishnupg-opencode-cli.hf.space/v1beta` or `/api/v1beta`
+- **Endpoints**:
+  - `POST /v1beta/models/{model}:generateContent`: Gemini content generation.
+  - `POST /v1beta/models/{model}:streamGenerateContent`: Gemini streaming content generation.
+
+### Live Telemetry WebSocket (`/live-ws`)
+- **Base URL**: `wss://jishnupg-opencode-cli.hf.space/live-ws`
+- **Function**: Real-time token throughput metrics, active request visualization, and provider fallback telemetry.