arcane-cli 1.1.1 → 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
@@ -20,6 +20,7 @@ import {
   readdir,
   readFile,
   rm,
+  rmdir,
   writeFile
 } from "fs/promises";
 import { createHash } from "crypto";
@@ -89,6 +90,20 @@ async function removeWithin(targetDir, relativePath) {
   validateTargetPath(targetDir, relativePath);
   await rm(path.resolve(targetDir, relativePath), { force: true });
 }
+async function removeEmptyAncestors(targetDir, relativePath) {
+  validateTargetPath(targetDir, relativePath);
+  const base = path.resolve(targetDir);
+  let dir = path.dirname(path.resolve(targetDir, relativePath));
+  while (dir !== base && dir.startsWith(base + path.sep)) {
+    try {
+      if ((await readdir(dir)).length > 0) return;
+      await rmdir(dir);
+    } catch {
+      return;
+    }
+    dir = path.dirname(dir);
+  }
+}
 async function copyDirectory(srcDir, targetDir, relativeDir, opts = {}) {
   validateTargetPath(targetDir, relativeDir);
   const copiedFiles = [];
@@ -201,6 +216,9 @@ function validateTrackingFields(manifest, filePath) {
   if (manifest.scope !== void 0 && !VALID_INSTALL_SCOPES.includes(manifest.scope)) {
     throw new ManifestInvalidFieldError(filePath, "scope", manifest.scope);
   }
+  if (manifest.spell_scope !== void 0 && !VALID_INSTALL_SCOPES.includes(manifest.spell_scope)) {
+    throw new ManifestInvalidFieldError(filePath, "spell_scope", manifest.spell_scope);
+  }
   if (manifest.fanout !== void 0 && !isValidFanoutRecord(manifest.fanout)) {
     throw new ManifestInvalidFieldError(filePath, "fanout", manifest.fanout);
   }
@@ -866,7 +884,7 @@ function listProfiles() {
 }
 
 // src/modules/user-tier.ts
-import { lstat, mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rm as rm2, rmdir, writeFile as writeFile3 } from "fs/promises";
+import { lstat, mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rm as rm2, rmdir as rmdir2, writeFile as writeFile3 } from "fs/promises";
 import { homedir } from "os";
 import { dirname, join, resolve } from "path";
 
@@ -999,6 +1017,14 @@ function componentForScope(component, scope) {
   }
   return { name: component.name, description: component.description, files, sourceOverrides };
 }
+function componentForSpellScope(component, spellScope) {
+  if (spellScope === "repo") return component;
+  if (!SPELL_COMPONENT_NAMES.includes(component.name)) return component;
+  return { ...component, files: [] };
+}
+function effectiveSpellScope(manifest) {
+  return manifest.spell_scope ?? "repo";
+}
 function spellIdsInStore(components) {
   const ids = /* @__PURE__ */ new Set();
   for (const component of components) {
@@ -1009,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) {
@@ -1076,20 +1109,22 @@ function perSpellDirectory(homeDir, relativePath) {
 async function removeDirectoryIfEmpty(dir) {
   try {
     const entries = await readdir2(dir);
-    if (entries.length === 0) await rmdir(dir);
+    if (entries.length === 0) await rmdir2(dir);
   } catch {
   }
 }
 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];
@@ -1132,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);
@@ -1172,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);
@@ -1183,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) {
@@ -1222,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: []
   };
@@ -1399,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
@@ -1808,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";
   }
@@ -1833,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";
 
@@ -2065,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) {
@@ -2091,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()
@@ -2156,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()}
@@ -2207,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.'
     );
@@ -2306,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`);
@@ -2327,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) {
@@ -2338,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(
@@ -2361,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);
@@ -2377,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(`
@@ -2408,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);
@@ -2453,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";
@@ -2752,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 {
@@ -2842,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 [];
   }
@@ -2876,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 = [];
   }
@@ -3274,16 +3419,35 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     profile = await select2({
       message: "Select an installation profile:\n",
       choices: profiles.map((p) => {
-        const profileComponents = getProfile(p.id);
+        const profileComponents2 = getProfile(p.id);
         return {
           value: p.id,
           name: `${PROFILE_ICONS[p.id] ?? "\u{1F4CB}"}  ${p.displayName} \u2014 ${p.description}`,
-          description: buildProfileDescription(profileComponents, p.id)
+          description: buildProfileDescription(profileComponents2, p.id)
         };
       })
     });
   }
-  const components = getProfile(profile);
+  const profileComponents = getProfile(profile);
+  let spell_scope;
+  if (!options.profile && !options.dryRun) {
+    let storeVersion;
+    try {
+      storeVersion = (await readManifest(userTierRoot())).version;
+    } catch {
+    }
+    if (storeVersion !== void 0) {
+      console.log();
+      const useTier = await confirm({
+        message: `This machine has an Arcane user tier (v${storeVersion}). Use it for this repository's spells instead of installing copies here?`,
+        default: false
+      });
+      spell_scope = useTier ? "user" : "repo";
+    }
+  }
+  const components = profileComponents.map(
+    (component) => componentForSpellScope(component, spell_scope ?? "repo")
+  );
   const groups = categorizeComponents(components);
   console.log();
   printSection(`\u{1F4E6} Profile: ${profile}`);
@@ -3470,6 +3634,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     profile,
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     components: installedComponents,
+    ...spell_scope ? { spell_scope } : {},
     ...role ? { role } : {},
     ...tracking_mode ? { tracking_mode, external_provider } : {},
     ...subject_root !== void 0 ? { subject_root } : {},
@@ -3621,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")
   );
@@ -3669,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
@@ -3783,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 = [
   {
@@ -3933,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;
@@ -4155,26 +4320,57 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
     return "reported";
   }
   await removeWithin(targetDir, file);
+  await removeEmptyAncestors(targetDir, file);
   console.log(`  Pruned orphaned file: ${file}`);
   return "pruned";
 }
-async function findMissingTrackedFiles(targetDir, components, scope = "repo") {
+function findReadoptedSpellComponents(components, scope = "repo", spellScope = "repo") {
+  if (scope !== "repo" || spellScope !== "repo") return /* @__PURE__ */ new Set();
+  return new Set(
+    components.filter((c) => SPELL_COMPONENT_NAMES.includes(c.name) && c.files.length === 0).map((c) => c.name)
+  );
+}
+async function findMissingTrackedFiles(targetDir, components, scope = "repo", spellScope = "repo", readopted = /* @__PURE__ */ new Set()) {
   const missing = [];
   for (const installed of components) {
     let component;
     try {
-      component = componentForScope(getComponent(installed.name), scope);
+      component = componentForSpellScope(
+        componentForScope(getComponent(installed.name), scope),
+        scope === "repo" ? spellScope : "repo"
+      );
     } catch {
       continue;
     }
     if (component.initOnly || component.skipExisting) continue;
-    for (const file of installed.files) {
+    const candidates = readopted.has(installed.name) ? component.files : installed.files;
+    for (const file of candidates) {
       if (!component.files.includes(file)) continue;
       if (!await fileExists(join9(targetDir, file))) missing.push(file);
     }
   }
   return missing;
 }
+function findUnmanagedTrackedFiles(components, scope = "repo", spellScope = "repo") {
+  const unmanaged = [];
+  for (const installed of components) {
+    let component;
+    try {
+      component = componentForSpellScope(
+        componentForScope(getComponent(installed.name), scope),
+        scope === "repo" ? spellScope : "repo"
+      );
+    } catch {
+      unmanaged.push(...installed.files);
+      continue;
+    }
+    const shipped = new Set(component.files);
+    for (const file of installed.files) {
+      if (!shipped.has(file)) unmanaged.push(file);
+    }
+  }
+  return unmanaged;
+}
 async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   let manifest;
   try {
@@ -4196,7 +4392,9 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     return;
   }
   const scope = resolvedScope.scope;
-  const homeDir = dirname4(targetDir);
+  const spellScope = effectiveSpellScope(manifest);
+  const readopted = findReadoptedSpellComponents(manifest.components, scope, spellScope);
+  const homeDir = dirname5(targetDir);
   if (scope === "repo") {
     console.warn(
       `WARNING: Arcane v${packageVersion} update safety notice: commit your work before updating.`
@@ -4229,11 +4427,13 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   }
   let sameVersionRestore = false;
   if (manifest.version === packageVersion && manifest.components.length > 0) {
-    const missing = await findMissingTrackedFiles(targetDir, manifest.components, scope);
-    if (missing.length === 0) {
+    const missing = await findMissingTrackedFiles(targetDir, manifest.components, scope, spellScope, readopted);
+    const unmanaged = findUnmanagedTrackedFiles(manifest.components, scope, spellScope);
+    if (missing.length === 0 && unmanaged.length === 0) {
       console.log("Already up to date.");
       if (scope === "user") {
         const fanout = await syncUserTierFanout({
+          ownedClients: SPELL_FANOUT_CLIENTS,
           homeDir,
           storeRoot: targetDir,
           spellIds: spellIdsInStore(manifest.components),
@@ -4249,9 +4449,16 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       return;
     }
     sameVersionRestore = true;
-    console.log(
-      `${options.dryRun ? "[dry-run] " : ""}Already at v${packageVersion}, but ${missing.length} tracked file${missing.length === 1 ? " is" : "s are"} missing \u2014 restoring.`
-    );
+    const prefix = options.dryRun ? "[dry-run] " : "";
+    if (missing.length > 0) {
+      console.log(
+        `${prefix}Already at v${packageVersion}, but ${missing.length} tracked file${missing.length === 1 ? " is" : "s are"} missing \u2014 restoring.`
+      );
+    } else {
+      console.log(
+        `${prefix}Already at v${packageVersion}, but ${unmanaged.length} tracked file${unmanaged.length === 1 ? " is" : "s are"} no longer managed here \u2014 reviewing.`
+      );
+    }
   }
   if (manifest.components.length === 0) {
     console.log("No components installed. Nothing to update.");
@@ -4266,7 +4473,10 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   for (const installed of componentsToUpdate) {
     let component;
     try {
-      component = componentForScope(getComponent(installed.name), scope);
+      component = componentForSpellScope(
+        componentForScope(getComponent(installed.name), scope),
+        scope === "repo" ? spellScope : "repo"
+      );
     } catch (err) {
       if (err instanceof ComponentNotFoundError) {
         console.log(`  ! ${installed.name} not in registry \u2014 skipping.`);
@@ -4301,7 +4511,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
         continue;
       }
       if (sameVersionRestore) {
-        const tracked = installed.files.includes(file);
+        const tracked = installed.files.includes(file) || readopted.has(installed.name);
         const restorable = tracked && !targetExists && !component.skipExisting;
         if (!restorable) {
           if (tracked) {
@@ -4378,13 +4588,24 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     }
     for (const file of installed.files) {
       if (updatedFiles.includes(file)) continue;
+      const recordedHash = installed.fileHashes?.[file];
       const status = await resolveOrphan(
         targetDir,
         file,
-        installed.fileHashes?.[file],
+        recordedHash,
         Boolean(options.prune) && !options.dryRun
       );
       orphanReport.push({ file, status });
+      if (status === "reported") {
+        try {
+          validateTargetPath(targetDir, file);
+          if (await fileExists(join9(targetDir, file))) {
+            updatedFiles.push(file);
+            if (recordedHash !== void 0) fileHashes[file] = recordedHash;
+          }
+        } catch {
+        }
+      }
     }
     updatedComponents.push({
       ...installed,
@@ -4404,6 +4625,11 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
       const marker = status === "pruned" ? "pruned" : options.prune ? "kept (see reason above)" : "not removed";
       console.log(`    ${file} \u2014 ${marker}`);
     }
+    if (scope === "repo" && spellScope === "user") {
+      console.log(
+        '  This repository takes its spells from the user tier (spell_scope: "user"), so the files above are no longer managed here \u2014 every client reads ~/.arcane instead.'
+      );
+    }
     if (!options.prune) {
       console.log("  Run `spell update --prune` to remove the ones that are safe to delete.");
     }
@@ -4420,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),
@@ -4483,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);
@@ -4516,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");
 }
@@ -4657,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})`
     );
@@ -4670,12 +4897,18 @@ async function runStatus(targetDir, packageVersion, options = {}) {
       );
     }
   } else {
-    console.log("  Scope: repo");
+    const spellScope = effectiveSpellScope(manifest);
+    console.log(spellScope === "user" ? "  Scope: repo (spells: user tier)" : "  Scope: repo");
+    const store = userTierRoot();
     try {
-      const store = userTierRoot();
       const userManifest = await readManifest(store);
       console.log(`  User tier: v${userManifest.version} at ${store} (spell status --user)`);
     } catch {
+      if (spellScope === "user") {
+        console.log(
+          `  ! User tier: not installed at ${store} \u2014 this repository expects it for every spell. Run \`spell init --user\` (\`spell doctor\` explains).`
+        );
+      }
     }
   }
   console.log("");
@@ -4714,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;
@@ -4823,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) {
@@ -4869,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}`);
@@ -4881,8 +5116,8 @@ async function uninstallUserTier(options, storeRoot, manifest) {
 }
 
 // src/commands/doctor.ts
-import { access as access4, 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";
 
@@ -4952,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, "\\$&");
@@ -4999,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;
   }
@@ -5221,8 +5456,8 @@ async function checkVSCodeExtension(id, label) {
   ];
   for (const dir of extDirs) {
     try {
-      const { readdir: readdir9 } = await import("fs/promises");
-      const entries = await readdir9(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)
@@ -5384,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);
     }
@@ -5646,6 +5881,74 @@ async function checkPlatformBranchPolicy(targetDir) {
     message: "remote is neither GitHub nor Azure DevOps \u2014 platform policy verification not available for this provider"
   };
 }
+async function checkSpellScope(targetDir, homeDir = resolveHomeDir()) {
+  const name = "Spell scope (ARC-045)";
+  let manifest;
+  try {
+    manifest = await readManifest(targetDir);
+  } catch {
+    return { name, passed: true, blocking: false, message: "no .arcane.json \u2014 nothing to check" };
+  }
+  if (effectiveSpellScope(manifest) === "repo") {
+    return {
+      name,
+      passed: true,
+      blocking: false,
+      message: "repo \u2014 this repository carries its own spells (the default)"
+    };
+  }
+  const storeRoot = userTierRoot(homeDir);
+  let store;
+  try {
+    store = await readManifest(storeRoot);
+  } catch (err) {
+    return {
+      name,
+      passed: false,
+      message: `this repository takes its spells from the user tier (spell_scope: "user"), but ${storeRoot} ${err instanceof ManifestNotFoundError ? "is not installed" : `could not be read (${err instanceof Error ? err.message : String(err)})`} \u2014 no client can reach a spell here. Run \`spell init --user\`, or set spell_scope back to "repo" and run \`spell update\`.`
+    };
+  }
+  let spellCount = 0;
+  let probed = false;
+  const probe = "spell-status.md";
+  try {
+    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);
+  } catch {
+  }
+  if (spellCount === 0 || !probed) {
+    return {
+      name,
+      passed: false,
+      message: `the user tier at ${storeRoot} holds ${spellCount} spell(s)${spellCount > 0 && !probed ? ` and not ${probe}` : ""} \u2014 this repository expects it to supply every spell. Run \`spell update --user\`.`
+    };
+  }
+  const majorMinor = (v) => v.split(".").slice(0, 2).join(".");
+  if (typeof manifest.version === "string" && majorMinor(store.version) !== majorMinor(manifest.version)) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      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${repoExpectsAgents ? ", agent roster present in the tier" : ""}`
+  };
+}
 async function runDoctor(targetDir, options = {}, assetsDir) {
   console.log("\nspell doctor \u2014 checking your Arcane environment\n");
   if (options.leaks) {
@@ -5671,7 +5974,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkPlatformBranchPolicy(targetDir),
     checkDelegations(targetDir),
     checkMcpConfig(targetDir),
-    checkUserTier(resolveHomeDir(), options.packageVersion)
+    checkUserTier(resolveHomeDir(), options.packageVersion),
+    checkSpellScope(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);
@@ -5719,7 +6023,7 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
 import { readFile as readFile12 } from "fs/promises";
 
 // src/modules/ward.ts
-import { readdir as readdir7, 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 = [];
@@ -5778,7 +6082,7 @@ async function scanFilenames(root, rules, repoRoot = root) {
   const findings = [];
   let entries;
   try {
-    entries = await readdir7(root, { withFileTypes: true });
+    entries = await readdir9(root, { withFileTypes: true });
   } catch {
     return findings;
   }
@@ -6000,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 readdir8, 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";
@@ -6558,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)
     }
   };
@@ -6567,7 +6871,7 @@ async function discoverPrograms(rootDir) {
   const plansDir = join16(rootDir, "docs", "plans");
   let entries;
   try {
-    entries = (await readdir8(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;
@@ -6584,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");
@@ -6624,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],
@@ -6710,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();
 }
@@ -6814,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);