@agentprojectcontext/apx 1.0.3 → 1.2.0

package/README.md

@@ -16,7 +16,7 @@ APX is a daemon + CLI that brings the APC convention to life:
 - **Plugins** — Telegram bot integration out of the box
 - **MCP support** — each agent can expose or consume MCP servers
 
-APX is opinionated about storage: the filesystem is the source of truth. No database required to read agent state. Project definitions live in the repo; runtime state (memory, sessions) lives in `~/.apx/` and is never committed.
+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.
 
 ## Quick start
 
@@ -65,13 +65,12 @@ Runtime state — local machine only, never committed:
 ```text
 ~/.apx/projects/<project-id>/
 ├── project.db             ← regenerable SQLite cache
+├── messages/              ← local message history
 └── agents/
     ├── <slug>/
-    │   ├── memory.md      ← durable memory, updated by the agent
     │   ├── sessions/      ← one .md per runtime invocation
     │   └── conversations/ ← LLM conversation threads
     └── default/           ← fallback when no agent role is active
-        ├── memory.md
         └── sessions/
 ```
 
@@ -94,7 +93,8 @@ apx messages tail --channel runtime      # only agent invocations
 
 ## Message channels
 
-All activity is logged to `.apc/messages/YYYY-MM-DD.jsonl`:
+Activity belongs to APX runtime state, not `.apc/`. Message storage is local to APX, under
+`~/.apx/`:
 
 | Channel | What it captures |
 |---------|-----------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -33,7 +33,10 @@
     "node-fetch": "^3.3.2"
   },
   "devDependencies": {
-    "better-sqlite3": "^11.3.0"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "better-sqlite3": "^11.3.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1"
   },
   "keywords": [
     "apc",

package/skills/apx/SKILL.md

@@ -4,11 +4,13 @@ description: "APX CLI skill. Activate ONLY when the user asks about running agen
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
-# APX — Agent Project Framework
+# APX — Agent Project Context Runtime
 
 This project uses **APX**. The daemon runs on `127.0.0.1:7430` and auto-starts on first `apx` call.
 Your current session, project, and agent are already injected above this block — refer to them.
 
+APX runtime state belongs outside `.apc/`, under `~/.apx/projects/<project-id>/`.
+
 ---
 
 ## Discover the project
@@ -32,7 +34,7 @@ apx exec <slug> "<prompt>"
 The output of `apx run` / `apx exec` is the agent's full stdout.
 If the agent printed `APC_RESULT: <value>`, that value is also captured as structured output.
 
-## Memory — durable, persists between sessions
+## Memory — durable, safe facts
 
 ```bash
 apx memory <slug>                       # read agent's memory.md
@@ -40,7 +42,7 @@ apx memory <slug> --append "<fact>"     # append a durable note (non-destructive
 apx memory <slug> --replace < file.md  # replace entire memory from stdin
 ```
 
-Write to memory when you discover something the agent should know on every future run.
+Write to memory only when you discover safe project context the agent should know on future runs.
 
 ## Observe activity
 
@@ -74,4 +76,5 @@ Print this on the last meaningful line of your output:
 APC_RESULT: <one-line summary or value>
 ```
 The invoker (`apx run`, super-agent, Telegram bot) captures it as structured output.
-Keep it factual and short — it becomes the session result stored in `.apc/agents/<slug>/sessions/`.
+Keep it factual and short. It becomes the session result stored in APX local runtime state, not
+inside `.apc/`.

package/src/cli/commands/project.js

@@ -109,11 +109,8 @@ export async function resolveProjectId(target) {
   // No override: walk up from cwd
   const root = findApfRoot();
   if (!root) {
-    const registered = await http.get("/projects").catch(() => []);
-    const hint = registered.length
-      ? `registered projects: ${registered.map((p) => `"${p.name}" (id ${p.id})`).join(", ")}`
-      : "no projects registered yet — run `apx project add <path>` first";
-    throw new Error(`not inside an APC project. Use --project <name|id|path>. ${hint}`);
+    // Fall back to the default project (id=0) — always available, no .apc/ required.
+    return 0;
   }
   const projects = await http.get("/projects");
   const found = projects.find((p) => p.path === root);

package/src/cli/commands/session.js

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { findApfRoot, readAgents } from "../../core/parser.js";
-import { ensureAgentDir } from "../../core/scaffold.js";
+import { getOrCreateApxId } from "../../core/scaffold.js";
 import { generateSessionId } from "../../core/session-store.js";
+import { ensureProjectStorage } from "../../core/config.js";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 
@@ -14,6 +15,12 @@ function requireRoot() {
   return root;
 }
 
+function requireStorageRoot(root) {
+  const apxId = getOrCreateApxId(root);
+  if (!apxId) throw new Error("could not resolve APX project storage id");
+  return ensureProjectStorage(apxId);
+}
+
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
 function readStdinSync() {
@@ -61,7 +68,7 @@ function setFrontmatterField(text, field, value) {
 }
 
 function listAllSessions(root) {
-  const agentsDir = path.join(root, ".apc", "agents");
+  const agentsDir = path.join(requireStorageRoot(root), "agents");
   if (!fs.existsSync(agentsDir)) return [];
   const out = [];
   for (const slug of fs.readdirSync(agentsDir)) {
@@ -124,10 +131,11 @@ export function cmdSessionNew(args) {
     throw new Error(`agent "${slug}" not found in AGENTS.md`);
   }
 
-  ensureAgentDir(root, slug);
-  const id = generateSessionId(root, slug);
+  const storageRoot = requireStorageRoot(root);
+  const id = generateSessionId(storageRoot, slug);
   const filename = `${id}.md`;
-  const filepath = path.join(root, ".apc", "agents", slug, "sessions", filename);
+  const filepath = path.join(storageRoot, "agents", slug, "sessions", filename);
+  fs.mkdirSync(path.dirname(filepath), { recursive: true });
 
   const taskRef = args.flags["task-ref"] === true ? "" : (args.flags["task-ref"] || "");
   let body = "";

package/src/cli/commands/setup.js

@@ -0,0 +1,336 @@
+// apx setup — interactive first-run wizard.
+// Guides the user through provider, model, channels, and language.
+// Starts the daemon and sends a fun wake-up message when done.
+
+import fs from "node:fs";
+import https from "node:https";
+import http from "node:http";
+import readline from "node:readline";
+import { spawnSync, spawn } from "node:child_process";
+import { readConfig, writeConfig, APX_HOME } from "../../core/config.js";
+
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+const c = {
+  reset: "\x1b[0m",
+  bold:  "\x1b[1m",
+  dim:   "\x1b[2m",
+  cyan:  "\x1b[36m",
+  green: "\x1b[32m",
+  yellow:"\x1b[33m",
+  red:   "\x1b[31m",
+  gray:  "\x1b[90m",
+};
+const b  = (s) => `${c.bold}${s}${c.reset}`;
+const cy = (s) => `${c.cyan}${s}${c.reset}`;
+const gr = (s) => `${c.green}${s}${c.reset}`;
+const di = (s) => `${c.dim}${s}${c.reset}`;
+
+// ── readline helpers ─────────────────────────────────────────────────────────
+let rl;
+function initRl() {
+  rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+function ask(prompt) {
+  return new Promise((resolve) => rl.question(prompt, (a) => resolve(a.trim())));
+}
+function close() { rl.close(); }
+
+// ── Fetch helpers ─────────────────────────────────────────────────────────────
+function fetchJson(url, timeout = 4000) {
+  return new Promise((resolve) => {
+    const mod = url.startsWith("https") ? https : http;
+    const req = mod.get(url, { timeout }, (res) => {
+      let body = "";
+      res.on("data", (c) => (body += c));
+      res.on("end", () => { try { resolve(JSON.parse(body)); } catch { resolve(null); } });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+  });
+}
+
+async function fetchOllamaModels(baseUrl) {
+  const data = await fetchJson(`${baseUrl.replace(/\/$/, "")}/api/tags`);
+  if (!data?.models) return [];
+  return data.models.map((m) => m.name).filter(Boolean);
+}
+
+// ── Provider definitions ──────────────────────────────────────────────────────
+const PROVIDERS = [
+  {
+    id: "anthropic",
+    label: "Anthropic (Claude)",
+    needsKey: true,
+    keyLabel: "Anthropic API key",
+    keyHint: "sk-ant-...",
+    models: ["claude-sonnet-4-5", "claude-haiku-4-5", "claude-opus-4-5"],
+  },
+  {
+    id: "openai",
+    label: "OpenAI (GPT)",
+    needsKey: true,
+    keyLabel: "OpenAI API key",
+    keyHint: "sk-...",
+    models: ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
+  },
+  {
+    id: "ollama",
+    label: "Ollama (local / self-hosted)",
+    needsKey: false,
+    models: [], // fetched dynamically
+  },
+  {
+    id: "gemini",
+    label: "Gemini (Google)",
+    needsKey: true,
+    keyLabel: "Gemini API key",
+    keyHint: "AIza...",
+    models: ["gemini-2.0-flash", "gemini-1.5-pro"],
+  },
+];
+
+// ── Main wizard ───────────────────────────────────────────────────────────────
+export async function cmdSetup() {
+  initRl();
+
+  console.log();
+  console.log(b(cy("  ╔═══════════════════════════════════╗")));
+  console.log(b(cy("  ║        APX Setup Wizard           ║")));
+  console.log(b(cy("  ╚═══════════════════════════════════╝")));
+  console.log();
+  console.log(di("  This will configure the APX daemon and super-agent."));
+  console.log(di("  You can re-run `apx setup` at any time to change settings."));
+  console.log();
+
+  // ── Super-agent? ────────────────────────────────────────────────────────────
+  const wantAgent = await ask(`  Enable super-agent? ${di("[Y/n]")} `);
+  if (/^n/i.test(wantAgent)) {
+    console.log(`\n  ${gr("✓")} Skipping super-agent. Run ${cy("apx daemon start")} to start the daemon.\n`);
+    close();
+    return;
+  }
+
+  // ── Provider ────────────────────────────────────────────────────────────────
+  console.log();
+  console.log(b("  AI Provider:"));
+  PROVIDERS.forEach((p, i) => console.log(`    ${cy(String(i + 1))}. ${p.label}`));
+  console.log();
+  let providerIdx = -1;
+  while (providerIdx < 0) {
+    const ans = await ask(`  Choose [1-${PROVIDERS.length}]: `);
+    const n = parseInt(ans, 10);
+    if (n >= 1 && n <= PROVIDERS.length) providerIdx = n - 1;
+    else console.log(`  ${c.yellow}Please enter a number between 1 and ${PROVIDERS.length}.${c.reset}`);
+  }
+  const provider = PROVIDERS[providerIdx];
+  let apiKey = "";
+  let ollamaUrl = "http://localhost:11434";
+
+  if (provider.id === "ollama") {
+    const urlAns = await ask(`  Ollama URL ${di("[http://localhost:11434]")}: `);
+    ollamaUrl = urlAns || "http://localhost:11434";
+  } else if (provider.needsKey) {
+    apiKey = await ask(`  ${provider.keyLabel} ${di(`(${provider.keyHint})`)}: `);
+  }
+
+  // ── Model ───────────────────────────────────────────────────────────────────
+  console.log();
+  let models = [...provider.models];
+
+  if (provider.id === "ollama") {
+    process.stdout.write(`  Fetching models from Ollama... `);
+    const fetched = await fetchOllamaModels(ollamaUrl);
+    if (fetched.length) {
+      models = fetched;
+      console.log(gr(`${fetched.length} found`));
+    } else {
+      console.log(di("(couldn't reach Ollama, enter manually)"));
+    }
+  }
+
+  let chosenModel = "";
+  if (models.length) {
+    console.log(b("  Model:"));
+    models.forEach((m, i) => console.log(`    ${cy(String(i + 1))}. ${m}`));
+    console.log(`    ${cy(String(models.length + 1))}. ${di("Enter manually")}`);
+    console.log();
+    let modelIdx = -1;
+    while (modelIdx < 0) {
+      const ans = await ask(`  Choose [1-${models.length + 1}]: `);
+      const n = parseInt(ans, 10);
+      if (n >= 1 && n <= models.length) { modelIdx = n - 1; chosenModel = models[modelIdx]; }
+      else if (n === models.length + 1) {
+        chosenModel = await ask("  Model name: ");
+        modelIdx = 0;
+      } else {
+        console.log(`  ${c.yellow}Invalid choice.${c.reset}`);
+      }
+    }
+  } else {
+    chosenModel = await ask("  Model name (e.g. qwen2.5:14b): ");
+  }
+  chosenModel = `${provider.id}:${chosenModel}`;
+
+  // ── Channels ────────────────────────────────────────────────────────────────
+  console.log();
+  console.log(b("  Channels:"));
+  console.log(`    ${cy("1")}. Web (local API — always on)`);
+  console.log(`    ${cy("2")}. Telegram`);
+  console.log();
+  const chAns = await ask(`  Enable Telegram? ${di("[Y/n]")} `);
+  const wantTelegram = !/^n/i.test(chAns);
+
+  let botToken = "";
+  let chatId = "";
+
+  if (wantTelegram) {
+    console.log();
+    console.log(di("  Create a bot at https://t.me/BotFather → get the token."));
+    console.log(di("  Then message your bot and visit:"));
+    console.log(di("  https://api.telegram.org/bot<TOKEN>/getUpdates to find your chat_id."));
+    console.log();
+    botToken = await ask("  Bot token: ");
+    chatId   = await ask("  Your chat ID: ");
+  }
+
+  // ── Language ────────────────────────────────────────────────────────────────
+  console.log();
+  console.log(b("  Language:"));
+  console.log(di("  The super-agent will always respond in your language."));
+  console.log();
+  const language = await ask("  Your language (e.g. English, Español, Português): ") || "English";
+
+  // ── Summary ─────────────────────────────────────────────────────────────────
+  console.log();
+  console.log(b("  ─── Summary ───────────────────────────────────────────"));
+  console.log(`  Provider:   ${cy(provider.label)}`);
+  console.log(`  Model:      ${cy(chosenModel)}`);
+  if (provider.id === "ollama") console.log(`  Ollama URL: ${cy(ollamaUrl)}`);
+  console.log(`  Telegram:   ${wantTelegram ? gr("enabled") : di("disabled")}`);
+  console.log(`  Language:   ${cy(language)}`);
+  console.log(b("  ────────────────────────────────────────────────────────"));
+  console.log();
+
+  const confirm = await ask(`  Start the daemon with these settings? ${di("[Y/n]")} `);
+  if (/^n/i.test(confirm)) {
+    console.log("\n  Cancelled. Run `apx setup` again to configure.\n");
+    close();
+    return;
+  }
+
+  close(); // done with prompts
+
+  // ── Write config ─────────────────────────────────────────────────────────────
+  const cfg = readConfig();
+
+  cfg.super_agent.enabled = true;
+  cfg.super_agent.model = chosenModel;
+  // System prompt: language instruction only, no wizard references
+  cfg.super_agent.system = `Always respond in the user's language: ${language}.`;
+
+  if (provider.id === "ollama") {
+    cfg.engines.ollama.base_url = ollamaUrl;
+  } else if (provider.needsKey && apiKey) {
+    cfg.engines[provider.id].api_key = apiKey;
+  }
+
+  if (wantTelegram && botToken && chatId) {
+    cfg.telegram.enabled = true;
+    cfg.telegram.bot_token = botToken;
+    cfg.telegram.chat_id = chatId;
+  }
+
+  writeConfig(cfg);
+  console.log(`\n  ${gr("✓")} Config saved to ${di("~/.apx/config.json")}`);
+
+  // ── Start daemon ─────────────────────────────────────────────────────────────
+  console.log();
+  process.stdout.write(`  Starting daemon... `);
+
+  const start = spawnSync("apx", ["daemon", "start"], { encoding: "utf8" });
+  if (start.status !== 0) {
+    console.log(c.red + "failed" + c.reset);
+    console.log(start.stderr || start.stdout);
+    process.exit(1);
+  }
+  console.log(gr("running ✓"));
+
+  // Give daemon a moment to come up
+  await new Promise((r) => setTimeout(r, 2000));
+
+  // ── Wake-up Telegram message ─────────────────────────────────────────────────
+  if (wantTelegram && botToken && chatId) {
+    console.log();
+    process.stdout.write(`  Sending wake-up message... `);
+    try {
+      const resp = await sendTelegramWakeup({ botToken, chatId, language, model: chosenModel });
+      if (resp) console.log(gr("sent ✓"));
+      else console.log(di("(couldn't reach Telegram)"));
+    } catch {
+      console.log(di("(couldn't reach Telegram)"));
+    }
+  }
+
+  console.log();
+  console.log(gr(b("  ✅ APX is ready!")));
+  console.log();
+  console.log(`  Daemon:   ${cy("http://127.0.0.1:7430")}`);
+  if (wantTelegram) console.log(`  Telegram: ${cy("active — message your bot")}`);
+  console.log();
+  console.log(di("  Tip: run `apx daemon status` anytime to check health."));
+  console.log();
+}
+
+// Send a fun wake-up message via Telegram using super-agent.
+// The prompt is in English so the model knows to reply in the user's language.
+async function sendTelegramWakeup({ botToken, chatId, language, model }) {
+  const prompt =
+    `You are APX, an AI agent assistant that just came online. ` +
+    `Send a short, fun, enthusiastic wake-up message to the user. ` +
+    `Be playful and creative — like a friendly AI that just woke up. ` +
+    `Keep it under 3 sentences. ` +
+    `IMPORTANT: respond in ${language}. ` +
+    `Do not mention that you were configured or set up.`;
+
+  // Ask the daemon's super-agent (give it a second attempt window)
+  let text;
+  try {
+    const res = await fetchJson("http://127.0.0.1:7430/super-agent/ask", 8000);
+    text = res?.text;
+  } catch {}
+
+  // Fallback: generate a simple message without daemon
+  if (!text) {
+    text = languageFallback(language);
+  }
+
+  // Send via Telegram bot API
+  return new Promise((resolve) => {
+    const body = JSON.stringify({ chat_id: chatId, text, parse_mode: "Markdown" });
+    const req = https.request({
+      hostname: "api.telegram.org",
+      path: `/bot${botToken}/sendMessage`,
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) },
+      timeout: 6000,
+    }, (res) => {
+      let d = "";
+      res.on("data", (c) => (d += c));
+      res.on("end", () => { try { resolve(JSON.parse(d)); } catch { resolve(null); } });
+    });
+    req.on("error", () => resolve(null));
+    req.write(body);
+    req.end();
+  });
+}
+
+// Minimal fallback messages per common language (used only if daemon can't respond)
+function languageFallback(lang) {
+  const l = lang.toLowerCase();
+  if (/espa[ñn]|spanish|arg|lat/i.test(l)) return "⚡ ¡Despierto y listo para trabajar! APX online.";
+  if (/portugu|brasil/i.test(l)) return "⚡ Acordei e pronto para trabalhar! APX online.";
+  if (/franc|french/i.test(l)) return "⚡ Réveillé et prêt à travailler ! APX en ligne.";
+  if (/deutsch|german/i.test(l)) return "⚡ Aufgewacht und bereit! APX ist online.";
+  if (/ital/i.test(l)) return "⚡ Sveglio e pronto a lavorare! APX online.";
+  return "⚡ I'm awake and ready to go! APX is online.";
+}

package/src/cli/commands/update.js

@@ -0,0 +1,75 @@
+import { spawnSync } from "node:child_process";
+import readline from "node:readline";
+import { getLatestVersion } from "../../core/update-check.js";
+
+const PACKAGE_NAME = "@agentprojectcontext/apx";
+
+export async function cmdUpdate(args) {
+  const force = args.flags.force || args.flags.yes || args.flags.y;
+
+  console.log("Checking for updates...");
+  const latest = await getLatestVersion();
+
+  if (!latest) {
+    console.error("Could not reach npm registry. Check your connection.");
+    process.exit(1);
+  }
+
+  // Read current version from the package that owns this file.
+  const { createRequire } = await import("node:module");
+  const { fileURLToPath } = await import("node:url");
+  const require = createRequire(import.meta.url);
+  const pkg = require("../../package.json");
+  const current = pkg.version;
+
+  function isNewer(cur, lat) {
+    const parse = (v) => v.replace(/^v/, "").split(".").map(Number);
+    const [ma, mi, pa] = parse(cur);
+    const [mb, mib, pb] = parse(lat);
+    if (mb > ma) return true;
+    if (mb === ma && mib > mi) return true;
+    if (mb === ma && mib === mi && pb > pa) return true;
+    return false;
+  }
+
+  if (!isNewer(current, latest)) {
+    console.log(`✅ Already up to date (${current})`);
+    return;
+  }
+
+  console.log(`\n  Current: ${current}`);
+  console.log(`  Latest:  ${latest}`);
+
+  if (!force) {
+    const confirmed = await confirm(`\nUpdate to ${latest}? [y/N] `);
+    if (!confirmed) {
+      console.log("Cancelled.");
+      return;
+    }
+  }
+
+  console.log(`\nRunning: npm install -g ${PACKAGE_NAME}@${latest}\n`);
+  const result = spawnSync(
+    "npm",
+    ["install", "-g", `${PACKAGE_NAME}@${latest}`],
+    { stdio: "inherit" }
+  );
+
+  if (result.status !== 0) {
+    console.error(`\n❌ Update failed (exit ${result.status})`);
+    process.exit(result.status || 1);
+  }
+
+  console.log(`\n✅ Updated to ${latest}. Restart any running apx daemon:`);
+  console.log(`   apx daemon stop && apx daemon start`);
+}
+
+function confirm(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}

package/src/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// apx — unified CLI for APC (Agent Project Framework).
+// apx — unified CLI for APC (Agent Project Context).
 // ESM, Node >= 18.
 import fs from "node:fs";
 import path from "node:path";
@@ -71,6 +71,9 @@ import { cmdPluginsList, cmdPluginStatus } from "./commands/plugins.js";
 import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus } from "./commands/skills.js";
 import { cmdIdentity } from "./commands/identity.js";
 import { cmdCommandList, cmdCommandShow } from "./commands/command.js";
+import { cmdUpdate } from "./commands/update.js";
+import { cmdSetup } from "./commands/setup.js";
+import { checkForUpdate } from "../core/update-check.js";
 import {
   cmdRoutineList,
   cmdRoutineGet,
@@ -87,17 +90,18 @@ const VERSION = JSON.parse(
   fs.readFileSync(path.join(__dirname, "..", "..", "package.json"), "utf8")
 ).version;
 
-const HELP = `apx — Agent Project Framework
+const HELP = `apx — Agent Project Context
 
 Usage:
   apx <command> [<subcommand>] [args] [--flags]
 
 Bootstrap:
   apx init [path] [--name "<name>"]                    initialize an APC project
-  apx project add <path>                               register a project with the daemon
+  apx project add [path]                               register a project with the daemon
   apx project list
   apx project remove <path|id>
-  apx project rebuild [<path|id>]                      rebuild SQLite cache from filesystem
+  apx project rebuild [<path|id>]                      rebuild project index from filesystem
+  apx add project [path]                               alias for: apx project add
 
 Agents:
   apx agent add <slug> [--role R] [--model M] [--skills a,b] [--language es-AR] [--description D]
@@ -144,7 +148,7 @@ Telegram:
 Messages:
   apx messages tail [--agent <slug>] [--channel <ch>] [-n 50] [--global]
                      global channels (telegram, direct, whatsapp) → ~/.apx/messages/<ch>/
-                     project channels (runtime, a2a, exec)        → <project>/.apc/messages/
+                     project channels (runtime, a2a, exec)        → ~/.apx/projects/<id>/messages/
   apx messages search "<query>"
 
 LLM engines (v0.2):
@@ -200,6 +204,8 @@ Skills (IDE integration):
   apx skills status                    show which IDE targets are installed (project + global)
 
 Other:
+  apx setup                                            interactive setup wizard (alias: apx install)
+  apx update                                           check for updates and upgrade (alias: apx upgrade)
   apx --help
   apx --version
 
@@ -466,6 +472,24 @@ async function dispatch(cmd, rest) {
         await cmdIdentity(parseArgs(rest));
         break;
 
+      case "add": {
+        // apx add <domain> [...args] — consistent alternative to apx <domain> add
+        const sub = rest[0];
+        if (sub === "project") await cmdProjectAdd(parseArgs(rest.slice(1)));
+        else die(`unknown 'add' subcommand: ${sub || "(none)"} — try: project`);
+        break;
+      }
+
+      case "setup":
+      case "install":
+        await cmdSetup();
+        return;
+
+      case "update":
+      case "upgrade":
+        await cmdUpdate(parseArgs(rest));
+        return; // skip checkForUpdate after an update
+
       default:
         die(`unknown command: ${cmd}\nRun \`apx --help\` for usage.`);
     }
@@ -475,6 +499,7 @@ const [topCmd, ...topRest] = argv;
 (async () => {
   try {
     await dispatch(topCmd, topRest);
+    checkForUpdate(VERSION);
   } catch (err) {
     die(err && err.message ? err.message : String(err));
   }