@ishlabs/cli 0.18.0 → 0.20.0

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 || "-"),
@@ -807,10 +851,10 @@ export function formatStudyList(studies, json) {
  *
  * Returns null when status is consistent; no warning emitted.
  */
-function detectStudyStatusInconsistency(study) {
+function detectStudyStatusInconsistency(study, participants) {
     if (study.status !== "failed")
         return null;
-    const allParticipants = collectParticipants(study);
+    const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
     const completedCount = allParticipants.filter((t) => t.status === "completed" || t.status === "complete").length;
     const totalInteractions = allParticipants.reduce((sum, t) => sum + t.interactionCount, 0);
     if (completedCount === 0 && totalInteractions === 0)
@@ -879,14 +923,16 @@ function renderAssignmentSteps(a) {
         }
     }
 }
-export function formatStudyDetail(study, json, options = {}) {
-    const inconsistency = detectStudyStatusInconsistency(study);
+export function formatStudyDetail(study, json, options = {}, participants) {
+    const inconsistency = detectStudyStatusInconsistency(study, participants);
     if (inconsistency)
         emitStatusInconsistencyWarning(inconsistency);
     if (json) {
-        const payload = inconsistency
-            ? { ...study, status_inferred: inconsistency.inferred }
-            : study;
+        const payload = { ...study };
+        if (participants !== undefined)
+            payload.participants = participants;
+        if (inconsistency)
+            payload.status_inferred = inconsistency.inferred;
         console.log(jsonOutput(payload, options));
         return;
     }
@@ -929,10 +975,10 @@ export function formatStudyDetail(study, json, options = {}) {
         }
     }
     // Participants summary
-    const allParticipants = collectParticipants(study);
+    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,
@@ -946,8 +992,8 @@ export function formatStudyDetail(study, json, options = {}) {
  * 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) {
-    const allParticipants = collectParticipants(study);
+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))
         : null;
@@ -995,7 +1041,7 @@ function buildStudyResultsEnvelope(study) {
     // CLI-side sanity check (Pattern E / Issue #2). Surface a status_inferred
     // field when the backend reports failed-with-data; agents can branch on
     // either the original status or status_inferred.
-    const inconsistency = detectStudyStatusInconsistency(study);
+    const inconsistency = detectStudyStatusInconsistency(study, participants);
     // Pattern B2 (cli half): per-participant rows expose status + error_message so
     // agents can act on a failed run without re-fetching every participant.
     const failedCount = allParticipants.filter((t) => t.status.toLowerCase() === "failed").length;
@@ -1025,18 +1071,18 @@ function buildStudyResultsEnvelope(study) {
         participants: participantRows,
     };
 }
-export function formatStudyResults(study, json) {
-    const inconsistency = detectStudyStatusInconsistency(study);
+export function formatStudyResults(study, participants, json) {
+    const inconsistency = detectStudyStatusInconsistency(study, participants);
     if (inconsistency)
         emitStatusInconsistencyWarning(inconsistency);
     if (json) {
         // preProjected: bypass leanJson so the stable envelope keeps documented
         // empty defaults (sentiment: null, interview_answers[].answers: []) rather
         // than having them stripped by the lean transform.
-        console.log(jsonOutput(buildStudyResultsEnvelope(study), { preProjected: true }));
+        console.log(jsonOutput(buildStudyResultsEnvelope(study, participants), { preProjected: true }));
         return;
     }
-    const allParticipants = collectParticipants(study);
+    const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
     const totalInteractions = allParticipants.reduce((sum, t) => sum + t.interactionCount, 0);
     // Header
     console.log(`${study.name || "Untitled"} — Results`);
@@ -1072,7 +1118,7 @@ export function formatStudyResults(study, 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,
@@ -1102,8 +1148,8 @@ export function formatStudyResults(study, json) {
  * per-participant {alias, status, sentiment, comment} row. Useful for agents that
  * need to branch on outcome without paying for the full envelope.
  */
-export function buildStudyResultsSummary(study) {
-    const allParticipants = collectParticipants(study);
+export function buildStudyResultsSummary(study, participants) {
+    const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
     const studyAlias = study.id
         ? deterministicAlias(ALIAS_PREFIX.study, String(study.id))
         : null;
@@ -1118,7 +1164,7 @@ export function buildStudyResultsSummary(study) {
         }
     }
     const sentiment = sentimentTotal > 0 ? { counts: sentimentCounts, total: sentimentTotal } : null;
-    const participants = allParticipants.map((t) => ({
+    const participantRows = allParticipants.map((t) => ({
         alias: t.alias || null,
         name: t.name,
         status: t.status,
@@ -1136,7 +1182,7 @@ export function buildStudyResultsSummary(study) {
         completed_count: completedCount,
         failed_count: failedCount,
         sentiment,
-        participants,
+        participants: participantRows,
     };
 }
 /**
@@ -1300,49 +1346,52 @@ export function buildParticipantSummary(participant) {
         out.error_kind = String(participant.error_kind);
     return out;
 }
-function collectParticipants(study) {
-    const iterations = Array.isArray(study.iterations) ? study.iterations : [];
-    const participants = [];
-    for (const iter of iterations) {
-        const it = iter;
-        const iterLabel = String(it.label || it.name || "-");
-        const iterParticipants = Array.isArray(it.participants) ? it.participants : [];
-        for (const participant of iterParticipants) {
-            const t = participant;
-            const profile = t.person;
-            const interactions = Array.isArray(t.interactions) ? t.interactions : [];
-            const sentimentCounts = {};
-            for (const interaction of interactions) {
-                const ix = interaction;
-                const sentiment = ix.sentiment;
-                if (sentiment?.label) {
-                    const label = String(sentiment.label);
-                    sentimentCounts[label] = (sentimentCounts[label] || 0) + 1;
-                }
+function collectParticipants(participants, iterations) {
+    const iterationLabels = new Map();
+    for (const iter of iterations ?? []) {
+        const id = iter.id ? String(iter.id) : "";
+        if (id) {
+            iterationLabels.set(id, String(iter.label || iter.name || "-"));
+        }
+    }
+    const rows = [];
+    for (const participant of participants ?? []) {
+        const t = participant;
+        const profile = t.person;
+        const interactions = Array.isArray(t.interactions) ? t.interactions : [];
+        const sentimentCounts = {};
+        for (const interaction of interactions) {
+            const ix = interaction;
+            const sentiment = ix.sentiment;
+            if (sentiment?.label) {
+                const label = String(sentiment.label);
+                sentimentCounts[label] = (sentimentCounts[label] || 0) + 1;
             }
-            const answers = Array.isArray(t.interview_answers) ? t.interview_answers : [];
-            const summary = t.participant_summary;
-            const summarySentimentObj = summary?.sentiment;
-            const id = String(t.id || "");
-            participants.push({
-                id,
-                name: String(profile?.name || t.instance_name || "Unknown"),
-                alias: id ? deterministicAlias(ALIAS_PREFIX.participant, id) : "",
-                iterationLabel: iterLabel,
-                status: String(t.status || "-"),
-                errorMessage: t.error_message ? String(t.error_message) : null,
-                interactionCount: interactions.length,
-                sentimentCounts,
-                summarySentiment: summarySentimentObj?.label ? String(summarySentimentObj.label) : null,
-                summaryComment: summary?.comment ? String(summary.comment) : null,
-                interviewAnswers: answers.map((a) => ({
-                    questionId: String(a.question_id || ""),
-                    answer: a.answer,
-                })),
-            });
         }
+        const answers = Array.isArray(t.interview_answers) ? t.interview_answers : [];
+        const summary = t.participant_summary;
+        const summarySentimentObj = summary?.sentiment;
+        const id = String(t.id || "");
+        const iterationId = t.iteration_id ? String(t.iteration_id) : "";
+        const iterationLabel = (iterationId && iterationLabels.get(iterationId)) || "-";
+        rows.push({
+            id,
+            name: String(profile?.name || t.instance_name || "Unknown"),
+            alias: id ? deterministicAlias(ALIAS_PREFIX.participant, id) : "",
+            iterationLabel,
+            status: String(t.status || "-"),
+            errorMessage: t.error_message ? String(t.error_message) : null,
+            interactionCount: interactions.length,
+            sentimentCounts,
+            summarySentiment: summarySentimentObj?.label ? String(summarySentimentObj.label) : null,
+            summaryComment: summary?.comment ? String(summary.comment) : null,
+            interviewAnswers: answers.map((a) => ({
+                questionId: String(a.question_id || ""),
+                answer: a.answer,
+            })),
+        });
     }
-    return participants;
+    return rows;
 }
 function formatQuestionType(q) {
     if (!q.type)
@@ -1370,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 || ""),
@@ -1444,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 || "-"),
@@ -1499,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 || "-"),
@@ -1524,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,
@@ -1569,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 || "-"),
@@ -1670,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`);
     }
@@ -2140,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"),

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

@@ -219,6 +219,11 @@ When in doubt: side-by-side comparison usually beats in-place edits. Ids are che
 - **Chatbot auth drift**: tokens/sessions baked into \`--from-curl\` expire. If transcripts come back as identical short error strings, re-run \`chat_endpoint_test\` and refresh the curl spec.
 - **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
 
@@ -375,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
@@ -1041,7 +1050,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

@@ -0,0 +1,32 @@
+/**
+ * Wrapper for the post-split `GET /studies/{id}/participants` endpoint.
+ *
+ * Returns a flat list of participants for one study with an `iteration_id`
+ * discriminator on each row. Each row carries the rich per-participant graph
+ * (person, interactions[], participant_summary, interview_answers, …) that
+ * used to be embedded under `study.iterations[*].participants[*]` on the
+ * legacy `GET /studies/{id}` response.
+ */
+import type { ApiClient } from "./api-client.js";
+import type { Participant } from "./types.js";
+export interface StudyParticipant extends Participant {
+    person?: {
+        id?: string;
+        name?: string;
+    };
+    interactions?: unknown[];
+    participant_summary?: Record<string, unknown> | null;
+    interview_answers?: Array<{
+        question_id?: string;
+        answer?: unknown;
+    }>;
+    participant_files?: unknown[];
+    participant_assignments?: unknown[];
+    conversation_id?: string | null;
+    error_message?: string | null;
+    error_kind?: string | null;
+    [k: string]: unknown;
+}
+export declare function fetchStudyParticipants(client: ApiClient, studyId: string, opts?: {
+    timeout?: number;
+}): Promise<StudyParticipant[]>;

package/dist/lib/study-participants.js

@@ -0,0 +1,12 @@
+/**
+ * Wrapper for the post-split `GET /studies/{id}/participants` endpoint.
+ *
+ * Returns a flat list of participants for one study with an `iteration_id`
+ * discriminator on each row. Each row carries the rich per-participant graph
+ * (person, interactions[], participant_summary, interview_answers, …) that
+ * used to be embedded under `study.iterations[*].participants[*]` on the
+ * legacy `GET /studies/{id}` response.
+ */
+export async function fetchStudyParticipants(client, studyId, opts) {
+    return await client.get(`/studies/${studyId}/participants`, undefined, opts);
+}

package/dist/lib/types.d.ts

@@ -155,7 +155,6 @@ export interface Iteration {
     description?: string;
     label?: string;
     details?: Record<string, unknown>;
-    participants?: Participant[];
     created_at: string;
     updated_at: string;
 }

package/dist/upgrade.js

@@ -32,11 +32,18 @@ export async function upgrade(currentVersion, targetVersion) {
     const scriptUrl = import.meta.url;
     const runningFromNodeModules = scriptUrl.includes("/node_modules/");
     if (looksLikeNode || runningFromNodeModules) {
-        throw new Error("Cannot self-upgrade an npm-installed CLI (would overwrite the node binary). " +
+        // Pattern C: tag as ValidationError so exitCodeFromError maps to 2
+        // (usage_error). Otherwise this would fall through to the generic
+        // exit 1 even with the wrapper in place (ISSUE-012).
+        const err = new Error("Cannot self-upgrade an npm-installed CLI (would overwrite the node binary). " +
             "Run `npm install -g @ishlabs/cli@latest` instead.");
+        err.name = "ValidationError";
+        throw err;
     }
     if (targetVersion && !/^\d+\.\d+\.\d+/.test(targetVersion)) {
-        throw new Error(`Invalid version format: ${targetVersion}`);
+        const err = new Error(`Invalid version format: ${targetVersion}`);
+        err.name = "ValidationError";
+        throw err;
     }
     const latest = targetVersion || (await getLatestVersion());
     if (latest === currentVersion) {

package/package.json

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