package-script

---
name: package-script
description: Fourth step of the package workflow. Turns the segmented talking-head beats into the package script, a table of Line (what the speaker says, maths in LaTeX), Visual (concrete, cinematic animation directions per beat) and Sources (fact IDs), then runs a de-slop pass and a mandatory audit of every spoken and visual claim before anything is built. Use after beat-segment, or whenever a package's lines or visuals change.
---

# Package script

The script is the single source of truth for what the speaker says and what the animation shows. Lines come from the
recording (via `beats.timeline.json`); Visuals are written here; facts come from `TOPIC.md`.

## Format

`SCRIPT.md`, one table per package, header line first:

```
<package id>, FPS 60, 1080x1920, clean length <total_s> s, background/colour notes
| # | t | Line | Visual | Sources |
| 0 | 0.00 | (no speech: hook visuals, play under beat 1) | … | F1 |
| 1 | 0.00 | <hook line as spoken> | … | F1, F4 |
| 2 | 4.80 | … | … | F2 |
…
```

- `t` is the beat's `clean_start` from `beats.timeline.json`. Never invent times.
- **Line** is the kept speech, corrected only for spelling. Every maths expression goes in inline `$…$`, written as
  exactly what is said and in the same notation as the on-screen equations (`That gives $V = -E_0 r\cos\theta$.`).
  Never put `|` inside maths, because it splits the table: use `\vert`, `\lvert…\rvert` or `\mid`.
- A long equation that is fully on screen and said as "this value" keeps its maths for checking as
  `[on screen: $…$]` right after the phrase.
- If the recording says something wrong (a sign slip, a misnamed law), the Line keeps what was said, followed by
  `[fix: …]`, and the beat is listed in `BEATS.md` for a re-record or a caption correction. The animation always shows
  the correct maths.
- **Visual** is written imperative, concrete and cinematic, with sound noted inline: "Pop in $\dot\theta=\omega$ …
  make $\sin\theta$ glow red and shake." Name colours, where things sit, what moves on which spoken phrase, and the
  3D props. One focal subject per beat. Keep the scene full-bleed (no dead band at the bottom) and text inside the
  safe area (see `package-build` Layout).
- **Sources** lists fact IDs from `TOPIC.md` on every row. The file ends with a citations table that resolves each ID
  to a working URL or a computation.

## Writing new lines (inserts and re-records)

Most lines already exist in the recording. When a line must be written (a missing hook, a fix to re-record, a bridge
between beats), match the speaker's voice and follow these rules:
- Complete sentences with proper grammar; no fragments, no comma splices, no dangling noun phrases after a colon.
- Spoken maths conventions: "Let … be …", "Since …, …", "If …, then …", "so", "which gives".
- Name the central idea in the speaker's own words (from `TOPIC.md`).
- Beat 2 says what the example is for: the question it answers.
- No call to action in the speech (the edit adds a visual one), no "Watch this", no "Follow me".
- Keep each new line within about ±10 % of the words of the line it replaces, so beat timing barely moves.
List every new line in `RERECORD.md` with the beat, the exact words and the maths in LaTeX, so the speaker can read it.

## Voice and de-slop

Copy the speaker, not a narrator. Plain, direct, slightly informal; contractions; short sentences.
Reject these tells in any new line, caption or post copy: "Let's dive in", "Here's the thing", "It's not just X, it's
Y", "In essence", "fascinating", "delve", tidy triplets and mirrored sentence pairs in every beat, em-dash cascades,
summarising what was just said, motivational closers ("That's the magic of…"), and overclaiming ("the entire future",
"everything blows up"). Say what actually holds. Run a de-slop check (a phrase list plus a read-through) on SCRIPT.md,
RERECORD.md and every caption or post text, and fix by rewriting, never by dodging the pattern.

## Recurring visual traps (from audits)

- A spectrum sweep starting at 0 Hz shows the DC offset as the biggest spike; start near 1 Hz or label it.
- Gibbs overshoot belongs to a jump, not to the corner of a continuous path.
- Claims like "transforms into itself" or "sits exactly on the floor" hold for one precise form; show exactly that.
- A mechanism shown on a machine must be what the machine actually did; otherwise use a maths overlay.
- Complex-conjugate eigenvalues move together; never show one of the pair moving alone.
- Field lines never cross, and their density encodes strength.

## Mandatory audit before building

Launch one research agent to audit every spoken and visual claim into `AUDIT.md` next to the script:
- a verdict per claim (CORRECT / LOOSE-but-OK / MISLEADING / WRONG);
- evidence: a computation with its output, or a source URL with a quote;
- for anything not CORRECT, a replacement line in the speaker's voice (for `RERECORD.md`) or a caption fix;
- every citation resolved to a checked, working URL or a computation;
- the style rules above, line by line, for any new line; and every "this value" followed by an `[on screen: $…$]`
  that matches the equation on screen in that beat.
Maths is verified by computation, history by primary or authoritative sources (the original paper, standards,
university notes), and numbers against the package's `math-validation.json` once the build exists. Apply the fixes,
re-run the de-slop check, then hand off.

## Hand-off to production

The builder times each beat from `beats.timeline.json` and stores the beat table as cues in the build manifest. Build
with `math-primitives`, plan motion with the `motion-designer` agent, verify with `visual-qa`, render through
`blender-agent-renders`. The orchestration is in `package-build`.