From c69dce259fe69fefde06ac7d6de5079484d41bc5 Mon Sep 17 00:00:00 2001
From: Ronaldo Davi <ronaldodavi@gmail.com>
Date: Thu, 8 Oct 2026 02:01:51 -0300
Subject: [PATCH] docs(guides): add common provider combinations section
 (#13735) (#15195)

Validated in a combined board with the other PRs of this wave on release/v3.8.52: the PR's own tests pass; typecheck:core, open-sse typecheck, api-typecheck, complexity, changelog-integrity, env-doc-sync, test-discovery, vitest-exclusions, error-helper, test-masking, lockfile, deps, gate-manifest, cli-i18n and i18n coverage green. Any file-size ceiling or stryker registration this wave needs lands in the wave's follow-up PR. Thank you for the contribution!
---
 docs/guides/USER_GUIDE.md | 59 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/guides/USER_GUIDE.md b/docs/guides/USER_GUIDE.md
index 5fe348a0fd..2587351e22 100644
--- a/docs/guides/USER_GUIDE.md
+++ b/docs/guides/USER_GUIDE.md
@@ -911,6 +911,65 @@ Chain: production-fallback
 
 ---
 
+### Common Provider Combinations & Routing Patterns
+
+Here are example patterns for combining multiple providers and routing between them in OmniRoute:
+
+#### 1. Coding Agent Combo: High-End Reasoning with Cost/Speed Fallback
+
+Ideal for coding agents (OpenCode, Claude Code, Cursor, Cline). Routes initially to frontier reasoning models, falling back to fast coding models on quota exhaustion or errors.
+
+- **Dashboard**: Combos → New Combo → Name: `agent-coding` → Strategy: `Priority`
+- **Models**:
+  1. `claude/claude-sonnet-4-6` (Primary coding agent)
+  2. `openai/gpt-4o` (Secondary high-capacity fallback)
+  3. `deepseek/deepseek-v4-flash` (High-efficiency, cost-effective fallback)
+
+```bash
+# Example via API
+curl -X POST http://localhost:20128/api/combos \
+  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "agent-coding",
+    "strategy": "priority",
+    "models": [
+      { "model": "claude/claude-sonnet-4-6" },
+      { "model": "openai/gpt-4o" },
+      { "model": "deepseek/deepseek-v4-flash" }
+    ]
+  }'
+```
+
+#### 2. Free-Tier Auto Failover Combo
+
+Chains multiple free-tier and keyless providers to maximize uptime without API costs.
+
+- **Strategy**: `Least Used` or `Round Robin` (distributes load across quotas)
+- **Models**:
+  1. `groq/llama-3.3-70b-versatile`
+  2. `gemini/gemini-2.5-flash`
+  3. `cerebras/gpt-oss-120b`
+
+```bash
+# Example via CLI
+omniroute combo create free-stack \
+  --models "groq/llama-3.3-70b-versatile,gemini/gemini-2.5-flash,cerebras/gpt-oss-120b" \
+  --strategy round-robin
+```
+
+#### 3. Multimodal / Vision & Text Pipeline
+
+Pairing specialized vision models with high-speed text generation for workflows involving image understanding and code generation.
+
+- **Pattern**: A `Priority` combo that lists vision-capable models first and a high-throughput text/code model last.
+- **Models**:
+  1. `gemini/gemini-2.5-pro` (Strong image/multimodal comprehension)
+  2. `openai/gpt-4o` (Balanced vision and tool usage)
+  3. `deepseek/deepseek-v4-flash` (Text/code generation)
+
+---
+
 ### Resilience & Circuit Breakers
 
 Configure via **Dashboard → Settings → Resilience**.