docs(models): checklist for rolling out a new model

MODELS.md

@@ -0,0 +1,65 @@
+# Модели: как вводить новую (чеклист)
+
+Единственное место с процедурой. Проверено 2026-09-01 боевым тестом на dell.
+
+## Главный инвариант
+
+**API отбрасывает новые модели по версии клиента.** `claude` CLI 2.1.248 с
+`--model claude-fable-5-1` получает от API
+`400: version 2.1.251 or newer is required` — id проходит насквозь, но сервер
+режет по минимальной версии Claude Code для этой модели. Поэтому порядок
+строго такой: **сначала CLI, потом id в конфигах.**
+
+CLI живёт в двух местах:
+
+- **гейтвей (контейнер на dell)** — забандлен в питоновский пакет
+  `claude-agent-sdk` (`_bundled/claude`), замораживается при сборке образа.
+  Версия CLI = версия пакета, соответствие в
+  [CHANGELOG SDK](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md)
+  (например 0.2.146 → CLI 2.1.248, 0.2.150 → 2.1.257).
+- **t3code на машинах (mac, dell-хост)** — обычный `claude` пользователя
+  (`~/.local/share/claude/versions/…`, `/usr/local/bin/claude`), сам
+  автообновляется; вручную — `claude update`.
+
+## Чеклист «вышла новая модель X»
+
+1. **beaver-gateway**: поднять SDK до версии с достаточно новым CLI:
+   `pyproject.toml` (`claude-agent-sdk>=…`) + `uv lock -P claude-agent-sdk`,
+   закоммитить, запушить `main`.
+2. **beaver-agent/config.py** (строки ~383–399, список агентов): поменять id
+   моделей у `deep`/`dispatcher`/… Effort там же.
+3. **beaver-agent/t3code.toml** (дефолты t3code-mcp per-machine,
+   `model = "claudeAgent/…"`): поменять id. Внимание: t3code для незнакомого
+   ему слага теряет опции `effort`/`contextWindow` (см. ниже) — id должен
+   быть в каталоге t3code, т.е. t3code-приложение должно быть обновлено.
+4. Деплой: `make deploy` (push `main:stable`; образ гейтвея собирается из
+   `beaver-gateway#main` при деплое, поэтому шаг 1 — раньше).
+5. **t3code на машинах**: `claude --version` ≥ минимума модели (обычно уже
+   сам обновился); само приложение t3code (alpha) обновляется nightly и
+   привозит новую модель в каталог.
+
+Проверить, какие id вообще существуют:
+
+```bash
+TOK=$(security find-generic-password -s "Claude Code-credentials" -w | jq -r .claudeAiOauth.accessToken)
+curl -s https://api.anthropic.com/v1/models -H "Authorization: Bearer $TOK" \
+  -H "anthropic-version: 2023-06-01" -H "anthropic-beta: oauth-2025-04-20" | jq -r '.data[].id'
+```
+
+## Алиасы `fable` / `opus` / `sonnet`
+
+CLI принимает голые алиасы и резолвит их в **новейшую модель, которую знает
+установленный CLI** (проверено: CLI 2.1.248 резолвит `fable` →
+`claude-fable-5`, не 5.1). Свойства:
+
+- никогда не дают 400 «слишком старый клиент» — деградируют до старой модели;
+- «всегда новейшая» они дают только при свежем CLI, так что шаг 1 чеклиста
+  они не отменяют, но убирают шаги 2–3 (id в конфигах менять не надо);
+- **в t3code** кастомный слаг (`fable`, `opus`, как и любой id вне каталога)
+  имеет пустые capabilities → t3 не передаёт `--effort` и суффикс `[1m]`
+  (`ClaudeAdapter.ts`: `resolveClaudeEffort(caps,…)` → undefined). Модель
+  работает, но на дефолтном effort и дефолтном окне CLI.
+
+Рекомендация: в `config.py` и `t3code.toml` можно перейти на алиасы, если
+устраивает «новейшее из того, что знает CLI»; explicit id — когда нужен
+точный контроль (и тогда обязательно проверять минимум версии CLI).