adom-bridge --target <desktop> hd_api '{"method":"POST","path":"/annotate","body":{"tool":"pen","mode":"auto"}}'

---
name: hydrogen-annotate
version: 1.1.0
description: >-
  Hydrogen's Annotate tool: the Title Bar pencil or Win+Alt+A lets the user draw
  on the whole screen (circle, arrow, box, note, snip) and puts a PNG on the
  clipboard for the AI thread. Use when asked to annotate, circle it, mark up
  the screen, snip a region, or about POST /annotate.
---

# Annotate: draw on the screen, paste it into your AI thread

## On the whole desktop (Hydrogen 1.0.612+)

Annotate draws **on top of any app, on the monitor the pointer is on**, and never gets in the way:

- Start it from anywhere with **Win+Alt+A**, or click the pencil. Settings > Hydrogen > Annotate
  turns the shortcut off, and says so when another program already holds it. (Win+Shift+A and
  Win+Shift+M belong to Windows; Alt+Shift+A is VS Code's Toggle Block Comment.)
- **Hold Ctrl and drag to draw.** Everything else, every click, the wheel, hovering and every key
  except Enter and Esc, still goes to your apps. So you can right-click a taskbar icon, and with
  its jump list open, Ctrl+drag a circle around the item: the jump list stays open.
- **Enter** copies, **Esc** cancels. Nothing is captured before Enter (in the default Multi);
  one-shot Auto captures when you let go of the mouse.
- The toolbar is its own small window, dragged by its grip, and it never takes the focus. It has
  Pen, Arrow, Box, Snip, six colours, Auto/Multi, Undo, Clear, Done, and **Drag draws**, which
  draws with a plain drag instead of Ctrl+drag (clicks then draw instead of reaching your apps).
- The capture is the area around the drawing with the drawing on it, on the clipboard as PNG (and
  as a bitmap), saved in `%APPDATA%\hydrogen-desktop\annotations`. A small card at the
  bottom-right shows it (Copy again, Show file); it never takes focus and leaves after 8 seconds.

The shortcut is per machine: `GET /annotate/hotkey` reads it, `POST /annotate/hotkey
{"enabled": false}` turns it off.

The pencil in Hydrogen's **Title Bar**, left of the bell and right of the CPU/RAM meter, is
**Annotate**. It puts a drawing canvas over the whole Hydrogen window (the editor, the wiki,
every panel; they are all under the same canvas), with the same toolbar pup uses. The human
draws, and the area around the drawing is captured and written to the clipboard as a PNG.
The point is the next step: paste it into an AI thread and say "this one".

## What the human sees

| Tool | What it does |
|---|---|
| Pen | Draw freehand. With Auto on, the capture fires the moment the mouse is released. |
| Arrow | Drag from tail to tip; the arrowhead lands where the mouse is released. |
| Box | Frame a region with a rectangle, corner to corner. |
| Text | Click where the note starts, type, press Enter. |
| Snip | Capture exactly a region, like Win+Shift+S: drag a marquee, it is copied on release, no strokes. |

Colours: red, blue, yellow on the bar, more one click deeper. Two capture modes:

- **Auto** (default): one shot. Draw one thing, lift the mouse, and it is captured, copied,
  and annotate mode closes. This is the "red circle" case.
- **Multi**: compose. Draw several shapes; nothing is captured until Done. The colour
  advances after each shape so every shape is distinct.

The capture is the composited window with the drawing on it, cropped tight around everything
drawn. A toast confirms it: "Captured 640×320, on your clipboard. Paste it into an AI thread."

Keys: **Enter** = Done (capture and close), **Esc** = leave without capturing, **Ctrl+Z** = undo
the last shape. Undo and Clear are on the bar too.

## What the AI does with it

**You do not need annotate to see the screen.** To look at Hydrogen yourself, take a
screenshot: `POST /screenshot` on the control API (the `hydrogen-self-screenshot` skill), or
`adom-bridge desktop_screenshot_window`. Annotate exists for the **human** to point at
something.

When the user pastes an annotated PNG into your thread, treat the drawing as the pointer: the
circled, boxed or arrowed thing is what they mean, and a text note is their comment. Read the
image before answering.

You can open the overlay for the human when that is the fastest way to get an answer ("circle
the part you mean"):

```bash
adom-bridge --target <desktop> hd_api '{"method":"POST","path":"/annotate","body":{"tool":"pen","mode":"auto"}}'
```

`tool` is pen | arrow | box | text | snip (default pen), `mode` is auto | multi, `scope` is
desktop (the default since 1.0.611: the whole monitor, any app) or window (inside Hydrogen only),
`close: true` dismisses the overlay. The response says whether the window took it
(`ok`). Then say what you want them to mark and wait; the result lands on **their**
clipboard, not in your context, so ask them to paste it. Do not open the overlay while they are
typing or during a demo recording without saying so first; it covers the whole window until Esc.

## Where it lives

- The pencil: `src/lib/components/editor/EditorNav.svelte` (button next to the meters).
- The overlay and toolbar: `src/lib/components/AnnotateOverlay.svelte`, driven by
  `src/lib/stores/annotate.ts` (`startAnnotate(tool, mode)`, `closeAnnotate()`).
- The route: `POST /annotate` in `src-tauri/crates/hydrogen-control/src/lib.rs`.
- The capture itself is `POST /screenshot` with `target=full`, cropped in the overlay.
- Desktop mode: `src-tauri/crates/hydrogen-app/src/desktop_annotate.rs` (the overlay and preview
  windows, the capture, the clipboard, the hotkeys), the `annotate-desktop` route with
  `src/lib/components/annotate/DesktopOverlay.svelte` and `DesktopPreview.svelte`, and the shared
  tools in `src/lib/annotate/draw.ts`.

Related: `hydrogen-self-screenshot` (the AI's own screenshots), `hydrogen-captions` (text
overlays the AI puts on screen for narration; not for marking things up), `hydrogen-pup`
(pup's annotate, the same toolbar in the browser window).