stylelint-plugin-rhythmguard 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-09-05
+
+### Added
+
+- Added `scale: "auto"` to `rhythmguard/use-scale`, `rhythmguard/no-offscale-transform` and `rhythmguard/prefer-token`. The scale is inferred from spacing tokens: `scaleSources` files, then `.rhythmguardrc.json` audit token sources, then the linted stylesheet's custom properties, then `tailwindConfigPath`, with a `rhythmic-4` fallback that is announced in the first report of the file. First matching source wins.
+- Added the `scaleSources` rule option and made `tailwindConfigPath` available to every scale rule.
+- Added `rhythmguard audit --scale auto`, which infers one project-level scale from token sources, then spacing custom properties across the scanned CSS, then the default. The JSON contract now carries `contracts.scale.values`, `source` and `files`; text and Markdown output print the scale and its source.
+- Added the quiet benchmark (`npm run bench:quiet`): audits public design systems with `--scale auto`, classifies findings as drift, noise or allowance, and writes `docs/QUIET_BENCHMARK.md` with a per-repo false-positive rate. Manifest and classification rules live in `benchmarks/quiet/`.
+- Scale inference now reads token values written as `calc(<length> * var(--factor))` (Radix Themes), expands a bare Tailwind v4 `--spacing` base into the default multiplier scale, and matches prefixed spacing tokens such as `--lb-spacing-md` while excluding `letter-spacing` and `word-spacing`.
+
+- Added `docs/FOR_AGENTS.md` with a paste-ready `AGENTS.md` block and the commands a coding agent should run, and a "what it is not" paragraph at the top of the README (no color checking, class strings need the ESLint companion, no SCSS in the audit).
+- The quiet benchmark now pins each repository to a recorded commit and keeps snapshots of its findings under `benchmarks/quiet/snapshots/`. `npm run bench:quiet -- --check` fails when the finding set or the inferred scale changes, `--update-snapshots` accepts a reviewed change, `--latest` audits upstream heads. A farm workflow runs the check on every change and the upstream run weekly.
+- `npx rhythmguard` with no command now runs a zero-config quickstart: detects Tailwind (and its major version), Next.js, an existing Stylelint config and token files; infers the spacing scale from the project's own tokens; audits the current directory; and prints the exact `.stylelintrc.json` (plus an ESLint snippet for Tailwind) to paste. `--help` is unchanged; `rhythmguard quickstart` is an explicit alias.
+- Added `stylelint-plugin-rhythmguard/configs/embed`: `use-scale` at warning level with `scale: "auto"`, no `extends`, shape frozen for 2.x. The entry point for shared-config authors who want to enable spacing governance for their consumers without knowing each consumer's scale. Guide in `docs/FOR_CONFIG_AUTHORS.md`.
+- Added `allowHairlines` (default `true`) to `use-scale`, `no-offscale-transform` and `prefer-token`. Non-zero lengths that resolve to one CSS pixel or less (`1px`, `-1px`, `0.5px`, `0.0625rem`) are exempt: they compensate for borders and rendering, not spacing. The quiet benchmark showed them to be the only systematic false positive left across Radix Themes, Mantine, Primer React and Liveblocks. Set `allowHairlines: false` to restore the previous reports.
+
+### Fixed
+
+- `rhythmguard/prefer-token` no longer reports percentages such as `translate(-50%, -50%)` or `inset: 100%` as raw scale values. Percentages are never token candidates. This was the largest noise source in the quiet benchmark.
+- `rhythmguard/use-scale` with `allowPercentages: false` now reports percentage lengths instead of silently skipping them.
+
 ## [2.1.0] - 2026-09-05
 
 ### Added

package/CONTRIBUTING.md

@@ -72,6 +72,7 @@ When changing rule logic:
 2. validate deterministic fix behavior
 3. update the rule's page in `docs/rules/` if options or behavior changed
 4. update CHANGELOG
+5. run the quiet benchmark: `npm run bench:quiet -- --check`. It audits real public design systems at pinned commits and fails when the finding set or the inferred scale changes. If the change is intended, review the printed diff, run `npm run bench:quiet -- --update-snapshots`, and commit `benchmarks/quiet/snapshots/` with a sentence in the PR on why the new findings are right. CI runs the same check.
 
 ## Release Workflow
 

package/README.md

@@ -13,7 +13,15 @@ Spacing scale and design-token governance for CSS and Tailwind. `padding: 13px`
 
 Rhythmguard is scale-aware rather than a blanket ban: values on your scale pass, values off it are reported with the two nearest steps, and tokens are only ever suggested from a map you control. It works on CSS declarations through Stylelint and on Tailwind class strings through an ESLint companion, and it ships an audit CLI so you can measure drift and ratchet it down before enforcing anything.
 
-## Install
+What it is not: it does not check colors or hex values, the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below), and it does not parse SCSS in the audit. Pair it with a color linter if you need one; do not expect one tool to do both.
+
+## Start here
+
+```bash
+npx rhythmguard
+```
+
+No install, no config. It detects your stack and token files, infers your spacing scale from your own tokens, audits the current directory, and prints the exact `.stylelintrc.json` (and ESLint snippet for Tailwind) to paste. Then:
 
 ```bash
 npm install --save-dev stylelint stylelint-plugin-rhythmguard
@@ -62,7 +70,7 @@ Every rule validates its options up front. Unknown option names and wrong shapes
 
 ## Configs
 
-`recommended`, `strict`, `tailwind`, `react-tailwind`, `expanded`, `logical`, `migration`, `motion`. All are `stylelint-plugin-rhythmguard/configs/<name>`. What each enables, the full custom setup, and the scale-selection precedence are in [docs/CONFIGS.md](docs/CONFIGS.md). Built-in and community scale presets are in [docs/SCALE_PRESETS.md](docs/SCALE_PRESETS.md).
+`recommended`, `strict`, `tailwind`, `react-tailwind`, `expanded`, `logical`, `migration`, `motion`, and `embed` for authors of shared configs (see [docs/FOR_CONFIG_AUTHORS.md](docs/FOR_CONFIG_AUTHORS.md)). All are `stylelint-plugin-rhythmguard/configs/<name>`. What each enables, the full custom setup, and the scale-selection precedence are in [docs/CONFIGS.md](docs/CONFIGS.md). Built-in and community scale presets are in [docs/SCALE_PRESETS.md](docs/SCALE_PRESETS.md).
 
 ## Audit before you enforce
 
@@ -83,6 +91,9 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 - [Framework setup](docs/FRAMEWORKS.md) for Vue, Lit, Astro and SvelteKit
 - [Comparison with adjacent plugins](docs/COMPARISON.md) and migration recipes
 - [Real before/after excerpts](docs/ADOPTION_DIFFS.md) from public codebases
+- [For shared-config authors](docs/FOR_CONFIG_AUTHORS.md): the `embed` entry point and how inference works per consumer
+- [For coding agents](docs/FOR_AGENTS.md): a paste-ready `AGENTS.md` block and the commands to run
+- [Quiet benchmark](docs/QUIET_BENCHMARK.md): findings on public design systems, checked on every change
 - [Product direction](docs/STRATEGY_2026-09.md)
 - Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Token governance for CSS and Tailwind — enforce spacing scales, require design tokens, catch arbitrary values",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -32,6 +32,11 @@
       "require": "./src/configs/recommended.js",
       "import": "./src/configs/recommended.mjs"
     },
+    "./configs/embed": {
+      "types": "./types/config.d.ts",
+      "require": "./src/configs/embed.js",
+      "import": "./src/configs/embed.mjs"
+    },
     "./configs/strict": {
       "types": "./types/config.d.ts",
       "require": "./src/configs/strict.js",
@@ -118,6 +123,7 @@
   "scripts": {
     "bench:perf": "node scripts/bench/compare.mjs",
     "bench:perf:fix": "node scripts/bench/compare.mjs --fix",
+    "bench:quiet": "node scripts/bench/quiet.mjs",
     "lint": "eslint .",
     "scales:add": "node scripts/scales/add-scale.mjs",
     "scales:validate": "node scripts/scales/validate-community-scales.mjs",

package/src/audit/args.js

@@ -36,7 +36,8 @@ Options:
   --token-source-format <format> Token source format: auto, css, flat-json, style-dictionary, dtcg (default: auto)
   --token-kind <kind>            Token kind: spacing, radius, typography, size, motion, all (default: spacing)
   --token-candidate-min-count <n> Minimum repeated raw value count for token candidates (default: 2)
-  --scale <values>               Comma-separated scale values (default: 0,4,8,12,16,24,32)
+  --scale <values|auto>          Comma-separated scale values (default: 0,4,8,12,16,24,32);
+                                 auto infers the scale from token sources, then scanned CSS
   --base-font-size <number>      px base for rem/em conversion (default: 16)
 `;
 
@@ -406,6 +407,10 @@ function parseScale(raw) {
     throw new Error('Missing value for --scale.');
   }
 
+  if (raw.trim().toLowerCase() === 'auto') {
+    return 'auto';
+  }
+
   const scale = raw.split(',')
     .map((part) => part.trim())
     .filter(Boolean)

package/src/audit/config.js

@@ -134,11 +134,21 @@ function parseBooleanOption(value, optionName) {
 }
 
 function normalizeCliTokenSources(sources, format) {
-  return sources.map((sourcePath) => ({
-    baseDir: process.cwd(),
-    format,
-    path: sourcePath,
-  }));
+  return sources.map((source) => {
+    // The programmatic API may pass typed { path | file, format?, baseDir? } entries.
+    if (source && typeof source === 'object') {
+      return {
+        baseDir: source.baseDir || process.cwd(),
+        format: source.format || format,
+        path: source.path || source.file,
+      };
+    }
+    return {
+      baseDir: process.cwd(),
+      format,
+      path: source,
+    };
+  });
 }
 
 function normalizeConfigTokenSources(sources, baseDir) {

package/src/audit/contract.js

@@ -243,6 +243,7 @@ function buildReport({
   externalTokenDefinitions,
   includeMotion,
   motionFindings,
+  scale,
   scanScope,
   templateFiles,
   tailwindFindings,
@@ -306,6 +307,7 @@ function buildReport({
       values: Object.fromEntries(sortCountMap(motionValues).slice(0, 10)),
     },
     offScaleValues: Object.fromEntries(sortCountMap(offScaleValues).slice(0, 10)),
+    scale: scale || null,
     scaleCleanliness,
     scanScope,
     scanned: {
@@ -370,8 +372,11 @@ function toAuditContractReport(report) {
       motion: report.motion,
       scale: {
         cleanliness: report.scaleCleanliness,
+        files: report.scale ? report.scale.files : [],
         offScaleValues: report.offScaleValues,
+        source: report.scale ? report.scale.source : 'default',
         tokenOpportunities: report.tokenOpportunities,
+        values: report.scale ? report.scale.values : null,
       },
       tokens: report.tokenContract,
     },

package/src/audit/render-markdown.js

@@ -3,6 +3,12 @@
 const { sortCountMap } = require('./contract');
 const { escapeMarkdown } = require('./render-utils');
 
+function describeScaleSource(scale) {
+  return scale.files.length > 0
+    ? `${scale.source} (${scale.files.join(', ')})`
+    : scale.source;
+}
+
 function renderMarkdown(report) {
   const lines = [
     '# Rhythmguard Design-System Audit',
@@ -20,6 +26,11 @@ function renderMarkdown(report) {
     `| Scale cleanliness | ${report.scaleCleanliness}% |`,
   ];
 
+  if (report.scale) {
+    lines.push(`| Scale | ${report.scale.values.join(', ')} |`);
+    lines.push(`| Scale source | ${describeScaleSource(report.scale)} |`);
+  }
+
   if (report.baseline) {
     lines.push(`| New findings | ${report.baseline.newFindingsCount} |`);
     lines.push(`| Resolved findings | ${report.baseline.resolvedFindingsCount} |`);

package/src/audit/render-text.js

@@ -21,9 +21,15 @@ function renderText(report) {
     `  Template files scanned   ${String(report.templateFilesScanned).padStart(4)}`,
     `  Files with issues        ${String(report.filesWithIssues).padStart(4)}`,
     `  Scale cleanliness        ${scoreBar(report.scaleCleanliness)}  ${report.scaleCleanliness}%`,
-    '',
   ];
 
+  if (report.scale) {
+    lines.push(`  Scale                    ${report.scale.values.join(', ')}`);
+    const files = report.scale.files.length > 0 ? ` (${report.scale.files.join(', ')})` : '';
+    lines.push(`  Scale source             ${report.scale.source}${files}`);
+  }
+  lines.push('');
+
   appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
   appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
   appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);

package/src/audit/report.js

@@ -1,6 +1,9 @@
 'use strict';
 
+const fs = require('node:fs');
+
 const {
+  createTokenKindMatcher,
   parseTokenSources,
 } = require('../utils/token-sources');
 const {
@@ -13,7 +16,9 @@ const {
   loadAuditConfig,
   loadIgnorePatterns,
 } = require('./config');
-const { buildReport } = require('./contract');
+const { buildReport, collectTokenDefinitions } = require('./contract');
+const { DEFAULT_SCALE, formatPath } = require('./shared');
+const { scaleFromDefinitions } = require('../utils/scale-inference');
 const {
   assertDirectory,
   collectCssFindings,
@@ -35,19 +40,27 @@ async function createAuditReport(options) {
   const scanFiles = getScanFiles(resolvedDir, ignorePatterns, parsed);
 
   const { cssFiles, scanScope, templateFiles } = scanFiles;
-  const lintOptions = {
-    baseFontSize: parsed.baseFontSize,
-    includeMotion: parsed.includeMotion,
-    scale: parsed.scale,
-  };
-
-  const cssResults = await runStylelintAudit(cssFiles, lintOptions);
 
   const tokenSourceResult = parseTokenSources({
     baseFontSize: parsed.baseFontSize,
     sources: parsed.tokenSources,
     tokenKind: parsed.tokenKind,
   });
+
+  const scale = resolveAuditScale({
+    baseFontSize: parsed.baseFontSize,
+    cssFiles,
+    requested: parsed.scale,
+    tokenSourceResult,
+  });
+
+  const lintOptions = {
+    baseFontSize: parsed.baseFontSize,
+    includeMotion: parsed.includeMotion,
+    scale: scale.values,
+  };
+
+  const cssResults = await runStylelintAudit(cssFiles, lintOptions);
   const stylelintFindings = collectCssFindings(cssResults);
   const cssFindings = stylelintFindings.filter((finding) => !finding.type.startsWith('motion-'));
   const motionFindings = [
@@ -64,6 +77,7 @@ async function createAuditReport(options) {
     externalTokenDefinitions: tokenSourceResult.definitions,
     includeMotion: parsed.includeMotion,
     motionFindings,
+    scale,
     scanScope,
     tailwindFindings: collectTailwindFindings(templateFiles, lintOptions),
     templateFiles,
@@ -84,6 +98,66 @@ async function createAuditReport(options) {
   return report;
 }
 
+/**
+ * One project-level scale for the whole audit, with provenance.
+ * "auto": external token sources, then spacing custom properties across the scanned
+ * CSS, then the default scale. First source that yields values wins.
+ */
+function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResult }) {
+  if (Array.isArray(requested)) {
+    return {
+      files: [],
+      source: requested === DEFAULT_SCALE ? 'default' : 'explicit',
+      tokenCount: 0,
+      values: requested,
+    };
+  }
+
+  if (tokenSourceResult.definitions.size > 0) {
+    const values = scaleFromDefinitions(tokenSourceResult.definitions, baseFontSize);
+    if (values) {
+      return {
+        files: tokenSourceResult.sources.map((source) => source.file),
+        source: 'token-sources',
+        tokenCount: tokenSourceResult.definitions.size,
+        values,
+      };
+    }
+  }
+
+  const definitions = new Map();
+  const matchesKind = createTokenKindMatcher('spacing');
+  for (const filePath of cssFiles) {
+    let text;
+    try {
+      text = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    collectTokenDefinitions(text, formatPath(filePath), definitions, matchesKind, baseFontSize);
+  }
+
+  if (definitions.size > 0) {
+    const values = scaleFromDefinitions(definitions, baseFontSize);
+    if (values) {
+      const files = new Set();
+      for (const definition of definitions.values()) {
+        for (const file of definition.files) {
+          files.add(file);
+        }
+      }
+      return {
+        files: Array.from(files).sort(),
+        source: 'scanned-css',
+        tokenCount: definitions.size,
+        values,
+      };
+    }
+  }
+
+  return { files: [], source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
+}
+
 function normalizeCreateAuditOptions(options = {}) {
   const parsed = {
     ...createDefaultAuditOptions(),

package/src/cli/index.js

@@ -3,9 +3,13 @@
 
 const command = process.argv[2];
 
-const HELP = `Usage: rhythmguard <command>
+const HELP = `Usage: rhythmguard [command]
+
+With no command: zero-config quickstart. Detects your stack and tokens, infers
+the spacing scale, audits the current directory and prints a config to paste.
 
 Commands:
+  quickstart    Same as running with no command
   audit <dir>   Report design-system drift across CSS and Tailwind class strings
   init          Scaffold a Rhythmguard config for your project
   doctor        Validate your Rhythmguard setup
@@ -14,22 +18,24 @@ Options:
   --help        Show this help message
 
 Examples:
+  npx rhythmguard
   npx rhythmguard audit ./src
-  npx rhythmguard audit ./src --json
   npx rhythmguard audit ./src --format markdown
   npx rhythmguard init
   npx rhythmguard doctor
 `;
 
-if (!command || command === '--help' || command === '-h') {
+if (command === '--help' || command === '-h') {
   process.stdout.write(HELP);
   process.exit(0);
 }
 
-if (command === 'audit') {
+if (!command || command === 'quickstart') {
+  require('./quickstart').run();
+} else if (command === 'audit') {
   require('./audit').run();
 } else if (command === 'init') {
-  require('./init');
+  require('./init').run();
 } else if (command === 'doctor') {
   require('./doctor');
 } else {

package/src/cli/init.js

@@ -153,4 +153,8 @@ async function run() {
   }
 }
 
-run();
+module.exports = { detect, run, selectProfile };
+
+if (require.main === module) {
+  run();
+}

package/src/cli/quickstart.js

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * `npx rhythmguard` with no arguments.
+ *
+ * The first minute, with nothing to configure: detect the stack and any token
+ * files, infer the spacing scale from the project's own tokens, audit the
+ * current directory, and end with the exact config to paste. Never fails the
+ * process on findings; this is a report, not a gate.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { createAuditReport } = require('../audit/report');
+const { detect } = require('./init');
+
+const TOKEN_FILE_PATTERN = /(^|[.-])tokens?\.json$/i;
+const TOKEN_DIRS = ['tokens', 'design-tokens', path.join('src', 'tokens'), path.join('dist', 'tokens')];
+const MAX_LISTED = 5;
+
+function readPackage(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function tailwindMajor(pkg) {
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps['@tailwindcss/postcss'] || deps['@tailwindcss/vite']) {
+    return 4;
+  }
+  const spec = deps.tailwindcss;
+  if (!spec) {
+    return null;
+  }
+  const match = String(spec).match(/(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function findTokenFiles(cwd) {
+  const found = new Set();
+  const consider = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && TOKEN_FILE_PATTERN.test(entry.name)) {
+        found.add(path.relative(cwd, path.join(dir, entry.name)));
+      }
+    }
+  };
+  consider(cwd);
+  for (const sub of TOKEN_DIRS) {
+    consider(path.join(cwd, sub));
+  }
+  return Array.from(found).sort();
+}
+
+function hasRhythmguardConfig(cwd) {
+  return fs.existsSync(path.join(cwd, '.rhythmguardrc.json'));
+}
+
+function toPosix(relativePath) {
+  return `./${relativePath.split(path.sep).join('/')}`;
+}
+
+function topEntries(counts, limit = MAX_LISTED) {
+  return Object.entries(counts || {})
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit);
+}
+
+function suggestedStylelintConfig({ profile, tokenFiles }) {
+  const ruleOptions = { scale: 'auto' };
+  if (tokenFiles.length > 0) {
+    ruleOptions.scaleSources = tokenFiles.map(toPosix);
+  }
+  return {
+    extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
+    rules: {
+      'rhythmguard/use-scale': [true, ruleOptions],
+    },
+  };
+}
+
+function eslintSnippet(scaleValues) {
+  const scale = scaleValues.filter((value) => typeof value === 'number').join(', ');
+  return [
+    "// eslint.config.js",
+    "import rhythmguard from 'stylelint-plugin-rhythmguard/eslint';",
+    '',
+    'export default [',
+    '  {',
+    "    plugins: { 'rhythmguard-tailwind': rhythmguard },",
+    `    rules: { 'rhythmguard-tailwind/tailwind-class-use-scale': ['warn', { scale: [${scale}] }] },`,
+    '  },',
+    '];',
+  ].join('\n');
+}
+
+function describeScale(scale) {
+  if (!scale) {
+    return 'default';
+  }
+  const files = scale.files && scale.files.length > 0 ? ` (${scale.files.slice(0, 3).join(', ')}${scale.files.length > 3 ? ', …' : ''})` : '';
+  return `${scale.source}${files}`;
+}
+
+async function run() {
+  const cwd = process.cwd();
+  const pkg = readPackage(cwd);
+  const stack = detect();
+  const twMajor = stack.tailwind ? tailwindMajor(pkg) : null;
+  const tokenFiles = findTokenFiles(cwd);
+  const rcPresent = hasRhythmguardConfig(cwd);
+  const out = [];
+
+  out.push('', '  Rhythmguard quickstart', `  ${cwd}`, '');
+  out.push('  Detected');
+  out.push(`    Tailwind        ${stack.tailwind ? `v${twMajor || '?'}` : 'no'}`);
+  out.push(`    Next.js         ${stack.nextjs ? 'yes' : 'no'}`);
+  out.push(`    Stylelint config ${stack.hasExistingConfig ? 'present' : 'none'}`);
+  out.push(`    Token files     ${tokenFiles.length > 0 ? tokenFiles.join(', ') : 'none found'}`);
+  out.push(`    .rhythmguardrc  ${rcPresent ? 'present (its token sources are used)' : 'none'}`);
+  out.push('');
+
+  let report;
+  try {
+    report = await createAuditReport({
+      dir: '.',
+      scale: 'auto',
+      ...(tokenFiles.length > 0 && !rcPresent
+        ? { tokenSources: tokenFiles }
+        : {}),
+    });
+  } catch (error) {
+    process.stderr.write(`Quickstart could not audit ${cwd}: ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (report.cssFilesScanned === 0 && report.templateFilesScanned === 0) {
+    out.push('  No CSS files found here. Run from your project root, or audit a directory directly:');
+    out.push('    npx rhythmguard audit ./src', '');
+    process.stdout.write(`${out.join('\n')}\n`);
+    return;
+  }
+
+  const scale = report.scale;
+  out.push('  Scale');
+  out.push(`    Scale           ${scale.values.join(', ')}`);
+  out.push(`    Source          ${describeScale(scale)}`);
+  if (scale.source === 'fallback') {
+    out.push('    Note            No spacing tokens found; the rhythmic-4 preset is being used.');
+    out.push('                    Add scaleSources or define --space-*/--spacing-* custom properties to lint against your own scale.');
+  }
+  out.push('');
+
+  const offScale = report.findings.css.filter((finding) => finding.type === 'off-scale');
+  out.push('  Findings');
+  out.push(`    CSS files       ${report.cssFilesScanned}`);
+  out.push(`    Template files  ${report.templateFilesScanned}`);
+  out.push(`    Off-scale       ${offScale.length} in CSS, ${report.findings.tailwind.length} in class strings`);
+  out.push(`    Token opps      ${report.findings.css.length - offScale.length} raw values that match or deserve a token`);
+  out.push(`    Cleanliness     ${report.scaleCleanliness}%`);
+  const topValues = topEntries(report.offScaleValues);
+  if (topValues.length > 0) {
+    out.push(`    Top values      ${topValues.map(([value, count]) => `${value} ×${count}`).join(', ')}`);
+  }
+  const topFiles = (report.topAffectedFiles || []).slice(0, 3);
+  if (topFiles.length > 0) {
+    out.push(`    Top files       ${topFiles.map((entry) => `${entry.file} (${entry.count})`).join(', ')}`);
+  }
+  out.push('');
+
+  const profile = stack.tailwind ? (stack.nextjs ? 'react-tailwind' : 'tailwind') : 'recommended';
+  out.push(`  Paste this into .stylelintrc.json${stack.hasExistingConfig ? ' (merge with your existing config)' : ''}:`, '');
+  out.push(JSON.stringify(suggestedStylelintConfig({ profile, tokenFiles }), null, 2).replace(/^/gm, '    '));
+  out.push('');
+
+  if (stack.tailwind) {
+    out.push('  Tailwind class strings need the ESLint companion. Paste this into eslint.config.js:', '');
+    out.push(eslintSnippet(scale.values).replace(/^/gm, '    '));
+    out.push('');
+  }
+
+  out.push('  Next');
+  out.push('    npx stylelint "**/*.css"                      lint with the config above');
+  out.push('    npx rhythmguard audit . --format markdown     PR-ready report');
+  out.push('    npx rhythmguard audit . --write-baseline      then gate only new drift in CI');
+  out.push('    npx rhythmguard doctor                        check the setup');
+  out.push('');
+
+  process.stdout.write(`${out.join('\n')}\n`);
+}
+
+module.exports = { findTokenFiles, run, suggestedStylelintConfig, tailwindMajor };

package/src/configs/embed.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * The one-liner for shared-config authors.
+ *
+ * One rule, warning level, scale inferred from the consuming project's own
+ * spacing tokens (scaleSources, .rhythmguardrc.json token sources, the
+ * stylesheet's custom properties, a Tailwind config, then rhythmic-4).
+ * No `extends`, no dependency beyond this plugin, and the shape is frozen for
+ * the life of the 2.x line so a config that embeds it never changes behaviour
+ * on a minor bump.
+ */
+module.exports = {
+  plugins: ['stylelint-plugin-rhythmguard'],
+  rules: {
+    'rhythmguard/use-scale': [
+      true,
+      {
+        scale: 'auto',
+        severity: 'warning',
+      },
+    ],
+  },
+};

package/src/configs/embed.mjs

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const config = require('./embed.js');
+export default config;

package/src/index.js

@@ -15,6 +15,7 @@ module.exports.rules = {
   [useMotionScale.ruleName]: useMotionScale,
 };
 module.exports.configs = {
+  embed: require('./configs/embed'),
   recommended: require('./configs/recommended'),
   strict: require('./configs/strict'),
   tailwind: require('./configs/tailwind'),