@kudusov.takhir/ba-toolkit 1.5.0 → 3.0.0

package/bin/ba-toolkit.js

@@ -18,41 +18,55 @@ const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const SKILLS_DIR = path.join(PACKAGE_ROOT, 'skills');
 const PKG = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
 
+// All five supported agents — Claude Code, Codex CLI, Gemini CLI,
+// Cursor, and Windsurf — load Agent Skills as direct subfolders of
+// their skills root: `<skills-root>/<skill-name>/SKILL.md`. The toolkit
+// installs the 21 skills natively in this layout for every agent. No
+// .mdc conversion. Confirmed against the Agent Skills documentation
+// for each platform via ctx7 MCP / official docs.
+//
+// Earlier versions tried to install Cursor and Windsurf via `.mdc`
+// rules under `.cursor/rules/` and `.windsurf/rules/` — but Rules and
+// Agent Skills are two separate features in both editors, and the
+// toolkit is a pipeline of skills, not rules. The wrong-feature install
+// silently failed: skills loaded as rules never surfaced as `/brief`,
+// `/srs`, … slash commands. v2.x corrects this for Cursor, and the
+// Windsurf cleanup in this changelog entry finishes the job.
+//
+// To stay safe sharing the skills root with the user's other skills,
+// every install also drops a `.ba-toolkit-manifest.json` next to the
+// installed items. uninstall and upgrade read this manifest to remove
+// only what the toolkit owns; without it they refuse to touch anything.
 const AGENTS = {
   'claude-code': {
     name: 'Claude Code',
-    projectPath: '.claude/skills/ba-toolkit',
-    globalPath: path.join(os.homedir(), '.claude', 'skills', 'ba-toolkit'),
-    format: 'skill',
+    projectPath: '.claude/skills',
+    globalPath: path.join(os.homedir(), '.claude', 'skills'),
     restartHint: 'Restart Claude Code to load the new skills.',
   },
   codex: {
     name: 'OpenAI Codex CLI',
     projectPath: null, // Codex uses only global
-    globalPath: path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills', 'ba-toolkit'),
-    format: 'skill',
+    globalPath: path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills'),
     restartHint: 'Restart the Codex CLI to load the new skills.',
   },
   gemini: {
     name: 'Google Gemini CLI',
-    projectPath: '.gemini/skills/ba-toolkit',
-    globalPath: path.join(os.homedir(), '.gemini', 'skills', 'ba-toolkit'),
-    format: 'skill',
+    projectPath: '.gemini/skills',
+    globalPath: path.join(os.homedir(), '.gemini', 'skills'),
     restartHint: 'Reload Gemini CLI to pick up the new skills.',
   },
   cursor: {
     name: 'Cursor',
-    projectPath: '.cursor/rules/ba-toolkit',
-    globalPath: null, // Cursor rules are project-scoped
-    format: 'mdc',
-    restartHint: 'Reload the Cursor window to apply new rules.',
+    projectPath: '.cursor/skills',
+    globalPath: null, // Cursor skills are project-scoped for now
+    restartHint: 'Reload the Cursor window to apply new skills.',
   },
   windsurf: {
     name: 'Windsurf',
-    projectPath: '.windsurf/rules/ba-toolkit',
-    globalPath: null,
-    format: 'mdc',
-    restartHint: 'Reload the Windsurf window to apply new rules.',
+    projectPath: '.windsurf/skills',
+    globalPath: null, // Windsurf skills are project-scoped for now
+    restartHint: 'Reload the Windsurf window to apply new skills.',
   },
 };
 
@@ -69,6 +83,21 @@ const DOMAINS = [
   { id: 'custom',       name: 'Custom',       desc: 'Any other domain — general interview questions' },
 ];
 
+// ASCII banner shown at the top of `ba-toolkit init`. Suppressed on
+// non-TTY stdout so it doesn't end up in CI logs or piped output.
+// Stored as an array of literal lines (not a template literal) so the
+// `$` characters stay out of any interpolation path.
+const BANNER = [
+  ' /$$                           /$$                         /$$ /$$       /$$   /$$    ',
+  '| $$                          | $$                        | $$| $$      |__/  | $$    ',
+  '| $$$$$$$   /$$$$$$          /$$$$$$    /$$$$$$   /$$$$$$ | $$| $$   /$$ /$$ /$$$$$$  ',
+  '| $$__  $$ |____  $$ /$$$$$$|_  $$_/   /$$__  $$ /$$__  $$| $$| $$  /$$/| $$|_  $$_/  ',
+  '| $$  \\ $$  /$$$$$$$|______/  | $$    | $$  \\ $$| $$  \\ $$| $$| $$$$$$/ | $$  | $$    ',
+  '| $$  | $$ /$$__  $$          | $$ /$$| $$  | $$| $$  | $$| $$| $$_  $$ | $$  | $$ /$$',
+  '| $$$$$$$/|  $$$$$$$          |  $$$$/|  $$$$$$/|  $$$$$$/| $$| $$ \\  $$| $$  |  $$$$/',
+  '|_______/  \\_______/           \\___/   \\______/  \\______/ |__/|__/  \\__/|__/   \\___/  ',
+];
+
 // --- Terminal helpers --------------------------------------------------
 
 const NO_COLOR = !!process.env.NO_COLOR || !process.stdout.isTTY;
@@ -83,6 +112,17 @@ const bold = colour(1);
 function log(...args) { console.log(...args); }
 function logError(...args) { console.error(red('error:'), ...args); }
 
+// Print the BANNER to stdout if — and only if — stdout is a real TTY.
+// Piped / redirected runs (CI, test spawn, `ba-toolkit init | tee ...`)
+// get a clean log without the 8-line block. The banner is decorative,
+// not load-bearing, so suppressing it in non-interactive contexts is
+// the right default.
+function printBanner() {
+  if (!process.stdout.isTTY) return;
+  for (const line of BANNER) log(cyan(line));
+  log('');
+}
+
 // --- Arg parsing -------------------------------------------------------
 
 function parseArgs(argv) {
@@ -124,30 +164,66 @@ function parseArgs(argv) {
 // --- Prompt helper -----------------------------------------------------
 
 // Shared across all prompts in a single CLI invocation. Creating a new
-// readline.Interface for every question (the previous approach) made Ctrl+C
+// readline.Interface for every question (the earlier approach) made Ctrl+C
 // handling unreliable, leaked listeners on stdin, and broke when stdin was
-// piped (EOF on the second create). One interface per process, closed by
-// closeReadline() once main() finishes (or by the SIGINT handler).
+// piped. One interface per process, closed by closeReadline() once main()
+// finishes (or by the SIGINT handler).
+//
+// prompt() does NOT use `rl.question(...)` — that method races with
+// readline's internal line buffering when stdin is piped. If input arrives
+// faster than prompts are issued (the common piped case: the user pipes a
+// here-doc with multiple answers, or a test feeds the entire stdin buffer
+// upfront), readline emits 'line' events before the question listener is
+// attached and those lines are silently dropped. The second prompt then
+// sees EOF and errors with INPUT_CLOSED despite the answer actually being
+// in the buffer.
+//
+// Instead we own the 'line' event ourselves and keep a line queue: every
+// line that arrives is pushed onto `lineQueue` if no one is waiting, or
+// delivered directly to the oldest waiter. A prompt() call takes the head
+// of the queue if non-empty, otherwise parks a waiter. The 'close' event
+// drains all waiting waiters with INPUT_CLOSED.
 let sharedRl = null;
+const lineQueue = [];
+const waiters = [];
+let inputClosed = false;
+
+function ensureReadline() {
+  if (sharedRl) return;
+  sharedRl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  sharedRl.on('line', (line) => {
+    if (waiters.length > 0) {
+      waiters.shift().resolve(line);
+    } else {
+      lineQueue.push(line);
+    }
+  });
+  sharedRl.on('close', () => {
+    inputClosed = true;
+    while (waiters.length > 0) {
+      const err = new Error('input stream closed before answer');
+      err.code = 'INPUT_CLOSED';
+      waiters.shift().reject(err);
+    }
+  });
+}
 
 function prompt(question) {
-  if (!sharedRl) {
-    sharedRl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  ensureReadline();
+  // Render the question ourselves — we're not using rl.question().
+  process.stdout.write(question);
+  if (lineQueue.length > 0) {
+    return Promise.resolve(String(lineQueue.shift()).trim());
+  }
+  if (inputClosed) {
+    const err = new Error('input stream closed before answer');
+    err.code = 'INPUT_CLOSED';
+    return Promise.reject(err);
   }
   return new Promise((resolve, reject) => {
-    let answered = false;
-    const onClose = () => {
-      if (!answered) {
-        const err = new Error('input stream closed before answer');
-        err.code = 'INPUT_CLOSED';
-        reject(err);
-      }
-    };
-    sharedRl.once('close', onClose);
-    sharedRl.question(question, (answer) => {
-      answered = true;
-      sharedRl.removeListener('close', onClose);
-      resolve(answer.trim());
+    waiters.push({
+      resolve: (line) => resolve(String(line).trim()),
+      reject,
     });
   });
 }
@@ -159,6 +235,213 @@ function closeReadline() {
   }
 }
 
+// --- Arrow-key menus -----------------------------------------------------
+//
+// Three layers, separated for testability:
+//
+//   1. menuStep(state, key) — pure state machine. Given the current
+//      menu state and a normalised key action, returns the new state.
+//      Unit-tested directly. No dependencies, no I/O.
+//
+//   2. renderMenu(state, opts) — pure renderer. Returns the frame to
+//      print as a string. Unit-tested too — uses the colour helpers,
+//      which collapse to identity strings under NO_COLOR (i.e., in
+//      tests), so the assertions are stable.
+//
+//   3. runMenuTty(items, opts) / selectMenu(items, opts) — the I/O
+//      glue. Detects TTY, sets raw mode, listens for keypress events,
+//      drives the loop, falls back to a numbered prompt under
+//      promptUntilValid when the terminal is non-interactive (CI,
+//      piped input, TERM=dumb). Not unit-tested — covered by manual
+//      smoke and the existing fallback-path integration tests.
+//
+// Cross-platform note: Node's `readline.emitKeypressEvents` decodes
+// arrow-key escape sequences uniformly across bash/zsh/fish on
+// Linux/macOS, Windows Terminal (PowerShell, cmd, WSL), Git Bash /
+// MSYS2, and VSCode's integrated terminal. Modern Node also enables VT
+// mode automatically on Windows when raw mode is requested, so legacy
+// cmd.exe on Win10+ works too. The only environment we explicitly bail
+// out of is `TERM=dumb` (emacs M-x shell, some IDE shells) — keypress
+// decoding is unreliable there.
+
+function menuStep(state, key) {
+  if (state.done) return state;
+  const len = state.items.length;
+  if (len === 0) return state;
+  switch (key) {
+    case 'up':
+      return { ...state, index: (state.index - 1 + len) % len };
+    case 'down':
+      return { ...state, index: (state.index + 1) % len };
+    case 'enter':
+      return { ...state, done: true, choice: state.items[state.index] };
+    case 'cancel':
+      return { ...state, done: true, choice: null };
+    default:
+      if (/^[0-9]$/.test(key)) {
+        const n = parseInt(key, 10);
+        if (n >= 1 && n <= len) {
+          return { ...state, index: n - 1 };
+        }
+      }
+      return state;
+  }
+}
+
+function renderMenu(state, { title } = {}) {
+  const lines = [];
+  if (title) {
+    lines.push('  ' + yellow(title));
+    lines.push('');
+  }
+  const labelWidth = Math.max(...state.items.map((it) => it.label.length));
+  state.items.forEach((item, i) => {
+    const selected = i === state.index;
+    const marker = selected ? cyan('>') : ' ';
+    const idx = String(i + 1).padStart(2);
+    const label = selected ? bold(item.label.padEnd(labelWidth)) : item.label.padEnd(labelWidth);
+    const desc = item.desc ? '  ' + gray('— ' + item.desc) : '';
+    lines.push(`  ${marker} ${idx}) ${label}${desc}`);
+  });
+  lines.push('');
+  lines.push('  ' + gray('↑/↓ navigate · Enter select · 1-9 jump · Esc cancel'));
+  return lines.join('\n') + '\n';
+}
+
+// True when arrow-key menus are usable in this process. False under
+// piped stdin/stdout, dumb terminals, or when raw mode is unavailable.
+function isInteractiveTerminal() {
+  if (!process.stdin.isTTY) return false;
+  if (!process.stdout.isTTY) return false;
+  if (process.env.TERM === 'dumb') return false;
+  if (typeof process.stdin.setRawMode !== 'function') return false;
+  return true;
+}
+
+// TTY runner: drive the menu state machine via raw-mode keypress
+// events. Returns the chosen item or null if the user cancelled.
+// The caller is responsible for not invoking this when
+// isInteractiveTerminal() is false.
+function runMenuTty(items, { title } = {}) {
+  // The shared line-mode readline (used by `prompt()`) and a raw-mode
+  // keypress reader can't both own stdin at the same time. Close any
+  // line-mode interface before we take over; the next prompt() call
+  // will lazily recreate it via ensureReadline().
+  closeReadline();
+
+  return new Promise((resolve) => {
+    let state = { items, index: 0, done: false, choice: null };
+    let lastFrameLineCount = 0;
+
+    const render = () => {
+      // Erase the previous frame in place: move the cursor up over its
+      // line count, then clear from cursor to end of screen. First
+      // render has nothing to erase.
+      if (lastFrameLineCount > 0) {
+        process.stdout.write(`\x1b[${lastFrameLineCount}A\x1b[J`);
+      }
+      const frame = renderMenu(state, { title });
+      process.stdout.write(frame);
+      // Count lines actually printed (frame ends with a trailing \n).
+      lastFrameLineCount = frame.split('\n').length - 1;
+    };
+
+    const cleanup = () => {
+      process.stdin.removeListener('keypress', onKey);
+      try {
+        process.stdin.setRawMode(false);
+      } catch { /* setRawMode can throw if stdin is not a TTY anymore */ }
+      process.stdin.pause();
+    };
+
+    const onKey = (_str, key) => {
+      if (!key) return;
+      let action = null;
+      if (key.ctrl && key.name === 'c') action = 'cancel';
+      else if (key.name === 'escape') action = 'cancel';
+      else if (key.name === 'up' || key.name === 'k') action = 'up';
+      else if (key.name === 'down' || key.name === 'j') action = 'down';
+      else if (key.name === 'return') action = 'enter';
+      else if (key.sequence && /^[0-9]$/.test(key.sequence)) action = key.sequence;
+      if (!action) return;
+      state = menuStep(state, action);
+      if (state.done) {
+        cleanup();
+        resolve(state.choice);
+      } else {
+        render();
+      }
+    };
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('keypress', onKey);
+    render();
+  });
+}
+
+// Top-level selector: interactive arrow-key menu in real terminals,
+// numbered prompt fallback everywhere else (CI, piped input, dumb
+// TERM, EditorIDE shells). Always returns either an item from `items`
+// or null on cancel.
+async function selectMenu(items, { title, fallbackPrompt }) {
+  if (isInteractiveTerminal()) {
+    return await runMenuTty(items, { title });
+  }
+  // Non-TTY fallback: print the numbered list once, then prompt with
+  // promptUntilValid so a single typo doesn't kill the wizard.
+  log('');
+  if (title) log('  ' + yellow(title));
+  const labelWidth = Math.max(...items.map((it) => it.label.length));
+  items.forEach((item, i) => {
+    const idx = String(i + 1).padStart(2);
+    const desc = item.desc ? '  ' + gray('— ' + item.desc) : '';
+    log(`    ${idx}) ${bold(item.label.padEnd(labelWidth))}${desc}`);
+  });
+  log('');
+  return await promptUntilValid(
+    fallbackPrompt,
+    (raw) => {
+      const trimmed = String(raw || '').toLowerCase().trim();
+      if (!trimmed) return null;
+      if (/^\d+$/.test(trimmed)) {
+        const n = parseInt(trimmed, 10);
+        return n >= 1 && n <= items.length ? items[n - 1] : null;
+      }
+      return items.find((it) => it.id === trimmed) || null;
+    },
+    { invalidMessage: `Invalid selection — pick a number between 1 and ${items.length} or an id.` },
+  );
+}
+
+// Ask the user `question`, run `resolver` on the trimmed answer, and
+// loop while the resolver returns null/undefined. Prints a yellow
+// "try again" message between attempts. Aborts with process.exit(1)
+// after `maxAttempts` consecutive invalid answers so a piped input
+// can't infinite-loop us.
+//
+// Previously, cmdInit called `resolveDomain` / `resolveAgent` /
+// `sanitiseSlug` once and hard-failed on the first typo — users who
+// mistyped "saass" lost the whole wizard and had to start over. With
+// the retry loop, they just read the error and try again.
+async function promptUntilValid(question, resolver, {
+  maxAttempts = 3,
+  invalidMessage = 'Invalid selection — try again.',
+} = {}) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const raw = await prompt(question);
+    const result = resolver(raw);
+    if (result != null && result !== '') return result;
+    const remaining = maxAttempts - attempt;
+    if (remaining > 0) {
+      log('  ' + yellow(`${invalidMessage} (${remaining} attempt${remaining === 1 ? '' : 's'} left)`));
+    }
+  }
+  logError(`Too many invalid attempts — aborting.`);
+  process.exit(1);
+}
+
 // --- Utilities ---------------------------------------------------------
 
 function sanitiseSlug(input) {
@@ -296,35 +579,21 @@ function today() {
   return new Date().toISOString().slice(0, 10);
 }
 
-function copyDir(src, dest, { dryRun = false, transform = null } = {}) {
-  if (!fs.existsSync(src)) {
-    throw new Error(`Source directory not found: ${src}`);
-  }
-  const copied = [];
-  (function walk(s, d) {
-    if (!dryRun) fs.mkdirSync(d, { recursive: true });
-    for (const entry of fs.readdirSync(s, { withFileTypes: true })) {
-      const srcPath = path.join(s, entry.name);
-      let destPath = path.join(d, entry.name);
-      if (entry.isDirectory()) {
-        walk(srcPath, destPath);
-        continue;
-      }
-      if (transform) {
-        const result = transform(srcPath, destPath);
-        if (!result) continue;
-        destPath = result.destPath;
-        if (!dryRun) {
-          fs.mkdirSync(path.dirname(destPath), { recursive: true });
-          fs.writeFileSync(destPath, result.content);
-        }
-      } else {
-        if (!dryRun) fs.copyFileSync(srcPath, destPath);
-      }
-      copied.push(destPath);
+// Generic recursive copy that mirrors src into dest. Used by copySkills
+// for the references/ folder and for skill-format skill folders, where
+// the source structure is preserved verbatim.
+function copyDirRecursive(src, dest, { dryRun, copied }) {
+  if (!dryRun) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const sp = path.join(src, entry.name);
+    const dp = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(sp, dp, { dryRun, copied });
+    } else {
+      if (!dryRun) fs.copyFileSync(sp, dp);
+      copied.push(dp);
     }
-  })(src, dest);
-  return copied;
+  }
 }
 
 // Minimal YAML frontmatter parser for SKILL.md files.
@@ -350,8 +619,10 @@ function copyDir(src, dest, { dryRun = false, transform = null } = {}) {
 //   - Quoted scalars (single or double quoted) — names would keep quotes
 //
 // Returns { name, description, body }. `description` is always
-// flattened to a single line (whitespace collapsed) because the .mdc
-// rule format expects a one-line description.
+// flattened to a single line (whitespace collapsed) — keeps the
+// downstream consumers (manifest summary, status output, agent skill
+// loaders that expect a single-line description) free of multi-line
+// surprises.
 function parseSkillFrontmatter(content) {
   const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
   if (!fmMatch) {
@@ -400,19 +671,50 @@ function parseSkillFrontmatter(content) {
   };
 }
 
-// Transform SKILL.md → .mdc for Cursor / Windsurf.
-// Other files (references/, templates/) are copied as-is.
-function skillToMdc(srcPath, destPath) {
-  const base = path.basename(srcPath);
-  if (base !== 'SKILL.md') {
-    return { destPath, content: fs.readFileSync(srcPath) };
-  }
-  const content = fs.readFileSync(srcPath, 'utf8');
-  const { name, description, body } = parseSkillFrontmatter(content);
-  const ruleName = name || path.basename(path.dirname(srcPath));
-  const mdcFrontmatter = `---\ndescription: ${description}\nalwaysApply: false\n---\n\n`;
-  const newDestPath = path.join(path.dirname(destPath), `${ruleName}.mdc`);
-  return { destPath: newDestPath, content: mdcFrontmatter + body };
+// Install the package's skills/ tree into the given destination. Every
+// supported agent uses the same Agent Skills layout: each source skill
+// folder lands as `<destRoot>/<skillName>/SKILL.md`. The `references/`
+// folder is copied as-is to `<destRoot>/references/`.
+//
+// Skill names come from the SKILL.md `name:` frontmatter field, falling
+// back to the source folder name. Returns:
+//   { copied, items }
+// where `copied` is the list of absolute file paths written and `items`
+// is the list of top-level entries in destRoot that the toolkit owns
+// (used to write the manifest).
+function copySkills(srcRoot, destRoot, { dryRun = false } = {}) {
+  if (!fs.existsSync(srcRoot)) {
+    throw new Error(`Source directory not found: ${srcRoot}`);
+  }
+  const copied = [];
+  const items = [];
+
+  if (!dryRun) fs.mkdirSync(destRoot, { recursive: true });
+
+  for (const entry of fs.readdirSync(srcRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const srcPath = path.join(srcRoot, entry.name);
+
+    if (entry.name === 'references') {
+      const refDest = path.join(destRoot, 'references');
+      copyDirRecursive(srcPath, refDest, { dryRun, copied });
+      items.push('references');
+      continue;
+    }
+
+    // Skill folder. Read its SKILL.md to get the canonical name.
+    const skillMdSrc = path.join(srcPath, 'SKILL.md');
+    if (!fs.existsSync(skillMdSrc)) continue; // not a skill folder
+    const content = fs.readFileSync(skillMdSrc, 'utf8');
+    const { name } = parseSkillFrontmatter(content);
+    const skillName = name || entry.name;
+
+    const skillDestDir = path.join(destRoot, skillName);
+    copyDirRecursive(srcPath, skillDestDir, { dryRun, copied });
+    items.push(skillName);
+  }
+
+  return { copied, items };
 }
 
 // Path to the AGENTS.md template file. Lives next to the rest of the
@@ -429,6 +731,13 @@ function skillToMdc(srcPath, destPath) {
 // 21-skill list and ordering; keep that template in sync with it.
 const AGENTS_TEMPLATE_PATH = path.join(SKILLS_DIR, 'references', 'templates', 'agents-template.md');
 
+// Anchor markers delimit the block inside AGENTS.md that `ba-toolkit
+// init` owns and is allowed to rewrite on re-init. Everything outside
+// the anchors (Pipeline Status, Key Constraints, Open Questions, user
+// notes) is preserved untouched. See agents-template.md.
+const AGENTS_MANAGED_BEGIN = '<!-- ba-toolkit:begin managed -->';
+const AGENTS_MANAGED_END = '<!-- ba-toolkit:end managed -->';
+
 function renderAgentsMd({ name, slug, domain }) {
   let template;
   try {
@@ -443,9 +752,50 @@ function renderAgentsMd({ name, slug, domain }) {
     .replace(/\[DATE\]/g, today());
 }
 
+// Merge the fresh AGENTS.md content into whatever already exists at
+// the project root. Three branches:
+//
+//   1. No existing file (existing == null) — return the fresh template,
+//      action 'created'.
+//   2. Existing file has both anchor markers — replace only the managed
+//      block content between the anchors, leave the rest of the file
+//      (Pipeline Status, Key Constraints, user notes) untouched. Action
+//      'merged'.
+//   3. Existing file has no anchors — it's either a legacy AGENTS.md
+//      from a pre-merge version of the toolkit or a fully user-authored
+//      file. Leave it untouched and return { action: 'preserved' } so
+//      the caller can print a note. We never silently overwrite
+//      user content.
+//
+// Pure function for easy testing. Exported so test/cli.test.js can
+// cover all three branches without spawning a process.
+function mergeAgentsMd(existing, ctx) {
+  const fresh = renderAgentsMd(ctx);
+  if (existing == null) {
+    return { content: fresh, action: 'created' };
+  }
+  const beginIdx = existing.indexOf(AGENTS_MANAGED_BEGIN);
+  const endIdx = existing.indexOf(AGENTS_MANAGED_END);
+  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
+    return { content: existing, action: 'preserved' };
+  }
+  const freshBeginIdx = fresh.indexOf(AGENTS_MANAGED_BEGIN);
+  const freshEndIdx = fresh.indexOf(AGENTS_MANAGED_END);
+  if (freshBeginIdx === -1 || freshEndIdx === -1) {
+    // Template is broken — fall back to returning fresh. Should be
+    // caught in unit tests if the template file ever loses its anchors.
+    return { content: fresh, action: 'created' };
+  }
+  const freshManaged = fresh.slice(freshBeginIdx, freshEndIdx + AGENTS_MANAGED_END.length);
+  const before = existing.slice(0, beginIdx);
+  const after = existing.slice(endIdx + AGENTS_MANAGED_END.length);
+  return { content: before + freshManaged + after, action: 'merged' };
+}
+
 // --- Commands ----------------------------------------------------------
 
 async function cmdInit(args) {
+  printBanner();
   log('');
   log('  ' + cyan('BA Toolkit — New Project Setup'));
   log('  ' + cyan('================================'));
@@ -480,20 +830,43 @@ async function cmdInit(args) {
       }
       slug = derived;
     } else if (derived) {
-      const custom = await prompt(`  Project slug [${cyan(derived)}]: `);
-      slug = custom || derived;
+      // Default branch: the derived slug is offered as the suggested
+      // answer. Empty input accepts the suggestion; anything the user
+      // types is run through sanitiseSlug and must produce something
+      // non-empty — otherwise re-prompt.
+      slug = await promptUntilValid(
+        `  Project slug [${cyan(derived)}]: `,
+        (raw) => {
+          const typed = String(raw || '').trim();
+          if (!typed) return derived;
+          const cleaned = sanitiseSlug(typed);
+          return cleaned || null;
+        },
+        { invalidMessage: 'Invalid slug — must produce at least one ASCII letter/digit after sanitisation.' },
+      );
     } else {
       log('  ' + gray(`(could not derive a slug from "${name}" — please type one manually)`));
-      slug = await prompt('  Project slug (lowercase, hyphens only): ');
+      slug = await promptUntilValid(
+        '  Project slug (lowercase, hyphens only): ',
+        (raw) => {
+          const cleaned = sanitiseSlug(String(raw || '').trim());
+          return cleaned || null;
+        },
+        { invalidMessage: 'Invalid slug — must contain at least one ASCII letter or digit.' },
+      );
     }
   }
+  // At this point `slug` is already a sanitised, non-empty string from
+  // one of the branches above. The final sanitiseSlug call is a
+  // defensive no-op for the flag path (--slug) where we haven't
+  // cleaned it yet.
   slug = sanitiseSlug(slug);
   if (!slug) {
     logError('Invalid or empty slug.');
     process.exit(1);
   }
 
-  // --- 3. Domain (numbered menu) ---
+  // --- 3. Domain (arrow menu in TTY, numbered fallback elsewhere) ---
   const domainFlag = stringFlag(args, 'domain');
   let domain;
   if (domainFlag) {
@@ -504,20 +877,18 @@ async function cmdInit(args) {
       process.exit(1);
     }
   } else {
-    log('');
-    log('  ' + yellow('Pick a domain:'));
-    const domainNameWidth = Math.max(...DOMAINS.map((d) => d.name.length));
-    DOMAINS.forEach((d, i) => {
-      const idx = String(i + 1).padStart(2);
-      log(`    ${idx}) ${bold(d.name.padEnd(domainNameWidth))} ${gray('— ' + d.desc)}`);
-    });
-    log('');
-    const raw = await prompt(`  Select [1-${DOMAINS.length}]: `);
-    domain = resolveDomain(raw);
-    if (!domain) {
-      logError(`Invalid selection: ${raw || '(empty)'}`);
-      process.exit(1);
+    const chosen = await selectMenu(
+      DOMAINS.map((d) => ({ id: d.id, label: d.name, desc: d.desc })),
+      {
+        title: 'Pick a domain:',
+        fallbackPrompt: `  Select [1-${DOMAINS.length}]: `,
+      },
+    );
+    if (chosen == null) {
+      log('  ' + yellow('Cancelled.'));
+      process.exit(130);
     }
+    domain = chosen.id;
   }
 
   // --- 4. Agent (numbered menu), unless --no-install ---
@@ -533,21 +904,19 @@ async function cmdInit(args) {
         process.exit(1);
       }
     } else {
-      log('');
-      log('  ' + yellow('Pick your AI agent:'));
       const agentEntries = Object.entries(AGENTS);
-      const agentNameWidth = Math.max(...agentEntries.map(([, a]) => a.name.length));
-      agentEntries.forEach(([id, a], i) => {
-        const idx = String(i + 1).padStart(2);
-        log(`    ${idx}) ${bold(a.name.padEnd(agentNameWidth))} ${gray('(' + id + ')')}`);
-      });
-      log('');
-      const raw = await prompt(`  Select [1-${agentEntries.length}]: `);
-      agentId = resolveAgent(raw);
-      if (!agentId) {
-        logError(`Invalid selection: ${raw || '(empty)'}`);
-        process.exit(1);
+      const chosen = await selectMenu(
+        agentEntries.map(([id, a]) => ({ id, label: a.name, desc: '(' + id + ')' })),
+        {
+          title: 'Pick your AI agent:',
+          fallbackPrompt: `  Select [1-${agentEntries.length}]: `,
+        },
+      );
+      if (chosen == null) {
+        log('  ' + yellow('Cancelled.'));
+        process.exit(130);
       }
+      agentId = chosen.id;
     }
   }
 
@@ -563,18 +932,23 @@ async function cmdInit(args) {
     log(`    exists   ${outputDir}`);
   }
 
+  // AGENTS.md: merge-on-reinit instead of overwrite. Everything outside
+  // the managed block (Pipeline Status, Key Constraints, user notes) is
+  // preserved. See mergeAgentsMd for the three branches (created,
+  // merged, preserved).
   const agentsPath = 'AGENTS.md';
-  let writeAgents = true;
-  if (fs.existsSync(agentsPath)) {
-    const answer = await prompt('  AGENTS.md already exists. Overwrite? (y/N): ');
-    if (answer.toLowerCase() !== 'y') {
-      writeAgents = false;
-      log('    skipped  AGENTS.md');
-    }
-  }
-  if (writeAgents) {
-    fs.writeFileSync(agentsPath, renderAgentsMd({ name, slug, domain }));
-    log('    created  AGENTS.md');
+  const existingAgents = fs.existsSync(agentsPath)
+    ? fs.readFileSync(agentsPath, 'utf8')
+    : null;
+  const { content: agentsContent, action: agentsAction } = mergeAgentsMd(
+    existingAgents,
+    { name, slug, domain },
+  );
+  if (agentsAction === 'preserved') {
+    log('    ' + gray('preserved AGENTS.md (no ba-toolkit managed block — left untouched)'));
+  } else {
+    fs.writeFileSync(agentsPath, agentsContent);
+    log(`    ${agentsAction === 'merged' ? 'updated ' : 'created '} AGENTS.md`);
   }
 
   // --- 6. Install skills for the selected agent ---
@@ -620,14 +994,18 @@ async function cmdInit(args) {
   log('');
 }
 
-// Marker file written into the install destination after a successful copy.
-// Lets `upgrade` and `status` (future command) tell which package version
-// is currently installed without diffing every file. Hidden file with no
-// `.md` / `.mdc` extension so the agent's skill loader ignores it.
-const SENTINEL_FILENAME = '.ba-toolkit-version';
+// Manifest written into the install destination after a successful copy.
+// Replaces the v1.x version sentinel — now also tracks WHICH items
+// belong to BA Toolkit, so uninstall/upgrade can selectively remove
+// only what we own without touching the user's other skills sitting in
+// the same directory.
+//
+// Hidden filename with no `.md` extension so the skill loader of every
+// supported agent ignores it.
+const MANIFEST_FILENAME = '.ba-toolkit-manifest.json';
 
-function readSentinel(destDir) {
-  const p = path.join(destDir, SENTINEL_FILENAME);
+function readManifest(destDir) {
+  const p = path.join(destDir, MANIFEST_FILENAME);
   if (!fs.existsSync(p)) return null;
   try {
     return JSON.parse(fs.readFileSync(p, 'utf8'));
@@ -636,45 +1014,51 @@ function readSentinel(destDir) {
   }
 }
 
-function writeSentinel(destDir) {
+function writeManifest(destDir, items) {
   const payload = {
     version: PKG.version,
     installedAt: new Date().toISOString(),
+    items,
   };
   fs.writeFileSync(
-    path.join(destDir, SENTINEL_FILENAME),
+    path.join(destDir, MANIFEST_FILENAME),
     JSON.stringify(payload, null, 2) + '\n',
   );
 }
 
-// Core install logic. Shared between `cmdInstall` (standalone), `cmdInit`
-// (full setup), and `cmdUpgrade`. Returns true on success, false if the
-// user declined to overwrite an existing destination. Pass `force: true`
-// to skip the overwrite prompt — `cmdUpgrade` uses this because it has
-// already wiped the destination and explicitly knows the overwrite is ok.
-async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = true, force = false }) {
-  const agent = AGENTS[agentId];
-  if (!agent) {
-    logError(`Unknown agent: ${agentId}`);
-    log('Supported: ' + Object.keys(AGENTS).join(', '));
-    process.exit(1);
-  }
-
-  let effectiveGlobal = !!isGlobal;
-  if (!isGlobal && !isProject) {
-    // Default: project-level if supported, otherwise global
-    effectiveGlobal = !agent.projectPath;
-  }
-  if (effectiveGlobal && !agent.globalPath) {
-    logError(`${agent.name} does not support --global install.`);
-    process.exit(1);
+// Detect the v1.x install layout: every previous install path nested
+// our 21 skills under an extra `ba-toolkit/` folder, which made them
+// invisible to every agent's skill loader. Returns the absolute paths
+// of any legacy folders that still exist for the given agent, so the
+// caller can warn the user to clean them up before installing v2.0.
+function detectLegacyInstall(agent) {
+  const candidates = [];
+  if (agent.projectPath) {
+    candidates.push(path.resolve(process.cwd(), agent.projectPath, 'ba-toolkit'));
   }
-  if (!effectiveGlobal && !agent.projectPath) {
-    logError(`${agent.name} does not support project-level install. Use --global.`);
-    process.exit(1);
+  if (agent.globalPath) {
+    candidates.push(path.join(agent.globalPath, 'ba-toolkit'));
   }
+  return candidates.filter((p) => fs.existsSync(p));
+}
 
-  const destDir = effectiveGlobal ? agent.globalPath : path.resolve(process.cwd(), agent.projectPath);
+// Core install logic. Shared between `cmdInstall` (standalone), `cmdInit`
+// (full setup), and `cmdUpgrade`. Returns true on success, false if the
+// user declined to overwrite an existing install. Pass `force: true` to
+// skip the overwrite prompt — cmdUpgrade uses this because it has
+// already removed the previous install via the manifest.
+//
+// v2.0 model: the destination directory is shared with the user's other
+// skills. We never wipe destDir wholesale. Before copying we read the
+// manifest (if any) and remove only the items the previous v2.0 install
+// owned, then copy the new tree and write a fresh manifest. Items that
+// don't appear in the manifest are not ours and never get touched.
+async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = true, force = false }) {
+  const { agent, destDir, effectiveGlobal } = resolveAgentDestination({
+    agentId,
+    isGlobal,
+    isProject,
+  });
 
   if (showHeader) {
     log('');
@@ -687,37 +1071,87 @@ async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = t
   log(`    source:       ${SKILLS_DIR}`);
   log(`    destination:  ${destDir}`);
   log(`    scope:        ${effectiveGlobal ? 'global (user-wide)' : 'project-level'}`);
-  log(`    format:       ${agent.format === 'mdc' ? '.mdc (converted from SKILL.md)' : 'SKILL.md (native)'}`);
+  log(`    format:       SKILL.md (native)`);
   if (dryRun) log('    ' + yellow('mode:         dry-run (no files will be written)'));
 
-  if (fs.existsSync(destDir) && !dryRun && !force) {
-    const answer = await prompt(`    ${destDir} already exists. Overwrite? (y/N): `);
+  // Warn about a v1.x wrapper folder if one is sitting in the same
+  // location. Don't auto-delete — could be the user's working state.
+  warnLegacyInstall(agent);
+
+  // If a previous v2.0 install lives here, ask before replacing it.
+  // The manifest is the only signal that the directory contains our
+  // files; without it we treat the install as fresh and let copySkills
+  // happily add to whatever's already there.
+  const existingManifest = readManifest(destDir);
+  if (existingManifest && !dryRun && !force) {
+    log(`    existing:     v${existingManifest.version} (${existingManifest.items.length} items)`);
+    const answer = await prompt('    Replace existing BA Toolkit install? (y/N): ');
     if (answer.toLowerCase() !== 'y') {
       log('    cancelled.');
       return false;
     }
   }
 
-  const transform = agent.format === 'mdc' ? skillToMdc : null;
-  let copied;
+  // Selectively remove the previous install's items (and only those)
+  // before copying the new tree. Sentinel-style file is removed too.
+  if (existingManifest && !dryRun) {
+    removeManifestItems(destDir, existingManifest);
+  }
+
+  let result;
   try {
-    copied = copyDir(SKILLS_DIR, destDir, { dryRun, transform });
+    result = copySkills(SKILLS_DIR, destDir, { dryRun });
   } catch (err) {
     logError(err.message);
     process.exit(1);
   }
 
   if (!dryRun) {
-    writeSentinel(destDir);
+    writeManifest(destDir, result.items);
   }
 
-  log('    ' + green(`${dryRun ? 'would copy' : 'copied'} ${copied.length} files.`));
-  if (!dryRun && agent.format === 'mdc') {
-    log('    ' + gray('SKILL.md files converted to .mdc rule format.'));
-  }
+  log('    ' + green(`${dryRun ? 'would copy' : 'copied'} ${result.copied.length} files (${result.items.length} items).`));
   return true;
 }
 
+// Remove every item listed in the given manifest from destDir, then
+// remove the manifest file itself. Items are top-level entries
+// relative to destDir — folder names like `brief`, `srs`, …,
+// `references`. Anything not in the manifest is left alone, including
+// the user's other skills sitting in the same directory.
+function removeManifestItems(destDir, manifest) {
+  for (const item of manifest.items) {
+    const p = path.join(destDir, item);
+    if (fs.existsSync(p)) {
+      fs.rmSync(p, { recursive: true, force: true });
+    }
+  }
+  const manifestPath = path.join(destDir, MANIFEST_FILENAME);
+  if (fs.existsSync(manifestPath)) {
+    fs.rmSync(manifestPath, { force: true });
+  }
+}
+
+// Print a yellow warning if the v1.x wrapper directory is still around
+// in the same skills root. The wrapper made every shipped skill
+// invisible to the agent, so any user upgrading from v1 needs to
+// remove it manually before v2.0 can install correctly.
+function warnLegacyInstall(agent) {
+  const legacy = detectLegacyInstall(agent);
+  if (legacy.length === 0) return;
+  log('');
+  log('  ' + yellow('! Legacy v1.x install detected — must be removed before v2.0 will work:'));
+  for (const p of legacy) {
+    log('  ' + yellow(`    ${p}`));
+  }
+  log('  ' + yellow('  v2.0 dropped the ba-toolkit/ wrapper folder; the agent ignored every skill nested under it.'));
+  log('  ' + yellow('  Remove the legacy folder manually:'));
+  for (const p of legacy) {
+    log('  ' + gray(`    rm -rf "${p}"`));
+  }
+  log('');
+}
+
 async function cmdInstall(args) {
   const agentId = stringFlag(args, 'for');
   if (!agentId) {
@@ -775,74 +1209,82 @@ function cmdStatus() {
   log(`  scanning from:    ${process.cwd()}`);
   log('');
 
-  // Walk every (agent × scope) combination and collect the ones whose
-  // destination directory actually exists. Project-scope paths resolve
-  // against the current working directory; global paths are absolute.
+  // Walk every (agent × scope) combination and collect the ones that
+  // have a v2.0 manifest. Project-scope paths resolve against the
+  // current working directory; global paths are absolute.
   const rows = [];
+  const legacyRows = [];
+
+  const checkLocation = (agent, agentId, scope, dir) => {
+    if (!fs.existsSync(dir)) return;
+    const manifest = readManifest(dir);
+    if (manifest) {
+      rows.push({
+        agentName: agent.name,
+        agentId,
+        scope,
+        path: dir,
+        version: manifest.version,
+        installedAt: manifest.installedAt,
+        itemCount: manifest.items.length,
+      });
+    }
+  };
+
   for (const [agentId, agent] of Object.entries(AGENTS)) {
     if (agent.projectPath) {
       const projectDir = path.resolve(process.cwd(), agent.projectPath);
-      if (fs.existsSync(projectDir)) {
-        const sentinel = readSentinel(projectDir);
-        rows.push({
-          agentName: agent.name,
-          agentId,
-          scope: 'project',
-          path: projectDir,
-          version: sentinel ? sentinel.version : null,
-          installedAt: sentinel ? sentinel.installedAt : null,
-        });
-      }
+      checkLocation(agent, agentId, 'project', projectDir);
     }
     if (agent.globalPath) {
-      if (fs.existsSync(agent.globalPath)) {
-        const sentinel = readSentinel(agent.globalPath);
-        rows.push({
-          agentName: agent.name,
-          agentId,
-          scope: 'global',
-          path: agent.globalPath,
-          version: sentinel ? sentinel.version : null,
-          installedAt: sentinel ? sentinel.installedAt : null,
-        });
-      }
+      checkLocation(agent, agentId, 'global', agent.globalPath);
+    }
+    // Surface any v1.x wrapper folders as a separate "legacy" row.
+    for (const legacyPath of detectLegacyInstall(agent)) {
+      legacyRows.push({ agentName: agent.name, agentId, path: legacyPath });
     }
   }
 
-  if (rows.length === 0) {
+  if (rows.length === 0 && legacyRows.length === 0) {
     log('  ' + gray('No BA Toolkit installations found in any known location.'));
     log('  ' + gray("Run 'ba-toolkit install --for <agent>' to install one."));
     log('');
     return;
   }
 
-  log(`  Found ${bold(rows.length)} installation${rows.length === 1 ? '' : 's'}:`);
-  log('');
-
-  for (const row of rows) {
-    let versionLabel;
-    if (!row.version) {
-      versionLabel = gray('(unknown — pre-1.4 install with no sentinel)');
-    } else if (row.version === PKG.version) {
-      versionLabel = green(row.version + ' (current)');
-    } else {
-      versionLabel = yellow(row.version + ' (outdated)');
-    }
-    log(`  ${bold(row.agentName)} ${gray('(' + row.agentId + ', ' + row.scope + ')')}`);
-    log(`    path:      ${row.path}`);
-    log(`    version:   ${versionLabel}`);
-    if (row.installedAt) {
+  if (rows.length > 0) {
+    log(`  Found ${bold(rows.length)} installation${rows.length === 1 ? '' : 's'}:`);
+    log('');
+    for (const row of rows) {
+      const versionLabel = row.version === PKG.version
+        ? green(row.version + ' (current)')
+        : yellow(row.version + ' (outdated)');
+      log(`  ${bold(row.agentName)} ${gray('(' + row.agentId + ', ' + row.scope + ')')}`);
+      log(`    path:      ${row.path}`);
+      log(`    version:   ${versionLabel}`);
+      log(`    items:     ${row.itemCount}`);
       log(`    installed: ${gray(row.installedAt)}`);
+      log('');
     }
+  }
+
+  if (legacyRows.length > 0) {
+    log('  ' + yellow(`Found ${legacyRows.length} legacy v1.x install${legacyRows.length === 1 ? '' : 's'} (broken — invisible to the agent):`));
     log('');
+    for (const row of legacyRows) {
+      log(`  ${bold(row.agentName)} ${gray('(' + row.agentId + ', legacy wrapper)')}`);
+      log(`    path:      ${row.path}`);
+      log(`    fix:       ` + gray(`rm -rf "${row.path}" && ba-toolkit install --for ${row.agentId}`));
+      log('');
+    }
   }
 
-  const stale = rows.filter((r) => !r.version || r.version !== PKG.version);
+  const stale = rows.filter((r) => r.version !== PKG.version);
   if (stale.length > 0) {
     log('  ' + yellow(`${stale.length} installation${stale.length === 1 ? '' : 's'} not at version ${PKG.version}.`));
     log('  ' + gray("Run 'ba-toolkit upgrade --for <agent>' to refresh."));
     log('');
-  } else {
+  } else if (rows.length > 0) {
     log('  ' + green('All installations are up to date.'));
     log('');
   }
@@ -869,54 +1311,47 @@ async function cmdUpgrade(args) {
   log(`  destination:  ${destDir}`);
   log(`  scope:        ${effectiveGlobal ? 'global (user-wide)' : 'project-level'}`);
 
+  warnLegacyInstall(agent);
+
   if (!fs.existsSync(destDir)) {
     log('');
     log('  ' + gray(`No installation found at ${destDir}.`));
-    log('  ' + gray(`Run \`ba-toolkit install --for ${agentId}\` first.`));
+    log('  ' + gray(`Run 'ba-toolkit install --for ${agentId}' first.`));
     log('');
     return;
   }
 
-  const sentinel = readSentinel(destDir);
-  const currentVersion = PKG.version;
-  const installedVersion = sentinel ? sentinel.version : null;
+  const manifest = readManifest(destDir);
+  if (!manifest) {
+    log('');
+    log('  ' + gray('No BA Toolkit manifest found in this destination.'));
+    log('  ' + gray(`Run 'ba-toolkit install --for ${agentId}' to install fresh.`));
+    log('');
+    return;
+  }
 
-  if (installedVersion === currentVersion) {
-    log(`  installed:    ${installedVersion} (current)`);
+  const currentVersion = PKG.version;
+  if (manifest.version === currentVersion) {
+    log(`  installed:    ${manifest.version} (current)`);
     log(`  package:      ${currentVersion}`);
     log('');
     log('  ' + green('Already up to date.'));
-    log('  ' + gray(`To force a clean reinstall, run \`ba-toolkit install --for ${agentId}\`.`));
+    log('  ' + gray(`To force a clean reinstall, run 'ba-toolkit install --for ${agentId}'.`));
     log('');
     return;
   }
 
-  log(`  installed:    ${installedVersion || gray('(unknown — pre-1.4 install with no sentinel)')}`);
+  log(`  installed:    ${manifest.version}`);
   log(`  package:      ${currentVersion}`);
+  log(`  items:        ${manifest.items.length}`);
   if (dryRun) log('  ' + yellow('mode:         dry-run (no files will be written)'));
   log('');
 
-  // Safety: same guard as cmdUninstall — never rmSync anything that
-  // doesn't look like a ba-toolkit folder.
-  if (path.basename(destDir) !== 'ba-toolkit') {
-    logError(`Refusing to upgrade suspicious destination (not a ba-toolkit folder): ${destDir}`);
-    process.exit(1);
-  }
-
-  // Count files in the existing install for the dry-run preview.
   if (dryRun) {
-    let existingCount = 0;
-    (function walk(d) {
-      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
-        const p = path.join(d, entry.name);
-        if (entry.isDirectory()) walk(p);
-        else existingCount++;
-      }
-    })(destDir);
-    log('  ' + yellow(`would remove ${existingCount} existing files`));
+    log('  ' + yellow(`would remove ${manifest.items.length} previously-installed items, then re-copy the new tree`));
   } else {
-    log('  ' + green('Removing previous install...'));
-    fs.rmSync(destDir, { recursive: true, force: true });
+    log('  ' + green('Removing previous install (manifest-driven)...'));
+    removeManifestItems(destDir, manifest);
   }
 
   const ok = await runInstall({
@@ -956,51 +1391,49 @@ async function cmdUninstall(args) {
   log(`  destination:  ${destDir}`);
   log(`  scope:        ${effectiveGlobal ? 'global (user-wide)' : 'project-level'}`);
   if (dryRun) log('  ' + yellow('mode:         dry-run (no files will be removed)'));
-  log('');
 
-  // Safety: this is the only place in the CLI that calls fs.rmSync with
-  // recursive: true. Refuse to proceed unless the destination is clearly
-  // a ba-toolkit folder (the install paths in AGENTS all end in
-  // `ba-toolkit/`). Without this check, a corrupted AGENTS entry or a
-  // future bug could turn this into `rm -rf $HOME`.
-  if (path.basename(destDir) !== 'ba-toolkit') {
-    logError(`Refusing to remove suspicious destination (not a ba-toolkit folder): ${destDir}`);
-    process.exit(1);
-  }
+  warnLegacyInstall(agent);
 
   if (!fs.existsSync(destDir)) {
+    log('');
     log('  ' + gray(`Nothing to uninstall — ${destDir} does not exist.`));
     log('');
     return;
   }
 
-  // Count files for the preview message and final confirmation.
-  let fileCount = 0;
-  (function walk(d) {
-    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
-      const p = path.join(d, entry.name);
-      if (entry.isDirectory()) walk(p);
-      else fileCount++;
-    }
-  })(destDir);
+  // The manifest is the proof we own anything in this directory. The
+  // destination is shared with the user's other skills/rules, so we
+  // can't just `rm -rf destDir` — we'd nuke unrelated files. Without
+  // a manifest, refuse and tell the user.
+  const manifest = readManifest(destDir);
+  if (!manifest) {
+    log('');
+    log('  ' + gray('No BA Toolkit manifest found in this destination.'));
+    log('  ' + gray('Either nothing was installed here, or the install pre-dates v2.0.'));
+    log('  ' + gray('For a v1.x legacy wrapper, see the warning above (if any) for the path to remove manually.'));
+    log('');
+    return;
+  }
 
-  log(`  Found ${bold(fileCount)} files in the destination.`);
+  log('');
+  log(`  installed:    ${manifest.version}`);
+  log(`  items:        ${bold(manifest.items.length)} (${manifest.items.slice(0, 5).join(', ')}${manifest.items.length > 5 ? ', …' : ''})`);
 
   if (dryRun) {
-    log('  ' + yellow(`would remove ${fileCount} files from ${destDir}.`));
+    log('  ' + yellow(`would remove ${manifest.items.length} items + the manifest from ${destDir}`));
     log('');
     return;
   }
 
   log('');
-  const answer = await prompt(`  Remove ${destDir}? (y/N): `);
+  const answer = await prompt(`  Remove ${manifest.items.length} BA Toolkit items from ${destDir}? (y/N): `);
   if (answer.toLowerCase() !== 'y') {
     log('  Cancelled.');
     log('');
     return;
   }
-  fs.rmSync(destDir, { recursive: true, force: true });
-  log('  ' + green(`Removed ${fileCount} files from ${destDir}.`));
+  removeManifestItems(destDir, manifest);
+  log('  ' + green(`Removed ${manifest.items.length} items.`));
   log('  ' + yellow(agent.restartHint));
   log('');
 }
@@ -1143,8 +1576,12 @@ module.exports = {
   levenshtein,
   closestMatch,
   parseSkillFrontmatter,
-  readSentinel,
+  readManifest,
+  detectLegacyInstall,
   renderAgentsMd,
+  mergeAgentsMd,
+  menuStep,
+  renderMenu,
   KNOWN_FLAGS,
   DOMAINS,
   AGENTS,