@agentprojectcontext/apx 1.24.0 → 1.27.1

package/src/{cli → interfaces/cli}/index.js

@@ -19,6 +19,8 @@ import {
   cmdAgentImport,
   cmdAgentVaultList,
   cmdAgentVaultAdd,
+  cmdAgentVaultRm,
+  cmdAgentVaultRestore,
 } from "./commands/agent.js";
 import { cmdMemory } from "./commands/memory.js";
 import {
@@ -31,8 +33,10 @@ import {
   cmdSessionCloseStale,
   cmdSessionResume,
   cmdSessionCompact,
+  cmdSessionSummary,
+  cmdSessionAsk,
 } from "./commands/session.js";
-import { cmdSessionsList } from "./commands/sessions.js";
+import { cmdSessionsList, cmdSessionFind } from "./commands/sessions.js";
 import {
   cmdMcpList,
   cmdMcpAdd,
@@ -46,8 +50,10 @@ import {
 import {
   cmdDaemonStart,
   cmdDaemonStop,
+  cmdDaemonRestart,
   cmdDaemonStatus,
   cmdDaemonLogs,
+  cmdDaemonReload,
 } from "./commands/daemon.js";
 import {
   cmdTelegramSend,
@@ -55,7 +61,24 @@ import {
   cmdTelegramSetup,
   cmdTelegramStart,
   cmdTelegramStop,
+  cmdTelegramChannelAdd,
+  cmdTelegramChannelList,
+  cmdTelegramChannelShow,
+  cmdTelegramChannelSet,
+  cmdTelegramChannelUnset,
+  cmdTelegramChannelRemove,
+  cmdTelegramContacts,
+  cmdTelegramContactRemove,
+  cmdTelegramRole,
+  cmdTelegramRoles,
+  cmdTelegramOwner,
 } from "./commands/telegram.js";
+import {
+  cmdProjectConfigShow,
+  cmdProjectConfigSet,
+  cmdProjectConfigUnset,
+  cmdProjectConfigEdit,
+} from "./commands/project-config.js";
 import { cmdMessagesTail, cmdMessagesSearch, cmdMessagesChat } from "./commands/messages.js";
 import { cmdLog } from "./commands/log.js";
 import { cmdSearch } from "./commands/search.js";
@@ -75,15 +98,18 @@ import {
   cmdPermission,
 } from "./commands/config.js";
 import { cmdPluginsList, cmdPluginStatus } from "./commands/plugins.js";
-import { cmdOverlayStart, cmdOverlayStop, cmdOverlayStatus } from "./commands/overlay.js";
-import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus } from "./commands/skills.js";
+import { cmdDesktopStart, cmdDesktopStop, cmdDesktopStatus, cmdDesktopInstall, cmdDesktopUninstall } from "./commands/desktop.js";
+import { cmdVoiceSay, cmdVoiceListen, cmdVoiceProviders } from "./commands/voice.js";
+import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus, cmdSkillsSync } from "./commands/skills.js";
 import { cmdIdentity } from "./commands/identity.js";
 import { cmdCommandList, cmdCommandShow } from "./commands/command.js";
 import { cmdUpdate } from "./commands/update.js";
 import { cmdSetup } from "./commands/setup.js";
 import { cmdStatus } from "./commands/status.js";
-import { checkForUpdate } from "../core/update-check.js";
-import { mascot } from "../core/mascot.js";
+import { cmdModel } from "./commands/model.js";
+import { cmdPair, cmdPairWeb, cmdPairList, cmdPairRevoke } from "./commands/pair.js";
+import { checkForUpdate } from "../../core/update-check.js";
+import { mascot } from "../../core/mascot.js";
 import {
   cmdRoutineList,
   cmdRoutineGet,
@@ -100,11 +126,20 @@ import {
   cmdArtifactShow,
   cmdArtifactRemove,
 } from "./commands/artifact.js";
+import {
+  cmdTaskAdd,
+  cmdTaskList,
+  cmdTaskShow,
+  cmdTaskDone,
+  cmdTaskDrop,
+  cmdTaskReopen,
+  cmdTaskPatch,
+} from "./commands/task.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const VERSION = JSON.parse(
-  fs.readFileSync(path.join(__dirname, "..", "..", "package.json"), "utf8")
+  fs.readFileSync(path.join(__dirname, "..", "..", "..", "package.json"), "utf8")
 ).version;
 
 // ── ANSI helpers (help only) ─────────────────────────────────────────────────
@@ -123,13 +158,14 @@ const hCmd  = (cmd, pad, desc) => `  ${H.WH}${cmd.padEnd(pad)}${H.R}  ${H.DI}${d
 const hSub  = (sub, pad, desc) => `    ${H.CY}${sub.padEnd(pad)}${H.R}  ${H.DI}${desc}${H.R}`;
 const hFlag = (f,   pad, desc) => `    ${H.YE}${f.padEnd(pad)}${H.R}  ${H.DI}${desc}${H.R}`;
 
-const topic = ({ title, summary, usage = [], commands = [], options = [], examples = [] }) => ({
+const topic = ({ title, summary, usage = [], commands = [], options = [], examples = [], notes = [] }) => ({
   title,
   summary,
   usage,
   commands,
   options,
   examples,
+  notes,
 });
 
 const HELP_TOPICS = new Map(Object.entries({
@@ -210,6 +246,56 @@ const HELP_TOPICS = new Map(Object.entries({
     usage: ["apx project rebuild [id]"],
     examples: ["apx project rebuild", "apx project rebuild default"],
   }),
+  "project config": topic({
+    title: "apx project config",
+    summary: "Read / write the per-project config (.apc/config.json) via the daemon API.",
+    usage: ["apx project config <show|set|unset|edit> <project> [args]"],
+    commands: [
+      ["show <project>", "Print effective + project_only config. Use --key dotted.key for one value."],
+      ["set <project> <key> <value>", "Set a dotted key in the project config (PATCH set)."],
+      ["unset <project> <key>", "Remove a dotted key from the project config (PATCH unset)."],
+      ["edit <project>", "Open the project_only config in $EDITOR; full replace on save."],
+    ],
+    options: [
+      ["--key <dotted.key>", "Limit `show` to one key — prints effective and project_only side by side."],
+      ["--json", "Emit JSON instead of human-readable lines (show --key only)."],
+    ],
+    examples: [
+      "apx project config show iacrmar",
+      "apx project config show iacrmar --key super_agent.model",
+      "apx project config set iacrmar super_agent.model groq:llama-3.3-70b-versatile",
+      "apx project config unset iacrmar super_agent.model",
+      "apx project config edit iacrmar",
+    ],
+  }),
+  "project config show": topic({
+    title: "apx project config show",
+    summary: "Print the effective and project_only config for a project.",
+    usage: ["apx project config show <project> [--key dotted.key] [--json]"],
+    options: [
+      ["--key <dotted.key>", "Print just one key (effective + project_only)."],
+      ["--json", "JSON output (only with --key)."],
+    ],
+    examples: ["apx project config show iacrmar", "apx project config show iacrmar --key super_agent.model"],
+  }),
+  "project config set": topic({
+    title: "apx project config set",
+    summary: "Set a dotted-key value in .apc/config.json (PATCH).",
+    usage: ["apx project config set <project> <dotted.key> <value>"],
+    examples: ["apx project config set iacrmar super_agent.model groq:llama-3.3-70b-versatile"],
+  }),
+  "project config unset": topic({
+    title: "apx project config unset",
+    summary: "Remove a dotted-key from .apc/config.json (PATCH unset).",
+    usage: ["apx project config unset <project> <dotted.key>"],
+    examples: ["apx project config unset iacrmar super_agent.model"],
+  }),
+  "project config edit": topic({
+    title: "apx project config edit",
+    summary: "Open the project_only config in $EDITOR. Saves with PUT on exit.",
+    usage: ["apx project config edit <project>"],
+    examples: ["apx project config edit iacrmar"],
+  }),
   agent: topic({
     title: "apx agent",
     summary: "Create, inspect, import, and vault agent definitions.",
@@ -219,8 +305,10 @@ const HELP_TOPICS = new Map(Object.entries({
       ["list | ls", "List project agents."],
       ["get | show <slug>", "Print one agent definition."],
       ["import <slug>", "Import an agent template from ~/.apx/agents."],
-      ["vault list | ls", "List reusable global agent templates."],
-      ["vault add <slug>", "Create or copy a reusable global agent template."],
+      ["vault list | ls", "List vault templates (bundled defaults + your overrides)."],
+      ["vault add <slug>", "Create a new vault template in the user layer (~/.apx/agents/)."],
+      ["vault rm <slug>", "Delete a vault template (tombstones the bundled default so it stays hidden)."],
+      ["vault restore <slug>", "Lift a tombstone so a previously-removed bundled default is visible again."],
     ],
     examples: ["apx agent add reviewer --role Reviewer --model gpt-5.2", "apx agent list"],
   }),
@@ -289,6 +377,18 @@ const HELP_TOPICS = new Map(Object.entries({
     ],
     examples: ["apx agent vault add reviewer --role Reviewer --model gpt-5.2"],
   }),
+  "agent vault rm": topic({
+    title: "apx agent vault rm",
+    summary: "Delete a vault template. Bundled defaults are tombstoned, not erased; restore them with `apx agent vault restore`.",
+    usage: ["apx agent vault rm <slug>"],
+    examples: ["apx agent vault rm tessa-qa"],
+  }),
+  "agent vault restore": topic({
+    title: "apx agent vault restore",
+    summary: "Lift a tombstone so a previously-removed bundled default is visible again.",
+    usage: ["apx agent vault restore <slug>"],
+    examples: ["apx agent vault restore tessa-qa"],
+  }),
   identity: topic({
     title: "apx identity",
     summary: "Read or edit APX profile identity fields.",
@@ -401,8 +501,45 @@ const HELP_TOPICS = new Map(Object.entries({
       ["close-stale", "Auto-close stale active sessions."],
       ["resume <id>", "Show APC session and optional external transcript summary."],
       ["compact <slug>", "Compact latest or selected conversation into summary."],
+      ["find | search <text>", "Find sessions by title (cross-engine). --deep also searches content."],
+      ["summary <id>", "LLM summary of any session by id (alias for resume --summary)."],
+      ["ask <id> \"<q>\"", "Ask a question about a session; map-reduces large transcripts."],
+    ],
+    examples: ["apx session find \"mejorar interfaz web\"", "apx session ask 019abc... \"¿qué cambios al sidebar?\""],
+  }),
+  "session find": topic({
+    title: "apx session find",
+    summary: "Find sessions by title across every engine, newest first. The fast way to turn a remembered title into a session id.",
+    usage: [
+      "apx session find \"<text>\" [--deep] [--engine <id>] [--dir <path>|--project <name>] [--limit N] [--json]",
+    ],
+    options: [
+      ["--deep", "Also search inside transcript content, not just titles (slower)."],
+      ["--engine <id>", "Restrict to one engine (apx | claude | codex)."],
+      ["--dir <path> / --project <name>", "Scope to one project (reaches unregistered Claude projects)."],
+      ["--limit N", "Max results (default 20)."],
+      ["--json", "Machine-readable output."],
+    ],
+    examples: [
+      "apx session find \"mejorar interfaz web\"",
+      "apx session find \"sidebar\" --deep --engine codex",
+    ],
+  }),
+  "session summary": topic({
+    title: "apx session summary",
+    summary: "Print an LLM summary of any session by id (resolves the owning engine automatically).",
+    usage: ["apx session summary <id> [--engine <id>]"],
+    examples: ["apx session summary 019abc...", "apx session summary 2e3c84 --engine claude"],
+  }),
+  "session ask": topic({
+    title: "apx session ask",
+    summary: "Ask a free-form question about a session. Small transcripts answered in one shot; large ones are map-reduced (mine each part, then synthesize).",
+    usage: ["apx session ask <id> \"<question>\" [--engine <id>] [--max-chunks N]"],
+    options: [
+      ["--max-chunks N", "Cap how many transcript parts are mined (default 20)."],
+      ["--engine <id>", "Restrict to one engine (apx | claude | codex)."],
     ],
-    examples: ["apx session list reviewer --last 5", "apx session close 2026-05-09-01 --result \"Done\""],
+    examples: ["apx session ask 019abc... \"¿qué decidimos sobre el sidebar?\""],
   }),
   "session new": topic({
     title: "apx session new",
@@ -424,10 +561,25 @@ const HELP_TOPICS = new Map(Object.entries({
   }),
   "session get": topic({
     title: "apx session get",
-    summary: "Print one session metadata record or full markdown body.",
-    usage: ["apx session get <id> [--body]", "apx session show <id> [--body]"],
-    options: [["--body", "Print the full session markdown file."]],
-    examples: ["apx session get 2026-05-09-01", "apx session get 2026-05-09-01 --body"],
+    summary: "Print one session record (APX local, or any detected engine).",
+    usage: [
+      "apx session get <id> [--body|--full|--tail N] [--json]",
+      "apx session get <id> --engine <apx|claude|codex> [--full|--tail N]",
+      "apx session get <id> --any [--full|--tail N]",
+    ],
+    options: [
+      ["--body / --full", "Print the full session file (markdown or JSONL transcript)."],
+      ["--tail N[k|m]", "Print the last N bytes of the transcript (e.g. --tail 32k)."],
+      ["--engine <id>", "Look inside one engine's storage: apx | claude | codex."],
+      ["--any", "Search every detected engine; errors on id collisions."],
+      ["--json", "Machine-readable metadata."],
+    ],
+    examples: [
+      "apx session get 2026-05-09-01",
+      "apx session get 2026-05-09-01 --body",
+      "apx session get b3f0c... --engine claude --tail 16k",
+      "apx session get b3f0c... --any --full",
+    ],
   }),
   "session update": topic({
     title: "apx session update",
@@ -463,14 +615,27 @@ const HELP_TOPICS = new Map(Object.entries({
   }),
   "session resume": topic({
     title: "apx session resume",
-    summary: "Show APC session metadata and optional external transcript summary.",
-    usage: ["apx session resume <id> [--summary] [--full] [--project <name|id|path>]"],
+    summary:
+      "Locate <id> across every detected engine (apx | claude | codex), show it, and optionally continue.",
+    usage: [
+      "apx session resume <id> [--engine <id>] [--summary] [--full|--tail N]",
+      "apx session resume <id> --continue            # spawn native CLI to resume",
+      "apx session resume <id> --into apx[:slug]     # create a new APX session seeded with the summary",
+    ],
     options: [
-      ["--summary", "Ask the super-agent to summarize when available."],
-      ["--full", "Print the full available transcript tail."],
-      ["--project <name|id|path>", "Resolve session in a specific daemon project."],
+      ["--engine <id>", "Restrict the search to one engine: apx | claude | codex."],
+      ["--summary", "Ask the super-agent to summarize the transcript (needs daemon)."],
+      ["--tail N[k|m]", "Print the last N bytes of the transcript (default = metadata only)."],
+      ["--full / --body", "Print the entire transcript."],
+      ["--continue", "Spawn the engine's native CLI (claude --resume / codex resume)."],
+      ["--into apx[:slug]", "Create a new APX session whose body is the summary of <id>."],
+      ["--project <name|id|path>", "Pin to a specific APX project (apx-engine summaries only)."],
+    ],
+    examples: [
+      "apx session resume b3f0c12a... --summary",
+      "apx session resume 2026-05-09-01 --continue",
+      "apx session resume b3f0c12a... --engine claude --into apx:reviewer",
     ],
-    examples: ["apx session resume 2026-05-09-01 --summary"],
   }),
   "session compact": topic({
     title: "apx session compact",
@@ -485,39 +650,43 @@ const HELP_TOPICS = new Map(Object.entries({
   }),
   sessions: topic({
     title: "apx sessions",
-    summary: "List AI engine sessions (Claude Code, Codex, APX) non-interactively.",
+    summary:
+      "List AI engine sessions (APX, Claude Code, Codex, …). Without --engine, lists every detected engine.",
     usage: ["apx sessions list [--engine <id>] [--project <name>|--dir <path>] [--limit N]"],
     commands: [
       ["list | ls", "List engine projects, or sessions of one project."],
     ],
     options: [
-      ["--engine <id>", "apx (default) | claude | codex | antigravity."],
+      ["--engine <id>", "Filter to one engine: apx | claude | codex | antigravity. Omit to list every detected engine."],
       ["--project <name>", "A registered APX project to resolve the directory from."],
       ["--dir <path>", "An explicit project directory (for unregistered projects)."],
-      ["--limit N", "Show only the N most recent sessions."],
+      ["--limit N", "Show only the N most recent sessions per engine."],
     ],
     examples: [
+      "apx sessions list                              # every engine, every project",
       "apx sessions list --engine claude",
       "apx sessions list --engine claude --project iacrmar",
-      "apx sessions list --engine codex --dir /path/to/project",
+      "apx sessions list --dir /path/to/project       # this dir across every engine",
     ],
   }),
   "sessions list": topic({
     title: "apx sessions list",
-    summary: "List engine projects, or the sessions of one resolved project.",
+    summary:
+      "List sessions. No --engine → every detected engine (empty engines show '(sin nada)', missing engines are skipped).",
     usage: [
-      "apx sessions list [--engine <id>]",
+      "apx sessions list                                # multi-engine view",
+      "apx sessions list --engine <id>                   # one engine",
       "apx sessions list --engine <id> --project <name>",
       "apx sessions list --engine <id> --dir <path>",
     ],
     options: [
-      ["--engine <id>", "apx (default) | claude | codex | antigravity."],
+      ["--engine <id>", "apx | claude | codex | antigravity. Omit to scan all."],
       ["--project <name>", "Resolve directory from a registered APX project."],
       ["--dir <path>", "Explicit project directory."],
-      ["--limit N", "Show only the N most recent sessions."],
+      ["--limit N", "Show only the N most recent sessions per engine."],
     ],
     examples: [
-      "apx sessions list",
+      "apx sessions list                                            # every engine, every project",
       "apx sessions list --engine claude --project iacrmar",
       "apx sessions list --engine codex --dir /Volumes/work/iacrmar",
     ],
@@ -543,27 +712,44 @@ const HELP_TOPICS = new Map(Object.entries({
     title: "apx mcp list",
     summary: "List MCP servers available to a project.",
     usage: ["apx mcp list [--project <name|id|path>]", "apx mcp ls [--project <name|id|path>]"],
-    options: [["--project <name|id|path>", "Pin command to a specific project."]],
-    examples: ["apx mcp list", "apx mcp list --project default"],
+    options: [
+      ["--project <name|id|path>", "Pin command to a specific project."],
+      ["--scope <shared|runtime|global|all>", "Filter by scope (default: all). shared = .apc/mcps.json, runtime = ~/.apx/projects/<id>/mcps.json, global = ~/.apx/mcps.json."],
+    ],
+    examples: [
+      "apx mcp list",
+      "apx mcp list --project default",
+      "apx mcp list --scope runtime --project iacrmar",
+    ],
   }),
   "mcp add": topic({
     title: "apx mcp add",
-    summary: "Add a project-owned MCP server.",
-    usage: ["apx mcp add <name> --command <cmd> [--env KEY=VAL ...] [--project <name|id|path>] [-- <arg> ...]"],
+    summary: "Add an APX-owned MCP server. Default scope is `shared` (commit to repo) inside an APC project, else `global`.",
+    usage: ["apx mcp add <name> --command <cmd> [--scope <shared|runtime|global>] [--env KEY=VAL ...] [--project <name|id|path>] [-- <arg> ...]"],
     options: [
       ["--command <cmd>", "Executable command for stdio MCP server."],
+      ["--scope <s>", "shared = .apc/mcps.json (committable); runtime = ~/.apx/projects/<id>/mcps.json (per-project, local, chmod 0600 — use for tokens); global = ~/.apx/mcps.json (machine-wide)."],
       ["--env KEY=VAL", "Environment variable. Repeatable."],
       ["--project <name|id|path>", "Pin command to a specific project."],
       ["-- <arg> ...", "Arguments passed to the MCP command."],
     ],
-    examples: ["apx mcp add filesystem --command npx -- -y @modelcontextprotocol/server-filesystem ."],
+    examples: [
+      "apx mcp add filesystem --command npx -- -y @modelcontextprotocol/server-filesystem .",
+      "apx mcp add github --scope runtime --project iacrmar --command npx -- -y @modelcontextprotocol/server-github",
+    ],
   }),
   "mcp remove": topic({
     title: "apx mcp remove",
-    summary: "Remove a project-owned MCP server.",
-    usage: ["apx mcp remove <name> [--project <name|id|path>]", "apx mcp rm <name> [--project <name|id|path>]"],
-    options: [["--project <name|id|path>", "Pin command to a specific project."]],
-    examples: ["apx mcp remove filesystem"],
+    summary: "Remove an APX-owned MCP server from a given scope.",
+    usage: [
+      "apx mcp remove <name> [--scope <shared|runtime|global>] [--project <name|id|path>]",
+      "apx mcp rm <name> [--scope <shared|runtime|global>] [--project <name|id|path>]",
+    ],
+    options: [
+      ["--project <name|id|path>", "Pin command to a specific project."],
+      ["--scope <s>", "Which scope to remove from. Defaults to `shared` inside an APC project, else `global`."],
+    ],
+    examples: ["apx mcp remove filesystem", "apx mcp remove github --scope runtime --project iacrmar"],
   }),
   "mcp enable": topic({
     title: "apx mcp enable",
@@ -602,15 +788,23 @@ const HELP_TOPICS = new Map(Object.entries({
   }),
   daemon: topic({
     title: "apx daemon",
-    summary: "Start, stop, inspect, and read logs from the local APX daemon.",
-    usage: ["apx daemon <start|stop|status|logs> [--flags]"],
+    summary: "Start, stop, restart, inspect, reload, and read logs from the local APX daemon.",
+    usage: ["apx daemon <start|stop|restart|reload|status|logs> [--flags]"],
     commands: [
       ["start", "Start daemon."],
       ["stop", "Stop daemon."],
+      ["restart", "Stop then start — picks up code, prompt, and tool changes."],
+      ["reload", "Re-read ~/.apx/config.json only (NOT code/prompts) without restart."],
       ["status", "Show daemon health."],
       ["logs", "Print daemon log tail."],
     ],
-    examples: ["apx daemon status", "apx daemon logs --tail 100"],
+    examples: ["apx daemon status", "apx daemon restart", "apx daemon logs --tail 100"],
+  }),
+  "daemon restart": topic({
+    title: "apx daemon restart",
+    summary: "Restart the local APX daemon (stop + start in one step).",
+    usage: ["apx daemon restart"],
+    examples: ["apx daemon restart"],
   }),
   "daemon start": topic({
     title: "apx daemon start",
@@ -640,15 +834,59 @@ const HELP_TOPICS = new Map(Object.entries({
   telegram: topic({
     title: "apx telegram",
     summary: "Configure, inspect, and send through the Telegram bridge.",
-    usage: ["apx telegram <send|status|start|stop|setup> [args] [--flags]"],
+    usage: ["apx telegram <send|status|start|stop|setup|channel|contacts|role|roles|owner> [args] [--flags]"],
     commands: [
       ["send \"text\"", "Send a Telegram message."],
       ["status", "Show Telegram plugin status."],
       ["start", "Start polling on every configured channel."],
       ["stop", "Stop polling (config stays intact)."],
       ["setup", "Print setup guidance."],
+      ["channel <sub>", "Manage channels: add | list | show | set | unset | remove."],
+      ["contacts", "List the known-people roster (auto-recorded from inbound messages)."],
+      ["role <user_id> <role>", "Assign a role to a contact (owner-only / terminal)."],
+      ["roles <sub>", "Define role→tools: list | set <name> --tools a,b | rm <name>."],
+      ["owner <channel> <user_id>", "Set who owns a channel."],
+    ],
+    examples: [
+      "apx telegram status",
+      "apx telegram channel add",
+      "apx telegram contacts",
+      "apx telegram role 889721252 editor",
+      "apx telegram owner default 889721252",
+      "apx telegram send \"hello\" --chat 123456",
     ],
-    examples: ["apx telegram status", "apx telegram start", "apx telegram send \"hello\" --chat 123456"],
+  }),
+  "telegram contacts": topic({
+    title: "apx telegram contacts",
+    summary: "List the global contacts roster, with each person's role and last-seen.",
+    usage: ["apx telegram contacts", "apx telegram contacts rm <user_id>"],
+    examples: ["apx telegram contacts", "apx telegram contacts rm 123456"],
+  }),
+  "telegram role": topic({
+    title: "apx telegram role",
+    summary: "Assign a role to a contact by Telegram user_id. Roles gate which tools they can use.",
+    usage: ["apx telegram role <user_id> <role>"],
+    examples: ["apx telegram role 889721252 editor", "apx telegram role 123456 guest"],
+  }),
+  "telegram roles": topic({
+    title: "apx telegram roles",
+    summary: "Define role→tools capability maps. owner/guest are built-in.",
+    usage: [
+      "apx telegram roles",
+      "apx telegram roles set <name> --tools call_agent,list_tasks",
+      "apx telegram roles set <name> --tools '*'",
+      "apx telegram roles rm <name>",
+    ],
+    examples: [
+      "apx telegram roles",
+      "apx telegram roles set editor --tools call_agent,create_task,list_tasks",
+    ],
+  }),
+  "telegram owner": topic({
+    title: "apx telegram owner",
+    summary: "Set who owns a channel (overrides their role to owner on that channel).",
+    usage: ["apx telegram owner <channel> <user_id>"],
+    examples: ["apx telegram owner default 889721252"],
   }),
   "telegram send": topic({
     title: "apx telegram send",
@@ -688,6 +926,79 @@ const HELP_TOPICS = new Map(Object.entries({
     usage: ["apx telegram setup"],
     examples: ["apx telegram setup"],
   }),
+  "telegram channel": topic({
+    title: "apx telegram channel",
+    summary: "Manage entries in cfg.telegram.channels[] — name, bot, chat, pinned project, master agent.",
+    usage: ["apx telegram channel <subcommand> [args] [--flags]"],
+    commands: [
+      ["add [name]", "Interactive wizard (or non-interactive with flags)."],
+      ["list | ls", "List configured channels."],
+      ["show <name>", "Print one channel as JSON."],
+      ["set <name>", "Patch fields (--project, --agent, --respond-engine true|false, --bot-token, --chat-id)."],
+      ["unset <name>", "Clear optional fields (--project, --agent, --bot-token, --chat-id)."],
+      ["remove | rm <name>", "Delete the channel from the array."],
+    ],
+    options: [
+      ["--project <name|id|path>", "Pin channel to a project for inbound routing."],
+      ["--agent <slug>", "Route inbound to this agent instead of the super-agent."],
+      ["--respond-engine <true|false>", "Whether the engine auto-replies on this channel."],
+      ["--bot-token <token>", "Override bot_token (use `add` non-interactively or `set` to rotate)."],
+      ["--chat-id <id>", "Default outbound chat id."],
+    ],
+    examples: [
+      "apx telegram channel add",
+      "apx telegram channel add clientes --bot-token TOKEN --chat-id 1234 --project iacrmar --agent comercial",
+      "apx telegram channel list",
+      "apx telegram channel set clientes --agent reviewer",
+      "apx telegram channel unset clientes --agent",
+      "apx telegram channel remove clientes",
+    ],
+  }),
+  "telegram channel add": topic({
+    title: "apx telegram channel add",
+    summary: "Interactive wizard (or one-shot non-interactive form) to add a Telegram channel.",
+    usage: [
+      "apx telegram channel add",
+      "apx telegram channel add <name> --bot-token TOKEN --chat-id ID [--project P] [--agent A] [--respond-engine true|false]",
+    ],
+    examples: [
+      "apx telegram channel add",
+      "apx telegram channel add support --bot-token 12345:ABC --chat-id 1234 --project default",
+    ],
+  }),
+  "telegram channel list": topic({
+    title: "apx telegram channel list",
+    summary: "List configured Telegram channels.",
+    usage: ["apx telegram channel list", "apx telegram channel ls"],
+    examples: ["apx telegram channel list"],
+  }),
+  "telegram channel show": topic({
+    title: "apx telegram channel show",
+    summary: "Print one Telegram channel as pretty JSON.",
+    usage: ["apx telegram channel show <name>"],
+    examples: ["apx telegram channel show clientes"],
+  }),
+  "telegram channel set": topic({
+    title: "apx telegram channel set",
+    summary: "Patch fields on an existing Telegram channel and reload the daemon.",
+    usage: ["apx telegram channel set <name> [--project P] [--agent A] [--respond-engine true|false] [--bot-token T] [--chat-id ID]"],
+    examples: [
+      "apx telegram channel set clientes --project iacrmar --agent comercial",
+      "apx telegram channel set clientes --respond-engine false",
+    ],
+  }),
+  "telegram channel unset": topic({
+    title: "apx telegram channel unset",
+    summary: "Clear optional fields on a channel (project pin, master agent, etc).",
+    usage: ["apx telegram channel unset <name> [--project] [--agent] [--bot-token] [--chat-id]"],
+    examples: ["apx telegram channel unset clientes --agent", "apx telegram channel unset clientes --project"],
+  }),
+  "telegram channel remove": topic({
+    title: "apx telegram channel remove",
+    summary: "Delete a channel from cfg.telegram.channels[] and reload the daemon.",
+    usage: ["apx telegram channel remove <name>", "apx telegram channel rm <name>"],
+    examples: ["apx telegram channel remove clientes"],
+  }),
   messages: topic({
     title: "apx messages",
     summary: "Read APX message logs.",
@@ -749,15 +1060,26 @@ const HELP_TOPICS = new Map(Object.entries({
   }),
   exec: topic({
     title: "apx exec",
-    summary: "Run a quick one-shot LLM call as an agent.",
-    usage: ["apx exec <agent> \"<prompt>\" [--model <id>] [--max-tokens N] [--temperature T] [--project <name|id|path>]"],
+    summary: "One-shot LLM call. Default target is the APX super-agent (daemon); use -a for an APC agent slug.",
+    usage: [
+      "apx exec \"<prompt>\" [--model <id>] [--project <name|id|path>]",
+      "apx exec -- \"<prompt>\"",
+      "apx exec -a <agent> \"<prompt>\" [--model <id>]",
+      "apx exec <agent> \"<prompt>\"  (legacy positional agent)",
+    ],
     options: [
+      ["-a, --agent <slug>", "APC agent slug (omit for super-agent default)."],
       ["--model <id>", "Override configured model."],
       ["--max-tokens N", "Output token limit."],
       ["--temperature T", "Sampling temperature."],
       ["--project <name|id|path>", "Pin command to a specific project."],
     ],
-    examples: ["apx exec reviewer \"Summarize your role\" --model gpt-5.2"],
+    examples: [
+      "apx exec \"What time is it in UTC?\"",
+      "apx exec -- \"decime qué hora es\"",
+      "apx exec -a reviewer \"Summarize your role\"",
+      "apx exec reviewer \"Summarize your role\" --model gpt-5.2",
+    ],
   }),
   chat: topic({
     title: "apx chat",
@@ -773,11 +1095,12 @@ const HELP_TOPICS = new Map(Object.entries({
   code: topic({
     title: "apx code",
     summary: "Start the APX terminal coding assistant with system and workspace context.",
-    usage: ["apx code [--project <name|id|path>]"],
+    usage: ["apx code [--project <name|id|path>] [--agent <slug>]"],
     options: [
       ["--project <name|id|path>", "Pin command to a specific project."],
+      ["--agent <slug>", "Route chat to a project agent instead of the APX default (super-agent mode)."],
     ],
-    examples: ["apx code", "apx code --project default"],
+    examples: ["apx code", "apx code --project default", "apx code --agent reviewer"],
   }),
   conversations: topic({
     title: "apx conversations",
@@ -1023,13 +1346,19 @@ const HELP_TOPICS = new Map(Object.entries({
   skills: topic({
     title: "apx skills",
     summary: "Install and inspect APX skill files for IDEs and agent tools.",
-    usage: ["apx skills [add] [targets] [--global]", "apx skills list", "apx skills status"],
+    usage: ["apx skills [add] [targets] [--global]", "apx skills sync", "apx skills list", "apx skills status"],
     commands: [
       ["add [targets]", "Install APX skills into selected targets."],
-      ["list | ls", "List known skill targets."],
-      ["status", "Show installed target status."],
+      ["sync | refresh", "Re-install every bundled skill to every global skill dir (idempotent)."],
+      ["list | ls", "List skills installed in this project's .apc/skills/."],
+      ["status", "Show which bundled skills are present in each global dir."],
+    ],
+    examples: [
+      "apx skills add claude-code cursor",
+      "apx skills add --global",
+      "apx skills sync                # force-refresh after editing skills/ in the repo",
+      "apx skills sync --verbose      # show every (skill × target) line",
     ],
-    examples: ["apx skills add claude-code cursor", "apx skills add --global"],
   }),
   "skills add": topic({
     title: "apx skills add",
@@ -1038,6 +1367,26 @@ const HELP_TOPICS = new Map(Object.entries({
     options: [["--global", "Install to global user-level skill targets."]],
     examples: ["apx skills add claude-code cursor", "apx skills add --global"],
   }),
+  "skills sync": topic({
+    title: "apx skills sync",
+    summary:
+      "Refresh bundled APX skills (auto-discovered from skills/) into every global skill dir (.claude, .cursor, .codex, .agents). Pushes only `scope: public` skills by default; pass --include-optional / --include-internal to push the other tiers. Prunes copies of slugs no longer included (use --no-prune to keep them).",
+    usage: [
+      "apx skills sync [--verbose] [--include-optional] [--include-internal] [--no-prune]",
+      "apx skills refresh",
+    ],
+    options: [
+      ["--include-optional", "Also push `scope: optional` skills (apx-voice, …)."],
+      ["--include-internal", "Also push `scope: internal` APX-dev skills (apx-mcp-builder, …)."],
+      ["--no-prune", "Don't remove global copies of slugs that aren't included this run."],
+      ["--verbose", "List each (skill × dir) result, not just the rollup."],
+    ],
+    examples: [
+      "apx skills sync",
+      "apx skills sync --include-optional",
+      "apx skills sync --include-internal --verbose",
+    ],
+  }),
   "skills list": topic({
     title: "apx skills list",
     summary: "List known APX skill targets.",
@@ -1078,6 +1427,374 @@ const HELP_TOPICS = new Map(Object.entries({
     usage: ["apx plugins status <id>"],
     examples: ["apx plugins status telegram"],
   }),
+
+  task: topic({
+    title: "apx task",
+    summary: "Per-project TODO list backed by the daemon (/projects/:pid/tasks).",
+    usage: ["apx task <subcommand> [args] [--flags]"],
+    commands: [
+      ["add | new | create \"<title>\"", "Create a task. Tags repeatable."],
+      ["list | ls", "List tasks (default state=open)."],
+      ["show | get <id>", "Print one task as JSON."],
+      ["done | complete <id>", "Mark task done."],
+      ["drop | archive <id>", "Drop / archive a task."],
+      ["reopen <id>", "Reopen a done or dropped task."],
+      ["patch | edit <id>", "Edit fields on an existing task."],
+    ],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: [
+      "apx task add \"Ship release notes\" --tag release --due 2026-06-01",
+      "apx task list --state open --tag release",
+      "apx task done t_abc123",
+    ],
+  }),
+  tasks: topic({
+    title: "apx tasks",
+    summary: "Alias for apx task.",
+    usage: ["apx tasks <subcommand> [args] [--flags]"],
+    examples: ["apx tasks list"],
+  }),
+  "task add": topic({
+    title: "apx task add",
+    summary: "Create a task on a project's TODO list.",
+    usage: ["apx task add \"<title>\" [--project X] [--body Y] [--tag t]... [--due 2026-05-30] [--agent A] [--source S]"],
+    options: [
+      ["--body <text>", "Optional task body / description."],
+      ["--tag <name>", "Tag the task. Repeatable for multiple tags."],
+      ["--due <date>", "Due date (any ISO-ish string the daemon accepts)."],
+      ["--agent <slug>", "Pre-assign the task to an agent."],
+      ["--source <name>", "Origin label (default: cli)."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: [
+      "apx task add \"Review PR #42\" --agent reviewer --tag review",
+      "apx task add \"Release notes\" --tag release --tag docs --due 2026-06-01",
+    ],
+  }),
+  "task list": topic({
+    title: "apx task list",
+    summary: "List tasks in the current project (defaults to open).",
+    usage: ["apx task list [--state open|done|dropped|all] [--tag X] [--agent Y] [--due-before ISO] [--limit N] [--project P]"],
+    options: [
+      ["--state <s>", "open (default) | done | dropped | all."],
+      ["--tag <name>", "Filter by tag."],
+      ["--agent <slug>", "Filter by assigned agent."],
+      ["--due-before <iso>", "Only tasks with due date before this ISO date."],
+      ["--limit N", "Cap the number of rows."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: [
+      "apx task list",
+      "apx task list --state all --limit 50",
+      "apx task list --agent reviewer --tag review",
+    ],
+  }),
+  "task show": topic({
+    title: "apx task show",
+    summary: "Print one task as JSON.",
+    usage: ["apx task show <id> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx task show t_abc123"],
+  }),
+  "task done": topic({
+    title: "apx task done",
+    summary: "Mark a task as done.",
+    usage: ["apx task done <id> [--by <name>] [--project <name|id|path>]"],
+    options: [
+      ["--by <name>", "Who marked it done (free-form label)."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx task done t_abc123", "apx task done t_abc123 --by reviewer"],
+  }),
+  "task drop": topic({
+    title: "apx task drop",
+    summary: "Drop / archive a task (kept in history, hidden from default list).",
+    usage: ["apx task drop <id> [--by <name>] [--project <name|id|path>]"],
+    options: [
+      ["--by <name>", "Who dropped it (free-form label)."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx task drop t_abc123"],
+  }),
+  "task reopen": topic({
+    title: "apx task reopen",
+    summary: "Reopen a previously done or dropped task.",
+    usage: ["apx task reopen <id> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx task reopen t_abc123"],
+  }),
+  "task patch": topic({
+    title: "apx task patch",
+    summary: "Edit fields on an existing task (title/body/due/agent/tags).",
+    usage: ["apx task patch <id> [--title T] [--body B] [--due D] [--agent A] [--tag t]... [--project P]"],
+    options: [
+      ["--title <text>", "Replace the title."],
+      ["--body <text>", "Replace the body."],
+      ["--due <date>", "Replace the due date (empty string clears)."],
+      ["--agent <slug>", "Reassign (empty string clears)."],
+      ["--tag <name>", "Replace tags. Repeatable; passing none clears."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: [
+      "apx task patch t_abc123 --title \"New title\"",
+      "apx task patch t_abc123 --tag review --tag urgent",
+    ],
+  }),
+
+  // ── Pair (companion-device pairing) ───────────────────────────────────────
+  pair: topic({
+    title: "apx pair",
+    summary: "Pair a companion device (Deck app, etc.) with the local APX daemon via QR code.",
+    usage: [
+      "apx pair [label] [--label <name>]",
+      "apx pair web",
+      "apx pair list | ls",
+      "apx pair revoke <id>",
+    ],
+    commands: [
+      ["(no arg) | deck | device", "QR for the APX Deck app (JSON payload). Poll until the device confirms."],
+      ["web", "QR + link for a browser on the LAN — scan with the phone camera or share the link."],
+      ["list | ls", "List currently-paired clients."],
+      ["revoke | rm <id>", "Revoke a paired client token."],
+    ],
+    options: [["--label <name>", "Friendly label stored with the pairing."]],
+    examples: ["apx pair", "apx pair web", "apx pair list", "apx pair revoke d_abc123"],
+    notes: [
+      "`apx pair` (deck) QR carries a JSON payload only the Deck app understands.",
+      "`apx pair web` QR carries a URL a browser/phone-camera can open — see `apx help pair web`.",
+      "Both share one engine: a per-client token, listable with `apx pair list`, revocable with `apx pair revoke`.",
+    ],
+  }),
+  "pair web": topic({
+    title: "apx pair web",
+    summary: "Pair a browser on the LAN. Mints a one-shot code (90s) and renders a QR + a shareable link.",
+    usage: ["apx pair web"],
+    commands: [
+      ["scan QR", "Point the phone's native camera at the QR → it opens the web already linked."],
+      ["share link", "Copy the printed `link:` (…/#pair=<code>) into Telegram/chat; tapping it pairs the browser."],
+      ["paste code", "Type the printed `code:` into the web pairing screen (manual fallback)."],
+    ],
+    examples: ["apx pair web"],
+    notes: [
+      "The QR/link encode a URL, so they only work for browsers — for the APX Deck app use `apx pair`.",
+      "The daemon must be reachable from the device: bind LAN (host=0.0.0.0) or use a tunnel (Tailscale/Cloudflare).",
+      "The code expires in 90s and is single-use; re-run to get a fresh one.",
+      "Each paired browser shows up in Settings › Dispositivos (kind=web) and is revocable with `apx pair revoke <id>`.",
+    ],
+  }),
+  "pair new": topic({
+    title: "apx pair new",
+    summary: "Issue a pairing nonce, render the QR, and poll the daemon until the device confirms.",
+    usage: ["apx pair [label] [--label <name>]", "apx pair new", "apx pair device"],
+    options: [["--label <name>", "Friendly label stored with the pairing."]],
+    examples: ["apx pair", "apx pair \"phone\"", "apx pair new --label tablet"],
+  }),
+  "pair list": topic({
+    title: "apx pair list",
+    summary: "List currently-paired companion clients.",
+    usage: ["apx pair list", "apx pair ls"],
+    examples: ["apx pair list"],
+  }),
+  "pair revoke": topic({
+    title: "apx pair revoke",
+    summary: "Revoke a paired client token by id.",
+    usage: ["apx pair revoke <id>", "apx pair rm <id>"],
+    examples: ["apx pair revoke d_abc123"],
+  }),
+
+  // ── Desktop (floating voice window) ───────────────────────────────────────
+  desktop: topic({
+    title: "apx desktop",
+    summary: "Launch, stop, or inspect the floating Electron voice desktop window.",
+    usage: ["apx desktop <start|stop|status|install|uninstall> [--flags]"],
+    commands: [
+      ["start",     "Start the desktop window (or report if already running)."],
+      ["stop",      "Stop the desktop window."],
+      ["status",    "Print desktop process state, PID, and autostart status."],
+      ["install",   "Activate autostart at user login (per-user, no sudo)."],
+      ["uninstall", "Deactivate autostart at user login."],
+    ],
+    options: [["--debug, -d", "Verbose start-up logs (start only)."]],
+    examples: [
+      "apx desktop start", "apx desktop status", "apx desktop stop",
+      "apx desktop install", "apx desktop uninstall",
+    ],
+  }),
+  "desktop start": topic({
+    title: "apx desktop start",
+    summary: "Start the floating Electron voice desktop window. No-op if it is already running.",
+    usage: ["apx desktop start [--debug]"],
+    options: [["--debug, -d", "Verbose start-up logs."]],
+    examples: ["apx desktop start", "apx desktop start --debug"],
+  }),
+  "desktop stop": topic({
+    title: "apx desktop stop",
+    summary: "Stop the floating Electron voice desktop window.",
+    usage: ["apx desktop stop"],
+    examples: ["apx desktop stop"],
+  }),
+  "desktop status": topic({
+    title: "apx desktop status",
+    summary: "Print desktop process state and PID (read from ~/.apx/desktop.pid).",
+    usage: ["apx desktop status"],
+    examples: ["apx desktop status"],
+  }),
+  overlay: topic({
+    title: "apx overlay (deprecated)",
+    summary: "Renamed to `apx desktop`. The old name still works and forwards.",
+    usage: ["apx desktop <start|stop|status>"],
+    examples: ["apx desktop start"],
+  }),
+
+  // ── Voice (TTS / mic round-trip) ──────────────────────────────────────────
+  voice: topic({
+    title: "apx voice",
+    summary: "Speak text through the daemon TTS, run a mic→reply round-trip, or list providers.",
+    usage: [
+      "apx voice say \"<text>\" [--provider <id>] [--voice <name>] [--no-play]",
+      "apx voice listen [--seconds N] [--provider <id>] [--no-play]",
+      "apx voice providers",
+    ],
+    commands: [
+      ["say \"<text>\"", "Synthesize and play text via /tts/say."],
+      ["listen", "Record from mic, send to /voice/turn, play the reply."],
+      ["providers | list", "List configured TTS / STT providers."],
+    ],
+    options: [
+      ["--provider <id>", "Override configured provider for this call."],
+      ["--voice <name>", "Override voice id (say only)."],
+      ["--seconds N", "Record for N seconds (listen). 0 = stop on silence."],
+      ["--no-play", "Do not play audio after synthesis / reply."],
+    ],
+    examples: [
+      "apx voice say \"hola, ¿cómo estás?\"",
+      "apx voice listen --seconds 5",
+      "apx voice providers",
+    ],
+  }),
+  "voice say": topic({
+    title: "apx voice say",
+    summary: "Synthesize text through the daemon TTS pipeline (/tts/say) and (by default) play it.",
+    usage: ["apx voice say \"<text>\" [--provider <id>] [--voice <name>] [--no-play]"],
+    options: [
+      ["--provider <id>", "Override configured TTS provider."],
+      ["--voice <name>", "Override voice id."],
+      ["--no-play", "Synthesize but do not play the audio file."],
+    ],
+    examples: [
+      "apx voice say \"hola\"",
+      "apx voice say \"prueba\" --provider piper --voice es_AR",
+      "apx voice say \"silenciado\" --no-play",
+    ],
+  }),
+  "voice listen": topic({
+    title: "apx voice listen",
+    summary: "Record from the local mic, send to /voice/turn (STT + super-agent + TTS), and play the reply.",
+    usage: ["apx voice listen [--seconds N] [--provider <id>] [--no-play]"],
+    options: [
+      ["--seconds N", "Record N seconds. 0 (default) = stop on silence."],
+      ["--provider <id>", "Override STT provider."],
+      ["--no-play", "Do not play the reply audio."],
+    ],
+    examples: ["apx voice listen", "apx voice listen --seconds 5"],
+  }),
+  "voice providers": topic({
+    title: "apx voice providers",
+    summary: "List configured TTS / STT providers known to the daemon.",
+    usage: ["apx voice providers", "apx voice list"],
+    examples: ["apx voice providers"],
+  }),
+
+  // ── Unified daemon log ────────────────────────────────────────────────────
+  log: topic({
+    title: "apx log",
+    summary: "Read the unified daemon log (~/.apx/logs/apx.log). Covers every module: telegram, whisper, super-agent, tools, desktop.",
+    usage: ["apx log [--tail N] [-f|--follow] [--errors]"],
+    options: [
+      ["--tail N", "Print the last N lines (default 100)."],
+      ["-f, --follow", "Keep tailing as new lines are appended."],
+      ["--errors", "Show only [ERROR] lines (also includes structured errors.jsonl)."],
+    ],
+    examples: ["apx log", "apx log --tail 50", "apx log -f", "apx log --errors --tail 20"],
+  }),
+  logs: topic({
+    title: "apx logs",
+    summary: "Alias for apx log.",
+    usage: ["apx logs [--tail N] [-f|--follow] [--errors]"],
+    examples: ["apx logs --tail 50"],
+  }),
+
+  // ── Model router ──────────────────────────────────────────────────────────
+  model: topic({
+    title: "apx model",
+    summary: "Inspect or edit the super-agent model fallback router (~/.apx/config.json super_agent.model_fallback).",
+    usage: ["apx model <subcommand> [args]"],
+    commands: [
+      ["status | show", "Print fallback order, configured keys, per-provider probe results, and active model."],
+      ["order <p1> <p2> …", "Set the fallback order (e.g. ollama openrouter groq)."],
+      ["key <provider> <api-key>", "Save an API key under engines.<provider>.api_key."],
+      ["set <provider> <model-id>", "Pin a specific model id for one provider in the fallback map."],
+      ["test", "Resolve which model the router would pick right now."],
+      ["enable", "Enable the fallback router."],
+      ["disable", "Disable the fallback router (primary only)."],
+    ],
+    examples: [
+      "apx model status",
+      "apx model order ollama openrouter groq",
+      "apx model key groq sk-xxxx",
+      "apx model set openrouter openrouter/anthropic/claude-3.7-sonnet",
+      "apx model test",
+    ],
+  }),
+  "model status": topic({
+    title: "apx model status",
+    summary: "Show provider health + active model picked by the fallback router.",
+    usage: ["apx model status", "apx model show"],
+    examples: ["apx model status"],
+  }),
+  "model order": topic({
+    title: "apx model order",
+    summary: "Set the fallback order across providers.",
+    usage: ["apx model order <p1> <p2> …"],
+    examples: ["apx model order ollama openrouter groq"],
+  }),
+  "model key": topic({
+    title: "apx model key",
+    summary: "Save an API key for one provider in ~/.apx/config.json (engines.<provider>.api_key).",
+    usage: ["apx model key <groq|openrouter|openai|…> <api-key>"],
+    examples: ["apx model key groq sk-xxxx"],
+  }),
+  "model set": topic({
+    title: "apx model set",
+    summary: "Pin a specific model id for one provider in the fallback map.",
+    usage: ["apx model set <provider> <provider:model-id>"],
+    examples: ["apx model set openrouter openrouter/anthropic/claude-3.7-sonnet"],
+  }),
+  "model test": topic({
+    title: "apx model test",
+    summary: "Resolve which model the router would pick right now.",
+    usage: ["apx model test"],
+    examples: ["apx model test"],
+  }),
+  "model enable": topic({
+    title: "apx model enable",
+    summary: "Enable the fallback router.",
+    usage: ["apx model enable"],
+    examples: ["apx model enable"],
+  }),
+  "model disable": topic({
+    title: "apx model disable",
+    summary: "Disable the fallback router (primary model only).",
+    usage: ["apx model disable"],
+    examples: ["apx model disable"],
+  }),
+
+  "daemon reload": topic({
+    title: "apx daemon reload",
+    summary: "Reload ~/.apx/config.json into the daemon without restarting.",
+    usage: ["apx daemon reload"],
+    examples: ["apx daemon reload"],
+  }),
 }));
 
 const HELP_ALIASES = new Map(Object.entries({
@@ -1089,6 +1806,7 @@ const HELP_ALIASES = new Map(Object.entries({
   "agent vault ls": "agent vault list",
   "session ls": "session list",
   "session show": "session get",
+  "session search": "session find",
   "sessions ls": "sessions list",
   "mcp ls": "mcp list",
   "mcp rm": "mcp remove",
@@ -1124,6 +1842,56 @@ const HELP_ALIASES = new Map(Object.entries({
   "plugin list": "plugins list",
   "plugin ls": "plugins list",
   "plugin status": "plugins status",
+  "telegram channels": "telegram channel",
+  "telegram channels list": "telegram channel list",
+  "telegram channels ls": "telegram channel list",
+  "telegram channels add": "telegram channel add",
+  "telegram channels show": "telegram channel show",
+  "telegram channels set": "telegram channel set",
+  "telegram channels unset": "telegram channel unset",
+  "telegram channels remove": "telegram channel remove",
+  "telegram channels rm": "telegram channel remove",
+  "telegram channel ls": "telegram channel list",
+  "telegram channel get": "telegram channel show",
+  "telegram channel rm": "telegram channel remove",
+  "project config get": "project config show",
+  "project config rm": "project config unset",
+
+  // tasks (alias of task)
+  "tasks list": "task list",
+  "tasks ls": "task list",
+  "task ls": "task list",
+  "tasks add": "task add",
+  "tasks new": "task add",
+  "tasks create": "task add",
+  "task new": "task add",
+  "task create": "task add",
+  "tasks show": "task show",
+  "tasks get": "task show",
+  "task get": "task show",
+  "tasks done": "task done",
+  "tasks complete": "task done",
+  "task complete": "task done",
+  "tasks drop": "task drop",
+  "tasks archive": "task drop",
+  "task archive": "task drop",
+  "tasks reopen": "task reopen",
+  "tasks patch": "task patch",
+  "tasks edit": "task patch",
+  "task edit": "task patch",
+
+  // pair
+  "pair device": "pair new",
+  "pair ls": "pair list",
+  "pair rm": "pair revoke",
+
+  // voice
+  "voice list": "voice providers",
+
+  // model
+  "model show": "model status",
+  "model set-order": "model order",
+  "model set-key": "model key",
 }));
 
 function buildHelp(version) {
@@ -1163,6 +1931,10 @@ function buildHelp(version) {
     hSec("Config"),
     hCmd("apx config show",            36, "--effective  --only-overrides"),
     hCmd("apx config set|unset",       36, "<key> [value]  edit .apc/config.json  (JSON-aware)"),
+    hCmd("apx model status",           36, "provider health + active model (fallback router)"),
+    hCmd("apx model order",            36, "<p1> <p2> …  fallback order  e.g. ollama openrouter groq"),
+    hCmd("apx model key",              36, "<groq|openrouter> <api-key>  → ~/.apx/config.json"),
+    hCmd("apx model test",             36, "resolve which model the router picks now"),
     hCmd("apx permission show",        36, "show APX tool permission mode"),
     hCmd("apx permission set <mode>",  36, "mode: total | automatico | permiso"),
 
@@ -1181,6 +1953,9 @@ function buildHelp(version) {
     hCmd("apx session close-stale",    36, "auto-close sessions older than 1h"),
     hCmd("apx session resume <id>",    36, "--summary  --full  (APC + Claude Code transcript)"),
     hCmd("apx session compact <slug>", 36, "--conversation <id>  collapse history into summary"),
+    hCmd("apx session find <text>",    36, "find sessions by title (cross-engine)  --deep  --engine X"),
+    hCmd("apx session summary <id>",   36, "LLM summary of any session by id"),
+    hCmd("apx session ask <id> \"<q>\"", 36, "ask about a session  --max-chunks N"),
     hCmd("apx sessions list",          36, "list AI engine sessions  --engine claude|codex|apx  --project P | --dir D"),
 
     hSec("MCPs"),
@@ -1194,6 +1969,7 @@ function buildHelp(version) {
 
     hSec("Daemon Service"),
     hCmd("apx daemon start",           36, ""),
+    hCmd("apx daemon reload",          36, "reload ~/.apx/config.json without restart"),
     hCmd("apx daemon stop",            36, ""),
     hCmd("apx daemon status",          36, ""),
     hCmd("apx daemon logs",            36, "--tail N  legacy daemon stdout log"),
@@ -1211,7 +1987,7 @@ function buildHelp(version) {
 
     hSec("LLM / Code"),
     hCmd("apx code",                   36, "APX terminal coding assistant"),
-    hCmd("apx exec <agent> \"prompt\"",36, "one-shot agent call  --model <id>  --max-tokens N"),
+    hCmd("apx exec \"prompt\"",         36, "super-agent (default)  --model <id>  -a <agent> for APC slug"),
     hCmd("apx chat <agent>",           36, "interactive agent REPL  --conversation <id>"),
     hCmd("apx search \"query\"",       36, "web search (ddg | brave | browser)  --mode <m>  -n N"),
     hCmd("apx conversations list",     36, "stored exec/chat conversations for <agent>"),
@@ -1241,6 +2017,15 @@ function buildHelp(version) {
     hCmd("apx routine disable <name>", 36, ""),
     hCmd("apx routine remove <name>",  36, ""),
 
+    hSec("Tasks"),
+    hCmd("apx task add \"<title>\"",   36, "--tag t  --due 2026-06-01  --agent A  --body \"...\""),
+    hCmd("apx task list",              36, "--state open|done|dropped|all  --tag X  --agent Y  --limit N"),
+    hCmd("apx task show <id>",         36, "print one task as JSON"),
+    hCmd("apx task done <id>",         36, "--by <name>  mark task done"),
+    hCmd("apx task drop <id>",         36, "drop / archive a task"),
+    hCmd("apx task reopen <id>",       36, "reopen a done/dropped task"),
+    hCmd("apx task patch <id>",        36, "--title T  --body B  --due D  --agent A  --tag t"),
+
     hSec("Artifacts"),
     hCmd("apx artifact create <name>", 36, "create managed file in project storage  [--content '...'] [--project 0]"),
     hCmd("apx artifact list",          36, "list artifacts"),
@@ -1259,6 +2044,22 @@ function buildHelp(version) {
     hCmd("apx plugins list",           36, "show loaded plugins and their status"),
     hCmd("apx plugins status <id>",    36, "detailed status of one plugin (e.g. telegram)"),
 
+    hSec("Voice & Overlay"),
+    hCmd("apx voice say \"text\"",     36, "TTS via daemon  --provider <id>  --voice <name>  --no-play"),
+    hCmd("apx voice listen",           36, "mic → /voice/turn → reply  --seconds N  --no-play"),
+    hCmd("apx voice providers",        36, "list configured TTS / STT providers"),
+    hCmd("apx desktop start",          36, "launch floating voice desktop window (Electron)"),
+    hCmd("apx desktop stop",           36, ""),
+    hCmd("apx desktop status",         36, "show desktop process + autostart state"),
+    hCmd("apx desktop install",        36, "auto-launch the window at login (mac/win/linux)"),
+    hCmd("apx desktop uninstall",      36, "remove the auto-launch entry"),
+
+    hSec("Pair (companion devices)"),
+    hCmd("apx pair [label]",           36, "QR pairing for Deck app / companion clients"),
+    hCmd("apx pair web",               36, "QR + link to pair a browser on the LAN"),
+    hCmd("apx pair list",              36, "list paired clients"),
+    hCmd("apx pair revoke <id>",       36, "revoke a paired client token"),
+
     hSec("Flags"),
     hFlag("--project <name|id|path>",  36, "pin commands to a specific project"),
     hFlag("--help",                    36, "show this help"),
@@ -1290,6 +2091,10 @@ function buildTopicHelp(t) {
     lines.push(hSec("Examples"));
     for (const ex of t.examples) lines.push(`    ${H.WH}${ex}${H.R}`);
   }
+  if (t.notes?.length) {
+    lines.push(hSec("Notes"));
+    for (const n of t.notes) lines.push(`    ${H.DI}${n}${H.R}`);
+  }
   lines.push(
     hSec("Global Flags"),
     hFlag("--help", 28, "show this help"),
@@ -1317,7 +2122,7 @@ function findHelpTopic(argv) {
       : withoutFlags;
   if (tokens.length === 0) return { global: true };
 
-  const projectSubcommands = new Set(["add", "list", "ls", "remove", "rm", "rebuild"]);
+  const projectSubcommands = new Set(["add", "list", "ls", "remove", "rm", "rebuild", "config"]);
   if (tokens[0] === "project" && tokens.length >= 3 && !projectSubcommands.has(tokens[1])) {
     for (let n = tokens.length - 2; n > 0; n--) {
       const key = normalizeHelpKey(tokens.slice(2, 2 + n).join(" "));
@@ -1359,6 +2164,8 @@ function parseArgs(argv) {
       }
     } else if (a === "-n") {
       args.flags.n = argv[++i];
+    } else if (a === "-a") {
+      args.flags.agent = argv[++i];
     } else {
       args._.push(a);
     }
@@ -1410,12 +2217,22 @@ async function dispatch(cmd, rest) {
         const sub = rest[0];
         const a = parseArgs(rest.slice(1));
         const PROJECT_SUBCOMMANDS = new Set([
-          "add", "list", "ls", "remove", "rm", "rebuild",
+          "add", "list", "ls", "remove", "rm", "rebuild", "config",
         ]);
         if (sub === "add") await cmdProjectAdd(a);
         else if (sub === "list" || sub === "ls") await cmdProjectList();
         else if (sub === "remove" || sub === "rm") await cmdProjectRemove(a);
         else if (sub === "rebuild") await cmdProjectRebuild(a);
+        else if (sub === "config") {
+          // apx project config <show|set|unset|edit> <project> ...
+          const csub = rest[1];
+          const ca = parseArgs(rest.slice(2));
+          if (csub === "show" || csub === "get") await cmdProjectConfigShow(ca);
+          else if (csub === "set") await cmdProjectConfigSet(ca);
+          else if (csub === "unset" || csub === "rm") await cmdProjectConfigUnset(ca);
+          else if (csub === "edit") await cmdProjectConfigEdit(ca);
+          else die(`unknown project config subcommand: ${csub || "(none)"} — try: show, set, unset, edit`);
+        }
         else if (sub && !PROJECT_SUBCOMMANDS.has(sub)) {
           // Sugar: `apx project <name|id> <subcommand...>` runs the inner
           // subcommand with --project=<name|id> appended.
@@ -1440,9 +2257,11 @@ async function dispatch(cmd, rest) {
         else if (sub === "vault") {
           const vsub = a._[0];
           const va = { ...a, _: a._.slice(1) };
-          if (vsub === "list" || vsub === "ls") cmdAgentVaultList();
+          if (vsub === "list" || vsub === "ls") cmdAgentVaultList(va);
           else if (vsub === "add") await cmdAgentVaultAdd(va);
-          else die(`unknown vault subcommand: ${vsub || "(none)"} — try: list, add`);
+          else if (vsub === "rm" || vsub === "remove") cmdAgentVaultRm(va);
+          else if (vsub === "restore") cmdAgentVaultRestore(va);
+          else die(`unknown vault subcommand: ${vsub || "(none)"} — try: list, add, rm, restore`);
         }
         else die(`unknown agent subcommand: ${sub || "(none)"}`);
         break;
@@ -1464,6 +2283,9 @@ async function dispatch(cmd, rest) {
         else if (sub === "close-stale") cmdSessionCloseStale();
         else if (sub === "resume") await cmdSessionResume(a);
         else if (sub === "compact") await cmdSessionCompact(a);
+        else if (sub === "find" || sub === "search") cmdSessionFind(a);
+        else if (sub === "summary") await cmdSessionSummary(a);
+        else if (sub === "ask") await cmdSessionAsk(a);
         else die(`unknown session subcommand: ${sub || "(none)"}`);
         break;
       }
@@ -1497,12 +2319,25 @@ async function dispatch(cmd, rest) {
         const a = parseArgs(rest.slice(1));
         if (sub === "start") await cmdDaemonStart(a);
         else if (sub === "stop") await cmdDaemonStop(a);
+        else if (sub === "restart") await cmdDaemonRestart(a);
+        else if (sub === "reload") await cmdDaemonReload(a);
         else if (sub === "status") await cmdDaemonStatus(a);
         else if (sub === "logs") cmdDaemonLogs(a);
         else die(`unknown daemon subcommand: ${sub || "(none)"}`);
         break;
       }
 
+      case "pair": {
+        const sub = rest[0];
+        const a = parseArgs(rest.slice(1));
+        if (!sub || sub === "new" || sub === "device" || sub === "deck") await cmdPair(a);
+        else if (sub === "web") await cmdPairWeb(a);
+        else if (sub === "list" || sub === "ls") await cmdPairList();
+        else if (sub === "revoke" || sub === "rm") await cmdPairRevoke(a);
+        else die(`unknown pair subcommand: ${sub} — try: (no arg)/deck, web, list, revoke <id>`);
+        break;
+      }
+
       case "telegram": {
         const sub = rest[0];
         const a = parseArgs(rest.slice(1));
@@ -1511,6 +2346,27 @@ async function dispatch(cmd, rest) {
         else if (sub === "start") await cmdTelegramStart();
         else if (sub === "stop") await cmdTelegramStop();
         else if (sub === "setup") cmdTelegramSetup();
+        else if (sub === "channel" || sub === "channels") {
+          const csub = rest[1];
+          const ca = parseArgs(rest.slice(2));
+          if (csub === "add") await cmdTelegramChannelAdd(ca);
+          else if (csub === "list" || csub === "ls" || !csub) await cmdTelegramChannelList();
+          else if (csub === "show" || csub === "get") await cmdTelegramChannelShow(ca);
+          else if (csub === "set") await cmdTelegramChannelSet(ca);
+          else if (csub === "unset") await cmdTelegramChannelUnset(ca);
+          else if (csub === "remove" || csub === "rm") await cmdTelegramChannelRemove(ca);
+          else die(`unknown telegram channel subcommand: ${csub} — try: add, list, show, set, unset, remove`);
+        }
+        else if (sub === "contacts" || sub === "contact") {
+          const csub = rest[1];
+          const ca = parseArgs(rest.slice(2));
+          if (csub === "rm" || csub === "remove") await cmdTelegramContactRemove(ca);
+          else if (!csub || csub === "list" || csub === "ls") await cmdTelegramContacts();
+          else die(`unknown telegram contacts subcommand: ${csub} — try: list, rm`);
+        }
+        else if (sub === "role") await cmdTelegramRole(parseArgs(rest.slice(1)));
+        else if (sub === "roles") await cmdTelegramRoles(parseArgs(rest.slice(1)));
+        else if (sub === "owner") await cmdTelegramOwner(parseArgs(rest.slice(1)));
         else die(`unknown telegram subcommand: ${sub || "(none)"}`);
         break;
       }
@@ -1528,7 +2384,7 @@ async function dispatch(cmd, rest) {
       case "log":
       case "logs": {
         // `apx log` is the unified daemon log (everything: telegram, whisper,
-        // super-agent, tools, overlay). For just the legacy stdout sink,
+        // super-agent, tools, desktop). For just the legacy stdout sink,
         // use `apx daemon logs`. `apx log -f` follows; `--errors` filters.
         await cmdLog(parseArgs(rest));
         break;
@@ -1595,6 +2451,11 @@ async function dispatch(cmd, rest) {
         break;
       }
 
+      case "model": {
+        await cmdModel(parseArgs(rest));
+        break;
+      }
+
       case "plugins":
       case "plugin": {
         const sub = rest[0];
@@ -1633,6 +2494,21 @@ async function dispatch(cmd, rest) {
         break;
       }
 
+      case "task":
+      case "tasks": {
+        const sub = rest[0];
+        const a = parseArgs(rest.slice(1));
+        if (!sub || sub === "list" || sub === "ls") await cmdTaskList(a);
+        else if (sub === "add" || sub === "new" || sub === "create") await cmdTaskAdd(a);
+        else if (sub === "show" || sub === "get") await cmdTaskShow(a);
+        else if (sub === "done" || sub === "complete") await cmdTaskDone(a);
+        else if (sub === "drop" || sub === "archive") await cmdTaskDrop(a);
+        else if (sub === "reopen") await cmdTaskReopen(a);
+        else if (sub === "patch" || sub === "edit") await cmdTaskPatch(a);
+        else die(`unknown task subcommand: ${sub}\nUsage: apx task <list|add|show|done|drop|reopen|patch>`);
+        break;
+      }
+
       case "command":
       case "commands": {
         const sub = rest[0];
@@ -1649,6 +2525,7 @@ async function dispatch(cmd, rest) {
         if (!sub || sub === "add") await cmdSkillsAdd(a);
         else if (sub === "list" || sub === "ls") await cmdSkillsList(a);
         else if (sub === "status") await cmdSkillsStatus();
+        else if (sub === "sync" || sub === "refresh") await cmdSkillsSync(a);
         else die(`unknown skills subcommand: ${sub}`);
         break;
       }
@@ -1671,13 +2548,28 @@ async function dispatch(cmd, rest) {
         await cmdUpdate(parseArgs(rest), VERSION);
         return; // skip checkForUpdate after an update
 
-      case "overlay": {
+      case "overlay":
+        console.error("  apx overlay has been renamed to apx desktop — forwarding.");
+        /* falls through */
+      case "desktop": {
         const [sub, ...oRest] = rest;
         const oArgs = parseArgs(oRest);
-        if (!sub || sub === "start")  { await cmdOverlayStart(oArgs); return; }
-        if (sub === "stop")           { await cmdOverlayStop(oArgs);  return; }
-        if (sub === "status")         { await cmdOverlayStatus(oArgs);return; }
-        die(`unknown overlay sub-command: ${sub}\nUsage: apx overlay <start|stop|status>`);
+        if (!sub || sub === "start")  { await cmdDesktopStart(oArgs); return; }
+        if (sub === "stop")           { await cmdDesktopStop(oArgs);  return; }
+        if (sub === "status")         { await cmdDesktopStatus(oArgs);return; }
+        if (sub === "install")        { await cmdDesktopInstall(oArgs);  return; }
+        if (sub === "uninstall")      { await cmdDesktopUninstall(oArgs);return; }
+        die(`unknown desktop sub-command: ${sub}\nUsage: apx desktop <start|stop|status|install|uninstall>`);
+        return;
+      }
+
+      case "voice": {
+        const [sub, ...vRest] = rest;
+        const vArgs = parseArgs(vRest);
+        if (sub === "say")        { await cmdVoiceSay(vArgs); return; }
+        if (sub === "listen")     { await cmdVoiceListen(vArgs); return; }
+        if (sub === "providers" || sub === "list") { await cmdVoiceProviders(); return; }
+        die(`unknown voice sub-command: ${sub || "(missing)"}\nUsage: apx voice <say|listen|providers>`);
         return;
       }