# Справочник инструментов

36 инструментов, сгруппированы по фазам. Общие аргументы:

- `server` — алиас стенда из конфига (по умолчанию `default`). Необязателен.
- `app_id` — идентификатор сервиса (см. `list_applications`).
- `confirm` — `true` для разрушительных операций.

Обозначения: **R** — только чтение; **W** — изменяет; **W!** — изменяет и
требует `confirm="true"`.

## Наблюдение (observe)

| Инструмент | Тип | Аргументы | Что делает |
|---|---|---|---|
| `server_health` | R | — | Живость `config_server` (`GET /health`). |
| `whoami` | R | — | Кто авторизован. |
| `server_info` | R | — | Версия API (capability-probe), адрес, режим `read_only`. Вызывать первым. |
| `list_applications` | R | `include_presence` | Список сервисов с хостами и статусами. |
| `get_application` | R | `app_id` | Детали: compose, версии, env-файлы, журнал миграций. |
| `get_config` | R | `app_id` | Текущие compose и env сервиса. |
| `env_files` | R | `app_id` | Имена текущих env-файлов. |
| `compose_version` | R | `version_id` | Содержимое версии compose. |
| `env_version` | R | `version_id` | Содержимое версии env-файла. |
| `env_versions` | R | `app_id`, `filename` | Все версии конкретного env-файла. |
| `list_tasks` | R | `host_ip`, `status`, `task_type`, `limit` | Задачи агентов (аудит, поиск failed). |
| `get_task` | R | `task_id`, `wait`, `tail`, `output_bytes` | Статус/вывод задачи; `wait=true` ждёт завершения. |
| `get_deployment_files` | R | — | schema, manifest, prebuild_vars, ip_overrides. |
| `ip_match` | R | — | Сопоставление IP схемы и агентов. |
| `release_job` | R | — | Статус фоновой выгрузки релиза. |
| `deployment_tasks` | R | — | Последние release-задачи (sync/start). |
| `stats` | R | — | Счётчики версий compose/env и логов миграций. |
| `service_map` | R | — | Карта хостов и сервисов. |
| `overview` | R | — | Сводка: health, stats, сервисы не в OK, failed-задачи. |
| `release_status` | R | — | Сводка развёртывания: job, задачи, приложения, IP. |

## Конфигурация (configure)

| Инструмент | Тип | Аргументы | Что делает |
|---|---|---|---|
| `set_compose` | W | `app_id`, `content` | Задать compose, создать версию, отправить агенту. |
| `set_env` | W | `app_id`, `filename`, `content` | Задать env-файл, создать версию, отправить агенту. |
| `restore_compose` | W! | `version_id`, `confirm` | Восстановить версию compose. |
| `restore_env_version` | W! | `version_id`, `confirm` | Восстановить версию env-файла. |
| `update_config` | W | `app_id` | Повторно отправить текущий конфиг агенту. |

## Жизненный цикл (operate)

| Инструмент | Тип | Аргументы | Что делает |
|---|---|---|---|
| `deploy` | W | `app_id`, `wait` | `docker-compose up -d`. |
| `restart` | W | `app_id`, `wait` | `down` + `up -d`. |
| `down` | W! | `app_id`, `confirm`, `wait` | `docker-compose down`. |
| `migrate` | W | `app_id`, `wait` | `docker-compose run migration`. |
| `update_front` | W! | `app_id`, `build_dir`, `confirm` | Загрузить сборку фронта (каталог внутри `front_roots`). |

## Развёртывание релиза (release)

| Инструмент | Тип | Аргументы | Что делает |
|---|---|---|---|
| `save_deployment_files` | W | `schema`, `manifest`, `prebuild_vars`, `ip_overrides` | Сохранить файлы развёртывания (только переданные поля). |
| `seed_hosts` | W | — | Создать хосты из schema.json. |
| `fill_vars` | W | — | Заполнить prebuild_vars из схемы. |
| `download_release` | W! | `load_images`, `gitlab_token`, `confirm` | Выгрузить релиз; `load_images=true` — фон. |
| `start_services` | W | — | Создать задачи запуска сервисов по схеме. |

## Обслуживание (maintain)

| Инструмент | Тип | Аргументы | Что делает |
|---|---|---|---|
| `cleanup_old_versions` | W! | `days`, `confirm` | Удалить версии/логи старше N дней. |

## Результаты и ошибки

- Успех — читаемый JSON.
- **Доменная ошибка** (неверный `app_id`, нет confirm, отказ сервера) возвращается
  как результат инструмента с текстом — ассистент видит её и может исправить.
- **Инфраструктурная ошибка** (нет сети) — как ошибка протокола.
- Длинный вывод задачи обрезается (по умолчанию с сохранением хвоста — там
  обычно причина сбоя); `get_task` принимает `output_bytes` и `tail`.