stylelint-plugin-rhythmguard 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.2.0] - 2026-09-06
+
+### Added
+
+- `rhythmguard audit --format badge` writes a shields.io endpoint document for a README badge: `spacing drift` as a percentage by default, or the off-scale count with `--badge-metric findings`. Workflow in `docs/CI_ADOPTION.md`. ([#68](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/68))
+- `rhythmguard init --agents <claude|cursor|copilot|all>` installs the agents block from `docs/FOR_AGENTS.md` as a Claude Code skill, a Cursor rule, or a block in `.github/copilot-instructions.md`. The packs ship in the package under `agents/`, are generated by `npm run build:agents`, and a test keeps them in sync with the docs. ([#69](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/69))
+- `npm run bench:state-of-spacing` generates a dated State of Spacing edition from the quiet benchmark results: one row per repository with scale source, off-scale count, drift per 100 CSS files, cleanliness, top values, top properties, and the change since the previous edition. Benchmark results now record the property of each finding. First edition at 20 repositories in `docs/STATE_OF_SPACING.md`. ([#70](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/70))
+
+### Changed
+
+- Dev dependencies: eslint 9.39.5; the unused `geist` package and its `next` and `sharp` chain are gone, and `npm audit` reports no findings. No runtime dependency changed.
+
+## [3.1.0] - 2026-09-06
+
+### Added
+
+- Audit findings for CSS declarations carry the declaration's `property`, recovered from the source at the warning position (`null` inside at-rules). Off-scale findings are counted by property in `offScaleProperties`, exposed as `contracts.scale.offScaleProperties`, rendered as a histogram in text, Markdown and HTML output and as a `Top properties` line in the quickstart. Baseline keys and benchmark snapshots are unchanged. ([#64](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/64))
+
+### Changed
+
+- `rhythmguard audit --help` describes what `--scale auto` reads and in which order, SCSS scanning through `postcss-scss`, and the value, property and file breakdowns.
+- CI and release workflows no longer run the full suite on the Stylelint 16.0.0 floor as an allowed-to-fail step; that step produced an error annotation on every green run. The blocking floor suite is unchanged. Actions `checkout` and `setup-node` moved to v5.
+
 ## [3.0.0] - 2026-09-06
 
 Upgrade notes: [`docs/MIGRATING_TO_3.md`](./docs/MIGRATING_TO_3.md).

package/CONTRIBUTING.md

@@ -6,7 +6,7 @@ Thank you for being here. Rhythmguard is a small, opinionated tool with one job:
 
 **Report a false positive.** A finding your team considers wrong is the most valuable report we get. It is how percentages and hairlines stopped being findings. Open a [false-positive report](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/new?template=false-positive.yml) with the CSS or class string and your config. No fix required.
 
-**Add a repository to the quiet benchmark.** The benchmark audits public design systems and fails CI when the findings change. Adding a repo is one JSON entry in `benchmarks/quiet/repos.json` plus `npm run bench:quiet -- --only <name>` to create its snapshot. Systems with tokens in unusual places are the most useful additions.
+**Add a repository to the quiet benchmark.** The benchmark audits public design systems and fails CI when the findings change. Adding a repo is one JSON entry in `benchmarks/quiet/repos.json` plus `npm run bench:quiet -- --only <name>` to create its snapshot. Systems with tokens in unusual places are the most useful additions. The same results feed the dated [State of Spacing](./docs/STATE_OF_SPACING.md) editions, so every repository you add widens that report.
 
 **Review a drift list.** Each benchmark repo has a list of findings that heuristics call real drift. Labelling them as real or as an allowance in `benchmarks/quiet/labels/<repo>.json` with a one-line reason turns a heuristic number into a reviewed one, and any systematic pattern you find becomes a candidate default.
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=4" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=5" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
 </p>
 
 # stylelint-plugin-rhythmguard
@@ -85,6 +85,8 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 
 `npx rhythmguard init` writes a starter config for your stack. `npx rhythmguard doctor` checks the setup.
 
+A README badge comes from the same audit: `--format badge` writes a shields.io endpoint document, see [`docs/CI_ADOPTION.md`](./docs/CI_ADOPTION.md#5-show-a-badge).
+
 ## Guides
 
 - [Tailwind integration](docs/TAILWIND.md), including v4 `@theme` tokens and what each layer covers
@@ -92,8 +94,9 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 - [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
+- [For coding agents](docs/FOR_AGENTS.md): a paste-ready `AGENTS.md` block, installable with `npx rhythmguard init --agents all` for Claude Code, Cursor and Copilot
 - [Quiet benchmark](docs/QUIET_BENCHMARK.md): findings on public design systems, checked on every change
+- [State of Spacing](docs/STATE_OF_SPACING.md): dated editions of the same data, ranked by drift density, with the values and properties that drifted
 - [Product direction](docs/STRATEGY_2026-09.md)
 - Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/)
 

package/agents/claude-code/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: rhythmguard
+description: Keep CSS and Tailwind spacing on the project scale. Use when writing or changing CSS, SCSS, CSS Modules or Tailwind class strings, and before finishing any such change.
+---
+
+## Spacing scale
+
+This project enforces its spacing scale with stylelint-plugin-rhythmguard.
+
+- Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
+- A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
+- Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
+- Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
+- If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
+
+Source: docs/FOR_AGENTS.md in the stylelint-plugin-rhythmguard repository (https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/FOR_AGENTS.md). Regenerate with `npx rhythmguard init --agents`.

package/agents/copilot/copilot-instructions.md

@@ -0,0 +1,13 @@
+## Spacing scale
+
+This project enforces its spacing scale with stylelint-plugin-rhythmguard.
+
+- Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
+- A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
+- Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
+- Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
+- If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
+
+Source: docs/FOR_AGENTS.md in the stylelint-plugin-rhythmguard repository (https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/FOR_AGENTS.md). Regenerate with `npx rhythmguard init --agents`.

package/agents/cursor/rhythmguard.mdc

@@ -0,0 +1,19 @@
+---
+description: Spacing scale rules enforced by stylelint-plugin-rhythmguard
+globs: ["**/*.css", "**/*.scss", "**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.html"]
+alwaysApply: true
+---
+
+## Spacing scale
+
+This project enforces its spacing scale with stylelint-plugin-rhythmguard.
+
+- Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
+- A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
+- Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
+- Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
+- If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
+
+Source: docs/FOR_AGENTS.md in the stylelint-plugin-rhythmguard repository (https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/FOR_AGENTS.md). Regenerate with `npx rhythmguard init --agents`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Nobody chose 13px. Catches off-scale spacing in CSS and Tailwind class strings and snaps it to your scale or tokens. Stylelint rules, an ESLint companion, and an audit CLI.",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -89,6 +89,7 @@
     }
   },
   "files": [
+    "agents",
     "examples",
     "scales",
     "schemas",
@@ -113,7 +114,9 @@
     "test:npm-smoke": "node scripts/ci/npm-registry-smoke.mjs --package stylelint-plugin-rhythmguard --version latest",
     "test:pack-smoke": "node scripts/ci/pack-smoke.mjs",
     "test:watch": "node --test --watch test/*.test.js",
-    "typecheck": "tsc -p tsconfig.typecheck.json"
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "build:agents": "node scripts/build-agents.mjs",
+    "bench:state-of-spacing": "node scripts/bench/state-of-spacing.mjs"
   },
   "repository": {
     "type": "git",
@@ -125,8 +128,8 @@
     "email": "hello@petrilahdelma.com"
   },
   "peerDependencies": {
-    "stylelint": "^16.0.0 || ^17.0.0",
     "postcss-scss": "^4.0.0",
+    "stylelint": "^16.0.0 || ^17.0.0",
     "stylelint-config-tailwindcss": "^1.0.1",
     "stylelint-plugin-logical-css": "^2.0.2"
   },
@@ -145,11 +148,10 @@
     "known-css-properties": "^0.37.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.22.0",
+    "@eslint/js": "^9.39.5",
     "@types/node": "^22.20.1",
     "c8": "^10.1.3",
-    "eslint": "^9.22.0",
-    "geist": "^1.7.0",
+    "eslint": "^9.39.5",
     "postcss-scss": "^4.0.9",
     "postcss-value-parser": "^4.2.0",
     "stylelint": "^16.15.0",

package/src/audit/args.js

@@ -4,6 +4,7 @@ const {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
 } = require('../utils/token-sources');
+const { BADGE_METRICS } = require('./render-badge');
 const {
   VALID_FORMATS,
   createDefaultAuditOptions,
@@ -13,12 +14,14 @@ const {
 const HELP = `Usage: rhythmguard audit <dir> [options]
 
 Options:
-  --format <text|json|json-v1|markdown|html|github> Output format (default: text)
+  --format <text|json|json-v1|markdown|html|github|badge> Output format (default: text)
                                  github = GitHub Actions workflow-command annotations
+                                 badge = shields.io endpoint JSON for a README badge
+  --badge-metric <drift|findings> Badge value: drift percent or off-scale count (default: drift)
   --json                         Alias for --format json
   --markdown                     Alias for --format markdown
   --schema                       Print the audit JSON schema and exit
-  --output <file>                Write json, markdown, or html output to a file
+  --output <file>                Write json, markdown, html or badge output to a file
   --config <file>                Load audit config (default: .rhythmguardrc.json when present)
   --no-config                    Ignore .rhythmguardrc.json discovery
   --ignore <pattern>             Exclude root-relative path/glob (repeatable, comma-separated)
@@ -37,8 +40,14 @@ Options:
   --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|auto>          Comma-separated scale values (default: 0,4,8,12,16,24,32);
-                                 auto infers the scale from token sources, then scanned CSS
+                                 auto infers the scale from token sources, then --space-*/--spacing-*
+                                 custom properties and Sass variables in scanned CSS/SCSS, then
+                                 installed design-token packages, and reports where it came from
   --base-font-size <number>      px base for rem/em conversion (default: 16)
+
+Scans .css files, and .scss files when postcss-scss is installed. Reports drift by
+value, by property and by file; text output prints histograms, markdown is PR-ready,
+json is the stable 2.0 contract.
 `;
 
 function parseArgs(argv) {
@@ -277,6 +286,16 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--badge-metric') {
+      parsed.badgeMetric = String(argv[++index] || '').toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith('--badge-metric=')) {
+      parsed.badgeMetric = arg.slice('--badge-metric='.length).toLowerCase();
+      continue;
+    }
+
     if (arg === '--format') {
       parsed.format = String(argv[++index] || '').toLowerCase();
       continue;
@@ -323,6 +342,10 @@ function parseArgs(argv) {
     throw new Error(`Invalid format "${parsed.format}". Expected text, json, json-v1, markdown, html, or github.`);
   }
 
+  if (!BADGE_METRICS.has(parsed.badgeMetric)) {
+    throw new Error(`Invalid badge metric "${parsed.badgeMetric}". Expected drift or findings.`);
+  }
+
   if (parsed.since && parsed.staged) {
     throw new Error('Use either --since or --staged, not both.');
   }

package/src/audit/contract.js

@@ -268,6 +268,9 @@ function buildReport({
   const offScaleValues = countByValue(cssFindings
     .filter((finding) => finding.type === 'off-scale' && finding.value)
     .map((finding) => finding.value));
+  const offScaleProperties = countByValue(cssFindings
+    .filter((finding) => finding.type === 'off-scale' && finding.property)
+    .map((finding) => finding.property));
   const tokenOpportunities = countByValue(cssFindings
     .filter((finding) => finding.type === 'token-opportunity' && finding.value)
     .map((finding) => finding.value));
@@ -319,6 +322,7 @@ function buildReport({
       findings: motionFindings.length,
       values: Object.fromEntries(sortCountMap(motionValues).slice(0, 10)),
     },
+    offScaleProperties: Object.fromEntries(sortCountMap(offScaleProperties).slice(0, 10)),
     offScaleValues: Object.fromEntries(sortCountMap(offScaleValues).slice(0, 10)),
     scale: scale || null,
     scaleCleanliness,
@@ -388,6 +392,7 @@ function toAuditContractReport(report) {
       scale: {
         cleanliness: report.scaleCleanliness,
         files: report.scale ? report.scale.files : [],
+        offScaleProperties: report.offScaleProperties || {},
         offScaleValues: report.offScaleValues,
         source: report.scale ? report.scale.source : 'default',
         tokenOpportunities: report.tokenOpportunities,

package/src/audit/render-badge.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * shields.io endpoint badge: https://shields.io/badges/endpoint
+ *
+ * `drift` reports 100 minus scale cleanliness as a percentage (the share of
+ * scanned files with at least one finding). `findings` reports the number of
+ * off-scale CSS values plus Tailwind class-string findings.
+ */
+const BADGE_METRICS = new Set(['drift', 'findings']);
+
+const THRESHOLDS = {
+  drift: [[2, 'brightgreen'], [5, 'green'], [15, 'yellow']],
+  findings: [[0, 'brightgreen'], [10, 'green'], [50, 'yellow']],
+};
+
+function badgeColor(metric, value) {
+  for (const [limit, color] of THRESHOLDS[metric]) {
+    if (value <= limit) {
+      return color;
+    }
+  }
+  return 'orange';
+}
+
+function badgeValue(report, metric) {
+  if (metric === 'drift') {
+    const cleanliness = Number.isFinite(report.scaleCleanliness) ? report.scaleCleanliness : 100;
+    return Math.max(0, Math.min(100, 100 - cleanliness));
+  }
+  const css = (report.findings && report.findings.css) || [];
+  const tailwind = (report.findings && report.findings.tailwind) || [];
+  return css.filter((finding) => finding.type === 'off-scale').length + tailwind.length;
+}
+
+function renderBadge(report, { metric = 'drift' } = {}) {
+  if (!BADGE_METRICS.has(metric)) {
+    throw new Error(`Unknown badge metric "${metric}". Use one of: ${Array.from(BADGE_METRICS).join(', ')}.`);
+  }
+  const value = badgeValue(report, metric);
+  const badge = {
+    schemaVersion: 1,
+    label: metric === 'drift' ? 'spacing drift' : 'off-scale values',
+    message: metric === 'drift' ? `${value}%` : String(value),
+    color: badgeColor(metric, value),
+  };
+  return `${JSON.stringify(badge, null, 2)}\n`;
+}
+
+module.exports = {
+  BADGE_METRICS,
+  badgeColor,
+  renderBadge,
+};

package/src/audit/render-html.js

@@ -34,6 +34,7 @@ function renderHtml(report) {
     metricHtml('CSS files', report.cssFilesScanned),
     metricHtml('Template files', report.templateFilesScanned),
     '</section>',
+    renderHtmlTable('CSS Off-Scale Properties', ['Property', 'Count'], Object.entries(report.offScaleProperties || {})),
     renderHtmlTable('Top Affected Files', ['File', 'Findings'], report.topAffectedFiles.map(({ file, count }) => [file, count])),
     renderHtmlTable('Token Contract Sources', ['File', 'Format', 'Tokens'], report.tokenContract.sources.map((source) => [
       source.file,

package/src/audit/render-markdown.js

@@ -40,6 +40,7 @@ function renderMarkdown(report) {
   lines.push('');
 
   appendMarkdownCounts(lines, 'CSS Off-Scale Values', report.offScaleValues);
+  appendMarkdownCounts(lines, 'CSS Off-Scale Properties', report.offScaleProperties, 'Property');
   appendMarkdownCounts(lines, 'CSS Token Opportunities', report.tokenOpportunities);
   appendMarkdownCounts(lines, 'Tailwind Class-String Drift', report.tailwindArbitraryValues);
   appendMarkdownCounts(lines, 'Motion Rhythm Drift', report.motion.values);
@@ -204,8 +205,8 @@ function appendBaselineMarkdown(lines, report) {
   }
 }
 
-function appendMarkdownCounts(lines, title, counts) {
-  const entries = sortCountMap(counts);
+function appendMarkdownCounts(lines, title, counts, label = 'Value') {
+  const entries = sortCountMap(counts || {});
 
   if (entries.length === 0) {
     return;
@@ -213,7 +214,7 @@ function appendMarkdownCounts(lines, title, counts) {
 
   lines.push(`## ${title}`);
   lines.push('');
-  lines.push('| Value | Count |');
+  lines.push(`| ${label} | Count |`);
   lines.push('| --- | ---: |');
   for (const [value, count] of entries) {
     lines.push(`| \`${escapeMarkdown(value)}\` | ${count} |`);

package/src/audit/render-text.js

@@ -33,6 +33,7 @@ function renderText(report) {
   lines.push('');
 
   appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
+  appendHistogram(lines, 'CSS OFF-SCALE PROPERTIES', report.offScaleProperties);
   appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
   appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);
   appendHistogram(lines, 'MOTION RHYTHM DRIFT', report.motion.values);
@@ -145,9 +146,9 @@ function appendBaselineText(lines, report) {
   }
 }
 
-function appendHistogram(lines, title, counts) {
-  const entries = sortCountMap(counts);
-  const total = sumCounts(counts);
+function appendHistogram(lines, title, counts = {}) {
+  const entries = sortCountMap(counts || {});
+  const total = sumCounts(counts || {});
 
   if (entries.length === 0) {
     return;

package/src/audit/scan.js

@@ -342,10 +342,12 @@ async function runStylelintAudit(cssFiles, options) {
 
 function collectCssFindings(fileResults) {
   const findings = [];
+  const sources = new Map();
 
   for (const fileResult of fileResults) {
     for (const warning of fileResult.warnings || []) {
       const text = warning.text || '';
+      const source = readSourceOnce(sources, fileResult.source);
       const offScaleMatch = text.match(
         /Unexpected (?:off-scale value|transform translation value) "([^"]+)"/,
       );
@@ -363,6 +365,9 @@ function collectCssFindings(fileResults) {
         column: warning.column || 1,
         file: formatPath(fileResult.source),
         line: warning.line || 1,
+        property: source === null
+          ? null
+          : findDeclarationProperty(source, warning.line || 1, warning.column || 1),
         rule: warning.rule || 'rhythmguard',
         text,
         type: getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }),
@@ -379,6 +384,73 @@ function collectCssFindings(fileResults) {
   return findings;
 }
 
+function readSourceOnce(cache, filePath) {
+  if (!filePath) {
+    return null;
+  }
+  if (!cache.has(filePath)) {
+    try {
+      cache.set(filePath, fs.readFileSync(filePath, 'utf8'));
+    } catch {
+      cache.set(filePath, null);
+    }
+  }
+  return cache.get(filePath);
+}
+
+const DECLARATION_BOUNDARY = new Set([';', '{', '}']);
+const DECLARATION_HEAD_PATTERN = /^\s*(?:(?:\/\*[\s\S]*?\*\/|\/\/[^\n]*)\s*)*(--[\w-]+|[a-zA-Z][\w-]*)\s*:/;
+
+/**
+ * Stylelint warnings carry a position but not the declaration node. Recover the
+ * property by walking from the warning position back to the previous declaration
+ * boundary and reading the `property:` head, skipping block and Sass line comments.
+ * Sass interpolation is blanked first so `#{...}` braces do not act as boundaries. Returns null when the position is not
+ * inside a declaration, for example inside an at-rule.
+ */
+function findDeclarationProperty(source, line, column) {
+  const offset = positionToOffset(source, line, column);
+  if (offset === null) {
+    return null;
+  }
+
+  const text = source.replace(/#\{[^}]*\}/g, (match) => ' '.repeat(match.length));
+  let start = offset;
+  while (start > 0 && !DECLARATION_BOUNDARY.has(text[start - 1])) {
+    start -= 1;
+  }
+  const backward = text.slice(start, offset).match(DECLARATION_HEAD_PATTERN);
+  if (backward) {
+    return backward[1];
+  }
+
+  let end = offset;
+  while (end < text.length && !DECLARATION_BOUNDARY.has(text[end])) {
+    end += 1;
+  }
+  const forward = text.slice(offset, end).match(DECLARATION_HEAD_PATTERN);
+  return forward ? forward[1] : null;
+}
+
+function positionToOffset(source, line, column) {
+  if (!Number.isInteger(line) || line < 1) {
+    return null;
+  }
+  let offset = 0;
+  let currentLine = 1;
+  while (currentLine < line) {
+    const newline = source.indexOf('\n', offset);
+    if (newline === -1) {
+      return null;
+    }
+    offset = newline + 1;
+    currentLine += 1;
+  }
+  const lineEnd = source.indexOf('\n', offset);
+  const lineLength = (lineEnd === -1 ? source.length : lineEnd) - offset;
+  return offset + Math.min(Math.max((column || 1) - 1, 0), lineLength);
+}
+
 function getCssFindingValue({
   motionDurationMatch,
   motionEasingMatch,
@@ -581,6 +653,7 @@ module.exports = {
   collectTailwindMotionFindings,
   createIgnoreMatchers,
   escapeRegExp,
+  findDeclarationProperty,
   findStringLiterals,
   getCssFindingType,
   getCssFindingValue,

package/src/audit/shared.js

@@ -18,7 +18,7 @@ const DEFAULT_AUDIT_TOKEN_PATTERN = '^--(space|spacing)-';
 
 const DEFAULT_TOKEN_CANDIDATE_MIN_COUNT = 2;
 
-const VALID_FORMATS = new Set(['text', 'json', 'json-v1', 'markdown', 'html', 'github']);
+const VALID_FORMATS = new Set(['text', 'json', 'json-v1', 'markdown', 'html', 'github', 'badge']);
 
 const SKIP_DIRS = new Set([
   '.git',
@@ -69,6 +69,7 @@ function createDefaultAuditOptions() {
     configPath: DEFAULT_CONFIG_PATH,
     dir: null,
     failOnNewDrift: false,
+    badgeMetric: 'drift',
     format: 'text',
     ignorePath: DEFAULT_IGNORE_PATH,
     ignorePatterns: [],

package/src/cli/audit.js

@@ -13,6 +13,7 @@ const {
   toAuditContractReport,
 } = require('../audit/contract');
 const { renderGithub } = require('../audit/render-github');
+const { renderBadge } = require('../audit/render-badge');
 const { renderHtml } = require('../audit/render-html');
 const { renderMarkdown } = require('../audit/render-markdown');
 const { renderText } = require('../audit/render-text');
@@ -73,6 +74,12 @@ async function run() {
     return;
   }
 
+  if (parsed.format === 'badge') {
+    writeOutput(renderBadge(report, { metric: parsed.badgeMetric }), parsed.outputPath);
+    finish(auditFailures);
+    return;
+  }
+
   if (parsed.format === 'github') {
     writeOutput(renderGithub(report), parsed.outputPath);
     finish(auditFailures);
@@ -108,6 +115,7 @@ module.exports = {
   createAuditReport,
   loadAuditConfig,
   parseArgs,
+  renderBadge,
   renderHtml,
   run,
   toAuditContractReport,

package/src/cli/index.js

@@ -12,6 +12,7 @@ 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
+                --agents <claude|cursor|copilot|all> installs the agent instruction packs instead
   doctor        Validate your Rhythmguard setup
 
 Options:
@@ -22,6 +23,7 @@ Examples:
   npx rhythmguard audit ./src
   npx rhythmguard audit ./src --format markdown
   npx rhythmguard init
+  npx rhythmguard init --agents all
   npx rhythmguard doctor
 `;
 

package/src/cli/init.js

@@ -98,7 +98,84 @@ function selectProfile(stack) {
   return 'recommended';
 }
 
+const AGENT_TARGETS = {
+  claude: { source: 'claude-code/SKILL.md', target: path.join('.claude', 'skills', 'rhythmguard', 'SKILL.md'), mode: 'write' },
+  cursor: { source: 'cursor/rhythmguard.mdc', target: path.join('.cursor', 'rules', 'rhythmguard.mdc'), mode: 'write' },
+  copilot: { source: 'copilot/copilot-instructions.md', target: path.join('.github', 'copilot-instructions.md'), mode: 'append' },
+};
+const AGENT_BLOCK_START = '<!-- rhythmguard:agents:start -->';
+const AGENT_BLOCK_END = '<!-- rhythmguard:agents:end -->';
+
+function parseInitArgs(argv) {
+  const parsed = { agents: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--agents') {
+      parsed.agents = String(argv[++index] || 'all').toLowerCase();
+    } else if (arg.startsWith('--agents=')) {
+      parsed.agents = arg.slice('--agents='.length).toLowerCase();
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Copies the generated packs under <package>/agents into the locations each
+ * agent reads. Claude Code and Cursor files are owned by Rhythmguard and
+ * overwritten; copilot-instructions.md is shared, so the block is appended
+ * between markers and replaced in place on later runs.
+ */
+function installAgents(selection, cwd = process.cwd()) {
+  const names = selection === 'all' ? Object.keys(AGENT_TARGETS) : [selection];
+  const unknown = names.filter((name) => !AGENT_TARGETS[name]);
+  if (unknown.length > 0) {
+    throw new Error(`Unknown agents target "${unknown[0]}". Use claude, cursor, copilot or all.`);
+  }
+
+  const packsDir = path.join(__dirname, '..', '..', 'agents');
+  const written = [];
+  for (const name of names) {
+    const { mode, source, target } = AGENT_TARGETS[name];
+    const content = fs.readFileSync(path.join(packsDir, source), 'utf8');
+    const targetPath = path.join(cwd, target);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+
+    if (mode === 'append' && fs.existsSync(targetPath)) {
+      const existing = fs.readFileSync(targetPath, 'utf8');
+      const block = `${AGENT_BLOCK_START}\n${content.trimEnd()}\n${AGENT_BLOCK_END}\n`;
+      const start = existing.indexOf(AGENT_BLOCK_START);
+      const end = existing.indexOf(AGENT_BLOCK_END);
+      const next = start !== -1 && end !== -1
+        ? `${existing.slice(0, start)}${block}${existing.slice(end + AGENT_BLOCK_END.length).replace(/^\n/, '')}`
+        : `${existing.trimEnd()}\n\n${block}`;
+      fs.writeFileSync(targetPath, next);
+    } else {
+      fs.writeFileSync(targetPath, content);
+    }
+    written.push(target);
+  }
+  return written;
+}
+
 async function run() {
+  const args = parseInitArgs(process.argv.slice(3));
+
+  if (args.agents) {
+    let written;
+    try {
+      written = installAgents(args.agents);
+    } catch (error) {
+      process.stderr.write(`${error.message}\n`);
+      process.exit(1);
+    }
+    process.stdout.write('\nRhythmguard agent packs\n\n');
+    for (const file of written) {
+      process.stdout.write(`✓ Wrote ${file}\n`);
+    }
+    process.stdout.write('\nThe block is the one in docs/FOR_AGENTS.md. Trim it to the lines that apply.\n\n');
+    return;
+  }
+
   const prompter = createPrompter();
 
   try {
@@ -152,7 +229,7 @@ async function run() {
   }
 }
 
-module.exports = { detect, run, selectProfile };
+module.exports = { AGENT_TARGETS, detect, installAgents, run, selectProfile };
 
 if (require.main === module) {
   run();

package/src/cli/quickstart.js

@@ -177,6 +177,10 @@ async function run() {
   if (topValues.length > 0) {
     out.push(`    Top values      ${topValues.map(([value, count]) => `${value} ×${count}`).join(', ')}`);
   }
+  const topProperties = topEntries(report.offScaleProperties);
+  if (topProperties.length > 0) {
+    out.push(`    Top properties  ${topProperties.map(([property, count]) => `${property} ×${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(', ')}`);

package/types/audit.d.ts

@@ -27,7 +27,9 @@ export interface AuditOptions {
   configPath?: string;
   dir?: string;
   failOnNewDrift?: boolean;
-  format?: "json" | "json-v1" | "markdown" | "text" | "html" | "github";
+  /** Badge value when `format` is "badge": drift percent or off-scale count. */
+  badgeMetric?: "drift" | "findings";
+  format?: "json" | "json-v1" | "markdown" | "text" | "html" | "github" | "badge";
   ignorePath?: string;
   ignorePatterns?: string[];
   includeMotion?: boolean;
@@ -77,7 +79,8 @@ export interface AuditFinding {
   key?: string;
   line?: number;
   message: string;
-  property?: string;
+  /** CSS property of the declaration, recovered from the source. Null when the position is not inside a declaration. CSS findings only. */
+  property?: string | null;
   rule?: string;
   type: string;
   value?: string;
@@ -113,6 +116,10 @@ export interface AuditReport {
     motion: AuditFinding[];
     tailwind: AuditFinding[];
   };
+  /** Off-scale CSS findings counted by property, top ten. */
+  offScaleProperties?: Record<string, number>;
+  /** Off-scale CSS findings counted by value, top ten. */
+  offScaleValues?: Record<string, number>;
   scanned: AuditScanned;
   summary: AuditSummary;
   [key: string]: unknown;
@@ -130,6 +137,7 @@ export interface AuditContractReport {
     scale: {
       cleanliness?: unknown;
       files: string[];
+      offScaleProperties?: Record<string, number>;
       offScaleValues?: unknown;
       source: AuditScaleSource;
       tokenOpportunities?: unknown;