@haposoft/cafekit 0.14.2 → 0.15.0

package/bin/lib/opencode-install.js

@@ -419,6 +419,20 @@ function upsertCafeKitAgentsBlock(existingContent, blockContent) {
     return existingContent.replace(blockPattern, managedBlock);
   }
 
+  // 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)) {
+    return `${managedBlock}${existingContent.slice(blockContent.length)}`;
+  }
+  const trimmedLegacy = blockContent.trimEnd();
+  if (
+    existingContent.startsWith(trimmedLegacy)
+    && ['', '\n', '\r'].includes(existingContent.charAt(trimmedLegacy.length))
+  ) {
+    return `${managedBlock}${existingContent.slice(trimmedLegacy.length)}`;
+  }
+  if (!existingContent) return `${managedBlock}\n`;
+
   const separator = existingContent.endsWith('\n') ? '\n' : '\n\n';
   return `${existingContent}${separator}${managedBlock}\n`;
 }
@@ -442,35 +456,23 @@ function getOpenCodeAgentsTemplateContent() {
 function copyOpenCodeAgentsMdFile(platformKey, results, options = {}) {
   if (platformKey !== 'opencode') return;
 
-  const shouldOverwriteManagedFiles = Boolean(options.upgrade);
   const dest = 'AGENTS.md';
   const content = getOpenCodeAgentsTemplateContent();
 
   if (content) {
     const destinationExists = fs.existsSync(dest);
+    const existingContent = destinationExists ? fs.readFileSync(dest, 'utf8') : '';
+    const nextContent = upsertCafeKitAgentsBlock(existingContent, content);
 
-    if (destinationExists && !shouldOverwriteManagedFiles) {
-      const existingContent = fs.readFileSync(dest, 'utf8');
-      const nextContent = upsertCafeKitAgentsBlock(existingContent, content);
-
-      if (nextContent === existingContent) {
-        console.log(`  → Skipped: AGENTS.md (already up to date)`);
-        results.skipped++;
-        return;
-      }
-
+    if (nextContent === existingContent) {
+      console.log(`  → Skipped: AGENTS.md (already up to date)`);
+      results.skipped++;
+    } else if (destinationExists) {
       fs.writeFileSync(dest, nextContent, 'utf8');
       console.log(`  ↻ AGENTS.md merged`);
       results.updated++;
-      return;
-    }
-
-    fs.writeFileSync(dest, content, 'utf8');
-
-    if (destinationExists && shouldOverwriteManagedFiles) {
-      console.log(`  ↻ AGENTS.md overwritten`);
-      results.updated++;
     } else {
+      fs.writeFileSync(dest, nextContent, 'utf8');
       console.log(`  ✓ AGENTS.md installed`);
       results.copied++;
     }

package/bin/lib/path-safety.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function isInside(base, target) {
+  const relative = path.relative(base, target);
+  return relative === ''
+    || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+/**
+ * Reject installer targets that traverse symlinks below the project root.
+ * Managed payloads and rollback snapshots must never follow a project-owned
+ * link into another directory.
+ */
+function assertNoSymlinkPath(filePath, basePath = process.cwd()) {
+  const base = path.resolve(basePath);
+  const target = path.resolve(filePath);
+  if (!isInside(base, target)) {
+    throw new Error(`Managed path is outside the project root: ${filePath}`);
+  }
+
+  const relative = path.relative(base, target);
+  let cursor = base;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    cursor = path.join(cursor, segment);
+    try {
+      if (fs.lstatSync(cursor).isSymbolicLink()) {
+        throw new Error(`Refusing to follow symlinked managed path: ${filePath}`);
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+  return target;
+}
+
+module.exports = { assertNoSymlinkPath, isInside };

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,7 +11,7 @@ const fs = require('fs');
 const path = require('path');
 const {
   PLATFORMS,
-  isClaudeCompatibleRuntime,
+  hasPlatformCapability,
   getRuntimeSupportTargetDir,
   getCopyOptions
 } = require('../lib/context');
@@ -165,7 +165,7 @@ function copyClaudeMdFile(ctx, platformKey) {
 
 /** 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');
@@ -175,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
   });

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,26 +16,60 @@ 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');
-
-function updateManagedClaudeFile(filePath, transform) {
-  const content = fs.readFileSync(filePath, 'utf8');
-  const next = transformManagedClaudeContent(content, transform);
-  if (next === content) return false;
-  fs.writeFileSync(filePath, next, 'utf8');
-  return true;
-}
-
-function readManagedClaudeBody(filePath) {
+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 = '';
-  transformManagedClaudeContent(content, (managed) => {
+  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) {
   if (!ctx.platforms.includes('claude')) return;
@@ -65,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 -->
 
@@ -86,12 +115,15 @@ Always respond in **${label}**. Technical terms, code identifiers, and file path
   // 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*$)/;
-  updateManagedClaudeFile(claudeMdFile, (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`;
-  });
+  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`;
+    });
+  }
 }
+
 function patchRuntimeLocale(ctx) {
   for (const key of ctx.platforms) {
     const rtPath = path.join(PLATFORMS[key].folder, 'runtime.json');
@@ -112,48 +144,53 @@ function patchRuntimeLocale(ctx) {
     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);
-  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 and scoped to the installer-owned block.
-  const regex = /##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?(?=\n##|\n*$)/;
-  const changed = updateManagedClaudeFile(claudeMdFile, (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 }));
+    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 = readManagedClaudeBody(claudeMdFile);
+  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;
     }
   }
 
@@ -223,4 +260,4 @@ async function runPostInstall(ctx) {
   return ctx;
 }
 
-module.exports = { configureAddressing, runPostInstall };
+module.exports = { configureAddressing, patchRuntimeLocale, runPostInstall };