@agentprojectcontext/apx 1.34.0 → 1.35.0

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

@@ -1,95 +1,86 @@
 ---
 name: apx-skill-builder
 scope: internal
-description: How to author a new APX skill — file location, frontmatter (name, description, scope), body style, and how the super-agent loads it on demand. Load when creating or adding a skill to APX.
+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** 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.
+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 (vs. inlining in the system prompt)
+## When to make a skill
 
-- **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.
+- **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
 
-Three places APX scans, in priority order:
+Scanned 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).
+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.
 
-Either layout works:
-- `<slug>/SKILL.md` (dir-style, preferred — lets you ship `references/`, `assets/`, etc.)
-- `<slug>.md` (flat-style, fine for short ones)
+Layouts: `<slug>/SKILL.md` (dir-style, preferred — supports `references/`, `assets/`) or `<slug>.md` (flat, fine for short).
 
 ## 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 it short — appears in skill listings.
-scope: public   # public (pushed to IDE skill dirs by default) | internal (repo/dev-only) | optional
+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 whether to call `load_skill`. Write it as the *trigger condition*, not a summary of the body.
-
-`scope` controls distribution: `public` skills are installed globally by `apx skills sync` / `--global`; `internal` ones stay in the APX repo (dev guides like this one); `optional` ones are available but not pushed by default. Omit it and the skill is treated as public.
+`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; the model won't know when it matters).
+**Bad**: `"This skill describes APX's MCP system."` (no trigger).
 
 ## Body style
 
-Opinionated, concrete, anti-example-driven. Every other APX skill in `skills/apx-*` follows the same shape — read one before writing yours:
+Opinionated, concrete, anti-example-driven. Read a sibling `skills/apx-*` before writing yours. Shape:
 
-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.
+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. If it's longer, split into sub-skills or move scripts into `<slug>/scripts/`.
+Length budget: 80-200 lines. Longer → split or move scripts to `<slug>/scripts/`.
 
-## How the super-agent loads it
+## Loader + commands
 
 ```js
-// The model emits a tool call:
+// Model emits:
 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.
+Returns the full body for the current turn; not persisted.
 
-The user can list installed skills with:
 ```bash
-apx skills list          # lists this project's .apc/skills/ (cwd-scoped — run from the project root)
-apx skills sync          # push bundled/public skills to the global skill dir
-apx skills status        # show what's installed vs available
+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: create + register
+## Workflow
 
 ```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
+# 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 the file
+# 2. Write
 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:
+# 3. Verify (daemon picks up on next listSkills() — no restart)
 apx skills list | grep my-thing
 
-# 4. Pre-test with the super-agent (it's the default target — no agent name needed):
+# 4. Pre-test with the super-agent (default target)
 apx exec "Load the my-thing skill and summarize it in 3 bullets"
 ```
 
@@ -97,57 +88,42 @@ apx exec "Load the my-thing skill and summarize it in 3 bullets"
 
 ```yaml
 ---
-# DON'T omit description — the model can't trigger on the slug alone.
+# DON'T omit description — the model can't trigger on 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 pile general advice. ONE topic per skill. A grab-bag is dead weight.
 
-# 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 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. If a section is incomplete,
-# delete it from the skill and add it to spec/backlog/.
+# DON'T leave TODOs in production skills. Delete incomplete sections;
+# move them to spec/backlog/.
 ```
 
-## Skill scaffolding (optional `<slug>/`)
+## Optional scaffolding
 
 ```
 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
+├── SKILL.md           ← always
+├── references/        ← markdown the skill cites
+├── assets/            ← images, schemas, sample inputs
+└── scripts/           ← shell/node helpers the skill shells out to
 ```
 
-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
+Only `SKILL.md` is auto-loaded. Reference others by relative path from the body ("see references/examples.md").
 
-- `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.
+## Existing skills — mimic the style
 
-Pick the closest topic, mimic the structure, then write yours.
+`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. When you add or change APX behavior, update or add the skill in the same PR — especially under `skills/apx-*`.
+`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 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.
+- 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/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

@@ -1,13 +1,13 @@
 ---
 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.
+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 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.
+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.
 
-## The shape
+## Shape
 
 ```json
 {
@@ -15,61 +15,60 @@ APX runs a Telegram plugin that polls `getUpdates` and routes messages. Config l
     "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?"
+    "respond_with_engine": true,   // global default auto-reply flag
     "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
-        "owner_user_id": "123456789"  // optional: per-channel owner (set via `apx telegram owner`)
+        "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); see `apx telegram contacts`
-    "roles": {}                       // role → allowed tools; see `apx telegram roles`
+    "contacts": [],   // global roster (user_id → role)
+    "roles": {}       // role → allowed tools
   }
 }
 ```
 
-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.
+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
-# Print the config template to get started
-apx telegram setup            # note: still emits root bot_token/chat_id — prefer channels[] below
+apx telegram setup            # template (still emits legacy root fields — prefer channels[])
 
 # Channels CRUD
-apx telegram channel add               # interactive wizard
+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 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>   # set the per-channel owner
+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                  # list the global roster
+apx telegram contacts
 apx telegram contacts rm <user_id>
-apx telegram role  <user_id> <role>    # assign a role to a contact
-apx telegram roles                     # list role → tools mappings
-apx telegram roles set <name> --tools a,b,c   # or --tools '*' for all
+apx telegram 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 (rarely needed — autostart with daemon)
+# Polling lifecycle (autostarts with daemon)
 apx telegram start
 apx telegram stop
 apx telegram status
 
-# Sending (defaults to first configured channel; use --chat for explicit chat id)
+# Sending (defaults to first configured channel)
 apx telegram send "text"
 apx telegram send "text" --chat 123456789
-apx telegram send "text" --interrupt        # bypass the pending-agent queue (also: --force)
+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 \
@@ -82,50 +81,40 @@ curl -X POST http://127.0.0.1:7430/telegram/send_voice \
   -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.
+Every `channel` CRUD write triggers `POST /admin/reload` so polling picks up the new wiring without restart.
 
-## What "pin to project" actually does
+## What "pin to project" does
 
-When a message arrives on a channel with `project: "iacrmar"`:
+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 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.
+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" actually does
+## What "master agent" 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).
+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 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 write to legacy root fields.
+apx config set telegram.bot_token "<T>"   # ← 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 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
-# ↑ 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.
+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. 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.
+`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
 
-- 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.
+- 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.