claude-code - 💡(How to fix) Fix [DOCS] Settings docs still place `/config` preferences in `~/.claude.json` instead of `~/.claude/settings.json` [1 participants]

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:

1. Local project settings (.claude/settings.local.json)
2. Shared project settings (.claude/settings.json)
3. 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:

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