Dashboard Workflows
Generations and Doxabot Instructions
Start generations, follow progress, review results, and guide Doxabot with project instructions
What a generation does
A generation is one run of Doxabot against a project's connected GitHub repository. Doxabot reads the repository, writes MDX pages, and stores the output as a versioned docs artifact. The output is not visible to readers until you publish it. Publishing switches the project's active docs version to the new output.
Because of this separation, a generation does not change your live site when it runs. You review the result first, then publish when it is ready. For the publishing model, see How It Works.
Before you start
A generation needs a project with a connected repository. Confirm both of these:
The project has a GitHub repository selected. Only the project owner can connect or change the repository.
You have permission to run generations on the project. Generation starts require the
generation.runpermission on the project.
Start a generation
Create a project and choose a repository
Sign in to the dashboard with Google or GitHub, open /dashboard/projects/new, and choose the GitHub repository that contains your documentation source. The project is hosted at <slug>.doxa.page.
Open the Generations page
Open your project and select Generations. The page shows the project's generation history.
Start the generation
Start a new generation from the Generations page. The run appears in the history with its current status.
Follow progress
Keep the Generations page open to follow the run. Each generation records its own events, so you can return later and review what happened in a finished run.
Agents connected through the MCP server can start, check, and cancel the same runs with the start_generation, get_generation, and cancel_generation tools. See Generation. Developers using the REST API can start a run with Start a generation.
Guide Doxabot with project instructions
Use Doxabot instructions in the project dashboard to tell Doxabot how your docs should read. Instructions work best when they are specific. Useful topics include:
| Topic | Example instruction |
|---|---|
| Audience | "Write for developers who already use our REST API." |
| Scope | "Document only the public SDK package. Skip internal tooling." |
| Structure | "Group pages under Getting Started, Guides, and Reference." |
| Style | "Use short sentences and show a complete example for every setup step." |
After a generation finishes, check its output to see whether your instructions were followed, and adjust the instructions if needed.
Review the results
When a generation finishes, review its output before you publish:
Check the run's status on the Generations page. A failed or cancelled run does not change the active version of your site.
Open the generated pages in the content editor. Use Split mode to compare the MDX source with the rendered preview. See Editing Pages in the Content Editor.
Compare the new pages with any pages you wrote or edited by hand. Keep the changes you want to preserve before you publish.
Publish when the output is ready. See Branches, Previews, Publishing, and Restore.
Note:
A generation can replace pages that a person wrote or approved. Review the output before you publish, and use branches to keep your manual edits separate until you are ready to merge them.
How generations relate to the published site
| Item | What it is | Visible to readers? |
|---|---|---|
| Generation | One run of Doxabot and its history entry | No |
| Generated output | Versioned docs artifact created by the run | No, until published |
| Active docs version | The version the published site serves | Yes |
| Publication | Switching the active version to a new output | Yes, after it completes |
After you publish, open <slug>.doxa.page and check the pages you reviewed to confirm the change is live.