oh-my-codex 0.8.2 → 0.8.4

package/dist/cli/setup.js

@@ -2,55 +2,120 @@
  * omx setup - Automated installation of oh-my-codex
  * Installs skills, prompts, MCP servers config, and AGENTS.md
  */
-import { mkdir, copyFile, readdir, readFile, writeFile, stat, rm } from 'fs/promises';
-import { join, dirname } from 'path';
-import { existsSync } from 'fs';
-import { spawnSync } from 'child_process';
-import { createInterface } from 'readline/promises';
-import { codexHome, codexConfigPath, codexPromptsDir, userSkillsDir, omxStateDir, omxPlansDir, omxLogsDir, omxAgentsConfigDir, } from '../utils/paths.js';
-import { mergeConfig } from '../config/generator.js';
-import { installNativeAgentConfigs } from '../agents/native-config.js';
-import { getPackageRoot } from '../utils/package.js';
-import { readSessionState, isSessionStale } from '../hooks/session.js';
-import { getCatalogHeadlineCounts } from './catalog-contract.js';
-import { tryReadCatalogManifest } from '../catalog/reader.js';
+import { mkdir, copyFile, readdir, readFile, writeFile, stat, rm, } from "fs/promises";
+import { join, dirname, relative } from "path";
+import { existsSync } from "fs";
+import { spawnSync } from "child_process";
+import { createInterface } from "readline/promises";
+import { homedir } from "os";
+import { codexHome, codexConfigPath, codexPromptsDir, userSkillsDir, omxStateDir, omxPlansDir, omxLogsDir, omxAgentsConfigDir, } from "../utils/paths.js";
+import { buildMergedConfig, getRootModelName } from "../config/generator.js";
+import { generateAgentToml } from "../agents/native-config.js";
+import { AGENT_DEFINITIONS } from "../agents/definitions.js";
+import { getPackageRoot } from "../utils/package.js";
+import { readSessionState, isSessionStale } from "../hooks/session.js";
+import { getCatalogHeadlineCounts } from "./catalog-contract.js";
+import { tryReadCatalogManifest } from "../catalog/reader.js";
 /**
  * Legacy scope values that may appear in persisted setup-scope.json files.
  * Both 'project-local' (renamed) and old 'project' (minimal, removed) are
  * migrated to the current 'project' scope on read.
  */
 const LEGACY_SCOPE_MIGRATION = {
-    'project-local': 'project',
+    "project-local": "project",
 };
-export const SETUP_SCOPES = ['user', 'project'];
+export const SETUP_SCOPES = ["user", "project"];
 function applyScopePathRewritesToAgentsTemplate(content, scope) {
-    if (scope !== 'project')
+    if (scope !== "project")
         return content;
     return content
-        .replaceAll('~/.codex', './.codex')
-        .replaceAll('~/.agents', './.agents');
+        .replaceAll("~/.codex", "./.codex")
+        .replaceAll("~/.agents", "./.agents");
 }
 const REQUIRED_TEAM_CLI_API_MARKERS = [
-    'if (subcommand === \'api\')',
-    'executeTeamApiOperation',
-    'TEAM_API_OPERATIONS',
+    "if (subcommand === 'api')",
+    "executeTeamApiOperation",
+    "TEAM_API_OPERATIONS",
 ];
-const DEFAULT_SETUP_SCOPE = 'user';
+const DEFAULT_SETUP_SCOPE = "user";
+const LEGACY_SETUP_MODEL = "gpt-5.3-codex";
+const DEFAULT_SETUP_MODEL = "gpt-5.4";
+function createEmptyCategorySummary() {
+    return {
+        updated: 0,
+        unchanged: 0,
+        backedUp: 0,
+        skipped: 0,
+        removed: 0,
+    };
+}
+function createEmptyRunSummary() {
+    return {
+        prompts: createEmptyCategorySummary(),
+        skills: createEmptyCategorySummary(),
+        nativeAgents: createEmptyCategorySummary(),
+        agentsMd: createEmptyCategorySummary(),
+        config: createEmptyCategorySummary(),
+    };
+}
+function getBackupContext(scope, projectRoot) {
+    const timestamp = new Date().toISOString().replace(/[:]/g, "-");
+    if (scope === "project") {
+        return {
+            backupRoot: join(projectRoot, ".omx", "backups", "setup", timestamp),
+            baseRoot: projectRoot,
+        };
+    }
+    return {
+        backupRoot: join(homedir(), ".omx", "backups", "setup", timestamp),
+        baseRoot: homedir(),
+    };
+}
+async function ensureBackup(destinationPath, contentChanged, backupContext, options) {
+    if (!contentChanged || !existsSync(destinationPath))
+        return false;
+    const relativePath = relative(backupContext.baseRoot, destinationPath);
+    const safeRelativePath = relativePath.startsWith("..") || relativePath === ""
+        ? destinationPath.replace(/^[/]+/, "")
+        : relativePath;
+    const backupPath = join(backupContext.backupRoot, safeRelativePath);
+    if (!options.dryRun) {
+        await mkdir(dirname(backupPath), { recursive: true });
+        await copyFile(destinationPath, backupPath);
+    }
+    if (options.verbose) {
+        console.log(`  backup ${destinationPath} -> ${backupPath}`);
+    }
+    return true;
+}
+async function filesDiffer(src, dst) {
+    if (!existsSync(dst))
+        return true;
+    const [srcContent, dstContent] = await Promise.all([
+        readFile(src, "utf-8"),
+        readFile(dst, "utf-8"),
+    ]);
+    return srcContent !== dstContent;
+}
+function logCategorySummary(name, summary) {
+    console.log(`  ${name}: updated=${summary.updated}, unchanged=${summary.unchanged}, ` +
+        `backed_up=${summary.backedUp}, skipped=${summary.skipped}, removed=${summary.removed}`);
+}
 function isSetupScope(value) {
     return SETUP_SCOPES.includes(value);
 }
 function getScopeFilePath(projectRoot) {
-    return join(projectRoot, '.omx', 'setup-scope.json');
+    return join(projectRoot, ".omx", "setup-scope.json");
 }
 export function resolveScopeDirectories(scope, projectRoot) {
-    if (scope === 'project') {
-        const codexHomeDir = join(projectRoot, '.codex');
+    if (scope === "project") {
+        const codexHomeDir = join(projectRoot, ".codex");
         return {
-            codexConfigFile: join(codexHomeDir, 'config.toml'),
+            codexConfigFile: join(codexHomeDir, "config.toml"),
             codexHomeDir,
-            nativeAgentsDir: join(projectRoot, '.omx', 'agents'),
-            promptsDir: join(codexHomeDir, 'prompts'),
-            skillsDir: join(projectRoot, '.agents', 'skills'),
+            nativeAgentsDir: join(projectRoot, ".omx", "agents"),
+            promptsDir: join(codexHomeDir, "prompts"),
+            skillsDir: join(projectRoot, ".agents", "skills"),
         };
     }
     return {
@@ -66,9 +131,9 @@ async function readPersistedSetupScope(projectRoot) {
     if (!existsSync(scopePath))
         return undefined;
     try {
-        const raw = await readFile(scopePath, 'utf-8');
+        const raw = await readFile(scopePath, "utf-8");
         const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed.scope === 'string') {
+        if (parsed && typeof parsed.scope === "string") {
             // Direct match to current scopes
             if (isSetupScope(parsed.scope))
                 return parsed.scope;
@@ -95,19 +160,21 @@ async function promptForSetupScope(defaultScope) {
         output: process.stdout,
     });
     try {
-        console.log('Select setup scope:');
+        console.log("Select setup scope:");
         console.log(`  1) user (default) — installs to ~/.codex, ~/.agents`);
-        console.log('  2) project — installs to ./.codex, ./.agents (local to project)');
-        const answer = (await rl.question('Scope [1-2] (default: 1): ')).trim().toLowerCase();
-        if (answer === '2' || answer === 'project')
-            return 'project';
+        console.log("  2) project — installs to ./.codex, ./.agents (local to project)");
+        const answer = (await rl.question("Scope [1-2] (default: 1): "))
+            .trim()
+            .toLowerCase();
+        if (answer === "2" || answer === "project")
+            return "project";
         return defaultScope;
     }
     finally {
         rl.close();
     }
 }
-async function promptForAgentsOverwrite() {
+async function promptForModelUpgrade(currentModel, targetModel) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         return false;
     }
@@ -116,10 +183,10 @@ async function promptForAgentsOverwrite() {
         output: process.stdout,
     });
     try {
-        const answer = (await rl.question('AGENTS.md already exists. Overwrite with template? [y/N]: '))
+        const answer = (await rl.question(`Detected model "${currentModel}". Update to "${targetModel}"? [Y/n]: `))
             .trim()
             .toLowerCase();
-        return answer === 'y' || answer === 'yes';
+        return answer === "" || answer === "y" || answer === "yes";
     }
     finally {
         rl.close();
@@ -127,17 +194,17 @@ async function promptForAgentsOverwrite() {
 }
 async function resolveSetupScope(projectRoot, requestedScope) {
     if (requestedScope) {
-        return { scope: requestedScope, source: 'cli' };
+        return { scope: requestedScope, source: "cli" };
     }
     const persisted = await readPersistedSetupScope(projectRoot);
     if (persisted) {
-        return { scope: persisted, source: 'persisted' };
+        return { scope: persisted, source: "persisted" };
     }
     if (process.stdin.isTTY && process.stdout.isTTY) {
         const scope = await promptForSetupScope(DEFAULT_SETUP_SCOPE);
-        return { scope, source: 'prompt' };
+        return { scope, source: "prompt" };
     }
-    return { scope: DEFAULT_SETUP_SCOPE, source: 'default' };
+    return { scope: DEFAULT_SETUP_SCOPE, source: "default" };
 }
 async function persistSetupScope(projectRoot, scope, options) {
     const scopePath = getScopeFilePath(projectRoot);
@@ -148,22 +215,22 @@ async function persistSetupScope(projectRoot, scope, options) {
     }
     await mkdir(dirname(scopePath), { recursive: true });
     const payload = { scope };
-    await writeFile(scopePath, JSON.stringify(payload, null, 2) + '\n');
+    await writeFile(scopePath, JSON.stringify(payload, null, 2) + "\n");
     if (options.verbose)
         console.log(`  Wrote ${scopePath}`);
 }
 export async function setup(options = {}) {
-    const { force = false, dryRun = false, scope: requestedScope, verbose = false, agentsOverwritePrompt, } = options;
+    const { force = false, dryRun = false, scope: requestedScope, verbose = false, modelUpgradePrompt, } = options;
     const pkgRoot = getPackageRoot();
     const projectRoot = process.cwd();
     const resolvedScope = await resolveSetupScope(projectRoot, requestedScope);
     const scopeDirs = resolveScopeDirectories(resolvedScope.scope, projectRoot);
-    const scopeSourceMessage = resolvedScope.source === 'persisted' ? ' (from .omx/setup-scope.json)' : '';
-    console.log('oh-my-codex setup');
-    console.log('=================\n');
+    const scopeSourceMessage = resolvedScope.source === "persisted" ? " (from .omx/setup-scope.json)" : "";
+    console.log("oh-my-codex setup");
+    console.log("=================\n");
     console.log(`Using setup scope: ${resolvedScope.scope}${scopeSourceMessage}\n`);
     // Step 1: Ensure directories exist
-    console.log('[1/8] Creating directories...');
+    console.log("[1/8] Creating directories...");
     const dirs = [
         scopeDirs.codexHomeDir,
         scopeDirs.promptsDir,
@@ -180,19 +247,25 @@ export async function setup(options = {}) {
         if (verbose)
             console.log(`  mkdir ${dir}`);
     }
-    await persistSetupScope(projectRoot, resolvedScope.scope, { dryRun, verbose });
-    console.log('  Done.\n');
-    // Step 2: Install agent prompts
-    console.log('[2/8] Installing agent prompts...');
+    await persistSetupScope(projectRoot, resolvedScope.scope, {
+        dryRun,
+        verbose,
+    });
+    console.log("  Done.\n");
     const catalogCounts = getCatalogHeadlineCounts();
+    const summary = createEmptyRunSummary();
+    const backupContext = getBackupContext(resolvedScope.scope, projectRoot);
+    // Step 2: Install agent prompts
+    console.log("[2/8] Installing agent prompts...");
     {
-        const promptsSrc = join(pkgRoot, 'prompts');
+        const promptsSrc = join(pkgRoot, "prompts");
         const promptsDst = scopeDirs.promptsDir;
-        const promptCount = await installDirectory(promptsSrc, promptsDst, '.md', { force, dryRun, verbose });
+        summary.prompts = await installDirectory(promptsSrc, promptsDst, ".md", backupContext, { force, dryRun, verbose }, "prompt");
         const cleanedLegacyPromptShims = await cleanupLegacySkillPromptShims(promptsSrc, promptsDst, {
             dryRun,
             verbose,
         });
+        summary.prompts.removed += cleanedLegacyPromptShims;
         if (cleanedLegacyPromptShims > 0) {
             if (dryRun) {
                 console.log(`  Would remove ${cleanedLegacyPromptShims} legacy skill prompt shim file(s).`);
@@ -202,127 +275,133 @@ export async function setup(options = {}) {
             }
         }
         if (catalogCounts) {
-            console.log(`  Installed ${promptCount} agent prompts (catalog baseline: ${catalogCounts.prompts}).\n`);
+            console.log(`  Prompt refresh complete (catalog baseline: ${catalogCounts.prompts}).\n`);
         }
         else {
-            console.log(`  Installed ${promptCount} agent prompts.\n`);
+            console.log("  Prompt refresh complete.\n");
         }
     }
     // Step 3: Install native agent configs
-    console.log('[3/8] Installing native agent configs...');
+    console.log("[3/8] Installing native agent configs...");
     {
-        const agentConfigCount = await installNativeAgentConfigs(pkgRoot, {
-            force,
+        summary.nativeAgents = await refreshNativeAgentConfigs(pkgRoot, scopeDirs.nativeAgentsDir, backupContext, {
             dryRun,
             verbose,
-            agentsDir: scopeDirs.nativeAgentsDir,
         });
-        console.log(`  Installed ${agentConfigCount} native agent configs to ${scopeDirs.nativeAgentsDir}.\n`);
+        console.log(`  Native agent refresh complete (${scopeDirs.nativeAgentsDir}).\n`);
     }
     // Step 4: Install skills
-    console.log('[4/8] Installing skills...');
+    console.log("[4/8] Installing skills...");
     {
-        const skillsSrc = join(pkgRoot, 'skills');
+        const skillsSrc = join(pkgRoot, "skills");
         const skillsDst = scopeDirs.skillsDir;
-        const skillCount = await installSkills(skillsSrc, skillsDst, { force, dryRun, verbose });
+        summary.skills = await installSkills(skillsSrc, skillsDst, backupContext, {
+            force,
+            dryRun,
+            verbose,
+        });
         if (catalogCounts) {
-            console.log(`  Installed ${skillCount} skills (catalog baseline: ${catalogCounts.skills}).\n`);
+            console.log(`  Skill refresh complete (catalog baseline: ${catalogCounts.skills}).\n`);
         }
         else {
-            console.log(`  Installed ${skillCount} skills.\n`);
+            console.log("  Skill refresh complete.\n");
         }
     }
     // Step 5: Update config.toml
-    console.log('[5/8] Updating config.toml...');
-    if (!dryRun) {
-        await mergeConfig(scopeDirs.codexConfigFile, pkgRoot, {
-            verbose,
-            agentsConfigDir: scopeDirs.nativeAgentsDir,
-        });
-    }
-    console.log(`  Done (${scopeDirs.codexConfigFile}).\n`);
+    console.log("[5/8] Updating config.toml...");
+    await updateManagedConfig(scopeDirs.codexConfigFile, pkgRoot, scopeDirs.nativeAgentsDir, summary.config, backupContext, { dryRun, verbose, modelUpgradePrompt });
+    console.log(`  Config refresh complete (${scopeDirs.codexConfigFile}).\n`);
     // Step 5.5: Verify team CLI interop surface is available.
-    console.log('[5.5/8] Verifying Team CLI API interop...');
+    console.log("[5.5/8] Verifying Team CLI API interop...");
     const teamToolsCheck = await verifyTeamCliApiInterop(pkgRoot);
     if (teamToolsCheck.ok) {
-        console.log('  omx team api command detected (CLI-first interop ready)');
+        console.log("  omx team api command detected (CLI-first interop ready)");
     }
     else {
         console.log(`  WARNING: ${teamToolsCheck.message}`);
-        console.log('  Run `npm run build` and then re-run `omx setup`.');
+        console.log("  Run `npm run build` and then re-run `omx setup`.");
     }
     console.log();
     // Step 6: Generate AGENTS.md
-    console.log('[6/8] Generating AGENTS.md...');
-    const agentsMdSrc = join(pkgRoot, 'templates', 'AGENTS.md');
-    const agentsMdDst = join(projectRoot, 'AGENTS.md');
+    console.log("[6/8] Generating AGENTS.md...");
+    const agentsMdSrc = join(pkgRoot, "templates", "AGENTS.md");
+    const agentsMdDst = join(projectRoot, "AGENTS.md");
     const agentsMdExists = existsSync(agentsMdDst);
     // Guard: refuse to overwrite AGENTS.md during active session
     const activeSession = await readSessionState(projectRoot);
     const sessionIsActive = activeSession && !isSessionStale(activeSession);
     if (existsSync(agentsMdSrc)) {
-        let shouldOverwriteAgentsMd = force;
-        if (!force && agentsMdExists && process.stdin.isTTY && process.stdout.isTTY) {
-            shouldOverwriteAgentsMd = agentsOverwritePrompt
-                ? await agentsOverwritePrompt()
-                : await promptForAgentsOverwrite();
-        }
-        if (sessionIsActive && shouldOverwriteAgentsMd) {
-            console.log('  WARNING: Active omx session detected (pid ' + activeSession?.pid + ').');
-            console.log('  Skipping AGENTS.md overwrite to avoid corrupting runtime overlay.');
-            if (force) {
-                console.log('  Stop the active session first, then re-run setup --force.');
-            }
-            else {
-                console.log('  Stop the active session first, then re-run setup and approve overwrite (or use --force).');
-            }
+        const content = await readFile(agentsMdSrc, "utf-8");
+        const rewritten = applyScopePathRewritesToAgentsTemplate(content, resolvedScope.scope);
+        let changed = true;
+        if (agentsMdExists) {
+            const existing = await readFile(agentsMdDst, "utf-8");
+            changed = existing !== rewritten;
         }
-        else if (shouldOverwriteAgentsMd || !agentsMdExists) {
-            if (!dryRun) {
-                const content = await readFile(agentsMdSrc, 'utf-8');
-                const rewritten = applyScopePathRewritesToAgentsTemplate(content, resolvedScope.scope);
-                await writeFile(agentsMdDst, rewritten);
-            }
-            console.log('  Generated AGENTS.md in project root.');
+        if (sessionIsActive && agentsMdExists && changed) {
+            summary.agentsMd.skipped += 1;
+            console.log("  WARNING: Active omx session detected (pid " +
+                activeSession?.pid +
+                ").");
+            console.log("  Skipping AGENTS.md overwrite to avoid corrupting runtime overlay.");
+            console.log("  Stop the active session first, then re-run setup.");
         }
         else {
-            console.log('  AGENTS.md already exists (use --force to overwrite).');
+            await syncManagedContent(rewritten, agentsMdDst, summary.agentsMd, backupContext, { dryRun, verbose }, "AGENTS.md");
+            if (summary.agentsMd.updated > 0) {
+                console.log("  Generated AGENTS.md in project root.");
+            }
+            else if (summary.agentsMd.unchanged > 0) {
+                console.log("  AGENTS.md already up to date.");
+            }
         }
     }
     else {
-        console.log('  AGENTS.md template not found, skipping.');
+        summary.agentsMd.skipped += 1;
+        console.log("  AGENTS.md template not found, skipping.");
     }
     console.log();
     // Step 7: Set up notify hook
-    console.log('[7/8] Configuring notification hook...');
+    console.log("[7/8] Configuring notification hook...");
     await setupNotifyHook(pkgRoot, { dryRun, verbose });
-    console.log('  Done.\n');
+    console.log("  Done.\n");
     // Step 8: Configure HUD
-    console.log('[8/8] Configuring HUD...');
-    const hudConfigPath = join(projectRoot, '.omx', 'hud-config.json');
+    console.log("[8/8] Configuring HUD...");
+    const hudConfigPath = join(projectRoot, ".omx", "hud-config.json");
     if (force || !existsSync(hudConfigPath)) {
         if (!dryRun) {
-            const defaultHudConfig = { preset: 'focused' };
+            const defaultHudConfig = { preset: "focused" };
             await writeFile(hudConfigPath, JSON.stringify(defaultHudConfig, null, 2));
         }
         if (verbose)
-            console.log('  Wrote .omx/hud-config.json');
-        console.log('  HUD config created (preset: focused).');
+            console.log("  Wrote .omx/hud-config.json");
+        console.log("  HUD config created (preset: focused).");
     }
     else {
-        console.log('  HUD config already exists (use --force to overwrite).');
+        console.log("  HUD config already exists (use --force to overwrite).");
     }
-    console.log('  StatusLine configured in config.toml via [tui] section.');
+    console.log("  StatusLine configured in config.toml via [tui] section.");
+    console.log();
+    console.log("Setup refresh summary:");
+    logCategorySummary("prompts", summary.prompts);
+    logCategorySummary("skills", summary.skills);
+    logCategorySummary("native_agents", summary.nativeAgents);
+    logCategorySummary("agents_md", summary.agentsMd);
+    logCategorySummary("config", summary.config);
     console.log();
+    if (force) {
+        console.log("Force mode: enabled additional destructive maintenance (for example stale deprecated skill cleanup).");
+        console.log();
+    }
     console.log('Setup complete! Run "omx doctor" to verify installation.');
-    console.log('\nNext steps:');
-    console.log('  1. Start Codex CLI in your project directory');
-    console.log('  2. Use /prompts:architect, /prompts:executor, /prompts:planner as slash commands');
-    console.log('  3. Skills are available via /skills or implicit matching');
-    console.log('  4. The AGENTS.md orchestration brain is loaded automatically');
-    console.log('  5. Native agent roles registered in config.toml [agents.*]');
+    console.log("\nNext steps:");
+    console.log("  1. Start Codex CLI in your project directory");
+    console.log("  2. Use /prompts:architect, /prompts:executor, /prompts:planner as slash commands");
+    console.log("  3. Skills are available via /skills or implicit matching");
+    console.log("  4. The AGENTS.md orchestration brain is loaded automatically");
+    console.log("  5. Native agent roles registered in config.toml [agents.*]");
     if (isGitHubCliConfigured()) {
-        console.log('\nSupport the project: gh repo star Yeachan-Heo/oh-my-codex');
+        console.log("\nSupport the project: gh repo star Yeachan-Heo/oh-my-codex");
     }
 }
 function isLegacySkillPromptShim(content) {
@@ -332,19 +411,18 @@ function isLegacySkillPromptShim(content) {
 async function cleanupLegacySkillPromptShims(promptsSrcDir, promptsDstDir, options) {
     if (!existsSync(promptsSrcDir) || !existsSync(promptsDstDir))
         return 0;
-    const sourceFiles = new Set((await readdir(promptsSrcDir))
-        .filter(name => name.endsWith('.md')));
+    const sourceFiles = new Set((await readdir(promptsSrcDir)).filter((name) => name.endsWith(".md")));
     const installedFiles = await readdir(promptsDstDir);
     let removed = 0;
     for (const file of installedFiles) {
-        if (!file.endsWith('.md'))
+        if (!file.endsWith(".md"))
             continue;
         if (sourceFiles.has(file))
             continue;
         const fullPath = join(promptsDstDir, file);
-        let content = '';
+        let content = "";
         try {
-            content = await readFile(fullPath, 'utf-8');
+            content = await readFile(fullPath, "utf-8");
         }
         catch {
             continue;
@@ -361,14 +439,56 @@ async function cleanupLegacySkillPromptShims(promptsSrcDir, promptsDstDir, optio
     return removed;
 }
 function isGitHubCliConfigured() {
-    const result = spawnSync('gh', ['auth', 'status'], { stdio: 'ignore' });
+    const result = spawnSync("gh", ["auth", "status"], { stdio: "ignore" });
     return result.status === 0;
 }
-async function installDirectory(srcDir, dstDir, ext, options) {
+async function syncManagedFileFromDisk(srcPath, dstPath, summary, backupContext, options, verboseLabel) {
+    const destinationExists = existsSync(dstPath);
+    const changed = !destinationExists || (await filesDiffer(srcPath, dstPath));
+    if (!changed) {
+        summary.unchanged += 1;
+        return;
+    }
+    if (await ensureBackup(dstPath, destinationExists, backupContext, options)) {
+        summary.backedUp += 1;
+    }
+    if (!options.dryRun) {
+        await mkdir(dirname(dstPath), { recursive: true });
+        await copyFile(srcPath, dstPath);
+    }
+    summary.updated += 1;
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would update" : "updated"} ${verboseLabel}`);
+    }
+}
+async function syncManagedContent(content, dstPath, summary, backupContext, options, verboseLabel) {
+    const destinationExists = existsSync(dstPath);
+    let changed = true;
+    if (destinationExists) {
+        const existing = await readFile(dstPath, "utf-8");
+        changed = existing !== content;
+    }
+    if (!changed) {
+        summary.unchanged += 1;
+        return;
+    }
+    if (await ensureBackup(dstPath, destinationExists, backupContext, options)) {
+        summary.backedUp += 1;
+    }
+    if (!options.dryRun) {
+        await mkdir(dirname(dstPath), { recursive: true });
+        await writeFile(dstPath, content);
+    }
+    summary.updated += 1;
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would update" : "updated"} ${verboseLabel}`);
+    }
+}
+async function installDirectory(srcDir, dstDir, ext, backupContext, options, kindLabel) {
+    const summary = createEmptyCategorySummary();
     if (!existsSync(srcDir))
-        return 0;
+        return summary;
     const files = await readdir(srcDir);
-    let count = 0;
     for (const file of files) {
         if (!file.endsWith(ext))
             continue;
@@ -377,78 +497,67 @@ async function installDirectory(srcDir, dstDir, ext, options) {
         const srcStat = await stat(src);
         if (!srcStat.isFile())
             continue;
-        if (options.force || !existsSync(dst)) {
-            if (!options.dryRun) {
-                await copyFile(src, dst);
-            }
-            if (options.verbose)
-                console.log(`  ${file}`);
-            count++;
+        await syncManagedFileFromDisk(src, dst, summary, backupContext, options, `${kindLabel} ${file}`);
+    }
+    return summary;
+}
+async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, options) {
+    const summary = createEmptyCategorySummary();
+    if (!options.dryRun) {
+        await mkdir(agentsDir, { recursive: true });
+    }
+    for (const [name, agent] of Object.entries(AGENT_DEFINITIONS)) {
+        const promptPath = join(pkgRoot, "prompts", `${name}.md`);
+        if (!existsSync(promptPath)) {
+            continue;
         }
+        const promptContent = await readFile(promptPath, "utf-8");
+        const toml = generateAgentToml(agent, promptContent);
+        const dst = join(agentsDir, `${name}.toml`);
+        await syncManagedContent(toml, dst, summary, backupContext, options, `native agent ${name}.toml`);
     }
-    return count;
+    return summary;
 }
-async function installSkills(srcDir, dstDir, options) {
+async function installSkills(srcDir, dstDir, backupContext, options) {
+    const summary = createEmptyCategorySummary();
     if (!existsSync(srcDir))
-        return 0;
+        return summary;
     const manifest = tryReadCatalogManifest();
     const skillStatusByName = manifest
         ? new Map(manifest.skills.map((skill) => [skill.name, skill.status]))
         : null;
-    const isInstallableStatus = (status) => status === 'active' || status === 'internal';
+    const isInstallableStatus = (status) => status === "active" || status === "internal";
     const entries = await readdir(srcDir, { withFileTypes: true });
     const staleCandidateSkillNames = new Set(manifest?.skills.map((skill) => skill.name) ?? []);
-    let count = 0;
     for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
         staleCandidateSkillNames.add(entry.name);
         const status = skillStatusByName?.get(entry.name);
         if (skillStatusByName && !isInstallableStatus(status)) {
+            summary.skipped += 1;
             if (options.verbose) {
-                const label = status ?? 'unlisted';
+                const label = status ?? "unlisted";
                 console.log(`  skipped ${entry.name}/ (status: ${label})`);
             }
             continue;
         }
         const skillSrc = join(srcDir, entry.name);
         const skillDst = join(dstDir, entry.name);
-        const skillMd = join(skillSrc, 'SKILL.md');
+        const skillMd = join(skillSrc, "SKILL.md");
         if (!existsSync(skillMd))
             continue;
-        let copied = 0;
-        let overwritten = 0;
-        let skipped = 0;
-        const skillFiles = await readdir(skillSrc);
         if (!options.dryRun) {
             await mkdir(skillDst, { recursive: true });
         }
+        const skillFiles = await readdir(skillSrc);
         for (const sf of skillFiles) {
             const sfPath = join(skillSrc, sf);
             const sfStat = await stat(sfPath);
             if (!sfStat.isFile())
                 continue;
             const dstPath = join(skillDst, sf);
-            const dstExists = existsSync(dstPath);
-            if (dstExists && !options.force) {
-                skipped++;
-                continue;
-            }
-            if (!options.dryRun) {
-                await copyFile(sfPath, dstPath);
-            }
-            if (dstExists) {
-                overwritten++;
-            }
-            else {
-                copied++;
-            }
-        }
-        if (copied + overwritten > 0) {
-            count++;
-        }
-        if (options.verbose) {
-            console.log(`  ${entry.name}/ (copied: ${copied}, overwritten: ${overwritten}, skipped: ${skipped})`);
+            await syncManagedFileFromDisk(sfPath, dstPath, summary, backupContext, options, `skill ${entry.name}/${sf}`);
         }
     }
     if (options.force && manifest && existsSync(dstDir)) {
@@ -462,20 +571,68 @@ async function installSkills(srcDir, dstDir, options) {
             if (!options.dryRun) {
                 await rm(staleSkillDir, { recursive: true, force: true });
             }
+            summary.removed += 1;
             if (options.verbose) {
-                const prefix = options.dryRun ? 'would remove stale skill' : 'removed stale skill';
-                const label = status ?? 'unlisted';
+                const prefix = options.dryRun
+                    ? "would remove stale skill"
+                    : "removed stale skill";
+                const label = status ?? "unlisted";
                 console.log(`  ${prefix} ${staleSkill}/ (status: ${label})`);
             }
         }
     }
-    return count;
+    return summary;
+}
+async function updateManagedConfig(configPath, pkgRoot, agentsConfigDir, summary, backupContext, options) {
+    const existing = existsSync(configPath)
+        ? await readFile(configPath, "utf-8")
+        : "";
+    const currentModel = getRootModelName(existing);
+    let modelOverride;
+    if (currentModel === LEGACY_SETUP_MODEL) {
+        const shouldPrompt = typeof options.modelUpgradePrompt === "function" ||
+            (process.stdin.isTTY && process.stdout.isTTY);
+        if (shouldPrompt) {
+            const shouldUpgrade = options.modelUpgradePrompt
+                ? await options.modelUpgradePrompt(currentModel, DEFAULT_SETUP_MODEL)
+                : await promptForModelUpgrade(currentModel, DEFAULT_SETUP_MODEL);
+            if (shouldUpgrade) {
+                modelOverride = DEFAULT_SETUP_MODEL;
+            }
+        }
+    }
+    const finalConfig = buildMergedConfig(existing, pkgRoot, {
+        agentsConfigDir,
+        modelOverride,
+        verbose: options.verbose,
+    });
+    const changed = existing !== finalConfig;
+    if (!changed) {
+        summary.unchanged += 1;
+        return;
+    }
+    if (await ensureBackup(configPath, existsSync(configPath), backupContext, options)) {
+        summary.backedUp += 1;
+    }
+    if (!options.dryRun) {
+        await writeFile(configPath, finalConfig);
+    }
+    if (options.verbose &&
+        modelOverride &&
+        currentModel &&
+        currentModel !== modelOverride) {
+        console.log(`  ${options.dryRun ? "would update" : "updated"} root model from ${currentModel} to ${modelOverride}`);
+    }
+    summary.updated += 1;
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would update" : "updated"} config ${configPath}`);
+    }
 }
 async function setupNotifyHook(pkgRoot, options) {
-    const hookScript = join(pkgRoot, 'scripts', 'notify-hook.js');
+    const hookScript = join(pkgRoot, "scripts", "notify-hook.js");
     if (!existsSync(hookScript)) {
         if (options.verbose)
-            console.log('  Notify hook script not found, skipping.');
+            console.log("  Notify hook script not found, skipping.");
         return;
     }
     // The notify hook is configured in config.toml via mergeConfig
@@ -483,15 +640,18 @@ async function setupNotifyHook(pkgRoot, options) {
         console.log(`  Notify hook: ${hookScript}`);
 }
 async function verifyTeamCliApiInterop(pkgRoot) {
-    const teamCliPath = join(pkgRoot, 'dist', 'cli', 'team.js');
+    const teamCliPath = join(pkgRoot, "dist", "cli", "team.js");
     if (!existsSync(teamCliPath)) {
         return { ok: false, message: `missing ${teamCliPath}` };
     }
     try {
-        const content = await readFile(teamCliPath, 'utf-8');
+        const content = await readFile(teamCliPath, "utf-8");
         const missing = REQUIRED_TEAM_CLI_API_MARKERS.filter((marker) => !content.includes(marker));
         if (missing.length > 0) {
-            return { ok: false, message: `team CLI interop markers missing: ${missing.join(', ')}` };
+            return {
+                ok: false,
+                message: `team CLI interop markers missing: ${missing.join(", ")}`,
+            };
         }
         return { ok: true };
     }