@atomixstudio/mcp 1.0.33 → 1.0.34

package/dist/index.js

@@ -17,8 +17,6 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // ../atomix-sync-core/dist/index.js
-import * as fs from "fs";
-import * as path from "path";
 import * as path3 from "path";
 function generateETag(meta) {
   const hash = `${meta.version}-${meta.updatedAt}`;
@@ -337,74 +335,6 @@ function diffTokens(oldContent, newCssVars, format, newDarkVars) {
   }
   return { added, modified, removed, addedDark, modifiedDark, removedDark };
 }
-async function syncRulesFiles(options) {
-  const { dsId: dsId2, apiKey: apiKey2, apiBase: apiBase2 = "https://atomixstudio.eu", rulesDir = process.cwd() } = options;
-  const rulesDirResolved = path.resolve(process.cwd(), rulesDir);
-  const toolsToSync = [
-    { tool: "cursor", filename: ".cursorrules" },
-    { tool: "windsurf", filename: ".windsurfrules" },
-    { tool: "cline", filename: ".clinerules" },
-    { tool: "continue", filename: ".continuerules" },
-    { tool: "copilot", filename: "copilot-instructions.md", dir: ".github" },
-    { tool: "generic", filename: "AI_GUIDELINES.md" }
-  ];
-  const existingTools = toolsToSync.filter((t) => {
-    const filePath = t.dir ? path.join(rulesDirResolved, t.dir, t.filename) : path.join(rulesDirResolved, t.filename);
-    return fs.existsSync(filePath);
-  });
-  const toolsToWrite = existingTools.length > 0 ? existingTools : [{ tool: "cursor", filename: ".cursorrules" }];
-  const results = [];
-  for (const { tool, filename, dir } of toolsToWrite) {
-    try {
-      const rulesUrl = `${apiBase2}/api/ds/${dsId2}/rules?format=${tool}`;
-      const headers = { "Content-Type": "application/json" };
-      if (apiKey2) headers["x-api-key"] = apiKey2;
-      const response = await fetch(rulesUrl, { headers });
-      if (!response.ok) {
-        results.push({
-          tool,
-          filename,
-          path: dir ? `${dir}/${filename}` : filename,
-          success: false,
-          error: `Failed to fetch ${tool} rules: ${response.status}`
-        });
-        continue;
-      }
-      const rulesData = await response.json();
-      if (!rulesData.content) {
-        results.push({
-          tool,
-          filename,
-          path: dir ? `${dir}/${filename}` : filename,
-          success: false,
-          error: `No content for ${tool} rules`
-        });
-        continue;
-      }
-      const targetDir = dir ? path.join(rulesDirResolved, dir) : rulesDirResolved;
-      if (!fs.existsSync(targetDir)) {
-        fs.mkdirSync(targetDir, { recursive: true });
-      }
-      const filePath = path.join(targetDir, filename);
-      fs.writeFileSync(filePath, rulesData.content);
-      results.push({
-        tool,
-        filename,
-        path: dir ? `${dir}/${filename}` : filename,
-        success: true
-      });
-    } catch (error) {
-      results.push({
-        tool,
-        filename,
-        path: dir ? `${dir}/${filename}` : filename,
-        success: false,
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  return results;
-}
 function generateCSSOutput(cssVariables, darkModeColors, deprecatedTokens = /* @__PURE__ */ new Map()) {
   const lines = [
     "/* Atomix Design System Tokens",
@@ -1992,8 +1922,8 @@ function buildFigmaPayloadsFromDS(data) {
 }
 
 // src/index.ts
-import * as path2 from "path";
-import * as fs2 from "fs";
+import * as path from "path";
+import * as fs from "fs";
 import { execSync } from "child_process";
 import { platform } from "os";
 import WebSocket, { WebSocketServer } from "ws";
@@ -2152,13 +2082,13 @@ function sendBridgeRequest(method, params, timeoutMs = FIGMA_BRIDGE_TIMEOUT_MS)
     );
   }
   const id = `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve3, reject) => {
     const timeout = setTimeout(() => {
       if (pendingBridgeRequests.delete(id)) {
         reject(new Error("Figma bridge timeout. " + FIGMA_CONNECTION_INSTRUCTIONS.startBridge + " Then " + FIGMA_CONNECTION_INSTRUCTIONS.connect));
       }
     }, timeoutMs);
-    pendingBridgeRequests.set(id, { resolve: resolve4, reject, timeout });
+    pendingBridgeRequests.set(id, { resolve: resolve3, reject, timeout });
     try {
       ws.send(JSON.stringify({ id, method: normalized, params }));
     } catch (e) {
@@ -2194,10 +2124,25 @@ function parseArgs() {
 var cliArgs = parseArgs();
 var { dsId, apiKey, accessToken } = cliArgs;
 var apiBase = cliArgs.apiBase || "https://atomix.studio";
+var MCP_VERSION = "1.0.33";
 var cachedData = null;
 var cachedETag = null;
 var cachedMcpTier = null;
 var authFailedNoTools = false;
+var mcpUpdateNotice = null;
+var mcpLatestVersion = null;
+function isVersionNewer(latest, current) {
+  const toParts = (v) => v.split(".").map((n) => parseInt(n, 10) || 0);
+  const a = toParts(latest);
+  const b = toParts(current);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
 function hasValidAuthConfig() {
   return !!(dsId && accessToken);
 }
@@ -2218,10 +2163,10 @@ ${changes.summary}`);
   }
 }
 function validateTokenFileAfterWrite(outputPath, format, expectedMinVariables) {
-  if (!fs2.existsSync(outputPath)) {
+  if (!fs.existsSync(outputPath)) {
     return { path: outputPath, status: "FAIL", detail: "File not found after write." };
   }
-  const content = fs2.readFileSync(outputPath, "utf-8");
+  const content = fs.readFileSync(outputPath, "utf-8");
   if (!content || content.trim().length === 0) {
     return { path: outputPath, status: "FAIL", detail: "File is empty after write." };
   }
@@ -2243,7 +2188,7 @@ function validateTokenFileAfterWrite(outputPath, format, expectedMinVariables) {
 }
 function formatValidationBlock(entries) {
   if (entries.length === 0) return "";
-  const displayPath = (p) => p.startsWith("(") ? p : path2.relative(process.cwd(), p);
+  const displayPath = (p) => p.startsWith("(") ? p : path.relative(process.cwd(), p);
   const lines = [
     "",
     "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
@@ -2273,6 +2218,14 @@ async function fetchDesignSystemForMCP(forceRefresh = false) {
   cachedData = result.data;
   cachedETag = result.etag;
   cachedMcpTier = result.data.meta.mcpTier ?? null;
+  const latest = result.data.meta.mcpLatestVersion;
+  if (latest && isVersionNewer(latest, MCP_VERSION)) {
+    mcpLatestVersion = latest;
+    mcpUpdateNotice = `**MCP update available:** A new Atomix MCP server (v${latest}) is available. You're on v${MCP_VERSION}. To use the new version in Cursor: 1) Quit Cursor completely and reopen, 2) Clear npx cache: \`rm -rf ~/.npm/_npx\` (macOS/Linux), 3) Ensure your MCP config uses \`@atomixstudio/mcp@latest\` or \`@atomixstudio/mcp@${latest}\`. To test a local build before publishing: point MCP to \`node /path/to/Atom/packages/mcp-user/dist/index.js\` with \`--ds-id\` and \`--atomix-token\`.`;
+  } else {
+    mcpUpdateNotice = null;
+    mcpLatestVersion = null;
+  }
   await updateChangeSummary(result.data);
   return result.data;
 }
@@ -2323,7 +2276,7 @@ function buildTypesetsList(typography, cssPrefix = "atmx") {
 var server = new Server(
   {
     name: "atomix-mcp-user",
-    version: "1.0.30"
+    version: MCP_VERSION
   },
   {
     capabilities: {
@@ -2441,18 +2394,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       }
     },
     {
-      name: "getAIToolRules",
-      description: "Generate design system rules for AI coding tools (Cursor, Copilot, Windsurf, etc.).",
+      name: "getRules",
+      description: "Get design system governance rules. Optionally filter by topic (colors, typo, motion, icons, layout, visual). Call at session start or before writing visual code.",
       inputSchema: {
         type: "object",
         properties: {
-          tool: {
+          topic: {
             type: "string",
-            enum: ["cursor", "copilot", "windsurf", "cline", "continue", "zed", "generic", "all"],
-            description: "AI tool to generate rules for. Use 'all' to get rules for all tools."
+            enum: ["colors", "typo", "typography", "motion", "icons", "layout", "visual", "style"],
+            description: "Optional. Filter rules by topic: colors, typo/typography, motion, icons, layout, or visual/style (color, border, radius, shadows, icons). Omit for all rules."
           }
-        },
-        required: ["tool"]
+        }
       }
     },
     {
@@ -2487,10 +2439,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "syncAll",
-      description: "Sync tokens, AI rules, skills (.cursor/skills/atomix-ds/SKILL.md), and atomix-dependencies.json. Use dryRun: true first to report what would change without writing; then dryRun: false to apply. Response includes a VALIDATION section\u2014agent must check it to confirm success. Optional: output (default ./tokens.css), format (default css), skipTokens (if true, only skills and manifest), dryRun (if true, report only; no files written).",
+      description: "Sync tokens, AI rules, skills (.cursor/skills/atomix-ds/SKILL.md), and atomix-dependencies.json. All paths are resolved under workspaceRoot so files are written inside the project repo (committable). Use dryRun: true first to report what would change without writing; then dryRun: false to apply. Optional: workspaceRoot (project root; default: ATOMIX_PROJECT_ROOT env or process.cwd()), output (default ./tokens.css), format (default css), skipTokens, dryRun.",
       inputSchema: {
         type: "object",
         properties: {
+          workspaceRoot: {
+            type: "string",
+            description: "Absolute path to the project/repo root. Skills and manifest are written under this path so they can be committed. If omitted, uses ATOMIX_PROJECT_ROOT env var, then process.cwd()."
+          },
           output: {
             type: "string",
             description: "Token file path (e.g. ./tokens.css). Default: ./tokens.css. Ignored if skipTokens is true."
@@ -2531,6 +2487,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         required: []
       }
     },
+    {
+      name: "getMcpVersion",
+      description: "Return the current Atomix MCP server version (e.g. 1.0.33) and, if known, the latest available from the API. Call this whenever the user asks about MCP version, Atomix MCP version, what version of the MCP server they are using, or whether an update is available. Prefer this over explaining the MCP protocol spec version.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    },
     {
       name: "syncToFigma",
       description: "Push the owner's design system to Figma: creates color variable collection (Light/Dark), color and paint styles, number variables (spacing, radius, borders, sizing, breakpoints), text styles, and shadow effect styles. Uses local WebSocket bridge and Atomix Figma plugin (no Figma REST API). No arguments. If the bridge is not running, the response includes agentInstruction to start it; only if that fails should the user start the bridge and connect the plugin. Call this when the user asks to 'sync to Figma' or 'push DS to Figma'.",
@@ -2554,18 +2519,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       isError: true
     };
   }
+  if (name === "getMcpVersion") {
+    const out = {
+      version: MCP_VERSION,
+      name: "atomix-mcp-user"
+    };
+    if (mcpLatestVersion) {
+      out.latestVersion = mcpLatestVersion;
+      out.updateAvailable = true;
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(out, null, 2) }]
+    };
+  }
   try {
     const shouldForceRefresh = name === "syncAll";
     const data = await fetchDesignSystemForMCP(shouldForceRefresh);
-    async function performTokenSyncAndRules(designSystemData, tokenOutput, tokenFormat, dryRun) {
+    async function performTokenSyncAndRules(designSystemData, tokenOutput, tokenFormat, dryRun, projectRoot) {
       const output = tokenOutput;
       const format = tokenFormat;
-      const outputPath = path2.resolve(process.cwd(), output);
-      const fileExists = fs2.existsSync(outputPath);
+      const outputPath = path.resolve(projectRoot, output);
+      const fileExists = fs.existsSync(outputPath);
       const deprecatedTokens = /* @__PURE__ */ new Map();
       const existingTokens = /* @__PURE__ */ new Map();
       if (fileExists && ["css", "scss", "less"].includes(format)) {
-        const oldContent = fs2.readFileSync(outputPath, "utf-8");
+        const oldContent = fs.readFileSync(outputPath, "utf-8");
         const oldVarPattern = /(?:^|\n)\s*(?:\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*)?(--[a-zA-Z0-9-]+):\s*([^;]+);/gm;
         let match;
         while ((match = oldVarPattern.exec(oldContent)) !== null) {
@@ -2615,7 +2593,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       let changes = [];
       let diff;
       if (fileExists && ["css", "scss", "less"].includes(format)) {
-        const oldContent = fs2.readFileSync(outputPath, "utf-8");
+        const oldContent = fs.readFileSync(outputPath, "utf-8");
         diff = diffTokens(oldContent, mergedCssVariables, format, darkModeColors?.dark);
         const lightChanges = diff.added.length + diff.modified.length;
         const darkChanges = diff.addedDark.length + diff.modifiedDark.length;
@@ -2670,7 +2648,7 @@ Version: ${designSystemData.meta.version}`,
           `  Tokens: ${tokenCount} (${deprecatedCount} deprecated preserved)`,
           changeLine,
           "",
-          "Rules: .cursorrules (or existing rules files in project)",
+          "Would write skills: .cursor/skills/atomix-ds/SKILL.md",
           "",
           "Call syncAll again with dryRun: false to apply."
         ].filter(Boolean).join("\n");
@@ -2680,30 +2658,12 @@ Version: ${designSystemData.meta.version}`,
           validation: [{ path: "(dry run)", status: "OK", detail: "No files written." }]
         };
       }
-      const outputDir = path2.dirname(outputPath);
-      if (!fs2.existsSync(outputDir)) fs2.mkdirSync(outputDir, { recursive: true });
-      fs2.writeFileSync(outputPath, newContent);
+      const outputDir = path.dirname(outputPath);
+      if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+      fs.writeFileSync(outputPath, newContent);
       const validation = [];
       validation.push(validateTokenFileAfterWrite(outputPath, format, tokenCount));
-      let rulesResults = [];
-      try {
-        rulesResults = await syncRulesFiles({
-          dsId,
-          apiKey: apiKey ?? void 0,
-          apiBase: apiBase ?? void 0,
-          rulesDir: process.cwd()
-        });
-        for (const r of rulesResults) {
-          const fullPath = path2.resolve(process.cwd(), r.path);
-          validation.push({
-            path: fullPath,
-            status: r.success && fs2.existsSync(fullPath) ? "OK" : "FAIL",
-            detail: r.success ? "Written." : r.error || "Write failed."
-          });
-        }
-      } catch (error) {
-        console.error(`[syncAll] Failed to sync rules: ${error}`);
-      }
+      const rulesResults = [];
       const governanceChanges = cachedData ? detectGovernanceChangesByFoundation(cachedData, designSystemData) : [];
       const response = formatSyncResponse({
         data: designSystemData,
@@ -2725,27 +2685,27 @@ Version: ${designSystemData.meta.version}`,
     }
     switch (name) {
       case "getToken": {
-        const path4 = args?.path;
-        const value = getTokenByPath(data.tokens, path4);
+        const path2 = args?.path;
+        const value = getTokenByPath(data.tokens, path2);
         if (value === void 0) {
           return {
             content: [{
               type: "text",
               text: JSON.stringify({
-                error: `Token not found: ${path4}`,
+                error: `Token not found: ${path2}`,
                 suggestion: "Use listTokens or searchTokens to find available tokens.",
                 availableCategories: TOKEN_CATEGORIES
               }, null, 2)
             }]
           };
         }
-        const cssVarKey = `--atmx-${path4.replace(/\./g, "-")}`;
+        const cssVarKey = `--atmx-${path2.replace(/\./g, "-")}`;
         const cssVar = data.cssVariables[cssVarKey];
         return {
           content: [{
             type: "text",
             text: JSON.stringify({
-              path: path4,
+              path: path2,
               value,
               cssVariable: cssVar || `var(${cssVarKey})`,
               usage: `style={{ property: "var(${cssVarKey})" }}`
@@ -2772,13 +2732,13 @@ Version: ${designSystemData.meta.version}`,
           };
         }
         const flat = flattenTokens(tokensToList);
-        const tokensWithCssVars = flat.map(({ path: path4, value }) => {
-          const fullPath = subcategory ? `${category}.${subcategory}.${path4}` : `${category}.${path4}`;
+        const tokensWithCssVars = flat.map(({ path: path2, value }) => {
+          const fullPath = subcategory ? `${category}.${subcategory}.${path2}` : `${category}.${path2}`;
           let cssVar;
           if (category === "colors" && subcategory === "static.brand") {
-            cssVar = data.cssVariables[`--atmx-color-brand-${path4}`];
+            cssVar = data.cssVariables[`--atmx-color-brand-${path2}`];
           } else if (category === "colors" && subcategory?.startsWith("modes.")) {
-            cssVar = data.cssVariables[`--atmx-color-${path4}`];
+            cssVar = data.cssVariables[`--atmx-color-${path2}`];
           } else {
             const cssVarKey = `--atmx-${fullPath.replace(/\./g, "-")}`;
             cssVar = data.cssVariables[cssVarKey];
@@ -2887,30 +2847,63 @@ Version: ${designSystemData.meta.version}`,
           }]
         };
       }
-      case "getAIToolRules": {
-        const tool = args?.tool;
-        const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=${tool === "all" ? "all" : tool}`;
-        console.error(`[getAIToolRules] Fetching: ${rulesUrl}`);
+      case "getRules": {
+        const topicRaw = args?.topic;
+        const topic = topicRaw?.toLowerCase().trim();
+        const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=json`;
+        console.error(`[getRules] Fetching: ${rulesUrl}${topic ? ` topic=${topic}` : ""}`);
         const headers = { "Content-Type": "application/json" };
         if (apiKey) headers["x-api-key"] = apiKey;
         try {
           const response = await fetch(rulesUrl, { headers });
-          console.error(`[getAIToolRules] Response status: ${response.status}`);
+          console.error(`[getRules] Response status: ${response.status}`);
           if (!response.ok) {
             const errorText = await response.text();
-            console.error(`[getAIToolRules] Error response: ${errorText}`);
+            console.error(`[getRules] Error response: ${errorText}`);
             throw new Error(`Failed to fetch rules: ${response.status} - ${errorText}`);
           }
-          const rules = await response.json();
-          console.error(`[getAIToolRules] Got ${rules.rules?.length || 0} rules`);
+          const payload = await response.json();
+          const categories = payload.categories ?? {};
+          const allRules = payload.rules ?? [];
+          if (!topic) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ rules: allRules, categories }, null, 2) }]
+            };
+          }
+          const topicToCategories = {
+            colors: ["general", "colors"],
+            typo: ["general", "typography"],
+            typography: ["general", "typography"],
+            motion: ["general", "motion"],
+            icons: ["general", "icons"],
+            layout: ["general", "spacing", "sizing", "layout"],
+            visual: ["general", "colors", "borders", "radius", "shadows", "icons"],
+            style: ["general", "colors", "borders", "radius", "shadows", "icons"]
+          };
+          const categoryKeys = topicToCategories[topic];
+          if (!categoryKeys) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ rules: allRules, categories }, null, 2) }]
+            };
+          }
+          const filteredCategories = {};
+          const filteredRules = [];
+          for (const key of categoryKeys) {
+            const list = categories[key];
+            if (list && list.length > 0) {
+              filteredCategories[key] = list;
+              filteredRules.push(...list);
+            }
+          }
+          console.error(`[getRules] Got ${filteredRules.length} rules for topic=${topic}`);
           return {
             content: [{
               type: "text",
-              text: JSON.stringify(rules, null, 2)
+              text: JSON.stringify({ rules: filteredRules, categories: filteredCategories }, null, 2)
             }]
           };
         } catch (fetchError) {
-          console.error(`[getAIToolRules] Fetch error:`, fetchError);
+          console.error(`[getRules] Fetch error:`, fetchError);
           throw fetchError;
         }
       }
@@ -2995,7 +2988,7 @@ Version: ${designSystemData.meta.version}`,
           copilot: `# Copilot Setup
 
 1. Create a Copilot instructions file in your project (e.g. \`.github/copilot-instructions.md\`)
-2. Use getAIToolRules({ tool: "copilot" }) to get the content
+2. Run /--sync to write the skill; call getRules() when you need governance rules
 3. Enable custom instructions in your editor (e.g. \`github.copilot.chat.codeGeneration.useInstructionFiles\`: true in settings)
 
 ## File Structure
@@ -3009,7 +3002,7 @@ Version: ${designSystemData.meta.version}`,
           windsurf: `# Windsurf Setup
 
 1. Create \`.windsurf/mcp.json\` in your project root
-2. Create \`.windsurfrules\` with rules from getAIToolRules
+2. Run /--sync to write the skill; call getRules() when you need governance rules
 3. Restart Windsurf Editor
 
 ## File Structure
@@ -3050,7 +3043,7 @@ Version: ${designSystemData.meta.version}`,
           zed: `# Zed Setup
 
 1. Create \`.zed/assistant/rules.md\` in your project
-2. Use getAIToolRules({ tool: "zed" }) for content
+2. Run /--sync to write the skill; call getRules() for governance rules
 
 ## File Structure
 
@@ -3078,9 +3071,8 @@ Version: ${designSystemData.meta.version}`,
 **Best Practice**: Keep \`tokens.css\` separate from your custom CSS. Use a separate file (e.g., \`custom.css\`) for custom styles.`,
           generic: `# Generic AI Tool Setup
 
-1. Create AI_GUIDELINES.md in your project root
-2. Use getAIToolRules({ tool: "generic" }) for content
-3. Reference in your prompts or context
+1. Run /--sync to write the skill (.cursor/skills/atomix-ds/SKILL.md)
+2. Call getRules() when you need governance rules; reference in your prompts or context
 
 ## File Structure
 
@@ -3115,16 +3107,16 @@ Version: ${designSystemData.meta.version}`,
         const dryRun = args?.dryRun === true;
         const output = args?.output || "./tokens.css";
         const format = args?.format || "css";
+        const projectRoot = path.resolve(
+          args?.workspaceRoot || process.env.ATOMIX_PROJECT_ROOT || process.cwd()
+        );
         const parts = [dryRun ? "[DRY RUN] syncAll report (no files written)." : "\u2713 syncAll complete."];
         let tokenResponseText = "";
         const allValidation = [];
         if (!skipTokens) {
-          const result = await performTokenSyncAndRules(data, output, format, dryRun);
+          const result = await performTokenSyncAndRules(data, output, format, dryRun, projectRoot);
           tokenResponseText = result.responseText;
           allValidation.push(...result.validation);
-          if (!dryRun && result.rulesResults.length > 0) {
-            parts.push(`Rules: ${result.rulesResults.map((r) => r.path).join(", ")}`);
-          }
           if (dryRun) {
             parts.push(`Would write tokens: ${output} (${format})`);
           } else {
@@ -3133,9 +3125,9 @@ Version: ${designSystemData.meta.version}`,
         }
         const dsVersion = String(data.meta.version ?? "1.0.0");
         const dsExportedAt = data.meta.exportedAt;
-        const skillsDir = path2.resolve(process.cwd(), ".cursor/skills/atomix-ds");
-        const skillPath1 = path2.join(skillsDir, "SKILL.md");
-        const manifestPath = path2.resolve(process.cwd(), "atomix-dependencies.json");
+        const skillsDir = path.resolve(projectRoot, ".cursor/skills/atomix-ds");
+        const skillPath1 = path.join(skillsDir, "SKILL.md");
+        const manifestPath = path.resolve(projectRoot, "atomix-dependencies.json");
         if (dryRun) {
           parts.push("Would write skills: .cursor/skills/atomix-ds/SKILL.md");
           parts.push("Would write manifest: atomix-dependencies.json");
@@ -3146,10 +3138,10 @@ Version: ${designSystemData.meta.version}`,
 ${reportText}` }]
           };
         }
-        if (!fs2.existsSync(skillsDir)) fs2.mkdirSync(skillsDir, { recursive: true });
+        if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
         const genericWithVersion = injectSkillVersion(GENERIC_SKILL_MD, dsVersion, dsExportedAt);
-        fs2.writeFileSync(skillPath1, genericWithVersion);
-        allValidation.push({ path: skillPath1, status: fs2.existsSync(skillPath1) ? "OK" : "FAIL", detail: "Written." });
+        fs.writeFileSync(skillPath1, genericWithVersion);
+        allValidation.push({ path: skillPath1, status: fs.existsSync(skillPath1) ? "OK" : "FAIL", detail: "Written." });
         parts.push("Skills: .cursor/skills/atomix-ds/SKILL.md (synced at DS v" + dsVersion + ")");
         const tokens = data.tokens;
         const typography = tokens?.typography;
@@ -3184,8 +3176,8 @@ ${reportText}` }]
             syncedAtVersion: data.meta.version ?? "1.0.0"
           }
         };
-        fs2.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
-        allValidation.push({ path: manifestPath, status: fs2.existsSync(manifestPath) ? "OK" : "FAIL", detail: "Written." });
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+        allValidation.push({ path: manifestPath, status: fs.existsSync(manifestPath) ? "OK" : "FAIL", detail: "Written." });
         parts.push("Manifest: atomix-dependencies.json (icons, fonts, skill paths)");
         const summary = parts.join("\n");
         const validationBlock = formatValidationBlock(allValidation);
@@ -3244,7 +3236,7 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
           showcase: platform2 === "web" || !platform2 ? {
             path: "atomix-setup-showcase.html",
             template: SHOWCASE_HTML_TEMPLATE,
-            substitutionInstructions: 'Replace placeholders with values from the synced token file. MCP/sync/export use the --atmx- prefix. {{TOKENS_CSS_PATH}} = path to the synced token file (e.g. ./tokens.css, same as syncAll output). {{TYPESETS_LINK}} = if a typeset CSS file was created (e.g. typesets.css), the full tag e.g. <link rel="stylesheet" href="typesets.css">, otherwise empty string. {{DS_NAME}} = design system name. {{BRAND_PRIMARY_VAR}} = var(--atmx-color-brand-primary). {{BRAND_PRIMARY_FOREGROUND_VAR}} = var(--atmx-color-brand-primary-foreground). {{HEADING_FONT_VAR}} = var(--atmx-typography-font-family-heading) or var(--atmx-typography-font-family-display). {{FONT_FAMILY_VAR}} = var(--atmx-typography-font-family-body). {{LARGEST_DISPLAY_TYPESET_CLASS}} = largest display typeset class from listTypesets (display role, largest font size; e.g. typeset-display-2xl or typeset-display-bold), or empty string if no typeset file. {{BODY_TYPESET_CLASS}} = typeset class for body text from listTypesets (e.g. typeset-body-md), or empty string if no typeset file. {{FONT_LINK_TAG}} = Google Fonts <link> for the font, or empty string. Do not invent CSS variable names; use only vars that exist in the export.'
+            substitutionInstructions: 'The synced token file (from syncAll) always uses the --atmx- prefix for every CSS variable. Keep all var(--atmx-*) references in the template; do not remove or change the prefix. Replace placeholders with values from the synced token file. {{TOKENS_CSS_PATH}} = path to the synced token file (e.g. ./tokens.css). {{TYPESETS_LINK}} = if a typeset CSS file was created, the full <link rel=\\"stylesheet\\" href=\\"typesets.css\\"> tag, otherwise empty string. {{DS_NAME}} = design system name. {{HEADING_FONT_VAR}} = var(--atmx-typography-font-family-heading) or var(--atmx-typography-font-family-display). {{FONT_FAMILY_VAR}} = var(--atmx-typography-font-family-body). {{LARGEST_DISPLAY_TYPESET_CLASS}} = largest display typeset class from listTypesets (display role, largest font size; e.g. typeset-display-2xl), or empty string if no typeset file. {{LARGEST_BODY_TYPESET_CLASS}} = largest body typeset class from listTypesets (body role, largest font size; e.g. typeset-body-lg), or empty string if no typeset file. {{BODY_TYPESET_CLASS}} = default body typeset class from listTypesets (e.g. typeset-body-md), or empty string. {{FONT_LINK_TAG}} = Google Fonts <link> for the font, or empty string. {{BRAND_PRIMARY_VAR}} = var(--atmx-color-brand-primary). Icon on circle uses luminance of brand primary (script sets white or black); no semantic foreground var. {{BUTTON_PADDING_VAR}} = var(--atmx-spacing-scale-md) or closest spacing token for button padding. {{BUTTON_HEIGHT_VAR}} = var(--atmx-sizing-height-md) or closest height token. {{BUTTON_RADIUS_VAR}} = var(--atmx-radius-scale-md) or var(--atmx-radius-scale-lg). {{CIRCLE_PADDING_VAR}} = var(--atmx-spacing-scale-md) or var(--atmx-spacing-scale-sm) for icon circle padding. {{ICON_SIZE_VAR}} = var(--atmx-sizing-icon-md) or var(--atmx-sizing-icon-lg). {{CHECK_ICON_SVG}} = inline SVG for Check icon from the design system icon library (getDependencies.iconLibrary.package: lucide-react, @heroicons/react, or phosphor-react). Use 24x24 viewBox; stroke=\\"currentColor\\" for Lucide/Heroicons, fill=\\"currentColor\\" for Phosphor so the script can set icon color by luminance. If unavailable, use: <svg xmlns=\\"http://www.w3.org/2000/svg\\" viewBox=\\"0 0 24 24\\" fill=\\"none\\" stroke=\\"currentColor\\" stroke-width=\\"2\\" stroke-linecap=\\"round\\" stroke-linejoin=\\"round\\"><path d=\\"M20 6L9 17l-5-5\\"/></svg>. Do not invent CSS variable names; use only vars that exist in the export.'
           } : void 0,
           meta: {
             dsName: data.meta.name,
@@ -3467,7 +3459,7 @@ ${JSON.stringify(out, null, 2)}` : JSON.stringify(out, null, 2);
             type: "text",
             text: JSON.stringify({
               error: `Unknown tool: ${name}`,
-              availableTools: ["getToken", "listTokens", "listTypesets", "searchTokens", "validateUsage", "getAIToolRules", "exportMCPConfig", "getSetupInstructions", "syncAll", "getDependencies", "syncToFigma"]
+              availableTools: ["getToken", "listTokens", "listTypesets", "searchTokens", "validateUsage", "getRules", "exportMCPConfig", "getSetupInstructions", "syncAll", "getDependencies", "getMcpVersion", "syncToFigma"]
             }, null, 2)
           }]
         };
@@ -3521,51 +3513,124 @@ atomixDsExportedAt: "${exportedAt ?? ""}"
 }
 var GENERIC_SKILL_MD = `---
 name: atomix-ds
-description: Use the Atomix design system for UI, tokens, and styles. Fetch rules and tokens via MCP tools; never hardcode design values.
+description: Use the project's design system tokens semantically when building or editing any UI. Covers everyday tasks \u2014 creating components, building pages, styling forms, theming, dark mode, responsive layouts, adding icons, choosing colors, setting type, adjusting spacing, and applying motion. Works with any platform or framework (web, React Native, iOS, Android, Flutter, etc.). Fetch token values and governance rules via MCP tools (getToken, listTokens, searchTokens, getRules, validateUsage). Tokens include colors, typography, spacing, sizing, radius, shadows, borders, motion, z-index, and icons. Never hardcode visual values \u2014 always resolve from the design system first.
 ---
 
 # Atomix Design System
 
-Use this skill when editing UI, design system files, or when the user asks to follow the project's design system. Your job is to **get the relevant data from the design system via MCP** and apply it\u2014not to guess or invent values.
-
-## Goal
+**Prerequisite:** Load rules first before anything else \u2014 call getRules() at the start of the session or before writing any visual code.
 
-Complete the user's task using the design system as the single source of truth. Every color, spacing, typography, radius, shadow, or sizing value must come from the MCP tools (tokens or governance rules). Do not hardcode hex codes, pixel values, or font names.
+This project uses a design system with semantic tokens. **Before writing any visual code**, fetch the relevant tokens and governance rules from the MCP tools below. The design system is the single source of truth \u2014 do not guess, invent, or hardcode visual values.
 
 ## When to use
 
-- Building or editing UI components, pages, or styles
-- Working in design system or token files (e.g. \`tokens.css\`, theme files)
-- User asks to "follow the design system", "use tokens", or "match the DS"
-- Validating or refactoring existing code, UI or visual design for token compliance
+Use this skill for everyday design and frontend tasks:
+
+**Building UI**
+- Creating a component (button, card, input, modal, nav, sidebar, table, list, badge, tooltip\u2026)
+- Laying out a page, screen, or view
+- Building a form, dialog, popover, or overlay
+- Adding a header, footer, hero section, or onboarding flow
+
+**Styling & theming**
+- Choosing colors for backgrounds, text, borders, icons, or interactive states
+- Setting typography \u2014 font family, size, weight, line height, letter spacing
+- Adjusting spacing, padding, margins, or gaps between elements
+- Applying border radius, shadows, or elevation to surfaces
+- Adding hover, focus, active, disabled, or loading states
+- Setting up dark mode, light mode, or theme switching
+- Configuring responsive or adaptive layouts
+
+**Working with assets**
+- Rendering icons (sizing and stroke width are defined by the design system)
+- Implementing designs from Figma, mockups, screenshots, or design specs
+- Translating a design handoff into code
+
+**Maintenance**
+- Refactoring hardcoded values to use tokens
+- Auditing code for design system compliance
+- Updating styles after a design system version change
+
+If the task has no visual output (pure logic, data, APIs, DevOps), this skill is not needed.
+
+## Semantic token usage
+
+Tokens have two layers \u2014 **primitives** (raw scales) and **semantic** (purpose-driven). Always prefer semantic tokens because they adapt to themes and modes automatically.
+
+| Intent | Use semantic token | Avoid raw primitive |
+|--------|-------------------|---------------------|
+| Page background | \`bg-page\` | \`neutral.50\` |
+| Card surface | \`bg-surface\` | \`white\` |
+| Primary text | \`text-primary\` | \`neutral.900\` |
+| Muted text | \`text-muted\` | \`neutral.500\` |
+| Default border | \`border-default\` | \`neutral.200\` |
+| Brand action | \`brand.primary\` | \`green.600\` |
+| Error state | \`status.error\` | \`red.500\` |
 
-## How to get design system data
+Call \`getRules\` for the full mapping of semantic tokens to primitives in each theme.
 
-**1. Governance rules (how to use tokens in code)**  
-Call **getAIToolRules** with the tool id for your current environment: \`cursor\`, \`windsurf\`, \`copilot\`, \`cline\`, \`continue\`, \`zed\`, or \`generic\`.  
-Example: \`getAIToolRules({ tool: "cursor" })\`.  
-Alternatively use the **/--rules** prompt or the resource \`atomix://rules/<tool>\`.
+When a semantic token doesn't exist for your use case, use the closest primitive from \`listTokens\` \u2014 but document why so the team can promote it to a semantic token later.
 
-**2. Token values (what to use in code)**  
-- **getToken(path)** \u2014 One token by path (e.g. \`colors.brand.primary\`, \`typography.fontSize.lg\`, \`sizing.icon.sm\`, \`icons.strokeWidth\`). Icon stroke width is at \`icons.strokeWidth\` when the design system defines it.
-- **listTokens(category)** \u2014 All tokens in a category: \`colors\`, \`typography\`, \`spacing\`, \`sizing\`, \`shadows\`, \`radius\`, \`borders\`, \`motion\`, \`zIndex\`. For icon config (e.g. stroke width), use \`getToken("icons.strokeWidth")\` since \`icons\` is not a list category.
-- **searchTokens(query)** \u2014 Find tokens by name or value.
+## How to fetch design system data
 
-**3. Validation**  
-- **validateUsage(value, context)** \u2014 Check if a CSS/value should use a token instead (e.g. \`validateUsage("#007061", "color")\`).
+### 1. Governance rules \u2014 always fetch first
 
-**4. Syncing tokens to a file**  
-- **syncAll({ output?, format?, skipTokens? })** \u2014 Syncs tokens to a file, AI rules, skills (.cursor/skills/atomix-ds/*), and atomix-dependencies.json. Default output \`./tokens.css\`, format \`css\`. Use \`skipTokens: true\` to only write skills and manifest.
+\`getRules()\` \u2014 optionally with a topic: \`colors\`, \`typo\`, \`motion\`, \`icons\`, \`layout\`, or \`visual\` (color, border, radius, shadows, icons). Returns how tokens should be applied \u2014 naming conventions, variable format, and semantic mappings.
 
-Use the returned rules and token paths/values when generating or editing code. Prefer CSS variables (e.g. \`var(--atmx-*)\`) or the exact token references from the tools.
+### 2. Token values \u2014 by task
+
+| I need\u2026 | MCP call |
+|---------|----------|
+| A specific token | \`getToken("colors.brand.primary")\` or \`getToken("spacing.scale.md")\` |
+| All tokens in a category | \`listTokens("colors")\` \u2014 categories: \`colors\`, \`typography\`, \`spacing\`, \`sizing\`, \`shadows\`, \`radius\`, \`borders\`, \`motion\`, \`zIndex\` |
+| Search by name or value | \`searchTokens("primary")\` or \`searchTokens("bold")\` |
+| Icon size or stroke | \`getToken("sizing.icon.sm")\` for dimensions, \`getToken("icons.strokeWidth")\` for stroke |
+| Typeset classes | \`listTypesets()\` \u2014 emit one class per typeset; include text-transform and text-decoration for 1:1 match |
+
+### 3. Validation
+
+\`validateUsage("#007061", "color")\` \u2014 checks if a raw value should be a token. Run this on any value you suspect is hardcoded.
+
+### 4. Syncing tokens to a file
+
+\`syncAll({ output?, format?, skipTokens? })\` \u2014 writes tokens to a file (default \`./tokens.css\`), skills (.cursor/skills/atomix-ds/SKILL.md), and manifest. Use \`skipTokens: true\` to only write skills and manifest.
+
+## Workflow
+
+1. **Fetch rules** \u2014 call \`getRules\` once per session (or with a topic when working on a specific area).
+2. **Fetch tokens** \u2014 call \`getToken\`, \`listTokens\`, or \`searchTokens\` for the values you need.
+3. **Apply semantically** \u2014 use token references or CSS variables (\`var(--atmx-*)\`) depending on your platform. Choose the semantic token that matches the *purpose*, not just the visual appearance.
+4. **Self-check** \u2014 scan your output for hardcoded hex codes, pixel values, rem/em literals, duration strings, or font names. If found, replace with the matching token.
+
+## Common mistakes
+
+Do not hardcode visual values. Always resolve from the design system:
+
+- A hex color (\`#007061\`, \`#333\`) \u2192 call \`getToken\` or \`searchTokens\` for the matching color token
+- A pixel/rem value (\`16px\`, \`1.5rem\`) \u2192 use the spacing, sizing, or radius token
+- A font name (\`"Inter"\`, \`"SF Pro"\`) \u2192 use the typography font-family token
+- A duration (\`200ms\`, \`0.3s\`) \u2192 use the motion duration token
+- A numeric weight (\`600\`, \`700\`) \u2192 use the typography font-weight token
+- A shadow string (\`0 4px 6px rgba(\u2026)\`) \u2192 use the shadow elevation token
+
+If no token matches, call \`searchTokens\` to find the closest option. Never invent a token path.
 
 ## Best practices
 
-- **Fetch first:** Before writing UI or styles, call getAIToolRules and/or getToken/listTokens so you know the exact tokens and conventions.
-- **Icons:** Apply the design system's icon tokens when rendering icons: sizing via \`getToken("sizing.icon.sm")\` or \`listTokens("sizing")\`, and stroke width via \`getToken("icons.strokeWidth")\` when the DS defines it; do not use hardcoded sizes or stroke widths.
-- **Typography:** Use typography tokens from the DS for any text. When creating global typeset CSS, call **listTypesets** and emit one CSS class per typeset (do not skip any); include text-transform and text-decoration when present for 1:1 match.
-- **No guessing:** If a value is not in the rules or token list, use searchTokens or listTokens to find the closest match rather than inventing a value.
-- **Version check:** If this skill file has frontmatter \`atomixDsVersion\`, compare it to the design system version from **getDependencies** (\`meta.designSystemVersion\`). If the design system is newer, suggest the user run **syncAll** to update skills and tokens.
+- **Fetch first:** Always call getRules and/or listTokens before writing any styles, regardless of platform or framework.
+- **Semantic over primitive:** Prefer tokens that describe purpose (\`text-primary\`, \`bg-surface\`) over tokens that describe appearance (\`neutral.900\`, \`white\`).
+- **Icons:** Size via \`getToken("sizing.icon.sm")\`; stroke width via \`getToken("icons.strokeWidth")\` when the DS defines it.
+- **Typography:** Use typography tokens for all text. For global typeset output, call **listTypesets** and emit every entry; include text-transform and text-decoration for 1:1 match.
+- **No guessing:** If a value is not in the rules or token list, call searchTokens or listTokens to find the closest match.
+- **Platform agnostic:** Token values work across CSS, Tailwind, React Native, SwiftUI, Compose, Flutter, and any style system. Use the output format appropriate to your platform.
+- **Version check:** If this file has frontmatter \`atomixDsVersion\`, compare to the version from **getDependencies** (\`meta.designSystemVersion\`). If the DS is newer, suggest running **syncAll** to update.
+
+## Strict mode and patterns
+
+- **Strict mode:** NO arbitrary values (e.g. \`bg-[#ff0000]\` forbidden). NO hardcoded colors \u2014 use CSS variables and semantic tokens only. NO hardcoded pixel values \u2014 use spacing/sizing tokens only. NO hardcoded typography \u2014 use typography typeset tokens only. Token vocabulary only \u2014 if a value is not in the design system, do not use it.
+- **CSS variables:** All tokens follow \`--atmx-{category}-{subcategory}-{token}\`. Correct: \`backgroundColor: "var(--atmx-color-bg-surface)"\`, \`borderRadius: "var(--atmx-radius-scale-md)"\`. Wrong: hex, raw px.
+- **Dark mode:** Colors switch in dark mode when using CSS variables; \`.dark\` on root toggles color variables.
+- **Button pattern:** Height and padding use sizing/spacing tokens; typography from typeset tokens; radius and border from tokens; transition from motion tokens; primary/secondary/ghost use action color tokens (e.g. \`--atmx-color-action-primary\`, \`--atmx-color-action-on-primary\`).
 `;
 var SHOWCASE_HTML_TEMPLATE = `<!DOCTYPE html>
 <html lang="en">
@@ -3581,52 +3646,153 @@ var SHOWCASE_HTML_TEMPLATE = `<!DOCTYPE html>
     body {
       margin: 0;
       font-family: {{FONT_FAMILY_VAR}}, system-ui, sans-serif;
-      background: {{BRAND_PRIMARY_VAR}};
-      color: {{BRAND_PRIMARY_FOREGROUND_VAR}};
+      background: var(--atmx-color-bg-page);
+      color: var(--atmx-color-text-primary);
       min-height: 100vh;
-      padding: 2rem;
+      padding: var(--atmx-spacing-scale-2xl);
       display: flex;
       justify-content: center;
       align-items: center;
     }
     .wrap { width: 375px; max-width: 100%; }
-    .icon { width: 2rem; height: 2rem; margin: 0 0 1rem; }
+    .top-row {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      margin-bottom: var(--atmx-spacing-scale-lg);
+    }
+    .top-row .mode-toggle { margin-bottom: 0; }
+    .icon-circle {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: calc({{ICON_SIZE_VAR}} + 2 * {{CIRCLE_PADDING_VAR}});
+      height: calc({{ICON_SIZE_VAR}} + 2 * {{CIRCLE_PADDING_VAR}});
+      padding: {{CIRCLE_PADDING_VAR}};
+      background: {{BRAND_PRIMARY_VAR}};
+      border-radius: 50%;
+    }
+    .icon-circle.light-icon { color: #fff; }
+    .icon-circle.dark-icon { color: #000; }
+    .icon-circle svg {
+      width: {{ICON_SIZE_VAR}};
+      height: {{ICON_SIZE_VAR}};
+      flex-shrink: 0;
+    }
+    .mode-toggle {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: {{BUTTON_PADDING_VAR}};
+      height: {{BUTTON_HEIGHT_VAR}};
+      border-radius: {{BUTTON_RADIUS_VAR}};
+      background: var(--atmx-color-bg-surface);
+      color: var(--atmx-color-text-primary);
+      border: 1px solid var(--atmx-color-border-default);
+      font-family: inherit;
+      font-size: inherit;
+      font-weight: inherit;
+      cursor: pointer;
+      margin-bottom: var(--atmx-spacing-scale-xl);
+    }
+    .mode-toggle:hover {
+      background: var(--atmx-color-bg-muted);
+    }
     h1 {
       font-family: {{HEADING_FONT_VAR}}, {{FONT_FAMILY_VAR}}, system-ui, sans-serif;
-      font-size: clamp(3rem, 4vw, 5rem);
-      font-weight: 700;
-      margin: 0 0 0.75rem;
+      margin: 0 0 var(--atmx-spacing-scale-md);
       line-height: 1.2;
     }
-    .lead { margin: 0 0 1.5rem; font-size: 1rem; line-height: 1.5; opacity: 0.95; }
-    .now { margin: 1.5rem 0 0; font-size: 0.875rem; line-height: 1.6; opacity: 0.95; text-align: left; }
-    .now strong { display: block; margin-bottom: 0.5rem; }
-    .now ul { margin: 0; padding-left: 1.25rem; }
-    .tips { margin-top: 1.5rem; font-size: 0.875rem; line-height: 1.6; opacity: 0.9; }
+    .lead {
+      margin: 0 0 var(--atmx-spacing-scale-xl);
+      opacity: 0.95;
+    }
+    .now { margin: var(--atmx-spacing-scale-xl) 0 0; opacity: 0.95; text-align: left; }
+    .now strong { display: block; margin-bottom: var(--atmx-spacing-scale-sm); }
+    .now ul { margin: 0; padding-left: var(--atmx-spacing-scale-xl); }
+    .tips { margin-top: var(--atmx-spacing-scale-xl); opacity: 0.9; }
     .tips a { color: inherit; text-decoration: underline; }
+    code {
+      font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+      font-size: 0.8125rem;
+      padding: 0.125rem 0.375rem;
+      border-radius: 0.25rem;
+      background: var(--atmx-color-bg-muted);
+    }
   </style>
 </head>
 <body class="{{BODY_TYPESET_CLASS}}">
   <div class="wrap">
-    <div class="icon" aria-hidden="true">
-      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="44" height="44"><path d="M20 6L9 17l-5-5"/></svg>
+    <div class="top-row">
+      <div class="icon-circle" aria-hidden="true">
+        {{CHECK_ICON_SVG}}
+      </div>
+      <button type="button" class="mode-toggle" id="mode-toggle" aria-label="Toggle light or dark mode">Dark</button>
     </div>
     <h1 class="{{LARGEST_DISPLAY_TYPESET_CLASS}}">You're all set with {{DS_NAME}}</h1>
-    <p class="lead">This page uses your design system: brand primary as background, headline and body typesets, and an icon.</p>
-    <div class="now">
+    <p class="lead {{LARGEST_BODY_TYPESET_CLASS}}">This page uses your design system: semantic colors (mode-aware), headline and body typesets, and an icon.</p>
+    <div class="now {{LARGEST_BODY_TYPESET_CLASS}}">
       <strong>What you can do now:</strong>
       <ul>
         <li>Ask your agent to build your designs using the design system tokens</li>
         <li>Build components and pages that use <code>var(--atmx-*)</code> for colors, spacing, and typography</li>
-        <li>Run <code>/--rules</code> to load governance rules; run <code>/--sync</code> and <code>/--refactor</code> after you change tokens in Atomix Studio</li>
+        <li>Run <code>/--rules</code> to load governance rules (or call getRules); run <code>/--sync</code> and <code>/--refactor</code> after you change tokens in Atomix Studio</li>
       </ul>
     </div>
-    <p class="tips">Keep the source of truth at <a href="https://atomix.studio" target="_blank" rel="noopener">atomix.studio</a> \u2014 avoid editing token values in this repo.</p>
+    <p class="tips {{LARGEST_BODY_TYPESET_CLASS}}">Keep the source of truth at <a href="https://atomix.studio" target="_blank" rel="noopener">atomix.studio</a> \u2014 avoid editing token values in this repo.</p>
   </div>
+  <script>
+    (function() {
+      var root = document.documentElement;
+      var btn = document.getElementById('mode-toggle');
+      var circle = document.querySelector('.icon-circle');
+      function hexToRgb(hex) {
+        var m = hex.slice(1).match(/.{2}/g);
+        return m ? m.map(function(x) { return parseInt(x, 16) / 255; }) : [0, 0, 0];
+      }
+      function relativeLuminance(r, g, b) {
+        var srgb = function(x) { return x <= 0.03928 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4); };
+        return 0.2126 * srgb(r) + 0.7152 * srgb(g) + 0.0722 * srgb(b);
+      }
+      function setIconContrast() {
+        if (!circle) return;
+        var bg = getComputedStyle(circle).backgroundColor;
+        var r = 0, g = 0, b = 0;
+        var rgbMatch = bg.match(/rgb\\(?\\s*(\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)\\s*\\)?/);
+        if (rgbMatch) {
+          r = parseInt(rgbMatch[1], 10) / 255;
+          g = parseInt(rgbMatch[2], 10) / 255;
+          b = parseInt(rgbMatch[3], 10) / 255;
+        } else if (bg.indexOf('#') === 0) {
+          var parts = hexToRgb(bg);
+          r = parts[0]; g = parts[1]; b = parts[2];
+        } else return;
+        var L = relativeLuminance(r, g, b);
+        circle.classList.remove('light-icon', 'dark-icon');
+        circle.classList.add(L > 0.179 ? 'dark-icon' : 'light-icon');
+      }
+      function updateLabel() {
+        var isDark = root.classList.contains('dark');
+        btn.textContent = isDark ? 'Light' : 'Dark';
+        btn.setAttribute('aria-label', isDark ? 'Switch to light mode' : 'Switch to dark mode');
+      }
+      btn.addEventListener('click', function() {
+        root.classList.toggle('dark');
+        root.setAttribute('data-theme', root.classList.contains('dark') ? 'dark' : 'light');
+        updateLabel();
+        setIconContrast();
+      });
+      if (root.classList.contains('dark') || root.getAttribute('data-theme') === 'dark') {
+        root.classList.add('dark');
+        root.setAttribute('data-theme', 'dark');
+      }
+      updateLabel();
+      setIconContrast();
+    })();
+  </script>
 </body>
 </html>
 `;
-var AI_TOOLS = ["cursor", "copilot", "windsurf", "cline", "continue", "zed", "generic"];
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
   if (!hasValidAuthConfig() || authFailedNoTools) {
     throw new Error(AUTH_REQUIRED_MESSAGE);
@@ -3681,26 +3847,44 @@ Get your DS ID and token from the Export modal or Settings \u2192 Regenerate Ato
       }]
     };
   }
-  const rulesMatch = uri.match(/^atomix:\/\/rules\/(.+)$/);
+  const rulesMatch = uri.match(/^atomix:\/\/rules(?:\/(.+))?$/);
   if (rulesMatch) {
-    const tool = rulesMatch[1];
-    if (!AI_TOOLS.includes(tool)) {
-      throw new Error(`Unknown tool: ${tool}. Available: ${AI_TOOLS.join(", ")}`);
-    }
-    const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=${tool}`;
+    const topicRaw = rulesMatch[1]?.toLowerCase().trim();
+    const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=json`;
     const headers = { "Content-Type": "application/json" };
     if (apiKey) headers["x-api-key"] = apiKey;
     const response = await fetch(rulesUrl, { headers });
-    if (!response.ok) {
-      throw new Error(`Failed to fetch rules: ${response.status}`);
+    if (!response.ok) throw new Error(`Failed to fetch rules: ${response.status}`);
+    const payload = await response.json();
+    const categories = payload.categories ?? {};
+    const allRules = payload.rules ?? [];
+    const topicToCategories = {
+      colors: ["general", "colors"],
+      typo: ["general", "typography"],
+      typography: ["general", "typography"],
+      motion: ["general", "motion"],
+      icons: ["general", "icons"],
+      layout: ["general", "spacing", "sizing", "layout"],
+      visual: ["general", "colors", "borders", "radius", "shadows", "icons"],
+      style: ["general", "colors", "borders", "radius", "shadows", "icons"]
+    };
+    if (!topicRaw || !topicToCategories[topicRaw]) {
+      return {
+        contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ rules: allRules, categories }, null, 2) }]
+      };
+    }
+    const categoryKeys = topicToCategories[topicRaw];
+    const filteredCategories = {};
+    const filteredRules = [];
+    for (const key of categoryKeys) {
+      const list = categories[key];
+      if (list?.length) {
+        filteredCategories[key] = list;
+        filteredRules.push(...list);
+      }
     }
-    const rulesData = await response.json();
     return {
-      contents: [{
-        uri,
-        mimeType: "text/markdown",
-        text: rulesData.content || JSON.stringify(rulesData, null, 2)
-      }]
+      contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ rules: filteredRules, categories: filteredCategories }, null, 2) }]
     };
   }
   throw new Error(`Unknown resource: ${uri}`);
@@ -3723,7 +3907,7 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
   const prompts = [
     { name: "--hello", description: "Get started with this design system - overview, tokens, and tools. Run this first!" },
     { name: "--get-started", description: "Get started with design system in project. Three phases: scan, report and ask, then create only after you approve." },
-    { name: "--rules", description: "Get the design system governance rules for your AI coding tool (default: cursor)." },
+    { name: "--rules", description: "Get design system governance rules (optionally by topic: colors, typo, motion, icons, layout, visual)." },
     { name: "--sync", description: "Sync tokens, AI rules, skills files, and dependencies manifest (icons, fonts). Use /--refactor to migrate deprecated tokens." },
     { name: "--refactor", description: "Migrate deprecated tokens in codebase. Run after /--sync." },
     { name: "--sync-to-figma", description: "Push this design system to Figma (variables, color + typography styles). Uses local bridge + plugin; no Figma token." }
@@ -3745,7 +3929,16 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     };
   }
   const canonicalName = name === "--hello" ? "hello" : name === "--get-started" ? "atomix-setup" : name === "--rules" ? "design-system-rules" : name === "--sync" ? "sync" : name === "--refactor" ? "refactor" : name === "--sync-to-figma" || name === "syncToFigma" ? "sync-to-figma" : name;
-  const shouldForceRefresh = canonicalName === "sync" || canonicalName === "refactor";
+  const shouldForceRefresh = [
+    "hello",
+    "atomix-setup",
+    // --get-started
+    "design-system-rules",
+    // --rules
+    "sync",
+    "refactor",
+    "sync-to-figma"
+  ].includes(canonicalName);
   let data = null;
   let stats = null;
   try {
@@ -3848,6 +4041,20 @@ Both are required. Configure the MCP server in your AI tool's MCP settings, then
     lines.push(instructions);
     return lines.join("\n");
   };
+  function withMcpNotice(res) {
+    if (!mcpUpdateNotice || res.messages.length === 0) return res;
+    const first = res.messages[0];
+    if (first?.content?.type === "text" && typeof first.content.text === "string") {
+      return {
+        ...res,
+        messages: [
+          { ...first, content: { ...first.content, text: first.content.text + "\n\n---\n\n" + mcpUpdateNotice } },
+          ...res.messages.slice(1)
+        ]
+      };
+    }
+    return res;
+  }
   switch (canonicalName) {
     case "hello": {
       const welcome = generateWelcomeMessage(data, stats);
@@ -3860,7 +4067,7 @@ Do not add any introduction or commentary before the ASCII art. The ASCII art mu
 
 ---
 ${welcome}`;
-      return {
+      return withMcpNotice({
         description: `Hello \u2014 ${data.meta.name} Design System`,
         messages: [
           {
@@ -3871,41 +4078,55 @@ ${welcome}`;
             }
           }
         ]
-      };
+      });
     }
     case "design-system-rules": {
-      const tool = args?.tool || "cursor";
-      const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=${tool}`;
+      const topic = args?.topic?.toLowerCase().trim();
+      const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=json`;
       const headers = { "Content-Type": "application/json" };
       if (apiKey) headers["x-api-key"] = apiKey;
       const response = await fetch(rulesUrl, { headers });
-      if (!response.ok) {
-        throw new Error(`Failed to fetch rules: ${response.status}`);
+      if (!response.ok) throw new Error(`Failed to fetch rules: ${response.status}`);
+      const payload = await response.json();
+      const categories = payload.categories ?? {};
+      const allRules = payload.rules ?? [];
+      const topicToCategories = {
+        colors: ["general", "colors"],
+        typo: ["general", "typography"],
+        typography: ["general", "typography"],
+        motion: ["general", "motion"],
+        icons: ["general", "icons"],
+        layout: ["general", "spacing", "sizing", "layout"],
+        visual: ["general", "colors", "borders", "radius", "shadows", "icons"],
+        style: ["general", "colors", "borders", "radius", "shadows", "icons"]
+      };
+      let rulesText;
+      if (topic && topicToCategories[topic]) {
+        const categoryKeys = topicToCategories[topic];
+        const filteredCategories = {};
+        const filteredRules = [];
+        for (const key of categoryKeys) {
+          const list = categories[key];
+          if (list?.length) {
+            filteredCategories[key] = list;
+            filteredRules.push(...list);
+          }
+        }
+        rulesText = JSON.stringify({ rules: filteredRules, categories: filteredCategories }, null, 2);
+      } else {
+        rulesText = JSON.stringify({ rules: allRules, categories }, null, 2);
       }
-      const rulesData = await response.json();
-      return {
-        description: `Design system rules for ${tool}`,
+      return withMcpNotice({
+        description: topic ? `Design system rules (topic: ${topic})` : "Design system rules",
         messages: [
-          {
-            role: "user",
-            content: {
-              type: "text",
-              text: `Show me the design system rules for ${tool}.`
-            }
-          },
-          {
-            role: "assistant",
-            content: {
-              type: "text",
-              text: rulesData.content || JSON.stringify(rulesData, null, 2)
-            }
-          }
+          { role: "user", content: { type: "text", text: topic ? `Show me the design system rules for topic: ${topic}.` : "Show me the design system rules." } },
+          { role: "assistant", content: { type: "text", text: rulesText } }
         ]
-      };
+      });
     }
     case "spacing": {
       const instructions = `List all spacing tokens in a table format. Use the listTokens tool with category "spacing" and subcategory "scale". Format the response as a markdown table with columns: Token Name | Value | CSS Variable. The Token Name should be in short format (e.g., "spacing.xs" instead of "spacing.scale.xs").`;
-      const response = {
+      return withMcpNotice({
         description: "List all spacing tokens",
         messages: [
           {
@@ -3916,12 +4137,11 @@ ${welcome}`;
             }
           }
         ]
-      };
-      return response;
+      });
     }
     case "radius": {
       const instructions = `List all border radius tokens in a table format. Use the listTokens tool with category "radius" and subcategory "scale". Format the response as a markdown table with columns: Token Name | Value | CSS Variable. The Token Name should be in short format (e.g., "radius.sm" instead of "radius.scale.sm").`;
-      return {
+      return withMcpNotice({
         description: "List all border radius tokens",
         messages: [
           {
@@ -3932,7 +4152,7 @@ ${welcome}`;
             }
           }
         ]
-      };
+      });
     }
     case "color": {
       const instructions = `List all color tokens in a table format showing both light and dark mode values. 
@@ -3949,7 +4169,7 @@ For semantic colors (from modes.light/modes.dark), match tokens by name and show
 The Token Name should be in short format:
 - Brand colors: "colors.brand.primary" (not "colors.static.brand.primary")
 - Semantic colors: "colors.bgSurface" (not "colors.modes.light.bgSurface")`;
-      return {
+      return withMcpNotice({
         description: "List all color tokens with light/dark mode",
         messages: [
           {
@@ -3960,11 +4180,11 @@ The Token Name should be in short format:
             }
           }
         ]
-      };
+      });
     }
     case "typography": {
       const instructions = `List all typography tokens in a table format. Use the listTokens tool with category "typography" (no subcategory needed). Format the response as a markdown table with columns: Token Name | Value | CSS Variable. Group tokens by type (fontSize, fontWeight, lineHeight, etc.) with section headers.`;
-      return {
+      return withMcpNotice({
         description: "List all typography tokens",
         messages: [
           {
@@ -3975,11 +4195,11 @@ The Token Name should be in short format:
             }
           }
         ]
-      };
+      });
     }
     case "shadow": {
       const instructions = `List all shadow/elevation tokens in a table format. Use the listTokens tool with category "shadows" and subcategory "elevation". Format the response as a markdown table with columns: Token Name | Value | CSS Variable. The Token Name should be in short format (e.g., "shadows.elevation.md" is fine as-is).`;
-      return {
+      return withMcpNotice({
         description: "List all shadow/elevation tokens",
         messages: [
           {
@@ -3990,11 +4210,11 @@ The Token Name should be in short format:
             }
           }
         ]
-      };
+      });
     }
     case "border": {
       const instructions = `List all border width tokens in a table format. Use the listTokens tool with category "borders" and subcategory "width". Format the response as a markdown table with columns: Token Name | Value | CSS Variable. The Token Name should be in short format (e.g., "borders.width.sm" is fine as-is).`;
-      return {
+      return withMcpNotice({
         description: "List all border width tokens",
         messages: [
           {
@@ -4005,7 +4225,7 @@ The Token Name should be in short format:
             }
           }
         ]
-      };
+      });
     }
     case "sizing": {
       const instructions = `List all sizing tokens in a table format. Call listTokens twice:
@@ -4013,7 +4233,7 @@ The Token Name should be in short format:
 2. category "sizing" and subcategory "icon" for icon sizes
 
 Format the response as a markdown table with columns: Token Name | Value | CSS Variable. Group by type (height vs icon) with section headers.`;
-      return {
+      return withMcpNotice({
         description: "List all sizing tokens",
         messages: [
           {
@@ -4024,7 +4244,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
             }
           }
         ]
-      };
+      });
     }
     case "motion": {
       const instructions = `List all motion tokens in a table format. Call listTokens twice:
@@ -4032,7 +4252,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
 2. category "motion" and subcategory "easing" for easing tokens
 
 Format the response as a markdown table with columns: Token Name | Value | CSS Variable. Group by type (duration vs easing) with section headers.`;
-      return {
+      return withMcpNotice({
         description: "List all motion tokens",
         messages: [
           {
@@ -4043,26 +4263,28 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
             }
           }
         ]
-      };
+      });
     }
     case "sync": {
       const output = args?.output || "./tokens.css";
       const format = args?.format || "css";
-      return {
+      const workspaceRoot = args?.workspaceRoot;
+      const rootHint = workspaceRoot ? ` Use workspaceRoot: "${workspaceRoot}" so files are written inside the repo.` : " If the project root is known, pass workspaceRoot with its absolute path so skills and manifest are written inside the repo (committable).";
+      return withMcpNotice({
         description: "Sync tokens, rules, skills, and dependencies manifest",
         messages: [
           {
             role: "user",
             content: {
               type: "text",
-              text: `Call the syncAll tool now. Use output="${output}" and format="${format}". This syncs tokens, AI rules, skills (.cursor/skills/atomix-ds/*), and atomix-dependencies.json. Execute immediately - do not search or ask questions.`
+              text: `Call the syncAll tool now. Use output="${output}" and format="${format}".${rootHint} This syncs tokens, AI rules, skills (.cursor/skills/atomix-ds/*), and atomix-dependencies.json. Execute immediately - do not search or ask questions.`
             }
           }
         ]
-      };
+      });
     }
     case "sync-to-figma": {
-      return {
+      return withMcpNotice({
         description: "Push design system to Figma via MCP tool",
         messages: [
           {
@@ -4073,34 +4295,34 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
             }
           }
         ]
-      };
+      });
     }
     case "refactor": {
       const refactorOutput = args?.output || "./tokens.css";
       const refactorFormat = args?.format || "css";
-      const refactorOutputPath = path2.resolve(process.cwd(), refactorOutput);
-      const refactorFileExists = fs2.existsSync(refactorOutputPath);
+      const refactorOutputPath = path.resolve(process.cwd(), refactorOutput);
+      const refactorFileExists = fs.existsSync(refactorOutputPath);
       if (!data) {
-        return {
+        return withMcpNotice({
           description: "Refactor codebase for deprecated tokens",
           messages: [{
             role: "user",
             content: { type: "text", text: `Failed to fetch design system from DB. Check your --ds-id and --atomix-token configuration.` }
           }]
-        };
+        });
       }
       if (!refactorFileExists) {
-        return {
+        return withMcpNotice({
           description: "Refactor codebase for deprecated tokens",
           messages: [{
             role: "user",
             content: { type: "text", text: `No token file found at \`${refactorOutput}\`. Please run \`/--sync\` first to create your token file, then run \`/--refactor\` to scan your codebase for deprecated token usage.` }
           }]
-        };
+        });
       }
       const deprecatedTokens = /* @__PURE__ */ new Map();
       if (["css", "scss", "less"].includes(refactorFormat)) {
-        const oldContent = fs2.readFileSync(refactorOutputPath, "utf-8");
+        const oldContent = fs.readFileSync(refactorOutputPath, "utf-8");
         const oldVarPattern = /(?:^|\n)\s*(?:\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*)?(--[a-zA-Z0-9-]+):\s*([^;]+);/gm;
         let match;
         while ((match = oldVarPattern.exec(oldContent)) !== null) {
@@ -4112,7 +4334,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
       const dsVersion = data.meta.version ?? "?";
       const dsExportedAt = data.meta.exportedAt ? new Date(data.meta.exportedAt).toLocaleString() : "N/A";
       if (deprecatedTokens.size === 0) {
-        return {
+        return withMcpNotice({
           description: "Refactor codebase for deprecated tokens",
           messages: [{
             role: "user",
@@ -4120,7 +4342,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
 
 Your token file \`${refactorOutput}\` is aligned with the design system (v${dsVersion}, exported ${dsExportedAt}). No tokens need migration.` }
           }]
-        };
+        });
       }
       const format = refactorFormat;
       const isNativeFormat = ["swift", "kotlin", "dart"].includes(format);
@@ -4235,18 +4457,18 @@ Use \`/color\`, \`/spacing\`, \`/radius\`, \`/typography\`, \`/shadow\`, \`/bord
 
 - Run only when the user has said yes (all or specific items).
 - For each approved item:
-  - **Skill:** Write the skill content from getDependencies \`skill.content\` to \`skill.path\` (.cursor/skills/atomix-ds/SKILL.md).
-  - **Token file:** Call **syncAll** with \`output\` set to the path (e.g. "./src/tokens.css" or "./tokens.css"). syncAll also writes skills and atomix-dependencies.json. You must call syncAll; do not only suggest the user run it later.
+  - **Skill:** Prefer calling **syncAll** (it writes the skill into the repo). If writing the skill manually, write getDependencies \`skill.content\` to \`skill.path\` (.cursor/skills/atomix-ds/SKILL.md) under the project root.
+  - **Token file and skills in repo:** Call **syncAll** with \`output\` set to the path (e.g. "./src/tokens.css" or "./tokens.css") and **workspaceRoot** set to the absolute path of the current project/workspace root. This ensures .cursor/skills/atomix-ds/SKILL.md and atomix-dependencies.json are written inside the repo so they can be committed. You must call syncAll; do not only suggest the user run it later.
   - **Icon package:** Install per getDependencies. When rendering icons, apply the design system's icon tokens: use getToken(\`sizing.icon.*\`) or listTokens(\`sizing\`) for size, and getToken(\`icons.strokeWidth\`) for stroke width when the DS defines it; do not use hardcoded sizes or stroke widths.
   - **Fonts and typeset:** Add font links (e.g. \`<link>\` or \`@import\` from Google Fonts). Then build a **complete typeset CSS**: call **listTypesets** to get every typeset from the owner's design system (do not skip any). Emit **one CSS rule per typeset** using the \`cssClass\` and the \`fontFamilyVar\`, \`fontSizeVar\`, \`fontWeightVar\`, \`lineHeightVar\` (and \`letterSpacingVar\`, \`textTransformVar\`, \`textDecorationVar\` when present) returned by listTypesets. Include text-transform and text-decoration when the typeset has them so the result is **1:1** with the design system. The typeset file must define the full type scale\u2014not only a font import. Do not create a CSS file that contains only a font import.
-  - **Showcase page (web only):** If platform is web and getDependencies returned a \`showcase\` object, create the file at \`showcase.path\` using \`showcase.template\`. Replace every placeholder per \`showcase.substitutionInstructions\`: TOKENS_CSS_PATH, TYPESETS_LINK (if you created a typeset CSS file, use the full \`<link rel="stylesheet" href="\u2026">\` tag; otherwise empty string), DS_NAME, BRAND_PRIMARY_VAR (page background), BRAND_PRIMARY_FOREGROUND_VAR (text on brand), HEADING_FONT_VAR (h1 fallback), FONT_FAMILY_VAR (body fallback), LARGEST_DISPLAY_TYPESET_CLASS (largest display typeset from listTypesets) and BODY_TYPESET_CLASS (e.g. typeset-body-md; leave empty if no typeset file), FONT_LINK_TAG. Use only CSS variable names that exist in the synced token file. Do not change the HTML structure. After creating the file, launch it in the default browser (e.g. \`open atomix-setup-showcase.html\` on macOS, \`xdg-open atomix-setup-showcase.html\` on Linux, or the equivalent on Windows).
+  - **Showcase page (web only):** If platform is web and getDependencies returned a \`showcase\` object, create the file at \`showcase.path\` using \`showcase.template\`. Replace every placeholder per \`showcase.substitutionInstructions\`: TOKENS_CSS_PATH, TYPESETS_LINK, DS_NAME, HEADING_FONT_VAR, FONT_FAMILY_VAR, LARGEST_DISPLAY_TYPESET_CLASS, LARGEST_BODY_TYPESET_CLASS, BODY_TYPESET_CLASS, FONT_LINK_TAG, BRAND_PRIMARY_VAR, BUTTON_PADDING_VAR, BUTTON_HEIGHT_VAR, BUTTON_RADIUS_VAR, CIRCLE_PADDING_VAR, ICON_SIZE_VAR, CHECK_ICON_SVG (inline SVG from the design system icon library). The page uses semantic colors (mode-aware) and a Dark/Light toggle. Use only CSS variable names that exist in the synced token file. Do not change the HTML structure. After creating the file, launch it in the default browser (e.g. \`open atomix-setup-showcase.html\` on macOS, \`xdg-open atomix-setup-showcase.html\` on Linux, or the equivalent on Windows).
 - Report only what you actually created or updated. Do not claim the token file was added if you did not call syncAll.
 - **After reporting \u2013 styles/theme:**
   - **Web:** If the project already has at least one CSS file: recommend how to integrate Atomix (e.g. import the synced tokens file, use \`var(--atmx-*)\`). Do not suggest a new global CSS. Only if there is **no** CSS file at all, ask once: "There are no CSS files yet. Do you want me to build a global typeset from the design system?" If yes, create a CSS file that includes: (1) font \`@import\` or document that a font link is needed, and (2) **typeset rules**\u2014call **listTypesets** and emit **one CSS class per typeset** (do not skip any). For each class set font-family, font-size, font-weight, line-height, letter-spacing; when the typeset has text-transform or text-decoration, set those too for a 1:1 match. Use the CSS variable names returned by listTypesets. The output must not be only a font import; it must define every typeset with every style detail from the design system.
   - **iOS/Android:** If the project already has theme/style files: recommend how to integrate Atomix tokens. Do not suggest a new global theme. Only if there is **no** theme/style at all, ask once: "There's no theme/style setup yet. Do you want a minimal token-based theme?" and add only if the user says yes.
 
 Create your todo list first, then Phase 1 (resolve platform/stack, call getDependencies, scan, build lists), then Phase 2 (report and ask). Do not perform Phase 3 until the user replies.`;
-      return {
+      return withMcpNotice({
         description: "Get started with design system in project (/--get-started). Create todo list; Phase 1 scan, Phase 2 report and ask, Phase 3 create only after user approval.",
         messages: [
           {
@@ -4257,7 +4479,7 @@ Create your todo list first, then Phase 1 (resolve platform/stack, call getDepen
             }
           }
         ]
-      };
+      });
     }
     default:
       throw new Error(`Unknown prompt: ${name}`);