oh-my-codex 0.14.4 → 0.15.1

package/dist/cli/setup.js

@@ -2,35 +2,49 @@
  * omx setup - Automated installation of oh-my-codex
  * Installs skills, prompts, MCP servers config, and AGENTS.md
  */
-import { mkdir, copyFile, readdir, readFile, rename, writeFile, stat, rm, } from "fs/promises";
+import { mkdir, cp, copyFile, readdir, readFile, rename, writeFile, stat, rm, } from "fs/promises";
 import { join, dirname, relative, basename } from "path";
 import { existsSync } from "fs";
 import { spawnSync } from "child_process";
 import { createInterface } from "readline/promises";
 import { homedir } from "os";
 import { codexHome, codexConfigPath, codexPromptsDir, codexAgentsDir, userSkillsDir, omxStateDir, detectLegacySkillRootOverlap, omxPlansDir, omxLogsDir, } from "../utils/paths.js";
-import { buildMergedConfig, getRootModelName, hasLegacyOmxTeamRunTable, } from "../config/generator.js";
+import { buildMergedConfig, getRootModelName, hasLegacyOmxTeamRunTable, stripExistingOmxBlocks, stripExistingSharedMcpRegistryBlock, stripOmxEnvSettings, stripOmxFeatureFlags, stripOmxSeededBehavioralDefaults, upsertCodexHooksFeatureFlag, OMX_DEVELOPER_INSTRUCTIONS, } from "../config/generator.js";
 import { mergeManagedCodexHooksConfig } from "../config/codex-hooks.js";
 import { getLegacyUnifiedMcpRegistryCandidate, getUnifiedMcpRegistryCandidates, loadUnifiedMcpRegistry, planClaudeCodeMcpSettingsSync, } from "../config/mcp-registry.js";
 import { generateAgentToml } from "../agents/native-config.js";
 import { AGENT_DEFINITIONS } from "../agents/definitions.js";
+import { getCatalogAgentStatusByName, getInstallableNativeAgentNames, isNativeAgentInstallableStatus, isSetupPromptAssetName, } from "../agents/policy.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 { DEFAULT_FRONTIER_MODEL } from "../config/models.js";
-import { addGeneratedAgentsMarker, hasOmxManagedAgentsSections, isOmxGeneratedAgentsMd, } from "../utils/agents-md.js";
+import { addGeneratedAgentsMarker, hasOmxManagedAgentsSections, isOmxGeneratedAgentsMd, upsertManagedAgentsBlock, } from "../utils/agents-md.js";
+import { DEFAULT_HUD_CONFIG } from "../hud/types.js";
+import { SETUP_INSTALL_MODES, SETUP_SCOPES, getSetupScopeFilePath, readPersistedSetupPreferences, } from "./setup-preferences.js";
+import { OMX_LOCAL_MARKETPLACE_NAME, resolvePackagedOmxMarketplace, upsertLocalOmxMarketplaceRegistration, } from "./plugin-marketplace.js";
+async function resolveStatusLinePresetForSetup(projectRoot, options) {
+    if (options.force) {
+        return DEFAULT_HUD_CONFIG.statusLine.preset;
+    }
+    const path = join(projectRoot, ".omx", "hud-config.json");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = JSON.parse(await readFile(path, "utf-8"));
+        const preset = raw?.statusLine?.preset;
+        if (preset === "minimal" || preset === "focused" || preset === "full") {
+            return preset;
+        }
+    }
+    catch {
+        // Malformed hud-config.json — fall through to default.
+    }
+    return undefined;
+}
 import { resolveAgentsModelTableContext, upsertAgentsModelTable, } from "../utils/agents-model-table.js";
-import { spawnPlatformCommandSync } from "../utils/platform-command.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",
-};
-export const SETUP_SCOPES = ["user", "project"];
+export { SETUP_INSTALL_MODES, SETUP_SCOPES };
 const PROJECT_GITIGNORE_ENTRIES = [
     ".omx/",
     ".codex/*",
@@ -44,6 +58,19 @@ const PROJECT_GITIGNORE_ENTRIES = [
 ];
 const LEGACY_PROJECT_GITIGNORE_ENTRIES = [".codex/"];
 const SETUP_ONLY_INSTALLABLE_SKILLS = new Set(["wiki"]);
+const HARD_DEPRECATED_SKILL_NAMES = new Set(["web-clone"]);
+function isCatalogInstallableStatus(status) {
+    return status === "active" || status === "internal";
+}
+function getSetupInstallableSkillNames(manifest = tryReadCatalogManifest()) {
+    return new Set([
+        ...(manifest?.skills ?? [])
+            .filter((skill) => typeof skill.name === "string" &&
+            isCatalogInstallableStatus(skill.status))
+            .map((skill) => skill.name),
+        ...SETUP_ONLY_INSTALLABLE_SKILLS,
+    ]);
+}
 function applyScopePathRewritesToAgentsTemplate(content, scope) {
     if (scope !== "project")
         return content;
@@ -55,10 +82,10 @@ const REQUIRED_TEAM_CLI_API_MARKERS = [
     "TEAM_API_OPERATIONS",
 ];
 const DEFAULT_SETUP_SCOPE = "user";
+const DEFAULT_SETUP_INSTALL_MODE = "legacy";
 const LEGACY_SETUP_MODEL = "gpt-5.3-codex";
 const DEFAULT_SETUP_MODEL = DEFAULT_FRONTIER_MODEL;
 const OBSOLETE_NATIVE_AGENT_FIELD = ["skill", "ref"].join("_");
-const TUI_OWNED_BY_CODEX_VERSION = [0, 107, 0];
 function createEmptyCategorySummary() {
     return {
         updated: 0,
@@ -234,16 +261,6 @@ async function buildLegacySkillOverlapNotice(scope) {
         message: `Detected ${overlap.overlappingSkillNames.length} overlapping skill names between canonical ${overlap.canonicalDir} and legacy ${overlap.legacyDir}.${mismatchSuffix} Remove or archive ~/.agents/skills after confirming ${overlap.canonicalDir} is the version you want Codex to load.`,
     };
 }
-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");
-}
 export function resolveScopeDirectories(scope, projectRoot) {
     if (scope === "project") {
         const codexHomeDir = join(projectRoot, ".codex");
@@ -265,33 +282,9 @@ export function resolveScopeDirectories(scope, projectRoot) {
         skillsDir: userSkillsDir(),
     };
 }
-async function readPersistedSetupPreferences(projectRoot) {
-    const scopePath = getScopeFilePath(projectRoot);
-    if (!existsSync(scopePath))
-        return undefined;
-    try {
-        const raw = await readFile(scopePath, "utf-8");
-        const parsed = JSON.parse(raw);
-        const persisted = {};
-        if (parsed && typeof parsed.scope === "string") {
-            // Direct match to current scopes
-            if (isSetupScope(parsed.scope)) {
-                persisted.scope = parsed.scope;
-            }
-            // Migrate legacy scope values (project-local → project)
-            const migrated = LEGACY_SCOPE_MIGRATION[parsed.scope];
-            if (migrated) {
-                console.warn(`[omx] Migrating persisted setup scope "${parsed.scope}" → "${migrated}" ` +
-                    `(see issue #243: simplified to user/project).`);
-                persisted.scope = migrated;
-            }
-        }
-        return Object.keys(persisted).length > 0 ? persisted : undefined;
-    }
-    catch {
-        // ignore invalid persisted scope and fall back to prompt/default
-    }
-    return undefined;
+function logCategorySummary(name, summary) {
+    console.log(`  ${name}: updated=${summary.updated}, unchanged=${summary.unchanged}, ` +
+        `backed_up=${summary.backedUp}, skipped=${summary.skipped}, removed=${summary.removed}`);
 }
 async function promptForSetupScope(defaultScope) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -302,20 +295,89 @@ async function promptForSetupScope(defaultScope) {
         output: process.stdout,
     });
     try {
+        const userDefaultMarker = defaultScope === "user" ? " (default)" : "";
+        const projectDefaultMarker = defaultScope === "project" ? " (default)" : "";
+        const defaultChoice = defaultScope === "project" ? "2" : "1";
         console.log("Select setup scope:");
-        console.log(`  1) user (default) — installs to ~/.codex (skills default to ~/.codex/skills)`);
-        console.log("  2) project — installs to ./.codex (local to project)");
-        const answer = (await rl.question("Scope [1-2] (default: 1): "))
+        console.log(`  1) user${userDefaultMarker} — installs to ${codexHome()} (skills default to ${userSkillsDir()})`);
+        console.log(`  2) project${projectDefaultMarker} — installs to ./.codex (local to project)`);
+        const answer = (await rl.question(`Scope [1-2] (default: ${defaultChoice}): `))
             .trim()
             .toLowerCase();
         if (answer === "2" || answer === "project")
             return "project";
+        if (answer === "1" || answer === "user")
+            return "user";
         return defaultScope;
     }
     finally {
         rl.close();
     }
 }
+async function promptForSetupInstallMode(defaultMode) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return defaultMode;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        console.log("Select user-scope skill delivery mode:");
+        console.log(`  1) legacy${defaultMode === "legacy" ? " (default)" : ""} — install/update OMX skills in the resolved user skill root`);
+        console.log(`  2) plugin${defaultMode === "plugin" ? " (default)" : ""} — rely on Codex plugin discovery and clean up matching legacy OMX-managed setup artifacts`);
+        const defaultChoice = defaultMode === "plugin" ? "2" : "1";
+        const answer = (await rl.question(`Install mode [1-2] (default: ${defaultChoice}): `))
+            .trim()
+            .toLowerCase();
+        if (answer === "2" || answer === "plugin")
+            return "plugin";
+        if (answer === "1" || answer === "legacy")
+            return "legacy";
+        return defaultMode;
+    }
+    finally {
+        rl.close();
+    }
+}
+function hasPersistedSetupPreferences(preferences) {
+    return Boolean(preferences?.scope || preferences?.installMode);
+}
+function formatPersistedSetupPreferenceSummary(preferences) {
+    return [
+        `scope=${preferences.scope ?? "not recorded"}`,
+        `installMode=${preferences.installMode ?? "not recorded"}`,
+    ].join(", ");
+}
+async function promptForPersistedSetupReview(preferences) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return "keep";
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        console.log("Existing OMX setup preferences detected:");
+        console.log(`  ${formatPersistedSetupPreferenceSummary(preferences)}`);
+        console.log("  1) keep   — reuse these choices for this setup run");
+        console.log("  2) review — review/change choices, using these values as defaults");
+        console.log("  3) reset  — ignore saved choices and run setup as if fresh");
+        const answer = (await rl.question("Setup preferences [1-3] (default: 1 keep): "))
+            .trim()
+            .toLowerCase();
+        if (answer === "2" || answer === "review" || answer === "change") {
+            return "review";
+        }
+        if (answer === "3" || answer === "reset" || answer === "fresh") {
+            return "reset";
+        }
+        return "keep";
+    }
+    finally {
+        rl.close();
+    }
+}
 async function promptForModelUpgrade(currentModel, targetModel) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         return false;
@@ -334,38 +396,43 @@ async function promptForModelUpgrade(currentModel, targetModel) {
         rl.close();
     }
 }
-function parseSemverTriplet(version) {
-    const match = version.match(/(\d+)\.(\d+)\.(\d+)/);
-    if (!match)
-        return null;
-    return [Number(match[1]), Number(match[2]), Number(match[3])];
-}
-function semverGte(version, minimum) {
-    if (version[0] !== minimum[0])
-        return version[0] > minimum[0];
-    if (version[1] !== minimum[1])
-        return version[1] > minimum[1];
-    return version[2] >= minimum[2];
-}
-function probeInstalledCodexVersion() {
-    const { result } = spawnPlatformCommandSync("codex", ["--version"], {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"],
+async function promptForAgentsOverwrite(destinationPath) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return false;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
     });
-    if (result.error || result.status !== 0)
-        return null;
-    const stdout = (result.stdout || "").trim();
-    return stdout === "" ? null : stdout;
+    try {
+        const answer = (await rl.question(`Overwrite existing AGENTS.md at "${destinationPath}"? [y/N]: `))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
 }
-function shouldOmxManageTuiFromCodexVersion(versionOutput) {
-    if (!versionOutput)
-        return true;
-    const parsed = parseSemverTriplet(versionOutput);
-    if (!parsed)
-        return true;
-    return !semverGte(parsed, TUI_OWNED_BY_CODEX_VERSION);
+async function promptForPluginAgentsMdDefault(destinationPath) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return false;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await rl.question(`Plugin mode: install OMX AGENTS.md defaults at "${destinationPath}"? [y/N]: `))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
 }
-async function promptForAgentsOverwrite(destinationPath) {
+async function promptForPluginDeveloperInstructionsDefault(configPath) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         return false;
     }
@@ -374,7 +441,25 @@ async function promptForAgentsOverwrite(destinationPath) {
         output: process.stdout,
     });
     try {
-        const answer = (await rl.question(`Overwrite existing AGENTS.md at "${destinationPath}"? [y/N]: `))
+        const answer = (await rl.question(`Plugin mode: add OMX developer_instructions defaults to "${configPath}"? [y/N]: `))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptForPluginDeveloperInstructionsOverwrite(configPath) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return false;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await rl.question(`Plugin mode: overwrite existing developer_instructions in "${configPath}" with OMX defaults? [y/N]: `))
             .trim()
             .toLowerCase();
         return answer === "y" || answer === "yes";
@@ -383,26 +468,132 @@ async function promptForAgentsOverwrite(destinationPath) {
         rl.close();
     }
 }
-async function resolveSetupScope(projectRoot, requestedScope) {
+async function resolveSetupScope(projectRoot, requestedScope, persistedReviewDecision = "keep", persistedPreferences, setupScopePrompt) {
     if (requestedScope) {
         return { scope: requestedScope, source: "cli" };
     }
-    const persisted = await readPersistedSetupPreferences(projectRoot);
-    if (persisted?.scope) {
+    const persisted = persistedPreferences ?? (await readPersistedSetupPreferences(projectRoot));
+    if (persisted?.scope && persistedReviewDecision === "keep") {
         return { scope: persisted.scope, source: "persisted" };
     }
-    if (process.stdin.isTTY && process.stdout.isTTY) {
-        const scope = await promptForSetupScope(DEFAULT_SETUP_SCOPE);
+    if (typeof setupScopePrompt === "function" ||
+        (process.stdin.isTTY && process.stdout.isTTY)) {
+        const defaultScope = persistedReviewDecision === "review" && persisted?.scope
+            ? persisted.scope
+            : DEFAULT_SETUP_SCOPE;
+        const scope = setupScopePrompt
+            ? await setupScopePrompt(defaultScope)
+            : await promptForSetupScope(defaultScope);
         return { scope, source: "prompt" };
     }
     return { scope: DEFAULT_SETUP_SCOPE, source: "default" };
 }
+async function readPluginManifestName(manifestPath) {
+    try {
+        const parsed = JSON.parse(await readFile(manifestPath, "utf-8"));
+        return typeof parsed === "object" &&
+            parsed !== null &&
+            "name" in parsed &&
+            typeof parsed.name === "string"
+            ? parsed.name
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function discoverOmxPluginCacheDir(cacheRoot = join(codexHome(), "plugins", "cache")) {
+    if (!existsSync(cacheRoot))
+        return null;
+    const queue = [
+        { path: cacheRoot, depth: 0 },
+    ];
+    const maxDepth = 5;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current)
+            break;
+        const manifestPath = join(current.path, ".codex-plugin", "plugin.json");
+        if (existsSync(manifestPath)) {
+            const name = await readPluginManifestName(manifestPath);
+            if (name === "oh-my-codex") {
+                return current.path;
+            }
+        }
+        if (current.depth >= maxDepth)
+            continue;
+        let entries;
+        try {
+            entries = await readdir(current.path, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === ".git" || entry.name === "node_modules")
+                continue;
+            queue.push({
+                path: join(current.path, entry.name),
+                depth: current.depth + 1,
+            });
+        }
+    }
+    return null;
+}
+async function resolveSetupInstallMode(projectRoot, scope, requestedInstallMode, installModePrompt, persistedReviewDecision = "keep", persistedPreferences) {
+    if (requestedInstallMode) {
+        return { installMode: requestedInstallMode, source: "cli" };
+    }
+    const persisted = persistedPreferences ?? (await readPersistedSetupPreferences(projectRoot));
+    if (persisted?.installMode &&
+        persistedReviewDecision === "keep" &&
+        persisted.scope === scope) {
+        return { installMode: persisted.installMode, source: "persisted" };
+    }
+    if (scope !== "user")
+        return null;
+    const discoveredPluginCacheDir = await discoverOmxPluginCacheDir();
+    const defaultMode = persistedReviewDecision === "review" && persisted?.installMode
+        ? persisted.installMode
+        : discoveredPluginCacheDir
+            ? "plugin"
+            : DEFAULT_SETUP_INSTALL_MODE;
+    if (typeof installModePrompt === "function" ||
+        (process.stdin.isTTY && process.stdout.isTTY)) {
+        if (discoveredPluginCacheDir) {
+            console.log(`Detected installed oh-my-codex Codex plugin cache at ${discoveredPluginCacheDir}.`);
+        }
+        const installMode = installModePrompt
+            ? await installModePrompt(defaultMode)
+            : await promptForSetupInstallMode(defaultMode);
+        return { installMode, source: "prompt" };
+    }
+    return { installMode: defaultMode, source: "default" };
+}
 function hasGitignoreEntry(content, entry) {
     return content
         .split(/\r?\n/)
         .map((line) => line.trim())
         .some((line) => line === entry);
 }
+function isProjectPathIgnoredByGit(projectRoot, path) {
+    const result = spawnSync("git", ["check-ignore", "--no-index", "-q", path], {
+        cwd: projectRoot,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    return result.status === 0;
+}
+function shouldAddProjectGitignoreEntry(projectRoot, content, entry) {
+    if (hasGitignoreEntry(content, entry))
+        return false;
+    if (entry === ".omx/" && isProjectPathIgnoredByGit(projectRoot, entry)) {
+        return false;
+    }
+    return true;
+}
 function stripLegacyGitignoreEntries(content, legacyEntries) {
     const legacyEntrySet = new Set(legacyEntries);
     const lines = content.split(/\r?\n/);
@@ -420,13 +611,13 @@ async function ensureProjectGitignore(projectRoot, backupContext, options) {
         ? await readFile(gitignorePath, "utf-8")
         : "";
     const normalized = stripLegacyGitignoreEntries(existing, LEGACY_PROJECT_GITIGNORE_ENTRIES);
-    const missingEntries = PROJECT_GITIGNORE_ENTRIES.filter((entry) => !hasGitignoreEntry(normalized.content, entry));
+    const missingEntries = PROJECT_GITIGNORE_ENTRIES.filter((entry) => shouldAddProjectGitignoreEntry(projectRoot, normalized.content, entry));
     if (missingEntries.length === 0 && !normalized.removed) {
         return "unchanged";
     }
     const nextContent = destinationExists
         ? `${normalized.content}${normalized.content.endsWith("\n") || normalized.content.length === 0 ? "" : "\n"}${missingEntries.join("\n")}${missingEntries.length > 0 ? "\n" : ""}`
-        : `${PROJECT_GITIGNORE_ENTRIES.join("\n")}\n`;
+        : `${missingEntries.join("\n")}\n`;
     if (await ensureBackup(gitignorePath, destinationExists, backupContext, options)) {
         // backup created when refreshing a pre-existing .gitignore
     }
@@ -444,41 +635,379 @@ async function ensureProjectGitignore(projectRoot, backupContext, options) {
     }
     return destinationExists ? "updated" : "created";
 }
-async function persistSetupScope(projectRoot, scope, options) {
-    const scopePath = getScopeFilePath(projectRoot);
+async function persistSetupPreferences(projectRoot, preferences, options) {
+    const scopePath = getSetupScopeFilePath(projectRoot);
     if (options.dryRun) {
         if (options.verbose)
             console.log(`  dry-run: skip persisting ${scopePath}`);
         return;
     }
     await mkdir(dirname(scopePath), { recursive: true });
-    const payload = { scope };
-    await writeFile(scopePath, JSON.stringify(payload, null, 2) + "\n");
+    await writeFile(scopePath, JSON.stringify(preferences, null, 2) + "\n");
     if (options.verbose)
         console.log(`  Wrote ${scopePath}`);
 }
+async function removeEmptyDirectoryIfPresent(dirPath, options) {
+    if (options.dryRun || !existsSync(dirPath))
+        return;
+    try {
+        const remaining = await readdir(dirPath);
+        if (remaining.length === 0) {
+            await rm(dirPath, { recursive: true, force: true });
+            if (options.verbose)
+                console.log(`  removed empty directory ${dirPath}`);
+        }
+    }
+    catch {
+        // Best-effort cleanup only.
+    }
+}
+async function cleanupPluginModeLegacyPrompts(srcDir, dstDir, backupContext, options) {
+    const summary = createEmptyCategorySummary();
+    if (!existsSync(srcDir) || !existsSync(dstDir))
+        return summary;
+    const manifest = tryReadCatalogManifest();
+    for (const file of await readdir(srcDir)) {
+        if (!file.endsWith(".md"))
+            continue;
+        const promptName = file.slice(0, -3);
+        if (manifest && !isSetupPromptAssetName(promptName, manifest))
+            continue;
+        const dst = join(dstDir, file);
+        if (!existsSync(dst))
+            continue;
+        if (await ensureBackup(dst, true, backupContext, options)) {
+            summary.backedUp += 1;
+        }
+        if (!options.dryRun) {
+            await rm(dst, { force: true });
+        }
+        summary.removed += 1;
+        if (options.verbose) {
+            console.log(`  ${options.dryRun ? "would archive and remove" : "archived and removed"} legacy prompt ${file}`);
+        }
+    }
+    await removeEmptyDirectoryIfPresent(dstDir, options);
+    return summary;
+}
+async function cleanupPluginModeLegacyNativeAgents(pkgRoot, agentsDir, backupContext, options) {
+    const summary = createEmptyCategorySummary();
+    if (!existsSync(agentsDir))
+        return summary;
+    const manifest = tryReadCatalogManifest();
+    const agentStatusByName = manifest
+        ? getCatalogAgentStatusByName(manifest)
+        : null;
+    for (const [name, agent] of Object.entries(AGENT_DEFINITIONS)) {
+        const status = agentStatusByName?.get(name);
+        if (agentStatusByName && !isNativeAgentInstallableStatus(status))
+            continue;
+        const dst = join(agentsDir, `${name}.toml`);
+        const promptPath = join(pkgRoot, "prompts", `${name}.md`);
+        if (!existsSync(dst) || !existsSync(promptPath))
+            continue;
+        const promptContent = await readFile(promptPath, "utf-8");
+        const expectedToml = generateAgentToml(agent, promptContent, {
+            codexHomeOverride: join(agentsDir, ".."),
+        });
+        const installedToml = await readFile(dst, "utf-8");
+        if (installedToml !== expectedToml &&
+            !isGeneratedOmxNativeAgentToml(installedToml, name)) {
+            summary.skipped += 1;
+            if (options.verbose) {
+                console.log(`  skipped legacy native agent cleanup for ${name}.toml: installed content is not an OMX-generated native agent`);
+            }
+            continue;
+        }
+        if (await ensureBackup(dst, true, backupContext, options)) {
+            summary.backedUp += 1;
+        }
+        if (!options.dryRun) {
+            await rm(dst, { force: true });
+        }
+        summary.removed += 1;
+        if (options.verbose) {
+            console.log(`  ${options.dryRun ? "would archive and remove" : "archived and removed"} legacy native agent ${name}.toml`);
+        }
+    }
+    if (manifest) {
+        const generatedCleanup = await cleanupGeneratedNonInstallableNativeAgents(agentsDir, manifest, backupContext, options);
+        summary.backedUp += generatedCleanup.backedUp;
+        summary.removed += generatedCleanup.removed;
+    }
+    await removeEmptyDirectoryIfPresent(agentsDir, options);
+    return summary;
+}
+function stripPluginModeLegacyRootDefaults(config) {
+    const lines = config.split(/\r?\n/);
+    const firstTableIndex = lines.findIndex((line) => /^\s*\[/.test(line));
+    const boundary = firstTableIndex >= 0 ? firstTableIndex : lines.length;
+    const result = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (index < boundary &&
+            line.trim() ===
+                "# oh-my-codex top-level settings (must be before any [table])") {
+            continue;
+        }
+        if (index < boundary &&
+            /^\s*notify\s*=\s*\["node",\s*".*notify-hook\.js"\]\s*$/.test(line)) {
+            continue;
+        }
+        if (index < boundary &&
+            /^\s*model_reasoning_effort\s*=\s*"medium"\s*$/.test(line)) {
+            continue;
+        }
+        if (index < boundary &&
+            /^\s*developer_instructions\s*=/.test(line) &&
+            line.includes("You have oh-my-codex installed.")) {
+            continue;
+        }
+        result.push(line);
+    }
+    return result.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+function rootHasTomlKey(config, key) {
+    const lines = config.split(/\r?\n/);
+    const firstTableIndex = lines.findIndex((line) => /^\s*\[/.test(line));
+    const boundary = firstTableIndex >= 0 ? firstTableIndex : lines.length;
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^\\s*${escapedKey}\\s*=`);
+    return lines.slice(0, boundary).some((line) => pattern.test(line));
+}
+function replaceRootTomlKey(config, key, line) {
+    const lines = config.trimEnd().split(/\r?\n/);
+    const firstTableIndex = lines.findIndex((entry) => /^\s*\[/.test(entry));
+    const boundary = firstTableIndex < 0 ? lines.length : firstTableIndex;
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^\\s*${escapedKey}\\s*=`);
+    for (let i = 0; i < boundary; i++) {
+        if (pattern.test(lines[i])) {
+            lines[i] = line;
+            return lines.join("\n") + "\n";
+        }
+    }
+    return insertRootTomlKey(config, line);
+}
+function insertRootTomlKey(config, line) {
+    const lines = config.trimEnd().split(/\r?\n/);
+    if (lines.length === 1 && lines[0] === "")
+        return `${line}\n`;
+    const firstTableIndex = lines.findIndex((entry) => /^\s*\[/.test(entry));
+    if (firstTableIndex < 0)
+        return `${lines.join("\n")}\n${line}\n`;
+    const before = lines
+        .slice(0, firstTableIndex)
+        .filter((entry) => entry.trim() !== "");
+    const after = lines.slice(firstTableIndex);
+    return [...before, line, "", ...after].join("\n") + "\n";
+}
+async function ensurePluginMarketplaceRegistration(configPath, pkgRoot, backupContext, summary, options) {
+    const packagedMarketplace = await resolvePackagedOmxMarketplace(pkgRoot);
+    if (!packagedMarketplace) {
+        summary.skipped += 1;
+        return "unavailable";
+    }
+    const existingConfig = existsSync(configPath)
+        ? await readFile(configPath, "utf-8")
+        : "";
+    const nextConfig = upsertLocalOmxMarketplaceRegistration(existingConfig, pkgRoot);
+    const destinationExists = existsSync(configPath);
+    if (nextConfig === existingConfig) {
+        summary.unchanged += 1;
+        return "unchanged";
+    }
+    if (await ensureBackup(configPath, destinationExists, backupContext, options)) {
+        summary.backedUp += 1;
+    }
+    if (!options.dryRun) {
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, nextConfig);
+    }
+    summary.updated += 1;
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would register" : "registered"} local Codex plugin marketplace ${OMX_LOCAL_MARKETPLACE_NAME} from ${pkgRoot}`);
+    }
+    return "updated";
+}
+async function applyPluginModeHooksConfig(configPath, hooksPath, pkgRoot, backupContext, summary, options) {
+    const existingConfig = existsSync(configPath)
+        ? await readFile(configPath, "utf-8")
+        : "";
+    const nextConfig = upsertCodexHooksFeatureFlag(existingConfig).trimEnd() + "\n";
+    if (nextConfig !== existingConfig) {
+        if (await ensureBackup(configPath, existsSync(configPath), backupContext, options)) {
+            summary.backedUp += 1;
+        }
+        if (!options.dryRun) {
+            await mkdir(dirname(configPath), { recursive: true });
+            await writeFile(configPath, nextConfig);
+        }
+        summary.updated += 1;
+    }
+    else {
+        summary.unchanged += 1;
+    }
+    const existingHooksContent = existsSync(hooksPath)
+        ? await readFile(hooksPath, "utf-8")
+        : null;
+    const hooksConfig = mergeManagedCodexHooksConfig(existingHooksContent, pkgRoot);
+    await syncManagedContent(hooksConfig, hooksPath, summary, backupContext, options, `native hooks ${hooksPath}`);
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would configure" : "configured"} plugin-mode native hooks at ${hooksPath}`);
+    }
+}
+async function applyPluginDeveloperInstructionsDefault(configPath, backupContext, summary, options) {
+    const existing = existsSync(configPath)
+        ? await readFile(configPath, "utf-8")
+        : "";
+    const line = `developer_instructions = ${JSON.stringify(OMX_DEVELOPER_INSTRUCTIONS)}`;
+    const hasExistingDeveloperInstructions = rootHasTomlKey(existing, "developer_instructions");
+    if (hasExistingDeveloperInstructions) {
+        const overwrite = options.pluginDeveloperInstructionsOverwritePrompt
+            ? await options.pluginDeveloperInstructionsOverwritePrompt(configPath)
+            : await promptForPluginDeveloperInstructionsOverwrite(configPath);
+        if (!overwrite) {
+            summary.skipped += 1;
+            if (options.verbose) {
+                console.log("  skipped plugin developer_instructions default: root developer_instructions already exists");
+            }
+            return "exists";
+        }
+    }
+    const nextConfig = hasExistingDeveloperInstructions
+        ? replaceRootTomlKey(existing, "developer_instructions", line)
+        : insertRootTomlKey(existing, line);
+    const destinationExists = existsSync(configPath);
+    if (await ensureBackup(configPath, destinationExists, backupContext, options)) {
+        summary.backedUp += 1;
+    }
+    if (!options.dryRun) {
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, nextConfig);
+    }
+    summary.updated += 1;
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would add" : "added"} plugin developer_instructions default to ${configPath}`);
+    }
+    return "updated";
+}
+async function cleanupPluginModeLegacyConfig(configPath, backupContext, options) {
+    if (!existsSync(configPath))
+        return false;
+    const original = await readFile(configPath, "utf-8");
+    let config = original;
+    config = stripExistingOmxBlocks(config).cleaned;
+    config = stripExistingSharedMcpRegistryBlock(config).cleaned;
+    config = stripPluginModeLegacyRootDefaults(config);
+    config = stripOmxSeededBehavioralDefaults(config);
+    config = stripOmxFeatureFlags(config);
+    config = stripOmxEnvSettings(config);
+    config = config.trim();
+    const nextConfig = config.length > 0 ? `${config}\n` : "";
+    if (nextConfig === original)
+        return false;
+    if (await ensureBackup(configPath, true, backupContext, options)) {
+        // backup created for pre-existing config
+    }
+    if (!options.dryRun) {
+        if (nextConfig.length === 0) {
+            await rm(configPath, { force: true });
+        }
+        else {
+            await writeFile(configPath, nextConfig);
+        }
+    }
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would clean" : nextConfig.length === 0 ? "removed" : "cleaned"} legacy OMX config ${basename(configPath)}`);
+    }
+    return true;
+}
+async function cleanupPluginModeLegacyAgentsMd(agentsMdPath, backupContext, options) {
+    if (!existsSync(agentsMdPath))
+        return false;
+    const content = await readFile(agentsMdPath, "utf-8");
+    if (!isOmxGeneratedAgentsMd(content))
+        return false;
+    if (await ensureBackup(agentsMdPath, true, backupContext, options)) {
+        // backup created for pre-existing AGENTS.md
+    }
+    if (!options.dryRun) {
+        await rm(agentsMdPath, { force: true });
+    }
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would remove" : "removed"} legacy OMX-generated AGENTS.md`);
+    }
+    return true;
+}
 export async function setup(options = {}) {
-    const { force = false, dryRun = false, scope: requestedScope, verbose = false, modelUpgradePrompt, } = options;
+    const { force = false, dryRun = false, installMode: requestedInstallMode, scope: requestedScope, verbose = false, setupScopePrompt, persistedSetupReviewPrompt, installModePrompt, modelUpgradePrompt, pluginAgentsMdPrompt, pluginDeveloperInstructionsPrompt, pluginDeveloperInstructionsOverwritePrompt, } = options;
     const pkgRoot = getPackageRoot();
     const projectRoot = process.cwd();
-    const resolvedScope = await resolveSetupScope(projectRoot, requestedScope);
+    const persistedPreferences = await readPersistedSetupPreferences(projectRoot, { warnOnLegacyScope: true });
+    let persistedReviewDecision = "keep";
+    const effectiveScopeForInstallMode = requestedScope ?? persistedPreferences?.scope ?? DEFAULT_SETUP_SCOPE;
+    const wouldUsePersistedScope = !requestedScope && Boolean(persistedPreferences?.scope);
+    const wouldUsePersistedInstallMode = !requestedInstallMode &&
+        Boolean(persistedPreferences?.installMode) &&
+        (!persistedPreferences?.scope ||
+            persistedPreferences.scope === effectiveScopeForInstallMode);
+    const shouldReviewPersistedSetup = hasPersistedSetupPreferences(persistedPreferences) &&
+        (wouldUsePersistedScope || wouldUsePersistedInstallMode) &&
+        (typeof persistedSetupReviewPrompt === "function" ||
+            (process.stdin.isTTY && process.stdout.isTTY));
+    if (shouldReviewPersistedSetup) {
+        persistedReviewDecision = persistedSetupReviewPrompt
+            ? await persistedSetupReviewPrompt(persistedPreferences)
+            : await promptForPersistedSetupReview(persistedPreferences);
+        console.log(`Setup preference review: ${persistedReviewDecision} (${formatPersistedSetupPreferenceSummary(persistedPreferences)})\n`);
+    }
+    const resolvedScope = await resolveSetupScope(projectRoot, requestedScope, persistedReviewDecision, persistedPreferences, setupScopePrompt);
+    const resolvedInstallMode = await resolveSetupInstallMode(projectRoot, resolvedScope.scope, requestedInstallMode, installModePrompt, persistedReviewDecision, persistedPreferences);
     const scopeDirs = resolveScopeDirectories(resolvedScope.scope, projectRoot);
     const scopeSourceMessage = resolvedScope.source === "persisted" ? " (from .omx/setup-scope.json)" : "";
     const backupContext = getBackupContext(resolvedScope.scope, projectRoot);
+    const isPluginInstallMode = resolvedInstallMode?.installMode === "plugin";
+    const pluginAgentsMdDst = resolvedScope.scope === "project"
+        ? join(projectRoot, "AGENTS.md")
+        : join(scopeDirs.codexHomeDir, "AGENTS.md");
+    const usePluginDeveloperInstructionsDefault = isPluginInstallMode
+        ? pluginDeveloperInstructionsPrompt
+            ? await pluginDeveloperInstructionsPrompt(scopeDirs.codexConfigFile)
+            : await promptForPluginDeveloperInstructionsDefault(scopeDirs.codexConfigFile)
+        : false;
+    const usePluginAgentsMdDefault = isPluginInstallMode
+        ? pluginAgentsMdPrompt
+            ? await pluginAgentsMdPrompt(pluginAgentsMdDst)
+            : await promptForPluginAgentsMdDefault(pluginAgentsMdDst)
+        : false;
     console.log("oh-my-codex setup");
     console.log("=================\n");
     console.log(`Using setup scope: ${resolvedScope.scope}${scopeSourceMessage}\n`);
+    if (resolvedInstallMode) {
+        const installModeSourceMessage = resolvedInstallMode.source === "persisted"
+            ? " (from .omx/setup-scope.json)"
+            : "";
+        console.log(`Using setup install mode: ${resolvedInstallMode.installMode}${installModeSourceMessage}\n`);
+    }
     // Step 1: Ensure directories exist
     console.log("[1/8] Creating directories...");
-    const dirs = [
-        scopeDirs.codexHomeDir,
-        scopeDirs.promptsDir,
-        scopeDirs.skillsDir,
-        scopeDirs.nativeAgentsDir,
-        omxStateDir(projectRoot),
-        omxPlansDir(projectRoot),
-        omxLogsDir(projectRoot),
-    ];
+    const dirs = isPluginInstallMode
+        ? [
+            scopeDirs.codexHomeDir,
+            omxStateDir(projectRoot),
+            omxPlansDir(projectRoot),
+            omxLogsDir(projectRoot),
+        ]
+        : [
+            scopeDirs.codexHomeDir,
+            scopeDirs.promptsDir,
+            scopeDirs.skillsDir,
+            scopeDirs.nativeAgentsDir,
+            omxStateDir(projectRoot),
+            omxPlansDir(projectRoot),
+            omxLogsDir(projectRoot),
+        ];
     for (const dir of dirs) {
         if (!dryRun) {
             await mkdir(dir, { recursive: true });
@@ -486,7 +1015,17 @@ export async function setup(options = {}) {
         if (verbose)
             console.log(`  mkdir ${dir}`);
     }
-    await persistSetupScope(projectRoot, resolvedScope.scope, {
+    const setupPreferencesToPersist = resolvedInstallMode &&
+        (resolvedScope.scope === "user" ||
+            resolvedInstallMode.installMode === "plugin")
+        ? {
+            scope: resolvedScope.scope,
+            installMode: resolvedInstallMode.installMode,
+        }
+        : {
+            scope: resolvedScope.scope,
+        };
+    await persistSetupPreferences(projectRoot, setupPreferencesToPersist, {
         dryRun,
         verbose,
     });
@@ -507,37 +1046,63 @@ export async function setup(options = {}) {
     {
         const promptsSrc = join(pkgRoot, "prompts");
         const promptsDst = scopeDirs.promptsDir;
-        summary.prompts = await installPrompts(promptsSrc, promptsDst, backupContext, { force, dryRun, verbose });
-        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).`);
+        if (isPluginInstallMode) {
+            summary.prompts = await cleanupPluginModeLegacyPrompts(promptsSrc, promptsDst, backupContext, { dryRun, verbose });
+            console.log(summary.prompts.removed > 0
+                ? `  ${dryRun ? "Would archive and remove" : "Archived and removed"} ${summary.prompts.removed} legacy OMX-managed prompt file(s).\n`
+                : "  Prompt refresh skipped; no legacy OMX-managed prompt files found.\n");
+        }
+        else {
+            summary.prompts = await installPrompts(promptsSrc, promptsDst, backupContext, { force, dryRun, verbose });
+            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).`);
+                }
+                else {
+                    console.log(`  Removed ${cleanedLegacyPromptShims} legacy skill prompt shim file(s).`);
+                }
+            }
+            if (catalogCounts) {
+                console.log(`  Prompt refresh complete (catalog baseline: ${catalogCounts.prompts}).\n`);
             }
             else {
-                console.log(`  Removed ${cleanedLegacyPromptShims} legacy skill prompt shim file(s).`);
+                console.log("  Prompt refresh complete.\n");
             }
         }
-        if (catalogCounts) {
-            console.log(`  Prompt refresh complete (catalog baseline: ${catalogCounts.prompts}).\n`);
-        }
-        else {
-            console.log("  Prompt refresh complete.\n");
-        }
     }
     // Step 3: Install skills
     console.log("[3/8] Installing skills...");
     {
         const skillsSrc = join(pkgRoot, "skills");
         const skillsDst = scopeDirs.skillsDir;
-        summary.skills = await installSkills(skillsSrc, skillsDst, backupContext, {
-            force,
-            dryRun,
-            verbose,
-        });
+        if (isPluginInstallMode) {
+            summary.skills = createEmptyCategorySummary();
+            const cleanup = await cleanupLegacyManagedSkills(skillsSrc, skillsDst, backupContext, { dryRun, verbose });
+            summary.skills.backedUp += cleanup.backedUp;
+            summary.skills.removed += cleanup.removedSkillNames.length;
+            summary.skills.skipped += cleanup.skippedSkillNames.length;
+            for (const warning of cleanup.warnings) {
+                console.log(`  warning: ${warning}`);
+            }
+            if (cleanup.removedSkillNames.length > 0) {
+                console.log(`  ${dryRun ? "Would remove" : "Removed"} ${cleanup.removedSkillNames.length} legacy OMX-managed skill director${cleanup.removedSkillNames.length === 1 ? "y" : "ies"}.`);
+            }
+            else {
+                console.log("  Skill refresh skipped; no removable legacy OMX-managed skill directories found.");
+            }
+        }
+        else {
+            summary.skills = await installSkills(skillsSrc, skillsDst, backupContext, {
+                force,
+                dryRun,
+                verbose,
+            });
+        }
         if (catalogCounts) {
             console.log(`  Skill refresh complete (catalog baseline: ${catalogCounts.skills}).\n`);
         }
@@ -547,7 +1112,13 @@ export async function setup(options = {}) {
     }
     // Step 4: Install native agent configs
     console.log("[4/8] Installing native agent configs...");
-    {
+    if (isPluginInstallMode) {
+        summary.nativeAgents = await cleanupPluginModeLegacyNativeAgents(pkgRoot, scopeDirs.nativeAgentsDir, backupContext, { dryRun, verbose });
+        console.log(summary.nativeAgents.removed > 0
+            ? `  ${dryRun ? "Would archive and remove" : "Archived and removed"} ${summary.nativeAgents.removed} legacy OMX-managed native agent config(s).\n`
+            : "  Native agent refresh skipped; no legacy OMX-managed native agent configs found.\n");
+    }
+    else {
         summary.nativeAgents = await refreshNativeAgentConfigs(pkgRoot, scopeDirs.nativeAgentsDir, backupContext, {
             force,
             dryRun,
@@ -557,39 +1128,93 @@ export async function setup(options = {}) {
     }
     // Step 5: Update config.toml
     console.log("[5/8] Updating config.toml...");
-    const registryCandidates = getUnifiedMcpRegistryCandidates();
-    const defaultRegistryCandidates = registryCandidates.slice(0, 1);
-    const legacyRegistryCandidate = getLegacyUnifiedMcpRegistryCandidate();
-    const sharedMcpRegistry = await loadUnifiedMcpRegistry({
-        candidates: options.mcpRegistryCandidates ?? defaultRegistryCandidates,
-    });
-    if (!options.mcpRegistryCandidates &&
-        !sharedMcpRegistry.sourcePath &&
-        existsSync(legacyRegistryCandidate) &&
-        !existsSync(defaultRegistryCandidates[0])) {
-        console.log(`  warning: legacy shared MCP registry detected at ${legacyRegistryCandidate} but ignored by default; move it to ${defaultRegistryCandidates[0]} if you still want setup to sync those servers`);
-    }
-    if (verbose && sharedMcpRegistry.sourcePath) {
-        console.log(`  shared MCP registry: ${sharedMcpRegistry.sourcePath} (${sharedMcpRegistry.servers.length} servers)`);
-    }
-    for (const warning of sharedMcpRegistry.warnings) {
-        console.log(`  warning: ${warning}`);
-    }
-    const managedConfig = await updateManagedConfig(scopeDirs.codexConfigFile, pkgRoot, sharedMcpRegistry, summary.config, backupContext, { codexVersionProbe: options.codexVersionProbe, dryRun, verbose, modelUpgradePrompt });
-    const resolvedConfig = managedConfig.finalConfig;
-    if (managedConfig.repairedLegacyTeamRunTable) {
-        console.log("  Removed retired [mcp_servers.omx_team_run] config during refresh.");
+    let resolvedConfig = "";
+    let omxManagesTui = false;
+    if (isPluginInstallMode) {
+        const configCleaned = await cleanupPluginModeLegacyConfig(scopeDirs.codexConfigFile, backupContext, { dryRun, verbose });
+        if (configCleaned)
+            summary.config.removed += 1;
+        console.log(configCleaned
+            ? `  ${dryRun ? "Would clean" : "Cleaned"} legacy OMX config entries for plugin mode.\n`
+            : "  Config refresh skipped; no legacy OMX config entries found.\n");
+        await applyPluginModeHooksConfig(scopeDirs.codexConfigFile, scopeDirs.codexHooksFile, pkgRoot, backupContext, summary.config, { dryRun, verbose });
+        const pluginMarketplaceResult = await ensurePluginMarketplaceRegistration(scopeDirs.codexConfigFile, pkgRoot, backupContext, summary.config, { dryRun, verbose });
+        if (pluginMarketplaceResult === "unavailable") {
+            console.log(`  warning: packaged ${OMX_LOCAL_MARKETPLACE_NAME} Codex plugin marketplace metadata not found; /skills plugin discovery was not registered.`);
+        }
+        else if (pluginMarketplaceResult === "updated") {
+            console.log(`  ${dryRun ? "Would register" : "Registered"} local Codex plugin marketplace ${OMX_LOCAL_MARKETPLACE_NAME} (${pkgRoot}).`);
+        }
+        else {
+            console.log(`  Local Codex plugin marketplace ${OMX_LOCAL_MARKETPLACE_NAME} already registered (${pkgRoot}).`);
+        }
+        resolvedConfig = existsSync(scopeDirs.codexConfigFile)
+            ? await readFile(scopeDirs.codexConfigFile, "utf-8")
+            : "";
+        console.log(`  Native Codex hooks refresh complete (${scopeDirs.codexHooksFile}).\n`);
+        if (usePluginDeveloperInstructionsDefault) {
+            const developerInstructionsResult = await applyPluginDeveloperInstructionsDefault(scopeDirs.codexConfigFile, backupContext, summary.config, {
+                dryRun,
+                verbose,
+                pluginDeveloperInstructionsOverwritePrompt,
+            });
+            if (developerInstructionsResult === "updated") {
+                resolvedConfig = existsSync(scopeDirs.codexConfigFile)
+                    ? await readFile(scopeDirs.codexConfigFile, "utf-8")
+                    : "";
+                console.log(`  ${dryRun ? "Would add" : "Added"} plugin-mode developer_instructions default (${scopeDirs.codexConfigFile}).\n`);
+            }
+            else {
+                console.log(`  Preserved existing developer_instructions in ${scopeDirs.codexConfigFile}.\n`);
+            }
+        }
+        else {
+            console.log("  Plugin-mode developer_instructions default not selected.\n");
+        }
     }
-    if (resolvedScope.scope === "user") {
-        await syncClaudeCodeMcpSettings(sharedMcpRegistry, summary.config, backupContext, { dryRun, verbose });
+    else {
+        const registryCandidates = getUnifiedMcpRegistryCandidates();
+        const defaultRegistryCandidates = registryCandidates.slice(0, 1);
+        const legacyRegistryCandidate = getLegacyUnifiedMcpRegistryCandidate();
+        const sharedMcpRegistry = await loadUnifiedMcpRegistry({
+            candidates: options.mcpRegistryCandidates ?? defaultRegistryCandidates,
+        });
+        if (!options.mcpRegistryCandidates &&
+            !sharedMcpRegistry.sourcePath &&
+            existsSync(legacyRegistryCandidate) &&
+            !existsSync(defaultRegistryCandidates[0])) {
+            console.log(`  warning: legacy shared MCP registry detected at ${legacyRegistryCandidate} but ignored by default; move it to ${defaultRegistryCandidates[0]} if you still want setup to sync those servers`);
+        }
+        if (verbose && sharedMcpRegistry.sourcePath) {
+            console.log(`  shared MCP registry: ${sharedMcpRegistry.sourcePath} (${sharedMcpRegistry.servers.length} servers)`);
+        }
+        for (const warning of sharedMcpRegistry.warnings) {
+            console.log(`  warning: ${warning}`);
+        }
+        const statusLinePreset = await resolveStatusLinePresetForSetup(projectRoot, { force });
+        const managedConfig = await updateManagedConfig(scopeDirs.codexConfigFile, pkgRoot, sharedMcpRegistry, summary.config, backupContext, {
+            dryRun,
+            modelUpgradePrompt,
+            verbose,
+            statusLinePreset,
+            forceStatusLinePreset: force,
+        });
+        resolvedConfig = managedConfig.finalConfig;
+        omxManagesTui = managedConfig.omxManagesTui;
+        if (managedConfig.repairedLegacyTeamRunTable) {
+            console.log("  Removed retired [mcp_servers.omx_team_run] config during refresh.");
+        }
+        if (resolvedScope.scope === "user") {
+            await syncClaudeCodeMcpSettings(sharedMcpRegistry, summary.config, backupContext, { dryRun, verbose });
+        }
+        console.log(`  Config refresh complete (${scopeDirs.codexConfigFile}).\n`);
+        const existingHooksContent = existsSync(scopeDirs.codexHooksFile)
+            ? await readFile(scopeDirs.codexHooksFile, "utf-8")
+            : null;
+        const hooksConfig = mergeManagedCodexHooksConfig(existingHooksContent, pkgRoot);
+        await syncManagedContent(hooksConfig, scopeDirs.codexHooksFile, summary.config, backupContext, { dryRun, verbose }, `native hooks ${scopeDirs.codexHooksFile}`);
+        console.log(`  Native Codex hooks refresh complete (${scopeDirs.codexHooksFile}).\n`);
     }
-    console.log(`  Config refresh complete (${scopeDirs.codexConfigFile}).\n`);
-    const existingHooksContent = existsSync(scopeDirs.codexHooksFile)
-        ? await readFile(scopeDirs.codexHooksFile, "utf-8")
-        : null;
-    const hooksConfig = mergeManagedCodexHooksConfig(existingHooksContent, pkgRoot);
-    await syncManagedContent(hooksConfig, scopeDirs.codexHooksFile, summary.config, backupContext, { dryRun, verbose }, `native hooks ${scopeDirs.codexHooksFile}`);
-    console.log(`  Native Codex hooks refresh complete (${scopeDirs.codexHooksFile}).\n`);
     // Step 5.5: Verify team CLI interop surface is available.
     console.log("[5.5/8] Verifying Team CLI API interop...");
     const teamToolsCheck = await verifyTeamCliApiInterop(pkgRoot);
@@ -603,84 +1228,159 @@ export async function setup(options = {}) {
     console.log();
     // Step 6: Generate AGENTS.md
     console.log("[6/8] Generating AGENTS.md...");
-    const agentsMdSrc = join(pkgRoot, "templates", "AGENTS.md");
-    const agentsMdDst = resolvedScope.scope === "project"
-        ? join(projectRoot, "AGENTS.md")
-        : join(scopeDirs.codexHomeDir, "AGENTS.md");
-    const agentsMdExists = existsSync(agentsMdDst);
-    // Guard: refuse to overwrite project-root AGENTS.md during active session
-    const activeSession = resolvedScope.scope === "project"
-        ? await readSessionState(projectRoot)
-        : null;
-    const sessionIsActive = activeSession && !isSessionStale(activeSession);
-    if (existsSync(agentsMdSrc)) {
-        const content = await readFile(agentsMdSrc, "utf-8");
-        const modelTableContext = resolveAgentsModelTableContext(resolvedConfig, {
-            codexHomeOverride: scopeDirs.codexHomeDir,
-        });
-        const rewritten = upsertAgentsModelTable(addGeneratedAgentsMarker(applyScopePathRewritesToAgentsTemplate(content, resolvedScope.scope)), modelTableContext);
-        let changed = true;
-        let canApplyManagedModelRefresh = false;
-        let managedRefreshContent = "";
-        if (agentsMdExists) {
-            const existing = await readFile(agentsMdDst, "utf-8");
-            changed = existing !== rewritten;
-            if (hasOmxManagedAgentsSections(existing)) {
-                managedRefreshContent = upsertAgentsModelTable(existing, modelTableContext);
-                canApplyManagedModelRefresh = managedRefreshContent !== existing;
+    if (isPluginInstallMode) {
+        const agentsMdRemoved = await cleanupPluginModeLegacyAgentsMd(pluginAgentsMdDst, backupContext, { dryRun, verbose });
+        if (agentsMdRemoved) {
+            summary.agentsMd.removed += 1;
+            console.log(`  ${dryRun ? "Would remove" : "Removed"} legacy OMX-generated AGENTS.md for plugin mode.\n`);
+        }
+        if (usePluginAgentsMdDefault) {
+            const agentsMdSrc = join(pkgRoot, "templates", "AGENTS.md");
+            if (existsSync(agentsMdSrc)) {
+                const content = await readFile(agentsMdSrc, "utf-8");
+                const modelTableContext = resolveAgentsModelTableContext(resolvedConfig, {
+                    codexHomeOverride: scopeDirs.codexHomeDir,
+                });
+                const rewritten = upsertAgentsModelTable(addGeneratedAgentsMarker(applyScopePathRewritesToAgentsTemplate(content, resolvedScope.scope)), modelTableContext);
+                const result = await syncManagedAgentsContent(rewritten, pluginAgentsMdDst, summary.agentsMd, backupContext, {
+                    agentsOverwritePrompt: options.agentsOverwritePrompt,
+                    dryRun,
+                    force,
+                    verbose,
+                });
+                if (result === "updated") {
+                    console.log(resolvedScope.scope === "project"
+                        ? "  Generated plugin-mode AGENTS.md defaults in project root."
+                        : `  Generated plugin-mode AGENTS.md defaults in ${scopeDirs.codexHomeDir}.`);
+                }
+                else if (result === "unchanged") {
+                    console.log(resolvedScope.scope === "project"
+                        ? "  Plugin-mode AGENTS.md defaults already up to date in project root."
+                        : `  Plugin-mode AGENTS.md defaults already up to date in ${scopeDirs.codexHomeDir}.`);
+                }
+                else {
+                    console.log(`  Skipped plugin-mode AGENTS.md defaults for ${pluginAgentsMdDst}.`);
+                }
+            }
+            else {
+                summary.agentsMd.skipped += 1;
+                console.log("  AGENTS.md template not found, skipping.");
             }
         }
-        if (resolvedScope.scope === "project" &&
-            sessionIsActive &&
-            agentsMdExists &&
-            changed) {
+        else {
             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 if (canApplyManagedModelRefresh) {
-            await syncManagedContent(managedRefreshContent, agentsMdDst, summary.agentsMd, backupContext, { dryRun, verbose }, `AGENTS model table ${agentsMdDst}`);
-            console.log(resolvedScope.scope === "project"
-                ? "  Refreshed AGENTS.md model capability table in project root."
-                : `  Refreshed AGENTS.md model capability table in ${scopeDirs.codexHomeDir}.`);
+            console.log(agentsMdRemoved
+                ? "  Plugin-mode AGENTS.md defaults not selected.\n"
+                : "  AGENTS.md generation skipped; no legacy OMX-generated AGENTS.md found and defaults not selected.\n");
         }
-        else {
-            const result = await syncManagedAgentsContent(rewritten, agentsMdDst, summary.agentsMd, backupContext, {
-                agentsOverwritePrompt: options.agentsOverwritePrompt,
-                dryRun,
-                force,
-                verbose,
+    }
+    else {
+        const agentsMdSrc = join(pkgRoot, "templates", "AGENTS.md");
+        const agentsMdDst = resolvedScope.scope === "project"
+            ? join(projectRoot, "AGENTS.md")
+            : join(scopeDirs.codexHomeDir, "AGENTS.md");
+        const agentsMdExists = existsSync(agentsMdDst);
+        // Guard: refuse to overwrite project-root AGENTS.md during active session
+        const activeSession = resolvedScope.scope === "project"
+            ? await readSessionState(projectRoot)
+            : null;
+        const sessionIsActive = activeSession && !isSessionStale(activeSession);
+        if (existsSync(agentsMdSrc)) {
+            const content = await readFile(agentsMdSrc, "utf-8");
+            const modelTableContext = resolveAgentsModelTableContext(resolvedConfig, {
+                codexHomeOverride: scopeDirs.codexHomeDir,
             });
-            if (result === "updated") {
-                console.log(resolvedScope.scope === "project"
-                    ? "  Generated AGENTS.md in project root."
-                    : `  Generated AGENTS.md in ${scopeDirs.codexHomeDir}.`);
+            const rewritten = upsertAgentsModelTable(addGeneratedAgentsMarker(applyScopePathRewritesToAgentsTemplate(content, resolvedScope.scope)), modelTableContext);
+            let changed = true;
+            let canApplyManagedModelRefresh = false;
+            let managedRefreshContent = "";
+            let canApplyManagedAgentsMerge = false;
+            let mergedAgentsContent = "";
+            if (agentsMdExists) {
+                const existing = await readFile(agentsMdDst, "utf-8");
+                changed = existing !== rewritten;
+                if (options.mergeAgents) {
+                    mergedAgentsContent = upsertManagedAgentsBlock(existing, rewritten);
+                    canApplyManagedAgentsMerge = mergedAgentsContent !== existing;
+                }
+                else {
+                    if (hasOmxManagedAgentsSections(existing)) {
+                        managedRefreshContent = upsertAgentsModelTable(existing, modelTableContext);
+                        canApplyManagedModelRefresh = managedRefreshContent !== existing;
+                    }
+                }
+            }
+            if (resolvedScope.scope === "project" &&
+                sessionIsActive &&
+                agentsMdExists &&
+                (changed || canApplyManagedAgentsMerge || canApplyManagedModelRefresh)) {
+                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 if (result === "unchanged") {
+            else if (options.mergeAgents &&
+                agentsMdExists &&
+                !canApplyManagedAgentsMerge) {
+                summary.agentsMd.unchanged += 1;
                 console.log(resolvedScope.scope === "project"
                     ? "  AGENTS.md already up to date in project root."
                     : `  AGENTS.md already up to date in ${scopeDirs.codexHomeDir}.`);
             }
-            else if (agentsMdExists) {
-                console.log(`  Skipped AGENTS.md overwrite for ${agentsMdDst}. Re-run interactively to confirm or use --force.`);
+            else if (canApplyManagedAgentsMerge) {
+                await syncManagedContent(mergedAgentsContent, agentsMdDst, summary.agentsMd, backupContext, { dryRun, verbose }, `merged AGENTS ${agentsMdDst}`);
+                console.log(resolvedScope.scope === "project"
+                    ? "  Merged OMX-managed AGENTS.md sections into project root."
+                    : `  Merged OMX-managed AGENTS.md sections into ${scopeDirs.codexHomeDir}.`);
+            }
+            else if (canApplyManagedModelRefresh) {
+                await syncManagedContent(managedRefreshContent, agentsMdDst, summary.agentsMd, backupContext, { dryRun, verbose }, `AGENTS model table ${agentsMdDst}`);
+                console.log(resolvedScope.scope === "project"
+                    ? "  Refreshed AGENTS.md model capability table in project root."
+                    : `  Refreshed AGENTS.md model capability table in ${scopeDirs.codexHomeDir}.`);
+            }
+            else {
+                const result = await syncManagedAgentsContent(rewritten, agentsMdDst, summary.agentsMd, backupContext, {
+                    agentsOverwritePrompt: options.agentsOverwritePrompt,
+                    dryRun,
+                    force,
+                    verbose,
+                });
+                if (result === "updated") {
+                    console.log(resolvedScope.scope === "project"
+                        ? "  Generated AGENTS.md in project root."
+                        : `  Generated AGENTS.md in ${scopeDirs.codexHomeDir}.`);
+                }
+                else if (result === "unchanged") {
+                    console.log(resolvedScope.scope === "project"
+                        ? "  AGENTS.md already up to date in project root."
+                        : `  AGENTS.md already up to date in ${scopeDirs.codexHomeDir}.`);
+                }
+                else if (agentsMdExists) {
+                    console.log(`  Skipped AGENTS.md overwrite for ${agentsMdDst}. Re-run interactively to confirm or use --force.`);
+                }
+            }
+            if (resolvedScope.scope === "user") {
+                console.log("  User scope leaves project AGENTS.md unchanged.");
             }
         }
-        if (resolvedScope.scope === "user") {
-            console.log("  User scope leaves project AGENTS.md unchanged.");
+        else {
+            summary.agentsMd.skipped += 1;
+            console.log("  AGENTS.md template not found, skipping.");
         }
+        console.log();
     }
-    else {
-        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...");
-    await setupNotifyHook(pkgRoot, { dryRun, verbose });
-    console.log("  Done.\n");
+    if (isPluginInstallMode) {
+        console.log("  Skipped for plugin skill delivery mode.\n");
+    }
+    else {
+        await setupNotifyHook(pkgRoot, { dryRun, verbose });
+        console.log("  Done.\n");
+    }
     // Step 8: Configure HUD
     console.log("[8/8] Configuring HUD...");
     const hudConfigPath = join(projectRoot, ".omx", "hud-config.json");
@@ -696,12 +1396,9 @@ export async function setup(options = {}) {
     else {
         console.log("  HUD config already exists (use --force to overwrite).");
     }
-    if (managedConfig.omxManagesTui) {
+    if (omxManagesTui) {
         console.log("  StatusLine configured in config.toml via [tui] section.");
     }
-    else {
-        console.log("  Codex CLI >= 0.107.0 manages [tui]; OMX left that section untouched.");
-    }
     console.log();
     console.log("Setup refresh summary:");
     logCategorySummary("prompts", summary.prompts);
@@ -722,10 +1419,18 @@ export async function setup(options = {}) {
     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 role/workflow keywords like $architect, $executor, and $plan in Codex");
-    console.log("  3. Browse skills with /skills; AGENTS keyword routing can also activate them implicitly");
-    console.log("  4. The AGENTS.md orchestration brain is loaded automatically");
-    console.log("  5. Native agent defaults configured in config.toml [agents] and TOML files written to .codex/agents/");
+    if (isPluginInstallMode) {
+        console.log(`  2. Registered Codex marketplace ${OMX_LOCAL_MARKETPLACE_NAME} supplies OMX skills and workflow surfaces`);
+        console.log("  3. Browse plugin-provided skills with /skills");
+        console.log("  4. Optional AGENTS.md and developer_instructions defaults are only installed when selected during plugin-mode setup");
+        console.log("  5. Legacy native-agent TOML defaults remain uninstalled in plugin mode");
+    }
+    else {
+        console.log("  2. Use role/workflow keywords like $architect, $executor, and $plan in Codex");
+        console.log("  3. Browse skills with /skills; AGENTS keyword routing can also activate them implicitly");
+        console.log("  4. The AGENTS.md orchestration brain is loaded automatically");
+        console.log("  5. Native agent defaults configured in config.toml [agents] and TOML files written to .codex/agents/");
+    }
     console.log('  6. "omx explore" and "omx sparkshell" can hydrate native release binaries on first use; source installs still allow repo-local fallbacks and OMX_EXPLORE_BIN / OMX_SPARKSHELL_BIN overrides');
     if (isGitHubCliConfigured()) {
         console.log("\nSupport the project: gh repo star Yeachan-Heo/oh-my-codex");
@@ -766,7 +1471,8 @@ 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",
         windowsHide: true,
     });
     return result.status === 0;
@@ -872,21 +1578,18 @@ async function installPrompts(srcDir, dstDir, backupContext, options) {
         return summary;
     const manifest = tryReadCatalogManifest();
     const agentStatusByName = manifest
-        ? new Map(manifest.agents.map((agent) => [agent.name, agent.status]))
+        ? getCatalogAgentStatusByName(manifest)
         : null;
-    const isInstallableStatus = (status) => status === "active" || status === "internal";
     const files = await readdir(srcDir);
-    const staleCandidatePromptNames = new Set(manifest?.agents.map((agent) => agent.name) ?? []);
     for (const file of files) {
         if (!file.endsWith(".md"))
             continue;
         const promptName = file.slice(0, -3);
-        staleCandidatePromptNames.add(promptName);
         const status = agentStatusByName?.get(promptName);
-        if (agentStatusByName && !isInstallableStatus(status)) {
+        if (manifest && !isSetupPromptAssetName(promptName, manifest)) {
             summary.skipped += 1;
             if (options.verbose) {
-                const label = status ?? "unlisted";
+                const label = status ?? "unclassified";
                 console.log(`  skipped ${file} (status: ${label})`);
             }
             continue;
@@ -905,13 +1608,14 @@ async function installPrompts(srcDir, dstDir, backupContext, options) {
                 continue;
             const promptName = file.slice(0, -3);
             const status = agentStatusByName?.get(promptName);
-            if (isInstallableStatus(status))
-                continue;
-            if (!staleCandidatePromptNames.has(promptName) && status === undefined)
+            if (isSetupPromptAssetName(promptName, manifest))
                 continue;
             const stalePromptPath = join(dstDir, file);
             if (!existsSync(stalePromptPath))
                 continue;
+            if (await ensureBackup(stalePromptPath, true, backupContext, options)) {
+                summary.backedUp += 1;
+            }
             if (!options.dryRun) {
                 await rm(stalePromptPath, { force: true });
             }
@@ -927,6 +1631,55 @@ async function installPrompts(srcDir, dstDir, backupContext, options) {
     }
     return summary;
 }
+function isGeneratedOmxNativeAgentToml(content, agentName) {
+    const firstLine = content.split(/\r?\n/, 1)[0]?.trim();
+    return firstLine === `# oh-my-codex agent: ${agentName}`;
+}
+async function cleanupGeneratedNonInstallableNativeAgents(agentsDir, manifest, backupContext, options) {
+    const summary = createEmptyCategorySummary();
+    if (!existsSync(agentsDir))
+        return summary;
+    const agentStatusByName = getCatalogAgentStatusByName(manifest);
+    const installedFiles = await readdir(agentsDir);
+    for (const file of installedFiles) {
+        if (!file.endsWith(".toml"))
+            continue;
+        const agentName = file.slice(0, -5);
+        const agentStatus = agentStatusByName.get(agentName);
+        if (agentStatus === undefined ||
+            isNativeAgentInstallableStatus(agentStatus)) {
+            continue;
+        }
+        const staleAgentPath = join(agentsDir, file);
+        let content = "";
+        try {
+            content = await readFile(staleAgentPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        if (!isGeneratedOmxNativeAgentToml(content, agentName)) {
+            if (options.verbose) {
+                console.log(`  skipped stale native agent ${file}: not an OMX-generated native agent`);
+            }
+            continue;
+        }
+        if (await ensureBackup(staleAgentPath, true, backupContext, options)) {
+            summary.backedUp += 1;
+        }
+        if (!options.dryRun) {
+            await rm(staleAgentPath, { force: true });
+        }
+        summary.removed += 1;
+        if (options.verbose) {
+            const prefix = options.dryRun
+                ? "would remove stale generated native agent"
+                : "removed stale generated native agent";
+            console.log(`  ${prefix} ${file} (status: ${agentStatus})`);
+        }
+    }
+    return summary;
+}
 async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, options) {
     const summary = createEmptyCategorySummary();
     if (!options.dryRun) {
@@ -934,17 +1687,18 @@ async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, opti
     }
     const manifest = tryReadCatalogManifest();
     const agentStatusByName = manifest
-        ? new Map(manifest.agents.map((agent) => [agent.name, agent.status]))
+        ? getCatalogAgentStatusByName(manifest)
         : null;
-    const isInstallableStatus = (status) => status === "active" || status === "internal";
     const staleCandidateNativeAgentNames = new Set(manifest?.agents.map((agent) => agent.name) ?? []);
-    for (const [name, agent] of Object.entries(AGENT_DEFINITIONS)) {
+    const nativeAgentNames = manifest
+        ? [...getInstallableNativeAgentNames(manifest)].sort()
+        : Object.keys(AGENT_DEFINITIONS).sort();
+    for (const name of nativeAgentNames) {
         staleCandidateNativeAgentNames.add(name);
-        const status = agentStatusByName?.get(name);
-        if (agentStatusByName && !isInstallableStatus(status)) {
+        const agent = AGENT_DEFINITIONS[name];
+        if (!agent) {
             if (options.verbose) {
-                const label = status ?? "unlisted";
-                console.log(`  skipped native agent ${name}.toml (status: ${label})`);
+                console.log(`  skipped native agent ${name}.toml (missing definition)`);
             }
             summary.skipped += 1;
             continue;
@@ -961,6 +1715,11 @@ async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, opti
         await syncManagedContent(toml, dst, summary, backupContext, options, `native agent ${name}.toml`);
     }
     summary.removed += await cleanupObsoleteNativeAgents(agentsDir, backupContext, options);
+    if (manifest) {
+        const generatedCleanup = await cleanupGeneratedNonInstallableNativeAgents(agentsDir, manifest, backupContext, options);
+        summary.backedUp += generatedCleanup.backedUp;
+        summary.removed += generatedCleanup.removed;
+    }
     if (options.force && manifest && existsSync(agentsDir)) {
         const installedFiles = await readdir(agentsDir);
         for (const file of installedFiles) {
@@ -968,7 +1727,7 @@ async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, opti
                 continue;
             const agentName = file.slice(0, -5);
             const agentStatus = agentStatusByName?.get(agentName);
-            if (isInstallableStatus(agentStatus))
+            if (isNativeAgentInstallableStatus(agentStatus))
                 continue;
             if (!staleCandidateNativeAgentNames.has(agentName) &&
                 agentStatus === undefined)
@@ -976,6 +1735,9 @@ async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, opti
             const staleAgentPath = join(agentsDir, file);
             if (!existsSync(staleAgentPath))
                 continue;
+            if (await ensureBackup(staleAgentPath, true, backupContext, options)) {
+                summary.backedUp += 1;
+            }
             if (!options.dryRun) {
                 await rm(staleAgentPath, { force: true });
             }
@@ -1029,13 +1791,13 @@ export async function installSkills(srcDir, dstDir, backupContext, options) {
     const summary = createEmptyCategorySummary();
     if (!existsSync(srcDir))
         return summary;
+    const installableSkillNames = getSetupInstallableSkillNames();
     const installableSkills = [];
     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 isSetupInstallableSkill = (skillName, status) => isInstallableStatus(status) || SETUP_ONLY_INSTALLABLE_SKILLS.has(skillName);
+    const isSetupInstallableSkill = (skillName, status) => isCatalogInstallableStatus(status) || installableSkillNames.has(skillName);
     const entries = await readdir(srcDir, { withFileTypes: true });
     const staleCandidateSkillNames = new Set(manifest?.skills.map((skill) => skill.name) ?? []);
     for (const entry of entries) {
@@ -1086,11 +1848,14 @@ export async function installSkills(srcDir, dstDir, backupContext, options) {
             await syncManagedFileFromDisk(sfPath, dstPath, summary, backupContext, options, `skill ${skillName}/${sf}`);
         }
     }
-    if (options.force && manifest && existsSync(dstDir)) {
+    if (manifest && existsSync(dstDir)) {
         for (const staleSkill of staleCandidateSkillNames) {
             const status = skillStatusByName?.get(staleSkill);
             if (isSetupInstallableSkill(staleSkill, status))
                 continue;
+            const hardDeprecated = HARD_DEPRECATED_SKILL_NAMES.has(staleSkill);
+            if (!options.force && !hardDeprecated)
+                continue;
             const staleSkillDir = join(dstDir, staleSkill);
             if (!existsSync(staleSkillDir))
                 continue;
@@ -1103,12 +1868,72 @@ export async function installSkills(srcDir, dstDir, backupContext, options) {
                     ? "would remove stale skill"
                     : "removed stale skill";
                 const label = status ?? "unlisted";
-                console.log(`  ${prefix} ${staleSkill}/ (status: ${label})`);
+                const reason = hardDeprecated ? ", hard-deprecated" : "";
+                console.log(`  ${prefix} ${staleSkill}/ (status: ${label}${reason})`);
             }
         }
     }
     return summary;
 }
+async function removeDirectoryCopyAware(sourceDir, backupContext, options) {
+    const destinationExists = existsSync(sourceDir);
+    if (!destinationExists)
+        return false;
+    const relativePath = relative(backupContext.baseRoot, sourceDir);
+    const safeRelativePath = relativePath.startsWith("..") || relativePath === ""
+        ? sourceDir.replace(/^[/]+/, "")
+        : relativePath;
+    const backupPath = join(backupContext.backupRoot, safeRelativePath);
+    if (!options.dryRun) {
+        await mkdir(dirname(backupPath), { recursive: true });
+        await cp(sourceDir, backupPath, { recursive: true });
+    }
+    if (options.verbose) {
+        console.log(`  backup ${sourceDir} -> ${backupPath}`);
+    }
+    if (!options.dryRun) {
+        await rm(sourceDir, { recursive: true, force: true });
+    }
+    return true;
+}
+async function cleanupLegacyManagedSkills(srcDir, dstDir, backupContext, options) {
+    const result = {
+        backedUp: 0,
+        removedSkillNames: [],
+        skippedSkillNames: [],
+        warnings: [],
+    };
+    if (!existsSync(dstDir) || !existsSync(srcDir)) {
+        return result;
+    }
+    const manifest = tryReadCatalogManifest();
+    const installableSkillNames = getSetupInstallableSkillNames(manifest);
+    for (const skillName of installableSkillNames) {
+        const shippedSkillDir = join(srcDir, skillName);
+        const installedSkillDir = join(dstDir, skillName);
+        const shippedSkillMd = join(shippedSkillDir, "SKILL.md");
+        const installedSkillMd = join(installedSkillDir, "SKILL.md");
+        if (!existsSync(shippedSkillMd) || !existsSync(installedSkillMd))
+            continue;
+        const [shippedSkillContent, installedSkillContent] = await Promise.all([
+            readFile(shippedSkillMd, "utf-8"),
+            readFile(installedSkillMd, "utf-8"),
+        ]);
+        const expectedInstalledContent = rewriteInstalledSkillDescriptionBadge(shippedSkillContent, shippedSkillMd);
+        if (installedSkillContent !== expectedInstalledContent) {
+            const warning = `Skipping legacy skill cleanup for ${skillName}: installed SKILL.md differs from OMX-managed content.`;
+            result.skippedSkillNames.push(skillName);
+            result.warnings.push(warning);
+            continue;
+        }
+        const removed = await removeDirectoryCopyAware(installedSkillDir, backupContext, options);
+        if (removed) {
+            result.backedUp += 1;
+            result.removedSkillNames.push(skillName);
+        }
+    }
+    return result;
+}
 async function updateManagedConfig(configPath, pkgRoot, sharedMcpRegistry, summary, backupContext, options) {
     const existing = existsSync(configPath)
         ? await readFile(configPath, "utf-8")
@@ -1116,8 +1941,7 @@ async function updateManagedConfig(configPath, pkgRoot, sharedMcpRegistry, summa
     const hadLegacyTeamRunTable = hasLegacyOmxTeamRunTable(existing);
     const currentModel = getRootModelName(existing);
     let modelOverride;
-    const codexVersion = options.codexVersionProbe?.() ?? probeInstalledCodexVersion();
-    const omxManagesTui = shouldOmxManageTuiFromCodexVersion(codexVersion);
+    const omxManagesTui = true;
     if (currentModel === LEGACY_SETUP_MODEL) {
         const shouldPrompt = typeof options.modelUpgradePrompt === "function" ||
             (process.stdin.isTTY && process.stdout.isTTY);
@@ -1136,6 +1960,8 @@ async function updateManagedConfig(configPath, pkgRoot, sharedMcpRegistry, summa
         sharedMcpServers: sharedMcpRegistry.servers,
         sharedMcpRegistrySource: sharedMcpRegistry.sourcePath,
         verbose: options.verbose,
+        statusLinePreset: options.statusLinePreset,
+        forceStatusLinePreset: options.forceStatusLinePreset,
     });
     const changed = existing !== finalConfig;
     if (!changed) {