How this site is built
Hand-written static HTML, one generated chrome definition, and a pre-release gate that has to pass before anything is tagged or published. Same pipeline as every other *.sgit.ai site: validate → tag → deploy.
Desks. The PHP desk: the work, the roles of the people and agents, and the evidence vault, open read-only, for the PHP flaws story of October 2026 (card 089).
The pipeline
validate
node admin/build/validate.js. Structure, links, version agreement, canonical/CNAME agreement, the agent surface, block balance, the agent-block rule, the provenance contract, and the redaction watch-list. A failure stops the release: no tag, no publish.
tag-release
Every push to dev is a release and ends tagged v{release}.{major}.{minor}. The version is owned by admin/build/version.txt and must agree with the release commit's subject.
deploy
Publishes the tagged commit to GitHub Pages. Never runs when validation failed, never from a pull request.
What the gate checks
| # | Check | Why it is here, specifically for this site |
|---|---|---|
| 1–7 | Version agreement, links, canonical, agent surface, key-leak, block balance, agent block | The shared core, inherited from every sibling site |
| 8 | The provenance contract — every block marked class="provenance" must state a first-published date and link to the original | This site's central argument is that most articles do not provide evidence and the link is never followed. A page here that failed its own contract would have refuted the site on page one |
| 9 | The redaction watch-list — a fixed list of Tier 3 strings (a named VC, an infra account number, live product pricing) may never appear anywhere in the published tree | The source material contains real commercial and safety-sensitive detail. The gate makes the exclusion structural rather than a habit somebody could forget |
The chrome
Every page is hand-written static HTML. The nav row and footer columns are defined once in admin/build/chrome.py and rewritten in place across the tree on every run.
Since v0.12.12 the nav block also carries the site's colour and the bar's layout, in that order, as the first things in the body of every page: assets/themes/themes.css (the five themes, every token in every theme, and the rules that shadow the imported stylesheet's literal colours), assets/themes/themes.js (a classic script that sets data-theme on <html> from what this browser remembers, before the first paint, and draws the picker) and assets/site-nav.css (the bar on one row in both looks, with the tools as one cluster). The rule that a stylesheet names a colour through a token, and the tokens themselves, are in assets/themes/README.md; admin/build/test_themes.mjs keeps it, and admin/build/shots_themes.mjs takes the pictures. The design note is five themes, and the bar on one row.
Since v0.12.60 the front page is this site's own: admin/build/front.py writes index.html in three views (Broadsheet, Briefing, Your desk; all in the page, data-view on <html> shows one, set by assets/front/front.js before the first paint and kept under newsroom.view), index.md, about/index.html and articles/front.json, from the wire, articles/find.json (admin/build/find.py: desks, controlled tags, series, formats, reading time) and the editor's words in admin/content/front/. admin/build/desks.py writes the desk pages. The nav block also carries the reading strip and highlights (assets/reader/) on every page with the meter: scrolled and read per section, kept in the browser, and highlights by quote (test: admin/build/test_reading.mjs). admin/build/agents.py writes the agents' pages and Written by the agents, from admin/content/agents.json. admin/build/deps.py writes what the site still takes from sgit.ai. Test: admin/build/test_front.mjs.
python3 admin/build/find.py # findability: articles/find.json
python3 admin/build/front.py # the front page in three views, index.md, about/, articles/front.json
python3 admin/build/desks.py # the desk pages
python3 admin/build/gen_documents.py # reader pages for every document under briefs/
python3 admin/build/gen_llms_full.py # the whole document set as one fetchable file
python3 admin/build/chrome.py # rewrites nav + footer everywhere, stamps the version
node admin/build/validate.js # the gate
Making a release
1. bump admin/build/version.txt (vX.Y.Z, exactly once)
add a row to admin/versions.html
update admin/comms.html
2. python3 admin/build/gen_documents.py (only if briefs/ changed)
python3 admin/build/gen_llms_full.py
python3 admin/build/chrome.py
3. node admin/build/validate.js
4. git commit -am "site vX.Y.Z: ..." && git push origin dev
The repository
.github/workflows/deploy-pages.yml validate → tag → deploy
admin/build/validate.js the gate
admin/build/chrome.py the single definition of nav and footer
admin/build/front.py the front page in three views (index.html, index.md, about/, articles/front.json)
admin/build/find.py findability: desks, tags, series, formats, reading time (articles/find.json)
admin/build/desks.py the desk pages
admin/build/deps.py what the site still takes from sgit.ai (admin/notes/sgit-ai-dependencies.md)
admin/build/gen_documents.py reader pages from briefs/, raw md stays the source
admin/build/gen_llms_full.py llms-full.txt — the whole document set in one fetch
admin/build/version.txt the version, owned here
admin/comms.html tasks and requests, in public
admin/versions.html release history
assets/site.css assets/nav.js the sgit.ai design language
assets/vendor/marked.min.js vendored, not CDN — MIT, see LICENSES.md
assets/mdreader.js renders a brief in-page from its raw markdown
thesis/ corrections/ provenance/ economics/ rights/ newsroom/ library/
shipped/ network/ documents/ about/
briefs/ the source pack, verbatim, CC BY 4.0
CNAME robots.txt sitemap.xml llms.txt llms-full.txt index.md
LICENSE LICENSES.md code Apache 2.0, content CC BY 4.0
v0.2.0's scope decision, stated rather than hidden
The site architecture in briefs/05 specifies several sections — rights, the newsroom, the thesis — as multi-page trees. v0.2.0 ships each of those as one comprehensive hub page rather than the full subpage tree, to get the whole architecture live and gated in one release instead of shipping half of it. That is a real de-scoping, tracked as open work on comms, not a silent shortcut.