@zyncat/ui 0.11.0 → 0.13.0

package/dist/mcp.js

@@ -1,16 +1,143 @@
 #!/usr/bin/env node
 
 // src/mcp/server.ts
-import { existsSync, readFileSync, readdirSync } from "fs";
-import { dirname, join } from "path";
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join2, relative, resolve } from "path";
 import { fileURLToPath } from "url";
+
+// scripts/lib/usage-format.mjs
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var HEADING_RE = /^# ([A-Za-z][\w /-]*?) - @zyncat\/ui\/([a-z][a-z0-9-]*)\s*$/;
+var META_RE = /^(Group|Docs): (.+?)\s*$/;
+var FENCE_RE = /^```(\w*)\s*$/;
+var GROUPS = [
+  { id: "primitives", title: "Primitives", note: "" },
+  {
+    id: "forms",
+    title: "Forms",
+    note: "Every form field takes label, helper/error/warning/success, size sm|md|lg, disabled."
+  },
+  { id: "data-display", title: "Data display", note: "" },
+  {
+    id: "date-time",
+    title: "Date, time & tabs",
+    note: "The date and time fields share: value is a string, onChange(value | null), timezone, min/max, disabled."
+  },
+  { id: "overlays", title: "Overlays & feedback", note: "" },
+  {
+    id: "expressive",
+    title: "Expressive",
+    note: "Creative motion components. Each publishes scoped --<component>-* custom properties as its theming surface."
+  },
+  {
+    id: "compound",
+    title: "Compound",
+    note: "Whole assembled patterns on the expressive contract - scoped --support-rail-* properties, no tone/corner/density enums. Actions are a SupportAction[]: id, label, icon, meta, description, onSelect."
+  },
+  {
+    id: "replicas",
+    title: "Replicas",
+    note: "Each reproduces an external platform surface; fidelity is the contract. Platform metrics are pinned constants - only --font-sans, --focus-ring and the duration tokens are read, so your theme cannot move them. None ever fetches media or autoplays: media and avatar take a URL string or your own node, with CSS-only placeholders."
+  },
+  { id: "dev", title: "Dev tools", note: "" }
+];
+var GROUP_IDS = new Set(GROUPS.map((g) => g.id));
+function parseUsage(text) {
+  const lines = text.split("\n");
+  const errors = [];
+  const doc = { title: "", subpath: "", group: "", docs: "", summary: "", prose: [], examples: [] };
+  const heading = lines[0]?.match(HEADING_RE);
+  if (!heading) {
+    errors.push(`line 1 must be "# <Title> - @zyncat/ui/<subpath>", got "${lines[0] ?? ""}"`);
+    return { doc, errors };
+  }
+  doc.title = heading[1].trim();
+  doc.subpath = heading[2];
+  let i = 1;
+  while (i < lines.length && !lines[i].trim()) i++;
+  for (; i < lines.length; i++) {
+    const meta = lines[i].match(META_RE);
+    if (!meta) break;
+    if (meta[1] === "Group") doc.group = meta[2];
+    else doc.docs = meta[2];
+  }
+  while (i < lines.length && !lines[i].trim()) i++;
+  if (i < lines.length && !FENCE_RE.test(lines[i])) {
+    doc.summary = lines[i].trim();
+    i++;
+    if (i < lines.length && lines[i].trim()) errors.push(`the summary (line ${i}) must be a single line`);
+  }
+  let fence = null;
+  for (; i < lines.length; i++) {
+    const open = lines[i].match(FENCE_RE);
+    if (open && !fence) {
+      fence = { lang: open[1] || "tsx", line: i + 1, code: [] };
+      continue;
+    }
+    if (fence && /^```\s*$/.test(lines[i])) {
+      doc.examples.push({ ...fence, code: fence.code.join("\n") });
+      fence = null;
+      continue;
+    }
+    if (fence) fence.code.push(lines[i]);
+    else doc.prose.push({ text: lines[i], line: i + 1 });
+  }
+  if (fence) errors.push(`unclosed \`\`\` fence opened at line ${fence.line}`);
+  while (doc.prose.length && !doc.prose[doc.prose.length - 1].text.trim()) doc.prose.pop();
+  while (doc.prose.length && !doc.prose[0].text.trim()) doc.prose.shift();
+  if (!doc.group) errors.push('missing "Group:" line');
+  else if (!GROUP_IDS.has(doc.group))
+    errors.push(`unknown group "${doc.group}" - one of: ${[...GROUP_IDS].join(", ")}`);
+  if (!doc.summary) errors.push("missing summary - one line of prose after the metadata block");
+  return { doc, errors };
+}
+function usagePathFor(source) {
+  return source ? source.replace(/^\.\//, "").replace(/\.(tsx|ts)$/, ".usage.md") : null;
+}
+function loadModules(root) {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const modules = [];
+  for (const [key, value] of Object.entries(pkg.exports ?? {})) {
+    if (!value || typeof value !== "object" || typeof value.types !== "string") continue;
+    const subpath = key.replace(/^\.\//, "");
+    const usagePath = usagePathFor(value.source);
+    const module = { subpath, typesPath: value.types.replace(/^\.\//, ""), sourcePath: value.source, usagePath };
+    if (usagePath && existsSync(join(root, usagePath))) {
+      const { doc, errors } = parseUsage(readFileSync(join(root, usagePath), "utf8"));
+      module.usage = doc;
+      module.usageErrors = errors;
+    }
+    modules.push(module);
+  }
+  return { version: String(pkg.version ?? "0"), modules };
+}
+function buildIndex(modules) {
+  const out = [];
+  for (const group of GROUPS) {
+    const inGroup = modules.filter((m) => m.usage?.group === group.id);
+    if (!inGroup.length) continue;
+    out.push(`== ${group.title} ==`);
+    if (group.note) out.push(group.note);
+    for (const m of inGroup) out.push(`${m.usage.title} - @zyncat/ui/${m.subpath} - ${m.usage.summary}`);
+    out.push("");
+  }
+  const typesOnly = modules.filter((m) => !m.usage);
+  if (typesOnly.length) {
+    out.push("== Types-only modules (documented by their .d.ts alone) ==");
+    for (const m of typesOnly) out.push(`@zyncat/ui/${m.subpath} - get_component("${m.subpath}")`);
+  }
+  return out.join("\n").trim();
+}
+
+// src/mcp/server.ts
 function findRoot() {
   let dir = dirname(fileURLToPath(import.meta.url));
   for (; ; ) {
-    const pj = join(dir, "package.json");
-    if (existsSync(pj)) {
+    const pj = join2(dir, "package.json");
+    if (existsSync2(pj)) {
       try {
-        if (JSON.parse(readFileSync(pj, "utf8")).name === "@zyncat/ui") return dir;
+        if (JSON.parse(readFileSync2(pj, "utf8")).name === "@zyncat/ui") return dir;
       } catch {
       }
     }
@@ -19,185 +146,167 @@ function findRoot() {
     dir = parent;
   }
 }
-var SECTION_RE = /^=+\s+(.+?)\s*$/;
-var HEADING_RE = /^([A-Za-z][\w /]*?) - @zyncat\/ui\/([a-z][a-z0-9-]*)\b.*$/;
 function db() {
   const root = findRoot();
-  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
-  const subpaths = Object.entries(pkg.exports ?? {}).filter(([, v]) => typeof v === "object" && v !== null && "types" in v).map(([k]) => k.replace(/^\.\//, ""));
-  const preamble = [];
-  const sections = [];
-  const entries = [];
-  let section = null;
-  let entry = null;
-  const close = (e) => {
-    if (!e) return;
-    while (e.lines.length && !e.lines[e.lines.length - 1].trim()) e.lines.pop();
-    entries.push(e);
-  };
-  for (const line of readFileSync(join(root, "llms.txt"), "utf8").split("\n")) {
-    const sec = line.match(SECTION_RE);
-    const head = line.match(HEADING_RE);
-    if (sec) {
-      close(entry);
-      entry = null;
-      section = { title: sec[1], body: [] };
-      sections.push(section);
-    } else if (head) {
-      close(entry);
-      entry = { title: head[1].trim(), subpath: head[2], section: section?.title ?? "", lines: [line] };
-    } else if (entry) {
-      entry.lines.push(line);
-    } else if (section) {
-      section.body.push(line);
-    } else {
-      preamble.push(line);
-    }
-  }
-  close(entry);
-  for (const s of sections) {
-    while (s.body.length && !s.body[s.body.length - 1].trim()) s.body.pop();
-    while (s.body.length && !s.body[0].trim()) s.body.shift();
-  }
-  while (preamble.length && !preamble[preamble.length - 1].trim()) preamble.pop();
-  return { root, version: String(pkg.version ?? "0"), subpaths, preamble, sections, entries };
+  const { version, modules } = loadModules(root);
+  return { root, version, modules, index: buildIndex(modules) };
 }
 var norm = (s) => s.toLowerCase().replace(/^@zyncat\/ui\//, "").replace(/[^a-z0-9]/g, "");
-function resolveSubpath(input) {
-  const d = db();
-  const q = norm(input);
-  if (!q) throw new Error('Pass a component name or subpath, e.g. "Button" or "text-field".');
+function resolveModules(d, inputs) {
+  const bySubpath = new Map(d.modules.map((m) => [m.subpath, m]));
   const candidates = /* @__PURE__ */ new Map();
-  for (const sub of d.subpaths) candidates.set(norm(sub), sub);
-  for (const e of d.entries) for (const part of e.title.split("/")) candidates.set(norm(part), e.subpath);
-  const exact = candidates.get(q);
-  if (exact) return exact;
-  const loose = /* @__PURE__ */ new Set();
-  for (const [name, sub] of candidates) if (name.includes(q) || q.includes(name)) loose.add(sub);
-  if (loose.size === 1) return [...loose][0];
-  const all = d.entries.map((e) => `${e.title} (${e.subpath})`).join(", ");
-  const extras = d.subpaths.filter((s) => !d.entries.some((e) => e.subpath === s)).join(", ");
-  throw new Error(
-    (loose.size ? `"${input}" is ambiguous: ${[...loose].join(", ")}. ` : `No component matches "${input}". `) + `Available: ${all}${extras ? `; types-only modules: ${extras}` : ""}.`
-  );
+  for (const m of d.modules) {
+    candidates.set(norm(m.subpath), m);
+    if (m.usage) {
+      for (const part of m.usage.title.split("/")) {
+        const key = norm(part);
+        if (key) candidates.set(key, m);
+      }
+    }
+  }
+  const misses = [];
+  const found = [];
+  for (const input of inputs) {
+    const q = norm(input);
+    if (!q) {
+      misses.push(`"${input}"`);
+      continue;
+    }
+    const exact = candidates.get(q) ?? bySubpath.get(q);
+    if (exact) {
+      found.push(exact);
+      continue;
+    }
+    const loose = /* @__PURE__ */ new Set();
+    for (const [name, m] of candidates) if (name.includes(q) || q.includes(name)) loose.add(m);
+    if (loose.size === 1) found.push([...loose][0]);
+    else if (loose.size > 1) misses.push(`"${input}" (ambiguous: ${[...loose].map((m) => m.subpath).join(", ")})`);
+    else misses.push(`"${input}"`);
+  }
+  if (misses.length) {
+    throw new Error(`No component matches ${misses.join(", ")}. The catalog:
+
+${d.index}`);
+  }
+  return [...new Set(found)];
 }
-function readTypes(root, subpath) {
+var RELATIVE_SPEC_RE = /(?:from\s+['"]|import\(['"])(\.[^'"]+)['"]/g;
+function readTypes(root, typesPath) {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
-  const walk = (base) => {
-    if (seen.has(base)) return;
-    seen.add(base);
-    const p = join(root, "dist", `${base}.d.ts`);
-    if (!existsSync(p)) return;
-    const text = readFileSync(p, "utf8");
-    out.push(`--- dist/${base}.d.ts ---
+  const walk = (path) => {
+    const full = resolve(root, path);
+    if (seen.has(full) || !existsSync2(full)) return;
+    seen.add(full);
+    const text = readFileSync2(full, "utf8");
+    out.push(`--- ${relative(root, full)} ---
 ${text.trimEnd()}`);
-    for (const m of text.matchAll(/from\s+['"]\.\/([\w.-]+)\.js['"]/g)) walk(m[1]);
+    for (const m of text.matchAll(RELATIVE_SPEC_RE)) {
+      const base = join2(dirname(full), m[1].replace(/\.js$/, ""));
+      for (const candidate of [`${base}.d.ts`, `${base}.d.mts`, join2(base, "index.d.ts")]) {
+        if (existsSync2(candidate)) {
+          walk(relative(root, candidate));
+          break;
+        }
+      }
+    }
   };
-  walk(subpath);
+  walk(typesPath);
   if (!out.length) {
     throw new Error(
-      `dist/${subpath}.d.ts not found - the package is not built. In the zyncat-ui repo run "pnpm build"; in a consumer, reinstall the package.`
+      `${typesPath} not found in the installed package - reinstall @zyncat/ui; in the zyncat-ui repo, run "pnpm build" first.`
     );
   }
   return out.join("\n\n");
 }
-var tokenFiles = (root) => existsSync(join(root, "src/tokens")) ? readdirSync(join(root, "src/tokens")).filter((f) => f.endsWith(".css")).sort() : [];
-var CODE_LINE_RE = /^(?:[<{]|import\s|const\s|let\s|function\s)/;
-function entryTeaser(e) {
-  const parts = [];
-  for (let i = 1; i < e.lines.length; i++) {
-    const line = e.lines[i].trim();
-    if (!line) break;
-    if (i > 1 && CODE_LINE_RE.test(line)) break;
-    parts.push(line);
+function renderModule(d, m) {
+  const out = [];
+  if (m.usage) {
+    out.push(`# ${m.usage.title} - @zyncat/ui/${m.subpath}`, "");
+    if (m.usage.docs) out.push(`Live docs page (see it rendered): ${m.usage.docs}`, "");
+    out.push(m.usage.summary, "");
+    const note = GROUPS.find((g) => g.id === m.usage.group)?.note;
+    if (note) out.push(`Applies to the whole ${m.usage.group} group: ${note}`, "");
+    const prose = m.usage.prose.map((l) => l.text);
+    if (prose.length) out.push(...prose, "");
+    for (const example of m.usage.examples) out.push("## Example", "", "```" + example.lang, example.code, "```", "");
+  } else {
+    out.push(`# @zyncat/ui/${m.subpath}`, "", "No usage doc - this module is documented by its types below.", "");
   }
-  return parts.join(" ");
+  out.push("## Complete prop types (entry .d.ts + the shared chunks it imports)", "", readTypes(d.root, m.typesPath));
+  return out.join("\n");
 }
-function listComponents() {
+function getComponent(raw) {
+  const inputs = (Array.isArray(raw) ? raw : [raw]).filter((v) => typeof v === "string");
+  if (!inputs.length) throw new Error('Pass one or more component names, e.g. ["select", "text-field"].');
   const d = db();
-  const out = [...d.preamble, ""];
-  for (const s of d.sections) {
-    const inSection = d.entries.filter((e) => e.section === s.title);
-    if (!inSection.length && !s.body.length) continue;
-    out.push(`== ${s.title} ==`);
-    out.push(...s.body);
-    for (const e of inSection) {
-      const first = entryTeaser(e);
-      out.push(`${e.title} - @zyncat/ui/${e.subpath}${first ? ` - ${first}` : ""}`);
-    }
-    out.push("");
-  }
-  const extras = d.subpaths.filter((sub) => !d.entries.some((e) => e.subpath === sub));
-  if (extras.length) {
-    out.push("== SUPPORTING MODULES (no llms.txt entry - full docs live in their types) ==");
-    for (const sub of extras) out.push(`@zyncat/ui/${sub} - call get_component("${sub}")`);
-  }
-  return out.join("\n").trim();
+  const modules = resolveModules(d, inputs);
+  return modules.map((m) => renderModule(d, m)).join("\n\n");
 }
-function getComponent(input) {
-  const d = db();
-  const sub = resolveSubpath(input);
-  const entry = d.entries.find((e) => e.subpath === sub);
-  const out = [`# ${entry ? entry.title : sub} - @zyncat/ui/${sub}`, ""];
-  if (entry) {
-    const note = d.sections.find((s) => s.title === entry.section)?.body ?? [];
-    if (note.length) out.push(`Applies to every ${entry.section} component:`, ...note, "");
-    out.push("## Usage (llms.txt)", ...entry.lines, "");
-  } else {
-    out.push("No llms.txt entry - this module is documented by its types below.", "");
+var tokenFiles = (root) => existsSync2(join2(root, "src/tokens")) ? readdirSync(join2(root, "src/tokens")).filter((f) => f.endsWith(".css")).sort() : [];
+function corpusFor(d, m) {
+  const parts = [];
+  if (m.usagePath && existsSync2(join2(d.root, m.usagePath))) {
+    parts.push({ label: "usage", text: readFileSync2(join2(d.root, m.usagePath), "utf8") });
   }
-  out.push("## Types (entry .d.ts + the shared chunks it imports)", readTypes(d.root, sub));
-  return out.join("\n");
+  try {
+    parts.push({ label: "types", text: readTypes(d.root, m.typesPath) });
+  } catch {
+  }
+  return parts;
 }
 function searchApi(query) {
-  const d = db();
   const words = query.toLowerCase().split(/\s+/).filter(Boolean);
   if (!words.length) throw new Error('Pass one or more keywords, e.g. "searchable" or "drag dismiss".');
-  const hits = /* @__PURE__ */ new Map();
-  const scan = (label, text, lineLabel) => {
-    text.split("\n").forEach((line, i) => {
-      const l = line.toLowerCase();
-      if (!words.every((w) => l.includes(w))) return;
-      const key = lineLabel ? lineLabel(line, i) : label;
-      if (!hits.has(key)) hits.set(key, []);
-      hits.get(key).push(`  L${i + 1}: ${line.trim()}`);
-    });
-  };
-  {
-    const raw = readFileSync(join(d.root, "llms.txt"), "utf8");
-    const labels = [];
-    let current = "llms.txt";
-    for (const line of raw.split("\n")) {
-      const sec = line.match(SECTION_RE);
-      const head = line.match(HEADING_RE);
-      if (sec) current = `llms.txt \xBB ${sec[1]}`;
-      else if (head) current = `llms.txt \xBB ${head[1].trim()}`;
-      labels.push(current);
+  const d = db();
+  const hits = [];
+  for (const m of d.modules) {
+    const hit = { module: m, score: 0, matched: /* @__PURE__ */ new Set(), lines: [] };
+    const head = `${m.usage?.title ?? ""} ${m.subpath} ${m.usage?.summary ?? ""}`.toLowerCase();
+    for (const w of words) {
+      if (head.includes(w)) {
+        hit.score += 4;
+        hit.matched.add(w);
+      }
     }
-    scan("llms.txt", raw, (_line, i) => labels[i]);
+    for (const { label, text } of corpusFor(d, m)) {
+      for (const line of text.split("\n")) {
+        const lower = line.toLowerCase();
+        const inLine = words.filter((w) => lower.includes(w));
+        if (!inLine.length) continue;
+        for (const w of inLine) hit.matched.add(w);
+        hit.score += inLine.length * (label === "usage" ? 2 : 1);
+        const shown = line.trim();
+        if (hit.lines.length < 4 && shown && !line.startsWith("---") && shown !== m.usage?.summary && !shown.startsWith("# "))
+          hit.lines.push(shown);
+      }
+    }
+    if (hit.matched.size) hits.push(hit);
   }
-  const distDir = join(d.root, "dist");
-  const dts = existsSync(distDir) ? readdirSync(distDir).filter((f) => f.endsWith(".d.ts")).sort() : [];
-  for (const f of dts) scan(`dist/${f}`, readFileSync(join(distDir, f), "utf8"));
-  for (const f of tokenFiles(d.root)) scan(`src/tokens/${f}`, readFileSync(join(d.root, "src/tokens", f), "utf8"));
-  const out = [];
-  let shown = 0;
-  let total = 0;
-  for (const [, lines] of hits) total += lines.length;
-  for (const [label, lines] of hits) {
-    if (shown >= 60) break;
-    out.push(`## ${label}`);
-    for (const l of lines) {
-      if (shown >= 60) break;
-      out.push(l);
-      shown++;
+  const full = hits.filter((h) => h.matched.size === words.length);
+  const ranked = (full.length ? full : hits).sort((a, b) => b.score - a.score).slice(0, 8);
+  const tokenHits = [];
+  for (const f of tokenFiles(d.root)) {
+    for (const line of readFileSync2(join2(d.root, "src/tokens", f), "utf8").split("\n")) {
+      const lower = line.toLowerCase();
+      if (words.some((w) => lower.includes(w)) && tokenHits.length < 12) tokenHits.push(`${f}: ${line.trim()}`);
     }
   }
-  if (!total) return `No matches for "${query}". Try a shorter keyword, or list_components for the full index.`;
-  if (total > shown) out.push(`... +${total - shown} more matching lines - narrow the query.`);
-  if (!dts.length) out.push("(note: dist/ is not built, so type definitions were not searched)");
-  out.push("", "Follow up with get_component(<name>) for the full picture.");
+  if (!ranked.length && !tokenHits.length) {
+    return `No matches for "${query}". The catalog:
+
+${d.index}`;
+  }
+  const out = [];
+  if (!full.length && ranked.length) out.push(`No component matches every word of "${query}"; closest by keyword:`, "");
+  for (const h of ranked) {
+    out.push(`## ${h.module.usage?.title ?? h.module.subpath} - @zyncat/ui/${h.module.subpath}`);
+    if (h.module.usage) out.push(h.module.usage.summary);
+    for (const line of h.lines) out.push(`  ${line}`);
+    out.push("");
+  }
+  if (tokenHits.length) out.push("## Design tokens", ...tokenHits.map((l) => `  ${l}`), "");
+  out.push(`Follow up with get_component([...names]) for complete APIs.`);
   return out.join("\n");
 }
 function getTokens(group) {
@@ -219,36 +328,74 @@ function getTokens(group) {
   }
   const out = picked.map(
     (f) => `/* ==== src/tokens/${f} ==== */
-${readFileSync(join(d.root, "src/tokens", f), "utf8").trimEnd()}`
+${readFileSync2(join2(d.root, "src/tokens", f), "utf8").trimEnd()}`
   );
-  const theming = d.sections.find((s) => s.title.includes("THEMING"));
-  if (theming?.body.length) out.push(["/* ==== theming ==== */", ...theming.body].join("\n"));
+  const theming = join2(d.root, "skills/zyncat-ui/references/theming.md");
+  if (!group && existsSync2(theming))
+    out.push(`/* ==== theming & overrides ==== */
+${readFileSync2(theming, "utf8").trimEnd()}`);
   return out.join("\n\n");
 }
-var TOOLS = [
-  {
-    name: "list_components",
-    description: "Every Zyncat UI component: name, import subpath and one-line purpose, grouped by category, plus package setup and usage conventions. Start here instead of exploring node_modules.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false }
-  },
+var GUIDES = { motion: "motion.md", design: "design-system.md", authoring: "authoring.md" };
+var inRepo = (root) => existsSync2(join2(root, "tsup.config.ts"));
+function contributorRoot(tool) {
+  const root = findRoot();
+  if (!inRepo(root)) {
+    throw new Error(
+      `${tool} is a contributor tool and is only available inside the zyncat-ui repository. In a consumer install use get_component / search_api / get_tokens.`
+    );
+  }
+  return root;
+}
+function guideSections(root, file) {
+  const path = join2(root, "docs/authoring", file);
+  if (!existsSync2(path)) throw new Error(`docs/authoring/${file} is missing from the repository.`);
+  const sections = [{ title: "", subtitles: [], lines: [] }];
+  for (const line of readFileSync2(path, "utf8").split("\n")) {
+    const head = line.match(/^##\s+(.+?)\s*$/);
+    const sub = line.match(/^###\s+(.+?)\s*$/);
+    if (head) sections.push({ title: head[1], subtitles: [], lines: [line] });
+    else {
+      const current = sections[sections.length - 1];
+      if (sub) current.subtitles.push(sub[1]);
+      current.lines.push(line);
+    }
+  }
+  return sections;
+}
+function guide(tool, file, topic) {
+  const sections = guideSections(contributorRoot(tool), file);
+  const text = (picked) => picked.flatMap((s) => s.lines).join("\n").trim();
+  if (!topic) return text(sections);
+  const q = norm(topic);
+  const matches = (title) => norm(title).includes(q) || q.includes(norm(title));
+  const named = sections.filter((s) => s.title);
+  const hits = named.filter((s) => matches(s.title) || s.subtitles.some(matches));
+  if (!hits.length) {
+    const titles = named.flatMap((s) => [s.title, ...s.subtitles]);
+    throw new Error(`No section of ${file} matches "${topic}". Sections: ${titles.join(", ")}.`);
+  }
+  return text(hits);
+}
+var CONSUMER_TOOLS = [
   {
     name: "get_component",
-    description: "Full API for one component: the maintainers' usage notes and example plus the complete TypeScript prop types with doc comments (shared type chunks inlined). Cheaper and more accurate than reading node_modules/@zyncat/ui yourself.",
+    description: "Full current API for one or more components: the maintainers\u2019 usage doc (purpose, when to pick it over its neighbours, example, live docs page URL) plus the complete TypeScript prop types with doc comments, shared type chunks inlined. Accepts a list - pass every component the change touches in ONE call. This is the only reliable source for props: call it before writing any Zyncat UI JSX. An unknown name returns the full component catalog, so a wrong guess still orients you.",
     inputSchema: {
       type: "object",
       properties: {
-        component: {
-          type: "string",
-          description: 'Component name or subpath - "Button", "TextField", "text-field", "@zyncat/ui/select".'
+        components: {
+          description: 'Component names or subpaths - ["select", "text-field", "dialog"], "Button", "@zyncat/ui/sheet".',
+          anyOf: [{ type: "string" }, { type: "array", items: { type: "string" }, minItems: 1 }]
         }
       },
-      required: ["component"],
+      required: ["components"],
       additionalProperties: false
     }
   },
   {
     name: "search_api",
-    description: 'Keyword search across all component docs, type definitions and design-token CSS. Finds which component owns a prop, type, token or behavior (e.g. "searchable", "DurationToken", "drag dismiss", "--accent"). Every word must match a line; follow up with get_component.',
+    description: 'Ranked keyword search across every component\u2019s usage doc, prop types and the design-token CSS. Finds which component owns a prop, behavior or token (e.g. "drag dismiss", "searchable", "DurationToken", "--accent"). Zero matches returns the whole catalog instead, so a miss still orients you. Follow up with get_component.',
     inputSchema: {
       type: "object",
       properties: { query: { type: "string", description: "One or more keywords." } },
@@ -258,7 +405,7 @@ var TOOLS = [
   },
   {
     name: "get_tokens",
-    description: "The design-token vocabulary as CSS custom properties with their real values - color, semantic, spacing, typography, radius, elevation, motion, icons, layers, glass, avatar, fonts. Optionally pass one group name; omit for all. Use for theming/overrides and for reading exact values.",
+    description: "The design-token vocabulary as CSS custom properties with their real values - color, semantic, spacing, typography, radius, elevation, motion, icons, layers, glass, avatar, fonts - plus the theming/override levels. Optionally pass one group name; omit for all. Use for theming and for reading exact values.",
     inputSchema: {
       type: "object",
       properties: {
@@ -268,17 +415,62 @@ var TOOLS = [
     }
   }
 ];
-var INSTRUCTIONS = "Zyncat UI design-system API. Before writing Zyncat UI code, use these tools instead of reading node_modules or guessing props: list_components (what exists + setup and conventions), get_component (one component: usage docs + complete prop types), search_api (find the component/prop/token for a keyword), get_tokens (CSS custom-property vocabulary with real values, for theming). Imports are per-subpath (@zyncat/ui/button - no barrel); link @zyncat/ui/styles.css once at the root.";
+var CONTRIBUTOR_TOOLS = [
+  {
+    name: "motion_guide",
+    description: "How to animate inside this repo: the transitions-vs-simulations boundary, which layer to reach for (CSS transition vs the engine vs Presence vs FLIP vs glide), the complete Layer keyframe vocabulary, [to] vs [from,to] semantics, timing, the one-writer-per-property ownership rules, sequencing, global reduced motion, and the canonical enter/exit recipes. Read this before writing any motion code - most of it is not guessable from the source.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: {
+          type: "string",
+          description: 'One section, e.g. "ownership", "timing", "simulations", "recipes". Omit for all.'
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "design_rules",
+    description: "The design-system rules for this repo: what the library is for, the system / expressive / replica contracts and the invariants that bind every tier, the token vocabulary and when to add a token rather than use an existing one, the consumer override levels, compose vs build a new component, which tier a component belongs in, and the internal machinery to reuse instead of hand-rolling.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: {
+          type: "string",
+          description: 'One section, e.g. "tokens", "contracts", "overrides", "compose", "tier". Omit for all.'
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "authoring_checklist",
+    description: "The complete checklist to add a component to this repo: file placement and tsup auto-discovery, the exports-map entry that fails silently when skipped, the per-component stylesheet and CSS-graph rule, the usage doc, which tests to write, and the checks to run.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  }
+];
+function tools() {
+  try {
+    return inRepo(findRoot()) ? [...CONSUMER_TOOLS, ...CONTRIBUTOR_TOOLS] : CONSUMER_TOOLS;
+  } catch {
+    return CONSUMER_TOOLS;
+  }
+}
+var CONSUMER_INSTRUCTIONS = "Zyncat UI design-system API - the live truth for the installed version. Before writing any JSX that renders a Zyncat UI component, call get_component with every component the change touches (it accepts a list); prop lists remembered from training, a skill index or old code are not the API. search_api finds which component owns a keyword or behavior; get_tokens prints the token vocabulary with real values plus the theming levels. Imports are per-subpath (@zyncat/ui/button - no barrel); link @zyncat/ui/styles.css once at the root. The zyncat-ui skill (installed by `npx zyncat-ui init`) carries the component map, the recipes and the conventions.";
+var CONTRIBUTOR_INSTRUCTIONS = " You are inside the zyncat-ui repository, so the contributor tools are also available and you are expected to use them before writing library code: motion_guide (call it before any motion code - the keyframe vocabulary and the ownership rules are not guessable from the source), design_rules (tokens, compose vs build, the internals to reuse), authoring_checklist (adding a component end to end).";
+function instructions() {
+  try {
+    return inRepo(findRoot()) ? CONSUMER_INSTRUCTIONS + CONTRIBUTOR_INSTRUCTIONS : CONSUMER_INSTRUCTIONS;
+  } catch {
+    return CONSUMER_INSTRUCTIONS;
+  }
+}
 function callTool(name, args) {
   const str = (k) => typeof args[k] === "string" ? args[k] : void 0;
   switch (name) {
-    case "list_components":
-      return listComponents();
-    case "get_component": {
-      const component = str("component");
-      if (!component) throw new Error('Missing required argument "component".');
-      return getComponent(component);
-    }
+    case "get_component":
+      return getComponent(args.components ?? args.component);
     case "search_api": {
       const query = str("query");
       if (!query) throw new Error('Missing required argument "query".');
@@ -286,6 +478,12 @@ function callTool(name, args) {
     }
     case "get_tokens":
       return getTokens(str("group"));
+    case "motion_guide":
+      return guide(name, GUIDES.motion, str("topic"));
+    case "design_rules":
+      return guide(name, GUIDES.design, str("topic"));
+    case "authoring_checklist":
+      return guide(name, GUIDES.authoring);
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
@@ -314,13 +512,13 @@ function handle(req) {
         protocolVersion: typeof params?.protocolVersion === "string" ? params.protocolVersion : "2025-06-18",
         capabilities: { tools: {} },
         serverInfo: { name: "zyncat-ui", version },
-        instructions: INSTRUCTIONS
+        instructions: instructions()
       });
     }
     case "ping":
       return reply(id, {});
     case "tools/list":
-      return reply(id, { tools: TOOLS });
+      return reply(id, { tools: tools() });
     case "tools/call": {
       try {
         const name = typeof params?.name === "string" ? params.name : "";