# CLAUDE.md — website-evaluator

## Overview

A Docker-based website audit pipeline. Given a URL it runs screenshots (Playwright),
Lighthouse audits (desktop + mobile), and DOM analysis, then assembles a structured
Markdown report optimised for consumption by Claude.

## Repository Structure

```
website-evaluator/
├── ABOUT.md               # One-line description for context-load menu
├── CLAUDE.md              # This file
├── MEMORY.md              # Index of memory topic files
├── FUTURE.md              # Ideas not on the active roadmap
├── README.md              # Human-readable overview and quick start
├── SPEC.md                # Index of spec files
├── spec/                  # Per-subsystem specs (WE-P, WE-S, WE-L, WE-D, WE-R)
├── src/
│   ├── index.js           # Entrypoint — arg parsing and pipeline orchestration
│   ├── screenshot.js      # Playwright screenshot capture (desktop + mobile)
│   ├── lighthouse.js      # Lighthouse audit runner (desktop + mobile presets)
│   ├── dom-analysis.js    # DOM metadata extraction via Playwright
│   └── report.js          # Markdown report assembly
├── Dockerfile             # Node 20 + Playwright base image
├── .dockerignore
├── package.json
└── scripts/
    └── verify-m1.sh       # Smoke test: run against example.com, check outputs
```

## Tech Stack

- **Runtime:** Node.js 20, ES modules (`type: "module"`)
- **Screenshots + DOM:** Playwright (Chromium)
- **Audits:** Lighthouse 12 + chrome-launcher (uses Playwright's bundled Chromium)
- **Base image:** `mcr.microsoft.com/playwright/node:20-noble`

## Running Locally (Docker)

```bash
# Build
docker build -t website-evaluator .

# Run — output lands in ./output/
mkdir -p output
docker run --rm -v "$(pwd)/output:/output" website-evaluator https://example.com

# Output
output/
  report.md                # Primary artifact — feed this to Claude
  screenshots/
    desktop.png
    mobile.png
  raw/
    lighthouse-desktop.json
    lighthouse-mobile.json
    dom.json
```

## Environment Variables

| Variable     | Default    | Purpose                          |
|---|---|---|
| `OUTPUT_DIR` | `/output`  | Where to write all output files  |

URL is passed as a CLI argument. `TARGET_URL` env var is also accepted as fallback.

## Spec Prefixes

| Spec file          | Prefix | Domain                     |
|---|---|---|
| pipeline.md        | WE-P   | Orchestration + I/O contract |
| screenshot.md      | WE-S   | Screenshot capture           |
| lighthouse.md      | WE-L   | Lighthouse audit             |
| dom-analysis.md    | WE-D   | DOM metadata extraction      |
| report.md          | WE-R   | Report structure + tone      |

## Conventions

- ES modules throughout (`import`/`export`, `.js` extensions in imports)
- Async/await — no callbacks
- Each module exports one primary function; no side effects at import time
- Errors propagate to `index.js` which handles process exit
- `console.log` for progress, `console.error` for failures

## Milestones

| # | Scope | Status |
|---|---|---|
| M1 | Core pipeline: screenshot + Lighthouse + DOM → report.md | In progress |
| M2 | `--analyze` flag: calls Claude API, appends AI recommendations | Future |
| M3 | Comparison mode: before/after and competitor diffs | Future |

## Gitea

- **Org:** `skynet`
- **Remote:** `git@gitea.oreillyit.nz-ai-enablement:skynet/website-evaluator.git`