The handover folder

What you get when someone exports a task from Handoff, and how to use it. One folder per task and date, for example monthly-supplier-invoices-2026-11-03/:

guide.html        open in a browser; screenshots embedded, self-contained
guide.pdf         the same guide as an A4 PDF, to print or send; screenshots embedded
guide.docx        the same guide as a Word document, which Confluence, SharePoint and Google
                  Docs import with its headings and screenshots
guide-for-notion.zip  guide.md with its images, as Notion's Markdown import (and other wikis) take it
guide.md          the same guide as Markdown
playbook.json     the same steps as data, for an AI agent
images/
  step-01.webp    one screenshot per step, clicks marked with red dots
  step-02.webp
  ...

For a person

Open guide.html. It reads top to bottom:

1. Title and duration: "Usually takes 14 min (9 to 22 min), 5 runs" is the median and the range over every time the task was recorded, after pauses and breaks were removed. "This run took 12 min" appears instead when there is only the one recording.
2. Summary and "Before you start": a short introduction and the accounts, systems or files the task needs, written by the local model from the steps. Treat the prerequisites as hints rather than a complete list.
3. Steps: each has a title, a sentence or two, the screenshot with the clicks marked, the app it happened in, how long it took, any scrolling needed to reach what was clicked ("Scroll down to “Confirm payment”"), and any keyboard shortcuts used. Why: lines are notes the recorder typed or spoke: the reasons, rules and exceptions behind the step, so they carry the most weight. "Typed:" lines appear only when the recorder chose to keep typed text, with obvious secrets replaced by [redacted]. Steps the recorder or Handoff judged to be detours (the news, the weather) are not in the guide.
4. Apps used: every application that appeared, so you know what access to ask for.

With a video overview, overview.mp4 (H.264, 1280×720, about a minute) sits beside the guide and guide.html shows it under the title. overview.json holds its captions, one per step, the step titles they were written for and the length it was made at (short, standard or full); it is read again when the video is made again, and ignored when the guide’s steps have changed.

Step titles were written by a local AI model from what was on screen, then checked and often edited by the recorder. Where a step says "Work in Safari: Supplier portal" the model was not available and the recorder left the plain name; the screenshot still shows what happened.

A guide exported in a brand (Settings → Branding) also has brand.json: the brand’s colours, fonts, organisation and footer, and images/logo.png. The video overview and the Follow window read it, so a guide made later from the folder, or followed on another computer, keeps the look it was exported in. Imported fonts are named by their path on the computer that exported it and are not copied; elsewhere the video uses Handoff’s font instead.

For an agent

playbook.json follows playbook-schema.json in this folder of the Handoff repository. The important fields:

Offsets are milliseconds from the start of the recording. Image coordinates refer to the images/step-NN.webp file named in image, which is the screen at logical (not Retina) resolution. screen coordinates are only meaningful on the same monitor layout the recording was made on. To find a control, prefer target (it names the control whatever the screen size), then the image position together with the screenshot and screen_text.

user_edited: true marks steps whose wording a person corrected; weigh those over model-written ones when they disagree with screen_text.

A handover pack

Handover pack… in the Library writes handover-<date>/:

index.html        the overview, with a link to each task's guide
handover.md       the same overview as Markdown
handover.pdf      the overview, then every task's guide, each from a new page
handover.docx     the same as a Word document
pack.json         title, prepared, tasks[] (name, folder, recordings, usually, cadence,
                  last_done, apps, prerequisites) and not_included[]
<task folder>/    each task's export: its procedure, or with one recording its latest guide

cadence is worked out from when the task’s recordings started (daily, weekly, every two weeks, monthly, quarterly, twice a year, yearly) and left out with fewer than three recordings or when they all fall within a week.

A procedure

Export procedure… on a task’s Procedure screen writes <task>-procedure-<date>/ with the same files. guide.md, guide.html and guide.pdf list the steps of all the task’s recordings: steps marked (sometimes) with "In 1 of 3 runs. When: …" (or "When is not known yet"), and "One of these" for places where recordings went different ways. playbook.json follows procedure-schema.json: procedure.steps[] with kind (core, conditional or alternative), group (alternatives share it), occurs_in of of_runs, condition (only from the person’s notes or answers), notes, median_ms and image.

What is deliberately not there

• Anything from applications the recorder excluded: those stretches were never captured.
• Screenshots the recorder deleted, and the hidden regions of screenshots they blurred.
• Typed text, unless the recorder turned it on. Even then, card numbers, 13-digit ID numbers, emails, phone numbers and values after password-style prompts read [redacted].
• Personal details on screenshots: areas where text recognition read an email address, card number, ID or phone number, password or code are pixelated in images/, unless the recorder chose to show them in Review.
• Audio. Spoken notes are turned into text on the recorder’s computer and only the text is kept.
• Steps left out as detours.