rafters 0.0.8 → 0.0.12

package/dist/index.js

@@ -9,8 +9,8 @@ import { Command } from "commander";
 
 // src/commands/add.ts
 import { existsSync } from "fs";
-import { access, mkdir, readFile, writeFile } from "fs/promises";
-import { dirname, join as join2 } from "path";
+import { access, mkdir, readFile as readFile2, writeFile } from "fs/promises";
+import { dirname, join as join3 } from "path";
 
 // ../../node_modules/.pnpm/zod@4.1.12/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -12558,22 +12558,28 @@ config(en_default());
 var RegistryFileSchema = external_exports.object({
   path: external_exports.string(),
   content: external_exports.string(),
-  dependencies: external_exports.array(external_exports.string())
+  dependencies: external_exports.array(external_exports.string()),
   // e.g., ["lodash@4.17.21"] - versioned
+  devDependencies: external_exports.array(external_exports.string()).default([])
+  // e.g., ["vitest"] - from @devDependencies JSDoc
 });
-var RegistryItemTypeSchema = external_exports.enum(["registry:ui", "registry:primitive"]);
+var RegistryItemTypeSchema = external_exports.enum(["ui", "primitive", "composite"]);
 var RegistryItemSchema = external_exports.object({
   name: external_exports.string(),
   type: RegistryItemTypeSchema,
   description: external_exports.string().optional(),
   primitives: external_exports.array(external_exports.string()),
-  files: external_exports.array(RegistryFileSchema)
+  files: external_exports.array(RegistryFileSchema),
+  rules: external_exports.array(external_exports.string()).default([]),
+  composites: external_exports.array(external_exports.string()).default([])
 });
 var RegistryIndexSchema = external_exports.object({
   name: external_exports.string(),
   homepage: external_exports.string(),
   components: external_exports.array(external_exports.string()),
-  primitives: external_exports.array(external_exports.string())
+  primitives: external_exports.array(external_exports.string()),
+  composites: external_exports.array(external_exports.string()).default([]),
+  rules: external_exports.array(external_exports.string()).default([])
 });
 
 // src/registry/client.ts
@@ -12644,6 +12650,30 @@ var RegistryClient = class {
     this.cache.set(cacheKey, item);
     return item;
   }
+  /**
+   * Fetch a composite by name
+   */
+  async fetchComposite(name2) {
+    const cacheKey = `composite:${name2}`;
+    const cached2 = this.cache.get(cacheKey);
+    if (cached2) {
+      return cached2;
+    }
+    const url2 = `${this.baseUrl}/registry/composites/${name2}.json`;
+    const response = await fetch(url2);
+    if (response.status === 404) {
+      throw new Error(`Composite "${name2}" not found`);
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch composite "${name2}": ${response.status} ${response.statusText}`
+      );
+    }
+    const data = await response.json();
+    const item = RegistryItemSchema.parse(data);
+    this.cache.set(cacheKey, item);
+    return item;
+  }
   /**
    * Fetch a registry item (component or primitive) by name
    * Tries component first, then primitive
@@ -12669,6 +12699,13 @@ var RegistryClient = class {
     const index = await this.fetchIndex();
     return index.components.map((name2) => ({ name: name2 }));
   }
+  /**
+   * List all available composites
+   */
+  async listComposites() {
+    const index = await this.fetchIndex();
+    return index.composites.map((name2) => ({ name: name2 }));
+  }
   /**
    * Check if a component exists in the registry
    */
@@ -12714,18 +12751,64 @@ var RegistryClient = class {
 };
 var registryClient = new RegistryClient();
 
-// src/utils/paths.ts
-import { join } from "path";
-function getRaftersPaths(projectRoot = process.cwd()) {
-  const root = join(projectRoot, ".rafters");
+// src/utils/exports.ts
+var DEFAULT_EXPORTS = {
+  tailwind: true,
+  typescript: true,
+  dtcg: false,
+  compiled: false
+};
+var EXPORT_CHOICES = [
+  {
+    name: "Tailwind CSS (web projects)",
+    value: "tailwind",
+    checked: true
+  },
+  {
+    name: "TypeScript (type-safe constants)",
+    value: "typescript",
+    checked: true
+  },
+  {
+    name: "DTCG JSON (Figma Tokens, Style Dictionary)",
+    value: "dtcg",
+    checked: false
+  },
+  {
+    name: "Standalone CSS (pre-built, no Tailwind required)",
+    value: "compiled",
+    checked: false
+  }
+];
+var FUTURE_EXPORTS = [
+  {
+    name: "iOS (Swift/SwiftUI)",
+    value: "tailwind",
+    // placeholder
+    checked: false,
+    disabled: "coming soon"
+  },
+  {
+    name: "Android (Compose)",
+    value: "tailwind",
+    // placeholder
+    checked: false,
+    disabled: "coming soon"
+  }
+];
+function selectionsToConfig(selections) {
   return {
-    root,
-    config: join(root, "config.rafters.json"),
-    tokens: join(root, "tokens"),
-    output: join(root, "output")
+    tailwind: selections.includes("tailwind"),
+    typescript: selections.includes("typescript"),
+    dtcg: selections.includes("dtcg"),
+    compiled: selections.includes("compiled")
   };
 }
 
+// src/utils/install-registry-deps.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+
 // src/utils/ui.ts
 import ora from "ora";
 var context = {
@@ -12844,8 +12927,9 @@ function log(event) {
       context.spinner?.succeed("Files written");
       const deps = event.dependencies;
       const devDeps = event.devDependencies;
+      const skippedDeps = event.skipped ?? [];
       if (deps.length > 0 || devDeps.length > 0) {
-        console.log("  Dependencies to install:");
+        console.log("  Dependencies installed:");
         for (const dep of deps) {
           console.log(`    ${dep}`);
         }
@@ -12853,9 +12937,32 @@ function log(event) {
           console.log(`    ${dep} (dev)`);
         }
       }
-      context.spinner = ora("Installing dependencies...").start();
+      if (skippedDeps.length > 0) {
+        console.log("  Dependencies skipped (already installed or internal):");
+        for (const dep of skippedDeps) {
+          console.log(`    ${dep}`);
+        }
+      }
+      break;
+    }
+    case "add:deps:no-package-json":
+      console.warn(`  Warning: ${event.message}`);
+      break;
+    case "add:deps:dry-run": {
+      const dryDeps = event.dependencies;
+      console.log("  [dry-run] Would install:");
+      for (const dep of dryDeps) {
+        console.log(`    ${dep}`);
+      }
       break;
     }
+    case "add:deps:install-failed":
+      context.spinner?.fail("Failed to install dependencies");
+      console.log(`  ${event.message}`);
+      if (event.suggestion) {
+        console.log(`  ${event.suggestion}`);
+      }
+      break;
     case "add:complete":
       context.spinner?.succeed(
         `Added ${event.installed} component${event.installed !== 1 ? "s" : ""}`
@@ -12973,6 +13080,127 @@ async function installWithPackageManager(packageManager, dependencies, options)
   }
 }
 
+// src/utils/install-registry-deps.ts
+function parseDependency(dep) {
+  const trimmed = dep.trim();
+  if (!trimmed) {
+    return { name: "", version: void 0 };
+  }
+  const versionAt = trimmed.lastIndexOf("@");
+  if (versionAt <= 0) {
+    return { name: trimmed, version: void 0 };
+  }
+  return {
+    name: trimmed.slice(0, versionAt),
+    version: trimmed.slice(versionAt + 1)
+  };
+}
+async function readInstalledDeps(targetDir) {
+  let raw;
+  try {
+    raw = await readFile(join(targetDir, "package.json"), "utf-8");
+  } catch {
+    return { packageJsonFound: false, installed: /* @__PURE__ */ new Set() };
+  }
+  try {
+    const pkg = JSON.parse(raw);
+    const installed = /* @__PURE__ */ new Set();
+    const depFields = ["dependencies", "devDependencies", "peerDependencies"];
+    for (const field of depFields) {
+      const section = pkg[field];
+      if (section && typeof section === "object") {
+        for (const name2 of Object.keys(section)) {
+          installed.add(name2);
+        }
+      }
+    }
+    return { packageJsonFound: true, installed };
+  } catch {
+    return { packageJsonFound: true, installed: /* @__PURE__ */ new Set() };
+  }
+}
+async function installRegistryDependencies(items, targetDir, options = {}) {
+  const result = {
+    installed: [],
+    skipped: [],
+    devInstalled: [],
+    failed: []
+  };
+  const allDeps = new Set(items.flatMap((item) => item.files.flatMap((file2) => file2.dependencies)));
+  if (allDeps.size === 0) {
+    return result;
+  }
+  const externalDeps = [];
+  for (const dep of allDeps) {
+    if (parseDependency(dep).name.startsWith("@rafters/")) {
+      result.skipped.push(dep);
+    } else {
+      externalDeps.push(dep);
+    }
+  }
+  if (externalDeps.length === 0) {
+    return result;
+  }
+  const { packageJsonFound, installed: installedInProject } = await readInstalledDeps(targetDir);
+  const toInstall = [];
+  if (!packageJsonFound) {
+    log({
+      event: "add:deps:no-package-json",
+      message: "No package.json found. Run npm init or pnpm init first.",
+      targetDir
+    });
+    toInstall.push(...externalDeps);
+  } else {
+    for (const dep of externalDeps) {
+      const { name: name2 } = parseDependency(dep);
+      if (installedInProject.has(name2)) {
+        result.skipped.push(dep);
+      } else {
+        toInstall.push(dep);
+      }
+    }
+  }
+  if (toInstall.length === 0) {
+    return result;
+  }
+  if (options.dryRun) {
+    log({
+      event: "add:deps:dry-run",
+      dependencies: toInstall
+    });
+    return result;
+  }
+  try {
+    await updateDependencies(toInstall, [], {
+      cwd: targetDir,
+      silent: options.silent ?? false
+    });
+    result.installed = toInstall;
+  } catch (err) {
+    result.failed = toInstall;
+    const message = err instanceof Error ? err.message : String(err);
+    log({
+      event: "add:deps:install-failed",
+      message: `Failed to install dependencies: ${message}`,
+      dependencies: toInstall,
+      suggestion: `Manually install: ${toInstall.join(" ")}`
+    });
+  }
+  return result;
+}
+
+// src/utils/paths.ts
+import { join as join2 } from "path";
+function getRaftersPaths(projectRoot = process.cwd()) {
+  const root = join2(projectRoot, ".rafters");
+  return {
+    root,
+    config: join2(root, "config.rafters.json"),
+    tokens: join2(root, "tokens"),
+    output: join2(root, "output")
+  };
+}
+
 // src/commands/add.ts
 async function isInitialized(cwd) {
   const paths = getRaftersPaths(cwd);
@@ -12986,7 +13214,7 @@ async function isInitialized(cwd) {
 async function loadConfig(cwd) {
   const paths = getRaftersPaths(cwd);
   try {
-    const content = await readFile(paths.config, "utf-8");
+    const content = await readFile2(paths.config, "utf-8");
     return JSON.parse(content);
   } catch (err) {
     if (existsSync(paths.config)) {
@@ -12996,6 +13224,56 @@ async function loadConfig(cwd) {
     return null;
   }
 }
+async function saveConfig(cwd, config3) {
+  const paths = getRaftersPaths(cwd);
+  await writeFile(paths.config, JSON.stringify(config3, null, 2));
+}
+function getInstalledNames(config3) {
+  if (!config3?.installed) return [];
+  const names2 = /* @__PURE__ */ new Set([
+    ...config3.installed.components,
+    ...config3.installed.primitives,
+    ...config3.installed.composites ?? []
+  ]);
+  return [...names2].sort();
+}
+var FOLDER_NAMES = /* @__PURE__ */ new Set(["composites"]);
+function isAlreadyInstalled(config3, item) {
+  if (!config3?.installed) return false;
+  if (item.type === "ui") {
+    return config3.installed.components.includes(item.name);
+  }
+  if (item.type === "composite") {
+    return (config3.installed.composites ?? []).includes(item.name);
+  }
+  return config3.installed.primitives.includes(item.name);
+}
+function trackInstalled(config3, items) {
+  if (!config3.installed) {
+    config3.installed = { components: [], primitives: [], composites: [] };
+  }
+  if (!config3.installed.composites) {
+    config3.installed.composites = [];
+  }
+  for (const item of items) {
+    if (item.type === "ui") {
+      if (!config3.installed.components.includes(item.name)) {
+        config3.installed.components.push(item.name);
+      }
+    } else if (item.type === "composite") {
+      if (!config3.installed.composites.includes(item.name)) {
+        config3.installed.composites.push(item.name);
+      }
+    } else {
+      if (!config3.installed.primitives.includes(item.name)) {
+        config3.installed.primitives.push(item.name);
+      }
+    }
+  }
+  config3.installed.components.sort();
+  config3.installed.primitives.sort();
+  config3.installed.composites.sort();
+}
 function transformPath(registryPath, config3) {
   if (!config3) return registryPath;
   if (registryPath.startsWith("components/ui/")) {
@@ -13004,10 +13282,13 @@ function transformPath(registryPath, config3) {
   if (registryPath.startsWith("lib/primitives/")) {
     return registryPath.replace("lib/primitives/", `${config3.primitivesPath}/`);
   }
+  if (registryPath.startsWith("composites/")) {
+    return registryPath.replace("composites/", `${config3.compositesPath}/`);
+  }
   return registryPath;
 }
 function fileExists(cwd, relativePath) {
-  return existsSync(join2(cwd, relativePath));
+  return existsSync(join3(cwd, relativePath));
 }
 function transformFileContent(content, config3) {
   let transformed = content;
@@ -13047,7 +13328,7 @@ async function installItem(cwd, item, options, config3) {
   let skipped = false;
   for (const file2 of item.files) {
     const projectPath = transformPath(file2.path, config3);
-    const targetPath = join2(cwd, projectPath);
+    const targetPath = join3(cwd, projectPath);
     if (fileExists(cwd, projectPath)) {
       if (!options.overwrite) {
         log({
@@ -13071,33 +13352,36 @@ async function installItem(cwd, item, options, config3) {
     files: installedFiles
   };
 }
-function collectDependencies(items) {
-  const deps = /* @__PURE__ */ new Set();
-  const devDeps = /* @__PURE__ */ new Set();
-  for (const item of items) {
-    for (const file2 of item.files) {
-      for (const dep of file2.dependencies) {
-        deps.add(dep);
-      }
-    }
-  }
-  return {
-    dependencies: [...deps].sort(),
-    devDependencies: [...devDeps].sort()
-  };
-}
-async function add(components, options) {
+async function add(componentArgs, options) {
   setAgentMode(options.agent ?? false);
+  let components = componentArgs;
   const client = new RegistryClient(options.registryUrl);
+  let folder;
+  const firstArg = components[0];
+  if (firstArg && FOLDER_NAMES.has(firstArg)) {
+    folder = firstArg;
+    components = components.slice(1);
+  }
   if (options.list) {
     const availableComponents = await client.listComponents();
+    const availableComposites = await client.listComposites();
     if (options.agent) {
-      log({ event: "add:list", components: availableComponents });
+      log({
+        event: "add:list",
+        components: availableComponents,
+        composites: availableComposites
+      });
     } else {
       console.log("Available components:\n");
       for (const comp of availableComponents) {
         console.log(`  ${comp.name}  ${comp.description ?? ""}`);
       }
+      if (availableComposites.length > 0) {
+        console.log("\nAvailable composites:\n");
+        for (const comp of availableComposites) {
+          console.log(`  ${comp.name}  ${comp.description ?? ""}`);
+        }
+      }
     }
     return;
   }
@@ -13109,6 +13393,24 @@ async function add(components, options) {
     return;
   }
   const config3 = await loadConfig(cwd);
+  if (options.update) {
+    options.overwrite = true;
+  }
+  if (options.updateAll) {
+    options.overwrite = true;
+    if (!config3) {
+      error46("No rafters config found. Run 'rafters init' first.");
+      process.exitCode = 1;
+      return;
+    }
+    const installedNames = getInstalledNames(config3);
+    if (installedNames.length === 0) {
+      error46("No installed components found. Use 'rafters add <component>' to install first.");
+      process.exitCode = 1;
+      return;
+    }
+    components = installedNames;
+  }
   if (components.length === 0) {
     error46("No components specified. Usage: rafters add <component...>");
     process.exitCode = 1;
@@ -13122,15 +13424,23 @@ async function add(components, options) {
   });
   const allItems = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const componentName of components) {
+  for (const itemName of components) {
     try {
-      const items = await client.resolveDependencies(componentName, seen);
-      allItems.push(...items);
+      if (folder === "composites") {
+        if (!seen.has(itemName)) {
+          const item = await client.fetchComposite(itemName);
+          seen.add(itemName);
+          allItems.push(item);
+        }
+      } else {
+        const items = await client.resolveDependencies(itemName, seen);
+        allItems.push(...items);
+      }
     } catch (err) {
       if (err instanceof Error) {
         error46(err.message);
       } else {
-        error46(`Failed to fetch component "${componentName}"`);
+        error46(`Failed to fetch "${itemName}"`);
       }
       process.exitCode = 1;
       return;
@@ -13138,11 +13448,22 @@ async function add(components, options) {
   }
   const installed = [];
   const skipped = [];
+  const installedItems = [];
   for (const item of allItems) {
+    if (!options.overwrite && isAlreadyInstalled(config3, item)) {
+      log({
+        event: "add:skip",
+        component: item.name,
+        reason: "already installed"
+      });
+      skipped.push(item.name);
+      continue;
+    }
     try {
       const result = await installItem(cwd, item, options, config3);
       if (result.installed) {
         installed.push(item.name);
+        installedItems.push(item);
         log({
           event: "add:installed",
           component: item.name,
@@ -13163,22 +13484,48 @@ async function add(components, options) {
       }
     }
   }
-  const { dependencies, devDependencies } = collectDependencies(allItems);
-  if (dependencies.length > 0 || devDependencies.length > 0) {
+  const emptyDeps = {
+    installed: [],
+    skipped: [],
+    devInstalled: [],
+    failed: []
+  };
+  let depsResult = emptyDeps;
+  try {
+    depsResult = await installRegistryDependencies(allItems, cwd);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log({
+      event: "add:deps:install-failed",
+      message: `Failed to process dependencies: ${message}`,
+      dependencies: [],
+      suggestion: "Check package.json and try installing dependencies manually."
+    });
+  }
+  if (depsResult.installed.length > 0 || depsResult.skipped.length > 0) {
     log({
       event: "add:dependencies",
-      dependencies,
-      devDependencies
+      dependencies: depsResult.installed,
+      devDependencies: depsResult.devInstalled,
+      skipped: depsResult.skipped
     });
-    try {
-      await updateDependencies(dependencies, devDependencies, { cwd });
-    } catch (err) {
-      log({
-        event: "add:error",
-        message: "Failed to install dependencies",
-        error: err instanceof Error ? err.message : String(err)
-      });
-    }
+  }
+  if (installedItems.length > 0 && config3) {
+    trackInstalled(config3, installedItems);
+    await saveConfig(cwd, config3);
+  } else if (installedItems.length > 0 && !config3) {
+    const newConfig = {
+      framework: "unknown",
+      componentsPath: "components/ui",
+      primitivesPath: "lib/primitives",
+      compositesPath: "composites",
+      cssPath: null,
+      shadcn: false,
+      exports: DEFAULT_EXPORTS,
+      installed: { components: [], primitives: [], composites: [] }
+    };
+    trackInstalled(newConfig, installedItems);
+    await saveConfig(cwd, newConfig);
   }
   log({
     event: "add:complete",
@@ -13189,19 +13536,19 @@ async function add(components, options) {
   if (skipped.length > 0 && installed.length === 0) {
     log({
       event: "add:hint",
-      message: "Some components were skipped. Use --overwrite to replace existing files.",
+      message: "Some components were skipped. Use --update to re-fetch, or --update-all to refresh everything.",
       skipped
     });
-    error46("Component already exists. Use --overwrite to replace.");
+    error46("Component already exists. Use --update to re-fetch from registry.");
     process.exitCode = 1;
   }
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync2 } from "fs";
-import { copyFile, mkdir as mkdir3, readFile as readFile4, rm, writeFile as writeFile3 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import { copyFile, mkdir as mkdir3, readFile as readFile5, rm, writeFile as writeFile3 } from "fs/promises";
 import { createRequire } from "module";
-import { join as join8, relative } from "path";
+import { join as join9, relative } from "path";
 import { checkbox, confirm } from "@inquirer/prompts";
 
 // ../design-tokens/src/plugins/scale.ts
@@ -14126,6 +14473,42 @@ function buildExtensions(token) {
   if (token.customPropertyOnly) {
     extensions.customPropertyOnly = token.customPropertyOnly;
   }
+  if (token.userOverride) {
+    extensions.userOverride = token.userOverride;
+  }
+  if (token.computedValue !== void 0) {
+    extensions.computedValue = convertValue({ ...token, value: token.computedValue });
+  }
+  if (token.generationRule) {
+    extensions.generationRule = token.generationRule;
+  }
+  if (token.pairedWith && token.pairedWith.length > 0) {
+    extensions.pairedWith = token.pairedWith;
+  }
+  if (token.conflictsWith && token.conflictsWith.length > 0) {
+    extensions.conflictsWith = token.conflictsWith;
+  }
+  if (token.applicableComponents && token.applicableComponents.length > 0) {
+    extensions.applicableComponents = token.applicableComponents;
+  }
+  if (token.requiredForComponents && token.requiredForComponents.length > 0) {
+    extensions.requiredForComponents = token.requiredForComponents;
+  }
+  if (token.trustLevel) {
+    extensions.trustLevel = token.trustLevel;
+  }
+  if (token.cognitiveLoad !== void 0) {
+    extensions.cognitiveLoad = token.cognitiveLoad;
+  }
+  if (token.consequence) {
+    extensions.consequence = token.consequence;
+  }
+  if (token.accessibilityLevel) {
+    extensions.accessibilityLevel = token.accessibilityLevel;
+  }
+  if (token.appliesWhen && token.appliesWhen.length > 0) {
+    extensions.appliesWhen = token.appliesWhen;
+  }
   return Object.keys(extensions).length > 0 ? { rafters: extensions } : {};
 }
 function tokenToDTCG(token) {
@@ -24332,7 +24715,7 @@ var require_volume = __commonJS({
     var Dir_1 = require_Dir();
     var resolveCrossPlatform = pathModule.resolve;
     var { O_RDONLY, O_WRONLY, O_RDWR, O_CREAT, O_EXCL, O_TRUNC, O_APPEND, O_DIRECTORY, O_SYMLINK, F_OK, COPYFILE_EXCL, COPYFILE_FICLONE_FORCE } = constants_1.constants;
-    var { sep: sep2, relative: relative2, join: join11, dirname: dirname4 } = pathModule.posix ? pathModule.posix : pathModule;
+    var { sep: sep2, relative: relative2, join: join12, dirname: dirname4 } = pathModule.posix ? pathModule.posix : pathModule;
     var kMinPoolSpace = 128;
     var EPERM = "EPERM";
     var ENOENT2 = "ENOENT";
@@ -24398,7 +24781,7 @@ var require_volume = __commonJS({
       function flatten(pathPrefix, node) {
         for (const path2 in node) {
           const contentOrNode = node[path2];
-          const joinedPath = join11(pathPrefix, path2);
+          const joinedPath = join12(pathPrefix, path2);
           if (typeof contentOrNode === "string" || contentOrNode instanceof buffer_1.Buffer) {
             flatJSON[joinedPath] = contentOrNode;
           } else if (typeof contentOrNode === "object" && contentOrNode !== null && Object.keys(contentOrNode).length > 0) {
@@ -24555,7 +24938,7 @@ var require_volume = __commonJS({
               return null;
           node = curr === null || curr === void 0 ? void 0 : curr.getNode();
           if (resolveSymlinks && node.isSymlink()) {
-            const resolvedPath = pathModule.isAbsolute(node.symlink) ? node.symlink : join11(pathModule.dirname(curr.getPath()), node.symlink);
+            const resolvedPath = pathModule.isAbsolute(node.symlink) ? node.symlink : join12(pathModule.dirname(curr.getPath()), node.symlink);
             steps = filenameToSteps(resolvedPath).concat(steps.slice(i + 1));
             curr = this.root;
             i = 0;
@@ -27479,7 +27862,7 @@ var posix = {
 
 // ../../node_modules/.pnpm/path-unified@0.2.0/node_modules/path-unified/src/posix.js
 var resolve = posResolve;
-var join3 = posJoin;
+var join4 = posJoin;
 
 // ../../node_modules/.pnpm/@isaacs+balanced-match@4.0.1/node_modules/@isaacs/balanced-match/dist/esm/index.js
 var balanced = (a, b, str) => {
@@ -37378,7 +37761,7 @@ var transforms_default = {
     type: value,
     filter: isAsset,
     transform: function(token, _, options) {
-      return join3(process?.cwd() ?? "/", options.usesDtcg ? token.$value : token.value);
+      return join4(process?.cwd() ?? "/", options.usesDtcg ? token.$value : token.value);
     }
   },
   /**
@@ -43578,12 +43961,12 @@ var formats_default = formats2;
 var { androidCopyImages, copyAssets } = actions;
 var { silent } = logVerbosityLevels;
 function getAssetDir(config3) {
-  return join3(config3.buildPath ?? "", "android/main/res/drawable-").replace(/\\/g, "/");
+  return join4(config3.buildPath ?? "", "android/main/res/drawable-").replace(/\\/g, "/");
 }
 function getAssetPath(token, imagesDir) {
   const name2 = token.path.slice(2, 4).join("_");
   const dir = `${imagesDir}${token.attributes?.state}`;
-  return { file: join3(dir, `${name2}.png`), dir };
+  return { file: join4(dir, `${name2}.png`), dir };
 }
 var actions_default = {
   /**
@@ -43624,7 +44007,7 @@ var actions_default = {
    */
   [copyAssets]: {
     do: async function(_, config3, _options, vol2 = fs2) {
-      const assetsPath = join3(config3.buildPath ?? "", "assets");
+      const assetsPath = join4(config3.buildPath ?? "", "assets");
       if (config3.log?.verbosity !== silent) {
         console.log(`Copying assets directory to ${assetsPath}`);
       }
@@ -43638,7 +44021,7 @@ var actions_default = {
       );
     },
     undo: async function(_, config3, _options, vol2 = fs2) {
-      const assetsPath = join3(config3.buildPath ?? "", "assets");
+      const assetsPath = join4(config3.buildPath ?? "", "assets");
       if (config3.log?.verbosity !== silent) {
         console.log(`Removing assets directory from ${assetsPath}`);
       }
@@ -44119,8 +44502,14 @@ var DEFAULT_DEPTH_DEFINITIONS = {
   },
   sticky: {
     value: 20,
-    meaning: "Sticky elements - headers, navigation",
-    contexts: ["sticky-header", "sticky-nav", "floating-actions"],
+    meaning: "Sticky elements - headers, toolbars",
+    contexts: ["sticky-header", "sticky-toolbar", "floating-actions"],
+    stackingContext: true
+  },
+  navigation: {
+    value: 25,
+    meaning: "Navigation panels - sidebars, slide-out nav",
+    contexts: ["sidebar", "navigation-panel", "slide-out-menu"],
     stackingContext: true
   },
   fixed: {
@@ -44146,6 +44535,12 @@ var DEFAULT_DEPTH_DEFINITIONS = {
     meaning: "Tooltips - highest common layer",
     contexts: ["tooltips", "toast-notifications"],
     stackingContext: true
+  },
+  overlay: {
+    value: 70,
+    meaning: "Overlay backdrops - screen-dimming layers behind modals",
+    contexts: ["modal-backdrop", "drawer-backdrop", "sheet-backdrop"],
+    stackingContext: true
   }
 };
 var DEFAULT_SHADOW_DEFINITIONS = {
@@ -46443,6 +46838,78 @@ function generateThemeBlock(groups) {
   lines.push("}");
   return lines.join("\n");
 }
+var ARTICLE_ELEMENT_STYLES = [
+  // Paragraphs
+  ["p", "leading-relaxed mb-4"],
+  ["p:last-child", "mb-0"],
+  // Headings
+  ["h1", "text-4xl font-bold tracking-tight mb-4 mt-0 text-accent-foreground"],
+  ["h2", "text-3xl font-semibold tracking-tight mb-3 mt-8 text-accent-foreground"],
+  ["h2:first-child", "mt-0"],
+  ["h3", "text-2xl font-semibold mb-2 mt-6 text-accent-foreground"],
+  ["h4", "text-xl font-semibold mb-2 mt-4 text-accent-foreground"],
+  ["h5", "text-lg font-semibold mb-2 mt-4 text-accent-foreground"],
+  ["h6", "text-base font-semibold mb-2 mt-4 text-accent-foreground"],
+  // Lists
+  ["ul", "list-disc pl-6 mb-4"],
+  ["ol", "list-decimal pl-6 mb-4"],
+  ["li", "mb-1"],
+  ["li > ul,\n  article li > ol", "mt-1 mb-0"],
+  // Links
+  ["a", "text-primary underline underline-offset-4"],
+  ["a:hover", "text-primary/80"],
+  // Blockquotes
+  ["blockquote", "border-l-4 border-muted pl-4 italic my-4"],
+  // Code
+  ["code", "bg-muted px-1.5 py-0.5 rounded text-sm font-mono"],
+  ["pre", "bg-muted p-4 rounded-lg overflow-x-auto my-4 text-sm font-mono"],
+  ["pre code", "bg-transparent p-0 rounded-none text-[inherit]"],
+  ["kbd", "bg-muted border border-border rounded px-1.5 py-0.5 text-sm font-mono"],
+  // Horizontal rules
+  ["hr", "border-border my-8"],
+  // Media
+  ["img", "rounded-lg my-4 max-w-full h-auto"],
+  ["video", "rounded-lg my-4 max-w-full h-auto"],
+  // Tables
+  ["table", "w-full my-4 border-collapse"],
+  ["caption", "mt-2 text-sm text-muted-foreground text-left"],
+  ["th", "border border-border px-3 py-2 text-left font-semibold"],
+  ["td", "border border-border px-3 py-2"],
+  // Figures
+  ["figure", "my-4"],
+  ["figcaption", "mt-2 text-sm text-muted-foreground"],
+  // Definition lists
+  ["dl", "my-4"],
+  ["dt", "font-semibold mt-2"],
+  ["dd", "pl-4 mb-2"],
+  // Details/Summary
+  ["details", "my-4"],
+  ["summary", "cursor-pointer font-semibold"],
+  // Inline formatting
+  ["strong,\n  article b", "font-semibold"],
+  ["mark", "bg-accent text-accent-foreground px-1 rounded"],
+  ["small", "text-sm"],
+  ["sub", "text-xs align-sub"],
+  ["sup", "text-xs align-super"],
+  ["abbr[title]", "underline decoration-dotted underline-offset-4 cursor-help"],
+  ["s,\n  article del", "line-through"],
+  ["ins", "underline"]
+];
+function generateArticleBaseLayer() {
+  const lines = [];
+  lines.push("@layer base {");
+  for (const [selector, utilities] of ARTICLE_ELEMENT_STYLES) {
+    if (selector.includes("\n")) {
+      lines.push(`  article ${selector} {`);
+    } else {
+      lines.push(`  article ${selector} {`);
+    }
+    lines.push(`    @apply ${utilities};`);
+    lines.push("  }");
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
 function generateKeyframes(motionTokens) {
   const keyframeTokens = motionTokens.filter((t2) => t2.name.startsWith("motion-keyframe-"));
   if (keyframeTokens.length === 0) {
@@ -46494,6 +46961,8 @@ function tokensToTailwind(tokens, options = {}) {
   if (keyframes) {
     sections.push(keyframes);
   }
+  sections.push("");
+  sections.push(generateArticleBaseLayer());
   return sections.join("\n");
 }
 function registryToTailwind(registry2, options) {
@@ -46505,7 +46974,7 @@ async function registryToCompiled(registry2, options = {}) {
   const themeCss = registryToTailwind(registry2, { includeImport });
   const { execFileSync } = await import("child_process");
   const { mkdtempSync, writeFileSync, readFileSync, rmSync } = await import("fs");
-  const { join: join11, dirname: dirname4 } = await import("path");
+  const { join: join12, dirname: dirname4 } = await import("path");
   const { createRequire: createRequire2 } = await import("module");
   const require2 = createRequire2(import.meta.url);
   let pkgDir;
@@ -46515,10 +46984,10 @@ async function registryToCompiled(registry2, options = {}) {
   } catch {
     throw new Error("Failed to resolve @tailwindcss/cli");
   }
-  const binPath = join11(pkgDir, "dist", "index.mjs");
-  const tempDir = mkdtempSync(join11(pkgDir, ".tmp-compile-"));
-  const tempInput = join11(tempDir, "input.css");
-  const tempOutput = join11(tempDir, "output.css");
+  const binPath = join12(pkgDir, "dist", "index.mjs");
+  const tempDir = mkdtempSync(join12(pkgDir, ".tmp-compile-"));
+  const tempInput = join12(tempDir, "input.css");
+  const tempOutput = join12(tempDir, "output.css");
   try {
     writeFileSync(tempInput, themeCss);
     const args = [binPath, "-i", tempInput, "-o", tempOutput];
@@ -46797,7 +47266,7 @@ function tagTokenizer() {
 
 // ../../node_modules/.pnpm/comment-parser@1.4.1/node_modules/comment-parser/es6/parser/tokenizers/type.js
 function typeTokenizer(spacing = "compact") {
-  const join11 = getJoiner(spacing);
+  const join12 = getJoiner(spacing);
   return (spec) => {
     let curlies = 0;
     let lines = [];
@@ -46840,7 +47309,7 @@ function typeTokenizer(spacing = "compact") {
     }
     parts[0] = parts[0].slice(1);
     parts[parts.length - 1] = parts[parts.length - 1].slice(0, -1);
-    spec.type = join11(parts);
+    spec.type = join12(parts);
     return spec;
   };
 }
@@ -46938,9 +47407,9 @@ function nameTokenizer() {
 
 // ../../node_modules/.pnpm/comment-parser@1.4.1/node_modules/comment-parser/es6/parser/tokenizers/description.js
 function descriptionTokenizer(spacing = "compact", markers = Markers) {
-  const join11 = getJoiner2(spacing);
+  const join12 = getJoiner2(spacing);
   return (spec) => {
-    spec.description = join11(spec.source, markers);
+    spec.description = join12(spec.source, markers);
     return spec;
   };
 }
@@ -47001,11 +47470,11 @@ function getParser4({ startLine = 0, fence = "```", spacing = "compact", markers
 }
 
 // ../../node_modules/.pnpm/comment-parser@1.4.1/node_modules/comment-parser/es6/stringifier/index.js
-function join4(tokens) {
+function join5(tokens) {
   return tokens.start + tokens.delimiter + tokens.postDelimiter + tokens.tag + tokens.postTag + tokens.type + tokens.postType + tokens.name + tokens.postName + tokens.description + tokens.end + tokens.lineEnd;
 }
 function getStringifier() {
-  return (block) => block.source.map(({ tokens }) => join4(tokens)).join("\n");
+  return (block) => block.source.map(({ tokens }) => join5(tokens)).join("\n");
 }
 
 // ../../node_modules/.pnpm/comment-parser@1.4.1/node_modules/comment-parser/es6/stringifier/inspect.js
@@ -47167,13 +47636,45 @@ function extractPrimitiveDependencies(source) {
     const pkg = match2[1];
     if (pkg && (pkg.includes("/primitives/") || pkg.includes("../primitives/"))) {
       const primitiveName = pkg.split("/").pop()?.replace(/\.(ts|tsx)$/, "");
-      if (primitiveName && !primitives.includes(primitiveName) && primitiveName !== "types") {
+      if (primitiveName && !primitives.includes(primitiveName)) {
         primitives.push(primitiveName);
       }
     }
   }
   return primitives;
 }
+var DEP_TAG_MAP = {
+  dependencies: "runtime",
+  devdependencies: "dev",
+  "internal-dependencies": "internal",
+  internaldependencies: "internal"
+};
+function extractJSDocDependencies(source) {
+  const result = { runtime: [], dev: [], internal: [] };
+  const blocks = parse3(source);
+  if (blocks.length === 0) return result;
+  for (const block of blocks) {
+    for (const tag of block.tags) {
+      const field = DEP_TAG_MAP[tag.tag.toLowerCase()];
+      if (!field) continue;
+      const value2 = getTagValue(tag).trim();
+      if (value2) {
+        const tokens = value2.split(/\s+/).filter(Boolean);
+        const validTokens = [];
+        for (const token of tokens) {
+          if (token.startsWith("(")) break;
+          validTokens.push(token);
+        }
+        result[field].push(...validTokens);
+      }
+    }
+  }
+  return {
+    runtime: [...new Set(result.runtime)],
+    dev: [...new Set(result.dev)],
+    internal: [...new Set(result.internal)]
+  };
+}
 function toDisplayName(name2) {
   return name2.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
@@ -48263,10 +48764,12 @@ var DEPTH_LEVELS = [
   "base",
   "dropdown",
   "sticky",
+  "navigation",
   "fixed",
   "modal",
   "popover",
-  "tooltip"
+  "tooltip",
+  "overlay"
 ];
 var ELEVATION_LEVELS = [
   "surface",
@@ -50325,14 +50828,14 @@ function buildColorSystem(options = {}) {
 }
 
 // ../design-tokens/src/persistence/node-adapter.ts
-import { mkdir as mkdir2, readdir as readdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
-import { join as join5 } from "path";
+import { mkdir as mkdir2, readdir as readdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { join as join6 } from "path";
 var SCHEMA_URL = "https://rafters.studio/schemas/namespace-tokens.json";
 var VERSION = "1.0.0";
 var NodePersistenceAdapter = class {
   tokensDir;
   constructor(projectRoot) {
-    this.tokensDir = join5(projectRoot, ".rafters", "tokens");
+    this.tokensDir = join6(projectRoot, ".rafters", "tokens");
   }
   async load() {
     let files;
@@ -50344,7 +50847,7 @@ var NodePersistenceAdapter = class {
     const allTokens = [];
     for (const file2 of files) {
       if (!file2.endsWith(".rafters.json")) continue;
-      const content = await readFile2(join5(this.tokensDir, file2), "utf-8");
+      const content = await readFile3(join6(this.tokensDir, file2), "utf-8");
       const data = NamespaceFileSchema.parse(JSON.parse(content));
       allTokens.push(...data.tokens);
     }
@@ -50372,7 +50875,7 @@ var NodePersistenceAdapter = class {
       };
       NamespaceFileSchema.parse(data);
       await writeFile2(
-        join5(this.tokensDir, `${namespace}.rafters.json`),
+        join6(this.tokensDir, `${namespace}.rafters.json`),
         JSON.stringify(data, null, 2)
       );
     }
@@ -50381,7 +50884,7 @@ var NodePersistenceAdapter = class {
 
 // ../design-tokens/src/rule-engine.ts
 import { promises as fs3 } from "fs";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 var RuleResultSchema = external_exports.union([
   external_exports.string(),
   external_exports.object({
@@ -50397,11 +50900,18 @@ var RuleContextSchema = external_exports.object({
 });
 
 // src/utils/detect.ts
-import { readFile as readFile3 } from "fs/promises";
-import { join as join7 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { readFile as readFile4 } from "fs/promises";
+import { join as join8 } from "path";
+var CONFIG_FILE_FRAMEWORKS = [
+  { files: ["astro.config.mjs", "astro.config.ts", "astro.config.js"], framework: "astro" },
+  { files: ["next.config.mjs", "next.config.ts", "next.config.js"], framework: "next" },
+  { files: ["remix.config.js", "remix.config.ts"], framework: "remix" },
+  { files: ["vite.config.ts", "vite.config.js", "vite.config.mjs"], framework: "vite" }
+];
 async function detectFramework(cwd) {
   try {
-    const content = await readFile3(join7(cwd, "package.json"), "utf-8");
+    const content = await readFile4(join8(cwd, "package.json"), "utf-8");
     const pkg = JSON.parse(content);
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     if (deps.next) {
@@ -50420,14 +50930,23 @@ async function detectFramework(cwd) {
     if (deps.vite) {
       return "vite";
     }
-    return "unknown";
   } catch {
-    return "unknown";
   }
+  return detectFrameworkFromConfigFiles(cwd);
+}
+function detectFrameworkFromConfigFiles(cwd) {
+  for (const { files, framework } of CONFIG_FILE_FRAMEWORKS) {
+    for (const file2 of files) {
+      if (existsSync2(join8(cwd, file2))) {
+        return framework;
+      }
+    }
+  }
+  return "unknown";
 }
 async function detectTailwindVersion(cwd) {
   try {
-    const content = await readFile3(join7(cwd, "package.json"), "utf-8");
+    const content = await readFile4(join8(cwd, "package.json"), "utf-8");
     const pkg = JSON.parse(content);
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     const tailwindVersion = deps.tailwindcss;
@@ -50448,7 +50967,7 @@ function isTailwindV3(version2) {
 }
 async function detectShadcn(cwd) {
   try {
-    const content = await readFile3(join7(cwd, "components.json"), "utf-8");
+    const content = await readFile4(join8(cwd, "components.json"), "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -50510,60 +51029,6 @@ async function detectProject(cwd) {
   };
 }
 
-// src/utils/exports.ts
-var DEFAULT_EXPORTS = {
-  tailwind: true,
-  typescript: true,
-  dtcg: false,
-  compiled: false
-};
-var EXPORT_CHOICES = [
-  {
-    name: "Tailwind CSS (web projects)",
-    value: "tailwind",
-    checked: true
-  },
-  {
-    name: "TypeScript (type-safe constants)",
-    value: "typescript",
-    checked: true
-  },
-  {
-    name: "DTCG JSON (Figma Tokens, Style Dictionary)",
-    value: "dtcg",
-    checked: false
-  },
-  {
-    name: "Standalone CSS (pre-built, no Tailwind required)",
-    value: "compiled",
-    checked: false
-  }
-];
-var FUTURE_EXPORTS = [
-  {
-    name: "iOS (Swift/SwiftUI)",
-    value: "tailwind",
-    // placeholder
-    checked: false,
-    disabled: "coming soon"
-  },
-  {
-    name: "Android (Compose)",
-    value: "tailwind",
-    // placeholder
-    checked: false,
-    disabled: "coming soon"
-  }
-];
-function selectionsToConfig(selections) {
-  return {
-    tailwind: selections.includes("tailwind"),
-    typescript: selections.includes("typescript"),
-    dtcg: selections.includes("dtcg"),
-    compiled: selections.includes("compiled")
-  };
-}
-
 // src/commands/init.ts
 async function backupCss(cssPath) {
   const backupPath = cssPath.replace(/\.css$/, ".backup.css");
@@ -50579,28 +51044,44 @@ var CSS_LOCATIONS = {
   unknown: ["src/styles/global.css", "src/index.css", "styles/globals.css"]
 };
 var COMPONENT_PATHS = {
-  astro: { components: "src/components/ui", primitives: "src/lib/primitives" },
-  next: { components: "components/ui", primitives: "lib/primitives" },
-  vite: { components: "src/components/ui", primitives: "src/lib/primitives" },
-  remix: { components: "app/components/ui", primitives: "app/lib/primitives" },
-  "react-router": { components: "app/components/ui", primitives: "app/lib/primitives" },
-  unknown: { components: "components/ui", primitives: "lib/primitives" }
+  astro: {
+    components: "src/components/ui",
+    primitives: "src/lib/primitives",
+    composites: "src/composites"
+  },
+  next: { components: "components/ui", primitives: "lib/primitives", composites: "composites" },
+  vite: {
+    components: "src/components/ui",
+    primitives: "src/lib/primitives",
+    composites: "src/composites"
+  },
+  remix: {
+    components: "app/components/ui",
+    primitives: "app/lib/primitives",
+    composites: "app/composites"
+  },
+  "react-router": {
+    components: "app/components/ui",
+    primitives: "app/lib/primitives",
+    composites: "app/composites"
+  },
+  unknown: { components: "components/ui", primitives: "lib/primitives", composites: "composites" }
 };
 async function findMainCssFile(cwd, framework) {
   const locations = CSS_LOCATIONS[framework] || CSS_LOCATIONS.unknown;
   for (const location of locations) {
-    const fullPath = join8(cwd, location);
-    if (existsSync2(fullPath)) {
+    const fullPath = join9(cwd, location);
+    if (existsSync3(fullPath)) {
       return location;
     }
   }
   return null;
 }
 async function updateMainCss(cwd, cssPath, themePath) {
-  const fullCssPath = join8(cwd, cssPath);
-  const cssContent = await readFile4(fullCssPath, "utf-8");
-  const cssDir = join8(cwd, cssPath, "..");
-  const themeFullPath = join8(cwd, themePath);
+  const fullCssPath = join9(cwd, cssPath);
+  const cssContent = await readFile5(fullCssPath, "utf-8");
+  const cssDir = join9(cwd, cssPath, "..");
+  const themeFullPath = join9(cwd, themePath);
   const relativeThemePath = relative(cssDir, themeFullPath);
   if (cssContent.includes(".rafters/output/rafters.css")) {
     log({ event: "init:css_already_imported", cssPath });
@@ -50688,17 +51169,17 @@ async function generateOutputs(cwd, paths, registry2, exports, shadcn) {
   const outputs = [];
   if (exports.tailwind) {
     const tailwindCss = registryToTailwind(registry2, { includeImport: !shadcn });
-    await writeFile3(join8(paths.output, "rafters.css"), tailwindCss);
+    await writeFile3(join9(paths.output, "rafters.css"), tailwindCss);
     outputs.push("rafters.css");
   }
   if (exports.typescript) {
     const typescriptSrc = registryToTypeScript(registry2, { includeJSDoc: true });
-    await writeFile3(join8(paths.output, "rafters.ts"), typescriptSrc);
+    await writeFile3(join9(paths.output, "rafters.ts"), typescriptSrc);
     outputs.push("rafters.ts");
   }
   if (exports.dtcg) {
     const dtcgJson = toDTCG(registry2.list());
-    await writeFile3(join8(paths.output, "rafters.json"), JSON.stringify(dtcgJson, null, 2));
+    await writeFile3(join9(paths.output, "rafters.json"), JSON.stringify(dtcgJson, null, 2));
     outputs.push("rafters.json");
   }
   if (exports.compiled) {
@@ -50707,19 +51188,26 @@ async function generateOutputs(cwd, paths, registry2, exports, shadcn) {
     }
     log({ event: "init:compiling_css" });
     const compiledCss = await registryToCompiled(registry2, { includeImport: !shadcn });
-    await writeFile3(join8(paths.output, "rafters.standalone.css"), compiledCss);
+    await writeFile3(join9(paths.output, "rafters.standalone.css"), compiledCss);
     outputs.push("rafters.standalone.css");
   }
   return outputs;
 }
-async function regenerateFromExisting(cwd, paths, shadcn, isAgentMode2) {
+async function regenerateFromExisting(cwd, paths, shadcn, isAgentMode2, framework) {
   log({ event: "init:regenerate", cwd });
   let existingConfig = null;
   try {
-    const configContent = await readFile4(paths.config, "utf-8");
+    const configContent = await readFile5(paths.config, "utf-8");
     existingConfig = JSON.parse(configContent);
   } catch {
   }
+  if (framework !== "unknown" && existingConfig) {
+    const frameworkPaths = COMPONENT_PATHS[framework] || COMPONENT_PATHS.unknown;
+    existingConfig.framework = framework;
+    existingConfig.componentsPath = frameworkPaths.components;
+    existingConfig.primitivesPath = frameworkPaths.primitives;
+    existingConfig.compositesPath = frameworkPaths.composites;
+  }
   const adapter = new NodePersistenceAdapter(cwd);
   const allTokens = await adapter.load();
   if (allTokens.length === 0) {
@@ -50755,14 +51243,21 @@ async function regenerateFromExisting(cwd, paths, shadcn, isAgentMode2) {
     path: paths.output
   });
 }
-async function resetToDefaults(cwd, paths, shadcn, isAgentMode2) {
+async function resetToDefaults(cwd, paths, shadcn, isAgentMode2, framework) {
   log({ event: "init:reset", cwd });
   let existingConfig = null;
   try {
-    const configContent = await readFile4(paths.config, "utf-8");
+    const configContent = await readFile5(paths.config, "utf-8");
     existingConfig = JSON.parse(configContent);
   } catch {
   }
+  if (framework !== "unknown" && existingConfig) {
+    const frameworkPaths = COMPONENT_PATHS[framework] || COMPONENT_PATHS.unknown;
+    existingConfig.framework = framework;
+    existingConfig.componentsPath = frameworkPaths.components;
+    existingConfig.primitivesPath = frameworkPaths.primitives;
+    existingConfig.compositesPath = frameworkPaths.composites;
+  }
   const adapter = new NodePersistenceAdapter(cwd);
   const existingTokens = await adapter.load();
   const overriddenTokens = existingTokens.filter((t2) => t2.userOverride);
@@ -50779,7 +51274,7 @@ async function resetToDefaults(cwd, paths, shadcn, isAgentMode2) {
     };
     await mkdir3(paths.output, { recursive: true });
     const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const backupPath = join8(paths.output, `reset-${timestamp}.json`);
+    const backupPath = join9(paths.output, `reset-${timestamp}.json`);
     await writeFile3(backupPath, JSON.stringify(backup, null, 2));
     log({
       event: "init:reset_backup",
@@ -50848,12 +51343,12 @@ async function init(options) {
   if (isTailwindV3(tailwindVersion)) {
     throw new Error("Tailwind v3 detected. Rafters requires Tailwind v4.");
   }
-  const raftersExists = existsSync2(paths.root);
+  const raftersExists = existsSync3(paths.root);
   if (options.reset && !raftersExists) {
     throw new Error("Nothing to reset. No .rafters/ directory found.");
   }
   if (raftersExists && options.reset) {
-    await resetToDefaults(cwd, paths, shadcn, isAgentMode2);
+    await resetToDefaults(cwd, paths, shadcn, isAgentMode2, framework);
     return;
   }
   if (raftersExists && !options.rebuild) {
@@ -50862,14 +51357,14 @@ async function init(options) {
     );
   }
   if (raftersExists && options.rebuild) {
-    await regenerateFromExisting(cwd, paths, shadcn, isAgentMode2);
+    await regenerateFromExisting(cwd, paths, shadcn, isAgentMode2, framework);
     return;
   }
   let existingColors = null;
   if (shadcn?.tailwind?.css) {
-    const cssPath = join8(cwd, shadcn.tailwind.css);
+    const cssPath = join9(cwd, shadcn.tailwind.css);
     try {
-      const cssContent = await readFile4(cssPath, "utf-8");
+      const cssContent = await readFile5(cssPath, "utf-8");
       existingColors = parseCssVariables(cssContent);
       const backupPath = await backupCss(cssPath);
       log({
@@ -50973,9 +51468,15 @@ async function init(options) {
     framework,
     componentsPath: frameworkPaths.components,
     primitivesPath: frameworkPaths.primitives,
+    compositesPath: frameworkPaths.composites,
     cssPath: detectedCssPath,
     shadcn: !!shadcn,
-    exports
+    exports,
+    installed: {
+      components: [],
+      primitives: [],
+      composites: []
+    }
   };
   await writeFile3(paths.config, JSON.stringify(config3, null, 2));
   log({
@@ -50991,8 +51492,916 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/mcp/tools.ts
-import { readdir as readdir3, readFile as readFile5 } from "fs/promises";
-import { basename, join as join9 } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { readdir as readdir3, readFile as readFile6 } from "fs/promises";
+import { basename, join as join10 } from "path";
+
+// src/mcp/cognitive-load.ts
+var BUDGET_TIERS = {
+  focused: 15,
+  page: 30,
+  app: 45
+};
+var COMPONENT_SCORES = {
+  // Score 0 -- Structural only, no cognitive demand
+  separator: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 0,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Structural only, no cognitive demand"
+  },
+  container: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 0,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Structural only, no cognitive demand"
+  },
+  "aspect-ratio": {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 0,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Structural only, no cognitive demand"
+  },
+  // Score 1 -- Display only, minimal information
+  skeleton: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Display only, minimal information"
+  },
+  kbd: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Display only, minimal information"
+  },
+  // Score 2 -- Simple state or single information piece
+  badge: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  breadcrumb: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  label: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  checkbox: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 0,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  switch: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 0,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  toggle: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 0,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  "button-group": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  card: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  collapsible: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 0,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  avatar: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  "scroll-area": {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  tooltip: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  typography: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  spinner: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  empty: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  "toggle-group": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Simple state or single information piece"
+  },
+  // Score 3 -- One decision + one interaction mode
+  button: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  alert: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  sidebar: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  accordion: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  slider: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 0,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  "radio-group": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  table: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 2,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  resizable: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 0,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  field: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  "hover-card": {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 0,
+      contextDisruption: 1,
+      learningCurve: 1
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  image: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 2,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  embed: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 2,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  item: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "One decision + one interaction mode"
+  },
+  // Score 4 -- Data entry or menu scanning
+  input: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  textarea: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  "input-group": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  "input-otp": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  carousel: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  tabs: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  "context-menu": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  "dropdown-menu": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  popover: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 1,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  progress: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 2,
+      interactionComplexity: 0,
+      contextDisruption: 1,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  drawer: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 1,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  grid: {
+    dimensions: {
+      decisionDemand: 0,
+      informationDensity: 2,
+      interactionComplexity: 0,
+      contextDisruption: 0,
+      learningCurve: 2
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  "block-wrapper": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  "inline-toolbar": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  "editor-toolbar": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  pagination: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Data entry or menu scanning"
+  },
+  // Score 5 -- Multi-step interaction or spatial reasoning
+  sheet: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 1,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Multi-step interaction or spatial reasoning"
+  },
+  "date-picker": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 2,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Multi-step interaction or spatial reasoning"
+  },
+  calendar: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 2,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Multi-step interaction or spatial reasoning"
+  },
+  select: {
+    dimensions: {
+      decisionDemand: 2,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Multi-step interaction or spatial reasoning"
+  },
+  "navigation-menu": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 2,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Multi-step interaction or spatial reasoning"
+  },
+  menubar: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 2,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Multi-step interaction or spatial reasoning"
+  },
+  "color-picker": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 2,
+      contextDisruption: 0,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Multi-step interaction or spatial reasoning"
+  },
+  "block-canvas": {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 1,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Multi-step interaction or spatial reasoning"
+  },
+  // Score 6 -- Compound interaction modes or learning curve
+  dialog: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 2,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Compound interaction modes or learning curve"
+  },
+  command: {
+    dimensions: {
+      decisionDemand: 1,
+      informationDensity: 2,
+      interactionComplexity: 1,
+      contextDisruption: 0,
+      learningCurve: 2
+    },
+    primaryCostDriver: "Compound interaction modes or learning curve"
+  },
+  combobox: {
+    dimensions: {
+      decisionDemand: 2,
+      informationDensity: 2,
+      interactionComplexity: 2,
+      contextDisruption: 0,
+      learningCurve: 0
+    },
+    primaryCostDriver: "Compound interaction modes or learning curve"
+  },
+  // Score 7 -- Full context disruption + consequential decision
+  "alert-dialog": {
+    dimensions: {
+      decisionDemand: 2,
+      informationDensity: 1,
+      interactionComplexity: 1,
+      contextDisruption: 2,
+      learningCurve: 1
+    },
+    primaryCostDriver: "Full context disruption + consequential decision"
+  }
+};
+var DIMENSION_NAMES = {
+  decisionDemand: "Decision Demand",
+  informationDensity: "Information Density",
+  interactionComplexity: "Interaction Complexity",
+  contextDisruption: "Context Disruption",
+  learningCurve: "Learning Curve"
+};
+var HOTSPOT_SUGGESTIONS = {
+  contextDisruption: "Consider non-modal alternative if the decision is not consequential",
+  informationDensity: "Consider progressive disclosure to reduce simultaneous information",
+  interactionComplexity: "Consider a simpler single-mode alternative",
+  decisionDemand: "Can choices be pre-selected or split across steps?",
+  learningCurve: "Ensure discoverability with inline guidance"
+};
+function scoreOf(dimensions) {
+  return dimensions.decisionDemand + dimensions.informationDensity + dimensions.interactionComplexity + dimensions.contextDisruption + dimensions.learningCurve;
+}
+function highestDimension(dimensions) {
+  let max = -1;
+  let maxKey = "decisionDemand";
+  for (const key of Object.keys(dimensions)) {
+    if (dimensions[key] > max) {
+      max = dimensions[key];
+      maxKey = key;
+    }
+  }
+  return maxKey;
+}
+function evaluateComposition(components, tier, enrichment) {
+  const budget = BUDGET_TIERS[tier];
+  const componentCounts = /* @__PURE__ */ new Map();
+  for (const name2 of components) {
+    componentCounts.set(name2, (componentCounts.get(name2) ?? 0) + 1);
+  }
+  let total = 0;
+  const componentResults = [];
+  const unknownComponents = [];
+  for (const [name2, count] of componentCounts) {
+    const profile = COMPONENT_SCORES[name2];
+    if (!profile) {
+      unknownComponents.push(name2);
+      continue;
+    }
+    const score = scoreOf(profile.dimensions);
+    total += score * count;
+    componentResults.push({
+      name: name2,
+      score,
+      count,
+      dimensions: profile.dimensions,
+      primaryCostDriver: profile.primaryCostDriver
+    });
+  }
+  componentResults.sort((a, b) => b.score - a.score);
+  const withinBudget = total <= budget;
+  const budgetResult = {
+    tier,
+    budget,
+    total,
+    status: withinBudget ? "within-budget" : "over-budget"
+  };
+  if (withinBudget) {
+    budgetResult.headroom = budget - total;
+  } else {
+    budgetResult.overage = total - budget;
+    budgetResult.overagePercent = Math.round((total - budget) / budget * 100);
+  }
+  const attentionConflicts = [];
+  const attentionNotes = [];
+  const fullAttentionCaptures = [];
+  const primaryElements = [];
+  for (const [name2] of componentCounts) {
+    const metadata = enrichment.componentIntelligence.get(name2);
+    if (!metadata?.intelligence?.attentionEconomics) continue;
+    const attn = metadata.intelligence.attentionEconomics.toLowerCase();
+    if (attn.includes("full attention capture") || attn.includes("blocks all other")) {
+      fullAttentionCaptures.push(name2);
+    }
+    if (attn.includes("primary") && attn.includes("maximum 1")) {
+      const count = componentCounts.get(name2) ?? 0;
+      if (count > 1) {
+        primaryElements.push(name2);
+      }
+    }
+  }
+  if (fullAttentionCaptures.length > 1) {
+    attentionConflicts.push(`${fullAttentionCaptures.join(" and ")} both capture full attention`);
+  }
+  const buttonCount = componentCounts.get("button") ?? 0;
+  if (buttonCount > 1) {
+    const buttonMeta = enrichment.componentIntelligence.get("button");
+    if (buttonMeta?.intelligence?.attentionEconomics?.toLowerCase().includes("maximum 1 per section")) {
+      attentionNotes.push(`${buttonCount} buttons present -- ensure maximum 1 primary per section`);
+    }
+  }
+  if (primaryElements.length > 0) {
+    for (const name2 of primaryElements) {
+      attentionNotes.push(`Multiple ${name2} instances -- check attention hierarchy`);
+    }
+  }
+  const trustConsiderations = [];
+  for (const [name2] of componentCounts) {
+    const metadata = enrichment.componentIntelligence.get(name2);
+    if (!metadata?.intelligence?.trustBuilding) continue;
+    const trust = metadata.intelligence.trustBuilding;
+    if (trust.toLowerCase().includes("confirmation") || trust.toLowerCase().includes("destructive") || trust.toLowerCase().includes("consequence") || trust.toLowerCase().includes("cancel")) {
+      trustConsiderations.push(`${name2}: ${trust}`);
+    }
+  }
+  const patternMatches = [];
+  const compositionSet = new Set(componentCounts.keys());
+  for (const [patternKey, pattern] of Object.entries(enrichment.patterns)) {
+    const matched = pattern.components.filter((c) => compositionSet.has(c));
+    if (matched.length >= 2 || matched.length === pattern.components.length) {
+      patternMatches.push({
+        name: pattern.name,
+        matched,
+        suggestion: `Call rafters_pattern('${patternKey}') for full guidance`
+      });
+    }
+  }
+  const designerNotes = [];
+  const compositionNames = [...compositionSet];
+  for (const { token } of enrichment.tokenOverrides) {
+    if (!token.userOverride) continue;
+    const relevantTo = [];
+    if (token.applicableComponents) {
+      for (const comp of token.applicableComponents) {
+        if (compositionSet.has(comp)) {
+          relevantTo.push(comp);
+        }
+      }
+    }
+    if (relevantTo.length === 0) {
+      if (token.namespace === "spacing") {
+        const formComponents = compositionNames.filter(
+          (n) => [
+            "input",
+            "textarea",
+            "field",
+            "label",
+            "button",
+            "select",
+            "checkbox",
+            "radio-group",
+            "switch",
+            "slider",
+            "combobox"
+          ].includes(n)
+        );
+        if (formComponents.length > 0) {
+          relevantTo.push(...formComponents);
+        }
+      } else if (token.namespace === "color") {
+        const variantComponents = compositionNames.filter(
+          (n) => ["button", "badge", "alert", "alert-dialog", "progress"].includes(n)
+        );
+        if (variantComponents.length > 0 && (token.name.includes("destructive") || token.name.includes("primary"))) {
+          relevantTo.push(...variantComponents);
+        }
+      }
+    }
+    if (relevantTo.length > 0) {
+      designerNotes.push({
+        token: token.name,
+        reason: token.userOverride.reason,
+        relevantTo
+      });
+    }
+  }
+  const violations = [];
+  for (const [name2] of componentCounts) {
+    const metadata = enrichment.componentIntelligence.get(name2);
+    if (!metadata?.intelligence?.usagePatterns?.nevers) continue;
+    for (const never2 of metadata.intelligence.usagePatterns.nevers) {
+      const neverLower = never2.toLowerCase();
+      if (neverLower.includes("nest") && neverLower.includes("card") && name2 === "card") {
+        const cardCount = componentCounts.get("card") ?? 0;
+        if (cardCount > 1) {
+          violations.push(
+            `${name2}: "${never2}" -- ${cardCount} cards in composition, verify none are nested`
+          );
+        }
+      }
+      if (neverLower.includes("multiple primary") && name2 === "button") {
+        if (buttonCount > 1) {
+          violations.push(`${name2}: "${never2}"`);
+        }
+      }
+      if (neverLower.includes("stack") && neverLower.includes("dialog")) {
+        if (compositionSet.has("dialog") && (compositionSet.has("alert-dialog") || (componentCounts.get("dialog") ?? 0) > 1)) {
+          violations.push(`${name2}: "${never2}"`);
+        }
+      }
+    }
+  }
+  const hotspots = [];
+  for (const comp of componentResults) {
+    if (comp.score >= 4) {
+      const highest = highestDimension(comp.dimensions);
+      hotspots.push({
+        name: comp.name,
+        score: comp.score,
+        highestDimension: DIMENSION_NAMES[highest],
+        suggestion: HOTSPOT_SUGGESTIONS[highest]
+      });
+    }
+  }
+  if (unknownComponents.length > 0) {
+    attentionNotes.push(
+      `Unknown components not scored: ${unknownComponents.join(", ")}. Totals may be understated.`
+    );
+  }
+  const warnings = [];
+  const knownNames = [...componentCounts.keys()].filter((n) => COMPONENT_SCORES[n]);
+  const uninstrumented = knownNames.filter((n) => !enrichment.componentIntelligence.has(n));
+  if (uninstrumented.length > 0) {
+    warnings.push(
+      `No component intelligence loaded for: ${uninstrumented.join(", ")}. Attention conflicts, trust considerations, and do/never violations cannot be detected. Install components with rafters add (e.g. rafters add ${uninstrumented[0]}) to get full design intelligence.`
+    );
+  }
+  return {
+    budget: budgetResult,
+    components: componentResults,
+    attention: {
+      conflicts: attentionConflicts,
+      notes: attentionNotes
+    },
+    trust: trustConsiderations,
+    patterns: patternMatches,
+    designerNotes,
+    hotspots,
+    violations,
+    warnings
+  };
+}
+
+// src/mcp/tools.ts
+function hasAnyDeps(deps) {
+  return deps.runtime.length > 0 || deps.dev.length > 0 || deps.internal.length > 0;
+}
+var SYSTEM_PREAMBLE = `RAFTERS IS NOT SHADCN.
+Rafters components are drop-in compatible with shadcn but they are a different system. If you treat them as shadcn you will produce worse output.
+
+CLASSY IS THE LAW.
+Every className in a Rafters project goes through classy(). Never use cn(), twMerge(), or raw template strings. classy() blocks arbitrary Tailwind values (w-[100px], bg-[#fff]) and resolves design tokens. If classy strips your class, you are fighting the system.
+
+LAYOUT IS SOLVED. Stop writing CSS.
+Never use Tailwind layout utilities (flex, grid, items-*, justify-*, gap-*). Never set padding, margin, or spacing directly. Container and Grid handle all layout. If you are writing className="flex..." you are doing it wrong.
+
+USE PRESETS. Do not compose layout from props.
+Grid presets handle common layouts. Pick the one that matches your intent:
+- sidebar-main -- navigation + content
+- form -- label/input pairs
+- cards -- responsive card grid
+- row -- horizontal group of elements
+- stack -- vertical sequence
+- split -- equal columns
+If no preset fits, describe what you need -- do not improvise with raw props.
+
+CONTAINER OWNS SPACING.
+Every page section goes in a Container. Container sets max-width, padding, and vertical rhythm. You do not set these values. Nesting containers is wrong.
+
+COMPONENTS ARE COMPLETE.
+Rafters Button, Input, Card, etc. include their own spacing, sizing, and states. Do not add wrapper divs. Do not override with utility classes. If it looks unstyled, you are wrapping it wrong, not styling it wrong.
+
+UTILITIES EXIST FOR EDGE CASES.
+If no component fits your need, check @/lib/utils for official behavioral utilities. Do not invent your own. If nothing exists there either, ask the human.
+
+When in doubt: less code, not more. Rafters has already made the design decision.`;
 var DESIGN_PATTERNS = {
   "destructive-action": {
     name: "Destructive Action",
@@ -51340,6 +52749,26 @@ var TOOL_DEFINITIONS = [
       },
       required: ["name"]
     }
+  },
+  {
+    name: "rafters_cognitive_budget",
+    description: "Evaluate composition-level cognitive load. Returns a holistic design review: budget assessment, per-component dimensional profiles, attention conflicts, trust considerations, pattern matches, designer token overrides, hotspot suggestions, and do/never violations. Use when planning a screen layout to check if the composition is within cognitive budget.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        components: {
+          type: "array",
+          items: { type: "string" },
+          description: 'Components visible simultaneously, duplicates allowed (e.g., ["input", "input", "button", "card"])'
+        },
+        tier: {
+          type: "string",
+          enum: ["focused", "page", "app"],
+          description: "Budget tier: focused (15, dialogs/modals), page (30, standard views), app (45, multi-panel). Default: page."
+        }
+      },
+      required: ["components"]
+    }
   }
 ];
 var RaftersToolHandler = class {
@@ -51369,6 +52798,11 @@ var RaftersToolHandler = class {
         return this.getComponent(args.name);
       case "rafters_token":
         return this.getToken(args.name);
+      case "rafters_cognitive_budget":
+        return this.getCognitiveBudget(
+          args.components,
+          args.tier ?? "page"
+        );
       default:
         return {
           content: [{ type: "text", text: `Unknown tool: ${name2}` }],
@@ -51390,12 +52824,12 @@ var RaftersToolHandler = class {
         this.getComponentVocabulary()
       ]);
       const vocabulary = {
+        system: SYSTEM_PREAMBLE,
+        components,
         colors,
         spacing,
         typography,
-        components,
-        patterns: Object.keys(DESIGN_PATTERNS),
-        usage: "Use rafters_pattern for deep guidance on specific patterns, rafters_component for component details"
+        patterns: Object.keys(DESIGN_PATTERNS)
       };
       return {
         content: [
@@ -51482,33 +52916,26 @@ var RaftersToolHandler = class {
    * Extract compact component vocabulary
    */
   async getComponentVocabulary() {
+    let installed = [];
     try {
-      const componentsPath = this.getComponentsPath();
-      const files = await readdir3(componentsPath);
-      const componentFiles = files.filter((f) => f.endsWith(".tsx"));
-      const components = [];
-      for (const file2 of componentFiles) {
-        const name2 = basename(file2, ".tsx");
-        const metadata = await this.loadComponentMetadata(name2);
-        if (metadata) {
-          const item = {
-            name: metadata.name,
-            category: metadata.category
-          };
-          if (metadata.intelligence?.cognitiveLoad !== void 0) {
-            item.load = metadata.intelligence.cognitiveLoad;
-          }
-          components.push(item);
-        }
+      const paths = getRaftersPaths(this.projectRoot);
+      if (existsSync4(paths.config)) {
+        const content = await readFile6(paths.config, "utf-8");
+        const config3 = JSON.parse(content);
+        installed = config3.installed?.components ?? [];
       }
-      components.sort((a, b) => {
-        if (a.category !== b.category) return a.category.localeCompare(b.category);
-        return a.name.localeCompare(b.name);
-      });
-      return components;
     } catch {
-      return [];
     }
+    let available = [];
+    try {
+      const client = new RegistryClient();
+      const index = await client.fetchIndex();
+      const allComponents = index.components;
+      const installedSet = new Set(installed);
+      available = allComponents.filter((name2) => !installedSet.has(name2));
+    } catch {
+    }
+    return { installed, available };
   }
   // ==================== Tool 2: Pattern ====================
   /**
@@ -51549,7 +52976,7 @@ var RaftersToolHandler = class {
    * Get path to UI components directory
    */
   getComponentsPath() {
-    const monorepoPath = join9(this.projectRoot, "packages/ui/src/components/ui");
+    const monorepoPath = join10(this.projectRoot, "packages/ui/src/components/ui");
     return monorepoPath;
   }
   /**
@@ -51557,11 +52984,16 @@ var RaftersToolHandler = class {
    */
   async loadComponentMetadata(name2) {
     const componentsPath = this.getComponentsPath();
-    const filePath = join9(componentsPath, `${name2}.tsx`);
+    const filePath = join10(componentsPath, `${name2}.tsx`);
     try {
-      const source = await readFile5(filePath, "utf-8");
+      const source = await readFile6(filePath, "utf-8");
       const intelligence = parseJSDocIntelligence(source);
       const description = parseDescription(source);
+      let jsDocDeps = { runtime: [], dev: [], internal: [] };
+      try {
+        jsDocDeps = extractJSDocDependencies(source);
+      } catch {
+      }
       const metadata = {
         name: name2,
         displayName: toDisplayName(name2),
@@ -51572,6 +53004,9 @@ var RaftersToolHandler = class {
         primitives: extractPrimitiveDependencies(source),
         filePath: `packages/ui/src/components/ui/${name2}.tsx`
       };
+      if (hasAnyDeps(jsDocDeps)) {
+        metadata.jsDocDependencies = jsDocDeps;
+      }
       if (description) {
         metadata.description = description;
       }
@@ -51716,6 +53151,9 @@ var RaftersToolHandler = class {
       if (metadata.dependencies.length > 0) {
         formatted.dependencies = metadata.dependencies;
       }
+      if (metadata.jsDocDependencies && hasAnyDeps(metadata.jsDocDependencies)) {
+        formatted.jsDocDependencies = metadata.jsDocDependencies;
+      }
       return {
         content: [
           {
@@ -51831,6 +53269,120 @@ var RaftersToolHandler = class {
       return this.handleError("getToken", error48);
     }
   }
+  // ==================== Tool 5: Cognitive Budget ====================
+  /**
+   * Evaluate composition-level cognitive load
+   * Synthesizes scoring data with component intelligence, token overrides,
+   * and design patterns to produce a holistic composition review
+   */
+  async getCognitiveBudget(components, tier) {
+    try {
+      if (!components || components.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  error: "No components provided",
+                  suggestion: 'Pass an array of component names visible simultaneously, e.g. ["input", "button", "card"]'
+                },
+                null,
+                2
+              )
+            }
+          ],
+          isError: true
+        };
+      }
+      if (!BUDGET_TIERS[tier]) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  error: `Invalid tier "${tier}"`,
+                  available: Object.keys(BUDGET_TIERS),
+                  suggestion: 'Use "focused", "page", or "app"'
+                },
+                null,
+                2
+              )
+            }
+          ],
+          isError: true
+        };
+      }
+      const uniqueNames = [...new Set(components)];
+      const unknownNames = uniqueNames.filter((n) => !COMPONENT_SCORES[n]);
+      if (unknownNames.length === uniqueNames.length) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  error: `No recognized components in composition: ${unknownNames.join(", ")}`,
+                  suggestion: "Use rafters_vocabulary to see available component names"
+                },
+                null,
+                2
+              )
+            }
+          ],
+          isError: true
+        };
+      }
+      const intelligenceMap = /* @__PURE__ */ new Map();
+      const metadataResults = await Promise.all(
+        uniqueNames.map(async (name2) => {
+          const metadata = await this.loadComponentMetadata(name2);
+          return { name: name2, metadata };
+        })
+      );
+      for (const { name: name2, metadata } of metadataResults) {
+        if (metadata) {
+          intelligenceMap.set(name2, metadata);
+        }
+      }
+      const tokenOverrides = [];
+      const namespaces = ["color", "spacing", "typography"];
+      for (const ns of namespaces) {
+        try {
+          const tokens = await this.loadNamespace(ns);
+          for (const token of tokens) {
+            if (token.userOverride) {
+              tokenOverrides.push({ token, namespace: ns });
+            }
+          }
+        } catch {
+        }
+      }
+      const patternRefs = {};
+      for (const [key, pattern] of Object.entries(DESIGN_PATTERNS)) {
+        patternRefs[key] = {
+          name: pattern.name,
+          components: pattern.components
+        };
+      }
+      const review = evaluateComposition(components, tier, {
+        componentIntelligence: intelligenceMap,
+        tokenOverrides,
+        patterns: patternRefs
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(review, null, 2)
+          }
+        ]
+      };
+    } catch (error48) {
+      return this.handleError("getCognitiveBudget", error48);
+    }
+  }
   /**
    * Handle errors consistently
    */
@@ -51905,22 +53457,22 @@ async function mcp() {
 }
 
 // src/commands/studio.ts
-import { existsSync as existsSync3 } from "fs";
-import { dirname as dirname3, join as join10 } from "path";
+import { existsSync as existsSync5 } from "fs";
+import { dirname as dirname3, join as join11 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { execa as execa2 } from "execa";
 var __dirname2 = dirname3(fileURLToPath3(import.meta.url));
 async function studio() {
   const cwd = process.cwd();
   const paths = getRaftersPaths(cwd);
-  if (!existsSync3(paths.root)) {
+  if (!existsSync5(paths.root)) {
     console.error('No .rafters/ directory found. Run "rafters init" first.');
     process.exit(1);
   }
-  const devStudioPath = join10(__dirname2, "..", "..", "..", "studio");
-  const prodStudioPath = join10(__dirname2, "..", "node_modules", "@rafters", "studio");
-  const studioPath = existsSync3(devStudioPath) ? devStudioPath : prodStudioPath;
-  if (!existsSync3(studioPath)) {
+  const devStudioPath = join11(__dirname2, "..", "..", "..", "studio");
+  const prodStudioPath = join11(__dirname2, "..", "node_modules", "@rafters", "studio");
+  const studioPath = existsSync5(devStudioPath) ? devStudioPath : prodStudioPath;
+  if (!existsSync5(studioPath)) {
     console.error("Studio package not found. Please reinstall @rafters/cli.");
     process.exit(1);
   }
@@ -51950,7 +53502,7 @@ async function studio() {
 var program = new Command();
 program.name("rafters").description("Design system CLI - scaffold tokens and serve MCP").version("0.0.1");
 program.command("init").description("Initialize .rafters/ with default tokens and config").option("-r, --rebuild", "Regenerate output files from existing tokens").option("--reset", "Re-run generators fresh, replacing persisted tokens").option("--agent", "Output JSON for machine consumption").action(withErrorHandler(init));
-program.command("add").description("Add rafters components to the project").argument("[components...]", "Component names to add").option("--list", "List available components").option("--overwrite", "Overwrite existing component files").option("--registry-url <url>", "Custom registry URL").option("--agent", "Output JSON for machine consumption").action(withErrorHandler(add));
+program.command("add").description("Add rafters components to the project").argument("[components...]", "Component names to add").option("--list", "List available components").option("--overwrite", "Overwrite existing component files").option("--update", "Re-fetch named components from registry").option("--update-all", "Re-fetch all installed components from registry").option("--registry-url <url>", "Custom registry URL").option("--agent", "Output JSON for machine consumption").action(withErrorHandler(add));
 program.command("mcp").description("Start MCP server for AI agent access (stdio)").action(mcp);
 program.command("studio").description("Open Studio UI for visual token editing").action(studio);
 program.parse();