Glossary

Studio, the CLI and these docs use the same words with the same meaning.

Term	Meaning
Site	A web portal: one or more origins, such as https://quotes.toscrape.com.
Task	What an expert does on a site, and the unit a spider automates. For example, “search quotes by author”.
Expert	The person who knows the task and records it. Experts use Chrome, never Studio or the CLI.
Session	One recording of a task by one expert. A directory in the archive.
Action	One thing the expert did in a session: a click, a typed value, a choice, a submit.
Archive	The directory where sessions are written: archive/<host>/. See The archive.
Relay	The local server the Chrome extension sends recordings to, when experts record in their own browser.
Sandbox	The site served offline from the recorded sessions. Spiders are tested here before they touch the real site.
Level	How far the sandbox may depart from the recording. Level 1 answers exactly as recorded. Level 2 tolerates values that change on every visit, such as tokens and nonces. Level 3 answers inputs no session recorded and marks those answers as generalised.
Spider	The program that performs a task. It is deterministic and versioned (v1, v2…).
IR	The spider’s source: a JSON document (spider.json) of states, steps, inputs and outputs. The Playwright script is compiled from it.
Input	A value the spider types or picks, such as a search query. Each session recorded an example of it.
Secret	An input whose value is never stored, such as a password. You pass it at run time.
Output	A value the spider reads from the site and returns, such as a list of results.
Test	What a session expects: the same requests in the same order and the same final page. Every spider must pass the tests of all its sessions.
Build	The step that turns a task’s sessions into a spider and proves it against their tests.
Runtime	Graphdom’s own engine for running a spider. The other target is a compiled Playwright script.
Effect	Every step is either a read (looks, navigates) or a submit (sends data the site keeps). The runtime asks before a submit.
Drift	The real site no longer matches what was recorded. The spider stops and reports it instead of guessing. In Studio, a task’s Drift lists its runs that drifted, each with the page before and after, and its repair (graphdom build --repair).