devharness 0.8.0

package/skills/devharness/references/sequences.md

@@ -0,0 +1,613 @@
+# Replay Sequences
+
+A sequence is an ordered list of tool calls you can re-run. It's how cdp-tools
+turns "I clicked around and hit the bug" into something repeatable - a
+regression test, a repro attached to an issue, or a multi-step automation.
+
+Everything below is the `replay` tool: `replay({ action: '...' })`.
+
+## Folders
+
+Sequences may live in subfolders of the sequences dir:
+
+```
+.cdp-tools/sequences/
+  _helpers/      preamble guards, forEach bodies - loaded, never run on their own
+  spine/
+  story/
+```
+
+Filenames are relative to that root (`spine/spine-01.json`), and `load` still
+accepts the bare basename, so moving a file into a folder does not break calls
+that name it.
+
+`replay({ action: 'runAll', folder: 'spine' })` loads the WHOLE tree, then runs
+only that folder. Loading everything matters: `conditional`'s `then` and
+`forEach`'s `do` resolve by sequence NAME, not by path, so a spine sequence can
+call a helper in `_helpers/` only if that helper was loaded too.
+
+**Tags are the other axis.** `replay({ action: 'declare', name: '...', tags:
+['ui'] })` labels a sequence; `replay({ action: 'runAll', tags: ['ui'] })` runs
+only those, and composes with `folder`. Several tags mean *any of*. Tags are
+lowercased and de-duplicated (a tag is matched, not displayed) and may not
+contain spaces.
+
+Every `runAll` reports the split whether or not you filtered - `3 passed (1
+contract, 1 ui, 1 untagged)`. That is the point: a suite reporting "36 passed"
+reads as interface coverage even when a third of it never issues an `input`
+step, and folders cannot carry the distinction because they already carry
+scenario shape.
+
+A folder whose name starts with `_` is skipped by a bare `runAll` - those
+sequences fail in isolation by design (unbound `{{var:}}`, an unmet
+precondition). Naming one explicitly runs it anyway.
+
+Failures are recorded and the suite continues unless `continueOnFailure: false`.
+A sequence that only PROMPTS (recorded variables, none supplied) or that PAUSES
+is reported as a failure, not a pass - it did not run.
+
+## Rules for building one
+
+These hold however you build a sequence - by hand, as a subagent, or from a
+slash command. They are here, once, rather than restated by each of those.
+
+- **Never hand-write sequence JSON.** Sequences come from recorded tool calls.
+  Hand-edited JSON skips the validation the tools apply and does not port.
+  The things that cannot be recorded have their own actions rather than being
+  an exception to this: `addConditional` for a guarded branch, `declare` for
+  the browsers and sockets a sequence needs.
+- **Do the work with the tools; don't describe it.** Every call you make is
+  recorded, and the sequence is assembled from that history afterwards.
+- **Pass `connectionReason` on every browser call** - including the connection
+  that is already active, and including tools where it is optional (`inspect`,
+  `execution`, `storage`, `network`, `breakpoint`, `request`). A call without it
+  records nothing about which browser it ran in, so on replay it lands wherever
+  the run-level connection points - silently, and the run still passes. This is
+  the most common way to produce a sequence that tests nothing.
+- **Check `listSaved` first.** Auth and setup flows often already exist; a
+  `conditional` step can reuse one instead of re-recording it.
+- **Keep the path minimal.** Skip exploratory calls (source searches, unrelated
+  navigation); include only what is needed to reproduce.
+- **Write a specific `expectedOutcome`** - file:line, variable names, expected
+  vs actual values. "It works" is not an expected outcome.
+
+## Getting a sequence
+
+**Record what a human does** - `recordInteraction`
+
+```
+replay({ action: 'recordInteraction', connectionReason: 'signup-flow' })
+```
+
+Opens the page with a recording overlay and captures real mouse, keyboard and
+navigation events. **This call blocks until the person finishes in the
+browser** - there is no separate stop action. It returns the created sequence.
+Pass `issueId` to name and link the recording to an issue (`bug-7-repro`).
+
+Because it waits on a human, don't call it unattended - the same rule as
+`issues({ action: 'resolve' })`.
+
+Tune how events become commands with `simplifyEvents` (default true),
+`includeHovers` (false), `preferCoordinates` (false - `x,y` clicks for
+canvas/3D) and `preferSelectors` (false - selector clicks even for canvas;
+wins if both preference flags are set). Add `outputFormat: 'events'` or
+`'commands'` to get the raw captured events / converted commands as JSON
+alongside the summary, or `'review'` for a readable walkthrough of the captured
+events (coordinates, element and selector per interaction, plus navigations,
+pastes and comments). All three are only available here - raw events are not
+stored with the sequence.
+
+**Build one from calls you already made** - `create`
+
+```
+replay({ action: 'create', name: 'login-check', indices: [3, 4, 5] })
+```
+
+Every tool response footer shows its history index (`**Repeat:**` hint).
+`replay({ action: 'history' })` lists them. This is usually faster than
+recording when you've just done the steps yourself.
+
+**Re-run calls you already made, without building a sequence** - `repeat`
+
+```
+replay({ action: 'repeat', indices: [12] })                // one call
+replay({ action: 'repeat', indices: [58, 59, 60, 61] })    // a whole stretch, in order
+```
+
+`indices` takes a list, so this replays a run of work in one call - and that is
+usually the point. Whenever you are about to redo something you already did
+(relaunch the browser, log in again, retype a form, get back to the screen
+where the bug shows), repeat those indices instead of re-issuing the calls by
+hand: it is faster, and retyped arguments drift from what actually ran.
+
+Every tool response carries its own index in the footer, so the numbers are
+already in front of you. `replay({ action: 'history' })` lists them when they
+have scrolled away. If the stretch turns out to be worth keeping, hand the same
+indices to `create`.
+
+## Managing them
+
+- `list` / `get` / `delete` - sequences in memory. `get` takes
+  `outputFormat: 'commands' | 'playwright' | 'puppeteer'` to return the raw
+  command JSON or generated test code instead of the detail view (`'events'`
+  and `'review'` are recordInteraction-only - a stored sequence has no raw
+  events, and `get` says so rather than ignoring them)
+- `load` / `listSaved` / `deleteSaved` - sequences on disk
+- `export` - write to a file as `sequence`, `playwright`, or `puppeteer`
+- `global: true` on `export` saves to `~/.cdp-tools/sequences/` instead of the
+  working directory
+
+`load` and `create` reject a sequence naming a tool that doesn't exist, listing
+the offending step, rather than failing halfway through a run after earlier
+steps already changed state.
+
+**Editing a sequence file mid-session just works.** The sequences directories
+are watched like a managed dev server's sources, and a run re-checks the file's
+timestamp anyway - so the version you just saved is the version that runs. No
+`load` needed to pick up an edit. A file caught mid-write leaves the loaded copy
+in place rather than replacing a good sequence with a half-saved one, and a
+sequence built from history has no file to reload from.
+
+## Running
+
+```
+replay({ action: 'run', sequenceId: 'seq-login', connectionReason: 'my-app' })
+```
+
+**`run` does not block** (changed in 0.7): it returns a run id immediately and
+executes in the background.
+
+```
+replay({ action: 'status', runId: 'run-3-...' })   // progress; full result once settled
+replay({ action: 'cancel', runId: 'run-3-...' })   // stop it
+```
+
+`cancel` reaches the step that is in flight (including inside nested
+`conditional` sequences), but what it can do there differs by tool - three
+levels, and the difference matters:
+
+- **Genuinely cancelled:** `wait` (all forms, mid-poll) and `request` with
+  `destination: 'node'` (the socket is closed - the server sees it aborted).
+- **Stops waiting, work continues:** `navigate` (deliberately no
+  `Page.stopLoading` - a half-loaded page is worse than a loaded one),
+  `inspect({ action: 'evaluateExpression' })`, `content({ action: 'parse' })`.
+- **Checkpoint only:** `input` - an input event on the wire cannot be
+  recalled, so cancelling stops events that had not gone out yet and undoes
+  nothing already dispatched (a cancelled drag does still release the button).
+  Same for `request` with `destination: 'browser'`, `screenshot`, and the
+  non-waiting `content`/`inspect` actions.
+
+`breakpoint({ action: 'await' })` is cancellable and now **fails** the step
+(it used to report success). `dom`, `network` and everything else have no real
+wait to interrupt, so they stop at the next step boundary. In every case, work
+already dispatched to the browser may still take effect. Full table:
+`docs/replay.md`.
+
+Several runs can execute concurrently - even of the same sequence - and the
+run id is what tells them apart. Settled runs and their results are kept in
+memory for 30 minutes (max 50); after that, or after a server restart (which
+kills in-flight runs), the id returns `REPLAY_RUN_NOT_FOUND`. Nested sequences
+(`conditional` flows, `replay run` steps) are part of their parent run, never
+separate runs. Pass `wait: true` to block until completion and get the full
+result in one call (the pre-0.7 behaviour).
+
+Useful `run` parameters:
+
+- `startUrl` - override the stored start URL for this run only (e.g. a
+  freshly minted magic link)
+- `baseUrl` - retarget every absolute URL at another origin, keeping paths and
+  queries. Point a staging-recorded sequence at local
+- `startFrom` - begin at step N (1-indexed)
+- `stepTimeout` / `totalTimeout` - each step is bounded by
+  `min(stepTimeout, remaining totalTimeout)` (defaults 30s / 5min); a step that
+  exceeds it fails the run at that step. `wait` steps are exempt from
+  `stepTimeout` (they have their own `timeoutMs`) but still capped by
+  `totalTimeout`
+- `variables` - substitute recorded typed text (see below)
+- `killChromeOnFinish` - tears down the browsers this run OWNS: its own
+  run-level connection, plus any browser a `launchChrome` step actually
+  created. A step that reached an already-bound reference only borrowed that
+  browser, so it is left running and a sequence can read from a long-lived
+  instance you launched yourself without it being killed underneath you.
+  Skipped for any browser whose port another live connection shares (a
+  `launchChrome` step usually opens a tab in the same instance) - the run says
+  which connection kept it alive
+
+Step through interactively with `step`, `finish`, `insert`, `status`, `cancel`
+(`run` with `stepTo: N` pauses after step N; the run's status becomes `paused`
+and you drive it from there). A bare `cancel` prefers the paused session;
+use `runId` to address a specific background run.
+
+## Two different "variables" - don't confuse them
+
+**1. `variables` on `run` replaces recorded typed text.** Keyed by the recorded
+input, for replaying a signup with a fresh email:
+
+```
+replay({ action: 'run', sequenceId: 'seq-signup',
+         variables: { 'var_2_#email': 'new@example.com' } })
+```
+
+**2. `saveAs` captures a value mid-run for later steps.** Supported on
+`request` and on `inspect({ action: 'evaluateExpression' })`. Later steps read
+it with `{{var:name}}` or `{{var:name.path}}`:
+
+```
+request({ url: '...', saveAs: 'login' })          // stores the whole response
+inspect({ action: 'evaluateExpression',
+          expression: 'document.querySelector("#pair").href',
+          saveAs: 'pairingUrl' })                  // stores the value itself
+navigate({ action: 'goto', url: '{{var:pairingUrl}}' })
+assert({ left: '{{var:login.body.token}}', operator: 'exists' })
+```
+
+Note the asymmetry: `request` stores the response object (so you index into
+`.body`), `inspect` stores the evaluated value directly. A `saveAs` that can't
+be honoured fails the step rather than silently capturing nothing.
+
+Values that only render as a description (`[HTMLDivElement]`, `Array(3)`) come
+back as strings - capture a specific field rather than a whole DOM object.
+
+## Waiting for async work
+
+Recording by hand hides races: driving tools interactively puts seconds
+between calls, so async work always looks settled. Replayed back-to-back, a
+step after a navigation or an async kick-off reads state that isn't there
+yet. `wait` is the sequence step for that:
+
+```
+{ tool: 'wait', params: { selector: 'button:has-text("Join")' } }   // appears
+{ tool: 'wait', params: { selectorGone: '.spinner' } }              // disappears
+{ tool: 'wait', params: { expression: 'window.__probe !== "PENDING"' } }
+{ tool: 'wait', params: { ms: 500 } }                               // last resort
+```
+
+Exactly one form per step. Condition forms poll a **synchronous** check from
+the MCP side (default: every 100ms, up to `timeoutMs` 15000), so they survive
+a navigation mid-wait and don't depend on in-page timers or promises. On
+timeout the step fails and stops the run - a `wait` never hangs. For async
+in-page work, kick it off in one step, store the result in a global, then
+`wait({ expression: 'window.__result !== undefined' })` and read it with
+`inspect` + `saveAs`.
+
+Historical note: sequences in the wild use a marker-div + hover-on-
+`:has-text()` idiom (an `input({ action: 'hover' })` on an element that only
+exists once async work settles). That was never stylistic - hover's short
+implicit element-wait was the *only* step that waited at all before `wait`
+existed. Don't copy the pattern into new sequences; use `wait` and `assert`.
+
+## Multi-device / multi-browser sequences
+
+Any step may carry its own `connectionReason`, and it is honoured for
+validation and pause handling, not just dispatch. That's what makes
+"device A scans, device B confirms" sequences work in one run:
+
+```
+{ tool: 'input',   params: { action: 'click', selector: '#pair',
+                             connectionReason: 'device-a' } }
+{ tool: 'inspect', params: { action: 'evaluateExpression',
+                             expression: '...', saveAs: 'code',
+                             connectionReason: 'device-a' } }
+{ tool: 'navigate', params: { action: 'goto', url: '{{var:code}}',
+                              connectionReason: 'device-b' } }
+```
+
+Steps without an explicit `connectionReason` use the run-level one.
+
+**Recording one.** Pass `connectionReason` explicitly on **every** call while you
+drive the browsers - including the one that happens to be active. Recording
+preserves it, and `create` decides what to do with it:
+
+- all steps on one connection - hoisted off the steps, so the sequence stays
+  portable and `run({ connectionReason })` still retargets it
+- genuinely spanning connections - kept per step
+- **mixed** (some steps named, some driven implicitly through the active
+  connection) - kept as-is with a warning, because nothing can tell which
+  browser the bare steps belonged to. `create` says so; re-record naming every
+  step rather than shipping it
+
+"Bare" covers the tools whose `connectionReason` is *optional* (`inspect`,
+`execution`, `storage`, `network`, `breakpoint`, `request`), not just the
+browser-only ones - those are the ones actually left off. A sequence can be both
+multi-connection and mixed, and that is the worst case: the bare steps land in a
+different browser depending on the run-level `connectionReason`, green either
+way. `create` warns about both.
+
+**Inserting into one.** `insert` re-stamps the connection `create` hoisted off
+(kept on the sequence as `recordedConnection`) before merging, so a same-browser
+insert re-hoists and stays portable, while a cross-browser insert makes every
+step explicit and becomes a real multi-connection sequence.
+
+**Declaring the browsers it needs.** A sequence can bring up its own browsers
+instead of expecting the caller to have launched them. Set it with `declare`:
+
+```js
+replay({ action: 'declare', name: 'duo-stock-propagation',
+         requiredConnections: [
+           { reference: 'duo-member-two', role: 'the member who draws stock',
+             url: 'http://localhost:5173/login' }
+         ] })
+```
+
+Each list replaces its field and `[]` clears it; passing one leaves the other
+untouched. The sequence is written back to its file (a memory-only one waits
+for `export`), and a declaration that cannot mean what it says is refused here
+rather than on the next run. It lands on the sequence next to `commands`:
+
+```json
+"requiredConnections": [
+  { "reference": "duo-member-two", "role": "the member who draws stock",
+    "url": "http://localhost:5173/login" }
+]
+```
+
+`url` defaults to the sequence's `startUrl`; `forceNewInstance` defaults to
+**true** (a separate process, not a tab - two identities in one browser share
+its storage); `role` shows up in the run summary. A reference already bound to
+a live browser is reused, and a `connections` mapping wins over the
+declaration. A browser that will not launch fails the run before step 1.
+
+**`profile` makes the device durable.** Add the persistent profile the browser
+should come up on - the same ones `launchChrome({ profile })` creates:
+
+```json
+{ "reference": "device-a", "profile": "device-a", "role": "the enrolled device" }
+```
+
+Storage (cookies, localStorage, IndexedDB, non-extractable CryptoKeys) survives
+between runs, so a device enrolled once stays enrolled; the reference is just
+this session's name for it. Steps still address browsers by `connectionReason` -
+there is no per-step `profile`.
+
+Two rules follow. `forceNewInstance` defaults to **false** when a profile is
+named, because only one live Chrome may hold a profile and the one already
+running it is the browser you asked for. And a profile-bearing reference may
+**not** be rebound through `connections`, nor may two declarations share one
+profile: a profile is an identity claim, not a default, and pointing it
+elsewhere would run device-a's steps in a browser that is not device-a and pass.
+Teardown kills the browser but never the profile directory.
+
+The run closes what it launched on every terminal outcome - completed, failed,
+cancelled - and reports *"Browsers closed (declared and launched): ..."*. A
+pause keeps them (that is the state you stopped to inspect); whatever ends the
+pause (`cancel`, `finish`, stepping off the end) closes them then. Browsers
+that were already up, or that share a port with another live connection, are
+left alone.
+
+**Declaring the sockets it depends on.** `requiredSockets` is the same idea for
+transports: URL substrings of the WebSockets the assertions ride on, set by the
+same action (`replay({ action: 'declare', name: '...', requiredSockets:
+['/api/sync/socket'] })`). A sequence that declares them is
+checked without the caller asking - `requireSockets: true` is only for a
+sequence that declares none. Per entry the run fails when a matching socket
+closed or hit frame errors mid-run, or when none is open at the end (including
+one that never opened - invisible to any final "is it up" assertion). Closes
+the run did not cause are not blamed on it: a socket torn down with its target
+by a navigation, or hung up by the page, is normal. Match the app's own path,
+not the origin, so the declaration survives `baseUrl`; dev-server sockets (Vite
+HMR) go undeclared and are ignored.
+
+**Replaying one in a different session.** Recorded references are per-session,
+so rebind them:
+
+```
+replay({ action: 'run', sequenceId: 'duo',
+         connections: { 'duo-member-two': 'my-second-browser' } })
+```
+
+Recorded name on the left, a reference from this session on the right. A key
+that matches nothing in the sequence is rejected up front, listing the real
+ones, rather than being ignored - "the sequence" includes the sequences its
+`conditional` steps pull in, so a setup sequence behind a conditional is
+rebindable too. Mapping two recorded references onto one browser is rejected as
+well - that would collapse the sequence into a single browser and pass.
+`issues({ action: 'workOn' | 'resolve' })` takes `connections` too.
+
+Any step naming a connection other than the run's is checked against the live
+session first, so a missing browser fails as *"step 3 needs connection
+duo-member-two, which does not exist in this session"* rather than as a generic
+"not connected to browser" from somewhere inside the tool.
+
+**repeat / runFromLog.** Each command replays against the connection it was
+recorded with. An explicit `connectionReason` retargets a single-connection
+batch and is refused for a multi-connection one.
+
+**Exported code.** `outputFormat: 'playwright' | 'puppeteer'` gives each recorded
+connection its own page rather than merging them into one. Only `navigate` and
+`input` steps have equivalents; everything else (`conditional`, `launchChrome`,
+`inspect`, `storage`, `wait`) becomes a `// [not generated]` comment, and a
+sequence where nothing could be generated exports a test that **throws** instead
+of an empty one that passes. Setup sequences are for `run`, not for export.
+
+Two things that deliberately do not happen: a run-level `connectionReason` does
+**not** override a step's own, and a per-step reference that doesn't exist in
+this session **fails the step** - it never falls back to the run-level
+connection. Falling back is what made a two-browser sequence silently replay in
+one browser and report success.
+
+## Conditional steps
+
+`conditional` is a virtual step tool - it runs another sequence inline when a
+condition holds. It's handled inside the executor and never appears in the tool
+list, which is why it's exempt from tool-name validation.
+
+Not being a tool, it is never recorded, so `create`/`insert` cannot produce
+one. `addConditional` is its authoring route:
+
+```javascript
+replay({ action: 'addConditional',
+         name: 'checkout-flow',          // or sequenceId
+         condition: '{{selector:.login-button}}',
+         thenSequence: 'perform-login',  // name of another sequence
+         insertAfterStep: 0 })           // omit to append
+```
+
+which stores `{ tool: 'conditional', params: { if, then } }`. Use it for state
+that varies between runs - "log in first, but only if logged out".
+
+Condition syntax and the branch target are checked before the sequence is
+touched. A sequence already saved on disk is rewritten in place; otherwise it
+waits for `export`. The response says which.
+
+| Condition | True when |
+|---|---|
+| `{{selector:CSS}}` / `{{!selector:CSS}}` | element exists / doesn't |
+| `{{url:contains:STRING}}` | current URL contains the string |
+| `{{url:matches:REGEX}}` | current URL matches the regex |
+| `{{url:EXACT}}` | current URL equals the value |
+| `{{cookie:NAME}}` / `{{!cookie:NAME}}` | cookie exists / doesn't |
+| `{{localStorage:KEY}}` / `{{!localStorage:KEY}}` | key exists / doesn't |
+| `{{indexedDB:DB/STORE/KEY}}` / `{{!indexedDB:...}}` | that record exists / doesn't |
+| `{{indexedDB:DB/STORE}}` | the object store holds at least one record |
+
+A database or store that doesn't exist yet counts as **absent**, not as an
+evaluation error - that's the state a wiped profile is in, and the state a
+healing setup sequence exists to fix.
+| `{{indexedDB:DB/STORE/KEY}}` / `{{!indexedDB:...}}` | that record exists / doesn't |
+| `{{indexedDB:DB/STORE}}` | the object store holds at least one record |
+
+A database or store that doesn't exist yet is **absent**, not an error - that's
+the state a wiped profile is in. A value JSON can't represent (a
+non-extractable `CryptoKey`, a `Blob`) still counts as present, so a device
+identity is probeable directly instead of through some UI proxy. An all-digits
+key is tried as a string and then as a number, since IndexedDB keys `42` and
+`"42"` differ.
+
+Conditions are interpolated like any other parameter, so a captured variable can
+drive one: `{{indexedDB:identity/keys/{{var:deviceId}}}}`.
+
+**Not met and cannot-evaluate are different outcomes.** A condition that is
+legitimately false skips the nested sequence and the step counts as a
+**success**. A condition that can't be evaluated at all - bad format, unknown
+type, invalid or over-long regex, tool error - **fails the run**. Don't write a
+conditional expecting a malformed condition to fall through quietly.
+
+The nested sequence shares the parent run's captured variables (`saveAs` values
+flow both ways) and inherits its remaining timeout budget. A `launchChrome` step
+inside it is skipped when that reference is already connected and run when it
+isn't, so a setup sequence spanning two browsers can create the second one
+itself.
+
+**Which browser its bare steps run in** follows from that: if the nested launch
+actually ran, they run in the browser it created (a setup sequence is a launch
+plus bare steps, since `create` hoists the connection off them - leaving them on
+the caller would open a browser and then do the work in the wrong one); if the
+launch was skipped or absent, they run in the calling run's connection, so a
+nested login sequence still works wherever it's called from. Steps naming their
+own `connectionReason` are unaffected.
+
+**Two connections are not two devices.** A plain `launchChrome` opens a tab in
+the running instance, so both references share one profile - one cookie jar, one
+localStorage, one IndexedDB. A duo test built that way has ONE device identity
+under two names, and a cross-user propagation check passes without a second
+device existing. When the two sides must be genuinely separate, launch the
+second with its own profile:
+`launchChrome({ reference: 'duo-member-two', profile: 'member', forceNewInstance: true })`.
+Same `port` in `listConnections` means same instance, so shared storage.
+
+Nesting depth is capped by `replay.maxConditionalDepth` (default 10) and regexes
+by `replay.maxRegexLength` (default 500), both in `.cdp-tools/config.json`.
+Oscillating chains (A->B->A) are allowed up to the depth cap. Full detail:
+`docs/replay.md`.
+
+## `forEach` steps
+
+A condition asks whether ONE named thing exists, so `conditional` can express
+"add it if it's missing" but never "remove everything that shouldn't be here".
+`forEach` is the other half: enumerate a source, run a sequence per item.
+
+```javascript
+{ tool: 'forEach', params: {
+    in: '{{var:shares}}',                 // an array a previous saveAs captured
+    as: 'share',                          // bound per iteration
+    do: 'revoke-one-share',               // sequence name, run once per item
+    where: 'item.name !== "Employees"',   // optional filter
+    maxItems: 50 } }                      // optional cap (default 100)
+```
+
+**`in` takes two forms.** `{{var:name}}` reads an array a previous `saveAs`
+captured - which is how anything non-DOM is enumerated, since
+`inspect({ action: 'evaluateExpression', saveAs: 'shares' })` can return exactly
+the list you want and is a recordable step. `{{selectorAll:CSS}}` enumerates the
+DOM, yielding `{ index, text, id, className, href, value }` per element -
+elements themselves cannot cross the CDP boundary, so `index` is what the body
+uses to address one again.
+
+**`as` binds the item**, readable in the body as `{{var:share.id}}` like any
+captured variable, with its position in `{{var:shareIndex}}`. The binding is
+replaced per iteration, not scoped - the variable store is shared by reference
+across nested runs, so a body's own `saveAs` captures also survive into the next
+iteration.
+
+**`where` is JavaScript, not the `{{...}}` condition grammar**, evaluated in the
+page with `item` and `index` in scope. Conditions probe the browser for one named
+thing; a filter has to read fields off an arbitrary object, which that grammar
+cannot express. A `where` that cannot be evaluated **fails the run** - the same
+rule a malformed condition follows, because silently excluding every item makes a
+typo look like an empty result set.
+
+An empty source is a **success**, and the run output says how many items were
+found - a converge loop with nothing left to clean up would otherwise be
+indistinguishable from a broken selector. A body failure stops the run and names
+which item it was on. Depth shares `maxConditionalDepth` with `conditional`.
+
+## `teardown` - steps that always run
+
+A sequence can carry a `teardown` array beside its `commands`:
+
+```json
+{ "name": "mint-and-check",
+  "commands": [ ... ],
+  "teardown": [
+    { "tool": "request",
+      "params": { "url": "/api/share/revoke/{{var:mint.body.id}}", "method": "POST" } }
+  ] }
+```
+
+They run once the main steps reach a terminal state - success, a failed step, an
+abort, or the total timeout - which is what makes cleanup survive the cases that
+need it. Three properties, each deliberate:
+
+- **Their own timeout budget** (`teardownTimeout`, default 60s), not drawn from
+  the run's `totalTimeout`. The commonest reason a run needs cleaning up after is
+  that it timed out; sharing the budget would skip teardown exactly then.
+- **The run's abort signal is NOT passed down**, so `replay cancel` stops the
+  work and not the cleanup. A cancelled run is precisely one that left something
+  behind.
+- **The variable store is shared**, so teardown can revoke what setup minted even
+  though the capturing step ran long before the failure.
+
+They do **not** run when a run *pauses* - `stepTo`, a breakpoint, a click
+validation failure. A paused run is not over, and its state is what you stopped
+to look at.
+
+A failing teardown step never changes the run's verdict; it is reported in its
+own section. Otherwise a broken cleanup would mask the failure it was cleaning up
+after.
+
+**Teardown is always best-effort.** A killed cdp-tools process takes any pending
+teardown with it, so it reduces accumulation and cannot guarantee a clean world.
+An assertion that depends on nothing being left over ("No assets yet") stays
+order-dependent whether or not teardown exists - mint your own fixture and assert
+on that instead, and teardown becomes hygiene rather than correctness.
+
+## When a sequence is flaky
+
+Name the symptom rather than adding sleeps - each of these has a real mechanism
+behind it, documented in `docs/replay.md`:
+
+| Symptom | What to reach for |
+|---|---|
+| Clicks land before the element exists | Click/type/hover already retry; add an explicit `wait({ selector })` step for work the previous step kicked off |
+| Consent banners or dialogs block interaction | `handleModals: true` on the input action, with a `dismissStrategy` |
+| Stale content while requests are in flight | `wait({ expression })` on a flag the app sets, not a fixed sleep |
+| localhost URL fails because nothing is running | The port check fails fast - start the server (`server({ action: 'start' })`) |
+| A run hangs or takes far too long | `stepTimeout` / `totalTimeout`; a step exceeding its budget fails the run at that step |
+| A step ran against the wrong browser | See the multi-device section - almost always a bare `connectionReason` |
+
+## Verifying a fix
+
+`issues({ action: 'workOn', id: N })` replays an issue's linked sequence so you
+can see the bug reproduce, fix it, then replay again. Closing the issue is
+`resolve`, which is human-gated - an agent should record findings with
+`comment` and leave the closing to a person.