@mono-agent/agent-app 0.6.2 → 0.9.0

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

@@ -33,7 +33,7 @@ Do **not** read or grep the `@mono-agent` TypeScript/package source — `package
 - 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.
-- Respect existing knowledge: if the folder has `AGENTS.md`, `CLAUDE.md`, `README.md`, or an existing `IDENTITY.md`, reference it from the identity instead of replacing it. Never overwrite existing files.
+- Respect existing knowledge: if the folder has `AGENTS.md`, `CLAUDE.md`, `README.md`, or `SOUL.md`, reference it from the identity instead of copying it. `IDENTITY.md` → `## Role` is the single canonical guided-init Role location. Never overwrite an existing identity; say explicitly that a newly entered Role was not written and tell the user to add or edit that heading manually.
 - Fail closed: no allowed tools, no memory writes, loopback-only network until the user opts in.
 - Do not fake runtime success, silently broaden tool access, or hide provider/MCP failures. Backup models are configured failover (`runtime.fallbackModels`), never silent substitution.
 - Secrets stay in env vars or the untracked config file; never commit tokens or `.env*` files.
@@ -46,7 +46,7 @@ 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 with Node 20+ and pnpm 10 or newer already installed:
+To run an unreleased build instead, use a clone of the mono-agent workspace with Node 22.19.0+ and pnpm 10 or newer already installed:
 
 ```bash
 git clone <mono-agent-repo> ~/mono-agent && cd ~/mono-agent
@@ -59,7 +59,7 @@ 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. Then run `mono-agent presets list` (and `mono-agent presets show <id>`) for a saved answer-set matching the user's intent; `references/playbooks.md` is the prose companion. If a preset fits, use it as the starting shape. The six presets are `starter`, `telegram-assistant`, `telegram-supermemory`, `slack-bot`, `local-private`, and `code-sandbox`; shapes with no preset (an OpenAI-API gateway, cron digest, A2A provider, Phoenix-observed, or a full multi-channel build) are hand-assembled from the capability modules and playbooks.
+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 presets list` (and `mono-agent presets show <id>`) for a saved answer-set matching the user's intent; `references/playbooks.md` is the prose companion. If a preset fits, use it as the starting shape. The five core presets are `starter`, `telegram-assistant`, `slack-bot`, `local-private`, and `code-sandbox`; optional plugins such as Supermemory ship their own setup skill. Shapes with no core preset (an OpenAI-API gateway, cron digest, A2A provider, Phoenix-observed, Supermemory, or a full multi-channel build) are hand-assembled from the capability modules and playbooks.
 2. **Scaffold.** In the user's folder, prefer the preset path when one fits — scaffold non-interactively with `--yes` (the composer is not the interactive `init` wizard):
 
    ```bash
@@ -67,8 +67,8 @@ Everything below runs in the user's agent folder, not the workspace.
    mono-agent init --model <ref> [--fallback-models <csv>] [--effort <level>] [--auth] [--memory lite|journal|bujo]   # bare scaffold
    ```
 
-   Either writes a `mono-agent.config.json` (with `tools.allowedTools` pre-filled from the selected capabilities' recommended tools), an `IDENTITY.md` that references any knowledge files already present, and `.mono-agent/` working directories (presets also emit a `.env.example` and any extra files). `--effort` writes `runtime.effort`; `--auth` opts in to provider setup before writing files; `--dry-run` previews without writing or launching auth/preflight commands. 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.
+   Either writes a `mono-agent.config.json` (with `tools.allowedTools` pre-filled from the selected capabilities' recommended tools), an `IDENTITY.md` whose `## Role` body is the one Role destination and which references any knowledge files already present, the managed project-local `mono-agent-configure` and `mono-agent-memory` skills, and `.mono-agent/` working directories (presets also emit a `.env.example` and any extra files). `--effort` writes `runtime.effort` on supporting providers (do not use it with direct `opencode:*` SDK 1.x); `--auth` opts in to provider setup before writing files; `--dry-run` previews without writing or launching auth/preflight commands. Existing scaffold/config files are never overwritten; reviewed secret setup is the deliberate exception that can transactionally replace `.env` and update `.gitignore`.
+3. **Configure.** Edit `mono-agent.config.json` to match the discovery answers. For a newly created identity, put the agreed text under `IDENTITY.md` → `## Role`; if it existed before init, preserve it and report that the new answer was not stored. Preserve the generated `mono-agent-configure` and `mono-agent-memory` selections when appending other skills, and do not auto-select this full authoring-oriented composer inside the generated agent. 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
@@ -82,7 +82,7 @@ Everything below runs in the user's agent folder, not the workspace.
    mono-agent start
    ```
 
-   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.
+   Then run the acceptance smoke test matching the chosen channel (see `references/validation.md`). To change anything, edit `mono-agent.config.json` or `IDENTITY.md` directly and run `mono-agent restart`; there is no live browser re-apply. On macOS, `mono-agent tui --configure` can open a temporary proposal-only configuration conversation against the already-running background agent. It is separate from ordinary chat, never accepts secrets, requires an out-of-band approval, and restarts or rolls back through the managed lifecycle. Off macOS, use manual edits plus `validate`, foreground `start`, and ordinary `tui`; conversational configuration is unavailable.
 
 ## When Config Is Not Enough
 

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

@@ -12,7 +12,7 @@ One `mono-agent.config.json` declares the whole agent. Paths are relative to the
 ```text
 my-agent/
   mono-agent.config.json   # the single declaration below
-  IDENTITY.md              # role, boundaries, references to existing knowledge
+  IDENTITY.md              # canonical ## Role body, 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
@@ -35,7 +35,7 @@ my-agent/
     "model": "claude:claude-sonnet-4-6",   // claude:* | codex:* | pi:<provider>:<model>
     "fallbackModels": ["pi:ollama:gemma4:31b"],
     "executionMode": "sdk",                // sdk | cli (default inferred from model)
-    "effort": "medium",                    // none|low|medium|high|xhigh|max
+    "effort": "medium",                    // none|low|medium|high|xhigh|max; omit for direct opencode:*
     "permissionMode": "default",           // default|plan|acceptEdits|bypassPermissions (CLI backends)
     "maxTurns": 0,                         // 0 or omitted means unlimited; 1-100 caps turns
     "workspace": ".",
@@ -85,10 +85,10 @@ my-agent/
     "writeMode": "capture",                // disabled | append-host-summary | capture (bujo only)
     "maxBytes": 64000,
     "embeddings": {                        // required for journal and bujo
-      "provider": "ollama",                // ollama | openai
+      "provider": "ollama",                // ollama | lmstudio | openai; exclusive, no fallback
       "model": "nomic-embed-text:v1.5",   // use exact :v1.5 tag (pull first with ollama pull)
-      "endpoint": "http://localhost:11434",
-      "apiKeyEnv": "OPENAI_API_KEY",       // or inline "apiKey"; required for openai
+      "endpoint": "http://localhost:11434", // service root; LM Studio default http://localhost:1234
+      // "apiKeyEnv": "LM_STUDIO_API_KEY", // optional authenticated LM Studio; required for openai
       "dim": 768                           // nomic-embed-text:v1.5 output dimension
     },
     "llm": {                               // enables bujo capture and the effective bujo tier; omit for lite/journal
@@ -110,7 +110,9 @@ my-agent/
     "mcpConfigPath": "./mcp.json"          // stdio/sse/http servers; inlined for SDK runtimes
   },
 
-  // Sandbox for runtime commands. Omit for no sandboxing.
+  // Sandbox for Pi-owned runtime commands. Direct Codex uses its own sandbox;
+  // Claude/direct OpenCode cannot enforce these exact srt scopes. All reject
+  // this block (pi:opencode-go:* remains a Pi route).
   "sandbox": {
     "mode": "native",                      // native (srt-wrapped) | off
     "network": { "mode": "none", "allowlist": [] }, // none|localhost|allowlist|all; *.suffix wildcards
@@ -187,8 +189,7 @@ my-agent/
     "port": 4040,
     "basePath": "/v1",                     // serves /v1/models + /v1/chat/completions (SSE)
     "allowNonLoopback": false,
-    "modelId": "my-agent",                 // model id advertised to API clients
-    "apiKey": "..."                        // optional bearer required from clients
+    "modelId": "my-agent"                  // model id advertised to API clients
   },
 
   // Telegram & Slack deliver only the FINAL answer by default (no streamed
@@ -291,9 +292,9 @@ mono-agent restart --force  # restart AND purge persisted pi sessions (fresh sta
 
 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 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 migrate` command remains Ollama-only; other maintenance commands use the configured embeddings provider. `agent-host` LLM capture is an in-app composition path that injects the `LlmComplete` implementation into the BuJo store.
 
-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).
+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); on macOS, `mono-agent tui --configure` opens a separate temporary proposal-only conversation against the managed background agent and must not be combined with `--local`. 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
 

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

@@ -10,15 +10,15 @@ Question:
 Which model should drive the agent, and should any backups take over when the provider fails?
 
 1. `claude:<model>` through SDK or CLI mode
-2. `pi:openai-codex:<model>` through SDK mode (preferred over direct Codex when Pi auth is configured)
-3. `codex:<model>` through CLI mode (direct Codex fallback path)
+2. `codex:<model>` through CLI mode (the default direct Codex path)
+3. `pi:openai-codex:<model>` through SDK mode (a selectable Pi alternative when Pi auth is configured)
 4. `pi:<provider>:<model>` through SDK mode (OpenAI, Copilot, OpenRouter, OpenCode-through-Pi, local Ollama, LM Studio, ...)
 5. A custom MonoRuntimeLike supplied programmatically (escape hatch)
 ```
 
-Fills: `runtime.model`, `runtime.fallbackModels` (ordered backup references tried on retryable provider failures), `runtime.executionMode` (usually inferred), `runtime.effort`, `runtime.maxTurns`.
+Fills: `runtime.model`, `runtime.fallbackModels` (ordered backup references tried on retryable provider failures), `runtime.executionMode` (usually inferred), `runtime.effort`, `runtime.maxTurns`. Keep a direct `codex:*` chain all-direct. Pi, Claude, and direct OpenCode may mix only with `sandbox` omitted/off; if native mono-agent sandboxing is selected, every primary/fallback/trigger model must stay on Pi (`pi:opencode-go:*` is Pi). Direct `opencode:*` is advanced scaffold/config-only, requires exact allow-all plus an explicit native `permissionMode`, and must omit `runtime.effort` under SDK 1.x.
 
-The interactive `mono-agent init` wizard discovers Pi OpenAI-Codex auth, OpenCode models, Ollama models, and LM Studio's local server best-effort. It ranks discovered `pi:openai-codex:gpt-5.5` above direct `codex:gpt-5.5`, maps discovered OpenCode options to `pi:opencode-go:<model>` for setup/preflight, and auto-adds local provider modules when a primary or fallback model uses `pi:ollama:*` or `pi:lmstudio:*`. Direct `opencode:<provider>:<model>` refs are supported only as hand-authored runtime backend config; do not present them as a first-class composer or init wizard selection. For local models also fill `providers.local` (e.g. an Ollama or LM Studio base URL plus model capabilities). Follow-up only if needed: continuous provider session per conversation (`runtime.session.mode: "continuous"`, default) versus stateless per-message.
+The interactive `mono-agent init` wizard discovers Pi OpenAI-Codex auth, OpenCode models, Ollama models, and LM Studio's local server best-effort. It defaults to direct `codex:gpt-5.6-terra` and presents both `pi:openai-codex:gpt-5.6-terra` and `pi:openai-codex:gpt-5.6-sol` as concrete selectable candidates. Direct `codex:gpt-5.6-sol` is also selectable; direct GPT-5.6 routes require Codex CLI 0.144.0 or newer. The wizard maps discovered OpenCode options to `pi:opencode-go:<model>` for setup/preflight, and auto-adds local provider modules when a primary or fallback model uses `pi:ollama:*` or `pi:lmstudio:*`. Recover missing Pi OAuth with `mono-agent auth login <provider>` (and `--pi-auth-path` when required). Direct `opencode:<provider>:<model>` refs are supported only as hand-authored runtime backend config; do not present them as a first-class composer or init wizard selection. For local models also fill `providers.local` (e.g. an Ollama or LM Studio base URL plus model capabilities). Follow-up only if needed: continuous provider session per conversation (`runtime.session.mode: "continuous"`, default) versus stateless per-message.
 
 ## 2. Channels Of Communication
 
@@ -43,10 +43,10 @@ Fills one config section per choice: built-in channels use `webhook`, `openaiApi
 Question:
 
 ```text
-What is this agent's role, and does this folder already contain knowledge it must respect?
+What exact text belongs in IDENTITY.md → ## Role, and does this folder already contain knowledge it must respect?
 ```
 
-Fills: `context.identityPath` (default `./IDENTITY.md`), optional `context.soulPath`, `runtime.workspace`. `mono-agent init` detects `AGENTS.md`, `CLAUDE.md`, `README.md`, and `SOUL.md` and references them from the generated identity — keep those references rather than copying content.
+Fills: the `## Role` body in the one canonical identity file, `context.identityPath` (default `./IDENTITY.md`), optional `context.soulPath`, and `runtime.workspace`. `mono-agent init` detects `AGENTS.md`, `CLAUDE.md`, `README.md`, and `SOUL.md` and references them from a generated identity — keep those references rather than copying content. If `IDENTITY.md` already exists, preserve it unchanged, say the newly entered Role was not written, and tell the user to add or edit its `## Role` heading manually. Do not assume the heading already exists or store the unused answer elsewhere.
 
 ## 4. Skills
 
@@ -113,11 +113,17 @@ No prerequisites. No Ollama. SQLite is bundled.
 
 **Tier 3 — journal (embeddings required):**
 
-- 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.
+- Guided init asks for Ollama or LM Studio, service root, exact model, actual dimension,
+  and optional auth-env name. Treat this as separate from runtime chat-model discovery.
+  - Ollama default root `http://localhost:11434`: enumerate `/api/tags`, retain only
+    `/api/show` capabilities containing `embedding`, then prove `/api/embed`.
+  - LM Studio default root `http://localhost:1234`: retain exact `type: "embedding"`
+    entries from `/api/v1/models`, use their `key`, then prove `/v1/embeddings`.
+  - Hand-authored OpenAI remains supported but is not a guided local-memory choice.
+- If typed discovery is inconclusive, ask for exact model + positive dimension, while
+  explaining that real readiness still must pass. Never substitute another provider.
+- LM Studio is keyless when `apiKeyEnv` is omitted. If named, the variable must already
+  contain the token in the owner-only agent environment; missing declared auth is `waiting`.
 
 Write:
 
@@ -129,13 +135,16 @@ Write:
   "embeddings": {
     "provider": "ollama",
     "model": "nomic-embed-text:v1.5",
+    "endpoint": "http://localhost:11434",
     "dim": 768
   }
 }
 ```
 
-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).
+After writing, remind the user to run `mono-agent validate` (checks root writability,
+managed provider/model/dimension identity, provider-native model typing, real finite-vector
+response, and dimension). Changing any semantic identity field on an existing root requires
+stopping the agent and running config-aware `mono-agent memory rebuild --json`.
 
 **Tier 4 — bujo (embeddings + chat model + consolidation):**
 
@@ -144,18 +153,24 @@ hybrid BM25+vector recall, entity graph, scheduled consolidation (decay + duplic
 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 embeddings provider/service-root/model/dimension/auth-env? Use the same
+  exclusive choices and real-probe contract 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
+  - agent-host: SDK runtime model reference such as `pi:openai-codex:gpt-5.6-terra` with
+    `executionMode: "sdk"`. Do not use CLI-backed refs such as `codex:gpt-5.6-terra`; 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?
 
+The embeddings service and capture LLM are independent. Choosing LM Studio embeddings does
+not move capture there; guided config keeps an explicit `agent-host` LLM, while an authored
+Ollama `memory.llm` remains valid. Standalone advanced `memory-bujo migrate` is still
+Ollama-only and outside guided init.
+
 Write (embeddings + chat model):
 
 ```jsonc
@@ -180,7 +195,7 @@ For an agent-host memory LLM, write the `llm` block as:
 ```jsonc
 "llm": {
   "provider": "agent-host",
-  "model": "pi:openai-codex:gpt-5.5",
+  "model": "pi:openai-codex:gpt-5.6-terra",
   "executionMode": "sdk"
 }
 ```
@@ -209,7 +224,7 @@ See `docs/memory/index.md` for the full tier table, config shapes, and CLI subco
 Question:
 
 ```text
-Should runtime commands run inside a sandbox?
+Should Pi-owned runtime commands run inside the native mono-agent sandbox? Direct Codex uses its own native sandbox and rejects this block; Claude and direct OpenCode reject it because their provider-owned tools cannot enforce the exact `srt` scopes.
 
 1. No sandbox for the first pass
 2. Native sandbox, no network (fail closed)

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

@@ -8,8 +8,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 | --- | --- | --- |
 | Model backends: claude (sdk/cli), codex (cli direct fallback), pi sdk providers (OpenAI, OpenAI-Codex preferred when Pi auth exists, Copilot, OpenRouter, OpenCode-through-Pi, Ollama, LM Studio, ...), plus hand-authored opencode runtime refs (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 + cli | `runtime.executionMode`, `runtime.effort` (`mono-agent init --effort <level>`), `runtime.maxTurns`, `runtime.workspace` |
-| Tool-permission posture for CLI backends | config | `runtime.permissionMode` |
+| Execution mode (sdk/cli), effort, max turns, workspace | config + cli | `runtime.executionMode`, `runtime.effort` (`mono-agent init --effort <level>`; unsupported for direct OpenCode SDK 1.x), `runtime.maxTurns`, `runtime.workspace` |
+| Tool-permission posture for CLI backends (direct OpenCode asks/rejects unanswered by default; configure explicitly) | config | `runtime.permissionMode` |
 | 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` |
@@ -23,19 +23,20 @@ Every framework capability and how a composed agent reaches it. This table is th
 
 | Capability | Coverage | Where |
 | --- | --- | --- |
-| Identity + optional soul documents | config | `context.identityPath`, `context.soulPath` |
+| Identity + optional soul documents; wizard Role has one explicit destination and created/preserved outcome | config + cli | `context.identityPath`, `context.soulPath`; guided Role is `IDENTITY.md` → `## Role`, and an existing identity is never overwritten |
 | Selected skills from a skills root | config | `context.skillsRoot`, `context.selectedSkills` |
+| Generated project configuration skills with progressive disclosure | config + cli | init selects `mono-agent-configure` + `mono-agent-memory` under `./skills` with `context.skillDisclosure: "index"`; drift: `mono-agent install-skill --project --check\|--update` |
 | 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 |
+| Conversation history (bounded in-memory) | auto | 12 messages by default; twice a positive `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 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` |
+| Journal memory (hybrid recall BM25+vector + salience decay; needs configured embeddings) | config | `memory.mode: "journal"`, `path`, `memory.embeddings.{provider,endpoint,model,dim,apiKeyEnv}` (`provider: "ollama" | "lmstudio" | "openai"`; exclusive, no cross-provider fallback) |
+| 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`; selected Ollama/LM Studio/OpenAI embeddings are independent from explicit `memory.llm` with `provider: "ollama"` (`model`, optional `endpoint`) or `provider: "agent-host"` (`model` is an SDK runtime model ref, 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` |
+| Memory out-of-band maintenance CLI (rebuild/recall/index/legacy reflect/migrate) | cli | `memory-bujo <subcommand> <root>`; opt-in `MONO_AGENT_MEMORY_EMBEDDINGS_PROVIDER` (`ollama`/`lmstudio`/`openai`), `_MODEL`, and `_DIM` for semantic recall; advanced `migrate` remains Ollama-only, outside guided init, and requires `MONO_AGENT_MEMORY_LLM_MODEL` (optional `_ENDPOINT`) |
+| Config-aware memory preview CLI (stats/today/show/search/top plus metadata-only audit; local search warns and falls back to FTS-only when embeddings are down) | cli | `mono-agent memory stats\|today\|show <date>\|search <query>\|top\|audit [--limit <n>] [--json]` |
+| Memory liveness check (managed tier/provider/model/dimension identity; provider-native typed discovery plus real finite-vector/dimension probe for Ollama or LM Studio; declared auth env; BuJo LLM config + consolidation cadence; no cross-provider fallback) | cli | `mono-agent validate` |
 | Host summaries appended after runs | config | `memory.writeMode: "append-host-summary"` |
-| Auto-provisioned read-only `MemoryRecall` 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) |
+| Auto-provisioned read-only `MemoryRecall` tool exposed for every configured memory tier; no chat LLM | config | `config.memory.recallTool.enabled` (`MONO_AGENT_MEMORY_RECALL_TOOL_ENABLED`, default on; explicit false opts out) |
 
 ## Tools, MCP, sandbox
 
@@ -45,7 +46,7 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Tool allow/deny lists (deny wins, even under allow-all; pi doesn't deny external MCP tools) | 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 | auto-available under allow-all once the channel is enabled; a **specific** `tools.allowedTools` must include `SlackSendMessage` / `TelegramSendMessage`; valid `slack.*` / `telegram.*` config and existing adapter allowlists provide credentials and destination bounds |
-| Sandbox on/off + srt engine | config | `sandbox.mode` |
+| Sandbox on/off + srt engine (Pi-owned tools; direct Codex has its own sandbox, Claude/direct OpenCode reject native mono policy) | 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` |
 | Fallback behavior when srt is unavailable | config | `sandbox.fallback`, `sandbox.unsafeAllowHostProcess` |
@@ -77,9 +78,10 @@ Every framework capability and how a composed agent reaches it. This table is th
 | 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) |
+| Managed proposal-only configuration conversation | cli + tool | macOS `mono-agent tui --configure` attaches to the authoritative background agent; `/configure`; separate configuration/ordinary conversation ids; host-gated `ProposeAgentConfiguration`; approval restarts and waits for readiness, failed start rolls files/agent back. `--local` is ordinary chat only; off macOS configuration is manual |
 | 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 |
 | Setup presets (saved answer-sets: generate config + `.env.example` + checklist) | cli | `mono-agent presets list\|show <id>`, `mono-agent init --preset <id> --yes` (`recipes`/`--recipe` deprecated aliases) |
-| Interactive setup wizard (preset/custom; walks model→channels→memory→tools→sandbox→observability) | cli | `mono-agent init` (no flags, on a TTY; `setup` alias) |
+| Interactive setup wizard (preset/custom; exact `IDENTITY.md` → `## Role` prompt/outcome; walks model→channels→memory→tools→sandbox→observability; Journal/BuJo explicitly choose Ollama or LM Studio service root/model/dimension/optional auth env using typed discovery and a real probe; macOS starts the background agent before temporary configuration) | cli | `mono-agent init` (no flags, on a TTY; `setup` alias); manual embedding entry still requires readiness probe; flags/non-TTY stay scaffold-only; unsupported platforms use manual configuration/foreground start/ordinary TUI |
 | Tools reporting + no-tools guardrail (allow-all → `All tools allowed`; explicit empty `allowedTools: []` → `waiting`; unknown-tool "did you mean"; send-tool/channel cross-checks) | cli | part of `mono-agent validate`/`doctor`; the wizard's tools step |
 | Resolved config view (every field tagged env/json/default) | cli | `mono-agent config` |
 | Scaffold / validate / start / install-skill | cli | `mono-agent init [--model <ref>] [--fallback-models <csv>] [--effort <level>] [--auth]\|validate [--consumer <path>]\|config\|presets\|start\|install-skill` |

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

@@ -50,8 +50,8 @@ Use this path when the agent needs identity, selected skills, history, and optio
 | 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 `MemoryRecall` 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 |
+| Embedding providers | `@mono-agent/memory/search` | Exclusive Ollama/LM Studio/OpenAI embedding providers used by the store subpath for vector recall; `agent-app` owns guided typed discovery and the real readiness probe |
+| Recall tool surface | `@mono-agent/agent-app` (bundled) | Auto-provisions read-only `MemoryRecall` for every configured tier and direct configured responder; automatic/tool recall share the same store and per-turn query cache |
 
 Mono-agent selected skills are not auto-selected by description. The host chooses `context.selectedSkills`, and the harness loads those exact bodies.
 

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

@@ -18,7 +18,7 @@ Flow, check whether one of these fits and adapt it. Verify every key against
 
 ```json
 {
-  "runtime": { "model": "claude:claude-sonnet-4-6" },
+  "runtime": { "model": "pi:openai-codex:gpt-5.6-terra" },
   "telegram": { "enabled": true, "botToken": "...", "allowedChatIds": ["123456789"] },
   "memory": {
     "mode": "bujo", "path": "./.mono-agent/memory", "writeMode": "capture",
@@ -38,7 +38,7 @@ Flow, check whether one of these fits and adapt it. Verify every key against
 
 ```json
 {
-  "runtime": { "model": "claude:claude-sonnet-4-6" },
+  "runtime": { "model": "pi:openai-codex:gpt-5.6-terra" },
   "slack": { "enabled": true, "botToken": "xoxb-...", "appToken": "xapp-...", "allowedChannelIds": ["C012345"], "botUserIds": ["U012345"], "mentionTextAliases": ["@agent"] },
   "tools": { "allowedTools": ["Read", "Grep", "SlackSendMessage", "deployTool"], "mcpConfigPath": "./mcp.json" },
   "concurrency": { "maxConcurrentRuns": 4, "maxPendingRuns": 8 }
@@ -71,10 +71,10 @@ Flow, check whether one of these fits and adapt it. Verify every key against
 ```json
 {
   "runtime": { "model": "claude:claude-sonnet-4-6", "session": { "mode": "continuous", "idleTimeoutMs": 1800000 } },
-  "openaiApi": { "enabled": true, "host": "0.0.0.0", "port": 4040, "basePath": "/v1", "allowNonLoopback": true, "modelId": "my-agent", "apiKey": "sk-secret" }
+  "openaiApi": { "enabled": true, "host": "0.0.0.0", "port": 4040, "basePath": "/v1", "allowNonLoopback": true, "modelId": "my-agent" }
 }
 ```
-**Steps:** `mono-agent init` → add `openaiApi` (set `allowNonLoopback`, `apiKey`, `modelId`) + continuous session → `validate` → `start` → in Open WebUI add an OpenAI connection at `http://host:4040/v1` with the bearer.
+**Steps:** `mono-agent init` → add `openaiApi` (set `allowNonLoopback`, `modelId`) + continuous session → put `MONO_AGENT_OPENAI_API_KEY` in an owner-only `.env` → `validate` → `start` → in Open WebUI add an OpenAI connection at `http://host:4040/v1` with the bearer.
 **Smoke:** `curl /v1/models` returns `my-agent`; two calls with the same `X-OpenWebUI-Chat-Id` resume the session and stream via SSE.
 
 ## 5. Webhook automation (sync + async)
@@ -164,13 +164,13 @@ const ext = createCollaboratorToolRuntimeExtension({
 
 ```json
 {
-  "runtime": { "model": "claude:claude-sonnet-4-6" },
+  "runtime": { "model": "pi:openai-codex:gpt-5.6-terra" },
   "tools": { "allowedTools": ["*"] },
   "sandbox": { "mode": "native", "network": { "mode": "localhost" }, "readableRoots": ["."], "writableRoots": ["."], "denyWrite": [".env", ".env.*", ".git/config", ".git/hooks/**"], "fallback": "fail-closed" }
 }
 ```
 **Steps:** `mono-agent init --memory journal` → leave tools at the allow-all default (`["*"]`); the **sandbox**, not an allowlist, is what constrains the code tools → `sandbox.mode native` + `network localhost` + deny-write defaults → keep `fallback: fail-closed` (do NOT set `unsafe-host-process`) → `validate` → `start`.
-**Smoke:** ask it to read a file + run Bash (works), then fetch an external URL or write `.env` (both blocked in the artifact). Note: provider CLI bridges run their own tool loops and may not be srt-wrapped — pair with provider sandboxing.
+**Smoke:** ask it to read a file + run Bash (works), then fetch an external URL or write `.env` (both blocked in the artifact). Keep every primary/fallback/trigger model on Pi; direct Codex, Claude, and direct OpenCode reject this mono-agent sandbox policy.
 
 ## 10. Phoenix-observed agent with the TUI
 **For:** an agent builder evaluating runs in a tracing dashboard.
@@ -212,6 +212,7 @@ const ext = createCollaboratorToolRuntimeExtension({
 }
 ```
 **Steps:** `ollama pull gemma4:31b` → `mono-agent init --model claude:claude-sonnet-4-6 --fallback-models pi:openai-codex:gpt-5.5,pi:ollama:gemma4:31b` → add `providers.local` + `piNative.piSessionsRoot` → `validate` → `start`.
+**Boundary:** this mixed Pi/Claude chain intentionally omits the native mono-agent sandbox. Keep direct Codex chains all-direct; keep every route on Pi (including `pi:opencode-go:*`, not direct `opencode:*`) when `sandbox.mode` is `native`.
 **Smoke:** force a retryable primary failure; confirm the run result reports failover to the next model (not silent) and the conversation resumes from the transcript tail.
 
 ## 13. Personal Telegram assistant with Supermemory
@@ -231,7 +232,7 @@ const ext = createCollaboratorToolRuntimeExtension({
   }
 }
 ```
-**Steps:** run `supermemory-server`, save its `sm_...` key in `.env`, `mono-agent init --preset telegram-supermemory --yes`, add Telegram token/chat id, `validate`, `start`.
+**Steps:** install the exact `@mono-agent/memory-supermemory` version matching agent-app, run `supermemory-server`, save its `sm_...` key in `.env`, add the explicit memory block plus Telegram token/chat id, `validate`, `start`.
 **Smoke:** send a fact, wait for ingestion, then ask a paraphrased question; confirm the run shows `MemoryRecall` returning Supermemory hits.
 
 ## 14. Fully local LM Studio agent

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

@@ -80,7 +80,7 @@ pnpm run test:demo
 
 | Surface | Smoke |
 | --- | --- |
-| TUI | Start the host and complete one local prompt. |
+| TUI | Start the host, connect with ordinary `mono-agent tui`, and complete one real prompt against the running responder. |
 | Telegram | Send one allowed chat message and verify the reply. |
 | Slack | Send one allowed DM or channel message and verify formatting. |
 | Adapter send tools | When `SlackSendMessage` / `TelegramSendMessage` are available (allow-all, or an explicit `tools.allowedTools` entry) with the channel enabled, call them from a non-Slack/Telegram surface such as TUI, cron, or OpenAI API to an allowed destination and verify delivery. |
@@ -90,8 +90,8 @@ pnpm run test:demo
 | Webhook | `curl` the invocation path and inspect the response body/status. |
 | Cron | Run a one-off scheduled invocation or wait for one tick. |
 | Observability | Confirm a run writes a redacted JSONL artifact; if an `observability.exporters` Phoenix entry is set, confirm the trace appears in Phoenix. |
-| Memory recall tool | With `memory.recallTool.enabled` (default on for journal/bujo with embeddings), ask the agent to recall an old note and confirm `MemoryRecall` appears in the run artifact and returns it. |
-| Semantic memory search | With `memory.embeddings` set (Ollama: `ollama pull nomic-embed-text:v1.5` first), ask a paraphrased question about an old note and confirm `MemoryRecall` (hybrid keyword + semantic) returns it. |
+| Memory recall tool | With any memory tier configured (`memory.recallTool.enabled` defaults on), ask the agent to recall an old note and confirm `MemoryRecall` appears separately from action-tool allowlists and returns it. |
+| Semantic memory search | With `memory.embeddings` set, first prove the configured provider only: Ollama model advertises `embedding` through `/api/show` and answers `/api/embed`, or LM Studio model has exact `type: "embedding"` in `/api/v1/models` and answers `/v1/embeddings`. Verify the finite vector dimension matches config, then ask a paraphrased question about an old note and confirm `MemoryRecall` returns it. Never accept a cross-provider fallback as proof. |
 
 ## Failure Handling