# Admin and engineering

> How this site is built, gated, released and versioned, how to add a page, and where everything lives.

*Source: <https://the-ultimate-insider.presentation.sgit.ai/admin/index.html> · site v0.1.23 · generated from the same content as the page, so the two cannot drift.*

---

Admin

# Admin and engineering

How this site is built, checked and shipped. Kept by [dev@the-ultimate-insider](../team/dev/index.md). This build is [v0.1.23](versions.md#v0.1.23).

## Architecture
`BRIEF.md · BRIEF-CORRECTIONS.md · REALITY.md · CLAUDE.md the brief, its corrections, what exists, the rules for agents site.json the site's name, address and top-bar navigation src/pages/**.html page bodies: a <!--meta {...} --> line, then the <main> content, nothing else content/articles/*.md articles, markdown with front matter src/static/ copied as is: assets/, talk/ (talk.json, the slides, the engine, the player) team/<id>/ each member: ROLE.md, policy.json, status.json, debriefs/ admin/build/build.py the build: _site/ from all of the above admin/build/validate.py the gate admin/build/agents.py the team checks: scope, overlaps, unowned files .github/workflows/release.yml gate every push; number, tag, build and deploy dev and main version written only by CI`

## Adding a page

A page is one file. Write the body only, with no head, navigation or footer, starting with its meta line; use `../` for links to the site root:
`<!--meta {"title": "...", "description": "..."} --> <section class="wrap narrow"> ... </section>`

The build then produces, for free: the page with the top bar (and the version in it), the footer, canonical, Open Graph and JSON-LD tags, its `.md` twin, its line in `llms.txt` and its entry in `sitemap.xml`. An article is one markdown file in `content/articles/`; a slide is one folder in `src/static/talk/slides/` plus its beat in `talk.json`.

## The gate

`admin/build/validate.py` fails the build on any finding, on every push and again on the release commit:

- every internal link and image resolves against the built files;
- every page is reachable: some other page links to it;
- every page has its `.md` twin, is listed in `llms.txt`, and carries structured data (JSON-LD);
- every page shows the version in its top bar, and it is this build's version;
- no version placeholder survives the build;
- no page loads a script or stylesheet from another host;
- every script parses (Node);
- every beat of the talk has a slide, a title, a script and a planned length;
- no two members of the team claim the same file;
- every vendored file matches its pinned sha256;
- no em-dashes in prose;
- the leak tripwire: private keys, cloud and API key shapes and sgit vault key shapes, in every tracked and every built file.

## Releasing

- `git fetch origin dev && git merge --ff-only origin/dev`
- `./run-website-locally.sh`: build, gate, serve on port 8000. The version reads `pending`: only CI numbers releases.
- Commit with a subject that says what changed and why, with no number in it, and push to your branch, then to `dev`.
- CI runs the gate, then one release job at a time picks the next number, commits it to `./version` as GitHub Actions with the subject `site vX.Y.Z: <your subject>`, tags it, builds that commit, gates it again and deploys it.
- The deploy polls the live `version.txt` until it serves the new number. A release is not done until it does.

Every release is listed in the [release history](versions.md), read from git, and as data in [versions/index.json](versions/index.json).

## Where everything is

- [The brief](../brief/index.md), published in full.
- [The release history](versions.md).
- [The team](../team/index.md): each member's role, scope, status and debriefs.
- [The board](../team/board.md): the team's Issues-FS vault, read live.
- [About and disclosure](../about/index.md).
- [llms.txt](../llms.txt), the index for agents.

---

*[Site index for agents](../llms.txt) · [HTML version](https://the-ultimate-insider.presentation.sgit.ai/admin/index.html)*