@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/apc/frontmatter.js

@@ -1,11 +1,13 @@
 // YAML-ish frontmatter — one parser.
 //
-// Four copies existed, and they did not agree on which keys are legal:
+// Six copies existed, and they did not agree on which keys are legal:
 //
 //   apc/parser.js        /^([a-zA-Z_-]+):/          dashes, no digits
 //   agent/skills/loader  /^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:/  digits and dashes, strips quotes
 //   core/sessions        /^([a-zA-Z_]+):/           neither
 //   cli/commands/session /^([a-zA-Z_]+):/           neither
+//   stores/sessions      /^([a-zA-Z_]+):/           neither
+//   stores/conversations /^([a-zA-Z_]+):/           neither
 //
 // That is not cosmetic duplication: a key like `route_to_agent2` or
 // `agent-slug` parsed in some code paths and vanished in others, so the same
@@ -16,12 +18,44 @@
 // digits and dashes, quoted values are unquoted) and returns everything the
 // callers between them needed: the fields, the body, and where the body starts.
 //
-// Deliberately not a YAML library: the frontmatter APX writes is flat
+// Still deliberately not a YAML library: the frontmatter APX *writes* is flat
 // `key: value` and staying strict about that keeps the format predictable for
-// the models that also read these files.
+// the models that also read these files. But APX also *reads* files it did not
+// write — every third-party skill dropped into ~/.apx/skills/ — and those come
+// from an ecosystem where a multi-line description is written as a block
+// scalar:
+//
+//   description: |
+//     Rewrite text that sounds AI-generated while keeping the writer's
+//     facts, meaning, and voice.
+//
+// A flat parser reads that as the literal string "|" and drops the rest. The
+// skill then lists and displays fine while the Skill Inspector embeds "|" as
+// its description, so it can never be matched — a silent failure with no error
+// anywhere, exactly the class of bug this file was created to end. So two
+// shapes beyond flat `key: value` are understood on the way IN:
+//
+//   • block scalars — `key: |` (literal, lines joined with \n) and `key: >`
+//     (folded, lines joined with a space, blank line = one \n).
+//   • nested maps   — `metadata:` followed by indented `key: value` children,
+//     flattened to dotted keys (`metadata.version`).
+//
+// Flattening rather than nesting is deliberate: every caller (and the web's
+// `frontmatter: Record<string, string>`) can keep assuming string values, so
+// reading a nested map is purely additive — nothing that worked before sees a
+// different shape. The parent key is still reported as "" exactly as it is
+// today, so a caller that reads `fm.metadata` is unaffected.
+//
+// What APX writes is unchanged: `setFrontmatterField` emits flat `key: value`
+// and only reaches for a block scalar when the value it is given contains a
+// newline — which previously produced a corrupt file.
 
 const KEY_VALUE = /^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/;
 
+// `|`, `>`, and their chomping/indent variants (`|-`, `>+`, `|2`). The
+// indicators are accepted but not honoured — see readBlockScalar.
+const BLOCK_SCALAR = /^([|>])[+-]?\d*$/;
+
 function unquote(value) {
   const v = value.trim();
   if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
@@ -30,6 +64,112 @@ function unquote(value) {
   return v;
 }
 
+/** Leading-whitespace width. Tabs count as one — indentation only has to be
+ *  comparable within a single file, not universally correct. */
+function indentOf(line) {
+  const m = line.match(/^[ \t]*/);
+  return m ? m[0].length : 0;
+}
+
+/**
+ * How far the entry that starts at `start` reaches: itself plus every
+ * following line indented deeper than it. A blank line belongs to the entry
+ * only when a deeper-indented line follows it — that keeps a paragraph break
+ * inside a block scalar, without swallowing the blank line an author left
+ * between two flat fields.
+ *
+ * @returns {number} exclusive end index; always > start.
+ */
+function entryExtent(lines, start, end, indent) {
+  let last = start;
+  for (let i = start + 1; i < end; i++) {
+    const line = lines[i];
+    if (line.trim() === "") continue;      // tentative — only kept if more follows
+    if (indentOf(line) <= indent) break;
+    last = i;
+  }
+  return last + 1;
+}
+
+/**
+ * Body of a block scalar: the lines in [start, end), stripped of the common
+ * indent established by the first non-blank one.
+ *
+ * Deviates from YAML in two places, both deliberate and both invisible for the
+ * frontmatter this parses: chomping indicators are ignored (trailing blank
+ * lines are always stripped — a trailing newline on a description would only
+ * surprise callers), and an explicit indent indicator (`|2`) is ignored in
+ * favour of the observed indent.
+ */
+function readBlockScalar(lines, start, end, style) {
+  const content = [];
+  let blockIndent = null;
+  for (let i = start; i < end; i++) {
+    const line = lines[i];
+    if (line.trim() === "") { content.push(""); continue; }
+    const ind = indentOf(line);
+    if (blockIndent === null) blockIndent = ind;
+    content.push(line.slice(Math.min(ind, blockIndent)));
+  }
+  while (content.length && content[content.length - 1] === "") content.pop();
+
+  if (style === "|") return content.join("\n");
+
+  // Folded: a run of lines becomes one space-joined line, a blank line ends
+  // the run and contributes the single newline between them.
+  const paragraphs = [];
+  let run = [];
+  for (const line of content) {
+    if (line.trim() === "") {
+      if (run.length) { paragraphs.push(run.join(" ")); run = []; }
+      continue;
+    }
+    run.push(line.trim());
+  }
+  if (run.length) paragraphs.push(run.join(" "));
+  return paragraphs.join("\n");
+}
+
+/**
+ * Parse the lines of one indentation level into `fm`, recursing into nested
+ * maps with dotted key prefixes.
+ *
+ * `levelIndent` is fixed by the caller for the top level (0, so a stray
+ * indented line stays skipped exactly as it always was) and observed from the
+ * first child for nested levels.
+ */
+function parseLevel(lines, start, end, prefix, levelIndent, fm) {
+  let indent = levelIndent;
+  let i = start;
+  while (i < end) {
+    const line = lines[i];
+    if (line.trim() === "") { i++; continue; }
+    const ind = indentOf(line);
+    if (indent === null) indent = ind;
+    if (ind < indent) break;                     // dedent — belongs to an outer level
+    if (ind > indent) { i++; continue; }         // deeper than this level and not claimed
+    const m = line.slice(ind).match(KEY_VALUE);
+    if (!m) { i++; continue; }                   // not `key: value` — skipped, never fatal
+
+    const key = prefix + m[1];
+    const rawValue = m[2].trim();
+    const stop = entryExtent(lines, i, end, ind);
+    const block = rawValue.match(BLOCK_SCALAR);
+
+    if (block) {
+      fm[key] = readBlockScalar(lines, i + 1, stop, block[1]);
+    } else if (rawValue === "" && stop > i + 1) {
+      // A bare `key:` with indented lines under it: a nested map. The parent
+      // keeps the "" it has always had; the children arrive as dotted keys.
+      fm[key] = "";
+      parseLevel(lines, i + 1, stop, `${key}.`, null, fm);
+    } else {
+      fm[key] = unquote(m[2]);
+    }
+    i = stop;
+  }
+}
+
 /**
  * Parse leading `---` frontmatter.
  *
@@ -49,10 +189,8 @@ export function parseFrontmatter(text) {
   if (end === -1) return { fm: {}, body: raw, bodyStart: 0 };
 
   const fm = {};
-  for (const line of raw.slice(openLen, end).split("\n")) {
-    const m = line.match(KEY_VALUE);
-    if (m) fm[m[1]] = unquote(m[2]);
-  }
+  const lines = raw.slice(openLen, end).split("\n");
+  parseLevel(lines, 0, lines.length, "", 0, fm);
 
   // The closing fence is followed by a newline, and authors conventionally
   // leave a blank line after it — consume both so `body` starts at content.
@@ -65,9 +203,27 @@ export function parseFrontmatterFields(text) {
   return parseFrontmatter(text).fm;
 }
 
+/**
+ * Render one `key: value` frontmatter entry as the line(s) it occupies.
+ * Single-line values are emitted exactly as they always were; a value that
+ * contains a newline becomes a literal block scalar, because writing it flat
+ * produces a file that no longer parses back to the same value.
+ *
+ * @returns {string[]} one entry, one line per element.
+ */
+export function formatFrontmatterEntry(key, value) {
+  const text = `${value}`;
+  if (!text.includes("\n")) return [`${key}: ${text}`];
+  return [`${key}: |`, ...text.split("\n").map((l) => (l ? `  ${l}` : ""))];
+}
+
 /**
  * Set or replace one field in place, preserving the rest of the file byte for
  * byte. Returns the text unchanged when there is no frontmatter to edit.
+ *
+ * Replacing a field that spans several lines (a block scalar, a nested map)
+ * replaces the whole entry — otherwise its continuation lines would be left
+ * orphaned under the new value.
  */
 export function setFrontmatterField(text, field, value) {
   const raw = String(text ?? "");
@@ -77,9 +233,9 @@ export function setFrontmatterField(text, field, value) {
 
   const lines = raw.slice(4, end).split("\n");
   const idx = lines.findIndex((l) => l.match(KEY_VALUE)?.[1] === field);
-  const entry = `${field}: ${value}`;
-  if (idx >= 0) lines[idx] = entry;
-  else lines.push(entry);
+  const entry = formatFrontmatterEntry(field, value);
+  if (idx >= 0) lines.splice(idx, entryExtent(lines, idx, lines.length, indentOf(lines[idx])) - idx, ...entry);
+  else lines.push(...entry);
 
   return `---\n${lines.join("\n")}${raw.slice(end)}`;
 }

package/src/core/apc/parser.js

@@ -6,66 +6,12 @@ import {
   apcAgentsDir,
   apcAgentFile,
   apcProjectFile,
-  agentsMdFile,
   isApcProject,
 } from "./paths.js";
 
 export const SLUG_RE = /^[a-z][a-z0-9_-]*$/;
-const H1_RE = /^#\s+Agents\s*$/i;
-const H2_RE = /^##\s+(\S.*?)\s*$/;
-const FIELD_RE = /^-\s+\*\*([^*]+?)\*\*\s*:\s*(.*)$/;
-const INDENT_CONT_RE = /^\s{2,}\S/;
 const LIST_FIELDS = new Set(["Skills", "Tools"]);
 
-// ---------------------------------------------------------------------------
-// AGENTS.md parser (legacy / Codex compat source)
-// ---------------------------------------------------------------------------
-
-export function parseAgentsMd(text) {
-  const stripped = text.replace(/<!--[\s\S]*?-->/g, "");
-  const lines = stripped.split(/\r?\n/);
-  const agents = [];
-  let current = null;
-  let pendingField = null;
-  let seenH1 = false;
-
-  for (const raw of lines) {
-    const line = raw.replace(/\s+$/, "");
-    if (H1_RE.test(line)) { seenH1 = true; continue; }
-    const mH2 = line.match(H2_RE);
-    if (mH2 && seenH1) {
-      const slug = mH2[1].trim();
-      if (SLUG_RE.test(slug)) {
-        current = { slug, fields: {} };
-        agents.push(current);
-        pendingField = null;
-      } else {
-        current = null; pendingField = null;
-      }
-      continue;
-    }
-    if (!current) continue;
-    const mField = line.match(FIELD_RE);
-    if (mField) {
-      const name = mField[1].trim();
-      const value = mField[2].trim();
-      current.fields[name] = LIST_FIELDS.has(name)
-        ? value.split(",").map((s) => s.trim()).filter(Boolean)
-        : value;
-      pendingField = name;
-      continue;
-    }
-    if (pendingField && INDENT_CONT_RE.test(raw)) {
-      const existing = current.fields[pendingField];
-      if (!Array.isArray(existing)) {
-        current.fields[pendingField] = existing ? `${existing} ${raw.trim()}` : raw.trim();
-      }
-      continue;
-    }
-    if (line.trim() === "") pendingField = null;
-  }
-  return agents;
-}
 
 // ---------------------------------------------------------------------------
 // Per-agent file parser  (.apc/agents/<slug>.md)
@@ -176,24 +122,39 @@ export function readVaultAgents({ includeRemoved = false } = {}) {
   return [...bySlug.values()].sort((a, b) => a.slug.localeCompare(b.slug));
 }
 
-// Resolve a single vault agent honoring the layered model. Returns null when
-// the slug is missing or tombstoned (unless includeRemoved is true).
-function readVaultAgent(slug, { includeRemoved = false } = {}) {
+// WHERE a vault slug's definition actually lives, honoring the layered model:
+// user file wins, bundled default is the fallback, a tombstoned slug resolves
+// to nothing. Returns null when the slug is unusable or absent.
+//
+// Every caller that needs the FILE — the import tool, `apx agent import`,
+// readAgents() resolving an imported slug — must come through here. Each of
+// them used to build `path.join(VAULT_DIR, slug + ".md")` by hand, which sees
+// ONLY the user layer: on a machine where ~/.apx/agents holds nothing (the
+// normal state — the bundle is the vault most people ever use), every bundled
+// agent looked missing while list_vault_agents listed it happily. Importing
+// one failed with "not found in vault. Available: <the very slug you asked
+// for>", and an already-imported one silently vanished from its project.
+export function vaultAgentFile(slug, { includeRemoved = false } = {}) {
+  if (!slug || !SLUG_RE.test(slug)) return null;
   if (!includeRemoved && readVaultTombstones().has(slug)) return null;
   const userPath = path.join(VAULT_DIR, `${slug}.md`);
-  if (fs.existsSync(userPath)) {
-    const agent = parseAgentFile(slug, fs.readFileSync(userPath, "utf8"));
-    const overrides = fs.existsSync(path.join(BUNDLED_VAULT_DIR, `${slug}.md`));
-    return { ...agent, source: overrides ? "user-override" : "user" };
-  }
+  if (fs.existsSync(userPath)) return userPath;
   const bundledPath = path.join(BUNDLED_VAULT_DIR, `${slug}.md`);
-  if (fs.existsSync(bundledPath)) {
-    const agent = parseAgentFile(slug, fs.readFileSync(bundledPath, "utf8"));
-    return { ...agent, source: "bundled" };
-  }
+  if (fs.existsSync(bundledPath)) return bundledPath;
   return null;
 }
 
+// Resolve a single vault agent honoring the layered model. Returns null when
+// the slug is missing or tombstoned (unless includeRemoved is true).
+function readVaultAgent(slug, { includeRemoved = false } = {}) {
+  const file = vaultAgentFile(slug, { includeRemoved });
+  if (!file) return null;
+  const agent = parseAgentFile(slug, fs.readFileSync(file, "utf8"));
+  if (path.dirname(file) !== VAULT_DIR) return { ...agent, source: "bundled" };
+  const overrides = fs.existsSync(path.join(BUNDLED_VAULT_DIR, `${slug}.md`));
+  return { ...agent, source: overrides ? "user-override" : "user" };
+}
+
 // Resolve a single agent for a project: local file → vault (layered) → null.
 export function resolveAgent(root, slug) {
   const localPath = apcAgentFile(root, slug);
@@ -219,7 +180,7 @@ export function importedVaultSlugs(root) {
 // Resolution order:
 //   1. .apc/agents/<slug>.md  (local — overrides everything)
 //   2. ~/.apx/agents/<slug>.md  (vault — for imported slugs)
-//   3. Legacy hand-written AGENTS.md (not auto-generated)
+// AGENTS.md is the project's startup-rules file, never an agent registry.
 export function readAgents(root) {
   const fromFiles = readAgentsFromDir(root).map((a) => ({ ...a, source: "local" }));
   const localSlugs = new Set(fromFiles.map((a) => a.slug));
@@ -229,27 +190,16 @@ export function readAgents(root) {
   const vaultAgents = imported
     .filter((slug) => !localSlugs.has(slug))
     .map((slug) => {
-      const vaultPath = path.join(VAULT_DIR, `${slug}.md`);
-      if (!fs.existsSync(vaultPath)) return null;
+      // includeRemoved: hiding a template from the vault listing must not
+      // delete the agent out of a project that already imported it.
+      const vaultPath = vaultAgentFile(slug, { includeRemoved: true });
+      if (!vaultPath) return null;
       const agent = parseAgentFile(slug, fs.readFileSync(vaultPath, "utf8"));
       return { ...agent, source: "vault" };
     })
     .filter(Boolean);
 
-  const all = [...fromFiles, ...vaultAgents];
-  const allSlugs = new Set(all.map((a) => a.slug));
-
-  const agentsMdPath = agentsMdFile(root);
-  if (!fs.existsSync(agentsMdPath)) return all;
-
-  const mdText = fs.readFileSync(agentsMdPath, "utf8");
-  if (mdText.includes("Auto-generated from .apc/agents/")) return all;
-
-  // Legacy hand-written AGENTS.md
-  const legacy = parseAgentsMd(mdText)
-    .filter((a) => !allSlugs.has(a.slug))
-    .map((a) => ({ ...a, source: "legacy" }));
-  return [...all, ...legacy];
+  return [...fromFiles, ...vaultAgents];
 }
 
 // ---------------------------------------------------------------------------

package/src/core/apc/paths.js

@@ -44,10 +44,6 @@ export function apcAgentFile(root, slug) {
   return path.join(root, APC_DIR, APC_AGENTS_DIR, `${slug}.md`);
 }
 
-export function apcAgentMemoryFile(root, slug) {
-  return path.join(root, APC_DIR, APC_AGENTS_DIR, slug, "memory.md");
-}
-
 export function apcRemovedFile(root) {
   return path.join(root, APC_DIR, APC_AGENTS_DIR, APC_REMOVED_FILE);
 }
@@ -68,8 +64,10 @@ export function apcNotesDir(root) {
   return path.join(root, APC_DIR, APC_NOTES_DIR);
 }
 
-// Project-level memory (super-agent / project-wide), distinct from the
-// per-agent memory.md that lives under .apc/agents/<slug>/.
+// Project-level memory: curated, committed, written by a person. This is the
+// ONLY memory.md that belongs inside a repo. A single agent's memory is runtime
+// state and lives in ~/.apx/projects/<apx_id>/agents/<slug>/memory.md — see
+// core/agent/memory.js. There is deliberately no builder for it here.
 export function apcMemoryFile(root) {
   return path.join(root, APC_DIR, APC_PROJECT_MEMORY_FILE);
 }

package/src/core/apc/project-memory.js

@@ -0,0 +1,44 @@
+// A project's CURATED memory — `<repo>/.apc/memory.md`. Committed.
+//
+// What the PROJECT knows and the team may read: what this repo is, who owns it,
+// the decisions that outlive a session. Distinct from what one agent knows
+// (per-agent memory.md), from what the super-agent knows everywhere
+// (~/.apx/memory.md), and — the distinction that matters most here — from the
+// project's LOCAL memory (core/stores/project-memory.js), which is never
+// committed and is where the agent actually writes.
+//
+// NOTHING AUTOMATIC WRITES THIS FILE. That is the rule, and it is APC's:
+// `.apc/` memory is "only for curated project facts safe for the team", while
+// private runtime memory belongs in the runtime's own store because it "often
+// contains sensitive prompts, credentials pasted by mistake, customer data".
+// A file that git will carry forever is written by a person who read it first.
+// The writer here is the Memories editor (a human pressing Save) and the
+// dangerous-gated file tools, which ask before they touch a repo.
+//
+// It still has an automatic READER: the RAG indexer scopes it to `project:<id>`,
+// so curated facts come back as context without being re-typed.
+import fs from "node:fs";
+import { apcDir, apcMemoryFile } from "./paths.js";
+
+export { apcMemoryFile as projectMemoryPath };
+
+/** Read the memory body. "" when the file doesn't exist. Never throws. */
+export function readProjectMemory(root) {
+  try {
+    return fs.readFileSync(apcMemoryFile(root), "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Replace the whole body — the Memories editor's Save, and the only writer.
+ * There is deliberately no append helper here: an appender is what an automatic
+ * caller reaches for, and this file is not written automatically.
+ */
+export function writeProjectMemory(root, body) {
+  const file = apcMemoryFile(root);
+  fs.mkdirSync(apcDir(root), { recursive: true });
+  fs.writeFileSync(file, body);
+  return { path: file, bytes: Buffer.byteLength(body, "utf8") };
+}

package/src/core/apc/projects-helpers.js

@@ -12,9 +12,42 @@ export function projectMeta(projects, entry) {
   };
 }
 
+/**
+ * The registry, scoped to the project a turn BELONGS to.
+ *
+ * `resolveProject` used to read an omitted `project` argument as "the default
+ * project", which is right for the super-agent (it orchestrates across all of
+ * them) and wrong for anyone who lives in one. A routine run by Magui in Appsi
+ * called `run_shell tail work/marketing/magui/brain.md` and got
+ * `~/.apx/projects/default` — her own notes, one directory over, reported as
+ * "No such file or directory". Every scheduled run since had been working from
+ * an empty memory and writing its entry where nobody reads it.
+ *
+ * Scoping at the registry — rather than threading a project through all 30-odd
+ * handlers — means a tool that takes an optional `project` keeps its exact
+ * signature and simply defaults to the right one. An EXPLICIT argument still
+ * wins, `project: "default"` still means the default project, and an unscoped
+ * registry behaves exactly as before.
+ *
+ * The wrapper delegates through the prototype chain: the registry keeps one set
+ * of entries and one cache, and a scope is a view of it, never a copy.
+ */
+export function scopeProjects(projects, projectId) {
+  if (!projects || projectId === undefined || projectId === null) return projects;
+  const self = projects.get?.(projectId);
+  if (!self) return projects;
+  return Object.assign(Object.create(projects), { current: () => self });
+}
+
 export function resolveProject(projects, target, { allowMulti = false } = {}) {
   if (target === undefined || target === null || target === "") {
     if (allowMulti) return null;
+    // Whose turn this is, when the caller said (see `scopeProjects`). Ahead of
+    // the default project, because "the project I belong to" is what an agent
+    // means by an unqualified path — and behind an explicit argument, which is
+    // handled below and still addresses any project by id, name or path.
+    const scoped = projects.current?.();
+    if (scoped) return scoped;
     const defaultProject = projects.get(0);
     if (defaultProject) return defaultProject;
     const all = projects.list();

package/src/core/apc/scaffold.js

@@ -10,6 +10,7 @@ import {
   writeVaultTombstones,
 } from "./parser.js";
 import { readApcContextSkill } from "./skill-sync.js";
+import { formatFrontmatterEntry } from "./frontmatter.js";
 import { nowIso } from "../util/time.js";
 import {
   apcDir,
@@ -137,7 +138,7 @@ export const IDE_TARGETS = [
 // 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
+  path.join(os.homedir(), ".claude", "skills"),    // Claude Code (Cursor reads it too)
   path.join(os.homedir(), ".cursor", "skills"),    // Cursor primary global path
   path.join(os.homedir(), ".codex",  "skills"),    // Codex (OpenAI)
   path.join(os.homedir(), ".agents", "skills"),    // Antigravity/other skills.sh adopters
@@ -215,10 +216,11 @@ export function listEngineSkills() {
   return listBundledSkills();
 }
 
-// Legacy slugs APX used to ship to global dirs but no longer does — exposed so
-// the CLI can report what `installGlobalSkills` will prune.
-export function listLegacyPruneSlugs() {
-  return [...PRUNE_LEGACY_SLUGS];
+// Slugs APX used to ship to global dirs but no longer does — exposed so the
+// CLI can report what `installGlobalSkills` will prune. Add to this list every
+// time a slug leaves the published set, or stale copies linger forever.
+export function listRetiredSkillSlugs() {
+  return [...RETIRED_SKILL_SLUGS];
 }
 
 function discoverBundledSkills() {
@@ -248,12 +250,12 @@ function discoverBundledSkills() {
 // compatibility with `apx skills sync --include-…`; the slim set has no tiers.
 //
 // Pruning: removes stale APX-shipped slugs that are no longer in the engine
-// set (the catalog of slugs APX has ever published, see PRUNE_LEGACY_SLUGS).
+// set (the catalog of slugs APX has ever published, see RETIRED_SKILL_SLUGS).
 // Skills the user installed themselves are NOT touched.
 //
 // Returns an array of { dir, skill, file, status, scope }.
 //   status ∈ {created, updated, unchanged, pruned}
-const PRUNE_LEGACY_SLUGS = [
+const RETIRED_SKILL_SLUGS = [
   "apx-agency-agents",
   "apx-agent",
   "apx-mcp-builder",
@@ -298,13 +300,13 @@ export function installGlobalSkills({
       results.push({ dir: base, skill: slug, file: dest, status: existed ? "updated" : "created", scope: "engine" });
     }
     if (prune) {
-      for (const slug of PRUNE_LEGACY_SLUGS) {
+      for (const slug of RETIRED_SKILL_SLUGS) {
         if (wantedSlugs.has(slug)) continue;
         const dest = path.join(base, slug, "SKILL.md");
         if (!fs.existsSync(dest)) continue;
         fs.unlinkSync(dest);
         try { fs.rmdirSync(path.dirname(dest)); } catch {}
-        results.push({ dir: base, skill: slug, file: dest, status: "pruned", scope: "legacy" });
+        results.push({ dir: base, skill: slug, file: dest, status: "pruned", scope: "retired" });
       }
     }
   }
@@ -339,7 +341,7 @@ const AGENTS_MD_TEMPLATE = `# AGENTS.md
 const APC_GITIGNORE = `# APC repository-safe context only.
 # Runtime state belongs in ~/.apx/projects/<id>/, not in .apc/.
 
-# Legacy per-agent runtime dirs (agent definitions are flat: agents/<slug>.md)
+# Per-agent runtime dirs (agent definitions are flat: agents/<slug>.md)
 agents/*/
 
 # Runtime sessions / conversations / messages
@@ -500,14 +502,14 @@ export function ensureAgentDir(root, _slug) {
 export function writeAgentFile(root, slug, fields, body = "") {
   const dest = apcAgentFile(root, slug);
   const lines = ["---"];
-  const order = ["role", "model", "language", "description", "skills", "tools"];
+  const order = ["name", "role", "model", "language", "description", "skills", "tools"];
   const written = new Set();
   for (const key of order) {
     const titleKey = key.charAt(0).toUpperCase() + key.slice(1);
     const v = fields[titleKey] ?? fields[key];
     if (v === undefined || v === null || v === "") continue;
     const value = Array.isArray(v) ? v.join(", ") : v;
-    lines.push(`${key}: ${value}`);
+    lines.push(...formatFrontmatterEntry(key, value));
     written.add(titleKey);
   }
   // Any extra fields not in the ordered list
@@ -515,7 +517,7 @@ export function writeAgentFile(root, slug, fields, body = "") {
     const titleKey = k.charAt(0).toUpperCase() + k.slice(1);
     if (written.has(titleKey) || v === undefined || v === null || v === "") continue;
     const value = Array.isArray(v) ? v.join(", ") : v;
-    lines.push(`${k.toLowerCase()}: ${value}`);
+    lines.push(...formatFrontmatterEntry(k.toLowerCase(), value));
   }
   lines.push("---");
   if (body) lines.push("", body);
@@ -527,19 +529,19 @@ export function writeVaultAgentFile(slug, fields, body = "") {
   fs.mkdirSync(VAULT_DIR, { recursive: true });
   const dest = path.join(VAULT_DIR, `${slug}.md`);
   const lines = ["---"];
-  const order = ["role", "model", "language", "description", "skills", "tools"];
+  const order = ["name", "role", "model", "language", "description", "skills", "tools"];
   const written = new Set();
   for (const key of order) {
     const titleKey = key.charAt(0).toUpperCase() + key.slice(1);
     const v = fields[titleKey] ?? fields[key];
     if (v === undefined || v === null || v === "") continue;
-    lines.push(`${key}: ${Array.isArray(v) ? v.join(", ") : v}`);
+    lines.push(...formatFrontmatterEntry(key, Array.isArray(v) ? v.join(", ") : v));
     written.add(titleKey);
   }
   for (const [k, v] of Object.entries(fields)) {
     const titleKey = k.charAt(0).toUpperCase() + k.slice(1);
     if (written.has(titleKey) || v === undefined || v === null || v === "") continue;
-    lines.push(`${k.toLowerCase()}: ${Array.isArray(v) ? v.join(", ") : v}`);
+    lines.push(...formatFrontmatterEntry(k.toLowerCase(), Array.isArray(v) ? v.join(", ") : v));
   }
   lines.push("---");
   if (body) lines.push("", body);
@@ -595,6 +597,24 @@ export function addImportedAgent(root, slug) {
   fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
 }
 
+// Drop a slug from the project's agents.imported list. The counterpart of
+// addImportedAgent, and the reason a rename does not leave a ghost: an imported
+// agent has NO local file (readAgents resolves it from the vault by that list),
+// so renaming it writes the new slug locally and the old one keeps resolving
+// from the vault — the same agent showing up twice in the roster, one card with
+// the chats and one with the history. Returns whether anything was removed;
+// a project with no project.json or no list is a no-op, not an error.
+export function removeImportedAgent(root, slug) {
+  const p = apcProjectFile(root);
+  if (!fs.existsSync(p)) return false;
+  const cfg = readJson(p, null);
+  const imported = cfg?.agents?.imported;
+  if (!Array.isArray(imported) || !imported.includes(slug)) return false;
+  cfg.agents.imported = imported.filter((s) => s !== slug);
+  fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+  return true;
+}
+
 // NOTE: AGENTS.md is created once at `apx init` (see AGENTS_MD_TEMPLATE) and is
 // thereafter owned by the user — APX never regenerates it. Agents live in
 // `.apc/agents/<slug>.md` (read by parser.js readAgents); they are NOT listed