The thesis
Notes tools keep your knowledge in their database and offer an export. That was fine while people were the only ones editing. Now a coding agent works in your repository all day, and the plan, the spec and the decision it needs are somewhere else, behind an integration that copies things back and forth and is always slightly wrong.
notdocs takes the other position: the markdown in the repository is the record, and everything else is a view of it. The web app is a Notion-like editor over those files. The CLI is a terminal over those files. The MCP server gives an agent those files. There is nothing to sync, because nobody is holding a second copy.
Who it is for
Indie hackers and small teams who ship with agents and are tired of their docs living apart from their code. If your repository already has a docs/ folder, a README, a CHANGELOG and a CLAUDE.md, you already have a workspace; notdocs gives it properties, boards, comments, search and a place for the whole team to read and write it.
What we decided
The founding decisions are a document in the repository like any other. This is the short form, in the order they were taken.
- 01
The markdown in the repository is the record.
Everything else, the web app included, is a view of those files. Nobody holds a second copy, so nothing has to sync.
- 02
Hybrid hosting.
A hosted control plane that reads and commits through a GitHub App, and a local daemon and CLI that run the same workspace offline against any folder.
- 03
One contract.
Every operation is defined once with its input, output and scope. The API, the SDK, the CLI, the MCP server and the assistant are generated from it or are thin clients of it.
- 04
Merges, not locks.
A write carries the hash it was read from. Concurrent edits are three-way merged; a real conflict is shown as a diff, never resolved silently.
- 05
Typed markdown.
Page, task, decision, spec, meeting and launch have schemas. A repository declares its own types in notdocs.config.json.
- 06
Comments in the repository.
A sidecar folder keyed by document id, committed like everything else, so an agent can read the review and answer it.
- 07
Search from day one.
Full text and embeddings for every document, for people in the palette and for agents as a tool. It put the index on the critical path, and we accepted that.
- 08
Import both ways in.
Notion exports and Obsidian vaults from the first version, because the people this is for already have their notes somewhere.
- 09
Agents are first-class, and ask first.
MCP over stdio locally and streamable HTTP hosted, scoped tokens that can be revoked, and an assistant that never writes without approval.
- 10
Business documents are MDD.
Letters, proposals, invoices, contracts, memos, reports and the legal documents use the MDD blocks for letterheads, page furniture and signatures, so the same file is a page in the workspace and a PDF or Word document on the way out. MDD 3 adopted the directive grammar notdocs already speaks.
Where we are
- There is no status page yet.
- A project and an organization are deleted from their settings; deleting an account is still done on request.
- The list of things we know we owe is longer than the list of things we have shipped; the changelog is the honest record of the second list.
If you want to shape the first list, write to hello@notdocs.dev, or read the changelog to see the second.