# Crop, redact, and annotate documentation images

import { Aside, Steps } from '@astrojs/starlight/components';

Ask Docs Agent to crop a documentation image to what the page is about, cover information that must not reach public documentation, or mark up the part of the interface your prose refers to. You can ask for each edit on its own or combine them in a single pass.

## Before you begin

You need:

- An EkLine account with Docs Agent enabled.
- A repository [connected to EkLine](/agent/github-app-setup/) that holds both your documentation pages and their image files.
- At least one image the agent can reach as a file. That means an image already committed to your connected repository, one the agent captured itself from a [sandbox](/agent/sandbox/), or a frame it [extracted from a video](/agent/screenshots-from-video/).

<Aside type="note" title="Which images the agent can edit">
The agent edits image files it can open in the session. These include images from your connected repository, a sandbox capture, a video frame, or a Confluence page it retrieved while [managing a knowledge base](/agent/manage-knowledge-base/). An image you attach to a chat message is different: the agent can see it and describe it, but it has no file to edit. To retouch a screenshot you have on your machine, commit it to your documentation repository first.
</Aside>

The agent edits PNG and JPEG files. It leaves vector images such as SVG untouched.

## Crop an image to what it shows

Cropping an image to the element it shows is the edit that helps most screenshots.

<Steps>
1. Open the Docs Agent editor and start a new session.

2. Name the image and what it should show:

   ```text
   Crop the screenshot in our billing guide so it shows only
   the Payment method panel, not the whole page.
   ```

3. Select the edited image's tab in the editor to review it. The image renders in the editor panel, and you can click it to open it full size.

4. Click **Raise PR** to open a pull request with the cropped image. The button fills the chat box with a message. Send it, and the agent opens the pull request.
</Steps>

The agent matches the padding, width, and light or dark theme of the images already beside it on the page, so a recropped image doesn't stand out from its neighbors. It cuts what doesn't illustrate the point, such as unrelated sidebars, panels, and toolbars, while keeping the page header or navigation item a reader needs to orient.

## Hide personal information

Screenshots taken in a real account show real data: names, email addresses, phone numbers, billing details, API tokens, and faces. Hide it before the image reaches public docs.

<Steps>
1. Tell the agent which image and what to hide:

   ```text
   The dashboard screenshot in our getting-started guide shows a
   real customer's name, email, and account ID. Hide those before
   we publish it.
   ```

2. Tell the agent whether the fields should look empty or hold sample data. Use sample data where a filled-in field is part of what the image teaches. An empty field is fine for an input that would show placeholder text:

   ```text
   Replace them with sample data rather than leaving the fields empty.
   ```

3. Review each covered region in the result. Confirm nothing readable remains, including partial text at the edge of a box and the same value repeated elsewhere in the image, such as an email that also appears in a header.
</Steps>

<Aside type="caution" title="Covering is not blurring">
The agent covers information with a solid, opaque fill. It doesn't blur or pixelate it, because blurred and pixelated text can be recovered. A blur is acceptable only on a real person's face, where no text is at risk, and even there the agent prefers a solid placeholder.
</Aside>

If the agent cannot fully cover a region, such as text that runs under a graphic, it still delivers the image. It flags the problem in its summary and in the pull request. Read that warning before you merge.

## Add a highlight, arrow, or numbered callout

Use annotations when a step refers to one control on a crowded screen.

<Steps>
1. Describe what to mark and how:

   ```text
   In the settings screenshot, outline the Save button and add an
   arrow pointing at the Advanced options toggle.
   ```

2. For an interface with several parts, ask for numbered markers and refer to those numbers in your text:

   ```text
   Add numbered markers to the editor screenshot: 1 on the file
   tree, 2 on the chat panel, 3 on the preview pane.
   ```

3. Review the placement. The agent matches the shape and accent color of annotations on the sibling images beside it, so a new image looks like it belongs.
</Steps>

The agent puts markers on the image, not text. Explain each marker in your prose: text drawn on an image can't be found by site search, read by screen readers, or translated.

Annotations are repeatable. Asking for the same highlight twice doesn't stack two outlines on top of each other.

## Combine edits in one pass

Ask for several edits together, and the agent applies them in a safe order: cover information first, annotate second, crop last.

```text
Take the account settings screenshot in our onboarding guide:
hide the customer's name and email, highlight the Notifications
toggle, and crop it to the settings panel.
```

## What the agent changes and what it leaves alone

| The agent | Detail |
|-----------|--------|
| Writes to the image's existing path | The edited image replaces the file your page already references, so no link needs updating |
| Leaves your repository untouched until you merge | The change arrives as a pull request you review, like any other documentation change |
| Matches its neighbors | Padding, width, theme, annotation shape, and accent color follow the sibling images beside it |
| Asks when a value might be real | In a session, if it can't tell whether a name or number is genuine or sample data, it asks you. An unattended run covers the value instead of asking |
| Leaves prose alone | It edits pixels only. For documentation that describes the interface incorrectly in text, use [Update and review](/agent/update-review/) |
| Skips vector images | SVG diagrams and logos stay untouched |
| Follows your call in a session | Whether an image needs cropping, covering, or annotating is yours to decide: a capture from a demo account often needs none of it. A scheduled run given no instruction defaults to making the image publishable |

## Verify the result

Before you merge the pull request:

- [ ] Every covered region is fully opaque, with no readable text at its edges.
- [ ] No value you asked to hide survives elsewhere in the same image.
- [ ] The cropped image still shows enough context for a reader to locate the element in the live product.
- [ ] Annotations point at the controls your prose names, and the numbering matches your steps.
- [ ] The image sits comfortably beside the others on the page in width and theme.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| The agent says it can't find the image | Give it the path or the page that references the image. An image you attached to a chat message isn't a file the agent can edit. Commit it to your repository first. |
| Nothing happened to an SVG | Cropping and covering are raster operations. Export the diagram to PNG, or edit the SVG source directly. |
| The edit covered too much or too little | Describe the region by what it contains rather than by position: "the panel with the Save button", not "the top right". |
| Text is still faintly visible | Ask the agent to extend the covered area past every edge of the text. Report any region it says it couldn't fully cover. |
| The new image looks different from the others on the page | Name the image you want it to match: "make it the same width and theme as the other screenshots in this guide". |
| The screenshot you captured shows test data you don't want published | Point the [sandbox](/agent/sandbox/) at an account with presentable data and recapture, rather than covering every field afterward. |

## Next steps

- [Keep documentation screenshots up to date](/agent/refresh-doc-screenshots/): recapture stale images automatically, on demand and on a schedule.
- [Browse authenticated pages with a sandbox](/agent/sandbox/): give the agent the sign-in variables it needs to capture pages behind a login.
- [Capture screenshots from a video](/agent/screenshots-from-video/): turn a moment in a recording into a documentation image.
- [Manage a knowledge base](/agent/manage-knowledge-base/): add and replace images on Confluence pages.