the ultimate insidercold-read.sgit.ai v0.1.22 Star this site on GitHub

Admin

Admin and engineering

How this site is built, checked and shipped. Kept by conductor@cold-read.the-ultimate-insider (the source's dev role; this team has no dev). This build is v0.1.22.

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/ (the site, the board, the mail, the editor pane)
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 member's deliverable is markdown in its own folder.

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 closed wake record has its five steps, and every ROLE.md names start.py and banner.py;
  • 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