@agentprojectcontext/apx 1.6.0 → 1.8.0

package/src/cli/index.js

@@ -53,7 +53,7 @@ import {
   cmdTelegramStatus,
   cmdTelegramSetup,
 } from "./commands/telegram.js";
-import { cmdMessagesTail, cmdMessagesSearch } from "./commands/messages.js";
+import { cmdMessagesTail, cmdMessagesSearch, cmdMessagesChat } from "./commands/messages.js";
 import { cmdExec } from "./commands/exec.js";
 import {
   cmdChat,
@@ -66,6 +66,7 @@ import {
   cmdConfigShow,
   cmdConfigSet,
   cmdConfigUnset,
+  cmdPermission,
 } from "./commands/config.js";
 import { cmdPluginsList, cmdPluginStatus } from "./commands/plugins.js";
 import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus } from "./commands/skills.js";
@@ -84,6 +85,7 @@ import {
   cmdRoutineEnable,
   cmdRoutineDisable,
   cmdRoutineRun,
+  cmdRoutineHistory,
 } from "./commands/routine.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -108,6 +110,887 @@ 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 = [] }) => ({
+  title,
+  summary,
+  usage,
+  commands,
+  options,
+  examples,
+});
+
+const HELP_TOPICS = new Map(Object.entries({
+  init: topic({
+    title: "apx init",
+    summary: "Initialize APC project files in the current directory or a target path.",
+    usage: ["apx init [path] [--name <name>]"],
+    options: [
+      ["--name <name>", "Project display name written to .apc/project.json."],
+    ],
+    examples: ["apx init", "apx init ./my-project --name \"My Project\""],
+  }),
+  setup: topic({
+    title: "apx setup",
+    summary: "Run the interactive APX setup wizard.",
+    usage: ["apx setup", "apx install"],
+    examples: ["apx setup"],
+  }),
+  install: topic({
+    title: "apx install",
+    summary: "Alias for apx setup.",
+    usage: ["apx install"],
+    examples: ["apx install"],
+  }),
+  status: topic({
+    title: "apx status",
+    summary: "Print daemon, super-agent, engine, Telegram, and project status.",
+    usage: ["apx status"],
+    examples: ["apx status"],
+  }),
+  update: topic({
+    title: "apx update",
+    summary: "Check for a published APX update and upgrade the global install.",
+    usage: ["apx update", "apx upgrade"],
+    examples: ["apx update"],
+  }),
+  upgrade: topic({
+    title: "apx upgrade",
+    summary: "Alias for apx update.",
+    usage: ["apx upgrade"],
+    examples: ["apx upgrade"],
+  }),
+  project: topic({
+    title: "apx project",
+    summary: "Register, list, remove, and rebuild daemon project entries.",
+    usage: ["apx project <subcommand> [args] [--flags]"],
+    commands: [
+      ["add [path]", "Register a project path with the daemon."],
+      ["list | ls", "List known daemon projects."],
+      ["remove | rm <id>", "Remove a daemon project entry."],
+      ["rebuild [id]", "Rebuild daemon index from project files."],
+      ["<name|id> <command>", "Run another APX command pinned to that project."],
+    ],
+    options: [["--project <name|id|path>", "Pin command to a specific project where supported."]],
+    examples: ["apx project add .", "apx project list", "apx project testing mcp list"],
+  }),
+  "project add": topic({
+    title: "apx project add",
+    summary: "Register a project with the APX daemon.",
+    usage: ["apx project add [path]"],
+    examples: ["apx project add .", "apx add project ../repo"],
+  }),
+  "project list": topic({
+    title: "apx project list",
+    summary: "List projects known by the daemon.",
+    usage: ["apx project list", "apx project ls"],
+    examples: ["apx project list"],
+  }),
+  "project remove": topic({
+    title: "apx project remove",
+    summary: "Remove a project entry from daemon storage.",
+    usage: ["apx project remove <id>", "apx project rm <id>"],
+    examples: ["apx project remove default"],
+  }),
+  "project rebuild": topic({
+    title: "apx project rebuild",
+    summary: "Rebuild a daemon project index from filesystem context.",
+    usage: ["apx project rebuild [id]"],
+    examples: ["apx project rebuild", "apx project rebuild default"],
+  }),
+  add: topic({
+    title: "apx add",
+    summary: "Friendly alias namespace for add operations.",
+    usage: ["apx add project [path]"],
+    commands: [["project [path]", "Alias for apx project add [path]."]],
+    examples: ["apx add project ."],
+  }),
+  "add project": topic({
+    title: "apx add project",
+    summary: "Alias for apx project add.",
+    usage: ["apx add project [path]"],
+    examples: ["apx add project ."],
+  }),
+  agent: topic({
+    title: "apx agent",
+    summary: "Create, inspect, import, and vault agent definitions.",
+    usage: ["apx agent <subcommand> [args] [--flags]"],
+    commands: [
+      ["add <slug>", "Create a project-local agent."],
+      ["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."],
+    ],
+    examples: ["apx agent add reviewer --role Reviewer --model gpt-5.2", "apx agent list"],
+  }),
+  "agent add": topic({
+    title: "apx agent add",
+    summary: "Create a project-local agent definition.",
+    usage: ["apx agent add <slug> [--role <role>] [--model <model>] [--skills a,b] [--language <tag>] [--description <text>] [--tools a,b]"],
+    options: [
+      ["--role <role>", "Human-readable role."],
+      ["--model <model>", "Preferred model id."],
+      ["--skills a,b", "Comma-separated skill names."],
+      ["--language <tag>", "Default response language, for example en-US or es-AR."],
+      ["--description <text>", "Short agent description."],
+      ["--tools a,b", "Comma-separated tool hints."],
+    ],
+    examples: ["apx agent add reviewer --role Reviewer --model gpt-5.2 --skills review,test"],
+  }),
+  "agent list": topic({
+    title: "apx agent list",
+    summary: "List agents available in the current APC project.",
+    usage: ["apx agent list", "apx agent ls"],
+    examples: ["apx agent list"],
+  }),
+  "agent get": topic({
+    title: "apx agent get",
+    summary: "Print one project agent definition.",
+    usage: ["apx agent get <slug>", "apx agent show <slug>"],
+    examples: ["apx agent get reviewer"],
+  }),
+  "agent import": topic({
+    title: "apx agent import",
+    summary: "Import a reusable agent template from the APX vault into the current project.",
+    usage: ["apx agent import <slug> [--copy] [--force]"],
+    options: [
+      ["--copy", "Copy the vault markdown file into the project instead of linking it."],
+      ["--force", "Overwrite an existing project-local definition when used with --copy."],
+    ],
+    examples: ["apx agent import reviewer", "apx agent import reviewer --copy --force"],
+  }),
+  "agent vault": topic({
+    title: "apx agent vault",
+    summary: "Manage reusable global agent templates under ~/.apx/agents.",
+    usage: ["apx agent vault <subcommand> [args] [--flags]"],
+    commands: [
+      ["list | ls", "List vault templates."],
+      ["add <slug>", "Create a vault template or copy a local project agent into the vault."],
+    ],
+    examples: ["apx agent vault list", "apx agent vault add reviewer"],
+  }),
+  "agent vault list": topic({
+    title: "apx agent vault list",
+    summary: "List reusable global agent templates.",
+    usage: ["apx agent vault list", "apx agent vault ls"],
+    examples: ["apx agent vault list"],
+  }),
+  "agent vault add": topic({
+    title: "apx agent vault add",
+    summary: "Create a reusable global agent template.",
+    usage: ["apx agent vault add <slug> [--role <role>] [--model <model>] [--skills a,b] [--language <tag>] [--description <text>]"],
+    options: [
+      ["--role <role>", "Human-readable role."],
+      ["--model <model>", "Preferred model id."],
+      ["--skills a,b", "Comma-separated skill names."],
+      ["--language <tag>", "Default response language."],
+      ["--description <text>", "Short agent description."],
+    ],
+    examples: ["apx agent vault add reviewer --role Reviewer --model gpt-5.2"],
+  }),
+  identity: topic({
+    title: "apx identity",
+    summary: "Read or edit daemon identity fields.",
+    usage: ["apx identity <show|set|wizard> [args]"],
+    commands: [
+      ["show", "Print current identity."],
+      ["set <key> <value>", "Set one identity field."],
+      ["wizard", "Run interactive identity setup."],
+    ],
+    examples: ["apx identity show", "apx identity set agent_name Ada"],
+  }),
+  "identity show": topic({
+    title: "apx identity show",
+    summary: "Print current daemon identity.",
+    usage: ["apx identity show"],
+    examples: ["apx identity show"],
+  }),
+  "identity set": topic({
+    title: "apx identity set",
+    summary: "Set one daemon identity field.",
+    usage: ["apx identity set <key> <value>"],
+    examples: ["apx identity set agent_name Ada", "apx identity set owner_name Sam"],
+  }),
+  "identity wizard": topic({
+    title: "apx identity wizard",
+    summary: "Run interactive identity setup.",
+    usage: ["apx identity wizard"],
+    examples: ["apx identity wizard"],
+  }),
+  config: topic({
+    title: "apx config",
+    summary: "Read and edit project configuration in .apc/config.json.",
+    usage: ["apx config [show] [--effective] [--only-overrides]", "apx config set <key.path> <value>", "apx config unset <key.path>"],
+    commands: [
+      ["show | ls", "Print config."],
+      ["set <key> <value>", "Set a JSON-aware value."],
+      ["unset | rm <key>", "Remove a key."],
+    ],
+    options: [
+      ["--effective", "Show merged effective config."],
+      ["--only-overrides", "Show only project overrides."],
+    ],
+    examples: ["apx config show --effective", "apx config set engines.openai.model gpt-5.2"],
+  }),
+  "config show": topic({
+    title: "apx config show",
+    summary: "Print project config.",
+    usage: ["apx config show [--effective] [--only-overrides]", "apx config ls"],
+    options: [
+      ["--effective", "Show merged effective config."],
+      ["--only-overrides", "Show only project overrides."],
+    ],
+    examples: ["apx config show", "apx config show --effective"],
+  }),
+  "config set": topic({
+    title: "apx config set",
+    summary: "Set a JSON-aware value in .apc/config.json.",
+    usage: ["apx config set <key.path> <value>"],
+    examples: ["apx config set super_agent.enabled true", "apx config set engines.openai.model gpt-5.2"],
+  }),
+  "config unset": topic({
+    title: "apx config unset",
+    summary: "Remove a key from .apc/config.json.",
+    usage: ["apx config unset <key.path>", "apx config rm <key.path>"],
+    examples: ["apx config unset engines.openai.model"],
+  }),
+  permission: topic({
+    title: "apx permission",
+    summary: "Show or set super-agent permission mode.",
+    usage: ["apx permission show", "apx permission set <total|automatico|permiso>"],
+    commands: [
+      ["show", "Print current permission mode."],
+      ["set <mode>", "Set permission mode."],
+    ],
+    examples: ["apx permission show", "apx permission set automatico"],
+  }),
+  "permission show": topic({
+    title: "apx permission show",
+    summary: "Print current super-agent permission mode.",
+    usage: ["apx permission show"],
+    examples: ["apx permission show"],
+  }),
+  "permission set": topic({
+    title: "apx permission set",
+    summary: "Set super-agent permission mode.",
+    usage: ["apx permission set <total|automatico|permiso>"],
+    examples: ["apx permission set permiso"],
+  }),
+  memory: topic({
+    title: "apx memory",
+    summary: "Read, append, or replace an agent memory.md file.",
+    usage: ["apx memory <slug>", "apx memory <slug> --append \"<note>\"", "apx memory <slug> --replace < memory.md"],
+    options: [
+      ["--append <note>", "Append a durable note under Recent context."],
+      ["--replace", "Replace memory from stdin."],
+    ],
+    examples: ["apx memory reviewer", "apx memory reviewer --append \"Prefers short PR summaries\""],
+  }),
+  session: topic({
+    title: "apx session",
+    summary: "Manage local runtime sessions stored under ~/.apx/projects/<project-id>.",
+    usage: ["apx session <subcommand> [args] [--flags]"],
+    commands: [
+      ["new <slug>", "Create a session file."],
+      ["list | ls [slug]", "List sessions."],
+      ["get | show <id>", "Print session metadata or body."],
+      ["update <id>", "Update session frontmatter."],
+      ["close <id>", "Mark a session complete."],
+      ["check", "Exit non-zero if an active session exists."],
+      ["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."],
+    ],
+    examples: ["apx session list reviewer --last 5", "apx session close 2026-05-09-01 --result \"Done\""],
+  }),
+  "session new": topic({
+    title: "apx session new",
+    summary: "Create a local runtime session file for an agent.",
+    usage: ["apx session new <slug> --title \"<title>\" [--task-ref <ref>] [--body -|\"text\"]"],
+    options: [
+      ["--title <title>", "Required session title."],
+      ["--task-ref <ref>", "External task id or URL."],
+      ["--body -|text", "Initial session body from stdin or inline text."],
+    ],
+    examples: ["apx session new reviewer --title \"Review PR\" --body -"],
+  }),
+  "session list": topic({
+    title: "apx session list",
+    summary: "List local runtime sessions.",
+    usage: ["apx session list [slug] [--last N]", "apx session ls [slug]"],
+    options: [["--last N", "Limit output to the most recent N sessions."]],
+    examples: ["apx session list", "apx session list reviewer --last 5"],
+  }),
+  "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"],
+  }),
+  "session update": topic({
+    title: "apx session update",
+    summary: "Update session frontmatter fields.",
+    usage: ["apx session update <id> [--status <s>] [--result <r>] [--title <t>] [--task_ref <ref>] [--completed <iso>]"],
+    options: [
+      ["--status <s>", "Set status."],
+      ["--result <r>", "Set result summary."],
+      ["--title <t>", "Set title."],
+      ["--task_ref <ref>", "Set task reference."],
+      ["--completed <iso>", "Set completion timestamp."],
+    ],
+    examples: ["apx session update 2026-05-09-01 --status \"in progress\""],
+  }),
+  "session close": topic({
+    title: "apx session close",
+    summary: "Mark a session complete and optionally store a result.",
+    usage: ["apx session close <id> [--result \"<text>\"]"],
+    options: [["--result <text>", "One-line completion result."]],
+    examples: ["apx session close 2026-05-09-01 --result \"Tests passing\""],
+  }),
+  "session check": topic({
+    title: "apx session check",
+    summary: "Detect active sessions to avoid agent collision.",
+    usage: ["apx session check"],
+    examples: ["apx session check"],
+  }),
+  "session close-stale": topic({
+    title: "apx session close-stale",
+    summary: "Auto-close active sessions older than the stale threshold.",
+    usage: ["apx session close-stale"],
+    examples: ["apx session close-stale"],
+  }),
+  "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>]"],
+    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."],
+    ],
+    examples: ["apx session resume 2026-05-09-01 --summary"],
+  }),
+  "session compact": topic({
+    title: "apx session compact",
+    summary: "Compact an agent conversation into a durable summary.",
+    usage: ["apx session compact <slug> [--conversation <id>] [--model <model>] [--project <name|id|path>]"],
+    options: [
+      ["--conversation <id>", "Compact a specific conversation instead of latest."],
+      ["--model <model>", "Override summarizer model."],
+      ["--project <name|id|path>", "Pin to a specific daemon project."],
+    ],
+    examples: ["apx session compact reviewer --conversation abc123"],
+  }),
+  mcp: topic({
+    title: "apx mcp",
+    summary: "Manage and call MCP servers merged from APC and supported IDE configs.",
+    usage: ["apx mcp <subcommand> [args] [--flags]"],
+    commands: [
+      ["list | ls", "List MCP servers for a project."],
+      ["add <name>", "Add a project-owned MCP server."],
+      ["remove | rm <name>", "Remove a project-owned MCP server."],
+      ["enable <name>", "Enable a project-owned MCP server."],
+      ["disable <name>", "Disable a project-owned MCP server."],
+      ["run <name> <tool>", "Call one MCP tool."],
+      ["tools <name>", "Show tool-list hint."],
+      ["check", "Audit source files, merge order, and conflicts."],
+    ],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx mcp list", "apx mcp run filesystem read_file '{\"path\":\"README.md\"}'"],
+  }),
+  "mcp list": topic({
+    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"],
+  }),
+  "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> ...]"],
+    options: [
+      ["--command <cmd>", "Executable command for stdio MCP server."],
+      ["--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 ."],
+  }),
+  "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"],
+  }),
+  "mcp enable": topic({
+    title: "apx mcp enable",
+    summary: "Enable a project-owned MCP server.",
+    usage: ["apx mcp enable <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx mcp enable filesystem"],
+  }),
+  "mcp disable": topic({
+    title: "apx mcp disable",
+    summary: "Disable a project-owned MCP server.",
+    usage: ["apx mcp disable <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx mcp disable filesystem"],
+  }),
+  "mcp run": topic({
+    title: "apx mcp run",
+    summary: "Call a tool on an MCP server through the daemon.",
+    usage: ["apx mcp run <name> <tool> ['<json-args>'] [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx mcp run filesystem read_file '{\"path\":\"README.md\"}'"],
+  }),
+  "mcp tools": topic({
+    title: "apx mcp tools",
+    summary: "Show MCP tool-list guidance for a server.",
+    usage: ["apx mcp tools <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx mcp tools filesystem"],
+  }),
+  "mcp check": topic({
+    title: "apx mcp check",
+    summary: "Audit MCP source files, active entries, and merge conflicts.",
+    usage: ["apx mcp check [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx mcp check"],
+  }),
+  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]"],
+    commands: [
+      ["start", "Start daemon."],
+      ["stop", "Stop daemon."],
+      ["status", "Show daemon health."],
+      ["logs", "Print daemon log tail."],
+    ],
+    examples: ["apx daemon status", "apx daemon logs --tail 100"],
+  }),
+  "daemon start": topic({
+    title: "apx daemon start",
+    summary: "Start the local APX daemon.",
+    usage: ["apx daemon start"],
+    examples: ["apx daemon start"],
+  }),
+  "daemon stop": topic({
+    title: "apx daemon stop",
+    summary: "Stop the local APX daemon.",
+    usage: ["apx daemon stop"],
+    examples: ["apx daemon stop"],
+  }),
+  "daemon status": topic({
+    title: "apx daemon status",
+    summary: "Show local APX daemon status.",
+    usage: ["apx daemon status"],
+    examples: ["apx daemon status"],
+  }),
+  "daemon logs": topic({
+    title: "apx daemon logs",
+    summary: "Print daemon logs.",
+    usage: ["apx daemon logs [--tail N]"],
+    options: [["--tail N", "Number of lines to print."]],
+    examples: ["apx daemon logs --tail 100"],
+  }),
+  telegram: topic({
+    title: "apx telegram",
+    summary: "Configure, inspect, and send through the Telegram bridge.",
+    usage: ["apx telegram <send|status|setup> [args] [--flags]"],
+    commands: [
+      ["send \"text\"", "Send a Telegram message."],
+      ["status", "Show Telegram plugin status."],
+      ["setup", "Print setup guidance."],
+    ],
+    examples: ["apx telegram status", "apx telegram send \"hello\" --chat 123456"],
+  }),
+  "telegram send": topic({
+    title: "apx telegram send",
+    summary: "Send a Telegram message through the configured bridge.",
+    usage: ["apx telegram send \"<text>\" [--chat <id>]"],
+    options: [["--chat <id>", "Override configured chat id."]],
+    examples: ["apx telegram send \"Deploy finished\" --chat 123456"],
+  }),
+  "telegram status": topic({
+    title: "apx telegram status",
+    summary: "Show Telegram bridge status.",
+    usage: ["apx telegram status"],
+    examples: ["apx telegram status"],
+  }),
+  "telegram setup": topic({
+    title: "apx telegram setup",
+    summary: "Print Telegram setup guidance.",
+    usage: ["apx telegram setup"],
+    examples: ["apx telegram setup"],
+  }),
+  messages: topic({
+    title: "apx messages",
+    summary: "Read APX message logs.",
+    usage: ["apx messages <tail|chat|search> [args] [--flags]"],
+    commands: [
+      ["tail", "Print recent messages."],
+      ["chat", "Print recent messages as a chat transcript with actor types."],
+      ["search \"query\"", "Search message logs."],
+    ],
+    examples: ["apx messages chat --channel telegram -n 20", "apx messages search \"deploy\""],
+  }),
+  "messages tail": topic({
+    title: "apx messages tail",
+    summary: "Print recent APX messages.",
+    usage: ["apx messages tail [--agent <slug>] [--channel <name>] [-n N] [--global] [--project <name|id|path>]"],
+    options: [
+      ["--agent <slug>", "Filter by agent."],
+      ["--channel <name>", "Filter by channel, for example runtime, telegram, exec."],
+      ["-n N", "Number of messages to print."],
+      ["--global", "Read global message store where supported."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx messages tail", "apx messages tail --channel runtime -n 20"],
+  }),
+  "messages search": topic({
+    title: "apx messages search",
+    summary: "Search APX message logs.",
+    usage: ["apx messages search \"<query>\" [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx messages search \"deploy\""],
+  }),
+  "messages chat": topic({
+    title: "apx messages chat",
+    summary: "Print APX messages as a chat transcript with user, agent, tool, or system type.",
+    usage: ["apx messages chat [--channel <name>] [-n N] [--global] [--agent <slug>] [--project <name|id|path>]"],
+    options: [
+      ["--channel <name>", "Filter by channel; telegram defaults to global message store."],
+      ["-n N", "Number of messages to print."],
+      ["--global", "Read global message store."],
+      ["--agent <slug>", "Filter project messages by agent."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx messages chat --channel telegram -n 20", "apx messages chat --channel a2a --project default"],
+  }),
+  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>]"],
+    options: [
+      ["--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"],
+  }),
+  chat: topic({
+    title: "apx chat",
+    summary: "Start an interactive agent chat REPL.",
+    usage: ["apx chat <agent> [--conversation <id>] [--model <id>] [--project <name|id|path>]"],
+    options: [
+      ["--conversation <id>", "Continue an existing conversation."],
+      ["--model <id>", "Override configured model."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx chat reviewer", "apx chat reviewer --conversation abc123"],
+  }),
+  conversations: topic({
+    title: "apx conversations",
+    summary: "List or read stored agent conversations.",
+    usage: ["apx conversations <list|get> <agent> [id] [--project <name|id|path>]", "apx conv <list|get> <agent> [id]"],
+    commands: [
+      ["list | ls <agent>", "List conversations for an agent."],
+      ["get | show <agent> <id>", "Print one conversation."],
+    ],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx conversations list reviewer", "apx conversations get reviewer abc123"],
+  }),
+  "conversations list": topic({
+    title: "apx conversations list",
+    summary: "List stored conversations for an agent.",
+    usage: ["apx conversations list <agent> [--project <name|id|path>]", "apx conv ls <agent>"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx conversations list reviewer"],
+  }),
+  "conversations get": topic({
+    title: "apx conversations get",
+    summary: "Print one stored conversation.",
+    usage: ["apx conversations get <agent> <id> [--project <name|id|path>]", "apx conv show <agent> <id>"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx conversations get reviewer abc123"],
+  }),
+  conv: topic({
+    title: "apx conv",
+    summary: "Alias for apx conversations.",
+    usage: ["apx conv <list|get> <agent> [id]"],
+    examples: ["apx conv list reviewer"],
+  }),
+  run: topic({
+    title: "apx run",
+    summary: "Launch a full external runtime session for an agent.",
+    usage: ["apx run <agent> --runtime <claude-code|codex|opencode|aider> \"<prompt>\" [--timeout <seconds>] [--project <name|id|path>]"],
+    options: [
+      ["--runtime <id>", "Runtime CLI to launch: claude-code, codex, opencode, aider."],
+      ["--timeout <seconds>", "Runtime timeout."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx run reviewer --runtime codex \"Review this repo\" --timeout 600"],
+  }),
+  env: topic({
+    title: "apx env",
+    summary: "Inspect local agent runtime environment.",
+    usage: ["apx env detect", "apx env list"],
+    commands: [["detect | list", "Show which supported runtime CLIs are installed."]],
+    examples: ["apx env detect"],
+  }),
+  "env detect": topic({
+    title: "apx env detect",
+    summary: "Show which supported runtime CLIs are installed.",
+    usage: ["apx env detect", "apx env list"],
+    examples: ["apx env detect"],
+  }),
+  send: topic({
+    title: "apx send",
+    summary: "Log an agent-to-agent message, optionally delivering it through the target engine.",
+    usage: ["apx send <from> <to> \"<message>\" [--deliver] [--project <name|id|path>]"],
+    options: [
+      ["--deliver", "Run the target engine after logging the message."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx send planner reviewer \"Please review this plan\" --deliver"],
+  }),
+  connections: topic({
+    title: "apx connections",
+    summary: "Show an agent communication map.",
+    usage: ["apx connections <agent> [--project <name|id|path>]", "apx graph <agent> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx connections reviewer"],
+  }),
+  graph: topic({
+    title: "apx graph",
+    summary: "Alias for apx connections.",
+    usage: ["apx graph <agent> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx graph reviewer"],
+  }),
+  routine: topic({
+    title: "apx routine",
+    summary: "Manage scheduled APX routines.",
+    usage: ["apx routine <subcommand> [args] [--flags]"],
+    commands: [
+      ["list | ls", "List routines with next and last run."],
+      ["add | new <name>", "Create a routine."],
+      ["get | show <name>", "Print routine definition."],
+      ["history | hist <name>", "Show execution history."],
+      ["run <name>", "Trigger manually."],
+      ["enable <name>", "Enable routine."],
+      ["disable <name>", "Disable routine."],
+      ["remove | rm <name>", "Remove routine."],
+    ],
+    examples: ["apx routine list", "apx routine add heartbeat --kind heartbeat --schedule every:5m"],
+  }),
+  routines: topic({
+    title: "apx routines",
+    summary: "Alias for apx routine.",
+    usage: ["apx routines <subcommand> [args] [--flags]"],
+    examples: ["apx routines list"],
+  }),
+  "routine list": topic({
+    title: "apx routine list",
+    summary: "List routines with next and last run details.",
+    usage: ["apx routine list [--project <name|id|path>]", "apx routine ls [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx routine list"],
+  }),
+  "routine add": topic({
+    title: "apx routine add",
+    summary: "Create a scheduled routine.",
+    usage: ["apx routine add <name> --kind <kind> --schedule <schedule> [--spec '<json>'] [--permission-mode <mode>] [--allowed-tools a,b] [--project <name|id|path>]"],
+    options: [
+      ["--kind <kind>", "heartbeat, exec_agent, super_agent, telegram, or shell."],
+      ["--schedule <schedule>", "every:60s, every:5m, every:1h, or once:<iso>."],
+      ["--spec '<json>'", "Routine-specific JSON config."],
+      ["--permission-mode <mode>", "total, automatico, or permiso."],
+      ["--allowed-tools a,b", "Comma-separated allowed tool names."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx routine add check --kind shell --schedule every:1h --spec '{\"cmd\":\"npm test\"}'"],
+  }),
+  "routine get": topic({
+    title: "apx routine get",
+    summary: "Print one routine definition.",
+    usage: ["apx routine get <name> [--project <name|id|path>]", "apx routine show <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx routine get check"],
+  }),
+  "routine history": topic({
+    title: "apx routine history",
+    summary: "Show execution history for one routine.",
+    usage: ["apx routine history <name> [--project <name|id|path>]", "apx routine hist <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx routine history check"],
+  }),
+  "routine run": topic({
+    title: "apx routine run",
+    summary: "Trigger a routine manually, ignoring schedule.",
+    usage: ["apx routine run <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx routine run check"],
+  }),
+  "routine enable": topic({
+    title: "apx routine enable",
+    summary: "Enable one routine.",
+    usage: ["apx routine enable <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx routine enable check"],
+  }),
+  "routine disable": topic({
+    title: "apx routine disable",
+    summary: "Disable one routine.",
+    usage: ["apx routine disable <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx routine disable check"],
+  }),
+  "routine remove": topic({
+    title: "apx routine remove",
+    summary: "Remove one routine.",
+    usage: ["apx routine remove <name> [--project <name|id|path>]", "apx routine rm <name> [--project <name|id|path>]"],
+    options: [["--project <name|id|path>", "Pin command to a specific project."]],
+    examples: ["apx routine remove check"],
+  }),
+  command: topic({
+    title: "apx command",
+    summary: "List or show workflow commands from .apc/commands/.",
+    usage: ["apx command [list]", "apx command show <name>"],
+    commands: [
+      ["list | ls", "List workflow commands."],
+      ["show | get <name>", "Print one command file."],
+    ],
+    examples: ["apx command list", "apx command show release"],
+  }),
+  commands: topic({
+    title: "apx commands",
+    summary: "Alias for apx command.",
+    usage: ["apx commands [list]", "apx commands show <name>"],
+    examples: ["apx commands list"],
+  }),
+  "command list": topic({
+    title: "apx command list",
+    summary: "List workflow commands in .apc/commands/.",
+    usage: ["apx command list", "apx command ls"],
+    examples: ["apx command list"],
+  }),
+  "command show": topic({
+    title: "apx command show",
+    summary: "Print one workflow command file.",
+    usage: ["apx command show <name>", "apx command get <name>"],
+    examples: ["apx command show release"],
+  }),
+  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"],
+    commands: [
+      ["add [targets]", "Install APX skills into selected targets."],
+      ["list | ls", "List known skill targets."],
+      ["status", "Show installed target status."],
+    ],
+    examples: ["apx skills add claude-code cursor", "apx skills add --global"],
+  }),
+  "skills add": topic({
+    title: "apx skills add",
+    summary: "Install APX skill files into local or global agent-tool targets.",
+    usage: ["apx skills add [targets] [--global]"],
+    options: [["--global", "Install to global user-level skill targets."]],
+    examples: ["apx skills add claude-code cursor", "apx skills add --global"],
+  }),
+  "skills list": topic({
+    title: "apx skills list",
+    summary: "List known APX skill targets.",
+    usage: ["apx skills list", "apx skills ls"],
+    examples: ["apx skills list"],
+  }),
+  "skills status": topic({
+    title: "apx skills status",
+    summary: "Show which APX skill targets are installed.",
+    usage: ["apx skills status"],
+    examples: ["apx skills status"],
+  }),
+  plugins: topic({
+    title: "apx plugins",
+    summary: "Inspect loaded APX daemon plugins.",
+    usage: ["apx plugins [list]", "apx plugins status <id>"],
+    commands: [
+      ["list | ls", "Show loaded plugins and status."],
+      ["status <id>", "Print detailed status for one plugin."],
+    ],
+    examples: ["apx plugins list", "apx plugins status telegram"],
+  }),
+  plugin: topic({
+    title: "apx plugin",
+    summary: "Alias for apx plugins.",
+    usage: ["apx plugin [list]", "apx plugin status <id>"],
+    examples: ["apx plugin list"],
+  }),
+  "plugins list": topic({
+    title: "apx plugins list",
+    summary: "Show loaded plugins and their status.",
+    usage: ["apx plugins list", "apx plugins ls"],
+    examples: ["apx plugins list"],
+  }),
+  "plugins status": topic({
+    title: "apx plugins status",
+    summary: "Show detailed status for one plugin.",
+    usage: ["apx plugins status <id>"],
+    examples: ["apx plugins status telegram"],
+  }),
+}));
+
+const HELP_ALIASES = new Map(Object.entries({
+  "project ls": "project list",
+  "project rm": "project remove",
+  "agent ls": "agent list",
+  "agent show": "agent get",
+  "agent vault ls": "agent vault list",
+  "session ls": "session list",
+  "session show": "session get",
+  "mcp ls": "mcp list",
+  "mcp rm": "mcp remove",
+  "conv list": "conversations list",
+  "conv ls": "conversations list",
+  "conv get": "conversations get",
+  "conv show": "conversations get",
+  "env list": "env detect",
+  "routines list": "routine list",
+  "routines ls": "routine list",
+  "routines add": "routine add",
+  "routines new": "routine add",
+  "routine new": "routine add",
+  "routines get": "routine get",
+  "routines show": "routine get",
+  "routine show": "routine get",
+  "routines history": "routine history",
+  "routines hist": "routine history",
+  "routine hist": "routine history",
+  "routines run": "routine run",
+  "routines enable": "routine enable",
+  "routines disable": "routine disable",
+  "routines remove": "routine remove",
+  "routines rm": "routine remove",
+  "routine rm": "routine remove",
+  "commands list": "command list",
+  "commands ls": "command list",
+  "command ls": "command list",
+  "commands show": "command show",
+  "commands get": "command show",
+  "command get": "command show",
+  "skills ls": "skills list",
+  "plugin list": "plugins list",
+  "plugin ls": "plugins list",
+  "plugin status": "plugins status",
+}));
+
 function buildHelp(version) {
   return [
     "",
@@ -142,6 +1025,8 @@ function buildHelp(version) {
     hCmd("apx identity wizard",        36, "interactive identity setup"),
     hCmd("apx config show",            36, "--effective  --only-overrides"),
     hCmd("apx config set <key> <val>", 36, "set key in .apc/config.json  (JSON-aware)"),
+    hCmd("apx permission show",        36, "show super-agent permission mode"),
+    hCmd("apx permission set <mode>",  36, "mode: total | automatico | permiso"),
     hCmd("apx config unset <key>",     36, "remove key from .apc/config.json"),
 
     hSec("Memory"),
@@ -182,6 +1067,7 @@ function buildHelp(version) {
 
     hSec("Messages"),
     hCmd("apx messages tail",          36, "--agent <slug>  --channel <ch>  -n 50  --global"),
+    hCmd("apx messages chat",          36, "--channel telegram  -n 50"),
     hCmd("apx messages search \"q\"",  36, ""),
 
     hSec("LLM / Chat"),
@@ -203,9 +1089,11 @@ function buildHelp(version) {
     hSec("Routines"),
     hCmd("apx routine list",           36, "list routines + next/last run"),
     hCmd("apx routine add <name>",     36, "--kind K  --schedule S  [--spec '{...}']"),
-    `    ${H.DI}kinds: heartbeat | exec_agent | telegram | shell${H.R}`,
+    `    ${H.DI}kinds: heartbeat | exec_agent | super_agent | telegram | shell${H.R}`,
+    `    ${H.DI}flags: --permission-mode total|automatico|permiso  --allowed-tools a,b${H.R}`,
     `    ${H.DI}schedule: every:60s | every:5m | every:1h | once:<iso>${H.R}`,
     hCmd("apx routine get <name>",     36, ""),
+    hCmd("apx routine history <name>", 36, "show routine execution history"),
     hCmd("apx routine run <name>",     36, "manual trigger (ignores schedule)"),
     hCmd("apx routine enable <name>",  36, ""),
     hCmd("apx routine disable <name>", 36, ""),
@@ -231,6 +1119,72 @@ function buildHelp(version) {
   ].join("\n") + "\n";
 }
 
+function buildTopicHelp(t) {
+  const lines = [
+    "",
+    `  ${H.B}${H.WH}${t.title}${H.R}`,
+    `  ${H.DI}${t.summary}${H.R}`,
+    "",
+  ];
+  if (t.usage.length) {
+    lines.push(hSec("Usage"));
+    for (const u of t.usage) lines.push(`    ${H.WH}${u}${H.R}`);
+  }
+  if (t.commands.length) {
+    lines.push(hSec("Commands"));
+    for (const [name, desc] of t.commands) lines.push(hSub(name, 28, desc));
+  }
+  if (t.options.length) {
+    lines.push(hSec("Options"));
+    for (const [flag, desc] of t.options) lines.push(hFlag(flag, 28, desc));
+  }
+  if (t.examples.length) {
+    lines.push(hSec("Examples"));
+    for (const ex of t.examples) lines.push(`    ${H.WH}${ex}${H.R}`);
+  }
+  lines.push(
+    hSec("Global Flags"),
+    hFlag("--help", 28, "show this help"),
+    hFlag("--version", 28, "print version"),
+    "",
+  );
+  return lines.join("\n") + "\n";
+}
+
+function normalizeHelpKey(key) {
+  return HELP_ALIASES.get(key) || key;
+}
+
+function findHelpTopic(argv) {
+  const hasHelpFlag = argv.some((a) => a === "--help" || a === "-h");
+  const hasHelpCommand = argv[0] === "help" || argv[1] === "help";
+  const wantsHelp = hasHelpFlag || hasHelpCommand;
+  if (!wantsHelp) return null;
+
+  const withoutFlags = argv.filter((a) => a !== "--help" && a !== "-h");
+  const tokens = withoutFlags[0] === "help"
+    ? withoutFlags.slice(1)
+    : withoutFlags[1] === "help"
+      ? [withoutFlags[0], ...withoutFlags.slice(2)]
+      : withoutFlags;
+  if (tokens.length === 0) return { global: true };
+
+  const projectSubcommands = new Set(["add", "list", "ls", "remove", "rm", "rebuild"]);
+  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(" "));
+      if (HELP_TOPICS.has(key)) return { topic: HELP_TOPICS.get(key) };
+    }
+  }
+
+  for (let n = tokens.length; n > 0; n--) {
+    const key = normalizeHelpKey(tokens.slice(0, n).join(" "));
+    if (HELP_TOPICS.has(key)) return { topic: HELP_TOPICS.get(key) };
+  }
+
+  return { global: true };
+}
+
 function parseArgs(argv) {
   const args = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
@@ -283,10 +1237,15 @@ process.on("unhandledRejection", (reason) => {
   die(reason instanceof Error ? reason.message : String(reason));
 });
 
-if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
+const helpRequest = findHelpTopic(argv);
+if (argv.length === 0 || helpRequest?.global) {
   process.stdout.write(buildHelp(VERSION));
   process.exit(0);
 }
+if (helpRequest?.topic) {
+  process.stdout.write(buildTopicHelp(helpRequest.topic));
+  process.exit(0);
+}
 
 if (argv[0] === "--version" || argv[0] === "-v") {
   console.log(VERSION);
@@ -401,6 +1360,7 @@ async function dispatch(cmd, rest) {
         const sub = rest[0];
         const a = parseArgs(rest.slice(1));
         if (sub === "tail") await cmdMessagesTail(a);
+        else if (sub === "chat") await cmdMessagesChat(a);
         else if (sub === "search") await cmdMessagesSearch(a);
         else die(`unknown messages subcommand: ${sub || "(none)"}`);
         break;
@@ -454,6 +1414,11 @@ async function dispatch(cmd, rest) {
         break;
       }
 
+      case "permission": {
+        await cmdPermission(parseArgs(rest));
+        break;
+      }
+
       case "plugins":
       case "plugin": {
         const sub = rest[0];
@@ -475,6 +1440,7 @@ async function dispatch(cmd, rest) {
         else if (sub === "enable") await cmdRoutineEnable(a);
         else if (sub === "disable") await cmdRoutineDisable(a);
         else if (sub === "run") await cmdRoutineRun(a);
+        else if (sub === "history" || sub === "hist") await cmdRoutineHistory(a);
         else die(`unknown routine subcommand: ${sub}`);
         break;
       }