brandrail 0.5.0 → 0.6.0

package/README.md

@@ -32,6 +32,8 @@ Brandrail only ever receives its hash, and the files it writes into the repo hol
 | `rules` | List the rules |
 | `connect` | `--no-browser`, `--no-install`, `--remote` (hosted MCP server), `--framework`, `--force` (sign in again) |
 | `mcp` | The MCP server over stdio, for AI tools. `--framework`, `--report` (send scores, never code) |
+| `migrate [paths]` | What's left on the way to the design system: other UI libraries (Material, MUI, Bootstrap, Ant Design, Chakra, PrimeNG) per library and per file. `--json`, `--top 30`, `--upload` |
+| `report` | A shareable HTML handover report (paths and counts, never code). `--out file.html` |
 | `whoami`, `logout` | Show or remove the saved sign-in |
 
 Nothing is uploaded unless you pass `--upload`, and code snippets are never uploaded.

package/dist/brandrail.mjs

@@ -8090,6 +8090,396 @@ function detectFramework(pkg) {
   return "html";
 }
 
+// ../engine/src/components.ts
+var SYNONYMS = {
+  button: ["btn", "cta", "action", "submit", "click"],
+  input: ["textinput", "textfield", "field", "text", "inputtext", "entry", "form"],
+  select: ["dropdown", "picker", "combobox", "menu", "options", "choose"],
+  textarea: ["multiline", "comment", "notes", "message", "inputtextarea"],
+  checkbox: ["check", "tick", "toggle", "agree"],
+  radio: ["radiogroup", "option", "choice"],
+  toggle: ["switch", "onoff"],
+  dialog: ["modal", "popup", "overlay", "lightbox"],
+  tooltip: ["hint", "hover", "popover"],
+  notification: ["toast", "alert", "flash", "banner", "snackbar", "message"],
+  avatar: ["profile", "user", "picture", "initials"],
+  datepicker: ["date", "calendar", "day", "schedule"],
+  progressbar: ["progress", "loading", "percent", "meter"],
+  loader: ["spinner", "loading", "busy"],
+  breadcrumb: ["path", "trail", "navigation", "nav"],
+  divider: ["separator", "rule", "hr", "line"],
+  table: ["datatable", "grid", "rows", "list"],
+  card: ["box", "panel", "tile", "container"],
+  label: ["badge", "tag", "chip", "pill", "status"],
+  tabs: ["tab", "segmented"]
+};
+var norm = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+var squash = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+function expand(words) {
+  const out = new Set(words);
+  for (const w of words) {
+    for (const [canon, syns] of Object.entries(SYNONYMS)) {
+      if (w === canon || syns.includes(w)) {
+        out.add(canon);
+        for (const s of syns) out.add(s);
+      }
+    }
+  }
+  return out;
+}
+function findComponents(config2, intent, limit = 5) {
+  const words = norm(intent).split(" ").filter((w) => w.length > 1);
+  const query = expand(words);
+  const q = squash(intent);
+  const out = [];
+  for (const c of config2.components ?? []) {
+    if (c.status === "deprecated") continue;
+    const name = squash(c.name);
+    let score = 0;
+    if (name === q) score += 100;
+    else if (q.includes(name) || name.includes(q)) score += 40;
+    const nameTerms = expand([name, ...(c.aliases ?? []).map(squash), ...c.replaces ?? []]);
+    for (const w of query) {
+      if (nameTerms.has(w)) score += 20;
+      else if (name.includes(w) && w.length > 2) score += 10;
+    }
+    const text2 = norm([c.description ?? "", ...c.usageRules ?? []].join(" "));
+    for (const w of words) if (w.length > 2 && text2.includes(w)) score += 3;
+    if (score >= 3) out.push({ component: c, score: score + (c.status === "stable" ? 1 : 0) });
+  }
+  return out.sort((a, b) => b.score - a.score || a.component.name.localeCompare(b.component.name)).slice(0, limit);
+}
+function findComponentByName(config2, name) {
+  const n = squash(name);
+  return (config2.components ?? []).find((c) => squash(c.name) === n || (c.aliases ?? []).some((a) => squash(a) === n));
+}
+
+// ../engine/src/migrate.ts
+var LIBRARY_LABEL = {
+  mui: "MUI (Material UI)",
+  "angular-material": "Angular Material",
+  bootstrap: "Bootstrap",
+  antd: "Ant Design",
+  chakra: "Chakra UI",
+  "react-bootstrap": "React Bootstrap",
+  primeng: "PrimeNG"
+};
+var CONCEPT_TAG = {
+  button: "button",
+  input: "input",
+  textarea: "textarea",
+  select: "select",
+  checkbox: "input[type=checkbox]",
+  radio: "input[type=radio]",
+  table: "table"
+};
+var REACT_LIBS = [
+  {
+    id: "mui",
+    packages: /^(@mui\/material|@mui\/joy|@material-ui\/core|@mui\/x-date-pickers)(\/|$)/,
+    names: {
+      Button: "button",
+      IconButton: "button",
+      Fab: "button",
+      LoadingButton: "button",
+      TextField: "input",
+      Input: "input",
+      OutlinedInput: "input",
+      Select: "select",
+      Autocomplete: "select",
+      NativeSelect: "select",
+      Checkbox: "checkbox",
+      Radio: "radio",
+      RadioGroup: "radio",
+      Switch: "toggle",
+      Dialog: "dialog",
+      Modal: "dialog",
+      Drawer: "dialog",
+      Tooltip: "tooltip",
+      Avatar: "avatar",
+      Chip: "label",
+      Badge: "label",
+      CircularProgress: "loader",
+      Skeleton: "loader",
+      LinearProgress: "progressbar",
+      Breadcrumbs: "breadcrumb",
+      Divider: "divider",
+      Snackbar: "notification",
+      Alert: "notification",
+      DatePicker: "datepicker",
+      DateField: "datepicker",
+      Tabs: "tabs",
+      Tab: "tabs",
+      Card: "card",
+      Paper: "card",
+      Table: "table",
+      TextareaAutosize: "textarea"
+    }
+  },
+  {
+    id: "antd",
+    packages: /^antd(\/|$)/,
+    names: {
+      Button: "button",
+      Input: "input",
+      InputNumber: "input",
+      Select: "select",
+      Checkbox: "checkbox",
+      Radio: "radio",
+      Switch: "toggle",
+      Modal: "dialog",
+      Drawer: "dialog",
+      Tooltip: "tooltip",
+      Popover: "tooltip",
+      Avatar: "avatar",
+      Tag: "label",
+      Badge: "label",
+      Spin: "loader",
+      Progress: "progressbar",
+      Breadcrumb: "breadcrumb",
+      Divider: "divider",
+      Alert: "notification",
+      DatePicker: "datepicker",
+      Tabs: "tabs",
+      Card: "card",
+      Table: "table"
+    }
+  },
+  {
+    id: "chakra",
+    packages: /^@chakra-ui\/react(\/|$)/,
+    names: {
+      Button: "button",
+      IconButton: "button",
+      Input: "input",
+      Textarea: "textarea",
+      Select: "select",
+      Checkbox: "checkbox",
+      Radio: "radio",
+      Switch: "toggle",
+      Modal: "dialog",
+      Drawer: "dialog",
+      Tooltip: "tooltip",
+      Avatar: "avatar",
+      Tag: "label",
+      Badge: "label",
+      Spinner: "loader",
+      Progress: "progressbar",
+      Breadcrumb: "breadcrumb",
+      Divider: "divider",
+      Alert: "notification",
+      Tabs: "tabs",
+      Card: "card",
+      Table: "table"
+    }
+  },
+  {
+    id: "react-bootstrap",
+    packages: /^react-bootstrap(\/|$)/,
+    names: {
+      Button: "button",
+      Form: "input",
+      FormControl: "input",
+      FormSelect: "select",
+      FormCheck: "checkbox",
+      Modal: "dialog",
+      Offcanvas: "dialog",
+      Tooltip: "tooltip",
+      OverlayTrigger: "tooltip",
+      Badge: "label",
+      Spinner: "loader",
+      ProgressBar: "progressbar",
+      Breadcrumb: "breadcrumb",
+      Alert: "notification",
+      Toast: "notification",
+      Tabs: "tabs",
+      Tab: "tabs",
+      Card: "card",
+      Table: "table"
+    }
+  }
+];
+var MAT_TAGS = {
+  "mat-form-field": "input",
+  "mat-select": "select",
+  "mat-autocomplete": "select",
+  "mat-checkbox": "checkbox",
+  "mat-radio-group": "radio",
+  "mat-radio-button": "radio",
+  "mat-slide-toggle": "toggle",
+  "mat-progress-bar": "progressbar",
+  "mat-spinner": "loader",
+  "mat-progress-spinner": "loader",
+  "mat-datepicker": "datepicker",
+  "mat-date-range-picker": "datepicker",
+  "mat-divider": "divider",
+  "mat-chip": "label",
+  "mat-chip-listbox": "label",
+  "mat-chip-option": "label",
+  "mat-tab-group": "tabs",
+  "mat-card": "card",
+  "mat-table": "table",
+  "mat-dialog-content": "dialog",
+  "mat-button-toggle-group": "button"
+};
+var MAT_ATTRS = {
+  "mat-button": "button",
+  "mat-raised-button": "button",
+  "mat-flat-button": "button",
+  "mat-stroked-button": "button",
+  "mat-icon-button": "button",
+  "mat-fab": "button",
+  "mat-mini-fab": "button",
+  matButton: "button",
+  matInput: "input",
+  matTooltip: "tooltip",
+  matBadge: "label",
+  "mat-table": "table"
+};
+var PRIME_TAGS = {
+  "p-button": "button",
+  "p-dropdown": "select",
+  "p-select": "select",
+  "p-multiselect": "select",
+  "p-checkbox": "checkbox",
+  "p-radiobutton": "radio",
+  "p-inputswitch": "toggle",
+  "p-toggleswitch": "toggle",
+  "p-dialog": "dialog",
+  "p-avatar": "avatar",
+  "p-tag": "label",
+  "p-badge": "label",
+  "p-progressspinner": "loader",
+  "p-progressbar": "progressbar",
+  "p-breadcrumb": "breadcrumb",
+  "p-divider": "divider",
+  "p-toast": "notification",
+  "p-message": "notification",
+  "p-calendar": "datepicker",
+  "p-datepicker": "datepicker",
+  "p-tabview": "tabs",
+  "p-tabs": "tabs",
+  "p-card": "card",
+  "p-table": "table"
+};
+var BOOTSTRAP_CLASSES = [
+  [/^btn$/, "button", "btn"],
+  [/^form-control$/, "input", "form-control"],
+  [/^(form-select|custom-select)$/, "select", "form-select"],
+  [/^form-switch$/, "toggle", "form-switch"],
+  [/^(form-check-input|custom-control-input)$/, "checkbox", "form-check-input"],
+  [/^modal$/, "dialog", "modal"],
+  [/^alert$/, "notification", "alert"],
+  [/^toast$/, "notification", "toast"],
+  [/^badge$/, "label", "badge"],
+  [/^spinner-(border|grow)$/, "loader", "spinner"],
+  [/^progress$/, "progressbar", "progress"],
+  [/^breadcrumb$/, "breadcrumb", "breadcrumb"],
+  [/^nav-tabs$/, "tabs", "nav-tabs"],
+  [/^card$/, "card", "card"]
+];
+var BOOTSTRAP_EVIDENCE = /\b(?:btn-(?:primary|secondary|success|danger|warning|info|light|dark|link|outline-[a-z]+)|form-control|form-select|form-check-input|custom-select|custom-control-input|spinner-border|spinner-grow|col-(?:xs|sm|md|lg|xl|xxl)-\d{1,2}|data-bs-[a-z]+|data-toggle)\b/;
+function* matchAll(re, text2) {
+  let m;
+  const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`);
+  while (m = g.exec(text2)) {
+    yield m;
+    if (m[0].length === 0) g.lastIndex++;
+  }
+}
+function findLegacyUsages(code, kind) {
+  const out = [];
+  if (kind === "css") return out;
+  for (const lib of REACT_LIBS) {
+    const local = /* @__PURE__ */ new Map();
+    for (const m of matchAll(/\bimport\s+(?:type\s+)?(?:(\w+)\s*,?\s*)?(?:\{([^}]*)\})?\s*from\s*(['"])([^'"]+)\3/g, code)) {
+      if (!lib.packages.test(m[4])) continue;
+      const sub = /\/([A-Z]\w*)$/.exec(m[4])?.[1];
+      if (m[1] && sub && lib.names[sub]) local.set(m[1], sub);
+      for (const part of (m[2] ?? "").split(",")) {
+        const [orig, alias] = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/).map((s) => s.trim());
+        if (orig && lib.names[orig]) local.set(alias || orig, orig);
+      }
+    }
+    if (!local.size) continue;
+    const names = [...local.keys()].map((n) => n.replace(/\$/g, "\\$")).join("|");
+    for (const m of matchAll(new RegExp(`<(${names})(?=[\\s/>])`, "g"), code)) {
+      const orig = local.get(m[1]);
+      out.push({ offset: m.index, library: lib.id, what: `${LIBRARY_LABEL[lib.id].split(" ")[0]} <${orig}>`, concept: lib.names[orig] });
+    }
+  }
+  for (const m of matchAll(/<((?:mat|p)-[a-z-]+)(?=[\s/>])([^>]*)>/g, code)) {
+    const tag = m[1];
+    const concept = MAT_TAGS[tag] ?? PRIME_TAGS[tag];
+    if (concept) out.push({ offset: m.index, library: tag.startsWith("mat-") ? "angular-material" : "primeng", what: `<${tag}>`, concept });
+  }
+  for (const m of matchAll(/<([a-z][\w-]*)(?=[\s/>])([^>]*)>/g, code)) {
+    for (const a of matchAll(/(?<=\s)\[?(mat-raised-button|mat-flat-button|mat-stroked-button|mat-icon-button|mat-button|mat-mini-fab|mat-fab|mat-table|matButton|matInput|matTooltip|matBadge)\]?(?=[\s=>/]|$)/g, m[2])) {
+      const name = a[1];
+      const concept = MAT_ATTRS[name];
+      if (concept) out.push({ offset: m.index, library: "angular-material", what: `<${m[1]} ${name}>`, concept });
+    }
+  }
+  if (!BOOTSTRAP_EVIDENCE.test(code)) return out.sort((a, b) => a.offset - b.offset);
+  for (const m of matchAll(/\b(?:class|className)\s*=\s*(["'])([^"']*)\1/g, code)) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const cls of m[2].split(/\s+/)) {
+      for (const [re, concept, label] of BOOTSTRAP_CLASSES) {
+        if (re.test(cls) && !seen.has(concept)) {
+          seen.add(concept);
+          out.push({ offset: m.index, library: "bootstrap", what: `class "${label}"`, concept });
+        }
+      }
+    }
+  }
+  for (const m of matchAll(/data-(?:bs-)?toggle\s*=\s*["'](tooltip|modal|popover)["']/g, code)) {
+    out.push({ offset: m.index, library: "bootstrap", what: `data-bs-toggle="${m[1]}"`, concept: m[1] === "modal" ? "dialog" : "tooltip" });
+  }
+  return out.sort((a, b) => a.offset - b.offset);
+}
+function componentForConcept(config2, concept) {
+  const tag = CONCEPT_TAG[concept];
+  if (tag && config2.replaces.get(tag)) return config2.replaces.get(tag);
+  return findComponents({ components: config2.components }, concept, 1)[0]?.component;
+}
+function migrationMap(config2, framework, libraries) {
+  const rows = [];
+  const add = (library, from, concept) => {
+    if (libraries && !libraries.includes(library)) return;
+    const c = componentForConcept(config2, concept);
+    rows.push({ library, from, concept, to: c ? { name: c.name, usage: resolveUsage(c, framework) } : void 0 });
+  };
+  for (const lib of REACT_LIBS) for (const [name, concept] of Object.entries(lib.names)) add(lib.id, `<${name}>`, concept);
+  for (const [tag, concept] of Object.entries(MAT_TAGS)) add("angular-material", `<${tag}>`, concept);
+  for (const [attr, concept] of Object.entries(MAT_ATTRS)) add("angular-material", attr, concept);
+  for (const [tag, concept] of Object.entries(PRIME_TAGS)) add("primeng", `<${tag}>`, concept);
+  for (const [, concept, label] of BOOTSTRAP_CLASSES) add("bootstrap", `.${label}`, concept);
+  return rows;
+}
+function migrationMapMarkdown(config2, framework, libraries) {
+  const rows = migrationMap(config2, framework, libraries);
+  const lines = ["| From | Library | Use instead |", "| --- | --- | --- |"];
+  for (const r of rows) {
+    const to = !r.to ? `_no ${r.concept} component yet: tokens + semantic HTML_` : r.to.usage ? `\`<${r.to.usage.tag}>\`${r.to.usage.importLine ? ` (\`${r.to.usage.importLine}\`)` : ""}` : `_${r.to.name} has no ${framework} version yet_`;
+    lines.push(`| \`${r.from}\` | ${LIBRARY_LABEL[r.library]} | ${to} |`);
+  }
+  return lines.join("\n");
+}
+function detectLibraries(pkg) {
+  if (!pkg) return [];
+  const deps = { ...pkg.devDependencies, ...pkg.dependencies };
+  const has = (re) => Object.keys(deps).some((d) => re.test(d));
+  const out = [];
+  if (has(/^(@mui\/material|@mui\/joy|@material-ui\/core)$/)) out.push("mui");
+  if (has(/^@angular\/material$/)) out.push("angular-material");
+  if (has(/^(bootstrap|ngx-bootstrap|@ng-bootstrap\/ng-bootstrap|bootstrap-vue(-next)?)$/)) out.push("bootstrap");
+  if (has(/^react-bootstrap$/)) out.push("react-bootstrap", "bootstrap");
+  if (has(/^antd$/)) out.push("antd");
+  if (has(/^@chakra-ui\/react$/)) out.push("chakra");
+  if (has(/^primeng$/)) out.push("primeng");
+  return [...new Set(out)];
+}
+
 // ../engine/src/rules.ts
 var MARKUP = ["jsx", "vue", "svelte", "html", "template"];
 var ALL = ["jsx", "vue", "svelte", "html", "template", "css"];
@@ -8623,6 +9013,26 @@ var componentProps = {
     return out;
   }
 };
+var legacyLibrary = {
+  id: "legacy-library",
+  title: "Other UI library in use",
+  description: "Pieces of Material, MUI, Bootstrap, Ant Design, Chakra or PrimeNG that a design system component replaces. The count is the migration still to do.",
+  defaultSeverity: "warning",
+  kinds: ["jsx", "vue", "svelte", "html", "template"],
+  check({ code, kind, config: config2, framework }) {
+    const out = [];
+    for (const u of findLegacyUsages(code, kind)) {
+      const comp = componentForConcept(config2, u.concept);
+      const usage = comp ? resolveUsage(comp, framework) : null;
+      out.push({
+        offset: u.offset,
+        message: `${u.what} (${LIBRARY_LABEL[u.library]}) should be ${comp ? comp.name : `a design system ${u.concept}`}`,
+        suggestion: comp && usage ? useSuggestion(comp, usage) : comp ? `${comp.name} has no ${FRAMEWORK_LABEL[framework]} version yet: add one in the registry, or build it with tokens` : `No ${u.concept} component in the registry yet: add one, or build it with tokens and semantic HTML`
+      });
+    }
+    return out;
+  }
+};
 var RULES = [
   noHardcodedColor,
   noRawPaletteClass,
@@ -8632,7 +9042,8 @@ var RULES = [
   fontFamily,
   radiusScale,
   imgAlt,
-  componentProps
+  componentProps,
+  legacyLibrary
 ];
 var RULE_IDS = RULES.map((r) => r.id);
 
@@ -8774,7 +9185,7 @@ function makeIgnore(globs) {
 }
 
 // ../engine/src/check.ts
-var ENGINE_VERSION = "0.5.0";
+var ENGINE_VERSION = "0.6.0";
 var WEIGHT = { error: 4, warning: 1.5, info: 0.25 };
 function computeScore(counts, lines) {
   const penalty = counts.error * WEIGHT.error + counts.warning * WEIGHT.warning + counts.info * WEIGHT.info;
@@ -9636,6 +10047,9 @@ function generateInstructions(config2, opts = {}) {
   if (sizeVars.length) lines.push(`- Font sizes come from the type scale: ${sizeVars.join(", ")}. Matching line heights are \`--font-line-height-*\`.`);
   if (r.fonts.length) lines.push(`- Fonts: use ${r.fontVars.map((v) => `\`var(${v})\``).join(" or ")}; never set another font-family.`);
   lines.push("");
+  lines.push("## Migrating existing UI");
+  lines.push("- Code that still uses Material, MUI, Bootstrap, Ant Design, Chakra, PrimeNG or raw HTML controls is migration work (`legacy-library` findings). `npx brandrail migrate` lists what's left per file. In Claude Code, use the `brandrail-migrate` skill (or the `brandrail-migrator` agent) and work in small batches; keep behaviour identical.");
+  lines.push("");
   lines.push("## Before you finish");
   lines.push("- If the Brandrail MCP server is connected, call `validate_snippet` on the UI you wrote and fix every violation.");
   lines.push("- Otherwise run `npx brandrail check` and fix errors before committing.");
@@ -9664,70 +10078,6 @@ ${block}
 `;
 }
 
-// ../engine/src/components.ts
-var SYNONYMS = {
-  button: ["btn", "cta", "action", "submit", "click"],
-  input: ["textinput", "textfield", "field", "text", "inputtext", "entry", "form"],
-  select: ["dropdown", "picker", "combobox", "menu", "options", "choose"],
-  textarea: ["multiline", "comment", "notes", "message", "inputtextarea"],
-  checkbox: ["check", "tick", "toggle", "agree"],
-  radio: ["radiogroup", "option", "choice"],
-  toggle: ["switch", "onoff"],
-  dialog: ["modal", "popup", "overlay", "lightbox"],
-  tooltip: ["hint", "hover", "popover"],
-  notification: ["toast", "alert", "flash", "banner", "snackbar", "message"],
-  avatar: ["profile", "user", "picture", "initials"],
-  datepicker: ["date", "calendar", "day", "schedule"],
-  progressbar: ["progress", "loading", "percent", "meter"],
-  loader: ["spinner", "loading", "busy"],
-  breadcrumb: ["path", "trail", "navigation", "nav"],
-  divider: ["separator", "rule", "hr", "line"],
-  table: ["datatable", "grid", "rows", "list"],
-  card: ["box", "panel", "tile", "container"],
-  label: ["badge", "tag", "chip", "pill", "status"],
-  tabs: ["tab", "segmented"]
-};
-var norm = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
-var squash = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
-function expand(words) {
-  const out = new Set(words);
-  for (const w of words) {
-    for (const [canon, syns] of Object.entries(SYNONYMS)) {
-      if (w === canon || syns.includes(w)) {
-        out.add(canon);
-        for (const s of syns) out.add(s);
-      }
-    }
-  }
-  return out;
-}
-function findComponents(config2, intent, limit = 5) {
-  const words = norm(intent).split(" ").filter((w) => w.length > 1);
-  const query = expand(words);
-  const q = squash(intent);
-  const out = [];
-  for (const c of config2.components ?? []) {
-    if (c.status === "deprecated") continue;
-    const name = squash(c.name);
-    let score = 0;
-    if (name === q) score += 100;
-    else if (q.includes(name) || name.includes(q)) score += 40;
-    const nameTerms = expand([name, ...(c.aliases ?? []).map(squash), ...c.replaces ?? []]);
-    for (const w of query) {
-      if (nameTerms.has(w)) score += 20;
-      else if (name.includes(w) && w.length > 2) score += 10;
-    }
-    const text2 = norm([c.description ?? "", ...c.usageRules ?? []].join(" "));
-    for (const w of words) if (w.length > 2 && text2.includes(w)) score += 3;
-    if (score >= 3) out.push({ component: c, score: score + (c.status === "stable" ? 1 : 0) });
-  }
-  return out.sort((a, b) => b.score - a.score || a.component.name.localeCompare(b.component.name)).slice(0, limit);
-}
-function findComponentByName(config2, name) {
-  const n = squash(name);
-  return (config2.components ?? []).find((c) => squash(c.name) === n || (c.aliases ?? []).some((a) => squash(a) === n));
-}
-
 // ../engine/src/mcp-config.ts
 var json = (o) => `${JSON.stringify(o, null, 2)}
 `;
@@ -10371,6 +10721,227 @@ function auditBrandKit(tokens) {
   }).sort((a, b) => a.severity === b.severity ? 0 : a.severity === "error" ? -1 : 1);
 }
 
+// ../engine/src/migrate-skill.ts
+var MIGRATE_SKILL_FILE = ".claude/skills/brandrail-migrate/SKILL.md";
+var MIGRATE_AGENT_FILE = ".claude/agents/brandrail-migrator.md";
+function librariesFor(pkg) {
+  if (!pkg) return void 0;
+  return [.../* @__PURE__ */ new Set([...detectLibraries(pkg), "bootstrap"])];
+}
+function migrationSkill(config2, opts = {}) {
+  const fw = config2.framework ?? "react";
+  const libs = librariesFor(opts.pkg);
+  const ds = opts.org ? `the ${opts.org} design system` : "the design system";
+  return `---
+name: brandrail-migrate
+description: Migrate existing UI in this repo to ${ds}. Replaces Material, MUI, Bootstrap, Ant Design, Chakra, PrimeNG and raw HTML controls with design system components, and hard-coded colours, spacing and fonts with Brand Kit tokens. Use when asked to migrate, reskin, adopt the design system, or clear Brandrail findings across files.
+---
+
+# Migrate UI to ${ds}
+
+This is ${fw === "angular" ? "an" : "a"} ${FRAMEWORK_LABEL[fw]} project. The design system rules are in CLAUDE.md / AGENTS.md (section "Design system rules"); follow them.
+If the Brandrail MCP server is connected, use \`get_component_docs\` for each component's props and events, and \`validate_snippet\` on every file you change.
+
+## Steps
+
+1. **See what's left**: \`npx brandrail migrate\` lists findings per file, worst first (\`--json\` for a machine-readable list).
+2. **Pick a small batch**: the files the user named, or the top 1-5 files from the list. Never the whole repo at once.
+3. **Migrate each file**, finding by finding:
+   - \`legacy-library\` and \`forbidden-import\`: replace the other library's piece with the component in the table below. Map its props and events
+     to the component's (check \`get_component_docs\`), keep every binding, handler, validation and accessibility attribute, then remove the old import.
+   - \`prefer-official-component\`: raw \`<button>\`, \`<select>\`, \`<input>\` \u2192 the design system component.
+   - \`no-hardcoded-color\`, \`spacing-scale\`, \`radius-scale\`, \`font-family\`: use the Brand Kit CSS variables, never new literal values.
+   - \`component-props\`: only the props / inputs / events the component lists.
+4. **Prove it**: \`npx brandrail check <the files>\` shows none of these findings for them, and the project's own build, lint and tests still pass.
+   Look at the screen if you can: the layout should look the same apart from the brand.
+5. **Commit the batch** ("Migrate <area> to the design system"), then go back to step 1.
+6. **Remove a library** from package.json only when \`npx brandrail migrate\` shows 0 usages of it in the whole repo, and say so in the commit.
+
+## Rules
+
+- Change the look, not the behaviour: no logic, routing, data or API changes in a migration commit.
+- If a piece has no design system component (the table says so), build it with semantic HTML and the Brand Kit tokens, and list it in your summary
+  so the design system team can add a component.
+- Ask before deleting files or changing shared code (layouts, base components) that many screens use.
+${fw === "angular" ? "- Angular: every NgModule or standalone component that uses a custom element needs `CUSTOM_ELEMENTS_SCHEMA`; read event values with `$any($event).detail`; bind properties in camelCase (`[selectedDate]`).\n" : ""}
+## What replaces what (${FRAMEWORK_LABEL[fw]})
+
+${libs ? `Libraries in this project: ${libs.map((l) => LIBRARY_LABEL[l]).join(", ")}.
+
+` : ""}${migrationMapMarkdown(resolveConfig(config2), fw, libs)}
+`;
+}
+function migrationAgent(opts = {}) {
+  return `---
+name: brandrail-migrator
+description: Migrates a batch of UI files to ${opts.org ? `the ${opts.org}` : "the"} design system using the brandrail-migrate skill. Use for "migrate <files or folder> to the design system", one batch per call.
+tools: Read, Edit, Write, Grep, Glob, Bash
+---
+
+You migrate UI code to the design system. Follow the \`brandrail-migrate\` skill exactly (.claude/skills/brandrail-migrate/SKILL.md).
+
+For the files or folder you're given:
+1. Run \`npx brandrail check <paths>\` to list the findings.
+2. Migrate every finding in those files, keeping behaviour identical.
+3. Run \`npx brandrail check <paths>\` again until it's clean, then the project's build or tests if they're quick.
+4. Reply with: files changed, findings fixed, anything that had no design system component, and anything you weren't sure about.
+
+Don't touch files outside the batch. Don't commit unless you were asked to.
+`;
+}
+
+// ../engine/src/project.ts
+var KIT = "@brandrail/kit";
+function mergeProjectConfig(prev, kit) {
+  if (!prev) return kit;
+  return {
+    ...prev,
+    ...kit,
+    rules: { ...prev.rules, ...kit.rules },
+    ignore: prev.ignore ?? kit.ignore,
+    tokensCss: prev.tokensCss,
+    framework: prev.framework ?? kit.framework
+  };
+}
+function tokensCssContent(config2, org) {
+  let css = generateTokensCss(config2.tokens, { version: config2.tokenVersion, org });
+  const usesKit = (config2.components ?? []).some((c) => c.importPath === KIT);
+  if (usesKit) css += `
+/* ${KIT} follows the Brand Kit: colours, font, spacing, radius and type scale. */
+${kitBridgeCss(config2.tokens)}
+`;
+  return { css, usesKit };
+}
+var CURSOR_GLOBS = "**/*.{tsx,jsx,ts,vue,svelte,html,css,scss,php,twig,hbs,mustache}";
+function ruleFileContent(file2, md, before) {
+  if (file2.endsWith(".mdc")) return `---
+description: Design system rules from Brandrail
+globs: ["${CURSOR_GLOBS}"]
+alwaysApply: true
+---
+
+${md}
+`;
+  if (file2.startsWith(".windsurf/")) return `---
+trigger: always_on
+---
+
+${md}
+`;
+  return upsertSection(before, md);
+}
+
+// ../engine/src/migrate-status.ts
+var MIGRATION_RULES = new Set(RULES.map((r) => r.id).filter((id) => id !== "img-alt"));
+var LABEL_TO_ID = new Map(Object.entries(LIBRARY_LABEL).map(([id, label]) => [label, id]));
+function migrationStatus(files, configInput) {
+  const config2 = "replaces" in configInput ? configInput : resolveConfig(configInput);
+  const report = check(files, config2, { snippets: false });
+  const per = /* @__PURE__ */ new Map();
+  const libraries = {};
+  const byRule = {};
+  for (const v of report.violations) {
+    if (!MIGRATION_RULES.has(v.ruleId)) continue;
+    byRule[v.ruleId] = (byRule[v.ruleId] ?? 0) + 1;
+    const f = per.get(v.file) ?? { path: v.file, findings: 0, byRule: {}, libraries: [] };
+    f.findings++;
+    f.byRule[v.ruleId] = (f.byRule[v.ruleId] ?? 0) + 1;
+    if (v.ruleId === "legacy-library") {
+      const label = /\(([^()]*(?:\([^()]*\))?[^()]*)\) should be/.exec(v.message)?.[1];
+      const id = label ? LABEL_TO_ID.get(label) : void 0;
+      if (id) {
+        libraries[id] = (libraries[id] ?? 0) + 1;
+        if (!f.libraries.includes(id)) f.libraries.push(id);
+      }
+    }
+    per.set(v.file, f);
+  }
+  const list = [...per.values()].sort((a, b) => b.findings - a.findings || a.path.localeCompare(b.path));
+  const filesClean = Math.max(0, report.filesScanned - list.length);
+  return {
+    report,
+    files: list,
+    filesScanned: report.filesScanned,
+    filesClean,
+    progress: report.filesScanned ? Math.round(filesClean / report.filesScanned * 100) : 100,
+    libraries,
+    byRule
+  };
+}
+
+// ../engine/src/report-html.ts
+var esc2 = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+var ruleTitle = (id) => RULES.find((r) => r.id === id)?.title ?? id;
+function formatHandoverHtml(s, meta3) {
+  const when = meta3.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const date5 = new Date(when).toLocaleDateString("en-AU", { day: "numeric", month: "long", year: "numeric" });
+  const libs = Object.entries(s.libraries);
+  const rules = Object.entries(s.byRule).sort((a, b) => b[1] - a[1]);
+  const total = rules.reduce((a, [, n]) => a + n, 0);
+  const tone = (n) => n >= 90 ? "good" : n >= 70 ? "warn" : "bad";
+  const trend = meta3.history?.length ? `<section><h2>Progress over time</h2><table><thead><tr><th>Date</th><th class="n">Files done</th><th class="n">Brand score</th></tr></thead><tbody>${[...meta3.history, { at: when, progress: s.progress, score: s.report.score }].map((h) => `<tr><td>${esc2(new Date(h.at).toLocaleDateString("en-AU"))}</td><td class="n">${h.progress}%</td><td class="n">${h.score}</td></tr>`).join("")}</tbody></table></section>` : "";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Design system handover \u2014 ${esc2(meta3.project)}</title>
+<style>
+  :root { --fg:#1f2328; --muted:#59636e; --line:#d1d9e0; --bg:#fff; --subtle:#f6f8fa; --good:#1a7f37; --warn:#9a6700; --bad:#cf222e; --accent:#0969da; }
+  @media (prefers-color-scheme: dark) { :root { --fg:#e6edf3; --muted:#9198a1; --line:#3d444d; --bg:#0d1117; --subtle:#151b23; --good:#3fb950; --warn:#d29922; --bad:#f85149; --accent:#4493f8; } }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif; }
+  main { max-width: 900px; margin: 0 auto; padding: 40px 16px 64px; }
+  h1 { font-size: 24px; margin: 0 0 4px; } h2 { font-size: 16px; margin: 32px 0 8px; }
+  .meta { color: var(--muted); margin: 0 0 24px; }
+  .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 12px; }
+  .card { border: 1px solid var(--line); border-radius: 8px; padding: 14px 16px; background: var(--subtle); }
+  .card p { margin: 0; color: var(--muted); font-size: 12px; } .card b { display: block; font-size: 26px; margin-top: 2px; }
+  .good { color: var(--good); } .warn { color: var(--warn); } .bad { color: var(--bad); }
+  .bar { height: 10px; border-radius: 5px; background: var(--line); overflow: hidden; margin-top: 8px; }
+  .bar span { display: block; height: 100%; background: var(--good); }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--line); vertical-align: top; }
+  th { color: var(--muted); font-weight: 500; } .n { text-align: right; font-variant-numeric: tabular-nums; }
+  code { font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; background: var(--subtle); padding: 1px 4px; border-radius: 4px; }
+  ol li { margin: 4px 0; } footer { margin-top: 40px; color: var(--muted); font-size: 12px; }
+  @media print { body { font-size: 12px; } main { padding: 0; } .card { break-inside: avoid; } }
+</style>
+</head>
+<body>
+<main>
+<h1>Design system handover: ${esc2(meta3.project)}</h1>
+<p class="meta">${esc2(date5)}${meta3.org ? ` \xB7 ${esc2(meta3.org)} design system` : ""}${meta3.kitVersion ? ` \xB7 Brand Kit v${esc2(meta3.kitVersion)}` : ""}${meta3.framework ? ` \xB7 ${esc2(meta3.framework)}` : ""}${meta3.branch ? ` \xB7 branch <code>${esc2(meta3.branch)}</code>` : ""}${meta3.commit ? ` @ <code>${esc2(meta3.commit.slice(0, 7))}</code>` : ""}</p>
+
+<div class="cards">
+  <div class="card"><p>Files on the design system</p><b class="${tone(s.progress)}">${s.progress}%</b><div class="bar"><span style="width:${s.progress}%"></span></div></div>
+  <div class="card"><p>Brand score</p><b class="${tone(s.report.score)}">${s.report.score}/100</b></div>
+  <div class="card"><p>UI files done</p><b>${s.filesClean} / ${s.filesScanned}</b></div>
+  <div class="card"><p>Findings left</p><b class="${total ? "warn" : "good"}">${total}</b></div>
+</div>
+
+${libs.length ? `<section><h2>Other UI libraries still in use</h2><table><thead><tr><th>Library</th><th class="n">Usages left</th></tr></thead><tbody>${libs.map(([id, n]) => `<tr><td>${esc2(LIBRARY_LABEL[id])}</td><td class="n">${n}</td></tr>`).join("")}</tbody></table></section>` : `<section><h2>Other UI libraries</h2><p class="good">None left in the code.</p></section>`}
+
+<section><h2>What's left, by kind</h2>${rules.length ? `<table><thead><tr><th>Finding</th><th>Rule</th><th class="n">Count</th></tr></thead><tbody>${rules.map(([id, n]) => `<tr><td>${esc2(ruleTitle(id))}</td><td><code>${esc2(id)}</code></td><td class="n">${n}</td></tr>`).join("")}</tbody></table>` : `<p class="good">Nothing: every UI file follows the design system.</p>`}</section>
+
+${s.files.length ? `<section><h2>Files with the most work left</h2><table><thead><tr><th>File</th><th>Libraries</th><th class="n">Findings</th></tr></thead><tbody>${s.files.slice(0, 40).map((f) => `<tr><td><code>${esc2(f.path)}</code></td><td>${esc2(f.libraries.map((l) => LIBRARY_LABEL[l]).join(", "))}</td><td class="n">${f.findings}</td></tr>`).join("")}</tbody></table>${s.files.length > 40 ? `<p class="meta">\u2026and ${s.files.length - 40} more files.</p>` : ""}</section>` : ""}
+
+${trend}
+
+<section><h2>How to finish</h2><ol>
+  <li>Run <code>npx brandrail connect</code> in the repo once (rule files, MCP server and the migration skill for AI tools).</li>
+  <li>Ask the AI tool: <em>"migrate ${esc2(s.files[0]?.path ?? "the next files")} to the design system"</em>. In Claude Code the <code>brandrail-migrate</code> skill and <code>brandrail-migrator</code> agent do it in small, checked batches.</li>
+  <li>Track progress with <code>npx brandrail migrate</code>; make the GitHub check required once the score holds above the team's threshold.</li>
+  <li>Remove each old library from <code>package.json</code> when it shows 0 usages here.</li>
+</ol></section>
+
+<footer>Generated by Brandrail (<code>npx brandrail report</code>). Only file paths and counts are included: no source code.</footer>
+</main>
+</body>
+</html>
+`;
+}
+
 // src/api.ts
 var DEFAULT_API = "https://www.brandrail.com.au";
 function apiBase() {
@@ -11159,7 +11730,7 @@ __export(util_exports, {
   defineLazy: () => defineLazy,
   defineLazyInternal: () => defineLazyInternal,
   derived: () => derived,
-  esc: () => esc2,
+  esc: () => esc3,
   escapeRegex: () => escapeRegex,
   explicitlyAborted: () => explicitlyAborted,
   extend: () => extend,
@@ -11390,7 +11961,7 @@ function randomString(length = 10) {
   }
   return str;
 }
-function esc2(str) {
+function esc3(str) {
   return JSON.stringify(str);
 }
 function slugify(input2) {
@@ -14190,7 +14761,7 @@ var $ZodObjectJIT = /* @__PURE__ */ $constructor("$ZodObjectJIT", (inst, def) =>
       if (key === "__proto__")
         continue;
       const id = ids[key];
-      const k = typeof key === "symbol" ? `syms[${syms.indexOf(key)}]` : esc2(key);
+      const k = typeof key === "symbol" ? `syms[${syms.indexOf(key)}]` : esc3(key);
       const isPresent = `${k} in input`;
       const schema = shape[key];
       const optin = schema?._zod?.optin;
@@ -23865,7 +24436,7 @@ function generatePropertiesChecks(doc, ctx, def, accessor) {
   doc.write(`if (${accessor} == null) return INVALID;`);
   const shape = def.shape;
   for (const key of Reflect.ownKeys(shape)) {
-    const keyExpr = typeof key === "symbol" ? addConstant(ctx, key) : esc2(key);
+    const keyExpr = typeof key === "symbol" ? addConstant(ctx, key) : esc3(key);
     const inputVar = newVar(ctx);
     doc.write(`const ${inputVar} = ${accessor}[${keyExpr}];`);
     compileChild(doc, ctx, shape[key], inputVar, false);
@@ -24039,16 +24610,16 @@ function generateStringFormatCheck(doc, ctx, def, accessor, needsValue = true) {
       doc.write(`if (${accessor} !== ${accessor}.toUpperCase()) return INVALID;`);
       break;
     case "includes":
-      doc.write(`if (!${accessor}.includes(${esc2(def.includes)})) return INVALID;`);
+      doc.write(`if (!${accessor}.includes(${esc3(def.includes)})) return INVALID;`);
       break;
     case "starts_with": {
       const prefix = def.prefix;
-      doc.write(`if (${accessor}.slice(0, ${prefix.length}) !== ${esc2(prefix)}) return INVALID;`);
+      doc.write(`if (${accessor}.slice(0, ${prefix.length}) !== ${esc3(prefix)}) return INVALID;`);
       break;
     }
     case "ends_with": {
       const suffix = def.suffix;
-      doc.write(`if (${accessor}.slice(-${suffix.length}) !== ${esc2(suffix)}) return INVALID;`);
+      doc.write(`if (${accessor}.slice(-${suffix.length}) !== ${esc3(suffix)}) return INVALID;`);
       break;
     }
     default: {
@@ -24254,8 +24825,8 @@ function generateObjectCheck(doc, ctx, schema, accessor, buildsValue = true) {
   const keys = Object.keys(shape);
   const symbolKeys = Object.getOwnPropertySymbols(shape);
   const allKeys = symbolKeys.length ? [...keys, ...symbolKeys] : keys;
-  const keyExpr = (k) => typeof k === "symbol" ? addConstant(ctx, k) : esc2(k);
-  const propKey = (k) => typeof k === "symbol" ? `[${keyExpr(k)}]` : esc2(k);
+  const keyExpr = (k) => typeof k === "symbol" ? addConstant(ctx, k) : esc3(k);
+  const propKey = (k) => typeof k === "symbol" ? `[${keyExpr(k)}]` : esc3(k);
   const propShape = shape;
   if (keys.includes("__proto__")) {
     throw new ZodCompileUnsupportedError('object shape key "__proto__"');
@@ -24299,7 +24870,7 @@ function generateObjectCheck(doc, ctx, schema, accessor, buildsValue = true) {
   if (catchall) {
     const catchallType = catchall._zod.def.type;
     if (catchallType === "never") {
-      const condition = keys.map((k) => `k !== ${esc2(k)}`).join(" && ") || "true";
+      const condition = keys.map((k) => `k !== ${esc3(k)}`).join(" && ") || "true";
       doc.write(`for (const k in ${accessor}) {`);
       doc.indented((d) => {
         d.write(`if (${condition}) return INVALID;`);
@@ -24570,7 +25141,7 @@ function generateLiteralCheck(doc, ctx, schema, accessor) {
     return accessor;
   }
   if (typeof value === "string") {
-    doc.write(`if (${accessor} !== ${esc2(value)}) return INVALID;`);
+    doc.write(`if (${accessor} !== ${esc3(value)}) return INVALID;`);
   } else if (typeof value === "number" || typeof value === "boolean") {
     doc.write(`if (${accessor} !== ${value}) return INVALID;`);
   } else if (value === null) {
@@ -24771,7 +25342,7 @@ function generateDiscriminatedUnionCheck(doc, ctx, def, accessor) {
   }
   const discVar = newVar(ctx);
   const outputVar = newVar(ctx);
-  doc.write(`const ${discVar} = ${accessor}?.[${esc2(def.discriminator)}];`);
+  doc.write(`const ${discVar} = ${accessor}?.[${esc3(def.discriminator)}];`);
   doc.write(`let ${outputVar};`);
   let firstBranch = true;
   const claimed = /* @__PURE__ */ new Set();
@@ -24801,7 +25372,7 @@ function generateDiscriminatedUnionCheck(doc, ctx, def, accessor) {
 }
 function literalEquality(ctx, accessor, value) {
   if (typeof value === "string")
-    return `${accessor} === ${esc2(value)}`;
+    return `${accessor} === ${esc3(value)}`;
   if (typeof value === "number") {
     if (Number.isNaN(value))
       return `Number.isNaN(${accessor})`;
@@ -24933,7 +25504,7 @@ function emitOwnKeys(doc, ctx, accessor, kVar, body, onSymbol) {
 }
 function literalPropertyKey(ctx, key) {
   if (typeof key === "string")
-    return esc2(key);
+    return esc3(key);
   return addConstant(ctx, key);
 }
 function generateMapCheck(doc, ctx, schema, accessor) {
@@ -40084,6 +40655,21 @@ function createBrandrailMcp(ctx) {
       return text(componentDoc(c, fwOf(framework)));
     }
   );
+  server.registerTool(
+    "get_migration_map",
+    {
+      title: "Map another UI library to the design system",
+      description: "What replaces each piece of Angular Material, MUI, Bootstrap, Ant Design, Chakra, React Bootstrap or PrimeNG in this design system, in the project's framework. Call before migrating code that uses one of those libraries; keep behaviour identical and use get_component_docs for props and events.",
+      inputSchema: {
+        libraries: external_exports.array(external_exports.enum(Object.keys(LIBRARY_LABEL))).optional().describe("Only these libraries (default: all)"),
+        framework: frameworkInput
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
+    },
+    async ({ libraries, framework }) => text(`# Migration map (${FRAMEWORK_LABEL[fwOf(framework)]})
+
+${migrationMapMarkdown(resolved, fwOf(framework), libraries)}`)
+  );
   server.registerTool(
     "validate_snippet",
     {
@@ -40129,7 +40715,7 @@ function createBrandrailMcp(ctx) {
 // src/files.ts
 import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync3, statSync } from "node:fs";
 import { dirname as dirname2, join as join3, relative, resolve, sep } from "node:path";
-var CONFIG_FILE = "brandrail.config.json";
+var CONFIG_FILE2 = "brandrail.config.json";
 var MAX_FILE_BYTES = 512 * 1024;
 function collectFiles(root, paths, ignoreGlobs) {
   const ignored = makeIgnore(ignoreGlobs);
@@ -40159,7 +40745,7 @@ function collectFiles(root, paths, ignoreGlobs) {
 function findConfig(start) {
   let dir = resolve(start);
   for (; ; ) {
-    const candidate = join3(dir, CONFIG_FILE);
+    const candidate = join3(dir, CONFIG_FILE2);
     if (existsSync3(candidate)) return candidate;
     const parent = dirname2(dir);
     if (parent === dir) return null;
@@ -40365,6 +40951,8 @@ Usage
                                MCP server for Claude Code / Cursor / Copilot, and the UI kit
   brandrail check [paths...]   Scan files and print violations
   brandrail init               Create brandrail.config.json and AI rule files
+  brandrail migrate [paths...] What's left on the way to the design system: per library and per file
+  brandrail report             Write a shareable HTML handover report (paths and counts, no code)
   brandrail mcp                Run the MCP server on this machine (AI tools start it; code never leaves it)
   brandrail whoami | logout    Show or remove the saved sign-in
   brandrail scan <url>         Check a running page (localhost, staging, behind a login) in a real browser
@@ -40394,6 +40982,14 @@ Options for connect
   --remote               Point AI tools at the hosted MCP server instead of the local one
   --framework, --tokens-css, --no-rules   As for init
 
+Options for migrate
+  --json                 Machine-readable output
+  --top <n>              How many files to list (default 15)
+  --upload               Store the result in the dashboard (scores and counts, never code)
+
+Options for report
+  --out <file>           Where to write it (default brandrail-report.html)
+
 Options for mcp
   --framework <name>     Override the detected framework
   --report               Also send brand scores (never code) to the dashboard
@@ -40425,7 +41021,7 @@ function parseArgs(argv) {
       const [k, v] = a.slice(2).split("=", 2);
       const next = rest[i2 + 1];
       if (v !== void 0) flags[k] = v;
-      else if (next !== void 0 && !next.startsWith("-") && ["config", "format", "fail-below", "changed", "pages", "storage-state", "wait", "width", "tokens-css", "framework"].includes(k)) {
+      else if (next !== void 0 && !next.startsWith("-") && ["config", "format", "fail-below", "changed", "pages", "storage-state", "wait", "width", "tokens-css", "framework", "top", "out"].includes(k)) {
         flags[k] = next;
         i2++;
       } else flags[k] = true;
@@ -40435,21 +41031,29 @@ function parseArgs(argv) {
 }
 var log2 = (s = "") => process.stderr.write(`${s}
 `);
+function readJson(path) {
+  if (!existsSync6(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync5(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
 async function loadConfig(cwd, flags) {
   const explicit = typeof flags.config === "string" ? resolve3(cwd, flags.config) : null;
   const path = explicit ?? findConfig(cwd);
-  if (path) return { config: readConfig(path), source: relative2(cwd, path) || CONFIG_FILE };
+  if (path) return { config: readConfig(path), source: relative2(cwd, path) || CONFIG_FILE2 };
   const key = resolveKey();
   if (key) {
     const { config: config2 } = await fetchBrandKit(key);
     return { config: config2, source: `${apiBase()} (published Brand Kit)` };
   }
-  throw new Error(`No ${CONFIG_FILE} found. Run \`npx brandrail init\` first, or run \`npx brandrail connect\` to use your published Brand Kit.`);
+  throw new Error(`No ${CONFIG_FILE2} found. Run \`npx brandrail init\` first, or run \`npx brandrail connect\` to use your published Brand Kit.`);
 }
 async function cmdCheck(cwd, positional, flags) {
   const { config: config2, source } = await loadConfig(cwd, flags);
   const resolved = resolveConfig(config2);
-  const root = dirname4(typeof flags.config === "string" ? resolve3(cwd, flags.config) : findConfig(cwd) ?? join6(cwd, CONFIG_FILE));
+  const root = dirname4(typeof flags.config === "string" ? resolve3(cwd, flags.config) : findConfig(cwd) ?? join6(cwd, CONFIG_FILE2));
   const files = collectFiles(root, positional.map((p) => relative2(root, resolve3(cwd, p))), resolved.ignore);
   let onlyLines;
   if (flags.changed) {
@@ -40504,46 +41108,29 @@ function tokensCssPath(root, config2, flags) {
 function writeTokensCss(root, rel, config2, org) {
   const abs = join6(root, rel);
   mkdirSync3(dirname4(abs), { recursive: true });
-  let css = generateTokensCss(config2.tokens, { version: config2.tokenVersion, org });
-  const usesKit = (config2.components ?? []).some((c) => c.importPath === "@brandrail/kit");
-  if (usesKit) css += `
-/* @brandrail/kit follows the Brand Kit: colours, font, spacing, radius and type scale. */
-${kitBridgeCss(config2.tokens)}
-`;
+  const { css, usesKit } = tokensCssContent(config2, org);
   writeFileSync3(abs, css);
   return usesKit;
 }
 function writeRuleFiles(root, config2, org, tokensCss) {
   const md = generateInstructions(config2, { org, tokensCss });
   const written = [];
-  const write2 = (rel, content) => {
-    const abs = join6(root, rel);
+  for (const { file: file2, readBy } of RULE_FILES) {
+    const abs = join6(root, file2);
     mkdirSync3(dirname4(abs), { recursive: true });
     const before = existsSync6(abs) ? readFileSync5(abs, "utf8") : "";
-    writeFileSync3(abs, content(before));
-    written.push(rel);
-  };
-  for (const { file: file2, readBy } of RULE_FILES) {
-    if (file2.endsWith(".mdc")) {
-      write2(file2, () => `---
-description: Design system rules from Brandrail
-globs: ["**/*.{tsx,jsx,ts,vue,svelte,html,css,scss,php,twig,hbs,mustache}"]
-alwaysApply: true
----
-
-${md}
-`);
-    } else if (file2.startsWith(".windsurf/")) {
-      write2(file2, () => `---
-trigger: always_on
----
-
-${md}
-`);
-    } else {
-      write2(file2, (before) => upsertSection(before, md));
-    }
-    written[written.length - 1] = `${file2}  (${readBy})`;
+    writeFileSync3(abs, ruleFileContent(file2, md, before));
+    written.push(`${file2}  (${readBy})`);
+  }
+  const pkg = readJson(join6(root, "package.json"));
+  for (const [file2, content, readBy] of [
+    [MIGRATE_SKILL_FILE, migrationSkill(config2, { org, pkg }), "Claude Code skill: migrate to the design system"],
+    [MIGRATE_AGENT_FILE, migrationAgent({ org }), "Claude Code agent: brandrail-migrator"]
+  ]) {
+    const abs = join6(root, file2);
+    mkdirSync3(dirname4(abs), { recursive: true });
+    writeFileSync3(abs, content);
+    written.push(`${file2}  (${readBy})`);
   }
   return written;
 }
@@ -40603,7 +41190,7 @@ function projectFramework(cwd, config2, flags) {
   }
 }
 async function cmdInit(cwd, flags) {
-  const target = join6(cwd, CONFIG_FILE);
+  const target = join6(cwd, CONFIG_FILE2);
   let config2 = starterConfig;
   let org;
   if (flags["from-api"]) {
@@ -40614,17 +41201,17 @@ async function cmdInit(cwd, flags) {
     org = res.org;
   }
   if (existsSync6(target) && !flags.force && !flags["from-api"]) {
-    log2(`${CONFIG_FILE} already exists (use --force to overwrite). Updating rule files from it.`);
+    log2(`${CONFIG_FILE2} already exists (use --force to overwrite). Updating rule files from it.`);
     config2 = readConfig(target);
     org ??= config2.org;
   } else {
     if (existsSync6(target)) {
       const prev = readConfig(target);
-      config2 = { ...prev, ...config2, rules: { ...prev.rules, ...config2.rules }, ignore: prev.ignore ?? config2.ignore, tokensCss: prev.tokensCss };
+      config2 = mergeProjectConfig(prev, config2);
     }
     writeFileSync3(target, `${JSON.stringify(config2, null, 2)}
 `);
-    log2(`\u2714 wrote ${CONFIG_FILE}${org ? ` from ${org}'s Brand Kit` : " (starter tokens \u2014 edit them or use --from-api)"}`);
+    log2(`\u2714 wrote ${CONFIG_FILE2}${org ? ` from ${org}'s Brand Kit` : " (starter tokens \u2014 edit them or use --from-api)"}`);
   }
   const framework = projectFramework(cwd, config2, flags);
   if (config2.framework !== framework) {
@@ -40663,7 +41250,7 @@ async function cmdConnect(cwd, flags) {
 \u2714 connected to ${org}. The key is saved in ${credentialsPath()} (only you can read it), never in this repo.`);
   }
   await cmdInit(cwd, { ...flags, "from-api": true, mcp: false });
-  const config2 = readConfig(join6(cwd, CONFIG_FILE));
+  const config2 = readConfig(join6(cwd, CONFIG_FILE2));
   const framework = projectFramework(cwd, config2, flags);
   writeMcpConfigs(cwd, framework, flags.remote ? "remote" : "local");
   const usesKit = (config2.components ?? []).some((c) => c.importPath === "@brandrail/kit");
@@ -40673,6 +41260,75 @@ Done. Restart your AI tool so it picks up the MCP server, then ask it to build s
   if (framework !== "react" && usesKit) log2(`(${framework}: import "@brandrail/kit/elements" once at your app entry \u2014 the rule files tell the AI the rest.)`);
   return 0;
 }
+async function cmdMigrate(cwd, positional, flags) {
+  const { config: config2, source } = await loadConfig(cwd, flags);
+  const resolved = resolveConfig(config2);
+  const root = dirname4(findConfig(cwd) ?? join6(cwd, CONFIG_FILE2));
+  const files = collectFiles(root, positional.map((p) => relative2(root, resolve3(cwd, p))), resolved.ignore);
+  const s = migrationStatus(files, resolved);
+  if (flags.format === "json" || flags.json) {
+    process.stdout.write(`${JSON.stringify({ progress: s.progress, filesScanned: s.filesScanned, filesClean: s.filesClean, score: s.report.score, libraries: s.libraries, byRule: s.byRule, files: s.files }, null, 2)}
+`);
+  } else {
+    const color = flags.color !== false && process.stdout.isTTY !== false && !process.env.NO_COLOR;
+    const c = (code, t) => color ? `\x1B[${code}m${t}\x1B[0m` : t;
+    const bar = (p) => `${"\u2588".repeat(Math.round(p / 5))}${"\u2591".repeat(20 - Math.round(p / 5))}`;
+    const out = [];
+    out.push(c("2", `Brand Kit: ${source}${config2.tokenVersion ? ` v${config2.tokenVersion}` : ""}`));
+    out.push("");
+    out.push(`${c("1", "Design system migration")}  ${bar(s.progress)} ${s.progress}%  (${s.filesClean} of ${s.filesScanned} UI files done \xB7 brand score ${s.report.score})`);
+    const libs = Object.entries(s.libraries);
+    if (libs.length) out.push("", c("1", "Other UI libraries still in use"), ...libs.map(([id, n]) => `  ${LIBRARY_LABEL[id].padEnd(22)} ${String(n).padStart(5)} usages`));
+    const top = typeof flags.top === "string" ? Number(flags.top) || 15 : 15;
+    if (s.files.length) {
+      out.push("", c("1", `Next files (${Math.min(top, s.files.length)} of ${s.files.length} with work left)`));
+      for (const f of s.files.slice(0, top)) {
+        const what = Object.entries(f.byRule).sort((a, b) => b[1] - a[1]).map(([r, n]) => `${r} ${n}`).join(", ");
+        out.push(`  ${String(f.findings).padStart(4)}  ${f.path}  ${c("2", what)}`);
+      }
+      out.push("", `Migrate a batch with your AI tool, e.g. "migrate ${s.files[0].path} to the design system"${existsSync6(join6(root, MIGRATE_SKILL_FILE)) ? " (Claude Code uses the brandrail-migrate skill)" : " \u2014 run `npx brandrail connect` first to add the migration skill"}.`);
+    } else out.push("", c("32", "\u2714 Every UI file follows the design system."));
+    process.stdout.write(`${out.join("\n")}
+`);
+  }
+  if (flags.upload) {
+    const key = resolveKey();
+    if (!key) log2(`warning: --upload skipped. ${NO_KEY}`);
+    else {
+      const repo = repoInfo(root);
+      const res = await uploadReport(key, {
+        source: process.env.CI ? "ci" : "cli",
+        target: { kind: "repo", name: repo.slug.split("/").pop() ?? repo.slug, location: repo.slug },
+        ref: repo.branch ?? repo.sha?.slice(0, 7),
+        title: `Migration status: ${s.progress}% of UI files done`,
+        report: s.report
+      });
+      log2(`Uploaded \u2192 ${res.url ?? res.scanId}`);
+    }
+  }
+  return 0;
+}
+async function cmdReport(cwd, flags) {
+  const { config: config2 } = await loadConfig(cwd, flags);
+  const resolved = resolveConfig(config2);
+  const root = dirname4(findConfig(cwd) ?? join6(cwd, CONFIG_FILE2));
+  const s = migrationStatus(collectFiles(root, [], resolved.ignore), resolved);
+  const repo = repoInfo(root);
+  const out = resolve3(cwd, typeof flags.out === "string" ? flags.out : "brandrail-report.html");
+  writeFileSync3(
+    out,
+    formatHandoverHtml(s, {
+      project: repo.slug,
+      org: config2.org,
+      branch: repo.branch,
+      commit: repo.sha,
+      kitVersion: config2.tokenVersion,
+      framework: config2.framework ? FRAMEWORK_LABEL[config2.framework] : void 0
+    })
+  );
+  log2(`\u2714 wrote ${relative2(cwd, out)}: ${s.progress}% of UI files on the design system, brand score ${s.report.score}. Open it in a browser, or print it to PDF.`);
+  return 0;
+}
 function cmdWhoami() {
   if (process.env.BRANDRAIL_KEY) {
     log2(`Using BRANDRAIL_KEY from the environment (${process.env.BRANDRAIL_KEY.slice(0, 12)}\u2026) against ${apiBase()}.`);
@@ -40770,7 +41426,7 @@ function cmdImport(cwd, positional, flags) {
   if (!files.length) throw new Error("No .json token files found.");
   const res = importTokenFiles(files, { includePrimitives: !!flags.primitives });
   const file2 = files.length === 1 ? positional[0] : `${files.length} files`;
-  const path = (typeof flags.config === "string" ? resolve3(cwd, flags.config) : findConfig(cwd)) ?? join6(cwd, CONFIG_FILE);
+  const path = (typeof flags.config === "string" ? resolve3(cwd, flags.config) : findConfig(cwd)) ?? join6(cwd, CONFIG_FILE2);
   const config2 = existsSync6(path) ? readConfig(path) : { ...starterConfig, tokens: {} };
   const next = flags.replace ? res.tokens : mergeTokens(config2.tokens, res.tokens);
   const d = diffTokens(config2.tokens, next);
@@ -40779,7 +41435,7 @@ function cmdImport(cwd, positional, flags) {
   log2(`\u2714 ${res.count} tokens from ${file2} (${res.format})${res.primitives ? `, ${res.primitives} palette primitives left out (--primitives to keep)` : ""}`);
   for (const n of res.notes) log2(`  \xB7 ${n}`);
   for (const i2 of auditBrandKit(next)) log2(`  ${i2.severity === "error" ? "\u2716" : "!"} ${i2.message}`);
-  log2(`\u2714 ${relative2(cwd, path) || CONFIG_FILE}: ${d.changed.length} changed, ${d.added.length} added, ${d.removed.length} removed`);
+  log2(`\u2714 ${relative2(cwd, path) || CONFIG_FILE2}: ${d.changed.length} changed, ${d.added.length} added, ${d.removed.length} removed`);
   log2("\nNext: npx brandrail init (to refresh AI rule files), then npx brandrail check");
   return 0;
 }
@@ -40811,6 +41467,10 @@ async function main(argv = process.argv.slice(2)) {
       return cmdConnect(cwd, flags);
     case "mcp":
       return runLocalMcp(cwd, { framework: typeof flags.framework === "string" ? flags.framework : void 0, report: flags.report === true });
+    case "migrate":
+      return cmdMigrate(cwd, positional, flags);
+    case "report":
+      return cmdReport(cwd, flags);
     case "whoami":
       return cmdWhoami();
     case "logout":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brandrail",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Keep AI-generated UI on-brand: checks code and live pages against your design system, and wires your Brand Kit into Claude Code, Cursor, Copilot and Codex.",
   "keywords": [
     "design-system",