diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs
index 9702accfd7..b25586f7a6 100644
--- a/docs-site/astro.config.mjs
+++ b/docs-site/astro.config.mjs
@@ -148,6 +148,7 @@ export default defineConfig({
             },
             { label: "Adapters", translations: { fr: "Adaptateurs", ko: "어댑터", "zh-CN": "适配器", "zh-TW": "適配器", ru: "Адаптеры", ja: "アダプター", tr: "Adaptörler" }, slug: "reference/adapters" },
             { label: "Architecture", translations: { fr: "Architecture", ko: "아키텍처", "zh-CN": "架构", "zh-TW": "架構", ru: "Архитектура", ja: "アーキテクチャ", tr: "Mimari" }, slug: "reference/architecture" },
+            { label: "Platform Support", translations: { fr: "Prise en charge des plateformes", ko: "플랫폼 지원", "zh-CN": "平台支持", "zh-TW": "平台支援", ru: "Поддержка платформ", ja: "プラットフォーム対応", tr: "Platform Desteği" }, link: `${SITE_URL}/reference/platform-support` },
             { label: "Proxy API Formats", translations: { fr: "Formats de l’API proxy", ko: "프록시 API 형식", "zh-CN": "代理 API 格式", "zh-TW": "代理 API 格式", ru: "Форматы API прокси", ja: "プロキシAPI形式", tr: "Proxy API Formatları" }, slug: "reference/proxy-formats" },
             { label: "Management API", translations: { fr: "API de gestion", ko: "관리 API", "zh-CN": "管理 API", "zh-TW": "管理 API", ru: "API управления", ja: "管理API", tr: "Yönetim API'si" }, slug: "reference/management-api" },
           ],
diff --git a/docs-site/src/content/docs/guides/providers.md b/docs-site/src/content/docs/guides/providers.md
index 1b87c03ff2..0b874bde3c 100644
--- a/docs-site/src/content/docs/guides/providers.md
+++ b/docs-site/src/content/docs/guides/providers.md
@@ -467,7 +467,8 @@ Elsewhere it asks you to paste the key. Meta ships no native Windows CLI, and on
 CLI exists but where it stores its credential has not been verified, so OpenCodex refuses
 to guess at a credential store and points you at [dev.meta.ai](https://dev.meta.ai)
 instead, where the same key is visible. A pasted key faces the same format check and the
-same live validation against the Model API as an imported one.
+same live validation against the Model API as an imported one. See
+[Platform support](/reference/platform-support/) for the full per-platform picture.
 
 **Read this before enabling it.** Meta scopes that credential to the Muse Code CLI, so
 using it here is an *unsupported* path. Meta does not authorize subscription coverage
diff --git a/docs-site/src/content/docs/reference/platform-support.md b/docs-site/src/content/docs/reference/platform-support.md
new file mode 100644
index 0000000000..a0d484551d
--- /dev/null
+++ b/docs-site/src/content/docs/reference/platform-support.md
@@ -0,0 +1,81 @@
+---
+title: Platform support
+description: What OpenCodex can do on macOS, Windows and Linux, and why a few capabilities stay platform-specific.
+---
+
+OpenCodex runs on macOS, Windows and Linux. Most of it behaves identically on all
+three; a few capabilities depend on something the operating system provides, and
+this page says which, and why.
+
+## Everywhere
+
+| Capability | Notes |
+| --- | --- |
+| Proxy, routing, provider adapters | The core runtime is platform-neutral. |
+| Background service | Three native backends: launchd on macOS, Task Scheduler **or** WinSW on Windows, a systemd user unit on Linux. |
+| Browser login | Opens through the platform's own handler. |
+| Client detection | Cursor, Claude Desktop, Kiro and Codex installs are located per platform. |
+
+### Provider keys in the OS credential store
+
+Supported on all three platforms, **when an unlocked OS credential service is
+available**: Keychain on macOS, Credential Manager on Windows, libsecret on
+Linux. A locked keyring or a headless session has no unlocked service, so the
+store is unavailable and OpenCodex says so rather than silently falling back.
+See [Providers](/reference/configuration/providers/) for the storage rules.
+
+## macOS only
+
+### Claude Code auto-connect
+
+Injecting `ANTHROPIC_BASE_URL` and the Claude Code levers into your session
+happens through the launchd user domain, which has no single equivalent
+elsewhere.
+
+On Linux the three plausible mechanisms each reach a different set of processes:
+`systemctl --user set-environment` reaches only systemd-spawned units,
+`~/.profile` only login shells, and `~/.bashrc` only interactive non-login
+shells. There is no one place that covers a user's whole session.
+
+On Windows the equivalent is `HKCU\Environment`, which is genuinely persistent
+rather than per-boot. That is the problem: it would move a bearer token from a
+domain that empties at reboot into a registry hive that does not, which is a
+change in how long the credential sits on disk and who can read it. That
+decision needs a security review rather than a port.
+
+Everything else Claude Code needs works on all platforms. You can set the same
+variables yourself, or run `ocx claude`, which passes them to the child process
+directly.
+
+## Import versus paste
+
+### Meta Muse Code
+
+On macOS, OpenCodex imports the API key the Muse Code CLI already stored after
+`muse login`, so you are not asked to provision a second one.
+
+Elsewhere it asks you to paste the key instead. Meta ships no native Windows
+CLI, and on Linux the CLI exists but where it keeps its credential has not been
+verified, so OpenCodex declines to guess at a credential store. The same key is
+visible in [Meta's developer console](https://dev.meta.ai), and a pasted key
+faces the same format check and the same live validation against the Model API
+as an imported one.
+
+## Windows notes
+
+The Windows service can run under Task Scheduler or as a native WinSW service,
+and those are mutually exclusive. `ocx service repair` refuses to proceed when
+it finds state for both, because guessing which one you meant is how a machine
+ends up with two proxies fighting over a port.
+
+Console output on a non-English Windows install arrives in the system code page
+rather than UTF-8. OpenCodex decodes it accordingly, so an account name with
+non-ASCII characters resolves correctly.
+
+## When something is unavailable
+
+OpenCodex states the actual reason rather than disabling a control silently. If
+a capability is unavailable on your platform, the error or the dashboard says
+which mechanism is missing and what the supported alternative is. If you hit one
+that does not, that is a bug worth reporting.
+