Writing the manual my homelab never hadproject

My homelab runs my family’s digital life: photo backups, document archives, media, and our smart home. And for most of its existence, the knowledge of how it all worked lived in exactly one place, which was my head. Nobody sets out to become a single point of failure. But documentation is the chore that always loses to the next project (and there’s always a next project), and after enough years of losing that dice roll, you end up with infrastructure your family depends on and a bus factor of one.

The failure mode isn’t hypothetical. A few times a year something breaks, inevitably late at night, and I sit there reverse-engineering a decision that past-me made, confidently, for reasons he wrote down nowhere. He’s a sharp guy, but he keeps terrible records.

So I built Alexandria, named with all due modesty after the ancient library (I’m aware of how that one ended; mine has backups). It’s a private git repository of chapters covering every host, every service, and every configuration that differs from a default, along with the reasoning behind it. That scope rule matters: stock settings need no documentation. The things I changed are exactly the things I’d otherwise have to rediscover at the worst possible time.

I didn’t write most of it. An AI model with read-only access walks the live systems over SSH (installed packages, mount tables, container configs, DNS zones) and drafts each chapter from what is actually running, not from what I remember deploying. Those are rarely the same thing, and the gap between them is precisely what documentation exists to capture. My job for Alexandria, much like this blog, is the audit: I read every chapter and correct it. Documentation rots because writing it is expensive; reviewing it is cheap enough to actually happen.

A few conventions keep the result trustworthy. Chapters describe current state, never plans; a runbook is allowed to look forward, a reference is not. Every chapter carries the date it was last audited, so staleness is visible instead of silent. When something can’t be verified against the live system, it gets an explicit marker in the text rather than a confident sentence, because an unverified claim in documentation is a small landmine with a long fuse. And secrets appear by variable name only, never by value. Those back up elsewhere.

The decision I went back and forth on was publishing. A hosted documentation site is nicer to read, and standing one up would be trivial. But Alexandria is, by construction, a complete map of my network’s attack surface: internal addresses, security posture, the works. I’ve read far too many stories of other enthusiasts’ networks being hijacked (e.g., for crypto mining or holding personal files ransom). Instead, it stays a private repo, readable offline with nothing but a git clone, which is conveniently also the only version that still works when the network itself is the thing that’s broken.

I didn’t predict who its real reader would be. I consult it occasionally, in short bursts. The AI, however, consults it constantly, following a purpose-built skill I authored; before we change anything in the lab, the relevant chapter gets read first, every time. These are tokens well spent. I set out to write a manual for a future version of me and ended up writing one that my tools read more often than I do. That realization, that the manual’s real reader had quietly become the machine, changed how I wrote the thing, and eventually earned an essay of its own. Its real exam is scheduled for some unknown 11pm fire drill, the next time something breaks and the answer needs to already be on the shelf. I like its odds better than mine.