teamix-evo 0.3.1 → 0.4.1

package/dist/core/index.js

@@ -1,11 +1,10 @@
-// src/core/design-init.ts
+// src/core/tokens-init.ts
 import * as path9 from "path";
 import * as fs6 from "fs/promises";
 import { createRequire as createRequire2 } from "module";
 import {
-  loadDesignPack,
-  loadDesignPackageManifest,
-  mergeDefaultAndVariant
+  loadTokensPackageManifest,
+  getVariantEntry
 } from "@teamix-evo/registry";
 
 // src/utils/fs.ts
@@ -90,71 +89,22 @@ function computeHash(content) {
   return `sha256:${hash}`;
 }
 
-// src/core/design-pack-classify.ts
-import * as path2 from "path";
-var TEAMIX_DIR = ".teamix-evo/design";
-var TOKENS_DIR = ".teamix-evo/tokens";
-var TOKENS_PACK_PREFIX = "foundations/tokens/";
-var ROOT_MANAGED_FILES = {
-  "DESIGN.md": { target: "DESIGN.md", managedRegions: ["core"] },
-  "AGENTS.md": { target: "AGENTS.md", managedRegions: ["teamix-evo"] },
-  "CLAUDE.md": { target: "CLAUDE.md", managedRegions: ["teamix-evo"] }
-};
-var FROZEN_FILES = /* @__PURE__ */ new Set([
-  "foundations/tokens/tokens.overrides.css"
-]);
-function classifyPackFile(relPath) {
-  if (path2.basename(relPath) === "README.md") {
-    return null;
-  }
-  const rootManaged = ROOT_MANAGED_FILES[relPath];
-  if (rootManaged) {
-    return {
-      target: rootManaged.target,
-      strategy: "managed",
-      managedRegions: rootManaged.managedRegions,
-      isFrozen: false
-    };
-  }
-  if (relPath.startsWith(TOKENS_PACK_PREFIX)) {
-    const rel2 = relPath.slice(TOKENS_PACK_PREFIX.length);
-    const target = path2.posix.join(TOKENS_DIR, rel2);
-    if (FROZEN_FILES.has(relPath)) {
-      return { target, strategy: "frozen", isFrozen: true };
-    }
-    return { target, strategy: "regenerable", isFrozen: false };
-  }
-  if (FROZEN_FILES.has(relPath)) {
-    return {
-      target: path2.posix.join(TEAMIX_DIR, relPath),
-      strategy: "frozen",
-      isFrozen: true
-    };
-  }
-  return {
-    target: path2.posix.join(TEAMIX_DIR, relPath),
-    strategy: "regenerable",
-    isFrozen: false
-  };
-}
-
 // src/core/state.ts
-import * as path3 from "path";
+import * as path2 from "path";
 import {
   validateConfig,
   validateInstalled,
   validateSkillsLock,
-  DesignPackLockSchema
+  TokensPackLockSchema
 } from "@teamix-evo/registry";
-var TEAMIX_DIR2 = ".teamix-evo";
+var TEAMIX_DIR = ".teamix-evo";
 var CONFIG_FILE = "config.json";
 var MANIFEST_FILE = "manifest.json";
-var DESIGN_DIR = "design";
-var DESIGN_LOCK_FILE = "pack.lock.json";
+var TOKENS_LOCK_FILE = "tokens-lock.json";
 var SKILLS_DIR = "skills";
 var SKILLS_LOCK_FILE = "manifest.lock.json";
 function getTeamixDir(projectRoot) {
-  return path3.join(projectRoot, TEAMIX_DIR2);
+  return path2.join(projectRoot, TEAMIX_DIR);
 }
 async function ensureTeamixDir(projectRoot) {
   const dir = getTeamixDir(projectRoot);
@@ -162,84 +112,85 @@ async function ensureTeamixDir(projectRoot) {
   return dir;
 }
 async function readProjectConfig(projectRoot) {
-  const configPath = path3.join(projectRoot, TEAMIX_DIR2, CONFIG_FILE);
+  const configPath = path2.join(projectRoot, TEAMIX_DIR, CONFIG_FILE);
   const raw = await readFileOrNull(configPath);
   if (raw === null) return null;
+  let data;
   try {
-    const data = JSON.parse(raw);
-    const result = validateConfig(data);
-    if (!result.success) {
-      logger.warn(`Invalid config.json: ${result.error}`);
-      return null;
-    }
-    return result.data;
+    data = JSON.parse(raw);
   } catch (err) {
-    logger.warn(`Failed to parse config.json: ${err.message}`);
-    return null;
+    throw new Error(
+      `Corrupted config.json (${err.message}). Fix the JSON manually or remove the file to start fresh; refusing to clobber prior config.`
+    );
   }
+  const result = validateConfig(data);
+  if (!result.success) {
+    throw new Error(
+      `Invalid config.json schema: ${result.error}. Fix the file manually or remove it to start fresh.`
+    );
+  }
+  return result.data;
 }
 async function writeProjectConfig(projectRoot, config) {
-  const configPath = path3.join(projectRoot, TEAMIX_DIR2, CONFIG_FILE);
+  const configPath = path2.join(projectRoot, TEAMIX_DIR, CONFIG_FILE);
   await writeFileSafe(configPath, JSON.stringify(config, null, 2) + "\n");
   logger.debug(`Wrote config \u2192 ${configPath}`);
 }
 async function readInstalledManifest(projectRoot) {
-  const manifestPath = path3.join(projectRoot, TEAMIX_DIR2, MANIFEST_FILE);
+  const manifestPath = path2.join(projectRoot, TEAMIX_DIR, MANIFEST_FILE);
   const raw = await readFileOrNull(manifestPath);
   if (raw === null) return null;
+  let data;
   try {
-    const data = JSON.parse(raw);
-    const result = validateInstalled(data);
-    if (!result.success) {
-      logger.warn(`Invalid manifest.json: ${result.error}`);
-      return null;
-    }
-    return result.data;
+    data = JSON.parse(raw);
   } catch (err) {
-    logger.warn(`Failed to parse manifest.json: ${err.message}`);
-    return null;
+    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.`
+    );
   }
+  const result = validateInstalled(data);
+  if (!result.success) {
+    throw new Error(
+      `Invalid manifest.json schema: ${result.error}. Fix the file manually or remove it to start fresh.`
+    );
+  }
+  return result.data;
 }
 async function writeInstalledManifest(projectRoot, manifest) {
-  const manifestPath = path3.join(projectRoot, TEAMIX_DIR2, MANIFEST_FILE);
+  const manifestPath = path2.join(projectRoot, TEAMIX_DIR, MANIFEST_FILE);
   await writeFileSafe(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
   logger.debug(`Wrote manifest \u2192 ${manifestPath}`);
 }
-async function readDesignPackLock(projectRoot) {
-  const lockPath = path3.join(
-    projectRoot,
-    TEAMIX_DIR2,
-    DESIGN_DIR,
-    DESIGN_LOCK_FILE
-  );
+async function readTokensLock(projectRoot) {
+  const lockPath = path2.join(projectRoot, TEAMIX_DIR, TOKENS_LOCK_FILE);
   const raw = await readFileOrNull(lockPath);
   if (raw === null) return null;
   try {
-    const parsed = DesignPackLockSchema.safeParse(JSON.parse(raw));
+    const parsed = TokensPackLockSchema.safeParse(JSON.parse(raw));
     if (!parsed.success) {
-      logger.warn(`Invalid design pack.lock.json: ${parsed.error.message}`);
+      logger.warn(`Invalid tokens-lock.json: ${parsed.error.message}`);
       return null;
     }
     return parsed.data;
   } catch (err) {
     logger.warn(
-      `Failed to parse design pack.lock.json: ${err.message}`
+      `Failed to parse tokens-lock.json: ${err.message}`
     );
     return null;
   }
 }
-async function readDesignVariant(projectRoot) {
-  const lock = await readDesignPackLock(projectRoot);
+async function readTokensVariant(projectRoot) {
+  const lock = await readTokensLock(projectRoot);
   return lock?.variant.name ?? null;
 }
 function getSkillsSourceDir(projectRoot, skillName) {
-  const base = path3.join(projectRoot, TEAMIX_DIR2, SKILLS_DIR);
-  return skillName ? path3.join(base, skillName) : base;
+  const base = path2.join(projectRoot, TEAMIX_DIR, SKILLS_DIR);
+  return skillName ? path2.join(base, skillName) : base;
 }
 async function readSkillsLock(projectRoot) {
-  const lockPath = path3.join(
+  const lockPath = path2.join(
     projectRoot,
-    TEAMIX_DIR2,
+    TEAMIX_DIR,
     SKILLS_DIR,
     SKILLS_LOCK_FILE
   );
@@ -261,9 +212,9 @@ async function readSkillsLock(projectRoot) {
   }
 }
 async function writeSkillsLock(projectRoot, lock) {
-  const lockPath = path3.join(
+  const lockPath = path2.join(
     projectRoot,
-    TEAMIX_DIR2,
+    TEAMIX_DIR,
     SKILLS_DIR,
     SKILLS_LOCK_FILE
   );
@@ -272,21 +223,21 @@ async function writeSkillsLock(projectRoot, lock) {
 }
 
 // src/core/skills-client.ts
-import * as path4 from "path";
+import * as path3 from "path";
 import * as fs2 from "fs/promises";
 import { createRequire } from "module";
 import { loadSkillsPackageManifest } from "@teamix-evo/registry";
 var require2 = createRequire(import.meta.url);
 function resolvePackageRoot(packageName) {
   const pkgJsonPath = require2.resolve(`${packageName}/package.json`);
-  return path4.dirname(pkgJsonPath);
+  return path3.dirname(pkgJsonPath);
 }
 async function loadSkillsData(packageName) {
   const packageRoot = resolvePackageRoot(packageName);
   logger.debug(`Resolved skills package root: ${packageRoot}`);
   const manifest = await loadSkillsPackageManifest(packageRoot);
   let data = {};
-  const dataPath = path4.join(packageRoot, "_data.json");
+  const dataPath = path3.join(packageRoot, "_data.json");
   try {
     const raw = await fs2.readFile(dataPath, "utf-8");
     data = JSON.parse(raw);
@@ -300,13 +251,16 @@ async function loadSkillsData(packageName) {
 }
 
 // src/core/skills-installer.ts
-import * as path8 from "path";
+import * as path7 from "path";
 import * as fs5 from "fs/promises";
-import { replaceManagedRegion } from "@teamix-evo/registry";
+import {
+  replaceManagedRegion,
+  hasManagedRegion
+} from "@teamix-evo/registry";
 
 // src/ide/QoderAdapter.ts
 import * as os from "os";
-import * as path5 from "path";
+import * as path4 from "path";
 var QoderAdapter = class {
   kind = "qoder";
   name = "qoder";
@@ -317,14 +271,14 @@ var QoderAdapter = class {
     return true;
   }
   getSkillTargetDir(skillName, scope, projectRoot) {
-    const base = scope === "global" ? path5.join(os.homedir(), ".qoder") : path5.join(projectRoot ?? this.getProjectRoot(), ".qoder");
-    return path5.join(base, "skills", skillName);
+    const base = scope === "global" ? path4.join(os.homedir(), ".qoder") : path4.join(projectRoot ?? this.getProjectRoot(), ".qoder");
+    return path4.join(base, "skills", skillName);
   }
 };
 
 // src/ide/ClaudeAdapter.ts
 import * as os2 from "os";
-import * as path6 from "path";
+import * as path5 from "path";
 var ClaudeAdapter = class {
   kind = "claude";
   name = "claude";
@@ -335,8 +289,8 @@ var ClaudeAdapter = class {
     return Boolean(process.env.CLAUDECODE);
   }
   getSkillTargetDir(skillName, scope, projectRoot) {
-    const base = scope === "global" ? path6.join(os2.homedir(), ".claude") : path6.join(projectRoot ?? this.getProjectRoot(), ".claude");
-    return path6.join(base, "skills", skillName);
+    const base = scope === "global" ? path5.join(os2.homedir(), ".claude") : path5.join(projectRoot ?? this.getProjectRoot(), ".claude");
+    return path5.join(base, "skills", skillName);
   }
 };
 
@@ -383,19 +337,19 @@ async function loadTemplateFile(filePath) {
 }
 
 // src/utils/path.ts
-import * as path7 from "path";
+import * as path6 from "path";
 import * as fs4 from "fs/promises";
 function resolveSourcePath(source, variantDir, packageRoot) {
   if (source.startsWith("_template/")) {
-    return path7.join(packageRoot, source);
+    return path6.join(packageRoot, source);
   }
-  return path7.join(variantDir, source);
+  return path6.join(variantDir, source);
 }
 async function walkDir(dir) {
   const files = [];
   const entries = await fs4.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = path7.join(dir, entry.name);
+    const fullPath = path6.join(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...await walkDir(fullPath));
     } else if (entry.isFile()) {
@@ -438,12 +392,12 @@ async function installSkills(options) {
 }
 async function writeSkillSource(skill, options) {
   const { data, packageRoot, projectRoot } = options;
-  const sourceAbs = path8.resolve(packageRoot, skill.source);
+  const sourceAbs = path7.resolve(packageRoot, skill.source);
   const targetDir = getSkillsSourceDir(projectRoot, skill.name);
   const stat2 = await fs5.stat(sourceAbs);
   const records = [];
   if (stat2.isFile()) {
-    const targetFile = path8.join(targetDir, "SKILL.md");
+    const targetFile = path7.join(targetDir, "SKILL.md");
     const content = await renderSkillContent(sourceAbs, skill, data);
     await writeFileSafe(targetFile, content);
     records.push(makeSourceRecord(skill, targetFile, content));
@@ -453,14 +407,14 @@ async function writeSkillSource(skill, options) {
   await ensureDir(targetDir);
   const entries = await walkDir(sourceAbs);
   for (const entry of entries) {
-    const rel2 = path8.relative(sourceAbs, entry);
-    let targetFile = path8.join(targetDir, rel2);
+    const rel2 = path7.relative(sourceAbs, entry);
+    let targetFile = path7.join(targetDir, rel2);
     if (skill.template && targetFile.endsWith(".hbs")) {
       targetFile = targetFile.slice(0, -4);
     }
     const content = skill.template && entry.endsWith(".hbs") ? renderTemplate(await loadTemplateFile(entry), { ...data, skill }) : await fs5.readFile(entry, "utf-8");
     await writeFileSafe(targetFile, content);
-    const relWritten = path8.relative(targetDir, targetFile);
+    const relWritten = path7.relative(targetDir, targetFile);
     records.push(makeSourceRecord(skill, targetFile, content, relWritten));
     logger.debug(`  Wrote source: ${targetFile}`);
   }
@@ -474,15 +428,66 @@ async function mirrorSkillToIde(skill, ide, scope, projectRoot) {
   const sourceFiles = await walkDir(sourceDir);
   await ensureDir(targetDir);
   for (const src of sourceFiles) {
-    const rel2 = path8.relative(sourceDir, src);
-    const targetFile = path8.join(targetDir, rel2);
-    const content = await fs5.readFile(src, "utf-8");
-    await writeFileSafe(targetFile, content);
-    records.push(makeMirrorRecord(skill, targetFile, content, ide, scope, rel2));
+    const rel2 = path7.relative(sourceDir, src);
+    const targetFile = path7.join(targetDir, rel2);
+    const sourceContent = await fs5.readFile(src, "utf-8");
+    const writtenContent = await writeMirrorContent(
+      targetFile,
+      sourceContent,
+      skill.managedRegions,
+      src
+    );
+    records.push(
+      makeMirrorRecord(skill, targetFile, writtenContent, ide, scope, rel2)
+    );
     logger.debug(`  Mirrored ${ide}:${scope}: ${targetFile}`);
   }
   return records;
 }
+async function writeMirrorContent(targetFile, sourceContent, managedRegions, sourceFile) {
+  const existing = await readFileOrNull(targetFile);
+  if (existing === null) {
+    await writeFileSafe(targetFile, sourceContent);
+    return sourceContent;
+  }
+  const regions = managedRegions ?? [];
+  const matchedRegions = regions.filter((id) => hasManagedRegion(existing, id));
+  if (matchedRegions.length === 0) {
+    if (existing !== sourceContent) {
+      logger.warn(
+        `Mirror drift detected at ${targetFile} \u2014 overwriting from source. Edit ${sourceFile} (not the mirror) and re-run \`teamix-evo skills sync\`.`
+      );
+      await writeFileSafe(targetFile, sourceContent);
+      return sourceContent;
+    }
+    return existing;
+  }
+  let merged = existing;
+  for (const id of matchedRegions) {
+    const newRegion = extractRegionBody(sourceContent, id);
+    if (newRegion === null) continue;
+    try {
+      merged = replaceManagedRegion(merged, id, newRegion);
+    } catch {
+    }
+  }
+  if (merged !== existing) {
+    await writeFileSafe(targetFile, merged);
+  }
+  return merged;
+}
+function extractRegionBody(content, id) {
+  const re = new RegExp(
+    `<!-- teamix-evo:managed:start id="${escapeRegExp(
+      id
+    )}" -->([\\s\\S]*?)<!-- teamix-evo:managed:end id="${escapeRegExp(
+      id
+    )}" -->`
+  );
+  const m = content.match(re);
+  if (!m) return null;
+  return m[1].replace(/^\n/, "").replace(/\n$/, "");
+}
 async function renderSkillContent(sourceAbs, skill, data) {
   if (skill.template ?? sourceAbs.endsWith(".hbs")) {
     const tpl = await loadTemplateFile(sourceAbs);
@@ -537,7 +542,7 @@ async function updateSkills(options) {
 }
 async function rewriteSkillSource(skill, options, summary) {
   const { data, packageRoot, projectRoot } = options;
-  const sourceAbs = path8.resolve(packageRoot, skill.source);
+  const sourceAbs = path7.resolve(packageRoot, skill.source);
   const targetDir = getSkillsSourceDir(projectRoot, skill.name);
   const stat2 = await fs5.stat(sourceAbs);
   if (!stat2.isFile()) {
@@ -545,8 +550,8 @@ async function rewriteSkillSource(skill, options, summary) {
     const entries = await walkDir(sourceAbs);
     const records = [];
     for (const entry of entries) {
-      const rel2 = path8.relative(sourceAbs, entry);
-      let targetFile2 = path8.join(targetDir, rel2);
+      const rel2 = path7.relative(sourceAbs, entry);
+      let targetFile2 = path7.join(targetDir, rel2);
       if (skill.template && targetFile2.endsWith(".hbs")) {
         targetFile2 = targetFile2.slice(0, -4);
       }
@@ -559,12 +564,12 @@ async function rewriteSkillSource(skill, options, summary) {
         summary.created++;
       }
       await writeFileSafe(targetFile2, content);
-      const relWritten = path8.relative(targetDir, targetFile2);
+      const relWritten = path7.relative(targetDir, targetFile2);
       records.push(makeSourceRecord(skill, targetFile2, content, relWritten));
     }
     return records;
   }
-  const targetFile = path8.join(targetDir, "SKILL.md");
+  const targetFile = path7.join(targetDir, "SKILL.md");
   const newContent = await renderSkillContent(sourceAbs, skill, data);
   const exists = await fileExists(targetFile);
   if (skill.updateStrategy === "frozen") {
@@ -639,14 +644,19 @@ async function syncSkillsToIdes(options) {
       await ensureDir(targetDir);
       const sourceFiles = await walkDir(sourceDir);
       for (const src of sourceFiles) {
-        const rel2 = path8.relative(sourceDir, src);
-        const targetFile = path8.join(targetDir, rel2);
-        const content = await fs5.readFile(src, "utf-8");
-        await writeFileSafe(targetFile, content);
+        const rel2 = path7.relative(sourceDir, src);
+        const targetFile = path7.join(targetDir, rel2);
+        const sourceContent = await fs5.readFile(src, "utf-8");
+        const writtenContent = await writeMirrorContent(
+          targetFile,
+          sourceContent,
+          skill.managedRegions,
+          src
+        );
         out.push({
           id: rel2 === "SKILL.md" ? skill.id : `${skill.id}:${rel2}`,
           target: targetFile,
-          hash: computeHash(content),
+          hash: computeHash(writtenContent),
           strategy: skill.updateStrategy,
           ide,
           scope
@@ -668,17 +678,46 @@ async function removeSkillFiles(records) {
       }
     }
   }
-  const parents = new Set(records.map((r) => path8.dirname(r.target)));
-  for (const dir of parents) {
-    try {
-      const entries = await fs5.readdir(dir);
-      if (entries.length === 0) await fs5.rmdir(dir);
-    } catch {
+  const startDirs = new Set(records.map((r) => path7.dirname(r.target)));
+  for (const startDir of startDirs) {
+    let dir = startDir;
+    for (let depth = 0; depth < 8; depth++) {
+      try {
+        const entries = await fs5.readdir(dir);
+        if (entries.length !== 0) break;
+        await fs5.rmdir(dir);
+      } catch {
+        break;
+      }
+      dir = path7.dirname(dir);
     }
   }
   return removed;
 }
 
+// src/utils/mcp.ts
+import * as path8 from "path";
+var MCP_JSON_CONTENT = {
+  mcpServers: {
+    "teamix-evo": {
+      command: "npx",
+      args: ["-y", "@teamix-evo/mcp"]
+    }
+  }
+};
+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");
+    logger.debug(`Wrote .mcp.json \u2192 ${mcpPath}`);
+    return "created";
+  } catch (err) {
+    logger.warn(`Failed to write .mcp.json: ${err.message}`);
+    return "failed";
+  }
+}
+
 // src/core/skills-add.ts
 var DEFAULT_SKILLS_PACKAGE = "@teamix-evo/skills";
 var FLAT_VARIANT = "_flat";
@@ -690,9 +729,6 @@ async function runSkillsAdd(options) {
   await ensureTeamixDir(projectRoot);
   const existingConfig = await readProjectConfig(projectRoot);
   const existingSkillsCfg = existingConfig?.packages?.skills;
-  if (!isIncremental && existingSkillsCfg) {
-    return { status: "already-added" };
-  }
   const ides = options.ides && options.ides.length > 0 ? [...options.ides] : existingSkillsCfg?.ides ? [...existingSkillsCfg.ides] : [];
   const scope = options.scope ?? existingSkillsCfg?.scope;
   if (ides.length === 0) {
@@ -702,7 +738,7 @@ async function runSkillsAdd(options) {
     throw new Error("Scope must be specified (project | global).");
   }
   const { manifest, data, packageRoot } = await loadSkillsData(packageName);
-  const currentDesignVariant = await readDesignVariant(projectRoot);
+  const currentTokensVariant = await readTokensVariant(projectRoot);
   if (isIncremental) {
     const known = new Set(manifest.skills.map((s) => s.id));
     const unknown = requestedNames.filter((n) => !known.has(n));
@@ -730,23 +766,27 @@ async function runSkillsAdd(options) {
     skippedSkillIds = requestedNames.filter((n) => existingSkillIds.has(n));
     onlyIds = requestedNames.filter((n) => !existingSkillIds.has(n));
   } else {
-    skippedSkillIds = [];
-    onlyIds = manifest.skills.filter((s) => {
+    const candidateIds = manifest.skills.filter((s) => {
       if (!s.variant) return true;
-      if (!currentDesignVariant) {
+      if (!currentTokensVariant) {
         logger.debug(
-          `Skipping variant-bound skill "${s.id}" (variant=${s.variant}): no design pack installed; will be picked up when "design init" runs.`
+          `Skipping variant-bound skill "${s.id}" (variant=${s.variant}): no tokens variant installed; will be picked up when "tokens init" runs.`
         );
         return false;
       }
-      if (s.variant !== currentDesignVariant) {
+      if (s.variant !== currentTokensVariant) {
         logger.debug(
-          `Skipping variant-bound skill "${s.id}" (variant=${s.variant}): current design variant is "${currentDesignVariant}".`
+          `Skipping variant-bound skill "${s.id}" (variant=${s.variant}): current tokens variant is "${currentTokensVariant}".`
         );
         return false;
       }
       return true;
     }).map((s) => s.id);
+    skippedSkillIds = candidateIds.filter((id) => existingSkillIds.has(id));
+    onlyIds = candidateIds.filter((id) => !existingSkillIds.has(id));
+  }
+  if (!isIncremental && existingSkillsCfg && onlyIds.length === 0) {
+    return { status: "already-added" };
   }
   if (isIncremental && onlyIds.length === 0) {
     return {
@@ -823,6 +863,7 @@ async function runSkillsAdd(options) {
     };
   }
   await writeSkillsLock(projectRoot, lock);
+  await ensureMcpJson(projectRoot);
   return {
     status: "installed",
     packageName,
@@ -844,85 +885,110 @@ function mergeInstalledResources(existing, next) {
   return [...map.values()];
 }
 
-// src/core/design-init.ts
-var BASELINE_DESIGN_RULES_SKILL = "teamix-evo-design-rules";
+// src/core/tokens-init.ts
 var DEFAULT_SKILLS_PACKAGE2 = "@teamix-evo/skills";
 var DEFAULT_AUTO_SKILL_IDES = ["qoder", "claude"];
 var DEFAULT_AUTO_SKILL_SCOPE = "project";
-var DEFAULT_DESIGN_PACKAGE = "@teamix-evo/design";
+var DEFAULT_TOKENS_PACKAGE = "@teamix-evo/tokens";
+var CONSUMER_TOKENS_DIR = "tokens";
+var CONSUMER_THEME_FILE = "tokens.theme.css";
+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 runDesignInit(options) {
+async function runTokensInit(options) {
   const { projectRoot, variant, ide } = options;
-  const packageName = options.packageName ?? DEFAULT_DESIGN_PACKAGE;
+  const packageName = options.packageName ?? DEFAULT_TOKENS_PACKAGE;
   await ensureTeamixDir(projectRoot);
-  const existingConfig = await readProjectConfig(projectRoot);
-  if (existingConfig?.packages?.design) {
-    return {
-      status: "already-initialized",
-      existingVariant: existingConfig.packages.design.variant
-    };
-  }
-  const packageRoot = options.packageRoot ?? resolveDesignPackageRoot(packageName);
-  const catalog = await loadDesignPackageManifest(packageRoot);
-  const variantEntry = catalog.variants.find((v) => v.name === variant);
+  const packageRoot = options.packageRoot ?? resolveTokensPackageRoot(packageName);
+  const catalog = await loadTokensPackageManifest(packageRoot);
+  const variantEntry = getVariantEntry(catalog, variant);
   if (!variantEntry) {
     const known = catalog.variants.map((v) => v.name).join(", ");
     throw new Error(
-      `Design variant not found: "${variant}". Known variants: ${known || "(none)"}. Hint: run "teamix-evo design list-variants" to see all.`
+      `Unknown variant "${variant}". Available variants: ${known || "(none)"}.
+Run \`teamix-evo tokens list-variants\` to see all options.`
     );
   }
-  const defaultDir = path9.join(packageRoot, "default");
-  const variantDir = path9.join(packageRoot, "variants", variant);
-  const defaultPack = await loadDesignPack(defaultDir);
-  const variantPack = await loadDesignPack(variantDir);
-  const merge = await mergeDefaultAndVariant(defaultDir, variantDir);
+  const existingConfig = await readProjectConfig(projectRoot);
+  if (existingConfig?.packages?.tokens) {
+    const existingVariant = existingConfig.packages.tokens.variant;
+    if (existingVariant === variant) {
+      return { status: "already-initialized", existingVariant };
+    }
+    return {
+      status: "variant-mismatch",
+      existingVariant,
+      requestedVariant: variant
+    };
+  }
   const installed = [];
-  for (const file of merge.files) {
-    const result = await installPackFile(file, projectRoot);
+  for (const fileRel of variantEntry.files) {
+    const result = await installVariantFile(fileRel, packageRoot, projectRoot);
     if (result) installed.push(result);
   }
+  const overridesAbs = path9.join(
+    projectRoot,
+    CONSUMER_TOKENS_DIR,
+    CONSUMER_OVERRIDES_FILE
+  );
+  if (!await fileExists(overridesAbs)) {
+    await writeFileSafe(overridesAbs, EMPTY_OVERRIDES_TEMPLATE);
+  }
+  const overridesContent = await fs6.readFile(overridesAbs, "utf-8");
+  installed.push({
+    id: `tokens:${CONSUMER_OVERRIDES_FILE}`,
+    target: path9.posix.join(CONSUMER_TOKENS_DIR, CONSUMER_OVERRIDES_FILE),
+    hash: computeHash(overridesContent),
+    strategy: "frozen"
+  });
   const lock = {
     schemaVersion: 1,
-    default: { version: defaultPack.version, from: packageName },
     variant: {
-      name: variantPack.name,
-      displayName: variantPack.displayName,
-      version: variantPack.version,
+      name: variantEntry.name,
+      displayName: variantEntry.displayName,
+      version: variantEntry.version,
       from: packageName
     },
-    linked: variantPack.linked,
+    packageVersion: catalog.version,
+    linked: variantEntry.linked,
     installedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   await writeFileSafe(
-    path9.join(projectRoot, ".teamix-evo", "design", "pack.lock.json"),
+    path9.join(projectRoot, ".teamix-evo", "tokens-lock.json"),
     JSON.stringify(lock, null, 2) + "\n"
   );
   const config = {
     $schema: "https://teamix-evo.dev/schema/config/v1.json",
     schemaVersion: 1,
-    ide,
+    ide: existingConfig?.ide ?? ide,
     packages: {
-      design: {
+      ...existingConfig?.packages ?? {},
+      tokens: {
         variant,
-        version: variantPack.version,
+        version: variantEntry.version,
         tailwind: "v4"
       }
     }
   };
   await writeProjectConfig(projectRoot, config);
-  const installedManifest = {
+  const prior = await readInstalledManifest(projectRoot) ?? {
     schemaVersion: 1,
-    installed: [
-      {
-        package: packageName,
-        variant,
-        version: variantPack.version,
-        installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        resources: installed
-      }
-    ]
+    installed: []
   };
-  await writeInstalledManifest(projectRoot, installedManifest);
+  const tokensIdx = prior.installed.findIndex((p) => p.package === packageName);
+  const tokensEntry = {
+    package: packageName,
+    variant,
+    version: variantEntry.version,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    resources: installed
+  };
+  if (tokensIdx >= 0) prior.installed[tokensIdx] = tokensEntry;
+  else prior.installed.push(tokensEntry);
+  await writeInstalledManifest(projectRoot, prior);
+  await ensureMcpJson(projectRoot);
   const skills = await tryAutoInstallVariantSkills({
     projectRoot,
     variant,
@@ -932,21 +998,16 @@ async function runDesignInit(options) {
     status: "installed",
     packageName,
     variant,
-    version: variantPack.version,
+    version: variantEntry.version,
     count: installed.length,
     resources: installed,
-    merge: {
-      overrides: merge.overrides,
-      variantAdds: merge.variantAdds,
-      defaultPassThrough: merge.defaultPassThrough
-    },
     skills
   };
 }
 async function tryAutoInstallVariantSkills(args) {
   const { projectRoot, variant, ide } = args;
-  const variantSkillId = `${BASELINE_DESIGN_RULES_SKILL}-${variant}`;
-  const desired = [BASELINE_DESIGN_RULES_SKILL, variantSkillId];
+  const variantSkillId = `teamix-evo-design-${variant}`;
+  const desired = [variantSkillId];
   let manifestSkillIds;
   try {
     const { manifest } = await loadSkillsData(DEFAULT_SKILLS_PACKAGE2);
@@ -966,7 +1027,9 @@ async function tryAutoInstallVariantSkills(args) {
   const missing = desired.filter((id) => !manifestSkillIds.has(id));
   if (missing.length > 0) {
     logger.warn(
-      `Skills auto-install: not found in manifest, skipping: ${missing.join(", ")}.`
+      `Skills auto-install: not found in manifest, skipping: ${missing.join(
+        ", "
+      )}.`
     );
   }
   if (present.length === 0) {
@@ -1011,32 +1074,69 @@ async function tryAutoInstallVariantSkills(args) {
     };
   }
 }
-async function installPackFile(file, projectRoot) {
-  const cls = classifyPackFile(file.relPath);
-  if (cls === null) return null;
-  const targetAbs = path9.join(projectRoot, cls.target);
-  if (cls.isFrozen && await fileExists(targetAbs)) {
-    const existing = await fs6.readFile(targetAbs, "utf-8");
+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 targetAbs = path9.join(projectRoot, targetRel);
+    const content = await fs6.readFile(sourceAbs, "utf-8");
+    await writeFileSafe(targetAbs, content);
     return {
-      id: `pack:${file.relPath}`,
-      target: cls.target,
-      hash: computeHash(existing),
-      strategy: cls.strategy
+      id: `tokens:${CONSUMER_THEME_FILE}`,
+      target: targetRel,
+      hash: computeHash(content),
+      strategy: "regenerable"
     };
   }
-  const content = await fs6.readFile(file.sourcePath, "utf-8");
-  await writeFileSafe(targetAbs, content);
-  return {
-    id: `pack:${file.relPath}`,
-    target: cls.target,
-    hash: computeHash(content),
-    strategy: cls.strategy
-  };
+  if (base === "overrides.css" || base === "tokens.overrides.css") {
+    const targetRel = path9.posix.join(
+      CONSUMER_TOKENS_DIR,
+      CONSUMER_OVERRIDES_FILE
+    );
+    const targetAbs = path9.join(projectRoot, targetRel);
+    if (await fileExists(targetAbs)) {
+      const existing = await fs6.readFile(targetAbs, "utf-8");
+      return {
+        id: `tokens:${CONSUMER_OVERRIDES_FILE}`,
+        target: targetRel,
+        hash: computeHash(existing),
+        strategy: "frozen"
+      };
+    }
+    const content = await fs6.readFile(sourceAbs, "utf-8");
+    await writeFileSafe(targetAbs, content);
+    return {
+      id: `tokens:${CONSUMER_OVERRIDES_FILE}`,
+      target: targetRel,
+      hash: computeHash(content),
+      strategy: "frozen"
+    };
+  }
+  return null;
 }
-function resolveDesignPackageRoot(packageName) {
+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);
+  return {
+    packageName,
+    packageVersion: catalog.version,
+    variants: catalog.variants.map((v) => ({
+      name: v.name,
+      displayName: v.displayName,
+      version: v.version,
+      description: v.description,
+      linked: v.linked
+    }))
+  };
+}
 
 // src/core/ui-init.ts
 var DEFAULT_UI_ALIASES = {
@@ -1082,6 +1182,7 @@ async function runUiInit(options) {
     rsc
   };
   await writeProjectConfig(projectRoot, config);
+  await ensureMcpJson(projectRoot);
   return {
     status: "installed",
     aliases,
@@ -1161,12 +1262,12 @@ function aliasToImportPath(alias) {
 }
 
 // src/core/ui-installer.ts
-var DESIGN_COMPONENTS_DIR = ".teamix-evo/design/components";
 async function installUiEntries(options) {
   const {
     projectRoot,
     manifest,
     packageRoot,
+    entryPackageRoot,
     aliases,
     requested,
     skipExisting = true
@@ -1175,7 +1276,6 @@ async function installUiEntries(options) {
   const idToEntry = new Map(manifest.entries.map((e) => [e.id, e]));
   const resources = [];
   const npmDeps = {};
-  const metaFiles = [];
   let written = 0;
   let skipped = 0;
   for (const id of orderedIds) {
@@ -1194,7 +1294,8 @@ async function installUiEntries(options) {
         skipped++;
         continue;
       }
-      const sourceAbs = path11.resolve(packageRoot, file.source);
+      const rootForEntry = entryPackageRoot?.get(entry.id) ?? packageRoot;
+      const sourceAbs = path11.resolve(rootForEntry, file.source);
       const raw = await fs8.readFile(sourceAbs, "utf-8");
       const transformed = rewriteImports(raw, aliases);
       await writeFileSafe(targetAbs, transformed);
@@ -1207,32 +1308,13 @@ async function installUiEntries(options) {
         strategy: entry.updateStrategy ?? "frozen"
       });
     }
-    if (entry.meta) {
-      const metaSourceAbs = path11.resolve(packageRoot, entry.meta);
-      const metaContent = await fs8.readFile(metaSourceAbs, "utf-8");
-      const metaTargetAbs = path11.join(
-        projectRoot,
-        DESIGN_COMPONENTS_DIR,
-        `${entry.id}.meta.md`
-      );
-      await writeFileSafe(metaTargetAbs, metaContent);
-      metaFiles.push(metaTargetAbs);
-      resources.push({
-        id: `${entry.id}:meta`,
-        target: metaTargetAbs,
-        hash: computeHash(metaContent),
-        strategy: "regenerable"
-      });
-      logger.info(`  meta:  ${rel(projectRoot, metaTargetAbs)}`);
-    }
   }
   return {
     orderedIds,
     resources,
     npmDependencies: npmDeps,
     written,
-    skipped,
-    metaFiles
+    skipped
   };
 }
 function resolveTargetPath(projectRoot, aliases, entry, file) {
@@ -1273,7 +1355,7 @@ async function removeUiFiles(records) {
 // src/core/ui-add.ts
 var DEFAULT_UI_PACKAGE = "@teamix-evo/ui";
 async function runUiAdd(options) {
-  const { projectRoot, ids, overwrite } = options;
+  const { projectRoot, ids, overwrite, includeDeprecated } = options;
   const packageName = options.packageName ?? DEFAULT_UI_PACKAGE;
   if (ids.length === 0) {
     throw new Error("At least one entry id must be provided.");
@@ -1286,7 +1368,21 @@ async function runUiAdd(options) {
     );
   }
   const { manifest, packageRoot } = await loadUiData(packageName);
-  const knownIds = new Set(manifest.entries.map((e) => e.id));
+  const archived = manifest.deprecatedEntries ?? [];
+  const archivedIds = new Set(archived.map((e) => e.id));
+  const activeIds = new Set(manifest.entries.map((e) => e.id));
+  const requestedDeprecated = ids.filter((id) => archivedIds.has(id));
+  if (requestedDeprecated.length > 0 && !includeDeprecated) {
+    const list = requestedDeprecated.map((s) => `"${s}"`).join(", ");
+    throw new Error(
+      `Refusing to install deprecated entr${requestedDeprecated.length === 1 ? "y" : "ies"} ${list}. These entries are archived and not part of the active distribution (ADR 0028). Pass \`--include-deprecated\` to override (e.g. for migration tooling).`
+    );
+  }
+  const effectiveManifest = includeDeprecated ? { ...manifest, entries: [...manifest.entries, ...archived] } : manifest;
+  const knownIds = /* @__PURE__ */ new Set([
+    ...activeIds,
+    ...includeDeprecated ? archivedIds : []
+  ]);
   const unknown = ids.filter((id) => !knownIds.has(id));
   if (unknown.length > 0) {
     throw new Error(
@@ -1295,7 +1391,7 @@ async function runUiAdd(options) {
   }
   const result = await installUiEntries({
     projectRoot,
-    manifest,
+    manifest: effectiveManifest,
     packageRoot,
     aliases: uiCfg.aliases,
     requested: ids,
@@ -1329,7 +1425,6 @@ async function runUiAdd(options) {
     orderedIds: result.orderedIds,
     written: result.written,
     skipped: result.skipped,
-    metaFiles: result.metaFiles,
     npmDependencies: result.npmDependencies,
     resources: result.resources
   };
@@ -1344,7 +1439,7 @@ function mergeResources(prior, next) {
 // src/core/ui-list.ts
 var DEFAULT_UI_PACKAGE2 = "@teamix-evo/ui";
 async function runUiList(options) {
-  const { projectRoot, installedOnly } = options;
+  const { projectRoot, installedOnly, includeDeprecated } = options;
   const packageName = options.packageName ?? DEFAULT_UI_PACKAGE2;
   const { manifest } = await loadUiData(packageName);
   const installedManifest = await readInstalledManifest(projectRoot);
@@ -1356,15 +1451,21 @@ async function runUiList(options) {
     const colon = r.id.indexOf(":");
     installedIds.add(colon >= 0 ? r.id.slice(0, colon) : r.id);
   }
-  const entries = manifest.entries.filter((e) => !installedOnly || installedIds.has(e.id)).map((e) => ({
-    id: e.id,
-    type: e.type,
-    description: e.description,
-    installed: installedIds.has(e.id)
+  const archived = manifest.deprecatedEntries ?? [];
+  const pool = includeDeprecated ? [
+    ...manifest.entries.map((e) => ({ entry: e, deprecated: false })),
+    ...archived.map((e) => ({ entry: e, deprecated: true }))
+  ] : manifest.entries.map((e) => ({ entry: e, deprecated: false }));
+  const entries = pool.filter(({ entry }) => !installedOnly || installedIds.has(entry.id)).map(({ entry, deprecated }) => ({
+    id: entry.id,
+    type: entry.type,
+    description: entry.description,
+    installed: installedIds.has(entry.id),
+    deprecated
   }));
   return {
     packageName,
-    total: manifest.entries.length,
+    total: manifest.entries.length + (includeDeprecated ? archived.length : 0),
     installedCount: installedIds.size,
     entries
   };
@@ -1501,6 +1602,7 @@ export {
   installResources,
   installSkills,
   installUiEntries,
+  listTokenVariants,
   loadSkillsData,
   loadUiData,
   loadVariantData,
@@ -1508,8 +1610,8 @@ export {
   readProjectConfig,
   removeSkillFiles,
   removeUiFiles,
-  runDesignInit,
   runSkillsAdd,
+  runTokensInit,
   runUiAdd,
   runUiInit,
   runUiList,