web sourced footage, illustration engines, and layout qc for explainers

AGENTS.md

@@ -0,0 +1,87 @@
+# video-use repository context
+
+video-use is a public, conversation-driven video production framework. Changes
+made here may be packaged into the skill and reused by people with different
+machines, media, workflows, providers, brands, and output goals. Treat the
+repository as a general product, never as one person's customized clone.
+
+## Product principles
+
+- The delivered video is the product. Prioritize visual and audio quality,
+  editorial judgment, factual correctness, synchronization, pacing, and
+  production reliability.
+- Design reusable contracts and capabilities. Do not hardcode personal paths,
+  credentials, account ids, prompts, brands, preferences, or assumptions
+  about one project.
+- Keep provider-specific behavior behind narrow boundaries. Core EDL validation,
+  rendering, reframing, and QC must remain usable from the command line without
+  any optional client or remote runner.
+- Preserve backwards compatibility when practical. If a format must change,
+  provide a clear migration path and reject unsupported input with an actionable
+  error.
+- Never silently downgrade a requested feature. A missing source, track, model,
+  codec, or dependency should fail before expensive work begins and explain what
+  is required.
+- Defaults should be safe and broadly useful, while explicit project or user
+  requirements always win.
+- Keep credentials out of source, logs, fixtures, prompts, and generated
+  artifacts. Configuration belongs in environment variables or provider secret
+  stores.
+
+## Architecture boundaries
+
+- `SKILL.md` defines the agent workflow and public editing contract.
+- `helpers/` contains provider-independent production tools and validation.
+- `skills/` contains focused companion skills and reusable production assets.
+- `tests/` protects public behavior. Optional clients or remote runners may
+  orchestrate core features but must never become the only place a feature
+  exists.
+
+Keep decision data explicit in portable project files such as `edit/edl.json`.
+Renderers should consume declared inputs deterministically. UI state, agent
+history, and cloud runtime state must not be required to reproduce an output.
+
+## Change workflow
+
+1. Identify whether a change belongs to the public editing contract, a reusable
+   helper, a focused skill, or an optional adapter.
+2. Implement the smallest complete general capability at the lowest reusable
+   layer. Wire adapters to that capability instead of duplicating it.
+3. Validate inputs locally before uploads or paid compute. Validate again at
+   remote execution boundaries.
+4. Add tests for successful use, invalid input, backwards compatibility, and
+   provider-boundary behavior where relevant.
+5. For render changes, create representative media and inspect the encoded
+   dimensions, duration, frame rate, visual framing, and audible output.
+6. Update the public EDL example or usage documentation whenever users or agents
+   need to author a new field.
+
+Cost and latency are secondary unless the user sets a budget or deadline. Improve
+them only when output quality and reliability remain equal or improve.
+
+## Communication and commits
+
+After code changes, summarize the affected files, the functions or contracts
+added, and what each does in plain language. Keep this technical context compact
+so someone can learn an unfamiliar codebase without reading every diff.
+
+Write simple, readable commit messages. Prefer short lowercase wording without
+punctuation.
+
+## Branch discipline
+
+Several agents work on this repository at once. To keep one agent's progress
+from being overwritten by another:
+
+- One feature per branch, one agent per branch. Never edit a worktree that
+  belongs to another branch; take files from a commit or tag instead.
+- Commit early. Uncommitted work in a worktree has no merge base and no
+  history, so a later sync silently discards it.
+- Hard rules in `SKILL.md` are append-only. New rules get the next number.
+  Removing or renumbering a rule requires an explicit reason in the commit.
+- Procedure prose belongs in `references/<feature>.md` at the repository root;
+  create that folder with the first reference file. Edits to `SKILL.md`
+  are limited to rules, helper-index bullets, directory-tree lines, the EDL
+  example, and one-line pointers to the reference files.
+- `tests/test_skill_contract.py` checks that the rules and every referenced
+  path still exist. Run it before committing a `SKILL.md` change.

README.md

@@ -16,9 +16,12 @@ Try video-use in [Browser Use Cloud](https://cloud.browser-use.com/v4?utm_campai
 - **Auto color grades** every segment (warm cinematic, neutral punch, or any custom ffmpeg chain)
 - **30ms audio fades** at every cut so you never hear a pop
 - **Burns subtitles** in your style — 2-word UPPERCASE chunks by default, fully customizable
-- **Generates animation overlays** via [HyperFrames](https://github.com/heygen-com/hyperframes), [Remotion](https://www.remotion.dev/), [Manim](https://www.manim.community/), or PIL — spawned in parallel sub-agents, one per animation
+- **Generates animation and illustration overlays** via [HyperFrames](https://github.com/heygen-com/hyperframes), [Remotion](https://www.remotion.dev/), [Manim](https://www.manim.community/), [Penrose](https://penrose.cs.cmu.edu/), [CeTZ](https://typst.app/universe/package/cetz), or PIL — chosen per visual beat
 - **Self-evaluates the rendered output** at every cut boundary before showing you anything
 - **Persists session memory** in `project.md` so next week's session picks up where you left off
+- **Renders every delivery format from one edit** — 16:9 and 9:16 with per-format loudness targets and keyframed reframing, validated before any render starts
+- **Finds real footage for explainers** — searches public video, inspects exact moments, records provenance, and places footage in split or picture-in-picture compositions that never cover captions
+- **Checks generated layouts** — text and component collisions fail the render before you see it
 
 ## Setup prompt
 
@@ -45,7 +48,7 @@ And in the session:
 
 > edit these into a launch video
 
-It inventories the sources, proposes a strategy, waits for your OK, then produces `edit/final.mp4` next to your sources. All outputs live in `<videos_dir>/edit/` — the skill directory stays clean.
+It inventories the sources, proposes a strategy, waits for your OK, then produces `edit/final.mp4` next to your sources. Ask for an explainer on a topic with no footage at all and it writes narration, builds the visuals, and captions them from the spoken words. All outputs live in `<videos_dir>/edit/` — the skill directory stays clean.
 
 ## Manual install
 
@@ -61,7 +64,9 @@ ln -sfn ~/Developer/video-use ~/.claude/skills/video-use        # Claude Code
 cd ~/Developer/video-use
 uv sync                         # or: pip install -e .
 brew install ffmpeg             # required
+brew install ffmpeg-full        # caption burn-in needs libass
 brew install yt-dlp             # optional, for downloading online sources
+brew install typst              # optional, CeTZ illustrations
 
 # 3. Add your ElevenLabs API key
 cp .env.example .env
@@ -107,6 +112,6 @@ The self-eval loop runs `timeline_view` on the _rendered output_ at every cut bo
 2. **Audio is primary, visuals follow.** Cuts come from speech boundaries and silence gaps.
 3. **Ask → confirm → execute → self-eval → persist.** Never touch the cut without strategy approval.
 4. **Zero assumptions about content type.** Look, ask, then edit.
-5. **12 hard rules, artistic freedom elsewhere.** Production-correctness is non-negotiable. Taste isn't.
+5. **14 hard rules, artistic freedom elsewhere.** Production-correctness is non-negotiable. Taste isn't.
 
 See [`SKILL.md`](./SKILL.md) for the full production rules and editing craft.