Nobody messed up. The page just got left behind by the code, the way they all do.
So I deleted it. Then I deleted the habit that kept making it.
This is the part of Bodhiorchard, the open-source dev workflow I've been building on my own, that I get the most pushback on. So let me actually make the case. Including where it doesn't hold.
Every wiki you own is lying to you
You just haven't caught it yet.
It starts honest. Someone writes up how the payments service works, and that day it's perfect. Then the code moves. A field gets renamed. A flow reroutes. A service splits in two.
Nobody updates the page. Not out of laziness. Updating the page is everyone's job, so it's nobody's.
Six months later a new hire reads it, believes it, and ships a bug.
By then the wiki isn't documentation. It's a museum of how things used to work.
We've all quietly signed up for the same deal: pretend the wiki is current, then grep the code when you actually need an answer. The grep is the real documentation. The page is decoration.
The reason docs rot isn't discipline
It's that a wiki is a second copy of the truth.
You write it by hand. You keep it next to the thing it describes. The two drift apart. Always. Two copies of one fact, updated by different people on different days, will diverge. That's not a team failing, it's just entropy.
Code can't drift from itself. It's the thing that runs. When the doc and the code disagree, the code wins, because the code is what's live at 2am.
So the whole thing rests on one line:
The code is the wiki.
Not "we document well." Not "the docs sit near the code." The list of what your system does gets generated from the source, on its own, and never gets hand-written in the first place. You can't forget to update something that was never separate.
The baseline scan
Connect a repo and Bodhiorchard scans it. It doesn't ask you to describe anything. It reads the call graph, the module boundaries, the route handlers, the history, and pulls the live features straight out.
My own run came back with this:
Baseline scan complete.
4 repositories indexed
19 active features extracted
312 code locations linked
0 pages written by a human
Nineteen features. Each one traceable to the exact files that back it. I typed none of it. Nobody keeps it current.
Two things make this more than a fancy grep.
First, it indexes code locations, not just words. Every fact points back to a real file and symbol:
{"feature":"Idempotent refund webhook handling","summary":"Bank may resend the same refund webhook up to 3x; processed once.","code_locations":["payments/src/webhooks/refund.handler.ts:24","payments/src/guards/refundGuard.ts:8","shared/db/migrations/0041_refund_dedupe.sql"],"linked_repos":["payments","shared"],"last_synced_commit":"9f2c1ab"}
Ask "how does refund idempotency work?" and the answer gets rebuilt from that. Not from a paragraph someone wrote at launch.
Second, it links across repos. A frontend call gets wired to the backend handler it actually hits. The thing wikis are worst at, "where does this logic continue," is the thing a code graph is best at.
And it doesn't go stale, because staleness is designed out:
on PR merge to main:
-> re-scan the affected paths
-> update the feature's code_locations + commit history
-> re-embed for semantic search
-> flag anything the diff orphaned
Every merge updates the feature that changed. The next person, or agent, to touch it inherits today's truth. A daily job sweeps for drift, so it shows up as a flag instead of a production incident.
You don't even open a dashboard to read any of this. You ask in plain English in Slack, and the answer comes back with a link to the code it came from.
What it changes day to day
Onboarding stops starting from a lie. A new engineer asks what the system does and gets an answer built from what it does today, files attached. Not the version from two refactors ago.
Status questions get answered from reality. "Are we on track for the P3 item, and what's the go-live date?" comes back from the live record, not a number someone typed into a board last Tuesday.
And your AI agents stop reasoning from stale context. This is the one I underrated. An agent is only as good as the context you hand it. Feed it a six-month-old wiki page and it'll cheerfully build on an architecture that's already gone. You get a clean PR that's wrong in a way that costs you an afternoon to spot.
That's why I stopped treating AI context files and human docs as two separate things. They're one thing with two readers. Generate them from one source, or watch them split apart the way the wiki did.
Where it stops
I'm not going to tell you this kills documentation. It doesn't. And where it stops matters.
Auto-extraction is great at what exists and where. It's useless at why.
A scan can tell you there's an idempotency guard on the refund webhook and point you at the line. It can't tell you the guard is there because one bank resends webhooks three times and double-refunded a customer back in March. That's intent. You earn it through pain, and no scan will ever infer it.
So the why still needs a person. In Bodhiorchard it lives in the BUD: one markdown file per feature, holding the intent, the criteria, the decisions.
# BUD-241 Β· Idempotent webhook handler for refunds
## Intent
Bank resends the same refund webhook up to 3x. We must process exactly once.
## Why this is hard (the part a scan can't infer)
- 2026-03 incident: duplicate webhook -> double refund. Don't regress this.
- An already-refunded txn must be REJECTED, not silently retried.
## Acceptance criteria
- Duplicate webhook IDs are a no-op (return 200, no state change)
- Illegal transition complete -> pending is impossible
The BUD is written by a human. But it's versioned, it's searchable, and it travels with the code as context for every agent. So even the human part stays alive instead of rotting in a tool nobody opens.
That split is the point. Machines maintain what rots fastest. People own what machines can't. The busywork dies, the judgment stays.
Try it, and tell me where it breaks
Bodhiorchard is Apache 2.0, self-hosted, and runs on a Mac mini in the corner of my room. Your repos, embeddings, and audit log never leave your hardware. I built it on my own time. The regulated fintech I run engineering at is where I felt this pain. It's not what owns the code.
Repo, with six demo videos and four sample repos to point it at: https://github.com/mickyarun/bodhiorchard
Full methodology: https://bodhiorchard.ai/
I'm not after stars. I'm stuck on one question.
Does "the code is the wiki" survive contact with your team? Or does the why sprawl back across five tools no matter how good the extraction gets? And if it does, where does it leak first?
I spent fifteen years maintaining wikis that were wrong by Friday. I finally stopped. If you've killed a doc tool and lived to tell it, what broke first: the tool, or your team's trust in it?
I'm Arun, CTO and co-founder of Atoa, a UK open banking payments platform, and the solo author of Bodhiorchard. I write about what building with AI is actually like, not what the conference slides say. Find me on X @mickyarun.