@haposoft/cafekit 0.14.1 → 0.15.0

package/bin/lib/version-check.js

@@ -4,7 +4,7 @@
  * Reads each platform's cafekit.json to compare the installed version with the
  * incoming one and decides whether to proceed:
  *
- *   same    → info + exit 0 (unless --force-overwrite)
+ *   same    → selective refresh (or full reset with --force-overwrite)
  *   newer   → normal update
  *   older   → downgrade warning + confirm (interactive) or abort (non-interactive)
  *   missing → fresh install, no check needed
@@ -43,7 +43,7 @@ function getInstalledVersion(platformKey) {
 
 /**
  * Check versions for all selected platforms and decide whether to proceed.
- * Sets ctx.cancelled on same-version (without --force) or unconfirmed downgrade.
+ * Sets ctx.cancelled on a skipped same-version refresh or unconfirmed downgrade.
  * Sets ctx.isUpdate = true when upgrading from an older version.
  * Shows interactive prompt when version differs, asking user what to do.
  */
@@ -65,33 +65,48 @@ async function checkVersions(ctx) {
     ctx.isUpdate = false;
     return ctx;
   }
+  const hasFreshPlatform = platformsWithInstall.length < ctx.platforms.length;
 
   // Get unique versions across all platforms
   const uniqueVersions = [...new Set(platformsWithInstall.map(p => p.installed))];
   const installedVersion = uniqueVersions.length === 1 ? uniqueVersions[0] : `${uniqueVersions.join(', ')}`;
 
-  // Determine overall comparison (assuming same version across platforms)
-  const firstPlatform = platformsWithInstall[0];
-  const cmp = cmpVersion(firstPlatform.installed, incoming);
+  const compared = platformsWithInstall.map((platform) => ({
+    ...platform,
+    cmp: cmpVersion(platform.installed, incoming)
+  }));
+  // Any downgrade risk takes precedence. Otherwise update every stale runtime
+  // even when the first selected runtime already matches the incoming version.
+  const firstPlatform = compared.find((platform) => platform.cmp > 0)
+    || compared.find((platform) => platform.cmp < 0)
+    || compared[0];
+  const cmp = compared.some((platform) => platform.cmp > 0)
+    ? 1
+    : compared.some((platform) => platform.cmp < 0) ? -1 : 0;
 
   // ── Same version ───────────────────────────────────────────────────────────
   if (cmp === 0) {
     ctx.isUpdate = false;
 
+    // A same-version runtime must not prevent adding another selected platform
+    // (for example, adding Codex to an existing Claude-only installation).
+    if (hasFreshPlatform) return ctx;
+
     if (ctx.options.forceOverwrite) {
       ctx.ui.info(ctx.t ? ctx.t('versionForceReinstall', { v: installedVersion }) : `Reinstalling CafeKit ${installedVersion} (--force-overwrite)...`);
       return ctx;
     }
 
     if (!ctx.interactive) {
-      ctx.ui.info(ctx.t ? ctx.t('versionUpToDate', { v: installedVersion }) : `CafeKit ${installedVersion} is already up to date. Use --force-overwrite to reinstall.`);
-      ctx.cancelled = true;
+      ctx.ui.info(ctx.t
+        ? ctx.t('versionRefreshing', { v: installedVersion })
+        : `Refreshing CafeKit ${installedVersion}; user-modified files will be preserved.`);
       return ctx;
     }
 
     // Show current vs new and ask what to do
     const options = [
-      { value: 'reinstall', label: ctx.t ? ctx.t('reinstallOption') : 'Reinstall (overwrite managed files)' },
+      { value: 'refresh', label: ctx.t ? ctx.t('refreshOption') : 'Refresh managed files (preserve your edits)' },
       { value: 'skip', label: ctx.t ? ctx.t('skipOption') : 'Skip (exit)' }
     ];
 
@@ -107,10 +122,6 @@ async function checkVersions(ctx) {
       return ctx;
     }
 
-    if (answer === 'reinstall') {
-      ctx.options.forceOverwrite = true;
-    }
-
     return ctx;
   }
 
@@ -194,6 +205,8 @@ async function checkVersions(ctx) {
       ? ctx.t('versionDowngrade', { from: firstPlatform.installed, to: incoming })
       : `Downgrading ${firstPlatform.installed} → ${incoming}. This may remove features.`;
 
+    if (ctx.options.forceOverwrite) return ctx;
+
     if (!ctx.interactive) {
       ctx.ui.warn ? ctx.ui.warn(msg + ' Downgrade aborted in non-interactive mode. Use --force-overwrite to proceed.') : console.warn(msg);
       ctx.cancelled = true;

package/bin/phases/claude-runtime.js

@@ -11,15 +11,54 @@ const fs = require('fs');
 const path = require('path');
 const {
   PLATFORMS,
-  isClaudeCompatibleRuntime,
+  hasPlatformCapability,
   getRuntimeSupportTargetDir,
   getCopyOptions
 } = require('../lib/context');
+const { sha256 } = require('../lib/manifest');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
 const { normalizeOpenCodeBody } = require('../lib/opencode-install');
 
 const SRC = path.join(__dirname, '../../src');
+const CLAUDE_START = '<!-- CAFEKIT CLAUDE START -->';
+const CLAUDE_END = '<!-- CAFEKIT CLAUDE END -->';
+
+function managedClaudeBlock(template) {
+  return `${CLAUDE_START}\n${template.trimEnd()}\n${CLAUDE_END}`;
+}
+
+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;
+  return { start, end: endStart + CLAUDE_END.length, bodyStart: start + CLAUDE_START.length, bodyEnd: endStart };
+}
+
+/** Transform only the CafeKit-owned body, preserving all surrounding bytes. */
+function transformManagedClaudeContent(content, transform) {
+  const range = managedClaudeRange(content);
+  if (!range) return content;
+  const body = content.slice(range.bodyStart, range.bodyEnd);
+  return `${content.slice(0, range.bodyStart)}${transform(body)}${content.slice(range.bodyEnd)}`;
+}
+
+function upsertManagedClaudeBlock(existing, template, legacyOwned) {
+  const block = managedClaudeBlock(template);
+  const range = managedClaudeRange(existing);
+  if (range) {
+    return `${existing.slice(0, range.start)}${block}${existing.slice(range.end)}`;
+  }
+
+  // Whole-file migration is deliberately limited to exact shipped content or
+  // a file whose bytes still match the legacy ownership manifest.
+  if (existing === template || legacyOwned) return `${block}\n`;
+  if (!existing) return `${block}\n`;
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${separator}${block}\n`;
+}
 
 /** Copy ROUTING.md (SKILLS_DIR substituted; OpenCode body normalized). */
 function copyRoutingFile(ctx, platformKey) {
@@ -105,15 +144,28 @@ function copyClaudeMdFile(ctx, platformKey) {
     return;
   }
 
-  const { action } = writeManagedFile({
-    src, dest, platformFolder: PLATFORMS.claude.folder, ctx, tracker: ctx.trackers.claude
-  });
+  const tracker = ctx.trackers.claude;
+  // Older releases recorded the root file relative to .claude/. Never retain
+  // that whole-file ownership claim, even when this run makes no content change.
+  if (tracker) tracker.prune('../CLAUDE.md');
+
+  const template = fs.readFileSync(src, 'utf8');
+  const exists = fs.existsSync(dest);
+  const existing = exists ? fs.readFileSync(dest, 'utf8') : '';
+  const legacyRecord = ctx.ownership?.[PLATFORMS.claude.folder]?.files?.['../CLAUDE.md'];
+  const legacyOwned = Boolean(legacyRecord && legacyRecord.sha256 === sha256(existing));
+  const next = upsertManagedClaudeBlock(existing, template, legacyOwned);
+  const action = !exists ? 'created' : next === existing ? 'unchanged' : 'updated';
+
+  if (!ctx.dryRun && action !== 'unchanged') {
+    fs.writeFileSync(dest, next, 'utf8');
+  }
   report(ctx, action, 'CLAUDE.md');
 }
 
 /** Copy the rules/ tree (ownership-aware; no longer force-overwrites). */
 function copyRulesDirectory(ctx, platformKey) {
-  if (!isClaudeCompatibleRuntime(platformKey)) return;
+  if (!hasPlatformCapability(platformKey, 'rules')) return;
 
   const src = path.join(SRC, 'claude/rules');
   const dest = getRuntimeSupportTargetDir(platformKey, 'rules');
@@ -123,9 +175,7 @@ function copyRulesDirectory(ctx, platformKey) {
     return;
   }
 
-  const transform = platformKey === 'opencode'
-    ? getCopyOptions('opencode', {}).transform
-    : undefined;
+  const transform = getCopyOptions(platformKey, {}).transform;
   const agg = copyManagedTree({
     src, dest, platformFolder: PLATFORMS[platformKey].folder, ctx, tracker: ctx.trackers[platformKey], transform
   });
@@ -137,5 +187,6 @@ module.exports = {
   copyClaudeRuntimeFiles,
   removeObsoleteClaudeRuntimeFiles,
   copyClaudeMdFile,
-  copyRulesDirectory
+  copyRulesDirectory,
+  transformManagedClaudeContent
 };

package/bin/phases/codex-runtime.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
+const { report, treeAction } = require('./report');
+const { copyRulesDirectory } = require('./claude-runtime');
+const {
+  normalizeCodexBody,
+  upsertManagedCodexBlock
+} = require('../lib/codex-install');
+
+const SRC = path.join(__dirname, '../../src');
+const CODEX_SRC = path.join(SRC, 'codex');
+
+const CODEX_OWN_RUNTIME = [
+  ['gitignore', '.gitignore'],
+  ['runtime.json', 'runtime.json'],
+  ['hooks.json', 'hooks.json']
+];
+
+function writeSourceFile(ctx, platformKey, src, dest, label, transform) {
+  const platform = PLATFORMS[platformKey];
+  const { action } = writeManagedFile({
+    src,
+    dest,
+    platformFolder: platform.folder,
+    ctx,
+    tracker: ctx.trackers[platformKey],
+    transform
+  });
+  report(ctx, action, label);
+}
+
+function installRuntimeFiles(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  for (const [sourceRel, targetRel] of CODEX_OWN_RUNTIME) {
+    writeSourceFile(
+      ctx,
+      platformKey,
+      path.join(CODEX_SRC, sourceRel),
+      path.join(platform.folder, targetRel),
+      `Codex runtime: ${targetRel}`
+    );
+  }
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(CODEX_SRC, 'agents-gitignore'),
+    path.join('.agents', '.gitignore'),
+    'Codex skills: .agents/.gitignore'
+  );
+
+  const agg = copyManagedTree({
+    src: path.join(CODEX_SRC, 'hooks'),
+    dest: path.join(platform.folder, 'hooks'),
+    platformFolder: platform.folder,
+    ctx,
+    tracker: ctx.trackers[platformKey]
+  });
+  report(ctx, treeAction(agg), 'Codex native hooks');
+}
+
+function installNativeRuleOverrides(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const source = path.join(CODEX_SRC, 'rules');
+  if (!fs.existsSync(source)) return;
+  const agg = copyManagedTree({
+    src: source,
+    dest: path.join(platform.folder, 'rules'),
+    platformFolder: platform.folder,
+    ctx,
+    tracker: ctx.trackers[platformKey]
+  });
+  report(ctx, treeAction(agg), 'Codex native rule overrides');
+}
+
+function installManagedAgentsMd(ctx) {
+  const source = path.join(CODEX_SRC, 'AGENTS.md');
+  if (!fs.existsSync(source)) {
+    report(ctx, 'missing', 'Codex AGENTS.md template');
+    return;
+  }
+
+  const destination = 'AGENTS.md';
+  const exists = fs.existsSync(destination);
+  const existing = exists ? fs.readFileSync(destination, 'utf8') : '';
+  const block = normalizeCodexBody(fs.readFileSync(source, 'utf8'))
+    .replace(/^# CLAUDE\.md\s*$/m, '# CafeKit for Codex CLI')
+    .trim();
+  const next = upsertManagedCodexBlock(existing, block);
+  const action = !exists ? 'created' : next === existing ? 'unchanged' : 'updated';
+
+  if (!ctx.dryRun && action !== 'unchanged') {
+    fs.writeFileSync(destination, next, 'utf8');
+  }
+  report(ctx, action, 'AGENTS.md (CafeKit Codex block)');
+}
+
+function installCodexRuntime(ctx, platformKey) {
+  if (platformKey !== 'codex') return ctx;
+  installRuntimeFiles(ctx, platformKey);
+  copyRulesDirectory(ctx, platformKey);
+  installNativeRuleOverrides(ctx, platformKey);
+  installManagedAgentsMd(ctx);
+  return ctx;
+}
+
+module.exports = { installCodexRuntime };

package/bin/phases/copy-payload.js

@@ -11,7 +11,7 @@ const path = require('path');
 const {
   PLATFORMS,
   DEPENDENCY_TEMPLATES,
-  isClaudeCompatibleRuntime,
+  hasPlatformCapability,
   getRuntimeSupportTargetDir,
   getCopyOptions
 } = require('../lib/context');
@@ -21,6 +21,10 @@ const {
   convertOpenCodeAgentContent,
   convertOpenCodeCommandContent
 } = require('../lib/opencode-install');
+const {
+  codexAgentName,
+  convertCodexAgentContent
+} = require('../lib/codex-install');
 
 const SRC = path.join(__dirname, '../../src');
 
@@ -53,6 +57,7 @@ function getPlatformSpecFiles(platformKey, ctx) {
 function ensureWorkflowDependencies(ctx, platformKey) {
   const platform = PLATFORMS[platformKey];
   const tracker = ctx.trackers[platformKey];
+  if (!platform.commandsDir) return;
   const commandTemplates = DEPENDENCY_TEMPLATES.commands[platformKey] || {};
   Object.entries(commandTemplates).forEach(([fileName, content]) => {
     if (!content) return;
@@ -72,20 +77,18 @@ function copyPlatformFiles(ctx, platformKey) {
   const platformFolder = platform.folder;
 
   // For OpenCode, text bodies are path-normalized (.claude → .opencode, etc.).
-  const bodyTransform = platformKey === 'opencode'
-    ? getCopyOptions('opencode', {}).transform
-    : undefined;
+  const bodyTransform = getCopyOptions(platformKey, {}).transform;
 
   const skillsSourceDir = path.join(SRC, 'claude/skills');
   const agentsSourceDir = path.join(SRC, platform.sourceDir, 'agents');
 
   if (!ctx.dryRun) {
-    fs.mkdirSync(platform.skillsDir, { recursive: true });
-    fs.mkdirSync(platform.agentsDir, { recursive: true });
+    if (platform.skillsDir) fs.mkdirSync(platform.skillsDir, { recursive: true });
+    if (platform.agentsDir) fs.mkdirSync(platform.agentsDir, { recursive: true });
   }
 
   // ── Skills ──────────────────────────────────────────────
-  if (fs.existsSync(skillsSourceDir)) {
+  if (hasPlatformCapability(platformKey, 'skills') && fs.existsSync(skillsSourceDir)) {
     const specSkillSource = path.join(skillsSourceDir, 'specs');
     const specSkillDest = path.join(platform.skillsDir, 'specs');
 
@@ -98,9 +101,9 @@ function copyPlatformFiles(ctx, platformKey) {
     }
 
     // Keep spec templates in sync (Claude command runtime reads these).
-    if (platformKey === 'claude') {
+    if (platformKey === 'claude' || platformKey === 'codex') {
       const legacyInitTemplate = path.join(platform.skillsDir, 'specs', 'templates', 'init.json');
-      if (fs.existsSync(legacyInitTemplate)) {
+      if (platformKey === 'claude' && fs.existsSync(legacyInitTemplate)) {
         if (!ctx.dryRun) fs.rmSync(legacyInitTemplate, { force: true });
         ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed legacy template: ${legacyInitTemplate}`);
         ctx.results.updated++;
@@ -118,14 +121,21 @@ function copyPlatformFiles(ctx, platformKey) {
       specTemplates.forEach((fileName) => {
         const src = path.join(specSkillSource, 'templates', fileName);
         const dest = path.join(platform.skillsDir, 'specs', 'templates', fileName);
-        const { action } = writeManagedFile({ src, dest, platformFolder, ctx, tracker });
+        const { action } = writeManagedFile({
+          src,
+          dest,
+          platformFolder,
+          ctx,
+          tracker,
+          transform: bodyTransform
+        });
         report(ctx, action, `template: ${fileName}`);
       });
     }
 
     // Additional required skills.
     let requiredSkills = [];
-    if (isClaudeCompatibleRuntime(platformKey)) {
+    if (hasPlatformCapability(platformKey, 'skills')) {
       requiredSkills = ctx.manifest?.skills?.required || [];
     }
     requiredSkills
@@ -146,18 +156,24 @@ function copyPlatformFiles(ctx, platformKey) {
   }
 
   // ── Agents + references + scripts ───────────────────────
-  if (isClaudeCompatibleRuntime(platformKey)) {
+  if (hasPlatformCapability(platformKey, 'agents')) {
     if (fs.existsSync(agentsSourceDir)) {
       const requiredAgents = ctx.manifest?.agents?.required || [
         'tester.md', 'code-reviewer.md', 'fullstack-developer.md', 'debugger.md'
       ];
-      const agentTransform = platformKey === 'opencode'
-        ? (content, src) => convertOpenCodeAgentContent(content, path.basename(src))
-        : undefined;
+      let agentTransform;
+      if (platformKey === 'opencode') {
+        agentTransform = (content, src) => convertOpenCodeAgentContent(content, path.basename(src));
+      } else if (platformKey === 'codex') {
+        agentTransform = (content, src) => convertCodexAgentContent(content, path.basename(src));
+      }
 
       requiredAgents.forEach((fileName) => {
         const src = path.join(agentsSourceDir, fileName);
-        const dest = path.join(platform.agentsDir, fileName);
+        const destName = platformKey === 'codex'
+          ? `${codexAgentName(fileName)}.toml`
+          : fileName;
+        const dest = path.join(platform.agentsDir, destName);
         const { action } = writeManagedFile({
           src, dest, platformFolder, ctx, tracker, transform: agentTransform
         });
@@ -189,6 +205,10 @@ function copyPlatformFiles(ctx, platformKey) {
   ensureWorkflowDependencies(ctx, platformKey);
 
   // ── Commands ────────────────────────────────────────────
+  if (!hasPlatformCapability(platformKey, 'commands') || !platform.commandsDir) {
+    return ctx;
+  }
+
   const sourceSubdir = platform.sourceSubdir || 'commands';
   const commandsSourceDir = path.join(SRC, platform.sourceDir, sourceSubdir);
   const specFiles = getPlatformSpecFiles(platformKey, ctx);

package/bin/phases/post-install.js

@@ -16,6 +16,59 @@ const path = require('path');
 const { PLATFORMS } = require('../lib/context');
 const { LANGUAGE_LABELS } = require('../lib/i18n');
 const { setupOpenCodeModel } = require('../lib/opencode-install');
+const { transformManagedCodexContent } = require('../lib/codex-install');
+const { transformManagedClaudeContent } = require('./claude-runtime');
+const ASSISTANT_NAMES = {
+  claude: 'Claude Code',
+  codex: 'Codex CLI',
+  opencode: 'OpenCode'
+};
+const LANGUAGE_LABEL_BY_CODE = {
+  vi: 'Vietnamese',
+  ja: 'Japanese',
+  en: 'English'
+};
+
+function readManagedBody(filePath, transformManagedContent) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  let body = '';
+  transformManagedContent(content, (managed) => {
+    body = managed;
+    return managed;
+  });
+  return body;
+}
+
+function instructionTargets(ctx) {
+  const targets = {
+    claude: {
+      file: path.join(process.cwd(), 'CLAUDE.md'),
+      transform: transformManagedClaudeContent
+    },
+    codex: {
+      file: path.join(process.cwd(), 'AGENTS.md'),
+      transform: transformManagedCodexContent
+    }
+  };
+  return Object.keys(targets)
+    .filter((key) => ctx.platforms.includes(key))
+    .map((key) => ({ key, ...targets[key] }));
+}
+
+function updateInstructionTarget(target, updateManaged) {
+  if (!fs.existsSync(target.file)) return false;
+  const content = fs.readFileSync(target.file, 'utf8');
+  const next = target.transform(content, updateManaged);
+  if (next === content) return false;
+  fs.writeFileSync(target.file, next, 'utf8');
+  return true;
+}
+
+function trackerOwnsPath(tracker, filePath) {
+  if (!tracker?.keyFor) return false;
+  const trackedKey = tracker.keyFor(filePath);
+  return tracker.recorded(trackedKey) !== null;
+}
 
 /** Write `"language"` field into .claude/settings.json so it's visible at a glance. */
 function patchSettingsLanguage(ctx) {
@@ -46,17 +99,12 @@ function patchSettingsLanguage(ctx) {
  * can update it idempotently.
  */
 function patchLanguageSection(ctx) {
-  if (!ctx.platforms.includes('claude')) return;
   // Skip when locale is English (default — no override needed in CLAUDE.md).
   const locale = ctx.locale || ctx.lang;
   if (!locale || locale === 'en' || locale === 'English') return;
 
-  const claudeMdFile = path.join(process.cwd(), 'CLAUDE.md');
-  if (!fs.existsSync(claudeMdFile)) return;
-
-  const LANG_LABEL = { vi: 'Vietnamese', ja: 'Japanese', en: 'English' };
   // Use locale directly when set (e.g. "Korean"), or map from lang code.
-  const label = locale in LANG_LABEL ? LANG_LABEL[locale] : locale;
+  const label = locale in LANGUAGE_LABEL_BY_CODE ? LANGUAGE_LABEL_BY_CODE[locale] : locale;
 
   const newSection = `## Language Consistency <!-- cafekit:lang -->
 
@@ -64,21 +112,18 @@ Always respond in **${label}**. Technical terms, code identifiers, and file path
 
 `;
 
-  let content = fs.readFileSync(claudeMdFile, 'utf8');
-  // Replace if marker present, else replace the generic section.
+  // Replace only inside the installer-owned block.
   const markerRe = /## Language Consistency <!-- cafekit:lang -->[\s\S]*?(?=\n##|\n*$)/;
   const genericRe = /## Language Consistency\n[\s\S]*?(?=\n##|\n*$)/;
-
-  if (markerRe.test(content)) {
-    content = content.replace(markerRe, newSection);
-  } else if (genericRe.test(content)) {
-    content = content.replace(genericRe, newSection);
-  } else {
-    content += `\n${newSection}\n`;
+  for (const target of instructionTargets(ctx)) {
+    updateInstructionTarget(target, (managed) => {
+      if (markerRe.test(managed)) return managed.replace(markerRe, newSection);
+      if (genericRe.test(managed)) return managed.replace(genericRe, newSection);
+      return `${managed.trimEnd()}\n\n${newSection}\n`;
+    });
   }
-
-  fs.writeFileSync(claudeMdFile, content, 'utf8');
 }
+
 function patchRuntimeLocale(ctx) {
   for (const key of ctx.platforms) {
     const rtPath = path.join(PLATFORMS[key].folder, 'runtime.json');
@@ -93,51 +138,59 @@ function patchRuntimeLocale(ctx) {
     // Use locale (freeform label) so custom languages propagate to the AI hook.
     const locale = ctx.locale || ctx.lang;
     if (data.locale.responseLanguage === locale) continue;
+    // Hardening: never downgrade an existing configured label to a bare default
+    // code when this run never made an explicit language choice (ctx.locale
+    // empty). Protects user config on any code path that skips selectLanguage.
+    if (!ctx.locale && data.locale.responseLanguage) continue;
     data.locale.responseLanguage = locale;
     fs.writeFileSync(rtPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
-    if (ctx.trackers[key]) ctx.trackers[key].record(rtPath);
+    // A preserved user-created/user-modified runtime was deliberately not
+    // recorded by managed-writer. Updating its explicit locale must not turn
+    // the whole user file into a pristine CafeKit ownership baseline.
+    const tracker = ctx.trackers[key];
+    if (trackerOwnsPath(tracker, rtPath)) tracker.record(rtPath);
   }
 }
 
 /** Human assistant name for the active platform(s). */
-function assistantName(ctx) {
-  return ctx.platforms.includes('claude') ? 'Claude Code' : 'OpenCode';
+function assistantName(platformKey) {
+  return ASSISTANT_NAMES[platformKey] || ASSISTANT_NAMES.opencode;
 }
 
 function configureAddressing(ctx, userAddress) {
-  const claudeMdFile = path.join(process.cwd(), 'CLAUDE.md');
-  if (!fs.existsSync(claudeMdFile)) {
-    ctx.ui.warn('CLAUDE.md not found at project root; skipped addressing');
-    return;
-  }
-
-  const name = assistantName(ctx);
-  let content = fs.readFileSync(claudeMdFile, 'utf8');
-  const addressingSection = `## Addressing (Context Overflow Indicator)
+  let found = false;
+  for (const target of instructionTargets(ctx)) {
+    if (!fs.existsSync(target.file)) continue;
+    found = true;
+    const name = assistantName(target.key);
+    const addressingSection = `## Addressing (Context Overflow Indicator)
 
 ${name} always addresses the user as "${userAddress}" throughout the conversation. If it stops doing so, it is a sign the context has been compacted/truncated — tell the user to consider \`/clear\`.`;
 
-  // Idempotent: replace existing section (shared marker) or append.
-  const regex = /##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?(?=\n##|\n*$)/;
-  content = regex.test(content)
-    ? content.replace(regex, addressingSection)
-    : `${content.endsWith('\n') ? content : `${content}\n`}\n${addressingSection}\n`;
-
-  fs.writeFileSync(claudeMdFile, content, 'utf8');
-  ctx.ui.success(ctx.t('addressingSet', { name, addr: userAddress }));
+    const regex = /##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?(?=\n##|\n*$)/;
+    const changed = updateInstructionTarget(target, (managed) => (
+      regex.test(managed)
+        ? managed.replace(regex, addressingSection)
+        : `${managed.endsWith('\n') ? managed : `${managed}\n`}\n${addressingSection}\n`
+    ));
+    if (changed) {
+      ctx.ui.success(ctx.t('addressingSet', { name, addr: userAddress }));
+    }
+  }
+  if (!found) ctx.ui.warn('Project instruction file not found; skipped addressing');
 }
 
 async function setupAddressing(ctx) {
-  if (!ctx.platforms.includes('claude')) return;
+  if (!ctx.platforms.some((key) => key === 'claude' || key === 'codex')) return;
 
-  // Check if there's already an addressing section in CLAUDE.md
-  const claudeMdFile = path.join(process.cwd(), 'CLAUDE.md');
   let existingName = null;
-  if (fs.existsSync(claudeMdFile)) {
-    const content = fs.readFileSync(claudeMdFile, 'utf8');
+  for (const target of instructionTargets(ctx)) {
+    if (!fs.existsSync(target.file)) continue;
+    const content = readManagedBody(target.file, target.transform);
     const match = content.match(/##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?always addresses the user as "([^"]+)"/);
     if (match) {
       existingName = match[1];
+      break;
     }
   }
 
@@ -199,15 +252,12 @@ async function runPostInstall(ctx) {
   // Write "language" field into .claude/settings.json for visibility.
   patchSettingsLanguage(ctx);
 
-  // Re-record post-write baselines so installer-managed files stay "pristine",
-  // then flush each touched platform tracker.
-  if (ctx.platforms.includes('claude') && ctx.trackers.claude && fs.existsSync('CLAUDE.md')) {
-    ctx.trackers.claude.record('CLAUDE.md');
-  }
+  // Flush touched platform trackers. Root CLAUDE.md is block-managed and must
+  // never regain a whole-file ownership record.
   for (const key of ctx.platforms) {
     if (ctx.trackers[key]) ctx.trackers[key].write();
   }
   return ctx;
 }
 
-module.exports = { configureAddressing, runPostInstall };
+module.exports = { configureAddressing, patchRuntimeLocale, runPostInstall };

package/bin/phases/root-config.js

@@ -4,7 +4,7 @@
  * Ensures the root .gitignore carries CafeKit-managed patterns:
  *  - workflow dirs (plans, shared research)
  *  - install safety artifacts (backup, lock)
- *  - runtime folders (.claude/, .opencode/) — reinstall via
+ *  - runtime folders (.claude/, .opencode/, .codex/, .agents/) — reinstall via
  *    `npx @haposoft/cafekit`; do not commit the local payload
  *
  * Layered with the in-folder `.claude/.gitignore` /
@@ -35,7 +35,9 @@ function ensureGitignore(ctx) {
     '.cafekit.lock',
     // Local runtime payload — reinstall with npx; keep out of git
     '.claude/',
-    '.opencode/'
+    '.opencode/',
+    '.codex/',
+    '.agents/'
   ];
   const prefix = ctx.dryRun ? '[dry-run] ' : '';