Repository documentation & wiki

Most teams keep their real knowledge about a service in three places that all go stale: a README nobody updates, a wiki nobody opens, and the head of the one engineer who has been there longest. Disco Parrot gives every repository a fourth place that does not go stale, because the agent that reads the docs to do its work is the same one that surfaces where they have gone wrong. Each repository has its own set of pages, they live in the platform next to the work, and the agent reads them in the middle of a run the way it reads your code.

This page is the how-to for the pages themselves: what a doc page is, how to get a repository's foundation written for you instead of by you, how to edit and organize the pages by hand, and where they live. For the scheduled review that keeps them current, see documentation health reviews; for the concept behind treating docs as a working artifact, read repository documentation. This page is about authoring and onboarding; that one is about the review loop.

What a doc page is

Every page is markdown, and that is a decision, not a default. There is no proprietary block format, no embed registry, nothing new to learn, and nothing that locks the content to this product: the same plain text a person reads is the text the agent reads, with no rendering layer in between to drift out of sync. A page carries a small, flat shape: a title, a path that the tree uses to group it, an optional category, and a scope that pins it to one repository. That is the whole record.

The shape is deliberately thin, because the point is that the docs read like a notebook your team keeps, not a content management system you administer.

The scope is what makes these repository docs rather than loose pages. A repository's pages are scoped to that repository, written as repo:owner/name, so the docs for your Insights service are its own set and never bleed into another repository's. A separate workspace-wide scope holds pages that belong to no single repository. When the agent works in a sandbox cloned from a repository, the docs it can reach are that repository's, which is what keeps a large workspace's documentation legible instead of one undifferentiated pile.

Get the docs without writing them

You can fill a repository's docs by hand. Most teams do not want to start from a blank tree, and they do not have to. The faster path is repo onboarding, a Flow that spins up a sandbox against the repository, reads the code, and writes the foundation pages for you.

Onboarding is something you run, not something that happens to you. Connecting a repository does not kick it off; you launch the onboarding Flow when you want a repository's docs bootstrapped, which means a new connection never spends an agent run you did not ask for, and you can re-run it deliberately when the code has moved far enough to be worth re-reading. Onboarding writes only into the platform's doc store; it does not touch your repository's committed files, so your README.md and any docs/ folder you already keep in Git stay exactly as your team wrote them.

The Flow works in passes, and the order is the point. It reads the repository and plans what is worth documenting, then writes the foundation, the architecture and conventions a newcomer needs first. After that it writes the domain and API pages, and last the decision records and quality references. A human checkpoint sits after the foundation is written, before the domain pass begins, and a second sits after the domain pass, before the decision records, so you get two moments to read what the agent has produced before it builds deeper on top of it. Send the run to the background and the checkpoints auto-advance; sit with it and they wait for you.

When the Flow finishes, the foundation pages are in the repository's docs, written by the agent. From that moment they are yours: edit them, reorganize them, delete the ones you do not want, exactly as you would a page you typed yourself. Running onboarding again does not pile up duplicates. It writes to the same pages by their path, so a second run updates the foundation in place rather than leaving you two architecture pages to reconcile.

Edit and organize by hand

Whether the agent wrote a page or you did, you edit it the same way, on the repository's own Documentation tab. The surface reads like a wiki and edits like a notebook: a tree of pages on the left, the page itself in the center, and a markdown editor when you switch a page into edit mode.

The tree is built from the paths on the pages. A page whose path is architecture/data-flow files itself under an architecture folder; group pages by giving them a shared path prefix, and the tree assembles the folders for you. There is no separate folder object to create and keep in sync, which means moving a page between folders is just changing its path, and a folder exists exactly as long as a page lives under it.

Four actions cover the whole surface. You create a page like this:

1. Name it, and the identifier is derived from the title so you are not hand-managing slugs.
2. Drop it under a folder, either an existing one you pick or a new path you type.
3. Write the body in markdown and save.

You edit a page in place: the title up top, the markdown body in the center, save or cancel. You organize by editing the path, the same field that put the page in the tree in the first place. And when a repository accumulates pages it has outgrown, you clear them out in a batch: hold the modifier key to select several pages in the tree at once, and delete the lot behind a single confirmation rather than one page at a time.

Where the docs live, and why there

A repository's docs live in the platform's own document store, the same place the agent reads them from, not in a docs/ folder committed to GitHub. That is a deliberate choice, and it is the choice that makes the rest of the loop cheap.

Keeping the docs in the platform is what makes a health review cheap enough to be worth running. When an approved fix is a write to the same store the agent already reads, applying it is a click.

If the docs lived only as files in your repository, every drift fix would be a second pull request to open, review, and merge, which is exactly the weight that stopped anyone from making those fixes in the first place. The docs sit where the agent reads them and where a person can correct them in one move, and that proximity is the whole reason they stay current instead of rotting in a folder nobody opens.

The trade you are reading correctly: these pages are not your repository's committed README.md, and they do not open a pull request when they change. They are a living knowledge base that the platform keeps and the agent uses, separate from the source it documents. Your code stays in GitHub where your team governs it; the docs about that code live where the agent and the review can keep them honest.

How the agent reads the docs

The docs are not only somewhere a person goes to read. They are somewhere the agent goes to read, at the start of a run, so it works against your conventions instead of inventing its own. When an agent starts working in a repository's sandbox, the platform looks for one of the repository's orientation pages, an index, an overview, an architecture page, or a conventions page, and loads it into the agent's context before it takes its first action. The agent that is about to touch your code starts by reading what your team wrote about it.

A repository with no pages yet costs nothing here. The agent starts cold, the way any agent would, and the first time it reaches for a page that is not there, that miss is itself the signal that tells the next review what the foundation is still missing. The orientation grows from empty as you and onboarding fill it in.

That is also what closes the loop with the health review. When the agent goes looking for a page that does not exist, that gap is captured as a signal. When a page is wrong and someone corrects the agent in chat, the correction is captured too. Those signals are what the next review reads, so the drift the agent hit on Tuesday is a proposal in Monday's batch. The docs do not stay current because someone remembered to update them; they stay current because the agent that relies on them is the same one surfacing where they are wrong.

A repository, documented end to end

Maya has just connected the Insights service as the Insights API repository, and the docs tree is empty. Rather than write the architecture page from scratch, she launches repo onboarding against it. The Flow spins up a sandbox, crawls the repository, and stops at the first checkpoint with the foundation drafted: an architecture overview and a conventions page. She reads them, fixes one sentence about how the service talks to the warehouse, and clears the checkpoint. The Flow writes the domain and API pages, pauses again before the decision records, and she lets that one run to the end.

When the run finishes, the Insights API repository has a real doc tree, its foundation written from the code. Maya opens the conventions page, switches it to edit, and adds the one rule the agent could not have inferred: that the team always writes its CSV exports through the shared formatter. She saves. The next engineer who runs an agent against Insights API gets a sandbox whose agent has already read that conventions page, so it reaches for the shared formatter without being told. The page Maya wrote once is now the thing that keeps every future run on the rails.

Permissions

Reading a repository's docs goes with the platform-docs.read scope, which every member and viewer carries, so anyone in the workspace can read what a repository documents. Creating, editing, organizing, and deleting pages go with platform-docs.manage.

Running and managing the onboarding Flow has its own pair: onboarding.read to see a repository's onboarding state and what it produced, and onboarding.manage to launch, reset, or clear it. The split is the usual one. Reading is open so the docs serve the whole team; changing what they say, and running the agent that writes them, is held by the people you trust to decide what your documentation says.

Why repository docs work this way

The reason documentation rots is never that people do not value it. It is that keeping it current was always somebody's twelfth priority, and the cost of an update, find the page, edit it, open a pull request, get it reviewed, was high enough that the update lost every time to more urgent work. Disco Parrot does not fix that by asking people to care more. It fixes it by moving the docs to where the cost of keeping them current is nearly zero: a living store the agent reads and a person edits in one move, with onboarding to write the first draft and a review to catch the drift.

The pieces are ordinary on their own, markdown pages, a tree, an editor. What makes them work is where they sit. The docs are close enough to the work that the agent reads them mid-run, close enough to a person that a fix is a click, and close enough to the health review that drift becomes a proposal instead of a slow decay. The knowledge that used to live in one engineer's head lives on a page the whole team can read and the agent can act on.

For a planner, repository docs are the one place the team's understanding of a service is written down the same way for everyone, so a plan is built against shared facts instead of whatever each person half-remembers. You run onboarding once, and the architecture and conventions are there for the next person, or the next agent, to plan from.

For an engineer, the docs read and edit like a notebook: markdown, a tree built from paths, an editor a click away. Onboarding writes the foundation the code can already explain, so you spend your time on the one convention it cannot infer, not on transcribing what the code already says.

For a lead, the docs stop being a project that never ships and become a working artifact that maintains itself. The knowledge that walked out the door with every departure now sits on a page, and the agent reading it on every run is the thing that keeps it honest.

For the person who has to sign off on letting an agent near the team's knowledge base, the boundary is clean: the docs live in the platform's store, not in your source; the agent reads them and a person decides what they say; and onboarding is a run you launch deliberately, not an automatic process you have to trust. The agent helps write the docs, but a person owns every word that stays.