Build and Check

Build

Build is the default action:

omegaflow recording=demo

A build:

1. records the scripted terminal session when the current recording is stale;
2. prepares narration audio when enabled;
3. adjusts terminal and narration timing for presentation;
4. checks visible commands and captions against the script;
5. publishes the configured output surfaces; and
6. applies run retention after a successful build.

For browser and mixed recordings, the analogous pipeline normalizes the typed plan, reuses or captures one persistent terminal/browser environment, prepares narration takes, solves a global semantic timeline, validates the closed public bundle, and publishes the selected surfaces. Presentation-only changes reuse a fresh private capture.

Fresh artifacts are reused. Force every rebuildable stage to run with:

omegaflow recording=demo force=true

Use a visible recorder window for one run with headed=true:

omegaflow recording=demo headed=true

verbose=true exposes more detail about freshness decisions and generated artifacts.

Preview a build

dry_run=true resolves the recording and prints its inputs, outputs, publish targets, and processing stages without running commands:

omegaflow recording=demo dry_run=true
omegaflow recording=demo dry_run=true output_format=json

This is a build mode, not a separate action.

Run one build stage

Use step when authoring or diagnosing a recording and you need one expensive part of the build without its downstream work:

omegaflow recording=demo step=capture
omegaflow recording=demo step=narration

step=capture runs the scripted terminal and browser workflow without preparing narration, assembling a video, or publishing it. step=narration generates or reuses narration takes without capture, assembly, or publishing. A normal build remains the preferred command when you want a finished video.

Select a publish surface

When a recording defines multiple publish surfaces, surface limits this build to one named surface:

omegaflow recording=demo surface=docs

Without the override, the recording's publish.on_build, publish.build_surfaces, and publish.default settings decide what is published.

Check

Check validates the recording and the freshness/alignment of generated artifacts without rebuilding them:

omegaflow recording=demo action=check

Use it when a CI job or release gate should fail instead of silently updating an output. If it reports stale or missing artifacts, run a build and check again.

For browser/mixed recordings, check validates the source, capture fingerprint, complete run_end, and the freshest run-local presentation bundle when one exists. It does not visit external sites or rebuild artifacts.

Common failures

• No recording selected: add recording=<id> or use action=list.
• A scripted command failed: use the printed action=inspect and action=output follow-ups. See Runs and Troubleshooting.
• Generated output is stale: rebuild the selected recording.
• A publish surface is unknown: check the recording's publish.surfaces mapping or remove the surface override.