A guide is a walkthrough of a flow: a screenshot per step with the control you used ringed and numbered, and a sentence under each. You click through the task once and Lens assembles the document, rather than asking you to screenshot each step and paste them together afterwards. A finished guide can also be played back against the live page, with each step's control highlighted on it — see Guide Mode below.
No AI is involved in building a guide. Step sentences come from the accessible name of each control — the name a screen reader would announce. A connected model can rewrite those sentences afterwards; it never writes them in the first place.
1. Two ways to capture one
Record steps (⌘⇧E, Alt+Shift+E) is the light one: no region to drag, no video, and no time limit — nothing accumulates between clicks, so a walkthrough can take as long as the work does.
- Press Record steps in the popup or use the shortcut. A small widget appears in the corner of the page.
- Click through your flow as you normally would every click on a real control becomes a step, and a page load becomes a step of its own so the guide does not read as though everything happened on one screen.
- Type into fields as you normally would a field is captured once you stop typing, not when you click into it, so the picture shows a filled box rather than an empty one. The step quotes what you entered — Type "ACME-1024" into "Order number".
- Choose from dropdowns as you normally would the step is the option that came out, not the click that opened it — Select "Germany" from "Country".
- Scroll as you normally would scrolling far enough to reach something becomes a step, named for the heading you land on. A nudge to bring something into view does not.
- Press Record clip for anything a still cannot carry a drag, a hover menu, an animation. Drag a region, do the thing, press Stop clip, and it is dropped in as one animated step in the place you recorded it.
- Press Finish the review panel opens. There is no file to name, because the guide is the whole result.
A flow that opens a new tab — a payment provider, a consent screen, a document — carries on being recorded. Any tab the flow itself opens joins the walkthrough; a tab you open for something else does not. Closing the tab you started in does not end the walkthrough if the flow has moved on, and Finish is available in whichever tab you are standing in.
Record GIF (⌘⇧R) produces a guide as well as the recording, as long as Build a guide from each recording is on — it is by default. The review panel appears under the file name on the save screen.
Only Record steps follows the flow into a new tab. A GIF recording is a capture stream bound to one tab, so it stays on the tab it started in.
The region you drag limits the recording, not the steps. Each step screenshot is a fresh capture of the whole tab, with the control you used ringed on it — so steps stay readable even when the recorded region was small.
A step is the whole screen on purpose. A picture cropped tight around one button leaves out the part of the page a reader needs in order to know where they are, and a crop cannot be undone once it is saved. Lens works out where a tighter crop would go and offers it instead: open a step's crop tool in the editor and that box is already drawn, ready to accept or drag.
2. What does not become a step
- Clicks on Lens's own controls. Pressing Finish does not appear in the guide it finishes.
- Clicks on nothing — empty space, a page background.
- A repeated click on the same control within a second, which is counted once.
- A drag or a text selection, which is not a click at all.
- Clicking into a field and leaving it empty — the step arrives when you type something, not before.
- Pausing while you fill a field in. The step is written once the typing settles, and typing on into the same field extends that step rather than adding another; the picture is of the field as you leave it.
- The page load a click causes — said as part of that click (Follow "Support" — opens docs.vectored.dev/support.html) rather than as a step of its own with no picture. A redirect chain names where you end up; a page you open yourself is still a step.
- Clicking a dropdown open. The step is the option you choose from it. On most platforms the open list is drawn by the operating system and would not appear in a screenshot of the page anyway.
- A short scroll, or the jump a page makes in response to a click that was already recorded.
3. Reviewing before anything is written
Nothing reaches your folder until you approve it. The review panel lists every step with its screenshot, and you can:
- Edit the guide title, and the text of any step.
- Untick steps you do not want. They are dropped, and the rest renumber.
- Untick the guide entirely and keep just the recording.
- Rewrite with AI — only if you have a model connected. It refuses any answer that changes the number of steps, so it can improve the words but cannot invent or lose a step.
4. Where guides live afterwards
Dashboard > Guides. One card per guide, newest first, each showing the site's own logo — or its favicon where there is no logo, or a coloured initial where there is neither — with the title, the site, the step count, the project and the day it was captured.
| Action | What it does |
|---|---|
| Play | Runs the guide against the live page. See Guide Mode below |
| Open editor | Opens the guide as a document in its own tab |
| Export | Self-contained HTML, Markdown, or the clipboard |
| Delete | Removes the guide's folder on disk and the entry pointing at it. Asks first |
Above the cards sit three actions that apply to the whole set: Find guides on disk, Import guide and Export all guides. The first two are covered under Importing a guide below, the third under Exporting.
Guides recorded while no folder was linked are held in the browser and listed below the others as pending. They are not lost — link a folder, make that project active, and write them from there.
5. Guide Mode: playing a guide back
An exported guide is something you read next to the work. Guide Mode puts it on the work: a small panel floats over the real page with the current step and its screenshot, and a ring is drawn around the control that step is about, on the page itself.
Start it from Dashboard > Guides > Play, or from Guide Mode in the editor's toolbar.
| Control | What it does |
|---|---|
| Drag the header | Moves the panel. It remembers where you left it |
| Drag the bottom corner | Resizes it, both directions. The step text scrolls inside |
| Minimise | Collapses to a pill in the same place, so the walkthrough does not jump to another corner |
| The step number | Opens the list of every step, to jump straight to one |
| Auto-advance | On by default. Moves to the next step when you actually use the ringed control |
| Expand the picture | Opens the step's screenshot full size |
The walkthrough follows you across pages: navigating mid-guide takes the panel with it and carries on at the right step. When a click takes you to a new page, the page-load step you have just performed is skipped, so you land on the step that is actually about the page in front of you.
Where the recording caught what was typed — an order number, a search term, an option chosen from a dropdown — the panel carries a Copy button beside the instruction, so the value goes into the field without being read off a screenshot and retyped. Anything that looked like a credential was never written down, so those steps have nothing to copy.
6. Dropdowns wait for the choice
Opening a dropdown is not the same as choosing from it, so a step about one does not move on when you click it. What happens next depends on where the list is drawn.
- A list drawn in the page — a listbox, a menu, or a dropdown built out of divs — has the option itself ringed as soon as it appears, with the tag reading Pick "Overnight courier". Click that option and the step is done.
- A list drawn by the operating system, which is what a plain <select> gets on macOS, is not part of the page and has nothing in it to ring. The tag names the option to choose instead.
Choose something other than what the guide recorded and the step stays where it is, saying Choose "Asia Pacific" — better than carrying you forward from a choice you did not make.
7. When the control cannot be found
Beside the step number the panel says which it is — Ringed on the page, or Not on this page. A step with no control to point at, such as a page load or a scroll, says nothing there and shows no ring; press Next when you have done it.
Lens looks for the control by the selector recorded at the time, then its id, then a test id, label or field name, then its position in the page, and finally by the words on it. A guide recorded before Guide Mode existed, or one recorded in Plain mode, still names the control each step is about — and that name alone is often enough to find it.
It also keeps looking. A page that fetches its content draws its controls after the page has loaded, and a control behind a menu does not exist until you open that menu; the ring goes on the moment the control appears, however long that takes.
Guide Mode needs an ordinary website tab. Started from the dashboard or the editor — both extension pages, which Chrome does not allow any script into — it opens the page the guide starts on in a new tab.
8. What a guide says about itself
Above the first step sits a table: written by, email, status (Draft, In review, Published), date, steps, time needed and comments. Every field is editable in the editor, and all of it is printed into guide.html and guide.md above step 1 — they are the questions a reader asks before starting, not after finishing.
The time needed is worked out from the steps themselves: a click reads quicker than a field to fill in, a clip counts for as long as it runs, and the words in each step count towards the reading. Type over it and your figure stands; clear it and the calculation comes back.
The name and address are filled in for you — from Settings, or from the address this Chrome profile is signed in with when Settings is blank. A guide someone else wrote keeps their name when you open it, and nothing is sent anywhere: it goes into that guide's own file in your folder. See Privacy.
9. The guide editor
The editor opens in its own tab and reads as a document: the sheet is the width of the exported page, and the steps run down it in order.
Step text is Markdown, and the toolbar offers exactly what Markdown can carry — bold, italic, strikethrough, code, highlight, links with an optional tooltip, pictures, bullet and numbered lists, task lists, nesting a list item deeper or bringing it back out, a line break inside a paragraph, tables, code blocks, rules, callouts and headings. Nothing else is offered on purpose: a font size or a colour would be something one of the two exports could not represent, and the same text is written to guide.md and rendered into guide.html.
Typed by hand, the whole of the basic syntax works: headings, bold, italic and both at once, blockquotes, ordered and unordered lists (-, * and +) nested by indentation, code spans — including the doubled-backtick form that holds a backtick — fenced code blocks, horizontal rules, links with titles, autolinked addresses such as <https://example.com> and bare email addresses, pictures, two-space hard line breaks, and backslash escapes. On top of that: strikethrough, ==highlight==, tables, task lists, GitHub-style callouts and :emoji: shortcodes.
Printed as written rather than rendered: setext headings, four-space indented code blocks, nested blockquotes, reference-style links, and raw HTML — the last of those deliberately.
Enter carries on what you are in the middle of: another bullet, another numbered item, another task with its own box, and any inline formatting you had switched on. An empty list item leaves the list, and Enter after a heading drops back to ordinary text.
Insert a picture opens the file picker and copies the file into the guide's own folder when you save, writing it into the text as !alt. Insert a table opens a grid — drag across it to choose the size — and while the caret is inside a table, a small bar above it adds or removes rows and columns.
| Key | What it does |
|---|---|
| ⌘B / ⌘I | Bold, italic |
| ⌘K | Link |
| ⌘S | Save |
| ⌘⇧M | Switch between formatted editing and the raw Markdown |
| ⌘⇧O | Show or hide the outline down the left |
| ⌘click | Open a link — a plain click inside editable text places the caret instead, as it does everywhere |
The outline down the left jumps between steps. The button in its header collapses it, and a tab at the screen edge — or ⌘⇧O — brings it back. On a window narrower than about 1000px there is no room for it and it is not shown.
Markdown in the ribbon, or ⌘⇧M, replaces the sheet with the whole guide as one Markdown document — the same text guide.md is exported as, title and numbered steps and picture links and all. Retitle it, rewrite a step, reorder or delete items, or type a new numbered step at the end; the document is read back into the guide as you type.
The outline still works here: clicking a step scrolls the document to that step's numbered line and puts the caret on it.
Lines are numbered down the left, and a wrapped line stays one line however many rows it takes — each number is as tall as the line beside it. The ? next to the toggle, which only exists in this view, lists every mark the editor understands and what it produces; clicking a row drops it in at the caret.
What the text does not carry is kept from the steps that were there: which control each step points at, what kind of step it is, the file behind each picture. Items are matched to their steps by the picture they name, so a step that moves takes its screenshot and its recorded control with it, and an item you type in becomes a plain step with no picture. While the mode is on the formatting controls are blurred and made inert rather than hidden — they have nothing to act on — and the title in the header is read-only, because the document's first line is the title. The mode is remembered between sessions.
10. Working on a step
Hover a step. On the step itself:
| Control | What it does |
|---|---|
| Move up / Move down | Reorder. Numbers are rewritten, but file names never change — anything already exported still points at the right picture |
| Add step above / below | An empty step to write by hand |
| Duplicate | A copy, for when two steps differ by a word |
| Split into individual clicks | Breaks an animated step back apart. Lossless — each click kept its own still |
| Copy step | Text and picture together, ready to paste |
| Delete | The step goes, and its picture is removed from the folder when you save |
The page a step happened on sits under it as a small pill, showing the host and the end of the path — docs.vectored.dev/lens, or docs/getting-started.html for a local file. A search address with forty parameters shortens to google.com/search?…, and the whole address is the tooltip. Clicking the pill changes the address, which is what you want when a guide was recorded against localhost; the arrow beside it opens the page in a new tab.
On the screenshot itself you get the same image tools as a still capture — crop, annotate, blur, colour and rotation — plus Replace image, which swaps in a different file while keeping its name. The crop tool opens with the crop the recording suggested already drawn, to accept or drag.
Nothing is written until you press Save. Closing with unsaved changes asks first, and undo covers everything, including a rewrite the assistant applied.
11. Exporting
| Format | What you get |
|---|---|
| Share bundle (.zip) | One guide as one file, for sending to somebody. It downloads rather than being written into the project folder, because it exists to be sent |
| Print / Save as PDF | The guide alone — no toolbars, no side panels, no per-step buttons — as one continuous strip sized to the document rather than sliced into A4 pages, so no screenshot is cut in half |
| Self-contained HTML | guide.html with every picture inlined and no scripts. One file you can email. A recorded value prints on its own line, selectable in one click |
| Markdown | guide.md beside its screenshots, relative paths, ready for a repo or a docs site |
| Copy to clipboard | Rich text for pasting into Confluence, Notion or a document |
From the editor, Markdown downloads as a .zip holding guide.md and every screenshot it points at, in one folder. On its own the Markdown is a document whose picture links lead nowhere; the archive keeps the two together. A guide with no screenshots downloads as a plain .md.
Export all guides, above the cards on the Guides tab, writes Lens_Guides_<date>.zip: one folder per guide, each holding guide.html, guide.md, the screenshots, and the guide.json they were built from — so the archive can be read back in, not only read. A guide that cannot be read, usually a folder needing reconnecting, is left out and counted rather than failing the whole archive.
A guide longer than a single PDF page allows breaks between steps, never through a picture. Animated steps print their poster frame. When pasting into a document, check the pictures survived — editors disagree about pasted images and some drop them.
12. Sending a guide to a colleague
Share bundle is the one to send. It holds the guide itself — the steps and the control each one points at — its screenshots, and readable HTML and Markdown copies for anyone who only wants to read it. The other end imports it from the same tab and gets a guide with a Play button, not a document about one.
Before this, sharing one guide meant sending the whole archive of every guide you had: Export all guides was the only route that produced something importable.
A shared guide plays with rings only against the same screens. Guide Mode finds each step's control by a selector recorded against the page you captured on, so a colleague on the same app and version gets the rings in the right places, and one on a different build may not. The pictures and the words are unaffected either way. A walkthrough recorded with Interactive walkthrough off has no selectors at all: it imports and reads perfectly, and it does not play.
13. Importing a guide
A guide appears in the list because project_metadata.json names it. Copying a guide folder into a project achieves nothing on its own, and a metadata file that is lost or overwritten takes every guide in that project out of the list with all the files still sitting on disk. These two actions cover both.
| Action | What it does |
|---|---|
| Import guide > From a file | A .zip written by either export, or a bare guide.json. One archive may hold many guides; all of them come in |
| Import guide > From a link | The same, fetched from an address you paste |
| Find guides on disk | Lists guide folders that are in a linked project folder but missing from its timeline |
An import is always a copy: it is given a new id and its own folder, so importing the same bundle twice leaves two guides rather than quietly overwriting the first. Nothing already on disk is replaced. A guide.json that arrives without its screenshots imports anyway and says so — those steps keep their words and have no picture.
Imports land in the active project, which must have a folder linked. What kind of file it is is read from its first bytes rather than its name, so a bundle fetched from a link works whatever the address ends in.
Importing from a link is the only time Lens reaches the network on its own. It downloads the address you paste and nothing else: no service in between, nothing of yours sent with the request, http and https only, and 50 MB or 30 seconds at the outside. See Privacy.
Find guides on disk walks every linked project, keeps each guide's existing id, and adds only what is missing. Run it after copying a folder in, or to repair a metadata file. Running it twice adds nothing the second time.
14. The assistant
The editor has a chat panel, and it stays shut until you have configured a model and a test has actually reached it. See AI features for setting one up.
- Step and Guide attach material to this message. A question with nothing attached sends only the question.
- Media additionally sends the screenshots of what you attached. Off by default — the files are not even read unless it is on.
- The model switcher picks which of your configured models answers, per message.
- Auto applies a proposed rewrite as it arrives rather than waiting for a click. Off by default, and undo reverses it.
If a request fails, the panel says so and stops. It has no offline imitation of a model — inventing documentation for software it cannot see is the one thing a documentation tool must never do.