@agfpd/iapeer 0.2.98 → 0.3.0

package/docs/ru/13-/320/260/321/200/321/205/320/270/321/202/320/265/320/272/321/202/321/203/321/200/320/260-/320/270-/320/272/320/276/320/275/321/202/321/200/320/260/320/272/321/202.md

@@ -0,0 +1,190 @@
+# 13 — Архитектура и контракт
+
+**Русский** · [English](../13-architecture-and-contract.md)
+
+Раздел для тех, кто разрабатывает под iapeer: рантайм-пакеты, capability-плагины, провайдеры памяти.
+
+## Инварианты
+
+На них держится поведение системы:
+
+- **Один роутер.** В системе ровно один постоянно работающий демон. Все сообщения идут через него; второго маршрутизатора нет.
+- **Идентичность на каждый запрос.** Демон не хранит сессию клиента — он определяет, кто к нему обратился, из заголовка `X-IAPeer-Identity` каждого MCP-запроса. Один слушатель обслуживает всех пиров.
+- **Единственный писатель реестра.** `peers-profiles.json` пишется только через одного писателя под файловой блокировкой. Прямая запись файла запрещена на уровне ядра — это исключает гонки.
+- **Живость определяется live-сессией пира.** Пир жив тогда и только тогда, когда у него есть живая сессия под супервизором. Это не отдельный флаг в состоянии, который можно рассинхронизировать, а наблюдаемый факт.
+- **`доставлено` ⟺ легло в живую сессию.** Успех доставки означает, что сообщение принято живой сессией (демон дождался подтверждения). Не подтвердила — демон считает сессию мёртвой, а не лжёт об успехе.
+- **Источник истины — локальный профиль.** Реестр — пересобираемая проекция профилей пиров. При расхождении прав профиль.
+- **Бинарь установлен на хост.** Демон работает с установленного `~/.local/bin/iapeer`, а не из рабочего дерева исходников. Обновление — это замена бинаря и перезапуск демона на него.
+
+## Рантайм-адаптеры на стороне ядра
+
+Адаптер — слой ядра, который умеет запускать сессию рантайма. Все адаптеры реализуют единый интерфейс; различия рантаймов спрятаны за ним.
+
+Ключевые свойства адаптера:
+
+- **`kind`** — `tui` (интерактивная сессия, принимает ввод: claude, codex) или `router` (долгоживущий процесс без ввода: telegram, notifier).
+- **`usesDoctrine`** — потребляет ли рантайм собранный системный промпт. Для TUI-агентов — да, для роутеров — нет (это не языковые модели).
+- **`requiresIntelligence`** — гейт по природе пира. У `telegram` это `natural`: попытка завести Telegram-присутствие у не-человека отклоняется с явной ошибкой.
+- **`buildArgv`** — как собрать команду запуска: для роутеров это `<рантайм>-runtime run` плюс дополнительные аргументы из `launch.env`.
+
+Роутеры пропускают все TUI-фазы: у них нет загрузочных диалогов, маркеров готовности, подтверждения доставки и контрольных команд. Их живость держит launchd, а не пробуждение демоном.
+
+Продакшен-механизм хостинга TUI-сессий — **pty-супервизор**: супервизор-демон владеет pty сессии и её pane-логом, через его сокет идёт доставка на ввод. tmux остаётся только внутренней dev-ветвью (shadow-branch), на пользовательском уровне не фигурирует.
+
+## Контракт рантайм-пакета
+
+Рантайм-пакет (`*-runtime`) — npm-пакет, добавляющий инфраструктурный рантайм. Примеры: `@agfpd/notifier-runtime`, `@agfpd/telegram-runtime`.
+
+### Манифест runtime.json
+
+Пакет при self-install пишет манифест в `~/.iapeer/runtimes/<рантайм>/runtime.json`. Ядро его читает.
+
+```json
+{
+  "runtime": "notifier",
+  "version": "0.2.0",
+  "selfConfig": { "command": "notifier-runtime", "args": ["self-config"] },
+  "peers": [
+    { "personality": "timer",   "intelligence": "absent", "description": "Планировщик по расписанию" },
+    { "personality": "watcher", "intelligence": "absent", "description": "Наблюдатель за событиями" }
+  ]
+}
+```
+
+| Поле | Тип | Обязательность | Назначение |
+|---|---|---|---|
+| `runtime` | строка | обязательно | ID рантайма, совпадает с именем папки; шаблон `^[a-z][a-z0-9]{0,31}$` |
+| `version` | строка | опционально | Версия пакета. Используется для гейта при `update-runtime`; без неё обновление просто переустанавливает |
+| `selfConfig` | дескриптор | опционально | Хук персональной настройки, вызывается ядром на каждого пира при провижне |
+| `peers` | массив | опционально | Объявленный набор пиров. Есть — режим declared-set; нет — operator-add |
+
+Элемент `peers[]`: `personality` (обязательно), `intelligence`, `description`, `path` (явная папка), `runtimeBin` (путь лаунчера) — последние четыре опциональны.
+
+**Дескриптор** (`selfConfig` и подобные) — это `{ "command": "...", "args": [...] }` или просто строка-команда.
+
+### Два режима развёртывания
+
+- **declared-set** — манифест содержит `peers[]`. `iapeer install-runtime <рантайм>` разворачивает весь набор сразу (notifier разворачивает `timer` и `watcher`).
+- **operator-add** — `peers[]` пуст или отсутствует. Пиров заводит оператор по одному: `iapeer create <имя> --runtime <рантайм>` (так подключают людей в telegram).
+
+### Что ядро вызывает у пакета
+
+Контракт минимален — ядро обращается к пакету ровно тремя способами:
+
+1. **`npx <пакет>`** — при установке. Пакет идемпотентно раскладывает свой бинарь на `PATH` и пишет `runtime.json`.
+2. **`<рантайм>-runtime run`** — при запуске сессии (через launchd-плист или launch). В окружении — `PEER_PERSONALITY`, `PEER_RUNTIME`, `PEER_IDENTITY`.
+3. **Хук `selfConfig`** — при провижне каждого пира. Вызывается в рабочей папке пира; в окружении — `IAPEER_PEER_PERSONALITY`, `IAPEER_PEER_CWD`, `IAPEER_PEER_RUNTIME`, `IAPEER_PEER_INTELLIGENCE`. Код возврата 0 — настроено (идемпотентно), иначе — ошибка (плист пишется, но не загружается).
+
+Команды вроде `prepare`, `interface`, `bot`, `doctor` — это внутренние команды самого пакета для оператора, а не контракт с ядром: ядро их не вызывает.
+
+### Установка и обновление
+
+- **`install-runtime <рантайм>`** определяет npm-пакет (по встроенному реестру или флагу `--package`), ставит его через `npx`, затем разворачивает объявленный набор пиров.
+- **`update-runtime <рантайм>`** сверяет версию манифеста с npm; при отставании переустанавливает, заново провизионирует и перезапускает пиров рантайма штатными `stop`/`start`.
+
+## Стандарт capability-плагина
+
+Capability-плагин добавляет пиру способность, не будучи рантаймом. Отличие чёткое: рантайм — способ присутствия пира, плагин — способность поверх рантайма.
+
+### Манифест iapeer.json
+
+Плагин может (но не обязан) положить в свой корень `iapeer.json`:
+
+| Поле | Тип | Назначение |
+|---|---|---|
+| `setup` | дескриптор | Шаг установки плагина. Вызывается при `enable`, если объявлен и установка прошла |
+| `requires` | — | Зависимости (рантаймы, другие плагины). Ядро их не разрешает — плагин проверяет их сам и отказывает, если зависимости нет |
+
+Плагин без `iapeer.json` или без `setup` — это простой класс: ставится и включается, дополнительной инициализации нет.
+
+### enable
+
+`iapeer enable <плагин> [пир]` по шагам:
+
+1. Находит пир (по имени или по текущей папке); отказывает, если у пира нет агентского рантайма.
+2. На каждом агентском рантайме пира ставит плагин: для Claude — в область проекта внутри папки пира (`plugin install … --scope project`), для Codex — в общий конфиг хоста. Установка попутно включает плагин.
+3. Если объявлен `setup` и установка удалась — вызывает его. В окружении: `IAPEER_PEER_PERSONALITY`, `IAPEER_PEER_CWD`; рабочая папка — корень плагина. Шаг best-effort: его сбой не откатывает уже сделанные установку и включение.
+
+Идемпотентность: для Claude привязка идёт по реальному пути папки пира, поэтому повторный `enable` не задевает другие пиры и не дублирует установку.
+
+### Критерии iapeer-совместимости
+
+Плагин считается совместимым, если он:
+
+1. полезен сам по себе;
+2. объявляет, что предоставляет и что требует;
+3. не владеет чужой ответственностью;
+4. имеет идемпотентную подготовку;
+5. имеет самодиагностику (`doctor`/`status`);
+6. использует общий ABI идентичности (`PEER_*`), когда тот доступен;
+7. не требует от пользователя вручную синхронизировать идентичность между плагинами;
+8. одинаково понимает имя, рантайм и идентичность под Claude, Codex и будущими рантаймами.
+
+## Контракт слота памяти
+
+Память даёт провайдер, занимающий единственный на хост слот. Слот занят ровно одним провайдером или пуст.
+
+### Манифест провайдера
+
+Провайдер атомарно пишет `~/.iapeer/memory-provider.json`; ядро только читает. Удаляет файл — освобождает слот. Ядро слот никогда не пишет.
+
+```json
+{
+  "provider": "iapeer-memory",
+  "package": "@agfpd/iapeer-memory",
+  "version": "0.2.7",
+  "registeredAt": "2026-06-11T17:46:41.449Z",
+  "heartbeat": "/Users/me/.iapeer/state/iapeer-memory/memoryd.heartbeat",
+  "provision": {
+    "command": "/Users/me/.local/bin/iapeer-memory",
+    "args": ["provision-peer", "--cwd", "{cwd}", "--runtime", "{runtime}",
+             "--personality", "{personality}", "--occasion", "{occasion}"]
+  },
+  "unprovision": {
+    "command": "/Users/me/.local/bin/iapeer-memory",
+    "args": ["unprovision-peer", "--cwd", "{cwd}", "--runtime", "{runtime}",
+             "--occasion", "{occasion}"]
+  }
+}
+```
+
+| Поле | Тип | Обязательность | Назначение |
+|---|---|---|---|
+| `provider` | строка | обязательно | Имя провайдера |
+| `package` | строка | обязательно | npm-пакет |
+| `version` | строка | обязательно | Версия пакета |
+| `registeredAt` | ISO-дата | обязательно | Когда занят слот |
+| `heartbeat` | путь | опционально | Файл сердцебиения демона провайдера; `iapeer status` показывает его свежесть |
+| `provision` | дескриптор | опционально | Команда настройки памяти пира при рождении |
+| `unprovision` | дескриптор | опционально | Команда сворачивания при удалении пира |
+
+`command` обязан быть абсолютным путём; `args` — массив строк. Невалидный блок ядро трактует как отсутствующий, пустой слот — как нормальное состояние.
+
+### Команды provision/unprovision
+
+В аргументах подставляются четыре плейсхолдера (подстановка пер-аргумент, на уровне подстроки):
+
+| Плейсхолдер | Значение |
+|---|---|
+| `{cwd}` | рабочая папка пира |
+| `{runtime}` | конкретный агентский рантайм (`claude` / `codex`) |
+| `{personality}` | имя пира — обязан совпадать с `normalize(basename({cwd}))` (имя пира и папка соотносятся 1:1); несовпадение → `ensurePeerProfile` завершается ошибкой |
+| `{occasion}` | момент вызова (см. ниже) |
+
+**Моменты вызова, которые эмитит ядро:**
+
+- **`birth`** — при рождении пира, по одной команде на каждый агентский рантайм. Идёт после предварительного доверия codex к папке, чтобы поверхности провайдера легли в уже доверенную папку.
+- **`remove`** — при удалении пира, по команде на агентский рантайм. Идёт до очистки состояния пира — провайдер видит его в последнем согласованном виде.
+
+**Окружение:** команда наследует всё окружение ядра; специальные `IAPEER_PEER_*` сюда ядро **не** добавляет — провайдер опирается на плейсхолдеры в аргументах. stdin игнорируется, stdout/stderr захватываются.
+
+**Семантика выполнения:** код возврата 0 — успех; иначе — ошибка; превышение 120 секунд — таймаут; недоступный бинарь — отдельный исход. Всё best-effort: сбой команды не валит ни рождение, ни удаление пира, но громко логируется. Провайдер обязан быть идемпотентным — ядро может вызвать одну команду повторно.
+
+### Рычаг родной памяти
+
+Когда слот занят, держать параллельно родную память рантайма вредно. Ядро при рождении пира с занятым слотом отключает её:
+
+- **Claude** — в `<папка>/.claude/settings.json` дописывает `"autoMemoryEnabled": false`;
+- **Codex** — в `<папка>/.codex/config.toml` дописывает `[features] memories = false`.
+
+Включить обратно — удалить ключ (восстановить умолчание рантайма). Вручную: `iapeer native-memory off|on`. Для Codex ядро при рождении заодно прописывает доверие к папке (`[projects."<реальный-путь>"] trust_level = "trusted"`), чтобы проектный конфиг читался с первой сессии; при удалении пира эта запись снимается.

package/docs/ru/14-/320/272/320/276/320/275/321/204/320/270/320/263/321/203/321/200/320/260/321/206/320/270/321/217-/320/270-/320/266/321/203/321/200/320/275/320/260/320/273/321/213.md

@@ -0,0 +1,91 @@
+# 14 — Конфигурация и журналы
+
+**Русский** · [English](../14-configuration-and-logs.md)
+
+Ядро работает на разумных значениях по умолчанию — отдельная настройка для запуска не нужна. Поведение тонко настраивается переменными окружения; журналы дают материал для разбора, когда что-то пошло не так.
+
+## Переменные окружения
+
+Все значения ниже — дефолты из текущего кода. Переменную задают в окружении демона или конкретного пира (через `launch.env`, см. [06 — Хранение](06-хранение.md)).
+
+### Жизненный цикл
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAPEER_IDLE_SECS` | `3600` | Через сколько секунд простоя демон закрывает сессию агента (усыпление). |
+| `IAPEER_BOOT_DEADLINE_SECS` | `240` | Сколько ждать загрузки сессии при подъёме, прежде чем считать запуск неудачным. |
+| `IAPEER_READY_GATE_SECS` | `120` | Сколько ждать готовности агента к вводу после загрузки. |
+| `IAPEER_CRASHLOOP_MAX` | `3` | Сколько смертей в окне допускается, прежде чем демон перестанет поднимать пир. |
+| `IAPEER_CRASHLOOP_WINDOW_SECS` | `300` | Окно (секунды), на котором считаются смерти для защиты от цикла перезапусков. |
+| `IAPEER_EPHEMERAL_QUIET_SECS` | `20` | Окно тишины, после которого свернётся эфемерный воркер, уже отправивший ответ. |
+| `IAPEER_EPHEMERAL_UNARMED_IDLE_SECS` | `600` | Страховочный предел для эфемерного воркера, который молчит и не отправил ответ. |
+
+Надзорный тик демона фиксирован — раз в минуту, не настраивается.
+
+### Демон
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAPEER_PORT` | `8765` | TCP-порт роутера на `127.0.0.1`. |
+| `IAPEER_DAEMON_SOCKET` | `~/.iapeer/state/iapeer/router.sock` | Путь локального сокета демона. |
+| `IAPEER_BEARER_TOKEN` | — | Если задан, демон требует этот bearer-токен на входе; иначе проверка токена выключена. |
+
+### Доставка сообщений
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAP_HOST_LIVENESS_GRACE_MS` | `4000` | Сколько ждать подтверждения, что сессия приняла сообщение, прежде чем считать её мёртвой. |
+| `IAP_LIVENESS_GRACE_MS` | `3000` | Окно проверки живости занятой сессии (по сдвигу истории диалога). |
+| `IAPEER_COMPOSER_QUEUE_TIMEOUT_MS` | `120000` | Сколько очередь композера ждёт, пока освободится поле ввода, прежде чем досылать принудительно. |
+| `IAPEER_COMPOSER_QUEUE_POLL_MS` | `500` | Частота опроса поля ввода в очереди композера. |
+
+### Пути и бинарники
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAPEER_ROOT` | `~/.iapeer` | Корень хранилища. Смена влечёт изоляцию сокетов в `<корень>/socks` (полезно для изолированных тестовых хостов). |
+| `IAPEER_SOCK_DIR` | `/tmp` | Каталог сокетов host-wide. Переопределяет расположение host-wide. |
+| `IAPEER_BIN_DIR` | `~/.local/bin` | Куда ставится бинарь `iapeer`. |
+| `IAPEER_LAUNCHAGENTS_DIR` | `~/Library/LaunchAgents` | Каталог плистов launchd. |
+| `IAPEER_CLAUDE_BIN` | `~/.local/bin/claude` | Путь к бинарю Claude. |
+| `IAPEER_CODEX_BIN` | `codex` (из `PATH`) | Путь к бинарю Codex. |
+| `NOTIFIER_RUNTIME_BIN` | `notifier-runtime` (из `PATH`) | Путь к лаунчеру notifier (для launchd с его минимальным `PATH`). |
+| `TELEGRAM_RUNTIME_BIN` | `telegram-runtime` (из `PATH`) | Путь к лаунчеру Telegram. |
+| `CODEX_HOME` | `~/.codex` | Переопределение каталога глобального конфига Codex. |
+
+### Журналы
+
+| Переменная | По умолчанию | Что задаёт |
+|---|---|---|
+| `IAPEER_LIFECYCLE_LOG_MAX_BYTES` | `5 МиБ` | Размер `lifecycle.log`, при котором происходит ротация. |
+| `IAPEER_LIFECYCLE_LOG_KEEP` | `5` | Сколько ротаций `lifecycle.log` хранить. |
+| `IAPEER_DELIVERY_LOG_MAX_BYTES` | `5 МиБ` | Размер `delivery.log` для ротации. |
+| `IAPEER_DELIVERY_LOG_KEEP` | `5` | Сколько ротаций `delivery.log` хранить. |
+| `IAPEER_SUPERVISE_LOG_VERBOSE` | выкл. | Подробный лог надзорных тиков (по умолчанию пишутся только решения, не рутинные «ничего не делаю»). |
+| `IAPEER_DAEMON_LOG` | выкл. | Расширенный лог демона. |
+
+### Внутренние, dev и тестовые
+
+`IAPEER_TEST_SANDBOX=1` включает защиту от записи в реальные пути: установка откажется писать в настоящий `~/.local/bin/iapeer` и потребует задать `IAPEER_BIN_DIR` на изолированный путь. Для разработки и автотестов, не для обычной работы.
+
+Ещё несколько переменных система читает, но в обычной эксплуатации их не задают:
+
+- `NOTIFIER_FALLBACK_TARGET` — запасной адресат для сигналов notifier; ядро резолвит его в плист пира при онбординге (без хардкода), вручную оператор его не выставляет.
+- `IAP_TMUX_PASTE_SETTLE_MS`, `IAP_TMUX_SUBMIT_TIMEOUT_MS` — тайминги доставки во внутренней tmux dev-ветви; на проде используется pty-супервизор ([13 — Архитектура и контракт](13-архитектура-и-контракт.md)), вне разработки не нужны.
+- `IAPEER_SHADOW_PATH` — `PATH` для shadow-fidelity прогона (внутренний инструмент разработки).
+
+## Журналы и диагностика
+
+Демон ведёт три долговременных журнала в `~/.iapeer/logs/iapeer/`:
+
+- **`lifecycle.log`** — решения жизненного цикла: пробуждения, усыпления, перезапуски, итоги надзорных тиков. Первое место, куда смотреть, если пир ведёт себя не так.
+- **`delivery.log`** — исход каждой доставки: кто, кому, в какой рантайм, результат, размеры, тема. Только метаданные — **тело сообщения не пишется**.
+- **`exits.log`** — смерти сессий с посмертными данными: супервизор фиксирует причину (код выхода / сигнал) в момент смерти сессии.
+
+### Посмертная диагностика
+
+Причину смерти сессии (код выхода / сигнал) супервизор фиксирует в момент смерти — это то, что обычная проверка «жив ли процесс» не ловит. Отдельный сторож (canary) держит соединение с супервизором и при смерти сессии записывает в `exits.log` обстоятельства: память, swap, процессы по потреблению, системные отчёты диагностики. Это материал для ответа на вопрос «почему агент умер».
+
+### Full Disk Access
+
+Чтобы читать системные отчёты диагностики, бинарю `iapeer` нужен Full Disk Access (FDA) — разрешение macOS. `iapeer status` показывает, выдан ли FDA, и подсказывает, что делать, если нет. Без FDA пиры будут натыкаться на запросы TCC при доступе к защищённым папкам и контейнерам сторонних приложений.

package/docs/ru/README.md

@@ -0,0 +1,97 @@
+# iapeer
+
+**Русский** · [English](../README.md)
+
+iapeer — ядро мультиагентной системы на одном хосте. Он держит реестр участников, единый демон-роутер для обмена сообщениями между ними и набор команд, которыми участниками управляют: создают, запускают, усыпляют, перезапускают, подключают к внешним каналам.
+
+Участник системы называется **пиром**. Пиром может быть AI-агент (Claude, Codex), человек (через Telegram) или служебный процесс (планировщик, наблюдатель). iapeer не различает их по природе на уровне транспорта — все они адресуются одинаково и обмениваются сообщениями через один протокол.
+
+```text
+   send_to_peer (от любого пира)
+        │
+        ▼
+   ┌────────────────────────┐
+   │      демон-роутер        │   работает постоянно
+   │   поиск · доставка       │   читает peers-profiles.json (реестр)
+   └────────────────────────┘
+        │
+        ▼
+   пир-получатель  (если спит — поднимет)
+```
+
+## Что это решает
+
+Когда на машине живёт не один агент, а команда — у каждого своя роль, своя рабочая папка, свой рантайм, — возникают задачи, которых у одиночного агента нет:
+
+- **Адресация.** Как агенту A отправить сообщение агенту B, не зная, запущен ли тот прямо сейчас.
+- **Присутствие.** Держать ли каждого агента в памяти постоянно (дорого) или поднимать по требованию (нужен кто-то, кто поднимет).
+- **Идентичность.** Один и тот же логический агент может присутствовать в разных рантаймах (сегодня Claude, завтра Codex) — система должна понимать, что это один и тот же пир.
+- **Жизненный цикл.** Кто усыпит простаивающего агента, кто перезапустит зависшего, кто не даст упавшему агенту войти в цикл перезапусков.
+
+iapeer берёт это на себя. Агенту достаточно вызвать `send_to_peer(<имя>, <текст>)` — остальное делает демон: найдёт получателя в реестре, проверит, жив ли он, доставит сообщение в живую сессию или поднимет спящего и доставит после пробуждения.
+
+## Быстрый старт
+
+Требования: **macOS** (управление процессами идёт через launchd), **[bun](https://bun.sh)** на `PATH` и хотя бы один агентский рантайм — Claude Code или Codex CLI.
+
+```bash
+# 1. Установите ядро — бинарь, раскладку ~/.iapeer и плист демона
+npx @agfpd/iapeer
+
+# 2. Подготовьте хост — onboard стартует демон, регистрирует marketplace,
+#    ставит notifier, Telegram и память
+iapeer onboard
+
+# 3. Создайте первого агента
+iapeer create assistant --runtime claude
+
+# 4. Отправьте сообщение — демон поднимет сессию, если её нет
+iapeer send assistant --message "привет, ты на связи?"
+```
+
+Подробный разбор каждого шага — в [02 — Быстрый старт](02-быстрый-старт.md).
+
+## Документация
+
+Разделы выстроены слоями: от «поставить и пользоваться» к «понять архитектуру и расширять».
+
+**Введение**
+- [01 — Обзор](01-обзор.md) — что такое iapeer и из чего он состоит
+- [02 — Быстрый старт](02-быстрый-старт.md) — установка, онбординг, первый пир, первое сообщение
+
+**Концепции**
+- [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md)
+- [04 — Жизненный цикл и демон](04-жизненный-цикл-и-демон.md)
+- [05 — Идентичность и системный промпт](05-системный-промпт.md)
+- [06 — Хранение](06-хранение.md)
+
+**Руководства**
+- [07 — Установка и обновление](07-установка-и-обновление.md)
+- [08 — Управление пирами](08-управление-пирами.md)
+- [09 — Рантаймы](09-рантаймы.md)
+- [10 — Обмен сообщениями](10-обмен-сообщениями.md)
+- [11 — Расширения и память](11-расширения-и-память.md)
+
+**Справочник**
+- [12 — CLI](12-cli-reference.md) — все команды с флагами
+- [13 — Архитектура и контракт](13-архитектура-и-контракт.md) — для разработчиков плагинов и рантайм-пакетов
+- [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md) — переменные окружения, журналы, диагностика
+
+## Статус
+
+Построено и работает: единый демон-роутер, протокол обмена сообщениями (IAP), реестр пиров, идентичность и её ABI, жизненный цикл (пробуждение, усыпление, перезапуск, надзор), рантайм-адаптеры для Claude, Codex, Telegram и notifier, установка и онбординг хоста, подключение Telegram, слот памяти и capability-плагины.
+
+Запланировано поверх ядра: граф совместимости пакетов, доктор здоровья всей команды и интерактивный интерфейс координации. Пока этих надстроек нет, координационные операции живут в CLI `iapeer`.
+
+## Планы
+
+Более крупные направления, запланированы и ещё не сделаны:
+
+- **Веб-интерфейс** — работа с командой через браузер.
+- **Поддержка Linux** — сегодня iapeer работает на macOS; Linux в планах.
+- **Дополнительные агентские рантаймы** — `opencode` и `antigravity`, два новых CLI-рантайма наряду с Claude Code и Codex.
+- **Рантайм Discord** — рантайм присутствия человека для Discord, наряду с Telegram.
+- **Гейт разрешений** — более тонкий контроль над тем, что агенту позволено делать.
+- **Апрув разрешений через Telegram** — подтверждать запросы разрешений агента прямо из чата; сегодня разрешения выданы автоматически флагами.
+
+Платформа сейчас — только macOS/launchd. Поддержка Linux (systemd) и Windows не реализована.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.98",
+  "version": "0.3.0",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",
@@ -27,8 +27,10 @@
   "files": [
     "src",
     "bin",
+    "docs",
     "tsconfig.json",
-    "!src/**/*.test.ts"
+    "!src/**/*.test.ts",
+    "!docs/internals/**"
   ],
   "exports": {
     ".": "./src/index.ts",
@@ -54,13 +56,17 @@
     "@modelcontextprotocol/sdk": "1.29.0",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
+    "ink": "^7.1.0",
     "proper-lockfile": "^4.1.2",
+    "react": "^19.2.7",
+    "react-devtools-core": "^7.0.1",
     "transliteration": "^2.6.1"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "@types/node": "^22.0.0",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/react": "^19.2.17",
     "typescript": "^5.6.0"
   }
 }

package/src/cli/index.ts

@@ -1002,6 +1002,26 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
   try {
     switch (verb) {
       case 'onboard': {
+        // Interactive TUI wizard (Фаза TUI-редизайн) — the DEFAULT for an
+        // interactive `iapeer onboard`. Routed ONLY in a real interactive terminal
+        // and never for an automation path (--accept-risk / --dry-run / --no-memory
+        // / --infra), which stay on the deterministic linear flow below. Escape
+        // hatch: IAPEER_ONBOARD_WIZARD=0 forces the linear path (recovery / scripts
+        // that want the old flow). The wizard owns its own gate screen, so we route
+        // BEFORE the readline gate. It fails closed: no real TTY →
+        // WIZARD_NOT_INTERACTIVE → fall through to linear.
+        const wizardOptOut = /^(0|false|no)$/i.test((env.IAPEER_ONBOARD_WIZARD ?? '').trim())
+        const automationFlag =
+          flags['accept-risk'] === true ||
+          flags['dry-run'] === true ||
+          flags['no-memory'] === true ||
+          typeof flags.infra === 'string'
+        if (!wizardOptOut && !automationFlag && process.stdin.isTTY === true && process.stdout.isTTY === true) {
+          const { runOnboardWizard, WIZARD_NOT_INTERACTIVE } = await import('../tui/onboard/run.tsx')
+          const wc = await runOnboardWizard({ env })
+          if (wc !== WIZARD_NOT_INTERACTIVE) return wc
+          // not a real interactive TTY after all → linear path below
+        }
         // SECURITY GATE (pre-release): the operator must consciously accept the risk of
         // beta infra with live agents BEFORE onboard mutates the host. --accept-risk /
         // IAPEER_ACCEPT_RISK accepts non-interactively (one-liner installers / CI); a