Why AI docs fail for low-level kernels (and how a dev fixed it)

Six months into writing TaterTOS64, an x86_64 kernel spanning C, Assembly, and linker scripts, I realized something frustrating: my brain was leaking faster than I could document it. The deeper I dug into paging logic, interrupt vectors, and scheduler hand-offs, the more I needed a way to trace architectural decisions across thousands of lines of code. So, I did what any modern developer would do—I turned to AI documentation tools.

The experiment lasted less than a week before I abandoned it entirely. Not because the tools were bad, but because they were fundamentally unsuited for the task. What I needed wasn’t a polished summary—it was a deterministic, traceable map of how my kernel actually worked. What I got instead was a masterclass in hallucinations.

The three fatal flaws of AI-generated kernel docs

1\. Context amnesia: Where did that constant really come from?

AI tools excel at explaining isolated snippets, but they failed spectacularly at mapping dependencies. When I asked about a constant used in my paging logic, the tool confidently cited a header file that didn’t even exist in my repository. It couldn’t trace #include chains or resolve where a type was actually defined. The documentation it generated looked plausible—until I spent hours manually verifying every claim.

2\. The hallucination loop: Imaginary code with real confidence

The worst part? The tools didn’t just get details wrong—they invented entire functions. My scheduler was described as using a "priority-based preemptive model," even though the actual implementation was a simple round-robin. The AI confidently cited non-existent method signatures in Assembly, mistaking low-level entry points for high-level C abstractions. It was like getting a driver’s manual written by someone who’d only glanced at a car’s exterior.

3\. The SaaS tax: Paying to document your own code

As a systems developer, I build locally. I don’t want to rent access to my own documentation pipeline for $20 a month. Cloud-based AI tools treat your code as input to a subscription service—not as a permanent asset. If I ever stop paying, the documentation vanishes. And the irony? The AI didn’t even understand my kernel well enough to justify the cost.

Building the solution: A compiler for your architecture

After two weeks of abandoning the kernel to its fate, I decided to build the tool I actually needed. I called it TaterBookBuilder—a deterministic documentation compiler designed for low-level systems code.

The core idea was simple: documentation shouldn’t guess. It should derive.

Step 1: Map every dependency before the LLM sees a prompt

TaterBookBuilder starts by crawling your repository to build a physical inclusion graph. It traces every #include (C) and %include (Assembly) to its exact source file, eliminating the guesswork of AI tools. No more wondering, "Where did this constant come from?"—the answer is a deterministic path in your repo.

Step 2: Parse code into a logical hierarchy

Using Roslyn for C#-like parsing and custom regex for Assembly, the tool constructs a logical hierarchy of your system. It automatically identifies kernel boundaries versus user space based on directory structure and hot-path signals—like syscall entry points. This creates a navigable map of your architecture, not just a dump of source files.

Step 3: The Evidence Map—proof that every claim is real

This was the breakthrough. Every statement in the generated documentation is backed by an Evidence Map: a footnote with a specific file path and line range. If the book claims, "The scheduler uses round-robin scheduling," you can jump directly to src/kernel/sched.c:L45-L120 to verify it yourself. No hallucinations. No guesses. Just hard, verifiable facts.

Philosophy: Local-first and perpetual

Documentation isn’t a product—it’s a permanent asset. It shouldn’t vanish if you stop paying a subscription, and it shouldn’t lie to you with plausible-sounding fiction. TaterBookBuilder is built on two principles:

• Local-first: Everything runs on your machine. No cloud dependencies, no API calls, no recurring fees.
• Perpetual: Buy it once, own it forever. The documentation pipeline keeps working exactly as it did on day one, even if the company behind it disappears.

What’s under the hood?

TaterBookBuilder ships as a 77MB Linux AppImage, bundling everything you need—even a static binary of Pandoc—so you don’t install a single dependency. The setup is turnkey: download, run, and generate a professional-grade architecture book in minutes.

Pricing: The JetBrains model

Unlike cloud-based AI tools, TaterBookBuilder follows a one-time purchase model. You buy the tool once, you own that version forever. You get a year of maintenance updates, but even if you don’t renew, your documentation pipeline keeps running. No lock-in. No surprises.

What’s next?

TaterBookBuilder is still evolving. I’m particularly interested in expanding support for Rust-based kernels and integrating interactive call-graph visualization. But the core promise remains unchanged: documentation should be as rock-solid and local as the code it describes.

If you’re a systems developer tired of AI tools that describe your code instead of explaining it, give TaterBookBuilder a try. The trial is waiting—and unlike AI docs, it won’t lie to you.