@haposoft/cafekit 0.18.1 → 0.18.3

package/bin/install.js

@@ -16,7 +16,8 @@
  */
 
 const { spawnSync } = require('child_process');
-const { buildContext, PLATFORMS, packageJson } = require('./lib/context');
+const fs = require('fs');
+const { buildContext, parseInstallerArgs, PLATFORMS, packageJson } = require('./lib/context');
 const lock = require('./lib/lock');
 const backup = require('./lib/backup');
 const manifestLib = require('./lib/manifest');
@@ -45,6 +46,28 @@ const { runPostInstall } = require('./phases/post-install');
 const { setupSkillDeps } = require('./phases/skills-setup');
 const { printSummary } = require('./phases/summary');
 
+function preflightTrackedRootFiles(ctx) {
+  const files = ['AGENTS.md'];
+  if (ctx.platforms.includes('claude')) files.push('CLAUDE.md');
+  for (const file of files) {
+    try {
+      fs.lstatSync(file);
+      continue;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const result = spawnSync('git', ['ls-files', '-v', '--error-unmatch', '--', file], {
+      cwd: process.cwd(), encoding: 'utf8', timeout: 3000, shell: false,
+    });
+    if (!result.error && result.status === 0) {
+      if (result.stdout[0]?.toUpperCase() === 'S') continue;
+      throw new Error(`${file} is tracked by git but missing from the working tree; restore it with \`git checkout -- ${file}\`, or \`git rm ${file}\` if the deletion is intended, then rerun the installer.`);
+    }
+    if (!result.error && (result.status === 1 || /not a git repository/i.test(result.stderr || ''))) continue;
+    ctx.ui.warn(`Could not confirm git state for ${file}; installing a fresh copy.`);
+  }
+}
+
 /** Install a single platform: payload + runtime + metadata, under one spinner. */
 function installPlatform(ctx, platformKey) {
   const platform = PLATFORMS[platformKey];
@@ -97,6 +120,7 @@ function printHelp() {
   console.log(`CafeKit installer (cafekit) v${packageJson.version}
 
 Usage: npx @haposoft/cafekit [options]
+       npx @haposoft/cafekit@latest migrate [--apply]
 
 Installs CafeKit skills, agents, rules and runtime into the current project
 for Claude Code and/or Codex CLI. Re-runs are selective: managed files are updated,
@@ -116,12 +140,22 @@ Options:
   -h, --help           Show this help
   -v, --version        Print version
 
+Commands:
+  migrate              Preview removing this repository's npx install so the
+                       CafeKit Claude Code and Codex plugins take over; edited
+                       files and runtime.json stay. Writes nothing.
+  migrate --apply      Remove it, with a backup in .cafekit-backup/ that is
+                       restored if anything fails.
+
 Docs: https://github.com/haposoft/cafekit`);
 }
 
 async function main() {
   // Info flags short-circuit before any side effects.
   const argv = process.argv.slice(2);
+  if (argv[0] === 'migrate') {
+    process.exit(await runMigrate(argv.slice(1)));
+  }
   if (argv.includes('--help') || argv.includes('-h')) {
     printHelp();
     process.exit(0);
@@ -131,6 +165,15 @@ async function main() {
     process.exit(0);
   }
 
+  // Reject a mistyped argument before the lock and before anything is written.
+  try {
+    parseInstallerArgs(process.argv);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    console.error('  Run npx @haposoft/cafekit --help for the options.');
+    process.exit(error.exitCode || 1);
+  }
+
   // ── Concurrency guard (before context; plain output) ────
   const got = lock.acquire();
   if (!got.acquired) {
@@ -175,6 +218,8 @@ async function main() {
     await selectDocumentSkills(ctx);
     if (ctx.cancelled) { lock.release(); process.exit(0); }
 
+    preflightTrackedRootFiles(ctx);
+
     // ── Pre-run snapshot for rollback ─────────────────────
     // Capture platform folders AND the root files the pipeline mutates
     // (CLAUDE.md, .gitignore) so a mid-run failure rolls back cleanly.
@@ -226,4 +271,82 @@ async function main() {
   process.exit(exitCode);
 }
 
+function printMigrateHelp(stream = console.log) {
+  stream(`Usage: npx @haposoft/cafekit@latest migrate [--apply]
+
+Removes this repository's CafeKit npx install so the Claude Code and Codex
+plugins take over. Without --apply it only prints the plan.
+
+Removed: installed files that still match their install hash and have a plugin
+equivalent, CafeKit hook entries, and the CafeKit instruction blocks.
+Kept: edited files, runtime.json, files you added, skills no plugin ships yet,
+and every user entry in settings.json, hooks.json, AGENTS.md and CLAUDE.md.
+A repository with an .omp/ install is refused.`);
+}
+
+/** `migrate [--apply]`: returns the exit code (0 done or nothing to do, 1 failed or refused, 2 bad usage). */
+async function runMigrate(args) {
+  let apply = false;
+  for (const arg of args) {
+    if (arg === '--apply') apply = true;
+    else if (arg === '--help' || arg === '-h') {
+      printMigrateHelp();
+      return 0;
+    } else {
+      console.error(`✗ Unknown argument for migrate: ${arg}`);
+      printMigrateHelp(console.error);
+      return 2;
+    }
+  }
+
+  const { planMigration, planSteps, applyMigration } = require('./lib/migrate-apply');
+  const { renderManifestPlan } = require('./lib/migrate-plan');
+  const { renderMergedPlan } = require('./lib/migrate-merged');
+  const root = process.cwd();
+  let plan;
+  try {
+    plan = planMigration(root);
+  } catch (error) {
+    console.error(`✗ migrate could not read this repository: ${error.message}`);
+    return 1;
+  }
+  const steps = planSteps(plan);
+  console.log(`CafeKit migrate — ${apply ? 'apply' : 'dry run (nothing is written)'}\n`);
+  // The merged-file planner may mark hook scripts kept, so the manifest plan renders after it.
+  const manifestText = renderManifestPlan(plan.manifest);
+  if (manifestText) console.log(manifestText);
+  const mergedText = renderMergedPlan(plan.merged);
+  if (mergedText) console.log(`\nMerged files:\n${mergedText}`);
+
+  // An install migrate cannot read (refused) or does not manage (unmanaged) would be left
+  // behind while the rest goes, so nothing is changed until it is fixed.
+  const blocked = Object.values(plan.manifest.platforms).filter((platform) => ['refused', 'unmanaged'].includes(platform.status));
+  if (plan.merged.refused || blocked.length > 0) {
+    if (plan.merged.refused) console.error(`\n✗ Refused: ${plan.merged.refused}`);
+    for (const platform of blocked) console.error(`\n✗ ${platform.name} cannot be migrated: ${platform.reason}`);
+    console.error('  Nothing was changed. Fix or remove that install by hand, then run migrate again.');
+    return 1;
+  }
+  if (steps.length === 0) {
+    console.log('\nNothing to migrate: no CafeKit npx file here is planned for removal.');
+    return 0;
+  }
+  if (!apply) {
+    console.log(`\n${steps.length} changes planned. Folders left empty are removed too.`);
+    console.log('Run `npx @haposoft/cafekit@latest migrate --apply` to apply them, with a backup.');
+    return 0;
+  }
+
+  const result = await applyMigration(root, { plan });
+  if (result.ok) {
+    console.log(`\n✓ Removed ${result.removed} files and rewrote ${result.written}. Backup: ${result.backupDir}`);
+    console.log('  Install the plugins if you have not: see the CafeKit README.');
+    return 0;
+  }
+  console.error(`\n✗ migrate stopped (${result.reason}): ${result.message}`);
+  if (result.backupDir) console.error(`  Backup: ${result.backupDir}`);
+  for (const step of result.manualSteps || []) console.error(`  ${step}`);
+  return 1;
+}
+
 main();

package/bin/lib/backup.js

@@ -47,30 +47,30 @@ function validateRunId(runId) {
  * Recursively copy a directory tree (verbatim, no transforms). Used for
  * snapshot and restore. Skips if the source does not exist.
  */
-function copyTree(src, dest) {
+function copyTree(src, dest, io = fs) {
   let stat;
   try {
-    stat = fs.lstatSync(src);
+    stat = io.lstatSync(src);
   } catch (error) {
     if (error.code === 'ENOENT') return;
     throw error;
   }
   if (stat.isSymbolicLink()) {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.symlinkSync(fs.readlinkSync(src), dest);
+    io.mkdirSync(path.dirname(dest), { recursive: true });
+    io.symlinkSync(io.readlinkSync(src), dest);
     return;
   }
   if (stat.isDirectory()) {
-    fs.mkdirSync(dest, { recursive: true });
-    for (const entry of fs.readdirSync(src)) {
-      copyTree(path.join(src, entry), path.join(dest, entry));
+    io.mkdirSync(dest, { recursive: true });
+    for (const entry of io.readdirSync(src)) {
+      copyTree(path.join(src, entry), path.join(dest, entry), io);
     }
   } else {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.copyFileSync(src, dest);
+    io.mkdirSync(path.dirname(dest), { recursive: true });
+    io.copyFileSync(src, dest);
     // Preserve restrictive perms (e.g. .env at 0o600) on the backup copy.
     try {
-      fs.chmodSync(dest, stat.mode);
+      io.chmodSync(dest, stat.mode);
     } catch {
       /* best-effort: chmod may fail on some filesystems */
     }
@@ -111,35 +111,54 @@ function snapshot(folders, runId) {
  * Restore every explicit target to its pre-run state. Existing targets are
  * replaced from backup; targets absent before the run are removed.
  *
+ * A target that fails does not stop the others: every target is attempted, and
+ * the failures are thrown together at the end as `error.restoreErrors`
+ * ([{ target, message }]) so the caller can name what to put back by hand.
+ *
  * @param {string} backupDir  path returned by snapshot()
+ * @param {{fs?: object}} options  file-system implementation (tests inject failures)
  */
-function restore(backupDir) {
-  if (!backupDir || !fs.existsSync(backupDir)) return;
+function restore(backupDir, options = {}) {
+  const io = options.fs || fs;
+  if (!backupDir || !io.existsSync(backupDir)) return;
 
   const metadataPath = path.join(backupDir, SNAPSHOT_METADATA);
-  const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+  const metadata = JSON.parse(io.readFileSync(metadataPath, 'utf8'));
   if (metadata?.schemaVersion !== 1 || !Array.isArray(metadata.targets)) {
     throw new Error(`Invalid backup metadata: ${metadataPath}`);
   }
-
   for (const record of metadata.targets) {
     if (!record || typeof record.existed !== 'boolean') {
       throw new Error(`Invalid backup target metadata: ${metadataPath}`);
     }
+    validateTarget(record.target);
+  }
+
+  const restoreErrors = [];
+  for (const record of metadata.targets) {
     const target = validateTarget(record.target);
-    const source = path.join(backupDir, SNAPSHOT_DATA, target);
-    let sourceExists = true;
     try {
-      fs.lstatSync(source);
+      const source = path.join(backupDir, SNAPSHOT_DATA, target);
+      let sourceExists = true;
+      try {
+        io.lstatSync(source);
+      } catch (error) {
+        if (error.code === 'ENOENT') sourceExists = false;
+        else throw error;
+      }
+      if (record.existed && !sourceExists) {
+        throw new Error(`Backup data missing for target: ${target}`);
+      }
+      io.rmSync(target, { recursive: true, force: true });
+      if (record.existed) copyTree(source, target, io);
     } catch (error) {
-      if (error.code === 'ENOENT') sourceExists = false;
-      else throw error;
-    }
-    if (record.existed && !sourceExists) {
-      throw new Error(`Backup data missing for target: ${target}`);
+      restoreErrors.push({ target, message: error.message });
     }
-    fs.rmSync(target, { recursive: true, force: true });
-    if (record.existed) copyTree(source, target);
+  }
+  if (restoreErrors.length > 0) {
+    const error = new Error(`Could not restore ${restoreErrors.map((item) => item.target).join(', ')} from ${backupDir}`);
+    error.restoreErrors = restoreErrors;
+    throw error;
   }
 }
 

package/bin/lib/codex-install.js

@@ -8,6 +8,22 @@ const { preserveAddressingSection } = require('./instruction-blocks');
 const CODEX_BLOCK_START = '<!-- CAFEKIT CODEX START -->';
 const CODEX_BLOCK_END = '<!-- CAFEKIT CODEX END -->';
 const INSTRUCTION_EXTENSIONS = new Set(['.md', '.mdx', '.txt']);
+const CODEX_ASK_DESCRIPTION_BOUNDARY = 'A request to fix or change something is still answered without editing any file; point the user to $cf-fix.';
+const CODEX_ASK_NOTE = 'Rule 1 (Codex): never edit, create, or delete files in this skill, '
+  + 'even when the user says fix it or sửa giúp luôn. Do not run commands that write files. '
+  + 'Answer the cause with evidence and tell the user to run $cf-fix.';
+const CODEX_RESEARCH_DEPTH_MARKER = 'Codex research depth: treat a settled repository decision that remains in force as a known option.';
+const CODEX_RESEARCH_DEPTH_NOTE = CODEX_RESEARCH_DEPTH_MARKER
+  + ' Use Quick for that decision. An outdated supporting rationale alone does not raise depth '
+  + 'unless correcting it changes the recommendation. Conflicting evidence that changes the '
+  + 'recommendation still requires escalation under the depth table.';
+const CODEX_SPECS_SCOPE_MARKER = 'Codex scope gate: put the GATE-SCOPE question in the final answer of the turn.';
+const CODEX_SPECS_SCOPE_NOTE = CODEX_SPECS_SCOPE_MARKER
+  + ' Ask it there, not in commentary or through `request_user_input`. Do not send a summary after the question. '
+  + 'For each item needing a decision, use `[NEEDS CLARIFICATION: <question>]`, replacing <question> '
+  + 'with the real question, not a placeholder or a quotation of this note. Offer EXPAND, KEEP, and CUT together. '
+  + 'Preserve the exact words NEEDS CLARIFICATION, EXPAND, KEEP, and CUT; do not translate them. '
+  + 'Wait for the user to decide; do not choose scope or implement code on their behalf.';
 
 const AGENT_NAMES = [
   'brainstormer',
@@ -200,11 +216,15 @@ function normalizeAskUserQuestion(content) {
   const oneSeparator = '(?:[^\\S\\r\\n]+|[^\\S\\r\\n]*\\r?\\n[^\\S\\r\\n]*)';
   const pattern = new RegExp(
     `(?:(\\b(?:${determinerPattern}|[0-9]+)\\b)(${oneSeparator}))?`
-      + `(\\bAskUserQuestion\\b|${masked.askMarkerPattern})`,
+      + `(\\bAskUserQuestion\\b|${masked.askMarkerPattern}|\\bnative(?:\\s+structured user-input|\\s+input)\\s+tool\\b)`,
     'g'
   );
-  const normalized = masked.content.replace(pattern, (match, determiner, spacing, _token, offset, source) => {
-    const literalIndex = match.indexOf('AskUserQuestion');
+  const withoutRuntimePossessive = masked.content.replace(
+    /\bthe runtime['’]s\s+native(?:\s+structured user-input|\s+input)\s+tool\b/g,
+    "a question in the turn's final answer"
+  );
+  const normalized = withoutRuntimePossessive.replace(pattern, (match, determiner, spacing, _token, offset, source) => {
+    const literalIndex = match.search(/AskUserQuestion|\bnative\b/);
     const tokenOffset = offset + (literalIndex >= 0
       ? literalIndex
       : match.indexOf(masked.askMarkerPrefix));
@@ -219,18 +239,33 @@ function normalizeAskUserQuestion(content) {
       const normalizedDeterminer = /^an$/i.test(determiner)
         ? (determiner[0] === 'A' ? 'A' : 'a')
         : determiner;
-      return `${normalizedDeterminer}${spacing}structured user-input request`;
+      return `${normalizedDeterminer}${spacing}question in the turn's final answer`;
     }
 
     const trailing = source.slice(offset + match.length);
     const pluralContext = new RegExp(`^${oneSeparator}(?:calls|batches)\\b`, 'i').test(trailing);
-    return `${pluralContext ? '' : 'a '}structured user-input request`;
+    return `${pluralContext ? '' : 'a '}question in the turn's final answer`;
   });
   return masked.restore(normalized);
 }
 
-function normalizeRuntimePaths(content) {
-  return normalizeSourcePaths(content, {
+function normalizeRuntimePaths(content, sourcePath = '') {
+  const stateRootsPattern = /const RUNTIME_STATE_ROOTS = Object\.freeze\(\[[\s\S]*?\]\);/;
+  const sharedStateRoots = path.basename(sourcePath) === 'provenance.cjs'
+    ? content.match(stateRootsPattern)?.[0] : null;
+  const preservedRoots = [];
+  let markerPrefix = '\uE000CAFEKIT_HOST_';
+  while (content.includes(markerPrefix)) markerPrefix += '_';
+  const rootToken = /(?<![\w/\\])\.claude(?:[/\\])?(?![\w/\\.-])/g;
+  const instruction = isInstructionAsset(sourcePath) ? content.replace(/^.*$/gm, line => {
+    if (!/(?<![\w/\\])\.codex(?:[/\\])?(?![\w/\\.-])/.test(line)) return line;
+    return line.replace(rootToken, original => {
+      const marker = `${markerPrefix}${preservedRoots.length}\uE001`;
+      preservedRoots.push([marker, original]);
+      return marker;
+    });
+  }) : content;
+  let next = normalizeSourcePaths(instruction, {
     runtimeRoot: '.codex',
     skillsRoot: '.agents/skills'
   })
@@ -239,8 +274,21 @@ function normalizeRuntimePaths(content) {
     .replace(/(?<!~\/)\.claude(?=[/\\])/g, '.codex')
     .replace(/(['"])\.claude\1/g, '$1.codex$1')
     .replace(/`\.claude`/g, '`.codex`');
+  // This table describes every runtime's generated state, not the install root.
+  if (sharedStateRoots) next = next.replace(stateRootsPattern, () => sharedStateRoots);
+  if (/\/ai-multimodal\/scripts\/(?:media_optimizer|document_converter)\.py$/.test(sourcePath.replace(/\\/g, '/'))) {
+    // Shared skills live under .agents; native support/config still lives in .codex.
+    next = next.replace(/\bclaude_dir = skills_dir\.parent\b/g,
+      "claude_dir = skills_dir.parent.parent / '.codex'");
+  }
+  for (const [marker, original] of preservedRoots) next = next.split(marker).join(original);
+  return next;
 }
 
+// Matches the vibe invocation list across a hard line wrap.
+const VIBE_INVOCATION_CLAUDE = new RegExp(
+  '\\(`/cf:vibe` from the plugin, `/vibe` from a project install, `\\$cf-vibe` on Codex\\)'.replace(/ /g, '\\s+'), 'g');
+
 function normalizeSkillNames(content) {
   return content
     .replace(/\/cf:([a-z0-9-]+)/gi, (_match, name) => `$cf-${name}`)
@@ -262,6 +310,7 @@ function normalizeAgentNames(content) {
 
 function normalizeAgentInvocations(content) {
   return content
+    .replace(/\bTask\s*\(\s*Explore\s*\)/g, 'spawn_agent(agent_type="explorer", fork_turns="none", task_name="explore", message="Describe the scan")')
     .replace(/\bAgent\s*\(/g, 'spawn_agent(')
     .replace(/\bsubagent_type\s*=\s*"([^"]+)"/g, (_match, name) => (
       `agent_type="${normalizeAgentRole(name)}", fork_turns="none"`
@@ -286,15 +335,63 @@ function isInstructionAsset(sourcePath) {
 }
 
 function normalizeCodexBody(content, sourcePath = '') {
-  let next = normalizeRuntimePaths(String(content));
+  let next = normalizeRuntimePaths(String(content), sourcePath);
   next = next
-    .replace(/\bCLAUDE\.md\b/g, 'AGENTS.md')
+    .replace(/^.*$/gm, line => line.replace(/\bCLAUDE\.md\b/g, (name, offset) => (
+      isInstructionAsset(sourcePath) && /(?<![\w/\\])AGENTS\.md\b/.test(line)
+        && !/[\w/\\]/.test(line[offset - 1] || '') ? name : 'AGENTS.md'
+    )))
     .replace(/\bClaude Code\b/g, 'Codex CLI');
 
   if (!isInstructionAsset(sourcePath)) return next;
 
+  if (/(?:^|\/)rules\/orchestrator\.md$/.test(String(sourcePath).replace(/\\/g, '/'))) {
+    next = next
+      .replace('When the current session or a subagent runs on a model below `fable` (e.g. `opus`, `sonnet`, `haiku`) and hits a hard problem',
+        'When the current session or a subagent hits a hard problem')
+      .replace('It runs autonomously on the strongest available model',
+        'It runs autonomously with high reasoning effort on the session model unless configuration selects another');
+  }
+
+  // The vibe-run exception lists every way to invoke vibe; on Codex only the `$cf-vibe` mention exists, and the
+  // generic rename below would turn the Claude names into the false "`$cf-vibe` from the plugin".
+  next = next.replace(VIBE_INVOCATION_CLAUDE, () => '(`$cf-vibe`)');
   next = normalizeAgentInvocations(normalizeAgentNames(normalizeSkillNames(next)));
-  return applyReplacements(normalizeAskUserQuestion(next), INSTRUCTION_REPLACEMENTS);
+  next = next.replace(/`?CLAUDE_CODE_SUBAGENT_MODEL`?/g,
+    'the configured agent model (`model` in `.codex/agents/<agent>.toml`, or `[agents].default_subagent_model` in native Codex configuration)');
+  next = applyReplacements(normalizeAskUserQuestion(next), INSTRUCTION_REPLACEMENTS);
+  const { frontmatter, body } = splitFrontmatter(next);
+  if (frontmatter.when_to_use && frontmatter.description) {
+    const description = `${frontmatter.description} Use when: ${frontmatter.when_to_use}`;
+    if (description.length <= 1024) {
+      const header = next.slice(0, next.length - body.length)
+        .replace(/^description:[^\r\n]*(?:\r?\n[ \t]+[^\r\n]*)*/m,
+          () => `description: ${JSON.stringify(description)}`);
+      next = header + body;
+    }
+  }
+  // Only the installed ask skill receives this Codex-specific boundary, never eval prompts.
+  if (/(?:^|\/)skills\/ask\/SKILL\.md$/.test(String(sourcePath).replace(/\\/g, '/'))) {
+    const { frontmatter, body } = splitFrontmatter(next);
+    const description = `${frontmatter.description} ${CODEX_ASK_DESCRIPTION_BOUNDARY}`;
+    if (description.length > 1024) throw new Error('Codex ask description exceeds 1024 characters');
+    const header = next.slice(0, next.length - body.length)
+      .replace(/^description:[^\r\n]*$/m, () => `description: ${JSON.stringify(description)}`);
+    next = `${header}\n${CODEX_ASK_NOTE}\n\n${body}`;
+  }
+  // Only the installed research skill receives this note, never prompts or templates.
+  if (/(?:^|\/)skills\/research\/SKILL\.md$/.test(String(sourcePath).replace(/\\/g, '/'))) {
+    const { body } = splitFrontmatter(next);
+    const header = next.slice(0, next.length - body.length);
+    next = `${header}\n${CODEX_RESEARCH_DEPTH_NOTE}\n\n${body}`;
+  }
+  // Only the installed specs skill receives this note, never prompts or templates.
+  if (/(?:^|\/)skills\/specs\/SKILL\.md$/.test(String(sourcePath).replace(/\\/g, '/')) && !next.includes(CODEX_SPECS_SCOPE_NOTE)) {
+    const { body } = splitFrontmatter(next);
+    const header = next.slice(0, next.length - body.length);
+    next = `${header}\n${CODEX_SPECS_SCOPE_NOTE}\n\n${body}`;
+  }
+  return next;
 }
 
 function getCodexCopyOptions(baseOptions = {}) {
@@ -307,14 +404,42 @@ function getCodexCopyOptions(baseOptions = {}) {
 function convertCodexAgentContent(content, fileName = '') {
   const { frontmatter, body } = splitFrontmatter(content);
   const name = codexAgentName(frontmatter.name || fileName);
-  const description = normalizeCodexBody(
+  let description = normalizeCodexBody(
     frontmatter.description || `CafeKit Codex agent: ${name}`
   );
-  const instructions = normalizeCodexBody(body).trim();
+  let agentBody = body;
+  if (['git_ops', 'project_manager'].includes(name)) {
+    let inTeamSection = false;
+    agentBody = body.split('\n').flatMap(line => {
+      if (/^## /.test(line)) {
+        inTeamSection = /^## (?:Team Mode|Collaborative Interlocking \(Swarm Protocol\))\s*$/.test(line);
+      }
+      if (!inTeamSection) return [line];
+      if (/\b(?:TaskList|TaskGet|TaskUpdate|SendMessage|shutdown_request)\b|When instantiated as a team member|When triggered as an active teammate/.test(line)) return [];
+      return [line.replace(/^(\s*)\d+\. /, '$1- ')];
+    }).join('\n');
+  }
+  let instructions = normalizeCodexBody(agentBody).trim();
+  const readOnly = ['brainstormer', 'code_auditor', 'inspector', 'researcher'].includes(name);
+  if (readOnly) {
+    instructions += '\n\n## Read-only role\n\nRead-only role: never create, never edit, and never delete files, and never run commands that write to disk; return findings in your reply.';
+  }
+  const reasoning = [];
+  if (name === 'strategist') {
+    description = 'Autonomous advisory counsel with high reasoning effort; inherits the session model unless native spawn or agent defaults select another. No session model switch or user interview. Mention @strategist or spawn it for hard design, debugging, or trade-off calls. Advisory-only; returns advice, not code.';
+    instructions = instructions
+      .replace('consulted for counsel and running on the strongest available model',
+        'consulted for counsel with high reasoning effort on the configured native model')
+      .replace(/## Runtime note\s+[\s\S]*$/,
+        '## Runtime note\n\nThis agent sets `model_reasoning_effort = "high"` and omits `model`. It inherits the session model unless an explicit native spawn or `[agents].default_subagent_model` selects another. No strongest-model selection is guaranteed. For deployment control, set `model` in `.codex/agents/strategist.toml` or configure native agent defaults in native Codex configuration; choose a model that supports high reasoning effort. Advice remains advisory-only and never counts as execution proof.');
+    reasoning.push('model_reasoning_effort = "high"');
+  }
 
   return [
     `name = ${JSON.stringify(name)}`,
     `description = ${JSON.stringify(description)}`,
+    ...(readOnly ? ['sandbox_mode = "read-only"'] : []),
+    ...reasoning,
     `developer_instructions = ${JSON.stringify(instructions)}`,
     ''
   ].join('\n');
@@ -365,6 +490,10 @@ function transformManagedCodexContent(content, transform) {
 }
 
 module.exports = {
+  CODEX_RESEARCH_DEPTH_MARKER,
+  CODEX_RESEARCH_DEPTH_NOTE,
+  CODEX_SPECS_SCOPE_MARKER,
+  CODEX_SPECS_SCOPE_NOTE,
   normalizeCodexBody,
   getCodexCopyOptions,
   codexAgentName,

package/bin/lib/context.js

@@ -128,7 +128,7 @@ const PLATFORMS = {
     detectFiles: ['.omp'],
     commandsDir: null,
     // omp discovers .claude/skills and .agents/skills itself, so CafeKit copies
-    // no skill payload for it. See specs/omp-runtime-support/plan.md.
+    // no skill payload for it. See specs/archive/omp-runtime-support/plan.md.
     skillsDir: '.agents/skills',
     agentsDir: null,
     skillsRef: '.agents/skills',
@@ -245,6 +245,7 @@ function getCopyOptions(platformKey, baseOptions = {}) {
  *  --upgrade / -u / --force / -f / --force-overwrite → forceOverwrite:true
  *      (overwrite user-modified managed files, backing up the user copy first)
  *  --dry-run                                         → dryRun:true
+ *  an unknown positional argument                    → throws with exitCode 2
  *
  * `upgrade` is kept as an alias of `forceOverwrite` for backward compatibility
  * with existing docs and muscle memory.
@@ -283,6 +284,10 @@ function parseInstallerArgs(argv) {
       args.lang = argv[++i];
     } else if (arg.startsWith('--lang=')) {
       args.lang = arg.slice('--lang='.length);
+    } else if (!arg.startsWith('-')) {
+      // A typo of a subcommand must not run an install.
+      const hint = arg === 'migrate' ? ' (migrate must be the first argument)' : '';
+      throw Object.assign(new Error(`Unknown argument: ${JSON.stringify(arg)}${hint}`), { exitCode: 2 });
     }
   }