[DOCS] Inconsistency between `--fallback-model` flag restrictions and "Max User" fallback behavior

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/cli-reference - https://code.claude.com/docs/en/costs - https://code.claude.com/docs/en/model-config

Section/Topic

The usage requirements for automatic model fallback, specifically distinguishing between the --fallback-model CLI flag and the built-in fallback behavior for Max/Pro subscribers.

Current Documentation

From CLI Reference:

--fallback-model | Enable automatic fallback to specified model when default model is overloaded (print mode only)

From Manage costs effectively:

For certain Max users, Claude Code will automatically fall back to Sonnet if you hit a usage threshold with Opus.

From Model configuration (default model setting):

For certain Max users, Claude Code will automatically fall back to Sonnet if you hit a usage threshold with Opus.

What's Wrong or Missing?

There is a contradiction regarding whether model fallback is restricted to "print mode" (non-interactive).

1. The CLI Reference explicitly labels the --fallback-model flag as "(print mode only)."
2. The Costs and Model Configuration pages describe a fallback from Opus to Sonnet for Max users as a general feature, implying it works in standard interactive sessions.

It is unclear if the "Max user" fallback is a separate internal mechanism that does work in interactive mode, or if all forms of model fallback are strictly limited to print mode. If the latter is true, interactive users hitting a threshold or encountering an overloaded model might be confused when an automatic fallback does not occur.

Suggested Improvement

Clarify the scope of fallback behavior in the Costs and Model Config sections.

Suggested addition to Manage costs effectively:

"For certain Max users, Claude Code will automatically fall back to Sonnet if you hit a usage threshold with Opus. Note: In interactive mode, this fallback occurs [automatically/only after a prompt]; for automated scripts using the CLI, use the --fallback-model flag (available in print mode only)."

Alternatively, if the Max user fallback only works in print mode, the Costs section should be updated to say:

"For certain Max users running in print mode (-p), Claude Code will automatically fall back to Sonnet..."

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation: CLI Reference
• Related documentation: Model Configuration