Check that everything needed for a run is present and working.

Reports the session type, input-device permissions, which capture backends work, detected screen geometry, GPU memory versus the selected model profile, and whether both model backends respond. When something is missing it returns the exact command to fix it. Call this before the first run on a machine.

Return everything needed to author and iterate on a run.

Call this before your first Playbook. Sections:

loop the learning loop -- how to go from a failed run to a working one, and what each failure mode actually means. Read this second. bursts the burst cookbook: how to chain inputs well, timing rules, ready-made patterns for desktop and for games, and the antipatterns that waste cycles. Read this if bursts are coming out one action at a time. burst the raw burst syntax playbook the state-machine JSON schema guards expression functions for transitions and reflexes example a complete working Playbook

Take a screenshot and return it to you directly.

Use this to see the screen yourself -- before writing a Playbook, to pick coordinates for probes and click regions, or to work out why a run went wrong. This does not involve the local vision model.

region is [x, y, width, height] in desktop pixels; omit for the whole desktop.

Run one vision pass and return grounded elements in screen coordinates.

watch is the closed vocabulary the vision model may use -- it can only report labels from this list, so name the things your Playbook's guards will test for.

Use this to check that the vision model can actually find what a state depends on before committing to it in a Playbook. If an element does not come back here, a sees(...) guard on it will never fire.

Execute one input burst yourself, bypassing the local models entirely.

For moments that need your judgement rather than the actuator's: opening the right application, clicking a specific confirmed target, typing something exact. Also the fastest way to sanity-check that input injection works at all.

Syntax: m:640,360;c:l;w:120;t:"hello";k:enter. Call voltage_reference for the full list. The safety policy still applies. Defaults to dry_run, so pass dry_run=false to actually inject.

Verify that input injection actually reaches the compositor.

Creates the virtual devices, moves the pointer to three known points, and captures after each to confirm the cursor moved. Reports whether absolute positioning works or whether the relative fallback is needed -- which cannot be known without trying, since it depends on how libinput classified the virtual device.

Run this once per machine before trusting a real (non-dry-run) Playbook.

Fully check a Playbook without running it.

Validates the schema, compiles every guard expression, parses every burst, checks that transition targets and probe references exist, and reports unreachable states and dead transitions. Errors come back as a complete list, not one at a time.

Always call this before voltage_run. Warnings are worth reading: "tests for X but X is not in watch" means a transition that can never fire.

Start a Playbook. Returns immediately with a run_id; poll voltage_status.

dry_run overrides the Playbook's policy. Leave it unset for the Playbook's own setting, which defaults to true. A dry run does everything except inject input, so it is the correct way to check that your states, guards and transitions behave before letting it touch the machine.

target_period_s is the loop period. 0.5 is a good default; lower it for games, raise it for slow UI.

Stop a run with voltage_stop, adjust it live with voltage_steer. The run also stops on its own budget, on any physical keyboard or mouse input from the user, and on the panic file.

Poll a run: current state, variables, last burst, what the vision model sees.

Includes recent cycles, governor refusals, and per-stage timings so you can tell whether a slow loop is capture, vision, decision, or execution.

Correct a live run without restarting it.

hint is injected into the actuator's prompt as a supervisor note and persists until changed -- use it when the actuator is doing something legal but wrong. force_state jumps the machine on the next cycle. variables updates run variables. dry_run can be flipped either way mid-run.

Stop a run and release every held key and button.

Safe to call at any time, including while a burst is mid-flight -- the burst is interrupted and anything held is released.

Pause or resume a run. Held input is not released, so a paused run can continue.

Read a run's cycle-by-cycle record: what was seen, decided, refused, executed.

only_refused=true filters to cycles the governor blocked, which is the fastest way to see where a Playbook's policy and the actuator's intentions disagree.

Explain why a run behaved as it did, and what to change.

Call this instead of reading the journal by hand. It computes what the journal implies but does not state -- watch labels the vision model never once reported, guards that never evaluated true, whether bursts actually moved the screen, whether the actuator is chaining or emitting one action at a time -- and returns each with the specific edit that fixes it, ordered blocker-first.

The distinction it exists for: a burst that never ran and a burst that ran and did nothing look identical in a summary and have unrelated causes. The first is policy or grammar; the second is window focus, pointer mode, or an application that ignores synthetic input.

Apply the highest-severity finding, re-run, diagnose again. Changing several things at once makes the next diagnosis uninterpretable.

Recall what previous runs learned about driving something.

Call this before writing a Playbook for a target you have driven before. Lessons persist across sessions and are keyed by target ("minecraft", "roblox", "dolphin"), so a new Playbook can start from what the last one discovered -- which labels the vision model actually recognises, where the HUD probes are, what timing the game needs -- rather than rediscovering it.

Omit target to see everything recorded so far.

Record something worth carrying to the next run against this target.

Write these as concrete, reusable facts, not narration:

good "the health bar is at x=120..300, y=1010; region_mean on red channel works" good "vision reports 'hotbar' reliably but never 'crosshair' -- do not watch it" good "block placement needs w:100 after the right click or it does not register" bad "the run failed" bad "tried again and it worked better"

kind groups them: label (what the vision model does and does not recognise), timing (waits that a specific application needs), policy (what the governor blocked and whether that was right), burst (a sequence that works), observation (anything else).