@kheleshikhi/studio-agent 0.8.0 → 0.9.1

package/dist/cli.js

@@ -3,7 +3,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { realpathSync, watch as watchFile } from "node:fs";
 import { createRequire } from "node:module";
-import { access, appendFile, mkdir, readFile, rm, 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,18 +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, 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.8.0";
+const VERSION = "0.9.1";
 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\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", "saved", "math-plane", "no-math-plane"]);
+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();
@@ -70,13 +76,17 @@ 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)) {
@@ -99,6 +109,10 @@ export function assertSupportedFlags(parsed) {
         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" && name !== "no-math-plane"), "command-id", "scratch", "starter"];
@@ -398,19 +412,34 @@ async function checkout(parsed, asset) {
     await target.write(source, lock);
     return { ok: true, command: "studio.checkout", asset, source: target.sourcePath, lock: target.lockPath, source_hash: hash, base_snapshot_public_id: lock.base_snapshot_public_id, authoring_brief: remote.authoring_brief || {}, authoring_warnings: remote.authoring_warnings || [] };
 }
+/**
+ * The hash of the source the server serves, as the Studio page will hash it.
+ *
+ * A draft's stored hash was computed from the JSON it was saved with; read
+ * back from Postgres JSONB, a whole-number decimal such as 0.0 returns as 0,
+ * so the mounted Studio (which hashes what it loaded) can disagree with the
+ * stored value for older drafts. Browser mount checks therefore compare
+ * against the served source; conflict detection keeps the stored snapshot.
+ */
+async function servedSourceHash(asset) {
+    const loaded = await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}`);
+    if (loaded.source && typeof loaded.source === "object")
+        return sourceHash(loaded.source);
+    return String(loaded.source_hash || "");
+}
 async function studioStatus(parsed, asset) {
     const target = workspace(parsed, asset);
-    const [source, lock, remote] = await Promise.all([target.source(), target.lock(), api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}/status`)]);
+    const [source, lock, remote, served] = await Promise.all([target.source(), target.lock(), api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}/status`), servedSourceHash(asset)]);
     const localHash = sourceHash(source);
     const remoteHead = remote.head_snapshot?.public_id || null;
-    return { ok: true, command: "studio.status", asset, local_source_hash: localHash, local_changed: localHash !== lock.checkout_source_hash, base_snapshot_public_id: lock.base_snapshot_public_id, remote_snapshot_public_id: remoteHead, remote_source_hash: remote.source_hash, remote_changed: remoteHead !== lock.base_snapshot_public_id, conflict: remoteHead !== lock.base_snapshot_public_id && localHash !== lock.checkout_source_hash, authoring_warnings: remote.authoring_warnings || [] };
+    return { ok: true, command: "studio.status", asset, local_source_hash: localHash, local_changed: localHash !== lock.checkout_source_hash, base_snapshot_public_id: lock.base_snapshot_public_id, remote_snapshot_public_id: remoteHead, remote_source_hash: remote.source_hash, served_source_hash: served, remote_changed: remoteHead !== lock.base_snapshot_public_id, conflict: remoteHead !== lock.base_snapshot_public_id && localHash !== lock.checkout_source_hash, authoring_warnings: remote.authoring_warnings || [] };
 }
 async function assertBrowserSource(parsed, asset) {
     const target = workspace(parsed, asset);
     const source = await target.source();
     const hash = sourceHash(source);
     const status = await studioStatus(parsed, asset);
-    if (status.local_changed || status.remote_source_hash !== hash)
+    if (status.local_changed || status.served_source_hash !== hash)
         throw new CliError("Save the local source before browser inspection; local, server, and runtime hashes must match.", "STUDIO_SOURCE_MISMATCH", 3, status);
     return { target, source, hash };
 }
@@ -812,6 +841,67 @@ async function readRecipe(parsed) {
         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;
@@ -819,6 +909,15 @@ async function readRecipe(parsed) {
  * 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 ?? []);
@@ -834,15 +933,21 @@ async function finishRender(input) {
         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");
-    await encode(encoder, recipe, path.join(destination, "frames", "%06d.png"), output, mixed);
-    const probed = await probe(encoder, output);
+    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, output);
+    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 });
     }
-    const bytes = await readFile(output);
+    setStage("manifest");
+    const bytes = await readFile(partial);
     const manifest = {
         kind: RENDER_KIND,
         subject: input.subject,
@@ -890,13 +995,16 @@ async function finishRender(input) {
         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, mix_seconds: (encodeStarted - mixStarted) / 1000,
+            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)
@@ -905,6 +1013,93 @@ async function finishRender(input) {
         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");
@@ -1029,56 +1224,10 @@ async function library(parsed, kind, action, argument) {
         const recipe = parseRecipe(await readRecipe(parsed), "experience");
         const encoder = await findEncoder();
         await ensureCompatibility();
-        let candidate;
-        let candidateHash;
-        let expectedRevision;
-        let expectedHash;
-        let revision = null;
-        try {
-            const lock = await target.lock();
-            revision = lock.head_revision_public_id || null;
-            if (parsed.flags.has("saved")) {
-                expectedRevision = revision || undefined;
-                expectedHash = lock.source_hash;
-            }
-        }
-        catch { /* No local checkout: render the saved revision. */ }
-        if (!parsed.flags.has("saved")) {
-            try {
-                candidate = await target.source();
-                candidateHash = sourceHash(candidate);
-            }
-            catch { /* No local source: render the saved revision. */ }
-        }
+        const source = await experienceRenderSource(target, parsed.flags.has("saved"));
         const destination = path.resolve(flag(parsed, "out", `render-experience-${stableId}-${Date.now()}`));
-        await mkdir(destination, { recursive: true });
-        const started = Date.now();
-        const response = await daemonRpc("/browser/render-experience-frames", {
-            method: "POST",
-            body: JSON.stringify({ asset: stableId, sourceHash: "", recipe, timeoutMs: Number(flag(parsed, "timeout", "30000")),
-                framesDirectory: path.join(destination, "frames"), audioDirectory: path.join(destination, "audio"),
-                out: path.join(destination, "mounted.png"),
-                library: { workspace: "experiences", selection: stableId, revision: expectedRevision, definitionHash: expectedHash },
-                ...(candidateHash ? { candidate, candidateHash } : {}) }),
-        });
-        const frames = response.result;
-        const context = await api("GET", "/v1/agent/context").catch(() => ({}));
-        const document = (candidate ?? {});
-        const scenes = document.scenes && typeof document.scenes === "object" ? document.scenes : null;
-        const result = await finishRender({
-            subject: "experience", encoder, recipe, destination, frames, started, keepFrames: parsed.flags.has("keep-frames"),
-            identity: {
-                experience: stableId,
-                source_hash: candidateHash ?? frames.source_hash ?? expectedHash ?? null,
-                source_origin: candidateHash ? "local" : "saved",
-                source_revision: revision,
-                scenes,
-                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 },
-        });
+        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") {
@@ -1123,6 +1272,172 @@ 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 = sourceHash(candidate);
+            revision = loaded.base_revision_public_id ?? null;
+        }
+        else {
+            candidate = await workspace(parsed, asset).source();
+            remoteHash = await servedSourceHash(asset);
+        }
+        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);
@@ -1144,13 +1459,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();
@@ -1248,18 +1564,24 @@ 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 (second === "inspect")
-            return { ok: true, command: `${first}.inspect`, result: await api("GET", `/v1/agent/catalogue/${plural}/${encodeURIComponent(required(third, "ID is required."))}`) };
     }
+    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")
@@ -1276,6 +1598,8 @@ async function run(parsed) {
         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") {
@@ -1360,8 +1684,15 @@ async function run(parsed) {
         }
         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") {
@@ -1426,7 +1757,7 @@ async function run(parsed) {
             const candidate = await target.source();
             const hash = sourceHash(candidate);
             const remote = await studioStatus(parsed, asset);
-            const remoteHash = String(remote.remote_source_hash || "");
+            const remoteHash = String(remote.served_source_hash || remote.remote_source_hash || "");
             // A new scratch asset deliberately has no server source yet. The
             // browser opens its empty Studio route, then receives the unsaved local
             // candidate through the bounded authoring/test bridge.
@@ -1470,28 +1801,14 @@ async function run(parsed) {
             const candidate = await target.source();
             const hash = sourceHash(candidate);
             const remote = await studioStatus(parsed, asset);
-            const remoteHash = String(remote.remote_source_hash || "");
+            const remoteHash = String(remote.served_source_hash || 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()}`));
-            await mkdir(destination, { recursive: true });
-            const started = Date.now();
-            const response = await daemonRpc("/browser/render-frames", {
-                method: "POST",
-                body: JSON.stringify({ asset, sourceHash: remoteHash, candidate, candidateHash: hash, recipe,
-                    framesDirectory: path.join(destination, "frames"), audioDirectory: path.join(destination, "audio"),
-                    measurePlaybackSeconds: Number(flag(parsed, "measure-playback", "0")),
-                    out: path.join(destination, "mounted.png"), timeoutMs: Number(flag(parsed, "timeout", "30000")) }),
-            });
-            const frames = response.result;
-            const result = await finishRender({
-                subject: "scene", encoder, recipe, destination, frames, started, keepFrames: parsed.flags.has("keep-frames"),
-                identity: { asset, source_hash: hash, source_revision: frames.source_revision ?? null, runtime_fingerprint: frames.runtime_fingerprint ?? 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 },
-            });
+            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") {
@@ -1557,6 +1874,15 @@ function help() {
         "  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> --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",
@@ -1573,6 +1899,12 @@ function help() {
         "      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",