@mono-agent/agent-app 0.4.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, 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,
@@ -197,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
@@ -239,18 +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, 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 +300,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

@@ -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) |
 
@@ -61,8 +60,10 @@ 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` |
+| 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 +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 `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` |

package/skills/mono-agent-composer/references/package-map.md

@@ -4,7 +4,7 @@ Use this map to select the smallest mono-agent package set for a host. Package c
 
 ## App Join (default)
 
-`@mono-agent/agent-app` is the config-first host: it loads `mono-agent.config.json`, builds the responder through `agent-host`, and drives every configured channel plus traceability and any configured observability exporters. It ships the `mono-agent` CLI (`init`, `validate`, `start`) and is the only publishable package allowed to compose communication adapters.
+`@mono-agent/agent-app` is the config-first host: it loads `mono-agent.config.json`, owns configured runtime/harness/responder/memory composition, and drives every configured channel plus traceability and any configured observability exporters. It ships the `mono-agent` CLI (`init`, `validate`, `start`) and is the only publishable package allowed to compose communication adapters.
 
 ```ts
 import { startMonoAgentApp } from "@mono-agent/agent-app";
@@ -23,13 +23,13 @@ Every real host needs these concepts:
 | Shared request/response shape | `@mono-agent/agent-contracts` | `AgentResponder`, request, response, stream, cancellation contracts | Prompt building, runtime execution, transport |
 | Core config | `@mono-agent/config` | Runtime, context, memory, tools, artifact, traceability settings | Adapter credentials, chat allowlists |
 | Runtime facade | `@mono-agent/runtime-adapter` | Model refs, execution-mode validation, local provider runtime options | Prompts, adapters, memory |
-| Configured responder | `@mono-agent/agent-host` | Turns `MonoAgentConfig` into runtime, harness, and responder | Polling chats, serving APIs, adapter settings |
+| Configured responder | `@mono-agent/agent-app` | Turns `MonoAgentConfig` into runtime, memory, harness, and responder | Polling chats, serving APIs, adapter settings |
 
 Minimal local host:
 
 ```ts
 import { loadMonoAgentConfigWithSources } from "@mono-agent/config";
-import { createConfiguredAgentResponder } from "@mono-agent/agent-host";
+import { createConfiguredAgentResponder } from "@mono-agent/agent-app";
 
 const config = await loadMonoAgentConfigWithSources({
   env: process.env,
@@ -37,7 +37,7 @@ const config = await loadMonoAgentConfigWithSources({
   jsonPath: "./mono-agent.config.json",
 });
 
-const responder = createConfiguredAgentResponder({ config });
+const responder = await createConfiguredAgentResponder({ config });
 ```
 
 ## Context And Skill Join
@@ -46,18 +46,18 @@ Use this path when the agent needs identity, selected skills, history, and optio
 
 | Need | Package | Use |
 | --- | --- | --- |
-| Prompt assembly | `@mono-agent/context` | Load identity/SOUL/skills/history/memory into deterministic prompt context |
-| Selected skill bodies | `@mono-agent/skills` | Load only configured skills from `<skillsRoot>/<name>/SKILL.md` |
-| Memory substrate (schema, migrations, FTS+vector db, RRF) | `@mono-agent/memory-store` | SQLite storage, BM25 FTS, optional vector index, hybrid recall; `MemoryStore`/`MemoryBlock`/`MemoryWriteResult` contract |
-| Memory engine (all tiers: lite/journal/bujo) | `@mono-agent/memory-bujo` | `BujoMemoryStore` — tier-aware: FTS recall (lite), hybrid recall + decay (journal), LLM capture/reconcile + entity graph + reflection/migration + auto-scheduler (bujo) |
-| Embedding providers | `@mono-agent/memory-search` | Ollama/OpenAI embedding providers used by memory-store for vector recall |
+| Prompt assembly | `@mono-agent/agent-harness` | Load identity/SOUL/skills/history/memory into deterministic prompt context |
+| Selected skill bodies | `@mono-agent/agent-harness` | Load only configured skills from `<skillsRoot>/<name>/SKILL.md` |
+| Memory substrate (schema, migrations, FTS+vector db, RRF) | `@mono-agent/memory/store` | SQLite storage, BM25 FTS, optional vector index, hybrid recall; re-exports `MemoryStore`/`MemoryBlock`/`MemoryWriteResult` from `@mono-agent/agent-contracts` |
+| Memory engine (all tiers: lite/journal/bujo) | `@mono-agent/memory/bujo` | `BujoMemoryStore` — tier-aware: FTS recall (lite), hybrid recall + decay (journal), LLM capture/reconcile + entity graph + scheduled consolidation (bujo) |
+| Embedding providers | `@mono-agent/memory/search` | Ollama/OpenAI embedding providers used by the store subpath for vector recall |
 | Recall tool surface | `@mono-agent/agent-app` (bundled) | Auto-provisions a read-only `memory_recall` tool (hybrid keyword+semantic search) from `config.memory.recallTool.enabled`; spawns the bundled `mono-agent-memory` stdio child using the same memory root + embeddings as the in-app memory |
 
 Mono-agent selected skills are not auto-selected by description. The host chooses `context.selectedSkills`, and the harness loads those exact bodies.
 
 ## Execution Join
 
-Use `@mono-agent/agent-harness` directly when a host needs custom runtime, memory, history, recorder, or request-scoped runtime options. Use `@mono-agent/agent-host` when config-driven composition is enough.
+Use `@mono-agent/agent-harness` directly when a host needs custom prompt/runtime/memory/history/recorder wiring below the config layer. Use `@mono-agent/agent-app` when config-driven composition is enough.
 
 `@mono-agent/agent-harness` owns:
 
@@ -72,10 +72,10 @@ Use `@mono-agent/agent-harness` directly when a host needs custom runtime, memor
 
 ## Tools And MCP Join
 
-Use `@mono-agent/tool-policy` for fail-closed tool/MCP policy normalization:
+Use `@mono-agent/agent-harness` for fail-closed tool/MCP policy normalization:
 
 ```ts
-import { createToolPolicy, toolPolicyToRuntimeOptions } from "@mono-agent/tool-policy";
+import { createToolPolicy, toolPolicyToRuntimeOptions } from "@mono-agent/agent-harness";
 
 const policy = createToolPolicy({
   allowedTools: ["Read", "Grep"],
@@ -98,25 +98,23 @@ Communication adapters are edge packages. They accept an `AgentResponder` and ow
 | Slack | `@mono-agent/slack-adapter` | Allowed channel or DM gets a streamed reply |
 | WhatsApp | `@mono-agent/whatsapp-adapter` | Allowed sender/group trigger produces a reply |
 | OpenAI-compatible API | `@mono-agent/openai-api-adapter` | `curl /v1/models` and `/v1/chat/completions` |
+| Operator endpoints | `@mono-agent/operator-adapter` | `mono-agent tui` connects; `mono-agent web` observes live runs |
 | A2A provider/consumer | `@mono-agent/a2a-adapter` | Send text to the Agent Card URL |
 | Webhook | `@mono-agent/webhook-adapter` | `curl` the configured invocation path |
 | Cron | `@mono-agent/cron-adapter` | One scheduled or manually triggered invocation |
 
-Adapters must not import the harness, runtime adapter, memory packages (`memory-store`, `memory-bujo`, `memory-search`), or other adapters. `@mono-agent/agent-app` composes them from config; custom hosts and demos may compose them directly.
+Adapters must not import the harness, runtime adapter, memory package (`@mono-agent/memory` subpaths), or other adapters. `@mono-agent/agent-app` composes them from config; custom hosts and demos may compose them directly.
 
 ## Observability Join
 
 Use:
 
-- `@mono-agent/tui` for local terminal chat and redacted read-only config (`mono-agent-tui --config ./mono-agent.config.json`).
-- `@mono-agent/observability` for JSONL event artifacts, summaries, and trace-source registration; add `@mono-agent/observability-otel` for the Phoenix OTLP exporter configured via `observability.exporters`.
+- `@mono-agent/tui` for the pi-tui operator console (`mono-agent tui`): live chat with full stream-event insight, recorded-run replay, config view.
+- `@mono-agent/operator-adapter` for the loopback NDJSON stream endpoint the console connects to (`tui` config section, on by default) and the live SSE endpoint `mono-agent web` observes (`live` config section, on by default).
+- `@mono-agent/observability` for JSONL event artifacts, summaries, trace-source registration, and the `@mono-agent/observability/otel` Phoenix OTLP exporter configured via `observability.exporters`.
 
 Traceability is local-first. A running host registers a source manifest; `mono-agent status` reads the trace-source registry to report live sources, and artifacts are keyed by `(sourceId, runId)` so duplicate run ids do not collide. Phoenix is the recommended trace viewer when an `observability.exporters` (phoenix) entry is configured; local JSONL artifacts are the fallback otherwise.
 
-## Evaluation Join
-
-Use `@mono-agent/agent-evals` to define end-to-end scenarios against a responder or harness: final-text assertions, trajectory/tool-call matching, cost/turn/duration budgets, and custom judges, with local JSON/markdown artifacts. Live-provider scenarios are skipped unless `MONO_AGENT_EVAL_LIVE=1`.
-
 ## Multi-Agent Join
 
 Use `@mono-agent/agent-orchestrator` when one runtime should call named collaborator responders through a bounded MCP tool. Keep collaborator selection in the orchestrator layer, not inside A2A. A2A remains direct discovery and text/task communication.