teamix-evo 0.7.0 → 0.9.0

package/dist/core/index.js

@@ -1,7 +1,6 @@
 // src/core/tokens-init.ts
 import * as path9 from "path";
 import * as fs6 from "fs/promises";
-import { createRequire as createRequire2 } from "module";
 import {
   loadTokensPackageManifest,
   getVariantEntry
@@ -97,11 +96,25 @@ import {
   validateSkillsLock,
   TokensPackLockSchema
 } from "@teamix-evo/registry";
+
+// src/utils/error.ts
+function getErrorMessage(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+// src/core/state.ts
 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);
@@ -120,7 +133,7 @@ async function readProjectConfig(projectRoot) {
     data = JSON.parse(raw);
   } catch (err) {
     throw new Error(
-      `Corrupted config.json (${err.message}). Fix the JSON manually or remove the file to start fresh; refusing to clobber prior config.`
+      `Corrupted config.json (${getErrorMessage(err)}). Fix the JSON manually or remove the file to start fresh; refusing to clobber prior config.`
     );
   }
   const result = validateConfig(data);
@@ -145,7 +158,7 @@ async function readInstalledManifest(projectRoot) {
     data = JSON.parse(raw);
   } catch (err) {
     throw new Error(
-      `Corrupted manifest.json (${err.message}). Fix the JSON manually or remove the file to start fresh; refusing to clobber prior install records.`
+      `Corrupted manifest.json (${getErrorMessage(err)}). Fix the JSON manually or remove the file to start fresh; refusing to clobber prior install records.`
     );
   }
   const result = validateInstalled(data);
@@ -173,9 +186,7 @@ async function readTokensLock(projectRoot) {
     }
     return parsed.data;
   } catch (err) {
-    logger.warn(
-      `Failed to parse tokens-lock.json: ${err.message}`
-    );
+    logger.warn(`Failed to parse tokens-lock.json: ${getErrorMessage(err)}`);
     return null;
   }
 }
@@ -187,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,
@@ -206,7 +220,7 @@ async function readSkillsLock(projectRoot) {
     return result.data;
   } catch (err) {
     logger.warn(
-      `Failed to parse skills manifest.lock.json: ${err.message}`
+      `Failed to parse skills manifest.lock.json: ${getErrorMessage(err)}`
     );
     return null;
   }
@@ -221,6 +235,12 @@ async function writeSkillsLock(projectRoot, lock) {
   await writeFileSafe(lockPath, JSON.stringify(lock, null, 2) + "\n");
   logger.debug(`Wrote skills lock \u2192 ${lockPath}`);
 }
+function findInstalledPackage(installed, packageName) {
+  if (!installed) return null;
+  const matches = installed.installed.filter((p) => p.package === packageName);
+  if (matches.length === 0) return null;
+  return matches[matches.length - 1] ?? null;
+}
 
 // src/core/skills-client.ts
 import * as path3 from "path";
@@ -255,7 +275,9 @@ import * as path7 from "path";
 import * as fs5 from "fs/promises";
 import {
   replaceManagedRegion,
-  hasManagedRegion
+  hasManagedRegion,
+  extractFrontmatter,
+  replaceFrontmatter
 } from "@teamix-evo/registry";
 
 // src/ide/QoderAdapter.ts
@@ -339,6 +361,8 @@ async function loadTemplateFile(filePath) {
 // src/utils/path.ts
 import * as path6 from "path";
 import * as fs4 from "fs/promises";
+import { createRequire as createRequire2 } from "module";
+var require3 = createRequire2(import.meta.url);
 function resolveSourcePath(source, variantDir, packageRoot) {
   if (source.startsWith("_template/")) {
     return path6.join(packageRoot, source);
@@ -358,9 +382,14 @@ async function walkDir(dir) {
   }
   return files;
 }
+function resolveTokensPackageRoot(packageName) {
+  const pkgJson = require3.resolve(`${packageName}/package.json`);
+  return path6.dirname(pkgJson);
+}
 
 // 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(
@@ -394,9 +423,9 @@ async function writeSkillSource(skill, options) {
   const { data, packageRoot, projectRoot } = options;
   const sourceAbs = path7.resolve(packageRoot, skill.source);
   const targetDir = getSkillsSourceDir(projectRoot, skill.name);
-  const stat2 = await fs5.stat(sourceAbs);
+  const stat5 = await fs5.stat(sourceAbs);
   const records = [];
-  if (stat2.isFile()) {
+  if (stat5.isFile()) {
     const targetFile = path7.join(targetDir, "SKILL.md");
     const content = await renderSkillContent(sourceAbs, skill, data);
     await writeFileSafe(targetFile, content);
@@ -463,6 +492,10 @@ async function writeMirrorContent(targetFile, sourceContent, managedRegions, sou
     return existing;
   }
   let merged = existing;
+  const upstreamFm = extractFrontmatter(sourceContent);
+  if (upstreamFm) {
+    merged = replaceFrontmatter(merged, upstreamFm);
+  }
   for (const id of matchedRegions) {
     const newRegion = extractRegionBody(sourceContent, id);
     if (newRegion === null) continue;
@@ -524,11 +557,7 @@ async function updateSkills(options) {
     if (idFilter && !idFilter.has(skill.id)) continue;
     const skillIdes = skill.ides.filter((i) => ides.includes(i));
     if (skillIdes.length === 0) continue;
-    const sourceRecords = await rewriteSkillSource(
-      skill,
-      options,
-      summary
-    );
+    const sourceRecords = await rewriteSkillSource(skill, options, summary);
     updated.push(...sourceRecords);
     for (const ide of skillIdes) {
       const mirrorRecords = await mirrorSkillToIde(
@@ -546,8 +575,8 @@ async function rewriteSkillSource(skill, options, summary) {
   const { data, packageRoot, projectRoot } = options;
   const sourceAbs = path7.resolve(packageRoot, skill.source);
   const targetDir = getSkillsSourceDir(projectRoot, skill.name);
-  const stat2 = await fs5.stat(sourceAbs);
-  if (!stat2.isFile()) {
+  const stat5 = await fs5.stat(sourceAbs);
+  if (!stat5.isFile()) {
     await ensureDir(targetDir);
     const entries = await walkDir(sourceAbs);
     const records = [];
@@ -618,6 +647,10 @@ async function rewriteSingleFile(args) {
   }
   const current = await readFileOrNull(targetFile);
   let merged = current ?? newContent;
+  const upstreamFm = extractFrontmatter(newContent);
+  if (upstreamFm) {
+    merged = replaceFrontmatter(merged, upstreamFm);
+  }
   for (const regionId of managedRegions ?? []) {
     const re = new RegExp(
       `<!-- teamix-evo:managed:start id="${escapeRegExp(
@@ -649,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));
@@ -692,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) {
@@ -700,7 +846,7 @@ async function removeSkillFiles(records) {
       removed.push(r.target);
     } catch (err) {
       if (err.code !== "ENOENT") {
-        logger.warn(`Failed to remove ${r.target}: ${err.message}`);
+        logger.warn(`Failed to remove ${r.target}: ${getErrorMessage(err)}`);
       }
     }
   }
@@ -735,11 +881,14 @@ async function ensureMcpJson(projectRoot) {
   const mcpPath = path8.join(projectRoot, ".mcp.json");
   if (await fileExists(mcpPath)) return "exists";
   try {
-    await writeFileSafe(mcpPath, JSON.stringify(MCP_JSON_CONTENT, null, 2) + "\n");
+    await writeFileSafe(
+      mcpPath,
+      JSON.stringify(MCP_JSON_CONTENT, null, 2) + "\n"
+    );
     logger.debug(`Wrote .mcp.json \u2192 ${mcpPath}`);
     return "created";
   } catch (err) {
-    logger.warn(`Failed to write .mcp.json: ${err.message}`);
+    logger.warn(`Failed to write .mcp.json: ${getErrorMessage(err)}`);
     return "failed";
   }
 }
@@ -784,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,
@@ -802,6 +967,7 @@ async function runSkillsInit(options) {
     scope,
     onlyIds,
     skippedSkillIds,
+    outdatedSkills,
     existing,
     existingConfig
   });
@@ -842,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",
@@ -857,7 +1024,8 @@ async function runSkillsAdd(options) {
       fileCount: 0,
       resources: [],
       addedSkillIds: [],
-      skippedSkillIds
+      skippedSkillIds,
+      outdatedSkills
     };
   }
   return finalizeSkillsInstall({
@@ -871,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);
@@ -899,6 +1109,7 @@ async function finalizeSkillsInstall(args) {
     scope,
     onlyIds,
     skippedSkillIds,
+    outdatedSkills,
     existing,
     existingConfig
   } = args;
@@ -912,8 +1123,8 @@ async function finalizeSkillsInstall(args) {
     onlyIds
   });
   const config = existingConfig ?? {
-    $schema: "https://teamix-evo.dev/schema/config/v1.json",
-    schemaVersion: 1,
+    $schema: "https://teamix-evo.dev/schema/config/v2.json",
+    schemaVersion: 2,
     ide: ideIdent,
     packages: {}
   };
@@ -964,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,
@@ -974,7 +1189,8 @@ async function finalizeSkillsInstall(args) {
     fileCount: result.count,
     resources: result.resources,
     addedSkillIds: onlyIds,
-    skippedSkillIds
+    skippedSkillIds,
+    outdatedSkills: outdatedSkills ?? []
   };
 }
 function mergeInstalledResources(existing, next) {
@@ -996,7 +1212,6 @@ var CONSUMER_OVERRIDES_FILE = "tokens.overrides.css";
 var EMPTY_OVERRIDES_TEMPLATE = `/* User-owned token overrides \u2014 frozen on subsequent installs. */
 /* See @teamix-evo/tokens variant theme.css for available CSS custom properties. */
 `;
-var require3 = createRequire2(import.meta.url);
 async function runTokensInit(options) {
   const { projectRoot, variant, ide } = options;
   const packageName = options.packageName ?? DEFAULT_TOKENS_PACKAGE;
@@ -1060,8 +1275,8 @@ Run \`npx teamix-evo@latest tokens list-variants\` to see all options.`
     JSON.stringify(lock, null, 2) + "\n"
   );
   const config = {
-    $schema: "https://teamix-evo.dev/schema/config/v1.json",
-    schemaVersion: 1,
+    $schema: "https://teamix-evo.dev/schema/config/v2.json",
+    schemaVersion: 2,
     ide: existingConfig?.ide ?? ide,
     packages: {
       ...existingConfig?.packages ?? {},
@@ -1114,7 +1329,9 @@ async function tryAutoInstallVariantSkills(args) {
     manifestSkillIds = new Set(manifest.skills.map((s) => s.id));
   } catch (err) {
     logger.warn(
-      `Skipping skills auto-install: could not load skills manifest (${err.message}).`
+      `Skipping skills auto-install: could not load skills manifest (${getErrorMessage(
+        err
+      )}).`
     );
     return {
       attempted: [],
@@ -1164,7 +1381,7 @@ async function tryAutoInstallVariantSkills(args) {
     };
   } catch (err) {
     logger.warn(
-      `Skills auto-install failed (continuing): ${err.message}`
+      `Skills auto-install failed (continuing): ${getErrorMessage(err)}`
     );
     return {
       attempted: desired,
@@ -1178,12 +1395,12 @@ async function installVariantFile(fileRelToPackage, packageRoot, projectRoot) {
   const sourceAbs = path9.join(packageRoot, fileRelToPackage);
   const base = path9.basename(fileRelToPackage);
   if (base === "theme.css") {
-    const targetRel = path9.posix.join(
-      CONSUMER_TOKENS_DIR,
-      CONSUMER_THEME_FILE
-    );
+    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}`,
@@ -1218,10 +1435,6 @@ async function installVariantFile(fileRelToPackage, packageRoot, projectRoot) {
   }
   return null;
 }
-function resolveTokensPackageRoot(packageName) {
-  const pkgJson = require3.resolve(`${packageName}/package.json`);
-  return path9.dirname(pkgJson);
-}
 async function listTokenVariants(packageName = DEFAULT_TOKENS_PACKAGE, packageRoot) {
   const root = packageRoot ?? resolveTokensPackageRoot(packageName);
   const catalog = await loadTokensPackageManifest(root);
@@ -1438,8 +1651,8 @@ async function runUiInit(options) {
   const tsx = options.tsx ?? true;
   const rsc = options.rsc ?? false;
   const config = existingConfig ?? {
-    $schema: "https://teamix-evo.dev/schema/config/v1.json",
-    schemaVersion: 1,
+    $schema: "https://teamix-evo.dev/schema/config/v2.json",
+    schemaVersion: 2,
     ide: ideIdent,
     packages: {}
   };
@@ -1568,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)}`);
@@ -1607,7 +1823,7 @@ async function removeUiFiles(records) {
       removed.push(r.target);
     } catch (err) {
       if (err.code !== "ENOENT") {
-        logger.warn(`Failed to remove ${r.target}: ${err.message}`);
+        logger.warn(`Failed to remove ${r.target}: ${getErrorMessage(err)}`);
       }
     }
   }
@@ -1938,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);
@@ -1958,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) {
@@ -1985,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;
@@ -2003,126 +2245,2639 @@ 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/installer.ts
-import * as path14 from "path";
+// src/core/agents-md.ts
 import * as fs10 from "fs/promises";
-async function installResources(options) {
-  const { projectRoot, manifest, data, variantDir, packageRoot } = options;
-  const installedResources = [];
-  for (const resource of manifest.resources) {
-    logger.debug(`Installing resource: ${resource.id} \u2192 ${resource.target}`);
-    if (resource.recursive) {
-      const results = await installRecursiveResource(
-        resource,
-        projectRoot,
-        data,
-        variantDir,
-        packageRoot
-      );
-      installedResources.push(...results);
+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)
+  );
+  const sections = [];
+  const missingSkillIds = [];
+  for (const id of ordered) {
+    const { section, missing } = await renderSkillSection(projectRoot, id);
+    sections.push(section);
+    if (missing) missingSkillIds.push(id);
+  }
+  const target = path14.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 (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 {
-      const result = await installSingleResource(
-        resource,
-        projectRoot,
-        data,
-        variantDir,
-        packageRoot
-      );
-      installedResources.push(result);
+      outputContent = fullTemplate;
+      merge = "overwritten";
     }
   }
+  await fs10.writeFile(target, outputContent, "utf8");
   return {
-    resources: installedResources,
-    count: installedResources.length
+    path: target,
+    skillCount: ordered.length,
+    missingSkillIds,
+    backedUp: targetExists,
+    merge
   };
 }
-async function installSingleResource(resource, projectRoot, data, variantDir, packageRoot) {
-  const sourcePath = resolveSourcePath(
-    resource.source,
-    variantDir,
-    packageRoot
+function bucketRank(id) {
+  if (id.startsWith("teamix-evo-design-")) return 0;
+  if (id.startsWith("teamix-evo-code-")) return 1;
+  return 2;
+}
+async function renderSkillSection(projectRoot, skillId) {
+  const skillPath = path14.join(
+    getSkillsSourceDir(projectRoot, skillId),
+    "SKILL.md"
   );
-  const targetPath = path14.join(projectRoot, resource.target);
-  let content;
-  if (resource.template) {
-    const templateContent = await loadTemplateFile(sourcePath);
-    content = renderTemplate(templateContent, data);
-  } else {
-    content = await fs10.readFile(sourcePath, "utf-8");
+  const lines = [];
+  lines.push(`### ${skillId}`);
+  let parts = null;
+  let missing = false;
+  try {
+    const raw = await fs10.readFile(skillPath, "utf8");
+    parts = extractDescriptionParts(raw);
+  } catch {
+    missing = true;
+  }
+  if (parts?.capability) {
+    lines.push(`- ${parts.capability}`);
+  }
+  lines.push(
+    `- **TRIGGER**: ${parts?.trigger ?? "\u672A\u914D\u7F6E\u89E6\u53D1\u6761\u4EF6\uFF0C\u9700\u624B\u52A8\u6FC0\u6D3B\u8BE5 skill\u3002"}`
+  );
+  lines.push(
+    `- **SKIP**: ${parts?.skip ?? "\u672A\u914D\u7F6E\u8DF3\u8FC7\u6761\u4EF6\uFF0C\u6309 TRIGGER \u515C\u5E95\u5224\u5B9A\u3002"}`
+  );
+  if (parts?.coordinates) {
+    lines.push(`- **Coordinates with**: ${parts.coordinates}`);
+  }
+  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
+
+> \u672C\u5DE5\u7A0B\u5DF2\u88C5\u914D Teamix Evo AI skills\u3002AI \u52A9\u624B\u5728\u4EE5\u4E0B\u573A\u666F\u4E0B**\u5FC5\u987B\u5148\u8BFB\u5BF9\u5E94 skill** \u518D\u52A8\u624B\u3002
+> \u672C\u6587\u4EF6\u7531 \`teamix-evo init\` / \`create-teamix-evo\` \u81EA\u52A8\u751F\u6210\uFF08regenerable\uFF0C[ADR 0038](https://github.com/teamix-evo/teamix-evo/blob/main/docs/adr/0038-create-agents-md-skill-trigger-fallback.md)\uFF09\uFF0C\u5237\u65B0\u65B9\u5F0F\u89C1\u5E95\u90E8\u3002
+
+## \u5DF2\u88C5 Skills\uFF08variant: ${variant}\uFF09
+
+${skillBlock}
+
+## \u89E6\u53D1\u515C\u5E95\u89C4\u5219
+
+- \u5199\u65B0 \`.tsx\` / \`.ts\` \u524D\uFF0C\u5BF9\u7167\u4E0A\u8FF0 TRIGGER \u5224\u5B9A\u662F\u5426\u547D\u4E2D
+- \u547D\u4E2D\u5219\u5148\u8BFB\u5BF9\u5E94 \`SKILL.md\`\uFF0C\u518D\u52A8\u624B\uFF1B\u4E8C\u8005\u540C\u65F6\u547D\u4E2D\u5219\u4E24\u4E2A\u90FD\u8BFB
+- \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`;
+}
+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;
+  const allLines = description.split("\n").map((l) => l.trim()).filter(Boolean);
+  let capability = "";
+  for (const line of allLines) {
+    if (/^(TRIGGER when:|SKIP:|Coordinates with:)/i.test(line)) break;
+    capability = capability ? `${capability} ${line}` : line;
   }
-  await writeFileSafe(targetPath, content);
-  const hash = computeHash(content);
-  logger.debug(`  Written: ${resource.target} (${resource.updateStrategy})`);
   return {
-    id: resource.id,
-    target: resource.target,
-    hash,
-    strategy: resource.updateStrategy
+    capability: capability.trim(),
+    trigger: extractSection(description, "TRIGGER when:"),
+    skip: extractSection(description, "SKIP:"),
+    coordinates: extractSection(description, "Coordinates with:")
   };
 }
-async function installRecursiveResource(resource, projectRoot, data, variantDir, packageRoot) {
-  const sourcePath = resolveSourcePath(
-    resource.source,
-    variantDir,
-    packageRoot
-  );
-  const targetDir = path14.join(projectRoot, resource.target);
-  const results = [];
-  await ensureDir(targetDir);
-  const entries = await walkDir(sourcePath);
-  for (const entry of entries) {
-    const relPath = path14.relative(sourcePath, entry);
-    let targetFile = path14.join(targetDir, relPath);
-    if (resource.template && targetFile.endsWith(".hbs")) {
-      targetFile = targetFile.slice(0, -4);
+function extractDescriptionBlock(fileContent) {
+  const lines = fileContent.split("\n");
+  if (lines[0]?.trim() !== "---") return null;
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      endIdx = i;
+      break;
     }
-    let content;
-    if (resource.template && entry.endsWith(".hbs")) {
-      const templateContent = await loadTemplateFile(entry);
-      content = renderTemplate(templateContent, data);
-    } else {
-      content = await fs10.readFile(entry, "utf-8");
+  }
+  if (endIdx === -1) return null;
+  const fmLines = lines.slice(1, endIdx);
+  let startIdx = -1;
+  let inlineValue = null;
+  let blockMode = "inline";
+  for (let i = 0; i < fmLines.length; i++) {
+    const m = fmLines[i]?.match(/^description:\s*(\|[+-]?|>[+-]?)?\s*(.*)$/);
+    if (m) {
+      startIdx = i;
+      const indicator = (m[1] ?? "").trim();
+      const rest = m[2] ?? "";
+      if (indicator.startsWith("|")) blockMode = "literal";
+      else if (indicator.startsWith(">")) blockMode = "folded";
+      else {
+        blockMode = "inline";
+        inlineValue = rest;
+      }
+      break;
     }
-    await writeFileSafe(targetFile, content);
-    const hash = computeHash(content);
-    const targetRel = path14.relative(projectRoot, targetFile);
-    results.push({
-      id: `${resource.id}:${relPath}`,
-      target: targetRel,
-      hash,
-      strategy: resource.updateStrategy
-    });
-    logger.debug(`  Written: ${targetRel}`);
   }
-  return results;
+  if (startIdx === -1) return null;
+  if (blockMode === "inline") {
+    return inlineValue ?? "";
+  }
+  const body = [];
+  let blockIndent = -1;
+  for (let i = startIdx + 1; i < fmLines.length; i++) {
+    const line = fmLines[i] ?? "";
+    if (line.trim() === "") {
+      body.push("");
+      continue;
+    }
+    const indentMatch = line.match(/^(\s+)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+    if (indent === 0) break;
+    if (blockIndent === -1) blockIndent = indent;
+    if (indent < blockIndent) break;
+    body.push(line.slice(blockIndent));
+  }
+  while (body.length > 0 && body[body.length - 1] === "") body.pop();
+  return body.join("\n");
+}
+function extractSection(description, marker) {
+  const markers = ["TRIGGER when:", "SKIP:", "Coordinates with:"];
+  const lines = description.split("\n");
+  let inSection = false;
+  const collected = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const startsWithMarker = trimmed.toLowerCase().startsWith(marker.toLowerCase());
+    if (!inSection && startsWithMarker) {
+      inSection = true;
+      collected.push(trimmed.slice(marker.length).trim());
+      continue;
+    }
+    if (inSection) {
+      const hitNextMarker = markers.some(
+        (m) => m !== marker && trimmed.toLowerCase().startsWith(m.toLowerCase())
+      );
+      if (hitNextMarker) break;
+      if (trimmed === "") {
+        if (collected[collected.length - 1] === "") break;
+        collected.push("");
+        continue;
+      }
+      collected.push(trimmed);
+    }
+  }
+  if (!inSection) return null;
+  const joined = collected.filter((l) => l !== "").join(" ").replace(/\s+/g, " ").trim();
+  return joined || null;
 }
 
-// src/core/registry-client.ts
-import * as path15 from "path";
+// src/core/init-detect.ts
 import * as fs11 from "fs/promises";
-import { createRequire as createRequire5 } from "module";
-import { loadVariantManifest } from "@teamix-evo/registry";
-var require6 = createRequire5(import.meta.url);
-function resolvePackageRoot4(packageName) {
+import * as path15 from "path";
+var IGNORED_TOP_LEVEL = /* @__PURE__ */ new Set([
+  ".git",
+  ".gitignore",
+  ".gitattributes",
+  ".gitkeep",
+  ".DS_Store",
+  "Thumbs.db",
+  ".idea",
+  ".vscode",
+  ".qoder",
+  ".claude",
+  "README.md",
+  "README",
+  "README.txt",
+  "LICENSE",
+  "LICENSE.md",
+  "LICENSE.txt"
+]);
+async function detectProjectState(cwd) {
+  const absCwd = path15.resolve(cwd);
+  const teamixDir = getTeamixDir(absCwd);
+  const hasTeamixDir = await fileExists(teamixDir);
+  if (hasTeamixDir) {
+    return {
+      state: "teamix-evo-installed",
+      cwd: absCwd,
+      hasTeamixDir: true,
+      hasPackageJson: await fileExists(path15.join(absCwd, "package.json")),
+      significantEntries: []
+    };
+  }
+  let entries;
+  try {
+    entries = await fs11.readdir(absCwd);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return {
+        state: "empty",
+        cwd: absCwd,
+        hasTeamixDir: false,
+        hasPackageJson: false,
+        significantEntries: []
+      };
+    }
+    throw err;
+  }
+  const significant = entries.filter((e) => !IGNORED_TOP_LEVEL.has(e));
+  const hasPackageJson = entries.includes("package.json");
+  if (significant.length === 0) {
+    return {
+      state: "empty",
+      cwd: absCwd,
+      hasTeamixDir: false,
+      hasPackageJson: false,
+      significantEntries: []
+    };
+  }
+  return {
+    state: "non-teamix-evo",
+    cwd: absCwd,
+    hasTeamixDir: false,
+    hasPackageJson,
+    significantEntries: significant.slice(0, 20).sort()
+  };
+}
+
+// src/core/init-conflicts.ts
+import * as crypto from "crypto";
+import * as fs12 from "fs/promises";
+import * as path16 from "path";
+var TAILWIND_CONFIG_CANDIDATES = [
+  "tailwind.config.ts",
+  "tailwind.config.js",
+  "tailwind.config.cjs",
+  "tailwind.config.mjs"
+];
+var TOKENS_FILE_CANDIDATES = [
+  "src/design-tokens.css",
+  "src/styles/design-tokens.css",
+  "src/styles/tokens.css"
+];
+var TOKENS_DIR_CANDIDATES = ["tokens"];
+var INDEX_CSS_CANDIDATES = [
+  "src/index.css",
+  "src/main.css",
+  "src/app.css",
+  "src/styles/index.css",
+  "src/styles/globals.css"
+];
+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);
+    return stat5.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function dirHasContent(target) {
+  try {
+    const entries = await fs12.readdir(target);
+    return entries.length > 0;
+  } catch {
+    return false;
+  }
+}
+function fingerprint(parts) {
+  const hash = crypto.createHash("sha256");
+  for (const p of [...parts].sort()) hash.update(p);
+  return `sha256:${hash.digest("hex").slice(0, 16)}`;
+}
+async function readPackageJson(cwd) {
+  const raw = await readFileOrNull(path16.join(cwd, "package.json"));
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function detectTailwindMajor(pkg) {
+  if (!pkg) return null;
+  const v = pkg.dependencies?.tailwindcss ?? pkg.devDependencies?.tailwindcss ?? null;
+  if (!v) return null;
+  const m = /(\d+)/.exec(v);
+  if (!m) return null;
+  const major = Number.parseInt(m[1], 10);
+  if (major === 3) return 3;
+  if (major === 4) return 4;
+  return null;
+}
+async function detectAgentsMd(cwd) {
+  const target = path16.join(cwd, "AGENTS.md");
+  const content = await readFileOrNull(target);
+  const exists = content !== null;
+  return {
+    key: "agents-md",
+    exists,
+    paths: exists ? ["AGENTS.md"] : [],
+    fingerprint: exists ? fingerprint([content]) : void 0,
+    recommendedStrategy: exists ? "merge-managed" : "overwrite",
+    availableStrategies: ["merge-managed", "overwrite", "skip"]
+  };
+}
+async function detectComponentsJson(cwd) {
+  const target = path16.join(cwd, "components.json");
+  const content = await readFileOrNull(target);
+  const exists = content !== null;
+  return {
+    key: "components-json",
+    exists,
+    paths: exists ? ["components.json"] : [],
+    fingerprint: exists ? fingerprint([content]) : void 0,
+    recommendedStrategy: exists ? "diff-prompt" : "overwrite",
+    availableStrategies: ["diff-prompt", "overwrite", "skip"]
+  };
+}
+async function detectTailwindConfig(cwd) {
+  const matched = [];
+  const contents = [];
+  for (const rel2 of TAILWIND_CONFIG_CANDIDATES) {
+    const c = await readFileOrNull(path16.join(cwd, rel2));
+    if (c !== null) {
+      matched.push(rel2);
+      contents.push(c);
+    }
+  }
+  const pkg = await readPackageJson(cwd);
+  const tailwindMajor = detectTailwindMajor(pkg);
+  const exists = matched.length > 0;
+  return {
+    key: "tailwind-config",
+    exists,
+    paths: matched,
+    fingerprint: exists ? fingerprint(contents) : void 0,
+    recommendedStrategy: exists ? "backup-overwrite" : "overwrite",
+    availableStrategies: ["backup-overwrite", "overwrite", "skip"],
+    meta: { tailwindMajor }
+  };
+}
+async function detectTokens(cwd) {
+  const matched = [];
+  const contents = [];
+  for (const rel2 of TOKENS_FILE_CANDIDATES) {
+    const c = await readFileOrNull(path16.join(cwd, rel2));
+    if (c !== null) {
+      matched.push(rel2);
+      contents.push(c);
+    }
+  }
+  for (const rel2 of TOKENS_DIR_CANDIDATES) {
+    const abs = path16.join(cwd, rel2);
+    if (await isDir(abs) && await dirHasContent(abs)) {
+      matched.push(`${rel2}/`);
+    }
+  }
+  const exists = matched.length > 0;
+  return {
+    key: "tokens",
+    exists,
+    paths: matched,
+    fingerprint: contents.length > 0 ? fingerprint(contents) : void 0,
+    recommendedStrategy: exists ? "migrate" : "overwrite",
+    availableStrategies: ["migrate", "coexist", "overwrite", "skip"]
+  };
+}
+async function detectIndexCss(cwd) {
+  const matched = [];
+  const contents = [];
+  for (const rel2 of INDEX_CSS_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: "index-css",
+    exists,
+    paths: matched,
+    fingerprint: exists ? fingerprint(contents) : void 0,
+    recommendedStrategy: exists ? "append" : "overwrite",
+    availableStrategies: ["append", "diff-prompt", "overwrite", "skip"]
+  };
+}
+async function detectShadcnSource(cwd) {
+  const matched = [];
+  for (const rel2 of SHADCN_FILE_CANDIDATES) {
+    if (await fileExists(path16.join(cwd, rel2))) matched.push(rel2);
+  }
+  for (const rel2 of SHADCN_DIR_CANDIDATES) {
+    const abs = path16.join(cwd, rel2);
+    if (await isDir(abs) && await dirHasContent(abs)) {
+      matched.push(`${rel2}/`);
+    }
+  }
+  let componentCount = 0;
+  try {
+    const uiDir = path16.join(cwd, "src/components/ui");
+    if (await isDir(uiDir)) {
+      const entries = await fs12.readdir(uiDir);
+      componentCount = entries.filter(
+        (e) => e.endsWith(".tsx") || e.endsWith(".ts")
+      ).length;
+    }
+  } catch {
+  }
+  const exists = matched.length > 0;
+  return {
+    key: "shadcn-source",
+    exists,
+    paths: matched,
+    recommendedStrategy: exists ? "skip-existing" : "overwrite",
+    availableStrategies: ["skip-existing", "per-file-prompt", "overwrite"],
+    meta: { componentCount }
+  };
+}
+async function detectConflicts(cwd) {
+  const absCwd = path16.resolve(cwd);
+  const items = await Promise.all([
+    detectAgentsMd(absCwd),
+    detectComponentsJson(absCwd),
+    detectTailwindConfig(absCwd),
+    detectTokens(absCwd),
+    detectIndexCss(absCwd),
+    detectShadcnSource(absCwd),
+    detectEslintConfig(absCwd),
+    detectStylelintConfig(absCwd)
+  ]);
+  return {
+    cwd: absCwd,
+    items,
+    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";
+import * as fs13 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. */
+/* See @teamix-evo/tokens variant theme.css for available CSS custom properties. */
+`;
+function buildMigrationBanner(legacyRel, isoTimestamp) {
+  return `/* === Migrated from ${legacyRel} on ${isoTimestamp} === */
+`;
+}
+function computeBackupRel(legacyRel, isoTimestamp) {
+  const tsSafe = isoTimestamp.replace(/[:.]/g, "-");
+  return path17.posix.join(
+    ".teamix-evo",
+    ".backups",
+    `${legacyRel}.${tsSafe}.bak`
+  );
+}
+async function migrateLegacyTokens(options) {
+  const { projectRoot, legacyPaths, dryRun = false } = options;
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueLegacy = [];
+  for (const raw of legacyPaths) {
+    const norm = raw.split(path17.sep).join("/");
+    if (!seen.has(norm)) {
+      seen.add(norm);
+      uniqueLegacy.push(norm);
+    }
+  }
+  const overridesRel = path17.posix.join(
+    CONSUMER_TOKENS_DIR2,
+    CONSUMER_OVERRIDES_FILE2
+  );
+  const overridesAbs = path17.join(projectRoot, overridesRel);
+  const existingOverrides = await readFileOrNull(overridesAbs);
+  const overridesCreated = existingOverrides === null;
+  const baseContent = existingOverrides === null ? EMPTY_OVERRIDES_TEMPLATE2 : existingOverrides;
+  const migrated = [];
+  const skipped = [];
+  const isoTimestamp = (/* @__PURE__ */ new Date()).toISOString();
+  let appendedPayload = "";
+  for (const legacyRel of uniqueLegacy) {
+    const legacyAbs = path17.join(projectRoot, legacyRel);
+    const content = await readFileOrNull(legacyAbs);
+    if (content === null) {
+      skipped.push({ from: legacyRel, reason: "not-found" });
+      continue;
+    }
+    if (content.trim() === "") {
+      skipped.push({ from: legacyRel, reason: "empty" });
+      continue;
+    }
+    const banner = buildMigrationBanner(legacyRel, isoTimestamp);
+    const separator = appendedPayload === "" && baseContent.endsWith("\n\n") ? "" : "\n";
+    const block = `${separator}${banner}${content}${content.endsWith("\n") ? "" : "\n"}`;
+    appendedPayload += block;
+    const backupRel = dryRun ? null : computeBackupRel(legacyRel, isoTimestamp);
+    migrated.push({
+      from: legacyRel,
+      backupTo: backupRel,
+      bytesAppended: Buffer.byteLength(block, "utf-8")
+    });
+  }
+  if (dryRun || migrated.length === 0) {
+    return {
+      migrated,
+      skipped,
+      overridesPath: overridesRel,
+      overridesCreated: dryRun ? overridesCreated : false,
+      dryRun
+    };
+  }
+  await ensureDir(path17.dirname(overridesAbs));
+  const merged = baseContent + appendedPayload;
+  const tmp = overridesAbs + ".tmp";
+  await fs13.writeFile(tmp, merged, "utf-8");
+  await fs13.rename(tmp, overridesAbs);
+  for (const entry of migrated) {
+    const legacyAbs = path17.join(projectRoot, entry.from);
+    const backupAbs = path17.join(projectRoot, entry.backupTo);
+    await ensureDir(path17.dirname(backupAbs));
+    const srcContent = await readFileOrNull(legacyAbs);
+    if (srcContent === null) {
+      logger.debug(
+        `legacy-tokens-migrate: source disappeared before backup: ${entry.from}`
+      );
+      continue;
+    }
+    await fs13.writeFile(backupAbs, srcContent, "utf-8");
+    if (await fileExists(legacyAbs)) {
+      await fs13.unlink(legacyAbs);
+    }
+    logger.debug(
+      `legacy-tokens-migrate: ${entry.from} \u2192 ${overridesRel} (backup: ${entry.backupTo})`
+    );
+  }
+  return {
+    migrated,
+    skipped,
+    overridesPath: overridesRel,
+    overridesCreated,
+    dryRun: false
+  };
+}
+
+// src/core/snapshot.ts
+import * as fs14 from "fs/promises";
+import * as path18 from "path";
+var TEAMIX_DIR2 = ".teamix-evo";
+var SNAPSHOTS_DIR = ".snapshots";
+var LOGS_DIR = "logs";
+var META_FILE = "_meta.json";
+var DEFAULT_KEEP = 5;
+function isoToFsSafe(iso) {
+  return iso.replace(/[:.]/g, "-");
+}
+function fsSafeToIso(safe) {
+  return safe.replace(
+    /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})(Z)$/,
+    "$1T$2:$3:$4.$5$6"
+  );
+}
+async function createSnapshot(projectRoot, opts = {}) {
+  const teamixDir = path18.join(projectRoot, TEAMIX_DIR2);
+  try {
+    const stat5 = await fs14.stat(teamixDir);
+    if (!stat5.isDirectory()) return null;
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  const isoTs = (/* @__PURE__ */ new Date()).toISOString();
+  const ts = isoToFsSafe(isoTs);
+  const snapshotRoot = path18.join(teamixDir, SNAPSHOTS_DIR);
+  const target = path18.join(snapshotRoot, ts);
+  await fs14.mkdir(target, { recursive: true });
+  const entries = await fs14.readdir(teamixDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === SNAPSHOTS_DIR) continue;
+    if (entry.name === LOGS_DIR) continue;
+    const src = path18.join(teamixDir, entry.name);
+    const dst = path18.join(target, entry.name);
+    await fs14.cp(src, dst, { recursive: true });
+  }
+  const meta = {
+    ts: isoTs,
+    reason: opts.reason ?? "manual"
+  };
+  await fs14.writeFile(
+    path18.join(target, META_FILE),
+    JSON.stringify(meta, null, 2) + "\n",
+    "utf-8"
+  );
+  logger.debug(
+    `Snapshot created \u2192 ${path18.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 = path18.join(projectRoot, TEAMIX_DIR2, SNAPSHOTS_DIR);
+  let entries;
+  try {
+    entries = await fs14.readdir(snapshotRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  const result = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path18.join(snapshotRoot, entry.name);
+    let isoTs = null;
+    let reason = null;
+    try {
+      const raw = await fs14.readFile(path18.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(
+        parsed.reason
+      )) {
+        reason = parsed.reason;
+      }
+    } catch {
+      isoTs = fsSafeToIso(entry.name);
+    }
+    result.push({ ts: entry.name, isoTs, reason, path: dir });
+  }
+  result.sort((a, b) => a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0);
+  return result;
+}
+async function pruneSnapshots(projectRoot, keep = DEFAULT_KEEP, opts = {}) {
+  if (keep < 0)
+    throw new Error(`pruneSnapshots: keep must be >= 0, got ${keep}`);
+  const snapshots = await listSnapshots(projectRoot);
+  if (snapshots.length <= keep) return [];
+  const tail = snapshots.slice(keep);
+  const toRemove = opts.protectedTs ? tail.filter((s) => s.ts !== opts.protectedTs) : tail;
+  const removed = [];
+  for (const snap of toRemove) {
+    await fs14.rm(snap.path, { recursive: true, force: true });
+    removed.push(snap.ts);
+    logger.debug(`Pruned snapshot ${snap.ts}`);
+  }
+  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",
+  "button-group",
+  "input",
+  "form",
+  "card",
+  "collapsible",
+  "dialog",
+  "dropdown-menu",
+  "tabs",
+  "table",
+  "sidebar",
+  "page-shell",
+  "page-header"
+];
+var CRITICAL_STEPS = /* @__PURE__ */ new Set([
+  "tokens",
+  "skills",
+  "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"],
+  // 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";
+}
+function strategyImplemented(key, strategy) {
+  return IMPLEMENTED_STRATEGIES[key]?.includes(strategy) ?? false;
+}
+async function resolveUiEntries(options) {
+  if (options.uiEntries && options.uiEntries.length > 0) {
+    return [...options.uiEntries];
+  }
+  if (options.answers.uiSelection === "all") {
+    const { manifest } = await loadUiData("@teamix-evo/ui");
+    return manifest.entries.map((e) => e.id);
+  }
+  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) {
+    try {
+      snapshot = await createSnapshot(projectRoot, { reason: "init" });
+    } catch (err) {
+      snapshotError = getErrorMessage(err);
+    }
+  }
+  let aborted = false;
+  const firstFailure = {
+    value: null
+  };
+  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];
+    if (!strategy) return;
+    if (strategyImplemented(key, strategy)) return;
+    pending.push({
+      key,
+      strategy,
+      reason: `Strategy "${strategy}" requires the managed-region engine (batch 4); recorded for follow-up.`
+    });
+  }
+  function recordFailure(name, err) {
+    const message = getErrorMessage(err);
+    record({ name, status: "fail", detail: message });
+    if (!firstFailure.value)
+      firstFailure.value = { step: name, error: message };
+    if (CRITICAL_STEPS.has(name)) aborted = true;
+  }
+  const tokensDecision = answers.conflictDecisions.tokens;
+  const legacyTokensPaths = options.legacyTokensPaths ?? [];
+  const wantMigrate = tokensDecision === "migrate" && legacyTokensPaths.length > 0;
+  if (tokensDecision === "skip") {
+    record({
+      name: "tokens",
+      status: "skip",
+      detail: "conflict strategy = skip"
+    });
+  } else if (dryRun) {
+    const planDetail = wantMigrate ? `runTokensInit(variant=${answers.variant}); migrateLegacyTokens(${legacyTokensPaths.length} file${legacyTokensPaths.length === 1 ? "" : "s"})` : `runTokensInit(variant=${answers.variant})`;
+    record({
+      name: "tokens",
+      status: "planned",
+      detail: planDetail
+    });
+  } else {
+    try {
+      const result = await runTokensInit({
+        projectRoot,
+        variant: answers.variant,
+        ide
+      });
+      let detail = result.status === "installed" ? `${result.packageName}@${result.version} (${result.count} files)` : result.status;
+      if (wantMigrate) {
+        try {
+          const m = await migrateLegacyTokens({
+            projectRoot,
+            legacyPaths: legacyTokensPaths
+          });
+          detail += `; migrated ${m.migrated.length}/${legacyTokensPaths.length} legacy file${legacyTokensPaths.length === 1 ? "" : "s"} \u2192 ${m.overridesPath}`;
+          if (m.skipped.length > 0) {
+            detail += ` (skipped ${m.skipped.length})`;
+          }
+        } catch (err) {
+          detail += `; migrate failed: ${getErrorMessage(err)}`;
+        }
+      }
+      record({
+        name: "tokens",
+        status: "ok",
+        detail,
+        changes: deriveTokensChanges(result, projectRoot)
+      });
+    } catch (err) {
+      recordFailure("tokens", err);
+    }
+  }
+  recordPending("tokens");
+  const codeSkillId = `teamix-evo-code-${answers.variant}`;
+  if (dryRun) {
+    record({
+      name: "skills",
+      status: "planned",
+      detail: `runSkillsAdd(${codeSkillId})`
+    });
+  } else if (aborted) {
+    record({
+      name: "skills",
+      status: "skip",
+      detail: "aborted: earlier critical step failed"
+    });
+  } else {
+    try {
+      const result = await runSkillsAdd({
+        projectRoot,
+        names: [codeSkillId],
+        ides: answers.ides,
+        scope: answers.scope,
+        ide
+      });
+      record({
+        name: "skills",
+        status: "ok",
+        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);
+    }
+  }
+  const agentsMdDecision = answers.conflictDecisions["agents-md"];
+  const agentsMdSkillIds = [
+    `teamix-evo-design-${answers.variant}`,
+    codeSkillId
+  ];
+  if (agentsMdDecision === "skip") {
+    record({
+      name: "agents-md",
+      status: "skip",
+      detail: "conflict strategy = skip"
+    });
+  } else if (dryRun) {
+    record({
+      name: "agents-md",
+      status: "planned",
+      detail: `runGenerateAgentsMd(${agentsMdSkillIds.length} skills)`
+    });
+  } else {
+    try {
+      const result = await runGenerateAgentsMd({
+        projectRoot,
+        variant: answers.variant,
+        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(", ")})` : ""}`,
+        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);
+    }
+  }
+  recordPending("agents-md");
+  const componentsJsonDecision = answers.conflictDecisions["components-json"];
+  const shadcnDecision = answers.conflictDecisions["shadcn-source"];
+  const skipUiInit = !answers.withUi || componentsJsonDecision === "skip";
+  if (skipUiInit) {
+    record({
+      name: "ui-init",
+      status: "skip",
+      detail: !answers.withUi ? "withUi = false" : "components.json conflict strategy = skip"
+    });
+    record({
+      name: "ui-add",
+      status: "skip",
+      detail: !answers.withUi ? "withUi = false" : "components.json conflict strategy = skip"
+    });
+  } else if (dryRun) {
+    record({
+      name: "ui-init",
+      status: "planned",
+      detail: "runUiInit()"
+    });
+    const entries = await resolveUiEntries(options).catch(() => [
+      ...BASELINE_UI_ENTRIES
+    ]);
+    record({
+      name: "ui-add",
+      status: "planned",
+      detail: `runUiAdd(${entries.length} entries: ${entries.slice(0, 3).join(", ")}${entries.length > 3 ? "\u2026" : ""})`
+    });
+  } else {
+    if (aborted) {
+      record({
+        name: "ui-init",
+        status: "skip",
+        detail: "aborted: earlier critical step failed"
+      });
+      record({
+        name: "ui-add",
+        status: "skip",
+        detail: "aborted: earlier critical step failed"
+      });
+    } else {
+      let uiInitOk = false;
+      try {
+        const initResult = await runUiInit({ projectRoot, ide });
+        record({
+          name: "ui-init",
+          status: "ok",
+          detail: initResult.status === "installed" ? "config.json packages.ui written" : initResult.status
+        });
+        uiInitOk = true;
+      } catch (err) {
+        recordFailure("ui-init", err);
+      }
+      if (!uiInitOk) {
+        record({
+          name: "ui-add",
+          status: "skip",
+          detail: "aborted: ui-init failed"
+        });
+      } else if (shadcnDecision === "skip") {
+        record({
+          name: "ui-add",
+          status: "skip",
+          detail: "shadcn-source conflict strategy = skip"
+        });
+      } else {
+        try {
+          const entries = await resolveUiEntries(options);
+          const addResult = await runUiAdd({
+            projectRoot,
+            ids: entries,
+            // 'overwrite' strategy → overwrite=true; everything else (incl.
+            // 'skip-existing' which is the default) → overwrite=false.
+            overwrite: shadcnDecision === "overwrite"
+          });
+          record({
+            name: "ui-add",
+            status: "ok",
+            detail: `${addResult.orderedIds.length} entries (${addResult.written} written, ${addResult.skipped} skipped)`,
+            changes: deriveUiAddChanges(addResult, projectRoot)
+          });
+        } catch (err) {
+          recordFailure("ui-add", err);
+        }
+      }
+    }
+  }
+  recordPending("components-json");
+  recordPending("shadcn-source");
+  if (!answers.withLint) {
+    record({
+      name: "lint",
+      status: "skip",
+      detail: "withLint = false"
+    });
+  } else if (dryRun) {
+    record({
+      name: "lint",
+      status: "planned",
+      detail: "runLintInit()"
+    });
+  } 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,
+        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: detailParts.join(" / "),
+        changes: deriveLintChanges(result)
+      });
+    } catch (err) {
+      recordFailure("lint", err);
+    }
+  }
+  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;
+  if (firstFailure.value) {
+    out.resumeHint = {
+      failedAt: firstFailure.value.step,
+      completed: steps.filter((s) => s.status === "ok").map((s) => s.name),
+      failed: steps.filter((s) => s.status === "fail").map((s) => s.name),
+      error: firstFailure.value.error,
+      // Every sub-step is idempotent (returns `already-initialized` when its
+      // state file already exists), so a plain re-run resumes from the
+      // failed step. A richer --resume model lands with batch 3 (lock
+      // snapshot + restore).
+      resumeCommand: "teamix-evo init"
+    };
+  }
+  return out;
+}
+
+// src/core/project-update.ts
+import * as path25 from "path";
+import {
+  loadTokensPackageManifest as loadTokensPackageManifest3,
+  getVariantEntry as getVariantEntry3
+} from "@teamix-evo/registry";
+
+// src/core/tokens-update.ts
+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 path20 from "path";
+var TEAMIX_DIR3 = ".teamix-evo";
+var HINTS_DIR = ".upgrade-hints";
+function isoToFsSafe2(iso) {
+  return iso.replace(/[:.]/g, "-");
+}
+async function writeTokensUpgradeHint(options) {
+  if (options.renames.length === 0) return null;
+  const isoTs = options.isoTs ?? (/* @__PURE__ */ new Date()).toISOString();
+  const fsTs = isoToFsSafe2(isoTs);
+  const filename = `tokens-${fsTs}.json`;
+  const target = path20.join(
+    options.projectRoot,
+    TEAMIX_DIR3,
+    HINTS_DIR,
+    filename
+  );
+  const payload = {
+    schemaVersion: 1,
+    ts: isoTs,
+    package: "tokens",
+    trigger: options.trigger,
+    fromVariant: options.fromVariant,
+    toVariant: options.toVariant,
+    fromVersion: options.fromVersion,
+    toVersion: options.toVersion,
+    renames: options.renames
+  };
+  await writeFileSafe(target, JSON.stringify(payload, null, 2) + "\n");
+  return {
+    path: target,
+    ts: fsTs,
+    renameCount: options.renames.length
+  };
+}
+function selectApplicableRenames(renames, fromVersion, toVersion) {
+  return renames.filter(
+    (r) => compareSemver2(r.sinceVersion, fromVersion) > 0 && compareSemver2(r.sinceVersion, toVersion) <= 0
+  ).sort((a, b) => compareSemver2(a.sinceVersion, b.sinceVersion));
+}
+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));
+  const bParts = bMain.split(".").map((n) => Number.parseInt(n, 10));
+  for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+    const ai = aParts[i] ?? 0;
+    const bi = bParts[i] ?? 0;
+    if (ai !== bi) return ai - bi;
+  }
+  if (aRest === "" && bRest !== "") return 1;
+  if (aRest !== "" && bRest === "") return -1;
+  return aRest.localeCompare(bRest, void 0, { numeric: true });
+}
+
+// src/core/managed-merge.ts
+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;
+  let match;
+  while ((match = re.exec(upstreamContent)) !== null) {
+    const id = match[1];
+    const body = match[2].replace(/^\n/, "").replace(/\n$/, "");
+    if (!hasManagedRegion3(updated, id)) {
+      throw new Error(
+        `Managed region "${id}" missing from consumer file \u2014 refusing to silently rewrite (ADR 0003).`
+      );
+    }
+    updated = replaceManagedRegion3(updated, id, body);
+  }
+  return updated;
+}
+
+// src/core/tokens-update.ts
+var DEFAULT_TOKENS_PACKAGE2 = "@teamix-evo/tokens";
+var CONSUMER_BASENAME_BY_UPSTREAM = {
+  "theme.css": "tokens.theme.css",
+  "overrides.css": "tokens.overrides.css"
+};
+async function runTokensUpdate(options) {
+  const { projectRoot } = options;
+  const packageName = options.packageName ?? DEFAULT_TOKENS_PACKAGE2;
+  const config = await readProjectConfig(projectRoot);
+  if (!config?.packages?.tokens) {
+    return { status: "not-initialized" };
+  }
+  const currentVariant = config.packages.tokens.variant;
+  const currentVersion = config.packages.tokens.version;
+  const packageRoot = options.packageRoot ?? resolveTokensPackageRoot(packageName);
+  const catalog = await loadTokensPackageManifest2(packageRoot);
+  const variantEntry = getVariantEntry2(catalog, currentVariant);
+  if (!variantEntry) {
+    throw new Error(
+      `Currently installed variant "${currentVariant}" no longer exists in ${packageName}@${catalog.version}. Available: ${catalog.variants.map((v) => v.name).join(", ")}. Run \`npx teamix-evo@latest tokens uninstall\` then \`npx teamix-evo@latest tokens init <variant>\` to switch.`
+    );
+  }
+  const upstreamByBasename = /* @__PURE__ */ new Map();
+  for (const fileRel of variantEntry.files) {
+    upstreamByBasename.set(
+      path21.basename(fileRel),
+      path21.join(packageRoot, fileRel)
+    );
+  }
+  const prior = await readInstalledManifest(projectRoot) ?? {
+    schemaVersion: 1,
+    installed: []
+  };
+  const installedIdx = prior.installed.findIndex(
+    (p) => p.package === packageName
+  );
+  const priorResources = installedIdx >= 0 ? prior.installed[installedIdx].resources : [];
+  const rewritten = [];
+  const managedReplaced = [];
+  const preserved = [];
+  const frozenDrift = [];
+  const refreshedResources = [];
+  for (const resource of priorResources) {
+    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") {
+      if (!upstreamAbs) {
+        refreshedResources.push(resource);
+        continue;
+      }
+      const content = await fs16.readFile(upstreamAbs, "utf-8");
+      await writeFileSafe(consumerAbs, content);
+      rewritten.push(resource.target);
+      refreshedResources.push({
+        ...resource,
+        hash: computeHash(content)
+      });
+      continue;
+    }
+    if (resource.strategy === "managed") {
+      if (!upstreamAbs || !await fileExists(consumerAbs)) {
+        refreshedResources.push(resource);
+        continue;
+      }
+      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);
+        managedReplaced.push(resource.target);
+      }
+      refreshedResources.push({
+        ...resource,
+        hash: computeHash(merged)
+      });
+      continue;
+    }
+    if (await fileExists(consumerAbs)) preserved.push(resource.target);
+    if (upstreamAbs) {
+      const upstreamContent = await fs16.readFile(upstreamAbs, "utf-8");
+      const upstreamHash = computeHash(upstreamContent);
+      if (resource.hash && upstreamHash !== resource.hash) {
+        frozenDrift.push({
+          target: resource.target,
+          reason: "upstream-changed"
+        });
+      }
+    }
+    refreshedResources.push(resource);
+  }
+  if (variantEntry.version === currentVersion) {
+    if (installedIdx >= 0) {
+      prior.installed[installedIdx] = {
+        ...prior.installed[installedIdx],
+        resources: refreshedResources
+      };
+      await writeInstalledManifest(projectRoot, prior);
+    }
+    return {
+      status: "up-to-date",
+      packageName,
+      variant: currentVariant,
+      version: currentVersion,
+      frozenDrift
+    };
+  }
+  const lock = {
+    schemaVersion: 1,
+    variant: {
+      name: variantEntry.name,
+      displayName: variantEntry.displayName,
+      version: variantEntry.version,
+      from: packageName
+    },
+    packageVersion: catalog.version,
+    linked: variantEntry.linked,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeFileSafe(
+    path21.join(projectRoot, ".teamix-evo", "tokens-lock.json"),
+    JSON.stringify(lock, null, 2) + "\n"
+  );
+  config.packages.tokens.version = variantEntry.version;
+  await writeProjectConfig(projectRoot, config);
+  if (installedIdx >= 0) {
+    prior.installed[installedIdx] = {
+      ...prior.installed[installedIdx],
+      version: variantEntry.version,
+      installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      resources: refreshedResources
+    };
+    await writeInstalledManifest(projectRoot, prior);
+  }
+  const renames = selectApplicableRenames(
+    variantEntry.renames ?? [],
+    currentVersion,
+    variantEntry.version
+  );
+  let hintPath;
+  if (renames.length > 0) {
+    const hint = await writeTokensUpgradeHint({
+      projectRoot,
+      trigger: "update",
+      fromVariant: currentVariant,
+      toVariant: currentVariant,
+      fromVersion: currentVersion,
+      toVersion: variantEntry.version,
+      renames
+    });
+    if (hint) hintPath = hint.path;
+  }
+  return {
+    status: "updated",
+    packageName,
+    variant: currentVariant,
+    from: currentVersion,
+    to: variantEntry.version,
+    rewritten,
+    managedReplaced,
+    preserved,
+    frozenDrift,
+    renames,
+    ...hintPath ? { hintPath } : {}
+  };
+}
+function lookupUpstreamBasename(consumerBasename) {
+  for (const [upstream, consumer] of Object.entries(
+    CONSUMER_BASENAME_BY_UPSTREAM
+  )) {
+    if (consumer === consumerBasename) return upstream;
+  }
+  return consumerBasename;
+}
+
+// src/core/ui-upgrade-detector.ts
+import * as fs17 from "fs/promises";
+import * as path22 from "path";
+var PACKAGE_NAME = {
+  ui: "@teamix-evo/ui",
+  "biz-ui": "@teamix-evo/biz-ui"
+};
+var ALIAS_KEY = {
+  ui: "components",
+  "biz-ui": "business"
+};
+var COMPONENT_FILE_RE = /\.(tsx|ts)$/;
+var SKIP_FILENAMES = /* @__PURE__ */ new Set(["index.ts", "index.tsx"]);
+async function detectComponentLineage(options) {
+  const { projectRoot, category } = options;
+  const config = options.config ?? await readProjectConfig(projectRoot);
+  const installed = options.installed ?? await readInstalledManifest(projectRoot);
+  const installDir = resolveInstallDir(category, config);
+  const installDirAbs = path22.join(projectRoot, installDir);
+  const installDirExists = await directoryExists(installDirAbs);
+  const hasComponentsJson = await fileExists(
+    path22.join(projectRoot, "components.json")
+  );
+  const installedPkg = findInstalledPackage(installed, PACKAGE_NAME[category]);
+  const registeredIds = installedPkg ? extractIds(installedPkg).sort() : [];
+  const onDiskIds = installDirExists ? await listComponentIds(installDirAbs) : [];
+  const registeredSet = new Set(registeredIds);
+  const unregisteredIds = onDiskIds.filter((id) => !registeredSet.has(id)).sort();
+  const lineage = classifyLineage({
+    hasInstalled: installedPkg !== null,
+    hasComponentsJson,
+    onDiskIds,
+    unregisteredIds
+  });
+  return {
+    category,
+    lineage,
+    installDir,
+    installDirExists,
+    hasComponentsJson,
+    registeredIds,
+    unregisteredIds,
+    installedVersion: installedPkg?.version ?? null,
+    installedVariant: installedPkg?.variant ?? null
+  };
+}
+function resolveInstallDir(category, config) {
+  const aliasMap = config?.packages?.ui?.aliases ?? config?.packages?.["biz-ui"]?.aliases ?? DEFAULT_UI_ALIASES;
+  const key = ALIAS_KEY[category];
+  return aliasMap[key] ?? DEFAULT_UI_ALIASES[key];
+}
+function extractIds(pkg) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const r of pkg.resources) {
+    const colon = r.id.indexOf(":");
+    ids.add(colon >= 0 ? r.id.slice(0, colon) : r.id);
+  }
+  return [...ids];
+}
+async function directoryExists(p) {
+  try {
+    const stat5 = await fs17.stat(p);
+    return stat5.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function listComponentIds(installDirAbs) {
+  const entries = await fs17.readdir(installDirAbs, { withFileTypes: true });
+  const ids = [];
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    if (SKIP_FILENAMES.has(e.name)) continue;
+    if (!COMPONENT_FILE_RE.test(e.name)) continue;
+    ids.push(e.name.replace(COMPONENT_FILE_RE, ""));
+  }
+  return ids.sort();
+}
+function classifyLineage(args) {
+  const { hasInstalled, hasComponentsJson, onDiskIds, unregisteredIds } = args;
+  if (hasInstalled) {
+    return unregisteredIds.length === 0 ? "teamix-evo" : "mixed";
+  }
+  if (onDiskIds.length === 0) return "absent";
+  return hasComponentsJson ? "shadcn-native" : "custom-only";
+}
+
+// src/core/ui-upgrade.ts
+import * as path24 from "path";
+import { createRequire as createRequire5 } from "module";
+import {
+  loadUiPackageManifest as loadUiPackageManifest3,
+  loadVariantUiPackageManifest as loadVariantUiPackageManifest2
+} from "@teamix-evo/registry";
+
+// src/core/ui-upgrade-staging.ts
+import * as path23 from "path";
+var TEAMIX_DIR4 = ".teamix-evo";
+var STAGING_DIR = ".upgrade-staging";
+var PACKAGE_NAME2 = {
+  ui: "@teamix-evo/ui",
+  "biz-ui": "@teamix-evo/biz-ui"
+};
+function isoToFsSafe3(iso) {
+  return iso.replace(/[:.]/g, "-");
+}
+async function buildUiUpgradeStaging(options) {
+  const { lineageReport, category } = options;
+  if (lineageReport.lineage !== "teamix-evo" && lineageReport.lineage !== "mixed") {
+    return null;
+  }
+  const installed = options.installed ?? await readInstalledManifest(options.projectRoot);
+  const installedPkg = findInstalledPackage(installed, PACKAGE_NAME2[category]);
+  if (!installedPkg) return null;
+  const isoTs = options.isoTs ?? (/* @__PURE__ */ new Date()).toISOString();
+  const fsTs = isoToFsSafe3(isoTs);
+  const stagingDir = path23.join(
+    options.projectRoot,
+    TEAMIX_DIR4,
+    STAGING_DIR,
+    `${category}-${fsTs}`
+  );
+  const entryMap = new Map(
+    options.manifest.entries.map((e) => [e.id, e])
+  );
+  const resByEntryId = collectResourcesByEntry(installedPkg.resources);
+  const onlyIds = options.onlyIds && options.onlyIds.length > 0 ? new Set(options.onlyIds) : null;
+  const entries = [];
+  for (const id of lineageReport.registeredIds) {
+    if (onlyIds && !onlyIds.has(id)) continue;
+    const built = await processRegistered({
+      id,
+      entry: entryMap.get(id),
+      resource: resByEntryId.get(id),
+      packageRoot: options.packageRoot,
+      entryPackageRoot: options.entryPackageRoot,
+      aliases: options.aliases,
+      stagingDir,
+      projectRoot: options.projectRoot,
+      category,
+      sourceVersion: options.manifest.version
+    });
+    if (built) entries.push(built);
+  }
+  for (const id of lineageReport.unregisteredIds) {
+    if (onlyIds && !onlyIds.has(id)) continue;
+    const built = await processForeign({
+      id,
+      installDirAbs: path23.join(options.projectRoot, lineageReport.installDir),
+      stagingDir,
+      projectRoot: options.projectRoot,
+      category
+    });
+    if (built) entries.push(built);
+  }
+  if (entries.length === 0) return null;
+  const byRisk = aggregateByRisk(entries);
+  const manifestOut = {
+    schemaVersion: 1,
+    ts: isoTs,
+    package: category,
+    trigger: options.trigger,
+    variant: lineageReport.installedVariant ?? "_flat",
+    fromVersion: lineageReport.installedVersion ?? "",
+    toVersion: options.manifest.version,
+    lineage: lineageReport.lineage,
+    summary: { total: entries.length, byRisk },
+    entries
+  };
+  await ensureDir(stagingDir);
+  await writeFileSafe(
+    path23.join(stagingDir, "meta.json"),
+    JSON.stringify(manifestOut, null, 2) + "\n"
+  );
+  return { stagingDir, manifest: manifestOut };
+}
+async function processRegistered(args) {
+  const { id, entry, resource, stagingDir, projectRoot, category } = args;
+  if (!resource) return null;
+  const currentSource = await readFileOrNull(resource.target);
+  if (currentSource === null) {
+    return buildBreakingEntry({
+      id,
+      category,
+      resource,
+      projectRoot,
+      stagingDir,
+      currentSource: "",
+      hint: "installed file missing on disk"
+    });
+  }
+  if (!entry) {
+    return buildBreakingEntry({
+      id,
+      category,
+      resource,
+      projectRoot,
+      stagingDir,
+      currentSource,
+      hint: "entry removed in upstream package"
+    });
+  }
+  const file = entry.files[0];
+  if (!file) return null;
+  const rootForEntry = args.entryPackageRoot?.get(id) ?? args.packageRoot;
+  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 = path23.extname(resource.target) || ".tsx";
+  const incomingExt = path23.extname(file.targetName) || currentExt;
+  const currentRel = `${id}/current${currentExt}`;
+  const incomingRel = `${id}/incoming${incomingExt}`;
+  await writeFileSafe(path23.join(stagingDir, currentRel), currentSource);
+  await writeFileSafe(path23.join(stagingDir, incomingRel), incomingTransformed);
+  const diff = classifyRisk({
+    currentHash: resource.hash,
+    incomingHash,
+    currentSource,
+    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: path23.relative(projectRoot, resource.target),
+      hash: resource.hash,
+      sourceLineage: "teamix-evo"
+    },
+    incoming: {
+      sourceVersion: args.sourceVersion,
+      hash: incomingHash,
+      relPath: incomingRel
+    },
+    diff,
+    promotion
+  };
+}
+async function processForeign(args) {
+  const { id, installDirAbs, stagingDir, projectRoot, category } = args;
+  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 = path23.extname(target);
+  const currentRel = `${id}/current${ext}`;
+  await writeFileSafe(path23.join(stagingDir, currentRel), raw);
+  return {
+    id,
+    category,
+    current: {
+      target: path23.relative(projectRoot, target),
+      hash: computeHash(raw),
+      sourceLineage: "custom"
+    },
+    diff: {
+      riskLevel: "foreign",
+      hints: [
+        "component is on disk but not registered in .teamix-evo/manifest.json",
+        "AI should propose: (a) ignore, (b) re-register via teamix-evo ui add, or (c) remove"
+      ],
+      filesChangedCount: 0
+    }
+  };
+}
+async function buildBreakingEntry(args) {
+  const ext = path23.extname(args.resource.target) || ".tsx";
+  const currentRel = `${args.id}/current${ext}`;
+  await writeFileSafe(
+    path23.join(args.stagingDir, currentRel),
+    args.currentSource
+  );
+  return {
+    id: args.id,
+    category: args.category,
+    current: {
+      target: path23.relative(args.projectRoot, args.resource.target),
+      hash: args.resource.hash,
+      sourceLineage: "teamix-evo"
+    },
+    diff: {
+      riskLevel: "breaking",
+      hints: [args.hint],
+      filesChangedCount: 0
+    }
+  };
+}
+function classifyRisk(args) {
+  if (args.currentHash === args.incomingHash) {
+    return { riskLevel: "unchanged", hints: [], filesChangedCount: 0 };
+  }
+  const curExports = extractExportNames(args.currentSource);
+  const newExports = extractExportNames(args.incomingSource);
+  const removedExports = setDiff(curExports, newExports);
+  const addedExports = setDiff(newExports, curExports);
+  const curVariants = extractCvaVariantValues(args.currentSource);
+  const newVariants = extractCvaVariantValues(args.incomingSource);
+  const removedVariants = setDiff(curVariants, newVariants);
+  const addedVariants = setDiff(newVariants, curVariants);
+  const hints = [];
+  for (const e of removedExports) hints.push(`removed export: ${e}`);
+  for (const e of addedExports) hints.push(`new export: ${e}`);
+  for (const v of removedVariants) hints.push(`removed cva variant: ${v}`);
+  for (const v of addedVariants) hints.push(`new cva variant: ${v}`);
+  if (args.multiFile) hints.push("multi-file entry; only first file staged");
+  let riskLevel;
+  if (removedExports.length > 0 || removedVariants.length > 0) {
+    riskLevel = "risky";
+  } else if (addedExports.length > 0 || addedVariants.length > 0 || args.multiFile) {
+    riskLevel = "upgradable-medium";
+  } else {
+    riskLevel = "upgradable-low";
+  }
+  return { riskLevel, hints, filesChangedCount: 1 };
+}
+function extractExportNames(src) {
+  const names = /* @__PURE__ */ new Set();
+  const re = /^\s*export\s+(?:default\s+)?(?:async\s+)?(?:const|let|var|function|class|interface|type|enum)\s+(\w+)/gm;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    if (m[1]) names.add(m[1]);
+  }
+  for (const dm of src.matchAll(/^\s*export\s+default\s+(\w+)\s*;/gm)) {
+    if (dm[1]) names.add(dm[1]);
+  }
+  return [...names];
+}
+function extractCvaVariantValues(src) {
+  const block = extractVariantsBlock(src);
+  if (block === null) return [];
+  const names = /* @__PURE__ */ new Set();
+  for (const groupBody of extractGroupBodies(block)) {
+    for (const km of groupBody.matchAll(/^\s*(?:['"]?)(\w+)(?:['"]?)\s*:/gm)) {
+      if (km[1]) names.add(km[1]);
+    }
+  }
+  return [...names];
+}
+function extractVariantsBlock(src) {
+  const idx = src.search(/\bvariants\s*:\s*\{/);
+  if (idx < 0) return null;
+  const open = src.indexOf("{", idx);
+  if (open < 0) return null;
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    const c = src[i];
+    if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) return src.slice(open + 1, i);
+    }
+  }
+  return null;
+}
+function* extractGroupBodies(block) {
+  const re = /(\w+)\s*:\s*\{/g;
+  let m;
+  while ((m = re.exec(block)) !== null) {
+    const open = block.indexOf("{", m.index);
+    if (open < 0) continue;
+    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) {
+          yield block.slice(open + 1, i);
+          re.lastIndex = i + 1;
+          break;
+        }
+      }
+    }
+  }
+}
+function setDiff(a, b) {
+  const bset = new Set(b);
+  return a.filter((x) => !bset.has(x)).sort();
+}
+function collectResourcesByEntry(resources) {
+  const out = /* @__PURE__ */ new Map();
+  for (const r of resources) {
+    const colon = r.id.indexOf(":");
+    const eid = colon >= 0 ? r.id.slice(0, colon) : r.id;
+    if (!out.has(eid)) out.set(eid, r);
+  }
+  return out;
+}
+function aggregateByRisk(entries) {
+  const out = {};
+  for (const e of entries) {
+    const k = e.diff.riskLevel;
+    out[k] = (out[k] ?? 0) + 1;
+  }
+  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 path24.dirname(pkgJsonPath);
+}
+async function buildStaging(args) {
+  const { category, projectRoot, aliases, lineageReport, trigger, onlyIds } = args;
+  if (category === "ui") {
+    const root = args.uiPackageRoot ?? resolvePackageRoot4("@teamix-evo/ui");
+    const manifest = await loadUiPackageManifest3(root);
+    return buildUiUpgradeStaging({
+      projectRoot,
+      category,
+      manifest,
+      packageRoot: root,
+      aliases,
+      lineageReport,
+      trigger,
+      onlyIds
+    });
+  }
+  const bizRoot = args.bizUiPackageRoot ?? resolvePackageRoot4("@teamix-evo/biz-ui");
+  const variant = lineageReport.installedVariant ?? "_flat";
+  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);
+  const entryPackageRoot = /* @__PURE__ */ new Map();
+  const merged = [];
+  for (const e of variantManifest.entries) {
+    entryPackageRoot.set(e.id, variantDir);
+    merged.push(e);
+  }
+  for (const e of uiManifest.entries) {
+    if (entryPackageRoot.has(e.id)) continue;
+    entryPackageRoot.set(e.id, uiRoot);
+    merged.push(e);
+  }
+  const synthetic = {
+    schemaVersion: 1,
+    package: "ui",
+    version: variantManifest.version,
+    engines: variantManifest.engines,
+    entries: merged
+  };
+  return buildUiUpgradeStaging({
+    projectRoot,
+    category,
+    manifest: synthetic,
+    packageRoot: variantDir,
+    entryPackageRoot,
+    aliases,
+    lineageReport,
+    trigger,
+    onlyIds
+  });
+}
+
+// src/core/project-update.ts
+var DEFAULT_TOKENS_PACKAGE3 = "@teamix-evo/tokens";
+var DEFAULT_SKILLS_PACKAGE4 = "@teamix-evo/skills";
+var CRITICAL_STEPS2 = /* @__PURE__ */ new Set(["tokens"]);
+async function runProjectUpdate(options) {
+  const { projectRoot, dryRun = false, onStep } = options;
+  const tokensPackage = options.tokensPackageName ?? DEFAULT_TOKENS_PACKAGE3;
+  const skillsPackage = options.skillsPackageName ?? DEFAULT_SKILLS_PACKAGE4;
+  const config = await readProjectConfig(projectRoot);
+  if (!config) {
+    return { status: "not-initialized" };
+  }
+  let snapshot = null;
+  let snapshotError;
+  if (!dryRun) {
+    try {
+      snapshot = await createSnapshot(projectRoot, { reason: "update" });
+    } catch (err) {
+      snapshotError = getErrorMessage(err);
+    }
+  }
+  const steps = [];
+  let aborted = false;
+  const firstFailure = { value: null };
+  function record(step) {
+    steps.push(step);
+    onStep?.(step);
+  }
+  function recordFailure(name, err) {
+    const message = getErrorMessage(err);
+    record({ name, status: "fail", detail: message });
+    if (!firstFailure.value) {
+      firstFailure.value = { step: name, error: message };
+    }
+    if (CRITICAL_STEPS2.has(name)) aborted = true;
+  }
+  let anyChanged = false;
+  if (!config.packages?.tokens) {
+    record({
+      name: "tokens",
+      status: "skip",
+      detail: "tokens not installed"
+    });
+  } else if (dryRun) {
+    try {
+      const plan = await planTokensUpdate(tokensPackage, config);
+      record({ name: "tokens", status: "planned", detail: plan });
+    } catch (err) {
+      recordFailure("tokens", err);
+    }
+  } else {
+    try {
+      const result = await runTokensUpdate({
+        projectRoot,
+        packageName: tokensPackage
+      });
+      if (result.status === "not-initialized") {
+        record({
+          name: "tokens",
+          status: "skip",
+          detail: "tokens not installed"
+        });
+      } else if (result.status === "up-to-date") {
+        const driftSuffix = result.frozenDrift.length > 0 ? `, frozen drift: ${result.frozenDrift.length}` : "";
+        record({
+          name: "tokens",
+          status: "ok",
+          detail: `up-to-date (${result.variant} v${result.version}${driftSuffix})`
+        });
+      } else {
+        anyChanged = true;
+        const extras = [];
+        if (result.managedReplaced.length > 0)
+          extras.push(`managed: ${result.managedReplaced.length}`);
+        if (result.frozenDrift.length > 0)
+          extras.push(`frozen drift: ${result.frozenDrift.length}`);
+        const suffix = extras.length > 0 ? ` [${extras.join(", ")}]` : "";
+        record({
+          name: "tokens",
+          status: "ok",
+          detail: `${result.variant} v${result.from} \u2192 v${result.to}${suffix}`
+        });
+      }
+    } catch (err) {
+      recordFailure("tokens", err);
+    }
+  }
+  if (!config.packages?.skills) {
+    record({
+      name: "skills",
+      status: "skip",
+      detail: "skills not installed"
+    });
+  } else if (aborted) {
+    record({
+      name: "skills",
+      status: "skip",
+      detail: "aborted: earlier critical step failed"
+    });
+  } else {
+    try {
+      const result = await runSkillsUpdate({
+        projectRoot,
+        dryRun,
+        packageName: skillsPackage
+      });
+      if (result.status === "no-skills") {
+        record({
+          name: "skills",
+          status: "skip",
+          detail: "no skills locked"
+        });
+      } else if (result.status === "no-changes") {
+        record({
+          name: "skills",
+          status: "ok",
+          detail: `up-to-date (${result.checkedSkillIds.length} skill(s) at v${result.version})`
+        });
+      } else if (result.status === "dry-run") {
+        const bumps = result.plan.filter((p) => p.action === "version-bump");
+        const detail = bumps.length === 0 ? `up-to-date (${result.plan.length} skill(s) checked at v${result.currentVersion})` : `${bumps.length} skill(s) would update: ${result.currentVersion} \u2192 ${result.availableVersion}`;
+        record({ name: "skills", status: "planned", detail });
+      } else {
+        anyChanged = true;
+        const summary = result.updatedSkillIds.length > 0 ? `updated: ${result.updatedSkillIds.join(", ")} (v${result.version})` : `refreshed at v${result.version}`;
+        record({ name: "skills", status: "ok", detail: summary });
+      }
+    } catch (err) {
+      recordFailure("skills", err);
+    }
+  }
+  await runComponentSourceStep("ui", {
+    projectRoot,
+    config,
+    dryRun,
+    record,
+    recordFailure
+  });
+  await runComponentSourceStep("biz-ui", {
+    projectRoot,
+    config,
+    dryRun,
+    record,
+    recordFailure
+  });
+  const out = (() => {
+    if (firstFailure.value) {
+      return {
+        status: "partial",
+        steps,
+        resumeHint: {
+          failedAt: firstFailure.value.step,
+          completed: steps.filter((s) => s.status === "ok").map((s) => s.name),
+          failed: steps.filter((s) => s.status === "fail").map((s) => s.name),
+          error: firstFailure.value.error,
+          resumeCommand: "teamix-evo update"
+        },
+        snapshot,
+        ...snapshotError ? { snapshotError } : {}
+      };
+    }
+    if (dryRun) return { status: "dry-run", steps, snapshot: null };
+    if (anyChanged)
+      return {
+        status: "updated",
+        steps,
+        snapshot,
+        ...snapshotError ? { snapshotError } : {}
+      };
+    return {
+      status: "up-to-date",
+      steps,
+      snapshot,
+      ...snapshotError ? { snapshotError } : {}
+    };
+  })();
+  return out;
+}
+async function runComponentSourceStep(category, args) {
+  const { projectRoot, config, dryRun, record, recordFailure } = args;
+  const cfgKey = category === "ui" ? "ui" : "biz-ui";
+  if (!config.packages?.[cfgKey]) {
+    record({
+      name: category,
+      status: "skip",
+      detail: `${category} not installed`
+    });
+    return;
+  }
+  const aliases = config.packages.ui?.aliases ?? config.packages["biz-ui"]?.aliases;
+  if (!aliases) {
+    record({
+      name: category,
+      status: "skip",
+      detail: `${category} aliases not configured`
+    });
+    return;
+  }
+  let report;
+  try {
+    report = await detectComponentLineage({
+      projectRoot,
+      category,
+      config
+    });
+  } catch (err) {
+    record({
+      name: category,
+      status: "skip",
+      detail: `lineage detect failed: ${getErrorMessage(err)}`
+    });
+    return;
+  }
+  if (report.lineage !== "teamix-evo" && report.lineage !== "mixed") {
+    record({
+      name: category,
+      status: "skip",
+      detail: `lineage=${report.lineage}; nothing to stage`
+    });
+    return;
+  }
+  if (dryRun) {
+    const total = report.registeredIds.length + report.unregisteredIds.length;
+    record({
+      name: category,
+      status: "planned",
+      detail: total === 0 ? "no components to stage" : `${total} component(s) to stage (lineage=${report.lineage})`
+    });
+    return;
+  }
+  try {
+    const built = await buildStaging({
+      category,
+      projectRoot,
+      aliases,
+      lineageReport: report,
+      trigger: "update",
+      onlyIds: []
+    });
+    if (built === null) {
+      record({
+        name: category,
+        status: "skip",
+        detail: "no entries to stage"
+      });
+      return;
+    }
+    const stagingRel = path25.relative(projectRoot, built.stagingDir);
+    const summary = summarizeStagingRisk(built.manifest.summary.byRisk);
+    record({
+      name: category,
+      status: "ok",
+      detail: `${built.manifest.summary.total} component(s) staged${summary ? ` (${summary})` : ""}, see ${stagingRel}`
+    });
+  } catch (err) {
+    recordFailure(category, err);
+  }
+}
+function summarizeStagingRisk(byRisk) {
+  const order = [
+    "risky",
+    "breaking",
+    "foreign",
+    "upgradable-medium",
+    "upgradable-low",
+    "unchanged"
+  ];
+  const parts = [];
+  for (const k of order) {
+    const v = byRisk[k];
+    if (v && v > 0) parts.push(`${v} ${k}`);
+  }
+  return parts.join(", ");
+}
+async function planTokensUpdate(tokensPackage, config) {
+  const tokensCfg = config.packages?.tokens;
+  if (!tokensCfg) return "tokens not installed";
+  const packageRoot = resolveTokensPackageRoot(tokensPackage);
+  const catalog = await loadTokensPackageManifest3(packageRoot);
+  const variantEntry = getVariantEntry3(catalog, tokensCfg.variant);
+  if (!variantEntry) {
+    return `variant "${tokensCfg.variant}" no longer in ${tokensPackage}@${catalog.version} \u2014 uninstall + re-init to switch`;
+  }
+  if (variantEntry.version === tokensCfg.version) {
+    return `up-to-date (${tokensCfg.variant} v${tokensCfg.version})`;
+  }
+  return `${tokensCfg.variant} v${tokensCfg.version} \u2192 v${variantEntry.version}`;
+}
+
+// src/core/installer.ts
+import * as path26 from "path";
+import * as fs18 from "fs/promises";
+async function installResources(options) {
+  const { projectRoot, manifest, data, variantDir, packageRoot } = options;
+  const installedResources = [];
+  for (const resource of manifest.resources) {
+    logger.debug(`Installing resource: ${resource.id} \u2192 ${resource.target}`);
+    if (resource.recursive) {
+      const results = await installRecursiveResource(
+        resource,
+        projectRoot,
+        data,
+        variantDir,
+        packageRoot
+      );
+      installedResources.push(...results);
+    } else {
+      const result = await installSingleResource(
+        resource,
+        projectRoot,
+        data,
+        variantDir,
+        packageRoot
+      );
+      installedResources.push(result);
+    }
+  }
+  return {
+    resources: installedResources,
+    count: installedResources.length
+  };
+}
+async function installSingleResource(resource, projectRoot, data, variantDir, packageRoot) {
+  const sourcePath = resolveSourcePath(
+    resource.source,
+    variantDir,
+    packageRoot
+  );
+  const targetPath = path26.join(projectRoot, resource.target);
+  let content;
+  if (resource.template) {
+    const templateContent = await loadTemplateFile(sourcePath);
+    content = renderTemplate(templateContent, data);
+  } else {
+    content = await fs18.readFile(sourcePath, "utf-8");
+  }
+  await writeFileSafe(targetPath, content);
+  const hash = computeHash(content);
+  logger.debug(`  Written: ${resource.target} (${resource.updateStrategy})`);
+  return {
+    id: resource.id,
+    target: resource.target,
+    hash,
+    strategy: resource.updateStrategy
+  };
+}
+async function installRecursiveResource(resource, projectRoot, data, variantDir, packageRoot) {
+  const sourcePath = resolveSourcePath(
+    resource.source,
+    variantDir,
+    packageRoot
+  );
+  const targetDir = path26.join(projectRoot, resource.target);
+  const results = [];
+  await ensureDir(targetDir);
+  const entries = await walkDir(sourcePath);
+  for (const entry of entries) {
+    const relPath = path26.relative(sourcePath, entry);
+    let targetFile = path26.join(targetDir, relPath);
+    if (resource.template && targetFile.endsWith(".hbs")) {
+      targetFile = targetFile.slice(0, -4);
+    }
+    let content;
+    if (resource.template && entry.endsWith(".hbs")) {
+      const templateContent = await loadTemplateFile(entry);
+      content = renderTemplate(templateContent, data);
+    } else {
+      content = await fs18.readFile(entry, "utf-8");
+    }
+    await writeFileSafe(targetFile, content);
+    const hash = computeHash(content);
+    const targetRel = path26.relative(projectRoot, targetFile);
+    results.push({
+      id: `${resource.id}:${relPath}`,
+      target: targetRel,
+      hash,
+      strategy: resource.updateStrategy
+    });
+    logger.debug(`  Written: ${targetRel}`);
+  }
+  return results;
+}
+
+// src/core/registry-client.ts
+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 path15.dirname(pkgJsonPath);
+  return path27.dirname(pkgJsonPath);
 }
 async function loadVariantData(packageName, variant) {
-  const packageRoot = resolvePackageRoot4(packageName);
-  const variantDir = path15.join(packageRoot, "library", variant);
+  const packageRoot = resolvePackageRoot5(packageName);
+  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 = path15.join(variantDir, "_data.json");
+  const dataPath = path27.join(variantDir, "_data.json");
   try {
-    const raw = await fs11.readFile(dataPath, "utf-8");
+    const raw = await fs19.readFile(dataPath, "utf-8");
     data = JSON.parse(raw);
   } catch (err) {
     if (err.code !== "ENOENT") {
@@ -2135,7 +4890,10 @@ async function loadVariantData(packageName, variant) {
 export {
   DEFAULT_UI_ALIASES,
   DEFAULT_UI_ICON_LIBRARY,
+  detectConflicts,
+  detectProjectState,
   ensureTeamixDir,
+  extractDescriptionParts,
   getTeamixDir,
   installResources,
   installSkills,
@@ -2153,7 +4911,10 @@ export {
   removeSkillFiles,
   removeUiFiles,
   runBizUiAdd,
+  runGenerateAgentsMd,
   runLintInit,
+  runProjectInit,
+  runProjectUpdate,
   runSkillsAdd,
   runSkillsInit,
   runSkillsUpdate,