@kheleshikhi/studio-agent 0.6.1 → 0.8.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, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,12 +16,15 @@ import { daemonRpc, setCliTrace } from "./protocol.js";
 import { 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 { capabilitiesView, compatibilityReport, contextSummary, experiencePreviewSummary, experienceSchemaNotice, mathPlaneRequirement, resolveCreateTarget, schemaTopicView } from "./context.js";
+const VERSION = "0.8.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"]);
 export function parse(argv) {
     const args = [];
     const flags = new Map();
@@ -59,7 +62,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;
@@ -74,6 +77,8 @@ export function assertSupportedFlags(parsed) {
         allowed = ["provider"];
     else if (["component", "behavior", "example"].includes(command) && action === "search")
         allowed = ["limit", "offset"];
+    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,6 +88,12 @@ 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")
@@ -90,7 +101,7 @@ export function assertSupportedFlags(parsed) {
     }
     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 +114,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 +143,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 +159,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 +238,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 +258,7 @@ async function api(method, route, body) {
     if (route === "/v1/agent/context") {
         assertCompatibility(result);
         compatibilityChecked = true;
+        serverContext = result;
     }
     return result;
 }
@@ -407,6 +417,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 +683,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 +709,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 +753,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 +801,110 @@ 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);
+    }
+}
+/**
+ * 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) {
+    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();
+    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);
+    verifyProbe(recipe, probed);
+    const level = await audioLevel(encoder, output);
+    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);
+    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, 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 writeFile(path.join(destination, "render.json"), `${JSON.stringify({ ...manifest, frame_sha256: frames.frame_sha256 }, null, 2)}\n`);
+    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 };
+}
 async function libraryInspectBrowser(parsed, kind, stableId) {
     const target = libraryWorkspace(parsed, kind, stableId);
     const viewport = flag(parsed, "viewport", "desktop");
@@ -728,6 +948,144 @@ 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();
+        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 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 },
+        });
+        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") {
@@ -822,10 +1180,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 {
@@ -889,6 +1260,17 @@ async function run(parsed) {
         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 === "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 (isLibraryKind(first)) {
         const result = await library(parsed, first, second, third);
         if (result !== undefined)
@@ -898,7 +1280,8 @@ async function run(parsed) {
         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 +1293,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 +1339,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,6 +1355,9 @@ 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))
@@ -1050,19 +1442,57 @@ 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()}`));
+            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 },
+            });
+            return { ok: true, command: "studio.render-video", asset, source_hash: hash, ...result };
         }
         if (action === "capture-preview") {
             const { hash } = await assertBrowserSource(parsed, asset);
@@ -1118,24 +1548,39 @@ 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>",
         "  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]",
         "",
         "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 +1610,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);