@ishlabs/cli 0.24.1 → 0.26.0

package/dist/commands/ask.js

@@ -436,15 +436,15 @@ Picks come back with a \`pick_confidence\` (0..1) score per participant when
     // error rather than a transient failure.
     ask
         .command("dispatch")
-        .description("Dispatch a draft ask — bills credits and starts the round")
+        .description("Dispatch a draft ask — draws credits and starts the round")
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
         .option("--wait", "Wait until the first round completes (or errors)")
         .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
 Use after \`ish ask create --no-dispatch\` to start a draft once the user has
-reviewed it. The dispatch is BILLABLE — credits are charged when responses
-land, the same as a normal create.
+reviewed it. Dispatch draws credits as responses land, the same as a normal
+create. This is the expected way to run an ask — go ahead and dispatch.
 
 Examples:
   # Dispatch the active draft and wait for results:

package/dist/commands/doctor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ish check / ish setup — environment diagnostics + dependency setup for
+ * local web and native (iOS/Android) simulations. (`doctor` is a kept alias.)
+ *
+ * `check [platform]` runs read-only checks and prints a flutter-doctor-style
+ * checklist (or `--json`), scoped to one platform's group + Account when a
+ * platform is given (ios|android|web), else everything. `setup`
+ * fetches/installs what it can (Chromium today; the iOS XCUITest runner once
+ * the artifact pipeline lands) and prints guidance for the rest, then re-runs
+ * the checks.
+ *
+ * Design notes:
+ *  - Device probes are light, NON-throwing `execFile` calls reimplemented here
+ *    (not imported from the local-sim drivers): doctor must never throw on a
+ *    missing tool, and must not pull the playwright/local-sim module graph.
+ *  - The Chromium check/setup is a DYNAMIC import of `install.ts` — that module
+ *    deep-imports a non-exported playwright path that crashes at module load on
+ *    the npm-installed CLI, so it can only be loaded lazily (same reason
+ *    `study run --local` imports it dynamically).
+ *  - iOS UI automation is migrating from idb to Apple's XCUITest (a prebuilt
+ *    WebDriverAgent runner fetched into `wdaDir()`); the runner row reflects
+ *    that target. Until the artifact ships, point `ISH_WDA_PATH` at a local
+ *    build.
+ */
+import type { Command } from "commander";
+export declare function registerDoctorCommands(program: Command): void;

package/dist/commands/doctor.js

@@ -0,0 +1,334 @@
+/**
+ * ish check / ish setup — environment diagnostics + dependency setup for
+ * local web and native (iOS/Android) simulations. (`doctor` is a kept alias.)
+ *
+ * `check [platform]` runs read-only checks and prints a flutter-doctor-style
+ * checklist (or `--json`), scoped to one platform's group + Account when a
+ * platform is given (ios|android|web), else everything. `setup`
+ * fetches/installs what it can (Chromium today; the iOS XCUITest runner once
+ * the artifact pipeline lands) and prints guidance for the rest, then re-runs
+ * the checks.
+ *
+ * Design notes:
+ *  - Device probes are light, NON-throwing `execFile` calls reimplemented here
+ *    (not imported from the local-sim drivers): doctor must never throw on a
+ *    missing tool, and must not pull the playwright/local-sim module graph.
+ *  - The Chromium check/setup is a DYNAMIC import of `install.ts` — that module
+ *    deep-imports a non-exported playwright path that crashes at module load on
+ *    the npm-installed CLI, so it can only be loaded lazily (same reason
+ *    `study run --local` imports it dynamically).
+ *  - iOS UI automation is migrating from idb to Apple's XCUITest (a prebuilt
+ *    WebDriverAgent runner fetched into `wdaDir()`); the runner row reflects
+ *    that target. Until the artifact ships, point `ISH_WDA_PATH` at a local
+ *    build.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readdirSync } from "node:fs";
+import * as path from "node:path";
+import { runInline } from "../lib/command-helpers.js";
+import { output } from "../lib/output.js";
+import { loadConfig } from "../config.js";
+import { decodeJwtClaims, isTokenExpired } from "../auth.js";
+import { wdaDir } from "../lib/paths.js";
+import pkg from "../../package.json" with { type: "json" };
+const execFileAsync = promisify(execFile);
+const XCRUN = "/usr/bin/xcrun";
+const isMac = process.platform === "darwin";
+async function tryExec(cmd, args, timeoutMs = 8000) {
+    try {
+        const { stdout, stderr } = await execFileAsync(cmd, args, {
+            timeout: timeoutMs,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        return { ok: true, stdout, stderr };
+    }
+    catch (e) {
+        const err = e;
+        return {
+            ok: false,
+            stdout: err.stdout ?? "",
+            stderr: err.stderr ?? err.message ?? String(e),
+        };
+    }
+}
+/** adb path, mirroring the device layer's resolution (ISH_ADB → ANDROID_HOME → PATH). */
+function resolveAdb() {
+    for (const v of [process.env.ISH_ADB, process.env.ADB]) {
+        if (v && existsSync(v))
+            return v;
+    }
+    for (const home of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]) {
+        if (home) {
+            const p = path.join(home, "platform-tools", "adb");
+            if (existsSync(p))
+                return p;
+        }
+    }
+    return "adb";
+}
+// ── Individual checks ──────────────────────────────────────────────────────
+function checkAuth() {
+    const cfg = loadConfig();
+    const token = cfg.access_token || cfg.token;
+    if (!token) {
+        return { key: "auth", name: "Account", group: "Account", status: "fail", message: "not logged in", fix: "ish login" };
+    }
+    const claims = decodeJwtClaims(token);
+    const email = claims?.email ?? "authenticated";
+    if (isTokenExpired(token)) {
+        // Expired access tokens auto-refresh via the refresh_token on the next API
+        // call, so this is a warn, not a hard fail.
+        return { key: "auth", name: "Account", group: "Account", status: "warn", message: `${email} (token expired — refreshes on next call)`, fix: "ish login (if refresh fails)" };
+    }
+    return { key: "auth", name: "Account", group: "Account", status: "pass", message: email };
+}
+function checkWorkspace() {
+    const cfg = loadConfig();
+    if (cfg.workspace) {
+        return { key: "workspace", name: "Active workspace", group: "Account", status: "pass", message: cfg.workspace };
+    }
+    return { key: "workspace", name: "Active workspace", group: "Account", status: "warn", message: "none set", fix: "ish workspace use <id>" };
+}
+async function checkXcode() {
+    if (!isMac) {
+        return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "skip", message: "iOS simulations require macOS" };
+    }
+    const r = await tryExec(XCRUN, ["--version"]);
+    if (r.ok) {
+        const ver = r.stdout.trim().split("\n")[0] || "xcrun present";
+        return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "pass", message: ver };
+    }
+    return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "fail", message: "xcrun not found", fix: "Install Xcode from the App Store, then `xcodebuild -runFirstLaunch`" };
+}
+async function checkSimulator() {
+    if (!isMac) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "skip" };
+    }
+    const r = await tryExec(XCRUN, ["simctl", "list", "devices", "booted", "-j"]);
+    if (!r.ok) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "fail", message: "could not query simctl", fix: "Install Xcode" };
+    }
+    let booted = [];
+    try {
+        const parsed = JSON.parse(r.stdout);
+        booted = Object.values(parsed.devices ?? {})
+            .flat()
+            .filter((d) => d.state === "Booted")
+            .map((d) => ({ name: d.name, udid: d.udid }));
+    }
+    catch {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "fail", message: "could not parse simctl output" };
+    }
+    if (booted.length === 1) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "pass", message: `${booted[0].name} (booted)` };
+    }
+    if (booted.length === 0) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "warn", message: "none booted", fix: "Open Simulator.app (Xcode ships simulators) or `xcrun simctl boot <udid>`" };
+    }
+    return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "warn", message: `${booted.length} booted — native runs drive exactly one`, fix: "Shut down the extras" };
+}
+/** True when the prebuilt XCUITest runner (WebDriverAgent `.app`) is present. */
+function wdaBundlePresent() {
+    const override = process.env.ISH_WDA_PATH;
+    if (override)
+        return existsSync(override);
+    const dir = wdaDir();
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((e) => e.endsWith(".app"));
+    }
+    catch {
+        return false;
+    }
+}
+function checkXcuitestRunner() {
+    if (!isMac) {
+        return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "skip" };
+    }
+    if (wdaBundlePresent()) {
+        return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "pass", message: process.env.ISH_WDA_PATH ? "ISH_WDA_PATH" : wdaDir() };
+    }
+    return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "warn", message: "not installed", fix: "ish setup (or set ISH_WDA_PATH to a local WebDriverAgent build)" };
+}
+async function checkAdb() {
+    const adbPath = resolveAdb();
+    const r = await tryExec(adbPath, ["devices"]);
+    if (!r.ok) {
+        const adb = { key: "adb", name: "Android adb", group: "Android", status: "warn", message: "not found (only needed for Android)", fix: "Install Android platform-tools" };
+        const emulator = { key: "android_emulator", name: "Android emulator", group: "Android", status: "skip" };
+        return { adb, emulator };
+    }
+    const adb = { key: "adb", name: "Android adb", group: "Android", status: "pass", message: adbPath };
+    // Lines after the "List of devices attached" header, in "device" state.
+    const devices = r.stdout
+        .split("\n")
+        .slice(1)
+        .map((l) => l.trim())
+        .filter((l) => l.endsWith("\tdevice"));
+    const emulator = devices.length === 1
+        ? { key: "android_emulator", name: "Android emulator", group: "Android", status: "pass", message: devices[0].split("\t")[0] }
+        : devices.length === 0
+            ? { key: "android_emulator", name: "Android emulator", group: "Android", status: "warn", message: "none online", fix: "Create + boot an AVD in Android Studio > Device Manager (or `emulator -avd <name>`)" }
+            : { key: "android_emulator", name: "Android emulator", group: "Android", status: "warn", message: `${devices.length} online — native runs drive exactly one`, fix: "Stop the extras" };
+    return { adb, emulator };
+}
+async function checkChromium() {
+    try {
+        const { isBrowserInstalled } = await import("../lib/local-sim/install.js");
+        return isBrowserInstalled()
+            ? { key: "chromium", name: "Chromium (web local)", group: "Web", status: "pass", message: "installed" }
+            : { key: "chromium", name: "Chromium (web local)", group: "Web", status: "warn", message: "not installed", fix: "ish setup" };
+    }
+    catch {
+        return { key: "chromium", name: "Chromium (web local)", group: "Web", status: "skip", message: "unavailable in this build" };
+    }
+}
+function checkCli() {
+    return { key: "cli", name: "ish CLI", group: "Account", status: "pass", message: `v${pkg.version}` };
+}
+async function runChecks() {
+    const { adb, emulator } = await checkAdb();
+    return [
+        await checkXcode(),
+        await checkSimulator(),
+        checkXcuitestRunner(),
+        adb,
+        emulator,
+        await checkChromium(),
+        checkAuth(),
+        checkWorkspace(),
+        checkCli(),
+    ];
+}
+// ── Rendering ───────────────────────────────────────────────────────────────
+const MARK = { pass: "[ OK ]", warn: "[WARN]", fail: "[FAIL]", skip: "[ -- ]" };
+const GROUP_ORDER = ["iOS", "Android", "Web", "Account"];
+const GROUP_LABEL = {
+    iOS: "iOS (native simulations)",
+    Android: "Android (native simulations)",
+    Web: "Web (local browser simulations)",
+    Account: "Account",
+};
+// `ish check <platform>` scopes the report to one platform's group + Account,
+// so an Android study never nags about Xcode and an iOS study never about adb.
+const PLATFORM_GROUPS = {
+    ios: ["iOS", "Account"],
+    android: ["Android", "Account"],
+    web: ["Web", "Account"],
+};
+function scopeChecks(checks, platform) {
+    if (!platform)
+        return checks;
+    const groups = PLATFORM_GROUPS[platform];
+    return groups ? checks.filter((c) => groups.includes(c.group)) : checks;
+}
+function overall(checks) {
+    if (checks.some((c) => c.status === "fail"))
+        return "fail";
+    if (checks.some((c) => c.status === "warn"))
+        return "warn";
+    return "pass";
+}
+function renderHuman(checks) {
+    const lines = ["", "ish check — local & native simulation environment", ""];
+    const width = Math.max(...checks.map((c) => c.name.length)) + 2;
+    for (const group of GROUP_ORDER) {
+        const inGroup = checks.filter((c) => c.group === group);
+        if (inGroup.length === 0)
+            continue;
+        lines.push(`  ${GROUP_LABEL[group]}`);
+        for (const c of inGroup) {
+            const label = c.name.padEnd(width, " ");
+            let line = `    ${MARK[c.status]}  ${label}${c.message ?? ""}`;
+            lines.push(line.trimEnd());
+            if ((c.status === "warn" || c.status === "fail") && c.fix) {
+                lines.push(`            ↳ ${c.fix}`);
+            }
+        }
+        lines.push("");
+    }
+    const o = overall(checks);
+    const fails = checks.filter((c) => c.status === "fail").length;
+    const warns = checks.filter((c) => c.status === "warn").length;
+    if (o === "pass") {
+        lines.push("Everything checks out.");
+    }
+    else {
+        const parts = [fails ? `${fails} blocking` : "", warns ? `${warns} optional` : ""].filter(Boolean);
+        lines.push(`${parts.join(", ")} issue(s). Run \`ish setup\` to fetch what's fetchable.`);
+    }
+    console.log(lines.join("\n"));
+}
+// ── Commands ──────────────────────────────────────────────────────────────
+export function registerDoctorCommands(program) {
+    program
+        .command("check [platform]")
+        .alias("doctor")
+        .description("Check your local simulation setup for a platform (ios | android | web), or everything")
+        .action(async (platform, _opts, cmd) => {
+        await runInline(cmd, async (globals) => {
+            const scope = platform?.toLowerCase();
+            if (scope && !PLATFORM_GROUPS[scope]) {
+                throw new Error(`Unknown platform "${platform}". Use one of: ios, android, web.`);
+            }
+            const checks = scopeChecks(await runChecks(), scope);
+            if (globals.json) {
+                output({ checks, overall: overall(checks) }, true);
+            }
+            else {
+                renderHuman(checks);
+            }
+        });
+    });
+    program
+        .command("setup")
+        .description("Fetch/install local-simulation dependencies (Chromium, iOS runner) and show what's left to do")
+        .action(async (_opts, cmd) => {
+        await runInline(cmd, async (globals) => {
+            const quiet = globals.json;
+            const log = (m) => { if (!quiet)
+                console.error(m); };
+            // 1. Chromium (web local) — auto-fetchable.
+            try {
+                const { isBrowserInstalled, ensureBrowser } = await import("../lib/local-sim/install.js");
+                if (isBrowserInstalled()) {
+                    log("Chromium: already installed.");
+                }
+                else {
+                    log("Chromium: fetching for local web simulations...");
+                    await ensureBrowser({ quiet, skipPrompt: true });
+                }
+            }
+            catch (e) {
+                log(`Chromium: could not install (${e instanceof Error ? e.message : String(e)}).`);
+            }
+            // 2. iOS XCUITest runner (WebDriverAgent) — auto-fetchable on macOS.
+            if (isMac) {
+                try {
+                    if (wdaBundlePresent()) {
+                        log("iOS runner: already installed.");
+                    }
+                    else {
+                        log("iOS runner: fetching WebDriverAgent...");
+                        const { resolveWdaBundle } = await import("../lib/local-sim/xcuitest.js");
+                        await resolveWdaBundle();
+                    }
+                }
+                catch (e) {
+                    log(`iOS runner: could not fetch (${e instanceof Error ? e.message : String(e)}).`);
+                }
+            }
+            // 3. Re-run checks so the user sees the resulting state, and hand back
+            //    the structured result on --json.
+            const checks = await runChecks();
+            if (globals.json) {
+                output({ checks, overall: overall(checks) }, true);
+            }
+            else {
+                renderHuman(checks);
+            }
+        });
+    });
+}

package/dist/commands/iteration.js

@@ -383,7 +383,7 @@ Concept pages: ish docs get-page concepts/iteration
         // Media image
         .option("--image-urls <urls>", "Comma-separated image URLs or local file paths — image modality")
         // Shared media
-        .option("--title <title>", "Content title — media modalities")
+        .option("--title <title>", "Content title shown to participants (the leading headline they read) — media modalities")
         .option("--mime-type <type>", "MIME type (e.g. video/mp4) — media modalities")
         // Copy/caption
         .option("--copy-text <text>", "Ad copy or social post caption (or @filepath) — ads & social posts")

package/dist/commands/study-analyze.js

@@ -81,7 +81,7 @@ export function attachStudyAnalyzeCommands(study) {
     study
         .command("analyze")
         .description("Trigger an AI summary + key-insights analysis for a study. " +
-        "First analysis per study is free; subsequent runs cost 10 credits.")
+        "First analysis per study is included; subsequent runs draw 10 credits.")
         .argument("[id]", "Study ID (defaults to active study)")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
         .option("--wait", "Poll until the run reaches completed or failed")

package/dist/commands/study-run.js

@@ -33,8 +33,8 @@ function parseMaxInteractions(value) {
 /**
  * Default cap the CLI sends when neither `--max-interactions` nor the
  * iteration carries its own value. Picked to match the frontend's
- * conservative interactive launchers and to prevent runaway spend when an
- * iteration runs against a broken or non-responsive surface — without a
+ * conservative interactive launchers and to prevent runaway credit draw when
+ * an iteration runs against a broken or non-responsive surface — without a
  * cap, a stuck participant can rack up hundreds of steps before the SDK gives
  * up.
  */
@@ -264,6 +264,34 @@ function readIterationDetails(details) {
         ...(typeof details.title === "string" && { title: details.title }),
     };
 }
+/**
+ * Normalize a platform string for matching. "web", "browser", and unset all
+ * mean the default browser path; "android"/"ios" are native. Lets `--platform
+ * web` match a "browser" iteration (and vice-versa) without false mismatches.
+ */
+function normalizePlatform(platform) {
+    const p = (platform ?? "").toLowerCase();
+    if (p === "" || p === "web" || p === "browser")
+        return "browser";
+    return p;
+}
+/**
+ * The local platform the user explicitly requested via flags, before any
+ * iteration is picked: --platform, or inferred from --app's extension
+ * (.apk → android, .app → ios). Undefined when neither is set (no preference →
+ * don't filter iterations by platform). The iteration's stored platform is
+ * deliberately NOT consulted here — it's what we're selecting against.
+ */
+function requestedLocalPlatform(opts) {
+    if (opts.platform)
+        return opts.platform;
+    const app = opts.app?.toLowerCase();
+    if (app?.endsWith(".apk"))
+        return "android";
+    if (app?.endsWith(".app"))
+        return "ios";
+    return undefined;
+}
 export function attachStudyRunCommands(study) {
     // --- Primary: `study run` ---
     const studyRun = study
@@ -294,6 +322,8 @@ export function attachStudyRunCommands(study) {
         .option("--devtools", "Open Chrome DevTools (local mode only)")
         .option("--debug", "Enable detailed debug logging to stderr and ~/.ish/local-sim.log")
         .option("--parallel <n>", "Run N participants in parallel (local mode only, default: all)")
+        .option("--platform <platform>", "Local target platform: 'web' (Playwright), 'android' (adb emulator), or 'ios' (simctl+idb simulator). Defaults to the iteration's platform.")
+        .option("--app <path>", "Native local mode: path to an .apk (android) / .app (ios) to install, or an installed package/bundle id to launch. The extension implies --platform.")
         .addHelpText("after", `
 Note: --workspace and --study are optional if you have set active context
   via \`ish workspace use <alias>\` and \`ish study use <alias>\`.
@@ -326,7 +356,7 @@ Examples:
   $ ish study run --config c-c3c
 
   # Cap interactions per participant (default 20 — pass higher to allow deeper
-  # exploration, lower to cap spend on a known-broken surface):
+  # exploration, lower to cap credit draw on a known-broken surface):
   $ ish study run --max-interactions 30
 
   # Block until all simulations finish (or timeout):
@@ -412,8 +442,13 @@ Examples:
             if (!study.assignments || study.assignments.length === 0) {
                 throw new Error("Study has no assignments. Add tasks with --assignments when creating the study, or use `ish study generate`.");
             }
-            // Step 1: Pick iteration (explicit --iteration, or latest on study)
+            // Step 1: Pick iteration (explicit --iteration, or latest on study).
+            // When --platform / --app requests a local platform, select the
+            // iteration whose details.platform matches — otherwise a multi-platform
+            // study (e.g. an android AND an ios iteration) would silently run the
+            // latest, which may be the wrong platform.
             const iterations = study.iterations || [];
+            const wantPlatform = opts.local ? requestedLocalPlatform(opts) : undefined;
             let iteration;
             if (opts.iteration) {
                 const wantedId = resolveId(opts.iteration);
@@ -421,6 +456,25 @@ Examples:
                 if (!iteration) {
                     throw new Error(`Iteration ${opts.iteration} not found on this study.`);
                 }
+                // An explicit --iteration whose platform contradicts --platform is a
+                // footgun (you'd drive the wrong device); refuse rather than guess.
+                if (wantPlatform) {
+                    const itPlatform = readIterationDetails(iteration.details).platform;
+                    if (normalizePlatform(itPlatform) !== normalizePlatform(wantPlatform)) {
+                        throw new Error(`--platform ${wantPlatform} but iteration ${opts.iteration} is platform ` +
+                            `'${itPlatform ?? "browser"}'. Pass the matching iteration or drop --platform.`);
+                    }
+                }
+            }
+            else if (wantPlatform) {
+                // Latest iteration whose platform matches the requested one.
+                const matching = iterations.filter((it) => normalizePlatform(readIterationDetails(it.details).platform) === normalizePlatform(wantPlatform));
+                if (matching.length === 0) {
+                    const available = [...new Set(iterations.map((it) => normalizePlatform(readIterationDetails(it.details).platform)))].join(", ") || "none";
+                    throw new Error(`No ${wantPlatform} iteration on this study (platforms present: ${available}). ` +
+                        `Create one with \`ish iteration create --study ${resolvedStudy} ...\`, or pass --iteration.`);
+                }
+                iteration = matching[matching.length - 1];
             }
             else if (iterations.length > 0) {
                 iteration = iterations[iterations.length - 1];
@@ -691,6 +745,21 @@ Examples:
             // by reusing the iteration's existing Conversation rows or by
             // calling pair-batch.
             let pairConversationIds = [];
+            // Resolve the local target platform ONCE so participant-create and the
+            // local-sim dispatch agree. Precedence: --platform flag > --app
+            // extension (.apk → android, .app → ios) > iteration's stored platform
+            // > browser. Used to set participant.platform (so the backend's native
+            // trigger is driven primarily by the participant, not just the
+            // empty-tree fallback) and to pick the device in the local loop.
+            const platformFromApp = opts.app?.toLowerCase().endsWith(".apk")
+                ? "android"
+                : opts.app?.toLowerCase().endsWith(".app")
+                    ? "ios"
+                    : undefined;
+            const resolvedPlatform = opts.platform
+                ?? platformFromApp
+                ?? detailsView.platform
+                ?? "browser";
             if (isPair && pairConfig) {
                 // Pair-mode flow mirrors the MCP (`ish-mcp` `_run_pair_mode`):
                 //   1. If the iteration already carries `conversations[]` from a
@@ -782,7 +851,7 @@ Examples:
                     participant_type: "ai",
                     status: "draft",
                     ...(opts.language && { language: opts.language }),
-                    ...(!isMedia && !isChat && { platform: detailsView.platform || "browser" }),
+                    ...(!isMedia && !isChat && { platform: resolvedPlatform }),
                 }));
                 log(`Creating ${participantInputs.length} participant${participantInputs.length > 1 ? "s" : ""}...`);
                 const batchResult = await client.post(`/iterations/${iterationId}/participants/batch`, { participants: participantInputs }, { timeout: dispatchTimeoutMs });
@@ -814,6 +883,8 @@ Examples:
                     devtools: opts.devtools,
                     debug: opts.debug,
                     parallel: opts.parallel ? parseInt(opts.parallel, 10) : undefined,
+                    platform: resolvedPlatform,
+                    ...(opts.app && { appPath: opts.app }),
                     quiet: globals.quiet,
                     json: globals.json,
                 });
@@ -1042,14 +1113,11 @@ Examples:
                     }, true);
                 }
                 else {
-                    for (let i = 0; i < simResults.length; i++) {
-                        const participant = createdParticipants[i];
-                        const personName = participant?.person?.name || "Unknown";
-                        log(`  ${personName.padEnd(24)} QUEUED`);
-                    }
+                    const studyAlias = tagAlias(ALIAS_PREFIX.study, resolvedStudy);
+                    const n = createdParticipants.length;
+                    log(`Dispatched ${n} participant${n > 1 ? "s" : ""} — run \`ish study results ${studyAlias}\` for results (or \`ish study poll --study ${studyAlias}\` / --wait to track progress).`);
                     const url = getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`);
-                    log(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
-                    log(`Run \`ish study poll --study ${resolvedStudy}\` (or --wait next time) to check progress.`);
+                    log(`  ${terminalLink(url, "Open in browser ↗")}`);
                 }
                 return;
             }

package/dist/commands/study.js

@@ -113,7 +113,7 @@ Concept pages: ish docs get-page concepts/study
         .requiredOption("--name <name>", "Study name")
         .option("--description <description>", "Study description")
         .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document, chat)")
-        .option("--content-type <type>", "Content type (per-modality enum — see 'Content types by modality' below). Not used for interactive / chat.")
+        .option("--content-type <type>", "Content type (per-modality enum — see 'Content types by modality' below). Changes how --title is presented to participants (e.g. content-type email renders --title as the Subject: line). Not used for interactive / chat.")
         .option("--assignment <name:instructions>", "Assignment as 'Name:Instructions' (repeatable)", collectRepeatable, [])
         .option("--assignments-file <path>", "JSON file with assignments array")
         .option("--assignments <json>", "Inline JSON array of assignments (escape hatch)")
@@ -124,7 +124,7 @@ Concept pages: ish docs get-page concepts/study
         .option("--screen-format <format>", "Screen format for interactive iterations: desktop (default) or mobile_portrait (hyphen/underscore variants accepted)")
         .option("--content-url <url>", "Public URL of the media file. Creates iteration A inline (video, audio, document modalities). For local files, use the 2-step `iteration create` flow.")
         .option("--image-urls <urls>", "Comma-separated public image URLs. Creates iteration A inline (image modality). For local files, use the 2-step `iteration create` flow.")
-        .option("--title <title>", "Content title (text + media modalities — image, video, audio, document; optional). Not used for interactive / chat.")
+        .option("--title <title>", "Participant-facing content title — the headline participants read before the body (text + media modalities — image, video, audio, document; optional). With --content-type email it becomes the email Subject: line. Not an internal label. Not used for interactive / chat.")
         .option("--segmentation-json <json>", "Segmentation JSON for the inline iteration A — time_based {intervals_seconds, labels?}, section_based {sections[{name,label,...}]}, or page_based {} (text + media). section_based sections are SEMANTIC: group related paragraphs into a few coherent sections (a long article is usually 3-6 sections, not one per paragraph). Lets one `study create` build a complete segmented iteration — no separate `iteration create` needed.")
         .option("--content-config-json <json>", "Content-config JSON for the inline iteration A (early_termination, selected_segment_indices) — text + media.")
         .option("--content-html <html>", "HTML version of the text, or @filepath — text modality (email rendering)")
@@ -239,6 +239,9 @@ Examples:
 
 Content types by modality (source: VALID_CONTENT_TYPES in src/lib/types.ts; interactive + chat omitted — they don't take --content-type):
 ${describeContentTypes()}
+  The content type also shapes how --title is rendered to participants: with
+  content-type email, --title becomes the email Subject: line; otherwise it
+  reads as the leading headline of the content.
 
 Tips:
   Use \`--get <path>\` to capture a single value (e.g. \`--get id\`),
@@ -310,11 +313,12 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 }
                 normalizedScreenFormat = normalized;
             }
-            // Pattern G.2: --title is metadata, not content. The backend
-            // accepts it on text + media modalities (see
-            // `buildIterationDetails` in iteration.ts). Reject it only on
-            // shapes that have no title field — interactive (URL only) and
-            // chat (endpoint config carries its own metadata).
+            // --title is participant-facing content: the backend renders it as a
+            // leading headline participants read before the body (and as the email
+            // Subject: line when content-type is email). It only exists on text +
+            // media modalities (see `buildIterationDetails` in iteration.ts), so
+            // reject it on shapes that have no title field — interactive (URL only)
+            // and chat (endpoint config carries its own configuration).
             if (opts.title !== undefined
                 && opts.contentText === undefined
                 && opts.contentUrl === undefined

package/dist/index.js

@@ -19,6 +19,7 @@ import { registerDocsCommands } from "./commands/docs.js";
 import { registerInitCommands } from "./commands/init.js";
 import { registerMcpCommands } from "./commands/mcp.js";
 import { registerSecretCommands } from "./commands/secret.js";
+import { registerDoctorCommands } from "./commands/doctor.js";
 import { AGENT_HELP_FOOTER } from "./lib/docs.js";
 import { runInline, EXIT_USAGE, injectGlobalWorkspaceOption } from "./lib/command-helpers.js";
 import { resolveApiUrl, resolveToken, verifyToken } from "./lib/auth.js";
@@ -510,6 +511,7 @@ registerDocsCommands(program);
 registerInitCommands(program);
 registerMcpCommands(program);
 registerSecretCommands(program);
+registerDoctorCommands(program);
 program
     .command("upgrade")
     .description("Update ish to the latest version")

package/dist/lib/alias-store.js

@@ -129,7 +129,7 @@ const HYDRATE_HINT = {
     // alias map at ~/.ish/aliases.json carries any sources the CLI has
     // touched in this session.
     ps: "ish source upload <file>  # or `cat ~/.ish/aliases.json | grep ^ps-` to recover prior aliases",
-    pt: "ish participant get <participant-id>",
+    pt: "ish study participant <participant-id>",
     c: "ish config list",
     a: "ish ask list",
     r: "ish ask get <ask-id>",

package/dist/lib/api-client.d.ts

@@ -48,6 +48,8 @@ export declare class ApiClient {
         screenshot_url?: string;
         location_name: string;
         screen_format?: string;
+        full_page_screenshot_base64?: string;
+        platform?: string;
     }): Promise<{
         frame_version_id: string;
     }>;