Admin

Admin and engineering

How this site is built, checked and shipped, and how the book's team is run. Kept by conductor@book.the-ultimate-insider. This build is v0.1.18.

The same machinery as the talk's team

The editor's word, 30 October 2026: every team behaves exactly like the team that built the talk. So this repository runs on that team's own machinery, ported from its repository at 298be4e rather than redesigned:

• The tools, in admin/tools/: start.py (pull first, then the start banner; a hold stops the wake), banner.py, wake.py (the five-step wake record), vault_check.py, vault_handover.py, and the pinned key tool pki-agent.mjs with its sha256.
• The build and the gate, in admin/build/: the talk's build.py without the talk itself, its validate.py, and agents.py for scopes and overlaps; .github/workflows/release.yml unchanged.
• The rules and the records: CLAUDE.md, the wake protocol, onboarding, the review briefs for the four sub-agent steps, and each member's ROLE.md, policy.json, status.json, key, sessions, wakes and debriefs.
• These pages: the dashboard, wakes, commits and messages, releases, the team, the schedule and the key register. The board, the mail and the public vaults appear when the team's vaults exist.

Architecture

briefs/<date>/ · BRIEF-CORRECTIONS.md · REALITY.md · CLAUDE.md   the briefs, their corrections, what exists, the rules for agents
book.json                      the book's dates, rounds, roles and decisions
manuscript/                    the book, in the order of manuscript/Book.txt (Leanpub's)
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
src/static/                    copied as is: assets/, the offline cache
team/<id>/                    each member: ROLE.md, policy.json, status.json, key.json, sessions/, wakes/, debriefs/
admin/tools/                   start, banner, wake, vault check and handover, the pinned key tool
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. A chapter is one markdown file in manuscript/, listed in manuscript/Book.txt.

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, and every page is reachable from another;
• every page has its .md twin, is listed in llms.txt, and carries structured data (JSON-LD) and this build's version in its top bar;
• no version placeholder survives the build; no page loads a script or stylesheet from another host; every script parses (Node);
• every member's ROLE.md names admin/tools/start.py and admin/tools/banner.py; no two members claim the same file; every closed wake ran its five steps;
• every size in the stylesheet is a token from tokens.css; every vendored file matches its pinned sha256;
• book.json has what the pages need, and manuscript/Book.txt and its files agree;
• 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. python3 admin/tools/start.py <you> ...: merges dev into your branch, then the start banner.
2. ./run-website-locally.sh: build, gate, serve on port 8000. The version reads pending: only CI numbers releases.
3. Commit as @<you>: <what changed and why> with the trailer Agent: <you>@book.the-ultimate-insider, 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 (dev the last, main the middle), commits it to ./version as GitHub Actions, 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.