@agentprojectcontext/apx 1.81.0 → 1.89.1

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

@@ -1,23 +1,33 @@
 ---
 name: apx-runtime
-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, captures the result. Load when delegating to another AI tool.
+description: Delegate a task to an external coding CLI (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code, antigravity) via `apx run`. The APX agent is optional — pass-through runs the CLI as itself, `-a <agent>` wraps it in that agent's system prompt. Load when delegating to another AI tool, or when confused about the agent argument.
 ---
 
 # apx-runtime
 
-A "runtime" is an external AI coding CLI that APX invokes headlessly. APX builds the agent's system prompt, spawns the CLI with the right flags, captures stdout (and the external session id when available), and stores run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (never committed). Some flows link to the engine's own transcript path.
+A "runtime" is an external AI coding CLI that APX invokes headlessly. APX spawns the CLI with the right flags, captures stdout (and the external session id when available), and stores run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (never committed). Some flows link to the engine's own transcript path.
+
+## The agent is OPTIONAL — and it is not "the CLI's agent"
+
+`apx run` delegates a prompt to an external CLI (claude-code, codex, …) that **has its own agency**. An APX agent does one thing here: its `buildAgentSystem()` output becomes the CLI's system prompt. It is a wrapper, not something Claude "uses."
+
+- **No agent → pass-through.** `apx run --runtime claude-code "<prompt>"` hands the prompt to the CLI with **no APX system prompt** — Claude/Codex runs as itself. This is the right form when you just want to delegate a task to the tool. Don't invent an agent to do it.
+- **With an agent → wrapped.** `apx run -a <agent> --runtime … "<prompt>"` when you want an APX persona/instructions (a project reviewer, a house style) to shape the run. Use it only when that wrapping is the point.
+
+(`apx exec` is the sibling for APX's OWN in-process engine — there `-a <agent>` is likewise optional and defaults to the super-agent. `apx run` is specifically for spawning an external CLI.)
 
 ## 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` |
+| `codex`         | `codex`         | `exec "<prompt>" --sandbox workspace-write --skip-git-repo-check --json` |
+| `opencode`      | `opencode`      | `run "<prompt>"` (non-interactive) |
+| `aider`         | `aider`         | `--message "<prompt>" --yes-always --no-auto-commits` |
 | `cursor-agent`  | `cursor-agent`  | headless print mode |
 | `gemini-cli`    | `gemini`        | headless prompt mode |
-| `qwen-code`     | `qwen-code`     | system prompt passed separately |
+| `qwen-code`     | `qwen`          | `--output-format text --approval-mode yolo "<prompt>"` |
+| `antigravity`   | `agy`           | `agy -p "<prompt>"` (headless). Falls back to the `antigravity-ide` GUI, which can't return a result to stdout. |
 
 `apx env detect` reports which are installed and reachable.
 
@@ -27,19 +37,41 @@ A "runtime" is an external AI coding CLI that APX invokes headlessly. APX builds
 apx env detect          # which runtimes are installed
 apx env list            # alias
 
-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 (seconds)
-apx run scratch  --runtime codex -      # prompt from stdin (large prompts)
+# Pass-through — just delegate to the CLI (no APX agent). The common case.
+apx run --runtime claude-code "Review the diff in src/host/daemon/api/ for memory leaks"
+apx run --runtime codex        "Refactor parseAgentFile to use a state machine"
+apx run --runtime codex --timeout 300 "<prompt>"   # cap (seconds)
+apx run --runtime codex -                          # prompt from stdin (large prompts)
+
+# Wrapped — shape the run with an APX agent's system prompt.
+apx run -a reviewer --runtime claude-code "Review this repo"
 ```
 
 Behavior:
 1. APX picks project from `--project` or cwd.
-2. Reads agent's `AGENT.md` + memory + skills; builds system prompt with `buildAgentSystem({ invocation: "runtime", runtime: "<id>" })`.
+2. **If `-a <agent>` was given**, reads that agent's definition + memory + skills and builds a system prompt with `buildAgentSystem(project, agent, { invocation: "runtime", runtime: "<id>" })`. **No agent → no system prompt (pass-through).**
 3. Spawns CLI with the right flags; cwd = project path.
 4. Captures stdout. If runtime printed `APC_RESULT: <value>`, that's the structured result; else 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 transcript when available.
+5. Writes a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` — `<slug>` is the agent, or the runtime id for a pass-through run.
+
+## `apx run` delegates; `apx send` converses
+
+`apx run` is a ONE-SHOT: the CLI starts cold, does the task, exits. When you want
+a back-and-forth with the CLI instead — ask, read the answer, ask again — address
+it as an a2a peer:
+
+```bash
+apx send <you> opencode "<message>" --deliver
+apx send <you> "opencode#review" "<message>" --deliver   # a second, separate thread
+```
+
+The peer answers on the a2a channel and CONTINUES ITS OWN SESSION between turns
+(`claude -p --resume`, `codex exec resume`, `opencode run --session`); APX keeps
+the id on the thread. So the second message costs one message, not a re-read of
+everything that came before. See the **apx** skill for the full addressing rules.
+
+Use `apx run` when you want the task done and the result back. Use `apx send`
+when the exchange has more than one turn.
 
 ## Resuming an external session
 
@@ -57,7 +89,7 @@ session_id: abc123
 Full resume/get/continue/summarise lives in the **`apx-sessions`** skill. Quick paths:
 
 ```bash
-apx sessions list --engine claude --project iacrmar
+apx sessions list --engine claude --project acme
 apx session resume <id>                          # auto-detects engine
 apx session resume <id> --continue               # spawn native CLI to keep going
 apx session resume <id> --summary                # super-agent summary
@@ -67,6 +99,84 @@ apx session get <id> --any --full                # or --engine claude --tail 16k
 
 See `apx-sessions` for full flag reference, collision handling, and daemon-vs-no-daemon matrix.
 
+## Async relay — reply back into a coding session
+
+Two agents that don't share a live process still need to talk both ways: a coding
+CLI (Claude Code, Codex, …) finishes and asks an APX agent something, the agent
+relays it to the user, the user answers, and the answer has to land back in the
+**same** coding session — with its full context intact. The daemon **cannot**
+inject into a live interactive CLI process, so the model is **mailbox + resume**,
+not a live socket: each round-trip is one headless resume of the session.
+
+**The whole convention is one line: identify your session when you message the
+agent.** A coding session tells the agent who to answer by including its engine
+and session id in the message body — nothing more:
+
+```
+engine=claude session=<your-session-id>
+```
+
+That's the "return address". Any APX agent, on seeing it, knows how to reply.
+
+**The return leg** — how an agent (or you, testing) answers a coding session:
+
+```bash
+# Headless: inject one message into the session's transcript (full context) and
+# capture its reply on stdout. Implies --continue. Claude only for now.
+apx session resume <session-id> --continue --msg "the owner says: go ahead with the tests, don't touch login"
+```
+
+The reply the woken session produces comes back on stdout — the agent relays that
+to the user, and the loop can go around again.
+
+**For an APX agent** (this is a general capability, not one agent's prompt hack):
+when a message carries `engine=claude session=<id>` and the user later answers it,
+run `apx session resume <id> --continue --msg "<user's reply>"` to hand the answer
+back. If you can't resolve the session or the resume fails, tell the user — never
+swallow it.
+
+**If you can't determine your own session id**, say so in the message instead of
+guessing — the agent then starts a fresh run rather than a true resume, and the
+user knows context won't carry.
+
+**The outbound leg** (coding CLI → agent) goes on the **a2a channel**, so the
+agent sees it as agent-to-agent, not as the user typing:
+
+```bash
+apx send <engine> <agent> "…question… engine=claude session=<id>" --deliver --project <name>
+```
+
+The sender does not need to be a registered agent — a coding CLI passes its
+engine name (`claude`, `codex`). If the recipient slug exists in several projects,
+`apx send` lists them; pass `--project`. `apx agent list --all` shows every agent
+with its project. Do NOT use `apx exec` for the hand-off — that posts on the user
+channel (the agent reads it as if the user spoke). `--msg` headless delivery on
+the return leg is claude-only today; other engines print "not supported yet". See
+the **claude-code** skill for the coding-CLI side.
+
+### a2a etiquette — never message the owner directly
+
+An a2a message is another AGENT talking, not the owner. The daemon enforces this
+in the a2a reply prompt, and you should follow it in fuller turns too:
+
+- **Don't ping the owner from an a2a turn.** No `apx telegram send`, no direct
+  owner message. Whether the owner hears about it — and when — is the
+  orchestrator's (Roby / the super-agent's) call, on its own channel, respecting
+  quiet-hours.
+- **Not the orchestrator?** If the message needs the owner's attention or a
+  decision, relay it up: `apx send <you> roby "…" --deliver`. Roby decides how
+  and when to tell the owner. Otherwise just do your part and reply on a2a.
+  - **Tag the urgency** so Roby knows how fast to surface it:
+    `--severity blocker` is a critical alert — Roby pings the owner **in the act**,
+    crossing quiet-hours and the interruption budget (use only for what truly
+    can't wait); `--severity status` / `--severity fyi` is a normal notice that
+    rides the end-of-day digest and never interrupts. Untagged = normal. The
+    `send` result reports `owner_notified` when a `blocker` reached the phone.
+- **Secretary profile active?** Anything promised to / owed to / needing action
+  from the owner must be CAPTURED as a commitment (`record_commitment` /
+  `apx commitment`, with a due date) so it resurfaces at the right time — a lone
+  a2a message is not a reminder, and quiet-hours can swallow a one-off ping.
+
 ## APC_RESULT contract
 
 To capture a structured value from the external runtime, instruct it via the prompt to print on its last line:

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

@@ -1,6 +1,6 @@
 ---
 name: apx-sessions
-description: "Cross-engine session ops (apx, claude, codex, antigravity): find by title, list, get transcript, summarize, ask, resume, continue. Triggers: 'apx session find/ask/summary/resume/get', 'find/resume/summarize session', 'get session transcript', 'continue session in apx'. Not for `apx run` orchestration (use apx skill)."
+description: "Cross-engine session ops (apx, claude, codex, opencode, antigravity): find by title, list, get transcript, summarize, ask, resume, continue. Triggers: 'apx session find/ask/summary/resume/get', 'find/resume/summarize session', 'get session transcript', 'continue session in apx'. Not for `apx run` orchestration (use apx skill)."
 ---
 
 # APX Sessions — cross-engine resume, summary, continuation
@@ -14,6 +14,7 @@ Storage locations APX scans:
 | apx       | `~/.apx/projects/<apx_id>/agents/<slug>/sessions/*.md`    |
 | claude    | `~/.claude/projects/<encoded-cwd>/<id>.jsonl`             |
 | codex     | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`            |
+| opencode  | `~/.local/share/opencode` (also `~/.config/opencode`) — listed via the `opencode` CLI (`session list` / `export`) |
 | antigravity | detected only — listing not implemented yet              |
 
 Uninstalled engines are skipped silently. Detected-but-empty engines print `(sin nada)`.
@@ -77,7 +78,7 @@ Limits of `ask`: binary noise (base64 images) is stripped before chunking. Cover
 ```bash
 apx sessions list                                       # all engines, all projects
 apx sessions list --dir /path/to/repo                   # all engines, one dir (no registration needed)
-apx sessions list --project iacrmar                     # all engines, registered project
+apx sessions list --project acme                     # all engines, registered project
 apx sessions list --engine claude                       # one engine, all projects
 apx sessions list --engine codex --dir /path --limit 10 # one engine, one dir
 ```
@@ -88,7 +89,7 @@ Per engine: `DATE | SESSION ID | TITLE` newest first, plus the native-CLI resume
 
 ## Resuming by id (`apx session resume <id>`)
 
-1. Searches every engine (apx → claude → codex).
+1. Searches every engine (apx → claude → codex → opencode).
 2. **One match** → prints metadata (engine, path, cwd, title).
 3. **Zero matches** → non-zero exit with `session "<id>" not found in any detected engine`.
 4. **Multiple matches** → prints all, exit 2, asks for `--engine <id>`.
@@ -97,7 +98,7 @@ Flags:
 
 | Flag | Effect |
 |------|--------|
-| `--engine <apx\|claude\|codex>` | Skip auto-detection. |
+| `--engine <apx\|claude\|codex\|opencode>` | Skip auto-detection. |
 | `--tail N[k\|m]` | Print last N bytes (e.g. `--tail 32k`). No daemon. |
 | `--full` / `--body` | Dump entire transcript. No daemon. |
 | `--summary` | Tail → super-agent → 4-bullet summary. **Daemon + `super_agent.enabled`.** |
@@ -161,7 +162,7 @@ If the daemon is down, `apx` auto-starts it when needed.
 
 ---
 
-## Native APX session commands (legacy, still useful)
+## Native APX session commands
 
 Manage APX-native sessions (`.md` files in `~/.apx/projects/.../sessions/`). They do **not** see Claude/Codex sessions.
 
@@ -185,7 +186,7 @@ $ apx session resume abc123
 ⚠️  session id "abc123" exists in multiple engines:
   - claude  /Users/.../-Volumes-work-repo/abc123.jsonl  (cwd: /Volumes/work/repo)
   - codex   /Users/.../sessions/2026/05/27/rollout-...-abc123.jsonl  (cwd: /Volumes/work/repo)
-→ re-run with --engine <id> to pick one (apx | claude | codex)
+→ re-run with --engine <id> to pick one (apx | claude | codex | opencode)
 ```
 
 Pick one with `--engine claude` or `--engine codex`.

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

@@ -17,11 +17,13 @@ A **skill** is a Markdown file the super-agent loads on demand. Inspired by Anth
 
 Scanned in priority order:
 
-1. `<repo>/.apc/skills/<slug>/SKILL.md` — project-scoped.
+1. `<repo>/.apc/skills/<slug>/SKILL.md` (or flat `<slug>.md`) — project-scoped.
 2. `~/.apx/skills/<slug>/SKILL.md` — user-global.
-3. `<repo>/skills/<slug>/SKILL.md` in the APX source — bundled.
+3. `<packageRoot>/src/core/runtime-skills/<slug>/SKILL.md` — the runtime-internal set that ships with APX (the built-in `apx-*`, `apc-context`, `claude-code`, …). This is where a new super-agent skill goes.
 
-Layouts: `<slug>/SKILL.md` (dir-style, preferred — supports `references/`, `assets/`) or `<slug>.md` (flat, fine for short).
+> ⚠️ `<repo>/skills/` is **NOT** in the super-agent's load chain (see `src/core/agent/skills/loader.js:23`). That folder is the slim engine-side set replicated to external CLIs/IDEs (`~/.claude/skills/`, `~/.codex/skills/`). A skill authored there will never load for the super-agent — put it under `src/core/runtime-skills/`.
+
+Layouts: `<slug>/SKILL.md` (dir-style, preferred — supports `references/`, `assets/`) or `<slug>.md` (flat, fine for short — project scope only).
 
 ## Frontmatter
 
@@ -40,7 +42,7 @@ scope: public   # public (synced globally) | internal (repo/dev-only) | optional
 
 ## Body style
 
-Opinionated, concrete, anti-example-driven. Read a sibling `skills/apx-*` before writing yours. Shape:
+Opinionated, concrete, anti-example-driven. Read a sibling `src/core/runtime-skills/apx-*` before writing yours. Shape:
 
 1. **One-paragraph "what this is"** — no preamble.
 2. **Concrete CLI calls** — most common first.
@@ -69,13 +71,13 @@ apx skills status        # what's installed vs available
 
 ```bash
 # 1. Pick scope:
-#    .apc/skills/<slug>/SKILL.md   (project)
-#    ~/.apx/skills/<slug>/SKILL.md (user-global)
-#    skills/<slug>/SKILL.md        (bundled, in repo)
+#    .apc/skills/<slug>/SKILL.md                     (project)
+#    ~/.apx/skills/<slug>/SKILL.md                   (user-global)
+#    src/core/runtime-skills/<slug>/SKILL.md         (runtime-internal, ships with APX)
 
 # 2. Write
-mkdir -p skills/my-thing
-$EDITOR skills/my-thing/SKILL.md
+mkdir -p src/core/runtime-skills/my-thing
+$EDITOR src/core/runtime-skills/my-thing/SKILL.md
 
 # 3. Verify (daemon picks up on next listSkills() — no restart)
 apx skills list | grep my-thing
@@ -98,13 +100,13 @@ name: vague-stuff
 # Teach the decision tree ("shared vs runtime", "what to do if it fails").
 
 # DON'T leave TODOs in production skills. Delete incomplete sections;
-# move them to spec/backlog/.
+# move them to spec/active/backlog/ (local-only).
 ```
 
 ## Optional scaffolding
 
 ```
-skills/my-thing/
+src/core/runtime-skills/my-thing/
 ├── SKILL.md           ← always
 ├── references/        ← markdown the skill cites
 ├── assets/            ← images, schemas, sample inputs
@@ -115,11 +117,11 @@ Only `SKILL.md` is auto-loaded. Reference others by relative path from the body
 
 ## Existing skills — mimic the style
 
-`skills/apx-routine`, `apx-mcp`, `apx-task`, `apx-telegram`, `apx-runtime`, `apx-sessions`, `apx-voice`, `apx-agent`, `apx-project`. Pick the closest topic, copy the structure.
+`src/core/runtime-skills/apx-routine`, `apx-mcp`, `apx-integrations`, `apx-task`, `apx-telegram`, `apx-runtime`, `apx-sessions`, `apx-voice`, `apx-agent`, `apx-project`. Pick the closest topic, copy the structure.
 
 ## Maintainer contract
 
-`AGENTS.md` rule 6 (regenerated by `apx agent add/import`) requires skills to move in lockstep with feature changes. Update or add the skill in the same PR as the behavior change — especially `skills/apx-*`.
+The dev guide `AGENTS.md` (repo root) rule 6 requires skills to move in lockstep with feature changes. Update or add the skill in the same PR as the behavior change — especially `src/core/runtime-skills/apx-*`.
 
 ## Don't
 

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

@@ -1,6 +1,6 @@
 ---
 name: apx-task
-description: Per-project TODO list. Event-sourced, project-scoped, addressable by short id prefix. Load when user wants to note, remind, list, or complete a task. Triggers: 'add a task', 'remind me to…', 'what's pending', 'mark as done', 'open tasks'.
+description: Per-project TODO list with subtasks, comments and a board. Event-sourced, project-scoped, addressable by short id prefix. Load when user wants to note, remind, list, complete, split or comment on a task. Triggers: 'add a task', 'remind me to…', 'what's pending', 'mark as done', 'open tasks', 'split this task', 'subtask', 'comment on the task', 'move it to QA'.
 ---
 
 # apx-task
@@ -11,30 +11,33 @@ A `task` is a per-project TODO. Append-only JSONL event log per month at `~/.apx
 
 ```bash
 # Add
-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
+apx task add "Review the auth bug" --project acme
+apx task add "Llamar al contador" --project casa --description "Antes del viernes, por el monotributo"
+apx task add "Rotar las claves" --project acme --body "Rotate every API key in .env and open a PR" --agent ops
+apx task add "Call the client" --project acme --due 2026-05-30 --tag urgent
+apx task add "Demo for tester X" --project acme --agent reviewer --tag demo --tag external --source cli
 
 # List (defaults to open)
-apx task list --project iacrmar
+apx task list --project acme
 apx task list --all                          # every registered project, each row labelled
 apx task list --all --status blocked         # what is stuck, everywhere
 apx task list --all --updated-since 2026-08-01T00:00:00Z   # what moved
-apx task list --project iacrmar --status in_review
-apx task list --project iacrmar --state all
-apx task list --project iacrmar --state done
-apx task list --project iacrmar --tag urgent
-apx task list --project iacrmar --due-before 2026-06-01
-apx task list --project iacrmar --limit 5
+apx task list --project acme --status in_review
+apx task list --project acme --state all
+apx task list --project acme --state done
+apx task list --project acme --tag urgent
+apx task list --project acme --due-before 2026-06-01
+apx task list --project acme --limit 5
 
 # Inspect / mutate
-apx task show t_abc123 --project iacrmar
-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 "New title" --due 2026-06-10
-apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces tags
+apx task show t_abc123 --project acme
+apx task show abc       --project acme    # prefix match (≥3 chars, unique)
+apx task done    t_abc123 --project acme --by manuel
+apx task drop    t_abc123 --project acme               # archived (not "done")
+apx task reopen  t_abc123 --project acme
+apx task patch   t_abc123 --project acme --title "New title" --due 2026-06-10
+apx task patch   t_abc123 --project acme --description "Lo que tengo que hacer yo"
+apx task patch   t_abc123 --project acme --tag bug --tag blocker   # replaces tags
 ```
 
 ## ID format
@@ -46,23 +49,71 @@ apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces
 | Field | When | Notes |
 |---|---|---|
 | `title` | always | One imperative line. Required. |
-| `body` | optional | Longer notes. Markdown OK. |
+| `description` | optional | **What the OWNER has to do**, in their words. Markdown OK. This is what the panel, the phone and `apx task show` display. Fill it for anything a person will do. |
+| `body` | optional | **The prompt an AGENT receives** if it runs the task. Only for tasks meant to be executed by an agent — leave it empty for a plain to-do. |
 | `tags` | optional | Free-form. Used by `--tag` filter. |
-| `due` | optional | ISO `YYYY-MM-DD`. Supports `--due-before`. |
+| `due` | optional | ISO `YYYY-MM-DD`. Filter with `--due-before` / `--due-after`. |
 | `agent` | optional | Slug of responsible agent. Used by `--agent` filter. |
 | `source` | auto/optional | Origin (cli, telegram, super-agent). |
-| `state` | derived | `open` after create, `done`/`dropped` after ops. |
+| `state` | derived | Storage lifecycle: `open` after create, `done`/`dropped` after ops. |
+| `status` | sub-status | Which BOARD COLUMN an **open** task sits in. Ships as `pending` (default) \| `running` \| `in_review` \| `blocked`, but the column catalog is configurable — call `GET /api/projects/:pid/tasks/columns` for what THIS project actually has. Orthogonal to `state`. Set via `POST …/tasks/:id/status` (the CLI `patch` does not set it). |
+| `parent` | optional | Id of a parent task. **A subtask is a task with a parent** — same store, same verbs, so it can be assigned, moved and closed on its own. |
+| `comments` | derived | The task's thread, oldest first. Present on `show`/`GET one`; list rows carry `comment_count` instead. |
+
+## Subtasks — splitting a task that is really several
+
+One row that bundles five requirements cannot be handed out, moved to QA, or
+ticked off in pieces. Split it: keep the parent as the epic and add a subtask
+per real unit of work.
+
+```bash
+apx task list --project acme --parent t_epic123   # its children
+apx task list --project acme --parent ""          # only top-level tasks
+```
+
+With the tool: `create_task({ project, title, parent: "t_epic123" })`.
+
+## Comments, and handing a task to an agent
+
+```
+POST /api/projects/:pid/tasks/:id/comments   { text }
+```
+
+**An @mention in a comment summons that agent.** It runs a REAL turn with its
+own tools against the task, and its reply is posted back as another comment —
+so "@qa probá el flujo de login" is a QA run, not a note. Agent→agent handovers
+(`@dev` inside QA's reply) cascade, are mirrored onto the a2a ledger, and stop
+at a ceiling of 4 replies per comment so a mention loop cannot run away.
+
+The `comment_task` tool writes a comment but **summons nobody** — that is
+deliberate: only the owner's comment, and the cascade already running under its
+ceiling, can start a turn. To hand work over, name the agent in your reply.
+
+## Board columns
+
+One catalog for every project (`config.tasks.columns`), and each project shows
+an ordered subset (`.apc/config.json` → `tasks.columns`). `done` is always the
+last column and is not in the catalog — closing a task is `POST …/done`, not a
+status. A column may carry `on_enter: { agent, instruction }`: a task landing
+there is handed to that agent through the same comment path as an @mention.
+
+```bash
+GET  /api/tasks/columns                  # the global catalog
+GET  /api/projects/:pid/tasks/columns    # what this project shows, + the catalog
+```
 
 ## Super-agent tools
 
-The super-agent has `create_task` and `list_tasks`. "Note that we need to close the auth bug in iacrmar tomorrow" → model calls:
+The super-agent has `create_task`, `list_tasks`, **`complete_task`** (done | drop | reopen | status) and **`comment_task`**. Add, list, and close all happen with tools — no shelling out to `apx task done`. "Note that we need to close the auth bug in acme tomorrow" → model calls:
 
 ```json
 { "name": "create_task",
-  "arguments": { "project": "iacrmar", "title": "Close the auth bug", "due": "<tomorrow>", "tags": ["bug"] } }
+  "arguments": { "project": "acme", "title": "Close the auth bug", "description": "The 401 on refresh — reproduce it first", "due": "<tomorrow>", "tags": ["bug"] } }
 ```
 
-"What's pending in iacrmar?" → `list_tasks({ project: "iacrmar" })`. If user doesn't say which project, `list_projects` first and ask — never assume. If the channel has pinned project context (Telegram), use that.
+**`description` vs `body`.** `description` is for the person; `body` is the prompt an agent receives. Most tasks the owner dictates are the first kind — write the description and leave `body` empty. Putting a prompt where the description belongs is what turns a to-do list into a queue of jobs its owner cannot read.
+
+"What's pending in acme?" → `list_tasks({ project: "acme" })`. If user doesn't say which project, `list_projects` first and ask — never assume. If the channel has pinned project context (Telegram), use that.
 
 ## Anti-examples
 
@@ -79,14 +130,16 @@ apx task drop t_abc            # "no longer needed; archive without completion"
 ## Endpoint surface
 
 ```
-GET    /api/projects/:pid/tasks                  ?state=open|done|dropped|all&tag=X&agent=Y&due_before=ISO&limit=N
+GET    /api/tasks                                cross-project; same filters, plus ?offset
+GET    /api/projects/:pid/tasks                  ?state=open|done|dropped|all&status=pending|running|in_review|blocked&tag=X&agent=Y&due_before=ISO&due_after=ISO&updated_since=ISO&limit=N
 POST   /api/projects/:pid/tasks                  { title, body?, tags?, due?, agent?, source?, meta? }
 GET    /api/projects/:pid/tasks/:id
 PATCH  /api/projects/:pid/tasks/:id              { patch: {...} }
 POST   /api/projects/:pid/tasks/:id/done         { by? }
 POST   /api/projects/:pid/tasks/:id/drop         { by? }
 POST   /api/projects/:pid/tasks/:id/reopen
-GET    /api/projects/:pid/tasks-summary          → { open, done, dropped, overdue, total }
+POST   /api/projects/:pid/tasks/:id/status       { status: pending|running|in_review|blocked }
+GET    /api/projects/:pid/tasks-summary          → { open, done, dropped, overdue, total, status:{…} }
 ```
 
 ## Don't

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

@@ -1,6 +1,6 @@
 ---
 name: apx-telegram
-description: APX Telegram plugin — channels, project pinning, master agents, media. Load BEFORE configuring a new bot or routing — multi-channel is the only mode, root bot_token/chat_id are legacy.
+description: APX Telegram plugin — channels, project pinning, master agents, media. Load BEFORE configuring a new bot or routing — channels[] is the only place credentials live.
 ---
 
 # apx-telegram
@@ -21,7 +21,7 @@ APX polls `getUpdates` and routes messages. Config: `~/.apx/config.json → tele
         "name": "default",
         "bot_token": "<from BotFather>",
         "chat_id": "<numeric chat id>",
-        "project": "iacrmar",          // optional: pin to project
+        "project": "acme",          // optional: pin to project
         "route_to_agent": "reviewer",  // optional: per-channel agent
         "respond_with_engine": true,   // optional: override global
         "owner_user_id": "123456789"   // optional: via `apx telegram owner`
@@ -33,19 +33,19 @@ APX polls `getUpdates` and routes messages. Config: `~/.apx/config.json → tele
 }
 ```
 
-Root `telegram.bot_token` / `telegram.chat_id` are **legacy**. Don't write them. If a config still has them and `channels[]` is empty, APX migrates them into `channels[0]` automatically on first read.
+Root `telegram.bot_token` / `telegram.chat_id` are **not read**. APX drops them on load, so a token written there silently does nothing — always use `channels[]`. With `channels[]` empty, APX polls one implicit `default` channel using `BOT_TELEGRAM_TOKEN` / `TELEGRAM_CHAT_ID` from the environment.
 
 ## Concrete CLI calls
 
 ```bash
-apx telegram setup            # template (still emits legacy root fields — prefer channels[])
+apx telegram setup            # prints the config template (channels[] shape)
 
 # Channels CRUD
 apx telegram channel add                  # interactive
-apx telegram channel add clientes --bot-token <T> --chat-id <C> --project iacrmar --agent reviewer
+apx telegram channel add clientes --bot-token <T> --chat-id <C> --project acme --agent reviewer
 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 --project acme
 apx telegram channel set    clientes --agent reviewer
 apx telegram channel set    clientes --respond-engine false
 apx telegram channel unset  clientes --project --agent
@@ -85,20 +85,20 @@ Every `channel` CRUD write triggers `POST /api/admin/reload` so polling picks up
 
 ## What "pin to project" does
 
-On a message to a channel with `project: "iacrmar"`:
-1. The super-agent invocation gets `channelMeta.projectId = <iacrmar's id>`.
+On a message to a channel with `project: "acme"`:
+1. The super-agent invocation gets `channelMeta.projectId = <acme's id>`.
 2. The system prompt resolves project-scoped agents, MCPs, memory.
-3. Tools (`list_agents`, `list_tasks`, `create_task`, …) default to that project — no need to repeat "in iacrmar" each message.
+3. Tools (`list_agents`, `list_tasks`, `create_task`, …) default to that project — no need to repeat "in acme" each message.
 
 ## What "master agent" does
 
-With `route_to_agent: "reviewer"`, messages go through `/api/projects/:pid/agents/reviewer/chat` instead of `/api/super-agent/chat`. The agent's `AGENT.md` + memory is used. No tools (project agents are `exec_agent`-shaped — text in, text out). Single LLM call. Use this for persona channels (reviewer, sales, support) instead of the general assistant. Empty = super-agent (default).
+With `route_to_agent: "reviewer"`, an incoming message is dispatched to that project agent instead of the super-agent. Routing is **in-process** — `src/core/channels/telegram/dispatch.js` reads the agent and makes a single `callEngine` with the agent's `AGENT.md` + memory (there is no per-request `agents/:slug/chat` HTTP route). No tools: text in, text out. Use this for persona channels (reviewer, sales, support) instead of the general assistant. Empty = super-agent (default).
 
 ## Anti-examples
 
 ```bash
-# DON'T write to legacy root fields.
-apx config set telegram.bot_token "<T>"   # ← use channels[] via `apx telegram channel`
+# DON'T write to the root fields — they are dropped on load.
+apx config set --global telegram.bot_token "<T>"   # ← use channels[] via `apx telegram channel`
 
 # DON'T expect routing magic from same project on two channels.
 # A channel pins messages TO a project, not vice-versa. Same project from multiple

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

@@ -0,0 +1,56 @@
+---
+name: apx-transcribe
+scope: optional
+description: Transcribe audio and video files to text from the command line with `apx transcribe`, using the daemon's built-in Whisper. Load when asked to transcribe a voice note, an audio clip, or a video's speech, to batch-transcribe a folder, to pipe transcription into a script, or when choosing between the local, cloud, or a networked custom STT engine.
+---
+
+# apx-transcribe
+
+`apx transcribe` is a thin CLI over the daemon's speech-to-text engine — the same persistent `whisper-server.py` that powers the desktop overlay and Telegram voice notes (`core/voice/transcription.js`). The model is preloaded at daemon boot, so calls hit a warm server and stay fast. This is the fastest way to turn a file on disk into text without writing any HTTP.
+
+## Usage
+
+```bash
+apx transcribe nota.oga                 # transcript to stdout, nothing else
+apx transcribe reunion.mp4              # video: the audio track is extracted
+apx transcribe a.wav b.m4a c.mp3        # bulk: one "── name ──" block per file
+apx transcribe ./notas-de-voz/          # every audio/video file in a folder
+apx transcribe voz.webm --lang es       # pin the language (else auto-detect)
+apx transcribe *.mp3 --json > out.json  # machine-readable array
+cat clip.wav | apx transcribe -         # read audio from stdin
+```
+
+## Formats
+
+Audio: `webm`, `ogg`/`oga`, `opus`, `m4a`, `aac`, `mp3`, `wav`, `flac`. Video: `mp4`, `mov`, `mkv`, `m4v`, `avi`, `3gp` and more. The daemon shells out to `ffmpeg`, which probes the real container from the bytes and pulls the audio track out of a video — so the extension is only a hint, and a mislabelled file still works.
+
+## Provider routing (`--provider`)
+
+The `--provider` flag overrides the configured STT routing for one call:
+
+| id | What it is |
+|---|---|
+| `local`  | The embedded Whisper. On Apple Silicon it runs on `mlx` (Metal GPU), on NVIDIA on `faster-whisper` cuda, else CPU — picked automatically. |
+| `openai` | Cloud Whisper (`whisper-1`). Needs `OPENAI_API_KEY` or `engines.openai.api_key`. |
+| `custom` | Any OpenAI-compatible STT server reachable over the network — mlx-audio on this Mac, a Radeon/NVIDIA box on the LAN, or a remote endpoint. Configured under `transcription.custom.base_url`. |
+
+Default routing lives in `~/.apx/config.json` under `transcription.provider` (`auto` tries local first, falls back to OpenAI if a key is set).
+
+## Output contract (why it is scriptable)
+
+- **One file** → the bare transcript on **stdout**, one trailing newline. Pipe-friendly: `apx transcribe x.oga | pbcopy` copies clean text.
+- **Many files / a folder** → a `── filename ──` header before each transcript.
+- **`--json`** → the full result object (`text`, `language`, `backend`, `model`, …) for one file, or an array of `{file, ...}` in bulk.
+- The `▸ APX CLI` banner always goes to **stderr**, never stdout.
+- Bulk runs **sequentially** (the local model is single-instance) and keeps going past a failed file, exiting non-zero if any failed.
+
+## How it works
+
+The CLI reads the file bytes and POSTs them to the daemon's `POST /api/transcribe/chunk` with `X-Audio-Format`, `X-Language`, and optional `X-Provider` headers. That endpoint is the shared "any external caller" entry point, so a routine's `pre_command`, a hook, or a plain shell script all get the same warm engine without spawning their own Whisper. Long media is allowed up to 20 minutes per request.
+
+## Don't
+
+- Don't spin up a separate Whisper process or a Python script to transcribe — the daemon already runs a warm one; `apx transcribe` reuses it. A parallel instance just fights for the GPU.
+- Don't restart the daemon to "load" the model before transcribing — it is preloaded at boot, and the endpoint lazily re-spawns it after the idle-shutdown anyway.
+- Don't pre-extract audio from a video before transcribing it — pass the video directly; the daemon's ffmpeg handles the audio track.
+- Don't parse the human transcript when you need fields — use `--json` and read `text`, never scrape stdout for the language or model.