Lessons from four films: copy that reads as written by a person, render and audio pitfalls, contributing notes

[ZLHad]

The maintainer asked that the general lessons sitting in an agent's notes and in project LESSONS.md files move into the docs, leaving out what is personal to one channel. They come from four films (《发送之后》, the FZ1073 film, the 3-minute tech-history film) and the review rounds of 2026-10-04/05.

What goes where

• playbook/09-narrative.md §10 (new): how narration, title cards and labels read as written by a person: the fact carries the heaviest beat, sentence lengths vary, the shapes models reach for (parallelism, triplets, "不是……而是……") are rare, spoken words, explanations go into labels, one common way to end in plain words, a caption-only script goes out with the gate ② storyboard. Written as a default that a concept can override; any film with narration or cards reads it. templates/SCRIPT.md points to it.
• playbook/12-ideation.md §4 and §7: the concept card's 首尾 line goes down to the last line or last picture.
• playbook/03-motion-design.md §2: text over a dense picture need not run faster than the same lines read as narration; re-export texts.json before trusting readcheck.
• playbook/02-verification.md, silent failures: sweep the frame function over every frame to catch an exception thrown in one shot only.
• engines/README.md: agent background tasks have a time limit, so detach long renders; two <script src> pitfalls plus the inline window.__timelines registration; three Three.js pitfalls.
• tools/audio/README.md: Gemini transcription quota and --resume; cue check can't see sounds with no attack (textures, section stop).
• CONTRIBUTING.md: run every subcommand before "the rest are fine", check rewordings for behaviour changes, run shellcheck and pyflakes locally through uv.
• cases/README.md: new cases from forwarded videos record content, not account names or how the videos arrived.

Left out on purpose: one person's reading speed, account positioning, key locations, and lessons already in the docs (review caps, light process, taste as defaults, Douyin frame grabs, SFX variety, outline names by content).

Checks: tools/ci.sh --committed passes, also with VH_BASH=/bin/bash; shellcheck and pyflakes ran through the new uv recipe (not skipped). Docs only, no behaviour change.