@kheleshikhi/studio-agent 0.6.1 → 0.9.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { createHash, randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { realpathSync, watch as watchFile } from "node:fs";
 import { createRequire } from "node:module";
-import { access, appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { access, appendFile, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -13,15 +13,24 @@ import { attemptDirectory, createAttemptPointer, finalizeClient, readAttemptPoin
 import { runDaemon } from "./daemon.js";
 import { audioUploadExtension, isLibraryKind, LIBRARY_STUDIO_WORKSPACE, libraryLockAfterSave, LibraryWorkspace, } from "./library.js";
 import { daemonRpc, setCliTrace } from "./protocol.js";
-import { cleanStaleDaemonMetadata, readConfig, readDaemonMetadata, stateDirectory, validateOrigin, writeConfig, } from "./state.js";
+import { runRenderJob } from "./render-jobs.js";
+import { compileDependencies, experienceProvenance } from "./shot-provenance.js";
+import { digestOf } from "./shot-provenance.js";
+import { episodeCues, episodeTimeline, parseEpisode } from "./episode.js";
+import { planEpisode, renderEpisode } from "./episode-runner.js";
+import { cacheDirectory, cleanStaleDaemonMetadata, readConfig, readDaemonMetadata, stateDirectory, validateOrigin, writeConfig, } from "./state.js";
 import { CliError } from "./types.js";
 import { sourceHash, StudioWorkspace } from "./workspace.js";
-import { parseScenario } from "./scenario.js";
-const VERSION = "0.6.1";
+import { parseScenario, parseExperienceScenario } from "./scenario.js";
+import { audioLevel, audioSegments, encode, encodeArguments, findEncoder, mix, parseRecipe, probe, RENDER_KIND, sha256, verifyProbe } from "./video.js";
+import { changedPaths } from "./presence.js";
+import { inspectNotice, PROJECT_FLAGS, projectCommand, projectId, SCOPED_SEARCH_FLAGS, scopeWarningNotice, scopeWarnings, searchNotice, searchParameters } from "./project.js";
+import { capabilitiesView, compatibilityReport, contextSummary, experiencePreviewSummary, experienceSchemaNotice, mathPlaneRequirement, resolveCreateTarget, schemaTopicView } from "./context.js";
+const VERSION = "0.9.0";
 const AGENT_PROTOCOL = 1;
-const INSTRUCTIONS = `# NerdBro Interactive Studio agent\n\nUse the provider-neutral \`nerdbro\` CLI. Before substantial authoring: read \`nerdbro context\`, fetch the live \`nerdbro guide\`, then search only relevant docs, exact contracts, Components, Behaviors and examples. Do not read the entire catalogue blindly.\n\nFor complex work, prove risky capabilities in a small spike first. Checkout once, edit only supported source, validate, compile, drive the learner scenario where supported, inspect visuals, save, certify, then stop for human approval. Never force a conflict, approve, publish, administer or deploy. Disconnect when work is over.\n\nIf this is a Git-backed workspace, inspect recent history first. Work in coherent batches; after each, run focused checks, inspect the diff, and commit the green checkpoint with intent and verification. Never force-push or rewrite another Agent's work.\n\nExperience is final learner content: it contains one or more Scenes, and each Scene owns local interaction and Bands. Read \`nerdbro schema experience\`, \`scene.stateMachines\`, and \`stateMachine.actions\` for current contracts. Library definitions (experience, audio, component, behavior) use \`create\` or \`checkout\`, edit \`source.json\`, then \`status\`, \`save\`, \`validate\` and \`certify\`. Audio must be AAC in MP4/M4A.\n\nCurrent live playbook: /docs/studio-language/agent-authoring-playbook\n`;
+const INSTRUCTIONS = `# NerdBro Interactive Studio agent\n\nUse the provider-neutral \`nerdbro\` CLI. Before substantial authoring: read \`nerdbro context\`, fetch the live \`nerdbro guide\`, then search only relevant docs, exact contracts, Components, Behaviors and examples. Do not read the entire catalogue blindly.\n\nFor complex work, prove risky capabilities in a small spike first. Checkout once, edit only supported source, validate, compile, drive the learner scenario where supported, inspect visuals, save, certify, then stop for human approval. Never force a conflict, approve, publish, administer or deploy. Disconnect when work is over.\n\nIf this is a Git-backed workspace, inspect recent history first. Work in coherent batches; after each, run focused checks, inspect the diff, and commit the green checkpoint with intent and verification. Never force-push or rewrite another Agent's work.\n\nEverything visual is a Scene (\`studio create\` defaults to the sceneComposition target); a graph is a Scene math plane, never a separate target. Interaction is an Experience: final learner content containing one or more Scenes, with inputs, requests, readouts/exports, tools, rounds, presentation and assessment outcomes (game is scoring only). The targets and schemas \`nerdbro context\` lists as frozen (InteractiveScene, mathGraph, combined) are read for existing assets only. Read \`nerdbro schema experience\`, \`scene.stateMachines\`, and \`stateMachine.actions\` for current contracts. Library definitions (experience, audio, component, behavior) use \`create\` or \`checkout\`, edit \`source.json\`, then \`status\`, \`save\`, \`validate\` and \`certify\`. Audio must be AAC in MP4/M4A.\n\nCurrent live playbook: /docs/studio-language/agent-authoring-playbook\n`;
 // Presence-only options never consume the following positional argument.
-const BOOLEAN_FLAGS = new Set(["force", "full-page", "headless", "no-browser", "declarative", "assessment", "no-assessment", "scratch"]);
+const BOOLEAN_FLAGS = new Set(["force", "full-page", "headless", "no-browser", "declarative", "assessment", "no-assessment", "scratch", "saved", "math-plane", "no-math-plane", "all-libraries", "full", "compact"]);
 export function parse(argv) {
     const args = [];
     const flags = new Map();
@@ -59,7 +68,7 @@ function flag(parsed, name, fallback) {
     const value = parsed.flags.get(name);
     return typeof value === "string" ? value : fallback;
 }
-const BRIEF_FLAGS = ["concept", "teaching-purpose", "learner-action", "expected-visual-behavior", "graph-purpose", "graph-x", "graph-y", "graph-sync", "language", "additional-instruction", "components", "behavior", "important-values", "assessment", "no-assessment"];
+const BRIEF_FLAGS = ["concept", "teaching-purpose", "learner-action", "expected-visual-behavior", "graph-purpose", "graph-x", "graph-y", "graph-sync", "language", "additional-instruction", "components", "behavior", "important-values", "assessment", "no-assessment", "math-plane", "no-math-plane"];
 const BROWSER_FLAGS = ["view", "viewport", "timeout"];
 export function assertSupportedFlags(parsed) {
     const [command, action, detail] = parsed.args;
@@ -67,13 +76,19 @@ export function assertSupportedFlags(parsed) {
     if (command === "_daemon")
         allowed = ["origin", "headless", "no-browser", "version-tag"];
     else if (command === "attempt" && action === "start")
-        allowed = ["label", "mode"];
+        allowed = ["label", "mode", "project"];
     else if (command === "attempt" && action === "finish")
         allowed = ["outcome"];
     else if (command === "agent" && action === "init")
         allowed = ["provider"];
-    else if (["component", "behavior", "example"].includes(command) && action === "search")
+    else if (["component", "behavior"].includes(command) && action === "search")
+        allowed = SCOPED_SEARCH_FLAGS;
+    else if (command === "example" && action === "search")
         allowed = ["limit", "offset"];
+    else if (command === "project")
+        allowed = PROJECT_FLAGS[action || "list"] || [];
+    else if (command === "world" && action === "inspect")
+        allowed = ["zone"];
     else if (isLibraryKind(command)) {
         if (action === "create")
             allowed = ["workspace", "name", "category", "visual", "palette", "implementation", "media", "language", "description", "kind", "master-audio", "declarative", "duration-ms", "scene-asset", "scene-package", "scene", "document"];
@@ -83,14 +98,24 @@ export function assertSupportedFlags(parsed) {
             allowed = ["workspace", "revision", "out"];
         else if (action === "inspect-browser")
             allowed = ["workspace", "viewport", "timeout"];
+        else if (command === "experience" && action === "drive")
+            allowed = ["workspace", "scenario", "viewport", "timeout", "out", "saved"];
+        else if (command === "experience" && action === "watch")
+            allowed = ["workspace", "once", "interval"];
+        else if (command === "experience" && action === "render-video")
+            allowed = ["workspace", "recipe", "out", "timeout", "keep-frames", "saved"];
         else if (["status", "save", "validate", "certify", "preview"].includes(action))
             allowed = ["workspace"];
         else if (action === "search")
             allowed = ["limit"];
     }
+    else if (command === "episode") {
+        if (["plan", "render", "status"].includes(action))
+            allowed = ["workspace", "out", "cache", "workers", "timeout"];
+    }
     else if (command === "studio") {
         if (action === "create")
-            allowed = ["title", "target", ...BRIEF_FLAGS.filter((name) => name !== "no-assessment"), "command-id", "scratch"];
+            allowed = ["title", "target", ...BRIEF_FLAGS.filter((name) => name !== "no-assessment" && name !== "no-math-plane"), "command-id", "scratch", "starter"];
         else if (action === "brief" && detail === "update")
             allowed = BRIEF_FLAGS;
         else if (action === "checkout")
@@ -103,10 +128,14 @@ export function assertSupportedFlags(parsed) {
             allowed = ["workspace", "scenario", "viewport", "timeout", "out", "view"];
         else if (action === "capture-preview")
             allowed = ["workspace", "out", "viewport", "mode", "duration", "fps", "timeout"];
+        else if (action === "render-video")
+            allowed = ["workspace", "recipe", "out", "timeout", "keep-frames", "measure-playback"];
         else if (action === "certify")
             allowed = ["workspace", ...BROWSER_FLAGS];
         else if (action === "export")
             allowed = ["workspace", "revision", "out"];
+        else if (action === "watch")
+            allowed = ["workspace", "once", "interval"];
         else
             allowed = ["workspace"];
     }
@@ -128,33 +157,15 @@ function output(value, asJson) {
     else
         process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
-function versionParts(value) {
-    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value);
-    if (!match)
-        throw new CliError(`Server returned an invalid CLI version: ${value}`, "AGENT_VERSION_INVALID", 5);
-    return match.slice(1).map(Number);
-}
-function compareVersions(left, right) {
-    const a = versionParts(left);
-    const b = versionParts(right);
-    for (let index = 0; index < 3; index += 1) {
-        if (a[index] !== b[index])
-            return a[index] - b[index];
-    }
-    return 0;
-}
+/** Refuse an incompatible CLI and warn when the server recommends a newer one. */
 export function assertCompatibility(context) {
-    if (Number(context.agent_protocol) !== AGENT_PROTOCOL) {
-        throw new CliError(`Agent protocol ${context.agent_protocol} is incompatible with CLI protocol ${AGENT_PROTOCOL}. Upgrade the NerdBro Studio Agent.`, "AGENT_PROTOCOL_INCOMPATIBLE", 5, context);
-    }
-    const minimum = String(context.minimum_cli_version || "");
-    if (compareVersions(VERSION, minimum) < 0) {
-        throw new CliError(`CLI ${VERSION} is too old; NerdBro requires ${minimum} or newer.`, "AGENT_CLI_UPGRADE_REQUIRED", 5, context);
-    }
-    const recommended = String(context.recommended_cli_version || minimum);
-    if (compareVersions(VERSION, recommended) < 0) {
-        process.stderr.write(`nerdbro: CLI ${recommended} is recommended (current ${VERSION}).\n`);
-    }
+    const report = compatibilityReport(context, VERSION, AGENT_PROTOCOL);
+    if (report.status === "protocol_incompatible")
+        throw new CliError(report.message, "AGENT_PROTOCOL_INCOMPATIBLE", 5, { ...context, compatibility: report });
+    if (report.status === "upgrade_required")
+        throw new CliError(report.message, "AGENT_CLI_UPGRADE_REQUIRED", 5, { ...context, compatibility: report });
+    if (report.status === "upgrade_recommended")
+        process.stderr.write(`nerdbro: ${report.message}\n`);
 }
 export function certificationRuntimeObservation(observation) {
     const allowed = [
@@ -162,7 +173,12 @@ export function certificationRuntimeObservation(observation) {
         "runtime_fingerprint", "runtime_part_id", "active_states",
         "state_machine_error", "math_graph", "environment", "error_summary",
     ];
-    return Object.fromEntries(allowed.filter((key) => observation[key] !== undefined).map((key) => [key, observation[key]]));
+    const certified = Object.fromEntries(allowed.filter((key) => observation[key] !== undefined).map((key) => [key, observation[key]]));
+    // The server refuses a probed observation; say honestly whether this was one.
+    const probe = observation.probe;
+    if (probe && typeof probe === "object")
+        certified.probe = { active: probe.active === true };
+    return certified;
 }
 export function structuredErrorDetails(value) {
     if (value && typeof value === "object" && !Array.isArray(value)) {
@@ -236,12 +252,19 @@ async function uploadApi(route, extension, contentType, bytes) {
     }
 }
 let compatibilityChecked = false;
+// The last live context this process read: target, deprecation and capability
+// authority for this command. Never persisted, never bundled.
+let serverContext = null;
 async function ensureCompatibility() {
     const context = await rawApi("GET", "/v1/agent/context");
     assertCompatibility(context);
     compatibilityChecked = true;
+    serverContext = context;
     return context;
 }
+async function liveContext() {
+    return serverContext ?? ensureCompatibility();
+}
 async function api(method, route, body) {
     if (!compatibilityChecked && route !== "/v1/agent/context")
         await ensureCompatibility();
@@ -249,6 +272,7 @@ async function api(method, route, body) {
     if (route === "/v1/agent/context") {
         assertCompatibility(result);
         compatibilityChecked = true;
+        serverContext = result;
     }
     return result;
 }
@@ -407,6 +431,109 @@ async function assertBrowserSource(parsed, asset) {
 async function reportBrowserActivity(asset, operation, metadata) {
     await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/activity`, { operation, ...metadata });
 }
+async function reportExperienceActivity(stableId, operation, metadata) {
+    await api("POST", `/v1/agent/authoring/experience/${encodeURIComponent(stableId)}/activity`, { operation, ...metadata });
+}
+/** Agent Presence is supplementary: a failure never fails the command. */
+async function setPresence(patch) {
+    try {
+        await api("PUT", "/v1/agent/presence", patch);
+    }
+    catch { /* Presence never blocks authoring. */ }
+}
+const PRESENCE_STATUS = {
+    validate: "validating", compile: "compiling", preview: "previewing", save: "saving",
+    certify: "certifying", drive: "probing", inspect: "capturing", screenshot: "capturing",
+    observe: "capturing", "capture-preview": "capturing", "inspect-browser": "capturing",
+    "render-video": "capturing",
+};
+/** Which presence a command announces, if it is one the Maker can watch. */
+export function presencePlan(args) {
+    const [command, action, id] = args;
+    const status = action ? PRESENCE_STATUS[action] : undefined;
+    if (!status || !id || !/^[A-Za-z0-9_.-]{1,80}$/.test(id))
+        return null;
+    if (command === "studio")
+        return { subject: `asset:${id}`, status, op: action };
+    if (command === "experience" && action !== "inspect")
+        return { subject: `experience:${id}`, status, op: action };
+    return null;
+}
+/** The bounded outcome a command reports to presence: verdicts, never documents. */
+export function presenceResult(result) {
+    const value = result && typeof result === "object" ? result : {};
+    const inner = value.result && typeof value.result === "object" ? value.result : {};
+    const outcome = { ok: value.ok !== false };
+    for (const [key, item] of Object.entries({
+        valid: inner.valid, compiled: inner.compiled, certified: inner.certified,
+        draft_created: value.draft_created, evidence_mode: value.evidence_mode,
+        diagnostic_count: Array.isArray(inner.diagnostics) ? inner.diagnostics.length : undefined,
+    })) {
+        if (typeof item === "boolean" || typeof item === "number" || typeof item === "string")
+            outcome[key] = item;
+    }
+    return outcome;
+}
+/**
+ * Report where the Agent is working in its local, unsaved source: changed
+ * JSON Pointers against the saved head and a working hash. Never the source
+ * itself. `--once` reports one settled state; otherwise it follows edits
+ * with a debounce until interrupted.
+ */
+async function watchSource(parsed, subject, command, sourcePath, readLocal, readRemote, report) {
+    const remote = await readRemote();
+    const interval = Math.max(250, Math.min(5_000, Number(flag(parsed, "interval", "750"))));
+    let lastActivityAt = 0;
+    let last;
+    const settle = async (forceActivity) => {
+        let local;
+        try {
+            local = await readLocal();
+        }
+        catch {
+            await setPresence({ subject, status: "editing" });
+            return undefined;
+        }
+        const hash = sourceHash(local);
+        const paths = changedPaths(remote, local);
+        if (last && last.hash === hash && !forceActivity)
+            return last;
+        last = { hash, paths };
+        await setPresence({ subject, status: "editing", working_source_hash: hash, changed_paths: paths,
+            ...(paths[0] ? { focused_path: paths[0] } : {}) });
+        // The activity feed keeps a bounded history; presence keeps only now.
+        if (forceActivity || Date.now() - lastActivityAt >= 10_000) {
+            lastActivityAt = Date.now();
+            await report({ status: "completed", working_source_hash: hash, changed_paths: paths, change_count: paths.length }).catch(() => undefined);
+        }
+        return last;
+    };
+    if (parsed.flags.has("once")) {
+        const settled = await settle(true);
+        return { ok: true, command, subject, working_source_hash: settled?.hash || null, changed_paths: settled?.paths || [], parse_error: !settled };
+    }
+    await settle(true);
+    let timer;
+    const watcher = watchFile(path.dirname(sourcePath), (_event, name) => {
+        if (name && path.basename(String(name)) !== path.basename(sourcePath))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => { void settle(false); }, interval);
+    });
+    // Presence expires on the server; a quiet editor still says it is here.
+    const heartbeat = setInterval(() => { void settle(true).catch(() => undefined); }, 30_000);
+    process.stderr.write(`Watching ${sourcePath}; press Ctrl+C to stop.\n`);
+    await new Promise((resolve) => {
+        const stop = () => resolve();
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+    watcher.close();
+    clearInterval(heartbeat);
+    clearTimeout(timer);
+    await setPresence({ subject, status: "idle" });
+    return { ok: true, command, subject, working_source_hash: last?.hash || null, changed_paths: last?.paths || [] };
+}
 async function capture(parsed, asset, inspect, activityOperation = inspect ? "browser.inspect" : "browser.capture") {
     const { source, hash } = await assertBrowserSource(parsed, asset);
     const view = flag(parsed, "view", "canvas");
@@ -570,7 +697,8 @@ async function libraryCheckout(parsed, kind, stableId) {
         checked_out_at: now,
     };
     await target.write(document, lock);
-    return { ok: true, command: `${kind}.checkout`, kind, stable_id: stableId, source: target.sourcePath, lock: target.lockPath, source_hash: hash, head_revision: remote.head_revision || null, approved_revision: remote.approved_revision || null, schema_version: lock.schema_version };
+    const notice = kind === "experience" ? experienceSchemaNotice(document, serverContext) : null;
+    return { ok: true, command: `${kind}.checkout`, kind, stable_id: stableId, source: target.sourcePath, lock: target.lockPath, source_hash: hash, head_revision: remote.head_revision || null, approved_revision: remote.approved_revision || null, schema_version: lock.schema_version, ...(notice ? { schema_notice: notice } : {}) };
 }
 async function libraryStatus(parsed, kind, stableId) {
     const target = libraryWorkspace(parsed, kind, stableId);
@@ -595,6 +723,7 @@ async function libraryStatus(parsed, kind, stableId) {
         approved_revision: remote.approved_revision || null,
         schema_version: remote.schema_version ?? null,
         schema_changed: (remote.schema_version ?? null) !== lock.schema_version,
+        ...(kind === "experience" && experienceSchemaNotice(source, serverContext) ? { schema_notice: experienceSchemaNotice(source, serverContext) } : {}),
     };
 }
 async function librarySave(parsed, kind, stableId) {
@@ -638,9 +767,10 @@ async function libraryPreview(parsed, kind, stableId) {
     await writeFile(target.previewPath, `${JSON.stringify(preview, null, 2)}\n`, "utf8");
     const count = (value) => Array.isArray(value) ? value.length : value !== null && typeof value === "object" ? Object.keys(value).length : null;
     const summary = kind === "experience"
-        ? { mode: preview.mode ?? null, source_hash: preview.sourceHash ?? null, scenes: count(preview.scenes), audio: count(preview.audio) }
+        ? experiencePreviewSummary(preview)
         : { id: preview.id ?? null, implementation: preview.implementation ?? null, outputs: count(preview.outputs) };
-    return { ok: true, command: `${kind}.preview`, kind, stable_id: stableId, local_source_hash: sourceHash(source), preview: target.previewPath, summary };
+    const notice = kind === "experience" ? experienceSchemaNotice(source, serverContext) : null;
+    return { ok: true, command: `${kind}.preview`, kind, stable_id: stableId, local_source_hash: sourceHash(source), preview: target.previewPath, summary, ...(notice ? { schema_notice: notice } : {}) };
 }
 async function libraryExport(parsed, kind, stableId) {
     const revision = required(flag(parsed, "revision"), "--revision is required.");
@@ -685,6 +815,276 @@ async function audioUpload(file) {
         next: `nerdbro audio create <stable-id> --name <text> --media ${media.sha256}`,
     };
 }
+async function readRecipe(parsed) {
+    const recipeFile = path.resolve(required(flag(parsed, "recipe"), "--recipe <recipe.json> is required."));
+    if ((await stat(recipeFile)).size > 65536)
+        throw new CliError("Recipe exceeds 64 KiB.", "VIDEO_RECIPE_INVALID", 2);
+    try {
+        return JSON.parse(await readFile(recipeFile, "utf8"));
+    }
+    catch {
+        throw new CliError("Recipe is not valid JSON.", "VIDEO_RECIPE_INVALID", 2);
+    }
+}
+const PARTIAL_VIDEO = "video.partial.mp4";
+const FAILURE_MANIFEST = "render-failed.json";
+/**
+ * A failed render, in one place: remove what it wrote (frames unless
+ * --keep-frames, sound copies, the mix and any unverified MP4), write
+ * `render-failed.json`, and return an error that names the source, the stage
+ * that failed and that no output is reusable. A render.json and video.mp4
+ * from an earlier successful render into the same directory are left alone;
+ * this attempt never replaced them.
+ */
+async function renderFailure(error, context) {
+    const failure = error instanceof CliError ? error : new CliError(String(error), "VIDEO_RENDER_FAILED");
+    const details = failure.details && typeof failure.details === "object" ? failure.details : {};
+    const stage = typeof details.stage === "string" ? details.stage : context.stage;
+    const { destination } = context;
+    if (!context.keepFrames)
+        await rm(path.join(destination, "frames"), { recursive: true, force: true }).catch(() => undefined);
+    for (const leftover of ["audio", "audio-mix.wav", PARTIAL_VIDEO]) {
+        await rm(path.join(destination, leftover), { recursive: true, force: true }).catch(() => undefined);
+    }
+    const report = {
+        kind: "kheleshikhi.video-render-failure.v1",
+        subject: context.subject,
+        ...context.identity,
+        stage,
+        code: failure.code,
+        message: failure.message,
+        output_reusable: false,
+        canonical: false,
+        frames_kept: context.keepFrames,
+        failed_at: new Date().toISOString(),
+    };
+    await writeFile(path.join(destination, FAILURE_MANIFEST), `${JSON.stringify(report, null, 2)}\n`).catch(() => undefined);
+    return new CliError(`Render failed at ${stage}: ${failure.message}`, failure.code, failure.exitCode, { ...details, stage, source: context.identity, output_reusable: false, failure_report: path.join(destination, FAILURE_MANIFEST) });
+}
+/**
+ * Capture a render's frames through a daemon job (see render-jobs.ts): short
+ * status polls instead of one request held open for minutes. Ctrl-C cancels
+ * the job; progress goes to stderr on a terminal.
+ */
+async function renderFramesThroughDaemon(kind, legacyRoute, request, json) {
+    const interrupt = new AbortController();
+    const onInterrupt = () => interrupt.abort("interrupted");
+    process.once("SIGINT", onInterrupt);
+    let reported = 0;
+    const onProgress = (job) => {
+        if (json || !process.stderr.isTTY || Date.now() - reported < 5_000)
+            return;
+        reported = Date.now();
+        const { stage, frame, frames } = job.progress;
+        process.stderr.write(`nerdbro: rendering ${stage}${frames ? ` ${frame ?? 0}/${frames} frames` : ""} (${Math.round(job.elapsed_ms / 1000)} s)\n`);
+    };
+    try {
+        return await runRenderJob(
+        // Polls are short; only the pre-job fallback route may run long.
+        (route, init) => daemonRpc(route, route === legacyRoute ? init : { ...init, signal: AbortSignal.timeout(60_000) }), kind, legacyRoute, request, { signal: interrupt.signal, onProgress });
+    }
+    finally {
+        process.removeListener("SIGINT", onInterrupt);
+    }
+}
+/**
+ * Mix, encode, verify and describe one render. The audio is mixed from the
+ * canonical bytes the runtime would have played, at the times it logged;
+ * the MP4 is probed against its recipe; `render.json` says what it is a
+ * derivative of and how it was made.
+ */
+async function finishRender(input) {
+    let stage = "audio_mix";
+    try {
+        return await finishRenderStages(input, (value) => { stage = value; });
+    }
+    catch (error) {
+        throw await renderFailure(error, { destination: input.destination, keepFrames: input.keepFrames, identity: input.identity, subject: input.subject, stage });
+    }
+}
+async function finishRenderStages(input, setStage) {
+    const { encoder, recipe, destination, frames } = input;
+    const durationMs = Math.round((frames.frames / recipe.fps) * 1000);
+    const log = (frames.audio?.events ?? []);
+    const sources = (frames.audio?.sources ?? {});
+    const mixStarted = Date.now();
+    let mixed;
+    let mixArgs = null;
+    // Logged times are video times from 0; the MP4 starts at `start`.
+    const startMs = Math.round(recipe.start * 1000);
+    const segments = recipe.audio === "scene" ? audioSegments(log, startMs + durationMs, startMs) : [];
+    if (segments.length) {
+        mixed = path.join(destination, "audio-mix.wav");
+        mixArgs = await mix(encoder, segments, new Map(Object.entries(sources).map(([key, value]) => [key, value.file])), durationMs, mixed);
+    }
+    const encodeStarted = Date.now();
+    // The encode lands under a partial name and becomes video.mp4 only once it
+    // is verified: a failed render never leaves an MP4 that looks finished.
+    const output = path.join(destination, "video.mp4");
+    const partial = path.join(destination, PARTIAL_VIDEO);
+    setStage("encode");
+    await encode(encoder, recipe, path.join(destination, "frames", "%06d.png"), partial, mixed);
+    setStage("verify");
+    const probed = await probe(encoder, partial);
+    verifyProbe(recipe, probed);
+    const level = await audioLevel(encoder, partial);
+    if (segments.length && (level.max_db === null || level.max_db < -60)) {
+        throw new CliError("Sounds were logged but the encoded audio track is silent.", "VIDEO_AUDIO_SILENT", 1, { segments: segments.length });
+    }
+    setStage("manifest");
+    const bytes = await readFile(partial);
+    const manifest = {
+        kind: RENDER_KIND,
+        subject: input.subject,
+        derivative: true,
+        canonical: false,
+        certification_evidence: false,
+        note: input.note,
+        ...input.identity,
+        recipe,
+        recipe_sha256: sha256(JSON.stringify(recipe)),
+        scenario_sha256: sha256(JSON.stringify(recipe.actions)),
+        timing: {
+            clock: input.clock,
+            fps: recipe.fps,
+            start_seconds: recipe.start,
+            end_seconds: recipe.end,
+            frame_count: frames.frames,
+            frame_time: "start + k / fps (computed exactly, never accumulated); frame k exists iff start + k / fps < end",
+            first_frame_seconds: recipe.start,
+            last_frame_seconds: recipe.start + (frames.frames - 1) / recipe.fps,
+        },
+        presentation: {
+            host: "studio_present=1 (the learner runtime alone, no Studio chrome)",
+            profile: recipe.profile,
+            frame_size: frames.frame_size,
+            scaled_after_capture: false,
+        },
+        learner_surface: frames.learner_surface,
+        camera_shots: frames.camera_shots,
+        actions: frames.actions,
+        ...(input.extra ?? {}),
+        frames_sha256: frames.frames_sha256,
+        audio: {
+            mode: recipe.audio,
+            codec: "aac",
+            method: "canonical assets mixed by FFmpeg at their logged video times; nothing was recorded from a speaker",
+            events: log,
+            sources: Object.fromEntries(Object.entries(sources).map(([key, value]) => [key, { sha256: value.sha256, bytes: value.bytes }])),
+            segments,
+            mix_arguments: mixArgs?.map((value) => value.startsWith(destination) ? path.relative(destination, value) : value) ?? null,
+            level_dbfs: level,
+            ...(segments.length ? {} : { note: recipe.audio === "silent" ? "The recipe asked for silence." : "Nothing sounded during the rendered span." }),
+        },
+        encoder: { name: "ffmpeg", version: encoder.version, video: "libx264 High, yuv420p, CFR", crf: recipe.crf, arguments: encodeArguments(recipe, "frames/%06d.png", "video.mp4", mixed ? "audio-mix.wav" : undefined) },
+        output: { file: "video.mp4", bytes: bytes.length, sha256: sha256(bytes), probe: probed },
+        determinism: "Video times, learner actions and sound placements are exact. Pixels depend on the browser and GPU; compare renders by frame_sha256.",
+        performance: { ...(frames.playback_timing ? { playback_timing: frames.playback_timing } : {}),
+            capture_seconds: frames.capture_seconds, ...(frames.capture_phases ? { capture_phases: frames.capture_phases } : {}),
+            mix_seconds: (encodeStarted - mixStarted) / 1000,
+            encode_seconds: (Date.now() - encodeStarted) / 1000,
+            total_seconds: (Date.now() - input.started) / 1000, frames_per_second_captured: frames.frames / Math.max(frames.capture_seconds, 0.001),
+            agent_rss_mb: Math.round(process.memoryUsage().rss / 1048576) },
+        rendered_at: new Date().toISOString(),
+    };
+    await rename(partial, output);
+    await writeFile(path.join(destination, "render.json"), `${JSON.stringify({ ...manifest, frame_sha256: frames.frame_sha256 }, null, 2)}\n`);
+    await rm(path.join(destination, FAILURE_MANIFEST), { force: true });
+    if (!input.keepFrames)
+        await rm(path.join(destination, "frames"), { recursive: true, force: true });
+    if (mixed)
+        await rm(mixed, { force: true });
+    return { output, manifest: path.join(destination, "render.json"), frames: frames.frames,
+        width: probed.width, height: probed.height, duration_seconds: probed.duration, audio_segments: segments.length,
+        audio_max_dbfs: level.max_db, sha256: manifest.output.sha256 };
+}
+/** One Scene presentation render (see video.ts): capture through a daemon job, then mix, encode, verify, describe. */
+async function renderSceneVideo(input) {
+    const { asset, candidate, recipe, encoder, destination, keepFrames } = input;
+    const hash = sourceHash(candidate);
+    await mkdir(destination, { recursive: true });
+    const started = Date.now();
+    const frames = await renderFramesThroughDaemon("scene", "/browser/render-frames", {
+        asset, sourceHash: input.remoteHash, candidate, candidateHash: hash, recipe,
+        framesDirectory: path.join(destination, "frames"), audioDirectory: path.join(destination, "audio"),
+        measurePlaybackSeconds: input.measurePlaybackSeconds ?? 0, keepFramesOnFailure: keepFrames,
+        out: path.join(destination, "mounted.png"), timeoutMs: input.timeoutMs
+    }, input.json).catch(async (error) => {
+        throw await renderFailure(error, { destination, keepFrames, subject: "scene", stage: "capture", identity: { asset, source_hash: hash } });
+    });
+    // The exact Component, Behavior and Audio definitions this source
+    // compiles against right now (a shot cache keys on its digest).
+    const compiledDependencies = await compileDependencies(api, asset, candidate).catch(() => null);
+    return finishRender({
+        subject: "scene", encoder, recipe, destination, frames, started, keepFrames,
+        identity: { asset, source_hash: hash, source_revision: frames.source_revision ?? null, runtime_fingerprint: frames.runtime_fingerprint ?? null,
+            dependencies_digest: compiledDependencies?.dependencies?.digest ?? null, dependencies: compiledDependencies?.dependencies ?? null },
+        note: "A presentation derivative of the Scene below. The Scene Source stays the authority and stays interactive; this file is never Experience content, never certification evidence and never part of a KSPKG.",
+        clock: "video time; the SceneClock follows it only while it plays (an authored pause holds the Scene)",
+        extra: { scene_clock: frames.scene_clock },
+    });
+}
+/** What an Experience render plays: the local source.json, or (with saved) the saved head the lock names. */
+async function experienceRenderSource(target, saved) {
+    const result = { revision: null };
+    try {
+        const lock = await target.lock();
+        result.revision = lock.head_revision_public_id || null;
+        if (saved) {
+            result.expectedRevision = result.revision || undefined;
+            result.expectedHash = lock.source_hash;
+        }
+    }
+    catch { /* No local checkout: render the saved revision. */ }
+    if (!saved) {
+        try {
+            result.candidate = await target.source();
+            result.candidateHash = sourceHash(result.candidate);
+        }
+        catch { /* No local source: render the saved revision. */ }
+    }
+    return result;
+}
+/** One Experience presentation render (see video.ts). */
+async function renderExperienceVideo(input) {
+    const { stableId, recipe, encoder, destination, keepFrames, candidate, candidateHash, expectedRevision, expectedHash, revision } = input;
+    await mkdir(destination, { recursive: true });
+    const started = Date.now();
+    const frames = await renderFramesThroughDaemon("experience", "/browser/render-experience-frames", {
+        asset: stableId, sourceHash: "", recipe, timeoutMs: input.timeoutMs,
+        framesDirectory: path.join(destination, "frames"), audioDirectory: path.join(destination, "audio"),
+        out: path.join(destination, "mounted.png"), keepFramesOnFailure: keepFrames,
+        library: { workspace: "experiences", selection: stableId, revision: expectedRevision, definitionHash: expectedHash },
+        ...(candidateHash ? { candidate, candidateHash } : {})
+    }, input.json).catch(async (error) => {
+        throw await renderFailure(error, { destination, keepFrames, subject: "experience", stage: "capture",
+            identity: { experience: stableId, source_hash: candidateHash ?? expectedHash ?? null, source_origin: candidateHash ? "local" : "saved" } });
+    });
+    const context = await api("GET", "/v1/agent/context").catch(() => ({}));
+    const document = (candidate ?? {});
+    const scenes = document.scenes && typeof document.scenes === "object" ? document.scenes : null;
+    // Per-Scene identity (approved revision, stored manifest, source hash and
+    // dependency digest) and every sound's sha256: what a shot cache keys on.
+    const sceneProvenance = await (async () => {
+        const rendered = candidate ?? (await api("GET", `${authoringRoute("experience", stableId)}?purpose=inspect`)).document;
+        return experienceProvenance(api, rendered);
+    })().catch((error) => ({ error: error instanceof Error ? error.message : String(error) }));
+    return finishRender({
+        subject: "experience", encoder, recipe, destination, frames, started, keepFrames,
+        identity: {
+            experience: stableId,
+            source_hash: candidateHash ?? frames.source_hash ?? expectedHash ?? null,
+            source_origin: candidateHash ? "local" : "saved",
+            source_revision: revision,
+            scenes,
+            scene_provenance: sceneProvenance,
+            scene_runtime_fingerprint: context.runtime_fingerprint ?? null,
+        },
+        note: "A presentation derivative of the Experience below. The Experience Source and its Scenes stay the authority and stay interactive; this file is never Experience content, never certification evidence and never part of a KSPKG.",
+        clock: "video time (the Experience master timeline advances with it while it runs)",
+        extra: { scenes_shown: frames.scenes, final_state: frames.final_state, final_scene: frames.final_scene, timeline_ms: frames.timeline_ms, completed: frames.completed },
+    });
+}
 async function libraryInspectBrowser(parsed, kind, stableId) {
     const target = libraryWorkspace(parsed, kind, stableId);
     const viewport = flag(parsed, "viewport", "desktop");
@@ -728,6 +1128,98 @@ async function libraryInspectBrowser(parsed, kind, stableId) {
     return { ok: true, command: `${kind}.inspect-browser`, kind, stable_id: stableId, screenshot: target.screenshotPath, browser: browserPath, activity, activity_scope: "local", warning };
 }
 async function library(parsed, kind, action, argument) {
+    if (kind === "experience" && action === "drive") {
+        const stableId = required(argument, "Experience stable id is required.");
+        const target = libraryWorkspace(parsed, kind, stableId);
+        const scenarioFile = path.resolve(required(flag(parsed, "scenario"), "--scenario <file.json> is required."));
+        if ((await stat(scenarioFile)).size > 65536)
+            throw new CliError("Scenario exceeds 64 KiB.", "STUDIO_SCENARIO_INVALID", 2);
+        let document;
+        try {
+            document = JSON.parse(await readFile(scenarioFile, "utf8"));
+        }
+        catch {
+            throw new CliError("Scenario is not valid JSON.", "STUDIO_SCENARIO_INVALID", 2);
+        }
+        const scenario = parseExperienceScenario(document);
+        await ensureCompatibility();
+        const destination = path.resolve(flag(parsed, "out", `experience-drive-${stableId}-${Date.now()}`));
+        await mkdir(destination, { recursive: true });
+        // Drive the exact local source.json by default: an unsaved candidate is
+        // mounted in the Agent's own browser through the non-persisting Draft
+        // Preview and bound by its canonical hash. Nothing is saved, and nothing
+        // reaches learners. --saved drives the saved server revision instead.
+        let candidate;
+        let candidateHash;
+        let expectedRevision;
+        let expectedHash;
+        if (!parsed.flags.has("saved")) {
+            try {
+                candidate = await target.source();
+                candidateHash = sourceHash(candidate);
+            }
+            catch { /* No local checkout: drive the saved revision. */ }
+        }
+        if (candidateHash === undefined) {
+            try {
+                const lock = await target.lock();
+                expectedRevision = lock.head_revision_public_id || undefined;
+                expectedHash = lock.source_hash;
+            }
+            catch { /* An approved Experience can be driven without local checkout. */ }
+        }
+        const sourceOrigin = candidateHash ? "local" : "saved";
+        const scenarioHash = createHash("sha256").update(JSON.stringify(scenario)).digest("hex");
+        const driveMetadata = { scenario_hash: scenarioHash, step_count: scenario.steps.length,
+            viewport: flag(parsed, "viewport", "desktop"), source_origin: sourceOrigin,
+            ...(candidateHash ?? expectedHash ? { source_hash: candidateHash ?? expectedHash } : {}) };
+        let response;
+        try {
+            response = await daemonRpc("/browser/experience-drive", {
+                method: "POST",
+                body: JSON.stringify({ asset: stableId, sourceHash: "", out: path.join(destination, "initial.png"),
+                    viewport: flag(parsed, "viewport", "desktop"), timeoutMs: Number(flag(parsed, "timeout", "30000")),
+                    library: { workspace: "experiences", selection: stableId, revision: expectedRevision, definitionHash: expectedHash }, scenario,
+                    ...(candidateHash ? { candidate, candidateHash } : {}),
+                    presenceSubject: `experience:${stableId}` }),
+            });
+        }
+        catch (error) {
+            const failure = error instanceof CliError ? error : new CliError(String(error));
+            const summaries = failure.details?.step_summaries;
+            await reportExperienceActivity(stableId, "experience.drive", { ...driveMetadata, status: "failed", error_code: failure.code,
+                ...(Array.isArray(summaries) ? { steps: summaries.slice(0, 32), failed_step_index: summaries.length - 1 } : {}) }).catch(() => undefined);
+            throw error;
+        }
+        const resultPath = path.join(destination, "result.json");
+        await writeFile(resultPath, `${JSON.stringify(response.result, null, 2)}\n`);
+        const evidenceMode = response.result.evidence_mode === "journey" ? "journey" : "probe";
+        await reportExperienceActivity(stableId, "experience.drive", { ...driveMetadata, status: "completed", evidence_mode: evidenceMode,
+            steps: response.result.step_summaries?.slice(0, 32) }).catch(() => undefined);
+        return { ok: true, command: "experience.drive", stable_id: stableId, output: destination,
+            result: resultPath, steps: scenario.steps.length, evidence_mode: evidenceMode,
+            source_origin: sourceOrigin, ...(candidateHash ? { source_hash: candidateHash } : {}),
+            ...(evidenceMode === "probe" ? { evidence_note: "Probe evidence: the run jumped, fired, seeked or used synthetic setup. It does not prove a learner can reach this point; prove that with a journey from the initial State." } : {}) };
+    }
+    if (kind === "experience" && action === "render-video") {
+        // A presentation derivative of an Experience: see video.ts. The real
+        // Experience player, in the presentation host, driven by video time.
+        const stableId = required(argument, "Experience stable id is required.");
+        const target = libraryWorkspace(parsed, kind, stableId);
+        const recipe = parseRecipe(await readRecipe(parsed), "experience");
+        const encoder = await findEncoder();
+        await ensureCompatibility();
+        const source = await experienceRenderSource(target, parsed.flags.has("saved"));
+        const destination = path.resolve(flag(parsed, "out", `render-experience-${stableId}-${Date.now()}`));
+        const result = await renderExperienceVideo({ stableId, ...source, recipe, encoder, destination,
+            keepFrames: parsed.flags.has("keep-frames"), timeoutMs: Number(flag(parsed, "timeout", "30000")), json: parsed.json });
+        return { ok: true, command: "experience.render-video", stable_id: stableId, ...result };
+    }
+    if (kind === "experience" && action === "watch") {
+        const stableId = required(argument, "Experience stable id is required.");
+        const target = libraryWorkspace(parsed, kind, stableId);
+        return watchSource(parsed, `experience:${stableId}`, "experience.watch", target.sourcePath, () => target.source(), async () => (await api("GET", `${authoringRoute(kind, stableId)}?purpose=inspect`)).document, (metadata) => reportExperienceActivity(stableId, "experience.source.edit", metadata));
+    }
     if (kind === "audio" && action === "upload")
         return audioUpload(required(argument, "Audio file is required."));
     if (AUTHORING_SEARCH_KINDS.includes(kind) && action === "search") {
@@ -765,6 +1257,173 @@ async function library(parsed, kind, action, argument) {
         return libraryExport(parsed, kind, stableId);
     return libraryInspectBrowser(parsed, kind, stableId);
 }
+// ---------------------------------------------------------------------------
+// Episodes (see episode.ts): validate | plan | render | status <episode.json>
+// ---------------------------------------------------------------------------
+export const EPISODE_MAX_WORKERS = 4;
+/**
+ * Shots rendered at once: what was asked, but never more than the daemon has
+ * render browsers. A daemon started without `NERDBRO_RENDER_WORKERS` owns one,
+ * and a second concurrent shot would fail `VIDEO_RENDER_BUSY` mid-episode.
+ */
+export function effectiveEpisodeWorkers(requested, daemonRenderWorkers) {
+    const available = typeof daemonRenderWorkers === "number" && Number.isInteger(daemonRenderWorkers) && daemonRenderWorkers >= 1
+        ? daemonRenderWorkers : 1;
+    if (requested <= available)
+        return { workers: requested, note: null };
+    return {
+        workers: available,
+        note: `--workers ${requested} reduced to ${available}: the running daemon has ${available} render browser(s). `
+            + `Restart it with NERDBRO_RENDER_WORKERS=${requested} (nerdbro agent stop) to render ${requested} shots at once.`,
+    };
+}
+async function readEpisodeFile(file) {
+    const episodePath = path.resolve(required(file, "episode.json is required: nerdbro episode <validate|plan|render|status> <episode.json>."));
+    if ((await stat(episodePath)).size > 1_048_576)
+        throw new CliError("episode.json exceeds 1 MiB.", "EPISODE_INVALID", 2);
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(episodePath, "utf8"));
+    }
+    catch {
+        throw new CliError("episode.json is not valid JSON.", "EPISODE_INVALID", 2);
+    }
+    return { episodePath, episode: parseEpisode(raw) };
+}
+/** Resolve one shot's exact identity from the live server (never from file times). */
+async function resolveEpisodeShot(parsed, shot) {
+    const failed = (message, code = "EPISODE_SHOT_UNRESOLVED") => new CliError(`Shot ${shot.id}: ${message}`, code, 2, { shot: shot.id, stage: "resolve" });
+    if (shot.scene) {
+        const { asset } = shot.scene;
+        let candidate;
+        let remoteHash = "";
+        let revision = null;
+        if (shot.scene.source === "approved") {
+            const loaded = await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}`);
+            if (loaded.source_origin !== "approved" || !loaded.source)
+                throw failed("the asset's current source is not its approved revision (a draft is open); render source local or approve it first.");
+            if (shot.scene.revision && loaded.base_revision_public_id !== shot.scene.revision)
+                throw failed(`revision ${shot.scene.revision} is not the asset's approved head ${loaded.base_revision_public_id}.`);
+            candidate = loaded.source;
+            remoteHash = String(loaded.source_hash || "");
+            revision = loaded.base_revision_public_id ?? null;
+        }
+        else {
+            candidate = await workspace(parsed, asset).source();
+            const status = await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}/status`);
+            remoteHash = String(status.source_hash || "");
+        }
+        const hash = sourceHash(candidate);
+        const compiled = await compileDependencies(api, asset, candidate);
+        if (!compiled.compiled)
+            throw failed("the Scene source does not compile; run `nerdbro studio validate`.", "EPISODE_SHOT_SOURCE_INVALID");
+        const audio = Object.fromEntries((compiled.dependencies?.audio ?? []).map((item) => [item.id, item.sha256 ?? "unresolved"]));
+        return {
+            sources: { main: hash },
+            dependency_digests: { main: compiled.dependencies?.digest ?? null },
+            audio_sha256: audio,
+            identity: { asset, source: shot.scene.source, source_hash: hash, revision, dependencies_digest: compiled.dependencies?.digest ?? null,
+                components: compiled.dependencies?.components ?? [], behaviors: compiled.dependencies?.behaviors ?? [] },
+            render: { asset, candidate, remoteHash },
+        };
+    }
+    const id = shot.experience.id;
+    const target = libraryWorkspace(parsed, "experience", id);
+    const source = await experienceRenderSource(target, shot.experience.source === "saved");
+    const document = source.candidate ?? (await api("GET", `${authoringRoute("experience", id)}?purpose=inspect`)).document;
+    if (!document)
+        throw failed("the Experience has no readable source.");
+    const provenance = await experienceProvenance(api, document);
+    const sources = { experience: source.candidateHash ?? source.expectedHash ?? sourceHash(document) };
+    const digests = {};
+    for (const [scene, identity] of Object.entries(provenance.scenes)) {
+        sources[`scene:${scene}`] = digestOf({ asset: identity.asset ?? null, revision: identity.revision ?? null, manifest: identity.manifest_path ?? null,
+            package: identity.package ?? null, package_sha256: identity.package_sha256 ?? null, source_hash: identity.source_hash ?? null });
+        digests[scene] = identity.dependencies_digest;
+    }
+    return {
+        sources, dependency_digests: digests, audio_sha256: provenance.audio,
+        identity: { experience: id, source: shot.experience.source, scene_provenance: provenance },
+        render: source,
+    };
+}
+async function renderEpisodeShot(parsed, encoder, shot, recipe, resolved, destination) {
+    const timeoutMs = Number(flag(parsed, "timeout", "30000"));
+    if (shot.scene) {
+        const render = resolved.render;
+        await renderSceneVideo({ ...render, recipe, encoder, destination, keepFrames: false, timeoutMs, json: true });
+    }
+    else {
+        await renderExperienceVideo({ stableId: shot.experience.id, ...resolved.render, recipe, encoder, destination,
+            keepFrames: false, timeoutMs, json: true });
+    }
+    return { output: path.join(destination, "video.mp4"), manifest: path.join(destination, "render.json") };
+}
+async function episodeCommand(parsed, action, file) {
+    if (!action || !["validate", "plan", "render", "status"].includes(action)) {
+        throw new CliError("Usage: nerdbro episode <validate|plan|render|status> <episode.json>.", "AGENT_COMMAND_UNKNOWN", 2);
+    }
+    const { episodePath, episode } = await readEpisodeFile(file);
+    const timeline = episodeTimeline(episode);
+    if (action === "validate") {
+        return { ok: true, command: "episode.validate", episode: episode.id, title: episode.title, shots: episode.shots.length,
+            total_frames: timeline.total_frames, total_seconds: timeline.total_seconds,
+            timeline: timeline.shots.map((item) => ({ id: item.id, frames: item.frames, offset_seconds: item.offset_seconds })),
+            subtitles: episodeCues(episode, timeline).length };
+    }
+    const out = path.resolve(flag(parsed, "out", path.join(path.dirname(episodePath), `episode-out-${episode.id}`)));
+    const cache = path.resolve(flag(parsed, "cache", path.join(cacheDirectory(), "episode-shots")));
+    const workers = Number(flag(parsed, "workers", "1"));
+    if (!Number.isInteger(workers) || workers < 1 || workers > EPISODE_MAX_WORKERS) {
+        throw new CliError(`--workers must be 1 to ${EPISODE_MAX_WORKERS}.`, "AGENT_ARGUMENT_INVALID", 2);
+    }
+    const encoder = await findEncoder();
+    await ensureCompatibility();
+    const context = await api("GET", "/v1/agent/context");
+    const deps = {
+        encoder, runtimeFingerprint: context.runtime_fingerprint ?? null,
+        resolveShot: (shot) => resolveEpisodeShot(parsed, shot),
+        renderShot: (shot, recipe, resolved, destination) => renderEpisodeShot(parsed, encoder, shot, recipe, resolved, destination),
+        log: (message) => { if (!parsed.json && process.stderr.isTTY)
+            process.stderr.write(`nerdbro: ${message}\n`); },
+    };
+    const options = { episode, baseDirectory: path.dirname(episodePath), out, cache, workers, deps };
+    if (action === "plan" || action === "status") {
+        const plan = await planEpisode(options);
+        let state = null;
+        try {
+            state = JSON.parse(await readFile(path.join(out, "episode-state.json"), "utf8"));
+        }
+        catch { /* never rendered here */ }
+        let output = null;
+        try {
+            const manifest = JSON.parse(await readFile(path.join(out, "episode.json"), "utf8"));
+            const current = manifest.shots?.map((shot) => shot.key).join() === plan.shots.map((shot) => shot.key).join();
+            output = { file: path.join(out, `${episode.id}.mp4`), sha256: manifest.output?.sha256 ?? null, matches_current_shots: current,
+                qc_passed: Array.isArray(manifest.qc) ? manifest.qc.every((check) => check.pass) : null };
+        }
+        catch { /* no assembled output */ }
+        return { ok: true, command: `episode.${action}`, episode: episode.id, out, cache,
+            total_frames: plan.timeline.total_frames, total_seconds: plan.timeline.total_seconds,
+            shots: plan.shots.map((shot) => ({ id: shot.id, subject: shot.subject, key: shot.key, frames: shot.frames, cache: shot.cache,
+                ...(shot.cache_reason ? { cache_reason: shot.cache_reason } : {}), offset_seconds: shot.offset_seconds })),
+            would_render: plan.shots.filter((shot) => shot.cache !== "valid").map((shot) => shot.id),
+            ...(action === "status" ? { state, output } : {}) };
+    }
+    const daemon = await startDaemon(true);
+    const concurrency = effectiveEpisodeWorkers(workers, daemon.render_workers);
+    if (concurrency.note)
+        deps.log?.(concurrency.note);
+    const result = await renderEpisode({ ...options, workers: concurrency.workers });
+    if (!result.ok) {
+        throw new CliError("The episode was assembled but failed QC; see qc.json.", "EPISODE_QC_FAILED", 1, { output: result.output, manifest: result.manifest, qc: result.qc?.filter((check) => !check.pass) });
+    }
+    return { ok: result.ok, command: "episode.render", episode: episode.id, output: result.output, srt: result.srt, manifest: result.manifest,
+        state: result.state, reused: result.reused, rendered: result.rendered,
+        shots: result.shots.map((shot) => ({ id: shot.id, key: shot.key, state: shot.state, render_seconds: shot.render_seconds ?? null })),
+        qc: result.qc, timings: result.timings, workers: concurrency.workers,
+        ...(concurrency.note ? { workers_note: concurrency.note } : {}) };
+}
 async function run(parsed) {
     const [first, second, third] = parsed.args;
     assertSupportedFlags(parsed);
@@ -786,13 +1445,14 @@ async function run(parsed) {
             if (await readAttemptPointer())
                 throw new CliError("This workspace already has an Attempt.", "AGENT_ATTEMPT_ALREADY_ACTIVE", 3);
             const origin = (await readConfig()).apiOrigin;
-            const server = await api("POST", "/v1/agent/attempts", { label, mode, server_origin: origin });
+            const project = flag(parsed, "project");
+            const server = await api("POST", "/v1/agent/attempts", { label, mode, server_origin: origin, ...(project ? { project: projectId(project) } : {}) });
             const pointer = await createAttemptPointer(server, origin);
-            return { ok: true, command: "attempt.start", attempt_id: pointer.attempt_id, label, mode, folder: pointer.attempt_root, pointer: path.join(process.cwd(), ".nerdbro-attempt.json") };
+            return { ok: true, command: "attempt.start", attempt_id: pointer.attempt_id, label, mode, folder: pointer.attempt_root, pointer: path.join(process.cwd(), ".nerdbro-attempt.json"), ...(project ? { project: pointer.project || null, project_scope: server.project_scope ?? null } : {}) };
         }
         if (second === "current") {
             const active = await readAttemptPointer();
-            return { ok: true, command: "attempt.current", attempt_id: active?.pointer.attempt_id || null };
+            return { ok: true, command: "attempt.current", attempt_id: active?.pointer.attempt_id || null, ...(active?.pointer.project ? { project: active.pointer.project } : {}) };
         }
         if (second === "status") {
             const active = await readAttemptPointer();
@@ -822,10 +1482,23 @@ async function run(parsed) {
         return daemonRpc("/disconnect", { method: "POST", body: "{}" });
     if (first === "whoami")
         return { ok: true, command: "whoami", result: await api("GET", "/v1/agent/whoami") };
-    if (first === "context" || first === "capabilities")
-        return { ok: true, command: first, result: await api("GET", `/v1/agent/${first}`) };
-    if (first === "schema")
-        return { ok: true, command: "schema", result: await api("GET", second ? `/v1/agent/schema/${encodeURIComponent(second)}` : "/v1/agent/schema") };
+    if (first === "context") {
+        const result = await api("GET", "/v1/agent/context");
+        return { ok: true, command: "context", summary: contextSummary(result, VERSION, AGENT_PROTOCOL), result };
+    }
+    if (first === "capabilities") {
+        const registry = await api("GET", "/v1/agent/capabilities");
+        return { ok: true, command: "capabilities", ...capabilitiesView(registry, await liveContext()) };
+    }
+    if (first === "schema") {
+        const result = await api("GET", second ? `/v1/agent/schema/${encodeURIComponent(second)}` : "/v1/agent/schema");
+        if (!second)
+            return { ok: true, command: "schema", result };
+        const view = schemaTopicView(second, result, await liveContext());
+        if (typeof view.deprecated === "string" && !parsed.json)
+            process.stderr.write(`nerdbro: schema ${second} is frozen: ${view.deprecated}\n`);
+        return { ok: true, command: "schema", result: view };
+    }
     if (first === "guide") {
         const result = await api("GET", "/v1/agent/docs/agent-authoring-playbook");
         return {
@@ -877,28 +1550,48 @@ async function run(parsed) {
         const plural = `${first}s`;
         if (second === "search") {
             const query = parsed.args.slice(2).join(" ");
-            const parameters = new URLSearchParams({ query });
-            const limit = flag(parsed, "limit");
-            const offset = flag(parsed, "offset");
-            if (limit)
-                parameters.set("limit", limit);
-            if (offset)
-                parameters.set("offset", offset);
-            return { ok: true, command: `${first}.search`, result: await api("GET", `/v1/agent/catalogue/${plural}/search?${parameters}`) };
+            // Project Attempts get the compact scoped view by default (server-side); see project.ts.
+            const parameters = searchParameters(query, (name) => flag(parsed, name), (name) => parsed.flags.has(name));
+            const result = await api("GET", `/v1/agent/catalogue/${plural}/search?${parameters}`);
+            const notice = searchNotice(result, first);
+            if (notice && !parsed.json)
+                process.stderr.write(`nerdbro: ${notice}\n`);
+            return { ok: true, command: `${first}.search`, result };
+        }
+        if (second === "inspect") {
+            const result = await api("GET", `/v1/agent/catalogue/${plural}/${encodeURIComponent(required(third, "ID is required."))}`);
+            const notice = inspectNotice(result, first);
+            if (notice && !parsed.json)
+                process.stderr.write(`nerdbro: ${notice}\n`);
+            return { ok: true, command: `${first}.inspect`, result };
+        }
+    }
+    if (first === "project")
+        return projectCommand(second, third, (name) => flag(parsed, name), api, (await readAttemptPointer())?.pointer.project);
+    if (first === "world") {
+        // Live World discovery; no World list is bundled with this package.
+        if (!second || second === "list")
+            return { ok: true, command: "world.list", result: await api("GET", "/v1/agent/worlds") };
+        if (second === "inspect") {
+            const world = required(third, "World ID is required.");
+            const zone = flag(parsed, "zone");
+            const query = zone ? `?zone=${encodeURIComponent(zone)}` : "";
+            return { ok: true, command: "world.inspect", result: await api("GET", `/v1/agent/worlds/${encodeURIComponent(world)}${query}`) };
         }
-        if (second === "inspect")
-            return { ok: true, command: `${first}.inspect`, result: await api("GET", `/v1/agent/catalogue/${plural}/${encodeURIComponent(required(third, "ID is required."))}`) };
     }
     if (isLibraryKind(first)) {
         const result = await library(parsed, first, second, third);
         if (result !== undefined)
             return result;
     }
+    if (first === "episode")
+        return episodeCommand(parsed, second, third);
     if (first === "studio") {
         const action = required(second, "Studio command is required.");
         if (action === "create") {
             const title = required(flag(parsed, "title"), "--title is required.");
-            const target = required(flag(parsed, "target"), "--target is required.");
+            // Default and frozen targets come from the live context, never from this package.
+            const target = resolveCreateTarget(flag(parsed, "target"), await liveContext());
             const concept = required(flag(parsed, "concept"), "--concept is required.");
             const brief = {
                 concept,
@@ -910,21 +1603,26 @@ async function run(parsed) {
                 graph_y_semantics: flag(parsed, "graph-y"),
                 graph_sync_semantics: flag(parsed, "graph-sync"),
                 language: flag(parsed, "language", "bilingual"),
-                requires_graph: target === "combined" || Boolean(flag(parsed, "graph-purpose")),
+                // A graph is a Scene math plane, asked for by graph intent, not by a target.
+                requires_graph: mathPlaneRequirement(parsed.flags),
                 requires_assessment: parsed.flags.has("assessment"),
                 additional_instruction: flag(parsed, "additional-instruction"),
                 selected_components: flag(parsed, "components")?.split(",").map((value) => value.trim()).filter(Boolean),
                 selected_behavior: flag(parsed, "behavior"),
                 important_values: flag(parsed, "important-values")?.split(",").map((value) => value.trim()).filter(Boolean),
             };
+            // A World zone starter (world:<world>/<zone>) is resolved by the server
+            // from the live World registry: the same Scene the human Playground opens.
+            const starter = flag(parsed, "starter");
             const result = await api("POST", "/v1/agent/studio", {
                 client_command_id: flag(parsed, "command-id", randomUUID()),
                 title, authoring_target: target, brief,
+                ...(starter ? { starter } : {}),
             });
             // A newly created Studio asset has no approved revision or draft; it is
             // already the isolated scratch surface. The flag makes that intent
             // explicit without inventing a second server-side lifecycle.
-            return { ok: true, command: "studio.create", scratch: parsed.flags.has("scratch"), result };
+            return { ok: true, command: "studio.create", scratch: parsed.flags.has("scratch"), target, math_plane_requested: brief.requires_graph === true, result };
         }
         if (action === "brief") {
             const updating = third === "update";
@@ -951,8 +1649,9 @@ async function run(parsed) {
                 brief.requires_assessment = true;
             if (parsed.flags.has("no-assessment"))
                 brief.requires_assessment = false;
-            if (flag(parsed, "graph-purpose"))
-                brief.requires_graph = true;
+            const mathPlane = mathPlaneRequirement(parsed.flags);
+            if (mathPlane !== undefined)
+                brief.requires_graph = mathPlane;
             if (flag(parsed, "components"))
                 brief.selected_components = flag(parsed, "components").split(",").map((value) => value.trim()).filter(Boolean);
             if (flag(parsed, "important-values"))
@@ -966,10 +1665,20 @@ async function run(parsed) {
             return checkout(parsed, asset);
         if (action === "status")
             return studioStatus(parsed, asset);
+        if (action === "watch") {
+            return watchSource(parsed, `asset:${asset}`, "studio.watch", target.sourcePath, () => target.source(), async () => (await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}`)).source, (metadata) => reportBrowserActivity(asset, "studio.source.edit", metadata));
+        }
         if (action === "source")
             return { ok: true, command: "studio.source", asset, source: await target.source() };
-        if (["validate", "compile", "preview"].includes(action))
-            return { ok: true, command: `studio.${action}`, asset, source_hash: sourceHash(await target.source()), result: await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/${action}`, { source: await target.source() }) };
+        if (["validate", "compile", "preview"].includes(action)) {
+            const result = await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/${action}`, { source: await target.source() });
+            // Project scope: out-of-scope dependencies warn here and block approval later.
+            const warnings = scopeWarnings(result);
+            const notice = scopeWarningNotice(warnings);
+            if (notice && !parsed.json)
+                process.stderr.write(`nerdbro: ${notice}\n`);
+            return { ok: true, command: `studio.${action}`, asset, source_hash: sourceHash(await target.source()), result, ...(warnings.length ? { scope_warnings: warnings } : {}) };
+        }
         if (action === "history")
             return { ok: true, command: "studio.history", asset, result: await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}/history`) };
         if (action === "save") {
@@ -1050,19 +1759,43 @@ async function run(parsed) {
                 response = await daemonRpc("/browser/drive", {
                     method: "POST",
                     body: JSON.stringify({ asset, sourceHash: remoteHash, candidate, candidateHash: hash, scenario,
+                        presenceSubject: `asset:${asset}`,
                         viewport: flag(parsed, "viewport", "desktop"),
                         out: path.join(destination, "initial.png"), timeoutMs: Number(flag(parsed, "timeout", "30000")) }),
                 });
             }
             catch (error) {
                 const failure = error instanceof CliError ? error : new CliError(String(error));
-                await reportBrowserActivity(asset, "studio.drive", { ...driveMetadata, status: "failed", error_code: failure.code }).catch(() => undefined);
+                const summaries = failure.details?.step_summaries;
+                await reportBrowserActivity(asset, "studio.drive", { ...driveMetadata, status: "failed", error_code: failure.code,
+                    ...(Array.isArray(summaries) ? { steps: summaries.slice(0, 32), failed_step_index: summaries.length - 1 } : {}) }).catch(() => undefined);
                 throw error;
             }
             await writeFile(path.join(destination, "result.json"), `${JSON.stringify(response.result, null, 2)}\n`);
-            await reportBrowserActivity(asset, "studio.drive", { ...driveMetadata, status: "completed" });
+            const evidenceMode = response.result.evidence_mode === "journey" ? "journey" : "probe";
+            await reportBrowserActivity(asset, "studio.drive", { ...driveMetadata, status: "completed", evidence_mode: evidenceMode,
+                steps: response.result.step_summaries?.slice(0, 32) });
             return { ok: true, command: "studio.drive", asset, source_hash: hash, output: destination,
-                result: path.join(destination, "result.json"), steps: scenario.steps.length };
+                result: path.join(destination, "result.json"), steps: scenario.steps.length, evidence_mode: evidenceMode,
+                ...(evidenceMode === "probe" ? { evidence_note: "Probe evidence: the run jumped, fired, seeked or used synthetic setup. It does not prove a learner can reach this point; prove that with a journey from the initial State." } : {}) };
+        }
+        if (action === "render-video") {
+            // A presentation derivative, never content or evidence: see video.ts.
+            const recipe = parseRecipe(await readRecipe(parsed), "scene");
+            // Refuse before any browser work: no encoder, no render.
+            const encoder = await findEncoder();
+            const candidate = await target.source();
+            const hash = sourceHash(candidate);
+            const remote = await studioStatus(parsed, asset);
+            const remoteHash = String(remote.remote_source_hash || "");
+            if (!remoteHash && remote.remote_snapshot_public_id) {
+                throw new CliError("Studio has a draft without a readable source.", "STUDIO_SOURCE_UNAVAILABLE", 3);
+            }
+            const destination = path.resolve(flag(parsed, "out", `render-${asset}-${Date.now()}`));
+            const result = await renderSceneVideo({ asset, candidate, remoteHash, recipe, encoder, destination,
+                keepFrames: parsed.flags.has("keep-frames"), timeoutMs: Number(flag(parsed, "timeout", "30000")),
+                measurePlaybackSeconds: Number(flag(parsed, "measure-playback", "0")), json: parsed.json });
+            return { ok: true, command: "studio.render-video", asset, source_hash: hash, ...result };
         }
         if (action === "capture-preview") {
             const { hash } = await assertBrowserSource(parsed, asset);
@@ -1118,24 +1851,54 @@ function help() {
     return [
         `NerdBro Studio Agent ${VERSION}`,
         "",
-        "Commands: setup, connect, disconnect, whoami, context, guide, schema [topic], capabilities",
+        "Model: everything visual is a Scene (graphs are Scene math planes); interaction is an Experience.",
+        "",
+        "Commands: setup, connect, disconnect, whoami, guide",
+        "  context                 live contract versions, offered/frozen targets, deprecations, compatibility",
+        "  schema [topic]          topic index, or one live projection (e.g. experience, scene.stateMachines)",
+        "  capabilities [--json]   universal Experience capabilities and tools, plus the Studio capability registry",
         "  docs | docs search <query> | docs open <slug>",
         "  agent start|status|stop|instructions|init --provider claude|codex|generic",
         "  component|behavior|example search <query>|inspect <id>",
+        "      component|behavior search [--limit n] [--offset n] [--all-libraries] [--full | --compact]",
+        "      in a project Attempt search is compact and scoped; stderr names related ids outside the scope",
+        "",
+        "Authoring projects (the libraries an Attempt may author from):",
+        "  project list | project libraries [<project>] | project show [<project>] | project current",
+        "  project create --title <text> --output-target lesson|game|experience|video --home-library <slug> [--purpose <text>] [--permitted a,b]",
+        "  attempt start --label <text> --project <project>   scope every later command in this workspace",
+        "  project import <stable-id> [--kind component|behavior|audio|experience] --reason <text> [--project <project>]",
+        "",
         "  studio checkout|status|source|history|validate|compile|preview|save <asset>",
-        "  studio create --scratch --title <text> --target <target> --concept <text> [--command-id <id>]",
-        "  studio brief <asset> | studio brief update <asset> [--concept <text> ...]",
+        "  studio create --scratch --title <text> --concept <text> [--target sceneComposition] [--starter world:<world>/<zone>] [--command-id <id>]",
+        "      --target defaults to sceneComposition; targets the server lists as frozen (combined, mathGraph) are refused",
+        "      graph intent: --math-plane | --graph-purpose <text> [--graph-x <text>] [--graph-y <text>] [--graph-sync <text>]",
+        "  world list | world inspect <world> [--zone <zone>]   live World discovery and zone starter Source",
+        "  studio brief <asset> | studio brief update <asset> [--concept <text> ...] [--math-plane | --no-math-plane]",
         "  studio open|screenshot|inspect|observe|capture-preview|certify <asset>",
         "  studio drive <asset> --scenario scenario.json [--workspace dir] [--viewport desktop|mobile] [--out dir]",
+        "      steps include previewState \"machine/state\" [+ setup], select \"kind:id\", restart; result says probe or journey",
+        "  studio watch <asset> [--once] [--interval ms]   report changed source paths to the Maker's Studio (Agent Presence)",
         "  studio inspect <asset> --view final|learner --viewport desktop|mobile",
         "  studio capture-preview <asset> [--mode semantic|fixed] [--viewport 480x320] [--duration 8] [--fps 4] [--out dir]",
+        "  studio render-video <asset> --recipe recipe.json [--out dir] [--keep-frames] [--measure-playback 15]",
+        "      presentation MP4 (H.264/AAC) of the learner surface at exact SceneClock times; needs local FFmpeg; writes render.json",
         "  studio export <asset> --revision <revision> [--out file.kspkg]",
         "",
+        "Episodes (kheleshikhi.episode.v1: ordered Scene/Experience shots, narration, music, subtitles):",
+        "  episode validate <episode.json>                         check the manifest and its timeline",
+        "  episode plan|status <episode.json> [--out dir] [--cache dir]   shot keys, cache hits, what would render",
+        "  episode render <episode.json> [--out dir] [--cache dir] [--workers 1-4]",
+        "      renders changed shots only, then concat + ducked mix + loudnorm + SRT + QC; needs local FFmpeg",
+        "",
         "Library authoring (<kind> = experience|audio|component|behavior):",
         "  experience|audio search <query> [--limit n] | inspect <stable-id>",
         "  audio upload <file.m4a|file.mp4>            AAC in MP4/M4A, at most 24 MiB",
         "  audio create <stable-id> --name <text> --media <sha256> [--category c] [--language l]",
-        "  experience create <stable-id> --name <text> --kind <poem|story|...>",
+        "  experience create <stable-id> --name <text> --kind <poem|story|...>   (authored as the context's experience_schema, V3)",
+        "  experience drive <stable-id> --scenario scenario.json [--viewport desktop|mobile] [--out dir]",
+        "  experience render-video <stable-id> --recipe recipe.json [--saved] [--out dir] [--keep-frames]",
+        "  experience watch <stable-id> [--once] [--interval ms]",
         "      (--scene-asset <asset-id> | --scene-package <kind:id> --scene <scene-id>)",
         "      [--master-audio <audio-id>] [--duration-ms <n>]",
         "  component create <stable-id> --name <text> [--category c] [--visual v] [--palette p]",
@@ -1165,7 +1928,22 @@ async function main() {
             commandId = `cmd_${randomUUID().replaceAll("-", "")}`;
             setCliTrace({ attemptId: active?.pointer.attempt_id, commandId });
         }
-        const result = await run(parsed);
+        const plan = presencePlan(parsed.args);
+        if (plan)
+            await setPresence({ subject: plan.subject, status: plan.status, last_command: { op: plan.op } });
+        let result;
+        try {
+            result = await run(parsed);
+        }
+        catch (error) {
+            if (plan) {
+                const code = error instanceof CliError ? error.code : "AGENT_COMMAND_FAILED";
+                await setPresence({ subject: plan.subject, status: "idle", last_command: { op: plan.op }, last_result: { ok: false, code } });
+            }
+            throw error;
+        }
+        if (plan)
+            await setPresence({ subject: plan.subject, status: "idle", last_command: { op: plan.op }, last_result: presenceResult(result) });
         if (active && commandId && parsed.args[0] !== "attempt")
             await saveCommandEvidence(active.pointer, commandId, parsed.args.slice(0, 2).join("."), result);
         output(result, parsed.json);