arcane-cli 0.17.0 → 0.19.0

package/dist/index.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from "url";
 import { dirname as dirname3, join as join11 } from "path";
 
 // src/commands/init.ts
-import { select as select2, confirm } from "@inquirer/prompts";
+import { select as select2, confirm, input as input2 } from "@inquirer/prompts";
 import { join as join4 } from "path";
 import chalk2 from "chalk";
 
@@ -98,6 +98,19 @@ var ManifestInvalidFieldError = class extends Error {
 var MANIFEST_FILE = ".arcane.json";
 var VALID_TRACKING_MODES = ["internal", "external"];
 var VALID_EXTERNAL_PROVIDERS = ["ado", "jira", "other"];
+var VALID_CONTENT_SENSITIVITY = ["standard", "sensitive"];
+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
+  // keep it a single path-shaped token rather than a multi-line payload.
+  /[\r\n\0]/.test(value);
+  return !invalid;
+}
+function validateSubjectRoot(value, filePath) {
+  if (!isValidSubjectRoot(value)) {
+    throw new ManifestInvalidFieldError(filePath, "subject_root", value);
+  }
+}
 function manifestPath(targetDir) {
   return path2.join(targetDir, MANIFEST_FILE);
 }
@@ -108,6 +121,19 @@ function validateTrackingFields(manifest, filePath) {
   if (manifest.external_provider !== void 0 && manifest.external_provider !== null && !VALID_EXTERNAL_PROVIDERS.includes(manifest.external_provider)) {
     throw new ManifestInvalidFieldError(filePath, "external_provider", manifest.external_provider);
   }
+  if (manifest.content_sensitivity !== void 0 && !VALID_CONTENT_SENSITIVITY.includes(manifest.content_sensitivity)) {
+    throw new ManifestInvalidFieldError(
+      filePath,
+      "content_sensitivity",
+      manifest.content_sensitivity
+    );
+  }
+  if (manifest.subject_root !== void 0 && manifest.subject_root !== null) {
+    if (typeof manifest.subject_root !== "string") {
+      throw new ManifestInvalidFieldError(filePath, "subject_root", manifest.subject_root);
+    }
+    validateSubjectRoot(manifest.subject_root, filePath);
+  }
 }
 async function readManifest(targetDir) {
   const filePath = manifestPath(targetDir);
@@ -155,15 +181,35 @@ var PROFILE_CONFIGS = [
     id: "lite",
     displayName: "Essentials",
     description: "Spells + core governance \u2014 fast start",
-    components: ["spell-prompts", "claude-commands", "agent-output-instructions", "git-conventions", "testing-standards", "framework-decisions", "session-continuity"]
+    components: [
+      "spells-session",
+      "spells-capture",
+      "spells-delivery",
+      "spells-review",
+      "spells-planning",
+      "spells-build",
+      "spells-venture",
+      "spells-meta",
+      "agent-output-instructions",
+      "git-conventions",
+      "testing-standards",
+      "framework-decisions",
+      "session-continuity"
+    ]
   },
   {
     id: "methodology",
     displayName: "Methodology Suite",
     description: "Spells + governance \u2014 full methodology without security/infra docs",
     components: [
-      "spell-prompts",
-      "claude-commands",
+      "spells-session",
+      "spells-capture",
+      "spells-delivery",
+      "spells-review",
+      "spells-planning",
+      "spells-build",
+      "spells-venture",
+      "spells-meta",
       "agent-output-instructions",
       "git-conventions",
       "testing-standards",
@@ -175,6 +221,44 @@ var PROFILE_CONFIGS = [
       "spell-authoring-standards"
     ]
   },
+  {
+    id: "docs",
+    displayName: "Docs / Records",
+    description: "Documentation and records repositories \u2014 no code, test, or deployment workflows",
+    components: [
+      // Deliberate exclusions, per docs-mode PRD MH-01: "spells-build"
+      // (implementation, tests, stack experts, release, deployment, PRD
+      // enchantment, asset tooling), "spells-review" (adversarial CODE review
+      // -- its own workflow validates test coverage against source, which a
+      // docs repo has neither of), and "spells-venture" (hub-only).
+      //
+      // MH-01 requires every retained spell to complete its core workflow
+      // without source code, tests, CI, or an external tracker. Asserted --
+      // exclusions included, which MH-01 requires explicitly -- in
+      // test/docs-profile-registry-split.test.ts.
+      "spells-session",
+      "spells-capture",
+      "spells-delivery",
+      "spells-planning",
+      "spells-meta",
+      "spells-docs",
+      "docs-baseline",
+      "records-conventions",
+      "agent-output-instructions",
+      "git-conventions",
+      // Four retained docs spells link to agent-policies; it carries no code
+      // implication, so shipping it closes a dangling reference cheaply.
+      "agent-policies",
+      "framework-decisions",
+      "session-continuity",
+      "decision-documentation-standard",
+      "agent-work-queue-model",
+      "development-methodology",
+      "naming-conventions",
+      "universal-agent-rules",
+      "spell-authoring-standards"
+    ]
+  },
   {
     id: "governance-only",
     displayName: "Governance Only",
@@ -323,46 +407,159 @@ var COMPONENTS = [
     description: "Copilot enforcement rules: PR link format, merge strategy, and branch naming",
     files: [".github/instructions/agent-output.instructions.md"]
   },
-  // Spell prompts — installed to .github/prompts/ (VS Code Copilot convention)
+  // Repository baseline files (EF-10 + EF-17). skipExisting: these are
+  // user-owned once written -- a repo with its own .gitattributes has an
+  // intentional policy Arcane must not overwrite. Sources are stored under a
+  // non-dotfile path and mapped via sourceOverrides; see RegistryComponent.
+  {
+    name: "docs-baseline",
+    description: "Line-ending and binary-format baseline for document repositories (.gitattributes/.gitignore)",
+    files: [".gitattributes", ".gitignore"],
+    sourceOverrides: {
+      ".gitattributes": "docs-baseline/gitattributes",
+      ".gitignore": "docs-baseline/gitignore"
+    },
+    skipExisting: true,
+    initOnly: true
+  },
+  {
+    name: "records-conventions",
+    description: "Supersession, tombstone, and retention conventions for records repositories",
+    files: [".arcane/governance/records-conventions.md"]
+  },
+  // ─── Spells ────────────────────────────────────────────────────────────────
+  // Split from the former monolithic `spell-prompts` + `claude-commands` pair
+  // so a profile can select spells by capability (see ARC-0NN). Grouping lives
+  // here and only here -- every spell file stays flat and unrenamed on disk.
+  //
+  // Each component carries BOTH client formats of the same spell: the Copilot
+  // prompt (.github/prompts/*.prompt.md) and the Claude Code wrapper
+  // (.claude/commands/*.md). They are never independently selectable -- every
+  // profile that wanted one always wanted the other -- and pairing them here
+  // makes it structurally impossible for the two formats of one spell to drift
+  // apart across profiles.
   {
-    name: "spell-prompts",
-    description: "Full Arcane spell prompt library (34 spells)",
+    name: "spells-session",
+    description: "Session lifecycle \u2014 open, close, commit, status, version",
     files: [
+      ".github/prompts/spell-open-session.prompt.md",
+      ".claude/commands/spell-open-session.md",
+      ".github/prompts/spell-close-session.prompt.md",
+      ".claude/commands/spell-close-session.md",
+      ".github/prompts/spell-commit-work.prompt.md",
+      ".claude/commands/spell-commit-work.md",
+      ".github/prompts/spell-status.prompt.md",
+      ".claude/commands/spell-status.md",
       ".github/prompts/spell-arcane-version.prompt.md",
-      ".github/prompts/spell-architect.prompt.md",
+      ".claude/commands/spell-arcane-version.md"
+    ]
+  },
+  {
+    name: "spells-capture",
+    description: "Idea, todo, feedback and explanation capture",
+    files: [
+      ".github/prompts/spell-save-idea.prompt.md",
+      ".claude/commands/spell-save-idea.md",
+      ".github/prompts/spell-todo.prompt.md",
+      ".claude/commands/spell-todo.md",
+      ".github/prompts/spell-feedback.prompt.md",
+      ".claude/commands/spell-feedback.md",
+      ".github/prompts/spell-suggest-feature.prompt.md",
+      ".claude/commands/spell-suggest-feature.md",
+      ".github/prompts/spell-document.prompt.md",
+      ".claude/commands/spell-document.md",
       ".github/prompts/spell-brainstorm.prompt.md",
+      ".claude/commands/spell-brainstorm.md",
+      ".github/prompts/spell-explain-concept.prompt.md",
+      ".claude/commands/spell-explain-concept.md"
+    ]
+  },
+  {
+    name: "spells-delivery",
+    description: "Pull-request lifecycle \u2014 open a PR, respond to review feedback",
+    files: [
+      ".github/prompts/spell-create-pull-request.prompt.md",
+      ".claude/commands/spell-create-pull-request.md",
+      ".github/prompts/spell-address-review.prompt.md",
+      ".claude/commands/spell-address-review.md"
+    ]
+  },
+  {
+    name: "spells-review",
+    description: "Adversarial code review \u2014 requires source and tests, so excluded from docs-only profiles",
+    files: [
+      ".github/prompts/spell-review.prompt.md",
+      ".claude/commands/spell-review.md",
+      ".github/prompts/spell-review-batch.prompt.md",
+      ".claude/commands/spell-review-batch.md"
+    ]
+  },
+  {
+    name: "spells-planning",
+    description: "PRD, architecture, scoping and product review",
+    files: [
+      ".github/prompts/spell-plan.prompt.md",
+      ".claude/commands/spell-plan.md",
+      ".github/prompts/spell-architect.prompt.md",
+      ".claude/commands/spell-architect.md",
       ".github/prompts/spell-scope.prompt.md",
-      ".github/prompts/spell-summon-venture.prompt.md",
+      ".claude/commands/spell-scope.md",
+      ".github/prompts/spell-product-review.prompt.md",
+      ".claude/commands/spell-product-review.md"
+    ]
+  },
+  {
+    name: "spells-build",
+    description: "Code and product delivery \u2014 implementation, tests, stack experts, release, deployment, asset tooling",
+    files: [
+      ".github/prompts/spell-implement.prompt.md",
+      ".claude/commands/spell-implement.md",
+      ".github/prompts/spell-test.prompt.md",
+      ".claude/commands/spell-test.md",
+      ".github/prompts/spell-full-cycle.prompt.md",
+      ".claude/commands/spell-full-cycle.md",
       ".github/prompts/spell-bug.prompt.md",
+      ".claude/commands/spell-bug.md",
       ".github/prompts/spell-bump.prompt.md",
-      ".github/prompts/spell-check-drift.prompt.md",
-      ".github/prompts/spell-close-session.prompt.md",
-      ".github/prompts/spell-commit-work.prompt.md",
+      ".claude/commands/spell-bump.md",
       ".github/prompts/spell-dotnet-expert.prompt.md",
-      ".github/prompts/spell-enchant.prompt.md",
-      ".github/prompts/spell-explain-concept.prompt.md",
-      ".github/prompts/spell-full-cycle.prompt.md",
-      ".github/prompts/spell-generate-bot-icons.prompt.md",
-      ".github/prompts/spell-implement.prompt.md",
-      ".github/prompts/spell-open-session.prompt.md",
-      ".github/prompts/spell-plan.prompt.md",
-      ".github/prompts/spell-present-arcane.prompt.md",
-      ".github/prompts/spell-product-review.prompt.md",
-      ".github/prompts/spell-review.prompt.md",
+      ".claude/commands/spell-dotnet-expert.md",
       ".github/prompts/spell-security-review.prompt.md",
+      ".claude/commands/spell-security-review.md",
       ".github/prompts/spell-ship.prompt.md",
-      ".github/prompts/spell-suggest-feature.prompt.md",
-      ".github/prompts/spell-test.prompt.md",
-      ".github/prompts/spell-todo.prompt.md",
-      // Workflow spell additions — PR lifecycle, status, capture, feedback
-      ".github/prompts/spell-address-review.prompt.md",
-      ".github/prompts/spell-create-pull-request.prompt.md",
-      ".github/prompts/spell-document.prompt.md",
-      ".github/prompts/spell-feedback.prompt.md",
+      ".claude/commands/spell-ship.md",
+      ".github/prompts/spell-enchant.prompt.md",
+      ".claude/commands/spell-enchant.md",
+      ".github/prompts/spell-generate-bot-icons.prompt.md",
+      ".claude/commands/spell-generate-bot-icons.md"
+    ]
+  },
+  {
+    name: "spells-docs",
+    description: "Documentation and records workflows \u2014 adopt an existing document tree",
+    files: [
+      ".github/prompts/spell-adopt-docs.prompt.md",
+      ".claude/commands/spell-adopt-docs.md"
+    ]
+  },
+  {
+    name: "spells-venture",
+    description: "Hub-only venture management",
+    files: [
+      ".github/prompts/spell-summon-venture.prompt.md",
+      ".claude/commands/spell-summon-venture.md",
       ".github/prompts/spell-manifest.prompt.md",
-      ".github/prompts/spell-save-idea.prompt.md",
-      ".github/prompts/spell-status.prompt.md",
-      ".github/prompts/spell-review-batch.prompt.md"
+      ".claude/commands/spell-manifest.md"
+    ]
+  },
+  {
+    name: "spells-meta",
+    description: "Arcane-about-Arcane \u2014 presentation and documentation drift detection",
+    files: [
+      ".github/prompts/spell-present-arcane.prompt.md",
+      ".claude/commands/spell-present-arcane.md",
+      ".github/prompts/spell-check-drift.prompt.md",
+      ".claude/commands/spell-check-drift.md"
     ]
   },
   // Templates
@@ -396,53 +593,11 @@ var COMPONENTS = [
     name: "agent-definitions",
     description: "Agent policy reference template (for governance-only setups \u2014 use `spell agents init` for the full agent system)",
     files: [".arcane/agents/agent-policies-template.md"]
-  },
+  }
   // NOTE: the static `agent-files` component was retired — `.github/agents/*.agent.md`
   // files are generated per-roster by `spell agents init` / `spell agents sync`, so
   // installing a fixed-name set via `spell init` shipped stale names and collided
   // with the generated output.
-  // Claude commands
-  {
-    name: "claude-commands",
-    description: "Claude Code slash command wrappers for all 34 Arcane spells",
-    files: [
-      ".claude/commands/spell-arcane-version.md",
-      ".claude/commands/spell-architect.md",
-      ".claude/commands/spell-brainstorm.md",
-      ".claude/commands/spell-scope.md",
-      ".claude/commands/spell-summon-venture.md",
-      ".claude/commands/spell-bug.md",
-      ".claude/commands/spell-bump.md",
-      ".claude/commands/spell-check-drift.md",
-      ".claude/commands/spell-close-session.md",
-      ".claude/commands/spell-commit-work.md",
-      ".claude/commands/spell-dotnet-expert.md",
-      ".claude/commands/spell-enchant.md",
-      ".claude/commands/spell-explain-concept.md",
-      ".claude/commands/spell-full-cycle.md",
-      ".claude/commands/spell-generate-bot-icons.md",
-      ".claude/commands/spell-implement.md",
-      ".claude/commands/spell-open-session.md",
-      ".claude/commands/spell-plan.md",
-      ".claude/commands/spell-present-arcane.md",
-      ".claude/commands/spell-product-review.md",
-      ".claude/commands/spell-review.md",
-      ".claude/commands/spell-security-review.md",
-      ".claude/commands/spell-ship.md",
-      ".claude/commands/spell-suggest-feature.md",
-      ".claude/commands/spell-test.md",
-      ".claude/commands/spell-todo.md",
-      // Workflow spell additions — PR lifecycle, status, capture, feedback
-      ".claude/commands/spell-address-review.md",
-      ".claude/commands/spell-create-pull-request.md",
-      ".claude/commands/spell-document.md",
-      ".claude/commands/spell-feedback.md",
-      ".claude/commands/spell-manifest.md",
-      ".claude/commands/spell-save-idea.md",
-      ".claude/commands/spell-status.md",
-      ".claude/commands/spell-review-batch.md"
-    ]
-  }
 ];
 function buildProfileMap() {
   const allNames = COMPONENTS.map((c) => c.name);
@@ -454,6 +609,23 @@ function buildProfileMap() {
 }
 var PROFILE_MAP = buildProfileMap();
 var componentIndex = new Map(COMPONENTS.map((c) => [c.name, c]));
+var SPELL_COMPONENT_NAMES = COMPONENTS.map((c) => c.name).filter(
+  (n) => n.startsWith("spells-")
+);
+var LEGACY_MONOLITH_REPLACEMENTS = [
+  "spells-session",
+  "spells-capture",
+  "spells-delivery",
+  "spells-review",
+  "spells-planning",
+  "spells-build",
+  "spells-venture",
+  "spells-meta"
+];
+var LEGACY_COMPONENT_MIGRATIONS = Object.assign(/* @__PURE__ */ Object.create(null), {
+  "spell-prompts": LEGACY_MONOLITH_REPLACEMENTS,
+  "claude-commands": LEGACY_MONOLITH_REPLACEMENTS
+});
 function getComponent(name) {
   const component = componentIndex.get(name);
   if (!component) {
@@ -1662,6 +1834,8 @@ var READ_SUBCOMMANDS = /* @__PURE__ */ new Set([
   "ls-files",
   "ls-tree",
   "symbolic-ref",
+  "show-ref",
+  "for-each-ref",
   "merge-base",
   "blame",
   "shortlog",
@@ -1788,10 +1962,25 @@ async function correctUnbornMasterDefault(cwd) {
     return { corrected: false, to: "main" };
   } catch {
   }
+  let mainRef;
   try {
-    await runGit(cwd, ["rev-parse", "--verify", "refs/heads/main"]);
-    return { corrected: false, to: "main" };
+    mainRef = await runGit(cwd, ["for-each-ref", "--format=%(objectname)", "refs/heads/main"]);
   } catch {
+    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+  }
+  if (mainRef.stdout.trim() !== "") {
+    return { corrected: false, to: "main" };
+  }
+  if (mainRef.stderr.trim() !== "") {
+    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+  }
+  try {
+    await runGit(cwd, ["symbolic-ref", "-q", "refs/heads/main"]);
+    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+  } catch (error) {
+    if (error.code !== 1) {
+      return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+    }
   }
   await runGit(cwd, ["symbolic-ref", "HEAD", "refs/heads/main"]);
   return { corrected: true, from: current, to: "main" };
@@ -1820,27 +2009,28 @@ async function ensureLocalPullRebase(cwd) {
 }
 
 // src/commands/init.ts
-var VALID_PROFILES = ["full", "lite", "governance-only", "methodology"];
+var VALID_PROFILES = ["full", "lite", "governance-only", "methodology", "docs"];
+var PROFILE_ICONS = {
+  full: "\u{1F9D9}",
+  lite: "\u26A1",
+  docs: "\u{1F4D6}"
+};
+function isSpellComponent(name) {
+  return name.startsWith("spells-");
+}
 function categorizeComponents(components) {
   const groups = [];
-  const prompts = components.find((c) => c.name === "spell-prompts");
-  if (prompts) {
-    groups.push({
-      icon: "\u2728",
-      label: "Copilot Spells",
-      count: prompts.files.length
-    });
+  const spellFiles = components.filter((c) => isSpellComponent(c.name)).flatMap((c) => c.files);
+  const promptCount = spellFiles.filter((f) => f.startsWith(".github/prompts/")).length;
+  if (promptCount > 0) {
+    groups.push({ icon: "\u2728", label: "Copilot Spells", count: promptCount });
   }
-  const claude = components.find((c) => c.name === "claude-commands");
-  if (claude) {
-    groups.push({
-      icon: "\u26A1",
-      label: "Claude Spells",
-      count: claude.files.length
-    });
+  const claudeCount = spellFiles.filter((f) => f.startsWith(".claude/commands/")).length;
+  if (claudeCount > 0) {
+    groups.push({ icon: "\u26A1", label: "Claude Spells", count: claudeCount });
   }
   const governance = components.filter(
-    (c) => c.name !== "spell-prompts" && c.name !== "claude-commands" && c.name !== "venture-template" && c.name !== "agent-definitions" && c.files.some((f) => f.startsWith(".arcane/governance/"))
+    (c) => !isSpellComponent(c.name) && c.name !== "venture-template" && c.name !== "agent-definitions" && c.files.some((f) => f.startsWith(".arcane/governance/"))
   );
   if (governance.length > 0) {
     groups.push({
@@ -1907,6 +2097,10 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
           printInfo(
             `Repointed the unborn branch from "${correction.from}" to "${correction.to}" (avoids the Git for Windows default-branch trap).`
           );
+        } else if (correction.blockedReason === "target-unreadable") {
+          printWarning(
+            'This repo\'s "main" branch ref exists but could not be read (broken ref). Left the current branch alone \u2014 repointing onto an unreadable ref risks attaching your staged work to history Arcane cannot see. Check `git for-each-ref refs/heads/main` before committing.'
+          );
         }
       }
       if (gitState.status === "ready" && gitState.uncommittedChanges > 0) {
@@ -1942,7 +2136,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
         const profileComponents = getProfile(p.id);
         return {
           value: p.id,
-          name: `${p.id === "full" ? "\u{1F9D9}" : p.id === "lite" ? "\u26A1" : "\u{1F4CB}"}  ${p.displayName} \u2014 ${p.description}`,
+          name: `${PROFILE_ICONS[p.id] ?? "\u{1F4CB}"}  ${p.displayName} \u2014 ${p.description}`,
           description: buildProfileDescription(profileComponents, p.id)
         };
       })
@@ -1976,7 +2170,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   for (const component of components) {
     const installedFiles = [];
     for (const file of component.files) {
-      const srcPath = join4(assetsDir, file);
+      const srcPath = join4(assetsDir, component.sourceOverrides?.[file] ?? file);
       if (options.dryRun) {
         printDryRun(`Would copy: ${file}`);
       } else {
@@ -2041,7 +2235,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   }
   let tracking_mode;
   let external_provider;
-  if (profile === "governance-only" || profile === "methodology") {
+  if (profile === "governance-only" || profile === "methodology" || profile === "docs") {
     tracking_mode = "internal";
     external_provider = null;
   } else if (!options.profile) {
@@ -2066,13 +2260,57 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       external_provider = null;
     }
   }
+  let subject_root;
+  if (profile === "docs" && !options.profile) {
+    console.log();
+    const shape = await select2({
+      message: "What does this repository hold?",
+      choices: [
+        {
+          value: "root",
+          name: "One subject, at the repository root (documents sit alongside Arcane's files)"
+        },
+        { value: "subdir", name: "One subject, in its own directory" },
+        { value: "portfolio", name: "Several subjects or ventures (decide per-document later)" }
+      ]
+    });
+    if (shape === "root") {
+      subject_root = ".";
+    } else if (shape === "subdir") {
+      const answer = await input2({
+        message: "Directory holding the subject's documents:",
+        default: "docs",
+        validate: (v) => isValidSubjectRoot(v.trim() || "docs") || "Must be a relative path inside the repository (no leading /, drive letter, or ..)."
+      });
+      subject_root = answer.trim() || "docs";
+    } else if (shape === "portfolio") {
+      subject_root = null;
+    }
+  }
+  let content_sensitivity;
+  if (!options.profile) {
+    console.log();
+    content_sensitivity = await select2({
+      message: "How should agents treat this repository's contents?",
+      choices: [
+        { value: "standard", name: "Standard \u2014 agents may quote contents in journals and decisions" },
+        {
+          value: "sensitive",
+          name: "Sensitive \u2014 agents reference documents by path, never transcribe them"
+        }
+      ],
+      default: "standard"
+    });
+  }
   const manifest = {
     version: packageVersion,
     profile,
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     components: installedComponents,
     ...role ? { role } : {},
-    ...tracking_mode ? { tracking_mode, external_provider } : {}
+    ...tracking_mode ? { tracking_mode, external_provider } : {},
+    ...subject_root !== void 0 ? { subject_root } : {},
+    ...content_sensitivity ? { content_sensitivity } : {}
   };
   await writeManifest(targetDir, manifest);
   printSuccess(`Initialized with profile "${profile}" \u2014 ${fileCount} files installed`);
@@ -2156,7 +2394,7 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   let fileCount = 0;
   const installedFiles = [];
   for (const file of component.files) {
-    const srcPath = join5(assetsDir, file);
+    const srcPath = join5(assetsDir, component.sourceOverrides?.[file] ?? file);
     if (options.dryRun) {
       console.log(`  [dry-run] Would copy: ${file}`);
     } else {
@@ -2199,7 +2437,7 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
 import { join as join7 } from "path";
 
 // src/modules/hub.ts
-import { confirm as confirm2, select as select3 } from "@inquirer/prompts";
+import { confirm as confirm2, select as select3, input as input3 } from "@inquirer/prompts";
 import { readdir as readdir3, writeFile as writeFile5 } from "fs/promises";
 import { join as join6 } from "path";
 var MANIFEST_RETROFITS = [
@@ -2220,7 +2458,7 @@ var MANIFEST_RETROFITS = [
     // Mirrors init.ts's Step 5b branching exactly (EF-14 D5): docs-only
     // profiles get a silent default, full/lite get asked.
     ask: async (manifest) => {
-      if (manifest.profile === "governance-only" || manifest.profile === "methodology") {
+      if (manifest.profile === "governance-only" || manifest.profile === "methodology" || manifest.profile === "docs") {
         return { tracking_mode: "internal", external_provider: null };
       }
       const tracking_mode = await select3({
@@ -2243,6 +2481,64 @@ var MANIFEST_RETROFITS = [
       }
       return { tracking_mode, external_provider: null };
     }
+  },
+  {
+    field: "content_sensitivity",
+    needsRetrofit: (m) => m.content_sensitivity === void 0,
+    // EF-12. Asked for every profile -- a code repo can hold sensitive records
+    // too -- and defaults to "standard", so an operator who just presses enter
+    // keeps today's behaviour exactly.
+    ask: async () => {
+      const content_sensitivity = await select3({
+        message: "How should agents treat this repository's contents?",
+        choices: [
+          {
+            value: "standard",
+            name: "Standard \u2014 agents may quote contents in journals and decisions"
+          },
+          {
+            value: "sensitive",
+            name: "Sensitive \u2014 agents reference documents by path, never transcribe them"
+          }
+        ],
+        default: "standard"
+      });
+      return { content_sensitivity };
+    }
+  },
+  {
+    field: "subject_root",
+    // EF-07. Only the docs profile is asked: other profiles describe code or a
+    // venture portfolio, where "what is this repo about" is already answered.
+    // A docs install that legitimately holds several subjects answers
+    // "portfolio" and stays unset -- so this retrofit deliberately does NOT
+    // re-ask on every update. It is gated on the field being absent AND the
+    // profile being docs, and once answered (either way) it never fires again,
+    // because "portfolio" writes an explicit empty marker.
+    needsRetrofit: (m) => m.profile === "docs" && m.subject_root === void 0,
+    ask: async () => {
+      const shape = await select3({
+        message: "What does this repository hold?",
+        choices: [
+          {
+            value: "root",
+            name: "One subject, at the repository root (documents sit alongside Arcane's files)"
+          },
+          { value: "subdir", name: "One subject, in its own directory" },
+          { value: "portfolio", name: "Several subjects or ventures" }
+        ]
+      });
+      if (shape === "root") return { subject_root: "." };
+      if (shape === "subdir") {
+        const answer = await input3({
+          message: "Directory holding the subject's documents:",
+          default: "docs",
+          validate: (v) => isValidSubjectRoot(v.trim() || "docs") || "Must be a relative path inside the repository (no leading /, drive letter, or ..)."
+        });
+        return { subject_root: answer.trim() || "docs" };
+      }
+      return { subject_root: null };
+    }
   }
 ];
 async function runManifestRetrofits(manifest) {
@@ -2307,6 +2603,25 @@ async function offerRegistryScaffold(targetDir, businessRoot) {
 }
 
 // src/commands/update.ts
+function migrateLegacyComponents(components) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of components) {
+    const replacements = LEGACY_COMPONENT_MIGRATIONS[entry.name];
+    if (!replacements) {
+      if (seen.has(entry.name)) continue;
+      seen.add(entry.name);
+      out.push(entry);
+      continue;
+    }
+    for (const name of replacements) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      out.push({ name, files: [], installedVersion: entry.installedVersion });
+    }
+  }
+  return out;
+}
 async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   let manifest;
   try {
@@ -2359,7 +2674,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   }
   let fileCount = 0;
   const updatedComponents = [];
-  for (const installed of manifest.components) {
+  const componentsToUpdate = migrateLegacyComponents(manifest.components);
+  for (const installed of componentsToUpdate) {
     let component;
     try {
       component = getComponent(installed.name);
@@ -2373,8 +2689,15 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     }
     const updatedFiles = [];
     for (const file of component.files) {
-      const srcPath = join7(assetsDir, file);
-      const preserveExisting = component.skipExisting && await fileExists(join7(targetDir, file));
+      const srcPath = join7(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const targetExists = await fileExists(join7(targetDir, file));
+      const preserveExisting = Boolean(component.skipExisting) && targetExists;
+      if (component.initOnly && !targetExists) {
+        console.log(
+          `  ! Missing: ${file} \u2014 not added automatically, because doing so would change how Git treats existing files. Run "spell add ${component.name}" if you want it.`
+        );
+        continue;
+      }
       if (preserveExisting) {
         console.log(`  ${options.dryRun ? "[dry-run] Would preserve" : "Preserved"}: ${file}`);
       } else if (options.dryRun) {
@@ -2384,7 +2707,9 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
         await copyFile(srcPath, targetDir, file, { force: true });
         fileCount++;
       }
-      updatedFiles.push(file);
+      if (!preserveExisting || installed.files.includes(file)) {
+        updatedFiles.push(file);
+      }
     }
     for (const dir of component.directories ?? []) {
       const srcDirPath = join7(assetsDir, dir);
@@ -2415,7 +2740,16 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     }
     return;
   }
-  const retrofitPatch = await runManifestRetrofits(manifest);
+  const interactive = Boolean(process.stdin.isTTY);
+  const retrofitPatch = interactive ? await runManifestRetrofits(manifest) : {};
+  if (!interactive) {
+    const pending = MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest));
+    if (pending.length > 0) {
+      console.log(
+        `  ! Skipped ${pending.length} manifest question${pending.length === 1 ? "" : "s"} (${pending.map((r) => r.field).join(", ")}) \u2014 no interactive terminal. Run \`spell update\` from a terminal to answer.`
+      );
+    }
+  }
   const updated = {
     ...manifest,
     version: packageVersion,
@@ -2963,7 +3297,7 @@ 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 | 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").action(
   async (opts) => {
     await runInit(
       {