diff --git a/services/mcp-gateway.md b/services/mcp-gateway.md
index 0a83217..fb121f5 100644
--- a/services/mcp-gateway.md
+++ b/services/mcp-gateway.md
@@ -98,7 +98,9 @@ cd /opt/stacks/ai/mcp-gateway && docker compose up -d --build
 docker logs mcp-gateway
 ```
 
-UI: `https://mcp.nuclide.systems/ui` (Pocket-ID-gated; `/login` to sign in).
+UI: `https://mcp.nuclide.systems/ui` (Pocket-ID-gated; `/login` to sign in).  
+Models UI: `https://mcp.nuclide.systems/ui/models` — sortable model catalog + service assignment overrides.  
+Model assignments data: `mcp-gateway/model_assignments.json` (bind-mounted rw). API: `GET /api/model-assignments`, `PATCH /api/model-assignments/{service_key}`.
 
 Config: `mcp-gateway/config.json` (live config, persisted). Timestamped backups created on every edit (`config.json.bak.YYYYMMDD-HHMMSS`).
 
@@ -121,6 +123,18 @@ uv run --with playwright -- python -m playwright install chromium   # once
 uv run --with playwright -- python ai/mcp-gateway/ui_check.py        # -> /tmp/mcp_ui.png
 ```
 
+## Model management (added 2026-05-23)
+
+`model_assignments.json` tracks the model each AI-consuming service uses, plus the full 35-model catalog with capability metadata (vision, tools, context window, latency, cost tier).
+
+**Services tracked:** karakeep_text, karakeep_image, paperless_ai, lobechat_default, nextcloud_assistant, home_assistant_voice.
+
+**Catalog models:** 35 (trimmed from 58 on 2026-05-23; dropped paid API models superseded by free SAIA equivalents).
+
+**Model evaluator agent** in `agents.json` — can be triggered via `POST /api/agents/model-evaluator/run` to audit assignments vs SAIA free baseline.
+
+**Env file writes**: the PATCH endpoint updates `model_assignments.json` and attempts to rewrite the service's `.env` file in-place. Because host paths (e.g. `/opt/stacks/karakeep/.env`) are not bind-mounted into the gateway container, `env_written` will be `false` — apply manually and `docker compose up -d --force-recreate <service>`.
+
 ## Verified end-to-end
 
 - `/health` 200 (no auth); `/.well-known/oauth-protected-resource` JSON (no auth).