Documentation That Cannot Drift

Technical documentation decays in a predictable way. Someone writes a page explaining how a system works, pastes in a code sample, and it is accurate. Then the code changes and the page does not, because nothing connects them. Six months later the sample is fiction, and the only people who find out are the ones who trusted it.

This matters more than usual for us. nimimo's architecture papers describe how keys are derived and how encryption works. A stale sample there is not an inconvenience. It is a security claim that has quietly stopped being true, published under our name on a page that argues you should verify rather than trust us.

So the papers do not contain code samples. They contain references to code, and the references are resolved from the actual source when the site builds.

How it works

In the markdown for a paper, a code block is written as a fence that names a file and a named region inside it:

```source path="lib/recovery/crypto.ts" region="derive-pin-key"
```

The region is marked in the source file itself, with comments that sit around the code being quoted:

// #region derive-pin-key
export async function derivePinKey(pin: string, salt: Uint8Array): Promise<CryptoKey> {
  // ...
}
// #endregion derive-pin-key

At build time the fence is replaced with whatever currently sits between those two markers, then syntax-highlighted. The published page shows the real function, not a copy of it made on the day the page was written.

The part that matters: it fails loudly

Resolving code at build time is only half of it. The half that makes it work is what happens when the reference breaks.

If a paper points at a file that no longer exists, or a region that has been renamed or deleted, the build throws. Not a warning, not a placeholder, not an empty block that ships silently. The build stops and names the paper and the missing region.

• Rename a region and forget the paper: build fails
• Move a file and forget the paper: build fails
• Delete a function a paper quotes: build fails
• Change the function's body: the paper updates itself, no action needed

That last line is the payoff. The common case, code evolving normally, needs no intervention at all. The paper tracks it. The failure cases are the ones where a human genuinely has to decide something, and those are the only ones that interrupt anyone.

Named regions, not line numbers

A fence can also quote a raw line range, and that option exists mostly to show why it is the worse one. Line numbers are correct until somebody adds an import at the top of the file, at which point every range below it silently shifts by one and quotes the wrong code.

A named region moves with the code it wraps. Insert twenty lines above it, reformat the file, move the function to a different position, and the markers travel with the function, and the paper keeps quoting the function. Line ranges are checked for going out of bounds, but a range that is merely wrong and still in bounds is exactly the failure this whole mechanism exists to prevent.

So regions are the default and ranges are the escape hatch for code that cannot carry a comment.

Why not just be disciplined

Because discipline does not survive contact with a deadline. Every team that has ever let documentation rot was staffed by people who intended to keep it current. Intent is not a mechanism.

This is the same reasoning that runs through the rest of the architecture. We do not ask you to trust that nimimo will not touch your keys; we arrange things so that it cannot. Removing the capability to do harm is more durable than promising not to, and it holds when everyone is tired and the release is late.

A build that fails on drift is that idea applied to prose. It does not require anyone to remember. It requires them to notice, which a failing build guarantees.

What it does not cover

The mechanism verifies that quoted code is current. It does not verify that the surrounding paragraphs are still true. You can have a perfectly up-to-date function sitting underneath an explanation that stopped matching it two releases ago, and no build will complain.

Prose still needs review. What changes is the failure mode: the sample and the source can no longer disagree, so a reader who trusts the code block is on solid ground even if the narrative around it has drifted. The most load-bearing part of the page is the part that cannot lie.

It is a narrow guarantee. We think narrow guarantees that actually hold are worth more than broad ones that depend on somebody remembering.