arcane-cli 1.4.0 → 1.5.1

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

@@ -262,7 +262,16 @@ async function resolveSecretsScanExcludePrefixes(targetDir) {
 }
 async function writeManifest(targetDir, manifest) {
   const filePath = manifestPath(targetDir);
-  await writeFile2(filePath, JSON.stringify(manifest, null, 2), "utf-8");
+  let existing = "";
+  try {
+    existing = await readFile2(filePath, "utf-8");
+  } catch {
+    existing = "";
+  }
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+  const trailingNewline = /\r?\n$/.test(existing) ? eol : "";
+  const body = JSON.stringify(manifest, null, 2).replaceAll("\n", eol);
+  await writeFile2(filePath, body + trailingNewline, "utf-8");
 }
 function addComponent(manifest, component) {
   return {
@@ -1025,6 +1034,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 +3481,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,9 +4334,37 @@ 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();
+  const inheritedFiles = [];
+  const inheritedHashes = {};
+  let carrier = null;
   for (const entry of components) {
     const replacements = LEGACY_COMPONENT_MIGRATIONS[entry.name];
     if (!replacements) {
@@ -4330,13 +4373,24 @@ function migrateLegacyComponents(components) {
       out.push(entry);
       continue;
     }
+    for (const file of entry.files) {
+      if (!inheritedFiles.includes(file)) inheritedFiles.push(file);
+      const hash = entry.fileHashes?.[file];
+      if (hash !== void 0 && inheritedHashes[file] === void 0) {
+        inheritedHashes[file] = hash;
+      }
+    }
     for (const name of replacements) {
+      carrier ??= name;
       if (seen.has(name)) continue;
       seen.add(name);
       out.push({ name, files: [], installedVersion: entry.installedVersion });
     }
   }
-  return out;
+  return {
+    components: out,
+    inherited: { files: inheritedFiles, fileHashes: inheritedHashes, carrier }
+  };
 }
 async function resolveOrphan(targetDir, file, recordedHash, prune) {
   try {
@@ -4361,6 +4415,19 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
   console.log(`  Pruned orphaned file: ${file}`);
   return "pruned";
 }
+async function retainReportedOrphan(targetDir, file, recordedHash, into) {
+  try {
+    validateTargetPath(targetDir, file);
+  } catch {
+    return;
+  }
+  if (!await fileExists(join9(targetDir, file))) return;
+  if (!into.files.includes(file)) into.files.push(file);
+  if (recordedHash !== void 0) {
+    into.fileHashes ??= {};
+    into.fileHashes[file] = recordedHash;
+  }
+}
 function findReadoptedSpellComponents(components, scope = "repo", spellScope = "repo") {
   if (scope !== "repo" || spellScope !== "repo") return /* @__PURE__ */ new Set();
   return new Set(
@@ -4432,6 +4499,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 +4547,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;
@@ -4506,7 +4575,17 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   const conflictedFiles = [];
   const customizedShims = [];
   const orphanReport = [];
-  const componentsToUpdate = migrateLegacyComponents(manifest.components);
+  const orphanCandidates = [];
+  const { components: componentsToUpdate, inherited } = migrateLegacyComponents(manifest.components);
+  if (inherited.carrier !== null) {
+    for (const file of inherited.files) {
+      orphanCandidates.push({
+        owner: inherited.carrier,
+        file,
+        recordedHash: inherited.fileHashes[file]
+      });
+    }
+  }
   for (const installed of componentsToUpdate) {
     let component;
     try {
@@ -4625,24 +4704,11 @@ 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,
+      orphanCandidates.push({
+        owner: installed.name,
         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 {
-        }
-      }
+        recordedHash: installed.fileHashes?.[file]
+      });
     }
     updatedComponents.push({
       ...installed,
@@ -4651,6 +4717,26 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       fileHashes
     });
   }
+  const claimed = new Set(updatedComponents.flatMap((c) => c.files));
+  const resolvedOrphans = /* @__PURE__ */ new Set();
+  for (const { owner, file, recordedHash } of orphanCandidates) {
+    if (claimed.has(file) || resolvedOrphans.has(file)) continue;
+    resolvedOrphans.add(file);
+    const status = await resolveOrphan(
+      targetDir,
+      file,
+      recordedHash,
+      Boolean(options.prune) && !options.dryRun
+    );
+    orphanReport.push({ file, status });
+    if (status !== "reported") continue;
+    let into = updatedComponents.find((c) => c.name === owner);
+    if (!into) {
+      into = { name: owner, files: [], installedVersion: packageVersion, fileHashes: {} };
+      updatedComponents.push(into);
+    }
+    await retainReportedOrphan(targetDir, file, recordedHash, into);
+  }
   const orphansToReport = orphanReport.filter((o) => o.status !== "not-found");
   if (orphansToReport.length > 0) {
     const verb = options.dryRun ? "[dry-run] Found" : "Found";
@@ -4726,7 +4812,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(
@@ -5155,8 +5242,6 @@ async function uninstallUserTier(options, storeRoot, manifest) {
 // src/commands/doctor.ts
 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";
 
 // src/config/incidents.ts
 var INCIDENT_QUEUE = [
@@ -5297,10 +5382,33 @@ async function scanRepository(repoRoot, rules, extensions, excludePrefixes = [])
   return findings;
 }
 
-// src/modules/platform-policy.ts
+// src/modules/exec.ts
 import { execFile as execFile2 } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile2);
+var EXTERNAL_CLI_TIMEOUT_MS = 1e4;
+function execFileWithTimeout(file, args, timeoutMs) {
+  return new Promise((resolve5, reject) => {
+    const child = execFile2(
+      file,
+      args,
+      {
+        timeout: timeoutMs,
+        killSignal: "SIGTERM",
+        windowsHide: true,
+        encoding: "utf8"
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve5({ stdout, stderr });
+      }
+    );
+    child.stdin?.end();
+  });
+}
+
+// src/modules/platform-policy.ts
 var SANCTIONED_MERGE_METHODS = ["merge", "rebase"];
 function compareToLadder(effective, declaredButBlocked, interactionNote) {
   const disallowedButPermitted = effective.filter(
@@ -5367,17 +5475,19 @@ function evaluateGitHubMergePolicy(rulesets) {
 }
 async function fetchGitHubRulesets(owner, repo) {
   try {
-    const { stdout: listOut } = await execFileAsync("gh", [
-      "api",
-      `repos/${owner}/${repo}/rulesets`
-    ]);
+    const { stdout: listOut } = await execFileWithTimeout(
+      "gh",
+      ["api", `repos/${owner}/${repo}/rulesets`],
+      EXTERNAL_CLI_TIMEOUT_MS
+    );
     const summaries = JSON.parse(listOut);
     const detailed = await Promise.all(
       summaries.map(async (s) => {
-        const { stdout } = await execFileAsync("gh", [
-          "api",
-          `repos/${owner}/${repo}/rulesets/${s.id}`
-        ]);
+        const { stdout } = await execFileWithTimeout(
+          "gh",
+          ["api", `repos/${owner}/${repo}/rulesets/${s.id}`],
+          EXTERNAL_CLI_TIMEOUT_MS
+        );
         return JSON.parse(stdout);
       })
     );
@@ -5409,7 +5519,7 @@ function evaluateAdoMergePolicy(policies) {
 async function fetchAdoMergeTypePolicies(org, project, repoName, branch) {
   try {
     const orgUrl = `https://dev.azure.com/${org}`;
-    const { stdout: repoOut } = await execFileAsync("az", [
+    const { stdout: repoOut } = await execFileWithTimeout("az", [
       "repos",
       "show",
       "--repository",
@@ -5422,10 +5532,10 @@ async function fetchAdoMergeTypePolicies(org, project, repoName, branch) {
       "id",
       "--output",
       "tsv"
-    ]);
+    ], EXTERNAL_CLI_TIMEOUT_MS);
     const repositoryId = repoOut.trim();
     if (!repositoryId) return null;
-    const { stdout } = await execFileAsync("az", [
+    const { stdout } = await execFileWithTimeout("az", [
       "repos",
       "policy",
       "list",
@@ -5439,7 +5549,7 @@ async function fetchAdoMergeTypePolicies(org, project, repoName, branch) {
       project,
       "--output",
       "json"
-    ]);
+    ], EXTERNAL_CLI_TIMEOUT_MS);
     return JSON.parse(stdout);
   } catch {
     return null;
@@ -5467,7 +5577,6 @@ function parseAdoRemote(url) {
 }
 
 // src/commands/doctor.ts
-var execFileAsync2 = promisify2(execFile3);
 function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -5484,40 +5593,33 @@ async function checkNodeVersion() {
     message: `${raw} \u2014 Node.js 18 or later is required`
   };
 }
-async function checkVSCodeExtension(id, label) {
+async function checkVSCodeExtension(id, label, homeDir = resolveHomeDir()) {
   const name = `VS Code extension: ${label}`;
-  const home = process.env["HOME"] ?? "";
-  const extDirs = [
-    join13(home, ".vscode", "extensions"),
-    join13(home, ".vscode-insiders", "extensions")
+  const flavours = [
+    { dir: join13(homeDir, ".vscode", "extensions"), bin: "code" },
+    { dir: join13(homeDir, ".vscode-insiders", "extensions"), bin: "code-insiders" }
   ];
-  for (const dir of extDirs) {
+  let installBin = null;
+  for (const flavour of flavours) {
+    let entries;
     try {
-      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)
-      );
-      if (found) {
-        return { name, passed: true, message: `${id} is installed` };
-      }
+      entries = await readdir8(flavour.dir);
     } catch {
+      continue;
     }
-  }
-  let installBin = "code";
-  for (const bin of ["code", "code-insiders"]) {
-    try {
-      await execFileAsync2(bin, ["--version"]);
-      installBin = bin;
-      break;
-    } catch {
+    installBin ??= flavour.bin;
+    const prefix = id.toLowerCase() + "-";
+    const found = entries.some(
+      (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
+    );
+    if (found) {
+      return { name, passed: true, message: `${id} is installed` };
     }
   }
   return {
     name,
     passed: false,
-    message: `${id} not found. Install via: ${installBin} --install-extension ${id}`,
+    message: `${id} not found. Install via: ${installBin ?? "code"} --install-extension ${id}`,
     blocking: false
   };
 }
@@ -6003,7 +6105,7 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
   }
   const results = await Promise.all([
     checkNodeVersion(),
-    checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)"),
+    checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)", resolveHomeDir()),
     checkArcaneManifest(targetDir),
     Promise.resolve(checkIncidentReleaseGate()),
     checkPullRebase(targetDir),
@@ -6033,26 +6135,24 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     console.log("  All checks passed. Your environment is ready.\n");
   } else {
     console.log("  One or more checks failed. Fix the issues above before proceeding.\n");
-    const hasMissingSession = sessionResults.some((r) => !r.passed);
-    if (options.fix && hasMissingSession && assetsDir) {
-      console.log("  \u{1F527} Fixing missing session continuity files...\n");
-      const created = await fixSessionContinuity(targetDir, assetsDir);
-      if (created.length > 0) {
-        for (const file of created) {
-          console.log(`    \u2713 Created: ${file}`);
-        }
-        console.log(`
+    process.exitCode = 1;
+  }
+  const hasMissingSession = sessionResults.some((r) => !r.passed);
+  if (options.fix && hasMissingSession && assetsDir) {
+    console.log("  \u{1F527} Fixing missing session continuity files...\n");
+    const created = await fixSessionContinuity(targetDir, assetsDir);
+    if (created.length > 0) {
+      for (const file of created) {
+        console.log(`    \u2713 Created: ${file}`);
+      }
+      console.log(`
   ${created.length} file(s) created. Repo is now close-session-ready.
 `);
-      } else {
-        console.log("    No files needed creation (all present).\n");
-      }
-    } else if (hasMissingSession && !options.fix) {
-      console.log("  \u{1F4A1} Run `spell doctor --fix` to create missing session files.\n");
-    }
-    if (!allPassed) {
-      process.exitCode = 1;
+    } else {
+      console.log("    No files needed creation (all present).\n");
     }
+  } else if (hasMissingSession && !options.fix) {
+    console.log("  \u{1F4A1} Run `spell doctor --fix` to create missing session files.\n");
   }
 }
 
@@ -7106,9 +7206,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