Admin

Admin and engineering

How this site is built, checked and shipped. Kept by dev@the-ultimate-insider. This build is v0.1.4.

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

1. git fetch origin dev && git merge --ff-only origin/dev
2. ./run-website-locally.sh: build, gate, serve on port 8000. The version reads pending: only CI numbers releases.
3. Commit with a subject that says what changed and why, with no number in it, and push to your branch, then to dev.
4. 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.
5. 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, read from git, and as data in versions/index.json.

Where everything is

• The brief, published in full.
• The release history.
• The team: each member's role, scope, status and debriefs.
• The board: the team's Issues-FS vault, read live.
• About and disclosure.
• llms.txt, the index for agents.