In Part 1 I covered what OpenWiki is — LangChain’s take on Karpathy’s “LLM Wiki,” applied to codebases. In Part 2 I ran it for real and learned that model choice makes or breaks an agentic doc run. This part is about the thing I didn’t get on the first pass, and what happened when I chased it: diagrams.
It turned into the most satisfying leg of the whole experiment — because it ended not with a workaround in my own copy, but with a pull request against the actual project.
OpenWiki produced a genuinely good wiki for my Spring Boot + Angular monorepo — architecture overview, auth flow, domain model, API surface, the works. All accurate, all source-grounded.
All prose and tables.
Not a single diagram. And for a codebase, that’s a real miss. The fastest way to explain a JWT refresh handshake or how Booking, Event, and Settlement relate isn't a paragraph — it's a picture. A newcomer skims a sequence diagram in five seconds and gets it. So the obvious question: can I get OpenWiki to draw?
If you want diagrams that live inside a docs-as-code wiki, the format matters. I went with Mermaid [1], and the reasoning is worth stating because it’s the same logic that makes OpenWiki itself work:
Mermaid is just fenced markdown — a ``` mermaid block. It stays diffable, it versions alongside the code, and it renders where the docs already live. (One honest caveat: GitHub and GitLab render it natively; Bitbucket's file view historically does not, so verify your host before assuming inline rendering. Agents and Obsidian read it fine either way.)
Here’s the thing that clicked. OpenWiki [2] is prompt-driven — under the hood it’s an LLM writing markdown files. If it can write a table, it can write a ``` mermaid block. Diagrams aren't a missing feature; they're a missing instruction.
So I ran a deliberately tight, one-off pass on an isolated copy — using Opus, the reliable choice from Part 2 — asking it to add exactly two diagrams and touch nothing else: a sequence diagram of the auth flow, and an ER diagram of the core entities. “Read only the files needed to make these accurate.”
It nailed it. Not “plausible-looking” — accurate. It opened the actual auth interceptor and read the token lifetimes out of config. The sequence diagram it produced:
It even captured the single-in-flight-refresh behaviour — the detail where concurrent 401s queue behind one refresh call — because it read that out of my interceptor. And in the ER diagram it correctly drew one relationship as a “soft link,” having noticed that a foreign-key-shaped column was actually a plain Long with no ORM relation. That's the difference between a diagram that helps and one that lies.
Then I tried to render the sequence diagram. It failed.
Not the content — the syntax. Opus had written a message label like store new token; queue concurrent 401s. In a Mermaid sequence diagram, a semicolon is a statement separator. That one ; split the line into a second, malformed statement, and the parser rejected the entire block. On GitHub it would have rendered as nothing — or as a raw error box.
The content was correct. A single poison character made it un-renderable.
This is the lesson worth carrying: auto-generated diagrams need a validation pass. The model gets the meaning right and occasionally gets the grammar wrong, and Mermaid has a few characters — semicolons, pipes, unescaped angle brackets — that quietly detonate inside labels. A mermaid lint step in CI catches this class of bug for free.
A one-off prompt gave me diagrams once. But I run openwiki --update on new commits — would the diagrams survive? Would they stay in sync? I didn't want to guess, so I read the source.
Two findings changed my whole approach:
I also checked whether AGENTS.md could serve as a persistent "please draw diagrams" instruction. It can't — OpenWiki reads that file only to manage its own reference stub, and treats other docs as source material to document, not as authoring instructions.
Conclusion: a durable diagram capability can’t be a prompt I remember to type. It has to live in the system prompt, and it has to explicitly tell update runs to keep diagrams in sync and to follow label-safety rules.
The quick path was to patch my own copy’s system prompt and move on. But this is open source, and the same gap will bite anyone who runs OpenWiki. So I built it as a contributable feature instead.
The design, optimized to actually get merged:
Everything green: the full test suite (plus the new tests), typecheck, lint, and formatting.
This is the question a maintainer will ask, and it has a real answer. A one-off prompt only affects one run. A setting buys three things a prompt can’t:
That framing — durability + correctness + discoverability, not mere convenience — is what turns “nice idea” into “worth a config key.”
Shipping to someone else’s project is as much etiquette as code. The project’s CONTRIBUTING is blunt: one PR = one change, and link an issue for anything non-trivial. So:
A quick note on sequencing, because I went back and forth on it: the textbook move is “open the issue, wait for a maintainer 👍, then PR.” But that advice was written for before you have code. Once you’re holding a complete, CI-clean, tightly-scoped implementation — and you’re wary of someone else grabbing the issue — opening the PR that references the issue is a legitimate, often preferred move. Design discussion and code review happen in one place, and an issue with a linked PR is effectively claimed. CONTRIBUTING only required me to link an issue, never to wait for approval. So I opened it.
The result of chasing a missing feature through a demo, a bug, a source dive, and a design:
Whether or not it merges in exactly this shape, that’s the arc I wanted to share: a prompt-driven tool is extensible by anyone who reads its prompts, the failure modes are real but small (a semicolon!), and the most satisfying way to close a gap in an open-source tool is to close it for everyone.
[1] “Mermaid — diagramming and charting tool,” official documentation. Available: https://mermaid.js.org
[2] LangChain, “OpenWiki,” GitHub repository. Available: https://github.com/langchain-ai/openwiki
[3] Y. Chavan, “feat: add optional Mermaid diagram generation (OPENWIKI_DIAGRAMS),” langchain-ai/openwiki, Pull Request #199. Available: https://github.com/langchain-ai/openwiki/pull/199
*← Back to Part 2 · Start at *Part 1
Teaching OpenWiki to Draw: From “No Diagrams” to an Upstream PR was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.