@mono-agent/agent-app 0.3.0 → 0.4.1

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, operator console, observability), write the config, then make it run with the `mono-agent` CLI. 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.
@@ -25,11 +46,12 @@ The `mono-agent` CLI ships with `@mono-agent/agent-app` on npm:
 npm install -g @mono-agent/agent-app   # or: npx @mono-agent/agent-app …
 ```
 
-To run an unreleased build instead, use a clone of the mono-agent workspace:
+To run an unreleased build instead, use a clone of the mono-agent workspace with Node 20+ and pnpm 10 or newer already installed:
 
 ```bash
 git clone <mono-agent-repo> ~/mono-agent && cd ~/mono-agent
-corepack enable && pnpm install --frozen-lockfile && pnpm run build
+pnpm install --frozen-lockfile
+pnpm run build
 alias mono-agent="node ~/mono-agent/packages/agent-app/dist/cli.js"
 ```
 
@@ -37,42 +59,46 @@ 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
    mono-agent start
    ```
 
-   Then run the acceptance smoke test matching the chosen channel (see `references/validation.md`). The operator console URL printed at start lets the user edit config in the browser; saves re-apply live.
+   Then run the acceptance smoke test matching the chosen channel (see `references/validation.md`). To change anything, edit `mono-agent.config.json` directly and run `mono-agent restart`; there is no live browser re-apply.
 
 ## 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 the operator console, sandbox, memory (lite with FTS-only recall, journal with hybrid BM25+vector recall + Ollama 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 runtimes (`MonoRuntimeLike`, incl. the OpenAI Agents SDK), 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
@@ -9,6 +14,7 @@ my-agent/
   mono-agent.config.json   # the single declaration below
   IDENTITY.md              # role, boundaries, references to existing knowledge
   skills/                  # optional: <skill-name>/SKILL.md per selected skill
+  cron/                    # optional: <job-id>.md scheduled prompts
   mcp.json                 # optional: MCP server definitions
   .env                     # optional: secrets; auto-loaded by the CLI, never committed
   .mono-agent/
@@ -31,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"
@@ -40,6 +45,12 @@ my-agent/
   // Local/self-hosted providers for pi:<provider>:<model> references.
   "providers": {
     "piAuthPath": "~/.pi/agent/auth.json", // Pi OAuth credentials (openai-codex, ...)
+    // Pi-native bridge tuning (all optional).
+    "piNative": {
+      "piMaxRetries": 2,                   // 0-8; transient provider-transport retries
+      "maxRetryDelayMs": 60000,            // backoff cap between retries (ms)
+      "piSessionsRoot": ".mono-agent/sessions" // durable JSONL sessions → resume across restarts (unset = in-memory)
+    },
     "local": [
       {
         "id": "ollama",
@@ -63,15 +74,15 @@ 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 Ollama embeddings.
+  //   journal — + hybrid recall (BM25+vector) + decay; needs embeddings.
   //   bujo    — + LLM capture/reconcile + entity graph + auto-scheduled
-  //             reflection/migration; needs Ollama embeddings + chat model.
+  //             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
-    "writeMode": "append-host-summary",    // disabled | append-host-summary
+    "writeMode": "capture",                // disabled | append-host-summary | capture (bujo only)
     "maxBytes": 64000,
     "embeddings": {                        // required for journal and bujo
       "provider": "ollama",                // ollama | openai
@@ -80,15 +91,16 @@ my-agent/
       "apiKeyEnv": "OPENAI_API_KEY",       // or inline "apiKey"; required for openai
       "dim": 768                           // nomic-embed-text:v1.5 output dimension
     },
-    "llm": {                               // required for bujo; omit for lite/journal
-      "provider": "ollama",
-      "model": "qwen3.6:latest",           // any local Ollama chat model; also set MONO_AGENT_MEMORY_LLM_MODEL for CLI
-      "endpoint": "http://localhost:11434" // optional; defaults to http://localhost:11434
+    "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.
@@ -109,24 +121,54 @@ my-agent/
     "unsafeAllowHostProcess": false        // explicit opt-in required for the unsafe fallback
   },
 
-  // Observability: JSONL artifacts + the trace-source registry dashboards read.
-  "artifacts": { "dir": "./.mono-agent/artifacts" },
+  // Observability: JSONL artifacts (always written; the local fallback) + the
+  // trace-source registry that `mono-agent status` reads.
+  "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
   },
 
-  // Local operator console (browser settings + traceability). On by default.
-  "console": {
-    "enabled": true,
-    "port": 0                              // 0 or omitted picks a free loopback port
+  // Optional trace viewer: add a Phoenix (OTLP) exporter to browse traces in
+  // Phoenix. Omit this entry to keep only the local JSONL artifacts.
+  "observability": {
+    "exporters": [
+      { "type": "phoenix", "endpoint": "http://127.0.0.1:6006/v1/traces" }
+    ]
+  },
+
+  // ----- 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"
   },
 
-  // ----- Channels: one section per channel; all independent. An unconfigured
-  // ----- channel reports waiting_for_config and never blocks the others.
+  "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,
@@ -149,6 +191,11 @@ my-agent/
     "apiKey": "..."                        // optional bearer required from clients
   },
 
+  // Telegram & Slack deliver only the FINAL answer by default (no streamed
+  // interim edits) while showing a working indicator — Telegram a "typing…"
+  // action, Slack a 👀 "seen" reaction. This is built-in behavior (not a JSON
+  // field); restoring live interim streaming needs a custom channel driver with
+  // stream.finalOnly=false. The OpenAI-compatible endpoint still streams tokens.
   "telegram": {
     "enabled": true,                       // opt-in; defaults to false (off → "disabled")
     "botToken": "...",
@@ -180,8 +227,8 @@ my-agent/
   },
 
   "a2a": {
+    "enabled": true,                       // canonical channel-root flag (legacy a2a.provider.enabled still honored)
     "provider": {
-      "enabled": true,
       "host": "127.0.0.1",
       "port": 4201,
       "publicBaseUrl": "https://agent.example.com", // Agent Card URL when fronted by a proxy
@@ -222,16 +269,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, console, every channel; exit 0 means ready
-mono-agent start        # console + traceability + every configured channel
-mono-agent start --no-console   # headless (or "console": { "enabled": false })
-mono-agent start --port 4400    # fixed console port (or "console": { "port": 4400 })
+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 operator console URL (config editing in the browser; saves re-apply live without restarting), the traceability source, 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.
+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 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
 
@@ -242,9 +295,9 @@ import { startMonoAgentApp, defaultChannelDrivers } from "@mono-agent/agent-app"
 
 const app = await startMonoAgentApp({
   cwd: process.cwd(),
-  runtime: myCustomRuntime,            // any MonoRuntimeLike (incl. createOpenAIAgentsRuntime)
+  runtime: myCustomRuntime,            // any MonoRuntimeLike
   drivers: [...defaultChannelDrivers(), myCustomDriver],
 });
 ```
 
-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

@@ -74,7 +74,7 @@ What tools or MCP servers does the agent actually need?
 4. Both
 ```
 
-Fills: `tools.allowedTools`, `tools.disallowedTools` (denylist wins), `tools.mcpConfigPath`. Record exact tool names; do not broaden access as a convenience.
+Fills: `tools.allowedTools`, `tools.disallowedTools` (denylist wins), `tools.mcpConfigPath`. Record exact tool names; do not broaden access as a convenience. To expose adapter-derived send tools, include `slack_send_message` / `telegram_send_message`; valid enabled Slack/Telegram adapter config and destination allowlists are still required.
 
 ## 6. Memory Strategy
 
@@ -85,14 +85,14 @@ Should the agent remember anything between conversations?
 
 1. No durable memory yet (recommended for first integration)
 2. Lite memory — FTS keyword recall + rapid-log capture; zero external deps
-3. Journal memory — hybrid recall (BM25+vector) + salience decay; requires local Ollama embeddings
+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 Ollama embeddings AND a local 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`), and tier-specific blocks below.
+(`disabled`/`append-host-summary`/`capture`), and tier-specific blocks below.
 
 **Tier 2 — lite (no external deps):**
 
@@ -110,9 +110,11 @@ No prerequisites. No Ollama. SQLite is bundled.
 
 **Tier 3 — journal (embeddings required):**
 
-- Ask: which local Ollama embeddings model? (default `nomic-embed-text:v1.5` — use the
-  exact `:v1.5` tag; pull first with `ollama pull nomic-embed-text:v1.5`).
-- Default `memory.embeddings.dim` to `768` for `nomic-embed-text:v1.5`.
+- Ask: which embeddings provider/model?
+  - Ollama default: `provider: "ollama"`, model `nomic-embed-text:v1.5`, dim `768`
+    (use the exact `:v1.5` tag; pull first with `ollama pull nomic-embed-text:v1.5`).
+  - OpenAI option: `provider: "openai"`, model `text-embedding-3-small`, API key via
+    `apiKeyEnv`, dim matching the model.
 
 Write:
 
@@ -129,24 +131,27 @@ Write:
 }
 ```
 
-After writing, remind the user to run `mono-agent validate` (checks Ollama reachability
-and that the model is pulled — warns loudly on any failure, never silently falls back).
+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.
-
-- Ask: which local Ollama embeddings model? (default `nomic-embed-text:v1.5` — exact
-  `:v1.5` tag; `ollama pull nomic-embed-text:v1.5`).
-- Ask: which local chat model for LLM pipelines? (e.g. `qwen3.6:latest`;
-  `ollama pull qwen3.6:latest`). A chat model is required — without it the `bujo` tier
-  cannot run capture/reflect/migrate.
-- Ask: should we keep the default reflection/migration schedule (nightly `0 3 * * *` /
-  monthly `0 4 1 * *`), or customise the cron expressions?
+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?
+  - Ollama: local model string such as `qwen3.6:latest`; pull it first with
+    `ollama pull qwen3.6:latest`.
+  - agent-host: SDK runtime model reference such as `pi:openai-codex:gpt-5.5` with
+    `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 consolidation?
+- Ask: should we keep the default consolidation schedule (`0 */2 * * *`), customise the
+  cron expression, or disable scheduled consolidation?
 
 Write (embeddings + chat model):
 
@@ -154,7 +159,7 @@ Write (embeddings + chat model):
 "memory": {
   "mode": "bujo",
   "path": "./.mono-agent/memory",
-  "writeMode": "append-host-summary",
+  "writeMode": "capture",
   "embeddings": {
     "provider": "ollama",
     "model": "nomic-embed-text:v1.5",
@@ -167,11 +172,20 @@ Write (embeddings + chat model):
 }
 ```
 
-If the user customises the ritual schedule, add the `reflection`/`migration` blocks:
+For an agent-host memory LLM, write the `llm` block as:
+
+```jsonc
+"llm": {
+  "provider": "agent-host",
+  "model": "pi:openai-codex:gpt-5.5",
+  "executionMode": "sdk"
+}
+```
+
+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:
@@ -179,12 +193,12 @@ After writing, append a prerequisite note:
 ```
 Before running mono-agent validate, pull the required models:
   ollama pull nomic-embed-text:v1.5
-  ollama pull qwen3.6:latest          # (or whichever chat model you chose)
+  ollama pull qwen3.6:latest          # only if using llm.provider: "ollama"
 ```
 
-Then run `mono-agent validate` — the Memory section confirms Ollama reachability, both
-models are present, the root is writable, and the ritual cadence (with next-run times).
-See `docs/memory.md` for the full tier table, config shapes, and CLI subcommands
+Then run `mono-agent validate` — the Memory section confirms the root is writable,
+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
@@ -207,14 +221,13 @@ Fills: the `sandbox` section — `mode`, `network.mode` (`none`/`localhost`/`all
 Question:
 
 ```text
-Do you need browsable traceability or just local artifacts?
+Do you need a browsable trace viewer or just local artifacts?
 
-1. JSONL artifacts and the operator console (recommended; console is on by default)
-2. JSONL artifacts and the console on a fixed port
-3. JSONL artifacts only (headless)
+1. JSONL artifacts plus Phoenix as the trace viewer (recommended; add an `observability.exporters` Phoenix entry)
+2. JSONL artifacts only (the local fallback; no external viewer)
 ```
 
-Fills: `artifacts.dir`, `traceability.registryDir` / `sourceId` / `sourceLabel`, and the `console` section — `console.port` for a fixed loopback port, `console.enabled: false` (or `start --no-console`) for headless. Artifacts record runtime/tool/message events and summaries, not private chain-of-thought. For a local terminal chat instead of (or alongside) the browser console, mention `mono-agent-tui --config ./mono-agent.config.json`.
+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,23 +1,23 @@
 # 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` |
-| Context compaction, tool-output bloat guard, cost tracking | auto | built into every run |
+| Tool-output bloat guard, cost tracking | auto | built into every run |
+| 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 |
-| OpenAI Agents SDK backend / fully custom runtime | code | `startMonoAgentApp({ runtime })` |
+| Fully custom runtime | code | `startMonoAgentApp({ runtime })` |
 
 ## Context, skills, memory
 
@@ -28,13 +28,14 @@ Every framework capability and how a composed agent reaches it. Use this to answ
 | Per-skill byte cap | config | `context.skillMaxBytes` |
 | 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 Ollama embeddings) | config | `memory.mode: "journal"`, `path`, `memory.embeddings.{provider,model,dim}` |
-| BuJo memory (journal + LLM capture/reconcile ADD/UPDATE/SUPERSEDE/NOOP + entity graph + auto-scheduled reflection/migration; needs Ollama embeddings + chat model) | config | `memory.mode: "bujo"`, `path`, `memory.embeddings.{provider,model,dim}`, `memory.llm.{provider,model,endpoint}` — 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; `MONO_AGENT_MEMORY_LLM_MODEL`, `MONO_AGENT_MEMORY_LLM_ENDPOINT` required for reflect/migrate |
-| Memory liveness check (root writable; Ollama + models for journal/bujo; ritual cadence for bujo — loud warn, no silent fallback) | cli | `mono-agent validate` |
+| 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 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) |
 
 ## Tools, MCP, sandbox
 
@@ -43,6 +44,7 @@ Every framework capability and how a composed agent reaches it. Use this to answ
 | Fail-closed tool policy (empty allowlist = no tools) | auto | default |
 | Tool allow/deny lists (deny wins) | config | `tools.allowedTools`, `tools.disallowedTools` |
 | MCP servers (stdio/sse/http) from a JSON file | config | `tools.mcpConfigPath` |
+| Adapter-derived send tools for enabled Slack/Telegram adapters | config | `tools.allowedTools` must include `slack_send_message` / `telegram_send_message`; valid `slack.*` / `telegram.*` config and existing adapter allowlists provide credentials and destination bounds |
 | Sandbox on/off + srt engine | config | `sandbox.mode` |
 | Network policy (none/localhost/allowlist/all) | config | `sandbox.network.{mode,allowlist}` |
 | Filesystem scopes (readable/writable roots, deny-write globs) | config | `sandbox.readableRoots`, `sandbox.writableRoots`, `sandbox.denyWrite` |
@@ -58,9 +60,11 @@ Every framework capability and how a composed agent reaches it. Use this to answ
 | 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 provider (Agent Card, JSON-RPC + REST, streaming, bearer) | config | `a2a.enabled` (canonical; legacy `a2a.provider.enabled` honored) + `a2a.provider` + `a2a.agent` + `a2a.skill` |
 | A2A consumer settings (remote agent URLs, timeouts) | config + code | `a2a.consumer` holds settings; calls via `createA2AConsumerResponder` |
-| Cron jobs (five-field expressions, timezones, overlap skip) | config | `cron.jobs[]` |
+| 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 })` |
 
@@ -68,13 +72,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 for dashboards) | config | `traceability.{registryDir,sourceId,sourceLabel,heartbeatMs,staleAfterMs}` |
-| Operator console (browser settings editor, traceability views, live config re-apply, bearer token) | config + cli | `console.{enabled,port}`; `--port`, `--no-console` |
-| 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` |
+| 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) |
+| 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` |