rafters 0.0.26 → 0.0.29

package/dist/index.js

@@ -12825,49 +12825,6 @@ async function detectShadcn(cwd) {
     return null;
   }
 }
-function parseCssVariables(css3) {
-  const light = {};
-  const dark = {};
-  const rootMatch = css3.match(/:root\s*\{([^}]+)\}/);
-  if (rootMatch?.[1]) {
-    parseVariablesIntoColors(rootMatch[1], light);
-  }
-  const darkMatch = css3.match(/\.dark\s*\{([^}]+)\}/);
-  if (darkMatch?.[1]) {
-    parseVariablesIntoColors(darkMatch[1], dark);
-  }
-  return { light, dark };
-}
-function parseVariablesIntoColors(block, colors) {
-  const varMap = {
-    "--background": "background",
-    "--foreground": "foreground",
-    "--card": "card",
-    "--card-foreground": "cardForeground",
-    "--popover": "popover",
-    "--popover-foreground": "popoverForeground",
-    "--primary": "primary",
-    "--primary-foreground": "primaryForeground",
-    "--secondary": "secondary",
-    "--secondary-foreground": "secondaryForeground",
-    "--muted": "muted",
-    "--muted-foreground": "mutedForeground",
-    "--accent": "accent",
-    "--accent-foreground": "accentForeground",
-    "--destructive": "destructive",
-    "--destructive-foreground": "destructiveForeground",
-    "--border": "border",
-    "--input": "input",
-    "--ring": "ring"
-  };
-  for (const [cssVar, colorKey] of Object.entries(varMap)) {
-    const regex = new RegExp(`${cssVar}:\\s*([^;]+);`);
-    const match2 = block.match(regex);
-    if (match2?.[1]) {
-      colors[colorKey] = match2[1].trim();
-    }
-  }
-}
 function frameworkToTarget(framework) {
   if (framework === "astro") return "astro";
   return "react";
@@ -12994,14 +12951,6 @@ function log(event) {
       }
       context.spinner = ora("Generating tokens...").start();
       break;
-    case "init:shadcn_detected": {
-      context.spinner?.info("Found existing shadcn colors");
-      console.log(`  Backed up: ${event.backupPath}`);
-      const colors = event.colorsFound;
-      console.log(`  Colors: ${colors.light} light, ${colors.dark} dark`);
-      context.spinner = ora("Generating tokens...").start();
-      break;
-    }
     case "init:generated":
       context.spinner?.succeed(`Generated ${event.tokenCount} tokens`);
       context.spinner = ora("Saving registry...").start();
@@ -13026,8 +12975,16 @@ function log(event) {
       context.spinner?.succeed(`Loaded ${event.tokenCount} tokens`);
       context.spinner = ora("Generating outputs...").start();
       break;
-    case "init:colors_imported":
-      console.log(`  Imported ${event.count} existing colors`);
+    case "init:existing_design_detected":
+      context.spinner?.info("Existing design system detected");
+      console.log(`  Found design decisions in ${event.cssPath}`);
+      console.log("");
+      console.log("  Your existing CSS has design decisions that should be");
+      console.log("  migrated intentionally, not automatically.");
+      console.log("");
+      console.log('  Ask your AI agent: "Onboard my existing design system to Rafters"');
+      console.log("");
+      context.spinner = ora("Finishing up...").start();
       break;
     case "init:prompting_exports":
       context.spinner?.succeed("Configuration ready");
@@ -53340,6 +53297,21 @@ Color.extend(interpolation);
 Color.extend(contrastMethods);
 
 // ../color-utils/src/conversion.ts
+function hexToOKLCH(hex3) {
+  try {
+    const color = new Color(hex3);
+    const oklch2 = color.to("oklch");
+    return {
+      l: oklch2.coords[0] ?? 0,
+      c: oklch2.coords[1] ?? 0,
+      h: oklch2.coords[2] ?? 0,
+      // Handle undefined hue for achromatic colors
+      alpha: oklch2.alpha ?? 1
+    };
+  } catch (_error) {
+    throw new Error(`Invalid hex color: ${hex3}`);
+  }
+}
 function roundOKLCH(oklch2) {
   return {
     l: Math.round(oklch2.l * 1e3) / 1e3,
@@ -58684,26 +58656,6 @@ async function init(options) {
     await regenerateFromExisting(cwd, paths, shadcn, isAgentMode2, framework);
     return;
   }
-  let existingColors = null;
-  if (shadcn?.tailwind?.css) {
-    const cssPath = join9(cwd, shadcn.tailwind.css);
-    try {
-      const cssContent = await readFile5(cssPath, "utf-8");
-      existingColors = parseCssVariables(cssContent);
-      const backupPath = await backupCss(cssPath);
-      log({
-        event: "init:shadcn_detected",
-        cssPath: shadcn.tailwind.css,
-        backupPath,
-        colorsFound: {
-          light: Object.keys(existingColors.light).length,
-          dark: Object.keys(existingColors.dark).length
-        }
-      });
-    } catch (err) {
-      log({ event: "init:shadcn_css_error", error: String(err) });
-    }
-  }
   let exports;
   if (isAgentMode2) {
     exports = DEFAULT_EXPORTS;
@@ -58723,39 +58675,6 @@ async function init(options) {
     }
   });
   const { registry: registry2 } = result;
-  if (existingColors) {
-    const tokenMap = {
-      background: "background",
-      foreground: "foreground",
-      card: "card",
-      "card-foreground": "cardForeground",
-      popover: "popover",
-      "popover-foreground": "popoverForeground",
-      primary: "primary",
-      "primary-foreground": "primaryForeground",
-      secondary: "secondary",
-      "secondary-foreground": "secondaryForeground",
-      muted: "muted",
-      "muted-foreground": "mutedForeground",
-      accent: "accent",
-      "accent-foreground": "accentForeground",
-      destructive: "destructive",
-      "destructive-foreground": "destructiveForeground",
-      border: "border",
-      input: "input",
-      ring: "ring"
-    };
-    for (const [tokenName, colorKey] of Object.entries(tokenMap)) {
-      const colorValue = existingColors.light[colorKey];
-      if (colorValue && registry2.has(tokenName)) {
-        registry2.updateToken(tokenName, colorValue);
-      }
-    }
-    log({
-      event: "init:colors_imported",
-      count: Object.keys(existingColors.light).length
-    });
-  }
   log({
     event: "init:generated",
     tokenCount: registry2.size()
@@ -58823,12 +58742,34 @@ async function init(options) {
     }
   };
   await writeFile3(paths.config, JSON.stringify(config3, null, 2));
+  const existingCssPath = detectedCssPath ?? (shadcn?.tailwind?.css || null);
+  if (existingCssPath) {
+    try {
+      const cssContent = await readFile5(join9(cwd, existingCssPath), "utf-8");
+      if (hasExistingDesignDecisions(cssContent)) {
+        log({
+          event: "init:existing_design_detected",
+          cssPath: existingCssPath,
+          action: "run rafters_onboard analyze to begin migration"
+        });
+      }
+    } catch {
+    }
+  }
   log({
     event: "init:complete",
     outputs: [...outputs, "config.rafters.json"],
     path: paths.output
   });
 }
+function hasExistingDesignDecisions(css3) {
+  const stripped = css3.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*/g, "");
+  const withoutBoilerplate = stripped.replace(/@import\s+['"][^'"]+['"];?/g, "").replace(/@tailwind\s+\w+;?/g, "").trim();
+  if (withoutBoilerplate.length === 0) return false;
+  const hasCustomProperties = /--[\w-]+\s*:/.test(stripped);
+  const hasThemeBlock = /@theme\s*\{/.test(stripped);
+  return hasCustomProperties || hasThemeBlock;
+}
 
 // src/commands/mcp.ts
 import { existsSync as existsSync6 } from "fs";
@@ -58841,7 +58782,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 
 // src/mcp/tools.ts
 import { existsSync as existsSync4 } from "fs";
-import { readdir as readdir3, readFile as readFile6 } from "fs/promises";
+import { mkdir as mkdir4, readdir as readdir3, readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
 import { basename, join as join10, relative as relative2 } from "path";
 
 // src/mcp/cognitive-load.ts
@@ -59752,6 +59693,19 @@ If no component fits your need, check @/lib/utils for official behavioral utilit
 COLORS ARE TAILWIND CLASSES.
 Write border-l-primary, bg-success, text-info-foreground. Do not create color constants, mapping objects, or reference palette names. Palette families are internal. See quickstart.colorTokens for the full list of semantic tokens and usage examples.
 
+ONBOARDING IS INTENTIONAL.
+When onboarding an existing project, do NOT skip the learning step.
+1. Call rafters_vocabulary and explore token shapes first. Understand namespaces, dependency graph, the two primitives.
+2. Call rafters_onboard analyze to see what existing design decisions are in the CSS.
+3. Do NOT automatically map colors. Ask the designer about each ambiguous decision.
+4. CHALLENGE SEMANTIC ASSIGNMENTS. Do not accept "this is primary" without asking why. "What makes this the primary identity color? Where is it used? What role does it play?" The designer must justify every family assignment.
+5. Every token mutation needs a reason that captures design INTENT, not just origin.
+   Bad: "imported from globals.css"
+   Good: "Brand blue from --brand-primary, primary identity color used on nav and CTAs per designer"
+6. The 11 semantic families (primary, secondary, tertiary, accent, neutral, success, warning, destructive, info, highlight, muted) MUST all be mapped. Extra colors are custom families in the color namespace.
+7. If analyze detects color scale patterns (e.g., --color-blaze-50 through --color-blaze-950), map the family using its base color. Do NOT create 11 individual tokens.
+8. Call rafters_onboard map to execute the migration once the designer confirms. Colors are automatically enriched with full OKLCH scales, harmonies, accessibility data, and API intelligence.
+
 When in doubt: less code, not more. Rafters has already made the design decision.`;
 var CONSUMER_QUICKSTART = {
   rule1: "Components are pre-styled. Import and render. Do not add className for visual styling -- only for layout context (e.g. border-l-4 for accent). Input knows its focus ring. Label knows its weight. You arrange, you do not style.",
@@ -60116,13 +60070,34 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "rafters_token",
-    description: "Get full intelligence for a design token: current value, derivation rule, dependencies, dependents (cascade impact), and human override context. Shows what the system computes vs what a designer chose and why. Use when you need to understand token relationships or respect designer decisions.",
+    description: "Read or write a design token. Read: returns full intelligence (value, derivation, dependencies, cascade impact, override context). Write: set/create/reset tokens with mandatory reason (why-gate). Every write cascades through the dependency graph, persists to disk, and regenerates CSS/TS/DTCG outputs.",
     inputSchema: {
       type: "object",
       properties: {
         name: {
           type: "string",
           description: 'Token name (e.g., "spacing-6", "primary-500", "spacing-base"). Use rafters_vocabulary to see available tokens.'
+        },
+        action: {
+          type: "string",
+          enum: ["get", "set", "create", "reset"],
+          description: "Action to perform. get (default): read token intelligence. set: update existing token value. create: add a new token. reset: clear override, restore computed value."
+        },
+        value: {
+          type: "string",
+          description: "New token value (required for set and create actions)."
+        },
+        reason: {
+          type: "string",
+          description: "Why this change is being made (required for set, create, and reset). Every mutation needs a reason that captures design INTENT."
+        },
+        namespace: {
+          type: "string",
+          description: 'Token namespace (required for create). E.g., "color", "spacing", "typography".'
+        },
+        category: {
+          type: "string",
+          description: 'Token category (required for create). E.g., "color", "spacing", "font".'
         }
       },
       required: ["name"]
@@ -60147,11 +60122,64 @@ var TOOL_DEFINITIONS = [
       },
       required: ["components"]
     }
+  },
+  {
+    name: "rafters_onboard",
+    description: 'Analyze an existing project for design decisions and map them into Rafters tokens. Use "analyze" to surface raw findings. Use "map" to execute -- but map REQUIRES the designer to confirm every mapping first. The tool will reject unconfirmed mappings and instruct you to ask the designer. This is an intentional system, not an automatic one.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["analyze", "map", "status"],
+          description: "analyze: scan CSS and return findings + family checklist. status: show which of the 11 families have designer decisions vs defaults. map: execute confirmed mappings (requires confirmed: true after designer review)."
+        },
+        confirmed: {
+          type: "boolean",
+          description: "Set to true ONLY after the designer has reviewed and approved every mapping. The reasons must come from the designer, not from you."
+        },
+        mappings: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              source: {
+                type: "string",
+                description: 'Original CSS variable name (e.g., "--brand-blue")'
+              },
+              target: {
+                type: "string",
+                description: 'Rafters token name to set or create (e.g., "primary")'
+              },
+              value: {
+                type: "string",
+                description: "The value to set (from the original CSS)"
+              },
+              reason: {
+                type: "string",
+                description: "The designer explains why this mapping makes sense. This must come from the human, not from you. Ask them."
+              },
+              namespace: {
+                type: "string",
+                description: "Namespace for new tokens (required if token does not exist)"
+              },
+              category: {
+                type: "string",
+                description: "Category for new tokens (required if token does not exist)"
+              }
+            },
+            required: ["source", "target", "value", "reason"]
+          },
+          description: "Array of mappings to execute (required for map action)"
+        }
+      },
+      required: ["action"]
+    }
   }
 ];
 var NO_PROJECT_ERROR = "No .rafters/ config found. Run `pnpm dlx rafters init` in your project first. If the MCP server was launched from a different directory, pass --project-root <path>.";
 var PROJECT_INDEPENDENT_TOOLS = /* @__PURE__ */ new Set(["rafters_pattern"]);
-var RaftersToolHandler = class {
+var RaftersToolHandler = class _RaftersToolHandler {
   adapter;
   projectRoot;
   cachedConfig;
@@ -60181,13 +60209,18 @@ var RaftersToolHandler = class {
         return this.getPattern(args.pattern);
       case "rafters_component":
         return this.getComponent(args.name);
-      case "rafters_token":
-        return this.getToken(args.name);
+      case "rafters_token": {
+        const action = args.action ?? "get";
+        if (action === "get") return this.getToken(args.name);
+        return this.writeToken(action, args);
+      }
       case "rafters_cognitive_budget":
         return this.getCognitiveBudget(
           args.components,
           args.tier ?? "page"
         );
+      case "rafters_onboard":
+        return this.onboard(args);
       default:
         return {
           content: [{ type: "text", text: `Unknown tool: ${name2}` }],
@@ -60717,6 +60750,689 @@ var RaftersToolHandler = class {
       return this.handleError("getToken", error48);
     }
   }
+  // ==================== Token Write Operations ====================
+  /**
+   * Handle set, create, and reset actions for rafters_token.
+   * Loads the full registry, mutates, cascades, persists, and regenerates outputs.
+   */
+  async writeToken(action, args) {
+    const name2 = args.name;
+    const reason = args.reason;
+    const value2 = args.value;
+    if (!reason) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: "Reason is required for every token mutation.",
+              hint: "Every change needs a WHY that captures design intent, not just origin.",
+              bad: "imported from globals.css",
+              good: "Brand blue from --brand-primary, primary identity color per designer"
+            })
+          }
+        ],
+        isError: true
+      };
+    }
+    if (!this.adapter || !this.projectRoot) {
+      return { content: [{ type: "text", text: NO_PROJECT_ERROR }], isError: true };
+    }
+    try {
+      const allTokens = await this.adapter.load();
+      const registry2 = new TokenRegistry(allTokens);
+      registry2.setAdapter(this.adapter);
+      switch (action) {
+        case "set": {
+          if (!value2) {
+            return {
+              content: [{ type: "text", text: '{"error": "value is required for set action"}' }],
+              isError: true
+            };
+          }
+          const existing = registry2.get(name2);
+          if (!existing) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: `Token "${name2}" not found. Use action: "create" for new tokens.`
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
+          const previousValue = existing.value;
+          existing.userOverride = {
+            previousValue: typeof previousValue === "string" ? previousValue : JSON.stringify(previousValue),
+            reason
+          };
+          await registry2.set(name2, value2);
+          const affected = this.getAffectedTokens(registry2, name2);
+          await this.regenerateOutputs(registry2);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  ok: true,
+                  action: "set",
+                  name: name2,
+                  reason,
+                  cascaded: affected
+                })
+              }
+            ]
+          };
+        }
+        case "create": {
+          const namespace = args.namespace;
+          const category = args.category;
+          if (!value2) {
+            return {
+              content: [{ type: "text", text: '{"error": "value is required for create action"}' }],
+              isError: true
+            };
+          }
+          if (!namespace) {
+            return {
+              content: [
+                { type: "text", text: '{"error": "namespace is required for create action"}' }
+              ],
+              isError: true
+            };
+          }
+          if (!category) {
+            return {
+              content: [
+                { type: "text", text: '{"error": "category is required for create action"}' }
+              ],
+              isError: true
+            };
+          }
+          if (registry2.has(name2)) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: `Token "${name2}" already exists. Use action: "set" to update.`
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
+          const newToken = {
+            name: name2,
+            namespace,
+            category,
+            value: value2,
+            containerQueryAware: true,
+            userOverride: {
+              previousValue: "",
+              reason
+            }
+          };
+          registry2.add(newToken);
+          await this.adapter.save(registry2.list());
+          await this.regenerateOutputs(registry2);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  ok: true,
+                  action: "create",
+                  name: name2,
+                  namespace,
+                  reason
+                })
+              }
+            ]
+          };
+        }
+        case "reset": {
+          const existing = registry2.get(name2);
+          if (!existing) {
+            return {
+              content: [
+                { type: "text", text: JSON.stringify({ error: `Token "${name2}" not found.` }) }
+              ],
+              isError: true
+            };
+          }
+          await registry2.set(name2, COMPUTED);
+          const affected = this.getAffectedTokens(registry2, name2);
+          await this.regenerateOutputs(registry2);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  ok: true,
+                  action: "reset",
+                  name: name2,
+                  reason,
+                  cascaded: affected
+                })
+              }
+            ]
+          };
+        }
+        default:
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: `Unknown action: ${action}. Use get, set, create, or reset.`
+                })
+              }
+            ],
+            isError: true
+          };
+      }
+    } catch (error48) {
+      return this.handleError("writeToken", error48);
+    }
+  }
+  /**
+   * Get list of tokens that would be affected by changing the given token
+   */
+  getAffectedTokens(registry2, tokenName) {
+    const affected = [];
+    for (const token of registry2.list()) {
+      if (token.dependsOn?.includes(tokenName)) {
+        affected.push(token.name);
+      }
+    }
+    return affected;
+  }
+  /**
+   * Regenerate output files (CSS, TS, DTCG) from registry state
+   */
+  async regenerateOutputs(registry2) {
+    if (!this.projectRoot) return;
+    const paths = getRaftersPaths(this.projectRoot);
+    const config3 = await this.loadConfig();
+    const exports = config3?.exports ?? {
+      tailwind: true,
+      typescript: true,
+      dtcg: false,
+      compiled: false
+    };
+    const shadcn = config3?.shadcn ?? false;
+    await mkdir4(paths.output, { recursive: true });
+    if (exports.tailwind) {
+      const css3 = registryToTailwind(registry2, { includeImport: !shadcn });
+      await writeFile4(join10(paths.output, "rafters.css"), css3);
+    }
+    if (exports.typescript) {
+      const ts = registryToTypeScript(registry2, { includeJSDoc: true });
+      await writeFile4(join10(paths.output, "rafters.ts"), ts);
+    }
+    if (exports.dtcg) {
+      const json3 = toDTCG(registry2.list());
+      await writeFile4(join10(paths.output, "rafters.json"), JSON.stringify(json3, null, 2));
+    }
+  }
+  // ==================== Tool 6: Onboard ====================
+  /**
+   * CSS file locations by framework (mirrors init.ts CSS_LOCATIONS)
+   */
+  static CSS_LOCATIONS = {
+    astro: ["src/styles/global.css", "src/styles/globals.css", "src/global.css"],
+    next: ["src/app/globals.css", "app/globals.css", "styles/globals.css"],
+    vite: ["src/index.css", "src/main.css", "src/styles.css", "src/app.css"],
+    remix: ["app/styles/global.css", "app/globals.css", "app/root.css"],
+    "react-router": ["app/app.css", "app/root.css", "app/styles.css", "app/globals.css"],
+    unknown: [
+      "src/styles/global.css",
+      "src/styles/globals.css",
+      "src/index.css",
+      "src/main.css",
+      "src/app.css",
+      "styles/globals.css",
+      "app/globals.css"
+    ]
+  };
+  /**
+   * The 11 semantic color families every design system needs.
+   * Defaults are not wrong. Unexamined defaults are wrong.
+   */
+  static SEMANTIC_FAMILIES = [
+    "primary",
+    "secondary",
+    "tertiary",
+    "accent",
+    "neutral",
+    "success",
+    "warning",
+    "destructive",
+    "info",
+    "highlight",
+    "muted"
+  ];
+  /**
+   * Handle rafters_onboard tool calls
+   */
+  async onboard(args) {
+    const action = args.action;
+    switch (action) {
+      case "analyze":
+        return this.analyzeProject();
+      case "status":
+        return this.getOnboardStatus();
+      case "map": {
+        const confirmed = args.confirmed;
+        if (!confirmed) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "Human confirmation required.",
+                  action: "STOP. Do not call this tool again until the designer has reviewed and approved every mapping.",
+                  instructions: [
+                    "Show each proposed mapping to the designer: source -> target, value, and your proposed reason.",
+                    'Ask the designer: "Is this the right semantic role? Why did you choose this color for this purpose?"',
+                    "The designer must provide or approve the reason. Do not write reasons yourself.",
+                    "Once the designer has confirmed all mappings, call rafters_onboard map again with confirmed: true."
+                  ]
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+        return this.mapTokens(args.mappings);
+      }
+      default:
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `Unknown action: ${action}. Use analyze or map.` })
+            }
+          ],
+          isError: true
+        };
+    }
+  }
+  /**
+   * Scan the project for existing design decisions.
+   * Returns raw findings -- the agent interprets, not the tool.
+   */
+  async analyzeProject() {
+    if (!this.projectRoot) {
+      return { content: [{ type: "text", text: NO_PROJECT_ERROR }], isError: true };
+    }
+    try {
+      const config3 = await this.loadConfig();
+      const framework = config3?.framework ?? "unknown";
+      const cssFindings = [];
+      const locations = /* @__PURE__ */ new Set();
+      const frameworkLocations = _RaftersToolHandler.CSS_LOCATIONS[framework] ?? _RaftersToolHandler.CSS_LOCATIONS.unknown ?? [];
+      for (const loc of frameworkLocations) locations.add(loc);
+      if (config3?.cssPath) locations.add(config3.cssPath);
+      for (const cssPath of locations) {
+        const fullPath = join10(this.projectRoot, cssPath);
+        if (!existsSync4(fullPath)) continue;
+        try {
+          const content = await readFile6(fullPath, "utf-8");
+          const finding = this.parseCssFindings(cssPath, content);
+          if (finding.customProperties.length > 0 || finding.themeBlocks.length > 0 || finding.imports.length > 0) {
+            cssFindings.push(finding);
+          }
+        } catch {
+        }
+      }
+      let shadcn = { detected: false };
+      try {
+        const componentsJson = await readFile6(join10(this.projectRoot, "components.json"), "utf-8");
+        const parsed = JSON.parse(componentsJson);
+        const cssPath = parsed.tailwind?.css;
+        shadcn = cssPath ? { detected: true, cssPath } : { detected: true };
+      } catch {
+      }
+      let designDeps = [];
+      try {
+        const pkgContent = await readFile6(join10(this.projectRoot, "package.json"), "utf-8");
+        const pkg = JSON.parse(pkgContent);
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        const designPatterns = [
+          "@radix-ui",
+          "class-variance-authority",
+          "tailwind-merge",
+          "clsx",
+          "@headlessui",
+          "lucide-react",
+          "@heroicons"
+        ];
+        designDeps = Object.keys(allDeps).filter(
+          (dep) => designPatterns.some((p2) => dep.startsWith(p2))
+        );
+      } catch {
+      }
+      let existingTokenCount = 0;
+      const familyStatus = {};
+      if (this.adapter) {
+        const tokens = await this.adapter.load();
+        existingTokenCount = tokens.length;
+        for (const family of _RaftersToolHandler.SEMANTIC_FAMILIES) {
+          const token = tokens.find((t2) => t2.name === family);
+          if (!token) {
+            familyStatus[family] = { status: "unmapped" };
+          } else if (token.userOverride?.reason) {
+            familyStatus[family] = { status: "designer", reason: token.userOverride.reason };
+          } else {
+            familyStatus[family] = { status: "default" };
+          }
+        }
+      }
+      const detectedFamilies = [];
+      const allProps = cssFindings.flatMap((f) => f.customProperties);
+      const familyMap = /* @__PURE__ */ new Map();
+      for (const prop of allProps) {
+        const scaleMatch = prop.name.match(
+          /^--(color-)?(.+?)-(50|100|200|300|400|500|600|700|800|900|950)$/
+        );
+        if (scaleMatch?.[2] && scaleMatch[3]) {
+          const family = scaleMatch[2];
+          if (!familyMap.has(family)) familyMap.set(family, []);
+          familyMap.get(family)?.push({ position: scaleMatch[3], value: prop.value });
+        }
+      }
+      for (const [family, positions] of familyMap) {
+        if (positions.length >= 3) {
+          const base = positions.find((p2) => p2.position === "500") ?? positions.find((p2) => p2.position === "600") ?? positions[0];
+          if (base) {
+            detectedFamilies.push({
+              family,
+              positions: positions.map((p2) => p2.position),
+              baseValue: base.value,
+              source: `--color-${family}-*`
+            });
+          }
+        }
+      }
+      const designerCount = Object.values(familyStatus).filter(
+        (s) => s.status === "designer"
+      ).length;
+      const totalFamilies = _RaftersToolHandler.SEMANTIC_FAMILIES.length;
+      const result = {
+        framework,
+        cssFiles: cssFindings,
+        colorFamilies: detectedFamilies.length > 0 ? detectedFamilies : void 0,
+        familyStatus,
+        familyCoverage: `${designerCount}/${totalFamilies} semantic families have designer decisions`,
+        shadcn,
+        designDependencies: designDeps,
+        existingTokenCount,
+        guidance: detectedFamilies.length > 0 ? `Found ${detectedFamilies.length} color scale pattern(s): ${detectedFamilies.map((f) => f.family).join(", ")}. Map each family using its base color (position 500/600), not individual scale positions. buildColorValue() will regenerate the full 11-step scale.` : 'Review the custom properties above. Map each to a rafters token using rafters_onboard with action: "map". For ambiguous decisions, ask the designer.'
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (error48) {
+      return this.handleError("analyzeProject", error48);
+    }
+  }
+  /**
+   * Check onboarding completeness -- which families have designer decisions
+   */
+  async getOnboardStatus() {
+    if (!this.adapter || !this.projectRoot) {
+      return { content: [{ type: "text", text: NO_PROJECT_ERROR }], isError: true };
+    }
+    try {
+      const tokens = await this.adapter.load();
+      const mapped = [];
+      const defaultsRemaining = [];
+      const unmapped = [];
+      for (const family of _RaftersToolHandler.SEMANTIC_FAMILIES) {
+        const token = tokens.find((t2) => t2.name === family);
+        if (!token) {
+          unmapped.push(family);
+        } else if (token.userOverride?.reason) {
+          mapped.push(family);
+        } else {
+          defaultsRemaining.push(family);
+        }
+      }
+      const semanticSet = new Set(_RaftersToolHandler.SEMANTIC_FAMILIES);
+      const customFamilies = tokens.filter(
+        (t2) => t2.namespace === "color" && !semanticSet.has(t2.name) && t2.userOverride?.reason && !t2.name.includes("-")
+      ).map((t2) => t2.name);
+      const complete = defaultsRemaining.length === 0 && unmapped.length === 0;
+      const coverage = `${mapped.length}/${_RaftersToolHandler.SEMANTIC_FAMILIES.length}`;
+      let guidance;
+      if (complete) {
+        guidance = "All semantic families have designer decisions. Onboarding is complete.";
+      } else if (defaultsRemaining.length > 0) {
+        guidance = `${defaultsRemaining.length} families still use generated defaults: ${defaultsRemaining.join(", ")}. Ask the designer: do these defaults work, or should we choose specific colors? If the defaults are intentional, confirm them with a reason.`;
+      } else {
+        guidance = `${unmapped.length} families are unmapped: ${unmapped.join(", ")}. These need designer decisions.`;
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                complete,
+                coverage,
+                families: { mapped, defaultsRemaining, unmapped, customFamilies },
+                guidance
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (error48) {
+      return this.handleError("getOnboardStatus", error48);
+    }
+  }
+  /**
+   * Parse CSS content into structured findings
+   */
+  parseCssFindings(path2, content) {
+    const customProperties = [];
+    const themeBlocks = [];
+    const imports = [];
+    const importMatches = content.matchAll(/@import\s+['"]([^'"]+)['"]/g);
+    for (const match2 of importMatches) {
+      if (match2[1]) imports.push(match2[1]);
+    }
+    const themeMatches = content.matchAll(/@theme\s*\{([^}]+)\}/g);
+    for (const match2 of themeMatches) {
+      if (match2[0]) themeBlocks.push(match2[0].trim());
+      if (match2[1]) this.extractCustomProperties(match2[1], "@theme", customProperties);
+    }
+    const rootMatch = content.match(/:root\s*\{([^}]+)\}/);
+    if (rootMatch?.[1]) {
+      this.extractCustomProperties(rootMatch[1], ":root", customProperties);
+    }
+    const darkMatch = content.match(/\.dark\s*\{([^}]+)\}/);
+    if (darkMatch?.[1]) {
+      this.extractCustomProperties(darkMatch[1], ".dark", customProperties);
+    }
+    const prefersMatch = content.match(
+      /@media\s*\(prefers-color-scheme:\s*dark\)\s*\{[^{]*\{([^}]+)\}/
+    );
+    if (prefersMatch?.[1]) {
+      this.extractCustomProperties(prefersMatch[1], "prefers-color-scheme: dark", customProperties);
+    }
+    return { path: path2, customProperties, themeBlocks, imports };
+  }
+  /**
+   * Extract CSS custom properties from a block
+   */
+  extractCustomProperties(block, context2, out) {
+    const propMatches = block.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g);
+    for (const match2 of propMatches) {
+      if (match2[1] && match2[2]) {
+        out.push({ name: match2[1], value: match2[2].trim(), context: context2 });
+      }
+    }
+  }
+  /**
+   * Detect if a string value is a CSS color (not a size, calc, or var reference)
+   */
+  static isColorValue(value2) {
+    const v = value2.trim().toLowerCase();
+    if (/^\d/.test(v) || v.startsWith("var(") || v.startsWith("calc(")) return false;
+    if (/\d+(rem|px|em|%|vw|vh|dvh|svh|ch|ex)$/.test(v)) return false;
+    return v.startsWith("#") || v.startsWith("rgb") || v.startsWith("hsl") || v.startsWith("oklch") || v.startsWith("oklab") || v.startsWith("lch") || v.startsWith("lab") || v.startsWith("color(") || v.startsWith("hwb");
+  }
+  /**
+   * Parse any CSS color to OKLCH. hexToOKLCH uses colorjs.io internally
+   * which accepts all CSS color formats, not just hex.
+   */
+  static parseToOKLCH(value2) {
+    try {
+      return hexToOKLCH(value2.trim());
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Fire api.rafters.studio enrichment for a color (non-blocking)
+   */
+  static fireEnrichment(oklch2) {
+    const l = oklch2.l.toFixed(3);
+    const c4 = oklch2.c.toFixed(3);
+    const h = Math.round(oklch2.h);
+    return fetch(`https://api.rafters.studio/color/${l}-${c4}-${h}?sync=true`).then((r) => r.ok ? r.json() : null).catch(() => null);
+  }
+  /**
+   * Build enriched ColorValue: local math + API intelligence
+   */
+  static async buildEnrichedColor(oklch2, tokenName) {
+    const enrichmentPromise = _RaftersToolHandler.fireEnrichment(oklch2);
+    const colorValue = buildColorValue(oklch2, { token: tokenName });
+    const enrichment = await enrichmentPromise;
+    if (enrichment && typeof enrichment === "object" && "color" in enrichment) {
+      const apiColor = enrichment.color;
+      if (apiColor?.intelligence) {
+        colorValue.intelligence = apiColor.intelligence;
+      }
+    }
+    return colorValue;
+  }
+  /**
+   * Execute a mapping plan -- enriches colors, writes tokens
+   */
+  async mapTokens(mappings) {
+    if (!mappings || mappings.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: "mappings array is required for map action",
+              hint: "Run analyze first, then provide mappings with source, target, value, and reason"
+            })
+          }
+        ],
+        isError: true
+      };
+    }
+    if (!this.adapter || !this.projectRoot) {
+      return { content: [{ type: "text", text: NO_PROJECT_ERROR }], isError: true };
+    }
+    try {
+      const allTokens = await this.adapter.load();
+      const registry2 = new TokenRegistry(allTokens);
+      registry2.setAdapter(this.adapter);
+      const results = [];
+      for (const mapping of mappings) {
+        const { source, target, value: value2, reason, namespace, category } = mapping;
+        if (!source || !target || !value2 || !reason) {
+          results.push({
+            source: source ?? "?",
+            target: target ?? "?",
+            action: "skipped",
+            ok: false,
+            error: "Missing required fields: source, target, value, reason"
+          });
+          continue;
+        }
+        let tokenValue = value2;
+        let enriched = false;
+        if (_RaftersToolHandler.isColorValue(value2)) {
+          const oklch2 = _RaftersToolHandler.parseToOKLCH(value2);
+          if (oklch2) {
+            tokenValue = await _RaftersToolHandler.buildEnrichedColor(oklch2, target);
+            enriched = true;
+          }
+        }
+        const exists = registry2.has(target);
+        if (exists) {
+          const existing = registry2.get(target);
+          if (existing) {
+            const previousValue = existing.value;
+            existing.userOverride = {
+              previousValue: typeof previousValue === "string" ? previousValue : JSON.stringify(previousValue),
+              reason: `Onboarded from ${source}: ${reason}`
+            };
+            await registry2.set(target, tokenValue);
+            results.push({ source, target, action: "set", ok: true, enriched });
+          }
+        } else {
+          const ns = namespace ?? (enriched ? "color" : "custom");
+          const cat = category ?? ns;
+          const newToken = {
+            name: target,
+            namespace: ns,
+            category: cat,
+            value: tokenValue,
+            containerQueryAware: true,
+            userOverride: {
+              previousValue: "",
+              reason: `Onboarded from ${source}: ${reason}`
+            }
+          };
+          registry2.add(newToken);
+          results.push({ source, target, action: "create", ok: true, enriched });
+        }
+      }
+      await this.adapter.save(registry2.list());
+      await this.regenerateOutputs(registry2);
+      const setCount = results.filter((r) => r.action === "set" && r.ok).length;
+      const createCount = results.filter((r) => r.action === "create" && r.ok).length;
+      const enrichedCount = results.filter((r) => r.enriched).length;
+      const failCount = results.filter((r) => !r.ok).length;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                ok: true,
+                summary: {
+                  set: setCount,
+                  created: createCount,
+                  enriched: enrichedCount,
+                  failed: failCount
+                },
+                results
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (error48) {
+      return this.handleError("mapTokens", error48);
+    }
+  }
   // ==================== Tool 5: Cognitive Budget ====================
   /**
    * Evaluate composition-level cognitive load
@@ -60942,7 +61658,7 @@ import { existsSync as existsSync7 } from "fs";
 import { resolve as resolve6 } from "path";
 
 // ../studio/src/api/vite-plugin.ts
-import { writeFile as writeFile4 } from "fs/promises";
+import { writeFile as writeFile5 } from "fs/promises";
 import { join as join13 } from "path";
 var TokenResponseSchema = external_exports.object({
   ok: external_exports.literal(true),
@@ -61156,12 +61872,6 @@ async function handleBuildColor(req, res) {
   }
 }
 async function handlePostToken(req, res, name2, registry2) {
-  const existingToken = registry2.get(name2);
-  if (!existingToken) {
-    res.statusCode = 404;
-    res.end(JSON.stringify({ ok: false, error: `Token "${name2}" not found` }));
-    return;
-  }
   let body;
   try {
     body = await readJsonBody(req);
@@ -61171,6 +61881,53 @@ async function handlePostToken(req, res, name2, registry2) {
     res.end(JSON.stringify({ ok: false, error: message }));
     return;
   }
+  const existingToken = registry2.get(name2);
+  if (!existingToken) {
+    const createSchema = external_exports.object({
+      namespace: external_exports.string().min(1),
+      category: external_exports.string().min(1),
+      value: external_exports.union([external_exports.string(), ColorValueSchema, ColorReferenceSchema]),
+      userOverride: external_exports.object({
+        previousValue: external_exports.union([external_exports.string(), ColorValueSchema, ColorReferenceSchema]),
+        reason: external_exports.string().min(1, "Reason is required. Every token needs a why."),
+        context: external_exports.string().optional()
+      }),
+      description: external_exports.string().optional()
+    });
+    const createResult = createSchema.safeParse(body);
+    if (!createResult.success) {
+      res.statusCode = 400;
+      const issues = createResult.error.issues;
+      const message = issues[0] ? `${issues[0].path.join(".") || "body"}: ${issues[0].message}` : createResult.error.message;
+      res.end(JSON.stringify({ ok: false, error: message }));
+      return;
+    }
+    const newToken = {
+      name: name2,
+      namespace: createResult.data.namespace,
+      category: createResult.data.category,
+      value: createResult.data.value,
+      userOverride: createResult.data.userOverride,
+      containerQueryAware: true,
+      description: createResult.data.description
+    };
+    const tokenResult2 = TokenSchema.safeParse(newToken);
+    if (!tokenResult2.success) {
+      res.statusCode = 400;
+      res.end(JSON.stringify({ ok: false, error: tokenResult2.error.message }));
+      return;
+    }
+    try {
+      registry2.add(tokenResult2.data);
+      const response = TokenResponseSchema.parse({ ok: true, token: registry2.get(name2) });
+      res.statusCode = 201;
+      res.end(JSON.stringify(response));
+    } catch (error48) {
+      res.statusCode = 500;
+      res.end(JSON.stringify({ ok: false, error: String(error48) }));
+    }
+    return;
+  }
   const namespaceSchema = getNamespacePatchSchema(existingToken.namespace);
   const patchResult = namespaceSchema.safeParse(body);
   if (!patchResult.success) {
@@ -61300,7 +62057,7 @@ function studioApiPlugin() {
       }
       registry2.setChangeCallback(async () => {
         try {
-          await writeFile4(outputPath, registryToVars(registry2));
+          await writeFile5(outputPath, registryToVars(registry2));
           server.ws.send({ type: "custom", event: "rafters:css-updated" });
         } catch (error48) {
           console.log(`[rafters] CSS regeneration failed: ${error48}`);
@@ -61317,6 +62074,19 @@ function studioApiPlugin() {
         }
         const data = parsed.data;
         const shouldPersist = data.persist !== false;
+        const existingToken = registry2.get(data.name);
+        const isColorFamily = existingToken?.namespace === "color" && typeof data.value === "object" && data.value !== null && "scale" in data.value;
+        let enrichmentPromise = null;
+        if (isColorFamily) {
+          const colorValue = data.value;
+          const base = colorValue.scale?.[5];
+          if (base) {
+            const l = base.l.toFixed(3);
+            const c4 = base.c.toFixed(3);
+            const h = Math.round(base.h);
+            enrichmentPromise = fetch(`https://api.rafters.studio/color/${l}-${c4}-${h}?sync=true`).then((r) => r.ok ? r.json() : null).catch(() => null);
+          }
+        }
         try {
           if (shouldPersist) {
             await registry2.set(data.name, data.value);
@@ -61328,6 +62098,26 @@ function studioApiPlugin() {
             name: data.name,
             persisted: shouldPersist
           });
+          if (enrichmentPromise) {
+            const enrichment = await enrichmentPromise;
+            if (enrichment && typeof enrichment === "object" && "color" in enrichment) {
+              const apiColor = enrichment.color;
+              if (apiColor?.intelligence) {
+                const current = registry2.get(data.name);
+                if (current && typeof current.value === "object" && current.value !== null) {
+                  const enrichedValue = {
+                    ...current.value,
+                    intelligence: apiColor.intelligence
+                  };
+                  await registry2.set(data.name, enrichedValue);
+                  client.send("rafters:color-enriched", {
+                    name: data.name,
+                    intelligence: apiColor.intelligence
+                  });
+                }
+              }
+            }
+          }
         } catch (error48) {
           console.log(`[rafters] Token update failed for "${data.name}": ${error48}`);
           client.send("rafters:token-updated", { ok: false, error: String(error48) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rafters",
-  "version": "0.0.26",
+  "version": "0.0.29",
   "description": "CLI for Rafters design system - scaffold tokens and add components",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,7 @@
   },
   "devDependencies": {
     "@playwright/test": "catalog:",
+    "@rafters/color-utils": "workspace:*",
     "@rafters/design-tokens": "workspace:*",
     "@rafters/shared": "workspace:*",
     "@rafters/studio": "workspace:*",