How I keep my homelab wiki up to date
Created
My homelab has a private wiki: what runs where, how each service works, why I decided things, and the gotchas I hit the hard way. AI agents do most of the work in my homelab, so the wiki is their memory as much as mine. A wiki like that is only useful if it is true, and documentation usually goes stale the week after it is written. These are the few rules that keep mine current without me doing the filing.
1. Filing is part of done
No job is finished until the wiki says how things work now. An agent that changes a service, finishes research, records a decision or hits a gotcha updates the right page before it tells me the work is done. If it truly can’t, it leaves a short note in an inbox folder and the next agent files it. Work tracked on a task stays open until its page is written.
So the wiki doesn’t depend on me remembering to update it. It moves with the work.
2. One writer at a time
Several agents can work at once, so the wiki has a single claim: an agent runs wiki begin, gets a token, writes, then
runs wiki commit with only the files it changed. If someone else holds the claim, it waits. The claim lives on my
storage box, so it covers every copy of the wiki, including my own edits in
Obsidian, which a small job syncs every few minutes under the same claim.
Commit refuses anything that isn’t in the agent’s list of files, and it never resets or merges someone else’s work.
3. Checks on every commit
Before anything is saved, a checker runs: valid page headers, a one-line summary, tags from a fixed list, links that resolve, unique page names, and an updated date that never moves backwards. Pages that describe a system list their sources: the files in my repositories they summarise, pinned to a version. A commit with any problem is refused until it’s fixed.
4. A weekly look for drift
A page can be correct when written and wrong a month later, because the code it describes changed. Once a week a lint job compares each page’s pinned sources with what the repositories hold now and lists the pages whose sources moved, plus orphans, broken links and system pages untouched for 60 days. The full report stays private; a short summary reaches me as one line. When something needs work, it becomes a task like any other.
I learned one lesson the hard way here: a changed source must show up as a finding in the report, not crash the whole job. For a day the lint failed silently because one pinned file had moved.
5. The public edition is a separate, stricter path
Some pages, like this one, are also published on my site. Only pages on an explicit list leave the private wiki. Each one is cleaned, scanned against a private list of words that must never go public, rewritten for a reader by a second model, reviewed by a third, and built in an isolated guest before it is deployed. A page that fails any step simply stays private.
What it adds up to
- The wiki changes when the system changes, not when someone has time to write documentation.
- There is never more than one writer, so nothing is lost or overwritten.
- Drift gets caught on a schedule instead of when something breaks.
The rules are short enough that every agent reads them at the start of its work, and that’s most of the trick.