[DOCS] Settings docs still place `/config` preferences in `~/.claude.json` instead of `~/.claude/settings.json`

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

Configuration scopes, Settings files, Global config settings, and Settings precedence

Current Documentation

The settings page currently says:

* Other configuration is stored in ~/.claude.json. This file contains your preferences (theme, notification settings, editor mode), OAuth session, MCP server configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches.

### Global config settings These settings are stored in ~/.claude.json rather than settings.json. Adding them to settings.json will trigger a schema validation error.

| editorMode | Key binding mode for the input prompt: "normal" or "vim". Default: "normal". Appears in /config as Editor mode |

Later on the same page, the precedence section says:

3. Local project settings (.claude/settings.local.json) 4. Shared project settings (.claude/settings.json) 5. User settings (~/.claude/settings.json)

What's Wrong or Missing?

Changelog v2.1.119 says /config settings such as theme, editor mode, and verbose-related preferences now persist to ~/.claude/settings.json and participate in the normal project/local/policy override hierarchy.

The current docs still describe these /config preferences as ~/.claude.json state, and explicitly say editorMode in settings.json is invalid. That leaves the main settings page internally outdated for the new behavior.

A. Wrong storage location

Users are told that /config preferences like theme and editor mode live in ~/.claude.json, even though v2.1.119 moved them into ~/.claude/settings.json.

B. Missing override-precedence guidance for migrated /config settings

The page documents the general settings hierarchy, but it does not connect that hierarchy to the migrated /config preferences. Readers can easily conclude that theme/editor mode/verbose-style settings are global-only values that cannot be overridden by local, project, or managed settings.

Suggested Improvement

Update the settings docs so they match v2.1.119:

1. Move migrated /config preferences out of the ~/.claude.json / “Global config settings” description and document them as settings.json keys.
2. Add the relevant keys to the main settings.json reference (for example theme, editor mode, verbose/view mode, and the other /config preferences that now persist there).
3. Explicitly state that these settings now follow standard precedence: managed/policy > CLI > local project > shared project > user.
4. Narrow the ~/.claude.json description to the state that still belongs there (for example OAuth/session state, trust decisions, caches, and MCP entries that have not moved).
5. Update related pages that still point users to ~/.claude.json for these /config preferences.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/settings | 117, 224-230, 446-465 | Says theme/editor mode live in ~/.claude.json, says editorMode belongs to “Global config settings”, while the same page also documents the settings.json precedence hierarchy |
| https://code.claude.com/docs/en/terminal-config | 115 | Tells users to set editorMode in ~/.claude.json |
| https://code.claude.com/docs/en/claude-directory | 420-425 | Says /config writes UI preferences like editorMode and showTurnDuration to ~/.claude.json |
| https://code.claude.com/docs/en/troubleshooting | 740-743 | Still categorizes ~/.claude.json as global state for theme |
| https://code.claude.com/docs/en/desktop | 614-619 | Says shared settings come from both ~/.claude.json and ~/.claude/settings.json |

Total scope: 5 pages affected

Source: Changelog v2.1.119

Exact changelog entry: /config settings (theme, editor mode, verbose, etc.) now persist to ~/.claude/settings.json and participate in project/local/policy override precedence