@agfpd/iapeer 0.4.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.4.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,49 +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
-  uninstall [--dry-run] [--yes] [--remove-codesign-identity]     remove THIS foundation install (binary, ~/.iapeer, daemon plist, PATH lines); refuses if a persistent-peer fleet is present
-  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
@@ -993,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)
@@ -1297,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,
@@ -1309,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
@@ -1699,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
@@ -1715,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`,
         )
@@ -1988,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() }))
 

package/src/init/index.ts

@@ -21,6 +21,7 @@ import { IapError } from '../core/errors.ts'
 import {
   ensureLocalIapScaffold,
   pluginStateDir,
+  resolveGlobalRoot,
   writeFileAtomic,
   type StorageOptions,
 } from '../storage/index.ts'
@@ -245,6 +246,36 @@ export function ensureDoctrineTemplate(cwd: string): { path: string; created: bo
   return { path, created: true }
 }
 
+/**
+ * Create the GLOBAL host-doctrine template `~/.iapeer/IAPEER.md` if absent — the
+ * host-wide owner doctrine (Layer-2 GLOBAL in composeSystemPrompt, shared by EVERY
+ * peer; the general layer ABOVE each peer's own `.iapeer/IAPEER.md`). It is consumed at
+ * launch but was never scaffolded, so a fresh install left no host-doctrine file for the
+ * owner to find — asymmetric with the per-peer stub (ensureDoctrineTemplate). This
+ * mirrors that stub at host scope (discoverability + consistency). NEVER overwrites an
+ * existing host doctrine. Returns {path, created}.
+ */
+export function ensureGlobalDoctrineTemplate(env: NodeJS.ProcessEnv = process.env): { path: string; created: boolean } {
+  const root = resolveGlobalRoot(env)
+  const path = join(root, IAPEER_DOCTRINE_FILE)
+  if (existsSync(path)) return { path, created: false }
+  mkdirSync(root, { recursive: true })
+  writeFileSync(
+    path,
+    [
+      '# Host doctrine',
+      '',
+      '<!-- Host-wide rules shared by EVERY peer on this machine — the general layer,',
+      "     merged into every peer's system prompt at launch ABOVE that peer's own",
+      '     .iapeer/IAPEER.md. Replace this with your host-wide conventions. An empty',
+      '     file contributes nothing. -->',
+      '',
+    ].join('\n'),
+    { mode: 0o644 },
+  )
+  return { path, created: true }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // initPeer — orchestrate: provision (identity + registry + infra plist) + per-peer
 // ecosystem wiring (MCP transport per agentic runtime + doctrine template)

package/src/install/index.ts

@@ -13,10 +13,11 @@
 // signInstalledBinary (signing.ts) re-signs each install with the
 // stable local identity so the designated requirement — and the grants — survive.
 
-import { copyFileSync, existsSync, mkdirSync, renameSync, statSync } from 'fs'
+import { copyFileSync, cpSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'fs'
 import { homedir } from 'os'
-import { join } from 'path'
+import { basename, join, relative, sep } from 'path'
 import { spawnSync } from 'child_process'
+import { resolveGlobalRoot } from '../storage/index.ts'
 import { signInstalledBinary, type SigningOutcome } from './signing.ts'
 
 /** The stable host-wide install path of the `iapeer` binary. Standard user-bin (no
@@ -95,6 +96,64 @@ export function installIapeer(cliEntrypoint: string, env: NodeJS.ProcessEnv = pr
   return { binPath, prevPath, size, signing }
 }
 
+/**
+ * Scaffold an ecosystem package's docs to the STABLE, versioned, per-package host
+ * path `~/.iapeer/docs/<pkg>/` so an agent can read the contract OFFLINE (a compiled
+ * binary embeds no docs; the npm tarball's docs/ is discarded after install — proven:
+ * `iapeer update` extracts to a temp dir it rm's in a `finally`, and the bunx cache
+ * does not retain the package findably). This is the FOUNDATION-OWNED CONVENTION every
+ * ecosystem package follows: each copies its OWN docs on its OWN install/update, so a
+ * package's on-host docs always match its installed version.
+ *
+ * Mechanics: copy <docsSource> → ~/.iapeer/docs/<pkg> EXCLUDING internals/ (mirroring
+ * the npm `files` exclusion), via an atomic temp-dir swap so a reader never sees a
+ * half-copied tree. BEST-EFFORT — a missing source or copy hiccup NEVER fails the
+ * install (the binary works without on-host docs); the caller logs the outcome.
+ */
+export function scaffoldHostDocs(
+  pkg: string,
+  docsSource: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { copied: boolean; dest: string; reason?: string } {
+  const root = resolveGlobalRoot(env)
+  const dest = join(root, 'docs', pkg)
+  // Fail-closed sandbox guard (in spirit with assertInstallSandboxIsolated): never write
+  // the REAL machine ~/.iapeer under a sandboxed test that forgot to set IAPEER_ROOT.
+  // Compared against the ACTUAL OS home (homedir()), not env.HOME — the root IS the docs
+  // isolation, so an env.HOME-based check would false-trip when a test legitimately
+  // points IAPEER_ROOT at <tmp>/.iapeer (with env.HOME also <tmp>).
+  if (env.IAPEER_TEST_SANDBOX === '1' && root === join(homedir(), '.iapeer')) {
+    throw new Error(`refusing to scaffold docs into the REAL ${join(root, 'docs')} under IAPEER_TEST_SANDBOX=1 — set IAPEER_ROOT`)
+  }
+  if (!existsSync(docsSource)) return { copied: false, dest, reason: `docs source not found: ${docsSource}` }
+  const tmp = `${dest}.tmp-${process.pid}`
+  try {
+    rmSync(tmp, { recursive: true, force: true })
+    mkdirSync(join(dest, '..'), { recursive: true })
+    cpSync(docsSource, tmp, {
+      recursive: true,
+      // Skip the internals/ subtree (matches package.json files: "!docs/internals";
+      // returning false for a directory skips its whole subtree) and macOS .DS_Store
+      // cruft (the foundation is macOS-targeted, so every dev/host tree carries it).
+      filter: src => {
+        if (basename(src) === '.DS_Store') return false
+        const rel = relative(docsSource, src)
+        return rel !== 'internals' && !rel.startsWith(`internals${sep}`)
+      },
+    })
+    rmSync(dest, { recursive: true, force: true })
+    renameSync(tmp, dest)
+    return { copied: true, dest }
+  } catch (e) {
+    try {
+      rmSync(tmp, { recursive: true, force: true })
+    } catch {
+      /* best-effort cleanup */
+    }
+    return { copied: false, dest, reason: e instanceof Error ? e.message : String(e) }
+  }
+}
+
 /** The previous-binary path kept by the last install for one-step rollback. */
 export function iapeerPrevBinPath(env: NodeJS.ProcessEnv = process.env): string {
   return `${iapeerBinPath(env)}.prev`

package/src/launch/composeSystemPrompt.ts

@@ -103,6 +103,14 @@ export function composeSystemPrompt(input: ComposePromptInput): string {
   // The YAML identity block is the only Layer-1 section (synthesized, no marker).
   const sections: string[] = [yaml]
 
+  // Host-context pointer to the on-host ecosystem docs (FU6). Each package's install
+  // scaffolds its own contract docs to the stable, versioned, per-package path
+  // ~/.iapeer/docs/<package>/, so an agent can read "how does iapeer do X" offline
+  // instead of guessing. Synthesized Layer-1 fact (no marker). Wording: owner-approved.
+  sections.push(
+    'iapeer reference docs are on this host at ~/.iapeer/docs/ — one folder per package (start at iapeer/README.md). Consult them for how iapeer works instead of guessing.',
+  )
+
   // Layer 2 — IAPEER.md doctrine, GLOBAL then LOCAL (general → specific), each its
   // OWN marked file-section. The bash existence-gate (present-but-empty global → a
   // bare "\n") is dropped deliberately: an empty doctrine file now contributes no

package/src/tui/ansi.ts

@@ -0,0 +1,71 @@
+// ANSI palette for plain-text CLI output that runs OUTSIDE Ink — chiefly the
+// post-Ink onboard summary (run.tsx), which prints after the wizard unmounts and
+// would otherwise read as a flat, colorless tail to a styled flow.
+//
+// It mirrors the Ink wizard's palette one-for-one (see app.tsx color()/glyph()):
+//   ok → green ✓ · warn → yellow ! · fail → red ✗ · pending → gray · ·
+//   headers → bold (cyan for emphasis) · secondary detail/paths → dim
+// so the seam between the React-rendered part and the printed part is invisible.
+//
+// Color is GATED (colorEnabled): on by default only on a real TTY, force-on with
+// FORCE_COLOR (covers inherited-pipe passthrough by a child process), and hard-off
+// with NO_COLOR (https://no-color.org — presence disables, any value) so piped /
+// redirected / CI captures stay byte-clean. This is the team-wide convention we
+// hand to peer providers (e.g. iapeer-memory) whose stdout we surface verbatim.
+
+const ESC = '\x1b['
+const RESET = `${ESC}0m`
+
+const CODE = {
+  bold: '1',
+  dim: '2',
+  red: '31',
+  green: '32',
+  yellow: '33',
+  cyan: '36',
+  gray: '90',
+} as const
+
+export type AnsiPaint = (s: string) => string
+
+export interface Ansi {
+  bold: AnsiPaint
+  dim: AnsiPaint
+  red: AnsiPaint
+  green: AnsiPaint
+  yellow: AnsiPaint
+  cyan: AnsiPaint
+  gray: AnsiPaint
+}
+
+/** Whether to emit ANSI color for `stream`. NO_COLOR (any value) hard-disables;
+ *  FORCE_COLOR (truthy, not "0"/"false") forces on; otherwise gated on a real TTY. */
+export function colorEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+  stream: { isTTY?: boolean } = process.stdout,
+): boolean {
+  if (env.NO_COLOR != null) return false
+  const fc = env.FORCE_COLOR
+  if (fc != null && fc !== '0' && fc !== 'false' && fc !== '') return true
+  return stream.isTTY === true
+}
+
+/** Build a palette. When `enabled` is false every paint fn is identity (no codes),
+ *  so the same call sites produce clean text for pipes/CI. Codes compose: an inner
+ *  paint applies before the outer, both before the run resets — `a.bold(a.cyan(s))`
+ *  renders bold+cyan. */
+export function makeAnsi(enabled: boolean): Ansi {
+  const wrap =
+    (code: string): AnsiPaint =>
+    (s: string) =>
+      enabled ? `${ESC}${code}m${s}${RESET}` : s
+  return {
+    bold: wrap(CODE.bold),
+    dim: wrap(CODE.dim),
+    red: wrap(CODE.red),
+    green: wrap(CODE.green),
+    yellow: wrap(CODE.yellow),
+    cyan: wrap(CODE.cyan),
+    gray: wrap(CODE.gray),
+  }
+}

package/src/tui/onboard/app.tsx

@@ -219,8 +219,11 @@ export function OnboardApp({
       if (installed.length === 0) {
         set('auth', { status: 'warn', detail: 'no runtime installed' })
         adv.push(
-          '⚠ SETUP INCOMPLETE — no agent runtime found. iapeer needs Claude Code or Codex CLI\n' +
-            '  to run peers. Install one, sign in, then re-run `iapeer onboard`.',
+          '⚠ SETUP INCOMPLETE — no agent runtime found. iapeer needs an agent runtime: Claude Code OR Codex (either works).\n' +
+            '  Install EITHER (commands verified against the official docs), sign in, then re-run `iapeer onboard`:\n' +
+            '    Claude Code:  curl -fsSL https://claude.ai/install.sh | bash   (or: brew install --cask claude-code)\n' +
+            '    Codex:        npm install -g @openai/codex                     (or: brew install --cask codex)\n' +
+            '  If a download is blocked in your region, try the brew form or the other runtime.',
         )
       } else {
         const notes = installed.map(rt => runtimeAuthNote(rt, env)).filter((n): n is string => n != null)

package/src/tui/onboard/run.tsx

@@ -19,6 +19,7 @@
 import React from 'react'
 import { render } from 'ink'
 import { OnboardApp, type WizardResult } from './app.tsx'
+import { type Ansi, colorEnabled, makeAnsi } from '../ansi.ts'
 
 /** Sentinel: the environment is not a real interactive TTY — caller should fall
  *  back to the linear non-interactive onboard path (never render raw + hang). */
@@ -28,6 +29,36 @@ export interface OnboardWizardOptions {
   env?: NodeJS.ProcessEnv
 }
 
+/** Style one post-Ink summary line to match the Ink wizard exactly: the headline
+ *  (no leading glyph) bold — red when it announces errors; each item line keeps its
+ *  glyph colored by status (✓ green / ! yellow / ✗ red / · gray) and dims the
+ *  trailing " — detail", just as the in-wizard render does. */
+function paintSummaryLine(line: string, a: Ansi): string {
+  const m = line.match(/^(\s*)([✓!✗·]) (.*)$/)
+  if (!m) return /error/i.test(line) ? a.bold(a.red(line)) : a.bold(line)
+  const [, indent, mark, rest] = m
+  const paintMark = mark === '✓' ? a.green : mark === '!' ? a.yellow : mark === '✗' ? a.red : a.gray
+  const i = rest.indexOf(' — ')
+  const label = i >= 0 ? rest.slice(0, i) : rest
+  const detail = i >= 0 ? rest.slice(i) : ''
+  return `${indent}${paintMark(mark)} ${label}${detail ? a.dim(detail) : ''}`
+}
+
+/** Color a `prefix: state[ rest]` progress line by the state's semantics, matching
+ *  the wizard palette + the cross-CLI convention agreed with iapeer-memory: red for
+ *  failure, GRAY for a neutral skip/decline (· semantics — yellow is reserved for
+ *  warn/attention, not "user chose not to"), yellow for warn, green otherwise. */
+function paintResult(prefix: string, state: string, rest: string, a: Ansi): string {
+  const paint = /(fail|error|refus)/i.test(state)
+    ? a.red
+    : /(skip|declin)/i.test(state)
+      ? a.gray
+      : /(warn|missing|incomplete)/i.test(state)
+        ? a.yellow
+        : a.green
+  return `${a.bold(`${prefix}:`)} ${paint(state)}${rest}`
+}
+
 /** Render the interactive onboard wizard. Resolves with the process exit code, or
  *  WIZARD_NOT_INTERACTIVE when there is no real TTY to drive it. */
 export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise<number> {
@@ -35,6 +66,10 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
   if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
     return WIZARD_NOT_INTERACTIVE
   }
+  // Post-Ink lines are plain stdout (Ink has unmounted), so they carry their own
+  // ANSI to stay visually continuous with the wizard. Gated: real TTY here (the
+  // wizard only runs on one), off under NO_COLOR.
+  const a = makeAnsi(colorEnabled(env, process.stdout))
 
   let result: WizardResult = { code: 0, memoryConsent: false, telegramConsent: false, advisories: [], summary: [] }
   try {
@@ -57,54 +92,79 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
   try {
     if (result.telegramConsent) {
       const { onboardTelegramStep } = await import('../../onboard/steps.ts')
-      process.stdout.write('\nSetting up Telegram… (Ctrl-C to skip — add later: `iapeer create <you> --runtime telegram`)\n')
+      process.stdout.write(
+        '\n' +
+          a.bold('Setting up Telegram…') +
+          a.dim(' (Ctrl-C to skip — add later: `iapeer create <you> --runtime telegram`)') +
+          '\n',
+      )
       try {
         const ts = await onboardTelegramStep({ env })
-        process.stdout.write(`telegram: ${ts.state}${ts.detail ? ` — ${ts.detail}` : ''}\n`)
+        process.stdout.write(paintResult('telegram', ts.state, ts.detail ? ` — ${ts.detail}` : '', a) + '\n')
       } catch (e) {
-        process.stdout.write(`telegram: step skipped — ${e instanceof Error ? e.message : String(e)}\n`)
+        process.stdout.write(paintResult('telegram', 'step skipped', ` — ${e instanceof Error ? e.message : String(e)}`, a) + '\n')
       }
     } else {
-      process.stdout.write('\ntelegram: skipped — add later with `iapeer create <you> --runtime telegram`\n')
+      process.stdout.write(
+        '\n' + paintResult('telegram', 'skipped', ' — add later with `iapeer create <you> --runtime telegram`', a) + '\n',
+      )
     }
 
     if (result.memoryConsent) {
       const { onboardMemoryProvider } = await import('../../onboard/memory.ts')
       process.stdout.write(
-        '\nInstalling the shared-memory provider (@agfpd/iapeer-memory)…\n' +
-          'This can take a few minutes — it builds a native module. Memory is OPTIONAL:\n' +
-          'press Ctrl-C to skip it (set it up later with `npx @agfpd/iapeer-memory init`).\n\n',
+        '\n' +
+          a.bold('Installing the shared-memory provider (@agfpd/iapeer-memory)…') +
+          '\n' +
+          a.dim(
+            'This can take a few minutes — it builds a native module. Memory is OPTIONAL:\n' +
+              'press Ctrl-C to skip it (set it up later with `npx @agfpd/iapeer-memory init`).',
+          ) +
+          '\n\n',
       )
       try {
         const mem = await onboardMemoryProvider({ env, runtime: result.hostRuntime, timeoutMs: 12 * 60_000 })
         const label = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
-        process.stdout.write(`\nmemory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${label})\n`)
+        const rest = `${mem.detail ? ` — ${mem.detail}` : ''} ${a.dim(`(slot: ${label})`)}`
+        process.stdout.write('\n' + paintResult('memory', mem.state, rest, a) + '\n')
       } catch (e) {
-        process.stdout.write(
-          `\nmemory: step skipped — ${e instanceof Error ? e.message : String(e)} (set up later: \`npx @agfpd/iapeer-memory init\`)\n`,
-        )
+        const rest = ` — ${e instanceof Error ? e.message : String(e)} ${a.dim('(set up later: `npx @agfpd/iapeer-memory init`)')}`
+        process.stdout.write('\n' + paintResult('memory', 'step skipped', rest, a) + '\n')
       }
     } else {
-      process.stdout.write('\nmemory: skipped — set it up later with `npx @agfpd/iapeer-memory init`\n')
+      process.stdout.write(
+        '\n' + paintResult('memory', 'skipped', ' — set it up later with `npx @agfpd/iapeer-memory init`', a) + '\n',
+      )
     }
   } finally {
     process.removeListener('SIGINT', ignore)
     for (const h of prevInt) process.on('SIGINT', h as NodeJS.SignalsListener)
   }
 
-  // Final summary (plain text, post-Ink).
+  // Final summary (post-Ink, ANSI-styled to match the wizard's palette).
   process.stdout.write('\n')
-  for (const line of result.summary) process.stdout.write(line + '\n')
+  for (const line of result.summary) process.stdout.write(paintSummaryLine(line, a) + '\n')
   if (result.advisories.length > 0) {
     process.stdout.write('\n')
-    for (const a of result.advisories) process.stdout.write(a + '\n')
+    // Advisories mirror the wizard's yellow box (a multi-line entry stays yellow
+    // line-to-line until the trailing reset).
+    for (const adv of result.advisories) process.stdout.write(a.yellow(adv) + '\n')
   }
-  process.stdout.write('\nNext steps:\n')
-  process.stdout.write('  • Create your first agent:  iapeer create <name> --runtime claude\n')
+
+  // Next steps — an aligned 2-column block (label padded, command highlighted), the
+  // bot-token left as its own explicit step (no surprise / don't-make-them-guess).
+  const next: Array<{ label: string; cmd: string; note?: string }> = [
+    { label: 'Create your first agent', cmd: 'iapeer create <name> --runtime claude' },
+  ]
   if (result.telegramConsent) {
-    // The wizard set up the human peer (name + user_id) but NOT the bot itself —
-    // the bot token is a separate, explicit step (no surprise / don't-make-them-guess).
-    process.stdout.write('  • Activate Telegram:        iapeer connect telegram   (paste a bot token from @BotFather)\n')
+    next.push({ label: 'Activate Telegram', cmd: 'iapeer connect telegram', note: 'paste a bot token from @BotFather' })
+  }
+  const w = Math.max(...next.map(n => n.label.length))
+  process.stdout.write('\n' + a.bold('Next steps:') + '\n')
+  for (const n of next) {
+    process.stdout.write(
+      `  ${a.cyan('•')} ${n.label.padEnd(w)}   ${a.cyan(n.cmd)}${n.note ? '  ' + a.dim(`(${n.note})`) : ''}\n`,
+    )
   }
   return result.code
 }