@agentprojectcontext/apx 1.33.0 → 1.34.0

package/src/{host/daemon/routines.js → core/routines/runner.js}

@@ -1,19 +1,17 @@
-// Routines: scheduled tasks per project. State persists in .apc/routines.json.
+// Routine execution — the domain logic any caller can invoke (daemon
+// scheduler, CLI `apx routine run`, HTTP `/projects/:pid/routines/:name/run`,
+// MCP server, future scripts). The runner orchestrates a 3-phase pipeline:
+//   1. pre_commands  (shell)
+//   2. handler       (heartbeat / exec_agent / super_agent / telegram / shell)
+//   3. post_commands (shell)
 //
-// Schedule formats:
-//   every:60s | every:5m | every:1h | once:<iso-8601>
-//
-// Kinds:
-//   heartbeat   — log a heartbeat message.   spec: { channel?, message? }
-//   exec_agent  — call an agent engine.       spec: { agent: slug, prompt }
-//   super_agent — call the APX super-agent.   spec: { prompt }
-//   telegram    — send a Telegram message.    spec: { channel?, chat_id?, text }
-//   shell       — run a shell command.        spec: { command, timeout_ms? }
-
+// `runRoutineNow(ctx, routine)` is the single entry point. Pass a ctx with at
+// least { project, projects, plugins, registries, globalConfig }. The runner
+// is process-state free — the daemon's RoutineScheduler is a separate file
+// (host/daemon/routines-scheduler.js) that just polls and calls this.
 import { spawn } from "node:child_process";
-import { execFile } from "node:child_process";
-import os from "node:os";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { callEngine } from "#core/engines/index.js";
 import { runSuperAgent } from "#core/agent/super-agent.js";
@@ -22,32 +20,18 @@ import { readAgents } from "#core/apc/parser.js";
 import { buildAgentSystem } from "#core/agent/build-agent-system.js";
 import { resolveAgentName, SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
 import { resolveArtifactRef, ARTIFACTS_SKIP_SIGNAL } from "#core/stores/artifacts.js";
-import { ensureRoutineMemory, readRoutineMemoryForPrompt, routineMemoryPath } from "#core/stores/routine-memory.js";
+import {
+  ensureRoutineMemory,
+  readRoutineMemoryForPrompt,
+  routineMemoryPath,
+} from "#core/stores/routine-memory.js";
 import { CHANNELS } from "#core/constants/channels.js";
 import {
-  listRoutines,
-  getRoutine,
-  upsertRoutine,
-  deleteRoutine,
-  setEnabled,
   updateRunState,
-  getDueRoutines,
   parseSchedule,
   computeNextRun,
 } from "#core/stores/routines.js";
-
-export {
-  listRoutines,
-  getRoutine,
-  upsertRoutine,
-  deleteRoutine,
-  setEnabled,
-  parseSchedule,
-  computeNextRun,
-};
-
-const TICK_MS = 5_000;
-const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+import { nowIso } from "#core/util/time.js";
 
 // --------------------- handlers ---------------------------------------------
 
@@ -211,7 +195,7 @@ const HANDLERS = {
 
 // --------------------- pipeline: pre/post shell commands --------------------
 
-// Run a single shell command. Returns { exitCode, stdout, stderr }.
+/** Run a single shell command. Returns { exitCode, stdout, stderr }. */
 function runShellCmd(cmd, env = {}, cwd = os.homedir()) {
   return new Promise((resolve) => {
     const child = spawn("sh", ["-c", cmd], {
@@ -228,13 +212,13 @@ function runShellCmd(cmd, env = {}, cwd = os.homedir()) {
   });
 }
 
-// Inject {{pre_output}} into a prompt string.
+/** Inject {{pre_output}} into a prompt string. */
 function injectPreOutput(prompt, preOutput) {
   if (!prompt || typeof prompt !== "string") return prompt;
   return prompt.replace(/\{\{pre_output\}\}/g, preOutput || "");
 }
 
-// Determine whether to skip the LLM call based on skip_prompt_on + pre results.
+/** Decide whether to skip the LLM call based on skip_prompt_on + pre results. */
 function shouldSkipPrompt(routine, preExitCode, preStdout) {
   const mode = routine.skip_prompt_on || "signal";
   if (mode === "always") return true;
@@ -245,10 +229,22 @@ function shouldSkipPrompt(routine, preExitCode, preStdout) {
   return false;
 }
 
-// --------------------- runtime: run one + loop ------------------------------
-
+// --------------------- runtime: run one routine -----------------------------
+
+/**
+ * Execute a single routine end-to-end (pre_commands → handler → post_commands)
+ * and persist last-run state. Pure with respect to process lifecycle — does NOT
+ * touch a timer, queue, or scheduler. Pure with respect to network — the
+ * super-agent / telegram handlers obviously go out, but the orchestration is
+ * sync from the caller's point of view via the returned promise.
+ *
+ * @param {object} ctx
+ *   - project: ProjectManager entry (logMessage, path, storagePath)
+ *   - projects, plugins, registries, globalConfig
+ * @param {object} routine The routine record from core/stores/routines.js
+ * @returns {object} { status, last_run_at, next_run_at, ...handler-result }
+ */
 export async function runRoutineNow(ctx, routine) {
-  // Determine the working directory for shell commands.
   const cwd = ctx.project?.path || os.homedir();
   const storagePath = ctx.project?.storagePath || os.homedir();
 
@@ -263,31 +259,26 @@ export async function runRoutineNow(ctx, routine) {
   if (hasPreCmds) {
     const combinedOut = [];
     for (const rawCmd of routine.pre_commands) {
-      // Resolve "artifact:<name>" shorthand to its absolute path.
       const cmd = resolveArtifactRef(rawCmd, storagePath);
       const { exitCode, stdout, stderr } = await runShellCmd(cmd, {}, cwd);
       combinedOut.push(stdout);
       if (stderr) combinedOut.push(stderr);
       preExitCode = exitCode;
       if (exitCode !== 0 && (routine.skip_prompt_on === "pre_failure" || routine.skip_prompt_on === "signal")) {
-        // Stop running further pre_commands on failure when mode cares about exit code.
         break;
       }
     }
     preStdout = combinedOut.join("");
 
-    // Write pre output to a temp file so post_commands can reference it via
-    // $APX_PRE_OUTPUT_FILE even if the output is large.
     try {
       preOutputFile = path.join(os.tmpdir(), `apx-pre-${routine.name}-${Date.now()}.txt`);
       fs.writeFileSync(preOutputFile, preStdout);
     } catch { preOutputFile = null; }
   }
 
-  // Env vars injected into post_commands and available in shell pre_commands output.
   const pipelineEnv = {
     APX_PRE_EXIT: String(preExitCode),
-    APX_PRE_OUTPUT: preStdout.slice(0, 32_000), // guard against huge outputs
+    APX_PRE_OUTPUT: preStdout.slice(0, 32_000),
     APX_PRE_OUTPUT_FILE: preOutputFile || "",
     APX_ROUTINE: routine.name,
   };
@@ -300,7 +291,6 @@ export async function runRoutineNow(ctx, routine) {
   let errMsg = null;
 
   if (!skip) {
-    // Inject {{pre_output}} into exec_agent and super_agent prompts.
     const enrichedRoutine = (hasPreCmds && preStdout)
       ? {
           ...routine,
@@ -344,11 +334,9 @@ export async function runRoutineNow(ctx, routine) {
     for (const rawCmd of routine.post_commands) {
       const cmd = resolveArtifactRef(rawCmd, storagePath);
       await runShellCmd(cmd, postEnv, cwd);
-      // Post-command failures are logged but don't change routine status.
     }
   }
 
-  // Cleanup temp file.
   if (preOutputFile) try { fs.unlinkSync(preOutputFile); } catch {}
 
   const lastRun = nowIso();
@@ -374,58 +362,3 @@ export async function runRoutineNow(ctx, routine) {
   });
   return { ...result, last_run_at: lastRun, next_run_at: next };
 }
-
-export class RoutineScheduler {
-  constructor({ projects, plugins, registries, globalConfig, log }) {
-    this.projects = projects;
-    this.plugins = plugins;
-    this.registries = registries;
-    this.globalConfig = globalConfig;
-    this.log = log || (() => {});
-    this._timer = null;
-    this._running = false;
-  }
-
-  start() {
-    if (this._timer) return;
-    this._timer = setInterval(
-      () => this._tick().catch((e) => this.log(`routines tick error: ${e.message}`)),
-      TICK_MS
-    );
-    this._timer.unref?.();
-  }
-
-  stop() {
-    if (this._timer) {
-      clearInterval(this._timer);
-      this._timer = null;
-    }
-  }
-
-  async _tick() {
-    if (this._running) return;
-    this._running = true;
-    try {
-      const nowStr = nowIso();
-      for (const proj of this.projects.list().map((p) => this.projects.get(p.id))) {
-        if (!proj) continue;
-        const due = getDueRoutines(proj.storagePath, nowStr);
-        for (const r of due) {
-          this.log(`routine ${r.name} (${r.kind}) firing in project #${proj.id}`);
-          await runRoutineNow(
-            {
-              project: proj,
-              projects: this.projects,
-              plugins: this.plugins,
-              registries: this.registries,
-              globalConfig: this.globalConfig,
-            },
-            r
-          );
-        }
-      }
-    } finally {
-      this._running = false;
-    }
-  }
-}

package/src/core/runtime-skills/apc-context/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: apc-context
+description: "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. Do not wait to be asked. Read .apc/ before making any assumption about agents, memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents', any question about agents or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the conversation with a migration offer before answering anything else. If the user declines, delete .apc/migrate.md immediately so it is not shown again."
+homepage: https://github.com/agentprojectcontext/agentprojectcontext
+---
+
+# Agent Project Context
+
+This project uses APC. APC stores portable project context in `.apc/` and `AGENTS.md`.
+
+APC does not store raw runtime sessions. Sessions, conversations, messages, caches, provider
+threads, and private runtime memory stay in the IDE, CLI, daemon, or user-level store that created
+them.
+
+## FIRST: check for pending migration
+
+Before doing anything else, check if `.apc/migrate.md` exists:
+
+```bash
+cat .apc/migrate.md 2>/dev/null
+```
+
+If it exists, open with this offer before answering anything else:
+
+> I see this project was initialized with Agent Project Context (APC).
+>
+> I found context files that may need migration:
+> [list files from .apc/migrate.md]
+>
+> I can read them, separate durable project context from runtime/private state, and migrate only
+> what belongs in APC.
+>
+> Want me to start?
+
+If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.
+
+## Migration rule: think, do not copy
+
+Read detected files first. Also read `AGENTS.md` if it exists.
+
+Classify content:
+
+| Content | Action |
+|---|---|
+| Agent definitions: name, model, description | Put in `.apc/agents/<name>.md` and/or `AGENTS.md` |
+| Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
+| Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
+| Durable safe facts useful to all contributors | Add to `.apc/agents/<name>/memory.md` only after curation |
+| MCP expectations without secrets | Add to `.apc/mcps.json` |
+| Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
+| Secrets, tokens, credentials, private headers | Do not store in repository |
+| IDE UI settings or personal aliases | Leave in IDE/user config |
+| Instructions to store sessions under `.apc/` | Drop as obsolete |
+
+After migration:
+
+1. Update `AGENTS.md` as the root project contract.
+2. Create or update `.apc/agents/`, `.apc/skills/`, `.apc/mcps.json` as needed.
+3. Do not create `.apc/**/sessions`, `.apc/messages`, or `.apc/conversations`.
+4. Delete obsolete source files only when their useful project context was migrated or intentionally dropped.
+5. Delete `.apc/migrate.md`.
+6. Summarize what moved, what stayed local, and what was dropped.
+
+## APC structure
+
+```text
+AGENTS.md                        ← root project contract
+.apc/
+  project.json                   ← project metadata
+  .gitignore                     ← safety guard
+  agents/<name>.md               ← agent definition
+  agents/<name>/memory.md        ← optional curated project memory
+  skills/<name>.md               ← reusable project instructions
+  mcps.json                      ← MCP hints without secrets
+```
+
+Do not store:
+
+```text
+.apc/agents/<name>/sessions/
+.apc/sessions/
+.apc/conversations/
+.apc/messages/
+.apc/cache/
+.apc/tmp/
+.apc/private/
+.apc/secrets/
+```
+
+## Visibility rules
+
+| Data | Visibility | Commit? |
+|---|---|---|
+| Agent definitions, skills, project rules | `stable` / `project` | Yes |
+| Curated safe `memory.md` | `project` | Yes, if team-safe |
+| MCP hints without secrets | `project` | Yes |
+| Sessions, conversations, messages | `local` | No; runtime-owned |
+| Secrets, tokens, `*.secret.json`, `*.env` | `private` | Never |
+| Caches, temp files, databases | `ephemeral` | No |
+
+## Operating rules
+
+1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
+2. Read agent definitions from `.apc/agents/<name>.md` when present.
+3. Read curated project memory from `.apc/agents/<name>/memory.md` when present.
+4. Write only durable, safe, curated facts to APC memory.
+5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
+6. Keep secrets out of APC and out of git.
+7. Treat `.apc/mcps.json` as MCP configuration hints, not as an MCP implementation.
+
+## Normalization
+
+If agent formats are broken or use legacy fields (role, skills in YAML), offer to normalize:
+
+```yaml
+---
+name: agent-name
+model: inherit
+description: Semantic activation trigger
+---
+```
+
+Identify and fix inconsistencies in `model` (use technical IDs or `inherit`) and ensure `description` is present for semantic activation.
+
+## Sessions
+
+Sessions belong to the runtime that created them.
+
+Examples:
+
+```text
+Codex runtime storage
+Claude Code runtime storage
+OpenCode runtime storage
+~/.apx/projects/<project-id>/agents/<name>/sessions/
+```
+
+At task end, provide the user a concise result. If project memory should be updated, write a short
+sanitized fact to `.apc/agents/<name>/memory.md` only when useful and safe.
+
+## APX
+
+Read `.apc/project.json` if present. It may contain an `apx` field:
+
+- `"installed"`: APX is available; use `apx` commands when useful.
+- `"declined"`: user chose not to install; do not suggest or run APX.
+- missing or `null`: unknown; do not assume APX is available.
+
+If APX is installed, it may manage runtime state outside the repository:
+
+```text
+~/.apx/projects/<project-id>/
+```
+
+APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
+across Codex, Claude Code, OpenCode, Aider, or direct LLM engines. Those are APX runtime features,
+not APC portable-core requirements.
+
+Never use APX to write secrets or raw sessions into `.apc/`.

package/src/core/runtime-skills/apx/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: apx
+description: "APX CLI umbrella — which sub-skill handles each operation (sessions, MCPs, routines, tasks, telegram, projects, agents, runtimes). Activate when the user mentions `apx`, the APX daemon, or wants to coordinate/run/delegate agents. Not for `.apc/` alone (use apc-context). Triggers: 'apx', 'apx run', 'apx daemon', 'coordinate agents', 'apx help'."
+homepage: https://github.com/agentprojectcontext/apx
+---
+
+# APX — Agent Project Context Runtime
+
+APX is a daemon (`127.0.0.1:7430`, auto-starts on first call) that turns external coding CLIs (Claude Code, Codex, OpenCode, Aider, …) and configurable agents into a unified orchestration surface.
+
+It reads APC project context from `.apc/` (committed) but keeps runtime state outside the repo under `~/.apx/projects/<project-id>/`. The super-agent has a default workspace at `~/.apx/projects/default` for system-level work.
+
+---
+
+## When to use APX (vs. spawning a subagent natively)
+
+If you can spawn a subagent natively in the IDE you're in (Claude Code, Cursor, …) — **do that**. No APX needed.
+
+Use APX when:
+- The user explicitly asks for a specific external runtime ("run this in Codex", "delegate to OpenCode").
+- You need to run an agent in a runtime different from the one you're in.
+- You're orchestrating from outside any IDE (a script, Telegram bot, CI, routine).
+
+---
+
+## Sub-skill index — open the one that matches the task
+
+| Topic | Sub-skill | When |
+|-------|-----------|------|
+| Delegate to an external coding CLI | **apx-runtime** | `apx run <agent> --runtime claude-code\|codex\|...` |
+| List / read / resume / summarise / continue sessions across engines | **apx-sessions** | `apx session resume`, `apx sessions list`, "import a codex session" |
+| Use a registered MCP tool | **apx-mcp** | `apx mcp run`, "call MCP filesystem", "the MCP is failing" |
+| Add / configure / use a project agent | **apx-agent** | "add an agent", "import from vault", per-agent model, agent memory |
+| Register / list / configure a project | **apx-project** | "register this project", `apx project list`, per-project config |
+| Per-project TODO list | **apx-task** | "add a task", "remind me to…", "what's pending" |
+| Scheduled / recurring agents | **apx-routine** | `apx routine add`, every-5m, cron-like jobs |
+| Telegram I/O | **apx-telegram** | configure bot, channels, send a message |
+| Voice channel (TTS, speech) — *optional* | **apx-voice** | only if voice is being set up |
+| Build a new MCP server — *internal/dev* | **apx-mcp-builder** | when developing a brand-new MCP from scratch |
+| Author a new APX skill — *internal/dev* | **apx-skill-builder** | when adding to APX itself |
+
+> Sub-skills marked *internal/dev* are not pushed to IDE skill dirs by default. They live in the APX repo and are loaded by APX itself; install one to your IDE with `apx skills add <slug> --global` if you want it there.
+
+---
+
+## Generic patterns (apply to every sub-skill)
+
+### Verify commands before recommending them
+
+Do not invent APX subcommands. Confirm exact CLI form with `apx --help` or `apx <command> --help` before telling another runtime to invoke APX. Avoid guessed aliases (e.g. `apx send-telegram` is *not* a thing — see apx-telegram).
+
+### `APC_RESULT` contract — structured return values
+
+When you want APX to capture a structured value from an agent (any runtime), instruct the agent to print on its last meaningful line:
+
+```
+APC_RESULT: <one-line value>
+```
+
+APX's `extractApfResult()` parses that and stores it as the session's `result` field. Useful for automation, routines, and CI.
+
+### Tool permissions
+
+```bash
+apx permission show
+apx permission set automatico   # total | automatico | permiso
+```
+
+`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP, runtime, outbound, config, or filesystem mutation actions.
+
+### Memory
+
+Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
+
+```bash
+apx memory <slug>                       # read agent's memory.md
+apx memory <slug> --append "<fact>"     # append a durable note
+apx memory <slug> --replace < file.md  # replace entire memory from stdin
+```
+
+### Observe activity
+
+```bash
+apx messages tail                               # last 50 messages, all channels
+apx messages chat --channel telegram -n 20      # readable chat view
+apx messages tail --channel runtime --agent <slug> -n 20
+```
+
+---
+
+## Anti-patterns
+
+- Don't activate APX-sessions inside a request that's purely about `apx run` orchestration — use apx-runtime.
+- Don't activate apx-mcp-builder unless the user is actually authoring a new MCP server (it's a deep developer guide, not a usage guide).
+- Don't push state to `.apc/` that belongs in `~/.apx/projects/<id>/` (sessions, conversations, runtime logs).

package/src/core/runtime-skills/apx-mcp/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: apx-mcp
+description: How to register, list, debug, and scope MCP servers in APX. Use BEFORE adding any MCP — three scopes (shared/runtime/global) with different commit and secrecy semantics.
+---
+
+# apx-mcp
+
+APX exposes Model Context Protocol (MCP) servers to agents. Three scopes, each in a different file with different rules:
+
+| Scope | File | Committed? | Secrets OK? | When |
+|---|---|---|---|---|
+| `shared` | `<repo>/.apc/mcps.json` | yes | **no** | Team-wide MCPs (filesystem, brave, github public) |
+| `runtime` | `~/.apx/projects/<apxId>/mcps.json` (chmod 0600) | no | yes | Per-project local — tokens, machine-specific endpoints |
+| `global` | `~/.apx/mcps.json` | n/a | yes | Machine-wide — not tied to any project |
+
+Resolution priority when a name appears in more than one: **runtime > shared > global**. Conflicts surface in `apx mcp check`.
+
+## Concrete CLI calls
+
+```bash
+# List (all scopes, this is the default)
+apx mcp list --project iacrmar
+apx mcp list --scope runtime --project iacrmar
+apx mcp list --scope shared  --project iacrmar
+apx mcp list --scope global
+
+# Inspect sources and conflicts
+apx mcp check --project iacrmar
+
+# Add — shared (commit to repo)
+apx mcp add filesystem --command npx --project iacrmar \
+  -- -y @modelcontextprotocol/server-filesystem .
+
+# Add — runtime (per-project, local, secrets safe)
+apx mcp add github --scope runtime --project iacrmar \
+  --command npx --env GITHUB_TOKEN=ghp_xxx \
+  -- -y @modelcontextprotocol/server-github
+
+# Add — global (machine-wide, not tied to a project)
+apx mcp add brave --scope global \
+  --command npx --env BRAVE_API_KEY=BSAxxx \
+  -- -y @modelcontextprotocol/server-brave-search
+
+# Remove (pass --scope when the MCP isn't in the default scope:
+# shared inside an APC project, else global)
+apx mcp remove filesystem --project iacrmar
+apx mcp remove github     --scope runtime --project iacrmar
+
+# Toggle (defaults to the scope that owns the MCP)
+apx mcp enable  filesystem --project iacrmar
+apx mcp disable filesystem --project iacrmar
+
+# Call a tool through the daemon (useful for debugging)
+apx mcp run filesystem read_file '{"path":"README.md"}'
+```
+
+## When the user asks for a new MCP
+
+Decision tree:
+1. **Has secrets / tokens?** → `runtime` scope. Always.
+2. **Is part of the project's shared dev environment?** → `shared` (committed).
+3. **Used across all your projects?** → `global`.
+
+Default if none is obvious: `shared` when inside an APC project, `global` outside.
+
+## Common command shapes by transport
+
+```bash
+# stdio MCP (most common — npx, uvx, node, python)
+apx mcp add <name> --command npx -- -y <package-or-flag-list>
+apx mcp add <name> --command uvx -- <python-cli-name>
+apx mcp add <name> --command python -- /abs/path/to/server.py
+
+# Env vars (one --env per var)
+apx mcp add <name> --command npx \
+  --env GITHUB_TOKEN=ghp_xxx \
+  --env GITHUB_OWNER=manuel \
+  -- -y @modelcontextprotocol/server-github
+```
+
+Anything after `--` is forwarded verbatim as args to the command. Quote carefully.
+
+## Anti-examples
+
+```bash
+# DON'T put tokens in shared scope. It commits.
+apx mcp add github --scope shared --env GITHUB_TOKEN=ghp_xxx ...
+# ↑ Token ends up in .apc/mcps.json in your repo. Use --scope runtime.
+
+# DON'T remove an MCP from the wrong scope.
+apx mcp remove github          # if github lives in runtime, this errors with a hint
+# ↑ Daemon returns 409 with the right scope to use.
+
+# DON'T expect IDE-foreign configs (~/.cursor/mcps.json, ~/.claude/mcps.json) to be
+# removable via apx mcp remove. APX reads them as advisory (source=cursor/claude/etc)
+# but won't write them. Edit the IDE config directly.
+```
+
+## Debugging connection issues
+
+```bash
+apx mcp check --project iacrmar             # what scopes APX sees + which files exist
+apx mcp run <name> <tool> '{...}'            # spawn the server and call a tool for real
+apx log -f                                   # tail unified log for spawn errors
+```
+
+A server that "doesn't show tools" usually means: the command failed to start (env vars missing, package not found), or the server crashed during initialize. The unified log has the stderr buffer.
+
+> `apx mcp tools <name>` is a placeholder stub (prints a "coming in v0.2" notice, lists nothing). To verify a server actually spawns, call a tool with `apx mcp run`.
+
+## Don't
+
+- Don't mix scopes for the same MCP name unless you actually want shadowing. The result is "the one with highest priority wins, others stay invisible."
+- Don't edit `~/.apx/projects/<id>/mcps.json` by hand; use `apx mcp add --scope runtime`. The file is chmod 0600 — the CLI keeps it that way.
+- Don't add tokens via `--env KEY=` inline if your shell history is public. Set them in your shell first, then `--env KEY=$KEY`.
+- Don't forget to `apx daemon reload` after editing config — actually `apx mcp` does this for you, but if you hand-edited the JSON, it's manual.

package/src/core/runtime-skills/{claude-code.md → claude-code/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: claude-code
 description: "Activate ONLY when the user explicitly mentions Claude Code, Claude CLI, claude command, Anthropic Claude Code, installing Claude Code, using Claude Code, or APX runtime claude-code. Do not activate for generic Claude model discussion."
 homepage: https://docs.anthropic.com/en/docs/claude-code

package/src/core/runtime-skills/{codex-cli.md → codex-cli/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: codex-cli
 description: "Activate ONLY when the user explicitly mentions Codex CLI, OpenAI Codex, @openai/codex, codex command, codex exec, installing Codex, using Codex, ~/.codex, or APX runtime codex."
 homepage: https://developers.openai.com/codex

package/src/core/runtime-skills/{opencode-cli.md → opencode-cli/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: opencode-cli
 description: "Activate ONLY when the user explicitly mentions OpenCode, opencode command, installing OpenCode, using OpenCode, OpenCode provider setup, or APX runtime opencode."
 homepage: https://opencode.ai/docs

package/src/core/runtime-skills/{openrouter.md → openrouter/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+scope: internal
 name: openrouter
 description: "Activate ONLY when the user explicitly mentions OpenRouter, OPENROUTER_API_KEY, OpenRouter models, installing OpenRouter provider config, or using OpenRouter with APX, OpenCode, LiteLLM, or an OpenAI-compatible client."
 homepage: https://openrouter.ai/docs

package/src/{host/daemon/env-detect.js → core/runtimes/detect.js}

@@ -1,7 +1,7 @@
 // Best-effort detection of installed agent CLIs and LLM runners.
 // We just probe the binary with `--version` (or equivalent) and don't fail if
 // it isn't there — caller decides what to do with absence.
-import { runProcess } from "./runtimes/_spawn.js";
+import { runProcess } from "#host/daemon/runtimes/_spawn.js";
 
 const PROBES = [
   // Coding-agent CLIs (runtimes/)