Hearth: The Documents

Aug 2026 – Sep 2026 · age 44

What it was

The prose that governed Hearth, where a model writes the code and a person writes the rules. The load-bearing document is the agent's instruction file: a layout generated from the source tree, a description of the gate that keeps documents true, and numbered invariants, each a bold sentence with why it exists and what broke without it. Beside it sit a mission statement, a README, a third-party notice and, from September 9, a security document written as a threat model. In mid-August there were about 8,600 lines, including a 4,000-line manual and priced landing-page copy for a community product. On September 1 they were cut to about 2,150 lines, and the mission was rewritten three times in six hours.

Wins, for the age

• At forty-four, Jeff wrote a specification a model reads every session, with a script that fails the build when a link, flag, recipe, schema version, invariant number or quoted test count drifts.
• Hand-cut the invariants from 169 to 132 rather than keyword-filtering them, because a filter "would have left the file quietly wrong". Deciding which rules still held took a primate reading every one.
• Kept a "Not verified" section naming what nobody had proved: real mail, a real certificate authority, a real Hevy call, a race. It is the honest alternative to a mock that agrees with the code.
• Wrote a security document whose last row names the operator: "Whoever runs the machine: everything; nothing".

What it taught

• The mission is the first document a model reads, so it is the first to be wrong. Each rewrite was Jeff learning what was wanted by watching what the model built.
• A manual for a product nobody runs is a liability. The August one contradicted itself and documented a recipe that did not exist; deleting it fixed all of that.
• A gate checks shapes, not truth. At the end the file still claimed HSTS was not sent, which was false.
• Reproduce every finding from the outside first, the old test-first discipline written into the rules.

Genealogy

Ancestors: Adama Docs: a platform's worth of prose, and the habit of writing to be read. Descendants: none on record. A model still reads it at the start of every session. Part of: Hearth.

Epitaph

Here lies nothing yet. Jeff wrote the rules for a model to follow, deleted half of them, and the half that stayed is the clearest specification this human ever wrote.