@agfpd/iapeer 0.2.97 → 0.2.99

package/docs/ru/03-/320/277/320/270/321/200/321/213-/321/200/320/260/320/275/321/202/320/260/320/271/320/274/321/213-/320/270/320/264/320/265/320/275/321/202/320/270/321/207/320/275/320/276/321/201/321/202/321/214.md

@@ -0,0 +1,117 @@
+# 03 — Пиры, рантаймы, идентичность
+
+**Русский** · [English](../03-peers-runtimes-identity.md)
+
+Углублённая версия трёх базовых понятий из [обзора](01-обзор.md) — с уровнем детализации, нужным, чтобы создавать пиров, переключать их между рантаймами и читать профили.
+
+## Пир
+
+Пир — участник системы. У него есть рабочая папка, имя, набор рантаймов и природа.
+
+### Имя (personality)
+
+Имя — короткое логическое имя в нижнем регистре: `assistant`, `code-reviewer`, `timer`. Формат по шаблону `^[a-z][a-z0-9-]{0,31}$`: буква, дальше буквы, цифры, дефисы, до 32 символов.
+
+Имя не хранится отдельной величиной — оно **выводится из имени рабочей папки**. Папка `~/.iapeer/peers/assistant` даёт имя `assistant`; не-латиница и прочие символы нормализуются к допустимому виду.
+
+Отсюда жёсткое правило: **имя и рабочая папка связаны один к одному**. Занятое другим пиром имя — отказ, без молчаливого суффикса для развода коллизии. Имя — это адрес, и он обязан быть однозначным.
+
+### Природа (intelligence)
+
+Каждый пир несёт атрибут природы. Он едет вместе с сообщением, поэтому получатель знает, с кем говорит, не полагаясь на догадки.
+
+| Значение | Кто это |
+|---|---|
+| `artificial` | AI-агент (Claude, Codex) |
+| `natural` | человек (через Telegram и подобные каналы) |
+| `absent` | программа без интеллекта (планировщик, наблюдатель, веб-хук) |
+
+Природа по умолчанию выводится из рантайма: агентские рантаймы дают `artificial`, Telegram — `natural`, notifier — `absent`. При создании пира её можно задать явно.
+
+Раньше использовались значения `human` и `scripted` — они и сейчас читаются (понимаются как `natural` и `absent` соответственно), но при записи система сохраняет то значение, что уже стоит в профиле, и не переписывает уже заведённых пиров.
+
+## Рантайм
+
+Рантайм — способ присутствия пира. Имя рантайма короче имени пира: формат `^[a-z][a-z0-9]{0,31}$`, без дефисов. Это важно для разбора идентичности (ниже).
+
+### Два класса рантаймов
+
+**claude, codex** — AI-агенты. Сессию не держат запущенной постоянно: демон поднимает агента на входящее сообщение и закрывает сессию после часа простоя. Этим рантаймом демон управляет полностью — поднимает и усыпляет.
+
+**telegram, notifier** — рантаймы-роутеры, не AI. Telegram-мост принимает входящие в любой момент, notifier срабатывает по расписанию — поэтому работают постоянно под launchd с автоперезапуском. Такой рантайм демон **не трогает**: пробуждение и усыпление к нему неприменимы, его жизненным циклом распоряжается launchd. Это инфраструктурные рантаймы.
+
+Деление — граница ответственности: демон отвечает за claude/codex, launchd — за инфраструктурные. Команды `stop`/`start`/`new` работают по-разному в зависимости от класса (см. [08 — Управление пирами](08-управление-пирами.md)).
+
+### Несколько рантаймов у одного пира
+
+Пир может объявлять несколько рантаймов. В профиле это два поля:
+
+- **`runtimes`** — список всех рантаймов, на которых пир может присутствовать, например `["claude", "codex"]`.
+- **`default_runtime`** — основной рантайм: куда по умолчанию маршрутизируются сообщения и какой рантайм поднимается первым.
+
+Добавить пиру рантайм и сделать его основным — разные операции. Первая (`add-runtime`) расширяет возможности, не меняя маршрутизацию; вторая (`default-runtime`) переключает основной рантайм. Массовое переключение `default_runtime` по всем пирам — это и есть момент «пересадки» команды с одного агентского рантайма на другой. См. [09 — Рантаймы](09-рантаймы.md).
+
+Список рантаймов пополняется и сам: при инициализации пира система сканирует его папку на признаки рантаймов (каталоги `.claude`, `.codex` и подпапки в `runtimes/`) и добавляет найденное в `runtimes`. Так список остаётся актуальным, даже когда рантайм появился у пира органически, а не был объявлен явно.
+
+## Идентичность
+
+Идентичность — адрес конкретного живого присутствия пира. Складывается из рантайма и имени через дефис:
+
+```text
+PEER_IDENTITY = PEER_RUNTIME + "-" + PEER_PERSONALITY
+```
+
+Пир `assistant` в Claude — это `claude-assistant`; он же в Codex — `codex-assistant`. Имя одно, идентичности две.
+
+Разбор идентичности идёт **по первому дефису**: всё слева — рантайм, всё справа — имя. Поскольку в имени рантайма дефисов нет, а в имени пира они допустимы, разбор однозначен: `claude-code-reviewer` — это рантайм `claude` и пир `code-reviewer`.
+
+### ABI идентичности
+
+Три значения образуют ABI — набор переменных окружения, по которым любой компонент системы понимает, кто он:
+
+| Переменная | Значение | Пример |
+|---|---|---|
+| `PEER_PERSONALITY` | имя пира | `assistant` |
+| `PEER_RUNTIME` | рантайм текущей сессии | `claude` |
+| `PEER_IDENTITY` | полный адрес | `claude-assistant` |
+
+Когда демон поднимает сессию агента, он передаёт эти переменные в окружение. Агент по ним знает своё имя и от чьего лица отправляет сообщения. Рантайм текущей сессии определяется в таком порядке: из заголовка идентичности (`PEER_IDENTITY`), затем из профиля, затем из `PEER_RUNTIME`, и в последнюю очередь — автоопределением по признакам рантайма в окружении: Codex выставляет `CODEX_THREAD_ID`, Claude — `CLAUDECODE=1`. Если не сработал ни один источник, подъём отклоняется с требованием задать `PEER_RUNTIME` или завести профиль.
+
+## Профиль и реестр
+
+У идентичности два места хранения, и важно понимать, какое из них главное.
+
+### Профиль пира — источник истины
+
+`<папка-пира>/.iapeer/peer-profile.json` — это карточка пира, единственный источник истины о нём. Вот реальный профиль:
+
+```json
+{
+  "personality": "assistant",
+  "runtimes": ["codex", "claude"],
+  "default_runtime": "claude",
+  "runtime": "claude",
+  "description": "Помощник общего профиля. Принимает задачи через IAP.",
+  "intelligence": "artificial",
+  "initial_prompt": "Новая сессия. Поздоровайся с владельцем.",
+  "interfaces": {
+    "telegram": { "bot": "assistant", "bot_username": "assistant_bot" }
+  }
+}
+```
+
+Поля профиля делятся на три класса по тому, кто ими владеет:
+
+- **Ядро идентичности** — `personality`, `default_runtime`, `runtimes`, `description`, `intelligence`, `initial_prompt`. Этим владеет ядро и жизненный цикл. Поле `initial_prompt` — затравка первого хода свежей сессии. Поле `runtime` рядом с `default_runtime` — это синхронная копия для совместимости со старыми читателями; оба пишутся согласованно.
+- **Приватная конфигурация плагина** — секции вроде `expansion` (шорткаты-алиасы), `notifier` (настройка пира-планировщика) и прочие, по одной на плагин. Читаются только из локального профиля, в реестр не попадают.
+- **Публичный паспорт** — секция `interfaces` (например `interfaces.telegram.bot`). Это атрибуты маршрутизации, и они проецируются в реестр.
+
+Описание `description` ограничено по длине (сейчас 450 символов) — оно само-документирующее, его видят другие пиры в реестре.
+
+### Реестр — производная
+
+`~/.iapeer/peers-profiles.json` — общий реестр всех пиров. Демон читает его, чтобы понять, кому доставлять сообщение и какие у пира рантаймы. Запись реестра содержит проекцию профиля: имя, основной рантайм, список рантаймов, описание, природа, рабочая папка, публичные интерфейсы.
+
+Реестр — не источник истины, а **проекция** локальных профилей. Его можно пересобрать из профилей в любой момент (`iapeer verify --fix`). Если реестр и профиль разошлись, прав профиль — реестр чинится по нему.
+
+Реестр пишется только через единственного писателя под файловой блокировкой — прямое редактирование `peers-profiles.json` запрещено на уровне ядра. Это исключает гонки, когда несколько процессов одновременно меняют состав пиров. Подробнее о раскладке и владении — [06 — Хранение](06-хранение.md).

package/docs/ru/04-/320/266/320/270/320/267/320/275/320/265/320/275/320/275/321/213/320/271-/321/206/320/270/320/272/320/273-/320/270-/320/264/320/265/320/274/320/276/320/275.md

@@ -0,0 +1,101 @@
+# 04 — Жизненный цикл и демон
+
+**Русский** · [English](../04-lifecycle-and-daemon.md)
+
+## Демон-роутер
+
+Демон — единственный постоянно работающий процесс ядра. У него три роли:
+
+1. **Маршрутизация** — принимает `send_to_peer`, находит получателя в реестре, доставляет.
+2. **Пробуждение** — поднимает сессию спящего получателя и доставляет после подъёма.
+3. **Надзор** — раз в минуту обходит пиров: усыпляет простаивающих, замечает упавших, перезапускает помеченных на свежий старт.
+
+Демон держит launchd по плисту `com.agfpd.iapeer` — отдельному от плистов пиров. launchd поднимает демон при загрузке системы и перезапускает при падении, поэтому роутер переживает и перезагрузку машины, и собственные сбои.
+
+Слушает демон на двух входах одновременно:
+
+- **локальный сокет** `~/.iapeer/state/iapeer/router.sock` (доступ только владельцу) — для CLI и рантаймов-роутеров;
+- **TCP на петле** `127.0.0.1:8765` — для агентов Claude и Codex, подключённых к `send_to_peer` по HTTP.
+
+### Надзорный тик
+
+Раз в минуту демон выполняет надзорный обход. За один тик он усыпляет агентов, простоявших дольше часа; замечает умершие сессии и решает их судьбу; поднимает свежими помеченных на немедленный перезапуск; докармливает очереди эфемерных воркеров. Минута — это потолок задержки для отложенной работы: очередь, накопившаяся за окно перезапуска демона, разгребётся на ближайшем тике.
+
+## Состояния пира
+
+Агент claude/codex в каждый момент в одном из трёх состояний:
+
+| Состояние | Что значит | Метка в `iapeer list` |
+|---|---|---|
+| **живой** | сессия запущена и отвечает | `●` |
+| **спит** | сессии нет, пир готов проснуться по сообщению | `○` |
+| **остановлен** | оператор поставил стоп-флаг; демон не будит | `✕` |
+
+```text
+                 сообщение
+       спит  ──────────────▶  живой
+        ▲                       │
+        │  снят стоп-флаг         │ час простоя / падение
+        │                       ▼
+   остановлен  ◀──────────  живой
+                стоп (оператор)
+```
+
+## Доставка и пробуждение
+
+На входящее сообщение демон смотрит на состояние получателя:
+
+- **живой** — вставляет в сессию, подтверждает приём, отвечает `доставлено`;
+- **спит** — поднимает сессию, перепроверяет получателя, доставляет, отвечает `доставлено, разбудил`;
+- **остановлен** — отказывает и сообщает отправителю прямо.
+
+Гарантию «`доставлено` значит легло в живую сессию» разбирает [10 — Обмен сообщениями](10-обмен-сообщениями.md).
+
+### Свежий старт или продолжение диалога
+
+Поднимая спящего, демон выбирает: начать **свежую** сессию или **продолжить** прежний диалог. Зависит от того, чем будят, от типа пира и — для агентов — от **топика** входящего сообщения.
+
+Три типа пира — три базовых поведения: **эфемерный воркер** всегда стартует свежим, **человек** (Telegram) всегда продолжает, **агент** продолжает только по совпавшему топику. Полная развёртка:
+
+| Чем разбудили | Условие | Результат |
+|---|---|---|
+| `iapeer <runtime>` (из папки) | — | 🆕 свежий |
+| `iapeer attach` | — | ▶️ продолжение (ошибка, если продолжать нечего) |
+| сообщение | упал / закрылся сам / никогда не запускался | 🆕 свежий |
+| сообщение | усыплён за простой, пир-**человек** (Telegram) | ▶️ продолжение (всегда) |
+| сообщение | усыплён за простой, **агент** · топик совпал с нитью сессии | ▶️ продолжение |
+| сообщение | усыплён за простой, **агент** · топик новый или его нет | 🆕 свежий |
+| сообщение | пир остановлен (`stop`) | 🚫 не будится — явный отказ |
+
+Ключевое для агентов: **продолжение включается явно — через топик**. Сообщение без топика после простоя поднимает свежую сессию, а не воскрешает старый контекст (иначе оживёт сессия многодневной давности и продолжит не ту работу). Чтобы продолжить нужную нить — отправитель указывает её топик. Топики **копятся**: в одной сессии может идти несколько нитей, и пинг по любой из них (не только последней) продолжит её. Для пиров-людей продолжение всегда — топик их не сбрасывает.
+
+Ленивый сброс на свежесть — **`iapeer refresh`** (см. «Команды жизненного цикла» ниже): помечает пира, и на его ближайшем естественном пробуждении он стартует свежим вместо продолжения — для любого типа, включая людей-в-Telegram. Так после обновления доктрины команда перечитывает её сама собой, без ручного `/new` и без массового пробуждения.
+
+## Усыпление при простое
+
+Агент, не проявлявший активности дольше часа, усыпляется на ближайшем надзорном тике: демон закрывает сессию и ставит метку усыпления. Память освобождается, диалог сохраняется на диске — следующее сообщение **с топиком той работы** поднимет агента ровно там, где он остановился (без топика или с новым — свежим, см. выше). Час простоя — единственная временна́я граница: «слепого» TTL по времени жизни нет. Порог простоя по умолчанию — 3600 секунд; он и другие пороги жизненного цикла (загрузка, готовность, защита от цикла перезапусков) настраиваются переменными окружения — [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md).
+
+## Надзор и устойчивость
+
+**Защита от цикла перезапусков.** Демон ведёт кольцо последних смертей каждого пира. Если за 5 минут пир умирает 3 раза, демон перестаёт его поднимать и оставляет спящим — это сигнал неисправности, а не сотая попытка вслепую.
+
+**Сериализация пробуждений.** На спящего агента может прилететь несколько сообщений сразу; поднять его должна одна попытка, иначе родятся две конкурирующие сессии. Демон берёт блокировку на пробуждение конкретного пира — остальные ждут готовности первой.
+
+**Посмертная диагностика.** Супервизор в момент смерти сессии фиксирует её причину (код выхода / сигнал) — это то, что обычная проверка «жив ли процесс» не ловит. На этот случай отдельный сторож (canary) держит блокирующее соединение с супервизором и при смерти сессии записывает обстоятельства — память, swap, список процессов, отчёты диагностики — в журнал.
+
+## Граница: claude/codex против инфраструктурных
+
+Демон управляет только агентами claude/codex и только теми, чей плист принадлежит ядру. Инфраструктурные пиры (Telegram, notifier) и любые пиры под чужим launchd-плистом для демона неприкосновенны: он их не будит, не усыпляет, не перезапускает. Их жизненным циклом распоряжается launchd.
+
+Поэтому `stop`, `start`, `new` отказываются трогать чужие launchd-пиры — для них ядро только читатель. Это защита от драки ядра с launchd за управление процессом.
+
+## Команды жизненного цикла
+
+- **`iapeer stop` / `start`** — остановить (стоп-флаг + закрыть сессию) и снять остановку. Для инфраструктурных — через launchd.
+- **`iapeer new`** — безусловный свежий перезапуск, аварийный рычаг для зависшей или мёртвой сессии; действует механически, в обход агента.
+- **`iapeer refresh <пир> \| --all`** — ленивый «мягкий перезапуск»: пометить пира на свежий старт при его СЛЕДУЮЩЕМ естественном пробуждении (перечитать доктрину/фрагменты с диска), не убивая живую сессию и не будя остальных. В отличие от `new` (немедленный жёсткий перезапуск) — это отложенный, ненавязчивый рычаг: применяют после релиза доктрины, чтобы команда освежилась сама собой. Маркер перекрывает «продолжение» для всех типов пиров, включая людей-в-Telegram (которые иначе продолжают старую сессию до явного `/new`).
+- **`iapeer compact`** — сжать диалог; спящего после усыпления демон сначала продолжит, потом сожмёт.
+- **`iapeer interrupt`** — прервать текущий ход (Escape), не теряя контекст.
+- **`iapeer self-fresh` / `self-done`** — самовызовы агента: пометить себя на свежий перезапуск или тихо завершиться (для эфемерных воркеров).
+
+Поведение по классам рантаймов — [08 — Управление пирами](08-управление-пирами.md); эфемерные воркеры — [10 — Обмен сообщениями](10-обмен-сообщениями.md).

package/docs/ru/05-/321/201/320/270/321/201/321/202/320/265/320/274/320/275/321/213/320/271-/320/277/321/200/320/276/320/274/320/277/321/202.md

@@ -0,0 +1,82 @@
+# 05 — Идентичность и системный промпт
+
+**Русский** · [English](../05-system-prompt.md)
+
+Чтобы агент знал своё имя, роль и соседей по команде, iapeer собирает ему системный промпт — текст, который рантайм получает до начала диалога. Промпт складывается из слоёв: часть пишет человек, часть собирает система.
+
+## Зачем подменять системный промпт
+
+У Claude и Codex есть собственный встроенный системный промпт — тот, что делает их «ассистентом по коду». iapeer заменяет его целиком: вместо родного промпта рантайм получает собранный iapeer текст, где агент описан как пир команды — со своим именем, ролью, знанием о соседях и общими правилами.
+
+Замена идёт штатным механизмом каждого рантайма:
+
+- **Claude** — флагом `--system-prompt-file <файл>`;
+- **Codex** — настройкой `model_instructions_file` (`codex -c model_instructions_file=<файл>`), которая подменяет компилированные базовые инструкции.
+
+Инфраструктурные рантаймы (Telegram, notifier) системный промпт не получают — это не языковые модели, им нечего им наполнять.
+
+## Слои промпта
+
+Промпт собирается из слоёв, от общего к частному. Каждый слой при пустом содержимом просто выпадает — лишних разделов не появляется.
+
+```text
+1. Блок идентичности (YAML)          ← система, всегда свежий
+2. Доктрина IAPEER.md                 ← человек: общая + персональная
+3. Реестр пиров                       ← система: кто ещё в команде
+4. Доменные файлы (любой .md по имени)← человек/плагин
+5. Доктринальные фрагменты            ← плагины-примитивы, машинно
+```
+
+### Слой 1 — блок идентичности
+
+Динамический YAML-блок в начале промпта. Система синтезирует его при каждом запуске из профиля пира и фактов о хосте: имя, описание, рабочая папка, платформа, версия ОС, пользователь, имя машины, сегодняшняя дата. Значения экранируются, поэтому двоеточия, кавычки и переводы строк в описании не ломают разметку.
+
+Этот слой всегда свежий — дата и факты о хосте подставляются заново на каждый запуск.
+
+### Слой 2 — доктрина IAPEER.md
+
+Главный слой, который наполняет человек, — для пира то же, что `CLAUDE.md` для проекта: постоянные инструкции и характер агента. Это два файла:
+
+- **Общая доктрина** `~/.iapeer/IAPEER.md` — правила, действующие для всех пиров хоста: как отвечать на обращения, как обращаться с памятью, общие договорённости команды.
+- **Персональная доктрина** `<папка-пира>/.iapeer/IAPEER.md` — роль и характер конкретного пира: кто он, чем занимается, какие у него зоны ответственности.
+
+Порядок — от общего к частному: сначала общая доктрина, затем персональная. Частное идёт после общего и уточняет его. Каждый файл вставляется как отдельная помеченная секция со своей меткой-путём (HTML-комментарий с путём файла, видимый модели), чтобы агент понимал, откуда взялось каждое правило.
+
+Оба файла редактирует оператор обычным markdown. Это и есть то место, где задаётся, кем будет агент.
+
+### Слой 3 — реестр пиров
+
+Система вставляет краткую сводку по всем пирам команды: имя, основной рантайм, список рантаймов, описание, природа. Так агент знает, к кому он может обратиться через `send_to_peer` и кто чем занимается. Сводка отсортирована по именам; если пиров нет — слой выпадает.
+
+Здесь и работает само-документирующее `description` из профиля: оно ограничено по длине именно потому, что попадает в промпт каждого пира — раздутые описания стоили бы контекста всей команде.
+
+Для сервис-пира — скажем, `timer` и `watcher` нотифаера — это описание несёт сам формат вызова: JSON-поля и пример. Так агент умеет управлять сервисом из одного своего промпта, а когда нужно больше — просто спрашивает сервис (на `help` тот отвечает полным форматом). Реестр учит вызову; остальное пир документирует сам.
+
+### Слой 4 — доменные файлы по имени
+
+Любой markdown-файл в корне `.iapeer/`, кроме `IAPEER.md`, едет в промпт своей секцией. Этот канал открыт и вам, не только плагинам: положите `SOUL.md` (или любое имя) в `~/.iapeer/` — его увидит каждый пир хоста; положите в папку `.iapeer/` одного пира — увидит только он. Выдать агенту дополнительный контекст — это просто добавить файл.
+
+Как и доктрина, каждый файл бывает общим (`~/.iapeer/<ДОМЕН>.md`) и персональным (`<папка-пира>/.iapeer/<ДОМЕН>.md`), вставляется от общего к частному. Сканируется только корень `.iapeer/` — не подпапки. Файлы идут в детерминированном порядке (по алфавиту имени), каждый — отдельной помеченной секцией, пустые выпадают. Плагины пользуются этим же каналом для своих настроек (`<ДОМЕН>.md` на плагин); ваши файлы вручную и файлы плагина стоят бок о бок.
+
+### Слой 5 — доктринальные фрагменты
+
+Последний слой — фрагменты, которые генерируют машинно плагины-примитивы. Они лежат в подпапке `fragments/` обоих корней (`~/.iapeer/fragments/` и `<папка-пира>/.iapeer/fragments/`). Например, провайдер памяти кладёт сюда актуальную карту памяти агента.
+
+Этот слой — самый изменчивый, поэтому он идёт последним и **перечитывается на каждом свежем подъёме сессии**. Когда у агента меняется память или другой машинный контекст, обновлённый фрагмент попадёт в промпт при следующем запуске.
+
+## Сборка и неизменность в сессии
+
+Слои склеиваются в один файл с пустой строкой между секциями. Этот файл и передаётся рантайму флагом подмены промпта.
+
+Системный промпт фиксируется в момент подъёма сессии и не меняется, пока сессия живёт. Когда демон поднимает агента заново — свежим или продолжая прежний диалог, — он пересобирает файл, поэтому свежие фрагменты слоя 5 и актуальная дата подтягиваются на каждом подъёме. Это проверено: продолжение диалога переприменяет новый файл промпта, а не тянет старый.
+
+Подмена доставляет системный промпт iapeer — личность пира. Она не отключает собственные нативные файлы инструкций рантайма: `CLAUDE.md` (Claude) или `AGENTS.md` (Codex) работают ровно так же, как вне iapeer, — читаются как постоянные инструкции, которым модель следует. Это два независимых канала — личность iapeer через подмену и нативные `CLAUDE.md`/`AGENTS.md` рантайма — и действуют они вместе. Так что если вы приносите готовый проект, где уже есть `CLAUDE.md`, он продолжит работать рядом с промптом iapeer; а сами эти файлы работают и без iapeer вообще.
+
+## Что наполнять вам
+
+Из всех слоёв руками наполняют два файла:
+
+- `~/.iapeer/IAPEER.md` — общие правила команды (один раз на хост);
+- `<папка-пира>/.iapeer/IAPEER.md` — роль каждого пира.
+
+Остальное — блок идентичности, реестр, фрагменты — система и плагины собирают сами. Раскладку каталогов, где лежат эти файлы, разбирает [06 — Хранение](06-хранение.md).

package/docs/ru/06-/321/205/321/200/320/260/320/275/320/265/320/275/320/270/320/265.md

@@ -0,0 +1,115 @@
+# 06 — Хранение
+
+**Русский** · [English](../06-storage.md)
+
+Состояние iapeer лежит в двух местах: общий каталог хоста `~/.iapeer/` и каталог `.iapeer/` внутри рабочей папки каждого пира.
+
+## Два уровня хранения
+
+**Общий уровень** `~/.iapeer/` — всё, что касается хоста целиком: реестр пиров, состояние демона, общие настройки, установленные пакеты рантаймов.
+
+**Уровень пира** `<папка-пира>/.iapeer/` — всё, что касается одного пира: его профиль, доктрина, состояние его плагинов, журналы его сессий.
+
+Один и тот же плагин может хранить данные на обоих уровнях: общие — в `~/.iapeer/`, привязанные к конкретному пиру — в его папке.
+
+## Раскладка общего уровня
+
+```text
+~/.iapeer/
+├── IAPEER.md                  доктрина хоста (общая для всех пиров; слой 2 промпта)
+├── peers-profiles.json        реестр всех пиров (пишется под блокировкой)
+├── peers-profiles.lock        файл блокировки реестра
+├── memory-provider.json       слот памяти: кто провайдер (если занят)
+├── fragments/                 общие доктринальные фрагменты (слой 5 промпта)
+├── peers/
+│   └── <имя>/                 рабочая папка пира по умолчанию
+│       └── .iapeer/           (раскладка уровня пира — см. ниже)
+├── state/
+│   ├── iapeer/                состояние демона (router.sock, router.json …)
+│   └── <плагин>/              изменяемое состояние плагина
+├── logs/
+│   ├── iapeer/                журналы демона: lifecycle.log, delivery.log, exits.log
+│   └── <имя>/                 журналы инфраструктурного пира (по имени)
+├── cache/
+│   ├── iapeer/                кеш ядра
+│   └── <плагин>/              кеш плагина (можно удалять)
+├── plugins/
+│   ├── iap/                   установка ядрового плагина IAP
+│   └── <плагин>/              установка плагина (неизменяемая)
+└── runtimes/
+    ├── claude/
+    │   └── plugins/<плагин>/  конфиг плагина под рантаймом claude
+    ├── codex/
+    │   └── plugins/<плагин>/
+    ├── telegram/
+    │   └── runtime.json       манифест рантайм-пакета
+    └── notifier/
+        └── runtime.json
+```
+
+Несколько узлов стоит выделить:
+
+- **`peers-profiles.json`** — реестр. Пишется только через единственного писателя под файловой блокировкой `peers-profiles.lock`; прямое редактирование запрещено на уровне ядра.
+- **`state/iapeer/`** — здесь живёт демон: его локальный сокет `router.sock` и конфигурация `router.json`.
+- **`logs/<имя>/`** — журналы инфраструктурных пиров кладутся по имени пира на общем уровне (а не в папке пира), потому что это вывод службы под launchd.
+- **`runtimes/<рантайм>/`** — двойное владение: корень принадлежит самому рантайму (Telegram держит здесь токены ботов, состояние опроса), а подпапка `plugins/<плагин>/` — это пространство плагинов, где лежит их конфиг под этим рантаймом.
+
+## Раскладка уровня пира
+
+```text
+<папка-пира>/.iapeer/
+├── peer-profile.json          профиль пира — источник истины о нём
+├── IAPEER.md                  персональная доктрина (слой 2 промпта)
+├── fragments/                 персональные доктринальные фрагменты (слой 5)
+├── plugins/
+│   ├── iap/
+│   └── <плагин>/              данные плагина для этого пира
+├── state/
+│   ├── iap/
+│   └── <плагин>/
+├── logs/
+│   ├── iap/
+│   └── <плагин>/
+├── cache/
+│   ├── iap/
+│   └── <плагин>/
+└── runtimes/
+    ├── claude/
+    │   ├── launch.env         аргументы и переменные запуска для этого рантайма
+    │   └── plugins/<плагин>/
+    └── codex/
+        ├── launch.env
+        └── plugins/<плагин>/
+```
+
+- **`peer-profile.json`** — карточка пира и единственный источник истины о нём (поля разобраны в [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md)).
+- **`launch.env`** — файл вида `KEY=VALUE` для конкретной пары пир+рантайм: дополнительные аргументы запуска (`PEER_START_ARGS`) и переменные окружения. Так одному пиру можно задать особые флаги запуска, не трогая остальных.
+
+Рабочая папка пира не обязана лежать в `~/.iapeer/peers/`. По умолчанию `iapeer create` кладёт её туда, но пиром можно сделать любую папку командой `iapeer init` — тогда `.iapeer/` появится прямо в ней.
+
+## Кто чем владеет
+
+Граница владения проста: каждый владеет содержимым своей папки и не лезет в чужие.
+
+| Владелец | Что принадлежит |
+|---|---|
+| **Ядро (`iapeer`)** | `peers-profiles.json`, `state/iapeer/`, `logs/iapeer/`, `cache/iapeer/` |
+| **Рантайм** | корень `runtimes/<рантайм>/` — кроме подпапки `plugins/` |
+| **Плагин** | своя папка `<плагин>/` во всех категориях (`state`, `logs`, `cache`, `plugins`) на обоих уровнях |
+
+Имя `iapeer` в категориях зарезервировано за ядром. Рантайм никогда не трогает `plugins/<плагин>/` внутри своего пространства, а плагин — корень рантайма.
+
+## Классы данных по сроку жизни
+
+Установка отделена от изменяемых данных — это важно для обновлений и для уборки:
+
+- **Установка** (`plugins/<плагин>/`) — неизменяемая. Это разложенный код плагина; обновление заменяет его целиком.
+- **Состояние** (`state/`) — изменяемые данные, которые нужно беречь: их потеря — потеря работы.
+- **Журналы** (`logs/`) — вывод процессов; полезны для разбора, но не критичны. Что пишется в `lifecycle.log`, `delivery.log`, `exits.log` и как настроить их ротацию — [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md).
+- **Кеш** (`cache/`) — восстановимые данные; их можно удалить без последствий, система пересоздаст.
+
+Такое разделение означает, что обновить плагин — значит заменить его папку установки, не задев его состояние; а почистить место — значит удалить кеш, не рискуя данными.
+
+## Реестр как производная
+
+Стоит повторить ключевой принцип хранения: **реестр `peers-profiles.json` — это проекция локальных профилей, а не отдельный источник истины.** Источник истины о пире — его `peer-profile.json`. Реестр можно пересобрать из профилей в любой момент командой `iapeer verify --fix`. При расхождении между реестром и профилем прав профиль. Поэтому потеря или порча реестра не фатальна — он восстанавливается обходом рабочих папок пиров.

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                            # убедиться, что ожил
+```