@haposoft/cafekit 0.15.3 → 0.16.0-rc.1

package/bin/install.js

@@ -28,7 +28,9 @@ const {
   copyClaudeRuntimeFiles,
   removeObsoleteClaudeRuntimeFiles,
   copyClaudeMdFile,
-  copyRulesDirectory
+  ensureSharedAgentsMdCore,
+  copyRulesDirectory,
+  removeObsoleteAgents
 } = require('./phases/claude-runtime');
 const { mergeClaudeSettings } = require('./phases/claude-settings');
 const { installOpenCodeRuntime } = require('./phases/opencode-runtime');
@@ -57,6 +59,7 @@ function installPlatform(ctx, platformKey) {
   ctx.ui.startSpinner(ctx.t('installingPlatform', { name: platform.name }));
 
   copyPlatformFiles(ctx, platformKey);
+  removeObsoleteAgents(ctx, platformKey);
 
   if (platformKey === 'claude') {
     copyRoutingFile(ctx, platformKey);
@@ -174,6 +177,7 @@ async function main() {
       ctx.backupDir = backup.snapshot([...targets, '.gitignore'], ctx.runId);
     }
 
+    ensureSharedAgentsMdCore(ctx);
     for (const platformKey of ctx.platforms) {
       installPlatform(ctx, platformKey);
     }

package/bin/lib/codex-install.js

@@ -1,7 +1,9 @@
 'use strict';
 
 const path = require('path');
+const { normalizeSourcePaths } = require('./copy-utils');
 const { splitFrontmatter } = require('./codex-frontmatter');
+const { preserveAddressingSection } = require('./instruction-blocks');
 
 const CODEX_BLOCK_START = '<!-- CAFEKIT CODEX START -->';
 const CODEX_BLOCK_END = '<!-- CAFEKIT CODEX END -->';
@@ -14,7 +16,7 @@ const AGENT_NAMES = [
   'deployer',
   'docs-keeper',
   'git-ops',
-  'god-developer',
+  'implementer',
   'inspector',
   'project-manager',
   'researcher',
@@ -63,10 +65,13 @@ function applyReplacements(content, replacements) {
 }
 
 function normalizeRuntimePaths(content) {
-  return content
-    .replace(/\.claude\/skills\b/g, '.agents/skills')
-    .replace(/\.claude\\skills\b/g, '.agents\\skills')
-    .replace(/\.claude(?=[/\\])/g, '.codex')
+  return normalizeSourcePaths(content, {
+    runtimeRoot: '.codex',
+    skillsRoot: '.agents/skills'
+  })
+    .replace(/(?<!~\/)\.claude\/skills\b/g, '.agents/skills')
+    .replace(/(?<!~\\)\.claude\\skills\b/g, '.agents\\skills')
+    .replace(/(?<!~\/)\.claude(?=[/\\])/g, '.codex')
     .replace(/(['"])\.claude\1/g, '$1.codex$1')
     .replace(/`\.claude`/g, '`.codex`');
 }
@@ -163,8 +168,17 @@ function managedRange(content) {
 
 function upsertManagedCodexBlock(existingContent, blockContent) {
   const existing = String(existingContent || '');
-  const block = `${CODEX_BLOCK_START}\n${String(blockContent).trim()}\n${CODEX_BLOCK_END}`;
+  let body = String(blockContent).trim();
+  // Reinstall replaces the managed block in place. If the new template dropped
+  // its Addressing section, carry the exact section over from the existing
+  // managed block so the saved address survives for setupAddressing. Only reads
+  // the managed body — never user-owned sections outside the block.
   const range = managedRange(existing);
+  if (range) {
+    const existingBody = existing.slice(range.start + CODEX_BLOCK_START.length, range.end);
+    body = preserveAddressingSection(body, existingBody);
+  }
+  const block = `${CODEX_BLOCK_START}\n${body}\n${CODEX_BLOCK_END}`;
   if (range === false) return existing;
   if (range) {
     return `${existing.slice(0, range.start)}${block}${existing.slice(range.end + CODEX_BLOCK_END.length)}`;
@@ -190,6 +204,7 @@ module.exports = {
   getCodexCopyOptions,
   codexAgentName,
   convertCodexAgentContent,
+  managedRange,
   upsertManagedCodexBlock,
   transformManagedCodexContent
 };

package/bin/lib/context.js

@@ -16,6 +16,7 @@ const packageJson = require('../../package.json');
 const { getOpenCodeCopyOptions } = require('./opencode-install');
 const { isInteractive, createUI } = require('./ui');
 const { resolveLang, createTranslator } = require('./i18n');
+const { normalizeSourcePaths } = require('./copy-utils');
 
 const INSTALL_COMMAND = `npx ${packageJson.name}@${packageJson.version}`;
 
@@ -82,7 +83,7 @@ const PLATFORMS = {
     commandPrefix: '/',
     sourceDir: 'claude',       // Maps to src/claude/
     sourceSubdir: 'commands',  // Source subfolder within src/claude/
-    backupTargets: ['.claude', 'CLAUDE.md'],
+    backupTargets: ['.claude', 'CLAUDE.md', 'AGENTS.md'],
     capabilities: {
       skills: true,
       agents: true,
@@ -216,7 +217,16 @@ function getCopyOptions(platformKey, baseOptions = {}) {
     // during module initialization.
     return require('./codex-install').getCodexCopyOptions(baseOptions);
   }
-  return baseOptions;
+  if (platformKey !== 'claude') return baseOptions;
+  return {
+    ...baseOptions,
+    transform: (content, sourcePath) => normalizeSourcePaths(
+      typeof baseOptions.transform === 'function'
+        ? baseOptions.transform(content, sourcePath)
+        : content,
+      { runtimeRoot: '.claude', skillsRoot: '.claude/skills' }
+    )
+  };
 }
 
 // ═══════════════════════════════════════════════════════════
@@ -305,11 +315,12 @@ function buildContext(argv, runId) {
   const options = parseInstallerArgs(argv);
   // Interactive only on a real TTY and not when --yes/CI forces non-interactive.
   const interactive = isInteractive() && !options.yes;
-  // Language: --lang wins; otherwise English (an interactive prompt may change it).
+  // Language: --lang wins; otherwise English for installer UI only (an interactive
+  // prompt or saved runtime locale may change both values).
   const lang = options.lang ? resolveLang(options.lang) : 'en';
-  // ctx.locale = the string that gets written to CLAUDE.md / runtime.json as the AI's response language.
-  // For known codes it mirrors lang; for "other", it's set later by setLang.
-  const locale = options.lang || 'en';
+  // A missing locale means "follow the user's language". Never persist the UI
+  // fallback as an AI response-language override on fresh installs/upgrades.
+  const locale = options.lang ? options.lang : null;
   return {
     argv,
     runId,

package/bin/lib/copy-utils.js

@@ -11,6 +11,33 @@ function isTextAsset(filePath) {
   return TEXT_REWRITE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
 }
 
+// Generated artifacts never ship as runtime payload: the coverage db, the
+// Python bytecode cache directory, and bytecode files. Skipping them here keeps
+// both copyRecursive and copyManagedTree (and the OpenCode plugin copy path
+// built on copyRecursive) from ever copying build residue.
+function isGeneratedArtifact(name) {
+  const base = String(name || '');
+  return (
+    base === '.coverage'
+    || base === '__pycache__'
+    || base.endsWith('.pyc')
+    || base.endsWith('.pyo')
+  );
+}
+
+function normalizeSourcePaths(content, options = {}) {
+  const runtimeRoot = String(options.runtimeRoot || '.claude');
+  const skillsRoot = String(options.skillsRoot || `${runtimeRoot}/skills`);
+  const runtimeRootWindows = runtimeRoot.replace(/\//g, '\\');
+  const skillsRootWindows = skillsRoot.replace(/\//g, '\\');
+
+  return String(content)
+    .replace(/packages\/spec\/src\/claude\/skills(?=\/|$)/g, skillsRoot)
+    .replace(/packages\\spec\\src\\claude\\skills(?=\\|$)/g, skillsRootWindows)
+    .replace(/packages\/spec\/src\/claude(?=\/|$)/g, runtimeRoot)
+    .replace(/packages\\spec\\src\\claude(?=\\|$)/g, runtimeRootWindows);
+}
+
 function copyRecursive(src, dest, options = {}) {
   const exists = fs.existsSync(src);
   const stats = exists && fs.statSync(src);
@@ -22,10 +49,12 @@ function copyRecursive(src, dest, options = {}) {
       fs.mkdirSync(dest, { recursive: true });
     }
     fs.readdirSync(src).forEach(childItemName => {
+      if (isGeneratedArtifact(childItemName)) return;
       const destItemName = childItemName === 'gitignore' ? '.gitignore' : childItemName;
       copyRecursive(path.join(src, childItemName), path.join(dest, destItemName), options);
     });
   } else {
+    if (isGeneratedArtifact(path.basename(src))) return;
     if (fs.existsSync(dest) && !shouldOverwriteManagedFiles) {
       return;
     }
@@ -56,6 +85,8 @@ function readJsonFile(filePath) {
 module.exports = {
   TEXT_REWRITE_EXTENSIONS,
   isTextAsset,
+  isGeneratedArtifact,
+  normalizeSourcePaths,
   copyRecursive,
   readJsonFile
 };

package/bin/lib/instruction-blocks.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const CORE_BLOCK_START = '<!-- CAFEKIT CORE START -->';
+const CORE_BLOCK_END = '<!-- CAFEKIT CORE END -->';
+
+function managedRange(content, startMarker = CORE_BLOCK_START, endMarker = CORE_BLOCK_END) {
+  const existing = String(content || '');
+  const start = existing.indexOf(startMarker);
+  const end = existing.indexOf(endMarker);
+  if (start < 0 && end < 0) return null;
+  const duplicateStart = existing.indexOf(startMarker, start + startMarker.length);
+  const duplicateEnd = existing.indexOf(endMarker, end + endMarker.length);
+  if (start < 0 || end <= start || duplicateStart >= 0 || duplicateEnd >= 0) return false;
+  return {
+    start,
+    end: end + endMarker.length,
+    bodyStart: start + startMarker.length,
+    bodyEnd: end
+  };
+}
+
+function migrateExactLegacyBlock(existingContent, startMarker, endMarker, replacementContent) {
+  const existing = String(existingContent || '');
+  const range = managedRange(existing, startMarker, endMarker);
+  if (!range) return existing;
+  const body = existing.slice(range.bodyStart, range.bodyEnd).trim();
+  if (body !== String(replacementContent).trim()) return existing;
+  const block = `${CORE_BLOCK_START}\n${String(replacementContent).trim()}\n${CORE_BLOCK_END}`;
+  return `${existing.slice(0, range.start)}${block}${existing.slice(range.end)}`;
+}
+
+function upsertManagedCoreBlock(existingContent, coreContent) {
+  const existing = String(existingContent || '');
+  const block = `${CORE_BLOCK_START}\n${String(coreContent).trim()}\n${CORE_BLOCK_END}`;
+  const range = managedRange(existing);
+  if (range === false) return existing;
+  if (range) {
+    return `${existing.slice(0, range.start)}${block}${existing.slice(range.end)}`;
+  }
+  if (!existing) return `${block}\n`;
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${separator}${block}\n`;
+}
+
+function transformManagedCoreContent(content, transform) {
+  const existing = String(content || '');
+  const range = managedRange(existing);
+  if (!range || typeof transform !== 'function') return existing;
+  const body = existing.slice(range.bodyStart, range.bodyEnd);
+  return `${existing.slice(0, range.bodyStart)}${transform(body)}${existing.slice(range.bodyEnd)}`;
+}
+
+// Mirrors the section regex used by post-install configureAddressing so an
+// extracted section round-trips exactly back into the managed body.
+const ADDRESSING_SECTION_RE = /##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?(?=\n##|\n*$)/;
+
+/** Extract the exact Addressing section (heading through next `##`) from a body, or null. */
+function extractAddressingSection(body) {
+  const match = String(body || '').match(ADDRESSING_SECTION_RE);
+  return match ? match[0].replace(/\n+$/, '') : null;
+}
+
+/**
+ * When a reinstall template drops the Addressing section, carry the exact one
+ * from the existing CafeKit-managed block so the saved address survives for
+ * setupAddressing. Only reads the managed block body — never user-owned
+ * sections outside the block, never the shared CORE block.
+ */
+function preserveAddressingSection(newBody, existingManagedBody) {
+  if (extractAddressingSection(newBody) !== null) return newBody;
+  const section = extractAddressingSection(existingManagedBody);
+  if (section === null) return newBody;
+  return `${String(newBody).trimEnd()}\n\n${section}`;
+}
+
+module.exports = {
+  CORE_BLOCK_START,
+  CORE_BLOCK_END,
+  managedRange,
+  migrateExactLegacyBlock,
+  upsertManagedCoreBlock,
+  transformManagedCoreContent,
+  extractAddressingSection,
+  preserveAddressingSection
+};

package/bin/lib/managed-writer.js

@@ -20,7 +20,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { isTextAsset } = require('./copy-utils');
+const { isTextAsset, isGeneratedArtifact } = require('./copy-utils');
 const manifest = require('./manifest');
 const { assertNoSymlinkPath } = require('./path-safety');
 
@@ -151,6 +151,9 @@ function copyManagedTree(opts) {
   const stats = fs.statSync(src);
   if (stats.isDirectory()) {
     for (const childName of fs.readdirSync(src)) {
+      // Generated artifacts (coverage, Python bytecode) are not runtime
+      // payload — skip so they never ship.
+      if (isGeneratedArtifact(childName)) continue;
       const destName = childName === 'gitignore' ? '.gitignore' : childName;
       const childAgg = copyManagedTree({
         ...opts,

package/bin/lib/opencode-install.js

@@ -3,7 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
-const { copyRecursive, isTextAsset } = require('./copy-utils');
+const { copyRecursive, isTextAsset, isGeneratedArtifact, normalizeSourcePaths } = require('./copy-utils');
+const { preserveAddressingSection } = require('./instruction-blocks');
 
 const SPEC_ROOT = path.resolve(__dirname, '..', '..');
 const OPENCODE_FOLDER = '.opencode';
@@ -48,7 +49,7 @@ const OPENCODE_COMMAND_TEMPLATES = [
   {
     fileName: 'develop.md',
     skillName: 'develop',
-    agent: 'god-developer',
+    agent: 'implementer',
     subtask: true,
     description: 'Implement approved CafeKit spec tasks with scope fidelity.'
   },
@@ -76,7 +77,7 @@ const OPENCODE_COMMAND_TEMPLATES = [
   {
     fileName: 'hotfix.md',
     skillName: 'hotfix',
-    agent: 'god-developer',
+    agent: 'implementer',
     subtask: true,
     description: 'Apply a scout-first, narrow production hotfix.'
   },
@@ -113,7 +114,7 @@ const OPENCODE_COMMAND_TEMPLATES = [
   {
     fileName: 'backend-development.md',
     skillName: 'backend-development',
-    agent: 'god-developer',
+    agent: 'implementer',
     subtask: true,
     description: 'Implement backend services, APIs, data layers, and integrations.'
   },
@@ -148,7 +149,7 @@ const OPENCODE_COMMAND_TEMPLATES = [
   {
     fileName: 'frontend-development.md',
     skillName: 'frontend-development',
-    agent: 'god-developer',
+    agent: 'implementer',
     subtask: true,
     description: 'Build React/TypeScript UI components and frontend features.'
   },
@@ -162,7 +163,7 @@ const OPENCODE_COMMAND_TEMPLATES = [
   {
     fileName: 'mobile-development.md',
     skillName: 'mobile-development',
-    agent: 'god-developer',
+    agent: 'implementer',
     subtask: true,
     description: 'Implement iOS, Android, React Native, or Flutter mobile features.'
   },
@@ -268,9 +269,12 @@ function formatOpenCodeValue(value) {
 // Applied to every text asset copied into .opencode/ so the installed
 // content points at the self-contained OpenCode runtime layout.
 function normalizeOpenCodeBody(content) {
-  return content
-    .replace(/\.claude\/(agents|commands|skills|rules|scripts|references|hooks)\b/g, '.opencode/$1')
-    .replace(/\.claude\\(agents|commands|skills|rules|scripts|references|hooks)\b/g, '.opencode\\$1')
+  return normalizeSourcePaths(content, {
+    runtimeRoot: '.opencode',
+    skillsRoot: '.opencode/skills'
+  })
+    .replace(/(?<!~\/)\.claude\/(agents|commands|skills|rules|scripts|references|hooks)\b/g, '.opencode/$1')
+    .replace(/(?<!~\\)\.claude\\(agents|commands|skills|rules|scripts|references|hooks)\b/g, '.opencode\\$1')
     .replace(/\.claude\/runtime\.json/g, '.opencode/runtime.json')
     .replace(/\.claude\/ROUTING\.md/g, '.opencode/ROUTING.md')
     .replace(/\.claude\/\.env/g, '.opencode/.env')
@@ -409,16 +413,44 @@ function createOpenCodeAgentsContent(sourceContent) {
   return adaptedContent.replace('## Core Objective', `${openCodeRuntimeBlock}\n## Core Objective`);
 }
 
+function managedOpenCodeRange(content) {
+  const existing = String(content || '');
+  const startMarker = '<!-- CAFEKIT OPENCODE START -->';
+  const endMarker = '<!-- CAFEKIT OPENCODE END -->';
+  const start = existing.indexOf(startMarker);
+  const end = existing.indexOf(endMarker);
+  if (start < 0 && end < 0) return null;
+  const duplicateStart = existing.indexOf(startMarker, start + startMarker.length);
+  const duplicateEnd = existing.indexOf(endMarker, end + endMarker.length);
+  if (start < 0 || end <= start || duplicateStart >= 0 || duplicateEnd >= 0) return false;
+  return {
+    start,
+    end: end + endMarker.length,
+    bodyStart: start + startMarker.length,
+    bodyEnd: end
+  };
+}
+
+
 function upsertCafeKitAgentsBlock(existingContent, blockContent) {
   const start = '<!-- CAFEKIT OPENCODE START -->';
   const end = '<!-- CAFEKIT OPENCODE END -->';
-  const managedBlock = `${start}\n${blockContent.trim()}\n${end}`;
-  const blockPattern = new RegExp(`${start}[\\s\\S]*?${end}`);
-
-  if (blockPattern.test(existingContent)) {
-    return existingContent.replace(blockPattern, managedBlock);
+  let body = String(blockContent).trim();
+  // Reinstall replaces the managed block in place. If the new template dropped
+  // its Addressing section, carry the exact section over from the existing
+  // managed block so the saved address survives for setupAddressing. Only reads
+  // the managed body — never user-owned sections outside the block.
+  const range = managedOpenCodeRange(existingContent);
+  if (range) {
+    const existingBody = existingContent.slice(range.bodyStart, range.bodyEnd);
+    body = preserveAddressingSection(body, existingBody);
+  }
+  const managedBlock = `${start}\n${body}\n${end}`;
+  if (range === false) return existingContent;
+  if (range) {
+    return `${existingContent.slice(0, range.start)}${managedBlock}${existingContent.slice(range.end)}`;
   }
-
+  if (!existingContent) return `${managedBlock}\n`;
   // Pre-managed-block releases wrote the shipped template as the whole file.
   // Wrap only an exact shipped prefix and preserve any user/Codex suffix.
   if (existingContent.startsWith(blockContent)) {
@@ -431,25 +463,23 @@ function upsertCafeKitAgentsBlock(existingContent, blockContent) {
   ) {
     return `${managedBlock}${existingContent.slice(trimmedLegacy.length)}`;
   }
-  if (!existingContent) return `${managedBlock}\n`;
-
   const separator = existingContent.endsWith('\n') ? '\n' : '\n\n';
   return `${existingContent}${separator}${managedBlock}\n`;
 }
 
+/** Transform only the CafeKit-owned OpenCode body, preserving surrounding bytes. */
+function transformManagedOpenCodeContent(content, transform) {
+  const existing = String(content || '');
+  const range = managedOpenCodeRange(existing);
+  if (!range || typeof transform !== 'function') return existing;
+  const body = existing.slice(range.bodyStart, range.bodyEnd);
+  return `${existing.slice(0, range.bodyStart)}${transform(body)}${existing.slice(range.bodyEnd)}`;
+}
+
 function getOpenCodeAgentsTemplateContent() {
   const openCodeTemplate = path.join(SPEC_ROOT, 'src/opencode/AGENTS.md');
-
-  if (fs.existsSync(openCodeTemplate)) {
-    return normalizeOpenCodeBody(fs.readFileSync(openCodeTemplate, 'utf8'));
-  }
-
-  const claudeTemplate = path.join(SPEC_ROOT, 'src/claude/CLAUDE.md');
-  if (!fs.existsSync(claudeTemplate)) {
-    return null;
-  }
-
-  return createOpenCodeAgentsContent(fs.readFileSync(claudeTemplate, 'utf8'));
+  if (!fs.existsSync(openCodeTemplate)) return null;
+  return normalizeOpenCodeBody(fs.readFileSync(openCodeTemplate, 'utf8'));
 }
 
 // Copy OpenCode project instructions to AGENTS.md at the project root.
@@ -462,6 +492,11 @@ function copyOpenCodeAgentsMdFile(platformKey, results, options = {}) {
   if (content) {
     const destinationExists = fs.existsSync(dest);
     const existingContent = destinationExists ? fs.readFileSync(dest, 'utf8') : '';
+    if (managedOpenCodeRange(existingContent) === false) {
+      console.log(`  ⚠ AGENTS.md: malformed CafeKit OPENCODE marker topology; preserved ${dest} without writing`);
+      results.errors++;
+      return;
+    }
     const nextContent = upsertCafeKitAgentsBlock(existingContent, content);
 
     if (nextContent === existingContent) {
@@ -537,6 +572,10 @@ function copyOpenCodePlugins(platformKey, results, options = {}) {
 
   const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
   entries.forEach(entry => {
+    // Skip generated artifacts before any directory/file handling, matching
+    // the filter copyRecursive applies to directory children.
+    if (isGeneratedArtifact(entry.name)) return;
+
     const sourcePath = path.join(sourceDir, entry.name);
     const destPath = path.join(targetDir, entry.name);
 
@@ -555,8 +594,12 @@ function copyOpenCodePlugins(platformKey, results, options = {}) {
       return;
     }
 
-    const sourceContent = fs.readFileSync(sourcePath, 'utf8');
-    fs.writeFileSync(destPath, sourceContent, 'utf8');
+    if (isTextAsset(sourcePath)) {
+      const sourceContent = fs.readFileSync(sourcePath, 'utf8');
+      fs.writeFileSync(destPath, normalizeOpenCodeBody(sourceContent), 'utf8');
+    } else {
+      fs.copyFileSync(sourcePath, destPath);
+    }
 
     if (destExists) {
       console.log(`  ↻ Plugin updated: ${entry.name}`);
@@ -846,6 +889,8 @@ module.exports = {
   convertOpenCodeAgentContent,
   convertOpenCodeCommandContent,
   copyOpenCodeAgentsMdFile,
+  managedOpenCodeRange,
+  transformManagedOpenCodeContent,
   copyOpenCodeSharedRuntimeFiles,
   copyOpenCodePlugins,
   copyOpenCodeCommandTemplates,

package/bin/phases/claude-runtime.js

@@ -19,10 +19,18 @@ const { sha256 } = require('../lib/manifest');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
 const { normalizeOpenCodeBody } = require('../lib/opencode-install');
+const {
+  upsertManagedCoreBlock,
+  managedRange,
+  migrateExactLegacyBlock,
+  preserveAddressingSection
+} = require('../lib/instruction-blocks');
 
 const SRC = path.join(__dirname, '../../src');
 const CLAUDE_START = '<!-- CAFEKIT CLAUDE START -->';
 const CLAUDE_END = '<!-- CAFEKIT CLAUDE END -->';
+const LEGACY_CORE_START = '<!-- CAFEKIT CLAUDE AGENTS START -->';
+const LEGACY_CORE_END = '<!-- CAFEKIT CLAUDE AGENTS END -->';
 
 function managedClaudeBlock(template) {
   return `${CLAUDE_START}\n${template.trimEnd()}\n${CLAUDE_END}`;
@@ -30,9 +38,11 @@ function managedClaudeBlock(template) {
 
 function managedClaudeRange(content) {
   const start = content.indexOf(CLAUDE_START);
-  if (start === -1) return null;
-  const endStart = content.indexOf(CLAUDE_END, start + CLAUDE_START.length);
-  if (endStart === -1) return null;
+  const endStart = content.indexOf(CLAUDE_END);
+  if (start === -1 && endStart === -1) return null;
+  const duplicateStart = content.indexOf(CLAUDE_START, start + CLAUDE_START.length);
+  const duplicateEnd = content.indexOf(CLAUDE_END, endStart + CLAUDE_END.length);
+  if (start === -1 || endStart <= start || duplicateStart >= 0 || duplicateEnd >= 0) return false;
   return { start, end: endStart + CLAUDE_END.length, bodyStart: start + CLAUDE_START.length, bodyEnd: endStart };
 }
 
@@ -45,7 +55,19 @@ function transformManagedClaudeContent(content, transform) {
 }
 
 function upsertManagedClaudeBlock(existing, template, legacyOwned) {
-  const block = managedClaudeBlock(template);
+  // When an existing managed block present, reinstall replaces it. If the new
+  // template dropped its Addressing section, carry the saved section over from
+  // the existing managed block so the user's address survives for setupAddressing.
+  const existingRange = managedClaudeRange(existing);
+  if (existingRange === false) return existing;
+  const existingManagedBody = existingRange
+    ? existing.slice(existingRange.bodyStart, existingRange.bodyEnd)
+    : '';
+  let body = template;
+  if (existingRange) {
+    body = preserveAddressingSection(template, existingManagedBody);
+  }
+  const block = managedClaudeBlock(body);
   const range = managedClaudeRange(existing);
   if (range) {
     return `${existing.slice(0, range.start)}${block}${existing.slice(range.end)}`;
@@ -60,6 +82,44 @@ function upsertManagedClaudeBlock(existing, template, legacyOwned) {
   return `${existing}${separator}${block}\n`;
 }
 
+function ensureSharedAgentsMdCore(ctx) {
+  const src = path.join(SRC, 'common/AGENTS.md');
+  const dest = 'AGENTS.md';
+  if (!fs.existsSync(src)) {
+    ctx.ui.warn('Shared AGENTS.md template not found');
+    ctx.results.missingDependencies++;
+    return;
+  }
+
+  const template = fs.readFileSync(src, 'utf8');
+  const exists = fs.existsSync(dest);
+  const existing = exists ? fs.readFileSync(dest, 'utf8') : '';
+  if (managedRange(existing) === false) {
+    ctx.ui.warn(`AGENTS.md: malformed CafeKit CORE marker topology; preserved ${dest} without writing`);
+    ctx.results.errors++;
+    return;
+  }
+  const migrated = migrateExactLegacyBlock(
+    existing,
+    LEGACY_CORE_START,
+    LEGACY_CORE_END,
+    template
+  );
+  const next = upsertManagedCoreBlock(migrated, template);
+  const action = !exists ? 'created' : next === existing ? 'unchanged' : 'updated';
+
+  if (!ctx.dryRun && action !== 'unchanged') {
+    fs.writeFileSync(dest, next, 'utf8');
+  }
+  report(ctx, action, 'AGENTS.md (shared CafeKit core)');
+}
+
+/** Install the shared AGENTS.md core used by Claude's @AGENTS.md import. */
+function copyClaudeAgentsMdFile(ctx, platformKey) {
+  if (platformKey !== 'claude') return;
+  ensureSharedAgentsMdCore(ctx);
+}
+
 /** Copy ROUTING.md (SKILLS_DIR substituted; OpenCode body normalized). */
 function copyRoutingFile(ctx, platformKey) {
   const platform = PLATFORMS[platformKey];
@@ -132,6 +192,37 @@ function removeObsoleteClaudeRuntimeFiles(ctx, platformKey) {
   });
 }
 
+/** Remove renamed agents only when ownership manifest proves pristine bytes. */
+function removeObsoleteAgents(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const obsolete = ctx.manifest?.obsolete?.agents?.[platformKey] || [];
+  const tracker = ctx.trackers?.[platformKey];
+  if (!platform || !tracker || obsolete.length === 0) return;
+
+  const ownership = ctx.ownership?.[platform.folder] || { files: {} };
+  for (const relPath of obsolete) {
+    const targetPath = path.join(platform.folder, relPath);
+    if (!fs.existsSync(targetPath)) continue;
+
+    const key = tracker.keyFor(targetPath);
+    const recorded = ownership.files?.[key];
+    const currentHash = sha256(fs.readFileSync(targetPath));
+    if (recorded?.sha256 === currentHash) {
+      if (!ctx.dryRun) {
+        fs.rmSync(targetPath, { force: true });
+        tracker.prune(key);
+      }
+      ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete agent: ${targetPath}`);
+      ctx.results.updated++;
+      continue;
+    }
+
+    ctx.ui.warn(`Preserved user-owned obsolete agent: ${targetPath}`);
+    ctx.results.preserved++;
+    ctx.results.preservedFiles.push(targetPath);
+  }
+}
+
 /** Install CLAUDE.md at the project root (ownership-aware). Claude only. */
 function copyClaudeMdFile(ctx, platformKey) {
   if (platformKey !== 'claude') return;
@@ -152,6 +243,11 @@ function copyClaudeMdFile(ctx, platformKey) {
   const template = fs.readFileSync(src, 'utf8');
   const exists = fs.existsSync(dest);
   const existing = exists ? fs.readFileSync(dest, 'utf8') : '';
+  if (managedClaudeRange(existing) === false) {
+    ctx.ui.warn(`CLAUDE.md: malformed CafeKit CLAUDE marker topology; preserved ${dest} without writing`);
+    ctx.results.errors++;
+    return;
+  }
   const legacyRecord = ctx.ownership?.[PLATFORMS.claude.folder]?.files?.['../CLAUDE.md'];
   const legacyOwned = Boolean(legacyRecord && legacyRecord.sha256 === sha256(existing));
   const next = upsertManagedClaudeBlock(existing, template, legacyOwned);
@@ -187,6 +283,9 @@ module.exports = {
   copyClaudeRuntimeFiles,
   removeObsoleteClaudeRuntimeFiles,
   copyClaudeMdFile,
+  copyClaudeAgentsMdFile,
+  ensureSharedAgentsMdCore,
   copyRulesDirectory,
+  removeObsoleteAgents,
   transformManagedClaudeContent
 };