roast-my-design-system 7.4.0 → 7.5.0

package/README.md

@@ -1,4 +1,4 @@
-<img src="https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/roaster_logo_300px.png?v=7.4.0" width="72" alt="roast-my-design-system">
+<img src="https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/roaster_logo_300px.png?v=7.5.0" width="72" alt="roast-my-design-system">
 
 # roast-my-design-system
 
@@ -10,6 +10,8 @@
 
 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 7.5: the kit is read as it is built, and every file left out of a count is named.** A fresh `npx shadcn create` install is told apart from a repo built on one: "The score is the kit's, not yours." A rules file a framework wrote for itself is named as such, and so is the shadcn skill when it is installed. The theme file is found where it is, even when `components.json` points at a file that moved; `button/index.tsx` is a Button. The repaint advice checks whether the theme file holds the variables before telling you to swap to them. And the side panel now lists everything a check leaves out, with the reason and one honest line: your agent reads it anyway. New on that list: the Next.js crash page, an embedded widget's `!important`, and `!important` aimed at a library's own class names.
+
 > **New in 7.4: the score says what it measures, and the report has a new shape.** Under the number: "How safely an AI agent can build on this repo without going off-system." A fixed side panel holds the score, the stack, how the repo was read, an index of every section, and what is not yours and not counted. Installed code splits by one test, does it teach an agent a wrong lesson: shadcn's own bracket values are out of the count and named; palette colours inside an installed registry stay in the score and are never prompted; catalogue stock is not a trap. A factory install scores 100. Leftover theme variables become a fix.
 
 > **New in 7.3: shadcn repos are compared with shadcn repos.** The benchmark carries a shadcn slice, 17 of the 34 fleet repos, and on a shadcn repo every fleet line reads against it: "Avg shadcn repo", "cleaner than 60% of shadcn repos". Ideals and the reputable-systems line stay the same for everyone.
@@ -79,11 +81,11 @@ Not to be confused with each other: **"Why this matters"** is generic, ships wit
 
 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: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then the summary, 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, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, 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=7.4.0)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then the summary, 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, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, 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=7.5.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=7.4.0)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=7.5.0)
 
 ## What makes the numbers trustworthy
 
@@ -237,8 +239,8 @@ After the roast, the skill also offers to write `design-system-rules.md` to disk
 
 - **[telekom/scale](https://gregkozakiewicz.github.io/roast-my-design-system/examples/telekom-scale.html)**: Stencil, 95 components read by tag, with Claude's notes embedded
 - **[adobe/spectrum-web-components](https://gregkozakiewicz.github.io/roast-my-design-system/examples/adobe-spectrum.html)**: Lit, the `--spectrum-*` namespace named in the header
-- **[npx shadcn create, fresh](https://gregkozakiewicz.github.io/roast-my-design-system/examples/shadcn-create-fresh.html)**: a factory install with all 61 components, scanned as is
-- **[vercel/ai-chatbot](https://gregkozakiewicz.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)**: React, with Claude's notes embedded
+- **[npx shadcn create, fresh](https://gregkozakiewicz.github.io/roast-my-design-system/examples/shadcn-create-fresh.html)**: a factory install with all 61 components, scanned as is and read as fresh
+- **[vercel/ai-chatbot](https://gregkozakiewicz.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)**: React on shadcn, with Claude's notes embedded
 - **[excalidraw/excalidraw](https://gregkozakiewicz.github.io/roast-my-design-system/examples/excalidraw-excalidraw.html)**
 - **[dubinc/dub](https://gregkozakiewicz.github.io/roast-my-design-system/examples/dubinc-dub.html)**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "7.4.0",
+  "version": "7.5.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/benchmark/benchmark.json

@@ -1852,7 +1852,7 @@
   },
   "slices": {
     "shadcn": {
-      "builtAt": "2026-09-12T20:07:59.374Z",
+      "builtAt": "2026-09-12T23:43:34.615Z",
       "repoCount": 16,
       "note": "every repo in the fleet the scanner reads as shadcn; the \"cleaner than\" line on a shadcn repo reads against these",
       "stats": {
@@ -2055,7 +2055,7 @@
             5,
             7,
             11,
-            22,
+            21,
             24,
             42,
             47,
@@ -2129,20 +2129,20 @@
             0,
             0,
             1,
+            1,
             2,
+            4,
             9,
-            9,
-            12,
-            42,
-            42,
-            55,
-            93,
-            157
+            11,
+            14,
+            34,
+            65,
+            126
           ],
           "p25": 0,
-          "median": 6,
-          "p75": 42,
-          "p90": 74
+          "median": 2,
+          "p75": 12,
+          "p90": 50
         },
         "neverImported": {
           "values": [
@@ -2151,7 +2151,7 @@
             0,
             0,
             1,
-            2,
+            3,
             5,
             13,
             19,
@@ -2208,7 +2208,7 @@
             66,
             100,
             179,
-            296,
+            297,
             488
           ],
           "p25": 22,
@@ -2249,7 +2249,7 @@
           "baseColor": "zinc",
           "tailwind": null,
           "codeFiles": 4391,
-          "ownFiles": 811,
+          "ownFiles": 810,
           "metrics": {
             "colors": 310,
             "greys": 66,
@@ -2262,7 +2262,7 @@
             "inlineStyles": 79,
             "arbitrary": 217,
             "nearPairs": 18,
-            "important": 157,
+            "important": 126,
             "neverImported": 99,
             "components": 1453,
             "paintTin": 22,
@@ -2316,7 +2316,7 @@
             "inlineStyles": 2,
             "arbitrary": 5,
             "nearPairs": 0,
-            "important": 2,
+            "important": 1,
             "neverImported": 0,
             "components": 60,
             "paintTin": 57,
@@ -2343,7 +2343,7 @@
             "inlineStyles": 7,
             "arbitrary": 74,
             "nearPairs": 0,
-            "important": 9,
+            "important": 2,
             "neverImported": 0,
             "components": 316,
             "paintTin": 66,
@@ -2411,7 +2411,7 @@
           "baseColor": "slate",
           "tailwind": null,
           "codeFiles": 2604,
-          "ownFiles": 788,
+          "ownFiles": 787,
           "metrics": {
             "colors": 132,
             "greys": 16,
@@ -2424,10 +2424,10 @@
             "inlineStyles": 24,
             "arbitrary": 113,
             "nearPairs": 8,
-            "important": 55,
-            "neverImported": 2,
+            "important": 34,
+            "neverImported": 3,
             "components": 1085,
-            "paintTin": 296,
+            "paintTin": 297,
             "doorOverrides": 26
           }
         },
@@ -2438,7 +2438,7 @@
           "baseColor": "neutral",
           "tailwind": null,
           "codeFiles": 2141,
-          "ownFiles": 775,
+          "ownFiles": 772,
           "metrics": {
             "colors": 174,
             "greys": 38,
@@ -2465,7 +2465,7 @@
           "baseColor": "gray",
           "tailwind": null,
           "codeFiles": 875,
-          "ownFiles": 410,
+          "ownFiles": 409,
           "metrics": {
             "colors": 17,
             "greys": 3,
@@ -2475,7 +2475,7 @@
             "radii": 14,
             "shadows": 0,
             "exactDuplicates": 17,
-            "inlineStyles": 22,
+            "inlineStyles": 21,
             "arbitrary": 25,
             "nearPairs": 1,
             "important": 0,
@@ -2505,7 +2505,7 @@
             "inlineStyles": 47,
             "arbitrary": 360,
             "nearPairs": 7,
-            "important": 42,
+            "important": 14,
             "neverImported": 13,
             "components": 777,
             "paintTin": 488,
@@ -2519,7 +2519,7 @@
           "baseColor": "slate",
           "tailwind": "3",
           "codeFiles": 2120,
-          "ownFiles": 350,
+          "ownFiles": 349,
           "metrics": {
             "colors": 254,
             "greys": 52,
@@ -2586,7 +2586,7 @@
             "inlineStyles": 47,
             "arbitrary": 366,
             "nearPairs": 10,
-            "important": 12,
+            "important": 4,
             "neverImported": 0,
             "components": 1204,
             "paintTin": 21,
@@ -2613,7 +2613,7 @@
             "inlineStyles": 58,
             "arbitrary": 569,
             "nearPairs": 16,
-            "important": 42,
+            "important": 11,
             "neverImported": 30,
             "components": 1494,
             "paintTin": 58,
@@ -2627,7 +2627,7 @@
           "baseColor": "neutral",
           "tailwind": "4",
           "codeFiles": 1775,
-          "ownFiles": 605,
+          "ownFiles": 604,
           "metrics": {
             "colors": 187,
             "greys": 51,
@@ -2667,7 +2667,7 @@
             "inlineStyles": 263,
             "arbitrary": 1602,
             "nearPairs": 59,
-            "important": 93,
+            "important": 65,
             "neverImported": 23,
             "components": 3630,
             "paintTin": 8,

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

@@ -32,7 +32,7 @@ import { fixPrompt } from '../lib/fixprompt.mjs';
 import { WHY } from './why.mjs';
 import { parseColor, luminance, isGrey } from '../lib/color.mjs';
 import { loadBenchmark, benchHelpers, makeHealthOf, coreMetrics, tileHealths, scoreOfTiles, scoreBreakdown, scorePackage as scorePackageOf, ZERO_IDEAL, WARN_TOLERANCE, SCORE_OF, SCHEMA_VERSION } from './score.mjs';
-import { profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
+import { ownSpacing, profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
 
 // The benchmark and every judgement made against it live in score.mjs; this
 // file only draws. The same numbers reach summary.json through scoreHarvest.
@@ -207,9 +207,12 @@ const greys = greysSorted(bgLumOf(THEMES.dark.pageBgHex));
 const greysLight = greysSorted(bgLumOf(THEMES.light.pageBgHex));
 const nonGreys = colors.filter((c) => !isGrey(c.value));
 const twColorUtils = (h.tokens.tailwind?.colors ?? []).length;
-const spacing = h.tokens.spacing ?? [];
-const twSpacing = h.tokens.tailwind?.spacing ?? [];
-// Off-scale spacing only (formula in score.mjs, shared with the packages pass).
+// On a kit the off-scale values inside installed folders are shadcn's own:
+// kept out of the tile and the bars (formula in score.mjs), named at the top.
+const P_isShadcn = (x) => profileOf(x).isShadcn;
+const spacingOwn = ownSpacing(h);
+const spacing = spacingOwn.css;
+const twSpacing = P_isShadcn(h) ? [...(h.tokens.tailwind?.spacing ?? []).filter((v) => !v.value.startsWith('[')), ...spacingOwn.tw] : (h.tokens.tailwind?.spacing ?? []);
 const spacingTotal = M.spacing;
 const exactDupes = h.duplicates.exactDuplicates ?? [];
 // A wrapped pair (one file imports the name from the other) is composition,
@@ -248,6 +251,7 @@ const nearPairs = nearColorPairs(colors);
 const collisions = h.tokens.tokenCollisions ?? [];
 
 const P = profileOf(h);
+const fresh = P.isShadcn && P.shadcn?.fresh?.fresh === true;
 // On a shadcn repo the bracket list is the team's own; installed brackets are
 // named in the side panel instead (see coreMetrics for the count).
 if (P.isShadcn) arbitrary = splitArbitrary(arbitrary, installedDirs(P)).own;
@@ -297,15 +301,18 @@ if (componentsMeasured && hardDupes.length > 0) candidates.push({ ratio: 1 + har
 if (inline.count > 20) candidates.push({ ratio: inline.count / 20, text: `${n(inline.count)} inline style blocks skip the design system. An agent that reads them learns to do the same` });
 if (arbitraryCount >= 20) candidates.push({ ratio: arbitraryCount / 30, text: `${n(arbitraryCount)} values like ${arbitrary[0].value} are written outside the Tailwind scale. An agent that reads them learns to do the same` });
 if (agentFiles.length === 0) candidates.push({ ratio: 1.3, text: `No agent rules file, so your AI agent has nothing to follow` });
-if ((h.staleRules ?? []).length >= 2) candidates.push({ ratio: 1.2 + h.staleRules.length / 10, text: `${h.staleRules.length} lines in your agent rules refer to files that no longer exist` });
+const staleOwn = (h.staleRules ?? []).filter((s) => !s.tool);
+if (staleOwn.length >= 2) candidates.push({ ratio: 1.2 + staleOwn.length / 10, text: `${staleOwn.length} lines in your agent rules refer to files that no longer exist` });
 const findings = candidates.sort((a, b) => b.ratio - a.ratio).map((c) => c.text);
 
-let verdict = findings.length === 0
+let verdict = fresh
+  ? 'A fresh shadcn install with nothing built on it yet. Everything below describes the kit you are starting from.'
+  : findings.length === 0
   ? (agentFiles.length > 0
     ? 'This repo is in good shape, and your agent has rules to read. Keep them in step with the code.'
     : 'This repo is in good shape. The gap is documentation: your agent still can\'t see the system.')
   : findings.slice(0, 3).join('. ') + '.';
-if (bench && findings.length) {
+if (bench && findings.length && !fresh) {
   const core = [['colors', tokenLed ? colorStrays : colors.length], ['greys', tokenLed ? greyStrays : greys.length],
     ['spacing', spacingTotal], ['typefaces', typefaces.length], ['exactDuplicates', hardDupes.length], ['inlineStyles', inline.count]];
   const worse = core.filter(([m, v]) => median(m) !== null && v > median(m)).length;
@@ -595,7 +602,7 @@ function sheetSection() {
   const sheet = sc.sheet, paint = sc.paint;
   const parts = [];
   if (sheet?.found) {
-    const bits = [`${n(sheet.lightRows)} variables for light, ${n(sheet.darkRows)} for dark in ${esc(sheet.file)}`];
+    const bits = [`${n(sheet.lightRows)} variables for light, ${n(sheet.darkRows)} for dark in ${esc(sheet.file)}${sheet.scope ? ` under ${esc(sheet.scope)}` : ''}${sheet.configured && sheet.configured !== sheet.file ? ` (components.json names ${esc(sheet.configured)}, ${sheet.configuredFound ? 'which holds no theme rows' : 'which does not exist'})` : ''}`];
     if (sheet.hslEra) bits.push('written in the Tailwind 3 form (hsl triplets)');
     if (sheet.shadcnMissing?.length) bits.push(`${sheet.shadcnMissing.length} of the ${SHADCN_ROW_COUNT} current shadcn variables not defined (${sheet.shadcnMissing.slice(0, 4).map((r) => `--${esc(r)}`).join(', ')}${sheet.shadcnMissing.length > 4 ? '…' : ''})${sheet.hslEra ? ', normal for an install from before the chart and sidebar rows existed' : ''}`);
     if (sheet.missingDark?.length) bits.push(`${sheet.missingDark.length} variable${sheet.missingDark.length === 1 ? '' : 's'} with no dark value (${sheet.missingDark.slice(0, 4).map((r) => `--${esc(r)}`).join(', ')})`);
@@ -635,7 +642,7 @@ function duplicatesSection() {
     </div>` : '';
   const dupeCards = exactDupes.slice(0, 8).map((d) => `
     <div class="fam">
-      ${eyebrow(`&lt;${esc(d.name)}&gt; · ${d.wrapped ? 'defined twice, one wraps the other' : `${d.files.length} implementations`}`)}
+      ${eyebrow(`&lt;${esc(d.name)}&gt; · ${d.upstream ? 'two shadcn components define it: upstream\'s overlap, not counted' : d.wrapped ? 'defined twice, one wraps the other' : `${d.files.length} implementations`}`)}
       <div class="fam-rows">
       ${d.files.slice(0, 6).map((f) => `<div class="mini-card">${fileLink(f)}</div>`).join('')}
       ${d.files.length > 6 ? `<div class="mini-card dim">…and ${d.files.length - 6} more</div>` : ''}
@@ -742,7 +749,7 @@ function typographySection() {
     ${typeSpecimens || receipts('the font sizes, by use', sizeChips)}
     ${radiiSpecimens || receipts('the radii, by use', radiiChips)}
     ${shadowSpecimens}
-    ${fontFamilies.length > 1 ? `<div class="glass pad" style="margin-top:16px">${sectionHead(`${typefaces.length} typeface${typefaces.length === 1 ? '' : 's'}, declared ${fontFamilies.length} different ways`, 'every distinct declaration is a chance for the next one to be wrong')}<div class="fam-rows">${fams}</div></div>` : ''}
+    ${fontFamilies.length > 1 && fontFamilies.length > typefaces.length ? `<div class="glass pad" style="margin-top:16px">${sectionHead(`${typefaces.length} typeface${typefaces.length === 1 ? '' : 's'}, declared ${fontFamilies.length} different ways`, 'every distinct declaration is a chance for the next one to be wrong')}<div class="fam-rows">${fams}</div></div>` : ''}
   </section>`;
 }
 
@@ -882,7 +889,8 @@ function componentsSection() {
     ${sectionHead(isLibrary ? 'The composition map' : 'The adoption map', `${n(reusable.length)} components defined · tile area is ${isLibrary ? 'internal use: how the system builds from itself, downstream consumers invisible from here' : 'import count'} · the real system, drawn to scale`)}
     ${mapped}
     ${overflow > 0 ? `<p class="sub">${overflow} more adopted component${overflow === 1 ? '' : 's'} below the top 24, not drawn.</p>` : ''}
-    ${onceUsed.length ? `<p class="sub">${n(onceUsed.length)} component${onceUsed.length === 1 ? ' is' : 's are'} imported exactly once: ${onceUsed.slice(0, 6).map((c) => `&lt;${esc(c.name)}&gt;`).join(', ')}${onceUsed.length > 6 ? ` and ${onceUsed.length - 6} more` : ''}. Quiet corners, not yet a system.</p>` : ''}
+    ${fresh ? '<p class="sub">No code of your own uses the kit yet. The counts below are the components using each other.</p>' : ''}
+    ${onceUsed.length && !fresh ? `<p class="sub">${n(onceUsed.length)} component${onceUsed.length === 1 ? ' is' : 's are'} imported exactly once: ${onceUsed.slice(0, 6).map((c) => `&lt;${esc(c.name)}&gt;`).join(', ')}${onceUsed.length > 6 ? ` and ${onceUsed.length - 6} more` : ''}. Quiet corners, not yet a system.</p>` : ''}
     ${top.length ? `<div class="tbl-wrap"><table><thead><tr><th>component</th><th>used</th><th>defined in</th><th>props</th></tr></thead><tbody>${rows}</tbody></table></div>` : ''}
     ${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` : vendoredUi ? `${n(neverImported.length)} catalogue components not used yet · installed by the shadcn CLI and waiting to be used, not written by this team` : `${n(neverImported.length)} components defined but never imported · they sit in the system as wrong answers waiting to be picked`)}
@@ -1081,9 +1089,18 @@ function whereToStartSection() {
     const pt = P.shadcn.paint;
     if (pt.tin.uses >= 10) {
       const s0 = pt.tin.samples[0], f0 = pt.tin.top[0];
-      c.push({ score: 20 + pt.tin.per100 / 4, metric: 'paintTin', after: 0,
-        title: `Repaint the ${n(pt.tin.uses)} colours from outside the theme`,
-        sub: `${esc(s0.value)} appears ${s0.count} times${f0 ? `, ${esc(basename(f0.file))} alone carries ${f0.count}` : ''}. The theme file already has a variable for each (a grey is <code>text-muted-foreground</code>, a status colour is a Badge variant or a variable you add). Swap the class, not the value.` });
+      // The swap only works when the theme file holds the variables. A
+      // product whose sheet defines none of them (formbricks: brand rows
+      // only, slate as the palette) needs a decision first, not a prompt:
+      // swapping classes there leaves text with no colour.
+      const sheetHasRows = (P.shadcn?.sheet?.shadcnPresent ?? 0) >= 5 || P.shadcn?.kit?.cssVariables === false;
+      c.push(sheetHasRows
+        ? { score: 20 + pt.tin.per100 / 4, metric: 'paintTin', after: 0,
+          title: `Repaint the ${n(pt.tin.uses)} colours from outside the theme`,
+          sub: `${esc(s0.value)} appears ${s0.count} times${f0 ? `, ${esc(basename(f0.file))} alone carries ${f0.count}` : ''}. The theme file already has a variable for each (a grey is <code>text-muted-foreground</code>, a status colour is a Badge variant or a variable you add). Swap the class, not the value.` }
+        : { score: 20 + pt.tin.per100 / 4, metric: 'paintTin', after: 0,
+          title: `Decide what the product paints from`,
+          sub: `${esc(s0.value)} appears ${s0.count} times${f0 ? `, ${esc(basename(f0.file))} alone carries ${f0.count}` : ''}, and there is no theme file to point them at: ${P.shadcn?.sheet?.file ? `${esc(P.shadcn.sheet.file)} defines` : 'the theme file defines'} none of shadcn's colour variables, so the palette is the system today. The first move is a decision, not a swap: adopt the theme variables (define them, map the palette onto them), then repaint file by file. Swapping <code>text-slate-500</code> for <code>text-muted-foreground</code> before that leaves the text with no colour.` });
     }
     if (pt.doors.uses >= 5) {
       const s0 = pt.doors.samples[0];
@@ -1130,6 +1147,7 @@ function whereToStartSection() {
   // reads at click time, so a forwarded report keeps working offline.
   const unesc = (s) => s.replace(/<[^>]+>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&rarr;/g, '->').replace(/&amp;/g, '&');
   const promptFor = (item) => fixPrompt({
+    metric: item.metric,
     title: unesc(item.title),
     sub: unesc(item.sub),
     deltaText: item.delta > 0 ? `about +${item.delta} points` : (item.target ? `about +${item.target.gain} points once ${item.target.target === 0 ? 'they are all cleared' : `the count is under ${n(item.target.target)}`}` : ''),
@@ -1205,7 +1223,20 @@ function agentSection() {
   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
+  // A file a framework wrote for itself (Next.js re-adds its block on every
+  // dev run) is not guidance about the design system, and says so.
+  const managedOnly = agentFiles.length > 0 && agentFiles.every((c) => c.managedOnly === true);
+  const managedBy = managedOnly ? agentFiles[0].managedBy : null;
+  const skill = (h.context ?? []).find((c) => c.kind === 'agent-skill');
+  const skillLine = P.isShadcn ? (skill ? ` The shadcn skill is installed (<span class="mono">${esc(skill.file)}</span>), so the agent can read the kit's configuration.` : ' shadcn offers a skill for that and it is not installed here.') : '';
+  // the files name the kit (or the skill is installed): the gap is the
+  // repo's own habits, which no hand-written file carries
+  const namesKit = P.isShadcn && (skill || agentFiles.some((c) => c.mentionsDesign === true && c.managedOnly !== true));
+  const msg = managedOnly
+    ? `<p class="sub">Your agent reads ${readsList}. ${esc(managedBy)} wrote it, and it is only about ${esc(managedBy)}: nothing in it mentions the theme file or the component folder, so the agent does not know the ${P.isShadcn ? 'kit' : 'design system'} is there.${skillLine} Add the rules file below and the agent knows the theme, the components and the styling rules.</p>`
+    : namesKit
+    ? `<p class="sub">Your agent reads ${readsList}${nestedCount && rootAgent.length ? `, plus ${nestedCount} rules file${nestedCount === 1 ? '' : 's'} nested in subfolders` : ''}${skill ? `, and the shadcn skill is installed (<span class="mono">${esc(skill.file)}</span>)` : ''}. ${skill && !agentFiles.some((c) => c.mentionsDesign) ? 'The skill tells it' : 'They tell it'} the kit is there. What ${skill && !agentFiles.some((c) => c.mentionsDesign) ? 'it does' : 'they do'} not carry is how this repo actually uses it: the numbers below, which the rules file turns into rules with receipts.</p>`
+    : agentFiles.length
     ? `<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
@@ -1222,13 +1253,13 @@ function agentSection() {
   const staleRows = stale.map((s) => `
     <div class="ledger-row">
       <span class="mono strong">${esc(s.ref)}</span>
-      <span class="dim">${s.problem === 'missing' ? 'named in' : 'named canonical in'} ${esc(s.file)}, ${s.problem === 'missing' ? 'but the path no longer exists' : 'but nothing imports it this scan'}</span>
+      <span class="dim">${s.problem === 'missing' ? 'named in' : 'named canonical in'} ${esc(s.file)}${s.tool ? ` (written by ${esc(s.tool)}, not by this team)` : ''}, ${s.problem === 'missing' ? 'but the path no longer exists' : 'but nothing imports it this scan'}</span>
     </div>`).join('');
   const staleBlock = stale.length ? `
     <div class="stale">
       ${eyebrow(`${stale.length} rule reference${stale.length === 1 ? '' : 's'} gone stale · a rule your agent obeys is worse than no rule when the repo has moved on`)}
       <div class="ledger">${staleRows}</div>
-      <p class="sub" style="margin-top:10px">Rules rot quietly: nobody edits them when a component is renamed or a file moves. Regenerate them from a fresh scan, or fix the lines by hand.</p>
+      <p class="sub" style="margin-top:10px">${stale.every((s) => s.tool) ? 'These lines were written by a tool, not by this team: a rule pack that speaks about files this app does not have. Not yours to fix; worth knowing your agent reads them.' : 'Rules rot quietly: nobody edits them when a component is renamed or a file moves. Regenerate them from a fresh scan, or fix the lines by hand.'}</p>
     </div>` : '';
   return `<section class="glass pad agent">
     ${sectionHead('What your AI agent sees today', '')}
@@ -1279,7 +1310,14 @@ function shadcnReceipt() {
   ].filter(Boolean);
   const unmatched = (k?.fellBack ?? []).filter((f) => f === 'theme' || f === 'chartColor');
   const fell = unmatched.length ? ` · ${unmatched.length === 2 ? 'accent and chart colour' : unmatched[0] === 'theme' ? 'accent' : 'chart colour'} not matched to a named shadcn theme` : '';
-  return `<div class="excl">Read as a shadcn install (${esc(P.confidence ?? 'medium')} confidence): ${esc(P.evidence.join(' · '))}${facts.length ? ` · ${esc(facts.join(', '))}` : ''}${esc(fell)}</div>`;
+  const receipt = `${esc(P.evidence.join(' · '))}${facts.length ? ` · ${esc(facts.join(', '))}` : ''}${esc(fell)}`;
+  if (fresh) {
+    const f = P.shadcn.fresh;
+    const doors = f.catalogueCount;
+    const pages = comps.filter((c) => c.isPage && f.ownFiles.includes(c.file)).length;
+    return `<div class="excl fresh">It is a fresh shadcn install${k?.style ? ` (style ${esc(k.style)}${k.baseColor ? `, base colour ${esc(k.baseColor)}` : ''}${k.tailwind ? `, Tailwind ${esc(k.tailwind)}` : ''})` : ''}. Nothing of your own yet: ${n(doors)} component${doors === 1 ? '' : 's'} installed, the theme file untouched, ${pages === 1 ? 'one demo page' : `${pages} pages`}. <b>The score is the kit's, not yours.</b> Run this again once you have built a few screens.</div><div class="excl">Evidence: ${receipt}</div>`;
+  }
+  return `<div class="excl">Read as a shadcn install (${esc(P.confidence ?? 'medium')} confidence): ${receipt}</div>`;
 }
 
 // User exclusions are printed in the header, never hidden: a scoped scan must
@@ -1339,12 +1377,38 @@ function exceptionsBlock() {
   if (P.isShadcn) {
     const ai = P.shadcn?.arbitraryInstalled;
     if (ai?.uses) lines.push(`${n(ai.uses)} bracket value${ai.uses === 1 ? '' : 's'} inside ${esc(P.uiDirs.map((d) => basename(d)).join(', '))} are shadcn's own (${ai.values.slice(0, 3).map((v) => esc(v.value)).join(', ')}) and are not counted. shadcn's docs allow brackets for one-off values, so your agent will treat them as normal; the rules file tells it otherwise for your own code.`);
+    const si = spacingOwn.installed;
+    const sv = si.values.length;
+    if (sv) lines.push(`${n(sv)} off-scale spacing value${sv === 1 ? '' : 's'} inside ${esc(P.uiDirs.map((d) => basename(d)).join(', '))} ${sv === 1 ? 'is' : 'are'} shadcn's own (${si.values.slice(0, 3).map((v) => esc(v.value)).join(', ')}) and ${sv === 1 ? 'is' : 'are'} not counted, for the same reason as the bracket values.`);
     if (vendoredUi && neverImported.length) lines.push(`${n(neverImported.length)} catalogue component${neverImported.length === 1 ? '' : 's'} not used yet: stock on the shelf, not scored.`);
     const rp = P.shadcn?.registryPaint;
     if (rp) lines.push(`Installed registr${rp.dirs.length === 1 ? 'y' : 'ies'} ${esc(rp.dirs.map((d) => basename(d)).join(', '))}: ${n(rp.files)} file${rp.files === 1 ? '' : 's'}${rp.tinUses ? `, ${n(rp.tinUses)} palette colour${rp.tinUses === 1 ? '' : 's'}` : ''}. Kept in the score, left out of the fixes. Your agent reads them like everything else.`);
   } else if (isLibrary) {
     lines.push('A library: unused components are internal-only, and downstream consumers are invisible from here.');
   }
+  const li = h.tokens?.important?.library;
+  if (li?.count) lines.push(`${n(li.count)} !important declaration${li.count === 1 ? '' : 's'} aimed at a library's own class names (${li.classes.slice(0, 3).map((c) => esc(c.value)).join(', ')}) ${li.count === 1 ? 'is' : 'are'} not counted: the library ships its CSS, and this is the only way through it. Your agent reads ${li.count === 1 ? 'it' : 'them'} like everything else.`);
+  // Files no checker judges (email, print, artwork, render-to-image, the
+  // crash page): named here with the reason, because the agent reads them
+  // like everything else and can copy what is in them.
+  const ex = h.tokens?.exemptFiles ?? [];
+  if (ex.length) {
+    const byReason = new Map();
+    for (const e of ex) { if (!byReason.has(e.reason)) byReason.set(e.reason, []); byReason.get(e.reason).push(e.file); }
+    for (const [reason, files] of byReason) {
+      // two files with one name (a spare-part copy) are told apart by their folder
+      const label = (f) => {
+        const parts = f.split('/');
+        for (let k = 1; k <= parts.length; k++) {
+          const tail = parts.slice(-k).join('/');
+          if (files.filter((o) => o === tail || o.endsWith(`/${tail}`)).length === 1) return tail;
+        }
+        return f;
+      };
+      const names = files.slice(0, 3).map((f) => esc(label(f))).join(', ') + (files.length > 3 ? ` and ${files.length - 3} more` : '');
+      lines.push(`${n(files.length)} file${files.length === 1 ? '' : 's'} not judged (${names}): ${esc(reason)}. Not counted, but your agent reads ${files.length === 1 ? 'it' : 'them'} like everything else, so what is in there is still an example it can copy.`);
+    }
+  }
   if (!lines.length) return '';
   return `<div class="excs"><b>Not yours, and not counted</b>${lines.map((l) => `<p>${l}</p>`).join('')}</div>`;
 }
@@ -1409,6 +1473,8 @@ const html = `<!doctype html>
   .side .chips { margin:0 0 14px; gap:5px; }
   .side .facts { font:500 11.5px/1.55 var(--sans); color:var(--dim); margin-bottom:16px; }
   .side .facts .excl { margin-top:6px; font-size:11.5px; }
+  .side .facts .excl.fresh { color:var(--text); }
+  .side .facts .excl.fresh b { color:var(--text); }
   .side .facts b { color:var(--text); font-weight:600; }
   .side .idx-head { margin-bottom:4px; }
   .side .idx a { display:block; font:500 13px/1.3 var(--sans); color:var(--dim); text-decoration:none; padding:6px 0 6px 12px; border-left:2px solid var(--line); }
@@ -1961,7 +2027,7 @@ if (summaryPath) {
     verdict,
     role: P.role,
     kind: P.kind,
-    ...(P.isShadcn && P.shadcn ? { shadcn: { confidence: P.confidence, evidence: P.evidence, style: P.shadcn.kit?.style ?? null, baseColor: P.shadcn.kit?.baseColor ?? null, tailwind: P.shadcn.kit?.tailwind ?? null, catalogues: P.uiDirs, registries: P.shadcn.registryDirs ?? [], ...(P.shadcn.registryPaint ? { registryFiles: P.shadcn.registryPaint.files, registryPaletteColours: P.shadcn.registryPaint.tinUses } : {}), ownFiles: P.shadcn.paint?.ownFiles ?? null } } : {}),
+    ...(P.isShadcn && P.shadcn ? { shadcn: { confidence: P.confidence, evidence: P.evidence, style: P.shadcn.kit?.style ?? null, baseColor: P.shadcn.kit?.baseColor ?? null, tailwind: P.shadcn.kit?.tailwind ?? null, catalogues: P.uiDirs, registries: P.shadcn.registryDirs ?? [], ...(P.shadcn.registryPaint ? { registryFiles: P.shadcn.registryPaint.files, registryPaletteColours: P.shadcn.registryPaint.tinUses } : {}), ownFiles: P.shadcn.paint?.ownFiles ?? null, fresh: P.shadcn.fresh?.fresh === true } } : {}),
     componentsMeasured,
     metrics: (({ colors, colorTokens, colorStrays, greys, greyStrays, spacing, exactDuplicates, inlineStyles, nearPairs, important, neverImported, arbitrary, tokenLed }) =>
       ({ colors, colorTokens, colorStrays, greys, greyStrays, spacing, exactDuplicates, inlineStyles, nearPairs, important, neverImported, arbitrary, tokenLed }))(M),

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

@@ -26,7 +26,7 @@ import { isGrey } from '../lib/color.mjs';
 import { nearColorPairs } from '../lib/nearpairs.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { SCHEMA_VERSION } from '../lib/version.mjs';
-import { profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
+import { profileOf, installedDirs, splitArbitrary, ownSpacing } from '../profiles/index.mjs';
 
 export { SCHEMA_VERSION };
 
@@ -136,8 +136,9 @@ export function coreMetrics(h, opts = {}) {
   const greys = colors.filter((c) => isGrey(c.value));
   const colorTokens = colors.filter((c) => c.isToken).length;
   const colorStrays = colors.length - colorTokens;
-  const spacing = h.tokens?.spacing ?? [];
-  const twSpacing = h.tokens?.tailwind?.spacing ?? [];
+  // Off-scale spacing the team wrote: on a kit the values inside installed
+  // folders are shadcn's own, kept out like its bracket values and named.
+  const sp = ownSpacing(h);
   const hardDupes = (h.duplicates?.exactDuplicates ?? []).filter((d) => !d.wrapped);
   return {
     colors: colors.length,
@@ -150,7 +151,7 @@ export function coreMetrics(h, opts = {}) {
     greyStrays: greys.filter((c) => !c.isToken).length,
     // Off-scale spacing only: CSS-declared values plus bracket utilities.
     // Many steps of the sanctioned Tailwind scale is health, not sprawl.
-    spacing: spacing.length + twSpacing.filter((v) => v.value.startsWith('[')).length,
+    spacing: sp.css.length + sp.tw.length,
     // A wrapped pair (one file imports the name from the other) is
     // composition, not competition: listed with a badge, never counted.
     exactDuplicates: hardDupes.length,

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

@@ -48,6 +48,21 @@ const SKIP_DIRS = new Set([
   '.turbo', '.cache', 'vendor', 'tmp',
 ]);
 const MAX_DEPTH = 6;
+// where the skills CLI installs a skill, per tool
+const SKILL_DIRS = ['.claude/skills', '.agents/skills', '.cursor/skills', '.codex/skills', '.github/skills', '.windsurf/skills', 'skills'];
+// framework-managed blocks: markers and who writes them
+const MANAGED = [
+  { by: 'Next.js', start: /<!--\s*(BEGIN:nextjs-agent-rules|NEXT-AGENTS-MD-START)\s*-->/, end: /<!--\s*(END:nextjs-agent-rules|NEXT-AGENTS-MD-END)\s*-->/ },
+];
+function managedBlock(raw) {
+  for (const m of MANAGED) {
+    const a = raw.search(m.start), e = raw.search(m.end);
+    if (a < 0 || e < 0) continue;
+    const rest = (raw.slice(0, a) + raw.slice(e).replace(m.end, '')).trim();
+    return { by: m.by, only: rest.length === 0 };
+  }
+  return null;
+}
 const MAX_NESTED = 60; // entries recorded; the true count keeps counting
 
 function sweepNested(root) {
@@ -98,12 +113,28 @@ export function harvestContext(root) {
       if (c.dir || st.isDirectory()) { found.push({ ...c, size: null, mentionsDesign: null }); continue; }
       size = st.size;
       if (size < 200_000) {
-        const text = readFileSync(p, 'utf8').toLowerCase();
+        const raw = readFileSync(p, 'utf8');
+        const text = raw.toLowerCase();
         mentionsDesign = /design system|component|token|color|colour|styling|tailwind|css/.test(text);
+        // A block a framework writes and re-writes (Next.js's dev server adds
+        // its agent-rules block whenever it sees an agent) is not the team's
+        // guidance. managedOnly: nothing else in the file.
+        const m = managedBlock(raw);
+        if (m) { found.push({ file: c.file, kind: c.kind, tool: c.tool ?? null, size, mentionsDesign, managedBy: m.by, managedOnly: m.only }); continue; }
       }
     } catch { /* unreadable */ }
     found.push({ file: c.file, kind: c.kind, tool: c.tool ?? null, size, mentionsDesign });
   }
+  // shadcn's own skill, installed by the skills CLI into a tool's skills
+  // folder: the one thing that tells an agent the kit is there.
+  for (const dir of SKILL_DIRS) {
+    const p = join(root, dir);
+    if (!existsSync(p)) continue;
+    let names = [];
+    try { names = readdirSync(p); } catch { continue; }
+    const hit = names.find((nm) => /^shadcn/i.test(nm));
+    if (hit) { found.push({ file: `${dir}/${hit}`, kind: 'agent-skill', tool: 'shadcn skill', size: null, mentionsDesign: true }); break; }
+  }
   const nested = sweepNested(root);
   found.push(...nested.found);
   if (nested.total > nested.found.length) {

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

@@ -1,4 +1,6 @@
 import { readFileSync } from 'node:fs';
+import { CATALOGUE } from '../profiles/shadcn-data.mjs';
+import { doorName } from '../profiles/shadcn.mjs';
 import { join } from 'node:path';
 
 /**
@@ -55,7 +57,8 @@ const ROUTE_FRAGMENT_RE = /(^|\/)app\/.*\/(form|header|footer|nav|page|layout|lo
  *   name from the other are tagged wrapped:true (composition, not competition)
  * @returns { exactDuplicates: [{name, files, wrapped?}], families: [{root, members: [{name, file, usageCount}]}] }
  */
-export function findDuplicates(components, uiDir = null, root = null) {
+export function findDuplicates(components, uiDir = null, root = null, uiDirs = null) {
+  const catalogueDirs = uiDirs ?? (uiDir ? [uiDir] : []);
   // Email templates legitimately mirror web component names (email Footer !=
   // web Footer); cross-matching them manufactures duplicates.
   const EMAIL_PATH_RE = /(^|\/)emails?(\/|-)/i;
@@ -88,9 +91,16 @@ export function findDuplicates(components, uiDir = null, root = null) {
   // agent trap worth listing, but not a competing implementation.
   const perFile = new Map();
   for (const c of comps) perFile.set(c.file, (perFile.get(c.file) ?? 0) + 1);
+  // Every copy inside the shadcn catalogue, each a catalogue door (toast.tsx
+  // and sonner.tsx both define Toaster): upstream's overlap, not the team's.
+  // Listed with a badge, never counted, like a wrapped pair.
+  for (const d of exactDuplicates) {
+    if (!catalogueDirs.length) break;
+    if (d.files.every((f) => catalogueDirs.some((u) => f.startsWith(`${u}/`)) && CATALOGUE.has(doorName(f)))) { d.wrapped = true; d.upstream = true; }
+  }
   if (root) {
     for (const d of exactDuplicates) {
-      if (d.files.length !== 2) continue;
+      if (d.files.length !== 2 || d.wrapped) continue;
       // A file defining 8+ components is an API surface (menu-item variants of
       // real components elsewhere) — same-name there is deliberate, not a copy.
       if (d.files.some((f) => (perFile.get(f) ?? 0) >= 8)) { d.wrapped = true; continue; }

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

@@ -27,7 +27,7 @@ import { ruleStaleness } from '../lib/staleness.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { lastTouchedDates } from '../lib/lasttouched.mjs';
 import { SCHEMA_VERSION } from '../lib/version.mjs';
-import { decideProfile, profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
+import { decideProfile, decideFresh, profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
 import { countPaint } from './paint.mjs';
 
 function arg(name, fallback) {
@@ -90,10 +90,13 @@ decideProfile(profile, components, files, target);
     // choices: a true lesson, badly framed. Kept out of the count, named.
     const split = splitArbitrary(tokens.tailwind?.arbitrary ?? [], allInstalled);
     profile.shadcn.arbitraryInstalled = split.installed;
+    // A fresh kit (the install command's output, nothing built yet) is
+    // decided here, once, from the facts above.
+    decideFresh(profile, components, files, tokens, target);
   }
 }
 
-const duplicates = findDuplicates(components, profile.uiDir, target);
+const duplicates = findDuplicates(components, profile.uiDir, target, profile.uiDirs ?? null);
 const context = harvestContext(target);
 const staleRules = ruleStaleness(target, components,
   new Set(neverImportedComponents(components, profile.uiDir).map((c) => c.name)),

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

@@ -8,7 +8,7 @@
  */
 import { existsSync } from 'node:fs';
 import {
-  EMAIL_PRINT_RE, ARTWORK_NAME_RE, RENDER_TO_IMAGE_RE, OG_ROUTE_RE, RENDERER_PATH_RE, svgHeavy,
+  EMAIL_PRINT_RE, ARTWORK_NAME_RE, RENDER_TO_IMAGE_RE, OG_ROUTE_RE, RENDERER_PATH_RE, CRASH_PAGE_RE, svgHeavy, exemptReason, isLibraryClass,
 } from '../lib/exempt.mjs';
 import { join } from 'node:path';
 import { canonical, parseColor } from '../lib/color.mjs';
@@ -293,6 +293,24 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   const inlineStyleFiles = new Map();
   // !important is the cascade admitting defeat; counted per style file.
   const importantFiles = new Map();
+  // An embedded widget (a survey, a chat bubble) lives inside a stranger's
+  // page and must beat the host's CSS: Tailwind imported with the important
+  // flag, or a config scoping every utility under an id. There, !important is
+  // the medium, like inline styles in email. Skipped, named with the reason.
+  const WIDGET_CSS_RE = /@import\s+["']tailwindcss(?:\/utilities\.css)?["'][^;]*\bimportant\b/;
+  const WIDGET_CONFIG_RE = /\bimportant\s*:\s*["']#/;
+  const widgetDirs = codeFiles.filter((f) => /(^|\/)tailwind\.config\.[mc]?[jt]s$/.test(f))
+    .filter((f) => WIDGET_CONFIG_RE.test(readSource(join(root, f)) ?? ''))
+    .map((f) => f.slice(0, f.lastIndexOf('/') + 1));
+  const mediumFiles = [];
+  // !important aimed at a library's own class names (a code editor, a date
+  // picker, an emoji picker ships its CSS; shouting is the only way through)
+  // is the medium too. Decided after the code walk: a class the team writes
+  // anywhere in code is the team's, so doubt counts (fleet probe 2026-09-13:
+  // 30% of all !important, the tile keeps its spread).
+  const importantBlocks = [];
+  const ownClasses = new Set();
+  const WIDGET_REASON = 'an embedded widget forces its rules through the host page\'s CSS, so !important is the medium';
 
   // Colours that appear in a CSS custom-property DEFINITION (--grey-100: #f5f5f5)
   // are deliberate tokens; everything else is a hardcoded stray. The diagnosis
@@ -342,7 +360,22 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     // character offset below still points at the same place in the file.
     const text = raw.replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length));
     const imp = (text.match(/!\s*important/gi) ?? []).length;
-    if (imp) importantFiles.set(file, (importantFiles.get(file) ?? 0) + imp);
+    const widget = WIDGET_CSS_RE.test(text) || widgetDirs.some((d) => file.startsWith(d));
+    if (imp && widget) mediumFiles.push({ file, reason: WIDGET_REASON, count: imp });
+    else if (imp) {
+      // innermost blocks carry a selector to judge; anything outside them
+      // (a declaration above a nested SCSS block) is counted, unjudged
+      let inBlocks = 0;
+      for (const m of text.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+        const n = (m[2].match(/!\s*important/gi) ?? []).length;
+        if (!n) continue;
+        inBlocks += n;
+        const sel = m[1].trim().split(/\s*\n\s*/).pop();
+        const classes = sel.startsWith('@') ? [] : [...sel.matchAll(/\.([A-Za-z_][\w-]*)/g)].map((x) => x[1]);
+        importantBlocks.push({ file, count: n, classes });
+      }
+      if (imp > inBlocks) importantBlocks.push({ file, count: imp - inBlocks, classes: [] });
+    }
     // Character ranges holding a re-statement of an already-named token. The
     // blanket colour sweep below reads the whole file, so it needs to be told
     // which stretches of it are variants rather than new colours.
@@ -417,14 +450,18 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   // Email, artwork, mostly-SVG files and pixel renderers: all imported from
   // lib/exempt.mjs, the one list every checker reads.
   const EXEMPT_RE = EMAIL_PRINT_RE, ARTWORK_RE = ARTWORK_NAME_RE;
+  // every file a check skipped, with the reason, so the report can name them
+  const exemptFiles = [];
+  const skip = (f, src) => { const r = exemptReason(f, src); if (r) exemptFiles.push({ file: f, reason: r }); return true; };
   // Colour-picker palettes and design-field option lists are user-facing data.
   const PALETTE_FILE_RE = /(color-picker|colour-picker|palette|design-fields|swatch)/i;
 
   for (const f of codeFiles) {
     if (!/\.(tsx|jsx|ts|js)$/.test(f)) continue;
-    if (EXEMPT_RE.test(f)) continue;
+    if (EXEMPT_RE.test(f) || CRASH_PAGE_RE.test(f)) { skip(f, ''); continue; }
     let src = readSource(join(root, f));
     if (src === null) continue;
+    for (const m of src.matchAll(/[A-Za-z_][\w-]+/g)) ownClasses.add(m[0]);
 
     // CSS-in-tagged-templates (Lit css``, styled-components css``) IS the
     // stylesheet in those worlds: Shoelace keeps its entire component styling
@@ -474,13 +511,13 @@ export function harvestTokens(root, styleFiles, codeFiles) {
       paletteFiles.add(f);
       for (const m of src.matchAll(HEX_RE)) tokenDefined.add(normalizeHex(m[0]));
     }
-    if (ARTWORK_RE.test(f) || RENDERER_PATH_RE.test(f) || svgHeavy(src)) continue;
+    if (ARTWORK_RE.test(f) || RENDERER_PATH_RE.test(f) || svgHeavy(src)) { skip(f, src); continue; }
     // A render-to-image surface (OG card, PDF invoice) is artwork drawn with
     // code: its colours are the picture's, not the product's palette. Until
     // 5.10.0 they were the only "strays" a clean shadcn repo had, and they
     // triggered the "every single one is hardcoded" banner on it.
     const renderToImage = RENDER_TO_IMAGE_RE.test(src) || OG_ROUTE_RE.test(f);
-    if (renderToImage) continue;
+    if (renderToImage) { skip(f, src); continue; }
 
     // Tailwind classes
     for (const cls of classStrings(src)) {
@@ -624,6 +661,17 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     }
   }
 
+  // Resolve the !important blocks now that every class the team writes is known.
+  const libraryImportant = { count: 0, classes: new Map(), files: new Map() };
+  for (const b of importantBlocks) {
+    // a known library's class names, none of which the team writes in code:
+    // both conditions, so a team class used only from CSS still counts
+    const library = b.classes.length > 0 && !b.classes.some((c) => ownClasses.has(c)) && b.classes.some(isLibraryClass);
+    if (!library) { importantFiles.set(b.file, (importantFiles.get(b.file) ?? 0) + b.count); continue; }
+    libraryImportant.count += b.count;
+    libraryImportant.classes.set(b.classes[0], (libraryImportant.classes.get(b.classes[0]) ?? 0) + b.count);
+    libraryImportant.files.set(b.file, (libraryImportant.files.get(b.file) ?? 0) + b.count);
+  }
   return {
     tokenFile,
     namespaces,
@@ -650,10 +698,17 @@ export function harvestTokens(root, styleFiles, codeFiles) {
       arbitrary: twArbitrary.toJSON(),
     },
     important: {
+      // aimed at a library's own class names: kept out, named at the top
+      library: {
+        count: libraryImportant.count,
+        classes: [...libraryImportant.classes.entries()].sort((a, b) => b[1] - a[1]).slice(0, 4).map(([value, count]) => ({ value: `.${value}`, count })),
+        files: [...libraryImportant.files.entries()].sort((a, b) => b[1] - a[1]).slice(0, 4).map(([file, count]) => ({ file, count })),
+      },
       count: [...importantFiles.values()].reduce((a, b) => a + b, 0),
       files: [...importantFiles.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6)
         .map(([file, count]) => ({ file, count })),
     },
+    exemptFiles: [...exemptFiles, ...mediumFiles],
     inlineStyles: {
       count: inlineStyleCount,
       files: [...inlineStyleFiles.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)

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

@@ -24,6 +24,10 @@
  * lines), so both give the same answer about the same file.
  */
 export const EMAIL_PRINT_RE = /email|(^|[/.])print([/.]|$)/i;
+// Next.js's crash page replaces the root layout, so the app's stylesheet
+// never loads there: Next.js tells developers to build it self-contained,
+// styling written on the elements. The medium, not a lapse (2026-09-13).
+export const CRASH_PAGE_RE = /(^|\/)global-error\.(tsx|jsx)$/;
 export const ARTWORK_NAME_RE = /(^|\/)[\w.-]*(icon|logo|badge|illustration|shield|artwork|graphic|background)[\w.-]*\.(tsx|jsx)$/i;
 export const SVG_MARKUP_RE = /<(svg|path|rect|circle|ellipse|polygon|defs|mask)\b/i;
 export const RENDER_TO_IMAGE_RE = /ImageResponse|from ['"]satori['"]|from ['"]@react-pdf|next\/og/;
@@ -42,9 +46,21 @@ export const svgHeavy = (text) =>
 export function exemptReason(file, text = '') {
   if (!file) return null;
   if (EMAIL_PRINT_RE.test(file)) return 'email and print styling has to be inline, because there is no cascade to inherit';
+  if (CRASH_PAGE_RE.test(file)) return 'the crash page replaces the root layout, so the stylesheet never loads there and its styling has to be inline';
   if (RENDERER_PATH_RE.test(file)) return 'a renderer draws pixels, so its colours are the picture rather than the interface';
   if (OG_ROUTE_RE.test(file) || RENDER_TO_IMAGE_RE.test(text)) return 'a render-to-image surface accepts nothing but inline styling, so there is no on-system way to write one';
   if (svgHeavy(text)) return 'the file is mostly drawing rather than styling';
   if (ARTWORK_NAME_RE.test(file) && SVG_MARKUP_RE.test(text)) return 'the colours belong to the artwork, not to the interface';
   return null;
 }
+
+/**
+ * Class names a library ships and the team can only shout over: a code
+ * editor, a date picker, a grid, an emoji picker, a docs theme. An !important
+ * on a selector made only of these, none of which the team writes in its own
+ * code, is the medium rather than the mess (fleet probe 2026-09-13: 30% of
+ * all !important, the tile keeps its spread). Prefix match, by name, so the
+ * report can say which library. Extend as the fleet shows new ones.
+ */
+export const LIBRARY_CLASS_RE = /^(cm-|ͼ|ProseMirror|monaco-|sp-|react-datepicker|react-tel-input|DateInput_|DayPicker|react-grid-|react-resizable|react-flow|react-select|react-toastify|Toastify|select2|EmojiPickerReact|epr-|notion-|fc-|fc$|tippy-|hljs|language-|ps__|ace_|ng-|docsearch|DocSearch|grecaptcha|rr-|sbdocs|docs-story|mapboxgl-|leaflet-|swiper-|slick-|rc-|ant-|Mui|ck-|ql-|tox-|mce-|DraftEditor|public-Draft|w-md-editor|rdp-|recharts-|apexcharts-|intercom-|crisp-|hubspot|shiki|katex|mermaid|prism-)/;
+export const isLibraryClass = (c) => LIBRARY_CLASS_RE.test(c);

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

@@ -7,7 +7,18 @@
  * plan. Born from the first user feedback (Willem, 2026-08-31).
  */
 
-export function fixPrompt({ title, sub, deltaText, repoName }) {
+// The two mistakes an agent chasing points makes (three repos, 2026-09-13):
+// repainting a picture to a grey, and rounding a width another element
+// depends on. Named in the prompt for the moves where they happen.
+const TRAP_LINES = {
+  paintTin: '- A gradient, an illustration or a status colour keeps its colour. Add a variable for it rather than swapping it to a grey; the swap is for text, borders and surfaces.',
+  colors: '- A gradient, an illustration or a status colour keeps its colour. Add a variable for it rather than swapping it to a grey; the swap is for text, borders and surfaces.',
+  arbitrary: '- Never round a width or height another element depends on: a preview panel, a skeleton that mirrors a chart, an editor pane. Name it if it repeats; leave it if it is one.',
+  spacing: '- Never round a width or height another element depends on: a preview panel, a skeleton that mirrors a chart, an editor pane. Name it if it repeats; leave it if it is one.',
+};
+
+export function fixPrompt({ title, sub, deltaText, repoName, metric = null }) {
+  const trap = TRAP_LINES[metric] ? `\n${TRAP_LINES[metric]}` : '';
   return `You are fixing one design-system finding in ${repoName ? `the ${repoName} repository` : 'this repository'}, measured by roast-my-design-system.
 
 The finding: ${title}
@@ -18,7 +29,7 @@ How to fix it, calmly and with respect for intent:
 - A value used many times is a decision without a name, not a mistake. Name it and consolidate; never blind-delete.
 - Small pixel nudges and one-off layout widths can be deliberate craft. Keep the deliberate exceptions; round the accidents to a neighbouring step.
 - Prefer the tokens, scale steps and canonical components this repository already has over inventing new ones.
-- Keep every change mechanical and reviewable. No redesigns, no drive-by refactors, no renamed files unless the finding asks for it.
+- Keep every change mechanical and reviewable. No redesigns, no drive-by refactors, no renamed files unless the finding asks for it.${trap}
 
 Work through the files named in the finding. When you are done, re-run the scan to verify the payoff:
 

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

@@ -25,6 +25,20 @@ const TICK_RE = /`<?([A-Z][A-Za-z0-9]{3,})>?`/g;
 // --apply trigger the staleness alarm on itself. In our content, only path
 // claims are checked (they rot for real); component-usage claims are not.
 const OURS_RE = /roast-my-design-system/i;
+// A rules file a tool wrote for itself (a lint preset's rule pack, the
+// Next.js agent block): its stale lines are the tool's, not the team's, so
+// the report names the tool instead of saying "your agent rules".
+const GENERATORS = [
+  [/ultracite/i, 'Ultracite'],
+  [/nextjs-agent-rules|NEXT-AGENTS-MD/, 'Next.js'],
+  [/\bbiome\b/i, 'Biome'],
+  [/generated by ([\w@/.-]+)/i, null],
+];
+function generatorOf(text) {
+  const head = text.slice(0, 600);
+  for (const [re, name] of GENERATORS) { const m = head.match(re); if (m) return name ?? m[1]; }
+  return null;
+}
 const BLOCK_RE = /<!-- roast-my-design-system:rules:begin[\s\S]*?roast-my-design-system:rules:end -->/g;
 
 function ruleTexts(root) {
@@ -33,7 +47,7 @@ function ruleTexts(root) {
   // the file minus our injected block, and component checks run only on it.
   const push = (file, text) => {
     const handWritten = text.replace(BLOCK_RE, '');
-    texts.push({ file, text, handWritten, ours: OURS_RE.test(handWritten) });
+    texts.push({ file, text, handWritten, ours: OURS_RE.test(handWritten), tool: generatorOf(text) });
   };
   for (const f of AGENT_FILES) {
     const p = join(root, f);
@@ -79,16 +93,16 @@ export function ruleStaleness(root, components, neverImportedNames = new Set(),
   }
   const findings = [];
   const seen = new Set();
-  const add = (file, ref, kind, problem) => {
+  const add = (file, ref, kind, problem, tool = null) => {
     const key = `${ref}|${problem}`;
     if (seen.has(key) || findings.length >= MAX_FINDINGS) return;
     seen.add(key);
-    findings.push({ file, ref, kind, problem });
+    findings.push({ file, ref, kind, problem, ...(tool ? { tool } : {}) });
   };
   const isPlaceholder = (ref) => ref.split('/').some((seg) => PLACEHOLDER_SEG.test(seg));
   const existsAsSuffix = (ref) => fileSuffixes.some((f) => f === ref || f.endsWith(`/${ref}`));
 
-  for (const { file, text, handWritten, ours } of ruleTexts(root)) {
+  for (const { file, text, handWritten, ours, tool } of ruleTexts(root)) {
     for (const m of text.matchAll(PATH_RE)) {
       const ref = m[1].replace(/^\.\//, '');
       if (isPlaceholder(ref)) continue;
@@ -98,7 +112,7 @@ export function ruleStaleness(root, components, neverImportedNames = new Set(),
       // a short test-file ref is almost surely package-relative and unverifiable;
       // a deep root-relative one was checked by existsSync above and is real drift
       if (UNVERIFIABLE_RE.test(ref) && ref.split('/').length < 4) continue;
-      add(file, ref, 'path', 'missing');
+      add(file, ref, 'path', 'missing', tool);
     }
     if (ours) continue; // fully generated file: paths checked above, component claims are ours to regenerate, not to second-guess
     const compRefs = new Set();

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

@@ -1,7 +1,7 @@
 // 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 = '7.4.0';
+export const VERSION = '7.5.0';
 // The shape of harvest.json and summary.json. Bumped only when a field is
 // renamed, removed or changes meaning; a new field is not a new schema. A
 // tool comparing two scans compares like with like by this number, not by VERSION.

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

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 /**
  * Profiles — what kind of repo is this, decided once and read everywhere.
  *
@@ -138,3 +140,74 @@ export function splitArbitrary(entries, dirs) {
   const values = [...installedValues.entries()].sort((a, b) => b[1] - a[1]).map(([value, count]) => ({ value, count }));
   return { own, installed: { uses: installedUses, values } };
 }
+
+/**
+ * A fresh kit: the shadcn install command's output with nothing built on it
+ * yet (Greg, 2026-09-12). Four absence checks and one presence check, all
+ * from facts already harvested; all five must hold. Decided once here, so the
+ * report, the rules file and the summary read one flag. When it holds the
+ * copy says "the score is the kit's, not yours" instead of narrating the
+ * catalogue's internal wiring as the team's habits.
+ *
+ * "Untouched" means untouched by these measures: a door edited by hand is
+ * invisible here, so the wording says "theme file untouched", never
+ * "components untouched".
+ */
+// what the install command writes around the catalogue, by file stem
+const SCAFFOLD_STEMS = new Set([
+  'layout', 'page', 'loading', 'error', 'not-found', 'template', 'globals',
+  'utils', 'use-mobile', 'theme-provider', 'providers', 'main', 'app', 'index',
+  'root', '__root', 'routes', 'router', 'vite-env.d', 'next-env.d', 'env.d',
+  'middleware', 'proxy', 'instrumentation',
+]);
+export function decideFresh(profile, components, files, tokens, root = null) {
+  const P = profileOf(profile);
+  if (!P.isShadcn || !profile.shadcn) return;
+  const sc = profile.shadcn;
+  const dirs = installedDirs(P);
+  const own = (files.code ?? []).filter((f) => /\.[jt]sx?$/.test(f) && !underAny(f, dirs));
+  // build config at the root (next.config, vite.config, tailwind.config) is scaffold too
+  const stem = (f) => f.split('/').pop().replace(/\.[jt]sx?$/, '').replace(/^[\w-]+\.config$/, 'app');
+  const ownComponents = (components ?? []).filter((c) => !c.isPage && !underAny(c.file, dirs));
+  const ownArbitrary = splitArbitrary(tokens?.tailwind?.arbitrary ?? [], dirs).own.reduce((s, a) => s + a.count, 0);
+  const ownInline = (tokens?.inlineStyles?.files ?? []).filter((f) => !underAny(f.file ?? f, dirs)).length;
+  // the demo page the install command writes shows one Button; a page that
+  // composes several doors is a screen someone built
+  const ownPages = (components ?? []).filter((c) => c.isPage && !underAny(c.file, dirs)).map((c) => c.file);
+  const doorImports = (f) => {
+    if (!root) return 0;
+    let src = '';
+    try { src = readFileSync(join(root, f), 'utf8'); } catch { return 0; }
+    return (src.match(/from\s+["'][^"']*\/ui\/[\w-]+["']/g) ?? []).length;
+  };
+  const checks = {
+    // 1. nothing of the team's own: every non-page component lives in a scaffold file
+    noOwnComponents: ownComponents.every((c) => SCAFFOLD_STEMS.has(stem(c.file))),
+    // 2. own code carries no colour, bracket or inline style
+    ownCodeClean: (sc.paintOwn?.tin?.uses ?? 0) === 0 && (sc.paintOwn?.doors?.uses ?? 0) === 0 && ownArbitrary === 0 && ownInline === 0,
+    // 3. the theme file is stock: every shadcn row, no custom row, --spacing untouched
+    sheetStock: sc.sheet?.found === true && (sc.sheet.custom ?? []).length === 0 && (sc.sheet.shadcnMissing ?? []).length === 0 && !sc.sheet.spacingChanged,
+    // 4. nothing installed beside the catalogue: no registries, no kit blocks
+    catalogueOnly: (sc.registryDirs ?? []).length === 0 && (sc.blockFiles ?? []).length === 0,
+    // 5. the reverse check: own code IS the scaffold, by name and by size
+    scaffold: own.length > 0 && own.length <= 10 && own.every((f) => SCAFFOLD_STEMS.has(stem(f)))
+      && ownPages.length <= 1 && ownPages.every((f) => doorImports(f) <= 1),
+  };
+  sc.fresh = {
+    fresh: Object.values(checks).every(Boolean),
+    checks,
+    ownFiles: own,
+    catalogueCount: (sc.installs ?? []).reduce((s, i) => s + (i.catalogueNames ?? 0), 0),
+  };
+}
+
+/** Off-scale spacing entries the team wrote (installed folders kept out on a kit). */
+export function ownSpacing(h) {
+  const P = profileOf(h);
+  const css = h.tokens?.spacing ?? [];
+  const tw = (h.tokens?.tailwind?.spacing ?? []).filter((v) => v.value.startsWith('['));
+  if (!P.isShadcn) return { css, tw, installed: { uses: 0, values: [] } };
+  const dirs = installedDirs(P);
+  const a = splitArbitrary(css, dirs), b = splitArbitrary(tw, dirs);
+  return { css: a.own, tw: b.own, installed: { uses: a.installed.uses + b.installed.uses, values: [...a.installed.values, ...b.installed.values].sort((x, y) => y.count - x.count) } };
+}

package/skills/roast-my-design-system/scripts/profiles/shadcn.mjs

@@ -33,6 +33,11 @@ import { CATALOGUE, BLOCK_COMPONENTS, REGISTRY_DIRS, KNOWN_ROWS, TWEAKCN_ROWS, L
 const readJSON = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
 const read = (p) => { try { return readFileSync(p, 'utf8'); } catch { return ''; } };
 const stripExt = (f) => f.replace(/\.[cm]?[jt]sx?$/, '');
+// A door is a file named after the component, or a folder named after it
+// holding an index file (formbricks: button/index.tsx). doorDir is the
+// catalogue folder the door sits in, either way.
+export const doorName = (f) => { const st = stripExt(basename(f)); return st === 'index' ? basename(dirname(f)) : st; };
+const doorDir = (f) => (stripExt(basename(f)) === 'index' ? dirname(dirname(f)) : dirname(f));
 
 /**
  * Every folder in the walk holding 8+ catalogue door names AND the marks of
@@ -47,8 +52,8 @@ function catalogueSweep(root, files) {
   const byDir = new Map();
   for (const f of files.code) {
     if (!/\.[jt]sx$/.test(f)) continue;
-    const d = dirname(f);
-    if (!CATALOGUE.has(stripExt(basename(f)))) continue;
+    const d = doorDir(f);
+    if (!CATALOGUE.has(doorName(f))) continue;
     const e = byDir.get(d) ?? { names: 0, marked: 0 };
     e.names += 1;
     if (e.marked < 3 && SHADCN_CODE_RE.test(read(join(root, f)))) e.marked += 1;
@@ -104,11 +109,17 @@ function resolveAlias(root, wsRoot, alias) {
 const CONTRACT_ROWS = ['background', 'foreground', 'primary', 'muted', 'border', 'ring', 'accent', 'card', 'popover', 'destructive'];
 function themeContract(root, files) {
   const seen = new Set();
+  let best = null, bestCount = 0;
   for (const f of (files.styles ?? []).slice(0, 60)) {
     const css = read(join(root, f));
-    for (const r of CONTRACT_ROWS) if (!seen.has(r) && new RegExp(`--${r}\\s*:`).test(css)) seen.add(r);
-    if (seen.size === CONTRACT_ROWS.length) break;
+    let here = 0;
+    for (const r of CONTRACT_ROWS) if (new RegExp(`--${r}\\s*:`).test(css)) { seen.add(r); here += 1; }
+    // the file that carries most of the contract is the sheet when the
+    // config names one that is missing or empty (a starter that moved it)
+    if (here > bestCount) { best = f; bestCount = here; }
+    if (seen.size === CONTRACT_ROWS.length && bestCount === CONTRACT_ROWS.length) break;
   }
+  themeContract.file = best;
   return seen.size;
 }
 
@@ -130,7 +141,22 @@ function readSheet(root, wsRoot, cssPath, files = null) {
   const file = [join(wsRoot, cssPath), join(wsRoot, 'src', cssPath)].find((p) => existsSync(p));
   if (!file) return { file: cssPath, found: false };
   const css = read(file);
-  const light = rowsUnder(css, ':root'), dark = rowsUnder(css, '\\.dark');
+  let light = rowsUnder(css, ':root'), dark = rowsUnder(css, '\\.dark');
+  // Rows under a scoped selector instead of :root (a theme picker's
+  // [data-theme='x'] blocks, a widget's #id): the first block holding
+  // --background is the sheet, its .dark twin the evening values.
+  let scope = null;
+  if (!light.has('background')) {
+    for (const m of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+      const sel = m[1].trim().split(/\s*\n\s*/).pop();
+      if (!/--background\s*:/.test(m[2]) || sel.startsWith('@')) continue;
+      const rows = new Map();
+      for (const d of m[2].matchAll(/--([a-z0-9-]+)\s*:\s*([^;]+);/gi)) rows.set(d[1], d[2].trim());
+      if (/\.dark\b/.test(sel)) { if (!dark.has('background')) dark = rows; }
+      else if (!light.has('background')) { light = rows; scope = sel; }
+      if (light.has('background') && dark.has('background')) break;
+    }
+  }
   const themeInline = rowsUnder(css, '@theme\\s+inline');
   const rows = [...light.keys()];
   const known = rows.filter((r) => KNOWN_ROWS.has(r));
@@ -162,7 +188,7 @@ function readSheet(root, wsRoot, cssPath, files = null) {
     customUnused = [...pending];
   }
   return {
-    file: file.slice(root.length + 1), found: true, hslEra, customUnused,
+    file: file.slice(root.length + 1), found: true, scope, hslEra, customUnused,
     lightRows: rows.length, darkRows: dark.size, shadcnPresent, shadcnMissing: SHADCN_ROWS.filter((r) => !light.has(r)),
     known: known.length, custom, missingDark, customMissingDark, customUnregistered, tweakcnPresent,
     spacing, spacingChanged: spacing !== null && norm(spacing) !== FACTORY_SPACING,
@@ -220,6 +246,10 @@ export default {
       .map((f) => ({ file: f, cfg: readJSON(join(root, f)) }))
       .filter((c) => c.cfg && (c.cfg.aliases || c.cfg.style !== undefined || c.cfg.tailwind));
 
+    // the theme contract (5+ of shadcn's named variables in one stylesheet),
+    // computed once: the decision below reads the count, the sheet reader
+    // falls back to the file
+    const contract = themeContract(root, files);
     // 2. catalogues: through each config's alias, then a sweep for door names
     const installs = [];
     for (const { file, cfg } of configs) {
@@ -229,12 +259,18 @@ export default {
       let catalogueNames = 0;
       if (uiAbs) {
         const rel = uiAbs.slice(root.length + 1).replace(/\\/g, '/');
-        catalogueNames = files.code.filter((f) => f.startsWith(`${rel}/`) && CATALOGUE.has(stripExt(basename(f)))).length;
+        catalogueNames = files.code.filter((f) => f.startsWith(`${rel}/`) && CATALOGUE.has(doorName(f))).length;
         uiAbs = rel;
       }
       const pkg = readJSON(join(wsRoot, 'package.json')) ?? readJSON(join(root, 'package.json')) ?? {};
       const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
-      const sheet = readSheet(root, wsRoot, cfg.tailwind?.css, files);
+      let sheet = readSheet(root, wsRoot, cfg.tailwind?.css, files);
+      // the named sheet is missing or holds no rows: read the stylesheet that
+      // carries the theme contract instead, and say so
+      if ((!sheet?.found || sheet.lightRows === 0) && contract && themeContract.file) {
+        const fallback = readSheet(root, root, themeContract.file, files);
+        if (fallback?.found && fallback.lightRows > 0) sheet = { ...fallback, configured: cfg.tailwind?.css ?? null, configuredFound: sheet?.found === true };
+      }
       installs.push({ config: file, uiDir: uiAbs, catalogueNames, kit: readKit(cfg, sheet, deps), sheet });
     }
     const swept = catalogueSweep(root, files);
@@ -247,7 +283,6 @@ export default {
     // catalogue folder. Without it: a catalogue by name AND the theme contract
     // in a stylesheet (5 or more of shadcn's named variables); names and
     // Radix alone describe half the React world.
-    const contract = themeContract(root, files);
     const withConfigAndDir = installs.filter((i) => i.config && i.uiDir);
     const byName = installs.filter((i) => i.catalogueNames >= 8);
     if (!withConfigAndDir.length && !(byName.length && contract >= 5)) return null;
@@ -276,7 +311,7 @@ export default {
     const cssVars = kit ? kit.cssVariables : true;
     profile.designSystem = { kind: 'shadcn', name: 'shadcn/ui', confidence: 'high', cssVariables: cssVars };
     // kit doors installed as blocks into own code
-    const blockFiles = files.code.filter((f) => /\.[jt]sx$/.test(f) && !profile.uiDirs.some((d) => f.startsWith(`${d}/`)) && BLOCK_COMPONENTS.has(stripExt(basename(f))));
+    const blockFiles = files.code.filter((f) => /\.[jt]sx$/.test(f) && !profile.uiDirs.some((d) => f.startsWith(`${d}/`)) && BLOCK_COMPONENTS.has(doorName(f)));
     // third-party registries installed beside the catalogue: a folder named
     // as the CLI creates it, or as a `registries` key in components.json
     // names it. Installed code, judged like the catalogue.

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

@@ -8,7 +8,7 @@ import { distinctTypefaces } from '../lib/typefaces.mjs';
 import { nearColorPairs } from './../lib/nearpairs.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { VERSION } from '../lib/version.mjs';
-import { profileOf } from '../profiles/index.mjs';
+import { profileOf, installedDirs, splitArbitrary, ownSpacing } from '../profiles/index.mjs';
 
 export function rulesMarkdown(h, opts = {}) {
   // compact: the size-aware variant for agent files with tight practical
@@ -92,16 +92,18 @@ const repoName = h.profile?.name ?? 'this repo';
     .sort((a, b) => b.usageCount - a.usageCount).slice(0, CAP.components);
   if (top.length) {
     section('Canonical components');
-    rule(compact
+    const fresh = profileOf(h).shadcn?.fresh?.fresh === true;
+    rule(compact || fresh
       ? 'Use these existing components instead of writing new ones:'
       : 'Use these existing components instead of writing new ones, the way this repo already uses them:');
+    if (fresh && !compact) lines.push('  (No code of your own uses the kit yet. The counts below are the components using each other.)');
     for (const c of top) {
       const props = !compact && c.propsHint?.named?.length ? ` · props: ${c.propsHint.named.slice(0, 4).join(', ')}` : '';
       lines.push(`  - \`<${c.name}>\` from \`${c.file}\` (used ${c.usageCount}x${props})`);
       // Golden example: the repo's own most common real usage, quoted with a
       // receipt. Full variant only; compact hosts trade examples for size.
       const ex = c.usageExample;
-      if (!compact && ex) {
+      if (!compact && !fresh && ex) {
         lines.push(`    - most common usage, as in \`${ex.file}\` (matching ${ex.matches} of ${ex.total} usages): \`${ex.snippet}\``);
       }
     }
@@ -119,7 +121,9 @@ const repoName = h.profile?.name ?? 'this repo';
       const files = d.files.map((f) => (typeof f === 'string' ? f : f.file));
       const ranked = [...files].sort((a, b) => sharedScore(b) - sharedScore(a));
       const clear = sharedScore(ranked[0]) > sharedScore(ranked[1]);
-      if (d.wrapped) {
+      if (d.upstream) {
+        rule(`\`<${d.name}>\` is defined by two shadcn components (${files.map((f) => `\`${f}\``).join(', ')}), upstream's overlap. Import whichever the surrounding code already uses; do not create a third.`);
+      } else if (d.wrapped) {
         rule(`\`<${d.name}>\` is defined twice and one wraps the other${clear ? `. Import \`${ranked[0]}\`` : ''}; do not create a third.`);
       } else if (clear) {
         rule(`\`<${d.name}>\` exists in ${files.length} places. Treat \`${ranked[0]}\` as canonical; do not import the other ${files.length === 2 ? 'copy' : 'copies'}, and never create another.`);
@@ -146,9 +150,12 @@ if (neverImported.length >= 3) {
 }
 
 // ---------- spacing ----------
-  const arbitrary = t.tailwind?.arbitrary ?? [];
+  // On a kit the values inside installed folders are shadcn's own: the
+  // counts here are the team's, the shadcn section explains the rest.
+  const P0 = profileOf(h);
+  const arbitrary = P0.isShadcn ? splitArbitrary(t.tailwind?.arbitrary ?? [], installedDirs(P0)).own : (t.tailwind?.arbitrary ?? []);
   const arbCount = arbitrary.reduce((s, a) => s + a.count, 0);
-  const offScale = (t.spacing ?? []).length;
+  const offScale = ownSpacing(h).css.length;
   if (t.tailwind?.spacing?.length || offScale || arbCount) {
     section('Spacing and sizing');
     if (t.tailwind?.spacing?.length) rule('Stay on the Tailwind spacing scale. If a gap looks wrong on a scale step, flag it instead of nudging by a pixel.');
@@ -173,7 +180,8 @@ if (neverImported.length >= 3) {
     const paint = sc.paint ?? null;
     section('shadcn: the components and the theme');
     rule(`This is a shadcn install${sc.kit?.style ? ` (style \`${sc.kit.style}\`${sc.kit.baseColor ? `, base colour ${sc.kit.baseColor}` : ''})` : ''}. The theme is a set of CSS variables${sheetFile ? ` in \`${sheetFile}\`` : ''}: background, foreground, primary, muted, border and the rest, each with a light and a dark value. Change a colour there, never in a component.`);
-    rule('Use the semantic classes the theme gives you (`bg-background`, `text-muted-foreground`, `border-border`), never a palette colour like `bg-blue-500` or `text-gray-600`, and never a hand-written `dark:` colour. The variables already carry both modes.');
+    if ((sc.sheet?.shadcnPresent ?? 0) >= 5 || sc.kit?.cssVariables === false) rule('Use the semantic classes the theme gives you (`bg-background`, `text-muted-foreground`, `border-border`), never a palette colour like `bg-blue-500` or `text-gray-600`, and never a hand-written `dark:` colour. The variables already carry both modes.');
+    else rule(`${sheetFile ? `\`${sheetFile}\` defines` : 'The theme file defines'} none of shadcn's colour variables, so \`bg-background\` and \`text-muted-foreground\` have nothing behind them here. Until the theme variables are adopted, stay with the palette classes the surrounding file already uses; do not introduce semantic classes with no variable behind them, and do not add a second palette.`);
     if (paint?.tin?.uses) lines.push(`  (${paint.tin.uses} palette colour${paint.tin.uses === 1 ? '' : 's'} already sit in own code, ${paint.tin.samples.slice(0, 3).map((s) => `\`${s.value}\` ×${s.count}`).join(', ')}; do not add to them.)`);
     rule('Before adding classes to a shadcn component, use one of its variants (`variant="outline"`, `size="sm"`). `className` on a shadcn component is for layout only: width, margin, position. Never colour, never typography.');
     if (paint?.typo?.uses) lines.push(`  (${paint.typo.uses} shadcn component${paint.typo.uses === 1 ? '' : 's'} get a text size or weight through className, like ${paint.typo.samples.slice(0, 2).map((s) => `\`${s.value}\``).join(' and ')}; add a size variant instead.)`);