devlyn-cli 4.1.0 → 4.2.1

package/bin/devlyn.js

@@ -4,34 +4,37 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const readline = require('readline');
 const { execSync } = require('child_process');
 
 const CONFIG_SOURCE = path.join(__dirname, '..', 'config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
 const PKG = require('../package.json');
-const { updateInstructions, InstructionError, holdsDevlynDefaults } = require('./instructions');
+const { updateInstructions, InstructionError, holdsDevlynDefaults, importsAgentsMd } = require('./instructions');
+const { contentHash, fingerprint, isOsMetadata, trackedPaths } = require('./skill-ownership');
+const SKILL_HISTORY = require('./skill-history.json');
 
 // The devlyn skill bundle installed into every skill-capable agent's loader
 // directory. Single source of truth so codex/omp/pi stay in lockstep — adding a
 // skill here installs it everywhere.
-const DEVLYN_CORE_SKILLS = ['devlyn-resolve', 'devlyn-ideate', 'devlyn-design-ui', 'devlyn-engines', 'devlyn-queue', '_shared'];
+const DEVLYN_CORE_SKILLS = ['devlyn-ideate', 'devlyn-engines', '_shared'];
 // 4.0.0 renamed the colon-named skills to the Agent Skills standard (`[a-z0-9-]`, name ==
 // folder): Git for Windows cannot check out a folder with ':' in its name. Installs from 3.x
 // and earlier keep the old folder under either spelling (':' or npm's U+F03A extraction
 // alias). Both are removed, and an optional skill that was installed is installed again
 // under its new name in the same place.
 const RENAMED_SKILLS = {
-  'devlyn:resolve': 'devlyn-resolve',
   'devlyn:ideate': 'devlyn-ideate',
-  'devlyn:design-ui': 'devlyn-design-ui',
   'devlyn:engines': 'devlyn-engines',
-  'devlyn:queue': 'devlyn-queue',
   'devlyn:pencil-pull': 'devlyn-pencil-pull',
   'devlyn:pencil-push': 'devlyn-pencil-push',
   'devlyn:reap': 'devlyn-reap',
 };
 const DEVLYN_INSTALL_MARKER = '.devlyn-install.json';
+// Project settings earlier releases added for the retired pipeline.
+const RETIRED_STOP_HOOK = 'python3 "$CLAUDE_PROJECT_DIR/.claude/skills/_shared/resolve-stop-hook.py"';
+const RETIRED_ENV = ['CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS'];
+const RETIRED_PERMISSIONS = ['Write(.devlyn/**)', 'Edit(.devlyn/**)', 'Bash(git add *)', 'Bash(git commit *)',
+  'Bash(git diff *)', 'Bash(git status *)', 'Bash(git log *)'];
 
 // Every spelling a colon name can have on disk: its own and npm's U+F03A extraction alias.
 function legacySkillPaths(root, name) {
@@ -80,13 +83,13 @@ const RETIRED_SKILL_MD_SHA256 = {
   ]),
 };
 
-// Whether `dir` is a real folder whose only file (dotfiles such as .DS_Store aside) is a SKILL.md
+// Whether `dir` is a real folder whose only file, besides OS metadata, is a SKILL.md
 // with an LF-normalized SHA-256 in `hashes`: an unedited copy devlyn-cli shipped, not something
 // the user added to or wrote.
 function isShippedCopy(dir, hashes) {
   const skill = path.join(dir, 'SKILL.md');
   return fs.lstatSync(dir, { throwIfNoEntry: false })?.isDirectory() === true
-    && fs.readdirSync(dir).filter((name) => !name.startsWith('.')).length === 1
+    && fs.readdirSync(dir).filter((name) => !isOsMetadata(path.join(dir, name))).length === 1
     && fs.lstatSync(skill, { throwIfNoEntry: false })?.isFile() === true
     && hashes.has(crypto.createHash('sha256')
       .update(fs.readFileSync(skill, 'utf8').replace(/\r\n/g, '\n')).digest('hex'));
@@ -102,24 +105,25 @@ function skillRoots(target, global) {
 
 // A devlyn Claude install in this scope. Globally only the marker a `--global --claude` run
 // writes counts; in a project also a devlyn skill (0.6.0 and later), command (0.2-0.5) or
-// CLAUDE.md with devlyn defaults, which a team may commit while ignoring .claude/. An optional
-// devlyn skill is not one: 4.0.1 put those into .claude/skills without the Claude target. A
-// CLAUDE.md link (often to AGENTS.md) is not the Claude target's file: updateInstructions
-// refuses links.
+// CLAUDE.md with devlyn defaults, held or imported from AGENTS.md, which a team may commit
+// while ignoring .claude/. An optional devlyn skill is not one: 4.0.1 put those into
+// .claude/skills without the Claude target. A CLAUDE.md link (often to AGENTS.md) is not the
+// Claude target's file: updateInstructions refuses links.
 function hasDevlynClaude(global) {
   const claudeDir = path.dirname(skillRoots('claude', global)[0]);
   if (global) return fs.existsSync(path.join(claudeDir, 'skills', DEVLYN_INSTALL_MARKER));
   const names = (dir) => (fs.existsSync(dir) ? fs.readdirSync(dir) : []);
   const optional = new Set(OPTIONAL_ADDONS.map((addon) => addon.name));
   const instructions = path.join(path.dirname(claudeDir), 'CLAUDE.md');
+  const claude = fs.lstatSync(instructions, { throwIfNoEntry: false })?.isFile() ? fs.readFileSync(instructions, 'utf8') : '';
   return names(path.join(claudeDir, 'skills')).some((name) => name === DEVLYN_INSTALL_MARKER
       || (name.startsWith('devlyn') && !optional.has(name.replace(/[:\uF03A]/g, '-'))))
     || names(path.join(claudeDir, 'commands')).some((name) => name.startsWith('devlyn.'))
-    || (fs.lstatSync(instructions, { throwIfNoEntry: false })?.isFile() === true
-      && holdsDevlynDefaults('CLAUDE.md', fs.readFileSync(instructions, 'utf8')));
+    || holdsDevlynDefaults('CLAUDE.md', claude) || importsAgentsDefaults(claude);
 }
 
-// Commands removed in previous versions; the project Claude install deletes them from .claude/.
+// Commands removed in previous versions; the project Claude install deletes them from .claude/
+// when they hold the bytes a version shipped (SKILL_HISTORY.commands).
 const DEPRECATED_FILES = [
   'commands/devlyn.handoff.md', // removed in v0.2.0
   'commands/devlyn.clean.md', // migrated to skills in v0.6.0
@@ -144,7 +148,7 @@ const DEPRECATED_FILES = [
 // Skill directories renamed from devlyn-* to devlyn:* in v0.7.x, plus
 // iter-0034 Phase 4 cutover (2026-05-03): 15 user skills deleted and 3 moved
 // to optional-skills/. Listed here so post-cutover `npx devlyn-cli` upgrades
-// force-remove stale legacy skill dirs from downstream `~/.claude/skills/`
+// remove verified, unchanged legacy skill dirs from downstream `~/.claude/skills/`
 // even though the source dirs no longer exist (the installer replaces only
 // the skills it ships — without this list, deleted-from-source skills persist
 // in user installs forever).
@@ -183,6 +187,15 @@ const DEPRECATED_DIRS = [
   // so users who previously opted in get their stale copies purged on upgrade.
   'skills/devlyn:team-design-ui',
   'skills/devlyn:design-system',
+  // Retired after 4.1.0 (design-ui deleted; the intent queue moved into
+  // devlyn-ideate; resolve retired). All were core skills, so their 3.x and
+  // 4.x folders go.
+  'skills/devlyn-design-ui',
+  'skills/devlyn:design-ui',
+  'skills/devlyn-queue',
+  'skills/devlyn:queue',
+  'skills/devlyn-resolve',
+  'skills/devlyn:resolve',
 ];
 
 function projectDir() {
@@ -257,10 +270,7 @@ const OPTIONAL_ADDONS = [
   { name: 'anthropics/skills', desc: 'Official Anthropic skill-creator with eval framework and description optimizer', type: 'external' },
   { name: 'Leonxlnx/taste-skill', desc: 'Premium frontend design skills — modern layouts, animations, and visual refinement', type: 'external' },
   // MCP servers (installed via claude mcp add)
-  // Note: the Codex integration uses the local `codex` CLI binary (not MCP).
-  // Install the CLI separately per https://platform.openai.com/docs/codex — the
-  // pair/risk-probe routes fail closed when Codex is required but unavailable.
-  { name: 'playwright', desc: 'Playwright MCP for browser testing — powers /devlyn-resolve BUILD_GATE browser tier', type: 'mcp', command: 'npx -y @playwright/mcp@latest' },
+  { name: 'playwright', desc: 'Playwright MCP for browser testing', type: 'mcp', command: 'npx -y @playwright/mcp@latest' },
 ];
 
 function log(msg, color = 'reset') {
@@ -306,23 +316,8 @@ function listContents() {
   showLogo();
   log('─'.repeat(44), 'dim');
 
-  const templatesDir = path.join(CONFIG_SOURCE, 'templates');
   const skillsDir = path.join(CONFIG_SOURCE, 'skills');
 
-  // List templates
-  if (fs.existsSync(templatesDir)) {
-    const templates = fs.readdirSync(templatesDir).filter((f) => f.endsWith('.md'));
-    if (templates.length > 0) {
-      log('\n📄 Templates:', 'blue');
-      templates.forEach((file) => {
-        const name = file.replace('.md', '');
-        const desc = getDescription(path.join(templatesDir, file));
-        log(`  ${COLORS.green}${name}${COLORS.reset}`);
-        if (desc) log(`     ${COLORS.dim}${desc}${COLORS.reset}`);
-      });
-    }
-  }
-
   // List skills
   if (fs.existsSync(skillsDir)) {
     const skills = fs.readdirSync(skillsDir).filter((d) => {
@@ -381,15 +376,22 @@ function cleanupDeprecated(skillsDir) {
 // copy is refreshed in place. Any other folder under a 4.0 name is the user's own; `-y` leaves it.
 function retireRenamedSkills(skillsDir) {
   const optional = new Set(OPTIONAL_ADDONS.filter((addon) => addon.type === 'local').map((addon) => addon.name));
+  const refreshed = [];
   for (const [oldName, newName] of Object.entries(RENAMED_SKILLS)) {
     const found = legacySkillPaths(skillsDir, oldName).filter((fullPath) => fs.existsSync(fullPath));
-    if (found.length > 0 && optional.has(newName)) installOptionalSkillInto(skillsDir, newName);
-    else if (isShippedCopy(path.join(skillsDir, newName), PRE_STANDARD_SKILL_MD_SHA256)) refreshPreStandardCopy(skillsDir, newName);
+    if (found.length > 0 && optional.has(newName)) {
+      installOptionalSkillInto(skillsDir, newName);
+      refreshed.push(newName);
+    } else if (isShippedCopy(path.join(skillsDir, newName), PRE_STANDARD_SKILL_MD_SHA256)) {
+      refreshPreStandardCopy(skillsDir, newName);
+      refreshed.push(newName);
+    }
     for (const fullPath of found) {
       fs.rmSync(fullPath, { recursive: true, force: true });
       log(`  ✕ ${path.basename(fullPath)}/ (renamed to ${newName})`, 'dim');
     }
   }
+  return refreshed;
 }
 
 function copyRecursive(src, dest, baseDir) {
@@ -417,6 +419,101 @@ function clearInstallMarker(skillsDir) {
   fs.rmSync(path.join(skillsDir, DEVLYN_INSTALL_MARKER), { force: true });
 }
 
+function readInstallManifest(root) {
+  const markerPath = path.join(root, DEVLYN_INSTALL_MARKER);
+  const stat = fs.lstatSync(markerPath, { throwIfNoEntry: false });
+  if (!stat) return {};
+  if (!stat.isFile()) throw new Error(`not a regular install marker: ${markerPath}`);
+  const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+  return marker?.package === PKG.name && marker.schemaVersion === 1 ? marker.skills || {} : {};
+}
+
+// Enumerate every directory this install may replace, migrate or remove, before
+// touching any target. Optional addons must be selected before this preflight too.
+function plannedSkills(root, optionalNames = []) {
+  const names = new Set([...DEVLYN_CORE_SKILLS, ...optionalNames]);
+  for (const relative of DEPRECATED_DIRS) {
+    for (const full of legacySkillPaths(root, path.basename(relative))) names.add(path.basename(full));
+  }
+  for (const [oldName, newName] of Object.entries(RENAMED_SKILLS)) {
+    const oldPaths = legacySkillPaths(root, oldName);
+    oldPaths.forEach((full) => names.add(path.basename(full)));
+    if (oldPaths.some((full) => fs.lstatSync(full, { throwIfNoEntry: false }))
+        || isShippedCopy(path.join(root, newName), PRE_STANDARD_SKILL_MD_SHA256)) names.add(newName);
+  }
+  for (const [name, hashes] of Object.entries(RETIRED_SKILL_MD_SHA256)) {
+    if (isShippedCopy(path.join(root, name), hashes)) names.add(name);
+  }
+  return names;
+}
+
+// `commandDir`: the project .claude/ whose DEPRECATED_FILES this install deletes, or null.
+function preflightSkills(roots, optionalNames = [], commandDir = null) {
+  const conflicts = [];
+  try {
+    // Do not follow a commands link into another installation either.
+    const commands = commandDir && fs.lstatSync(path.join(commandDir, 'commands'), { throwIfNoEntry: false });
+    if (commands && !commands.isDirectory()) throw new Error('not a real directory');
+    const tracked = commandDir ? trackedPaths(path.join(commandDir, 'commands')) : [];
+    for (const relPath of commandDir ? DEPRECATED_FILES : []) {
+      const fullPath = path.join(commandDir, relPath);
+      const stat = fs.lstatSync(fullPath, { throwIfNoEntry: false });
+      if (!stat || (stat.isFile() && SKILL_HISTORY.commands[relPath].includes(contentHash(fullPath)))) continue;
+      const isTracked = tracked.some((file) => file.toLowerCase() === fullPath.toLowerCase());
+      conflicts.push(`${fullPath}: ${isTracked ? 'git-tracked; ' : ''}`
+        + (stat.isFile() ? 'fingerprint mismatch with known shipped copies' : 'link or special file'));
+    }
+  } catch (error) {
+    conflicts.push(`${path.join(commandDir, 'commands')}: ${error.message}`);
+  }
+  for (const root of roots) {
+    try {
+      // Do not follow an agent-directory or skill-root link into another installation.
+      for (const dir of [path.dirname(root), root]) {
+        const stat = fs.lstatSync(dir, { throwIfNoEntry: false });
+        if (stat && !stat.isDirectory()) throw new Error(`not a real directory: ${dir}`);
+      }
+      const tracked = trackedPaths(root);
+      const manifest = readInstallManifest(root);
+      for (const name of plannedSkills(root, optionalNames)) {
+        const dest = path.join(root, name);
+        const isTracked = tracked.some((file) => file.toLowerCase() === dest.toLowerCase()
+          || file.toLowerCase().startsWith(dest.toLowerCase() + path.sep));
+        try {
+          if (!fs.lstatSync(dest, { throwIfNoEntry: false })) {
+            if (isTracked) throw new Error('missing contents; cannot verify installer ownership');
+            continue;
+          }
+          const actual = fingerprint(dest);
+          const logicalName = name.replace(/[:\uF03A]/g, '-');
+          const source = path.join(DEVLYN_CORE_SKILLS.includes(logicalName)
+            ? path.join(CONFIG_SOURCE, 'skills') : OPTIONAL_SKILLS_SOURCE, logicalName);
+          const current = fs.existsSync(source) && fingerprint(source) === actual;
+          const historical = SKILL_HISTORY.skills[logicalName]?.includes(actual);
+          const singleFile = isShippedCopy(dest, RETIRED_SKILL_MD_SHA256[name] || PRE_STANDARD_SKILL_MD_SHA256);
+          if (!current && !historical && !singleFile && manifest[name] !== actual) {
+            throw new Error(manifest[name] ? 'modified contents (install manifest fingerprint mismatch)'
+              : fs.existsSync(source) || SKILL_HISTORY.skills[logicalName]?.length
+                ? 'fingerprint mismatch with known shipped copies'
+                : 'unknown installer ownership (no fingerprint history for this copy)');
+          }
+        } catch (error) {
+          conflicts.push(`${dest}: ${isTracked ? 'git-tracked; ' : ''}${error.message}`);
+        }
+      }
+    } catch (error) {
+      conflicts.push(`${root}: ${error.message}`);
+    }
+  }
+  if (conflicts.length) {
+    throw new InstructionError('Installation refused; nothing was changed:\n'
+      + conflicts.map((conflict) => `  - ${conflict}`).join('\n')
+      + '\nMove these out of the install path, or back them up and remove them, then rerun.'
+      + '\nFor tracked paths, also remove them from the Git index.'
+      + '\nRerun the same command after resolving every conflict; -y does not bypass this check.');
+  }
+}
+
 function assertCompleteSkillInstall(sourceSkillsDir, skillsDir, skillNames) {
   function complete(src, dest) {
     if (!fs.existsSync(src) || !fs.existsSync(dest)) return false;
@@ -436,13 +533,14 @@ function assertCompleteSkillInstall(sourceSkillsDir, skillsDir, skillNames) {
   }
 }
 
-function writeInstallMarker(skillsDir) {
+function writeInstallMarker(skillsDir, names, previous) {
   const markerPath = path.join(skillsDir, DEVLYN_INSTALL_MARKER);
   const tempPath = `${markerPath}.${process.pid}.tmp`;
   const marker = {
     schemaVersion: 1,
     package: PKG.name,
     version: PKG.version,
+    skills: { ...previous, ...Object.fromEntries(names.map((name) => [name, fingerprint(path.join(skillsDir, name))])) },
   };
   try {
     fs.writeFileSync(tempPath, JSON.stringify(marker, null, 2) + '\n', {
@@ -456,141 +554,65 @@ function writeInstallMarker(skillsDir) {
   }
 }
 
-function multiSelect(items, preselectedIndices = []) {
-  return new Promise((resolve) => {
-    const selected = new Set(preselectedIndices.filter((i) => i >= 0 && i < items.length));
-    let cursor = 0;
-    let firstRender = true;
-
-    const render = () => {
-      // Move cursor up to redraw (skip on first render)
-      const totalLines = items.length * 2 + 2; // 2 lines per item + header + blank
-      if (!firstRender) {
-        process.stdout.write(`\x1b[${totalLines}A\x1b[0J`); // Move up and clear to end of screen
-      }
-      firstRender = false;
-
-      console.log(`${COLORS.dim}(↑↓ navigate, space select, enter confirm)${COLORS.reset}\n`);
-
-      items.forEach((item, i) => {
-        const checkbox = selected.has(i) ? `${COLORS.green}◉${COLORS.reset}` : `${COLORS.dim}○${COLORS.reset}`;
-        const pointer = i === cursor ? `${COLORS.cyan}❯${COLORS.reset}` : ' ';
-        const name = i === cursor ? `${COLORS.cyan}${item.name}${COLORS.reset}` : item.name;
-        const tagLabel = item.type === 'mcp' ? 'mcp' : item.type === 'local' ? 'skill' : 'pack';
-        const tagColor = item.type === 'mcp' ? COLORS.green : item.type === 'local' ? COLORS.magenta : COLORS.cyan;
-        const tag = `${tagColor}${tagLabel}${COLORS.reset}`;
-        console.log(`${pointer} ${checkbox} ${name}${item.type ? ` ${COLORS.dim}[${tag}${COLORS.dim}]${COLORS.reset}` : ''}`);
-        console.log(`    ${COLORS.dim}${item.desc}${COLORS.reset}`);
-      });
-    };
-
-    render();
-
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding('utf8');
-
-    const onKeypress = (key) => {
-      // Ctrl+C
-      if (key === '\u0003') {
-        process.stdin.setRawMode(false);
-        process.stdin.removeListener('data', onKeypress);
-        process.exit();
-      }
-
-      // Enter
-      if (key === '\r' || key === '\n') {
-        process.stdin.setRawMode(false);
-        process.stdin.removeListener('data', onKeypress);
-        process.stdin.pause();
-        console.log('');
-        resolve([...selected].map((i) => items[i]));
-        return;
-      }
-
-      // Space - toggle selection
-      if (key === ' ') {
-        if (selected.has(cursor)) {
-          selected.delete(cursor);
-        } else {
-          selected.add(cursor);
-        }
-        render();
-        return;
-      }
-
-      // Arrow up or k
-      if (key === '\x1b[A' || key === 'k') {
-        cursor = cursor > 0 ? cursor - 1 : items.length - 1;
-        render();
-        return;
-      }
-
-      // Arrow down or j
-      if (key === '\x1b[B' || key === 'j') {
-        cursor = cursor < items.length - 1 ? cursor + 1 : 0;
-        render();
-        return;
-      }
-
-      // 'a' - select all
-      if (key === 'a') {
-        if (selected.size === items.length) {
-          selected.clear();
-        } else {
-          items.forEach((_, i) => selected.add(i));
-        }
-        render();
-        return;
-      }
-    };
-
-    process.stdin.on('data', onKeypress);
+// One Inquirer menu, imported only when shown (Inquirer is ESM). The page gets the terminal
+// rows left after everything else the menu draws, so a redraw never scrolls it into
+// duplicates. Ctrl+C cancels the install.
+async function ask(module, help, config) {
+  const { default: prompt } = await import(module);
+  const { stdin: input, stdout: output } = process;
+  const columns = output.columns || 80;
+  // Most rows a text wraps to: an ASCII character takes one cell, any other at most two.
+  const rows = (text = '') => Math.ceil([...text].reduce((cells, c) => cells + (c.codePointAt(0) < 0x80 ? 1 : 2), 0) / columns);
+  // Message, blank line, the active choice's description, key help, and the line Inquirer
+  // adds when the help exactly fills the width.
+  const reserved = rows(`? ${config.message}`) + 1 + Math.max(...config.choices.map((choice) => rows(choice.description))) + rows(help) + 1;
+  try {
+    return await prompt({
+      ...config,
+      pageSize: Math.max(1, (output.rows || 24) - reserved),
+      theme: { keybindings: ['vim'], style: { keysHelpTip: () => help } },
+    }, { input, output });
+  } catch (error) {
+    if (error.name !== 'ExitPromptError') throw error;
+    console.log('Installation cancelled.');
+    process.exit(0);
+  }
+}
+
+// Checkbox menu (space toggles, a toggles all); resolves to the chosen items.
+function multiSelect(message, items, preselectedIndices = []) {
+  return ask('@inquirer/checkbox', '↑↓ navigate · space select · a all · enter confirm', {
+    message,
+    choices: items.map((item, index) => ({
+      name: item.type ? `${item.name} [${item.type === 'mcp' ? 'mcp' : item.type === 'local' ? 'skill' : 'pack'}]` : item.name,
+      short: item.name,
+      description: item.desc,
+      value: item,
+      checked: preselectedIndices.includes(index),
+    })),
   });
 }
 
-// One of `items` (↑↓ move, Enter confirms); resolves to the chosen index.
-function singleSelect(items, initial) {
-  return new Promise((resolve) => {
-    let cursor = initial;
-    let drawn = false;
-    const render = () => {
-      if (drawn) process.stdout.write(`\x1b[${items.length + 2}A\x1b[0J`);
-      drawn = true;
-      console.log(`${COLORS.dim}(↑↓ navigate, enter confirm)${COLORS.reset}\n`);
-      items.forEach((item, i) => console.log(i === cursor ? `${COLORS.cyan}❯ ${item}${COLORS.reset}` : `  ${item}`));
-    };
-    render();
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding('utf8');
-    const onKeypress = (key) => {
-      if (key === '\u0003') {
-        process.stdin.setRawMode(false);
-        process.exit();
-      }
-      if (key === '\r' || key === '\n') {
-        process.stdin.setRawMode(false);
-        process.stdin.removeListener('data', onKeypress);
-        process.stdin.pause();
-        console.log('');
-        resolve(cursor);
-      } else if (['\x1b[A', 'k', '\x1b[B', 'j'].includes(key)) {
-        cursor = (cursor + (key === '\x1b[A' || key === 'k' ? items.length - 1 : 1)) % items.length;
-        render();
-      }
-    };
-    process.stdin.on('data', onKeypress);
+// One of `items`; resolves to the chosen index.
+function singleSelect(message, items, initial) {
+  return ask('@inquirer/select', '↑↓ navigate · enter confirm', {
+    message,
+    choices: items.map((name, index) => ({ name, value: index })),
+    default: initial,
   });
 }
 
+// After install(), whose preflight already cleared every selected addon before any change.
 function installLocalSkill(skillName, roots) {
   if (!fs.existsSync(path.join(OPTIONAL_SKILLS_SOURCE, skillName))) {
     log(`   ⚠️  Skill "${skillName}" not found`, 'yellow');
     return false;
   }
   log(`\n🛠️  Installing ${skillName}...`, 'cyan');
-  for (const root of roots) installOptionalSkillInto(root, skillName);
+  for (const root of roots) {
+    installOptionalSkillInto(root, skillName);
+    writeInstallMarker(root, [skillName], readInstallManifest(root));
+  }
   return true;
 }
 
@@ -660,6 +682,7 @@ function installCoreSkills(skillsDir) {
   const sourceSkillsDir = path.join(CONFIG_SOURCE, 'skills');
   log(`\n📁 Installing devlyn skills to ${skillsDir.replace(os.homedir(), '~')}`, 'green');
   fs.mkdirSync(skillsDir, { recursive: true });
+  const previous = readInstallManifest(skillsDir);
   clearInstallMarker(skillsDir);
   const removed = cleanupDeprecated(skillsDir);
   if (removed > 0) {
@@ -674,8 +697,8 @@ function installCoreSkills(skillsDir) {
     copyRecursive(src, dest, skillsDir);
   }
   assertCompleteSkillInstall(sourceSkillsDir, skillsDir, DEVLYN_CORE_SKILLS);
-  retireRenamedSkills(skillsDir);
-  writeInstallMarker(skillsDir);
+  const refreshed = retireRenamedSkills(skillsDir);
+  writeInstallMarker(skillsDir, [...DEVLYN_CORE_SKILLS, ...refreshed], previous);
 }
 
 // Keep installer-managed pipeline state and install metadata out of git.
@@ -726,14 +749,56 @@ function installAgentsProject(withClaude) {
   ignoreInGit(['.devlyn/', '.agents/skills/.devlyn-install.json']);
 }
 
-// Project CLAUDE.md and .claude/: skills, templates, commit conventions and settings.
+// Whether Claude Code reads the devlyn defaults of AGENTS.md through an `@AGENTS.md` import in this CLAUDE.md text.
+// An AGENTS.md that is CLAUDE.md under another name holds CLAUDE.md's own defaults.
+function importsAgentsDefaults(claude) {
+  const agents = path.join(projectDir(), 'AGENTS.md');
+  return importsAgentsMd(claude) && !agentsMdIsClaudeMd() && fs.statSync(agents, { throwIfNoEntry: false })?.isFile() === true
+    && holdsDevlynDefaults('AGENTS.md', fs.readFileSync(agents, 'utf8'));
+}
+
+// Claude Code reads AGENTS.md only where no CLAUDE.md exists, or through a CLAUDE.md that imports it. So a new
+// CLAUDE.md imports an existing AGENTS.md, and a CLAUDE.md importing an AGENTS.md that holds devlyn defaults holds no
+// copy of its own, not even one it got while AGENTS.md lacked the block. Only the AGENTS.md target updates those defaults,
+// together with .agents/skills, so the Claude target stops while they need an update.
+function installClaudeInstructions() {
+  const file = path.join(projectDir(), 'CLAUDE.md');
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+  const initial = !stat && fs.statSync(path.join(projectDir(), 'AGENTS.md'), { throwIfNoEntry: false })?.isFile() ? '@AGENTS.md\n' : '';
+  const imported = importsAgentsDefaults(stat?.isFile() ? fs.readFileSync(file, 'utf8') : initial);
+  if (imported && updateInstructions('AGENTS.md', '', true, false)) {
+    throw new InstructionError('Claude Code reads AGENTS.md here, and its devlyn defaults need an update. Codex, omp, Pi and Grok '
+      + 'read them too, with .agents/skills, so choose AGENTS.md as well (npx devlyn-cli -y --claude) to update both together.');
+  }
+  updateInstructions('CLAUDE.md', initial, !imported);
+  if (imported) log('  → CLAUDE.md imports AGENTS.md, which holds the devlyn block', 'dim');
+}
+
+// Project CLAUDE.md and .claude/: skills and settings.
 function installClaudeCore() {
-  updateInstructions('CLAUDE.md');
   const skillsDir = skillRoots('claude', false)[0];
   const targetDir = path.dirname(skillsDir);
-  for (const entry of fs.readdirSync(CONFIG_SOURCE)) {
-    if (entry !== 'skills') copyRecursive(path.join(CONFIG_SOURCE, entry), path.join(targetDir, entry), targetDir);
+  // Read before any write, so settings this install cannot merge leave the Claude target as it was.
+  const settingsPath = path.join(targetDir, 'settings.json');
+  const unmergeable = (reason) => new InstructionError(`Cannot merge .claude/settings.json: ${reason}. `
+    + 'CLAUDE.md and .claude/ are unchanged; fix the file and rerun the same install command.');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      // Claude Code accepts a leading byte order mark.
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8').replace(/^\uFEFF/, ''));
+    } catch (error) {
+      throw unmergeable(error.message);
+    }
+  }
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw unmergeable('root must be a JSON object');
+  }
+  if (Object.prototype.hasOwnProperty.call(settings, 'env')
+      && (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env))) {
+    throw unmergeable('env must be a JSON object');
   }
+  installClaudeInstructions();
   for (const relPath of DEPRECATED_FILES) {
     const fullPath = path.join(targetDir, relPath);
     if (fs.existsSync(fullPath)) {
@@ -744,108 +809,51 @@ function installClaudeCore() {
   installCoreSkills(skillsDir);
   ignoreInGit(['.devlyn/', '.claude/skills/.devlyn-install.json']);
 
-  // Enable agent teams in project settings
-  const settingsPath = path.join(targetDir, 'settings.json');
-  let settings = {};
-  if (fs.existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-    } catch (error) {
-      throw new Error(`Cannot merge .claude/settings.json: ${error.message}`);
-    }
-  }
-  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
-    throw new Error('Cannot merge .claude/settings.json: root must be a JSON object');
-  }
-  const hasOwnSetting = (key) => Object.prototype.hasOwnProperty.call(settings, key);
+  // One-hour foreground Bash calls and one-hour prompt caching serve a drain host that waits in the foreground.
   let settingsChanged = false;
-  if (!hasOwnSetting('env')) {
+  if (!Object.prototype.hasOwnProperty.call(settings, 'env')) {
     settings.env = {};
     settingsChanged = true;
   }
-  if (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env)) {
-    throw new Error('Cannot merge .claude/settings.json: env must be a JSON object');
-  }
-  // Auto-allow pipeline state directory and common git commands so resolve doesn't prompt
-  if (!hasOwnSetting('permissions')) {
-    settings.permissions = {};
-    settingsChanged = true;
-  }
-  if (!settings.permissions || typeof settings.permissions !== 'object' || Array.isArray(settings.permissions)) {
-    throw new Error('Cannot merge .claude/settings.json: permissions must be a JSON object');
-  }
-  if (!Object.prototype.hasOwnProperty.call(settings.permissions, 'allow')) {
-    settings.permissions.allow = [];
-    settingsChanged = true;
-  }
-  if (!Array.isArray(settings.permissions.allow)) {
-    throw new Error('Cannot merge .claude/settings.json: permissions.allow must be an array');
-  }
-  const pipelinePermissions = [
-    'Write(.devlyn/**)',
-    'Edit(.devlyn/**)',
-    'Bash(git add *)',
-    'Bash(git commit *)',
-    'Bash(git diff *)',
-    'Bash(git status *)',
-    'Bash(git log *)',
-  ];
-  for (const perm of pipelinePermissions) {
-    if (!settings.permissions.allow.includes(perm)) {
-      settings.permissions.allow.push(perm);
-      settingsChanged = true;
-    }
-  }
   if (!settings.env.ENABLE_PROMPT_CACHING_1H) {
     settings.env.ENABLE_PROMPT_CACHING_1H = 'true';
     settingsChanged = true;
   }
-  if (!settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) {
-    settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
-    settingsChanged = true;
-  }
   const bashMaxTimeoutMs = Number.parseInt(settings.env.BASH_MAX_TIMEOUT_MS, 10);
   if (!Number.isFinite(bashMaxTimeoutMs) || bashMaxTimeoutMs < 3600000) {
     settings.env.BASH_MAX_TIMEOUT_MS = '3600000';
     settingsChanged = true;
   }
-  if (!hasOwnSetting('hooks')) {
-    settings.hooks = {};
-    settingsChanged = true;
-  }
-  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
-    throw new Error('Cannot merge .claude/settings.json: hooks must be a JSON object');
-  }
-  if (!Object.prototype.hasOwnProperty.call(settings.hooks, 'Stop')) {
-    settings.hooks.Stop = [];
-    settingsChanged = true;
-  }
-  if (!Array.isArray(settings.hooks.Stop)) {
-    throw new Error('Cannot merge .claude/settings.json: hooks.Stop must be an array');
-  }
-  const stopHookCommand = 'python3 "$CLAUDE_PROJECT_DIR/.claude/skills/_shared/resolve-stop-hook.py"';
-  const stopHookInstalled = settings.hooks.Stop.some((entry) => (
-    entry && Array.isArray(entry.hooks) && entry.hooks.some((hook) => (
-      hook && hook.type === 'command' && hook.command === stopHookCommand
-    ))
-  ));
-  if (!stopHookInstalled) {
-    settings.hooks.Stop.push({
-      hooks: [{ type: 'command', command: stopHookCommand, timeout: 30 }],
-    });
+  // Remove exactly the retired Stop hook command, and its entry only when nothing else is left in it.
+  const retiredHook = (hook) => hook?.type === 'command' && hook.command === RETIRED_STOP_HOOK;
+  const stop = Array.isArray(settings.hooks?.Stop) ? settings.hooks.Stop : [];
+  for (let i = stop.length - 1; i >= 0; i--) {
+    const hooks = stop[i]?.hooks;
+    if (!Array.isArray(hooks) || !hooks.some(retiredHook)) continue;
+    stop[i].hooks = hooks.filter((hook) => !retiredHook(hook));
+    if (stop[i].hooks.length === 0 && Object.keys(stop[i]).length === 1) stop.splice(i, 1);
+    log('  ✕ settings.json Stop hook of the retired pipeline (removed)', 'dim');
     settingsChanged = true;
   }
   if (settingsChanged) {
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    log('  → settings.json (agent teams + one-hour Bash max + 1h prompt caching + pipeline permissions + Stop hook)', 'dim');
+    log('  → settings.json', 'dim');
+  }
+  // Their ownership cannot be established, so the other retired settings stay; name the ones present.
+  const retired = [
+    ...RETIRED_ENV.filter((key) => Object.prototype.hasOwnProperty.call(settings.env, key)),
+    ...RETIRED_PERMISSIONS.filter((rule) => Array.isArray(settings.permissions?.allow) && settings.permissions.allow.includes(rule)),
+  ];
+  if (retired.length > 0) {
+    log(`  Retired devlyn settings may remain in .claude/settings.json: ${retired.join(', ')} — delete those you did not add yourself.`, 'yellow');
   }
 }
 
 // Installs the targets in one scope; returns the skill roots written.
-function install(targets, global) {
+function install(targets, global, optionalNames = []) {
   // In the home folder CLAUDE.md, AGENTS.md (agents read a parent folder's too) and
-  // .claude/settings.json (permissions, Stop hook) would apply to every project. Same folder by
-  // identity, so a link or another spelling of the path is caught too.
+  // .claude/settings.json would apply to every project. Same folder by identity, so a link or
+  // another spelling of the path is caught too.
   const home = fs.statSync(os.homedir(), { bigint: true, throwIfNoEntry: false });
   const here = fs.statSync(projectDir(), { bigint: true });
   if (!global && home?.dev === here.dev && home?.ino === here.ino) {
@@ -853,7 +861,10 @@ function install(targets, global) {
       + 'would apply to every project. Run from a project folder, or use --global for skills only.');
   }
   const roots = targets.flatMap((target) => skillRoots(target, global));
-  for (const target of targets) {
+  preflightSkills(roots, optionalNames,
+    !global && targets.includes('claude') ? path.dirname(skillRoots('claude', false)[0]) : null);
+  // AGENTS.md first, whatever order the menu gave: a new CLAUDE.md holds the block only when AGENTS.md does not.
+  for (const target of ['agents', 'claude'].filter((name) => targets.includes(name))) {
     if (global) skillRoots(target, true).forEach((root) => installCoreSkills(root));
     else if (target === 'agents') installAgentsProject(targets.includes('claude'));
     else installClaudeCore();
@@ -906,13 +917,12 @@ async function init({ yes, claude, global }) {
     return;
   }
 
-  log('\n🎯 What to install:\n', 'blue');
   const targetOptions = [
     { key: 'agents', name: 'AGENTS.md — Codex · omp · Pi · Grok', desc: 'AGENTS.md + .agents/skills' },
-    { key: 'claude', name: 'CLAUDE.md — Claude Code', desc: 'CLAUDE.md + .claude/ (skills, templates, settings)' },
+    { key: 'claude', name: 'CLAUDE.md — Claude Code', desc: 'CLAUDE.md + .claude/ (skills, settings)' },
   ];
   const preselected = claude || hasDevlynClaude(false) || (global && hasDevlynClaude(true)) ? [0, 1] : [0];
-  const targets = (await multiSelect(targetOptions, preselected)).map((option) => option.key);
+  const targets = (await multiSelect('What to install', targetOptions, preselected)).map((option) => option.key);
 
   if (targets.length === 0) {
     log('\n💡 Nothing selected — nothing installed.', 'yellow');
@@ -920,14 +930,10 @@ async function init({ yes, claude, global }) {
     return;
   }
 
-  log('📍 Where:\n', 'blue');
-  const scope = await singleSelect(['This project', 'Global — every project on this machine'], global ? 1 : 0);
-  const roots = install(targets, scope === 1);
-
+  const scope = await singleSelect('Where', ['This project', 'Global — every project on this machine'], global ? 1 : 0);
   // Ask about optional addons (local skills + external packs; MCP servers belong to Claude Code)
-  log('\n📚 Optional skills & packs:\n', 'blue');
-
-  const selectedAddons = await multiSelect(OPTIONAL_ADDONS.filter((addon) => addon.type !== 'mcp' || targets.includes('claude')));
+  const selectedAddons = await multiSelect('Optional skills & packs', OPTIONAL_ADDONS.filter((addon) => addon.type !== 'mcp' || targets.includes('claude')));
+  const roots = install(targets, scope === 1, selectedAddons.filter((addon) => addon.type === 'local').map((addon) => addon.name));
 
   if (selectedAddons.length > 0) {
     for (const addon of selectedAddons) {
@@ -951,7 +957,7 @@ function showHelp() {
   log('  npx devlyn-cli -y            Without prompts: AGENTS.md + .agents/skills, plus CLAUDE.md + .claude/ if this project has them');
   log('  npx devlyn-cli -y --claude   Also install CLAUDE.md + .claude/ for Claude Code');
   log('  npx devlyn-cli -y --global   Skills only, for every project on this machine (~/.agents/skills, ~/.codex/skills; ~/.claude/skills with --claude, or when it already has a devlyn install)');
-  log('  npx devlyn-cli list          List available skills & templates');
+  log('  npx devlyn-cli list          List available skills');
   log('  npx devlyn-cli --help        Show this help\n');
   log('Optional skills (select during install):', 'green');
   OPTIONAL_ADDONS.filter((a) => a.type === 'local').forEach((skill) => {