M1: initial scaffold — pipeline, specs, source, Dockerfile

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -0,0 +1,71 @@
+# website-evaluator
+
+A Docker-based website audit tool. Given a URL it captures screenshots, runs
+Lighthouse audits (desktop + mobile), extracts DOM metadata, and assembles a
+structured Markdown report designed to be read by Claude for design critique
+and improvement recommendations.
+
+## Quick Start
+
+```bash
+# Build the image
+docker build -t website-evaluator .
+
+# Evaluate a site
+mkdir -p output
+docker run --rm -v "$(pwd)/output:/output" website-evaluator https://example.com
+
+# Feed the report to Claude
+# Open output/report.md and paste it into a Claude conversation with:
+# "Here is a website evaluation report. Please analyse it and suggest improvements."
+```
+
+## Output
+
+```
+output/
+  report.md                # Primary artifact — structured Markdown for Claude
+  screenshots/
+    desktop.png            # Full-page desktop (1440×900)
+    mobile.png             # Full-page mobile (375×812)
+  raw/
+    lighthouse-desktop.json
+    lighthouse-mobile.json
+    dom.json
+```
+
+## What the Report Covers
+
+- **Lighthouse scores** — Performance, Accessibility, Best Practices, SEO (desktop + mobile)
+- **Core Web Vitals** — LCP, TBT, CLS, TTFB with status labels
+- **Critical issues** — Pre-interpreted findings with "so what" explanations and fix guidance
+- **Page structure** — Title, meta description, canonical, heading hierarchy, images, links
+- **Accessibility detail** — WCAG violations grouped by impact level
+- **Performance detail** — Opportunities and diagnostics with estimated savings
+- **SEO detail** — Meta, robots, canonical, structured data
+
+## Milestones
+
+| # | Scope | Status |
+|---|---|---|
+| M1 | Core pipeline: screenshot + Lighthouse + DOM → report.md | ✅ Complete |
+| M2 | `--analyze` flag: Claude API integration, AI recommendations | Planned |
+| M3 | Comparison mode: before/after and competitor diffs | Planned |
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| `scripts/verify-m1.sh` | Smoke test: builds image, runs against example.com, checks all outputs exist |
+
+## Architecture
+
+```
+URL in
+  └─▶ Playwright: screenshot desktop (1440px) + mobile (375px) + DOM extraction
+  └─▶ Lighthouse: desktop audit
+  └─▶ Lighthouse: mobile audit
+  └─▶ Report assembly → /output/report.md
+```
+
+Built on `mcr.microsoft.com/playwright/node:20-noble` — Chrome is bundled, no separate install needed.