Skip to main content
A Show Page isn’t a read-only handout. Annotation turns it into a two-way surface: you point at exactly what you mean — a chart, a paragraph, an empty gap that looks wrong — say a word about it, and your agent picks it up like any other message. When the answer is easier to show than to describe, it comes back on the page, pinned next to the thing you pointed at. It’s the same instinct as Show Pages themselves, run in reverse: instead of the agent handing you a page, you hand the agent a spot on it.
Annotation and on-page replies arrive with a recent Avibe release. If your chat has no annotation control on a Show Page, or vibe show doesn’t list the annotate / reply / marks commands yet, run vibe upgrade and reload.

​
Turn on annotation

When you open a Show Page inside the Workbench chat, an Annotate control appears in the page header, next to the button that takes you back to the conversation. It’s off by default — the page behaves like a normal page until you turn it on.
  • On desktop, the control starts as a single icon. Activate it and it expands into a small segmented group: the Annotate toggle plus the two modes, Smart and Screenshot.
  • On a phone, it’s one button that opens a compact popup — pick Smart or Screenshot, or Turn off annotation. Tapping the button turns annotation on in whichever mode you used last.
Annotation opens in Smart mode the first time, and after that it remembers the mode you used. Press Esc any time to leave. While annotation is off, clicks, links, and controls on the page work exactly as before.

​
Smart mode — point and say

Smart mode is for pointing at what’s already on the page.
  1. Click an element, select some text, or drag a box around a region. A comment card opens, anchored to what you picked.
  2. Give it an intent so the agent knows what kind of response you want:
    • Comment — a note or observation.
    • Change — you want this reworked.
    • Question — you’re asking about it; the agent is nudged to answer right here on the page.
    • Approve — a one-tap sign-off. No typing needed.
  3. Send. Your annotation lands in the chat as a message and your agent responds — reworking the page, replying on it, or answering in chat, whichever fits.
Because Approve needs no text, signing off on something is a single tap.

​
Screenshot mode — mark up a capture

Sometimes the point isn’t one element — it’s how a few things look together. Screenshot mode captures a region and lets you mark it up.
  1. Drag a box around the area you care about. Avibe captures it locally, in your browser — there’s no screen-sharing prompt, and it works on iPhone-class devices where screen capture normally isn’t available.
  2. Drop numbered comments onto the capture — “1” here, “2” there — as many as you need.
  3. Send them together as one batch, so the agent gets the whole picture and your notes in order.
On touch, page scrolling locks while you’re marking a region so your drag stays precise. Press Esc, or toggle annotation off, to scroll normally again.

​
On a standalone page

Open a Show Page on its own — a direct /show/… tab, or a page you’ve pinned to the Dock — and there’s no chat header to hang the control on. Instead a small floating button sits in the bottom-right corner. It opens the same modes and produces the same result: your annotation still flows back to the session’s conversation, and the agent still answers.

​
What happens after you send

Your annotation shows up in the chat as a normal message (tagged so you can tell it came from the page) and kicks off a reply, just like anything else you send. The agent can also answer on the page. When it does, a violet dot appears next to the element you pointed at — a short reply, anchored to your question. Open it to read the answer; once you’ve read it, the mark retires: it fades to a quiet gray and won’t come back on the next load. Think of these as conversation bubbles, not sticky notes that pile up forever. A few things keep the page calm:
  • At most five unread marks show inline at once. Any beyond that collect into a badge in the bottom-right corner whose list holds every active mark.
  • If the agent reworked the page and a mark’s original spot is gone, that mark moves into the badge list labeled “original location updated” — its text is still there to read, and it’s never pinned to the wrong place.

​
Public pages: who can annotate

When you publish a Show Page as a public /p/… link, the read and write sides are treated differently:
  • Anyone with the link can view the page and read the marks on it.
  • Annotating requires being signed in to the workbench in the same browser. An anonymous visitor sees the page read-only, with no annotation control. Sign in and the control appears.
Every annotation records who made it — your workbench identity — so you and the agent can tell contributions apart. Nothing you annotate is anonymous, and public links never let a stranger write to your page.

​
Answering on the page: reverse marks

The second half of the loop belongs to the agent. You don’t run these commands yourself — you ask for the behavior (“answer my page questions on the page”, “flag anything you changed”) and the agent uses the vibe show commands below. They’re worth knowing when you’re writing agent instructions, and they’re the reference an agent follows. The agent barely has to construct anything: each annotation that reaches it carries its own event id, and many arrive with a ready-to-run vibe show reply … line. Whether to answer on the page or just edit the page content is the agent’s call, per situation. An agent can also declare a note straight in the page it writes, with an agent-note attribute on any element it authors:
That kind of note lives and dies with the element — rewrite or remove the element and the note follows on the next render. (Named mark-* anchors say where something is; agent-note says what the agent wants to tell you about it.) The lifecycle, in one breath: marks are conversation bubbles. Unread ones show as a violet dot; reading one retires it for good. A reply stays paired to the annotation it answers. Agents are guided to leave only one or two marks per turn; at most five render inline and the rest fall into the badge; and a mark whose anchor no longer resolves degrades into the badge list rather than being guessed onto the wrong spot. The page carries the conversation; the chat keeps the transcript. Between the two, pointing at your agent’s work and getting an answer back is just… talking. See Show Pages for everything a page can be in the first place.