Everything it does,
and everything it will not.
Reading
- front matter removed
- badge images removed
- relative links rewritten to repository-root
- paths kept, so a model can cite them
The folder structure is the navigation
No config file, no front matter, no sidebar to maintain. The docs root is found, titles come from front matter then the first heading then the filename, order is README first and numeric prefixes next, and CHANGELOG and LICENSE collapse into a group at the bottom rather than cluttering the top.
The lit path
The rail beside the tree lights the ancestry of whatever you are reading, so you always know where in the corpus you are standing.
Built to read end to end
A 78-character measure at every width, real typography, dark by default. For a spec somebody actually reads, not a page somebody scans.
Diagrams and code
Mermaid renders in the product's own palette, and code blocks use six syntax colours that follow the theme. Neither is loaded for a document that has none.
Your reading preferences
Theme, reading width, sidebar density and motion are yours and follow you, applied before the first paint rather than after it.
Copy for LLM
Take a document or a whole folder to your model as clean markdown — front matter and badges stripped, links rewritten — with the token count before you paste.
Sources
Two providers, read-only, never cloned
A GitHub App with read access to the repositories you pick, revocable from GitHub at any time. Or a GitLab access token — gitlab.com, self-managed or internal instances, public and private projects. One call returns the whole tree plus a blob SHA per file; no git binary, no working copy, nothing on disk.
No token in the database
GitHub installation tokens are minted on demand from the App key and held in memory only. A GitLab token is encrypted at rest under its own key, and one carrying a write scope or no expiry is refused by name at connect.
Many repositories, one project
An engineer across six services reads and searches all of them from one place. A project groups repositories and carries the access list.
Private images work
Images inside a private repository are served through an authenticated proxy rather than hotlinked, so they load for the people allowed to see them and nobody else.
The branch is read, not guessed
The real branch list comes from the repository. A fixed main-or-master picker once pointed a connection at a branch that did not exist, and the sync then found nothing.
Search
Every document in every connected repository
Full-text search across the whole organization in one statement, ranked, with the path and the review state beside each hit. Core Postgres, no extensions — a search that needs one is a search that stops working on somebody's managed database.
One keystroke
The command palette opens on ⌘K for everything and ⌘P for files, with projects, settings and account actions in the same list.
Find in document
⌘F highlights matches without touching the document's markup, so nothing on the page shifts while you search it.
Workflow
Two axes, and drift measured against the content
Review state and implementation state move independently, and each remembers the exact version it was set against. Edit the document and it reads validated · drifted rather than keeping a badge that is no longer true. A document nobody has triaged has no row at all — an untriaged corpus costs nothing and shows no pills.
The board
Every document with a status, in columns you can drag between, across one project or the whole organization, filtered by a URL you can send to somebody.
Notes on a heading
Feedback anchored to the section it is about. A note whose heading disappears fails visibly rather than relocating onto text that says something else.
Read receipts
Counted after ten seconds of visible dwell, never on a click, and only against the current version — so three of five reviewers have read this means what it says.
Marking a document not applicable
Take a README off the board without saying anything about the document itself. Not draft, not rejected — simply not a work item.
The revision log
Past versions are stored rather than re-fetched, so you can see what changed between the version somebody validated and the text now.
Ask your docs
Summaries that know when they are stale
A summary is keyed to the document's content, not to a date, so it is current or it says it is not. A cached answer spends no credit, which is what makes the allowance workable. Document text leaves the box only for an organization that switched it on — the setting defaults to off and turning it on is audited.
Questions the summary offered
You ask what the current summary suggests, not free text. Without that gate an ordinary member holds an unvalidated, organization-funded channel to a third-party model.
Chat with a document
Streamed, grounded in one document, and separate from the suggested-question path for exactly the reason above.
Change summaries
A paragraph on what moved, for the documents somebody is watching, rather than a diff you have to read.
Batch summarisation
Summarise a corpus on purpose, priced before it runs. Never automatic, because a background pass that spends an allowance is a bill nobody agreed to.
Agents
An MCP server over your own documentation — 16 tools
One stateless endpoint. Your coding agent finds, reads and cites what your team already wrote, with nothing pasted into a prompt. Tools are withheld by scope rather than by name, so a read-only key is never shown the write half.
Artifacts
An agent files a spec or a plan as a versioned document beside the documentation. It can never reach a repository file, and there is no delete.
Review floors
A key can carry a minimum review state. Below it, documents are 404 on every door — on the reader routes too, because a floor with one front door is not a floor.
Typed replies
An agent answers a note as agrees, disagrees, needs clarification or addressed. Four notes where it disagreed is a queue a lead opens; a transcript is not.
Implementation claims
An agent says it started or finished, with evidence saved as a note. It records a claim, never a completion.
Rate limits, not quotas
Reads are free on every plan and bounded by a per-key token bucket rather than a monthly allowance.
Organizations and access
Membership is the organization; access is the project
Joining hands out no documents. Nothing is implicit: a Member reads a project through a team grant or a direct one, and somebody in no team with no grant reads nothing. Access is resolved server-side on every request, in one query, and a project you have lost access to answers exactly as one that never existed.
Roles that mean one thing each
Owner, Admin, Member and Guest at the organization; Admin, Member and Viewer on a project. A Guest sees only what was granted — the organization is invisible furniture to them.
Teams
Grant a project to a team rather than to seven people, and remove somebody once.
Invitations
An invite carries an intent — a role, some project grants, some teams — and grants nothing until it is accepted. The link works once, expires, and can be revoked.
A handle, claimed once
Claimed, never changed, because four tables denormalise it beside a name and a rename has no honest answer.
Leaving safely
You may go unless going strands somebody. The last Owner of an organization other people are in has to hand it over first.
Security
Markdown is sanitized server-side, on an allowlist
Markdown permits raw HTML, so a script tag in somebody's README would otherwise run in our origin with your session. This is the highest-severity risk in a product like this and it is closed before anything is stored, not at render time.
Audit log
Every security and product change, with who and when, written inside the same transaction as the change — so if the change rolls back the record goes with it.
Sessions and devices
A real list of where you are signed in, and a notification when a new device appears. A coarse platform label and a truncated address — no city, no country, no guess at whether it was unusual.
IP allowlist
Refuse every request from an address you did not name, reaching API keys as well as browsers.
Keys that outlive people
An API key belongs to the organization and names one project, so a CI job does not break the day the person who set it up changes team. Only its hash is stored, and revoking one bites on the next request.
Two ways in, neither removable alone
GitHub, a password, or both. Removing one is refused when the other is absent, so an account can never be left with no way in.
Docs health
Three signals, none of them an opinion
A relative link that resolves to no document. A document whose content has not changed in longer than your threshold. A document that names a source file which changed after the document did — the one signal in the product connecting code to documentation. Nothing here calls a model, so none of it costs anything.
Findings are derived, not filed
A finding that stopped being true is gone rather than resolved. What survives the rebuild is a person's decision that one was wrong.
Silence about what it cannot know
A freshly connected repository reports no staleness at any threshold, and the screen says so rather than implying everything is fresh.
Notifications
An inbox, not a second copy of the audit trail
The audit log answers what happened in this organization; the inbox answers what you still need to see. They are different questions and neither table can answer the other's — a successful sync, a note reply, an exhausted allowance and every billing event write no audit row at all.
You are never notified about yourself
The actor is never a recipient, a duplicate that is still unread is suppressed, and anybody who cannot read the subject is dropped — a title is content.
Told once, your way
Per category: as it happens, in a digest on your cadence, or not by email at all. Off means do not tell me twice, so a digest does not then tell you.
Security always reaches you
There is no switch that suppresses your password was changed. A setting that could would only ever help whoever changed it.
What we deliberately don't build
Not a roadmap, and not things we ran out of time for. Each of these was considered and refused, and the reason is what keeps the product from becoming the thing it was built to replace.
- An editor for your repository
- Repository documents are read-only here: you edit them in your IDE and commit. Drafts and Handbook pages have an editor; your repository files never do.
- A public comment board
- The public site is for reading. Feedback stays inside Docs Flowy as notes, where agents reply and people close them.
- A wiki with its own storage
- Git is the source of truth for every repository document. Docs Flowy stores only what sits beside them: drafts, agent artifacts and Handbook pages.
- Custom MDX components
- Plain CommonMark and GFM. Portability is the promise — your docs stay readable without us.
- Our own markdown renderer
- A solved problem. We use a good one rather than maintaining a worse one.
- A config file you must write
- There is an override. It is never required, and needing one would be our bug.
If one of these is what you need, we say which tool to use instead.