diff --git a/site/src/content/docs/api/overview.mdx b/site/src/content/docs/api/overview.mdx
index 8656c11..d23c522 100644
--- a/site/src/content/docs/api/overview.mdx
+++ b/site/src/content/docs/api/overview.mdx
@@ -9,10 +9,21 @@ The Nyuchi API is a single versioned HTTP gateway. Every endpoint lives under a
 
 ## Base URL
 
-| Environment | URL |
-|-------------|-----|
-| Production  | `https://api.nyuchi.com` |
-| Legacy host | `https://api.mukoko.com` |
+| Host | What it is |
+|------|------------|
+| `https://api.nyuchi.com` | **Production — the gateway serving traffic today** (FastAPI on Fly.io). Point every client here. |
+| `https://api.mukoko.com` | A **separate Mukoko gateway still being built.** It serves nothing usable yet and has no DNS record, so a request to it fails to connect. |
+
+<Aside type="caution">
+  **`api.mukoko.com` is not a legacy alias.** It has never served traffic and
+  does not redirect anywhere — it is a future gateway that has not shipped, not
+  a deprecated predecessor of `api.nyuchi.com`. Describing it as "legacy" tells
+  a reader the opposite of what is true (that it used to work, rather than that
+  it does not work yet), so please don't reword it back. The name is documented
+  here only because it appears in the gateway's trusted-host allowlist — see
+  [Security and rate limits](/api/security/) — and a reader who has heard it
+  needs somewhere to find out what it actually is.
+</Aside>
 
 <Aside type="note">
   The legacy `/api/*` prefix no longer resolves. If you are upgrading from an earlier client, repoint every request from `/api/...` to `/v1/...`.
diff --git a/site/src/content/docs/api/security.mdx b/site/src/content/docs/api/security.mdx
index 366715c..adabf8f 100644
--- a/site/src/content/docs/api/security.mdx
+++ b/site/src/content/docs/api/security.mdx
@@ -13,13 +13,21 @@ The gateway only accepts traffic whose `Host` header matches an allowed entry. U
 
 | Allowed by default | Used for |
 |--------------------|----------|
-| `api.nyuchi.com` | Production traffic |
-| `api.mukoko.com` | Legacy production host |
+| `api.nyuchi.com` | Production traffic — the gateway serving requests today |
+| `api.mukoko.com` | Reserved for a separate Mukoko gateway still being built. Allow-listed ahead of that host existing — **not** a legacy or deprecated production host, and no DNS record today, so no request actually arrives carrying this `Host` header yet |
 | `*.fly.dev` | Fly.io preview deployments |
 | `localhost`, `testserver` | Local development and CI |
 
 Override the list with the `TRUSTED_HOSTS` environment variable (comma-separated) when you stand up a new edge or staging host.
 
+<Aside type="caution">
+  The `api.mukoko.com` entry is easy to misread as an old host kept alive for
+  back-compat. It is the reverse: the Mukoko gateway has not shipped, so nothing
+  has ever been served on that name. See [API overview](/api/overview/) for the
+  full four-host picture — the two gateways are also routinely confused with
+  WorkOS's `auth.mukoko.com` and `accounts.mukoko.com`.
+</Aside>
+
 ## Security headers
 
 Every response carries a standard hardening header set:
diff --git a/site/src/content/docs/deployment/agentgateway.mdx b/site/src/content/docs/deployment/agentgateway.mdx
index 057c78a..f4b0fb7 100644
--- a/site/src/content/docs/deployment/agentgateway.mdx
+++ b/site/src/content/docs/deployment/agentgateway.mdx
@@ -122,9 +122,11 @@ be unnecessary.
 
 The OIDC identity is a **WorkOS Connect OAuth Application** (first-party,
 confidential — not Public, since agentgateway exchanges the code
-server-side), created in the "Nyuchi Identity" WorkOS project's Production
-environment — the same pattern `mzizi-mcp` and `bushtrade-mcp` use for
-gating internal services against the same identity pool.
+server-side), created in the **Production** environment of the WorkOS project
+**`Mukoko Account`** — the account's only project, whose other environment is
+the `Staging` sandbox. (There is no "Nyuchi Identity" project; that name never
+existed in this WorkOS account.) Same pattern `mzizi-mcp` and `bushtrade-mcp`
+use for gating internal services against the same identity pool.
 
 **Four secrets, set with `flyctl secrets set`, not written to `config.yaml`
 or committed to git:**