> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Illustrate workflows with reference videos

> Show an expected interaction while preserving its saved context.

A reference video illustrates a workflow definition. It is distinct from a finding's evidence video and a runner's replay recording. Uploading a reference clip does not execute a test or certify the behavior.

## Attach a useful clip

Open a workflow and use its reference-video controls. Choose a small MP4 or WebM that demonstrates the saved-view interaction with synthetic data. Supply a meaningful title and context/note where the UI offers them. Explain what the viewer should inspect, rather than relying on a clip alone to define the expected result.

Upload limits, allowed MIME types and deployment capabilities come from the running server. Local uploads use private filesystem storage; hosted uploads use private R2 with staged/resumable transfers. Do not manually construct large base64 requests or expose storage credentials.

## Handle interrupted uploads

Keep the workflow and upload draft open while the client handles chunk/status/complete operations. A completed staged upload still needs the final association commit. If expectations changed while the upload was in progress, reread the workflow and reconcile; do not force an old expected version onto newer text. Expired or invalid transfers need a fresh upload.

## Edit, replace or detach

Metadata edits, replacements and detachments create saved history rather than rewriting earlier attachments. Confirm replacement/detachment carefully. A failed operation preserves the draft so you can retry after resolving the error. Use the same request identity/content after an ambiguous commit.

Select a historical definition to see that version's association and metadata. A text-only expectation edit keeps the clip's original illustrated definition, so the UI can label it **Earlier expectations**. A detached current clip can still be playable from the exact earlier definition. Historical views are read-only.

Archiving a workflow or ancestor makes it inactive, while saved history remains available under deployment authorization. Do not infer an indefinite media retention policy from history support; operators own backup and retention.

Developers extending uploads should use the [video history contract](https://github.com/SynclyUS/bugspray/blob/main/docs/catalog-video-history.md) and `apps/shared/catalog-videos.ts`, rather than inventing transfer endpoints or bypassing optimistic concurrency.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.