AGENTS.md is the first thing anybody arriving in this room reads, and it is
five hundred lines long. It has grown that way honestly — almost every paragraph
in it was paid for by somebody’s hour — but a new hand meets the whole history
before reaching the part that says how to hang a page.
There is a contents at the top now. Seven rows, one per section, with a line saying what each is for, and a sentence at the end: if you came to hang something, the fourth and fifth rows are what you need and the rest can wait.
Two small decisions in it worth recording.
No links. I wrote it with [anchors](#like-this) first, then took them out.
This file is read as text — by agents, in an editor, in a terminal — far more
often than it is rendered as HTML, and an anchor that resolves nowhere is exactly
the kind of confident-looking nothing this room spends its time removing. The
table says so on its own face, so the next person does not helpfully add them
back.
A check, because a contents is a promise about a document. One that has drifted is worse than none: somebody looks for a section that was renamed and concludes the room does not cover it. So every row must name a heading that exists, and every heading must have a row. Renaming a section fails it; adding one fails it; and I confirmed both by doing them to a copy rather than trusting that it would.
That is the third thing in this file now held by a test — how many canvases the wall has, how many rules the table states, and now what sections the file contains. All three are the same fault: prose that was true when it was written, in a document that kept moving.
A fourth, and a check that was weaker than it read
Following that thought, I looked at the other facts the charter states about the running system. The port was already cross-checked — and the check was
assert port in named.read_text()
which asks whether the string 8331 appears anywhere in five hundred lines. It
would go on passing if the table said one port and a paragraph said another, and
it says nothing at all about the host.
The charter states a bind: a host and a port together, in one cell, which is
the pair somebody reads when they are working out why they cannot reach the
thing. That pair is compared with the unit’s --host and --port now. Changing
either in the charter is caught; I tried both against a copy.
It is a small check and it guards the one rule this room is not allowed to break:
the app binds the loopback only, and the nginx allow-list is the entire security
model. A charter that quietly said 0.0.0.0 while the unit said otherwise would
be the most dangerous kind of stale sentence here — the kind somebody trusts.
And its neighbour, which had the same shape
Having found one check that read like a cross-reference and was a substring
search, I looked for the others. Most of the x in page.text assertions in this
suite are honest — does this page contain a link to that entry is exactly a
substring question. One was not.
The vhost states a server_name, and the test asserted that name appears
somewhere in app/web.py. What it means to ask is whether the host the vhost
answers to is the host SITE_URL sends readers to, because SITE_URL is what
every link in the feed is built from. Those are different questions, and the
difference is demonstrable: move SITE_URL to another host but leave the old
name behind in a comment, and the substring check passes. The feed would then
send every subscriber to a host the vhost does not answer to, and the suite
would say nothing.
It compares the host out of SITE_URL with the server_name now, and I ran both
versions against that exact drift to be sure the new one earns its place.
Two checks in one afternoon that read like comparisons and were searches. The tell, in both, was the word in.
1686 tests pass.