# Run documentation work

## Overview

A documentation generation run is a project job that creates a documentation version and reports
its progress until it completes, fails, or is cancelled. Use this page when you need to start a
run, monitor work already in progress, or decide what to do after the result appears.

| If you need to… | Go to |
|---|---|
| Prepare the project and choose run options | [Before you start](#before-you-start) |
| Open the correct work surface | [Find the work surface](#find-the-work-surface) |
| Start a new run | [Start a documentation generation run](#start-a-documentation-generation-run) |
| Check progress or refresh job history | [Monitor and manage a run](#monitor-and-manage-a-run) |
| Respond to a status, empty state, or error | [Handle status branches and errors](#handle-status-branches-and-errors) |
| Continue after the run changes state | [Know what happens next](#know-what-happens-next) |
| Understand the Operations hub | [Operations overview](doc:operations-overview) |
| Read each job status | [Documentation job status reference](doc:documentation-job-status-reference) |
| Follow the ordered generation stages | [Documentation generation lifecycle](doc:documentation-generation-lifecycle) |

## Before you start

A project is the context for both starting a generation run and reviewing its jobs. Sign in before
opening the project work surfaces. The project must have an identifier so you can open its jobs
route, and the project information used by generation must already be saved.

**Prerequisites**

- Have a signed-in session with access to the project.
- Know the project to generate or monitor.
- Have the branch, optional version label, screenshot choice, video choice, and page limit ready
  if you need to change the run settings.

The generation form treats **Version label** and **Max pages** as optional. The choices for
rebuilding, fixing findings, or capturing from the application appear only when the available
preview reports pages. An unavailable **Fix findings only** or **Capture from the app** choice is
disabled.

| If you want to… | Choose or provide… |
|---|---|
| Use a repository source | A value in **Generate from** or the selected branch |
| Identify this version later | A value in **Version label** |
| Limit the number of pages | A positive value in **Max pages** |
| Include updated page images | **Include screenshots** |
| Add narrated walkthroughs | **Generate narrated videos** |
| Choose how to generate | Select the generation method. |

## Find the work surface

**Operations** is the hub for operational activity. A project's **Activity & Jobs** view is the
project-specific place to monitor generation runs and refresh their history.

1. Select **Operations** in the application navigation.
2. Open the project's jobs route to reach **Activity & Jobs**.
3. Select **Configure & run documentation generation →** when the jobs view shows that no
   generation runs exist and you need to move to project settings.

**Result:** The work surface is ready for either the project generation form or continued monitoring
in the selected project's **Activity & Jobs** page.

While the Operations page is loading, it can show `Loading operations…`.

The Operations surface can show these job-table headers:

| Timing and state | Work and output | Cost and detail |
|---|---|---|
| **When**, **Status**, **Stage**, **Duration** | **Operation**, **Docs** | **Model**, **Calls**, **Tokens**, **Cost**, **Error** |

Work from the headers and messages visible in your list.

## Start a documentation generation run

A generation run starts work for the selected project and source. Choose the source and optional
settings before committing the start action.

**Prerequisites**

- You are signed in and have opened the project generation form.
- The project information and source branch are available.
- The form is not loading and another generation is not already running.

**Steps**

1. Choose the source branch using one option from this table.

   | If you need to… | Action |
   |---|---|
   | Use the selected branch | Enter the branch in **Generate from**. |
   | Choose another branch | Select **Select Another Branch**, enter text in **Search branches**, then select the branch. |

2. Enter a value in **Version label** when you want to identify the new version.
3. Select **Include screenshots** to include updated screenshots.
4. Select **Generate narrated videos** to record narrated walkthrough videos.
5. Enter a positive page count in **Max pages** when you want to cap the number of pages.
6. Select one available generation option from this table.

   | If you need to… | Select… |
   |---|---|
   | Rebuild the documentation | The available rebuild option |
   | Fix recorded findings | The available fix option |
   | Include application content | **Capture from the app** |

7. Select **Generate** to start the generation.

When the form is loading or a generation is already in progress, **Generate** is disabled. If the
start request fails, the error condition can show `Failed to start generation`.

**Result:** The generation form changes to its progress phase and shows the current stage and
progress for the run.

## Monitor and manage a run

**Activity & Jobs** is the project list of generation runs. An active run is a **Running** or
**Pending** job with progress information; a **Completed** or **Failed** job can be expanded for
its outcome or failure details.

**Prerequisites**

- You have opened the project's **Activity & Jobs** page.
- The project has loaded its job history.

**Steps**

1. Read the status shown for each job row.
2. Select **Refresh** in the page header to request the latest job history.
3. Select **Refresh job history** in the Recent Jobs area when that control is available.
4. Select a **Completed** or **Failed** job row to expand its details.
5. Read the progress area on a **Running** or **Pending** job, including its stage and percentage.

The page can show `Loading runs…` while the first list request is in progress. A project with no
jobs shows `No generation runs yet`.

`Every documentation generation run for this project lands here.`

**Result:** The page shows the latest available job history, and an expanded row or progress area
shows the information for the run you selected.

## Handle status branches and errors

Each job status changes which operation is available. Use the status and the exact message on
screen to choose the safe next action.

| What you see | What to do |
|---|---|
| A **Running** or **Pending** job | Select **Cancel** once. The control changes to **Are you sure?**; select it only when you intend to cancel the run. |
| A completed, failed, or cancelled job with generated documents | Select **Delete N Docs** once, then select **Confirm Delete?** only when you intend to remove those documents. |
| A completed, failed, or cancelled job without generated documents | Select **Delete Job** once, then select **Confirm Delete?** only when you intend to remove the job. |
| An error phase with a retry option | Select **Retry Generation** to return to the configuration phase. |
| `Version Generated!` | Review the document and category counts, then continue to the project's versions. |
| `Generation was cancelled` | Treat the run as cancelled and return to configuration or start a separate run. |
| `Job Failed` | Read the failure details in the expanded row before choosing a recovery action. |
| `Jobs failed to load.` | Check the project jobs page again. |
| `Failed to load job history: {error.message}` | Select **Refresh job history** to request the history again; read the changing error details after the prefix. |
| `Showing the last successful load — refreshing failed ({error.message}).` | Continue using the displayed rows, then select **Refresh job history** again; read the changing error details in parentheses. |
| `Operations failed to load.` | Return to **Operations** and reload the operational surface. |
| `Insights failed to load.` | Continue with job monitoring; the insights area is separate from the job list. |
| Queues are absent or unavailable | Continue with the job tables and status rows that are present. |
| Needs-attention data is absent | Continue with the available Operations sections. |
| Manual insights has no project selector | Use the currently selected project. |

**Result:** You have either kept the run available for monitoring, returned it to configuration,
or completed the status-specific action shown on screen.

## Know what happens next

The completion phase is the handover from generation work to version review. It shows the document
and category counts for the generated version. An active run remains available in **Activity & Jobs**
for continued monitoring.

After `Version Generated!`, open the project's versions to review the new version. Use
[Documentation job status reference](doc:documentation-job-status-reference) when you need the
meaning of a status, and [Documentation generation lifecycle](doc:documentation-generation-lifecycle)
when you need the ordered stages.

**Result:** You know whether to review the project's versions, continue monitoring **Activity &
Jobs**, or use the status and lifecycle reference pages.