@agentprojectcontext/apx 1.34.0 → 1.35.0

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

@@ -1,24 +1,22 @@
 ---
 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.
+description: Register, list, debug, scope MCP servers in APX. Load BEFORE adding any MCP — three scopes (shared/runtime/global) with different commit and secrecy semantics. Triggers: 'add MCP', 'apx mcp', 'MCP scope', 'MCP failing', 'list MCPs'.
 ---
 
 # apx-mcp
 
-APX exposes Model Context Protocol (MCP) servers to agents. Three scopes, each in a different file with different rules:
+APX exposes MCP servers via three scopes; resolution priority **runtime > shared > global**, conflicts via `apx mcp check`:
 
 | 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`.
+| `shared` | `<repo>/.apc/mcps.json` | yes | **no** | Team-wide (filesystem, brave, github public) |
+| `runtime` | `~/.apx/projects/<apxId>/mcps.json` (chmod 0600) | no | yes | Per-project — tokens, machine-specific endpoints |
+| `global` | `~/.apx/mcps.json` | n/a | yes | Machine-wide, not tied to a project |
 
 ## Concrete CLI calls
 
 ```bash
-# List (all scopes, this is the default)
+# List (defaults to all scopes)
 apx mcp list --project iacrmar
 apx mcp list --scope runtime --project iacrmar
 apx mcp list --scope shared  --project iacrmar
@@ -36,34 +34,32 @@ 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)
+# Add — global (machine-wide)
 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)
+# Remove (pass --scope when not in default: shared inside 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)
+# Toggle (defaults to owning scope)
 apx mcp enable  filesystem --project iacrmar
 apx mcp disable filesystem --project iacrmar
 
-# Call a tool through the daemon (useful for debugging)
+# Call a tool through the daemon (debugging)
 apx mcp run filesystem read_file '{"path":"README.md"}'
 ```
 
-## When the user asks for a new MCP
+## Scope decision tree
 
-Decision tree:
-1. **Has secrets / tokens?** → `runtime` scope. Always.
-2. **Is part of the project's shared dev environment?** → `shared` (committed).
+1. **Has secrets/tokens?** → `runtime`. Always.
+2. **Part of 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.
+Default if unclear: `shared` inside an APC project, `global` outside.
 
-## Common command shapes by transport
+## Command shapes by transport
 
 ```bash
 # stdio MCP (most common — npx, uvx, node, python)
@@ -78,39 +74,38 @@ apx mcp add <name> --command npx \
   -- -y @modelcontextprotocol/server-github
 ```
 
-Anything after `--` is forwarded verbatim as args to the command. Quote carefully.
+Everything after `--` is forwarded verbatim as args. Quote carefully.
 
 ## Anti-examples
 
 ```bash
-# DON'T put tokens in shared scope. It commits.
+# 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 remove from the wrong scope — daemon returns 409 with the right scope.
+apx mcp remove github          # errors if github lives in runtime
 
-# 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)
+# DON'T expect IDE-foreign configs (~/.cursor/mcps.json, ~/.claude/mcps.json)
+# to be removable via apx mcp remove. APX reads them advisory (source=cursor/claude)
 # but won't write them. Edit the IDE config directly.
 ```
 
-## Debugging connection issues
+## Debugging
 
 ```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
+apx mcp check --project iacrmar      # scopes seen + which files exist
+apx mcp run <name> <tool> '{...}'    # spawn server, call a tool
+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.
+"Doesn't show tools" = command failed to start (missing env vars, package not found) or crashed during initialize. Unified log holds 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`.
+> `apx mcp tools <name>` is a placeholder stub ("coming in v0.2"). Use `apx mcp run` to verify spawn.
 
 ## 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.
+- Don't mix scopes for the same MCP name unless you want shadowing — 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 — CLI preserves it).
+- Don't put tokens via `--env KEY=` inline if shell history is public. Set them in your shell first, then `--env KEY=$KEY`.
+- Don't forget to `apx daemon reload` after hand-editing JSON. `apx mcp` does this for you.

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

@@ -1,33 +1,31 @@
 ---
 name: apx-mcp-builder
 scope: internal
-description: How to build a Model Context Protocol (MCP) server from scratch and register it in APX. Load when authoring a new MCP / exposing a new tool surface to agents. Covers the JSON-RPC stdio protocol, FastMCP (Python) / TypeScript SDK shapes, and APX registration.
+description: Author a new MCP (Model Context Protocol) server and register it in APX. Covers JSON-RPC stdio protocol, FastMCP (Python) / TypeScript SDK shapes, tool design, secrets, debugging. Load when building a new MCP / exposing a new tool surface. To add an existing MCP, load `apx-mcp` instead.
 ---
 
 # 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.
+An MCP server is a tiny stdio JSON-RPC process. APX spawns it (via `apx mcp add`), discovers tools (`tools/list`), and lets the super-agent call them by name.
 
-## The minimum surface
-
-An MCP server must implement four RPC methods:
+## Minimum surface
 
 | 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. | — |
+| `initialize` | Handshake (protocol version + capabilities). | Server capabilities. |
+| `tools/list` | Enumerate tools. | `{ tools: [{name, description, inputSchema}] }` |
+| `tools/call` | Run one tool with `{ name, arguments }`. | `{ content: [...], isError? }` |
+| `notifications/initialized` | One-way init-done from APX. | — |
 
-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.
+JSON-RPC 2.0 over stdio, framed `Content-Length: N\r\n\r\n<JSON>`. The `@modelcontextprotocol/sdk` (TS) and `fastmcp` / `mcp` (Python) packages handle framing.
 
 ## 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** | Fastest path; decorator-based; ideal for pip-wrapping tools. |
+| **Node + @modelcontextprotocol/sdk** | Node-only libs, or zero install (`npx -y`). |
+| Raw JSON-RPC | Only when exposing an existing daemon. Otherwise use the SDK. |
 
 ## Python (FastMCP) — minimum viable server
 
@@ -40,7 +38,6 @@ 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()
@@ -49,18 +46,13 @@ def get_stock(sku: str) -> dict:
     return {"sku": sku, "stock": 42}
 
 if __name__ == "__main__":
-    mcp.run()  # stdio transport by default
+    mcp.run()  # stdio transport
 ```
 
-Install:
 ```bash
 pip install fastmcp
-# or via uv (recommended):
-uv tool install fastmcp
-```
+# or: uv tool install fastmcp
 
-Register in APX:
-```bash
 apx mcp add my-server \
   --command uv --project iacrmar \
   -- run python /abs/path/my_server.py
@@ -102,7 +94,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 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" }]) }],
     };
@@ -113,7 +104,6 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 await server.connect(new StdioServerTransport());
 ```
 
-Register:
 ```bash
 apx mcp add my-server \
   --command npx --project iacrmar \
@@ -122,16 +112,14 @@ apx mcp add my-server \
 
 ## 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.
+1. **Names are snake_case verbs**: `search_inventory`, not `inventorySearch`.
+2. **inputSchema is JSON Schema draft-07**. `required` matters — vague schemas → bad calls.
+3. **Descriptions read like a man-page**. Tool + param descriptions are surfaced to the model.
+4. **Return structured data**, not prose. Convention: JSON inside a text content block. Images use the `image` type.
+5. **Errors are errors**: `throw new Error(...)` propagates as `isError: true`. Empty result = "found nothing" — different signal.
 
 ## Env vars and secrets
 
-Pass them at registration time via `--env`:
-
 ```bash
 apx mcp add github \
   --scope runtime --project iacrmar \
@@ -141,43 +129,41 @@ apx mcp add github \
   -- -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.
+`--scope runtime` writes to `~/.apx/projects/<id>/mcps.json` (chmod 0600, never committed). NEVER `--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 expose every internal function. A server with 40 tools eats context.
+# Pick 5-10 high-value tools per server; split into multiple servers if 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 return giant blobs in `content`. The agent re-reads 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 mix stdio + HTTP transports in one process. APX spawns stdio;
+# for 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.)
+# DON'T print to stdout outside JSON-RPC frames. Stray print() corrupts
+# the protocol — use stderr for logs. (SDKs handle this; bare `print("debug")`
+# in a tool body breaks everything.)
 ```
 
-## Common debugging path
+## Debugging
 
 ```bash
-# 1. Does the server start + does a tool work? (apx mcp tools is a v0.2 stub — don't rely on it)
+# Smoke test (apx mcp tools is a v0.2 stub — don't rely on it)
 apx mcp run my-server search_inventory '{"query":"shoes"}'
 
-# 2. Are there spawn errors?
-apx log -f                              # tail the daemon log — stderr lands here
+# Spawn errors / stderr
+apx log -f
 
-# 3. What scopes/files + env does APX see?
+# Scopes / files / env APX sees
 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.
+- Don't reinvent SDK framing — bypass only with reason.
+- Don't make interactive tools. MCP is one-shot per call; split flows into multiple tools.
+- Don't ship without a README — future-you forgets which env vars matter.
+- Don't expect APX to retry MCP errors. The agent sees the error and decides.

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

@@ -1,30 +1,30 @@
 ---
 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.
+description: Register, list, configure, manage APX projects. Load BEFORE asking "which project?" — registered projects are listable; per-project config set via dotted-key PATCH. Triggers: 'register project', 'apx project', 'project config', 'list projects', 'what projects are registered'.
 ---
 
 # 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>/`.
+A project in APX is an APC-compliant folder (`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
+## 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.
+- **`default`** (id=0): super-agent's scratch workspace at `~/.apx/projects/default/`. Used when user has no project named, no project registered, or addresses "apx itself". Don't use for real work — 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 /path/to/repo          # reads AGENTS.md + .apc/project.json
 apx project add .                       # current dir
 
 # Inspect
 apx project list                        # id, name, agents count, path
 
-# Remove / rebuild (id or exact path only — these do NOT resolve by name)
+# Remove / rebuild (id or exact path only — no name resolution here)
 apx project remove <id|path>
-apx project rebuild <id|path>           # force re-scan of .apc/ on disk
+apx project rebuild <id|path>           # force re-scan of .apc/
 
 # Per-project config — dotted keys, lives in <repo>/.apc/config.json
 apx project config show <project>                                  # effective + project_only
@@ -36,17 +36,11 @@ apx project config unset <project> super_agent.model               # back to glo
 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.
+Every `project config` write triggers `POST /admin/reload` so the daemon picks up changes without restart.
 
-## Resolution of `<project>` argument
+## `<project>` argument resolution
 
-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.
+Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), absolute path, relative path (resolved from cwd). The CLI's `resolveProjectId()` does fuzzy id/name/path matching. If "project not found", run `apx project list` first.
 
 ## What lives where
 
@@ -59,7 +53,7 @@ The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching.
     ├── 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)
+    └── config.json                             ← project-only overrides (edited by `project config`)
 
 ~/.apx/projects/<apxId>/                        ← runtime state (never committed)
 ├── messages/YYYY-MM-DD.jsonl
@@ -70,29 +64,26 @@ The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching.
 └── mcps.json                                   ← per-project runtime MCPs (local, may hold tokens)
 ```
 
-## Anti-example
+## Anti-examples
 
 ```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
-```
+mkdir -p /path/repo/.apc && echo "{...}" > /path/repo/.apc/project.json
+# ↑ No scaffold validation; project appears registered but breaks on `apx project rebuild`.
+# Use `apx init <path>` then `apx project add <path>`.
 
-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.
+# DON'T set super_agent.model to a model lacking an engine key.
 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.
+# ↑ Fails 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 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 operate on the default project (id=0) as if it were the user's main work. 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.
+- Don't move a project's `.apc/` folder without re-running `apx project rebuild` — `apxId` will be stale.

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

@@ -1,35 +1,31 @@
 ---
 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.
+description: Create, edit, run, debug APX routines (scheduled tasks). Load BEFORE `apx routine add` — schedule grammar, kind selection, pre/post hooks, double-reply gotcha.
 ---
 
 # 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.
+A scheduled APX task. Scheduler ticks every 5s. Each routine has a `kind`, `schedule`, optional `spec`, and optional `pre_commands` / `post_commands` shell hooks.
 
-## When to use which `kind`
+## Picking `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`.
+| `heartbeat` | no | "Still alive" marker. No LLM. |
+| `shell` | no | Pure shell. Stdout captured. |
+| `exec_agent` | **no** | Loads agent prompt, sends `spec.prompt`, returns text. Single LLM call. |
+| `super_agent` | **all** | Default agent with full tool registry. Multi-iteration loop. |
+| `telegram` | n/a | Sends hardcoded text via Telegram plugin. |
+
+Rule: text from model → `exec_agent`; orchestration (MCPs, files, multi-agent) → `super_agent`; pure shell → `shell`; fixed Telegram poke → `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.
+- `once:<iso-8601>` — `once:2026-12-01T08:00:00Z`. Fires once, then disabled.
+- Cron — `*/5 * * * *`, `0 8 * * *`. Standard 5-field.
 
-## Anatomy of a routine
+## Anatomy
 
 ```json
 {
@@ -44,12 +40,9 @@ A routine is a scheduled APX task. APX runs the scheduler tick every 5s and fire
 }
 ```
 
-**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.
+Pipeline: `pre_commands` run sequentially → combined stdout becomes `{{pre_output}}` in `spec.prompt` and `$APX_PRE_OUTPUT` (plus `$APX_PRE_OUTPUT_FILE` for big payloads) → handler runs, result becomes `$APX_LLM_OUTPUT` → `post_commands` run.
 
-## Anti-example: the double-reply
+## Anti-example: double-reply
 
 ```json
 {
@@ -59,28 +52,24 @@ A routine is a scheduled APX task. APX runs the scheduler tick every 5s and fire
 }
 ```
 
-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`:
+Sends **two** messages: one from agent's `send_telegram` tool, one from `post_commands`. The runner auto-suppresses `send_telegram` when post contains `apx telegram send`, but the clean fix is `exec_agent`:
 
 ```json
 {
   "kind": "exec_agent",
-  "spec": { "agent": "default", "prompt": "The weather is {{pre_output}}. One friendly sentence, no greeting." },
+  "spec": { "agent": "default", "prompt": "The weather is {{pre_output}}. One friendly sentence." },
   "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)
+# Always pin --project; never use default for real ones
 apx routine list --project iacrmar
+apx routine get  weather-bariloche --project iacrmar
 
-# Inspect one
-apx routine get weather-bariloche --project iacrmar
-
-# Create — text-only exec_agent + shell delivery
+# Create — exec_agent + shell delivery
 apx routine add weather-bariloche \
   --project iacrmar \
   --kind exec_agent \
@@ -97,7 +86,7 @@ apx routine add daily-status \
   --spec '{"prompt":"List projects with pending tasks and send me a short summary via Telegram."}' \
   --permission-mode automatico
 
-# Toggle, run, remove
+# 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
@@ -106,23 +95,21 @@ 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>`.
+Routines live in `~/.apx/projects/<apxId>/routines.json`. Without `--project`, they go to default (id=0, super-agent scratch) — **not** a user project. Always pass `--project <name|id|path>`.
 
 ## `skip_prompt_on`
 
-Controls whether the LLM call is skipped based on the `pre_commands` result (`shouldSkipPrompt` in `host/daemon/routines.js`):
+Gates the LLM call based on `pre_commands` (`shouldSkipPrompt` in `host/daemon/routines.js`). Post-commands always run.
 
-| Value | Skips the LLM when… |
+| Value | Skips LLM when… |
 |---|---|
-| `signal` (default) | a pre_command prints the literal marker `APX_SKIP` to stdout. A non-zero exit alone does **not** skip. |
+| `signal` (default) | pre_command prints literal `APX_SKIP`. Non-zero exit alone does NOT skip. |
 | `pre_failure` | any pre_command exits non-zero. |
-| `pre_success` | the pre_commands exit 0 (i.e. run the LLM only on pre failure). |
-| `always` | unconditionally — pure pre→post pipeline, no LLM. |
-| `never` | never — the LLM always runs, even if pre crashes. |
-
-Post-commands run regardless of the skip decision. The skip only gates the `kind` handler (the LLM call).
+| `pre_success` | pre_commands exit 0 (LLM only on pre failure). |
+| `always` | unconditionally — pure pre→post, no LLM. |
+| `never` | LLM always runs, even if pre crashes. |
 
-## Debugging a routine
+## Debugging
 
 ```bash
 apx routine history weather-bariloche --project iacrmar    # last runs
@@ -130,11 +117,11 @@ 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`.
+"Sends nothing" usually means: `enabled: false`, `next_run_at` in the future, or empty LLM text (check `apx messages` or `result.text`).
 
 ## 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.
+- Use `super_agent` when `exec_agent` would do — it loops, calls tools, costs more.
+- Write `apx telegram send` inside a `super_agent` prompt — agent calls `send_telegram` AND post_commands fire. Pick one.
+- Hardcode model names in `spec` without reason — routines inherit `super_agent.model` (with router fallback).
+- Put credentials in `spec`. Use `~/.apx/config.json` engines and reference by provider.