teamix-evo 0.8.0 → 0.9.0

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command37 } from "commander";
+import { Command as Command39 } from "commander";
 import { createRequire as createRequire8 } from "module";
 
 // src/commands/tokens/index.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 
 // src/commands/tokens/init.ts
 import { Command } from "commander";
@@ -181,7 +181,8 @@ var TEAMIX_DIR = ".teamix-evo";
 var CONFIG_FILE = "config.json";
 var MANIFEST_FILE = "manifest.json";
 var TOKENS_LOCK_FILE = "tokens-lock.json";
-var SKILLS_DIR = "skills";
+var SKILLS_DIR = "skills-source";
+var LEGACY_SKILLS_DIR = "skills";
 var SKILLS_LOCK_FILE = "manifest.lock.json";
 function getTeamixDir(projectRoot) {
   return path4.join(projectRoot, TEAMIX_DIR);
@@ -265,6 +266,9 @@ function getSkillsSourceDir(projectRoot, skillName) {
   const base = path4.join(projectRoot, TEAMIX_DIR, SKILLS_DIR);
   return skillName ? path4.join(base, skillName) : base;
 }
+function getLegacySkillsSourceDir(projectRoot) {
+  return path4.join(projectRoot, TEAMIX_DIR, LEGACY_SKILLS_DIR);
+}
 async function readSkillsLock(projectRoot) {
   const lockPath = path4.join(
     projectRoot,
@@ -397,6 +401,7 @@ function resolveTokensPackageRoot(packageName) {
 
 // src/core/skills-installer.ts
 async function installSkills(options) {
+  await migrateLegacySkillsSourceDir(options.projectRoot);
   const { manifest, ides, scope, onlyIds } = options;
   const installed = [];
   const targets = manifest.skills.filter(
@@ -689,6 +694,7 @@ function escapeRegExp(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 async function syncSkillsToIdes(options) {
+  await migrateLegacySkillsSourceDir(options.projectRoot);
   const { projectRoot, skills, ides, scope, onlyIds } = options;
   const out = [];
   const targets = skills.filter((s) => !onlyIds || onlyIds.includes(s.id));
@@ -732,6 +738,118 @@ async function syncSkillsToIdes(options) {
   }
   return { resources: out, count: out.length };
 }
+async function migrateLegacySkillsSourceDir(projectRoot) {
+  const legacyDir = getLegacySkillsSourceDir(projectRoot);
+  const newDir = getSkillsSourceDir(projectRoot);
+  let legacyExists = false;
+  let newExists = false;
+  try {
+    legacyExists = (await fs5.stat(legacyDir)).isDirectory();
+  } catch {
+    legacyExists = false;
+  }
+  try {
+    newExists = (await fs5.stat(newDir)).isDirectory();
+  } catch {
+    newExists = false;
+  }
+  if (!legacyExists) return;
+  if (newExists) {
+    logger.warn(
+      `Detected stale legacy skills source dir at ${legacyDir} alongside ${newDir}; the new layout takes precedence \u2014 you can safely delete the legacy dir.`
+    );
+    return;
+  }
+  try {
+    await fs5.rename(legacyDir, newDir);
+    logger.info(
+      `Migrated skills source dir: \`.teamix-evo/${LEGACY_SKILLS_DIR}/\` \u2192 \`.teamix-evo/skills-source/\``
+    );
+  } catch (err) {
+    logger.warn(
+      `Failed to rename legacy skills source dir (${getErrorMessage(
+        err
+      )}); leaving as-is. New skills will install under the new layout.`
+    );
+    return;
+  }
+  try {
+    const manifest = await readInstalledManifest(projectRoot);
+    if (!manifest) return;
+    const legacyFragmentPosix = `/.teamix-evo/${LEGACY_SKILLS_DIR}/`;
+    const newFragmentPosix = `/.teamix-evo/skills-source/`;
+    const legacyFragmentNative = `${path7.sep}.teamix-evo${path7.sep}${LEGACY_SKILLS_DIR}${path7.sep}`;
+    const newFragmentNative = `${path7.sep}.teamix-evo${path7.sep}skills-source${path7.sep}`;
+    let touched = 0;
+    for (const pkg of manifest.installed) {
+      for (const r of pkg.resources) {
+        if (typeof r.target !== "string") continue;
+        const before = r.target;
+        let after = before.replace(legacyFragmentPosix, newFragmentPosix);
+        after = after.replace(legacyFragmentNative, newFragmentNative);
+        if (after !== before) {
+          r.target = after;
+          touched += 1;
+        }
+      }
+    }
+    if (touched > 0) {
+      await writeInstalledManifest(projectRoot, manifest);
+      logger.debug(
+        `Rewrote ${touched} manifest target(s) to the new skills-source path.`
+      );
+    }
+  } catch (err) {
+    logger.warn(
+      `Migrated skills source dir but failed to update manifest paths (${getErrorMessage(
+        err
+      )}); manifest may still reference legacy paths.`
+    );
+  }
+}
+async function pruneEmptyIdeSkillDirs(args) {
+  const removed = [];
+  for (const ide of args.ides) {
+    const adapter = getAdapter(ide);
+    const placeholderDir = adapter.getSkillTargetDir(
+      "__placeholder__",
+      args.scope,
+      args.projectRoot
+    );
+    const skillsRoot = path7.dirname(placeholderDir);
+    let entries;
+    try {
+      entries = await fs5.readdir(skillsRoot);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const dir = path7.join(skillsRoot, name);
+      let stat7;
+      try {
+        stat7 = await fs5.stat(dir);
+      } catch {
+        continue;
+      }
+      if (!stat7.isDirectory()) continue;
+      let children;
+      try {
+        children = await fs5.readdir(dir);
+      } catch {
+        continue;
+      }
+      if (children.some((c) => c === "SKILL.md")) continue;
+      if (children.length !== 0) continue;
+      try {
+        await fs5.rmdir(dir);
+        removed.push(dir);
+        logger.debug(`Pruned empty IDE skill dir: ${dir}`);
+      } catch {
+      }
+    }
+  }
+  return removed;
+}
 async function removeSkillFiles(records) {
   const removed = [];
   for (const r of records) {
@@ -827,13 +945,29 @@ async function runSkillsInit(options) {
     }
     return true;
   }).map((s) => s.id);
-  const skippedSkillIds = candidateIds.filter(
-    (id) => existing.skillIds.has(id)
+  const { onlyIds, skippedSkillIds, outdatedSkills } = partitionByVersion(
+    candidateIds,
+    manifest,
+    existing
   );
-  const onlyIds = candidateIds.filter((id) => !existing.skillIds.has(id));
-  if (existingSkillsCfg && onlyIds.length === 0) {
+  if (existingSkillsCfg && onlyIds.length === 0 && outdatedSkills.length === 0) {
     return { status: "already-initialized" };
   }
+  if (onlyIds.length === 0) {
+    return {
+      status: "installed",
+      packageName,
+      version: existingSkillsCfg?.version ?? manifest.version,
+      ides,
+      scope,
+      skillCount: 0,
+      fileCount: 0,
+      resources: [],
+      addedSkillIds: [],
+      skippedSkillIds,
+      outdatedSkills
+    };
+  }
   return finalizeSkillsInstall({
     projectRoot,
     packageName,
@@ -845,6 +979,7 @@ async function runSkillsInit(options) {
     scope,
     onlyIds,
     skippedSkillIds,
+    outdatedSkills,
     existing,
     existingConfig
   });
@@ -885,10 +1020,11 @@ async function runSkillsAdd(options) {
     }
   }
   const existing = await readExistingState(projectRoot, packageName);
-  const skippedSkillIds = requestedNames.filter(
-    (n) => existing.skillIds.has(n)
+  const { onlyIds, skippedSkillIds, outdatedSkills } = partitionByVersion(
+    requestedNames,
+    manifest,
+    existing
   );
-  const onlyIds = requestedNames.filter((n) => !existing.skillIds.has(n));
   if (onlyIds.length === 0) {
     return {
       status: "installed",
@@ -900,7 +1036,8 @@ async function runSkillsAdd(options) {
       fileCount: 0,
       resources: [],
       addedSkillIds: [],
-      skippedSkillIds
+      skippedSkillIds,
+      outdatedSkills
     };
   }
   return finalizeSkillsInstall({
@@ -914,10 +1051,52 @@ async function runSkillsAdd(options) {
     scope,
     onlyIds,
     skippedSkillIds,
+    outdatedSkills,
     existing,
     existingConfig
   });
 }
+function partitionByVersion(ids, manifest, existing) {
+  const manifestById = new Map(manifest.skills.map((s) => [s.id, s]));
+  const onlyIds = [];
+  const skippedSkillIds = [];
+  const outdatedSkills = [];
+  for (const name of ids) {
+    if (!existing.skillIds.has(name)) {
+      onlyIds.push(name);
+      continue;
+    }
+    const installedVer = existing.lock?.skills?.[name]?.version;
+    const latestVer = manifestById.get(name)?.version;
+    if (installedVer && latestVer && compareSemver(installedVer, latestVer) < 0) {
+      outdatedSkills.push({
+        id: name,
+        installed: installedVer,
+        latest: latestVer
+      });
+    } else {
+      skippedSkillIds.push(name);
+    }
+  }
+  return { onlyIds, skippedSkillIds, outdatedSkills };
+}
+function parseSemverTriple(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function compareSemver(a, b) {
+  const pa = parseSemverTriple(a);
+  const pb = parseSemverTriple(b);
+  if (!pa || !pb) {
+    if (a === b) return 0;
+    return a < b ? -1 : 1;
+  }
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+}
 async function readExistingState(projectRoot, packageName) {
   const installed = await readInstalledManifest(projectRoot);
   const pkg = installed?.installed.find((p2) => p2.package === packageName);
@@ -942,6 +1121,7 @@ async function finalizeSkillsInstall(args) {
     scope,
     onlyIds,
     skippedSkillIds,
+    outdatedSkills,
     existing,
     existingConfig
   } = args;
@@ -1007,6 +1187,10 @@ async function finalizeSkillsInstall(args) {
   }
   await writeSkillsLock(projectRoot, lock);
   await ensureMcpJson(projectRoot);
+  try {
+    await pruneEmptyIdeSkillDirs({ projectRoot, ides, scope });
+  } catch {
+  }
   return {
     status: "installed",
     packageName,
@@ -1017,7 +1201,8 @@ async function finalizeSkillsInstall(args) {
     fileCount: result.count,
     resources: result.resources,
     addedSkillIds: onlyIds,
-    skippedSkillIds
+    skippedSkillIds,
+    outdatedSkills: outdatedSkills ?? []
   };
 }
 function mergeInstalledResources(existing, next) {
@@ -1225,6 +1410,9 @@ async function installVariantFile(fileRelToPackage, packageRoot, projectRoot) {
     const targetRel = path9.posix.join(CONSUMER_TOKENS_DIR, CONSUMER_THEME_FILE);
     const targetAbs = path9.join(projectRoot, targetRel);
     const content = await fs6.readFile(sourceAbs, "utf-8");
+    if (await fileExists(targetAbs)) {
+      await backupFile(targetAbs, projectRoot);
+    }
     await writeFileSafe(targetAbs, content);
     return {
       id: `tokens:${CONSUMER_THEME_FILE}`,
@@ -1434,10 +1622,10 @@ async function writeTokensUpgradeHint(options) {
 }
 function selectApplicableRenames(renames, fromVersion, toVersion) {
   return renames.filter(
-    (r) => compareSemver(r.sinceVersion, fromVersion) > 0 && compareSemver(r.sinceVersion, toVersion) <= 0
-  ).sort((a, b) => compareSemver(a.sinceVersion, b.sinceVersion));
+    (r) => compareSemver2(r.sinceVersion, fromVersion) > 0 && compareSemver2(r.sinceVersion, toVersion) <= 0
+  ).sort((a, b) => compareSemver2(a.sinceVersion, b.sinceVersion));
 }
-function compareSemver(a, b) {
+function compareSemver2(a, b) {
   const [aMain = "", aRest = ""] = a.split("-", 2);
   const [bMain = "", bRest = ""] = b.split("-", 2);
   const aParts = aMain.split(".").map((n) => Number.parseInt(n, 10));
@@ -1876,19 +2064,243 @@ var uninstallCommand = new Command5("uninstall").description(
   }
 });
 
+// src/commands/tokens/audit.ts
+import { Command as Command6 } from "commander";
+
+// src/core/tokens-audit.ts
+import * as fs10 from "fs/promises";
+import * as path14 from "path";
+var THEME_REL = "tokens/tokens.theme.css";
+var OVERRIDES_REL = "tokens/tokens.overrides.css";
+async function runTokensAudit(options) {
+  const themePath = path14.join(options.projectRoot, THEME_REL);
+  const overridesPath = path14.join(options.projectRoot, OVERRIDES_REL);
+  const themeSrc = await safeRead(themePath);
+  if (themeSrc === null) {
+    return { status: "no-theme", themePath, overridesPath };
+  }
+  const overridesSrc = await safeRead(overridesPath);
+  if (overridesSrc === null) {
+    return { status: "no-overrides", themePath, overridesPath };
+  }
+  const themeTokens = parseCssVariables(themeSrc);
+  const overrideTokens = parseCssVariables(overridesSrc);
+  const themeIndex = /* @__PURE__ */ new Map();
+  for (const tok of themeTokens) themeIndex.set(tok.name, tok);
+  const entries = [];
+  for (const tok of overrideTokens) {
+    entries.push(classifyOverride(tok, themeIndex));
+  }
+  const summary = {
+    redundant: 0,
+    kept: 0,
+    migrate: 0,
+    custom: 0
+  };
+  for (const entry of entries) summary[entry.category] += 1;
+  return {
+    status: "audited",
+    themePath,
+    overridesPath,
+    totalOverrides: entries.length,
+    entries,
+    summary
+  };
+}
+async function safeRead(filePath) {
+  try {
+    return await fs10.readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function parseCssVariables(source) {
+  const stripped = source.replace(
+    /\/\*[\s\S]*?\*\//g,
+    (m) => m.replace(/[^\n]/g, " ")
+  );
+  const out = [];
+  const lines = stripped.split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    const lineRaw = lines[i] ?? "";
+    const match = /^\s*(--[A-Za-z0-9_-]+)\s*:\s*([^;]+?)\s*;/.exec(lineRaw);
+    if (!match) continue;
+    const name = match[1];
+    const value = match[2];
+    if (!name || !value) continue;
+    out.push({ name, value: value.trim(), line: i + 1 });
+  }
+  return out;
+}
+function classifyOverride(override, themeIndex) {
+  const direct = themeIndex.get(override.name);
+  if (direct) {
+    const equal = areValuesSemanticallyEqual(override.value, direct.value);
+    return {
+      name: override.name,
+      value: override.value,
+      line: override.line,
+      category: equal ? "redundant" : "kept",
+      themeName: direct.name,
+      themeValue: direct.value,
+      reason: equal ? `theme already declares ${direct.name} with an equivalent value \u2014 safe to delete` : `genuinely differs from theme value \u2014 kept as user override`
+    };
+  }
+  if (!override.name.startsWith("--color-")) {
+    const v4Name = `--color-${override.name.slice(2)}`;
+    const v4Match = themeIndex.get(v4Name);
+    if (v4Match) {
+      const wrapped = wrapAsHslIfBare(override.value);
+      const equal = areValuesSemanticallyEqual(wrapped, v4Match.value);
+      return {
+        name: override.name,
+        value: override.value,
+        line: override.line,
+        category: "migrate",
+        themeName: v4Match.name,
+        themeValue: v4Match.value,
+        compareCategory: equal ? "redundant" : "kept",
+        reason: equal ? `legacy v3 shape; theme has ${v4Match.name} with equivalent value \u2014 rewrite as v4 (or delete)` : `legacy v3 shape; rewrite as v4 \`${v4Name}: hsl(...)\` and keep override`
+      };
+    }
+  }
+  return {
+    name: override.name,
+    value: override.value,
+    line: override.line,
+    category: "custom",
+    reason: `no matching theme variable \u2014 project-specific extension`
+  };
+}
+function areValuesSemanticallyEqual(a, b) {
+  return normaliseCssValue(a) === normaliseCssValue(b);
+}
+function normaliseCssValue(value) {
+  let v = value.trim().toLowerCase();
+  v = v.replace(/\s+/g, " ");
+  v = v.replace(/\s*([(),/])\s*/g, "$1");
+  v = v.replace(/(\d+\.\d*?)0+(?=[^0-9]|$)/g, "$1").replace(/\.(?=[^0-9]|$)/g, "");
+  return v;
+}
+function wrapAsHslIfBare(value) {
+  const trimmed = value.trim();
+  if (/^[a-z-]+\s*\(/i.test(trimmed)) return trimmed;
+  const triplet = /^-?\d+(?:\.\d+)?\s+\d+(?:\.\d+)?%\s+\d+(?:\.\d+)?%(?:\s*\/\s*\S+)?$/;
+  if (triplet.test(trimmed)) {
+    return `hsl(${trimmed})`;
+  }
+  return trimmed;
+}
+function formatAuditEntry(entry) {
+  const head = `  ${entry.name}: ${entry.value};`;
+  switch (entry.category) {
+    case "redundant":
+      return `${head}
+    \u2192 REDUNDANT \u2014 ${entry.reason}`;
+    case "kept":
+      return `${head}
+    \u2192 KEEP \u2014 ${entry.reason}`;
+    case "migrate": {
+      const sub = entry.compareCategory ? ` (currently ${entry.compareCategory})` : "";
+      return `${head}
+    \u2192 MIGRATE${sub} \u2014 ${entry.reason}`;
+    }
+    case "custom":
+      return `${head}
+    \u2192 CUSTOM \u2014 ${entry.reason}`;
+  }
+}
+function renderAuditSummary(result) {
+  const lines = [];
+  lines.push(`tokens audit \xB7 ${result.totalOverrides} override(s) inspected`);
+  lines.push(
+    `  redundant=${result.summary.redundant}  kept=${result.summary.kept}  migrate=${result.summary.migrate}  custom=${result.summary.custom}`
+  );
+  for (const cat of ["redundant", "migrate", "custom", "kept"]) {
+    const subset = result.entries.filter((e) => e.category === cat);
+    if (subset.length === 0) continue;
+    lines.push("");
+    lines.push(`[${cat.toUpperCase()}] (${subset.length})`);
+    for (const entry of subset) lines.push(formatAuditEntry(entry));
+  }
+  return lines.join("\n");
+}
+
+// src/commands/tokens/audit.ts
+var auditCommand = new Command6("audit").description(
+  "\u5BA1\u8BA1 tokens/tokens.overrides.css\uFF1A\u4E0E\u53D8\u4F53 theme.css \u5BF9\u7167\uFF0C\u5206\u7C7B\u8F93\u51FA\u5197\u4F59/\u4FDD\u7559/\u8FC1\u79FB/\u9879\u76EE\u7279\u6709"
+).option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA\u7ED3\u679C\uFF08\u4FBF\u4E8E skill \u6D88\u8D39\uFF09").option(
+  "--filter <category>",
+  "\u4EC5\u663E\u793A\u6307\u5B9A bucket\uFF08redundant|kept|migrate|custom\uFF09\uFF0C\u53EF\u9017\u53F7\u5206\u9694"
+).action(async (opts) => {
+  try {
+    const ide = detectIde();
+    const projectRoot = ide.getProjectRoot();
+    const result = await runTokensAudit({ projectRoot });
+    if (result.status === "no-theme") {
+      logger.error(
+        `No tokens.theme.css found at ${result.themePath}. Run \`tokens init <variant>\` first.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    if (result.status === "no-overrides") {
+      logger.info(
+        `No tokens.overrides.css at ${result.overridesPath}. Nothing to audit.`
+      );
+      return;
+    }
+    if (result.status !== "audited") {
+      return;
+    }
+    const filterSet = parseFilter(opts.filter);
+    const filtered = filterSet ? {
+      ...result,
+      entries: result.entries.filter((e) => filterSet.has(e.category))
+    } : result;
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(filtered, null, 2) + "\n");
+      return;
+    }
+    logger.info(renderAuditSummary(filtered));
+    logger.info("");
+    logger.info(
+      "\u63D0\u793A\uFF1A\u6B64\u547D\u4EE4\u53EA\u8BFB\uFF0C\u4E0D\u4F1A\u4FEE\u6539 overrides.css\uFF1B\u6309\u4E0A\u9762\u7684 REDUNDANT / MIGRATE \u5206\u7C7B\u81EA\u884C\u88C1\u526A\u3002"
+    );
+  } catch (err) {
+    logger.error(`Failed to audit tokens: ${getErrorMessage(err)}`);
+    process.exitCode = 1;
+  }
+});
+function parseFilter(raw) {
+  if (!raw) return null;
+  const valid = ["redundant", "kept", "migrate", "custom"];
+  const out = /* @__PURE__ */ new Set();
+  for (const part of raw.split(",").map((s) => s.trim().toLowerCase())) {
+    if (!part) continue;
+    if (valid.includes(part)) {
+      out.add(part);
+    }
+  }
+  return out.size > 0 ? out : null;
+}
+
 // src/commands/tokens/index.ts
-var tokensCommand = new Command6("tokens").description("\u7BA1\u7406 design tokens(\u53D8\u4F53\u7EA7 theme.css \u7B49)");
+var tokensCommand = new Command7("tokens").description(
+  "\u7BA1\u7406 design tokens(\u53D8\u4F53\u7EA7 theme.css \u7B49)"
+);
 tokensCommand.addCommand(initCommand);
 tokensCommand.addCommand(updateCommand);
 tokensCommand.addCommand(listCommand);
 tokensCommand.addCommand(listVariantsCommand);
 tokensCommand.addCommand(uninstallCommand);
+tokensCommand.addCommand(auditCommand);
 
 // src/commands/skills/index.ts
-import { Command as Command14 } from "commander";
+import { Command as Command15 } from "commander";
 
 // src/commands/skills/init.ts
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 import * as prompts2 from "@clack/prompts";
 
 // src/utils/cancelled.ts
@@ -1921,7 +2333,7 @@ function parseScope(input) {
 }
 
 // src/commands/skills/init.ts
-var initCommand2 = new Command7("init").description(
+var initCommand2 = new Command8("init").description(
   "\u81EA\u4E3E teamix-evo skills\uFF08\u6309 tokens variant + scope \u5168\u88C5\u7B26\u5408\u6761\u4EF6\u7684 skill\uFF1Bscope \u4E3A global-only \u7684 entry skill \u81EA\u52A8\u8DF3\u8FC7 \u2014 ADR 0033\uFF09"
 ).option("--ide <list>", '\u9017\u53F7\u5206\u9694\u7684 IDE \u5217\u8868\uFF0C\u5982 "qoder,claude"').option("--scope <scope>", "project | global\uFF08\u9ED8\u8BA4 project\uFF09").option("-y, --yes", "\u4F7F\u7528\u9ED8\u8BA4\u503C\uFF0C\u8DF3\u8FC7\u4EA4\u4E92").action(async (opts) => {
   try {
@@ -1969,6 +2381,13 @@ var initCommand2 = new Command7("init").description(
       );
     }
     logger.info(`  Files:   ${result.fileCount}`);
+    if (result.outdatedSkills.length > 0) {
+      const outdatedDesc = result.outdatedSkills.map((o) => `${o.id}@${o.installed} \u2192 ${o.latest}`).join(", ");
+      const outdatedIds = result.outdatedSkills.map((o) => o.id).join(" ");
+      logger.warn(
+        `\u90E8\u5206\u6280\u80FD\u5DF2\u88C5\u4F46\u6709\u53EF\u7528\u66F4\u65B0\uFF1A${outdatedDesc}\u3002\u8FD0\u884C "npx teamix-evo@latest skills update ${outdatedIds}" \u5347\u7EA7\u3002`
+      );
+    }
     logger.info("");
     logger.info(
       'Run "npx teamix-evo@latest skills list" to see installed skills.'
@@ -2021,9 +2440,9 @@ async function resolveIdesAndScope(args) {
 }
 
 // src/commands/skills/add.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 import * as prompts3 from "@clack/prompts";
-var addCommand = new Command8("add").description(
+var addCommand = new Command9("add").description(
   "\u589E\u91CF\u6DFB\u52A0 teamix-evo skills\uFF08\u5FC5\u987B\u6307\u5B9A\u81F3\u5C11\u4E00\u4E2A skill id\uFF1B\u81EA\u4E3E\u8BF7\u7528 `skills init`\uFF09"
 ).argument("<names...>", "\u81F3\u5C11\u4E00\u4E2A skill id\uFF08\u589E\u91CF\u88C5\uFF09").option("--ide <list>", '\u9017\u53F7\u5206\u9694\u7684 IDE \u5217\u8868\uFF0C\u5982 "qoder,claude"').option(
   "--scope <scope>",
@@ -2060,26 +2479,45 @@ var addCommand = new Command8("add").description(
       ide: ide.name,
       names
     });
-    if (result.addedSkillIds.length === 0 && result.skippedSkillIds.length > 0) {
-      logger.warn(
-        `\u5DF2\u5B58\u5728\uFF0C\u65E0\u9700\u6DFB\u52A0\uFF1A${result.skippedSkillIds.join(
-          ", "
-        )}\u3002\u5982\u9700\u5237\u65B0\u5185\u5BB9\u8BF7\u8FD0\u884C "npx teamix-evo@latest skills update"\u3002`
-      );
+    const hasAdded = result.addedSkillIds.length > 0;
+    const hasSkipped = result.skippedSkillIds.length > 0;
+    const hasOutdated = result.outdatedSkills.length > 0;
+    const outdatedDesc = result.outdatedSkills.map((o) => `${o.id}@${o.installed} \u2192 ${o.latest}`).join(", ");
+    const outdatedIds = result.outdatedSkills.map((o) => o.id).join(" ");
+    if (!hasAdded) {
+      if (hasOutdated) {
+        logger.warn(
+          `\u5DF2\u5B89\u88C5\u4F46\u6709\u53EF\u7528\u66F4\u65B0\uFF1A${outdatedDesc}\u3002\u8FD0\u884C "npx teamix-evo@latest skills update ${outdatedIds}" \u5347\u7EA7\u3002`
+        );
+      }
+      if (hasSkipped) {
+        if (hasOutdated) {
+          logger.info(`\u5176\u4F59\u5DF2\u662F\u6700\u65B0\uFF1A${result.skippedSkillIds.join(", ")}`);
+        } else {
+          logger.warn(
+            `\u5DF2\u5B58\u5728\uFF0C\u65E0\u9700\u6DFB\u52A0\uFF1A${result.skippedSkillIds.join(
+              ", "
+            )}\u3002\u5982\u9700\u5237\u65B0\u5185\u5BB9\u8BF7\u8FD0\u884C "npx teamix-evo@latest skills update"\u3002`
+          );
+        }
+      }
       return;
     }
     logger.success(`Skills added: ${result.skillCount} skill(s)`);
     logger.info(`  IDEs:    ${result.ides.join(", ")}`);
     logger.info(`  Scope:   ${result.scope}`);
-    if (result.addedSkillIds.length > 0) {
-      logger.info(`  Added:   ${result.addedSkillIds.join(", ")}`);
-    }
-    if (result.skippedSkillIds.length > 0) {
+    logger.info(`  Added:   ${result.addedSkillIds.join(", ")}`);
+    if (hasSkipped) {
       logger.info(
         `  Skipped: ${result.skippedSkillIds.join(", ")} (already added)`
       );
     }
     logger.info(`  Files:   ${result.fileCount}`);
+    if (hasOutdated) {
+      logger.warn(
+        `\u90E8\u5206\u6280\u80FD\u5DF2\u88C5\u4F46\u6709\u53EF\u7528\u66F4\u65B0\uFF1A${outdatedDesc}\u3002\u8FD0\u884C "npx teamix-evo@latest skills update ${outdatedIds}" \u5347\u7EA7\u3002`
+      );
+    }
     logger.info("");
     logger.info(
       'Run "npx teamix-evo@latest skills list" to see installed skills.'
@@ -2144,9 +2582,9 @@ async function resolveIdesAndScope2(args) {
 }
 
 // src/commands/skills/list.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 var SKILLS_PACKAGE = "@teamix-evo/skills";
-var listCommand2 = new Command9("list").alias("ls").description(
+var listCommand2 = new Command10("list").alias("ls").description(
   "\u5217\u51FA teamix-evo skills\uFF08\u9ED8\u8BA4\u5C55\u793A\u5168\u90E8 skill \u5E76\u6807\u6CE8\u5DF2\u88C5/\u672A\u88C5\uFF1B--installed \u4EC5\u770B\u5DF2\u88C5\uFF09"
 ).option("--installed", "\u4EC5\u5C55\u793A\u5DF2\u5B89\u88C5\u7684 skill\uFF08\u9690\u85CF\u672A\u5B89\u88C5\u9879\uFF09").action(async (opts) => {
   try {
@@ -2242,7 +2680,7 @@ function printInstalledHeader(cfg, installedAt) {
 }
 
 // src/commands/skills/update.ts
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 import { createRequire as createRequire3 } from "module";
 
 // src/core/skills-update.ts
@@ -2418,7 +2856,7 @@ async function runSkillsUpdate(options) {
 // src/commands/skills/update.ts
 var require4 = createRequire3(import.meta.url);
 var SKILLS_PACKAGE2 = "@teamix-evo/skills";
-var updateCommand2 = new Command10("update").description(
+var updateCommand2 = new Command11("update").description(
   "\u66F4\u65B0\u5DF2\u5B89\u88C5\u7684 teamix-evo skills\uFF08\u4EC5\u5347\u7EA7 lock \u5DF2\u8BB0\u5F55\u4E14 scope \u5339\u914D\u7684 skill \u2014 ADR 0035\uFF09"
 ).argument("[names...]", "\u53EF\u9009\uFF1A\u4EC5\u5347\u7EA7\u6307\u5B9A skill id\uFF1B\u7701\u7565\u5219\u5347\u7EA7\u5168\u90E8\u5DF2\u88C5").option("--dry-run", "\u9884\u89C8\u53D8\u66F4\uFF0C\u4E0D\u5199\u76D8").option(
   "--scope <scope>",
@@ -2541,12 +2979,12 @@ async function printVersionBanner() {
 }
 
 // src/commands/skills/uninstall.ts
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 import * as prompts4 from "@clack/prompts";
-import * as path14 from "path";
-import * as fs10 from "fs/promises";
+import * as path15 from "path";
+import * as fs11 from "fs/promises";
 var SKILLS_PACKAGE3 = "@teamix-evo/skills";
-var uninstallCommand2 = new Command11("uninstall").description(
+var uninstallCommand2 = new Command12("uninstall").description(
   "\u5378\u8F7D\u5DF2\u5B89\u88C5\u7684 teamix-evo skills\uFF1B\u4E0D\u4F20 ids \u5219\u5378\u8F7D\u6574\u5305\uFF0C\u4F20 ids \u5219\u6309 skill \u5220\u9664"
 ).argument("[ids...]", "\u53EF\u9009\uFF1A\u4EC5\u5378\u8F7D\u6307\u5B9A skill id\uFF1B\u7701\u7565\u5219\u5378\u8F7D\u6574\u4E2A skills \u5305").option("-y, --yes", "\u8DF3\u8FC7\u786E\u8BA4").action(async (ids, opts) => {
   try {
@@ -2611,7 +3049,7 @@ async function runFullUninstall(args) {
   const skillsRoot = getSkillsSourceDir(projectRoot);
   const sourceSkillNames = await listSkillSourceNames(skillsRoot);
   try {
-    await fs10.rm(skillsRoot, { recursive: true, force: true });
+    await fs11.rm(skillsRoot, { recursive: true, force: true });
     logger.debug(`Removed source dir ${skillsRoot}`);
   } catch (err) {
     logger.warn(`Failed to remove ${skillsRoot}: ${getErrorMessage(err)}`);
@@ -2637,10 +3075,10 @@ async function runFullUninstall(args) {
   await writeProjectConfig(projectRoot, config);
   logger.success(`Uninstalled ${SKILLS_PACKAGE3}`);
   logger.info(`  Removed: ${removed.length} files`);
-  logger.info(`  Source:  ${path14.relative(projectRoot, skillsRoot)} (cleaned)`);
+  logger.info(`  Source:  ${path15.relative(projectRoot, skillsRoot)} (cleaned)`);
   if (cleanedMirrorDirs.length > 0) {
     logger.info(
-      `  Mirrors: ${cleanedMirrorDirs.map((d) => path14.relative(projectRoot, d)).join(", ")} (cleaned)`
+      `  Mirrors: ${cleanedMirrorDirs.map((d) => path15.relative(projectRoot, d)).join(", ")} (cleaned)`
     );
   }
 }
@@ -2678,7 +3116,7 @@ async function runPartialUninstall(args) {
   for (const id of matched) {
     const dir = getSkillsSourceDir(projectRoot, id);
     try {
-      await fs10.rm(dir, { recursive: true, force: true });
+      await fs11.rm(dir, { recursive: true, force: true });
       logger.debug(`Removed source dir ${dir}`);
     } catch (err) {
       logger.warn(`Failed to remove ${dir}: ${getErrorMessage(err)}`);
@@ -2704,7 +3142,7 @@ async function runPartialUninstall(args) {
   logger.info(`  Files:   ${removed.length}`);
   if (cleanedMirrorDirs.length > 0) {
     logger.info(
-      `  Mirrors: ${cleanedMirrorDirs.map((d) => path14.relative(projectRoot, d)).join(", ")} (cleaned)`
+      `  Mirrors: ${cleanedMirrorDirs.map((d) => path15.relative(projectRoot, d)).join(", ")} (cleaned)`
     );
   }
   if (missing.length > 0) {
@@ -2713,7 +3151,7 @@ async function runPartialUninstall(args) {
 }
 async function listSkillSourceNames(skillsRoot) {
   try {
-    const entries = await fs10.readdir(skillsRoot, { withFileTypes: true });
+    const entries = await fs11.readdir(skillsRoot, { withFileTypes: true });
     return entries.filter((e) => e.isDirectory()).map((e) => e.name);
   } catch {
     return [];
@@ -2737,13 +3175,13 @@ async function removeMirrorDirs(projectRoot, scope, ides, skillNames) {
       const dir = adapter.getSkillTargetDir(name, targetScope, projectRoot);
       let existed = true;
       try {
-        await fs10.access(dir);
+        await fs11.access(dir);
       } catch {
         existed = false;
       }
       if (!existed) continue;
       try {
-        await fs10.rm(dir, { recursive: true, force: true });
+        await fs11.rm(dir, { recursive: true, force: true });
         removed.push(dir);
         logger.debug(`Removed mirror dir ${dir}`);
       } catch (err) {
@@ -2751,13 +3189,13 @@ async function removeMirrorDirs(projectRoot, scope, ides, skillNames) {
       }
     }
     if (removed.length > 0) {
-      const skillsParent = path14.dirname(
+      const skillsParent = path15.dirname(
         adapter.getSkillTargetDir("placeholder", targetScope, projectRoot)
       );
       try {
-        const remaining = await fs10.readdir(skillsParent);
+        const remaining = await fs11.readdir(skillsParent);
         if (remaining.length === 0) {
-          await fs10.rmdir(skillsParent);
+          await fs11.rmdir(skillsParent);
         }
       } catch {
       }
@@ -2783,18 +3221,18 @@ function dedupe(values) {
 }
 
 // src/commands/skills/sync.ts
-import { Command as Command12 } from "commander";
+import { Command as Command13 } from "commander";
 
 // src/core/skills-sync.ts
-import * as path15 from "path";
-import * as fs11 from "fs/promises";
+import * as path16 from "path";
+import * as fs12 from "fs/promises";
 import { createRequire as createRequire4 } from "module";
 import { loadSkillsPackageManifest as loadSkillsPackageManifest2 } from "@teamix-evo/registry";
 var require5 = createRequire4(import.meta.url);
 async function readSkillMetaFromUpstream(skillId) {
   try {
     const pkgJson = require5.resolve("@teamix-evo/skills/package.json");
-    const packageRoot = path15.dirname(pkgJson);
+    const packageRoot = path16.dirname(pkgJson);
     const manifest = await loadSkillsPackageManifest2(packageRoot);
     const entry = manifest.skills.find((s) => s.id === skillId);
     if (!entry) return null;
@@ -2874,7 +3312,7 @@ async function runSkillsSync(options) {
 }
 async function dirExists(p2) {
   try {
-    const stat7 = await fs11.stat(p2);
+    const stat7 = await fs12.stat(p2);
     return stat7.isDirectory();
   } catch {
     return false;
@@ -2892,8 +3330,8 @@ async function refreshMirrorRecords(projectRoot, newMirrorRecords) {
 }
 
 // src/commands/skills/sync.ts
-var syncCommand = new Command12("sync").description(
-  "\u628A .teamix-evo/skills/ \u4E0B\u7684\u6E90\u91CD\u65B0\u955C\u50CF\u5230 IDE \u8DEF\u5F84\uFF08.qoder / .claude\uFF09"
+var syncCommand = new Command13("sync").description(
+  "\u628A .teamix-evo/skills-source/ \u4E0B\u7684\u6E90\u91CD\u65B0\u955C\u50CF\u5230 IDE \u8DEF\u5F84\uFF08.qoder / .claude\uFF09"
 ).argument(
   "[names...]",
   "\u53EF\u9009\uFF1A\u4EC5\u540C\u6B65\u6307\u5B9A skill id\uFF1B\u7701\u7565\u5219\u540C\u6B65\u5168\u90E8\u5DF2\u8BB0\u5F55\u5728 lock \u5185\u7684 skill"
@@ -2918,7 +3356,7 @@ var syncCommand = new Command12("sync").description(
     });
     if (result.status === "no-skills") {
       logger.info(
-        "No skills recorded in .teamix-evo/skills/manifest.lock.json. Nothing to sync."
+        "No skills recorded in .teamix-evo/skills-source/manifest.lock.json. Nothing to sync."
       );
       return;
     }
@@ -2943,11 +3381,11 @@ var syncCommand = new Command12("sync").description(
 });
 
 // src/commands/skills/doctor.ts
-import { Command as Command13 } from "commander";
+import { Command as Command14 } from "commander";
 
 // src/core/skills-doctor.ts
-import * as path16 from "path";
-import * as fs12 from "fs/promises";
+import * as path17 from "path";
+import * as fs13 from "fs/promises";
 async function runSkillsDoctor(options) {
   const { projectRoot } = options;
   const lock = await readSkillsLock(projectRoot);
@@ -2969,8 +3407,8 @@ async function runSkillsDoctor(options) {
     const sourceFiles = await walkDir(sourceDir);
     const sourceContents = /* @__PURE__ */ new Map();
     for (const f of sourceFiles) {
-      const rel2 = path16.relative(sourceDir, f);
-      sourceContents.set(rel2, await fs12.readFile(f, "utf-8"));
+      const rel2 = path17.relative(sourceDir, f);
+      sourceContents.set(rel2, await fs13.readFile(f, "utf-8"));
     }
     for (const ide of entry.mirroredTo) {
       const adapter = getAdapter(ide);
@@ -2991,7 +3429,7 @@ async function runSkillsDoctor(options) {
         continue;
       }
       for (const [rel2, sourceContent] of sourceContents.entries()) {
-        const mirrorFile = path16.join(mirrorDir, rel2);
+        const mirrorFile = path17.join(mirrorDir, rel2);
         if (!await fileExists(mirrorFile)) {
           findings.push({
             kind: "missing-mirror",
@@ -3003,7 +3441,7 @@ async function runSkillsDoctor(options) {
           });
           continue;
         }
-        const mirrorContent = await fs12.readFile(mirrorFile, "utf-8");
+        const mirrorContent = await fs13.readFile(mirrorFile, "utf-8");
         if (computeHash(mirrorContent) !== computeHash(sourceContent)) {
           findings.push({
             kind: "mirror-drift",
@@ -3024,7 +3462,7 @@ async function runSkillsDoctor(options) {
 }
 async function dirExists2(p2) {
   try {
-    const stat7 = await fs12.stat(p2);
+    const stat7 = await fs13.stat(p2);
     return stat7.isDirectory();
   } catch {
     return false;
@@ -3032,7 +3470,9 @@ async function dirExists2(p2) {
 }
 
 // src/commands/skills/doctor.ts
-var doctorCommand = new Command13("doctor").description("\u68C0\u67E5 .teamix-evo/skills/ \u6E90\u4E0E IDE \u955C\u50CF\u662F\u5426\u6F02\u79FB\uFF1B\u63D0\u793A\u5982\u4F55\u4FEE\u590D").action(async () => {
+var doctorCommand = new Command14("doctor").description(
+  "\u68C0\u67E5 .teamix-evo/skills-source/ \u6E90\u4E0E IDE \u955C\u50CF\u662F\u5426\u6F02\u79FB\uFF1B\u63D0\u793A\u5982\u4F55\u4FEE\u590D"
+).action(async () => {
   try {
     const ide = detectIde();
     const cwd = ide.getProjectRoot();
@@ -3069,7 +3509,7 @@ var doctorCommand = new Command13("doctor").description("\u68C0\u67E5 .teamix-ev
 });
 
 // src/commands/skills/index.ts
-var skillsCommand = new Command14("skills").description(
+var skillsCommand = new Command15("skills").description(
   "\u7BA1\u7406 teamix-evo skills\uFF08\u5411 AI IDE \u6CE8\u5165\u6280\u80FD\uFF1Bsource-mirror \u6A21\u578B\u89C1 ADR 0013\uFF09"
 );
 skillsCommand.addCommand(initCommand2);
@@ -3081,10 +3521,10 @@ skillsCommand.addCommand(doctorCommand);
 skillsCommand.addCommand(uninstallCommand2);
 
 // src/commands/ui/index.ts
-import { Command as Command19 } from "commander";
+import { Command as Command21 } from "commander";
 
 // src/commands/ui/init.ts
-import { Command as Command15 } from "commander";
+import { Command as Command16 } from "commander";
 import * as prompts5 from "@clack/prompts";
 
 // src/core/ui-init.ts
@@ -3142,7 +3582,7 @@ async function runUiInit(options) {
 }
 
 // src/commands/ui/init.ts
-var initCommand3 = new Command15("init").description(
+var initCommand3 = new Command16("init").description(
   "\u521D\u59CB\u5316 teamix-evo ui \u914D\u7F6E\uFF08\u8BE2\u95EE aliases / iconLibrary / tsx / rsc\uFF09"
 ).option("-y, --yes", "\u4F7F\u7528\u9ED8\u8BA4\u503C\uFF0C\u8DF3\u8FC7\u4EA4\u4E92").option(
   "--components <path>",
@@ -3261,26 +3701,26 @@ async function resolveConfig(opts) {
 }
 
 // src/commands/ui/add.ts
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 
 // src/core/ui-client.ts
-import * as path17 from "path";
-import * as fs13 from "fs/promises";
+import * as path18 from "path";
+import * as fs14 from "fs/promises";
 import { createRequire as createRequire5 } from "module";
 import { loadUiPackageManifest } from "@teamix-evo/registry";
 var require6 = createRequire5(import.meta.url);
 function resolvePackageRoot2(packageName) {
   const pkgJsonPath = require6.resolve(`${packageName}/package.json`);
-  return path17.dirname(pkgJsonPath);
+  return path18.dirname(pkgJsonPath);
 }
 async function loadUiData(packageName) {
   const packageRoot = resolvePackageRoot2(packageName);
   logger.debug(`Resolved ui package root: ${packageRoot}`);
   const manifest = await loadUiPackageManifest(packageRoot);
   let data = {};
-  const dataPath = path17.join(packageRoot, "_data.json");
+  const dataPath = path18.join(packageRoot, "_data.json");
   try {
-    const raw = await fs13.readFile(dataPath, "utf-8");
+    const raw = await fs14.readFile(dataPath, "utf-8");
     data = JSON.parse(raw);
   } catch (err) {
     if (err.code !== "ENOENT") {
@@ -3292,8 +3732,8 @@ async function loadUiData(packageName) {
 }
 
 // src/core/ui-installer.ts
-import * as path18 from "path";
-import * as fs14 from "fs/promises";
+import * as path19 from "path";
+import * as fs15 from "fs/promises";
 import { resolveUiEntryOrder } from "@teamix-evo/registry";
 
 // src/utils/transform-imports.ts
@@ -3366,9 +3806,12 @@ async function installUiEntries(options) {
         continue;
       }
       const rootForEntry = entryPackageRoot?.get(entry.id) ?? packageRoot;
-      const sourceAbs = path18.resolve(rootForEntry, file.source);
-      const raw = await fs14.readFile(sourceAbs, "utf-8");
+      const sourceAbs = path19.resolve(rootForEntry, file.source);
+      const raw = await fs15.readFile(sourceAbs, "utf-8");
       const transformed = rewriteImports(raw, aliases);
+      if (exists) {
+        await backupFile(targetAbs, projectRoot);
+      }
       await writeFileSafe(targetAbs, transformed);
       written++;
       logger.info(`  write: ${rel(projectRoot, targetAbs)}`);
@@ -3395,10 +3838,10 @@ function resolveTargetPath(projectRoot, aliases, entry, file) {
       `Entry "${entry.id}" requires alias "${file.targetAlias}" but it is not configured.`
     );
   }
-  return path18.join(projectRoot, aliasDir, file.targetName);
+  return path19.join(projectRoot, aliasDir, file.targetName);
 }
 function rel(projectRoot, abs) {
-  return path18.relative(projectRoot, abs);
+  return path19.relative(projectRoot, abs);
 }
 
 // src/core/ui-add.ts
@@ -3485,30 +3928,271 @@ function mergeResources(prior, next) {
   return Array.from(merged.values());
 }
 
-// src/commands/ui/add.ts
-var addCommand2 = new Command16("add").description(
-  "\u5B89\u88C5\u4E00\u4E2A\u6216\u591A\u4E2A ui entry\uFF08\u6309 id\uFF0C\u81EA\u52A8\u5C55\u5F00 registryDependencies\uFF09"
-).argument("<ids...>", 'entry id \u5217\u8868\uFF0C\u5982 "button" "dialog"').option("--overwrite", "\u5373\u4F7F\u76EE\u6807\u6587\u4EF6\u5DF2\u5B58\u5728\u4E5F\u8986\u76D6\uFF08\u7ED5\u8FC7 frozen \u8DF3\u8FC7\uFF09").option(
-  "--include-deprecated",
-  "\u5141\u8BB8\u5B89\u88C5\u5DF2\u5F52\u6863\u7684 deprecated entry\uFF08\u4EC5\u8FC1\u79FB / \u5BA1\u8BA1\u573A\u666F\uFF0CADR 0028\uFF09"
-).action(
-  async (ids, opts) => {
-    try {
-      const ide = detectIde();
-      const projectRoot = ide.getProjectRoot();
-      logger.info(`Installing entries: ${ids.join(", ")}`);
-      const result = await runUiAdd({
-        projectRoot,
-        ids,
-        overwrite: opts.overwrite,
-        includeDeprecated: opts.includeDeprecated
-      });
-      logger.success(
-        `UI add complete: ${result.written} written, ${result.skipped} skipped.`
-      );
-      logger.info("");
-      logger.info(`Resolved order: ${result.orderedIds.join(" \u2192 ")}`);
-      const npmDeps = Object.entries(result.npmDependencies);
+// src/core/ui-adopt.ts
+import * as path20 from "path";
+import * as fs16 from "fs/promises";
+var DEFAULT_UI_PACKAGE2 = "@teamix-evo/ui";
+async function runUiAdopt(options) {
+  const { projectRoot, dryRun = false } = options;
+  const packageName = options.packageName ?? DEFAULT_UI_PACKAGE2;
+  const config = await readProjectConfig(projectRoot);
+  const uiCfg = config?.packages?.ui;
+  if (!config || !uiCfg?.aliases) {
+    throw new Error(
+      "UI not initialized. Run `runUiInit` (or `teamix-evo ui init`) first."
+    );
+  }
+  const { manifest, packageRoot } = await loadUiData(packageName);
+  const aliases = uiCfg.aliases;
+  const adopted = [];
+  const foreign = [];
+  const hooks = [];
+  const utils = [];
+  const types = [];
+  const idToEntry = /* @__PURE__ */ new Map();
+  for (const e of manifest.deprecatedEntries ?? []) idToEntry.set(e.id, e);
+  for (const e of manifest.entries) idToEntry.set(e.id, e);
+  const aliasRoots = [
+    { abs: path20.join(projectRoot, aliases.components), bucket: "components" },
+    { abs: path20.join(projectRoot, aliases.hooks), bucket: "hooks" },
+    { abs: path20.join(projectRoot, aliases.utils), bucket: "utils" },
+    { abs: path20.join(projectRoot, aliases.business), bucket: "components" }
+  ];
+  if (aliases.lib && aliases.lib !== aliases.utils) {
+    aliasRoots.push({
+      abs: path20.join(projectRoot, aliases.lib),
+      bucket: "utils"
+    });
+  }
+  for (const root of aliasRoots) {
+    const files = await listSourceFiles(root.abs);
+    for (const abs of files) {
+      const rel2 = toPosixRel(projectRoot, abs);
+      const content = await fs16.readFile(abs, "utf-8");
+      const fileType = classifyFile(abs, content);
+      const id = inferEntryId(abs);
+      if (fileType === "type") {
+        types.push({ rel: rel2, fileType, target: abs, reason: "no-registry-match" });
+        continue;
+      }
+      if (fileType === "hook" || root.bucket === "hooks") {
+        hooks.push({
+          rel: rel2,
+          fileType: "hook",
+          target: abs,
+          reason: "no-registry-match"
+        });
+        continue;
+      }
+      if (fileType === "util" || root.bucket === "utils") {
+        utils.push({
+          rel: rel2,
+          fileType: "util",
+          target: abs,
+          reason: "no-registry-match"
+        });
+        continue;
+      }
+      const entry = id ? idToEntry.get(id) : void 0;
+      if (!entry) {
+        foreign.push({
+          rel: rel2,
+          fileType: fileType === "unknown" ? "component" : fileType,
+          target: abs,
+          reason: "no-registry-match"
+        });
+        continue;
+      }
+      const upstream = await readUpstreamContent(
+        packageRoot,
+        entry,
+        aliases
+      ).catch((err) => {
+        logger.debug(
+          `Failed to read upstream for ${entry.id}: ${err.message}`
+        );
+        return null;
+      });
+      const lineage = upstream === null ? "detected" : normalize(upstream) === normalize(content) ? "teamix-evo" : "custom";
+      adopted.push({
+        id: entry.id,
+        target: abs,
+        rel: rel2,
+        fileType: fileType === "unknown" ? "component" : fileType,
+        sourceLineage: lineage,
+        hash: computeHash(content)
+      });
+    }
+  }
+  if (!dryRun && adopted.length > 0) {
+    await mergeIntoInstalledManifest({
+      projectRoot,
+      packageName,
+      manifest,
+      adopted
+    });
+  }
+  return {
+    packageName,
+    adopted,
+    foreign,
+    hooks,
+    utils,
+    types,
+    dryRun
+  };
+}
+async function listSourceFiles(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = await fs16.readdir(current, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      throw err;
+    }
+    for (const e of entries) {
+      const abs = path20.join(current, e.name);
+      if (e.isDirectory()) {
+        if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+        stack.push(abs);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (/\.(ts|tsx)$/.test(e.name)) out.push(abs);
+    }
+  }
+  return out;
+}
+function classifyFile(abs, content) {
+  const base = path20.basename(abs);
+  if (base.endsWith(".d.ts")) return "type";
+  if (/^use-[a-z0-9-]+\.tsx?$/i.test(base)) return "hook";
+  const hasJsx = /<[A-Za-z][^>]*?>/.test(content);
+  const hasReactImport = /from ['"]react['"]/.test(content);
+  const hasForwardRef = /forwardRef\s*[<(]/.test(content);
+  const hasProvider = /\.Provider\b/.test(content) || /createContext\s*[<(]/.test(content);
+  if (hasProvider && (hasJsx || hasReactImport)) return "provider";
+  if (hasJsx || hasForwardRef) return "component";
+  if (hasReactImport && /export\s+(const|function|default)/.test(content))
+    return "component";
+  const exportsValue = /export\s+(const|function|class|default|let|var)\b/.test(
+    content
+  );
+  const exportsType = /export\s+(type|interface)\b/.test(content) || /^\s*type\s+/m.test(content);
+  if (!exportsValue && exportsType) return "type";
+  if (base.startsWith("use-")) return "hook";
+  if (/\b(use[A-Z]\w+)\s*\(/.test(content) && !hasJsx) {
+    return "util";
+  }
+  if (!hasJsx && !hasReactImport) return "util";
+  return "unknown";
+}
+function inferEntryId(abs) {
+  const base = path20.basename(abs).replace(/\.(tsx?|d\.ts)$/i, "");
+  if (!base) return null;
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(base)) return null;
+  if (base.startsWith("use-")) return null;
+  return base;
+}
+async function readUpstreamContent(packageRoot, entry, aliases) {
+  const file = entry.files[0];
+  if (!file) return null;
+  const sourceAbs = path20.resolve(packageRoot, file.source);
+  let raw;
+  try {
+    raw = await fs16.readFile(sourceAbs, "utf-8");
+  } catch {
+    return null;
+  }
+  return rewriteImports(raw, aliases);
+}
+function normalize(s) {
+  return s.replace(/\r\n/g, "\n").trim();
+}
+function toPosixRel(projectRoot, abs) {
+  return path20.relative(projectRoot, abs).split(path20.sep).join("/");
+}
+async function mergeIntoInstalledManifest(args) {
+  const { projectRoot, packageName, manifest, adopted } = args;
+  const installed = await readInstalledManifest(
+    projectRoot
+  ) ?? { schemaVersion: 1, installed: [] };
+  const idx = installed.installed.findIndex((p2) => p2.package === packageName);
+  const prior = idx >= 0 ? installed.installed[idx] : null;
+  const newResources = adopted.map((a) => {
+    const targetName = path20.basename(a.target);
+    return {
+      id: `${a.id}:${targetName}`,
+      target: a.target,
+      hash: a.hash,
+      strategy: "frozen",
+      sourceLineage: a.sourceLineage
+    };
+  });
+  const merged = mergeResources2(prior?.resources ?? [], newResources);
+  const entry = {
+    package: packageName,
+    variant: "_flat",
+    version: manifest.version,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    resources: merged
+  };
+  if (idx >= 0) installed.installed[idx] = entry;
+  else installed.installed.push(entry);
+  await writeInstalledManifest(projectRoot, installed);
+}
+function mergeResources2(prior, next) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const r of prior) merged.set(r.id, r);
+  for (const r of next) merged.set(r.id, r);
+  return Array.from(merged.values());
+}
+
+// src/commands/ui/add.ts
+var addCommand2 = new Command17("add").description(
+  "\u5B89\u88C5\u4E00\u4E2A\u6216\u591A\u4E2A ui entry\uFF08\u6309 id\uFF0C\u81EA\u52A8\u5C55\u5F00 registryDependencies\uFF09"
+).argument("[ids...]", 'entry id \u5217\u8868\uFF0C\u5982 "button" "dialog"').option("--overwrite", "\u5373\u4F7F\u76EE\u6807\u6587\u4EF6\u5DF2\u5B58\u5728\u4E5F\u8986\u76D6\uFF08\u7ED5\u8FC7 frozen \u8DF3\u8FC7\uFF09").option(
+  "--include-deprecated",
+  "\u5141\u8BB8\u5B89\u88C5\u5DF2\u5F52\u6863\u7684 deprecated entry\uFF08\u4EC5\u8FC1\u79FB / \u5BA1\u8BA1\u573A\u666F\uFF0CADR 0028\uFF09"
+).option("--adopt", "\u626B\u63CF\u9879\u76EE\u73B0\u6709 UI \u6E90\u7801\u7EB3\u7BA1\u5230 manifest\uFF0C\u4E0D\u5199\u5165\u4EFB\u4F55\u6587\u4EF6\u5185\u5BB9").option(
+  "--dry-run",
+  "\u4EC5\u626B\u63CF + \u8F93\u51FA\u62A5\u544A\uFF0C\u4E0D\u4FEE\u6539 manifest\uFF08\u4EC5\u4E0E --adopt \u540C\u7528\uFF09"
+).action(
+  async (ids, opts) => {
+    try {
+      const ide = detectIde();
+      const projectRoot = ide.getProjectRoot();
+      if (opts.adopt) {
+        await runAdoptCli(projectRoot, opts.dryRun ?? false);
+        return;
+      }
+      if (opts.dryRun) {
+        logger.warn(
+          "`--dry-run` only takes effect together with `--adopt`; ignoring for plain ui add."
+        );
+      }
+      if (!ids || ids.length === 0) {
+        throw new Error(
+          "At least one entry id must be provided (or pass `--adopt`)."
+        );
+      }
+      logger.info(`Installing entries: ${ids.join(", ")}`);
+      const result = await runUiAdd({
+        projectRoot,
+        ids,
+        overwrite: opts.overwrite,
+        includeDeprecated: opts.includeDeprecated
+      });
+      logger.success(
+        `UI add complete: ${result.written} written, ${result.skipped} skipped.`
+      );
+      logger.info("");
+      logger.info(`Resolved order: ${result.orderedIds.join(" \u2192 ")}`);
+      const npmDeps = Object.entries(result.npmDependencies);
       if (npmDeps.length > 0) {
         logger.info("");
         logger.info("Install npm dependencies in your project:");
@@ -3530,15 +4214,51 @@ var addCommand2 = new Command16("add").description(
     }
   }
 );
+async function runAdoptCli(projectRoot, dryRun) {
+  logger.info(
+    dryRun ? "Adopt scan (dry-run) \u2014 no manifest changes will be written." : "Adopting existing UI source files into manifest..."
+  );
+  const result = await runUiAdopt({ projectRoot, dryRun });
+  logger.success(
+    `UI adopt complete: ${result.adopted.length} adopted, ${result.foreign.length} foreign, ${result.hooks.length} hooks, ${result.utils.length} utils, ${result.types.length} types.`
+  );
+  if (result.adopted.length > 0) {
+    logger.info("");
+    logger.info("Adopted (matched registry id):");
+    for (const a of result.adopted) {
+      logger.info(`  \u2022 ${a.id} \u2190 ${a.rel} [${a.sourceLineage}]`);
+    }
+  }
+  if (result.foreign.length > 0) {
+    logger.info("");
+    logger.info("Foreign (no registry match \u2014 keep as-is):");
+    for (const f of result.foreign) logger.info(`  \u2022 ${f.rel}`);
+  }
+  if (result.hooks.length > 0) {
+    logger.info("");
+    logger.info("Hooks:");
+    for (const h of result.hooks) logger.info(`  \u2022 ${h.rel}`);
+  }
+  if (result.utils.length > 0) {
+    logger.info("");
+    logger.info("Utils:");
+    for (const u of result.utils) logger.info(`  \u2022 ${u.rel}`);
+  }
+  if (result.types.length > 0) {
+    logger.info("");
+    logger.info("Type-only modules:");
+    for (const t of result.types) logger.info(`  \u2022 ${t.rel}`);
+  }
+}
 
 // src/commands/ui/list.ts
-import { Command as Command17 } from "commander";
+import { Command as Command18 } from "commander";
 
 // src/core/ui-list.ts
-var DEFAULT_UI_PACKAGE2 = "@teamix-evo/ui";
+var DEFAULT_UI_PACKAGE3 = "@teamix-evo/ui";
 async function runUiList(options) {
   const { projectRoot, installedOnly, includeDeprecated } = options;
-  const packageName = options.packageName ?? DEFAULT_UI_PACKAGE2;
+  const packageName = options.packageName ?? DEFAULT_UI_PACKAGE3;
   const { manifest } = await loadUiData(packageName);
   const installedManifest = await readInstalledManifest(projectRoot);
   const installedIds = /* @__PURE__ */ new Set();
@@ -3570,7 +4290,7 @@ async function runUiList(options) {
 }
 
 // src/commands/ui/list.ts
-var listCommand3 = new Command17("list").description("\u5217\u51FA @teamix-evo/ui \u7684\u6240\u6709 entry \u53CA\u5DF2\u5B89\u88C5\u72B6\u6001").option("--installed", "\u4EC5\u5C55\u793A\u5DF2\u5B89\u88C5\u7684 entry").option(
+var listCommand3 = new Command18("list").description("\u5217\u51FA @teamix-evo/ui \u7684\u6240\u6709 entry \u53CA\u5DF2\u5B89\u88C5\u72B6\u6001").option("--installed", "\u4EC5\u5C55\u793A\u5DF2\u5B89\u88C5\u7684 entry").option(
   "--include-deprecated",
   "\u540C\u65F6\u5217\u51FA\u5DF2\u5F52\u6863\u7684 deprecated entry\uFF08\u9ED8\u8BA4\u9690\u85CF\uFF0CADR 0028\uFF09"
 ).action(
@@ -3622,10 +4342,10 @@ var listCommand3 = new Command17("list").description("\u5217\u51FA @teamix-evo/u
 );
 
 // src/commands/_upgrade-command-factory.ts
-import { Command as Command18 } from "commander";
+import { Command as Command19 } from "commander";
 
 // src/core/ui-upgrade.ts
-import * as path21 from "path";
+import * as path23 from "path";
 import { createRequire as createRequire6 } from "module";
 import {
   loadUiPackageManifest as loadUiPackageManifest2,
@@ -3633,8 +4353,8 @@ import {
 } from "@teamix-evo/registry";
 
 // src/core/ui-upgrade-detector.ts
-import * as fs15 from "fs/promises";
-import * as path19 from "path";
+import * as fs17 from "fs/promises";
+import * as path21 from "path";
 var PACKAGE_NAME = {
   ui: "@teamix-evo/ui",
   "biz-ui": "@teamix-evo/biz-ui"
@@ -3650,10 +4370,10 @@ async function detectComponentLineage(options) {
   const config = options.config ?? await readProjectConfig(projectRoot);
   const installed = options.installed ?? await readInstalledManifest(projectRoot);
   const installDir = resolveInstallDir(category, config);
-  const installDirAbs = path19.join(projectRoot, installDir);
+  const installDirAbs = path21.join(projectRoot, installDir);
   const installDirExists = await directoryExists(installDirAbs);
   const hasComponentsJson = await fileExists(
-    path19.join(projectRoot, "components.json")
+    path21.join(projectRoot, "components.json")
   );
   const installedPkg = findInstalledPackage(installed, PACKAGE_NAME[category]);
   const registeredIds = installedPkg ? extractIds(installedPkg).sort() : [];
@@ -3693,14 +4413,14 @@ function extractIds(pkg) {
 }
 async function directoryExists(p2) {
   try {
-    const stat7 = await fs15.stat(p2);
+    const stat7 = await fs17.stat(p2);
     return stat7.isDirectory();
   } catch {
     return false;
   }
 }
 async function listComponentIds(installDirAbs) {
-  const entries = await fs15.readdir(installDirAbs, { withFileTypes: true });
+  const entries = await fs17.readdir(installDirAbs, { withFileTypes: true });
   const ids = [];
   for (const e of entries) {
     if (!e.isFile()) continue;
@@ -3720,7 +4440,7 @@ function classifyLineage(args) {
 }
 
 // src/core/ui-upgrade-staging.ts
-import * as path20 from "path";
+import * as path22 from "path";
 var TEAMIX_DIR4 = ".teamix-evo";
 var STAGING_DIR = ".upgrade-staging";
 var PACKAGE_NAME2 = {
@@ -3740,7 +4460,7 @@ async function buildUiUpgradeStaging(options) {
   if (!installedPkg) return null;
   const isoTs = options.isoTs ?? (/* @__PURE__ */ new Date()).toISOString();
   const fsTs = isoToFsSafe2(isoTs);
-  const stagingDir = path20.join(
+  const stagingDir = path22.join(
     options.projectRoot,
     TEAMIX_DIR4,
     STAGING_DIR,
@@ -3772,7 +4492,7 @@ async function buildUiUpgradeStaging(options) {
     if (onlyIds && !onlyIds.has(id)) continue;
     const built = await processForeign({
       id,
-      installDirAbs: path20.join(options.projectRoot, lineageReport.installDir),
+      installDirAbs: path22.join(options.projectRoot, lineageReport.installDir),
       stagingDir,
       projectRoot: options.projectRoot,
       category
@@ -3795,7 +4515,7 @@ async function buildUiUpgradeStaging(options) {
   };
   await ensureDir(stagingDir);
   await writeFileSafe(
-    path20.join(stagingDir, "meta.json"),
+    path22.join(stagingDir, "meta.json"),
     JSON.stringify(manifestOut, null, 2) + "\n"
   );
   return { stagingDir, manifest: manifestOut };
@@ -3829,19 +4549,19 @@ async function processRegistered(args) {
   const file = entry.files[0];
   if (!file) return null;
   const rootForEntry = args.entryPackageRoot?.get(id) ?? args.packageRoot;
-  const sourceAbs = path20.resolve(rootForEntry, file.source);
+  const sourceAbs = path22.resolve(rootForEntry, file.source);
   const raw = await readFileOrNull(sourceAbs);
   if (raw === null) {
     return null;
   }
   const incomingTransformed = rewriteImports(raw, args.aliases);
   const incomingHash = computeHash(incomingTransformed);
-  const currentExt = path20.extname(resource.target) || ".tsx";
-  const incomingExt = path20.extname(file.targetName) || currentExt;
+  const currentExt = path22.extname(resource.target) || ".tsx";
+  const incomingExt = path22.extname(file.targetName) || currentExt;
   const currentRel = `${id}/current${currentExt}`;
   const incomingRel = `${id}/incoming${incomingExt}`;
-  await writeFileSafe(path20.join(stagingDir, currentRel), currentSource);
-  await writeFileSafe(path20.join(stagingDir, incomingRel), incomingTransformed);
+  await writeFileSafe(path22.join(stagingDir, currentRel), currentSource);
+  await writeFileSafe(path22.join(stagingDir, incomingRel), incomingTransformed);
   const diff = classifyRisk({
     currentHash: resource.hash,
     incomingHash,
@@ -3849,11 +4569,16 @@ async function processRegistered(args) {
     incomingSource: incomingTransformed,
     multiFile: entry.files.length > 1
   });
+  const promotion = derivePromotion({
+    currentSource,
+    incomingSource: incomingTransformed,
+    targetName: entry.files[0]?.targetName ?? `${id}.tsx`
+  });
   return {
     id,
     category,
     current: {
-      target: path20.relative(projectRoot, resource.target),
+      target: path22.relative(projectRoot, resource.target),
       hash: resource.hash,
       sourceLineage: "teamix-evo"
     },
@@ -3862,25 +4587,26 @@ async function processRegistered(args) {
       hash: incomingHash,
       relPath: incomingRel
     },
-    diff
+    diff,
+    promotion
   };
 }
 async function processForeign(args) {
   const { id, installDirAbs, stagingDir, projectRoot, category } = args;
-  const tsx = path20.join(installDirAbs, `${id}.tsx`);
-  const ts = path20.join(installDirAbs, `${id}.ts`);
+  const tsx = path22.join(installDirAbs, `${id}.tsx`);
+  const ts = path22.join(installDirAbs, `${id}.ts`);
   const target = await fileExists(tsx) ? tsx : await fileExists(ts) ? ts : null;
   if (!target) return null;
   const raw = await readFileOrNull(target);
   if (raw === null) return null;
-  const ext = path20.extname(target);
+  const ext = path22.extname(target);
   const currentRel = `${id}/current${ext}`;
-  await writeFileSafe(path20.join(stagingDir, currentRel), raw);
+  await writeFileSafe(path22.join(stagingDir, currentRel), raw);
   return {
     id,
     category,
     current: {
-      target: path20.relative(projectRoot, target),
+      target: path22.relative(projectRoot, target),
       hash: computeHash(raw),
       sourceLineage: "custom"
     },
@@ -3895,17 +4621,17 @@ async function processForeign(args) {
   };
 }
 async function buildBreakingEntry(args) {
-  const ext = path20.extname(args.resource.target) || ".tsx";
+  const ext = path22.extname(args.resource.target) || ".tsx";
   const currentRel = `${args.id}/current${ext}`;
   await writeFileSafe(
-    path20.join(args.stagingDir, currentRel),
+    path22.join(args.stagingDir, currentRel),
     args.currentSource
   );
   return {
     id: args.id,
     category: args.category,
     current: {
-      target: path20.relative(args.projectRoot, args.resource.target),
+      target: path22.relative(args.projectRoot, args.resource.target),
       hash: args.resource.hash,
       sourceLineage: "teamix-evo"
     },
@@ -4025,12 +4751,191 @@ function aggregateByRisk(entries) {
   }
   return out;
 }
+function derivePromotion(args) {
+  const fileType = classifyPromoteFileType(args.targetName, args.currentSource);
+  const featureVector = buildFeatureVector(
+    args.currentSource,
+    args.incomingSource
+  );
+  const { recommendedModes, confidence, reasons } = scorePromotionModes(
+    fileType,
+    featureVector
+  );
+  return { fileType, featureVector, recommendedModes, confidence, reasons };
+}
+function classifyPromoteFileType(targetName, src) {
+  if (targetName.endsWith(".d.ts")) return "type";
+  if (/^use-[a-z0-9-]+\.tsx?$/i.test(targetName)) return "hook";
+  const hasJsx = /<[A-Za-z][^>]*?>/.test(src);
+  const hasReactImport = /from ['"]react['"]/.test(src);
+  const hasProvider = /\.Provider\b/.test(src) || /createContext\s*[<(]/.test(src);
+  if (hasProvider && (hasJsx || hasReactImport)) return "provider";
+  if (hasJsx || /forwardRef\s*[<(]/.test(src)) return "component";
+  if (!hasJsx && !hasReactImport) return "util";
+  return "component";
+}
+function buildFeatureVector(current, incoming) {
+  const curExports = extractExportNames(current);
+  const newExports = extractExportNames(incoming);
+  const apiAdded = setDiff(curExports, newExports);
+  const apiRemoved = setDiff(newExports, curExports);
+  const curVariants = extractCvaVariantValues(current);
+  const newVariants = extractCvaVariantValues(incoming);
+  const cvaAdded = setDiff(curVariants, newVariants);
+  const cvaModified = [];
+  const sharedVariants = curVariants.filter((v) => newVariants.includes(v));
+  for (const v of sharedVariants) {
+    if (extractVariantBody(current, v) !== extractVariantBody(incoming, v)) {
+      cvaModified.push(v);
+    }
+  }
+  const curClass = extractClassNameLiterals(current);
+  const newClass = extractClassNameLiterals(incoming);
+  const classNameDiff = curClass !== newClass;
+  const curTokens = extractTokenRefs(current);
+  const newTokens = extractTokenRefs(incoming);
+  const tokenUsageDiff = curTokens.size !== newTokens.size || [...curTokens].some((t) => !newTokens.has(t));
+  const hasState = /\buseState\s*[<(]/.test(current);
+  const hasEffect = /\b(useEffect|useLayoutEffect|useMemo|useCallback)\s*[<(]/.test(current);
+  const curImports = extractImportSources(current);
+  const newImports = extractImportSources(incoming);
+  const hasExtraImports = [...curImports].some((src) => !newImports.has(src));
+  const tagSet = /* @__PURE__ */ new Set();
+  for (const m of current.matchAll(/<([A-Z]\w+)[\s/>]/g)) {
+    if (m[1]) tagSet.add(m[1]);
+  }
+  const atomicChildren = [...tagSet];
+  const isComposition = atomicChildren.length > 2;
+  const signatureChanged = extractDefaultParamList(current) !== extractDefaultParamList(incoming);
+  return {
+    apiDelta: { added: apiAdded, removed: apiRemoved, signatureChanged },
+    styleDelta: { classNameDiff, tokenUsageDiff },
+    logicDelta: { hasState, hasEffect, hasExtraImports },
+    cvaDelta: { addedVariants: cvaAdded, modifiedVariants: cvaModified },
+    structureDelta: { isComposition, atomicChildren }
+  };
+}
+function scorePromotionModes(fileType, fv) {
+  const reasons = [];
+  if (fileType === "hook" || fileType === "util" || fileType === "type") {
+    reasons.push(
+      `fileType=${fileType} \u2014 not a component, deferred to ManualReview`
+    );
+    return { recommendedModes: ["ManualReview"], confidence: 0.5, reasons };
+  }
+  const apiNoChange = fv.apiDelta.added.length === 0 && fv.apiDelta.removed.length === 0 && !fv.apiDelta.signatureChanged;
+  const logicMinimal = !fv.logicDelta.hasState && !fv.logicDelta.hasEffect && !fv.logicDelta.hasExtraImports;
+  if (fv.apiDelta.removed.length > 0 || fv.apiDelta.signatureChanged) {
+    reasons.push(
+      "signature changed or props removed \u2014 Coexist preserves user version"
+    );
+    return { recommendedModes: ["Coexist"], confidence: 0.85, reasons };
+  }
+  if (apiNoChange && logicMinimal && (fv.styleDelta.classNameDiff || fv.styleDelta.tokenUsageDiff) && fv.cvaDelta.addedVariants.length === 0 && fv.cvaDelta.modifiedVariants.length === 0) {
+    reasons.push(
+      "only style / token differences \u2014 push to tokens.overrides.css"
+    );
+    return { recommendedModes: ["TokenOnly"], confidence: 0.8, reasons };
+  }
+  const modes = [];
+  let score = 0;
+  if (fv.cvaDelta.addedVariants.length > 0 || fv.cvaDelta.modifiedVariants.length > 0) {
+    modes.push("Variant");
+    reasons.push(
+      `cva variants delta: +${fv.cvaDelta.addedVariants.length} ~${fv.cvaDelta.modifiedVariants.length}`
+    );
+    score = Math.max(score, 0.7);
+  }
+  if (fv.logicDelta.hasState || fv.logicDelta.hasEffect || fv.logicDelta.hasExtraImports || fv.apiDelta.added.length > 0) {
+    modes.push("Wrapper");
+    reasons.push("user added state / effect / imports / props");
+    score = Math.max(score, 0.75);
+  }
+  if (apiNoChange && logicMinimal && !fv.styleDelta.classNameDiff && !fv.styleDelta.tokenUsageDiff && fv.cvaDelta.addedVariants.length === 0 && fv.cvaDelta.modifiedVariants.length === 0) {
+    modes.push("Preset");
+    reasons.push("no API/logic delta \u2014 Preset captures default-prop tweaks");
+    score = Math.max(score, 0.6);
+  }
+  if (fv.structureDelta.isComposition) {
+    modes.push("Compose");
+    reasons.push(
+      `composition of ${fv.structureDelta.atomicChildren.length} atomic children`
+    );
+    score = Math.max(score, 0.65);
+  }
+  if (modes.length === 0) {
+    reasons.push("no axis crossed the 0.6 threshold");
+    return { recommendedModes: ["ManualReview"], confidence: 0.4, reasons };
+  }
+  return { recommendedModes: modes, confidence: score, reasons };
+}
+function extractVariantBody(src, key) {
+  const block = extractVariantsBlock(src);
+  if (block === null) return "";
+  const re = new RegExp(`(?:["']?${key}["']?)\\s*:\\s*\\{`);
+  const idx = block.search(re);
+  if (idx < 0) return "";
+  const open = block.indexOf("{", idx);
+  if (open < 0) return "";
+  let depth = 0;
+  for (let i = open; i < block.length; i++) {
+    const c = block[i];
+    if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) return block.slice(open + 1, i);
+    }
+  }
+  return "";
+}
+function extractClassNameLiterals(src) {
+  const out = [];
+  for (const m of src.matchAll(/className\s*=\s*["'`]([^"'`]*)["'`]/g)) {
+    if (m[1]) out.push(m[1]);
+  }
+  for (const m of src.matchAll(/\b(?:cn|clsx|cva)\s*\(/g)) {
+    const open = (m.index ?? 0) + m[0].length - 1;
+    let depth = 1;
+    let i = open + 1;
+    for (; i < src.length && depth > 0; i++) {
+      const c = src[i];
+      if (c === "(") depth++;
+      else if (c === ")") depth--;
+    }
+    const body = src.slice(open + 1, i - 1);
+    for (const lit of body.matchAll(/["'`]([^"'`]*)["'`]/g)) {
+      if (lit[1]) out.push(lit[1]);
+    }
+  }
+  return out.sort().join("|");
+}
+function extractTokenRefs(src) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of src.matchAll(/var\(--([a-z0-9-]+)\)/g)) {
+    if (m[1]) out.add(m[1]);
+  }
+  for (const m of src.matchAll(/--([a-z][a-z0-9-]*)\s*:/g)) {
+    if (m[1]) out.add(m[1]);
+  }
+  return out;
+}
+function extractImportSources(src) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of src.matchAll(/^\s*import\b[^'"]*['"]([^'"]+)['"]/gm)) {
+    if (m[1]) out.add(m[1]);
+  }
+  return out;
+}
+function extractDefaultParamList(src) {
+  const m = /export\s+default\s+(?:async\s+)?function\s+\w*\s*\(([^)]*)\)/.exec(src) ?? /export\s+default\s+(?:\([^)]*\)|\w+)\s*=>/.exec(src) ?? /(?:const|function)\s+\w+\s*=?\s*(?:\(([^)]*)\)|\w+)\s*(?:=>|\{)/.exec(src);
+  return m?.[1]?.replace(/\s+/g, " ").trim() ?? "";
+}
 
 // src/core/ui-upgrade.ts
 var nodeRequire = createRequire6(import.meta.url);
 function resolvePackageRoot3(packageName) {
   const pkgJsonPath = nodeRequire.resolve(`${packageName}/package.json`);
-  return path21.dirname(pkgJsonPath);
+  return path23.dirname(pkgJsonPath);
 }
 async function runUiUpgrade(options) {
   const { projectRoot, category, ids = [], trigger } = options;
@@ -4116,7 +5021,7 @@ async function buildStaging(args) {
   }
   const bizRoot = args.bizUiPackageRoot ?? resolvePackageRoot3("@teamix-evo/biz-ui");
   const variant = lineageReport.installedVariant ?? "_flat";
-  const variantDir = path21.join(bizRoot, "variants", variant);
+  const variantDir = path23.join(bizRoot, "variants", variant);
   const variantManifest = await loadVariantUiPackageManifest(variantDir);
   const uiRoot = args.uiPackageRoot ?? resolvePackageRoot3("@teamix-evo/ui");
   const uiManifest = await loadUiPackageManifest2(uiRoot);
@@ -4168,7 +5073,7 @@ var META = {
 };
 function makeUpgradeCommand(category) {
   const meta = META[category];
-  return new Command18("upgrade").description(
+  return new Command19("upgrade").description(
     `\u4E3A ${category} \u7EC4\u4EF6\u751F\u6210\u5347\u7EA7 staging\uFF08\u4E0D\u5199 src\uFF0C\u9700\u901A\u8FC7 teamix-evo-upgrade skill \u5E94\u7528\uFF09`
   ).argument(
     "[ids...]",
@@ -4230,36 +5135,865 @@ function makeUpgradeCommand(category) {
           return;
         }
       }
-    } catch (err) {
+    } catch (err) {
+      logger.error(
+        `Failed to build ${category} staging: ${getErrorMessage(err)}`
+      );
+      logger.debug(err.stack ?? "");
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/commands/ui/upgrade.ts
+var upgradeCommand = makeUpgradeCommand("ui");
+
+// src/commands/ui/promote.ts
+import { Command as Command20 } from "commander";
+
+// src/core/ui-promote.ts
+import * as fs19 from "fs/promises";
+import * as path25 from "path";
+
+// src/core/ui-promote-imports.ts
+import * as fs18 from "fs/promises";
+import * as path24 from "path";
+var SOURCE_FILE_EXT = /\.(tsx?|jsx?|mts|cts)$/;
+var STATIC_IMPORT_FROM = /^(\s*(?:import|export)\s[\s\S]*?from\s+['"])([^'"\n]+)(['"])/;
+var SIDE_EFFECT_IMPORT = /^(\s*import\s+['"])([^'"\n]+)(['"])/;
+var DYNAMIC_IMPORT_STR = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+var DYNAMIC_IMPORT_TPL = /\bimport\s*\(\s*`/g;
+async function rewriteProjectImports(projectRoot, specs, options = {}) {
+  if (specs.length === 0) return { rewritten: [], skipped: [] };
+  const scanRoot = options.scanRoot ?? path24.join(projectRoot, "src");
+  const dryRun = options.dryRun ?? false;
+  const backup = options.backup ?? true;
+  const files = await collectTsFiles(scanRoot);
+  const rewritten = [];
+  const skipped = [];
+  for (const file of files) {
+    const raw = await readFileOrNull(file);
+    if (raw === null) continue;
+    const rel2 = toRel(projectRoot, file);
+    const lines = raw.split("\n");
+    let changed = false;
+    for (let i = 0; i < lines.length; i++) {
+      const orig = lines[i] ?? "";
+      const staticMatch = orig.match(STATIC_IMPORT_FROM);
+      if (staticMatch) {
+        const whole = staticMatch[0];
+        const prefix = staticMatch[1] ?? "";
+        const spec = staticMatch[2] ?? "";
+        const quote2 = staticMatch[3] ?? "";
+        const replaced = applySpecs(spec, specs);
+        if (replaced !== null) {
+          if (/^\s*export\s/.test(orig)) {
+            skipped.push({
+              file: rel2,
+              line: i + 1,
+              reason: "aliased-export",
+              snippet: orig.trim()
+            });
+            continue;
+          }
+          lines[i] = `${prefix}${replaced}${quote2}${orig.slice(whole.length)}`;
+          changed = true;
+        }
+        continue;
+      }
+      const sideMatch = orig.match(SIDE_EFFECT_IMPORT);
+      if (sideMatch) {
+        const whole = sideMatch[0];
+        const prefix = sideMatch[1] ?? "";
+        const spec = sideMatch[2] ?? "";
+        const quote2 = sideMatch[3] ?? "";
+        const replaced = applySpecs(spec, specs);
+        if (replaced !== null) {
+          lines[i] = `${prefix}${replaced}${quote2}${orig.slice(whole.length)}`;
+          changed = true;
+        }
+        continue;
+      }
+      for (const m of orig.matchAll(DYNAMIC_IMPORT_STR)) {
+        const target = m[1] ?? "";
+        if (specs.some((s) => isAffected(target, s.oldPath))) {
+          skipped.push({
+            file: rel2,
+            line: i + 1,
+            reason: "dynamic-import",
+            snippet: orig.trim()
+          });
+        }
+      }
+      if (DYNAMIC_IMPORT_TPL.test(orig)) {
+        skipped.push({
+          file: rel2,
+          line: i + 1,
+          reason: "string-template",
+          snippet: orig.trim()
+        });
+        DYNAMIC_IMPORT_TPL.lastIndex = 0;
+      }
+    }
+    if (changed) {
+      const updated = lines.join("\n");
+      if (!dryRun) {
+        if (backup) await backupFile(file, projectRoot);
+        await writeFileSafe(file, updated);
+      }
+      rewritten.push(rel2);
+    }
+  }
+  return { rewritten, skipped };
+}
+function applySpecs(target, specs) {
+  for (const s of specs) {
+    if (target === s.oldPath) return s.newPath;
+    if (target.startsWith(s.oldPath + "/")) {
+      return s.newPath + target.slice(s.oldPath.length);
+    }
+  }
+  return null;
+}
+function isAffected(target, oldPath) {
+  return target === oldPath || target.startsWith(oldPath + "/");
+}
+async function collectTsFiles(root) {
+  const out = [];
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await fs18.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === "ENOENT") return;
+      throw err;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".") || e.name === "node_modules" || e.name === "dist") {
+        continue;
+      }
+      const full = path24.join(dir, e.name);
+      if (e.isDirectory()) {
+        await walk(full);
+      } else if (e.isFile() && SOURCE_FILE_EXT.test(e.name)) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out;
+}
+function toRel(projectRoot, abs) {
+  return path24.relative(projectRoot, abs).split(path24.sep).join("/");
+}
+
+// src/core/ui-promote.ts
+var TEAMIX_DIR5 = ".teamix-evo";
+var STAGING_DIR2 = ".upgrade-staging";
+async function runUiPromote(options) {
+  const { projectRoot } = options;
+  const dryRun = options.dryRun ?? false;
+  const promotions = [];
+  const fileChanges = [];
+  const skipped = [];
+  const rewritten = [];
+  const config = await readProjectConfig(projectRoot);
+  if (!config?.packages?.ui?.aliases) {
+    return {
+      status: "not-initialized",
+      promotions,
+      fileChanges,
+      importRewrite: { rewritten, skipped }
+    };
+  }
+  const aliases = config.packages.ui.aliases;
+  const stagingDir = options.stagingDir ?? await findLatestUiStagingDir(projectRoot);
+  if (!stagingDir) {
+    return {
+      status: "no-staging",
+      promotions,
+      fileChanges,
+      importRewrite: { rewritten, skipped }
+    };
+  }
+  const meta = await readStagingMeta(stagingDir);
+  if (!meta || meta.entries.length === 0) {
+    return {
+      status: "no-entries",
+      stagingDir,
+      promotions,
+      fileChanges,
+      importRewrite: { rewritten, skipped }
+    };
+  }
+  const onlyIds = options.ids && options.ids.length > 0 ? new Set(options.ids) : null;
+  const targetEntries = onlyIds ? meta.entries.filter((e) => onlyIds.has(e.id)) : meta.entries;
+  const newResources = [];
+  for (const entry of targetEntries) {
+    const decision = decideModes(entry, options.modesOverride);
+    try {
+      const outcome = await promoteEntry({
+        projectRoot,
+        stagingDir,
+        entry,
+        modes: decision,
+        aliases,
+        keepOriginalNames: options.keepOriginalNames ?? false,
+        dryRun
+      });
+      promotions.push(outcome.promotion);
+      fileChanges.push(...outcome.fileChanges);
+      newResources.push(...outcome.newResources);
+      if (decision.includes("Coexist") && options.migrateImports && outcome.coexistRewriteSpec) {
+        const r = await rewriteProjectImports(
+          projectRoot,
+          [outcome.coexistRewriteSpec],
+          { dryRun, backup: true }
+        );
+        rewritten.push(...r.rewritten);
+        skipped.push(...r.skipped);
+        for (const rel2 of r.rewritten) {
+          fileChanges.push({
+            kind: "modified",
+            path: rel2,
+            step: "ui-promote-imports"
+          });
+        }
+      }
+    } catch (err) {
+      logger.error(`Promotion failed for ${entry.id}: ${getErrorMessage(err)}`);
+      promotions.push({
+        id: entry.id,
+        modes: decision,
+        status: "skipped",
+        outputs: [],
+        reason: getErrorMessage(err)
+      });
+    }
+  }
+  if (!dryRun && newResources.length > 0) {
+    await mergeIntoInstalledManifest2(projectRoot, newResources);
+  }
+  return {
+    status: "promoted",
+    stagingDir,
+    promotions,
+    fileChanges,
+    importRewrite: { rewritten, skipped }
+  };
+}
+async function promoteEntry(args) {
+  const { entry, modes, projectRoot, stagingDir, aliases, dryRun } = args;
+  const fileChanges = [];
+  const newResources = [];
+  let coexistRewriteSpec;
+  if (modes.includes("ManualReview")) {
+    return {
+      promotion: {
+        id: entry.id,
+        modes,
+        status: "manual-review",
+        outputs: [],
+        reason: "Confidence below threshold or fileType non-component \u2014 see staging meta.json"
+      },
+      fileChanges,
+      newResources
+    };
+  }
+  if (modes.includes("TokenOnly")) {
+    return {
+      promotion: {
+        id: entry.id,
+        modes,
+        status: "token-only",
+        outputs: [],
+        reason: "\u5DEE\u5F02\u4EC5\u9650 className/token \u2014 \u7F16\u8F91 tokens/tokens.overrides.css \u800C\u975E\u521B\u5EFA biz-ui \u6587\u4EF6"
+      },
+      fileChanges,
+      newResources
+    };
+  }
+  const currentSrc = await readStagedFile(stagingDir, entry, "current");
+  const incomingSrc = await readStagedFile(stagingDir, entry, "incoming");
+  const businessDir = path25.join(projectRoot, aliases.business);
+  const uiDir = path25.join(projectRoot, aliases.components);
+  const businessRel = aliases.business;
+  const uiRel = aliases.components;
+  if (modes.includes("Coexist")) {
+    if (!currentSrc) {
+      throw new Error("Coexist requires a current.tsx in staging");
+    }
+    if (!incomingSrc) {
+      throw new Error("Coexist requires an incoming.tsx in staging");
+    }
+    const legacyId = `legacy-${entry.id}`;
+    const legacyAbs = path25.join(businessDir, `${legacyId}.tsx`);
+    const uiAbs = path25.join(uiDir, `${entry.id}.tsx`);
+    if (await fileExists(uiAbs)) {
+      if (!dryRun) await backupFile(uiAbs, projectRoot);
+      fileChanges.push({
+        kind: "backed-up",
+        path: posix2(path25.relative(projectRoot, uiAbs)),
+        step: "ui-promote",
+        detail: "pre-coexist user version"
+      });
+    }
+    const renamed = args.keepOriginalNames ? currentSrc : prefixExportsLegacy(currentSrc, entry.id);
+    if (!dryRun) {
+      await ensureDir(businessDir);
+      await writeFileSafe(legacyAbs, renamed);
+    }
+    fileChanges.push({
+      kind: "created",
+      path: posix2(path25.join(businessRel, `${legacyId}.tsx`)),
+      step: "ui-promote",
+      detail: "Coexist legacy snapshot"
+    });
+    newResources.push({
+      id: `${legacyId}:${legacyId}.tsx`,
+      target: legacyAbs,
+      hash: computeHash(renamed),
+      strategy: "frozen"
+    });
+    if (!dryRun) await writeFileSafe(uiAbs, incomingSrc);
+    fileChanges.push({
+      kind: "modified",
+      path: posix2(path25.join(uiRel, `${entry.id}.tsx`)),
+      step: "ui-promote",
+      detail: "Coexist upstream restore"
+    });
+    coexistRewriteSpec = {
+      oldPath: importPathFor(uiRel, entry.id),
+      newPath: importPathFor(businessRel, legacyId)
+    };
+    return {
+      promotion: {
+        id: entry.id,
+        modes,
+        status: "promoted",
+        outputs: [
+          posix2(path25.join(businessRel, `${legacyId}.tsx`)),
+          posix2(path25.join(uiRel, `${entry.id}.tsx`))
+        ],
+        reason: "\u53CC\u8F68\uFF1Aupstream \u88C5\u56DE ui/\u3001\u7528\u6237\u7248\u6539\u540D\u8FDB business/legacy-"
+      },
+      fileChanges,
+      newResources,
+      coexistRewriteSpec
+    };
+  }
+  if (modes.includes("Fork")) {
+    if (!currentSrc) throw new Error("Fork requires a current.tsx in staging");
+    const forkAbs = path25.join(businessDir, `${entry.id}.tsx`);
+    if (await fileExists(forkAbs)) {
+      if (!dryRun) await backupFile(forkAbs, projectRoot);
+      fileChanges.push({
+        kind: "backed-up",
+        path: posix2(path25.relative(projectRoot, forkAbs)),
+        step: "ui-promote",
+        detail: "pre-fork existing business file"
+      });
+    }
+    if (!dryRun) {
+      await ensureDir(businessDir);
+      await writeFileSafe(forkAbs, currentSrc);
+    }
+    fileChanges.push({
+      kind: "created",
+      path: posix2(path25.join(businessRel, `${entry.id}.tsx`)),
+      step: "ui-promote",
+      detail: "Fork \u2014 full custom copy"
+    });
+    newResources.push({
+      id: `${entry.id}:${entry.id}.tsx`,
+      target: forkAbs,
+      hash: computeHash(currentSrc),
+      strategy: "frozen"
+    });
+    return {
+      promotion: {
+        id: entry.id,
+        modes,
+        status: "promoted",
+        outputs: [posix2(path25.join(businessRel, `${entry.id}.tsx`))],
+        reason: "Fork\uFF1A\u5B8C\u6574\u4FDD\u7559\u7528\u6237\u5B9E\u73B0"
+      },
+      fileChanges,
+      newResources
+    };
+  }
+  const businessAbs = path25.join(businessDir, `${entry.id}.tsx`);
+  const composedSource = composeBusinessFile({
+    id: entry.id,
+    modes,
+    aliases,
+    entry,
+    incomingSource: incomingSrc
+  });
+  if (await fileExists(businessAbs)) {
+    if (!dryRun) await backupFile(businessAbs, projectRoot);
+    fileChanges.push({
+      kind: "backed-up",
+      path: posix2(path25.relative(projectRoot, businessAbs)),
+      step: "ui-promote",
+      detail: "pre-promote business file"
+    });
+  }
+  if (!dryRun) {
+    await ensureDir(businessDir);
+    await writeFileSafe(businessAbs, composedSource);
+  }
+  fileChanges.push({
+    kind: "created",
+    path: posix2(path25.join(businessRel, `${entry.id}.tsx`)),
+    step: "ui-promote",
+    detail: `modes: ${modes.join("+")}`
+  });
+  newResources.push({
+    id: `${entry.id}:${entry.id}.tsx`,
+    target: businessAbs,
+    hash: computeHash(composedSource),
+    strategy: "frozen"
+  });
+  return {
+    promotion: {
+      id: entry.id,
+      modes,
+      status: "promoted",
+      outputs: [posix2(path25.join(businessRel, `${entry.id}.tsx`))],
+      reason: `modes: ${modes.join("+")} \u5DF2\u751F\u6210 business/${entry.id}.tsx`
+    },
+    fileChanges,
+    newResources
+  };
+}
+function composeBusinessFile(args) {
+  const { id, modes, aliases, entry } = args;
+  const componentName = pascalCase(id);
+  const upstreamImport = importPathFor(aliases.components, id);
+  const hasVariant = modes.includes("Variant");
+  const hasWrapper = modes.includes("Wrapper");
+  const hasPreset = modes.includes("Preset");
+  const hasCompose = modes.includes("Compose");
+  const banner = renderBanner({ id, modes, entry });
+  const importLines = [
+    `import * as React from 'react';`,
+    `import { ${componentName} as Base${componentName}, type ${componentName}Props as Base${componentName}Props } from '${upstreamImport}';`
+  ];
+  if (hasCompose && entry.promotion?.featureVector?.structureDelta?.atomicChildren) {
+    const children = entry.promotion.featureVector.structureDelta.atomicChildren.filter((c) => c !== componentName).slice(0, 4);
+    for (const child of children) {
+      importLines.push(
+        `// TODO: confirm import path for atomic child <${child} />`
+      );
+    }
+  }
+  const body = [];
+  body.push(
+    `export interface ${componentName}Props extends Base${componentName}Props {`
+  );
+  if (hasWrapper) {
+    body.push(
+      `  // TODO(Wrapper): add business-only props (e.g. loading?: boolean, confirm?: () => void)`
+    );
+  }
+  body.push(`}`);
+  body.push("");
+  if (hasVariant) {
+    body.push(
+      `// TODO(Variant): extend cva variants from upstream \u2014 when upstream`
+    );
+    body.push(
+      `// exports \`${id}Variants\`, import + spread it here; when not, copy the`
+    );
+    body.push(
+      `// configuration into this file and annotate \`SOURCE_OF_TRUTH\`.`
+    );
+    body.push("");
+  }
+  if (hasPreset) {
+    body.push(
+      `export const ${componentName}: React.FC<${componentName}Props> = ({`
+    );
+    body.push(
+      `  // TODO(Preset): fill defaults migrated from your previous user version,`
+    );
+    body.push(
+      `  //              e.g. \`size = 'md'\`, \`variant = 'primary'\`.`
+    );
+    body.push(`  ...props`);
+    body.push(`}) => {`);
+  } else {
+    body.push(
+      `export const ${componentName}: React.FC<${componentName}Props> = (props) => {`
+    );
+  }
+  if (hasWrapper) {
+    body.push(
+      `  // TODO(Wrapper): pull business state / effects out of props before rendering.`
+    );
+  }
+  if (hasCompose) {
+    body.push(
+      `  // TODO(Compose): assemble atomic children \u2014 ${entry.promotion?.featureVector?.structureDelta?.atomicChildren?.join(
+        ", "
+      ) ?? "..."}`
+    );
+  }
+  body.push(`  return <Base${componentName} {...props} />;`);
+  body.push(`};`);
+  return [banner, "", importLines.join("\n"), "", body.join("\n"), ""].join(
+    "\n"
+  );
+}
+function renderBanner(args) {
+  const reasons = args.entry.promotion?.reasons ?? [];
+  const lines = [
+    `/**`,
+    ` * Generated by \`teamix-evo ui promote-to-biz\` (Init landing plan \xA7C.3).`,
+    ` *`,
+    ` *   id     : ${args.id}`,
+    ` *   modes  : ${args.modes.join(" + ")}`,
+    ` *   note   : \u4E1A\u52A1\u5B9A\u5236\u5C42\uFF1B\u4E0A\u6E38 ui/${args.id}.tsx \u4ECD\u662F SOURCE_OF_TRUTH\uFF0C\u8BF7\u907F\u514D\u5728\u6B64\u518D\u6B21\u590D\u5236\u5176\u5185\u90E8\u7EC6\u8282\u3002`
+  ];
+  if (reasons.length > 0) {
+    lines.push(" *");
+    lines.push(" * \u63A8\u8350\u7406\u7531\uFF1A");
+    for (const r of reasons) lines.push(` *   \u2022 ${r}`);
+  }
+  lines.push(" */");
+  return lines.join("\n");
+}
+async function findLatestUiStagingDir(projectRoot) {
+  const base = path25.join(projectRoot, TEAMIX_DIR5, STAGING_DIR2);
+  let entries;
+  try {
+    entries = await fs19.readdir(base, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  const candidates = entries.filter((e) => e.isDirectory() && e.name.startsWith("ui-")).map((e) => e.name).sort();
+  const last = candidates[candidates.length - 1];
+  return last ? path25.join(base, last) : null;
+}
+async function readStagingMeta(stagingDir) {
+  const raw = await readFileOrNull(path25.join(stagingDir, "meta.json"));
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function readStagedFile(stagingDir, entry, kind) {
+  const ext = path25.extname(entry.current.target) || ".tsx";
+  const direct = path25.join(stagingDir, entry.id, `${kind}${ext}`);
+  const directRead = await readFileOrNull(direct);
+  if (directRead !== null) return directRead;
+  if (kind === "incoming" && entry.incoming?.relPath) {
+    return readFileOrNull(path25.join(stagingDir, entry.incoming.relPath));
+  }
+  return null;
+}
+function decideModes(entry, override) {
+  if (override && override.length > 0) return override;
+  const recommended = entry.promotion?.recommendedModes;
+  if (recommended && recommended.length > 0) return recommended;
+  return ["ManualReview"];
+}
+async function mergeIntoInstalledManifest2(projectRoot, newResources) {
+  const installed = await readInstalledManifest(
+    projectRoot
+  ) ?? { schemaVersion: 1, installed: [] };
+  const idx = installed.installed.findIndex(
+    (p2) => p2.package === "@teamix-evo/biz-ui-promoted"
+  );
+  const prior = idx >= 0 ? installed.installed[idx] : void 0;
+  const merged = /* @__PURE__ */ new Map();
+  for (const r of prior?.resources ?? []) merged.set(r.id, r);
+  for (const r of newResources) merged.set(r.id, r);
+  const next = {
+    package: "@teamix-evo/biz-ui-promoted",
+    variant: "_promoted",
+    version: "0.0.0",
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    resources: Array.from(merged.values())
+  };
+  if (idx >= 0) installed.installed[idx] = next;
+  else installed.installed.push(next);
+  await writeInstalledManifest(projectRoot, installed);
+}
+function prefixExportsLegacy(source, id) {
+  const stem = pascalCase(id);
+  const stemRe = new RegExp(`\\b${stem}([A-Z]\\w*)?\\b`, "g");
+  let out = source;
+  out = out.replace(
+    new RegExp(
+      `(\\bexport\\s+(?:const|let|var|function|class|interface|type|enum)\\s+)(${stem}[A-Z]?\\w*)\\b`,
+      "g"
+    ),
+    (_full, prefix, name) => `${prefix}Legacy${name}`
+  );
+  out = out.replace(/export\s*\{([^}]+)\}/g, (full, body) => {
+    const replacedBody = body.replace(stemRe, (m) => `Legacy${m}`);
+    return `export {${replacedBody}}`;
+  });
+  out = out.replace(
+    new RegExp(`(\\bexport\\s+default\\s+)(${stem}[A-Z]?\\w*)(\\s*;)`, "g"),
+    (_full, prefix, name, suffix) => `${prefix}Legacy${name}${suffix}`
+  );
+  out = out.replace(
+    new RegExp(
+      `(\\bexport\\s+default\\s+(?:function|class)\\s+)(${stem}[A-Z]?\\w*)\\b`,
+      "g"
+    ),
+    (_full, prefix, name) => `${prefix}Legacy${name}`
+  );
+  return out;
+}
+function pascalCase(id) {
+  return id.split(/[-_]/g).filter(Boolean).map((p2) => p2[0].toUpperCase() + p2.slice(1)).join("");
+}
+function importPathFor(aliasDir, id) {
+  const trimmed = aliasDir.replace(/^\.\//, "").replace(/\/$/, "");
+  const root = trimmed.startsWith("src/") ? `@/${trimmed.slice("src/".length)}` : `@/${trimmed}`;
+  return `${root}/${id}`;
+}
+function posix2(p2) {
+  return p2.split(path25.sep).join("/");
+}
+
+// src/core/file-changes.ts
+import * as fs20 from "fs/promises";
+import * as path26 from "path";
+function toRelativePosix(p2, projectRoot) {
+  let rel2 = p2;
+  if (path26.isAbsolute(p2)) {
+    rel2 = path26.relative(projectRoot, p2);
+  }
+  return rel2.split(path26.sep).join("/");
+}
+async function listBackupOriginals(projectRoot) {
+  const backupsDir = path26.join(projectRoot, ".teamix-evo", ".backups");
+  const out = /* @__PURE__ */ new Set();
+  const stack = [backupsDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fs20.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      throw err;
+    }
+    for (const e of entries) {
+      const full = path26.join(dir, e.name);
+      if (e.isDirectory()) {
+        stack.push(full);
+      } else if (e.isFile() && e.name.endsWith(".bak")) {
+        const rel2 = path26.relative(backupsDir, full);
+        const original = stripBackupSuffix(rel2);
+        if (original) out.add(original.split(path26.sep).join("/"));
+      }
+    }
+  }
+  return out;
+}
+function stripBackupSuffix(rel2) {
+  const m = rel2.match(
+    /^(.+)\.\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\.bak$/
+  );
+  return m?.[1] ?? null;
+}
+function diffBackupSet(before, after) {
+  const out = /* @__PURE__ */ new Set();
+  for (const p2 of after) {
+    if (!before.has(p2)) out.add(p2);
+  }
+  return out;
+}
+function formatFileChangeSummary(changes) {
+  if (changes.length === 0) return [];
+  const buckets = {
+    created: /* @__PURE__ */ new Map(),
+    modified: /* @__PURE__ */ new Map(),
+    "backed-up": /* @__PURE__ */ new Map(),
+    deleted: /* @__PURE__ */ new Map()
+  };
+  for (const c of changes) {
+    const existing = buckets[c.kind].get(c.path);
+    if (!existing) buckets[c.kind].set(c.path, c);
+  }
+  const order = [
+    ["created", "\u{1F195} \u65B0\u5EFA"],
+    ["modified", "\u270F\uFE0F  \u4FEE\u6539"],
+    ["backed-up", "\u{1F4BE} \u5DF2\u5907\u4EFD"],
+    ["deleted", "\u{1F5D1}  \u5220\u9664"]
+  ];
+  const lines = [];
+  for (const [kind, label] of order) {
+    const bucket = buckets[kind];
+    if (bucket.size === 0) continue;
+    lines.push(`${label}\uFF08${bucket.size}\uFF09\uFF1A`);
+    const sorted = [...bucket.values()].sort(
+      (a, b) => a.path.localeCompare(b.path)
+    );
+    for (const c of sorted) {
+      const detail = c.detail ? ` \u2014 ${c.detail}` : "";
+      lines.push(`  \u2022 ${c.path} [${c.step}]${detail}`);
+    }
+  }
+  return lines;
+}
+
+// src/commands/ui/promote.ts
+var VALID_MODES = [
+  "Coexist",
+  "Preset",
+  "Wrapper",
+  "Compose",
+  "Variant",
+  "Fork",
+  "TokenOnly",
+  "ManualReview"
+];
+var promoteCommand = new Command20("promote-to-biz").description(
+  "\u5C06 staging \u4E2D\u7684\u7EC4\u4EF6\u6309 8 \u6A21\u5F0F promote \u5230 src/components/business/\uFF08Init \u843D\u5730\u8BA1\u5212 \xA7C.3\uFF09"
+).argument("[ids...]", "\u53EF\u9009 entry id \u5217\u8868\uFF1B\u7701\u7565\u65F6\u5904\u7406 staging \u4E2D\u5168\u90E8\u6761\u76EE").option(
+  "--modes <list>",
+  '\u9017\u53F7\u5206\u9694\u7684\u6A21\u5F0F\u5217\u8868\uFF08\u8986\u76D6 staging \u63A8\u8350\uFF09\uFF0C\u5982 "Wrapper,Preset"'
+).option(
+  "--migrate-imports",
+  "Coexist \u6A21\u5F0F\u65F6\u540C\u6B65\u91CD\u5199 src/** \u4E2D ui/<id> import \u4E3A legacy-<id>"
+).option(
+  "--keep-original-names",
+  "Coexist \u6A21\u5F0F\u8DF3\u8FC7 Foo \u2192 LegacyFoo \u91CD\u547D\u540D\uFF08\u9ED8\u8BA4\u4F1A\u91CD\u547D\u540D\uFF09"
+).option("--dry-run", "\u53EA\u8F93\u51FA\u53D8\u66F4\u8BA1\u5212\uFF0C\u4E0D\u5199\u5165\u4EFB\u4F55\u6587\u4EF6").option(
+  "--staging-dir <path>",
+  "\u6307\u5B9A staging \u76EE\u5F55\uFF08\u9ED8\u8BA4\u4F7F\u7528 .teamix-evo/.upgrade-staging/ui-* \u4E2D\u6700\u65B0\u7684\uFF09"
+).action(async (ids, opts) => {
+  try {
+    const ide = detectIde();
+    const projectRoot = ide.getProjectRoot();
+    const modesOverride = parseModes(opts.modes);
+    const result = await runUiPromote({
+      projectRoot,
+      ids: ids ?? [],
+      modesOverride,
+      migrateImports: opts.migrateImports ?? false,
+      keepOriginalNames: opts.keepOriginalNames ?? false,
+      dryRun: opts.dryRun ?? false,
+      stagingDir: opts.stagingDir
+    });
+    renderResult(result, opts.dryRun ?? false);
+  } catch (err) {
+    logger.error(`promote-to-biz failed: ${getErrorMessage(err)}`);
+    logger.debug(err instanceof Error ? err.stack ?? "" : "");
+    process.exitCode = 1;
+  }
+});
+function parseModes(raw) {
+  if (!raw || raw.trim().length === 0) return void 0;
+  const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  const out = [];
+  for (const p2 of parts) {
+    const match = VALID_MODES.find((m) => m.toLowerCase() === p2.toLowerCase());
+    if (!match) {
+      throw new Error(`Unknown mode "${p2}". Valid: ${VALID_MODES.join(", ")}`);
+    }
+    out.push(match);
+  }
+  return out;
+}
+function renderResult(result, dryRun) {
+  switch (result.status) {
+    case "not-initialized":
+      logger.error("UI not initialized. Run `npx teamix-evo ui init` first.");
+      process.exitCode = 1;
+      return;
+    case "no-staging":
       logger.error(
-        `Failed to build ${category} staging: ${getErrorMessage(err)}`
+        "No `ui-*` staging dir found under `.teamix-evo/.upgrade-staging/`. Run `teamix-evo ui upgrade` first."
       );
-      logger.debug(err.stack ?? "");
       process.exitCode = 1;
+      return;
+    case "no-entries":
+      logger.warn(`Staging dir is empty: ${result.stagingDir}`);
+      return;
+    case "promoted":
+      break;
+  }
+  const promoted = result.promotions.filter((p2) => p2.status === "promoted");
+  const manual = result.promotions.filter((p2) => p2.status === "manual-review");
+  const tokenOnly = result.promotions.filter((p2) => p2.status === "token-only");
+  const failed = result.promotions.filter((p2) => p2.status === "skipped");
+  logger.success(
+    `${dryRun ? "[dry-run] " : ""}promote-to-biz complete: ${promoted.length} promoted, ${manual.length} manual-review, ${tokenOnly.length} token-only, ${failed.length} skipped.`
+  );
+  logger.info("");
+  if (promoted.length > 0) {
+    logger.info("Promoted:");
+    for (const p2 of promoted) {
+      logger.info(`  \u2022 ${p2.id} [${p2.modes.join("+")}]`);
+      for (const out of p2.outputs) logger.info(`      \u2192 ${out}`);
+      if (p2.reason) logger.info(`      ${p2.reason}`);
     }
-  });
+    logger.info("");
+  }
+  if (manual.length > 0) {
+    logger.info("Manual review needed (no file written):");
+    for (const p2 of manual) logger.info(`  \u2022 ${p2.id} \u2014 ${p2.reason ?? ""}`);
+    logger.info("");
+  }
+  if (tokenOnly.length > 0) {
+    logger.info("Token-only (edit tokens.overrides.css instead):");
+    for (const p2 of tokenOnly) logger.info(`  \u2022 ${p2.id}`);
+    logger.info("");
+  }
+  if (failed.length > 0) {
+    logger.warn("Failed:");
+    for (const p2 of failed) logger.warn(`  \u2022 ${p2.id} \u2014 ${p2.reason ?? ""}`);
+    logger.info("");
+  }
+  if (result.importRewrite.rewritten.length > 0) {
+    logger.info(
+      `Import rewrite: ${result.importRewrite.rewritten.length} file(s) updated under src/**.`
+    );
+  }
+  if (result.importRewrite.skipped.length > 0) {
+    logger.warn("Manual import fix needed (could not be rewritten safely):");
+    for (const s of result.importRewrite.skipped) {
+      logger.warn(`  \u2022 ${s.file}:${s.line} [${s.reason}] \u2014 ${s.snippet}`);
+    }
+    logger.info("");
+  }
+  if (result.fileChanges.length > 0) {
+    logger.info("\u6587\u4EF6\u53D8\u66F4\uFF1A");
+    for (const line of formatFileChangeSummary(result.fileChanges)) {
+      logger.info(`  ${line}`);
+    }
+  }
 }
 
-// src/commands/ui/upgrade.ts
-var upgradeCommand = makeUpgradeCommand("ui");
-
 // src/commands/ui/index.ts
-var uiCommand = new Command19("ui").description(
+var uiCommand = new Command21("ui").description(
   "\u7BA1\u7406 teamix-evo ui \u7EC4\u4EF6\uFF08\u6E90\u7801\u6CE8\u5165\u5F0F\u5B89\u88C5\uFF0Cshadcn \u98CE\u683C\uFF09"
 );
 uiCommand.addCommand(initCommand3);
 uiCommand.addCommand(addCommand2);
 uiCommand.addCommand(listCommand3);
 uiCommand.addCommand(upgradeCommand);
+uiCommand.addCommand(promoteCommand);
 
 // src/commands/biz-ui/index.ts
-import { Command as Command23 } from "commander";
+import { Command as Command25 } from "commander";
 
 // src/commands/biz-ui/add.ts
-import { Command as Command20 } from "commander";
+import { Command as Command22 } from "commander";
 
 // src/core/variant-ui-add.ts
-import * as path22 from "path";
+import * as path27 from "path";
 import { createRequire as createRequire7 } from "module";
 import {
   loadUiPackageManifest as loadUiPackageManifest3,
@@ -4269,7 +6003,7 @@ import {
 var require7 = createRequire7(import.meta.url);
 function resolvePackageRoot4(packageName) {
   const pkgJsonPath = require7.resolve(`${packageName}/package.json`);
-  return path22.dirname(pkgJsonPath);
+  return path27.dirname(pkgJsonPath);
 }
 async function runVariantUiAdd(packageName, options) {
   const { projectRoot, variant, ids, overwrite } = options;
@@ -4292,7 +6026,7 @@ async function runVariantUiAdd(packageName, options) {
       `Variant "${variant}" not found in ${fullPackageName}. Known variants: ${known}. Hint: \`teamix-evo ${packageName} list-variants\` shows all.`
     );
   }
-  const variantDir = path22.join(packageRoot, "variants", variant);
+  const variantDir = path27.join(packageRoot, "variants", variant);
   const variantManifest = await loadVariantUiPackageManifest2(variantDir);
   const knownIds = new Set(variantManifest.entries.map((e) => e.id));
   const unknown = ids.filter((id) => !knownIds.has(id));
@@ -4339,7 +6073,7 @@ async function runVariantUiAdd(packageName, options) {
     (p2) => p2.package === fullPackageName && p2.variant === variant
   );
   const prior = idx >= 0 ? installed.installed[idx] : null;
-  const mergedResources = mergeResources2(
+  const mergedResources = mergeResources3(
     prior?.resources ?? [],
     result.resources
   );
@@ -4363,7 +6097,7 @@ async function runVariantUiAdd(packageName, options) {
     resources: result.resources
   };
 }
-function mergeResources2(prior, next) {
+function mergeResources3(prior, next) {
   const merged = /* @__PURE__ */ new Map();
   for (const r of prior) merged.set(r.id, r);
   for (const r of next) merged.set(r.id, r);
@@ -4405,7 +6139,7 @@ async function listVariantUiEntries(packageName, variant, packageRoot) {
       `Variant "${variant}" not found in ${fullPackageName}. Known: ${known}.`
     );
   }
-  const variantDir = path22.join(root, "variants", variant);
+  const variantDir = path27.join(root, "variants", variant);
   const variantManifest = await loadVariantUiPackageManifest2(variantDir);
   return {
     packageName: fullPackageName,
@@ -4427,7 +6161,7 @@ async function listTemplatesEntries(variant, packageRoot) {
 }
 
 // src/commands/biz-ui/add.ts
-var addCommand3 = new Command20("add").description(
+var addCommand3 = new Command22("add").description(
   "\u5B89\u88C5\u4E00\u4E2A\u6216\u591A\u4E2A\u4E1A\u52A1 UI \u7EC4\u4EF6(\u6309 id,\u81EA\u52A8\u5C55\u5F00 ui \u5305\u7684 registryDependencies)"
 ).argument("<ids...>", '\u7EC4\u4EF6 id \u5217\u8868,\u5982 "tenant-switcher" "org-picker"').option("--variant <name>", '\u53D8\u4F53 id(\u5FC5\u586B,\u5982 "opentrek"\u3001"uni-manager")').option("--overwrite", "\u5373\u4F7F\u76EE\u6807\u6587\u4EF6\u5DF2\u5B58\u5728\u4E5F\u8986\u76D6").action(
   async (ids, opts) => {
@@ -4478,8 +6212,8 @@ var addCommand3 = new Command20("add").description(
 );
 
 // src/commands/biz-ui/list.ts
-import { Command as Command21 } from "commander";
-var listCommand4 = new Command21("list").description("\u5217\u51FA\u6307\u5B9A\u53D8\u4F53\u4E0B\u7684 biz-ui entries").requiredOption("--variant <name>", "\u53D8\u4F53\u540D\uFF08\u5982 opentrek / uni-manager\uFF09").action(async (opts) => {
+import { Command as Command23 } from "commander";
+var listCommand4 = new Command23("list").description("\u5217\u51FA\u6307\u5B9A\u53D8\u4F53\u4E0B\u7684 biz-ui entries").requiredOption("--variant <name>", "\u53D8\u4F53\u540D\uFF08\u5982 opentrek / uni-manager\uFF09").action(async (opts) => {
   try {
     const result = await listBizUiEntries(opts.variant);
     logger.info(`${result.packageName}#${result.variant} entries:`);
@@ -4504,8 +6238,8 @@ var listCommand4 = new Command21("list").description("\u5217\u51FA\u6307\u5B9A\u
 });
 
 // src/commands/biz-ui/list-variants.ts
-import { Command as Command22 } from "commander";
-var listVariantsCommand2 = new Command22("list-variants").description("\u5217\u51FA @teamix-evo/biz-ui \u5305\u5185\u63D0\u4F9B\u7684\u6240\u6709\u4E1A\u52A1\u53D8\u4F53").action(async () => {
+import { Command as Command24 } from "commander";
+var listVariantsCommand2 = new Command24("list-variants").description("\u5217\u51FA @teamix-evo/biz-ui \u5305\u5185\u63D0\u4F9B\u7684\u6240\u6709\u4E1A\u52A1\u53D8\u4F53").action(async () => {
   try {
     const result = await listBizUiVariants();
     logger.info(`Available biz-ui variants in ${result.packageName}:`);
@@ -4532,7 +6266,7 @@ var listVariantsCommand2 = new Command22("list-variants").description("\u5217\u5
 var upgradeCommand2 = makeUpgradeCommand("biz-ui");
 
 // src/commands/biz-ui/index.ts
-var bizUiCommand = new Command23("biz-ui").description(
+var bizUiCommand = new Command25("biz-ui").description(
   "\u7BA1\u7406\u4E1A\u52A1 UI \u7EC4\u4EF6(\u53D8\u4F53\u611F\u77E5 \u2014 \u4E0E design / templates \u540C\u53D8\u4F53\u540D\u7A7A\u95F4)"
 );
 bizUiCommand.addCommand(addCommand3);
@@ -4541,11 +6275,11 @@ bizUiCommand.addCommand(listVariantsCommand2);
 bizUiCommand.addCommand(upgradeCommand2);
 
 // src/commands/templates/index.ts
-import { Command as Command27 } from "commander";
+import { Command as Command29 } from "commander";
 
 // src/commands/templates/add.ts
-import { Command as Command24 } from "commander";
-var addCommand4 = new Command24("add").description(
+import { Command as Command26 } from "commander";
+var addCommand4 = new Command26("add").description(
   "\u5B89\u88C5\u4E00\u4E2A\u6216\u591A\u4E2A\u9875\u9762\u6A21\u677F(\u6309 id,\u81EA\u52A8\u5C55\u5F00 ui \u5305\u7684 registryDependencies)"
 ).argument("<ids...>", '\u6A21\u677F id \u5217\u8868,\u5982 "list-detail-page"').option("--variant <name>", '\u53D8\u4F53 id(\u5FC5\u586B,\u5982 "opentrek"\u3001"uni-manager")').option("--overwrite", "\u5373\u4F7F\u76EE\u6807\u6587\u4EF6\u5DF2\u5B58\u5728\u4E5F\u8986\u76D6").action(
   async (ids, opts) => {
@@ -4596,8 +6330,8 @@ var addCommand4 = new Command24("add").description(
 );
 
 // src/commands/templates/list.ts
-import { Command as Command25 } from "commander";
-var listCommand5 = new Command25("list").description("\u5217\u51FA\u6307\u5B9A\u53D8\u4F53\u4E0B\u7684 templates entries").requiredOption("--variant <name>", "\u53D8\u4F53\u540D\uFF08\u5982 opentrek / uni-manager\uFF09").action(async (opts) => {
+import { Command as Command27 } from "commander";
+var listCommand5 = new Command27("list").description("\u5217\u51FA\u6307\u5B9A\u53D8\u4F53\u4E0B\u7684 templates entries").requiredOption("--variant <name>", "\u53D8\u4F53\u540D\uFF08\u5982 opentrek / uni-manager\uFF09").action(async (opts) => {
   try {
     const result = await listTemplatesEntries(opts.variant);
     logger.info(`${result.packageName}#${result.variant} entries:`);
@@ -4622,8 +6356,8 @@ var listCommand5 = new Command25("list").description("\u5217\u51FA\u6307\u5B9A\u
 });
 
 // src/commands/templates/list-variants.ts
-import { Command as Command26 } from "commander";
-var listVariantsCommand3 = new Command26("list-variants").description("\u5217\u51FA @teamix-evo/templates \u5305\u5185\u63D0\u4F9B\u7684\u6240\u6709\u9875\u9762\u6A21\u677F\u53D8\u4F53").action(async () => {
+import { Command as Command28 } from "commander";
+var listVariantsCommand3 = new Command28("list-variants").description("\u5217\u51FA @teamix-evo/templates \u5305\u5185\u63D0\u4F9B\u7684\u6240\u6709\u9875\u9762\u6A21\u677F\u53D8\u4F53").action(async () => {
   try {
     const result = await listTemplatesVariants();
     logger.info(`Available templates variants in ${result.packageName}:`);
@@ -4647,7 +6381,7 @@ var listVariantsCommand3 = new Command26("list-variants").description("\u5217\u5
 });
 
 // src/commands/templates/index.ts
-var templatesCommand = new Command27("templates").description(
+var templatesCommand = new Command29("templates").description(
   "\u7BA1\u7406\u9875\u9762\u6A21\u677F(\u53D8\u4F53\u611F\u77E5 \u2014 \u4E0E design / biz-ui \u540C\u53D8\u4F53\u540D\u7A7A\u95F4)"
 );
 templatesCommand.addCommand(addCommand4);
@@ -4655,16 +6389,16 @@ templatesCommand.addCommand(listCommand5);
 templatesCommand.addCommand(listVariantsCommand3);
 
 // src/commands/logs/index.ts
-import { Command as Command30 } from "commander";
+import { Command as Command32 } from "commander";
 
 // src/commands/logs/analyze.ts
-import { Command as Command28 } from "commander";
+import { Command as Command30 } from "commander";
 import { existsSync as existsSync2 } from "fs";
-import { resolve as resolve4, join as join22 } from "path";
+import { resolve as resolve5, join as join27 } from "path";
 
 // src/commands/logs/_io.ts
 import { readFileSync, readdirSync, statSync } from "fs";
-import { join as join21 } from "path";
+import { join as join26 } from "path";
 var DATE_DIR_RE = /^\d{4}-\d{2}-\d{2}$/;
 function parseIntOrUndef(v) {
   if (v === void 0) return void 0;
@@ -4676,7 +6410,7 @@ function readRecords(baseDir, dayLimit) {
   const selected = dayLimit !== void 0 ? dayDirs.slice(0, dayLimit) : dayDirs;
   const records = [];
   for (const day of selected) {
-    const dayPath = join21(baseDir, day);
+    const dayPath = join26(baseDir, day);
     let entries;
     try {
       entries = readdirSync(dayPath);
@@ -4685,7 +6419,7 @@ function readRecords(baseDir, dayLimit) {
     }
     for (const entry of entries) {
       if (!entry.endsWith(".jsonl")) continue;
-      const fp = join21(dayPath, entry);
+      const fp = join26(dayPath, entry);
       try {
         if (!statSync(fp).isFile()) continue;
       } catch {
@@ -4705,14 +6439,14 @@ function readRecords(baseDir, dayLimit) {
 }
 
 // src/commands/logs/analyze.ts
-var logsAnalyzeCommand = new Command28("analyze").description(
+var logsAnalyzeCommand = new Command30("analyze").description(
   "\u6C47\u603B vibe-logger \u8F93\u51FA (.teamix-evo/logs/ai/**/*.jsonl) \u2014 \u5DE5\u5177 / \u5305\u6807\u7B7E / MCP \u8C03\u7528\u9891\u7387,\u8F85\u52A9\u751F\u6001\u4F18\u5316"
 ).option("--dir <path>", "log \u76EE\u5F55 (\u9ED8\u8BA4 <project>/.teamix-evo/logs/ai)").option(
   "--days <n>",
   "\u53EA\u770B\u6700\u8FD1 N \u5929\u7684\u76EE\u5F55 (\u9ED8\u8BA4\u5168\u90E8;\u6309\u76EE\u5F55\u540D YYYY-MM-DD \u6BD4\u5BF9,\u4E0D\u89E3\u6790\u8BB0\u5F55 ts)"
 ).option("--top <n>", "\u6BCF\u4E2A\u6392\u884C\u5C55\u793A\u524D N \u9879 (\u9ED8\u8BA4 10)", "10").option("--json", "\u4EE5 JSON \u8F93\u51FA (CI/\u5DE5\u5177\u53CB\u597D)").action((opts) => {
-  const baseDir = resolve4(
-    opts.dir ?? join22(process.cwd(), ".teamix-evo", "logs", "ai")
+  const baseDir = resolve5(
+    opts.dir ?? join27(process.cwd(), ".teamix-evo", "logs", "ai")
   );
   if (!existsSync2(baseDir)) {
     logger.warn(`No log directory at ${baseDir}.`);
@@ -4854,14 +6588,14 @@ function pad(n, width) {
 }
 
 // src/commands/logs/trace.ts
-import { Command as Command29 } from "commander";
+import { Command as Command31 } from "commander";
 import { existsSync as existsSync3 } from "fs";
-import { resolve as resolve5, join as join23 } from "path";
-var logsTraceCommand = new Command29("trace").description(
+import { resolve as resolve6, join as join28 } from "path";
+var logsTraceCommand = new Command31("trace").description(
   "\u6309\u4F1A\u8BDD\u8FD8\u539F AI \u8C03\u7528\u94FE\u8DEF:\u4ECE\u7528\u6237 prompt \u8D77\u59CB,\u4E32\u8054\u540E\u7EED PreToolUse/PostToolUse \u76F4\u5230\u4E0B\u4E00\u4E2A prompt \u6216 Stop"
 ).option("--prompt <keyword>", "\u6309\u7528\u6237\u8F93\u5165\u5173\u952E\u5B57\u8FC7\u6EE4 (\u5B50\u4E32\u5339\u914D,\u4E0D\u533A\u5206\u5927\u5C0F\u5199)").option("--session <id>", "\u6307\u5B9A\u4F1A\u8BDD ID (\u524D\u7F00\u5339\u914D)").option("--days <n>", "\u53EA\u770B\u6700\u8FD1 N \u5929\u7684\u76EE\u5F55 (\u9ED8\u8BA4 7)", "7").option("--dir <path>", "log \u76EE\u5F55 (\u9ED8\u8BA4 <project>/.teamix-evo/logs/ai)").option("--json", "\u4EE5 JSON \u8F93\u51FA (CI/\u5DE5\u5177\u53CB\u597D)").action((opts) => {
-  const baseDir = resolve5(
-    opts.dir ?? join23(process.cwd(), ".teamix-evo", "logs", "ai")
+  const baseDir = resolve6(
+    opts.dir ?? join28(process.cwd(), ".teamix-evo", "logs", "ai")
   );
   if (!existsSync3(baseDir)) {
     logger.warn(`No log directory at ${baseDir}.`);
@@ -5030,22 +6764,22 @@ function padLeft(s, n) {
 }
 
 // src/commands/logs/index.ts
-var logsCommand = new Command30("logs").description(
+var logsCommand = new Command32("logs").description(
   "\u67E5\u8BE2 vibe-logger \u8F93\u51FA (.teamix-evo/logs/ai/**/*.jsonl) \u2014 AI \u8C03\u7528\u94FE\u5206\u6790"
 );
 logsCommand.addCommand(logsAnalyzeCommand);
 logsCommand.addCommand(logsTraceCommand);
 
 // src/commands/lint/index.ts
-import { Command as Command32 } from "commander";
+import { Command as Command34 } from "commander";
 
 // src/commands/lint/init.ts
-import { Command as Command31 } from "commander";
+import { Command as Command33 } from "commander";
 import * as prompts6 from "@clack/prompts";
 
 // src/core/lint-init.ts
-import * as path23 from "path";
-import * as fs16 from "fs";
+import * as path28 from "path";
+import * as fs21 from "fs";
 import { execa } from "execa";
 var ESLINT_CONFIG_CONTENT = `/**
  * teamix-evo consumer ESLint preset \u2014 9 token-discipline rules.
@@ -5072,18 +6806,29 @@ var ESLINT_DEPS = [
 ];
 var STYLELINT_DEPS = ["@teamix-evo/stylelint-config", "stylelint"];
 async function runLintInit(options) {
-  const { projectRoot, skipInstall } = options;
-  const eslintConfigPath = path23.join(projectRoot, "eslint.config.js");
-  const stylelintConfigPath = path23.join(projectRoot, "stylelint.config.cjs");
-  const eslintExists = await fileExists(eslintConfigPath);
-  const stylelintExists = await fileExists(stylelintConfigPath);
-  if (eslintExists && stylelintExists) {
+  const {
+    projectRoot,
+    skipInstall,
+    eslintStrategy = "overwrite",
+    stylelintStrategy = "overwrite",
+    eslintExistingPaths = [],
+    stylelintExistingPaths = []
+  } = options;
+  const eslintConfigPath = path28.join(projectRoot, "eslint.config.js");
+  const stylelintConfigPath = path28.join(projectRoot, "stylelint.config.cjs");
+  const eslintTemplateExists = await fileExists(eslintConfigPath);
+  const stylelintTemplateExists = await fileExists(stylelintConfigPath);
+  const eslintSkipRequested = eslintStrategy === "skip" && eslintExistingPaths.length > 0;
+  const stylelintSkipRequested = stylelintStrategy === "skip" && stylelintExistingPaths.length > 0;
+  const eslintNeedsWrite = !eslintTemplateExists && !eslintSkipRequested;
+  const stylelintNeedsWrite = !stylelintTemplateExists && !stylelintSkipRequested;
+  if (!eslintNeedsWrite && !stylelintNeedsWrite) {
     return { status: "already-initialized" };
   }
   if (!skipInstall) {
     const depsToInstall = [
-      ...eslintExists ? [] : ESLINT_DEPS,
-      ...stylelintExists ? [] : STYLELINT_DEPS
+      ...eslintNeedsWrite ? ESLINT_DEPS : [],
+      ...stylelintNeedsWrite ? STYLELINT_DEPS : []
     ];
     if (depsToInstall.length > 0) {
       const pm = detectPm(projectRoot);
@@ -5092,39 +6837,54 @@ async function runLintInit(options) {
       await execa(pm, args, { cwd: projectRoot, stdio: "inherit" });
     }
   }
+  if (eslintNeedsWrite && eslintExistingPaths.length > 0) {
+    for (const rel2 of eslintExistingPaths) {
+      await backupFile(path28.join(projectRoot, rel2), projectRoot);
+    }
+  }
+  if (stylelintNeedsWrite && stylelintExistingPaths.length > 0) {
+    for (const rel2 of stylelintExistingPaths) {
+      await backupFile(path28.join(projectRoot, rel2), projectRoot);
+    }
+  }
   let wroteEslint = false;
   let wroteStylelint = false;
-  if (!eslintExists) {
+  if (eslintNeedsWrite) {
     await writeFileSafe(eslintConfigPath, ESLINT_CONFIG_CONTENT);
     logger.debug(`Wrote eslint.config.js \u2192 ${eslintConfigPath}`);
     wroteEslint = true;
   }
-  if (!stylelintExists) {
+  if (stylelintNeedsWrite) {
     await writeFileSafe(stylelintConfigPath, STYLELINT_CONFIG_CONTENT);
     logger.debug(`Wrote stylelint.config.cjs \u2192 ${stylelintConfigPath}`);
     wroteStylelint = true;
   }
-  await patchPackageJsonScripts(projectRoot);
+  const packageJsonPatched = await patchPackageJsonScripts(projectRoot);
   return {
     status: "installed",
     eslint: wroteEslint,
-    stylelint: wroteStylelint
+    stylelint: wroteStylelint,
+    eslintMergeRequested: wroteEslint && eslintStrategy === "merge" && eslintExistingPaths.length > 0,
+    stylelintMergeRequested: wroteStylelint && stylelintStrategy === "merge" && stylelintExistingPaths.length > 0,
+    eslintSkipped: eslintSkipRequested,
+    stylelintSkipped: stylelintSkipRequested,
+    packageJsonPatched
   };
 }
 function detectPm(projectRoot) {
-  if (fs16.existsSync(path23.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs16.existsSync(path23.join(projectRoot, "yarn.lock"))) return "yarn";
+  if (fs21.existsSync(path28.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs21.existsSync(path28.join(projectRoot, "yarn.lock"))) return "yarn";
   return "npm";
 }
 async function patchPackageJsonScripts(projectRoot) {
-  const pkgPath = path23.join(projectRoot, "package.json");
+  const pkgPath = path28.join(projectRoot, "package.json");
   const raw = await readFileOrNull(pkgPath);
-  if (!raw) return;
+  if (!raw) return false;
   let pkg;
   try {
     pkg = JSON.parse(raw);
   } catch {
-    return;
+    return false;
   }
   const scripts = pkg.scripts ?? {};
   let changed = false;
@@ -5137,14 +6897,16 @@ async function patchPackageJsonScripts(projectRoot) {
     changed = true;
   }
   if (changed) {
+    await backupFile(pkgPath, projectRoot);
     pkg.scripts = scripts;
     await writeFileSafe(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
     logger.debug("Patched package.json scripts with lint / lint:css");
   }
+  return changed;
 }
 
 // src/commands/lint/init.ts
-var initCommand4 = new Command31("init").description(
+var initCommand4 = new Command33("init").description(
   "\u521D\u59CB\u5316 ESLint + Stylelint \u5DE5\u7A0B\u89C4\u8303\uFF08\u5B89\u88C5\u4F9D\u8D56 + \u751F\u6210\u914D\u7F6E\u6587\u4EF6 + \u6CE8\u5165 scripts\uFF09"
 ).option("-y, --yes", "\u8DF3\u8FC7\u786E\u8BA4\uFF0C\u76F4\u63A5\u6267\u884C").action(async (opts) => {
   try {
@@ -5192,18 +6954,18 @@ var initCommand4 = new Command31("init").description(
 });
 
 // src/commands/lint/index.ts
-var lintCommand = new Command32("lint").description(
+var lintCommand = new Command34("lint").description(
   "\u7BA1\u7406\u5DE5\u7A0B\u89C4\u8303\uFF08ESLint + Stylelint token-discipline \u89C4\u5219\u96C6\uFF09"
 );
 lintCommand.addCommand(initCommand4);
 
 // src/commands/init/index.ts
-import { Command as Command33 } from "commander";
-import * as path29 from "path";
+import { Command as Command35 } from "commander";
+import * as path35 from "path";
 
 // src/core/init-detect.ts
-import * as fs17 from "fs/promises";
-import * as path24 from "path";
+import * as fs22 from "fs/promises";
+import * as path29 from "path";
 var IGNORED_TOP_LEVEL = /* @__PURE__ */ new Set([
   ".git",
   ".gitignore",
@@ -5223,7 +6985,7 @@ var IGNORED_TOP_LEVEL = /* @__PURE__ */ new Set([
   "LICENSE.txt"
 ]);
 async function detectProjectState(cwd) {
-  const absCwd = path24.resolve(cwd);
+  const absCwd = path29.resolve(cwd);
   const teamixDir = getTeamixDir(absCwd);
   const hasTeamixDir = await fileExists(teamixDir);
   if (hasTeamixDir) {
@@ -5231,13 +6993,13 @@ async function detectProjectState(cwd) {
       state: "teamix-evo-installed",
       cwd: absCwd,
       hasTeamixDir: true,
-      hasPackageJson: await fileExists(path24.join(absCwd, "package.json")),
+      hasPackageJson: await fileExists(path29.join(absCwd, "package.json")),
       significantEntries: []
     };
   }
   let entries;
   try {
-    entries = await fs17.readdir(absCwd);
+    entries = await fs22.readdir(absCwd);
   } catch (err) {
     if (err.code === "ENOENT") {
       return {
@@ -5272,8 +7034,8 @@ async function detectProjectState(cwd) {
 
 // src/core/init-conflicts.ts
 import * as crypto from "crypto";
-import * as fs18 from "fs/promises";
-import * as path25 from "path";
+import * as fs23 from "fs/promises";
+import * as path30 from "path";
 var TAILWIND_CONFIG_CANDIDATES = [
   "tailwind.config.ts",
   "tailwind.config.js",
@@ -5295,9 +7057,29 @@ var INDEX_CSS_CANDIDATES = [
 ];
 var SHADCN_FILE_CANDIDATES = ["src/lib/utils.ts"];
 var SHADCN_DIR_CANDIDATES = ["src/components/ui"];
+var ESLINT_CONFIG_CANDIDATES = [
+  ".eslintrc.cjs",
+  ".eslintrc.js",
+  ".eslintrc.json",
+  ".eslintrc.yml",
+  "eslint.config.js",
+  "eslint.config.cjs",
+  "eslint.config.mjs",
+  "eslint.config.ts"
+];
+var STYLELINT_CONFIG_CANDIDATES = [
+  ".stylelintrc.cjs",
+  ".stylelintrc.js",
+  ".stylelintrc.json",
+  ".stylelintrc.yml",
+  "stylelint.config.cjs",
+  "stylelint.config.js",
+  "stylelint.config.mjs",
+  "stylelint.config.ts"
+];
 async function isDir(target) {
   try {
-    const stat7 = await fs18.stat(target);
+    const stat7 = await fs23.stat(target);
     return stat7.isDirectory();
   } catch {
     return false;
@@ -5305,7 +7087,7 @@ async function isDir(target) {
 }
 async function dirHasContent(target) {
   try {
-    const entries = await fs18.readdir(target);
+    const entries = await fs23.readdir(target);
     return entries.length > 0;
   } catch {
     return false;
@@ -5317,7 +7099,7 @@ function fingerprint(parts) {
   return `sha256:${hash.digest("hex").slice(0, 16)}`;
 }
 async function readPackageJson(cwd) {
-  const raw = await readFileOrNull(path25.join(cwd, "package.json"));
+  const raw = await readFileOrNull(path30.join(cwd, "package.json"));
   if (raw === null) return null;
   try {
     return JSON.parse(raw);
@@ -5337,7 +7119,7 @@ function detectTailwindMajor(pkg) {
   return null;
 }
 async function detectAgentsMd(cwd) {
-  const target = path25.join(cwd, "AGENTS.md");
+  const target = path30.join(cwd, "AGENTS.md");
   const content = await readFileOrNull(target);
   const exists = content !== null;
   return {
@@ -5350,7 +7132,7 @@ async function detectAgentsMd(cwd) {
   };
 }
 async function detectComponentsJson(cwd) {
-  const target = path25.join(cwd, "components.json");
+  const target = path30.join(cwd, "components.json");
   const content = await readFileOrNull(target);
   const exists = content !== null;
   return {
@@ -5366,7 +7148,7 @@ async function detectTailwindConfig(cwd) {
   const matched = [];
   const contents = [];
   for (const rel2 of TAILWIND_CONFIG_CANDIDATES) {
-    const c = await readFileOrNull(path25.join(cwd, rel2));
+    const c = await readFileOrNull(path30.join(cwd, rel2));
     if (c !== null) {
       matched.push(rel2);
       contents.push(c);
@@ -5389,14 +7171,14 @@ async function detectTokens(cwd) {
   const matched = [];
   const contents = [];
   for (const rel2 of TOKENS_FILE_CANDIDATES) {
-    const c = await readFileOrNull(path25.join(cwd, rel2));
+    const c = await readFileOrNull(path30.join(cwd, rel2));
     if (c !== null) {
       matched.push(rel2);
       contents.push(c);
     }
   }
   for (const rel2 of TOKENS_DIR_CANDIDATES) {
-    const abs = path25.join(cwd, rel2);
+    const abs = path30.join(cwd, rel2);
     if (await isDir(abs) && await dirHasContent(abs)) {
       matched.push(`${rel2}/`);
     }
@@ -5415,7 +7197,7 @@ async function detectIndexCss(cwd) {
   const matched = [];
   const contents = [];
   for (const rel2 of INDEX_CSS_CANDIDATES) {
-    const c = await readFileOrNull(path25.join(cwd, rel2));
+    const c = await readFileOrNull(path30.join(cwd, rel2));
     if (c !== null) {
       matched.push(rel2);
       contents.push(c);
@@ -5434,19 +7216,19 @@ async function detectIndexCss(cwd) {
 async function detectShadcnSource(cwd) {
   const matched = [];
   for (const rel2 of SHADCN_FILE_CANDIDATES) {
-    if (await fileExists(path25.join(cwd, rel2))) matched.push(rel2);
+    if (await fileExists(path30.join(cwd, rel2))) matched.push(rel2);
   }
   for (const rel2 of SHADCN_DIR_CANDIDATES) {
-    const abs = path25.join(cwd, rel2);
+    const abs = path30.join(cwd, rel2);
     if (await isDir(abs) && await dirHasContent(abs)) {
       matched.push(`${rel2}/`);
     }
   }
   let componentCount = 0;
   try {
-    const uiDir = path25.join(cwd, "src/components/ui");
+    const uiDir = path30.join(cwd, "src/components/ui");
     if (await isDir(uiDir)) {
-      const entries = await fs18.readdir(uiDir);
+      const entries = await fs23.readdir(uiDir);
       componentCount = entries.filter(
         (e) => e.endsWith(".tsx") || e.endsWith(".ts")
       ).length;
@@ -5464,14 +7246,16 @@ async function detectShadcnSource(cwd) {
   };
 }
 async function detectConflicts(cwd) {
-  const absCwd = path25.resolve(cwd);
+  const absCwd = path30.resolve(cwd);
   const items = await Promise.all([
     detectAgentsMd(absCwd),
     detectComponentsJson(absCwd),
     detectTailwindConfig(absCwd),
     detectTokens(absCwd),
     detectIndexCss(absCwd),
-    detectShadcnSource(absCwd)
+    detectShadcnSource(absCwd),
+    detectEslintConfig(absCwd),
+    detectStylelintConfig(absCwd)
   ]);
   return {
     cwd: absCwd,
@@ -5479,10 +7263,50 @@ async function detectConflicts(cwd) {
     hasAnyConflict: items.some((i) => i.exists)
   };
 }
+async function detectEslintConfig(cwd) {
+  const matched = [];
+  const contents = [];
+  for (const rel2 of ESLINT_CONFIG_CANDIDATES) {
+    const c = await readFileOrNull(path30.join(cwd, rel2));
+    if (c !== null) {
+      matched.push(rel2);
+      contents.push(c);
+    }
+  }
+  const exists = matched.length > 0;
+  return {
+    key: "eslint-config",
+    exists,
+    paths: matched,
+    fingerprint: exists ? fingerprint(contents) : void 0,
+    recommendedStrategy: exists ? "merge" : "overwrite",
+    availableStrategies: ["merge", "backup-overwrite", "overwrite", "skip"]
+  };
+}
+async function detectStylelintConfig(cwd) {
+  const matched = [];
+  const contents = [];
+  for (const rel2 of STYLELINT_CONFIG_CANDIDATES) {
+    const c = await readFileOrNull(path30.join(cwd, rel2));
+    if (c !== null) {
+      matched.push(rel2);
+      contents.push(c);
+    }
+  }
+  const exists = matched.length > 0;
+  return {
+    key: "stylelint-config",
+    exists,
+    paths: matched,
+    fingerprint: exists ? fingerprint(contents) : void 0,
+    recommendedStrategy: exists ? "merge" : "overwrite",
+    availableStrategies: ["merge", "backup-overwrite", "overwrite", "skip"]
+  };
+}
 
 // src/core/legacy-tokens-migrate.ts
-import * as path26 from "path";
-import * as fs19 from "fs/promises";
+import * as path31 from "path";
+import * as fs24 from "fs/promises";
 var CONSUMER_TOKENS_DIR2 = "tokens";
 var CONSUMER_OVERRIDES_FILE2 = "tokens.overrides.css";
 var EMPTY_OVERRIDES_TEMPLATE2 = `/* User-owned token overrides \u2014 frozen on subsequent installs. */
@@ -5494,7 +7318,7 @@ function buildMigrationBanner(legacyRel, isoTimestamp) {
 }
 function computeBackupRel(legacyRel, isoTimestamp) {
   const tsSafe = isoTimestamp.replace(/[:.]/g, "-");
-  return path26.posix.join(
+  return path31.posix.join(
     ".teamix-evo",
     ".backups",
     `${legacyRel}.${tsSafe}.bak`
@@ -5505,17 +7329,17 @@ async function migrateLegacyTokens(options) {
   const seen = /* @__PURE__ */ new Set();
   const uniqueLegacy = [];
   for (const raw of legacyPaths) {
-    const norm = raw.split(path26.sep).join("/");
+    const norm = raw.split(path31.sep).join("/");
     if (!seen.has(norm)) {
       seen.add(norm);
       uniqueLegacy.push(norm);
     }
   }
-  const overridesRel = path26.posix.join(
+  const overridesRel = path31.posix.join(
     CONSUMER_TOKENS_DIR2,
     CONSUMER_OVERRIDES_FILE2
   );
-  const overridesAbs = path26.join(projectRoot, overridesRel);
+  const overridesAbs = path31.join(projectRoot, overridesRel);
   const existingOverrides = await readFileOrNull(overridesAbs);
   const overridesCreated = existingOverrides === null;
   const baseContent = existingOverrides === null ? EMPTY_OVERRIDES_TEMPLATE2 : existingOverrides;
@@ -5524,7 +7348,7 @@ async function migrateLegacyTokens(options) {
   const isoTimestamp = (/* @__PURE__ */ new Date()).toISOString();
   let appendedPayload = "";
   for (const legacyRel of uniqueLegacy) {
-    const legacyAbs = path26.join(projectRoot, legacyRel);
+    const legacyAbs = path31.join(projectRoot, legacyRel);
     const content = await readFileOrNull(legacyAbs);
     if (content === null) {
       skipped.push({ from: legacyRel, reason: "not-found" });
@@ -5554,15 +7378,15 @@ async function migrateLegacyTokens(options) {
       dryRun
     };
   }
-  await ensureDir(path26.dirname(overridesAbs));
+  await ensureDir(path31.dirname(overridesAbs));
   const merged = baseContent + appendedPayload;
   const tmp = overridesAbs + ".tmp";
-  await fs19.writeFile(tmp, merged, "utf-8");
-  await fs19.rename(tmp, overridesAbs);
+  await fs24.writeFile(tmp, merged, "utf-8");
+  await fs24.rename(tmp, overridesAbs);
   for (const entry of migrated) {
-    const legacyAbs = path26.join(projectRoot, entry.from);
-    const backupAbs = path26.join(projectRoot, entry.backupTo);
-    await ensureDir(path26.dirname(backupAbs));
+    const legacyAbs = path31.join(projectRoot, entry.from);
+    const backupAbs = path31.join(projectRoot, entry.backupTo);
+    await ensureDir(path31.dirname(backupAbs));
     const srcContent = await readFileOrNull(legacyAbs);
     if (srcContent === null) {
       logger.debug(
@@ -5570,9 +7394,9 @@ async function migrateLegacyTokens(options) {
       );
       continue;
     }
-    await fs19.writeFile(backupAbs, srcContent, "utf-8");
+    await fs24.writeFile(backupAbs, srcContent, "utf-8");
     if (await fileExists(legacyAbs)) {
-      await fs19.unlink(legacyAbs);
+      await fs24.unlink(legacyAbs);
     }
     logger.debug(
       `legacy-tokens-migrate: ${entry.from} \u2192 ${overridesRel} (backup: ${entry.backupTo})`
@@ -5588,10 +7412,13 @@ async function migrateLegacyTokens(options) {
 }
 
 // src/core/agents-md.ts
-import * as fs20 from "fs/promises";
-import * as path27 from "path";
+import * as fs25 from "fs/promises";
+import * as path32 from "path";
+import { hasManagedRegion as hasManagedRegion3, replaceManagedRegion as replaceManagedRegion3 } from "@teamix-evo/registry";
+var AGENTS_MD_MANAGED_ID = "teamix-evo-skills";
 async function runGenerateAgentsMd(options) {
   const { projectRoot, variant, skillIds } = options;
+  const mode = options.mode ?? "overwrite";
   const ordered = [...skillIds].sort(
     (a, b) => bucketRank(a) - bucketRank(b) || a.localeCompare(b)
   );
@@ -5602,13 +7429,47 @@ async function runGenerateAgentsMd(options) {
     sections.push(section);
     if (missing) missingSkillIds.push(id);
   }
-  const body = renderAgentsMd({ variant, sections });
-  const target = path27.join(projectRoot, "AGENTS.md");
-  await fs20.writeFile(target, body, "utf8");
+  const target = path32.join(projectRoot, "AGENTS.md");
+  const targetExists = await fileExists(target);
+  const fullTemplate = renderAgentsMd({ variant, sections });
+  const managedBody = renderManagedBlockBody({ variant, sections });
+  let outputContent;
+  let merge;
+  if (!targetExists) {
+    outputContent = fullTemplate;
+    merge = "created";
+  } else {
+    await backupFile(target, projectRoot);
+    if (mode === "merge-managed") {
+      const existing = await readFileOrNull(target) ?? "";
+      if (hasManagedRegion3(existing, AGENTS_MD_MANAGED_ID)) {
+        outputContent = replaceManagedRegion3(
+          existing,
+          AGENTS_MD_MANAGED_ID,
+          managedBody
+        );
+        merge = "managed-replaced";
+      } else {
+        const wrapped = wrapManagedBlock(managedBody);
+        outputContent = `${wrapped}
+
+${PRECEDENCE_NOTICE}
+
+${existing.trimStart()}`;
+        merge = "managed-prepended";
+      }
+    } else {
+      outputContent = fullTemplate;
+      merge = "overwritten";
+    }
+  }
+  await fs25.writeFile(target, outputContent, "utf8");
   return {
     path: target,
     skillCount: ordered.length,
-    missingSkillIds
+    missingSkillIds,
+    backedUp: targetExists,
+    merge
   };
 }
 function bucketRank(id) {
@@ -5617,11 +7478,8 @@ function bucketRank(id) {
   return 2;
 }
 async function renderSkillSection(projectRoot, skillId) {
-  const skillPath = path27.join(
-    projectRoot,
-    ".teamix-evo",
-    "skills",
-    skillId,
+  const skillPath = path32.join(
+    getSkillsSourceDir(projectRoot, skillId),
     "SKILL.md"
   );
   const lines = [];
@@ -5629,7 +7487,7 @@ async function renderSkillSection(projectRoot, skillId) {
   let parts = null;
   let missing = false;
   try {
-    const raw = await fs20.readFile(skillPath, "utf8");
+    const raw = await fs25.readFile(skillPath, "utf8");
     parts = extractDescriptionParts(raw);
   } catch {
     missing = true;
@@ -5646,10 +7504,19 @@ async function renderSkillSection(projectRoot, skillId) {
   if (parts?.coordinates) {
     lines.push(`- **Coordinates with**: ${parts.coordinates}`);
   }
-  lines.push(`- **\u4F4D\u7F6E**: \`.teamix-evo/skills/${skillId}/SKILL.md\``);
+  lines.push(`- **\u4F4D\u7F6E**: \`.teamix-evo/skills-source/${skillId}/SKILL.md\``);
   return { section: lines.join("\n"), missing };
 }
 function renderAgentsMd(args) {
+  const { variant, sections } = args;
+  const managedBody = renderManagedBlockBody({ variant, sections });
+  const wrapped = wrapManagedBlock(managedBody);
+  return `${wrapped}
+
+${PRECEDENCE_NOTICE}
+`;
+}
+function renderManagedBlockBody(args) {
   const { variant, sections } = args;
   const skillBlock = sections.length > 0 ? sections.join("\n\n") : "_\uFF08\u672C\u5DE5\u7A0B\u672A\u88C5\u914D\u5DE5\u7A0B\u7EA7 skill\u3002\uFF09_";
   return `# AGENTS.md
@@ -5668,9 +7535,15 @@ ${skillBlock}
 - \u6A21\u7CCA\u573A\u666F\uFF1A\u5148\u6309 SKIP \u53CD\u5411\u6392\u9664\uFF0C\u5269\u4F59\u552F\u4E00 skill \u5373\u4E3A\u5165\u53E3
 - \u751F\u547D\u5468\u671F\u547D\u4EE4\uFF08\`init\` / \`update\` / \`add\`\uFF09\u8D70 \`teamix-evo-manage\`\uFF08\u5168\u5C40 skill\uFF0C\u672C\u6587\u4EF6\u4E0D\u5217\uFF09
 
-> \u5237\u65B0\u672C\u6587\u4EF6\uFF1A\`npx teamix-evo skills add\` \u6216\u91CD\u8DD1 \`npm create teamix-evo\` / \`teamix-evo init\`\u3002
-`;
+> \u5237\u65B0\u672C\u6587\u4EF6\uFF1A\`npx teamix-evo skills add\` \u6216\u91CD\u8DD1 \`npm create teamix-evo\` / \`teamix-evo init\`\u3002`;
+}
+function wrapManagedBlock(body) {
+  return `<!-- teamix-evo:managed:start id="${AGENTS_MD_MANAGED_ID}" -->
+${body}
+<!-- teamix-evo:managed:end id="${AGENTS_MD_MANAGED_ID}" -->`;
 }
+var PRECEDENCE_NOTICE = `<!-- teamix-evo:precedence -->
+> \u51B2\u7A81\u4EE5\u4E0A\u65B9\u7684 **Skills** \u7D22\u5F15\u4E3A\u51C6\uFF08\u4E0A\u6E38\u8DEF\u5F84\u4E0E TRIGGER/SKIP \u5951\u7EA6\uFF09\uFF1B\u9879\u76EE\u7279\u6709\u7684\u4EBA\u5DE5\u7EC6\u5219\u8BF7\u5199\u5728\u672C\u5904\u4EE5\u4E0B\u3001\u4E0D\u8981\u8986\u76D6\u4E0A\u65B9 managed \u533A\u57DF\u3002`;
 function extractDescriptionParts(fileContent) {
   const description = extractDescriptionBlock(fileContent);
   if (description == null) return null;
@@ -5771,9 +7644,9 @@ function extractSection(description, marker) {
 }
 
 // src/core/snapshot.ts
-import * as fs21 from "fs/promises";
-import * as path28 from "path";
-var TEAMIX_DIR5 = ".teamix-evo";
+import * as fs26 from "fs/promises";
+import * as path33 from "path";
+var TEAMIX_DIR6 = ".teamix-evo";
 var SNAPSHOTS_DIR = ".snapshots";
 var LOGS_DIR = "logs";
 var META_FILE = "_meta.json";
@@ -5788,9 +7661,9 @@ function fsSafeToIso(safe) {
   );
 }
 async function createSnapshot(projectRoot, opts = {}) {
-  const teamixDir = path28.join(projectRoot, TEAMIX_DIR5);
+  const teamixDir = path33.join(projectRoot, TEAMIX_DIR6);
   try {
-    const stat7 = await fs21.stat(teamixDir);
+    const stat7 = await fs26.stat(teamixDir);
     if (!stat7.isDirectory()) return null;
   } catch (err) {
     if (err.code === "ENOENT") return null;
@@ -5798,38 +7671,38 @@ async function createSnapshot(projectRoot, opts = {}) {
   }
   const isoTs = (/* @__PURE__ */ new Date()).toISOString();
   const ts = isoToFsSafe3(isoTs);
-  const snapshotRoot = path28.join(teamixDir, SNAPSHOTS_DIR);
-  const target = path28.join(snapshotRoot, ts);
-  await fs21.mkdir(target, { recursive: true });
-  const entries = await fs21.readdir(teamixDir, { withFileTypes: true });
+  const snapshotRoot = path33.join(teamixDir, SNAPSHOTS_DIR);
+  const target = path33.join(snapshotRoot, ts);
+  await fs26.mkdir(target, { recursive: true });
+  const entries = await fs26.readdir(teamixDir, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.name === SNAPSHOTS_DIR) continue;
     if (entry.name === LOGS_DIR) continue;
-    const src = path28.join(teamixDir, entry.name);
-    const dst = path28.join(target, entry.name);
-    await fs21.cp(src, dst, { recursive: true });
+    const src = path33.join(teamixDir, entry.name);
+    const dst = path33.join(target, entry.name);
+    await fs26.cp(src, dst, { recursive: true });
   }
   const meta = {
     ts: isoTs,
     reason: opts.reason ?? "manual"
   };
-  await fs21.writeFile(
-    path28.join(target, META_FILE),
+  await fs26.writeFile(
+    path33.join(target, META_FILE),
     JSON.stringify(meta, null, 2) + "\n",
     "utf-8"
   );
   logger.debug(
-    `Snapshot created \u2192 ${path28.relative(projectRoot, target)} (${meta.reason})`
+    `Snapshot created \u2192 ${path33.relative(projectRoot, target)} (${meta.reason})`
   );
   const keep = opts.keep ?? DEFAULT_KEEP;
   await pruneSnapshots(projectRoot, keep, { protectedTs: opts.protectedTs });
   return { ts, path: target };
 }
 async function listSnapshots(projectRoot) {
-  const snapshotRoot = path28.join(projectRoot, TEAMIX_DIR5, SNAPSHOTS_DIR);
+  const snapshotRoot = path33.join(projectRoot, TEAMIX_DIR6, SNAPSHOTS_DIR);
   let entries;
   try {
-    entries = await fs21.readdir(snapshotRoot, { withFileTypes: true });
+    entries = await fs26.readdir(snapshotRoot, { withFileTypes: true });
   } catch (err) {
     if (err.code === "ENOENT") return [];
     throw err;
@@ -5837,11 +7710,11 @@ async function listSnapshots(projectRoot) {
   const result = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const dir = path28.join(snapshotRoot, entry.name);
+    const dir = path33.join(snapshotRoot, entry.name);
     let isoTs = null;
     let reason = null;
     try {
-      const raw = await fs21.readFile(path28.join(dir, META_FILE), "utf-8");
+      const raw = await fs26.readFile(path33.join(dir, META_FILE), "utf-8");
       const parsed = JSON.parse(raw);
       if (typeof parsed.ts === "string") isoTs = parsed.ts;
       if (typeof parsed.reason === "string" && ["init", "update", "switch", "restore", "manual"].includes(
@@ -5866,17 +7739,17 @@ async function pruneSnapshots(projectRoot, keep = DEFAULT_KEEP, opts = {}) {
   const toRemove = opts.protectedTs ? tail.filter((s) => s.ts !== opts.protectedTs) : tail;
   const removed = [];
   for (const snap of toRemove) {
-    await fs21.rm(snap.path, { recursive: true, force: true });
+    await fs26.rm(snap.path, { recursive: true, force: true });
     removed.push(snap.ts);
     logger.debug(`Pruned snapshot ${snap.ts}`);
   }
   return removed.reverse();
 }
 async function restoreSnapshot(projectRoot, ts) {
-  const snapshotRoot = path28.join(projectRoot, TEAMIX_DIR5, SNAPSHOTS_DIR);
-  const target = path28.join(snapshotRoot, ts);
+  const snapshotRoot = path33.join(projectRoot, TEAMIX_DIR6, SNAPSHOTS_DIR);
+  const target = path33.join(snapshotRoot, ts);
   try {
-    const stat7 = await fs21.stat(target);
+    const stat7 = await fs26.stat(target);
     if (!stat7.isDirectory()) {
       throw new Error(`Snapshot path is not a directory: ${target}`);
     }
@@ -5889,22 +7762,22 @@ async function restoreSnapshot(projectRoot, ts) {
     throw err;
   }
   await createSnapshot(projectRoot, { reason: "restore", protectedTs: ts });
-  const teamixDir = path28.join(projectRoot, TEAMIX_DIR5);
-  const live = await fs21.readdir(teamixDir, { withFileTypes: true });
+  const teamixDir = path33.join(projectRoot, TEAMIX_DIR6);
+  const live = await fs26.readdir(teamixDir, { withFileTypes: true });
   for (const entry of live) {
     if (entry.name === SNAPSHOTS_DIR) continue;
     if (entry.name === LOGS_DIR) continue;
-    await fs21.rm(path28.join(teamixDir, entry.name), {
+    await fs26.rm(path33.join(teamixDir, entry.name), {
       recursive: true,
       force: true
     });
   }
-  const snapshotEntries = await fs21.readdir(target, { withFileTypes: true });
+  const snapshotEntries = await fs26.readdir(target, { withFileTypes: true });
   for (const entry of snapshotEntries) {
     if (entry.name === META_FILE) continue;
-    const src = path28.join(target, entry.name);
-    const dst = path28.join(teamixDir, entry.name);
-    await fs21.cp(src, dst, { recursive: true });
+    const src = path33.join(target, entry.name);
+    const dst = path33.join(teamixDir, entry.name);
+    await fs26.cp(src, dst, { recursive: true });
   }
   logger.debug(`Restored .teamix-evo/ from snapshot ${ts}`);
 }
@@ -5931,12 +7804,19 @@ var CRITICAL_STEPS = /* @__PURE__ */ new Set([
   "ui-init"
 ]);
 var IMPLEMENTED_STRATEGIES = {
+  // 'agents-md': both 'merge-managed' (Phase 2.B — splice the
+  // teamix-evo-skills managed region) and 'overwrite' (full rewrite) write
+  // through `runGenerateAgentsMd`.
   "agents-md": ["merge-managed", "overwrite", "skip"],
   tokens: ["migrate", "overwrite", "skip"],
   "components-json": ["overwrite", "skip"],
   "shadcn-source": ["overwrite", "skip-existing", "skip"],
   "tailwind-config": ["skip"],
-  "index-css": ["skip"]
+  "index-css": ["skip"],
+  // Phase 3.E: lint conflict strategies are honored end-to-end by
+  // `runLintInit` (backup user file + write template, optional AI-assist hint).
+  "eslint-config": ["merge", "backup-overwrite", "skip", "overwrite"],
+  "stylelint-config": ["merge", "backup-overwrite", "skip", "overwrite"]
 };
 function pickIde(ides) {
   return ides[0] ?? "qoder";
@@ -5954,11 +7834,75 @@ async function resolveUiEntries(options) {
   }
   return [...BASELINE_UI_ENTRIES];
 }
+function deriveTokensChanges(result, projectRoot) {
+  if (result.status !== "installed") return [];
+  return result.resources.map((r) => ({
+    kind: "created",
+    path: toRelativePosix(r.target, projectRoot),
+    step: "tokens",
+    detail: r.strategy
+  }));
+}
+function deriveSkillsChanges(result, projectRoot) {
+  if (result.status !== "installed") return [];
+  return result.addedSkillIds.map((id) => ({
+    kind: "created",
+    path: `.teamix-evo/skills/${id}/SKILL.md`,
+    step: "skills",
+    detail: "skill installed (source mirror + IDE mirrors)"
+  }));
+}
+function deriveUiAddChanges(result, projectRoot) {
+  const out = [];
+  let remaining = result.written;
+  for (let i = result.resources.length - 1; i >= 0 && remaining > 0; i--) {
+    const r = result.resources[i];
+    out.unshift({
+      kind: "created",
+      path: toRelativePosix(r.target, projectRoot),
+      step: "ui-add",
+      detail: r.strategy
+    });
+    remaining--;
+  }
+  return out;
+}
+function deriveLintChanges(result) {
+  if (result.status !== "installed") return [];
+  const out = [];
+  if (result.eslint) {
+    out.push({
+      kind: "created",
+      path: "eslint.config.js",
+      step: "lint",
+      detail: "@teamix-evo/eslint-config consumer preset"
+    });
+  }
+  if (result.stylelint) {
+    out.push({
+      kind: "created",
+      path: "stylelint.config.cjs",
+      step: "lint",
+      detail: "@teamix-evo/stylelint-config consumer preset"
+    });
+  }
+  if (result.packageJsonPatched) {
+    out.push({
+      kind: "created",
+      path: "package.json",
+      step: "lint",
+      detail: 'scripts.lint / scripts["lint:css"]'
+    });
+  }
+  return out;
+}
 async function runProjectInit(options) {
   const { projectRoot, answers, dryRun = false, onStep } = options;
   const ide = pickIde(answers.ides);
   const steps = [];
   const pending = [];
+  const allChanges = [];
+  const backupsBefore = dryRun ? /* @__PURE__ */ new Set() : await listBackupOriginals(projectRoot).catch(() => /* @__PURE__ */ new Set());
   let snapshot = null;
   let snapshotError;
   if (!dryRun) {
@@ -5975,6 +7919,9 @@ async function runProjectInit(options) {
   function record(step) {
     steps.push(step);
     onStep?.(step);
+    if (step.changes && step.changes.length > 0) {
+      allChanges.push(...step.changes);
+    }
   }
   function recordPending(key) {
     const strategy = answers.conflictDecisions[key];
@@ -6034,7 +7981,8 @@ async function runProjectInit(options) {
       record({
         name: "tokens",
         status: "ok",
-        detail
+        detail,
+        changes: deriveTokensChanges(result, projectRoot)
       });
     } catch (err) {
       recordFailure("tokens", err);
@@ -6066,7 +8014,8 @@ async function runProjectInit(options) {
       record({
         name: "skills",
         status: "ok",
-        detail: result.status === "installed" ? `added: ${result.addedSkillIds.join(", ") || "none"}; existing: ${result.skippedSkillIds.join(", ") || "none"}` : result.status
+        detail: result.status === "installed" ? `added: ${result.addedSkillIds.join(", ") || "none"}; existing: ${result.skippedSkillIds.join(", ") || "none"}` : result.status,
+        changes: deriveSkillsChanges(result, projectRoot)
       });
     } catch (err) {
       recordFailure("skills", err);
@@ -6094,12 +8043,25 @@ async function runProjectInit(options) {
       const result = await runGenerateAgentsMd({
         projectRoot,
         variant: answers.variant,
-        skillIds: agentsMdSkillIds
+        skillIds: agentsMdSkillIds,
+        // Phase 2.B: when the user picked `merge-managed` on conflict, only
+        // rewrite the `teamix-evo-skills` managed region so hand-written
+        // sections survive the regenerate step. `overwrite` keeps the
+        // historical full-rewrite default.
+        mode: agentsMdDecision === "merge-managed" ? "merge-managed" : "overwrite"
       });
       record({
         name: "agents-md",
         status: "ok",
-        detail: `${result.skillCount} skill index${result.missingSkillIds.length > 0 ? ` (missing SKILL.md: ${result.missingSkillIds.join(", ")})` : ""}`
+        detail: `${result.skillCount} skill index${result.missingSkillIds.length > 0 ? ` (missing SKILL.md: ${result.missingSkillIds.join(", ")})` : ""}`,
+        changes: [
+          {
+            kind: result.backedUp ? "modified" : "created",
+            path: toRelativePosix(result.path, projectRoot),
+            step: "agents-md",
+            detail: "skill-trigger fallback (ADR 0038)"
+          }
+        ]
       });
     } catch (err) {
       recordFailure("agents-md", err);
@@ -6184,7 +8146,8 @@ async function runProjectInit(options) {
           record({
             name: "ui-add",
             status: "ok",
-            detail: `${addResult.orderedIds.length} entries (${addResult.written} written, ${addResult.skipped} skipped)`
+            detail: `${addResult.orderedIds.length} entries (${addResult.written} written, ${addResult.skipped} skipped)`,
+            changes: deriveUiAddChanges(addResult, projectRoot)
           });
         } catch (err) {
           recordFailure("ui-add", err);
@@ -6208,14 +8171,39 @@ async function runProjectInit(options) {
     });
   } else {
     try {
+      const eslintStrategy = answers.conflictDecisions["eslint-config"];
+      const stylelintStrategy = answers.conflictDecisions["stylelint-config"];
+      const eslintExistingPaths = options.legacyEslintPaths ?? [];
+      const stylelintExistingPaths = options.legacyStylelintPaths ?? [];
       const result = await runLintInit({
         projectRoot,
-        skipInstall: options.skipInstall ?? false
+        skipInstall: options.skipInstall ?? false,
+        eslintStrategy: eslintStrategy === "merge" || eslintStrategy === "backup-overwrite" || eslintStrategy === "skip" || eslintStrategy === "overwrite" ? eslintStrategy : "overwrite",
+        stylelintStrategy: stylelintStrategy === "merge" || stylelintStrategy === "backup-overwrite" || stylelintStrategy === "skip" || stylelintStrategy === "overwrite" ? stylelintStrategy : "overwrite",
+        eslintExistingPaths,
+        stylelintExistingPaths
       });
+      const detailParts = [];
+      if (result.status === "installed") {
+        detailParts.push(
+          `eslint=${result.eslint}, stylelint=${result.stylelint}`
+        );
+        if (result.eslintMergeRequested) {
+          detailParts.push("eslint:AI-merge-pending");
+        }
+        if (result.stylelintMergeRequested) {
+          detailParts.push("stylelint:AI-merge-pending");
+        }
+        if (result.eslintSkipped) detailParts.push("eslint:skipped");
+        if (result.stylelintSkipped) detailParts.push("stylelint:skipped");
+      } else {
+        detailParts.push(result.status);
+      }
       record({
         name: "lint",
         status: "ok",
-        detail: result.status === "installed" ? `eslint=${result.eslint}, stylelint=${result.stylelint}` : result.status
+        detail: detailParts.join(" / "),
+        changes: deriveLintChanges(result)
       });
     } catch (err) {
       recordFailure("lint", err);
@@ -6223,11 +8211,34 @@ async function runProjectInit(options) {
   }
   recordPending("tailwind-config");
   recordPending("index-css");
+  if (!dryRun) {
+    try {
+      const backupsAfter = await listBackupOriginals(projectRoot);
+      const newlyBackedUp = diffBackupSet(backupsBefore, backupsAfter);
+      if (newlyBackedUp.size > 0) {
+        for (const change of allChanges) {
+          if (change.kind === "created" && newlyBackedUp.has(change.path)) {
+            change.kind = "modified";
+          }
+        }
+        for (const rel2 of newlyBackedUp) {
+          allChanges.push({
+            kind: "backed-up",
+            path: rel2,
+            step: "backup",
+            detail: ".teamix-evo/.backups/<\u540C\u8DEF\u5F84>.<isoTs>.bak"
+          });
+        }
+      }
+    } catch {
+    }
+  }
   const status = dryRun ? "dry-run" : steps.some((s) => s.status === "fail") ? "partial" : "installed";
   const out = {
     status,
     steps,
     pendingConflictWork: pending,
+    changes: allChanges,
     snapshot
   };
   if (snapshotError) out.snapshotError = snapshotError;
@@ -6247,6 +8258,72 @@ async function runProjectInit(options) {
   return out;
 }
 
+// src/core/post-init-guidance.ts
+import * as path34 from "path";
+var HEADING = "Next steps:";
+async function buildPostInitGuidance(options) {
+  const { projectRoot, withLint, withUi } = options;
+  let foreignComponents = null;
+  if (withUi) {
+    try {
+      const result = await runUiAdopt({ projectRoot, dryRun: true });
+      foreignComponents = result.foreign.length;
+    } catch {
+      foreignComponents = null;
+    }
+  }
+  let overridesVariables = null;
+  try {
+    const overridesAbs = path34.join(
+      projectRoot,
+      "tokens",
+      "tokens.overrides.css"
+    );
+    const raw = await readFileOrNull(overridesAbs);
+    if (raw !== null) {
+      overridesVariables = countCssCustomProperties(raw);
+    }
+  } catch {
+    overridesVariables = null;
+  }
+  const lines = [];
+  lines.push("\u2022 \u542F\u52A8 dev server \u9A8C\u8BC1\uFF1A`npm run dev`");
+  if (withLint) {
+    lines.push("\u2022 lint \u68C0\u67E5\uFF1A`npm run lint` / `npm run lint:css`");
+  }
+  if (withUi) {
+    if (foreignComponents !== null && foreignComponents > 0) {
+      lines.push(
+        `\u2022 \u68C0\u6D4B\u5230 ${foreignComponents} \u4E2A foreign UI \u7EC4\u4EF6\uFF08\u7528\u6237\u81EA\u6709\uFF0C\u4E0D\u5728 registry\uFF09\u2014 \u53EF\u6267\u884C \`teamix-evo ui add --adopt\` \u590D\u6838\u7EB3\u7BA1\u72B6\u6001`
+      );
+    } else if (foreignComponents === 0) {
+      lines.push(
+        "\u2022 UI \u63A5\u7BA1\u5B8C\u6210\uFF1A\u5F53\u524D src/components/ui/ \u5DF2\u5168\u90E8\u6CE8\u518C\u5230 manifest"
+      );
+    }
+  }
+  if (overridesVariables !== null && overridesVariables > 0) {
+    lines.push(
+      `\u2022 tokens.overrides.css \u542B ${overridesVariables} \u4E2A CSS \u53D8\u91CF \u2014 \u540E\u7EED\u53EF\u901A\u8FC7 \`teamix-evo tokens audit\` \u5BA1\u8BA1\u5197\u4F59 / \u63A8\u8350\u8FC1\u79FB\uFF08Phase 4.C.5\uFF09`
+    );
+  }
+  lines.push(
+    "\u2022 \u8BA9 AI \u63A5\u529B\uFF1A\u5728 IDE \u5185\u89E6\u53D1 `teamix-evo-manage` skill\uFF0C\u6309 adopt \u2192 upgrade \u2192 tokens audit \u2192 AGENTS.md \u56DE\u586B \u2192 lint 5 \u6B65\u8D70\u5B8C\u95ED\u73AF"
+  );
+  return {
+    stats: { foreignComponents, overridesVariables },
+    lines
+  };
+}
+var POST_INIT_HEADING = HEADING;
+function countCssCustomProperties(content) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of content.matchAll(/^\s*(--[a-z][a-z0-9-]*)\s*:/gim)) {
+    if (m[1]) seen.add(m[1]);
+  }
+  return seen.size;
+}
+
 // src/commands/init/wizard.ts
 import * as p from "@clack/prompts";
 var FRIENDLY_KEY = {
@@ -6255,7 +8332,9 @@ var FRIENDLY_KEY = {
   "tailwind-config": "tailwind.config.*",
   tokens: "tokens / src/design-tokens.css",
   "index-css": "src/index.css",
-  "shadcn-source": "src/lib/utils.ts + src/components/ui/"
+  "shadcn-source": "src/lib/utils.ts + src/components/ui/",
+  "eslint-config": "eslint.config.* / .eslintrc.*",
+  "stylelint-config": "stylelint.config.* / .stylelintrc.*"
 };
 var STRATEGY_LABEL = {
   overwrite: "\u8986\u76D6\uFF08\u5199\u5165\u65B0\u6587\u4EF6\uFF09",
@@ -6267,7 +8346,8 @@ var STRATEGY_LABEL = {
   coexist: "\u5171\u5B58\uFF08\u4EC5\u5199 overrides\uFF0C\u4E0D\u8986\u76D6\u73B0\u6709\uFF09",
   append: "\u8FFD\u52A0 @import \u884C + managed \u6807\u8BB0\uFF08\u63A8\u8350\uFF09",
   "skip-existing": "\u8DF3\u8FC7\u540C\u540D\u6587\u4EF6\uFF0C\u4EC5\u88C5\u65B0\u589E\uFF08\u63A8\u8350\uFF09",
-  "per-file-prompt": "\u9010\u6587\u4EF6\u8BE2\u95EE"
+  "per-file-prompt": "\u9010\u6587\u4EF6\u8BE2\u95EE",
+  merge: "\u5907\u4EFD + \u5199\u6A21\u677F\uFF0C\u8D77 AI \u52A9\u624B\u624B\u5408\u5E76\uFF08\u63A8\u8350\uFF09"
 };
 function strategyLabel(s) {
   return STRATEGY_LABEL[s];
@@ -6446,10 +8526,10 @@ var STEP_ICON = {
 };
 
 // src/commands/init/index.ts
-var initCommand5 = new Command33("init").description(
+var initCommand5 = new Command35("init").description(
   "\u628A teamix-evo AI \u5957\u4EF6\u63A5\u5165\u5DF2\u6709\u5DE5\u7A0B\uFF08\u666E\u901A\u7248\u63A5\u5165\uFF1A\u68C0\u6D4B\u51B2\u7A81 \u2192 \u5F15\u5BFC wizard \u2192 \u9759\u9ED8\u843D\u5730\uFF09"
 ).option("--cwd <dir>", "\u6307\u5B9A\u5DE5\u7A0B\u6839\u76EE\u5F55\uFF08\u9ED8\u8BA4\uFF1A\u5F53\u524D\u76EE\u5F55\uFF09").option("-y, --yes", "\u8DF3\u8FC7\u4EA4\u4E92\uFF0C\u5168\u90E8\u4F7F\u7528\u63A8\u8350\u9ED8\u8BA4\u503C").option("--dry-run", "\u53EA\u8F93\u51FA\u6267\u884C\u8BA1\u5212\uFF0C\u4E0D\u5199\u4EFB\u4F55\u6587\u4EF6").option("--variant <name>", "tokens variant\uFF08\u8986\u76D6 wizard \u8BE2\u95EE\uFF09").action(async (opts) => {
-  const cwd = path29.resolve(opts.cwd ?? process.cwd());
+  const cwd = path35.resolve(opts.cwd ?? process.cwd());
   try {
     const state = await detectProjectState(cwd);
     if (state.state === "empty") {
@@ -6496,11 +8576,15 @@ var initCommand5 = new Command33("init").description(
       logger.info("\u{1F4CB} dry-run \u6A21\u5F0F\uFF1A\u4EE5\u4E0B\u8BA1\u5212\u4E0D\u4F1A\u5199\u5165\u4EFB\u4F55\u6587\u4EF6");
     }
     const legacyTokensPaths = (conflicts.items.find((it) => it.key === "tokens")?.paths ?? []).filter((p2) => !p2.startsWith("tokens/"));
+    const legacyEslintPaths = conflicts.items.find((it) => it.key === "eslint-config")?.paths ?? [];
+    const legacyStylelintPaths = conflicts.items.find((it) => it.key === "stylelint-config")?.paths ?? [];
     const result = await runProjectInit({
       projectRoot: cwd,
       answers,
       dryRun,
       legacyTokensPaths,
+      legacyEslintPaths,
+      legacyStylelintPaths,
       onStep: (step) => {
         const icon = STEP_ICON[step.status];
         const detail = step.detail ? ` \u2014 ${step.detail}` : "";
@@ -6552,12 +8636,23 @@ var initCommand5 = new Command33("init").description(
         logger.info(`  \u2022 ${w.key} \u2192 ${w.strategy}`);
       }
     }
+    if (result.status !== "dry-run" && result.changes.length > 0) {
+      logger.info("");
+      logger.info("\u672C\u6B21 init \u6587\u4EF6\u53D8\u66F4\u6E05\u5355\uFF1A");
+      for (const line of formatFileChangeSummary(result.changes)) {
+        logger.info(line);
+      }
+    }
     if (result.status === "installed") {
+      const guidance = await buildPostInitGuidance({
+        projectRoot: cwd,
+        withLint: answers.withLint,
+        withUi: answers.withUi
+      });
       logger.info("");
-      logger.info("Next steps:");
-      logger.info("  \u2022 \u542F\u52A8 dev server \u9A8C\u8BC1\uFF1A`npm run dev`");
-      if (answers.withLint) {
-        logger.info("  \u2022 lint \u68C0\u67E5\uFF1A`npm run lint` / `npm run lint:css`");
+      logger.info(POST_INIT_HEADING);
+      for (const line of guidance.lines) {
+        logger.info(`  ${line}`);
       }
     }
   } catch (err) {
@@ -6573,11 +8668,11 @@ var initCommand5 = new Command33("init").description(
 });
 
 // src/commands/update/index.ts
-import { Command as Command34 } from "commander";
-import * as path31 from "path";
+import { Command as Command36 } from "commander";
+import * as path37 from "path";
 
 // src/core/project-update.ts
-import * as path30 from "path";
+import * as path36 from "path";
 import {
   loadTokensPackageManifest as loadTokensPackageManifest3,
   getVariantEntry as getVariantEntry3
@@ -6828,7 +8923,7 @@ async function runComponentSourceStep(category, args) {
       });
       return;
     }
-    const stagingRel = path30.relative(projectRoot, built.stagingDir);
+    const stagingRel = path36.relative(projectRoot, built.stagingDir);
     const summary = summarizeStagingRisk(built.manifest.summary.byRisk);
     record({
       name: category,
@@ -6871,10 +8966,10 @@ async function planTokensUpdate(tokensPackage, config) {
 }
 
 // src/commands/update/index.ts
-var updateCommand3 = new Command34("update").description(
+var updateCommand3 = new Command36("update").description(
   "\u4E00\u952E\u5347\u7EA7 teamix-evo \u5DF2\u88C5\u8D44\u6E90\uFF08regenerable \u8986\u76D6\u3001frozen \u4FDD\u7559\u3001managed \u5408\u5E76 \u2014 ADR 0003 \u4E09\u6001\uFF09"
 ).option("--cwd <dir>", "\u6307\u5B9A\u5DE5\u7A0B\u6839\u76EE\u5F55\uFF08\u9ED8\u8BA4\uFF1A\u5F53\u524D\u76EE\u5F55\uFF09").option("--dry-run", "\u53EA\u8F93\u51FA\u5347\u7EA7\u8BA1\u5212\uFF0C\u4E0D\u5199\u4EFB\u4F55\u6587\u4EF6").action(async (opts) => {
-  const cwd = path31.resolve(opts.cwd ?? process.cwd());
+  const cwd = path37.resolve(opts.cwd ?? process.cwd());
   const dryRun = opts.dryRun ?? false;
   try {
     if (dryRun) {
@@ -6956,14 +9051,14 @@ var updateCommand3 = new Command34("update").description(
 });
 
 // src/commands/restore/index.ts
-import { Command as Command35 } from "commander";
-import * as path32 from "path";
+import { Command as Command37 } from "commander";
+import * as path38 from "path";
 import * as prompts7 from "@clack/prompts";
 function createRestoreCommand() {
-  return new Command35("restore").description(
+  return new Command37("restore").description(
     "\u56DE\u6EDA .teamix-evo/ \u5230\u6307\u5B9A snapshot\uFF08init/update \u5931\u8D25\u65F6\u4F7F\u7528 \u2014 ADR 0019 \xA72\uFF09"
   ).argument("[ts]", "\u76EE\u6807 snapshot \u65F6\u95F4\u6233\uFF08\u5982 2026-06-11T20-59-03-000Z\uFF09").option("--list", "\u5217\u51FA\u53EF\u7528 snapshot\uFF08\u4E0D\u505A\u5B9E\u9645\u56DE\u6EDA\uFF09").option("--cwd <dir>", "\u6307\u5B9A\u5DE5\u7A0B\u6839\u76EE\u5F55\uFF08\u9ED8\u8BA4\uFF1A\u5F53\u524D\u76EE\u5F55\uFF09").option("-y, --yes", "\u8DF3\u8FC7\u4E8C\u6B21\u786E\u8BA4\uFF08destructive\uFF0C\u8BF7\u786E\u8BA4\u65E0\u8BEF\uFF09").action(async (ts, opts) => {
-    const cwd = path32.resolve(opts.cwd ?? process.cwd());
+    const cwd = path38.resolve(opts.cwd ?? process.cwd());
     try {
       const snapshots = await listSnapshots(cwd);
       if (opts.list) {
@@ -7059,13 +9154,13 @@ function printSnapshotTable(snapshots) {
 }
 
 // src/commands/switch/index.ts
-import { Command as Command36 } from "commander";
-import * as path34 from "path";
+import { Command as Command38 } from "commander";
+import * as path40 from "path";
 import * as prompts8 from "@clack/prompts";
 
 // src/core/variant-switch.ts
-import * as path33 from "path";
-import * as fs22 from "fs/promises";
+import * as path39 from "path";
+import * as fs27 from "fs/promises";
 import {
   loadTokensPackageManifest as loadTokensPackageManifest4,
   getVariantEntry as getVariantEntry4
@@ -7099,8 +9194,8 @@ async function runVariantSwitch(options) {
   const upstreamByBasename = /* @__PURE__ */ new Map();
   for (const fileRel of variantEntry.files) {
     upstreamByBasename.set(
-      path33.basename(fileRel),
-      path33.join(packageRoot, fileRel)
+      path39.basename(fileRel),
+      path39.join(packageRoot, fileRel)
     );
   }
   const prior = await readInstalledManifest(projectRoot) ?? {
@@ -7114,7 +9209,7 @@ async function runVariantSwitch(options) {
   const priorVersion = installedIdx >= 0 ? prior.installed[installedIdx].version : "0.0.0";
   const changes = [];
   for (const resource of priorResources) {
-    const consumerBasename = path33.basename(resource.target);
+    const consumerBasename = path39.basename(resource.target);
     const upstreamBasename = lookupUpstreamBasename2(consumerBasename);
     const upstreamAbs = upstreamBasename ? upstreamByBasename.get(upstreamBasename) : void 0;
     if (resource.strategy === "frozen") {
@@ -7135,7 +9230,7 @@ async function runVariantSwitch(options) {
       });
       continue;
     }
-    const upstreamContent = await fs22.readFile(upstreamAbs, "utf-8");
+    const upstreamContent = await fs27.readFile(upstreamAbs, "utf-8");
     if (resource.strategy === "regenerable") {
       const newHash = computeHash(upstreamContent);
       if (newHash === resource.hash) {
@@ -7188,12 +9283,12 @@ async function runVariantSwitch(options) {
   }
   const refreshedResources = [];
   for (const resource of priorResources) {
-    const consumerAbs = path33.isAbsolute(resource.target) ? resource.target : path33.join(projectRoot, resource.target);
-    const consumerBasename = path33.basename(resource.target);
+    const consumerAbs = path39.isAbsolute(resource.target) ? resource.target : path39.join(projectRoot, resource.target);
+    const consumerBasename = path39.basename(resource.target);
     const upstreamBasename = lookupUpstreamBasename2(consumerBasename);
     const upstreamAbs = upstreamBasename ? upstreamByBasename.get(upstreamBasename) : void 0;
     if (resource.strategy === "regenerable" && upstreamAbs) {
-      const upstreamContent = await fs22.readFile(upstreamAbs, "utf-8");
+      const upstreamContent = await fs27.readFile(upstreamAbs, "utf-8");
       await writeFileSafe(consumerAbs, upstreamContent);
       logger.debug(`[variant-switch] rewrite regenerable: ${resource.target}`);
       refreshedResources.push({
@@ -7203,8 +9298,8 @@ async function runVariantSwitch(options) {
       continue;
     }
     if (resource.strategy === "managed" && upstreamAbs && await fileExists(consumerAbs)) {
-      const upstreamContent = await fs22.readFile(upstreamAbs, "utf-8");
-      const consumerContent = await fs22.readFile(consumerAbs, "utf-8");
+      const upstreamContent = await fs27.readFile(upstreamAbs, "utf-8");
+      const consumerContent = await fs27.readFile(consumerAbs, "utf-8");
       const merged = mergeManagedRegions(upstreamContent, consumerContent);
       if (merged !== consumerContent) {
         await writeFileSafe(consumerAbs, merged);
@@ -7235,7 +9330,7 @@ async function runVariantSwitch(options) {
     installedAt: now
   };
   await writeFileSafe(
-    path33.join(projectRoot, ".teamix-evo", "tokens-lock.json"),
+    path39.join(projectRoot, ".teamix-evo", "tokens-lock.json"),
     JSON.stringify(lock, null, 2) + "\n"
   );
   logger.debug(
@@ -7332,10 +9427,10 @@ var KIND_LABEL = {
   unchanged: "unchanged"
 };
 function createSwitchCommand() {
-  return new Command36("switch").description(
+  return new Command38("switch").description(
     "variant \u5207\u6362\uFF1A\u5148\u5C55\u793A file-level diff\uFF0C--apply \u624D\u771F\u5199\uFF08ADR 0019 \xA7D3\uFF09"
   ).argument("<new-variant>", "\u76EE\u6807 variant id\uFF08\u5982 opentrek / uni-manager\uFF09").option("--cwd <dir>", "\u6307\u5B9A\u5DE5\u7A0B\u6839\u76EE\u5F55\uFF08\u9ED8\u8BA4\uFF1A\u5F53\u524D\u76EE\u5F55\uFF09").option("--apply", "\u771F\u6B63\u6267\u884C\u5207\u6362\uFF08\u9ED8\u8BA4 dry-run\uFF0C\u4EC5\u5C55\u793A\u8BA1\u5212\uFF09").option("-y, --yes", "\u8DF3\u8FC7 --apply \u4E8C\u6B21\u786E\u8BA4\uFF08destructive\uFF0C\u8BF7\u786E\u8BA4\u65E0\u8BEF\uFF09").action(async (newVariant, opts) => {
-    const cwd = path34.resolve(opts.cwd ?? process.cwd());
+    const cwd = path40.resolve(opts.cwd ?? process.cwd());
     const apply = opts.apply ?? false;
     try {
       const plan = await runVariantSwitch({
@@ -7451,7 +9546,7 @@ function printChangePlan(from, to, toVersion, changes) {
 // src/index.ts
 var require8 = createRequire8(import.meta.url);
 var { version } = require8("../package.json");
-var program = new Command37();
+var program = new Command39();
 program.name("teamix-evo").description("Where ideas evolve. \u2014 AI Coding \u5957\u4EF6").version(version);
 program.addCommand(tokensCommand);
 program.addCommand(skillsCommand);