Reviewing

Screenshots and annotations

Mark up screenshots with numbered boxes, arrows, pins and notes, in documents and in comments, and how agents read them.

For agents: this page as markdown · llms.txt

A screenshot with a box around the problem says more than a paragraph describing it. planpage lets you mark up any image in a document or a comment, and keeps the marks as data rather than pixels: each mark has a number and a note, people see them drawn over the image, and agents read them as text.

Marking up an image

In a document you can edit, hover over or select an image and choose Annotate (or Edit marks when it already has some).

The editor has these tools, each with a key:

Tool Key
Select and move V Move, resize or delete marks. Arrow keys nudge.
Box B
Ellipse O
Arrow A
Line L
Draw D Freehand, with a pen, finger or mouse.
Numbered pin P A numbered dot to point at something small.
Text T
Highlight H
Redact R Blacks out the area and removes the pixels underneath.
Crop C

There are seven colours that read in both light and dark themes, and three stroke widths. Cmd/Ctrl-Z undoes, Delete removes the selected mark, + and − zoom and 0 fits the image.

Every mark gets a number. Write what's wrong in its note, in the list beside the image (below it on a phone). Clicking a note selects its mark, and the other way round. The notes list is also the text alternative for people using a screen reader.

Redact and Crop change the image itself: saving uploads a new copy without the hidden or cropped pixels, so nothing you blacked out can be recovered from the saved image. Other marks are drawn on top and can be changed later.

In documents

An annotated image shows its marks drawn over it, numbered, with the notes listed underneath. Hover or tap a note to highlight its mark, and click the image to open it full size and zoom. Share pages show figures the same way.

In the document's markdown an annotated image is a :::figure block, so agents can write one too:

:::figure{src="https://share.planpa.ge/i/4kQ…Zt.png" alt="Checkout page"}
1. box 312,148 220x40 red: The total is missing VAT
2. arrow 120,500 -> 300,420 red: This button does nothing
:::

Positions are in the image's own pixels. See Writing documents for the rest of the markdown planpage understands.

In comments

The comment box takes screenshots too: paste, drop, or pick files, up to six per comment. Each can be marked up before you send it. They show as thumbnails that open full size with their marks.

While reviewing, you can also click a spot on an image in the document to start a thread pinned there, like a comment in a design tool. The pin shows on the image, numbered after the image's own marks, and goes away when the thread is resolved.

Who can see screenshots

Screenshots in comments are private to the workspace: only people who can open the workspace see them, and a share link only shows them to people viewing that document. Images in the document body are public links by default, so they work on GitHub and in other places markdown goes. You can make any image private, or public again, in Images. See Images.

What agents see

Agents read the marks as numbered lines of text: the kind of mark, where it is, its colour and its note, plus the details of any page element it points at (see Planpage Capture).

  • read_document and get_feedback include each figure's and each comment screenshot's marks as text.
  • view_image shows an agent the picture itself, with the marks drawn on. It can zoom to one mark (mark: 2) or crop a region, and works on private images too.
  • read_document and read_document_blocks take include_images to return the document's pictures along with its text.
  • Agents can reply with their own marked-up screenshot: upload_image takes annotations, and comment and reply_comment take images.