@ishlabs/cli 0.27.0 → 0.28.0

package/README.md

@@ -45,6 +45,10 @@ The CLI resolves your auth token in this order:
 
 Test plan is available at `/Users/felixweiland/ish-cli-test-plan.md`.
 
+## Experiments
+
+Durable records of engineering experiments (including reverted ones, so we don't re-run them) live in [`docs/experiments/`](docs/experiments/README.md).
+
 ---
 
 ## Concepts

package/dist/commands/doctor.js

@@ -125,13 +125,16 @@ async function checkSimulator() {
     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 >= 1) {
+        // >1 booted is fine now: a parallel run (`--parallel N`) reuses booted
+        // simulators and clones the shortfall, so extras are a head start, not a
+        // problem. A single-device (non-parallel) run still needs exactly one.
+        const extra = booted.length > 1
+            ? ` (+${booted.length - 1} more — parallel runs pool them; a single-device run needs exactly one)`
+            : "";
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "pass", message: `${booted[0].name} (booted)${extra}` };
     }
-    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" };
+    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>`" };
 }
 /** True when the prebuilt XCUITest runner (WebDriverAgent `.app`) is present. */
 function wdaBundlePresent() {
@@ -172,11 +175,18 @@ async function checkAdb() {
         .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" };
+    // >1 online is fine now: `--parallel` pools emulators (and auto-launches more
+    // from your AVDs). A single-device (non-parallel) run still uses exactly one.
+    const emulator = devices.length >= 1
+        ? {
+            key: "android_emulator",
+            name: "Android emulator",
+            group: "Android",
+            status: "pass",
+            message: devices[0].split("\t")[0] +
+                (devices.length > 1 ? ` (+${devices.length - 1} more — parallel runs pool them)` : ""),
+        }
+        : { key: "android_emulator", name: "Android emulator", group: "Android", status: "warn", message: "none online (parallel runs auto-launch your AVDs)", fix: "Create an AVD in Android Studio > Device Manager (or `emulator -avd <name>`)" };
     return { adb, emulator };
 }
 async function checkChromium() {

package/dist/commands/feedback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ish feedback — report a bug, request a feature, or send any other feedback
+ * to the ish team straight from the terminal.
+ *
+ * Transport: posts to the ish backend (`POST /api/v1/product-feedback` via
+ * ApiClient) with the user's bearer token. The backend inserts into the
+ * `product_feedback` table — the same table the web app's "Send feedback"
+ * dialog writes to — using its privileged connection, so CLI reports show up
+ * alongside web feedback. Per ADR-0029 (ish-frontend), clients submit through
+ * api.ishlabs.io, NEVER via Supabase PostgREST directly: the `sb_publishable_*`
+ * key shipped in this binary is deliberately powerless against the database.
+ * (The web flow additionally mirrors to Notion + captures PostHog server-side;
+ * those are deferred for the CLI.)
+ *
+ * Diagnostics: to help whoever triages the report, the user's message is
+ * augmented with an environment + active-config block (opt out with
+ * --no-diagnostics), and optionally (--health) the `ish check` setup checklist
+ * plus the tail of ~/.ish/local-sim.log. The reporter's identity (user_id /
+ * user_email) is attached server-side from the JWT, not here.
+ */
+import type { Command } from "commander";
+export declare function registerFeedbackCommands(program: Command): void;

package/dist/commands/feedback.js

@@ -0,0 +1,259 @@
+/**
+ * ish feedback — report a bug, request a feature, or send any other feedback
+ * to the ish team straight from the terminal.
+ *
+ * Transport: posts to the ish backend (`POST /api/v1/product-feedback` via
+ * ApiClient) with the user's bearer token. The backend inserts into the
+ * `product_feedback` table — the same table the web app's "Send feedback"
+ * dialog writes to — using its privileged connection, so CLI reports show up
+ * alongside web feedback. Per ADR-0029 (ish-frontend), clients submit through
+ * api.ishlabs.io, NEVER via Supabase PostgREST directly: the `sb_publishable_*`
+ * key shipped in this binary is deliberately powerless against the database.
+ * (The web flow additionally mirrors to Notion + captures PostHog server-side;
+ * those are deferred for the CLI.)
+ *
+ * Diagnostics: to help whoever triages the report, the user's message is
+ * augmented with an environment + active-config block (opt out with
+ * --no-diagnostics), and optionally (--health) the `ish check` setup checklist
+ * plus the tail of ~/.ish/local-sim.log. The reporter's identity (user_id /
+ * user_email) is attached server-side from the JWT, not here.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import pkg from "../../package.json" with { type: "json" };
+import { loadConfig } from "../config.js";
+import { withClient } from "../lib/command-helpers.js";
+import { resolveApiUrl } from "../lib/auth.js";
+import { output } from "../lib/output.js";
+import { c } from "../lib/colors.js";
+const { version: CLI_VERSION } = pkg;
+const FEEDBACK_TYPES = ["bug", "feature", "other"];
+const DESCRIPTION_MIN = 10;
+const DESCRIPTION_MAX = 4000;
+const TITLE_MIN = 3;
+const TITLE_MAX = 120;
+const TYPE_NOUN = {
+    bug: "Bug report",
+    feature: "Feature request",
+    other: "Feedback",
+};
+function validationError(message) {
+    // `name === "ValidationError"` maps to exit code 2 in exitCodeFromError.
+    const err = new Error(message);
+    err.name = "ValidationError";
+    return err;
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+/**
+ * Resolve the feedback body from the positional argument, an `@file`
+ * reference, or piped stdin — the same input idioms the rest of the CLI uses
+ * for text fields (no interactive prompt; the CLI is for autonomous agents).
+ */
+async function resolveDescription(message) {
+    if (message && message.startsWith("@")) {
+        const path = message.slice(1);
+        try {
+            return readFileSync(path, "utf-8");
+        }
+        catch {
+            throw new Error(`Cannot read file: ${path}`);
+        }
+    }
+    // Explicit stdin sentinel, or no argument with something piped in.
+    if (message === "-" || (message === undefined && !process.stdin.isTTY)) {
+        return readStdin();
+    }
+    if (message === undefined) {
+        throw validationError('No feedback message. Pass it as an argument, pipe it on stdin, or use @file:\n' +
+            '  ish feedback "the save button on the profile page does nothing"\n' +
+            '  ish feedback --type feature "let me export interactions as CSV"\n' +
+            "  ish feedback @bug-report.md\n" +
+            '  echo "..." | ish feedback -');
+    }
+    return message;
+}
+function deriveTitle(explicit, description, type) {
+    if (explicit !== undefined) {
+        const t = explicit.trim();
+        if (t.length < TITLE_MIN) {
+            throw validationError(`--title must be at least ${TITLE_MIN} characters.`);
+        }
+        return t.slice(0, TITLE_MAX);
+    }
+    // Mirror the web dialog: first non-empty line of the message becomes the
+    // title, capped to TITLE_MAX. Fall back to a generic title so the table's
+    // NOT NULL + min-length contract is always satisfied even for terse bodies.
+    const firstLine = description
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0) ?? "";
+    const candidate = firstLine.slice(0, TITLE_MAX).trim();
+    return candidate.length >= TITLE_MIN ? candidate : `${TYPE_NOUN[type]} from CLI`;
+}
+// ── Diagnostics ────────────────────────────────────────────────────────────
+//
+// Appended to the message so whoever debugs the report has grounded context.
+// None of this needs the JWT — the backend attaches the reporter's identity
+// from the token. The aim is maximal useful signal without a schema change.
+/** Always-on, instant one-liner: the bare minimum a debugger needs. */
+function platformLine(dev) {
+    return `Sent via ish CLI v${CLI_VERSION} · ${process.platform} ${process.arch} · node ${process.versions.node}${dev ? " · dev" : ""}`;
+}
+/** Active-config context (instant; no subprocesses). Default-on. */
+function diagnosticsBlock(apiUrl) {
+    const cfg = loadConfig();
+    const lines = [
+        "Diagnostics (auto-attached; pass --no-diagnostics to omit)",
+        `- Active workspace: ${cfg.workspace ?? "none"}`,
+        `- Active study: ${cfg.study ?? "none"}`,
+        `- Active ask: ${cfg.ask ?? "none"}`,
+        `- API: ${apiUrl}`,
+    ];
+    return lines.join("\n");
+}
+/** Setup/health checklist, reusing `ish check`'s probes. Heavier (subprocess
+ *  probes for xcrun/adb), so gated behind --health. */
+async function healthBlock() {
+    try {
+        const { runChecks } = await import("./doctor.js");
+        const checks = await runChecks();
+        const MARK = {
+            pass: "OK",
+            warn: "WARN",
+            fail: "FAIL",
+            skip: "--",
+        };
+        const lines = checks.map((ch) => {
+            const fix = (ch.status === "warn" || ch.status === "fail") && ch.fix
+                ? ` (fix: ${ch.fix})`
+                : "";
+            return `- [${MARK[ch.status] ?? ch.status}] ${ch.name}: ${ch.message ?? ""}${fix}`.trimEnd();
+        });
+        return ["Setup checks (ish check):", ...lines].join("\n");
+    }
+    catch (e) {
+        return `Setup checks: could not run (${e instanceof Error ? e.message : String(e)}).`;
+    }
+}
+/** Tail of the local-simulation debug log, when present. Written to
+ *  ~/.ish/local-sim.log by `study run --local --debug`. */
+function localSimLogTail(maxLines = 80) {
+    // Match the literal path debug.ts writes to (it uses homedir()/.ish, not the
+    // ISH_HOME-aware paths helper), so we read exactly where the log lands.
+    const logFile = join(homedir(), ".ish", "local-sim.log");
+    if (!existsSync(logFile))
+        return undefined;
+    try {
+        const tail = readFileSync(logFile, "utf-8").split("\n").slice(-maxLines).join("\n").trim();
+        if (!tail)
+            return undefined;
+        return [
+            `Recent local-sim log (last ${maxLines} lines of ~/.ish/local-sim.log):`,
+            "```",
+            tail,
+            "```",
+        ].join("\n");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Assemble everything appended to the user's message. */
+async function buildAppendix(opts) {
+    const sections = [platformLine(opts.dev)];
+    if (opts.diagnostics)
+        sections.push(diagnosticsBlock(opts.apiUrl));
+    if (opts.health) {
+        sections.push(await healthBlock());
+        const log = localSimLogTail();
+        if (log)
+            sections.push(log);
+    }
+    return "\n\n—\n" + sections.join("\n\n");
+}
+export function registerFeedbackCommands(program) {
+    program
+        .command("feedback")
+        .description("Report a bug or send feedback to the ish team")
+        .argument("[message]", "Feedback text. Use @path to read from a file, or - to read from stdin.")
+        .option("--type <type>", "Feedback type: bug | feature | other", "bug")
+        .option("--title <title>", "Short title (default: first line of the message)")
+        .option("--no-diagnostics", "Don't attach environment/account diagnostics to the report")
+        .option("--health", "Also run setup checks (ish check) and attach recent local-sim logs — useful for simulation/setup bugs")
+        .option("--dry-run", "Print exactly what would be sent (including diagnostics) without submitting")
+        .addHelpText("after", `\nExamples:
+  $ ish feedback "the save button on the profile page does nothing"
+  $ ish feedback --type feature "let me export interactions as CSV"
+  $ ish feedback --type other "the guided setup was great"
+  $ ish feedback @bug-report.md
+  $ ish study run … --local --debug 2>err.txt; ish feedback @err.txt --health
+  $ git log -1 --oneline | ish feedback -
+
+Reports go to the ish team and show up alongside web feedback. Sends as the
+logged-in user (run \`ish login\` first). bug is the default type. To give
+whoever debugs it the most signal, attach the failing command's output via
+@file or stdin; environment + active-config diagnostics are attached
+automatically (opt out with --no-diagnostics), and --health adds setup
+checks + local-sim logs.`)
+        .action(async (message, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const type = opts.type;
+            if (!FEEDBACK_TYPES.includes(type)) {
+                throw validationError(`Invalid --type "${opts.type}". Must be one of: ${FEEDBACK_TYPES.join(", ")}.`);
+            }
+            const rawDescription = await resolveDescription(message);
+            const description = rawDescription.trim();
+            if (description.length === 0) {
+                throw validationError('No feedback message. Pass it as an argument, pipe it on stdin, or use @file:\n' +
+                    '  ish feedback "the save button on the profile page does nothing"\n' +
+                    '  ish feedback --type feature "let me export interactions as CSV"\n' +
+                    "  ish feedback @bug-report.md");
+            }
+            if (description.length < DESCRIPTION_MIN) {
+                throw validationError(`Please add a bit more detail (at least ${DESCRIPTION_MIN} characters).`);
+            }
+            if (description.length > DESCRIPTION_MAX) {
+                throw validationError(`Feedback is too long (${description.length} chars; max ${DESCRIPTION_MAX}).`);
+            }
+            const title = deriveTitle(opts.title, description, type);
+            const apiUrl = resolveApiUrl(globals.apiUrl, globals.dev);
+            const appendix = await buildAppendix({
+                apiUrl,
+                dev: globals.dev,
+                diagnostics: opts.diagnostics,
+                health: opts.health ?? false,
+            });
+            const body = {
+                type,
+                title,
+                description: description + appendix,
+            };
+            if (opts.dryRun) {
+                if (!globals.quiet) {
+                    console.error(`${c.dim}Dry run — nothing sent. This is what would be submitted:${c.reset}`);
+                }
+                output(body, globals.json);
+                return;
+            }
+            if (!globals.quiet) {
+                console.error(`Sending ${type} report…`);
+            }
+            const data = await client.post("/product-feedback", body);
+            if (!globals.quiet) {
+                console.error(`${c.green}✓${c.reset} Thanks! Your ${type} report was sent to the ish team.`);
+            }
+            output(data, globals.json, { writePath: true });
+        });
+    });
+}

package/dist/commands/iteration.js

@@ -9,7 +9,7 @@ import { readFileSync } from "node:fs";
 import { withClient, resolveStudy, resolveWorkspace, readFileOrStdin, collectIds } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatIterationList, ValidationError } from "../lib/output.js";
-import { resolveContentUrl, resolveContentUrls, resolveTextContent } from "../lib/upload.js";
+import { resolveContentUrl, resolveContentUrls, resolveTextContent, archiveHtmlImages } from "../lib/upload.js";
 import { isMediaModality, validateIterationDetails, normalizeChatMode, validateRoleCriteria } from "../lib/modality.js";
 import { validateSegmentation, warnIfOverSegmented } from "../lib/segmentation.js";
 import { normalizeEnumValue, SCREEN_FORMATS } from "../lib/enums.js";
@@ -297,7 +297,9 @@ function buildIterationDetails(modality, opts) {
             if (opts.platform === "figma" && (!opts.fileKey || !opts.startNodeId)) {
                 throw new Error("Figma interactive iterations require both --file-key and --start-node-id.");
             }
-            let screenFormat = "desktop";
+            // Native (ios/android) targets are phones — default to mobile_portrait
+            // rather than desktop. An explicit --screen-format still wins below.
+            let screenFormat = isNativePlatform(opts.platform) ? "mobile_portrait" : "desktop";
             if (opts.screenFormat !== undefined) {
                 const normalized = normalizeEnumValue(opts.screenFormat, SCREEN_FORMATS);
                 if (normalized === null) {
@@ -385,7 +387,7 @@ Concept pages: ish docs get-page concepts/iteration
         .option("--platform <platform>", "Platform (browser, android, ios, figma, code) — interactive only")
         .option("--url <url>", "URL to test — interactive only (optional for ios/android native apps)")
         .option("--app <id>", "Native app bundle id (or .app/.apk path) — ios/android; supplies the iteration target so --url isn't required")
-        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only; hyphen/underscore variants accepted")
+        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only; hyphen/underscore variants accepted. Default: desktop, or mobile_portrait for native ios/android")
         .option("--locale <locale>", "Locale code (e.g. en-US) — interactive only")
         .option("--file-key <key>", "Figma file key — required when --platform=figma")
         .option("--start-node-id <id>", "Figma start node id — required when --platform=figma")
@@ -622,8 +624,15 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                 if (isMedia) {
                     if (resolved.contentText)
                         resolved.contentText = resolveTextContent(resolved.contentText);
-                    if (resolved.contentHtml)
+                    if (resolved.contentHtml) {
                         resolved.contentHtml = resolveTextContent(resolved.contentHtml);
+                        // Archive external <img> images onto workspace storage so the
+                        // render-to-image worker (egress-denied to other origins) can
+                        // fetch them. Mirrors the FE paste pipeline; text modality only.
+                        if (modality === "text") {
+                            resolved.contentHtml = await archiveHtmlImages(client, studyId, resolved.contentHtml, { quiet: globals.quiet });
+                        }
+                    }
                     if (resolved.copyText)
                         resolved.copyText = resolveTextContent(resolved.copyText);
                     if (resolved.copyHtml)

package/dist/commands/study-run.js

@@ -16,13 +16,10 @@ import { fetchStudyParticipants } from "../lib/study-participants.js";
 import { streamStudyEvents } from "../lib/study-events.js";
 import { isMediaModality, isChatModality, iterationHasContent, describeRequiredContentFlag, readChatMode, readParticipantPairConfig, summarizeRoleCriteria, toModality, } from "../lib/modality.js";
 // NOTE: local-sim modules are loaded via dynamic import at the `--local`
-// branch below, NOT statically here. `local-sim/install.ts` deep-imports
-// `playwright-core/lib/server/registry/index`, which is not exposed by
-// playwright-core's `exports` map — Node refuses to resolve it during
-// module load (ERR_PACKAGE_PATH_NOT_EXPORTED), so a static import here
-// would crash *every* `ish` invocation on the npm-installed CLI, not
-// just `study run --local`. The bun-compiled binary bundles the deep
-// path so it doesn't hit Node's resolver; only the npm path is sensitive.
+// branch below, NOT statically here, so that plain API commands never pay
+// for (or crash on) playwright-core. The registry deep import inside
+// `local-sim/install.ts` is itself lazy for the same reason — see the
+// comment in `installBrowser()`.
 import { estimateChatPair, estimateChatSolo, estimateMediaRun } from "../lib/billing.js";
 import { reportReadiness } from "../lib/report-readiness.js";
 import { runChecks, scopeChecks, overall } from "./doctor.js";
@@ -324,7 +321,7 @@ export function attachStudyRunCommands(study) {
         .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 ~/.ish/local-sim.log")
-        .option("--parallel <n>", "Run N participants in parallel (local mode only, default: all)")
+        .option("--parallel <n>", "Run N participants in parallel (local mode only). Browser: default all. Native iOS/Android: pools N auto-provisioned devices — simulators (iOS) / headless emulators from your AVDs (Android) — default 1, capped at 5, auto-sized to host RAM (and AVD count).")
         .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", `
@@ -737,10 +734,6 @@ Examples:
                 }
                 log("");
             }
-            if (opts.local) {
-                const { ensureBrowser } = await import("../lib/local-sim/install.js");
-                await ensureBrowser({ quiet: globals.quiet, skipPrompt: globals.json });
-            }
             // Step 5: Either reuse the iteration's participants or batch-create new ones
             let createdParticipants;
             // Pair-mode bookkeeping: the dispatch endpoint takes
@@ -763,6 +756,13 @@ Examples:
                 ?? platformFromApp
                 ?? detailsView.platform
                 ?? "browser";
+            // Chromium is only needed for the browser local path. iOS/Android
+            // local runs drive a simulator/emulator and must not block on (or
+            // prompt for) a browser download.
+            if (opts.local && normalizePlatform(resolvedPlatform) === "browser") {
+                const { ensureBrowser } = await import("../lib/local-sim/install.js");
+                await ensureBrowser({ quiet: globals.quiet, skipPrompt: globals.json });
+            }
             // Best-effort native-readiness report. When this is a LOCAL native run
             // (iOS/Android driven on this developer's machine), fire-and-forget a
             // fresh, platform-scoped `runChecks()` to the backend so the web app

package/dist/commands/study-screenshots.js

@@ -23,14 +23,16 @@ import { resolveId } from "../lib/alias-store.js";
 import { output, printTable } from "../lib/output.js";
 import { ApiError } from "../lib/api-client.js";
 /**
- * Server-side screenshots are produced by remote interactive runs only. A
- * study whose only runs were local (`ish study run --local`) has none — and the
- * grouped endpoint currently 500s instead of returning an empty index. Tag this
- * hint onto the error so the bare 500 points the user at the local debug report.
+ * The frame-grouped screenshot INDEX (`/screenshots/grouped`) is a remote-run
+ * artifact — it groups by frame_version_id, which local runs don't create — and
+ * the endpoint currently 500s for a local-only study instead of returning an
+ * empty index. Local (`--local`) runs DO still capture per-interaction
+ * screenshots; they just live on the participant rows, not in this index. Tag
+ * this hint onto the error so the bare 500 points the user at where they ARE.
  */
 const LOCAL_RUN_SCREENSHOT_HINT = [
-    "Screenshots are produced by remote runs only.",
-    "Ran this study locally (--local)? The per-step screenshots are in the HTML debug report under ~/.ish/debug/ (path printed at the end of each local run).",
+    "The frame-grouped screenshot index is a remote-run artifact (this endpoint may 500 for local-only studies).",
+    "Ran this study locally (--local)? Per-interaction screenshots ARE captured — read them via `ish study get <id>` (each interaction carries a screenshot_url), or open the per-step HTML debug report under ~/.ish/debug/ (path printed at the end of each local run).",
 ];
 /**
  * GET the frame-grouped screenshot index, tagging the local-run hint onto any
@@ -136,12 +138,13 @@ Examples:
   $ 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 remote interactive runs only — chat /
-video / text studies don't have them, and neither do local runs
-(\`ish study run --local\`), which instead write a per-step HTML debug report to
-~/.ish/debug/ (the path is printed at the end of each local run). Each row's
-storage URL is self-credentialed, so the CLI fetches bytes without forwarding
-your bearer.`);
+This frame-grouped index is built by remote interactive runs — chat / video /
+text studies don't populate it, and neither do local runs (\`ish study run
+--local\`). Local runs still CAPTURE per-interaction screenshots: read them via
+\`ish study get <id>\` (each interaction carries a screenshot_url) or the per-step
+HTML debug report under ~/.ish/debug/ (path printed at the end of each local
+run). 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).")

package/dist/commands/study.js

@@ -350,8 +350,20 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 validateSegmentation(inlineMediaExtras.segmentation);
                 warnIfOverSegmented(inlineMediaExtras.segmentation, { quiet: globals.quietExplicit });
             }
+            let inlineContentHtml;
+            if (opts.contentHtml) {
+                inlineContentHtml = opts.contentHtml.startsWith("@")
+                    ? readFileSync(opts.contentHtml.slice(1), "utf8")
+                    : opts.contentHtml;
+                // The study does not exist yet here, so we cannot archive remote
+                // images onto workspace storage (the render worker egress-denies
+                // other origins). Point the operator at the archive-capable flow.
+                if (/<img\b[^>]*\bsrc\s*=\s*["']https?:\/\//i.test(inlineContentHtml) && !globals.quietExplicit) {
+                    process.stderr.write("Note: --content-html has remote <img> images, which `study create` cannot archive (the study does not exist yet) — they will not render. To archive them, run `ish study create` without content, then `ish iteration create --content-html ...`.\n");
+                }
+            }
             const inlineEmailExtras = {
-                ...(opts.contentHtml && { content_html: opts.contentHtml.startsWith("@") ? readFileSync(opts.contentHtml.slice(1), "utf8") : opts.contentHtml }),
+                ...(inlineContentHtml !== undefined && { content_html: inlineContentHtml }),
                 ...(opts.senderName && { sender_name: opts.senderName }),
                 ...(opts.senderEmail && { sender_email: opts.senderEmail }),
                 ...(opts.featuredImageUrl && { featured_image_url: opts.featuredImageUrl }),
@@ -1244,13 +1256,20 @@ checklists ("steps") ride along when present in the JSON forms
         if (!id) {
             throw new Error("Provide a study alias or UUID, or use --clear.");
         }
-        await withClient(cmd, async (client) => {
+        await withClient(cmd, async (client, globals) => {
             const rid = resolveId(id);
             const data = await client.get(`/studies/${rid}`);
             const config = loadConfig();
             config.study = rid;
             saveConfig(config);
-            console.error(`Active study set to "${data.name || rid}".`);
+            // stdout = data: emit a JSON object so `study use --json` is capturable
+            // (e.g. `--get alias`); the human confirmation stays on stderr.
+            if (globals.json) {
+                output({ id: rid, alias: tagAlias(ALIAS_PREFIX.study, rid), name: data.name ?? null, active: true }, true, { writePath: true });
+            }
+            else {
+                console.error(`Active study set to "${data.name || rid}".`);
+            }
         });
     });
     attachStudyRunCommands(study);

package/dist/commands/workspace.js

@@ -296,7 +296,7 @@ async function collectWorkspaceUsage(client, workspaceId) {
         people_used: typeof participants.total === "number" ? participants.total : 0,
         people_max: lookupLimit("maxCustomPersons"),
         concurrent_participants_max: lookupLimit("maxConcurrentParticipants"),
-        workspace_members_max: lookupLimit("maxWorkspaceMembers"),
+        workspace_members_max: lookupLimit("maxSeats"),
     };
 }
 // ---------------------------------------------------------------------------

package/dist/index.js

@@ -20,6 +20,7 @@ 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 { registerFeedbackCommands } from "./commands/feedback.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";
@@ -512,6 +513,7 @@ registerInitCommands(program);
 registerMcpCommands(program);
 registerSecretCommands(program);
 registerDoctorCommands(program);
+registerFeedbackCommands(program);
 program
     .command("upgrade")
     .description("Update ish to the latest version")

package/dist/lib/command-helpers.js

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import { resolveApiUrl, resolveToken } from "./auth.js";
 import { getAppUrl } from "../auth.js";
 import { ApiClient, ApiError } from "./api-client.js";
-import { outputError, setVerbose, setFields, setGetField } from "./output.js";
+import { outputError, shouldSuggestReport, setVerbose, setFields, setGetField } from "./output.js";
 import { setColorsEnabled, colorsEnabled } from "./colors.js";
 import { loadConfig } from "../config.js";
 import { resolveId } from "./alias-store.js";
@@ -513,7 +513,10 @@ export async function withClient(cmd, fn) {
             await fn(client, globals);
         }
         catch (err) {
-            outputError(err, globals.json);
+            // Nudge to report genuine faults — but never when the failing command
+            // IS `ish feedback` (don't suggest reporting via the thing that broke).
+            const suggestReport = shouldSuggestReport(err) && commandPath(cmd).split(".")[0] !== "feedback";
+            outputError(err, globals.json, { suggestReport });
             await exitWithFlush(exitCodeFromError(err));
         }
     });
@@ -530,7 +533,8 @@ export async function runInline(cmd, fn) {
             await fn(globals);
         }
         catch (err) {
-            outputError(err, globals.json);
+            const suggestReport = shouldSuggestReport(err) && commandPath(cmd).split(".")[0] !== "feedback";
+            outputError(err, globals.json, { suggestReport });
             await exitWithFlush(exitCodeFromError(err));
         }
     });