About this site

How these pages are made, what is hand-written and what is rendered, and the rules every number follows.

What is here

Four sections. The story and Systems and subsystems are written by hand for this site, in plain English, and every figure on them carries a source link. The library is every markdown document in the repository (README, CLAUDE.md, the plan, architecture, status, code map, the NSA brief, and every report, run spec, audit, handoff, consult record, working-method skill and review rubric), rendered as it is. The markdown files are the record; these pages are a copy with navigation, diagrams and explainers.

The rule for numbers

A number on a story or spec page is never typed from memory. Each one is written as a citation to a file and, where the file has one, a section; --check-citations fails if the literal number is not found there (the plain build only warns). Decimals, percentages, thousands-grouped numbers and integers of 100 or more must be cited; small counts (ten detectors, 12 layers) may stand alone. The README wins where two documents disagree, and each disagreement is listed below rather than resolved here. Where no document states a number, the page leaves it out.

Footers and versions

Every page's footer names its source file(s) with the first 12 characters of the SHA-256 of that file's bytes. The hash identifies the exact version of the markdown a page was built from; a later commit that changes the file changes the hash, which is how the freshness check notices. Pages carry no commit hash, because a document edited in the same commit as the site cannot know that commit's hash before it exists. The report for this site (docs/reports/2026-09-26_docs-site.md) records the commit each build came from.

How it is built

One standard-library Python script, scripts/build_site.py, reads the markdown corpus and the hand-written sources under docs/site/source/ and writes everything else under docs/site/. The output is committed, so nothing needs building to read the site; it works opened from a checkout (docs/site/index.html), from python3 -m http.server in docs/site, and as a GitHub Pages site from main / docs. There is no runtime dependency: no CDN, no webfont, no library. Diagrams are Mermaid sources pre-rendered to SVG in light and dark by docs/site/source/render-diagrams.js (Node, Playwright, Mermaid 11.17.2); the manifest beside them records each source's hash, and --strict and --check refuse a diagram whose source changed since it was rendered.

uv run python scripts/build_site.py --strict          # rebuild
uv run python scripts/build_site.py --check           # is the committed site fresh?
uv run python scripts/build_site.py --check-citations # is every number where its citation says?
npm pack mermaid@11 && tar xzf mermaid-11*.tgz        # once, anywhere
node docs/site/source/render-diagrams.js --mermaid package/dist/mermaid.min.js
node docs/site/source/verify-pages.js --out /tmp/site-shots   # every page, two widths, two themes

The cost constants

The cost function shown on the home page and the metric page is built from the constants in src/hearsay/metrics.py at build time: C_FA = 4, C_miss = 1, π_synth = 0.3, normalizer 0.3, so the weight on the false-alarm rate is 9.33. The interactive explorer evaluates (4*pfa*(1-0.3) + 1*pmiss*0.3) / 0.3.

What is not here

No 404 page (it would live outside this site's folder). Code links point at GitHub and assume the repository is public and the branch merged to main; document links stay inside this site and work offline. Paths under models/, outputs/, data/, weights/ and the submission TSVs are not in the repository and are shown as plain text.

Discrepancies found while building, routed to the maintainers

These were found while building this site and are recorded here rather than fixed, because the source documents belong to other lanes. Each is routed to the oversight chat; the markdown stays the record until it is corrected there.

The architecture and status documents are dated ~04:40 Saturday. docs/architecture.md §9 and the committed flow diagram still show the previous fusion rule (0.8 / 0.2, "M5 not shipped"); the README and the library's newer reports state the shipped rule. The story pages follow the README and redraw those diagrams; the library renders the documents as they are.
The gated-file mapping. docs/architecture.md §7 states an older formula for the score of a gated file; the code and the gate report record the current one (a block below 0.001, failures below that, a small jitter). The spec page cites the code.
Ratification time. The README says the shipped rule was ratified at 12:03; the status document says ~12:05; the sweep report and the decoding table say 12:20 with the runner's default switched at 12:35. The site shows the README's time and cites each document where it uses its own.
Two roundings of one figure. M1b's In-the-Wild minDCF is 0.342 in the README's detector table and 0.343 in its results table and the sweep; the test share above 0.5 is 27.4% in the README's numbers table and 27.5% in the orchestration ablation (a different readout). Each is cited to its own table.
Stale comments and defaults in code. A pipeline comment, the Docker build script and the Docker entrypoint still name the previous rule or an older default; the orchestration-ablation script defaults to the previous constants file; the Docker build does not stage the M5 checkpoint that the runner's current default needs, so a rebuild as-is would refuse to start (the recorded evidence image ran the previous rule, as the README states). The runner's team default is not our team name, so the team must always be passed.
Docstring versus constant. The speech gate's docstring says "a tenth" of frames voiced where the constant is five percent (the reports and the architecture document agree with the constant).
The role label of Spectra-AASIST in code is "fused" while the rule only lets it suppress; the reports and this site say "suppressor".
Stale line references and file claims in the code map (line numbers for the embedding module; a claim that the Spectra test file does not exist) and in the frontend contract (the verdict rule and a line reference into the speech gate).
A test title says "all five" engineered detectors where it asserts seven registered names.
Five links in the audit records use absolute paths from the Mac; the site rewrites them to the repository paths they point at.