# Authoring a report video

From a cited sweep report to a built cut. Written for an agent; a person can
follow it too.

## 0. Scaffold

```sh
umtool new <slug> --from ~/reports/<sweep>/sweep-report.md
```

Writes the directory, a manifest skeleton with an **empty** timeline, and a
README listing every `?v=` citation as a checklist.

## 1. Fill in provenance — `siteOrigin` FIRST

```jsonc
"provenance": {
  "siteOrigin": "https://jeralyzer.pages.dev",   // the archive's REAL origin
  "channelSlug": "the-quartering",               // default channel for cue lookups
  "channel": "TheQuartering"
}
```

**This is the field that shipped broken twice.** One manifest has no `siteOrigin`
at all — 19 QR codes encoding `undefined/?v=…` — and one has
`http://localhost:3000`, a finished video whose codes resolve to nothing on
anybody's phone. `umtool check` blocks until it is set to something real.

## 2. Turn each citation into a WINDOW

**This is the work, and it is the part nothing automates.**

A report records **one** second per citation. A clip needs a start *and* an end,
and both come from the source's cue file:

```
transcripts/channels/<channel>/data/<video>/transcript.cues.json
```

For each citation:

1. Open the cue file and find the cues around the cited second.
2. **Verify the quote is actually there, and that the speaker is who you think.**
   Two standing traps: a first-person quote is often the host reading someone
   else's tweet aloud or being sarcastic — check ±90 s of context; and ASR
   garbles names (the corpus stores "Metokur" as "mr medicare").
3. Take `start` from the first cue of the thought and `end` from the last.
4. Round to **2 dp**.

```jsonc
{ "type": "clip", "id": "c04", "video": "uyz1_FIqIEk",
  "start": 32980.24, "end": 32994.19,
  "cite": 32989,
  "quote": "the words this clip exists for",
  "note": "why it is in the cut" }
```

**Array order is the cut.** There is no sort.

Per-clip `channel` when the sources span mirrors. On Rumble, `video` must be the
**local directory slug**, not the site/MCP id — see [quirks.md](quirks.md).

## 3. Check, before anything encodes

```sh
umtool check <slug>
```

Fix everything blocking. It catches a dead origin, a missing `channelSlug`,
duplicate ids, a cue file that is not there, and a source the last preflight found
gone.

## 4. Widen to sentences

```sh
node umtool/report-to-video/resolve-windows.mjs <manifest>          # dry
node umtool/report-to-video/resolve-windows.mjs <manifest> --write  # apply
```

A cue boundary is a *line-wrap* boundary, so cutting there drops the lead-in that
makes a quote make sense.

Then read the result. Where the widener made a clip worse — it swallowed
neighbouring audio, or it undid a deliberately short quote — set `lock` and say
why in the project README. Across the six real manifests, five are **100% locked**:
a human-chosen window usually *is* the truth.

## 5. Bench each clip

`/browse/<slug>/clip/<id>`. Look at the waveform and the cue rail, and act on
what it says: run a clip to the end of its sentence, or set `lockEnd` to
acknowledge that you meant to cut there. One 14-clip cut shipped with 8 clips
ending mid-thought.

If it warns that the widener would revert your edit, take the offer to set the
matching lock.

## 6. Fast pass, watch it, then final

```sh
umtool build <slug> --preset fast     # hard cuts, minutes
umtool build <slug> --preset final
```

Watch the fast pass end to end. It is the only way to find a clip that is
technically correct and editorially wrong.

## The checklist

- [ ] `siteOrigin` is the archive's real origin
- [ ] every `video` is the **local** directory slug
- [ ] every quote verified in context, not just found by search
- [ ] every window at 2 dp, `end` after `start`
- [ ] `umtool check` exits 0
- [ ] windows resolved, or locked with a reason written down
- [ ] no clip ends mid-sentence unless `lockEnd` says so
- [ ] a fast pass watched all the way through

## What a sweep will miss

Worth knowing before you trust a citation list to be complete: a share-link
keyword is the **spine** of a sweep, not its coverage. Back it with substring,
clinical-vocabulary and symptom sweeps — one real cut's earliest and best clip
never says the search word at all.