@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/docs/SCRIPT.md

@@ -44,6 +44,200 @@ whether it needs a real capture or an honest `dom-demo`. Don't write a
 claim the decision tree can't resolve to something real or
 explicitly-labeled-constructed.
 
+## Tone
+
+The claim-obligates-visual rule and the direct, confident voice above are non-negotiable
+in every tone. Tone changes energy and pacing, never honesty.
+
+- **default.** Direct, confident, plain. The baseline above with nothing added.
+- **release.** Terser still. Built for a changelog/what's-new cut: lead with the change,
+  name the beat that shows it, skip framing sentences like "here's what's new."
+- **walkthrough.** Slower, more explanatory. Full sentences, a beat's VO may explain why a
+  step matters, not just name it. For a docs/tutorial video where the viewer is following
+  along, not skimming.
+- **quiet.** Understated, almost dry. Short sentences, no adjectives doing marketing work
+  ("powerful", "seamless"), let the visual carry the excitement. Fits an audience that
+  already trusts the product and wants the facts.
+
+State the tone once at the top of a video's brief if it isn't `default`, so every beat's
+VO is written in the same register rather than drifting line to line.
+
+## Music-only videos (no narration)
+
+`beats.json` can carry a top-level `narration`:
+
+```json
+{ "narration": "none", "beats": [ ... ] }
+```
+
+Omit it and `"voice"` is assumed, matching every `beats.json` written before this existed:
+every beat needs `vo`, held to the pace budget above.
+
+Under `"none"`, `vo` is optional on every beat and, if present at all, is not held to that
+budget: nothing is going to speak it. A beat can instead carry `onScreenText`, checked
+against a reading-time budget instead of a spoken one:
+
+```
+duration_seconds >= (onScreenText word count / 3.5) + 0.8
+```
+
+3.5 words/sec is a faster ceiling than the spoken 2.3-2.9 range on purpose: a viewer reads
+faster than a narrator speaks, and the fixed 0.8s covers a card's own entrance. `onScreenText`
+is optional too: a beat can be pure visual-plus-music with nothing to read at all.
+
+`stitch_composition`'s `musicBed` defaults its volume to 1.0 (full level) when narration is
+`"none"`, instead of the 0.18 tuned for sitting quietly under a voice.
+
+## Lesson scripts (Supernova mode)
+
+A lesson video (production mode `"supernova"`, see PIPELINE.md) is won or lost on its script, and the
+visuals illustrate it. These rules are for a lesson, in addition to the pacing above (which still
+applies: 2.3 to 2.9 words per second, checked by `validate_beats`). `check_script` lints them.
+
+A lesson explains **one concept in up to two minutes**, and every lesson has the same shape so a viewer
+knows what is coming. A series (a channel, a course) keeps that shape constant; only the content changes.
+There are two shapes, chosen by the concept card's `arc`: `"seven-beat"` (the default, below) and `"story"`
+([the story arc](#the-story-arc)). A card without `arc` is a seven-beat lesson and is checked exactly as before.
+
+Start from a **concept card**, `src/videos/<name>/concept.json`:
+
+```json
+{
+  "goal": "explain why a projectile is two independent motions, and use that to find its range",
+  "terms": ["projectile", "components"],
+  "example": "a ball launched at 20 m/s at 30 degrees, with g = 9.81 m/s squared: it lands 35.3 m away",
+  "reference": "Physics A.1 Kinematics",
+  "referenceSpoken": "physics, topic A one, kinematics",
+  "maxSeconds": 120
+}
+```
+
+The goal is what the viewer can do afterwards, the terms are the two or three that need defining, and the
+example is the one thing the whole lesson keeps coming back to, with its real numbers. `reference` is
+where the lesson sits (a syllabus chapter code, "Part 2 of 4"), as it is written on screen, and
+`referenceSpoken` is how it is said; both are optional, and when they are set the opening beat has to say
+it. `maxSeconds` is the length budget and defaults to 120. Get the script approved before any scene is built.
+
+### The arc
+
+Seven beats, in this order. A beat can take more than one scene, and a lesson that has nothing to derive
+(a definition, a classification) replaces the derive beat with a second picture, but never reorders
+the others. The times are for a 120 second lesson; shrink them in proportion for a shorter one.
+
+| # | Beat | What it does | About |
+|---|---|---|---|
+| 1 | Hook | A question or a surprising fact a beginner can feel, in the first sentence. Then say where the lesson sits: the `referenceSpoken` | 10 s |
+| 2 | Picture | The diagram starts here, before any formula. Say what the viewer is looking at in everyday words, and define each new term at first use | 20 s |
+| 3 | Set up | Name the quantities with their symbols and units, and state the assumptions ("no air resistance", "level ground"). Label them on the diagram | 15 s |
+| 4 | Derive | Build the formula line by line from things the viewer has already accepted. One `Derivation` with a step per line, each with its `spoken` form (and a `because`), and say why each step is allowed | 35 s |
+| 5 | Use it | One worked example with the real numbers and their units | 20 s |
+| 6 | Aha | The result that generalises or surprises, and where it stops being true (the assumption that breaks) | 10 s |
+| 7 | Close | A one-line recap, then the check question. End on the question and let the last frame hold | 10 s |
+
+About 270 to 330 words fit (2.3 to 2.9 words per second on plain prose; maths-heavy lines are read slower,
+nearer 2.2). The viewer should never wait more than about 8 seconds without something on screen changing,
+and the diagram's first element is on screen inside the first 15 seconds. `validate_scenes` with `render: true` checks both
+from the frames it samples: `diagram-late` (the first frame with anything drawn beyond the background and the captions:
+a warning after 15 s, an error after 25 s) and `static-stretch` (frames that do not change, captions aside, for more
+than 8 s: a warning). The thresholds are the options `diagramWarnSeconds`, `diagramErrorSeconds` and `staticSeconds`.
+A caption box marked `data-ovs-captions` (`LessonCaptions` does it) is the part ignored; otherwise the bottom 22 percent.
+
+### The story arc
+
+`"arc": "story"` is the story-first lesson. It is not the seven-beat arc: it opens on a real situation told as a
+problem, and it ends on a practice question the viewer answers in the comments. Six beats, in this order:
+
+| # | Beat | What it does |
+|---|---|---|
+| 1 | Situation | A real scene told as a problem (the `situation`), in the first beat |
+| 2 | The idea | The narrator (`character`) explains the idea in everyday words, terms defined at first use |
+| 3 | The formulas | The key formulas stated on screen, each said as its `spoken` form, in the card's order |
+| 4 | Apply | The formulas applied to the story's own numbers |
+| 5 | Watch out | One short "watch out": the common mistake or the assumption that breaks |
+| 6 | Practice | The original practice question, with a prompt to answer in the comments. End on the question |
+
+The extra card fields, all optional and only read for the story arc:
+
+```json
+{
+  "goal": "find what a jar of money grows to with compound interest",
+  "terms": ["interest"],
+  "example": "1000 rupees at five percent for three years",
+  "arc": "story",
+  "situation": "Maya saves money in a jar at the market",
+  "character": "Pixel",
+  "formulas": [
+    { "tex": "A = P(1+r)^n", "spoken": "A equals P times one plus r to the power n", "source": "IB data booklet" }
+  ],
+  "practiceQuestion": "How much is in a jar after three years at five percent?",
+  "answer": "1157.63"
+}
+```
+
+`formulas` are listed in the order they are stated: `tex` is what is on screen, `spoken` how it is said, `source`
+where it comes from. The pacing rules, sentence length, reading level, terms, `maxSeconds` and `reference` apply to
+both arcs. The story arc does not count beats: the six are the shape, not a limit, and a beat may take more than one
+scene. Its checks, in `check_script`, replace the seven-beat arc's closing-question check and the hook's "question or a
+number" warning (the "in this video" error stays):
+
+- `story-situation` (error): the first beat shares at least two content words with `situation` (all of them if the
+  situation has fewer). A warning if the card has no `situation`.
+- `story-formula` (error): each `formulas[].spoken` is in the narration, and in the order given. It is matched like an
+  `Equation`'s `spoken` string, ignoring case and punctuation; the formulas may fall in different beats.
+- `story-practice` (error): the last beat ends with the `practiceQuestion` (it need not be a question mark). A warning
+  if the card has no `practiceQuestion`.
+- `story-comment` (error): the last beat contains a prompt that matches `/comment/i`.
+- `story-subscribe` (warning): a beat says "like and subscribe".
+- `story-answer` (warning): the `answer` is in the narration. It is withheld until the pinned comment.
+
+For a story lesson `write_description` puts the practice question and "Drop your answer in the comments." in the
+description and writes the answer to `output/<name>-ANSWER.md`, the pinned comment (a line of working comes from an
+optional card field `answerWorking`). The config's `disclaimers` array is appended, each line once, at the end of
+every lesson description. See [SUPERNOVA.md](SUPERNOVA.md#the-description).
+
+### Rules
+
+1. **Hook in the first sentence**: a question or a surprising fact, with a number if there is one. Never
+   "in this video".
+2. **Say where it sits** in the first beat, if the card has a `reference`.
+3. **Intuition and a concrete example before any formula.** The formula arrives as a shortcut for
+   something the viewer already sees.
+4. **Define every term in plain words at first use** ("a slope is how steep a line is"), at most two new
+   terms in a beat.
+5. **One idea per beat. Sentences of about 14 words or fewer**, in spoken English, at about grade 8 or
+   below. A lesson is heard once.
+6. **Write maths as it is spoken.** Each `Equation` carries a `spoken` string ("x squared plus one") that
+   must appear in the narration of its beat.
+7. **Derive, do not announce.** A derivation shows each step: what is assumed, what is substituted, what
+   cancels. "It can be shown that" is not a derivation. If a step cannot fit in the time, it is a
+   Part 2, not a faster voice.
+8. **End with a one-line recap, then a check question** the viewer can answer in their head. The last
+   beat ends with a question mark.
+
+### Correctness
+
+The linter counts and matches; it cannot tell that a formula is right. Before a script is approved:
+
+- Write the derivation in a file next to the script (`derivation.md`), one line per step with its reason.
+- Check every step and every number on screen with code (plain Python or sympy), not by hand: the
+  symbolic result, the worked example, and the units (does the result have the dimensions it should?).
+- Compute the numbers a scene shows from the same code that checked them, rather than typing them twice.
+- Name the assumptions and one place the result fails.
+- Have someone who knows the subject read the derivation and the script before a scene is built.
+
+### What `check_script` reports
+
+Each finding points at a beat: average sentence length (warning above 16 words), Flesch-Kincaid reading
+level (warning above grade 9), a term used with no definition beside it (note), more than two new terms in
+a beat (warning), an `Equation`'s `spoken` string missing from the narration (error), a hook that is not a
+question or does not hold a number (warning) or opens "in this video" (error), pace against the beat length
+(error, the same budget as `validate_beats`), a last beat that does not end with a question (error), the
+whole lesson running over `maxSeconds` (error), and a card `reference` that the first beat does not say
+(error; a warning when `referenceSpoken` is missing, because then it cannot be checked). It counts and
+matches; it cannot tell you the explanation is good or the derivation is correct, so listen to it, and
+check the maths as above. For `"arc": "story"` it adds the six `story-*` checks listed under [the story
+arc](#the-story-arc) and leaves out the closing-question check.
+
 ## No em dashes
 
 No em dashes in any VO line, ever, same writing rule as every other doc in

package/docs/STYLE.md

@@ -6,13 +6,18 @@ a rule here, it fails QC.
 ## What good cinematography for this pipeline looks like (decoded)
 
 1. **Camera lives INSIDE the UI.** Never show a flat full-screen
-   screenshot. The camera is always zoomed into a region (120-250% scale),
-   slightly tilted (1-4 degrees rotateZ, 2-8 degrees rotateX/Y
-   perspective), and moving (push-in, drift, pan). UI is rendered oversized
-   on a stage; the camera crops into it.
-2. **Shallow depth of field.** One focal plane per shot. Everything else
-   (background layers, edge regions, sidebars) carries gaussian blur.
-   Focus can rack between layers mid-shot.
+   screenshot. The camera is always zoomed into a region (105-160% scale
+   on a capture with text; constructed panels with nothing to read can go
+   further), slightly tilted (1-4 degrees rotateZ, 2-8 degrees rotateX/Y
+   perspective), and moving (push-in, drift, pan). Past 160% the product
+   text goes soft. UI is rendered oversized on a stage; the camera crops
+   into it.
+2. **Depth without blur.** One focal plane per shot. Depth comes from
+   parallax (`Layer` depth, `LayeredShot`), a slight tilt and handheld
+   sway, not from smearing the frame. Blur is opt-in (`depthOfField`
+   defaults to 0), is never applied to text the viewer has to read (list
+   those regions in `protect`), and stays under about 4px when used.
+   Focus can still rack from one point to another mid-shot (`rackTo`).
 3. **Low-key lighting.** Dark scenes: deep vignette, soft glow accents on
    the key element (accent-colored text-shadow/box-shadow). Light scenes:
    soft large-radius drop shadows, floating cards, generous negative
@@ -27,8 +32,37 @@ a rule here, it fails QC.
 7. **Motion never stops.** Every shot has at least a subtle push-in (2-5%
    scale over the shot). Static frame = dead frame = QC fail.
 
+## Non-negotiables, and strong defaults
+
+This file has two kinds of rule.
+
+**Non-negotiable.** No brief overrides these, at any creative level:
+
+- Product UI and product text on screen come only from real captures or real tool output;
+  anything constructed is clearly non-product or disclosed. AI-generated clips never show
+  product UI. (A Supernova lesson has no product behind it, so everything in it is constructed on
+  purpose and the per-shot disclosure is replaced by one line in the description: the video is a
+  constructed explanation, not footage.)
+- Every claim in on-screen text or narration is backed by something shown in the same beat or an
+  adjacent one.
+- No em dashes on screen or in narration.
+- The quality gates pass before the final render: nothing cropped or outside the safe area, text
+  at or above the minimum size and on screen long enough to read, no dead frames (unless the brief
+  marks the hold as deliberate), contrast passing, loudness on target.
+- The user approves the brief and the beats before anything is written or rendered.
+
+**Strong defaults.** Everything else below (a camera that always moves, no linear easing, grain
+and vignette, the palette and type, cut rhythm, the SFX map) is how a video made with this
+pipeline looks unless the brief says otherwise. The brief may override any of them with a stated
+reason, recorded in its `styleOverrides` (`{ rule, reason }`), so the departure is a decision
+someone made and not an accident. At literal level, or without a brief, the defaults stand.
+
 ## Hard rules
 
+The rules in this section are the ones most often broken. They are QC failures. The provenance
+rule and the no-em-dash rule are non-negotiable; for the others, a brief may record an override
+with a reason.
+
 - NO linear easing. Ever. Use `@openvidstudio/core`'s `E.*` presets
   (cinematic bezier / springs).
 - Every scene wrapped in `CinematicScene` (grain + vignette + grade always
@@ -71,11 +105,42 @@ a rule here, it fails QC.
   #3ECF8E. Warn: #F5A623.
 - Light scenes: bg #F4F6F9, cards #FFFFFF, shadow rgba(15,23,42,0.12)
   large radius.
-- Fonts: Inter (UI), JetBrains Mono (terminal/code) via
-  `@remotion/google-fonts`.
+- Fonts: Inter (UI), JetBrains Mono (terminal/code), bundled locally (see
+  `packages/core/src/localFonts.ts`) rather than fetched from Google Fonts at render
+  time, so a render with no network access still gets the real glyphs.
 - Grain: 4-6% opacity, animated (re-seeded translate per frame). Vignette:
   25-40% edge darkening.
 
+## The hook
+
+The first 2 seconds decide whether anyone watches the rest. Plan the hook beat before any
+other beat, not last. It must be built from a real capture or a labeled `dom-demo`, same
+as every other beat: an exciting hook that overclaims fails the claim-obligates-visual
+rule (`SCRIPT.md`) just as much as a boring one would.
+
+No generic SaaS language anywhere in VO or on-screen text: "streamline your workflow,"
+"powerful," "seamless," "unlock." Use the product's own copy and claims instead. If the
+product's README doesn't say it that way, the video shouldn't either.
+
+## Beat-locked cuts
+
+When a video's music bed is a `compose_score` track (or any other track `plan_music_cues`
+has a grid for), scene cuts can land on the beat instead of at an arbitrary second. Read
+the `<stem>.cues.json` next to a composed track, or call `plan_music_cues` for any other
+track, before writing `beats.json`'s `start` values.
+
+- `strongCues` are the sparse, strong moments (bar downbeats for a composed score). Snap a
+  handful of major reveals here: a hard cut into a new scene, a hero reveal, the outro
+  logo landing. Shift the reveal's start to within about 0.15s of the nearest strong cue.
+- `beats` is the full beat grid. Snap sequential reveals here: cards or stats arriving one
+  after another, a list filling in. Snap each to within about 0.10s of a consecutive beat.
+- Lock at most a handful of moments per video, not every cut. A video where everything
+  is beat-locked reads as rigid, not musical.
+- Readability outranks the grid. If snapping to a cue would cut off a line of text before
+  it's readable, use the natural timing instead and skip that lock.
+- Mark a locked cut in the brief so a later edit doesn't silently drift off the beat:
+  `// beat-locked: 12.86s`.
+
 ## Deferred (do not attempt in pure Remotion)
 
 - Live-action beats (desk/keyboard shots, ambient texture): text-free, so

package/docs/SUPERNOVA.md

@@ -0,0 +1,191 @@
+# SUPERNOVA.md: short animated lessons
+
+Supernova is openvidstudio's second kind of production: a STEM concept explained in up to two minutes, vertical
+(1080x1920), narrated and captioned, with a script first and pictures that illustrate it. It is a production
+**mode** (`production.mode: "supernova"`), not a fourth creative level. The process is the `supernova` skill; the
+script rules are in [SCRIPT.md](SCRIPT.md); the primitives are in [API.md](API.md).
+
+Make a lesson project with `init_project` and `mode: "supernova"`. It stores the mode, defaults the frame to
+1080x1920, and installs `@openvidstudio/stem`, its display font and the maths renderer.
+
+## One concept in up to two minutes, a series for a big topic
+
+A lesson teaches one thing and takes **at most two minutes**. A big topic is a short series ("Part 2 of
+4") and each part ends on the question the next one answers. Every lesson has the same seven-beat shape
+(hook, picture, set up, derive, use it, aha, close), written out with times and rules in
+[SCRIPT.md](SCRIPT.md#the-arc), so a viewer, and a series, can rely on it.
+
+## The concept card
+
+`src/videos/<name>/concept.json`, next to `beats.json`. `check_script` reads it, and `validate_scenes` lets the
+numbers in its worked example appear on screen.
+
+```json
+{
+  "goal": "tell why a derivative is a slope",
+  "terms": ["slope", "derivative"],
+  "example": "a ball rolling down a hill, followed for one second",
+  "reference": "Calculus 5.1",
+  "referenceSpoken": "calculus, topic five point one",
+  "maxSeconds": 120
+}
+```
+
+`goal` is what the viewer can do afterwards, `terms` the two or three that need defining, `example` the one worked
+example the lesson keeps coming back to, with its real numbers. `reference` is where the lesson sits (a syllabus
+chapter, "Part 2 of 4"), `referenceSpoken` is how it is said, and the opening beat has to say it. Both are
+optional. `maxSeconds` is the length budget (default 120). A worked example, projectile motion:
+
+```json
+{
+  "goal": "work out how far and how high a launched ball goes, from its speed and angle",
+  "terms": ["projectile", "range"],
+  "example": "a ball launched at 20 m/s at 30 degrees, with g = 9.81 m/s squared: it flies for 2.04 s, lands 35.3 m away and peaks at 5.1 m",
+  "reference": "Kinematics, part 1 of 2",
+  "referenceSpoken": "kinematics, part one of two"
+}
+```
+
+Its script, in the shape SCRIPT.md asks for (each beat's duration comes from the measured voice, see
+NARRATION.md):
+
+| Beat | Narration |
+|---|---|
+| hook | How far does a thrown ball go? This is kinematics, part one of two. Throw it harder and it goes farther. But how much farther? |
+| picture | Picture a ball leaving your hand at an angle. A ball in flight like this is called a projectile. It rises, slows and falls. |
+| set-up | Say it leaves at a speed v and an angle theta. Ignore the air. Gravity pulls it down at g, and nothing pulls it sideways. |
+| derive | Split the launch in two. Sideways, x equals v cosine theta times t. Upward, y equals v sine theta times t, minus a half g t squared. It lands when y is zero again, at t equals two v sine theta over g. |
+| use-it | Use twenty metres a second at thirty degrees. That is two point oh four seconds in the air. The range is how far it lands: thirty-five point three metres. |
+| aha | Now change the angle. Forty-five degrees gives the longest range, and two angles that add to ninety land in the same spot. |
+| close | So: two separate motions, one steady, one pulled by gravity. At the very top of the path, what is the ball's acceleration? |
+
+This is a worked example of the format, not a lesson that has been built and listened to.
+
+A card can also set `"arc": "story"` for the story-first lesson, with `situation`, `character`, `formulas`,
+`practiceQuestion` and `answer`; see [SCRIPT.md](SCRIPT.md#the-story-arc).
+
+## Design: Void + Spark
+
+The idea: **light is meaning.** Everything is dark and flat except the one thing the viewer must look at.
+
+| Token | Value |
+|---|---|
+| Void | `#07060B`, panels `#0E0C16`, hairline grid at 5% white |
+| Text | warm white `#F3EFE6` (never pure white), dim `#8C8799` |
+| Math | blue giant `#5CC8FF` |
+| Physics | solar amber `#FFB347`, ember `#FF7A3D` |
+| CS | nebula violet `#B58CFF` |
+| Chemistry | red dwarf `#FF4D5E` |
+| Biology | aurora `#7CFFB2` |
+
+One accent per subject, so a profile grid of lessons reads as a spectrum. `supernovaDesignSystem(subject)` builds it:
+`export const design = supernovaDesignSystem("physics")`. The display face is Space Grotesk, the body face Inter, both from
+local files. Equations are in sans-serif maths (MathJax with the Fira font; the comparison with KaTeX is in API.md).
+
+**Glow budget: one glowing element at a time.** The Spark is one; a Nova's flash is one. `validate_scenes` (render
+mode) counts them: more than one is a warning, more than two an error, except in a beat that holds a Nova.
+
+## The primitives
+
+All in `@openvidstudio/stem`, documented with stills in [API.md](API.md#supernova-openvidstudiostem):
+
+- `Spark`: the pen, the pointer and the particle. Traces curves, carries a value along a function, orbits, splits,
+  falls under gravity, walks pointers through arrays.
+- `Nova`: the payoff, once per video, on the aha sentence. Silence, a three-frame flash, a shockwave ring, the result
+  condenses from particles.
+- `Axes`, `Plot`, `NumberLine`: graphs, tangents, shaded area, intervals.
+- `Equation`: sans-serif maths revealed term by term, with a required `spoken` form that must match the narration.
+- `Derivation`: the derive beat. A formula built line by line, each step with its `spoken` form and an optional `because`; the line before moves up and dims (a stack of three), terms that carry over stay put, new ones arrive in the accent, gone ones fade. Each step is revealed at the word it is spoken at, so `check_script` also reads its `spoken` strings and checks they are in the narration in order.
+- `LessonCaptions`: word-timed captions that break at sentence ends, in the Reels safe zone.
+- `FreeBody`: forces as arrows whose length is exactly magnitude times the scale shown.
+- `ArrayViz`: cells, named pointers, a lit range and a dimmed one, a Spark-driven pointer.
+- `useNarrationWords(beatId)` (in core): when each word of the narration is said, so the Spark can point at it.
+
+One idea on screen at a time, at most two things moving.
+
+## The voice
+
+One fixed voice for the handle, so a viewer knows it by ear and lessons can be made in any order.
+
+| | |
+|---|---|
+| Engine | `edge-tts` (fast, and it gives word timings). It sends the script text to Microsoft, which is fine for public lesson scripts. `preflight` speaks one word to check it works: Microsoft refused 7.2.8 with a 403 in October 2026, and `pip install -U edge-tts` fixes it |
+| Voice | `en-US-AndrewNeural` |
+| Rate | the engine's default, `+0%`. Pace comes from the script (2.3 to 2.9 words per second); the stretch is clamped to 0.9 to 1.12 so it never sounds processed |
+| Final pass | `omnivoice` gives better control but runs about 40 times slower than real time on a CPU: use it for a last pass, never to iterate |
+
+This is a proposal, the default voice of the engine, chosen so there is one. Changing it is a decision for the handle's
+owner, made once and for every lesson: pass the same `voice` to `generate_narration` each time.
+
+### Fit the beats to the voice
+
+The voice reads plain prose at about 3 words per second and number-heavy lines at about 2.2, so a word count
+alone mis-sizes a beat. Write the beats with provisional lengths, run `generate_narration`, then run `fit_beats`.
+It sets each beat to the measured spoken length plus half a second (`padSeconds`), clamps it into the 2.3 to 2.9
+words per second window `validate_beats` wants, rounds to whole frames, moves the later beats' starts, and never
+touches `vo`. A very short line ("Now the honest part.") ends up near 1.7 seconds. A beat it cannot fit, because the
+voice needs more than the window allows, is listed in `unfittable` with the words to cut or the frames to lengthen it to.
+Pass `dryRun: true` to see the lengths first, then run `generate_narration` again with `overwrite: true`.
+NARRATION.md has the clamp.
+
+## Captions
+
+Burn captions in for silent autoplay with `LessonCaptions`, one line in a scene:
+
+```tsx
+<LessonCaptions beatId="hook" text={vo} />   // vo is the beat's narration text
+```
+
+The word timings carry bare words with no punctuation, so the component takes the text from the beat's `vo` (split on
+spaces, it matches the timings one to one) and breaks a caption at a sentence end, at a comma after at least three
+words, and at `maxWords` (default 6), so a caption never runs one sentence into the next. The word being said is
+picked out in the subject's accent. If the text and the timings differ in length it falls back to the timings' bare
+words, and with no timings at all (an engine that gives none) it spreads the words evenly over the scene and says so
+in `data-ovs-captions-timing="estimated"`. It stays out of the Reels safe zones by default (above the bottom 22
+percent of a tall frame, below the top 14), works at 1920x1080, and its box is tagged `data-ovs-captions`, which
+`validate_scenes` ignores when it looks for a diagram or a static stretch. See API.md for the props.
+
+## Canvas explainers
+
+A lesson can also be an HTML canvas explainer (hand-drawn chalkboard, whiteboard, flat vector, a pixel-character look) turned
+into a video by `render_canvas_explainer`, with the same script gates: `beats.json` after `fit_beats` drives the beat times,
+the narration clips are mixed over the score, and the text is captioned. `validate_canvas_explainer` is its `validate_scenes`.
+See "Canvas explainers" in PIPELINE.md.
+
+Canvas explainers in a pixel style have a ready kit: `@openvidstudio/styles` has the recurring pixel narrator (idle, talk,
+point, think, celebrate), a small prop set, parallax, a perspective floor grid, fog and shadows, the accent per subject, a
+chip sound palette, and vertical 720x1280 layout helpers (`safeArea`, `fitText` with the role minimums, a caption band).
+It is plain 2D canvas and a pure function of `t`. Cropping a landscape layout to vertical is not offered: lay the lesson
+out vertically. See "Pixel narrator and depth kit" in [API.md](API.md#pixel-narrator-and-depth-kit-openvidstudiostyles).
+
+## Reels safe zones
+
+Instagram draws its own interface over a reel, so keep key content (text, the part of a diagram being explained) out of the
+top about 14% (270 px) and the bottom about 22% (420 px) of the 1080x1920 frame, and about 10% (108 px) off the right
+edge. `supernovaDesignSystem` sets its layout grid to exactly that (108 / 270 / 420).
+
+Checked against current guidance in October 2026: the top figure agrees with the one most sources cite (14%, about 269 px,
+from Meta's percentages for Reels ads). The bottom does not: sources give anywhere from about 340 px to 35% (672 px). The
+35% is for ads; 22% is a design choice for an organic reel and a minimum. If a lesson is also run as an ad, keep key content
+out of the bottom 35%. Meta publishes percentages, not pixels, and the interface changes, so look at a real upload before
+trusting any of these. Backgrounds can run to the edge; key content stays inside.
+
+## The description
+
+`write_description` writes `output/<name>-DESCRIPTION.md` for a lesson as for any video (chapters from the beats,
+credits, and one line saying the video is a constructed explanation, not footage). Two things come from the lesson's
+own files. If `concept.json` has a `practiceQuestion` and an `answer`, the description gets a "Practice question"
+section with the question and the line "Drop your answer in the comments.", and the answer is written to
+`output/<name>-ANSWER.md` instead, never into the description: the answer, and one line of working if the card has an
+optional `answerWorking`. Paste that file as the pinned comment. And the `disclaimers` array in
+`openvidstudio.config.json` (for example `["Constructed animation, not footage.", "Not affiliated with or endorsed by
+any exam board."]`) is appended, each line once, at the end of every lesson description. A project with none of these
+gets the same description as before. See [SCRIPT.md](SCRIPT.md#the-story-arc).
+
+## Checks
+
+`validate_beats` (pace), `check_script` (the script, the two-minute budget and the reference), `validate_scenes` with
+`render: true` (framing, numbers, glow, and the arc: `diagram-late` and `static-stretch`), a contact sheet, then listen. `finalize_video` must report no `audio-tick`. See
+the skill for the order. `render_video` skips its brand-lock gate on a Supernova project, because a lesson has no brand to
+extract, and says so in `brandLockSkipReason`.
+In a lesson `validate_scenes` leaves out the camera checks (keyframes, a camera that never moves): lesson scenes are flat on purpose.

package/docs/TOOLS.md

@@ -0,0 +1,55 @@
+# Tools
+
+GENERATED by `node scripts/generate-tool-docs.mjs` from the tools the server actually registers.
+Do not edit by hand: CI fails if this file is out of date. Each tool's own description (what it
+checks, what it returns, when to use it) is what an MCP client shows an agent; this page is the map.
+
+44 tools, 45 with the Higgsfield tier enabled.
+
+| Tool | What it does |
+| --- | --- |
+| `add_motion_primitive` | Copy a catalog motion primitive's source into the project. |
+| `capture_desktop` | Record a desktop application, window, or whole screen. |
+| `capture_mobile` | Record an Android device or iOS Simulator. |
+| `capture_screen_recording` | Capture a zoom-compensated, full-viewport screen recording. |
+| `capture_screenshot` | Capture a zoom-compensated, DOM-rect-cropped screenshot. |
+| `capture_terminal` | Record a real command run as timed, themeable text. |
+| `catalog_motion_primitives` | Search the motion primitives catalog. |
+| `check_script` | Lint a lesson script against its concept card. |
+| `collect_facts` | Merge a video's run records into facts.json. |
+| `compose_score` | Compose an original, arc-matched score. |
+| `contact_sheet` | Render one image showing every beat. |
+| `diff_beats` | Turn an edited beats.json draft into a per-beat rerun plan. |
+| `docs_drift` | Find the clips that no longer match the pages they document. |
+| `export_rendition` | Export the same beats as a GIF, a docs screenshot set, or store frames. |
+| `extract_brand` | Read a repo's own palette, fonts and logo, and theme the video with them. |
+| `finalize_video` | Final assembly: loudness target, poster frame, size-capped share copy. |
+| `find_music_bed` | Search public-domain music catalogs for a background track. |
+| `fit_beats` | Size the beats from the measured voice. |
+| `generate_narration` | Generate narration audio for every beat. |
+| `import_higgsfield_clip` | Import an already-generated Higgsfield clip into this project's asset convention. Only registered when `hasHiggsfield` is true in `openvidstudio.config.json`. |
+| `import_music_bed` | Download a CC0 track and shape it into a music bed. |
+| `init_project` | Initialize an openvidstudio project. |
+| `job_status` | Poll an async job's progress and result. |
+| `plan_beats` | Plan a beat skeleton with word budgets before writing narration. |
+| `plan_music_cues` | Detect or read beat and strong-cue timestamps for a music track. |
+| `plan_production` | Turn creative level + time budget into a concrete, time-estimated plan. |
+| `plan_shots` | Rank what a demo should show, from the repository's own emphasis. |
+| `plan_sound_effects` | Work out which sound effects are needed and where to get them. |
+| `preflight` | Check the machine can actually run the pipeline. |
+| `qc_capture` | Flag capture artifacts that are present but wrong. |
+| `qc_extract_frames` | Extract QC frames for every beat. |
+| `reformat_vertical` | Reformat a finished video to 9:16 using the manifest. |
+| `release_diff` | Two refs in, a what's-new clip's manifest out. |
+| `render_canvas_explainer` | Render an HTML canvas explainer to a video. |
+| `render_stills` | Render representative frames without a full video encode. |
+| `render_video` | Render a composition with the Remotion CLI. |
+| `scaffold_scene` | Scaffold a working scene for one beat. |
+| `stitch_composition` | Stitch a video's beats into a composition. |
+| `validate_beats` | Validate a drafted beats.json. |
+| `validate_canvas_explainer` | Check a canvas explainer for problems that render without erroring. |
+| `validate_scenes` | Check scenes for problems that render without erroring. |
+| `visual_regression` | Diff this render's beats against the last accepted one. |
+| `write_beats_file` | Write a validated beats.json to disk. |
+| `write_brief` | Write a validated creative brief (brief.md + brief.json) to disk. |
+| `write_description` | Write a video's description, with sample content disclosed. |