arcane-cli 1.4.0 → 1.5.0

package/README.md

@@ -263,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 `~/.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. 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) {
@@ -3469,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";
     }
@@ -4319,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();
@@ -4432,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.`
@@ -4479,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;
@@ -4726,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(
@@ -7106,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