# Documentation generation lifecycle

## Documentation generation lifecycle

A documentation generation run is the background work that creates documentation for a project.
Use this page to find a run, follow its stages, and choose the next action from its status.

| If you need to… | Go to |
|---|---|
| Understand the run's stages and statuses | [Understand the lifecycle and screen](#understand-the-lifecycle-and-screen) |
| Open a project run or the organisation-wide activity view | [Find a generation run](#find-a-generation-run) |
| Refresh progress or stop an active run | [Monitor and manage a run](#monitor-and-manage-a-run) |
| Interpret a completed, failed, or cancelled run | [Handle status branches](#handle-status-branches) |
| Start documentation generation | `run-documentation-work` |
| Review status meanings | `documentation-job-status-reference` |
| Review the full run history | `job-history` |
| Open the organisation-wide activity view | `operations-overview` |
| Review published output | `published-documentation` |
| Resolve shared errors | `general-error-messages` |

## Before you start

A project context identifies which generation runs you are reviewing. The project jobs page takes
the project identifier in its route, while manual insights on Operations use the projects
returned for your organisation.

**Prerequisites**

- Know the project whose generation activity you need to inspect.
- Have access to the project jobs route or the `Operations` page.
- For manual insights, have at least one project returned by the project list.

## Find a generation run

A generation run appears either in one project's job history or in the organisation-wide
**Operations** view.

**Prerequisites**

- Have the project identifier when opening a project-specific list.

**Steps**

1. Open the route that matches the work you need to review.

   | If you need to… | Open |
   |---|---|
| Review one project's generation runs | [Job history](doc:job-history) |
| Review organisation-wide generation activity | [Operations overview](doc:operations-overview) |

2. On the project jobs page, use the link back to the project when you need the project's main
   page.

**Result:** The selected project jobs list or the organisation-wide operations view is on screen.

## Understand the lifecycle and screen

The jobs screen is a list of generation runs with loading, empty, active, completed, and failed
states. An active run reports progress; an expanded completed or failed row provides more detail.

The page requests up to 50 runs for the selected project and listens for progress, completion,
failure, cancellation, and screenshot-progress updates for active runs.

The five displayed stages are shown in this order:

```mermaid
flowchart LR
  A[Cloning Repository] --> B[Analyzing Code]
  B --> C[Generating Docs]
  C --> D[Uploading to Database]
  D --> E[Publishing Documents]
```

| What you see | Meaning |
|---|---|
| `Loading runs…` | The project job list is loading. |
| `No generation runs yet` | The project has no generation runs to list. |
| `Configure & run documentation generation →` | The empty state offers the route into generation configuration. |
| `Waiting to start...` | A pending job has no current stage yet. |
| `Starting...` | An active job has no live stage yet. |
| `Completed` | The run completed. |
| `Failed` | The run failed. |
| `Running` | The run is active. |
| `Pending` | The run is waiting to start. |
| `Cancelled` | The run was cancelled. |

The jobs page and Operations page do not ask you to enter values. The Operations page can show
a project selector when more than one project is returned; each option uses the returned project
name.

## Monitor and manage a run

Use this procedure while a run is listed and you need current progress or need to stop an active
run.

**Prerequisites**

- Have the project jobs list open.
- For cancellation, the run has status `Running` or `Pending` and **Cancel** is available.

**Steps**

1. On the project jobs page, select **Refresh**, or in Recent Jobs, select **Refresh job history**.

2. If the active job shows **Cancel**, select **Cancel**.

3. Select **Are you sure?** to confirm the cancellation.

**Result:** The list is refreshed, or the active run is cancelled and its status changes to
`Cancelled`.

## Handle status branches

A job status tells you which part of the generation work is available for review and which controls
you can use next.

**Prerequisites**

- Have the project jobs list open.
- Know the status shown on the job row.

**Steps**

1. Select a job row with status `Completed` or `Failed` to expand its details.

2. Review the expanded result for a completed run or the failure details for a failed run.

3. Use the status-specific control shown on the row.

   | Status and condition | Control and outcome |
   |---|---|
   | `Completed`, `Failed`, or `Cancelled`, with created documents | Select **Delete <n> Docs** once to arm deletion, then select **Confirm Delete?**. |
   | `Completed`, `Failed`, or `Cancelled`, with no created documents | Select **Delete Job** once to arm deletion, then select **Confirm Delete?**. |
   | `Running` or `Pending` | Monitor the progress display or use **Cancel**. |

Completed and failed rows also support regeneration after review. Continue with
`run-documentation-work` for the generation task.

**Result:** The selected row is expanded for review, remains active for monitoring, or shows its
status-specific action state.

## When the run goes wrong

Use the message on screen to decide whether to wait for loading, refresh the relevant surface, or
inspect the failed job's details.

| What you see | What it means | What to do |
|---|---|---|
| `Jobs failed to load.` | The jobs request failed while no job rows were available. | Refresh the project jobs page with **Refresh**. |
| `Operations failed to load.` | The operations request failed. | Reopen **Operations** or refresh **Operations**. |
| `Loading insights…` | Manual insights are loading for the selected project. | Wait for the insights panels to load. |
| `Insights failed to load.` | The manual-insights request failed. | Reopen the **Operations** page. |
| `Job Failed` | The selected job has failed. | Expand the failed row and read its error detail. |
| A failed job's error detail | The job's error text is displayed below `Job Failed`. | Use that text when following up. |

**Prerequisites**

- Have the message on screen.
- For a job message, have the project jobs list open.
- For an Operations message, have access to **Operations**.

**Steps**

1. Follow the alternative that matches the message.

   | If you see… | Do this |
   |---|---|
   | `Jobs failed to load.` | Select **Refresh** on the project jobs page. |
   | `Operations failed to load.` | Reopen **Operations**. |
   | `Loading insights…` | Wait for the manual insights panels to load. |
   | `Insights failed to load.` | Reopen **Operations**. |
   | `Job Failed` | Select the failed job row and read its error detail. |
   | A failed job's error detail | Use the displayed error text when following up. |

2. If `Loading operations…`, `Loading runs…`, `Starting...`, or `Waiting to start...` appears,
   wait for the current loading or job state to update.

**Result:** You have refreshed the project jobs page, reopened **Operations**, waited for the
current state to update, or read the failed job's error detail and know the next action.

## Know what happens next

After you review the run, continue with the page that owns the next task or reference.

| Next need | Continue with |
|---|---|
| Start a generation run | `run-documentation-work` |
| Interpret a status | `documentation-job-status-reference` |
| Review previous runs | `job-history` |
| Review organisation-wide activity | `operations-overview` |
| Review published output | `published-documentation` |
| Resolve shared errors | `general-error-messages` |

The empty jobs state points to **Configure & run documentation generation →**. After a run completes
or fails, the jobs list refreshes so the updated status and run details appear in the list.