sharness.ai / admin

How this site is built

Static HTML with no framework, plus a handful of small stdlib-only tools that keep it consistent. The design pages are written in markdown and their HTML is generated from it; the front page, the CLI, status and admin pages are hand-written HTML. Modelled on the *.sgit.ai sites (nfrs.sgit.ai in particular), using the same pipeline and gate. The conventions are documented at coding.sgit.ai.

The tools

File	Job
`admin/build/version.txt`	Owns the site version. Bumped exactly once per release.
`admin/build/chrome.py`	The single definition of the nav, the footer and the version badge, rewritten in place across every page. Also stamps the version into `llms.txt` and `index.md`.
`admin/build/validate.js`	The pre-release gate: version agreement, internal links, canonical host against `CNAME`, a vault-key-shaped-string tripwire, and generate or date every number. Any failure stops the release.
`admin/build/gen_pages.py`	Generates each design page's `index.html` from its `index.md` twin, which is the source of truth and is served as-is. `--check` fails CI when any HTML is stale.
`admin/build/gen_articles.py`	Generates `/articles/`: each article's page and markdown twin, and the index, from the sources in `admin/content/articles/`. Those sources are in the newsroom's format (front matter, lead figure, the three anchors) so they import into newsroom.sgit.ai unchanged; the gate holds them to it. `--check` runs in CI.
`briefs/`	The source design pack, verbatim. Never edited: corrections go into the next revision of the pack.
`admin/build/gen_sitemap.py`	Writes `sitemap.xml` from the tree, with each page's last commit date.
`admin/build/gen_llms_full.py`	Writes `llms-full.txt`: the agent surface in one fetch.

The pipeline

.github/workflows/deploy-pages.yml, in this order:

validate: runs the gate, and gen_pages.py --check. It also runs on pull requests, so branch work is gated before it reaches the release branch.
tag-release: every push to dev is a release. The version in version.txt must match the release commit's subject (site vX.Y.Z: ...), and must be the next minor or a deliberate major bump. CI then tags the release commit.
deploy: publishes the tree to GitHub Pages. A push to main, or a manual run, deploys without tagging. Never runs when validation failed.

Cutting a release

# 1. bump admin/build/version.txt, add a row to admin/versions.html
python3 admin/build/gen_pages.py && python3 admin/build/gen_articles.py
python3 admin/build/chrome.py
python3 admin/build/gen_sitemap.py && python3 admin/build/gen_llms_full.py
node admin/build/validate.js
git commit -am "site vX.Y.Z: ..." && git push origin dev

← What exists today Comms →