@fragments-sdk/mcp 0.9.0 → 0.10.1

package/dist/{chunk-YSNIGHNU.js → chunk-KGFM5SCE.js}

@@ -1,28 +1,19 @@
-import {
-  BRAND,
-  DEFAULTS
-} from "./chunk-4SVS3AA3.js";
-import {
-  componentNames,
-  findComponent,
-  findComponentByName,
-  getGuidanceWhen,
-  getGuidanceWhenNot,
-  listBlocks,
-  listComponents
-} from "./chunk-YSRGQDEB.js";
-
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
+  ErrorCode,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 import { readFileSync as readFileSync6 } from "fs";
-import { join as join8 } from "path";
+import { join as join7 } from "path";
 import { fileURLToPath } from "url";
+import { BRAND as BRAND4 } from "@fragments-sdk/core";
 
 // src/config.ts
 import { readFileSync, existsSync } from "fs";
@@ -30,2372 +21,294 @@ import { join } from "path";
 function loadConfigFile(projectRoot) {
   const configPath = join(projectRoot, "ds-mcp.config.json");
   if (existsSync(configPath)) {
-    try {
-      const content = readFileSync(configPath, "utf-8");
-      return JSON.parse(content);
-    } catch (e) {
-      throw new Error(`Failed to parse ${configPath}: ${e instanceof Error ? e.message : String(e)}`);
-    }
-  }
-  const pkgPath = join(projectRoot, "package.json");
-  if (existsSync(pkgPath)) {
-    try {
-      const content = readFileSync(pkgPath, "utf-8");
-      const pkg = JSON.parse(content);
-      if (pkg.dsMcp) return pkg.dsMcp;
-    } catch {
-    }
-  }
-  return null;
-}
-
-// src/server.ts
-import { buildMcpTools, buildToolNames, MCP_TOOL_DEFINITIONS } from "@fragments-sdk/context/mcp-tools";
-
-// src/orama-index.ts
-import { create, insertMultiple, search } from "@orama/orama";
-var SYNONYM_MAP = {
-  "form": ["input", "field", "submit", "validation"],
-  "input": ["form", "field", "text", "entry"],
-  "button": ["action", "click", "submit", "trigger"],
-  "action": ["button", "click", "trigger"],
-  "submit": ["button", "form", "action", "send"],
-  "alert": ["notification", "message", "warning", "error", "feedback"],
-  "notification": ["alert", "message", "toast"],
-  "feedback": ["form", "comment", "review", "rating"],
-  "card": ["container", "panel", "box", "content"],
-  "toggle": ["switch", "checkbox", "boolean", "on/off"],
-  "switch": ["toggle", "checkbox", "boolean"],
-  "badge": ["tag", "label", "status", "indicator"],
-  "status": ["badge", "indicator", "state"],
-  "login": ["auth", "signin", "authentication", "form"],
-  "auth": ["login", "signin", "authentication"],
-  "chat": ["message", "conversation", "ai"],
-  "table": ["data", "grid", "list", "rows"],
-  "textarea": ["text", "input", "multiline", "area", "comment"],
-  "area": ["textarea", "multiline", "text"],
-  "landing": ["page", "hero", "marketing", "section", "layout"],
-  "hero": ["landing", "marketing", "banner", "headline", "section"],
-  "marketing": ["landing", "hero", "pricing", "testimonial", "cta"],
-  "cta": ["marketing", "banner", "action", "button"],
-  "testimonial": ["marketing", "review", "quote", "feedback"],
-  "layout": ["stack", "grid", "box", "container", "page"],
-  "page": ["layout", "landing", "section", "container"],
-  "section": ["hero", "feature", "testimonial", "cta", "faq"],
-  "pricing": ["card", "plan", "tier", "marketing"],
-  "plan": ["pricing", "card", "tier", "subscription"],
-  "dashboard": ["metrics", "stats", "chart", "card", "grid"],
-  "metrics": ["dashboard", "stats", "progress", "number"],
-  "stats": ["metrics", "dashboard", "progress", "badge"],
-  "chart": ["dashboard", "metrics", "data", "graph"]
-};
-function expandQuery(query) {
-  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  const expanded = new Set(terms);
-  for (const term of terms) {
-    const synonyms = SYNONYM_MAP[term];
-    if (synonyms) {
-      for (const syn of synonyms) expanded.add(syn);
-    }
-  }
-  return Array.from(expanded).join(" ");
-}
-function twoPassSearch(config) {
-  const { index, query, properties, boost, limit, kind } = config;
-  const baseConfig = {
-    mode: "fulltext",
-    properties,
-    boost,
-    limit
-  };
-  const originalTermsQuery = query.toLowerCase().split(/\s+/).filter(Boolean).join(" ");
-  const expandedQuery = expandQuery(query);
-  const originalResults = search(index, { term: originalTermsQuery, ...baseConfig, threshold: 0.8 });
-  const expandedResults = search(index, { term: expandedQuery, ...baseConfig, threshold: 1 });
-  const origHits = originalResults.hits;
-  const expHits = expandedResults.hits;
-  const scoreMap = /* @__PURE__ */ new Map();
-  for (const hit of origHits) {
-    scoreMap.set(hit.document.name, (hit.score || 0) * 2);
-  }
-  for (const hit of expHits) {
-    const name = hit.document.name;
-    const existing = scoreMap.get(name) ?? 0;
-    scoreMap.set(name, existing + (hit.score || 0));
-  }
-  const scored = [];
-  for (const [name, score] of scoreMap) {
-    if (score > 0) {
-      scored.push({ name, kind, rank: scored.length, score });
-    }
-  }
-  scored.sort((a, b) => b.score - a.score);
-  scored.forEach((s, i) => {
-    s.rank = i;
-  });
-  return scored;
-}
-var componentSchema = {
-  name: "string",
-  description: "string",
-  category: "string",
-  tags: "string",
-  whenUsed: "string",
-  patterns: "string",
-  variants: "string",
-  status: "string"
-};
-function isCompiledFragment(value) {
-  return "meta" in value;
-}
-function normalizeComponent(value) {
-  if (!isCompiledFragment(value)) return value;
-  return {
-    id: value.filePath ?? value.meta.name,
-    name: value.meta.name,
-    description: value.meta.description ?? "",
-    category: value.meta.category ?? "uncategorized",
-    status: value.meta.status ?? "stable",
-    tags: value.meta.tags ?? [],
-    props: {},
-    propsSummary: value.propsSummary ?? value.contract?.propsSummary ?? Object.entries(value.props ?? {}).map(
-      ([propName, prop]) => `${propName}${prop.required ? " (required)" : ""}: ${prop.type}`
-    ),
-    examples: (value.variants ?? []).map((variant) => ({
-      name: variant.name,
-      description: variant.description,
-      code: variant.code
-    })),
-    relations: (value.relations ?? []).map((relation) => ({
-      componentName: relation.component,
-      relationship: relation.relationship,
-      note: relation.note
-    })),
-    compoundChildren: [],
-    guidance: {
-      when: value.usage?.when ?? [],
-      whenNot: value.usage?.whenNot ?? [],
-      guidelines: value.usage?.guidelines ?? [],
-      accessibility: value.usage?.accessibility ?? [],
-      dos: value.usage?.when ?? [],
-      donts: value.usage?.whenNot ?? [],
-      patterns: []
-    },
-    sourceType: "fragments-json",
-    sourcePath: value.sourcePath ?? value.filePath,
-    metadata: {
-      a11yRules: value.contract?.a11yRules ?? [],
-      scenarioTags: value.contract?.scenarioTags ?? []
-    }
-  };
-}
-function buildComponentIndex(fragments) {
-  const db = create({ schema: componentSchema, language: "english" });
-  const normalized = fragments.map(normalizeComponent);
-  const docs = normalized.map((f) => ({
-    name: f.name,
-    description: f.description ?? "",
-    category: f.category ?? "",
-    tags: (f.tags ?? []).join(" "),
-    whenUsed: (f.guidance.when ?? []).join(" "),
-    patterns: (f.guidance.patterns ?? []).map(
-      (pattern) => `${pattern.name} ${pattern.description || ""}`
-    ).join(" "),
-    variants: f.examples.map(
-      (example) => `${example.name} ${example.description || ""}`
-    ).join(" "),
-    status: f.status ?? "stable"
-  }));
-  insertMultiple(db, docs);
-  return db;
-}
-function searchComponents(query, index, fragments, limit = 50) {
-  const normalized = fragments.map(normalizeComponent);
-  const boostConfig = {
-    mode: "fulltext",
-    properties: ["name", "whenUsed", "description", "patterns", "category", "tags", "variants"],
-    boost: {
-      name: 3,
-      whenUsed: 2.5,
-      description: 2,
-      patterns: 1.5,
-      category: 1.5,
-      tags: 1.5,
-      variants: 1
-    },
-    limit
-  };
-  const originalTermsList = query.toLowerCase().split(/\s+/).filter(Boolean);
-  const originalTermsQuery = originalTermsList.join(" ");
-  const expandedQuery = expandQuery(query);
-  const originalResults = search(index, { term: originalTermsQuery, ...boostConfig, threshold: 0.8 });
-  const expandedResults = search(index, { term: expandedQuery, ...boostConfig, threshold: 1 });
-  const origHits = originalResults.hits;
-  const expHits = expandedResults.hits;
-  const scoreMap = /* @__PURE__ */ new Map();
-  for (const hit of origHits) {
-    scoreMap.set(hit.document.name, (hit.score || 0) * 2);
-  }
-  for (const hit of expHits) {
-    const name = hit.document.name;
-    const existing = scoreMap.get(name) ?? 0;
-    scoreMap.set(name, existing + (hit.score || 0));
-  }
-  const fragmentMap = /* @__PURE__ */ new Map();
-  for (const f of normalized) {
-    fragmentMap.set(f.name.toLowerCase(), f);
-  }
-  const originalTermsSet = new Set(originalTermsList);
-  const scored = [];
-  for (const [name, rawScore] of scoreMap) {
-    let score = rawScore;
-    const nameLower = name.toLowerCase();
-    const fragment = fragmentMap.get(nameLower);
-    if (originalTermsSet.has(nameLower)) {
-      score += 25;
-    }
-    if (fragment) {
-      if (fragment.status === "stable") score += 5;
-      else if (fragment.status === "beta") score += 2;
-      if (fragment.status === "deprecated") score -= 25;
-    }
-    if (score > 0) {
-      scored.push({ name, kind: "component", rank: scored.length, score });
-    }
-  }
-  scored.sort((a, b) => b.score - a.score);
-  scored.forEach((s, i) => {
-    s.rank = i;
-  });
-  return scored;
-}
-var blockSchema = {
-  name: "string",
-  description: "string",
-  category: "string",
-  tags: "string",
-  components: "string"
-};
-function normalizeBlock(value) {
-  if ("id" in value) return value;
-  return {
-    id: value.filePath ?? value.name,
-    name: value.name,
-    description: value.description ?? "",
-    category: value.category ?? "uncategorized",
-    components: value.components ?? [],
-    tags: value.tags ?? [],
-    code: value.code ?? ""
-  };
-}
-function buildBlockIndex(blocks) {
-  const db = create({ schema: blockSchema, language: "english" });
-  const normalized = blocks.map(normalizeBlock);
-  const docs = normalized.map((b) => ({
-    name: b.name,
-    description: b.description ?? "",
-    category: b.category ?? "",
-    tags: (b.tags ?? []).join(" "),
-    components: b.components.join(" ")
-  }));
-  insertMultiple(db, docs);
-  return db;
-}
-function searchBlocks(query, index, limit = 50) {
-  return twoPassSearch({
-    index,
-    query,
-    properties: ["name", "description", "components", "tags", "category"],
-    boost: {
-      name: 3,
-      description: 2,
-      components: 1.5,
-      tags: 1.5,
-      category: 1.5
-    },
-    limit,
-    kind: "block"
-  });
-}
-var tokenSchema = {
-  name: "string",
-  category: "string",
-  description: "string"
-};
-function normalizeTokenData(tokenData) {
-  if ("flat" in tokenData) return tokenData;
-  const categories = Object.fromEntries(
-    Object.entries(tokenData.categories).map(([category, entries]) => [
-      category,
-      entries.map((entry) => ({
-        name: entry.name,
-        category,
-        value: typeof entry.value === "string" ? entry.value : void 0,
-        description: entry.description
-      }))
-    ])
-  );
-  return {
-    prefix: tokenData.prefix,
-    total: tokenData.total,
-    categories,
-    flat: Object.values(categories).flat()
-  };
-}
-function buildTokenIndex(tokenData) {
-  const db = create({ schema: tokenSchema, language: "english" });
-  const normalizedData = normalizeTokenData(tokenData);
-  const docs = [];
-  for (const [cat, tokens] of Object.entries(normalizedData.categories)) {
-    for (const token of tokens) {
-      docs.push({
-        name: token.name,
-        category: cat,
-        description: token.description ?? ""
-      });
-    }
-  }
-  insertMultiple(db, docs);
-  return db;
-}
-function searchTokens(query, index, limit = 50) {
-  return twoPassSearch({
-    index,
-    query,
-    properties: ["name", "category", "description"],
-    boost: {
-      name: 2.5,
-      category: 2,
-      description: 1.5
-    },
-    limit,
-    kind: "token"
-  });
-}
-var USE_CASE_TOKEN_CATEGORIES = {
-  "table": ["spacing", "borders", "surfaces", "text"],
-  "data": ["spacing", "borders", "surfaces"],
-  "grid": ["spacing", "layout"],
-  "form": ["spacing", "borders", "radius", "focus"],
-  "input": ["spacing", "borders", "radius", "focus"],
-  "card": ["surfaces", "shadows", "radius", "borders", "spacing"],
-  "button": ["colors", "radius", "spacing", "focus"],
-  "layout": ["spacing", "layout", "surfaces"],
-  "dashboard": ["spacing", "surfaces", "borders", "shadows"],
-  "chat": ["spacing", "surfaces", "radius", "shadows"],
-  "modal": ["shadows", "surfaces", "radius", "spacing"],
-  "dialog": ["shadows", "surfaces", "radius", "spacing"],
-  "navigation": ["spacing", "surfaces", "borders"],
-  "sidebar": ["spacing", "surfaces", "borders"],
-  "hero": ["spacing", "typography", "colors"],
-  "landing": ["spacing", "typography", "colors"],
-  "pricing": ["spacing", "surfaces", "borders", "radius"],
-  "auth": ["spacing", "borders", "radius", "focus"],
-  "login": ["spacing", "borders", "radius", "focus"],
-  "dark": ["colors", "surfaces"],
-  "theme": ["colors", "surfaces", "text"]
-};
-function extractTokenCategories(query) {
-  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  const categories = /* @__PURE__ */ new Set();
-  for (const term of terms) {
-    const cats = USE_CASE_TOKEN_CATEGORIES[term];
-    if (cats) {
-      for (const cat of cats) categories.add(cat);
-    }
-  }
-  if (categories.size === 0) {
-    return ["spacing", "colors", "surfaces"];
-  }
-  return Array.from(categories);
-}
-
-// src/version.ts
-import { readFileSync as readFileSync2 } from "fs";
-function readPackageVersion() {
-  try {
-    const raw = readFileSync2(new URL("../package.json", import.meta.url), "utf-8");
-    const pkg = JSON.parse(raw);
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-var MCP_SERVER_VERSION = readPackageVersion();
-
-// src/search.ts
-var CONVEX_SEARCH_URL = "https://combative-jay-834.convex.site/search";
-var CONVEX_TIMEOUT_MS = 3e3;
-async function searchConvex(query, apiKey, limit = 10, kind) {
-  try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), CONVEX_TIMEOUT_MS);
-    const response = await fetch(CONVEX_SEARCH_URL, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${apiKey}`
-      },
-      body: JSON.stringify({ query, limit, ...kind && { kind } }),
-      signal: controller.signal
-    });
-    clearTimeout(timeout);
-    if (!response.ok) {
-      return [];
-    }
-    const data = await response.json();
-    return data.results.map((r, i) => ({
-      name: r.name,
-      kind: r.kind ?? "component",
-      rank: i,
-      score: r.score
-    }));
-  } catch {
-    return [];
-  }
-}
-function keywordScoreComponents(query, fragments, componentIndex) {
-  const index = componentIndex ?? buildComponentIndex(fragments);
-  return searchComponents(query, index, fragments);
-}
-function keywordScoreBlocks(query, blocks, blockIndex) {
-  const index = blockIndex ?? buildBlockIndex(blocks);
-  return searchBlocks(query, index);
-}
-function keywordScoreTokens(query, tokenData, tokenIndex) {
-  const index = tokenIndex ?? buildTokenIndex(tokenData);
-  return searchTokens(query, index);
-}
-function reciprocalRankFusion(resultSets, k = 60) {
-  const scoreMap = /* @__PURE__ */ new Map();
-  for (const { results } of resultSets) {
-    for (let rank = 0; rank < results.length; rank++) {
-      const result2 = results[rank];
-      const key = `${result2.kind}:${result2.name}`;
-      const rrfScore = 1 / (k + rank + 1);
-      const existing = scoreMap.get(key);
-      if (existing) {
-        existing.score += rrfScore;
-      } else {
-        scoreMap.set(key, { score: rrfScore, kind: result2.kind, name: result2.name });
-      }
-    }
-  }
-  const fused = [];
-  for (const [, { score, kind, name }] of scoreMap) {
-    fused.push({ name, kind, rank: 0, score });
-  }
-  fused.sort((a, b) => b.score - a.score);
-  fused.forEach((r, i) => {
-    r.rank = i;
-  });
-  return fused;
-}
-async function hybridSearch(query, data, limit = 10, kind, apiKey) {
-  const keywordResults = [];
-  if (!kind || kind === "component") {
-    keywordResults.push(...keywordScoreComponents(query, data.fragments, data.componentIndex));
-  }
-  if ((!kind || kind === "block") && data.blocks) {
-    keywordResults.push(...keywordScoreBlocks(query, data.blocks, data.blockIndex));
-  }
-  if ((!kind || kind === "token") && data.tokenData) {
-    keywordResults.push(...keywordScoreTokens(query, data.tokenData, data.tokenIndex));
-  }
-  keywordResults.sort((a, b) => b.score - a.score);
-  keywordResults.forEach((r, i) => {
-    r.rank = i;
-  });
-  if (!apiKey) {
-    return keywordResults.slice(0, limit);
-  }
-  const vectorResults = await searchConvex(query, apiKey, limit, kind);
-  if (vectorResults.length === 0) {
-    return keywordResults.slice(0, limit);
-  }
-  const graphBoostResults = [];
-  if (data.graph) {
-    try {
-      const { ComponentGraphEngine: ComponentGraphEngine2, deserializeGraph: deserializeGraph2 } = await import("@fragments-sdk/context/graph");
-      const graph = deserializeGraph2(data.graph);
-      const engine = new ComponentGraphEngine2(graph);
-      const topComponents = [...keywordResults, ...vectorResults].filter((r) => r.kind === "component").slice(0, 5);
-      const neighborSet = /* @__PURE__ */ new Set();
-      for (const result2 of topComponents) {
-        const neighbors = engine.neighbors(result2.name, 1);
-        for (const n of neighbors.neighbors) {
-          if (!neighborSet.has(n.component)) {
-            neighborSet.add(n.component);
-            graphBoostResults.push({
-              name: n.component,
-              kind: "component",
-              rank: graphBoostResults.length,
-              score: 1
-              // Will be normalized through RRF
-            });
-          }
-        }
-      }
-    } catch {
-    }
-  }
-  const resultSets = [
-    { label: "vector", results: vectorResults },
-    { label: "keyword", results: keywordResults }
-  ];
-  if (graphBoostResults.length > 0) {
-    resultSets.push({ label: "graph", results: graphBoostResults });
-  }
-  const fused = reciprocalRankFusion(resultSets);
-  return fused.slice(0, limit);
-}
-
-// src/scoring.ts
-var MINIMUM_SCORE_THRESHOLD = 5;
-function assignConfidence(score, maxScore) {
-  if (maxScore <= 0) return "low";
-  const ratio = score / maxScore;
-  if (ratio >= 0.7) return "high";
-  if (ratio >= 0.4) return "medium";
-  return "low";
-}
-function meetsMinimumThreshold(maxScore) {
-  return maxScore >= MINIMUM_SCORE_THRESHOLD;
-}
-function levenshtein(a, b) {
-  const la = a.length;
-  const lb = b.length;
-  const dp = Array.from({ length: lb + 1 }, (_, i) => i);
-  for (let i = 1; i <= la; i++) {
-    let prev = i - 1;
-    dp[0] = i;
-    for (let j = 1; j <= lb; j++) {
-      const temp = dp[j];
-      dp[j] = a[i - 1] === b[j - 1] ? prev : 1 + Math.min(prev, dp[j], dp[j - 1]);
-      prev = temp;
-    }
-  }
-  return dp[lb];
-}
-function findClosestMatch(input, candidates, maxDistance = 3) {
-  const inputLower = input.toLowerCase();
-  let bestMatch = null;
-  let bestDist = maxDistance + 1;
-  for (const candidate of candidates) {
-    const candidateLower = candidate.toLowerCase();
-    const dist = levenshtein(inputLower, candidateLower);
-    if (dist < bestDist) {
-      bestDist = dist;
-      bestMatch = candidate;
-    } else if (dist === bestDist && bestMatch) {
-      const currentLenDiff = Math.abs(bestMatch.length - input.length);
-      const newLenDiff = Math.abs(candidate.length - input.length);
-      if (newLenDiff < currentLenDiff) {
-        bestMatch = candidate;
-      }
-    }
-  }
-  return bestDist <= maxDistance ? bestMatch : null;
-}
-var BLOCK_BOOST_PER_OCCURRENCE = 5;
-function buildBlockComponentFrequency(blocks) {
-  const freq = /* @__PURE__ */ new Map();
-  for (const block of blocks) {
-    for (const comp of block.components) {
-      const key = comp.toLowerCase();
-      freq.set(key, (freq.get(key) ?? 0) + 1);
-    }
-  }
-  return freq;
-}
-function boostByBlockFrequency(results, freq) {
-  for (const result2 of results) {
-    const count = freq.get(result2.name.toLowerCase()) ?? 0;
-    if (count > 0) {
-      result2.score += count * BLOCK_BOOST_PER_OCCURRENCE;
-    }
-  }
-  results.sort((a, b) => b.score - a.score);
-  results.forEach((r, i) => {
-    r.rank = i;
-  });
-  return results;
-}
-
-// src/server-helpers.ts
-function normalizeFilter(value) {
-  const normalized = value?.trim().toLowerCase();
-  return normalized && normalized.length > 0 ? normalized : void 0;
-}
-function categoryMatches(category, categoryFilter) {
-  if (!categoryFilter) return true;
-  return normalizeFilter(category) === categoryFilter;
-}
-function buildLocalSearchData(data, indexes) {
-  const isLegacy = "fragments" in data;
-  const allFragments = Object.values(
-    isLegacy ? data.fragments : data.components
-  );
-  const allBlocks = Object.values(
-    isLegacy ? data.blocks ?? data.recipes ?? {} : data.blocks ?? {}
-  );
-  const tokens = isLegacy ? data.tokens : data.tokens;
-  const graph = isLegacy ? data.graph : data.graph;
-  const localData = {
-    fragments: allFragments,
-    blocks: allBlocks,
-    tokenData: tokens,
-    graph,
-    componentIndex: indexes.componentIndex ?? void 0,
-    blockIndex: indexes.blockIndex ?? void 0,
-    tokenIndex: indexes.tokenIndex ?? void 0
-  };
-  return { allFragments, allBlocks, localData };
-}
-async function buildImportStatements(components, resolvePackageName) {
-  const grouped = /* @__PURE__ */ new Map();
-  const uniqueComponents = [...new Set(components.filter(Boolean))];
-  const resolvedPackages = await Promise.all(
-    uniqueComponents.map(async (component) => ({
-      component,
-      packageName: await resolvePackageName(component)
-    }))
-  );
-  for (const { component, packageName } of resolvedPackages) {
-    const existing = grouped.get(packageName);
-    if (!existing) {
-      grouped.set(packageName, [component]);
-      continue;
-    }
-    existing.push(component);
-  }
-  return Array.from(grouped.entries()).map(
-    ([packageName, componentNames2]) => `import { ${componentNames2.join(", ")} } from '${packageName}';`
-  );
-}
-function limitTokensPerCategory(categories, limit) {
-  if (limit === void 0) {
-    return {
-      categories,
-      total: Object.values(categories).reduce((sum, tokens) => sum + tokens.length, 0)
-    };
-  }
-  const limited = {};
-  let total = 0;
-  for (const [category, tokens] of Object.entries(categories)) {
-    const sliced = tokens.slice(0, limit);
-    if (sliced.length === 0) continue;
-    limited[category] = sliced;
-    total += sliced.length;
-  }
-  return { categories: limited, total };
-}
-
-// src/search-helpers.ts
-var STOP_WORDS = /* @__PURE__ */ new Set([
-  "a",
-  "an",
-  "and",
-  "bar",
-  "build",
-  "button",
-  "for",
-  "form",
-  "i",
-  "login",
-  "me",
-  "need",
-  "of",
-  "or",
-  "the",
-  "to",
-  "use",
-  "with"
-]);
-function normalizeTerms(value) {
-  return value.toLowerCase().split(/[^a-z0-9]+/g).filter((term) => term.length > 1 && !STOP_WORDS.has(term));
-}
-function hasDirectQueryOverlap(query, component) {
-  const queryTerms = normalizeTerms(query);
-  if (queryTerms.length === 0) return true;
-  const haystack = new Set(
-    normalizeTerms(
-      [
-        component.name,
-        component.description,
-        component.category,
-        component.tags.join(" "),
-        getGuidanceWhen(component).join(" "),
-        getGuidanceWhenNot(component).join(" "),
-        component.propsSummary.join(" ")
-      ].join(" ")
-    )
-  );
-  return queryTerms.some((term) => haystack.has(term));
-}
-function getRankingBonus(component) {
-  let bonus = 0;
-  if (component.isCanonical) bonus += 30;
-  if (component.tier === "core") bonus += 20;
-  if (component.status === "stable") bonus += 5;
-  return bonus;
-}
-
-// src/tools/discover.ts
-function renderContextMarkdown(args) {
-  const lines = ["# Design System Context", ""];
-  for (const component of args.components) {
-    lines.push(`## ${component.name}`);
-    if (component.description) {
-      lines.push(component.description);
-    }
-    lines.push(
-      `- Category: ${component.category}`,
-      `- Status: ${component.status}`
-    );
-    if (component.propsSummary.length > 0) {
-      lines.push(`- Props: ${component.propsSummary.join(", ")}`);
-    }
-    const when = getGuidanceWhen(component);
-    if (when.length > 0) {
-      lines.push(`- Use when: ${when.slice(0, args.compact ? 1 : 3).join("; ")}`);
-    }
-    const whenNot = getGuidanceWhenNot(component);
-    if (whenNot.length > 0) {
-      lines.push(
-        `- Avoid when: ${whenNot.slice(0, args.compact ? 1 : 2).join("; ")}`
-      );
-    }
-    if (args.includeRelations && component.relations.length > 0) {
-      lines.push(
-        `- Related: ${component.relations.slice(0, 5).map(
-          (relation) => `${relation.componentName} (${relation.relationship})`
-        ).join(", ")}`
-      );
-    }
-    if (args.includeCode && component.examples[0]?.code) {
-      lines.push("", "```tsx", component.examples[0].code, "```");
-    }
-    lines.push("");
-  }
-  if (args.blocks.length > 0) {
-    lines.push("## Blocks", "");
-    for (const block of args.blocks) {
-      lines.push(`- ${block.name}: ${block.description}`);
-    }
-    lines.push("");
-  }
-  return lines.join("\n").trim();
-}
-function renderContextJson(args) {
-  return JSON.stringify({
-    components: args.components.map((component) => ({
-      name: component.name,
-      description: component.description,
-      category: component.category,
-      status: component.status,
-      propsSummary: component.propsSummary,
-      when: getGuidanceWhen(component),
-      whenNot: getGuidanceWhenNot(component),
-      ...args.includeRelations && { relations: component.relations },
-      ...args.includeCode && {
-        examples: component.examples.filter((example) => Boolean(example.code)).slice(0, 2)
-      }
-    })),
-    blocks: args.blocks
-  });
-}
-var discoverHandler = async (args, ctx) => {
-  const data = ctx.data;
-  const snapshotComponents = listComponents(data.snapshot);
-  const componentsByName = new Map(
-    snapshotComponents.map((component) => [
-      component.name.toLowerCase(),
-      component
-    ])
-  );
-  const useCase = args?.useCase ?? void 0;
-  const componentForAlts = args?.component ?? void 0;
-  const category = normalizeFilter(args?.category);
-  const search2 = args?.search?.toLowerCase() ?? void 0;
-  const status = args?.status ?? void 0;
-  const format = args?.format ?? "markdown";
-  const compact = args?.compact ?? false;
-  const includeCode = args?.includeCode ?? false;
-  const includeRelations = args?.includeRelations ?? false;
-  const depth = args?.depth ?? "quick";
-  const suggestLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 25) : 10;
-  const listLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 25) : void 0;
-  const verbosity = args?.verbosity ?? (compact ? "compact" : "standard");
-  const allSnapshotComponents = listComponents(data.snapshot);
-  if (!useCase && !componentForAlts && (args?.format || includeCode || includeRelations)) {
-    let components2 = allSnapshotComponents;
-    const allBlocks = listBlocks(data.snapshot);
-    if (category) {
-      components2 = components2.filter(
-        (component) => categoryMatches(component.category, category)
-      );
-    }
-    if (search2) {
-      const scored = keywordScoreComponents(
-        search2,
-        components2,
-        ctx.indexes.componentIndex ?? void 0
-      );
-      const allowedNames = new Set(components2.map((component) => component.name));
-      const sortedNames = scored.filter((result2) => allowedNames.has(result2.name)).map((result2) => result2.name.toLowerCase());
-      components2 = components2.filter((component) => sortedNames.includes(component.name.toLowerCase())).sort(
-        (a, b) => sortedNames.indexOf(a.name.toLowerCase()) - sortedNames.indexOf(b.name.toLowerCase())
-      );
-    }
-    if (status) {
-      components2 = components2.filter((component) => component.status === status);
-    }
-    const blocks = allBlocks.map((block) => ({
-      name: block.name,
-      description: block.description
-    }));
-    const ctxContent = format === "json" ? renderContextJson({
-      components: components2,
-      blocks,
-      includeCode: includeCode || verbosity === "full",
-      includeRelations
-    }) : renderContextMarkdown({
-      components: components2,
-      blocks,
-      includeCode: includeCode || verbosity === "full",
-      includeRelations,
-      compact: verbosity === "compact"
-    });
-    return {
-      content: [{ type: "text", text: ctxContent }],
-      _meta: {
-        componentCount: components2.length,
-        blockCount: blocks.length
-      }
-    };
-  }
-  if (useCase) {
-    const { allFragments, allBlocks, localData } = buildLocalSearchData(
-      {
-        components: data.components,
-        blocks: data.blocks,
-        tokens: data.tokens,
-        graph: data.graph
-      },
-      {
-        componentIndex: ctx.indexes.componentIndex,
-        blockIndex: ctx.indexes.blockIndex,
-        tokenIndex: ctx.indexes.tokenIndex
-      }
-    );
-    const context = args?.context?.toLowerCase() ?? "";
-    const fullQuery = context ? `${useCase} ${context}` : useCase;
-    const searchResults = await hybridSearch(
-      fullQuery,
-      localData,
-      suggestLimit,
-      "component",
-      ctx.config.searchApiKey
-    );
-    const filteredSearchResults = searchResults.filter((result2) => {
-      const component = componentsByName.get(result2.name.toLowerCase());
-      if (!component) return false;
-      if (category && !categoryMatches(component.category, category)) return false;
-      if (status && component.status !== status) return false;
-      result2.score += getRankingBonus(component);
-      return true;
-    });
-    const blockMatches = keywordScoreBlocks(
-      fullQuery,
-      allBlocks,
-      ctx.indexes.blockIndex ?? void 0
-    ).slice(0, 5);
-    if (blockMatches.length > 0) {
-      const matchedBlocks = blockMatches.map(
-        (match) => allBlocks.find((block) => block.name.toLowerCase() === match.name.toLowerCase())
-      ).filter(Boolean);
-      const blockFreq = buildBlockComponentFrequency(matchedBlocks);
-      boostByBlockFrequency(filteredSearchResults, blockFreq);
-    }
-    const maxScore = filteredSearchResults.length > 0 ? filteredSearchResults[0].score : 0;
-    const scored = filteredSearchResults.map((result2) => {
-      const component = componentsByName.get(result2.name.toLowerCase());
-      if (!component) return null;
-      return {
-        component: component.name,
-        category: component.category,
-        description: component.description,
-        confidence: assignConfidence(result2.score, maxScore),
-        reasons: [`Matched via hybrid search (score: ${result2.score.toFixed(4)})`],
-        usage: {
-          when: getGuidanceWhen(component).slice(0, 3),
-          whenNot: getGuidanceWhenNot(component).slice(0, 2)
-        },
-        publicRef: component.publicRef,
-        componentKey: component.id,
-        tier: component.tier,
-        isCanonical: component.isCanonical ?? false,
-        sourcePath: component.sourcePath,
-        exampleCount: component.examples.length,
-        status: component.status
-      };
-    }).filter(Boolean);
-    const suggestions = [];
-    const categoryCount = {};
-    for (const item of scored) {
-      if (!item) continue;
-      const cat = item.category || "uncategorized";
-      const count = categoryCount[cat] || 0;
-      if (count < 2 || suggestions.length < 3) {
-        suggestions.push(item);
-        categoryCount[cat] = count + 1;
-        if (suggestions.length >= suggestLimit) break;
-      }
-    }
-    const compositionHint = suggestions.length >= 2 ? `These components work well together. For example, ${suggestions[0].component} can be combined with ${suggestions.slice(1, 3).map((item) => item.component).join(" and ")}.` : void 0;
-    const useCaseLower = useCase.toLowerCase();
-    const styleKeywords = [
-      "color",
-      "spacing",
-      "padding",
-      "margin",
-      "font",
-      "border",
-      "radius",
-      "shadow",
-      "variable",
-      "token",
-      "css",
-      "theme",
-      "dark mode",
-      "background",
-      "hover"
-    ];
-    const isStyleQuery = styleKeywords.some(
-      (keyword) => useCaseLower.includes(keyword)
-    );
-    const noMatch = suggestions.length === 0 || !suggestions.some((item) => {
-      const component = componentsByName.get(item.component.toLowerCase());
-      return component ? hasDirectQueryOverlap(useCase, component) : false;
-    });
-    const belowThreshold = !noMatch && maxScore > 1 && !meetsMinimumThreshold(maxScore);
-    const weakMatch = !noMatch && (belowThreshold || suggestions.every((item) => item.confidence === "low"));
-    let recommendation;
-    let nextStep;
-    if (noMatch) {
-      recommendation = isStyleQuery ? `No matching components found. Your query seems styling-related \u2014 try ${ctx.toolNames.tokens} to find tokens.` : `No matching components found. Try different keywords or browse all components with ${ctx.toolNames.discover}.`;
-      nextStep = isStyleQuery ? `Use ${ctx.toolNames.tokens}(search: "${useCaseLower.split(/\s+/)[0]}") to find tokens.` : void 0;
-    } else if (weakMatch) {
-      recommendation = `Weak matches only \u2014 ${suggestions[0].component} might work but confidence is low.${isStyleQuery ? ` If you need tokens, try ${ctx.toolNames.tokens}.` : ""}`;
-      nextStep = `Use ${ctx.toolNames.inspect}("${suggestions[0].component}") to check if it fits, or try broader search terms.`;
-    } else {
-      recommendation = `Best match: ${suggestions[0].component} (${suggestions[0].confidence} confidence) - ${suggestions[0].description}`;
-      nextStep = `Use ${ctx.toolNames.inspect}("${suggestions[0].component}") for full details.`;
-    }
-    const tokenHint = isStyleQuery && !noMatch ? `Your query includes styling terms. For tokens, also try ${ctx.toolNames.tokens}(search: "${useCaseLower.split(/\s+/)[0]}").` : void 0;
-    const blockNames = blockMatches.map(
-      (match) => allBlocks.find((block) => block.name.toLowerCase() === match.name.toLowerCase())
-    ).filter(Boolean).slice(0, 3).map((block) => block.name);
-    const blockHint = blockNames.length > 0 ? `Related blocks: ${blockNames.join(", ")}. Use ${ctx.toolNames.blocks}(search: "${useCase}") for ready-to-use patterns.` : void 0;
-    let fullBlocks;
-    let fullTokens;
-    let fullImports;
-    if (depth === "full" && !noMatch) {
-      const tokenData = ctx.data.tokens;
-      const [blockSearchResults, tokenSearchResults] = await Promise.all([
-        hybridSearch(fullQuery, localData, 5, "block", ctx.config.searchApiKey),
-        tokenData ? hybridSearch(fullQuery, localData, 10, "token", ctx.config.searchApiKey) : Promise.resolve([])
-      ]);
-      const topBlockScore = blockSearchResults.length > 0 ? blockSearchResults[0].score : 0;
-      const relevantBlockResults = blockSearchResults.filter(
-        (result2) => result2.score >= topBlockScore * 0.3
-      );
-      if (relevantBlockResults.length > 0) {
-        fullBlocks = (await Promise.all(
-          relevantBlockResults.slice(0, 5).map(async (result2) => {
-            const block = allBlocks.find(
-              (entry) => entry.name.toLowerCase() === result2.name.toLowerCase()
-            );
-            if (!block) return null;
-            const imports = await buildImportStatements(
-              block.components,
-              async (componentName) => ctx.resolvePackageName(componentName)
-            );
-            const codeLines = block.code.split("\n");
-            const code = codeLines.length > 30 ? `${codeLines.slice(0, 20).join("\n")}
-// ... truncated (${codeLines.length} lines total)` : block.code;
-            return {
-              name: block.name,
-              description: block.description,
-              components: block.components,
-              code,
-              imports
-            };
-          })
-        )).filter(Boolean);
-      }
-      if (tokenSearchResults.length > 0 && tokenData) {
-        fullTokens = {};
-        const tokensByName = /* @__PURE__ */ new Map();
-        for (const [cat, tokens] of Object.entries(tokenData.categories)) {
-          for (const token of tokens) {
-            tokensByName.set(token.name, cat);
-          }
-        }
-        for (const result2 of tokenSearchResults) {
-          const cat = tokensByName.get(result2.name);
-          if (cat) {
-            if (!fullTokens[cat]) fullTokens[cat] = [];
-            fullTokens[cat].push(result2.name);
-          }
-        }
-        if (Object.keys(fullTokens).length === 0) fullTokens = void 0;
-      }
-      if (!fullTokens && tokenData) {
-        const categories = extractTokenCategories(fullQuery);
-        fullTokens = {};
-        for (const cat of categories) {
-          const tokens = tokenData.categories[cat];
-          if (tokens && tokens.length > 0) {
-            fullTokens[cat] = tokens.slice(0, 5).map((token) => token.name);
-          }
-        }
-        if (Object.keys(fullTokens).length === 0) fullTokens = void 0;
-      }
-      if (suggestions.length > 0) {
-        fullImports = {};
-        for (const item of suggestions) {
-          if (!item) continue;
-          const pkgName = ctx.resolvePackageName(item.component);
-          fullImports[item.component] = `import { ${item.component} } from '${pkgName}';`;
-        }
-      }
-    }
-    const suggestResponse = verbosity === "compact" ? {
-      useCase,
-      suggestions: suggestions.map((item) => ({
-        component: item.component,
-        description: item.description,
-        confidence: item.confidence
-      })),
-      recommendation
-    } : {
-      useCase,
-      context: context || void 0,
-      suggestions: depth === "full" ? suggestions.map((item) => ({
-        ...item,
-        import: fullImports?.[item.component]
-      })) : suggestions,
-      noMatch,
-      weakMatch,
-      recommendation,
-      compositionHint,
-      ...tokenHint && { tokenHint },
-      ...blockHint && { blockHint },
-      nextStep,
-      ...fullBlocks && fullBlocks.length > 0 && { blocks: fullBlocks },
-      ...fullTokens && { tokens: fullTokens }
-    };
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(suggestResponse)
-        }
-      ]
-    };
-  }
-  if (componentForAlts) {
-    const component = findComponent(data.snapshot, componentForAlts);
-    if (!component) {
-      const closest = findClosestMatch(
-        componentForAlts,
-        componentNames(data.snapshot)
-      );
-      const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({
-              error: `Component "${componentForAlts}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`
-            })
-          }
-        ],
-        isError: true
-      };
-    }
-    const relations = component.relations;
-    const referencedBy = allSnapshotComponents.map((entry) => {
-      const relation = entry.relations.find(
-        (candidate) => candidate.componentName.toLowerCase() === component.name.toLowerCase()
-      );
-      if (!relation) return null;
-      return {
-        component: entry.name,
-        relationship: relation.relationship,
-        note: relation.note
-      };
-    }).filter(Boolean);
-    const sameCategory = allSnapshotComponents.filter(
-      (entry) => entry.category === component.category && entry.name.toLowerCase() !== component.name.toLowerCase()
-    ).map((entry) => ({
-      component: entry.name,
-      description: entry.description
-    }));
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({
-            component: component.name,
-            category: component.category,
-            directRelations: relations,
-            referencedBy,
-            sameCategory,
-            suggestion: relations.find(
-              (relation) => relation.relationship === "alternative"
-            ) ? `Consider ${relations.find((relation) => relation.relationship === "alternative")?.componentName}: ${relations.find((relation) => relation.relationship === "alternative")?.note}` : void 0
-          })
-        }
-      ]
-    };
-  }
-  let filteredComponents = allSnapshotComponents.filter((component) => {
-    if (category && !categoryMatches(component.category, category)) return false;
-    if (status && (component.status ?? "stable") !== status) return false;
-    return true;
-  });
-  if (search2) {
-    const scored = keywordScoreComponents(
-      search2,
-      filteredComponents,
-      ctx.indexes.componentIndex ?? void 0
-    ).map((result2) => {
-      const component = filteredComponents.find(
-        (entry) => entry.name.toLowerCase() === result2.name.toLowerCase()
-      );
-      if (!component) return null;
-      return {
-        component,
-        score: result2.score + getRankingBonus(component)
-      };
-    }).filter(Boolean);
-    filteredComponents = scored.sort((a, b) => b.score - a.score).map((entry) => entry.component);
-  } else {
-    filteredComponents = filteredComponents.sort((a, b) => {
-      const bonusDiff = getRankingBonus(b) - getRankingBonus(a);
-      if (bonusDiff !== 0) return bonusDiff;
-      return a.name.localeCompare(b.name);
-    });
-  }
-  const limitedComponents = listLimit === void 0 ? filteredComponents : filteredComponents.slice(0, listLimit);
-  const components = limitedComponents.map((component) => {
-    if (verbosity === "compact") {
-      return {
-        name: component.name,
-        category: component.category,
-        publicRef: component.publicRef,
-        componentKey: component.id,
-        tier: component.tier,
-        isCanonical: component.isCanonical ?? false,
-        ...component.propsSummary.length > 0 && {
-          propsSummary: component.propsSummary
-        }
-      };
-    }
-    return {
-      name: component.name,
-      category: component.category,
-      description: component.description,
-      status: component.status ?? "stable",
-      publicRef: component.publicRef,
-      componentKey: component.id,
-      tier: component.tier,
-      isCanonical: component.isCanonical ?? false,
-      sourcePath: component.sourcePath,
-      exampleCount: component.examples.length,
-      tags: component.tags,
-      ...(includeCode || verbosity === "full") && component.examples[0]?.code ? {
-        example: component.examples[0].code
-      } : {}
-    };
-  });
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify({
-          total: filteredComponents.length,
-          returned: components.length,
-          components,
-          categories: [...new Set(components.map((component) => component.category))],
-          hint: components.length === 0 ? "No components found. Try broader search terms or check available categories." : components.length > 5 ? `Use ${ctx.toolNames.discover} with useCase for recommendations, or ${ctx.toolNames.inspect} for details on a specific component.` : void 0
-        })
-      }
-    ]
-  };
-};
-
-// src/tools/inspect.ts
-import { promises as fs } from "fs";
-import { existsSync as existsSync2 } from "fs";
-import { join as join2 } from "path";
-
-// src/utils.ts
-function projectFields(obj, fields) {
-  if (!fields || fields.length === 0) {
-    return obj;
-  }
-  const result2 = {};
-  for (const field of fields) {
-    const parts = field.split(".");
-    let source = obj;
-    let target = result2;
-    for (let i = 0; i < parts.length; i++) {
-      const part = parts[i];
-      const isLast = i === parts.length - 1;
-      if (source === null || source === void 0 || typeof source !== "object") {
-        break;
-      }
-      const sourceObj = source;
-      const value = sourceObj[part];
-      if (isLast) {
-        target[part] = value;
-      } else {
-        if (!(part in target)) {
-          target[part] = {};
-        }
-        target = target[part];
-        source = value;
-      }
-    }
-  }
-  return result2;
-}
-
-// src/tools/inspect.ts
-async function getSourceCode(component, projectRoot) {
-  const sourcePath = component.sourcePath;
-  if (!sourcePath) return void 0;
-  const fullPath = join2(projectRoot, sourcePath);
-  if (!existsSync2(fullPath)) return { path: sourcePath, code: null };
-  try {
-    const code = await fs.readFile(fullPath, "utf-8");
-    return { path: sourcePath, code };
-  } catch {
-    return { path: sourcePath, code: null };
-  }
-}
-var inspectHandler = async (args, ctx) => {
-  const componentName = args?.component;
-  const fields = args?.fields;
-  const exampleName = args?.variant ?? void 0;
-  const maxExamples = args?.maxExamples;
-  const maxLines = args?.maxLines;
-  const verbosity = args?.verbosity ?? "standard";
-  if (!componentName) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({ error: "component is required" })
-        }
-      ],
-      isError: true
-    };
-  }
-  const component = findComponent(ctx.data.snapshot, componentName);
-  if (!component) {
-    const closest = findClosestMatch(
-      componentName,
-      componentNames(ctx.data.snapshot)
-    );
-    const suggestion = closest ? ` Did you mean "${closest}"? Use ${ctx.toolNames.inspect}("${closest}") to inspect it.` : "";
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({
-            error: `Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`
-          })
-        }
-      ],
-      isError: true
-    };
-  }
-  const pkgName = ctx.resolvePackageName(component.name);
-  let examples = component.examples;
-  if (exampleName) {
-    const query = exampleName.toLowerCase();
-    let filtered = examples.filter((example) => example.name.toLowerCase() === query);
-    if (filtered.length === 0) {
-      filtered = examples.filter(
-        (example) => example.name.toLowerCase().startsWith(query)
-      );
-    }
-    if (filtered.length === 0) {
-      filtered = examples.filter(
-        (example) => example.name.toLowerCase().includes(query)
-      );
-    }
-    if (filtered.length > 0) {
-      examples = filtered;
-    } else {
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({
-              error: `Example "${exampleName}" not found for ${componentName}. Available: ${component.examples.map((example) => example.name).join(", ")}`
-            })
-          }
-        ],
-        isError: true
-      };
-    }
-  }
-  if (maxExamples && maxExamples > 0) {
-    examples = examples.slice(0, maxExamples);
-  }
-  const truncateCode = (code) => {
-    if (!maxLines || maxLines <= 0) {
-      return { code, truncated: false, remainingLines: 0 };
-    }
-    const lines = code.split("\n");
-    if (lines.length <= maxLines) {
-      return { code, truncated: false, remainingLines: 0 };
-    }
-    return {
-      code: lines.slice(0, maxLines).join("\n"),
-      truncated: true,
-      remainingLines: lines.length - maxLines
-    };
-  };
-  const renderedExamples = examples.map((example) => ({
-    ...example.code ? truncateCode(example.code) : { truncated: false, remainingLines: 0 },
-    variant: example.name,
-    description: example.description,
-    code: example.code ? truncateCode(example.code).code : `<${component.name} />`,
-    ...example.code ? {} : {
-      note: "No code example provided. Refer to props for customization."
-    }
-  }));
-  const propsReference = Object.entries(component.props ?? {}).map(
-    ([propName, prop]) => ({
-      name: propName,
-      type: prop.type,
-      required: prop.required,
-      default: prop.default,
-      description: prop.description,
-      values: prop.values
-    })
-  );
-  const propConstraints = Object.entries(component.props ?? {}).filter(
-    ([, prop]) => Boolean(prop.constraints && prop.constraints.length > 0)
-  ).map(([propName, prop]) => ({
-    prop: propName,
-    constraints: prop.constraints
-  }));
-  const fullResult = {
-    meta: {
-      id: component.id,
-      name: component.name,
-      description: component.description,
-      category: component.category,
-      status: component.status,
-      publicRef: component.publicRef,
-      publicSlug: component.publicSlug,
-      isCanonical: component.isCanonical ?? false,
-      tier: component.tier
-    },
-    props: propsReference,
-    examples: {
-      import: `import { ${component.name} } from '${pkgName}';`,
-      code: renderedExamples
-    },
-    relations: component.relations,
-    compoundChildren: component.compoundChildren,
-    guidance: {
-      when: getGuidanceWhen(component),
-      whenNot: getGuidanceWhenNot(component),
-      guidelines: component.guidance.guidelines,
-      accessibility: component.guidance.accessibility,
-      usageGuidance: component.guidance.usageGuidance,
-      dos: component.guidance.dos,
-      donts: component.guidance.donts,
-      patterns: component.guidance.patterns,
-      propConstraints,
-      alternatives: component.relations?.filter((relation) => relation.relationship === "alternative").map((relation) => ({
-        component: relation.componentName,
-        note: relation.note
-      })) ?? []
-    },
-    metadata: component.metadata,
-    source: await getSourceCode(component, ctx.config.projectRoot)
-  };
-  const aliasMap = { usage: "guidance" };
-  const resolvedFields = fields?.map((field) => {
-    const parts = field.split(".");
-    if (aliasMap[parts[0]]) parts[0] = aliasMap[parts[0]];
-    return parts.join(".");
-  });
-  let result2;
-  if (verbosity === "compact" && !resolvedFields?.length) {
-    result2 = {
-      meta: fullResult.meta,
-      propsSummary: component.propsSummary,
-      metadata: component.metadata
-    };
-  } else if (verbosity === "full") {
-    result2 = resolvedFields && resolvedFields.length > 0 ? projectFields(fullResult, resolvedFields) : fullResult;
-  } else if (resolvedFields && resolvedFields.length > 0) {
-    result2 = projectFields(fullResult, resolvedFields);
-  } else {
-    const { source: _source, ...withoutSource } = fullResult;
-    result2 = withoutSource;
-  }
-  return {
-    content: [{ type: "text", text: JSON.stringify(result2) }]
-  };
-};
-
-// src/tools/blocks.ts
-var blocksHandler = async (args, ctx) => {
-  const blockName = args?.name;
-  const search2 = args?.search?.toLowerCase() ?? void 0;
-  const component = args?.component?.toLowerCase() ?? void 0;
-  const category = args?.category?.toLowerCase() ?? void 0;
-  const blocksLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 50) : void 0;
-  const allBlocks = listBlocks(ctx.data.snapshot);
-  if (allBlocks.length === 0) {
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          total: 0,
-          blocks: [],
-          hint: `No composition blocks found. Blocks are reusable patterns showing how components wire together (e.g., "Login Form", "Settings Page"). Create .block.ts files and run \`${BRAND.cliCommand} build\`.`
-        })
-      }]
-    };
-  }
-  let filtered = allBlocks;
-  if (blockName) {
-    filtered = filtered.filter(
-      (b) => b.name.toLowerCase() === blockName.toLowerCase()
-    );
-    if (filtered.length === 0) {
-      const allBlockNames = allBlocks.map((b) => b.name);
-      const closest = findClosestMatch(blockName, allBlockNames);
-      const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-      throw new Error(`Block "${blockName}" not found.${suggestion} Use ${ctx.toolNames.blocks} to see available blocks.`);
-    }
-  }
-  if (search2) {
-    if (ctx.indexes.blockIndex) {
-      const ranked = searchBlocks(search2, ctx.indexes.blockIndex, 50);
-      const rankedNames = new Set(ranked.map((r) => r.name.toLowerCase()));
-      filtered = filtered.filter((b) => rankedNames.has(b.name.toLowerCase()));
-      filtered.sort((a, b) => {
-        const aIdx = ranked.findIndex((r) => r.name.toLowerCase() === a.name.toLowerCase());
-        const bIdx = ranked.findIndex((r) => r.name.toLowerCase() === b.name.toLowerCase());
-        return (aIdx === -1 ? Infinity : aIdx) - (bIdx === -1 ? Infinity : bIdx);
-      });
-    } else {
-      filtered = filtered.filter((b) => {
-        const haystack = [
-          b.name,
-          b.description,
-          ...b.tags ?? [],
-          ...b.components,
-          b.category
-        ].join(" ").toLowerCase();
-        return haystack.includes(search2);
-      });
-    }
-  }
-  if (component) {
-    filtered = filtered.filter(
-      (b) => b.components.some((c) => c.toLowerCase() === component)
-    );
-  }
-  if (category) {
-    filtered = filtered.filter(
-      (b) => b.category.toLowerCase() === category
-    );
-  }
-  const blocksUseIcons = filtered.some(
-    (b) => b.components.some((c) => c === "Icon") || b.code && /\bIcon\b/.test(b.code)
-  );
-  const iconHint = blocksUseIcons ? "Icon components in block code are from @phosphor-icons/react. Import them as: import { IconName } from '@phosphor-icons/react';" : void 0;
-  if (blocksLimit !== void 0) {
-    filtered = filtered.slice(0, blocksLimit);
-  }
-  const verbosity = args?.verbosity ?? "standard";
-  const blocksWithImports = await Promise.all(filtered.map(async (b) => {
-    const imports = await buildImportStatements(
-      b.components,
-      async (componentName) => ctx.resolvePackageName(componentName)
-    );
-    const base = {
-      name: b.name,
-      description: b.description,
-      category: b.category,
-      components: b.components,
-      tags: b.tags,
-      import: imports.join("\n"),
-      imports
-    };
-    if (verbosity === "compact") return base;
-    if (verbosity === "full") return { ...base, code: b.code };
-    const codeLines = b.code.split("\n");
-    const code = codeLines.length > 30 ? codeLines.slice(0, 20).join("\n") + "\n// ... truncated (" + codeLines.length + " lines total)" : b.code;
-    return { ...base, code };
-  }));
-  return {
-    content: [{
-      type: "text",
-      text: JSON.stringify({
-        total: blocksWithImports.length,
-        blocks: blocksWithImports,
-        ...iconHint && { iconHint },
-        ...blocksWithImports.length === 0 && allBlocks.length > 0 && {
-          hint: "No blocks matching your query. Try broader search terms."
-        }
-      })
-    }]
-  };
-};
-
-// src/tools/tokens.ts
-var TOKEN_CATEGORY_ALIASES = {
-  colors: ["color", "colors", "accent", "background", "foreground", "theme"],
-  spacing: ["spacing", "space", "spaces", "padding", "margin", "gap", "inset"],
-  typography: ["typography", "type", "font", "fonts", "letter", "line-height"],
-  surfaces: ["surface", "surfaces", "canvas"],
-  shadows: ["shadow", "shadows", "elevation"],
-  radius: ["radius", "radii", "corner", "corners", "rounded", "rounding"],
-  borders: ["border", "borders", "stroke", "outline"],
-  text: ["text", "copy", "content"],
-  focus: ["focus", "ring", "focus-ring"],
-  layout: ["layout", "container", "grid", "breakpoint"],
-  code: ["code"],
-  "component-sizing": ["component-sizing", "sizing", "size", "sizes"]
-};
-function normalizeCategoryValue(value) {
-  const normalized = value?.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
-  return normalized && normalized.length > 0 ? normalized : void 0;
-}
-function resolveCategoryKeys(categories, requestedCategory) {
-  const normalized = normalizeCategoryValue(requestedCategory);
-  if (!normalized) {
-    return Object.keys(categories);
-  }
-  const keys = Object.keys(categories);
-  const exactMatches = keys.filter((key) => normalizeCategoryValue(key) === normalized);
-  if (exactMatches.length > 0) {
-    return exactMatches;
-  }
-  const canonical = Object.entries(TOKEN_CATEGORY_ALIASES).find(
-    ([categoryName, aliases]) => categoryName === normalized || aliases.includes(normalized)
-  );
-  if (canonical) {
-    const aliases = [canonical[0], ...canonical[1]];
-    const aliasMatches = keys.filter((key) => {
-      const normalizedKey = normalizeCategoryValue(key) ?? "";
-      return aliases.some((alias) => normalizedKey.includes(alias));
-    });
-    if (aliasMatches.length > 0) {
-      return aliasMatches;
-    }
-  }
-  return keys.filter((key) => (normalizeCategoryValue(key) ?? "").includes(normalized));
-}
-function canonicalizeCategory(category, tokens) {
-  const normalizedCategory = normalizeCategoryValue(category);
-  const candidates = [
-    normalizedCategory,
-    ...tokens.flatMap((token) => [
-      normalizeCategoryValue(token.category),
-      normalizeCategoryValue(token.path?.[0]),
-      normalizeCategoryValue(token.name.split(/[.:/-]/)[0])
-    ])
-  ].filter(Boolean);
-  for (const candidate of candidates) {
-    for (const [canonical, aliases] of Object.entries(TOKEN_CATEGORY_ALIASES)) {
-      if (candidate === canonical || aliases.some(
-        (alias) => candidate === alias || candidate.includes(alias) || alias.includes(candidate)
-      )) {
-        return canonical;
-      }
-    }
-  }
-  return normalizedCategory || "other";
-}
-function normalizeTokenCategories(categories) {
-  const normalized = {};
-  for (const [category, tokens] of Object.entries(categories)) {
-    const canonical = canonicalizeCategory(category, tokens);
-    if (!normalized[canonical]) normalized[canonical] = [];
-    normalized[canonical].push(
-      ...tokens.map((token) => ({
-        ...token,
-        category: canonical
-      }))
-    );
-  }
-  for (const tokens of Object.values(normalized)) {
-    tokens.sort((a, b) => a.name.localeCompare(b.name));
-  }
-  return normalized;
-}
-var tokensHandler = async (args, ctx) => {
-  const category = args?.category;
-  const search2 = args?.search?.toLowerCase() ?? void 0;
-  const tokensLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 100) : search2 ? 25 : void 0;
-  const tokenData = ctx.data.tokens;
-  if (!tokenData || tokenData.total === 0) {
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          total: 0,
-          categories: {},
-          hint: `No design tokens found. Add a tokens.include pattern to your ${BRAND.configFile} and run \`${BRAND.cliCommand} build\`.`
-        })
-      }]
-    };
-  }
-  const normalizedCategories = normalizeTokenCategories(tokenData.categories);
-  let filteredCategories = {};
-  let filteredTotal = 0;
-  const resolvedCategoryKeys = resolveCategoryKeys(normalizedCategories, category);
-  const friendlyCategories = Object.keys(TOKEN_CATEGORY_ALIASES);
-  const searchMatchesCategory = search2 ? resolveCategoryKeys(normalizedCategories, search2) : [];
-  for (const [cat, tokens] of Object.entries(normalizedCategories)) {
-    if (category && !resolvedCategoryKeys.includes(cat)) continue;
-    let filtered = tokens;
-    if (search2) {
-      if (searchMatchesCategory.includes(cat)) {
-        filtered = tokens;
-      } else {
-        filtered = tokens.filter(
-          (t) => t.name.toLowerCase().includes(search2) || t.description && t.description.toLowerCase().includes(search2) || (normalizeCategoryValue(cat) ?? "").includes(search2) || t.value && t.value.toLowerCase().includes(search2) || t.path && t.path.join(" ").toLowerCase().includes(search2)
-        );
-      }
-    }
-    if (filtered.length > 0) {
-      filteredCategories[cat] = filtered;
-      filteredTotal += filtered.length;
-    }
-  }
-  if (tokensLimit !== void 0) {
-    const limited = limitTokensPerCategory(filteredCategories, tokensLimit);
-    filteredCategories = limited.categories;
-    filteredTotal = limited.total;
-  }
-  let hint;
-  if (filteredTotal === 0) {
-    if (category && search2) {
-      const categoryTotal = resolvedCategoryKeys.reduce(
-        (sum, key) => sum + (normalizedCategories[key]?.length ?? 0),
-        0
-      );
-      hint = categoryTotal > 0 ? `No tokens matching "${search2}" in category "${category}" (${categoryTotal} tokens in this category). Try a broader search or remove the search term.` : `Category "${category}" not found. Try categories like: ${friendlyCategories.join(", ")}.`;
-    } else if (search2) {
-      hint = `No tokens matching "${search2}". Try categories like: ${friendlyCategories.join(", ")}.`;
-    } else if (category) {
-      hint = `Category "${category}" not found. Try categories like: ${friendlyCategories.join(", ")}.`;
-    }
-  } else if (!category && !search2) {
-    hint = `Use var(--token-name) in your CSS/styles. Filter by category or search to narrow results.`;
-  }
-  return {
-    content: [{
-      type: "text",
-      text: JSON.stringify({
-        prefix: tokenData.prefix,
-        total: filteredTotal,
-        totalAvailable: tokenData.total,
-        categories: filteredCategories,
-        ...hint && { hint },
-        ...!category && !search2 && {
-          availableCategories: Object.entries(normalizedCategories).map(([cat, tokens]) => ({
-            category: cat,
-            count: tokens.length
-          }))
-        }
-      })
-    }]
-  };
-};
-
-// src/service.ts
-var DEFAULT_ENDPOINTS = {
-  render: "/fragments/render",
-  compare: "/fragments/compare",
-  fix: "/fragments/fix",
-  a11y: "/fragments/a11y"
-};
-async function renderComponent(viewerUrl, request, endpoints) {
-  const renderUrl = `${viewerUrl}${endpoints?.render ?? DEFAULT_ENDPOINTS.render}`;
-  const response = await fetch(renderUrl, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      component: request.component,
-      props: request.props ?? {},
-      variant: request.variant,
-      viewport: request.viewport ?? { width: 800, height: 600 }
-    })
-  });
-  return await response.json();
-}
-async function compareComponent(viewerUrl, request, endpoints) {
-  const compareUrl = `${viewerUrl}${endpoints?.compare ?? DEFAULT_ENDPOINTS.compare}`;
-  const response = await fetch(compareUrl, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(request)
-  });
-  return await response.json();
-}
-async function fixComponent(viewerUrl, request, endpoints) {
-  const fixUrl = `${viewerUrl}${endpoints?.fix ?? DEFAULT_ENDPOINTS.fix}`;
-  const response = await fetch(fixUrl, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(request)
-  });
-  return await response.json();
-}
-async function auditComponent(viewerUrl, request, endpoints) {
-  const a11yUrl = `${viewerUrl}${endpoints?.a11y ?? DEFAULT_ENDPOINTS.a11y}`;
-  const response = await fetch(a11yUrl, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      component: request.component,
-      variant: request.variant,
-      standard: request.standard,
-      includeFixPatches: request.includeFixPatches
-    })
-  });
-  const raw = await response.json();
-  if (raw.error) {
-    return {
-      component: request.component,
-      results: [],
-      score: 0,
-      aaPercent: 0,
-      aaaPercent: 0,
-      passed: false,
-      standard: request.standard ?? "AA",
-      error: raw.error
-    };
-  }
-  const results = raw.results ?? [];
-  const standard = request.standard ?? "AA";
-  let totalCritical = 0;
-  let totalSerious = 0;
-  let totalModerate = 0;
-  let totalMinor = 0;
-  for (const r of results) {
-    totalCritical += r.summary.critical;
-    totalSerious += r.summary.serious;
-    totalModerate += r.summary.moderate;
-    totalMinor += r.summary.minor;
-  }
-  const deductions = totalCritical * 10 + totalSerious * 5 + totalModerate * 2 + totalMinor * 1;
-  const score = Math.max(0, 100 - deductions);
-  const variantCount = results.length;
-  const aaPassCount = results.filter((r) => {
-    const critical = r.summary.critical;
-    const serious = r.summary.serious;
-    return critical === 0 && serious === 0;
-  }).length;
-  const aaaPassCount = results.filter((r) => {
-    const total = r.summary.critical + r.summary.serious + r.summary.moderate + r.summary.minor;
-    return total === 0;
-  }).length;
-  const totalPasses = results.reduce((sum, r) => sum + r.passes, 0);
-  const totalViolations = totalCritical + totalSerious + totalModerate + totalMinor;
-  const emptyAudit = results.length > 0 && totalPasses === 0 && totalViolations === 0;
-  const aaPercent = variantCount > 0 ? Math.round(aaPassCount / variantCount * 100) : 100;
-  const aaaPercent = variantCount > 0 ? Math.round(aaaPassCount / variantCount * 100) : 100;
-  const aaPass = !emptyAudit && totalCritical === 0 && totalSerious === 0;
-  const aaaPass = !emptyAudit && totalViolations === 0;
-  const passed = standard === "AAA" ? aaaPass : aaPass;
-  return {
-    component: request.component,
-    results,
-    score: emptyAudit ? 0 : score,
-    aaPercent: emptyAudit ? 0 : aaPercent,
-    aaaPercent: emptyAudit ? 0 : aaaPercent,
-    ...emptyAudit && { emptyAudit },
-    passed,
-    standard
-  };
-}
-
-// src/tools/render.ts
-var NO_VIEWER_MSG = "This tool requires a running dev server. Add --viewer-url http://localhost:PORT to this server's config args. Start the viewer with 'fragments dev' in your component library directory.";
-var renderHandler = async (args, ctx) => {
-  const componentName = args?.component;
-  const variantName = args?.variant;
-  const props = args?.props ?? {};
-  const viewport = args?.viewport;
-  const figmaUrl = args?.figmaUrl;
-  const threshold = args?.threshold ?? (figmaUrl ? 1 : ctx.config.threshold ?? DEFAULTS.diffThreshold);
-  if (!componentName) {
-    return {
-      content: [{ type: "text", text: "Error: component name is required" }],
-      isError: true
-    };
-  }
-  {
-    const component = findComponentByName(ctx.data.snapshot, componentName);
-    if (!component) {
-      const allNames = componentNames(ctx.data.snapshot);
-      const closest = findClosestMatch(componentName, allNames);
-      const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-      throw new Error(`Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`);
+    try {
+      const content = readFileSync(configPath, "utf-8");
+      return JSON.parse(content);
+    } catch (e) {
+      throw new Error(`Failed to parse ${configPath}: ${e instanceof Error ? e.message : String(e)}`);
     }
   }
-  const viewerUrl = ctx.config.viewerUrl;
-  if (!viewerUrl) {
-    return {
-      content: [{
-        type: "text",
-        text: NO_VIEWER_MSG
-      }],
-      isError: true
-    };
-  }
-  if (figmaUrl) {
+  const pkgPath = join(projectRoot, "package.json");
+  if (existsSync(pkgPath)) {
     try {
-      const result2 = await compareComponent(viewerUrl, {
-        component: componentName,
-        variant: variantName,
-        props,
-        figmaUrl,
-        threshold
-      }, ctx.config.fileConfig?.endpoints);
-      if (result2.error) {
-        return {
-          content: [{
-            type: "text",
-            text: `Compare error: ${result2.error}${result2.suggestion ? `
-Suggestion: ${result2.suggestion}` : ""}`
-          }],
-          isError: true
-        };
-      }
-      const content = [];
-      const summaryText = result2.match ? `MATCH: ${componentName} matches Figma design (${result2.diffPercentage}% diff, threshold: ${result2.threshold}%)` : `MISMATCH: ${componentName} differs from Figma design by ${result2.diffPercentage}% (threshold: ${result2.threshold}%)`;
-      content.push({ type: "text", text: summaryText });
-      if (result2.diff && !result2.match) {
-        content.push({
-          type: "image",
-          data: result2.diff.replace("data:image/png;base64,", ""),
-          mimeType: "image/png"
-        });
-        content.push({
-          type: "text",
-          text: `Diff image above shows visual differences (red highlights). Changed regions: ${result2.changedRegions?.length ?? 0}`
-        });
-      }
-      content.push({
-        type: "text",
-        text: JSON.stringify({
-          match: result2.match,
-          diffPercentage: result2.diffPercentage,
-          threshold: result2.threshold,
-          figmaUrl: result2.figmaUrl,
-          changedRegions: result2.changedRegions
-        })
-      });
-      return { content };
-    } catch (error) {
-      return {
-        content: [{
-          type: "text",
-          text: `Failed to compare component: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running and FIGMA_ACCESS_TOKEN is set.`
-        }],
-        isError: true
-      };
+      const content = readFileSync(pkgPath, "utf-8");
+      const pkg = JSON.parse(content);
+      if (pkg.dsMcp) return pkg.dsMcp;
+    } catch {
     }
   }
+  return null;
+}
+
+// src/server.ts
+import { buildMcpTools, buildToolNames, MCP_TOOL_DEFINITIONS } from "@fragments-sdk/context/mcp-tools";
+
+// src/version.ts
+import { readFileSync as readFileSync2 } from "fs";
+function readPackageVersion() {
   try {
-    const result2 = await renderComponent(viewerUrl, {
-      component: componentName,
-      props,
-      variant: variantName,
-      viewport: viewport ?? { width: 800, height: 600 }
-    }, ctx.config.fileConfig?.endpoints);
-    if (result2.error) {
-      return {
-        content: [{ type: "text", text: `Render error: ${result2.error}` }],
-        isError: true
-      };
-    }
-    return {
-      content: [
-        {
-          type: "image",
-          data: result2.screenshot.replace("data:image/png;base64,", ""),
-          mimeType: "image/png"
-        },
-        {
-          type: "text",
-          text: `Successfully rendered ${componentName}${variantName ? ` (variant: "${variantName}")` : ""}${Object.keys(props).length > 0 ? ` with props: ${JSON.stringify(props)}` : ""}`
-        }
-      ]
-    };
-  } catch (error) {
-    return {
-      content: [{
-        type: "text",
-        text: `Failed to render component: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
-      }],
-      isError: true
-    };
+    const raw = readFileSync2(new URL("../package.json", import.meta.url), "utf-8");
+    const pkg = JSON.parse(raw);
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
   }
-};
+}
+var MCP_SERVER_VERSION = readPackageVersion();
 
-// src/tools/fix.ts
-var NO_VIEWER_MSG2 = "This tool requires a running dev server. Add --viewer-url http://localhost:PORT to this server's config args. Start the viewer with 'fragments dev' in your component library directory.";
-var fixHandler = async (args, ctx) => {
-  const componentName = args?.component;
-  const variantName = args?.variant ?? void 0;
-  const fixType = args?.fixType ?? "all";
-  if (!componentName) {
-    throw new Error("component is required");
-  }
-  const fragment = findComponentByName(ctx.data.snapshot, componentName);
-  if (!fragment) {
-    const allNames = componentNames(ctx.data.snapshot);
-    const closest = findClosestMatch(componentName, allNames);
-    const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-    throw new Error(`Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`);
-  }
-  const viewerUrl = ctx.config.viewerUrl;
-  if (!viewerUrl) {
-    return {
-      content: [{
-        type: "text",
-        text: NO_VIEWER_MSG2
-      }],
-      isError: true
-    };
+// src/catalog-meta.ts
+function getCatalogMeta(data) {
+  const rawUpdatedAt = data.validateFixContext?.updatedAt ?? data.snapshot.metadata.updatedAt;
+  const updatedAt = typeof rawUpdatedAt === "number" ? new Date(rawUpdatedAt).toISOString() : rawUpdatedAt;
+  return {
+    catalogRevision: data.validateFixContext?.catalogRevision ?? data.snapshot.metadata.revision,
+    updatedAt
+  };
+}
+
+// src/token-suggestions.ts
+function propertyFamilyFor(property, value) {
+  const prop = property.toLowerCase().trim();
+  const normalizedValue = value?.toLowerCase().trim();
+  if (prop.includes("shadow")) return "shadow";
+  if (prop.includes("z-index")) return "z-index";
+  if (prop.includes("transition") || prop.includes("duration") || prop.includes("animation")) {
+    return "duration";
+  }
+  if (prop.includes("font") || prop.includes("line-height") || prop === "letter-spacing") {
+    return "typography";
   }
-  try {
-    const result2 = await fixComponent(viewerUrl, {
-      component: componentName,
-      variant: variantName,
-      fixType
-    }, ctx.config.fileConfig?.endpoints);
-    if (result2.error) {
-      return {
-        content: [{
-          type: "text",
-          text: `Fix generation error: ${result2.error}`
-        }],
-        isError: true
-      };
-    }
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          component: componentName,
-          variant: variantName ?? "all",
-          fixType,
-          patches: result2.patches,
-          summary: result2.summary,
-          patchCount: result2.patches.length,
-          nextStep: result2.patches.length > 0 ? `Apply patches using your editor or \`patch\` command, then run ${ctx.toolNames.render} to confirm fixes.` : void 0
-        })
-      }]
-    };
-  } catch (error) {
-    return {
-      content: [{
-        type: "text",
-        text: `Failed to generate fixes: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
-      }],
-      isError: true
-    };
+  if (prop.includes("radius")) return "radius";
+  if (prop.endsWith("border-width") || prop === "border-width" || prop === "outline-width" || prop === "stroke-width") {
+    return "border-width";
   }
-};
-
-// src/tools/a11y.ts
-var NO_VIEWER_MSG3 = "This tool requires a running dev server. Add --viewer-url http://localhost:PORT to this server's config args. Start the viewer with 'fragments dev' in your component library directory.";
-var a11yHandler = async (args, ctx) => {
-  const componentName = args?.component;
-  const variantName = args?.variant ?? void 0;
-  const standard = args?.standard ?? "AA";
-  const includeFixPatches = args?.includeFixPatches ?? false;
-  if (!componentName) {
-    throw new Error("component is required");
-  }
-  {
-    const fragment = findComponentByName(ctx.data.snapshot, componentName);
-    if (!fragment) {
-      const allNames = componentNames(ctx.data.snapshot);
-      const closest = findClosestMatch(componentName, allNames);
-      const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-      throw new Error(`Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`);
-    }
+  if (prop.includes("color") || prop === "background" || prop.startsWith("background-") || prop === "fill" || prop === "stroke" || prop === "caret-color" || prop === "accent-color" || (prop === "border" || prop === "outline") && normalizedValue && looksLikeColor(normalizedValue)) {
+    return "color";
   }
-  const viewerUrl = ctx.config.viewerUrl;
-  if (!viewerUrl) {
-    return {
-      content: [{
-        type: "text",
-        text: NO_VIEWER_MSG3
-      }],
-      isError: true
-    };
+  if (prop === "margin" || prop.startsWith("margin-") || prop === "padding" || prop.startsWith("padding-") || prop === "gap" || prop === "row-gap" || prop === "column-gap" || prop === "inset" || prop === "top" || prop === "right" || prop === "bottom" || prop === "left" || prop.endsWith("width") || prop.endsWith("height")) {
+    return "spacing";
   }
-  try {
-    const result2 = await auditComponent(viewerUrl, {
-      component: componentName,
-      variant: variantName,
-      standard,
-      includeFixPatches
-    }, ctx.config.fileConfig?.endpoints);
-    if (result2.error) {
-      return {
-        content: [{
-          type: "text",
-          text: `A11y audit error: ${result2.error}`
-        }],
-        isError: true
-      };
-    }
-    let nextStep;
-    if (result2.emptyAudit) {
-      nextStep = `No testable elements found for ${variantName ? `variant "${variantName}"` : componentName}. The variant may not exist or renders no accessible content. Check available variants with ${ctx.toolNames.inspect}("${componentName}").`;
-    } else if (result2.passed) {
-      nextStep = 'All accessibility checks passed. Consider running with standard: "AAA" for enhanced compliance.';
-    } else {
-      nextStep = `Fix the violations above, then re-run ${ctx.toolNames.a11y} to verify. Use ${ctx.toolNames.fix} for automated fixes.`;
-    }
+  return "other";
+}
+function suggestToken(input) {
+  const family = propertyFamilyFor(input.property, input.value);
+  const limit = Math.min(Math.max(input.limit ?? 5, 1), 10);
+  const candidates = input.tokens ? scoreCandidates(input.tokens, family, input) : [];
+  const top = candidates.slice(0, limit).map(
+    (candidate) => presentCandidate(candidate, input.tokens)
+  );
+  const meta = {
+    propertyFamily: family,
+    catalogRevision: input.catalogRevision,
+    updatedAt: input.updatedAt,
+    candidateCount: candidates.length
+  };
+  if (family === "other") {
     return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          component: componentName,
-          variant: variantName ?? "all",
-          standard,
-          totalViolations: result2.results.reduce((sum, r) => sum + r.summary.total, 0),
-          variantsPassingAA: `${result2.aaPercent}%`,
-          variantsPassingAAA: `${result2.aaaPercent}%`,
-          passed: result2.passed,
-          ...result2.emptyAudit && { emptyAudit: true },
-          results: result2.results,
-          nextStep
-        })
-      }]
+      alternatives: [],
+      noSuggestion: true,
+      noSuggestionReason: `No token family is known for CSS property "${input.property}".`,
+      _meta: meta
     };
-  } catch (error) {
+  }
+  if (!input.tokens || input.tokens.total === 0) {
     return {
-      content: [{
-        type: "text",
-        text: `Failed to audit component: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
-      }],
-      isError: true
+      alternatives: [],
+      noSuggestion: true,
+      noSuggestionReason: "No design tokens are available in the active catalog.",
+      _meta: meta
     };
   }
-};
-
-// src/graph-handler.ts
-import {
-  ComponentGraphEngine,
-  deserializeGraph
-} from "@fragments-sdk/context/graph";
-function handleGraphTool(args, serializedGraph, blocks, componentNames2) {
-  if (!serializedGraph) {
+  if (top.length === 0) {
     return {
-      text: JSON.stringify({
-        error: "No graph data available. Run `fragments build` to generate the component graph.",
-        hint: "The graph is built automatically during `fragments build` and embedded in fragments.json."
-      }),
-      isError: true
+      alternatives: [],
+      noSuggestion: true,
+      noSuggestionReason: `No ${family} tokens are available for CSS property "${input.property}".`,
+      _meta: meta
     };
   }
-  const graph = deserializeGraph(serializedGraph);
-  const blockData = blocks ? Object.fromEntries(
-    Object.entries(blocks).map(([k, v]) => [k, { components: v.components }])
-  ) : void 0;
-  const engine = new ComponentGraphEngine(graph, blockData);
-  const edgeTypes = args.edgeTypes;
-  switch (args.mode) {
-    case "health": {
-      const health = engine.getHealth();
-      const blockCount = blocks ? Object.keys(blocks).length : 0;
-      return {
-        text: JSON.stringify({
-          mode: "health",
-          ...health,
-          ...health.compositionCoverage === 0 && blockCount === 0 && {
-            compositionNote: "No composition blocks defined yet \u2014 compositionCoverage will increase as blocks are added"
-          },
-          summary: `${health.nodeCount} components, ${health.edgeCount} edges, ${health.connectedComponents.length} island(s), ${health.orphans.length} orphan(s), ${health.compositionCoverage}% in blocks`
-        })
-      };
-    }
-    case "dependencies": {
-      if (!args.component) {
-        return { text: JSON.stringify({ error: "component is required for dependencies mode" }), isError: true };
-      }
-      if (!engine.hasNode(args.component)) {
-        const closest = componentNames2 ? findClosestMatch(args.component, componentNames2) : null;
-        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
-      }
-      const deps = engine.dependencies(args.component, edgeTypes);
-      return {
-        text: JSON.stringify({
-          mode: "dependencies",
-          component: args.component,
-          count: deps.length,
-          dependencies: deps.map((e) => ({
-            component: e.target,
-            type: e.type,
-            weight: e.weight,
-            note: e.note,
-            provenance: e.provenance
-          }))
-        })
-      };
-    }
-    case "dependents": {
-      if (!args.component) {
-        return { text: JSON.stringify({ error: "component is required for dependents mode" }), isError: true };
-      }
-      if (!engine.hasNode(args.component)) {
-        const closest = componentNames2 ? findClosestMatch(args.component, componentNames2) : null;
-        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
-      }
-      const deps = engine.dependents(args.component, edgeTypes);
-      return {
-        text: JSON.stringify({
-          mode: "dependents",
-          component: args.component,
-          count: deps.length,
-          dependents: deps.map((e) => ({
-            component: e.source,
-            type: e.type,
-            weight: e.weight,
-            note: e.note,
-            provenance: e.provenance
-          }))
-        })
-      };
-    }
-    case "impact": {
-      if (!args.component) {
-        return { text: JSON.stringify({ error: "component is required for impact mode" }), isError: true };
-      }
-      if (!engine.hasNode(args.component)) {
-        const closest = componentNames2 ? findClosestMatch(args.component, componentNames2) : null;
-        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
-      }
-      const result2 = engine.impact(args.component, args.maxDepth ?? 3);
-      return {
-        text: JSON.stringify({
-          mode: "impact",
-          ...result2,
-          summary: `Changing ${args.component} affects ${result2.totalAffected} component(s) and ${result2.affectedBlocks.length} block(s)`
-        })
-      };
-    }
-    case "path": {
-      if (!args.component || !args.target) {
-        return { text: JSON.stringify({ error: "component and target are required for path mode" }), isError: true };
-      }
-      const result2 = engine.path(args.component, args.target);
-      return {
-        text: JSON.stringify({
-          mode: "path",
-          from: args.component,
-          to: args.target,
-          ...result2,
-          edges: result2.edges.map((e) => ({
-            source: e.source,
-            target: e.target,
-            type: e.type
-          }))
-        })
-      };
-    }
-    case "composition": {
-      if (!args.component) {
-        return { text: JSON.stringify({ error: "component is required for composition mode" }), isError: true };
-      }
-      if (!engine.hasNode(args.component)) {
-        const closest = componentNames2 ? findClosestMatch(args.component, componentNames2) : null;
-        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
-      }
-      const tree = engine.composition(args.component);
-      return {
-        text: JSON.stringify({
-          mode: "composition",
-          ...tree
-        })
-      };
-    }
-    case "alternatives": {
-      if (!args.component) {
-        return { text: JSON.stringify({ error: "component is required for alternatives mode" }), isError: true };
-      }
-      if (!engine.hasNode(args.component)) {
-        const closest = componentNames2 ? findClosestMatch(args.component, componentNames2) : null;
-        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
+  const [recommended, ...alternatives] = top;
+  return {
+    recommended,
+    alternatives,
+    _meta: meta
+  };
+}
+function scoreCandidates(tokenData, family, input) {
+  if (family === "other") return [];
+  const value = normalizeComparableValue(input.value);
+  const flatTokens = tokenData.flat.length > 0 ? tokenData.flat : Object.values(tokenData.categories).flat();
+  const familyTokens = flatTokens.filter((token) => !isGarbageToken(token)).map((token) => ({ token, family: tokenFamily(token) })).filter((entry) => entry.family === family);
+  const scored = familyTokens.map(({ token }) => {
+    const tokenValue = normalizeComparableValue(token.value);
+    let score = 50;
+    let reason = "family-match";
+    if (value && tokenValue && value === tokenValue) {
+      score += 60;
+      reason = "exact-value-match";
+    } else if (value && tokenValue && family !== "color") {
+      const distanceScore = lengthDistanceScore(value, tokenValue);
+      if (distanceScore > 0) {
+        score += distanceScore;
+        reason = "nearest-neighbor";
       }
-      const alts = engine.alternatives(args.component);
-      return {
-        text: JSON.stringify({
-          mode: "alternatives",
-          component: args.component,
-          count: alts.length,
-          alternatives: alts
-        })
-      };
-    }
-    case "islands": {
-      const islands = engine.islands();
-      return {
-        text: JSON.stringify({
-          mode: "islands",
-          count: islands.length,
-          islands: islands.map((island, i) => ({
-            id: i + 1,
-            size: island.length,
-            components: island
-          }))
-        })
-      };
     }
-    default:
-      return {
-        text: JSON.stringify({
-          error: `Unknown mode: "${args.mode}". Valid modes: dependencies, dependents, impact, path, composition, alternatives, islands, health`
-        }),
-        isError: true
-      };
-  }
+    score += nameRelevanceScore(token, input.property, input.context);
+    return { token, family, score, reason };
+  });
+  return scored.filter((candidate) => candidate.score > 0).sort((a, b) => b.score - a.score || a.token.name.localeCompare(b.token.name));
 }
-
-// src/tools/graph.ts
-var graphHandler = async (args, ctx) => {
-  const graphArgs = {
-    mode: args?.mode ?? "health",
-    component: args?.component,
-    target: args?.target,
-    edgeTypes: args?.edgeTypes,
-    maxDepth: args?.maxDepth
-  };
-  const data = ctx.data;
-  const allNames = componentNames(data.snapshot);
-  const result2 = handleGraphTool(
-    graphArgs,
-    data.graph,
-    data.blocks,
-    allNames
-  );
-  if (result2.isError) {
-    return {
-      content: [{ type: "text", text: result2.text }],
-      isError: true
-    };
-  }
+function presentCandidate(candidate, tokenData) {
+  const cssVar = cssVarForToken(candidate.token);
+  const resolvedValue = resolvedValueForToken(candidate.token);
+  const confidence = candidate.score >= 105 ? "high" : candidate.score >= 65 ? "medium" : "low";
   return {
-    content: [{ type: "text", text: result2.text }]
+    name: dottedNameForToken(candidate.token, tokenData),
+    ...cssVar && { cssVar },
+    ...cssVar && {
+      cssValue: resolvedValue ? `var(${cssVar}, ${resolvedValue})` : `var(${cssVar})`
+    },
+    ...resolvedValue && { resolvedValue },
+    confidence,
+    reason: candidate.reason
   };
-};
+}
+function isGarbageToken(token) {
+  const value = token.value?.trim();
+  if (!value) return false;
+  if (value.includes("#{") || value.includes("$")) return true;
+  if (/^\$[\w-]+/.test(token.name)) return true;
+  return false;
+}
+function tokenFamily(token) {
+  const haystack = [
+    token.type,
+    token.category,
+    ...token.path ?? [],
+    token.name
+  ].filter(Boolean).join(" ").toLowerCase();
+  if (/\b(color|colour|background|foreground|surface|palette)\b/.test(haystack)) {
+    return "color";
+  }
+  if (/\b(radius|radii|rounded|corner)\b/.test(haystack)) return "radius";
+  if (/\b(border-width|border width|stroke-width|stroke width)\b/.test(haystack)) {
+    return "border-width";
+  }
+  if (/\b(shadow|elevation)\b/.test(haystack)) return "shadow";
+  if (/\b(font|type|typography|line-height|letter-spacing)\b/.test(haystack)) {
+    return "typography";
+  }
+  if (/\b(duration|transition|animation)\b/.test(haystack)) return "duration";
+  if (/\b(z-index|zindex)\b/.test(haystack)) return "z-index";
+  if (/\b(space|spacing|size|sizing|width|height|gap|padding|margin|inset)\b/.test(haystack)) {
+    return "spacing";
+  }
+  if (/\bborder\b/.test(haystack)) return "border-width";
+  return "other";
+}
+function cssVarForToken(token) {
+  if (token.name.startsWith("--")) return token.name;
+  const match = token.value?.match(/var\((--[\w-]+)/);
+  return match?.[1];
+}
+function dottedNameForToken(token, tokenData) {
+  if (!token.name.startsWith("--")) return token.name;
+  let name = token.name.slice(2);
+  const prefix = tokenData?.prefix?.replace(/^--/, "").replace(/-$/, "");
+  if (prefix && name.startsWith(`${prefix}-`)) {
+    name = name.slice(prefix.length + 1);
+  }
+  return name.replace(/-/g, ".");
+}
+function resolvedValueForToken(token) {
+  const value = token.value?.trim();
+  if (!value) return void 0;
+  const fallback = value.match(/var\(--[\w-]+,\s*([^)]+)\)/)?.[1]?.trim();
+  if (fallback) return fallback;
+  if (value.startsWith("var(")) return void 0;
+  return value;
+}
+function normalizeComparableValue(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim().toLowerCase();
+  const color = normalizeColor(trimmed);
+  if (color) return color;
+  const length = parseLength(trimmed);
+  if (length) return `${length.value}${length.unit}`;
+  return trimmed.replace(/\s+/g, " ");
+}
+function looksLikeColor(value) {
+  return /^#([\da-f]{3,8})$/i.test(value) || /^rgba?\(/i.test(value) || /^hsla?\(/i.test(value);
+}
+function normalizeColor(value) {
+  const hex = value.match(/^#([\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i);
+  if (!hex) return void 0;
+  const body = hex[1].toLowerCase();
+  if (body.length === 3) {
+    return `#${body[0]}${body[0]}${body[1]}${body[1]}${body[2]}${body[2]}`;
+  }
+  return `#${body}`;
+}
+function parseLength(value) {
+  const match = value.match(/^(-?\d+(?:\.\d+)?)(px|rem|em|%)$/);
+  if (!match) return void 0;
+  return { value: Number(match[1]), unit: match[2] };
+}
+function lengthDistanceScore(inputValue, tokenValue) {
+  const input = parseLength(inputValue);
+  const token = parseLength(tokenValue);
+  if (!input || !token || input.unit !== token.unit) return 0;
+  const distance = Math.abs(input.value - token.value);
+  if (distance === 0) return 60;
+  if (distance <= 2) return 35;
+  if (distance <= 4) return 20;
+  if (distance <= 8) return 10;
+  return 0;
+}
+function nameRelevanceScore(token, property, context) {
+  const haystack = [token.name, token.category, ...token.path ?? []].join(" ").toLowerCase();
+  const prop = property.toLowerCase();
+  let score = 0;
+  for (const part of prop.split(/[^a-z0-9]+/).filter((part2) => part2.length > 2)) {
+    if (haystack.includes(part)) score += 4;
+  }
+  if (context === "component" && haystack.includes("component")) score += 3;
+  if (context === "global" && haystack.includes("global")) score += 3;
+  return score;
+}
 
-// src/tools/perf.ts
-var perfHandler = async (args, ctx) => {
-  const componentName = args?.component ?? void 0;
-  const sort = args?.sort ?? "size";
-  const filter = args?.filter ?? void 0;
-  let entries = Object.values(ctx.data.components).filter((component) => component.performance).map((component) => ({
-    name: component.name,
-    ...component.performance
-  }));
-  if (entries.length === 0) {
+// src/tools/tokens-suggest.ts
+var tokensSuggestHandler = async (args, ctx) => {
+  const property = args.property;
+  if (!property || typeof property !== "string") {
     return {
       content: [
         {
           type: "text",
-          text: JSON.stringify({
-            total: 0,
-            components: [],
-            hint: `No performance data found. Run \`${BRAND.cliCommand} perf\` first to measure bundle sizes.`
-          })
+          text: JSON.stringify({ error: "property is required." })
         }
-      ]
+      ],
+      isError: true
     };
   }
-  if (componentName) {
-    entries = entries.filter(
-      (entry) => entry.name.toLowerCase() === componentName.toLowerCase()
-    );
-    if (entries.length === 0) {
-      throw new Error(
-        `No performance data for "${componentName}". Run \`${BRAND.cliCommand} perf --component ${componentName}\` first.`
-      );
-    }
-  }
-  if (filter) {
-    if (filter === "over-budget") {
-      entries = entries.filter((entry) => entry.overBudget);
-    } else {
-      entries = entries.filter((entry) => entry.complexity === filter);
-    }
-  }
-  switch (sort) {
-    case "name":
-      entries.sort((a, b) => a.name.localeCompare(b.name));
-      break;
-    case "budget":
-      entries.sort((a, b) => b.budgetPercent - a.budgetPercent);
-      break;
-    case "size":
-    default:
-      entries.sort((a, b) => b.bundleSize - a.bundleSize);
-      break;
-  }
+  const context = args.context;
+  const catalogMeta = getCatalogMeta(ctx.data);
+  const result2 = suggestToken({
+    tokens: ctx.data.tokens,
+    property,
+    value: typeof args.value === "string" ? args.value : void 0,
+    context: context === "component" || context === "block" || context === "global" ? context : void 0,
+    catalogRevision: catalogMeta.catalogRevision,
+    updatedAt: catalogMeta.updatedAt
+  });
   return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify({
-          total: entries.length,
-          summary: ctx.data.performanceSummary ?? void 0,
-          components: entries
-        })
-      }
-    ]
+    content: [{ type: "text", text: JSON.stringify(result2) }],
+    _meta: result2._meta
   };
 };
 
 // src/tools/spec-govern.ts
-var SEVERITY_WEIGHTS = {
-  critical: 10,
-  serious: 5,
-  moderate: 2,
-  minor: 1
-};
+import { SEVERITY_WEIGHTS, maxSeverity } from "@fragments-sdk/core/severity";
 function isRuleEnabled(rule, defaultEnabled = true) {
   if (rule === void 0) return defaultEnabled;
   if (typeof rule === "boolean") return rule;
@@ -2434,9 +347,8 @@ function flattenNodes(spec) {
   return flattened;
 }
 function worstSeverity(violations) {
-  const order = ["critical", "serious", "moderate", "minor"];
   return violations.reduce(
-    (worst, violation) => order.indexOf(violation.severity) < order.indexOf(worst) ? violation.severity : worst,
+    (worst, violation) => maxSeverity(worst, violation.severity),
     "minor"
   );
 }
@@ -2448,12 +360,25 @@ function result(validator, violations) {
     violations
   };
 }
+var SEVERITY_SCORE_CAPS = {
+  critical: 25,
+  serious: 50,
+  moderate: 80,
+  minor: 95
+};
+function verdictFor(violations) {
+  if (violations.length === 0) return "pass";
+  const worst = worstSeverity(violations);
+  return worst === "critical" || worst === "serious" ? "fail" : "warn";
+}
 function computeScore(violations) {
+  if (violations.length === 0) return 100;
   const penalty = violations.reduce(
     (sum, violation) => sum + SEVERITY_WEIGHTS[violation.severity],
     0
   );
-  return Math.max(0, 100 - penalty);
+  const cap = SEVERITY_SCORE_CAPS[worstSeverity(violations)];
+  return Math.min(cap, Math.max(0, 100 - penalty));
 }
 function validateComponents(nodes, options) {
   const rules = options.policy?.rules ?? {};
@@ -2524,7 +449,76 @@ function validateSafety(nodes) {
       }
     }
   }
-  return result("safety", violations);
+  return result("safety", violations);
+}
+function editDistance(a, b) {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const distances = Array.from({ length: rows }, () => Array(cols).fill(0));
+  for (let i = 0; i < rows; i++) distances[i][0] = i;
+  for (let j = 0; j < cols; j++) distances[0][j] = j;
+  for (let i = 1; i < rows; i++) {
+    for (let j = 1; j < cols; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      distances[i][j] = Math.min(
+        distances[i - 1][j] + 1,
+        distances[i][j - 1] + 1,
+        distances[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return distances[a.length][b.length];
+}
+function normalizePropValue(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function closestAllowedValue(rawValue, allowedValues) {
+  const normalizedRaw = normalizePropValue(rawValue);
+  const ranked = allowedValues.map((value) => {
+    const normalizedValue = normalizePropValue(value);
+    const distance = editDistance(normalizedRaw, normalizedValue);
+    const prefixMatch = normalizedRaw.length >= 4 && (normalizedValue.startsWith(normalizedRaw) || normalizedRaw.startsWith(normalizedValue));
+    return { value, distance, prefixMatch };
+  }).sort((a, b) => {
+    if (a.prefixMatch !== b.prefixMatch) return a.prefixMatch ? -1 : 1;
+    return a.distance - b.distance || a.value.localeCompare(b.value);
+  });
+  const best = ranked[0];
+  if (!best) return void 0;
+  if (best.prefixMatch || best.distance <= 2) return best.value;
+  return void 0;
+}
+function validateProps(nodes, options) {
+  const rules = options.policy?.rules ?? {};
+  const propRule = rules["props/valid-values"];
+  const componentProps = options.componentProps ?? {};
+  const violations = [];
+  if (!isRuleEnabled(propRule)) {
+    return result("props", violations);
+  }
+  for (const [index, node] of nodes.entries()) {
+    const type = nodeType(node);
+    const propSchema = componentProps[type] ?? componentProps[parentType(type)];
+    if (!propSchema) continue;
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+      const allowedValues = propSchema[prop]?.values?.filter(Boolean) ?? [];
+      if (allowedValues.length === 0) continue;
+      const rawValue = typeof value === "string" ? value : void 0;
+      if (!rawValue || allowedValues.includes(rawValue)) continue;
+      const closest = closestAllowedValue(rawValue, allowedValues);
+      violations.push({
+        nodeId: nodeId(node, index),
+        nodeType: type,
+        rule: "props/invalid-value",
+        severity: ruleSeverity(propRule, "moderate"),
+        message: `Prop "${prop}" on ${type} has invalid value "${rawValue}"`,
+        suggestion: closest ? `Use "${closest}" for prop "${prop}" on ${type}.` : `Use one of: ${allowedValues.join(", ")}`,
+        prop,
+        rawValue
+      });
+    }
+  }
+  return result("props", violations);
 }
 function hasHardcodedCssValue(value) {
   if (value.includes("var(")) return false;
@@ -2576,14 +570,29 @@ function validateTokens(nodes, options) {
   }
   return result("tokens", violations);
 }
+function textFromUnknown(value) {
+  if (typeof value === "string") return value.trim();
+  if (Array.isArray(value)) return textFromChildren(value);
+  if (typeof value === "object" && value !== null) {
+    return textFromNode(value);
+  }
+  return "";
+}
+function textFromNode(node) {
+  const type = nodeType(node).toLowerCase();
+  const props = node.props ?? {};
+  const propText = [
+    textFromUnknown(props.children),
+    type === "text" ? textFromUnknown(props.value) : ""
+  ].filter(Boolean);
+  const childText = textFromChildren(node.children);
+  return [...propText, childText].join(" ").trim();
+}
 function textFromChildren(children) {
+  if (typeof children === "string") return children.trim();
   if (!Array.isArray(children)) return "";
   return children.map((child) => {
-    if (typeof child === "string") return child;
-    if (typeof child === "object" && child !== null && !Array.isArray(child)) {
-      return textFromChildren(child.children);
-    }
-    return "";
+    return textFromUnknown(child);
   }).join(" ").trim();
 }
 function validateA11y(nodes) {
@@ -2593,7 +602,7 @@ function validateA11y(nodes) {
     if (!/button/i.test(type)) continue;
     const props = node.props ?? {};
     const label = props["aria-label"] ?? props["aria-labelledby"] ?? props.title;
-    const childText = textFromChildren(node.children);
+    const childText = textFromNode(node);
     if (typeof label === "string" && label.trim().length > 0) continue;
     if (childText.length > 0) continue;
     violations.push({
@@ -2613,6 +622,7 @@ function runSpecGovern(spec, options) {
   const results = [
     validateSafety(nodes),
     validateComponents(nodes, options),
+    validateProps(nodes, options),
     validateTokens(nodes, options),
     validateA11y(nodes)
   ];
@@ -2621,6 +631,7 @@ function runSpecGovern(spec, options) {
     new Set(nodes.map((node) => nodeType(node)))
   );
   return {
+    verdict: verdictFor(violations),
     passed: results.every((entry) => entry.passed),
     score: computeScore(violations),
     results,
@@ -2638,7 +649,7 @@ function formatVerdict(verdict, format = "summary") {
   }
   const lines = [];
   const icon = verdict.passed ? "ok" : "fail";
-  lines.push(`${icon} Governance check: score ${verdict.score}/100`);
+  lines.push(`${icon} Governance check: verdict ${verdict.verdict}, score ${verdict.score}/100`);
   lines.push("");
   for (const entry of verdict.results) {
     const resultIcon = entry.passed ? "ok" : "fail";
@@ -2657,6 +668,14 @@ function formatVerdict(verdict, format = "summary") {
 }
 
 // src/tools/govern.ts
+function buildComponentProps(ctx) {
+  return Object.fromEntries(
+    Object.values(ctx.data.components).map((component) => [
+      component.name,
+      component.props
+    ])
+  );
+}
 var governHandler = async (args, ctx) => {
   const spec = args?.spec;
   if (!spec || typeof spec !== "object") {
@@ -2665,7 +684,7 @@ var governHandler = async (args, ctx) => {
         {
           type: "text",
           text: JSON.stringify({
-            error: "spec is required and must be an object with { nodes: [{ id, type, props, children }] }"
+            error: "spec is required and must be an object with { nodes: [{ id, type, props, children }], root?, metadata? }. See the govern.schema MCP resource for the full schema."
           })
         }
       ],
@@ -2681,12 +700,15 @@ var governHandler = async (args, ctx) => {
     const verdict = runSpecGovern(spec, {
       allowedComponents,
       tokenPrefix: ctx.data.tokens?.prefix,
-      policy: policyOverrides
+      policy: policyOverrides,
+      componentProps: buildComponentProps(ctx)
     });
     const text = format === "summary" ? formatVerdict(verdict, "summary") : JSON.stringify(verdict);
     return {
       content: [{ type: "text", text }],
       _meta: {
+        ...getCatalogMeta(ctx.data),
+        verdict: verdict.verdict,
         score: verdict.score,
         passed: verdict.passed,
         violationCount: verdict.results.reduce(
@@ -2703,7 +725,7 @@ var governHandler = async (args, ctx) => {
         {
           type: "text",
           text: JSON.stringify({
-            error: isSpecError ? `Invalid spec format: ${message}. Expected: { nodes: [{ id: string, type: string, props: object, children?: string[] }] }` : message
+            error: isSpecError ? `Invalid spec format: ${message}. Expected: { nodes: [{ id?: string, type: string, props?: object, children?: array|string }], root?: string, metadata?: object }. See the govern.schema MCP resource for examples.` : message
           })
         }
       ],
@@ -2752,8 +774,11 @@ function validateNodeShape(node, path) {
     return `${path}.props must be an object`;
   }
   if ("children" in node && node.children !== void 0) {
+    if (typeof node.children === "string") {
+      return null;
+    }
     if (!Array.isArray(node.children)) {
-      return `${path}.children must be an array`;
+      return `${path}.children must be an array or string`;
     }
     for (const [index, child] of node.children.entries()) {
       if (!isPlainObject(child)) continue;
@@ -2898,6 +923,59 @@ function getNextAction(status, replacements, unresolvedAmbiguityCount) {
   if (replacements.length > 0) return "review_partial_fix";
   return "revise_input";
 }
+function authorizationForAmbiguity(args) {
+  const required = [];
+  if (!args.applyFixes) {
+    required.push("applyFixes");
+  }
+  if (!args.allowElicitation) {
+    required.push("allowElicitation");
+  } else if (!args.supportsElicitation) {
+    required.push("clientCapabilities.elicitation.form");
+  }
+  if (!args.allowSampling) {
+    required.push("allowSampling");
+  } else if (!args.supportsSampling) {
+    required.push("clientCapabilities.sampling");
+  }
+  return required;
+}
+function buildWouldFixIfAuthorized(args) {
+  const entries = [];
+  if (!args.applyFixes) {
+    entries.push(
+      ...args.deterministicPreview.map((replacement) => ({
+        action: "replace_component",
+        nodeId: replacement.nodeId,
+        from: replacement.from,
+        to: replacement.to,
+        reason: replacement.reason,
+        requiredAuthorization: ["applyFixes"]
+      }))
+    );
+  }
+  const requiredAuthorization = authorizationForAmbiguity({
+    applyFixes: args.applyFixes,
+    allowElicitation: args.allowElicitation,
+    allowSampling: args.allowSampling,
+    supportsElicitation: args.supportsElicitation,
+    supportsSampling: args.supportsSampling
+  });
+  if (requiredAuthorization.length > 0) {
+    entries.push(
+      ...args.unresolvedAmbiguities.map((ambiguity) => ({
+        action: "resolve_ambiguous_component",
+        nodeId: ambiguity.nodeId,
+        from: ambiguity.from,
+        candidates: ambiguity.candidates,
+        rankedCandidates: ambiguity.rankedCandidates,
+        reason: ambiguity.reason,
+        requiredAuthorization
+      }))
+    );
+  }
+  return entries;
+}
 async function emitValidateAndFixTelemetry(args) {
   if (!args.ctx.mcp?.server) return;
   try {
@@ -2919,11 +997,20 @@ async function emitValidateAndFixTelemetry(args) {
 function buildAllowedComponents(ctx) {
   return buildEffectiveComponents(ctx).filter(({ selection }) => selection === "preferred" || selection === "allowed").map(({ component }) => component.name);
 }
+function buildComponentProps2(ctx) {
+  return Object.fromEntries(
+    Object.values(ctx.data.components).map((component) => [
+      component.name,
+      component.props
+    ])
+  );
+}
 function runGovern(spec, ctx, policyOverrides) {
   return runSpecGovern(spec, {
     allowedComponents: buildAllowedComponents(ctx),
     tokenPrefix: ctx.data.tokens?.prefix,
-    policy: policyOverrides
+    policy: policyOverrides,
+    componentProps: buildComponentProps2(ctx)
   });
 }
 function walkNodes2(nodes, visitor, path = "nodes") {
@@ -3237,11 +1324,14 @@ var validateAndFixHandler = async (args, ctx) => {
     let replacements = [];
     let ambiguities = [];
     const resolutionPath = [];
+    const supportsElicitation = supportsFormElicitation(ctx);
+    const supportsModelSampling = supportsSampling(ctx);
+    const preview = !originalVerdict.passed ? applyDeterministicReplacements(spec, ctx) : void 0;
+    if (!applyFixes && preview) {
+      ambiguities = preview.ambiguities;
+    }
     if (!originalVerdict.passed && applyFixes) {
-      const result2 = applyDeterministicReplacements(
-        spec,
-        ctx
-      );
+      const result2 = preview ?? applyDeterministicReplacements(spec, ctx);
       replacements = result2.replacements;
       ambiguities = result2.ambiguities;
       if (replacements.length > 0) {
@@ -3251,7 +1341,7 @@ var validateAndFixHandler = async (args, ctx) => {
       const unresolvedAmbiguities2 = ambiguities.filter(
         (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
       );
-      if (unresolvedAmbiguities2.length > 0 && allowElicitation && supportsFormElicitation(ctx)) {
+      if (unresolvedAmbiguities2.length > 0 && allowElicitation && supportsElicitation) {
         workingSpec ??= cloneSpec(spec);
         const elicitedReplacements = await resolveAmbiguitiesWithElicitation(
           unresolvedAmbiguities2,
@@ -3266,7 +1356,7 @@ var validateAndFixHandler = async (args, ctx) => {
       const remainingAmbiguities = ambiguities.filter(
         (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
       );
-      if (remainingAmbiguities.length > 0 && allowSampling && supportsSampling(ctx)) {
+      if (remainingAmbiguities.length > 0 && allowSampling && supportsModelSampling) {
         workingSpec ??= cloneSpec(spec);
         const sampledReplacements = await resolveAmbiguitiesWithSampling(
           remainingAmbiguities,
@@ -3287,6 +1377,18 @@ var validateAndFixHandler = async (args, ctx) => {
     const unresolvedAmbiguities = ambiguities.filter(
       (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
     ).map(({ nodeRef: _nodeRef, ...ambiguity }) => ambiguity);
+    const unresolvedAmbiguitiesWithRefs = ambiguities.filter(
+      (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
+    );
+    const wouldFixIfAuthorized = buildWouldFixIfAuthorized({
+      deterministicPreview: preview?.replacements ?? [],
+      unresolvedAmbiguities: unresolvedAmbiguitiesWithRefs,
+      applyFixes,
+      allowElicitation,
+      allowSampling,
+      supportsElicitation,
+      supportsSampling: supportsModelSampling
+    });
     const attestation = {
       sourceType: ctx.data.snapshot.sourceType,
       sourceLabel: ctx.data.snapshot.sourceLabel,
@@ -3301,9 +1403,9 @@ var validateAndFixHandler = async (args, ctx) => {
         overrideApplied: Boolean(policyOverrides)
       },
       clientCapabilities: {
-        sampling: supportsSampling(ctx),
+        sampling: supportsModelSampling,
         samplingTools: Boolean(ctx.mcp?.clientCapabilities?.sampling?.tools),
-        elicitationForm: supportsFormElicitation(ctx),
+        elicitationForm: supportsElicitation,
         roots: Boolean(ctx.mcp?.clientCapabilities?.roots)
       },
       capabilitiesUsed: {
@@ -3333,6 +1435,7 @@ var validateAndFixHandler = async (args, ctx) => {
       replacements,
       unresolvedAmbiguities.length
     );
+    const catalogMeta = getCatalogMeta(ctx.data);
     const payload = {
       status,
       nextAction,
@@ -3358,7 +1461,8 @@ var validateAndFixHandler = async (args, ctx) => {
         effectiveComponents,
         "forbidden"
       ),
-      unresolvedAmbiguities
+      unresolvedAmbiguities,
+      wouldFixIfAuthorized
     };
     await emitValidateAndFixTelemetry({
       ctx,
@@ -3381,13 +1485,14 @@ var validateAndFixHandler = async (args, ctx) => {
         }
       ],
       _meta: {
+        ...catalogMeta,
         status,
         nextAction,
         replacementCount: replacements.length,
         passed: finalVerdict.passed,
         unresolvedAmbiguityCount: unresolvedAmbiguities.length,
-        resolutionPath,
-        catalogRevision: attestation.catalogRevision
+        wouldFixIfAuthorizedCount: wouldFixIfAuthorized.length,
+        resolutionPath
       }
     };
   } catch (error) {
@@ -3406,52 +1511,22 @@ var validateAndFixHandler = async (args, ctx) => {
   }
 };
 
-// src/tools/generate-ui.ts
-var generateUiHandler = async (args, ctx) => {
-  const prompt = args?.prompt;
-  if (!prompt) {
-    throw new Error("prompt is required");
-  }
-  const currentTree = args?.currentTree;
-  const playgroundUrl = ctx.config.playgroundUrl ?? "https://usefragments.com";
-  const response = await fetch(`${playgroundUrl}/api/playground/generate`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      prompt,
-      ...currentTree && { currentSpec: currentTree }
-    })
-  });
-  if (!response.ok) {
-    const errorBody = await response.text();
-    throw new Error(`Playground API error (${response.status}): ${errorBody}`);
-  }
-  const text = await response.text();
-  return {
-    content: [{
-      type: "text",
-      text
-    }]
-  };
-};
-
-// src/findings-service.ts
+// src/cloud-http.ts
 var DEFAULT_CLOUD_URL = "https://app.usefragments.com";
 function normalizeCloudUrl(url) {
   if (!url) return DEFAULT_CLOUD_URL;
   return url.replace(/\/+$/, "");
 }
-async function fetchFindings(apiKey, params, cloudUrl) {
-  const base = normalizeCloudUrl(cloudUrl);
-  const url = new URL(`${base}/api/findings`);
-  if (params.status) url.searchParams.set("status", params.status);
-  if (params.severity) url.searchParams.set("severity", params.severity);
-  if (params.category) url.searchParams.set("category", params.category);
-  if (params.ruleId) url.searchParams.set("ruleId", params.ruleId);
-  if (params.filePath) url.searchParams.set("filePath", params.filePath);
-  if (params.limit != null) url.searchParams.set("limit", String(params.limit));
+async function cloudFetchJson(args) {
+  const base = normalizeCloudUrl(args.cloudUrl);
+  const url = new URL(`${base}${args.path}`);
+  if (args.query) {
+    for (const [key, value] of Object.entries(args.query)) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+  }
   const response = await fetch(url.toString(), {
-    headers: { "X-API-Key": apiKey }
+    headers: { "X-API-Key": args.apiKey }
   });
   if (!response.ok) {
     const body = await response.text();
@@ -3463,11 +1538,29 @@ async function fetchFindings(apiKey, params, cloudUrl) {
       message = body;
     }
     throw new Error(
-      `Cloud findings API error (${response.status}): ${message}`
+      `Cloud ${args.resource} API error (${response.status}): ${message}`
     );
   }
   return await response.json();
 }
+
+// src/findings-service.ts
+async function fetchFindings(apiKey, params, cloudUrl) {
+  return cloudFetchJson({
+    apiKey,
+    cloudUrl,
+    path: "/api/findings",
+    resource: "findings",
+    query: {
+      status: params.status,
+      severity: params.severity,
+      category: params.category,
+      ruleId: params.ruleId,
+      filePath: params.filePath,
+      limit: params.limit
+    }
+  });
+}
 async function fetchFindingsForFile(apiKey, filePath, cloudUrl) {
   return fetchFindings(
     apiKey,
@@ -3475,8 +1568,59 @@ async function fetchFindingsForFile(apiKey, filePath, cloudUrl) {
     cloudUrl
   );
 }
+function buildFindingSourceUrl(finding) {
+  const { repoFullName, commitSha, filePath, line } = finding;
+  if (!repoFullName || !commitSha || !filePath) return void 0;
+  if (!/^[-\w.]+\/[-\w.]+$/.test(repoFullName)) return void 0;
+  if (!/^[a-fA-F0-9]{7,64}$/.test(commitSha)) return void 0;
+  const normalizedPath = filePath.replace(/^\/+/, "");
+  if (!normalizedPath) return void 0;
+  const encodedPath = normalizedPath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  const lineSuffix = line != null && line > 0 ? `#L${Math.floor(line)}` : "";
+  return `https://github.com/${repoFullName}/blob/${commitSha}/${encodedPath}${lineSuffix}`;
+}
+async function fetchFindingsSummary(apiKey, params, cloudUrl) {
+  const { findings } = await fetchFindings(
+    apiKey,
+    { ...params, limit: params.limit ?? 200 },
+    cloudUrl
+  );
+  return summarizeFindings(findings, params);
+}
+function summarizeFindings(findings, params) {
+  const bySeverity = { error: 0, warning: 0, info: 0 };
+  const byStatus = { open: 0, resolved: 0, ignored: 0 };
+  const byCategory = {};
+  const byRuleId = {};
+  const byFilePath = {};
+  for (const finding of findings) {
+    bySeverity[finding.severity] += 1;
+    byStatus[finding.status] += 1;
+    increment(byRuleId, finding.ruleId);
+    if (finding.category) increment(byCategory, finding.category);
+    if (finding.filePath) increment(byFilePath, finding.filePath);
+  }
+  const { limit: _limit, ...filters } = params;
+  return {
+    total: findings.length,
+    filters,
+    bySeverity,
+    byStatus,
+    byCategory,
+    byRuleId,
+    byFilePath,
+    topFiles: topEntries(byFilePath, "filePath"),
+    topRules: topEntries(byRuleId, "ruleId")
+  };
+}
+function increment(counts, key) {
+  counts[key] = (counts[key] ?? 0) + 1;
+}
+function topEntries(counts, keyName) {
+  return Object.entries(counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 10).map(([key, count]) => ({ [keyName]: key, count }));
+}
 
-// src/tools/findings.ts
+// src/tools/cloud-auth.ts
 function resolveCloudApiKey(ctx) {
   return ctx.config.cloudApiKey ?? ctx.config.fileConfig?.cloud?.apiKey ?? process.env.FRAGMENTS_API_KEY;
 }
@@ -3496,6 +1640,38 @@ function missingKeyError() {
     isError: true
   };
 }
+
+// src/tools/findings.ts
+function enrichFindings(findings, ctx) {
+  return findings.map((finding) => {
+    const sourceUrl = finding.sourceUrl ?? buildFindingSourceUrl(finding);
+    const withSourceUrl = sourceUrl ? { ...finding, sourceUrl } : finding;
+    if (!finding.prop || !finding.rawValue || !ctx.data.tokens) {
+      return withSourceUrl;
+    }
+    const catalogMeta = getCatalogMeta(ctx.data);
+    const suggestion = suggestToken({
+      tokens: ctx.data.tokens,
+      property: finding.prop,
+      value: finding.rawValue,
+      catalogRevision: catalogMeta.catalogRevision,
+      updatedAt: catalogMeta.updatedAt
+    });
+    if (!suggestion.recommended) {
+      const {
+        suggestedToken: _discarded,
+        suggestedTokenDetails: _details,
+        ...rest
+      } = withSourceUrl;
+      return rest;
+    }
+    return {
+      ...withSourceUrl,
+      suggestedToken: suggestion.recommended.cssVar ?? suggestion.recommended.name,
+      suggestedTokenDetails: suggestion.recommended
+    };
+  });
+}
 var findingsListHandler = async (args, ctx) => {
   const apiKey = resolveCloudApiKey(ctx);
   if (!apiKey) return missingKeyError();
@@ -3510,9 +1686,65 @@ var findingsListHandler = async (args, ctx) => {
   if (args.limit != null) params.limit = Number(args.limit);
   try {
     const result2 = await fetchFindings(apiKey, params, cloudUrl);
+    const findings = enrichFindings(result2.findings, ctx);
+    const catalogMeta = getCatalogMeta(ctx.data);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ ...result2, findings })
+        }
+      ],
+      _meta: {
+        ...catalogMeta,
+        count: findings.length,
+        tokenSuggestionCount: findings.filter(
+          (finding) => finding.suggestedTokenDetails
+        ).length
+      }
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+var findingsSummaryHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const cloudUrl = resolveCloudUrl(ctx);
+  const params = {};
+  if (args.status) params.status = args.status;
+  if (args.severity)
+    params.severity = args.severity;
+  if (args.category) params.category = String(args.category);
+  if (args.ruleId) params.ruleId = String(args.ruleId);
+  if (args.filePath) params.filePath = String(args.filePath);
+  if (args.limit != null) params.limit = Number(args.limit);
+  try {
+    const summary = await fetchFindingsSummary(apiKey, params, cloudUrl);
+    const catalogMeta = getCatalogMeta(ctx.data);
     return {
-      content: [{ type: "text", text: JSON.stringify(result2) }],
-      _meta: { count: result2.findings.length }
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(summary)
+        }
+      ],
+      _meta: {
+        ...catalogMeta,
+        total: summary.total,
+        topFileCount: summary.topFiles.length,
+        topRuleCount: summary.topRules.length
+      }
     };
   } catch (error) {
     return {
@@ -3546,7 +1778,11 @@ var findingsForFileHandler = async (args, ctx) => {
   const cloudUrl = resolveCloudUrl(ctx);
   try {
     const result2 = await fetchFindingsForFile(apiKey, filePath, cloudUrl);
-    const findings = result2.findings.filter((f) => f.filePath === filePath);
+    const findings = enrichFindings(
+      result2.findings.filter((f) => f.filePath === filePath),
+      ctx
+    );
+    const catalogMeta = getCatalogMeta(ctx.data);
     return {
       content: [
         {
@@ -3554,7 +1790,14 @@ var findingsForFileHandler = async (args, ctx) => {
           text: JSON.stringify({ findings, filePath })
         }
       ],
-      _meta: { count: findings.length, filePath }
+      _meta: {
+        ...catalogMeta,
+        count: findings.length,
+        filePath,
+        tokenSuggestionCount: findings.filter(
+          (finding) => finding.suggestedTokenDetails
+        ).length
+      }
     };
   } catch (error) {
     return {
@@ -3571,43 +1814,208 @@ var findingsForFileHandler = async (args, ctx) => {
   }
 };
 
+// src/tools/swap-to-canonical.ts
+import * as ts from "typescript";
+import { resolveCanonicalForHtmlElement, formatRawHtmlElement } from "@fragments-sdk/classifier";
+
+// src/canonical-mappings-service.ts
+async function fetchCanonicalMappings(apiKey, cloudUrl) {
+  const catalog = await cloudFetchJson({
+    apiKey,
+    cloudUrl,
+    path: "/api/catalog",
+    resource: "catalog"
+  });
+  return catalog.canonicalMappings ?? [];
+}
+
+// src/tools/swap-to-canonical.ts
+function errorResult(message) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: message })
+      }
+    ],
+    isError: true
+  };
+}
+var resolveCanonicalForElement = resolveCanonicalForHtmlElement;
+function walkRawJsxElements(source) {
+  const results = [];
+  const visit = (node) => {
+    let opening;
+    if (ts.isJsxSelfClosingElement(node)) {
+      opening = node;
+    } else if (ts.isJsxElement(node)) {
+      opening = node.openingElement;
+    }
+    if (opening) {
+      const tagNameNode = opening.tagName;
+      if (ts.isIdentifier(tagNameNode)) {
+        const tagName = tagNameNode.text;
+        if (/^[a-z]/.test(tagName)) {
+          const attrs = /* @__PURE__ */ new Map();
+          for (const attr of opening.attributes.properties) {
+            if (!ts.isJsxAttribute(attr)) continue;
+            if (!attr.name || !ts.isIdentifier(attr.name)) continue;
+            const name = attr.name.text;
+            if (!attr.initializer) {
+              attrs.set(name, { value: "", dynamic: false });
+              continue;
+            }
+            if (ts.isStringLiteral(attr.initializer)) {
+              attrs.set(name, {
+                value: attr.initializer.text,
+                dynamic: false
+              });
+            } else if (ts.isJsxExpression(attr.initializer)) {
+              attrs.set(name, { value: "", dynamic: true });
+            }
+          }
+          const start = opening.getStart(source);
+          const { line } = source.getLineAndCharacterOfPosition(start);
+          results.push({ tagName, attrs, line: line + 1 });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return results;
+}
+var formatRawElement = formatRawHtmlElement;
+function buildPropMapping(attrs, rowMapping) {
+  const transforms = new Map(rowMapping.map((m) => [m.rawProp, m]));
+  const mapping = [];
+  for (const rawProp of attrs.keys()) {
+    if (rawProp === "type") continue;
+    mapping.push(transforms.get(rawProp) ?? { rawProp, canonicalProp: rawProp });
+  }
+  return mapping;
+}
+function groupMappingsByCanonical(mappings) {
+  const out = /* @__PURE__ */ new Map();
+  for (const m of mappings) {
+    if (!m.importPath) continue;
+    const list = out.get(m.canonical) ?? [];
+    list.push(m);
+    out.set(m.canonical, list);
+  }
+  for (const list of out.values()) {
+    list.sort((a, b) => {
+      const ac = a.confidence ?? 0;
+      const bc = b.confidence ?? 0;
+      if (ac !== bc) return bc - ac;
+      return a.name.localeCompare(b.name);
+    });
+  }
+  return out;
+}
+function buildSwapSuggestions(args) {
+  const eligible = args.mappings.filter(
+    (m) => (m.canonicalStatus ?? legacyStatusForMapping(m)) === "confirmed"
+  );
+  if (eligible.length === 0) return [];
+  const byCanonical = groupMappingsByCanonical(eligible);
+  if (byCanonical.size === 0) return [];
+  const source = ts.createSourceFile(
+    args.filePath,
+    args.fileContent,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */
+    true,
+    ts.ScriptKind.TSX
+  );
+  const elements = walkRawJsxElements(source);
+  const suggestions = [];
+  for (const el of elements) {
+    const canonical = resolveCanonicalForElement(el.tagName, el.attrs);
+    if (!canonical) continue;
+    const candidates = byCanonical.get(canonical);
+    if (!candidates || candidates.length === 0) continue;
+    const primary = candidates[0];
+    const importPath = primary.importPath;
+    if (!importPath) continue;
+    const suggestion = {
+      rawElement: formatRawElement(el.tagName, el.attrs),
+      canonical,
+      componentName: primary.name,
+      importPath,
+      propMapping: buildPropMapping(el.attrs, primary.propMapping),
+      line: el.line
+    };
+    if (candidates.length > 1) {
+      suggestion.alternates = candidates.slice(1).filter((c) => c.importPath).map((c) => ({
+        name: c.name,
+        importPath: c.importPath,
+        confidence: c.confidence ?? 0
+      }));
+    }
+    suggestions.push(suggestion);
+  }
+  return suggestions;
+}
+function legacyStatusForMapping(mapping) {
+  return mapping.canonicalConfidence === "overridden" || mapping.canonicalConfidence === "auto" ? "confirmed" : "proposed";
+}
+var swapToCanonicalHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const filePath = typeof args.filePath === "string" ? args.filePath : "";
+  const fileContent = typeof args.fileContent === "string" ? args.fileContent : "";
+  if (!filePath || !fileContent) {
+    return errorResult("filePath and fileContent are required.");
+  }
+  const cloudUrl = resolveCloudUrl(ctx);
+  let mappings;
+  try {
+    mappings = await fetchCanonicalMappings(apiKey, cloudUrl);
+  } catch (error) {
+    return errorResult(error instanceof Error ? error.message : String(error));
+  }
+  const suggestions = buildSwapSuggestions({
+    filePath,
+    fileContent,
+    mappings
+  });
+  const message = mappings.length === 0 ? "No confirmed canonical primitives are configured for this project. Visit the Components page to confirm primitives." : void 0;
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ suggestions, filePath, message })
+      }
+    ],
+    _meta: {
+      count: suggestions.length,
+      mappingCount: mappings.length,
+      filePath
+    }
+  };
+};
+
 // src/tools/index.ts
 var CORE_TOOLS = {
-  discover: discoverHandler,
-  inspect: inspectHandler,
-  blocks: blocksHandler,
-  tokens: tokensHandler,
-  graph: graphHandler,
-  perf: perfHandler,
+  "tokens.suggest": tokensSuggestHandler,
   govern: governHandler,
   validate_and_fix: validateAndFixHandler,
   findings_list: findingsListHandler,
-  findings_for_file: findingsForFileHandler
-};
-var VIEWER_TOOLS = {
-  render: renderHandler,
-  fix: fixHandler,
-  a11y: a11yHandler
-};
-var INFRA_TOOLS = {
-  generate_ui: generateUiHandler
+  findings_summary: findingsSummaryHandler,
+  findings_for_file: findingsForFileHandler,
+  swap_to_canonical: swapToCanonicalHandler
 };
+var VIEWER_TOOLS = {};
+var INFRA_TOOLS = {};
 var BUILTIN_TOOLS = {
   ...CORE_TOOLS,
   ...VIEWER_TOOLS,
   ...INFRA_TOOLS
 };
 var TOOL_CAPABILITIES = {
-  discover: ["components"],
-  inspect: ["components"],
-  blocks: ["blocks"],
-  tokens: ["tokens"],
-  graph: ["graph"],
-  perf: ["performance"],
-  validate_and_fix: ["components"],
-  render: ["components"],
-  fix: ["components"],
-  a11y: ["components"]
+  "tokens.suggest": ["tokens"],
+  validate_and_fix: ["components"]
 };
 
 // src/registry.ts
@@ -3747,16 +2155,17 @@ function telemetryMiddleware(logger) {
 }
 
 // src/source-selection.ts
-import { existsSync as existsSync8 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { join as join6 } from "path";
 
 // src/adapters/fragments-json.ts
 import { readFile } from "fs/promises";
 
 // src/discovery.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync } from "fs";
-import { join as join3, dirname, resolve } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync } from "fs";
+import { join as join2, dirname, resolve } from "path";
 import { createRequire } from "module";
+import { BRAND } from "@fragments-sdk/core";
 function resolveWorkspaceGlob(baseDir, pattern) {
   const parts = pattern.split("/");
   let dirs = [baseDir];
@@ -3768,14 +2177,14 @@ function resolveWorkspaceGlob(baseDir, pattern) {
         try {
           for (const entry of readdirSync(d, { withFileTypes: true })) {
             if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
-              next.push(join3(d, entry.name));
+              next.push(join2(d, entry.name));
             }
           }
         } catch {
         }
       } else {
-        const candidate = join3(d, part);
-        if (existsSync3(candidate)) next.push(candidate);
+        const candidate = join2(d, part);
+        if (existsSync2(candidate)) next.push(candidate);
       }
     }
     dirs = next;
@@ -3784,8 +2193,8 @@ function resolveWorkspaceGlob(baseDir, pattern) {
 }
 function getWorkspaceDirs(rootDir) {
   const dirs = [];
-  const rootPkgPath = join3(rootDir, "package.json");
-  if (existsSync3(rootPkgPath)) {
+  const rootPkgPath = join2(rootDir, "package.json");
+  if (existsSync2(rootPkgPath)) {
     try {
       const rootPkg = JSON.parse(readFileSync3(rootPkgPath, "utf-8"));
       const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : rootPkg.workspaces?.packages;
@@ -3798,8 +2207,8 @@ function getWorkspaceDirs(rootDir) {
     } catch {
     }
   }
-  const pnpmWsPath = join3(rootDir, "pnpm-workspace.yaml");
-  if (existsSync3(pnpmWsPath)) {
+  const pnpmWsPath = join2(rootDir, "pnpm-workspace.yaml");
+  if (existsSync2(pnpmWsPath)) {
     try {
       const content = readFileSync3(pnpmWsPath, "utf-8");
       const lines = content.split("\n");
@@ -3832,8 +2241,8 @@ function resolveDepPackageJson(localRequire, depName) {
     const mainPath = localRequire.resolve(depName);
     let dir = dirname(mainPath);
     while (true) {
-      const candidate = join3(dir, "package.json");
-      if (existsSync3(candidate)) {
+      const candidate = join2(dir, "package.json");
+      if (existsSync2(candidate)) {
         const pkg = JSON.parse(readFileSync3(candidate, "utf-8"));
         if (pkg.name === depName) return candidate;
       }
@@ -3846,23 +2255,23 @@ function resolveDepPackageJson(localRequire, depName) {
   return null;
 }
 function findFragmentsInDeps(dir, found, depField) {
-  const pkgJsonPath = join3(dir, "package.json");
-  if (!existsSync3(pkgJsonPath)) return;
+  const pkgJsonPath = join2(dir, "package.json");
+  if (!existsSync2(pkgJsonPath)) return;
   try {
     const pkgJson = JSON.parse(readFileSync3(pkgJsonPath, "utf-8"));
     const allDeps = {
       ...pkgJson.dependencies,
       ...pkgJson.devDependencies
     };
-    const localRequire = createRequire(join3(dir, "noop.js"));
+    const localRequire = createRequire(join2(dir, "noop.js"));
     for (const depName of Object.keys(allDeps)) {
       try {
         const depPkgPath = resolveDepPackageJson(localRequire, depName);
         if (!depPkgPath) continue;
         const depPkg = JSON.parse(readFileSync3(depPkgPath, "utf-8"));
         if (depPkg[depField]) {
-          const fragmentsPath = join3(dirname(depPkgPath), depPkg[depField]);
-          if (existsSync3(fragmentsPath) && !found.includes(fragmentsPath)) {
+          const fragmentsPath = join2(dirname(depPkgPath), depPkg[depField]);
+          if (existsSync2(fragmentsPath) && !found.includes(fragmentsPath)) {
             found.push(fragmentsPath);
           }
         }
@@ -3877,8 +2286,8 @@ function findDesignSystemJson(startDir, outFile, depField) {
   const resolvedStart = resolve(startDir);
   let dir = resolvedStart;
   while (true) {
-    const candidate = join3(dir, outFile);
-    if (existsSync3(candidate)) {
+    const candidate = join2(dir, outFile);
+    if (existsSync2(candidate)) {
       found.push(candidate);
       break;
     }
@@ -3887,7 +2296,7 @@ function findDesignSystemJson(startDir, outFile, depField) {
     dir = parent;
   }
   findFragmentsInDeps(resolvedStart, found, depField);
-  if (found.length === 0 || existsSync3(join3(resolvedStart, "pnpm-workspace.yaml"))) {
+  if (found.length === 0 || existsSync2(join2(resolvedStart, "pnpm-workspace.yaml"))) {
     const workspaceDirs = getWorkspaceDirs(resolvedStart);
     for (const wsDir of workspaceDirs) {
       findFragmentsInDeps(wsDir, found, depField);
@@ -3902,8 +2311,8 @@ function findBundleManifest(startDir) {
   const found = [];
   let dir = resolve(startDir);
   while (true) {
-    const candidate = join3(dir, BRAND.dataDir, BRAND.manifestFile);
-    if (existsSync3(candidate)) {
+    const candidate = join2(dir, BRAND.dataDir, BRAND.manifestFile);
+    if (existsSync2(candidate)) {
       found.push(candidate);
       break;
     }
@@ -3914,6 +2323,9 @@ function findBundleManifest(startDir) {
   return found;
 }
 
+// src/adapters/fragments-json.ts
+import { BRAND as BRAND2 } from "@fragments-sdk/core";
+
 // src/adapters/snapshot-converters.ts
 import { mcpSnapshotSchema } from "@fragments-sdk/core";
 function slugify(value) {
@@ -4059,13 +2471,15 @@ function tokensFromCompiledTokenData(tokens) {
       category,
       value: valueToString(entry.value),
       description: entry.description
-    }));
-    categories[category] = normalized;
-    flat.push(...normalized);
+    })).filter((token) => !isGarbageToken(token));
+    if (normalized.length > 0) {
+      categories[category] = normalized;
+      flat.push(...normalized);
+    }
   }
   return {
     prefix: tokens.prefix,
-    total: tokens.total,
+    total: flat.length,
     categories,
     flat
   };
@@ -4104,18 +2518,18 @@ var FragmentsJsonAdapter = class {
     const paths = this.discover(projectRoot);
     if (paths.length === 0) {
       throw new Error(
-        `No ${BRAND.outFile} found. Searched ${projectRoot} and package.json dependencies.
+        `No ${BRAND2.outFile} found. Searched ${projectRoot} and package.json dependencies.
 
 Fix: Add a project-level MCP config so the server runs from your workspace root:
 
   Cursor:    .cursor/mcp.json
   VS Code:   .vscode/mcp.json
-  Claude:    claude mcp add ${BRAND.nameLower} -- npx @fragments-sdk/mcp
+  Claude:    claude mcp add ${BRAND2.nameLower} -- npx @fragments-sdk/mcp
   Windsurf:  .windsurf/mcp.json
 
 Or pass --project-root: npx @fragments-sdk/mcp -p /path/to/project
 
-If you're a library author, run \`${BRAND.cliCommand} build\` first.`
+If you're a library author, run \`${BRAND2.cliCommand} build\` first.`
       );
     }
     const content = await readFile(paths[0], "utf-8");
@@ -4164,7 +2578,7 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
     const snapshot = validateSnapshot({
       schemaVersion: 1,
       sourceType: "fragments-json",
-      sourceLabel: BRAND.outFile,
+      sourceLabel: BRAND2.outFile,
       capabilities: buildCapabilities({
         components,
         blocks,
@@ -4200,12 +2614,12 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
 };
 
 // src/adapters/auto-extract.ts
-import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
-import { join as join6, relative, sep } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { join as join5, relative, sep } from "path";
 
 // src/adapters/discover-components.ts
-import { readdirSync as readdirSync2, existsSync as existsSync4 } from "fs";
-import { join as join4, extname, basename } from "path";
+import { readdirSync as readdirSync2, existsSync as existsSync3 } from "fs";
+import { join as join3, extname, basename } from "path";
 var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   "dist",
@@ -4241,10 +2655,10 @@ function discoverComponentFiles(projectRoot) {
     "src/ui",
     "lib/ui",
     "packages"
-  ].map((d) => join4(projectRoot, d)).filter((d) => existsSync4(d));
+  ].map((d) => join3(projectRoot, d)).filter((d) => existsSync3(d));
   if (scanDirs.length === 0) {
-    const srcDir = join4(projectRoot, "src");
-    if (existsSync4(srcDir)) scanDirs.push(srcDir);
+    const srcDir = join3(projectRoot, "src");
+    if (existsSync3(srcDir)) scanDirs.push(srcDir);
   }
   for (const dir of scanDirs) {
     walkDir(dir, results, seen);
@@ -4263,14 +2677,14 @@ function walkDir(dir, results, seen, depth = 0) {
     if (entry.name.startsWith(".")) continue;
     if (entry.isDirectory()) {
       if (EXCLUDED_DIRS.has(entry.name)) continue;
-      walkDir(join4(dir, entry.name), results, seen, depth + 1);
+      walkDir(join3(dir, entry.name), results, seen, depth + 1);
       continue;
     }
     if (!entry.isFile()) continue;
     const ext = extname(entry.name);
     if (ext !== ".tsx" && ext !== ".jsx") continue;
     if (EXCLUDED_PATTERNS.some((p) => p.test(entry.name))) continue;
-    const filePath = join4(dir, entry.name);
+    const filePath = join3(dir, entry.name);
     if (seen.has(filePath)) continue;
     seen.add(filePath);
     const name = inferComponentName(entry.name, dir);
@@ -4288,8 +2702,8 @@ function inferComponentName(fileName, dirPath) {
 }
 
 // src/adapters/scan-tokens.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync4, existsSync as existsSync5 } from "fs";
-import { join as join5, extname as extname2 } from "path";
+import { readdirSync as readdirSync3, readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+import { join as join4, extname as extname2 } from "path";
 function scanTokens(projectRoot) {
   const cssFiles = discoverCssFiles(projectRoot);
   if (cssFiles.length === 0) return void 0;
@@ -4327,7 +2741,7 @@ function discoverCssFiles(projectRoot) {
     "styles",
     "css",
     "app"
-  ].map((d) => join5(projectRoot, d)).filter((d) => existsSync5(d));
+  ].map((d) => join4(projectRoot, d)).filter((d) => existsSync4(d));
   searchDirs.push(projectRoot);
   for (const dir of searchDirs) {
     try {
@@ -4336,22 +2750,22 @@ function discoverCssFiles(projectRoot) {
         if (!entry.isFile()) continue;
         const ext = extname2(entry.name);
         if (ext === ".css" || ext === ".scss") {
-          files.push(join5(dir, entry.name));
+          files.push(join4(dir, entry.name));
         }
       }
     } catch {
       continue;
     }
   }
-  const srcDir = join5(projectRoot, "src");
-  if (existsSync5(srcDir)) {
+  const srcDir = join4(projectRoot, "src");
+  if (existsSync4(srcDir)) {
     try {
       for (const subEntry of readdirSync3(srcDir, { withFileTypes: true })) {
         if (subEntry.isDirectory() && ["styles", "css", "theme", "tokens"].includes(subEntry.name)) {
-          const subDir = join5(srcDir, subEntry.name);
+          const subDir = join4(srcDir, subEntry.name);
           for (const file of readdirSync3(subDir, { withFileTypes: true })) {
             if (file.isFile() && (file.name.endsWith(".css") || file.name.endsWith(".scss"))) {
-              files.push(join5(subDir, file.name));
+              files.push(join4(subDir, file.name));
             }
           }
         }
@@ -4583,7 +2997,7 @@ Check that your tsconfig.json includes the component directories.`
 var extractorModulePromise = null;
 async function loadExtractorModule() {
   if (!extractorModulePromise) {
-    extractorModulePromise = import("./dist-BDWAHJ4K.js");
+    extractorModulePromise = import("./dist-LVC53MY5.js");
   }
   return extractorModulePromise;
 }
@@ -4849,15 +3263,15 @@ function inferCategory(relativePath) {
 function findTsConfig(projectRoot) {
   const candidates = ["tsconfig.json", "tsconfig.app.json"];
   for (const name of candidates) {
-    const p = join6(projectRoot, name);
-    if (existsSync6(p)) return p;
+    const p = join5(projectRoot, name);
+    if (existsSync5(p)) return p;
   }
   return null;
 }
 function readPackageName(projectRoot) {
   try {
-    const pkgPath = join6(projectRoot, "package.json");
-    if (!existsSync6(pkgPath)) return void 0;
+    const pkgPath = join5(projectRoot, "package.json");
+    if (!existsSync5(pkgPath)) return void 0;
     const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
     return pkg.name;
   } catch {
@@ -4880,7 +3294,36 @@ function chooseComponentSource(args) {
   }
   return args.catalogComponents;
 }
-var TOKEN_CATEGORY_ALIASES2 = {
+function dominantString(values) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    if (!trimmed) continue;
+    counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);
+  }
+  const ranked = [...counts.entries()].sort(
+    (a, b) => b[1] - a[1] || a[0].localeCompare(b[0])
+  );
+  if (ranked.length === 0) return void 0;
+  if (ranked[1] && ranked[1][1] === ranked[0][1]) return void 0;
+  return ranked[0][0];
+}
+function inferDesignSystemMetadataFromComponents(components) {
+  const packageName = dominantString(
+    components.map((component) => component.packageName)
+  );
+  const packageComponents = packageName ? components.filter((component) => component.packageName === packageName) : components;
+  const importPath = dominantString(
+    packageComponents.map(
+      (component) => component.importPath ?? component.packageName
+    )
+  );
+  return {
+    packageName: packageName ?? null,
+    importPath: importPath ?? packageName ?? null
+  };
+}
+var TOKEN_CATEGORY_ALIASES = {
   color: ["color", "colors", "accent", "background", "foreground", "danger", "brand"],
   spacing: ["spacing", "space", "padding", "margin", "gap", "inset"],
   typography: ["typography", "font", "text", "copy", "line-height", "letter"],
@@ -4911,7 +3354,7 @@ function canonicalizeTokenCategory(token) {
   ].map(normalizeValue).filter(Boolean);
   for (const candidate of candidates) {
     for (const [canonical, aliases] of Object.entries(
-      TOKEN_CATEGORY_ALIASES2
+      TOKEN_CATEGORY_ALIASES
     )) {
       if (candidate === canonical || aliases.some(
         (alias) => candidate === alias || candidate.includes(alias) || alias.includes(candidate)
@@ -4924,7 +3367,7 @@ function canonicalizeTokenCategory(token) {
 }
 function groupTokens(flat) {
   const categories = {};
-  const normalizedFlat = (flat ?? []).map((token) => {
+  const normalizedFlat = (flat ?? []).filter((token) => !isGarbageToken(token)).map((token) => {
     const category = canonicalizeTokenCategory(token);
     const normalized = {
       name: token.name,
@@ -5055,6 +3498,7 @@ var CloudCatalogAdapter = class {
   constructor(options) {
     this.options = options;
   }
+  options;
   name = "cloud";
   async load(_projectRoot) {
     const headers = {
@@ -5073,14 +3517,19 @@ var CloudCatalogAdapter = class {
     }
     const raw = await response.json();
     const validateFixRaw = validateFixResponse && validateFixResponse.ok ? await validateFixResponse.json() : void 0;
-    const designSystem = mergeDesignSystemMetadata(
-      raw.designSystem,
-      validateFixRaw?.content?.designSystem
-    );
     const sourceComponents = chooseComponentSource({
       catalogComponents: raw.components ?? [],
       contextComponents: validateFixRaw?.content?.components ?? []
     });
+    const inferredDesignSystem = inferDesignSystemMetadataFromComponents(sourceComponents);
+    const designSystem = mergeDesignSystemMetadata(
+      {
+        ...raw.designSystem,
+        packageName: raw.designSystem?.packageName ?? inferredDesignSystem.packageName,
+        importPath: raw.designSystem?.importPath ?? inferredDesignSystem.importPath
+      },
+      validateFixRaw?.content?.designSystem
+    );
     const components = Object.fromEntries(
       sourceComponents.map((component) => [
         component.componentKey,
@@ -5147,7 +3596,7 @@ var CloudCatalogAdapter = class {
 };
 
 // src/adapters/bundle.ts
-import { existsSync as existsSync7 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { readFile as readFile2 } from "fs/promises";
 import { dirname as dirname3, resolve as resolve2 } from "path";
 import {
@@ -5155,6 +3604,7 @@ import {
   bundleManifestSchema,
   bundleTokenFileSchema
 } from "@fragments-sdk/core";
+import { BRAND as BRAND3 } from "@fragments-sdk/core";
 async function readJsonFile(path, parser, label) {
   const content = await readFile2(path, "utf-8");
   try {
@@ -5273,7 +3723,7 @@ var BundleAdapter = class {
     const manifests = this.discover(projectRoot);
     if (manifests.length === 0) {
       throw new Error(
-        `No ${BRAND.dataDir}/${BRAND.manifestFile} found. Run \`${BRAND.cliCommand} context install --cloud\` or commit a Fragments bundle into your workspace.`
+        `No ${BRAND3.dataDir}/${BRAND3.manifestFile} found. Run \`${BRAND3.cliCommand} context install --cloud\` or commit a Fragments bundle into your workspace.`
       );
     }
     const manifestPath = manifests[0];
@@ -5285,7 +3735,7 @@ var BundleAdapter = class {
     const bundleDir = dirname3(manifestPath);
     const repoRoot = dirname3(bundleDir);
     const tokensPath = resolve2(bundleDir, "tokens.json");
-    const tokensFile = existsSync7(tokensPath) ? await readJsonFile(tokensPath, bundleTokenFileSchema, "bundle tokens") : void 0;
+    const tokensFile = existsSync6(tokensPath) ? await readJsonFile(tokensPath, bundleTokenFileSchema, "bundle tokens") : void 0;
     const components = Object.fromEntries(
       await Promise.all(
         Object.values(manifest.components).map(async (entry) => {
@@ -5331,7 +3781,7 @@ var BundleAdapter = class {
     const snapshot = validateSnapshot({
       schemaVersion: 1,
       sourceType: "bundle",
-      sourceLabel: `${BRAND.dataDir}/${BRAND.manifestFile}`,
+      sourceLabel: `${BRAND3.dataDir}/${BRAND3.manifestFile}`,
       capabilities: buildCapabilities({
         components,
         tokens
@@ -5382,7 +3832,7 @@ function resolveCloudUrl2(fileConfig) {
   return fileConfig?.cloud?.url ?? process.env.FRAGMENTS_CLOUD_URL;
 }
 function hasTsProject(projectRoot) {
-  return existsSync8(join7(projectRoot, "tsconfig.json")) || existsSync8(join7(projectRoot, "tsconfig.app.json"));
+  return existsSync7(join6(projectRoot, "tsconfig.json")) || existsSync7(join6(projectRoot, "tsconfig.app.json"));
 }
 function resolveDataAdapter(config, fileConfig) {
   const source = config.source ?? fileConfig?.source ?? "auto";
@@ -5396,7 +3846,7 @@ function resolveDataAdapter(config, fileConfig) {
     case "cloud":
       if (!cloudApiKey) {
         throw new Error(
-          "Cloud source requires a Cloud API key. Set FRAGMENTS_API_KEY or pass cloudApiKey."
+          "Cloud source requires a Cloud API key. Pass --cloud-api-key, set FRAGMENTS_API_KEY, or configure cloud.apiKey in ds-mcp.config.json."
         );
       }
       return {
@@ -5440,7 +3890,142 @@ function resolveDataAdapter(config, fileConfig) {
   }
 }
 function resolveSearchApiKey(config, fileConfig) {
-  return config.searchApiKey ?? config.apiKey ?? fileConfig?.vectorSearch?.apiKey;
+  return config.searchApiKey ?? fileConfig?.vectorSearch?.apiKey;
+}
+
+// src/spec-schema.ts
+var UI_SPEC_SCHEMA_URI = "fragments://schemas/govern.schema";
+var UI_SPEC_SCHEMA_NAME = "govern.schema";
+var UI_SPEC_SCHEMA_MIME_TYPE = "application/schema+json";
+var UI_SPEC_SCHEMA_RESOURCE = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: UI_SPEC_SCHEMA_URI,
+  title: "Fragments UI Spec",
+  description: "Input shape accepted by the Fragments govern and validate_and_fix MCP tools.",
+  type: "object",
+  required: ["nodes"],
+  additionalProperties: false,
+  properties: {
+    root: {
+      type: "string",
+      description: "Optional node id to treat as the root. When omitted, top-level nodes are evaluated in order."
+    },
+    metadata: {
+      type: "object",
+      description: "Optional caller metadata. The validator stores and echoes only fields that downstream tools understand.",
+      additionalProperties: true
+    },
+    nodes: {
+      type: "array",
+      description: "Top-level UI nodes. Each node names a component type and may carry props plus nested children.",
+      items: { $ref: "#/$defs/node" }
+    }
+  },
+  $defs: {
+    node: {
+      type: "object",
+      required: ["type"],
+      additionalProperties: false,
+      properties: {
+        id: {
+          type: "string",
+          description: "Stable caller-provided id. Used in violations and fixedSpec patches."
+        },
+        type: {
+          type: "string",
+          description: 'Design-system component name, including compound names such as "DatePicker.Trigger".'
+        },
+        props: {
+          type: "object",
+          description: 'Component props. Put simple text labels in props.children, e.g. { "children": "Save" }.',
+          additionalProperties: true
+        },
+        children: {
+          description: "Nested child nodes, or a string text child for leaf content. Prefer props.children for simple button labels.",
+          oneOf: [
+            { type: "string" },
+            {
+              type: "array",
+              items: {
+                oneOf: [{ type: "string" }, { $ref: "#/$defs/node" }]
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  examples: {
+    valid: [
+      {
+        nodes: [
+          {
+            id: "save",
+            type: "Button",
+            props: { variant: "primary", children: "Save" }
+          }
+        ]
+      },
+      {
+        root: "card",
+        metadata: { source: "agent-draft" },
+        nodes: [
+          {
+            id: "card",
+            type: "Card",
+            props: {},
+            children: [
+              {
+                id: "title",
+                type: "Heading",
+                props: { level: 2, children: "Billing" }
+              },
+              {
+                id: "submit",
+                type: "Button",
+                props: { children: "Update plan" }
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    invalid: [
+      {
+        reason: "String event handlers are blocked by safety/no-string-handlers.",
+        spec: {
+          nodes: [
+            {
+              id: "danger",
+              type: "Button",
+              props: { children: "Save", onClick: 'alert("saved")' }
+            }
+          ]
+        }
+      },
+      {
+        reason: "Raw CSS values should use design tokens; call tokens.suggest before writing them.",
+        spec: {
+          nodes: [
+            {
+              id: "panel",
+              type: "Box",
+              props: { style: { padding: "6px" } }
+            }
+          ]
+        }
+      }
+    ]
+  },
+  notes: [
+    "Use component names from the active catalog; unknown components fail components/allow.",
+    "Use props.children for simple text labels, especially Button text.",
+    "Do not put JavaScript source strings in event handler props.",
+    "Run validate_and_fix after govern when the verdict asks for revision or deterministic repair."
+  ]
+};
+function serializeUiSpecSchema() {
+  return JSON.stringify(UI_SPEC_SCHEMA_RESOURCE, null, 2);
 }
 
 // src/server.ts
@@ -5452,12 +4037,13 @@ var TOOL_DEFINITION_BY_KEY = new Map(
 function createMcpServer(config) {
   const server = new Server(
     {
-      name: `${BRAND.nameLower}-mcp`,
+      name: `${BRAND4.nameLower}-mcp`,
       version: MCP_SERVER_VERSION
     },
     {
       capabilities: {
         tools: { listChanged: true },
+        resources: { listChanged: false },
         logging: {}
       }
     }
@@ -5488,21 +4074,20 @@ function createMcpServer(config) {
   let loadDataPromise = null;
   let resolvedRoot = null;
   let resolveProjectRootPromise = null;
-  let componentIndex = null;
-  let blockIndex = null;
-  let tokenIndex = null;
   async function resolveProjectRoot() {
     if (resolvedRoot) return resolvedRoot;
     if (resolveProjectRootPromise) return resolveProjectRootPromise;
     resolveProjectRootPromise = (async () => {
-      try {
-        const result2 = await server.listRoots();
-        if (result2.roots?.length > 0) {
-          const rootUri = result2.roots[0].uri;
-          resolvedRoot = fileURLToPath(rootUri);
-          return resolvedRoot;
+      if (server.getClientCapabilities()?.roots) {
+        try {
+          const result2 = await server.listRoots();
+          if (result2.roots?.length > 0) {
+            const rootUri = result2.roots[0].uri;
+            resolvedRoot = fileURLToPath(rootUri);
+            return resolvedRoot;
+          }
+        } catch {
         }
-      } catch {
       }
       resolvedRoot = config.projectRoot;
       return resolvedRoot;
@@ -5519,11 +4104,6 @@ function createMcpServer(config) {
     loadDataPromise = (async () => {
       const projectRoot = await resolveProjectRoot();
       const loaded = await adapter.load(projectRoot);
-      const allFragments = Object.values(loaded.components);
-      const allBlocks = Object.values(loaded.blocks ?? {});
-      componentIndex = buildComponentIndex(allFragments);
-      blockIndex = allBlocks.length > 0 ? buildBlockIndex(allBlocks) : null;
-      tokenIndex = loaded.tokens && loaded.tokens.total > 0 ? buildTokenIndex(loaded.tokens) : null;
       cachedData = loaded;
       return loaded;
     })();
@@ -5538,21 +4118,49 @@ function createMcpServer(config) {
     return {
       tools: registry.listTools(
         {
-          hasViewer: !!config.viewerUrl,
-          hasPlayground: !!(config.playgroundUrl ?? fileConfig?.playgroundUrl),
+          hasViewer: false,
+          hasPlayground: false,
           capabilities: data.capabilities
         },
         TOOLS
       )
     };
   });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+      {
+        uri: UI_SPEC_SCHEMA_URI,
+        name: UI_SPEC_SCHEMA_NAME,
+        title: "Fragments govern UI spec schema",
+        description: "JSON schema and examples for the spec argument accepted by govern and validate_and_fix.",
+        mimeType: UI_SPEC_SCHEMA_MIME_TYPE
+      }
+    ]
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri !== UI_SPEC_SCHEMA_URI) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `Unknown resource URI: ${request.params.uri}`
+      );
+    }
+    return {
+      contents: [
+        {
+          uri: UI_SPEC_SCHEMA_URI,
+          mimeType: UI_SPEC_SCHEMA_MIME_TYPE,
+          text: serializeUiSpecSchema()
+        }
+      ]
+    };
+  });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const data = await loadData();
     const toolContext = {
       data,
       config: mergedConfig,
-      indexes: { componentIndex, blockIndex, tokenIndex },
+      indexes: { componentIndex: null, blockIndex: null, tokenIndex: null },
       mcp: {
         server,
         clientCapabilities: server.getClientCapabilities()
@@ -5567,8 +4175,8 @@ function createMcpServer(config) {
           return "your-component-library";
         }
         const root = resolvedRoot ?? config.projectRoot;
-        const packageJsonPath = join8(root, "package.json");
-        if (existsSync9(packageJsonPath)) {
+        const packageJsonPath = join7(root, "package.json");
+        if (existsSync8(packageJsonPath)) {
           try {
             const content = readFileSync6(packageJsonPath, "utf-8");
             const pkg = JSON.parse(content);
@@ -5632,11 +4240,6 @@ function createSandboxServer() {
 
 export {
   loadConfigFile,
-  SYNONYM_MAP,
-  USE_CASE_TOKEN_CATEGORIES,
-  MINIMUM_SCORE_THRESHOLD,
-  BLOCK_BOOST_PER_OCCURRENCE,
-  DEFAULT_ENDPOINTS,
   CORE_TOOLS,
   VIEWER_TOOLS,
   INFRA_TOOLS,
@@ -5657,4 +4260,4 @@ export {
   startMcpServer,
   createSandboxServer
 };
-//# sourceMappingURL=chunk-YSNIGHNU.js.map
+//# sourceMappingURL=chunk-KGFM5SCE.js.map