@agfpd/iapeer 0.2.98 → 0.3.0

package/docs/12-cli-reference.md

@@ -0,0 +1,96 @@
+# 12 — CLI
+
+[Русский](ru/12-cli-reference.md) · **English**
+
+The full list of `iapeer <command>`. General rules: `--help` / `-h` anywhere in the line prints help and runs nothing; flags take both `--key value` and `--key=value` forms.
+
+## Core install and maintenance
+
+| Command | What it does |
+|---|---|
+| `install` | Core bootstrap: build the `~/.local/bin/iapeer` binary, create the `~/.iapeer/` layout, write the daemon plist (without loading). |
+| `update [version] [--force]` | Update the core from npm, restart the daemon, restart the core's infra services. With no argument — to the latest version; with a version — to the exact one. `--force` reinstalls even when versions match. |
+| `rollback` | Restore the previous binary (`.prev`), restart the daemon, check health. One level back. |
+| `version` · `--version` · `-v` | The installed binary's version. |
+| `help` · `--help` · `-h` | Command help. |
+| `daemon [--install-plist]` | Run the router (normally held by launchd). `--install-plist` only writes the plist, without loading. |
+
+`update` checks the daemon's health after the restart: if the daemon didn't revive, the command returns a non-zero code and advises `rollback`.
+
+## Host
+
+| Command | What it does |
+|---|---|
+| `onboard [flags]` | Host setup: marketplace (Claude + Codex) → notifier → Telegram (human peer) → memory provider. All steps on by default. |
+| `status` | Host snapshot: version, daemon health, memory slot. Non-zero exit code if the daemon is unhealthy. |
+| `install-runtime <runtime> [--package <pkg>] [--npx] [--no-bootstrap]` | Install a runtime package and provision its declared peer set. `--no-bootstrap` — don't load peers into launchd. |
+| `update-runtime <runtime> \| --all [--force]` | Update runtime package(s) with a restart of their peers. |
+
+`onboard` flags: `--dry-run` (show without changes), `--no-notifier`, `--no-telegram`, `--no-memory`, `--telegram-human <name>`, `--telegram-user-id <id>`, `--memory <pkg>`, `--infra <list>`.
+
+## Peers: creation and review
+
+| Command | What it does |
+|---|---|
+| `init [folder] [--runtime r] [--description d] [--bin path] [--no-bootstrap]` | Make the current (or a given) folder a peer: profile, MCP, doctrine. The peer name is the folder name; not set by a separate flag. |
+| `create <name> [--runtime r] [--path folder] [--bin path] [--description d] [--intelligence i] [--no-bootstrap]` | Create a peer from anywhere (by default `~/.iapeer/peers/<name>`) and provision it. |
+| `list [--json]` | The peer registry with per-runtime state. In an interactive terminal — a control panel; otherwise or with `--json` — a table. |
+| `verify [--json] [--fix]` | Check profiles against the standard and registry↔profile divergences. `--fix` self-heals the registry and migrates the old runtime-field format. |
+
+## Peers: lifecycle
+
+| Command | What it does |
+|---|---|
+| `stop <peer> [runtime] \| --all` | Agent: stop flag + close the session (the daemon won't wake it). Infra: remove from launchd. `--all` — all peers. |
+| `start <peer> [runtime] \| --all` | Clear the stop flag (the session comes up on the first message). Infra: load into launchd. |
+| `new <peer> [runtime]` | An unconditional fresh restart — the emergency lever for a hung/dead session, around the agent. Code 0 = a fresh session is up and ready. |
+| `refresh <peer> [runtime] \| --all` | A lazy "soft restart": an agent peer comes up fresh (re-reads the doctrine/fragments from disk) on its NEXT natural wake. Doesn't kill a live session, doesn't wake the rest, doesn't do an immediate restart — only sets a marker. Routers (notifier/telegram) and absent runtimes are skipped (they have no doctrine). `--all` — all peers. |
+| `remove <peer> [--force]` | Delete the registry entry (doesn't touch the peer's folder). Refuses a live peer without `--force`. Idempotent. |
+| `attach <peer> [runtime]` | Bring up (if asleep), resume the conversation, open the session under the supervisor in the terminal (detach — `Ctrl-]`). |
+| `interrupt <peer> [runtime]` | Interrupt the current turn (Escape), context intact. |
+| `compact <peer> [runtime]` | Compact the conversation; a sleeper is resumed first after idle sleep. |
+| `add-runtime <runtime> (--peer <p> \| --all)` | Add an agent runtime to existing peers. Doesn't touch `default_runtime`. |
+| `default-runtime <runtime> (--peer <p> \| --all)` | Switch the primary runtime (routing / first bring-up). Refuses if the runtime isn't declared. |
+
+`stop`/`start`/`new` refuse to touch peers under a foreign launchd plist — the core doesn't intervene in what it doesn't manage.
+
+## Messages
+
+| Command | What it does |
+|---|---|
+| `send <target> (--message <text> \| --message-file <f\|->) [--from <id>] [--runtime <r>] [--attachment <path>]… [--topic <t>]` | Manual IAP send over the same path as `send_to_peer`. |
+
+`--message-file -` reads the body from stdin. `--attachment` is repeatable. `--from` defaults to the current folder's peer identity.
+
+## Launch and runtimes
+
+| Command | What it does |
+|---|---|
+| `<runtime>` (e.g. `iapeer claude`) | Launch the current folder's peer on this runtime — always as a fresh session. |
+| `connect telegram <peer> [--token <t>]` | Connect a Telegram bot to a peer: register the bot → write into the profile → restart the router. Asks only for the token. |
+
+## Extensions and memory
+
+| Command | What it does |
+|---|---|
+| `enable <plugin> [peer] [--no-setup]` | Install and enable a capability plugin for a peer (across runtimes), run its setup step. |
+| `native-memory <off\|on> (--peer <p> \| --all)` | Turn off/restore a peer's runtimes' native memory. |
+| `trust-hooks <hooks.json> [--check]` | Pre-trust codex hooks from a file (without the modal). `--check` — a divergence report. |
+
+## Agent self-calls
+
+Commands an agent runs in its own session (require `PEER_IDENTITY` in the environment):
+
+| Command | What it does |
+|---|---|
+| `self-fresh` | Mark itself for a fresh restart and close its session — the daemon brings up a fresh one. |
+| `self-done` | Ephemeral worker: quietly finish, freeing the queue, waking no one. |
+
+## Service
+
+| Command | What it does |
+|---|---|
+| `daemon` | The router daemon's entry point; launched from the `com.agfpd.iapeer` plist. |
+| `run-infra <name> <runtime>` | An infrastructure peer's entry point; launched from its launchd plist. |
+
+These two commands are invoked by launchd, not the operator directly.

package/docs/13-architecture-and-contract.md

@@ -0,0 +1,190 @@
+# 13 — Architecture and contract
+
+[Русский](ru/13-архитектура-и-контракт.md) · **English**
+
+A section for those building on iapeer: runtime packages, capability plugins, memory providers.
+
+## Invariants
+
+The system's behavior rests on these:
+
+- **One router.** There's exactly one continuously running daemon in the system. All messages go through it; there's no second router.
+- **Identity per request.** The daemon keeps no client session — it determines who called from the `X-IAPeer-Identity` header of each MCP request. One listener serves all peers.
+- **A single registry writer.** `peers-profiles.json` is written only through one writer under a file lock. Direct writing of the file is forbidden at the core level — this rules out races.
+- **Liveness is defined by a peer's live session.** A peer is alive if and only if it has a live session under the supervisor. This isn't a separate state flag that can desync, but an observable fact.
+- **`delivered` ⟺ landed in a live session.** Delivery success means the message was accepted by a live session (the daemon waited for confirmation). If it didn't confirm — the daemon treats the session as dead rather than lying about success.
+- **The source of truth is the local profile.** The registry is a reprojectable projection of the peer profiles. On a divergence, the profile wins.
+- **The binary is installed on the host.** The daemon runs from the installed `~/.local/bin/iapeer`, not from a source working tree. An update is replacing the binary and restarting the daemon onto it.
+
+## Runtime adapters on the core side
+
+An adapter is a core layer that knows how to launch a runtime's session. All adapters implement one interface; the runtimes' differences are hidden behind it.
+
+The adapter's key properties:
+
+- **`kind`** — `tui` (an interactive session that takes input: claude, codex) or `router` (a long-lived process with no input: telegram, notifier).
+- **`usesDoctrine`** — whether the runtime consumes the assembled system prompt. For TUI agents — yes, for routers — no (they aren't language models).
+- **`requiresIntelligence`** — a gate on the peer's nature. For `telegram` it's `natural`: an attempt to give a non-human a Telegram presence is rejected with an explicit error.
+- **`buildArgv`** — how to assemble the launch command: for routers it's `<runtime>-runtime run` plus extra arguments from `launch.env`.
+
+Routers skip all the TUI phases: they have no boot dialogs, no readiness markers, no delivery confirmation, no control commands. Their liveness is held by launchd, not a wake by the daemon.
+
+The production mechanism for hosting TUI sessions is the **pty supervisor**: a supervisor daemon owns the session's pty and its pane log, and delivery onto input goes through its socket. tmux remains only an internal dev branch (the shadow branch) and doesn't figure at the user level.
+
+## The runtime-package contract
+
+A runtime package (`*-runtime`) is an npm package that adds an infrastructure runtime. Examples: `@agfpd/notifier-runtime`, `@agfpd/telegram-runtime`.
+
+### The runtime.json manifest
+
+On self-install the package writes a manifest to `~/.iapeer/runtimes/<runtime>/runtime.json`. The core reads it.
+
+```json
+{
+  "runtime": "notifier",
+  "version": "0.2.0",
+  "selfConfig": { "command": "notifier-runtime", "args": ["self-config"] },
+  "peers": [
+    { "personality": "timer",   "intelligence": "absent", "description": "Schedule-driven scheduler" },
+    { "personality": "watcher", "intelligence": "absent", "description": "Event watcher" }
+  ]
+}
+```
+
+| Field | Type | Required | Purpose |
+|---|---|---|---|
+| `runtime` | string | required | The runtime ID, matches the folder name; pattern `^[a-z][a-z0-9]{0,31}$` |
+| `version` | string | optional | The package version. Used for the gate at `update-runtime`; without it an update simply reinstalls |
+| `selfConfig` | descriptor | optional | A personal-setup hook, called by the core for each peer at provision |
+| `peers` | array | optional | The declared peer set. Present — declared-set mode; absent — operator-add |
+
+A `peers[]` element: `personality` (required), `intelligence`, `description`, `path` (an explicit folder), `runtimeBin` (a launcher path) — the last four optional.
+
+A **descriptor** (`selfConfig` and the like) is `{ "command": "...", "args": [...] }` or simply a command string.
+
+### Two deployment modes
+
+- **declared-set** — the manifest contains `peers[]`. `iapeer install-runtime <runtime>` provisions the whole set at once (notifier provisions `timer` and `watcher`).
+- **operator-add** — `peers[]` is empty or absent. Peers are set up by the operator one at a time: `iapeer create <name> --runtime <runtime>` (this is how humans are connected on telegram).
+
+### What the core calls on the package
+
+The contract is minimal — the core reaches the package in exactly three ways:
+
+1. **`npx <package>`** — at install. The package idempotently lays its binary on `PATH` and writes `runtime.json`.
+2. **`<runtime>-runtime run`** — at session launch (via the launchd plist or launch). In the environment — `PEER_PERSONALITY`, `PEER_RUNTIME`, `PEER_IDENTITY`.
+3. **The `selfConfig` hook** — at each peer's provision. Called in the peer's working folder; in the environment — `IAPEER_PEER_PERSONALITY`, `IAPEER_PEER_CWD`, `IAPEER_PEER_RUNTIME`, `IAPEER_PEER_INTELLIGENCE`. Exit code 0 — configured (idempotently), otherwise — an error (the plist is written but not loaded).
+
+Commands like `prepare`, `interface`, `bot`, `doctor` are the package's own internal commands for the operator, not a contract with the core: the core doesn't call them.
+
+### Install and update
+
+- **`install-runtime <runtime>`** determines the npm package (from the built-in registry or the `--package` flag), installs it via `npx`, then provisions the declared peer set.
+- **`update-runtime <runtime>`** compares the manifest version with npm; when behind, it reinstalls, re-provisions, and restarts the runtime's peers with the standard `stop`/`start`.
+
+## The capability-plugin standard
+
+A capability plugin adds an ability to a peer without being a runtime. The distinction is clear: a runtime is a peer's mode of presence, a plugin is an ability on top of a runtime.
+
+### The iapeer.json manifest
+
+A plugin may (but need not) place an `iapeer.json` in its root:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `setup` | descriptor | The plugin's setup step. Called at `enable`, if declared and the install succeeded |
+| `requires` | — | Dependencies (runtimes, other plugins). The core doesn't resolve them — the plugin checks them itself and refuses if a dependency is missing |
+
+A plugin with no `iapeer.json` or no `setup` is the simple class: it's installed and enabled, with no extra initialization.
+
+### enable
+
+`iapeer enable <plugin> [peer]`, step by step:
+
+1. Finds the peer (by name or by the current folder); refuses if the peer has no agent runtime.
+2. On each of the peer's agent runtimes it installs the plugin: for Claude — into the project scope inside the peer's folder (`plugin install … --scope project`), for Codex — into the host's shared config. The install enables the plugin along the way.
+3. If a `setup` is declared and the install succeeded — it calls it. In the environment: `IAPEER_PEER_PERSONALITY`, `IAPEER_PEER_CWD`; the working folder is the plugin root. The step is best-effort: its failure doesn't roll back the install and enable already done.
+
+Idempotency: for Claude the binding is by the peer folder's real path, so a repeated `enable` doesn't disturb other peers or duplicate the install.
+
+### iapeer-compatibility criteria
+
+A plugin is considered compatible if it:
+
+1. is useful on its own;
+2. declares what it provides and what it requires;
+3. doesn't own others' responsibilities;
+4. has an idempotent preparation;
+5. has self-diagnostics (`doctor`/`status`);
+6. uses the shared identity ABI (`PEER_*`) when it's available;
+7. doesn't require the user to manually sync identity between plugins;
+8. understands name, runtime, and identity the same under Claude, Codex, and future runtimes.
+
+## The memory-slot contract
+
+Memory is provided by a provider that claims the single per-host slot. The slot is occupied by exactly one provider or empty.
+
+### The provider manifest
+
+The provider atomically writes `~/.iapeer/memory-provider.json`; the core only reads it. Deleting the file frees the slot. The core never writes the slot.
+
+```json
+{
+  "provider": "iapeer-memory",
+  "package": "@agfpd/iapeer-memory",
+  "version": "0.2.7",
+  "registeredAt": "2026-06-11T17:46:41.449Z",
+  "heartbeat": "/Users/me/.iapeer/state/iapeer-memory/memoryd.heartbeat",
+  "provision": {
+    "command": "/Users/me/.local/bin/iapeer-memory",
+    "args": ["provision-peer", "--cwd", "{cwd}", "--runtime", "{runtime}",
+             "--personality", "{personality}", "--occasion", "{occasion}"]
+  },
+  "unprovision": {
+    "command": "/Users/me/.local/bin/iapeer-memory",
+    "args": ["unprovision-peer", "--cwd", "{cwd}", "--runtime", "{runtime}",
+             "--occasion", "{occasion}"]
+  }
+}
+```
+
+| Field | Type | Required | Purpose |
+|---|---|---|---|
+| `provider` | string | required | The provider name |
+| `package` | string | required | The npm package |
+| `version` | string | required | The package version |
+| `registeredAt` | ISO date | required | When the slot was claimed |
+| `heartbeat` | path | optional | The provider daemon's heartbeat file; `iapeer status` shows its freshness |
+| `provision` | descriptor | optional | The command to set up a peer's memory at birth |
+| `unprovision` | descriptor | optional | The command to wind down at peer removal |
+
+`command` must be an absolute path; `args` is an array of strings. The core treats an invalid block as absent, and an empty slot as a normal state.
+
+### The provision/unprovision commands
+
+Four placeholders are substituted in the arguments (per-argument substitution, at the substring level):
+
+| Placeholder | Value |
+|---|---|
+| `{cwd}` | the peer's working folder |
+| `{runtime}` | the specific agent runtime (`claude` / `codex`) |
+| `{personality}` | the peer name — must equal `normalize(basename({cwd}))` (the peer name and folder are 1:1); a mismatch → `ensurePeerProfile` fails |
+| `{occasion}` | the call moment (see below) |
+
+**The call moments the core emits:**
+
+- **`birth`** — at a peer's birth, one command per agent runtime. It runs after Codex pre-trusts the folder, so the provider's surfaces land in an already-trusted folder.
+- **`remove`** — at a peer's removal, one command per agent runtime. It runs before the peer's state is cleaned — the provider sees it in its last consistent form.
+
+**Environment:** the command inherits the whole core environment; the core does **not** add special `IAPEER_PEER_*` here — the provider relies on the placeholders in the arguments. stdin is ignored, stdout/stderr are captured.
+
+**Execution semantics:** exit code 0 — success; otherwise — an error; over 120 seconds — a timeout; an unavailable binary — a separate outcome. All best-effort: a command's failure fails neither a peer's birth nor its removal, but is logged loudly. The provider must be idempotent — the core may invoke one command again.
+
+### The native-memory lever
+
+When the slot is claimed, keeping a runtime's native memory in parallel is harmful. The core, at the birth of a peer with a claimed slot, turns it off:
+
+- **Claude** — appends `"autoMemoryEnabled": false` to `<folder>/.claude/settings.json`;
+- **Codex** — appends `[features] memories = false` to `<folder>/.codex/config.toml`.
+
+To turn it back on — delete the key (restore the runtime's default). By hand: `iapeer native-memory off|on`. For Codex the core, at birth, also writes folder trust (`[projects."<real-path>"] trust_level = "trusted"`) so the project config is read from the first session; at peer removal this entry is removed.

package/docs/14-configuration-and-logs.md

@@ -0,0 +1,91 @@
+# 14 — Configuration and logs
+
+[Русский](ru/14-конфигурация-и-журналы.md) · **English**
+
+The core runs on sensible defaults — no separate setup is needed to start. Behavior is fine-tuned with environment variables; logs give material for analysis when something has gone wrong.
+
+## Environment variables
+
+All values below are the defaults from the current code. A variable is set in the daemon's environment or a specific peer's (via `launch.env`, see [06 — Storage](06-storage.md)).
+
+### Lifecycle
+
+| Variable | Default | What it sets |
+|---|---|---|
+| `IAPEER_IDLE_SECS` | `3600` | After how many idle seconds the daemon closes an agent session (sleep). |
+| `IAPEER_BOOT_DEADLINE_SECS` | `240` | How long to wait for a session to load on bring-up before treating the launch as failed. |
+| `IAPEER_READY_GATE_SECS` | `120` | How long to wait for the agent to be ready for input after load. |
+| `IAPEER_CRASHLOOP_MAX` | `3` | How many deaths in the window are allowed before the daemon stops bringing the peer up. |
+| `IAPEER_CRASHLOOP_WINDOW_SECS` | `300` | The window (seconds) over which deaths are counted for restart-loop protection. |
+| `IAPEER_EPHEMERAL_QUIET_SECS` | `20` | The quiet window after which an ephemeral worker that already replied winds down. |
+| `IAPEER_EPHEMERAL_UNARMED_IDLE_SECS` | `600` | The safety bound for an ephemeral worker that stays silent and sent no reply. |
+
+The daemon's supervisory tick is fixed — once a minute, not configurable.
+
+### Daemon
+
+| Variable | Default | What it sets |
+|---|---|---|
+| `IAPEER_PORT` | `8765` | The router's TCP port on `127.0.0.1`. |
+| `IAPEER_DAEMON_SOCKET` | `~/.iapeer/state/iapeer/router.sock` | The daemon's local socket path. |
+| `IAPEER_BEARER_TOKEN` | — | If set, the daemon requires this bearer token at the entrance; otherwise token checking is off. |
+
+### Message delivery
+
+| Variable | Default | What it sets |
+|---|---|---|
+| `IAP_HOST_LIVENESS_GRACE_MS` | `4000` | How long to wait for confirmation that a session accepted a message before treating it as dead. |
+| `IAP_LIVENESS_GRACE_MS` | `3000` | The liveness-check window for a busy session (by the conversation-history shift). |
+| `IAPEER_COMPOSER_QUEUE_TIMEOUT_MS` | `120000` | How long the composer queue waits for the input field to free before force-delivering. |
+| `IAPEER_COMPOSER_QUEUE_POLL_MS` | `500` | The poll frequency of the input field in the composer queue. |
+
+### Paths and binaries
+
+| Variable | Default | What it sets |
+|---|---|---|
+| `IAPEER_ROOT` | `~/.iapeer` | The storage root. Changing it isolates sockets into `<root>/socks` (useful for isolated test hosts). |
+| `IAPEER_SOCK_DIR` | `/tmp` | The host-wide socket directory. Overrides the host-wide location. |
+| `IAPEER_BIN_DIR` | `~/.local/bin` | Where the `iapeer` binary is installed. |
+| `IAPEER_LAUNCHAGENTS_DIR` | `~/Library/LaunchAgents` | The launchd plists directory. |
+| `IAPEER_CLAUDE_BIN` | `~/.local/bin/claude` | The path to the Claude binary. |
+| `IAPEER_CODEX_BIN` | `codex` (from `PATH`) | The path to the Codex binary. |
+| `NOTIFIER_RUNTIME_BIN` | `notifier-runtime` (from `PATH`) | The path to the notifier launcher (for launchd with its minimal `PATH`). |
+| `TELEGRAM_RUNTIME_BIN` | `telegram-runtime` (from `PATH`) | The path to the Telegram launcher. |
+| `CODEX_HOME` | `~/.codex` | An override for Codex's global config directory. |
+
+### Logs
+
+| Variable | Default | What it sets |
+|---|---|---|
+| `IAPEER_LIFECYCLE_LOG_MAX_BYTES` | `5 MiB` | The `lifecycle.log` size at which rotation happens. |
+| `IAPEER_LIFECYCLE_LOG_KEEP` | `5` | How many `lifecycle.log` rotations to keep. |
+| `IAPEER_DELIVERY_LOG_MAX_BYTES` | `5 MiB` | The `delivery.log` size for rotation. |
+| `IAPEER_DELIVERY_LOG_KEEP` | `5` | How many `delivery.log` rotations to keep. |
+| `IAPEER_SUPERVISE_LOG_VERBOSE` | off | A verbose log of supervisory ticks (by default only decisions are written, not routine "doing nothing"). |
+| `IAPEER_DAEMON_LOG` | off | An extended daemon log. |
+
+### Internal, dev, and test
+
+`IAPEER_TEST_SANDBOX=1` turns on write protection for real paths: the install refuses to write into the real `~/.local/bin/iapeer` and requires `IAPEER_BIN_DIR` set to an isolated path. For development and automated tests, not for normal work.
+
+A few more variables the system reads but that aren't set in normal operation:
+
+- `NOTIFIER_FALLBACK_TARGET` — a fallback recipient for notifier signals; the core resolves it into the peer's plist at onboarding (no hardcode), the operator doesn't set it by hand.
+- `IAP_TMUX_PASTE_SETTLE_MS`, `IAP_TMUX_SUBMIT_TIMEOUT_MS` — delivery timings in the internal tmux dev branch; production uses the pty supervisor ([13 — Architecture and contract](13-architecture-and-contract.md)), so they aren't needed outside development.
+- `IAPEER_SHADOW_PATH` — the `PATH` for a shadow-fidelity run (an internal development tool).
+
+## Logs and diagnostics
+
+The daemon keeps three durable logs in `~/.iapeer/logs/iapeer/`:
+
+- **`lifecycle.log`** — lifecycle decisions: wakes, sleeps, restarts, supervisory-tick outcomes. The first place to look if a peer is behaving wrong.
+- **`delivery.log`** — the outcome of each delivery: who, to whom, into which runtime, the result, sizes, topic. Metadata only — **the message body is not written**.
+- **`exits.log`** — session deaths with postmortem data: the supervisor records the cause (exit code / signal) at the moment a session dies.
+
+### Postmortem diagnostics
+
+The cause of a session's death (exit code / signal) the supervisor records at the moment of death — what an ordinary "is the process alive" check misses. A separate canary holds a connection to the supervisor and, on a session's death, writes the circumstances to `exits.log`: memory, swap, top processes by consumption, system diagnostic reports. It's the material for answering "why did the agent die".
+
+### Full Disk Access
+
+To read system diagnostic reports, the `iapeer` binary needs Full Disk Access (FDA) — a macOS permission. `iapeer status` shows whether FDA is granted and hints at what to do if not. Without FDA, peers will hit TCC prompts when accessing protected folders and third-party app containers.

package/docs/README.md

@@ -0,0 +1,97 @@
+# iapeer
+
+[Русский](ru/README.md) · **English**
+
+iapeer is the core of a multi-agent system on one host. It maintains a registry of participants, a single router daemon for messaging between them, and a set of commands to manage participants: create, start, sleep, restart, connect to external channels.
+
+A participant in the system is called a **peer**. A peer can be an AI agent (Claude, Codex), a human (over Telegram), or a service process (a scheduler, a watcher). iapeer doesn't distinguish them by nature at the transport level — they're all addressed the same way and exchange messages over one protocol.
+
+```text
+   send_to_peer (from any peer)
+        │
+        ▼
+   ┌────────────────────────┐
+   │      router daemon       │   runs continuously
+   │   find · deliver         │   reads peers-profiles.json (the registry)
+   └────────────────────────┘
+        │
+        ▼
+   recipient peer  (asleep? it'll be brought up)
+```
+
+## What it solves
+
+When a machine hosts not one agent but a team — each with its own role, working folder, and runtime — problems arise that a single agent doesn't have:
+
+- **Addressing.** How agent A sends a message to agent B without knowing whether B is running right now.
+- **Presence.** Whether to keep every agent in memory all the time (expensive) or bring them up on demand (someone has to do the bringing up).
+- **Identity.** The same logical agent may be present in different runtimes (Claude today, Codex tomorrow) — the system must understand it's the same peer.
+- **Lifecycle.** Who sleeps an idle agent, who restarts a hung one, who keeps a crashed agent from entering a restart loop.
+
+iapeer takes this on. An agent only needs to call `send_to_peer(<name>, <text>)` — the daemon does the rest: finds the recipient in the registry, checks whether it's alive, delivers into a live session or brings up a sleeper and delivers after the wake.
+
+## Quick start
+
+Requirements: **macOS** (process management goes through launchd), **[bun](https://bun.sh)** on `PATH`, and at least one agent runtime — Claude Code or Codex CLI.
+
+```bash
+# 1. Install the core — the binary, the ~/.iapeer layout, and the daemon plist
+npx @agfpd/iapeer
+
+# 2. Set up the host — onboard starts the daemon, registers the marketplace,
+#    installs notifier, Telegram, and memory
+iapeer onboard
+
+# 3. Create your first agent
+iapeer create assistant --runtime claude
+
+# 4. Send a message — the daemon brings up the session if there's none
+iapeer send assistant --message "hi, are you there?"
+```
+
+A detailed breakdown of each step — in [02 — Quick start](02-quickstart.md).
+
+## Documentation
+
+The sections are layered: from "install and use" to "understand the architecture and extend it".
+
+**Introduction**
+- [01 — Overview](01-overview.md) — what iapeer is and what it's made of
+- [02 — Quick start](02-quickstart.md) — install, onboarding, the first peer, the first message
+
+**Concepts**
+- [03 — Peers, runtimes, identity](03-peers-runtimes-identity.md)
+- [04 — Lifecycle and the daemon](04-lifecycle-and-daemon.md)
+- [05 — Identity and the system prompt](05-system-prompt.md)
+- [06 — Storage](06-storage.md)
+
+**Guides**
+- [07 — Install and update](07-install-and-update.md)
+- [08 — Peer management](08-peer-management.md)
+- [09 — Runtimes](09-runtimes.md)
+- [10 — Messaging](10-messaging.md)
+- [11 — Extensions and memory](11-extensions-and-memory.md)
+
+**Reference**
+- [12 — CLI](12-cli-reference.md) — all commands with flags
+- [13 — Architecture and contract](13-architecture-and-contract.md) — for plugin and runtime-package developers
+- [14 — Configuration and logs](14-configuration-and-logs.md) — environment variables, logs, diagnostics
+
+## Status
+
+Built and working: the single router daemon, the messaging protocol (IAP), the peer registry, identity and its ABI, the lifecycle (wake, sleep, restart, supervision), runtime adapters for Claude, Codex, Telegram, and notifier, host install and onboarding, Telegram connection, the memory slot, and capability plugins.
+
+Planned on top of the core: a package-compatibility graph, a whole-team health doctor, and an interactive coordination interface. Until those exist, coordination operations live in the `iapeer` CLI.
+
+## Roadmap
+
+Larger directions, planned and not yet built:
+
+- **Web UI** — a browser interface for working with the team.
+- **Linux support** — iapeer runs on macOS today; Linux is planned.
+- **More agent runtimes** — `opencode` and `antigravity`, two further CLI runtimes alongside Claude Code and Codex.
+- **Discord runtime** — a human-presence runtime for Discord, alongside Telegram.
+- **Permissions gate** — finer control over what an agent is allowed to do.
+- **Approve permissions over Telegram** — approve an agent's permission requests from the chat; today permissions are auto-allowed by flags.
+
+The platform for now is macOS/launchd only. Linux (systemd) and Windows support is not implemented.

package/docs/ru/01-/320/276/320/261/320/267/320/276/321/200.md

@@ -0,0 +1,86 @@
+# 01 — Обзор
+
+**Русский** · [English](../01-overview.md)
+
+iapeer держит команду агентов на одном хосте: ведёт реестр участников, маршрутизирует сообщения между ними и управляет их присутствием. Три понятия задают всю систему — пир, рантайм, идентичность.
+
+## Пир
+
+Пир — участник системы. Это AI-агент (Claude, Codex), человек (через Telegram) или служебный процесс (планировщик, наблюдатель). На уровне транспорта они неразличимы: адресуются одинаково, обмениваются сообщениями по одному протоколу.
+
+У пира есть имя (`personality`) — короткое логическое имя в нижнем регистре (`assistant`, `code-reviewer`). Имя стабильно при переходе между рантаймами, выводится из имени рабочей папки и уникально: два пира одно имя носить не могут.
+
+Природу пира задаёт атрибут `intelligence` — он едет в конверте каждого сообщения, поэтому получатель знает, с кем говорит, без внешних договорённостей:
+
+| Значение | Кто |
+|---|---|
+| `artificial` | AI-агент (Claude, Codex) |
+| `natural` | человек (через Telegram) |
+| `absent` | программа без интеллекта (планировщик, наблюдатель) |
+
+## Рантайм
+
+Рантайм — способ присутствия пира. Один пир может присутствовать в нескольких рантаймах. По управлению жизненным циклом рантаймы делятся на два класса:
+
+- **claude, codex** — AI-агенты. Сессию не держат запущенной постоянно: демон поднимает агента на входящее сообщение и закрывает сессию после часа простоя. Этим классом распоряжается демон.
+- **telegram, notifier** — служебные рантаймы-роутеры (не AI). Работают постоянно: Telegram-мост принимает входящие в любой момент, notifier срабатывает по расписанию. Их держит launchd с автоперезапуском. Эти рантаймы называются инфраструктурными; демон их не трогает.
+
+Граница — это разделение ответственности: демон управляет агентами claude/codex, launchd — инфраструктурными рантаймами. Команды `stop`/`start`/`new` поэтому работают по-разному в зависимости от класса.
+
+## Идентичность
+
+Идентичность — адрес живого присутствия пира, склейка рантайма и имени:
+
+```text
+PEER_IDENTITY = PEER_RUNTIME + "-" + PEER_PERSONALITY
+```
+
+Агент `assistant` в Claude — `claude-assistant`, он же в Codex — `codex-assistant`: имя одно, идентичности разные. Разбор идёт по первому дефису (в имени рантайма дефисов нет, в имени пира допустимы), поэтому `claude-code-reviewer` — это рантайм `claude` и пир `code-reviewer`.
+
+Три значения — `PEER_PERSONALITY`, `PEER_RUNTIME`, `PEER_IDENTITY` — передаются в окружение сессии. По ним любой компонент знает своё имя и от чьего лица действует. Подробно — [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md).
+
+## Компоненты
+
+```text
+┌──────────────────────────────────────────────────────────────┐
+│  CLI  iapeer <команда>                                         │
+│  create · list · send · stop/start · new · connect · enable …  │
+└───────────────┬──────────────────────────────────────────────┘
+                │
+┌───────────────▼───────────────┐     ┌──────────────────────────┐
+│  Демон-роутер (работает 24/7)  │     │  Реестр пиров             │
+│  • принимает send_to_peer      │◀───▶│  ~/.iapeer/               │
+│  • находит получателя          │     │  peers-profiles.json      │
+│  • доставляет / поднимает      │     └──────────────────────────┘
+│  • надзор за пирами            │
+└───────────────┬───────────────┘
+                │ поднимает / усыпляет
+┌───────────────▼───────────────────────────────────────────────┐
+│  Рантайм-адаптеры                                              │
+│ claude · codex (pty-супервизор) │ telegram · notifier (launchd)│
+└────────────────────────────────────────────────────────────────┘
+```
+
+**Демон-роутер** — единственный постоянно работающий процесс ядра, под launchd. Принимает вызовы `send_to_peer`, находит получателя в реестре, доставляет сообщение в живую сессию или поднимает спящего агента. Раз в минуту обходит пиров: закрывает сессии после часа простоя, перезапускает помеченных на свежий старт, не даёт упавшему агенту войти в цикл перезапусков. См. [04 — Жизненный цикл и демон](04-жизненный-цикл-и-демон.md).
+
+**Реестр пиров** — `~/.iapeer/peers-profiles.json`: имя, рантаймы, описание, природа, рабочая папка каждого пира. Источник истины — профиль каждого пира (`<папка>/.iapeer/peer-profile.json`); реестр пересобирается из профилей. См. [06 — Хранение](06-хранение.md).
+
+**Рантайм-адаптеры** — слой запуска сессий. Для Claude и Codex это TUI-сессия под pty-супервизором с подменённым системным промптом; для Telegram и notifier — долгоживущий процесс-роутер под launchd. Адаптеры прячут различия рантаймов за единым интерфейсом. См. [09 — Рантаймы](09-рантаймы.md).
+
+**CLI `iapeer`** — вход для оператора и агентов: создание пиров, обзор и состояние пиров, ручная отправка, остановка и перезапуск, подключение Telegram, установка расширений. См. [12 — CLI](12-cli-reference.md).
+
+## Путь сообщения
+
+1. Отправитель вызывает `send_to_peer(assistant, "...")` — вызов идёт в демон по локальному сокету или HTTP.
+2. Демон находит `assistant` в реестре и проверяет наличие живой сессии.
+3. **Жив** — сообщение вставляется в сессию, демон подтверждает приём, отвечает `доставлено`.
+4. **Спит** — демон поднимает сессию (продолжает прежний диалог или начинает свежий), доставляет, отвечает `доставлено, разбудил`.
+5. **Остановлен** оператором — демон отказывает в доставке и сообщает отправителю прямо.
+
+Ответ `доставлено` означает, что сообщение легло в живую сессию, — очереди «на потом» в обычном случае нет. Механику разбирает [10 — Обмен сообщениями](10-обмен-сообщениями.md).
+
+## Дальше
+
+- Попробовать — [02 — Быстрый старт](02-быстрый-старт.md).
+- Понять понятия глубже — [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md).
+- Разработать расширение или рантайм-пакет — [13 — Архитектура и контракт](13-архитектура-и-контракт.md).