From c51dc864d86bd904d5c2a0f1e428a8af2da86580 Mon Sep 17 00:00:00 2001
From: rain <rain@melonbread.xyz>
Date: Tue, 23 Jun 2026 19:47:19 -0400
Subject: [PATCH] README: document omp zai-coding provider quirk + models.yml
 encrypted
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Explains why models.yml is in chezmoi (encrypted) and why the literal
Z.ai API key is in apiKey: rather than in zai.key — short version:
omp v16.1.16's built-in zai provider routes to /api/anthropic which
rejects Bearer auth, so a custom zai-coding provider is needed at
/api/coding/paas/v4 which does accept Bearer. The custom provider's
apiKey field requires a literal value, so the key is embedded in the
encrypted file. See references/omp-provider-secrets.md in the chezmoi
skill for the long version + verification commands.
---
 README.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

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.