lighthouse fixes

site/docs/lighthouse.md

@@ -0,0 +1,51 @@
+# Lighthouse Quality Gate
+
+This project provides a deterministic Lighthouse runner for the required variants:
+
+- mobile + `light`
+- mobile + `dark`
+- mobile + `high-contrast`
+- desktop + `light`
+- desktop + `dark`
+- desktop + `high-contrast`
+
+## Commands
+
+- `npm run lighthouse:run`
+  - runs Lighthouse and writes JSON reports to `site/lighthouse-reports/`
+- `npm run verify:lighthouse`
+  - same as above, but fails if any median category score is below 100
+
+## Run Environment Requirements
+
+- Use a clean Chrome environment (no extensions).
+- Default target URL is `http://127.0.0.1:4321/`.
+- The runner starts `astro preview` automatically for local URLs.
+- To run against production explicitly, pass `--url=https://santhoshj.com/`.
+
+## Scoring Rule
+
+- The runner executes 3 runs per variant by default.
+- For each category (`performance`, `accessibility`, `best-practices`, `seo`), it records per-run scores.
+- The quality gate uses the median score for each category per variant.
+- `verify:lighthouse` requires all medians to equal `100`.
+
+## Gate Scope (Deterministic By Design)
+
+- The default gate target is the home page (`/`).
+- The home page shell is the deterministic quality gate surface and is expected to avoid third-party above-the-fold image dependencies.
+- If additional URLs are added to the gate, they should follow the same deterministic rule for above-the-fold media.
+
+## Useful Options
+
+- `--url=<url>`: target URL
+- `--runs=<n>`: run count per variant
+- `--out=<path>`: report output directory
+- `--assert-100`: enable gate failure when any median is below 100
+
+Environment variable equivalents:
+
+- `LIGHTHOUSE_TARGET_URL`
+- `LIGHTHOUSE_RUNS`
+- `LIGHTHOUSE_OUTPUT_DIR`
+- `LIGHTHOUSE_SKIP_PREVIEW=true` (skip auto-starting preview)