docs: document openrouter sync workflow

docs/custom_models.md

@@ -221,7 +221,7 @@ 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.json` → Routed through OpenRouter (requires `OPENROUTER_API_KEY`)
+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
 
 **Provider Priority Order:**
@@ -241,7 +241,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. Each entry maps directly onto [`ModelCapabilities`](../providers/shared/model_capabilities.py).
+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).
+
+### Refreshing the Live OpenRouter Catalogue
+
+Run the sync script whenever OpenRouter adds or removes models that you want `listmodels` and provider enumeration to expose, or before cutting a release that should include an updated OpenRouter catalogue.
+
+```bash
+source .pal_venv/bin/activate
+python scripts/sync_openrouter_models.py
+```
+
+By default the script:
+
+- fetches `https://openrouter.ai/api/v1/models`
+- writes conservative discovery data to `conf/openrouter_models_live.json`
+- leaves `conf/openrouter_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_openrouter_models.py --url https://openrouter.ai/api/v1/models --output conf/openrouter_models_live.json
+```
+
+Important runtime behavior:
+
+- `conf/openrouter_models_live.json` is the generated baseline catalogue
+- `conf/openrouter_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/openrouter_models_live.json`
+2. Add or update curated entries in `conf/openrouter_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
 
 #### Adding an OpenRouter Model