docs(combo): sync all combo/routing-strategy docs to current state + document test coverage (#5185)

Integrated into release/v3.8.39. Combo/routing-strategy docs sync; docs-only.

README.md

@@ -295,7 +295,7 @@ Result: 4 layers of fallback = zero downtime
 - **⚖️ Quota-Share routing** — a dedicated combo strategy that spreads load across accounts by _available quota_: Deficit-Round-Robin scheduling, per-connection `max_concurrent` with cooldown-wait queueing, multi-window usage buckets (5h / 7d / per-model), per-(key,model) caps, session stickiness for prompt-cache integrity, and proactive saturation from upstream token-usage headers. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)
 - **🤖 One-command CLI/agent setup** — a dedicated `setup-*` command configures each coding tool to route through OmniRoute (Claude Code, Codex, Cline, Continue, Cursor, Roo Code, Kilo Code, Crush, Goose, Qwen Code, Aider, OpenCode, Gemini CLI); `omniroute launch` / `omniroute launch-codex` are zero-config launchers. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
 - **🛰️ Remote mode** — drive a remote OmniRoute from any machine with scoped access tokens (`omniroute connect` / `omniroute contexts` / `omniroute tokens`). → [Remote Mode](docs/guides/REMOTE-MODE.md)
-- **🧭 Smarter auto-routing** — OpenRouter-style `auto/<category>:<tier>` combos (e.g. `auto/coding:fast`, `auto/reasoning:pro`), a **Fusion** strategy (16th — fan out to a panel of models in parallel, then synthesize via a judge), **task-aware routing** (best-fit connection per task type), per-request `X-Route-Model` override, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, and `web_search`-aware routing. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
+- **🧭 Smarter auto-routing** — OpenRouter-style `auto/<category>:<tier>` combos (e.g. `auto/coding:fast`, `auto/reasoning:pro`), a **Fusion** strategy (fan out to a panel of models in parallel, then synthesize via a judge), **task-aware routing** (best-fit connection per task type), per-request `X-Route-Model` override, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, and `web_search`-aware routing. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
 - **🗜️ Pluggable compression** — an async pipeline of **9 composable engines** with Compression Studios, an LLMLingua-2 ONNX engine and a heuristic/SLM two-tier **Ultra**, RTK, delegated Anthropic Context Editing, **Output Styles** (output-axis steering: terse-prose / less-code / terse-CJK), an **adaptive context-budget dial** (escalate only as far as needed to fit the context window), per-request `x-omniroute-compression` control, an opt-in offline eval harness, one-click **Headroom** proxy lifecycle management from the dashboard (Docker sidecar supported), a synthetic **compression playground** (Play lanes + A/B Compare with USD-capped fidelity verdicts), an opt-in **per-step fidelity gate** that rejects a lossy engine before it degrades the prompt, and a unified panel with named profiles + an active-profile selector. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
 - **🕵️ Transparent MITM decrypt (TPROXY)** — capture & translate traffic from CLIs that ignore proxy env vars, with a per-SNI certificate authority and a trust-store installer. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md)
 - **💸 Cost telemetry everywhere** — `X-OmniRoute-*` cost/usage headers on every endpoint (including media), a non-token cost engine, a cache-HIT `X-OmniRoute-Cost-Saved` header, and per-key USD spend quotas. → [API Reference](docs/reference/API_REFERENCE.md)

docs/routing/AUTO-COMBO.md

@@ -569,6 +569,36 @@ To strongly favor Tier 1 (subscription), increase `tierPriority` weight:
 
 See `docs/marketing/TIERS.md` for tier definitions and provider classification.
 
+## Testing & Coverage
+
+### Deterministic routing-decision matrix (`npm run test:combo:matrix`)
+
+`tests/integration/combo-matrix/*.test.ts` proves the routing **decision** of all 17
+public strategies end-to-end through the real combo pipeline with a mocked upstream.
+Coverage includes:
+
+- All 17 `ROUTING_STRATEGY_VALUES` strategies (ordered, weighted, cost, context, fusion, …).
+- `quota-share` (internal) end-to-end: DRR fairness + saturation deprioritization via the
+  real `selectQuotaShareTarget` seam (`registerQuotaFetcher` / `setLKGP` /
+  `__setHeadroomSaturationFetcherForTests`).
+- `context-relay` universal-handoff coverage across every target count.
+
+This suite runs in CI (`test:integration` job) with `--test-concurrency=1` and
+`--test-force-exit` so it is deterministic and does not require live credentials.
+
+### Gated live smoke (NOT in CI — real providers)
+
+| Command | What it does |
+| :--- | :--- |
+| `npm run test:combo:live` | In-process real routing with `RUN_COMBO_LIVE=1`; snapshots a live OmniRoute DB |
+| `npm run test:combo:live:vps` | HTTP calls against a live OmniRoute server (set `COMBO_LIVE_BASE_URL`) |
+| `npm run test:combo:live:vps:failover` | Same, with deliberate failover scenarios |
+
+These smoke tests exercise the real wire path (combo → provider → completion). They are
+intentionally excluded from CI because they require live credentials and VPS access.
+
+---
+
 ## Files
 
 | File                                                      | Purpose                                                                    |

docs/routing/QUOTA_SHARE.md

@@ -334,6 +334,29 @@ re-migration.
 
 ---
 
+## Internal Strategy Classification
+
+`quota-share` is an **internal-only** routing strategy (`INTERNAL_ROUTING_STRATEGY_VALUES` in
+`src/shared/constants/routingStrategies.ts`). It is used exclusively by system-minted
+`qtSd/` pool combos and is deliberately excluded from `ROUTING_STRATEGY_VALUES` so it never
+appears as a user-selectable option in the UI or API.
+
+---
+
+## Test Coverage
+
+Two layers of automated coverage ship with the quota-share engine:
+
+| Suite | Command | What it covers |
+| :--- | :--- | :--- |
+| Unit (29 tests) | `node --import tsx/esm --test tests/unit/quota-share-strategy.test.ts` | DRR scheduler, saturation gating, concurrency caps, fairShare math, backlog queueing |
+| Integration matrix | `npm run test:combo:matrix` | End-to-end routing decision through the real combo pipeline; DRR fairness + saturation deprioritization via live seams (`registerQuotaFetcher`, `setLKGP`, `__setHeadroomSaturationFetcherForTests`) |
+
+The integration matrix runs in CI alongside the other 17 public strategies. The unit suite
+can be run standalone.
+
+---
+
 ## DB Schema Summary
 
 Three tables added by migrations `073–075`: