[DOCS] Model configuration page missing documentation of automatic fallback notification behavior

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/model-config

Section/Topic

"default model setting" section

Current Documentation

The model-config page has one sentence about automatic fallback:

"Claude Code may automatically fall back to Sonnet if you hit a usage threshold with Opus."

That is the entirety of the fallback documentation. There is no explanation of:

• When the notification appears (previously only in verbose mode)
• What the notification looks like
• What triggers the fallback (usage threshold only, or other conditions?)

What's Wrong or Missing?

Version 2.1.76 changed fallback notification behavior:

"Improved model fallback notifications — now always visible instead of hidden behind verbose mode, with human-friendly model names"

This is user-facing behavior that users need to understand:

A. Notification visibility change not documented

Previously, model fallback notifications were only visible in verbose mode (Ctrl+O or --verbose). After this change they are always shown. Users who have never seen a fallback notification (because they don't use verbose mode) may be surprised when they start appearing, and need documentation to understand what they mean and how to respond.

B. Fallback conditions not explained

The current one-sentence mention says "if you hit a usage threshold with Opus" but does not explain: what the threshold is, whether there are other conditions that trigger fallback, how long the fallback lasts, or whether there is a way to check current fallback status.

C. Human-friendly model names not explained

The changelog notes fallback now uses "human-friendly model names." Users need to know what these names look like so they can recognize a fallback notification when it appears.

Suggested Improvement

Expand the fallback section in model-config.md under the "default model setting" heading:

Automatic model fallback Claude Code may automatically fall back from Opus to Sonnet when you approach your Opus usage limit. When a fallback occurs, a notification appears in your session showing the model Claude switched to. These notifications are always visible (you do not need verbose mode to see them). If you see a fallback notification, you can: - Continue working with the fallback model - Run /model to switch back to Opus manually (your usage limit permitting) - Run /usage to check your current plan limits and rate limit status

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/model-config | "default model setting" — one vague sentence on fallback; no notification behavior |
| https://code.claude.com/docs/en/troubleshooting | No entry explaining automatic model fallback |

Total scope: 2 pages affected

Source: Changelog v2.1.76

Improved model fallback notifications — now always visible instead of hidden behind verbose mode, with human-friendly model names