subscriptions.sgit.ai / admin

Admin & engineering

This site is hand-written static HTML with two build tools and one gate. Nothing is compiled, there is no framework, and a human can open any page and edit it. What is not hand-maintained is the chrome and the version, because a site whose legal armour depends on structure should not drift.

One definition of the chrome

admin/build/chrome.py holds the nav, the footer and the version badge, and rewrites them in place across every page in the tree. It also stamps the version into llms.txt, llms-full.txt and index.md.

The pre-release gate

admin/build/validate.js runs before anything is tagged or published, on pushes and on pull requests. A failure stops the release: no tag, no deploy. Five checks:

CheckWhat it catches
Version agreementAny page badge, the versions table, or either text twin disagreeing with version.txt.
Internal linksEvery relative link and source in every page must resolve to a file in the tree.
Canonical hostEvery page must declare where it canonically lives, and it must be on the host in CNAME.
Key-leak tripwireNothing in the tree may look like a vault key.
Record, never verdictEvery fragment marked .regentry — a register entry — is checked against a published blocklist of verdict words (unfair, dishonest, scam, worst, best…). A hit fails the build. This is the source's own instruction — “a CI check should grep register pages for a published adjective blocklist” — made real.

The pipeline

Every push to the release branch runs .github/workflows/deploy-pages.yml in three stages, the same pipeline as the sibling repositories (SGit-AI__Website, __PKI, __NFRs):

1

validate

The gate above. Runs on pull requests too, so branch work is checked before it can reach the release branch. A failure here means no tag and no publish.

2

tag-release

Every push to the release branch is a minor release, ending tagged. The version is owned by version.txt, bumped exactly once per release, and it must also appear in the release commit's subject as site vX.Y.Z:. CI verifies the two agree, that the bump is the next minor or a deliberate major, and then tags the release commit. Historical tags are backfilled from commit subjects, idempotently.

3

deploy

Publishes the tagged commit to GitHub Pages. Runs on manual dispatch even without a tag, and never when validation failed.

The release process

  1. Bump admin/build/version.txt once, and add a row to admin/versions.html. Update comms if the state of play changed.
  2. python3 admin/build/gen_documents.py — only if a source document was added or changed.
  3. python3 admin/build/chrome.py — propagates the version and any nav or footer change everywhere.
  4. python3 admin/build/gen_sitemap.py && python3 admin/build/gen_llms_full.py
  5. node admin/build/validate.js
  6. git commit -am "site vX.Y.Z: …" && git push origin dev

The tree

← The documents Comms →