# How Docup works

How Docup reads a repository, plans pages, writes them, and keeps drafts, live pages and your own edits apart.

Docup is a pipeline with a human checkpoint in the middle. It reads your repository, writes a draft, and stops. You decide what readers see. This page explains each stage and the ideas behind them, so the rest of the docs make sense.

## The first run

When you create a project, Docup runs four steps.

### Read

Docup downloads your default branch as one archive and keeps only the files it is allowed to read. It skips dependencies, build output, lockfiles, binaries, environment files, keys and anything you listed as an ignore path. It reads at most 1,500 files and about 12 MB of text, and skips any single file over 100 KB. The exact rules are in [AI guidance](/settings/guidance).

### Plan

A planner explores the code with tools and decides which pages your project needs. It follows a few rules:

- Write for the people who use the project, not the people who work on it.
- Start with an overview, then getting started, then the main guides, then reference pages such as configuration, API or CLI, but only when the code really has them.
- Plan at most 15 pages. Fewer, focused pages beat many thin ones.
- Plan pages only about things that exist in the code.

Every planned page gets a path, a title, a one-sentence summary, and the list of repository files it should be written from. Paths have at most one folder level, such as `guides/installation`.

### Write

Each page is written by a writer that reads the page's files, and any other file it needs, before it writes. The writer is told to state only what it verified in the code and to leave out anything it cannot confirm. It produces plain Markdown with headings, fenced code blocks and occasional callouts. Pages are written four at a time.

If an attempt returns nothing usable, Docup tries again, up to four attempts per page. A page that still fails is marked **Failed**, and the rest of the run continues.

### Save

The pages are stored as drafts. The project becomes ready, and you land on the dashboard. The commit that was read is remembered, which is how later updates know what changed. See [Keeping docs up to date](/guides/updates).

## Drafts and live pages

Every page has two versions of its text.


|                 | Draft                                | Live                 |
| --------------- | ------------------------------------ | -------------------- |
| Who sees it     | You, in the dashboard and in Preview | Readers of your site |
| What changes it | Editing, moving and reordering pages | Publishing           |
| Used by Ask AI  | No                                   | Yes                  |


Edits, new pages, moved pages and a new sidebar order all stay drafts until you publish. Publishing copies the draft text, path and order to the live site in one step. See [Publishing your site](/guides/publishing).

### Taking content offline

You can take content down while keeping your drafts intact:
- **Unpublishing the site** takes the entire site offline. Every page is returned to a draft state, ready to be published again with one click. This does not affect your draft content.
- **Unpublishing a page** takes that specific page off the live site. If you unpublish the last remaining live page, the entire site goes offline since a site without live pages is not reachable anyway.

## Your edits are protected

Docup remembers the last text the AI wrote for each page. A page counts as **edited by you** as soon as its text differs from that.

- Later updates never overwrite an edited page. They propose a suggestion that keeps your wording and changes only what the code needs. You review it as a line-by-line comparison.
- **Reset to AI version** puts the AI's last text back.
- Instructions in [AI guidance](/settings/guidance) steer new writing but never overwrite edited pages.

## Pages remember their sources

Each page records the repository files it was written from. The list is shown on the page as **Generated from**. It is the link between your code and your docs:

- When a push changes one of those files, the page is a candidate for an update.
- When a file is renamed, the list follows it.
- When every file of a page is deleted, Docup flags the page and asks whether you want to unpublish, keep, or delete it.

Pages you create by hand have no sources, so pushes never touch them.

## What the AI can and cannot do

- It reads only the files that pass the filter, and only from the branch Docup tracks.
- It never edits your repository.
- It writes into drafts. The one time text goes live without you clicking Publish is when a push updates a page you have not edited, on a site that is already live. See [Keeping docs up to date](/guides/updates).
- It is told not to guess commands, options or defaults. Still, you know your product best. Read the draft, and check code samples and names before you publish.

> **Tip:** The more your repository explains itself, the better the draft. A clear README, documented configuration and an `.env.example` file all give the writer facts to work from.