@maz-ui/mcp 5.1.0-beta.0 → 5.1.0-beta.1

package/dist/shared/{mcp.DzqVbCaL.mjs → mcp.DseFuKdl.mjs}

@@ -1,18 +1,34 @@
 import { Buffer } from 'node:buffer';
 import { join, dirname, resolve, relative, isAbsolute } from 'node:path';
 import { parseArgs } from 'node:util';
-import { findInstalledPackage, AGENT_TARGETS, detectAgentTargets, setupAgents } from '@maz-ui/node';
+import { findProjectPackage, readPackageVersion, AGENT_TARGETS, detectAgentTargets, setupAgents } from '@maz-ui/node';
 import { getErrorMessage } from '@maz-ui/utils/helpers/getErrorMessage';
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import MiniSearch from 'minisearch';
 import { NodeTypes, parse } from '@vue/compiler-dom';
-import { glob } from 'tinyglobby';
+import { glob, globSync } from 'tinyglobby';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { execFileSync } from 'node:child_process';
+import { parse as parse$1 } from '@babel/parser';
 
-const version = "5.0.1-beta.0";
+function readOwnVersion(from = dirname(fileURLToPath(import.meta.url))) {
+  let directory = from;
+  for (; ; ) {
+    const file = join(directory, "package.json");
+    if (existsSync(file)) {
+      const { name, version } = JSON.parse(readFileSync(file, "utf8"));
+      if (name === "@maz-ui/mcp" && version)
+        return version;
+    }
+    const parent = dirname(directory);
+    if (parent === directory)
+      return "0.0.0";
+    directory = parent;
+  }
+}
 
 const SUPPORTED_SCHEMA_VERSION = 1;
 const docCategories = ["guide", "component", "composable", "directive", "plugin", "ecosystem", "util", "node", "reference"];
@@ -93,9 +109,16 @@ const manifestSchema = z.object({
 });
 
 class Knowledge {
-  constructor(manifest, source) {
+  /**
+   * @param manifest manifest of the docs bundle
+   * @param source where the bundle was found
+   * @param documentedVersion version of the documented maz-ui, read from a package.json at runtime when possible: the
+   * docs are generated before the release bumps the version, so `manifest.version` can be the previous one
+   */
+  constructor(manifest, source, documentedVersion = manifest.version) {
     this.manifest = manifest;
     this.source = source;
+    this.documentedVersion = documentedVersion;
     this.docsById = new Map(manifest.docs.map((doc) => [doc.id, doc]));
     this.componentsByName = new Map(manifest.components.map((component) => [component.name, component]));
     this.iconNames = new Set(manifest.icons.names);
@@ -105,7 +128,7 @@ class Knowledge {
   iconNames;
   cache = /* @__PURE__ */ new Map();
   get version() {
-    return this.manifest.version;
+    return this.documentedVersion;
   }
   get docs() {
     return this.manifest.docs;
@@ -139,21 +162,8 @@ function readManifest(directory) {
   return parsed.success ? parsed.data : void 0;
 }
 function findProjectMazUi(cwd) {
-  const bases = [cwd];
-  for (const folder of ["apps", "packages"]) {
-    const root = join(cwd, folder);
-    if (existsSync(root)) {
-      for (const entry of readdirSync(root, { withFileTypes: true })) {
-        if (entry.isDirectory())
-          bases.push(join(root, entry.name));
-      }
-    }
-  }
-  const directory = bases.map((base) => join(base, "node_modules", "maz-ui")).find((candidate) => existsSync(join(candidate, "package.json"))) ?? findInstalledPackage(cwd, "maz-ui");
-  if (!directory)
-    return void 0;
-  const { version } = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
-  return { directory, version };
+  const directory = findProjectPackage(cwd, "maz-ui");
+  return directory ? { directory, version: readPackageVersion(directory) ?? "0.0.0" } : void 0;
 }
 function loadKnowledge(options = {}) {
   const explicit = options.docsDir ?? process.env.MAZ_UI_DOCS_DIR;
@@ -161,20 +171,20 @@ function loadKnowledge(options = {}) {
     const manifest2 = readManifest(explicit);
     if (!manifest2)
       throw new Error(`No valid maz-ui docs bundle (manifest.json) in ${explicit}`);
-    return new Knowledge(manifest2, { kind: "custom", directory: explicit });
+    return new Knowledge(manifest2, { kind: "custom", directory: explicit }, readPackageVersion(dirname(explicit)) ?? manifest2.version);
   }
   const project = findProjectMazUi(options.cwd ?? process.cwd());
   if (project) {
     const directory = join(project.directory, "docs");
     const manifest2 = readManifest(directory);
     if (manifest2)
-      return new Knowledge(manifest2, { kind: "project", directory, projectVersion: project.version });
+      return new Knowledge(manifest2, { kind: "project", directory, projectVersion: project.version }, project.version);
   }
   const bundledDir = options.bundledDir ?? defaultBundledDir();
   const manifest = readManifest(bundledDir);
   if (!manifest)
     throw new Error(`The docs bundle of @maz-ui/mcp is missing or invalid (${bundledDir}). Reinstall the package.`);
-  return new Knowledge(manifest, { kind: "bundled", directory: bundledDir, projectVersion: project?.version });
+  return new Knowledge(manifest, { kind: "bundled", directory: bundledDir, projectVersion: project?.version }, options.bundledVersion ?? readOwnVersion());
 }
 
 const CATEGORY_PRIORITY = ["component", "composable", "directive", "plugin", "util", "guide", "ecosystem", "reference", "node"];
@@ -418,6 +428,7 @@ function analyze(text) {
 
 const FIELD_BOOSTS = {
   name: 8,
+  symbols: 3,
   aliases: 5,
   description: 2.5,
   headings: 1.5,
@@ -436,8 +447,19 @@ const CATEGORY_HINTS = {
   function: "util",
   guide: "guide"
 };
+const META_DOCS = /* @__PURE__ */ new Map([
+  ["guide/ai-agents", /\b(?:ai|agents?|llms?|claude|cursor|copilot|codex|mcp)\b/i],
+  ["ecosystem/mcp", /\b(?:ai|agents?|llms?|claude|cursor|copilot|codex|mcp)\b/i],
+  ["ecosystem/eslint-config", /\b(?:eslint|lint|linter|linting)\b/i],
+  ["ecosystem/stylelint-config", /\b(?:stylelint|lint|linter|linting)\b/i],
+  ["guide/migration-v5", /\b(?:migrat\w*|upgrad\w*|v4|v5|breaking)\b/i]
+]);
+const META_DOC_FACTOR = 0.3;
+const LOW_VALUE_TERMS = new Set(["add", "show", "display", "delete", "remove", "update", "set", "open", "close", "user", "users", "page", "item", "data", "value", "list", "text", "click", "between", "before", "after"].map((term) => processTerm(term) ?? term));
+const LOW_VALUE_FACTOR = 0.4;
+const LOW_VALUE_ONLY_FACTOR = 0.25;
 const EXACT_MATCH_BOOST = 4;
-const EXACT_ALIAS_BOOST = 2.5;
+const EXACT_ALIAS_BOOST = 4;
 const CATEGORY_HINT_BOOST = 1.4;
 function normalizedSynonyms() {
   const map = /* @__PURE__ */ new Map();
@@ -473,7 +495,8 @@ class DocSearch {
     ].join(" ") : "";
     return {
       id: doc.id,
-      name: [doc.title, ...doc.symbols, doc.slug].join(" "),
+      name: [doc.title, doc.slug].join(" "),
+      symbols: doc.symbols.join(" "),
       aliases: doc.aliases.join(" . "),
       description: doc.description,
       headings: doc.headings.join(" . "),
@@ -497,10 +520,11 @@ class DocSearch {
     const expansion = [...new Set(terms.flatMap((term) => this.synonyms.get(term) ?? []))].filter((term) => !terms.includes(term));
     const exact = this.exactMatch(query);
     const normalizedQuery = query.trim().toLowerCase();
+    const hasValuableTerm = terms.some((term) => !LOW_VALUE_TERMS.has(term));
     const results = this.index.search({
       combineWith: "OR",
       queries: [
-        { queries: [terms.join(" ")], combineWith: "OR" },
+        { queries: [terms.join(" ")], combineWith: "OR", boostTerm: (term) => LOW_VALUE_TERMS.has(term) ? LOW_VALUE_FACTOR : 1 },
         ...expansion.length > 0 ? [{ queries: [expansion.join(" ")], combineWith: "OR", boostTerm: () => 0.45 }] : []
       ]
     }, {
@@ -521,6 +545,11 @@ class DocSearch {
         score *= EXACT_ALIAS_BOOST;
       if (hintedCategory && doc.category === hintedCategory)
         score *= CATEGORY_HINT_BOOST;
+      if (hasValuableTerm && result.queryTerms.every((term) => LOW_VALUE_TERMS.has(term)))
+        score *= LOW_VALUE_ONLY_FACTOR;
+      const metaTopic = META_DOCS.get(doc.id);
+      if (metaTopic && !metaTopic.test(query))
+        score *= META_DOC_FACTOR;
       return { doc, score, matched };
     }).sort((a, b) => b.score - a.score).slice(0, limit);
   }
@@ -739,7 +768,39 @@ function themeSuggestion(utility, hue, step) {
   const scale = step === "500" ? "" : `-${step}`;
   return colors.map((color) => `\`${utility}-${color}${scale}\``).join(" or ");
 }
-function checkClassList(value, offset, context) {
+const THEME_BACKGROUND = /^(?:[\w-]+:)*!?bg-(primary|secondary|accent|info|success|warning|destructive|contrast)(?:-\d{2,3})?(?:\/\d+)?!?$/;
+const FIXED_BACKGROUND = /^(?:[\w-]+:)*!?(?:bg-(?:overlay|black|white|transparent|linear|radial|conic|gradient|none)|bg-\[|bg-\(|from-|via-|to-)/;
+function backgroundOf(classList) {
+  for (const token of classList.split(/\s+/)) {
+    const theme = THEME_BACKGROUND.exec(token);
+    if (theme)
+      return { kind: "theme", color: theme[1] };
+    if (FIXED_BACKGROUND.test(token))
+      return { kind: "fixed" };
+  }
+  return void 0;
+}
+function reportBlackWhite(token, utility, color, background, position, context) {
+  if (background?.kind === "fixed" && utility !== "bg")
+    return;
+  if (background?.color && color === "white" && utility !== "bg") {
+    context.report({
+      rule: "theme-colors",
+      severity: "warning",
+      message: `\`${token}\` on \`bg-${background.color}\`: the theme gives the readable color of each background.`,
+      suggestion: `Use \`${utility}-${background.color}-foreground\`.`
+    }, position);
+    return;
+  }
+  context.report({
+    rule: "theme-colors",
+    severity: "warning",
+    message: `\`${token}\` is a fixed color that does not follow the theme nor dark mode.`,
+    suggestion: color === "white" ? `Use \`${utility}-surface\` (backgrounds) or the \`-foreground\` of the color behind (\`text-primary-foreground\`). Keep it over a fixed dark background (\`bg-overlay\`, image, video).` : `Use \`${utility}-foreground\` (text) or \`${utility}-contrast\`.`
+  }, position);
+}
+function checkClassList(value, offset, context, inherited) {
+  const background = backgroundOf(value) ?? inherited;
   for (const match of value.matchAll(/\S+/g)) {
     const token = match[0];
     const position = offset + (match.index ?? 0);
@@ -765,13 +826,7 @@ function checkClassList(value, offset, context) {
     }
     const blackWhite = BLACK_WHITE_CLASS.exec(token);
     if (blackWhite) {
-      const [, utility, color] = blackWhite;
-      context.report({
-        rule: "theme-colors",
-        severity: "warning",
-        message: `\`${token}\` is a fixed color that does not follow the theme nor dark mode.`,
-        suggestion: color === "white" ? `Use \`${utility}-surface\` (backgrounds) or the \`-foreground\` of the color behind (\`text-primary-foreground\`).` : `Use \`${utility}-foreground\` (text) or \`${utility}-contrast\`.`
-      }, position);
+      reportBlackWhite(token, blackWhite[1], blackWhite[2], background, position, context);
       continue;
     }
     if (ARBITRARY_COLOR_CLASS.test(token)) {
@@ -991,30 +1046,71 @@ function reviewScript(code, offset, context) {
   }
   checkClassStrings(code.replaceAll(/^\s*import\s[^\n]*$/gm, (line) => " ".repeat(line.length)), offset, context);
 }
+function mazUiName(imported, source) {
+  if (!/^(?:maz-ui|@maz-ui\/icons)(?:\/|$)/.test(source))
+    return void 0;
+  return imported ?? source.split("/").at(-1);
+}
+function localComponents(scripts) {
+  const components = /* @__PURE__ */ new Map();
+  for (const [, clause, source] of scripts.matchAll(/import\s+(?!type\s)([^'";]*?)\s+from\s+["']([^"']+)["']/g)) {
+    const named = /\{([^}]*)\}/.exec(clause)?.[1] ?? "";
+    const defaultName = /^\s*([A-Z]\w*)/.exec(clause.replace(/\{[^}]*\}/, ""))?.[1];
+    if (defaultName)
+      components.set(defaultName, mazUiName(void 0, source));
+    for (const specifier of named.split(",")) {
+      const [imported, local = imported] = specifier.replace(/^\s*type\s+/, "").split(/\s+as\s+/).map((part) => part.trim());
+      if (/^[A-Z]/.test(local ?? ""))
+        components.set(local, mazUiName(imported, source));
+    }
+  }
+  return components;
+}
 
 const COLOR_LITERAL = /#[\da-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\(/i;
 const COLOR_PROPERTIES = /^(?:color|background(?:-color)?|border(?:-[a-z]+)*-color|border(?:-(?:top|right|bottom|left|inline|block)(?:-(?:start|end))?)?|outline(?:-color)?|fill|stroke|box-shadow|text-shadow|caret-color|accent-color|text-decoration-color|column-rule-color)$/;
-function blankComments(css) {
+function blankComments$1(css) {
   return css.replaceAll(/\/\*[\s\S]*?\*\//g, (match) => match.replaceAll(/[^\n]/g, " "));
 }
+const BLACK_OR_WHITE = /^#(?:f{3}|f{6}|f{8}|0{3}|0{6}|0{8})$/i;
+function keyframesRanges(css) {
+  const ranges = [];
+  for (const match of css.matchAll(/@keyframes[^{]*\{/g)) {
+    const start = match.index ?? 0;
+    let depth = 0;
+    for (let index = start + match[0].length - 1; index < css.length; index++) {
+      if (css[index] === "{") {
+        depth++;
+      } else if (css[index] === "}" && --depth === 0) {
+        ranges.push([start, index]);
+        break;
+      }
+    }
+  }
+  return ranges;
+}
 function checkStyleDeclarations(css, offset, context) {
+  const keyframes = keyframesRanges(css);
   for (const match of css.matchAll(/(^|[;{\s])([a-z-]+)\s*:\s*([^;{}]+)/g)) {
     const [, prefix, property, value] = match;
     if (property.startsWith("--") || !COLOR_PROPERTIES.test(property) || /var\(--/.test(value))
       continue;
     const color = COLOR_LITERAL.exec(value);
-    if (color) {
-      context.report({
-        rule: "hardcoded-color",
-        severity: "warning",
-        message: `\`${property}\` uses a hard-coded color (\`${color[0].replace("(", "")}\`): it ignores the theme and dark mode.`,
-        suggestion: "Use a theme variable: `var(--maz-primary)`, `var(--maz-surface)`, `var(--maz-foreground)`, `var(--maz-muted)`, `var(--maz-divider)`... (`color-mix(in oklab, var(--maz-primary) 20%, transparent)` for tints)."
-      }, offset + (match.index ?? 0) + prefix.length);
-    }
+    if (!color)
+      continue;
+    const index = match.index ?? 0;
+    const inKeyframes = keyframes.some(([start, end]) => index > start && index < end);
+    const blackOrWhite = BLACK_OR_WHITE.test(color[0]);
+    context.report({
+      rule: "hardcoded-color",
+      severity: inKeyframes || blackOrWhite ? "info" : "warning",
+      message: `\`${property}\` uses a hard-coded color (\`${color[0].replace("(", "")}\`): it ignores the theme and dark mode.`,
+      suggestion: `Use a theme variable: \`var(--maz-primary)\`, \`var(--maz-surface)\`, \`var(--maz-foreground)\`, \`var(--maz-muted)\`, \`var(--maz-divider)\`... (\`color-mix(in oklab, var(--maz-primary) 20%, transparent)\` for tints).${blackOrWhite ? " Keep it if the element is over media (image, video) or a fixed dark background." : ""}`
+    }, offset + index + prefix.length);
   }
 }
 function reviewStyle(source, offset, context, { sfc = false } = {}) {
-  const css = blankComments(source);
+  const css = blankComments$1(source);
   const applies = [...css.matchAll(/@apply\s+([^;]+);/g)];
   for (const apply of applies) {
     checkClassList(apply[1], offset + (apply.index ?? 0) + apply[0].indexOf(apply[1]), context);
@@ -1259,17 +1355,54 @@ function checkPropValue(prop, value, offset, component, context) {
     }, offset);
   }
 }
-function reportUnknownProp(name, offset, component, context) {
+const PROP_SYNONYMS = {
+  items: ["options"],
+  choices: ["options"],
+  list: ["options"],
+  data: ["options", "rows"],
+  columns: ["headers"],
+  value: ["modelValue"],
+  checked: ["modelValue"],
+  selected: ["modelValue"],
+  open: ["modelValue"],
+  isOpen: ["modelValue"],
+  show: ["modelValue"],
+  visible: ["modelValue"],
+  active: ["modelValue"],
+  text: ["label", "title", "content"],
+  helperText: ["hint"],
+  helper: ["hint"],
+  message: ["hint"],
+  errorMessage: ["hint", "error"],
+  variant: ["color", "fill", "outlined"],
+  image: ["src"],
+  leftIcon: ["startIcon"],
+  rightIcon: ["endIcon"],
+  prependIcon: ["startIcon"],
+  appendIcon: ["endIcon"]
+};
+function nameWords(name) {
+  return toKebab(name).split("-").filter(Boolean);
+}
+function propSuggestions(name, component, { containing = true } = {}) {
   const camel = toCamel(name);
-  const candidates = component.props.map((prop) => prop.name);
-  const near = closest(camel, candidates, { max: 2, limit: 2 });
-  if (isPassthroughAttribute(name) && near.length === 0)
+  const props = component.props.map((prop) => prop.name);
+  const synonyms = (PROP_SYNONYMS[camel] ?? []).filter((prop) => props.includes(prop));
+  const words = nameWords(camel.replace(/^(?:is|has)(?=[A-Z])/, ""));
+  const withWords = containing ? props.filter((prop) => words.every((word) => nameWords(prop).includes(word))).sort((a, b) => a.length - b.length) : [];
+  const near = closest(camel, props, { max: camel.length <= 3 ? 1 : 2, limit: 2 });
+  return [.../* @__PURE__ */ new Set([...synonyms, ...withWords, ...near])].slice(0, 3);
+}
+function reportUnknownProp(name, offset, component, context) {
+  const passthrough = isPassthroughAttribute(name);
+  const near = propSuggestions(name, component, { containing: !passthrough });
+  if (passthrough && near.length === 0)
     return;
   context.report({
     rule: "unknown-prop",
     severity: "warning",
-    message: `${component.name} has no prop \`${name}\`${isPassthroughAttribute(name) ? "" : ": it will only be forwarded as an HTML attribute"}.`,
-    suggestion: near.length > 0 ? `Did you mean ${near.map((entry) => `\`${toKebab(entry)}\``).join(" or ")}? Check \`get_component_api({ names: ["${component.name}"] })\`.` : `Check the real API with \`get_component_api({ names: ["${component.name}"] })\`.`
+    message: `${component.name} has no prop \`${name}\`${passthrough ? "" : ": it will only be forwarded as an HTML attribute"}.`,
+    suggestion: near.length > 0 ? `Did you mean ${near.map((entry) => entry === "modelValue" ? "`v-model`" : `\`${toKebab(entry)}\``).join(" or ")}? Check \`get_component_api({ names: ["${component.name}"] })\`.` : `Check the real API with \`get_component_api({ names: ["${component.name}"] })\`.`
   }, offset);
 }
 function checkModel(directive, component, context) {
@@ -1320,10 +1453,16 @@ function usedSlots(element) {
   const templates = element.children.filter((child) => isElement(child) && child.tag === "template");
   return [element, ...templates].flatMap((node) => node.props.filter(isStaticSlot)).map((prop) => ({ name: directiveArg(prop) ?? "default", offset: prop.loc.start.offset }));
 }
+function slotMatches(slot, name) {
+  if (!slot.includes("{"))
+    return slot === name;
+  const [prefix, suffix] = slot.split(/\{[^}]*\}/);
+  return name.length > prefix.length + suffix.length && name.startsWith(prefix) && name.endsWith(suffix);
+}
 function checkSlots(element, component, context) {
   const slots = component.slots.map((slot) => slot.name);
   for (const { name, offset } of usedSlots(element)) {
-    if (slots.includes(name) || name === "default" && slots.length === 0)
+    if (slots.some((slot) => slotMatches(slot, name)) || name === "default" && slots.length === 0)
       continue;
     const near = closest(name, slots, { max: 3, limit: 2 });
     context.report({
@@ -1371,8 +1510,26 @@ function checkMazComponent(element, component, source, context) {
   }
   checkSlots(element, component, context);
 }
+const SVG_SHAPES = /* @__PURE__ */ new Set(["path", "circle", "rect", "polyline", "polygon", "line", "ellipse"]);
+const ICON_MAX_VIEWBOX = 32;
+function svgDescendants(element) {
+  return element.children.filter(isElement).flatMap((child) => [child, ...svgDescendants(child)]);
+}
+function isAnimated(element) {
+  const classes = staticAttribute(element, "class")?.value?.content ?? "";
+  return element.tag.startsWith("animate") || /\banimate-|\[animation/.test(classes) || element.props.some((prop) => prop.name.startsWith("stroke-dash"));
+}
+function isIconLikeSvg(svg) {
+  const descendants = svgDescendants(svg);
+  if (!descendants.some((child) => SVG_SHAPES.has(child.tag)))
+    return false;
+  const viewBox = staticAttribute(svg, "viewBox")?.value?.content.trim().split(/[\s,]+/).map(Number);
+  if (viewBox?.length === 4 && (viewBox[2] > ICON_MAX_VIEWBOX || viewBox[3] > ICON_MAX_VIEWBOX))
+    return false;
+  return ![svg, ...descendants].some((node) => isAnimated(node) || node !== svg && node.props.some((prop) => prop.type === NodeTypes.DIRECTIVE));
+}
 function checkNativeElement(element, context) {
-  if (element.tag === "svg" && element.children.some((child) => isElement(child) && ["path", "circle", "rect", "polyline", "line"].includes(child.tag))) {
+  if (element.tag === "svg" && isIconLikeSvg(element)) {
     context.report({
       rule: "inline-svg",
       severity: "warning",
@@ -1391,10 +1548,10 @@ function checkNativeElement(element, context) {
     }, element.loc.start.offset);
   }
 }
-function checkClassBindings(element, source, context) {
+function checkClassBindings(element, source, context, inherited) {
   for (const prop of element.props) {
     if (prop.type === NodeTypes.ATTRIBUTE && prop.name === "class" && prop.value) {
-      checkClassList(prop.value.content, valueOffset(prop, source), context);
+      checkClassList(prop.value.content, valueOffset(prop, source), context, inherited);
     } else if (prop.type === NodeTypes.ATTRIBUTE && prop.name === "style" && prop.value) {
       checkStyleDeclarations(prop.value.content, valueOffset(prop, source), context);
     } else if (prop.type === NodeTypes.DIRECTIVE && prop.name === "bind" && directiveArg(prop) === "class") {
@@ -1420,17 +1577,18 @@ function checkMazTag(element, mazName, source, context) {
     suggestion: near.length > 0 ? `Did you mean ${near.map((entry) => `\`${entry}\``).join(" or ")}?` : "Use `search_docs` or `find_icons` to find the right name."
   }, element.loc.start.offset);
 }
-function walk(node, source, context) {
+function walk(node, source, context, background) {
   for (const child of node.children) {
     if (!isElement(child))
       continue;
-    const mazName = mazTagName(child.tag);
+    const pascal = /[A-Z-]/.test(child.tag) ? toPascal(child.tag) : void 0;
+    const mazName = pascal && context.localComponents?.has(pascal) ? mazTagName(context.localComponents.get(pascal) ?? "") : mazTagName(child.tag);
     if (mazName)
       checkMazTag(child, mazName, source, context);
     else
       checkNativeElement(child, context);
-    checkClassBindings(child, source, context);
-    walk(child, source, context);
+    checkClassBindings(child, source, context, background);
+    walk(child, source, context, backgroundOf(staticAttribute(child, "class")?.value?.content ?? "") ?? background);
   }
 }
 function reviewTemplate(root, source, context) {
@@ -1537,7 +1695,9 @@ function reviewCode(code, options) {
     reviewTemplate(parse(code), code, context);
   } else {
     const root = parse(code, { parseMode: "sfc" });
-    for (const block of blocksOf(root)) {
+    const blocks = blocksOf(root);
+    context.localComponents = localComponents(blocks.filter((block) => block.tag === "script").map((block) => blockContent(block).content).join("\n"));
+    for (const block of blocks) {
       if (block.tag === "template") {
         reviewTemplate(block, code, context);
       } else if (block.tag === "script") {
@@ -1742,7 +1902,7 @@ Workflow:
 1. search_docs("<the need in plain words>") BEFORE creating a component, composable, helper, icon or style ("confirm before delete", "phone input", "debounce search", "dark mode toggle").
 2. get_component_api(["MazBtn", ...]) BEFORE writing a template with Maz* components: use only documented props, values, events and slots.
 3. find_icons("<meaning>") for icons: never inline SVG nor another icon library.
-4. get_theme_tokens() BEFORE styling: theme colors only (bg-surface, text-foreground, text-muted, border-divider, bg-primary text-primary-foreground, bg-container...), radius, shadow-elevation, breakpoints mob-*/tab-*/lap-*.
+4. get_theme_tokens() BEFORE styling: it reads the project theme (preset, @theme tokens, variants, utilities) and lists the maz-ui classes. Theme colors only (bg-surface, text-foreground, text-muted, border-divider, bg-primary text-primary-foreground, bg-container...), radius, shadow-elevation, breakpoints mob-*/tab-*/lap-*.
 5. review_code({ paths: [...] }) on the files you changed, then fix every error and warning.
 Other tools: get_doc (pages and guides: guide/tailwind, ecosystem/themes, ecosystem/translations, ecosystem/nuxt, guide/vue, guide/migration-v5...), list_docs (catalog), get_setup_guide (install in Vue or Nuxt).
 
@@ -2042,6 +2202,464 @@ const getSetupGuideTool = defineTool({
   run: getSetupGuide
 });
 
+function sourceOf(node, source) {
+  return source.slice(node.start ?? 0, node.end ?? 0).replaceAll(/\s+/g, " ");
+}
+function keyOf(node) {
+  if (node.type !== "ObjectProperty" || node.computed)
+    return void 0;
+  if (node.key.type === "Identifier")
+    return node.key.name;
+  return node.key.type === "StringLiteral" || node.key.type === "NumericLiteral" ? String(node.key.value) : void 0;
+}
+function unwrap(node) {
+  return node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression" || node.type === "TSNonNullExpression" || node.type === "ParenthesizedExpression" ? unwrap(node.expression) : node;
+}
+function literalValue(node, source) {
+  const expression = unwrap(node);
+  switch (expression.type) {
+    case "StringLiteral":
+    case "NumericLiteral":
+    case "BooleanLiteral":
+      return expression.value;
+    case "NullLiteral":
+      return null;
+    case "TemplateLiteral":
+      return expression.expressions.length === 0 ? expression.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join("") : `<expr: ${sourceOf(expression, source)}>`;
+    case "ArrayExpression":
+      return expression.elements.map((element) => element && element.type !== "SpreadElement" ? literalValue(element, source) : null);
+    case "ObjectExpression":
+      return Object.fromEntries(expression.properties.flatMap((property) => {
+        const key = keyOf(property);
+        return key && property.type === "ObjectProperty" ? [[key, literalValue(property.value, source)]] : [];
+      }));
+    default:
+      return `<expr: ${sourceOf(expression, source)}>`;
+  }
+}
+function isDefinePreset(node) {
+  return node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "definePreset";
+}
+function findPresetCalls(node, found, name) {
+  if (isDefinePreset(node)) {
+    found.push({ call: node, name });
+    return;
+  }
+  const variableName = node.type === "VariableDeclarator" && node.id.type === "Identifier" ? node.id.name : name;
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "loc" || key === "leadingComments" || key === "trailingComments" || key === "innerComments")
+      continue;
+    for (const child of Array.isArray(value) ? value : [value]) {
+      if (child && typeof child === "object" && typeof child.type === "string")
+        findPresetCalls(child, found, variableName);
+    }
+  }
+}
+function readPresets(file, source) {
+  let program;
+  try {
+    program = parse$1(source, { sourceType: "module", plugins: ["typescript"], errorRecovery: true }).program;
+  } catch {
+    return [];
+  }
+  const calls = [];
+  findPresetCalls(program, calls);
+  return calls.flatMap(({ call, name }) => {
+    const [argument] = call.arguments;
+    if (!argument || argument.type !== "ObjectExpression")
+      return [];
+    const options = literalValue(argument, source);
+    const base = options.base;
+    const overrides = options.overrides;
+    return [{
+      file,
+      exportName: name,
+      base: typeof base === "string" ? base.replace(/^<expr: (.*)>$/, "$1") : void 0,
+      overrides: overrides && typeof overrides === "object" && !Array.isArray(overrides) ? overrides : {}
+    }];
+  });
+}
+
+const BLOCK_AT_RULES = /^@(?:utility|keyframes|custom-variant)\s/;
+function blankComments(css, comments) {
+  return css.replaceAll(/\/\*([\s\S]*?)\*\//g, (match, text, index) => {
+    comments.push({ end: index + match.length, text: text.replaceAll(/\s*\n\s*\*?\s*/g, " ").trim() });
+    return match.replaceAll(/[^\n]/g, " ");
+  });
+}
+function commentBefore(css, comments, start) {
+  const comment = comments.findLast((entry) => entry.end <= start);
+  return comment && css.slice(comment.end, start).trim() === "" ? comment.text : void 0;
+}
+function parseCss(source) {
+  const comments = [];
+  const css = blankComments(source, comments);
+  const result = { declarations: [], statements: [], blocks: [] };
+  const stack = [];
+  let start = 0;
+  let parens = 0;
+  let quote;
+  const flush = (end) => {
+    const raw = css.slice(start, end);
+    const statement = raw.trim();
+    const position = start + raw.indexOf(statement);
+    if (statement.startsWith("@")) {
+      result.statements.push(statement.replaceAll(/\s+/g, " "));
+      return;
+    }
+    const declaration = /^(--[\w*-]+|[a-z-]+)\s*:([\s\S]*)$/.exec(statement);
+    if (declaration && stack.length > 0) {
+      result.declarations.push({
+        property: declaration[1],
+        value: declaration[2].trim().replaceAll(/\s+/g, " "),
+        context: stack.map((entry) => entry.prelude),
+        comment: commentBefore(css, comments, position)
+      });
+    }
+  };
+  for (let index = 0; index < css.length; index++) {
+    const char = css[index];
+    if (quote) {
+      if (char === quote && css[index - 1] !== "\\")
+        quote = void 0;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === "(") {
+      parens++;
+    } else if (char === ")") {
+      parens = Math.max(0, parens - 1);
+    } else if (parens > 0) {
+      continue;
+    } else if (char === ";") {
+      flush(index);
+      start = index + 1;
+    } else if (char === "{") {
+      stack.push({ prelude: css.slice(start, index).trim().replaceAll(/\s+/g, " "), open: index });
+      start = index + 1;
+    } else if (char === "}") {
+      flush(index);
+      start = index + 1;
+      const block = stack.pop();
+      if (block && BLOCK_AT_RULES.test(block.prelude))
+        result.blocks.push({ prelude: block.prelude, body: css.slice(block.open + 1, index).trim().replaceAll(/\s+/g, " ") });
+    }
+  }
+  return result;
+}
+const NAMESPACES = [
+  { prefix: "--color-", topic: "colors", usage: (name) => `bg-${name} text-${name} border-${name}...` },
+  { prefix: "--font-weight-", topic: "typography", usage: (name) => `font-${name}` },
+  { prefix: "--font-", topic: "typography", usage: (name) => `font-${name}` },
+  { prefix: "--text-shadow-", topic: "shadows", usage: (name) => `text-shadow-${name}` },
+  { prefix: "--text-", topic: "typography", usage: (name) => `text-${name}` },
+  { prefix: "--tracking-", topic: "typography", usage: (name) => `tracking-${name}` },
+  { prefix: "--leading-", topic: "typography", usage: (name) => `leading-${name}` },
+  { prefix: "--animate-", topic: "typography", usage: (name) => `animate-${name}` },
+  { prefix: "--ease-", topic: "typography", usage: (name) => `ease-${name}` },
+  { prefix: "--duration-", topic: "typography", usage: (name) => `duration-(--duration-${name})` },
+  { prefix: "--radius-", topic: "radius", usage: (name) => `rounded-${name}` },
+  { prefix: "--inset-shadow-", topic: "shadows", usage: (name) => `inset-shadow-${name}` },
+  { prefix: "--drop-shadow-", topic: "shadows", usage: (name) => `drop-shadow-${name}` },
+  { prefix: "--shadow-", topic: "shadows", usage: (name) => `shadow-${name}` },
+  { prefix: "--spacing-", topic: "spacing", usage: (name) => `p-${name} gap-${name} w-${name}...` },
+  { prefix: "--breakpoint-", topic: "breakpoints", usage: (name) => `${name}:` },
+  { prefix: "--container-", topic: "layout", usage: (name) => `max-w-${name} @${name}:` },
+  { prefix: "--aspect-", topic: "layout", usage: (name) => `aspect-${name}` },
+  { prefix: "--z-", topic: "z-index", usage: (name) => `z-${name}` }
+];
+function tokenOf(variable, value, { inline = false, comment } = {}) {
+  if (variable === "--spacing")
+    return { variable, value, topic: "spacing", usage: "p-4 gap-2 w-8... (base step)", inline, comment };
+  const namespace = NAMESPACES.find((entry) => variable.startsWith(entry.prefix));
+  return namespace ? { variable, value, topic: namespace.topic, usage: namespace.usage(variable.slice(namespace.prefix.length)), inline, comment } : { variable, value, topic: "css-variables", usage: `var(${variable})`, inline, comment };
+}
+function importPath(statement) {
+  return /^@import\s+(?:url\()?\s*["']([^"']+)["']/.exec(statement)?.[1];
+}
+function themeContext(context) {
+  return context.find((prelude) => /^@theme\b/.test(prelude));
+}
+function readStylesheet(file, source) {
+  const { declarations, statements, blocks } = parseCss(source);
+  const stylesheet = { file, imports: [], tokens: [], resets: [], variants: [], utilities: [], keyframes: [], mazVariables: [] };
+  for (const statement of statements) {
+    const path = importPath(statement);
+    const variant = /^@custom-variant ([\w-]+) (.+)$/.exec(statement);
+    if (path)
+      stylesheet.imports.push(path);
+    else if (variant)
+      stylesheet.variants.push({ name: variant[1], definition: variant[2] });
+  }
+  for (const { prelude, body } of blocks) {
+    const [, kind, name] = /^@([\w-]+) ([\w*-]+)/.exec(prelude) ?? [];
+    if (kind === "utility")
+      stylesheet.utilities.push({ name, css: body });
+    else if (kind === "keyframes")
+      stylesheet.keyframes.push(name);
+    else if (kind === "custom-variant")
+      stylesheet.variants.push({ name, definition: `{ ${body} }` });
+  }
+  for (const { property, value, context, comment } of declarations) {
+    const theme = themeContext(context);
+    if (theme && property.startsWith("--")) {
+      if (value === "initial")
+        stylesheet.resets.push(property);
+      else if (!/^--[\w-]+--/.test(property))
+        stylesheet.tokens.push(tokenOf(property, value, { inline: /\binline\b/.test(theme), comment }));
+    } else if (!theme && property.startsWith("--maz-")) {
+      stylesheet.mazVariables.push({ variable: property, value, selector: context.filter((prelude) => !prelude.startsWith("@layer")).join(" ") });
+    }
+  }
+  return stylesheet;
+}
+function isTailwindStylesheet(source) {
+  return /@import\s+(?:url\()?\s*["'](?:tailwindcss|maz-ui\/tailwindcss)/.test(source) || /@(?:theme|custom-variant|utility)\b/.test(source);
+}
+
+const IGNORED = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/coverage/**",
+  "**/public/**",
+  "**/.*/**",
+  "**/*.min.css",
+  "**/*.d.ts",
+  "**/*.{spec,test}.*"
+];
+const MAX_FILE_SIZE = 3e5;
+const PATTERNS = ["*.css", "*.ts", "*.mts", "*.cts", "*.js", "*.mjs"];
+const IGNORED_PATH = /(?:^|\/)(?:node_modules|dist|build|coverage|public|fixtures|__tests__|\.[^/]+)\/|\.min\.css$|\.d\.ts$|\.(?:spec|test)\.\w+$/;
+function projectFiles(rootDir) {
+  try {
+    return execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "--", ...PATTERNS], { cwd: rootDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 }).split("\n").filter((file) => file && !IGNORED_PATH.test(file));
+  } catch {
+    return globSync(PATTERNS.map((pattern) => `**/${pattern}`), { cwd: rootDir, ignore: IGNORED, deep: 8 }).filter((file) => !IGNORED_PATH.test(file));
+  }
+}
+function readSmallFile(path) {
+  try {
+    return statSync(path).size <= MAX_FILE_SIZE ? readFileSync(path, "utf8") : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readProjectTheme(rootDir) {
+  if (!existsSync(join(rootDir, "package.json")))
+    return { stylesheets: [], presets: [] };
+  const files = projectFiles(rootDir).sort();
+  const theme = { stylesheets: [], presets: [] };
+  for (const file of files) {
+    const source = readSmallFile(join(rootDir, file));
+    if (!source)
+      continue;
+    if (file.endsWith(".css")) {
+      if (isTailwindStylesheet(source))
+        theme.stylesheets.push(readStylesheet(file, source));
+    } else if (source.includes("definePreset(")) {
+      theme.presets.push(...readPresets(file, source));
+    }
+  }
+  return theme;
+}
+const FOUNDATION_USAGE = {
+  "base-font-size": { topic: "typography", usage: "root font size: every `rem` and the `text-*` sizes" },
+  "border-width": { topic: "typography", usage: "`border` (default width)" },
+  "font-family": { topic: "typography", usage: "`font-sans` (default font)" },
+  "font-mono-stack": { topic: "typography", usage: "`font-mono`" },
+  "font-display-stack": { topic: "typography", usage: "`font-display`" },
+  "motion-fast": { topic: "typography", usage: "`duration-(--duration-fast)`" },
+  "motion-normal": { topic: "typography", usage: "`duration-(--duration-normal)` and the default transition duration" },
+  "motion-slow": { topic: "typography", usage: "`duration-(--duration-slow)`" },
+  "easing-out": { topic: "typography", usage: "`ease-out` and the default transition easing" },
+  "easing-in": { topic: "typography", usage: "`ease-in`" },
+  "easing-in-out": { topic: "typography", usage: "`ease-in-out`" },
+  "disabled-opacity": { topic: "utilities", usage: "`disabled-opacity`, `disabled-state`" },
+  "disabled-cursor": { topic: "utilities", usage: "`disabled-cursor`, `disabled-state`" },
+  "space": { topic: "spacing", usage: "every spacing utility (`p-4` = 4 x space)" }
+};
+const COMPONENT_USAGE = {
+  "btn.font-weight": "font weight of MazBtn",
+  "container.bg": "`bg-container`: MazCard, MazContainer, MazDialog, MazPopover, MazDrawer...",
+  "input.bg": "`bg-input`: MazInput, MazSelect, MazTextarea, MazCheckbox...",
+  "input.top-label-font-weight": "font weight of the `top-label` of the inputs",
+  "dialog.max-width": "max width of MazDialog",
+  "dialog.min-width": "min width of MazDialog"
+};
+function code(value) {
+  return `\`${value.replaceAll("`", "'").replaceAll("|", "\\|")}\``;
+}
+function shorten(value, max = 70) {
+  return value.length > max ? `${value.slice(0, max - 3)}...` : value;
+}
+function display(value) {
+  if (value === void 0)
+    return "-";
+  return code(shorten(typeof value === "object" && value !== null ? JSON.stringify(value) : String(value)));
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+const COLOR_CLASSES = {
+  shadow: "`shadow-shadow/20`",
+  overlay: "`bg-overlay`",
+  divider: "`border-divider`"
+};
+function colorClasses(name) {
+  if (COLOR_CLASSES[name])
+    return COLOR_CLASSES[name];
+  return name.endsWith("-foreground") ? code(`text-${name}`) : `${code(`bg-${name}`)} ${code(`text-${name}`)}`;
+}
+function presetColors(preset) {
+  const colors = asRecord(preset.overrides.colors);
+  const light = asRecord(colors.light);
+  const dark = asRecord(colors.dark);
+  const names = [.../* @__PURE__ */ new Set([...Object.keys(light), ...Object.keys(dark)])];
+  if (names.length === 0)
+    return [];
+  return [
+    "| Color | Classes | Light | Dark |",
+    "| --- | --- | --- | --- |",
+    ...names.map((name) => `| \`${name}\` | ${colorClasses(name)} | ${display(light[name])} | ${display(dark[name])} |`)
+  ];
+}
+function presetFoundation(preset, wanted) {
+  const rows = Object.entries(asRecord(preset.overrides.foundation)).filter(([key]) => wanted(FOUNDATION_USAGE[key]?.topic ?? "css-variables")).map(([key, value]) => `| \`${key}\` | \`--maz-${key}\` | ${FOUNDATION_USAGE[key]?.usage ?? "-"} | ${display(value)} |`);
+  return rows.length > 0 ? ["| Foundation | CSS variable | Used by | Value |", "| --- | --- | --- | --- |", ...rows] : [];
+}
+function presetScales(preset, wanted) {
+  const scales = asRecord(preset.overrides.scales);
+  const rows = [
+    ...wanted("radius") ? Object.entries(asRecord(scales.rounded)).map(([key, value]) => `| ${code(`rounded-${key}`)} | ${display(value)} |`) : [],
+    ...wanted("shadows") ? Object.entries(asRecord(scales.shadow)).map(([key, value]) => `| ${code(`shadow-${key}`)} | ${display(value)} |`) : []
+  ];
+  return rows.length > 0 ? ["| Class | Value |", "| --- | --- |", ...rows] : [];
+}
+function flatten(value, path) {
+  const record = asRecord(value);
+  const keys = Object.keys(record);
+  if (keys.length === 0 || keys.every((key) => key === "light" || key === "dark"))
+    return [[path, value]];
+  return keys.flatMap((key) => flatten(record[key], path ? `${path}.${key}` : key));
+}
+function presetComponents(preset) {
+  const rows = flatten(asRecord(preset.overrides.components), "").filter(([path]) => path).map(([path, value]) => `| \`components.${path}\` | ${COMPONENT_USAGE[path] ?? "-"} | ${display(value)} |`);
+  return rows.length > 0 ? ["| Component token | Used by | Value |", "| --- | --- | --- |", ...rows] : [];
+}
+function renderPreset(preset, wanted, filtered) {
+  const name = typeof preset.overrides.name === "string" ? ` \`${preset.overrides.name}\`` : "";
+  const origin = [preset.exportName && `\`${preset.exportName}\``, preset.base && `base \`${preset.base}\``].filter(Boolean).join(", ");
+  const tables = [
+    wanted("colors") ? presetColors(preset) : [],
+    presetFoundation(preset, wanted),
+    presetScales(preset, wanted),
+    wanted("colors") ? presetComponents(preset) : []
+  ].filter((table) => table.length > 0);
+  if (filtered && tables.length === 0)
+    return void 0;
+  return [
+    `### Preset${name} - \`${preset.file}\`${origin ? ` (${origin})` : ""}`,
+    "The preset sets the **values** of the maz-ui tokens at runtime, the class names stay the same: `bg-primary` uses the preset `primary`, `font-display` the preset `font-display-stack`. Brand colors, fonts, radius, shadows and motion belong here, not in CSS.",
+    ...tables.map((table) => table.join("\n"))
+  ].join("\n\n");
+}
+function mazUiThemeVariables(tailwind) {
+  const variables = /* @__PURE__ */ new Map();
+  const named = (entries, toVariable) => {
+    for (const entry of entries) variables.set(toVariable(entry.name), entry.value);
+  };
+  for (const color of tailwind.colors) variables.set(`--color-${color.name}`, `var(${color.variable})`);
+  named(tailwind.fonts, (name) => `--${name}`);
+  named(tailwind.radius, (name) => name.replace(/^rounded-/, "--radius-"));
+  named(tailwind.shadows, (name) => `--${name}`);
+  named(tailwind.breakpoints, (name) => `--breakpoint-${name.replace(/:$/, "")}`);
+  named(tailwind.easings, (name) => `--${name}`);
+  named(tailwind.zIndex, (name) => `--${name}`);
+  named(tailwind.durations, (name) => /--duration-[\w-]+/.exec(name)?.[0] ?? name);
+  return variables;
+}
+function tokenNote(token, mazUi) {
+  const original = mazUi.get(token.variable);
+  const notes = [
+    token.comment,
+    original && original !== token.value ? `Redefines the maz-ui token (maz-ui: ${code(shorten(original, 50))}): this class no longer follows the preset.` : void 0
+  ];
+  return notes.filter(Boolean).join(" ").replaceAll("|", "\\|") || "-";
+}
+function renderStylesheet(stylesheet, mazUi, wanted, animated) {
+  const sections = [];
+  const problems = stylesheetProblems(stylesheet);
+  if (problems.length > 0)
+    sections.push(problems.map((problem) => `> ${problem}`).join("\n>\n"));
+  const tokens = stylesheet.tokens.filter((token) => wanted(token.topic));
+  if (tokens.length > 0) {
+    sections.push([
+      `#### Project tokens (\`@theme\`)`,
+      "",
+      "| Classes | Variable | Value | Note |",
+      "| --- | --- | --- | --- |",
+      ...tokens.map((token) => `| ${code(token.usage)} | \`${token.variable}\` | ${code(shorten(token.value, 60))} | ${tokenNote(token, mazUi)} |`)
+    ].join("\n"));
+  }
+  if (stylesheet.resets.length > 0 && wanted("colors"))
+    sections.push(`Reset namespaces: ${stylesheet.resets.map((reset) => code(reset)).join(", ")}: the default Tailwind tokens of these namespaces do not exist.`);
+  if (stylesheet.variants.length > 0 && (wanted("variants") || wanted("breakpoints")))
+    sections.push(["#### Custom variants", "", "| Variant | Definition |", "| --- | --- |", ...stylesheet.variants.map((variant) => `| \`${variant.name}:\` | ${code(shorten(variant.definition))} |`)].join("\n"));
+  if (stylesheet.utilities.length > 0 && wanted("utilities"))
+    sections.push(["#### Custom utilities", "", "| Class | CSS |", "| --- | --- |", ...stylesheet.utilities.map((utility) => `| \`${utility.name}\` | ${code(shorten(utility.css))} |`)].join("\n"));
+  const keyframes = stylesheet.keyframes.filter((name) => !animated.has(name));
+  if (keyframes.length > 0 && wanted("typography"))
+    sections.push(`Keyframes without \`animate-*\` token: ${keyframes.map((name) => code(name)).join(", ")}. Use them in CSS or add a \`--animate-<name>\` token to the \`@theme\` to get a class.`);
+  if (stylesheet.mazVariables.length > 0 && (wanted("layout") || wanted("css-variables"))) {
+    sections.push([
+      "#### maz-ui variables set in CSS",
+      "",
+      "| Variable | Value | Selector |",
+      "| --- | --- | --- |",
+      ...stylesheet.mazVariables.map((variable) => `| \`${variable.variable}\` | ${code(shorten(variable.value, 50))} | ${code(variable.selector)} |`)
+    ].join("\n"));
+  }
+  return sections;
+}
+function renderStylesheetSection(stylesheet, mazUi, topics, animated) {
+  const sections = renderStylesheet(stylesheet, mazUi, (topic) => !topics?.length || topics.includes(topic), animated);
+  if (topics?.length && sections.length === 0)
+    return void 0;
+  const imports = stylesheet.imports.length > 0 ? [`Imports: ${stylesheet.imports.map((path) => code(path)).join(", ")}`] : [];
+  return [`### Tailwind \`${stylesheet.file}\``, ...imports, ...sections].join("\n\n");
+}
+function stylesheetProblems(stylesheet) {
+  if (!stylesheet.imports.includes("tailwindcss"))
+    return [];
+  const mazUiImports = stylesheet.imports.filter((path) => path.startsWith("maz-ui/tailwindcss"));
+  const problems = [];
+  if (mazUiImports.length === 0)
+    problems.push("The maz-ui theme is not imported: `bg-primary`, `rounded-md`, `mob-m:`... do not exist. Add `@import 'maz-ui/tailwindcss/theme.css';` after `@import 'tailwindcss';`.");
+  else if (!mazUiImports.includes("maz-ui/tailwindcss/utilities.css"))
+    problems.push("`maz-ui/tailwindcss/utilities.css` is not imported: `flex-center`, `padded-container`, `disabled-state`... do not exist.");
+  return problems;
+}
+const HOW_IT_WORKS = `How your theme combines with maz-ui:
+
+1. **The preset** (\`definePreset\` of \`@maz-ui/themes\`) sets the runtime values of the maz-ui tokens (\`--maz-*\`): brand colors, fonts, radius, shadows, motion. The maz-ui classes keep their names and follow it, in light and dark mode.
+2. **The Tailwind entry** imports the maz-ui theme, then extends it with \`@theme\` tokens (each one generates classes: \`--animate-rise\` -> \`animate-rise\`, \`--font-display\` -> \`font-display\`), \`@custom-variant\` and \`@utility\`.
+3. **Pick classes in this order**: the project tokens below for project-specific needs, then the maz-ui classes, never the default Tailwind palette, hard-coded values or arbitrary values. When a value is missing, add a token to the project \`@theme\` (or a brand value to the preset) and use its class.`;
+function renderProjectTheme(theme, tailwind, topics) {
+  if (theme.stylesheets.length === 0 && theme.presets.length === 0)
+    return void 0;
+  const wanted = (topic) => !topics?.length || topics.includes(topic);
+  const mazUi = mazUiThemeVariables(tailwind);
+  const animated = new Set(theme.stylesheets.flatMap((stylesheet) => stylesheet.tokens.filter((token) => token.variable.startsWith("--animate-")).map((token) => token.value.split(/\s/)[0])));
+  return [
+    "## Your project theme",
+    HOW_IT_WORKS,
+    ...theme.presets.map((preset) => renderPreset(preset, wanted, !!topics?.length)),
+    ...theme.stylesheets.map((stylesheet) => renderStylesheetSection(stylesheet, mazUi, topics, animated))
+  ].filter(Boolean).join("\n\n");
+}
+
 const THEME_TOPICS = {
   "setup": "Setup",
   "colors": "Colors",
@@ -2057,28 +2675,32 @@ const THEME_TOPICS = {
   "transitions": "Vue transitions",
   "css-variables": "CSS variables in custom CSS"
 };
-function getThemeTokens(context, { topics }) {
+function getThemeTokens(context, { topics, project = true }) {
   const reference = context.knowledge.docsById.get("reference/tailwind-tokens");
   if (!reference)
     throw new ToolInputError('This maz-ui version does not ship the Tailwind reference. Read `get_doc({ id: "guide/tailwind" })`.');
   const markdown = stripFrontmatter(context.knowledge.readDoc(reference.id));
-  const footer = '\n\nTo extend the theme (your own colors, fonts, animations, variants, container width): `get_doc({ id: "guide/tailwind" })`. Brand colors and radius belong to a preset: `get_doc({ id: "ecosystem/themes", sections: ["Creating Custom Themes"] })`.';
-  if (!topics?.length)
-    return `${markdown.trim()}${footer}`;
-  const parts = topics.map((topic) => {
+  const projectTheme = project ? renderProjectTheme(readProjectTheme(context.cwd), context.knowledge.manifest.tailwind, topics) : void 0;
+  const footer = '\n\nHow to extend the theme (project colors, fonts, animations, variants, utilities, container width) and how it combines with the preset: `get_doc({ id: "guide/tailwind" })`. Brand colors, fonts and radius belong to a preset: `get_doc({ id: "ecosystem/themes", sections: ["Creating Custom Themes"] })`.';
+  const mazUiTheme = topics?.length ? `# maz-ui ${context.knowledge.version} Tailwind theme
+
+${topics.map((topic) => {
     const section = findSection(markdown, THEME_TOPICS[topic]);
     return section ? sectionContent(markdown, section) : "";
-  });
-  return `# maz-ui ${context.knowledge.version} Tailwind theme
+  }).filter(Boolean).join("\n\n")}` : markdown.trim();
+  return projectTheme ? `${projectTheme}
+
+---
 
-${parts.filter(Boolean).join("\n\n")}${footer}`;
+${mazUiTheme}${footer}` : `${mazUiTheme}${footer}`;
 }
 const getThemeTokensTool = defineTool({
   name: "get_theme_tokens",
   title: "maz-ui Tailwind theme tokens",
-  description: "Every Tailwind CSS class and CSS variable of the maz-ui theme (installed version): theme colors (bg-primary, text-muted, border-divider, bg-surface... with -foreground and 50-950 scales), radius, shadows (shadow-elevation), spacing, breakpoints (mob-*, tab-*, lap-*), fonts, durations, z-index, custom utilities (flex-center, padded-container), dark variant and CSS variables. Use it before styling: never the default Tailwind palette, hard-coded colors or the internal `maz:` prefix.",
+  description: "The Tailwind theme of the project: its own tokens, preset, variants and utilities (read from its Tailwind entry and `definePreset`), then every Tailwind CSS class and CSS variable of the maz-ui theme (installed version): theme colors (bg-primary, text-muted, border-divider, bg-surface... with -foreground and 50-950 scales), radius, shadows (shadow-elevation), spacing, breakpoints (mob-*, tab-*, lap-*), fonts, durations, z-index, custom utilities (flex-center, padded-container), dark variant and CSS variables. Use it before styling: never the default Tailwind palette, hard-coded colors or the internal `maz:` prefix.",
   inputSchema: {
-    topics: z.array(z.enum(Object.keys(THEME_TOPICS))).optional().describe("Only these topics (default: everything)")
+    topics: z.array(z.enum(Object.keys(THEME_TOPICS))).optional().describe("Only these topics (default: everything)"),
+    project: z.boolean().optional().describe("Include the theme of the project: preset, `@theme` tokens, variants, utilities (default: true)")
   },
   run: getThemeTokens
 });
@@ -2145,7 +2767,7 @@ async function runTool(context, tool, args) {
 function createMazUiMcpServer(options = {}) {
   const context = createContext(options);
   const server = new McpServer(
-    { name: "maz-ui", title: "maz-ui", version },
+    { name: "maz-ui", title: "maz-ui", version: readOwnVersion() },
     { instructions: buildInstructions(context) }
   );
   for (const tool of TOOLS) {
@@ -2172,7 +2794,7 @@ async function startStdioServer(options = {}) {
   return server;
 }
 
-const HELP = `maz-ui-mcp ${version}: maz-ui knowledge for AI coding agents
+const HELP = `maz-ui-mcp: maz-ui knowledge for AI coding agents
 
 Usage:
   maz-ui-mcp [serve] [--docs <dir>]   Start the MCP server (stdio)
@@ -2309,7 +2931,7 @@ async function runCli(argv = process.argv.slice(2)) {
     return 0;
   }
   if (values.version) {
-    console.log(version);
+    console.log(readOwnVersion());
     return 0;
   }
   switch (command) {