sg-sentinel.sgit.ai / admin / engineering

How this site is built

Static HTML in the sgit.ai design language — no framework, no build step to view (open index.html and it works). The only generated artefacts are the document reader pages; the only runtime JS is the in-page markdown reader on those pages, with a raw-file fallback. Same engineering approach as nhi.sgit.ai.

Structure

Path	What it is
`index.html` + five pages	The narrative: problem → idea → architecture → proof → method → roadmap. Hand-written, hand-built inline SVGs, no JS.
`briefs/`	The 23 packet documents, markdown, byte-verbatim from `sg-sentinel-website-packet`. The source of truth for every claim.
`documents/`	One reader page per document — summary, key concepts, key ideas, in-page rendering. Generated by `admin/build/gen_documents.py`; adding a document is one dict entry.
`code/sentinel/`	The 115-file `sentinel/` package snapshot, verbatim from the packet. Every code excerpt on the site comes from here.
`assets/`	`site.css` (the shared stylesheet, sgit.ai design language) and `mdreader.js` (the in-page markdown reader: marked + optional mermaid, fallback to the raw file on any failure).
`admin/`	Engineering: this page, versions, comms, and `build/` (version.txt, validate.js, gen_documents.py).

Release process

Bump admin/build/version.txt (vX.Y.Z, exactly once per release) and add a row to versions; update comms.
If documents changed: python3 admin/build/gen_documents.py.
node admin/build/validate.js — the pre-release gate.
git commit -am "site vX.Y.Z: ..." && git push origin dev.

Every push to dev runs .github/workflows/deploy-pages.yml: validate → auto-tag → deploy to GitHub Pages. The tag (vX.Y.Z) is verified against version.txt and the commit subject, and the bump must be the next minor (or a deliberate major). A push to main is deploy-only (no tag), usable as a test or fallback. Same pipeline as SGit-AI__Website.

The validate gate

admin/build/validate.js fails the release (no tag, no publish) on any of:

Version disagreement — every page's version badge, the versions table, llms.txt and index.md must all carry the version that version.txt owns, and each release must appear exactly once in the history table.
Broken internal links — every relative href/src in every page must resolve to a file in the tree.
Key/credential leaks — nothing in the tree may look like an sgit vault key or an AWS access key id. The site shows deploy commands; it must never contain a credential.

Content rules (from the website brief)

Accuracy above all — everything on the site is traceable to the packet; if the briefs don't say it, the site doesn't claim it.
Don't overclaim status — local targets proven; the live AWS path code-complete and unit-tested via in-memory doubles, not yet run against a real CloudFront distribution. Stated wherever status appears.
Real code, real commands only — excerpts come verbatim from code/sentinel/ and the testing manual; no invented snippets, no invented metrics.

The brief itself is captured with the rest of the corpus: the website brief.

← Release history Comms →