@agentprojectcontext/apx 1.25.0 → 1.27.2

package/skills/apx-mcp/SKILL.md

@@ -0,0 +1,114 @@
+---
+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 (--scope optional; defaults to where the MCP lives)
+apx mcp remove filesystem --project iacrmar
+apx mcp remove github     --scope runtime --project iacrmar
+
+# Toggle (modifies whichever scope owns it)
+apx mcp enable  filesystem --project iacrmar
+apx mcp disable filesystem --project iacrmar
+
+# Call a tool through the daemon (useful for debugging)
+apx mcp tools <name>                            # list tools the server exposes
+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 tools <name>                         # forces the daemon to actually spawn the server
+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.
+
+## 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/skills/apx-mcp-builder/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: apx-mcp-builder
+scope: internal
+description: How to build a Model Context Protocol (MCP) server from scratch and wire it into APX. Load when the user asks "creame un MCP server", "necesito una herramienta para X", or you need to expose a new tool surface to agents. Covers the JSON-RPC stdio protocol, FastMCP Python / TypeScript SDK shapes, and APX-specific registration.
+---
+
+# apx-mcp-builder
+
+A **Model Context Protocol** server is a tiny process the agent talks to over stdio JSON-RPC. APX spawns it (via `apx mcp add`), discovers its tools (`tools/list`), and lets the super-agent call them by name. This skill is for **authoring a new MCP server**. To **add an existing one** to APX, load `apx-mcp` instead.
+
+## The minimum surface
+
+An MCP server must implement four RPC methods:
+
+| Method | Purpose | Returns |
+|---|---|---|
+| `initialize` | Handshake. APX sends protocol version + capabilities. | Server's capabilities. |
+| `tools/list` | Enumerate available tools. | `{ tools: [{name, description, inputSchema}] }` |
+| `tools/call` | Run one tool. APX sends `{ name, arguments }`. | `{ content: [...], isError? }` |
+| `notifications/initialized` | One-way; APX signals it's done initializing. | — |
+
+JSON-RPC 2.0 framing over stdio. Each message: `Content-Length: N\r\n\r\n<JSON>`. The `@modelcontextprotocol/sdk` (TS) and `fastmcp` / `mcp` (Python) packages handle framing for you.
+
+## Pick a stack
+
+| Stack | When |
+|---|---|
+| **Python + FastMCP** | Fastest path. Decorator-based. Great if your tools wrap pip libs. |
+| **Node + @modelcontextprotocol/sdk** | When the tool calls Node-only libs, or you want zero install (`npx -y`). |
+| Raw JSON-RPC | Only if you have an existing daemon you want to expose. Otherwise SDK. |
+
+## Python (FastMCP) — minimum viable server
+
+```python
+# my_server.py
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+@mcp.tool()
+def search_inventory(query: str, limit: int = 10) -> list[dict]:
+    """Search the inventory by free-text query. Returns matching SKUs."""
+    # ... your logic ...
+    return [{"sku": "abc", "title": "..."}]
+
+@mcp.tool()
+def get_stock(sku: str) -> dict:
+    """Return the current stock count for a SKU."""
+    return {"sku": sku, "stock": 42}
+
+if __name__ == "__main__":
+    mcp.run()  # stdio transport by default
+```
+
+Install:
+```bash
+pip install fastmcp
+# or via uv (recommended):
+uv tool install fastmcp
+```
+
+Register in APX:
+```bash
+apx mcp add my-server \
+  --command uv --project iacrmar \
+  -- run python /abs/path/my_server.py
+```
+
+## Node (TypeScript SDK) — minimum viable server
+
+```typescript
+// my-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const server = new Server(
+  { name: "my-server", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "search_inventory",
+      description: "Search the inventory by free-text query.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+          limit: { type: "number", default: 10 },
+        },
+        required: ["query"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  if (req.params.name === "search_inventory") {
+    const { query, limit = 10 } = req.params.arguments as any;
+    // ... your logic ...
+    return {
+      content: [{ type: "text", text: JSON.stringify([{ sku: "abc" }]) }],
+    };
+  }
+  throw new Error(`unknown tool: ${req.params.name}`);
+});
+
+await server.connect(new StdioServerTransport());
+```
+
+Register:
+```bash
+apx mcp add my-server \
+  --command npx --project iacrmar \
+  -- -y my-server-package
+```
+
+## Tool design rules
+
+1. **Names are snake_case**, verbs preferred: `search_inventory`, not `inventorySearch`.
+2. **inputSchema is JSON Schema draft-07**. Be strict: `required` matters. The agent reads the schema; vague schemas → bad calls.
+3. **Descriptions read like a CLI man-page**. Each tool's description and each param's description gets surfaced to the model. Make them count.
+4. **Return structured data**, not prose. MCP `content` can be text but the convention is to put JSON inside a text block so the agent can parse it back. For images, use the `image` content type.
+5. **Errors are errors, not silent empty**. `throw new Error(...)` propagates as `isError: true` and the agent will see it. Empty results = "found nothing"; that's a different signal.
+
+## Env vars and secrets
+
+Pass them at registration time via `--env`:
+
+```bash
+apx mcp add github \
+  --scope runtime --project iacrmar \
+  --command npx \
+  --env GITHUB_TOKEN=ghp_xxx \
+  --env GITHUB_OWNER=manuel \
+  -- -y @modelcontextprotocol/server-github
+```
+
+`--scope runtime` writes to `~/.apx/projects/<id>/mcps.json` (chmod 0600, never committed). NEVER use `--scope shared` for tokens — that file lives in `.apc/` and gets committed.
+
+## Anti-examples
+
+```python
+# DON'T expose every internal function as a tool.
+# A server with 40 tools is a context budget killer. Pick 5-10 high-value
+# tools per server; split into multiple servers if you have more.
+
+# DON'T return giant blobs in `content`. The agent has to read all of it
+# every turn. Paginate (`offset`, `limit`) and let the agent ask for more.
+
+# DON'T mix stdio + HTTP transports in the same process. Pick one. APX
+# spawns stdio servers; if you want HTTP, use `url:` in mcps.json instead
+# of `command:`.
+
+# DON'T print to stdout other than JSON-RPC frames. Any stray print()
+# corrupts the protocol — use stderr for logs. (FastMCP / the SDK handle
+# this for you, but `print("debug")` in a tool body breaks everything.)
+```
+
+## Common debugging path
+
+```bash
+# 1. Does the server start?
+apx mcp tools my-server                # forces a spawn + tools/list
+
+# 2. Are there spawn errors?
+apx log -f                              # tail the daemon log — stderr lands here
+
+# 3. Does a tool work in isolation?
+apx mcp run my-server search_inventory '{"query":"shoes"}'
+
+# 4. Are env vars set?
+apx mcp check --project iacrmar
+```
+
+## Don't
+
+- Don't reinvent the SDK framing. FastMCP / @modelcontextprotocol/sdk handle the stdio JSON-RPC dance — bypass only if you really need to.
+- Don't make tools that require interactive input. MCP is one-shot per call. If you need a flow, design separate tools for each step.
+- Don't ship a server without a README in the repo. Future-you will not remember which env vars matter.
+- Don't expect APX to retry MCP errors automatically. The agent sees the error and decides.

package/skills/apx-project/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: apx-project
+description: How to register, list, configure, and manage APX projects. Use BEFORE asking the user "which project?" — registered projects are listable; per-project config (model override, etc) is set with dotted-key PATCH.
+---
+
+# apx-project
+
+A project in APX is an APC-compliant folder on disk (`AGENTS.md` + `.apc/project.json`). Once registered, APX keeps runtime state (sessions, messages, routines, tasks, MCPs) under `~/.apx/projects/<apxId>/`.
+
+## The two kinds of projects
+
+- **`default`** (id=0): the super-agent's scratch workspace under `~/.apx/projects/default/`. Used when the user has no project named, has no project registered, or explicitly addresses "apx itself". Don't use it for real work — it's shared.
+- **registered** (id=1+): real projects, each rooted at a path the user owns.
+
+## Concrete CLI calls
+
+```bash
+# Register
+apx project add /path/to/repo          # registers; reads AGENTS.md + .apc/project.json
+apx project add .                       # current dir
+
+# Inspect
+apx project list                        # name, id, path, agents count
+apx project list -l                     # long form, includes storagePath
+
+# Remove / rebuild
+apx project remove <id|name|path>
+apx project rebuild <id|name|path>      # force re-scan of .apc/ on disk
+
+# Per-project config — dotted keys, lives in <repo>/.apc/config.json
+apx project config show <project>                                  # effective + project_only
+apx project config show <project> --key super_agent.model          # one key
+apx project config set <project> super_agent.model groq:llama-3.3-70b-versatile
+apx project config set <project> super_agent.permission_mode total
+apx project config set <project> telegram.route_to_agent reviewer
+apx project config unset <project> super_agent.model               # back to global
+apx project config edit <project>                                  # opens $EDITOR on project_only JSON
+```
+
+Every write to `project config` triggers `POST /admin/reload` so the daemon picks up the change without restart.
+
+## Resolution of `<project>` argument
+
+Accepted forms:
+- numeric id: `1`
+- exact name from `.apc/project.json`: `iacrmar`
+- absolute path: `/Volumes/SSDT7Shield/trabajos_proyectos/iacrmar`
+- relative path (from cwd) — resolved before matching.
+
+The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching. If you got "project not found", `apx project list` first.
+
+## What lives where
+
+```
+<repo>/                                         ← project root the user owns
+├── AGENTS.md                                   ← agent definitions (committed)
+└── .apc/
+    ├── project.json                            ← { apxId, name, ... }
+    ├── agents/<slug>.md
+    ├── agents/<slug>/memory.md
+    ├── skills/<slug>.md or <slug>/SKILL.md
+    ├── mcps.json                               ← shared MCPs (committed)
+    ├── commands/                               ← custom slash-commands
+    └── config.json                             ← project-only overrides (this is what `project config` edits)
+
+~/.apx/projects/<apxId>/                        ← runtime state (never committed)
+├── messages/YYYY-MM-DD.jsonl
+├── agents/<slug>/{sessions/, conversations/}
+├── routines.json
+├── tasks/YYYY-MM.jsonl
+├── artifacts/
+└── mcps.json                                   ← per-project runtime MCPs (local, may hold tokens)
+```
+
+## Anti-example
+
+```bash
+# DON'T hand-write AGENTS.md + .apc/project.json with shell tools.
+echo "Hello" > /path/repo/AGENTS.md
+mkdir -p /path/repo/.apc
+echo "{...}" > /path/repo/.apc/project.json
+```
+
+There's no scaffold validation, the project will appear registered but break on the first `apx project rebuild`. Use `apx init <path>` (project scaffold) and then `apx project add <path>`.
+
+```bash
+# DON'T set super_agent.model to a model that's not in the engine you have keys for.
+apx project config set iacrmar super_agent.model gemini:gemini-1.5-pro
+# ↑ Will fail at first call unless engines.gemini.api_key is set.
+```
+
+## When asked "what projects are there?"
+
+Don't ask. Call `list_projects` (tool) or `apx project list`. Same for "which agents does X have?" → `list_agents` / `apx agent list --project X`.
+
+## Don't
+
+- Don't operate on the default project (id=0) as if it were the user's main work. It's a scratch space for super-agent state.
+- Don't put secrets in `.apc/config.json` — it's committed. Put them in `~/.apx/config.json` (machine-local) under `engines.*` or `voice.tts.*`.
+- Don't move a project's `.apc/` folder without re-running `apx project rebuild` afterwards. The `apxId` will be stale.

package/skills/apx-routine/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: apx-routine
+description: How to create, edit, run, and debug APX routines. Use BEFORE writing any `apx routine add` command — schedule grammar, kind selection, pre/post commands, and the gotchas that produce double-replies.
+---
+
+# apx-routine
+
+A routine is a scheduled APX task. APX runs the scheduler tick every 5s and fires routines that are due. Each routine has a `kind`, a `schedule`, an optional `spec`, and optional `pre_commands` / `post_commands` shell hooks.
+
+## When to use which `kind`
+
+| Kind | Tools? | Description |
+|---|---|---|
+| `heartbeat` | no | Logs a marker message. Useful as a "still alive" ping. No LLM call. |
+| `shell` | no | Pure shell command. No LLM. Stdout captured. |
+| `exec_agent` | **no tools** | Loads a project agent's system prompt, sends `spec.prompt` to the engine, returns plain text. Single LLM call. |
+| `super_agent` | **all tools** | Runs the APX default agent (super-agent mode) with the full tool registry. Multi-iteration tool loop. |
+| `telegram` | n/a | Sends a hardcoded text via the Telegram plugin. |
+
+**Picking rule of thumb**:
+- Just need text from a model? → `exec_agent`.
+- Need orchestration (call MCPs, write files, call other agents, send messages with logic)? → `super_agent`.
+- Pure shell (curl + jq + write somewhere)? → `shell`.
+- Periodic Telegram poke with fixed text? → `telegram`.
+
+## Schedule grammar
+
+- `every:<N><unit>` — `every:30s`, `every:5m`, `every:24h`, `every:7d`. **Most common.**
+- `once:<iso-8601>` — `once:2026-12-01T08:00:00Z`. Fires once at that instant, then disabled.
+- Cron — `*/5 * * * *`, `0 8 * * *`. Standard 5-field. Use only if you really need cron expressions.
+
+## Anatomy of a routine
+
+```json
+{
+  "name": "weather-bariloche",
+  "kind": "exec_agent",
+  "schedule": "every:24h",
+  "spec": { "agent": "default", "prompt": "Escribí un saludo breve..." },
+  "pre_commands":  ["curl -s 'https://wttr.in/Bariloche?format=...'"],
+  "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""],
+  "enabled": true,
+  "skip_prompt_on": "signal"
+}
+```
+
+**The pipeline**:
+1. `pre_commands` run sequentially. Their combined stdout becomes `{{pre_output}}` substitutable in `spec.prompt`, and `$APX_PRE_OUTPUT` env var available to `post_commands`. Also written to `$APX_PRE_OUTPUT_FILE` for big payloads.
+2. The handler for `kind` runs. Its text result is exposed to post hooks as `$APX_LLM_OUTPUT`.
+3. `post_commands` run sequentially with that env.
+
+## Anti-example: the double-reply
+
+```json
+{
+  "kind": "super_agent",   ← DON'T
+  "spec": { "prompt": "El clima es {{pre_output}}. Mandalo por Telegram." },
+  "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
+}
+```
+
+This sends **two** Telegram messages: one from the super-agent's `send_telegram` tool call, one from `post_commands`. The runner now auto-suppresses `send_telegram` when `post_commands` contains `apx telegram send` (see spec/done/01), but the cleaner fix is to use `exec_agent`:
+
+```json
+{
+  "kind": "exec_agent",
+  "spec": { "agent": "default", "prompt": "El clima es {{pre_output}}. Una frase amigable, sin saludos." },
+  "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
+}
+```
+
+One message, the model writes prose, the shell pipes it to Telegram.
+
+## Concrete CLI calls
+
+```bash
+# List routines per project (always pin --project; never use default for real ones)
+apx routine list --project iacrmar
+
+# Inspect one
+apx routine get weather-bariloche --project iacrmar
+
+# Create — text-only exec_agent + shell delivery
+apx routine add weather-bariloche \
+  --project iacrmar \
+  --kind exec_agent \
+  --schedule "every:24h" \
+  --spec '{"agent":"default","prompt":"El clima es {{pre_output}}. Una frase amigable."}' \
+  --pre-commands "curl -s 'https://wttr.in/Bariloche?format=%t+%C+viento+%w'" \
+  --post-commands 'apx telegram send "$APX_LLM_OUTPUT"'
+
+# Create — super-agent with tools
+apx routine add daily-status \
+  --project iacrmar \
+  --kind super_agent \
+  --schedule "0 9 * * *" \
+  --spec '{"prompt":"Listame proyectos con tasks pendientes y mandame por Telegram un resumen corto."}' \
+  --permission-mode automatico
+
+# Toggle, run, remove
+apx routine enable  weather-bariloche --project iacrmar
+apx routine disable weather-bariloche --project iacrmar
+apx routine run     weather-bariloche --project iacrmar     # force-trigger now
+apx routine remove  weather-bariloche --project iacrmar
+```
+
+## `--project` is non-negotiable
+
+Routines live in `~/.apx/projects/<apxId>/routines.json`. Without `--project`, the default project (id=0, the super-agent's scratch workspace) gets the routine — that is **not** a user project. Always pass `--project <name|id|path>`.
+
+## `skip_prompt_on`
+
+Controls what happens when `pre_commands` exit non-zero:
+
+| Value | Behavior |
+|---|---|
+| `signal` (default) | Skip the LLM only on SIGINT/SIGTERM; non-zero exit still runs the LLM. |
+| `pre_failure` | Skip LLM + post on any non-zero exit. |
+| `pre_success` | Only run LLM if every pre command exits 0. Same as `pre_failure` for most cases. |
+| `always` | Skip LLM unconditionally — useful when you want pure pre→post pipelines. |
+| `never` | Always run, even if pre crashes. |
+
+## Debugging a routine
+
+```bash
+apx routine history weather-bariloche --project iacrmar    # last runs
+apx log -f                                                  # tail unified log
+apx messages tail --channel routine -n 20                   # routine-channel messages
+```
+
+A routine that "sends nothing" most often means: (a) `enabled: false`, (b) `next_run_at` is in the future, (c) the LLM returned empty text — visible in `apx messages` or in the `result.text` of `apx routine run`.
+
+## Don't
+
+- Don't use `super_agent` when `exec_agent` would do. The super-agent loops, calls tools, costs more.
+- Don't write `apx telegram send` inside a `super_agent` routine prompt — the agent will call `send_telegram` AND `post_commands` will fire. Pick one.
+- Don't hardcode model names in `spec` unless you have a reason — the routine inherits `super_agent.model` (with router fallback) by default.
+- Don't put credentials in routine `spec`. Put them in `~/.apx/config.json` engines and reference them by provider.

package/skills/apx-runtime/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: apx-runtime
+description: How to call external coding CLIs (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code) from APX. Load when the user wants to delegate a task to another AI tool — APX builds the system prompt, spawns the CLI, captures the result.
+---
+
+# apx-runtime
+
+A "runtime" in APX is an external AI coding CLI that APX can invoke headlessly. APX builds the agent's system prompt, spawns the CLI with the right flags, captures the stdout (and the external tool's session id when available), and stores the run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (runtime state — never committed). Some flows also link to the external engine's own transcript path.
+
+## Supported runtimes
+
+| id | binary | Headless flag |
+|---|---|---|
+| `claude-code`   | `claude`        | `-p "<prompt>" --append-system-prompt "<sys>" --output-format json` |
+| `codex`         | `codex`         | `exec "<prompt>"` (works outside git repos) |
+| `opencode`      | `opencode`      | non-interactive mode |
+| `aider`         | `aider`         | `--message "<prompt>" --no-stream` |
+| `cursor-agent`  | `cursor-agent`  | headless print mode |
+| `gemini-cli`    | `gemini`        | headless prompt mode |
+| `qwen-code`     | `qwen-code`     | passes system prompt separately |
+
+`apx env detect` reports which are installed and reachable.
+
+## Concrete CLI calls
+
+```bash
+# What's available on this machine
+apx env detect
+apx runtime list
+
+# Run an agent through an external CLI
+apx run reviewer --runtime claude-code "Review the diff in src/host/daemon/api/ for memory leaks"
+apx run scratch  --runtime codex       "Refactor parseAgentsMd to use a state machine"
+apx run scratch  --runtime opencode    "<prompt>"
+```
+
+Behavior:
+1. APX picks the project from `--project` or cwd.
+2. Reads the agent's `AGENT.md` + memory + skills, builds the system prompt with `buildAgentSystem({ invocation: "runtime", runtime: "<id>" })`.
+3. Spawns the CLI with the right flags. cwd = project path.
+4. Captures stdout. If the runtime printed `APC_RESULT: <value>`, that's the structured result; else the first 200 chars of stdout.
+5. Writes `~/.apx/projects/<apxId>/agents/<slug>/sessions/<YYYY-MM-DD>-<id>.md` with frontmatter linking back to the external tool's own session file (when available).
+
+## Resuming an external session
+
+After a `apx run`, the resulting APC session file references the external transcript:
+
+```yaml
+# ~/.apx/projects/<apxId>/agents/reviewer/sessions/2026-05-27-claude-code-abc123.md
+---
+external_session_path: /Users/.../.claude/projects/<...>/abc123.jsonl
+runtime: claude-code
+session_id: abc123
+---
+```
+
+All session resume / get / continue / summarise operations live in the
+**`apx-sessions`** skill. From here, the most common quick paths:
+
+```bash
+# Discover the id (or use the one printed by `apx run`)
+apx sessions list --engine claude --project iacrmar
+
+# Resume — apx auto-detects which engine owns the id
+apx session resume <id>
+apx session resume <id> --continue              # spawn the native CLI to keep going
+apx session resume <id> --summary               # super-agent summary of the transcript
+apx session resume <id> --into apx:<slug>       # seed a new APX session with the summary
+
+# Just read the transcript
+apx session get <id> --any --full               # or --engine claude --tail 16k
+```
+
+See the `apx-sessions` skill for the full flag reference, collision handling,
+and daemon-vs-no-daemon matrix.
+
+## APC_RESULT contract
+
+When you want APX to capture a structured value from the external runtime, instruct the runtime via the prompt to print on its last line:
+
+```
+APC_RESULT: <one-line value>
+```
+
+APX `extractApfResult()` parses that and stores it as the session's `result` field. Useful for return values from automation.
+
+## Anti-examples
+
+```bash
+# DON'T expect `apx run` to be interactive. It's headless.
+# For interactive, just invoke the CLI directly (e.g. `claude` for Claude Code).
+
+# DON'T pass huge prompts via the command line (shell args have limits).
+# For prompts > ~10KB, use a stdin-friendly route or write a temp file and reference it.
+
+# DON'T forget that each runtime has its own model selection.
+# APX passes the system prompt and the user prompt; it does NOT impose a model on
+# the external CLI. The user's external CLI config (e.g. Claude Code's CLAUDE.md
+# defaults) wins.
+```
+
+## When to use which
+
+| You want | Pick |
+|---|---|
+| Pair-program with file edits and shell | `claude-code` if the user has Claude Code, else `codex` |
+| Lightweight LLM run with no tools | `apx exec <agent> "<prompt>"` (no runtime needed) |
+| The super-agent to call other agents | `call_agent` tool (in-process, no spawn) |
+| Run something that needs persisted state across days | `apx run` with `claude-code` or `codex` (their sessions persist) |
+
+## Don't
+
+- Don't run untrusted prompts in `--runtime` of a CLI with broad tool permissions on the user's machine. The CLI may take file write or shell actions.
+- Don't expect APX to track tool calls inside the external CLI's transcript. APX captures stdout and the external session path — that's it. Inspect the external transcript directly for tool-level audit.
+- Don't pick a runtime the user doesn't have installed; `apx env detect` first if unsure.