arcane-cli 1.2.0 → 1.3.0

package/dist/index.js

@@ -6,11 +6,11 @@ const require = __createRequire(import.meta.url);
 import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";
 import { fileURLToPath } from "url";
-import { dirname as dirname10, join as join18 } from "path";
+import { dirname as dirname11, join as join18 } from "path";
 
 // src/commands/init.ts
 import { select as select2, confirm, input as input2 } from "@inquirer/prompts";
-import { dirname as dirname3, join as join6 } from "path";
+import { dirname as dirname4, join as join6 } from "path";
 import chalk2 from "chalk";
 
 // src/modules/copier.ts
@@ -1035,18 +1035,25 @@ function spellIdsInStore(components) {
   }
   return [...ids].sort();
 }
+var USER_AGENT_FANOUT_DIR = ".copilot/agents";
+var SPELL_FANOUT_CLIENTS = ["codex", "claude"];
 var USER_FANOUT_PATHS = {
   codex: (id) => `.agents/skills/${id}/SKILL.md`,
   claude: (id) => `.claude/commands/${id}.md`
 };
+function userAgentFanoutPath(slug) {
+  return `${USER_AGENT_FANOUT_DIR}/${slug}.agent.md`;
+}
 var FANOUT_CLIENT_LABELS = {
   codex: "Codex/Copilot skills",
-  claude: "Claude Code commands"
+  claude: "Claude Code commands",
+  "copilot-agents": "Copilot agent modes"
 };
 function clientOfFanoutPath(relativePath) {
   const normalized = relativePath.replace(/\\/g, "/");
   if (normalized.startsWith(".agents/skills/")) return "codex";
   if (normalized.startsWith(".claude/commands/")) return "claude";
+  if (normalized.startsWith(`${USER_AGENT_FANOUT_DIR}/`)) return "copilot-agents";
   return void 0;
 }
 async function readSpellSource(storeRoot, id, fallbackDir) {
@@ -1108,14 +1115,16 @@ async function removeDirectoryIfEmpty(dir) {
 }
 async function syncUserTierFanout(options) {
   const rendered = await renderUserFanout(options.storeRoot, options.spellIds, options.fallbackDir);
-  const desired = rendered.files;
+  const desired = [...rendered.files, ...options.extraFiles ?? []];
+  const owned = options.ownedClients;
+  const ownsClient = (client) => owned === void 0 || client !== void 0 && owned.includes(client);
   const previous = options.previous ?? {};
   const dryRun = Boolean(options.dryRun);
   const record = {};
   const outcomes = [];
   const desiredPaths = new Set(desired.map((f) => f.relativePath));
   for (const id of rendered.missing) {
-    for (const client of ["codex", "claude"]) {
+    for (const client of SPELL_FANOUT_CLIENTS) {
       const relativePath = USER_FANOUT_PATHS[client](id);
       desiredPaths.add(relativePath);
       if (previous[relativePath] !== void 0) record[relativePath] = previous[relativePath];
@@ -1158,6 +1167,10 @@ async function syncUserTierFanout(options) {
   }
   for (const [relativePath, recorded] of Object.entries(previous)) {
     if (desiredPaths.has(relativePath)) continue;
+    if (!ownsClient(clientOfFanoutPath(relativePath))) {
+      record[relativePath] = recorded;
+      continue;
+    }
     validateTargetPath(options.homeDir, relativePath);
     const target = join(options.homeDir, relativePath);
     const state = await classifyTarget(target);
@@ -1198,7 +1211,7 @@ function describeFanoutOutcomes(outcomes, dryRun = false) {
   const lines = [];
   const prefix = dryRun ? "[dry-run] Would " : "";
   const byClient = (status) => {
-    const n = { codex: 0, claude: 0 };
+    const n = { codex: 0, claude: 0, "copilot-agents": 0 };
     for (const o of outcomes) {
       if (o.status !== status) continue;
       const client = clientOfFanoutPath(o.relativePath);
@@ -1209,8 +1222,9 @@ function describeFanoutOutcomes(outcomes, dryRun = false) {
   const paths = (status) => outcomes.filter((o) => o.status === status).map((o) => `    ~/${o.relativePath}`).join("\n");
   if (counts.written > 0) {
     const n = byClient("written");
+    const breakdown = Object.keys(n).filter((client) => n[client] > 0).map((client) => `${n[client]} ${FANOUT_CLIENT_LABELS[client]}`).join(", ");
     lines.push(
-      `${prefix}${dryRun ? "write" : "Wrote"} ${counts.written} client file(s): ${n.codex} ${FANOUT_CLIENT_LABELS.codex}, ${n.claude} ${FANOUT_CLIENT_LABELS.claude}.`
+      `${prefix}${dryRun ? "write" : "Wrote"} ${counts.written} client file(s): ${breakdown}.`
     );
   }
   if (counts.pruned > 0) {
@@ -1248,7 +1262,7 @@ ${paths("kept-edited")}`
 async function inspectUserTierFanout(homeDir, record) {
   const health = {
     total: 0,
-    byClient: { codex: 0, claude: 0 },
+    byClient: { codex: 0, claude: 0, "copilot-agents": 0 },
     missing: [],
     customized: []
   };
@@ -1425,7 +1439,7 @@ function printWarning(message) {
 // src/modules/agents.ts
 import { select, checkbox, Separator } from "@inquirer/prompts";
 import { mkdir as mkdir4, writeFile as writeFile6, copyFile as copyFile2 } from "fs/promises";
-import { join as join4 } from "path";
+import { dirname as dirname2, join as join4 } from "path";
 import { stringify } from "yaml";
 
 // src/config/agent-roles.ts
@@ -1834,9 +1848,15 @@ var AgentDefinitionNotFoundError = class extends Error {
   }
 };
 var AgentRosterNotFoundError = class extends Error {
-  constructor() {
+  /**
+   * Names the tier the caller actually asked for. A `--user` run that reports
+   * the repository's path sends the operator to the wrong file and the wrong
+   * command, which is worse than no message.
+   */
+  constructor(scope = "repo") {
+    const user = scope === "user";
     super(
-      'No agent roster found at .arcane/agents.yaml. Run "spell agents init" to create one.'
+      `No agent roster found at ${user ? "~/.arcane/agents.yaml" : ".arcane/agents.yaml"}. Run "spell agents init${user ? " --user" : ""}" to create one.`
     );
     this.name = "AgentRosterNotFoundError";
   }
@@ -1859,30 +1879,33 @@ async function loadAgentDefinition(agentsDir, id) {
   }
   return validateAgentDefinition(parseYaml2(content, filePath), filePath);
 }
-async function loadRoster(targetDir) {
-  const rosterPath = join2(targetDir, ".arcane", "agents.yaml");
+function agentsBaseDir(targetDir, scope = "repo") {
+  return scope === "user" ? targetDir : join2(targetDir, ".arcane");
+}
+async function loadRoster(targetDir, scope = "repo") {
+  const rosterPath = join2(agentsBaseDir(targetDir, scope), "agents.yaml");
   let content;
   try {
     content = await readFile4(rosterPath, "utf8");
   } catch {
-    throw new AgentRosterNotFoundError();
+    throw new AgentRosterNotFoundError(scope);
   }
   return validateAgentRoster(parseYaml2(content, rosterPath), rosterPath);
 }
-async function rosterExists(targetDir) {
+async function rosterExists(targetDir, scope = "repo") {
   try {
-    await access2(join2(targetDir, ".arcane", "agents.yaml"));
+    await access2(join2(agentsBaseDir(targetDir, scope), "agents.yaml"));
     return true;
   } catch {
     return false;
   }
 }
-function projectAgentsDir(targetDir) {
-  return join2(targetDir, ".arcane", "agents");
+function projectAgentsDir(targetDir, scope = "repo") {
+  return join2(agentsBaseDir(targetDir, scope), "agents");
 }
 
 // src/modules/agent-generator.ts
-import { writeFile as writeFile5, mkdir as mkdir3 } from "fs/promises";
+import { writeFile as writeFile5, mkdir as mkdir3, readdir as readdir4 } from "fs/promises";
 import { join as join3 } from "path";
 import { homedir as homedir2 } from "os";
 
@@ -2091,11 +2114,23 @@ function renderAgentRosterSection(entries) {
 ${rows}
 `;
 }
+async function existingAgentFiles(agentsDir) {
+  try {
+    const entries = await readdir4(agentsDir);
+    return entries.filter((name) => name.endsWith(".agent.md")).sort().map((name) => `.github/agents/${name}`);
+  } catch {
+    return [];
+  }
+}
 async function syncAgents(targetDir, assetsDir, roster, options = {}) {
   const synced = [];
   const skipped = [];
   let hasUnresolvedRoles = false;
-  const projectDefs = projectAgentsDir(targetDir);
+  const userTier = options.scope === "user";
+  const repoOptedOut = !userTier && options.spellScope === "user";
+  const userAgentFiles = [];
+  const unmanagedAgentFiles = [];
+  const projectDefs = projectAgentsDir(targetDir, userTier ? "user" : "repo");
   const bundledDefs = join3(assetsDir, "agents");
   const resolved = [];
   for (const entry of roster.roster) {
@@ -2117,7 +2152,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       displayName: entry.name ?? entry.definition
     });
   }
-  if (roster.openclaw.enabled && options.openclaw !== false) {
+  if (!userTier && roster.openclaw.enabled && options.openclaw !== false) {
     const openclawRoot = roster.openclaw.workspace_root.replace(
       /^~/,
       homedir2()
@@ -2182,34 +2217,46 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
   }
   if (options.copilot !== false) {
     const agentsDir = join3(targetDir, ".github", "agents");
-    if (!options.dryRun) {
-      await mkdir3(agentsDir, { recursive: true });
+    if (!options.dryRun && !userTier) {
+      await mkdir3(repoOptedOut ? join3(targetDir, ".github") : agentsDir, { recursive: true });
     }
     for (const { def, displayName } of resolved) {
       if (!def.clients.copilot?.agent_file) continue;
       const slug = displayName.toLowerCase().replace(/\s+/g, "-");
       const fileName = `${slug}.agent.md`;
+      const content = renderCopilotAgent(def, displayName);
+      if (userTier) {
+        const relativePath = userAgentFanoutPath(slug);
+        userAgentFiles.push({ relativePath, client: "copilot-agents", content });
+        synced.push(`~/${relativePath}`);
+        continue;
+      }
+      if (repoOptedOut) continue;
       if (!options.dryRun) {
-        await writeFile5(
-          join3(agentsDir, fileName),
-          renderCopilotAgent(def, displayName),
-          "utf8"
-        );
+        await writeFile5(join3(agentsDir, fileName), content, "utf8");
       } else {
         console.log(`  [dry-run] Would write: .github/agents/${fileName}`);
       }
       synced.push(`.github/agents/${fileName}`);
     }
-    const copilotSection = `${renderSpellRoutingSection()}
+    if (repoOptedOut) {
+      unmanagedAgentFiles.push(...await existingAgentFiles(agentsDir));
+    }
+    if (!userTier) {
+      const copilotSection = `${renderSpellRoutingSection()}
 ${renderAgentRosterSection(resolved)}`;
-    const copilotMerged = await mergeIntoFile(
-      targetDir,
-      ".github/copilot-instructions.md",
-      copilotSection,
-      { force: true, dryRun: options.dryRun }
-    );
-    if (copilotMerged)
-      synced.push(".github/copilot-instructions.md (agents section)");
+      const copilotMerged = await mergeIntoFile(
+        targetDir,
+        ".github/copilot-instructions.md",
+        copilotSection,
+        { force: true, dryRun: options.dryRun }
+      );
+      if (copilotMerged)
+        synced.push(".github/copilot-instructions.md (agents section)");
+    }
+  }
+  if (userTier) {
+    return { synced, skipped, hasUnresolvedRoles, userAgentFiles, unmanagedAgentFiles };
   }
   if (options.claude !== false) {
     const claudeSection = `${renderSpellRoutingSection()}
@@ -2233,12 +2280,83 @@ ${renderAgentRosterSection(resolved)}`;
     );
     if (codexMerged) synced.push("AGENTS.md (agents section)");
   }
-  return { synced, skipped, hasUnresolvedRoles };
+  return { synced, skipped, hasUnresolvedRoles, userAgentFiles, unmanagedAgentFiles };
 }
 
 // src/modules/agents.ts
+function agentsTargetDir(scope, cwd) {
+  return scope === "user" ? userTierRoot() : cwd;
+}
+async function requireUserStore(storeRoot) {
+  try {
+    return await readManifest(storeRoot);
+  } catch {
+    console.error(
+      `
+  \u2717 No user tier at ${storeRoot}.
+    Run \`spell init --user\` once to create it, then re-run this command.
+`
+    );
+    process.exit(1);
+    throw new Error("unreachable");
+  }
+}
+async function repoSpellScope(targetDir) {
+  try {
+    return effectiveSpellScope(await readManifest(targetDir));
+  } catch {
+    return "repo";
+  }
+}
+async function performAgentSync(targetDir, assetsDir, roster, options) {
+  const scope = options.scope ?? "repo";
+  const spellScope = scope === "user" ? void 0 : await repoSpellScope(targetDir);
+  const result = await syncAgents(targetDir, assetsDir, roster, {
+    ...options,
+    scope,
+    ...spellScope === void 0 ? {} : { spellScope }
+  });
+  if (scope === "user") {
+    const manifest = await requireUserStore(targetDir);
+    const fanout = await syncUserTierFanout({
+      homeDir: dirname2(targetDir),
+      storeRoot: targetDir,
+      spellIds: [],
+      extraFiles: result.userAgentFiles,
+      ownedClients: ["copilot-agents"],
+      previous: manifest.fanout,
+      dryRun: options.dryRun,
+      fallbackDir: assetsDir
+    });
+    for (const line of describeFanoutOutcomes(fanout.outcomes, options.dryRun)) {
+      console.log(`  ${line}`);
+    }
+    if (!options.dryRun) {
+      await writeManifest(targetDir, { ...manifest, fanout: fanout.record });
+    }
+  }
+  if (result.unmanagedAgentFiles.length > 0) {
+    console.log(
+      `
+  ! This repository takes its spells from the user tier (spell_scope: "user"), so it no
+    longer receives agent files of its own. ${result.unmanagedAgentFiles.length} are still on disk
+    from before the opt-out. Nothing here deletes them -- no component ever tracked
+    them, so there is no recorded hash to prove one untouched. Remove them yourself:
+`
+    );
+    for (const file of result.unmanagedAgentFiles) console.log(`      ${file}`);
+    console.log(`
+      git rm ${result.unmanagedAgentFiles.join(" ")}
+`);
+  }
+  return result;
+}
 async function runAgentsInit(options, targetDir, assetsDir) {
-  if (!options.force && await rosterExists(targetDir)) {
+  const scope = options.scope ?? "repo";
+  if (scope === "user") await requireUserStore(targetDir);
+  const baseDir = agentsBaseDir(targetDir, scope);
+  const label = scope === "user" ? "~/.arcane" : ".arcane";
+  if (!options.force && await rosterExists(targetDir, scope)) {
     console.log(
       'Agent roster already exists at .arcane/agents.yaml. Run "spell agents sync" to regenerate outputs, or use --force to reinitialize.'
     );
@@ -2332,16 +2450,12 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
     },
     roster: rosterEntries
   };
-  const arcaneDir = join4(targetDir, ".arcane", "agents");
+  const arcaneDir = join4(baseDir, "agents");
   if (!options.dryRun) {
     await mkdir4(arcaneDir, { recursive: true });
-    await writeFile6(
-      join4(targetDir, ".arcane", "agents.yaml"),
-      stringify(roster),
-      "utf8"
-    );
+    await writeFile6(join4(baseDir, "agents.yaml"), stringify(roster), "utf8");
   } else {
-    console.log("  [dry-run] Would write: .arcane/agents.yaml");
+    console.log(`  [dry-run] Would write: ${label}/agents.yaml`);
   }
   for (const roleId of selectedRoleIds) {
     const src = join4(assetsDir, "agents", `${roleId}.yaml`);
@@ -2353,7 +2467,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
         console.warn(`  ! Could not copy definition for "${roleId}" \u2014 skipping`);
       }
     } else {
-      console.log(`  [dry-run] Would copy: .arcane/agents/${roleId}.yaml`);
+      console.log(`  [dry-run] Would copy: ${label}/agents/${roleId}.yaml`);
     }
   }
   if (options.dryRun) {
@@ -2364,20 +2478,24 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
     return;
   }
   printStep("Syncing agent definitions to all clients...");
-  const { synced, skipped, hasUnresolvedRoles } = await syncAgents(
+  const { synced, skipped, hasUnresolvedRoles } = await performAgentSync(
     targetDir,
     assetsDir,
     roster,
-    { dryRun: false }
+    { dryRun: false, scope }
   );
   printSuccess("Agent roster initialized");
   console.log(`    \u{1F4CB} Profile: ${profileId} \xB7 Naming: ${namingStrategy} \xB7 Agents: ${rosterEntries.length}`);
-  console.log(`    \u{1F504} Synced: ${synced.length} outputs (Copilot, Claude, Codex, OpenClaw)`);
+  console.log(
+    `    \u{1F504} Synced: ${synced.length} outputs (${scope === "user" ? "Copilot agent modes in ~/.copilot/agents" : "Copilot, Claude, Codex, OpenClaw"})`
+  );
   if (skipped.length > 0) {
     console.log(`    \u26A0\uFE0F  Skipped: ${skipped.length} (${skipped.join(", ")})`);
   }
   console.log();
-  console.log(`    \u{1F4A1} Customize: edit .arcane/agents.yaml \u2192 spell agents sync`);
+  console.log(
+    `    \u{1F4A1} Customize: edit ${label}/agents.yaml \u2192 spell agents sync${scope === "user" ? " --user" : ""}`
+  );
   console.log();
   if (hasUnresolvedRoles) {
     console.error(
@@ -2387,9 +2505,10 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   }
 }
 async function runAgentsSync(options, targetDir, assetsDir) {
+  const scope = options.scope ?? "repo";
   let roster;
   try {
-    roster = await loadRoster(targetDir);
+    roster = await loadRoster(targetDir, scope);
   } catch (err) {
     if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
       console.error(err.message);
@@ -2403,11 +2522,11 @@ async function runAgentsSync(options, targetDir, assetsDir) {
   } else {
     console.log("\n  Syncing agents...\n");
   }
-  const { synced, skipped, hasUnresolvedRoles } = await syncAgents(
+  const { synced, skipped, hasUnresolvedRoles } = await performAgentSync(
     targetDir,
     assetsDir,
     roster,
-    options
+    { ...options, scope }
   );
   if (options.dryRun) {
     console.log(`
@@ -2434,10 +2553,10 @@ async function runAgentsSync(options, targetDir, assetsDir) {
     process.exitCode = 1;
   }
 }
-async function runAgentsList(targetDir) {
+async function runAgentsList(targetDir, scope = "repo") {
   let roster;
   try {
-    roster = await loadRoster(targetDir);
+    roster = await loadRoster(targetDir, scope);
   } catch (err) {
     if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
       console.error(err.message);
@@ -2479,9 +2598,9 @@ async function runAgentsList(targetDir) {
 }
 
 // src/modules/push-safety.ts
-import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile7, chmod, access as access3, rm as rm4, readdir as readdir4 } from "fs/promises";
+import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile7, chmod, access as access3, rm as rm4, readdir as readdir5 } from "fs/promises";
 import { constants } from "fs";
-import { join as join5, resolve as resolve2, dirname as dirname2, basename } from "path";
+import { join as join5, resolve as resolve2, dirname as dirname3, basename } from "path";
 
 // src/modules/git.ts
 import { execFile } from "child_process";
@@ -2778,7 +2897,7 @@ async function repositoryRoot(cwd) {
     ]);
     const commonDir = stdout.trim();
     if (commonDir !== "") {
-      const parent = dirname2(commonDir);
+      const parent = dirname3(commonDir);
       if (basename(commonDir) === ".git" && parent !== "") return parent;
     }
   } catch {
@@ -2868,7 +2987,7 @@ async function defaultHooks(cwd) {
     return [];
   }
   try {
-    return (await readdir4(hooksDir)).filter((name) => !name.endsWith(".sample")).sort();
+    return (await readdir5(hooksDir)).filter((name) => !name.endsWith(".sample")).sort();
   } catch {
     return [];
   }
@@ -2902,7 +3021,7 @@ async function removeHook(cwd, hookName) {
   const hooksDir = join5(root, ARCANE_HOOKS_DIR);
   let remaining = [];
   try {
-    remaining = await readdir4(hooksDir);
+    remaining = await readdir5(hooksDir);
   } catch {
     remaining = [];
   }
@@ -3667,7 +3786,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
   console.log(chalk2.hex("#a855f7")(`
   \u2726 Arcane v${packageVersion}
 `));
-  const homeDir = dirname3(storeRoot);
+  const homeDir = dirname4(storeRoot);
   const components = USER_TIER_COMPONENTS.map(
     (name) => componentForScope(getComponent(name), "user")
   );
@@ -3715,7 +3834,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
       fileHashes
     });
   }
-  const fanout = await syncUserTierFanout({ homeDir, storeRoot, spellIds, fallbackDir: assetsDir });
+  const fanout = await syncUserTierFanout({ homeDir, storeRoot, spellIds, fallbackDir: assetsDir, ownedClients: SPELL_FANOUT_CLIENTS });
   const manifest = {
     version: packageVersion,
     // The tier is un-profiled; "full" records the profile its component set
@@ -3829,12 +3948,12 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
 }
 
 // src/commands/update.ts
-import { dirname as dirname4, join as join9 } from "path";
+import { dirname as dirname5, join as join9 } from "path";
 import { readFile as readFile7, writeFile as writeFile9 } from "fs/promises";
 
 // src/modules/hub.ts
 import { confirm as confirm2, select as select3, input as input3 } from "@inquirer/prompts";
-import { readdir as readdir5, writeFile as writeFile8 } from "fs/promises";
+import { readdir as readdir6, writeFile as writeFile8 } from "fs/promises";
 import { join as join8 } from "path";
 var MANIFEST_RETROFITS = [
   {
@@ -3979,7 +4098,7 @@ async function offerRegistryScaffold(targetDir, businessRoot) {
   const businessRootPath = join8(targetDir, businessRoot);
   let ventureDirs;
   try {
-    const entries = await readdir5(businessRootPath, { withFileTypes: true });
+    const entries = await readdir6(businessRootPath, { withFileTypes: true });
     ventureDirs = entries.filter((e) => e.isDirectory() && e.name !== "_template").map((e) => e.name);
   } catch {
     return;
@@ -4275,7 +4394,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   const scope = resolvedScope.scope;
   const spellScope = effectiveSpellScope(manifest);
   const readopted = findReadoptedSpellComponents(manifest.components, scope, spellScope);
-  const homeDir = dirname4(targetDir);
+  const homeDir = dirname5(targetDir);
   if (scope === "repo") {
     console.warn(
       `WARNING: Arcane v${packageVersion} update safety notice: commit your work before updating.`
@@ -4314,6 +4433,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       console.log("Already up to date.");
       if (scope === "user") {
         const fanout = await syncUserTierFanout({
+          ownedClients: SPELL_FANOUT_CLIENTS,
           homeDir,
           storeRoot: targetDir,
           spellIds: spellIdsInStore(manifest.components),
@@ -4526,6 +4646,7 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
   let fanoutRecord;
   if (scope === "user") {
     const fanout = await syncUserTierFanout({
+      ownedClients: SPELL_FANOUT_CLIENTS,
       homeDir,
       storeRoot: targetDir,
       spellIds: spellIdsInStore(updatedComponents),
@@ -4589,11 +4710,11 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
 }
 
 // src/commands/status.ts
-import { dirname as dirname6 } from "path";
+import { dirname as dirname7 } from "path";
 
 // src/modules/version-check.ts
 import { readFile as readFile8, writeFile as writeFile10, mkdir as mkdir6 } from "fs/promises";
-import { dirname as dirname5, join as join10 } from "path";
+import { dirname as dirname6, join as join10 } from "path";
 import { homedir as homedir3 } from "os";
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
@@ -4622,7 +4743,7 @@ async function readCache(cachePath) {
   }
 }
 async function writeCache(cachePath, latest) {
-  await mkdir6(dirname5(cachePath), { recursive: true });
+  await mkdir6(dirname6(cachePath), { recursive: true });
   const entry = { latest, checkedAt: (/* @__PURE__ */ new Date()).toISOString() };
   await writeFile10(cachePath, JSON.stringify(entry, null, 2), "utf-8");
 }
@@ -4763,7 +4884,7 @@ async function runStatus(targetDir, packageVersion, options = {}) {
   console.log("");
   if (scope === "user") {
     console.log(`  Scope: user \u2014 ${targetDir}`);
-    const health = await inspectUserTierFanout(dirname6(targetDir), manifest.fanout);
+    const health = await inspectUserTierFanout(dirname7(targetDir), manifest.fanout);
     console.log(
       `  Client files: ${health.total} (${health.byClient.codex} ${FANOUT_CLIENT_LABELS.codex}, ${health.byClient.claude} ${FANOUT_CLIENT_LABELS.claude})`
     );
@@ -4826,7 +4947,7 @@ async function runStatus(targetDir, packageVersion, options = {}) {
 
 // src/commands/uninstall.ts
 import { rm as rm5 } from "fs/promises";
-import { dirname as dirname7, join as join11 } from "path";
+import { dirname as dirname8, join as join11 } from "path";
 import { confirm as confirm3 } from "@inquirer/prompts";
 async function runUninstall(options, targetDir) {
   let manifest;
@@ -4935,7 +5056,7 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
 \u2713 Uninstalled \u2014 ${removed} files removed.`);
 }
 async function uninstallUserTier(options, storeRoot, manifest) {
-  const homeDir = dirname7(storeRoot);
+  const homeDir = dirname8(storeRoot);
   const storeFiles = manifest.components.flatMap((c) => c.files);
   const recordedCount = Object.keys(manifest.fanout ?? {}).length;
   if (options.dryRun) {
@@ -4981,6 +5102,8 @@ async function uninstallUserTier(options, storeRoot, manifest) {
     }
   }
   await rm5(join11(storeRoot, ".arcane.json"), { force: true });
+  await rm5(join11(storeRoot, "agents"), { recursive: true, force: true });
+  await rm5(join11(storeRoot, "agents.yaml"), { force: true });
   await removeDirectoryIfEmpty(join11(storeRoot, USER_TIER_SPELLS_DIR));
   await removeDirectoryIfEmpty(storeRoot);
   for (const line of describeFanoutOutcomes(fanout.outcomes)) console.log(`  ${line}`);
@@ -4993,8 +5116,8 @@ async function uninstallUserTier(options, storeRoot, manifest) {
 }
 
 // src/commands/doctor.ts
-import { access as access4, readdir as readdir7, readFile as readFile10, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
-import { join as join13, dirname as dirname8 } from "path";
+import { access as access4, readdir as readdir8, readFile as readFile10, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
+import { join as join13, dirname as dirname9 } from "path";
 import { execFile as execFile3 } from "child_process";
 import { promisify as promisify2 } from "util";
 
@@ -5064,7 +5187,7 @@ function evaluateIncidentGate(records) {
 }
 
 // src/modules/denylist-scan.ts
-import { readFile as readFile9, readdir as readdir6 } from "fs/promises";
+import { readFile as readFile9, readdir as readdir7 } from "fs/promises";
 import { join as join12, relative } from "path";
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -5111,7 +5234,7 @@ async function collectScannableFiles(root, repoRoot = root, extensions = DEFAULT
   const collected = [];
   let entries;
   try {
-    entries = await readdir6(root, { withFileTypes: true });
+    entries = await readdir7(root, { withFileTypes: true });
   } catch {
     return collected;
   }
@@ -5333,8 +5456,8 @@ async function checkVSCodeExtension(id, label) {
   ];
   for (const dir of extDirs) {
     try {
-      const { readdir: readdir10 } = await import("fs/promises");
-      const entries = await readdir10(dir);
+      const { readdir: readdir11 } = await import("fs/promises");
+      const entries = await readdir11(dir);
       const prefix = id.toLowerCase() + "-";
       const found = entries.some(
         (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
@@ -5496,7 +5619,7 @@ async function fixSessionContinuity(targetDir, assetsDir) {
       await access4(destPath);
     } catch {
       const srcPath = join13(assetsDir, file);
-      await mkdir7(dirname8(destPath), { recursive: true });
+      await mkdir7(dirname9(destPath), { recursive: true });
       await fsCopyFile(srcPath, destPath);
       created.push(file);
     }
@@ -5789,7 +5912,7 @@ async function checkSpellScope(targetDir, homeDir = resolveHomeDir()) {
   let probed = false;
   const probe = "spell-status.md";
   try {
-    const entries = await readdir7(join13(storeRoot, USER_TIER_SPELLS_DIR));
+    const entries = await readdir8(join13(storeRoot, USER_TIER_SPELLS_DIR));
     const spells = entries.filter((e) => e.startsWith("spell-") && e.endsWith(".md"));
     spellCount = spells.length;
     probed = spells.includes(probe);
@@ -5811,11 +5934,19 @@ async function checkSpellScope(targetDir, homeDir = resolveHomeDir()) {
       message: `this repository is at v${manifest.version} but the user tier it uses is at v${store.version} \u2014 run \`spell update --user\` (and \`spell update\` here) to bring them together.`
     };
   }
+  const repoExpectsAgents = await rosterExists(targetDir);
+  if (repoExpectsAgents && !await rosterExists(storeRoot, "user")) {
+    return {
+      name,
+      passed: false,
+      message: `this repository has an agent roster and takes its client files from the user tier, but ${storeRoot} has no roster of its own \u2014 no agent mode can reach a client here. Run \`spell agents init --user\`, or set spell_scope back to "repo" and run \`spell agents sync\`.`
+    };
+  }
   return {
     name,
     passed: true,
     blocking: false,
-    message: `user \u2014 ${spellCount} spell(s) from ${storeRoot} (v${store.version}), ${probe} present`
+    message: `user \u2014 ${spellCount} spell(s) from ${storeRoot} (v${store.version}), ${probe} present${repoExpectsAgents ? ", agent roster present in the tier" : ""}`
   };
 }
 async function runDoctor(targetDir, options = {}, assetsDir) {
@@ -5892,7 +6023,7 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
 import { readFile as readFile12 } from "fs/promises";
 
 // src/modules/ward.ts
-import { readdir as readdir8, readFile as readFile11 } from "fs/promises";
+import { readdir as readdir9, readFile as readFile11 } from "fs/promises";
 import { join as join14, relative as relative2 } from "path";
 async function scanFileAllRules(absolutePath, displayPath, rules) {
   const findings = [];
@@ -5951,7 +6082,7 @@ async function scanFilenames(root, rules, repoRoot = root) {
   const findings = [];
   let entries;
   try {
-    entries = await readdir8(root, { withFileTypes: true });
+    entries = await readdir9(root, { withFileTypes: true });
   } catch {
     return findings;
   }
@@ -6173,8 +6304,8 @@ import { access as access5 } from "fs/promises";
 import { join as join17 } from "path";
 
 // src/modules/show-report/generate.ts
-import { mkdir as mkdir8, readdir as readdir9, readFile as readFile14, writeFile as writeFile11 } from "fs/promises";
-import { basename as basename3, dirname as dirname9, isAbsolute, join as join16, relative as relative3, resolve as resolve4 } from "path";
+import { mkdir as mkdir8, readdir as readdir10, readFile as readFile14, writeFile as writeFile11 } from "fs/promises";
+import { basename as basename3, dirname as dirname10, isAbsolute, join as join16, relative as relative3, resolve as resolve4 } from "path";
 
 // src/modules/show-report/model.ts
 import { readFile as readFile13 } from "fs/promises";
@@ -6731,7 +6862,7 @@ async function programFromPlan(rootDir, slug, planRelPath) {
     program: {
       slug,
       planRelPath,
-      queueRelPath: toPosix(join16(dirname9(planRelPath), "OPERATOR-QUEUE.md")),
+      queueRelPath: toPosix(join16(dirname10(planRelPath), "OPERATOR-QUEUE.md")),
       ledgerProgramName: programNameFromTitle(frontmatter.title ?? slug)
     }
   };
@@ -6740,7 +6871,7 @@ async function discoverPrograms(rootDir) {
   const plansDir = join16(rootDir, "docs", "plans");
   let entries;
   try {
-    entries = (await readdir9(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
+    entries = (await readdir10(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
   } catch (error) {
     if (error.code === "ENOENT") return { programs: [], skipped: [] };
     throw error;
@@ -6757,7 +6888,7 @@ async function discoverPrograms(rootDir) {
 async function programFromPlanPath(rootDir, planPath) {
   const planAbs = isAbsolute(planPath) ? planPath : resolve4(rootDir, planPath);
   const planRelPath = toPosix(relative3(rootDir, planAbs));
-  return programFromPlan(rootDir, basename3(dirname9(planAbs)), planRelPath);
+  return programFromPlan(rootDir, basename3(dirname10(planAbs)), planRelPath);
 }
 function normalizeLineEndings2(content) {
   return content.replace(/\r\n?/g, "\n");
@@ -6797,7 +6928,7 @@ async function runReportGeneration(options) {
     const generated = await generateReport(options.rootDir, program2, templateHtml);
     const missing = JSON.parse(generated.json).sections.flatMap((section) => section.rows).filter((row) => row.descriptionState === "unwritten").map((row) => row.id);
     if (missing.length > 0) unwritten.push({ slug: program2.slug, ids: missing });
-    const outAbs = options.outDir ? isAbsolute(options.outDir) ? options.outDir : resolve4(options.rootDir, options.outDir) : resolve4(options.rootDir, dirname9(program2.planRelPath));
+    const outAbs = options.outDir ? isAbsolute(options.outDir) ? options.outDir : resolve4(options.rootDir, options.outDir) : resolve4(options.rootDir, dirname10(program2.planRelPath));
     const outRel = toPosix(relative3(options.rootDir, outAbs));
     const outputs = [
       [`${outRel}/show-report.json`, generated.json],
@@ -6883,9 +7014,10 @@ async function runReport(targetDir, options = {}, assetsDir) {
 import { realpathSync } from "fs";
 var require3 = createRequire2(import.meta.url);
 var pkg = require3("../package.json");
-var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join18(dirname10(fileURLToPath(import.meta.url)), "assets");
+var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join18(dirname11(fileURLToPath(import.meta.url)), "assets");
 var program = new Command();
 var USER_FLAG_DESCRIPTION = "Operate on the per-user tier at ~/.arcane \u2014 spells shared by every repository on this machine, fanned out to ~/.agents/skills (Codex, Copilot) and ~/.claude/commands (Claude Code)";
+var USER_TIER_AGENTS_DESCRIPTION = "Operate on the per-user tier at ~/.arcane \u2014 one agent roster shared by every repository on this machine, rendered to ~/.copilot/agents (VS Code agent modes)";
 function targetDirFor(opts) {
   return opts.user ? userTierRoot() : process.cwd();
 }
@@ -6987,39 +7119,44 @@ agentsCommand.command("init").description(
 ).option(
   "--naming <strategy>",
   "Naming strategy: arcanos | generic | random | custom"
-).option("--force", "Reinitialize even if roster already exists").option("--dry-run", "Preview what would be created without writing files").action(
+).option("--force", "Reinitialize even if roster already exists").option("--dry-run", "Preview what would be created without writing files").option("--user", USER_TIER_AGENTS_DESCRIPTION).action(
   async (opts) => {
+    const scope = opts.user ? "user" : "repo";
     await runAgentsInit(
       {
         profile: opts.profile,
         naming: opts.naming,
         force: opts.force,
-        dryRun: opts.dryRun
+        dryRun: opts.dryRun,
+        scope
       },
-      process.cwd(),
+      agentsTargetDir(scope, process.cwd()),
       ASSETS_DIR
     );
   }
 );
 agentsCommand.command("sync").description(
   "Regenerate all client instruction files from canonical agent definitions"
-).option("--dry-run", "Preview what would be generated without writing files").option("--no-openclaw", "Skip OpenClaw workspace output").option("--no-copilot", "Skip Copilot output").option("--no-claude", "Skip Claude output").option("--no-codex", "Skip Codex output").action(
+).option("--dry-run", "Preview what would be generated without writing files").option("--no-openclaw", "Skip OpenClaw workspace output").option("--no-copilot", "Skip Copilot output").option("--no-claude", "Skip Claude output").option("--no-codex", "Skip Codex output").option("--user", USER_TIER_AGENTS_DESCRIPTION).action(
   async (opts) => {
+    const scope = opts.user ? "user" : "repo";
     await runAgentsSync(
       {
         dryRun: opts.dryRun,
         openclaw: opts.openclaw,
         copilot: opts.copilot,
         claude: opts.claude,
-        codex: opts.codex
+        codex: opts.codex,
+        scope
       },
-      process.cwd(),
+      agentsTargetDir(scope, process.cwd()),
       ASSETS_DIR
     );
   }
 );
-agentsCommand.command("list").description("Show the current agent roster with assigned names and roles").action(async () => {
-  await runAgentsList(process.cwd());
+agentsCommand.command("list").description("Show the current agent roster with assigned names and roles").option("--user", USER_TIER_AGENTS_DESCRIPTION).action(async (opts) => {
+  const scope = opts.user ? "user" : "repo";
+  await runAgentsList(agentsTargetDir(scope, process.cwd()), scope);
 });
 if (realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
   await program.parseAsync(process.argv);