arcane-cli 1.3.1 → 1.5.0

package/README.md

@@ -237,12 +237,16 @@ Codex, VS Code Copilot and Claude Code each discover the user tier from their ow
 
 ```bash
 spell agents init --user   # ~/.arcane/agents.yaml plus one definition file per role
-spell agents sync --user   # renders ~/.copilot/agents/<name>.agent.md — VS Code agent modes
+spell agents sync --user   # renders ~/.claude/agents/<name>.md — read by VS Code and Claude Code
 spell agents list --user   # the roster the tier holds
 ```
 
 Unlike spells, agent files are never delivered by `spell init` or `spell update`: they are rendered from your roster, whose naming strategy decides each file's name and contents, so an upgrade leaves them alone by design (ARC-047). And unlike skills, VS Code does **not** collapse two agents that share a name — a repository carrying its own `.github/agents` files adds a second entry beside the tier's rather than replacing it, so opting the repository out is what produces one set.
 
+`~/.claude/agents` is read by VS Code **and** by Claude Code, so one file gives you the persona in both. Each description ends by saying the persona is for when you ask for it by name: Claude Code reads that field to decide whether to route work to a subagent unprompted, and twelve personas installed once per machine would otherwise start answering in projects that have nothing to do with Arcane. Change that sentence in `renderUserTierAgent` if you want the opposite.
+
+A repository that opts in and has no roster of its own now takes the machine-wide one for its roster tables, rather than refusing.
+
 **Then let a repository stop carrying its own copies.** `spell init` offers this when the machine already has a tier, and an existing repository opts in by setting one field:
 
 ```jsonc
@@ -259,6 +263,16 @@ spell doctor          # fails loudly if the user tier it now depends on is missi
 
 This is what removes the duplication: with the repository's own copies gone, one workspace holding ten Arcane projects shows one set of `/spell-*` entries, not ten. It is also what makes the answer predictable — while both tiers own a command name, which copy a client runs is not something you can read off the docs.
 
+**Tired of answering that question in every new repository?** Tell the machine once:
+
+```bash
+spell update --user --default-scope user   # or repo, to go back
+```
+
+That pre-selects the answer `spell init` offers in **new** repositories on this machine. It rewrites nothing that already exists, and the question is still asked, so a repository you want to keep self-contained is one keystroke away. An absent `spell_scope` means `repo` permanently, on every machine ([ARC-048](DECISIONS.md#arc-048--an-absent-spell_scope-means-repo-permanently-new-repositories-may-be-pre-selected)) — a preference decides what you are *offered*, never what an existing repository *means*.
+
+If a repository that opted in ever lands on a machine with no tier, `spell update` there now says so, names the store path, and gives you both ways out.
+
 **Shared, team and cloud repositories should stay `repo`.** The field is committed and inherited by every clone, so opting in tells *everyone* who clones that repository to get their spells from a machine-wide install they may not have. Reverse it by setting the field back and running `spell update`, which reinstalls every spell file.
 
 ---

package/dist/assets/.arcane/governance/portable-bootstrap.md

@@ -52,7 +52,7 @@ Paste this entire file into any AI client (Claude web, ChatGPT, etc.) to give it
 ## Where Documents Live
 
 - **Framework-managed standards:** `.arcane/governance/`. Spells reference this single installed layer; **do not create a duplicate root `governance/` tree. Enforcement: explicitly advisory prose (ARC-023) — no check scans a repo for a duplicate root-level `governance/` directory.**
-- **Framework-managed spells:** `.arcane/spells/<id>.md` is each spell's one authored source (ARC-045). The files each AI client discovers — `.github/prompts/<id>.prompt.md` for Copilot, `.claude/commands/<id>.md` for Claude Code, `.agents/skills/<id>/SKILL.md` for Codex — are thin generated shims that point back at it; edit the canonical file, never a shim. **Enforcement: executable check (ARC-023) — `npm run check:self-host-parity` re-renders every shim from its canonical file and fails on any difference; `spell update` keeps a hand-edited shim untouched and names it rather than merging into it.** The same canonical spells can also be installed once per machine — `spell init --user` puts them at `~/.arcane/spells/<id>.md` with one Codex/Copilot skill under `~/.agents/skills/` and one Claude Code command under `~/.claude/commands/` per spell (ARC-045 decision 3); governance never moves up a tier. The agent roster follows the same shape (ARC-047): `spell agents init|sync --user` keeps `agents.yaml` and the role definitions at `~/.arcane` and renders one `~/.copilot/agents/<name>.agent.md` per agent, which is where VS Code looks for machine-wide agent modes. Agent files are never installed by `spell init`/`spell update` at either tier -- they are rendered from the roster, whose naming strategy picks each file's name, which is why an upgrade never touches them. A repository may then opt out of carrying its own copies entirely with `spell_scope: "user"` in `.arcane.json` (ARC-045 decision 4) — `spell update --prune` removes what it no longer manages, keeping anything you edited, and `spell doctor` fails loudly if the tier it now depends on is missing.
+- **Framework-managed spells:** `.arcane/spells/<id>.md` is each spell's one authored source (ARC-045). The files each AI client discovers — `.github/prompts/<id>.prompt.md` for Copilot, `.claude/commands/<id>.md` for Claude Code, `.agents/skills/<id>/SKILL.md` for Codex — are thin generated shims that point back at it; edit the canonical file, never a shim. **Enforcement: executable check (ARC-023) — `npm run check:self-host-parity` re-renders every shim from its canonical file and fails on any difference; `spell update` keeps a hand-edited shim untouched and names it rather than merging into it.** The same canonical spells can also be installed once per machine — `spell init --user` puts them at `~/.arcane/spells/<id>.md` with one Codex/Copilot skill under `~/.agents/skills/` and one Claude Code command under `~/.claude/commands/` per spell (ARC-045 decision 3); governance never moves up a tier. The agent roster follows the same shape (ARC-047): `spell agents init|sync --user` keeps `agents.yaml` and the role definitions at `~/.arcane` and renders one `~/.claude/agents/<name>.md` per agent -- the one home location read by both VS Code and Claude Code, so a persona shows up once in each rather than twice in one (ARC-047 decisions 3 and 11). Agent files are never installed by `spell init`/`spell update` at either tier -- they are rendered from the roster, whose naming strategy picks each file's name, which is why an upgrade never touches them. An absent `spell_scope` means `repo` permanently (ARC-048); a machine may set `default_spell_scope` in its own store to pre-select the answer `spell init` offers in NEW repositories, which never rewrites an existing one and never suppresses the question. A repository may then opt out of carrying its own copies entirely with `spell_scope: "user"` in `.arcane.json` (ARC-045 decision 4) — `spell update --prune` removes what it no longer manages, keeping anything you edited, and `spell doctor` fails loudly if the tier it now depends on is missing.
 - **Project-owned orientation and continuity:** `README.md`, `project.md`, `TODO.md`, `DECISIONS.md`, `ai-context/`, and `journal/`. Arcane creates missing files once and preserves existing content.
 - **Project/domain documents:** use explicit descriptive paths such as `docs/`, `security/`, `infrastructure/`, or a configured business root. These add project context alongside framework standards.
 - **Overrides survive `arcane update`:** editing a managed `.arcane/governance/` standard no longer risks silent loss. Additive project documents were always safe; a hand-edit to a shipped standard now is too. **Enforcement: executable check (ARC-038, shipped BC-31)** — `spell update` compares each file's on-disk content against its recorded hash at install time: unchanged, it refreshes normally; edited, it fetches the exact previously-installed published version as a three-way merge base against your edit and the new vendor content, auto-merging non-overlapping changes and leaving standard conflict markers only on genuine collisions. If the prior published version can't be fetched, your edit is left untouched with a warning rather than replaced.

package/dist/index.js

@@ -1025,6 +1025,9 @@ function componentForSpellScope(component, spellScope) {
 function effectiveSpellScope(manifest) {
   return manifest.spell_scope ?? "repo";
 }
+function preferredSpellScope(manifest) {
+  return manifest?.default_spell_scope === "user" ? "user" : "repo";
+}
 function spellIdsInStore(components) {
   const ids = /* @__PURE__ */ new Set();
   for (const component of components) {
@@ -1035,25 +1038,27 @@ function spellIdsInStore(components) {
   }
   return [...ids].sort();
 }
-var USER_AGENT_FANOUT_DIR = ".copilot/agents";
+var USER_AGENT_FANOUT_DIR = ".claude/agents";
+var LEGACY_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`;
+  return `${USER_AGENT_FANOUT_DIR}/${slug}.md`;
 }
 var FANOUT_CLIENT_LABELS = {
   codex: "Codex/Copilot skills",
   claude: "Claude Code commands",
-  "copilot-agents": "Copilot agent modes"
+  "copilot-agents": "agent personas (VS Code + Claude Code)"
 };
 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";
+  if (normalized.startsWith(`${LEGACY_USER_AGENT_FANOUT_DIR}/`)) return "copilot-agents";
   return void 0;
 }
 async function readSpellSource(storeRoot, id, fallbackDir) {
@@ -2050,6 +2055,16 @@ ${allowed}
 ${denied}
 `;
 }
+function renderUserTierAgent(def, name) {
+  const collapsed = def.persona.description.replace(/\s+/g, " ").trim();
+  const firstSentence = /^.*?[.!?](?=\s|$)/.exec(collapsed)?.[0] ?? def.role;
+  const repoFile = renderCopilotAgent(def, name);
+  const body = repoFile.slice(repoFile.indexOf("---", 3) + 3);
+  return `---
+name: ${name}
+description: ${def.role}. ${firstSentence} Use only when explicitly asked for ${name} by name; do not delegate to this persona automatically.
+---${body}`;
+}
 function renderCopilotAgent(def, name) {
   const firstLine = def.persona.description.split("\n")[0]?.trim() ?? def.role;
   const rules = def.persona.behavioral_rules.map((r) => `- ${r}`).join("\n");
@@ -2130,7 +2145,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
   const repoOptedOut = !userTier && options.spellScope === "user";
   const userAgentFiles = [];
   const unmanagedAgentFiles = [];
-  const projectDefs = projectAgentsDir(targetDir, userTier ? "user" : "repo");
+  const projectDefs = options.definitionsDir ?? projectAgentsDir(targetDir, userTier ? "user" : "repo");
   const bundledDefs = join3(assetsDir, "agents");
   const resolved = [];
   for (const entry of roster.roster) {
@@ -2224,7 +2239,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       if (!def.clients.copilot?.agent_file) continue;
       const slug = displayName.toLowerCase().replace(/\s+/g, "-");
       const fileName = `${slug}.agent.md`;
-      const content = renderCopilotAgent(def, displayName);
+      const content = userTier ? renderUserTierAgent(def, displayName) : renderCopilotAgent(def, displayName);
       if (userTier) {
         const relativePath = userAgentFanoutPath(slug);
         userAgentFiles.push({ relativePath, client: "copilot-agents", content });
@@ -2301,6 +2316,24 @@ async function requireUserStore(storeRoot) {
     throw new Error("unreachable");
   }
 }
+async function resolveRoster(targetDir, scope, homeDir) {
+  try {
+    return {
+      roster: await loadRoster(targetDir, scope),
+      definitionsDir: projectAgentsDir(targetDir, scope),
+      fromUserTier: scope === "user"
+    };
+  } catch (err) {
+    const missing = err instanceof AgentRosterNotFoundError;
+    if (!missing || scope !== "repo" || await repoSpellScope(targetDir) !== "user") throw err;
+    const storeRoot = homeDir === void 0 ? userTierRoot() : userTierRoot(homeDir);
+    return {
+      roster: await loadRoster(storeRoot, "user"),
+      definitionsDir: projectAgentsDir(storeRoot, "user"),
+      fromUserTier: true
+    };
+  }
+}
 async function repoSpellScope(targetDir) {
   try {
     return effectiveSpellScope(await readManifest(targetDir));
@@ -2487,7 +2520,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   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 (${scope === "user" ? "Copilot agent modes in ~/.copilot/agents" : "Copilot, Claude, Codex, OpenClaw"})`
+    `    \u{1F504} Synced: ${synced.length} outputs (${scope === "user" ? "agent personas in ~/.claude/agents" : "Copilot, Claude, Codex, OpenClaw"})`
   );
   if (skipped.length > 0) {
     console.log(`    \u26A0\uFE0F  Skipped: ${skipped.length} (${skipped.join(", ")})`);
@@ -2507,8 +2540,10 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
 async function runAgentsSync(options, targetDir, assetsDir) {
   const scope = options.scope ?? "repo";
   let roster;
+  let definitionsDir;
+  let fromUserTier = false;
   try {
-    roster = await loadRoster(targetDir, scope);
+    ({ roster, definitionsDir, fromUserTier } = await resolveRoster(targetDir, scope));
   } catch (err) {
     if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
       console.error(err.message);
@@ -2522,11 +2557,16 @@ async function runAgentsSync(options, targetDir, assetsDir) {
   } else {
     console.log("\n  Syncing agents...\n");
   }
+  if (fromUserTier && scope === "repo") {
+    console.log(
+      "  This repository has no roster of its own and takes its spells from the user tier,\n  so its roster tables are built from ~/.arcane/agents.yaml.\n"
+    );
+  }
   const { synced, skipped, hasUnresolvedRoles } = await performAgentSync(
     targetDir,
     assetsDir,
     roster,
-    { ...options, scope }
+    { ...options, scope, ...definitionsDir === void 0 ? {} : { definitionsDir } }
   );
   if (options.dryRun) {
     console.log(`
@@ -3432,15 +3472,18 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   let spell_scope;
   if (!options.profile && !options.dryRun) {
     let storeVersion;
+    let preferred = "repo";
     try {
-      storeVersion = (await readManifest(userTierRoot())).version;
+      const store = await readManifest(userTierRoot());
+      storeVersion = store.version;
+      preferred = preferredSpellScope(store);
     } 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
+        default: preferred === "user"
       });
       spell_scope = useTier ? "user" : "repo";
     }
@@ -4282,6 +4325,31 @@ async function fetchPublishedFile(version, relativeAssetPath) {
 }
 
 // src/commands/update.ts
+async function missingTierWarning(scope, spellScope, homeDir) {
+  if (scope !== "repo" || spellScope !== "user") return [];
+  const storeRoot = homeDir === void 0 ? userTierRoot() : userTierRoot(homeDir);
+  try {
+    await readManifest(storeRoot);
+    return [];
+  } catch {
+    return [
+      "",
+      `  ! This repository takes its spells from the user tier, and ${storeRoot} is not installed.`,
+      "    No client can reach a spell here: the routing block in CLAUDE.md and AGENTS.md still",
+      "    names spells that resolve to nothing, so an agent improvises the workflow instead of",
+      "    failing. Fix it with one of:",
+      "",
+      "      spell init --user                       # install the tier on this machine",
+      '      # or set "spell_scope": "repo" in .arcane.json and re-run `spell update`',
+      ""
+    ];
+  }
+}
+function defaultScopePatch(options, manifest) {
+  if (options.defaultScope === void 0) return void 0;
+  if (manifest.default_spell_scope === options.defaultScope) return void 0;
+  return { default_spell_scope: options.defaultScope };
+}
 function migrateLegacyComponents(components) {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
@@ -4395,6 +4463,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   const spellScope = effectiveSpellScope(manifest);
   const readopted = findReadoptedSpellComponents(manifest.components, scope, spellScope);
   const homeDir = dirname5(targetDir);
+  for (const line of await missingTierWarning(scope, spellScope)) console.log(line);
   if (scope === "repo") {
     console.warn(
       `WARNING: Arcane v${packageVersion} update safety notice: commit your work before updating.`
@@ -4442,8 +4511,9 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
           fallbackDir: assetsDir
         });
         for (const line of describeFanoutOutcomes(fanout.outcomes, options.dryRun)) console.log(`  ${line}`);
-        if (!options.dryRun && JSON.stringify(fanout.record) !== JSON.stringify(manifest.fanout ?? {})) {
-          await writeManifest(targetDir, { ...manifest, fanout: fanout.record });
+        const scopePatch = defaultScopePatch(options, manifest);
+        if (!options.dryRun && (JSON.stringify(fanout.record) !== JSON.stringify(manifest.fanout ?? {}) || scopePatch !== void 0)) {
+          await writeManifest(targetDir, { ...manifest, ...scopePatch, fanout: fanout.record });
         }
       }
       return;
@@ -4689,7 +4759,8 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
     version: packageVersion,
     components: updatedComponents,
     ...retrofitPatch,
-    ...fanoutRecord !== void 0 ? { fanout: fanoutRecord } : {}
+    ...fanoutRecord !== void 0 ? { fanout: fanoutRecord } : {},
+    ...defaultScopePatch(options, manifest)
   };
   await writeManifest(targetDir, updated);
   console.log(
@@ -7069,9 +7140,31 @@ program.command("add <component>").description("Add a component to an existing A
 program.command("update").description("Update installed components to the current package version").option("--dry-run", "Preview what would be updated without making changes").option(
   "--prune",
   "Also delete orphaned managed files (tracked before this update, no longer part of any current component). Hash-checked: an edited file is reported, never silently deleted"
-).option("--user", USER_FLAG_DESCRIPTION).action(async (opts) => {
+).option("--user", USER_FLAG_DESCRIPTION).option(
+  "--default-scope <scope>",
+  "With --user: remember repo | user as the answer `spell init` pre-selects for NEW repositories on this machine. Never rewrites an existing repository, and the question is still asked"
+).action(async (opts) => {
+  if (opts.defaultScope !== void 0) {
+    if (!opts.user) {
+      console.error(
+        "\n  \u2717 --default-scope applies to the user tier only. It records a preference in\n    ~/.arcane, not in a repository. Re-run it as:\n\n      spell update --user --default-scope " + opts.defaultScope + "\n"
+      );
+      process.exit(1);
+    }
+    if (opts.defaultScope !== "repo" && opts.defaultScope !== "user") {
+      console.error(
+        "\n  \u2717 --default-scope takes repo or user, not: " + opts.defaultScope + "\n"
+      );
+      process.exit(1);
+    }
+  }
   await runUpdate(
-    { dryRun: opts.dryRun, prune: opts.prune, user: opts.user },
+    {
+      dryRun: opts.dryRun,
+      prune: opts.prune,
+      user: opts.user,
+      ...opts.defaultScope === void 0 ? {} : { defaultScope: opts.defaultScope }
+    },
     targetDirFor(opts),
     ASSETS_DIR,
     pkg.version