arcane-cli 0.17.1 → 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) {
@@ -1837,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({
@@ -1963,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)
         };
       })
@@ -1997,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 {
@@ -2062,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) {
@@ -2087,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`);
@@ -2177,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 {
@@ -2220,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 = [
@@ -2241,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({
@@ -2264,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) {
@@ -2328,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 {
@@ -2380,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);
@@ -2394,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) {
@@ -2405,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);
@@ -2436,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,
@@ -2984,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(
       {