docs(troubleshooting): note server-managed settings skip custom ANTHROPIC_BASE_URL (#3118)

## Description

Documents a known Claude Code client-side limitation: server-managed
settings (delivered from the claude.ai admin console) are silently
skipped whenever `ANTHROPIC_BASE_URL` is non-default — which is exactly
the condition Headroom wrapping creates. Fixes #3074 by explaining the
root cause is upstream, not a Headroom bug, and pointing affected users
at the endpoint-managed alternative.

## Type of Change

- [x] Documentation
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Refactor / chore

## Changes Made

- Added a new "Server-managed settings unavailable through custom
ANTHROPIC_BASE_URL" section to `docs/content/docs/troubleshooting.mdx`,
immediately after the existing "Remote Control unavailable through
custom ANTHROPIC_BASE_URL" section (same class of Claude-side gate, same
Symptom/Cause/Fix format).
- Explains why Headroom has no endpoint to implement here (per
Anthropic's docs, Claude Code skips the fetch client-side before any
request is sent) and distinguishes this from the unrelated, unaffected
OS-level `managed-settings.json` file.
- Links to Anthropic's official docs and to #3074.

## Testing

- [x] Verified locally
- [ ] Added/updated automated tests
- [ ] N/A

```
$ python3 -c "
import re
text = open('docs/content/docs/troubleshooting.mdx', encoding='utf-8').read()
headings = re.findall(r'^##\s+.*$', text, re.MULTILINE)
start = text.index('## Server-managed settings')
end = text.index('## Compression Too Aggressive')
section = text[start:end]
print('backticks even:', section.count(chr(96)) % 2 == 0)
print('brackets balanced:', section.count('[') == section.count(']'))
print('parens balanced:', section.count('(') == section.count(')'))
"
backticks even: True
brackets balanced: True
parens balanced: True
```

## Real Behavior Proof

- Environment: Docs-only change (MDX prose, no code path). `docs/` npm
deps are not installed in this sandbox, so the Next.js docs build (`npm
run build`) was not run.
- Exact command / steps: Diffed the new section against the file's
existing neighboring section (git diff), and ran a Python script
validating heading structure and backtick/bracket/paren balance within
the new section (shown above).
- Observed result: New `##` heading inserted cleanly between the two
existing sections with no structural changes elsewhere in the file;
markdown syntax (bold labels, inline code, links) mirrors the adjacent
"Remote Control" section exactly, and is balanced/well-formed.
- Not tested: The actual Next.js docs site build/render (`npm run build`
in `docs/`) — no network/npm install available in this sandbox. No
functional/runtime behavior is affected by this change.

## Runtime Rollout Safety

- Rollout-managed feature(s): None
- Minimum rollout channel: N/A
- Stable/default behavior changed: No
- Kill switch / disable path: N/A
- Unsafe override required: No
- Qualification impact: None
- Rollback path: Revert the commit; no state or config is introduced

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

docs/content/docs/troubleshooting.mdx

@@ -223,6 +223,18 @@ See [issue #746](https://github.com/headroomlabs-ai/headroom/issues/746) for the
 
 `ENABLE_TOOL_SEARCH` is unaffected and can stay enabled for context-window savings while routing through Headroom.
 
+## Server-managed settings unavailable through custom ANTHROPIC_BASE_URL
+
+**Symptom**: Settings pushed from **Admin Settings > Claude Code > Managed settings** in the claude.ai console (server-managed settings) don't apply to sessions running through Headroom, even though they apply fine without the proxy.
+
+**Cause**: This is a Claude-side gate, not a Headroom limitation. Per Anthropic's docs, server-managed settings require a direct connection to `api.anthropic.com`; if `ANTHROPIC_BASE_URL` is set to any non-default host — which is exactly what wrapping via Headroom does — Claude Code skips the settings fetch entirely for that session. The request never reaches Headroom, so there is no endpoint for Headroom to implement or proxy.
+
+This is separate from the OS-level `managed-settings.json` file (macOS `/Library/Application Support/ClaudeCode/`, Linux `/etc/claude-code/`, Windows `C:\Program Files\ClaudeCode\`): that file is read straight from local disk at startup and is unaffected by `ANTHROPIC_BASE_URL` or Headroom. If that file isn't taking effect, the cause is unrelated to proxying (path, permissions, or JSON syntax) — check `claude --debug-file <path>` and search the log for `Remote settings`.
+
+**Fix**: None available on the Headroom side — this is an intentional Anthropic security boundary (a proxy in the path could otherwise forge org policy). If your org relies on server-managed settings, deploy the same policy as [endpoint-managed settings](https://code.claude.com/docs/en/settings#settings-files) (MDM profile, Windows registry, or a local `managed-settings.json`) instead, since those are read locally and unaffected by proxying.
+
+See [Server-managed settings platform availability](https://code.claude.com/docs/en/server-managed-settings#platform-availability) and [issue #3074](https://github.com/headroomlabs-ai/headroom/issues/3074).
+
 ## Compression Too Aggressive
 
 **Symptom**: LLM responses are missing information that was in tool outputs.