I’ve been using Obsidian for a couple years now, and it has slowly changed how I think about documentation.

Not in a big “second brain” way. I have a folder full of markdown files, links between notes, some loose conventions, and enough structure that I can usually find the thing I am looking for again later.

When you know a notes in a portable format you can easily share them with anyone, and use it with your AI workflows.

Eventually I started wanting that same shape inside my projects at home and work. This helped improve reliability and gives the AI tools the context you often omit becasue you’ve internalized it.

The Docs Folder

For a while now I have been adding a docs/ folder with a few predictable buckets:

• adrs/ for decisions and the reasons behind them
• features/ for how a specific capability is supposed to work
• guides/ for developer notes and project-specific gotchas
• external/ for API specs and externally provided documentation
• workflows/ for the repeated tasks a human or agent needs to do

Each document was structured similar to an obsidian document. It links to related documents. The folder is meant to be useful to teh developers, but it is also meant to be useful to an AI agent working in the repo.

An agent can grep the codebase, but it cannot magically know the decision history. It can read a README, but it will miss the edge cases that only exist in a forgotten ADR. It can infer a lot from tests, but it is still guessing at intent.

I have often treated AI agents as someone I onboarded to the project 5 min ago, and needs all the help it can get to get up to speed on the project.

So I started treating project docs as part of the repo. Not a polished docs site that maybe gets updated maybe never, but a living set of notes that explain what the project is, how it works, and why it is shaped that way.

OKFs

Google recently introduced the Open Knowledge Format, or OKF, this starts to formalize what many of us have been doing already.

The OKF v0.1 spec is intentionally small. It is markdown files, YAML frontmatter, normal links between files, optional index.md files for navigation, and a few rules about what makes a bundle conformant. A concept is one markdown file. The type field is required. Most other things are guidance.

This adds a lot of flexibility while also standardizing things that will ultimatly make it’s way into the AI training data.

The Hard Part

The downside of “just files” is that eventually there are a lot of files.

For small projects, you do not need anything fancy. If your docs/ folder has ten or twenty documents, rg, your editor search, and a decent index.md are probably enough. Honestly, adding more tooling too early just gives you another thing to maintain.

The pain starts when the project and thus the documentation start to grow.

You add ADRs. Then feature specs. Then guides. Then workflow notes. Then generated reference docs. Then you add new ones that replace old ones as technologies or processes change. Suddenly you have a hundred or a few hundred markdown files, and the nice simple folder has become a knowledge base.

As a human, I might know the doc exists, but not remember the title. Or I might remember that a decision touched “search indexing”, but not whether it was in an ADR, a feature spec, or a guide. A normal text search helps, but it does not understand the structure of the bundle. Additionaly a tool like Obsidian on top can help with a search, but not everyone on your team will have these tools.

For an AI agent, the problem is worse. An agent cannot just read hundreds of documents into context and hope for the best. It can write it’s own script, or dispatch a sub-agent to find docs, but this is not ideal. It needs to assemble context deliberately: find the relevant docs, read the right sections, follow the useful links, and avoid dumping the whole knowledge base.

OKF gives us a good storage format. It does not, by itself, solve the query problem.

okq

So i’ve started building okq for this use case.

okq is a local command-line tool for searching and navigating OKF-style documentation bundles. It is meant to sit on top of a docs/ folder and answer questions like:

okq search "search index lifecycle"
okq find --type adr --tag security
okq get adrs/0002-library-stack --section Decision
okq backlinks features/search
okq path features/search features/get
okq stats

The important bit is that it returns locations first, not giant content dumps.

Search results point to path:line, with a heading and a short snippet. If you want the full section, you ask for it with get. If you find one relevant document, you can ask for its neighbors or backlinks and move through the graph.

That flow matters for agents:

okq search "auth token refresh"
okq neighbors features/auth
okq get adrs/0007-auth-boundaries --section Decision # it may just read the file directly

It is also deliberately boring. It is all local. It does not require embeddings, a vector database, an API key, or a network call. There is a --json mode for every command so agents and scripts can use the same interface a person uses in the terminal.

Not for Every Project

I want to be clear about the scale where this is useful.

If your project has a README and a handful of docs, you do not need okq. Your editor search is enough. rg is enough. A simple table of contents is enough.

okq starts to make sense when the docs become large enough that “just read it” stops being a reasonable answer. Roughly, I think that means hundreds of documentation files, or at least a docs folder that is trending in that direction.

And because OKF is just markdown and frontmatter, you can still keep using whatever editor or workflow you like. okq is just a consumer of the bundle.

Final Thoughts

The thing I like most about OKF is that it is not trying to be magical, it does what we already do, and standardizes the repo docs format.

It takes a pattern that a lot of people were already discovering independently and gives it a small shared contract. If you have used Obsidian, Notion exports, Hugo content folders, GitHub-rendered docs, or the newer LLM-wiki style repos, the shape is familiar.

Once there is a common shape, AI tooling can train and build against it.

But the most important part for me, is maybe… just maybe my client projects will actually start documenting what the project is supposed to do.