feat(agents): publish scoped model catalogs and dedicated client profiles

.github/workflows/validate.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Validate repository contract
         shell: pwsh
         run: ./tests/static/validate.ps1
+      - name: Validate Windows profile template without credentials
+        shell: pwsh
+        run: ./tests/static/windows-profile.ps1
       - name: ShellCheck
         run: |
           shellcheck setup-macos.command uninstall-macos.command scripts/macos/*.sh tests/macos/*.sh

AGENTS.md

@@ -6,3 +6,6 @@
 - Do not overwrite unrelated Codex, Claude Code, shell, or PATH configuration. Update and uninstall only files marked as installer-owned.
 - Keep Windows PowerShell 5.1 compatibility and macOS system Bash compatibility.
 - Validate script syntax, generated TOML/JSON, idempotency, secret handling, and uninstall boundaries before publishing.
+
+- Codex uses the user-level profile-v2 file and `/v1/codex` with WebSocket enabled. Publish installers only after authenticated server catalog and HTTP/WebSocket release checks; HTTP fallback keeps the same profile URL.
+- Managed launchers fetch and validate fresh key-scoped catalogs into private per-launch snapshots; never fall back to stale/bundled lists or accept executable server settings. Claude's explicit base URL is `/v1/claude-code`. Keep ordinary keys, preserve unrelated configuration, and document managed-policy/explicit-override boundaries.

README.en.md

@@ -4,6 +4,14 @@ Public, auditable one-click setup for routing local Codex CLI and Claude Code se
 
 [Русская версия](README.md)
 
+## Release compatibility
+
+This version configures `https://neuroapi.host/v1/codex` with `supports_websockets = true`, and `https://neuroapi.host/v1/claude-code` for Claude Code. Publish or distribute it **only after the server profiles are deployed** and authenticated `/v1/codex/models`, HTTP/WebSocket `/v1/codex/responses`, `/v1/claude-code/client-settings`, and Claude Messages/count_tokens checks pass. Local implementation is not production evidence. Setup deliberately does not call the API to validate credentials; launchers fetch the current catalog before starting a client.
+
+An existing `CODEX_HOME` selects the profile directory without being modified. Keep its value consistent for setup, launch and uninstall.
+
+Use a current Codex release whose `--help` describes `--profile` as loading `<name>.config.toml`. Update older clients that expect `[profiles.name]` in the main configuration. For WebSocket troubleshooting, temporarily set `supports_websockets = false` in the generated profile, keeping `/v1/codex` and its credential helper.
+
 ## Quick start
 
 Install [Codex CLI](https://developers.openai.com/codex/cli/) and/or [Claude Code](https://code.claude.com/docs/en/installation), then create a key in the [NeuroAPI dashboard](https://neuroapi.host/login?redirect=/dashboard/tokens).
@@ -37,11 +45,13 @@ This prevents accidental plaintext disclosure. It does not protect a key from ma
 
 ## Verification
 
-- In `codex-neuroapi`, run `/debug-config` and confirm the `neuroapi-host` profile and `https://neuroapi.host/v1`.
-- In `claude-neuroapi`, run `/status` and confirm `https://neuroapi.host` plus `apiKeyHelper`.
+- In `codex-neuroapi`, run `/debug-config` and confirm the `neuroapi-host` profile and `https://neuroapi.host/v1/codex`.
+- In `claude-neuroapi`, run `/status` and confirm `https://neuroapi.host/v1/claude-code` plus `apiKeyHelper`.
 - Check current model IDs and pricing at [neuroapi.host/price](https://neuroapi.host/price).
 
-The installer defaults are examples and may drift with provider catalogs.
+Each launcher fetches a fresh catalog scoped to the ordinary NeuroAPI key. Codex uses a private `model_catalog_json`; Claude receives a configured picker. There are no hardcoded default models. Codex 0.147.0+ and Claude Code 2.1.280+ are required. Invalid, empty or unavailable catalogs stop launch instead of restoring stale lists. Organization policies and deliberate CLI overrides retain their documented precedence; these launchers do not support host-managed provider mode.
+
+Recommended server selection as of 2026-09-26: GPT-6 Sol, Astra and Luna for Codex; **Opus 5.5** (`claude-opus-5-5`, preferred), Sonnet 5, Haiku 4.5 and Fable 5.1 for Claude Code. Opus 5.5 becomes the default after publication and key eligibility; otherwise the next available recommendation is selected. Official ID: [Anthropic](https://www.anthropic.com/claude/opus).
 
 ## More
 

README.md

@@ -10,6 +10,14 @@ NeuroAPI — российский AI API-сервис: единый доступ
 
 [English version](README.en.md)
 
+## Совместимость версии
+
+Эта версия создаёт профиль Codex с `https://neuroapi.host/v1/codex` и `supports_websockets = true`, а профиль Claude Code — с `https://neuroapi.host/v1/claude-code`. Выпускайте и распространяйте установщик **только после публикации серверных профилей**: должны пройти авторизованные проверки `GET /v1/codex/models`, HTTP/WebSocket `/v1/codex/responses`, `GET /v1/claude-code/client-settings` и Claude Messages/count_tokens. Подготовленный код не доказывает доступность этих адресов в production; setup намеренно не вызывает API для проверки ключа.
+
+Уже заданный `CODEX_HOME` учитывается для профиля и не изменяется; сохраняйте одинаковое значение при установке, запуске и удалении.
+
+Нужен актуальный Codex с отдельными profile-файлами: `codex --help` должен описывать `--profile` как загрузку `<name>.config.toml`. Старые версии с `[profiles.name]` в общем конфиге обновите перед установкой. Для диагностики WebSocket можно временно поставить `supports_websockets = false` в созданном профиле, сохранив `/v1/codex` и credential helper. Подробнее — [решение проблем](docs/troubleshooting.md).
+
 ## Установка в один запуск
 
 Сначала установите сам [Codex CLI](https://developers.openai.com/codex/cli/) и/или [Claude Code](https://code.claude.com/docs/en/installation), затем создайте API-ключ в [кабинете NeuroAPI](https://neuroapi.host/login?redirect=/dashboard/tokens).
@@ -60,15 +68,15 @@ chmod +x setup-macos.command
 | Получает ключ | command-backed auth helper | `apiKeyHelper` / Keychain helper |
 | Существующие конфиги | не перезаписываются | не перезаписываются |
 
-Установщик не вызывает API и не отправляет ключ в сеть. Сеть используется уже Codex CLI или Claude Code при ваших запросах к `https://neuroapi.host`.
+Установщик не вызывает API и не отправляет ключ в сеть. При запуске `codex-neuroapi` или `claude-neuroapi` запускатель получает актуальный каталог с `https://neuroapi.host`, затем клиент использует API при ваших запросах.
 
 ## Почему ключ не лежит в конфиге
 
 - ключ не принимается аргументом BAT/shell-команды;
 - ключ не сохраняется в `.env`, TOML, JSON или репозитории;
 - Windows шифрует значение через DPAPI без отдельного сохранённого master key;
 - macOS сохраняет значение штатной командой Keychain с интерактивным `-w`;
-- helpers печатают только токен в stdout в момент, когда его запрашивает клиент.
+- helpers печатают только токен в stdout по запросу launcher или клиента.
 
 Это защищает от случайной публикации ключа, но не от вредоносной программы, уже работающей от имени того же пользователя. Полная модель угроз: [docs/security.md](docs/security.md).
 
@@ -95,15 +103,17 @@ Codex CLI:
 
 1. Запустите `codex-neuroapi`.
 2. Выполните `/debug-config`.
-3. Проверьте профиль `neuroapi-host`, provider `neuroapi` и `https://neuroapi.host/v1`.
+3. Проверьте профиль `neuroapi-host`, provider `neuroapi` и `https://neuroapi.host/v1/codex`.
 
 Claude Code:
 
 1. Запустите `claude-neuroapi`.
 2. Выполните `/status`.
-3. Проверьте base URL `https://neuroapi.host` и credential source `apiKeyHelper`.
+3. Проверьте base URL `https://neuroapi.host/v1/claude-code` и credential source `apiKeyHelper`.
+
+При каждом запуске launcher получает актуальный список для вашего обычного ключа NeuroAPI. Codex использует отдельный каталог, Claude Code — настроенное меню; фиксированных моделей в установщике нет. Нужны Codex 0.147.0+ и Claude Code 2.1.280+. При ошибке обновления или пустом списке запуск останавливается, не возвращаясь к старым моделям. Подробности и ограничения managed-политик: [ручная настройка](docs/manual-setup.md).
 
-Примеры используют `gpt-5.6-sol` и `claude-sonnet-4-5`. ID моделей меняются: при `model not found` возьмите точное имя из [каталога NeuroAPI](https://neuroapi.host/price) или `GET /v1/models`.
+Рекомендуемый серверный набор на 26.09.2026: Codex — GPT-6 Sol, Astra и Luna; Claude Code — **Opus 5.5** (`claude-opus-5-5`, приоритетный), Sonnet 5, Haiku 4.5 и Fable 5.1. Opus 5.5 выбирается после публикации модели на сервисе и появления доступа у ключа; до этого используется следующая доступная рекомендация. Официальный ID: [Anthropic](https://www.anthropic.com/claude/opus).
 
 ## Удаление и замена ключа
 

docs/manual-setup.md

@@ -4,21 +4,23 @@
 
 ## Codex CLI
 
-Создаётся отдельный user-level profile:
+Нужен Codex 0.147.0 или новее с profile-v2. Создаётся отдельный user-level profile:
 
 - Windows: `%USERPROFILE%\.codex\neuroapi-host.config.toml`;
 - macOS: `~/.codex/neuroapi-host.config.toml`.
 
+Если `CODEX_HOME` уже задан, обе платформы используют `<CODEX_HOME>/neuroapi-host.config.toml` вместо стандартного пути. Setup не изменяет `CODEX_HOME`; используйте одинаковое значение при установке, запуске и удалении. Доступ к ключу по-прежнему идёт через прежний helper.
+
 Основная конфигурация:
 
 ```toml
-model = "gpt-5.6-sol"
 model_provider = "neuroapi"
 
 [model_providers.neuroapi]
 name = "NeuroAPI"
-base_url = "https://neuroapi.host/v1"
+base_url = "https://neuroapi.host/v1/codex"
 wire_api = "responses"
+supports_websockets = true
 
 [model_providers.neuroapi.auth]
 command = "/absolute/path/to/installer-owned-helper"
@@ -28,26 +30,35 @@ refresh_interval_ms = 300000
 
 На Windows `command` — `powershell.exe`, а helper и DPAPI secret передаются отдельными элементами `args`.
 
-Запуск: `codex --profile neuroapi-host`. Проверка: `/debug-config`.
+Запуск: `codex-neuroapi`. Перед каждым запуском launcher получает `/v1/codex/models` с обычным ключом NeuroAPI, проверяет ответ и передаёт приватный файл через `model_catalog_json` вместе с доступной моделью по умолчанию. Файл удаляется после завершения клиента. Проверка: `/debug-config` и `/model`.
+
+Прямой `codex --profile neuroapi-host` пропускает этот механизм: command-auth discovery может подмешать встроенные модели. При ручной настройке без launcher можно задать собственный проверенный `model_catalog_json`; поддерживать его актуальность тогда нужно самостоятельно.
 
 Project `.codex/config.toml` не подходит для provider/auth redirect: актуальный Codex игнорирует там `model_provider` и `model_providers` по соображениям безопасности.
 
+## HTTP/SSE для диагностики
+
+Если соединение WebSocket блокируется вашей сетью, в секции `[model_providers.neuroapi]` созданного профиля замените `supports_websockets = true` на `supports_websockets = false`. Base URL остаётся `https://neuroapi.host/v1/codex`, auth helper и key storage не меняются. При повторном запуске setup управляемый профиль снова получит настройку по умолчанию `true`.
+
+Если сервер ещё не предоставляет `/v1/codex`, не распространяйте эту версию установщика: сначала требуется согласованный серверный выпуск. Возврат к общему `/v1` не решает несовпадение формата каталога при command-backed auth.
+
 ## Claude Code
 
-Существующий `~/.claude/settings.json` не меняется. Launcher передаёт отдельный installer-owned JSON через `claude --settings <file>`.
+Нужен Claude Code 2.1.280 или новее. Существующий `~/.claude/settings.json` не меняется. Launcher получает `/v1/claude-code/client-settings`, проверяет разрешённые поля данных, добавляет локальный `apiKeyHelper` и передаёт приватный JSON через `claude --settings <file>`.
 
 ```json
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "apiKeyHelper": "/absolute/path/to/installer-owned-helper",
   "env": {
-    "ANTHROPIC_BASE_URL": "https://neuroapi.host",
-    "ANTHROPIC_MODEL": "claude-sonnet-4-5"
+    "ANTHROPIC_BASE_URL": "https://neuroapi.host/v1/claude-code"
   }
 }
 ```
 
-Проверка: `/status`.
+Это локальная основа настроек, а не полный runtime-файл. Сервер добавляет доступную `model`, `availableModels`, семейные defaults, пустой `fallbackModel` и `modelPicker.options` с `replaceBuiltInOptions: true`. Совместимые fallback-модели могут быть разрешены отдельно от меню. Проверка: `/status` и `/model`.
+
+Настройки организации могут иметь более высокий приоритет; режим host-managed provider для этих launchers не поддерживается. Явные пользовательские аргументы остаются явными переопределениями. Меню не заменяет серверные ограничения ключа.
 
 ## Пути Windows
 
@@ -73,7 +84,11 @@ Setup не меняет `.zprofile`, `.zshrc`, `.bash_profile` или систе
 
 ## Модели
 
-`gpt-5.6-sol` и `claude-sonnet-4-5` — текущие defaults этого репозитория, а не бессрочная гарантия каталога. Точный доступ зависит от опубликованных моделей и вашего ключа. Проверяйте [каталог](https://neuroapi.host/price) или `GET https://neuroapi.host/v1/models` со своим ключом.
+Конкретные IDs выбирает сервер из опубликованных моделей с учётом ключа, тарифа и совместимости протокола. В установщике больше нет фиксированной основной модели. Ошибка загрузки, пустой список, неподходящая версия клиента или неверная схема останавливают запуск с понятным сообщением: старый список не используется.
+
+Серверный порядок по умолчанию на 26.09.2026: `claude-opus-5-5`, `claude-sonnet-5`, `claude-haiku-4-5`, `claude-fable-5-1`; для Codex — `gpt-6-sol`, `gpt-6-astra`, `gpt-6-luna`. После публикации Opus 5.5 доступные ключу настройки содержат `model: "claude-opus-5-5"` и `ANTHROPIC_DEFAULT_OPUS_MODEL: "claude-opus-5-5"`. До публикации выбирается первая доступная рекомендация. Opus 5 и 4.8 остаются только совместимыми служебными вариантами вне рекомендуемого меню. Сохранённая администратором настройка каталога имеет приоритет над этим порядком.
+
+Специальный ключ не нужен. Можно подключаться вручную через обычный API: сервер распознаёт известные заголовки Codex/Claude на `/v1/models`. Однако клиент должен сам запросить каталог, а встроенные варианты могут сохраниться. Управляемые launchers — дополнительный способ получить заданное меню, а не условие доступа к API.
 
 ## Официальные контракты