@ishlabs/cli 0.12.2 → 0.14.0

package/dist/commands/study-screenshots.js

@@ -0,0 +1,216 @@
+/**
+ * ish study screenshots — list and download screenshots produced by an
+ * interactive study run.
+ *
+ * Wraps two backend endpoints:
+ *
+ *   GET /studies/{id}/screenshots/grouped  — frame-grouped index
+ *   GET /screenshots/{id}                  — one row carrying screenshot_url
+ *
+ * The screenshot_url is a Supabase Storage URL (public or signed) — we fetch
+ * its bytes with NO Authorization header (the user's ish bearer is never
+ * forwarded cross-origin).
+ *
+ * Mirrors the agent-facing surface ish-mcp exposes via
+ * ``ish://study/{id}/screenshots`` and ``ish://study/{id}/screenshot/{scid}``.
+ * The CLI is for humans / scripts; the MCP resources are for LLM agents.
+ * Both wrap the same backend rows.
+ */
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname, extname, join } from "node:path";
+import { withClient, resolveStudy } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { output, printTable } from "../lib/output.js";
+function projectScreenshot(s) {
+    return {
+        id: s.id,
+        label: s.label ?? null,
+        description: s.description ?? null,
+    };
+}
+function projectListing(studyId, raw) {
+    return {
+        study_id: studyId,
+        total_count: raw.total_count,
+        frames: (raw.groups ?? []).map((g) => ({
+            frame_id: g.frame?.id ?? null,
+            label: g.frame?.label ?? null,
+            count: g.count,
+            screenshots: (g.screenshots ?? []).map(projectScreenshot),
+        })),
+        uncategorized: (raw.uncategorized ?? []).map(projectScreenshot),
+    };
+}
+function printListingTable(listing) {
+    if (listing.total_count === 0) {
+        console.log("No screenshots on this study yet. Screenshots are produced by interactive runs (ish study run).");
+        return;
+    }
+    console.log(`Study ${listing.study_id} — ${listing.total_count} screenshot${listing.total_count === 1 ? "" : "s"} across ${listing.frames.length} frame${listing.frames.length === 1 ? "" : "s"}:`);
+    const rows = [];
+    let frameIdx = 1;
+    for (const frame of listing.frames) {
+        const tag = `frame ${frameIdx}${frame.label ? ` — ${frame.label}` : ""}`;
+        for (const s of frame.screenshots) {
+            rows.push([tag, s.id, s.label ?? ""]);
+        }
+        frameIdx += 1;
+    }
+    for (const s of listing.uncategorized) {
+        rows.push(["(uncategorized)", s.id, s.label ?? ""]);
+    }
+    printTable(["FRAME", "SCREENSHOT ID", "LABEL"], rows);
+    console.error(`\n  Download one with \`ish study screenshots download <study-id> --id <screenshot-id> --out <path>\`,\n  or pass --all to download every screenshot into a directory.`);
+}
+function mimeToExt(contentType) {
+    const t = (contentType ?? "").split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    if (t === "image/png")
+        return ".png";
+    if (t === "image/jpeg" || t === "image/jpg")
+        return ".jpg";
+    if (t === "image/webp")
+        return ".webp";
+    if (t === "image/gif")
+        return ".gif";
+    return ".bin";
+}
+async function fetchScreenshotBytes(url) {
+    // No Authorization header — screenshot URLs are self-credentialed (public
+    // Supabase Storage URLs, or signed URLs whose token lives in ?token=).
+    // Forwarding the ish bearer to a third-party storage host would either
+    // leak it or 401 the fetch. Mirrors IshApiClient.get_url_bytes in ish-mcp.
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch screenshot bytes (HTTP ${res.status}). The signed URL may have expired — re-run \`ish study screenshots <id>\` to get a fresh listing.`);
+    }
+    return {
+        body: await res.arrayBuffer(),
+        contentType: res.headers.get("content-type") ?? "application/octet-stream",
+    };
+}
+async function writeBytes(path, body) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, Buffer.from(body));
+}
+export function attachStudyScreenshotsCommands(study) {
+    const screenshots = study
+        .command("screenshots")
+        .description("List or download screenshots produced by an interactive study run.")
+        .addHelpText("after", `
+Examples:
+  $ ish study screenshots                         # list for active study
+  $ ish study screenshots <study-id>
+  $ ish study screenshots <study-id> --json
+  $ ish study screenshots download <study-id> --id <scid> --out shot.png
+  $ ish study screenshots download <study-id> --all --out ./shots/
+
+Screenshots are produced server-side by interactive runs only — chat / video /
+text studies don't have them. Each row's storage URL is self-credentialed,
+so the CLI fetches bytes without forwarding your bearer.`);
+    screenshots
+        .command("list", { isDefault: true })
+        .description("List screenshots for a study (frame-grouped).")
+        .argument("[id]", "Study ID (defaults to active study)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const studyId = resolveStudy(id);
+            const raw = await client.get(`/studies/${studyId}/screenshots/grouped`);
+            const listing = projectListing(studyId, raw);
+            if (globals.json) {
+                output(listing, true, { preProjected: true });
+                return;
+            }
+            printListingTable(listing);
+        });
+    });
+    screenshots
+        .command("download")
+        .description("Download screenshot bytes to disk. Pass --id for one, or --all for every screenshot on the study.")
+        .argument("[id]", "Study ID (defaults to active study)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
+        .option("--id <screenshot-id>", "Single screenshot ID (mutually exclusive with --all).")
+        .option("--all", "Download every screenshot on the study into --out (treated as a directory).")
+        .option("--out <path>", "Output path. With --id: a file path (defaults to ./<screenshot-id>.<ext>). With --all: a directory (defaults to ./screenshots/).")
+        .action(async (id, opts, cmd) => {
+        if (opts.id && opts.all) {
+            throw new Error("Pass either --id or --all, not both.");
+        }
+        if (!opts.id && !opts.all) {
+            throw new Error("Pass --id <screenshot-id> or --all.");
+        }
+        await withClient(cmd, async (client, globals) => {
+            const studyId = resolveStudy(id);
+            if (opts.id) {
+                const screenshotId = resolveId(opts.id);
+                const row = await client.get(`/screenshots/${screenshotId}`);
+                if (!row.screenshot_url) {
+                    throw new Error(`Screenshot ${screenshotId} has no screenshot_url — the row may be from an aborted upload.`);
+                }
+                const { body, contentType } = await fetchScreenshotBytes(row.screenshot_url);
+                const inferredExt = mimeToExt(contentType);
+                const outPath = opts.out ?? `./${screenshotId}${inferredExt}`;
+                // Honour an explicit --out even if the extension doesn't match the
+                // upstream mime; only auto-pick an extension when --out wasn't set.
+                const finalPath = opts.out || extname(outPath) ? outPath : outPath + inferredExt;
+                await writeBytes(finalPath, body);
+                if (globals.json) {
+                    output({
+                        study_id: studyId,
+                        screenshot_id: screenshotId,
+                        path: finalPath,
+                        bytes: body.byteLength,
+                        content_type: contentType,
+                    }, true, { preProjected: true });
+                }
+                else {
+                    console.log(`Saved ${(body.byteLength / 1024).toFixed(1)} KB → ${finalPath} (${contentType})`);
+                }
+                return;
+            }
+            // --all: walk the index, fetch each row, save under --out dir.
+            const outDir = opts.out ?? "./screenshots";
+            const grouped = await client.get(`/studies/${studyId}/screenshots/grouped`);
+            const all = [
+                ...(grouped.groups ?? []).flatMap((g) => g.screenshots ?? []),
+                ...(grouped.uncategorized ?? []),
+            ];
+            if (all.length === 0) {
+                if (globals.json) {
+                    output({ study_id: studyId, downloaded: 0, paths: [] }, true, { preProjected: true });
+                }
+                else {
+                    console.log("No screenshots to download.");
+                }
+                return;
+            }
+            const paths = [];
+            let totalBytes = 0;
+            for (const s of all) {
+                if (!s.screenshot_url)
+                    continue;
+                const { body, contentType } = await fetchScreenshotBytes(s.screenshot_url);
+                const path = join(outDir, `${s.id}${mimeToExt(contentType)}`);
+                await writeBytes(path, body);
+                paths.push(path);
+                totalBytes += body.byteLength;
+                if (!globals.json) {
+                    process.stderr.write(`  ${path} (${(body.byteLength / 1024).toFixed(1)} KB)\n`);
+                }
+            }
+            if (globals.json) {
+                output({
+                    study_id: studyId,
+                    downloaded: paths.length,
+                    total_bytes: totalBytes,
+                    paths,
+                }, true, { preProjected: true });
+            }
+            else {
+                console.log(`\nSaved ${paths.length}/${all.length} screenshots (${(totalBytes / 1024).toFixed(1)} KB total) → ${outDir}/`);
+            }
+        });
+    });
+}

package/dist/commands/study.js

@@ -11,8 +11,12 @@ import { VALID_CONTENT_TYPES } from "../lib/types.js";
 import { parseAssignment, loadAssignmentsFile, parseQuestion } from "../lib/study-inputs.js";
 import { loadQuestionsManifest } from "../lib/ask-questions.js";
 import { isLocalPath } from "../lib/upload.js";
+import { normalizeChatMode, validateRoleCriteria } from "../lib/modality.js";
+import { normalizeEnumValue, SCREEN_FORMATS } from "../lib/enums.js";
 import { attachStudyRunCommands } from "./study-run.js";
 import { attachStudyTesterCommands } from "./study-tester.js";
+import { attachStudyAnalyzeCommands } from "./study-analyze.js";
+import { attachStudyScreenshotsCommands } from "./study-screenshots.js";
 function collectRepeatable(value, prev = []) {
     return prev.concat([value]);
 }
@@ -86,8 +90,13 @@ Concept pages: ish docs get-page concepts/study
         .addHelpText("after", "\nExamples:\n  $ ish study list --workspace <id>\n  $ ish study list --workspace <id> --json")
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get(`/products/${resolveWorkspace(opts.workspace)}/studies`);
-            formatStudyList(data, globals.json);
+            const resolvedWs = resolveWorkspace(opts.workspace);
+            const data = await client.get(`/products/${resolvedWs}/studies`);
+            const withUrls = data.map((s) => ({
+                ...s,
+                url: getWebUrl(globals, `/${resolvedWs}/${String(s.id ?? "")}/overview`),
+            }));
+            formatStudyList(withUrls, globals.json);
         });
     });
     study
@@ -105,13 +114,21 @@ Concept pages: ish docs get-page concepts/study
         .option("--questionnaire <path>", "JSON file defining the questionnaire (supports text, slider, likert, single-choice, multiple-choice, number; timing=before|after)")
         .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file. Creates iteration A inline (text modality only)")
         .option("--url <url>", "URL to test. Creates iteration A inline (interactive modality only)")
-        .option("--screen-format <format>", "Screen format for interactive iterations: desktop (default) or mobile_portrait")
+        .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("--endpoint <id>", "Saved chatbot endpoint id or alias. Creates iteration A inline (chat modality only)")
-        .option("--endpoint-config <file>", "ChatbotEndpointConfig JSON file (or `-` for stdin); embedded directly. Mutually exclusive with --endpoint (chat modality only)")
+        .option("--endpoint <id>", "Saved chatbot endpoint id or alias. Creates iteration A inline (chat modality, external_chatbot mode)")
+        .option("--endpoint-config <file>", "ChatbotEndpointConfig JSON file (or `-` for stdin); embedded directly. Mutually exclusive with --endpoint (chat modality, external_chatbot mode)")
         .option("--max-turns <n>", "Maximum conversation turns per tester (chat modality only; default 12)", (v) => Number(v))
+        .option("--chat-mode <mode>", "Chat mode: external_chatbot (default) or tester_pair (two AI audiences talk to each other) — chat modality only")
+        .option("--audience-a <ids>", "Tester profile IDs/aliases for audience A (comma-separated or repeatable). Pass a single profile and N on --audience-b to broadcast (1×N rehearsal: fix side A, vary side B) — chat tester_pair mode", (value, prev = []) => prev.concat(value.split(",").map((s) => s.trim()).filter(Boolean)), [])
+        .option("--audience-b <ids>", "Tester profile IDs/aliases for audience B. When both sides are explicit they must be equal length, BUT if either side is a singleton it's auto-broadcast to match the other (1×N rehearsal) — chat tester_pair mode", (value, prev = []) => prev.concat(value.split(",").map((s) => s.trim()).filter(Boolean)), [])
+        .option("--scenario-a <text-or-@file>", "Side-A scenario + goal — chat tester_pair mode")
+        .option("--scenario-b <text-or-@file>", "Side-B scenario + goal — chat tester_pair mode")
+        .option("--initiator-side <a|b>", "Which side speaks first (default: a) — chat tester_pair mode")
+        .option("--role-criteria-a <json-or-@file>", 'RoleCriteria filter for side A (JSON object or @filepath). Keys: occupation[], min_age, max_age, gender[], country[], education_level_in[], household_in[], locale_type_in[], income_level_in[], employment_status_in[], requires_captions, uses_screen_reader, prefers_reduced_motion, prefers_high_contrast, has_any_accessibility_need. The five *_in arrays accept snake_case spec values; the five accessibility filters are booleans. Use INSTEAD of --audience-a or alongside it. chat tester_pair mode.')
+        .option("--role-criteria-b <json-or-@file>", "RoleCriteria filter for side B — same shape as --role-criteria-a. chat tester_pair mode.")
         .addHelpText("after", `
 Note: --workspace is optional if set via \`ish workspace use <alias>\`.
 
@@ -227,12 +244,25 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             // exist until after `studies` POST. For local files, agents fall
             // back to the existing 2-step `iteration create` path which uploads
             // against the freshly-created study.
+            const normalizedChatMode = normalizeChatMode(opts.chatMode);
+            if (opts.chatMode !== undefined && normalizedChatMode === null) {
+                throw new ValidationError(`Invalid --chat-mode "${opts.chatMode}". Expected "external_chatbot" or "tester_pair" (hyphenated variants accepted).`, ["external_chatbot", "tester_pair"]);
+            }
+            const pairFlagsSet = (opts.audienceA && opts.audienceA.length > 0)
+                || (opts.audienceB && opts.audienceB.length > 0)
+                || opts.scenarioA !== undefined
+                || opts.scenarioB !== undefined
+                || opts.initiatorSide !== undefined
+                || opts.roleCriteriaA !== undefined
+                || opts.roleCriteriaB !== undefined
+                || normalizedChatMode === "tester_pair";
             const inlineMediaFlagsSet = [
                 opts.contentText !== undefined ? "--content-text" : null,
                 opts.url !== undefined ? "--url" : null,
                 opts.contentUrl !== undefined ? "--content-url" : null,
                 opts.imageUrls !== undefined ? "--image-urls" : null,
                 (opts.endpoint !== undefined || opts.endpointConfig !== undefined) ? "--endpoint/--endpoint-config" : null,
+                pairFlagsSet ? "--chat-mode tester_pair (with --audience-a/-b or --role-criteria-a/-b plus --scenario-a/-b)" : null,
             ].filter((f) => f !== null);
             if (inlineMediaFlagsSet.length > 1) {
                 throw new ValidationError(`Pass only one inline-iteration flag: ${inlineMediaFlagsSet.join(", ")}.`, inlineMediaFlagsSet);
@@ -240,6 +270,14 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             if (opts.screenFormat !== undefined && opts.url === undefined) {
                 throw new Error("--screen-format only applies when --url is set (interactive modality).");
             }
+            let normalizedScreenFormat;
+            if (opts.screenFormat !== undefined) {
+                const normalized = normalizeEnumValue(opts.screenFormat, SCREEN_FORMATS);
+                if (normalized === null) {
+                    throw new ValidationError(`Invalid --screen-format "${opts.screenFormat}". Expected: ${SCREEN_FORMATS.join(" | ")} (hyphen/underscore variants accepted).`, [...SCREEN_FORMATS]);
+                }
+                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
@@ -279,7 +317,7 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                         type: "interactive",
                         url: opts.url,
                         platform: "browser",
-                        screen_format: opts.screenFormat || "desktop",
+                        screen_format: normalizedScreenFormat || "desktop",
                     },
                 };
             }
@@ -328,6 +366,9 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 if (opts.modality && opts.modality !== "chat") {
                     throw new ValidationError(`--endpoint / --endpoint-config require --modality chat (got "${opts.modality}").`, ["chat"]);
                 }
+                if (normalizedChatMode && normalizedChatMode !== "external_chatbot") {
+                    throw new ValidationError(`--endpoint / --endpoint-config are only valid with --chat-mode external_chatbot (got "${opts.chatMode}"). For tester_pair use --audience-a/-b and --scenario-a/-b.`, ["external_chatbot"]);
+                }
                 let endpointConfig;
                 if (opts.endpoint !== undefined) {
                     const epId = resolveId(opts.endpoint);
@@ -353,8 +394,117 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                     name: "A",
                     details: {
                         type: "chat",
-                        endpoint: endpointConfig,
-                        chatbot_endpoint_id: chatbotEndpointId,
+                        mode_details: {
+                            mode: "external_chatbot",
+                            endpoint: endpointConfig,
+                            ...(chatbotEndpointId && { chatbot_endpoint_id: chatbotEndpointId }),
+                        },
+                        max_turns: maxTurns,
+                        early_termination: true,
+                    },
+                };
+            }
+            else if (pairFlagsSet) {
+                if (opts.modality && opts.modality !== "chat") {
+                    throw new ValidationError(`--chat-mode tester_pair (with --audience-a/-b or --role-criteria-a/-b plus --scenario-a/-b) requires --modality chat (got "${opts.modality}").`, ["chat"]);
+                }
+                if (normalizedChatMode && normalizedChatMode !== "tester_pair") {
+                    throw new ValidationError(`--audience-a/-b or --role-criteria-a/-b imply --chat-mode tester_pair (got "${opts.chatMode}").`, ["tester_pair"]);
+                }
+                const audA = (opts.audienceA ?? []).map(resolveId);
+                const audB = (opts.audienceB ?? []).map(resolveId);
+                // Parse + validate role criteria if supplied (JSON or @filepath).
+                const parseCriteria = (raw, flag) => {
+                    if (raw === undefined)
+                        return undefined;
+                    const text = raw.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw;
+                    const trimmed = text.trim();
+                    if (trimmed.length === 0)
+                        return undefined;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(trimmed);
+                    }
+                    catch {
+                        throw new Error(`Invalid ${flag}: expected valid JSON object.`);
+                    }
+                    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                        throw new Error(`Invalid ${flag}: expected a JSON object.`);
+                    }
+                    return validateRoleCriteria(parsed, flag);
+                };
+                let critA;
+                let critB;
+                try {
+                    critA = parseCriteria(opts.roleCriteriaA, "--role-criteria-a");
+                    critB = parseCriteria(opts.roleCriteriaB, "--role-criteria-b");
+                }
+                catch (err) {
+                    throw new ValidationError(err instanceof Error ? err.message : "Invalid role criteria.", ["--role-criteria-a", "--role-criteria-b"]);
+                }
+                const sideAHasInput = audA.length > 0 || !!critA;
+                const sideBHasInput = audB.length > 0 || !!critB;
+                if (!sideAHasInput || !sideBHasInput) {
+                    throw new Error("tester_pair chat iterations require, for each side, either an explicit audience (--audience-a / --audience-b) or a role-criteria filter (--role-criteria-a / --role-criteria-b).");
+                }
+                // 1×N broadcast: canonical "rehearse one side against N
+                // variations" shape. See iteration.ts buildIterationDetails
+                // tester_pair arm for the rationale.
+                let audA_final = audA;
+                let audB_final = audB;
+                let broadcastMsg;
+                if (audA.length === 1 && audB.length > 1 && !critA && !critB) {
+                    audA_final = Array(audB.length).fill(audA[0]);
+                    broadcastMsg = `Broadcasting --audience-a (1 profile) to length ${audB.length} to match --audience-b — same side-A profile across all ${audB.length} conversations.`;
+                }
+                else if (audB.length === 1 && audA.length > 1 && !critA && !critB) {
+                    audB_final = Array(audA.length).fill(audB[0]);
+                    broadcastMsg = `Broadcasting --audience-b (1 profile) to length ${audA.length} to match --audience-a — same side-B profile across all ${audA.length} conversations.`;
+                }
+                if (broadcastMsg) {
+                    console.error(broadcastMsg);
+                }
+                const bothExplicit = audA_final.length > 0 && audB_final.length > 0 && !critA && !critB;
+                if (bothExplicit && audA_final.length !== audB_final.length) {
+                    // CLI's 1×N broadcast (above) already cloned the singleton side,
+                    // so this branch only fires when both sides ship >1 with
+                    // mismatched counts. Server rejects the same way.
+                    throw new ValidationError(`--audience-a (${audA_final.length}) and --audience-b (${audB_final.length}) cannot be paired. ` +
+                        `Pick the same number on each side (1:1 by index), or pass exactly one profile on one side to broadcast ` +
+                        `(e.g. --audience-a tp-rep --audience-b tp-cto1,tp-cto2,tp-cto3), ` +
+                        `or use --role-criteria-a/-b on either side to let the backend resolve the pool.`, ["--audience-a", "--audience-b"]);
+                }
+                if (!opts.scenarioA || !opts.scenarioB) {
+                    throw new Error("tester_pair chat iterations require --scenario-a <text-or-@file> and --scenario-b <text-or-@file>.");
+                }
+                const scenarioA = opts.scenarioA.startsWith("@")
+                    ? readFileSync(opts.scenarioA.slice(1), "utf8")
+                    : opts.scenarioA;
+                const scenarioB = opts.scenarioB.startsWith("@")
+                    ? readFileSync(opts.scenarioB.slice(1), "utf8")
+                    : opts.scenarioB;
+                if (scenarioA.trim().length === 0 || scenarioB.trim().length === 0) {
+                    throw new Error("--scenario-a and --scenario-b must be non-empty.");
+                }
+                const initiator = (opts.initiatorSide ?? "a").toLowerCase();
+                if (initiator !== "a" && initiator !== "b") {
+                    throw new ValidationError(`Invalid --initiator-side "${opts.initiatorSide}". Expected "a" or "b".`, ["a", "b"]);
+                }
+                const maxTurns = opts.maxTurns ?? 12;
+                inlineIteration = {
+                    name: "A",
+                    details: {
+                        type: "chat",
+                        mode_details: {
+                            mode: "tester_pair",
+                            audience_a: audA_final,
+                            audience_b: audB_final,
+                            scenario_a: scenarioA,
+                            scenario_b: scenarioB,
+                            initiator_side: initiator,
+                            ...(critA && { role_criteria_a: critA }),
+                            ...(critB && { role_criteria_b: critB }),
+                        },
                         max_turns: maxTurns,
                         early_termination: true,
                     },
@@ -389,6 +539,9 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             if (opts.modality === "chat" && inlineIteration) {
                 result.chatbot_endpoint_id = chatbotEndpointId;
             }
+            if (data.id) {
+                result.url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
+            }
             formatStudyDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
@@ -414,6 +567,9 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
+            if (data.id) {
+                result.url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
+            }
             formatStudyDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
@@ -445,6 +601,9 @@ list table layout in human mode.`)
                 const result = data;
                 if (result.id)
                     result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
+                if (data.product_id) {
+                    result.url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
+                }
                 formatStudyDetail(result, globals.json);
                 if (!globals.json && data.product_id) {
                     const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
@@ -453,10 +612,14 @@ list table layout in human mode.`)
                 return;
             }
             const results = await Promise.all(flat.map(async (raw) => {
-                const data = await client.get(`/studies/${resolveId(raw)}`);
+                const rid = resolveId(raw);
+                const data = await client.get(`/studies/${rid}`);
                 const r = data;
                 if (r.id)
                     r.alias = tagAlias(ALIAS_PREFIX.study, String(r.id));
+                if (data.product_id) {
+                    r.url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
+                }
                 return r;
             }));
             if (globals.json) {
@@ -690,4 +853,6 @@ Examples:
     });
     attachStudyRunCommands(study);
     attachStudyTesterCommands(study);
+    attachStudyAnalyzeCommands(study);
+    attachStudyScreenshotsCommands(study);
 }

package/dist/commands/workspace.js

@@ -29,13 +29,44 @@ Concept pages: ish docs get-page concepts/workspace
     });
     workspace
         .command("create")
-        .description("Create a new workspace")
+        .description("Create a new workspace (or reuse an existing one with --ensure)")
         .requiredOption("--name <name>", "Workspace name")
         .option("--description <description>", "Workspace description")
         .option("--base-url <url>", "Default base URL")
-        .addHelpText("after", "\nExamples:\n  $ ish workspace create --name \"My App\" --base-url https://example.com\n  $ ish workspace create --name \"My App\" --json")
+        .option("--ensure", "Idempotent: if a workspace with this exact name already exists in the caller's account, return it instead of creating. Useful on saturated accounts where create would 402/usage_limit_reached.")
+        .addHelpText("after", `
+Examples:
+  $ ish workspace create --name "My App" --base-url https://example.com
+  $ ish workspace create --name "My App" --json
+
+  # Idempotent — returns an existing workspace if --name matches one you own:
+  $ ish workspace create --name "My App" --ensure
+
+With --ensure the response includes a top-level \`reused: true\` flag when an
+existing workspace was returned. On creation, \`reused: false\`.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            if (opts.ensure) {
+                const existing = await client.get("/products");
+                const match = Array.isArray(existing)
+                    ? existing.find((w) => w.name === opts.name)
+                    : undefined;
+                if (match) {
+                    const result = match;
+                    if (result.id)
+                        result.alias = tagAlias(ALIAS_PREFIX.workspace, String(result.id));
+                    result.reused = true;
+                    formatWorkspaceDetail(result, globals.json, { writePath: true });
+                    if (!globals.json) {
+                        console.error(`Reusing existing workspace "${opts.name}".`);
+                        if (match.id) {
+                            const url = getWebUrl(globals, `/${match.id}`);
+                            console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                        }
+                    }
+                    return;
+                }
+            }
             const body = {
                 name: opts.name,
                 ...(opts.description !== undefined && { description: opts.description }),
@@ -45,6 +76,8 @@ Concept pages: ish docs get-page concepts/workspace
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.workspace, String(result.id));
+            if (opts.ensure)
+                result.reused = false;
             formatWorkspaceDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${data.id}`);

package/dist/lib/accessibility-profile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Client-side validator for the AccessibilityProfile v1.0 JSONB shape on
+ * TesterProfile.accessibility_profile. Mirrors
+ * `ish-mcp/spec/accessibility-profile-schema.v1.json` (additionalProperties:
+ * false at every level except `extensions`). An empty object `{}` is the
+ * canonical default. When non-empty, `version` is required and must be
+ * `"1.0"`.
+ *
+ * Surfacing validation here is cheaper than a server round-trip and gives
+ * agents the same exit-2 error contract they get for other CLI inputs.
+ */
+export declare function validateAccessibilityProfile(raw: unknown): Record<string, unknown>;