teamix-evo 0.8.0 → 0.9.0

package/dist/core/index.js

@@ -113,7 +113,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 path2.join(projectRoot, TEAMIX_DIR);
@@ -197,6 +198,9 @@ function getSkillsSourceDir(projectRoot, skillName) {
   const base = path2.join(projectRoot, TEAMIX_DIR, SKILLS_DIR);
   return skillName ? path2.join(base, skillName) : base;
 }
+function getLegacySkillsSourceDir(projectRoot) {
+  return path2.join(projectRoot, TEAMIX_DIR, LEGACY_SKILLS_DIR);
+}
 async function readSkillsLock(projectRoot) {
   const lockPath = path2.join(
     projectRoot,
@@ -385,6 +389,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(
@@ -677,6 +682,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));
@@ -720,6 +726,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 stat5;
+      try {
+        stat5 = await fs5.stat(dir);
+      } catch {
+        continue;
+      }
+      if (!stat5.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) {
@@ -815,13 +933,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,
@@ -833,6 +967,7 @@ async function runSkillsInit(options) {
     scope,
     onlyIds,
     skippedSkillIds,
+    outdatedSkills,
     existing,
     existingConfig
   });
@@ -873,10 +1008,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",
@@ -888,7 +1024,8 @@ async function runSkillsAdd(options) {
       fileCount: 0,
       resources: [],
       addedSkillIds: [],
-      skippedSkillIds
+      skippedSkillIds,
+      outdatedSkills
     };
   }
   return finalizeSkillsInstall({
@@ -902,10 +1039,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((p) => p.package === packageName);
@@ -930,6 +1109,7 @@ async function finalizeSkillsInstall(args) {
     scope,
     onlyIds,
     skippedSkillIds,
+    outdatedSkills,
     existing,
     existingConfig
   } = args;
@@ -995,6 +1175,10 @@ async function finalizeSkillsInstall(args) {
   }
   await writeSkillsLock(projectRoot, lock);
   await ensureMcpJson(projectRoot);
+  try {
+    await pruneEmptyIdeSkillDirs({ projectRoot, ides, scope });
+  } catch {
+  }
   return {
     status: "installed",
     packageName,
@@ -1005,7 +1189,8 @@ async function finalizeSkillsInstall(args) {
     fileCount: result.count,
     resources: result.resources,
     addedSkillIds: onlyIds,
-    skippedSkillIds
+    skippedSkillIds,
+    outdatedSkills: outdatedSkills ?? []
   };
 }
 function mergeInstalledResources(existing, next) {
@@ -1213,6 +1398,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}`,
@@ -1593,6 +1781,9 @@ async function installUiEntries(options) {
       const sourceAbs = path11.resolve(rootForEntry, file.source);
       const raw = await fs8.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)}`);
@@ -1963,18 +2154,29 @@ var ESLINT_DEPS = [
 ];
 var STYLELINT_DEPS = ["@teamix-evo/stylelint-config", "stylelint"];
 async function runLintInit(options) {
-  const { projectRoot, skipInstall } = options;
+  const {
+    projectRoot,
+    skipInstall,
+    eslintStrategy = "overwrite",
+    stylelintStrategy = "overwrite",
+    eslintExistingPaths = [],
+    stylelintExistingPaths = []
+  } = options;
   const eslintConfigPath = path13.join(projectRoot, "eslint.config.js");
   const stylelintConfigPath = path13.join(projectRoot, "stylelint.config.cjs");
-  const eslintExists = await fileExists(eslintConfigPath);
-  const stylelintExists = await fileExists(stylelintConfigPath);
-  if (eslintExists && stylelintExists) {
+  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);
@@ -1983,23 +2185,38 @@ async function runLintInit(options) {
       await execa(pm, args, { cwd: projectRoot, stdio: "inherit" });
     }
   }
+  if (eslintNeedsWrite && eslintExistingPaths.length > 0) {
+    for (const rel2 of eslintExistingPaths) {
+      await backupFile(path13.join(projectRoot, rel2), projectRoot);
+    }
+  }
+  if (stylelintNeedsWrite && stylelintExistingPaths.length > 0) {
+    for (const rel2 of stylelintExistingPaths) {
+      await backupFile(path13.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) {
@@ -2010,12 +2227,12 @@ function detectPm(projectRoot) {
 async function patchPackageJsonScripts(projectRoot) {
   const pkgPath = path13.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;
@@ -2028,17 +2245,22 @@ 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/core/agents-md.ts
 import * as fs10 from "fs/promises";
 import * as path14 from "path";
+import { hasManagedRegion as hasManagedRegion2, replaceManagedRegion as replaceManagedRegion2 } 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)
   );
@@ -2049,13 +2271,47 @@ async function runGenerateAgentsMd(options) {
     sections.push(section);
     if (missing) missingSkillIds.push(id);
   }
-  const body = renderAgentsMd({ variant, sections });
   const target = path14.join(projectRoot, "AGENTS.md");
-  await fs10.writeFile(target, body, "utf8");
+  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 (hasManagedRegion2(existing, AGENTS_MD_MANAGED_ID)) {
+        outputContent = replaceManagedRegion2(
+          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 fs10.writeFile(target, outputContent, "utf8");
   return {
     path: target,
     skillCount: ordered.length,
-    missingSkillIds
+    missingSkillIds,
+    backedUp: targetExists,
+    merge
   };
 }
 function bucketRank(id) {
@@ -2065,10 +2321,7 @@ function bucketRank(id) {
 }
 async function renderSkillSection(projectRoot, skillId) {
   const skillPath = path14.join(
-    projectRoot,
-    ".teamix-evo",
-    "skills",
-    skillId,
+    getSkillsSourceDir(projectRoot, skillId),
     "SKILL.md"
   );
   const lines = [];
@@ -2093,10 +2346,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
@@ -2115,9 +2377,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;
@@ -2311,6 +2579,26 @@ 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 stat5 = await fs12.stat(target);
@@ -2487,7 +2775,9 @@ async function detectConflicts(cwd) {
     detectTailwindConfig(absCwd),
     detectTokens(absCwd),
     detectIndexCss(absCwd),
-    detectShadcnSource(absCwd)
+    detectShadcnSource(absCwd),
+    detectEslintConfig(absCwd),
+    detectStylelintConfig(absCwd)
   ]);
   return {
     cwd: absCwd,
@@ -2495,6 +2785,46 @@ 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(path16.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(path16.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 path17 from "path";
@@ -2706,6 +3036,56 @@ async function pruneSnapshots(projectRoot, keep = DEFAULT_KEEP, opts = {}) {
   return removed.reverse();
 }
 
+// src/core/file-changes.ts
+import * as fs15 from "fs/promises";
+import * as path19 from "path";
+function toRelativePosix(p, projectRoot) {
+  let rel2 = p;
+  if (path19.isAbsolute(p)) {
+    rel2 = path19.relative(projectRoot, p);
+  }
+  return rel2.split(path19.sep).join("/");
+}
+async function listBackupOriginals(projectRoot) {
+  const backupsDir = path19.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 fs15.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      throw err;
+    }
+    for (const e of entries) {
+      const full = path19.join(dir, e.name);
+      if (e.isDirectory()) {
+        stack.push(full);
+      } else if (e.isFile() && e.name.endsWith(".bak")) {
+        const rel2 = path19.relative(backupsDir, full);
+        const original = stripBackupSuffix(rel2);
+        if (original) out.add(original.split(path19.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 p of after) {
+    if (!before.has(p)) out.add(p);
+  }
+  return out;
+}
+
 // src/core/project-init.ts
 var BASELINE_UI_ENTRIES = [
   "button",
@@ -2728,12 +3108,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";
@@ -2751,11 +3138,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) {
@@ -2772,6 +3223,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];
@@ -2831,7 +3285,8 @@ async function runProjectInit(options) {
       record({
         name: "tokens",
         status: "ok",
-        detail
+        detail,
+        changes: deriveTokensChanges(result, projectRoot)
       });
     } catch (err) {
       recordFailure("tokens", err);
@@ -2863,7 +3318,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);
@@ -2891,12 +3347,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);
@@ -2981,7 +3450,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);
@@ -3005,14 +3475,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);
@@ -3020,11 +3515,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;
@@ -3045,22 +3563,22 @@ async function runProjectInit(options) {
 }
 
 // src/core/project-update.ts
-import * as path24 from "path";
+import * as path25 from "path";
 import {
   loadTokensPackageManifest as loadTokensPackageManifest3,
   getVariantEntry as getVariantEntry3
 } from "@teamix-evo/registry";
 
 // src/core/tokens-update.ts
-import * as path20 from "path";
-import * as fs15 from "fs/promises";
+import * as path21 from "path";
+import * as fs16 from "fs/promises";
 import {
   loadTokensPackageManifest as loadTokensPackageManifest2,
   getVariantEntry as getVariantEntry2
 } from "@teamix-evo/registry";
 
 // src/core/upgrade-hints.ts
-import * as path19 from "path";
+import * as path20 from "path";
 var TEAMIX_DIR3 = ".teamix-evo";
 var HINTS_DIR = ".upgrade-hints";
 function isoToFsSafe2(iso) {
@@ -3071,7 +3589,7 @@ async function writeTokensUpgradeHint(options) {
   const isoTs = options.isoTs ?? (/* @__PURE__ */ new Date()).toISOString();
   const fsTs = isoToFsSafe2(isoTs);
   const filename = `tokens-${fsTs}.json`;
-  const target = path19.join(
+  const target = path20.join(
     options.projectRoot,
     TEAMIX_DIR3,
     HINTS_DIR,
@@ -3097,10 +3615,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));
@@ -3116,7 +3634,7 @@ function compareSemver(a, b) {
 }
 
 // src/core/managed-merge.ts
-import { hasManagedRegion as hasManagedRegion2, replaceManagedRegion as replaceManagedRegion2 } from "@teamix-evo/registry";
+import { hasManagedRegion as hasManagedRegion3, replaceManagedRegion as replaceManagedRegion3 } from "@teamix-evo/registry";
 function mergeManagedRegions(upstreamContent, consumerContent) {
   let updated = consumerContent;
   const re = /<!-- teamix-evo:managed:start id="([^"]+)" -->([\s\S]*?)<!-- teamix-evo:managed:end(?: id="\1")? -->/g;
@@ -3124,12 +3642,12 @@ function mergeManagedRegions(upstreamContent, consumerContent) {
   while ((match = re.exec(upstreamContent)) !== null) {
     const id = match[1];
     const body = match[2].replace(/^\n/, "").replace(/\n$/, "");
-    if (!hasManagedRegion2(updated, id)) {
+    if (!hasManagedRegion3(updated, id)) {
       throw new Error(
         `Managed region "${id}" missing from consumer file \u2014 refusing to silently rewrite (ADR 0003).`
       );
     }
-    updated = replaceManagedRegion2(updated, id, body);
+    updated = replaceManagedRegion3(updated, id, body);
   }
   return updated;
 }
@@ -3160,8 +3678,8 @@ async function runTokensUpdate(options) {
   const upstreamByBasename = /* @__PURE__ */ new Map();
   for (const fileRel of variantEntry.files) {
     upstreamByBasename.set(
-      path20.basename(fileRel),
-      path20.join(packageRoot, fileRel)
+      path21.basename(fileRel),
+      path21.join(packageRoot, fileRel)
     );
   }
   const prior = await readInstalledManifest(projectRoot) ?? {
@@ -3178,8 +3696,8 @@ async function runTokensUpdate(options) {
   const frozenDrift = [];
   const refreshedResources = [];
   for (const resource of priorResources) {
-    const consumerAbs = path20.isAbsolute(resource.target) ? resource.target : path20.join(projectRoot, resource.target);
-    const consumerBasename = path20.basename(resource.target);
+    const consumerAbs = path21.isAbsolute(resource.target) ? resource.target : path21.join(projectRoot, resource.target);
+    const consumerBasename = path21.basename(resource.target);
     const upstreamBasename = lookupUpstreamBasename(consumerBasename);
     const upstreamAbs = upstreamBasename ? upstreamByBasename.get(upstreamBasename) : void 0;
     if (resource.strategy === "regenerable") {
@@ -3187,7 +3705,7 @@ async function runTokensUpdate(options) {
         refreshedResources.push(resource);
         continue;
       }
-      const content = await fs15.readFile(upstreamAbs, "utf-8");
+      const content = await fs16.readFile(upstreamAbs, "utf-8");
       await writeFileSafe(consumerAbs, content);
       rewritten.push(resource.target);
       refreshedResources.push({
@@ -3201,8 +3719,8 @@ async function runTokensUpdate(options) {
         refreshedResources.push(resource);
         continue;
       }
-      const upstreamContent = await fs15.readFile(upstreamAbs, "utf-8");
-      const consumerContent = await fs15.readFile(consumerAbs, "utf-8");
+      const upstreamContent = await fs16.readFile(upstreamAbs, "utf-8");
+      const consumerContent = await fs16.readFile(consumerAbs, "utf-8");
       const merged = mergeManagedRegions(upstreamContent, consumerContent);
       if (merged !== consumerContent) {
         await writeFileSafe(consumerAbs, merged);
@@ -3216,7 +3734,7 @@ async function runTokensUpdate(options) {
     }
     if (await fileExists(consumerAbs)) preserved.push(resource.target);
     if (upstreamAbs) {
-      const upstreamContent = await fs15.readFile(upstreamAbs, "utf-8");
+      const upstreamContent = await fs16.readFile(upstreamAbs, "utf-8");
       const upstreamHash = computeHash(upstreamContent);
       if (resource.hash && upstreamHash !== resource.hash) {
         frozenDrift.push({
@@ -3256,7 +3774,7 @@ async function runTokensUpdate(options) {
     installedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   await writeFileSafe(
-    path20.join(projectRoot, ".teamix-evo", "tokens-lock.json"),
+    path21.join(projectRoot, ".teamix-evo", "tokens-lock.json"),
     JSON.stringify(lock, null, 2) + "\n"
   );
   config.packages.tokens.version = variantEntry.version;
@@ -3312,8 +3830,8 @@ function lookupUpstreamBasename(consumerBasename) {
 }
 
 // src/core/ui-upgrade-detector.ts
-import * as fs16 from "fs/promises";
-import * as path21 from "path";
+import * as fs17 from "fs/promises";
+import * as path22 from "path";
 var PACKAGE_NAME = {
   ui: "@teamix-evo/ui",
   "biz-ui": "@teamix-evo/biz-ui"
@@ -3329,10 +3847,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 = path21.join(projectRoot, installDir);
+  const installDirAbs = path22.join(projectRoot, installDir);
   const installDirExists = await directoryExists(installDirAbs);
   const hasComponentsJson = await fileExists(
-    path21.join(projectRoot, "components.json")
+    path22.join(projectRoot, "components.json")
   );
   const installedPkg = findInstalledPackage(installed, PACKAGE_NAME[category]);
   const registeredIds = installedPkg ? extractIds(installedPkg).sort() : [];
@@ -3372,14 +3890,14 @@ function extractIds(pkg) {
 }
 async function directoryExists(p) {
   try {
-    const stat5 = await fs16.stat(p);
+    const stat5 = await fs17.stat(p);
     return stat5.isDirectory();
   } catch {
     return false;
   }
 }
 async function listComponentIds(installDirAbs) {
-  const entries = await fs16.readdir(installDirAbs, { withFileTypes: true });
+  const entries = await fs17.readdir(installDirAbs, { withFileTypes: true });
   const ids = [];
   for (const e of entries) {
     if (!e.isFile()) continue;
@@ -3399,7 +3917,7 @@ function classifyLineage(args) {
 }
 
 // src/core/ui-upgrade.ts
-import * as path23 from "path";
+import * as path24 from "path";
 import { createRequire as createRequire5 } from "module";
 import {
   loadUiPackageManifest as loadUiPackageManifest3,
@@ -3407,7 +3925,7 @@ import {
 } from "@teamix-evo/registry";
 
 // src/core/ui-upgrade-staging.ts
-import * as path22 from "path";
+import * as path23 from "path";
 var TEAMIX_DIR4 = ".teamix-evo";
 var STAGING_DIR = ".upgrade-staging";
 var PACKAGE_NAME2 = {
@@ -3427,7 +3945,7 @@ async function buildUiUpgradeStaging(options) {
   if (!installedPkg) return null;
   const isoTs = options.isoTs ?? (/* @__PURE__ */ new Date()).toISOString();
   const fsTs = isoToFsSafe3(isoTs);
-  const stagingDir = path22.join(
+  const stagingDir = path23.join(
     options.projectRoot,
     TEAMIX_DIR4,
     STAGING_DIR,
@@ -3459,7 +3977,7 @@ async function buildUiUpgradeStaging(options) {
     if (onlyIds && !onlyIds.has(id)) continue;
     const built = await processForeign({
       id,
-      installDirAbs: path22.join(options.projectRoot, lineageReport.installDir),
+      installDirAbs: path23.join(options.projectRoot, lineageReport.installDir),
       stagingDir,
       projectRoot: options.projectRoot,
       category
@@ -3482,7 +4000,7 @@ async function buildUiUpgradeStaging(options) {
   };
   await ensureDir(stagingDir);
   await writeFileSafe(
-    path22.join(stagingDir, "meta.json"),
+    path23.join(stagingDir, "meta.json"),
     JSON.stringify(manifestOut, null, 2) + "\n"
   );
   return { stagingDir, manifest: manifestOut };
@@ -3516,19 +4034,19 @@ async function processRegistered(args) {
   const file = entry.files[0];
   if (!file) return null;
   const rootForEntry = args.entryPackageRoot?.get(id) ?? args.packageRoot;
-  const sourceAbs = path22.resolve(rootForEntry, file.source);
+  const sourceAbs = path23.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 = path22.extname(resource.target) || ".tsx";
-  const incomingExt = path22.extname(file.targetName) || currentExt;
+  const currentExt = path23.extname(resource.target) || ".tsx";
+  const incomingExt = path23.extname(file.targetName) || currentExt;
   const currentRel = `${id}/current${currentExt}`;
   const incomingRel = `${id}/incoming${incomingExt}`;
-  await writeFileSafe(path22.join(stagingDir, currentRel), currentSource);
-  await writeFileSafe(path22.join(stagingDir, incomingRel), incomingTransformed);
+  await writeFileSafe(path23.join(stagingDir, currentRel), currentSource);
+  await writeFileSafe(path23.join(stagingDir, incomingRel), incomingTransformed);
   const diff = classifyRisk({
     currentHash: resource.hash,
     incomingHash,
@@ -3536,11 +4054,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: path22.relative(projectRoot, resource.target),
+      target: path23.relative(projectRoot, resource.target),
       hash: resource.hash,
       sourceLineage: "teamix-evo"
     },
@@ -3549,25 +4072,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 = path22.join(installDirAbs, `${id}.tsx`);
-  const ts = path22.join(installDirAbs, `${id}.ts`);
+  const tsx = path23.join(installDirAbs, `${id}.tsx`);
+  const ts = path23.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 = path22.extname(target);
+  const ext = path23.extname(target);
   const currentRel = `${id}/current${ext}`;
-  await writeFileSafe(path22.join(stagingDir, currentRel), raw);
+  await writeFileSafe(path23.join(stagingDir, currentRel), raw);
   return {
     id,
     category,
     current: {
-      target: path22.relative(projectRoot, target),
+      target: path23.relative(projectRoot, target),
       hash: computeHash(raw),
       sourceLineage: "custom"
     },
@@ -3582,17 +4106,17 @@ async function processForeign(args) {
   };
 }
 async function buildBreakingEntry(args) {
-  const ext = path22.extname(args.resource.target) || ".tsx";
+  const ext = path23.extname(args.resource.target) || ".tsx";
   const currentRel = `${args.id}/current${ext}`;
   await writeFileSafe(
-    path22.join(args.stagingDir, currentRel),
+    path23.join(args.stagingDir, currentRel),
     args.currentSource
   );
   return {
     id: args.id,
     category: args.category,
     current: {
-      target: path22.relative(args.projectRoot, args.resource.target),
+      target: path23.relative(args.projectRoot, args.resource.target),
       hash: args.resource.hash,
       sourceLineage: "teamix-evo"
     },
@@ -3712,12 +4236,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 = createRequire5(import.meta.url);
 function resolvePackageRoot4(packageName) {
   const pkgJsonPath = nodeRequire.resolve(`${packageName}/package.json`);
-  return path23.dirname(pkgJsonPath);
+  return path24.dirname(pkgJsonPath);
 }
 async function buildStaging(args) {
   const { category, projectRoot, aliases, lineageReport, trigger, onlyIds } = args;
@@ -3737,7 +4440,7 @@ async function buildStaging(args) {
   }
   const bizRoot = args.bizUiPackageRoot ?? resolvePackageRoot4("@teamix-evo/biz-ui");
   const variant = lineageReport.installedVariant ?? "_flat";
-  const variantDir = path23.join(bizRoot, "variants", variant);
+  const variantDir = path24.join(bizRoot, "variants", variant);
   const variantManifest = await loadVariantUiPackageManifest2(variantDir);
   const uiRoot = args.uiPackageRoot ?? resolvePackageRoot4("@teamix-evo/ui");
   const uiManifest = await loadUiPackageManifest3(uiRoot);
@@ -4019,7 +4722,7 @@ async function runComponentSourceStep(category, args) {
       });
       return;
     }
-    const stagingRel = path24.relative(projectRoot, built.stagingDir);
+    const stagingRel = path25.relative(projectRoot, built.stagingDir);
     const summary = summarizeStagingRisk(built.manifest.summary.byRisk);
     record({
       name: category,
@@ -4062,8 +4765,8 @@ async function planTokensUpdate(tokensPackage, config) {
 }
 
 // src/core/installer.ts
-import * as path25 from "path";
-import * as fs17 from "fs/promises";
+import * as path26 from "path";
+import * as fs18 from "fs/promises";
 async function installResources(options) {
   const { projectRoot, manifest, data, variantDir, packageRoot } = options;
   const installedResources = [];
@@ -4100,13 +4803,13 @@ async function installSingleResource(resource, projectRoot, data, variantDir, pa
     variantDir,
     packageRoot
   );
-  const targetPath = path25.join(projectRoot, resource.target);
+  const targetPath = path26.join(projectRoot, resource.target);
   let content;
   if (resource.template) {
     const templateContent = await loadTemplateFile(sourcePath);
     content = renderTemplate(templateContent, data);
   } else {
-    content = await fs17.readFile(sourcePath, "utf-8");
+    content = await fs18.readFile(sourcePath, "utf-8");
   }
   await writeFileSafe(targetPath, content);
   const hash = computeHash(content);
@@ -4124,13 +4827,13 @@ async function installRecursiveResource(resource, projectRoot, data, variantDir,
     variantDir,
     packageRoot
   );
-  const targetDir = path25.join(projectRoot, resource.target);
+  const targetDir = path26.join(projectRoot, resource.target);
   const results = [];
   await ensureDir(targetDir);
   const entries = await walkDir(sourcePath);
   for (const entry of entries) {
-    const relPath = path25.relative(sourcePath, entry);
-    let targetFile = path25.join(targetDir, relPath);
+    const relPath = path26.relative(sourcePath, entry);
+    let targetFile = path26.join(targetDir, relPath);
     if (resource.template && targetFile.endsWith(".hbs")) {
       targetFile = targetFile.slice(0, -4);
     }
@@ -4139,11 +4842,11 @@ async function installRecursiveResource(resource, projectRoot, data, variantDir,
       const templateContent = await loadTemplateFile(entry);
       content = renderTemplate(templateContent, data);
     } else {
-      content = await fs17.readFile(entry, "utf-8");
+      content = await fs18.readFile(entry, "utf-8");
     }
     await writeFileSafe(targetFile, content);
     const hash = computeHash(content);
-    const targetRel = path25.relative(projectRoot, targetFile);
+    const targetRel = path26.relative(projectRoot, targetFile);
     results.push({
       id: `${resource.id}:${relPath}`,
       target: targetRel,
@@ -4156,25 +4859,25 @@ async function installRecursiveResource(resource, projectRoot, data, variantDir,
 }
 
 // src/core/registry-client.ts
-import * as path26 from "path";
-import * as fs18 from "fs/promises";
+import * as path27 from "path";
+import * as fs19 from "fs/promises";
 import { createRequire as createRequire6 } from "module";
 import { loadVariantManifest } from "@teamix-evo/registry";
 var require6 = createRequire6(import.meta.url);
 function resolvePackageRoot5(packageName) {
   const pkgJsonPath = require6.resolve(`${packageName}/package.json`);
-  return path26.dirname(pkgJsonPath);
+  return path27.dirname(pkgJsonPath);
 }
 async function loadVariantData(packageName, variant) {
   const packageRoot = resolvePackageRoot5(packageName);
-  const variantDir = path26.join(packageRoot, "library", variant);
+  const variantDir = path27.join(packageRoot, "library", variant);
   logger.debug(`Resolved variant dir: ${variantDir}`);
   logger.debug(`Package root: ${packageRoot}`);
   const manifest = await loadVariantManifest(variantDir);
   let data = {};
-  const dataPath = path26.join(variantDir, "_data.json");
+  const dataPath = path27.join(variantDir, "_data.json");
   try {
-    const raw = await fs18.readFile(dataPath, "utf-8");
+    const raw = await fs19.readFile(dataPath, "utf-8");
     data = JSON.parse(raw);
   } catch (err) {
     if (err.code !== "ENOENT") {