# Screenshot status and review information

Screenshot status information tells you which documentation-version screenshots
are current, carried forward, outdated, or still absent. Use it to decide which
screenshots need review or follow-up action.

| If you need to… | Go to |
|---|---|
| Review a version's screenshots end to end | [Review version screenshots](doc:review-version-screenshots) |
| Understand the screenshot gallery and versions | [Screenshots overview](doc:screenshots-overview) |

## Before you start

Select a project and version before reviewing its screenshot coverage.

**Prerequisites**

- A project is selected in the header.
- A documentation version is available for that project.
- You know which status or screenshot route you need to review.

The page requests screenshot data only after a project and version are selected.
The version selector chooses an active version first; when no active version is
available, it chooses the first available version. The available rows and status
counts come from the selected project and version.

## Find screenshots to review

Use this procedure when you need to locate screenshots in the selected version.

**Prerequisites**

- A project and documentation version are selected.

**Steps**

1. In the version selector, select the documentation version you want to review.
2. In the status filters, select the status that matches the review you need.
3. In the page-size area, select the number of rows to display on each page.
4. Select the checkbox beside a row when you need to include that screenshot in a bulk action.
5. Select **Select all on page** when you need to include every displayed row.

If no row matches the selected filter, the page shows **No screenshots found** and
the message `Placeholders appear here as soon as a document declares one.`

**Result:** The list shows the screenshots matching your selected version and
status filter, with selected rows marked.

## Understand the status screen

The status screen compares a version's screenshot placeholders with the screenshots
currently available for those routes.

The summary can show counts for **Fresh**, **Carried**, **Stale**, and **Missing**,
along with a coverage percentage.

| What you are checking | Where to read it |
|---|---|
| The route represented by a placeholder | Route path |
| The document that declares it | Document |
| The current screenshot state | Status |
| Find out how recent the image is | Age |
| Whether the source may have changed | Staleness |
| The overall counts and percentage | The summary and coverage bar |

The status values **Fresh**, **Carried**, **Stale**, **Missing**, **Valid**,
**Warning**, and **Critical** describe the available review states. A row with a
stale, warning, or critical state shows Code may have changed in its staleness
column. A carried or valid row shows **Valid** there.

When no project is selected, the page shows **Screenshots**, **No project
selected**, and `The project dropdown in the header sets the project for every
enterprise surface.` When the list is loading, it shows `Loading screenshots…`.

The page does not show the screenshot list while it is loading. When the filtered
list has no rows, it shows **No screenshots found** instead of the table.

## Open and review a screenshot

A screenshot preview is the detail view for one qualifying row. Use it to inspect
the information attached to that row before deciding what to do with it.

**Prerequisites**

- The screenshot row is visible in the selected version and filter.

**Steps**

1. In the row's action area, select **View**.
2. Identify the route, document, status, and capture date for the screenshot.
3. In Staleness analysis, check whether the route is likely valid, missing a
   screenshot, or may have changed.
4. Select **Close** to return to the screenshot list.

The preview can also offer **Annotate**, **Recapture**, **Upload replacement**,
**Remove from doc**, and **Close**. **Annotate** is available when the preview has
an image asset and an id. **View** is available for fresh, carried, valid, stale,
warning, and critical rows.

**Result:** The screenshot's review details are visible.

## Choose the action for the screenshot status

Use this procedure to choose a follow-up action without treating every status the
same way.

**Prerequisites**

- You have reviewed the row's Status and Staleness information.

| If the row is… | Use |
|---|---|
| **Missing** | **Capture** or **Upload** |
| **Carried**, **Stale**, **Warning**, or **Valid** | **Recapture** |
| **Fresh** or **Critical** | **View** |
| Selected with other rows | Bulk **Recapture**, **Remove placeholders**, or **Mark not needed** |

**Steps**

1. Choose the action for the selected row or rows:

   | If you need to… | Select |
   |---|---|
   | Add an image for a missing row | **Capture** or **Upload** |
   | Refresh a carried, stale, warning, or valid image | **Recapture** |
   | Apply one action to selected rows | **Recapture**, **Remove placeholders**, or **Mark not needed** |
   | Remove one placeholder from the preview | **Remove from doc** |

The bulk action bar appears when at least one row is selected. During bulk
recapture, the page shows `Recapturing screenshots`, a count of completed items,
and `Cancel remaining`.

**Result:** The appropriate action is selected for the selected status and rows.

## Add an image or markup

Use **Capture** when a route needs a new image. An annotation is explanatory
markup added to an existing screenshot; use **Annotate** to add it.

### Add a screenshot image

**Prerequisites**

- A screenshot row has **Missing** status.
- The project Site URL is configured.

**Steps**

1. Enter the address you want to preview.
2. Select **Preview** to load the page image.
3. Choose what to do after the preview step:

   | If you need to… | Select |
   |---|---|
   | Save the loaded image | **Save this screenshot** |
   | Leave without saving | **Cancel** |

The modal starts with a URL derived from the selected route and project Site URL.
Before a preview begins, it shows `Enter a URL and click Preview`; while the
preview is loading, it shows `Taking screenshot…`.
Before a preview is loaded, its footer says `Preview a URL first, then save`.
After a preview loads, it says `Preview loaded — click Save to use this screenshot`.
After saving, the modal shows `Screenshot captured` and `Saved to your project`.

**Result:** After a successful save, `Screenshot captured` and `Saved to your project`
appear.

### Annotate a screenshot

**Prerequisites**

- A preview has an image asset and an id.

**Steps**

1. In the preview footer, select **Annotate**.
2. In the annotation tool control, select **Select**, **Box**, **Arrow**, **Mask**, or **Marker**.
3. Select an annotation color.
4. Drag across the screenshot to draw the selected annotation.
5. For a selected non-marker annotation, enter an optional label.
6. For a selected mask annotation, select **Blur (vs solid bar)** when the mask should use the blur setting.
7. Choose one action for the selected annotation.

   | If you need to… | Select |
   |---|---|
   | Remove the selected annotation | **Delete** |
   | Save the annotations currently shown | **Save (N)** |
   | Leave the editor without saving | **Cancel** |

**Result:** The selected annotation is deleted, saved, or left unchanged according
to your choice.

## Troubleshoot a stopped action

Match the message you see to the corrective action in the table.

| What you see | What it means | What to do |
|---|---|---|
| `No Site URL configured. Go to Project Settings → Basic Information → Site URL to set it.` | The project setting needed for capture is absent. | Configure the Site URL in project settings. |
| `Failed to load preview. Check the URL and try again.` or `Preview failed` | The preview request did not load the requested URL. | Check the URL and select **Try again**. |
| `Failed to save screenshot` | Saving the screenshot did not complete. | Return to the preview and try **Save this screenshot** again. |
| `Upload failed` | The image upload did not complete. | Try **Upload** again with the intended image file. |
| `Action failed` | A bulk action did not complete. | Recheck the selected rows and retry the bulk action. |
| `Remove failed` | Removing the placeholder did not complete. | Return to the preview and retry **Remove from doc**. |
| `No screenshot has been captured for this route yet.` | No image exists for this row. | Select **Capture** or **Upload** for the route. |
| `Source code may have changed. UI could look different now.` | The image may no longer match the current page. | Select **Recapture** and review the new image. |
| `Route component unchanged — likely valid.` | The route has no reported source change. | Continue reviewing the screenshot or close the preview. |

## What to do next

After status review, use the page that owns the next task:

- Use [Review version screenshots](doc:review-version-screenshots) for the
  end-to-end task of reviewing screenshots attached to a project version.
- Use [Screenshots overview](doc:screenshots-overview) for the gallery and its
  relationship to project versions.
- Use [Project versions](doc:project-versions) for version context and selection.