roast-my-design-system 5.8.0 → 5.9.0

package/README.md

@@ -8,9 +8,9 @@
 
 A free CLI tool (and Claude Code skill) that roasts your repo's design system with real data, then generates the rules that keep your AI agent on-system.
 
-> **New in 5.7: it reads web components, and it admits what it cannot read.** Stencil, Lit and plain custom elements are detected by their tag registrations (validated on telekom/scale, Shoelace, Ionic, Material Web, Adobe Spectrum, Siemens iX, Baloise and Lion); component libraries get composition maps and library language instead of adoption accusations; an earned token namespace like `--telekom-*` is named in the header. And when a repo's component pattern is beyond the scan, the tiles say "not measured" and the score takes no credit, because zeros the scanner never earned are not discipline.
+> **New in 5.9: the agent card knows which doors your rules actually reach.** The report now states, as plain fact, which tools can read the rules files you have: Claude Code reads CLAUDE.md, Codex reads AGENTS.md, Cursor reads AGENTS.md and `.cursor/rules`. Where a door is missing, the card shows the one-line fix (Claude Code skips AGENTS.md; a CLAUDE.md containing the single line `@AGENTS.md` closes the gap). The scan also finds rules files nested in subfolders now, which is how monorepos really do it (twenty carries 35 AGENTS.md files; a root-only look reported 1), and it recognises GEMINI.md, `.windsurf/rules` and `.github/instructions`.
 
-> **New in 5.6: every fix comes with its prompt.** Each move in the report's Where to start now carries a copy button holding a ready-made fix prompt: the finding, the file paths, the expected score payoff, and the calm rules for fixing without steamrolling craft. Paste it into your agent, fix, re-run the scan, press the next button. View it first if you like: the prompt unfolds right in the report.
+> **New in 5.8: every finding can explain itself.** A "why this matters" toggle under each finding unfolds the calm story behind the brutal number: how the mess arrives innocently, what it costs later, how an agent multiplies it, and why the ideal sits where it sits, benchmark medians included. Written to a plain-language standard, reviewed word by word.
 
 > **New in 5.0: it runs as a local MCP server.** One command, and your agent asks the design system before writing UI, then gets the work checked after: which Button is canonical, which token holds that colour, review my changes. Local, deterministic, nothing leaves your machine. See [Live answers over MCP](#live-answers-over-mcp).
 
@@ -21,7 +21,7 @@ Run it on your codebase and get, in about a second:
 - **Reads React and web components alike.** Stencil, Lit and custom elements detected by tag registration, counted by kebab tag; libraries get composition maps, not adoption accusations; earned token namespaces named in the header; and anything the scan cannot read is declared "not measured" instead of scored.
 - **The receipts behind it.** Every colour and its near-identical twin, every spacing value, typeface, duplicated or never-imported component, inline style and !important, with real file paths, in one self-contained HTML report you can open, Slack or email.
 - **The first fixes ranked by payoff, each with its prompt.** A "Where to start" list derived from your own numbers, and every move carries a copy button with a ready-made fix prompt for your agent: the finding, the files, the expected payoff, and rules that respect deliberate craft. Fix, re-run the scan, press the next button.
-- **Rules that stop the mess coming back.** A generated `design-system-rules.md` with canonical components, your token file, and known duplicates to avoid, so your AI agent follows your system instead of guessing at it. `--apply` injects them into every agent file you have: Claude, Cursor, GitHub Copilot, and Windsurf. Every scan also checks the rules you already have for stale references: paths that no longer exist, components named canonical that nothing imports anymore.
+- **Rules that stop the mess coming back.** A generated `design-system-rules.md` with canonical components, your token file, and known duplicates to avoid, so your AI agent follows your system instead of guessing at it. `--apply` injects them into every agent file you have: Claude, Cursor, GitHub Copilot, and Windsurf. Every scan also checks the rules you already have for stale references: paths that no longer exist, components named canonical that nothing imports anymore. And the agent card states which tools can actually read the rules you have (Claude Code, Codex, Cursor), with the one-line fix where a door is missing.
 
 ## Why this exists
 
@@ -60,11 +60,11 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 
 The full report for vercel/ai-chatbot, top to bottom — including "What the numbers mean", Claude's read of the scan, embedded right under the verdict:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, three-yardstick tiles, the adoption map treemap, palette forensics, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=5.8.0)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, three-yardstick tiles, the adoption map treemap, palette forensics, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=5.9.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=5.8.0)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=5.9.0)
 
 ## What makes the numbers trustworthy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 34 public repos, reads React and web components (Stencil, Lit), hands you a copy-paste fix prompt for each top finding, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
   "keywords": [

package/skills/roast-my-design-system/scripts/diagnose/index.mjs

@@ -1168,10 +1168,29 @@ function packagesSection() {
 }
 
 function agentSection() {
-  const have = agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)} · ${esc(c.tool ?? c.kind)}</span>`).join('');
+  // Root files get chips; nested ones (monorepo packages) fold into a single
+  // count chip, because 35 chips is wallpaper and one number is a finding.
+  const rootAgent = agentFiles.filter((c) => !c.nested);
+  const nestedAgent = agentFiles.filter((c) => c.nested);
+  const overflow = nestedAgent.find((c) => c.file.startsWith('(+'));
+  const nestedCount = nestedAgent.filter((c) => !c.file.startsWith('(+')).length
+    + (overflow ? parseInt(overflow.file.slice(2), 10) || 0 : 0);
+  const have = rootAgent.map((c) => `<span class="chip chip-agent">${esc(c.file)} · ${esc(c.tool ?? c.kind)}</span>`).join('')
+    + (nestedCount ? `<span class="chip chip-agent">+${nestedCount} nested in subfolders</span>` : '');
+  const readsList = (rootAgent.length ? rootAgent : nestedAgent.slice(0, 3)).map((c) => `<span class="mono">${esc(c.file)}</span>`).join(', ');
   const msg = agentFiles.length
-    ? `<p class="sub">Your agent reads ${agentFiles.map((c) => `<span class="mono">${esc(c.file)}</span>`).join(', ')}. But none of it points at a single source of truth for components and tokens, because there isn't one yet. The numbers below are what your agent actually works from.</p>`
+    ? `<p class="sub">Your agent reads ${readsList}${nestedCount && rootAgent.length ? `, plus ${nestedCount} rules file${nestedCount === 1 ? '' : 's'} nested in subfolders` : ''}. But none of it points at a single source of truth for components and tokens, because there isn't one yet. The numbers below are what your agent actually works from.</p>`
     : `<p class="sub">No <span class="mono">CLAUDE.md</span>, no <span class="mono">AGENTS.md</span>, no <span class="mono">.cursorrules</span>. Every time your AI builds UI here, it guesses, from everything below. This is why its output looks almost-but-not-quite right.</p>`;
+  // Door coverage, stated as fact: which tools can read what exists. Claude
+  // Code reads CLAUDE.md only; Codex reads AGENTS.md; Cursor reads AGENTS.md
+  // and .cursor/rules (its legacy .cursorrules is labelled, not judged).
+  const hasFile = (name) => agentFiles.some((c) => c.file === name || c.file.endsWith(`/${name}`));
+  const claudeOk = hasFile('CLAUDE.md');
+  const agentsOk = hasFile('AGENTS.md');
+  const cursorOk = agentsOk || agentFiles.some((c) => c.file.endsWith('.cursor/rules') || c.file === '.cursor/rules');
+  const cursorLegacyOnly = !cursorOk && hasFile('.cursorrules');
+  const mark = (ok) => (ok ? '<b class="cov-yes">✓</b>' : '<b class="cov-no">—</b>');
+  const coverage = agentFiles.length ? `<p class="sub coverage">Readable by: Claude Code ${mark(claudeOk)} · Codex ${mark(agentsOk)} · Cursor ${cursorLegacyOnly ? '<b class="cov-no">legacy file only</b>' : mark(cursorOk)}${claudeOk && !agentsOk ? ' · <span class="dim">copy the same rules into an AGENTS.md and the other tools see them too</span>' : ''}${agentsOk && !claudeOk ? ' · <span class="dim">Claude Code skips AGENTS.md: add a CLAUDE.md containing the single line <span class="mono">@AGENTS.md</span> and it reads the same rules</span>' : ''}</p>` : '';
   const stale = h.staleRules ?? [];
   const staleRows = stale.map((s) => `
     <div class="ledger-row">
@@ -1186,7 +1205,7 @@ function agentSection() {
     </div>` : '';
   return `<section class="glass pad agent">
     ${sectionHead('What your AI agent sees today', '')}
-    ${msg}${have ? `<div class="chips">${have}</div>` : ''}${staleBlock}</section>`;
+    ${msg}${have ? `<div class="chips">${have}</div>` : ''}${coverage}${staleBlock}</section>`;
 }
 
 // ---------- page ----------
@@ -1294,6 +1313,9 @@ const html = `<!doctype html>
   .chip { border:1px solid var(--line); background:var(--card); border-radius:99px;
     padding:4px 12px; font:500 11.5px/1.5 var(--sans); color:var(--text); }
   .chip-agent { background:var(--text); color:var(--bg); border-color:var(--text); font-weight:600; }
+  .coverage { margin-top:12px; }
+  .cov-yes { color:var(--ok); font-weight:700; }
+  .cov-no { color:var(--coral); font-weight:700; }
   .excl { margin-top:10px; font:500 12px/1.6 var(--sans); color:var(--dim); }
   .excl .mono { font-size:11.5px; color:var(--text); }
   .stale { margin-top:18px; }
@@ -1537,6 +1559,11 @@ const html = `<!doctype html>
     .foot-sub .pulse polyline { animation:none; stroke-dashoffset:0; }
   }
   .scan-id { font-family:var(--mono); font-size:11px; letter-spacing:.04em; }
+  .copy-pill { font:700 9.5px/1 var(--sans); letter-spacing:.06em; text-transform:uppercase; padding:3px 8px;
+    border-radius:99px; border:1px solid var(--line); background:transparent; color:var(--dim);
+    cursor:pointer; vertical-align:1px; }
+  .copy-pill:hover { color:var(--accent); border-color:var(--accent); }
+  @media print { .copy-pill { display:none; } }
   footer .brand { color:var(--accent); font-weight:700; text-decoration:none; }
   footer .brand:hover { text-decoration:underline; }
   footer .creds { display:flex; gap:16px; font:700 9.5px/1.6 var(--sans); letter-spacing:.16em; text-transform:uppercase; color:var(--dim2); }
@@ -1646,6 +1673,8 @@ ${extraSectionsHtml()}
 
 ${whereToStartSection()}
 
+${agentSection()}
+
 ${giftSection()}
 
 ${trapsBlock()}
@@ -1654,8 +1683,6 @@ ${trapsBlock()}
 
 ${packagesSection()}
 
-${agentSection()}
-
 <section style="margin-top:16px">${paletteSection()}</section>
 
 ${spacingBars()}
@@ -1669,7 +1696,7 @@ ${componentsSection()}
 
 <footer>
   <div class="foot-left">
-    <div>Generated by <a class="brand" href="https://github.com/gregkozakiewicz/roast-my-design-system">roast-my-design-system</a> <span class="ver">ver. ${VERSION}</span>, free on npm and as a Claude Code + Codex skill</div>
+    <div>Generated by <a class="brand" href="https://github.com/gregkozakiewicz/roast-my-design-system">roast-my-design-system</a> <span class="ver">ver. ${VERSION}</span> · free to run: <a class="brand" href="https://www.npmjs.com/package/roast-my-design-system"><span class="mono" id="npx-cmd">npx roast-my-design-system</span></a> <button type="button" class="copy-pill" id="npx-copy">copy</button> · also a Claude Code + Codex skill and a local MCP server</div>
     <div class="foot-sub">Designed and built by <a class="author" href="https://gregkozakiewicz.com/?utm_source=roast-report"><span class="gk-mark"></span>Greg Kozakiewicz</a> · <span class="scan-id" title="scan id">${scanId}</span> · ${FEEDBACK_ASK} <a class="feedback" href="${feedbackUrl(VERSION).replace(/&/g, '&amp;')}">${PULSE_ICON}${FEEDBACK_CTA}</a></div>
   </div>
   <span class="creds"><span>Non-destructive scan</span><span>Read-only</span><span>Paths are real</span></span>
@@ -1728,6 +1755,17 @@ ${componentsSection()}
       v.textContent=show?'hide it':'view it first';
     });
   });
+  var npxCopy=document.getElementById('npx-copy');
+  if(npxCopy){
+    npxCopy.addEventListener('click', function(){
+      var text=document.getElementById('npx-cmd').textContent;
+      var done=function(){ npxCopy.textContent='copied'; setTimeout(function(){ npxCopy.textContent='copy'; },1600); };
+      var manual=function(){ var r=document.createRange(); r.selectNodeContents(document.getElementById('npx-cmd'));
+        var s=getSelection(); s.removeAllRanges(); s.addRange(r); npxCopy.textContent='select + copy'; setTimeout(function(){ npxCopy.textContent='copy'; },2600); };
+      if(navigator.clipboard && navigator.clipboard.writeText){ navigator.clipboard.writeText(text).then(done, manual); }
+      else { manual(); }
+    });
+  }
   document.querySelectorAll('.whybtn').forEach(function(b){
     b.addEventListener('click', function(){
       var holder=document.getElementById('why-'+b.getAttribute('data-why'));

package/skills/roast-my-design-system/scripts/harvest/context.mjs

@@ -2,17 +2,26 @@
  * Context-file harvest — the agent-facing and design-facing docs the repo
  * already has. Step 5 (wire up their agent) needs to know what exists so it
  * extends rather than clobbers; the diagnosis mentions what's missing.
+ *
+ * Two passes: the root checklist below (known doors at known paths), then a
+ * nested sweep for rules files living inside subfolders, because that is how
+ * monorepos actually do it (twenty carries 35 AGENTS.md files; a root-only
+ * look reported 1 and called it the whole story). Nested entries carry
+ * nested:true so the report can summarise them instead of flooding chips.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
 const CONTEXT_FILES = [
   { file: 'CLAUDE.md',        kind: 'agent-rules', tool: 'Claude Code' },
   { file: 'AGENTS.md',        kind: 'agent-rules', tool: 'generic (AGENTS.md standard)' },
+  { file: 'GEMINI.md',        kind: 'agent-rules', tool: 'Gemini CLI' },
   { file: '.cursorrules',     kind: 'agent-rules', tool: 'Cursor (legacy format)' },
   { file: '.cursor/rules',    kind: 'agent-rules', tool: 'Cursor', dir: true },
   { file: '.github/copilot-instructions.md', kind: 'agent-rules', tool: 'GitHub Copilot' },
-  { file: '.windsurfrules',   kind: 'agent-rules', tool: 'Windsurf' },
+  { file: '.github/instructions', kind: 'agent-rules', tool: 'GitHub Copilot (scoped)', dir: true },
+  { file: '.windsurfrules',   kind: 'agent-rules', tool: 'Windsurf (legacy format)' },
+  { file: '.windsurf/rules',  kind: 'agent-rules', tool: 'Windsurf', dir: true },
   { file: 'components.json',  kind: 'design-config', tool: 'shadcn/ui' },
   { file: 'tailwind.config.js',  kind: 'design-config', tool: 'Tailwind' },
   { file: 'tailwind.config.ts',  kind: 'design-config', tool: 'Tailwind' },
@@ -21,6 +30,63 @@ const CONTEXT_FILES = [
   { file: 'STYLEGUIDE.md',    kind: 'design-doc' },
 ];
 
+// Nested sweep targets: the doors that tools officially read from
+// subdirectories (closer file wins, per the AGENTS.md standard and Cursor's
+// docs). Only these — a nested tailwind.config is build detail, not a door.
+const NESTED_FILES = {
+  'CLAUDE.md': 'Claude Code',
+  'AGENTS.md': 'generic (AGENTS.md standard)',
+  'GEMINI.md': 'Gemini CLI',
+};
+const NESTED_DIRS = {
+  '.cursor': { child: 'rules', tool: 'Cursor' },
+  '.windsurf': { child: 'rules', tool: 'Windsurf' },
+};
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.next', '.git', 'dist', 'build', 'out', 'coverage',
+  '.turbo', '.cache', 'vendor', 'tmp',
+]);
+const MAX_DEPTH = 6;
+const MAX_NESTED = 60; // entries recorded; the true count keeps counting
+
+function sweepNested(root) {
+  const found = [];
+  let total = 0;
+  const walk = (dir, rel, depth) => {
+    if (depth > MAX_DEPTH) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const relPath = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        const nd = NESTED_DIRS[e.name];
+        if (nd) {
+          // rel is empty at the root, where the checklist above already owns
+          // these paths; the sweep only reports the nested ones.
+          if (rel && existsSync(join(dir, e.name, nd.child))) {
+            total++;
+            if (found.length < MAX_NESTED) found.push({ file: `${relPath}/${nd.child}`, kind: 'agent-rules', tool: nd.tool, nested: true, size: null, mentionsDesign: null });
+          }
+          continue; // never descend into tool dot-dirs
+        }
+        if (e.name.startsWith('.')) continue;
+        walk(join(dir, e.name), relPath, depth + 1);
+      } else if (depth > 0 && NESTED_FILES[e.name]) {
+        total++;
+        if (found.length < MAX_NESTED) {
+          let size = 0;
+          try { size = statSync(join(dir, e.name)).size; } catch { /* unreadable */ }
+          found.push({ file: relPath, kind: 'agent-rules', tool: NESTED_FILES[e.name], nested: true, size, mentionsDesign: null });
+        }
+      }
+    }
+  };
+  walk(root, '', 0);
+  return { found, total };
+}
+
 export function harvestContext(root) {
   const found = [];
   for (const c of CONTEXT_FILES) {
@@ -38,5 +104,10 @@ export function harvestContext(root) {
     } catch { /* unreadable */ }
     found.push({ file: c.file, kind: c.kind, tool: c.tool ?? null, size, mentionsDesign });
   }
+  const nested = sweepNested(root);
+  found.push(...nested.found);
+  if (nested.total > nested.found.length) {
+    found.push({ file: `(+${nested.total - nested.found.length} more nested rules files)`, kind: 'agent-rules', tool: null, nested: true, size: null, mentionsDesign: null });
+  }
   return found;
 }

package/skills/roast-my-design-system/scripts/lib/version.mjs

@@ -1,4 +1,4 @@
 // Single version constant for the engine — imported by diagnose (report
 // footer) and rules (generated-by line). This is the bump spot that used to
 // live as a const inside diagnose/index.mjs.
-export const VERSION = '5.8.0';
+export const VERSION = '5.9.0';

package/skills/roast-my-design-system/scripts/rules/build.mjs

@@ -30,7 +30,9 @@ const repoName = h.profile?.name ?? 'this repo';
   if (!compact) {
     lines.push(`<!-- Generated by roast-my-design-system from a scan of ${repoName} on ${scanDate}.`);
     lines.push('     Paste into CLAUDE.md, .cursor/rules or AGENTS.md. Regenerate after big refactors:');
-    lines.push('     npx roast-my-design-system@latest --rules -->');
+    lines.push('     npx roast-my-design-system@latest --rules');
+    lines.push('     Door note: Codex and Cursor read AGENTS.md; Claude Code reads CLAUDE.md only.');
+    lines.push('     If this lives in AGENTS.md, add the line "@AGENTS.md" to CLAUDE.md so Claude sees it too. -->');
     lines.push('');
   }
   // Mirror of the report's "no design system" banner: with almost no colour or