@agentprojectcontext/apx 1.33.1 → 1.35.0

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

@@ -0,0 +1,232 @@
+---
+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)."
+---
+
+# APX Sessions — cross-engine resume, summary, continuation
+
+APX treats every supported engine as a session store. These commands list, read, summarize, and continue sessions **without caring which engine owns them**.
+
+Storage locations APX scans:
+
+| Engine    | Where                                                     |
+|-----------|-----------------------------------------------------------|
+| 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              |
+
+Uninstalled engines are skipped silently. Detected-but-empty engines print `(sin nada)`.
+
+---
+
+## Discovery flow (read first)
+
+You start with a vague title, not an id. Do **not** `apx sessions list | grep`. The flow:
+
+```bash
+# 1. Title → id (cross-engine, newest first)
+apx session find "improve web UI"
+
+# 2. Gist
+apx session summary <id>
+
+# 3. Specifics
+apx session ask <id> "what sidebar changes were left pending?"
+```
+
+`find` prints a "Next:" block with `summary`/`ask`/`resume` pre-filled with the top hit's id. **If tempted to grep session lists, use `find` instead.**
+
+---
+
+## Finding sessions (`apx session find`)
+
+```bash
+apx session find "<text>"                      # titles across every engine
+apx session find "<text>" --deep               # also greps transcript content
+apx session find "<text>" --engine codex       # restrict to one engine
+apx session find "<text>" --dir /path/to/repo  # scope (reaches unregistered Claude projects)
+apx session find "<text>" --limit 10 --json
+```
+
+Default is title-only (fast, indexed). `--deep` reads each candidate transcript off disk; combine with `--engine`/`--dir` to scope. Output rows: `DATE | ENGINE | SESSION ID | TITLE`, newest first, plus ready-to-run `summary`/`ask`/`resume` commands.
+
+**Coverage caveat:** an engine is enumerated only when APX can resolve a project cwd. Codex always records it; APX uses registered projects; **Claude only lists folders mapping to a registered APX project** (encoded folder names are lossy). If a Claude session is missing, scope with `--dir <path>`.
+
+---
+
+## Summarize / Ask
+
+```bash
+apx session summary <id>                  # auto-detect, LLM summary
+apx session summary <id> --engine claude
+apx session summary <id> --max-chunks 8   # bound cost on a huge transcript
+
+apx session ask <id> "what did we decide about the sidebar?"
+apx session ask <id> "what files were changed?" --max-chunks 30
+```
+
+`summary` is the alias for `apx session resume <id> --summary`: resolves engine, prints a 4-bullet summary plus next steps. `ask` is RAG-lite Q&A: small transcripts answer in one shot; large ones are **map-reduced** (each ~48 KB part mined for relevant notes, final pass synthesizes). Both **require the daemon + `super_agent.enabled`**.
+
+Limits of `ask`: binary noise (base64 images) is stripped before chunking. Coverage 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 size (seconds to a couple of minutes). Quality depends on `super_agent.model` — cheap thinking models (e.g. gemini-2.5-flash) can return thin answers.
+
+---
+
+## Listing sessions
+
+```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 --engine claude                       # one engine, all projects
+apx sessions list --engine codex --dir /path --limit 10 # one engine, one dir
+```
+
+Per engine: `DATE | SESSION ID | TITLE` newest first, plus the native-CLI resume command at the bottom. Without `--engine`, output is grouped with `══ <Engine> ══` headers. Empty engines print `(sin nada)`; uninstalled engines are omitted.
+
+---
+
+## Resuming by id (`apx session resume <id>`)
+
+1. Searches every engine (apx → claude → codex).
+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>`.
+
+Flags:
+
+| Flag | Effect |
+|------|--------|
+| `--engine <apx\|claude\|codex>` | 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`.** |
+| `--continue` | Spawn engine's native CLI in resume mode (`claude --resume <id>`, `codex resume <id>`) in recorded cwd. |
+| `--into apx[:slug]` | Create a new APX session whose body is the summary of `<id>`. Frontmatter records `parent_session: <engine>:<id>`. Default slug = original APX agent if any, else first agent in `AGENTS.md`. |
+| `--project <name\|id\|path>` | Only for `--summary` on apx-native sessions. |
+
+### Recipes
+
+```bash
+# Codex id → summary in apx
+apx session resume 019abc... --summary
+
+# Continue a Codex thread inside APX with the reviewer agent
+apx session resume 019abc... --summary --into apx:reviewer
+
+# Dump full transcript and grep
+apx session resume 019abc... --full | rg "TODO"
+
+# Re-open in native CLI
+apx session resume 019abc... --continue
+
+# Known Claude session, skip auto-detect
+apx session resume 2e3c840b-... --engine claude --tail 16k
+```
+
+---
+
+## Reading content (`apx session get`)
+
+```bash
+# Default: local APC project sessions
+apx session get <id>             # metadata
+apx session get <id> --body      # full markdown body
+apx session get <id> --json      # machine-readable metadata
+
+# Engine mode: any engine by id
+apx session get <id> --engine claude --full
+apx session get <id> --engine codex  --tail 16k
+apx session get <id> --any --full                 # search all engines, error on collision
+apx session get <id> --engine claude --json
+```
+
+**Use this to pull a Codex/Claude session into your current context.** Pipe `--full` into a file or prompt:
+
+```bash
+apx session get 019abc... --engine codex --full > /tmp/prev.jsonl
+```
+
+---
+
+## Daemon requirements
+
+| Capability | Daemon? |
+|------------|---------|
+| `find`, `list`, `get`, `resume <id>` (metadata/tail/full/continue) | no |
+| `resume --summary`, `summary`, `ask` | yes (daemon + `super_agent.enabled` in `~/.apx/config.json`) |
+| `resume --into apx[:slug]` | daemon needed only to compute embedded summary; without it the new session has an empty summary block |
+
+If the daemon is down, `apx` auto-starts it when needed.
+
+---
+
+## Native APX session commands (legacy, still useful)
+
+Manage APX-native sessions (`.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 current APC project
+apx session list <slug>
+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 open
+apx session close-stale                # auto-close >1h old
+apx session compact <slug>             # summarize a conversation to disk
+```
+
+---
+
+## Disambiguating collisions
+
+```
+$ 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)
+```
+
+Pick one with `--engine claude` or `--engine codex`.
+
+---
+
+## Tips for callers (LLMs)
+
+1. **Start with `find`, not grep.** Never reconstruct via `apx sessions list | grep`.
+2. **Don't ask the user which engine.** Auto-detect handles it; re-run with `--engine` only on collision.
+3. **`summary` for the gist, `ask` for specifics.** Both need daemon + `super_agent.enabled`.
+4. **`ask` on huge transcripts is slow and capped.** Raise `--max-chunks` if truncation warns and full coverage matters.
+5. **Prefer `--tail N` over `--full`** when feeding raw transcripts to another model — JSONL is verbose, the tail is dense.
+6. **`--into apx:slug`** is the bridge for "let's continue this in apx with the reviewer agent".
+7. **Don't invent ids.** Discover them via `find` or `sessions list`.
+8. **`apx session get --any --full`** is the simplest no-daemon import of any engine session.
+
+---
+
+## Quick reference
+
+```bash
+# Discovery
+apx session find "<text>"                          # start here
+apx session find "<text>" --deep
+apx sessions list
+apx sessions list --project <name>
+apx sessions list --engine <id> --dir <path>
+
+# Understand
+apx session summary <id>
+apx session ask <id> "<question>"
+
+# Read
+apx session get <id>                               # local APC metadata
+apx session get <id> --engine <id> --full
+apx session get <id> --any --tail 32k
+
+# Resume / continue
+apx session resume <id>
+apx session resume <id> --summary
+apx session resume <id> --continue
+apx session resume <id> --into apx:<slug>
+```

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

@@ -0,0 +1,129 @@
+---
+name: apx-skill-builder
+scope: internal
+description: Author a new APX skill — file location, frontmatter (name, description, scope), body style, on-demand loader. Load when creating or adding a skill to APX.
+---
+
+# apx-skill-builder
+
+A **skill** is a Markdown file the super-agent loads on demand. Inspired by Anthropic's skill-creator, simplified for APX's daemon-served model.
+
+## When to make a skill
+
+- **Yes**: topic is bounded (a tool, a config domain, a recurring workflow), instructions need >50 tokens to be safe, not every conversation needs them.
+- **No**: one-off explanations, casual chat, anything fitting in 2-3 lines of the base prompt.
+
+## File location
+
+Scanned in priority order:
+
+1. `<repo>/.apc/skills/<slug>/SKILL.md` — project-scoped.
+2. `~/.apx/skills/<slug>/SKILL.md` — user-global.
+3. `<repo>/skills/<slug>/SKILL.md` in the APX source — bundled.
+
+Layouts: `<slug>/SKILL.md` (dir-style, preferred — supports `references/`, `assets/`) or `<slug>.md` (flat, fine for short).
+
+## Frontmatter
+
+```yaml
+---
+name: my-skill
+description: One-sentence trigger for the super-agent. Include user-phrases that should cause it to load. Short — appears in skill listings.
+scope: public   # public (synced globally) | internal (repo/dev-only) | optional (not pushed by default)
+---
+```
+
+`description` is what the model sees when deciding `load_skill`. Write it as the *trigger condition*, not a body summary. Omit `scope` → 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).
+
+## Body style
+
+Opinionated, concrete, anti-example-driven. Read a sibling `skills/apx-*` before writing yours. Shape:
+
+1. **One-paragraph "what this is"** — no preamble.
+2. **Concrete CLI calls** — most common first.
+3. **Schema / shape** if files/config are involved.
+4. **Anti-examples** — at least one "DON'T" with reason. Stops the model inventing flags.
+5. **Open questions / footnotes** if the surface is incomplete.
+
+Length budget: 80-200 lines. Longer → split or move scripts to `<slug>/scripts/`.
+
+## Loader + commands
+
+```js
+// Model emits:
+load_skill({ slug: "my-skill", project_path: "/abs/path/optional" })
+```
+
+Returns the full body for the current turn; not persisted.
+
+```bash
+apx skills list          # this project's .apc/skills/ (run from project root)
+apx skills sync          # push bundled/public skills to global skill dir
+apx skills status        # what's installed vs available
+```
+
+## Workflow
+
+```bash
+# 1. Pick scope:
+#    .apc/skills/<slug>/SKILL.md   (project)
+#    ~/.apx/skills/<slug>/SKILL.md (user-global)
+#    skills/<slug>/SKILL.md        (bundled, in repo)
+
+# 2. Write
+mkdir -p skills/my-thing
+$EDITOR skills/my-thing/SKILL.md
+
+# 3. Verify (daemon picks up on next listSkills() — no restart)
+apx skills list | grep my-thing
+
+# 4. Pre-test with the super-agent (default target)
+apx exec "Load the my-thing skill and summarize it in 3 bullets"
+```
+
+## Anti-examples
+
+```yaml
+---
+# DON'T omit description — the model can't trigger on slug alone.
+name: vague-stuff
+---
+
+# DON'T pile general advice. ONE topic per skill. A grab-bag is dead weight.
+
+# DON'T duplicate apx --help. Skills explain WHEN and WHY, not WHAT.
+# 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/.
+```
+
+## Optional scaffolding
+
+```
+skills/my-thing/
+├── SKILL.md           ← always
+├── references/        ← markdown the skill cites
+├── assets/            ← images, schemas, sample inputs
+└── scripts/           ← shell/node helpers the skill shells out to
+```
+
+Only `SKILL.md` is auto-loaded. Reference others by relative path from the body ("see references/examples.md").
+
+## 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.
+
+## 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-*`.
+
+## Don't
+
+- Don't ship without frontmatter `description` — loader works, trigger is silent.
+- Don't put secrets inside skills. They're read aloud by an LLM.
+- Don't reference machine-only paths — use `<repo>` or `~/.apx` placeholders.
+- Don't write in third person. The reader is the model. Write to it.

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

@@ -1,16 +1,16 @@
 ---
 name: apx-task
-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'.
+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'.
 ---
 
 # 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`.
+A `task` is a per-project TODO. Append-only JSONL event log per month at `~/.apx/projects/<apxId>/tasks/YYYY-MM.jsonl`. State is the fold of the event stream. Once created a task lives forever — `done` and `drop` record state transitions, don't delete events. `reopen` flips back to `open`.
 
 ## Concrete CLI calls
 
 ```bash
-# Add — most common
+# 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
@@ -25,7 +25,7 @@ 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 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
@@ -35,7 +35,7 @@ apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces
 
 ## 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.
+`t_` + 6 base36 chars (~4B keyspace). Prefix matching works at ≥3 chars when the prefix is unique. If two tasks share a prefix you get null — use a longer one.
 
 ## Fields
 
@@ -43,36 +43,33 @@ apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces
 |---|---|---|
 | `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. |
+| `tags` | optional | Free-form. Used by `--tag` filter. |
+| `due` | optional | ISO `YYYY-MM-DD`. Supports `--due-before`. |
+| `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. |
 
 ## Super-agent tools
 
-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:
+The super-agent has `create_task` and `list_tasks`. "Note that we need to close the auth bug in iacrmar tomorrow" → model calls:
 
 ```json
 { "name": "create_task",
   "arguments": { "project": "iacrmar", "title": "Close the auth bug", "due": "<tomorrow>", "tags": ["bug"] } }
 ```
 
-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.
+"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.
 
 ## 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.
+apx task done t_abc            # "I completed this work"
+apx task drop t_abc            # "no longer needed; archive without completion"
+# Reporting/metrics distinguish them.
 ```
 
 ## Endpoint surface
@@ -90,6 +87,6 @@ GET    /projects/:pid/tasks-summary          → { open, done, dropped, overdue,
 
 ## 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).
+- Don't use tasks for reminders that need to *fire* — that's a future routine kind (`task-due-notify`, not built). Tasks are a list, not a scheduler.
+- Don't depend on `done` deleting the task. It doesn't. Event log stays.
+- Don't grep `~/.apx/projects/<id>/tasks/*.jsonl` for state — use `apx task list` or `getTask()`. Fold logic isn't trivial (later events override fields).

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

@@ -0,0 +1,120 @@
+---
+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.
+---
+
+# apx-telegram
+
+APX polls `getUpdates` and routes messages. Config: `~/.apx/config.json → telegram`. Key model: **each channel can be pinned to a project and a master agent**. Messages on a pinned channel run inside that project, optionally handled by a specific agent instead of the default super-agent.
+
+## 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 auto-reply flag
+    "channels": [
+      {
+        "name": "default",
+        "bot_token": "<from BotFather>",
+        "chat_id": "<numeric chat id>",
+        "project": "iacrmar",          // 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`
+      }
+    ],
+    "contacts": [],   // global roster (user_id → role)
+    "roles": {}       // role → allowed tools
+  }
+}
+```
+
+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.
+
+## Concrete CLI calls
+
+```bash
+apx telegram setup            # template (still emits legacy root fields — prefer channels[])
+
+# 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 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      # alias: rm
+apx telegram owner          clientes <user_id>
+
+# Contacts roster + roles (global; gate which tools a sender may trigger)
+apx telegram contacts
+apx telegram contacts rm <user_id>
+apx telegram role  <user_id> <role>
+apx telegram roles
+apx telegram roles set <name> --tools a,b,c     # or --tools '*'
+apx telegram roles rm  <name>
+
+# Polling lifecycle (autostarts with daemon)
+apx telegram start
+apx telegram stop
+apx telegram status
+
+# Sending (defaults to first configured channel)
+apx telegram send "text"
+apx telegram send "text" --chat 123456789
+apx telegram send "text" --interrupt            # bypass 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 \
+  -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 polling picks up the new wiring without restart.
+
+## 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>`.
+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.
+
+## What "master agent" does
+
+With `route_to_agent: "reviewer"`, messages go through `/projects/:pid/agents/reviewer/chat` instead of `/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).
+
+## 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 expect routing magic from same project on two channels.
+# A channel pins messages TO a project, not vice-versa. Same project from multiple
+# channels is fine, but each channel has its own message log — no unified context.
+
+# DON'T set route_to_agent to a non-existent slug.
+apx telegram channel set default --agent nope    # silently 404s; verify with channel show
+```
+
+## Multiple bots, one APX
+
+`channels[]` supports multiple `{bot_token, chat_id}` pairs — different bots OR the same bot with different chats. Plugin polls each in parallel; project/agent pinning is per-channel. Wire "client A bot, personal bot, notifications-only bot" as three channels.
+
+## Don't
+
+- Write to `telegram.bot_token` / `telegram.chat_id` at root.
+- Expect `apx telegram send` to target a project — it targets a *chat id*. Verify wiring with `apx telegram channel show <name>`.
+- Set `respond_with_engine: false` and then wonder why replies stop. That flag disables auto-reply for the channel.
+- Forget the plugin only fires on listed chat IDs. Other chats are ignored.