@haposoft/cafekit 0.15.1 → 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/i18n.js

@@ -79,7 +79,7 @@ const MESSAGES = {
     pipFailed:             '{skill} — some packages failed. Retry:\n  {cmd}',
     npmInstalling:         'Installing Node packages: {skill}',
     npmInstalled:          '{skill} — Node packages ready',
-    npmFailed:             '{skill} — npm install failed. Check the log and retry in: {dir}',
+    npmFailed:             '{skill} — npm install failed ({error}). Retry in: {dir}',
     playwrightInstalling:  'Downloading Playwright browser for {skill}',
     playwrightReady:       '{skill} — Playwright browser ready',
     playwrightSkipped:     '{skill} — Playwright browser download skipped',
@@ -132,6 +132,9 @@ const MESSAGES = {
     langKept:             'Language: {lang} (saved — skipping prompt)',
     platformKept:         'Platform: {names} (saved — skipping prompt)',
 
+    // Add more platforms prompt (interactive, prior install exists)
+    addPlatformsPrompt:   'Existing platforms: {names}. Add more?',
+
     // Version picker
     versionPickPrompt:    'Select CafeKit version to install:',
     versionPickCurrent:   '(installed)',
@@ -199,7 +202,7 @@ const MESSAGES = {
     pipFailed:             '{skill} — 一部のパッケージが失敗しました。再試行:\n  {cmd}',
     npmInstalling:         'Node パッケージをインストール中: {skill}',
     npmInstalled:          '{skill} — Node パッケージの準備ができました',
-    npmFailed:             '{skill} — npm install に失敗しました。{dir} で手動再試行してください。',
+    npmFailed:             '{skill} — npm install に失敗しました ({error})。{dir} で手動再試行してください。',
     playwrightInstalling:  '{skill} 用の Playwright ブラウザをダウンロード中',
     playwrightReady:       '{skill} — Playwright ブラウザの準備ができました',
     playwrightSkipped:     '{skill} — Playwright ブラウザのダウンロードをスキップしました',
@@ -249,6 +252,9 @@ const MESSAGES = {
     langKept:             '言語: {lang} (保存済み — スキップ)',
     platformKept:         'プラットフォーム: {names} (保存済み — スキップ)',
 
+    // Add more platforms prompt (interactive, prior install exists)
+    addPlatformsPrompt:   '既存プラットフォーム: {names}。さらに追加しますか？',
+
     // Version picker
     versionPickPrompt:    'インストールする CafeKit バージョンを選択:',
     versionPickCurrent:   '(インストール済み)',
@@ -316,7 +322,7 @@ const MESSAGES = {
     pipFailed:             '{skill} — một số gói cài thất bại. Chạy lại thủ công:\n  {cmd}',
     npmInstalling:         'Đang cài gói Node: {skill}',
     npmInstalled:          '{skill} — gói Node đã sẵn sàng',
-    npmFailed:             '{skill} — npm install thất bại. Hãy thử lại trong: {dir}',
+    npmFailed:             '{skill} — npm install thất bại ({error}). Hãy thử lại trong: {dir}',
     playwrightInstalling:  'Đang tải Playwright browser cho {skill}',
     playwrightReady:       '{skill} — Playwright browser đã sẵn sàng',
     playwrightSkipped:     '{skill} — đã bỏ qua tải Playwright browser',
@@ -366,6 +372,9 @@ const MESSAGES = {
     langKept:             'Ngôn ngữ: {lang} (đã lưu — bỏ qua chọn lại)',
     platformKept:         'Nền tảng: {names} (đã lưu — bỏ qua chọn lại)',
 
+    // Add more platforms prompt (interactive, prior install exists)
+    addPlatformsPrompt:   'Nền tảng hiện có: {names}. Thêm nền tảng khác?',
+
     // Version picker
     versionPickPrompt:    'Chọn phiên bản CafeKit để cài:',
     versionPickCurrent:   '(đang cài)',

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/lib/skill-deps.js

@@ -17,6 +17,19 @@ const { spawnSync, spawn } = require('child_process');
 
 const isWindows = process.platform === 'win32';
 
+/**
+ * npm and npx are `.cmd` launchers on Windows, so Node cannot spawn them
+ * directly without a command interpreter. Keep the shell boundary explicit;
+ * all arguments passed here are installer-owned constants.
+ */
+function resolvePackageCommand(command, args, platform = process.platform, env = process.env) {
+  if (platform !== 'win32') return { command, args };
+  return {
+    command: env.ComSpec || env.COMSPEC || 'cmd.exe',
+    args: ['/d', '/s', '/c', `${command}.cmd`, ...args]
+  };
+}
+
 /** Run a command synchronously, return { ok, stdout, stderr, status }. Never throws. */
 function run(cmd, args, opts = {}) {
   const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
@@ -48,11 +61,32 @@ function runAsync(cmd, args, opts = {}) {
       });
     });
     child.on('error', (err) => {
-      resolve({ ok: false, status: null, stdout, stderr: stderr || err.message });
+      resolve({
+        ok: false,
+        status: null,
+        stdout,
+        stderr: stderr || err.message,
+        errorCode: err.code || ''
+      });
     });
   });
 }
 
+/** Return one actionable line without flooding the installer UI with npm output. */
+function commandFailureReason(result) {
+  const lines = `${result.stderr || ''}\n${result.stdout || ''}`
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return lines.find((line) => (
+    /\bE[A-Z0-9_]{2,}\b/.test(line) || /\bnpm error code\b/i.test(line)
+  ))
+    || lines.find((line) => /^npm error\b/i.test(line))
+    || lines.at(-1)
+    || result.errorCode
+    || `exit ${result.status ?? 'unknown'}`;
+}
+
 /** Is a command available on PATH? */
 function hasCmd(name) {
   const probe = isWindows ? run('where', [name]) : run('which', [name]);
@@ -104,12 +138,12 @@ async function pipInstall(skillsDir, requirementsPath, upgrade = false) {
   return r.ok;
 }
 
-/** `npm install` (fresh) or `npm update` (existing) in a skill scripts dir. Async — keeps spinner alive. */
+/** `npm install` (fresh) or `npm update` (existing) in a skill scripts dir. */
 async function npmInstall(dir, upgrade = false, extraEnv = {}) {
   const args = upgrade ? ['update', '--no-audit', '--no-fund'] : ['install', '--no-audit', '--no-fund'];
   const env = { ...process.env, ...extraEnv };
-  const r = await runAsync('npm', args, { cwd: dir, env });
-  return r.ok;
+  const npm = resolvePackageCommand('npm', args);
+  return runAsync(npm.command, npm.args, { cwd: dir, env });
 }
 
 /**
@@ -130,10 +164,11 @@ async function installChromium(scriptsDir, interactive = false) {
     const r = await runAsync('node', [installMjs], { cwd: scriptsDir });
     return r.ok;
   }
+  const npx = resolvePackageCommand('npx', ['--yes', '@puppeteer/browsers', 'install', 'chrome']);
   if (interactive) {
-    return run('npx', ['--yes', '@puppeteer/browsers', 'install', 'chrome'], { cwd: scriptsDir, stdio: 'inherit' }).ok;
+    return run(npx.command, npx.args, { cwd: scriptsDir, stdio: 'inherit' }).ok;
   }
-  const r = await runAsync('npx', ['--yes', '@puppeteer/browsers', 'install', 'chrome'], { cwd: scriptsDir });
+  const r = await runAsync(npx.command, npx.args, { cwd: scriptsDir });
   return r.ok;
 }
 
@@ -149,7 +184,8 @@ function pkgHasDep(scriptsDir, name) {
 
 /** Download the Playwright Chromium browser (for the pptx html2pptx workflow). Async — keeps spinner alive. */
 async function installPlaywrightBrowser(scriptsDir) {
-  const r = await runAsync('npx', ['--yes', 'playwright', 'install', 'chromium'], { cwd: scriptsDir });
+  const npx = resolvePackageCommand('npx', ['--yes', 'playwright', 'install', 'chromium']);
+  const r = await runAsync(npx.command, npx.args, { cwd: scriptsDir });
   return r.ok;
 }
 
@@ -255,6 +291,8 @@ function systemHint(tool) {
 
 module.exports = {
   isWindows,
+  resolvePackageCommand,
+  commandFailureReason,
   hasCmd,
   findPython,
   venvDir,