From 99ebc0898c7dbec918ea2e01624af0a26af23b4b Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Mon, 22 Jun 2026 11:29:38 +0300
Subject: docs(AGENTS): document W3C validation (live service + local nu
 engine)

Explain how to validate generated pages against https://validator.w3.org/
(the Nu HTML checker and the Jigsaw CSS validator) and with the local
vnu.jar (the same engine, offline). Stress validating ONE page per kind
since every page of a kind is template-generated and identical -- bulk
scanning a whole dist/ is wasteful and can fill a tmpfs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENTS.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

(limited to 'AGENTS.md')

diff --git a/AGENTS.md b/AGENTS.md
index f827492..6026c0d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,4 +31,61 @@ firefox "file://$PWD/dist/index.html"
 Use the in-tree `bin/shuriken` and `share/templates/default` (not the installed
 copies) so local changes are exercised. Existing thumbnails/blurs are reused, so
 only the HTML is re-rendered. This regenerates locally only — do **not** run
-`shuriken --sync` / `just sync`, which would publish to the live web servers.
+`shuriken --sync` / `just sync` unless explicitly asked, since it publishes to
+the live web servers (`irregular.ninja` syncs to fishfinger + blowfish).
+
+## W3C validation (HTML + CSS)
+
+Generated pages must stay W3C-conformant. **Every page of a given kind is
+template-generated and structurally identical, so validate ONE page per kind —
+never scan all sub-pages.** A full album is ~10k+ HTML files; bulk-validating
+them wastes time, hammers the public service, and can fill a tmpfs (a stray
+multi-GB validator log once exhausted RAM and broke the build).
+
+The page kinds (one representative each, from a generated `dist/`):
+
+- `index.html` — splash
+- `page-1.html` — preview overview grid (tiles / 2x2 features / subdivisions)
+- `1-1.html` — photo view page
+- `1-1-details.html` — details page
+- `1-0.html` — navigation redirect
+- `stats/index.html` — stats overview
+- `stats/<camera-or-filter>/index.html` — a stats mini-album gallery
+- `stats/<camera-or-filter>/1.html` — a mini-album view page
+
+### Live service — https://validator.w3.org/
+
+HTML, per representative page (the Nu checker that backs validator.w3.org):
+
+```sh
+curl -sS -H "Content-Type: text/html; charset=utf-8" --data-binary @page-1.html \
+    "https://validator.w3.org/nu/?out=json"
+```
+
+CSS is identical across pages, so validate the stylesheet once with the W3C CSS
+validator (Jigsaw). Extract the inline `<style>` block to a file, then:
+
+```sh
+curl -sS 'https://jigsaw.w3.org/css-validator/validator' \
+    -F "file=@album.css;type=text/css" -F profile=css3 -F output=json -F warning=no
+```
+
+Both should report zero errors (`messages[].type=="error"` for HTML;
+`cssvalidation.result.errorcount` for CSS).
+
+### Local Nu engine (offline, no rate limits)
+
+`vnu.jar` is the exact same checker the W3C site runs, so prefer it for repeated
+runs. Download once and validate the representative pages (it checks inline CSS
+too with `--also-check-css`):
+
+```sh
+curl -sSL -o /tmp/vnu.jar \
+    https://github.com/validator/validator/releases/download/latest/vnu.jar
+java -jar /tmp/vnu.jar --also-check-css --errors-only \
+    index.html page-1.html 1-1.html 1-1-details.html 1-0.html \
+    stats/index.html stats/<camera>/index.html stats/<camera>/1.html
+```
+
+No output and exit 0 means all clean. Pass individual files (one per kind) — do
+**not** point it at a whole `dist/` directory.
-- 
cgit v1.2.3