@agfpd/iapeer 0.3.0 → 0.4.1

package/README.md

@@ -2,8 +2,9 @@
 
 **Host-level core for a team of AI agents on one machine.**
 
+[![CI](https://github.com/agfpd/iapeer/actions/workflows/ci.yml/badge.svg)](https://github.com/agfpd/iapeer/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@agfpd/iapeer)](https://www.npmjs.com/package/@agfpd/iapeer)
-[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+[![license](https://img.shields.io/npm/l/@agfpd/iapeer)](./LICENSE)
 [![platform](https://img.shields.io/badge/platform-macOS-lightgrey)](#quick-start)
 
 iapeer keeps a team of AI agents, humans, and services on one host **always reachable — every one of them a single message away.** Each participant is a **peer**: a Claude Code or Codex CLI agent, a person on Telegram, or a scheduler/watcher service. Any agent reaches any other with one call — `send_to_peer(<name>, <text>)` — and a peer that is asleep is still reachable: the daemon wakes it and delivers. Agents on Claude and on Codex — different AI runtimes from different vendors — talk as equal peers; humans take part over Telegram, or directly in the terminal — attached to a peer's live session with `iapeer attach`.

package/docs/03-peers-runtimes-identity.md

@@ -95,7 +95,7 @@ Identity has two storage places, and it matters which is authoritative.
   "intelligence": "artificial",
   "initial_prompt": "New session. Greet the owner.",
   "interfaces": {
-    "telegram": { "bot": "assistant", "bot_username": "assistant_bot" }
+    "telegram": { "bot": "assistant" }
   }
 }
 ```

package/docs/06-storage.md

@@ -33,6 +33,9 @@ The same plugin can store data at both levels: shared in `~/.iapeer/`, peer-boun
 ├── cache/
 │   ├── iapeer/                core cache
 │   └── <plugin>/              plugin cache (safe to delete)
+├── docs/
+│   ├── iapeer/                foundation reference docs (this host's installed version)
+│   └── <package>/             each ecosystem package's docs (copied on its install)
 ├── plugins/
 │   ├── iap/                   the core IAP plugin's install
 │   └── <plugin>/              a plugin's install (immutable)
@@ -53,6 +56,15 @@ A few nodes worth highlighting:
 - **`state/iapeer/`** — where the daemon lives: its local socket `router.sock` and config `router.json`.
 - **`logs/<name>/`** — an infrastructure peer's logs are placed by peer name at the shared level (not in the peer's folder), because it's the output of a launchd service.
 - **`runtimes/<runtime>/`** — dual ownership: the root belongs to the runtime itself (Telegram keeps bot tokens and poll state here), while the `plugins/<plugin>/` subfolder is the plugins' space, holding their config under this runtime.
+- **`docs/<package>/`** — on-host reference docs, one folder per ecosystem package (see below).
+
+## On-host ecosystem docs
+
+`~/.iapeer/docs/<package>/` holds a copy of each ecosystem package's reference docs, so an agent can read the contract offline at a stable, versioned path. It exists because a compiled binary embeds no docs and the npm tarball's `docs/` is discarded after install — a reference into a transient install or cache directory would go dead on the first update.
+
+The convention is **copy-on-install, per package**: every package copies its own public docs (excluding `internals/`) into its own `~/.iapeer/docs/<package>/` on each of its installs and updates, via an atomic swap, best-effort — a copy failure never fails the install. Because the copy happens in the same install that places the artifact, a package's on-host docs always match its installed version. Each package writes only its own subfolder, the same ownership isolation as everywhere else; the folder name is the short unscoped package name (`iapeer`, `iapeer-memory`, `telegram-runtime`, `notifier-runtime`).
+
+A peer's system prompt points here — `~/.iapeer/docs/`, one folder per package, starting at `iapeer/README.md` — so a "how does iapeer do X" question is answered from the docs rather than guessed.
 
 ## The peer-level layout
 

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

@@ -95,7 +95,7 @@ PEER_IDENTITY = PEER_RUNTIME + "-" + PEER_PERSONALITY
   "intelligence": "artificial",
   "initial_prompt": "Новая сессия. Поздоровайся с владельцем.",
   "interfaces": {
-    "telegram": { "bot": "assistant", "bot_username": "assistant_bot" }
+    "telegram": { "bot": "assistant" }
   }
 }
 ```

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

@@ -33,6 +33,9 @@
 ├── cache/
 │   ├── iapeer/                кеш ядра
 │   └── <плагин>/              кеш плагина (можно удалять)
+├── docs/
+│   ├── iapeer/                справочные доки фундамента (версия, установленная на хосте)
+│   └── <пакет>/               доки каждого пакета экосистемы (копируются при его установке)
 ├── plugins/
 │   ├── iap/                   установка ядрового плагина IAP
 │   └── <плагин>/              установка плагина (неизменяемая)
@@ -53,6 +56,15 @@
 - **`state/iapeer/`** — здесь живёт демон: его локальный сокет `router.sock` и конфигурация `router.json`.
 - **`logs/<имя>/`** — журналы инфраструктурных пиров кладутся по имени пира на общем уровне (а не в папке пира), потому что это вывод службы под launchd.
 - **`runtimes/<рантайм>/`** — двойное владение: корень принадлежит самому рантайму (Telegram держит здесь токены ботов, состояние опроса), а подпапка `plugins/<плагин>/` — это пространство плагинов, где лежит их конфиг под этим рантаймом.
+- **`docs/<пакет>/`** — справочные доки на хосте, по одной папке на каждый пакет экосистемы (см. ниже).
+
+## Доки экосистемы на хосте
+
+`~/.iapeer/docs/<пакет>/` хранит копию справочных доков каждого пакета экосистемы, чтобы агент мог читать контракт офлайн по стабильному версионированному пути. Это нужно потому, что скомпилированный бинарь доков не несёт, а `docs/` из npm-тарбола выбрасывается после установки — ссылка во временный каталог установки или кеша умерла бы на первом же обновлении.
+
+Конвенция — **копирование при установке, по пакету**: каждый пакет копирует свои публичные доки (исключая `internals/`) в свою папку `~/.iapeer/docs/<пакет>/` при каждой своей установке и обновлении, атомарной заменой, best-effort — сбой копирования никогда не валит установку. Поскольку копирование происходит в той же установке, что кладёт артефакт, доки пакета на хосте всегда соответствуют его установленной версии. Каждый пакет пишет только свою подпапку — та же изоляция владения, что и везде; имя папки — короткое unscoped-имя пакета (`iapeer`, `iapeer-memory`, `telegram-runtime`, `notifier-runtime`).
+
+Системный промпт пира указывает сюда — `~/.iapeer/docs/`, по папке на пакет, начиная с `iapeer/README.md`, — чтобы вопрос «как iapeer делает X» отвечался из доков, а не угадывался.
 
 ## Раскладка уровня пира
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -13,6 +13,7 @@
 import { spawnSync } from 'child_process'
 import { existsSync, readFileSync } from 'fs'
 import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
 import {
   isInfraRuntime,
   isRuntime,
@@ -157,14 +158,23 @@ export function listPeers(opts: CliEnvOptions = {}): PeerListing[] {
 
 const GLYPH: Record<RuntimeLiveness, string> = { live: '●', asleep: '○', stopped: '✕' }
 
-/** Render the scriptable list table (non-tty default). */
+/** Render the scriptable list table (non-tty default). Columns are PADDED to align
+ *  (name · [default] · nature · liveness) — a ragged table reads as noise. The
+ *  trailing liveness column is variable-width, so it needs no padding. */
 export function formatListTable(rows: PeerListing[]): string {
   if (rows.length === 0) return 'no peers registered\n'
-  const lines = rows.map(r => {
-    const status = r.runtimes.map(s => `${GLYPH[s.status]} ${s.runtime}`).join('  ')
-    const la = r.last_active_runtime ? ` last-active:${r.last_active_runtime}` : ''
-    return `${r.personality}  [${r.default_runtime}]  ${r.intelligence}  ${status}${la}`
-  })
+  const cells = rows.map(r => ({
+    name: r.personality,
+    rt: `[${r.default_runtime}]`,
+    intel: r.intelligence,
+    status:
+      r.runtimes.map(s => `${GLYPH[s.status]} ${s.runtime}`).join('  ') +
+      (r.last_active_runtime ? `  last-active:${r.last_active_runtime}` : ''),
+  }))
+  const wName = Math.max(...cells.map(c => c.name.length))
+  const wRt = Math.max(...cells.map(c => c.rt.length))
+  const wIntel = Math.max(...cells.map(c => c.intel.length))
+  const lines = cells.map(c => `${c.name.padEnd(wName)}  ${c.rt.padEnd(wRt)}  ${c.intel.padEnd(wIntel)}  ${c.status}`)
   return lines.join('\n') + '\n'
 }
 
@@ -939,48 +949,146 @@ export function parseArgs(argv: string[]): { positionals: string[]; flags: Recor
   return { positionals, flags }
 }
 
-const USAGE = `usage: iapeer <verb> [args]
-  install                                                        build binary + global scaffold + daemon plist (one bootstrap)
-  update [version] [--force]                                     pull latest (or exact) @agfpd/iapeer from npm + restart daemon + recycle owned infra jobs
-  rollback                                                       revert to the previous binary (.prev) + restart daemon + recycle owned infra jobs
-  version | --version | -v                                       print the installed binary's version
-  help | --help | -h                                             print this usage (works appended to any verb; executes nothing)
-  daemon [--install-plist]                                       run the host-wide HTTP-MCP router (launchd-held)
-  onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--infra <csv>]
-                                                                 backbone host-phase: marketplace → notifier → telegram (human peer) → memory (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively
-  status                                                         host snapshot: version, daemon health, memory slot (<provider> | none)
-  install-runtime <runtime> [--package pkg] [--npx]              npx-install a runtime package + deploy its declared peer-set
-  update-runtime <runtime> | --all [--force]                     version-gate → re-install + re-provision declared set → restart the runtime's peers
-  init [cwd] [--runtime r] [--description d]                     onboard the CURRENT folder as a peer (name = folder name; identity + MCP + doctrine)
-  create <personality> [--runtime r] [--path dir] [--bin abs]   create a peer anywhere (default ~/.iapeer/peers/<p>) + provision
-  list [--json]                                                  registered peers + per-runtime liveness
-  verify [--json] [--fix]                                        profile-standard conformance + index↔local drift (--fix self-heals the index + migrates legacy runtime→default_runtime in local profiles)
-  stop <peer> [runtime] | --all                                  warm peer: kill the live session + set a durable stop-flag — the daemon will NOT wake it
-                                                                 until \`start\`; always-on (notifier/telegram): launchctl bootout. --all = every registered peer
-  start <peer> [runtime] | --all                                 warm peer: clear the stop-flag — wakeable again; does NOT launch a session (the daemon brings
-                                                                 it up on the peer's first message); always-on: launchctl bootstrap. --all = every registered peer
-  refresh <peer> [runtime] | --all                               LAZY soft-reload: agentic peer comes up FRESH (re-reads doctrine) on its NEXT natural wake — no
-                                                                 kill, no burst-wake; non-agentic runtimes skipped. --all = whole fleet. (eager: \`new\`/self-fresh)
-  remove <peer> [--force]                                        delete a peer's registry record (locked writer); refuses a LIVE peer unless --force
-  send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]   manual IAP send (fallback)
-  <runtime>                                                      launch the cwd's peer FRESH; on a TTY drop into it (like attach), else detached
-  connect telegram <peer> [--token <t>]                          attach a telegram bot to a peer (bot add → interface → router restart; asks only the token)
-  enable <plugin> [peer] [--no-setup]                            install + enable an agfpd capability for a peer
-  new <peer> [runtime]                                           UNCONDITIONAL fresh restart: canary-clean kill + fresh wake (emergency lever for a hung/dead session — bypasses the peer; exit 0 = fresh session up+ready)
-  add-runtime <runtime> (--peer <p> | --all)                     add an agentic runtime to existing peer(s): runtimes-merge + scaffold + codex birth chain (pre-trust, native-memory, memory provision, MCP). default_runtime untouched
-  default-runtime <runtime> (--peer <p> | --all)                 flip the PRIMARY (routing/wake default) — the fleet-switch lever; refuses an undeclared runtime; registry self-healed in the same command
-  attach <peer> [runtime]                                        ensure-live + resume, then tmux attach
-  interrupt <peer> [runtime]                                     interrupt the current turn (Escape) — context intact
-  compact <peer> [runtime]                                       compact the peer's dialogue (/compact); resumes clean-asleep first
-  self-fresh                                                     (agent self-call) mark /new eager-fresh + self-kill — the daemon relaunches fresh
-  self-done                                                      (agent self-call, ephemeral) silent finish: arm own quiet-reap, wake no one
-  native-memory <off|on> (--peer <p> | --all)                    gate/restore runtimes' native memory (canonized lever; контракт «Слот памяти»)
-  trust-hooks <hooks.json> [--check]                             pre-seed codex hooks trust for a file-form hooks.json (no modal); --check = drift report
-  shadow [--once | --minutes <m>] [--interval <ms>]              READ-ONLY tmux→pty fidelity observer (migration burn-in): compares pty-model verdicts vs live tmux on the warm fleet → ~/.iapeer/logs/iapeer/shadow-fidelity.json. Never delivers/mutates.
-  shadow-install                                                 install + load the always-on shadow burn-in launchd job (com.iapeer.shadow-fidelity); idempotent, re-cycled by update/rollback
-  shadow-uninstall                                               bootout + remove the shadow burn-in launchd job (the correct way to stop it; STOP file is respawned past by KeepAlive)
-  supervisor up|start|attach|list|kill <sess> [runtime]         DARK (cutover Block 2): detach-persistent pty-supervisor PoC port; serves nothing on the live fleet (throwaway validation only)
-`
+/** Verb catalog for `help` — structured so the renderer can wrap descriptions to
+ *  the terminal width instead of overflowing a hand-aligned column (the old static
+ *  USAGE ran long descriptions off the right edge → collided with the next row on a
+ *  narrow terminal). `sig` = the invocation signature, `desc` = one prose line. */
+const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
+  { sig: 'install', desc: 'build binary + global scaffold + daemon plist (one bootstrap)' },
+  { sig: 'update [version] [--force]', desc: 'pull latest (or exact) @agfpd/iapeer from npm + restart daemon + recycle owned infra jobs' },
+  { sig: 'rollback', desc: 'revert to the previous binary (.prev) + restart daemon + recycle owned infra jobs' },
+  {
+    sig: 'uninstall [--dry-run] [--yes] [--remove-codesign-identity]',
+    desc: 'remove THIS foundation install (binary, ~/.iapeer, daemon plist, PATH lines); refuses if a persistent-peer fleet is present',
+  },
+  { sig: 'version | --version | -v', desc: "print the installed binary's version" },
+  { sig: 'help | --help | -h', desc: 'print this usage (works appended to any verb; executes nothing)' },
+  { sig: 'daemon [--install-plist]', desc: 'run the host-wide HTTP-MCP router (launchd-held)' },
+  {
+    sig: 'onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--infra <csv>]',
+    desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
+  },
+  { sig: 'status', desc: 'host snapshot: version, daemon health, memory slot (<provider> | none)' },
+  { sig: 'install-runtime <runtime> [--package pkg] [--npx]', desc: 'npx-install a runtime package + deploy its declared peer-set' },
+  { sig: 'update-runtime <runtime> | --all [--force]', desc: "version-gate → re-install + re-provision declared set → restart the runtime's peers" },
+  { sig: 'init [cwd] [--runtime r] [--description d]', desc: 'onboard the CURRENT folder as a peer (name = folder name; identity + MCP + doctrine)' },
+  { sig: 'create <personality> [--runtime r] [--path dir] [--bin abs]', desc: 'create a peer anywhere (default ~/.iapeer/peers/<p>) + provision' },
+  { sig: 'list [--json]', desc: 'registered peers + per-runtime liveness' },
+  {
+    sig: 'verify [--json] [--fix]',
+    desc: 'profile-standard conformance + index↔local drift (--fix self-heals the index + migrates legacy runtime→default_runtime in local profiles)',
+  },
+  {
+    sig: 'stop <peer> [runtime] | --all',
+    desc: 'warm peer: kill the live session + set a durable stop-flag — the daemon will NOT wake it until `start`; always-on (notifier/telegram): launchctl bootout. --all = every registered peer',
+  },
+  {
+    sig: 'start <peer> [runtime] | --all',
+    desc: "warm peer: clear the stop-flag — wakeable again; does NOT launch a session (the daemon brings it up on the peer's first message); always-on: launchctl bootstrap. --all = every registered peer",
+  },
+  {
+    sig: 'refresh <peer> [runtime] | --all',
+    desc: 'LAZY soft-reload: agentic peer comes up FRESH (re-reads doctrine) on its NEXT natural wake — no kill, no burst-wake; non-agentic runtimes skipped. --all = whole fleet. (eager: `new`/self-fresh)',
+  },
+  { sig: 'remove <peer> [--force]', desc: 'delete a peer\'s registry record (locked writer); refuses a LIVE peer unless --force' },
+  {
+    sig: 'send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]',
+    desc: 'manual IAP send (fallback)',
+  },
+  { sig: '<runtime>', desc: "launch the cwd's peer FRESH; on a TTY drop into it (like attach), else detached" },
+  { sig: 'connect telegram <peer> [--token <t>]', desc: 'attach a telegram bot to a peer (bot add → interface → router restart; asks only the token)' },
+  { sig: 'enable <plugin> [peer] [--no-setup]', desc: 'install + enable an agfpd capability for a peer' },
+  {
+    sig: 'new <peer> [runtime]',
+    desc: 'UNCONDITIONAL fresh restart: canary-clean kill + fresh wake (emergency lever for a hung/dead session — bypasses the peer; exit 0 = fresh session up+ready)',
+  },
+  {
+    sig: 'add-runtime <runtime> (--peer <p> | --all)',
+    desc: 'add an agentic runtime to existing peer(s): runtimes-merge + scaffold + codex birth chain (pre-trust, native-memory, memory provision, MCP). default_runtime untouched',
+  },
+  {
+    sig: 'default-runtime <runtime> (--peer <p> | --all)',
+    desc: 'flip the PRIMARY (routing/wake default) — the fleet-switch lever; refuses an undeclared runtime; registry self-healed in the same command',
+  },
+  { sig: 'attach <peer> [runtime]', desc: 'ensure-live + resume, then tmux attach' },
+  { sig: 'interrupt <peer> [runtime]', desc: 'interrupt the current turn (Escape) — context intact' },
+  { sig: 'compact <peer> [runtime]', desc: 'compact the peer\'s dialogue (/compact); resumes clean-asleep first' },
+  { sig: 'self-fresh', desc: '(agent self-call) mark /new eager-fresh + self-kill — the daemon relaunches fresh' },
+  { sig: 'self-done', desc: '(agent self-call, ephemeral) silent finish: arm own quiet-reap, wake no one' },
+  { sig: 'native-memory <off|on> (--peer <p> | --all)', desc: "gate/restore runtimes' native memory (canonized lever; контракт «Слот памяти»)" },
+  { sig: 'trust-hooks <hooks.json> [--check]', desc: 'pre-seed codex hooks trust for a file-form hooks.json (no modal); --check = drift report' },
+  {
+    sig: 'shadow [--once | --minutes <m>] [--interval <ms>]',
+    desc: 'READ-ONLY tmux→pty fidelity observer (migration burn-in): compares pty-model verdicts vs live tmux on the warm fleet → ~/.iapeer/logs/iapeer/shadow-fidelity.json. Never delivers/mutates.',
+  },
+  { sig: 'shadow-install', desc: 'install + load the always-on shadow burn-in launchd job (com.iapeer.shadow-fidelity); idempotent, re-cycled by update/rollback' },
+  { sig: 'shadow-uninstall', desc: 'bootout + remove the shadow burn-in launchd job (the correct way to stop it; STOP file is respawned past by KeepAlive)' },
+  {
+    sig: 'supervisor up|start|attach|list|kill <sess> [runtime]',
+    desc: 'DARK (cutover Block 2): detach-persistent pty-supervisor PoC port; serves nothing on the live fleet (throwaway validation only)',
+  },
+]
+
+/** Greedy word-wrap to `width` columns. A token longer than `width` keeps its own
+ *  line (overflows rather than being split — never break a flag/path mid-token). */
+export function wrapText(text: string, width: number): string[] {
+  const words = text.split(/\s+/).filter(Boolean)
+  if (words.length === 0) return ['']
+  const out: string[] = []
+  let cur = ''
+  for (const w of words) {
+    if (cur === '') cur = w
+    else if (cur.length + 1 + w.length <= width) cur += ` ${w}`
+    else {
+      out.push(cur)
+      cur = w
+    }
+  }
+  if (cur !== '') out.push(cur)
+  return out
+}
+
+/** The terminal width to lay help out for — capped so an ultrawide terminal doesn't
+ *  stretch descriptions into unreadably long lines; 80 when not a TTY. */
+function helpWidth(): number {
+  const c = process.stdout.columns
+  return c && c > 0 ? Math.min(c, 100) : 80
+}
+
+/** Render `iapeer help` as an aligned two-column block that wraps to `width`.
+ *  Signatures that fit the left column print inline with their (wrapped) description
+ *  in the right column; over-long signatures wrap on their own lines first, then the
+ *  description follows at the same right-column indent. Deterministic + width-pure
+ *  so it is unit-testable. */
+export function renderUsage(width: number = helpWidth()): string {
+  const W = Math.max(40, width)
+  const INDENT = 2
+  const GUTTER = 2
+  // Left column: longest signature, but capped (≤44, and shrunk on a narrow
+  // terminal) so the right column always keeps a readable ~20+ cols.
+  const longest = Math.max(...VERBS.map(v => v.sig.length))
+  const leftCol = Math.min(longest, 44, Math.max(16, W - 26))
+  const rightStart = INDENT + leftCol + GUTTER
+  const rightWidth = Math.max(20, W - rightStart)
+  const rightPad = ' '.repeat(rightStart)
+  const lines: string[] = ['usage: iapeer <verb> [args]']
+  for (const v of VERBS) {
+    const desc = wrapText(v.desc, rightWidth)
+    if (v.sig.length <= leftCol) {
+      lines.push(`${' '.repeat(INDENT)}${v.sig.padEnd(leftCol)}${' '.repeat(GUTTER)}${desc[0] ?? ''}`)
+      for (const d of desc.slice(1)) lines.push(rightPad + d)
+    } else {
+      // Over-long signature: wrap it across its own lines (continuation indented),
+      // then the description at the shared right-column indent. Wrap to leave room
+      // for the deeper continuation indent (INDENT+2) so no wrapped sig line spills.
+      const sigLines = wrapText(v.sig, W - INDENT - 2)
+      lines.push(' '.repeat(INDENT) + sigLines[0])
+      for (const s of sigLines.slice(1)) lines.push(' '.repeat(INDENT + 2) + s)
+      for (const d of desc) lines.push(rightPad + d)
+    }
+  }
+  return lines.join('\n') + '\n'
+}
 
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
   const [verb, ...rest] = argv
@@ -992,7 +1100,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
   // match is safe: the look-ahead parser never consumes a `--`-token as a value, so
   // a LITERAL "--help" value is only expressible as `--key=--help` (not intercepted).
   if (verb === 'help' || argv.includes('--help') || argv.includes('-h')) {
-    process.stdout.write(USAGE)
+    process.stdout.write(renderUsage())
     return 0
   }
   const { positionals, flags } = parseArgs(rest)
@@ -1296,10 +1404,40 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // scaffold the folder (no-clobber), then init it. Operator-add for an infra
         // human (telegram) or any agentic peer; provisions + auto-bootstraps infra.
         if (!positionals[0]) return usage(errOut)
+        const explicitRuntime = typeof flags.runtime === 'string' ? (flags.runtime as Runtime) : undefined
+        // FU5 — never SILENTLY default to claude when both agentic runtimes are
+        // installed. `--runtime` selects the DEFAULT (not the sole runtime); the
+        // model is `runtimes` = all installed agentic runtimes, `default_runtime` =
+        // the one chosen. So: resolve the default explicitly (prompt on a TTY, a loud
+        // note off it) and auto-configure the other installed runtime(s) so the
+        // `runtimes` list is TRUTHFUL — each listed runtime is actually wired.
+        let chosenRuntime = explicitRuntime
+        let extraRuntimes: Runtime[] = []
+        if (!explicitRuntime || !isInfraRuntime(explicitRuntime)) {
+          const { isRuntimeInstalled } = await import('../init/index.ts')
+          const { planCreateRuntimes, secondaryRuntimes } = await import('../create/index.ts')
+          const installed = (['claude', 'codex'] as Runtime[]).filter(rt => isRuntimeInstalled(rt, env))
+          const plan = planCreateRuntimes(explicitRuntime, installed)
+          if (plan.ambiguous) {
+            chosenRuntime =
+              process.stdin.isTTY === true && process.stdout.isTTY === true
+                ? await promptDefaultRuntime(plan.installedAgentic)
+                : (errOut(
+                    `note: ${plan.installedAgentic.join(' and ')} are both installed — defaulting to "${plan.fallbackDefault}". ` +
+                      'Pass --runtime to choose the default, or run create in a terminal to be asked.\n',
+                  ),
+                  plan.fallbackDefault)
+          } else {
+            chosenRuntime = plan.resolvedDefault
+          }
+          // installed.length === 0 → chosenRuntime stays undefined; createPeer surfaces
+          // the clear "no agentic runtime installed" error.
+          extraRuntimes = secondaryRuntimes(chosenRuntime, installed)
+        }
         const { createPeer } = await import('../create/index.ts')
         const r = await createPeer({
           personality: positionals[0],
-          runtime: typeof flags.runtime === 'string' ? (flags.runtime as Runtime) : undefined,
+          runtime: chosenRuntime,
           path: typeof flags.path === 'string' ? flags.path : undefined,
           description: typeof flags.description === 'string' ? flags.description : undefined,
           intelligence: typeof flags.intelligence === 'string' ? (flags.intelligence as Intelligence) : undefined,
@@ -1308,8 +1446,24 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           env,
           warn: m => errOut(`warn: ${m}\n`),
         })
+        // Wire the other installed agentic runtime(s) — addRuntime is capability-only
+        // (merges `runtimes`, runs the runtime's birth chain, NEVER flips the default).
+        // Best-effort: a peer is usable on its default even if a secondary warns.
+        const addedRuntimes: Runtime[] = []
+        for (const rt of extraRuntimes) {
+          try {
+            const outcomes = await addRuntime(rt, { peer: r.personality, env })
+            const o = outcomes.find(x => x.personality === r.personality)
+            if (o && (o.action === 'added' || o.action === 'already')) addedRuntimes.push(rt)
+            else errOut(`warn: could not add runtime "${rt}": ${o?.detail ?? o?.action ?? 'failed'}\n`)
+          } catch (e) {
+            errOut(`warn: could not add runtime "${rt}": ${e instanceof Error ? e.message : String(e)}\n`)
+          }
+        }
+        const allRuntimes = [r.runtime, ...addedRuntimes]
         out(
-          `created "${r.personality}" (${r.runtime}) at ${r.location}; mcp: ${r.mcpConfigPaths.join(', ') || r.codexMcpConfigPath || 'none'}` +
+          `created "${r.personality}" (default: ${r.runtime}; runtimes: ${allRuntimes.join(', ')}) at ${r.location}; ` +
+            `mcp: ${r.mcpConfigPaths.join(', ') || r.codexMcpConfigPath || 'none'}` +
             `${r.plistPath ? `; plist: ${r.plistPath}` : ''}${r.bootstrapped ? `; bootstrap: ${r.bootstrapped.state}` : ''}\n`,
         )
         return r.bootstrapped && (r.bootstrapped.state === 'failed' || r.bootstrapped.state === 'refused-foreign') ? 1 : 0
@@ -1639,6 +1793,53 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         ;(failed ? errOut : out)(msg)
         return failed ? 1 : 0
       }
+      case 'uninstall': {
+        // Symmetric foundation removal (namespace-safe; REFUSES on a foreign fleet).
+        // DESTRUCTIVE — removes ~/.iapeer (all peers/memory/logs). --dry-run previews;
+        // --yes skips the confirm; --remove-codesign-identity also drops the shared
+        // agfpd signing identity (otherwise kept).
+        const { planUninstall, executeUninstall } = await import('../uninstall/index.ts')
+        const removeCodesign = flags['remove-codesign-identity'] === true
+        const plan = planUninstall({ env, removeCodesignIdentity: removeCodesign })
+        if (plan.refused) {
+          errOut(`uninstall refused — ${plan.refused.reason}\n`)
+          return 1
+        }
+        out('iapeer uninstall — will remove:\n')
+        for (const it of plan.items) {
+          const mark = it.present ? '•' : '·'
+          const tail = it.detail ? ` — ${it.detail}` : it.present ? '' : ' — already gone'
+          out(`  ${mark} ${it.what}${it.path ? `  (${it.path})` : ''}${tail}\n`)
+        }
+        if (flags['dry-run'] === true) {
+          out('\n(dry-run — nothing removed)\n')
+          return 0
+        }
+        if (flags.yes !== true) {
+          if (process.stdin.isTTY !== true) {
+            errOut('\nuninstall is destructive (removes ~/.iapeer) — re-run with --yes in a non-interactive shell.\n')
+            return 2
+          }
+          const { createInterface } = await import('node:readline/promises')
+          const rl = createInterface({ input: process.stdin, output: process.stdout })
+          let answer = ''
+          try {
+            answer = (await rl.question('\nThis permanently removes iapeer and ALL its data. Continue? [y/N] ')).trim().toLowerCase()
+          } finally {
+            rl.close()
+          }
+          if (answer !== 'y' && answer !== 'yes') {
+            out('uninstall aborted.\n')
+            return 1
+          }
+        }
+        const res = executeUninstall({ env, removeCodesignIdentity: removeCodesign })
+        for (const r of res.removed) out(`  removed: ${r}\n`)
+        for (const s of res.skipped) out(`  skipped (absent): ${s}\n`)
+        for (const f of res.failed) errOut(`  FAILED: ${f.what} — ${f.detail}\n`)
+        out(res.failed.length ? '\nuninstall finished with errors (see above).\n' : '\niapeer uninstalled. (bun left in place.)\n')
+        return res.failed.length ? 1 : 0
+      }
       case 'install': {
         // UNIFIED foundation install (contract Установка §1 — "один npx ставит
         // фундамент"): ONE command does all three install-phase steps that used to be
@@ -1651,9 +1852,19 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // Bootstrap path — run from the src tree (`bun src/cli/index.ts install`) or
         // npx; the compiled binary cannot rebuild itself from source (its
         // import.meta.url is the binary → build fails with a clear error).
-        const { installIapeer } = await import('../install/index.ts')
+        const { installIapeer, scaffoldHostDocs } = await import('../install/index.ts')
+        const { ensureGlobalDoctrineTemplate } = await import('../init/index.ts')
         ensureGlobalIapScaffold({ env })
+        // FU11 — scaffold the GLOBAL host-doctrine stub ~/.iapeer/IAPEER.md (Layer-2
+        // global doctrine, consumed at launch but previously never created — asymmetric
+        // with the per-peer stub). Idempotent: never overwrites an owner's host doctrine.
+        const hostDoctrine = ensureGlobalDoctrineTemplate(env)
         const r = installIapeer(fileURLToPath(import.meta.url), env)
+        // FU6 — copy the foundation contract docs to the stable per-package host path
+        // ~/.iapeer/docs/iapeer/ (the ecosystem convention: each package copies its OWN
+        // docs on its OWN install, version = its binary). install runs from source, so
+        // docs/ sits at <entry>/../../docs. Best-effort: never fails the install.
+        const docs = scaffoldHostDocs('iapeer', join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'docs'), env)
         const { path: plist, changed: plistChanged } = installDaemonPlist({ env })
         const signingLine =
           r.signing == null
@@ -1667,6 +1878,8 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
             `${r.size ? ` (${Math.round(r.size / 1e6)}M)` : ''}\n` +
             signingLine +
             `  scaffold: ~/.iapeer/ ensured (peers/, state, logs, cache, runtimes)\n` +
+            `  host doctrine: ${hostDoctrine.path}${hostDoctrine.created ? ' (stub created — fill it in)' : ' (kept)'}\n` +
+            `  docs: ${docs.copied ? docs.dest : `skipped (${docs.reason})`}\n` +
             `  daemon plist ${plistChanged ? 'written' : 'unchanged (byte-identical — no write, no BTM notification)'}: ${plist}\n` +
             `  (NOT loaded — a live daemon migration is a separate step: launchctl bootstrap gui/$(id -u) ${plist})\n`,
         )
@@ -1940,10 +2153,33 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
 }
 
 function usage(errOut: (s: string) => void): number {
-  errOut(USAGE)
+  errOut(renderUsage())
   return 2
 }
 
+/** Interactive default-runtime picker (FU5) — only called on a real TTY when more
+ *  than one agentic runtime is installed and no `--runtime` was given. Accepts a
+ *  number or the runtime name; empty input takes the first (the listed default). */
+async function promptDefaultRuntime(installed: Runtime[]): Promise<Runtime> {
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    process.stdout.write('More than one agent runtime is installed. Which should this peer default to?\n')
+    installed.forEach((rt, i) => process.stdout.write(`  [${i + 1}] ${rt}\n`))
+    for (;;) {
+      const ans = (await rl.question(`Choose [1-${installed.length}] (default 1): `)).trim().toLowerCase()
+      if (ans === '') return installed[0]!
+      const n = Number(ans)
+      if (Number.isInteger(n) && n >= 1 && n <= installed.length) return installed[n - 1]!
+      const byName = installed.find(rt => rt === ans)
+      if (byName) return byName
+      process.stdout.write(`Please enter a number 1-${installed.length} or a runtime name (${installed.join(' / ')}).\n`)
+    }
+  } finally {
+    rl.close()
+  }
+}
+
 /** Default --from for `send`: the identity of the peer in the current cwd (contract:
  *  "по умолчанию — identity пира текущей папки"). Requires running from a peer cwd. */
 function defaultFromIdentity(env: NodeJS.ProcessEnv): string {

package/src/create/index.ts

@@ -28,6 +28,44 @@ import { defaultPeerCwd, ensureGlobalIapScaffold } from '../storage/index.ts'
 import { readPeerProfile } from '../identity/index.ts'
 import { initPeer, type InitPeerResult } from '../init/index.ts'
 
+/** The default-runtime decision for `create` (FU5), factored out pure + testable.
+ *  `--runtime` selects the DEFAULT, not the sole runtime; the model is `runtimes` =
+ *  all installed agentic runtimes, `default_runtime` = the chosen one. */
+export interface CreateRuntimePlan {
+  /** True only when the default is AMBIGUOUS — more than one agentic runtime is
+   *  installed and no `--runtime` was given. The caller prompts on a TTY; off a TTY
+   *  it falls back to `fallbackDefault` with a loud note (never a silent claude). */
+  ambiguous: boolean
+  /** The resolved default when NOT ambiguous. `undefined` means "let initPeer
+   *  resolve it" — exactly one installed → that one, none → its clear error. */
+  resolvedDefault?: Runtime
+  /** The deterministic default to use when ambiguous + non-interactive. */
+  fallbackDefault?: Runtime
+  /** The installed agentic runtimes — the prompt candidates and the basis for the
+   *  secondary runtimes to wire (all of them except the chosen default). */
+  installedAgentic: Runtime[]
+}
+
+/**
+ * Decide create's default runtime + whether a prompt is needed, from the explicit
+ * `--runtime` (if any) and the set of installed agentic runtimes. Pure: the caller
+ * supplies `installedAgentic` (probed via isRuntimeInstalled) and performs the TTY
+ * prompt; this only encodes the policy.
+ */
+export function planCreateRuntimes(explicit: Runtime | undefined, installedAgentic: Runtime[]): CreateRuntimePlan {
+  if (explicit) return { ambiguous: false, resolvedDefault: explicit, installedAgentic }
+  if (installedAgentic.length > 1) return { ambiguous: true, fallbackDefault: installedAgentic[0], installedAgentic }
+  if (installedAgentic.length === 1) return { ambiguous: false, resolvedDefault: installedAgentic[0], installedAgentic }
+  return { ambiguous: false, resolvedDefault: undefined, installedAgentic }
+}
+
+/** The other installed agentic runtimes to wire after creating on `chosen` (so the
+ *  `runtimes` list is truthful). Empty when `chosen` is undefined/infra. */
+export function secondaryRuntimes(chosen: Runtime | undefined, installedAgentic: Runtime[]): Runtime[] {
+  if (!chosen) return []
+  return installedAgentic.filter(rt => rt !== chosen)
+}
+
 export interface CreatePeerOptions {
   /** The peer's personality (REQUIRED; validated/normalized). Drives the default
    *  location (~/.iapeer/peers/<personality>) and the registry/profile identity. */

package/src/daemon/index.ts

@@ -81,9 +81,11 @@ export function resolveCallerFromHeader(value: string | undefined, index: PeersI
 // Embedding it here ALSO duplicated the full list into every agent's context on every
 // turn — confirmed live: an agent saw the identical roster twice. The
 // description stays light: purpose + parameter semantics only; the model gets the
-// roster from its system prompt. Likewise the MCP server-level `instructions` field is
-// left unset (createMcpServer) — it would re-inject doctrine into the client system
-// prompt, re-creating the very duplication this removed. Static (no index needed).
+// roster from its system prompt. The MCP server-level `instructions` field carries
+// EXACTLY ONE cross-cutting behavioral rule (the owner-approved no-empty-acks guide,
+// SERVER_INSTRUCTIONS) — it loads ONCE per session at initialize (not per turn), so it
+// is cheap; it deliberately does NOT restate the roster/doctrine (that lives in the
+// system prompt — duplicating it here is the mistake this note warns of). Static.
 export function buildSendDescription(): string {
   return [
     'Send a message to a known iapeer peer through Inter-Agent-Protocol.',
@@ -94,6 +96,13 @@ export function buildSendDescription(): string {
   ].join('\n')
 }
 
+// MCP server-level `instructions` — returned in the initialize result, loaded ONCE
+// per session (NOT per turn like the tool description), so it is the cheap home for
+// a single cross-cutting behavioral rule. VERBATIM owner-approved (no-empty-acks):
+// keep the wording exact; do NOT expand it into doctrine/roster (see the note above).
+export const SERVER_INSTRUCTIONS =
+  'Reply only when a message needs one — a question, task, request, or awaited result. Skip bare acks/FYIs/thanks; they just loop. Silence is the right reply when nothing is asked.'
+
 // The daemon serves the AGENT exactly ONE MCP tool: send_to_peer. list_online_peers
 // is DEPRECATED by contract (docs/Примитивы и CLI: "list_online_peers УПРАЗДНЁН —
 // ел контекст; список живых пиров — через CLI verb `list`, не через tool агента").
@@ -259,7 +268,7 @@ function headerFromRequestInfo(extra: { requestInfo?: { headers?: Record<string,
 }
 
 export function createMcpServer(deps: CallToolDeps = {}): Server {
-  const server = new Server(SERVER_INFO, { capabilities: { tools: {} } })
+  const server = new Server(SERVER_INFO, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS })
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listTools() }))