How it is built

A static site, generated by a small Python build with no dependencies, served as plain files. No framework, no client-side rendering: every page is complete HTML before any script runs, and the one script on the site (the findings filter) only hides and shows rows that are already there.

The files

Path	What it is
`data/findings.json`	The register. The source of every finding page, list, filter and count
`data/exemplars.json`	What good looks like: things that work, each linked to the findings it answers
`data/principles.json`	The principles, each with a rule, a reason and a test
`data/taxonomy.json`	The problem, visibility and recommendation vocabularies findings are indexed by
`data/lab.json`	The design lab: vaults and read keys, directions, screenshots, decisions
`data/site.json`	Name, navigation, the products findings belong to (sites, platform, prototypes, browsers), the sibling sites
`data/versions.json`	The release history; the first entry is the current version
`content/*/.md`	Hand-written pages, with `{{directives}}` the build fills from the data
`admin/build/build.py`	Builds every `.html`, its `.md` twin, `llms.txt`, `llms-full.txt`, `sitemap.xml`
`admin/build/md.py`	The markdown renderer (stdlib only)
`admin/build/gate.py`	The release gate
`assets/`	One stylesheet, one script, the icon
`lab/shots/`	Phone screenshots from the lab's vaults
`findings/img/`	Evidence screenshots attached to findings

Build and check

python3 admin/build/build.py     # write every generated file
python3 admin/build/gate.py      # must print GATE PASS
python3 -m http.server 8000      # then open http://localhost:8000/

The gate

CI runs it on every push, and a release is the commit it passes on. It fails if:

any generated file is stale (the build is re-run and compared byte for byte), or any .html in the tree is not generated;
a finding is missing a field, uses an unknown product, area, problem, visibility, recommendation, kind, severity, status or principle, repeats an id, has a date that is not a date, or attaches an image that is missing or has no alt text;
a principle, problem, visibility or recommendation has no finding that uses it;
an internal link or #anchor on any page goes nowhere, or a page has no markdown twin;
a colour is written anywhere but the token block at the top of assets/site.css;
the version disagrees between data/versions.json, the pages, llms.txt and index.md;
a lab screenshot named in data/lab.json is missing, or a credential that is not a published read key appears in a tracked file.

Versions

The version is shown once, in the footer, and links to what changed.

Each release bumps the last number (v0.4.0 → v0.4.1), unless the project lead asks for a larger step. Every release gets an entry in data/versions.json naming what changed and the files it touched.