@agfpd/iapeer 0.2.98 → 0.3.0

package/docs/ru/07-/321/203/321/201/321/202/320/260/320/275/320/276/320/262/320/272/320/260-/320/270-/320/276/320/261/320/275/320/276/320/262/320/273/320/265/320/275/320/270/320/265.md

@@ -0,0 +1,87 @@
+# 07 — Установка и обновление
+
+**Русский** · [English](../07-install-and-update.md)
+
+Установка — два шага: разложить ядро и подготовить хост. Демон поднимать вручную не нужно — это делает онбординг. Ниже — оба шага, плюс обновление ядра и откат.
+
+## Что нужно заранее
+
+- **macOS.** Процессами управляет launchd — другой платформы пока нет.
+- **[bun](https://bun.sh)** на `PATH`. Ядро исполняется через bun; скомпилированного JS в пакете нет.
+- **`~/.local/bin` на `PATH`.** Сюда ставится бинарь `iapeer`. Нет в `PATH` — команда не найдётся после установки.
+- **Хотя бы один агентский рантайм** — Claude Code или Codex CLI. Без него `iapeer create` и `iapeer init` откажут с явной ошибкой.
+
+## Шаг 1. Установите ядро
+
+```bash
+npx @agfpd/iapeer
+```
+
+Запуск без аргументов выполняет установку. Она делает ровно три вещи:
+
+1. **Раскладка.** Создаёт `~/.iapeer/` со всеми каталогами: реестр, состояние, логи, кеш, пространства рантаймов.
+2. **Бинарь.** Собирает `iapeer` и атомарно кладёт в `~/.local/bin/iapeer`. Прежняя версия остаётся рядом как `iapeer.prev` — резерв для отката. Атомарность важна: между старой и новой версией нет момента, когда по пути лежит пустышка.
+3. **Плист демона.** Пишет `~/Library/LaunchAgents/com.agfpd.iapeer.plist`, но **не загружает** его. Загрузку берёт на себя `iapeer onboard` (шаг 2): на работающем хосте демон уже может крутиться, и миграция на новый бинарь — осознанное действие, а не побочный эффект установки.
+
+При установке однократно создаётся локальная подпись бинаря (для разрешений macOS). Подпись стабильна и переживает обновления.
+
+Установка идемпотентна — повторный запуск безопасен.
+
+Та же операция доступна как `iapeer install`, если бинарь уже стоит. Но самый первый раз — всегда через `npx` или из исходников: скомпилированный бинарь не умеет пересобирать сам себя.
+
+## Шаг 2. Подготовьте хост
+
+```bash
+iapeer onboard
+```
+
+`onboard` готовит хост к появлению агентов. Первым делом он **поднимает демон** — загружает плист в launchd, дальше launchd держит демон сам, поднимая его заново при падении и перезагрузке. Отдельная команда `launchctl` для этого не нужна. Затем onboard регистрирует marketplace расширений в Claude и Codex, разворачивает планировщик (`notifier`), создаёт пир-человека в Telegram и ставит провайдера памяти. Старт демона идёт всегда; остальные шаги включены по умолчанию и отключаются флагами (`--no-notifier`, `--no-telegram`, `--no-memory`).
+
+Проверьте, что демон жив и хост готов:
+
+```bash
+iapeer status
+```
+
+Вы увидите версию ядра, здоровье демона и состояние слота памяти. Код возврата ненулевой, если демон нездоров, — это удобно для скриптов-проверок.
+
+Разбор каждого шага onboard — в [02 — Быстрый старт](02-быстрый-старт.md); рантаймы и память подробно — в [09](09-рантаймы.md) и [11](11-расширения-и-память.md).
+
+## Обновление ядра
+
+```bash
+iapeer update            # до последней версии
+iapeer update 0.2.80     # до конкретной версии
+iapeer update --force    # переустановить, даже если версия уже стоит
+```
+
+Обновление тянет версию ядра из npm и перезапускает демон на неё. По шагам:
+
+1. Узнаёт нужную версию из npm. Если установленная уже совпадает и нет `--force` — ничего не делает.
+2. Скачивает и собирает новый бинарь. Это делается через `npm pack`, а не `npx`: бинарь не пересобирает себя сам.
+3. Перезапускает демон на новый бинарь.
+4. Перезапускает launchd-джобы инфраструктуры, которыми владеет ядро (`com.iapeer.*` — роутеры `timer`, `watcher`, Telegram), переводя их на только что заменённый бинарь. Их плисты запускают тот же бинарь ядра, что и демон, — без перезапуска джоб остался бы на старом коде. Перезапускается именно джоб (снимается и поднимается заново); **пакетный код** рантаймов (telegram-runtime, notifier-runtime) при этом не обновляется — это отдельная операция `update-runtime`. Провайдер памяти (`iapeer-memory`) и плисты обычных пиров не трогаются вовсе. Если демон на шаге 3 не поднялся, этот шаг пропускается — нет смысла переводить джобы на бинарь, на котором демон не ожил.
+5. Проверяет, что демон действительно поднялся здоровым, — не по тому, что команда перезапуска завершилась успешно, а пробой: подключается к сокету демона (тому самому, что демон открывает прямо перед сигналом готовности). Здоровым демон считается, только когда сокет принимает соединение **дважды подряд** — одиночная проба прошла бы и у демона, который привязал сокет и тут же упал. На проверку отведено 15 секунд; если за это время серия успешных проб не набралась — команда говорит об этом прямо и советует откатиться.
+
+Обновление трогает **только ядро**. Плист демона и сторонние пакеты остаются как есть.
+
+Указать конкретную версию (`iapeer update <версия>`) полезно, когда нужно откатиться глубже, чем на один шаг назад, или встать на проверенную версию.
+
+## Откат
+
+```bash
+iapeer rollback
+```
+
+Восстанавливает предыдущий бинарь (тот самый `iapeer.prev`), перезапускает демон на него и проверяет здоровье. Откат идёт **на один уровень назад** — хранится одна предыдущая версия. Это локальное «отменить последнее обновление», пока в npm выкладывают исправленную версию. Если нужно встать на версию глубже — `iapeer update <версия>`.
+
+## Если демон не поднялся после обновления
+
+Признак — `iapeer status` показывает нездоровый демон, или `update` завершился с предупреждением. Порядок действий:
+
+```bash
+iapeer rollback                         # вернуться на прежний бинарь
+# если демон всё ещё лежит — поднять вручную:
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agfpd.iapeer.plist
+iapeer status                            # убедиться, что ожил
+```

package/docs/ru/08-/321/203/320/277/321/200/320/260/320/262/320/273/320/265/320/275/320/270/320/265-/320/277/320/270/321/200/320/260/320/274/320/270.md

@@ -0,0 +1,119 @@
+# 08 — Управление пирами
+
+**Русский** · [English](../08-peer-management.md)
+
+Повседневные операции с пирами. Полные сигнатуры команд с флагами — в [12 — CLI](12-cli-reference.md); здесь — когда и зачем применять каждую.
+
+## Создание пира: create и init
+
+Создать пир можно двумя командами, и разница между ними — в том, откуда берётся рабочая папка.
+
+**`iapeer create <имя>`** создаёт пир из любого места. Команда сама выбирает папку (по умолчанию `~/.iapeer/peers/<имя>`, или укажите `--path`), разворачивает её и инициализирует. Это основной способ.
+
+```bash
+iapeer create assistant --runtime claude
+iapeer create reviewer --runtime codex --description "Ревью кода и архитектуры"
+iapeer create helper --path ~/projects/helper --runtime claude
+```
+
+**`iapeer init`** превращает в пир текущую (или указанную) папку. Это удобно, когда у пира уже есть своя папка проекта и хочется, чтобы `.iapeer/` появился прямо в ней.
+
+```bash
+cd ~/projects/myagent
+iapeer init
+```
+
+Имя пира берётся из имени папки (нормализованный `basename` — `myagent`); отдельного флага для имени нет — чтобы пир назывался иначе, переименуйте папку. Рантайм определяется автоматически из установленных (Claude/Codex), при необходимости задаётся флагом `--runtime`.
+
+По сути `create` — это «выбрать/создать папку, затем `init`». Обе команды выполняют одно и то же наполнение пира:
+
+- пишут профиль `peer-profile.json`;
+- заносят пир в реестр;
+- настраивают подключение к демону по MCP (так агент получит `send_to_peer`);
+- создают файл доктрины `IAPEER.md` для наполнения;
+- если занят слот памяти — подключают общую память и проводят связанную с этим настройку рантайма.
+
+Защита от затирания: если в целевой папке уже живёт другой пир (с другим именем в профиле), команда откажет, а не перезапишет.
+
+Флаг `--no-bootstrap` создаёт пир, не запуская его службу (актуально для инфраструктурных пиров, которые иначе сразу поднимаются под launchd).
+
+## Обзор пиров: list
+
+```bash
+iapeer list           # таблица
+iapeer list --json    # машинно-читаемый формат
+```
+
+Каждая строка — пир, его рантаймы и состояние каждого: `●` живой, `○` спит, `✕` остановлен. Если запустить в интерактивном терминале, `list` открывает панель управления (стрелки для навигации, Enter — присоединиться, `/` — поиск, `q` — выход); в неинтерактивном режиме или с `--json` печатает таблицу для скриптов.
+
+## Проверка целостности: verify
+
+```bash
+iapeer verify          # отчёт о расхождениях
+iapeer verify --fix    # починить
+```
+
+`verify` проверяет две вещи: соответствие профилей стандарту и расхождения между реестром и локальными профилями. С `--fix` команда самовосстанавливает реестр из профилей (и попутно мигрирует профили со старого формата поля рантайма на актуальный). Это штатный способ привести реестр в порядок, если он рассинхронизировался.
+
+## Остановка и запуск: stop, start
+
+```bash
+iapeer stop assistant          # остановить
+iapeer start assistant         # снять остановку
+iapeer stop --all              # остановить всех пиров
+iapeer start --all             # снять остановку со всех
+```
+
+Поведение зависит от класса рантайма:
+
+- **Агент claude/codex.** `stop` ставит стойкий стоп-флаг и закрывает сессию — демон не будит пир, пока не выполнят `start`. `start` снимает флаг: пир снова можно разбудить, но **сессия не запускается сразу** — демон поднимет её при первом сообщении.
+- **Инфраструктурный пир.** `stop` снимает службу с launchd, `start` загружает обратно.
+
+Можно адресовать конкретный рантайм: `iapeer stop assistant codex`.
+
+## Безусловный перезапуск: new
+
+```bash
+iapeer new assistant
+```
+
+`new` — аварийный рычаг для зависшей или мёртвой сессии. В отличие от мягкого пути (когда живой агент сам читает команду и перезапускается), `new` действует механически, в обход агента: чисто сносит текущую сессию и поднимает свежую. Команда возвращает успех только тогда, когда свежая сессия действительно поднялась и готова. Это спасение для случая, когда агент завис настолько, что не читает ничего.
+
+## Ленивый мягкий перезапуск: refresh
+
+```bash
+iapeer refresh assistant         # пометить пира на свежий старт при следующем пробуждении
+iapeer refresh --all             # пометить все пиры
+```
+
+`refresh` — отложенный рычаг для случая «обновилась доктрина, хочу, чтобы команда её перечитала, но без рывка». Он **только ставит маркер**: не убивает живую сессию, не будит спящих, не делает немедленный перезапуск. Эффект наступает сам собой — на **следующем естественном пробуждении** пира (после штатного усыпления за простой, или на следующем сообщении спящему): вместо продолжения прежнего диалога поднимется свежая сессия, которая перечитает доктрину и фрагменты с диска.
+
+Зачем отдельно от `new`: `new` — немедленный и жёсткий (рвёт текущую работу), а массовый `new --all` поднял бы разом всю команду. `refresh` — ленивый и мягкий: живую работу не трогает, всплеска пробуждений нет, свежесть приходит к каждому пиру в его обычный момент подъёма. Маркер перекрывает «продолжение» для **всех** типов пиров, в том числе людей-в-Telegram, которые иначе продолжают старую сессию до явного `/new`. Роутеры (notifier/telegram) и absent-рантаймы пропускаются — у них нет доктрины. Применять `refresh` — осознанный шаг оператора (например после релиза обновлённой доктрины), а не автоматический побочный эффект.
+
+## Удаление: remove
+
+```bash
+iapeer remove assistant          # удалить запись из реестра
+iapeer remove assistant --force  # удалить, даже если пир сейчас живой
+```
+
+`remove` удаляет запись пира из реестра. Важные свойства:
+
+- **Папку пир не удаляет.** Данные пира (его `.iapeer/`, история, память) остаются на диске — `remove` чистит только запись в реестре. Если папка была одноразовой, удалите её сами.
+- **Отказывает живому пиру.** Удалить запись работающего пира — значит оторвать его сессию от маршрутизации. Команда откажет, пока пир жив; обойти можно флагом `--force`, но честнее сначала остановить.
+- **Идемпотентно.** Удаление несуществующего пира — не ошибка, а успешный ноль.
+
+Типичное применение — подчистить «зомби»-записи, оставшиеся от завершившихся одноразовых пиров.
+
+## Присоединение к сессии: attach
+
+```bash
+iapeer attach assistant
+iapeer attach assistant codex    # конкретный рантайм
+```
+
+`attach` поднимает пир, если тот спит, продолжает его прежний диалог и открывает его сессию под супервизором прямо в вашем терминале — как обычную консоль. Отсоединиться — сочетанием `Ctrl-]` или просто закрыть терминал; сессия в любом случае продолжает работать в фоне, а `iapeer attach` снова подключит вас, когда понадобится.
+
+## Граница: чужой launchd неприкосновенен
+
+Команды `stop`, `start`, `new` **отказываются трогать пиров, которыми управляет чужой launchd-плист** (например, действующие пиры под отдельным менеджером жизненного цикла). Для таких пиров ядро — только читатель: вмешательство означало бы драку с launchd за управление процессом. Это сознательная защита, а не ограничение — она не даёт ядру случайно сломать то, чем владеет не оно.

package/docs/ru/09-/321/200/320/260/320/275/321/202/320/260/320/271/320/274/321/213.md

@@ -0,0 +1,103 @@
+# 09 — Рантаймы
+
+**Русский** · [English](../09-runtimes.md)
+
+Рантайм — способ присутствия пира. Ядро знает четыре: `claude`, `codex`, `telegram`, `notifier`. Первые два — AI-агенты, вторые два — инфраструктурные роутеры.
+
+## Агентские рантаймы: claude, codex
+
+Демон поднимает агента на входящее сообщение в сессии под pty-супервизором и закрывает её после часа простоя. Системный промпт ([05](05-системный-промпт.md)) подменяется штатным механизмом рантайма.
+
+**Claude** запускается с флагом `--system-prompt-file`, который заменяет встроенный системный промпт собранным iapeer текстом. Продолжение диалога идёт через `--continue` (берётся последняя сессия), не через выбор сессии по идентификатору. История диалога лежит в `~/.claude/projects/<папка>/*.jsonl`.
+
+**Codex** получает промпт настройкой `model_instructions_file` (`codex -c model_instructions_file=<файл>`), которая подменяет компилированные базовые инструкции. Продолжение — `codex resume --last`. История — в `~/.codex/sessions/`. Подключение к демону по MCP у Codex идёт через токен-заголовок: Codex закрывает HTTP-MCP за проверкой токена, поэтому ядро подставляет нерабочий «пустой» токен (он не несёт защитной функции), а демон узнаёт пир по заголовку `X-IAPeer-Identity`.
+
+При настройке Codex ядро host-wide гасит стартовый диалог проверки обновлений (`check_for_update_on_startup = false` в `config.toml`). Интерактивное «доступно обновление, нажмите Enter» — это шлагбаум на загрузке: разбуженная демоном headless-сессия Codex зависла бы на нём, не дойдя до готовности, пока к ней не подключится человек. Обновления Codex остаются ручными (`codex update` либо brew), а не вопросом на старте. Уже выставленное оператором значение ключа ядро не переписывает.
+
+Запустить агента в текущей папке вручную, свежей сессией:
+
+```bash
+iapeer claude     # поднять пир текущей папки в Claude
+iapeer codex      # в Codex
+```
+
+Тонкие флаги запуска для конкретной пары пир+рантайм задаются в `<папка>/.iapeer/runtimes/<рантайм>/launch.env` ([06](06-хранение.md)).
+
+### Какой рантайм выбирается при создании пира
+
+Когда пир создаётся (`create` / `init`), основной рантайм определяется по слоям:
+
+1. Явный `--runtime` — берётся он, но сначала проверяется, что рантайм установлен; если нет, команда завершается внятной ошибкой, а не принимает несуществующий рантайм молча.
+2. Иначе — маркер в папке (`.claude` / `.codex`): папка, уже сконфигурированная под рантайм, сохраняет его. Маркер в приоритете и на установленность не перепроверяется.
+3. Иначе — из установленных на хосте: ровно один установлен — он; ни одного — внятная ошибка (а не тихий Claude на хосте без рантайма); установлены оба — по умолчанию Claude (выбрать Codex явно — `--runtime codex`).
+
+Установленность рантайма ядро определяет по его лаунчеру — переменная `IAPEER_<РАНТАЙМ>_BIN`, нативное расположение установщика, затем `PATH` — и по глобальному каталогу конфигурации (`~/.claude` / `~/.codex`).
+
+## Инфраструктурные рантаймы: telegram, notifier
+
+Это долгоживущие процессы-роутеры, не AI. Работают постоянно под launchd; демон их не поднимает и не усыпляет.
+
+**telegram** — мост Telegram ↔ пиры. Требует, чтобы пир был природы `natural` (человек): попытка завести Telegram-присутствие у AI-агента отклоняется. Запускается как `telegram-runtime run`.
+
+**notifier** — планировщик. Разворачивает служебных пиров `timer` (срабатывает по расписанию) и `watcher` (следит за событиями). Запускается как `notifier-runtime run`.
+
+Плисты инфраструктурных пиров, в отличие от плиста демона, **загружаются автоматически** при `iapeer create --runtime telegram|notifier` и при `iapeer onboard` (если не передан `--no-bootstrap`). Поэтому отдельный `launchctl bootstrap` для них не нужен.
+
+## Несколько рантаймов у пира
+
+В профиле пира два поля про рантаймы: `runtimes` (все, на которых пир может присутствовать) и `default_runtime` (основной — куда маршрутизируются сообщения и какой поднимается первым). Расширить возможности и переключить основной рантайм — разные команды.
+
+### add-runtime — добавить рантайм
+
+```bash
+iapeer add-runtime codex --peer assistant   # одному пиру
+iapeer add-runtime codex --all              # всем пирам
+```
+
+Добавляет агентский рантайм существующим пирам: дописывает его в `runtimes`, разворачивает пространство рантайма и проводит полную настройку для Codex (предварительное доверие к папке, рычаг родной памяти, подключение памяти, MCP). `default_runtime` команда **не трогает** — это расширение возможностей, не смена маршрутизации. Идемпотентна. Инфраструктурные пиры пропускаются: добавить им агентский рантайм — решение оператора через `create`, а не массовая операция.
+
+### default-runtime — переключить основной
+
+```bash
+iapeer default-runtime codex --peer assistant   # одному
+iapeer default-runtime codex --all              # все пиры
+```
+
+Переключает основной рантайм — куда идёт маршрутизация и какой рантайм поднимается первым. Массовое переключение `--all` — это и есть «пересадка» всей команды с одного агентского рантайма на другой; обратно симметрично (`default-runtime claude --all`). Команда откажет, если пир не объявляет этот рантайм (сначала `add-runtime`), и пропустит инфраструктурных. Реестр чинится в той же команде, поэтому маршрутизация переключается сразу.
+
+## Подключение Telegram: connect
+
+```bash
+iapeer connect telegram assistant --token <токен-бота>
+```
+
+Подключает Telegram-бота к пиру за один проход: регистрирует бота, прописывает его в профиль пира, перезапускает роутер. От человека нужен только токен (у `@BotFather`). После — отправьте боту **первое сообщение**: Telegram не позволяет боту начать чат первым, поэтому канал оживёт только после входящего от человека.
+
+Команда идемпотентна, и поведение зависит от токена. **Тот же токен** — чистый no-op: файл учётных данных бота не меняется, живой роутер уже работает на этих данных, перезапуска нет. **Новый или изменённый токен** требует перезапуска роутера (учётные данные читаются только при старте) — это секундная пауза в доставке для всех Telegram-пиров; входящие при этом не теряются (long-polling помнит смещение, Telegram держит сообщения до 24 часов). Неверный токен отсекается сразу, с дословной причиной от Telegram.
+
+## Рантайм-пакеты
+
+Инфраструктурные рантаймы поставляются отдельными npm-пакетами (`*-runtime`). Ставит и обновляет их ядро:
+
+```bash
+iapeer install-runtime notifier        # установить пакет + развернуть его пиров
+iapeer update-runtime notifier         # обновить с перезапуском пиров
+iapeer update-runtime --all            # обновить все рантайм-пакеты
+```
+
+`install-runtime` ставит пакет и разворачивает объявленный им набор пиров (notifier разворачивает `timer` и `watcher`); флаг `--no-bootstrap` ставит пакет, не загружая его пиров в launchd. Рантайм без объявленного набора (telegram) — это режим «добавляет оператор»: пиров заводят вручную через `iapeer create <имя> --runtime telegram`.
+
+### Деплой рантайм-пакета: всегда из облака, как `iapeer update`
+
+Доставка рантайм-пакета следует тому же разделению **release ≠ deploy**, что и ядро (см. [07 — Установка и обновление](07-установка-и-обновление.md)). `iapeer update-runtime <рантайм>` — это рантайм-аналог `iapeer update`: деплой на хост **из облака (npm)**, а не из локального рабочего дерева. Он:
+
+1. **version-gate** — сверяет npm-latest с `version`-штампом манифеста (`~/.iapeer/runtimes/<рантайм>/runtime.json`); установлен latest → no-op (`already-latest`). Без штампа гейт пропускается, переустановка идёт идемпотентно (и сообщает об этом) — поэтому штамповать `version` в манифест обязанность пакета (иначе ломается и `update-runtime`-гейтинг, и наблюдаемость версии в `iapeer status` и аудите версий по пирам).
+2. **re-install** — форс-`npx @agfpd/<рантайм>-runtime`: **тянет пакет из npm** и даёт ему self-deploy'ить новый бинарь + манифест. Источник — опубликованный пакет, **не** рабочее дерево.
+3. **re-provision** — идемпотентно тем же путём, что `install-runtime` (sync описаний, re-self-config; живые пиры не клоббятся).
+4. **restart** — перезапускает зарегистрированных пиров рантайма обычными `stop`/`start`. Они **host-aware**: пир под супервизором корректно гасится (kill супервизора и ребёнка) и поднимается заново на новом бинаре — отдельная процедура не нужна.
+
+Соответственно, **локальный self-install из рабочего дерева — это dev-проба, а не деплой** (аналог запуска ядра из исходников `bun src/...`). Деплоить рантайм надо из облака: сначала release (`npm publish` — в облако, живые хосты не трогает), затем deploy (`update-runtime` — pull из облака + перезапуск). Обход npm (активация локального кода через self-install) рассинхронизирует npm и хост и невоспроизводим на новом хосте: чистый хост поднимает рантайм только из npm (`install-runtime`, далее `update-runtime`). Ядро (`iapeer update`) сознательно НЕ трогает рантайм-пакеты — симметрия намеренная.
+
+Путь к лаунчеру рантайма по умолчанию резолвится из `PATH`; переопределить его (например для launchd с минимальным `PATH`) можно переменными `NOTIFIER_RUNTIME_BIN` / `TELEGRAM_RUNTIME_BIN` — см. [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md).
+
+Контракт рантайм-пакета — формат манифеста, обязанности, команды — в [13 — Архитектура и контракт](13-архитектура-и-контракт.md).

package/docs/ru/10-/320/276/320/261/320/274/320/265/320/275-/321/201/320/276/320/276/320/261/321/211/320/265/320/275/320/270/321/217/320/274/320/270.md

@@ -0,0 +1,69 @@
+# 10 — Обмен сообщениями
+
+**Русский** · [English](../10-messaging.md)
+
+Пиры обмениваются сообщениями по протоколу IAP. Агенты делают это инструментом `send_to_peer`, оператор — командой `iapeer send`. Оба пути ведут через один и тот же роутинг демона.
+
+## Два способа отправить
+
+**`send_to_peer`** — MCP-инструмент, который получает каждый агент claude/codex (через подключение к демону). Это основной канал между агентами.
+
+```text
+send_to_peer(personality="assistant", message="...", topic?, attachments?)
+```
+
+**`iapeer send`** — отправка из командной строки, тот же путь доставки в обход агентской сессии (работает, даже когда HTTP-слушатель демона недоступен):
+
+```bash
+iapeer send assistant --message "текст"
+iapeer send assistant --message-file ./report.md       # тело из файла; '-' = stdin
+iapeer send assistant --message "см. вложение" --attachment ./report.pdf
+iapeer send assistant --message "..." --topic "релиз" --from claude-reviewer
+```
+
+Флаг `--from` задаёт отправителя (`<рантайм>-<имя>`); по умолчанию — идентичность пира текущей папки. `--attachment` повторяемый. `--message-file` с телом из файла или stdin удобен для длинных и многострочных сообщений.
+
+## Путь доставки
+
+Демон находит получателя в реестре и смотрит на его состояние:
+
+- **живой** — демон пишет сообщение в сессию пира через сокет супервизора на ввод сессии. Демон ждёт подтверждения, что ввод принят (поле ввода очистилось); ответ — `доставлено`.
+- **занят** (агент в середине хода, поле ввода не пустое) — сообщение встаёт в очередь композера и доставляется, как только агент освободится; ответ отправителю — `в очереди`. Очередь ждёт до 120 секунд, потом досылает принудительно.
+- **спит** — демон поднимает сессию, перепроверяет получателя, доставляет; ответ — `доставлено, разбудил`.
+- **остановлен** — демон отказывает и сообщает отправителю прямо.
+
+Ключевая гарантия: `доставлено` означает, что сообщение действительно легло в живую сессию (демон дождался подтверждения), а не просто было отправлено в пустоту. Если сессия не подтвердила приём в отведённое время, демон считает её мёртвой и не лжёт об успехе.
+
+В конверте каждого сообщения едет природа отправителя (`intelligence`) — получатель знает, пишет ему человек, агент или служебный процесс.
+
+## Ограничения сообщения
+
+У протокола есть пределы: тело сообщения — до 16000 символов, тема — до 200, вложений — до 20 за раз. Сообщение сверх лимита нужно разбивать или передавать содержимое файлом-вложением.
+
+## Отправка в Telegram только со своим ботом
+
+Пир не может слать сообщения в Telegram-домен, если у него нет привязанного Telegram-бота. Это защита: ответ человеку уходит через бота конкретного агента, и пир без такой привязки в Telegram не пишет — доставка ему отказывается. Привязка делается командой `iapeer connect telegram` (см. [09 — Рантаймы](09-рантаймы.md)).
+
+## Контрольные команды
+
+Контроль сессии идёт отдельным каналом от сообщений — это не текст в диалог, а управляющее воздействие:
+
+```bash
+iapeer interrupt assistant     # прервать текущий ход (Escape), контекст цел
+iapeer compact assistant       # сжать диалог
+```
+
+`interrupt` останавливает зашедший не туда или зависший ход, не теряя контекст. `compact` сжимает диалог; если пир спит после чистого усыпления, демон сначала продолжит диалог, потом сожмёт, а для пустой сессии честно ответит, что сжимать нечего.
+
+Отдельно стоят **алиасы** — шорткаты вида `/alias-new`, `/alias-compact`, заданные в профиле пира. Это не контроль, а заготовки текста: рантайм разворачивает алиас в полный текст и доставляет его пиру как обычное сообщение. Так оператор одной короткой командой запускает заранее прописанный сценарий (например, «сохрани состояние в память и перезапустись свежим»).
+
+## Эфемерные воркеры
+
+Пир с политикой пробуждения `wake_policy: "ephemeral"` в профиле работает иначе обычного агента — он предназначен для одноразовых задач:
+
+- **всегда свежий.** Каждая задача поднимает свежую сессию, без продолжения прошлого диалога.
+- **очередь по одной.** Задачи такому пиру не доставляются в живую сессию параллельно — они выстраиваются в durable-очередь (переживает перезапуск демона) и обрабатываются строго по одной. Демон докармливает очередь на надзорных тиках.
+- **завершение после ответа.** Отправив свой единственный ответ, воркер помечается на тихое сворачивание: окно тишины (по умолчанию 20 секунд) — и демон закрывает сессию, никого не будя. Если воркер молчит и не отвечает, страховочный предел (по умолчанию 600 секунд) всё равно его свернёт.
+- **`iapeer self-done`** — самовызов воркера, которому нечего отправить: освобождает очередь под следующую задачу, не разбудив никого. Доктрина «нечего отправлять — `self-done` вместо пустого ответа».
+
+Эта модель держит поток одноразовых задач упорядоченным: один воркер на задачу, без накопления параллельных сессий, без пустых пробуждений адресата.

package/docs/ru/11-/321/200/320/260/321/201/321/210/320/270/321/200/320/265/320/275/320/270/321/217-/320/270-/320/277/320/260/320/274/321/217/321/202/321/214.md

@@ -0,0 +1,60 @@
+# 11 — Расширения и память
+
+**Русский** · [English](../11-extensions-and-memory.md)
+
+Возможности пира расширяются двумя видами пакетов: capability-плагины (способности — инструменты, контекст) и рантайм-пакеты (способы присутствия). Память — отдельный механизм: один провайдер на хост через слот. Этот раздел — как этим пользоваться; контракт для разработчиков пакетов — в [13 — Архитектура и контракт](13-архитектура-и-контракт.md).
+
+## Capability-плагины: enable
+
+Плагин добавляет пиру способность, не будучи рантаймом, — общую память, синтез речи, набор навыков. Подключение:
+
+```bash
+iapeer enable peer-voice assistant      # подключить плагин пиру
+iapeer enable iapeer-memory             # пиру текущей папки
+iapeer enable peer-voice assistant --no-setup   # без шага установки плагина
+```
+
+Команда ставит плагин на каждом агентском рантайме пира (для Claude — в область проекта внутри папки пира, для Codex — в общий конфиг хоста), включает его и, если плагин объявляет шаг установки, выполняет его. Операция идемпотентна и не мешает другим пирам: для Claude привязка идёт по папке конкретного пира.
+
+Локальный снимок marketplace у рантайма может отставать: плагин, зарегистрированный в marketplace уже после последней синхронизации хоста, до неё читается как «неизвестный плагин». Поэтому, если установка с первого раза не прошла, `enable` обновляет снимок marketplace рантайма (Claude — `marketplace update`, Codex — `marketplace upgrade`) и повторяет попытку один раз.
+
+## Слот памяти
+
+Память в iapeer — first-class опция, не встроенная функция. Её даёт **провайдер памяти** — отдельный пакет, занимающий единственный на хост слот. Слот либо занят ровно одним провайдером, либо пуст; пустой слот — нормальное состояние.
+
+Провайдер по умолчанию ставится при онбординге:
+
+```bash
+iapeer onboard                       # ставит провайдера по умолчанию, если слот пуст
+iapeer onboard --memory <пакет>      # указать другого провайдера
+iapeer onboard --no-memory           # оставить слот пустым
+```
+
+Состояние слота показывает `iapeer status` — имя провайдера, версия и свежесть его демона (или `none`, если слот пуст).
+
+Эталонный провайдер — **iapeer-memory** (`@agfpd/iapeer-memory`), он же ставится по умолчанию. Это общая память команды: канон знаний (знания, решения, идеи, проекты, списки) и личная оперативка каждого агента, с поиском по содержимому и графу связей. Память доезжает агенту двумя путями — карта его заметок попадает в системный промпт слоем фрагментов ([05 — Системный промпт](05-системный-промпт.md)), а читает и пишет он через MCP-инструменты провайдера. Подробности — в собственной документации iapeer-memory.
+
+Когда слот занят, ядро на стыках жизни пира зовёт команды провайдера: при рождении пира (`birth`) — настроить ему память, при удалении (`remove`) — свернуть. Формат манифеста провайдера, команды и моменты вызова — в [13](13-архитектура-и-контракт.md).
+
+### Родная память рантайма
+
+У Claude и Codex есть собственная встроенная память. Когда слот занят провайдером, держать параллельно ещё и родную память рантайма вредно — копится второй, никем не курируемый набор. Поэтому при рождении пира с занятым слотом ядро автоматически отключает родную память его рантаймов.
+
+Управлять этим вручную:
+
+```bash
+iapeer native-memory off --peer assistant   # отключить родную память
+iapeer native-memory on --peer assistant     # вернуть как было
+iapeer native-memory off --all               # по всем пирам
+```
+
+## Рантайм-пакеты
+
+Способы присутствия (Telegram, планировщик) поставляются рантайм-пакетами:
+
+```bash
+iapeer install-runtime notifier      # установить + развернуть объявленных пиров
+iapeer update-runtime --all          # обновить все рантайм-пакеты
+```
+
+`install-runtime` ставит пакет и разворачивает объявленный им набор пиров (notifier — `timer` и `watcher`). Рантайм без объявленного набора (telegram) заводит пиров оператор через `iapeer create … --runtime telegram`. Подробности подключения Telegram — [09 — Рантаймы](09-рантаймы.md); контракт рантайм-пакета — [13](13-архитектура-и-контракт.md).

package/docs/ru/12-cli-reference.md

@@ -0,0 +1,96 @@
+# 12 — CLI
+
+**Русский** · [English](../12-cli-reference.md)
+
+Полный перечень команд `iapeer <команда>`. Общие правила: `--help` / `-h` в любом месте строки печатает справку и ничего не выполняет; флаги принимают форму `--key value` и `--key=value`.
+
+## Установка и обслуживание ядра
+
+| Команда | Что делает |
+|---|---|
+| `install` | Bootstrap ядра: собрать бинарь `~/.local/bin/iapeer`, создать раскладку `~/.iapeer/`, записать плист демона (без загрузки). |
+| `update [версия] [--force]` | Обновить ядро из npm, перезапустить демон, перезапустить инфра-службы ядра. Без аргумента — до последней версии; с версией — до точной. `--force` переустанавливает даже при совпадении версий. |
+| `rollback` | Вернуть предыдущий бинарь (`.prev`), перезапустить демон, проверить здоровье. На один уровень назад. |
+| `version` · `--version` · `-v` | Версия установленного бинаря. |
+| `help` · `--help` · `-h` | Справка по командам. |
+| `daemon [--install-plist]` | Запустить роутер (обычно держит launchd). `--install-plist` только пишет плист, не загружая. |
+
+`update` проверяет здоровье демона после перезапуска: если демон не ожил — команда возвращает ненулевой код и советует `rollback`.
+
+## Хост
+
+| Команда | Что делает |
+|---|---|
+| `onboard [флаги]` | Подготовка хоста: marketplace (Claude + Codex) → notifier → Telegram (пир-человек) → провайдер памяти. Все шаги по умолчанию включены. |
+| `status` | Снимок хоста: версия, здоровье демона, слот памяти. Код возврата ненулевой, если демон нездоров. |
+| `install-runtime <рантайм> [--package <пакет>] [--npx] [--no-bootstrap]` | Установить рантайм-пакет и развернуть его объявленный набор пиров. `--no-bootstrap` — не загружать пиров в launchd. |
+| `update-runtime <рантайм> \| --all [--force]` | Обновить рантайм-пакет(ы) с перезапуском их пиров. |
+
+Флаги `onboard`: `--dry-run` (показать без изменений), `--no-notifier`, `--no-telegram`, `--no-memory`, `--telegram-human <имя>`, `--telegram-user-id <id>`, `--memory <пакет>`, `--infra <список>`.
+
+## Пиры: создание и обзор
+
+| Команда | Что делает |
+|---|---|
+| `init [папка] [--runtime r] [--description d] [--bin путь] [--no-bootstrap]` | Сделать текущую (или указанную) папку пиром: профиль, MCP, доктрина. Имя пира — это имя папки; отдельным флагом не задаётся. |
+| `create <имя> [--runtime r] [--path папка] [--bin путь] [--description d] [--intelligence i] [--no-bootstrap]` | Создать пир из любого места (по умолчанию `~/.iapeer/peers/<имя>`) и провизионировать. |
+| `list [--json]` | Реестр пиров с состоянием по рантаймам. В интерактивном терминале — панель управления; иначе или с `--json` — таблица. |
+| `verify [--json] [--fix]` | Проверка профилей на соответствие стандарту и расхождений реестр↔профиль. `--fix` самовосстанавливает реестр и мигрирует старый формат поля рантайма. |
+
+## Пиры: жизненный цикл
+
+| Команда | Что делает |
+|---|---|
+| `stop <пир> [рантайм] \| --all` | Агент: стоп-флаг + закрыть сессию (демон не будит). Инфра: снять с launchd. `--all` — все пиры. |
+| `start <пир> [рантайм] \| --all` | Снять стоп-флаг (сессия поднимется на первом сообщении). Инфра: загрузить в launchd. |
+| `new <пир> [рантайм]` | Безусловный свежий перезапуск — аварийный рычаг для зависшей/мёртвой сессии, в обход агента. Код 0 = свежая сессия поднята и готова. |
+| `refresh <пир> [рантайм] \| --all` | Ленивый «мягкий перезапуск»: агентский пир поднимется свежим (перечитает доктрину/фрагменты с диска) на своём СЛЕДУЮЩЕМ естественном пробуждении. Не убивает живую сессию, не будит остальных, не делает немедленный перезапуск — только ставит маркер. Роутеры (notifier/telegram) и absent-рантаймы пропускаются (у них нет доктрины). `--all` — все пиры. |
+| `remove <пир> [--force]` | Удалить запись из реестра (папку пира не трогает). Отказывает живому пиру без `--force`. Идемпотентно. |
+| `attach <пир> [рантайм]` | Поднять (если спит), продолжить диалог, открыть сессию под супервизором в терминале (отсоединиться — `Ctrl-]`). |
+| `interrupt <пир> [рантайм]` | Прервать текущий ход (Escape), контекст цел. |
+| `compact <пир> [рантайм]` | Сжать диалог; спящего после усыпления сначала продолжить. |
+| `add-runtime <рантайм> (--peer <p> \| --all)` | Добавить агентский рантайм существующим пирам. `default_runtime` не трогает. |
+| `default-runtime <рантайм> (--peer <p> \| --all)` | Переключить основной рантайм (маршрутизация/первый подъём). Откажет, если рантайм не объявлен. |
+
+`stop`/`start`/`new` отказываются трогать пиров под чужим launchd-плистом — ядро не вмешивается в то, чем управляет не оно.
+
+## Сообщения
+
+| Команда | Что делает |
+|---|---|
+| `send <цель> (--message <текст> \| --message-file <f\|->) [--from <id>] [--runtime <r>] [--attachment <путь>]… [--topic <t>]` | Ручная отправка IAP по тому же пути, что `send_to_peer`. |
+
+`--message-file -` читает тело из stdin. `--attachment` повторяемый. `--from` по умолчанию — идентичность пира текущей папки.
+
+## Запуск и рантаймы
+
+| Команда | Что делает |
+|---|---|
+| `<рантайм>` (например `iapeer claude`) | Запустить пир текущей папки в этом рантайме — всегда свежей сессией. |
+| `connect telegram <пир> [--token <t>]` | Подключить Telegram-бота к пиру: регистрация бота → запись в профиль → перезапуск роутера. Спрашивает только токен. |
+
+## Расширения и память
+
+| Команда | Что делает |
+|---|---|
+| `enable <плагин> [пир] [--no-setup]` | Установить и включить capability-плагин для пира (по рантаймам), вызвать его шаг установки. |
+| `native-memory <off\|on> (--peer <p> \| --all)` | Отключить/вернуть родную память рантаймов пира. |
+| `trust-hooks <hooks.json> [--check]` | Предварительно доверить codex-хуки из файла (без модального окна). `--check` — отчёт о расхождениях. |
+
+## Агентские самовызовы
+
+Команды, которые агент выполняет в своей сессии (требуют `PEER_IDENTITY` в окружении):
+
+| Команда | Что делает |
+|---|---|
+| `self-fresh` | Пометить себя на свежий перезапуск и закрыть свою сессию — демон поднимет свежую. |
+| `self-done` | Эфемерный воркер: тихо завершиться, освободив очередь, никого не разбудив. |
+
+## Служебные
+
+| Команда | Что делает |
+|---|---|
+| `daemon` | Точка входа демона-роутера; запускается из плиста `com.agfpd.iapeer`. |
+| `run-infra <имя> <рантайм>` | Точка входа инфраструктурного пира; запускается из его launchd-плиста. |
+
+Эти две команды вызывает launchd, а не оператор напрямую.