@agentprojectcontext/apx 1.36.0 → 1.38.0

package/README.md

@@ -1,8 +1,30 @@
 <p align="center">
-  <img src="assets/hero.png" alt="APX — Local Runtime for AI Agents" width="600">
+  <img src="assets/banner.svg" alt="APX — Agent Project eXecutable" width="820">
 </p>
 
-> The reference implementation of the [APC protocol](https://github.com/agentprojectcontext/agentprojectcontext).
+<p align="center">
+  <b>APX</b> &mdash; <b>A</b>gent <b>P</b>roject e<b>X</b>ecutable.<br>
+  A local runtime, CLI and web admin for AI agents, built on the
+  <a href="https://github.com/agentprojectcontext/agentprojectcontext">APC protocol</a>.
+</p>
+
+<p align="center">
+  <a href="https://agentprojectcontext.github.io/apx/"><img src="https://img.shields.io/badge/Website-agentprojectcontext.github.io-3fb950?style=flat-square&logo=googlechrome&logoColor=white" alt="Website"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-3fb950?style=flat-square" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/Node.js-20%2B-3fb950?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js 20+">
+  <a href="https://github.com/agentprojectcontext/agentprojectcontext"><img src="https://img.shields.io/badge/Protocol-APC-3fb950?style=flat-square" alt="APC protocol"></a>
+</p>
+
+<p align="center">
+  <b><a href="https://agentprojectcontext.github.io/apx/">🌐 Visit the website</a></b> &nbsp;&middot;&nbsp;
+  <a href="#quick-start">Quick start</a> &middot;
+  <a href="#examples">Examples</a> &middot;
+  <a href="#web-admin">Web admin</a> &middot;
+  <a href="#use-cases">Use cases</a> &middot;
+  <a href="https://github.com/agentprojectcontext/agentprojectcontext">APC spec</a>
+</p>
+
+> APX is the reference implementation of the [APC protocol](https://github.com/agentprojectcontext/agentprojectcontext).
 > APX is to APC what a language SDK is to a protocol spec.
 
 ## What APX is
@@ -11,6 +33,7 @@ APX is a daemon + CLI that brings the APC convention to life:
 
 - **Daemon** — a local HTTP server that manages projects, agents, sessions, and message logs
 - **CLI** (`apx`) — commands for running agents, reading memory, tailing messages, managing sessions
+- **Web admin** — a local web UI served by the daemon to browse projects, agents, sessions, and MCPs from the browser
 - **Runtimes** — bridges to Claude Code, Codex, OpenCode, Aider
 - **Engines** — direct LLM calls via Anthropic, OpenAI, Gemini, Ollama, or a mock
 - **Plugins** — Telegram bot integration out of the box
@@ -18,12 +41,27 @@ APX is a daemon + CLI that brings the APC convention to life:
 
 APX is opinionated about storage: the filesystem is the source of truth. Project definitions and curated memory live in the repo. Runtime state such as sessions, conversations, messages, and caches lives in `~/.apx/` and is never committed.
 
+<div align="center">
+<pre>
+   ▄███████▄
+  █ ██   ██ █
+  █  ◕   ◕  █
+  █    ‿    █
+   ▀███████▀
+</pre>
+<sub>Meet <b>Roby</b> — your project's super-agent. He greets you across the <code>apx</code> CLI and the web admin.</sub>
+</div>
+
 ## Quick start
 
 ```bash
+# 1 · Install
 npm install -g apx
 
-# In any directory with an AGENTS.md
+# 2 · Set up — interactive wizard (provider → model → channels → daemon)
+apx setup
+
+# In any directory with an AGENTS.md, register the project
 apx init
 
 # Spawn an agent with a full external runtime
@@ -36,6 +74,27 @@ apx exec sofia "What is my role in this project?"
 apx messages tail
 ```
 
+## Examples
+
+Real commands — copy one, point it at an agent like `sofia`, and APX routes it to the right
+runtime. The session and memory land in `.apc/`.
+
+| What | Command |
+|------|---------|
+| Register a project | `apx init` |
+| Spawn an agent (full runtime) | `apx run sofia --runtime claude-code "Review the open PRs and summarize them"` |
+| Ask a quick question (one-shot) | `apx exec sofia "What is my role in this project?"` |
+| Read an agent's memory | `apx memory sofia` |
+| Switch runtime, same context | `apx run sofia --runtime codex "Add tests for the parser"` |
+| Watch what's happening | `apx messages tail` |
+
+## Use cases
+
+- **Review PRs across any runtime** — point an agent at your repo; APX routes to Claude Code and falls back to Codex or OpenCode if one isn't installed. The session and its summary land in `.apc/`.
+- **Operate your agents from Telegram** — talk to project agents from your phone. Identity roles gate who can do what, and every message is logged per channel for a full audit trail.
+- **Memory that lives in your repo** — curated, per-agent memory is plain markdown, committed and reviewable alongside your code. No vendor database, no hidden state, no lock-in.
+- **Run the same prompt across engines** — send one prompt through Anthropic, OpenAI, Gemini or a local Ollama model with `apx exec`, configured per project or globally.
+
 ## Installation
 
 ```bash
@@ -44,6 +103,25 @@ npm install -g apx
 
 Requires Node.js 20+. The daemon starts automatically on first `apx` call.
 
+## Web admin
+
+APX ships a local **web admin** — the same runtime, in your browser. The daemon serves a
+single-page app so you can browse and manage everything the CLI does without leaving the UI:
+
+- **Projects & agents** — see registered projects, open agents, edit roles, models, and skills
+- **Sessions & messages** — read past sessions and tail live activity across every channel
+- **MCPs, engines & channels** — review MCP servers, configure engines, and manage Telegram/desktop
+
+It runs entirely on your machine. Start the daemon (any `apx` call does this) and open:
+
+```bash
+apx            # ensures the daemon is up
+open http://localhost:7430   # macOS — or just visit it in any browser
+```
+
+The web admin is served from `src/interfaces/web/dist` at the daemon port (`7430` by default,
+override with `APX_PORT`). Nothing is sent anywhere — it talks to the local daemon only.
+
 ## Project layout
 
 Project context — committed to the repository:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/src/core/mascot.js

@@ -1,122 +1,122 @@
-// APX mascot — a panda that appears in different moods across the CLI.
+// APX mascot — "Roby", a little terminal critter that shows up across the CLI.
 // Usage: import { mascot } from '#core/mascot.js'; mascot('happy');
+//
+// Same character as the web Splash/404 ("Roby"): a chunky ▄███████▄ head with
+// two screen-eyes and a tiny mouth. Rendered as clean emerald-green line art on
+// the terminal's own background — no heavy black-on-white blocks, no stray legs.
+// Kept deliberately simple and a touch hand-made, not a photoreal sprite.
 
 const R = "\x1b[0m";
 const B = "\x1b[1m";
-const W = "\x1b[97m";       // bright white
-const BK = "\x1b[40m";      // bg black
-const CY = "\x1b[36m";
-const YE = "\x1b[33m";
-const GR = "\x1b[32m";
-const RE = "\x1b[31m";
 const DI = "\x1b[2m";
-const BL = "\x1b[34m";
 
-// Each mood: [panda lines, caption]
+// Honor NO_COLOR; otherwise tint in emerald to match the web Roby (text-emerald).
+const NO_COLOR = !!process.env.NO_COLOR;
+const truecolor = /truecolor|24bit/i.test(process.env.COLORTERM || "");
+
+function rgb(r, g, b) {
+  if (NO_COLOR) return "";
+  if (truecolor) return `\x1b[38;2;${r};${g};${b}m`;
+  // 6x6x6 cube fallback for 256-color terminals.
+  const q = (v) => Math.round((v / 255) * 5);
+  return `\x1b[38;5;${16 + 36 * q(r) + 6 * q(g) + q(b)}m`;
+}
+
+// Two emerald tones: a bright frame and a dimmer "screen" green for the eyes,
+// so the face reads without resorting to a second background colour.
+const G = rgb(52, 211, 153);   // emerald-400 — frame, mouth, pupils
+const GD = rgb(20, 120, 92);   // dim emerald — recessed eye screens
+const reset = NO_COLOR ? "" : R;
+const bold = NO_COLOR ? "" : B;
+const dim = NO_COLOR ? "" : DI;
+
+// Caption colours per mood (still emerald-family, just a nudge of hue).
+const C_OK = rgb(52, 211, 153);
+const C_INFO = rgb(94, 198, 255);
+const C_WARN = rgb(240, 200, 90);
+const C_BAD = rgb(240, 110, 110);
+
+// Build Roby's head. `eyes` is [left, right] pupils; `mouth` is one glyph;
+// `top` is an optional floating accent that hovers over the head.
+function buildRoby({ eyes, mouth, top = "" }) {
+  const [el, er] = eyes;
+  const lines = [];
+  lines.push(top ? `      ${dim}${top}${reset}` : "");
+  lines.push(`   ${G}▄███████▄${reset}`);
+  // Eye screens: dim ██ sockets set into the bright frame.
+  lines.push(`  ${G}█ ${GD}██${G}   ${GD}██${G} █${reset}`);
+  // Pupils + mouth, each a single green run (clean, no inline colour breaks).
+  lines.push(`  ${G}█  ${el}   ${er}  █${reset}`);
+  lines.push(`  ${G}█    ${mouth}    █${reset}`);
+  lines.push(`   ${G}▀███████▀${reset}`);
+  return lines.filter((l, i) => !(i === 0 && l === ""));
+}
+
 const MOODS = {
   // ─── happy: default greeting / daemon started ────────────────────────────
   happy: {
-    color: GR,
-    lines: [
-      `   ${BK}${W}  ▄███████▄  ${R}`,
-      `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}`,
-      `  ${BK}${W} █  ◕   ◕  █ ${R}`,
-      `  ${BK}${W} █   ╰ω╯   █ ${R}`,
-      `   ${BK}${W}  ▀███████▀  ${R}`,
-      `   ${DI}   ╱  ╲  ╱  ╲   ${R}`,
-    ],
-    caption: `${GR}${B}ready to go!${R}`,
+    caption: "ready to go!",
+    color: C_OK,
+    lines: buildRoby({ eyes: ["◕", "◕"], mouth: "‿" }),
   },
 
   // ─── wave: first run / setup ─────────────────────────────────────────────
   wave: {
-    color: CY,
-    lines: [
-      `   ${BK}${W}  ▄███████▄  ${R}   ${DI}/)${R}`,
-      `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}  ${DI}//${R}`,
-      `  ${BK}${W} █  ◕   ◕  █ ${R} ${DI}//${R}`,
-      `  ${BK}${W} █   ╰▽╯   █ ${R}${DI}/${R}`,
-      `   ${BK}${W}  ▀███████▀  ${R}`,
-      `   ${DI}   ╱  ╲  ╱  ╲   ${R}`,
-    ],
-    caption: `${CY}${B}APX — Agent Project Context${R}`,
+    caption: "APX — Agent Project Context",
+    color: C_OK,
+    lines: buildRoby({ eyes: ["◕", "◕"], mouth: "▽", top: "·" }),
   },
 
-  // ─── confused: unknown command / not found ────────────────────────────────
+  // ─── confused: unknown command / not found (the web 404 "lost" Roby) ──────
   confused: {
-    color: YE,
-    lines: [
-      `   ${BK}${W}  ▄███████▄  ${R}  ${YE}?${R}`,
-      `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}`,
-      `  ${BK}${W} █  ◔   ◔  █ ${R}`,
-      `  ${BK}${W} █   ╰~╯   █ ${R}`,
-      `   ${BK}${W}  ▀███████▀  ${R}`,
-      `   ${DI}   ╱  ╲  ╱  ╲   ${R}`,
-    ],
-    caption: `${YE}${B}hmm, I don't know that one${R}`,
+    caption: "hmm, I don't know that one",
+    color: C_WARN,
+    lines: buildRoby({ eyes: ["◑", "◐"], mouth: "o", top: "?" }),
   },
 
   // ─── sad: error ───────────────────────────────────────────────────────────
   sad: {
-    color: RE,
-    lines: [
-      `   ${BK}${W}  ▄███████▄  ${R}`,
-      `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}`,
-      `  ${BK}${W} █  ╥   ╥  █ ${R}`,
-      `  ${BK}${W} █   ╰︵╯   █ ${R}`,
-      `   ${BK}${W}  ▀███████▀  ${R}`,
-      `   ${DI}   ╱  ╲  ╱  ╲   ${R}`,
-    ],
-    caption: `${RE}${B}something went wrong${R}`,
+    caption: "something went wrong",
+    color: C_BAD,
+    lines: buildRoby({ eyes: ["╥", "╥"], mouth: "︵" }),
   },
 
   // ─── excited: update available ────────────────────────────────────────────
   excited: {
-    color: BL,
-    lines: [
-      `   ${BK}${W}  ▄███████▄  ${R}  ${BL}↑${R}`,
-      `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}`,
-      `  ${BK}${W} █  ★   ★  █ ${R}`,
-      `  ${BK}${W} █   ╰◡╯   █ ${R}`,
-      `   ${BK}${W}  ▀███████▀  ${R}`,
-      `   ${DI}   ╱  ╲  ╱  ╲   ${R}`,
-    ],
-    caption: `${BL}${B}new version available!${R}`,
+    caption: "new version available!",
+    color: C_INFO,
+    lines: buildRoby({ eyes: ["★", "★"], mouth: "▽", top: "✦" }),
   },
 
   // ─── sleeping: daemon not running ────────────────────────────────────────
   sleeping: {
-    color: DI,
-    lines: [
-      `   ${BK}${W}  ▄███████▄  ${R}  ${DI}z z z${R}`,
-      `  ${BK}${W} █ ${R}${B}██${R}${W}   ${B}██${R}${BK}${W} █ ${R}`,
-      `  ${BK}${W} █  −   −  █ ${R}`,
-      `  ${BK}${W} █   ╰_╯   █ ${R}`,
-      `   ${BK}${W}  ▀███████▀  ${R}`,
-      `   ${DI}   ╱  ╲  ╱  ╲   ${R}`,
-    ],
-    caption: `${DI}${B}daemon is not running${R}`,
+    caption: "daemon is not running",
+    color: rgb(150, 150, 150),
+    lines: buildRoby({ eyes: ["−", "−"], mouth: "‿", top: "z z" }),
   },
 };
 
-// Print the mascot to stderr (doesn't interfere with piped output).
+// Print the mascot to stderr (doesn't interfere with piped stdout).
 // mood: 'happy' | 'wave' | 'confused' | 'sad' | 'excited' | 'sleeping'
 export function mascot(mood = "happy", message = "") {
   const def = MOODS[mood] || MOODS.happy;
   const out = [
     "",
     ...def.lines,
-    `      ${def.caption}`,
-    message ? `   ${def.color}${message}${R}` : "",
     "",
-  ].join("\n");
+    `   ${def.color}${bold}${def.caption}${reset}`,
+    message ? `   ${dim}${message}${reset}` : "",
+    "",
+  ]
+    .filter((l, i, a) => !(l === "" && a[i - 1] === ""))
+    .join("\n");
   process.stderr.write(out + "\n");
 }
 
 // One-liner for inline use: mascot.confused("apx: unknown command: foo")
-mascot.confused  = (msg) => mascot("confused",  msg);
-mascot.sad       = (msg) => mascot("sad",       msg);
-mascot.happy     = (msg) => mascot("happy",     msg);
-mascot.wave      = (msg) => mascot("wave",      msg);
-mascot.excited   = (msg) => mascot("excited",   msg);
-mascot.sleeping  = (msg) => mascot("sleeping",  msg);
+mascot.confused = (msg) => mascot("confused", msg);
+mascot.sad = (msg) => mascot("sad", msg);
+mascot.happy = (msg) => mascot("happy", msg);
+mascot.wave = (msg) => mascot("wave", msg);
+mascot.excited = (msg) => mascot("excited", msg);
+mascot.sleeping = (msg) => mascot("sleeping", msg);

package/src/host/daemon/api/agents.js

@@ -245,12 +245,18 @@ export function register(app, { projects, project }) {
   app.get("/projects/:pid/agents/:slug/memory", (req, res) => {
     const p = project(req, res);
     if (!p) return;
+    // Validate the agent exists — otherwise an unknown slug returned 200 with an
+    // empty body, masking typos (QA BUG-API-1).
+    if (!readAgents(p.path).some((a) => a.slug === req.params.slug))
+      return res.status(404).json({ error: "agent not found" });
     res.json({ body: readAgentMemory(p, req.params.slug) });
   });
 
   app.put("/projects/:pid/agents/:slug/memory", (req, res) => {
     const p = project(req, res);
     if (!p) return;
+    if (!readAgents(p.path).some((a) => a.slug === req.params.slug))
+      return res.status(404).json({ error: "agent not found" });
     const { body } = req.body || {};
     if (typeof body !== "string")
       return res.status(400).json({ error: "body must be string" });

package/src/host/daemon/api/conversations.js

@@ -11,11 +11,18 @@ import { replyAsAgent } from "#core/agent/a2a/reply.js";
 import { nowIso } from "./shared.js";
 
 export function register(app, { project, config }) {
+  // The super-agent (default name "apx") is a pseudo-agent: it owns
+  // conversations per project but is NOT listed in AGENTS.md. Resolve its slug
+  // so `apx conversations list` (which defaults to the super-agent) works
+  // instead of 404-ing on the AGENTS.md check.
+  const superAgentSlug = () => config?.super_agent?.name || "apx";
+  const agentResolvable = (p, slug) =>
+    slug === superAgentSlug() || readAgents(p.path).some((a) => a.slug === slug);
+
   app.get("/projects/:pid/agents/:slug/conversations", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const agents = readAgents(p.path);
-    if (!agents.find((a) => a.slug === req.params.slug))
+    if (!agentResolvable(p, req.params.slug))
       return res.status(404).json({ error: "agent not found" });
     res.json(listConversations(p.storagePath, req.params.slug));
   });

package/src/host/daemon/api/web.js

@@ -27,13 +27,29 @@ const API_PREFIXES = [
   "/super-agent", "/identity",
 ];
 
-function isApiPath(p) {
+export function isApiPath(p) {
   for (const prefix of API_PREFIXES) {
     if (p === prefix || p.startsWith(prefix + "/")) return true;
   }
   return false;
 }
 
+// Client-side routes the SPA actually knows how to render. Must mirror the
+// <Routes> registry in src/interfaces/web/src/App.tsx. Anything else still
+// gets the SPA shell (so React Router shows the styled 404 page) but with an
+// HTTP 404 status, so curl/crawlers/health-checks see the right code instead
+// of a misleading 200.
+const SPA_ROUTES = [
+  /^\/$/,
+  /^\/settings(\/.*)?$/,
+  /^\/m\/(voice|desktop|deck|code)(\/.*)?$/,
+  /^\/p\/[^/]+(\/.*)?$/,
+];
+
+export function isKnownSpaRoute(p) {
+  return SPA_ROUTES.some((re) => re.test(p));
+}
+
 export function register(app, { express, token }) {
   // /admin/web-token: localhost-only endpoint that returns the daemon token
   // so the same-origin admin panel can authenticate every subsequent call.
@@ -118,6 +134,9 @@ export function register(app, { express, token }) {
     if (req.method !== "GET") return next();
     if (isApiPath(req.path)) return next();
     if (path.extname(req.path)) return next(); // let static handle 404 of /foo.png
+    // Always serve the shell so the SPA can render, but set 404 for routes the
+    // app doesn't recognize so the HTTP status matches what the user sees.
+    res.status(isKnownSpaRoute(req.path) ? 200 : 404);
     res.sendFile(path.join(WEB_DIST, "index.html"));
   });
 }

package/src/host/daemon/desktop-ws.js

@@ -10,6 +10,37 @@ export function setDesktopMessageHandler(fn) {
   _messageHandler = fn;
 }
 
+// --- WS upgrade auth helpers (shared by the daemon upgrade handler + tests) ---
+//
+// The desktop WS channel must authenticate the same way the HTTP /desktop/*
+// routes do: a bearer token (master or paired client) carried on the upgrade
+// request. The legitimate desktop window sends `Authorization: Bearer <token>`
+// (src/interfaces/desktop/main.js); browser clients can pass `?token=`. Without
+// this the daemon (which binds 0.0.0.0 by default) would let any LAN client open
+// the channel and drive the super-agent. See QA BUG-WS-AUTH.
+
+/** Path-gate: is this upgrade for the desktop (or legacy overlay) WS channel? */
+export function isDesktopUpgradePath(url) {
+  let pathname = url || "";
+  try { pathname = new URL(url, "http://localhost").pathname; } catch { /* keep raw */ }
+  return pathname === "/desktop/ws" || pathname === "/overlay/ws";
+}
+
+/** Extract the bearer token from the upgrade request (header first, ?token= fallback). */
+export function extractWsToken(req) {
+  const auth = (req && req.headers && req.headers["authorization"]) || "";
+  if (auth.startsWith("Bearer ")) return auth.slice(7);
+  try {
+    return new URL((req && req.url) || "", "http://localhost").searchParams.get("token") || "";
+  } catch { return ""; }
+}
+
+/** True iff the upgrade request carries a token the store recognizes. */
+export function isDesktopUpgradeAuthorized(req, tokenStore) {
+  if (!tokenStore || typeof tokenStore.has !== "function") return false;
+  return tokenStore.has(extractWsToken(req));
+}
+
 export function registerDesktopClient(ws) {
   _clients.add(ws);
   ws.on("close", () => _clients.delete(ws));

package/src/host/daemon/index.js

@@ -22,7 +22,7 @@ import { RoutineScheduler } from "./routines-scheduler.js";
 import { buildApi } from "./api.js";
 import { createTokenStore } from "./token-store.js";
 import { triggerWakeup } from "./wakeup.js";
-import { registerDesktopClient } from "./desktop-ws.js";
+import { registerDesktopClient, isDesktopUpgradePath, isDesktopUpgradeAuthorized } from "./desktop-ws.js";
 import { log as logToUnified } from "#core/logging.js";
 import { initMemory, stopMemory } from "#core/memory/index.js";
 
@@ -247,7 +247,17 @@ async function main() {
   // Attach WebSocket upgrade for the desktop channel on /desktop/ws
   // (legacy /overlay/ws still accepted for one release).
   server.on("upgrade", async (req, socket, head) => {
-    if (req.url !== "/desktop/ws" && req.url !== "/overlay/ws") { socket.destroy(); return; }
+    if (!isDesktopUpgradePath(req.url)) { socket.destroy(); return; }
+    // Auth: the WS upgrade must carry a valid token (master or paired client),
+    // matching the HTTP /desktop/* routes. Without this, any client that can
+    // reach the daemon (host binds 0.0.0.0 → the LAN) could open the desktop
+    // channel and drive the super-agent (permission_mode "total"). The
+    // legitimate desktop window already sends the bearer token. See QA BUG-WS-AUTH.
+    if (!isDesktopUpgradeAuthorized(req, tokenStore)) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+      socket.destroy();
+      return;
+    }
     // Lazy-import ws to avoid hard dep on startup
     let WebSocketServer;
     try { ({ WebSocketServer } = await import("ws")); } catch {

package/src/interfaces/cli/commands/agent.js

@@ -5,6 +5,7 @@ import { apcAgentFile } from "#core/apc/paths.js";
 import { writeAgentFile, writeVaultAgentFile, removeVaultAgent, restoreVaultAgent, addImportedAgent, ensureAgentDir } from "#core/apc/scaffold.js";
 import { ensureAgentRuntimeDir, agentMemoryPath } from "#core/agent/memory.js";
 import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
 
 // ── ANSI ──────────────────────────────────────────────────────────────────────
 const c = { reset:"\x1b[0m", bold:"\x1b[1m", dim:"\x1b[2m", cyan:"\x1b[36m", green:"\x1b[32m", yellow:"\x1b[33m", gray:"\x1b[90m" };
@@ -100,6 +101,25 @@ export function cmdAgentGet(args) {
   console.log();
 }
 
+export async function cmdAgentRemove(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx agent remove: missing <slug> — usage: apx agent remove <slug>");
+  // Resolve locally first so we can give a clear message + suggestions instead
+  // of a bare 404 when the slug is wrong.
+  const root = findApfRoot();
+  if (root) {
+    const local = readAgents(root).find((a) => a.slug === slug);
+    if (!local) {
+      const inVault = readVaultAgents().find((v) => v.slug === slug);
+      if (inVault) throw new Error(`agent "${slug}" is in the vault but not in this project — nothing to remove here (use \`apx agent vault rm ${slug}\` to delete the template)`);
+      throw new Error(`agent "${slug}" not found in this project — run \`apx agent list\` to see the agents you can remove`);
+    }
+  }
+  const pid = await resolveProjectId(args?.flags?.project);
+  await http.delete(`/projects/${pid}/agents/${slug}`);
+  console.log(`${tag("removed")}  ${bold(slug)}  ${gray("(agent file + runtime memory deleted)")}`);
+}
+
 // ── Vault commands ────────────────────────────────────────────────────────────
 
 export function cmdAgentVaultList(args = { flags: {} }) {

package/src/interfaces/cli/commands/chat.js

@@ -1,6 +1,13 @@
 import readline from "node:readline";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
+import { readConfig } from "#core/config/index.js";
+
+// The super-agent (default name "apx") is the default conversational agent, so
+// `apx conversations list` (no slug) targets it — no need to spell it out.
+function superAgentSlug() {
+  try { return readConfig()?.super_agent?.name || "apx"; } catch { return "apx"; }
+}
 
 export async function cmdChat(args) {
   const slug = args._[0];
@@ -51,12 +58,12 @@ export async function cmdChat(args) {
 }
 
 export async function cmdConversationsList(args) {
-  const slug = args._[0];
-  if (!slug) throw new Error("apx conversations list: missing <agent-slug>");
+  // No slug → the super-agent (default conversational agent).
+  const slug = args._[0] || superAgentSlug();
   const pid = await resolveProjectId(args?.flags?.project);
   const rows = await http.get(`/projects/${pid}/agents/${slug}/conversations`);
   if (rows.length === 0) {
-    console.log("(no conversations)");
+    console.log(`(no conversations for ${slug})`);
     return;
   }
   console.log("ID".padEnd(16) + " ENGINE".padEnd(35) + " TURNS  STATUS");
@@ -72,9 +79,11 @@ export async function cmdConversationsList(args) {
 }
 
 export async function cmdConversationsGet(args) {
-  const slug = args._[0];
-  const id = args._[1];
-  if (!slug || !id) throw new Error("apx conversations get: usage: apx conversations get <agent> <id>");
+  // Two forms: `get <agent> <id>` or `get <id>` (→ super-agent).
+  let slug, id;
+  if (args._.length >= 2) { slug = args._[0]; id = args._[1]; }
+  else { slug = superAgentSlug(); id = args._[0]; }
+  if (!id) throw new Error("apx conversations get: usage: apx conversations get [<agent>] <id>");
   const pid = await resolveProjectId(args?.flags?.project);
   const conv = await http.get(`/projects/${pid}/agents/${slug}/conversations/${id}`);
   process.stdout.write(`# Conversation ${id} (${slug})\n`);

package/src/interfaces/cli/commands/identity.js

@@ -46,8 +46,27 @@ export async function cmdIdentity(args) {
     if (args.flags.personality && args.flags.personality !== true) fields.personality = args.flags.personality;
     if (args.flags.language && args.flags.language !== true) fields.language = args.flags.language;
 
+    // Positional form documented in help: `apx identity set <key> <value>`.
+    const KEY_TO_FIELD = {
+      name: "agent_name", owner: "owner_name", context: "owner_context",
+      personality: "personality", language: "language",
+      agent_name: "agent_name", owner_name: "owner_name", owner_context: "owner_context",
+    };
+    const pKey = args._[1];
+    const pVal = args._.slice(2).join(" ");
+    if (pKey && pVal) {
+      const field = KEY_TO_FIELD[pKey];
+      if (!field) {
+        console.error(`unknown identity key "${pKey}". Known: name, owner, context, personality, language`);
+        process.exitCode = 2;
+        return;
+      }
+      fields[field] = pVal;
+    }
+
     if (Object.keys(fields).length === 0) {
-      console.log("Usage: apx identity set --name <name> --owner <name> --context <text> --personality <text> --language <lang>");
+      console.log("Usage: apx identity set <key> <value>   (keys: name, owner, context, personality, language)");
+      console.log("   or: apx identity set --name <name> --owner <name> --context <text> --personality <text> --language <lang>");
       return;
     }
 

package/src/interfaces/cli/commands/update.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { getLatestVersion } from "#core/update-check.js";
+import { apxBanner } from "../branding.js";
 
 const PACKAGE_NAME = "@agentprojectcontext/apx";
 
@@ -58,6 +59,7 @@ function daemonRunning() {
 export async function cmdUpdate(args, currentVersion) {
   const force = args.flags.force || args.flags.yes || args.flags.y;
 
+  apxBanner(currentVersion, "update");
   console.log("Checking for updates...");
   const latest = await getLatestVersion();