@ishlabs/cli 0.19.0 → 0.21.0

package/dist/lib/output.d.ts

@@ -48,6 +48,12 @@ export declare function formatWorkspaceDetail(workspace: Record<string, unknown>
 export declare function formatSiteAccessStatus(summary: import("./site-access.js").SiteAccessSummary, json: boolean): void;
 export declare function formatStudyList(studies: Record<string, unknown>[], json: boolean): void;
 export declare function formatStudyDetail(study: Record<string, unknown>, json: boolean, options?: OutputOptions, participants?: ReadonlyArray<Record<string, unknown>>): void;
+/**
+ * Stable JSON envelope for `study results`. Schema is fixed regardless of
+ * study state — fields default to `null`, `0`, or `[]` when nothing has run.
+ * Agents can rely on the keys always being present (M4).
+ */
+export declare function buildStudyResultsEnvelope(study: Record<string, unknown>, participants: ReadonlyArray<Record<string, unknown>>): Record<string, unknown>;
 export declare function formatStudyResults(study: Record<string, unknown>, participants: ReadonlyArray<Record<string, unknown>>, json: boolean): void;
 /**
  * `study results --summary` projection. Drops interview_answers + per-participant
@@ -102,3 +108,15 @@ export declare function deriveWinnerConfidence(args: {
 }): "low" | "medium" | "high";
 export declare function formatAskResults(ask: Record<string, unknown>, json: boolean, roundFilter?: number): void;
 export declare function formatConfigList(configs: Record<string, unknown>[], json: boolean): void;
+export type StudyResultsGroupByKind = "iteration" | "frame" | "segment" | "turn" | "assignment" | "step";
+/**
+ * Render a `--group-by <kind>` projection. JSON mode is a thin pass-through
+ * to jsonOutput with `preProjected: true` so the lean transform doesn't
+ * strip our stable empties. Human mode renders one section per slice plus
+ * a small ASCII sentiment histogram.
+ *
+ * The renderer accepts both the wrapped `{study, slices, ...}` shape (per-
+ * iteration) and the bare-array shape (every other --group-by); the
+ * surface (T5) doesn't need to know the difference.
+ */
+export declare function formatStudyResultsGroupBy(projection: unknown, kind: StudyResultsGroupByKind, json: boolean): void;

package/dist/lib/output.js

@@ -224,7 +224,11 @@ function wrapList(items, existing, opts = {}) {
     const limit = typeof existing?.limit === "number" ? existing.limit : returned;
     const offset = typeof existing?.offset === "number" ? existing.offset : 0;
     const has_more = total > offset + returned;
-    const leanItems = _verbose || opts.preProjectedItems
+    // ISSUE-031: if the user explicitly named fields via --fields or --get,
+    // skip the per-item lean-strip so the requested fields actually survive
+    // to the output. Otherwise `--fields id,alias` silently drops `id`.
+    const userSpecifiedFields = (_fields && _fields.length > 0) || (typeof _getField === "string" && _getField.length > 0);
+    const leanItems = _verbose || opts.preProjectedItems || userSpecifiedFields
         ? items
         : leanJson(items) ?? [];
     return { items: leanItems, total, returned, limit, offset, has_more };
@@ -277,9 +281,16 @@ function pickFields(data, fields) {
 /** Serialize data as JSON, applying lean transform and field selection. */
 function jsonOutput(data, options = {}) {
     let out;
-    if (_verbose || options.preProjected) {
-        // Verbose: full payload. preProjected: caller already chose the fields,
-        // so don't strip again (otherwise leanJson would drop e.g. created_at).
+    // ISSUE-031: when the user explicitly names fields via --fields or
+    // --get, their request takes precedence over the default lean-strip.
+    // Previously --fields id,alias would silently drop `id` because
+    // leanJson ran first and stripped UUID-valued fields. The user
+    // asking for a field is unambiguous intent — bypass the strip.
+    const userSpecifiedFields = (_fields && _fields.length > 0) || (typeof _getField === "string" && _getField.length > 0);
+    if (_verbose || options.preProjected || userSpecifiedFields) {
+        // Verbose: full payload. preProjected: caller already chose the fields.
+        // userSpecifiedFields: caller said exactly what they want — don't
+        // second-guess by stripping UUIDs they asked for.
         out = data;
     }
     else {
@@ -461,6 +472,29 @@ function suggestionsForError(err) {
     }
     return [];
 }
+/**
+ * Pattern F (ISSUE-023): rewrite server-side internal entity names to the
+ * user-facing CLI surface names so messages like "Product not found" don't
+ * leak the backend's internal vocabulary to a first-time CLI user.
+ *
+ * Mapping reflects the rename audit: server still calls workspaces
+ * "products" and people "profiles" / "tester profiles" in some response
+ * messages; the CLI surface is `workspace` / `person`. Source is
+ * `attachment` server-side.
+ *
+ * Word-boundary anchored to avoid touching e.g. "productivity" or
+ * "Attachments must be ..." (the latter is genuinely about attachments).
+ */
+function remapEntityName(message) {
+    return message
+        .replace(/\bProduct not found\b/g, "Workspace not found")
+        .replace(/\bproduct not found\b/g, "workspace not found")
+        .replace(/\bTester [Pp]rofile not found\b/g, (m) => m.includes("P") ? "Person not found" : "person not found")
+        .replace(/\bProfile not found\b/g, "Person not found")
+        .replace(/\bprofile not found\b/g, "person not found")
+        .replace(/\bAttachment not found\b/g, "Source not found")
+        .replace(/\battachment not found\b/g, "source not found");
+}
 export function outputError(err, json) {
     const suggestions = suggestionsForError(err);
     if (err instanceof ApiError) {
@@ -505,7 +539,7 @@ export function outputError(err, json) {
             : undefined;
         if (json) {
             console.error(JSON.stringify({
-                error: err.message,
+                error: remapEntityName(err.message),
                 error_code: err.error_code,
                 status: err.status,
                 retryable: err.retryable,
@@ -527,7 +561,7 @@ export function outputError(err, json) {
                 console.error("Error: Insufficient credits. Purchase more at https://app.ishlabs.io");
             }
             else {
-                console.error(`Error: ${err.message}`);
+                console.error(`Error: ${remapEntityName(err.message)}`);
             }
             if (Array.isArray(bodyErrors)) {
                 for (const entry of bodyErrors) {
@@ -549,6 +583,12 @@ export function outputError(err, json) {
     else if (err instanceof ValidationError) {
         if (json) {
             console.error(JSON.stringify({
+                // ValidationError is CLI-thrown (we control its message), so we
+                // don't apply remapEntityName — that helper exists to translate
+                // server-side internal vocabulary ("Product"/"Profile"/"Attachment")
+                // back to user-facing names. Applying it here risks mangling
+                // user-supplied content (e.g. a workspace name containing "Profile
+                // not found"). Restrict the remap to the ApiError branch.
                 error: err.message,
                 error_code: "validation_error",
                 retryable: false,
@@ -597,6 +637,10 @@ export function outputError(err, json) {
         const mergedSuggestions = [...new Set([...suggestions, ...taggedSuggestions])];
         if (json) {
             console.error(JSON.stringify({
+                // Generic Error: CLI-thrown (we control the message), so we don't
+                // apply remapEntityName — see ValidationError branch above for the
+                // same reasoning. Server-side names only leak through the ApiError
+                // branch where remapEntityName IS applied.
                 error: err.message,
                 error_code: errorCode,
                 retryable,
@@ -702,7 +746,7 @@ export function formatWorkspaceList(workspaces, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.workspace);
-    printTable(["#", "NAME", "ROOM", "STUDIES", "ASKS", "PARTICIPANTS", "LAST ACTIVITY"], workspaces.map((w) => [
+    printTable(["ALIAS", "NAME", "ROOM", "STUDIES", "ASKS", "PARTICIPANTS", "LAST ACTIVITY"], workspaces.map((w) => [
         aliasMap.get(String(w.id)) || String(w.id || ""),
         String(w.name || ""),
         formatHeadroom(w.has_headroom),
@@ -784,7 +828,7 @@ export function formatStudyList(studies, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.study);
-    printTable(["#", "NAME", "MODALITY", "TYPE", "STATUS", "PARTICIPANTS"], studies.map((s) => [
+    printTable(["ALIAS", "NAME", "MODALITY", "TYPE", "STATUS", "PARTICIPANTS"], studies.map((s) => [
         aliasMap.get(String(s.id)) || String(s.id || ""),
         String(s.name || ""),
         String(s.modality || "-"),
@@ -934,7 +978,7 @@ export function formatStudyDetail(study, json, options = {}, participants) {
     const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
     if (allParticipants.length > 0) {
         console.log(`\nParticipants (${allParticipants.length}):`);
-        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS"], allParticipants.map((t) => [
+        printTable(["ALIAS", "NAME", "ITERATION", "STATUS", "INTERACTIONS"], allParticipants.map((t) => [
             t.id ? deterministicAlias(ALIAS_PREFIX.participant, t.id) : t.id,
             t.name,
             t.iterationLabel,
@@ -948,7 +992,7 @@ export function formatStudyDetail(study, json, options = {}, participants) {
  * study state — fields default to `null`, `0`, or `[]` when nothing has run.
  * Agents can rely on the keys always being present (M4).
  */
-function buildStudyResultsEnvelope(study, participants) {
+export function buildStudyResultsEnvelope(study, participants) {
     const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
     const studyAlias = study.id
         ? deterministicAlias(ALIAS_PREFIX.study, String(study.id))
@@ -1074,7 +1118,7 @@ export function formatStudyResults(study, participants, json) {
     // Participants table
     if (allParticipants.length > 0) {
         console.log("\nParticipants:");
-        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS", "SENTIMENT"], allParticipants.map((t) => {
+        printTable(["ALIAS", "NAME", "ITERATION", "STATUS", "INTERACTIONS", "SENTIMENT"], allParticipants.map((t) => {
             const parts = Object.entries(t.sentimentCounts).map(([label, count]) => `${count} ${label.toLowerCase()}`);
             return [
                 t.id ? deterministicAlias(ALIAS_PREFIX.participant, t.id) : t.id,
@@ -1375,7 +1419,7 @@ export function formatIterationList(iterations, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.iteration);
-    printTable(["#", "LABEL", "NAME", "PARTICIPANTS", "CREATED"], iterations.map((it) => {
+    printTable(["ALIAS", "LABEL", "NAME", "PARTICIPANTS", "CREATED"], iterations.map((it) => {
         const participants = Array.isArray(it.participants) ? it.participants.length : 0;
         return [
             aliasMap.get(String(it.id)) || String(it.id || ""),
@@ -1449,7 +1493,7 @@ export function formatPersonList(profiles, json, limit) {
         console.log("No participant profiles.");
         return;
     }
-    printTable(["#", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
+    printTable(["ALIAS", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
         String(p.alias || p.id || ""),
         String(p.name || ""),
         String(p.occupation || "-"),
@@ -1504,7 +1548,7 @@ export function formatGeneratedProfileList(profiles, json) {
         console.log(jsonOutput(list));
         return;
     }
-    printTable(["#", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
+    printTable(["ALIAS", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
         String(p.alias || p.id || ""),
         String(p.name || ""),
         String(p.occupation || "-"),
@@ -1529,7 +1573,7 @@ export function formatSimulationPoll(results, json, isMedia = false) {
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.participant);
     const countHeader = isMedia ? "SEGMENTS" : "INTERACTIONS";
-    printTable(["#", "PARTICIPANT", "STATUS", countHeader], results.map((r) => {
+    printTable(["ALIAS", "PARTICIPANT", "STATUS", countHeader], results.map((r) => {
         const id = String(r.id || r.participant_id || "");
         return [
             aliasMap.get(id) || id,
@@ -1574,7 +1618,7 @@ export function formatAskList(asks, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.ask);
-    printTable(["#", "NAME", "STATUS", "PARTICIPANTS", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
+    printTable(["ALIAS", "NAME", "STATUS", "PARTICIPANTS", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
         aliasMap.get(String(a.id)) || String(a.id || ""),
         String(a.name || ""),
         String(a.status || "-"),
@@ -1675,7 +1719,7 @@ export function formatAskDetail(ask, json) {
                 String(obj.status || "-"),
             ];
         });
-        printTable(["#", "NAME", "STATUS"], rows);
+        printTable(["ALIAS", "NAME", "STATUS"], rows);
         if (participants.length > 20)
             console.log(`  … and ${participants.length - 20} more`);
     }
@@ -2145,7 +2189,7 @@ export function formatConfigList(configs, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.config);
-    printTable(["#", "NAME", "SOURCE", "CREATED"], configs.map((c) => [
+    printTable(["ALIAS", "NAME", "SOURCE", "CREATED"], configs.map((c) => [
         aliasMap.get(String(c.id)) || String(c.id || ""),
         String(c.name || ""),
         String(c.source_type || "manual"),
@@ -2182,3 +2226,219 @@ function formatDate(value) {
         return str.slice(0, 10);
     }
 }
+const POSITIVE_SENTIMENT = new Set(["satisfied", "curious", "engaged", "confident", "delighted"]);
+const NEGATIVE_SENTIMENT = new Set(["frustrated", "confused", "blocked", "anxious", "disappointed"]);
+function sentimentColor(label) {
+    const l = label.toLowerCase();
+    if (POSITIVE_SENTIMENT.has(l))
+        return c.green;
+    if (NEGATIVE_SENTIMENT.has(l))
+        return c.red;
+    return c.dim;
+}
+function asciiHistogram(hist, options = {}) {
+    const width = options.width ?? 20;
+    const indent = options.indent ?? "  ";
+    const entries = Object.entries(hist).filter(([, v]) => v > 0);
+    if (entries.length === 0)
+        return [];
+    const max = entries.reduce((acc, [, v]) => (v > acc ? v : acc), 0);
+    const labelWidth = entries.reduce((acc, [k]) => (k.length > acc ? k.length : acc), 0);
+    return entries
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([label, count]) => {
+        const bars = max > 0 ? Math.max(1, Math.round((count / max) * width)) : 0;
+        const color = sentimentColor(label);
+        return `${indent}${label.padEnd(labelWidth)}  ${color}${"█".repeat(bars)}${c.reset}  ${count}`;
+    });
+}
+function slicesFromProjection(projection) {
+    // Iteration projection wraps `{ study, slices, totals_unfiltered, warnings }`;
+    // all others are bare arrays. Both come through here.
+    if (Array.isArray(projection)) {
+        return projection.filter((s) => Boolean(s) && typeof s === "object" && !Array.isArray(s));
+    }
+    if (projection && typeof projection === "object") {
+        const wrapped = projection;
+        const slices = wrapped.slices;
+        if (Array.isArray(slices)) {
+            return slices.filter((s) => Boolean(s) && typeof s === "object" && !Array.isArray(s));
+        }
+    }
+    return [];
+}
+function totalInteractionsFromSlices(slices) {
+    let total = 0;
+    for (const s of slices) {
+        const n = typeof s.interaction_count === "number" ? s.interaction_count : 0;
+        total += n;
+    }
+    return total;
+}
+function totalsUnfilteredFromProjection(projection) {
+    if (projection && typeof projection === "object" && !Array.isArray(projection)) {
+        const t = projection.totals_unfiltered;
+        if (t && typeof t === "object" && !Array.isArray(t)) {
+            return t;
+        }
+    }
+    return null;
+}
+function renderIterationSlice(slice) {
+    const label = String(slice.iteration_label ?? slice.iteration_id ?? "?");
+    const pCount = Number(slice.participant_count ?? 0);
+    const iCount = Number(slice.interaction_count ?? 0);
+    console.log(`\n  ${c.bold}Iteration ${label}${c.reset}  ${c.dim}${pCount} participant${pCount !== 1 ? "s" : ""} · ${iCount} interaction${iCount !== 1 ? "s" : ""}${c.reset}`);
+    const hist = slice.sentiment ?? {};
+    for (const line of asciiHistogram(hist, { indent: "    " }))
+        console.log(line);
+    const top = Array.isArray(slice.top_actions) ? slice.top_actions : [];
+    if (top.length > 0) {
+        const parts = top.map((a) => `${a.action_type} ×${a.count}`);
+        console.log(`    ${c.dim}Top actions:${c.reset} ${parts.join(", ")}`);
+    }
+    const comments = Array.isArray(slice.sample_comments) ? slice.sample_comments : [];
+    for (const ccomment of comments) {
+        console.log(`    ${c.dim}"${ccomment}"${c.reset}`);
+    }
+}
+function renderFrameSlice(slice) {
+    const label = slice.frame_label ? String(slice.frame_label) : String(slice.frame_id);
+    const iCount = Number(slice.interaction_count ?? 0);
+    const aliases = Array.isArray(slice.participant_aliases) ? slice.participant_aliases : [];
+    console.log(`\n  ${c.bold}${label}${c.reset}  ${c.dim}${iCount} interaction${iCount !== 1 ? "s" : ""} · ${aliases.length} participant${aliases.length !== 1 ? "s" : ""}${c.reset}`);
+    const hist = slice.sentiment_histogram ?? {};
+    for (const line of asciiHistogram(hist, { indent: "    " }))
+        console.log(line);
+    const comments = Array.isArray(slice.sample_comments) ? slice.sample_comments : [];
+    for (const ccomment of comments) {
+        console.log(`    ${c.dim}"${ccomment}"${c.reset}`);
+    }
+}
+function renderSegmentSlice(slice) {
+    const idx = slice.segment_index;
+    const label = slice.segment_label ? String(slice.segment_label) : null;
+    const header = idx !== null && idx !== undefined
+        ? `Segment ${idx}${label ? ` — ${label}` : ""}`
+        : (label ?? "Segment ?");
+    const iCount = Number(slice.interaction_count ?? 0);
+    console.log(`\n  ${c.bold}${header}${c.reset}  ${c.dim}${iCount} interaction${iCount !== 1 ? "s" : ""}${c.reset}`);
+    const hist = slice.sentiment_histogram ?? {};
+    for (const line of asciiHistogram(hist, { indent: "    " }))
+        console.log(line);
+    const engagement = slice.engagement_histogram ?? {};
+    if (Object.keys(engagement).length > 0) {
+        const parts = Object.entries(engagement).map(([k, v]) => `${v} ${k}`);
+        console.log(`    ${c.dim}Engagement:${c.reset} ${parts.join(", ")}`);
+    }
+    const comments = Array.isArray(slice.sample_comments) ? slice.sample_comments : [];
+    for (const ccomment of comments) {
+        console.log(`    ${c.dim}"${ccomment}"${c.reset}`);
+    }
+}
+function renderTurnSlice(slice) {
+    const turn = Number(slice.turn_index ?? 0);
+    const iCount = Number(slice.interaction_count ?? 0);
+    const failures = Number(slice.failures ?? 0);
+    const failPart = failures > 0 ? `  ${c.red}${failures} failure${failures !== 1 ? "s" : ""}${c.reset}` : "";
+    console.log(`\n  ${c.bold}Turn ${turn}${c.reset}  ${c.dim}${iCount} interaction${iCount !== 1 ? "s" : ""}${c.reset}${failPart}`);
+    const hist = slice.sentiment_histogram ?? {};
+    for (const line of asciiHistogram(hist, { indent: "    " }))
+        console.log(line);
+    const replies = Array.isArray(slice.sample_replies) ? slice.sample_replies : [];
+    for (const r of replies) {
+        console.log(`    ${c.dim}"${r}"${c.reset}`);
+    }
+}
+function renderAssignmentSlice(slice) {
+    const name = String(slice.assignment_name ?? slice.assignment_id ?? "?");
+    const iCount = Number(slice.interaction_count ?? 0);
+    console.log(`\n  ${c.bold}${name}${c.reset}  ${c.dim}${iCount} interaction${iCount !== 1 ? "s" : ""}${c.reset}`);
+    const hist = slice.sentiment_histogram ?? {};
+    for (const line of asciiHistogram(hist, { indent: "    " }))
+        console.log(line);
+    const sc = Array.isArray(slice.step_completion) ? slice.step_completion : [];
+    if (sc.length > 0) {
+        const rows = sc.map((s) => [
+            String(s.name ?? s.step_id ?? "?"),
+            String(s.passed ?? 0),
+            String(s.inconclusive ?? 0),
+            String(s.failed ?? 0),
+            typeof s.rate === "number" ? s.rate.toFixed(2) : "-",
+        ]);
+        console.log(`    ${c.dim}Steps:${c.reset}`);
+        printTable(["STEP", "PASSED", "INCONCLUSIVE", "FAILED", "RATE"], rows);
+    }
+}
+function renderStepSlice(slice) {
+    const name = String(slice.step_name ?? slice.step_id ?? "?");
+    const assignment = String(slice.assignment_name ?? "?");
+    const total = Number(slice.total ?? 0);
+    const passed = Number(slice.passed ?? 0);
+    const inconclusive = Number(slice.inconclusive ?? 0);
+    const failed = Number(slice.failed ?? 0);
+    const rate = typeof slice.rate === "number" ? slice.rate.toFixed(2) : "-";
+    const rateColor = failed > passed ? c.red : (passed > failed ? c.green : c.dim);
+    console.log(`\n  ${c.bold}${assignment} › ${name}${c.reset}  ${rateColor}${passed}/${total} passed${c.reset}  ${c.dim}(${inconclusive} inconclusive, ${failed} failed, rate ${rate})${c.reset}`);
+    const verdicts = Array.isArray(slice.participant_verdicts)
+        ? slice.participant_verdicts
+        : [];
+    if (verdicts.length > 0) {
+        const rows = verdicts.map((v) => [
+            String(v.participant_alias ?? "-"),
+            String(v.verdict ?? "-"),
+            v.reason ? truncate(String(v.reason), 60) : "-",
+        ]);
+        printTable(["PARTICIPANT", "VERDICT", "REASON"], rows);
+    }
+}
+/**
+ * Render a `--group-by <kind>` projection. JSON mode is a thin pass-through
+ * to jsonOutput with `preProjected: true` so the lean transform doesn't
+ * strip our stable empties. Human mode renders one section per slice plus
+ * a small ASCII sentiment histogram.
+ *
+ * The renderer accepts both the wrapped `{study, slices, ...}` shape (per-
+ * iteration) and the bare-array shape (every other --group-by); the
+ * surface (T5) doesn't need to know the difference.
+ */
+export function formatStudyResultsGroupBy(projection, kind, json) {
+    if (json) {
+        console.log(jsonOutput(projection, { preProjected: true }));
+        return;
+    }
+    const slices = slicesFromProjection(projection);
+    const totalInteractions = totalInteractionsFromSlices(slices);
+    const unfiltered = totalsUnfilteredFromProjection(projection);
+    const totalUnfiltered = unfiltered && typeof unfiltered.interaction_count === "number"
+        ? unfiltered.interaction_count
+        : null;
+    const headline = `Sliced by ${kind}: ${slices.length} group${slices.length !== 1 ? "s" : ""} (${totalInteractions}${totalUnfiltered !== null ? `/${totalUnfiltered}` : ""} interaction${totalInteractions !== 1 ? "s" : ""})`;
+    console.log(`${c.bold}${headline}${c.reset}`);
+    if (slices.length === 0) {
+        console.log(`  ${c.dim}(no groups matched)${c.reset}`);
+        return;
+    }
+    for (const slice of slices) {
+        switch (kind) {
+            case "iteration":
+                renderIterationSlice(slice);
+                break;
+            case "frame":
+                renderFrameSlice(slice);
+                break;
+            case "segment":
+                renderSegmentSlice(slice);
+                break;
+            case "turn":
+                renderTurnSlice(slice);
+                break;
+            case "assignment":
+                renderAssignmentSlice(slice);
+                break;
+            case "step":
+                renderStepSlice(slice);
+                break;
+        }
+    }
+}

package/dist/lib/profile-sources.js

@@ -164,6 +164,11 @@ export async function resolveSourceRef(client, value, opts) {
 }
 // --- Agentic generation jobs ---
 const GENERATION_POLL_INTERVAL_MS = 2_500;
+/** NEW-CP-3: emit a "still running" heartbeat at least this often even if
+ *  status/progress_message hasn't changed. Backend often stays at
+ *  `running` with no message for tens of seconds; without a breadcrumb
+ *  the CLI looks frozen. */
+const GENERATION_HEARTBEAT_MS = 15_000;
 const GENERATION_TERMINAL_STATUSES = new Set(["completed", "failed"]);
 /**
  * Thrown when a generation job doesn't reach a terminal status before the
@@ -190,7 +195,9 @@ export class GenerationTimeoutError extends Error {
 export async function pollGenerationJobUntilDone(client, jobId, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 600_000;
     const deadline = Date.now() + timeoutMs;
+    const startedAt = Date.now();
     let lastReported = "";
+    let lastHeartbeatAt = Date.now();
     while (true) {
         const job = await client.get(`/people/generation-jobs/${jobId}`, undefined, { timeout: 60_000 });
         if (!opts.quiet) {
@@ -198,8 +205,19 @@ export async function pollGenerationJobUntilDone(client, jobId, opts = {}) {
                 ? `${job.status}: ${job.progress_message}`
                 : job.status;
             if (line !== lastReported) {
+                // Status / message changed — emit it as a fresh breadcrumb.
                 process.stderr.write(`  ${line}\n`);
                 lastReported = line;
+                lastHeartbeatAt = Date.now();
+            }
+            else if (Date.now() - lastHeartbeatAt >= GENERATION_HEARTBEAT_MS) {
+                // NEW-CP-3: the backend often holds at `status=running` with no
+                // `progress_message` for tens of seconds. Without a heartbeat the
+                // CLI looks frozen. Emit a "still running" line every 15s so the
+                // operator knows we're polling and not hung.
+                const elapsedSec = Math.round((Date.now() - startedAt) / 1000);
+                process.stderr.write(`  still ${job.status} (${elapsedSec}s elapsed)…\n`);
+                lastHeartbeatAt = Date.now();
             }
         }
         if (GENERATION_TERMINAL_STATUSES.has(job.status))

package/dist/lib/skill-content.js

@@ -220,6 +220,10 @@ When in doubt: side-by-side comparison usually beats in-place edits. Ids are che
 - **401 surfaces as fake blocker**: an unauthenticated endpoint produces "participant got stuck on auth screen" — looks like a UX blocker but is config. Always confirm endpoint auth before reading transcripts as user-research data.
 - **No per-page/per-timestamp scoping for media**: there's no "evaluate just slide 14" or "react to seconds 0-30" API. State the focus explicitly in the \`assignment\` text, or pre-stitch the artifact (e.g. replace one slide locally, upload as a new iteration).
 - **\`study get --json\` participants live at the top level**, not nested under \`iterations[*].participants\`. The backend split made \`/studies/{id}\` lite (metadata + iteration shells, no participant graph) and added \`/studies/{id}/participants\`; the CLI joins them so \`study get --json\` carries a flat \`participants[]\` with \`iteration_id\` on each row. Read \`.participants[]\`, not \`.iterations[].participants[]\`.
+- **All destructive deletes require \`--yes\` in non-TTY mode**: \`ish workspace delete\`, \`study delete\`, \`ask delete\`, \`person delete\`, \`source delete\`, \`chat endpoint delete\`. In \`--json\` mode (or any piped/non-TTY invocation), omitting \`--yes\` refuses with \`error_kind: "ConfirmationRequired"\` + an \`example\` field showing the same command with \`--yes\` appended. \`workspace delete\` is the highest-blast-radius: it removes ALL nested studies, asks, people, secrets, configs, sources, and chat endpoints — the prompt names them explicitly.
+- **\`ish login\` is idempotent**: with a valid saved token, \`ish login\` short-circuits with "Already logged in" and **does not open a new browser tab**. Use \`--force\` (or \`-f\`) only when actually switching accounts.
+- **\`ish person create\` accepts inline flags** (mirrors \`person update\`): the file-only API (\`--file <path>\`) is preserved as an escape hatch but the common path is \`ish person create --name "X" --type ai --country US ...\` — \`--type\` defaults to \`ai\` when \`--file\` is omitted. See \`ish person create --help\` for the full inline-flag set including \`--household\` (MECE rule applies) and \`--accessibility-profile\`.
+- **\`ish status\` now surfaces \`chat_endpoint\`** alongside \`workspace\`/\`study\`/\`ask\`. Stale or orphan active refs get a \`warning\` + \`hint\` field on the affected ref (instead of silently dropping the \`name\`). On \`workspace use <other>\`, the CLI cascade-clears \`study\`/\`ask\`/\`chat_endpoint\` (they belong to the previous workspace).
 
 ## When in doubt
 
@@ -376,9 +380,13 @@ ish person suggest-scenarios \\
 #    [{"text":"...","source":"situation","scenario_prompt":"..."}, ...]
 #    Valid source values: situation, voice, binary, micro-story
 
-# 3. Save the person shell
+# 3. Save the person shell — either from file:
 ish person create --file ./persona.json
 # → p-d4e
+#
+# …or inline (mirror of person update):
+# ish person create --name "Alice" --type ai --country US \\
+#     --occupation founder --household single --bio "..."
 
 # 4. Persist the answers as structured evidence
 ish person evidence add p-d4e --traces-file ./answers.json
@@ -909,6 +917,70 @@ Rules to remember:
 See \`ish docs get-page concepts/extending-a-simulation\` for the full
 mental model (cancel + extend as a pair, error envelopes, cost model).
 
+## 12. Slice study results by frame / segment / turn / sentiment
+
+Goal: ask narrower questions of a finished run than the kitchen-sink
+\`ish study results\` envelope answers. The canonical use case:
+**"what differed on the login screen across these five iterations?"**.
+
+\`\`\`bash
+# 12a. Across-iterations comparison on one frame (the canonical question).
+#      --frame matches frame names by case-insensitive substring; pass
+#      a full Frame UUID or an f-… alias when the name is ambiguous.
+ish study results s-b2c --frame login --group-by iteration --json
+
+# 12b. Frustrated reactions to one segment of a video study:
+ish study results s-b2c --segment 3 --sentiment Frustrated
+
+# 12c. Who failed the "verify email" step, and why?
+#      --group-by step exposes per-participant verdicts inline so you
+#      don't fan out across participants.
+ish study results s-b2c --assignment "Sign up" --step verify-email \\
+    --group-by step --json
+
+# 12d. Pair-mode chat: only side A turn 4.
+ish study results s-b2c --side a --turn 4
+
+# 12e. Sanity-check coverage when a filter narrows the slice:
+ish study results s-b2c --frame checkout --json \\
+    | jq '{matched: .participant_count, total: .totals_unfiltered.participant_count}'
+
+# 12f. A filter that matches zero interactions still returns the stable
+#      envelope shape — participant_count: 0, totals_unfiltered populated,
+#      exit code 0 (not 4). Never error on no-match.
+ish study results s-b2c --frame doesnotexist --json
+# → ValidationError because "doesnotexist" matches no frame names; pass
+#   --include-unmatched only when --frame DID resolve and you want the
+#   degraded captures (frame_version_id: null) back.
+\`\`\`
+
+Rules to remember:
+- **Filters compose with AND across flags; OR within \`--sentiment\`.**
+  \`--frame login --sentiment Frustrated,Confused\` keeps only login-frame
+  interactions whose sentiment is Frustrated OR Confused.
+- **Modality mismatch is not an error.** \`--segment 0\` on an
+  interactive study emits a stderr warning and is ignored. The
+  exception is **\`--group-by\`** — \`--group-by frame\` on a chat study,
+  \`--group-by turn\` on a video study, etc. error at the router (exit 2).
+- **Empty-slice contract: exit 0, not 4.** Zero matches return a
+  stable envelope with \`participant_count: 0\` and
+  \`totals_unfiltered\` populated. Agents key on
+  \`totals_unfiltered.participant_count\` to ask "is the filter too
+  tight, or did the run not produce data?".
+- \`--frame\` accepts a name substring, a Frame UUID, an \`f-…\` alias,
+  or a \`frame_version_id\` UUID. Ambiguous substring (matches >1
+  frame) errors with the candidate list.
+- \`--summary\` is orthogonal to filters and narrows the summary over
+  the filtered set. \`--transcript\` is single-participant and errors
+  (exit 2) when **any** filter or \`--group-by\` is set.
+- Per-step output exposes \`participant_verdicts: [{participant_alias,
+  verdict, reason, evidence_interaction_ids}]\` — not
+  \`per_participant_verdicts\`. The verdict enum is \`passed\` /
+  \`inconclusive\` / \`failed\`.
+
+See \`ish docs get-page guides/slicing-results\` for the full filter
+table, projection shapes, and the defensive null-handling rules.
+
 ## Tips for chaining commands as an agent
 
 - Capture aliases from JSON: \`ITER=$(ish iteration create --url … --json | jq -r .alias)\`
@@ -1002,6 +1074,10 @@ mental model (cancel + extend as a pair, error envelopes, cost model).
 | List of participants from \`study run\`        | \`--json \\| jq '.participants[].id'\`        | \`--get participant_aliases\` (or \`participant_ids\` for UUIDs)                |
 | Per-answer sentiment                      | \`--json \\| jq '...'\` per participant       | \`ish study results <id> --json\` (sentiment is on every answer row) |
 | "Did this run land?" headline             | \`study results --json\` + jq filtering | \`ish study results <id> --summary --json\`                          |
+| Across-iterations comparison on one frame | \`study results --json\` + jq per iteration | \`ish study results <id> --frame login --group-by iteration --json\` |
+| Per-step pass/fail with reasons inline    | \`study participant --json\` per participant + jq | \`ish study results <id> --step verify-email --group-by step --json\` |
+| Frustrated reactions to one media segment | \`study results --json\` + jq | \`ish study results <id> --segment 3 --sentiment Frustrated --json\` |
+| Sanity-check filter coverage              | hand-count \`.participants\` vs total | \`--get totals_unfiltered.participant_count\` (set on every sliced envelope) |
 | Chat transcript for one participant (external_chatbot) | \`study participant --json\` + jq      | \`ish study results <id> --transcript <participant_id> --json\`           |
 | Pair-mode conversation transcripts        | \`study participant --json\` per participant       | \`ish iteration get <iter-id> --json \\| jq '.conversations[]'\`     |
 | Participant headline only (no action timeline) | \`study participant --json\` + jq            | \`ish study participant <id> --summary --json\`                           |
@@ -1042,7 +1118,7 @@ ish <command> --help
 | \`mcp\`       | Wire the hosted ish MCP server into local AI    | guides/mcp-add              |
 |             | clients (Cursor, VS Code, Claude Code,          |                             |
 |             | Claude Desktop, Windsurf). Idempotent.          |                             |
-| \`login\`     | Browser-based auth                              | —                           |
+| \`login\`     | Browser-based auth. Idempotent: short-circuits on valid saved token. \`--force\` to switch accounts. | —                           |
 | \`logout\`    | Clear saved credentials                         | —                           |
 | \`status\`    | Show active session (user, workspace,           | concepts/active-context     |
 |             | study, ask, token validity) — alias \`whoami\`    |                             |

package/dist/lib/study-participants.d.ts

@@ -6,6 +6,19 @@
  * (person, interactions[], participant_summary, interview_answers, …) that
  * used to be embedded under `study.iterations[*].participants[*]` on the
  * legacy `GET /studies/{id}` response.
+ *
+ * Audit (study-results-slice plan, T4): the flat endpoint already returns
+ * everything the new `ish study results --frame/--segment/--step/...` filter
+ * pipeline needs in a single round-trip — no per-participant fan-out:
+ *   - `interactions[]` (modality-discriminated via `ParticipantWithAttributesPublicResponse`)
+ *   - `participant_assignments[].step_results[]` with `{step_id, name,
+ *     description, verdict, reason, evidence_interaction_ids[]}`, hydrated
+ *     by `attach_participant_step_results_flat` in the study repository
+ *     before serialisation (`ish-backend/app/api/study/repository.py:315`)
+ *   - `participant_summary`, `interview_answers`
+ * If a future filter ever needs `conversation_id` on each interaction (for
+ * `--group-by conversation`), that's a backend-side addition on
+ * `_InteractionResponseBase`, not a CLI change.
  */
 import type { ApiClient } from "./api-client.js";
 import type { Participant } from "./types.js";