Review

A scene is judged in two passes: code checks every frame, then a reviewer agent reads a contact sheet. It goes round until it passes or reaches you. Checks, reviewers, and people all write the same mark.

#1. Code checks

After every render, rapid check holds the scene to its format and style before any agent looks, and writes renders/<id>/r<n>.checks.json: { "pass": boolean, "marks": Mark[] }, each mark authored { "kind": "check", "name": <check> }.

The placement checks (crop, band, keep-out, safe) hold only elements at rest: an element moving between frames is entering or leaving, so it isn't marked, and one wholly off the frame isn't seen. min-text holds whenever type is on the frame. An edge may cross a guide by half a pixel. Hits of one check on one element on consecutive frames merge into one mark with a span.

Blockers and majors fail the scene; minors and nits go to the reviewer as notes. In a video, a scene with code problems fails its render before any check runs. The checks see only elements with data-el and data-role (tracked elements).

#Key frames first

Before a scene moves, its hero is built as a still at meta.key. Code checks the still (rapid check --still, renders/<id>/key-k<try>.checks.json): placement, fonts, problems, empty, grid, scale; in a video every scene but the storyboard's one breath is held to 40% empty field whatever its room. The reviewer reads the frame into the review's frame (each third, how much is bare, hero over body, the visual doing work) and judges it as a poster against the storyboard's key and the style's proof: reviews/<id>-k<try>.json. A major from the checks, or a review that never read the frame, makes a pass a revise. Three tries, then an approval. --keys person has you approve the still instead; --keys off skips key frames.

#2. The contact sheet

The reviewer never watches the video. rapid sheet draws frames at chosen moments, each labelled with its time and frame number:

• Round 1: the poster, then every cue. With no cues, frames spread over the scene.
• Later rounds: the starts and ends of the changed spans, the cues inside them, then the poster.
• At most --max (12) frames, no two in one frame.

With agent review, rapid sheet --micro adds a strip 0.3 s either side of the key and of every mark the review must answer. A rapid-reviewer reads the sheet, the strip, the checks, and the previous scene's sheet in a fresh context, against taste.md and the refs; it never edits the scene and doesn't repeat what the checks found. It writes reviews/<id>-r<n>.json.

#3. Rounds

--rounds (default 4, 1–10). From round 2 the builder reads the last review and checks and changes only what their marks ask, near their times. A review lists every earlier mark it was handed (the last round's, the key frame's, the director's) in answers; a pass that leaves one carried, or leaves one out, counts as a revise. With --review none, passing checks accept the scene and failing ones go straight to an approval.

What a builder reads: the last review and checks; renders/<id>/marks.json, a person's marks (the screening page, add_mark, rapid revise --at), read first and acted on before anything else; and any rapid redo --note, in its prompt.

#4. Stops

With --stops all, approvals wait after the storyboard, on a key frame that didn't settle (every key frame with --keys person), and on a scene out of rounds or sent to you. --stops storyboard keeps only the first; --stops none keeps none and takes the best try or round instead. At a stop:

• approve: rapid approve <node>, /rapid approve <node>, Approve in the pane, or ask Claude;
• redo the step before it with a direction: rapid redo <node> --note "…";
• look first: /rapid open <node>, or Open in the pane.

#Mark

Mark in contracts/src/marks.ts.

{
  "id": "r1-card-hold",
  "scene_id": "card",
  "version": "9c1e…",
  "t": 0.8,
  "t_end": 2.3,
  "element": "card",
  "note": "The card holds too long before it leaves; cut the hold to about 0.8 s so it leaves on the settle.",
  "severity": "major",
  "author": { "kind": "agent", "name": "rapid-reviewer" },
  "created_at": "2026-10-28T12:00:00.000Z"
}

POST /api/marks takes a mark without id and created_at, with an optional job_id (HTTP API).

#Review

One round's judgment, reviews/<id>-r<round>.json, or a key frame's, reviews/<id>-k<try>.json (round is then the try, and every mark sits at the key time).