Skip to content

docs: document combo invocation by exact model name (#7992) - #10779

Merged
diegosouzapw merged 1 commit into
diegosouzapw:release/v3.8.50from
maxmad64bis:docs/7992-combo-invocation-docs
Aug 20, 2026
Merged

diegosouzapw merged 1 commit into
diegosouzapw:release/v3.8.50from
maxmad64bis:docs/7992-combo-invocation-docs

Conversation

@maxmad64bis

@maxmad64bis maxmad64bis commented Aug 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Persisted combos (Settings → Combos) are only used when the client sends their exact name in the model field — auto/auto/* is a separate zero-config router that does not consult persisted combos. The confusion produced two issues (#7992, #7111): reporters' clients kept sending model: "auto" while their combos were never reached, and openrouter/auto 402s were a real paid OpenRouter product, not an alias.

This PR documents the invocation contract on three surfaces (no runtime change):

  • Combos page guide (Getting Started with Combos): new info block + 4 i18n keys (usageGuideInvoke*)
  • docs/routing/AUTO-COMBO.md: new section Calling a Custom Combo From a Client
  • docs/getting-started/AUTO-COMBO-GUIDE.md: FAQ Can I force a specific provider? now mentions the exact-name requirement
  • changelog fragment (changelog.d/maintenance/10779-combo-invocation-docs.md)

Related Issues

Validation

Choose the change type and focused loop from the Contribution Golden Path. The full unit suite, Vitest, the 60% coverage gate, and the production build all run in CI on this PR (#8329):

  • Change type: UI / i18n / docs
  • Focused tests and category gates from the golden path: check:docs-sync, check:docs-counts, check:doc-links, check:fabricated-docs, i18n:check-ui-coverage, check:changelog-integrity — PASS locally
  • npm run lint — PASS locally
  • Reconciled with the current active release base (fork synced to upstream tip 3d7ed7aa8, branch rebased, focused checks rerun afterward)
  • Production-code changes include a new or updated automated test in this PR: tests/unit/combo-guide-invocation-keys.test.ts (2 tests)
  • SonarQube is temporarily opt-in while the private project has no quota; it is not a PR gate.

Known base-red: check:env-doc-sync fails on the base tip itself (verified on a clean base worktree). ⚠️ base-red inherited: #9985

Tests Added Or Updated

  • tests/unit/combo-guide-invocation-keys.test.ts — new: asserts the 4 usageGuideInvoke* i18n keys exist in en.json with the expected copy, and that ComboUsageGuide (page.tsx) references each key via getI18nOrFallback. Run: node --import tsx/esm --test tests/unit/combo-guide-invocation-keys.test.ts → 2/2 PASS.

Coverage Notes

  • The only production-code change is a static copy block in src/app/(dashboard)/dashboard/combos/page.tsx (4 getI18nOrFallback calls) + 4 new en.json keys (i18n files excluded from the test-policy gate by design). The new test covers the catalog keys and their page references; no covered branches are removed, so no coverage movement is expected.

Reviewer Notes

  • No runtime behavior change — getComboForModel() resolution order is untouched.
  • Local check:dashboard-typecheck was inconclusive in the dev environment (stale node_modules before the fork sync; process died after npm install); the gate runs authoritatively in CI.
  • lint:md reports only pre-existing errors (CHANGELOG.md, AUTO-COMBO.md lines 7/10, AUTO-COMBO-GUIDE.md lines 7/50) — none on the added lines.
  • The grand-public FAQ line and the docs section deliberately reuse the same wording as the UI note so all three surfaces stay consistent.
  • UI render not screenshot-tested: the added block is static copy following the exact patterns of the existing guide blocks (same i18n helper, same design-system classes), covered by lint + the new unit test.

@maxmad64bis
maxmad64bis force-pushed the docs/7992-combo-invocation-docs branch from 94376d5 to ab5f136 Compare August 19, 2026 21:59
Persisted combos (Settings → Combos) are only used when the client sends
their exact name in the model field; auto/auto/* is a separate zero-config
router that does not consult persisted combos, and openrouter/auto is a
real paid OpenRouter product (Auto Best Available), not an alias.

Three surfaces, no runtime change:
- Combos page guide: info block + 4 i18n keys (usageGuideInvoke*)
- docs/routing/AUTO-COMBO.md: 'Calling a Custom Combo From a Client' section
- docs/getting-started/AUTO-COMBO-GUIDE.md: FAQ exact-name requirement
- changelog fragment + unit test (tests/unit/combo-guide-invocation-keys.test.ts)
@maxmad64bis
maxmad64bis force-pushed the docs/7992-combo-invocation-docs branch from ab5f136 to 5124d91 Compare August 19, 2026 22:02
@diegosouzapw
diegosouzapw merged commit 121023e into diegosouzapw:release/v3.8.50 Aug 20, 2026
5 checks passed
@maxmad64bis
maxmad64bis deleted the docs/7992-combo-invocation-docs branch September 24, 2026 21:10
muhamadgalihsaputra pushed a commit to niyatna/NiyatnaRoute that referenced this pull request Sep 27, 2026
… (diegosouzapw#10779)

Merged via merge-train (release/v3.8.50, batch1 2026-08-20) — static gates (typecheck/file-size/complexity/cognitive/changelog) green on the combined tree; test:unit reds observed in the boarded run were verified pre-existing on the pure release tip (unrelated flake), not caused by this PR. Thanks for the contribution!
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(backend): combos not used — enabled providers not seen by the router

2 participants