feat(zen): add live model sync

docs/custom_models.md

@@ -221,13 +221,15 @@ CUSTOM_MODEL_NAME=your-loaded-model
 The system automatically routes models to the appropriate provider:
 
 1. Entries in `conf/custom_models.json` → Always routed through the Custom API (requires `CUSTOM_API_URL`)
-2. Entries in `conf/openrouter_models_live.json` and `conf/openrouter_models.json` → Routed through OpenRouter (requires `OPENROUTER_API_KEY`)
-3. **Unknown models** → Fallback logic based on model name patterns
+2. Entries in `conf/zen_models_live.json` and `conf/zen_models.json` → Routed through OpenCode Zen (requires `ZEN_API_KEY`)
+3. Entries in `conf/openrouter_models_live.json` and `conf/openrouter_models.json` → Routed through OpenRouter (requires `OPENROUTER_API_KEY`)
+4. **Unknown models** → Fallback logic based on model name patterns
 
 **Provider Priority Order:**
 1. Native APIs (Google, OpenAI) - if API keys are available
-2. Custom endpoints - for models declared in `conf/custom_models.json`  
-3. OpenRouter - catch-all for cloud models
+2. OpenCode Zen - curated gateway models
+3. Custom endpoints - for models declared in `conf/custom_models.json`
+4. OpenRouter - catch-all for cloud models
 
 This ensures clean separation between local and cloud models while maintaining flexibility for unknown models.
 
@@ -241,7 +243,42 @@ These JSON files define model aliases and capabilities. You can:
 
 ### Adding Custom Models
 
-Edit `conf/openrouter_models.json` to tweak OpenRouter behaviour or `conf/custom_models.json` to add local models. The generated `conf/openrouter_models_live.json` file is discovery data from OpenRouter's `/api/v1/models` endpoint; curated entries in `conf/openrouter_models.json` override those generated defaults. Each entry maps directly onto [`ModelCapabilities`](../providers/shared/model_capabilities.py).
+Edit `conf/zen_models.json` to tweak OpenCode Zen behaviour, `conf/openrouter_models.json` to tweak OpenRouter behaviour, or `conf/custom_models.json` to add local models. The generated `conf/zen_models_live.json` and `conf/openrouter_models_live.json` files are discovery data from the upstream model listing endpoints; curated entries override those generated defaults. Each entry maps directly onto [`ModelCapabilities`](../providers/shared/model_capabilities.py).
+
+### Refreshing the Live OpenCode Zen Catalogue
+
+Run the sync script whenever OpenCode Zen adds or removes models that you want `listmodels` and provider enumeration to expose, or before cutting a release that should include an updated Zen catalogue.
+
+```bash
+source .pal_venv/bin/activate
+python scripts/sync_zen_models.py
+```
+
+By default the script:
+
+- fetches `https://opencode.ai/zen/v1/models`
+- writes conservative discovery data to `conf/zen_models_live.json`
+- leaves `conf/zen_models.json` untouched
+
+Use the optional flags if you need to test against a different endpoint or write to a different file:
+
+```bash
+python scripts/sync_zen_models.py --url https://opencode.ai/zen/v1/models --output conf/zen_models_live.json
+```
+
+Important runtime behavior:
+
+- `conf/zen_models_live.json` is the generated baseline catalogue
+- `conf/zen_models.json` is the curated override layer for aliases and PAL-specific capability flags
+- curated entries win when the same `model_name` appears in both files
+- models missing from the curated file are still available from the generated catalogue
+
+After refreshing the catalogue:
+
+1. Review the diff in `conf/zen_models_live.json`
+2. Add or update curated entries in `conf/zen_models.json` if a new model needs aliases or PAL-specific capability tweaks
+3. Restart the server so the updated manifests are reloaded
+4. Commit the generated JSON alongside any curated overrides so other contributors get the same catalogue state
 
 ### Refreshing the Live OpenRouter Catalogue