# Crop, redact, and annotate documentation images

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

<Aside type="note" title="Request access">
  Docs Agent is available to all plans, but we grant access on request. Contact support@ekline.io to request access.
</Aside>

A raw screenshot is rarely publishable. It shows the whole browser window when the reader needs one panel. It carries a real customer's name and email in the corner, and nothing in it points at the control the surrounding paragraph describes.

Docs Agent makes those three edits for you. Ask it to crop an 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. This guide covers each edit on its own, then how to 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

An uncropped capture makes the reader hunt. Cropping to the element the image depicts is the single edit that improves 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. Open the edited image from the file list to review it. It renders in the editor pane, 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 prefills a chat 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 — unrelated sidebars, panels, and toolbars — while keeping the page header or navigation item a reader needs to orient.

## Hide personal information

Screenshots taken against a real account carry real data: names, email addresses, phone numbers, billing details, API tokens, and faces. Published to public documentation, that data is out of your control.

<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. Choose whether the fields should look empty or hold plausible sample data. Sample data reads better where a populated field is part of what the image teaches; an empty field is fine for a placeholder-style input:

   ```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 rather than blurring or pixelating it. Blurred and pixelated text can be recovered, so it is not a safe way to remove information from an image you publish. 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 — text that runs under a graphic, for example — 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

Annotations connect your prose to the pixels. Use them 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 and leaves explanations to your prose. Text baked into an image is invisible to site search, unreadable by screen readers, and untranslatable. A numbered marker that your paragraph explains serves readers better than a caption drawn on the screenshot.

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

## Combine edits in one pass

Most images need more than one edit. Ask for all of them together and the agent applies them in the order that produces a safe result: cover information first, annotate second, crop last. Cropping first can leave real data in an edge the crop keeps, and annotating before covering can leave a marker pointing at a field the agent then hides.

```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.