@kheleshikhi/studio-agent 0.6.1

package/dist/cli.js

@@ -0,0 +1,1198 @@
+#!/usr/bin/env node
+import { createHash, randomUUID } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { access, appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { chromium } from "playwright";
+import { browserProbeLaunchOptions, VIEW_QUERY } from "./browser.js";
+import { attemptDirectory, createAttemptPointer, finalizeClient, readAttemptPointer, saveCommandEvidence } from "./attempt.js";
+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 { CliError } from "./types.js";
+import { sourceHash, StudioWorkspace } from "./workspace.js";
+import { parseScenario } from "./scenario.js";
+const VERSION = "0.6.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\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`;
+// 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"]);
+export function parse(argv) {
+    const args = [];
+    const flags = new Map();
+    let json = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (value === "--json") {
+            json = true;
+            continue;
+        }
+        if (value === "--version") {
+            args.push(value);
+            continue;
+        }
+        if (value.startsWith("--")) {
+            const name = value.slice(2);
+            if (BOOLEAN_FLAGS.has(name)) {
+                flags.set(name, true);
+                continue;
+            }
+            const next = argv[index + 1];
+            if (next && !next.startsWith("--")) {
+                flags.set(name, next);
+                index += 1;
+            }
+            else
+                flags.set(name, true);
+            continue;
+        }
+        args.push(value);
+    }
+    return { args, json, flags };
+}
+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 BROWSER_FLAGS = ["view", "viewport", "timeout"];
+export function assertSupportedFlags(parsed) {
+    const [command, action, detail] = parsed.args;
+    let allowed = [];
+    if (command === "_daemon")
+        allowed = ["origin", "headless", "no-browser", "version-tag"];
+    else if (command === "attempt" && action === "start")
+        allowed = ["label", "mode"];
+    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")
+        allowed = ["limit", "offset"];
+    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"];
+        else if (action === "checkout")
+            allowed = ["workspace", "force"];
+        else if (action === "export")
+            allowed = ["workspace", "revision", "out"];
+        else if (action === "inspect-browser")
+            allowed = ["workspace", "viewport", "timeout"];
+        else if (["status", "save", "validate", "certify", "preview"].includes(action))
+            allowed = ["workspace"];
+        else if (action === "search")
+            allowed = ["limit"];
+    }
+    else if (command === "studio") {
+        if (action === "create")
+            allowed = ["title", "target", ...BRIEF_FLAGS.filter((name) => name !== "no-assessment"), "command-id", "scratch"];
+        else if (action === "brief" && detail === "update")
+            allowed = BRIEF_FLAGS;
+        else if (action === "checkout")
+            allowed = ["workspace", "force"];
+        else if (["screenshot", "inspect", "observe"].includes(action))
+            allowed = ["workspace", ...BROWSER_FLAGS, "full-page", "out"];
+        else if (action === "open")
+            allowed = ["workspace", "view"];
+        else if (action === "drive")
+            allowed = ["workspace", "scenario", "viewport", "timeout", "out", "view"];
+        else if (action === "capture-preview")
+            allowed = ["workspace", "out", "viewport", "mode", "duration", "fps", "timeout"];
+        else if (action === "certify")
+            allowed = ["workspace", ...BROWSER_FLAGS];
+        else if (action === "export")
+            allowed = ["workspace", "revision", "out"];
+        else
+            allowed = ["workspace"];
+    }
+    const unknown = [...parsed.flags.keys()].filter((name) => !allowed.includes(name));
+    if (unknown.length) {
+        throw new CliError(`Unknown flag --${unknown[0]} for ${command || "this command"}${action ? ` ${action}` : ""}. Valid flags: ${allowed.length ? allowed.map((name) => `--${name}`).join(", ") : "--json"}.`, "CLI_UNKNOWN_FLAG", 2);
+    }
+}
+function required(value, message) {
+    if (!value)
+        throw new CliError(message, "AGENT_ARGUMENT_REQUIRED", 2);
+    return value;
+}
+function output(value, asJson) {
+    if (asJson)
+        process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    else if (typeof value === "string")
+        process.stdout.write(`${value}\n`);
+    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;
+}
+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`);
+    }
+}
+export function certificationRuntimeObservation(observation) {
+    const allowed = [
+        "mounted", "runtime_ready", "geometry_instance_ids", "source_hash",
+        "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]]));
+}
+export function structuredErrorDetails(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return value == null ? {} : { server_detail: value };
+}
+export function studioLockAfterSave(lock, saved, hash, checkoutTime = new Date().toISOString()) {
+    return {
+        ...lock,
+        base_snapshot_public_id: String(saved.public_id || lock.base_snapshot_public_id || "") || null,
+        checkout_source_hash: hash,
+        source_hash: hash,
+        checkout_time: checkoutTime,
+    };
+}
+export function reconciledStudioLock(lock, remote, hash) {
+    const head = remote.head_snapshot;
+    if (remote.source_hash !== hash || !head?.public_id)
+        return null;
+    return studioLockAfterSave(lock, head, hash);
+}
+/** A session paired before a scope existed must re-pair; say so plainly. */
+export function scopeAwareError(error) {
+    if (!(error instanceof CliError) || error.code !== "AGENT_SCOPE_REQUIRED")
+        return error;
+    const scope = /AGENT_SCOPE_REQUIRED:([A-Z0-9_]+)/.exec(error.message)?.[1] || "required";
+    return new CliError(`This Agent session was not granted the ${scope} scope (it was probably paired by an older CLI). Run \`nerdbro disconnect\` and then \`nerdbro connect\` to pair again.`, "AGENT_SCOPE_REQUIRED", 4, { required_scope: scope, reconnect_required: true });
+}
+async function rawApi(method, route, body) {
+    try {
+        await ensureDaemon();
+        const response = await daemonRpc("/api", { method: "POST", body: JSON.stringify({ method, path: route, body }) });
+        return response.result;
+    }
+    catch (error) {
+        throw scopeAwareError(error);
+    }
+}
+async function rawBinaryApi(method, route, code = "STUDIO_EXPORT_INVALID") {
+    await ensureDaemon();
+    let response;
+    try {
+        response = await daemonRpc("/api", {
+            method: "POST",
+            body: JSON.stringify({ method, path: route }),
+        });
+    }
+    catch (error) {
+        throw scopeAwareError(error);
+    }
+    if (!response.binaryBase64)
+        throw new CliError("Server did not return package bytes.", code);
+    return new Uint8Array(Buffer.from(response.binaryBase64, "base64"));
+}
+async function uploadApi(route, extension, contentType, bytes) {
+    await ensureDaemon();
+    if (!compatibilityChecked)
+        await ensureCompatibility();
+    try {
+        // Only the bytes and a bare extension cross the loopback RPC; the daemon
+        // names the multipart part `upload.<extension>`.
+        const response = await daemonRpc("/api-upload", {
+            method: "POST",
+            body: JSON.stringify({ path: route, field: "file", extension, contentType, dataBase64: Buffer.from(bytes).toString("base64") }),
+        });
+        return response.result;
+    }
+    catch (error) {
+        throw scopeAwareError(error);
+    }
+}
+let compatibilityChecked = false;
+async function ensureCompatibility() {
+    const context = await rawApi("GET", "/v1/agent/context");
+    assertCompatibility(context);
+    compatibilityChecked = true;
+    return context;
+}
+async function api(method, route, body) {
+    if (!compatibilityChecked && route !== "/v1/agent/context")
+        await ensureCompatibility();
+    const result = await rawApi(method, route, body);
+    if (route === "/v1/agent/context") {
+        assertCompatibility(result);
+        compatibilityChecked = true;
+    }
+    return result;
+}
+async function waitForDaemon() {
+    const deadline = Date.now() + 15_000;
+    while (Date.now() < deadline) {
+        if (await readDaemonMetadata()) {
+            try {
+                await daemonRpc("/status");
+                return;
+            }
+            catch { /* keep waiting */ }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new CliError("Agent daemon did not start.", "AGENT_DAEMON_START_FAILED");
+}
+async function startDaemon(headless, noBrowser = false) {
+    await cleanStaleDaemonMetadata();
+    if (await readDaemonMetadata()) {
+        const running = await daemonRpc("/status");
+        if (running.daemon_version === VERSION && running.protocol_version === AGENT_PROTOCOL)
+            return running;
+        await daemonRpc("/stop", { method: "POST", body: "{}" });
+        for (let attempt = 0; attempt < 50 && await readDaemonMetadata(); attempt += 1)
+            await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    const config = await readConfig();
+    const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "_daemon", "--origin", config.apiOrigin, "--version-tag", VERSION, ...(headless ? ["--headless"] : []), ...(noBrowser ? ["--no-browser"] : [])], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: false,
+    });
+    child.unref();
+    await waitForDaemon();
+    return daemonRpc("/status");
+}
+async function ensureDaemon() { await startDaemon(true); }
+function openExternal(url) {
+    const command = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.unref();
+}
+async function setup() {
+    if (Number(process.versions.node.split(".")[0]) < 20)
+        throw new CliError("Node 20 or newer is required.", "AGENT_NODE_UNSUPPORTED", 5);
+    if (!["win32", "darwin", "linux"].includes(process.platform))
+        throw new CliError(`Unsupported platform: ${process.platform}`, "AGENT_OS_UNSUPPORTED", 5);
+    let browser = "";
+    for (const channel of ["chrome", "msedge"]) {
+        try {
+            const instance = await chromium.launch(browserProbeLaunchOptions(channel));
+            browser = channel === "chrome" ? "Google Chrome" : "Microsoft Edge";
+            await instance.close();
+            break;
+        }
+        catch { /* try next browser */ }
+    }
+    if (!browser) {
+        try {
+            const instance = await chromium.launch(browserProbeLaunchOptions());
+            browser = "Playwright Chromium";
+            await instance.close();
+        }
+        catch {
+            const require = createRequire(import.meta.url);
+            const cli = require.resolve("playwright/cli");
+            const installed = spawnSync(process.execPath, [cli, "install", "chromium"], { stdio: "inherit" });
+            if (installed.status !== 0)
+                throw new CliError("Playwright Chromium installation failed.", "AGENT_BROWSER_INSTALL_FAILED", 5);
+            const instance = await chromium.launch(browserProbeLaunchOptions());
+            browser = "Playwright Chromium";
+            await instance.close();
+        }
+    }
+    const config = await readConfig();
+    const health = await fetch(new URL("/healthcheck", `${config.apiOrigin}/`)).then((response) => response.ok).catch(() => false);
+    return { ok: true, command: "setup", node: process.versions.node, platform: `${process.platform} ${process.arch}`, browser, production_api: config.apiOrigin, production_api_reachable: health, state_directory: stateDirectory(), ready: true };
+}
+async function connect() {
+    await startDaemon(true);
+    const created = await daemonRpc("/connect", { method: "POST", body: JSON.stringify({ clientVersion: VERSION, clientLabel: `${os.hostname()} (${process.platform} ${process.arch})` }) });
+    const pairing = created.pairing;
+    const verification = `${String(pairing.verification_url)}?code=${encodeURIComponent(String(pairing.user_code))}`;
+    if (!process.env.NERDBRO_NO_OPEN)
+        openExternal(verification);
+    if (!process.argv.includes("--json"))
+        process.stdout.write(`Connect NerdBro Studio Agent\n\nOpen:\n${verification}\n\nCode:\n${pairing.user_code}\n\nWaiting for approval...\n`);
+    const expires = new Date(String(pairing.expires_at)).getTime();
+    while (Date.now() < expires) {
+        await new Promise((resolve) => setTimeout(resolve, Number(pairing.polling_interval_seconds || 2) * 1000));
+        const status = await daemonRpc("/pairing-poll", { method: "POST", body: JSON.stringify({ pairingId: pairing.pairing_id, pairingSecret: pairing.pairing_secret }) });
+        if (status.status === "approved") {
+            const context = await ensureCompatibility();
+            return { ok: true, command: "connect", session_id: status.session_id, expires_at: status.session_expires_at, scopes: status.scopes, compatibility: { agent_protocol: context.agent_protocol, minimum_cli_version: context.minimum_cli_version, recommended_cli_version: context.recommended_cli_version } };
+        }
+        if (["expired", "denied", "redeemed"].includes(String(status.status)))
+            throw new CliError(`Pairing ended with status ${status.status}.`, "PAIRING_NOT_APPROVED", 4);
+    }
+    throw new CliError("Pairing expired before approval.", "PAIRING_EXPIRED", 4);
+}
+function workspace(parsed, asset) {
+    return new StudioWorkspace(path.resolve(flag(parsed, "workspace", path.join(process.cwd(), "nerdbro-studio"))), asset);
+}
+async function checkout(parsed, asset) {
+    const remote = await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}/checkout`);
+    const source = remote.source || remote.starter_source;
+    if (!source || typeof source !== "object")
+        throw new CliError("Asset has no semantic source or canonical starter.", "STUDIO_SOURCE_UNAVAILABLE");
+    const target = workspace(parsed, asset);
+    if (!parsed.flags.has("force")) {
+        try {
+            await access(target.sourcePath);
+            throw new CliError(`${target.sourcePath} already exists; use --force.`, "STUDIO_CHECKOUT_EXISTS", 2);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+        }
+    }
+    const hash = sourceHash(source);
+    const lock = {
+        schema: "kheleshikhi.interactive-studio-lock.v1",
+        asset_id: asset,
+        server_origin: (await readConfig()).apiOrigin,
+        base_snapshot_public_id: remote.head_snapshot?.public_id || null,
+        base_revision_public_id: remote.base_revision_public_id || null,
+        source_hash: String(remote.source_hash || hash),
+        checkout_source_hash: hash,
+        compiler_version: String(remote.compiler_version),
+        scene_schema: remote.scene_schema,
+        component_catalogue_checksum: String(remote.component_catalogue_checksum),
+        behavior_catalogue_checksum: String(remote.behavior_catalogue_checksum),
+        checkout_time: new Date().toISOString(),
+    };
+    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 || [] };
+}
+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 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 || [] };
+}
+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)
+        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 };
+}
+async function reportBrowserActivity(asset, operation, metadata) {
+    await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/activity`, { operation, ...metadata });
+}
+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");
+    const root = path.resolve(flag(parsed, "out", inspect ? `capture-${new Date().toISOString().replace(/[:.]/g, "-")}` : `studio-${asset}-${view}.png`));
+    if (!inspect) {
+        try {
+            if ((await stat(root)).isDirectory())
+                throw new CliError("Screenshot --out must name a PNG file.", "STUDIO_SCREENSHOT_OUTPUT_INVALID", 2);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (path.extname(root).toLowerCase() !== ".png")
+            throw new CliError("Screenshot --out must name a .png file.", "STUDIO_SCREENSHOT_OUTPUT_INVALID", 2);
+    }
+    const screenshot = inspect ? path.join(root, "screenshot.png") : root;
+    const preflight = inspect ? {
+        validation: await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/validate`, { source }),
+        compilation: await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/compile`, { source }),
+    } : undefined;
+    const response = await daemonRpc("/browser/capture", { method: "POST", body: JSON.stringify({ asset, sourceHash: hash, view, viewport: flag(parsed, "viewport", "desktop"), fullPage: parsed.flags.has("full-page"), out: screenshot, timeoutMs: Number(flag(parsed, "timeout", "30000")) }) });
+    const browserFailures = {
+        console_errors: response.result.browser?.console_errors || [],
+        page_errors: response.result.browser?.page_errors || [],
+        request_failures: response.result.browser?.request_failures || [],
+        http_errors: response.result.browser?.http_errors || [],
+    };
+    const browserFailed = Object.values(browserFailures).some((values) => values.length > 0);
+    const screenshotSha256 = createHash("sha256").update(await readFile(screenshot)).digest("hex");
+    await reportBrowserActivity(asset, activityOperation, {
+        source_hash: hash,
+        view,
+        viewport: flag(parsed, "viewport", "desktop"),
+        runtime_fingerprint: response.result.runtime?.runtime_fingerprint,
+        runtime_ready: response.result.runtime?.runtime_ready,
+        console_error_count: browserFailures.console_errors.length + browserFailures.page_errors.length,
+        network_error_count: browserFailures.request_failures.length + browserFailures.http_errors.length,
+        screenshot_sha256: screenshotSha256,
+        status: browserFailed ? "failed" : "completed",
+    });
+    if (inspect) {
+        await mkdir(root, { recursive: true });
+        await writeFile(path.join(root, "runtime.json"), `${JSON.stringify(response.result.runtime, null, 2)}\n`);
+        await writeFile(path.join(root, "browser.json"), `${JSON.stringify(response.result.browser, null, 2)}\n`);
+        await writeFile(path.join(root, "preflight.json"), `${JSON.stringify(preflight, null, 2)}\n`);
+        await writeFile(path.join(root, "source-hash.txt"), `${hash}\n`);
+        if (browserFailed)
+            throw new CliError("Studio inspection captured browser or network errors.", "STUDIO_BROWSER_DIAGNOSTICS_FAILED", 1, { ...browserFailures, output: root });
+        return { ok: true, command: "studio.inspect", asset, view, output: root, screenshot, runtime: path.join(root, "runtime.json"), browser: path.join(root, "browser.json"), preflight: path.join(root, "preflight.json"), source_hash: hash };
+    }
+    if (browserFailed)
+        throw new CliError("Studio capture reported browser or network errors.", "STUDIO_BROWSER_DIAGNOSTICS_FAILED", 1, browserFailures);
+    return { ok: true, command: "studio.screenshot", asset, view, path: screenshot, source_hash: hash, browser: response.result.browser, runtime: response.result.runtime };
+}
+async function initInstructions(provider) {
+    const name = provider === "claude" ? "CLAUDE.md" : provider === "codex" ? "AGENTS.md" : "NERDBRO_AGENT.md";
+    const target = path.resolve(name);
+    let existing = "";
+    try {
+        existing = await readFile(target, "utf8");
+    }
+    catch { /* new file */ }
+    if (!existing.includes("# NerdBro Interactive Studio agent")) {
+        if (existing)
+            await appendFile(target, `\n${INSTRUCTIONS}`);
+        else
+            await writeFile(target, INSTRUCTIONS);
+    }
+    const active = await readAttemptPointer();
+    if (active?.pointer.mode === "benchmark" && !existing.includes("## NerdBro benchmark completion")) {
+        await appendFile(target, `\n## NerdBro benchmark completion\n\nThis workspace is Attempt ${active.pointer.attempt_id}. Preserve observable command outputs and decisions. Before stopping, write REPORT.md with what was built, completed and incomplete work, asset and revision IDs, certification and approval status, and reviewer next steps. Write EVALUATION.md with educational-runtime, language, tooling, documentation and browser ratings; what worked, exact failures, workarounds, your own mistakes, platform limitations and prioritized product fixes. Do not include private chain-of-thought or credentials. Run \`nerdbro attempt finish --outcome completed|blocked|incomplete|abandoned\` with the accurate outcome and report the Attempt ID, client bundle path and SHA-256.\n`);
+    }
+    return { ok: true, command: "agent.init", provider, path: target, credentials_written: false };
+}
+// ---------------------------------------------------------------------------
+// Library authoring (experience, audio, component, behavior). A thin client of
+// /v1/agent/authoring: every semantic rule, template and certification lives on
+// the server. There is deliberately no approve or publish command.
+// ---------------------------------------------------------------------------
+const LIBRARY_ACTIONS = ["create", "checkout", "status", "save", "validate", "certify", "preview", "export", "inspect-browser"];
+const PREVIEW_KINDS = ["experience", "behavior"];
+const AUTHORING_SEARCH_KINDS = ["experience", "audio"];
+function authoringRoute(kind, stableId, suffix = "") {
+    return `/v1/agent/authoring/${kind}${stableId === undefined ? "" : `/${encodeURIComponent(stableId)}`}${suffix}`;
+}
+function libraryWorkspace(parsed, kind, stableId) {
+    return new LibraryWorkspace(path.resolve(flag(parsed, "workspace", path.join(process.cwd(), "nerdbro-studio"))), kind, stableId);
+}
+async function readJsonObject(file, code) {
+    try {
+        const value = JSON.parse(await readFile(path.resolve(file), "utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("not a JSON object");
+        return value;
+    }
+    catch (error) {
+        throw new CliError(`Cannot read ${file}: ${String(error)}`, code, 2);
+    }
+}
+export async function libraryCreateBody(parsed, stableId) {
+    const body = { stable_id: stableId, name: required(flag(parsed, "name"), "--name is required.") };
+    const mapping = [
+        ["category", "category"],
+        ["visual", "visual"],
+        ["palette", "palette"],
+        ["implementation", "implementation"],
+        ["media", "audio_media_sha256"],
+        ["language", "language"],
+        ["description", "description"],
+        ["kind", "experience_kind"],
+        ["master-audio", "master_audio"],
+    ];
+    for (const [option, field] of mapping) {
+        const value = flag(parsed, option);
+        if (value !== undefined)
+            body[field] = value;
+    }
+    if (parsed.flags.has("declarative"))
+        body.implementation = "declarative";
+    const duration = flag(parsed, "duration-ms");
+    if (duration !== undefined) {
+        if (!/^\d+$/.test(duration) || Number(duration) <= 0)
+            throw new CliError("--duration-ms must be a positive integer.", "AGENT_ARGUMENT_INVALID", 2);
+        body.duration_ms = Number(duration);
+    }
+    const sceneAsset = flag(parsed, "scene-asset");
+    const scenePackage = flag(parsed, "scene-package");
+    if (sceneAsset && scenePackage)
+        throw new CliError("Use either --scene-asset or --scene-package, not both.", "AGENT_ARGUMENT_INVALID", 2);
+    if (sceneAsset)
+        body.scene = { asset: sceneAsset };
+    if (scenePackage)
+        body.scene = { package: scenePackage, scene: required(flag(parsed, "scene"), "--scene <scene-id> is required with --scene-package.") };
+    const documentFile = flag(parsed, "document");
+    if (documentFile)
+        body.document = await readJsonObject(documentFile, "LIBRARY_SOURCE_INVALID");
+    return body;
+}
+async function libraryCheckout(parsed, kind, stableId) {
+    const target = libraryWorkspace(parsed, kind, stableId);
+    if (!parsed.flags.has("force"))
+        await target.assertNoLocalChanges();
+    const remote = await api("GET", `${authoringRoute(kind, stableId)}?purpose=checkout`);
+    const document = remote.document;
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+        throw new CliError(`${kind} ${stableId} has no document to check out.`, "LIBRARY_SOURCE_UNAVAILABLE");
+    }
+    const hash = sourceHash(document);
+    const now = new Date().toISOString();
+    const lock = {
+        schema: "kheleshikhi.library-lock.v1",
+        kind,
+        stable_id: stableId,
+        server_origin: (await readConfig()).apiOrigin,
+        head_revision_public_id: remote.head_revision?.public_id || null,
+        source_hash: hash,
+        schema_version: remote.schema_version ?? null,
+        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 };
+}
+async function libraryStatus(parsed, kind, stableId) {
+    const target = libraryWorkspace(parsed, kind, stableId);
+    const [source, lock] = await Promise.all([target.source(), target.lock()]);
+    const remote = await api("GET", `${authoringRoute(kind, stableId)}?purpose=status`);
+    const localHash = sourceHash(source);
+    const remoteHead = remote.head_revision?.public_id || null;
+    const localChanged = localHash !== lock.source_hash;
+    const remoteChanged = remoteHead !== lock.head_revision_public_id;
+    return {
+        ok: true,
+        command: `${kind}.status`,
+        kind,
+        stable_id: stableId,
+        local_source_hash: localHash,
+        local_changed: localChanged,
+        base_revision_public_id: lock.head_revision_public_id,
+        remote_revision_public_id: remoteHead,
+        remote_changed: remoteChanged,
+        conflict: localChanged && remoteChanged,
+        head_revision: remote.head_revision || null,
+        approved_revision: remote.approved_revision || null,
+        schema_version: remote.schema_version ?? null,
+        schema_changed: (remote.schema_version ?? null) !== lock.schema_version,
+    };
+}
+async function librarySave(parsed, kind, stableId) {
+    const target = libraryWorkspace(parsed, kind, stableId);
+    const [source, lock] = await Promise.all([target.source(), target.lock()]);
+    const base = required(lock.head_revision_public_id || undefined, "The lock has no base revision; run checkout again.");
+    const hash = sourceHash(source);
+    let saved;
+    try {
+        saved = await api("POST", authoringRoute(kind, stableId, "/drafts"), { document: source, base_revision_public_id: base });
+    }
+    catch (error) {
+        if (error instanceof CliError && error.exitCode === 3) {
+            throw new CliError(error.message, "VOCABULARY_DRAFT_CONFLICT", 3, { ...structuredErrorDetails(error.details), local_source_preserved: true, source: target.sourcePath, base_revision_public_id: base });
+        }
+        throw error;
+    }
+    const updated = libraryLockAfterSave(lock, saved, hash);
+    await target.writeLock(updated);
+    return { ok: true, command: `${kind}.save`, kind, stable_id: stableId, source_hash: hash, draft_created: saved.draft_created !== false, reason: saved.reason || null, head_revision: saved.head_revision || null, approval: "not_requested" };
+}
+async function libraryRevision(parsed, kind, stableId) {
+    const explicit = flag(parsed, "revision");
+    if (explicit)
+        return explicit;
+    const lock = await libraryWorkspace(parsed, kind, stableId).lock();
+    return required(lock.head_revision_public_id || undefined, "--revision is required (the lock has no head revision).");
+}
+async function libraryCheck(parsed, kind, stableId, action) {
+    const revision = await libraryRevision(parsed, kind, stableId);
+    const result = await api("POST", authoringRoute(kind, stableId, `/revisions/${encodeURIComponent(revision)}/${action}`));
+    if (action === "certify" && result.certified === false) {
+        throw new CliError("Certification did not pass; see details for outstanding profiles.", "LIBRARY_CERTIFICATION_FAILED", 1, result);
+    }
+    return { ok: true, command: `${kind}.${action}`, kind, stable_id: stableId, revision, result, approval: action === "certify" ? "requires_human" : "not_requested" };
+}
+async function libraryPreview(parsed, kind, stableId) {
+    const target = libraryWorkspace(parsed, kind, stableId);
+    const source = await target.source();
+    const preview = await api("POST", `/v1/agent/authoring/${kind}/preview`, { document: source });
+    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) }
+        : { 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 };
+}
+async function libraryExport(parsed, kind, stableId) {
+    const revision = required(flag(parsed, "revision"), "--revision is required.");
+    if (!/^[A-Za-z0-9_-]+$/.test(revision))
+        throw new CliError("Revision contains unsafe characters.", "AGENT_ARGUMENT_INVALID", 2);
+    const out = path.resolve(flag(parsed, "out", `${stableId}-${revision}.kspkg`));
+    if (!out.endsWith(".kspkg"))
+        throw new CliError("Export output must end in .kspkg.", "LIBRARY_EXPORT_EXTENSION_INVALID", 2);
+    await ensureCompatibility();
+    const bytes = await rawBinaryApi("GET", authoringRoute(kind, stableId, `/revisions/${encodeURIComponent(revision)}/export.kspkg`), "LIBRARY_EXPORT_INVALID");
+    await mkdir(path.dirname(out), { recursive: true });
+    await writeFile(out, bytes);
+    return { ok: true, command: `${kind}.export`, kind, stable_id: stableId, revision, path: out, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex"), approved_revision_only: true };
+}
+async function audioUpload(file) {
+    let byteSize;
+    try {
+        const info = await stat(file);
+        if (!info.isFile())
+            throw new Error("not a file");
+        byteSize = info.size;
+    }
+    catch {
+        throw new CliError("Cannot read the audio file.", "AUDIO_FILE_UNREADABLE", 2);
+    }
+    const extension = audioUploadExtension(file, byteSize);
+    const bytes = await readFile(file);
+    audioUploadExtension(file, bytes.length); // the file may have grown since stat
+    const media = await uploadApi("/v1/agent/audio/media", extension, "audio/mp4", new Uint8Array(bytes));
+    // Deliberately no local path, filename, or bytes in the result.
+    return {
+        ok: true,
+        command: "audio.upload",
+        sha256: media.sha256,
+        duration_ms: media.durationMs ?? null,
+        byte_size: media.byteSize ?? bytes.length,
+        media_type: media.mediaType ?? null,
+        codec: media.codec ?? null,
+        sample_rate: media.sampleRate ?? null,
+        channels: media.channels ?? null,
+        public_id: media.publicId ?? null,
+        next: `nerdbro audio create <stable-id> --name <text> --media ${media.sha256}`,
+    };
+}
+async function libraryInspectBrowser(parsed, kind, stableId) {
+    const target = libraryWorkspace(parsed, kind, stableId);
+    const viewport = flag(parsed, "viewport", "desktop");
+    const studioWorkspace = LIBRARY_STUDIO_WORKSPACE[kind];
+    let warning = null;
+    let expectedRevision;
+    let expectedHash;
+    try {
+        const [source, lock] = await Promise.all([target.source(), target.lock()]);
+        if (sourceHash(source) !== lock.source_hash)
+            warning = "Local source.json has unsaved changes; the Studio shows the saved server head.";
+        expectedRevision = lock.head_revision_public_id || undefined;
+        if (!warning)
+            expectedHash = lock.source_hash;
+    }
+    catch { /* no local checkout: the capture shows the server head */ }
+    await ensureCompatibility();
+    await mkdir(target.directory, { recursive: true });
+    const response = await daemonRpc("/browser/capture", {
+        method: "POST",
+        body: JSON.stringify({ asset: stableId, sourceHash: "", viewport, out: target.screenshotPath, timeoutMs: Number(flag(parsed, "timeout", "30000")), library: { workspace: studioWorkspace, selection: stableId, revision: expectedRevision, definitionHash: expectedHash } }),
+    });
+    const browser = response.result.browser || {};
+    const consoleErrors = (browser.console_errors?.length || 0) + (browser.page_errors?.length || 0);
+    const networkErrors = (browser.request_failures?.length || 0) + (browser.http_errors?.length || 0);
+    const failed = consoleErrors + networkErrors > 0;
+    const browserPath = path.join(target.directory, "browser.json");
+    await writeFile(browserPath, `${JSON.stringify(browser, null, 2)}\n`);
+    const activity = {
+        operation: "browser.capture",
+        subject: `${kind}:${stableId}`,
+        workspace: studioWorkspace,
+        viewport,
+        screenshot_sha256: createHash("sha256").update(await readFile(target.screenshotPath)).digest("hex"),
+        console_error_count: consoleErrors,
+        network_error_count: networkErrors,
+        status: failed ? "failed" : "completed",
+    };
+    if (failed)
+        throw new CliError("Studio Library capture reported browser or network errors.", "STUDIO_BROWSER_DIAGNOSTICS_FAILED", 1, { activity, browser: browserPath });
+    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 === "audio" && action === "upload")
+        return audioUpload(required(argument, "Audio file is required."));
+    if (AUTHORING_SEARCH_KINDS.includes(kind) && action === "search") {
+        const parameters = new URLSearchParams({ query: parsed.args.slice(2).join(" ") });
+        const limit = flag(parsed, "limit");
+        if (limit)
+            parameters.set("limit", limit);
+        return { ok: true, command: `${kind}.search`, result: await api("GET", `${authoringRoute(kind)}?${parameters}`) };
+    }
+    if (AUTHORING_SEARCH_KINDS.includes(kind) && action === "inspect") {
+        const stableId = required(argument, "Stable id is required.");
+        return { ok: true, command: `${kind}.inspect`, result: await api("GET", `${authoringRoute(kind, stableId)}?purpose=inspect`) };
+    }
+    if (!action || !LIBRARY_ACTIONS.includes(action))
+        return undefined;
+    if ((action === "preview" || action === "export") && !PREVIEW_KINDS.includes(kind))
+        return undefined;
+    const stableId = required(argument, "Stable id is required.");
+    libraryWorkspace(parsed, kind, stableId);
+    if (action === "create") {
+        const created = await api("POST", authoringRoute(kind), await libraryCreateBody(parsed, stableId));
+        return { ok: true, command: `${kind}.create`, kind, stable_id: created.stable_id || stableId, head_revision: created.head_revision || null, approval: created.approval || "not_requested", next: `nerdbro ${kind} checkout ${created.stable_id || stableId}` };
+    }
+    if (action === "checkout")
+        return libraryCheckout(parsed, kind, stableId);
+    if (action === "status")
+        return libraryStatus(parsed, kind, stableId);
+    if (action === "save")
+        return librarySave(parsed, kind, stableId);
+    if (action === "validate" || action === "certify")
+        return libraryCheck(parsed, kind, stableId, action);
+    if (action === "preview")
+        return libraryPreview(parsed, kind, stableId);
+    if (action === "export")
+        return libraryExport(parsed, kind, stableId);
+    return libraryInspectBrowser(parsed, kind, stableId);
+}
+async function run(parsed) {
+    const [first, second, third] = parsed.args;
+    assertSupportedFlags(parsed);
+    if (!first || first === "help" || first === "--help")
+        return help();
+    if (first === "--version" || first === "version")
+        return { ok: true, command: "version", version: VERSION };
+    if (first === "_daemon") {
+        await runDaemon({ apiOrigin: validateOrigin(required(flag(parsed, "origin"), "Daemon origin is required.")), headless: parsed.flags.has("headless"), noBrowser: parsed.flags.has("no-browser"), version: flag(parsed, "version-tag", VERSION) });
+    }
+    if (first === "setup")
+        return setup();
+    if (first === "attempt") {
+        if (second === "start") {
+            const label = required(flag(parsed, "label"), "--label is required.");
+            const mode = flag(parsed, "mode", "authoring");
+            if (!["authoring", "benchmark"].includes(mode))
+                throw new CliError("--mode must be authoring or benchmark.", "ATTEMPT_MODE_INVALID", 2);
+            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 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") };
+        }
+        if (second === "current") {
+            const active = await readAttemptPointer();
+            return { ok: true, command: "attempt.current", attempt_id: active?.pointer.attempt_id || null };
+        }
+        if (second === "status") {
+            const active = await readAttemptPointer();
+            const id = third || active?.pointer.attempt_id;
+            if (!id)
+                throw new CliError("No active workspace Attempt; pass an Attempt ID.", "ATTEMPT_NOT_ACTIVE", 2);
+            const status = await api("GET", `/v1/agent/attempts/${encodeURIComponent(id)}`);
+            return { ok: true, command: "attempt.status", ...status, folder: attemptDirectory(id) };
+        }
+        if (second === "finish") {
+            const active = await readAttemptPointer();
+            if (!active)
+                throw new CliError("No active workspace Attempt.", "ATTEMPT_NOT_ACTIVE", 2);
+            const id = active.pointer.attempt_id;
+            const server = await api("GET", `/v1/agent/attempts/${encodeURIComponent(id)}`);
+            const outcome = flag(parsed, "outcome");
+            if (!outcome || !["completed", "blocked", "incomplete", "abandoned"].includes(outcome))
+                throw new CliError("Pass --outcome completed|blocked|incomplete|abandoned.", "ATTEMPT_OUTCOME_REQUIRED", 2);
+            const bundle = await finalizeClient(active.pointer, active.workspace, { ...server, outcome });
+            await api("POST", `/v1/agent/attempts/${encodeURIComponent(id)}/finish`, { outcome });
+            return { ok: true, command: "attempt.finish", attempt_id: id, outcome, client_bundle: bundle.path, sha256: bundle.sha256, files: bundle.included, excluded: bundle.excluded };
+        }
+    }
+    if (first === "connect")
+        return connect();
+    if (first === "disconnect")
+        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 === "guide") {
+        const result = await api("GET", "/v1/agent/docs/agent-authoring-playbook");
+        return {
+            ok: true, command: "guide", playbook_version: result.playbook_version,
+            fingerprint: result.documentation_fingerprint, public_url: result.public_url,
+            markdown: result.markdown,
+        };
+    }
+    if (first === "docs") {
+        if (!second)
+            return { ok: true, command: "docs", result: await api("GET", "/v1/agent/docs") };
+        if (second === "search") {
+            const query = parsed.args.slice(2).join(" ");
+            return { ok: true, command: "docs.search", result: await api("GET", `/v1/agent/docs/search?q=${encodeURIComponent(query)}`) };
+        }
+        if (second === "open") {
+            const slug = required(third, "Documentation slug is required.");
+            const result = await api("GET", `/v1/agent/docs/${encodeURIComponent(slug)}`);
+            return parsed.json ? { ok: true, command: "docs.open", result } : String(result.markdown || "");
+        }
+    }
+    if (first === "config" && second === "set" && third === "origin") {
+        const origin = validateOrigin(required(parsed.args[3], "Origin URL is required."));
+        let daemonStopped = false;
+        try {
+            await daemonRpc("/stop", { method: "POST", body: "{}" });
+            daemonStopped = true;
+        }
+        catch (error) {
+            if (!(error instanceof CliError) || !["AGENT_DAEMON_NOT_RUNNING", "AGENT_DAEMON_UNAVAILABLE"].includes(error.code))
+                throw error;
+        }
+        await writeConfig({ apiOrigin: origin });
+        return { ok: true, command: "config.set.origin", origin, daemon_stopped: daemonStopped, reconnect_required: true };
+    }
+    if (first === "agent") {
+        if (second === "start")
+            return { ok: true, command: "agent.start", ...(await startDaemon(true)) };
+        if (second === "status")
+            return { command: "agent.status", ...(await daemonRpc("/status")) };
+        if (second === "stop")
+            return { command: "agent.stop", ...(await daemonRpc("/stop", { method: "POST", body: "{}" })) };
+        if (second === "instructions")
+            return INSTRUCTIONS;
+        if (second === "init")
+            return initInstructions(required(flag(parsed, "provider", "generic"), "Provider is required."));
+    }
+    if (["component", "behavior", "example"].includes(first)) {
+        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}`) };
+        }
+        if (second === "inspect")
+            return { ok: true, command: `${first}.inspect`, result: await api("GET", `/v1/agent/catalogue/${plural}/${encodeURIComponent(required(third, "ID is required."))}`) };
+    }
+    if (isLibraryKind(first)) {
+        const result = await library(parsed, first, second, third);
+        if (result !== undefined)
+            return result;
+    }
+    if (first === "studio") {
+        const action = required(second, "Studio command is required.");
+        if (action === "create") {
+            const title = required(flag(parsed, "title"), "--title is required.");
+            const target = required(flag(parsed, "target"), "--target is required.");
+            const concept = required(flag(parsed, "concept"), "--concept is required.");
+            const brief = {
+                concept,
+                teaching_purpose: flag(parsed, "teaching-purpose"),
+                learner_action: flag(parsed, "learner-action"),
+                expected_visual_behavior: flag(parsed, "expected-visual-behavior"),
+                graph_purpose: flag(parsed, "graph-purpose"),
+                graph_x_semantics: flag(parsed, "graph-x"),
+                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")),
+                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),
+            };
+            const result = await api("POST", "/v1/agent/studio", {
+                client_command_id: flag(parsed, "command-id", randomUUID()),
+                title, authoring_target: target, brief,
+            });
+            // 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 };
+        }
+        if (action === "brief") {
+            const updating = third === "update";
+            const briefAsset = required(updating ? parsed.args[3] : third, "Asset ID is required.");
+            const route = `/v1/agent/studio/${encodeURIComponent(briefAsset)}/brief`;
+            if (!updating)
+                return { ok: true, command: "studio.brief", result: await api("GET", route) };
+            const current = await api("GET", route);
+            const names = {
+                concept: "concept", "teaching-purpose": "teaching_purpose",
+                "learner-action": "learner_action", "expected-visual-behavior": "expected_visual_behavior",
+                "graph-purpose": "graph_purpose", "graph-x": "graph_x_semantics",
+                "graph-y": "graph_y_semantics", "graph-sync": "graph_sync_semantics",
+                language: "language", "additional-instruction": "additional_instruction",
+                behavior: "selected_behavior",
+            };
+            const brief = { ...current.brief };
+            for (const [option, field] of Object.entries(names)) {
+                const value = flag(parsed, option);
+                if (value !== undefined)
+                    brief[field] = value;
+            }
+            if (parsed.flags.has("assessment"))
+                brief.requires_assessment = true;
+            if (parsed.flags.has("no-assessment"))
+                brief.requires_assessment = false;
+            if (flag(parsed, "graph-purpose"))
+                brief.requires_graph = true;
+            if (flag(parsed, "components"))
+                brief.selected_components = flag(parsed, "components").split(",").map((value) => value.trim()).filter(Boolean);
+            if (flag(parsed, "important-values"))
+                brief.important_values = flag(parsed, "important-values").split(",").map((value) => value.trim()).filter(Boolean);
+            const result = await api("PATCH", route, { brief, base_brief_hash: current.brief_hash });
+            return { ok: true, command: "studio.brief.update", result };
+        }
+        const asset = required(third, "Asset ID is required.");
+        const target = workspace(parsed, asset);
+        if (action === "checkout")
+            return checkout(parsed, asset);
+        if (action === "status")
+            return studioStatus(parsed, asset);
+        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 (action === "history")
+            return { ok: true, command: "studio.history", asset, result: await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}/history`) };
+        if (action === "save") {
+            const source = await target.source();
+            const lock = await target.lock();
+            const hash = sourceHash(source);
+            try {
+                const saved = await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/drafts`, { source, base_snapshot_public_id: lock.base_snapshot_public_id, base_revision_public_id: lock.base_revision_public_id });
+                await target.writeLock(studioLockAfterSave(lock, saved, hash));
+                return { ok: true, command: "studio.save", asset, source_hash: hash, saved: saved.saved !== false, changed: saved.changed !== false, draft_created: saved.draft_created !== false, reason: saved.reason || null, draft: saved, approval: "not_requested" };
+            }
+            catch (error) {
+                if (error instanceof CliError && (error.exitCode === 3 || error.code === "AGENT_NETWORK_FAILURE")) {
+                    try {
+                        const remote = await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}/status`);
+                        const reconciled = reconciledStudioLock(lock, remote, hash);
+                        if (reconciled) {
+                            await target.writeLock(reconciled);
+                            return { ok: true, command: "studio.save", asset, source_hash: hash, saved: true, changed: false, draft_created: false, reconciled: true, reason: "identical_remote_head", draft: remote.head_snapshot, approval: "not_requested" };
+                        }
+                    }
+                    catch { /* The original save error remains the useful failure. */ }
+                }
+                if (error instanceof CliError && error.exitCode === 3)
+                    throw new CliError(error.message, "STUDIO_DRAFT_CONFLICT", 3, { ...structuredErrorDetails(error.details), local_source_preserved: true, source: target.sourcePath });
+                throw error;
+            }
+        }
+        if (action === "open") {
+            const view = flag(parsed, "view", "canvas");
+            if (!VIEW_QUERY[view])
+                throw new CliError(`Unknown Studio view: ${view}`, "STUDIO_VIEW_INVALID", 2);
+            const context = await api("GET", "/v1/agent/context");
+            const publicUrl = required(String(context.authoring_playbook_url || ""), "Server did not provide a public Studio origin.");
+            const url = new URL(`/maker/interactive/studio/${encodeURIComponent(asset)}`, new URL(publicUrl).origin);
+            url.search = new URLSearchParams(VIEW_QUERY[view]).toString();
+            openExternal(url.toString());
+            await reportBrowserActivity(asset, "browser.open", { view, status: "completed" });
+            return { ok: true, command: "studio.open", asset, view, url: url.toString(), browser: "system" };
+        }
+        if (action === "screenshot")
+            return capture(parsed, asset, false);
+        if (action === "inspect")
+            return capture(parsed, asset, true);
+        if (action === "observe") {
+            const result = await capture({ ...parsed, flags: new Map(parsed.flags).set("out", path.join(stateDirectory(), "last-observation.png")) }, asset, false, "browser.observe");
+            return { ok: true, command: "studio.observe", asset, source_hash: result.source_hash, runtime: result.runtime, browser: result.browser };
+        }
+        if (action === "drive") {
+            const scenarioPath = required(flag(parsed, "scenario"), "--scenario <file.json> is required.");
+            const scenarioFile = path.resolve(scenarioPath);
+            if ((await stat(scenarioFile)).size > 65536)
+                throw new CliError("Scenario exceeds 64 KiB.", "STUDIO_SCENARIO_INVALID", 2);
+            let scenarioDocument;
+            try {
+                scenarioDocument = JSON.parse(await readFile(scenarioFile, "utf8"));
+            }
+            catch {
+                throw new CliError("Scenario is not valid JSON.", "STUDIO_SCENARIO_INVALID", 2);
+            }
+            const scenario = parseScenario(scenarioDocument);
+            const candidate = await target.source();
+            const hash = sourceHash(candidate);
+            const remote = await studioStatus(parsed, asset);
+            const remoteHash = String(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.
+            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", `studio-drive-${asset}-${Date.now()}`));
+            await mkdir(destination, { recursive: true });
+            const scenarioHash = createHash("sha256").update(JSON.stringify(scenario)).digest("hex");
+            const driveMetadata = { source_hash: hash, view: "learner", viewport: flag(parsed, "viewport", "desktop"), scenario_hash: scenarioHash, step_count: scenario.steps.length };
+            let response;
+            try {
+                response = await daemonRpc("/browser/drive", {
+                    method: "POST",
+                    body: JSON.stringify({ asset, sourceHash: remoteHash, candidate, candidateHash: hash, scenario,
+                        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);
+                throw error;
+            }
+            await writeFile(path.join(destination, "result.json"), `${JSON.stringify(response.result, null, 2)}\n`);
+            await reportBrowserActivity(asset, "studio.drive", { ...driveMetadata, status: "completed" });
+            return { ok: true, command: "studio.drive", asset, source_hash: hash, output: destination,
+                result: path.join(destination, "result.json"), steps: scenario.steps.length };
+        }
+        if (action === "capture-preview") {
+            const { hash } = await assertBrowserSource(parsed, asset);
+            const destination = path.resolve(flag(parsed, "out", `preview-capture-${new Date().toISOString().replace(/[:.]/g, "-")}`));
+            const response = await daemonRpc("/browser/preview-observation", {
+                method: "POST",
+                body: JSON.stringify({
+                    asset, sourceHash: hash, out: destination,
+                    viewport: flag(parsed, "viewport", "480x320"),
+                    mode: flag(parsed, "mode", "semantic"),
+                    duration: Number(flag(parsed, "duration", "8")),
+                    fps: Number(flag(parsed, "fps", "4")),
+                    timeoutMs: Number(flag(parsed, "timeout", "30000")),
+                }),
+            });
+            const result = response.result;
+            await reportBrowserActivity(asset, "browser.observe", {
+                source_hash: hash,
+                status: "completed",
+                view: "canvas",
+                viewport: flag(parsed, "viewport", "480x320"),
+                runtime_fingerprint: result.manifest?.runtime_fingerprint,
+                runtime_ready: true,
+                screenshot_sha256: createHash("sha256").update(await readFile(result.contact_sheet)).digest("hex"),
+            });
+            return {
+                ok: true, command: "studio.capture-preview", asset, source_hash: hash,
+                manifest: result.manifest, timeline: result.timeline,
+                output: result.output, contact_sheet: result.contact_sheet, frames: result.frames,
+            };
+        }
+        if (action === "certify") {
+            const { source } = await assertBrowserSource(parsed, asset);
+            const observed = await capture({ ...parsed, flags: new Map(parsed.flags).set("out", path.join(stateDirectory(), "last-certification.png")) }, asset, false, "browser.observe");
+            const runtimeObservation = certificationRuntimeObservation(observed.runtime);
+            return { ok: true, command: "studio.certify", asset, result: await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/certify`, { source, runtime_observation: runtimeObservation }) };
+        }
+        if (action === "export") {
+            const revision = required(flag(parsed, "revision"), "--revision is required.");
+            const out = path.resolve(flag(parsed, "out", `${asset}-${revision}.kspkg`));
+            if (!out.endsWith(".kspkg"))
+                throw new CliError("Export output must end in .kspkg.", "STUDIO_EXPORT_EXTENSION_INVALID", 2);
+            await ensureCompatibility();
+            const bytes = await rawBinaryApi("GET", `/v1/agent/studio/${encodeURIComponent(asset)}/revisions/${encodeURIComponent(revision)}/export`);
+            await mkdir(path.dirname(out), { recursive: true });
+            await writeFile(out, bytes);
+            return { ok: true, command: "studio.export", asset, revision, path: out, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex"), format: "kheleshikhi.package.v2/interactivePart", approved_revision_only: true };
+        }
+    }
+    throw new CliError(`Unknown command: ${parsed.args.join(" ")}`, "AGENT_COMMAND_UNKNOWN", 2);
+}
+function help() {
+    return [
+        `NerdBro Studio Agent ${VERSION}`,
+        "",
+        "Commands: setup, connect, disconnect, whoami, context, guide, schema [topic], capabilities",
+        "  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 open|screenshot|inspect|observe|capture-preview|certify <asset>",
+        "  studio drive <asset> --scenario scenario.json [--workspace dir] [--viewport desktop|mobile] [--out dir]",
+        "  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 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|...>",
+        "      (--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]",
+        "  behavior create <stable-id> --name <text> [--declarative]",
+        "  <kind> checkout <stable-id> [--workspace dir] [--force]",
+        "  <kind> status|save <stable-id> [--workspace dir]",
+        "  <kind> validate|certify <stable-id> [--revision <revision>]",
+        "  experience|behavior preview <stable-id>      local source.json -> preview.json",
+        "  experience|behavior export <stable-id> --revision <revision> [--out file.kspkg]",
+        "  <kind> inspect-browser <stable-id> [--viewport desktop|mobile|WxH]",
+        "",
+        "Flow: create or checkout -> edit source.json -> status -> save (draft) -> validate -> certify.",
+        "Certification is technical evidence; approval and publication are human-only in the Studio.",
+        "Docs, schemas and contracts are fetched live from the server; none is bundled.",
+        "",
+        "Every command supports --json.",
+        "Finish an Attempt with: attempt finish --outcome completed|blocked|incomplete|abandoned.",
+    ].join("\n");
+}
+async function main() {
+    const parsed = parse(process.argv.slice(2));
+    let active = null;
+    let commandId;
+    try {
+        if (!["_daemon", "--version", "version", "help", "--help"].includes(parsed.args[0] || "")) {
+            active = await readAttemptPointer();
+            commandId = `cmd_${randomUUID().replaceAll("-", "")}`;
+            setCliTrace({ attemptId: active?.pointer.attempt_id, commandId });
+        }
+        const result = await run(parsed);
+        if (active && commandId && parsed.args[0] !== "attempt")
+            await saveCommandEvidence(active.pointer, commandId, parsed.args.slice(0, 2).join("."), result);
+        output(result, parsed.json);
+    }
+    catch (error) {
+        const failure = error instanceof CliError ? error : new CliError(String(error));
+        if (active && commandId)
+            await saveCommandEvidence(active.pointer, commandId, parsed.args.slice(0, 2).join("."), { ok: false, code: failure.code, message: failure.message }).catch(() => undefined);
+        const result = { ok: false, code: failure.code, message: failure.message, details: failure.details };
+        if (parsed.json)
+            output(result, true);
+        else
+            process.stderr.write(`nerdbro: ${failure.message}\n`);
+        process.exitCode = failure.exitCode;
+    }
+}
+function invokedAsMain() {
+    const executable = process.argv[1];
+    if (!executable)
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(executable);
+    }
+    catch {
+        return fileURLToPath(import.meta.url) === path.resolve(executable);
+    }
+}
+if (invokedAsMain())
+    void main();
+//# sourceMappingURL=cli.js.map