onsystem 0.8.0 → 0.9.0

package/dist/{stdio-MTS6QAgo.js → stdio-B7u6dqLd.js}

@@ -1,5 +1,5 @@
-import { Ct as isInside, Dt as defaultProjectConfig, F as TOKEN_CATEGORIES, G as DEFAULT_SEVERITY, H as CONFIG_FILES, J as LEGACY_CONFIG_FILES, Q as excludedBy, St as SCRIPT_FILE, Tt as relativePath, Y as RULE_IDS, _ as NAME, at as LIBRARIES, bt as truncate, ct as notReadYet, d as searchComponents, et as loadConfig, ft as detectProject, m as uncheckedNotice, n as DesignSystemHost, ot as LIBRARY_IDS, pt as findDesignSystemPackage, rt as formatPx, st as libraryTitle, u as buildSearchIndex, v as VERSION, vt as closest, xt as unique, yt as plural } from "./design-system-Dmcv7eHR.js";
-import { n as hasProjectMarker, r as loadTarget, t as findProjectRoot } from "./workspace-CM1RyqZA.js";
+import { $ as LEGACY_CONFIG_FILES, At as relativePath, Ct as closest, Dt as SCRIPT_FILE, Et as unique, Mt as defaultProjectConfig, Ot as isInside, Tt as truncate, X as DEFAULT_SEVERITY, _t as detectProject, at as loadConfig, ct as formatPx, d as descriptionOf, dt as LIBRARY_IDS, et as RULE_IDS, f as searchComponents, ft as libraryTitle, h as uncheckedNotice, n as DesignSystemHost, pt as notReadYet, q as CONFIG_FILES, rt as excludedBy, u as buildSearchIndex, ut as LIBRARIES, v as NAME, vt as findDesignSystemPackage, wt as plural, y as VERSION, z as TOKEN_CATEGORIES } from "./design-system-Bykei5W0.js";
+import { n as hasProjectMarker, r as loadTarget, t as findProjectRoot } from "./workspace-Dp1q8qZ8.js";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -232,19 +232,122 @@ function importStatement(component) {
 function variantSummary(component) {
 	return component.variants.map((v) => `${v.name}: ${v.values.join(" | ")}${v.default ? ` (default ${v.default})` : ""}`);
 }
+/** An icon: a component that renders an <svg>. */
+function isIcon(component) {
+	return component.element === "svg";
+}
+/**
+* Icons from one import, or from the modules of one folder, are listed by name on one line from
+* this many on: a spinner or a logo is listed like the rest.
+*/
+const ICON_LINE = 5;
+/**
+* What list_components shows of `items`, after `filter`. `packageOf`: at a workspace root, the
+* package an item comes from, so two apps' `@/components/icons` are not taken for one.
+*/
+function listComponents(items, component, filter = {}, packageOf = () => "") {
+	const query = filter.query?.trim().toLowerCase();
+	const matching = items.filter((item) => {
+		const c = component(item);
+		if (filter.kind && filter.kind === "icon" !== isIcon(c)) return false;
+		const texts = [
+			c.name,
+			...c.aliases,
+			...c.subcomponents,
+			descriptionOf(c) ?? ""
+		];
+		return !query || texts.some((text) => text.toLowerCase().includes(query));
+	});
+	const icons = [];
+	if (!filter.kind) {
+		const group = (groups, item, from, folder) => {
+			const key = `${packageOf(item)}\0${from}`;
+			const known = groups.get(key) ?? {
+				from,
+				items: [],
+				...folder ? { folder } : {}
+			};
+			known.items.push(item);
+			groups.set(key, known);
+		};
+		const byImport = /* @__PURE__ */ new Map();
+		for (const item of matching) {
+			const c = component(item);
+			if (isIcon(c)) group(byImport, item, c.library ?? c.importPath);
+		}
+		const byFolder = /* @__PURE__ */ new Map();
+		for (const found of byImport.values()) {
+			if (found.items.length >= ICON_LINE) {
+				icons.push(found);
+				continue;
+			}
+			for (const item of found.items) {
+				const c = component(item);
+				const folder = c.importPath.slice(0, Math.max(0, c.importPath.lastIndexOf("/")));
+				if (!c.library && folder) group(byFolder, item, folder, true);
+			}
+		}
+		icons.push(...[...byFolder.values()].filter((found) => found.items.length >= ICON_LINE));
+	}
+	const inLine = new Set(icons.flatMap((found) => found.items));
+	const rest = matching.filter((item) => !inLine.has(item));
+	const shown = rest.slice(0, filter.limit ?? rest.length);
+	return {
+		shown,
+		icons,
+		matched: matching.length,
+		omitted: rest.length - shown.length
+	};
+}
+/** `query "chart" and kind "icon"`, or '' without filters. */
+function filterText(filter) {
+	return [filter.query?.trim() ? `query "${filter.query.trim()}"` : "", filter.kind ? `kind "${filter.kind}"` : ""].filter(Boolean).join(" and ");
+}
+/** The first line of a list: how many components there are, or how many match the filter. */
+function listHead(roots, parts, listed, filter) {
+	const filtered = filterText(filter);
+	if (filtered) return `${listed.matched} of ${plural(roots, "component")} match ${filtered}`;
+	return `${plural(roots, "component")}${parts ? ` (+${plural(parts, "part")})` : ""}`;
+}
+/**
+* `128 icons from "@dub/ui" (each renders <svg>; import { Name } from "@dub/ui"): Apple, Bolt`,
+* or for a module per icon, `6 icons in "@/components/icons" (each renders <svg>; import { Name }
+* from "@/components/icons/<module>"): CheckIcon (check), PlusIcon (plus)`.
+*/
+function iconLine(group) {
+	const { from, items } = group;
+	const count = plural(items.length, "icon");
+	if (!group.folder) return `${count} from "${from}" (each renders <svg>; import { Name } from "${from}"): ${items.map((c) => c.name).join(", ")}`;
+	return `${count} in "${from}" (each renders <svg>; import { Name } from "${from}/<module>"): ${items.map((c) => `${c.name} (${c.importPath.slice(from.length + 1)})`).join(", ")}`;
+}
+/** What a list says at its end about the icons it named and the components `limit` left out. */
+function listTail(listed) {
+	const lines = [];
+	if (listed.icons.length) lines.push("", "Pass kind \"icon\" to list the icons one by one.");
+	if (listed.omitted) lines.push("", `${listed.omitted.toLocaleString("en-US")} more not shown: pass a higher \`limit\`, or a \`query\`.`);
+	return lines;
+}
 /** `project`: the folder of a workspace root's project the list is for. */
-function renderComponentList(ds, project) {
+function renderComponentList(ds, project, filter = {}) {
 	const roots = ds.roots();
-	if (!roots.length) return `No components found${project ? ` in ${project}` : ""}. Check the "components" globs in the config (root: ${ds.root}).`;
+	const where = project ? ` in ${project}` : "";
+	if (!roots.length) return `No components found${where}. Check the "components" globs in the config (root: ${ds.root}).`;
+	const listed = listComponents(roots, (c) => c, filter);
+	if (!listed.matched) return `No components match ${filterText(filter)}${where} (${roots.length} in all). Call list_components without filters to see them.`;
 	const parts = ds.components.length - roots.length;
-	const lines = [`${plural(roots.length, "component")}${parts ? ` (+${plural(parts, "part")})` : ""}${project ? ` in ${project}` : ""}. Call get_component before using one.`, ""];
-	const own = roots.filter((c) => !c.library);
+	const lines = [`${listHead(roots.length, parts, listed, filter)}${where}. Call get_component before using one.`, ""];
+	const own = listed.shown.filter((c) => !c.library);
 	for (const component of own) lines.push(...listItem(component, registryNote(ds, component)));
-	for (const library of new Set(roots.flatMap((c) => c.library ? [c.library] : []))) {
+	for (const library of new Set(listed.shown.flatMap((c) => c.library ? [c.library] : []))) {
 		if (own.length) lines.push("");
 		lines.push(`From ${library} (import { Name } from "${library}"):`, "");
-		for (const component of roots.filter((c) => c.library === library)) lines.push(...listItem(component, "", false));
+		for (const component of listed.shown.filter((c) => c.library === library)) lines.push(...listItem(component, "", false));
+	}
+	for (const group of listed.icons) {
+		if (lines.at(-1) !== "") lines.push("");
+		lines.push(iconLine(group));
 	}
+	lines.push(...listTail(listed));
 	return lines.join("\n");
 }
 /** ` (from @signoff-ui, read-only)` for a component copied from a shadcn registry. */
@@ -254,7 +357,8 @@ function registryNote(ds, component) {
 }
 function listItem(component, note = "", withImport = true) {
 	const element = component.element ? ` <${component.element}>` : "";
-	const lines = [`${component.name}${element}${note} — ${firstSentence(component.description) || "No description."}`];
+	const description = firstSentence(descriptionOf(component));
+	const lines = [`${component.name}${element}${note}${description ? ` — ${description}` : ""}`];
 	for (const variant of variantSummary(component)) lines.push(`  ${variant}`);
 	if (component.subcomponents.length) lines.push(`  parts: ${component.subcomponents.join(", ")}`);
 	if (withImport) lines.push(`  ${importStatement(component)}`);
@@ -268,22 +372,44 @@ function listOf$1(items, max = 3) {
 }
 const PICK_PROJECT = "This is a monorepo root: pass `path`, the file you are editing, to get_component, get_tokens and check_ui so they answer for its project.";
 /** Every project's components at a workspace root, grouped by the package they come from. */
-function renderCatalogList(catalog) {
+function renderCatalogList(catalog, filter = {}) {
 	const roots = catalog.roots();
 	if (!roots.length) return `No components found in any project of this monorepo (root: ${catalog.root}). Run \`onsystem inspect\` there to see what was looked at.`;
-	const byPackage = /* @__PURE__ */ new Map();
-	for (const entry of roots) byPackage.set(entry.package, [...byPackage.get(entry.package) ?? [], entry]);
+	const listed = listComponents(roots, (e) => e.component, filter, (e) => e.package);
+	if (!listed.matched) return `No components match ${filterText(filter)} in any project (${roots.length} in all). Call list_components without filters to see them.`;
+	const packages = new Set(roots.map((e) => e.package));
 	const parts = catalog.entries.length - roots.length;
-	const lines = [`${plural(roots.length, "component")}${parts ? ` (+${plural(parts, "part")})` : ""} from ${plural(byPackage.size, "package")}, used by ${plural(catalog.projects.length, "project")}. ${PICK_PROJECT}`];
-	for (const [pkg, entries] of byPackage) {
-		const projects = [...new Set(entries.flatMap((e) => e.projects))];
+	const lines = [`${listHead(roots.length, parts, listed, filter)} from ${plural(packages.size, "package")}, used by ${plural(catalog.projects.length, "project")}. ${PICK_PROJECT}`];
+	const byPackage = /* @__PURE__ */ new Map();
+	const section = (pkg) => {
+		const known = byPackage.get(pkg) ?? {
+			entries: [],
+			icons: []
+		};
+		byPackage.set(pkg, known);
+		return known;
+	};
+	for (const entry of listed.shown) section(entry.package).entries.push(entry);
+	for (const group of listed.icons) {
+		const [first] = group.items;
+		const items = group.items.map((e) => e.component);
+		if (first) section(first.package).icons.push(iconLine({
+			...group,
+			items
+		}));
+	}
+	for (const [pkg, { entries, icons }] of byPackage) {
+		const projects = [...new Set(roots.filter((e) => e.package === pkg).flatMap((e) => e.projects))];
 		lines.push("", `## ${pkg} (used by ${listOf$1(projects)})`);
 		for (const entry of entries) {
-			const others = entry.ambiguous ? catalog.roots().filter((e) => e !== entry && e.component.name === entry.component.name) : [];
+			const others = entry.ambiguous ? roots.filter((e) => e !== entry && e.component.name === entry.component.name) : [];
 			const note = others.length ? ` (also in ${[...new Set(others.map((e) => e.package))].join(", ")})` : "";
 			lines.push(...listItem(entry.component, note));
 		}
+		if (entries.length && icons.length) lines.push("");
+		lines.push(...icons);
 	}
+	lines.push(...listTail(listed));
 	return lines.join("\n");
 }
 /** Several components under one name at a workspace root, and how to pick one. */
@@ -362,18 +488,26 @@ const REACT_ARIA_NOTABLE = [
 	"isReadOnly",
 	"autoFocus"
 ];
+/**
+* A prop's description longer than this is cut to its first sentence: a primitive library's
+* JSDoc (Base UI's, Radix's) runs to paragraphs per prop, and the structured content has it all.
+*/
+const PROP_LINE = 160;
 function renderProp(prop) {
 	const optional = prop.required ? "" : "?";
 	const fallback = prop.default !== void 0 ? ` = ${prop.default}` : "";
 	const deprecated = prop.deprecated ? ` DEPRECATED${prop.deprecated === true ? "" : `: ${prop.deprecated}`}.` : "";
-	const description = prop.description ? ` — ${prop.description.replace(/\s*\n\s*/g, " ")}` : "";
+	const text = prop.description?.replace(/\s*\n\s*/g, " ").trim();
+	const line = text && text.length > PROP_LINE ? firstSentence(text, PROP_LINE) : text;
+	const description = line ? ` — ${line}` : "";
 	return `- ${prop.name}${optional}: ${prop.type}${fallback}${description}${deprecated}`;
 }
 /** `origin`: at a workspace root, the package the component comes from and who uses it. */
 function renderComponent(ds, component, origin) {
 	const lines = [`# ${component.name}`];
 	if (component.deprecated) lines.push(`DEPRECATED${component.deprecated === true ? "" : `: ${component.deprecated}`}`);
-	if (component.description) lines.push(component.description);
+	const description = descriptionOf(component);
+	if (description) lines.push(description);
 	lines.push("", importStatement(component));
 	const facts = [
 		component.element ? `Renders <${component.element}>` : void 0,
@@ -386,6 +520,13 @@ function renderComponent(ds, component, origin) {
 	if (origin) lines.push(`From ${origin.package}, used by ${listOf$1(origin.projects)}.`);
 	const registry = ds.registryOf(component);
 	if (registry) lines.push(`Installed from the shadcn registry ${registry.registry} into ${registry.folder}: use it as it is. Its code is the registry's, so change it upstream, not here; \`npx shadcn add --overwrite\` replaces the file.`);
+	if (component.subcomponents.length) {
+		lines.push("", "## Parts");
+		for (const name of component.subcomponents) {
+			const part = ds.getComponent(name);
+			lines.push(`- ${name}${part?.description ? ` — ${firstSentence(part.description)}` : ""}`);
+		}
+	}
 	lines.push("", "## Props");
 	if (!component.props.length && !component.inherits.length) lines.push("No props.");
 	for (const prop of component.props) lines.push(renderProp(prop));
@@ -411,13 +552,6 @@ function renderComponent(ds, component, origin) {
 			lines.push(`  when ${when}: ${compound.classes}`);
 		}
 	}
-	if (component.subcomponents.length) {
-		lines.push("", "## Parts");
-		for (const name of component.subcomponents) {
-			const part = ds.getComponent(name);
-			lines.push(`- ${name}${part?.description ? ` — ${firstSentence(part.description)}` : ""}`);
-		}
-	}
 	const tokens = ds.relatedTokens(component);
 	if (tokens.length) {
 		lines.push("", "## Design tokens used");
@@ -440,31 +574,63 @@ function renderComponent(ds, component, origin) {
 	}
 	return lines.join("\n");
 }
+/** The first line of search results: best first, or, when none clearly matches, that none does. */
+function searchHead(query, hits, where = "") {
+	return hits.every((hit) => hit.weak) ? `No component clearly matches "${query}"${where}. The nearest have only a word or two in common with it:` : `Components for "${query}"${where}, best first:`;
+}
+/** The last line of search results. */
+function searchTail(hits) {
+	return hits.every((hit) => hit.weak) ? "If none of them fits, the design system may have no component for this: ask, or build it from the components it has (list_components). Call get_component before using one." : "Call get_component for props, variants and examples.";
+}
+/** `1. CardHeader (part of Card) — Top section of a card.` */
+function searchItem(index, component, from = "") {
+	const parent = component.parent ? ` (part of ${component.parent})` : "";
+	const description = firstSentence(descriptionOf(component));
+	return `${index + 1}. ${component.name}${parent}${from}${description ? ` — ${description}` : ""}`;
+}
 function renderSearch(query, hits) {
 	if (!hits.length) return `No components match "${query}". Try other words, or list_components to browse.`;
-	const lines = [`Components for "${query}", best first:`, ""];
+	const lines = [searchHead(query, hits), ""];
 	hits.forEach((hit, i) => {
 		const c = hit.component;
-		const parent = c.parent ? ` (part of ${c.parent})` : "";
-		lines.push(`${i + 1}. ${c.name}${parent} — ${firstSentence(c.description) || "No description."}`);
+		lines.push(searchItem(i, c));
 		lines.push(`   score ${hit.score} · matched: ${hit.matched.join(", ")} · ${importStatement(c)}`);
 	});
-	lines.push("", "Call get_component for props, variants and examples.");
+	lines.push("", searchTail(hits));
 	return lines.join("\n");
 }
 /** Search hits at a workspace root, each with the package it comes from. */
 function renderCatalogSearch(query, hits) {
 	if (!hits.length) return `No components match "${query}" in any project. Try other words, or list_components to browse.`;
-	const lines = [`Components for "${query}" across the monorepo's projects, best first:`, ""];
+	const lines = [searchHead(query, hits, " across the monorepo's projects"), ""];
 	hits.forEach((hit, i) => {
 		const c = hit.component;
-		const parent = c.parent ? ` (part of ${c.parent})` : "";
-		lines.push(`${i + 1}. ${c.name}${parent} from ${hit.entry.package} — ${firstSentence(c.description) || "No description."}`);
+		lines.push(searchItem(i, c, ` from ${hit.entry.package}`));
 		lines.push(`   score ${hit.score} · matched: ${hit.matched.join(", ")} · used by ${listOf$1(hit.entry.projects)} · ${importStatement(c)}`);
 	});
-	lines.push("", `Call get_component for props, variants and examples. ${PICK_PROJECT}`);
+	lines.push("", `${searchTail(hits)} ${PICK_PROJECT}`);
 	return lines.join("\n");
 }
+/**
+* Where a token is listed in get_tokens: under its category, or, for a color of a scoped
+* family (`chart-*`, `sidebar-*`, the syntax colors one file uses), under that family, with
+* what it is for. An agent looking for a green with no `--success` in the theme otherwise finds
+* `chart-2` among the colors, takes its dark value, and check_ui has nothing against it.
+*/
+function tokenGroup(ds, token) {
+	const family = ds.tokenIndex.scopedFamilyOf(token);
+	return family === void 0 ? token.category : `${SCOPED}${family}`;
+}
+/** Marks a scoped family's group: no category starts with it. */
+const SCOPED = "\0";
+function groupHeading(ds, group, count) {
+	if (!group.startsWith(SCOPED)) return `## ${group} (${count})`;
+	const family = group.slice(1);
+	if (family === "chart") return `## chart (${count}): for charts only, not for status colors`;
+	if (family === "sidebar") return `## sidebar (${count}): for the sidebar only, not for status colors`;
+	const [file] = ds.tokenIndex.familyFiles.get(family) ?? [];
+	return `## ${family} (${count}): for one part of the UI only${file ? ` (${file} uses them)` : ""}, not for status colors`;
+}
 /** Tokens at a workspace root, grouped by category, each with the package that defines it. */
 function renderCatalogTokens(catalog, tokens, filter = {}) {
 	if (!catalog.tokens.length) return `No design tokens found in any project of this monorepo (root: ${catalog.root}). Set "tokens" in a project's config: https://onsystem.vercel.app/docs/configuration`;
@@ -473,10 +639,18 @@ function renderCatalogTokens(catalog, tokens, filter = {}) {
 		return `No tokens match${what ? ` ${what}` : ""} in any project; call get_tokens without filters to see them.`;
 	}
 	const groups = /* @__PURE__ */ new Map();
-	for (const t of tokens) groups.set(t.token.category, [...groups.get(t.token.category) ?? [], t]);
+	for (const t of tokens) {
+		const key = tokenGroup(t.ds, t.token);
+		const group = groups.get(key) ?? {
+			ds: t.ds,
+			list: []
+		};
+		group.list.push(t);
+		groups.set(key, group);
+	}
 	const lines = [PICK_PROJECT, ""];
-	for (const [category, list] of groups) {
-		lines.push(`## ${category} (${list.length})`);
+	for (const [key, { ds, list }] of groups) {
+		lines.push(groupHeading(ds, key, list.length));
 		for (const { token, package: pkg } of list) {
 			const usage = token.usage.length ? ` → ${token.usage.join(", ")}` : "";
 			lines.push(`- ${token.name}: ${token.value}${usage} (${pkg})`);
@@ -495,10 +669,13 @@ function renderTokens(ds, tokens, filter = {}) {
 		return `No tokens match${what ? ` ${what}` : ""}. The design system has ${categories}; call get_tokens without filters to see them.`;
 	}
 	const groups = /* @__PURE__ */ new Map();
-	for (const token of tokens) groups.set(token.category, [...groups.get(token.category) ?? [], token]);
+	for (const token of tokens) {
+		const group = tokenGroup(ds, token);
+		groups.set(group, [...groups.get(group) ?? [], token]);
+	}
 	const lines = [];
-	for (const [category, list] of groups) {
-		lines.push(`## ${category} (${list.length})`);
+	for (const [group, list] of groups) {
+		lines.push(groupHeading(ds, group, list.length));
 		for (const token of list) {
 			const px = token.category === "spacing" || token.category === "radius" ? ds.tokenIndex.toPx(token.value) : void 0;
 			const value = px !== void 0 && !/^-?[\d.]+px$/.test(token.value) ? `${token.value} = ${formatPx(px)}` : token.value;
@@ -548,7 +725,7 @@ const INSTRUCTIONS = `This server describes the project's design system: its Rea
 When writing or changing UI in this project:
 1. Find components with search_components (by intent) or list_components.
 2. Read get_component before using a component: use only the props and variant values it lists.
-3. Style with tokens from get_tokens, never with hex/rgb colors, arbitrary px values or Tailwind's default palette.
+3. Style with tokens from get_tokens, never with hex/rgb colors, arbitrary px values or Tailwind's default palette. chart-* and sidebar-* tokens are for charts and the sidebar only: for a status color the theme has no token for (success, warning, info), add a token or keep the Tailwind color as check_ui says, and never use a chart-* or sidebar-* token for it.
 4. Run check_ui on every snippet or file you write and fix all errors before you finish.
 In a monorepo served from its root, pass \`path\` (the file you are editing) to list_components, get_component, search_components and get_tokens, and \`path\` or \`filename\` to check_ui, so each answer comes from that file's own project.`;
 const READ_ONLY = {
@@ -575,9 +752,12 @@ const MAX_CODE = 1e6;
 /** Diagnostics check_ui returns by default: a 3,000-line file can have thousands, more than a context holds. */
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 1e3;
-/** check_ui's answer for a path or filename that is not JS or TS. */
-function notScript(name) {
-	return errorResult(`check_ui checks .tsx, .jsx, .ts and .js files; ${name} is not one, so it was not checked.`);
+/**
+* check_ui's answer for a path or filename that is not JS or TS. `fix`: what to do instead,
+* for a `filename` given with code (the code itself may be fine).
+*/
+function notScript(name, fix = "") {
+	return errorResult(`check_ui checks .tsx, .jsx, .ts and .js files; ${name} is not one, so it was not checked.${fix}`);
 }
 /**
 * An integer, without the ±9007199254740991 bounds zod adds to the JSON Schema,
@@ -675,8 +855,8 @@ const componentSummarySchema = z.object({
 	description: z.string().optional(),
 	importPath: z.string(),
 	element: z.string().optional(),
-	variants: z.record(z.string(), z.array(z.string())),
-	subcomponents: z.array(z.string()),
+	variants: z.record(z.string(), z.array(z.string())).optional().describe("Left out when none."),
+	subcomponents: z.array(z.string()).optional().describe("Left out when none."),
 	...originShape
 });
 const tokenSchema = z.object({
@@ -733,14 +913,58 @@ function origin(entry) {
 		projects: entry.projects
 	};
 }
+/** A component in list_components, without the fields it has nothing in. */
 function summary(c) {
+	const description = descriptionOf(c);
 	return {
 		name: c.name,
-		...c.description ? { description: c.description } : {},
+		...description ? { description } : {},
 		importPath: c.importPath,
 		...c.element ? { element: c.element } : {},
-		variants: Object.fromEntries(c.variants.map((v) => [v.name, v.values])),
-		subcomponents: c.subcomponents
+		...c.variants.length ? { variants: Object.fromEntries(c.variants.map((v) => [v.name, v.values])) } : {},
+		...c.subcomponents.length ? { subcomponents: c.subcomponents } : {}
+	};
+}
+/** list_components' structured content: what its text lists, as it lists it. */
+function listContent(listed, component, originOf) {
+	return {
+		components: listed.shown.map((item) => ({
+			...summary(component(item)),
+			...originOf?.(item)
+		})),
+		...listed.icons.length ? { icons: listed.icons.map(({ from, items, folder }) => ({
+			from,
+			names: items.map((item) => component(item).name),
+			...folder ? { modules: items.map((item) => component(item).importPath) } : {},
+			...originOf && items[0] ? { package: originOf(items[0]).package } : {}
+		})) } : {},
+		...listed.omitted ? { omitted: listed.omitted } : {}
+	};
+}
+/**
+* Said above a component asked for by a name that is not how its design system writes it:
+* `Card.Header` finds CardHeader, and code written as asked would not compile.
+*/
+function nameNotice(asked, component) {
+	if (asked === component.name || component.aliases.includes(asked)) return "";
+	if (!asked.includes(".") && !component.name.includes(".")) return "";
+	return `There is no \`${asked}\` in this design system: write \`<${component.name}>\`.\n\n`;
+}
+function resourceDescription(component) {
+	const description = descriptionOf(component);
+	return description ? { description } : {};
+}
+/** A search_components result. */
+function result(hit) {
+	const description = descriptionOf(hit.component);
+	return {
+		name: hit.component.name,
+		...hit.component.parent ? { parent: hit.component.parent } : {},
+		...description ? { description } : {},
+		importPath: hit.component.importPath,
+		score: hit.score,
+		matched: hit.matched,
+		...hit.weak ? { weak: true } : {}
 	};
 }
 /** Builds the MCP server: five tools, two resources and one prompt. Transport-agnostic. */
@@ -798,33 +1022,51 @@ function createServer({ getDesignSystem, getProjects }) {
 	};
 	server.registerTool("list_components", {
 		title: "List design-system components",
-		description: "List every component in the project design system with a one-line description, the native element it renders, its variant values, its parts and its import. Call this before writing UI in this project. At a monorepo root, pass `path` for the project of the file you are editing; without it, every project is listed, each component with its package.",
-		inputSchema: z.object({ path: projectPath }),
-		outputSchema: z.object({ components: z.array(componentSummarySchema) }),
+		description: "List every component in the project design system with a one-line description, the native element it renders, its variant values, its parts and its import. Icons (components that render an <svg>) are named on one line per import, or per folder for icons with a module each, five or more to a line. Call this before writing UI in this project. `query`, `kind` and `limit` narrow a long list. At a monorepo root, pass `path` for the project of the file you are editing; without it, every project is listed, each component with its package.",
+		inputSchema: z.object({
+			query: z.string().max(MAX_QUERY).optional().describe("Only components with this text in their name, their parts' names or their description."),
+			kind: z.enum(["component", "icon"]).optional().describe("\"icon\": only the components that render an <svg>, one by one. \"component\": all the others."),
+			limit: z.number().int().min(1).max(MAX_LIMIT).optional().describe("Most components to list one by one."),
+			path: projectPath
+		}),
+		outputSchema: z.object({
+			components: z.array(componentSummarySchema).describe("The components listed one by one, after `query`, `kind` and `limit`."),
+			icons: z.array(z.object({
+				from: z.string().describe("The module they are imported from, or, with `modules`, the folder of their modules."),
+				names: z.array(z.string()),
+				modules: z.array(z.string()).optional().describe("For icons with a module each: each one's module, in the order of `names`."),
+				package: originShape.package
+			})).optional().describe("Without `kind`: icons, the components that render an <svg>, by name, five or more per module, or per folder for icons with a module each."),
+			omitted: int().optional().describe("Matching components left out by `limit`.")
+		}),
 		annotations: READ_ONLY
-	}, async ({ path: target }) => {
+	}, async ({ query, kind, limit, path: target }) => {
 		const found = await scoped(target);
 		if (isResult(found)) return found;
+		const filter = {
+			query,
+			kind,
+			limit
+		};
 		if ("catalog" in found) {
 			const { catalog } = found;
+			const listed = listComponents(catalog.roots(), (entry) => entry.component, filter, (entry) => entry.package);
 			return {
 				content: [{
 					type: "text",
-					text: renderCatalogList(catalog)
+					text: renderCatalogList(catalog, filter)
 				}],
-				structuredContent: { components: catalog.roots().map((entry) => ({
-					...summary(entry.component),
-					...origin(entry)
-				})) }
+				structuredContent: listContent(listed, (entry) => entry.component, origin)
 			};
 		}
 		const { ds } = found;
+		const listed = listComponents(ds.roots(), (c) => c, filter);
 		return {
 			content: [{
 				type: "text",
-				text: renderComponentList(ds, found.project?.dir)
+				text: renderComponentList(ds, found.project?.dir, filter)
 			}],
-			structuredContent: { components: ds.roots().map(summary) }
+			structuredContent: listContent(listed, (c) => c)
 		};
 	});
 	server.registerTool("get_component", {
@@ -849,13 +1091,15 @@ function createServer({ getDesignSystem, getProjects }) {
 				return errorResult(`No component named "${name}" in any project.` + (guess ? ` Did you mean "${guess}"?` : "") + ` Available: ${names.join(", ")}.`);
 			}
 			if (matches.length > 1) return errorResult(renderAmbiguous(name, matches));
+			const description = descriptionOf(entry.component);
 			return {
 				content: [{
 					type: "text",
-					text: renderComponent(entry.ds, entry.component, entry)
+					text: nameNotice(name, entry.component) + renderComponent(entry.ds, entry.component, entry)
 				}],
 				structuredContent: {
 					...entry.component,
+					...description ? { description } : {},
 					import: importStatement(entry.component),
 					tokens: entry.ds.relatedTokens(entry.component).map((t) => t.name),
 					...origin(entry)
@@ -875,13 +1119,15 @@ function createServer({ getDesignSystem, getProjects }) {
 			};
 		}
 		const shown = fromRoot(ds, component, found.root);
+		const description = descriptionOf(component);
 		return {
 			content: [{
 				type: "text",
-				text: renderComponent(ds, shown)
+				text: nameNotice(name, component) + renderComponent(ds, shown)
 			}],
 			structuredContent: {
 				...shown,
+				...description ? { description } : {},
 				import: importStatement(component),
 				tokens: ds.relatedTokens(component).map((t) => t.name)
 			}
@@ -889,7 +1135,7 @@ function createServer({ getDesignSystem, getProjects }) {
 	});
 	server.registerTool("search_components", {
 		title: "Search components by intent",
-		description: "Find components by what you want to build, e.g. \"confirm a destructive action\", \"status label\", \"text field with validation\". Ranks names, descriptions, docs, props and variant values with BM25 (local, no API key). Use it when you do not know which component fits.",
+		description: "Find components by what you want to build, e.g. \"confirm a destructive action\", \"status label\", \"text field with validation\". Ranks names, descriptions, docs, props and variant values with BM25 (local, no API key). When no component clearly matches, it says so and lists the nearest, marked `weak`. Use it when you do not know which component fits.",
 		inputSchema: z.object({
 			query: z.string().min(1).max(MAX_QUERY).describe("What the UI should do, in plain words."),
 			limit: z.number().int().min(1).max(20).default(5).describe("Maximum results."),
@@ -902,6 +1148,7 @@ function createServer({ getDesignSystem, getProjects }) {
 			importPath: z.string(),
 			score: z.number(),
 			matched: z.array(z.string()),
+			weak: z.boolean().optional().describe("Set when no component clearly matches the query: each result has only a word or two in common with it."),
 			...originShape
 		})) }),
 		annotations: READ_ONLY
@@ -916,12 +1163,7 @@ function createServer({ getDesignSystem, getProjects }) {
 					text: renderCatalogSearch(query, hits)
 				}],
 				structuredContent: { results: hits.map((h) => ({
-					name: h.component.name,
-					...h.component.parent ? { parent: h.component.parent } : {},
-					...h.component.description ? { description: h.component.description } : {},
-					importPath: h.component.importPath,
-					score: h.score,
-					matched: h.matched,
+					...result(h),
 					...origin(h.entry)
 				})) }
 			};
@@ -933,19 +1175,12 @@ function createServer({ getDesignSystem, getProjects }) {
 				type: "text",
 				text: renderSearch(query, hits)
 			}],
-			structuredContent: { results: hits.map((h) => ({
-				name: h.component.name,
-				...h.component.parent ? { parent: h.component.parent } : {},
-				...h.component.description ? { description: h.component.description } : {},
-				importPath: h.component.importPath,
-				score: h.score,
-				matched: h.matched
-			})) }
+			structuredContent: { results: hits.map(result) }
 		};
 	});
 	server.registerTool("get_tokens", {
 		title: "Get design tokens",
-		description: "List design tokens with resolved values, dark-mode values and how to use each (Tailwind class or CSS variable). Filter by category (color, spacing, radius, typography, shadow, other) or a substring. Use these instead of hex codes, px values or Tailwind default palette classes.",
+		description: "List design tokens with resolved values, dark-mode values and how to use each (Tailwind class or CSS variable). Filter by category (color, spacing, radius, typography, shadow, other) or a substring. Use these instead of hex codes, px values or Tailwind default palette classes. Chart and sidebar colors are listed under their own headings: they are for charts and the sidebar, not for status colors.",
 		inputSchema: z.object({
 			category: z.enum(TOKEN_CATEGORIES).optional().describe("Only tokens of this category."),
 			query: z.string().max(MAX_QUERY).optional().describe("Substring to match in names, usages or descriptions."),
@@ -1010,10 +1245,10 @@ function createServer({ getDesignSystem, getProjects }) {
 	});
 	server.registerTool("check_ui", {
 		title: "Check UI code against the design system",
-		description: "Lint TSX/JSX against the design system. Reports hardcoded colors, spacing and radius (with the nearest token), native elements that have a design-system component, unknown components, props and variant values, and icon-only buttons without an accessible name. Each diagnostic has line/column, a rule id, a message and a suggested fix. Run it on every snippet or file you write and fix all errors. Pass `code` for unsaved code, or `path` for a file in the project.",
+		description: "Lint TSX/JSX against the design system. Reports hardcoded colors, spacing and radius (with the nearest token), native elements that have a design-system component, unknown components, props and variant values, and icon-only buttons without an accessible name. Each diagnostic has line/column, a rule id, a message and a suggested fix. Run it on every snippet or file you write and fix all errors. Pass `path` for a file in the project, or `code` for unsaved code, with `path` (or `filename`) naming the file it is for or its project folder.",
 		inputSchema: z.object({
 			code: z.string().max(MAX_CODE).optional().describe(`TSX/JSX source to check (up to ${MAX_CODE.toLocaleString("en")} characters).`),
-			path: z.string().max(MAX_PATH).optional().describe("Path of a .tsx, .jsx, .ts or .js file to check: relative to the project root (the monorepo root, when served from there), or absolute."),
+			path: z.string().max(MAX_PATH).optional().describe("Path of a .tsx, .jsx, .ts or .js file, relative to the project root (the monorepo root, when served from there) or absolute: the file to check, or, with `code`, the file the code is for, as `filename`. With `code`, a project folder only picks the project."),
 			filename: z.string().max(MAX_PATH).optional().describe("Name to report `code` under; a .jsx extension parses it as JSX. At a monorepo root, the path the code will be saved under, which picks the project whose design system checks it. When the server was started outside your project, pass it as an absolute path: the project is found from it."),
 			limit: z.number().int().min(1).max(MAX_LIMIT).default(DEFAULT_LIMIT).describe(`Most diagnostics to return, errors first (default ${DEFAULT_LIMIT}). The counts and byRule cover all of them.`)
 		}),
@@ -1036,11 +1271,14 @@ function createServer({ getDesignSystem, getProjects }) {
 			notice: z.string().optional().describe("Set when no components or no color tokens were found, so rules did not run, when components came from modules the model does not include, when the project depends on a component library onsystem does not read yet, or when its dependencies are not installed.")
 		}),
 		annotations: READ_ONLY
-	}, async ({ code, path: filePath, filename, limit }) => {
+	}, async ({ code, path: filePath, filename: given, limit }) => {
 		if (code === void 0 && !filePath) return errorResult("Pass either `code` or `path`.");
-		if (code !== void 0 && filename !== void 0 && !SCRIPT_FILE.test(filename)) return notScript(filename);
-		const routeBy = code === void 0 ? filePath : filename ?? void 0;
+		if (code !== void 0 && given !== void 0 && !SCRIPT_FILE.test(given)) return notScript(given, " Pass as `filename` the .tsx path the code is for, or leave `filename` out.");
+		const folder = code !== void 0 && filePath && !SCRIPT_FILE.test(filePath) ? filePath : void 0;
+		const filename = code === void 0 || folder !== void 0 ? given : given ?? (filePath || void 0);
+		let routeBy = code === void 0 ? filePath : filename ?? folder;
 		const set = await getProjects?.(routeBy);
+		if (set && folder !== void 0 && routeBy === folder && path.resolve(set.root, folder) === set.root && !set.dirs.includes(".")) routeBy = void 0;
 		let ds;
 		if (!set) ds = await getDesignSystem(routeBy);
 		else if (routeBy) {
@@ -1128,14 +1366,14 @@ function createServer({ getDesignSystem, getProjects }) {
 				uri: `ds://components/${c.name}${ambiguous ? `?path=${encodeURIComponent(projects[0] ?? ".")}` : ""}`,
 				name: c.name,
 				title: c.name,
-				...c.description ? { description: c.description } : {},
+				...resourceDescription(c),
 				mimeType: "text/markdown"
 			})) };
 			return { resources: found.ds.components.map((c) => ({
 				uri: `ds://components/${c.name}`,
 				name: c.name,
 				title: c.name,
-				...c.description ? { description: c.description } : {},
+				...resourceDescription(c),
 				mimeType: "text/markdown"
 			})) };
 		},
@@ -1216,8 +1454,8 @@ function createServer({ getDesignSystem, getProjects }) {
 
 Work like this:
 1. Find components: search_components for each piece of the UI (for example "confirm a destructive action"), or list_components for an overview.
-2. Read the contract: get_component for every component you use. Use only the props and variant values it lists, and compose parts the way its examples do.
-3. Style with tokens: get_tokens when you need a color, spacing or radius. Never write hex/rgb colors, arbitrary px values or Tailwind default palette classes such as bg-blue-500.
+2. Read the contract: get_component for every component you use. Use only the props and variant values it lists, and compose its parts as its docs and examples show, when it has them.
+3. Style with tokens: get_tokens when you need a color, spacing or radius. Never write hex/rgb colors, arbitrary px values or Tailwind default palette classes such as bg-blue-500. chart-* and sidebar-* tokens are for charts and the sidebar only: for a status color the theme has no token for (success, warning, info), add a token or keep the Tailwind color as check_ui says, and never use a chart-* or sidebar-* token for it.
 4. Use design-system components instead of native elements (<Button>, not <button>).
 5. Verify: run check_ui on the code you wrote, fix every error, and run it again until it reports none.