@ishlabs/cli 0.8.5 → 0.9.0

package/README.md

@@ -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,9 +32,10 @@ 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;
 }>;
 /**
  * Thrown by `refreshTokens` when the refresh attempt failed permanently and
@@ -36,9 +52,12 @@ export declare class AuthRefreshPermanentError extends Error {
     readonly body: string;
     constructor(httpStatus: number, body: string, errorCode: string | undefined);
 }
-export declare function refreshTokens(refreshToken: string, options?: {
+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,35 +124,141 @@ 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;
             }
-            // 202 = pending, keep polling
+            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;
+            }
+            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 ---
 /**
@@ -177,16 +299,20 @@ function parseRefreshErrorCode(body) {
     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) {

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.");

package/dist/commands/source.js

@@ -7,8 +7,8 @@
  * generation runs, or to inspect processing status.
  */
 import { withClient, resolveWorkspace } from "../lib/command-helpers.js";
-import { resolveId } from "../lib/alias-store.js";
-import { formatAudienceSource } from "../lib/output.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { formatAudienceSource, output } from "../lib/output.js";
 import { inferSourceKind, uploadAndProcessSource, } from "../lib/profile-sources.js";
 const VALID_KINDS = ["text_file", "audio", "image"];
 export function registerSourceCommands(program) {
@@ -75,4 +75,26 @@ Examples:
             formatAudienceSource(src, globals.json);
         });
     });
+    source
+        .command("delete")
+        .description("Delete an audience source plus its uploaded file")
+        .argument("<id>", "Source ID or alias")
+        .addHelpText("after", `
+Removes both the database row and the underlying uploaded file. Profiles
+already generated from this source remain in place — they don't reference
+the source after generation.
+
+Examples:
+  $ ish source delete tps-3a4`)
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveId(id);
+            await client.del(`/tester-profiles/sources/${rid}`);
+            output({
+                id: rid,
+                alias: tagAlias(ALIAS_PREFIX.testerProfileSource, rid),
+                message: "Source deleted",
+            }, globals.json, { writePath: true });
+        });
+    });
 }

package/dist/commands/study.js

@@ -81,7 +81,7 @@ Concept pages: ish docs get-page concepts/study
         .option("--workspace <id>", "Workspace ID")
         .requiredOption("--name <name>", "Study name")
         .option("--description <description>", "Study description")
-        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document)")
+        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document, chat)")
         .option("--content-type <type>", "Content type (varies by modality — see examples below)")
         .option("--assignment <name:instructions>", "Assignment as 'Name:Instructions' (repeatable)", collectRepeatable, [])
         .option("--assignments-file <path>", "JSON file with assignments array")
@@ -317,7 +317,7 @@ When no runs have completed, the same envelope is returned with zero counts and
         .option("--name <name>", "Study name")
         .option("--description <description>", "Study description")
         .option("--status <status>", "Study status (draft, running, completed)")
-        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document)")
+        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document, chat)")
         .option("--content-type <type>", "Content type")
         .option("--assignment <name:instructions>", "Replace all assignments with these (repeatable)", collectRepeatable, [])
         .option("--assignments-file <path>", "JSON file with assignments array")

package/dist/config.d.ts

@@ -5,6 +5,10 @@
 export interface IshConfig {
     access_token?: string;
     refresh_token?: string;
+    /** OAuth client_id minted by Supabase DCR at last login. Required to refresh
+     *  tokens issued by Supabase OAuth Server (public client → must include
+     *  client_id on refresh). Absent for legacy/non-OAuth tokens. */
+    oauth_client_id?: string;
     token?: string;
     workspace?: string;
     study?: string;

package/dist/connect.js

@@ -233,8 +233,14 @@ async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
         let accessToken = config.access_token;
         // Refresh if expired or close to expiry
         if (isTokenExpired(accessToken)) {
+            if (!config.oauth_client_id) {
+                throw new Error('Saved tokens are missing oauth_client_id. Run "ish login" to re-authenticate.');
+            }
             try {
-                const tokens = await refreshTokens(config.refresh_token);
+                const tokens = await refreshTokens(config.refresh_token, {
+                    accessToken,
+                    clientId: config.oauth_client_id,
+                });
                 accessToken = tokens.accessToken;
                 config.access_token = tokens.accessToken;
                 config.refresh_token = tokens.refreshToken;
@@ -250,7 +256,12 @@ async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
                 const cfg = loadConfig();
                 if (!cfg.refresh_token)
                     throw new Error("No refresh token");
-                const tokens = await refreshTokens(cfg.refresh_token);
+                if (!cfg.oauth_client_id)
+                    throw new Error('Missing oauth_client_id; run "ish login" again.');
+                const tokens = await refreshTokens(cfg.refresh_token, {
+                    accessToken: cfg.access_token,
+                    clientId: cfg.oauth_client_id,
+                });
                 cfg.access_token = tokens.accessToken;
                 cfg.refresh_token = tokens.refreshToken;
                 saveConfig(cfg);

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program, Option } from "commander";
 import { runTunnel } from "./connect.js";
-import { login, getAppUrl, decodeJwtClaims } from "./auth.js";
+import { login, decodeJwtClaims } from "./auth.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { upgrade } from "./upgrade.js";
 import { registerWorkspaceCommands } from "./commands/workspace.js";
@@ -83,11 +83,11 @@ program
     .description("Authenticate with Ish via your browser")
     .action(async (_opts, cmd) => {
     await runInline(cmd, async (globals) => {
-        const appUrl = globals.dev ? "http://localhost:3000" : getAppUrl();
-        const tokens = await login(appUrl);
+        const tokens = await login();
         const config = loadConfig();
         config.access_token = tokens.accessToken;
         config.refresh_token = tokens.refreshToken;
+        config.oauth_client_id = tokens.clientId;
         saveConfig(config);
         output({ message: "Login successful" }, globals.json);
     });

package/dist/lib/auth.js

@@ -57,8 +57,14 @@ export async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
         let accessToken = config.access_token;
         // Refresh if expired or close to expiry
         if (isTokenExpired(accessToken)) {
+            if (!config.oauth_client_id) {
+                throw new Error('Saved tokens are missing oauth_client_id. Run "ish login" to re-authenticate.');
+            }
             try {
-                const tokens = await refreshTokens(config.refresh_token, { accessToken });
+                const tokens = await refreshTokens(config.refresh_token, {
+                    accessToken,
+                    clientId: config.oauth_client_id,
+                });
                 accessToken = tokens.accessToken;
                 config.access_token = tokens.accessToken;
                 config.refresh_token = tokens.refreshToken;

package/dist/lib/command-helpers.js

@@ -45,6 +45,77 @@ function describeFilters(flags) {
         parts.push(`--visibility ${flags.visibility}`);
     return parts.join(" ");
 }
+/**
+ * Best-effort: surface the top-3 populated countries so an empty-audience
+ * error doesn't strand the agent without a pivot. Two tiers — tier 1 keeps
+ * non-country filters and drops `--country` (used when `--country` was the
+ * binding constraint); tier 2 fires when tier 1 returns empty (or when
+ * `--country` wasn't set at all) and drops every filter so the workspace's
+ * overall country distribution is the fallback. Returns the empty string on
+ * any failure — never replaces the primary error with a secondary one.
+ */
+async function suggestCountries(client, workspace, flags, opts) {
+    const countOf = (items) => {
+        const counts = new Map();
+        for (const p of items) {
+            const c = typeof p.country === "string" ? p.country : null;
+            if (c)
+                counts.set(c, (counts.get(c) ?? 0) + 1);
+        }
+        return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3);
+    };
+    const fetchFacet = async (keepOtherFilters) => {
+        try {
+            const broader = {
+                product_id: workspace,
+                type: "ai",
+                limit: "500",
+                offset: "0",
+            };
+            if (keepOtherFilters) {
+                if (flags.search)
+                    broader.search = flags.search;
+                if (flags.gender && flags.gender.length > 0)
+                    broader.gender = flags.gender;
+                if (flags.minAge)
+                    broader.min_age = flags.minAge;
+                if (flags.maxAge)
+                    broader.max_age = flags.maxAge;
+                if (flags.visibility)
+                    broader.visibility = flags.visibility;
+            }
+            const data = await client.get("/tester-profiles", broader);
+            const items = Array.isArray(data)
+                ? data
+                : Array.isArray(data?.items)
+                    ? data.items
+                    : [];
+            const pool = opts.requireSimulatable ? items.filter(isSimulatable) : items;
+            return countOf(pool);
+        }
+        catch {
+            return [];
+        }
+    };
+    const countrySet = !!(flags.country && flags.country.length > 0);
+    // Tier 1: when --country is set, drop just country and keep other filters.
+    // When --country isn't set, skip straight to the unfiltered fallback —
+    // tier 1 with `keepOtherFilters=false` would re-issue the same query that
+    // already returned 0.
+    let top = [];
+    let label = "Populated countries";
+    if (countrySet) {
+        top = await fetchFacet(true);
+        label = "Populated countries with these other filters";
+    }
+    if (top.length === 0) {
+        top = await fetchFacet(false);
+        label = "Populated countries";
+    }
+    if (top.length === 0)
+        return "";
+    return ` ${label}: ${top.map(([c, n]) => `${c} (${n})`).join(", ")}.`;
+}
 function hasFilterFlag(flags) {
     return Boolean(flags.search
         || (flags.gender && flags.gender.length > 0)
@@ -129,56 +200,18 @@ export async function resolveAudienceProfileIds(client, workspace, flags, opts =
         if (opts.excludeProfileIds && opts.excludeProfileIds.size > 0 && !filterDesc) {
             throw new Error("All matching profiles are already in this audience.");
         }
-        // When --country was the binding constraint, query the broader pool (drop
-        // country filter, keep the rest) and surface the top populated countries
-        // so the agent doesn't have to round-trip through `ish profile list` to
-        // find one that matches. Pure best-effort — any failure falls back to the
-        // original error.
-        let suggestion = "";
-        if (flags.country && flags.country.length > 0) {
-            try {
-                const broader = {
-                    product_id: workspace,
-                    type: "ai",
-                    limit: "500",
-                    offset: "0",
-                };
-                if (flags.search)
-                    broader.search = flags.search;
-                if (flags.gender && flags.gender.length > 0)
-                    broader.gender = flags.gender;
-                if (flags.minAge)
-                    broader.min_age = flags.minAge;
-                if (flags.maxAge)
-                    broader.max_age = flags.maxAge;
-                if (flags.visibility)
-                    broader.visibility = flags.visibility;
-                const broaderData = await client.get("/tester-profiles", broader);
-                const broaderItems = Array.isArray(broaderData)
-                    ? broaderData
-                    : Array.isArray(broaderData?.items)
-                        ? broaderData.items
-                        : [];
-                const broaderPool = opts.requireSimulatable
-                    ? broaderItems.filter(isSimulatable)
-                    : broaderItems;
-                const counts = new Map();
-                for (const p of broaderPool) {
-                    const c = typeof p.country === "string" ? p.country : null;
-                    if (c)
-                        counts.set(c, (counts.get(c) ?? 0) + 1);
-                }
-                const top = [...counts.entries()]
-                    .sort((a, b) => b[1] - a[1])
-                    .slice(0, 3);
-                if (top.length > 0) {
-                    suggestion = ` Populated countries with these other filters: ${top.map(([c, n]) => `${c} (${n})`).join(", ")}.`;
-                }
-            }
-            catch {
-                // Swallow — never replace the user's error with a secondary failure.
-            }
-        }
+        // Country suggestion: surface the top populated countries so the agent
+        // doesn't have to round-trip through `ish profile list` to find one that
+        // matches. Two tiers — tier 1 drops `--country` only and retains other
+        // filters when `--country` was set (so the hint reflects "of countries
+        // that match your other filters, here are the populated ones"). Tier 2
+        // fires when tier 1 returns nothing *and* tier 1 was scoped, or when
+        // `--country` wasn't the constraint to begin with: drop every filter and
+        // surface the workspace's overall country distribution. Pure best-effort
+        // — any failure falls back to the original error.
+        const suggestion = await suggestCountries(client, workspace, flags, {
+            requireSimulatable: !!opts.requireSimulatable,
+        });
         if (filterDesc) {
             throw new Error(`No ${sim}tester profiles in workspace ${workspace} match: ${filterDesc}.${suggestion} Broaden your filters or run \`ish profile list\` to inspect the pool.`);
         }

package/dist/lib/docs.js

@@ -18,7 +18,7 @@ Workspace (= product)
 ├── Tester Profiles ────── reusable audience personas (alias: tp-…)
 │     └── Sources ──────── transcripts/audio/images that seed generation
 ├── Study ──────────────── persistent research artifact (alias: s-…)
-│     ├── modality ──────── interactive | text | video | audio | image | document
+│     ├── modality ──────── interactive | text | video | audio | image | document | chat
 │     ├── assignments ───── tasks the tester does
 │     ├── questionnaire ─── questions the tester answers
 │     └── Iterations ────── one configured run (URL or content) (alias: i-…)
@@ -108,8 +108,9 @@ ish workspace site-access status
 const CONCEPT_STUDY = `# concept: study
 
 A **study** is the persistent research artifact. It defines:
-- \`modality\`: \`interactive\` (the tester drives a real browser) or one of
-  \`text | video | audio | image | document\` (media reaction studies).
+- \`modality\`: \`interactive\` (the tester drives a real browser), one of
+  \`text | video | audio | image | document\` (media reaction studies),
+  or \`chat\` (multi-turn probe against an external chatbot endpoint).
 - \`content_type\` (media studies only): \`email | social_post | ad | …\` —
   controls the framing the tester is given.
 - \`assignments\`: the tasks the tester performs. See \`concepts/assignment\`.
@@ -200,9 +201,9 @@ pick was wrong.
 const CONCEPT_ITERATION = `# concept: iteration
 
 An **iteration** is one configured run of a study. It carries the
-volatile bits — the URL (interactive) or the media (video/text/etc.) —
-while the study carries the persistent shape (assignments, questionnaire,
-modality).
+volatile bits — the URL (interactive), the media (video/text/etc.), or
+the chatbot endpoint (chat) — while the study carries the persistent
+shape (assignments, questionnaire, modality).
 
 - Alias prefix: \`i-\`
 - A study has 1..N iterations. \`ish study run\` defaults to the latest.
@@ -224,9 +225,19 @@ ish iteration create --study s-b2c --url https://example.com
 # Interactive on mobile screen format:
 ish iteration create --url https://example.com --screen-format mobile_portrait
 
+# 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"
+
 # Text/email content from a file:
 ish iteration create --content-text @./email.html --title "Newsletter"
 
+# Email iteration with sender + featured hero image:
+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
+
 # Video (URL or local file):
 ish iteration create --content-url ./video.mp4
 
@@ -236,11 +247,113 @@ ish iteration create --image-urls "./a.png,./b.png"
 # Document (PDF):
 ish iteration create --content-url ./report.pdf
 
+# Chat — probe a saved chatbot endpoint:
+ish iteration create --chat-endpoint-id ce-... --max-turns 10 --early-termination
+
 # Inspect:
 ish iteration list --study s-b2c
 ish iteration get i-d4e
 \`\`\`
 
+## Segments and segment labels
+
+For media iterations (video, audio, text, image, document), reactions
+can be collected per **segment** instead of over the whole asset. A
+segment is a contiguous slice of the iteration's content — a 30-second
+window of a video, a paragraph range of an email, a section of a PDF.
+Each segment can carry a human-readable **label** ("Intro", "Pricing
+section", "Call to action") that surfaces in the tester UI and in
+results.
+
+Segments live inside the iteration's \`segmentation\` field — there is
+no separate segments resource. Three discriminated shapes:
+
+- **time_based** (video, audio): boundaries in seconds. Segment 0 runs
+  from \`intervals_seconds[0]\` to \`intervals_seconds[1]\`, etc.
+  Optional \`labels[]\` names each segment.
+
+  \`\`\`json
+  {
+    "type": "time_based",
+    "intervals_seconds": [0, 30, 60, 90],
+    "labels": ["Hook", "Feature 1", "Feature 2", "CTA"]
+  }
+  \`\`\`
+
+- **section_based** (text, document, image copy): explicit list of
+  named sections, either marker-bounded or paragraph-bounded.
+
+  \`\`\`json
+  {
+    "type": "section_based",
+    "sections": [
+      { "name": "intro", "label": "Intro",   "paragraph_start": 0, "paragraph_end": 1 },
+      { "name": "body",  "label": "Body",    "paragraph_start": 1, "paragraph_end": 4 },
+      { "name": "cta",   "label": "Call to action", "paragraph_start": 4, "paragraph_end": 5 }
+    ]
+  }
+  \`\`\`
+
+- **page_based** (document): pages are auto-derived from the document.
+  No additional fields.
+
+Pass via \`--segmentation-json '<json>'\` on \`iteration create\`.
+
+### Default segmentation for text/image iterations
+
+For text- and image-modality iterations created without
+\`--segmentation-json\`, the worker synthesises a single whole-content
+section so a minimal \`ish iteration create --content-text "..."\` runs
+end-to-end. Author your own segmentation when you want section-level
+reactions; otherwise the default just works.
+
+### content_config — early termination + selected segments
+
+A sibling of \`segmentation\` that controls how the tester progresses
+through segments:
+
+- \`early_termination: true\` — stop the session once every selected
+  segment has been seen.
+- \`selected_segment_indices: [0, 2]\` — only show these segment
+  indices; \`null\` (default) means all segments are active.
+
+Pass via \`--content-config-json '<json>'\`.
+
+## HTML content (text + media captions)
+
+- **Text modality**: pair plain \`--content-text\` with rich
+  \`--content-html\` to render emails / articles with formatting. The
+  plain text is what testers reason over; the HTML is what they see.
+- **Media captions** (video, audio, image): \`--copy-text\` and
+  \`--copy-html\` attach a caption to the media — the social-post
+  pattern. Add \`--social-platform\` (instagram/tiktok/facebook/linkedin/x)
+  for platform-specific framing, and \`--copy-position before|after\`
+  for ordering relative to the media.
+
+Captions can carry their own segmentation when you want
+paragraph-by-paragraph reactions to a long caption. Use the
+\`--details-json\` escape hatch to pass a nested
+\`copy_content.segmentation\`.
+
+## Chat modality
+
+Chat iterations probe an external chatbot endpoint by having a tester
+hold a multi-turn conversation against it. Two ways to wire the
+endpoint:
+
+\`\`\`
+# Reference a saved endpoint row (recommended — reproducible):
+ish iteration create --chat-endpoint-id ce-...
+
+# Inline endpoint config (one-off):
+ish iteration create --chat-endpoint-json '{"url":"https://...","headers":{...}}'
+\`\`\`
+
+Tunables:
+- \`--max-turns N\` — cap the conversation length (default 12, max 50).
+- \`--early-termination\` — let the worker end the session early when
+  the tester signals the conversation is over.
+
 ## No more auto-empty iteration A
 
 \`ish study create\` and \`ish study generate\` **do not auto-create
@@ -261,16 +374,6 @@ then retry.
 
 Treat this as actionable, not transient — re-running won't change anything.
 
-## Default segmentation for text/image iterations
-
-For text-modality iterations created with just \`--content-text\` (and
-similarly \`--image-urls\` for image), the worker now synthesises a
-single whole-content section if no \`segmentation\` was supplied. This
-means a minimal \`ish iteration create --study s-XYZ --content-text
-"..."\` actually runs end-to-end without you needing to author a
-SegmentationConfig manually. Author your own segmentation when you
-want section-level reactions; otherwise the default just works.
-
 ## Related
 
 - \`concepts/study\` — the parent artifact.
@@ -1375,7 +1478,7 @@ const PAGES = [
     {
         slug: "concepts/iteration",
         title: "concept: iteration",
-        description: "One configured run of a study (URL or media).",
+        description: "One configured run of a study (URL, media, or chat). Covers segments, segment labels, and HTML content.",
         body: CONCEPT_ITERATION,
     },
     {

package/dist/lib/skill-content.js

@@ -77,7 +77,7 @@ Workspace (= product)
 ├── Tester Profiles (tp-…)   reusable audience personas
 │     └── Sources (tps-…)    transcripts/audio/images that seed generation
 ├── Study (s-…)              persistent research artifact
-│     ├── modality           interactive | text | video | audio | image | document
+│     ├── modality           interactive | text | video | audio | image | document | chat
 │     ├── assignments        tasks the tester does
 │     ├── questionnaire      questions the tester answers
 │     └── Iterations (i-…)   one configured run; carries the URL or media

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.8.5",
-  "description": "The command-line interface for Ish",
+  "version": "0.9.0",
+  "description": "The command-line interface for ish",
   "type": "module",
   "bin": {
     "ish": "./dist/index.js"
@@ -41,4 +41,4 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"
   }
-}
+}