arcane-cli 1.0.0 → 1.1.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 dirname5, join as join17 } from "path";
+import { dirname as dirname10, join as join18 } from "path";
 
 // src/commands/init.ts
 import { select as select2, confirm, input as input2 } from "@inquirer/prompts";
-import { join as join5 } from "path";
+import { dirname as dirname3, join as join6 } from "path";
 import chalk2 from "chalk";
 
 // src/modules/copier.ts
@@ -109,6 +109,15 @@ var VALID_TRACKING_MODES = ["internal", "external"];
 var VALID_EXTERNAL_PROVIDERS = ["ado", "github", "jira", "other"];
 var VALID_CONTENT_SENSITIVITY = ["standard", "sensitive"];
 var VALID_PUSH_POLICIES = ["open", "guarded", "blocked"];
+var VALID_INSTALL_SCOPES = ["repo", "user"];
+function isValidFanoutPath(file) {
+  return file.length > 0 && !file.startsWith("/") && !/^[a-zA-Z]:/.test(file) && !file.includes("\\") && !file.split("/").includes("..") && !/[\r\n\0]/.test(file);
+}
+function isValidFanoutRecord(value) {
+  return isRecord(value) && Object.entries(value).every(
+    ([file, hash]) => isValidFanoutPath(file) && typeof hash === "string" && /^[0-9a-f]{64}$/.test(hash)
+  );
+}
 function isValidSubjectRoot(value) {
   const invalid = value.trim() === "" || path2.isAbsolute(value) || // Windows drive-relative ("C:docs") and UNC-ish values also escape.
   /^[a-zA-Z]:/.test(value) || value.startsWith("\\\\") || value.startsWith("\\") || value.split(/[\\/]/).includes("..") || // A stored subject_root is interpolated into agent prompts downstream, so
@@ -132,6 +141,9 @@ function validateSecretsScanExcludePrefixes(value, filePath) {
 function manifestPath(targetDir) {
   return path2.join(targetDir, MANIFEST_FILE);
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function validateTrackingFields(manifest, filePath) {
   if (manifest.tracking_mode !== void 0 && !VALID_TRACKING_MODES.includes(manifest.tracking_mode)) {
     throw new ManifestInvalidFieldError(filePath, "tracking_mode", manifest.tracking_mode);
@@ -158,6 +170,12 @@ function validateTrackingFields(manifest, filePath) {
   if (manifest.secretsScanExcludePrefixes !== void 0) {
     validateSecretsScanExcludePrefixes(manifest.secretsScanExcludePrefixes, filePath);
   }
+  if (manifest.scope !== void 0 && !VALID_INSTALL_SCOPES.includes(manifest.scope)) {
+    throw new ManifestInvalidFieldError(filePath, "scope", manifest.scope);
+  }
+  if (manifest.fanout !== void 0 && !isValidFanoutRecord(manifest.fanout)) {
+    throw new ManifestInvalidFieldError(filePath, "fanout", manifest.fanout);
+  }
 }
 async function readManifest(targetDir) {
   const filePath = manifestPath(targetDir);
@@ -179,9 +197,6 @@ async function readManifest(targetDir) {
   validateTrackingFields(manifest, filePath);
   return manifest;
 }
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 async function resolveSecretsScanExcludePrefixes(targetDir) {
   try {
     const manifest = await readManifest(targetDir);
@@ -822,6 +837,400 @@ function listProfiles() {
   }));
 }
 
+// src/modules/user-tier.ts
+import { createHash as createHash2 } from "crypto";
+import { lstat, mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rm, rmdir, writeFile as writeFile3 } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+
+// src/modules/spell-compiler.ts
+import { parse as parseYaml } from "yaml";
+var MissingFrontmatterError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MissingFrontmatterError";
+  }
+};
+var InvalidSkillNameError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidSkillNameError";
+  }
+};
+var CANONICAL_SPELLS_DIR = ".arcane/spells";
+function canonicalSpellPath(id) {
+  return `${CANONICAL_SPELLS_DIR}/${id}.md`;
+}
+var CLIENT_SHIM_PATH_PATTERNS = [
+  /^\.github\/prompts\/spell-[a-z0-9-]+\.prompt\.md$/,
+  /^\.claude\/commands\/spell-[a-z0-9-]+\.md$/,
+  /^\.agents\/skills\/spell-[a-z0-9-]+\/SKILL\.md$/
+];
+function isClientShimPath(path4) {
+  const normalized = path4.replace(/\\/g, "/").replace(/^\.\//, "");
+  return CLIENT_SHIM_PATH_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+var FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function parsePromptFrontmatter(content) {
+  const match = content.match(FRONTMATTER_PATTERN);
+  if (!match) {
+    throw new MissingFrontmatterError(
+      "Prompt file has no YAML frontmatter block (expected a leading --- ... --- block)."
+    );
+  }
+  const raw = parseYaml(match[1]);
+  const name = raw?.["name"];
+  const description = raw?.["description"];
+  if (typeof name !== "string" || name.trim() === "") {
+    throw new MissingFrontmatterError('Prompt frontmatter is missing a "name" field.');
+  }
+  if (typeof description !== "string" || description.trim() === "") {
+    throw new MissingFrontmatterError('Prompt frontmatter is missing a "description" field.');
+  }
+  const claudeDescription = raw?.["claude_description"];
+  return {
+    name,
+    description,
+    claudeDescription: typeof claudeDescription === "string" ? claudeDescription : void 0
+  };
+}
+var SPELL_NAME_PREFIX = /^Spell\s*—\s*/;
+function deriveStubTitle(name) {
+  return name.replace(SPELL_NAME_PREFIX, "").trim();
+}
+function renderClaudeCommandStub(id, frontmatter, canonicalRef = canonicalSpellPath(id)) {
+  const title = deriveStubTitle(frontmatter.name);
+  const description = frontmatter.claudeDescription ?? frontmatter.description;
+  const promptPath = canonicalRef;
+  return `---
+description: ${description}
+---
+
+# ${title}
+
+Invoke the Arcane \`${id}\` spell workflow.
+
+See the full prompt at \`${promptPath}\` for the complete workflow definition.
+
+---
+
+@${promptPath}
+`;
+}
+var SKILL_NAME_PATTERN = /^[a-z0-9-]+$/;
+function renderCodexSkill(id, frontmatter, canonicalPath) {
+  if (!SKILL_NAME_PATTERN.test(id)) {
+    throw new InvalidSkillNameError(
+      `Skill id "${id}" must match ${SKILL_NAME_PATTERN} (lowercase letters, digits, hyphens only).`
+    );
+  }
+  const description = frontmatter.claudeDescription ?? frontmatter.description;
+  return `---
+name: ${id}
+description: ${description}
+---
+
+This skill is the Arcane \`${id}\` spell. Read \`${canonicalPath}\` and follow it as the complete workflow.
+`;
+}
+
+// src/modules/user-tier.ts
+var USER_TIER_DIR_NAME = ".arcane";
+var USER_TIER_SPELLS_DIR = "spells";
+function resolveHomeDir() {
+  return homedir();
+}
+function userTierRoot(homeDir = resolveHomeDir()) {
+  return join(homeDir, USER_TIER_DIR_NAME);
+}
+var USER_TIER_COMPONENTS = SPELL_COMPONENT_NAMES;
+var CANONICAL_SPELL_PATH_PATTERN = /^\.arcane\/spells\/(spell-[a-z0-9-]+)\.md$/;
+var STORE_SPELL_PATH_PATTERN = /^spells\/(spell-[a-z0-9-]+)\.md$/;
+function storeSpellPath(id) {
+  return `${USER_TIER_SPELLS_DIR}/${id}.md`;
+}
+function spellIdFromCanonicalPath(path4) {
+  return path4.replace(/\\/g, "/").match(CANONICAL_SPELL_PATH_PATTERN)?.[1];
+}
+function spellIdFromStorePath(path4) {
+  return path4.replace(/\\/g, "/").match(STORE_SPELL_PATH_PATTERN)?.[1];
+}
+function absoluteStoreSpellPath(storeRoot, id) {
+  return resolve(storeRoot, storeSpellPath(id)).replace(/\\/g, "/");
+}
+function componentForScope(component, scope) {
+  if (scope === "repo") return component;
+  const files = [];
+  const sourceOverrides = {};
+  for (const file of component.files) {
+    const id = spellIdFromCanonicalPath(file);
+    if (id === void 0) continue;
+    const installed = storeSpellPath(id);
+    files.push(installed);
+    sourceOverrides[installed] = component.sourceOverrides?.[file] ?? file;
+  }
+  return { name: component.name, description: component.description, files, sourceOverrides };
+}
+function spellIdsInStore(components) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const component of components) {
+    for (const file of component.files) {
+      const id = spellIdFromStorePath(file);
+      if (id !== void 0) ids.add(id);
+    }
+  }
+  return [...ids].sort();
+}
+var USER_FANOUT_PATHS = {
+  codex: (id) => `.agents/skills/${id}/SKILL.md`,
+  claude: (id) => `.claude/commands/${id}.md`
+};
+var FANOUT_CLIENT_LABELS = {
+  codex: "Codex/Copilot skills",
+  claude: "Claude Code commands"
+};
+function clientOfFanoutPath(relativePath) {
+  const normalized = relativePath.replace(/\\/g, "/");
+  if (normalized.startsWith(".agents/skills/")) return "codex";
+  if (normalized.startsWith(".claude/commands/")) return "claude";
+  return void 0;
+}
+async function readSpellSource(storeRoot, id, fallbackDir) {
+  for (const candidate of [
+    join(storeRoot, storeSpellPath(id)),
+    ...fallbackDir ? [join(fallbackDir, canonicalSpellPath(id))] : []
+  ]) {
+    try {
+      return await readFile3(candidate, "utf-8");
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+  return void 0;
+}
+async function renderUserFanout(storeRoot, spellIds, fallbackDir) {
+  const files = [];
+  const missing = [];
+  for (const id of [...spellIds].sort()) {
+    const canonical = await readSpellSource(storeRoot, id, fallbackDir);
+    if (canonical === void 0) {
+      missing.push(id);
+      continue;
+    }
+    const frontmatter = parsePromptFrontmatter(canonical);
+    const absolutePath = absoluteStoreSpellPath(storeRoot, id);
+    files.push({
+      relativePath: USER_FANOUT_PATHS.codex(id),
+      client: "codex",
+      content: renderCodexSkill(id, frontmatter, absolutePath)
+    });
+    files.push({
+      relativePath: USER_FANOUT_PATHS.claude(id),
+      client: "claude",
+      content: renderClaudeCommandStub(id, frontmatter, absolutePath)
+    });
+  }
+  return { files, missing };
+}
+async function classifyTarget(path4) {
+  try {
+    const stats = await lstat(path4);
+    return stats.isFile() ? "file" : "other";
+  } catch (err) {
+    if (err.code === "ENOENT") return "absent";
+    throw err;
+  }
+}
+function sha256(content) {
+  return createHash2("sha256").update(content, "utf-8").digest("hex");
+}
+function perSpellDirectory(homeDir, relativePath) {
+  if (clientOfFanoutPath(relativePath) !== "codex") return void 0;
+  return dirname(join(homeDir, relativePath));
+}
+async function removeDirectoryIfEmpty(dir) {
+  try {
+    const entries = await readdir2(dir);
+    if (entries.length === 0) await rmdir(dir);
+  } catch {
+  }
+}
+async function syncUserTierFanout(options) {
+  const rendered = await renderUserFanout(options.storeRoot, options.spellIds, options.fallbackDir);
+  const desired = rendered.files;
+  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"]) {
+      const relativePath = USER_FANOUT_PATHS[client](id);
+      desiredPaths.add(relativePath);
+      if (previous[relativePath] !== void 0) record[relativePath] = previous[relativePath];
+      outcomes.push({ relativePath, status: "unrenderable" });
+    }
+  }
+  for (const file of desired) {
+    const target = join(options.homeDir, file.relativePath);
+    const recorded = previous[file.relativePath];
+    const newHash = sha256(file.content);
+    const state = await classifyTarget(target);
+    if (state === "absent") {
+      if (!dryRun) {
+        await mkdir2(dirname(target), { recursive: true });
+        await writeFile3(target, file.content, "utf-8");
+      }
+      record[file.relativePath] = newHash;
+      outcomes.push({ relativePath: file.relativePath, status: "written" });
+      continue;
+    }
+    if (state === "other" || recorded === void 0) {
+      outcomes.push({ relativePath: file.relativePath, status: "collision" });
+      continue;
+    }
+    const currentHash = await hashFile(target);
+    if (currentHash !== recorded) {
+      record[file.relativePath] = recorded;
+      outcomes.push({ relativePath: file.relativePath, status: "customized" });
+      continue;
+    }
+    if (currentHash === newHash) {
+      record[file.relativePath] = newHash;
+      outcomes.push({ relativePath: file.relativePath, status: "unchanged" });
+      continue;
+    }
+    if (!dryRun) await writeFile3(target, file.content, "utf-8");
+    record[file.relativePath] = newHash;
+    outcomes.push({ relativePath: file.relativePath, status: "written" });
+  }
+  for (const [relativePath, recorded] of Object.entries(previous)) {
+    if (desiredPaths.has(relativePath)) continue;
+    const target = join(options.homeDir, relativePath);
+    const state = await classifyTarget(target);
+    if (state === "absent") {
+      outcomes.push({ relativePath, status: "gone" });
+      continue;
+    }
+    if (state === "other" || await hashFile(target) !== recorded) {
+      record[relativePath] = recorded;
+      outcomes.push({ relativePath, status: "kept-edited" });
+      continue;
+    }
+    if (!dryRun) {
+      await rm(target, { force: true });
+      const spellDir = perSpellDirectory(options.homeDir, relativePath);
+      if (spellDir !== void 0) await removeDirectoryIfEmpty(spellDir);
+    }
+    outcomes.push({ relativePath, status: "pruned" });
+  }
+  return { record, outcomes };
+}
+function summarizeFanout(outcomes) {
+  const counts = {
+    written: 0,
+    unchanged: 0,
+    customized: 0,
+    collision: 0,
+    pruned: 0,
+    "kept-edited": 0,
+    gone: 0,
+    unrenderable: 0
+  };
+  for (const outcome of outcomes) counts[outcome.status]++;
+  return counts;
+}
+function describeFanoutOutcomes(outcomes, dryRun = false) {
+  const counts = summarizeFanout(outcomes);
+  const lines = [];
+  const prefix = dryRun ? "[dry-run] Would " : "";
+  const byClient = (status) => {
+    const n = { codex: 0, claude: 0 };
+    for (const o of outcomes) {
+      if (o.status !== status) continue;
+      const client = clientOfFanoutPath(o.relativePath);
+      if (client !== void 0) n[client]++;
+    }
+    return n;
+  };
+  const paths = (status) => outcomes.filter((o) => o.status === status).map((o) => `    ~/${o.relativePath}`).join("\n");
+  if (counts.written > 0) {
+    const n = byClient("written");
+    lines.push(
+      `${prefix}${dryRun ? "write" : "Wrote"} ${counts.written} client file(s): ${n.codex} ${FANOUT_CLIENT_LABELS.codex}, ${n.claude} ${FANOUT_CLIENT_LABELS.claude}.`
+    );
+  }
+  if (counts.pruned > 0) {
+    lines.push(`${prefix}${dryRun ? "remove" : "Removed"} ${counts.pruned} client file(s) no longer needed.`);
+  }
+  if (counts.customized > 0) {
+    lines.push(
+      `! ${dryRun ? "Would keep" : "Kept"} ${counts.customized} customized client file(s) untouched (edited since Arcane wrote them):
+${paths("customized")}
+  Delete one to have it regenerated by the next \`spell update --user\`.`
+    );
+  }
+  if (counts.collision > 0) {
+    lines.push(
+      `! ${dryRun ? "Would leave" : "Left"} ${counts.collision} existing path(s) alone (not written by Arcane \u2014 a skill or command of the same name, a directory or a link already exists there):
+${paths("collision")}
+  Move or rename it and run \`spell update --user\` to install Arcane's.`
+    );
+  }
+  if (counts.unrenderable > 0) {
+    lines.push(
+      `! ${dryRun ? "Would keep" : "Kept"} ${counts.unrenderable} client file(s) whose spell source is missing from the store and from this CLI (left as they are):
+${paths("unrenderable")}
+  Restore the spell with \`spell update --user\`, or delete these files if the spell is no longer shipped.`
+    );
+  }
+  if (counts["kept-edited"] > 0) {
+    lines.push(
+      `! ${dryRun ? "Would keep" : "Kept"} ${counts["kept-edited"]} edited client file(s) that Arcane no longer needs (delete them yourself if unwanted):
+${paths("kept-edited")}`
+    );
+  }
+  return lines;
+}
+async function inspectUserTierFanout(homeDir, record) {
+  const health = {
+    total: 0,
+    byClient: { codex: 0, claude: 0 },
+    missing: [],
+    customized: []
+  };
+  for (const [relativePath, recorded] of Object.entries(record ?? {})) {
+    health.total++;
+    const client = clientOfFanoutPath(relativePath);
+    if (client !== void 0) health.byClient[client]++;
+    const target = join(homeDir, relativePath);
+    const state = await classifyTarget(target);
+    if (state === "absent") {
+      health.missing.push(relativePath);
+      continue;
+    }
+    if (state === "other" || await hashFile(target) !== recorded) health.customized.push(relativePath);
+  }
+  return health;
+}
+function isUserTierStore(targetDir) {
+  return resolve(targetDir) === resolve(userTierRoot());
+}
+function resolveInstallScope(targetDir, manifestScope, userFlag) {
+  if (userFlag) return { scope: "user", misplacedUserManifest: false };
+  if (manifestScope !== "user") return { scope: "repo", misplacedUserManifest: false };
+  return isUserTierStore(targetDir) ? { scope: "user", misplacedUserManifest: false } : { scope: "repo", misplacedUserManifest: true };
+}
+function misplacedUserManifestMessage(targetDir) {
+  return `This .arcane.json belongs to the user tier (scope: "user"), but ${targetDir} is not the store (${userTierRoot()}). Run the command with --user to operate on the store, or from the store directory itself.`;
+}
+var VSCODE_USER_TIER_NOTE = [
+  "VS Code Copilot: no settings change is needed \u2014 Copilot discovers ~/.agents/skills by default",
+  "(chat.useAgentSkills, on by default) and lists each spell under /. Reload the window after installing.",
+  "VS Code has deprecated chat.promptFilesLocations; the user tier does not use it."
+];
+var CLAUDE_PRECEDENCE_NOTE = "Claude Code runs a personal command over a project command of the same name, so /spell-* in a repository that still carries its own shims now runs the user tier's copy.";
+
 // src/modules/banner.ts
 import chalk from "chalk";
 import gradient from "gradient-string";
@@ -844,7 +1253,7 @@ var WORDMARK = [
 var INDENT = "  ";
 var LOCKUP_WIDTH = INDENT.length + Math.max(...WORDMARK.map((l) => l.length));
 function sleep(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
 }
 function isAnimatable() {
   return !!process.stdout.isTTY && process.env["TERM"] !== "dumb" && process.env["CI"] !== "true" && process.env["ARCANE_DISABLE_ANIMATION"] !== "true" && (process.stdout.columns ?? 80) >= LOCKUP_WIDTH;
@@ -962,8 +1371,8 @@ function printWarning(message) {
 
 // src/modules/agents.ts
 import { select, checkbox, Separator } from "@inquirer/prompts";
-import { mkdir as mkdir3, writeFile as writeFile5, copyFile as copyFile2 } from "fs/promises";
-import { join as join3 } from "path";
+import { mkdir as mkdir4, writeFile as writeFile6, copyFile as copyFile2 } from "fs/promises";
+import { join as join4 } from "path";
 import { stringify } from "yaml";
 
 // src/config/agent-roles.ts
@@ -1198,8 +1607,8 @@ async function applyNamingStrategy(strategy, roleIds) {
 }
 
 // src/modules/agent-loader.ts
-import { readFile as readFile3, readdir as readdir2, access as access2 } from "fs/promises";
-import { join } from "path";
+import { readFile as readFile4, readdir as readdir3, access as access2 } from "fs/promises";
+import { join as join2 } from "path";
 import { parse } from "yaml";
 
 // src/modules/agent-schema.ts
@@ -1379,7 +1788,7 @@ var AgentRosterNotFoundError = class extends Error {
     this.name = "AgentRosterNotFoundError";
   }
 };
-function parseYaml(content, source) {
+function parseYaml2(content, source) {
   try {
     return parse(content);
   } catch (err) {
@@ -1388,44 +1797,44 @@ function parseYaml(content, source) {
   }
 }
 async function loadAgentDefinition(agentsDir, id) {
-  const filePath = join(agentsDir, `${id}.yaml`);
+  const filePath = join2(agentsDir, `${id}.yaml`);
   let content;
   try {
-    content = await readFile3(filePath, "utf8");
+    content = await readFile4(filePath, "utf8");
   } catch {
     throw new AgentDefinitionNotFoundError(id, agentsDir);
   }
-  return validateAgentDefinition(parseYaml(content, filePath), filePath);
+  return validateAgentDefinition(parseYaml2(content, filePath), filePath);
 }
 async function loadRoster(targetDir) {
-  const rosterPath = join(targetDir, ".arcane", "agents.yaml");
+  const rosterPath = join2(targetDir, ".arcane", "agents.yaml");
   let content;
   try {
-    content = await readFile3(rosterPath, "utf8");
+    content = await readFile4(rosterPath, "utf8");
   } catch {
     throw new AgentRosterNotFoundError();
   }
-  return validateAgentRoster(parseYaml(content, rosterPath), rosterPath);
+  return validateAgentRoster(parseYaml2(content, rosterPath), rosterPath);
 }
 async function rosterExists(targetDir) {
   try {
-    await access2(join(targetDir, ".arcane", "agents.yaml"));
+    await access2(join2(targetDir, ".arcane", "agents.yaml"));
     return true;
   } catch {
     return false;
   }
 }
 function projectAgentsDir(targetDir) {
-  return join(targetDir, ".arcane", "agents");
+  return join2(targetDir, ".arcane", "agents");
 }
 
 // src/modules/agent-generator.ts
-import { writeFile as writeFile4, mkdir as mkdir2 } from "fs/promises";
-import { join as join2 } from "path";
-import { homedir } from "os";
+import { writeFile as writeFile5, mkdir as mkdir3 } from "fs/promises";
+import { join as join3 } from "path";
+import { homedir as homedir2 } from "os";
 
 // src/modules/merger.ts
-import { readFile as readFile4, writeFile as writeFile3, rm } from "fs/promises";
+import { readFile as readFile5, writeFile as writeFile4, rm as rm2 } from "fs/promises";
 import path3 from "path";
 var MARKER_START = "<!-- arcane:start -->";
 var MARKER_END = "<!-- arcane:end -->";
@@ -1440,7 +1849,7 @@ async function mergeIntoFile(targetDir, relativePath, content, opts = {}) {
   const destPath = path3.resolve(targetDir, relativePath);
   let existing;
   try {
-    existing = await readFile4(destPath, "utf8");
+    existing = await readFile5(destPath, "utf8");
   } catch (err) {
     const e = err;
     if (e.code === "ENOENT") {
@@ -1456,7 +1865,7 @@ ${content}
 ${MARKER_END}
 `;
     if (!opts.dryRun) {
-      await writeFile3(destPath, newContent, "utf8");
+      await writeFile4(destPath, newContent, "utf8");
     }
     return true;
   }
@@ -1481,7 +1890,7 @@ ${MARKER_END}
 ${content}
 ${afterMarker}`;
     if (!opts.dryRun) {
-      await writeFile3(destPath, updated, "utf8");
+      await writeFile4(destPath, updated, "utf8");
     }
     return true;
   }
@@ -1491,7 +1900,7 @@ ${content}
 ${MARKER_END}
 `;
   if (!opts.dryRun) {
-    await writeFile3(destPath, appended, "utf8");
+    await writeFile4(destPath, appended, "utf8");
   }
   return true;
 }
@@ -1499,7 +1908,7 @@ async function stripMarkerSection(targetDir, relativePath, opts = {}) {
   const destPath = path3.resolve(targetDir, relativePath);
   let existing;
   try {
-    existing = await readFile4(destPath, "utf8");
+    existing = await readFile5(destPath, "utf8");
   } catch {
     return false;
   }
@@ -1511,9 +1920,9 @@ async function stripMarkerSection(targetDir, relativePath, opts = {}) {
   const stripped = (before + after).replace(/\n{3,}/g, "\n\n").trim();
   if (!opts.dryRun) {
     if (stripped.length === 0) {
-      await rm(destPath, { force: true });
+      await rm2(destPath, { force: true });
     } else {
-      await writeFile3(destPath, stripped + "\n", "utf8");
+      await writeFile4(destPath, stripped + "\n", "utf8");
     }
   }
   return true;
@@ -1634,7 +2043,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
   const skipped = [];
   let hasUnresolvedRoles = false;
   const projectDefs = projectAgentsDir(targetDir);
-  const bundledDefs = join2(assetsDir, "agents");
+  const bundledDefs = join3(assetsDir, "agents");
   const resolved = [];
   for (const entry of roster.roster) {
     let def;
@@ -1658,27 +2067,27 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
   if (roster.openclaw.enabled && options.openclaw !== false) {
     const openclawRoot = roster.openclaw.workspace_root.replace(
       /^~/,
-      homedir()
+      homedir2()
     );
     for (const { entry, def, displayName } of resolved) {
       if (!def.clients.openclaw) continue;
       const workspaceName = entry.id === "main" ? "workspace" : `workspace-${entry.id}`;
-      const workspaceDir = join2(openclawRoot, workspaceName);
+      const workspaceDir = join3(openclawRoot, workspaceName);
       try {
         if (!options.dryRun) {
-          await mkdir2(workspaceDir, { recursive: true });
-          await writeFile4(
-            join2(workspaceDir, "IDENTITY.md"),
+          await mkdir3(workspaceDir, { recursive: true });
+          await writeFile5(
+            join3(workspaceDir, "IDENTITY.md"),
             renderIdentity(def, displayName),
             "utf8"
           );
-          await writeFile4(
-            join2(workspaceDir, "SOUL.md"),
+          await writeFile5(
+            join3(workspaceDir, "SOUL.md"),
             renderSoul(def, displayName),
             "utf8"
           );
-          await writeFile4(
-            join2(workspaceDir, "TOOLS.md"),
+          await writeFile5(
+            join3(workspaceDir, "TOOLS.md"),
             renderTools(def, displayName),
             "utf8"
           );
@@ -1703,11 +2112,11 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
         }
       }))
     };
-    const generatedDir = join2(targetDir, ".arcane", "generated");
+    const generatedDir = join3(targetDir, ".arcane", "generated");
     if (!options.dryRun) {
-      await mkdir2(generatedDir, { recursive: true });
-      await writeFile4(
-        join2(generatedDir, "openclaw-roster.json"),
+      await mkdir3(generatedDir, { recursive: true });
+      await writeFile5(
+        join3(generatedDir, "openclaw-roster.json"),
         JSON.stringify(patch, null, 2) + "\n",
         "utf8"
       );
@@ -1719,17 +2128,17 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
     synced.push("openclaw-roster.json");
   }
   if (options.copilot !== false) {
-    const agentsDir = join2(targetDir, ".github", "agents");
+    const agentsDir = join3(targetDir, ".github", "agents");
     if (!options.dryRun) {
-      await mkdir2(agentsDir, { recursive: true });
+      await mkdir3(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`;
       if (!options.dryRun) {
-        await writeFile4(
-          join2(agentsDir, fileName),
+        await writeFile5(
+          join3(agentsDir, fileName),
           renderCopilotAgent(def, displayName),
           "utf8"
         );
@@ -1870,11 +2279,11 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
     },
     roster: rosterEntries
   };
-  const arcaneDir = join3(targetDir, ".arcane", "agents");
+  const arcaneDir = join4(targetDir, ".arcane", "agents");
   if (!options.dryRun) {
-    await mkdir3(arcaneDir, { recursive: true });
-    await writeFile5(
-      join3(targetDir, ".arcane", "agents.yaml"),
+    await mkdir4(arcaneDir, { recursive: true });
+    await writeFile6(
+      join4(targetDir, ".arcane", "agents.yaml"),
       stringify(roster),
       "utf8"
     );
@@ -1882,8 +2291,8 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
     console.log("  [dry-run] Would write: .arcane/agents.yaml");
   }
   for (const roleId of selectedRoleIds) {
-    const src = join3(assetsDir, "agents", `${roleId}.yaml`);
-    const dest = join3(arcaneDir, `${roleId}.yaml`);
+    const src = join4(assetsDir, "agents", `${roleId}.yaml`);
+    const dest = join4(arcaneDir, `${roleId}.yaml`);
     if (!options.dryRun) {
       try {
         await copyFile2(src, dest);
@@ -2017,9 +2426,9 @@ async function runAgentsList(targetDir) {
 }
 
 // src/modules/push-safety.ts
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile6, chmod, access as access3, rm as rm2, readdir as readdir3 } from "fs/promises";
+import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile7, chmod, access as access3, rm as rm3, readdir as readdir4 } from "fs/promises";
 import { constants } from "fs";
-import { join as join4, resolve, dirname, basename } from "path";
+import { join as join5, resolve as resolve2, dirname as dirname2, basename } from "path";
 
 // src/modules/git.ts
 import { execFile } from "child_process";
@@ -2116,7 +2525,7 @@ function buildGitEnv() {
 function runGit(cwd, args, options = {}) {
   const commandClass = options.commandClass ?? classifyGitCommand(args);
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUTS_MS[commandClass] ?? DEFAULT_TIMEOUTS_MS.write;
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const child = execFile(
       "git",
       args,
@@ -2150,7 +2559,7 @@ function runGit(cwd, args, options = {}) {
           reject(error);
           return;
         }
-        resolve4({ stdout, stderr });
+        resolve5({ stdout, stderr });
       }
     );
     child.stdin?.end();
@@ -2268,7 +2677,7 @@ function isArcaneHooksPath(root, value) {
   const windows = process.platform === "win32";
   const normalize = (p) => {
     const separated = windows ? p.replace(/\\/g, "/") : p;
-    const absolute = resolve(root, separated).replace(/\\/g, "/").replace(/\/+$/, "");
+    const absolute = resolve2(root, separated).replace(/\\/g, "/").replace(/\/+$/, "");
     return windows ? absolute.toLowerCase() : absolute;
   };
   return normalize(value) === normalize(ARCANE_HOOKS_DIR);
@@ -2316,7 +2725,7 @@ async function repositoryRoot(cwd) {
     ]);
     const commonDir = stdout.trim();
     if (commonDir !== "") {
-      const parent = dirname(commonDir);
+      const parent = dirname2(commonDir);
       if (basename(commonDir) === ".git" && parent !== "") return parent;
     }
   } catch {
@@ -2330,10 +2739,10 @@ async function repositoryRoot(cwd) {
   return cwd;
 }
 async function hookFilePath(cwd, hookName = "pre-push") {
-  return join4(await repositoryRoot(cwd), ARCANE_HOOKS_DIR, hookName);
+  return join5(await repositoryRoot(cwd), ARCANE_HOOKS_DIR, hookName);
 }
 async function hooksPathValue(cwd) {
-  return join4(await repositoryRoot(cwd), ARCANE_HOOKS_DIR).replace(/\\/g, "/");
+  return join5(await repositoryRoot(cwd), ARCANE_HOOKS_DIR).replace(/\\/g, "/");
 }
 async function installHook(cwd, hookName, body) {
   const root = await repositoryRoot(cwd);
@@ -2352,12 +2761,12 @@ async function installHook(cwd, hookName, body) {
       return { status: "refused-default-hooks", hooks: displaced };
     }
   }
-  const hookPath = join4(root, ARCANE_HOOKS_DIR, hookName);
+  const hookPath = join5(root, ARCANE_HOOKS_DIR, hookName);
   if (existing !== void 0 && await hookFileMatches(cwd, hookName, body)) {
     return { status: "already-ours" };
   }
-  await mkdir4(join4(root, ARCANE_HOOKS_DIR), { recursive: true });
-  await writeFile6(hookPath, body, "utf-8");
+  await mkdir5(join5(root, ARCANE_HOOKS_DIR), { recursive: true });
+  await writeFile7(hookPath, body, "utf-8");
   await chmod(hookPath, 493);
   await runGit(cwd, ["config", "--local", "core.hooksPath", await hooksPathValue(cwd)]);
   return { status: "installed", path: hookPath };
@@ -2401,12 +2810,12 @@ async function defaultHooks(cwd) {
   let hooksDir;
   try {
     const { stdout } = await runGit(cwd, ["rev-parse", "--git-common-dir"]);
-    hooksDir = join4(resolve(cwd, stdout.trim()), "hooks");
+    hooksDir = join5(resolve2(cwd, stdout.trim()), "hooks");
   } catch {
     return [];
   }
   try {
-    return (await readdir3(hooksDir)).filter((name) => !name.endsWith(".sample")).sort();
+    return (await readdir4(hooksDir)).filter((name) => !name.endsWith(".sample")).sort();
   } catch {
     return [];
   }
@@ -2415,7 +2824,7 @@ async function hookFileMatches(cwd, hookName, body) {
   const hookPath = await hookFilePath(cwd, hookName);
   if (!await fileExists(hookPath)) return false;
   try {
-    if (await readFile5(hookPath, "utf-8") !== body) return false;
+    if (await readFile6(hookPath, "utf-8") !== body) return false;
   } catch {
     return false;
   }
@@ -2434,13 +2843,13 @@ async function removeHook(cwd, hookName) {
   if (!isArcaneHooksPath(root, existing.value)) return;
   if (existing.scope !== "local" && existing.scope !== "worktree") return;
   try {
-    await rm2(await hookFilePath(cwd, hookName), { force: true });
+    await rm3(await hookFilePath(cwd, hookName), { force: true });
   } catch {
   }
-  const hooksDir = join4(root, ARCANE_HOOKS_DIR);
+  const hooksDir = join5(root, ARCANE_HOOKS_DIR);
   let remaining = [];
   try {
-    remaining = await readdir3(hooksDir);
+    remaining = await readdir4(hooksDir);
   } catch {
     remaining = [];
   }
@@ -2768,6 +3177,10 @@ function buildProfileDescription(components, profile) {
   return "\n" + parts.join("\n");
 }
 async function runInit(options, targetDir, assetsDir, packageVersion) {
+  if (options.user) {
+    await runInitUser(options, targetDir, assetsDir, packageVersion);
+    return;
+  }
   if (options.profile && !VALID_PROFILES.includes(options.profile)) {
     throw new Error(
       `Invalid profile "${options.profile}". Valid options: ${VALID_PROFILES.join(", ")}`
@@ -2872,7 +3285,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     const installedFiles = [];
     const fileHashes = {};
     for (const file of component.files) {
-      const srcPath = join5(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const srcPath = join6(assetsDir, component.sourceOverrides?.[file] ?? file);
       if (options.dryRun) {
         printDryRun(`Would copy: ${file}`);
       } else {
@@ -2889,7 +3302,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       fileCount++;
     }
     for (const dir of component.directories ?? []) {
-      const srcDirPath = join5(assetsDir, dir);
+      const srcDirPath = join6(assetsDir, dir);
       if (options.dryRun) {
         printDryRun(`Would copy directory: ${dir}/`);
       } else {
@@ -2918,7 +3331,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   if (options.dryRun) {
     if (hasAgents) {
       const agentFiles = await import("fs").then(
-        (fsModule) => fsModule.promises.readdir(join5(assetsDir, "agents"))
+        (fsModule) => fsModule.promises.readdir(join6(assetsDir, "agents"))
       );
       const yamlFiles = agentFiles.filter((f) => f.endsWith(".yaml")).sort();
       printDryRun("Would run agent setup (interactive):");
@@ -3160,9 +3573,110 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   );
   console.log();
 }
+async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
+  if (options.profile) {
+    throw new Error(
+      '"--profile" does not apply to "--user": the user tier always installs every spell and nothing else.'
+    );
+  }
+  try {
+    await readManifest(storeRoot);
+    console.log(chalk2.hex("#a855f7")(`
+  \u2726 Arcane v${packageVersion}
+`));
+    console.log(
+      `Already initialized (user tier at ${storeRoot}). Run "spell update --user" to update it.`
+    );
+    return;
+  } catch (err) {
+    if (!(err instanceof ManifestNotFoundError)) throw err;
+  }
+  console.log(chalk2.hex("#a855f7")(`
+  \u2726 Arcane v${packageVersion}
+`));
+  const homeDir = dirname3(storeRoot);
+  const components = USER_TIER_COMPONENTS.map(
+    (name) => componentForScope(getComponent(name), "user")
+  );
+  const spellIds = components.flatMap((c) => c.files).map((file) => spellIdFromStorePath(file)).filter((id) => id !== void 0);
+  printSection(`\u{1F4E6} User tier \u2014 ${storeRoot}`);
+  console.log();
+  console.log(
+    `  \u2728 ${spellIds.length} Spells \u2192 ${storeRoot}/spells/  \xB7  \u{1F517} ${spellIds.length * 2} client files \u2192 ~/.agents/skills (Codex, Copilot), ~/.claude/commands (Claude Code)`
+  );
+  console.log();
+  if (options.dryRun) {
+    for (const component of components) {
+      for (const file of component.files) printDryRun(`Would copy: ${file}`);
+    }
+    for (const id of spellIds) {
+      for (const client of ["codex", "claude"]) {
+        const relativePath = USER_FANOUT_PATHS[client](id);
+        if (await fileExists(join6(homeDir, relativePath))) {
+          printDryRun(`Would leave alone (exists, not written by Arcane): ~/${relativePath}`);
+        } else {
+          printDryRun(`Would write: ~/${relativePath}`);
+        }
+      }
+    }
+    printDryRun(
+      `Would initialize the user tier \u2014 ${spellIds.length} spells, ${spellIds.length * 2} client files`
+    );
+    return;
+  }
+  const installedComponents = [];
+  let fileCount = 0;
+  for (const component of components) {
+    const installedFiles = [];
+    const fileHashes = {};
+    for (const file of component.files) {
+      const srcPath = join6(assetsDir, component.sourceOverrides?.[file] ?? file);
+      fileHashes[file] = await copyFile(srcPath, storeRoot, file, { force: options.force });
+      installedFiles.push(file);
+      fileCount++;
+    }
+    installedComponents.push({
+      name: component.name,
+      files: installedFiles,
+      installedVersion: packageVersion,
+      fileHashes
+    });
+  }
+  const fanout = await syncUserTierFanout({ homeDir, storeRoot, spellIds, fallbackDir: assetsDir });
+  const manifest = {
+    version: packageVersion,
+    // The tier is un-profiled; "full" records the profile its component set
+    // is drawn from, and every command reads `scope` before `profile`.
+    profile: "full",
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    components: installedComponents,
+    scope: "user",
+    fanout: fanout.record
+  };
+  await writeManifest(storeRoot, manifest);
+  printStep(`\u2728 ${fileCount} Spells installed to ${storeRoot}/spells/`);
+  for (const line of describeFanoutOutcomes(fanout.outcomes)) {
+    if (line.startsWith("!")) printWarning(line.slice(2));
+    else printStep(`\u{1F517} ${line}`);
+  }
+  printSuccess(
+    `Initialized the user tier \u2014 ${fileCount} spells, ${Object.keys(fanout.record).length} client files recorded`
+  );
+  console.log();
+  printSection("\u{1F9ED} Clients");
+  console.log();
+  for (const line of VSCODE_USER_TIER_NOTE) printInfo(line);
+  printInfo(CLAUDE_PRECEDENCE_NOTE);
+  console.log();
+  printSection("\u{1F680} Next steps");
+  console.log();
+  printNextStep(1, "Reload VS Code, and start a fresh Codex or Claude Code session, so the pickers see the new files");
+  printNextStep(2, "`spell status --user` shows the tier; `spell update --user` refreshes it after upgrading the CLI");
+  console.log();
+}
 
 // src/commands/add.ts
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   let manifest;
   try {
@@ -3198,7 +3712,7 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   const installedFiles = [];
   const fileHashes = {};
   for (const file of component.files) {
-    const srcPath = join6(assetsDir, component.sourceOverrides?.[file] ?? file);
+    const srcPath = join7(assetsDir, component.sourceOverrides?.[file] ?? file);
     if (options.dryRun) {
       console.log(`  [dry-run] Would copy: ${file}`);
     } else {
@@ -3208,7 +3722,7 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
     fileCount++;
   }
   for (const dir of component.directories ?? []) {
-    const srcDirPath = join6(assetsDir, dir);
+    const srcDirPath = join7(assetsDir, dir);
     if (options.dryRun) {
       console.log(`  [dry-run] Would copy directory: ${dir}/`);
     } else {
@@ -3242,13 +3756,13 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
 }
 
 // src/commands/update.ts
-import { join as join8 } from "path";
-import { readFile as readFile6, writeFile as writeFile8, rm as rm3 } from "fs/promises";
+import { dirname as dirname4, join as join9 } from "path";
+import { readFile as readFile7, writeFile as writeFile9, rm as rm4 } from "fs/promises";
 
 // src/modules/hub.ts
 import { confirm as confirm2, select as select3, input as input3 } from "@inquirer/prompts";
-import { readdir as readdir4, writeFile as writeFile7 } from "fs/promises";
-import { join as join7 } from "path";
+import { readdir as readdir5, writeFile as writeFile8 } from "fs/promises";
+import { join as join8 } from "path";
 var MANIFEST_RETROFITS = [
   {
     field: "role",
@@ -3387,12 +3901,12 @@ async function runManifestRetrofits(manifest) {
   return patch;
 }
 async function offerRegistryScaffold(targetDir, businessRoot) {
-  const registryPath = join7(targetDir, businessRoot, "registry.json");
+  const registryPath = join8(targetDir, businessRoot, "registry.json");
   if (await fileExists(registryPath)) return;
-  const businessRootPath = join7(targetDir, businessRoot);
+  const businessRootPath = join8(targetDir, businessRoot);
   let ventureDirs;
   try {
-    const entries = await readdir4(businessRootPath, { withFileTypes: true });
+    const entries = await readdir5(businessRootPath, { withFileTypes: true });
     ventureDirs = entries.filter((e) => e.isDirectory() && e.name !== "_template").map((e) => e.name);
   } catch {
     return;
@@ -3427,7 +3941,7 @@ async function offerRegistryScaffold(targetDir, businessRoot) {
     updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
     ventures
   };
-  await writeFile7(registryPath, JSON.stringify(registry, null, 2) + "\n", "utf-8");
+  await writeFile8(registryPath, JSON.stringify(registry, null, 2) + "\n", "utf-8");
   console.log(
     `  \u2713 Scaffolded ${businessRoot}/registry.json with ${Object.keys(ventures).length} venture(s).`
   );
@@ -3575,18 +4089,6 @@ async function fetchPublishedFile(version, relativeAssetPath) {
   }
 }
 
-// src/modules/spell-compiler.ts
-import { parse as parseYaml2 } from "yaml";
-var CLIENT_SHIM_PATH_PATTERNS = [
-  /^\.github\/prompts\/spell-[a-z0-9-]+\.prompt\.md$/,
-  /^\.claude\/commands\/spell-[a-z0-9-]+\.md$/,
-  /^\.agents\/skills\/spell-[a-z0-9-]+\/SKILL\.md$/
-];
-function isClientShimPath(path4) {
-  const normalized = path4.replace(/\\/g, "/").replace(/^\.\//, "");
-  return CLIENT_SHIM_PATH_PATTERNS.some((pattern) => pattern.test(normalized));
-}
-
 // src/commands/update.ts
 function migrateLegacyComponents(components) {
   const out = [];
@@ -3608,7 +4110,7 @@ function migrateLegacyComponents(components) {
   return out;
 }
 async function resolveOrphan(targetDir, file, recordedHash, prune) {
-  const filePath = join8(targetDir, file);
+  const filePath = join9(targetDir, file);
   if (!await fileExists(filePath)) return "not-found";
   if (!prune) return "reported";
   if (recordedHash === void 0) {
@@ -3620,23 +4122,23 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
     console.log(`  ! Orphaned but edited since install \u2014 not pruning: ${file}`);
     return "reported";
   }
-  await rm3(filePath, { force: true });
+  await rm4(filePath, { force: true });
   console.log(`  Pruned orphaned file: ${file}`);
   return "pruned";
 }
-async function findMissingTrackedFiles(targetDir, components) {
+async function findMissingTrackedFiles(targetDir, components, scope = "repo") {
   const missing = [];
   for (const installed of components) {
     let component;
     try {
-      component = getComponent(installed.name);
+      component = componentForScope(getComponent(installed.name), scope);
     } catch {
       continue;
     }
     if (component.initOnly || component.skipExisting) continue;
     for (const file of installed.files) {
       if (!component.files.includes(file)) continue;
-      if (!await fileExists(join8(targetDir, file))) missing.push(file);
+      if (!await fileExists(join9(targetDir, file))) missing.push(file);
     }
   }
   return missing;
@@ -3648,46 +4150,70 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   } catch (err) {
     if (err instanceof ManifestNotFoundError) {
       console.error(
-        'Not initialized. Run "spell init" first before updating.'
+        `Not initialized. Run "spell init${options.user ? " --user" : ""}" first before updating.`
       );
       process.exit(1);
       return;
     }
     throw err;
   }
-  console.warn(
-    `WARNING: Arcane v${packageVersion} update safety notice: commit your work before updating.`
-  );
-  console.warn(
-    "Updates can replace managed files. A clean committed baseline is required for recovery."
-  );
-  const gitState = await inspectGitRepository(targetDir);
-  if (gitState.status === "not-repository") {
-    console.error(
-      "Update refused: this directory is not a Git repository or Git is unavailable."
-    );
+  const resolvedScope = resolveInstallScope(targetDir, manifest.scope, options.user);
+  if (resolvedScope.misplacedUserManifest) {
+    console.error(misplacedUserManifestMessage(targetDir));
     process.exit(1);
     return;
   }
-  if (gitState.status === "no-commits") {
-    console.error(
-      "Update refused: this repository has no commits. Commit the current baseline before updating."
+  const scope = resolvedScope.scope;
+  const homeDir = dirname4(targetDir);
+  if (scope === "repo") {
+    console.warn(
+      `WARNING: Arcane v${packageVersion} update safety notice: commit your work before updating.`
     );
-    process.exit(1);
-    return;
-  }
-  if (gitState.uncommittedChanges > 0) {
-    console.error(
-      `Update refused: this repository has ${gitState.uncommittedChanges} uncommitted change${gitState.uncommittedChanges === 1 ? "" : "s"}. Commit or otherwise clean the working tree before updating.`
+    console.warn(
+      "Updates can replace managed files. A clean committed baseline is required for recovery."
     );
-    process.exit(1);
-    return;
+    const gitState = await inspectGitRepository(targetDir);
+    if (gitState.status === "not-repository") {
+      console.error(
+        "Update refused: this directory is not a Git repository or Git is unavailable."
+      );
+      process.exit(1);
+      return;
+    }
+    if (gitState.status === "no-commits") {
+      console.error(
+        "Update refused: this repository has no commits. Commit the current baseline before updating."
+      );
+      process.exit(1);
+      return;
+    }
+    if (gitState.uncommittedChanges > 0) {
+      console.error(
+        `Update refused: this repository has ${gitState.uncommittedChanges} uncommitted change${gitState.uncommittedChanges === 1 ? "" : "s"}. Commit or otherwise clean the working tree before updating.`
+      );
+      process.exit(1);
+      return;
+    }
   }
   let sameVersionRestore = false;
   if (manifest.version === packageVersion && manifest.components.length > 0) {
-    const missing = await findMissingTrackedFiles(targetDir, manifest.components);
+    const missing = await findMissingTrackedFiles(targetDir, manifest.components, scope);
     if (missing.length === 0) {
       console.log("Already up to date.");
+      if (scope === "user") {
+        const fanout = await syncUserTierFanout({
+          homeDir,
+          storeRoot: targetDir,
+          spellIds: spellIdsInStore(manifest.components),
+          previous: manifest.fanout,
+          dryRun: options.dryRun,
+          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 });
+        }
+      }
       return;
     }
     sameVersionRestore = true;
@@ -3708,7 +4234,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   for (const installed of componentsToUpdate) {
     let component;
     try {
-      component = getComponent(installed.name);
+      component = componentForScope(getComponent(installed.name), scope);
     } catch (err) {
       if (err instanceof ComponentNotFoundError) {
         console.log(`  ! ${installed.name} not in registry \u2014 skipping.`);
@@ -3732,8 +4258,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     const updatedFiles = [];
     const fileHashes = {};
     for (const file of component.files) {
-      const srcPath = join8(assetsDir, component.sourceOverrides?.[file] ?? file);
-      const targetExists = await fileExists(join8(targetDir, file));
+      const srcPath = join9(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const targetExists = await fileExists(join9(targetDir, file));
       const preserveExisting = Boolean(component.skipExisting) && targetExists;
       const recordedHash = installed.fileHashes?.[file];
       if (component.initOnly && !targetExists) {
@@ -3753,7 +4279,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
           continue;
         }
       }
-      const editedByOperator = recordedHash !== void 0 && targetExists && !preserveExisting && await hashFile(join8(targetDir, file)) !== recordedHash;
+      const editedByOperator = recordedHash !== void 0 && targetExists && !preserveExisting && await hashFile(join9(targetDir, file)) !== recordedHash;
       if (preserveExisting) {
         console.log(`  ${options.dryRun ? "[dry-run] Would preserve" : "Preserved"}: ${file}`);
       } else if (editedByOperator && isClientShimPath(file)) {
@@ -3768,7 +4294,10 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       } else {
         let handled = false;
         if (editedByOperator) {
-          const oldVendorContent = await fetchPublishedFile(installed.installedVersion, file);
+          const oldVendorContent = await fetchPublishedFile(
+            installed.installedVersion,
+            component.sourceOverrides?.[file] ?? file
+          );
           if (oldVendorContent === void 0) {
             console.log(
               `  ! Could not fetch the previously published version of ${file} to merge your edits \u2014 left your version untouched. Update it manually if you want the latest.`
@@ -3777,11 +4306,11 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
             handled = true;
           } else {
             const [currentContent, newContent] = await Promise.all([
-              readFile6(join8(targetDir, file), "utf-8"),
-              readFile6(srcPath, "utf-8")
+              readFile7(join9(targetDir, file), "utf-8"),
+              readFile7(srcPath, "utf-8")
             ]);
             const result = merge3(oldVendorContent, currentContent, newContent);
-            await writeFile8(join8(targetDir, file), result.content, "utf-8");
+            await writeFile9(join9(targetDir, file), result.content, "utf-8");
             fileHashes[file] = await hashFile(srcPath);
             if (result.hasConflict) {
               conflictedFiles.push(file);
@@ -3803,7 +4332,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       }
     }
     for (const dir of component.directories ?? []) {
-      const srcDirPath = join8(assetsDir, dir);
+      const srcDirPath = join9(assetsDir, dir);
       if (options.dryRun) {
         console.log(`  [dry-run] Would update directory: ${dir}/`);
       } else {
@@ -3856,12 +4385,29 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
   Each keeps working in its client as-is. To converge: move your edits into the canonical spell (.arcane/spells/<id>.md \u2014 later updates merge edits there), delete the customized file, commit, and run \`spell update\` again \u2014 it restores the generated shim at the current version.`
     );
   }
+  let fanoutRecord;
+  if (scope === "user") {
+    const fanout = await syncUserTierFanout({
+      homeDir,
+      storeRoot: targetDir,
+      spellIds: spellIdsInStore(updatedComponents),
+      previous: manifest.fanout,
+      dryRun: options.dryRun,
+      // A dry run has restored nothing yet, so a missing store spell renders
+      // from the vendor asset the real run would write (review finding F1).
+      fallbackDir: assetsDir
+    });
+    const lines = describeFanoutOutcomes(fanout.outcomes, options.dryRun);
+    if (lines.length > 0) console.log();
+    for (const line of lines) console.log(`  ${line}`);
+    fanoutRecord = fanout.record;
+  }
   if (options.dryRun) {
     console.log(
       `
 [dry-run] Would update ${fileCount} files.`
     );
-    const applicableRetrofits = MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest));
+    const applicableRetrofits = scope === "repo" ? MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest)) : [];
     if (applicableRetrofits.length > 0) {
       console.log(
         `[dry-run] Would ask ${applicableRetrofits.length} manifest retrofit question${applicableRetrofits.length === 1 ? "" : "s"}: ${applicableRetrofits.map((r) => r.field).join(", ")}.`
@@ -3869,9 +4415,9 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
     }
     return;
   }
-  const interactive = Boolean(process.stdin.isTTY);
+  const interactive = Boolean(process.stdin.isTTY) && scope === "repo";
   const retrofitPatch = interactive ? await runManifestRetrofits(manifest) : {};
-  if (!interactive) {
+  if (!interactive && scope === "repo") {
     const pending = MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest));
     if (pending.length > 0) {
       console.log(
@@ -3883,7 +4429,8 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
     ...manifest,
     version: packageVersion,
     components: updatedComponents,
-    ...retrofitPatch
+    ...retrofitPatch,
+    ...fanoutRecord !== void 0 ? { fanout: fanoutRecord } : {}
   };
   await writeManifest(targetDir, updated);
   console.log(
@@ -3898,15 +4445,18 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
   Search for "<<<<<<< yours" and resolve before committing.`
     );
   }
-  if (manifest.role !== "hub" && updated.role === "hub") {
+  if (scope === "repo" && manifest.role !== "hub" && updated.role === "hub") {
     await offerRegistryScaffold(targetDir, updated.business_root ?? "ventures");
   }
 }
 
+// src/commands/status.ts
+import { dirname as dirname6 } from "path";
+
 // src/modules/version-check.ts
-import { readFile as readFile7, writeFile as writeFile9, mkdir as mkdir5 } from "fs/promises";
-import { dirname as dirname2, join as join9 } from "path";
-import { homedir as homedir2 } from "os";
+import { readFile as readFile8, writeFile as writeFile10, mkdir as mkdir6 } from "fs/promises";
+import { dirname as dirname5, join as join10 } from "path";
+import { homedir as homedir3 } from "os";
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
 function getFeedUrl() {
@@ -3919,11 +4469,11 @@ function getFeedUrl() {
   }
   return url;
 }
-var DEFAULT_CACHE_PATH = join9(homedir2(), ".arcane", "version-cache.json");
+var DEFAULT_CACHE_PATH = join10(homedir3(), ".arcane", "version-cache.json");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 async function readCache(cachePath) {
   try {
-    const content = await readFile7(cachePath, "utf-8");
+    const content = await readFile8(cachePath, "utf-8");
     const parsed = JSON.parse(content);
     if (typeof parsed.latest !== "string" || typeof parsed.checkedAt !== "string") {
       return null;
@@ -3934,9 +4484,9 @@ async function readCache(cachePath) {
   }
 }
 async function writeCache(cachePath, latest) {
-  await mkdir5(dirname2(cachePath), { recursive: true });
+  await mkdir6(dirname5(cachePath), { recursive: true });
   const entry = { latest, checkedAt: (/* @__PURE__ */ new Date()).toISOString() };
-  await writeFile9(cachePath, JSON.stringify(entry, null, 2), "utf-8");
+  await writeFile10(cachePath, JSON.stringify(entry, null, 2), "utf-8");
 }
 async function getLatestVersion(feedUrl) {
   const normalizedBase = feedUrl.endsWith("/") ? feedUrl : feedUrl + "/";
@@ -4015,20 +4565,27 @@ function generateVersionDriftDiagram(repoFilesVersion, installedCliVersion, npmL
 }
 
 // src/commands/status.ts
-async function runStatus(targetDir, packageVersion) {
+async function runStatus(targetDir, packageVersion, options = {}) {
   let manifest;
   try {
     manifest = await readManifest(targetDir);
   } catch (err) {
     if (err instanceof ManifestNotFoundError) {
       console.error(
-        'Not initialized. Run "spell init" first.'
+        `Not initialized. Run "spell init${options.user ? " --user" : ""}" first.`
       );
       process.exit(1);
       return;
     }
     throw err;
   }
+  const resolvedScope = resolveInstallScope(targetDir, manifest.scope, options.user);
+  if (resolvedScope.misplacedUserManifest) {
+    console.error(misplacedUserManifestMessage(targetDir));
+    process.exit(1);
+    return;
+  }
+  const scope = resolvedScope.scope;
   if (manifest.components.length === 0) {
     console.log("No components installed.");
     return;
@@ -4066,6 +4623,30 @@ async function runStatus(targetDir, packageVersion) {
     );
   }
   console.log("");
+  if (scope === "user") {
+    console.log(`  Scope: user \u2014 ${targetDir}`);
+    const health = await inspectUserTierFanout(dirname6(targetDir), manifest.fanout);
+    console.log(
+      `  Client files: ${health.total} (${health.byClient.codex} ${FANOUT_CLIENT_LABELS.codex}, ${health.byClient.claude} ${FANOUT_CLIENT_LABELS.claude})`
+    );
+    if (health.missing.length > 0 || health.customized.length > 0) {
+      const parts = [];
+      if (health.missing.length > 0) parts.push(`${health.missing.length} missing`);
+      if (health.customized.length > 0) parts.push(`${health.customized.length} customized`);
+      console.log(
+        `  ! ${parts.join(", ")} \u2014 \`spell update --user\` regenerates missing files; customized files are never overwritten.`
+      );
+    }
+  } else {
+    console.log("  Scope: repo");
+    try {
+      const store = userTierRoot();
+      const userManifest = await readManifest(store);
+      console.log(`  User tier: v${userManifest.version} at ${store} (spell status --user)`);
+    } catch {
+    }
+  }
+  console.log("");
   const latestStr = versionResult.error ? "unable to check" : versionResult.latest ?? manifest.version;
   let footer = `  Installed: ${packageVersion}  Latest: ${latestStr}`;
   if (versionResult.updateAvailable) {
@@ -4092,11 +4673,16 @@ async function runStatus(targetDir, packageVersion) {
       }
     }
   }
+  if (scope === "user") {
+    console.log("");
+    for (const line of VSCODE_USER_TIER_NOTE) console.log(`  ${line}`);
+    console.log(`  ${CLAUDE_PRECEDENCE_NOTE}`);
+  }
 }
 
 // src/commands/uninstall.ts
-import { rm as rm4 } from "fs/promises";
-import { join as join10 } from "path";
+import { rm as rm5 } from "fs/promises";
+import { dirname as dirname7, join as join11 } from "path";
 import { confirm as confirm3 } from "@inquirer/prompts";
 async function runUninstall(options, targetDir) {
   let manifest;
@@ -4104,12 +4690,22 @@ async function runUninstall(options, targetDir) {
     manifest = await readManifest(targetDir);
   } catch (err) {
     if (err instanceof ManifestNotFoundError) {
-      console.error('Not initialized. Run "spell init" first.');
+      console.error(`Not initialized. Run "spell init${options.user ? " --user" : ""}" first.`);
       process.exit(1);
       return;
     }
     throw err;
   }
+  const resolvedScope = resolveInstallScope(targetDir, manifest.scope, options.user);
+  if (resolvedScope.misplacedUserManifest) {
+    console.error(misplacedUserManifestMessage(targetDir));
+    process.exit(1);
+    return;
+  }
+  if (resolvedScope.scope === "user") {
+    await uninstallUserTier(options, targetDir, manifest);
+    return;
+  }
   const policy = manifest.push_policy ?? "open";
   const controlsInForce = await isHookEnforced(targetDir) || (await blockedRemotes(targetDir)).length > 0;
   if ((policy === "blocked" || controlsInForce) && !options.dryRun) {
@@ -4159,24 +4755,24 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
   let removed = 0;
   for (const component of manifest.components) {
     for (const file of component.files) {
-      const filePath = join10(targetDir, file);
+      const filePath = join11(targetDir, file);
       try {
-        await rm4(filePath, { force: true });
+        await rm5(filePath, { force: true });
         removed++;
       } catch {
       }
     }
   }
-  await rm4(join10(targetDir, ".arcane.json"), { force: true });
+  await rm5(join11(targetDir, ".arcane.json"), { force: true });
   const agentDirs = [
     ".github/agents",
     ".arcane/agents",
     ".arcane/generated"
   ];
   for (const dir of agentDirs) {
-    await rm4(join10(targetDir, dir), { recursive: true, force: true });
+    await rm5(join11(targetDir, dir), { recursive: true, force: true });
   }
-  await rm4(join10(targetDir, ".arcane/agents.yaml"), { force: true });
+  await rm5(join11(targetDir, ".arcane/agents.yaml"), { force: true });
   const markerFiles = [
     "CLAUDE.md",
     "AGENTS.md",
@@ -4192,10 +4788,63 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
   console.log(`
 \u2713 Uninstalled \u2014 ${removed} files removed.`);
 }
+async function uninstallUserTier(options, storeRoot, manifest) {
+  const homeDir = dirname7(storeRoot);
+  const storeFiles = manifest.components.flatMap((c) => c.files);
+  const recordedCount = Object.keys(manifest.fanout ?? {}).length;
+  if (options.dryRun) {
+    for (const file of storeFiles) console.log(`[dry-run] Would remove: ${storeRoot}/${file}`);
+    const preview = await syncUserTierFanout({
+      homeDir,
+      storeRoot,
+      spellIds: [],
+      previous: manifest.fanout,
+      dryRun: true
+    });
+    for (const line of describeFanoutOutcomes(preview.outcomes, true)) console.log(line);
+    console.log(`[dry-run] Would remove: ${storeRoot}/.arcane.json`);
+    console.log(
+      `
+[dry-run] ${storeFiles.length} spell(s), up to ${recordedCount} client file(s) + manifest would be removed from the user tier.`
+    );
+    return;
+  }
+  if (!options.yes) {
+    const confirmed = await confirm3({
+      message: `This will remove ${storeFiles.length} spells, ${recordedCount} client files and .arcane.json from the user tier at ${storeRoot}. Continue?`,
+      default: false
+    });
+    if (!confirmed) {
+      console.log("Uninstall cancelled.");
+      return;
+    }
+  }
+  const fanout = await syncUserTierFanout({
+    homeDir,
+    storeRoot,
+    spellIds: [],
+    previous: manifest.fanout
+  });
+  let removed = 0;
+  for (const file of storeFiles) {
+    await rm5(join11(storeRoot, file), { force: true });
+    removed++;
+  }
+  await rm5(join11(storeRoot, ".arcane.json"), { force: true });
+  await removeDirectoryIfEmpty(join11(storeRoot, USER_TIER_SPELLS_DIR));
+  await removeDirectoryIfEmpty(storeRoot);
+  for (const line of describeFanoutOutcomes(fanout.outcomes)) console.log(`  ${line}`);
+  const pruned = fanout.outcomes.filter((o) => o.status === "pruned").length;
+  const kept = fanout.outcomes.filter((o) => o.status === "kept-edited").length;
+  console.log(
+    `
+\u2713 Uninstalled the user tier \u2014 ${removed} spells and ${pruned} client files removed${kept > 0 ? `; ${kept} edited client file(s) kept` : ""}.`
+  );
+}
 
 // src/commands/doctor.ts
-import { access as access4, readFile as readFile9, mkdir as mkdir6, copyFile as fsCopyFile } from "fs/promises";
-import { join as join12, dirname as dirname3 } from "path";
+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 { execFile as execFile3 } from "child_process";
 import { promisify as promisify2 } from "util";
 
@@ -4265,8 +4914,8 @@ function evaluateIncidentGate(records) {
 }
 
 // src/modules/denylist-scan.ts
-import { readFile as readFile8, readdir as readdir5 } from "fs/promises";
-import { join as join11, relative } from "path";
+import { readFile as readFile9, readdir as readdir6 } from "fs/promises";
+import { join as join12, relative } from "path";
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -4283,7 +4932,7 @@ async function scanFile(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
   try {
-    content = await readFile8(absolutePath, "utf8");
+    content = await readFile9(absolutePath, "utf8");
   } catch {
     return findings;
   }
@@ -4312,12 +4961,12 @@ async function collectScannableFiles(root, repoRoot = root, extensions = DEFAULT
   const collected = [];
   let entries;
   try {
-    entries = await readdir5(root, { withFileTypes: true });
+    entries = await readdir6(root, { withFileTypes: true });
   } catch {
     return collected;
   }
   for (const entry of entries) {
-    const absolutePath = join11(root, entry.name);
+    const absolutePath = join12(root, entry.name);
     if (entry.isDirectory()) {
       if (SKIP_DIRECTORIES.has(entry.name)) continue;
       collected.push(...await collectScannableFiles(absolutePath, repoRoot, extensions));
@@ -4529,13 +5178,13 @@ async function checkVSCodeExtension(id, label) {
   const name = `VS Code extension: ${label}`;
   const home = process.env["HOME"] ?? "";
   const extDirs = [
-    join12(home, ".vscode", "extensions"),
-    join12(home, ".vscode-insiders", "extensions")
+    join13(home, ".vscode", "extensions"),
+    join13(home, ".vscode-insiders", "extensions")
   ];
   for (const dir of extDirs) {
     try {
-      const { readdir: readdir8 } = await import("fs/promises");
-      const entries = await readdir8(dir);
+      const { readdir: readdir9 } = await import("fs/promises");
+      const entries = await readdir9(dir);
       const prefix = id.toLowerCase() + "-";
       const found = entries.some(
         (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
@@ -4564,13 +5213,13 @@ async function checkVSCodeExtension(id, label) {
 }
 async function checkArcaneManifest(targetDir) {
   const name = "Arcane manifest (.arcane.json)";
-  const manifestPath2 = join12(targetDir, ".arcane.json");
+  const manifestPath2 = join13(targetDir, ".arcane.json");
   try {
     await access4(manifestPath2);
   } catch {
-    const selfHostedManifestPath = join12(targetDir, "src", "assets", ".arcane.json");
+    const selfHostedManifestPath = join13(targetDir, "src", "assets", ".arcane.json");
     try {
-      const raw = await readFile9(selfHostedManifestPath, "utf8");
+      const raw = await readFile10(selfHostedManifestPath, "utf8");
       const manifest = JSON.parse(raw);
       if (isRecord3(manifest) && manifest["selfHosted"] === true && manifest["tracking_mode"] === "internal") {
         return {
@@ -4589,7 +5238,7 @@ async function checkArcaneManifest(targetDir) {
     };
   }
   try {
-    const raw = await readFile9(manifestPath2, "utf8");
+    const raw = await readFile10(manifestPath2, "utf8");
     const manifest = JSON.parse(raw);
     if (!isRecord3(manifest) || typeof manifest["version"] !== "string" || !manifest["version"] || !Array.isArray(manifest["components"])) {
       return {
@@ -4674,7 +5323,7 @@ async function checkSessionContinuity(targetDir) {
   const results = [];
   for (const file of SESSION_CONTINUITY_FILES) {
     const name = `Session file: ${file}`;
-    const filePath = join12(targetDir, file);
+    const filePath = join13(targetDir, file);
     try {
       await access4(filePath);
       results.push({ name, passed: true, message: "present" });
@@ -4692,18 +5341,82 @@ async function checkSessionContinuity(targetDir) {
 async function fixSessionContinuity(targetDir, assetsDir) {
   const created = [];
   for (const file of SESSION_CONTINUITY_FILES) {
-    const destPath = join12(targetDir, file);
+    const destPath = join13(targetDir, file);
     try {
       await access4(destPath);
     } catch {
-      const srcPath = join12(assetsDir, file);
-      await mkdir6(dirname3(destPath), { recursive: true });
+      const srcPath = join13(assetsDir, file);
+      await mkdir7(dirname8(destPath), { recursive: true });
       await fsCopyFile(srcPath, destPath);
       created.push(file);
     }
   }
   return created;
 }
+async function checkUserTier(homeDir = resolveHomeDir(), cliVersion) {
+  const name = "User tier (ARC-045)";
+  const storeRoot = userTierRoot(homeDir);
+  let manifest;
+  try {
+    manifest = await readManifest(storeRoot);
+  } catch (err) {
+    if (err instanceof ManifestNotFoundError) {
+      return {
+        name,
+        passed: true,
+        blocking: false,
+        message: "no user tier installed (optional \u2014 `spell init --user` shares every spell across the repositories on this machine)"
+      };
+    }
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `could not read ${storeRoot}/.arcane.json (${err instanceof Error ? err.message : String(err)}) \u2014 remove it and re-run \`spell init --user\``
+    };
+  }
+  try {
+    if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+      return {
+        name,
+        passed: false,
+        blocking: false,
+        message: `${storeRoot}/.arcane.json has no version field \u2014 remove the store and re-run \`spell init --user\``
+      };
+    }
+    const majorMinor = (v) => v.split(".").slice(0, 2).join(".");
+    const problems = [];
+    if (cliVersion !== void 0 && majorMinor(manifest.version) !== majorMinor(cliVersion)) {
+      problems.push(`installed at v${manifest.version}, this CLI is v${cliVersion}`);
+    }
+    const health = await inspectUserTierFanout(homeDir, manifest.fanout);
+    if (health.missing.length > 0) {
+      problems.push(`${health.missing.length} of ${health.total} client file(s) missing`);
+    }
+    if (problems.length > 0) {
+      return {
+        name,
+        passed: false,
+        blocking: false,
+        message: `${problems.join("; ")} \u2014 run \`spell update --user\` (regenerates missing files; never overwrites edited ones)`
+      };
+    }
+    const customized = health.customized.length > 0 ? `, ${health.customized.length} customized` : "";
+    return {
+      name,
+      passed: true,
+      blocking: false,
+      message: `v${manifest.version} at ${storeRoot} \u2014 ${health.total} client file(s) in place${customized}`
+    };
+  } catch (err) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `could not inspect the user tier at ${storeRoot} (${err instanceof Error ? err.message : String(err)}) \u2014 run \`spell update --user\`; if that fails too, remove the store and re-run \`spell init --user\``
+    };
+  }
+}
 async function checkPushPolicy(targetDir) {
   const name = "Push policy (EF-09)";
   let manifest;
@@ -4757,10 +5470,10 @@ async function checkPushPolicy(targetDir) {
 }
 async function checkMcpConfig(targetDir) {
   const name = "MCP config (per-server timeout, I12)";
-  const filePath = join12(targetDir, ".mcp.json");
+  const filePath = join13(targetDir, ".mcp.json");
   let raw;
   try {
-    raw = await readFile9(filePath, "utf8");
+    raw = await readFile10(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no .mcp.json \u2014 nothing to check" };
   }
@@ -4813,10 +5526,10 @@ function isDelegationsFile(value) {
 }
 async function checkDelegations(targetDir) {
   const name = "Standing delegations (T13)";
-  const filePath = join12(targetDir, ".arcane", "delegations.json");
+  const filePath = join13(targetDir, ".arcane", "delegations.json");
   let raw;
   try {
-    raw = await readFile9(filePath, "utf8");
+    raw = await readFile10(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no delegations recorded" };
   }
@@ -4919,7 +5632,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkPushPolicy(targetDir),
     checkPlatformBranchPolicy(targetDir),
     checkDelegations(targetDir),
-    checkMcpConfig(targetDir)
+    checkMcpConfig(targetDir),
+    checkUserTier(resolveHomeDir(), options.packageVersion)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);
@@ -4964,16 +5678,16 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
 }
 
 // src/commands/ward.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 
 // src/modules/ward.ts
-import { readdir as readdir6, readFile as readFile10 } from "fs/promises";
-import { join as join13, relative as relative2 } from "path";
+import { readdir as readdir7, readFile as readFile11 } from "fs/promises";
+import { join as join14, relative as relative2 } from "path";
 async function scanFileAllRules(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
   try {
-    content = await readFile10(absolutePath, "utf8");
+    content = await readFile11(absolutePath, "utf8");
   } catch {
     return findings;
   }
@@ -5026,12 +5740,12 @@ async function scanFilenames(root, rules, repoRoot = root) {
   const findings = [];
   let entries;
   try {
-    entries = await readdir6(root, { withFileTypes: true });
+    entries = await readdir7(root, { withFileTypes: true });
   } catch {
     return findings;
   }
   for (const entry of entries) {
-    const absolutePath = join13(root, entry.name);
+    const absolutePath = join14(root, entry.name);
     if (entry.isDirectory()) {
       if (SKIP_DIRECTORIES.has(entry.name)) continue;
       findings.push(...await scanFilenames(absolutePath, rules, repoRoot));
@@ -5068,7 +5782,7 @@ async function runWard(repoRoot, options = {}) {
     const findings2 = await scanFileAllRules(absolutePath, displayPath, allRules);
     if (findings2.length > 0) {
       try {
-        fileLines.set(displayPath, (await readFile10(absolutePath, "utf8")).split("\n"));
+        fileLines.set(displayPath, (await readFile11(absolutePath, "utf8")).split("\n"));
       } catch {
       }
     }
@@ -5096,7 +5810,7 @@ function parseTermsFileContent(raw) {
 }
 async function readTermsFile(filePath) {
   try {
-    return parseTermsFileContent(await readFile11(filePath, "utf8"));
+    return parseTermsFileContent(await readFile12(filePath, "utf8"));
   } catch (error) {
     console.warn(
       `\u26A0 arcane: could not read --terms-file "${filePath}": ${error.message}`
@@ -5146,7 +5860,7 @@ async function runWardCli(targetDir, options = {}, exclusions = []) {
 }
 
 // src/commands/unblock-push.ts
-import { basename as basename2, resolve as resolve2 } from "path";
+import { basename as basename2, resolve as resolve3 } from "path";
 import { input as input4 } from "@inquirer/prompts";
 async function runUnblockPush(targetDir) {
   let manifest;
@@ -5178,7 +5892,7 @@ async function runUnblockPush(targetDir) {
     process.exit(1);
     return;
   }
-  const repoName = basename2(resolve2(targetDir));
+  const repoName = basename2(resolve3(targetDir));
   if (repoName === "") {
     console.error(
       "Could not determine a repository name to confirm against (is this repository at a filesystem root?). Refusing to unblock."
@@ -5245,15 +5959,15 @@ Name did not match ("${typed.trim()}" \u2260 "${repoName}"). Nothing changed.`);
 
 // src/commands/report.ts
 import { access as access5 } from "fs/promises";
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 
 // src/modules/show-report/generate.ts
-import { mkdir as mkdir7, readdir as readdir7, readFile as readFile13, writeFile as writeFile10 } from "fs/promises";
-import { basename as basename3, dirname as dirname4, isAbsolute, join as join15, relative as relative3, resolve as resolve3 } from "path";
+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";
 
 // src/modules/show-report/model.ts
-import { readFile as readFile12 } from "fs/promises";
-import { join as join14 } from "path";
+import { readFile as readFile13 } from "fs/promises";
+import { join as join15 } from "path";
 
 // src/modules/show-report/plan-parser.ts
 function parseFrontmatter(content) {
@@ -5521,7 +6235,7 @@ async function getCast(cwd, fromRef, toRef) {
 // src/modules/show-report/model.ts
 async function readOptional(path4) {
   try {
-    return await readFile12(path4, "utf8");
+    return await readFile13(path4, "utf8");
   } catch {
     return null;
   }
@@ -5617,13 +6331,13 @@ function buildCorrections(ledgerRows, programName) {
   };
 }
 async function buildShowReportModel(options) {
-  const planAbsPath = join14(options.rootDir, options.planRelPath);
-  const queueAbsPath = join14(options.rootDir, options.queueRelPath);
+  const planAbsPath = join15(options.rootDir, options.planRelPath);
+  const queueAbsPath = join15(options.rootDir, options.queueRelPath);
   const ledgerRelPath = "docs/verification-ledger.md";
-  const ledgerAbsPath = join14(options.rootDir, ledgerRelPath);
-  const decisionsAbsPath = join14(options.rootDir, "DECISIONS.md");
+  const ledgerAbsPath = join15(options.rootDir, ledgerRelPath);
+  const decisionsAbsPath = join15(options.rootDir, "DECISIONS.md");
   const [planContent, queueContent, ledgerContent, decisionsContent] = await Promise.all([
-    readFile12(planAbsPath, "utf8"),
+    readFile13(planAbsPath, "utf8"),
     readOptional(queueAbsPath),
     readOptional(ledgerAbsPath),
     readOptional(decisionsAbsPath)
@@ -5786,7 +6500,7 @@ function toPosix(path4) {
 async function programFromPlan(rootDir, slug, planRelPath) {
   let planContent;
   try {
-    planContent = await readFile13(join15(rootDir, planRelPath), "utf8");
+    planContent = await readFile14(join16(rootDir, planRelPath), "utf8");
   } catch {
     return { skipped: { slug, reason: `no PLAN.md at ${planRelPath}` } };
   }
@@ -5798,16 +6512,16 @@ async function programFromPlan(rootDir, slug, planRelPath) {
     program: {
       slug,
       planRelPath,
-      queueRelPath: toPosix(join15(dirname4(planRelPath), "OPERATOR-QUEUE.md")),
+      queueRelPath: toPosix(join16(dirname9(planRelPath), "OPERATOR-QUEUE.md")),
       ledgerProgramName: programNameFromTitle(frontmatter.title ?? slug)
     }
   };
 }
 async function discoverPrograms(rootDir) {
-  const plansDir = join15(rootDir, "docs", "plans");
+  const plansDir = join16(rootDir, "docs", "plans");
   let entries;
   try {
-    entries = (await readdir7(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
+    entries = (await readdir8(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
   } catch (error) {
     if (error.code === "ENOENT") return { programs: [], skipped: [] };
     throw error;
@@ -5822,23 +6536,23 @@ async function discoverPrograms(rootDir) {
   return { programs, skipped };
 }
 async function programFromPlanPath(rootDir, planPath) {
-  const planAbs = isAbsolute(planPath) ? planPath : resolve3(rootDir, planPath);
+  const planAbs = isAbsolute(planPath) ? planPath : resolve4(rootDir, planPath);
   const planRelPath = toPosix(relative3(rootDir, planAbs));
-  return programFromPlan(rootDir, basename3(dirname4(planAbs)), planRelPath);
+  return programFromPlan(rootDir, basename3(dirname9(planAbs)), planRelPath);
 }
 function normalizeLineEndings(content) {
   return content.replace(/\r\n?/g, "\n");
 }
 async function readOptionalFile(path4) {
   try {
-    return await readFile13(path4, "utf8");
+    return await readFile14(path4, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw error;
   }
 }
 async function generateReport(rootDir, program2, templateHtml) {
-  const planContent = await readFile13(join15(rootDir, program2.planRelPath), "utf8");
+  const planContent = await readFile14(join16(rootDir, program2.planRelPath), "utf8");
   const frontmatter = parseFrontmatter(planContent);
   const model = await buildShowReportModel({
     rootDir,
@@ -5856,7 +6570,7 @@ async function generateReport(rootDir, program2, templateHtml) {
   };
 }
 async function runReportGeneration(options) {
-  const templateHtml = await readFile13(options.templatePath, "utf8");
+  const templateHtml = await readFile14(options.templatePath, "utf8");
   const drifted = [];
   const repaired = [];
   const unwritten = [];
@@ -5864,19 +6578,19 @@ 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 : resolve3(options.rootDir, options.outDir) : resolve3(options.rootDir, dirname4(program2.planRelPath));
+    const outAbs = options.outDir ? isAbsolute(options.outDir) ? options.outDir : resolve4(options.rootDir, options.outDir) : resolve4(options.rootDir, dirname9(program2.planRelPath));
     const outRel = toPosix(relative3(options.rootDir, outAbs));
     const outputs = [
       [`${outRel}/show-report.json`, generated.json],
       [`${outRel}/show-report.html`, generated.html]
     ];
     for (const [relPath, expected] of outputs) {
-      const actual = await readOptionalFile(join15(options.rootDir, relPath));
+      const actual = await readOptionalFile(join16(options.rootDir, relPath));
       if (actual === null || normalizeLineEndings(actual) !== normalizeLineEndings(expected)) {
         drifted.push(`${relPath} does not match a regeneration from its sources.`);
         if (options.mode === "write") {
-          await mkdir7(outAbs, { recursive: true });
-          await writeFile10(join15(options.rootDir, relPath), expected, "utf8");
+          await mkdir8(outAbs, { recursive: true });
+          await writeFile11(join16(options.rootDir, relPath), expected, "utf8");
           repaired.push(relPath);
         }
       }
@@ -5887,7 +6601,7 @@ async function runReportGeneration(options) {
 
 // src/commands/report.ts
 async function runReport(targetDir, options = {}, assetsDir) {
-  const templatePath = join16(assetsDir, "report", "show-report.template.html");
+  const templatePath = join17(assetsDir, "report", "show-report.template.html");
   try {
     await access5(templatePath);
   } catch {
@@ -5950,8 +6664,12 @@ 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"] ?? join17(dirname5(fileURLToPath(import.meta.url)), "assets");
+var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join18(dirname10(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)";
+function targetDirFor(opts) {
+  return opts.user ? userTierRoot() : process.cwd();
+}
 program.name("spell").description("Arcane framework CLI \u2014 scaffold and manage governance files").version(pkg.version).action(async () => {
   if (program.args.length > 0) {
     const [attempted] = program.args;
@@ -5971,15 +6689,16 @@ program.name("spell").description("Arcane framework CLI \u2014 scaffold and mana
   await printWelcome(pkg.version, process.cwd());
   program.outputHelp();
 });
-program.command("init").description("Scaffold Arcane framework files into the current repository").option("--profile <profile>", "Profile: full | lite | methodology | docs | governance-only").option("--force", "Overwrite existing files without error").option("--dry-run", "Preview what would be installed without making changes").action(
+program.command("init").description("Scaffold Arcane framework files into the current repository").option("--profile <profile>", "Profile: full | lite | methodology | docs | governance-only").option("--force", "Overwrite existing files without error").option("--dry-run", "Preview what would be installed without making changes").option("--user", USER_FLAG_DESCRIPTION).action(
   async (opts) => {
     await runInit(
       {
         profile: opts.profile,
         force: opts.force,
-        dryRun: opts.dryRun
+        dryRun: opts.dryRun,
+        user: opts.user
       },
-      process.cwd(),
+      targetDirFor(opts),
       ASSETS_DIR,
       pkg.version
     );
@@ -5999,25 +6718,29 @@ 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"
-).action(async (opts) => {
+).option("--user", USER_FLAG_DESCRIPTION).action(async (opts) => {
   await runUpdate(
-    { dryRun: opts.dryRun, prune: opts.prune },
-    process.cwd(),
+    { dryRun: opts.dryRun, prune: opts.prune, user: opts.user },
+    targetDirFor(opts),
     ASSETS_DIR,
     pkg.version
   );
 });
-program.command("status").description("Show installed components and check for updates").action(async () => {
-  await runStatus(process.cwd(), pkg.version);
+program.command("status").description("Show installed components and check for updates").option("--user", USER_FLAG_DESCRIPTION).action(async (opts) => {
+  await runStatus(targetDirFor(opts), pkg.version, { user: opts.user });
 });
-program.command("uninstall").description("Remove all installed Arcane framework files").option("--yes", "Skip confirmation prompt").option("--dry-run", "Preview what would be removed without deleting files").action(async (opts) => {
-  await runUninstall({ yes: opts.yes, dryRun: opts.dryRun }, process.cwd());
+program.command("uninstall").description("Remove all installed Arcane framework files").option("--yes", "Skip confirmation prompt").option("--dry-run", "Preview what would be removed without deleting files").option("--user", USER_FLAG_DESCRIPTION).action(async (opts) => {
+  await runUninstall({ yes: opts.yes, dryRun: opts.dryRun, user: opts.user }, targetDirFor(opts));
 });
 program.command("unblock-push").description("Lift this repository's push block (interactive terminal only)").action(async () => {
   await runUnblockPush(process.cwd());
 });
 program.command("doctor").description("Check your environment for Arcane prerequisites").option("--fix", "Automatically create missing session continuity files").option("--leaks", "Run only the on-demand secrets/credential scan (ARC-037), skipping the default checks").action(async (opts) => {
-  await runDoctor(process.cwd(), { fix: opts.fix, leaks: opts.leaks }, ASSETS_DIR);
+  await runDoctor(
+    process.cwd(),
+    { fix: opts.fix, leaks: opts.leaks, packageVersion: pkg.version },
+    ASSETS_DIR
+  );
 });
 program.command("ward").description("Scan the repo for leaked identifiers -- third-party trademarks and the operator's own personal identifiers alike (T18)").option(
   "--terms <terms>",