diff --git a/README.md b/README.md
index 06adf8a..8886ed6 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,7 @@ fastfetch will run on shell start, starship prompt active, all tools on PATH.
 
 ### Per-machine age key (required to decrypt secrets)
 
-The repo contains encrypted secrets (`~/.omp/agent/zai.key`, `~/.omp/agent/.env`) that only your per-machine age key can decrypt. After bootstrap, generate the key on this box:
+The repo contains encrypted secrets (`~/.omp/agent/zai.key`, `~/.omp/agent/.env`, `~/.omp/agent/models.yml`) that only your per-machine age key can decrypt. After bootstrap, generate the key on this box:
 
 ```bash
 age-keygen -o ~/.config/chezmoi/key.txt
@@ -100,6 +100,16 @@ chezmoi apply
 
 If you skip this step, the omp config files will still land (they're not encrypted), but `zai.key` and `.env` will be missing and omp won't be able to authenticate against providers.
 
+### Why `models.yml` is encrypted (and not in `zai.key`)
+
+omp v16.1.16 has a quirk: the built-in `zai` provider routes to `https://api.z.ai/api/anthropic` (Anthropic-compatible endpoint) which requires `x-api-key`. omp only sends `Authorization: Bearer`, so the built-in provider always 401s on real Z.ai API keys.
+
+Workaround: define a custom `zai-coding` provider in `~/.omp/agent/models.yml` pointing at the OpenAI-compatible endpoint `https://api.z.ai/api/coding/paas/v4` (which DOES accept `Authorization: Bearer`).
+
+Gotcha: omp's `apiKey:` field in custom providers expects a **literal key value** — NOT an env var name. `apiKey: ZAI_CODING_API_KEY` was being treated as the literal string `ZAI_CODING_API_KEY` and sent as `Authorization: Bearer ZAI_CO...KEY` → 401. The encrypted `models.yml` in this repo contains the literal Z.ai API key in `apiKey:` (same key that's in `zai.key`).
+
+`run_onchange_35-ensure-omp-models-perms.sh` chmod 600s the decrypted file so the literal key isn't world-readable (matches `zai.key`'s tighter perms).
+
 ## Sway / Wayland desktop stack
 
 Sway + wofi + foot + waybar + swaybg/lock/idle + grim/slurp + wl-clipboard is opt-in at bootstrap time. The user decides per-box.