Before an AI edits the wiki, run the round-trip test

The onboarding SOP your company runs new hires through is probably three years old. There is a YAML block at the top naming an owner who left in 2024 and a last-reviewed date nobody has touched since. A table maps systems to access roles. Two screenshots. A handful of fenced shell snippets for provisioning a laptop. Six internal links, two of them already dead.

You point an agent at it: clean this up, renumber the steps, add the missing one about revoking access when someone leaves, fix the dead links.

It does. The prose reads better than it has in years. Then you stop because you cannot actually tell what else moved. Is the frontmatter intact, or did the owner field get rewritten? Are the code fences still fenced, or did one collapse into a paragraph? Did the screenshots survive? Who just edited a document the entire company relies on, and if a step is now subtly wrong, can you put it back?

That pause is the whole thing. The question was never whether the agent could write. It is whether you can trust what it left behind.

What OpenKnowledge is actually proposing

OpenKnowledge is a new open-source project from Inkeep that GitHub describes as a "Beautiful, AI-native markdown editor and LLM Wiki." It went public in June, had roughly 1,400 GitHub stars at research time, and is shipping quickly: releases had reached v0.20.0-beta.9 by late June. The Show HN discussion is useful because people immediately asked the questions operators should ask: migration from Obsidian or Notion, local model support, macOS limitations, team sharing, and whether agent edits preserve frontmatter and nested code fences.

The docs describe three layers: a WYSIWYG editor for humans, MCP and skills for agents, and Markdown files underneath. Git holds the recovery story. The README describes a macOS app plus a local web app and CLI, with setup commands like npm install -g @inkeep/open-knowledge, ok init, and ok start --open. From there, the knowledge base can be handed to Claude, Codex, Cursor, or another CLI-backed agent.

That is a genuinely interesting shape, and it is also early, fast-moving software. That combination is exactly why it is worth looking at now. It takes a question that has been abstract and makes it concrete: what does it actually take to let an agent maintain the documents your team depends on?

You can say the promise in one breath: human editor, agent tools, Markdown files, Git sync. The real version is a question you answer page by page. Can one messy page go in, get edited by an agent, and come back out with nothing lost that mattered, including the team's trust?

That is the test.

The wiki round-trip test

Here is the line I would write on the whiteboard before anyone points an AI at the company wiki:

The wiki is not ready when the agent can write it. It is ready when the team can round-trip one messy page without losing trust.

A round-trip is the full loop. One real page goes from its current state, through an agent edit, into human review, into version history, and back to a state you would defend in a meeting. This is not a test of writing quality. It is a test of whether the page survives the journey intact, and whether you can see and reverse everything that happened to it on the way.

Pick your messiest important page. Not a clean one. The gnarly SOP with the frontmatter, tables, nested code fences, screenshots, and attachments, because that is the page that exposes everything. A page that only has paragraphs will pass any test and teach you nothing.

Fill in one card for that one page. Nine fields, and you can do it in an afternoon.

1. The page. Name the specific document, and make it your worst good one: the access SOP, onboarding checklist, customer escalation guide, incident runbook, or internal FAQ. Choose a page that hurts if it breaks.

2. Source format. Inventory what is actually in it before the agent touches it: YAML frontmatter, internal wiki links, normal links, embeds, tables, fenced code blocks, images, attachments, and owner metadata. This is your before-picture. You cannot tell what broke if you never wrote down what was there.

3. Agent action. Give one concrete instruction: restructure, add a missing step, repair dead links, or summarize exceptions. Do not ask it to "improve this." OpenKnowledge's MCP reference splits read access from write actions: exec is a read-only shell-style tool for commands like cat, ls, grep, and find, while write actions include write, edit, delete, and move. A summarize-only job and a move-and-rename job are different risks.

4. Human review surface. Review twice, two ways. First in the WYSIWYG view the way a reader sees it, then in the raw Markdown diff. The pretty view hides exactly the failures you care about, like a swallowed frontmatter key or a collapsed code fence. OpenKnowledge's agent activity panel groups every edit by file with additions, deletions, timestamps, and diffs. That diff is the evidence trail, which is the same reason agent work should leave receipts you can read.

5. Repository surface. Find the commit. Check the author identity, branch, and whether the edit stayed local or pushed. If GitHub sync is on, OpenKnowledge can actively pull commits, commit local edits, and push back to the remote. The docs warn to enable sync only on repositories where you are comfortable with OpenKnowledge writing commits to remote history, and to commit or discard local work first because a pull can overwrite uncommitted changes. Decide the sync posture before the edit, not after.

6. Rollback route. Know your undo before you need it. While an agent session is open, OpenKnowledge can undo the latest edit in a file or every edit the agent made in that file. Once the session closes, recovery moves to timeline rollback through Git history, which is why the quickstart requires Git for timeline and recovery features. A round-trip you cannot reverse is not a round-trip. It is a one-way edit you have not noticed yet.

7. Access boundary. Decide which folders the agent may touch and pin that down. content.dir in the project config can scope the content directory. The principle is the same one behind keeping capabilities on a shelf the agent reaches for deliberately: the agent should not carry the whole library by default. If this is a familiar problem, the capability shelf pattern is the adjacent read.

8. Egress boundary. Know what leaves the building. The MCP reference says search blends title boost, body BM25, and recency, with semantic search as an opt-in signal that involves content egress. For a public FAQ, that may be fine. For an SOP with internal system names and access roles, it is a decision someone should make on purpose, not discover later.

9. Pass/fail rule. Write the rule down in advance so you are not grading on a curve at 5 p.m. The page passes only if the frontmatter parses, every code fence is still fenced, every link resolves, every attachment renders, the owner remains clear, and exactly one identity owns the commit. One broken fence is a fail. Ownership ambiguity is a fail. Testing the artifact this way, not just the final prose, is the same discipline as evaluating the workflow, not the output.

Run that card once and you will know more about whether your wiki is ready than any feature list can tell you. Run it on your three worst pages and you will know whether the team is ready, which is the part that actually decides adoption.

Why review the loop instead of the output

The failure modes do not live in the prose. They live in the plumbing.

An agent that rewrites your access SOP into beautiful numbered steps has done the easy part. The hard part is the YAML block it might flatten, the nested code fence it might unwrap, the wiki link it might rename, the screenshot path it might drop, and the remote commit it might push before the team has agreed who owns AI-made documentation edits.

None of that shows up when you skim the rendered page. It shows up in the diff, in the commit, in the rollback test, and three weeks later when someone follows a step that no longer links anywhere.

This is also why the answer is not "just keep the wiki in plain Markdown" or "just use Git." Those are strong ingredients, but they do not automatically make the workflow safe. Markdown can still be mangled. Git can still record a bad change. A diff can still be ignored. The round-trip test forces the whole system to prove itself with one document before the whole library becomes editable by an agent.

That is the useful lesson from OpenKnowledge even if you never adopt the tool. AI-maintained documentation needs a loop, not just an editor. The loop has a source, a tool, a human surface, a repository surface, a rollback route, and a data boundary. If one of those is missing, the wiki may look smarter while becoming harder to trust.

Run it this afternoon

You do not need a big rollout plan for the first test. You need one messy page, one copy of the wiki, one specific agent instruction, and one hour. Ask the agent to repair the page, then walk the loop: rendered page, raw source, diff, commit, rollback, links, attachments, and egress settings.

If the page comes back intact and you can prove every change, you have learned that one lane of the wiki may be ready to become an agent workspace. If it does not, you have learned exactly which boundary to set first, on one page instead of the whole library.

Run the wiki round-trip test before the agent edits the library

Bring one messy SOP, spec, or internal FAQ. We will map the source format, allowed agent edits, review surface, rollback route, sync behavior, and egress boundary before the wiki becomes an agent workspace. Start with the AI workflow controls framework, or map one AI-maintained doc workflow with us. It is the same controlled-rollout work we do under process automation.