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:.