[DOCS] Model configuration page missing model removal and automatic migration behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Model aliases" section and "Pin models for third-party deployments" section

Current Documentation

The model aliases table lists the current models (Opus 4.6, Sonnet 4.6, Haiku) and states:

"Aliases always point to the latest version. To pin to a specific version, use the full model name (for example, claude-opus-4-6) or set the corresponding environment variable like ANTHROPIC_DEFAULT_OPUS_MODEL."

The "Pin models for third-party deployments" section covers pinning for Bedrock, Vertex AI, and Foundry deployments, and warns that alias resolution can change when new models ship. However, it does not address what happens when a pinned model is removed entirely.

What's Wrong or Missing?

A. No model removal or migration behavior documented

Changelog v2.1.68 states: "Removed Opus 4 and 4.1 from Claude Code on the first-party API — users with these models pinned are automatically moved to Opus 4.6." This automatic migration behavior is not documented anywhere in the model configuration reference. Users who pin to a specific model version (e.g., claude-opus-4-0) have no way to know from the docs that:

1. Models can be removed from Claude Code even if they remain available through the raw API
2. When a pinned model is removed, Claude Code automatically migrates users to the successor model
3. Which specific models have been removed

B. Pinning section scoped only to third-party providers

The pinning documentation is titled "Pin models for third-party deployments" and focuses exclusively on Bedrock, Vertex AI, and Foundry. First-party API users who pin models using full model names or environment variables face the same removal/migration scenario but have no dedicated guidance.

Suggested Improvement

Add a subsection to the model configuration page (after the pinning section or as part of it) that documents model lifecycle behavior:

Model availability and migration

• Claude Code periodically removes older model versions. When a model you have pinned is removed, Claude Code automatically migrates you to the latest version in the same model family (e.g., Opus 4 and 4.1 users were migrated to Opus 4.6).
• Removed models may still be available through the Anthropic API directly but are no longer usable in Claude Code.
• Check the changelog for announcements about model removals.

Also consider broadening the "Pin models for third-party deployments" section title to cover all pinning scenarios, or adding a brief note for first-party API users about the implications of pinning to a specific version.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/model-config | Primary model configuration reference — missing removal/migration policy |
| https://code.claude.com/docs/en/settings | References ANTHROPIC_DEFAULT_OPUS_MODEL env var but no migration behavior |
| https://code.claude.com/docs/en/amazon-bedrock | Third-party pinning guidance — same migration risk applies |
| https://code.claude.com/docs/en/google-vertex-ai | Third-party pinning guidance — same migration risk applies |
| https://code.claude.com/docs/en/microsoft-foundry | Third-party pinning guidance — same migration risk applies |

Total scope: 5 pages affected

Source: Changelog v2.1.68

"Removed Opus 4 and 4.1 from Claude Code on the first-party API — users with these models pinned are automatically moved to Opus 4.6"