@agentprojectcontext/apx 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APF Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+<p align="center">
+  <img src="assets/hero.png" alt="APX — Local Runtime for AI Agents" width="600">
+</p>
+
+> 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
+
+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
+- **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
+- **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.
+
+## Quick start
+
+```bash
+npm install -g apx
+
+# In any directory with an AGENTS.md
+apx init
+
+# Spawn an agent with a full Claude Code runtime
+apx run sofia --runtime claude-code "Review the open PRs and summarize them"
+
+# Or a quick one-shot LLM exec
+apx exec sofia "What is my role in this project?"
+
+# Watch what's happening
+apx messages tail
+```
+
+## Installation
+
+```bash
+npm install -g apx
+```
+
+Requires Node.js 20+. The daemon starts automatically on first `apx` call.
+
+## Project layout
+
+Project context — committed to the repository:
+
+```text
+project-root/
+├── AGENTS.md              ← agent definitions
+└── .apc/
+    ├── project.json       ← project metadata + stable "id"
+    ├── agents/
+    │   └── <slug>.md      ← agent definition (role, model, skills…)
+    ├── mcps.json          ← MCP servers available to this project
+    ├── skills/            ← reusable skill prompts
+    └── commands/          ← custom slash commands
+```
+
+Runtime state — local machine only, never committed:
+
+```text
+~/.apx/projects/<project-id>/
+├── project.db             ← regenerable SQLite cache
+└── 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/
+```
+
+## Core commands
+
+```bash
+apx init [path]                          # initialize a project
+apx agent list                           # list agents
+apx agent add <slug> --role R --model M  # add an agent
+apx memory <slug>                        # read agent memory
+apx memory <slug> --append "<note>"      # append to memory
+
+apx run   <slug> --runtime claude-code "<prompt>"   # full runtime session
+apx exec  <slug> "<prompt>"                          # quick LLM call
+
+apx session list <slug>                  # list past sessions
+apx messages tail                        # last 50 messages, all channels
+apx messages tail --channel runtime      # only agent invocations
+```
+
+## Message channels
+
+All activity is logged to `.apc/messages/YYYY-MM-DD.jsonl`:
+
+| Channel | What it captures |
+|---------|-----------------|
+| `runtime` | `apx run` invocations (prompt in, response out) |
+| `a2a` | Agent-to-agent calls made from within a session |
+| `telegram` | Telegram bot messages (stored globally in `~/.apx/messages/telegram/`) |
+| `exec` | Quick `apx exec` calls |
+
+## Runtimes
+
+| Runtime | Description |
+|---------|-------------|
+| `claude-code` | Spawns Claude Code CLI with the agent's system prompt injected |
+| `codex` | OpenAI Codex CLI |
+| `opencode` | OpenCode CLI |
+| `aider` | Aider CLI |
+
+## Engines (for `apx exec`)
+
+Configured in `~/.apx/config.json`:
+
+```json
+{
+  "engines": {
+    "anthropic": { "api_key": "sk-ant-..." },
+    "openai":    { "api_key": "sk-..." },
+    "ollama":    { "base_url": "http://localhost:11434" },
+    "gemini":    { "api_key": "..." }
+  }
+}
+```
+
+## Architecture
+
+<p align="center">
+  <img src="assets/diagram.png" alt="APX architecture diagram" width="720">
+</p>
+
+## APC protocol
+
+APX implements the [APC specification](https://github.com/agentprojectcontext/agentprojectcontext). The spec defines the on-disk layout; APX provides the tooling to use it.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agentprojectcontext/apx",
+  "version": "1.0.3",
+  "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "apx": "./src/cli/index.js",
+    "apx-daemon": "./src/daemon/index.js",
+    "apx-mcp": "./src/mcp/index.js"
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/daemon/index.js",
+    "smoke": "node src/daemon/smoke.js",
+    "test": "node --test --test-reporter=spec tests/*.test.js",
+    "upgrade": "npm install && npm install -g .",
+    "postinstall": "node src/cli/postinstall.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^4.21.0",
+    "node-fetch": "^3.3.2"
+  },
+  "devDependencies": {
+    "better-sqlite3": "^11.3.0"
+  },
+  "keywords": [
+    "apc",
+    "apx",
+    "agents",
+    "mcp",
+    "daemon",
+    "claude",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentprojectcontext/apx.git"
+  },
+  "homepage": "https://github.com/agentprojectcontext/apx"
+}

package/skills/apx/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: apx
+description: "APX CLI skill. Activate ONLY when the user asks about running agents, coordinating between agents, or explicitly uses apx commands. Provides: apx run, apx exec, apx memory, apx mcp, apx session, apx messages tail. Do NOT activate just because .apc/ exists — project context is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', 'run an agent', 'coordinate agents', 'multi-agent', 'apx memory', 'apx mcp', 'daemon'."
+homepage: https://github.com/agentprojectcontext/apx
+---
+
+# APX — Agent Project Framework
+
+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.
+
+---
+
+## Discover the project
+
+```bash
+apx agent list                          # agents in AGENTS.md + their roles/models
+apx mcp list                            # MCP servers available to this project
+```
+
+## Coordinate with other agents
+
+```bash
+# Full external session (best for complex, multi-step tasks)
+apx run <slug> --runtime claude-code "<prompt>"
+apx run <slug> --runtime codex        "<prompt>"
+
+# Quick one-shot LLM call (requires engine API key in ~/.apx/config.json)
+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
+
+```bash
+apx memory <slug>                       # read agent's memory.md
+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.
+
+## Observe activity
+
+```bash
+apx messages tail                       # last 50 messages, all channels
+apx messages tail --channel runtime     # only agent invocations (in/out)
+apx messages tail --channel telegram    # Telegram conversation history
+apx messages tail --agent <slug> -n 20
+apx session list  <slug>                # sessions for a specific agent
+```
+
+## MCP tools
+
+```bash
+apx mcp list                            # registered MCP servers
+apx mcp tools <server>                  # list tools a server exposes
+apx mcp run   <server> <tool> '<json>'  # call a tool directly
+```
+
+## Anti-collision guard
+
+Before starting a long task, prevent duplicate runs:
+```bash
+apx session check    # exits 1 if a session is already active for this agent
+```
+
+## APC_RESULT — how to signal your return value
+
+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/`.

package/src/cli/commands/a2a.js

@@ -0,0 +1,66 @@
+import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
+
+export async function cmdSend(args) {
+  const from = args._[0];
+  const to = args._[1];
+  if (!from || !to) {
+    throw new Error('apx send: usage: apx send <from> <to> "<body>" [--deliver]');
+  }
+  let body = args._.slice(2).join(" ").trim();
+  if (!body || body === "-") {
+    const fs = await import("node:fs");
+    if (!process.stdin.isTTY) {
+      const chunks = [];
+      const buf = Buffer.alloc(65536);
+      try {
+        while (true) {
+          const n = fs.readSync(0, buf, 0, buf.length);
+          if (!n) break;
+          chunks.push(buf.slice(0, n).toString("utf8"));
+        }
+      } catch {}
+      body = chunks.join("").trim();
+    }
+  }
+  if (!body) throw new Error("apx send: body is empty");
+
+  const pid = await resolveProjectId(args?.flags?.project);
+  const result = await http.post(`/projects/${pid}/send`, {
+    from,
+    to,
+    body,
+    deliver: !!args.flags.deliver,
+  });
+  console.log(`✉  ${from} → ${to}  @ ${result.ts}`);
+  console.log(`   ${body}`);
+  if (result.reply) {
+    if (result.reply.error) {
+      console.log(`\n⚠  delivery failed: ${result.reply.error}`);
+    } else {
+      console.log(`\n← ${to} replies:`);
+      console.log(result.reply.text);
+    }
+  }
+}
+
+export async function cmdConnections(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx connections: missing <agent-slug>");
+  const pid = await resolveProjectId(args?.flags?.project);
+  const peers = await http.get(`/projects/${pid}/agents/${slug}/connections`);
+  if (peers.length === 0) {
+    console.log(`(no connections logged for ${slug} yet)`);
+    return;
+  }
+  console.log("PEER".padEnd(16) + " CH".padEnd(11) + " DIR  N    LAST");
+  for (const p of peers) {
+    console.log(
+      (p.peer || "?").padEnd(16) + " " +
+      (p.channel || "").padEnd(10) + " " +
+      (p.direction || "").padEnd(4) + " " +
+      String(p.n).padEnd(4) + " " +
+      (p.last_ts || "")
+    );
+  }
+}

package/src/cli/commands/agent.js

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findApfRoot, readAgents, readVaultAgents, VAULT_DIR, SLUG_RE } from "../../core/parser.js";
+import { writeAgentFile, writeVaultAgentFile, addImportedAgent, ensureAgentDir, regenerateAgentsMd } from "../../core/scaffold.js";
+import { http } from "../http.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" };
+const dim  = (s) => `${c.dim}${s}${c.reset}`;
+const bold = (s) => `${c.bold}${s}${c.reset}`;
+const cyan = (s) => `${c.cyan}${s}${c.reset}`;
+const gray = (s) => `${c.gray}${s}${c.reset}`;
+const tag  = (s) => `${c.yellow}${s}${c.reset}`;
+
+function requireRoot() {
+  const root = findApfRoot();
+  if (!root) throw new Error("not inside an APC project (run `apx init` first)");
+  return root;
+}
+
+async function nudgeDaemon(root) {
+  try {
+    if (!(await http.ping())) return;
+    const projects = await http.get("/projects", { autoStart: false });
+    const me = projects.find((p) => p.path === root);
+    if (me) await http.post(`/projects/${me.id}/rebuild`, undefined, { autoStart: false });
+  } catch { /* daemon hiccup */ }
+}
+
+export async function cmdAgentAdd(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx agent add: missing <slug>");
+  if (!SLUG_RE.test(slug)) throw new Error(`invalid slug "${slug}"`);
+
+  const root = requireRoot();
+  const existing = readAgents(root);
+  if (existing.some((a) => a.slug === slug)) {
+    throw new Error(`agent "${slug}" already exists`);
+  }
+
+  const fields = {};
+  const f = args.flags;
+  if (f.role && f.role !== true)        fields.Role = f.role;
+  if (f.model && f.model !== true)      fields.Model = f.model;
+  if (f.language && f.language !== true) fields.Language = f.language;
+  if (f.description && f.description !== true) fields.Description = f.description;
+  if (f.skills && f.skills !== true)    fields.Skills = String(f.skills).split(",").map((s) => s.trim()).filter(Boolean);
+  if (f.tools && f.tools !== true)      fields.Tools = String(f.tools).split(",").map((s) => s.trim()).filter(Boolean);
+
+  writeAgentFile(root, slug, fields);
+  ensureAgentDir(root, slug);
+  regenerateAgentsMd(root);
+  await nudgeDaemon(root);
+
+  console.log(`Added agent ${slug}`);
+  for (const [k, v] of Object.entries(fields)) {
+    console.log(`  ${k}: ${Array.isArray(v) ? v.join(", ") : v}`);
+  }
+}
+
+export function cmdAgentList() {
+  const root = requireRoot();
+  const agents = readAgents(root);
+  if (agents.length === 0) {
+    console.log(dim("(no agents — try `apx agent add <slug>` or `apx agent import <slug>`)"));
+    return;
+  }
+  console.log();
+  for (const a of agents) {
+    const src   = a.source === "vault" ? tag(" ↑ vault") : a.source === "legacy" ? gray(" ↑ legacy") : "";
+    const role  = a.fields.Role  ? dim(a.fields.Role)  : gray("—");
+    const model = a.fields.Model ? dim(a.fields.Model) : gray("—");
+    console.log(`  ${bold(a.slug)}${src}  ${role}  ${cyan(model)}`);
+  }
+  console.log();
+}
+
+export function cmdAgentGet(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx agent get: missing <slug>");
+  const root = requireRoot();
+  const a = readAgents(root).find((x) => x.slug === slug);
+  if (!a) {
+    // Check vault and suggest import
+    const vault = readVaultAgents();
+    const inVault = vault.find((v) => v.slug === slug);
+    if (inVault) {
+      throw new Error(`agent "${slug}" not imported in this project. Run: apx agent import ${slug}`);
+    }
+    throw new Error(`agent "${slug}" not found`);
+  }
+  const src = a.source === "vault" ? tag(" ↑ vault") : a.source === "legacy" ? gray(" ↑ legacy") : "";
+  console.log(`\n  ${bold(a.slug)}${src}`);
+  for (const [k, v] of Object.entries(a.fields)) {
+    console.log(`  ${gray(k.padEnd(12))}  ${Array.isArray(v) ? v.join(", ") : v}`);
+  }
+  if (a.body) console.log(`\n${dim(a.body)}`);
+  console.log();
+}
+
+// ── Vault commands ────────────────────────────────────────────────────────────
+
+export function cmdAgentVaultList() {
+  const vault = readVaultAgents();
+  if (vault.length === 0) {
+    console.log(dim(`(vault empty — add templates with \`apx agent vault add <slug>\`)`));
+    console.log(gray(`  vault: ${VAULT_DIR}`));
+    return;
+  }
+  console.log(`\n  ${gray("vault:")} ${gray(VAULT_DIR)}\n`);
+  for (const a of vault) {
+    const role  = a.fields.Role  ? dim(a.fields.Role)  : gray("—");
+    const model = a.fields.Model ? dim(a.fields.Model) : gray("—");
+    console.log(`  ${bold(a.slug)}  ${role}  ${cyan(model)}`);
+  }
+  console.log();
+}
+
+export async function cmdAgentVaultAdd(args) {
+  const slug = args._[0];
+  if (!slug || !SLUG_RE.test(slug)) throw new Error("apx agent vault add: missing or invalid <slug>");
+
+  // If we're inside a project, offer to copy the local agent to vault
+  const root = findApfRoot();
+  if (root) {
+    const local = readAgents(root).find((a) => a.slug === slug && a.source === "local");
+    if (local) {
+      writeVaultAgentFile(slug, local.fields, local.body);
+      console.log(`\n  ${bold(slug)} added to vault from local definition\n`);
+      return;
+    }
+  }
+
+  // Otherwise create a blank vault entry from flags
+  const fields = {};
+  const f = args.flags;
+  if (f.role && f.role !== true)        fields.Role = f.role;
+  if (f.model && f.model !== true)      fields.Model = f.model;
+  if (f.language && f.language !== true) fields.Language = f.language;
+  if (f.description && f.description !== true) fields.Description = f.description;
+  if (f.skills && f.skills !== true)    fields.Skills = String(f.skills).split(",").map((s) => s.trim()).filter(Boolean);
+
+  writeVaultAgentFile(slug, fields);
+  console.log(`\n  ${bold(slug)} added to vault  ${gray(VAULT_DIR + "/" + slug + ".md")}\n`);
+}
+
+export async function cmdAgentImport(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx agent import: missing <slug>");
+  const root = requireRoot();
+
+  const vaultPath = path.join(VAULT_DIR, `${slug}.md`);
+  if (!fs.existsSync(vaultPath)) {
+    const vault = readVaultAgents();
+    const available = vault.map((a) => a.slug).join(", ") || "(none)";
+    throw new Error(`"${slug}" not found in vault. Available: ${available}`);
+  }
+
+  const alreadyLocal = fs.existsSync(path.join(root, ".apc", "agents", `${slug}.md`));
+  if (alreadyLocal && !args.flags.force) {
+    console.log(dim(`  "${slug}" already has a local definition. Use --force to overwrite.`));
+    return;
+  }
+
+  if (args.flags.copy) {
+    // Copy .md into project so user can edit locally
+    fs.copyFileSync(vaultPath, path.join(root, ".apc", "agents", `${slug}.md`));
+    console.log(`\n  ${bold(slug)} copied from vault to project (now local)\n`);
+  } else {
+    // Just register as imported — reads from vault at runtime
+    addImportedAgent(root, slug);
+    console.log(`\n  ${bold(slug)} imported from vault ${tag("↑ vault")}\n`);
+    console.log(gray(`  definition: ${vaultPath}`));
+    console.log(gray(`  memory:     ${path.join(root, ".apc", "agents", slug, "memory.md")} (project-local)`));
+    console.log();
+  }
+
+  ensureAgentDir(root, slug);
+  regenerateAgentsMd(root);
+  await nudgeDaemon(root);
+}

package/src/cli/commands/chat.js

@@ -0,0 +1,84 @@
+import readline from "node:readline";
+import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
+
+export async function cmdChat(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx chat: usage: apx chat <agent> [--conversation <id>] [--model <id>]");
+
+  const pid = await resolveProjectId(args?.flags?.project);
+  let convId = args.flags.conversation === true ? null : args.flags.conversation || null;
+  const overrideModel = args.flags.model === true ? null : args.flags.model || null;
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: `${slug}> `,
+    terminal: process.stdin.isTTY,
+  });
+
+  console.log(`apx chat with ${slug}${convId ? ` (cont. ${convId})` : ""} — type Ctrl-D or 'exit' to quit`);
+  rl.prompt();
+
+  rl.on("line", async (line) => {
+    const text = line.trim();
+    if (text === "exit" || text === "quit") {
+      rl.close();
+      return;
+    }
+    if (!text) {
+      rl.prompt();
+      return;
+    }
+    try {
+      const body = { prompt: text };
+      if (convId) body.conversation_id = convId;
+      if (overrideModel) body.model = overrideModel;
+
+      const result = await http.post(`/projects/${pid}/agents/${slug}/chat`, body);
+      convId = result.conversation_id;
+      process.stdout.write("\n" + result.text + "\n\n");
+    } catch (e) {
+      process.stderr.write(`apx: ${e.message}\n`);
+    }
+    rl.prompt();
+  });
+
+  rl.on("close", () => {
+    process.stdout.write("\n");
+    process.exit(0);
+  });
+}
+
+export async function cmdConversationsList(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx conversations list: missing <agent-slug>");
+  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)");
+    return;
+  }
+  console.log("ID".padEnd(16) + " ENGINE".padEnd(35) + " TURNS  STATUS");
+  for (const r of rows) {
+    const id = r.filename.replace(/\.md$/, "");
+    console.log(
+      id.padEnd(16) +
+      " " + (r.engine || "?").padEnd(34) +
+      " " + String(r.turn_count || 0).padEnd(6) +
+      " " + (r.status || "open")
+    );
+  }
+}
+
+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>");
+  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`);
+  for (const t of conv.turns) {
+    process.stdout.write(`\n## ${t.role} — ${t.ts}\n${t.content}\n`);
+  }
+}

package/src/cli/commands/command.js

@@ -0,0 +1,42 @@
+// apx command — list and show workflow commands from .apc/commands/
+import fs from "node:fs";
+import path from "node:path";
+import { findApfRoot } from "../../core/parser.js";
+
+function commandsDir(root) {
+  return path.join(root, ".apc", "commands");
+}
+
+function listCommandFiles(root) {
+  const dir = commandsDir(root);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+}
+
+export function cmdCommandList() {
+  const root = findApfRoot();
+  if (!root) throw new Error("not inside an APC project");
+  const files = listCommandFiles(root);
+  if (files.length === 0) {
+    console.log("(no commands — add .md files to .apc/commands/)");
+    return;
+  }
+  for (const f of files) {
+    const slug = f.replace(/\.md$/, "");
+    const text = fs.readFileSync(path.join(commandsDir(root), f), "utf8");
+    const firstLine = text.split("\n").find((l) => l.trim() && !l.startsWith("#"))
+      || text.split("\n").find((l) => l.startsWith("# "))?.replace(/^#\s*/, "")
+      || "";
+    console.log(`  ${slug.padEnd(24)}  ${firstLine.slice(0, 60)}`);
+  }
+}
+
+export function cmdCommandShow(args) {
+  const name = args._[0];
+  if (!name) throw new Error("apx command show: missing <name>");
+  const root = findApfRoot();
+  if (!root) throw new Error("not inside an APC project");
+  const file = path.join(commandsDir(root), `${name}.md`);
+  if (!fs.existsSync(file)) throw new Error(`command "${name}" not found in .apc/commands/`);
+  process.stdout.write(fs.readFileSync(file, "utf8"));
+}