You’ve inherited a project eight years older than any of the current developers. There’s no documentation, and what exists is lying. “Document the system” has been in the backlog for a year — and will keep hanging there, because it’s phrased wrong. “Document the system” isn’t a task; it’s a sentence.

You don’t need to describe everything

The honest answer to “we have legacy, it’s impossible to make sense of it” is: you don’t have to make sense of all of it. You need to close holes one at a time, starting with the ones somebody has already referenced. The logic is simple: if something got referenced, someone needed it. That is prioritization — free and honest. Everything else can wait — possibly forever, and that’s fine.

A hole is “mentioned but not described.” Someone wrote about the billing worker, and there’s no document about the billing worker. Two documents are clearly about the same thing but don’t know about each other. That’s what we work with.

The first step is manual — I won’t lie

We don’t have a magic “import legacy” button. The start is the same as in any project: meldoc init in the repository, the first .meldoc.md files with an alias and title, scan, push. You define the hierarchy yourself through parentAlias — the CLI doesn’t understand your code’s modules and doesn’t pretend to. Write three to five documents about what you know right now: the entry points, the deploy, the scariest subsystem. Don’t polish them — this is a seed, not a result.

Then meldoc docs shows the tree of local docs with duplicates and orphans flagged, and meldoc validate finds broken links and duplicate aliases (--fix can attach orphaned roots to a parent). Even at this stage the first holes are visible.

The ritual: one hole per sitting

Now comes the part I’m writing this for. In Graphs in Meldoc I described how Meldoc keeps three layers of connections — hierarchy, wiki links and semantic proximity. On legacy, this turns into a practical ritual for an agent through MCP.

Step one — docs_audit with the broken-links check: a literal list of “mentioned but not described,” documents whose [[…]] links resolve to nowhere. Step two — docs_related in suggestion mode: semantically close documents not yet connected by a wiki link. If both mention an entity that exists nowhere — there’s your next hole.

The agent takes one hole, reads the context (for big docs — the heading structure first), creates the missing document or applies a pinpoint edit to a section — without rewriting the whole file, with a preview via dryRun. The document appears — the broken link to it comes alive by itself, the connections recompute. The hole is closed. Repeat tomorrow.

This is not a one-button “find everything undocumented” feature. It’s a recipe made of ordinary tools, and it works because every iteration is small and ends with a closed hole — not with a six-month moratorium.

What it’s all for

After a month of such rituals, the legacy project has a map — not a complete one, but a living one: what’s actually used is described. And when an AI agent lands on that repository, it will have something to read — that was Your AI agent hallucinates because it has nothing to read, and really, the whole series was leading here. Documentation isn’t a museum. It’s holes you close faster than they appear.