Mark up and annotate

A box around the detail can say more than a paragraph about where to look. Mark up a report, image, web page, or spreadsheet and hand your notes to an agent. The agent can also leave notes on the work for you to review in place. Both directions use markers and a shared card, so the discussion stays with the thing you are changing.

Mark up a surface

Open the document in a render pane, or the page in a browser preview. Select Mark up in the pane header, then choose the detail you want to discuss.

Type a note in Describe the change and press Enter to save it. You can add up to 12 regions to a batch. Move or resize a region, open its marker to change the note, or remove it. The floating toolbar can move out of your way. Its note count opens the list; Clear removes the batch's regions and Copy copies prompt text only, without images.

Markup is available on desktop and in the browser IDE. In hob roam, annotation batches are read-only; open the full workspace to edit them.

Send it to an agent

Choose a destination with the arrow beside Send to, then select Send to <agent>. You can use an existing agent in the document's environment or create a New Agent. A worktree is a separate environment, so its agent must share the document's environment to receive the batch.

This places an Annotations · file · N regions pill in the agent's composer. The message is not sent yet. Add any wider context, then send the message when you are ready. If you are still typing a region note, Send to saves that note before preparing the batch.

For images and PDFs, the agent receives one clean crop per region, your notes, the source file path, a snapshot fingerprint, and instructions for applying the edit. Web batches carry element context without crops. Spreadsheet batches carry worksheet ranges and cell context.

Keep a draft and return to sent notes

Each document pane keeps one unsent batch. Reopen Mark up to resume it, or select its composer pill to return to the document. While editing that draft, Update draft saves it back to the same conversation.

Sent batches stay in the conversation. Select their pill to open Annotation details, inspect the region previews, and read the notes. Sent notes are read-only. Apply again puts an editable copy on the document, with the destination locked to the original conversation.

If the document changed, hob shows a notice instead of treating the old selection as current. Review the affected regions against the current content before sending them again.

When the agent changes the file

For an annotated edit, the agent passes the batch's expected fingerprint to hob revision create. hob refuses to replace an original that changed while the agent worked. Sending markup alone creates no revision; see Keep a previous version for saved copies, Undo, and restoring older work.

Annotations from your agent

Ask an agent to annotate the part you want explained. Open its annotation link to reveal the first note. Next moves through the set; Done or Esc closes the card and leaves the markers. Hover over a marker to preview its note, or select it to keep the card open.

The markers belong to the pane and survive restarts. Depending on the surface and changes to its content, status labels include Current, Needs review, Relocated, and Missing. A missing target is not a new guessed location.

You can clear the set with Remove all; you cannot edit or move an individual agent note. Starting your own markup clears the agent markers on that pane. A new attention pointer or annotation set also replaces its previous markers.

Attention, annotations, or a walkthrough?

Agents offer annotations and walkthroughs when you ask for that guidance. See Working with your agent for attention and walkthroughs in the guestbook workflow.

hob revision create reports/counter-review.pdf reports/counter-review.updated.pdf \
  --expected-fingerprint '<fingerprint from the batch>'
hob revision list reports/counter-review.pdf

{"file":"app.js","location":"line:58","match":"<exact gutter line>","note":"This updates the counter."}
{"file":"mockup.png","location":"rect:12,20,65,15","note":"Keep the counter near the note field."}
{"file":"reports/counter-review.pdf","location":"page:1","match":"Before approving","note":"Try each behavior before committing."}
{"pane":"web_<id>","location":"node:n7","note":"Try typing here."}
{"pane":"render_<id>","location":"cell:'Review'!A1:C4","note":"These are the checks still to run."}

Next