@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/planBeats.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapDurationsToBars = snapDurationsToBars;
 exports.runPlanBeats = runPlanBeats;
 exports.registerPlanBeats = registerPlanBeats;
 const zod_1 = require("zod");
@@ -18,6 +19,48 @@ const mcp_1 = require("./mcp");
  */
 const PACE_MIN = 2.3;
 const PACE_MAX = 2.9;
+/**
+ * Round a set of beat durations to whole bars. Every beat gets at least one bar, the total is
+ * the nearest whole number of bars to the original (never fewer than one per beat), and any
+ * difference is settled on the beats whose rounding moved furthest the wrong way, so the
+ * result stays as close to the requested proportions as whole bars allow. Boundaries are
+ * placed at exact bar positions and rounded once, so they never drift across the video.
+ */
+function snapDurationsToBars(durations, fps, bpm, beatsPerBar = 4) {
+    const barFrames = (60 / bpm) * beatsPerBar * fps;
+    const n = durations.length;
+    const total = durations.reduce((a, b) => a + b, 0);
+    const totalBars = Math.max(n, Math.round(total / barFrames));
+    const bars = durations.map((d) => Math.max(1, Math.round(d / barFrames)));
+    let diff = totalBars - bars.reduce((a, b) => a + b, 0);
+    while (diff !== 0) {
+        const step = diff > 0 ? 1 : -1;
+        let best = -1;
+        let bestWant = -Infinity;
+        for (let i = 0; i < n; i++) {
+            if (step < 0 && bars[i] <= 1)
+                continue;
+            const want = step * (durations[i] / barFrames - bars[i]);
+            if (want > bestWant) {
+                bestWant = want;
+                best = i;
+            }
+        }
+        if (best === -1)
+            break;
+        bars[best] += step;
+        diff -= step;
+    }
+    const starts = [];
+    let acc = 0;
+    for (const b of bars) {
+        starts.push(Math.round(acc * barFrames));
+        acc += b;
+    }
+    const totalFrames = Math.round(acc * barFrames);
+    const snapped = starts.map((s, i) => (i + 1 < n ? starts[i + 1] : totalFrames) - s);
+    return { bars, starts, durations: snapped, barFrames, totalFrames, totalBars: acc };
+}
 function slotsFor(arc, features) {
     const demo = features.length ? features : ["feature"];
     if (arc === "simple") {
@@ -73,22 +116,46 @@ function runPlanBeats(input) {
     const fps = input.fps ?? config.videoConfig.fps ?? 30;
     const arc = input.arc ?? "simple";
     const appUrl = input.appUrl ?? config.capture.appUrl;
-    const totalFrames = Math.round(input.targetDurationSeconds * fps);
+    const requestedFrames = Math.round(input.targetDurationSeconds * fps);
     const slots = slotsFor(arc, input.features ?? []);
     const weightTotal = slots.reduce((a, s) => a + s.weight, 0);
+    // Last beat absorbs the rounding so the total lands exactly on target.
+    const rawDurations = [];
+    let used = 0;
+    slots.forEach((slot, i) => {
+        const raw = Math.round((slot.weight / weightTotal) * requestedFrames);
+        const duration = i === slots.length - 1 ? requestedFrames - used : raw;
+        rawDurations.push(duration);
+        used += duration;
+    });
+    let snap = null;
+    const beatsPerBar = input.snapToBars?.beatsPerBar ?? 4;
+    if (input.snapToBars) {
+        const { bpm } = input.snapToBars;
+        if (!(bpm > 0) || !Number.isFinite(bpm))
+            throw new Error(`snapToBars.bpm must be a positive number, got ${bpm}.`);
+        if (!Number.isInteger(beatsPerBar) || beatsPerBar < 1) {
+            throw new Error(`snapToBars.beatsPerBar must be a whole number of at least 1, got ${beatsPerBar}.`);
+        }
+        snap = snapDurationsToBars(rawDurations, fps, bpm, beatsPerBar);
+    }
+    const durations = snap ? snap.durations : rawDurations;
+    const totalFrames = snap ? snap.totalFrames : requestedFrames;
     const beats = [];
     let start = 0;
     slots.forEach((slot, i) => {
-        // Last beat absorbs the rounding so the total lands exactly on target.
-        const raw = Math.round((slot.weight / weightTotal) * totalFrames);
-        const duration = i === slots.length - 1 ? totalFrames - start : raw;
+        const duration = durations[i];
         const seconds = duration / fps;
         const min = Math.ceil(PACE_MIN * seconds);
         const max = Math.floor(PACE_MAX * seconds);
+        let startBar;
+        if (snap)
+            startBar = snap.bars.slice(0, i).reduce((a, b) => a + b, 0);
         beats.push({
             id: slot.id,
             start,
             duration,
+            ...(snap ? { startBar, bars: snap.bars[i] } : {}),
             seconds: Number(seconds.toFixed(2)),
             captureMethod: slot.method,
             wordBudget: { min, max, suggested: Math.round((min + max) / 2) },
@@ -97,6 +164,14 @@ function runPlanBeats(input) {
         start += duration;
     });
     const notes = [
+        ...(snap
+            ? [
+                `Beats snapped to bars at ${input.snapToBars.bpm} bpm (${beatsPerBar} beats per bar, ${snap.barFrames.toFixed(2)} ` +
+                    `frames per bar): every boundary is a downbeat, so cuts land on the music. The total is ${snap.totalBars} ` +
+                    `bars, ${totalFrames} frames (${(totalFrames / fps).toFixed(2)} s) against the ${requestedFrames} frames asked for. ` +
+                    `Word budgets below are for the snapped durations.`,
+            ]
+            : []),
         `Word budgets are the range validate_beats will accept for each duration. Write to the suggested ` +
             `number: it sits mid band, so a small edit later does not push the beat out of range.`,
         `Every beat with captureMethod "screenshot" also needs visual.url and visual.interactions (an array, ` +
@@ -117,6 +192,16 @@ function runPlanBeats(input) {
         arc,
         totalWordBudget: totalBudget,
         beats,
+        ...(snap
+            ? {
+                snappedToBars: {
+                    bpm: input.snapToBars.bpm,
+                    beatsPerBar,
+                    framesPerBar: Number(snap.barFrames.toFixed(4)),
+                    totalBars: snap.totalBars,
+                },
+            }
+            : {}),
         notes,
     };
 }
@@ -130,7 +215,8 @@ function registerPlanBeats(server) {
             "being too sparse rather than too long. Writing to a stated number avoids that round trip. Three " +
             "arcs: simple (single feature, hook to CTA), packed (one dense hero beat then one demo per claim), " +
             "tutorial (prerequisites, install, setup, steps, recap). Output feeds straight into validate_beats " +
-            "once narration is written in.",
+            "once narration is written in. Pass snapToBars with the score's bpm when the video is cut to music, so " +
+            "every boundary lands on a downbeat; the planned total then moves to the nearest whole bar.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),
             targetDurationSeconds: zod_1.z.number().positive(),
@@ -138,6 +224,13 @@ function registerPlanBeats(server) {
             features: zod_1.z.array(zod_1.z.string()).optional(),
             appUrl: zod_1.z.string().optional(),
             fps: zod_1.z.number().positive().optional(),
+            snapToBars: zod_1.z
+                .object({ bpm: zod_1.z.number().positive(), beatsPerBar: zod_1.z.number().int().min(1).optional() })
+                .optional()
+                .describe("Land every beat boundary on a downbeat of the score. Pass the score's bpm (what compose_score was " +
+                "given). Each beat becomes a whole number of bars (at least one), the total moves to the nearest " +
+                "whole bar, and each planned beat reports startBar and bars. Word budgets are for the snapped " +
+                "durations, so write to those."),
         },
     }, async (input) => (0, mcp_1.runTool)("plan_beats", () => runPlanBeats(input)));
 }

package/dist/tools/planProduction.d.ts

@@ -0,0 +1,77 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CreativeLevel, type ProductionMode } from "../config";
+/**
+ * Turns the two intake questions (PLANNING.md step 0: creative level, time budget) into a
+ * concrete plan with a time estimate per phase, based on this machine's actual measured
+ * render speed rather than a guess. The agent shows this plan, with the estimate, at the
+ * approval gate before any beat gets written.
+ *
+ * The estimate has two kinds of number in it, and they are not equally solid:
+ *  - Render time (draft pass, stills, final pass) is derived from preflight's real
+ *    `remotion benchmark` measurement on this machine, divided by a per-level scene weight
+ *    (a finished video renders slower than the flat benchmark composition). The bundle time per
+ *    review round is measured by the same benchmark. This is the part the ±30% accuracy
+ *    bar is actually about, and it's real because it's measured, not guessed. The scene
+ *    weights are calibrated against recorded runs (see LevelProfile.renderWeight).
+ *  - Authoring time (how long writing N bespoke scenes or filling N templates actually
+ *    takes) has no machine to benchmark -- it's a per-beat constant, tuned per level
+ *    (AUTHORING_SECONDS_PER_BEAT below), and it is the part of this estimate most likely
+ *    to need recalibrating against real telemetry once peak/mid mode's actual authoring
+ *    tools (Phase C: design.ts, compose_score, the primitive library) exist to time. Treat
+ *    it as an engineering estimate, not a measurement, until then.
+ */
+export interface PlanProductionInput {
+    projectRoot?: string;
+    /** "standard" (default) or "supernova", a STEM lesson, which has no creative level. */
+    mode?: ProductionMode;
+    /** Required for a standard video; a supernova lesson ignores it. */
+    creativeLevel?: CreativeLevel;
+    timeBudgetMinutes: number;
+    targetDurationSeconds?: number;
+}
+export interface PhaseEstimate {
+    phase: string;
+    seconds: number;
+    note: string;
+}
+export interface PlanProductionResult {
+    mode: ProductionMode;
+    /** null for a supernova lesson, which is not planned on the peak/mid/literal scale. */
+    creativeLevel: CreativeLevel | null;
+    timeBudgetMinutes: number;
+    targetDurationSeconds: number;
+    beatCountEstimate: number;
+    arc: string;
+    customScenes: number;
+    templateScenes: number;
+    scoreStrategy: string;
+    qcRounds: number;
+    renderPasses: string[];
+    phases: PhaseEstimate[];
+    /** Sum of phases[].seconds. */
+    totalEstimateSeconds: number;
+    /** False when totalEstimateSeconds exceeds timeBudgetMinutes * 60. */
+    fitsBudget: boolean;
+    /** Ordered: first thing to cut, then the next, if the budget is short. Empty if it fits. */
+    cutFirst: string[];
+    /** Present when even the unavoidable minimum (one final render) doesn't fit the budget. */
+    infeasibleWarning?: string;
+    /** How the render-time portion was derived: a real measurement, or an unmeasured fallback. */
+    measurement: {
+        fps: number | null;
+        cpuCount: number | null;
+        source: "benchmark" | "fallback";
+        bundleSeconds?: number | null;
+    };
+    warnings: string[];
+}
+export declare function runPlanProductionLogic(input: PlanProductionInput, benchmark: {
+    fps: number | null;
+    cpuCount: number | null;
+    source: "benchmark" | "fallback";
+    bundleSeconds?: number | null;
+}, projectConfig: {
+    fps: number;
+}): PlanProductionResult;
+export declare function runPlanProduction(input: PlanProductionInput): Promise<PlanProductionResult>;
+export declare function registerPlanProduction(server: McpServer): void;

package/dist/tools/planProduction.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPlanProductionLogic = runPlanProductionLogic;
+exports.runPlanProduction = runPlanProduction;
+exports.registerPlanProduction = registerPlanProduction;
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const config_1 = require("../config");
+const preflight_1 = require("./preflight");
+const mcp_1 = require("./mcp");
+// Draft renders at half resolution with a fast x264 preset (renderVideo.ts's
+// buildRenderCommand); this is the same ratio runRenderVideo's own async-job estimate
+// (estimateRenderSeconds) uses between draft and final, kept consistent with it rather
+// than independently re-guessed here.
+const DRAFT_SPEEDUP = 4;
+// A still is one real frame at full quality, not a whole pass, so its cost scales with how
+// many frames get sampled (start/mid/end/cut per beat, see Phase C's render_stills), not
+// with the composition's total duration the way a draft or final pass does.
+const STILL_FRAMES_PER_BEAT = 4;
+// No benchmark available (preflight failed, or the composition couldn't render): fall back
+// to a conservative, clearly-labeled placeholder rather than refusing to plan at all.
+// Matches renderVideo.ts's own async-estimate fallback order of magnitude.
+const FALLBACK_FPS = 2;
+// One bundle of the project costs about this much when preflight could not time one.
+const FALLBACK_BUNDLE_SECONDS = 30;
+// Capturing a beat's real footage (open the page, settle, interact, record) and how many of those
+// captures get repeated once because a selector moved or a frame came out wrong.
+const CAPTURE_SECONDS_PER_BEAT = 45;
+const CAPTURE_RETRY_FRACTION = 0.5;
+// Authoring-time constants (see the module doc comment): an engineering estimate, most
+// solid for literal (today's scaffold_scene + a real template is literally all that mode
+// does, so this is close to directly measurable) and least solid for peak (depends on
+// Phase C tooling that doesn't exist yet to time for real).
+const LEVEL_PROFILES = {
+    peak: {
+        qcRounds: 3,
+        customFraction: 1,
+        arc: "cold-open hook, tension, problem, reveal, chapters, payoff, optional twist",
+        scoreStrategy: "compose_score: an original, arc-matched score (Phase C)",
+        authoringSecondsPerBeat: 90,
+        scoreSeconds: 90,
+        renderWeight: 3.7,
+    },
+    mid: {
+        qcRounds: 2,
+        customFraction: 0.3,
+        arc: "hook, problem, demo x2-3, differentiator, cta (PIPELINE.md's Simple demo arc)",
+        scoreStrategy: "the built-in ambient music-bed.mp3 or a CC0 track via find_music_bed",
+        authoringSecondsPerBeat: 35,
+        scoreSeconds: 20,
+        renderWeight: 2,
+    },
+    literal: {
+        qcRounds: 1,
+        customFraction: 0,
+        arc: "exactly the beats specified, nothing added",
+        scoreStrategy: "whatever beats.json/the brief specifies; the built-in music-bed.mp3 if unstated",
+        authoringSecondsPerBeat: 10,
+        scoreSeconds: 0,
+        renderWeight: 1,
+    },
+};
+/**
+ * A Supernova lesson: script-first, narrated, built from stem primitives with nothing captured.
+ * Authoring and the render weight are engineering estimates (no lesson has been timed yet): a
+ * lesson scene is a few primitives rather than a bespoke layout, but Spark trails and the Nova's
+ * particles make a frame heavier than the flat benchmark composition.
+ */
+const SUPERNOVA_PROFILE = {
+    qcRounds: 2,
+    customFraction: 1,
+    arc: "hook question, a concrete example, terms defined at first use, the formula as a shortcut, the aha on a Nova, a recap, a check question",
+    scoreStrategy: "compose_score with no percussion: a quiet pad under the voice",
+    authoringSecondsPerBeat: 60,
+    scoreSeconds: 20,
+    renderWeight: 2,
+};
+// ~10s/beat average across PIPELINE.md's Simple demo arc (60-75s over hook+problem+2-3
+// demos+differentiator+cta, 6-8 beats) -- the same ratio for any target duration.
+const SECONDS_PER_BEAT_ESTIMATE = 10;
+function runPlanProductionLogic(input, benchmark, projectConfig) {
+    const mode = input.mode ?? "standard";
+    if (mode === "standard" && input.creativeLevel === undefined) {
+        throw new Error("creativeLevel is required for a standard video (peak, mid or literal).");
+    }
+    const profile = mode === "supernova" ? SUPERNOVA_PROFILE : LEVEL_PROFILES[input.creativeLevel];
+    const levelLabel = mode === "supernova" ? "supernova" : input.creativeLevel;
+    const targetDurationSeconds = input.targetDurationSeconds ?? 60;
+    const beatCountEstimate = Math.max(3, Math.round(targetDurationSeconds / SECONDS_PER_BEAT_ESTIMATE));
+    const customScenes = Math.round(beatCountEstimate * profile.customFraction);
+    const templateScenes = beatCountEstimate - customScenes;
+    const fps = benchmark.fps ?? FALLBACK_FPS;
+    const totalFrames = targetDurationSeconds * projectConfig.fps;
+    // fps is the flat benchmark composition's speed; a finished video renders at fps / renderWeight.
+    const sceneFps = fps / profile.renderWeight;
+    const finalRenderSeconds = totalFrames / sceneFps;
+    const draftRenderSeconds = totalFrames / (sceneFps * DRAFT_SPEEDUP);
+    const stillsFramesTotal = beatCountEstimate * STILL_FRAMES_PER_BEAT;
+    const stillsPassSeconds = stillsFramesTotal / sceneFps;
+    const bundleMeasured = typeof benchmark.bundleSeconds === "number";
+    const bundleSeconds = bundleMeasured ? benchmark.bundleSeconds : FALLBACK_BUNDLE_SECONDS;
+    // One bundle per review round, one for the draft pass and one for the final render.
+    const bundleCount = profile.qcRounds + 2;
+    // A lesson captures nothing: every scene is constructed from primitives.
+    const captureSeconds = mode === "supernova" ? 0 : beatCountEstimate * CAPTURE_SECONDS_PER_BEAT * (1 + CAPTURE_RETRY_FRACTION);
+    const authoringSeconds = beatCountEstimate * profile.authoringSecondsPerBeat;
+    const phases = [
+        {
+            phase: "brief + beats",
+            seconds: Math.round(beatCountEstimate * 8),
+            note: `${beatCountEstimate} beats, ${levelLabel} arc: ${profile.arc}`,
+        },
+        {
+            phase: "score",
+            seconds: profile.scoreSeconds,
+            note: profile.scoreStrategy,
+        },
+        {
+            phase: "scene authoring",
+            seconds: Math.round(authoringSeconds),
+            note: `${customScenes} custom scene${customScenes === 1 ? "" : "s"}, ${templateScenes} template scene${templateScenes === 1 ? "" : "s"} ` +
+                `(engineering estimate, not yet calibrated against real telemetry for peak/mid -- see this tool's module doc comment)`,
+        },
+        {
+            phase: "capture",
+            seconds: Math.round(captureSeconds),
+            note: mode === "supernova"
+                ? "no real captures: a lesson is constructed from primitives"
+                : `${beatCountEstimate} beats x ${CAPTURE_SECONDS_PER_BEAT}s, plus an allowance for ${Math.round(CAPTURE_RETRY_FRACTION * 100)}% of them to be captured twice (engineering estimate)`,
+        },
+        {
+            phase: "review bundles",
+            seconds: Math.round(bundleSeconds * bundleCount),
+            note: `${bundleCount} bundles (${profile.qcRounds} review round${profile.qcRounds === 1 ? "" : "s"}, the draft pass, the final render) x ${bundleSeconds}s` +
+                (bundleMeasured ? " measured by preflight's benchmark" : " (unmeasured fallback, run preflight with benchmark: true for a real number)"),
+        },
+        {
+            phase: "stills QC",
+            seconds: Math.round(stillsPassSeconds * profile.qcRounds),
+            note: `${profile.qcRounds} round${profile.qcRounds === 1 ? "" : "s"} x ${stillsFramesTotal} frames at ${sceneFps.toFixed(2)}fps (${fps.toFixed(2)}fps benchmark / ${profile.renderWeight}x ${levelLabel} scene weight)`,
+        },
+        {
+            phase: "draft render",
+            seconds: Math.round(draftRenderSeconds),
+            note: `${totalFrames} frames at ~${(sceneFps * DRAFT_SPEEDUP).toFixed(2)}fps (draft: half-res, veryfast preset)`,
+        },
+        {
+            phase: "final render",
+            seconds: Math.round(finalRenderSeconds),
+            note: `${totalFrames} frames at ${sceneFps.toFixed(2)}fps: the measured ${fps.toFixed(2)}fps benchmark divided by a ${profile.renderWeight}x ${levelLabel} scene weight${benchmark.source === "fallback" ? " (unmeasured fallback, run preflight with benchmark: true for a real number)" : ""}`,
+        },
+    ];
+    const totalEstimateSeconds = phases.reduce((sum, p) => sum + p.seconds, 0);
+    const budgetSeconds = input.timeBudgetMinutes * 60;
+    const fitsBudget = totalEstimateSeconds <= budgetSeconds;
+    const cutFirst = [];
+    let infeasibleWarning;
+    if (!fitsBudget) {
+        if (profile.qcRounds > 1)
+            cutFirst.push(`drop to 1 QC round (saves ~${Math.round(stillsPassSeconds * (profile.qcRounds - 1))}s)`);
+        if (customScenes > 0) {
+            cutFirst.push(`template the non-hook/cta beats instead of authoring them custom (saves up to ~${Math.round(authoringSeconds - beatCountEstimate * LEVEL_PROFILES.literal.authoringSecondsPerBeat)}s)`);
+        }
+        if (profile.scoreSeconds > 0)
+            cutFirst.push(`use the built-in music-bed.mp3 instead of ${profile.scoreStrategy} (saves ~${profile.scoreSeconds}s)`);
+        cutFirst.push(`shorten targetDurationSeconds (currently ${targetDurationSeconds}s)`);
+        cutFirst.push(`render draft-only and skip the final pass for review, then render final once approved`);
+        if (finalRenderSeconds > budgetSeconds) {
+            const feasibleSeconds = Math.floor((budgetSeconds * sceneFps) / projectConfig.fps);
+            infeasibleWarning =
+                `Even the unavoidable minimum, one final render (${Math.round(finalRenderSeconds)}s), does not fit the ` +
+                    `${input.timeBudgetMinutes}min budget at this machine's measured ${fps.toFixed(2)}fps. Feasible alternatives: ` +
+                    `a ${Math.max(10, feasibleSeconds)}s target instead of ${targetDurationSeconds}s, draft quality only, or a longer budget.`;
+        }
+    }
+    const warnings = [];
+    if (benchmark.source === "fallback") {
+        warnings.push(`No real benchmark available -- using a conservative ${FALLBACK_FPS}fps placeholder. Run preflight with ` +
+            `benchmark: true for a real measurement; every render-time number above may be off by more than ±30%.`);
+    }
+    return {
+        mode,
+        creativeLevel: mode === "supernova" ? null : input.creativeLevel,
+        timeBudgetMinutes: input.timeBudgetMinutes,
+        targetDurationSeconds,
+        beatCountEstimate,
+        arc: profile.arc,
+        customScenes,
+        templateScenes,
+        scoreStrategy: profile.scoreStrategy,
+        qcRounds: profile.qcRounds,
+        renderPasses: ["stills QC (" + profile.qcRounds + "x)", "draft", "final"],
+        phases,
+        totalEstimateSeconds: Math.round(totalEstimateSeconds),
+        fitsBudget,
+        cutFirst,
+        ...(infeasibleWarning ? { infeasibleWarning } : {}),
+        measurement: benchmark,
+        warnings,
+    };
+}
+async function runPlanProduction(input) {
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const config = (0, config_1.loadConfig)(projectRoot);
+    const preflight = await (0, preflight_1.runPreflight)({ projectRoot, benchmark: true });
+    const benchmark = preflight.benchmarkResult?.ok === true
+        ? {
+            fps: preflight.benchmarkResult.fps,
+            cpuCount: preflight.benchmarkResult.cpuCount,
+            source: "benchmark",
+            bundleSeconds: preflight.benchmarkResult.bundleSeconds ?? null,
+        }
+        : { fps: null, cpuCount: null, source: "fallback" };
+    const mode = input.mode ?? (0, config_1.productionMode)(config);
+    const result = runPlanProductionLogic({ ...input, mode }, benchmark, { fps: config.videoConfig.fps });
+    if (!preflight.ok) {
+        result.warnings.push(`preflight reports this machine isn't fully ready: ${preflight.blockers.join("; ")}. The estimate above assumes those get fixed first.`);
+    }
+    return result;
+}
+const CREATIVE_LEVEL_SCHEMA = {
+    type: "string",
+    title: "Creative level",
+    description: "peak: full creative liberty, bespoke story/design/score. mid: strong defaults, templates plus the " +
+        "occasional custom scene. literal: exactly what's specified, nothing added.",
+    oneOf: [
+        { const: "peak", title: "Peak -- full creative liberty" },
+        { const: "mid", title: "Mid -- strong defaults" },
+        { const: "literal", title: "Literal -- exactly as specified" },
+    ],
+};
+const TIME_BUDGET_SCHEMA = {
+    type: "number",
+    title: "Time budget (minutes)",
+    description: "Wall-clock minutes you're willing to wait for the finished video, not a conversation deadline.",
+    minimum: 1,
+};
+function registerPlanProduction(server) {
+    server.registerTool("plan_production", {
+        title: "Turn creative level + time budget into a concrete, time-estimated plan",
+        description: "Takes the two intake questions (PLANNING.md step 0: creativeLevel and timeBudgetMinutes) and " +
+            "returns a concrete production plan: the arc, how many beats, how many get a bespoke scene versus a " +
+            "template, the score strategy, how many stills-QC rounds, the render passes, and a time estimate per " +
+            "phase based on this machine's real measured render speed (runs preflight with benchmark: true " +
+            "internally). Render-time numbers (draft pass, stills, final pass) are derived from that real " +
+            "measurement; scene-authoring time is a per-level engineering estimate, not a measurement (see this " +
+            "tool's module doc comment for why, and what would make it one). Reports fitsBudget and, when it's " +
+            "false, cutFirst: an ordered list of what to cut, cheapest first, plus an infeasibleWarning with " +
+            "concrete feasible alternatives (a shorter target duration, draft-only quality, a longer budget) when " +
+            "even one final render alone would not fit. Show this plan and its estimate at the approval gate " +
+            "before writing any beat. creativeLevel/timeBudgetMinutes are optional on this tool specifically: " +
+            "if either is omitted and the connected client supports MCP elicitation, this tool asks for the " +
+            "missing one(s) itself (a structured form, not drafted content). If the client doesn't support " +
+            "elicitation and either is still missing, it fails with an explicit instruction for the calling agent " +
+            "to ask the dev directly (PLANNING.md §0) and call this again with both set -- it never guesses a " +
+            "level or a budget. In supernova mode (a STEM lesson, from the project's production.mode or the mode " +
+            "input) only the budget is asked for: a lesson has no creative level, and its plan has no capture term.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            mode: zod_1.z
+                .enum(["standard", "supernova"])
+                .optional()
+                .describe("Defaults to the project's production.mode. A supernova lesson needs no creativeLevel."),
+            creativeLevel: zod_1.z.enum(["peak", "mid", "literal"]).optional(),
+            timeBudgetMinutes: zod_1.z.number().positive().optional(),
+            targetDurationSeconds: zod_1.z.number().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("plan_production", async () => {
+        let { creativeLevel, timeBudgetMinutes } = input;
+        const mode = input.mode ?? (0, config_1.productionMode)((0, config_1.loadConfig)((0, util_1.resolveProjectRoot)(input.projectRoot)));
+        // A lesson is not planned on the peak/mid/literal scale, so it is never asked for one.
+        const needsLevel = mode === "standard";
+        if ((needsLevel && creativeLevel === undefined) || timeBudgetMinutes === undefined) {
+            const caps = server.server.getClientCapabilities();
+            if (caps?.elicitation) {
+                const properties = {};
+                if (needsLevel && creativeLevel === undefined)
+                    properties.creativeLevel = CREATIVE_LEVEL_SCHEMA;
+                if (timeBudgetMinutes === undefined)
+                    properties.timeBudgetMinutes = TIME_BUDGET_SCHEMA;
+                const elicited = await server.server.elicitInput({
+                    mode: "form",
+                    message: "Before planning this video: what creative level and time budget?",
+                    requestedSchema: { type: "object", properties, required: Object.keys(properties) },
+                });
+                if (elicited.action === "accept" && elicited.content) {
+                    const content = elicited.content;
+                    creativeLevel = creativeLevel ?? content.creativeLevel;
+                    timeBudgetMinutes = timeBudgetMinutes ?? content.timeBudgetMinutes;
+                }
+            }
+        }
+        if ((needsLevel && creativeLevel === undefined) || timeBudgetMinutes === undefined) {
+            const missing = [needsLevel && creativeLevel === undefined && "creativeLevel", timeBudgetMinutes === undefined && "timeBudgetMinutes"]
+                .filter(Boolean)
+                .join(" and ");
+            throw new Error(`${missing} still missing. This client doesn't support MCP elicitation, or the dev declined it -- ` +
+                `ask directly in conversation (PLANNING.md §0 has the two questions), then call plan_production ` +
+                `again with both set. Never guess these.`);
+        }
+        return runPlanProduction({ ...input, mode, creativeLevel, timeBudgetMinutes });
+    }));
+}

package/dist/tools/planShots.d.ts

@@ -0,0 +1,79 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Ranks what a demo video should show, from what the repository already says.
+ *
+ * Deciding what to show is the hard part of a demo video. Skipping the timeline editor is
+ * a convenience; choosing the fifteen seconds that carry the pitch is the part people get
+ * wrong, and it is the part a repository is unexpectedly good at answering. The author
+ * already ordered the README, already wrote the changelog, already decided which routes
+ * exist and which the docs link to most. Nobody reads those as a ranking because reading
+ * them that way is tedious, not because the signal is weak.
+ *
+ * Every candidate carries its evidence. A ranking without evidence is a vibe with a number
+ * attached, and the proposed test for this feature is whether the project's own author says
+ * "yes, that is my product's best moment", which they cannot judge without seeing why.
+ *
+ * What this deliberately does not do is write beats. It feeds PLANNING.md's intake rather
+ * than replacing it: the intake is where a human says what the video is for, and a ranking
+ * of what the repo emphasises is an input to that conversation, not a substitute.
+ */
+export interface ShotCandidate {
+    /** A short name for the moment. */
+    title: string;
+    /** Where it came from and why it scored. */
+    evidence: string[];
+    score: number;
+    /** A route, command, or file the beat would point at, when the signal named one. */
+    target?: string;
+    /** What the capture would most likely be, given what this target is. */
+    suggestedCapture: "screenshot" | "recording" | "terminal" | "dom-demo";
+}
+export interface PlanShotsInput {
+    /** The repository being filmed. Not the video project. */
+    repoRoot: string;
+    maxShots?: number;
+    /** Days of git history to weigh. Defaults to 180. */
+    historyDays?: number;
+}
+export interface PlanShotsResult {
+    candidates: ShotCandidate[];
+    signalsUsed: string[];
+    signalsMissing: string[];
+    notes: string[];
+}
+/** Titles are labels in a ranked list, so they get cut at a word, not mid-word. */
+export declare function shortTitle(text: string, max?: number): string;
+/**
+ * Feature claims from a README, in the order the author put them.
+ *
+ * Order is the signal. The first feature listed is almost always the one the author thinks
+ * sells the project, and the tenth is almost always there for completeness. A bold lead-in
+ * on a bullet is a second, weaker signal of the same thing.
+ */
+export declare function parseReadmeFeatures(markdown: string): {
+    title: string;
+    detail: string;
+    rank: number;
+    bold: boolean;
+}[];
+/**
+ * The most recent release's added features.
+ *
+ * Recency matters twice over: a feature shipped last month is what the project wants seen,
+ * and it is the one least likely to already have a video. Fixes are skipped, because
+ * "we fixed a crash" is not a demo beat.
+ */
+export declare function parseChangelogFeatures(markdown: string): {
+    title: string;
+    version: string;
+}[];
+/** Routes a Next.js or Remix style tree declares. A route that exists is a thing to film. */
+export declare function discoverRoutes(files: string[]): string[];
+/** How often each route is linked from documentation. A route the docs push is a route users land on. */
+export declare function countRouteMentions(routes: string[], docs: string): Record<string, number>;
+/** Directories the recent commits actually touched, which is where the work has been. */
+export declare function summarizeChurn(gitLog: string): Record<string, number>;
+export declare function runPlanShots(input: PlanShotsInput): Promise<PlanShotsResult>;
+/** Loose title matching, so a README bullet and a route about the same thing merge rather than compete. */
+export declare function overlaps(a: string, b: string): boolean;
+export declare function registerPlanShots(server: McpServer): void;