From README.md to README.mp4: Why AI-Native Repositories Need a Conceptual Entry Point
For a long time, README.md has been the front door of an open-source repository.
It usually answers familiar questions:
- What is this?
- How do I install it?
- How do I run it?
- What are the basic examples?
- Where is the documentation?
That works well when the repository is mainly a library, a command-line tool, or a framework.
But AI-native repositories are starting to change the role of the README.
Some repositories are no longer just code.
They define a way of working.
They may include:
- prompts
- skills
- workflows
- domain knowledge
- human review points
- agent roles
- audit logs
- handoff rules
- approval gates
In that kind of repository, the hardest question is not always:
How do I install this?
It is often:
What mental model do I need before I can understand this repository?
README.md is still necessary
I do not think README.md will disappear.
Markdown is still excellent for:
- search
- copy and paste
- installation steps
- command examples
- API references
- LLM-readable context
- long-term maintenance
A repository still needs a stable textual entry point.
But a reference document is not always the best first explanation.
When a repository introduces a new way of working, readers need to understand the concept before they can understand the file tree.
AI-native repositories need a conceptual entry point
AI-related repositories often combine multiple layers.
For example:
- the work process
- reusable capabilities
- operational skills
- domain knowledge
- stable references
- human responsibility
- AI execution boundaries
If these layers are not explained clearly, everything looks like “just documents” or “just prompts”.
That is a problem.
A repository for controlled AI work is not only a document folder.
It is an information architecture.
It has to explain how humans and AI share knowledge, divide responsibility, and keep work auditable.
This is difficult to communicate with a file tree alone.
README.mp4 as the new front door
This is why I think README.mp4 may become a common pattern.
Not as a replacement for README.md.
But as a conceptual entry point.
A possible structure is:
README.md : reference, setup, links, examples
README.mp4 : short conceptual overview
docs/ : detailed explanation
examples/ : executable confirmation
In this model, README.md becomes the hub.
README.mp4 becomes the first explanation for humans.
The video does not need to be long.
In fact, it should probably be short.
A good overview video should answer:
- What problem exists?
- Why are existing approaches not enough?
- What structure does this repository provide?
- How should humans use it?
- Where should the reader go next?
This is not marketing.
It is conceptual onboarding.
The problem is not installation. It is understanding.
Traditional OSS documentation often starts from installation.
That makes sense when the user already understands the category.
For example:
npm install ...
pip install ...
dotnet add package ...
But for AI-native repositories, the category itself may be new.
Before the user runs a command, they may need to understand:
- why domain knowledge must be externalized
- why prompts alone are not enough
- why AI needs explicit work boundaries
- why knowledge access should be controlled
- why human auditability matters
- why stable references are needed across documents
If the README starts with commands too early, the reader may miss the actual purpose.
A small experiment: XRefKit
I recently changed the opening of my repository, XRefKit, around this idea.
Repository:
https://github.com/synthaicode/XRefKit
XRefKit is an information architecture for controlled AI work.
It makes domain knowledge referenceable, traceable, and maintainable for AI-assisted work.
The repository is designed so AI can load only the knowledge it needs, follow explicit work boundaries, and remain auditable by humans.
Its core model separates:
- flow
- capability
- skill
- knowledge
- stable XID-based references
The goal is to prevent AI behavior, knowledge access, and work responsibility from collapsing into one layer.
Originally, the visible center of the repository was XID-based link durability.
But the broader purpose is controlled AI work.
So I added a short overview video near the top of the README:
▶️ Watch the 2-minute overview: Why XRefKit exists and how it helps AI teams use domain knowledge
The point of this video is not to replace the README.
The point is to explain the mental model before the reader enters the details.
Markdown for reference, video for understanding
This may become an important distinction.
Markdown is good for reference.
Video is good for initial understanding.
A README can describe:
- commands
- file layout
- concepts
- examples
- references
But a short video can show the flow:
A diagram can also show structure. But a diagram cannot control the order in which a viewer encounters information. The viewer sees everything at once. A video has a timeline. It can present the problem first, then the limitation, then the solution. That is not just display. It is argument.
Prompt → Skill → Domain Knowledge → AI Team
That flow is easier to understand when it is presented as a story.
This is especially important when the repository is not only about using AI, but about controlling AI work.
AI changes documentation requirements
AI does not only change coding.
It also changes documentation.
When humans work with AI agents, documentation is no longer just for humans.
It becomes part of the operating environment.
The repository may need to provide:
- knowledge fragments for AI
- stable IDs for cross-document references
- explicit task boundaries
- review criteria
- handoff rules
- audit trails
- operational commands
In that situation, documentation has two audiences:
- Humans who need to understand the system
- AI agents that need to use the system correctly
README.md is useful for both.
But humans may need a faster conceptual entry point before they can understand why the repository is structured that way.
Conclusion
README.md is not going away.
It is still necessary.
But for AI-native repositories, it may no longer be enough as the first entry point.
The future standard may not be:
README.md or README.mp4
It may be:
README.md + README.mp4
Markdown for reference.
Video for understanding.
For repositories that define not only code, but also AI workflows, domain knowledge, skills, and governance structures, this distinction may become increasingly important.