@openvidstudio/mcp-server 1.3.1 → 1.4.0

package/dist/tools/renderVideo.js

@@ -296,6 +296,8 @@ async function runIncrementalRender(input, ctx) {
         totalFrames,
     };
 }
+const SUPERNOVA_BRAND_LOCK_SKIP = "Brand-lock gate skipped: this is a supernova project, and a lesson has no brand to extract " +
+    "(its design is supernovaDesignSystem).";
 /**
  * The synchronous half of render_video: validate input and the brand-lock gate, throwing
  * immediately on anything wrong, before any real work (a render that will take 40+ minutes,
@@ -313,13 +315,14 @@ function prepareRenderVideo(input) {
     const outPathRel = input.outPath ?? path.join("output", `${videoName}.mp4`);
     (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
     const brandLocked = fs.existsSync(path.join(projectRoot, "src", "brand.ts"));
-    if (!brandLocked && input.skipBrandLock !== true) {
+    const brandLockSkipReason = !brandLocked && (0, config_1.productionMode)((0, config_1.loadConfig)(projectRoot)) === "supernova" ? SUPERNOVA_BRAND_LOCK_SKIP : undefined;
+    if (!brandLocked && input.skipBrandLock !== true && brandLockSkipReason === undefined) {
         throw new Error(`Brand-lock gate: no src/brand.ts found in this project. Run extract_brand with ` +
             `{ sourceRepo: "${projectRoot}" } before rendering. It writes src/brand.ts from the repo being filmed. ` +
             "If this project deliberately has no brand to extract, pass skipBrandLock: true.");
     }
     fs.mkdirSync(path.dirname(path.join(projectRoot, outPathRel)), { recursive: true });
-    return { videoName, projectRoot, compositionId, outPathRel, brandLocked };
+    return { videoName, projectRoot, compositionId, outPathRel, brandLocked, ...(brandLockSkipReason ? { brandLockSkipReason } : {}) };
 }
 /**
  * Records what this render actually did next to what was asked: which beats were rendered
@@ -349,7 +352,12 @@ async function runRenderVideo(input, opts = {}) {
     return result;
 }
 async function renderVideoUnrecorded(input, opts) {
-    const { videoName, projectRoot, compositionId, outPathRel, brandLocked } = prepareRenderVideo(input);
+    const prepared = prepareRenderVideo(input);
+    const result = await renderPrepared(input, opts, prepared);
+    return prepared.brandLockSkipReason ? { ...result, brandLockSkipReason: prepared.brandLockSkipReason } : result;
+}
+async function renderPrepared(input, opts, prepared) {
+    const { videoName, projectRoot, compositionId, outPathRel, brandLocked } = prepared;
     const started = Date.now();
     if (input.incremental === true) {
         return runIncrementalRender(input, {
@@ -404,7 +412,8 @@ function registerRenderVideo(server) {
             "to tell progress from a hang. BRAND-LOCK GATE: refuses to run unless src/brand.ts exists (written " +
             "by extract_brand), so a video never ships wearing openvidstudio's own default look by accident. " +
             "Run extract_brand against the repo being filmed first; pass skipBrandLock: true only when the " +
-            "project deliberately has no brand to extract. Returns the render's captured stdout/stderr, how " +
+            "project deliberately has no brand to extract. A supernova project (production.mode in " +
+            "openvidstudio.config.json) skips the gate on its own and says why in brandLockSkipReason. Returns the render's captured stdout/stderr, how " +
             "long it took, and brandLocked (whether src/brand.ts existed at render time). Pass incremental to render "
             + "each beat to its own cached segment under output/segments/<videoName>/ and concatenate them with "
             + "ffmpeg under stream copy, re-rendering only the beats whose inputs actually changed. A segment is "

package/dist/tools/validateBeats.d.ts

@@ -8,6 +8,8 @@ export interface ValidateBeatsResult {
      */
     warnings: string[];
 }
+export declare const MIN_PACE = 2.3;
+export declare const MAX_PACE = 2.9;
 /** SCRIPT.md's reading-time budget for onScreenText on a narration:"none" beat. */
 export declare const MAX_READING_WORDS_PER_SEC = 3.5;
 export declare const READING_OVERHEAD_SEC = 0.8;

package/dist/tools/validateBeats.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.READING_OVERHEAD_SEC = exports.MAX_READING_WORDS_PER_SEC = void 0;
+exports.READING_OVERHEAD_SEC = exports.MAX_READING_WORDS_PER_SEC = exports.MAX_PACE = exports.MIN_PACE = void 0;
 exports.wordCount = wordCount;
 exports.voPaceCheck = voPaceCheck;
 exports.validateBeatsLogic = validateBeatsLogic;
@@ -16,8 +16,8 @@ const EM_DASH = "—";
 const RHYTHM_MIN_BEATS = 4;
 /** The longest beat should be at least this many times the shortest, or the shots read as evenly spaced ticks. */
 const RHYTHM_MIN_SPREAD = 2.5;
-const MIN_PACE = 2.3;
-const MAX_PACE = 2.9;
+exports.MIN_PACE = 2.3;
+exports.MAX_PACE = 2.9;
 /** SCRIPT.md's reading-time budget for onScreenText on a narration:"none" beat. */
 exports.MAX_READING_WORDS_PER_SEC = 3.5;
 exports.READING_OVERHEAD_SEC = 0.8;
@@ -45,8 +45,8 @@ function wordCount(text) {
 function voPaceCheck(vo, seconds) {
     const words = wordCount(vo);
     const pace = words / seconds;
-    const message = pace < MIN_PACE || pace > MAX_PACE
-        ? `VO pace ${pace.toFixed(2)} words/sec is outside the ${MIN_PACE}-${MAX_PACE} words/sec ` +
+    const message = pace < exports.MIN_PACE || pace > exports.MAX_PACE
+        ? `VO pace ${pace.toFixed(2)} words/sec is outside the ${exports.MIN_PACE}-${exports.MAX_PACE} words/sec ` +
             `budget (${words} words over ${seconds.toFixed(2)}s, per SCRIPT.md)`
         : null;
     return { words, pace, message };

package/dist/tools/validateCanvasExplainer.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerValidateCanvasExplainer(server: McpServer): void;

package/dist/tools/validateCanvasExplainer.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerValidateCanvasExplainer = registerValidateCanvasExplainer;
+const zod_1 = require("zod");
+const canvasValidate_1 = require("../canvasValidate");
+const mcp_1 = require("./mcp");
+function registerValidateCanvasExplainer(server) {
+    server.registerTool("validate_canvas_explainer", {
+        title: "Check a canvas explainer for problems that render without erroring",
+        description: "What validate_scenes does for a Remotion composition, for a canvas explainer (see render_canvas_explainer). Loads the HTML " +
+            "in headless Chromium and samples frames through window.seek(t). Checks: purity, three times drawn twice with another time " +
+            "between, the frames must match (error); text size, by intercepting fillText and strokeText: labels 28px, headlines 44px and " +
+            "key numbers 64px at 720 on the shorter side, scaled to the canvas (warning below, error below half; captions drawn through " +
+            "window.CAPTIONS are exempt); safe areas, on a tall canvas no text in the top 14% or bottom 22% except captions (warning); the " +
+            "lesson arc through the same code as validate_scenes, the first frame with anything drawn beyond the background and the captions " +
+            "(diagram-late: warning after 15 s, error after 25 s) and any run of frames that do not change longer than 8 s " +
+            "(static-stretch, warning); the sound, by scheduling window.scoreSound into an offline context: the most source nodes " +
+            "playing at once (warning above 3) and the peak level (warning at clipping); and Math.random in the source (warning). " +
+            "Findings have validate_scenes' shape (beatId, scene, severity, check, message). Pass videoName to use the project's beats " +
+            "and captions as render_canvas_explainer does. Returns ok, the findings, the length, the smallest text size and the sound figures.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            htmlPath: zod_1.z.string().min(1),
+            width: zod_1.z.number().int().positive().optional().describe("Default 1280."),
+            height: zod_1.z.number().int().positive().optional().describe("Default 720. Use 720 wide by 1280 high for a Reel."),
+            fps: zod_1.z.number().positive().optional(),
+            videoName: zod_1.z.string().optional(),
+            audio: zod_1.z.boolean().optional().describe("Judge the sound too. Default true."),
+            textScale: zod_1.z.number().positive().optional().describe("Multiply the text minimums by this instead of min(width, height) / 720."),
+            diagramWarnSeconds: zod_1.z.number().positive().optional(),
+            diagramErrorSeconds: zod_1.z.number().positive().optional(),
+            staticSeconds: zod_1.z.number().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("validate_canvas_explainer", () => (0, canvasValidate_1.validateCanvasExplainer)(input)));
+}

package/dist/tools/validateScenes.d.ts

@@ -27,6 +27,12 @@ export interface ValidateScenesInput {
     compositionId?: string;
     /** With render: limit the measurement to these beats. Static checks always cover every beat. */
     beatIds?: string[];
+    /** Lessons, with render: warn when the first drawn element is later than this many seconds. Default 15. */
+    diagramWarnSeconds?: number;
+    /** Lessons, with render: an error when the first drawn element is later than this. Default 25. */
+    diagramErrorSeconds?: number;
+    /** Lessons, with render: warn when nothing changes for longer than this. Default 8. */
+    staticSeconds?: number;
 }
 export interface SceneFinding {
     beatId: string;

package/dist/tools/validateScenes.js

@@ -44,11 +44,19 @@ const path = __importStar(require("node:path"));
 const zod_1 = require("zod");
 const util_1 = require("../util");
 const config_1 = require("../config");
+const lessonArc_1 = require("../lessonArc");
 const capture_1 = require("@openvidstudio/capture");
 const mcp_1 = require("./mcp");
 const facts_1 = require("../facts");
 const renderStills_1 = require("./renderStills");
 const validateScenesRender_1 = require("./validateScenesRender");
+function arcThresholds(input) {
+    return {
+        diagramWarnSeconds: input.diagramWarnSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.diagramWarnSeconds,
+        diagramErrorSeconds: input.diagramErrorSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.diagramErrorSeconds,
+        staticSeconds: input.staticSeconds ?? lessonArc_1.DEFAULT_ARC_THRESHOLDS.staticSeconds,
+    };
+}
 /**
  * Reads the `<asset>.settle.json` sidecar capture_screenshot/capture_screen_recording
  * write next to their output (see @openvidstudio/capture's writeSettleSidecar) and
@@ -298,8 +306,9 @@ function staticPass(input) {
                 });
             }
         }
-        // Motion. A frozen frame is a QC fail in STYLE.md.
-        if (scales.length >= 2 && new Set(scales).size === 1) {
+        // Motion. A frozen frame is a QC fail in STYLE.md. A lesson scene is flat on purpose (a Void with a
+        // Spark, a graph, an equation) and need not use CinematicScene, so the camera checks are product-demo rules.
+        if (!lesson && scales.length >= 2 && new Set(scales).size === 1) {
             const positions = new Set([...src.matchAll(/\bx:\s*(\d+),\s*y:\s*(\d+)/g)].map((m) => `${m[1]},${m[2]}`));
             if (positions.size <= 1) {
                 findings.push({
@@ -310,7 +319,7 @@ function staticPass(input) {
                 });
             }
         }
-        if (scales.length < 2 && !usesSelfManagedCamera(src)) {
+        if (!lesson && scales.length < 2 && !usesSelfManagedCamera(src)) {
             findings.push({
                 beatId: beat.id,
                 scene: `${component}.tsx`,
@@ -411,6 +420,7 @@ async function runValidateScenesFull(input) {
     const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
     const videoDir = path.join(projectRoot, "src", "videos", videoName);
     const doc = JSON.parse(fs.readFileSync(path.join(videoDir, "beats.json"), "utf8"));
+    const lesson = isLesson(projectRoot, doc);
     let beats = doc.beats;
     if (input.beatIds && input.beatIds.length > 0) {
         const known = new Set(beats.map((b) => b.id));
@@ -429,7 +439,10 @@ async function runValidateScenesFull(input) {
         fps: doc.fps ?? 30,
         minimums: (0, validateScenesRender_1.readTypeMinimums)(videoDir),
         deliberateHolds: (0, validateScenesRender_1.readDeliberateHolds)(videoDir),
-        glowBudget: isLesson(projectRoot, doc),
+        glowBudget: lesson,
+        // The arc is about the whole lesson, so a run over a few beats (beatIds) does not judge it.
+        arc: lesson && beats.length === doc.beats.length ? arcThresholds(input) : undefined,
+        lessonSeconds: Math.max(0, ...doc.beats.map((b) => b.start + b.duration)) / (doc.fps ?? 30),
     });
     const findings = [...result.findings, ...rendered.findings];
     const full = {
@@ -467,11 +480,16 @@ function registerValidateScenes(server) {
             "needs longer to read than the beat lasts (3.5 words/sec plus 0.8s, the same budget validate_beats " +
             "applies), beats whose frames never change, em dashes in on-screen copy, text colour against the " +
             "pixels rendered behind it (WCAG 4.5:1, 3:1 for large text), text outside the title-safe area, and " +
-            "scene text that overlaps the chapter HUD. In a Supernova lesson (production mode supernova) two checks change: " +
+            "scene text that overlaps the chapter HUD. In a Supernova lesson (production mode supernova) the camera warnings (fewer than two keyframes, a camera that never moves) are dropped, " +
+            "and two checks change: " +
             "a number typed into a scene passes when the concept card's worked example (concept.json) or an Equation's tex " +
             "has it, and one that appears nowhere is still flagged, and render mode also counts the glowing elements in " +
             "sampled frames (Void + Spark allows one at a time): more than one is a warning, more than two an error, " +
-            "except in a beat that holds a Nova. Needs stitch_composition to have run. A beat that cannot be mounted (a screen " +
+            "except in a beat that holds a Nova. Render mode in a lesson also judges its arc from the frames it " +
+            "already samples (and only when every beat is measured): diagram-late, the first sampled frame with anything " +
+            "drawn beyond the background and the captions (a warning after 15 s, an error after 25 s), and static-stretch, " +
+            "a run of sampled frames that do not change, captions aside, for more than 8 s (a warning). The thresholds are " +
+            "the options diagramWarnSeconds, diagramErrorSeconds and staticSeconds. Needs stitch_composition to have run. A beat that cannot be mounted (a screen " +
             "recording played through OffthreadVideo) is reported as render-skipped, never as clean.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),
@@ -479,6 +497,9 @@ function registerValidateScenes(server) {
             render: zod_1.z.boolean().optional(),
             compositionId: zod_1.z.string().optional(),
             beatIds: zod_1.z.array(zod_1.z.string()).optional(),
+            diagramWarnSeconds: zod_1.z.number().positive().optional().describe("Lessons, render mode: warn when the first drawn element is later than this (default 15)."),
+            diagramErrorSeconds: zod_1.z.number().positive().optional().describe("Lessons, render mode: error when the first drawn element is later than this (default 25)."),
+            staticSeconds: zod_1.z.number().positive().optional().describe("Lessons, render mode: warn when nothing changes for longer than this (default 8)."),
         },
     }, async (input) => (0, mcp_1.runTool)("validate_scenes", () => runValidateScenesFull(input)));
 }

package/dist/tools/validateScenesRender.d.ts

@@ -1,3 +1,4 @@
+import { type ArcThresholds } from "../lessonArc";
 import type { SceneFinding } from "./validateScenes";
 import { MAX_READING_WORDS_PER_SEC, READING_OVERHEAD_SEC } from "./validateBeats";
 /**
@@ -71,6 +72,13 @@ export interface RenderCheckInput {
     deliberateHolds?: string[];
     /** Count the glowing elements in each sampled frame against Supernova's one-at-a-time budget. Lessons only. */
     glowBudget?: boolean;
+    /**
+     * Judge the lesson arc (the diagram inside the first seconds, no long static stretch) from the frames sampled
+     * here, with these thresholds. Lessons only, and only when every beat of the lesson is measured.
+     */
+    arc?: ArcThresholds;
+    /** The lesson's length in seconds, which bounds a static stretch that runs to the end. */
+    lessonSeconds?: number;
 }
 export interface RenderCheckResult {
     findings: SceneFinding[];

package/dist/tools/validateScenesRender.js

@@ -54,6 +54,7 @@ const capture_1 = require("@openvidstudio/capture");
 const remotionBridge_1 = require("../remotionBridge");
 const sharp_1 = __importDefault(require("sharp"));
 const frameDiff_1 = require("../frameDiff");
+const lessonArc_1 = require("../lessonArc");
 const util_1 = require("../util");
 const validateBeats_1 = require("./validateBeats");
 Object.defineProperty(exports, "MAX_READING_WORDS_PER_SEC", { enumerable: true, get: function () { return validateBeats_1.MAX_READING_WORDS_PER_SEC; } });
@@ -623,6 +624,13 @@ function judgeGlow(beat, samples, frames) {
         },
     ];
 }
+/** Runs in the page: the boxes of the lesson's captions (LessonCaptions marks them), in frame pixels. */
+function probeCaptionBoxes() {
+    return Array.from(document.querySelectorAll("[data-ovs-captions]")).map((el) => {
+        const r = el.getBoundingClientRect();
+        return { x: r.x, y: r.y, width: r.width, height: r.height };
+    });
+}
 function sampleFrames(beat) {
     const last = Math.max(0, beat.duration - 1);
     const frames = SAMPLE_FRACTIONS.map((f) => beat.start + Math.min(last, Math.round(beat.duration * f)));
@@ -645,6 +653,8 @@ async function runRenderChecks(input) {
     // Largest share of each brand colour seen in any sampled frame, for the palette check.
     const brandColors = brandHexColors(input.projectRoot);
     const brandSeen = new Map(brandColors.map((c) => [c, 0]));
+    const arcSamples = [];
+    let arcPrevious = null;
     try {
         const composition = await (0, remotionBridge_1.resolveComposition)(bundleDir, input.compositionId, remotionBrowser);
         browser = await (0, capture_1.launchChromium)();
@@ -682,6 +692,11 @@ async function runRenderChecks(input) {
                     const shot = path.join(scratch, `${beat.id}-${i}.png`);
                     await page.screenshot({ path: shot });
                     shots.push(shot);
+                    if (input.arc) {
+                        const arc = await (0, lessonArc_1.measureArcFrame)(shot, await page.evaluate(probeCaptionBoxes), arcPrevious);
+                        arcPrevious = arc.signature;
+                        arcSamples.push({ time: frame / input.fps, beatId: beat.id, drawn: arc.drawn, changedFromPrevious: arc.changedFromPrevious });
+                    }
                     const shares = await measureFrame(shot, probes, brandColors);
                     for (const [hex, share] of shares)
                         brandSeen.set(hex, Math.max(brandSeen.get(hex) ?? 0, share));
@@ -720,6 +735,7 @@ async function runRenderChecks(input) {
                     severity: "warning",
                     message: `Render-based checks could not run for this beat, so it was NOT measured: ${skipped[skipped.length - 1].reason}`,
                 });
+                arcPrevious = null;
                 // The page may be wedged mid-mount; the next beat gets a fresh one.
                 await page?.close().catch(() => undefined);
                 page = null;
@@ -730,6 +746,21 @@ async function runRenderChecks(input) {
         // no frame to find the palette in, and saying it is missing would be a false alarm.
         if (measured > 0)
             findings.push(...judgeBrandPalette(brandSeen));
+        // A lesson that skipped a beat has a hole in its samples, and a hole reads as a static stretch or a late
+        // diagram that may not be there. Judged only when every beat was measured.
+        if (input.arc && measured === input.beats.length && measured > 0) {
+            const lessonSeconds = input.lessonSeconds ?? Math.max(...input.beats.map((b) => b.start + b.duration)) / input.fps;
+            for (const f of (0, lessonArc_1.judgeLessonArc)(arcSamples, lessonSeconds, input.arc)) {
+                findings.push({
+                    beatId: f.beatId,
+                    scene: f.beatId === "*" ? "beats.json" : `${(0, util_1.pascalCase)(f.beatId)}.tsx`,
+                    source: "render",
+                    check: f.check,
+                    severity: f.severity,
+                    message: f.message,
+                });
+            }
+        }
     }
     finally {
         await browser?.close().catch(() => undefined);

package/dist/tools/writeDescription.d.ts

@@ -12,6 +12,12 @@ export interface WriteDescriptionResult {
     chapters: string[];
     /** Credit lines written, so a caller can show them without re-reading the file. */
     credits: string[];
+    /** Lesson with a practiceQuestion and an answer: the ANSWER.md written next to the description (the pinned comment). Absent otherwise. */
+    answerPath?: string;
+    /** Lesson with a practiceQuestion and an answer: the question put in the description. Absent otherwise. */
+    practiceQuestion?: string;
+    /** The config's `disclaimers` appended to a lesson description, each once, in order. Absent when none were. */
+    disclaimers?: string[];
 }
 /** YouTube lists chapters only when there are at least three and each is at least ten seconds. */
 export declare const MIN_CHAPTERS = 3;

package/dist/tools/writeDescription.js

@@ -137,6 +137,36 @@ function readBrief(projectRoot, videoName) {
     }
     return { logline, audience, feeling, constructedShots, ...(lesson ? { lesson: true } : {}) };
 }
+/**
+ * A lesson's concept card (src/videos/<video>/concept.json) gives the practice question and its answer. Absence is
+ * normal: most lessons have no practice question, and then nothing here changes. It counts only when both the question
+ * and the answer are there, because a question with no answer to withhold is just a line in the narration.
+ */
+function readPractice(projectRoot, videoName) {
+    const file = path.join(projectRoot, "src", "videos", videoName, "concept.json");
+    if (!fs.existsSync(file))
+        return undefined;
+    let card;
+    try {
+        card = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const text = (v) => (typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined);
+    const question = text(card.practiceQuestion);
+    const answer = text(card.answer);
+    if (!question || !answer)
+        return undefined;
+    return { question, answer, working: text(card.answerWorking) };
+}
+/** The pinned comment: the answer, and one line of working when the card has it. */
+function buildAnswer(practice) {
+    const lines = [`Answer: ${practice.answer}`];
+    if (practice.working)
+        lines.push(`Working: ${practice.working}`);
+    return lines.join("\n") + "\n";
+}
 /**
  * Reads beats.json for the real beat list. Required, unlike brief.json: without it there is
  * nothing to ground the description in, which is the entire point of this tool.
@@ -293,7 +323,7 @@ function formatSeconds(frames, fps) {
  * any tool, so "drafting" here means template logic over real facts (brief fields, real beats),
  * never invented content.
  */
-function buildDescription(videoName, brief, beatsData, chapters, credits, lesson = false) {
+function buildDescription(videoName, brief, beatsData, chapters, credits, lesson = false, practice, disclaimers = []) {
     const { fps, beats } = beatsData;
     const totalFrames = beats.reduce((sum, b) => sum + b.duration, 0);
     const lines = [`# ${videoName}`, ""];
@@ -341,6 +371,14 @@ function buildDescription(videoName, brief, beatsData, chapters, credits, lesson
         // Replaces the sample-content disclosure: everything in a lesson is drawn for it.
         lines.push("This video is a constructed explanation, not footage.");
         lines.push("");
+        if (practice) {
+            lines.push("## Practice question");
+            lines.push("");
+            lines.push(practice.question);
+            lines.push("");
+            lines.push("Drop your answer in the comments.");
+            lines.push("");
+        }
     }
     else if (constructedShots.length > 0) {
         lines.push("## Sample content used in this video");
@@ -367,6 +405,13 @@ function buildDescription(videoName, brief, beatsData, chapters, credits, lesson
     for (const c of credits)
         lines.push(`- ${c}`);
     lines.push("");
+    // Last, each line once: a line the description already carries on its own is not repeated.
+    const body = new Set(lines.map((l) => l.trim()));
+    const added = disclaimers.filter((d) => !body.has(d));
+    for (const d of added)
+        lines.push(d);
+    if (added.length > 0)
+        lines.push("");
     return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
 }
 /**
@@ -382,7 +427,11 @@ function runWriteDescription(input) {
     const chapters = buildChapters(beatsData.beats, beatsData.fps);
     const credits = buildCredits(projectRoot, videoName, beatsData.beats);
     const lesson = brief?.lesson === true || (0, config_1.productionMode)((0, config_1.loadConfig)(projectRoot)) === "supernova";
-    const content = buildDescription(videoName, brief, beatsData, chapters, credits, lesson);
+    const practice = lesson ? readPractice(projectRoot, videoName) : undefined;
+    const disclaimers = lesson
+        ? [...new Set(((0, config_1.loadConfig)(projectRoot).disclaimers ?? []).map((d) => d.trim()).filter((d) => d.length > 0))]
+        : [];
+    const content = buildDescription(videoName, brief, beatsData, chapters, credits, lesson, practice, disclaimers);
     const outPath = path.join(projectRoot, "output", `${videoName}-DESCRIPTION.md`);
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
     fs.writeFileSync(outPath, content, "utf8");
@@ -406,12 +455,19 @@ function runWriteDescription(input) {
                 `passing result, so the incomplete file was removed instead of being reported as written.`);
         }
     }
+    let answerPath;
+    if (practice) {
+        answerPath = path.join(projectRoot, "output", `${videoName}-ANSWER.md`);
+        fs.writeFileSync(answerPath, buildAnswer(practice), "utf8");
+    }
     return {
         written: true,
         path: outPath,
         sampleContentDisclosed: constructedShots.map((s) => s.beatId),
         chapters: chapters.chapters.map((c) => `${chapterTimestamp(c.seconds)} ${c.label}`),
         credits,
+        ...(practice && answerPath ? { answerPath, practiceQuestion: practice.question } : {}),
+        ...(disclaimers.length > 0 ? { disclaimers } : {}),
     };
 }
 function registerWriteDescription(server) {
@@ -432,6 +488,12 @@ function registerWriteDescription(server) {
             "writing a list YouTube would ignore), and a Credits section read from what is on disk: the tool, " +
             "the music (an original compose_score track, an imported CC0 track with its source, or the built-in " +
             "bed), narration engine and voice, and any sound effect whose licence asks for a credit. " +
+            "For a lesson (Supernova mode) whose concept card (src/videos/<videoName>/concept.json) has a practiceQuestion " +
+            "and an answer, the description gains a Practice question section with the question and the line " +
+            "\"Drop your answer in the comments.\", and the answer goes only to output/<videoName>-ANSWER.md (a ready-to-paste " +
+            "pinned comment: the answer, plus a line of working from the card's optional answerWorking), returned as answerPath. " +
+            "The `disclaimers` string array in openvidstudio.config.json is appended to every lesson description, each line " +
+            "once, at the end. A project without these fields gets the same file as before. " +
             "finalize_video writes this file on every run, so a finished video always has one.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),