rafters 0.0.26 → 0.0.28

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");
@@ -58684,26 +58641,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 +58660,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 +58727,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 +58767,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 +59678,16 @@ 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. 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"
+5. Call rafters_onboard map to execute the migration once the designer confirms.
+
 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 +60052,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 +60104,60 @@ var TOOL_DEFINITIONS = [
       },
       required: ["components"]
     }
+  },
+  {
+    name: "rafters_onboard",
+    description: 'Analyze an existing project for design decisions (CSS custom properties, @theme blocks, shadcn colors) and map them into Rafters tokens. Use "analyze" to surface raw findings. Use "map" to execute token writes from a mapping plan. The agent interprets the findings, asks the designer about ambiguous decisions, then maps with intent.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["analyze", "map"],
+          description: "analyze: scan project CSS and return structured findings. map: execute a mapping plan (array of source->target->reason)."
+        },
+        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: "Why this mapping makes sense (design intent)"
+              },
+              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 +60187,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 +60728,487 @@ 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"
+    ]
+  };
+  /**
+   * Handle rafters_onboard tool calls
+   */
+  async onboard(args) {
+    const action = args.action;
+    switch (action) {
+      case "analyze":
+        return this.analyzeProject();
+      case "map":
+        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;
+      if (this.adapter) {
+        const tokens = await this.adapter.load();
+        existingTokenCount = tokens.length;
+      }
+      const result = {
+        framework,
+        cssFiles: cssFindings,
+        shadcn,
+        designDependencies: designDeps,
+        existingTokenCount,
+        guidance: '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);
+    }
+  }
+  /**
+   * 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());
+    }
+    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 });
+      }
+    }
+  }
+  /**
+   * Execute a mapping plan -- calls writeToken for each mapping
+   */
+  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;
+        }
+        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, value2);
+            results.push({ source, target, action: "set", ok: true });
+          }
+        } else {
+          const ns = namespace ?? "color";
+          const cat = category ?? ns;
+          const newToken = {
+            name: target,
+            namespace: ns,
+            category: cat,
+            value: value2,
+            containerQueryAware: true,
+            userOverride: {
+              previousValue: "",
+              reason: `Onboarded from ${source}: ${reason}`
+            }
+          };
+          registry2.add(newToken);
+          results.push({ source, target, action: "create", ok: true });
+        }
+      }
+      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 failCount = results.filter((r) => !r.ok).length;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                ok: true,
+                summary: { set: setCount, created: createCount, failed: failCount },
+                results
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (error48) {
+      return this.handleError("mapTokens", error48);
+    }
+  }
   // ==================== Tool 5: Cognitive Budget ====================
   /**
    * Evaluate composition-level cognitive load
@@ -60942,7 +61434,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 +61648,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 +61657,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 +61833,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 +61850,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 +61874,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.28",
   "description": "CLI for Rafters design system - scaffold tokens and add components",
   "license": "MIT",
   "type": "module",