roast-my-design-system 5.7.2 → 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,17 +60,17 @@ 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.7.2)
+![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.2.3)
+![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
 
 - **Deterministic scanner, not AI sampling.** A zero-dependency Node script reads *every* file (about a second on a normal repo, a few on a large monorepo) and returns the same numbers every run. Claude narrates; it never counts.
 - **Read-only.** Nothing in your repo is modified. The only outputs are a temp JSON and the HTML report.
-- **No network, no telemetry.** Everything runs locally. Nothing about your code leaves your machine.
+- **No network, no telemetry.** Everything runs locally. Nothing about your code leaves your machine. Dependency scanners such as Socket may flag URL strings in this package; they are product links and format identifiers written into generated reports, never fetched.
 - **Zero dependencies, enforced by the test suite.** The package installs nothing but itself, and that is a tested promise rather than a habit: the suite fails if package.json ever declares a dependency, and the exact file list npm ships is a photographed contract, so nothing can stow away in a release.
 - **Honest gaps.** When a repo's components register in a pattern the scan cannot read, the component tiles say "not measured" and drop out of the score. A zero the scanner never earned is presented as blindness, not discipline.
 - **Honest exclusions.** Test files, Storybook stories, docs sites, example apps, SVG artwork, and email templates (which *must* inline styles) are excluded, so you can't discredit the numbers on a technicality. Your own exclusions (`.roastignore`, `--exclude`) are printed in the report header with file counts, so a scoped scan can never pass itself off as the whole repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "5.7.2",
+  "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

@@ -29,6 +29,7 @@ import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { VERSION } from '../lib/version.mjs';
 import { feedbackUrl, FEEDBACK_ASK, FEEDBACK_CTA } from '../lib/feedback.mjs';
 import { fixPrompt } from '../lib/fixprompt.mjs';
+import { WHY } from './why.mjs';
 
 // The benchmark (Ideal-2026 norms + scanned-repo stats) ships next to the
 // code so the page works offline; degrade gracefully when absent.
@@ -343,18 +344,22 @@ function healthOf(metric, value) {
   if (value <= warnCap) return 'warn';
   return 'bad';
 }
+// Our own marks, drawn by hand for this report: a tick that starts at the
+// left foot, a full-bleed cross, a round exclamation, a quiet dash. Generic
+// glyphs on purpose, and our own coordinates on purpose: nothing here is
+// copied from any icon set.
 const ICONS = {
-  good: '<svg class="ic ic-good" viewBox="0 0 24 24"><polyline points="20 6 9 17 4 12"/></svg>',
-  warn: '<svg class="ic ic-warn" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12" y2="16.01"/></svg>',
-  bad: '<svg class="ic ic-bad" viewBox="0 0 24 24"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>',
+  good: '<svg class="ic ic-good" viewBox="0 0 24 24"><polyline points="4.5 12.5 9.5 17.5 19.5 6.5"/></svg>',
+  warn: '<svg class="ic ic-warn" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9.5"/><line x1="12" y1="7.5" x2="12" y2="13"/><line x1="12" y1="16.5" x2="12" y2="16.51"/></svg>',
+  bad: '<svg class="ic ic-bad" viewBox="0 0 24 24"><line x1="18.5" y1="5.5" x2="5.5" y2="18.5"/><line x1="5.5" y1="5.5" x2="18.5" y2="18.5"/></svg>',
   info: '',
-  na: '<svg class="ic ic-na" viewBox="0 0 24 24"><line x1="7" y1="12" x2="17" y2="12"/></svg>',
+  na: '<svg class="ic ic-na" viewBox="0 0 24 24"><line x1="6.5" y1="12" x2="17.5" y2="12"/></svg>',
 };
 
-// Feather "activity", the pulse line, points reversed so it traces left to
-// right. Sits before the footer's feedback link
-// and inherits its colour through currentColor, so it follows the theme.
-const PULSE_ICON = '<svg class="pulse" viewBox="0 0 24 24" aria-hidden="true"><polyline points="2 12 6 12 9 3 15 21 18 12 22 12"/></svg>';
+// The heartbeat line, drawn by hand: flat, one beat, flat. It traces left to
+// right, sits before the footer's feedback link and inherits its colour
+// through currentColor, so it follows the theme.
+const PULSE_ICON = '<svg class="pulse" viewBox="0 0 24 24" aria-hidden="true"><polyline points="2 12.5 6.5 12.5 9.5 4 15 20.5 18 12.5 22 12.5"/></svg>';
 
 // Comparison rows inside a tile: your number vs each yardstick.
 // ▼ mint = you sit at or under the reference, ▲ coral = you're over it.
@@ -468,6 +473,12 @@ const statTile = (s) => `<div class="stat glass st-${s.health}">
 const eyebrow = (text) => `<div class="eyebrow">${text}</div>`;
 const sectionHead = (title, subtitle) => `<div class="sec-head"><h2>${title}</h2>${subtitle ? `<p class="sub">${subtitle}</p>` : ''}</div>`;
 
+// "Why this matters": the calm explanation folded under a brutal finding,
+// same unfold mechanics as the fix-prompt viewer. One per finding, rendered
+// only where that finding's evidence block rendered.
+const WHY_ICON = '<svg class="why-ic" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="9.5"/><path d="M9.3 9.1a2.8 2.8 0 1 1 4 3.1c-.9.5-1.3 1.1-1.3 2.1"/><line x1="12" y1="17.2" x2="12" y2="17.21"/></svg>';
+const whyToggle = (key) => (WHY[key] ? `<div class="whywrap"><button type="button" class="whybtn" data-why="${key}">${WHY_ICON}<span class="why-lab">why this matters</span></button><div class="whytext" hidden id="why-${key}">${WHY[key].map((p) => `<p>${p}</p>`).join('')}</div></div>` : '');
+
 function paletteSection() {
   if (!colors.length) return '';
   const tokens = colors.filter((c) => c.isToken).length;
@@ -491,7 +502,8 @@ function paletteSection() {
   const ramp = greys.length >= 4 ? `
     <div class="ramp-head">${eyebrow('Grey ramp · sorted dark → light · how many can you tell apart?')}</div>
     <div class="only-dark">${rampFor(greys)}</div>
-    <div class="only-light">${rampFor(greysLight)}</div>` : '';
+    <div class="only-light">${rampFor(greysLight)}</div>
+    ${whyToggle('greys')}` : '';
 
   return `<section class="palette-grid">
   <div class="glass pal-hero grad">
@@ -502,6 +514,7 @@ function paletteSection() {
     <div class="split-track"><div class="split"><span class="sp-tok" style="width:${tokenPct}%"></span><span class="sp-stray" style="width:${100 - tokenPct}%"></span></div></div>
     <div class="split-legend"><span>${n(tokens)} tokens</span><span>${n(strays)} strays</span></div>
     ${tokens ? '' : `<p class="sub warn-text">None of these are defined as CSS variables. Every single one is a hardcoded value.</p>`}
+    ${whyToggle('colors')}
   </div>
   <div class="glass pal-usage">
     <div class="pal-usage-head">
@@ -512,7 +525,8 @@ function paletteSection() {
     ${ramp}
     ${nearPairs.length ? `
     <div class="receipts">${eyebrow(`${nearPairs.length} nearly identical pair${nearPairs.length === 1 ? '' : 's'} · copy-paste, not decisions`)}
-    <div class="chips-row">${nearPairs.slice(0, 8).map((pr) => `<span class="vchip" title="every channel within ${pr.d} of its twin"><i class="ndot" style="background:${esc(pr.a.value)}"></i>${esc(pr.a.value)} ×${pr.a.count} <b class="nsim">≈</b> <i class="ndot" style="background:${esc(pr.b.value)}"></i>${esc(pr.b.value)} ×${pr.b.count}</span>`).join('')}${nearPairs.length > 8 ? `<span class="vchip dim">+${nearPairs.length - 8} more</span>` : ''}</div></div>` : ''}
+    <div class="chips-row">${nearPairs.slice(0, 8).map((pr) => `<span class="vchip" title="every channel within ${pr.d} of its twin"><i class="ndot" style="background:${esc(pr.a.value)}"></i>${esc(pr.a.value)} ×${pr.a.count} <b class="nsim">≈</b> <i class="ndot" style="background:${esc(pr.b.value)}"></i>${esc(pr.b.value)} ×${pr.b.count}</span>`).join('')}${nearPairs.length > 8 ? `<span class="vchip dim">+${nearPairs.length - 8} more</span>` : ''}</div>
+    ${whyToggle('nearPairs')}</div>` : ''}
   </div>
 </section>`;
 }
@@ -580,10 +594,12 @@ function spacingBars() {
     <span class="bar-count">${n(s.count)}</span></div>`).join('');
   const arb = arbitraryCount ? `
     <div class="receipts">${eyebrow(`${n(arbitraryCount)} arbitrary values punched through the scale, one bracket at a time`)}
-    <div class="chips-row">${arbitrary.slice(0, 10).map((a) => `<span class="vchip bad" title="${esc(a.files?.[0]?.file ?? '')}">${esc(a.value)} ×${a.count}</span>`).join('')}${arbitrary.length > 10 ? `<span class="vchip dim">+${arbitrary.length - 10} more</span>` : ''}</div></div>` : '';
+    <div class="chips-row">${arbitrary.slice(0, 10).map((a) => `<span class="vchip bad" title="${esc(a.files?.[0]?.file ?? '')}">${esc(a.value)} ×${a.count}</span>`).join('')}${arbitrary.length > 10 ? `<span class="vchip dim">+${arbitrary.length - 10} more</span>` : ''}</div>
+    ${whyToggle('arbitrary')}</div>` : '';
   return `<section class="glass pad">
     ${sectionHead(`${n(spacingTotal)} off-scale spacing values`, `a disciplined repo keeps these around a dozen · on-scale Tailwind steps (·) shown for context · off-scale in coral`)}
-    <div class="bars">${rows}</div>${arb}</section>`;
+    <div class="bars">${rows}</div>
+    ${whyToggle('spacing')}${arb}</section>`;
 }
 
 function duplicatesSection() {
@@ -612,7 +628,8 @@ function duplicatesSection() {
     </div>`).join('');
   return `<div class="glass pad half">
     ${sectionHead('Duplicated components', 'an agent asking which one is canonical gets several plausible answers. Paths open in VS Code')}
-    <div class="fams">${iconCard}${dupeCards}${famCards}</div></div>`;
+    <div class="fams">${iconCard}${dupeCards}${famCards}</div>
+    ${whyToggle('duplicates')}</div>`;
 }
 
 // Scanned values get injected into style attributes below (a radius, a shadow,
@@ -695,6 +712,7 @@ function typographySection() {
   return `<section>
     ${sectionHead('Typography &amp; shape', '')}
     <div class="stats minis">${mini.map((s) => statTile(s)).join('')}</div>
+    ${typefaces.length ? whyToggle('typefaces') : ''}
     ${typeSpecimens || receipts('the font sizes, by use', sizeChips)}
     ${radiiSpecimens || receipts('the radii, by use', radiiChips)}
     ${shadowSpecimens}
@@ -723,7 +741,8 @@ function inlineSection() {
   const max = Math.max(...inline.files.slice(0, 6).map((f) => f.count), 1);
   const importantRow = important.count ? `
     <div class="receipts">${eyebrow(`${n(important.count)} !important declaration${important.count === 1 ? '' : 's'} · the cascade admitting defeat`)}
-    <div class="chips-row">${important.files.map((f) => `<span class="vchip bad" title="${esc(f.file)}">${esc(basename(f.file))} ×${f.count}</span>`).join('')}</div></div>` : '';
+    <div class="chips-row">${important.files.map((f) => `<span class="vchip bad" title="${esc(f.file)}">${esc(basename(f.file))} ×${f.count}</span>`).join('')}</div>
+    ${whyToggle('important')}</div>` : '';
   const blocks = inline.count >= 5 ? `<div class="fam-rows">${inline.files.slice(0, 6).map((f) => `
       <div class="mini-card col">
         <div class="mc-row">${fileLink(f.file)}<span class="mc-count">×${f.count}</span></div>
@@ -731,7 +750,7 @@ function inlineSection() {
       </div>`).join('')}</div>` : '';
   return `<div class="glass pad half">
     ${sectionHead(inline.count >= 5 ? `${n(inline.count)} inline style blocks` : `${n(important.count)} !important declarations`, 'styling no system can see')}
-    ${blocks}${importantRow}</div>`;
+    ${blocks}${inline.count >= 5 ? whyToggle('inline') : ''}${importantRow}</div>`;
 }
 
 // The adoption map: the real system drawn to scale as a treemap. Every
@@ -842,7 +861,8 @@ function componentsSection() {
     ${neverImported.length >= 2 ? `
     <div class="receipts">${eyebrow(isLibrary ? `${n(neverImported.length)} components unused internally · showroom stock to review, not dead weight: consumers in other repos are invisible from here` : `${n(neverImported.length)} components defined but never imported · they sit in the system as wrong answers waiting to be picked`)}
     ${orphanRows()}
-    <p class="sub" style="margin-top:8px">Routers, dynamic imports and barrel files can hide real usage, so treat this as a shortlist to check, not a demolition order.</p>` : ''}</section>`;
+    <p class="sub" style="margin-top:8px">Routers, dynamic imports and barrel files can hide real usage, so treat this as a shortlist to check, not a demolition order.</p>
+    ${isLibrary ? '' : whyToggle('neverImported')}` : ''}</section>`;
 }
 
 // "Where to start" — at most three moves, every one derived from this repo's
@@ -1148,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">
@@ -1166,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 ----------
@@ -1274,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; }
@@ -1336,14 +1378,28 @@ const html = `<!doctype html>
   .only-light { display:none; }
   html[data-theme="light"] .only-light { display:block; }
   html[data-theme="light"] .only-dark { display:none; }
-  /* theme toggle */
-  .theme-toggle { position:fixed; top:18px; right:18px; z-index:10; width:40px; height:40px; border-radius:99px;
-    display:grid; place-items:center; cursor:pointer; color:var(--dim); }
+  /* theme toggle: a slide switch. The knob is a lightly rounded square that
+     carries the current mode's icon (moon in dark, sun in light) and slides
+     to the other side on click. The icons themselves never animate. */
+  .theme-toggle { position:fixed; top:18px; right:18px; z-index:10; width:88px; height:32px; border-radius:10px;
+    cursor:pointer; color:var(--dim); padding:0; }
   .theme-toggle:hover { color:var(--text); }
-  .theme-toggle svg { width:18px; height:18px; fill:none; stroke:currentColor; stroke-width:2; stroke-linecap:round; stroke-linejoin:round; }
-  .theme-toggle .only-light, html[data-theme="light"] .theme-toggle .only-light { display:none; }
-  html[data-theme="light"] .theme-toggle .only-light { display:block; }
-  .theme-toggle .only-dark { display:block; }
+  .tt-lab { position:absolute; top:0; bottom:0; display:flex; align-items:center; font:700 9px var(--sans);
+    letter-spacing:.14em; text-transform:uppercase; transition:opacity .3s ease; }
+  .tt-day { left:13px; opacity:0; }
+  .tt-night { right:13px; opacity:1; }
+  html[data-theme="light"] .tt-day { opacity:1; }
+  html[data-theme="light"] .tt-night { opacity:0; }
+  .tt-knob { position:absolute; top:calc(50% - 13px); left:3px; width:26px; height:26px; border-radius:8px;
+    background:var(--card-solid); box-shadow:0 1px 4px rgba(0,0,0,.3), 0 0 0 1px var(--line-soft);
+    display:grid; place-items:center; transition:left .3s ease; }
+  html[data-theme="light"] .theme-toggle .tt-knob { left:59px; }
+  .tt-knob svg { grid-area:1/1; width:15px; height:15px; fill:none; stroke:currentColor; stroke-width:2;
+    stroke-linecap:round; stroke-linejoin:round; transition:opacity .3s ease; }
+  .tt-moon { opacity:1; } .tt-sun { opacity:0; }
+  html[data-theme="light"] .tt-moon { opacity:0; }
+  html[data-theme="light"] .tt-sun { opacity:1; }
+  @media (prefers-reduced-motion: reduce) { .tt-knob, .tt-knob svg, .tt-lab { transition:none; } }
 
   /* palette */
   .palette-grid { display:grid; grid-template-columns:1fr 1.6fr; gap:16px; }
@@ -1413,6 +1469,23 @@ const html = `<!doctype html>
     user-select:all; -webkit-user-select:all; }
   @media print { .start-actions { display:none; } }
 
+  .whywrap { margin-top:12px; }
+  .whybtn { font:500 11.5px/1 var(--sans); color:var(--dim); background:none; border:none; padding:0; cursor:pointer;
+    display:inline-flex; align-items:center; gap:5px; }
+  .whybtn .why-lab { text-decoration:underline; text-underline-offset:3px; }
+  .why-ic { width:15.5px; height:15.5px; fill:none; stroke:currentColor; stroke-width:2; stroke-linecap:round; stroke-linejoin:round; }
+  .whybtn:hover { color:var(--accent); }
+  /* On the light-mode gradient hero the dim grey is unreadable: follow the
+     card's own white text treatment instead. */
+  html[data-theme="light"] .grad .whybtn { color:rgba(255,255,255,.82); }
+  html[data-theme="light"] .grad .whybtn:hover { color:#fff; }
+  html[data-theme="light"] .grad .whytext.shown { border-color:rgba(255,255,255,.35); }
+  html[data-theme="light"] .grad .whytext p { color:rgba(255,255,255,.88); }
+  .whytext.shown { display:block; border:1px solid var(--line); border-radius:10px; padding:12px 14px; margin-top:8px; }
+  .whytext p { font:13px/1.7 var(--sans); color:var(--dim); margin:0 0 10px; }
+  .whytext p:last-child { margin-bottom:0; }
+  @media print { .whybtn { display:none; } .whytext.shown { border:none; padding:0; } }
+
   .pill { border-radius:99px; padding:3px 10px; font:500 10.5px/1.5 var(--sans); white-space:nowrap; }
   .pill-mint { background:var(--ok-soft); color:var(--ok); }
   .pill-coral { background:var(--coral-soft); color:var(--coral); }
@@ -1478,14 +1551,19 @@ const html = `<!doctype html>
   .foot-sub .feedback:hover { text-decoration:underline; }
   .foot-sub .pulse { width:14px; height:14px; vertical-align:-3px; margin-right:5px; fill:none;
     stroke:currentColor; stroke-width:2; stroke-linecap:round; stroke-linejoin:round; }
-  /* The line traces itself and sweeps out, like a heart monitor. 46 is the
+  /* The line traces itself and sweeps out, like a heart monitor. 44 is the
      polyline's own length, so the dash covers it exactly. */
-  .foot-sub .pulse polyline { stroke-dasharray:46; animation:pulse-trace 3.4s cubic-bezier(.5,0,.5,1) infinite; }
-  @keyframes pulse-trace { 0% { stroke-dashoffset:46; } 55% { stroke-dashoffset:0; } 100% { stroke-dashoffset:-46; } }
+  .foot-sub .pulse polyline { stroke-dasharray:44; animation:pulse-trace 3.4s cubic-bezier(.5,0,.5,1) infinite; }
+  @keyframes pulse-trace { 0% { stroke-dashoffset:44; } 55% { stroke-dashoffset:0; } 100% { stroke-dashoffset:-44; } }
   @media (prefers-reduced-motion: reduce) {
     .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); }
@@ -1560,8 +1638,12 @@ const html = `<!doctype html>
 <!-- rmds-schema: ${NS_TAG} -->
 </head><body>
 <button class="theme-toggle glass" aria-label="Switch between light and dark mode" onclick="(function(){var r=document.documentElement,t=r.getAttribute('data-theme')==='light'?'dark':'light';r.setAttribute('data-theme',t);try{localStorage.setItem('roast-theme',t)}catch(e){}})()">
-  <svg class="only-dark" viewBox="0 0 24 24"><circle cx="12" cy="12" r="4"/><line x1="12" y1="2" x2="12" y2="5"/><line x1="12" y1="19" x2="12" y2="22"/><line x1="2" y1="12" x2="5" y2="12"/><line x1="19" y1="12" x2="22" y2="12"/><line x1="4.9" y1="4.9" x2="7" y2="7"/><line x1="17" y1="17" x2="19.1" y2="19.1"/><line x1="4.9" y1="19.1" x2="7" y2="17"/><line x1="17" y1="7" x2="19.1" y2="4.9"/></svg>
-  <svg class="only-light" viewBox="0 0 24 24"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z"/></svg>
+  <span class="tt-lab tt-day">Day</span>
+  <span class="tt-lab tt-night">Night</span>
+  <span class="tt-knob">
+    <svg class="tt-moon" viewBox="0 0 24 24"><path d="M20.5 13.2A8.8 8.8 0 1 1 10.8 3.5a6.9 6.9 0 0 0 9.7 9.7z"/></svg>
+    <svg class="tt-sun" viewBox="0 0 24 24"><circle cx="12" cy="12" r="4.2"/><line x1="12" y1="2.2" x2="12" y2="5.4"/><line x1="12" y1="18.6" x2="12" y2="21.8"/><line x1="2.2" y1="12" x2="5.4" y2="12"/><line x1="18.6" y1="12" x2="21.8" y2="12"/><line x1="5.1" y1="5.1" x2="7.3" y2="7.3"/><line x1="16.7" y1="16.7" x2="18.9" y2="18.9"/><line x1="5.1" y1="18.9" x2="7.3" y2="16.7"/><line x1="16.7" y1="7.3" x2="18.9" y2="5.1"/></svg>
+  </span>
 </button>
 <script>try{var t=localStorage.getItem('roast-theme');if(t==='light'||t==='dark')document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
 <div class="wrap">
@@ -1591,6 +1673,8 @@ ${extraSectionsHtml()}
 
 ${whereToStartSection()}
 
+${agentSection()}
+
 ${giftSection()}
 
 ${trapsBlock()}
@@ -1599,8 +1683,6 @@ ${trapsBlock()}
 
 ${packagesSection()}
 
-${agentSection()}
-
 <section style="margin-top:16px">${paletteSection()}</section>
 
 ${spacingBars()}
@@ -1614,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>
@@ -1673,6 +1755,26 @@ ${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'));
+      if(!holder) return;
+      var show=holder.hidden;
+      holder.hidden=!show; holder.classList.toggle('shown', show);
+      var lab=b.querySelector('.why-lab'); if(lab) lab.textContent=show?'hide':'why this matters';
+    });
+  });
   var copyBtn=document.getElementById('gift-copy');
   function rulesText(){ return document.getElementById('gift-md').textContent; }
   copyBtn.addEventListener('click', function(){

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

@@ -0,0 +1,61 @@
+// "Why this matters" toggle copy — one entry per finding, unfolds under the
+// finding's own evidence block. The finding stays brutal; this text is the calm
+// explanation behind it: innocent mechanism, compounding cost, agent amplifier,
+// why the ideal sits where it sits.
+//
+// The copy is Greg-approved word for word (docs/why-behind-copy-approved.md,
+// 2026-09-04) and follows docs/greg-copy-style.md. Do not edit casually: every
+// number in these texts is a published calibration (ideals + benchmark medians)
+// and must move together with benchmark.json if the norms are ever re-tuned.
+
+export const WHY = {
+  colors: [
+    'Look, nobody consciously chooses 100 colours to start with. They were added with each change, and the change after that. No one was checking for the drift, because no one expected it. Then come the multipliers: a rebrand, a dark-mode pass, ad hoc files, each one multiplying the values again.',
+    'When an agent looks for Brand Blue it scans the repo, sees dozens of blues and logically picks the one used most often, which is how the most-used stray outvotes the actual token.',
+    '24 covers a whole product: a brand hue with its tints, an accent, the greys, the status colours. The median across 10 reputable design systems is exactly 24.',
+  ],
+  nearPairs: [
+    'A palette is a set of decisions, and two colours a screen can not tell apart are one decision recorded twice. Nobody chooses to own both: someone could not find the first value quickly enough, made a twin by eye, and it stayed.',
+    'The cost is never tonight’s screen, which looks fine. It is every choice that comes after: colour pickers now offer both, a search for one misses the other, a dark-mode pass updates one twin and ships the other unchanged, and an agent asked for the dark surface copies whichever it happens to find, so the pair breeds.',
+    'The ideal is 0 because each pair collapses in minutes: keep the one that is already a token, point the stray at it, and the multiplication stops. Pound for pound, the cheapest credibility on this page.',
+  ],
+  greys: [
+    'A grey scale is a ladder: each step needs a job (background, border, muted text, disabled) and a visible gap to its neighbours. Around 12 rungs covers every job a real interface has; the reputable systems median is 5.',
+    'Past 13 the gaps close, steps stop being distinguishable, and each new grey is no longer a rung but a guess between rungs, which is exactly where twins come from.',
+  ],
+  spacing: [
+    'Nobody starts a design system with 50 spacing values. A deadline, a last-minute change, and someone nudged a layout until it sat right, and 13px honestly sat better than 12px. The next person can not tell a deliberate exception from a new value, or honestly never noticed, and copies it either way.',
+    'That is how layout rhythm starts drifting. Two lists almost align, two cards almost match, and the page stops looking right. An agent copies nudge after nudge, because to an agent 13px looks as intentional as 12px. And once one page carries enough exceptions, the agent treats them as canonical, and the poison spreads to the other pages.',
+    'The 12 is a budget for values outside the scale, and it is a generous one: the 10 reputable design systems we scanned hold a median of 6. The average product repo carries 34, which is a second, unwritten scale.',
+  ],
+  typefaces: [
+    'One product should have a maximum of 3 font families. When they arrive on their own, it is usually one with a component library, one with a marketing page, one left over from an old logo. Bold and italic do not count; those are weights of one family. And no one will take the risk of removing a font, because nobody is sure what still uses it and what will break.',
+    'Every extra font makes pages heavier to load, adds a licence to track, and splits the product’s voice. An agent starting a new page scans the repo, sees several fonts in use, and may feel obligated to use all of them. The split grows on its own.',
+    'The ideal is 3, one for each real job: a sans for the interface, a serif if the brand wants an accent, a mono for code.',
+  ],
+  duplicates: [
+    'Nobody builds a second Button on purpose. The first one was hard to find, or almost right but easier to rewrite than to change. On the day, rewriting was the faster choice. And no one deletes the old one later, because nobody is sure what still uses it and what will break.',
+    'From then on, every fix reaches one copy and misses the other. Every search has a wrong answer on offer. An agent picks whichever version it happens to find, and every new page makes the more common copy stronger. Common wins over correct, and the drift only deepens.',
+    'The ideal is 0, because the fix is cheap: point one copy at the other and the multiplying stops. The average product repo carries 20 duplicated components.',
+  ],
+  inline: [
+    'An inline style is the fastest way to make one element behave. A deadline, one stubborn element, done. On the day, a fair trade.',
+    'The cost is that the design system can not see it. Theming misses it, dark mode misses it, a token change misses it. Every inline style is a private exception and requires someone to find it by hand. And agents like inline styles, because they always work and they need no knowledge of your system. Every block already in the repo teaches the agent that this is how styling is done here, so the habit spreads.',
+    'The ideal is 0, and the count is fair: only fully static blocks are counted, runtime positioning and canvas work are exempt. The average product repo carries 49 blocks. The 10 reputable systems hold a median of 12.',
+  ],
+  important: [
+    'Every !important marks a styling fight someone had to win by the end of the day. One is harmless. And no one removes it later, because nobody is sure what will break.',
+    'But each one raises the floor. The next override in that area has to shout at least as loud, so the count only climbs. An agent that loses a styling fight reaches for !important straight away, because it is the most common CSS fix it has ever seen.',
+    'The ideal is 0, because !important is CSS admitting defeat. Fix the rule that kept losing, and the next one is never needed. The average product repo carries 7.',
+  ],
+  neverImported: [
+    'A component nobody imports was built for a future that moved, or replaced and never removed. Writing it was probably right at the time. Leaving it on the shelf is the only mistake.',
+    'Every dead component makes the catalogue slower to search and harder to trust. An agent reading your components folder can not tell retired from current, so a dead component becomes a live example to copy.',
+    'The ideal is 0, because a design system is the set of things actually in use. And these are the safest deletes in the repo: nothing imports them, so nothing can break. Delete, or mark as deprecated where the agent will read it.',
+  ],
+  arbitrary: [
+    'Brackets exist for a reason. Sometimes the scale really lacks a value, and one w-[137px] for a stubborn third-party embed is craft, done on purpose.',
+    'But a bracket is a value with no name. A search for the token will never find it, and a scale change leaves it untouched. An agent that sees brackets in the repo learns that the scale is optional. It can not tell which brackets were deliberate, so it feels free to add its own, and the escape hatch becomes the main door.',
+    'The 20 is a budget for real exceptions, and it is a generous one: 9 of the 10 reputable systems we scanned sit at 0, including systems built on Tailwind. The average product repo carries 70.',
+  ],
+};

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.7.2';
+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