Repository documentation

Most teams treat documentation like they treat exercise: necessary, but always for next week. By the time someone updates the architecture page, it describes a system that shipped two quarters ago. By the time anyone writes the onboarding doc, the engineer who needed it has already left.

Disco Parrot treats your repository documentation as a working artifact. Each repo has its own set of docs that lives in the platform, the agent reads them the same way it reads your code, and a scheduled review keeps the pages in step with what is actually shipping. The point is not the docs themselves. The point is that they are current the next time you, or an agent, need them.

The pages, briefly

Every page is markdown. There is no proprietary block format, no embed registry, nothing new to learn. A page has a title, a path that the tree uses to group it, an optional category, and a scope that pins it to a particular repository. That is the entire shape, and it is what keeps the docs reading like a notebook rather than a CMS.

Get the docs without writing them

You can fill the docs by hand if you want to. Most teams do not want to. The faster path is the repo onboarding Flow, which spins up a sandbox against the repo, reads it, and writes the foundation pages for you.

The Flow runs in four passes. The first reads the repo and decides what is worth writing about. The next drafts the architecture and conventions pages. After that comes the domain and API set, and last the ADRs and quality references. A checkpoint sits between the foundation pass and the domain pass, and another sits before the ADRs, so you get two natural moments to look at what the agent has written before it goes deeper. If you send the run to the background, the checkpoints auto-advance. If you are watching, they wait.

When the Flow finishes, the pages are in the docs, written by the agent. From that moment they are yours to edit, the same as any page you wrote by hand. Running onboarding again does not duplicate the work; it writes to the same pages by their path, so a re-run updates them in place, including any hand edits to a page it produces again. The full authoring how-to, the editor, the tree, and what a re-run does and does not touch, is its own page under repository documentation and wiki.

You can also edit a page directly. The docs editor opens to a tree on the left, a header at the top, and a markdown editor in the middle. Admins can update a page through the API without going through a Flow when the situation calls for it.

A review that keeps the docs current

Conventions move. Names change. An endpoint gains a parameter, a diagram stops matching the deployment, an onboarding step breaks on the fourth try. Documentation drifts the moment the code starts shipping, and the gap widens whenever nobody is looking. The health review is what makes someone look.

A health review is a scheduled Flow that runs against one repository. It reads the docs, reads what has actually happened in the repo since the last review, and surfaces a batch of proposals. Each proposal is one of four kinds: an update to an existing page (a set of small edits, never a rewrite), a new page the docs are clearly missing, a restructure when a page has outgrown its layout, or a deprecation when a page no longer reflects how the system works.

Every proposal comes with a confidence (high, medium, or low) and a rationale that ties the suggestion back to the evidence behind it.

The signals it watches for

The review does not invent things to suggest. It only proposes when there is concrete evidence, and the evidence has shape. Ten kinds of signal are captured as work happens, each one stamped with the session, the user, and a fragment that lets you trace the suggestion to its origin.

A proposal explains itself through its signals. When you accept the edit, you are accepting the platform's read of the evidence behind it.

Small edits, not rewrites

A rewrite is hard to trust. It touches everything, the reviewer has no good way to look at it line by line, and the result is either accepted whole or rejected whole. So the platform never proposes a rewrite when it can propose a set of small edits instead.

An update proposal is a list of edits. Each edit names the exact text it wants to replace, the text it wants to put there, and the reasoning behind the change. You approve, reject, or revise each one. The proposal does not move forward until every edit has a decision, and when it applies, only the approved edits land.

This matters when a proposal is mixed. Two of the five edits are clearly right; one is wrong about a convention; two are debatable. With surgical edits you take the two that are right, you reject the one that misses, you rework the two that need work, and the platform records the result as partially applied. The page reflects what you actually shipped. Nothing was forced through, and nothing of value was lost.

When the page moved underneath the proposal

If the page changed between when the proposal was generated and when it is reviewed, an edit's find string may no longer match. The platform handles this in two layers. A recoverable drift, where one or two anchors no longer match, lets you reject those edits cleanly and apply the rest, with the result recorded as partially applied. A blocking drift, where the target page has been deleted or has moved out from under the proposal entirely, blocks the proposal at the apply step and surfaces the error on the record so a person can decide what to do.

The recoverable case is the common one, and that is the point of breaking the work into discrete edits in the first place. One anchor going stale does not lose the rest of the analysis.

Reviewing a batch

Each review run produces one batch of proposals. You filter by confidence, by change type, or by status; you can walk them one at a time, or you can run a bulk action across the whole batch. That last one is the dial that decides how much you want to trust the agent.

A team that wants to move fast bulk-approves the high-confidence proposals and triages medium and low by hand. A team that wants to slow down keeps every proposal in review. Both are reasonable; the surface is the same.

The cross-repo view

If you are running reviews across several repositories, the cross-repo view rolls up the open proposals across all of them. You see which repo has the most pending work, how many of the proposals are high confidence, and where the next half hour is best spent. Repos with nothing to review stay off the list so the view focuses on what wants attention.

Configuring a review

A review is configured per repository, on the repository's own settings where you connect it: a cron schedule and a lookback window that sets how far back the review reads. Each run gathers the docs and the recent work, analyzes them for drift, and writes up what it found as a batch of proposals, then stops in front of a person. Nothing changes a page until someone approves it.

The way you move fast is the high-confidence column. When you trust what a review marks high confidence, you approve those proposals as a group and give your real attention to the rest. The full review experience, walking a batch, approving the surgical edits inside a proposal one at a time, and the bulk approve-all-high-confidence action, is its own how-to under documentation health reviews.

How the agent uses the docs

The docs are not just somewhere you go to read. They are somewhere the agent goes to read, in the middle of a run, when it needs to know what your conventions actually are. The agent queries them the same way it would look up a function in your codebase: only the pages it needs, only when it needs them. A large doc set does not crowd out the prompt; the agent calls for what is relevant.

The point of that design is the loop it closes. When a page is missing, the agent's failure to find one becomes the agent-search-pattern signal that feeds the next review. When a page is wrong, the next correction in chat becomes the user-correction signal. The drift becomes the work, the work becomes the proposal, the proposal becomes the page. The docs do not stay current because someone remembered. They stay current because the system has a job to do.

Permissions

Reading the docs goes with the platform-docs.read scope; editing goes with platform-docs.manage. Scheduling a review and changing its lookback window sit behind the standard admin bundle that governs the rest of workspace automation, and approving a review's proposals is held by your planners, admins, and owners. An applied change is tied to the proposal that produced it, the signals it was built from and the person who approved it, so the audit trail can answer who changed a page and why.

The bigger picture

Most teams have given up on keeping documentation current. The honest version of that story is that nobody was being paid to do it, and the rest of the work was always more pressing. The health review turns the maintenance into a Flow you can review the same way you review a pull request: a clear proposal, a rationale, an edit you can accept, revise, or reject. The docs stay current because the system makes it cheap, and because the agent that benefits from them is the same one helping write them.