issues-fs.sgit.ai / admin

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 sgit.ai, pki.sgit.ai and graphs.sgit.ai: validate → tag → deploy.

The pipeline

validate

node admin/build/validate.js. Structure, internal links, version agreement, canonical/CNAME agreement, the agent surface, block balance, and two tripwires specific to this site. A failure stops the release: no tag, no publish. It also runs on pull requests, so branch work is gated before it can reach the release branch.

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 — bumped exactly once per release — and 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. That is HEAD on a direct push and HEAD's parent when a pull request lands as a merge commit, so the job anchors on the newest release commit reachable from HEAD rather than on HEAD itself.

deploy

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

What the gate checks

#	Check	Why it is there
1	Version agreement — `version.txt` against every page's badge, the versions table, `llms.txt` and `index.md`; and each release listed exactly once	A blanket version-bump that touches the history table produces duplicate rows, which shipped once on a sibling site
2	Internal links — every relative `href`/`src` resolves to a file in the tree	The cheapest class of error, and the most damaging to trust
3	Canonical host — every page declares a canonical, and every canonical and `og:url` is on the host in `CNAME`	A site assembled from a sibling's pattern can ship a canonical pointing at the sibling
4	The agent surface — every section hub is named in `llms.txt`, and the sitemap and the tree agree in both directions	This site documents three agent-operable surfaces and only one was ever discoverable. For an agent, a page missing from `llms.txt` is a page that does not exist — so it is checked rather than remembered
5	The corrections tripwire — no page may state one of the four false claims as fact	The site exists partly to correct them. A page may show one as false by marking the element `data-corrected-claim`; it may not state one straight
6	Key-leak tripwire — nothing in the tree may look like a vault key	Inherited from the sibling sites, and cheap
7	Block balance — every page opens and closes the same number of `<div>`s	A note box closed with `</p>` is accepted silently by browsers and runs the note's border down the rest of the page
8	Every page carries a “for an agent” block	The house rule is that each page serves three readers — documentation, demonstration, and an agent carrying the rule into another session. Here the third one is the product

The chrome

Every page is hand-written static HTML, and that stays true — a human should be able to open any file and edit it. What is not hand-maintained is the chrome: the nav row (including the version badge that the gate requires to agree everywhere) and the footer columns. Those are defined once in admin/build/chrome.py and rewritten in place across the tree, which is what stops a thirty-page site from drifting.

python3 admin/build/chrome.py      # rewrites nav + footer everywhere, stamps the version
node    admin/build/validate.js    # the gate

Adding a page: add it to NAV or FOOTER if it belongs there, write the file with an empty <nav class="site"></nav> and <footer class="site"></footer>, then run chrome.py. The here state is derived from the page's own path.

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/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/version.txt              the version, owned here
admin/comms.html                     tasks and requests, in public
admin/versions.html                  release history
assets/site.css                      the sgit.ai design language
assets/nav.js  assets/mdreader.js
briefs/                              the source pack, verbatim
CNAME  robots.txt  sitemap.xml  llms.txt  index.md
LICENSE  LICENSES.md                 code Apache 2.0, content CC BY 4.0

Conventions inherited from the network

llms.txt is treated as the whole surface for an agent reader, and each entry carries the page's single most important fact rather than just its topic.
Raw markdown is the source of truth where a document is reproduced; rendered pages are presentation. The sources are published at stable constructed paths.
Open questions are published unresolved, numbered, with the evidence on each side. Q1–Q7.
What we got wrong is recorded rather than edited away. The corrections page.
Voice: short declarative sentences making checkable claims; the argument published before the implementation, and labelled as which; no marketing adjectives.

← The documents Comms: tasks & requests →