diff --git a/docs/concepts/models.md b/docs/concepts/models.md
index f704068b4..b7fba7b12 100644
--- a/docs/concepts/models.md
+++ b/docs/concepts/models.md
@@ -104,3 +104,5 @@ Output
 
 - Update [`docs/configuration.md`](/gateway/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
 - Keep this doc current when CLI surface or scan logic changes.
+- Note provider aliases like `z.ai/*` -> `zai/*` when relevant.
+- Provider ids in model refs are normalized to lowercase.
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index b3dbef3b4..c51a24de2 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -987,6 +987,30 @@ Select the model via `agent.model.primary` (provider/model).
 }
 ```
 
+### Z.AI (GLM-4.7) — provider alias support
+
+Z.AI models are available via the built-in `zai` provider. Set `ZAI_API_KEY`
+in your environment and reference the model by provider/model.
+
+```json5
+{
+  agent: {
+    model: "zai/glm-4.7",
+    allowedModels: ["zai/glm-4.7"]
+  }
+}
+```
+
+Notes:
+- `z.ai/*` and `z-ai/*` are accepted aliases and normalize to `zai/*`.
+- If `ZAI_API_KEY` is missing, requests to `zai/*` will fail with an auth error at runtime.
+- Z.AI’s general API endpoint is `https://api.z.ai/api/paas/v4`. The GLM Coding
+  Plan uses the dedicated Coding endpoint `https://api.z.ai/api/coding/paas/v4`.
+  The built-in `zai` provider uses the Coding endpoint. If you need the general
+  endpoint, define a custom provider in `models.providers` with the base URL
+  override (see the custom providers section above).
+- Use a fake placeholder in docs/configs; never commit real API keys.
+
 ### Local models (LM Studio) — recommended setup
 
 Best current local setup (what we’re running): **MiniMax M2.1** on a beefy Mac Studio