@agentprojectcontext/apx 1.33.1 → 1.35.0

package/skills/apx-sessions/SKILL.md

@@ -1,281 +0,0 @@
----
-name: apx-sessions
-description: "Manage APX sessions across engines (apx, claude, codex). Find a session by title, list, resume, summarize, ask about, or pull a transcript — without knowing which engine owns it. Triggers: 'apx session find/ask/summary/resume/get', 'find a session', 'resume claude/codex session', 'summarize session', 'get session transcript', 'continue session in apx'. Not for `apx run` orchestration (that's the apx skill)."
----
-
-# APX Sessions — cross-engine resume, summary, and continuation
-
-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 "improve web UI"
-
-# 2. Get the gist of that session
-apx session summary <id>
-
-# 3. Ask something specific about it
-apx session ask <id> "what sidebar changes were left pending?"
-```
-
-`find` prints a "Next:" block with the exact `summary`/`ask`/`resume` commands pre-filled with the top hit's id, so you can copy-paste straight through. **If you're tempted to grep session lists, use `find` instead.**
-
----
-
-## 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> "what did we decide about the 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 "let's continue this in apx with the reviewer agent".
-7. **Don't invent ids.** Discover them via `apx session find` or `apx sessions list`.
-8. **`apx session get --any --full`** is the simplest way to import an arbitrary engine session into your context, with no daemon dependency.
-
----
-
-## 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

@@ -1,153 +0,0 @@
----
-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.
----
-
-# 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 it short — appears in skill listings.
-scope: public   # public (pushed to IDE skill dirs by default) | internal (repo/dev-only) | optional
----
-```
-
-`description` is what the model sees when deciding whether to call `load_skill`. Write it as the *trigger condition*, not a summary of the body.
-
-`scope` controls distribution: `public` skills are installed globally by `apx skills sync` / `--global`; `internal` ones stay in the APX repo (dev guides like this one); `optional` ones are available but not pushed by default. Omit it and the skill is treated as public.
-
-**Good**: `"How to register an MCP server. Load BEFORE running 'apx mcp add' — three scopes, gotchas with stdio commands, secrets handling."`
-
-**Bad**: `"This skill describes APX's MCP system."` (no trigger; the model won't know when it matters).
-
-## 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          # lists this project's .apc/skills/ (cwd-scoped — run from the project root)
-apx skills sync          # push bundled/public skills to the global skill dir
-apx skills status        # show what's installed vs available
-```
-
-## Workflow: create + register
-
-```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. Pre-test with the super-agent (it's the default target — no agent name needed):
-apx exec "Load the my-thing skill and summarize it in 3 bullets"
-```
-
-## Anti-examples
-
-```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-telegram/SKILL.md

@@ -1,131 +0,0 @@
----
-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
-        "owner_user_id": "123456789"  // optional: per-channel owner (set via `apx telegram owner`)
-      }
-    ],
-    "contacts": [],                   // global roster (user_id → role); see `apx telegram contacts`
-    "roles": {}                       // role → allowed tools; see `apx telegram roles`
-  }
-}
-```
-
-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
-# Print the config template to get started
-apx telegram setup            # note: still emits root bot_token/chat_id — prefer channels[] below
-
-# Channels CRUD
-apx telegram channel add               # interactive wizard
-apx telegram channel add clientes --bot-token <T> --chat-id <C> --project iacrmar --agent reviewer
-apx telegram channel list              # 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
-
-# Contacts roster + roles (global; gate which tools a sender may trigger)
-apx telegram contacts                  # list the global roster
-apx telegram contacts rm <user_id>
-apx telegram role  <user_id> <role>    # assign a role to a contact
-apx telegram roles                     # list role → tools mappings
-apx telegram roles set <name> --tools a,b,c   # or --tools '*' for all
-apx telegram roles rm  <name>
-
-# Polling lifecycle (rarely needed — autostart with daemon)
-apx telegram start
-apx telegram stop
-apx telegram status
-
-# Sending (defaults to first configured channel; use --chat for explicit chat id)
-apx telegram send "text"
-apx telegram send "text" --chat 123456789
-apx telegram send "text" --interrupt        # bypass the pending-agent queue (also: --force)
-
-# Media (daemon HTTP API — no dedicated CLI subcommand yet)
-curl -X POST http://127.0.0.1:7430/telegram/send_photo \
-  -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.