ui_guardrails 1.0.0

data/doc/PUBLISHING.md

@@ -0,0 +1,98 @@
+# Publishing to RubyGems
+
+Guardrails publishes to [RubyGems.org](https://rubygems.org/) using **RubyGems Trusted Publishing** — no long-lived API key stored in repo secrets. The `.github/workflows/release.yml` workflow runs on every `v*` tag push: it verifies the gemspec version matches the tag, runs the suite, and pushes the gem via a short-lived OIDC token RubyGems mints in exchange for the GitHub Actions identity.
+
+## One-time setup (before the first release)
+
+The gem doesn't exist on RubyGems.org yet, so the trusted publisher is configured as **pending** — it claims the name on the first successful push.
+
+1. **Sign in to rubygems.org** with the account that should own the gem (`meticulous` org owner). Confirm the account has 2FA enabled.
+
+2. **Open the pending trusted publishers page**: <https://rubygems.org/profile/oidc/pending_trusted_publishers> → **Create**.
+
+3. **Fill the form:**
+
+   | Field | Value |
+   |---|---|
+   | RubyGem name | `ui_guardrails` |
+   | Repository owner | `meticulous` |
+   | Repository name | `guardrails` |
+   | Workflow filename | `release.yml` |
+   | Environment | `release` |
+
+4. **Save.** The pending trusted publisher will sit there until the first tagged push from this repo successfully authenticates against it. After that first push, RubyGems automatically converts it to a regular trusted publisher attached to the now-created gem.
+
+## Cutting a release
+
+After the change set is merged to `main`:
+
+```bash
+# Pull main locally
+git checkout main
+git pull --ff-only
+
+# Confirm version + CHANGELOG are in the right shape
+grep VERSION lib/guardrails/version.rb
+head -20 CHANGELOG.md
+
+# Tag the merge commit and push the tag (replace X.Y.Z with the
+# version you're cutting — the next-release example would be the
+# version in lib/guardrails/version.rb on main right now).
+git tag -a vX.Y.Z -m "vX.Y.Z — <short summary>"
+git push origin vX.Y.Z
+```
+
+The `release.yml` workflow takes over from there. Watch the run at <https://github.com/meticulous/guardrails/actions> — it'll:
+
+1. Verify `Guardrails::VERSION` matches the tag (refuses to publish a mismatched gem)
+2. Run the test suite
+3. Build the gem
+4. Push to RubyGems.org via trusted publishing
+
+The whole flow typically runs in under 90 seconds.
+
+## What if the workflow fails?
+
+| Failure | Likely cause |
+|---|---|
+| `Guardrails::VERSION (X.Y.Z) does not match tag (vA.B.C). Refusing to publish.` | The tag points at a commit whose `lib/guardrails/version.rb` doesn't match. Re-tag against the right commit or bump the version. |
+| Spec suite fails | Same fix as a regular CI failure — root cause whatever the spec reported. |
+| `rubygems/release-gem` fails with an OIDC error | The pending trusted publisher on rubygems.org wasn't created, the workflow filename doesn't match, or the environment name doesn't match. Double-check the form in step 3 above. |
+
+## Manual fallback (legacy path)
+
+If trusted publishing breaks for any reason, the gem can still be published manually with an API key:
+
+1. Create an [API key on rubygems.org](https://rubygems.org/profile/api_keys) with the `push_rubygem` scope. Lock it to the `ui_guardrails` gem.
+2. Configure local credentials:
+   ```bash
+   mkdir -p ~/.gem
+   touch ~/.gem/credentials
+   chmod 600 ~/.gem/credentials
+   # then edit and add:
+   # ---
+   # :rubygems_api_key: rubygems_xxxxxxxxxxxxxxxxxxxxxxxx
+   ```
+3. Build and push:
+   ```bash
+   gem build *.gemspec
+   gem push *.gem
+   ```
+
+This path is for emergencies only — prefer the workflow.
+
+## Why trusted publishing over an API key secret
+
+- **No long-lived secret rotation.** The OIDC token is minted per workflow run and expires in minutes.
+- **Repo-bound by construction.** A leaked API key in a different repo's workflow would be useless against guardrails — trusted publishing is scoped to (repo × workflow × environment).
+- **Audit trail.** RubyGems records which workflow run published each version; you can confirm provenance at <https://rubygems.org/gems/ui_guardrails/versions>.
+
+## Yanking a bad release
+
+If a published version has a critical bug:
+
+```bash
+gem yank ui_guardrails -v X.Y.Z   # replace with the version to pull
+```
+
+Yanking removes the version from `gem install` resolution but leaves the version slot reserved — you can't republish a yanked version number. Bump and re-release.

data/doc/ROADMAP.md

@@ -0,0 +1,158 @@
+# Guardrails — Roadmap
+
+**Status:** **1.0.0 released on RubyGems.org** — V0 ✅, V1 ✅, V2 ✅ (visual-diff via snap_diff-capybara landed 0.8.0; published as 1.0.0 once the trusted-publisher pipeline merged)
+**Last updated:** 2026-05-11
+
+## Context
+
+Guardrails is a Ruby gem that prevents UI drift in Rails apps — particularly drift introduced by AI coding assistants that generate UI faster than design-system consistency can be maintained. The gem is also the conceptual scaffolding for the Rails World talk. The talk is **concept-led, not demo-led**, so the gem is the durable artifact rather than a live-demo dependency.
+
+This doc tracks shipped vs. planned scope and parks remaining unknowns. V0 + most of V1 landed in PR #1; 0.2.x patches refined detectors against four real codebases (Talos, Avo, Forem, Patchvault); 0.3.0 added cross-codebase structural pattern detection; 0.4.0 added the class-itis detector.
+
+---
+
+## V0 — Foundation
+
+### Audit (`rails guardrails:audit`)
+
+| Item | Status | Notes |
+|---|---|---|
+| Inline `style=` attributes | ✅ shipped | |
+| Hex / rgb color literals | ✅ shipped | Scoped to color-bearing attributes (fill, stroke, color, bgcolor, background, flood/lighting/stop-color, data-*color*) after Copilot review caught href="#section" false positives |
+| Tailwind arbitrary values (`bg-[#fa3]`) | ✅ shipped | Reported once as `tailwind_arbitrary`, not double-flagged as raw_color |
+| Hardcoded `font-size` / `line-height` | ❌ dropped as standalone | Folded into inline_style + tailwind_arbitrary detectors. Type-scale awareness lives in suggest mode token matching |
+
+### Suggest mode (`SUGGEST=1`)
+
+| Item | Status | Notes |
+|---|---|---|
+| Markdown checklist artifact | ✅ shipped | `doc/guardrails-suggestions-{TIMESTAMP}.md` |
+| Closest-token matching | ✅ shipped | Exact + near-match (channel-distance ≤ 4) |
+| Per-violation `[ ]` checkbox + rule + replacement | ✅ shipped | |
+| Type-scale matching | ✅ shipped | `text-[1rem]` matches a defined `--text-base: 1rem` token |
+
+### Auto-fix (`APPLY=1`)
+
+| Item | Status | Notes |
+|---|---|---|
+| `raw_color` exact-match rewrite to `var(--token)` | ✅ shipped | Right-to-left within line; verifies expected text at column before writing |
+| `raw_color` near-match rewrite | ✅ shipped | Gated on `near_match_policy: fix` in guardrails.yml |
+| `tailwind_arbitrary` auto-fix | ✅ shipped | Replaces `bg-[#hex]` with `bg-tokenname` when a `:tailwind` theme token matches by value. Variant prefixes (`lg:hover:`, `[&>div]:`) preserved |
+| `inline_style` auto-fix | ❌ deferred | Structural rewrite, not value swap |
+| `font-size` auto-fix | ❌ deferred | Same constraint as inline_style |
+
+### Icons (`rails guardrails:icons`)
+
+| Item | Status |
+|---|---|
+| SVG sprite generation | ✅ shipped |
+| Inline `<svg>` detection in views | ✅ shipped |
+| Dead-icon report | ✅ shipped |
+
+### Init / analysis (`rails guardrails:init`)
+
+| Item | Status | Notes |
+|---|---|---|
+| Stack detection (CSS-vars / SCSS / raw-hex) | ✅ shipped | |
+| `guardrails.yml` writing with sensible defaults | ✅ shipped | |
+| `prefers-color-scheme` + `prefers-contrast` MQ scaffolding | ✅ shipped | Skipped if ConfigWriter refuses to overwrite |
+| Interactive prompts (TTY) | ✅ shipped | near_match_policy / near_match_threshold / scan_paths / ignore paths (matched as exact paths or directory prefixes — not shell globs). CI-safe non-TTY fallback to defaults. Skipped entirely when config exists and FORCE=1 isn't set |
+| Refuse-overwrite by default | ✅ shipped | |
+| `FORCE=1` to overwrite + re-scaffold MQs | ✅ shipped | |
+
+### Tokens (`rails guardrails:tokens`)
+
+| Item | Status | Notes |
+|---|---|---|
+| Parse CSS custom properties + SCSS variables from `colors_file` | ✅ shipped | |
+| Parse `type_scale_file` alongside `colors_file` | ✅ shipped | |
+| Tailwind v4 `@theme {}` blocks | ✅ shipped | Goes through the existing CSS custom property scanner |
+| `tailwind.config.js` (v3) regex parsing | ✅ shipped | Best-effort: flat colors, nested scales (gray.50 → gray-50), spread/function values skipped |
+| Stylesheet drift scan with comment stripping | ✅ shipped | |
+| Hex normalization (case + short form + alpha) | ✅ shipped | |
+| Drift matching against Tailwind theme colors | ✅ shipped | |
+
+### Stimulus audit
+
+| Item | Status | Notes |
+|---|---|---|
+| Orphan controllers (referenced, no JS file) | ✅ shipped | |
+| Dead controllers (JS file, never referenced) | ✅ shipped | |
+| Ruby helper syntax detection | ✅ shipped | `tag.div(data: { controller: "foo" })` and hash-rocket variants |
+
+### CI integration
+
+| Item | Status | Notes |
+|---|---|---|
+| Exit codes (0 clean, 1 violations) | ✅ shipped | |
+| `FORMAT=json` machine-readable output | ✅ shipped | Unified across all sub-audits |
+| `--strict` flag | ❌ dropped | No semantic distinction beyond exit-1-on-violations default. Revisit if/when warning vs error severities emerge |
+
+---
+
+## V1 — Polish + Differentiation
+
+| Item | Status | Notes |
+|---|---|---|
+| ViewComponent preview detection | ✅ shipped | |
+| ViewComponent slot validation | ✅ shipped | Known limit: code-only components (`def call`) flag declared slots as orphans |
+| Component-shape similarity | ✅ shipped | n-gram Jaccard, default threshold 0.7. PartialSimilarity scans both `_*.html.erb` partials and `*_component.html.erb` VC templates |
+| Lookbook integration | ✅ shipped (0.5.0) | `Guardrails::Lookbook::ComponentReport` data API + Railtie auto-registers the `:guardrails` panel when Lookbook is loaded; partial ships inside the gem. Host can override the partial via standard view-path precedence. |
+| ERB-partial structural similarity | ✅ shipped | Same PartialSimilarity engine |
+| A11y integration | ✅ shipped (0.6.0) | Static checks shipped (image_alt, button_name, link_name, input_label). button_name and link_name skip when the element body wraps ERB output — those cases get a `helper_recommended` finding instead. **Deep mode shipped via `Guardrails::A11yDeep`** — consumes axe-core JSON output (single or multi-page) and folds findings into the unified report. `AXE_JSON=path/to/axe.json bundle exec rake guardrails:audit` or `rake guardrails:a11y:deep`. Stayed parse-only (no Capybara / headless Chrome runtime deps) per the original size constraint. |
+| `helper_recommended` detector | ✅ shipped | Flags `<button>` / `<a>` wrapping ERB output and suggests `tag.button` / `button_to` / `link_to`. Pairs with the a11y skip for the same case |
+| Targeted auto-fix | ✅ shipped | See V0 auto-fix table; tailwind_arbitrary now also auto-fixes when a `:tailwind` theme token matches |
+| Sample app in `examples/` | ✅ shipped (0.7.0) | Bootable Rails 7.2 app. `cd examples/demo && bundle install && bin/rails server` renders the seeded views and mounts Lookbook with the Guardrails panel auto-registered. Same tree the integration spec exercises. |
+
+---
+
+## V2 — Advanced
+
+| Item | Status | Notes |
+|---|---|---|
+| Cross-codebase pattern detection | ✅ shipped (0.3.0) | `Guardrails::CrossCodebasePatterns` — fingerprints element subtree shapes, surfaces shapes appearing 3+ times across `app/views` and `app/components`. Drops redundant nested patterns dominated by an outer shape. Verified against Patchvault (24 patterns), Talos (90), Forem (50), Avo (0, expected — ViewComponent-driven). |
+| Class-itis reduction | ✅ shipped (0.4.0) | `Guardrails::ClassItis` — groups elements by `(tag, sorted-class-list)`, reports tuples with >= 5 classes appearing in >= 3 places. ERB-driven fragments are dropped; static portion only. Verified against Forem (27 clusters incl. an `<h1>` repeating 27 times), Patchvault (1), Avo (1), Talos (0 — classes mostly ERB-fragmented). |
+| Visual diff integration | ✅ shipped (0.8.0) | `Guardrails::VisualDiff` parses screenshot-diff tool output and folds findings into the unified report. Initial adapter: snap_diff-capybara (baselines-in-git, the Rails-native default). BackstopJS adapter tracked in issue #15. Same parse-only constraint as `A11yDeep` — no Capybara / Chromium runtime deps. See `doc/VISUAL-DIFF.md` + `doc/RESEARCH-visual-diff.md`. |
+
+---
+
+## Decisions Captured
+
+| Question | Decision |
+|---|---|
+| Tailwind arbitrary values | **In V0.** High signal even outside AI-coded apps. |
+| ViewComponent vs ERB | **Uniform in V0.** Rich support in V1 with Lookbook docs. |
+| Auto-fix | **Suggest in V0** via markdown checklist. **Targeted auto-fix in V1**: raw_color → `var(--token)` with `APPLY=1`. Broad auto-fix not committed. |
+| VS Code extension | **Out of scope.** |
+| Stimulus | **In V0.** |
+| A11y | **Static checks in V0/V1.** axe-core full wrapper deferred — bundling Capybara + headless Chrome was too heavy; documented integration path instead. |
+| Sample app | **Yes, fake-Rails-app structure** (not bootable). |
+| Tailwind v4 | **Supported in V0** via `@theme` directives. |
+| Tailwind v3 (`tailwind.config.js`) | **Supported in V0, colors-only by design.** Best-effort regex parsing of `theme.colors` / `theme.extend.colors`. Non-color tokens (spacing, fontSize, fontFamily, screens) are NOT extracted from v3 configs — projects that want non-color token coverage should migrate to Tailwind v4 `@theme {}` directives, which our existing CSS-custom-property scanner parses cleanly. |
+| Suggestions-md location | `doc/guardrails-suggestions-{TIMESTAMP}.md`. |
+| Near-match handling | Always *suggest* by default. Per-project policy in `guardrails.yml` (`fix` / `leave` / `notify`). |
+| `--strict` flag | **Dropped from V0.** No distinction beyond default exit-1-on-violations until severity levels exist. |
+| Standalone font-size detector | **Folded into inline_style + tailwind_arbitrary.** Type-scale awareness lives in suggest mode. |
+| Near-match threshold | **Max per-channel R/G/B = 4 units (default).** Configurable per-project via `tokens.near_match_threshold` in `guardrails.yml`; ConfigWriter emits a footer comment explaining the scale (0/1/4/10/20+). |
+| Init rerunnability | **Refuses overwrite by default; `FORCE=1` overrides.** Prompts are skipped entirely when overwrite is refused (no questions whose answers won't apply). |
+| MQ scaffold conflicts | **Skip if any matching `@media` block already exists.** Don't augment partial blocks. |
+| ERB-aware a11y | **Resolved via `helper_recommended` detector.** `<button>` / `<a>` wrapping ERB output trip the helper-recommendation rule (suggest `tag.button` / `link_to` etc.); the corresponding a11y rule (button_name / link_name) skips that case so users get one actionable suggestion, not two overlapping flags. |
+| Tailwind utility-name auto-fix | **Shipped.** APPLY=1 rewrites `bg-[#hex]` to `bg-tokenname` against `:tailwind` theme tokens. Variant prefixes (`lg:hover:`, `[&>div]:`) preserved. Suggestion text falls back to `bg-[var(--name)]` when only a `:css_var` token matches (still arbitrary, but parameterized). |
+
+---
+
+## Sample App (`examples/`)
+
+A fake-Rails-app directory tree (no Gemfile or `config/`, not bootable as a Rails server) that exercises every audit. Three roles:
+
+1. **Integration test surface** — `spec/integration/demo_app_spec.rb` runs each audit and asserts concrete counts.
+2. **Showcase / talk material** — clear contrast between `welcome/index.html.erb` (clean) and `welcome/broken.html.erb` (every detector finds at least one violation).
+3. **Onboarding reference** — `examples/demo/README.md` explains what's seeded.
+
+If a bootable Rails server is needed for the talk demo, that's a separate scaffolding step on top of this tree — not currently shipped.
+
+---
+
+## Open Questions
+
+None currently. All four V1 follow-up questions have been resolved (see Decisions Captured below). Add new ones here as they emerge during V2 work.

data/doc/UPSTREAM-snap_diff-issue-draft.md

@@ -0,0 +1,63 @@
+# Upstream issue draft — snap_diff-capybara JSON report companion
+
+> Persistent draft for the ask Guardrails wants to make of snap_diff-capybara upstream: add a JSON companion to the HTML report so mismatch ratios flow through. Kept in-repo as decision/communication history regardless of whether the upstream issue has been filed (and what its status is). If filed, link the resulting upstream issue here.
+>
+> **Upstream issue status:** _not yet filed (awaiting sign-off)._
+> **Target repo:** <https://github.com/snap-diff/snap_diff-capybara/issues/new>
+
+---
+
+**Suggested title:**
+
+```
+Feature: emit a snap_diff_report.json companion to the HTML report
+```
+
+**Suggested labels:** `enhancement`, `report`
+
+---
+
+**Body:**
+
+```markdown
+## Context
+
+Hi, thanks for maintaining this gem — we're integrating it into [Guardrails](https://github.com/meticulous/guardrails), a static-audit gem that consolidates Rails UI-drift findings into a single report (static a11y, view-level drift, partial similarity, ViewComponent / Stimulus audits, etc.). The latest release (0.8.0) adds a snap_diff-capybara adapter for our `Guardrails::VisualDiff` audit, walking `doc/screenshots/` for `<name>.diff.png` files and folding them into the unified report. Works well.
+
+The one gap: we'd like per-finding **mismatch percentages** in the unified report, but the filesystem layout is binary (a `.diff.png` either exists or doesn't). Our current adapter emits `mismatch_ratio: nil` and treats nil as "unconditionally failing" — fine for snap_diff itself, but it means our `VISUAL_DIFF_THRESHOLD=0.02` knob doesn't do anything for snap_diff users (the threshold needs a numeric ratio to filter against).
+
+## Ask
+
+Would you be open to emitting a `snap_diff_report.json` alongside the HTML report? Something like:
+
+```json
+{
+  "generated_at": "2026-05-11T08:23:14Z",
+  "fail_if_new": true,
+  "scenarios": [
+    {
+      "name": "homepage",
+      "viewport": "desktop_1280",
+      "passed": false,
+      "mismatch_ratio": 0.0237,
+      "baseline_path": "doc/screenshots/homepage.png",
+      "current_path": "tmp/snap_diff/homepage.actual.png",
+      "diff_path": "doc/screenshots/homepage.diff.png",
+      "heatmap_path": "doc/screenshots/homepage.heatmap.diff.png"
+    }
+  ]
+}
+```
+
+BackstopJS's `jsonReport.json` is a reasonable shape reference if you want a prior-art example.
+
+## Why not just walk the filesystem (more)
+
+We could read the diff PNGs ourselves to compute mismatch ratios, but that pulls libvips / ChunkyPNG into Guardrails' install footprint — and snap_diff already has the comparison data internally during its run. Keeping image work in the gem that already does image work is cleaner.
+
+## Happy to PR
+
+If the proposal seems reasonable, I'm happy to draft the implementation. Wanted to check on the shape and whether you'd want it gated by an opt-in config option before opening one.
+
+Thanks again for the gem.
+```

data/doc/VISUAL-DIFF.md

@@ -0,0 +1,135 @@
+# Visual-diff integration
+
+Guardrails consumes screenshot-diff tool output and folds findings into the unified audit report — same pattern as [deep a11y](A11Y.md). Guardrails doesn't bundle a browser or run screenshots itself; your existing visual-regression toolchain produces the artifacts, we provide the merge + report + exit-code contract.
+
+The shipped adapter in 0.8.0 is **snap_diff-capybara** (the Rails-native gem; commits baselines to git under `doc/screenshots/`). A BackstopJS adapter is tracked in [issue #15](https://github.com/meticulous/guardrails/issues/15).
+
+## Quick start
+
+In a Rails app with `snap_diff-capybara` installed and system tests that call `screenshot "name"`:
+
+```bash
+# Run your system tests as usual — snap_diff writes baselines/diffs
+# under doc/screenshots/ when assertions fail:
+bundle exec rspec spec/system/
+
+# Then fold the visual-diff findings into the unified audit:
+VISUAL_DIFF=1 bundle exec rake guardrails:audit
+
+# Or run the visual check standalone:
+bundle exec rake guardrails:visual:deep
+```
+
+If the diffs sit somewhere other than `doc/screenshots/`:
+
+```bash
+VISUAL_DIFF_DIR=spec/screenshots bundle exec rake guardrails:visual:deep
+```
+
+To tolerate small mismatches (when the adapter emits a numeric ratio — snap_diff currently emits only a binary pass/fail, see "Adapter limits" below):
+
+```bash
+# VISUAL_DIFF=1 still needs to be set — VISUAL_DIFF_THRESHOLD alone
+# doesn't enable the check, just tunes it.
+VISUAL_DIFF=1 VISUAL_DIFF_THRESHOLD=0.02 bundle exec rake guardrails:audit
+```
+
+## Configuration
+
+### Embedded (Gemfile install) — Rails initializer
+
+Drop a `config/initializers/guardrails.rb`:
+
+```ruby
+Guardrails.configure do |c|
+  c.visual_diff.enabled       = true
+  c.visual_diff.adapter       = :snap_diff           # default
+  c.visual_diff.snap_diff_dir = "spec/screenshots"   # default: doc/screenshots
+  c.visual_diff.threshold     = 0.02                 # default: 0.0 (strict)
+end
+```
+
+With `enabled = true`, `rake guardrails:audit` always runs the visual-diff check; no need to set `VISUAL_DIFF=1` on each invocation.
+
+### Sidecar (no Gemfile change) — environment variables
+
+| Var | Effect |
+|---|---|
+| `VISUAL_DIFF=1` | Enable visual-diff on `rake guardrails:audit` (the standalone `guardrails:visual:deep` task is always enabled). |
+| `VISUAL_DIFF_DIR=path` | Override the snap_diff baseline directory (default `doc/screenshots`). |
+| `VISUAL_DIFF_THRESHOLD=0.02` | Per-finding mismatch ratio above which the audit fails. Currently only meaningful for adapters that emit numeric ratios — snap_diff is binary. |
+
+Env always overrides Configuration.
+
+## How the snap_diff adapter works
+
+The snap_diff-capybara gem commits baseline screenshots to git under `doc/screenshots/<name>.png` and, on test failure, writes a sibling `<name>.diff.png` (changed pixels in red) plus a `<name>.heatmap.diff.png` (variance density). Tests fail on baseline mismatches in CI, so the diff files are an artifact of "this regression slipped through to the artifact directory."
+
+Guardrails walks the configured directory recursively, pairs each `<name>.diff.png` with its baseline `<name>.png`, and emits one finding per pair. `.heatmap.diff.png` files are excluded (visualization companions, not separate findings).
+
+Each finding carries:
+
+| Field | Source |
+|---|---|
+| `scenario` | Path under the screenshots dir, sans `.diff.png` (`checkout/cart` for `doc/screenshots/checkout/cart.diff.png`). |
+| `baseline_path` | Sibling `<name>.png` path, relative to the repo root. |
+| `diff_path` | The `.diff.png` path. |
+| `mismatch_ratio` / `viewport` / `url` / `selector` / `current_path` | All `nil` for snap_diff — see "Adapter limits". |
+
+## Adapter limits (snap_diff)
+
+- **No mismatch percentage.** snap_diff is binary at the filesystem layer — either a `.diff.png` exists (failed) or it doesn't (passed). `Guardrails::VisualDiff` treats `nil` mismatch_ratio as "unconditionally failing", so the audit fails on any diff regardless of the configured threshold. Tracked upstream — when snap_diff-capybara adds a `snap_diff_report.json` companion (or equivalent) we'll wire mismatch percentages through.
+- **No URL / viewport / selector.** Those live in snap_diff's Capybara tests, not the artifact tree. Adapters that have them (BackstopJS, issue #15) populate the optional fields.
+
+## JSON output
+
+When `FORMAT=json` is set on `guardrails:audit`, visual-diff findings appear under `visual_diff:`:
+
+```json
+{
+  "summary": {
+    "...": "...",
+    "visual_diff": 2
+  },
+  "visual_diff": [
+    {
+      "scenario": "checkout/cart",
+      "viewport": null,
+      "mismatch_ratio": null,
+      "baseline_path": "doc/screenshots/checkout/cart.png",
+      "current_path": null,
+      "diff_path": "doc/screenshots/checkout/cart.diff.png",
+      "url": null,
+      "selector": null
+    }
+  ]
+}
+```
+
+## CI
+
+A complete CI loop, end-to-end:
+
+```yaml
+- name: System tests (snap_diff captures baselines/diffs)
+  run: bundle exec rspec spec/system/
+  continue-on-error: true  # don't fail the job here — let Guardrails report
+
+- name: Guardrails audit
+  run: VISUAL_DIFF=1 bundle exec rake guardrails:audit FORMAT=json > findings.json
+
+- name: Upload findings + diff images
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: guardrails
+    path: |
+      findings.json
+      doc/screenshots/**/*.diff.png
+```
+
+## Why parse-only
+
+Bundling axe-core for deep a11y would have meant bundling Capybara + headless Chrome. We didn't, and 0.6.0 shipped a parser instead. Visual-diff is the same trade: bundling Playwright/Chromium would inflate the install footprint for users who don't run system tests. Users who do run system tests already have a screenshot tool; Guardrails layers on top.
+
+See the full evaluation: [`doc/RESEARCH-visual-diff.md`](RESEARCH-visual-diff.md).