@mono-agent/agent-app 0.4.0 → 0.5.0

package/skills/mono-agent-composer/SKILL.md

@@ -5,10 +5,31 @@ description: Construct a working mono-agent in the current folder from one mono-
 
 # Mono Agent Composer
 
-Construct a working mono-agent in the user's current folder — empty or already holding knowledge — from one `mono-agent.config.json`. Discover what the user wants (runtime with backup models, communication channels incl. crons and webhooks, skills, MCP servers, memory strategy incl. semantic search, sandbox, observability), write the config, then make it run with the `mono-agent` CLI. The config is JSON-first: edit `mono-agent.config.json` directly (agents can edit it too); changes apply on the next `mono-agent restart`. No hand-written host code unless the user genuinely needs programmatic composition. `references/feature-coverage.md` maps every framework feature to a config key, CLI flag, or the programmatic escape hatch — consult it before declaring anything impossible or inventing keys.
+Construct a working mono-agent in the user's current folder — empty or already holding knowledge — from one `mono-agent.config.json`. Discover what the user wants (runtime with backup models, communication channels incl. crons and webhooks, skills, MCP servers, memory strategy incl. semantic search, sandbox, observability), write the config, then make it run with the `mono-agent` CLI. The config is JSON-first: edit `mono-agent.config.json` directly (agents can edit it too); changes apply on the next `mono-agent restart`. No hand-written host code unless the user genuinely needs programmatic composition.
+
+## Authoritative Sources — Read the References, Not the Package Source
+
+The `references/*.md` bundled beside this SKILL.md ARE the source of truth for what a mono-agent can do and how to configure it. They are maintained in lockstep with the framework and are **complete for configuration and capabilities**. Answer every "can it do X?", "what is the key for Y?", and "how is Z configured?" from them.
+
+Do **not** read or grep the `@mono-agent` TypeScript/package source — `packages/*/src`, `node_modules/@mono-agent/*`, the vendored runtime — to compose, configure, or troubleshoot an agent. For configuration the source is not more authoritative than the references: it is slower, easy to misread, and full of internal-only knobs that are NOT user-configurable. You will usually be working in the user's own agent folder where that source does not even exist.
+
+- `references/feature-coverage.md` is the **exhaustive** map of every feature to a `config` key, `cli` flag, `auto` behavior, or `code`-only escape hatch. If a capability is listed `config`/`cli`, use that key/flag verbatim. If it is **not in the table, or is marked `code`**, it is not reachable through `mono-agent.config.json` — say so plainly and name the escape hatch. Absence from the table means "not configurable," never "go check the source."
+- The real exception: if the user is **modifying the framework itself** (changing `@mono-agent` package code), that is framework development, not composing an agent — outside this skill. Only then is reading `packages/*/src` correct.
+- The published docs site (<https://mono-agent-docs.vercel.app/>) is the human-facing companion and the repo's `docs/` is a repo-only long-form mirror an end user will not have. Neither is needed: the bundled references work offline and are sufficient.
+
+**Red flags — STOP, you are about to grep source you should not:**
+
+| Thought | Reality |
+| --- | --- |
+| "Let me verify the key name against the source." | The references give the exact key. Trust them; don't re-derive from source. |
+| "The references might be incomplete — I'll double-check `packages/.../src`." | `feature-coverage.md` is exhaustive for config/CLI. Not in it = not configurable. |
+| "I'll confirm the docs and source agree." | You are composing an agent, not auditing the framework. The references are the contract. |
+| "The real behavior is in the source, not just the docs." | For configuration the references are authoritative. Answer from them and stop. |
 
 ## Operating Rules
 
+- Answer capability/config questions from the bundled `references/*.md` (authoritative and complete) — never grep or read the `@mono-agent` package source to compose an agent. See "Authoritative Sources" above.
+
 - The deliverable is a folder that works: `mono-agent.config.json` + `IDENTITY.md` (+ optional `skills/`, `mcp.json`), validated and started — not a tutorial.
 - Start by discovering the intended agent product, not by naming packages.
 - Ask one question at a time; skip anything the user already answered.
@@ -38,22 +59,23 @@ Everything below runs in the user's agent folder, not the workspace.
 
 ## Composition Flow
 
-1. **Discover.** Read `references/discovery-questions.md` and resolve: runtime model + backup models, channels, identity/knowledge, skills, tools/MCP, memory strategy, sandbox, observability, and the acceptance smoke test.
-2. **Scaffold.** In the user's folder run:
+1. **Discover.** Read `references/discovery-questions.md` and resolve: runtime model + backup models, channels, identity/knowledge, skills, tools/MCP, memory strategy, sandbox, observability, and the acceptance smoke test. Then run `mono-agent recipes list` (and `mono-agent recipes show <id>`) for an executable blueprint matching the user's intent; `references/playbooks.md` is the prose companion. If a recipe fits, use it as the starting shape.
+2. **Scaffold.** In the user's folder, prefer the recipe path when one fits:
 
    ```bash
-   mono-agent init --model <ref> [--fallback-models <csv>] [--memory lite|journal|bujo]
+   mono-agent init --recipe <id> [--with slack,cron] [--dry-run]   # blueprint + .env.example + checklist
+   mono-agent init --model <ref> [--fallback-models <csv>] [--memory lite|journal|bujo]   # bare scaffold
    ```
 
-   This writes a minimal `mono-agent.config.json` (webhook enabled as the zero-credential smoke channel), an `IDENTITY.md` that references any knowledge files already present, and `.mono-agent/` working directories. It never overwrites existing files.
-3. **Configure.** Edit `mono-agent.config.json` to match the discovery answers. Read `references/config-blueprint.md` for the full annotated config shape: every channel section, skills, MCP, memory, sandbox, and fallback models.
+   Either writes a `mono-agent.config.json`, an `IDENTITY.md` that references any knowledge files already present, and `.mono-agent/` working directories (recipes also emit a `.env.example` and any extra files). `--dry-run` previews without writing. It never overwrites existing files.
+3. **Configure.** Edit `mono-agent.config.json` to match the discovery answers. Read `references/config-blueprint.md` for the full annotated config shape: every channel section, skills, MCP, memory, sandbox, and fallback models. Run `mono-agent config` to see the resolved configuration field-by-field with each value tagged `env` / `json` / `default` — the fastest way to confirm a value came from where you intended.
 4. **Validate.**
 
    ```bash
-   mono-agent validate
+   mono-agent validate [--recipe <id>] [--consumer <path>]
    ```
 
-   Fix every `[error]` section. `[waiting]` channels are fine — they are simply not configured yet. Re-run until the report says the config is ready.
+   Fix every `[error]` section. `[waiting]` channels are fine — they are simply not configured yet. With `--recipe`, the report also flags any capability the recipe promised that is not yet live. Re-run until the report says the config is ready.
 5. **Start and smoke.**
 
    ```bash
@@ -64,16 +86,19 @@ Everything below runs in the user's agent folder, not the workspace.
 
 ## When Config Is Not Enough
 
-Config-first covers one responder served over any combination of the seven channels (webhook, OpenAI-compatible API, Telegram, Slack, WhatsApp, A2A, cron) plus sandbox, memory (lite with FTS-only recall, journal with hybrid BM25+vector recall + configured embeddings, or bujo with SQLite-indexed hybrid recall + LLM capture/reconcile + entity graph + auto-scheduled reflection/migration), and traceability. Drop to programmatic composition only for: custom `MonoRuntimeLike` implementations, request-scoped runtime extensions, tool approval gates, structured output schemas, multi-agent orchestration (`@mono-agent/agent-orchestrator`), custom channel message texts, or bespoke transports — `references/feature-coverage.md` lists which features are config keys and which are code-only. Read `references/package-map.md` for the package boundaries, and start from `startMonoAgentApp({ drivers, runtime, ... })` or `@mono-agent/agent-host` rather than re-writing lifecycle glue. For eval suites over the composed agent, use `@mono-agent/agent-evals`.
+Config-first covers one responder served over any combination of the seven channels (webhook, OpenAI-compatible API, Telegram, Slack, WhatsApp, A2A, cron) plus sandbox, memory (lite with FTS-only recall, journal with hybrid BM25+vector recall + configured embeddings, or bujo with SQLite-indexed hybrid recall + LLM capture/reconcile + entity graph + auto-scheduled consolidation), and traceability. Drop to programmatic composition only for: custom `MonoRuntimeLike` implementations, request-scoped runtime extensions, tool approval gates, structured output schemas, multi-agent orchestration (`@mono-agent/agent-orchestrator`), custom channel message texts, or bespoke transports — `references/feature-coverage.md` lists which features are config keys and which are code-only. Read `references/package-map.md` for the package boundaries, and start from `startMonoAgentApp({ drivers, runtime, ... })` or `@mono-agent/agent-app` rather than re-writing lifecycle glue.
 
 ## Implementation References
 
 - `references/discovery-questions.md` — the question sequence and which config keys each answer fills.
 - `references/config-blueprint.md` — annotated `mono-agent.config.json` covering every section, plus the folder layout and programmatic escape hatch.
 - `references/feature-coverage.md` — every framework feature mapped to config / CLI / code / dev-tooling coverage; the answer to "can the config do X?".
+- `references/playbooks.md` — end-to-end recipes (persona → config block → `init`/`validate`/`start`/smoke). Check for a matching recipe before hand-assembling a config.
 - `references/package-map.md` — which package owns what, for programmatic composition and troubleshooting.
 - `references/validation.md` — validation commands and per-channel smoke tests; read before claiming the agent works.
 
+These bundled `references/*` files are your authoritative, self-sufficient source — they ship with `@mono-agent/agent-app` and work offline, so always read them rather than the package source or a remote site. The published documentation site at <https://mono-agent-docs.vercel.app/> (notably its Playbooks index and Feature Matrix) is the human-facing companion, and the repo's `docs/reference/feature-registry.md` is a longer-form mirror that exists only inside a framework checkout — neither is required, and do not depend on the live site being reachable.
+
 ## Done Criteria
 
 - `mono-agent validate` exits 0 in the user's folder.

package/skills/mono-agent-composer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Mono Agent Composer"
+  short_description: "Compose config-first mono-agents"
+  default_prompt: "Use $mono-agent-composer to build and validate a config-first mono-agent folder."

package/skills/mono-agent-composer/references/config-blueprint.md

@@ -1,5 +1,10 @@
 # Config Blueprint
 
+> A prose, per-domain version of this reference (runtime, channels, memory, …)
+> lives on the published docs site:
+> <https://mono-agent-docs.vercel.app/config/>. This annotated JSON
+> stays the offline canonical shape.
+
 One `mono-agent.config.json` declares the whole agent. Paths are relative to the folder; every field also has a `MONO_AGENT_*` env var that overrides it (env > JSON > defaults). Omit a section to leave that capability off — every section except `runtime.model` and `context.identityPath` is optional. `references/feature-coverage.md` maps every framework feature to its config key; if a capability is not listed there, it needs the programmatic escape hatch.
 
 ## Folder Layout
@@ -32,7 +37,6 @@ my-agent/
     "executionMode": "sdk",                // sdk | cli (default inferred from model)
     "effort": "medium",                    // none|low|medium|high|xhigh|max
     "permissionMode": "default",           // default|plan|acceptEdits|bypassPermissions (CLI backends)
-    "reasoningSummary": "auto",            // auto|concise|detailed|off|on
     "maxTurns": 0,                         // 0 or omitted means unlimited; 1-100 caps turns
     "workspace": ".",
     "session": { "mode": "continuous", "idleTimeoutMs": 1800000 } // or "per-message"
@@ -70,11 +74,11 @@ my-agent/
   },
 
   // Memory strategy. Omit the section for no memory.
-  // Three tiers over one substrate (memory-store + memory-bujo):
+  // Three tiers over one substrate (@mono-agent/memory store + bujo subpaths):
   //   lite    — FTS keyword recall + rapid-log; no external deps.
   //   journal — + hybrid recall (BM25+vector) + decay; needs embeddings.
   //   bujo    — + LLM capture/reconcile + entity graph + auto-scheduled
-  //             reflection/migration; needs embeddings + an app-level memory.llm.
+  //             lightweight consolidation; needs embeddings + an app-level memory.llm for capture/tier selection.
   "memory": {
     "mode": "bujo",                        // lite | journal | bujo
     "path": "./.mono-agent/memory",        // root directory for all tiers
@@ -87,17 +91,16 @@ my-agent/
       "apiKeyEnv": "OPENAI_API_KEY",       // or inline "apiKey"; required for openai
       "dim": 768                           // nomic-embed-text:v1.5 output dimension
     },
-    "llm": {                               // enables bujo capture/rituals; omit for lite/journal
+    "llm": {                               // enables bujo capture and the effective bujo tier; omit for lite/journal
       // Env: MONO_AGENT_MEMORY_LLM_PROVIDER / _MODEL / _EXECUTION_MODE / _ENDPOINT.
       "provider": "ollama",                // ollama | agent-host
       "model": "qwen3.6:latest",           // ollama: model string; agent-host: runtime ref, e.g. pi:openai-codex:gpt-5.5
       "endpoint": "http://localhost:11434" // ollama only; invalid for agent-host
       // For agent-host, use: "model": "pi:openai-codex:gpt-5.5", "executionMode": "sdk"; omit endpoint.
     },
-    // Bujo auto-scheduler — override defaults or disable per-ritual.
-    // Rituals run in-app; no external cron or launchd needed.
-    "reflection": { "enabled": true, "cron": "0 3 * * *" },  // default: nightly 03:00
-    "migration":  { "enabled": true, "cron": "0 4 1 * *" }   // default: 1st of month 04:00
+    // Bujo auto-scheduler — override the default or disable it.
+    // Consolidation runs in-app; no external cron or launchd needed.
+    "consolidation": { "enabled": true, "cron": "0 */2 * * *" } // default: every two hours
   },
 
   // Fail-closed tool policy + MCP servers. Deny wins; overlap is rejected.
@@ -120,13 +123,21 @@ my-agent/
 
   // Observability: JSONL artifacts (always written; the local fallback) + the
   // trace-source registry that `mono-agent status` reads.
-  "artifacts": { "dir": "./.mono-agent/artifacts" },
+  "artifacts": {
+    "dir": "./.mono-agent/artifacts",
+    "retention": { "maxAgeDays": 365, "maxCount": 50000, "dryRun": false },
+    "memoryRetention": { "maxAgeDays": 7, "maxCount": 5000, "dryRun": false }
+  },
   "traceability": {
     "registryDir": "./.mono-agent/trace-sources",
     "sourceId": "my-agent",
     "sourceLabel": "My Agent",
     "heartbeatMs": 10000,
-    "staleAfterMs": 30000
+    "staleAfterMs": 30000,
+    // Also mirror this agent's manifest into the global ~/.mono-agent/trace-sources
+    // registry so `mono-agent tui` discovers it from any directory. Default true;
+    // set false to keep the agent visible only via its own registryDir.
+    "globalDiscovery": true
   },
 
   // Optional trace viewer: add a Phoenix (OTLP) exporter to browse traces in
@@ -137,8 +148,27 @@ my-agent/
     ]
   },
 
-  // ----- Channels: one section per channel; all independent. An unconfigured
-  // ----- channel reports waiting_for_config and never blocks the others.
+  // ----- Channels: one section per channel; all independent. Most channels are
+  // ----- opt-in; operator surfaces (`tui`, `live`) default on and can opt out.
+  // ----- A waiting/disabled channel never blocks the others.
+
+  "tui": {
+    "enabled": true,                       // default-on loopback operator console endpoint
+    "host": "127.0.0.1",
+    "port": 0,
+    "basePath": "/tui",
+    "allowNonLoopback": false,
+    "apiKey": "optional-bearer"
+  },
+
+  "live": {
+    "enabled": true,                       // default-on read-only SSE relay for mono-agent web
+    "host": "127.0.0.1",
+    "port": 0,
+    "basePath": "/live",
+    "allowNonLoopback": false,
+    "apiKey": "optional-bearer"
+  },
 
   "webhook": {
     "enabled": true,
@@ -184,38 +214,47 @@ my-agent/
     "stripMentionText": true
   },
 
-  "whatsapp": {
-    "enabled": true,                       // opt-in; defaults to false (off → "disabled")
-    "allowedChatJids": ["123@s.whatsapp.net"], // or "allowAllChats": true
-    "allowAllChats": false,
-    "groupMode": "mention",                // mention | any (group trigger rule)
-    "botJids": ["456@s.whatsapp.net"],
-    "mentionTextAliases": ["@agent"],
-    "stripMentionText": true
-    // Baileys auth state lives in .mono-agent/whatsapp-auth; the start log
-    // prints a QR code to scan on first login.
-  },
-
-  "a2a": {
-    "provider": {
-      "enabled": true,
-      "host": "127.0.0.1",
-      "port": 4201,
-      "publicBaseUrl": "https://agent.example.com", // Agent Card URL when fronted by a proxy
-      "allowNonLoopback": false,
-      "requireBearer": false,
-      "bearerToken": "..."
-    },
-    "agent": { "name": "My Agent", "description": "What it does.", "version": "0.1.0" },
-    "skill": { "id": "main", "name": "Main", "description": "Primary skill.", "tags": ["agent"] },
-    "consumer": {                          // settings for calling remote A2A agents
-      "remoteAgentUrls": ["http://127.0.0.1:4202"],
-      "defaultRemoteAgentUrl": "http://127.0.0.1:4202",
-      "bearerToken": "...",
-      "timeoutMs": 30000
-      // Consumed programmatically (createA2AConsumerResponder); the app's A2A
-      // channel runs the provider side.
-    }
+  "channels": {
+    "plugins": [
+      {
+        "package": "@mono-agent/whatsapp-adapter",
+        "id": "whatsapp",
+        "config": {
+          "enabled": true,                 // opt-in; defaults to false (off → "disabled")
+          "allowedChatJids": ["123@s.whatsapp.net"], // or "allowAllChats": true
+          "allowAllChats": false,
+          "groupMode": "mention",          // mention | any (group trigger rule)
+          "botJids": ["456@s.whatsapp.net"],
+          "mentionTextAliases": ["@agent"],
+          "stripMentionText": true
+          // Baileys auth state lives in .mono-agent/whatsapp-auth; the start log
+          // prints a QR code to scan on first login.
+        }
+      },
+      {
+        "package": "@mono-agent/a2a-adapter",
+        "id": "a2a",
+        "config": {
+          "enabled": true,
+          "provider": {
+            "host": "127.0.0.1",
+            "port": 4201,
+            "publicBaseUrl": "https://agent.example.com",
+            "allowNonLoopback": false,
+            "requireBearer": false,
+            "bearerToken": "..."
+          },
+          "agent": { "name": "My Agent", "description": "What it does.", "version": "0.1.0" },
+          "skill": { "id": "main", "name": "Main", "description": "Primary skill.", "tags": ["agent"] },
+          "consumer": {                    // settings for calling remote A2A agents
+            "remoteAgentUrls": ["http://127.0.0.1:4202"],
+            "defaultRemoteAgentUrl": "http://127.0.0.1:4202",
+            "bearerToken": "...",
+            "timeoutMs": 30000
+          }
+        }
+      }
+    ]
   },
 
   "cron": {
@@ -239,18 +278,22 @@ my-agent/
 ## Lifecycle
 
 ```bash
+mono-agent recipes list                 # executable blueprints (id, risk, tags)
+mono-agent recipes show <id>            # generated config + .env.example + follow-up checklist
+mono-agent init --recipe <id> [--with slack,cron] [--dry-run]   # scaffold from a blueprint
 mono-agent init --model claude:claude-sonnet-4-6 --fallback-models pi:ollama:gemma4:31b [--memory lite|journal|bujo]
-mono-agent validate     # per-section report incl. sandbox, observability, every channel; exit 0 means ready
+mono-agent config       # resolved config field-by-field, each value tagged env/json/default
+mono-agent validate [--recipe <id>] [--consumer <path>]     # per-section report; --recipe also checks the recipe's capabilities
 mono-agent start        # traceability + every configured channel
 mono-agent restart      # apply config edits (config is JSON-first; restart to re-apply)
 mono-agent restart --force  # restart AND purge persisted pi sessions (fresh start; durable memory kept)
 ```
 
-A `.env` file in the folder is loaded automatically (exported shell variables win); use `--env-file <path>` for an alternate file. `start` prints the traceability source (Phoenix when an `observability.exporters` Phoenix entry is configured, otherwise the local JSONL artifacts) and one status line per channel: `running` with its endpoint facts, `waiting_for_config` with the exact missing setting, `disabled`, or `failed` with the reason. Config is JSON-first: edit `mono-agent.config.json` directly (agents can edit it) and run `mono-agent restart` to apply — there is no live browser re-apply.
+A `.env` file in the folder is loaded automatically (exported shell variables win); use `--env-file <path>` for an alternate file. `validate --consumer <path>` loads the consumer folder's `.env` by default and resolves relative `--config` / `--env-file` paths there. `start` prints the traceability source (Phoenix when an `observability.exporters` Phoenix entry is configured, otherwise the local JSONL artifacts) and one status line per channel: `running` with its endpoint facts, `waiting_for_config` with the exact missing setting, `disabled`, or `failed` with the reason. Config is JSON-first: edit `mono-agent.config.json` directly (agents can edit it) and run `mono-agent restart` to apply — there is no live browser re-apply.
 
-For BuJo capture and rituals, configure `memory.llm`. Use `provider: "ollama"` with a local Ollama chat model string and optional `endpoint`, or `provider: "agent-host"` with `model` as a normal SDK runtime model reference such as `pi:openai-codex:gpt-5.5` and `executionMode: "sdk"`. `endpoint` is Ollama-only, and CLI-backed refs such as `codex:gpt-5.5` are rejected for memory LLMs until runtimes can enforce no external actions. The same values can be supplied via `MONO_AGENT_MEMORY_LLM_PROVIDER`, `MONO_AGENT_MEMORY_LLM_MODEL`, `MONO_AGENT_MEMORY_LLM_EXECUTION_MODE`, and `MONO_AGENT_MEMORY_LLM_ENDPOINT`. The standalone `memory-bujo` maintenance CLI remains Ollama-only; `agent-host` LLM capture is an in-app composition path that injects the `LlmComplete` implementation into the BuJo store.
+For BuJo capture and the effective `bujo` tier that runs scheduled consolidation, configure `memory.llm`. Use `provider: "ollama"` with a local Ollama chat model string and optional `endpoint`, or `provider: "agent-host"` with `model` as a normal SDK runtime model reference such as `pi:openai-codex:gpt-5.5` and `executionMode: "sdk"`. `endpoint` is Ollama-only, and CLI-backed refs such as `codex:gpt-5.5` are rejected for memory LLMs until runtimes can enforce no external actions. The same values can be supplied via `MONO_AGENT_MEMORY_LLM_PROVIDER`, `MONO_AGENT_MEMORY_LLM_MODEL`, `MONO_AGENT_MEMORY_LLM_EXECUTION_MODE`, and `MONO_AGENT_MEMORY_LLM_ENDPOINT`. The standalone `memory-bujo` maintenance CLI remains Ollama-only; `agent-host` LLM capture is an in-app composition path that injects the `LlmComplete` implementation into the BuJo store.
 
-For a local terminal chat against the same config, `@mono-agent/tui` ships a `mono-agent-tui` bin: `mono-agent-tui --config ./mono-agent.config.json`.
+For operator views, run `mono-agent tui` or `mono-agent web` from any directory once the agent is started. Both discover running agents via the trace-source registry. The TUI chats over the default-on `tui` stream endpoint (`"tui": {"enabled": false}` opts out); the web PWA reads artifacts and live updates from the default-on `live` relay (`"live": {"enabled": false}` opts out). Web history/live views show agent runs by default; add `mono-agent web --include-memory` to inspect memory-maintenance runs. Both bind loopback by default. The low-level `mono-agent-tui` bin also supports `--responder <file>` (embedded, an ESM module default-exporting an `AgentResponderLike` or exporting `createResponder(env, cwd, configJson)`) and `--url <baseUrl>` (direct connect).
 
 ## Programmatic Escape Hatch
 
@@ -266,4 +309,4 @@ const app = await startMonoAgentApp({
 });
 ```
 
-For a bare responder without channels, use `@mono-agent/config` + `@mono-agent/agent-host` (`createConfiguredAgentResponder` — also takes `memory`, `historyStore`, `runtimeOptions`, `runtimeOptionsForRequest`). For multi-agent orchestration, add `@mono-agent/agent-orchestrator` (`createCollaboratorToolRuntimeExtension`) — see `references/package-map.md`. Channel message texts and stream tuning (welcome/help/error texts, edit debounce) are channel-driver overrides, not config keys.
+For a bare responder without channels, use `@mono-agent/config` + `@mono-agent/agent-app` (`createConfiguredAgentResponder` — also takes `memory`, `historyStore`, `runtimeOptions`, `runtimeOptionsForRequest`). For multi-agent orchestration, add `@mono-agent/agent-orchestrator` (`createCollaboratorToolRuntimeExtension`) — see `references/package-map.md`. Channel message texts and stream tuning (welcome/help/error texts, edit debounce) are channel-driver overrides, not config keys.

package/skills/mono-agent-composer/references/discovery-questions.md

@@ -35,7 +35,7 @@ Where should people (or other agents) reach this agent? Pick every channel that
 7. Cron (scheduled prompts, no inbound channel)
 ```
 
-Fills one config section per choice: `webhook`, `openaiApi`, `telegram`, `slack`, `whatsapp`, `a2a`, `cron`. Channels are independent: an unconfigured channel reports `waiting_for_config` and never blocks the others. For chat channels collect tokens and allowlists (chat IDs, channel IDs, JIDs). For HTTP channels collect host/port/path and whether non-loopback binding is allowed (default: loopback only).
+Fills one config section per choice: built-in channels use `webhook`, `openaiApi`, `telegram`, `slack`, and `cron`; WhatsApp and A2A are external channel plugins under `channels.plugins[]` with package names `@mono-agent/whatsapp-adapter` and `@mono-agent/a2a-adapter`. Channels are independent: an unconfigured channel reports `waiting_for_config` and never blocks the others. For chat channels collect tokens and allowlists (chat IDs, channel IDs, JIDs). For HTTP channels collect host/port/path and whether non-loopback binding is allowed (default: loopback only).
 
 ## 3. Identity And Existing Knowledge
 
@@ -87,10 +87,10 @@ Should the agent remember anything between conversations?
 2. Lite memory — FTS keyword recall + rapid-log capture; zero external deps
 3. Journal memory — hybrid recall (BM25+vector) + salience decay; requires embeddings
 4. BuJo memory — full tier: journal + LLM capture/reconcile + entity graph + auto-scheduled
-   reflection/migration; requires embeddings AND a chat model
+   consolidation; requires embeddings AND a chat model
 ```
 
-All tiers share the same `@mono-agent/memory-bujo` substrate. Fills: `memory.mode`
+All tiers share the same `@mono-agent/memory/bujo` substrate. Fills: `memory.mode`
 (`lite`/`journal`/`bujo`), `memory.path`, `memory.writeMode`
 (`disabled`/`append-host-summary`/`capture`), and tier-specific blocks below.
 
@@ -134,13 +134,12 @@ Write:
 After writing, remind the user to run `mono-agent validate` (checks root writability and
 provider-specific liveness; Ollama model pulls are checked only when using Ollama).
 
-**Tier 4 — bujo (embeddings + chat model + auto-rituals):**
+**Tier 4 — bujo (embeddings + chat model + consolidation):**
 
 Proactively explain what bujo does: capture → reconcile (ADD/UPDATE/SUPERSEDE/NOOP),
-hybrid BM25+vector recall, entity graph, reflection (decay + insight synthesis), monthly
-migration (promote/reschedule/cluster/forget), living `index.md` + `future-log.md`.
-The reflection and migration rituals are **auto-scheduled in-app** — no external cron or
-launchd setup needed.
+hybrid BM25+vector recall, entity graph, scheduled consolidation (decay + duplicate
+superseding), living `index.md`, and an empty retired `future-log.md` stub. Consolidation
+is **auto-scheduled in-app** — no external cron or launchd setup needed.
 
 - Ask: which embeddings provider/model? Use the same choices as journal.
 - Ask: which chat LLM provider/model for LLM pipelines?
@@ -150,9 +149,9 @@ launchd setup needed.
     `executionMode: "sdk"`. Do not use CLI-backed refs such as `codex:gpt-5.5`; they are
     rejected for memory LLMs until runtimes can enforce no external actions.
 - Ask: should per-turn intelligent capture be enabled (`writeMode: "capture"`), or only
-  deterministic rapid-log summaries (`append-host-summary`) plus scheduled rituals?
-- Ask: should we keep the default reflection/migration schedule (nightly `0 3 * * *` /
-  monthly `0 4 1 * *`), or customise the cron expressions?
+  deterministic rapid-log summaries (`append-host-summary`) plus scheduled consolidation?
+- Ask: should we keep the default consolidation schedule (`0 */2 * * *`), customise the
+  cron expression, or disable scheduled consolidation?
 
 Write (embeddings + chat model):
 
@@ -183,11 +182,10 @@ For an agent-host memory LLM, write the `llm` block as:
 }
 ```
 
-If the user customises the ritual schedule, add the `reflection`/`migration` blocks:
+If the user customises the consolidation schedule, add the `consolidation` block:
 
 ```jsonc
-"reflection": { "enabled": true, "cron": "0 3 * * *" },
-"migration":  { "enabled": true, "cron": "0 4 1 * *" }
+"consolidation": { "enabled": true, "cron": "0 */4 * * *" }
 ```
 
 After writing, append a prerequisite note:
@@ -199,8 +197,8 @@ Before running mono-agent validate, pull the required models:
 ```
 
 Then run `mono-agent validate` — the Memory section confirms the root is writable,
-provider-specific liveness, and the ritual cadence (with next-run times).
-See `docs/memory.md` for the full tier table, config shapes, and CLI subcommands
+provider-specific liveness, and the consolidation cadence.
+See `docs/memory/index.md` for the full tier table, config shapes, and CLI subcommands
 (`memory-bujo rebuild|recall|index|reflect|migrate`).
 
 ## 7. Sandbox
@@ -229,7 +227,7 @@ Do you need a browsable trace viewer or just local artifacts?
 2. JSONL artifacts only (the local fallback; no external viewer)
 ```
 
-Fills: `artifacts.dir`, `traceability.registryDir` / `sourceId` / `sourceLabel`, and — when Phoenix is wanted — an `observability.exporters` (phoenix) OTLP entry. Local JSONL artifacts are always written and are the fallback when no exporter is configured. Artifacts record runtime/tool/message events and summaries, not private chain-of-thought. For a local terminal chat, mention `mono-agent-tui --config ./mono-agent.config.json`. Config is JSON-first — edit `mono-agent.config.json` directly and run `mono-agent restart` to apply changes.
+Fills: `artifacts.dir`, `traceability.registryDir` / `sourceId` / `sourceLabel`, and — when Phoenix is wanted — an `observability.exporters` (phoenix) OTLP entry. Local JSONL artifacts are always written and are the fallback when no exporter is configured. Artifacts record runtime/tool/message events and summaries, not private chain-of-thought. For a terminal operator console, mention `mono-agent tui` (run from anywhere once the agent is started; live chat with thinking/tool insight, run replay, config view). Config is JSON-first — edit `mono-agent.config.json` directly and run `mono-agent restart` to apply changes.
 
 ## 9. Acceptance Smoke Test
 

package/skills/mono-agent-composer/references/feature-coverage.md

@@ -1,21 +1,20 @@
 # Feature Coverage
 
-Every framework capability and how a composed agent reaches it. Use this to answer "can the config do X?" without guessing: `config` = a `mono-agent.config.json` key (env var override always exists), `cli` = a `mono-agent` CLI flag/command, `auto` = always on when the app runs, `code` = programmatic escape hatch only, `dev` = development/test tooling. The repo's `docs/feature-registry.md` is the long-form source of truth.
+Every framework capability and how a composed agent reaches it. This table is the **authoritative, exhaustive** answer to "can the config do X?" — answer from it, do not grep the `@mono-agent` package source to confirm. `config` = a `mono-agent.config.json` key (env var override always exists), `cli` = a `mono-agent` CLI flag/command, `auto` = always on when the app runs, `code` = programmatic escape hatch only, `dev` = development/test tooling. A capability that is absent here, or marked `code`, is not reachable through config — that is the answer, not a cue to read source. The repo's `docs/reference/feature-registry.md` (framework checkout only) and the documentation site at <https://mono-agent-docs.vercel.app/> are longer-form human-facing mirrors of this same table.
 
 ## Runtime
 
 | Capability | Coverage | Where |
 | --- | --- | --- |
-| Model backends: claude (sdk/cli), codex (cli), pi sdk providers (OpenAI, Copilot, OpenRouter, Ollama, ...) | config | `runtime.model` |
+| Model backends: claude (sdk/cli), codex (cli), pi sdk providers (OpenAI, Copilot, OpenRouter, Ollama, ...), opencode (cli, `opencode:<provider>:<model>` via the OpenCode server) | config | `runtime.model` |
 | Backup models on retryable provider failure | config | `runtime.fallbackModels` |
 | Execution mode (sdk/cli), effort, max turns, workspace | config | `runtime.executionMode`, `runtime.effort`, `runtime.maxTurns`, `runtime.workspace` |
 | Tool-permission posture for CLI backends | config | `runtime.permissionMode` |
-| Reasoning summary verbosity | config | `runtime.reasoningSummary` |
 | Continuous provider sessions with idle eviction | config | `runtime.session.{mode,idleTimeoutMs}` |
 | Local providers (Ollama / LM Studio / OpenAI-compatible) | config | `providers.local[]` |
 | Pi OAuth credentials | config | `providers.piAuthPath` |
 | Tool-output bloat guard, cost tracking | auto | built into every run |
-| Context handling | provider | delegated to the provider; the pi bridge (pi-agent-core AgentHarness) runs no automatic in-loop summarization, so runs report `context_compaction_applied: null` |
+| Context handling / auto-compaction | provider + auto | delegated to the provider; the pi bridge drives `AgentHarness.compact()` (proactive before a near-window turn + reactive recovery on overflow). Runs report `context_compaction_applied: true` / `false` / `null` |
 | Structured output (JSON schema), live input steering | code | harness `runtimeOptions` |
 | Tool approval gates (risk tiers, timeouts, always-allow) | code | `createMonoRuntime({ onToolApprovalRequest, ... })` — needs a host UI |
 | Fully custom runtime | code | `startMonoAgentApp({ runtime })` |
@@ -30,11 +29,11 @@ Every framework capability and how a composed agent reaches it. Use this to answ
 | Conversation history (in-memory; unlimited unless turns are capped) | auto | sized from `runtime.maxTurns`; custom store via code |
 | Lite memory (FTS keyword recall + rapid-log capture; no external deps) | config | `memory.mode: "lite"`, `path`, `maxBytes`, `writeMode` |
 | Journal memory (hybrid recall BM25+vector + salience decay; needs configured embeddings) | config | `memory.mode: "journal"`, `path`, `memory.embeddings.{provider,model,dim}` (`provider: "ollama" | "openai"`) |
-| BuJo memory (journal + LLM capture/reconcile ADD/UPDATE/SUPERSEDE/NOOP + entity graph + auto-scheduled reflection/migration; needs embeddings + an app-level `memory.llm`) | config | `memory.mode: "bujo"`, `path`, `memory.embeddings.{provider,model,dim}`, `memory.llm` with `provider: "ollama"` (`model`, optional `endpoint`) or `provider: "agent-host"` (`model` is an SDK runtime model ref, e.g. `pi:openai-codex:gpt-5.5`, optional `executionMode: "sdk"`) — see `docs/memory.md` |
-| BuJo reflection auto-scheduler (nightly decay + insight synthesis; in-app, no external cron needed) | config | `memory.reflection.{enabled,cron}` (default `0 3 * * *`); env `MONO_AGENT_MEMORY_REFLECTION_CRON`, `MONO_AGENT_MEMORY_REFLECTION_ENABLED` |
-| BuJo migration auto-scheduler (monthly promote/reschedule/cluster/forget; in-app) | config | `memory.migration.{enabled,cron}` (default `0 4 1 * *`); env `MONO_AGENT_MEMORY_MIGRATION_CRON`, `MONO_AGENT_MEMORY_MIGRATION_ENABLED` |
-| Memory out-of-band maintenance CLI (rebuild/recall/index/reflect/migrate) | cli | `memory-bujo <subcommand> <root>`; opt-in `MONO_AGENT_MEMORY_EMBEDDINGS_PROVIDER`/`_MODEL`/`_DIM` for semantic recall; reflect/migrate are Ollama-only and require `MONO_AGENT_MEMORY_LLM_MODEL` (optional `MONO_AGENT_MEMORY_LLM_ENDPOINT`) |
-| Memory liveness check (root writable; provider-specific Ollama checks only when embeddings/chat use Ollama; BuJo LLM config + ritual cadence — loud warn, no silent fallback) | cli | `mono-agent validate` |
+| BuJo memory (journal + LLM capture/reconcile ADD/UPDATE/SUPERSEDE/NOOP + entity graph + auto-scheduled consolidation; needs embeddings + an app-level `memory.llm`) | config | `memory.mode: "bujo"`, `path`, `memory.embeddings.{provider,model,dim}`, `memory.llm` with `provider: "ollama"` (`model`, optional `endpoint`) or `provider: "agent-host"` (`model` is an SDK runtime model ref, e.g. `pi:openai-codex:gpt-5.5`, optional `executionMode: "sdk"`) — see `docs/memory/index.md` |
+| BuJo consolidation auto-scheduler (lightweight decay + duplicate superseding; in-app, no external cron needed) | config | `memory.consolidation.{enabled,cron}` (default `0 */2 * * *`); env `MONO_AGENT_MEMORY_CONSOLIDATION_CRON`, `MONO_AGENT_MEMORY_CONSOLIDATION_ENABLED` |
+| Memory out-of-band maintenance CLI (rebuild/recall/index/legacy reflect/migrate) | cli | `memory-bujo <subcommand> <root>`; opt-in `MONO_AGENT_MEMORY_EMBEDDINGS_PROVIDER`/`_MODEL`/`_DIM` for semantic recall; legacy reflect/migrate are Ollama-only and require `MONO_AGENT_MEMORY_LLM_MODEL` (optional `MONO_AGENT_MEMORY_LLM_ENDPOINT`) |
+| Config-aware memory preview CLI (stats/today/show/search/top for the configured backend; local search warns and falls back to FTS-only when embeddings are down) | cli | `mono-agent memory stats\|today\|show <date>\|search <query>\|top [--limit <n>] [--json]` |
+| Memory liveness check (root writable; provider-specific Ollama checks only when embeddings/chat use Ollama; BuJo LLM config + consolidation cadence — loud warn, no silent fallback) | cli | `mono-agent validate` |
 | Host summaries appended after runs | config | `memory.writeMode: "append-host-summary"` |
 | Auto-provisioned read-only `memory_recall` tool (hybrid keyword+semantic search) exposed to the agent from the single memory config; no chat LLM | config | `config.memory.recallTool.enabled` (`MONO_AGENT_MEMORY_RECALL_TOOL_ENABLED`, default on for journal/bujo with embeddings) |
 
@@ -60,9 +59,12 @@ Every framework capability and how a composed agent reaches it. Use this to answ
 | OpenAI-compatible API (/v1/models, /v1/chat/completions, SSE, bearer) | config | `openaiApi` section |
 | Telegram (long polling, chat allowlist) | config | `telegram` section |
 | Slack (Socket Mode, channel allowlist, mention handling) | config | `slack` section |
-| WhatsApp (Baileys, QR login, group mention/any triggers) | config | `whatsapp` section |
-| A2A provider (Agent Card, JSON-RPC + REST, streaming, bearer) | config | `a2a.provider` + `a2a.agent` + `a2a.skill` |
-| A2A consumer settings (remote agent URLs, timeouts) | config + code | `a2a.consumer` holds settings; calls via `createA2AConsumerResponder` |
+| External channel plugins | config | `channels.plugins[]: { package, id?, label?, config? }`; package must export `createChannelDriver(options)` or a default driver factory |
+| WhatsApp (Baileys, QR login, group mention/any triggers) | config | `channels.plugins[].package: "@mono-agent/whatsapp-adapter"` plus plugin `config.{enabled,allowedChatJids,allowAllChats,groupMode,botJids,mentionTextAliases,stripMentionText}` |
+| A2A provider (Agent Card, JSON-RPC + REST, streaming, bearer) | config | `channels.plugins[].package: "@mono-agent/a2a-adapter"` plus plugin `config.provider`, `config.agent`, `config.skill`; `config.enabled` is canonical |
+| A2A consumer settings (remote agent URLs, timeouts) | config + code | same A2A plugin entry's `config.consumer`; calls via `createA2AConsumerResponder` |
+| TUI stream endpoint (operator console transport) | config | `tui.{enabled,host,port,basePath,allowNonLoopback,apiKey}`; default on, loopback |
+| Live event relay (read-only run-event SSE for web) | config | `live.{enabled,host,port,basePath,allowNonLoopback,apiKey}`; default on, loopback |
 | Cron jobs (five-field expressions, timezones, overlap skip) | config | `cron.jobs[]`, single-job `MONO_AGENT_CRON_*`, or one markdown file per job in `cron.dir` / `MONO_AGENT_CRON_DIR` (default `cron/`) |
 | Channel message texts / stream tuning (welcome, debounce, ...) | code | channel driver overrides |
 | Custom transports | code | implement `ChannelDriver`, pass via `startMonoAgentApp({ drivers })` |
@@ -71,13 +73,16 @@ Every framework capability and how a composed agent reaches it. Use this to answ
 
 | Capability | Coverage | Where |
 | --- | --- | --- |
-| JSONL run artifacts (events + summaries, secrets redacted) | config | `artifacts.dir` |
-| Trace-source registry (heartbeat manifests `mono-agent status` reads) | config | `traceability.{registryDir,sourceId,sourceLabel,heartbeatMs,staleAfterMs}` |
+| JSONL run artifacts (events + summaries, secrets redacted) | config | `artifacts.dir`, `artifacts.retention`, `artifacts.memoryRetention` |
+| Trace-source registry (heartbeat manifests `mono-agent status` reads) | config | `traceability.{registryDir,sourceId,sourceLabel,heartbeatMs,staleAfterMs,globalDiscovery}` |
 | Phoenix trace viewer (OTLP exporter; local JSONL artifacts are the fallback) | config | `observability.exporters` (phoenix entry) |
-| Terminal chat (TUI with transcript + redacted config pane) | cli | `mono-agent-tui --config ./mono-agent.config.json` |
-| Scaffold / validate / start / install-skill | cli | `mono-agent init|validate|start|install-skill` |
+| Operator console (live chat with thinking/tool/telemetry insight, run replay, config view) | cli | `mono-agent tui [--agent <label>]`; agents serve the `tui` stream endpoint by default (`tui.enabled`, loopback) |
+| Session Recorder web PWA (read-only run browser) | cli | `mono-agent web [--host] [--port] [--no-open] [--allow-non-loopback] [--include-memory]`; consumes the default-on `live` relay and local artifacts; memory runs are opt-in |
+| Executable config blueprints (generate config + `.env.example` + checklist) | cli | `mono-agent recipes list\|show <id>`, `mono-agent init --recipe <id>` |
+| Resolved config view (every field tagged env/json/default) | cli | `mono-agent config` |
+| Scaffold / validate / start / install-skill | cli | `mono-agent init\|validate [--consumer <path>]\|config\|recipes\|start\|install-skill` |
+| Recipe capability check (selected recipe live?) | cli | `mono-agent validate --recipe <id>` |
 | `.env` auto-loading | cli | automatic; `--env-file <path>` |
 | Explicit failure objects (no fake success) | auto | harness |
 | Per-request runtime options, custom memory/history stores | code | `createConfiguredAgentResponder` options |
 | Multi-agent delegation (`ask_collaborator` loopback MCP tool) | code | `@mono-agent/agent-orchestrator` |
-| Eval scenarios/suites (trajectory + judge assertions) | dev | `@mono-agent/agent-evals`, live runs via `MONO_AGENT_EVAL_LIVE=1` |