docs(providers): document Z.AI/Zhipu GLM provider variants

Update provider documentation with:
- Four provider variants table (zai, zai-coding, zhipu, zhipu-coding)
- Region and plan type guidance
- CLI setup commands for all variants
- Environment variable fallback chains
- Config snippets for each variant
- Important notes on key interchangeability and billing

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

docs/providers/glm.md

@@ -4,18 +4,33 @@ read_when:
   - You want GLM models in Moltbot
   - You need the model naming convention and setup
 ---
-# GLM models
+# GLM Models
 
-GLM is a **model family** (not a company) available through the Z.AI platform. In Moltbot, GLM
-models are accessed via the `zai` provider and model IDs like `zai/glm-4.7`.
+GLM is a **model family** developed by Zhipu AI. GLM models are available through two platforms:
 
-## CLI setup
+- **Z.AI** (api.z.ai) - International platform
+- **Zhipu AI** (bigmodel.cn) - China mainland platform
+
+## Provider Options
+
+| Provider | Platform | Use Case |
+|----------|----------|----------|
+| `zai` | Z.AI (International) | Pay-as-you-go |
+| `zai-coding` | Z.AI (International) | Coding Plan subscription |
+| `zhipu` | Zhipu AI (China) | Pay-as-you-go |
+| `zhipu-coding` | Zhipu AI (China) | Coding Plan subscription |
+
+## CLI Setup
 
 ```bash
+# International users
 moltbot onboard --auth-choice zai-api-key
+
+# China users
+moltbot onboard --auth-choice zhipu-api-key
 ```
 
-## Config snippet
+## Config Snippet
 
 ```json5
 {
@@ -24,8 +39,18 @@ moltbot onboard --auth-choice zai-api-key
 }
 ```
 
+## Available Models
+
+- `glm-4.7` - Latest flagship model (205K context)
+- `glm-4.6` - Previous generation (205K context)
+- `glm-4.6v` - Vision model (128K context)
+- `glm-4.5` - Balanced performance (131K context)
+- `glm-4.5-air` - Lighter variant (131K context)
+- `glm-4.5-flash` - Faster variant (131K context)
+
+Model availability may vary by region; check the platform docs for the latest.
+
 ## Notes
 
-- GLM versions and availability can change; check Z.AI's docs for the latest.
-- Example model IDs include `glm-4.7` and `glm-4.6`.
-- For provider details, see [/providers/zai](/providers/zai).
+- Model IDs follow the pattern `{provider}/glm-{version}` (e.g., `zai/glm-4.7`, `zhipu/glm-4.7`)
+- For detailed provider setup, see [/providers/zai](/providers/zai)

docs/providers/index.md

@@ -41,8 +41,8 @@ See [Venice AI](/providers/venice).
 - [Moonshot AI (Kimi + Kimi Code)](/providers/moonshot)
 - [OpenCode Zen](/providers/opencode)
 - [Amazon Bedrock](/bedrock)
-- [Z.AI](/providers/zai)
-- [GLM models](/providers/glm)
+- [Z.AI / Zhipu AI (GLM models)](/providers/zai) - International + China, pay-as-you-go + Coding Plan
+- [GLM models](/providers/glm) - Model family overview
 - [MiniMax](/providers/minimax)
 - [Venius (Venice AI, privacy-focused)](/providers/venice)
 - [Ollama (local models)](/providers/ollama)

docs/providers/zai.md

@@ -1,24 +1,81 @@
 ---
-summary: "Use Z.AI (GLM models) with Moltbot"
+summary: "Use Z.AI / Zhipu AI (GLM models) with Moltbot"
 read_when:
   - You want Z.AI / GLM models in Moltbot
-  - You need a simple ZAI_API_KEY setup
+  - You need to choose between international and China endpoints
+  - You have a Coding Plan subscription
 ---
-# Z.AI
+# Z.AI / Zhipu AI (GLM Models)
 
-Z.AI is the API platform for **GLM** models. It provides REST APIs for GLM and uses API keys
-for authentication. Create your API key in the Z.AI console. Moltbot uses the `zai` provider
-with a Z.AI API key.
+Z.AI and Zhipu AI provide access to **GLM** models. There are four provider configurations
+depending on your region and subscription type.
 
-## CLI setup
+## Provider Variants
+
+| Provider | Region | Plan Type | Base URL |
+|----------|--------|-----------|----------|
+| `zai` | International | Pay-as-you-go | api.z.ai |
+| `zai-coding` | International | Coding Plan | api.z.ai (coding endpoint) |
+| `zhipu` | China | Pay-as-you-go | bigmodel.cn |
+| `zhipu-coding` | China | Coding Plan | bigmodel.cn (coding endpoint) |
+
+## Which should I use?
+
+- **International users with pay-as-you-go**: Use `zai`
+- **International users with Coding Plan subscription ($3-15/mo)**: Use `zai-coding`
+- **China mainland users with pay-as-you-go**: Use `zhipu`
+- **China mainland users with Coding Plan**: Use `zhipu-coding`
+
+The Coding Plan endpoints are optimized for coding tools and have better tool-calling
+performance. They use subscription-based billing rather than per-token billing.
+
+## CLI Setup
 
 ```bash
+# International (pay-as-you-go)
 moltbot onboard --auth-choice zai-api-key
-# or non-interactive
-moltbot onboard --zai-api-key "$ZAI_API_KEY"
+
+# International (Coding Plan)
+moltbot onboard --auth-choice zai-coding-api-key
+
+# China (pay-as-you-go)
+moltbot onboard --auth-choice zhipu-api-key
+
+# China (Coding Plan)
+moltbot onboard --auth-choice zhipu-coding-api-key
 ```
 
-## Config snippet
+### Non-interactive
+
+```bash
+# International (pay-as-you-go)
+moltbot onboard --non-interactive --auth-choice zai-api-key --zai-api-key "$ZAI_API_KEY"
+
+# International (Coding Plan)
+moltbot onboard --non-interactive --auth-choice zai-coding-api-key --zai-coding-api-key "$ZAI_API_KEY"
+
+# China (pay-as-you-go)
+moltbot onboard --non-interactive --auth-choice zhipu-api-key --zhipu-api-key "$ZHIPU_API_KEY"
+
+# China (Coding Plan)
+moltbot onboard --non-interactive --auth-choice zhipu-coding-api-key --zhipu-coding-api-key "$ZHIPU_API_KEY"
+```
+
+## Environment Variables
+
+| Provider | Primary Env Var | Fallback Chain |
+|----------|-----------------|----------------|
+| `zai` | `ZAI_API_KEY` | `Z_AI_API_KEY` |
+| `zai-coding` | `ZAI_CODING_API_KEY` | `ZAI_API_KEY` → `Z_AI_API_KEY` |
+| `zhipu` | `ZHIPU_API_KEY` | (none) |
+| `zhipu-coding` | `ZHIPU_CODING_API_KEY` | `ZHIPU_API_KEY` |
+
+The coding providers fall back to their respective general provider's env var, so you can
+use a single API key for both if desired.
+
+## Config Snippets
+
+### International (pay-as-you-go)
 
 ```json5
 {
@@ -27,8 +84,46 @@ moltbot onboard --zai-api-key "$ZAI_API_KEY"
 }
 ```
 
-## Notes
+### International (Coding Plan)
 
-- GLM models are available as `zai/<model>` (example: `zai/glm-4.7`).
-- See [/providers/glm](/providers/glm) for the model family overview.
-- Z.AI uses Bearer auth with your API key.
+```json5
+{
+  env: { ZAI_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "zai-coding/glm-4.7" } } }
+}
+```
+
+### China (pay-as-you-go)
+
+```json5
+{
+  env: { ZHIPU_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "zhipu/glm-4.7" } } }
+}
+```
+
+### China (Coding Plan)
+
+```json5
+{
+  env: { ZHIPU_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "zhipu-coding/glm-4.7" } } }
+}
+```
+
+## Important Notes
+
+- **Same API key, different endpoints**: Your API key works on both general and coding
+  endpoints, but the billing is different. Using a Coding Plan key on the general
+  endpoint may return error 1113 ("Insufficient balance").
+
+- **Regional keys are not interchangeable**: Keys from z.ai don't work on bigmodel.cn
+  and vice versa. Create your key on the platform for your region.
+
+- **Coding endpoint optimized for tools**: The coding endpoints have better
+  tool-calling performance and are recommended for use with coding assistants.
+
+- **GLM models**: Models are available as `{provider}/glm-4.7`, `{provider}/glm-4.6`, etc.
+  See [/providers/glm](/providers/glm) for the model family overview.
+
+- **Authentication**: All variants use Bearer token auth with your API key.