roast-my-design-system 5.12.0 → 5.12.2

package/README.md

@@ -33,23 +33,32 @@ Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in
 
 One scan powers all of it; the flags decide what lands on disk. Combine freely.
 
-| Command                                                             | What you get |
+**Run it yourself.** Type these in a terminal and you get a result.
+
+| Command | What you get |
 |---|---|
-| <code>npx&nbsp;roast-my-design-system@latest</code> | The scan and `design-system-roast.html`, opened in your browser |
-| <code>npx&nbsp;roast-my-design-system@latest&nbsp;&lt;path&gt;</code> | Scan a different repo than the current directory |
+| `npx roast-my-design-system@latest` | The scan and `design-system-roast.html`, opened in your browser |
+| `... <path>` | Scan a different repo than the current directory |
 | `... --apply` | The generated agent rules injected straight into every agent file you have: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.cursor/rules/`, `.windsurfrules` and `.github/copilot-instructions.md`, inside a marked block. Re-running replaces only that block, never your own text. Windsurf and Copilot get a compact variant sized for their limits |
 | `... --rules` | The same rules written to `design-system-rules.md` instead, for pasting by hand |
 | `... --card` | `roast-card.svg`: a shareable 1200x630 card with the score and worst findings. Pure SVG, embeds in a README |
 | `... --sarif` | `design-system-roast.sarif` for GitHub code scanning: upload it in CI and findings appear in the Security tab, annotated on files |
-| `... --mcp` | The scan as a local MCP server: 5 tools your agent calls while writing UI, from "is there a Button already?" to "review my changes", plus the `roast-fix` prompt that serves the top fix from a fresh scan. See [Live answers over MCP](#live-answers-over-mcp) |
 | `... --check` | The working tree's changed files checked against the design system, in the terminal. Exits 1 on findings, so it slots into scripts |
-| <code>...&nbsp;--by&nbsp;"Dwayne&nbsp;Hicks"</code> | A requester credit in the report header, next to the scan date |
-| <code>...&nbsp;--notes&nbsp;&lt;file.md&gt;</code> | An agent-written analysis embedded in the report as **"What the numbers mean"**: labelled as written by AI, kept apart from the measured numbers. The Claude Code skill writes and passes this automatically; the flag is here so any agent can |
-| <code>...&nbsp;--section&nbsp;"Title"&nbsp;&lt;file.md&gt;</code> | An agent-written chapter appended after the notes, same styling, same written-by-AI label, with sub-headings allowed. Repeatable, so analysis that outgrows the notes still lives inside the report instead of a hand-built page |
-| <code>...&nbsp;--exclude&nbsp;lab/</code> | Leave a folder out of the scan (repeat the flag or comma-separate). Or list folders in a `.roastignore` file at the repo root. Either way the report says so in the header; see [Scoping the scan](#scoping-the-scan) |
+| `... --exclude lab/` | Leave a folder out of the scan (repeat the flag or comma-separate). Or list folders in a `.roastignore` file at the repo root. Either way the report says so in the header; see [Scoping the scan](#scoping-the-scan) |
 | `... --json` | The scan summary as JSON on stdout, for scripts and pipelines |
-| <code>...&nbsp;--theme&nbsp;light</code>&nbsp;/ <code>--out&nbsp;&lt;file&gt;</code>&nbsp;/ <code>--no-open</code> | Light report, custom report path, don't open the browser |
-| <code>/roast-my-design-system</code> (in&nbsp;Claude&nbsp;Code) | The full experience: the roast in chat *and* embedded in the report as "What the numbers mean", the rules offer, and the fix loop with Claude on your own numbers |
+| `... --by "Dwayne Hicks"` | Puts a name in the report header, for when you ran it for someone else |
+| `... --theme light` / `--out <file>` / `--no-open` / `--open` | Light report, custom report path, never open the browser, always open it |
+
+**For your agent.** These need an agent: two of them carry writing only an agent can produce, and two are doors it works through rather than output you read.
+
+| Command | What you get |
+|---|---|
+| `... --notes <file.md>` | The agent's read of this scan, embedded in the report as **"What the numbers mean"**: which findings matter, which good numbers are accidents, what to fix first. Labelled as written by AI and kept apart from the measured numbers. The Claude Code skill writes and passes it automatically; the flag is here so any agent can |
+| `... --section "Title" <file.md>` | A further agent-written chapter after the notes, same styling, same label, sub-headings allowed. Repeatable, so analysis that outgrows the notes still lives inside the report instead of a hand-built page |
+| `... --mcp` | The scan as a local MCP server: 5 tools your agent calls while writing UI, from "is there a Button already?" to "review my changes", plus the `roast-fix` prompt that serves the top fix from a fresh scan. See [Live answers over MCP](#live-answers-over-mcp) |
+| `/roast-my-design-system` (in Claude Code) | The full experience: the roast in chat *and* embedded in the report as "What the numbers mean", the rules offer, and the fix loop with Claude on your own numbers |
+
+Not to be confused with each other: **"Why this matters"** is generic, ships with the tool and reads the same in every report. **"What the numbers mean"** is your agent's read of your repo, and only appears when an agent passed it.
 
 **One scan writes rules for every agent: Claude, Cursor, GitHub Copilot, and Windsurf.** Every scan also checks the agent rules you already have and flags stale references, no flag needed.
 
@@ -62,11 +71,11 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 
 The full report for vercel/ai-chatbot, top to bottom, including "What the numbers mean", Claude's read of the scan, embedded right under the verdict:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-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.12.0)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-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.12.2)
 
 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.12.0)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=5.12.2)
 
 ## What makes the numbers trustworthy
 

package/bin/roast.mjs

@@ -63,10 +63,13 @@ if (flag('help') || flag('h')) {
 
 Usage: npx roast-my-design-system@latest [path] [options]
 
+Run it yourself
+
   path            repo to scan (default: current directory)
   --theme <t>     dark | light (default: dark)
   --out <file>    report path (default: design-system-roast.html in the repo)
   --no-open       write the report without opening it
+  --open          open it even when the output is piped or an agent is running
   --rules         also write design-system-rules.md: agent rules (for
                   CLAUDE.md / .cursor/rules) generated from the scan
   --apply         inject the rules straight into your agent files (CLAUDE.md,
@@ -78,16 +81,8 @@ Usage: npx roast-my-design-system@latest [path] [options]
                   the score and worst findings (pure SVG, embeds in READMEs)
   --sarif         also write design-system-roast.sarif for GitHub code
                   scanning: findings annotated on files in the Security tab
-  --by <name>     put a requester credit in the report header, next to the
-                  scan date ("commissioned by <name>")
-  --notes <file>  embed an agent-written analysis (markdown-lite) in the
-                  report as "What the numbers mean", labelled as written by
-                  AI and kept apart from the measured numbers. The Claude
-                  Code skill writes and passes this automatically
-  --section "Title" <file>
-                  append an agent-written chapter after the notes, same
-                  markdown-lite plus "## " sub-headings, same written-by-AI
-                  label. Repeatable, one chapter per --section
+  --by <name>     put a name in the report header, for when you ran it for
+                  someone else ("commissioned by <name>")
   --exclude <p>   leave a folder out of the scan (repo-relative, e.g.
                   --exclude lab/ --exclude piglet/ or --exclude lab/,piglet/;
                   same as listing it in a .roastignore file at the repo root).
@@ -97,6 +92,17 @@ Usage: npx roast-my-design-system@latest [path] [options]
   --check         check the working tree's changed files (git diff + untracked)
                   against the design system and print the findings; exits 1
                   when something is over the line, so it composes with scripts
+
+For your agent (a plain terminal has no agent to write these)
+
+  --notes <file>  the agent's read of this scan, embedded in the report as
+                  "What the numbers mean", labelled as written by AI and kept
+                  apart from the measured numbers. The Claude Code skill
+                  writes and passes this automatically
+  --section "Title" <file>
+                  a further agent-written chapter after the notes, same
+                  markdown-lite plus "## " sub-headings, same label.
+                  Repeatable, one chapter per --section
   --mcp           run as a local MCP server (stdio) so your agent can query
                   the design system live: context, canonical components,
                   tokens, validation. Add to your client, e.g. Claude Code:
@@ -133,12 +139,38 @@ const wantApply = flag('apply') === true;
 const wantCard = flag('card') === true;
 const wantSarif = flag('sarif') === true;
 const asJson = flag('json') === true;
-const noOpen = flag('no-open') === true || asJson;
+// Opening a browser tab is a courtesy to a person watching a terminal. When
+// an agent runs the scan (Claude Code, Cursor, Codex) it captures stdout, so
+// there is no terminal and no one to look — and an agent verifying a fix runs
+// this repeatedly, throwing a tab in the user's face each time (Greg, working
+// through the fix loop, 2026-09-10). No TTY, no tab. `--open` forces it back
+// for anyone piping output who still wants the report.
+const interactive = process.stdout.isTTY === true && !process.env.CI;
+const forceOpen = flag('open') === true;
+// flag() consumes the argument, so ask once and keep the answer.
+const askedNoOpen = flag('no-open') === true;
+const noOpen = askedNoOpen || asJson;
 const theme = opt('theme', 'dark');
 const commissionedBy = opt('by', null);
 const notesFile = opt('notes', null);
 const sections = optPairs('section');
 const excludes = optAll('exclude');
+// Reject an unreadable --notes / --section before scanning, not after: the
+// scan is the expensive part, and dying on a flag once the work is done is
+// the rudest possible order (Greg watched it happen, 2026-09-10). diagnose
+// checks these too; this is the early door with the same words.
+for (const [flagName, file] of [
+  ...(notesFile ? [['--notes', notesFile]] : []),
+  ...sections.map(([, f]) => ['--section', f]),
+]) {
+  if (existsSync(resolve(file))) continue;
+  console.error(`${flagName}: cannot read ${file}
+  ${flagName} is for an agent to pass: the file holds its writing about this
+  scan, which the report embeds. Running by hand? Leave the flag off, or use
+  the Claude Code skill, which writes it for you.`);
+  process.exit(1);
+}
+
 const target = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());
 if (!existsSync(target) || !statSync(target).isDirectory()) {
   console.error(`Not a directory: ${target}`);
@@ -162,6 +194,16 @@ function run(script, args, env) {
 const say = (s) => { if (!asJson) console.log(s); };
 
 say(`roast-my-design-system ${VERSION} · read-only scan, nothing leaves your machine`);
+// The score this repo had last time, read from the report about to be
+// overwritten. It decides whether a browser tab is worth throwing at anyone:
+// an agent working a fix runs the scan repeatedly, and only the run that
+// actually moves the number is worth looking at.
+let previousScore = null;
+try {
+  const prev = readFileSync(outPath, 'utf8').match(/<!-- rmds-score: (\d+|na) -->/);
+  if (prev) previousScore = prev[1];
+} catch { /* no previous report: this is the first look, so it is worth opening */ }
+
 // the harvest goes to a temp dir this wrapper deletes right after; tell the
 // script so it does not print a path that will be gone seconds later
 run('harvest/index.mjs', [target, '--out', harvestPath,
@@ -239,7 +281,20 @@ if (!asJson) {
   say(`\n${FEEDBACK_ASK} ${FEEDBACK_CTA}:\n${feedbackUrl(VERSION)}\n${STAR_ASK} ${STAR_CTA}:\n${STAR_URL}`);
 }
 
-if (!noOpen) {
+// A person at a terminal asked for this, so they get the report. An agent
+// did not: it gets the tab only when the number moved, which is the moment
+// worth seeing (Greg, working a fix loop through Claude Code, 2026-09-10 —
+// several windows opened while the agent was still working).
+// `summary` was parsed before the temp dir was removed; reading the file
+// here would find nothing.
+const currentScore = summary?.score === undefined || summary?.score === null ? null : String(summary.score);
+const scoreMoved = previousScore === null || (currentScore !== null && currentScore !== previousScore);
+const quietRun = !interactive && !forceOpen && !scoreMoved;
+if (quietRun && !asJson && !askedNoOpen) {
+  console.log(`\n  (score unchanged at ${currentScore ?? '?'}, so no browser tab. Add --open if you want one.)`);
+}
+
+if (!noOpen && !quietRun) {
   // Windows: `start` treats a first quoted arg as the window TITLE, and Node
   // quotes paths containing spaces — pass an empty title so the path lands
   // in the file slot. Linux: xdg-open may be absent (headless, WSL); the

package/package.json

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

@@ -138,7 +138,16 @@ const notesPath = arg('notes', null);
 let notesText = null;
 if (notesPath) {
   try { notesText = readFileSync(resolve(notesPath), 'utf8').trim() || null; }
-  catch { console.error(`--notes: cannot read ${notesPath}`); process.exit(1); }
+  catch {
+    // Typed by hand more often than not: the flag reads like "add a note",
+    // but the file holds an agent's analysis of this scan, and a plain
+    // terminal has no agent to write one (Greg, 2026-09-10).
+    console.error(`--notes: cannot read ${notesPath}
+  --notes is for an agent to pass: the file holds its read of this scan,
+  which the report embeds as "What the numbers mean". Running by hand?
+  Leave the flag off, or use the Claude Code skill, which writes it for you.`);
+    process.exit(1);
+  }
 }
 
 // --section "Title" file.md, repeatable; unreadable files are hard errors for
@@ -152,7 +161,12 @@ for (let i = 3; i < process.argv.length; i++) {
   }
   let text;
   try { text = readFileSync(resolve(file), 'utf8').trim(); }
-  catch { console.error(`--section: cannot read ${file}`); process.exit(1); }
+  catch {
+    console.error(`--section: cannot read ${file}
+  --section is for an agent to pass: the file holds a chapter it wrote,
+  rendered inside the report. Running by hand? Leave the flag off.`);
+    process.exit(1);
+  }
   if (text) extraSections.push({ title, text });
   i += 2;
 }
@@ -1649,6 +1663,7 @@ const html = `<!doctype html>
   .author:hover { text-decoration:underline; }
 </style>
 <!-- rmds-schema: ${NS_TAG} -->
+<!-- rmds-score: ${healthScore ?? 'na'} -->
 </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){}})()">
   <span class="tt-lab tt-day">Day</span>

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.12.0';
+export const VERSION = '5.12.2';