Publishing & Delivery

The final stamp on a project: record that a video is ready, published, or blocked, point at the finished file, and leave a machine-readable receipt anyone — human or agent — can trust.

What it does

• Marks the publish stage of a project with one of three states: ready (cleared review, safe to ship), published (it has gone out), or blocked (something is stopping delivery).
• Writes a canonical publish-report.json artifact so the project's "is this done?" answer lives on disk, not in someone's head.
• Records the path to the final rendered video (--final-output) so the deliverable is tied to the project.
• Captures freeform notes — release context, or the exact reason a project is blocked.
• Updates the project's checkpoint, event timeline, and manifest state in one shot, so status, reports, and dashboards all agree.
• Refuses to run until the publish stage is actually reachable — a project that has not passed review cannot be marked published by accident.

How to use it

The installed CLI is vclaw; from a source checkout run npm run build first and use node dist/cli/vclaw.js as shown below.

node dist/cli/vclaw.js video publish --project my-promo --status ready

Records the project as cleared and safe to ship; writes publish-report.json with status: "ready".

node dist/cli/vclaw.js video publish --project my-promo --status published --final-output projects/my-promo/output/final.mp4

Marks it as delivered and pins the finished video file to the report.

node dist/cli/vclaw.js video publish --project my-promo --status blocked --note "Client wants a different soundtrack" --note "Re-render scene 3"

Flags the project as blocked and attaches one or more reasons; --note repeats.

node dist/cli/vclaw.js video status --project my-promo

Reads back the project's current stage and confirms the publish state landed.

How it flows

Diagram source (live Mermaid)

Artifacts & outputs

• publish-report.json — written to projects/<slug>/artifacts/publish-report.json. Holds projectSlug, status (ready | published | blocked), generatedAt, and optionally finalOutputPath and notes. A prior copy is snapshotted under projects/<slug>/artifacts/history/.
• A publish checkpoint under projects/<slug>/checkpoints/ — completed for ready/published, failed for blocked (with the notes as issues).
• An artifact.publish-report.written line appended to projects/<slug>/events/events.jsonl.
• The command also prints the full artifact as JSON to stdout.

Tips & gotchas

"ready" is a promise, not a hope

A project is only genuinely shippable when its review-report.json has both verdict: "pass" and metrics.publishReady: true. Mark --status ready to reflect that, then --status published once the file has actually gone out. See Director mode and Projects & lifecycle.

Publish does not skip the gate

publish requires the publish stage to be reachable for the project's production mode. A stale or failed review means the stage is not ready and the command throws instead of silently stamping it done. Resolve the review first.

Use blocked as a paper trail

--status blocked --note "..." is the right way to park a project. The notes flow into the checkpoint issues and the event log, so the next operator (or agent) sees exactly why and what to fix.

Driving it from an agent

video publish is deterministic and writes JSON to stdout. It exits 0 on success and non-zero if --project/--status are missing or the publish stage is not ready — so an agent should treat a non-zero exit as "not shippable yet, re-check review" rather than retrying blindly. Marking --status blocked is itself a 0 exit (the block was recorded successfully); read status back to branch on the new project state.

Related: Storyboard · Director mode · Projects & lifecycle