[DOCS] Document `managed-settings.d/` drop-in directory for multi-team policy fragment deployment

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

File-based managed settings — configuration scopes and settings precedence

Current Documentation

File-based: managed-settings.json and managed-mcp.json deployed to system directories: macOS: /Library/Application Support/ClaudeCode/ Linux and WSL: /etc/claude-code/ * Windows: C:\Program Files\ClaudeCode\

And in the precedence section:

Within the managed tier, precedence is: server-managed > MDM/OS-level policies > managed-settings.json > HKCU registry (Windows only). Only one managed source is used; sources do not merge.

What's Wrong or Missing?

Claude Code v2.1.83 added a managed-settings.d/ drop-in directory alongside managed-settings.json. This directory allows separate teams to deploy independent policy fragment files that are merged alphabetically into the effective managed settings. Neither the settings page nor the server-managed-settings page documents this directory, its merge behavior, or how teams should use it. Additionally, the existing precedence section incorrectly states "Only one managed source is used; sources do not merge" — this is no longer accurate given the new merging behavior within the file-based managed tier.

Source: Changelog v2.1.83

Suggested Improvement

In the file-based managed settings section of the settings page, add coverage of the drop-in directory:

• Document that a managed-settings.d/ directory can be placed alongside managed-settings.json in the same system directories (macOS, Linux/WSL, Windows).
• Explain that each file in managed-settings.d/ is a partial settings JSON fragment.
• Explain that fragments are merged alphabetically by filename into the effective managed settings.
• Explain how managed-settings.d/ fragments interact with managed-settings.json (e.g., whether managed-settings.json takes precedence over or merges with drop-in fragments).
• Provide a practical example showing two teams (e.g., security and platform) each deploying their own fragment file (e.g., 10-security.json, 20-platform.json).
• Update the precedence section to reflect that within the file-based tier, sources now merge rather than the old "only one source is used" behavior.

Impact

High - Administrators deploying endpoint-managed settings for multi-team organizations cannot discover or use this capability from the docs. The existing precedence statement actively contradicts the new behavior, which may cause misconfiguration.

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/settings | Primary page documenting file-based managed settings, configuration scopes, and settings precedence — all need updating |
| https://code.claude.com/docs/en/server-managed-settings | Cross-references endpoint-managed settings; may need a note that file-based settings now support drop-in fragments |
| https://code.claude.com/docs/en/permissions | Documents managed-only settings and references managed-settings.json |

Total scope: 3 pages affected

Source: Changelog v2.1.83

Added managed-settings.d/ drop-in directory alongside managed-settings.json, letting separate teams deploy independent policy fragments that merge alphabetically