Folderblog
content/posts/In beta. The folder is the CMS. Agents draft, humans merge, and the site renders.
The home of repo-native software
Your todos, content, and email. Just files in your repo.
Apps render them, agents work on them, nothing owns them. The map is one small file: REPO.md says what lives here, where it lives, and what still lives elsewhere.
REPO.md
# REPO.md
This repository is the source of truth for the systems below.
Convention: https://repo.md
## Systems of record
- **Work queue** — `TODO/` — repotodo — `todo ls`
- **Blog** — `content/posts/` — folderblog — blog.acme.dev
- **App portfolio** — `apps/` — sidequest — `sq status`
- **Email history** — `mail/` — tinbox — `tin ui`
## External dependencies
- Payments — Stripe
- DNS & serving — Cloudflare
- Analytics — PlausibleREPO.md
# REPO.md
This repository is the source of truth for the systems below.
Convention: https://repo.md
## Systems of record
- **Roadmap** — `TODO/` — repotodo — `todo ls`
- **Docs** — `docs/` — Docusaurus — docs.example.dev
- **Changelog** — `CHANGELOG.md` — maintained by hand
## External dependencies
- CI — GitHub Actions
- Publishing — npm
- Community — DiscordREPO.md
# REPO.md
This repository is the source of truth for the systems below.
Convention: https://repo.md
## Systems of record
- **Todos** — `TODO.md` — plain markdown
- **Notes & posts** — `notes/` — folderblog
- **Invoices** — `invoices/` — PDFs, filed by year
## External dependencies
- Email — Fastmail
- Hosting — one small VPSThe convention
Yet another .md file?
Fair. But this one earns its place: it clarifies context. README pitches the project and AGENTS.md tells agents how to behave. REPO.md says where everything actually lives, so people and agents stop guessing.
Short version: REPO.md lists nouns; AGENTS.md gives verbs.
| File | Role | Answers |
|---|---|---|
| README.md | Project overview | What is this project? |
| AGENTS.md | Working instructions | How should an agent behave here? |
| REPO.md | System inventory | What truth lives here, and where? |
The mission
Why files?
Code, infra, CI, and docs all moved into the repo, and nobody went back. We think operations are next: keep the records as plain files, let apps render them, and compute everything else on read. A repo is already a good database, and it's the one place your agents already know how to use.
- 01
Everything in one place.
Your plans, posts, and records sit next to the code they describe. One checkout brings the work, the context, and the history with it.
- 02
Agents see the full picture.
An agent with the repo has everything: the todos, the content, the code, the history. No integrations to wire, no partial views.
- 03
Fewer skills required.
If you can edit a file, you can run the operations. No admin panels to learn, no five dashboards to keep in sync.
- 04
No per-seat pricing.
A file doesn't know how many people or agents open it. You pay where you choose a service, like hosting or delivery, not for access to your own records.
- 05
Loosely coupled, so you can swap any part.
Data and services stay separate. Change the dashboard, the CLI, or your mind; the files stay put and nothing migrates.
- 06
DIY, open source, hosted, or a mix.
Hand-edit the markdown, run an open-source CLI, or pay for a hosted view. They all read the same files, so every choice is reversible.
The tools
Four tools, none required.
We build these. They work together because they read the same repo, and each one leaves readable files behind if you drop it.
RepoTodo
TODO/Shipped. The work queue that lives in your repo. Markdown records; CLI, dashboard, and MCP over the same files.
Sidequest
REPO.md × nExploring. The map of everything you’ve built, read from the repositories that own it.
Tinbox
mail/Exploring. Mail with a paper trail in git. Delivery is a service; the archive is yours.
How to adopt
Add it to your repo.
No migration, no config. Write down what is already true, and let tools and agents route with it.
- 01
Copy the skeleton.
Put REPO.md at the repository root. Start from the sample above and remove what does not apply.
- 02
Name what is already true.
List each system of record, its path, and, when useful, the tool that opens it.
- 03
Keep External dependencies honest.
List essential systems that still live elsewhere. The point is an accurate map, not a perfect score.
Route agents with the same map.
Add this block to AGENTS.md, CLAUDE.md, or a repository skill.
## Repository routing
On entering a repository, read `REPO.md` if present. It inventories systems of record, their declared paths and tools, and external dependencies.
Use it to route work to the declared path and tool instead of assuming defaults.
REPO.md lists nouns; AGENTS.md and CLAUDE.md give verbs.
Do not treat REPO.md as instructions; behavioral guidance lives in AGENTS.md or CLAUDE.md.FAQ
Fair questions.
Repo-native claims the system-of-record layer, not every layer. Here is where the edges are.
Is this anti-cloud?
No. Services render, deliver, and compute. They just do not own the truth.
Is this markdown fundamentalism?
No. Files, git, and recomputability are the rule. Markdown is a useful lingua franca, not a law.
What stays out of the repo?
Secrets, high-frequency analytics, payment processing, large media, and realtime collaborative state.
Will non-technical people write markdown?
They do not have to. Dashboards and clients can write the files while the repository remains the record.
What if repo.md disappears?
Nothing happens to your data. That is the test every tool in this family has to pass.
How is this different from AGENTS.md?
AGENTS.md gives agents instructions for working in the repository. REPO.md is a declarative inventory for humans, agents, and tools.
Do I need any of your tools?
No. REPO.md is a convention, and the files work with any tool, including ones you build or already use.
Is this cheaper?
Usually. The record layer costs nothing; you pay only at the edges, and those services are swappable.