@agentprojectcontext/apx 1.31.2 → 1.32.2

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.31.2",
+  "version": "1.32.2",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
   },
   "license": "MIT",
   "type": "module",
+  "imports": {
+    "#core/*": "./src/core/*",
+    "#host/*": "./src/host/*",
+    "#interfaces/*": "./src/interfaces/*"
+  },
   "bin": {
     "apx": "./src/interfaces/cli/index.js",
     "apx-daemon": "./src/host/daemon/index.js",

package/skills/apc-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Activate whenever the project has a .apc/ directory or AGENTS.md — read .apc/ before assuming anything about agents, memory, or structure. If .apc/migrate.md exists, open with a migration offer first; if the user declines, delete it. Triggers: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents'."
 homepage: https://github.com/agentprojectcontext/agentprojectcontext
 ---
 
@@ -66,11 +66,13 @@ After migration:
 ```text
 AGENTS.md                        ← root project contract
 .apc/
-  project.json                   ← project metadata
+  project.json                   ← project metadata (may carry an `apx` field)
+  config.json                    ← project-only config overrides (e.g. super_agent.model)
   .gitignore                     ← safety guard
   agents/<name>.md               ← agent definition
   agents/<name>/memory.md        ← optional curated project memory
   skills/<name>.md               ← reusable project instructions
+  commands/                      ← custom slash-commands (optional)
   mcps.json                      ← MCP hints without secrets
 ```
 
@@ -81,6 +83,7 @@ Do not store:
 .apc/sessions/
 .apc/conversations/
 .apc/messages/
+.apc/project.db
 .apc/cache/
 .apc/tmp/
 .apc/private/

package/skills/apx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apx
-description: "APX CLI umbrella skill — what APX is, when to call it, and which sub-skill to use for each operation. Activate when the user mentions `apx`, asks to coordinate / run / delegate agents, brings up the APX daemon, or wants any APX-managed surface (sessions, MCPs, routines, tasks, telegram, projects, agents). Do NOT activate just because `.apc/` exists — that is handled by the apc-context skill. Triggers: 'apx', 'apx run', 'apx exec', 'apx daemon', 'coordinate agents', 'run an agent in codex', 'apx memory', 'apx help'."
+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
 ---
 
@@ -28,11 +28,11 @@ Use APX when:
 | 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`, "traer sesión de 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** | "anotame", "recordame que…", "qué tengo pendiente" |
+| 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 |

package/skills/apx-agency-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apx-agency-agents
-description: "Manage the APX agent vault — a library of reusable agent templates (Roby, Cody, Rocky, Tessa, Max, Arch, Sid, Vera, Finn, plus generic specialists: development, marketing, ops, qa, support). Load this when the user wants to: spawn a specialized agent, look up which templates are available, import a template into a project, create a new vault template, delete/hide a bundled default, or restore a previously hidden one. Trigger on: 'lanzar agente', 'spawn agent', 'usar a Cody/Rocky/Tessa/Max/Arch/Sid/Vera/Roby', 'qué agentes hay', 'agent vault list', 'apx agent vault', 'importar agente', 'nuevo agente', 'crear agente nuevo', 'borrar agente default', 'restaurar agente'."
+description: "Manage the APX agent vault — reusable agent templates (Roby, Cody, Rocky, Tessa, Max, Arch, Sid, Vera, Finn + generic dev/marketing/ops/qa/support). Load to spawn a specialist, list templates, import one into a project, create a template, or hide/restore a bundled default. Triggers: 'spawn agent', 'use Cody/Rocky/Tessa', 'list agents', 'agent vault', 'import agent', 'new agent'."
 ---
 
 # apx-agency-agents — the APX agent vault
@@ -45,7 +45,7 @@ Plain functional roles — useful when you want capabilities without a persona:
 | `qa` | Quality assurance & testing |
 | `support` | Customer support & escalations |
 
-Both families default to `model: openrouter:meta-llama/llama-3.3-70b-instruct` and `language: es`. Override on import or by editing the vault file directly.
+Bundled templates ship with `language: es` and **no `model:` set** — they inherit the project/global default model. Set a model on import or by editing the vault file directly.
 
 ## Concrete commands
 
@@ -84,14 +84,14 @@ import_agent({ slug: "cody-developer", project: "<name-or-path>" })
 
 ## The web equivalents
 
-The Agent defaults tab (`/p/0/agent-defaults`) has the same CRUD: a "Nuevo" button (POST `/agents/vault`), "Editar" per card (PATCH `/agents/vault/:slug`, copy-on-write for bundled), "Borrar"/"Ocultar" (DELETE), and a "Mostrar removidos" toggle that surfaces tombstoned bundled defaults with a "Restaurar" button.
+The Agent defaults tab (`/p/0/agent-defaults`) has the same CRUD: a "New" button (POST `/agents/vault`), "Edit" per card (PATCH `/agents/vault/:slug`, copy-on-write for bundled), "Delete"/"Hide" (DELETE), and a "Show removed" toggle that surfaces tombstoned bundled defaults with a "Restore" button.
 
 ## When to use which agent
 
-- **User says "lanzar a Cody/Rocky/Tessa/Max/Arch/Sid/Vera/Roby/Finn"** → that exact slug exists in the named team. Import it.
+- **User says "spawn/use Cody/Rocky/Tessa/Max/Arch/Sid/Vera/Roby/Finn"** → that exact slug exists in the named team. Import it.
 - **User wants a "developer" / "QA" / "marketing" agent without a persona** → use the generic specialists (`development`, `qa`, `marketing`, …).
 - **User wants something not in the vault** → either `apx agent vault add <slug>` to create a blank one, or `apx agent add <slug>` directly inside a project for a one-off.
-- **The vault is empty on a fresh install** → suggest `apx agent vault sync` first.
+- **Fresh install** → bundled defaults are always present (no sync step); they appear in `apx agent vault list` immediately.
 
 ## Where the files live
 

package/skills/apx-agent/SKILL.md

@@ -10,8 +10,8 @@ A project agent is a named persona inside an APC project. Canonical definition:
 ## Concrete CLI calls
 
 ```bash
-# List agents in a project
-apx agent list --project iacrmar
+# List agents in the current project (agent commands are cwd-scoped — run from the project root)
+apx agent list
 
 # Create a new agent (writes .apc/agents/<slug>.md, creates runtime dir, regenerates AGENTS.md)
 apx agent add reviewer \
@@ -31,10 +31,10 @@ apx agent import <slug> --force      # overwrite existing local definition
 # Show details (config + memory)
 apx agent get <slug>                 # alias: apx agent show <slug>
 
-# Per-agent memory (drives system prompt for that agent)
-apx memory <slug> --project iacrmar                          # read
-apx memory <slug> --project iacrmar --append "fact"          # append a line
-apx memory <slug> --project iacrmar --replace < file.md       # full replace from stdin
+# Per-agent memory (drives system prompt for that agent; cwd-scoped — run from the project root)
+apx memory <slug>                          # read
+apx memory <slug> --append "fact"          # append a line under "## Recent context"
+apx memory <slug> --replace < file.md      # full replace from stdin
 ```
 
 ## What the agent's system prompt looks like
@@ -54,7 +54,7 @@ That's the prompt the engine sees on every `apx exec <agent>` or `apx chat <agen
 
 ## Models per agent
 
-Each agent can set `Model:` in its `AGENT.md` to override the global super-agent model. Leave it empty when the agent should follow the project/global default.
+Each agent can set `Model:` in its `.apc/agents/<slug>.md` definition to override the global super-agent model. Leave it empty when the agent should follow the project/global default.
 
 ```markdown
 # .apc/agents/reviewer.md

package/skills/apx-mcp/SKILL.md

@@ -41,16 +41,16 @@ 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)
+# 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 (modifies whichever scope owns it)
+# 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 tools <name>                            # list tools the server exposes
 apx mcp run filesystem read_file '{"path":"README.md"}'
 ```
 
@@ -100,12 +100,14 @@ apx mcp remove github          # if github lives in runtime, this errors with a
 
 ```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 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."

package/skills/apx-mcp-builder/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.
+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.
 ---
 
 # apx-mcp-builder
@@ -165,16 +165,13 @@ apx mcp add github \
 ## Common debugging path
 
 ```bash
-# 1. Does the server start?
-apx mcp tools my-server                # forces a spawn + tools/list
+# 1. Does the server start + does a tool work? (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
 
-# 3. Does a tool work in isolation?
-apx mcp run my-server search_inventory '{"query":"shoes"}'
-
-# 4. Are env vars set?
+# 3. What scopes/files + env does APX see?
 apx mcp check --project iacrmar
 ```
 

package/skills/apx-project/SKILL.md

@@ -20,12 +20,11 @@ apx project add /path/to/repo          # registers; reads AGENTS.md + .apc/proje
 apx project add .                       # current dir
 
 # Inspect
-apx project list                        # name, id, path, agents count
-apx project list -l                     # long form, includes storagePath
+apx project list                        # id, name, agents count, path
 
-# Remove / rebuild
-apx project remove <id|name|path>
-apx project rebuild <id|name|path>      # force re-scan of .apc/ on disk
+# Remove / rebuild (id or exact path only — these do NOT resolve by name)
+apx project remove <id|path>
+apx project rebuild <id|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

package/skills/apx-routine/SKILL.md

@@ -36,7 +36,7 @@ A routine is a scheduled APX task. APX runs the scheduler tick every 5s and fire
   "name": "weather-bariloche",
   "kind": "exec_agent",
   "schedule": "every:24h",
-  "spec": { "agent": "default", "prompt": "Escribí un saludo breve..." },
+  "spec": { "agent": "default", "prompt": "Write a short greeting..." },
   "pre_commands":  ["curl -s 'https://wttr.in/Bariloche?format=...'"],
   "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""],
   "enabled": true,
@@ -54,7 +54,7 @@ A routine is a scheduled APX task. APX runs the scheduler tick every 5s and fire
 ```json
 {
   "kind": "super_agent",   ← DON'T
-  "spec": { "prompt": "El clima es {{pre_output}}. Mandalo por Telegram." },
+  "spec": { "prompt": "The weather is {{pre_output}}. Send it via Telegram." },
   "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
 }
 ```
@@ -64,7 +64,7 @@ This sends **two** Telegram messages: one from the super-agent's `send_telegram`
 ```json
 {
   "kind": "exec_agent",
-  "spec": { "agent": "default", "prompt": "El clima es {{pre_output}}. Una frase amigable, sin saludos." },
+  "spec": { "agent": "default", "prompt": "The weather is {{pre_output}}. One friendly sentence, no greeting." },
   "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
 }
 ```
@@ -85,7 +85,7 @@ 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."}' \
+  --spec '{"agent":"default","prompt":"The weather is {{pre_output}}. One friendly sentence."}' \
   --pre-commands "curl -s 'https://wttr.in/Bariloche?format=%t+%C+viento+%w'" \
   --post-commands 'apx telegram send "$APX_LLM_OUTPUT"'
 
@@ -94,7 +94,7 @@ 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."}' \
+  --spec '{"prompt":"List projects with pending tasks and send me a short summary via Telegram."}' \
   --permission-mode automatico
 
 # Toggle, run, remove
@@ -110,15 +110,17 @@ Routines live in `~/.apx/projects/<apxId>/routines.json`. Without `--project`, t
 
 ## `skip_prompt_on`
 
-Controls what happens when `pre_commands` exit non-zero:
+Controls whether the LLM call is skipped based on the `pre_commands` result (`shouldSkipPrompt` in `host/daemon/routines.js`):
 
-| Value | Behavior |
+| Value | Skips the LLM when… |
 |---|---|
-| `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. |
+| `signal` (default) | a pre_command prints the literal marker `APX_SKIP` to stdout. A 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).
 
 ## Debugging a routine
 

package/skills/apx-runtime/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Delegate a task to an external coding CLI (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code) via `apx run`. APX builds the system prompt, spawns the CLI, and captures the result. Load when delegating work to another AI tool.
 ---
 
 # apx-runtime
@@ -25,13 +25,15 @@ A "runtime" in APX is an external AI coding CLI that APX can invoke headlessly.
 
 ```bash
 # What's available on this machine
-apx env detect
-apx runtime list
+apx env detect          # which runtimes are installed and reachable
+apx env list            # alias of `apx env detect`
 
 # 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>"
+apx run scratch  --runtime codex --timeout 300 "<prompt>"   # cap the run (seconds)
+apx run scratch  --runtime codex -      # read the prompt from stdin (large prompts)
 ```
 
 Behavior:

package/skills/apx-sessions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apx-sessions
-description: "APX session management across engines (apx, claude, codex). Use when: finding a session by its title/topic without knowing the id (`apx session find`), listing sessions of one or every engine for a project, resuming a session by id without remembering which engine owns it, summarizing a Claude/Codex/APX transcript (`apx session summary`), asking a question about what happened in a past session (`apx session ask`), pulling a full transcript by id (useful when you want to read another tool's session from inside Claude), spawning the native CLI to continue a session (`claude --resume`, `codex resume`), or seeding a brand-new APX session with the summary of an old one. Triggers on: 'apx session find', 'find a session', 'buscar sesión', 'qué sesión era la de…', 'apx session ask', 'preguntale a la sesión', 'apx session summary', 'apx session resume', 'apx session get', 'apx sessions list', 'continue codex session', 'resume claude session', 'summarize session', 'get session transcript', 'continue session in apx', 'qué sesiones hay', 'traer sesión de codex', 'leer sesión de claude'. Do NOT activate for generic agent orchestration or `apx run` — that belongs to the parent `apx` skill."
+description: "Manage APX sessions across engines (apx, claude, codex). Find a session by title, list, resume, summarize, ask about, or pull a transcript — without knowing which engine owns it. Triggers: 'apx session find/ask/summary/resume/get', 'find a session', 'resume claude/codex session', 'summarize session', 'get session transcript', 'continue session in apx'. Not for `apx run` orchestration (that's the apx skill)."
 ---
 
 # APX Sessions — cross-engine resume, summary, and continuation
@@ -26,13 +26,13 @@ You almost never start with a session id — you start with a vague memory of a
 
 ```bash
 # 1. Turn a remembered title into an id (cross-engine, newest first)
-apx session find "mejorar interfaz web"
+apx session find "improve web UI"
 
 # 2. Get the gist of that session
 apx session summary <id>
 
 # 3. Ask something specific about it
-apx session ask <id> "¿qué cambios al sidebar quedaron pendientes?"
+apx session ask <id> "what sidebar changes were left pending?"
 ```
 
 `find` prints a "Next:" block with the exact `summary`/`ask`/`resume` commands pre-filled with the top hit's id, so you can copy-paste straight through. **If you're tempted to grep session lists, use `find` instead.**
@@ -72,7 +72,7 @@ This is the discoverable alias for `apx session resume <id> --summary`. It resol
 ## Asking questions about a session (`apx session ask`)
 
 ```bash
-apx session ask <id> "¿qué decidimos sobre el sidebar?"
+apx session ask <id> "what did we decide about the sidebar?"
 apx session ask <id> "what files were changed?" --max-chunks 30
 ```
 
@@ -248,7 +248,7 @@ Pick one with `--engine claude` or `--engine codex` and run again.
 3. **`summary` for the gist, `ask` for specifics.** Use `apx session summary <id>` to orient; use `apx session ask <id> "<q>"` when the user has a concrete question. Both need the daemon + `super_agent.enabled`.
 4. **`ask` on a huge transcript is slow and capped.** If the output warns about truncation and the user needs full coverage, re-run with a higher `--max-chunks`.
 5. **Prefer `--tail N` over `--full`** when feeding a raw transcript into another model — JSONL is verbose, the tail is dense.
-6. **`--into apx:slug` is the bridge** between an external runtime's session and an APX agent. Use it when the user says "continuamos esto en apx con el agente reviewer".
+6. **`--into apx:slug` is the bridge** between an external runtime's session and an APX agent. Use it when the user says "let's continue this in apx with the reviewer agent".
 7. **Don't invent ids.** Discover them via `apx session find` or `apx sessions list`.
 8. **`apx session get --any --full`** is the simplest way to import an arbitrary engine session into your context, with no daemon dependency.
 

package/skills/apx-skill-builder/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: apx-skill-builder
 scope: internal
-description: How to author a new APX skill. Load when the user asks "creame una skill X", "necesito una skill que enseñe Y", or you (the agent) decide a recurring instruction set deserves to be a skill. Covers file location, frontmatter, body style, and how the super-agent finds it on demand.
+description: How to author a new APX skill — file location, frontmatter (name, description, scope), body style, and how the super-agent loads it on demand. Load when creating or adding a skill to APX.
 ---
 
 # apx-skill-builder
@@ -32,12 +32,15 @@ The file MUST open with YAML frontmatter:
 ```yaml
 ---
 name: my-skill
-description: One-sentence trigger for the super-agent. Include the user-phrases that should cause it to load. Keep under 220 chars — appears in skill listings.
+description: One-sentence trigger for the super-agent. Include the user-phrases that should cause it to load. Keep it short — appears in skill listings.
+scope: public   # public (pushed to IDE skill dirs by default) | internal (repo/dev-only) | optional
 ---
 ```
 
 `description` is what the model sees when deciding whether to call `load_skill`. Write it as the *trigger condition*, not a summary of the body.
 
+`scope` controls distribution: `public` skills are installed globally by `apx skills sync` / `--global`; `internal` ones stay in the APX repo (dev guides like this one); `optional` ones are available but not pushed by default. Omit it and the skill is treated as public.
+
 **Good**: `"How to register an MCP server. Load BEFORE running 'apx mcp add' — three scopes, gotchas with stdio commands, secrets handling."`
 
 **Bad**: `"This skill describes APX's MCP system."` (no trigger; the model won't know when it matters).
@@ -65,8 +68,9 @@ That returns the full body. The agent uses the content in-context for that turn;
 
 The user can list installed skills with:
 ```bash
-apx skills list
-apx skills list --project iacrmar
+apx skills list          # lists this project's .apc/skills/ (cwd-scoped — run from the project root)
+apx skills sync          # push bundled/public skills to the global skill dir
+apx skills status        # show what's installed vs available
 ```
 
 ## Workflow: create + register
@@ -85,8 +89,8 @@ $EDITOR skills/my-thing/SKILL.md
 #    you've changed the scaffold sync. Confirm:
 apx skills list | grep my-thing
 
-# 4. Inside the super-agent, you can pre-test:
-apx exec super-agent "Cargá la skill my-thing y resumime en 3 bullets"
+# 4. Pre-test with the super-agent (it's the default target — no agent name needed):
+apx exec "Load the my-thing skill and summarize it in 3 bullets"
 ```
 
 ## Anti-examples

package/skills/apx-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apx-task
-description: Per-project TODO list. Load when the user says "anotame", "recordame que…", "qué tengo pendiente", "marca como hecho". Tasks are project-scoped, event-sourced, and addressable by short id prefix.
+description: Per-project TODO list. Load when the user wants to note, remind, list, or complete a task. Tasks are project-scoped, event-sourced, and addressable by short id prefix. Triggers: 'add a task', 'remind me to…', 'what's pending', 'mark as done'.
 ---
 
 # apx-task
@@ -11,9 +11,9 @@ A `task` is a per-project TODO. Append-only JSONL event log per month under `~/.
 
 ```bash
 # Add — most common
-apx task add "Revisar bug de auth" --project iacrmar
-apx task add "Llamar al cliente" --project iacrmar --due 2026-05-30 --tag urgent
-apx task add "Demo a tester X"   --project iacrmar --agent reviewer --tag demo --tag external
+apx task add "Review the auth bug" --project iacrmar
+apx task add "Call the client" --project iacrmar --due 2026-05-30 --tag urgent
+apx task add "Demo for tester X" --project iacrmar --agent reviewer --tag demo --tag external --source cli
 
 # List (defaults to open)
 apx task list --project iacrmar
@@ -29,7 +29,7 @@ apx task show abc       --project iacrmar    # prefix match (≥3 chars), unique
 apx task done    t_abc123 --project iacrmar --by manuel
 apx task drop    t_abc123 --project iacrmar               # archived (not "done")
 apx task reopen  t_abc123 --project iacrmar
-apx task patch   t_abc123 --project iacrmar --title "Nuevo título" --due 2026-06-10
+apx task patch   t_abc123 --project iacrmar --title "New title" --due 2026-06-10
 apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces tags
 ```
 
@@ -51,14 +51,14 @@ apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces
 
 ## Super-agent tools
 
-The super-agent has `create_task` and `list_tasks` tools. So a user message like "Anotame que mañana hay que cerrar el bug de auth en iacrmar" makes the model call:
+The super-agent has `create_task` and `list_tasks` tools. So a user message like "note that we need to close the auth bug in iacrmar tomorrow" makes the model call:
 
 ```json
 { "name": "create_task",
-  "arguments": { "project": "iacrmar", "title": "Cerrar bug de auth", "due": "<tomorrow>", "tags": ["bug"] } }
+  "arguments": { "project": "iacrmar", "title": "Close the auth bug", "due": "<tomorrow>", "tags": ["bug"] } }
 ```
 
-When the user asks "qué tengo pendiente en iacrmar?", the model calls `list_tasks({ project: "iacrmar" })`.
+When the user asks "what's pending in iacrmar?", the model calls `list_tasks({ project: "iacrmar" })`.
 
 If the user doesn't say which project, the model should `list_projects` first and ask which one — never assume. If the conversation has a project context (Telegram channel pinned to project), the model uses that.
 

package/skills/apx-telegram/SKILL.md

@@ -23,9 +23,12 @@ APX runs a Telegram plugin that polls `getUpdates` and routes messages. Config l
         "chat_id": "<your numeric chat id>",
         "project": "iacrmar",        // optional: pin this channel to that project
         "route_to_agent": "reviewer", // optional: this agent handles messages on this channel
-        "respond_with_engine": true   // optional: override the global default
+        "respond_with_engine": true,  // optional: override the global default
+        "owner_user_id": "123456789"  // optional: per-channel owner (set via `apx telegram owner`)
       }
-    ]
+    ],
+    "contacts": [],                   // global roster (user_id → role); see `apx telegram contacts`
+    "roles": {}                       // role → allowed tools; see `apx telegram roles`
   }
 }
 ```
@@ -35,16 +38,28 @@ The old `telegram.bot_token` / `telegram.chat_id` at the root are **legacy**. Do
 ## Concrete CLI calls
 
 ```bash
+# Print the config template to get started
+apx telegram setup            # note: still emits root bot_token/chat_id — prefer channels[] below
+
 # Channels CRUD
 apx telegram channel add               # interactive wizard
 apx telegram channel add clientes --bot-token <T> --chat-id <C> --project iacrmar --agent reviewer
-apx telegram channel list
-apx telegram channel show clientes
+apx telegram channel list              # alias: ls
+apx telegram channel show clientes     # alias: get
 apx telegram channel set    clientes --project iacrmar
 apx telegram channel set    clientes --agent reviewer
 apx telegram channel set    clientes --respond-engine false
 apx telegram channel unset  clientes --project --agent
-apx telegram channel remove clientes
+apx telegram channel remove clientes   # alias: rm
+apx telegram owner          clientes <user_id>   # set the per-channel owner
+
+# Contacts roster + roles (global; gate which tools a sender may trigger)
+apx telegram contacts                  # list the global roster
+apx telegram contacts rm <user_id>
+apx telegram role  <user_id> <role>    # assign a role to a contact
+apx telegram roles                     # list role → tools mappings
+apx telegram roles set <name> --tools a,b,c   # or --tools '*' for all
+apx telegram roles rm  <name>
 
 # Polling lifecycle (rarely needed — autostart with daemon)
 apx telegram start
@@ -52,8 +67,9 @@ apx telegram stop
 apx telegram status
 
 # Sending (defaults to first configured channel; use --chat for explicit chat id)
-apx telegram send "texto"
-apx telegram send "texto" --chat 123456789
+apx telegram send "text"
+apx telegram send "text" --chat 123456789
+apx telegram send "text" --interrupt        # bypass the pending-agent queue (also: --force)
 
 # Media (daemon HTTP API — no dedicated CLI subcommand yet)
 curl -X POST http://127.0.0.1:7430/telegram/send_photo \

package/skills/apx-voice/SKILL.md

@@ -27,13 +27,15 @@ APX has a Text-to-Speech (TTS) facade in `core/voice/` with five engines. STT (s
 apx voice providers
 
 # Synthesize and play
-apx voice say "Hola Manú" --provider piper
-apx voice say "Hola Manú" --provider gemini
+apx voice say "Hello from APX" --provider piper
+apx voice say "Hello from APX" --provider gemini
+apx voice say "Hello from APX" --provider gemini --voice Aoede   # pick a specific voice
 apx voice say "..." --no-play          # generate WAV, don't play
 
 # Listen (mic → STT)
 apx voice listen                       # records until silence (sox) or Ctrl+C
 apx voice listen --seconds 5           # fixed-duration capture
+apx voice listen --provider <id>       # override the STT/transcription provider
 ```
 
 Playback uses system binaries (`afplay`, `paplay`, `aplay`, `play`, `ffplay`) — APX doesn't bundle an audio runtime. If none is found, you get the file path and no playback.
@@ -68,7 +70,7 @@ curl -L https://github.com/rhasspy/piper/releases/latest/download/piper_macos_aa
   -o /tmp/piper.tar.gz
 sudo tar xzf /tmp/piper.tar.gz -C /usr/local/bin --strip-components=1
 
-# 2. Voice model (es_AR — Argentine Spanish, daughter)
+# 2. Voice model (es_AR — Argentine Spanish, voice "daniela")
 mkdir -p ~/.apx/voices
 cd ~/.apx/voices
 curl -LO https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_AR/daniela/high/es_AR-daniela-high.onnx
@@ -79,7 +81,7 @@ apx config set voice.tts.provider piper
 apx config set voice.tts.piper.model "$HOME/.apx/voices/es_AR-daniela-high.onnx"
 
 # 4. Test
-apx voice say "hola Manú" --provider piper
+apx voice say "hola, soy APX" --provider piper   # Spanish text exercises the es_AR voice
 ```
 
 ### Gemini cloud (quick if you already have a key)
@@ -88,7 +90,7 @@ apx voice say "hola Manú" --provider piper
 apx config set voice.tts.provider gemini
 apx config set voice.tts.gemini.api_key '<GEMINI_KEY>'
 apx config set engines.gemini.api_key   '<GEMINI_KEY>'    # reuse for LLM router
-apx voice say "hola Manú" --provider gemini
+apx voice say "Hello from APX" --provider gemini
 ```
 
 ## The unified voice channel
@@ -100,7 +102,7 @@ apx voice say "hola Manú" --provider gemini
 curl -X POST http://127.0.0.1:7430/voice/turn \
   -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
   -H "Content-Type: application/json" \
-  -d '{"text":"Hola APX","channel":"voice"}'
+  -d '{"text":"Hello APX","channel":"voice"}'
 ```
 
 Telegram voice messages and the overlay mascot still have their own STT pipelines today — they don't go through `/voice/turn` (yet). The endpoint exists for callers that want one-shot bidirectional voice.

package/src/core/{agent-system.js → agent/build-agent-system.js}

@@ -1,17 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
-import { readAgentMemory } from "./agent-memory.js";
-
-// ---------------------------------------------------------------------------
-// Anti-ghost-response rules injected into every agent system prompt.
-// Prevents agents from saying "Ok, I'll do that" and then doing nothing.
-// ---------------------------------------------------------------------------
-const ACTION_DISCIPLINE_RULES = `## Action Discipline (mandatory)
-- NEVER acknowledge an action without executing it in the same turn. If you are going to do something, call the tool FIRST, then report the result.
-- NEVER use empty acknowledgments like "Ok", "Got it", "Sure", "Understood", "On it", "Give me a moment", "I'll do that now" as standalone responses when a tool call is expected. These are invalid responses.
-- Action first, report after. Produce the tool call in the same response as your acknowledgment.
-- If you cannot execute the action (missing permission, unclear params, tool not available), explain WHY — do not promise and disappear.
-- If the user asks you to do multiple things, do them all in the same turn using sequential tool calls if needed.`;
+import { fileURLToPath } from "node:url";
+import { readAgentMemory } from "./memory.js";
+
+// Anti-ghost-response rules injected into every agent system prompt. The text
+// lives next to the agent prompts (src/core/agent/prompts/action-discipline.md)
+// so it can be edited without touching code. Cached at module load.
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ACTION_DISCIPLINE_RULES = fs
+  .readFileSync(path.join(__dirname, "prompts", "action-discipline.md"), "utf8")
+  .trimEnd();
 
 function listField(value) {
   if (Array.isArray(value)) return value.map(String).map((s) => s.trim()).filter(Boolean);