@agentprojectcontext/apx 1.14.1 → 1.15.0

package/src/core/logging.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { APX_HOME } from "./config.js";
+
+export const LOG_DIR = path.join(APX_HOME, "logs");
+export const ERROR_TRACE_PATH = path.join(LOG_DIR, "errors.jsonl");
+
+const SECRET_KEY_RE = /(token|secret|password|api[_-]?key|authorization|bot[_-]?token)/i;
+
+function redact(value, seen = new WeakSet()) {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== "object") return value;
+  if (seen.has(value)) return "[circular]";
+  seen.add(value);
+
+  if (Array.isArray(value)) return value.map((item) => redact(item, seen));
+
+  const out = {};
+  for (const [key, val] of Object.entries(value)) {
+    out[key] = SECRET_KEY_RE.test(key) ? "[redacted]" : redact(val, seen);
+  }
+  return out;
+}
+
+export function appendErrorTrace(record) {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  const entry = {
+    ts: new Date().toISOString(),
+    ...redact(record),
+  };
+  fs.appendFileSync(ERROR_TRACE_PATH, JSON.stringify(entry) + "\n", "utf8");
+}
+
+export function previewText(text, max = 500) {
+  const clean = String(text || "").replace(/\s+/g, " ").trim();
+  return clean.length > max ? clean.slice(0, max - 1) + "…" : clean;
+}

package/src/core/scaffold.js

@@ -6,9 +6,43 @@ import { fileURLToPath } from "node:url";
 import { readAgents, readAgentsFromDir, VAULT_DIR } from "./parser.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skills");
+const RUNTIME_SKILLS_DIR = path.join(__dirname, "runtime-skills");
 
 export const SPEC_VERSION = "0.1.0";
 
+// ---------------------------------------------------------------------------
+// Bundled skills — single source of truth lives at <packageRoot>/skills/<slug>/SKILL.md
+// with proper frontmatter. The `apc-context` copy is refreshed on every
+// install/update from the canonical APC repo (see src/cli/postinstall.js).
+// ---------------------------------------------------------------------------
+
+function readBundledSkill(slug) {
+  const file = path.join(BUNDLED_SKILLS_DIR, slug, "SKILL.md");
+  if (!fs.existsSync(file)) return null;
+  return fs.readFileSync(file, "utf8");
+}
+
+// Split frontmatter and body from a SKILL.md. Used by IDE targets that need
+// to re-wrap the body in their own rule-file frontmatter.
+function splitFrontmatter(raw) {
+  if (!raw.startsWith("---")) return { fm: "", body: raw };
+  const end = raw.indexOf("\n---", 3);
+  if (end < 0) return { fm: "", body: raw };
+  const fm = raw.slice(0, end + 4);
+  const body = raw.slice(end + 4).replace(/^\n/, "");
+  return { fm, body };
+}
+
+// Pull description from frontmatter so cursor/.mdc rule files can advertise
+// the same activation trigger.
+function readDescription(raw) {
+  const { fm } = splitFrontmatter(raw);
+  const m = fm.match(/^description:\s*"?(.*?)"?\s*$/m);
+  return m ? m[1] : "";
+}
+
 // ---------------------------------------------------------------------------
 // IDE skill targets — written during `apx init` and `apx skills add`
 // ---------------------------------------------------------------------------
@@ -21,7 +55,8 @@ export const IDE_TARGETS = [
     label: "Claude Code",
     ideDir: ".claude",
     file: ".claude/skills/apx/SKILL.md",
-    render: (c) => buildSkillMd(c),
+    // Claude Code consumes SKILL.md with its native frontmatter as-is.
+    render: (raw) => raw,
     append: false,
   },
   {
@@ -29,8 +64,11 @@ export const IDE_TARGETS = [
     label: "Cursor",
     ideDir: ".cursor",
     file: ".cursor/rules/apx.mdc",
-    render: (c) =>
-      `---\ndescription: APX CLI skill. Activate when the user asks about running agents, coordinating between agents, or uses apx commands (apx run, apx exec, apx memory, apx mcp, apx session, apx messages).\n---\n\n${c}`,
+    render: (raw) => {
+      const { body } = splitFrontmatter(raw);
+      const desc = readDescription(raw);
+      return `---\ndescription: ${desc}\n---\n\n${body}`;
+    },
     append: false,
   },
   {
@@ -38,8 +76,11 @@ export const IDE_TARGETS = [
     label: "Windsurf",
     ideDir: ".windsurf",
     file: ".windsurf/rules/apx.md",
-    render: (c) =>
-      `---\ntrigger: model_decision\ndescription: APX CLI skill. Activate when the user asks about running agents, coordinating between agents, or uses apx commands (apx run, apx exec, apx memory, apx mcp, apx session, apx messages).\n---\n\n${c}`,
+    render: (raw) => {
+      const { body } = splitFrontmatter(raw);
+      const desc = readDescription(raw);
+      return `---\ntrigger: model_decision\ndescription: ${desc}\n---\n\n${body}`;
+    },
     append: false,
   },
   {
@@ -47,7 +88,10 @@ export const IDE_TARGETS = [
     label: "GitHub Copilot",
     ideDir: ".github",
     file: ".github/copilot-instructions.md",
-    render: (c) => `\n<!-- apx-skill -->\n${c}\n<!-- /apx-skill -->\n`,
+    render: (raw) => {
+      const { body } = splitFrontmatter(raw);
+      return `\n<!-- apx-skill -->\n${body}\n<!-- /apx-skill -->\n`;
+    },
     append: true,
     guard: "<!-- apx-skill -->",
   },
@@ -56,13 +100,16 @@ export const IDE_TARGETS = [
     label: "Trae",
     ideDir: ".trae",
     file: ".trae/rules/project_rules.md",
-    render: (c) => `\n<!-- apx-skill -->\n${c}\n<!-- /apx-skill -->\n`,
+    render: (raw) => {
+      const { body } = splitFrontmatter(raw);
+      return `\n<!-- apx-skill -->\n${body}\n<!-- /apx-skill -->\n`;
+    },
     append: true,
     guard: "<!-- apx-skill -->",
   },
 ];
 
-// Global targets (absolute paths, use ~/<dir>/skills/apx/SKILL.md format).
+// Global targets (absolute paths, use ~/<dir>/skills/<slug>/SKILL.md format).
 // These dirs are read by Claude Code, Cursor (compat), and tools adopting the skills.sh spec.
 const GLOBAL_SKILL_DIRS = [
   path.join(os.homedir(), ".claude", "skills"),    // Claude Code + Cursor legacy compat
@@ -71,52 +118,23 @@ const GLOBAL_SKILL_DIRS = [
   path.join(os.homedir(), ".agents", "skills"),    // Antigravity/other skills.sh adopters
 ];
 
-function buildApcContextSkillMd(content) {
-  const frontmatter = [
-    "---",
-    "name: apc-context",
-    "description: \"ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. Do not wait to be asked. Read .apc/ before making any assumption about agents, memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents', any question about agents or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the conversation with a migration offer before answering anything else. If the user declines, delete .apc/migrate.md immediately so it is not shown again.\"",
-    "homepage: https://github.com/agentprojectcontext/agentprojectcontext",
-    "---",
-    "",
-  ].join("\n");
-  return frontmatter + content;
-}
-
-function buildSkillMd(content) {
-  const frontmatter = [
-    "---",
-    "name: apx",
-    "description: \"APX CLI skill. Activate when: user asks to run or coordinate agents, use MCP tools from .apc/mcps.json, install agents from a team workspace, or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', 'run an agent', 'coordinate agents', 'MCP not working', 'install agent', 'team agents', 'apx memory', 'daemon'.\"",
-    "homepage: https://github.com/agentprojectcontext/apx",
-    "---",
-    "",
-  ].join("\n");
-  return frontmatter + content;
-}
-
 function readRuntimeSkillFiles() {
-  const skillsDir = path.join(__dirname, "runtime-skills");
-  if (!fs.existsSync(skillsDir)) return [];
-
-  return fs.readdirSync(skillsDir)
+  if (!fs.existsSync(RUNTIME_SKILLS_DIR)) return [];
+  return fs.readdirSync(RUNTIME_SKILLS_DIR)
     .filter((name) => name.endsWith(".md"))
     .sort()
     .map((name) => ({
       slug: path.basename(name, ".md"),
-      md: fs.readFileSync(path.join(skillsDir, name), "utf8").trim(),
+      md: fs.readFileSync(path.join(RUNTIME_SKILLS_DIR, name), "utf8").trim(),
     }));
 }
 
 // Install APX + APC context skills into IDE rule files. Returns an array of result objects.
 // targetIds: array of target ids to install; null = all project targets.
 export function installIdeSkills(root, targetIds = null) {
-  const apxSrc = path.join(__dirname, "apx-skill.md");
-  const apcSrc = path.join(__dirname, "apc-context-skill.md");
-  if (!fs.existsSync(apxSrc)) return [];
-
-  const apxContent = fs.readFileSync(apxSrc, "utf8").trim();
-  const apcContent = fs.existsSync(apcSrc) ? fs.readFileSync(apcSrc, "utf8").trim() : null;
+  const apxRaw = readBundledSkill("apx");
+  const apcRaw = readBundledSkill("apc-context");
+  if (!apxRaw) return [];
 
   const targets = targetIds
     ? IDE_TARGETS.filter((t) => targetIds.includes(t.id))
@@ -129,10 +147,9 @@ export function installIdeSkills(root, targetIds = null) {
       continue;
     }
 
-    // Install APX skill
     const dest = path.join(root, t.file);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    const rendered = t.render(apxContent);
+    const rendered = t.render(apxRaw);
     if (t.append) {
       const existing = fs.existsSync(dest) ? fs.readFileSync(dest, "utf8") : "";
       if (t.guard && existing.includes(t.guard)) {
@@ -147,31 +164,28 @@ export function installIdeSkills(root, targetIds = null) {
       results.push({ ...t, status: existed ? "updated" : "created" });
     }
 
-    // Install APC context skill alongside (only for non-append targets with a skills dir)
-    if (apcContent && t.id === "claude-code") {
+    // Install APC context skill alongside Claude Code (dir-style skills dir).
+    if (apcRaw && t.id === "claude-code") {
       const apcDest = path.join(root, ".claude", "skills", "apc-context", "SKILL.md");
       fs.mkdirSync(path.dirname(apcDest), { recursive: true });
       const existed = fs.existsSync(apcDest);
-      fs.writeFileSync(apcDest, buildApcContextSkillMd(apcContent), "utf8");
+      fs.writeFileSync(apcDest, apcRaw, "utf8");
       results.push({ ...t, id: "claude-code/apc-context", label: "Claude Code (apc-context)", file: apcDest, status: existed ? "updated" : "created" });
     }
   }
   return results;
 }
 
-// Install both APX and APC context skills to global ~/.../skills/ dirs.
+// Install bundled APX/APC skills + runtime docs to global ~/.../skills/ dirs.
 // Returns an array of result objects with { dir, skill, status }.
 export function installGlobalSkills() {
   const results = [];
 
-  const apxSrc = path.join(__dirname, "apx-skill.md");
-  const apcSrc = path.join(__dirname, "apc-context-skill.md");
-
   const skills = [];
-  if (fs.existsSync(apxSrc))
-    skills.push({ slug: "apx", md: buildSkillMd(fs.readFileSync(apxSrc, "utf8").trim()) });
-  if (fs.existsSync(apcSrc))
-    skills.push({ slug: "apc-context", md: buildApcContextSkillMd(fs.readFileSync(apcSrc, "utf8").trim()) });
+  const apxRaw = readBundledSkill("apx");
+  const apcRaw = readBundledSkill("apc-context");
+  if (apxRaw) skills.push({ slug: "apx", md: apxRaw });
+  if (apcRaw) skills.push({ slug: "apc-context", md: apcRaw });
   skills.push(...readRuntimeSkillFiles());
 
   for (const base of GLOBAL_SKILL_DIRS) {

package/src/daemon/api.js

@@ -1,6 +1,7 @@
 // Express REST API for APX. See APC docs reference/apx-daemon.
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
 import express from "express";
 import { buildBrowserRouter } from "./tools/browser.js";
@@ -49,6 +50,7 @@ import { readAgents } from "../core/parser.js";
 import { parseSessionFrontmatter } from "../core/parser.js";
 import { writeAgentFile, ensureAgentDir, regenerateAgentsMd } from "../core/scaffold.js";
 import { buildAgentSystem } from "../core/agent-system.js";
+import { appendErrorTrace, previewText } from "../core/logging.js";
 import {
   createArtifact,
   listArtifacts,
@@ -58,11 +60,34 @@ import {
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
+function appendSuperAgentErrorTrace(req, error, details = {}) {
+  appendErrorTrace({
+    trace_id: req.apxTraceId,
+    surface: "daemon_api",
+    route: `${req.method} ${req.route?.path || req.path}`,
+    project_id: req.params?.pid || null,
+    channel: /Channel:\s*([^\n]+)/i.exec(details.contextNote || "")?.[1]?.trim() || null,
+    model: details.model || null,
+    stream: !!details.stream,
+    prompt_preview: previewText(details.prompt),
+    previous_messages: Array.isArray(details.previousMessages) ? details.previousMessages.length : 0,
+    error: {
+      message: error?.message || String(error),
+      stack: error?.stack || null,
+    },
+  });
+}
+
 export function buildApi({ projects, registries, plugins, scheduler, version, startedAt, addProjectGlobally, config }) {
   const telegram = plugins?.get("telegram");
 
   const app = express();
   app.use(express.json({ limit: "2mb" }));
+  app.use((req, res, next) => {
+    req.apxTraceId = req.get("x-apx-trace-id") || randomUUID();
+    res.setHeader("x-apx-trace-id", req.apxTraceId);
+    next();
+  });
 
   // ---- Tool routers (fetch / browser / search / glob / grep / registry) ----
   // fetch  = native HTTP, no Chromium  → fast, cheap, default for REST/HTML
@@ -636,7 +661,8 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
       });
       res.end();
     } catch (e) {
-      send({ type: "error", error: e.message });
+      appendSuperAgentErrorTrace(req, e, { prompt, contextNote, previousMessages, model, stream: true });
+      send({ type: "error", trace_id: req.apxTraceId, error: `${e.message} (trace: ${req.apxTraceId})` });
       res.end();
     }
   });
@@ -665,7 +691,8 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
         trace: saResult.trace,
       });
     } catch (e) {
-      res.status(500).json({ error: e.message });
+      appendSuperAgentErrorTrace(req, e, { prompt, contextNote, previousMessages, model, stream: false });
+      res.status(500).json({ error: e.message, trace_id: req.apxTraceId });
     }
   });
 

package/src/daemon/engines/anthropic.js

@@ -11,7 +11,7 @@ function getKey(config) {
 export default {
   id: "anthropic",
 
-  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice }) {
+  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice, signal }) {
     const key = getKey(config);
     if (!key) throw new Error("anthropic: no api_key (set ANTHROPIC_API_KEY or engines.anthropic.api_key)");
     if (!model) throw new Error("anthropic: model required");
@@ -47,6 +47,7 @@ export default {
         "anthropic-version": API_VERSION,
       },
       body: JSON.stringify(body),
+      signal,
     });
     const json = await res.json();
     if (!res.ok) {

package/src/daemon/engines/gemini.js

@@ -10,7 +10,7 @@ function getKey(config) {
 export default {
   id: "gemini",
 
-  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, config = {} }) {
+  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, config = {}, signal }) {
     const key = getKey(config);
     if (!key) throw new Error("gemini: no api_key (set GEMINI_API_KEY or engines.gemini.api_key)");
     if (!model) throw new Error("gemini: model required");
@@ -33,6 +33,7 @@ export default {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
+      signal,
     });
     const json = await res.json();
     if (!res.ok) {

package/src/daemon/engines/index.js

@@ -46,11 +46,10 @@ export function getAdapter(provider) {
   return a;
 }
 
-export async function callEngine({ modelId, system, messages, config, temperature, maxTokens, tools, toolChoice }) {
+export async function callEngine({ modelId, system, messages, config, temperature, maxTokens, tools, toolChoice, signal }) {
   const { provider, model } = resolveProvider(modelId);
   const adapter = getAdapter(provider);
-  const providerCfg =
-    (config && config.engines && config.engines[provider]) || {};
+  const providerCfg = (config && config.engines && config.engines[provider]) || {};
   return adapter.chat({
     system,
     messages,
@@ -60,6 +59,7 @@ export async function callEngine({ modelId, system, messages, config, temperatur
     tools,
     toolChoice,
     config: providerCfg,
+    signal,
   });
 }
 

package/src/daemon/engines/ollama.js

@@ -8,7 +8,7 @@ function baseUrl(config) {
 export default {
   id: "ollama",
 
-  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, tools, config = {} }) {
+  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, tools, config = {}, signal }) {
     if (!model) throw new Error("ollama: model required");
 
     // The caller can pass `messages` as either:
@@ -45,6 +45,7 @@ export default {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
+      signal,
     });
     if (!res.ok) {
       const text = await res.text();

package/src/daemon/engines/openai.js

@@ -10,7 +10,7 @@ function getKey(config) {
 export default {
   id: "openai",
 
-  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice }) {
+  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice, signal }) {
     const key = getKey(config);
     if (!key) throw new Error("openai: no api_key (set OPENAI_API_KEY or engines.openai.api_key)");
     if (!model) throw new Error("openai: model required");
@@ -52,6 +52,7 @@ export default {
         authorization: `Bearer ${key}`,
       },
       body: JSON.stringify(body),
+      signal,
     });
     const json = await res.json();
     if (!res.ok) {

package/src/daemon/plugins/telegram.js

@@ -290,6 +290,7 @@ class ChannelPoller {
     this.polling = false;
     this.lastError = null;
     this.lastUpdateAt = null;
+    this.activeRequests = new Map(); // chat_id -> AbortController
   }
 
   resolveProject() {
@@ -390,7 +391,19 @@ class ChannelPoller {
         ? "@" + msg.from.username
         : `${msg.from?.first_name || ""} ${msg.from?.last_name || ""}`.trim() || "unknown";
     const chat_id = msg.chat?.id;
-    const text = msg.text || msg.caption || "";
+
+    // Default Interrupt: abort any running request for this chat_id
+    if (chat_id) {
+      const prev = this.activeRequests.get(chat_id);
+      if (prev) {
+        this.log(`telegram[${this.channel.name}] interrupting previous request for chat ${chat_id}`);
+        prev.abort();
+      }
+    }
+    const abortCtrl = new AbortController();
+    if (chat_id) this.activeRequests.set(chat_id, abortCtrl);
+
+    let text = msg.text || msg.caption || "";
 
     // ── Incoming photo handling ───────────────────────────────────────────
     if (msg.photo && msg.photo.length > 0) {
@@ -617,16 +630,22 @@ class ChannelPoller {
           prompt: text,
           previousMessages,
           contextNote: `You are replying inside Telegram right now. Telegram channel="${this.channel.name}", author=${author}, chat_id=${chat_id}. Keep the reply plain-text and concise. Previous turns of this chat are included only for local conversational context; re-call tools for facts.`,
+          signal: abortCtrl.signal,
         });
         replyText = sa.text;
         replyAuthor = sa.name;
         saTrace = sa.trace;
         saUsage = sa.usage;
       } catch (e) {
+        if (abortCtrl.signal.aborted) {
+          this.log(`telegram[${this.channel.name}] request aborted for chat ${chat_id}`);
+          return; // don't send reply if aborted
+        }
         this.log(`telegram[${this.channel.name}] super-agent failed: ${e.message}`);
       }
     }
 
+    if (chat_id) this.activeRequests.delete(chat_id);
     if (!replyText) {
       stopTyping();
       return;

package/src/daemon/skills-loader.js

@@ -1,26 +1,28 @@
 // daemon/skills-loader.js
 // Discover and load APX skills on-demand for the super-agent.
 //
-// The super-agent reads skills from immutable INTERNAL sources under
-// src/core/ — they ship with apx and can never be deleted by the user. This
-// guarantees apx/apc/runtime knowledge is always available regardless of
-// what the user does to ~/.apx/skills/. Distribution copies under
-// <package>/skills/ are a separate concern (scaffold.js handles them) and
-// the loader does NOT read from there.
+// The super-agent reads skills from immutable INTERNAL sources under the
+// package root — they ship with apx and can never be deleted by the user.
+// This guarantees apx/apc/runtime knowledge is always available regardless
+// of what the user does to ~/.apx/skills/ or per-project overrides.
 //
 // Discovery order (priority high → low):
-//   1. <projectPath>/.apc/skills/<slug>.md          ← project-scoped
-//   1b.<projectPath>/.apc/skills/<slug>/SKILL.md    ← same, dir-style
-//   2. ~/.apx/skills/<slug>/SKILL.md                ← user-installed global
-//   3. <packageRoot>/src/core/runtime-skills/<slug>.md ← built-in runtime docs
-//                                                       (claude-code, codex-cli,
-//                                                       opencode-cli, openrouter)
-//   4. <packageRoot>/src/core/apx-skill.md          ← built-in intrinsic apx
-//   4b.<packageRoot>/src/core/apc-context-skill.md  ← built-in intrinsic apc-context
+//   1. <projectPath>/.apc/skills/<slug>.md           ← project-scoped (flat)
+//   1b.<projectPath>/.apc/skills/<slug>/SKILL.md     ← project-scoped (dir)
+//   2. ~/.apx/skills/<slug>/SKILL.md                 ← user-installed global
+//   3. <packageRoot>/skills/<slug>/SKILL.md          ← bundled core skills
+//                                                     (apx, apc-context)
+//   4. <packageRoot>/src/core/runtime-skills/<slug>.md
+//                                                     (claude-code, codex-cli,
+//                                                      opencode-cli, openrouter)
 //
-// A slug found in a higher-priority location SHADOWS lower ones — so a user
-// who drops `~/.apx/skills/apx/SKILL.md` overrides the intrinsic one, but the
-// intrinsic stays in the package as a safety net.
+// A slug found in a higher-priority location SHADOWS lower ones. A user can
+// override the bundled apc-context by dropping `~/.apx/skills/apc-context/SKILL.md`,
+// but the bundled copy stays in the package as a safety net.
+//
+// Note: the bundled `apc-context` skill is REFRESHED from the canonical apc
+// repo on every npm install / update (see src/cli/postinstall.js). APC is a
+// living standard, so its skill content is not pinned to an apx version.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -32,38 +34,8 @@ const __dirname  = path.dirname(__filename);
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
 
 const RUNTIME_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
+const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skills");
 const GLOBAL_DIR         = path.join(os.homedir(), ".apx", "skills");
-const CORE_DIR           = path.join(PACKAGE_ROOT, "src", "core");
-
-// Intrinsic built-in skills whose source files (src/core/*-skill.md) do NOT
-// carry frontmatter — the scaffold.js wrapper adds frontmatter when copying
-// these out to external IDE skill dirs. For the super-agent's catalog we
-// supply slug + description inline. Keep in sync with scaffold.js.
-const INTRINSIC = [
-  {
-    slug: "apx",
-    file: path.join(CORE_DIR, "apx-skill.md"),
-    description:
-      "APX CLI skill. Activate when: user asks to run or coordinate agents, " +
-      "use MCP tools from .apc/mcps.json, install agents from a team workspace, " +
-      "or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — " +
-      "that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', " +
-      "'run an agent', 'coordinate agents', 'MCP not working', 'install agent', " +
-      "'team agents', 'apx memory', 'daemon'.",
-  },
-  {
-    slug: "apc-context",
-    file: path.join(CORE_DIR, "apc-context-skill.md"),
-    description:
-      "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. " +
-      "Do not wait to be asked. Read .apc/ before making any assumption about agents, " +
-      "memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', " +
-      "'list agents', 'agent context', 'who are the agents', any question about agents " +
-      "or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the " +
-      "conversation with a migration offer before answering anything else. If the user " +
-      "declines, delete .apc/migrate.md immediately so it is not shown again.",
-  },
-];
 
 // ---------------------------------------------------------------------------
 // Frontmatter parsing (minimal — handles the YAML we ship)
@@ -153,15 +125,11 @@ export function listSkills({ projectPath } = {}) {
   // priority 2: user-installed global
   found.push(...scanDirStyle(GLOBAL_DIR, "global"));
 
-  // priority 3: built-in runtime docs (have frontmatter)
-  found.push(...scanFlatStyle(RUNTIME_SKILLS_DIR, "builtin"));
+  // priority 3: bundled core skills (apx, apc-context)
+  found.push(...scanDirStyle(BUNDLED_SKILLS_DIR, "builtin"));
 
-  // priority 4: intrinsic built-ins (no frontmatter — descriptions hardcoded)
-  for (const it of INTRINSIC) {
-    if (fs.existsSync(it.file)) {
-      found.push({ slug: it.slug, source: "builtin", file: it.file, _description: it.description });
-    }
-  }
+  // priority 4: runtime docs (claude-code, codex-cli, opencode-cli, openrouter)
+  found.push(...scanFlatStyle(RUNTIME_SKILLS_DIR, "builtin"));
 
   // dedupe by slug (first-wins = higher priority shadows lower)
   const seen = new Set();
@@ -170,15 +138,12 @@ export function listSkills({ projectPath } = {}) {
     if (seen.has(entry.slug)) continue;
     seen.add(entry.slug);
 
-    // Description: prefer inline (intrinsic) → frontmatter → empty
-    let description = entry._description || "";
-    if (!description) {
-      try {
-        const raw = fs.readFileSync(entry.file, "utf8");
-        const { fm } = parseFrontmatter(raw);
-        description = fm.description || "";
-      } catch { /* unreadable — skip description */ }
-    }
+    let description = "";
+    try {
+      const raw = fs.readFileSync(entry.file, "utf8");
+      const { fm } = parseFrontmatter(raw);
+      description = fm.description || "";
+    } catch { /* unreadable — skip description */ }
 
     result.push({
       slug: entry.slug,
@@ -223,6 +188,6 @@ export function loadSkill(slug, { projectPath } = {}) {
 // Useful for diagnostics
 export const SKILL_LOCATIONS = {
   runtime_skills: RUNTIME_SKILLS_DIR,
-  intrinsic: CORE_DIR,
+  bundled: BUNDLED_SKILLS_DIR,
   global: GLOBAL_DIR,
 };

package/src/daemon/smoke.js

@@ -14,7 +14,14 @@ import { readAgents } from "../core/parser.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const EXAMPLE = path.resolve(__dirname, "..", "..", "examples", "my-first-project");
+const EXAMPLE_CANDIDATES = [
+  path.resolve(__dirname, "..", "..", "examples", "my-first-project"),
+  path.resolve(__dirname, "..", "..", "..", "apc", "examples", "my-first-project"),
+];
+const EXAMPLE = EXAMPLE_CANDIDATES.find((p) =>
+  fs.existsSync(path.join(p, "AGENTS.md")) &&
+  fs.existsSync(path.join(p, ".apc", "project.json"))
+);
 
 function assert(cond, msg) {
   if (!cond) {
@@ -24,6 +31,7 @@ function assert(cond, msg) {
 }
 
 const projects = new ProjectManager();
+assert(EXAMPLE, `example project missing; checked ${EXAMPLE_CANDIDATES.join(", ")}`);
 const entry = projects.register(EXAMPLE);
 console.log("registered project", entry.id, entry.path);
 

package/src/daemon/super-agent-tools/index.js

@@ -22,6 +22,7 @@ import searchFiles from "./tools/search-files.js";
 import listSkills from "./tools/list-skills.js";
 import loadSkill from "./tools/load-skill.js";
 import transcribeAudio from "./tools/transcribe-audio.js";
+import askQuestions from "./tools/ask-questions.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 
@@ -50,6 +51,7 @@ const NATIVE_TOOLS = [
   listSkills,
   loadSkill,
   transcribeAudio,
+  askQuestions,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env