@agentprojectcontext/apx 1.24.0 → 1.27.1

package/skills/apx-sessions/SKILL.md

@@ -0,0 +1,281 @@
+---
+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."
+---
+
+# APX Sessions — cross-engine resume, summary, and continuation
+
+APX treats every supported engine (apx, claude, codex, antigravity) as a session store. The commands in this skill let you list, read, summarize, and continue sessions **without caring which engine owns them**.
+
+Engine storage locations APX scans:
+
+| Engine    | Where APX looks                                           |
+|-----------|-----------------------------------------------------------|
+| apx       | `~/.apx/projects/<apx_id>/agents/<slug>/sessions/*.md`    |
+| claude    | `~/.claude/projects/<encoded-cwd>/<id>.jsonl`             |
+| codex     | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`            |
+| antigravity | detected only — listing not implemented yet              |
+
+Engines not installed on the machine are silently skipped. Detected-but-empty engines show `(sin nada)`.
+
+---
+
+## The discovery flow (read this first)
+
+You almost never start with a session id — you start with a vague memory of a *title* ("the one about improving the web UI"). Do **not** hand-roll `apx sessions list ... | grep`. The flow is three commands:
+
+```bash
+# 1. Turn a remembered title into an id (cross-engine, newest first)
+apx session find "mejorar interfaz web"
+
+# 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?"
+```
+
+`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.**
+
+---
+
+## Finding a session by title or content (`apx session find`)
+
+```bash
+apx session find "<text>"                      # match titles across every engine
+apx session find "<text>" --deep               # also search inside transcript content
+apx session find "<text>" --engine codex       # restrict to one engine
+apx session find "<text>" --dir /path/to/repo  # scope to one project (reaches unregistered Claude projects)
+apx session find "<text>" --limit 10 --json    # cap results / machine-readable
+```
+
+- Default search is **title-only** (fast — titles are already indexed per engine).
+- `--deep` reads each candidate transcript off disk and greps its content too. Slower; prefer combining it with `--engine`/`--dir` scope.
+- Output is one row per match — `DATE | ENGINE | SESSION ID | TITLE` — newest first, followed by ready-to-run `summary`/`ask`/`resume` commands.
+
+**Coverage caveat:** an engine can only be enumerated when APX can resolve a project's working directory. Codex always records it; APX uses registered projects; **Claude only lists folders that map back to a registered APX project** (its folder names are a lossy encoding of the cwd). If a Claude session is missing, scope with `--dir <path>` to reach it.
+
+---
+
+## Summarizing a session (`apx session summary`)
+
+```bash
+apx session summary <id>                  # auto-detect engine, print an LLM summary
+apx session summary <id> --engine claude  # skip auto-detect
+apx session summary <id> --max-chunks 8   # bound cost on a huge transcript
+```
+
+This is the discoverable alias for `apx session resume <id> --summary`. It resolves the owning engine, then prints a 4-bullet summary plus next steps. **Requires the daemon + `super_agent.enabled`.**
+
+---
+
+## Asking questions about a session (`apx session ask`)
+
+```bash
+apx session ask <id> "¿qué decidimos sobre el sidebar?"
+apx session ask <id> "what files were changed?" --max-chunks 30
+```
+
+RAG-lite Q&A over the transcript. Small transcripts are answered in one shot; large ones are **map-reduced**: each ~48 KB part is mined for question-relevant notes, then a final pass synthesizes the answer. **Requires the daemon + `super_agent.enabled`.**
+
+How it works and its limits:
+
+- Binary noise (base64 image payloads, which can be the majority of a JSONL transcript) is stripped before chunking.
+- Coverage is capped at `--max-chunks` (default 20 ≈ ~960 KB). Bigger transcripts print a truncation warning — raise `--max-chunks` for full coverage at the cost of more (sequential) model calls.
+- Speed scales with transcript size: a typical session answers in seconds; a multi-MB Codex rollout can take a couple of minutes.
+- Output quality depends on the configured `super_agent.model`. Small/cheap models that "think" (e.g. gemini-2.5-flash) can return thin answers; the command already requests a raised output budget to compensate.
+
+---
+
+## Listing sessions
+
+```bash
+# Every detected engine, every known project — broadest view
+apx sessions list
+
+# Every engine, scoped to one directory (no need for it to be a registered APX project)
+apx sessions list --dir /path/to/repo
+apx sessions list --project iacrmar          # uses a registered APX project's path
+
+# One engine, all projects
+apx sessions list --engine claude
+apx sessions list --engine codex
+
+# One engine, one project
+apx sessions list --engine claude --project iacrmar
+apx sessions list --engine codex  --dir /path/to/repo --limit 10
+```
+
+Output format per engine: `DATE | SESSION ID | TITLE`, newest first, plus the exact native-CLI resume command at the bottom.
+
+When no `--engine` is passed, output is grouped by engine with `══ <Engine> ══` headers. Empty engines print `(sin nada)`; un-installed engines are not listed at all.
+
+---
+
+## Resuming a session by id (the headline command)
+
+```bash
+apx session resume <id>
+```
+
+What it does, in order:
+
+1. Searches every detected engine for `<id>` (apx → claude → codex).
+2. **One match** → prints metadata: engine, file path, cwd, title.
+3. **Zero matches** → exits non-zero with `session "<id>" not found in any detected engine`.
+4. **Multiple matches (collision)** → prints all of them and exits with code 2, telling you to re-run with `--engine <id>`.
+
+Then it applies any of the following flags:
+
+| Flag | Effect |
+|------|--------|
+| `--engine <apx\|claude\|codex>` | Restrict the search to one engine (skip auto-detection). |
+| `--tail N[k\|m]` | Print last N bytes of the transcript (e.g. `--tail 32k`). No daemon required. |
+| `--full` / `--body` | Dump the entire transcript. No daemon required. |
+| `--summary` | Send the tail to the APX super-agent and print a 4-bullet summary. **Requires daemon + `super_agent.enabled`.** |
+| `--continue` | Spawn the engine's native CLI in resume mode (`claude --resume <id>`, `codex resume <id>`) in the recorded cwd. |
+| `--into apx[:slug]` | Create a brand-new APX session whose body is the summary of `<id>`. Frontmatter records `parent_session: <engine>:<id>` for lineage. Default slug = the session's original APX agent if any, else the first agent in `AGENTS.md`. |
+| `--project <name\|id\|path>` | Used only for `--summary` on apx-native sessions (picks the daemon project). |
+
+### Common recipes
+
+```bash
+# "I have a Codex session id, give me a summary in apx"
+apx session resume 019abc... --summary
+
+# "I want to keep working on that Codex thread, but in APX with the reviewer agent"
+apx session resume 019abc... --summary --into apx:reviewer
+
+# "Just dump the full transcript so I can grep it"
+apx session resume 019abc... --full | rg "TODO"
+
+# "Re-open in the native CLI, interactively"
+apx session resume 019abc... --continue
+
+# "I know it's a Claude session, skip auto-detect"
+apx session resume 2e3c840b-... --engine claude --tail 16k
+```
+
+---
+
+## Reading a session's content (`apx session get`)
+
+`apx session get` is the "fetch and read" command. It has two modes:
+
+### Default mode — local APC project sessions
+
+```bash
+apx session get <id>             # metadata of the local APC session
+apx session get <id> --body      # full markdown body
+apx session get <id> --json      # machine-readable metadata
+```
+
+### Engine mode — read any engine's session by id
+
+```bash
+apx session get <id> --engine claude --full       # full Claude JSONL
+apx session get <id> --engine codex  --tail 16k   # last 16 KB of a Codex rollout
+apx session get <id> --any --full                  # search every engine, error on collision
+apx session get <id> --engine claude --json        # JSON metadata only
+```
+
+**This is the command you want when you're inside Claude and need to ingest a Codex/Claude session as context.** Pipe `--full` into a file or directly into your prompt.
+
+```bash
+# Pull a Codex session into context for the current Claude session
+apx session get 019abc... --engine codex --full > /tmp/prev.jsonl
+```
+
+---
+
+## Daemon vs. no daemon
+
+| Capability | Daemon required? |
+|------------|------------------|
+| `apx session find ...` | ❌ no |
+| `apx sessions list ...` | ❌ no |
+| `apx session get ...` (any mode) | ❌ no |
+| `apx session resume <id>` (metadata only) | ❌ no |
+| `apx session resume <id> --tail / --full` | ❌ no |
+| `apx session resume <id> --continue` | ❌ no |
+| `apx session resume <id> --summary` / `apx session summary <id>` | ✅ yes (daemon + `super_agent.enabled` in `~/.apx/config.json`) |
+| `apx session ask <id> "<q>"` | ✅ yes (daemon + `super_agent.enabled`) |
+| `apx session resume <id> --into apx[:slug]` | ⚠️ daemon needed only to compute the summary it embeds; without it, the new session is created with an empty summary block |
+
+If the daemon is down, `apx` auto-starts it when needed.
+
+---
+
+## Native APX session commands (legacy / still useful)
+
+These manage APX-native sessions (the `.md` files in `~/.apx/projects/.../sessions/`). They do **not** see Claude/Codex sessions.
+
+```bash
+apx session new <slug> --title "Investigate bug X"
+apx session list                       # all agents in the current APC project
+apx session list <slug>                # one agent
+apx session update <id> --status "in progress"
+apx session close <id> --result "Fixed in PR #42"
+apx session check                      # exit 1 if any APX session is still open
+apx session close-stale                # auto-close sessions older than 1h
+apx session compact <slug>             # summarize a conversation durable to disk
+```
+
+These live next to the new cross-engine commands above; they don't replace each other.
+
+---
+
+## Disambiguating collisions
+
+If two engines happen to use the same id string for different sessions:
+
+```
+$ 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-2026-05-27T10-00-00-abc123.jsonl  (cwd: /Volumes/work/repo)
+→ re-run with --engine <id> to pick one (apx | claude | codex)
+```
+
+Pick one with `--engine claude` or `--engine codex` and run again.
+
+---
+
+## Tips for callers (LLMs)
+
+1. **Start with `find`, not grep.** If the user describes a session by topic instead of id, run `apx session find "<text>"`. Never reconstruct this with `apx sessions list | grep` — that's the exact footgun this command replaces.
+2. **Don't ask the user which engine.** Auto-detect handles it. If the CLI prints a collision message, *then* re-run with `--engine`.
+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".
+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.
+
+---
+
+## Quick reference card
+
+```bash
+# Discovery
+apx session find "<text>"                          # find by title across engines (start here)
+apx session find "<text>" --deep                   # also search transcript content
+apx sessions list                                  # all engines, all projects
+apx sessions list --project <name>                 # all engines, one project
+apx sessions list --engine <id> --dir <path>       # one engine, one dir
+
+# Understand
+apx session summary <id>                           # LLM summary of any session
+apx session ask <id> "<question>"                  # Q&A over the transcript (map-reduced)
+
+# Read
+apx session get <id>                               # local APC session metadata
+apx session get <id> --engine <id> --full          # any engine, full transcript
+apx session get <id> --any --tail 32k              # any engine, last 32 KB
+
+# Resume / continue
+apx session resume <id>                            # auto-detect engine, show metadata
+apx session resume <id> --summary                  # add super-agent summary
+apx session resume <id> --continue                 # spawn native CLI to keep working
+apx session resume <id> --into apx:<slug>          # seed a new APX session with the summary
+```

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

@@ -0,0 +1,149 @@
+---
+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.
+---
+
+# apx-skill-builder
+
+A **skill** in APX is a Markdown file the super-agent loads on demand to learn how to do something. Inspired by Anthropic's skill-creator pattern, simplified for APX's daemon-served model.
+
+## When to make a skill (vs. inlining in the system prompt)
+
+- **Make a skill** when the topic is bounded (a tool, a config domain, a recurring workflow), the instructions need >50 tokens to be safe, and not every conversation needs them.
+- **Don't** make a skill for one-off explanations, casual chat, or stuff that fits in 2-3 lines in the base prompt.
+
+## File location
+
+Three places APX scans, in priority order:
+
+1. `<repo>/.apc/skills/<slug>/SKILL.md` — project-scoped (only this project's super-agent sees it).
+2. `~/.apx/skills/<slug>/SKILL.md` — user-global (all projects).
+3. `<repo>/skills/<slug>/SKILL.md` in the APX source — bundled (ships with the package).
+
+Either layout works:
+- `<slug>/SKILL.md` (dir-style, preferred — lets you ship `references/`, `assets/`, etc.)
+- `<slug>.md` (flat-style, fine for short ones)
+
+## Frontmatter
+
+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` is what the model sees when deciding whether to call `load_skill`. Write it as the *trigger condition*, not a summary of the body.
+
+**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).
+
+## Body style
+
+Opinionated, concrete, anti-example-driven. Every other APX skill in `skills/apx-*` follows the same shape — read one before writing yours:
+
+1. **One-paragraph "what this is"** (no preamble, no marketing).
+2. **Concrete CLI calls** the user runs, with the most common case first.
+3. **Schema / shape** if the topic involves files or config.
+4. **Anti-examples** — at least one "DON'T do this" with the reason. This is what stops the model from inventing flags.
+5. **Open questions / footnotes** if the surface is incomplete.
+
+Length budget: 80-200 lines. If it's longer, split into sub-skills or move scripts into `<slug>/scripts/`.
+
+## How the super-agent loads it
+
+```js
+// The model emits a tool call:
+load_skill({ slug: "my-skill", project_path: "/abs/path/optional" })
+```
+
+That returns the full body. The agent uses the content in-context for that turn; it doesn't persist.
+
+The user can list installed skills with:
+```bash
+apx skills list
+apx skills list --project iacrmar
+```
+
+## Workflow: create + register
+
+```bash
+# 1. Pick scope
+#    Project-scoped:   .apc/skills/<slug>/SKILL.md
+#    User-global:      ~/.apx/skills/<slug>/SKILL.md
+#    Bundled (in repo): skills/<slug>/SKILL.md
+
+# 2. Write the file
+mkdir -p skills/my-thing
+$EDITOR skills/my-thing/SKILL.md
+
+# 3. The daemon picks it up on next listSkills() — no restart needed unless
+#    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"
+```
+
+## Anti-examples
+
+```yaml
+---
+# DON'T omit description — the model can't trigger on the slug alone.
+name: vague-stuff
+---
+
+# DON'T pile general advice into the body. Pick ONE topic per skill.
+# A skill that says "lots of useful tips about everything" is dead weight
+# in the model's mental cache.
+
+# DON'T duplicate apx --help. Skills explain WHEN and WHY, not just WHAT.
+# `apx mcp add --help` already lists flags. The skill teaches the decision
+# tree ("when shared vs runtime", "what to do if it fails").
+
+# DON'T leave TODOs in production skills. If a section is incomplete,
+# delete it from the skill and add it to spec/backlog/.
+```
+
+## Skill scaffolding (optional `<slug>/`)
+
+```
+skills/my-thing/
+├── SKILL.md           ← the body (always)
+├── references/        ← markdown files the skill cites
+│   └── examples.md
+├── assets/            ← images, JSON schemas, sample inputs
+└── scripts/           ← shell / node scripts the skill may shell out to
+    └── verify.sh
+```
+
+The super-agent only sees `SKILL.md` automatically. `references/` and `scripts/` are addressable via paths from inside the body (e.g. "see references/examples.md"). Use this for skills with lots of supporting material.
+
+## Existing APX skills — copy the style
+
+- `skills/apx-routine/SKILL.md` — routine kind selection + pipeline.
+- `skills/apx-mcp/SKILL.md` — three-scope MCP configuration.
+- `skills/apx-task/SKILL.md` — TODO management.
+- `skills/apx-telegram/SKILL.md` — channel ↔ project ↔ agent wiring.
+- `skills/apx-runtime/SKILL.md` — external CLIs (claude-code, codex, …).
+- `skills/apx-sessions/SKILL.md` — cross-engine list, resume, summary, `--into apx`.
+- `skills/apx-voice/SKILL.md` — TTS engine setup.
+- `skills/apx-agent/SKILL.md` — per-project agents.
+- `skills/apx-project/SKILL.md` — project registration + typology.
+
+Pick the closest topic, mimic the structure, then write yours.
+
+## Maintainer contract
+
+`AGENTS.md` rule 6 (regenerated by `apx agent add/import`) requires skills to move in lockstep with feature changes. When you add or change APX behavior, update or add the skill in the same PR — especially under `skills/apx-*`.
+
+## Don't
+
+- Don't ship a skill without the frontmatter `description` — the loader can read the file but the trigger is silent.
+- Don't put secrets inside skills. They're meant to be read aloud by an LLM.
+- Don't reference filesystem paths that only exist on your machine — use `<repo>` or `~/.apx` placeholders.
+- Don't write skills in third person. The reader is the model. Write to it.

package/skills/apx-task/SKILL.md

@@ -0,0 +1,95 @@
+---
+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.
+---
+
+# apx-task
+
+A `task` is a per-project TODO. Append-only JSONL event log per month under `~/.apx/projects/<apxId>/tasks/YYYY-MM.jsonl`. State is the fold of the event stream. Once created, a task lives forever — `done` and `drop` don't delete events, they record a state transition. `reopen` flips back to `open`.
+
+## Concrete CLI calls
+
+```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
+
+# List (defaults to open)
+apx task list --project iacrmar
+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
+
+# 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 "Nuevo título" --due 2026-06-10
+apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces tags
+```
+
+## ID format
+
+`t_` + 6 base36 chars (32-bit entropy → ~4B keyspace). Prefix matching works once you have ≥ 3 chars and the prefix uniquely identifies a task. If two tasks share a prefix, you get null — use a longer one.
+
+## Fields
+
+| Field | When | Notes |
+|---|---|---|
+| `title` | always | One imperative line. Required. |
+| `body` | optional | Longer notes. Markdown OK. |
+| `tags` | optional | Free-form strings. Used by `--tag` filter. |
+| `due` | optional | ISO date `YYYY-MM-DD`. Listing supports `--due-before`. |
+| `agent` | optional | Slug of an agent responsible. Used by `--agent` filter. |
+| `source` | auto/optional | Where the task came from (cli, telegram, super-agent). |
+| `state` | derived | `open` after create, `done` / `dropped` after their respective ops. |
+
+## 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:
+
+```json
+{ "name": "create_task",
+  "arguments": { "project": "iacrmar", "title": "Cerrar bug de auth", "due": "<tomorrow>", "tags": ["bug"] } }
+```
+
+When the user asks "qué tengo pendiente en 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.
+
+## Anti-examples
+
+```bash
+# DON'T add tasks without --project for real work.
+apx task add "Stuff"            # falls back to first registered project (or default=0)
+# ↑ Will dump into a project you may not have meant. Always --project.
+
+# DON'T use `done` when the task is no longer relevant. Use `drop`.
+apx task done t_abc            # implies "I completed this work"
+apx task drop t_abc            # implies "this is no longer needed; archive without completion"
+# Reporting / metrics distinguish them.
+```
+
+## Endpoint surface
+
+```
+GET    /projects/:pid/tasks                  ?state=open|done|dropped|all&tag=X&agent=Y&due_before=ISO&limit=N
+POST   /projects/:pid/tasks                  { title, body?, tags?, due?, agent?, source?, meta? }
+GET    /projects/:pid/tasks/:id
+PATCH  /projects/:pid/tasks/:id              { patch: {...} }
+POST   /projects/:pid/tasks/:id/done         { by? }
+POST   /projects/:pid/tasks/:id/drop         { by? }
+POST   /projects/:pid/tasks/:id/reopen
+GET    /projects/:pid/tasks-summary          → { open, done, dropped, overdue, total }
+```
+
+## Don't
+
+- Don't use tasks for reminders that need to *fire* — that's a future routine kind (`task-due-notify`, not built yet). Tasks are a list, not a scheduler.
+- Don't depend on `done` deleting the task. It doesn't. The event log stays.
+- Don't grep `~/.apx/projects/<id>/tasks/*.jsonl` for state — use `apx task list` or `getTask()`. The fold logic isn't trivial (later events can override fields).

package/skills/apx-telegram/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: apx-telegram
+description: How APX talks to Telegram — channels, project pinning, master agents, media. Load BEFORE configuring a new bot or routing — multi-channel is the only mode now, the root bot_token/chat_id fields are legacy.
+---
+
+# apx-telegram
+
+APX runs a Telegram plugin that polls `getUpdates` and routes messages. Config lives in `~/.apx/config.json → telegram`. The relationship to remember: **each channel can be pinned to a project and to a master agent**. Messages arriving on a pinned channel automatically run inside that project, optionally handled by a specific agent instead of the default APX super-agent.
+
+## The shape
+
+```json
+{
+  "telegram": {
+    "enabled": true,
+    "poll_interval_ms": 1500,
+    "route_to_agent": "",          // global default master agent (empty = super-agent)
+    "respond_with_engine": true,   // global default for "should the LLM auto-reply?"
+    "channels": [
+      {
+        "name": "default",
+        "bot_token": "<from BotFather>",
+        "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
+      }
+    ]
+  }
+}
+```
+
+The old `telegram.bot_token` / `telegram.chat_id` at the root are **legacy**. Don't write to them. If a config still has them and `channels[]` is empty, APX migrates them into `channels[0]` automatically with a warning on first read.
+
+## Concrete CLI calls
+
+```bash
+# 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 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
+
+# Polling lifecycle (rarely needed — autostart with daemon)
+apx telegram start
+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
+
+# Media (daemon HTTP API — no dedicated CLI subcommand yet)
+curl -X POST http://127.0.0.1:7430/telegram/send_photo \
+  -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
+  -H "Content-Type: application/json" \
+  -d '{"photo":"/abs/path.png","caption":"...","channel":"clientes"}'
+curl -X POST http://127.0.0.1:7430/telegram/send_voice \
+  -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
+  -H "Content-Type: application/json" \
+  -d '{"audio":"/abs/path.ogg","duration":5,"channel":"default"}'
+```
+
+Every `channel` CRUD write triggers `POST /admin/reload` so the polling plugin picks up the new wiring without a daemon restart.
+
+## What "pin to project" actually does
+
+When a message arrives on a channel with `project: "iacrmar"`:
+1. The super-agent invocation gets `channelMeta.projectId = <iacrmar's id>`.
+2. The system prompt resolves project-scoped data (agents, MCPs, memory) for that turn.
+3. The agent can call tools (`list_agents`, `list_tasks`, `create_task`, …) and they default to that project — the user doesn't have to say "in iacrmar" every message.
+
+## What "master agent" actually does
+
+With `route_to_agent: "reviewer"` on the channel, incoming messages go through `/projects/:pid/agents/reviewer/chat` instead of `/super-agent/chat`. The agent's `AGENT.md` system prompt + memory is used. No tools (project agents are `exec_agent`-shaped — text in, text out). Single LLM call.
+
+Use this when you want a Telegram channel to feel like talking to a specific persona (a reviewer, a sales agent, a customer support agent) instead of the general APX assistant.
+
+If `route_to_agent` is empty: the channel goes through the super-agent (default APX mode).
+
+## Anti-examples
+
+```bash
+# DON'T write to telegram.bot_token / telegram.chat_id directly.
+apx config set telegram.bot_token "<T>"
+# ↑ Those fields are legacy. Use channels[] via `apx telegram channel`.
+
+# DON'T add the same project to two channels expecting routing magic.
+# A channel pins messages TO a project, not the other way around. The same
+# project can be addressed from multiple channels — fine. But that doesn't
+# unify the conversation contexts; each channel has its own message log.
+
+# DON'T set route_to_agent to a non-existent slug.
+apx telegram channel set default --agent nope
+# ↑ Will silently route to a 404 — the channel's messages won't get a reply
+# until you fix it. `apx telegram channel show <name>` to verify.
+```
+
+## Multiple bots, one APX
+
+`channels[]` supports multiple `{bot_token, chat_id}` pairs. Each can be a different bot OR the same bot with different chats. The plugin polls each in parallel. Project / agent pinning is per-channel.
+
+This is how you wire "I have a client A bot, a personal bot, and a notifications-only bot": three channels, three (possibly) different bots, distinct project pins.
+
+## Don't
+
+- Don't write to `telegram.bot_token` / `telegram.chat_id` at root.
+- Don't expect `apx telegram send` to target a project — it sends to a *chat id* (or the channel's configured `chat_id`). Use `apx telegram channel show <name>` to verify wiring.
+- Don't set `respond_with_engine: false` and then wonder why messages aren't getting replies. That flag turns auto-reply off for the channel.
+- Don't forget that the Telegram plugin only fires on chat IDs you've listed. Messages from other chats are ignored.