cli.sgit.ai / Engineering
Engineering: how this site is built and released
One folder of content, one generator, one gate, one version number. Deployed to https://cli.sgit.ai by GitHub Pages on every push to dev, the same pipeline as sgit.ai and pki.sgit.ai.
The shape
| Path | What it is |
|---|---|
admin/content/<path>.md | the source of the page at <path>.html: flat front matter, then markdown |
admin/content/articles/<slug>.md | one article; adding the file publishes it (the contract) |
admin/content/reference/sgit-cli-reference.json | the output of sgit help all --format json; the command reference is generated from it |
REALITY.md, BRIEF-CORRECTIONS.md | at the repository root, published as Reality and Corrections |
admin/build/build.py | the generator: pages, markdown twins, nav and footer, llms.txt, llms-full.txt, sitemap, assets/version.js |
admin/build/md.py | the markdown renderer, from pki.sgit.ai and newsroom.sgit.ai; escapes everything, so content cannot carry HTML |
admin/build/validate.js | the gate |
admin/build/import_sgit_ai.py | moves pages from sgit.ai, from their markdown twins (what moved) |
admin/build/import_cli_research.py | publishes documents from the CLI repository as articles |
admin/build/version.txt | the site version, the one place it is written |
.github/workflows/deploy-pages.yml | validate, tag, deploy |
Every generated file is listed in admin/build/generated.json, and the build deletes a listed file it no longer produces, so removing a content file removes its page and its twin.
Releasing
- Bump
admin/build/version.txt(vX.Y.Z, once per release) and add a row toadmin/content/admin/versions.mdwith one sentence on what changed and why. python3 admin/build/build.pynode admin/build/validate.jsgit commit -am "site vX.Y.Z: ..." && git push origin dev. Thesite vX.Y.Z:prefix is load-bearing: the tag job finds the release commit by it and refuses a release whose newest prefix disagrees withversion.txt.- Check that https://cli.sgit.ai/assets/version.js serves the new version. A clean push is not a release.
The gate
node admin/build/validate.js fails the build on any of these, in CI on every push and pull request, before anything is tagged or deployed:
| Check | Why |
|---|---|
The build is current (build.py --check) | a page edited by hand, or content committed without building, ships something the source does not say |
The version agrees: version.txt, assets/version.js, llms.txt, one row in the release history | the badge on every page reads version.js; a release without its row has no record |
| Every internal link and asset resolves | an orphaned or misspelled link is a page nobody can reach |
Every page has a canonical link on the CNAME host, and a markdown twin, and is in llms.txt | pages agents cannot read, or that claim to live elsewhere |
| No page is an orphan: every page is linked from another page | a page nothing links to is unpublished in practice |
| The leak tripwire: vault-key shapes, private-key markers, cloud and provider key prefixes, across every file | this site discusses keys constantly; it must never contain one |
| Advisory, not failing: em-dashes in prose on this site's own pages | the estate's writing rule; pages moved or published verbatim keep their authors' punctuation |
Against the estate's guidance
Every sgit repository lists what each repository carries. Where this one stands at v0.1.0:
| The guidance asks for | Here |
|---|---|
| The brief, published in full | yes, with the initial prompt |
| A reality file and a corrections file | yes, yes |
| One version, up on every push, shown on every page | yes: version.txt, the badge, the release history |
| A gate that fails the build | yes, above |
Machine-readable twins and llms.txt | yes, generated from the same source |
| Licences and a participant disclosure | yes: Apache-2.0 for code, CC BY 4.0 for content, the disclosure |
| Nav and footer injected at build | yes, from one definition in build.py |
| A credentials tier that is never committed | .local/ is gitignored; nothing in this repository needs a secret to build |
The review folder (review/) | not yet, recorded in the reality file |
| Roles and a board, as files | not yet, recorded in the reality file |
| A release script that verifies the live site | not yet: step 5 above is by hand |
This page as markdown · its source, admin/content/admin/index.md