mlola-ui 1.0.2 → 1.0.4

package/registry/source-manifest.json

@@ -8,43 +8,43 @@
   "packages/components/accordion/accordion.tsx": "sha256-0ALaLJd1fvj8Vbx86HLBKm3qUItrtwbrGJTykVfNSMg=",
   "packages/components/activity-heatmap/activity-heatmap.tsx": "sha256-fMGDlXKpOfIOy0hmbpR8hKrbbN3fC386tXK27A21ZwM=",
   "packages/components/activity-heatmap/calendar.ts": "sha256-NB+AjXY5Xc+KzR8MMTRBgZxdzOeoHhkW0KQOW7WJPuQ=",
-  "packages/components/alert/alert.tsx": "sha256-kg//PTcUW7j7AEnhfO/pZFddm++RIo8yKur46OeoeNo=",
+  "packages/components/alert/alert.tsx": "sha256-j680akXvCIh4MTVnUo79acvVrv51XyQ3UBJ5FBAy8Dw=",
   "packages/components/app-shell/app-shell.tsx": "sha256-XAq82XOTH3ZR+hxTkYFu8P7Ih2aI6ERy/TpXc2VMUwM=",
   "packages/components/avatar/avatar.tsx": "sha256-hvZUGhatN95ZyX6p6NBhTRf6h1/rrJ+bJrqBMtIspq0=",
-  "packages/components/badge/badge.tsx": "sha256-+mgudoxlPn+mjpQycUfQmv8sC/e/K5FXfXm2+wnH7bI=",
-  "packages/components/breadcrumb/breadcrumb.tsx": "sha256-SiIpg0oAieyoZbMlBwwQDZhR/KVIFLFCLCQJ6vwv7Fs=",
+  "packages/components/badge/badge.tsx": "sha256-flEH8S2jZ/64n3Y/ROhC9+9rvF7wXaN0xLcMMwqNOVQ=",
+  "packages/components/breadcrumb/breadcrumb.tsx": "sha256-Mt9mvmwwDgdp5/+mj5byIrh8+hicsp7R6UcvUlK0yog=",
   "packages/components/button/button.tsx": "sha256-khqYxcV3hlZ+Q+cYNTRXEpAfIijDFSvkuDJXMPtlk7g=",
   "packages/components/calendar/calendar.tsx": "sha256-uE22LI4jpU8ErR/oBmAkeKiu+Rp0bz3IXZVCurycpwc=",
   "packages/components/calendar/dates.ts": "sha256-mygYkoC70av2ZQ0vkxf885trwW97Wd10I4dptYQe+4A=",
   "packages/components/card/card.tsx": "sha256-aMKbv5DWYYWq7GZAFR9O1fuYE0H61WCjkvEbRMOd894=",
-  "packages/components/carousel/carousel.tsx": "sha256-LAPKz9DG9vEBv/8jKjqgH7XiSEERkWWLr4n/Kve1omQ=",
-  "packages/components/checkbox/checkbox.tsx": "sha256-cqTFwYwNPRxKiBnXXWkcFeDlJ6tpJ9GX4IdqrYRp9Fs=",
-  "packages/components/color-picker/color-picker.tsx": "sha256-UziuULSI7dIGLfu4jjWIz6Cbh2/HiaY2KYXlfQ+6iQg=",
-  "packages/components/color-picker/color.ts": "sha256-3IO6DaelZ6TVn2aw+6o6pZCQGAQdeNRkN7sPypUzddE=",
-  "packages/components/combobox/combobox.tsx": "sha256-CnuJP01m0ZPMB4MGjoKbJCBQ7inI6bPf5aMDrq4m1qI=",
+  "packages/components/carousel/carousel.tsx": "sha256-pamugpB6Ujt9Ylxd37jNF/ZwSb8iRkW/MoYe12nY3i4=",
+  "packages/components/checkbox/checkbox.tsx": "sha256-hz4YbGwOxv/aJpJHrLXR4MKSWJGyjzoJEIGvdhyML9M=",
+  "packages/components/color-picker/color-picker.tsx": "sha256-E+QB6MbSxg+3AZX3A7bOkst4arxgpmFL2ZmochoWCl8=",
+  "packages/components/color-picker/color.ts": "sha256-YqSgYjzn7XfPWAHuyzbwOhbg/ScaSfB7V73e9w+OjJs=",
+  "packages/components/combobox/combobox.tsx": "sha256-CvuYc/hJoS7yw6QM9vv1SIkwflx0Kwd95UjchtC+AOs=",
   "packages/components/command-menu/command-menu.tsx": "sha256-mF1z92yrPY609pjx5Dt1l5EhGHl9EWV8F8Sq0hyJRw4=",
   "packages/components/context-menu/context-menu.tsx": "sha256-YgYsIzvLGFcJG1XX5zFJwrid5Z1Kn0lyWVzmLKmbMVU=",
-  "packages/components/date-picker/date-picker.tsx": "sha256-pX7snZCO3SxVftkCvI/f5b82bNHPconUa50BJnjYNWc=",
+  "packages/components/date-picker/date-picker.tsx": "sha256-rsmDweD3RVfKTXR2i+/pnTb/MsrDAZXmHAYBvcUGxig=",
   "packages/components/dropdown-menu/dropdown-menu.tsx": "sha256-xgybCu9HBxIieafu5CjAtY4aCOQoaAj/VUCH6D6vLP8=",
-  "packages/components/dropzone/dropzone.tsx": "sha256-jMVEnTki4Suhx7pOWfLX9MO1Q3nLz0xqDJ/2EPHdpYg=",
-  "packages/components/empty-state/empty-state.tsx": "sha256-AWwOuZgm71hossjCGYygtvzGcDy6JOPryF+U1UrsLhM=",
-  "packages/components/hover-card/hover-card.tsx": "sha256-HZyB9SUDcRPG8MvRX1sHqHA2rNcO63yVevH9hiGqVAA=",
+  "packages/components/dropzone/dropzone.tsx": "sha256-tHCCpEWE6839UeLOszTo+R2vAL4Sp9UxuRdLkFLfnq4=",
+  "packages/components/empty-state/empty-state.tsx": "sha256-uCKqYpr9vkozXZHpdl4GFtdX9ijcGOriCHvgyarBqRw=",
+  "packages/components/hover-card/hover-card.tsx": "sha256-AyRbxfqDOYBgGlgjgrtQZm5DipArLEzQn6XnzjPd0ro=",
   "packages/components/input/input.tsx": "sha256-lbbheo+ydQTzyujTf0W7DD96TogOjifCyqj9c3h3W0g=",
   "packages/components/kbd/kbd.tsx": "sha256-wrPqzn1e82zJYoKzO7u94Bgq4+nPc0DXLc8GJ/4/3nY=",
   "packages/components/modal/modal.tsx": "sha256-vybxgBGYCrMYvJRnO1wDAc2VFQylu+mQIf5OZIcabX4=",
-  "packages/components/number-input/number-input.tsx": "sha256-D+8jH2YaW4lCv/F02qvkc9Huhxvz0y1idzgOBwsjiN8=",
+  "packages/components/number-input/number-input.tsx": "sha256-BDOyvCNtMULD/HK7uWHsYbGg79lrRDrVqtGQQrYHpmM=",
   "packages/components/number-input/number.ts": "sha256-IrHCQrEhI5ein9ifMFuSViSoxQUBoT3tNmmCu/paGGM=",
-  "packages/components/otp-input/otp-input.tsx": "sha256-MWDyTP99wVAQSYJsF78ol1Kv9LKOj1lybmp2zOomVqo=",
+  "packages/components/otp-input/otp-input.tsx": "sha256-QURn8g5HqCQXBTdeENPbVxoPlqs3ZtoAPLRlFjQDxmI=",
   "packages/components/pagination/pagination.tsx": "sha256-FBwk8tq4JcsK2D0dlWEYiDSRx3owgBmGzEIlVRaNBoE=",
   "packages/components/popover/popover.tsx": "sha256-/kTiAuFklU4IuP97XaiCUGdEpKtNyMPLPS359mfzPHw=",
   "packages/components/priority-icon/labels.ts": "sha256-zhmJIb7/gS16wU+xCJ7hkReBi9q5RI3SMwdjkJvvvKU=",
   "packages/components/priority-icon/priority-icon.tsx": "sha256-3D6hFRpht3YuWouLhakE2DFdldavmJx0B/povEDwrtQ=",
-  "packages/components/progress/progress.tsx": "sha256-3SOA1JX54msiq/pF2UolesQqQZm0zSVyZQi6W38lOOA=",
+  "packages/components/progress/progress.tsx": "sha256-9OjecRNPWn7Bfe+C5IyXaKsW1NJae6X5gco1o0X5XkE=",
   "packages/components/radio-group/radio-group.tsx": "sha256-jhnSEBLkdpe8dv5us/Q1sMsQF4sKGRgDXWGKm2JSFew=",
   "packages/components/rating/rating.tsx": "sha256-zgPOQXzAiRE4qGNPQ8qat3SP1XSI/7567kA5VaT51P0=",
   "packages/components/resizable/resizable.tsx": "sha256-40sK2UyIR9Ek72KAu5nvbr44tKEY6JhC5Ftb++Wf6cI=",
-  "packages/components/segmented-control/segmented-control.tsx": "sha256-sExMN2WHtzxcaCu7xN/1jaP+sRVwJ2OAW1WkKGhNYnU=",
-  "packages/components/select/select.tsx": "sha256-MWHL/mlAO2ob4H3EmYSBZcC1qqy+M3cF1Z4s0R+frrc=",
+  "packages/components/segmented-control/segmented-control.tsx": "sha256-MCBG5XHFWCwbACctsYKbqe8mvSSR6pf60tyRgdCDKDA=",
+  "packages/components/select/select.tsx": "sha256-m8QmKUGC4386XcklosSntal0XwUAFjKosTBQSF0dduQ=",
   "packages/components/sheet/sheet.tsx": "sha256-EIn3OeRDmXGHbYf/uihRh8aw3LmzarIFiyC9DUsL1jg=",
   "packages/components/skeleton/skeleton.tsx": "sha256-2Fk72NbLr3+CrXH7jGbHNsc3t+vskMqSyySe/UwbGCs=",
   "packages/components/slider/slider.tsx": "sha256-l+VrBqPYHIIcemiVixxwDxNDB0HEMmYRZekx/H5HroQ=",
@@ -53,15 +53,15 @@
   "packages/components/stepper/stepper.tsx": "sha256-uI/dRmkbijlixHiGUceWcpaDzpEixrzQ1UTmoPbGZAY=",
   "packages/components/table/table.tsx": "sha256-ed1Qn2sIpxRvGdPDAb5ih5AcXr5PmHTHdlrJLYDYRp8=",
   "packages/components/tabs/tabs.tsx": "sha256-kWAQjE9mshqZL7V3NJTUiurp6M5Nu3vx5O1LsIgdV5Y=",
-  "packages/components/tag-input/tag-input.tsx": "sha256-+R1f2XljDYInsfuggKkpqz5m9TqEa0g3QYKMX2TE6h0=",
-  "packages/components/textarea/textarea.tsx": "sha256-jeyvAlzFr25eWZ/Inkxo1UEOHXlCPB/QHeId124SfR8=",
-  "packages/components/time-picker/time-picker.tsx": "sha256-OyIfJN6xVv6TwUYtRirkemJe5VMcu2HXxjaJj8fvu9I=",
+  "packages/components/tag-input/tag-input.tsx": "sha256-EK7xJTe3Y/S5Kn3vS0zBQg9lC+RVoGvky6HOAt+DnAw=",
+  "packages/components/textarea/textarea.tsx": "sha256-C9jMYZ63w+m6bgdLvHjvULRuoCe26q5zbgS4+ahWzr8=",
+  "packages/components/time-picker/time-picker.tsx": "sha256-og8Cbf+e8oFYewfagUgjRzLHSIIlAZh+1OpAn9yNq70=",
   "packages/components/time-picker/times.ts": "sha256-V/4uqFZPn9gVnyx8cB9vwp/RocmTYaPmLxjfy8DPQOI=",
-  "packages/components/timeline/timeline.tsx": "sha256-FDZx+ihL5tbIY/sEl0444uj27JWHE5xl0vl8IqRUUPY=",
-  "packages/components/toast/toast.tsx": "sha256-RrqUAAfKavEkZaLjywJHc0iTNHC1DHlIGVX97kftDkg=",
-  "packages/components/toggle/toggle.tsx": "sha256-zwTbHMSs3n0eg5XIpREDnySYLXHaLly1Ew4FWlzvgJY=",
+  "packages/components/timeline/timeline.tsx": "sha256-nVg7lBcAUAzqEb0YrHagJXSaHE2aWWE9bUbQMWQY6PU=",
+  "packages/components/toast/toast.tsx": "sha256-FvZnwN6Lk/QEHmcNxo7sVlEvR3Lx54aT5cH9lwrthhE=",
+  "packages/components/toggle/toggle.tsx": "sha256-8qPHeSliHNdzQS7OLJ47BrvRR75MYyUGJlK4s21XS/U=",
   "packages/components/tooltip/tooltip.tsx": "sha256-NbaOUmlUbBlUIdovchrWwH2QqzuvXB97DjnJnrHf4Gc=",
-  "packages/components/tour/tour.tsx": "sha256-1aSh7hMVt/DM/kH3WGJzJMGNsNqYEOmnwAZwc8dwRv8=",
+  "packages/components/tour/tour.tsx": "sha256-mrAE8aVDBVIibGvQah9Gh3mzIiWDFxB6aObzqFo5xXU=",
   "packages/components/virtual-list/virtual-list.tsx": "sha256-raGEFn4HlAOIohqZcy0DgptsnUIPS/6bWLYeTe+M9E8=",
   "packages/components/virtual-list/virtual.ts": "sha256-PyDIj3C2Vwb1i4ZssxSlYjgKmZPBIFLZFNq8YCW2Z78="
 }

package/src/agents.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import { designGuide } from "./knowledge.js";
+
+/**
+ * Tells the project's coding agents that the UI is Mlola, where the design
+ * language is written down, and how to ask about it, so an assistant builds
+ * with Mlola without being reminded:
+ *
+ * - `mlola.agents.md`   the design guide: classes, tokens, rules (refreshed)
+ * - `AGENTS.md`         a short section, between markers, read by most agents
+ * - `CLAUDE.md`         imports AGENTS.md for Claude Code
+ * - `.mcp.json`         the Mlola MCP server, for Claude Code and others
+ * - `.cursor/…`         a rule and the MCP server, when the project uses Cursor
+ * - `.vscode/mcp.json`  the MCP server, when the project uses VS Code
+ *
+ * Every write merges: anything else in these files is left as it was.
+ */
+
+export const GUIDE_FILE = "mlola.agents.md";
+const START = "<!-- mlola-ui:start -->";
+const END = "<!-- mlola-ui:end -->";
+const SERVER = { command: "npx", args: ["-y", "mlola-ui", "mcp"] };
+
+const BRIEF = `## UI: Mlola UI
+
+This project's interface is built with Mlola UI. Before writing or changing UI:
+
+- Read \`${GUIDE_FILE}\` (and \`mlola-pro.agents.md\` when it exists): every
+  class, attribute and token, and the rules for new UI.
+- Compose from Mlola components first: \`npx mlola-ui list\`,
+  \`npx mlola-ui add <name>\`. Write new CSS only for what they do not cover.
+- Never write a color, spacing, radius, shadow or duration by hand: read the
+  \`--ml-*\` tokens. There is no Tailwind or other styling framework here.
+- State and variants go in \`data-*\` and \`aria-*\` with the shared words
+  (\`data-tone\`, \`data-variant\`, \`data-size\`, \`data-status\`), never in extra
+  classes. \`data-theme\` and \`data-mode\` belong to the engine.
+- The \`mlola\` MCP server (\`npx mlola-ui mcp\`) searches components, explains
+  tokens and checks markup against the contract. Check new markup with its
+  \`check_markup\` tool before finishing.`;
+
+/** Replaces the marked section, or appends it; returns what happened. */
+function mergeSection(filename, body) {
+  const block = `${START}\n${body}\n${END}`;
+  if (!fs.existsSync(filename)) {
+    fs.writeFileSync(filename, `${block}\n`);
+    return "created";
+  }
+  const current = fs.readFileSync(filename, "utf8");
+  const start = current.indexOf(START);
+  const end = current.indexOf(END);
+  const next = start >= 0 && end > start ? `${current.slice(0, start)}${block}${current.slice(end + END.length)}` : `${current.replace(/\s*$/, "")}\n\n${block}\n`;
+  if (next === current) return "unchanged";
+  fs.writeFileSync(filename, next);
+  return "updated";
+}
+
+function mergeJson(filename, update) {
+  let data = {};
+  if (fs.existsSync(filename)) {
+    try {
+      data = JSON.parse(fs.readFileSync(filename, "utf8"));
+    } catch {
+      return "skipped (not valid JSON; add the server by hand)";
+    }
+  }
+  const next = update(structuredClone(data));
+  if (JSON.stringify(next) === JSON.stringify(data)) return "unchanged";
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  const existed = fs.existsSync(filename);
+  fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`);
+  return existed ? "updated" : "created";
+}
+
+export function writeAgentFiles(cwd) {
+  const results = [];
+  const record = (file, status) => results.push({ file, status });
+
+  const guide = designGuide();
+  if (guide) {
+    const filename = path.join(cwd, GUIDE_FILE);
+    const before = fs.existsSync(filename) ? fs.readFileSync(filename, "utf8") : null;
+    if (before !== guide) fs.writeFileSync(filename, guide);
+    record(GUIDE_FILE, before === null ? "created" : before === guide ? "unchanged" : "updated");
+  }
+
+  record("AGENTS.md", mergeSection(path.join(cwd, "AGENTS.md"), BRIEF));
+
+  // Claude Code reads CLAUDE.md, which can import AGENTS.md rather than repeat it.
+  const claude = path.join(cwd, "CLAUDE.md");
+  const claudeText = fs.existsSync(claude) ? fs.readFileSync(claude, "utf8") : null;
+  if (claudeText === null) {
+    fs.writeFileSync(claude, "@AGENTS.md\n");
+    record("CLAUDE.md", "created");
+  } else if (!/^@AGENTS\.md\s*$/m.test(claudeText)) {
+    record("CLAUDE.md", mergeSection(claude, "@AGENTS.md"));
+  } else {
+    record("CLAUDE.md", "unchanged");
+  }
+
+  record(".mcp.json", mergeJson(path.join(cwd, ".mcp.json"), (data) => ({ ...data, mcpServers: { ...(data.mcpServers ?? {}), mlola: SERVER } })));
+
+  if (fs.existsSync(path.join(cwd, ".cursor"))) {
+    record(".cursor/mcp.json", mergeJson(path.join(cwd, ".cursor", "mcp.json"), (data) => ({ ...data, mcpServers: { ...(data.mcpServers ?? {}), mlola: SERVER } })));
+    const rule = path.join(cwd, ".cursor", "rules", "mlola.mdc");
+    const text = `---\ndescription: Mlola UI, how interface code is built and styled in this project\nalwaysApply: true\n---\n\n${BRIEF.replace(/^## .*\n\n/, "")}\n`;
+    const before = fs.existsSync(rule) ? fs.readFileSync(rule, "utf8") : null;
+    if (before !== text) {
+      fs.mkdirSync(path.dirname(rule), { recursive: true });
+      fs.writeFileSync(rule, text);
+    }
+    record(".cursor/rules/mlola.mdc", before === null ? "created" : before === text ? "unchanged" : "updated");
+  }
+
+  if (fs.existsSync(path.join(cwd, ".vscode"))) {
+    record(".vscode/mcp.json", mergeJson(path.join(cwd, ".vscode", "mcp.json"), (data) => ({ ...data, servers: { ...(data.servers ?? {}), mlola: { type: "stdio", ...SERVER } } })));
+  }
+  return results;
+}

package/src/cli.js

@@ -7,17 +7,21 @@ import {
   targetRoot,
   writeDefaultConfig,
 } from "./config.js";
+import { writeAgentFiles } from "./agents.js";
 import { addAssets, assetHint, loadAssetIndex } from "./assets.js";
 import { runDoctor } from "./doctor.js";
 import { collectEngineDependencies, installItems } from "./installer.js";
 import { loadCatalogNames, loadRegistry, resolveItems } from "./registry.js";
 import { clearCredentials, fetchProItems, GUIDE_FILENAME, hostFrom, readCredentials, saveCredentials, verifyToken, writeProGuide, writeProStyles } from "./pro.js";
+import { serveMcp } from "./mcp.js";
 import { pullTheme } from "./theme-pull.js";
 
 const HELP = `Mlola UI — source-copy components with Theme
 
 Usage:
-  mlola-ui init [--force]
+  mlola-ui init [--force] [--no-agents]
+  mlola-ui agents
+  mlola-ui mcp
   mlola-ui add <name...> [--overwrite] [--install|--yes]
   mlola-ui add asset <id...> [--overwrite]
   mlola-ui login <token> [--host <url>]
@@ -27,15 +31,25 @@ Usage:
   mlola-ui theme pull <theme-id | url> [--host <url>] [--overwrite]
 
 Examples:
-  npx mlola-ui init
+  npx mlola-ui init                   (also tells your coding agents about Mlola)
   npx mlola-ui add button card
   npx mlola-ui login mlp_…          (Mlola Pro: a token from /account)
   npx mlola-ui add conversation bot
   npx mlola-ui add asset empty-inbox orb
   npx mlola-ui list --kind block
   npx mlola-ui theme pull https://ui.mlola.com/t/th-4k2x9qf7wz3m
+  npx mlola-ui mcp                    (an MCP server for Claude Code, Cursor, Codex…)
 `;
 
+const CLI_VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+function reportAgents(results, output) {
+  const changed = results.filter((entry) => entry.status !== "unchanged");
+  for (const { file, status } of changed) output.log(`✓ ${status[0].toUpperCase()}${status.slice(1)} ${file}`);
+  if (!changed.length) output.log("• Agent instructions are up to date");
+  output.log("Coding agents now know this UI is Mlola: AGENTS.md points them at mlola.agents.md, and .mcp.json starts the Mlola MCP server.");
+}
+
 function hasFlag(args, ...names) {
   return args.some((argument) => names.includes(argument));
 }
@@ -113,6 +127,17 @@ export async function run(argv, options = {}) {
       output.log(
         `Install the engines you use, starting with: npm install ${config.engine.engine ?? "@mlola-ui/engine"} ${config.engine.motion}`,
       );
+      if (!hasFlag(args, "--no-agents")) reportAgents(writeAgentFiles(cwd), output);
+      return 0;
+    }
+
+    if (command === "agents") {
+      reportAgents(writeAgentFiles(cwd), output);
+      return 0;
+    }
+
+    if (command === "mcp") {
+      await serveMcp({ cwd, run, version: CLI_VERSION });
       return 0;
     }
 
@@ -167,7 +192,7 @@ export async function run(argv, options = {}) {
       if (!token) throw new Error(`Usage: mlola-ui login <token>. Create a token at ${host}/account.`);
       const { licence } = await verifyToken(host, token, fetcher);
       const filename = saveCredentials(env, token, host === hostFrom(env) ? undefined : host);
-      output.log(`✓ Logged in to Mlola Pro (${licence.plan} licence). Token saved to ${filename}.`);
+      output.log(`✓ Logged in to Mlola Pro (${licence.plan} license). Token saved to ${filename}.`);
       return 0;
     }
 
@@ -212,7 +237,7 @@ export async function run(argv, options = {}) {
         if (!credentials) {
           throw new Error(
             `${proNames.map((name) => `"${name}"`).join(", ")} ${proNames.length === 1 ? "is" : "are"} part of Mlola Pro. ` +
-              `With a licence, create a token at ${host}/account and run "npx mlola-ui login <token>". See ${host}/pricing to get Pro.`,
+              `With a license, create a token at ${host}/account and run "npx mlola-ui login <token>". See ${host}/pricing to get Pro.`,
           );
         }
         const delivered = await fetchProItems(host, credentials.token, proNames, fetcher);

package/src/knowledge.js

@@ -0,0 +1,235 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_CONFIG, interpolateTarget } from "./config.js";
+import { BUNDLED_REGISTRY_ROOT, loadRegistry, readJson, sourcePath } from "./registry.js";
+
+/**
+ * What the CLI knows about Mlola UI, as answers rather than files: every
+ * component and catalog item, the tokens, the rules for new UI, and the
+ * element contract markup is checked against. All of it is read from the
+ * registry bundled with this CLI, so an answer always matches the version
+ * that `add` installs, and it works offline.
+ */
+
+const cache = new Map();
+function bundled(name) {
+  if (!cache.has(name)) {
+    const filename = path.join(BUNDLED_REGISTRY_ROOT, name);
+    cache.set(name, fs.existsSync(filename) ? (name.endsWith(".json") ? readJson(filename) : fs.readFileSync(filename, "utf8")) : null);
+  }
+  return cache.get(name);
+}
+
+const KIND = { "registry:ui": "component", "registry:block": "block", "registry:page": "page", "registry:template": "template" };
+
+/** Every item, free and Pro, in one shape. */
+export function allItems() {
+  const registry = loadRegistry();
+  const free = registry.items.map((item) => ({
+    name: item.name,
+    kind: KIND[item.type] ?? "component",
+    tier: "free",
+    title: item.title,
+    description: item.description,
+    category: item.category,
+    tags: item.tags ?? [],
+    variants: item.variants ?? [],
+    sizes: item.sizes ?? [],
+  }));
+  const pro = (bundled("catalog.json")?.items ?? []).map((item) => ({
+    name: item.name,
+    kind: KIND[item.type] ?? "component",
+    tier: "pro",
+    title: item.title,
+    description: item.description,
+    category: item.category,
+    tags: item.tags ?? [],
+    variants: [],
+    sizes: [],
+  }));
+  return [...free, ...pro];
+}
+
+/** Items matching a query: every word must appear in the name, title, description, category or tags. */
+export function searchItems({ query = "", kind, category, tier } = {}) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return allItems()
+    .filter((item) => (!kind || item.kind === kind) && (!category || item.category === category) && (!tier || item.tier === tier))
+    .map((item) => {
+      const haystack = [item.name, item.title, item.description, item.category, ...item.tags].join(" ").toLowerCase();
+      const score = words.reduce((sum, word) => sum + (item.name === word ? 5 : item.name.includes(word) ? 3 : haystack.includes(word) ? 1 : -100), 0);
+      return { item, score };
+    })
+    .filter(({ score }) => score >= 0)
+    .sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name))
+    .map(({ item }) => item);
+}
+
+/** The classes a component styles (its own prefix) and the attributes each reacts to. */
+function elementsOf(name) {
+  const contract = bundled("contract.json");
+  if (!contract) return [];
+  const prefix = `ml-${name}`;
+  return contract.classes
+    .filter((cls) => cls === prefix || cls.startsWith(`${prefix}-`))
+    .map((cls) => ({ class: cls, attributes: contract.elements[cls] ?? {} }));
+}
+
+function projectConfig(cwd) {
+  try {
+    return readJson(path.join(cwd, "mlola.config.json"));
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+/** Everything an agent needs to use one item correctly. */
+export function describeItem(name, { cwd = process.cwd(), includeSource = false } = {}) {
+  const registry = loadRegistry();
+  const item = registry.items.find((entry) => entry.name === name);
+  if (!item) {
+    const pro = (bundled("catalog.json")?.items ?? []).find((entry) => entry.name === name);
+    if (pro) {
+      return {
+        name,
+        tier: "pro",
+        kind: KIND[pro.type] ?? "component",
+        title: pro.title,
+        description: pro.description,
+        category: pro.category,
+        install: `npx mlola-ui login <token>   # once, with a token from https://ui.mlola.com/account\nnpx mlola-ui add ${name}`,
+        note: "Part of Mlola Pro. Its source arrives with a license token; its classes and attributes are listed in mlola-pro.agents.md after the first Pro install.",
+      };
+    }
+    const close = allItems().filter((entry) => entry.name.includes(name) || name.includes(entry.name)).map((entry) => entry.name).slice(0, 5);
+    throw new Error(`No item named "${name}".${close.length ? ` Did you mean: ${close.join(", ")}?` : ""} Search with search_components.`);
+  }
+  const config = projectConfig(cwd);
+  const usage = item.usage
+    ? { import: `import { ${item.usage.exportName} } from "${interpolateTarget(item.usage.importPath, config, "import")}";`, exportName: item.usage.exportName }
+    : null;
+  const result = {
+    name,
+    tier: "free",
+    kind: KIND[item.type] ?? "component",
+    title: item.title,
+    description: item.description,
+    category: item.category,
+    variants: item.variants ?? [],
+    sizes: item.sizes ?? [],
+    usage,
+    install: `npx mlola-ui add ${name}`,
+    dependsOn: item.registryDependencies ?? [],
+    engineDependencies: item.engineDependencies ?? {},
+    elements: elementsOf(name),
+  };
+  if (includeSource) {
+    result.source = (item.files ?? [])
+      .filter((file) => !file.path.includes("/_internal/"))
+      .map((file) => ({ path: interpolateTarget(file.target, config), content: fs.readFileSync(sourcePath(file.path), "utf8") }));
+  }
+  return result;
+}
+
+export function designData() {
+  return bundled("agents.json");
+}
+
+export function designGuide() {
+  return bundled("agents.md");
+}
+
+export function tokens(group) {
+  const data = designData();
+  if (!data) return [];
+  const groups = data.tokens;
+  if (!group) return groups;
+  const wanted = group.toLowerCase();
+  return groups.filter((entry) => entry.group.toLowerCase().includes(wanted) || entry.names.some((name) => name.includes(wanted)));
+}
+
+export function themes() {
+  const registry = loadRegistry();
+  return registry.themes ?? designData()?.themes ?? [];
+}
+
+/* ── Checking markup against the contract ─────────────────────────── */
+
+const SHARED = new Set(["data-tone", "data-variant", "data-size", "data-state", "data-status"]);
+const UTILITY = /^(-?(m|p)[trblxy]?-\d|flex$|grid$|block$|inline|hidden$|items-|justify-|gap-|w-|h-|min-|max-|text-(xs|sm|base|lg|xl|\d|[a-z]+-\d)|font-(bold|medium|semibold|light)|bg-|border-|rounded|shadow|ring-|space-[xy]-|leading-|tracking-|opacity-|z-\d|absolute$|relative$|fixed$|sticky$|overflow-|col-span|row-span|sm:|md:|lg:|xl:|hover:|focus:|dark:)/;
+const COLOR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/i;
+
+/**
+ * Checks HTML or JSX against the element contract. It reads string-valued
+ * class, className, style and data-* attributes; expressions in braces are
+ * skipped, since their value is only known at runtime.
+ */
+export function checkMarkup(markup) {
+  const contract = bundled("contract.json");
+  const known = new Set(contract?.classes ?? []);
+  const proPrefixes = (bundled("catalog.json")?.items ?? []).map((item) => `ml-${item.name}`);
+  const themeIds = new Set(themes().map((theme) => theme.id));
+  const issues = [];
+  const note = (severity, tag, message, fix) => issues.push({ severity, element: tag.slice(0, 120), message, ...(fix ? { fix } : {}) });
+
+  for (const match of markup.matchAll(/<([A-Za-z][\w.-]*)((?:\s+(?:[^\s"'>={}]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}))?))*)\s*\/?>/g)) {
+    const tag = match[0];
+    const attributes = new Map();
+    for (const attribute of match[2].matchAll(/([^\s"'>={}]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\{(?:[^{}]|\{[^{}]*\})*\})))?/g)) {
+      const [, name, double, single, expression] = attribute;
+      const value = double ?? single ?? (expression ? /^\{\s*["'`]([^"'`$]*)["'`]\s*\}$/.exec(expression)?.[1] ?? null : "");
+      attributes.set(name, value);
+      if (expression) attributes.set(`${name}:raw`, expression);
+    }
+    const classValue = attributes.get("class") ?? attributes.get("className");
+    const classes = typeof classValue === "string" ? classValue.split(/\s+/).filter(Boolean) : [];
+    const mlola = classes.filter((cls) => cls.startsWith("ml-"));
+
+    for (const cls of mlola) {
+      if (known.has(cls) || proPrefixes.some((prefix) => cls === prefix || cls.startsWith(`${prefix}-`))) continue;
+      const base = [...known].find((candidate) => cls.startsWith(`${candidate}-`) && elementsOf(candidate.slice(3)).length);
+      note(
+        "error",
+        tag,
+        `"${cls}" is not a Mlola class.`,
+        base ? `Mlola has no variant classes: use "${base}" with a data-* attribute (data-variant, data-tone, data-size).` : "Search with search_components, or name your own element with your own prefix (not ml-).",
+      );
+    }
+    const utilities = classes.filter((cls) => !cls.startsWith("ml-") && UTILITY.test(cls));
+    if (utilities.length) {
+      note("warning", tag, `Utility classes (${utilities.slice(0, 4).join(" ")}) do nothing here: Mlola ships no utility framework.`, "Use a component or composition primitive; for your own CSS, read --ml-* tokens.");
+    }
+
+    for (const [name, value] of attributes) {
+      if (!name.startsWith("data-") || typeof value !== "string") continue;
+      if (name === "data-theme" && value && !themeIds.has(value) && !/^th-[0-9a-z]{12}$/.test(value)) {
+        note("error", tag, `data-theme="${value}" is not a theme.`, `Use one of: ${[...themeIds].join(", ")}, or a Studio theme id.`);
+      }
+      if (name === "data-mode" && !["light", "dark"].includes(value)) {
+        note("error", tag, `data-mode is "light" or "dark"; "${value}" belongs in an attribute of your own.`, "data-theme and data-mode belong to the engine. Use data-kind or data-state for a component's own meaning.");
+      }
+      if (!SHARED.has(name) || !mlola.length) continue;
+      const allowed = new Set();
+      let reacts = false;
+      for (const cls of mlola) {
+        const values = contract?.elements?.[cls]?.[name];
+        if (values) {
+          reacts = true;
+          for (const entry of values) allowed.add(entry);
+        }
+      }
+      if (reacts && allowed.size && !allowed.has(value)) {
+        note("error", tag, `${name}="${value}" is not a value ${mlola.join(" ")} reacts to.`, `Allowed: ${[...allowed].sort().join(", ")}.`);
+      } else if (!reacts && mlola.every((cls) => known.has(cls))) {
+        note("warning", tag, `${name} has no effect on ${mlola.join(" ")}.`, `See get_component for the attributes it reacts to.`);
+      }
+    }
+
+    // A style string, or a JSX style object, with a color written into it.
+    const style = attributes.get("style") ?? attributes.get("style:raw");
+    if (typeof style === "string" && COLOR.test(style)) {
+      note("error", tag, "A color is written by hand in style.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens).");
+    }
+  }
+  return issues;
+}