ai_stp

# CLI CLI — рабочая поверхность продукта. Он обнаруживает факты, ведёт паспорта, выбирает состав и просит provider харнесса применить план. Сайт показывает каталог и аккаунт. Нативное состояние harness он не пишет. Каждую команду, которую человек копирует из этого справочника, запускайте с `--json`. CLI печатает ровно один конверт в stdout и больше ничего. ## Как читать конверт При `ok: true` результат в `data`. `warnings` всё равно стоит показать. При `ok: false` `error.code` — стабильный код из закрытого реестра; `next_actions` называет разумную следующую команду, а не разрешение. Не угадывать следующий шаг по классу кода выхода. Повторять вызов только если конверт говорит `retryable: true`. После неподтверждённого таймаута сначала читайте статус, а не повторяйте apply. ## Mutability и confirmation Эти два поля отвечают на разные вопросы. | `mutability` | Смысл | | --- | --- | | `read` | наблюдает; ничего не создаёт | | `plan` | записывает проверяемый план или снимок; target не меняет | | `apply` | меняет состояние | | `destructive` | уничтожает идентичность или управляемые байты; всегда отдельное решение | | `confirmation` | Смысл | | --- | --- | | `none` | лишнего токена нет; это не «можно запускать не спросив» | | `explicit_flag` | передать флаг из дескриптора, обычно `--confirm` | | `plan_digest` | передать `--expected-plan-digest` неизменённого плана | Команда чтения на свежей установке возвращает типизированную пустоту. Она не запускает молча `device init`. ## Machine help — это парсер Повседневное обнаружение: ```bash ai-stp task intents --json ``` Expert: полный реестр этой установки: ```text ai-stp help --agent --json ``` Документация группирует команды, чтобы человек нашёл страницу. Если страница и CLI расходятся, следуйте CLI. Полный список по одной строке на команду — [карта команд](commands.md). ## Группы команд | Группа | Страница | Когда открывать | | --- | --- | --- | | Наблюдение | [Наблюдение](observe.md) | первый запуск, здоровье, machine help | | Конфигурация | [Конфигурация](config.md) | значения, которые эта установка должна соблюдать | | Телеметрия | [Телеметрия установки](telemetry.md) | необязательный анонимный ping установки | | Устройство | [Устройство](device.md) | идентичность этой установки | | Паспорта | [Паспорта](passport.md) | факты разработчика и устройства | | Вход | [Вход](auth.md) | сессия аккаунта и `link web` | | Согласие | [Согласие](consent.md) | непроверенные издатели и major-линии | | Проект | [Проект](project.md) | discover, индекс, символы, паспорт проекта | | Toolchain | [Toolchain](toolchain.md) | управляемые инструменты и обзор harness | | Программа harness | [Программа harness](harness.md) | бинарник harness, не сетап | | Agent Skill | [Agent Skill CLI](skill.md) | skill самого CLI, не kind `skill` | | Реестр | [Реестр](registry.md) | поиск в каталоге, fetch, локальные port | | Компонент | [Команды компонента](component.md) | discover → паспорт → публикация | | Выбор | [Выбор](select.md) | eligibility, proposal, отчёты | | Установка | [Установка](install.md) | intent install; expert recover/resume остаются | | Target | [Target](target.md) | ежедневный статус, diff, backup, именованный rollback | | Setup | [Команды сетапа](setup.md) | compose, импорт, update, публикация | | Provider | [Provider](provider.md) | бинарник, который пишет нативное состояние | | Синхронизация | [Синхронизация](sync.md) | частный поток аккаунта | | Доступ | [Доступ](grant.md) | доступ к major-линии | | Жалобы | [Жалобы](report.md) | закрытые жалобы | | Owner | [Owner](owner.md) | серверные объекты, которыми вы владеете | | Publication | [Publication](publication.md) | attest, plan, confirm | | Eval | [Eval](eval.md) | локальная эталонная оценка | ## Рабочий цикл ```text task intents --json → task start --intent <shipped> --idempotency-key <key> --json → follow continuations (исполнять argv только когда actor равен cli) → сообщить payload verification ``` Expert leaves (`install plan` / `approve` / `apply`) остаются для recovery. Повседневные install, change и switch сливают эти шаги in-process под соответствующим intent. Агент пропускает шаг, только если предыдущий конверт уже сделал его ненужным. Механическую проверку он не пропускает. ## Чего CLI не делает - не вызывает model API и не просит ключ модели; - не пишет target harness сам — это делает только public provider; - не кладёт секреты, тела `.env` и токены в паспорт; - не считает `author_verified` доказательством безопасности версии компонента. ## Типичные отказы | Что видно | Что это значит | Что делать | | --- | --- | --- | | мутирующая команда без `--json` | в stdout смешался человеческий текст | добавить `--json` и читать один конверт | | stale plan | байты плана изменились | построить новый план, показать, подтвердить снова | | нет confirmation | требовался `explicit_flag` или `plan_digest` | прочитать дескриптор; не выдумывать имя флага | | команды нет в machine help | этой установки её нет | остановиться; не подменять похожей командой | Первый запуск связным текстом — [Быстрый старт для человека](../quickstart/human.md). Ритуал сессии для агента — [Быстрый старт для ИИ-агента](../quickstart/agent.md).