docs: cross-browser baseline storage guide and reference sweep

New docs/regression-testing/cross-browser.md covers the full RFC 0002
flow: determinism rationale, provenance statuses and policies, backend
matrix (commit/ci-artifact/service with the §11 exposure-and-cost
tradeoffs), LFS adoption (forward-only, migration guidance), CI jobs, the
blocking-flip criteria (§13 Q2: ≥20 clean containerized compares), and
troubleshooting.

Reference sweep: regression-testing README (shared baseline dir + manifest
sync note), onboarding architecture/pipeline-configuration tables
(visualBaselines key reference), scripts/README, root README script trees,
error-recovery Phase 7 row, and CLAUDE.md (script list, Phase 7 diagram
line, features bullet, key artifacts, honest script count 40→55). Commits
the implementation plan for the branch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Paul Mulligan

CLAUDE.md

@@ -74,11 +74,19 @@ node scripts/visual-diff.js --batch <actual-dir> <expected-dir> [--output-dir di
 # Initialize a new React project
 ./scripts/setup-project.sh my-app --next  # or --vite
 
-# Cross-browser testing (Playwright)
+# Cross-browser testing (Playwright, ad-hoc capture only)
 ./scripts/cross-browser-test.sh chromium http://localhost:3000
 ./scripts/cross-browser-test.sh firefox http://localhost:3000
 ./scripts/cross-browser-test.sh webkit http://localhost:3000
 
+# Cross-browser baselines: pinned-container capture, provenance-verified compare (RFC 0002)
+./scripts/cross-browser-baseline.sh capture http://localhost:3000 [--local] [--dry-run]
+./scripts/cross-browser-baseline.sh compare http://localhost:3000 [--json] [--blocking]
+./scripts/cross-browser-baseline.sh verify [--json]
+
+# Route large baseline sets through Git LFS (visualBaselines.storage = "lfs")
+./scripts/setup-baseline-lfs.sh [--dry-run] [--force]
+
 # Setup Playwright browsers (one-time)
 ./scripts/setup-playwright.sh
 
@@ -292,7 +300,7 @@ Autonomous 9-phase pipeline that converts a Figma design into a working, tested
       ├─ [5]   VISUAL DIFF  → pixelmatch loop → max 5 iterations
       │   └─ [6] E2E TESTS  → e2e-test-generator skill
       ├─ [5.5] DARK MODE   → check-dark-mode.sh (non-blocking)
-      ├─ [7]   CROSS-BROWSER → Firefox/WebKit screenshots (non-blocking)
+      ├─ [7]   CROSS-BROWSER → cross-browser-baseline.sh compare (non-blocking)
       ├─ [7.5] REGRESSION  → regression-test.sh (non-blocking)
       ├─ [8]   QUALITY GATE → [coverage|types|build|tokens|lighthouse] in parallel
       └─ [8.5] RESPONSIVE  → check-responsive.sh (non-blocking)
@@ -306,6 +314,7 @@ Autonomous 9-phase pipeline that converts a Figma design into a working, tested
 - `verify-tokens.sh` — Catches hardcoded values and token drift
 - `verify-test-coverage.sh` — Ensures every component has tests
 - `visual-diff.js` — Pixel-level screenshot comparison with region analysis
+- `.claude/visual-qa/baselines/manifest.json` — Cross-browser baseline provenance (engine, Playwright version, pinned image, sha256, host — RFC 0002)
 - `sync-tokens.sh` — Detects token drift between lockfile and source
 - `check-dark-mode.sh` — Dark mode screenshot capture and visual comparison
 - `generate-stories.sh` — AST-based Storybook story + MDX generation with prop controls, variants, and action args
@@ -317,7 +326,7 @@ Autonomous 9-phase pipeline that converts a Figma design into a working, tested
 - **App-type awareness** — Chrome extensions, PWAs, React Native, and web apps get tailored E2E strategies
 - **Chrome extension E2E** — Playwright persistent context with `--load-extension`
 - Design token extraction with lockfile enforcement
-- Cross-browser verification (Firefox, WebKit) with configurable thresholds
+- Cross-browser verification (Firefox, WebKit) — committed per-engine baselines diffed at the 0.03 cross-engine threshold, with pinned-container capture and per-baseline provenance (RFC 0002; backends: commit | ci-artifact | service)
 - Quality gate: 80%+ coverage, TypeScript, Lighthouse audit
 - Resumable: TodoWrite tracks progress across interrupted sessions
 - **Dark mode verification** — automated dark theme screenshot comparison (non-blocking)
@@ -586,6 +595,8 @@ gh issue create               # Create issue
 ./scripts/audit-cross-browser-css.sh   # Cross-browser CSS audit
 ./scripts/capture-baselines.sh          # Capture regression baselines
 ./scripts/regression-test.sh            # Visual regression testing
+./scripts/cross-browser-baseline.sh     # Cross-browser baseline capture/compare (RFC 0002)
+./scripts/setup-baseline-lfs.sh         # Git LFS opt-in for large baseline sets
 ./scripts/export-design-system.sh       # Export components + tokens as pnpm workspace
 ./scripts/import-design-tokens.sh       # Reconstruct lockfile from an export (round-trip / consumer)
 ./scripts/validate-pipeline-config.sh   # Validate pipeline.config.json against schema
@@ -623,6 +634,6 @@ node scripts/metrics-dashboard.js summary  # Quick metrics summary
 ---
 
 **Last Updated:** 2026-07-01
-**Architecture:** 56 agents, 24 skills, 4 plugins + gh CLI, Figma + Canva + Playwright MCP, 40 scripts, 8 hooks, 5 renderers (nextjs, vite, astro, sveltekit, expo)
+**Architecture:** 56 agents, 24 skills, 4 plugins + gh CLI, Figma + Canva + Playwright MCP, 55 scripts, 8 hooks, 5 renderers (nextjs, vite, astro, sveltekit, expo)
 
 > **Keeping counts in sync:** When adding or removing agents, skills, scripts, or hooks, update all count references across the project. Search for the old count number in `*.md` files to find all references: `CLAUDE.md`, `README.md`, `CONTRIBUTING.md`, `docs/onboarding/`, `docs/react-development/`, and `.claude/AGENT-NAMING-GUIDE.md`. The agent and skill counts are enforced automatically by `scripts/check-doc-counts.sh` (run in CI and on pre-commit), which recounts `.claude/agents/` and `.claude/skills/` and fails on any documented count that disagrees.

README.md

@@ -65,7 +65,9 @@ project-root/
 │   ├── verify-tokens.sh         # Design token enforcement
 │   ├── verify-test-coverage.sh  # Component test verification
 │   ├── visual-diff.js           # Pixel-level screenshot comparison
-│   ├── cross-browser-test.sh    # Playwright multi-browser
+│   ├── cross-browser-test.sh    # Playwright multi-browser (ad-hoc capture)
+│   ├── cross-browser-baseline.sh # Cross-browser baselines + provenance (RFC 0002)
+│   ├── setup-baseline-lfs.sh    # Git LFS opt-in for large baseline sets
 │   ├── setup-playwright.sh      # One-time browser setup
 │   ├── check-dead-code.sh       # Dead code detection (knip)
 │   ├── check-security.sh        # Dependency audit + anti-patterns
@@ -249,7 +251,9 @@ Full catalog: `.claude/skills/README.md`
 ### Testing
 ```bash
 ./scripts/run-tests.sh             # Vitest unit/component tests
-./scripts/cross-browser-test.sh    # Playwright multi-browser screenshots
+./scripts/cross-browser-test.sh    # Playwright multi-browser screenshots (ad-hoc)
+./scripts/cross-browser-baseline.sh # Cross-browser baseline capture/compare (RFC 0002)
+./scripts/setup-baseline-lfs.sh    # Route large baseline sets through Git LFS
 ./scripts/setup-playwright.sh      # One-time browser engine setup
 ```
 

docs/guides/error-recovery.md

@@ -27,7 +27,7 @@ Every phase has characteristic failure patterns. The table below lists the most
 | 5: Visual Diff | Screenshot capture fails, diff threshold exceeded after 5 iterations | Check dev server is running at expected port, lower threshold or fix components |
 | 5.5: Dark Mode | Dark theme not configured, screenshot fails | Non-blocking — add dark mode support or skip |
 | 6: E2E Tests | Browser not installed, test timeout, element not found | Run `./scripts/setup-playwright.sh`, increase timeout in `pipeline.config.json` |
-| 7: Cross-Browser | Firefox/WebKit not installed | Run `./scripts/setup-playwright.sh` to install all browsers |
+| 7: Cross-Browser | No committed baselines (compare skips), provenance flags, Firefox/WebKit not installed | Capture + commit baselines via `./scripts/cross-browser-baseline.sh capture` (pinned container); `./scripts/setup-playwright.sh` for local engines; see `docs/regression-testing/cross-browser.md` |
 | 7.5: Regression | No baselines captured yet | Run `./scripts/capture-baselines.sh` first, then `./scripts/regression-test.sh` |
 | 8: Quality Gate | Coverage below 80%, TypeScript errors, Lighthouse below thresholds | Write more tests, fix type errors, optimize performance |
 | 8.5: Responsive | Dev server not running, screenshot timeout | Start dev server first, check ports |

docs/onboarding/architecture.md

@@ -291,7 +291,9 @@ Located in `scripts/`. These are the automation backbone that agents and pipelin
 | Script | Purpose |
 |--------|---------|
 | `run-tests.sh` | Vitest with coverage |
-| `cross-browser-test.sh` | Playwright multi-browser screenshots |
+| `cross-browser-test.sh` | Playwright multi-browser screenshots (ad-hoc capture, no comparison) |
+| `cross-browser-baseline.sh` | Cross-browser baseline capture/compare with provenance (RFC 0002) |
+| `setup-baseline-lfs.sh` | Route large baseline sets through Git LFS (storage="lfs") |
 | `setup-playwright.sh` | One-time browser engine installation |
 | `capture-baselines.sh` | Capture baseline screenshots for regression |
 | `regression-test.sh` | Visual regression testing against baselines |

docs/onboarding/pipeline-configuration.md

@@ -785,6 +785,71 @@ Visual regression testing against stored baselines.
 
 ---
 
+## Cross-Browser Baselines (`visualBaselines`)
+
+Cross-browser (firefox/webkit) screenshot baseline storage per
+[RFC 0002](../rfcs/0002-cross-browser-screenshot-baseline-storage.md):
+pluggable backend, deterministic pinned-container capture, and per-baseline
+provenance. Shares `baselineDir` with `regressionTesting` (each flow walks
+only its own engines). Full guide:
+[docs/regression-testing/cross-browser.md](../regression-testing/cross-browser.md).
+
+| Field                     | Type                                             | Default                                        | Description                                                                                   |
+| ------------------------- | ------------------------------------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `enabled`                 | `boolean`                                        | `true`                                         | Enable the cross-browser baseline flow.                                                        |
+| `backend`                 | `string` (enum: `commit`, `ci-artifact`, `service`) | `"commit"`                                 | Where baselines live: git-tracked, last-green-main CI artifact, or a SaaS provider.            |
+| `storage`                 | `string` (enum: `git`, `lfs`)                    | `"git"`                                        | commit backend only — `lfs` routes PNGs through Git LFS (`setup-baseline-lfs.sh`).            |
+| `baselineDir`             | `string`                                         | `".claude/visual-qa/baselines"`                | Baseline root, shared with `regressionTesting`.                                                |
+| `screenshotDir`           | `string`                                         | `".claude/visual-qa/screenshots/cross-browser"`| Transient current captures (gitignored).                                                       |
+| `diffDir`                 | `string`                                         | `".claude/visual-qa/diffs/cross-browser"`      | Transient diff images (gitignored).                                                            |
+| `browsers`                | `browserList`                                    | `["chromium","firefox","webkit"]`              | Engines to baseline; must stay within `e2e.crossBrowserBrowsers` (structural check).           |
+| `routes`                  | `string[]`                                       | `["/"]`                                        | Routes to capture.                                                                             |
+| `breakpoints`             | `breakpointMap`                                  | `{ "mobile": 375, "desktop": 1440 }`           | Viewport name → pixel width.                                                                   |
+| `threshold`               | `percentageRatio` (0–1)                          | `0.03`                                         | Cross-engine tolerance; must equal `e2e.crossBrowserDiffThreshold` (structural check).         |
+| `blocking`                | `boolean`                                        | `false`                                        | When `true`, compare exits non-zero on failures (Phase B teeth).                               |
+| `reportFile`              | `string`                                         | `"cross-browser-report.md"`                    | Report filename under `.claude/visual-qa/`.                                                    |
+| `capture.mode`            | `string` (enum: `container`, `local`)            | `"container"`                                  | Container is required for trustworthy firefox/webkit baselines; local is recorded + flagged.   |
+| `capture.image`           | `string`                                         | `"mcr.microsoft.com/playwright:v1.61.1-noble"` | The determinism pin; scripts warn on drift vs the resolved Playwright version.                 |
+| `capture.waitAfterLoadMs` | `integer (≥0)`                                   | `1500`                                         | Wait time before capture, in ms.                                                               |
+| `capture.fullPage`        | `boolean`                                        | `true`                                         | Capture full page.                                                                             |
+| `provenance.manifest`     | `string`                                         | `".claude/visual-qa/baselines/manifest.json"`  | Committed provenance manifest (sha256, engine, image, host, gitSha per baseline).              |
+| `provenance.policy`       | `string` (enum: `warn`, `enforce`)               | `"warn"`                                       | `enforce` excludes flagged baselines from diffing and counts them as failures.                 |
+| `ciArtifact.compareAgainst` | `string` (enum: `last-green-main`)             | `"last-green-main"`                            | ci-artifact backend: which build's artifact PRs compare against.                               |
+| `ciArtifact.retentionDays`  | `integer (≥1)`                                 | `30`                                           | Retention of the published baselines artifact.                                                 |
+| `service.provider`        | `string` (enum: `chromatic`, `percy`)            | `"chromatic"`                                  | service backend: which provider owns capture/diff/review.                                      |
+| `service.projectTokenEnv` | `string`                                         | `"CHROMATIC_PROJECT_TOKEN"`                    | Env var holding the provider project token (set as a CI secret).                               |
+
+```json
+"visualBaselines": {
+  "enabled": true,
+  "backend": "commit",
+  "storage": "git",
+  "baselineDir": ".claude/visual-qa/baselines",
+  "screenshotDir": ".claude/visual-qa/screenshots/cross-browser",
+  "diffDir": ".claude/visual-qa/diffs/cross-browser",
+  "browsers": ["chromium", "firefox", "webkit"],
+  "routes": ["/"],
+  "breakpoints": { "mobile": 375, "desktop": 1440 },
+  "threshold": 0.03,
+  "blocking": false,
+  "reportFile": "cross-browser-report.md",
+  "capture": {
+    "mode": "container",
+    "image": "mcr.microsoft.com/playwright:v1.61.1-noble",
+    "waitAfterLoadMs": 1500,
+    "fullPage": true
+  },
+  "provenance": {
+    "manifest": ".claude/visual-qa/baselines/manifest.json",
+    "policy": "warn"
+  },
+  "ciArtifact": { "compareAgainst": "last-green-main", "retentionDays": 30 },
+  "service": { "provider": "chromatic", "projectTokenEnv": "CHROMATIC_PROJECT_TOKEN" }
+}
+```
+
+---
+
 ## Dead Code (`deadCode`)
 
 Unused export/dependency/file detection.