A repository document can be clear, accurate, and still be almost unavailable to an AI agent at the moment it needs it.
I don't mean that documentation written for humans suddenly stopped working. A good README is still good. Clear prose is still clear prose. If the exact paragraph reaches the context window, a model may understand it perfectly well.
The harder part is everything that happens before and after that paragraph.
Take it out of software for a moment.
You leave a folder of instructions for whoever is looking after your flat while you're away. Every page in it is clear. The trouble starts at eleven at night when the boiler makes a noise, because now someone has to find the boiler page in a folder they have never read, work out whether it still describes the boiler you replaced in March, notice that the sticky note on the front contradicts page four, and decide whether calling someone out is their call or yours.
None of that is a writing problem. The pages are fine.
The same shape shows up in a repository.
An acting agent has to find the right knowledge under a limited context budget, decide whether it is current and authoritative enough to use, and then do something with it: edit a file, run a command, choose an implementation path, respect a boundary, or stop because the action is not authorized.
That changes the documentation contract.
Readable is not the same as retrievable
Humans compensate for weak information architecture surprisingly well. We browse. We skim giant files. We remember that the deployment note was somewhere near the bottom of a README. We notice tone and context. If two documents disagree, we can ask someone which one is current.
An agent can search and browse too, but retrieval is now part of the execution path. The question becomes more specific:
Can the agent locate the right knowledge when it needs it, without loading everything and without selecting an obsolete or merely adjacent document?
This is the part I think is easy to underestimate because language models are so good at reading unstructured text. Parsing ability can hide retrieval weakness.
If the agent receives the right paragraph, prose may be enough. Getting the right paragraph into context is a different problem.
LangChain's OpenWiki release article gives a concrete version of that distinction. The repo wiki can be larger than you would want to stuff into an AGENTS.md or CLAUDE.md, so the instruction surface can point the coding agent toward the larger knowledge base instead. The agent retrieves what it needs rather than carrying the whole wiki at startup.
The transferable idea is the separation between routing context and knowledge context.
A small, frequently loaded instruction file can tell the agent where important knowledge lives and when to consult it. The larger corpus can remain decomposed and navigable. The startup prompt does not have to become a compressed copy of the repository.
That is a better question for documentation than "can the model read Markdown?"
Most of them can. That was never the interesting part.
Retrieval needs addresses
Long documents are not inherently bad. But if important knowledge is trapped inside one enormous catch-all file, retrieval has fewer stable targets. The folder version of that is one long unnumbered note instead of a page you can send someone to.
The Open Knowledge Format specification formalizes one approach to this. It describes a knowledge bundle made from Markdown concept documents with structured front matter, path-based identities, links, and indexes. The current upstream specification used for this article is v0.2, which also makes provenance, trust, freshness, and lifecycle concerns explicit.
That does not mean every repository needs OKF, or YAML on every page. Metadata nobody uses is just another thing to keep stale.
What matters is addressability.
When knowledge is expected to be retrieved programmatically, a document stops being only a blob of text. Stable paths, descriptive headings, useful metadata, links, and indexes give retrieval something to target. They also make it easier to ask for one relevant unit instead of loading a whole knowledge dump and hoping the important sentence survives the compression.
This is where structure stops being decoration.
A heading helps a person scan. It can also give an agent a stable semantic target. A link helps a person browse. It can also expose a relationship between two units of knowledge. A small type field may tell a retrieval system whether a page is a current operating instruction, a historical design note, or generated reference material.
Prose carries nuance. Structure carries repeatable routing signals.
I would not trade one for the other.
I ran into the same semantic boundary from the output side in The Output Became a Work Object: once later behavior depends on identity, provenance, permissions, or machine-readable state, leaving the contract implicit in prose gets expensive.
An instruction file should route, not carry everything
There is a tempting response to agent context problems: put more into the file that always gets loaded.
It works until it doesn't.
A short instruction surface is useful precisely because it can be loaded frequently. If it gradually absorbs every architectural decision, workflow rule, troubleshooting note, environment caveat, and historical exception, it becomes a second repository in miniature. Then every new piece of context makes the supposedly concise control surface harder to maintain.
OpenWiki's design is interesting here because its repository keeps the larger generated knowledge base as linked Markdown and provides an update path intended to keep that material aligned with repository change. The instruction file can act as a router into the knowledge rather than as the knowledge corpus itself.
That is a pattern, not a product recommendation.
The repository also says OpenWiki emits OKF v0.1. The upstream OKF specification I am using as a separate structural reference is v0.2. I am keeping those two facts separate on purpose; the newer provenance, trust, lifecycle, and attestation semantics in v0.2 should not be casually attributed to OpenWiki's stated v0.1 output.
This is exactly the sort of distinction agent-facing documentation has to preserve. Similar-looking knowledge is not automatically the same authority.
Freshness is part of correctness
A stale page can still be beautifully written.
That is what makes it dangerous.
If an agent is using documentation inside an execution loop, an old directory name, superseded command, abandoned architecture, or obsolete owner can become an action rather than a minor reading inconvenience. The agent may follow the document perfectly and still do the wrong thing.
So knowledge intended for operational reuse needs a visible relationship to change.
That relationship can be simple:
- version the documentation beside the code it explains;
- update it through the same change workflow;
- record a meaningful modification or generation time;
- make supersession explicit;
- attach the document to a canonical resource;
- expose a lifecycle state when one actually matters;
- distinguish current operating instructions from historical explanation.
None of those mechanisms guarantees freshness. They give the consumer evidence to reason about it.
That distinction matters. Metadata does not make a document true. A timestamp does not make it correct. A retrieval score does not make it authoritative.
The useful question is whether the knowledge system gives the agent enough information to avoid treating old state as present state.
Authority has to survive retrieval
Relevance and authority are different problems.
A search system may surface the document most similar to the query. That document may still be the wrong one to govern an action. Page four and the sticky note are both about the boiler. Only one of them is current, and being about the boiler is not what settles which.
A design exploration can rank highly for an architecture question after a later canonical has replaced it. A generated wiki page can summarize repository behavior accurately without becoming the authority for changing that behavior. A historical postmortem may contain the exact keywords an agent is looking for while describing a system that no longer exists.
I made a similar distinction between description and ownership in The Boundary Was the Architecture: a surface can describe another system accurately without becoming the authority that owns it.
This is where I think agent documentation gets more demanding than ordinary search quality.
The agent needs to answer two questions:
- Is this relevant?
- Am I allowed to treat this as the governing truth for the action I am about to take?
Useful signals can include canonical links, source references, generated-versus-authored status, provenance, supersession relationships, current-versus-historical labels, and verification state where the domain warrants it.
The current OKF v0.2 specification makes several of those concerns explicit. Again, that is a separate structural example rather than a claim about what OpenWiki v0.1 already implements.
The broader point is mine: retrieval should not erase authority boundaries.
If anything, it makes them more important.
The last mile is actionability
There is another gap between documentation an agent can parse and documentation an agent can safely act from.
"Deploy the site" is readable.
It is not necessarily enough.
Which project? Which environment? Which branch? What has to pass first? Is deployment authorized in this session? What happens if a prerequisite is missing? Which parts are suggestions and which are stop conditions?
Human teams often carry that layer socially. People know which instructions are ceremonial, which ones are current, and which actions require someone else's approval. It is the same judgment the flat-sitter makes when they text you at midnight instead of calling someone out.
Agents do not inherit that context automatically.
For operational documentation, I would make these distinctions explicit when they materially affect execution:
- description versus instruction;
- capability versus permission;
- default path versus exception;
- safe read versus mutating action;
- prerequisite versus suggestion;
- current authority versus reference context;
- stop condition versus optional guidance.
That capability-permission split is also the execution problem behind The Eval Sandbox Is an Execution Boundary: once an environment can turn model behavior into real effects, declared scope and actual authority have to be designed separately.
This is not an OpenWiki rule or an OKF doctrine. It is editorial synthesis from the changed-consumer problem.
Once the reader can act, ambiguity in documentation becomes ambiguity in execution.
A practical audit for repository knowledge
You do not need a new documentation platform to test this. A repository can start with five questions.
Can the agent locate the knowledge?
Is there a deterministic entry point, index, instruction reference, known folder, or retrieval path? Can the agent discover the relevant document without loading the whole repository?
Is the knowledge addressable?
Are important concepts trapped inside giant files, or do they have stable paths, headings, documents, or identifiers that retrieval can target? Are related concepts linked rather than merely sitting near each other?
Can the agent distinguish authority?
Does the document make clear whether it is canonical, generated, historical, advisory, or superseded? Can the agent trace it back to the resource that actually owns the decision?
Can the agent tell whether it is fresh enough?
Is there a visible update path, version history, lifecycle marker, generation time, or relationship to repository change? What happens when the implementation moves but the documentation does not?
Can the agent act without guessing the boundary?
Do operational documents separate instruction from explanation and capability from permission? Are prerequisites, exclusions, stop conditions, and escalation paths visible where they matter?
Those questions are deliberately tool-independent. A repository could answer them with maintained Markdown, a generated wiki, a docs site, a structured knowledge format, or something else entirely.
The implementation choice comes later.
The contract is additive
I do not think the arrival of coding agents creates a separate universe of "agent documentation" that should replace the human one.
That sounds like a fast route to two knowledge systems disagreeing with each other.
The stronger target is a shared layer that humans can read and agents can retrieve: ordinary prose where prose is best, structure where repeated ambiguity needs to disappear, links and indexes where traversal matters, and enough provenance and lifecycle context that the consumer can tell what kind of truth it has found.
Human readability is still part of the contract. It is just not the whole contract once the document sits inside an execution loop.
A page can be beautifully written and still fail because the agent cannot find it, cannot tell whether it is current, or cannot distinguish explanation from authority. It can fail in the opposite direction too: immaculate metadata does not rescue bad explanations or false certainty.
The reader did not stop being human.
The repository gained another reader—one that may act on what it finds.
// End of transmission. Retrieve. Verify. Then act. — ZYANE