speqs 0.5.1 → 0.7.0

package/dist/commands/simulation.js

@@ -4,18 +4,138 @@
  * Primary command: `speqs simulation run` — orchestrates the full flow:
  *   1. Creates iteration (if not provided)
  *   2. Creates testers from profiles
- *   3. Starts simulations
+ *   3. Starts simulations (interactive or media, based on study modality)
  */
 import * as readline from "node:readline/promises";
-import { withClient, getWebUrl, terminalLink } from "../lib/command-helpers.js";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy } from "../lib/command-helpers.js";
 import { resolveId } from "../lib/alias-store.js";
-import { output, outputError, formatSimulationPoll } from "../lib/output.js";
+import { output, formatSimulationPoll } from "../lib/output.js";
 function parseMaxInteractions(value) {
     const n = parseInt(value, 10);
     if (isNaN(n) || n < 1)
         throw new Error(`Invalid --max-interactions value: ${value}`);
     return n;
 }
+function parseSlowMo(value) {
+    const n = parseInt(value, 10);
+    if (isNaN(n) || n < 0)
+        throw new Error(`Invalid --slow-mo value: ${value}`);
+    return n;
+}
+import { MEDIA_MODALITIES } from "../lib/types.js";
+import { resolveContentUrl, resolveContentUrls, resolveTextContent } from "../lib/upload.js";
+import { runLocalSimulations } from "../lib/local-sim/loop.js";
+import { ensureBrowser } from "../lib/local-sim/install.js";
+function isMediaModality(modality) {
+    return !!modality && MEDIA_MODALITIES.includes(modality);
+}
+/**
+ * Build iteration details based on study modality and CLI options.
+ */
+function buildCopyContent(opts) {
+    if (!opts.copyText)
+        return undefined;
+    return {
+        text: opts.copyText,
+        ...(opts.copyHtml && { html: opts.copyHtml }),
+        ...(opts.socialPlatform && { social_platform: opts.socialPlatform }),
+        ...(opts.copyPosition && { position: opts.copyPosition }),
+    };
+}
+function buildIterationDetails(modality, opts) {
+    switch (modality) {
+        case "text":
+            if (!opts.contentText) {
+                throw new Error("Text studies require --content-text. Provide the text content to evaluate.");
+            }
+            return {
+                type: "text",
+                content_text: opts.contentText,
+                ...(opts.contentHtml && { content_html: opts.contentHtml }),
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+            };
+        case "video":
+        case "audio": {
+            if (!opts.contentUrl) {
+                throw new Error(`${modality} studies require --content-url. Provide the URL to the ${modality} file.`);
+            }
+            const copy = buildCopyContent(opts);
+            return {
+                type: modality,
+                content_url: opts.contentUrl,
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...(copy && { copy_content: copy }),
+            };
+        }
+        case "image": {
+            if (!opts.imageUrls) {
+                throw new Error("Image studies require --image-urls. Provide comma-separated image URLs.");
+            }
+            const copy = buildCopyContent(opts);
+            return {
+                type: "image",
+                image_urls: opts.imageUrls.split(",").map((s) => s.trim()).filter(Boolean),
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...(copy && { copy_content: copy }),
+            };
+        }
+        case "document":
+            if (!opts.contentUrl) {
+                throw new Error("Document studies require --content-url. Provide the URL to the document.");
+            }
+            return {
+                type: "document",
+                content_url: opts.contentUrl,
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+            };
+        default:
+            // Interactive
+            if (!opts.url) {
+                throw new Error("Interactive studies require --url. Provide the URL to test.");
+            }
+            return {
+                type: "interactive",
+                platform: opts.platform || "browser",
+                url: opts.url,
+                screen_format: opts.screenFormat || "desktop",
+                ...(opts.locale && { locale: opts.locale }),
+            };
+    }
+}
+/**
+ * Copy relevant fields from a previous iteration's details for reuse.
+ */
+function copyDetailsFromPrevious(modality, details) {
+    if (isMediaModality(modality)) {
+        const copy = details.copy_content;
+        return {
+            ...(typeof details.content_text === "string" && { contentText: details.content_text }),
+            ...(typeof details.content_html === "string" && { contentHtml: details.content_html }),
+            ...(typeof details.content_url === "string" && { contentUrl: details.content_url }),
+            ...(Array.isArray(details.image_urls) && { imageUrls: details.image_urls.join(",") }),
+            ...(typeof details.title === "string" && { title: details.title }),
+            ...(typeof details.mime_type === "string" && { mimeType: details.mime_type }),
+            ...(copy && typeof copy.text === "string" && { copyText: copy.text }),
+            ...(copy && typeof copy.html === "string" && { copyHtml: copy.html }),
+            ...(copy && typeof copy.social_platform === "string" && { socialPlatform: copy.social_platform }),
+            ...(copy && typeof copy.position === "string" && { copyPosition: copy.position }),
+        };
+    }
+    const screenFormat = typeof details.screen_format === "string"
+        ? details.screen_format
+        : typeof details.screenFormat === "string"
+            ? details.screenFormat
+            : undefined;
+    return {
+        ...(typeof details.platform === "string" && { platform: details.platform }),
+        ...(typeof details.url === "string" && { url: details.url }),
+        ...(screenFormat && { screenFormat }),
+    };
+}
 export function registerSimulationCommands(program) {
     const sim = program
         .command("simulation")
@@ -25,102 +145,236 @@ export function registerSimulationCommands(program) {
     sim
         .command("run")
         .description("Run simulations (creates iteration + testers + starts simulations)")
-        .requiredOption("--workspace <id>", "Workspace ID")
-        .requiredOption("--study <id>", "Study ID")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--study <id>", "Study ID")
         .option("--profiles <ids>", "Comma-separated tester profile IDs (auto-selected from last iteration if omitted)")
         .option("--iteration <id>", "Use existing iteration (skip creation)")
         .option("--iteration-name <name>", "Name for new iteration (forces creating a new iteration)")
-        .option("--platform <platform>", "Platform (browser, android, figma, code)")
-        .option("--url <url>", "URL to test")
-        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop)")
+        // Interactive options
+        .option("--platform <platform>", "Platform (browser, android, figma, code) — interactive only")
+        .option("--url <url>", "URL to test — interactive only")
+        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only")
+        // Media options
+        .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file — text modality")
+        .option("--content-html <html>", "HTML version of the text, or @filepath to read from file — text modality")
+        .option("--content-url <url>", "URL or local file path to media file — video, audio, document modalities")
+        .option("--image-urls <urls>", "Comma-separated image URLs or local file paths — image modality")
+        .option("--title <title>", "Content title — media modalities")
+        .option("--mime-type <type>", "MIME type (e.g. video/mp4) — media modalities")
+        // Copy/caption options (ads & social posts)
+        .option("--copy-text <text>", "Ad copy or social post caption (or @filepath) — ads & social posts")
+        .option("--copy-html <html>", "HTML version of copy text (or @filepath)")
+        .option("--social-platform <platform>", "Social platform (instagram, tiktok, facebook, linkedin, x)")
+        .option("--copy-position <pos>", "Copy position relative to media (before, after)", "after")
+        .option("--config <id>", "Simulation config ID (required for media, auto-resolved for interactive)")
+        // Shared options
         .option("--max-interactions <n>", "Max interactions per tester")
         .option("--language <lang>", "Language code (e.g. en, sv)")
         .option("--locale <locale>", "Locale code (e.g. en-US)")
         .option("-y, --yes", "Skip confirmation prompt")
+        // Local simulation options
+        .option("--local", "Run simulation with local browser (Playwright) instead of remote")
+        .option("--headed", "Show browser window (local mode only)")
+        .option("--slow-mo <ms>", "Slow down actions by ms (local mode only)")
+        .option("--devtools", "Open Chrome DevTools (local mode only)")
+        .option("--debug", "Enable detailed debug logging to stderr and ~/.speqs/local-sim.log")
+        .option("--parallel <n>", "Run N testers in parallel (local mode only, default: all)")
         .addHelpText("after", `
+Note: --workspace and --study are optional if you have set active context
+  via \`speqs workspace use <alias>\` and \`speqs study use <alias>\`.
+  Profiles and iteration settings are auto-reused from the latest iteration.
+
 Examples:
-  # Re-run with same settings and profiles as last time:
-  $ speqs sim run --workspace W --study S
+  # Re-run with same settings (after setting context):
+  $ speqs sim run -y
+
+  # Interactive — first run:
+  $ speqs sim run --workspace w-6ec --study s-b2c --profiles tp-795,tp-af2 --url https://example.com
+
+  # Text/email (inline or from file):
+  $ speqs sim run --content-text "Your email content..." --config c-c3c
+  $ speqs sim run --content-text @./email.html --config c-c3c
+
+  # Video (URL or local file):
+  $ speqs sim run --content-url ./video.mp4 --config c-c3c
 
-  # Re-run with different profiles:
-  $ speqs sim run --workspace W --study S --profiles p1,p2
+  # Image (local files):
+  $ speqs sim run --image-urls "./a.png,./b.png" --config c-c3c
 
-  # Force a new iteration:
-  $ speqs sim run --workspace W --study S --iteration-name "Round 2"
+  # Document:
+  $ speqs sim run --content-url ./report.pdf --config c-c3c
 
-  # First run (no previous iteration):
-  $ speqs sim run --workspace W --study S --profiles p1,p2 --url https://example.com`)
+  # Video ad with copy text:
+  $ speqs sim run --content-url ./ad.mp4 --copy-text "Buy now — 50% off!" --config c-c3c
+
+  # Social post with caption:
+  $ speqs sim run --image-urls ./post.png --copy-text @./caption.txt --social-platform instagram --config c-c3c
+
+  # Re-run existing iteration:
+  $ speqs sim run --iteration i-d4e
+
+  # Local browser simulation (no remote Browserbase):
+  $ speqs sim run --local --url http://localhost:3000
+  $ speqs sim run --local --url http://localhost:3000 --headed --slow-mo 500`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const log = (msg) => { if (!globals.quiet)
                 console.error(msg); };
-            // Step 0: Resolve defaults from latest iteration
-            let resolvedPlatform = opts.platform;
-            let resolvedUrl = opts.url;
-            let resolvedScreenFormat = opts.screenFormat;
+            const resolvedWorkspace = resolveWorkspace(opts.workspace);
+            const resolvedStudy = resolveStudy(opts.study);
+            if (opts.iteration && opts.iterationName) {
+                throw new Error("Cannot use both --iteration and --iteration-name. Use --iteration to reuse an existing iteration, or --iteration-name to create a new one.");
+            }
+            // Step 0: Fetch study to determine modality and resolve defaults
+            const study = await client.get(`/studies/${resolvedStudy}`);
+            const modality = study.modality || "interactive";
+            const isMedia = isMediaModality(modality);
+            if (!study.assignments || study.assignments.length === 0) {
+                throw new Error("Study has no assignments. Add tasks with --assignments when creating the study, or use `speqs study generate`.");
+            }
+            // Validate conflicting options
+            if (isMedia && opts.url) {
+                throw new Error(`This study uses "${modality}" modality — --url is for interactive studies. Use --content-text, --content-url, or --image-urls instead.`);
+            }
+            if (!isMedia && (opts.contentText || opts.contentUrl || opts.imageUrls)) {
+                throw new Error(`This study uses "interactive" modality — --content-text, --content-url, and --image-urls are for media studies. Use --url instead.`);
+            }
+            // Resolve defaults from latest iteration
             let profileIds = opts.profiles
                 ? opts.profiles.split(",").map((s) => s.trim()).filter(Boolean).map(resolveId)
                 : [];
             const profileNames = new Map();
             let iterationId = opts.iteration ? resolveId(opts.iteration) : undefined;
-            const resolvedWorkspace = resolveId(opts.workspace);
-            const resolvedStudy = resolveId(opts.study);
-            if (!iterationId || profileIds.length === 0 || !resolvedPlatform || !resolvedScreenFormat) {
-                const study = await client.get(`/studies/${resolvedStudy}`);
-                if (!study.assignments || study.assignments.length === 0) {
-                    outputError(new Error("Study has no assignments. Add tasks with --assignments when creating the study, or use `speqs study generate`."), globals.json);
-                    process.exit(1);
+            // Mutable copies for resolving from previous iteration
+            let resolvedOpts = { ...opts };
+            const iterations = study.iterations || [];
+            const latest = iterations.length > 0 ? iterations[iterations.length - 1] : null;
+            if (latest) {
+                const iterLabel = latest.label || latest.name || latest.id.slice(0, 8);
+                log(`Using iteration "${iterLabel}" as baseline`);
+                // Reuse iteration if not creating a new one
+                if (!iterationId && !opts.iterationName) {
+                    iterationId = latest.id;
                 }
-                const iterations = study.iterations || [];
-                const latest = iterations.length > 0 ? iterations[iterations.length - 1] : null;
-                if (latest) {
-                    const iterLabel = latest.label || latest.name || latest.id.slice(0, 8);
-                    log(`Using iteration "${iterLabel}" as baseline`);
-                    // Reuse iteration if not creating a new one
-                    if (!iterationId && !opts.iterationName) {
-                        iterationId = latest.id;
-                    }
-                    // Fill platform/url/screen-format from iteration details
-                    const details = latest.details;
-                    if (details) {
-                        if (!resolvedPlatform)
-                            resolvedPlatform = details.platform;
-                        if (!resolvedUrl)
-                            resolvedUrl = details.url;
-                        if (!resolvedScreenFormat)
-                            resolvedScreenFormat = details.screen_format || details.screenFormat;
-                    }
-                    // Auto-select profiles from latest iteration's testers
-                    if (profileIds.length === 0 && latest.testers && latest.testers.length > 0) {
-                        const seen = new Set();
-                        for (const t of latest.testers) {
-                            const pid = t.tester_profile_id || t.tester_profile?.id;
-                            if (pid && !seen.has(pid)) {
-                                seen.add(pid);
-                                profileIds.push(pid);
-                                const name = t.tester_profile?.name;
-                                if (name)
-                                    profileNames.set(pid, name);
-                            }
+                // Fill defaults from previous iteration details
+                const details = latest.details;
+                if (details) {
+                    const prev = copyDetailsFromPrevious(modality, details);
+                    if (!resolvedOpts.platform && prev.platform)
+                        resolvedOpts.platform = prev.platform;
+                    if (!resolvedOpts.url && prev.url)
+                        resolvedOpts.url = prev.url;
+                    if (!resolvedOpts.screenFormat && prev.screenFormat)
+                        resolvedOpts.screenFormat = prev.screenFormat;
+                    if (!resolvedOpts.contentText && prev.contentText)
+                        resolvedOpts.contentText = prev.contentText;
+                    if (!resolvedOpts.contentHtml && prev.contentHtml)
+                        resolvedOpts.contentHtml = prev.contentHtml;
+                    if (!resolvedOpts.contentUrl && prev.contentUrl)
+                        resolvedOpts.contentUrl = prev.contentUrl;
+                    if (!resolvedOpts.imageUrls && prev.imageUrls)
+                        resolvedOpts.imageUrls = prev.imageUrls;
+                    if (!resolvedOpts.title && prev.title)
+                        resolvedOpts.title = prev.title;
+                    if (!resolvedOpts.mimeType && prev.mimeType)
+                        resolvedOpts.mimeType = prev.mimeType;
+                    if (!resolvedOpts.copyText && prev.copyText)
+                        resolvedOpts.copyText = prev.copyText;
+                    if (!resolvedOpts.copyHtml && prev.copyHtml)
+                        resolvedOpts.copyHtml = prev.copyHtml;
+                    if (!resolvedOpts.socialPlatform && prev.socialPlatform)
+                        resolvedOpts.socialPlatform = prev.socialPlatform;
+                    if (!resolvedOpts.copyPosition && prev.copyPosition)
+                        resolvedOpts.copyPosition = prev.copyPosition;
+                }
+                // Auto-select profiles from latest iteration's testers
+                if (profileIds.length === 0 && latest.testers && latest.testers.length > 0) {
+                    const seen = new Set();
+                    for (const t of latest.testers) {
+                        const pid = t.tester_profile_id || t.tester_profile?.id;
+                        if (pid && !seen.has(pid)) {
+                            seen.add(pid);
+                            profileIds.push(pid);
+                            const name = t.tester_profile?.name;
+                            if (name)
+                                profileNames.set(pid, name);
                         }
                     }
                 }
             }
-            // Apply hardcoded fallbacks
-            resolvedPlatform = resolvedPlatform || "browser";
-            resolvedScreenFormat = resolvedScreenFormat || "desktop";
             if (profileIds.length === 0) {
-                outputError(new Error("No profiles specified and no previous iteration to copy from. Use --profiles <ids>."), globals.json);
-                process.exit(1);
+                throw new Error("No profiles specified and no previous iteration to copy from. Use --profiles <ids>.");
+            }
+            // Resolve local file paths → upload to storage and get URLs
+            if (isMedia) {
+                if (resolvedOpts.contentText) {
+                    resolvedOpts.contentText = resolveTextContent(resolvedOpts.contentText);
+                }
+                if (resolvedOpts.contentHtml) {
+                    resolvedOpts.contentHtml = resolveTextContent(resolvedOpts.contentHtml);
+                }
+                if (resolvedOpts.copyText) {
+                    resolvedOpts.copyText = resolveTextContent(resolvedOpts.copyText);
+                }
+                if (resolvedOpts.copyHtml) {
+                    resolvedOpts.copyHtml = resolveTextContent(resolvedOpts.copyHtml);
+                }
+                if (resolvedOpts.contentUrl) {
+                    resolvedOpts.contentUrl = await resolveContentUrl(client, resolvedStudy, resolvedOpts.contentUrl, { mimeTypeOverride: resolvedOpts.mimeType, quiet: globals.quiet });
+                }
+                if (resolvedOpts.imageUrls) {
+                    const urls = await resolveContentUrls(client, resolvedStudy, resolvedOpts.imageUrls, { mimeTypeOverride: resolvedOpts.mimeType, quiet: globals.quiet });
+                    resolvedOpts.imageUrls = urls.join(",");
+                }
             }
-            // Confirmation step — show resolved settings
+            // Resolve config_id for media simulations
+            const resolvedConfigOverride = opts.config ? resolveId(opts.config) : undefined;
+            const profileConfigMap = new Map();
+            if (isMedia && !resolvedConfigOverride) {
+                // Resolve config from each profile's simulation_config_id
+                for (const pid of profileIds) {
+                    const profile = await client.get(`/tester-profiles/${pid}`);
+                    if (profile.simulation_config_id) {
+                        profileConfigMap.set(pid, profile.simulation_config_id);
+                    }
+                    else {
+                        throw new Error(`Profile ${profileNames.get(pid) || pid} has no simulation config assigned.\n` +
+                            "Use --config <id> to specify one, or assign a config to the profile.\n" +
+                            "List configs with: speqs config list");
+                    }
+                }
+            }
+            // Confirmation step
             if (!globals.json && !opts.yes) {
                 log("");
                 log("  Simulation settings:");
-                log(`    Platform:       ${resolvedPlatform}`);
-                log(`    Screen format:  ${resolvedScreenFormat}`);
-                if (resolvedUrl)
-                    log(`    URL:            ${resolvedUrl}`);
+                log(`    Modality:       ${modality}`);
+                if (study.content_type)
+                    log(`    Content type:   ${study.content_type}`);
+                if (isMedia) {
+                    if (resolvedOpts.title)
+                        log(`    Title:          ${resolvedOpts.title}`);
+                    if (resolvedOpts.contentText)
+                        log(`    Content:        ${resolvedOpts.contentText.slice(0, 80)}${resolvedOpts.contentText.length > 80 ? "..." : ""}`);
+                    if (resolvedOpts.contentUrl)
+                        log(`    Content URL:    ${resolvedOpts.contentUrl}`);
+                    if (resolvedOpts.imageUrls)
+                        log(`    Image URLs:     ${resolvedOpts.imageUrls}`);
+                    if (resolvedOpts.mimeType)
+                        log(`    MIME type:      ${resolvedOpts.mimeType}`);
+                    if (resolvedOpts.copyText)
+                        log(`    Copy text:      ${resolvedOpts.copyText.slice(0, 80)}${resolvedOpts.copyText.length > 80 ? "..." : ""}`);
+                    if (resolvedOpts.socialPlatform)
+                        log(`    Platform:       ${resolvedOpts.socialPlatform}`);
+                    if (resolvedConfigOverride)
+                        log(`    Config:         ${resolvedConfigOverride}`);
+                }
+                else {
+                    log(`    Platform:       ${resolvedOpts.platform || "browser"}`);
+                    log(`    Screen format:  ${resolvedOpts.screenFormat || "desktop"}`);
+                    if (resolvedOpts.url)
+                        log(`    URL:            ${resolvedOpts.url}`);
+                }
                 if (opts.language)
                     log(`    Language:       ${opts.language}`);
                 log(`    Profiles (${profileIds.length}):`);
@@ -138,62 +392,136 @@ Examples:
                 }
                 log("");
             }
+            // Ensure browser is ready before creating server-side state
+            if (opts.local) {
+                await ensureBrowser({ quiet: globals.quiet, skipPrompt: globals.json });
+            }
             // Step 1: Create or use existing iteration
             if (!iterationId) {
-                const iterName = opts.iterationName || `CLI ${new Date().toISOString().slice(0, 16)}`;
+                const iterName = resolvedOpts.iterationName || `CLI ${new Date().toISOString().slice(0, 16)}`;
                 const iterBody = {
                     name: iterName,
-                    details: {
-                        type: "interactive",
-                        platform: resolvedPlatform,
-                        url: resolvedUrl || "",
-                        screen_format: resolvedScreenFormat,
-                        ...(opts.locale && { locale: opts.locale }),
-                    },
+                    details: buildIterationDetails(modality, resolvedOpts),
                 };
                 log(`Creating iteration "${iterName}"...`);
                 const iter = await client.post(`/studies/${resolvedStudy}/iterations`, iterBody);
                 iterationId = iter.id;
                 log(`Created iteration "${iterName}"`);
             }
-            // Step 2: Create testers from profiles
-            const testerInputs = profileIds.map((profileId) => ({
-                tester_profile_id: profileId,
-                tester_type: "ai",
-                status: "draft",
-                ...(opts.language && { language: opts.language }),
-                platform: resolvedPlatform,
-            }));
-            log(`Creating ${testerInputs.length} tester${testerInputs.length > 1 ? "s" : ""}...`);
-            const batchResult = await client.post(`/iterations/${iterationId}/testers/batch`, { testers: testerInputs });
-            const createdTesters = batchResult.testers;
-            log(`Created ${createdTesters.length} tester${createdTesters.length > 1 ? "s" : ""}`);
-            // Step 3: Start simulations (batch) — config resolved from profiles by backend
-            const simItems = createdTesters.map((t) => ({
-                study_id: resolvedStudy,
-                tester_id: t.id,
-                ...(opts.language && { language: opts.language }),
-                ...(opts.locale && { locale: opts.locale }),
-            }));
-            log(`Starting ${simItems.length} simulation${simItems.length > 1 ? "s" : ""}...`);
-            const simResult = await client.post("/simulation/interactive/start/batch", {
-                product_id: resolvedWorkspace,
-                simulations: simItems,
-                platform: resolvedPlatform,
-                ...(resolvedUrl && { url: resolvedUrl }),
-                screen_format: resolvedScreenFormat,
-                ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
-            }, { timeout: 60_000 });
+            else if (!opts.iteration) {
+                // Auto-reused iteration — update its details to reflect current run
+                const newDetails = buildIterationDetails(modality, resolvedOpts);
+                await client.put(`/iterations/${iterationId}`, { details: newDetails });
+            }
+            // Step 2: Create testers from profiles (or reuse from explicit iteration)
+            let createdTesters;
+            if (opts.iteration && !opts.profiles) {
+                // Reuse existing testers from the explicitly provided iteration
+                const existingIter = await client.get(`/iterations/${iterationId}`);
+                if (existingIter.testers && existingIter.testers.length > 0) {
+                    createdTesters = existingIter.testers;
+                    log(`Reusing ${createdTesters.length} existing tester${createdTesters.length > 1 ? "s" : ""} from iteration`);
+                }
+                else {
+                    throw new Error("Iteration has no existing testers. Use --profiles to create new testers.");
+                }
+            }
+            else {
+                const testerInputs = profileIds.map((profileId) => ({
+                    tester_profile_id: profileId,
+                    tester_type: "ai",
+                    status: "draft",
+                    ...(opts.language && { language: opts.language }),
+                    ...(!isMedia && { platform: resolvedOpts.platform || "browser" }),
+                }));
+                log(`Creating ${testerInputs.length} tester${testerInputs.length > 1 ? "s" : ""}...`);
+                const batchResult = await client.post(`/iterations/${iterationId}/testers/batch`, { testers: testerInputs });
+                createdTesters = batchResult.testers;
+                log(`Created ${createdTesters.length} tester${createdTesters.length > 1 ? "s" : ""}`);
+            }
+            // Step 3: Start simulations
+            // Local mode: run simulations with local browser
+            if (opts.local) {
+                if (isMedia) {
+                    throw new Error("Local mode is only supported for interactive simulations.");
+                }
+                const testerNameMap = new Map();
+                for (const t of createdTesters) {
+                    testerNameMap.set(t.id, t.tester_profile?.name ?? "Unknown");
+                }
+                await runLocalSimulations(client, {
+                    workspaceId: resolvedWorkspace,
+                    studyId: resolvedStudy,
+                    iterationId: iterationId,
+                    testerIds: createdTesters.map((t) => t.id),
+                    testerNames: testerNameMap,
+                    url: resolvedOpts.url,
+                    screenFormat: resolvedOpts.screenFormat,
+                    locale: opts.locale,
+                    maxInteractions: opts.maxInteractions ? parseMaxInteractions(opts.maxInteractions) : undefined,
+                    headed: !!opts.headed,
+                    slowMo: opts.slowMo ? parseSlowMo(opts.slowMo) : undefined,
+                    devtools: opts.devtools,
+                    debug: opts.debug,
+                    parallel: opts.parallel ? parseInt(opts.parallel, 10) : undefined,
+                    quiet: globals.quiet,
+                    json: globals.json,
+                });
+                if (globals.json) {
+                    output({
+                        iteration_id: iterationId,
+                        testers: createdTesters.map((t) => ({ id: t.id, profile_name: t.tester_profile?.name })),
+                        mode: "local",
+                    }, true);
+                }
+                return;
+            }
+            // Remote mode: delegate to backend
+            log(`Starting ${createdTesters.length} simulation${createdTesters.length > 1 ? "s" : ""}...`);
+            let simResults;
+            if (isMedia) {
+                // Media batch endpoint — resolve config per tester from override or profile
+                const mediaBatchItems = createdTesters.map((t, i) => ({
+                    study_id: resolvedStudy,
+                    tester_id: t.id,
+                    config_id: resolvedConfigOverride || profileConfigMap.get(profileIds[i]),
+                    ...(opts.language && { language: opts.language }),
+                }));
+                const simResult = await client.post("/simulation/media/start/batch", {
+                    product_id: resolvedWorkspace,
+                    simulations: mediaBatchItems,
+                    ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+                }, { timeout: 60_000 });
+                simResults = simResult.results;
+            }
+            else {
+                // Interactive batch endpoint
+                const simItems = createdTesters.map((t) => ({
+                    study_id: resolvedStudy,
+                    tester_id: t.id,
+                    ...(opts.config && { config_id: resolveId(opts.config) }),
+                    ...(opts.language && { language: opts.language }),
+                    ...(opts.locale && { locale: opts.locale }),
+                }));
+                const simResult = await client.post("/simulation/interactive/start/batch", {
+                    product_id: resolvedWorkspace,
+                    simulations: simItems,
+                    platform: resolvedOpts.platform || "browser",
+                    ...(resolvedOpts.url && { url: resolvedOpts.url }),
+                    screen_format: resolvedOpts.screenFormat || "desktop",
+                    ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+                }, { timeout: 60_000 });
+                simResults = simResult.results;
+            }
             if (globals.json) {
                 output({
                     iteration_id: iterationId,
                     testers: createdTesters.map((t) => ({ id: t.id, profile_name: t.tester_profile?.name })),
-                    simulations: simResult.results,
+                    simulations: simResults,
                 }, true);
             }
             else {
-                // Human-readable summary (to stderr — not data)
-                for (let i = 0; i < simResult.results.length; i++) {
+                for (let i = 0; i < simResults.length; i++) {
                     const tester = createdTesters[i];
                     const profileName = tester?.tester_profile?.name || "Unknown";
                     log(`  ${profileName.padEnd(24)} QUEUED`);
@@ -220,8 +548,8 @@ Examples:
             }
             else if (opts.study) {
                 const rid = resolveId(opts.study);
-                // Get study to find all testers with running/queued simulations
                 const study = await client.get(`/studies/${rid}`);
+                const isMedia = isMediaModality(study.modality);
                 // Collect all testers across iterations
                 const allTesters = [];
                 for (const iteration of study.iterations || []) {
@@ -231,18 +559,19 @@ Examples:
                             status: tester.status,
                             tester_name: tester.tester_profile?.name || "Unknown",
                             interaction_count: Array.isArray(tester.interactions) ? tester.interactions.length : 0,
+                            ...(tester.error && { error: tester.error }),
+                            ...(tester.failure_reason && { error: tester.failure_reason }),
                         });
                     }
                 }
-                formatSimulationPoll(allTesters, globals.json);
+                formatSimulationPoll(allTesters, globals.json, isMedia);
                 if (!globals.json && study.product_id) {
                     const url = getWebUrl(globals, `/${study.product_id}/${rid}/timeline`);
                     console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
                 }
             }
             else {
-                outputError(new Error("Provide a job_id argument or --study flag"), globals.json);
-                process.exit(1);
+                throw new Error("Provide a job_id argument or --study flag");
             }
         });
     });
@@ -250,8 +579,8 @@ Examples:
     sim
         .command("start")
         .description("Start a single interactive simulation (low-level)")
-        .requiredOption("--workspace <id>", "Workspace ID")
-        .requiredOption("--study <id>", "Study ID")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--study <id>", "Study ID")
         .requiredOption("--tester <id>", "Tester ID")
         .option("--config <id>", "Simulation config ID (resolved from profile if omitted)")
         .option("--platform <platform>", "Platform (browser, android, figma, code)", "browser")
@@ -263,8 +592,8 @@ Examples:
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const body = {
-                product_id: resolveId(opts.workspace),
-                study_id: resolveId(opts.study),
+                product_id: resolveWorkspace(opts.workspace),
+                study_id: resolveStudy(opts.study),
                 tester_id: resolveId(opts.tester),
                 ...(opts.config && { config_id: resolveId(opts.config) }),
                 platform: opts.platform,
@@ -281,19 +610,23 @@ Examples:
     sim
         .command("start-media")
         .description("Start a media simulation (low-level)")
-        .requiredOption("--workspace <id>", "Workspace ID")
-        .requiredOption("--study <id>", "Study ID")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--study <id>", "Study ID")
         .requiredOption("--tester <id>", "Tester ID")
-        .option("--config <id>", "Simulation config ID (resolved from profile if omitted)")
+        .requiredOption("--config <id>", "Simulation config ID")
         .option("--max-interactions <n>", "Max interactions")
         .option("--language <lang>", "Language code")
+        .addHelpText("after", `
+Examples:
+  $ speqs sim start-media --workspace W --study S --tester T --config C
+  $ speqs sim start-media --workspace W --study S --tester T --config C --max-interactions 10`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const body = {
-                product_id: resolveId(opts.workspace),
-                study_id: resolveId(opts.study),
+                product_id: resolveWorkspace(opts.workspace),
+                study_id: resolveStudy(opts.study),
                 tester_id: resolveId(opts.tester),
-                ...(opts.config && { config_id: resolveId(opts.config) }),
+                config_id: resolveId(opts.config),
                 ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
                 ...(opts.language && { language: opts.language }),
             };