@ishlabs/cli 0.12.2 → 0.13.0

package/dist/commands/chat-config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ish chat config — Manage chatbot configurations (agent shape).
+ *
+ * A configuration captures *what the chatbot is* (model, system prompt,
+ * tools, sub-agents, custom {key, value} fields) — distinct from the
+ * *wire envelope* on a chatbot endpoint. Configurations live N-per-
+ * endpoint; chat iterations reference one and freeze a snapshot at
+ * creation time so historical comparisons stay reproducible.
+ *
+ * Four-verb surface mirroring `ish secret`: `list / set / get /
+ * delete`. `set` is the create-or-update upsert (composite write —
+ * mirrors MCP `chatbot_config_set` and the `chatbot_setup` precedent).
+ * `get --view iterations` surfaces the cross-study aggregation.
+ */
+import type { Command } from "commander";
+interface CustomField {
+    key: string;
+    value: string;
+}
+export declare function parseCustomField(raw: string): CustomField;
+export declare function parseCustomFieldsFlag(values: string[] | undefined): CustomField[] | undefined;
+export declare function attachChatConfigCommands(parent: Command): void;
+export {};

package/dist/commands/chat-config.js

@@ -0,0 +1,289 @@
+/**
+ * ish chat config — Manage chatbot configurations (agent shape).
+ *
+ * A configuration captures *what the chatbot is* (model, system prompt,
+ * tools, sub-agents, custom {key, value} fields) — distinct from the
+ * *wire envelope* on a chatbot endpoint. Configurations live N-per-
+ * endpoint; chat iterations reference one and freeze a snapshot at
+ * creation time so historical comparisons stay reproducible.
+ *
+ * Four-verb surface mirroring `ish secret`: `list / set / get /
+ * delete`. `set` is the create-or-update upsert (composite write —
+ * mirrors MCP `chatbot_config_set` and the `chatbot_setup` precedent).
+ * `get --view iterations` surfaces the cross-study aggregation.
+ */
+import * as fs from "node:fs";
+import { ApiError } from "../lib/api-client.js";
+import { ALIAS_PREFIX, tagAlias } from "../lib/alias-store.js";
+import { collectRepeatable, confirmDestructive, resolveChatConfig, resolveChatEndpoint, withClient, } from "../lib/command-helpers.js";
+import { output } from "../lib/output.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export function parseCustomField(raw) {
+    const idx = raw.indexOf("=");
+    if (idx <= 0) {
+        throw new Error(`--custom-field must be \`key=value\` (got "${raw}").`);
+    }
+    return { key: raw.slice(0, idx).trim(), value: raw.slice(idx + 1) };
+}
+export function parseCustomFieldsFlag(values) {
+    if (values === undefined)
+        return undefined;
+    const seen = new Set();
+    const out = [];
+    for (const raw of values) {
+        const f = parseCustomField(raw);
+        if (!f.key)
+            throw new Error("--custom-field key cannot be empty.");
+        if (seen.has(f.key)) {
+            throw new Error(`--custom-field key "${f.key}" is repeated; keys must be unique.`);
+        }
+        seen.add(f.key);
+        out.push(f);
+    }
+    return out;
+}
+function parseJsonListFlag(file, label) {
+    if (file === undefined)
+        return undefined;
+    const content = file === "-" ? fs.readFileSync(0, "utf-8") : fs.readFileSync(file, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        const m = err instanceof Error ? err.message : String(err);
+        throw new Error(`${label} is not valid JSON: ${m}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new Error(`${label} must be a JSON array.`);
+    return parsed;
+}
+function readSystemPrompt(systemPrompt, systemPromptFile) {
+    if (systemPrompt !== undefined && systemPromptFile !== undefined) {
+        throw new Error("Pass at most one of --system-prompt or --system-prompt-file.");
+    }
+    if (systemPrompt !== undefined)
+        return systemPrompt;
+    if (systemPromptFile !== undefined) {
+        return systemPromptFile === "-"
+            ? fs.readFileSync(0, "utf-8")
+            : fs.readFileSync(systemPromptFile, "utf-8");
+    }
+    return undefined;
+}
+function pruneUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+function attachList(parent) {
+    parent
+        .command("list")
+        .description("List configurations under a chatbot endpoint")
+        .option("--endpoint <id>", "Endpoint alias or UUID (defaults to active endpoint)")
+        .addHelpText("after", "\nExamples:\n  $ ish chat config list\n  $ ish chat config list --json | jq '.[] | {alias, name, isDefault, usageCount}'")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const epId = resolveChatEndpoint(undefined, opts.endpoint);
+            const rows = await client.get(`/chatbot-endpoints/${epId}/configurations`);
+            for (const row of rows) {
+                if (row.id)
+                    tagAlias(ALIAS_PREFIX.chatConfig, row.id);
+            }
+            if (globals.json) {
+                output(rows, true);
+                return;
+            }
+            if (rows.length === 0) {
+                console.log("No configurations yet. Run `ish chat config set --name <name>` to author one.");
+                return;
+            }
+            for (const row of rows) {
+                const alias = row.id ? tagAlias(ALIAS_PREFIX.chatConfig, row.id) : "?";
+                const def = row.isDefault ? " [default]" : "";
+                const ver = row.versionLabel ? ` (${row.versionLabel})` : "";
+                const model = row.model ? `  model=${row.model}` : "";
+                const usage = `  used=${row.usageCount ?? 0}`;
+                console.log(`${alias}  ${row.name}${ver}${def}${model}${usage}`);
+            }
+        });
+    });
+}
+function attachSet(parent) {
+    parent
+        .command("set")
+        .description("Create or update a chatbot configuration (composite upsert)")
+        .requiredOption("--name <name>", "Configuration name (unique per endpoint)")
+        .option("--endpoint <id>", "Endpoint alias or UUID (defaults to active endpoint; create only)")
+        .option("--config <id>", "Configuration alias or UUID — switches to update mode")
+        .option("--version-label <label>", "Optional version tag (e.g. v3, 1.2.0, git sha)")
+        .option("--description <text>", "Optional description")
+        .option("--model <id>", "Primary model identifier (e.g. claude-sonnet-4-6)")
+        .option("--system-prompt <text>", "System prompt text")
+        .option("--system-prompt-file <file>", 'Read system prompt from file (or "-" for stdin)')
+        .option("--tools-file <file>", 'JSON array of tools (or "-" for stdin)')
+        .option("--sub-agents-file <file>", 'JSON array of sub-agents (or "-" for stdin)')
+        .option("--custom-field <key=value>", "Custom field; repeat. Replaces all custom fields on update.", collectRepeatable)
+        .option("--default", "Mark as the endpoint's default configuration")
+        .addHelpText("after", `
+Without --config, POSTs a new configuration under the endpoint. With
+--config, PUTs an update. With --default, fires the set-default call
+after the write so a single command leaves the endpoint with the
+right default. Editing does NOT retroactively change historical
+iterations — each iteration froze a snapshot at creation.
+
+Examples:
+  $ ish chat config set --name v1-sonnet --model claude-sonnet-4-6 \\
+      --system-prompt-file ./prompt.txt --custom-field git_sha=abc --default
+  $ ish chat config set --config cc-abc --name v1.1-sonnet
+  $ cat tools.json | ish chat config set --name with-search --tools-file -`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const cid = opts.config ? resolveChatConfig(undefined, opts.config) : null;
+            const body = pruneUndefined({
+                name: opts.name,
+                versionLabel: opts.versionLabel,
+                description: opts.description,
+                model: opts.model,
+                systemPrompt: readSystemPrompt(opts.systemPrompt, opts.systemPromptFile),
+                tools: parseJsonListFlag(opts.toolsFile, "--tools-file"),
+                subAgents: parseJsonListFlag(opts.subAgentsFile, "--sub-agents-file"),
+                customFields: parseCustomFieldsFlag(opts.customField),
+            });
+            let saved;
+            if (cid === null) {
+                const epId = resolveChatEndpoint(undefined, opts.endpoint);
+                if (opts.default)
+                    body.isDefault = true;
+                saved = await client.post(`/chatbot-endpoints/${epId}/configurations`, body);
+            }
+            else {
+                saved = await client.put(`/chatbot-configurations/${cid}`, body);
+                if (opts.default) {
+                    saved = await client.post(`/chatbot-configurations/${cid}/set-default`);
+                }
+            }
+            if (saved.id)
+                tagAlias(ALIAS_PREFIX.chatConfig, saved.id);
+            if (!globals.quiet) {
+                const action = cid === null ? "Created" : "Updated";
+                const tag = saved.isDefault ? " (default)" : "";
+                const alias = saved.id ? tagAlias(ALIAS_PREFIX.chatConfig, saved.id) : "?";
+                console.error(`${action} configuration ${alias}${tag}`);
+            }
+            output(saved, globals.json);
+        });
+    });
+}
+function attachGet(parent) {
+    parent
+        .command("get")
+        .description("Get a chatbot configuration (or its referencing iterations)")
+        .argument("[id]", "Configuration alias or UUID")
+        .option("--config <id>", "Configuration alias or UUID (alternative to positional)")
+        .option("--view <view>", "default | iterations. `iterations` returns the cross-study aggregation list.", "default")
+        .addHelpText("after", `
+\`--view iterations\` returns every iteration referencing this
+configuration across studies, joined to study metadata. Mirrors
+\`study_get(view=...)\`.
+
+Examples:
+  $ ish chat config get cc-abc
+  $ ish chat config get cc-abc --view iterations --json | jq 'group_by(.studyName) | length'`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const cid = resolveChatConfig(id, opts.config);
+            if (opts.view === "iterations") {
+                const rows = await client.get(`/chatbot-configurations/${cid}/iterations`);
+                if (globals.json) {
+                    output(rows, true);
+                    return;
+                }
+                if (rows.length === 0) {
+                    console.log("No iterations reference this configuration yet.");
+                    return;
+                }
+                for (const r of rows) {
+                    console.log(`${r.iterationLabel}  ${r.studyName} — ${r.iterationName}  (${r.createdAt})`);
+                }
+                return;
+            }
+            if (opts.view !== "default") {
+                throw new Error(`--view must be 'default' or 'iterations' (got "${opts.view}").`);
+            }
+            const row = await client.get(`/chatbot-configurations/${cid}`);
+            if (row.id)
+                tagAlias(ALIAS_PREFIX.chatConfig, row.id);
+            output(row, globals.json);
+        });
+    });
+}
+function attachDelete(parent) {
+    parent
+        .command("delete")
+        .description("Delete a chatbot configuration (rejected when iterations reference it)")
+        .argument("[id]", "Configuration alias or UUID")
+        .option("--config <id>", "Configuration alias or UUID (alternative to positional)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .addHelpText("after", `
+Returns HTTP 409 (configuration_in_use) when iterations reference the
+configuration. Snapshots remain readable on those iterations but the
+live cross-study aggregation link breaks. Inspect \`usageCount\`
+via \`ish chat config get <id>\` first.
+
+Examples:
+  $ ish chat config delete cc-abc --yes`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const cid = resolveChatConfig(id, opts.config);
+            await confirmDestructive(`Delete chat configuration ${tagAlias(ALIAS_PREFIX.chatConfig, cid)}? This cannot be undone.`, { yes: opts.yes, json: globals.json });
+            try {
+                await client.del(`/chatbot-configurations/${cid}`);
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 409) {
+                    const detail = err.body;
+                    const ids = detail?.detail?.iteration_ids ?? [];
+                    const e = new Error(`Cannot delete: configuration is referenced by ${ids.length} iteration(s).`);
+                    e.error_kind =
+                        "configuration_in_use";
+                    e.iteration_ids = ids;
+                    throw e;
+                }
+                throw err;
+            }
+            output({
+                success: true,
+                deleted: true,
+                id: cid,
+                alias: tagAlias(ALIAS_PREFIX.chatConfig, cid),
+            }, globals.json, { writePath: true });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function attachChatConfigCommands(parent) {
+    const config = parent
+        .command("config")
+        .description("Manage chatbot configurations (agent shape: model, prompt, tools, sub-agents)")
+        .addHelpText("after", `
+Configurations live under a chatbot endpoint and are referenced by chat
+iterations. Each iteration freezes a snapshot at creation so editing a
+configuration does NOT retroactively change historical iterations. Use
+\`set --config <id>\` to update in place, or omit \`--config\` to create
+a new configuration. Aliases use the \`cc-\` prefix.`);
+    attachList(config);
+    attachSet(config);
+    attachGet(config);
+    attachDelete(config);
+}

package/dist/commands/chat.js

@@ -18,6 +18,7 @@ import { ApiError } from "../lib/api-client.js";
 import { output } from "../lib/output.js";
 import { formatChatEndpointList, formatChatEndpointDetail, envelopeFromRow, } from "../lib/chat-endpoint-formatters.js";
 import { getChatEndpointTemplate, TEMPLATE_NAMES, } from "../lib/chat-endpoint-templates.js";
+import { attachChatConfigCommands } from "./chat-config.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -57,25 +58,6 @@ function urlLooksLocal(url) {
         return false;
     }
 }
-function inferredToConfig(inferred) {
-    const cfg = {
-        transport: inferred.transport,
-        outgoing: {
-            url: inferred.outgoing.url ?? undefined,
-            method: inferred.outgoing.method,
-            headers: inferred.outgoing.headers ?? {},
-            bodyTemplate: inferred.outgoing.bodyTemplate ?? {},
-            mode: inferred.outgoing.mode,
-            roleAliases: inferred.outgoing.roleAliases ?? {},
-        },
-        incoming: inferred.incoming,
-        asyncPoll: inferred.asyncPoll ?? null,
-    };
-    if (inferred.streaming) {
-        cfg.streaming = inferred.streaming;
-    }
-    return cfg;
-}
 async function tunnelGuard(client) {
     try {
         await client.get("/connect/active");
@@ -355,12 +337,12 @@ endpoint, apply the override, and PUT the merged result. Field flags win over
     });
 }
 // ---------------------------------------------------------------------------
-// init — auto-detect-shape onboarding
+// init — test-and-map onboarding (auto-detect via /chat/test-and-map)
 // ---------------------------------------------------------------------------
 function attachChatEndpointInit(parent) {
     parent
         .command("init")
-        .description("Author an endpoint from a curl/JSON sample via auto-detect-shape, or from a known-good template")
+        .description("Author an endpoint from a curl/JSON sample via test-and-map, or from a known-good template")
         .option("--from-curl <file>", 'Path to a curl example file (or "-" for stdin)')
         .option("--from-json <file>", 'Path to a JSON request/response sample (or "-" for stdin)')
         .option("--template <name>", `Start from a known-good template (one of: ${TEMPLATE_NAMES.join(", ")})`)
@@ -446,22 +428,27 @@ Examples:
                 output(result, globals.json, { writePath: true });
                 return;
             }
-            // Auto-detect path (curl or JSON paste).
+            // Auto-detect path (curl or JSON paste). Drives the same
+            // /test-and-map endpoint the editor uses, so the CLI and editor
+            // stay aligned on inference behaviour and error vocabulary.
             const path = (opts.fromCurl ?? opts.fromJson);
             const paste = await readFileOrStdin(path);
-            const inferRes = await client.post(`/products/${ws}/chat/auto-detect-shape`, { paste }, { timeout: 120_000 });
-            if (!inferRes.ok) {
+            const mapRes = await client.post(`/products/${ws}/chat/test-and-map`, { documentation: paste }, { timeout: 120_000 });
+            if (mapRes.kind === "failure") {
                 // Surface as a structured failure envelope on stdout AND throw so
                 // the wrapper sets a non-zero exit. The thrown Error carries the
-                // shape's error_kind for the agent to branch on.
-                const err = new Error(inferRes.errorMessage ?? "auto-detect-shape failed.");
-                err.error_kind = inferRes.errorKind;
+                // backend's error_kind for the agent to branch on.
+                const err = new Error(mapRes.errorMessage ?? "test-and-map failed.");
+                err.error_kind = mapRes.errorKind;
                 throw err;
             }
-            const inferred = inferRes.inferred;
-            const config = inferredToConfig(inferred);
-            const inferredUrl = inferred.outgoing.url ?? null;
-            const detectedTunnel = urlLooksLocal(inferredUrl);
+            const config = mapRes.inferredConfig;
+            const inferredUrl = (typeof config.outgoing?.url === "string" && config.outgoing.url
+                ? config.outgoing.url
+                : null);
+            // Trust the backend's tunnel detection when present; fall back to
+            // the local heuristic only if the envelope didn't populate it.
+            const detectedTunnel = mapRes.tunnelBackedDetected ?? urlLooksLocal(inferredUrl);
             let tunnelBacked;
             if (opts.tunnelBacked === true)
                 tunnelBacked = true;
@@ -474,8 +461,9 @@ Examples:
             if (!inferredUrl) {
                 warnings.push("Inferred shape has no URL; set --url before testing.");
             }
-            if (inferred.confidence !== "high") {
-                warnings.push(`Auto-detect confidence: ${inferred.confidence} — verify the shape before running.`);
+            const confidence = mapRes.confidence ?? null;
+            if (confidence && confidence !== "high") {
+                warnings.push(`Auto-detect confidence: ${confidence} — verify the shape before running.`);
             }
             // Decide whether to save. --no-save short-circuits; otherwise save when
             // a name is available (--name wins; else fall back to the inferred
@@ -508,8 +496,8 @@ Examples:
                     }
                 }
             }
-            const missingSignals = Array.isArray(inferred.missingSignals)
-                ? inferred.missingSignals
+            const missingSignals = Array.isArray(mapRes.missingSignals)
+                ? mapRes.missingSignals
                 : [];
             const result = {
                 success: true,
@@ -519,8 +507,8 @@ Examples:
                 config,
                 tunnel_backed: tunnelBacked,
                 tunnel_backed_detected: detectedTunnel,
-                confidence: inferred.confidence,
-                explanation: inferred.explanation,
+                confidence,
+                explanation: mapRes.explanation ?? "",
                 missingSignals,
                 warnings,
             };
@@ -714,6 +702,7 @@ mirrors that editing model.`);
     attachChatEndpointInit(endpoint);
     attachChatEndpointTest(endpoint);
     attachChatEndpointMap(endpoint);
+    attachChatConfigCommands(chat);
 }
 // Re-exported for tests / external integration if needed.
 export { envelopeFromRow };

package/dist/commands/study-analyze.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ish study analyze / ish study insights — AI summary + key insights for a
+ * study.
+ *
+ * Wraps three backend endpoints already shipped server-side and used by the
+ * web overview page:
+ *
+ *   POST /studies/{id}/analysis  — kick off an analysis run
+ *   GET  /studies/{id}/results   — list runs for a study (newest first)
+ *   GET  /study-results/{id}     — fetch one run
+ *
+ * Status state machine: pending → running → (completed | failed). Polling
+ * mirrors the FE behaviour (5s here vs 15s in the FE — agents care more
+ * about latency than load).
+ */
+import type { Command } from "commander";
+export interface KeyInsight {
+    id: string;
+    title: string;
+    description: string;
+    category: "friction" | "confusion" | "blocker" | "observation" | "positive";
+    tester_count: number;
+    iteration_labels: string[];
+    is_discarded: boolean;
+    interaction_ids: string[];
+    sequence: number;
+    created_at: string;
+}
+export interface StudyResult {
+    id: string;
+    study_id: string;
+    status: "pending" | "running" | "completed" | "failed";
+    modality: string;
+    summary: string | null;
+    error_message: string | null;
+    progress_message: string | null;
+    key_insights: KeyInsight[];
+    created_at: string;
+    started_at: string | null;
+}
+export declare function attachStudyAnalyzeCommands(study: Command): void;

package/dist/commands/study-analyze.js

@@ -0,0 +1,187 @@
+/**
+ * ish study analyze / ish study insights — AI summary + key insights for a
+ * study.
+ *
+ * Wraps three backend endpoints already shipped server-side and used by the
+ * web overview page:
+ *
+ *   POST /studies/{id}/analysis  — kick off an analysis run
+ *   GET  /studies/{id}/results   — list runs for a study (newest first)
+ *   GET  /study-results/{id}     — fetch one run
+ *
+ * Status state machine: pending → running → (completed | failed). Polling
+ * mirrors the FE behaviour (5s here vs 15s in the FE — agents care more
+ * about latency than load).
+ */
+import { withClient, resolveStudy, parseWaitTimeout } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { output, printTable } from "../lib/output.js";
+import { WaitTimeoutError } from "./study-run.js";
+const POLL_INTERVAL_MS = 5_000;
+const ANALYSIS_TERMINAL_STATUSES = new Set(["completed", "failed"]);
+async function pollAnalysisUntilDone(client, opts) {
+    const start = Date.now();
+    let lastReported = "";
+    while (true) {
+        const result = await client.get(`/study-results/${opts.resultId}`, undefined, { timeout: 60_000 });
+        if (!opts.quiet) {
+            const line = result.progress_message
+                ? `${result.status}: ${result.progress_message}`
+                : result.status;
+            if (line !== lastReported) {
+                process.stderr.write(`  ${line}\n`);
+                lastReported = line;
+            }
+        }
+        if (ANALYSIS_TERMINAL_STATUSES.has(result.status)) {
+            return result;
+        }
+        if (Date.now() - start > opts.timeoutMs) {
+            throw new WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for analysis. ` +
+                `Status: ${result.status}. Run \`ish study insights ${opts.studyId}\` to check later.`, {
+                study_id: opts.studyId,
+                timeout_seconds: Math.round(opts.timeoutMs / 1000),
+                done: 0,
+                total: 1,
+                pending: 1,
+                rows: [],
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+}
+function formatKeyInsightsTable(insights) {
+    printTable(["#", "CATEGORY", "TESTERS", "TITLE"], insights
+        .filter((i) => !i.is_discarded)
+        .map((i) => [
+        String(i.sequence),
+        i.category,
+        String(i.tester_count),
+        i.title,
+    ]));
+}
+function formatStudyAnalysis(result) {
+    const header = `Analysis ${result.id} — ${result.status}`;
+    console.log(header);
+    if (result.started_at)
+        console.log(`  started_at: ${result.started_at}`);
+    if (result.progress_message)
+        console.log(`  progress: ${result.progress_message}`);
+    if (result.error_message)
+        console.log(`  error: ${result.error_message}`);
+    if (result.summary) {
+        console.log(`\nSummary:\n${result.summary}`);
+    }
+    if (result.key_insights && result.key_insights.length > 0) {
+        console.log("\nKey insights:");
+        formatKeyInsightsTable(result.key_insights);
+    }
+}
+export function attachStudyAnalyzeCommands(study) {
+    study
+        .command("analyze")
+        .description("Trigger an AI summary + key-insights analysis for a study. " +
+        "First analysis per study is free; subsequent runs cost 10 credits.")
+        .argument("[id]", "Study ID (defaults to active study)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
+        .option("--wait", "Poll until the run reaches completed or failed")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300; only with --wait)")
+        .addHelpText("after", `
+Examples:
+  $ ish study analyze                              # uses active study
+  $ ish study analyze <study-id>
+  $ ish study analyze <study-id> --wait
+  $ ish study analyze <study-id> --wait --timeout 600 --json
+
+Prerequisites (enforced server-side):
+  - Study modality is one of: interactive, video, audio, text, image, document
+  - At least 5 testers with completed interactions
+
+Read prior runs:
+  $ ish study insights <study-id>`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const studyId = resolveStudy(id);
+            const initial = await client.post(`/studies/${studyId}/analysis`);
+            if (!opts.wait) {
+                if (globals.json) {
+                    output(initial, true);
+                }
+                else {
+                    formatStudyAnalysis(initial);
+                    console.error(`\n  Run \`ish study insights ${studyId}\` to read the result once it completes,\n  or rerun with --wait to block.`);
+                }
+                return;
+            }
+            const timeoutMs = parseWaitTimeout(opts.timeout, 300_000);
+            const final = await pollAnalysisUntilDone(client, {
+                resultId: initial.id,
+                studyId,
+                timeoutMs,
+                quiet: globals.json,
+            });
+            if (globals.json) {
+                output(final, true);
+            }
+            else {
+                formatStudyAnalysis(final);
+            }
+        });
+    });
+    study
+        .command("insights")
+        .description("Read AI-generated insights from prior `ish study analyze` runs (newest first).")
+        .argument("[id]", "Study ID (defaults to active study)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
+        .option("--all", "Show every prior run as a compact table (default: latest only)")
+        .option("--result <id>", "Fetch a specific result by id rather than the latest")
+        .addHelpText("after", `
+Examples:
+  $ ish study insights                             # latest run for active study
+  $ ish study insights <study-id>
+  $ ish study insights <study-id> --all
+  $ ish study insights <study-id> --json
+  $ ish study insights <study-id> --result <result-id>
+
+Trigger a new run with \`ish study analyze --wait\`.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (opts.result) {
+                const single = await client.get(`/study-results/${resolveId(opts.result)}`);
+                if (globals.json) {
+                    output(single, true);
+                }
+                else {
+                    formatStudyAnalysis(single);
+                }
+                return;
+            }
+            const studyId = resolveStudy(id);
+            const history = await client.get(`/studies/${studyId}/results`);
+            const latest = history[0] ?? null;
+            if (globals.json) {
+                output({ latest, history }, true);
+                return;
+            }
+            if (!latest) {
+                console.log("No analysis runs yet. Trigger one with `ish study analyze`.");
+                return;
+            }
+            if (opts.all) {
+                console.log(`Analysis history for study ${studyId}:`);
+                printTable(["#", "ID", "STATUS", "STARTED", "INSIGHTS"], history.map((r, idx) => [
+                    String(history.length - idx),
+                    r.id,
+                    r.status,
+                    r.started_at ?? r.created_at,
+                    String((r.key_insights ?? []).length),
+                ]));
+                return;
+            }
+            formatStudyAnalysis(latest);
+            if (history.length > 1) {
+                console.error(`\n  ${history.length - 1} prior run${history.length - 1 === 1 ? "" : "s"} — pass --all to list.`);
+            }
+        });
+    });
+}

package/dist/commands/study-screenshots.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ish study screenshots — list and download screenshots produced by an
+ * interactive study run.
+ *
+ * Wraps two backend endpoints:
+ *
+ *   GET /studies/{id}/screenshots/grouped  — frame-grouped index
+ *   GET /screenshots/{id}                  — one row carrying screenshot_url
+ *
+ * The screenshot_url is a Supabase Storage URL (public or signed) — we fetch
+ * its bytes with NO Authorization header (the user's ish bearer is never
+ * forwarded cross-origin).
+ *
+ * Mirrors the agent-facing surface ish-mcp exposes via
+ * ``ish://study/{id}/screenshots`` and ``ish://study/{id}/screenshot/{scid}``.
+ * The CLI is for humans / scripts; the MCP resources are for LLM agents.
+ * Both wrap the same backend rows.
+ */
+import type { Command } from "commander";
+export declare function attachStudyScreenshotsCommands(study: Command): void;

package/dist/commands/study-screenshots.js

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

package/dist/commands/study.js

@@ -13,6 +13,8 @@ import { loadQuestionsManifest } from "../lib/ask-questions.js";
 import { isLocalPath } from "../lib/upload.js";
 import { attachStudyRunCommands } from "./study-run.js";
 import { attachStudyTesterCommands } from "./study-tester.js";
+import { attachStudyAnalyzeCommands } from "./study-analyze.js";
+import { attachStudyScreenshotsCommands } from "./study-screenshots.js";
 function collectRepeatable(value, prev = []) {
     return prev.concat([value]);
 }
@@ -690,4 +692,6 @@ Examples:
     });
     attachStudyRunCommands(study);
     attachStudyTesterCommands(study);
+    attachStudyAnalyzeCommands(study);
+    attachStudyScreenshotsCommands(study);
 }

package/dist/lib/alias-store.d.ts

@@ -18,6 +18,7 @@ export declare const ALIAS_PREFIX: {
     readonly ask: "a";
     readonly askRound: "r";
     readonly chatEndpoint: "ep";
+    readonly chatConfig: "cc";
 };
 /**
  * Save aliases for a list of IDs under the given prefix.

package/dist/lib/alias-store.js

@@ -21,6 +21,7 @@ export const ALIAS_PREFIX = {
     ask: "a",
     askRound: "r",
     chatEndpoint: "ep",
+    chatConfig: "cc",
 };
 /** Format a number with zero-padding (minimum 2 digits). */
 function padNum(n) {

package/dist/lib/command-helpers.d.ts

@@ -129,6 +129,12 @@ export declare function resolveAsk(explicit?: string): string;
  * endpoint persisted by `ish chat endpoint use`. Throws when none are set.
  */
 export declare function resolveChatEndpoint(positional?: string, flag?: string): string;
+/**
+ * Resolve a chat configuration id from a positional arg or `--config` flag.
+ * Configurations don't have an "active" notion (unlike endpoints), so this
+ * helper only resolves explicit input — there is no fallback.
+ */
+export declare function resolveChatConfig(positional?: string, flag?: string): string;
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export declare function collectRepeatable(value: string, prev?: string[]): string[];
 /**

package/dist/lib/command-helpers.js

@@ -598,6 +598,18 @@ export function resolveChatEndpoint(positional, flag) {
         return config.chat_endpoint;
     throw new Error('No chat endpoint set. Use `ish chat endpoint use <id>`, pass the endpoint id, or set --endpoint.');
 }
+/**
+ * Resolve a chat configuration id from a positional arg or `--config` flag.
+ * Configurations don't have an "active" notion (unlike endpoints), so this
+ * helper only resolves explicit input — there is no fallback.
+ */
+export function resolveChatConfig(positional, flag) {
+    if (positional)
+        return resolveId(positional);
+    if (flag)
+        return resolveId(flag);
+    throw new Error("Pass a chat configuration alias / UUID (positional argument or --config <id>).");
+}
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export function collectRepeatable(value, prev = []) {
     return prev.concat([value]);

package/dist/lib/docs.js

@@ -1116,7 +1116,10 @@ time the CLI sees an entity.
 - \`tp-\`   tester profile
 - \`tps-\`  tester-profile source
 - \`a-\`    ask
+- \`r-\`    ask round
 - \`c-\`    config (simulation config)
+- \`ep-\`   chatbot endpoint
+- \`cc-\`   chatbot configuration
 
 ## Examples
 
@@ -1130,6 +1133,70 @@ ish profile generate --source tps-3a4 --count 4
 The full UUID is also always accepted. Add \`--verbose\` to JSON output
 to see UUIDs alongside aliases.
 `;
+const REFERENCE_SCREENSHOTS = `# reference: screenshots and iteration media
+
+Interactive study runs produce per-frame screenshots server-side. They
+let you (or an agent) see what testers actually saw alongside the
+sentiment summary.
+
+## Screenshots — interactive studies only
+
+Screenshots are produced by interactive runs only — chat / video / text
+studies don't have them.
+
+### CLI
+
+\`\`\`
+ish study screenshots                          # active study, frame-grouped
+ish study screenshots <study-id> --json        # machine-readable index
+ish study screenshots download <study-id> --id <screenshot-id> --out shot.png
+ish study screenshots download <study-id> --all --out ./shots/
+\`\`\`
+
+The list is grouped by frame. Each frame represents a distinct viewport
+testers landed on (e.g. the hero, the pricing block, a documentation
+page). Pulling every screenshot can be heavy — start with the listing,
+then download representative frames.
+
+### MCP (agent-facing)
+
+\`ish-mcp\` exposes the same artifacts as MCP Resources so an agent can
+look at them inline. \`study_get(view='summary' | 'per_tester')\` on an
+interactive study now carries:
+
+- \`screenshots_resource: ish://study/<id>/screenshots\` — JSON index
+  with frame groups and per-screenshot \`resource_uri\` strings.
+
+Read those URIs with \`resources/read\`:
+
+- \`ish://study/<study-id>/screenshots\` — index (JSON).
+- \`ish://study/<study-id>/screenshot/<screenshot-id>\` — image bytes.
+
+## Iteration media — caller-supplied URLs
+
+For non-interactive studies the iteration carries the artifact directly
+(\`content_url\` for video / audio / document, \`image_urls\` for image,
+\`featured_image_url\` for text-as-email). \`ish iteration get <id>\`
+already shows those fields.
+
+The MCP surface adds resource URIs alongside them on every \`Iteration\`
+payload:
+
+- \`media_resources: [ish://iteration/<id>/media/<kind>/<index>, …]\`
+  where \`kind\` is one of \`content\`, \`image\`, \`featured_image\`.
+
+Index resource: \`ish://iteration/<iteration-id>/media\` — lists every
+item (kind, index, source URL, resource URI).
+Bytes: \`ish://iteration/<iteration-id>/media/<kind>/<index>\`.
+
+## Auth boundary
+
+Screenshot URLs and iteration media URLs are *self-credentialed* — public
+URLs carry no credential, signed URLs embed the credential in the query
+string. Both the CLI and the MCP server fetch their bytes WITHOUT
+forwarding your ish bearer token, so the bearer never leaks
+cross-origin.
+`;
 const REFERENCE_JSON_MODE = `# reference: output modes for agents
 
 \`ish\` distinguishes **three output modes** so agents don't have to
@@ -1772,7 +1839,7 @@ ish chat endpoint init \\
     --name my-bot
 \`\`\`
 
-\`init\` posts the curl to \`/chat/auto-detect-shape\`, infers the
+\`init\` posts the curl to \`/chat/test-and-map\`, infers the
 config (URL, method, headers, body template, response paths,
 mode, async-poll if applicable), and saves it as a chatbot endpoint
 resource. Output JSON shape:
@@ -1893,7 +1960,7 @@ The legacy per-affordance fields (\`optionsPath\`,
 slot tagged with \`kind\`; anything passive is a reference. New
 affordance shapes ship as a new \`kind\` value, no schema migration.
 
-\`auto-detect-shape\` (the engine behind \`init\`) populates these
+\`test-and-map\` (the engine behind \`init\`) populates these
 lists from the response stub via a shape-based classifier:
 \`list[{label, id?}]\` becomes \`alternatives\`,
 \`{fields: [...]}\` becomes \`form\`,
@@ -2214,6 +2281,12 @@ const PAGES = [
         description: "Display vs capture vs chain: --human, --get, --json, --fields, exit codes, pipe behavior.",
         body: REFERENCE_JSON_MODE,
     },
+    {
+        slug: "reference/screenshots",
+        title: "reference: screenshots and iteration media",
+        description: "How to list and fetch interactive-run screenshots and iteration media URLs from CLI and MCP, and the cross-origin auth boundary.",
+        body: REFERENCE_SCREENSHOTS,
+    },
     {
         slug: "reference/billing-limits",
         title: "reference: billing tier limits",

package/dist/lib/skill-content.js

@@ -147,6 +147,21 @@ ish ask dispatch a-6ec --wait
 ish study results
 ish ask results a-6ec --round 1
 
+# AI summary + key insights (any modality with completed testers)
+ish study analyze --wait                                       # trigger + block
+ish study insights                                             # read latest
+
+# Screenshots (interactive studies — see what testers actually saw)
+ish study screenshots                                          # list, frame-grouped
+ish study screenshots download <study-id> --id <scid> --out shot.png
+ish study screenshots download <study-id> --all --out ./shots/
+
+# Chat configurations (model + system prompt + tools per chatbot endpoint)
+ish chat config list                                           # active endpoint
+ish chat config set --name v1 --model claude-sonnet-4-6 \\
+    --system-prompt-file ./prompt.txt --default
+ish chat config get cc-abc --view iterations                   # cross-study use
+
 # Read offline docs
 ish docs overview
 ish docs get-page <slug>

package/dist/lib/types.js

@@ -7,7 +7,7 @@ export const VALID_CONTENT_TYPES = {
     text: ["narrative", "informational", "commercial", "editorial", "reference", "email", "news"],
     video: ["tutorial", "documentary", "entertainment", "review", "lifestyle", "news", "social_post", "ad"],
     audio: ["music", "narration", "conversation", "speech", "soundscape", "news", "ad"],
-    image: ["product", "photography", "infographic", "artwork", "interface", "social_post", "ad"],
+    image: ["product", "photography", "infographic", "artwork", "interface", "visual_assets", "social_post", "ad"],
     document: ["deck", "presentation", "report", "brochure", "guide"],
 };
 export const ASK_VARIANT_KINDS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {