@ishlabs/cli 0.8.4 → 0.9.0

package/README.md

@@ -55,7 +55,7 @@ Two top-level research primitives, both consume reusable tester profiles:
 Workspace (= product, top-level container)
 │
 ├── Tester Profiles        ← reusable audience personas
-│     └── Audience Sources (transcripts / audio / images that seed generation)
+│     └── Audience Sources (images/PDFs/audio/video/text transcripts that seed generation)
 │
 ├── Study  ─────────────── "structured research artifact"
 │     ├── modality (interactive | text | video | audio | image | document)
@@ -103,7 +103,7 @@ ish workspace  site-access status | basic-auth | cookie | login | affirm-public
 ish study      list | create | generate | get | results | update | delete | use
 ish iteration  list | create | get | update | delete
 ish profile    list | create | generate | get | update | delete
-ish source     upload | get
+ish source     upload | get | delete
 ish config     list | create | get | schema | update | delete
 ```
 

package/dist/auth.d.ts

@@ -1,6 +1,21 @@
 /**
- * Browser-based authentication via the Ish frontend plugin auth flow.
- * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ * Browser-based authentication via Supabase OAuth Server (RFC 6749 / OAuth 2.1).
+ *
+ * Flow:
+ *   1. DCR (RFC 7591) — register a one-shot public OAuth client at the Supabase
+ *      OAuth Server with the loopback redirect URI we just opened a port for.
+ *   2. PKCE (RFC 7636 S256) — generate verifier + challenge.
+ *   3. Loopback redirect (RFC 8252) — listen on 127.0.0.1:<random> and open the
+ *      browser at the Supabase /oauth/authorize URL.
+ *   4. After the user signs in + consents at <ish-frontend>/oauth/consent,
+ *      Supabase redirects back to our loopback with ?code=&state=.
+ *   5. Exchange code → tokens at /oauth/token, return access + refresh.
+ *
+ * Refresh tokens minted here flow back through /oauth/token (not the legacy
+ * /auth/v1/token endpoint), so refreshTokens() targets the same URL.
+ *
+ * Tokens land in ~/.ish/config.json with the same shape as before; the MCP
+ * server's `local` mode keeps reading them without changes.
  */
 export declare function getAppUrl(): string;
 export declare function getSupabaseUrl(): string;
@@ -17,13 +32,32 @@ export declare function resolveSupabaseProjectFromToken(accessToken: string | un
 export declare function decodeJwtExp(token: string): number;
 export declare function decodeJwtClaims(token: string): Record<string, unknown> | undefined;
 export declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
-export declare function login(appUrl?: string): Promise<{
+export declare function login(): Promise<{
     accessToken: string;
     refreshToken: string;
+    clientId: string;
 }>;
-export declare function refreshTokens(refreshToken: string, options?: {
+/**
+ * Thrown by `refreshTokens` when the refresh attempt failed permanently and
+ * the local config can't recover (e.g. Supabase `refresh_token_not_found`,
+ * `invalid_grant`, or any 400-class response). Callers should treat this as
+ * "user must run `ish login` again" — retrying won't help.
+ *
+ * Transient failures (network errors, 5xx, timeouts) are NOT this error and
+ * may be worth retrying.
+ */
+export declare class AuthRefreshPermanentError extends Error {
+    readonly httpStatus: number;
+    readonly errorCode: string | undefined;
+    readonly body: string;
+    constructor(httpStatus: number, body: string, errorCode: string | undefined);
+}
+export declare function refreshTokens(refreshToken: string, options: {
     /** The (possibly expired) access token. Used to pick the correct Supabase project. */
     accessToken?: string;
+    /** OAuth client_id from DCR at login time. Supabase requires it on
+     *  refresh because the issued client is public (no client secret). */
+    clientId: string;
     /** Force a specific Supabase project URL (e.g. for tests). */
     supabaseUrl?: string;
     /** Force a specific anon/publishable key. */

package/dist/auth.js

@@ -1,11 +1,27 @@
 /**
- * Browser-based authentication via the Ish frontend plugin auth flow.
- * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ * Browser-based authentication via Supabase OAuth Server (RFC 6749 / OAuth 2.1).
+ *
+ * Flow:
+ *   1. DCR (RFC 7591) — register a one-shot public OAuth client at the Supabase
+ *      OAuth Server with the loopback redirect URI we just opened a port for.
+ *   2. PKCE (RFC 7636 S256) — generate verifier + challenge.
+ *   3. Loopback redirect (RFC 8252) — listen on 127.0.0.1:<random> and open the
+ *      browser at the Supabase /oauth/authorize URL.
+ *   4. After the user signs in + consents at <ish-frontend>/oauth/consent,
+ *      Supabase redirects back to our loopback with ?code=&state=.
+ *   5. Exchange code → tokens at /oauth/token, return access + refresh.
+ *
+ * Refresh tokens minted here flow back through /oauth/token (not the legacy
+ * /auth/v1/token endpoint), so refreshTokens() targets the same URL.
+ *
+ * Tokens land in ~/.ish/config.json with the same shape as before; the MCP
+ * server's `local` mode keeps reading them without changes.
  */
+import * as http from "node:http";
 import * as crypto from "node:crypto";
 import { execFile } from "node:child_process";
-const POLL_INTERVAL = 2_000;
-const LOGIN_TIMEOUT = 5 * 60 * 1000; // 5 minutes (matches server-side token TTL)
+const LOGIN_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+const CLIENT_NAME = "ish CLI";
 const DEFAULT_APP_URL = "https://app.ishlabs.io";
 // Known Supabase projects, keyed by hostname. The CLI may be talking to either
 // production or development depending on how the user logged in — the access
@@ -13,12 +29,12 @@ const DEFAULT_APP_URL = "https://app.ishlabs.io";
 // must send refresh requests back to that same project (with its matching
 // publishable/anon key) or Supabase will reject them.
 const SUPABASE_PROJECTS = {
-    // Production
+    // Development (default — local dev work hits this project)
     "muqvgnqyubmqnfnqwxuk.supabase.co": {
         url: "https://muqvgnqyubmqnfnqwxuk.supabase.co",
         anonKey: "sb_publishable_pxXwY9EaWFwkR7h728NWvQ_NFqGfh8K",
     },
-    // Development
+    // Production
     "hngymyxdyamokpbeakps.supabase.co": {
         url: "https://hngymyxdyamokpbeakps.supabase.co",
         anonKey: "sb_publishable_JlS-HfwNyDqLNbrfbrkUlw_PSdZJdo2",
@@ -108,52 +124,202 @@ export function isTokenExpired(token, bufferSeconds = 300) {
         return true;
     return Date.now() / 1000 >= exp - bufferSeconds;
 }
-// --- Login via browser polling ---
-export async function login(appUrl) {
-    const url = appUrl ?? getAppUrl();
-    const state = crypto.randomBytes(32).toString("hex");
-    const loginUrl = `${url}/auth/plugin?state=${state}`;
-    console.error("Opening browser to sign in...");
-    console.error(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
-    openBrowser(loginUrl);
-    console.error("Waiting for authentication...");
-    const deadline = Date.now() + LOGIN_TIMEOUT;
-    while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, POLL_INTERVAL));
-        try {
-            const resp = await fetch(`${url}/api/plugin/auth/poll?state=${state}`, {
-                signal: AbortSignal.timeout(10_000),
-            });
-            if (resp.status === 200) {
-                const data = await resp.json();
-                if (data.status === "complete" && data.access_token && data.refresh_token) {
-                    return { accessToken: data.access_token, refreshToken: data.refresh_token };
-                }
+function startCallbackServer() {
+    return new Promise((resolve, reject) => {
+        let resolveCallback = null;
+        const callbackPromise = new Promise((res) => {
+            resolveCallback = res;
+        });
+        const server = http.createServer((req, res) => {
+            const reqUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (reqUrl.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const cb = {
+                code: reqUrl.searchParams.get("code") ?? undefined,
+                state: reqUrl.searchParams.get("state") ?? undefined,
+                error: reqUrl.searchParams.get("error") ?? undefined,
+                errorDescription: reqUrl.searchParams.get("error_description") ?? undefined,
+            };
+            const headline = cb.error ? "Sign-in failed" : "Signed in to Ish";
+            const subline = cb.error
+                ? `${cb.error}${cb.errorDescription ? `: ${cb.errorDescription}` : ""}`
+                : "You can close this window and return to your terminal.";
+            const html = `<!doctype html><html><head><meta charset="utf-8"><title>${headline}</title></head><body style="font-family:system-ui,-apple-system,sans-serif;padding:3em;text-align:center;color:#1f2937"><h1 style="font-weight:600;margin-bottom:1em">${headline}</h1><p style="color:#6b7280">${subline}</p></body></html>`;
+            res.writeHead(cb.error ? 400 : 200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(html);
+            if (resolveCallback)
+                resolveCallback(cb);
+        });
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                reject(new Error("Failed to start callback server"));
+                return;
             }
-            // 202 = pending, keep polling
+            resolve({
+                port: addr.port,
+                waitForCallback: () => callbackPromise,
+                close: () => {
+                    server.close();
+                },
+            });
+        });
+    });
+}
+async function registerOAuthClient(supabaseUrl, redirectUri) {
+    const resp = await fetch(`${supabaseUrl}/auth/v1/oauth/clients/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_name: CLIENT_NAME,
+            redirect_uris: [redirectUri],
+            application_type: "native",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!resp.ok) {
+        throw new Error(`Dynamic client registration failed (HTTP ${resp.status}): ${await resp.text().catch(() => "")}`);
+    }
+    const data = await resp.json();
+    if (typeof data.client_id !== "string") {
+        throw new Error("Dynamic client registration response missing client_id");
+    }
+    return data.client_id;
+}
+function generatePkcePair() {
+    const verifier = crypto.randomBytes(64).toString("base64url");
+    const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}
+export async function login() {
+    const supabaseUrl = getSupabaseUrl();
+    const server = await startCallbackServer();
+    const redirectUri = `http://127.0.0.1:${server.port}/callback`;
+    try {
+        const clientId = await registerOAuthClient(supabaseUrl, redirectUri);
+        const { verifier, challenge } = generatePkcePair();
+        const state = crypto.randomBytes(24).toString("base64url");
+        const authorizeUrl = new URL(`${supabaseUrl}/auth/v1/oauth/authorize`);
+        authorizeUrl.searchParams.set("response_type", "code");
+        authorizeUrl.searchParams.set("client_id", clientId);
+        authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+        authorizeUrl.searchParams.set("state", state);
+        authorizeUrl.searchParams.set("scope", "openid email profile");
+        authorizeUrl.searchParams.set("code_challenge", challenge);
+        authorizeUrl.searchParams.set("code_challenge_method", "S256");
+        console.error("Opening browser to sign in...");
+        console.error(`If the browser doesn't open, visit:\n  ${authorizeUrl.toString()}\n`);
+        openBrowser(authorizeUrl.toString());
+        console.error("Waiting for authentication...");
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error("Login timed out. Please try again.")), LOGIN_TIMEOUT);
+        });
+        const cb = await Promise.race([server.waitForCallback(), timeoutPromise]);
+        if (cb.error) {
+            throw new Error(`OAuth error: ${cb.error}${cb.errorDescription ? ` — ${cb.errorDescription}` : ""}`);
         }
-        catch {
-            // Network error, keep polling
+        if (cb.state !== state) {
+            throw new Error("OAuth state mismatch — possible CSRF attempt. Please try again.");
+        }
+        if (!cb.code) {
+            throw new Error("No authorization code received from Supabase.");
+        }
+        const tokenResp = await fetch(`${supabaseUrl}/auth/v1/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code: cb.code,
+                redirect_uri: redirectUri,
+                client_id: clientId,
+                code_verifier: verifier,
+            }).toString(),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!tokenResp.ok) {
+            throw new Error(`Token exchange failed (HTTP ${tokenResp.status}): ${await tokenResp.text().catch(() => "")}`);
+        }
+        const tokenData = await tokenResp.json();
+        if (typeof tokenData.access_token !== "string" || typeof tokenData.refresh_token !== "string") {
+            throw new Error("Token exchange response missing access_token or refresh_token");
         }
+        return {
+            accessToken: tokenData.access_token,
+            refreshToken: tokenData.refresh_token,
+            clientId,
+        };
+    }
+    finally {
+        server.close();
     }
-    throw new Error("Login timed out. Please try again.");
 }
 // --- Token refresh ---
+/**
+ * Thrown by `refreshTokens` when the refresh attempt failed permanently and
+ * the local config can't recover (e.g. Supabase `refresh_token_not_found`,
+ * `invalid_grant`, or any 400-class response). Callers should treat this as
+ * "user must run `ish login` again" — retrying won't help.
+ *
+ * Transient failures (network errors, 5xx, timeouts) are NOT this error and
+ * may be worth retrying.
+ */
+export class AuthRefreshPermanentError extends Error {
+    httpStatus;
+    errorCode;
+    body;
+    constructor(httpStatus, body, errorCode) {
+        const detail = errorCode ? ` ${errorCode}` : "";
+        super(`Token refresh failed permanently (HTTP ${httpStatus}${detail}): ${body}`);
+        this.name = "AuthRefreshPermanentError";
+        this.httpStatus = httpStatus;
+        this.errorCode = errorCode;
+        this.body = body;
+    }
+}
+function parseRefreshErrorCode(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            if (typeof parsed.error_code === "string")
+                return parsed.error_code;
+            if (typeof parsed.error === "string")
+                return parsed.error;
+        }
+    }
+    catch {
+        // not JSON — fall through
+    }
+    return undefined;
+}
 export async function refreshTokens(refreshToken, options) {
-    const project = options?.supabaseUrl && options?.anonKey
+    const project = options.supabaseUrl && options.anonKey
         ? { url: options.supabaseUrl, anonKey: options.anonKey }
-        : resolveSupabaseProjectFromToken(options?.accessToken);
-    const resp = await fetch(`${project.url}/auth/v1/token?grant_type=refresh_token`, {
+        : resolveSupabaseProjectFromToken(options.accessToken);
+    // OAuth-server-minted tokens refresh through /oauth/token. The legacy
+    // /auth/v1/token endpoint is for password/magic-link flows and won't
+    // accept refresh tokens issued under the OAuth grant.
+    const resp = await fetch(`${project.url}/auth/v1/oauth/token`, {
         method: "POST",
-        headers: {
-            apikey: project.anonKey,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ refresh_token: refreshToken }),
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: options.clientId,
+        }).toString(),
         signal: AbortSignal.timeout(10_000),
     });
     if (!resp.ok) {
         const body = await resp.text().catch(() => "");
+        if (resp.status >= 400 && resp.status < 500) {
+            throw new AuthRefreshPermanentError(resp.status, body, parseRefreshErrorCode(body));
+        }
         throw new Error(`Token refresh failed (HTTP ${resp.status}): ${body}`);
     }
     const data = await resp.json();

package/dist/commands/ask.js

@@ -326,6 +326,10 @@ Minimal --questions JSON (server keys: "question" + "type"):
     { "question": "What stood out?", "type": "text" },
     { "question": "Rate it 1-5", "type": "slider" }
   ]
+
+Picks come back with a \`pick_confidence\` (0..1) score per tester when
+\`--wants-pick\` is set — read it off \`pick.confidence\` in the response. See
+\`ish docs get-page concepts/ask\` for interpretation.
 `)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
@@ -430,7 +434,14 @@ lookups.`)
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
         .option("--round <n>", "Show only round N (1-indexed; default: all rounds)")
-        .addHelpText("after", "\nExamples:\n  $ ish ask results a-6ec\n  $ ish ask results a-6ec --round 1 --json")
+        .addHelpText("after", `
+Examples:
+  $ ish ask results a-6ec
+  $ ish ask results a-6ec --round 1 --json
+
+Each pick has a \`pick_confidence\` field (0..1, when --wants-pick was set) —
+the model's self-reported confidence in its variant choice. See
+\`ish docs get-page concepts/ask\` for how to use it for ranking ties.`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const aid = resolveAsk(pickAskRef(id, opts.ask));
@@ -539,13 +550,18 @@ lookups.`)
         .requiredOption("--round <n|round-id>", "Round number (1-indexed) or round id/alias")
         .requiredOption("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}]`)
         .option("--redispatch-all", "Clear prior phase-1 outputs (comment, pick, ratings) and re-run the entire round from scratch (legacy behavior). Default is additive — only the new questions are answered.", false)
+        .option("--wait", "Wait until the round completes (or errors)")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
 Examples:
   # Additive (default): preserves prior picks/ratings/comments.
   $ ish ask add-questions a-6ec --round 1 --questions ./qs.json
 
+  # Wait for the round to finish before returning.
+  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json --wait
+
   # Legacy reset: re-runs the whole round; prior picks may shift.
-  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json --redispatch-all
+  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json --redispatch-all --wait
 
 Minimal valid --questions JSON:
   [
@@ -566,6 +582,16 @@ text, slider, likert, single-choice, multiple-choice, number.`)
                 ...(opts.redispatchAll && { redispatch_all: true }),
             };
             const updated = await client.post(`/asks/${aid}/rounds/${round.id}/questions`, body);
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                await pollUntilRoundDone(client, aid, updated.order_index, timeoutMs, !!globals.quiet);
+                const refreshed = await client.get(`/asks/${aid}`);
+                const target = refreshed.rounds.find((r) => r.id === updated.id);
+                if (target) {
+                    formatRoundDetail(target, globals.json);
+                    return;
+                }
+            }
             if (!globals.json || globals.verbose) {
                 formatRoundDetail(updated, globals.json);
                 return;

package/dist/commands/iteration.js

@@ -23,6 +23,30 @@ function buildCopyContent(opts) {
         ...(opts.copyPosition && { position: opts.copyPosition }),
     };
 }
+function parseJsonFlag(raw, flagName) {
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`Invalid ${flagName}: expected a JSON object`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("Invalid "))
+            throw err;
+        throw new Error(`Invalid ${flagName}: expected valid JSON object`);
+    }
+}
+function mediaExtras(opts) {
+    const segmentation = parseJsonFlag(opts.segmentationJson, "--segmentation-json");
+    const contentConfig = parseJsonFlag(opts.contentConfigJson, "--content-config-json");
+    return {
+        ...(segmentation && { segmentation }),
+        ...(contentConfig && { content_config: contentConfig }),
+    };
+}
 function buildIterationDetails(modality, opts) {
     switch (modality) {
         case "text":
@@ -35,6 +59,10 @@ function buildIterationDetails(modality, opts) {
                 ...(opts.contentHtml && { content_html: opts.contentHtml }),
                 ...(opts.title && { title: opts.title }),
                 ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...(opts.senderName && { sender_name: opts.senderName }),
+                ...(opts.senderEmail && { sender_email: opts.senderEmail }),
+                ...(opts.featuredImageUrl && { featured_image_url: opts.featuredImageUrl }),
+                ...mediaExtras(opts),
             };
         case "video":
         case "audio": {
@@ -48,6 +76,7 @@ function buildIterationDetails(modality, opts) {
                 ...(opts.title && { title: opts.title }),
                 ...(opts.mimeType && { mime_type: opts.mimeType }),
                 ...(copy && { copy_content: copy }),
+                ...mediaExtras(opts),
             };
         }
         case "image": {
@@ -61,6 +90,7 @@ function buildIterationDetails(modality, opts) {
                 ...(opts.title && { title: opts.title }),
                 ...(opts.mimeType && { mime_type: opts.mimeType }),
                 ...(copy && { copy_content: copy }),
+                ...mediaExtras(opts),
             };
         }
         case "document":
@@ -72,17 +102,45 @@ function buildIterationDetails(modality, opts) {
                 content_url: opts.contentUrl,
                 ...(opts.title && { title: opts.title }),
                 ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...mediaExtras(opts),
             };
+        case "chat": {
+            const endpoint = parseJsonFlag(opts.chatEndpointJson, "--chat-endpoint-json");
+            if (!endpoint && !opts.chatEndpointId) {
+                throw new Error("Chat iterations require either --chat-endpoint-id (saved endpoint) or --chat-endpoint-json (inline config).");
+            }
+            let maxTurns;
+            if (opts.maxTurns !== undefined) {
+                const parsed = Number.parseInt(opts.maxTurns, 10);
+                if (!Number.isFinite(parsed) || parsed < 1) {
+                    throw new Error("Invalid --max-turns: expected a positive integer");
+                }
+                maxTurns = parsed;
+            }
+            return {
+                type: "chat",
+                ...(endpoint && { endpoint }),
+                ...(opts.chatEndpointId && { chatbot_endpoint_id: opts.chatEndpointId }),
+                ...(maxTurns !== undefined && { max_turns: maxTurns }),
+                ...(opts.earlyTermination !== undefined && { early_termination: opts.earlyTermination }),
+            };
+        }
         default:
             if (!opts.url) {
                 throw new Error("Interactive iterations require --url. Provide the URL to test.");
             }
+            if (opts.platform === "figma" && (!opts.fileKey || !opts.startNodeId)) {
+                throw new Error("Figma interactive iterations require both --file-key and --start-node-id.");
+            }
             return {
                 type: "interactive",
                 platform: opts.platform || "browser",
                 url: opts.url,
                 screen_format: opts.screenFormat || "desktop",
                 ...(opts.locale && { locale: opts.locale }),
+                ...(opts.fileKey && { file_key: opts.fileKey }),
+                ...(opts.startNodeId && { start_node_id: opts.startNodeId }),
+                ...(opts.flowName && { flow_name: opts.flowName }),
             };
     }
 }
@@ -91,9 +149,11 @@ export function registerIterationCommands(program) {
         .command("iteration")
         .description("Manage iterations of a study (a study's run-time configuration)")
         .addHelpText("after", `
-An iteration is one configured run of a study — it carries the URL (interactive) or
-media content (text/video/image/document). A study has 1..N iterations; \`ish study run\`
-defaults to the latest. Local file paths in --content-url / --image-urls are auto-uploaded.
+An iteration is one configured run of a study — it carries the URL (interactive),
+media content (text/video/image/document), or chatbot endpoint (chat). A study has
+1..N iterations; \`ish study run\` defaults to the latest. Local file paths in
+--content-url / --image-urls are auto-uploaded. Segments and per-segment labels
+live inside --segmentation-json.
 
 Concept pages: ish docs get-page concepts/iteration
                 ish docs get-page concepts/study`);
@@ -145,9 +205,15 @@ Concept pages: ish docs get-page concepts/iteration
         .option("--url <url>", "URL to test — interactive only")
         .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only")
         .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")
+        .option("--flow-name <name>", "Figma flow name — interactive only")
         // Media text
         .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file — text modality")
         .option("--content-html <html>", "HTML version of the text, or @filepath to read from file — text modality")
+        .option("--sender-name <name>", "Email 'From' display name — text modality (email rendering)")
+        .option("--sender-email <email>", "Email sender address — text modality (email rendering)")
+        .option("--featured-image-url <url>", "Hero image URL — text modality (email rendering)")
         // Media video/audio/document
         .option("--content-url <url>", "URL or local file path to media file — video, audio, document modalities")
         // Media image
@@ -160,6 +226,14 @@ Concept pages: ish docs get-page concepts/iteration
         .option("--copy-html <html>", "HTML version of copy text (or @filepath)")
         .option("--social-platform <platform>", "Social platform (instagram, tiktok, facebook, linkedin, x)")
         .option("--copy-position <pos>", "Copy position relative to media (before, after)", "after")
+        // Segmentation / per-iteration evaluation config (media modalities)
+        .option("--segmentation-json <json>", "Segmentation JSON — time_based {intervals_seconds, labels?}, section_based {sections[{name,label,...}]}, or page_based {} — media modalities")
+        .option("--content-config-json <json>", "Content config JSON — {early_termination, selected_segment_indices?} — media modalities")
+        // Chat modality
+        .option("--chat-endpoint-id <id>", "Saved chatbot endpoint id — chat modality")
+        .option("--chat-endpoint-json <json>", "Inline chatbot endpoint config JSON — chat modality")
+        .option("--max-turns <n>", "Max tester turns (1-50) — chat modality")
+        .option("--early-termination", "End the chat session early when the tester signals stop — chat modality")
         // Escape hatch
         .option("--details-json <json>", "Raw iteration details JSON (overrides individual flags)")
         .addHelpText("after", `
@@ -194,6 +268,25 @@ Examples:
   $ ish iteration create --image-urls ./post.png \\
       --copy-text @./caption.txt --social-platform instagram
 
+  # Email with sender + featured image + section-based segmentation:
+  $ ish iteration create --content-text @./email.txt --content-html @./email.html \\
+      --sender-name "Marketing" --sender-email "marketing@example.com" \\
+      --featured-image-url https://cdn.example.com/hero.png \\
+      --segmentation-json '{"type":"section_based","sections":[{"name":"intro","label":"Intro","paragraph_start":0,"paragraph_end":1}]}'
+
+  # Video with time-based segmentation + labels and early termination:
+  $ ish iteration create --content-url ./promo.mp4 \\
+      --segmentation-json '{"type":"time_based","intervals_seconds":[0,30,60],"labels":["Hook","Body","CTA"]}' \\
+      --content-config-json '{"early_termination":true,"selected_segment_indices":[0,2]}'
+
+  # Figma interactive (file_key + start_node_id required):
+  $ ish iteration create --platform figma --url https://figma.com/proto \\
+      --screen-format mobile_portrait --file-key abc123 --start-node-id 0:1 \\
+      --flow-name "Onboarding A"
+
+  # Chat (probe a saved chatbot endpoint):
+  $ ish iteration create --chat-endpoint-id ce-...  --max-turns 10 --early-termination
+
   # Raw JSON escape hatch (overrides individual flags):
   $ ish iteration create --study s-b2c --details-json \\
       '{"type":"interactive","platform":"browser","url":"https://example.com","screen_format":"desktop"}'
@@ -221,10 +314,11 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                 const study = await client.get(`/studies/${studyId}`);
                 const modality = study.modality || "interactive";
                 const isMedia = isMediaModality(modality);
-                if (isMedia && opts.url) {
-                    throw new Error(`This study uses "${modality}" modality — --url is for interactive studies. Use --content-text, --content-url, or --image-urls instead.`);
+                const isChat = modality === "chat";
+                if ((isMedia || isChat) && opts.url) {
+                    throw new Error(`This study uses "${modality}" modality — --url is for interactive studies. Use the modality-specific flags instead.`);
                 }
-                if (!isMedia && (opts.contentText || opts.contentUrl || opts.imageUrls)) {
+                if (!isMedia && !isChat && (opts.contentText || opts.contentUrl || opts.imageUrls)) {
                     throw new Error(`This study uses "interactive" modality — --content-text, --content-url, and --image-urls are for media studies. Use --url instead.`);
                 }
                 // Validate per-modality required flags BEFORE any upload so we don't
@@ -252,6 +346,11 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                             throw new Error("Document iterations require --content-url. Provide the URL or local file path.");
                         }
                         break;
+                    case "chat":
+                        if (!opts.chatEndpointId && !opts.chatEndpointJson) {
+                            throw new Error("Chat iterations require either --chat-endpoint-id (saved endpoint) or --chat-endpoint-json (inline config).");
+                        }
+                        break;
                     default:
                         if (!opts.url) {
                             throw new Error("Interactive iterations require --url. Provide the URL to test.");