Why documentation was never the product

I have been shipping products with coding agents for about a year. The mistakes that cost me real time were never syntax. The agent knew how to call the library. It did not know whether that library was the right one, whether the version it had in mind still existed, or what would break in the specific version sitting in my lockfile.

Two of those cost me a full day each. Once, an agent pinned a package to a release that was never published, and the install failed in CI rather than locally, so I lost the afternoon to a bisect. Another time it reached for an auth library whose v5 had been in beta since 2025 and wrote against a mix of the v4 and v5 APIs, both of which are described in the same docs site. Neither is a documentation failure. In both cases the documentation was fine and reachable.

Sonatype's 2026 report put a number on the first shape of this. Across 36,780 samples of AI dependency upgrade suggestions, 27.76% pointed at versions that were non-existent, deprecated, or unsafe, including more than 10,000 releases that exist in no registry (Making AI Work Safely). That is not an edge case rate. That is roughly one suggestion in four, on the single decision that is hardest to notice going wrong, because a wrong version looks exactly like a right one until something fails.

What the docs tools actually do

Context7, Docfork, and the rest of the docs MCP market do one job: given a library you have already chosen, fetch current documentation for it so the model is not working from a two-year-old snapshot. That job is real and it is worth doing. It is also the second half of the problem.

The numbers say the first half is not covered. Firecrawl's DevDex benchmark scores Context7 at 46.6% recall on the documentation track and 16.8% overall, the gap being repository and issue-to-fix queries it does not index at all. The documentation number is respectable for what it is. The two it drops are the questions I actually have when something breaks.

The commercial side has been shaky too. Context7 cut its free tier from roughly 6,000 calls a month to 1,000 in January 2026. Docfork, an MIT-licensed docs MCP, shut down on 14 June 2026, endpoints and keys included. An audit of 1,847 publicly listed MCP servers put 52% of them in an abandoned bucket, though it was published by a company selling managed MCP hosting, so read the framing with that in mind. If you are wiring a tool into an agent a team depends on daily, that base rate matters as much as the benchmark does.

A verdict is a different object

So I stopped trying to improve documentation retrieval and wrote down what I actually wanted the agent to receive. It came out as a small, fixed structure:

One question, phrased with its constraints, because "auth for a Next.js app" has no correct answer and "auth for a Next.js app, solo dev, free tier, email and Google login" has one. One pick, with the version it was tested against. One alternative, and the condition under which the alternative is the better choice. What to avoid, and why. The traps at that version. A skill to follow. The sources, each with the date a person read it.

The alternative's condition is the field that most comparison content skips, and it is the one that makes the document usable by something that is not me. An agent cannot tell whether it is the exception unless the exception is written down.

None of this is retrieval. Every field is a judgment somebody made and signed. That is the part a scraper cannot produce, and it is also the part that goes stale.

Which is why every verdict expires

A claim about software is true on a date and not after. Most technical writing hides this: the post is dated, the claim inside it is not, and by the time it is wrong nothing about the page has changed.

So every verdict carries the version it was tested against and a recheck date. A nightly job reads the package registries. When a pick's latest release moves past the tested version by a major, the verdict is served with a RECHECK flag on the first line until a person verifies it again. It is still served, because a stale answer that says it is stale beats a fresh guess that says nothing. The agent gets both the answer and the warning, and it can decide what to do with the version numbers.

That is the bet: not better documentation, but a layer above it that says what to use, carries the date it was checked, and admits when the check has gone stale.