add_marker
Add timestamped narration markers to screen recordings, with Clipy-verified assertions or driver-attested pass/fail evidence. Markers become transcript chapters.
Instructions
Drop a live-timestamped narration marker into the active recording session ('reproduced the bug', 'the fix renders correctly at mobile width'). Markers become the recording's transcript chapters, so narrate as you work — they are how the recording stays agent-readable despite having no audio. A mark can carry evidence in ONE of two provenances, never both. (1) CLIPY-VERIFIED — assertSelector (element must exist), assertText (that element must contain the text; requires assertSelector), assertUrl (glob on the live URL): Clipy itself checks the recorded page, so this is the strongest evidence. (2) DRIVER-ATTESTED — observed + verdict (both required together): you report what YOUR tooling saw and whether it passed. Clipy vouches only that you SAID it — it did NOT verify it — which is falsifiable against the recorded frames: weaker than clipy-verified, far stronger than plain prose. Use driver-attested when your agent drives its OWN browser/tooling while Clipy records (e.g. via mac-screen) or when there is no Clipy-owned page to assert against. The two lanes are rendered so the weaker one LOOKS weaker at a glance: clipy-verified marks lead with a verdict glyph ([assert ✓ verified-by-clipy; …] / [ASSERT ✗ verified-by-clipy; …]), while driver-attested marks lead with a HEDGE glyph instead ([≈ ASSERT driver-attested; observed=…] / [≈ FAILED driver-attested; observed=…]) — a skimming reviewer must never mistake an attestation for a verification. Failures are annotated into the mark as explicit FAILURES (never written as fact), tallied in their own segment of the recording's verification summary, and — with failMode 'abort' — discard the whole session. Marks default to the live recording clock; pass atSeconds to backdate one.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | What is happening right now. | |
| verdict | No | DRIVER-ATTESTED outcome for `observed`. Requires observed. Mutually exclusive with assertSelector/assertText/assertUrl. | |
| failMode | No | On a FAILED outcome (a clipy-verified assertion that failed, or a driver-attested verdict of 'fail'): 'warn' (default) records the failure and keeps recording; 'abort' discards the whole session (like abort_recording) and returns loudly. A pass never aborts; an unverified claim never aborts. | |
| observed | No | DRIVER-ATTESTED evidence: what YOUR tooling observed (e.g. 'HTTP 200, body contains orderId'). Requires verdict. Mutually exclusive with assertSelector/assertText/assertUrl — one provenance per mark. | |
| assertUrl | No | Glob the current page URL must match. `**` matches anything (including `/`); `*` matches within a path segment. e.g. 'http://localhost:3000/**/settings'. | |
| atSeconds | No | Place the mark at this point on the recording timeline (seconds from the start), instead of the live clock — e.g. to annotate something that happened a few seconds ago. Clamped to >= 0. (The CLI's relative --ago shorthand is CLI-only; compute the absolute second and pass it here.) Note: any assertion is still evaluated NOW, against the live page — if that diverges from the backdated position by >2s, the mark is annotated so the verdict is never misread as pertaining to the backdated moment. | |
| assertText | No | Substring that must appear in assertSelector's element text. REQUIRES assertSelector — a bare page-body text match is weak evidence and is rejected. | |
| assertSelector | No | CSS selector that must exist on the page at this moment. |