There is a guides section on this site as of this morning. It has one guide in it. I have written sixteen.

That ratio is the post.

The sixteen have been sitting in a folder since August, and every time I looked at the list I told myself they were nearly ready. Formatting. A read-through. Somebody's closing paragraph. The usual fortnight that turns into a month.

Then I actually read one, start to finish, as though I were someone who had come to the site to build the thing it described. And it was very good, and completely useless.

What was missing was not polish

The guide was about monitoring a fleet of AI agents — how to know which of them ran last night, which one is about to run out of room, and which one you have not heard from in three weeks. I built that system in April and it has been running since. I know it well. The guide had the design, the costs, the trade-offs, and four genuinely hard-won lessons in it.

Here is what it did not have: a schema. An endpoint. A hook script. A single command you could type. Two thousand words about a system and not one line of how to build it.

I had written an essay and put the word "guide" at the top of it.

That distinction sounds pedantic until you try to follow one. An essay about a system tells you what the author concluded. A guide tells you what to do next, and then tells you what you should see when you have done it — so that when nothing happens, you know which of the last four things you got wrong. The gap between those two documents is not tone. It is whether the reader ends the evening with a working thing or a vague sense that they should have understood more.

So the rebuild was not an edit. It was eight numbered steps, two hundred and sixty lines of real code, and a check after every single step. That took a morning, which is roughly how long I had spent over the preceding month telling myself the guide was nearly ready.

And then somebody asked the obvious question

This is the part I would not have found on my own, and it is the reason I am writing this rather than just quietly shipping the guide.

The rebuilt guide had two halves. First, how to build the thing. Second, six failures from the real system — the six ways my own monitoring lied to me over five months. An agent that was switched off being credited with a sixteen-minute session. A context measurement that turned out to be a file size divided by a number I made up. Two safety mechanisms that between them showed a working agent as offline for two hours. A compliance figure I got wrong by a factor of fifty.

Every one of those six failures reported success. Not one threw an error. That is the entire spine of the piece, and it is a subject I have written about before.

Which is when it was pointed out to me that a guide making that argument contained no way to check for any of it.

I had put a confirmation after each build step, and I was pleased with them. But look at what those confirmations actually do: every one proves that the thing you just did worked. Not one would catch any of the six a week later, when the real damage happens — when you add an agent, change a hook, or upgrade a model and something starts quietly lying.

I had written a guide about not trusting green lights and handed the reader eight green lights.

Six queries, and two of them told me I was wrong

The fix was a new section: six queries, one per failure, none taking more than a second. Is anything arriving twice. Are there sessions that never reported. Is any model being measured against the wrong window. Is anything closing sessions that are still alive. Is every event you registered actually turning up. Is anybody writing handovers at all.

Then — and this is the only part of the morning I would call a discipline rather than a task — I ran all six against my own database before publishing them.

Two came back and refuted me.

I had written "you should see no rows" on a check that returns ten on my own system, all of them scars from a bug I fixed in July and deliberately never cleaned up. The lesson that fell out of that is worth more than the check: an "expect zero" test against a table you never prune will fail permanently the first time you have a bug, and then you will train yourself to ignore it. Date the check, not the count.

And I had confidently described five sessions as evidence of a race condition when they are nothing of the sort — they are sessions where the only hook that ever fired was the closing one, which by design writes no heartbeat. Perfectly healthy. I had written the wrong expectation into an audit of a system I built myself.

Both corrections are in the published guide rather than quietly edited out, because a check you have learned to explain away is worse than no check at all.

One query, though, earned its place completely. I wrote it expecting nothing and it returned the outage — three agents whose sessions were marked finished up to a minute before their own last heartbeat, every one dated to the two days before I fixed that bug in August. Nothing since. I did not hand it those dates. It found them in five months of data, given nothing but the shape of the fault.

That is the argument for auditing what your system contains rather than reviewing what your code says, and I could not have made it up. The bug was invisible while it was happening, invisible to review before that, and trivially visible in the table three weeks later to anyone who thought to ask the data instead of the code.

What the series actually is

So: sixteen guides, one published, fifteen to go, and each one gets signed off on its own rather than as a batch. The section will fill up slowly and that is deliberate.

They are not tutorials. There is no shortage of tutorials, and most of them work beautifully right up until the moment yours does not. Every one of these is a thing I actually built and am actually running, written to the same shape:

Everything is measured on the day of writing. Where a number in a guide came from a code comment or an earlier draft rather than a query I ran myself, I have gone back and run the query — and in the first guide that alone moved a headline figure by a third, because the version I had been carrying since August was simply out of date and perfectly plausible.

The first one is Know What Your Agents Did Overnight. Two database tables, one shell hook, about fifty lines of PHP, and roughly seventy-six megabytes to know what two dozen agents have been doing since April.

It also contains the single most useful thing anyone has told me about my own operation, which I did not design for and only noticed because I went looking for a closing paragraph. I read those agent handovers most mornings — and a good proportion of what is in them is not the agent's unfinished work at all. It is mine.