@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/interfaces/cli/help/index.js

@@ -8,6 +8,10 @@
 // examples, notes. `topic()` only fills in the empty arrays so every consumer
 // can iterate without guarding.
 
+// The agent typology and avatar vocabularies are owned by core, so `apx help`
+// can't list a type the daemon would reject or a blob the web can't draw.
+import { AGENT_TYPE_VALUES, BLOB_KEYS } from "#core/apc/agent-identity.js";
+
 // ── ANSI helpers (help only) ─────────────────────────────────────────────────
 const H = {
   R:  "\x1b[0m",
@@ -24,6 +28,10 @@ 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}`;
 
+// Every file-editing command answers to the same selector, so the flag reads
+// the same everywhere it appears.
+const PROJECT_FLAG = ["--project <name|id|path>", "Act on that project instead of the one cwd is inside."];
+
 const topic = ({ title, summary, usage = [], commands = [], options = [], examples = [], notes = [] }) => ({
   title,
   summary,
@@ -127,11 +135,11 @@ export const HELP_TOPICS = new Map(Object.entries({
       ["--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",
+      "apx project config show acme",
+      "apx project config show acme --key super_agent.model",
+      "apx project config set acme super_agent.model groq:llama-3.3-70b-versatile",
+      "apx project config unset acme super_agent.model",
+      "apx project config edit acme",
     ],
   }),
   "project config show": topic({
@@ -142,25 +150,25 @@ export const HELP_TOPICS = new Map(Object.entries({
       ["--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"],
+    examples: ["apx project config show acme", "apx project config show acme --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"],
+    examples: ["apx project config set acme 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"],
+    examples: ["apx project config unset acme 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"],
+    examples: ["apx project config edit acme"],
   }),
   agent: topic({
     title: "apx agent",
@@ -169,6 +177,7 @@ export const HELP_TOPICS = new Map(Object.entries({
     commands: [
       ["add <slug>", "Create a project-local agent."],
       ["list | ls", "List project agents."],
+      ["set | edit <slug>", "Edit an agent's system prompt and/or fields."],
       ["get | show <slug>", "Print one agent definition."],
       ["remove | rm <slug>", "Delete a project agent (file + runtime memory)."],
       ["import <slug>", "Import an agent template from ~/.apx/agents."],
@@ -177,33 +186,73 @@ export const HELP_TOPICS = new Map(Object.entries({
       ["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"],
+    examples: ["apx agent add reviewer --role Reviewer --prompt-file ./prompt.md", "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]"],
+    summary: "Create a project-local agent definition, with its system prompt.",
+    usage: ["apx agent add <slug> [--prompt <text>|-] [--prompt-file <path>] [--type <type>] [--role <role>] [--area <area>] [--model <model>] [--skills a,b] [--language <tag>] [--description <text>] [--tools a,b] [--icon <blob>] [--parent <slug>] [--project <name|id|path>]"],
     options: [
-      ["--role <role>", "Human-readable role."],
+      ["--prompt <text>", "The agent's system prompt (its instructions). Use `-` to read it from stdin."],
+      ["--prompt-file <path>", "Read the system prompt from a file."],
+      ["--type <type>", `Typology: ${AGENT_TYPE_VALUES.join(" | ")}. 'orchestrator' also marks the agent as master.`],
+      ["--role <role>", "Role — a role slug from `apx org show`, or free text."],
+      ["--area <area>", "Org-chart area slug from `apx org show` (growth, not Growth). Display names are slugified on write."],
       ["--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."],
+      ["--tools a,b", "Comma-separated tool hints. Omitted means the safe default set."],
+      ["--icon <blob>", "Avatar blob preset. Omitted means one is picked from those this project isn't using."],
+      ["--parent <slug>", "The orchestrator this agent reports to."],
+      ["--project <name|id|path>", "Create it in that project instead of the one cwd is inside."],
+    ],
+    notes: [
+      "--description is one line of metadata; the PROMPT is what the agent is actually told. Without it the agent runs on its frontmatter alone.",
+      "For a multi-line prompt pipe it in: apx agent add reviewer --prompt - <<'EOF' … EOF",
+      `Blob presets: ${BLOB_KEYS.join(", ")}.`,
+    ],
+    examples: [
+      "apx agent add reviewer --type specialist --role Reviewer --prompt-file ./reviewer-prompt.md",
+      "apx agent add reviewer --role Reviewer --prompt - < prompt.md",
+    ],
+  }),
+  "agent set": topic({
+    title: "apx agent set",
+    summary: "Edit an existing project agent: its system prompt, identity or fields.",
+    usage: ["apx agent set <slug> [--prompt <text>|-] [--prompt-file <path>] [--type <type>] [--role <role>] [--area <area>] [--icon <blob>] [--model <model>] [--language <tag>] [--description <text>] [--skills a,b] [--tools a,b] [--emoji <e>] [--parent <slug>] [--project <name|id|path>]"],
+    options: [
+      ["--prompt <text>", "Replace the agent's system prompt. Use `-` to read it from stdin."],
+      ["--prompt-file <path>", "Replace the system prompt from a file."],
+      ["--type <type>", `Typology: ${AGENT_TYPE_VALUES.join(" | ")}.`],
+      ["--icon <blob>", "Change the avatar blob preset."],
+      ["--tools a,b", "Comma-separated tool allowlist. A declared list is a deliberate narrowing; omit the flag to leave the agent on the broad default."],
+      ["--project <name|id|path>", "Edit the agent in that project instead of the one cwd is inside."],
+    ],
+    notes: [
+      "Only what you pass is changed; a field-only edit leaves the prompt intact.",
+      "Aliases: apx agent edit, apx agent update.",
+      "You do not have to stand in the project: `--project` takes a name, an id from `apx project list`, or a path.",
+    ],
+    examples: [
+      "apx agent set reviewer --prompt - < prompt.md",
+      "apx agent set reviewer --type specialist --area growth --icon kiwi",
+      "apx agent set magui --tools browser_navigate,browser_snapshot,browser_click --project appsi",
     ],
-    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"],
+    summary: "List agents available in an APC project (the one cwd is inside, unless --project says otherwise).",
+    usage: ["apx agent list [--project <name|id|path>]", "apx agent ls [--project <name|id|path>]"],
+    options: [PROJECT_FLAG],
+    examples: ["apx agent list", "apx agent list --project appsi"],
   }),
   "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"],
+    usage: ["apx agent get <slug> [--project <name|id|path>]", "apx agent show <slug> [--project <name|id|path>]"],
+    options: [PROJECT_FLAG],
+    examples: ["apx agent get reviewer", "apx agent get magui --project appsi"],
   }),
   "agent remove": topic({
     title: "apx agent remove",
@@ -293,40 +342,70 @@ export const HELP_TOPICS = new Map(Object.entries({
   }),
   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>"],
+    summary: "Read and edit configuration: the project layer (.apc/config.json) or, with --global, ~/.apx/config.json.",
+    usage: [
+      "apx config [show] [--global] [--effective] [--only-overrides]",
+      "apx config set [--global] <key.path> <value>",
+      "apx config unset [--global] <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."],
+      ["--global", "Target ~/.apx/config.json instead of the project. Credentials, daemon and voice settings live there."],
+      ["--scope <project|global>", "Explicit scope (alias of --global)."],
+      ["--effective", "Show merged effective config. Project scope only."],
+      ["--only-overrides", "Show only project overrides. Project scope only."],
+      ["--project <name|id|path>", "Pin the project layer to a specific project."],
+    ],
+    examples: [
+      "apx config show --effective",
+      "apx config show --global",
+      "apx config set --global engines.openai.api_key sk-example",
+      "apx config set engines.openai.model gpt-5.2",
     ],
-    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"],
+    summary: "Print project config, or ~/.apx/config.json with --global.",
+    usage: ["apx config show [--global] [--effective] [--only-overrides]", "apx config ls"],
     options: [
-      ["--effective", "Show merged effective config."],
-      ["--only-overrides", "Show only project overrides."],
+      ["--global", "Print ~/.apx/config.json (secrets redacted). JSON on stdout, header on stderr, so it pipes to jq."],
+      ["--scope <project|global>", "Explicit scope (alias of --global)."],
+      ["--effective", "Show merged effective config. Project scope only."],
+      ["--only-overrides", "Show only project overrides. Project scope only."],
     ],
-    examples: ["apx config show", "apx config show --effective"],
+    examples: ["apx config show", "apx config show --effective", "apx config show --global"],
   }),
   "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"],
+    summary: "Set a JSON-aware value in .apc/config.json, or in ~/.apx/config.json with --global.",
+    usage: ["apx config set [--global] <key.path> <value>"],
+    options: [
+      ["--global", "Write to ~/.apx/config.json and hot-reload the daemon. Required for credentials — .apc/config.json is committed."],
+      ["--scope <project|global>", "Explicit scope (alias of --global)."],
+    ],
+    examples: [
+      "apx config set --global super_agent.enabled true",
+      "apx config set --global engines.openai.api_key sk-example",
+      "apx config set engines.openai.model gpt-5.2",
+    ],
+    notes: [
+      "Setting a key that looks like a credential WITHOUT --global prints a warning:",
+      ".apc/config.json is committed to git. The write still goes through.",
+    ],
   }),
   "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"],
+    summary: "Remove a key from .apc/config.json, or from ~/.apx/config.json with --global.",
+    usage: ["apx config unset [--global] <key.path>", "apx config rm <key.path>"],
+    options: [
+      ["--global", "Remove the key from ~/.apx/config.json and hot-reload the daemon."],
+      ["--scope <project|global>", "Explicit scope (alias of --global)."],
+    ],
+    examples: ["apx config unset engines.openai.model", "apx config unset --global super_agent.model"],
   }),
   permission: topic({
     title: "apx permission",
@@ -492,7 +571,8 @@ export const HELP_TOPICS = new Map(Object.entries({
       "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> --continue            # spawn native CLI to resume (interactive, for a human)",
+      "apx session resume <id> --continue --msg \"<text>\"   # headless: inject one message, capture the reply",
       "apx session resume <id> --into apx[:slug]     # create a new APX session seeded with the summary",
     ],
     options: [
@@ -500,13 +580,15 @@ export const HELP_TOPICS = new Map(Object.entries({
       ["--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)."],
+      ["--continue", "Spawn the engine's native CLI (claude --resume / codex resume), interactive."],
+      ["--msg \"<text>\"", "Headless: inject one message into the transcript (full context) and capture the reply. Implies --continue. Claude only. \"-\" or empty reads stdin. How an APX agent answers a coding session."],
       ["--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 fb65f80d... --continue --msg \"the owner says: go ahead with the tests, don't touch login\"",
       "apx session resume b3f0c12a... --engine claude --into apx:reviewer",
     ],
   }),
@@ -538,7 +620,7 @@ export const HELP_TOPICS = new Map(Object.entries({
     examples: [
       "apx sessions list                              # every engine, every project",
       "apx sessions list --engine claude",
-      "apx sessions list --engine claude --project iacrmar",
+      "apx sessions list --engine claude --project acme",
       "apx sessions list --dir /path/to/project       # this dir across every engine",
     ],
   }),
@@ -560,8 +642,8 @@ export const HELP_TOPICS = new Map(Object.entries({
     ],
     examples: [
       "apx sessions list                                            # every engine, every project",
-      "apx sessions list --engine claude --project iacrmar",
-      "apx sessions list --engine codex --dir /Volumes/work/iacrmar",
+      "apx sessions list --engine claude --project acme",
+      "apx sessions list --engine codex --dir /Volumes/work/acme",
     ],
   }),
   obsidian: topic({
@@ -594,7 +676,7 @@ export const HELP_TOPICS = new Map(Object.entries({
     usage: ["apx mcp <subcommand> [args] [--flags]"],
     commands: [
       ["list | ls", "List MCP servers for a project."],
-      ["add <name>", "Add a project-owned MCP server."],
+      ["add <name>", "Add a project-owned MCP server (stdio via --command, remote via --url)."],
       ["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."],
@@ -617,23 +699,31 @@ export const HELP_TOPICS = new Map(Object.entries({
     examples: [
       "apx mcp list",
       "apx mcp list --project default",
-      "apx mcp list --scope runtime --project iacrmar",
+      "apx mcp list --scope runtime --project acme",
     ],
   }),
   "mcp add": topic({
     title: "apx mcp add",
-    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> ...]"],
+    summary: "Add an APX-owned MCP server, local (stdio) or remote (http). 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> ...]",
+      "apx mcp add <name> --url <endpoint> [--header \"Name: value\" ...] [--scope <shared|runtime|global>] [--project <name|id|path>]",
+    ],
     options: [
-      ["--command <cmd>", "Executable command for stdio MCP server."],
+      ["--command <cmd>", "Executable command for a local stdio MCP server."],
+      ["--url <endpoint>", "Endpoint of a remote streamable-HTTP MCP server. Mutually exclusive with --command."],
+      ["--header \"Name: value\"", "HTTP header for --url (also accepts Name=value). Repeatable. Put tokens in --scope runtime."],
+      ["--transport <stdio|http>", "Optional; inferred from --command / --url."],
       ["--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."],
+      ["--env KEY=VAL", "Environment variable (stdio only). Repeatable."],
       ["--project <name|id|path>", "Pin command to a specific project."],
-      ["-- <arg> ...", "Arguments passed to the MCP command."],
+      ["-- <arg> ...", "Arguments passed to the MCP command (stdio only)."],
     ],
     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",
+      "apx mcp add github --scope runtime --project acme --command npx -- -y @modelcontextprotocol/server-github",
+      "apx mcp add postbean --url https://mcp.example.com/mcp --scope runtime",
+      "apx mcp add postbean --url https://mcp.example.com/mcp --header \"Authorization: Bearer $TOKEN\" --scope runtime",
     ],
   }),
   "mcp remove": topic({
@@ -647,7 +737,7 @@ export const HELP_TOPICS = new Map(Object.entries({
       ["--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"],
+    examples: ["apx mcp remove filesystem", "apx mcp remove github --scope runtime --project acme"],
   }),
   "mcp enable": topic({
     title: "apx mcp enable",
@@ -862,7 +952,7 @@ export const HELP_TOPICS = new Map(Object.entries({
     ],
     examples: [
       "apx telegram channel add",
-      "apx telegram channel add clientes --bot-token TOKEN --chat-id 1234 --project iacrmar --agent comercial",
+      "apx telegram channel add clientes --bot-token TOKEN --chat-id 1234 --project acme --agent comercial",
       "apx telegram channel list",
       "apx telegram channel set clientes --agent reviewer",
       "apx telegram channel unset clientes --agent",
@@ -898,7 +988,7 @@ export const HELP_TOPICS = new Map(Object.entries({
     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 --project acme --agent comercial",
       "apx telegram channel set clientes --respond-engine false",
     ],
   }),
@@ -978,14 +1068,15 @@ export const HELP_TOPICS = new Map(Object.entries({
     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 --code \"<prompt>\"   (coding channel: code system prompt + git tools)",
+      "apx exec --code \"<prompt>\" [--session <id>]   (coding channel; lands in a code session)",
       "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)."],
-      ["-c, --code", "Run on the 'code' channel (coding system prompt + code tools)."],
+      ["-c, --code", "Run on the 'code' channel. The turn is saved as a code session, visible at /code."],
+      ["--session <id>", "Continue an existing code session instead of opening a new one (--code only)."],
       ["--channel <name>", "Explicit channel (cli, code, api, …). Default cli."],
       ["--model <id>", "Override configured model."],
       ["--max-tokens N", "Output token limit."],
@@ -995,6 +1086,7 @@ export const HELP_TOPICS = new Map(Object.entries({
     examples: [
       "apx exec \"What time is it in UTC?\"",
       "apx exec --code \"refactor the auth middleware\"",
+      "apx exec --code --session cs_ab12cd \"now add a test for it\"",
       "apx exec -- \"decime qué hora es\"",
       "apx exec -a reviewer \"Summarize your role\"",
       "apx exec reviewer \"Summarize your role\" --model gpt-5.2",
@@ -1065,14 +1157,18 @@ export const HELP_TOPICS = new Map(Object.entries({
   }),
   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|cursor-agent|gemini-cli|qwen-code|antigravity> \"<prompt>\" [--timeout <seconds>] [--project <name|id|path>]"],
+    summary: "Delegate a prompt to an external runtime CLI. The agent is OPTIONAL — without one it's a pass-through (the CLI runs as itself); with one, that agent's system prompt shapes the turn.",
+    usage: ["apx run [-a <agent>] --runtime <claude-code|codex|opencode|aider|cursor-agent|gemini-cli|qwen-code|antigravity> \"<prompt>\" [--timeout <seconds>] [--project <name|id|path>]"],
     options: [
       ["--runtime <id>", "Runtime CLI to launch: claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code, antigravity."],
+      ["-a, --agent <slug>", "Optional. Wrap the run in this APX agent's system prompt. Omit for a pass-through — the external CLI uses its own default persona (it does not use APX agents)."],
       ["--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"],
+    examples: [
+      "apx run --runtime codex \"Review this repo\"                 # pass-through",
+      "apx run -a reviewer --runtime codex \"Review this repo\"     # wrapped in the reviewer agent",
+    ],
   }),
   env: topic({
     title: "apx env",
@@ -1089,13 +1185,32 @@ export const HELP_TOPICS = new Map(Object.entries({
   }),
   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>]"],
+    summary: "Log an agent-to-agent message, optionally delivering it through the recipient.",
+    usage: ["apx send <from> <to> \"<message>\" [--deliver] [--code] [--background] [--timeout <s>] [--severity blocker|status|fyi] [--model <id>] [--usage <json>] [--project <name|id|path>]"],
     options: [
-      ["--deliver", "Run the target engine after logging the message."],
+      ["--deliver", "Run the recipient now and print its reply (plus the session it kept)."],
+      ["--code", "Open the exchange as a coding session: the peer runs with write access, and the exchange shows up in the Code module. Without it the peer is read-only. Not available for claude-code or codex."],
+      ["--background", "Hand the turn back immediately; the reply lands on the thread when the peer finishes. For work that takes minutes."],
+      ["--timeout <s>", "Seconds before the peer is killed. Default 300 in the foreground, 3600 with --background."],
+      ["--severity <blocker|status|fyi>", "Urgency for the owner. blocker = alert now (Roby pings, crosses quiet-hours); status/fyi = rides the digest."],
+      ["--model <id>", "Attribution override. Default: the sender agent's configured model. Sets which model the message shows as."],
+      ["--usage <json>", "Token usage, e.g. '{\"input_tokens\":10,\"output_tokens\":5}'. A plain relay spends none, so it stays empty unless you pass it."],
       ["--project <name|id|path>", "Pin command to a specific project."],
     ],
-    examples: ["apx send planner reviewer \"Please review this plan\" --deliver"],
+    examples: [
+      "apx send planner reviewer \"Please review this plan\" --deliver",
+      "apx send claude-code opencode \"Take a look at src/auth and tell me what you'd change\" --deliver",
+      "apx send claude-code opencode:review \"Second thread, separate history\" --deliver",
+      "apx send claude-code opencode \"Add the retry to the fetch helper\" --deliver --code --background",
+      "apx send magui roby \"Postiz API is down, daily post failed\" --severity blocker --deliver",
+    ],
+    notes: [
+      "<to> is a PEER: an agent slug from AGENTS.md, the configured super-agent name (for example Roby; runs the real orchestrator), or a runtime id (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code, antigravity) answered by spawning that CLI.",
+      "Append :<thread> for a second, independent exchange with the same peer (opencode:review). Separate history, separate session.",
+      "A runtime peer continues its OWN session between turns, and runs in your current directory rather than the project's.",
+      "Read-only is the default on purpose: being messaged is not consent to have your checkout edited. --code is what opens write access, and it is enforced by the runtime itself (opencode --agent), not just asked for in the prompt.",
+      "claude-code and codex are never --code peers: they are the CLIs you drive yourself, and a message must not also start them writing to the same checkout. They answer read-only; send the work to opencode or use apx run.",
+    ],
   }),
   connections: topic({
     title: "apx connections",
@@ -1136,7 +1251,7 @@ export const HELP_TOPICS = new Map(Object.entries({
   "routine add": topic({
     title: "apx routine add",
     summary: "Create a scheduled routine.",
-    usage: ["apx routine add <name> --kind <kind> --schedule <schedule> [--spec '<json>'] [--pre-commands 'cmd1,cmd2'] [--post-commands 'cmd'] [--skip-prompt-on signal|pre_failure|pre_success|always|never] [--project <name|id|path>]"],
+    usage: ["apx routine add <name> --kind <kind> --schedule <schedule> [--spec '<json>'] [--pre-commands 'cmd1,cmd2'] [--post-commands 'cmd'] [--skip-prompt-on signal|pre_failure|pre_success|always|never] [--deliver-to telegram,web] [--project <name|id|path>]"],
     options: [
       ["--kind <kind>", "heartbeat, exec_agent, super_agent, telegram, shell, or watch."],
       ["--schedule <schedule>", "every:60s, every:5m, every:1h, or once:<iso>."],
@@ -1144,6 +1259,7 @@ export const HELP_TOPICS = new Map(Object.entries({
       ["--pre-commands 'cmd'", "Comma-separated shell commands to run BEFORE the LLM. Use 'artifact:<name>' shorthand."],
       ["--post-commands 'cmd'", "Comma-separated shell commands to run AFTER the LLM. Env: APX_LLM_OUTPUT, APX_PRE_OUTPUT, APX_STATUS."],
       ["--skip-prompt-on <mode>", "signal (default), pre_failure, pre_success, always, never."],
+      ["--deliver-to a,b", "Where the output goes: telegram, web, profile (ask the active agent profile), none. Unset means nowhere."],
       ["--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."],
@@ -1151,6 +1267,7 @@ export const HELP_TOPICS = new Map(Object.entries({
     examples: [
       "apx routine add check --kind shell --schedule every:1h --spec '{\"cmd\":\"npm test\"}'",
       "apx routine add asana-check --kind super_agent --schedule '*/5 * * * *' --pre-commands 'artifact:check_asana.sh' --skip-prompt-on pre_success --project 0",
+      "apx routine add standup --kind super_agent --schedule '30 8 * * 1-5' --spec '{\"prompt\":\"What needs attention today?\"}' --deliver-to telegram,web",
     ],
   }),
   "routine get": topic({
@@ -1411,7 +1528,7 @@ export const HELP_TOPICS = new Map(Object.entries({
   "skills inspector": topic({
     title: "apx skills inspector",
     summary:
-      "Toggle and tune the Skill Inspector (per-turn skill RAG). When ON: the static slug-dump in the system prompt is suppressed and a local RAG picks 0–N skills per turn — loading the body of high-confidence matches, hinting mid-confidence ones, injecting nothing below threshold. When OFF: legacy behaviour (full slug list + passive suggestion). Opt-in test feature.",
+      "Toggle and tune the Skill Inspector (per-turn skill RAG). When ON: the static slug-dump in the system prompt is suppressed and a local RAG picks 0–N skills per turn — loading the body of high-confidence matches, hinting mid-confidence ones, injecting nothing below threshold. When OFF: the static behaviour (full slug list + passive suggestion). Opt-in test feature.",
     usage: ["apx skills inspector [status|enable|disable|set <key> <value>]"],
     examples: [
       "apx skills inspector enable",
@@ -1453,15 +1570,21 @@ export const HELP_TOPICS = new Map(Object.entries({
   panel: topic({
     title: "apx panel",
     summary:
-      "Reach the admin panel from another device on the same network. Not a tunnel — nothing leaves your LAN, and loopback stays the default.",
-    usage: ["apx panel <status|share|unshare>"],
+      "Reach the admin panel from another device: on your own network with `share`, or from anywhere with `tailscale`. Loopback stays the default.",
+    usage: ["apx panel <status|share|unshare|tailscale>"],
     commands: [
       ["status", "Whether the panel is local only or shared, and on what address."],
       ["share", "Bind a LAN address and print the URL to open on your phone."],
       ["unshare", "Go back to local only."],
+      ["tailscale on", "Publish it at https://<machine>.<tailnet>.ts.net — works from anywhere on your tailnet, with a real certificate. Not `funnel`: nothing is public."],
+      ["tailscale off", "Stop publishing over HTTPS."],
+      ["tailscale status", "Whether Tailscale is up and what it publishes."],
     ],
     options: [["--host <ip>", "share: bind this address instead of the detected one."]],
-    examples: ["apx panel status", "apx panel share", "apx panel unshare"],
+    examples: ["apx panel status", "apx panel share", "apx panel tailscale on"],
+    notes: [
+      "Installing the panel as an app on a phone, recording a voice note, and copying to the clipboard all need a SECURE CONTEXT — https:// or localhost. A LAN address served over http:// has none of the three, whatever APX does, which is what `tailscale on` is for.",
+    ],
   }),
   profile: topic({
     title: "apx profile",
@@ -1473,6 +1596,7 @@ export const HELP_TOPICS = new Map(Object.entries({
       ["show | get <id>", "Details, settings and token cost of one profile."],
       ["install | add <id|path>", "Validate and install a profile. Does NOT activate it."],
       ["use | activate <id>", "Make a profile active and install its routines."],
+      ["sync", "Re-read the active package from disk after an APX update — refreshes its routines, keeps your settings and your edits."],
       ["off | deactivate", "Go back to vanilla. Disables its routines, deletes nothing."],
       ["config", "Show or change the active profile's settings."],
       ["doctor [<id>]", "What is missing for this profile to do its job."],
@@ -1489,6 +1613,7 @@ export const HELP_TOPICS = new Map(Object.entries({
       "apx profile install secretary",
       "apx profile use secretary",
       "apx profile config --set day_open_at=08:30 --set nudge_budget_per_day=3",
+      "apx profile sync",
       "apx profile show secretary --preview",
       "apx profile off",
     ],
@@ -1517,9 +1642,15 @@ export const HELP_TOPICS = new Map(Object.entries({
       ["--all", "list: fold every registered project into one list, each row labelled."],
       ["--status <s>", "list: workflow sub-status — pending | running | in_review | blocked."],
       ["--updated-since <ISO>", "list: only what moved since that moment."],
+      ["--category <c>", "add/patch: what kind of task — general | trip. A trip carries a place."],
+      ["--place \"<name>\"", "add/patch: the place this errand is at. Empty clears the location."],
+      ["--address \"<text>\"", "add/patch: street address of that place."],
+      ["--at \"<lat,lon>\"", "add/patch: pin it. A pinned trip task needs no place search and no model."],
+      ["--radius <m>", "add/patch: how close counts as \"there\" (default: the mobility radius)."],
     ],
     examples: [
       "apx task add \"Ship release notes\" --tag release --due 2026-06-01",
+      "apx task add \"Buy ibuprofen\" --category trip --place \"Pharmacy on Main\" --at \"-41.13,-71.31\"",
       "apx task list --state open --tag release",
       "apx task list --all --status blocked",
       "apx task done t_abc123",
@@ -1552,18 +1683,24 @@ export const HELP_TOPICS = new Map(Object.entries({
   "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]"],
+    usage: ["apx task add \"<title>\" [--project X] [--body Y] [--tag t]... [--due 2026-05-30] [--agent A] [--source S] [--category trip] [--place \"Farmacia X\"] [--at \"lat,lon\"] [--radius 1500]"],
     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)."],
+      ["--category <id>", "general (default) | trip. A trip task is an errand with a place, and mobility watches for it."],
+      ["--place <name>", "Where the errand is. Empty string clears it."],
+      ["--address <text>", "Street address, when the name alone is ambiguous."],
+      ["--at <lat,lon>", "Pin the exact spot. A pinned errand costs no place search and no model."],
+      ["--radius <m>", "How close counts as \"there\" for this errand (default 2000)."],
       ["--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",
+      "apx task add \"Comprar pan lactal\" --category trip --place \"La Anónima\" --at \"-41.13,-71.31\"",
     ],
   }),
   "task list": topic({
@@ -1741,7 +1878,101 @@ export const HELP_TOPICS = new Map(Object.entries({
     examples: ["apx desktop start"],
   }),
 
+  // ── Images (text-to-image) ────────────────────────────────────────────────
+  image: topic({
+    title: "apx image",
+    summary: "Text-to-image through the daemon's routed engine. Speaks three dialects — the AUTOMATIC1111 API (A1111, Forge, Draw Things, stable-diffusion.cpp), the native stable-diffusion.cpp async job API, and OpenAI-compatible /v1/images — so the same command drives a local server, a box on the LAN and a cloud key. Configure engines in Settings → Images or under `images.*` in ~/.apx/config.json.",
+    usage: [
+      "apx image \"<prompt>\" [--out <file>] [--provider <id>] [--size 768x512] [--steps N] [--cfg N]",
+      "apx image \"<prompt>\" [--seed N] [--negative \"...\"] [--count N] [--model <id>] [--format png|jpeg|webp]",
+      "apx image \"<prompt>\" --init <img> [--denoise 0.45]        # img2img: repaint that picture",
+      "apx image \"<prompt>\" --control <img> [--control-strength 0.8]  # ControlNet: keep its structure",
+      "apx image \"<prompt>\" --init <img> --mask <img> [--mask-blur 12]  # inpaint only the white area",
+      "apx image providers",
+      "apx image capabilities [--provider <id>]",
+    ],
+    commands: [
+      ["providers", "Which engines are configured, reachable and in what routing order."],
+      ["capabilities", "Models, samplers and schedulers a server actually offers."],
+    ],
+    options: [
+      ["--out <file>", "Copy the result here (a directory works too). Without it the path under ~/.apx/images/<date>/ is printed and nothing is written into your project."],
+      ["--provider <id>", "Force an engine: a1111 | sdcpp | openai | mock | custom:<slug>. Default: the configured routing."],
+      ["--size <WxH>", "e.g. 768x512. Or pass --width / --height separately."],
+      ["--steps N", "Sampling steps. A turbo checkpoint wants ~8; a standard one 20-30."],
+      ["--cfg N", "Guidance scale (cfg_scale). Turbo checkpoints want ~1.0."],
+      ["--seed N", "Fix the seed for a reproducible image. Default -1 (random)."],
+      ["--negative \"...\"", "What to keep out of the picture."],
+      ["--count N", "How many images in one run."],
+      ["--model <id>", "Checkpoint / model id, where the server can switch."],
+      ["--format <ext>", "png | jpeg | webp, where the server supports it."],
+      ["--init <img>", "img2img: start from this picture and repaint it. Alias: --img-ref. Needs an a1111-dialect engine."],
+      ["--denoise N", "With --init: how far the sampler may stray. ~0.3 retouches, 0.45 is the middle, >0.6 reinvents. Default 0.45. On a TURBO checkpoint (cfg 1.0) there is no classifier-free guidance, so the init image outvotes the prompt until ~0.75 — measured: 0.45 barely moves the geometry and the prompt does not land at all."],
+      ["--mask <img>", "Inpaint: with --init, repaint ONLY where the mask is white and leave the black areas byte-identical. Must be exactly the same size as --init. The one reliable way to change part of a picture and keep the rest of the scene."],
+      ["--mask-blur N", "Feather the mask edge by N px so the repaint blends instead of showing a hard seam. ~12 is a good start."],
+      ["--inpaint-fill <id>", "What the masked area starts from: original (default) | noise | fill | nothing. Use `noise` when the prompt has to override what is already there — on a turbo checkpoint `original` often leaves the region unchanged."],
+      ["--control <img>", "ControlNet: build a NEW picture around this one's structure (pose, composition, edges). Needs an sdcpp-dialect engine started with a ControlNet model."],
+      ["--control-strength N", "With --control: how hard the structure is enforced, 0..1. Default 0.8."],
+      ["--sampler <id>", "Sampler name (see `apx image capabilities`)."],
+      ["--scheduler <id>", "Scheduler name (see `apx image capabilities`)."],
+      ["--prompt \"...\"", "Pass the prompt explicitly — needed only when it is literally the word providers or capabilities."],
+      ["--json", "Machine-readable result: engine, resolved request, ignored options, file paths."],
+      ["--open", "Open the image in the OS viewer when it is done."],
+    ],
+    examples: [
+      "apx image \"a green origami fox on a white background\"",
+      "apx image \"portrait of a fox\" --size 768x512 --steps 8 --cfg 1.0 --out fox.png",
+      "apx image \"a logo sketch\" --provider a1111 --seed 123 --json",
+      "apx image \"same room, at night\" --init photo.png --denoise 0.45",
+      "apx image \"same room, at night\" --init photo.png --denoise 0.8 --steps 16   # turbo checkpoint",
+      "apx image \"a knight in armor\" --control pose.png --control-strength 0.8 --provider custom:sdxl_cn",
+      "apx image \"blonde hair\" --init portrait.png --mask hair.png --mask-blur 12 --denoise 0.75",
+      "apx image providers",
+      "apx image capabilities --provider sdcpp",
+    ],
+    notes: [
+      "Engines are tried in order (images.order) and the first reachable one wins, exactly like TTS routing; set images.mode=single to pin one. `mock` is always last and always available, so a call with nothing configured still returns a file instead of an error.",
+      "Not every engine honors every knob. The OpenAI dialect has no steps, cfg, sampler or negative prompt; stable-diffusion.cpp hosts one checkpoint and cannot switch models. Whatever an engine cannot honor is REPORTED after the run instead of being silently dropped.",
+      "The A1111 route is preferred over the native sdcpp one for the same server because only it carries steps and cfg — a turbo checkpoint left on a server's stock 20 steps / cfg 7 renders several times slower for a worse picture.",
+      "Ollama cannot generate images: it serves language and vision models, none of which produce pixels. For a local engine on macOS, point the a1111 provider at Draw Things' HTTP API (or any local A1111-compatible server) instead.",
+      "--init and --control are two different operations, not two names for one. --init makes the picture the canvas the sampler repaints (img2img); --control keeps only its structure and paints something new around it (ControlNet). No engine speaks both: --init rides the A1111 route, --control the native stable-diffusion.cpp one, so pick the matching --provider. Whichever an engine cannot honor is reported after the run.",
+      "To change ONE thing in a picture and keep the rest, use --mask, not a bigger --denoise. Raising denoise far enough for the prompt to land also lets the model rebuild the subject: it works for a global regrade (\"at night\", \"deep blue\") but loses the pose, the clothes and the face when the prompt describes the subject. A mask confines the change, so denoise ~0.75 inside it is safe.",
+      "A reference image is read by the CLI and sent as base64, so the daemon can live on another machine. The body cap is 2 MB — roughly a 1.4 MB file — and a bigger one is refused up front with a `sips -Z` command to shrink it.",
+      "Images are kept under ~/.apx/images/<date>/ so they are never written into a project checkout unless --out says so.",
+    ],
+  }),
+
   // ── Voice (TTS / mic round-trip) ──────────────────────────────────────────
+  transcribe: topic({
+    title: "apx transcribe",
+    summary: "Speech-to-text from audio OR video files (or stdin) using the daemon's whisper — the same STT engine the desktop overlay and Telegram voice notes use. Handles one file, many files, or a whole folder. The model is preloaded at daemon boot, so repeat calls hit a warm server.",
+    usage: [
+      "apx transcribe <file> [--lang <code>] [--provider local|openai|custom] [--json]",
+      "apx transcribe <a> <b> <c>          # bulk: one block per file",
+      "apx transcribe <dir>                # every audio/video file in a folder",
+      "cat clip.wav | apx transcribe - [--format webm|ogg|wav|mp3]",
+    ],
+    options: [
+      ["--lang <code>", "ISO language (e.g. es, en). Default: auto-detect."],
+      ["--provider <id>", "Override STT routing: local (embedded whisper) | openai (cloud) | custom (any OpenAI-compatible server on the LAN/remote). Default: config."],
+      ["--json", "Machine-readable output: the result object for one file, or an array of {file, ...} in bulk."],
+      ["--format <ext>", "Audio format hint for stdin input (default webm)."],
+    ],
+    examples: [
+      "apx transcribe nota.oga",
+      "apx transcribe reunion.mp4                 # video: the audio track is pulled out",
+      "apx transcribe voz.webm --lang es",
+      "apx transcribe *.mp3 --json > out.json     # bulk to JSON",
+      "apx transcribe ./notas-de-voz/             # a whole folder",
+      "cat clip.wav | apx transcribe -",
+    ],
+    notes: [
+      "Audio: webm, ogg/oga, opus, m4a, aac, mp3, wav, flac. Video: mp4, mov, mkv, m4v, avi, 3gp… — ffmpeg extracts the audio track. The container is probed from the bytes, so the extension is only a hint.",
+      "Single file → clean transcript on stdout (pipe-friendly). Many files or a folder → a '── name ──' header per file. The APX banner goes to stderr, so stdout stays scriptable.",
+      "Bulk runs sequentially (the local model is single-instance) and keeps going past a failed file, exiting non-zero if any failed.",
+      "Long media can take a while; the daemon allows up to 20 minutes per request. A GPU backend (mlx on Apple Silicon, faster-whisper cuda on NVIDIA) is picked automatically for the local provider.",
+    ],
+  }),
   voice: topic({
     title: "apx voice",
     summary: "Speak text through the daemon TTS, run a mic→reply round-trip, or list providers.",
@@ -1897,6 +2128,8 @@ export const HELP_ALIASES = new Map(Object.entries({
   "project rm": "project remove",
   "agent ls": "agent list",
   "agent show": "agent get",
+  "agent edit": "agent set",
+  "agent update": "agent set",
   "agent vault ls": "agent vault list",
   "session ls": "session list",
   "session show": "session get",
@@ -2010,7 +2243,8 @@ export function buildHelp(version) {
     hCmd("apx project rebuild [id]",   36, "rebuild project index from filesystem"),
 
     hSec("Agents"),
-    hCmd("apx agent add <slug>",       36, "--role R  --model M  --skills a,b  --language es-AR  --description D"),
+    hCmd("apx agent add <slug>",       36, "--prompt -  --role R  --model M  --skills a,b  --language es-AR  --description D"),
+    hCmd("apx agent set <slug>",       36, "edit the system prompt (--prompt -) and/or any field"),
     hCmd("apx agent list",             36, ""),
     hCmd("apx agent get <slug>",       36, ""),
     hCmd("apx agent remove <slug>",    36, "delete a project agent (file + runtime memory)"),
@@ -2046,7 +2280,7 @@ export function buildHelp(version) {
     hCmd("apx session close <id>",     36, "--result \"text\""),
     hCmd("apx session check",          36, "anti-collision: exit 1 if active session"),
     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 resume <id>",    36, "--summary  --full  --continue [--msg \"<text>\"]  (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"),
@@ -2074,7 +2308,7 @@ export function buildHelp(version) {
     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"),
+    hCmd("apx daemon logs",            36, "--tail N  raw daemon stdout log"),
     hCmd("apx log",                    36, "unified log (all modules)  -f follow  --tail N  --errors only"),
 
     hSec("Telegram"),
@@ -2097,7 +2331,7 @@ export function buildHelp(version) {
     hCmd("apx acp",                    36, "serve the super-agent over the Agent Client Protocol (stdio, for IDEs)"),
 
     hSec("Runtimes"),
-    hCmd("apx run <agent>",            36, "--runtime <id> \"prompt\"  --timeout <s>"),
+    hCmd("apx run [-a <agent>]",       36, "--runtime <id> \"prompt\"  --timeout <s>"),
     `                                        ${H.DI}runtimes: claude-code | codex | opencode | aider | cursor-agent | gemini-cli | qwen-code | antigravity${H.R}`,
     hCmd("apx env detect",             36, "which agent CLIs are installed"),
 
@@ -2150,10 +2384,15 @@ export 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"),
+    hSec("Images"),
+    hCmd("apx image \"<prompt>\"",      36, "text-to-image via the routed engine  --out  --size  --steps  --cfg  --provider"),
+    hCmd("apx image providers",        36, "which image engines are configured and reachable"),
+
+    hSec("Voice & Desktop"),
     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 transcribe <file…|dir>", 36, "STT of audio/video via the warm daemon whisper — bulk-capable  --lang es  --provider  --json"),
     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"),