Fallback provider docs show stale/incorrect config paths for fallback_providers

[WadydX]

Bug Description

The fallback provider docs describe stale or incorrect config paths for fallback configuration.

The docs currently give two conflicting shapes:

• fallback_model: as the documented config section in the environment variables reference;
• fallback_providers: "under model:" in the CLI reference.

The code writes and reads fallback provider chains from top-level fallback_providers, with top-level fallback_model only treated as a legacy format.

Users hand-editing config from the docs can place fallback settings under the wrong key and get confusing failover behavior.

Inspected against main commit af6f9bc2a12682b06fb3632acf5a9cbf01e74a85.

Steps to Reproduce

Static docs/code mismatch:

1. Open the environment variables reference fallback section.
2. Open the CLI reference fallback command section.
3. Compare both against hermes_cli/fallback_cmd.py and gateway/run.py.

Expected Behavior

Docs should consistently document the current config shape:

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

If fallback_model remains supported, it should be described as legacy/backward-compatible rather than the primary config shape.

Actual Behavior

Docs currently show or describe stale/conflicting paths:

• fallback_model: as the section to add;
• fallback_providers: under model:;
• code actually uses top-level fallback_providers.

Evidence

• website/docs/reference/environment-variables.md:516-526
  • says to add a fallback_model section.
• website/docs/reference/cli-commands.md:1066
  • says changes persist to fallback_providers: under model: in config.yaml.
• hermes_cli/fallback_cmd.py:15-17
  • documents storage as top-level fallback_providers.
• hermes_cli/fallback_cmd.py:49-54
  • writes config["fallback_providers"] = chain and removes legacy fallback_model.
• gateway/run.py:2046-2060
  • runtime reads top-level fallback_providers or top-level legacy fallback_model.

Affected Component

Documentation / Configuration

Environment

Static analysis of current main; no local environment-specific behavior required.

Prior Art Checked

I searched existing issues and PRs for:

• fallback_providers under model
• fallback_model environment-variables.md
• fallback providers config.yaml docs

I found related fallback/provider issues, but no exact existing issue for this docs/config-path mismatch.

Root Cause Analysis

The fallback provider implementation migrated to a top-level fallback_providers list while some reference docs still describe the legacy single fallback key or an incorrect nested location.

Proposed Fix

Update the relevant reference docs to:

• show top-level fallback_providers as the current config shape;
• mention top-level fallback_model only as legacy/backward-compatible behavior, if desired;
• remove the wording that says fallback_providers is under model:.

[0xsir0000]

Submitted PR #20516.

Approach: Rewrote docs/user-guide/features/fallback-providers.md to lead with fallback_providers: (top-level list) — the shape that hermes_cli/fallback_cmd.py writes and that cli.py:2224 reads first. Updated the misleading "persists under model.fallback_providers" intro line, fixed the nine YAML examples (including custom-endpoint, auxiliary cross-reference, and summary-table rows), added a worked multi-fallback example, and flipped the fallback_model vs fallback_providers admonition to put the current shape first.

Also touched configuration.md (auxiliary cross-reference + two "main"-only-valid-in-X notes) so it stops pointing readers at the legacy key.

The CLI reference (reference/cli-commands.md:1110) and env-vars reference (reference/environment-variables.md:523-531) were already correct — this PR aligns the user-guide page with them.

[WadydX]

Rechecked on current main (64145a199).

Status looks partially improved, not fully resolved:

• The incorrect "under model:" wording appears fixed.
• However, website/docs/user-guide/features/fallback-providers.md still repeatedly presents fallback_model examples as the direct YAML-edit path, while runtime/CLI primary behavior is top-level fallback_providers.

Given the issue scope (docs showing stale/incorrect config paths), I'd keep this open until the user-guide examples are fully aligned around fallback_providers as primary and fallback_model as explicitly legacy-only.