@ishlabs/cli 0.17.7 → 0.19.0

package/dist/commands/study.js

@@ -8,13 +8,14 @@ import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
 import { formatStudyList, formatStudyDetail, formatStudyResults, buildStudyResultsSummary, buildChatTranscript, output, ValidationError, } from "../lib/output.js";
 import { VALID_CONTENT_TYPES } from "../lib/types.js";
-import { parseAssignment, loadAssignmentsFile, parseQuestion } from "../lib/study-inputs.js";
+import { fetchStudyParticipants } from "../lib/study-participants.js";
+import { parseAssignment, loadAssignmentsFile, validateAssignmentsArray, parseQuestion } from "../lib/study-inputs.js";
 import { loadQuestionsManifest } from "../lib/ask-questions.js";
 import { isLocalPath } from "../lib/upload.js";
 import { normalizeChatMode, validateRoleCriteria } from "../lib/modality.js";
 import { normalizeEnumValue, SCREEN_FORMATS } from "../lib/enums.js";
 import { attachStudyRunCommands } from "./study-run.js";
-import { attachStudyTesterCommands } from "./study-tester.js";
+import { attachStudyParticipantCommands } from "./study-participant.js";
 import { attachStudyAnalyzeCommands } from "./study-analyze.js";
 import { attachStudyScreenshotsCommands } from "./study-screenshots.js";
 function collectRepeatable(value, prev = []) {
@@ -51,12 +52,14 @@ function resolveAssignments(opts) {
         return loadAssignmentsFile(opts.assignmentsFile);
     }
     if (opts.assignments) {
+        let parsed;
         try {
-            return JSON.parse(opts.assignments);
+            parsed = JSON.parse(opts.assignments);
         }
         catch {
             throw new Error("Invalid --assignments JSON");
         }
+        return validateAssignmentsArray(parsed, "--assignments");
     }
     return undefined;
 }
@@ -120,19 +123,19 @@ Concept pages: ish docs get-page concepts/study
         .option("--title <title>", "Content title (text + media modalities — image, video, audio, document; optional). Not used for interactive / chat.")
         .option("--endpoint <id>", "Saved chatbot endpoint id or alias. Creates iteration A inline (chat modality, external_chatbot mode)")
         .option("--endpoint-config <file>", "ChatbotEndpointConfig JSON file (or `-` for stdin); embedded directly. Mutually exclusive with --endpoint (chat modality, external_chatbot mode)")
-        .option("--max-turns <n>", "Maximum conversation turns per tester (chat modality only; default 12)", (v) => Number(v))
-        .option("--chat-mode <mode>", "Chat mode: external_chatbot (default) or tester_pair (two AI audiences talk to each other) — chat modality only")
-        .option("--audience-a <ids>", "Tester profile IDs/aliases for audience A (comma-separated or repeatable). Pass a single profile and N on --audience-b to broadcast (1×N rehearsal: fix side A, vary side B) — chat tester_pair mode", (value, prev = []) => prev.concat(value.split(",").map((s) => s.trim()).filter(Boolean)), [])
-        .option("--audience-b <ids>", "Tester profile IDs/aliases for audience B. When both sides are explicit they must be equal length, BUT if either side is a singleton it's auto-broadcast to match the other (1×N rehearsal) — chat tester_pair mode", (value, prev = []) => prev.concat(value.split(",").map((s) => s.trim()).filter(Boolean)), [])
-        .option("--scenario-a <text-or-@file>", "Side-A scenario + goal — chat tester_pair mode")
-        .option("--scenario-b <text-or-@file>", "Side-B scenario + goal — chat tester_pair mode")
-        .option("--initiator-side <a|b>", "Which side speaks first (default: a) — chat tester_pair mode")
-        .option("--role-criteria-a <json-or-@file>", 'RoleCriteria filter for side A (JSON object or @filepath). Keys: occupation[], min_age, max_age, gender[], country[], education_level_in[], household_in[], locale_type_in[], income_level_in[], employment_status_in[], requires_captions, uses_screen_reader, prefers_reduced_motion, prefers_high_contrast, has_any_accessibility_need. The five *_in arrays accept snake_case spec values; the five accessibility filters are booleans. Use INSTEAD of --audience-a or alongside it. chat tester_pair mode.')
-        .option("--role-criteria-b <json-or-@file>", "RoleCriteria filter for side B — same shape as --role-criteria-a. chat tester_pair mode.")
+        .option("--max-turns <n>", "Maximum conversation turns per participant (chat modality only; default 12)", (v) => Number(v))
+        .option("--chat-mode <mode>", "Chat mode: external_chatbot (default) or participant_pair (two AI groups talk to each other) — chat modality only")
+        .option("--group-a <ids>", "Person IDs/aliases for group A (comma-separated or repeatable). Pass a single profile and N on --group-b to broadcast (1×N rehearsal: fix side A, vary side B) — chat participant_pair mode", (value, prev = []) => prev.concat(value.split(",").map((s) => s.trim()).filter(Boolean)), [])
+        .option("--group-b <ids>", "Person IDs/aliases for group B. When both sides are explicit they must be equal length, BUT if either side is a singleton it's auto-broadcast to match the other (1×N rehearsal) — chat participant_pair mode", (value, prev = []) => prev.concat(value.split(",").map((s) => s.trim()).filter(Boolean)), [])
+        .option("--scenario-a <text-or-@file>", "Side-A scenario + goal — chat participant_pair mode")
+        .option("--scenario-b <text-or-@file>", "Side-B scenario + goal — chat participant_pair mode")
+        .option("--initiator-side <a|b>", "Which side speaks first (default: a) — chat participant_pair mode")
+        .option("--role-criteria-a <json-or-@file>", 'RoleCriteria filter for side A (JSON object or @filepath). Keys: occupation[], min_age, max_age, gender[], country[], education_level_in[], household_in[], locale_type_in[], income_level_in[], employment_status_in[], requires_captions, uses_screen_reader, prefers_reduced_motion, prefers_high_contrast, has_any_accessibility_need. The five *_in arrays accept snake_case spec values; the five accessibility filters are booleans. Use INSTEAD of --group-a or alongside it. chat participant_pair mode.')
+        .option("--role-criteria-b <json-or-@file>", "RoleCriteria filter for side B — same shape as --role-criteria-a. chat participant_pair mode.")
         .addHelpText("after", `
 Note: --workspace is optional if set via \`ish workspace use <alias>\`.
 
-The questionnaire is the set of questions testers answer. Use \`--question\` to
+The questionnaire is the set of questions participants answer. Use \`--question\` to
 quickly add simple text questions, or \`--questionnaire <file.json>\` for richer
 types (slider, likert, single-choice, multiple-choice, number) and custom
 timing. The two forms are mutually exclusive — pick one.
@@ -187,6 +190,23 @@ Examples:
   $ ish study create --name "Newsletter" --modality text --content-type email \\
       --assignments-file ./assignments.json
 
+  # Interactive study whose assignment carries a step-by-step checklist
+  # (JSON only — the inline --assignment shorthand can't express steps).
+  # Steps are honored for interactive + external_chatbot chat modalities only;
+  # the backend rejects them for media (text/video/audio/image/document) and
+  # for chat participant_pair. After a run, study get reports per-step completion.
+  $ ish study create --name "Checkout" --modality interactive \\
+      --assignments-file ./assignments.json
+  #   assignments.json:
+  #   [
+  #     { "name": "Buy", "instructions": "Add to cart and check out",
+  #       "steps": [
+  #         { "name": "Find a product", "description": "Browse to any item" },
+  #         { "name": "Add to cart" },
+  #         { "name": "Complete checkout" }
+  #       ] }
+  #   ]
+
   # Chat study targeting a saved chatbot endpoint:
   $ ish study create --name "Onboarding bot" --modality chat \\
       --endpoint ep-abc \\
@@ -213,7 +233,7 @@ Tips:
   \`--fields a,b,c\` to project the JSON output to listed fields.
 
 Next: configure a run with \`ish iteration create --study <id>\`,
-      then dispatch with \`ish study run\` (audience size is set on run, not create).`)
+      then dispatch with \`ish study run\` (people are selected on run, not create).`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const assignments = resolveAssignments(opts);
@@ -246,23 +266,23 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             // against the freshly-created study.
             const normalizedChatMode = normalizeChatMode(opts.chatMode);
             if (opts.chatMode !== undefined && normalizedChatMode === null) {
-                throw new ValidationError(`Invalid --chat-mode "${opts.chatMode}". Expected "external_chatbot" or "tester_pair" (hyphenated variants accepted).`, ["external_chatbot", "tester_pair"]);
+                throw new ValidationError(`Invalid --chat-mode "${opts.chatMode}". Expected "external_chatbot" or "participant_pair" (hyphenated variants accepted).`, ["external_chatbot", "participant_pair"]);
             }
-            const pairFlagsSet = (opts.audienceA && opts.audienceA.length > 0)
-                || (opts.audienceB && opts.audienceB.length > 0)
+            const pairFlagsSet = (opts.groupA && opts.groupA.length > 0)
+                || (opts.groupB && opts.groupB.length > 0)
                 || opts.scenarioA !== undefined
                 || opts.scenarioB !== undefined
                 || opts.initiatorSide !== undefined
                 || opts.roleCriteriaA !== undefined
                 || opts.roleCriteriaB !== undefined
-                || normalizedChatMode === "tester_pair";
+                || normalizedChatMode === "participant_pair";
             const inlineMediaFlagsSet = [
                 opts.contentText !== undefined ? "--content-text" : null,
                 opts.url !== undefined ? "--url" : null,
                 opts.contentUrl !== undefined ? "--content-url" : null,
                 opts.imageUrls !== undefined ? "--image-urls" : null,
                 (opts.endpoint !== undefined || opts.endpointConfig !== undefined) ? "--endpoint/--endpoint-config" : null,
-                pairFlagsSet ? "--chat-mode tester_pair (with --audience-a/-b or --role-criteria-a/-b plus --scenario-a/-b)" : null,
+                pairFlagsSet ? "--chat-mode participant_pair (with --group-a/-b or --role-criteria-a/-b plus --scenario-a/-b)" : null,
             ].filter((f) => f !== null);
             if (inlineMediaFlagsSet.length > 1) {
                 throw new ValidationError(`Pass only one inline-iteration flag: ${inlineMediaFlagsSet.join(", ")}.`, inlineMediaFlagsSet);
@@ -367,7 +387,7 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                     throw new ValidationError(`--endpoint / --endpoint-config require --modality chat (got "${opts.modality}").`, ["chat"]);
                 }
                 if (normalizedChatMode && normalizedChatMode !== "external_chatbot") {
-                    throw new ValidationError(`--endpoint / --endpoint-config are only valid with --chat-mode external_chatbot (got "${opts.chatMode}"). For tester_pair use --audience-a/-b and --scenario-a/-b.`, ["external_chatbot"]);
+                    throw new ValidationError(`--endpoint / --endpoint-config are only valid with --chat-mode external_chatbot (got "${opts.chatMode}"). For participant_pair use --group-a/-b and --scenario-a/-b.`, ["external_chatbot"]);
                 }
                 let endpointConfig;
                 if (opts.endpoint !== undefined) {
@@ -389,7 +409,7 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                         throw new Error("Invalid --endpoint-config JSON.");
                     }
                 }
-                const maxTurns = opts.maxTurns ?? 12;
+                const maxTurns = opts.maxTurns ?? 14;
                 inlineIteration = {
                     name: "A",
                     details: {
@@ -406,13 +426,13 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             }
             else if (pairFlagsSet) {
                 if (opts.modality && opts.modality !== "chat") {
-                    throw new ValidationError(`--chat-mode tester_pair (with --audience-a/-b or --role-criteria-a/-b plus --scenario-a/-b) requires --modality chat (got "${opts.modality}").`, ["chat"]);
+                    throw new ValidationError(`--chat-mode participant_pair (with --group-a/-b or --role-criteria-a/-b plus --scenario-a/-b) requires --modality chat (got "${opts.modality}").`, ["chat"]);
                 }
-                if (normalizedChatMode && normalizedChatMode !== "tester_pair") {
-                    throw new ValidationError(`--audience-a/-b or --role-criteria-a/-b imply --chat-mode tester_pair (got "${opts.chatMode}").`, ["tester_pair"]);
+                if (normalizedChatMode && normalizedChatMode !== "participant_pair") {
+                    throw new ValidationError(`--group-a/-b or --role-criteria-a/-b imply --chat-mode participant_pair (got "${opts.chatMode}").`, ["participant_pair"]);
                 }
-                const audA = (opts.audienceA ?? []).map(resolveId);
-                const audB = (opts.audienceB ?? []).map(resolveId);
+                const audA = (opts.groupA ?? []).map(resolveId);
+                const audB = (opts.groupB ?? []).map(resolveId);
                 // Parse + validate role criteria if supplied (JSON or @filepath).
                 const parseCriteria = (raw, flag) => {
                     if (raw === undefined)
@@ -445,21 +465,21 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 const sideAHasInput = audA.length > 0 || !!critA;
                 const sideBHasInput = audB.length > 0 || !!critB;
                 if (!sideAHasInput || !sideBHasInput) {
-                    throw new Error("tester_pair chat iterations require, for each side, either an explicit audience (--audience-a / --audience-b) or a role-criteria filter (--role-criteria-a / --role-criteria-b).");
+                    throw new Error("participant_pair chat iterations require, for each side, either explicit people (--group-a / --group-b) or a role-criteria filter (--role-criteria-a / --role-criteria-b).");
                 }
                 // 1×N broadcast: canonical "rehearse one side against N
                 // variations" shape. See iteration.ts buildIterationDetails
-                // tester_pair arm for the rationale.
+                // participant_pair arm for the rationale.
                 let audA_final = audA;
                 let audB_final = audB;
                 let broadcastMsg;
                 if (audA.length === 1 && audB.length > 1 && !critA && !critB) {
                     audA_final = Array(audB.length).fill(audA[0]);
-                    broadcastMsg = `Broadcasting --audience-a (1 profile) to length ${audB.length} to match --audience-b — same side-A profile across all ${audB.length} conversations.`;
+                    broadcastMsg = `Broadcasting --group-a (1 profile) to length ${audB.length} to match --group-b — same side-A profile across all ${audB.length} conversations.`;
                 }
                 else if (audB.length === 1 && audA.length > 1 && !critA && !critB) {
                     audB_final = Array(audA.length).fill(audB[0]);
-                    broadcastMsg = `Broadcasting --audience-b (1 profile) to length ${audA.length} to match --audience-a — same side-B profile across all ${audA.length} conversations.`;
+                    broadcastMsg = `Broadcasting --group-b (1 profile) to length ${audA.length} to match --group-a — same side-B profile across all ${audA.length} conversations.`;
                 }
                 if (broadcastMsg) {
                     console.error(broadcastMsg);
@@ -469,13 +489,13 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                     // CLI's 1×N broadcast (above) already cloned the singleton side,
                     // so this branch only fires when both sides ship >1 with
                     // mismatched counts. Server rejects the same way.
-                    throw new ValidationError(`--audience-a (${audA_final.length}) and --audience-b (${audB_final.length}) cannot be paired. ` +
+                    throw new ValidationError(`--group-a (${audA_final.length}) and --group-b (${audB_final.length}) cannot be paired. ` +
                         `Pick the same number on each side (1:1 by index), or pass exactly one profile on one side to broadcast ` +
-                        `(e.g. --audience-a tp-rep --audience-b tp-cto1,tp-cto2,tp-cto3), ` +
-                        `or use --role-criteria-a/-b on either side to let the backend resolve the pool.`, ["--audience-a", "--audience-b"]);
+                        `(e.g. --group-a p-rep --group-b p-cto1,p-cto2,p-cto3), ` +
+                        `or use --role-criteria-a/-b on either side to let the backend resolve the pool.`, ["--group-a", "--group-b"]);
                 }
                 if (!opts.scenarioA || !opts.scenarioB) {
-                    throw new Error("tester_pair chat iterations require --scenario-a <text-or-@file> and --scenario-b <text-or-@file>.");
+                    throw new Error("participant_pair chat iterations require --scenario-a <text-or-@file> and --scenario-b <text-or-@file>.");
                 }
                 const scenarioA = opts.scenarioA.startsWith("@")
                     ? readFileSync(opts.scenarioA.slice(1), "utf8")
@@ -490,15 +510,15 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 if (initiator !== "a" && initiator !== "b") {
                     throw new ValidationError(`Invalid --initiator-side "${opts.initiatorSide}". Expected "a" or "b".`, ["a", "b"]);
                 }
-                const maxTurns = opts.maxTurns ?? 12;
+                const maxTurns = opts.maxTurns ?? 14;
                 inlineIteration = {
                     name: "A",
                     details: {
                         type: "chat",
                         mode_details: {
-                            mode: "tester_pair",
-                            audience_a: audA_final,
-                            audience_b: audB_final,
+                            mode: "participant_pair",
+                            group_a: audA_final,
+                            group_b: audB_final,
                             scenario_a: scenarioA,
                             scenario_b: scenarioB,
                             initiator_side: initiator,
@@ -597,14 +617,17 @@ list table layout in human mode.`)
                 throw new Error("Provide at least one study id.");
             if (flat.length === 1) {
                 const rid = resolveId(flat[0]);
-                const data = await client.get(`/studies/${rid}`);
+                const [data, participants] = await Promise.all([
+                    client.get(`/studies/${rid}`),
+                    fetchStudyParticipants(client, rid),
+                ]);
                 const result = data;
                 if (result.id)
                     result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
                 if (data.product_id) {
                     result.url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
                 }
-                formatStudyDetail(result, globals.json);
+                formatStudyDetail(result, globals.json, {}, participants);
                 if (!globals.json && data.product_id) {
                     const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
                     console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
@@ -613,13 +636,17 @@ list table layout in human mode.`)
             }
             const results = await Promise.all(flat.map(async (raw) => {
                 const rid = resolveId(raw);
-                const data = await client.get(`/studies/${rid}`);
+                const [data, participants] = await Promise.all([
+                    client.get(`/studies/${rid}`),
+                    fetchStudyParticipants(client, rid),
+                ]);
                 const r = data;
                 if (r.id)
                     r.alias = tagAlias(ALIAS_PREFIX.study, String(r.id));
                 if (data.product_id) {
                     r.url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
                 }
+                r.participants = participants;
                 return r;
             }));
             if (globals.json) {
@@ -632,84 +659,84 @@ list table layout in human mode.`)
     });
     study
         .command("results")
-        .description("View aggregated results: tester counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed.")
+        .description("View aggregated results: participant counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed.")
         .argument("<id>", "Study ID")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
-        .option("--summary", "Lean summary projection: counts + sentiment + per-tester {alias, status, sentiment, comment}. Drops interview_answers + per-interaction breakdowns.")
+        .option("--summary", "Lean summary projection: counts + sentiment + per-participant {alias, status, sentiment, comment}. Drops interview_answers + per-interaction breakdowns.")
         // PC-N4: agents reach for `--summarize` (verb) by analogy with the MCP
         // `summarize` action; accept it as a hidden alias of --summary so the
         // canonical flag stays the documented one but the muscle-memory variant
         // works without a round-trip.
         .addOption(new Option("--summarize", "Hidden alias for --summary").hideHelp())
-        .option("--transcript <tester_id>", "Chat transcript projection for one tester: flat role/text/turn-index array (chat-modality only). Mirrors the MCP `get_chat_transcript` shape.")
+        .option("--transcript <participant_id>", "Chat transcript projection for one participant: flat role/text/turn-index array (chat-modality only). Mirrors the MCP `get_chat_transcript` shape.")
         .addHelpText("after", `
 Examples:
   $ ish study results <id>
   $ ish study results <id> --json
   $ ish study results <id> --summary --json
-  $ ish study results <id> --transcript t-d4e --json
+  $ ish study results <id> --transcript pt-d4e --json
 
 Default --json envelope (M10: per-answer sentiment now included):
   {
     "study": { "alias": "s-...", "name": "...", "modality": "..." },
-    "tester_count": 12,
+    "participant_count": 12,
     "completed_count": 8,
     "failed_count": 0,
     "sentiment": { "counts": { "Satisfied": 5, "Frustrated": 2 }, "total": 7 },
     "interview_answers": [
       { "question": "...", "type": "text",
         "answers": [
-          { "tester_alias": "t-...", "tester_name": "...", "iteration": "A",
+          { "participant_alias": "pt-...", "participant_name": "...", "iteration": "A",
             "answer": "...", "sentiment": "Satisfied" }
         ] }
     ],
-    "testers": [
-      { "alias": "t-...", "name": "...", "iteration": "A", "status": "completed",
+    "participants": [
+      { "alias": "pt-...", "name": "...", "iteration": "A", "status": "completed",
         "interaction_count": 12, "sentiment": "Satisfied", "comment": "...",
         "error_message": "..." }
     ]
   }
 
 --summary projection (M2-friction-7: drops the interview_answers payload):
-  { study, tester_count, completed_count, failed_count, sentiment, testers: [...] }
+  { study, participant_count, completed_count, failed_count, sentiment, participants: [...] }
 
---transcript <tester_id> projection (M2-friction-12, chat modality):
+--transcript <participant_id> projection (M2-friction-12, chat modality):
   {
-    "tester_id": "...", "tester_alias": "t-...",
+    "participant_id": "...", "participant_alias": "pt-...",
     "instance_name": "...", "modality": "chat",
     "transcript": [
       { "role": "bot",    "text": "Hi…",    "turn_index": 0, "failure": null },
-      { "role": "tester", "text": "Pricing?", "turn_index": 0,
+      { "role": "participant", "text": "Pricing?", "turn_index": 0,
         "action_type": "send_text", "option_label": null, "sentiment": null }
     ],
     "unique_bot_replies": 2,
-    "tester_summary": { "comment": "...", "sentiment": {...} }
+    "participant_summary": { "comment": "...", "sentiment": {...} }
   }
 
 Tips:
-  Use \`--get <path>\` for a single value (e.g. \`--get tester_count\`),
+  Use \`--get <path>\` for a single value (e.g. \`--get participant_count\`),
   \`--fields a,b,c\` to project the JSON output further.
 
 Common --get paths (default envelope):
-  --get tester_count                            # how many testers ran
+  --get participant_count                            # how many participants ran
   --get completed_count                         # how many finished
   --get failed_count                            # how many errored
   --get sentiment                               # {counts, total} histogram
   --get sentiment.counts                        # bare label→count map
   --get sentiment.total                         # total sentiment-tagged answers
   --get study.modality                          # interactive | text | image | …
-  --get testers.alias                           # one alias per line
-  --get testers.0.comment                       # first tester's narrative comment
-  --get testers.0.sentiment                     # first tester's aggregate sentiment
+  --get participants.alias                           # one alias per line
+  --get participants.0.comment                       # first participant's narrative comment
+  --get participants.0.sentiment                     # first participant's aggregate sentiment
   --get interview_answers                       # full per-question payload
   --get interview_answers.0.question            # text of the first question
   --get interview_answers.0.answers.0.answer    # first answer to the first question
 
-Common --get paths (--transcript <tester_id> envelope):
+Common --get paths (--transcript <participant_id> envelope):
   --get transcript                              # full role/text/turn array
   --get transcript.text                         # one text per turn
-  --get tester_summary.comment                  # narrative comment
-  --get tester_summary.sentiment                # aggregate sentiment map
+  --get participant_summary.comment                  # narrative comment
+  --get participant_summary.sentiment                # aggregate sentiment map
   --get unique_bot_replies                      # bot-side message count
 
 When no runs have completed, the default envelope is returned with zero counts and empty arrays.`)
@@ -724,20 +751,23 @@ When no runs have completed, the default envelope is returned with zero counts a
             }
             const rid = resolveId(id);
             if (opts.transcript) {
-                // --transcript <tester_id>: bypass the study aggregator; fetch
-                // the named tester directly. Cheaper (one GET, no nested
+                // --transcript <participant_id>: bypass the study aggregator; fetch
+                // the named participant directly. Cheaper (one GET, no nested
                 // iterations payload) and shapes 1:1 with the MCP transcript.
-                const testerId = resolveId(opts.transcript);
-                const tester = await client.get(`/testers/${testerId}`);
-                output(buildChatTranscript(tester), globals.json, { preProjected: true });
+                const participantId = resolveId(opts.transcript);
+                const participant = await client.get(`/participants/${participantId}`);
+                output(buildChatTranscript(participant), globals.json, { preProjected: true });
                 return;
             }
-            const data = await client.get(`/studies/${rid}`);
+            const [data, participants] = await Promise.all([
+                client.get(`/studies/${rid}`),
+                fetchStudyParticipants(client, rid),
+            ]);
             if (wantsSummary) {
-                output(buildStudyResultsSummary(data), globals.json, { preProjected: true });
+                output(buildStudyResultsSummary(data, participants), globals.json, { preProjected: true });
             }
             else {
-                formatStudyResults(data, globals.json);
+                formatStudyResults(data, participants, globals.json);
             }
             if (!globals.json && data.product_id) {
                 const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
@@ -770,7 +800,11 @@ Examples:
   $ ish study update <id> --assignment "Sign up:Complete the signup flow" \\
       --question "How easy was it?"
   $ ish study update <id> --questionnaire ./questionnaire.json
-  $ ish study update <id> --assignments-file ./assignments.json`)
+  $ ish study update <id> --assignments-file ./assignments.json
+
+Replacing assignments replaces the full list (no additive edit). Assignment
+checklists ("steps") ride along when present in the JSON forms
+(--assignments-file / --assignments) — see docs get-page concepts/assignment.`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const assignments = resolveAssignments(opts);
@@ -852,7 +886,7 @@ Examples:
         });
     });
     attachStudyRunCommands(study);
-    attachStudyTesterCommands(study);
+    attachStudyParticipantCommands(study);
     attachStudyAnalyzeCommands(study);
     attachStudyScreenshotsCommands(study);
 }

package/dist/commands/workspace.js

@@ -152,7 +152,7 @@ existing workspace was returned. On creation, \`reused: false\`.`)
         .addHelpText("after", `
 Usage counters:
   studies_used / studies_max — current study count vs the user's plan cap
-  testers_used / testers_max — workspace-private tester profile count vs cap
+  people_used / people_max — workspace-private participant profile count vs cap
 
 Caps fall back to null when the user's plan grants unlimited (math.inf). The
 account tier is read from /account/me; limit tables come from /billing/limits.
@@ -174,7 +174,7 @@ Examples:
             if (usage.tier)
                 console.log(`Plan:           ${usage.tier}`);
             console.log(`Studies:        ${usage.studies_used} / ${renderCap(usage.studies_max)}`);
-            console.log(`Custom testers: ${usage.testers_used} / ${renderCap(usage.testers_max)}`);
+            console.log(`Custom people: ${usage.people_used} / ${renderCap(usage.people_max)}`);
         });
     });
     workspace
@@ -213,11 +213,11 @@ async function collectWorkspaceUsage(client, workspaceId) {
     const studiesPromise = client
         .get(`/products/${workspaceId}/studies`)
         .catch(() => []);
-    // testers_used: paginated list returns { total, items, ... }. Backend
-    // gates `maxCustomTesterProfiles` on visibility=workspace (rows owned by
+    // people_used: paginated list returns { total, items, ... }. Backend
+    // gates `maxCustomPersons` on visibility=workspace (rows owned by
     // this workspace; was `private` before the visibility rename).
-    const testersPromise = client
-        .get("/tester-profiles", {
+    const peoplePromise = client
+        .get("/people", {
         product_id: workspaceId,
         visibility: "workspace",
         type: "ai",
@@ -232,18 +232,18 @@ async function collectWorkspaceUsage(client, workspaceId) {
     const limitsPromise = client
         .get("/billing/limits")
         .catch(() => ({ tiers: {} }));
-    const [product, studies, testers, account, limits] = await Promise.all([
+    const [product, studies, participants, account, limits] = await Promise.all([
         productPromise,
         studiesPromise,
-        testersPromise,
+        peoplePromise,
         acctPromise,
         limitsPromise,
     ]);
     const tier = typeof account.credits?.tier === "string" ? account.credits.tier : null;
     const tierTable = tier ? limits.tiers?.[tier] ?? null : null;
     const studiesMax = tierTable && "maxStudiesPerProduct" in tierTable ? tierTable.maxStudiesPerProduct : null;
-    const testersMax = tierTable && "maxCustomTesterProfiles" in tierTable
-        ? tierTable.maxCustomTesterProfiles
+    const peopleMax = tierTable && "maxCustomPersons" in tierTable
+        ? tierTable.maxCustomPersons
         : null;
     return {
         id: workspaceId,
@@ -252,8 +252,8 @@ async function collectWorkspaceUsage(client, workspaceId) {
         tier,
         studies_used: Array.isArray(studies) ? studies.length : 0,
         studies_max: studiesMax,
-        testers_used: typeof testers.total === "number" ? testers.total : 0,
-        testers_max: testersMax,
+        people_used: typeof participants.total === "number" ? participants.total : 0,
+        people_max: peopleMax,
     };
 }
 // ---------------------------------------------------------------------------
@@ -364,7 +364,7 @@ function registerSiteAccessCommands(workspace) {
     });
     sa
         .command("login")
-        .description("Set login form credentials a tester will type into the site")
+        .description("Set login form credentials a participant will type into the site")
         .requiredOption("--username <u>", 'Username (or "-" to read from stdin)')
         .requiredOption("--password <p>", 'Password (or "-" to read from stdin)')
         .option("--workspace <id>", "Workspace ID; defaults to active workspace")

package/dist/connect.js

@@ -46,7 +46,7 @@ function row(content, inner) {
 }
 function renderCard(sim) {
     const inner = CARD_WIDTH - 4;
-    const name = truncate(sim.tester_name ?? sim.instance_name ?? sim.tester_id.slice(0, 8), inner - 2);
+    const name = truncate(sim.participant_name ?? sim.instance_name ?? sim.participant_id.slice(0, 8), inner - 2);
     // Top border with name
     const nameSegment = `─ ${name} `;
     const topPad = CARD_WIDTH - 2 - nameSegment.length;
@@ -160,16 +160,16 @@ function renderSimulationCards(simulations) {
     }
 }
 // --- Local storage for completed simulations ---
-const storedTesterIds = new Set();
+const storedParticipantIds = new Set();
 function storeCompletedSimulation(sim) {
-    if (storedTesterIds.has(sim.tester_id))
+    if (storedParticipantIds.has(sim.participant_id))
         return;
-    storedTesterIds.add(sim.tester_id);
+    storedParticipantIds.add(sim.participant_id);
     const dir = simulationsDir();
     mkdirSync(dir, { recursive: true });
     const logFile = join(dir, "history.jsonl");
     const entry = {
-        tester_id: sim.tester_id,
+        participant_id: sim.participant_id,
         instance_name: sim.instance_name,
         status: sim.status,
         study_name: sim.study_name,

package/dist/index.js

@@ -10,13 +10,14 @@ import { upgrade } from "./upgrade.js";
 import { registerWorkspaceCommands } from "./commands/workspace.js";
 import { registerStudyCommands } from "./commands/study.js";
 import { registerIterationCommands } from "./commands/iteration.js";
-import { registerProfileCommands } from "./commands/profile.js";
+import { registerPersonCommands } from "./commands/person.js";
 import { registerSourceCommands } from "./commands/source.js";
 import { registerConfigCommands } from "./commands/config.js";
 import { registerAskCommands } from "./commands/ask.js";
 import { registerChatCommand } from "./commands/chat.js";
 import { registerDocsCommands } from "./commands/docs.js";
 import { registerInitCommands } from "./commands/init.js";
+import { registerMcpCommands } from "./commands/mcp.js";
 import { registerSecretCommands } from "./commands/secret.js";
 import { AGENT_HELP_FOOTER } from "./lib/docs.js";
 import { runInline, EXIT_USAGE, injectGlobalWorkspaceOption } from "./lib/command-helpers.js";
@@ -43,7 +44,7 @@ catch {
 }
 program
     .name("ish")
-    .description("ish CLI — run studies and asks against AI tester audiences")
+    .description("ish CLI — run studies and asks with AI people")
     .version(version)
     .addHelpText("after", AGENT_HELP_FOOTER);
 // Unified error envelope for Commander-level failures (unknown command,
@@ -91,7 +92,7 @@ program
     .addOption(new Option("--dev", "Use local dev API (http://localhost:8000)").hideHelp())
     .option("--workspace <id>", "Default workspace ID; per-subcommand --workspace overrides")
     .option("--json", "Output as JSON (auto-enabled when piped)")
-    .option("--get <field>", "Extract a single field from the JSON response and print only its value (implies --json internally; supports dotted paths e.g. tester_profile.name)")
+    .option("--get <field>", "Extract a single field from the JSON response and print only its value (implies --json internally; supports dotted paths e.g. person.name)")
     .option("--human", "Force human-readable output even when stdout is piped (overrides JSON-when-piped auto-detection)")
     .option("--fields <fields>", "Comma-separated fields to include in JSON output (e.g. alias,name,status)")
     .option("--verbose", "Include full UUIDs and timestamps in JSON output")
@@ -305,13 +306,14 @@ program
 registerWorkspaceCommands(program);
 registerStudyCommands(program);
 registerIterationCommands(program);
-registerProfileCommands(program);
+registerPersonCommands(program);
 registerSourceCommands(program);
 registerConfigCommands(program);
 registerAskCommands(program);
 registerChatCommand(program);
 registerDocsCommands(program);
 registerInitCommands(program);
+registerMcpCommands(program);
 registerSecretCommands(program);
 program
     .command("upgrade")

package/dist/lib/accessibility-profile.d.ts

@@ -1,6 +1,6 @@
 /**
  * Client-side validator for the AccessibilityProfile v1.0 JSONB shape on
- * TesterProfile.accessibility_profile. Mirrors
+ * Person.accessibility_profile. Mirrors
  * `ish-mcp/spec/accessibility-profile-schema.v1.json` (additionalProperties:
  * false at every level except `extensions`). An empty object `{}` is the
  * canonical default. When non-empty, `version` is required and must be

package/dist/lib/accessibility-profile.js

@@ -1,6 +1,6 @@
 /**
  * Client-side validator for the AccessibilityProfile v1.0 JSONB shape on
- * TesterProfile.accessibility_profile. Mirrors
+ * Person.accessibility_profile. Mirrors
  * `ish-mcp/spec/accessibility-profile-schema.v1.json` (additionalProperties:
  * false at every level except `extensions`). An empty object `{}` is the
  * canonical default. When non-empty, `version` is required and must be

package/dist/lib/alias-hydrate.js

@@ -116,10 +116,10 @@ export async function hydrateForAlias(client, alias, hints = {}) {
             await hydrateList(client, ALIAS_PREFIX.iteration, `/studies/${study}/iterations`);
             return;
         }
-        case ALIAS_PREFIX.testerProfile: {
+        case ALIAS_PREFIX.person: {
             if (!ws)
                 return;
-            await hydrateList(client, ALIAS_PREFIX.testerProfile, "/tester-profiles", { workspace_id: ws, type: "all", limit: "200" });
+            await hydrateList(client, ALIAS_PREFIX.person, "/people", { workspace_id: ws, type: "all", limit: "200" });
             return;
         }
         case ALIAS_PREFIX.ask: {
@@ -135,9 +135,9 @@ export async function hydrateForAlias(client, alias, hints = {}) {
             return;
         }
         // No cheap single-call hydrate for the rest:
-        //   tester (`t-`)         — scoped to iteration
+        //   participant (`pt-`)         — scoped to iteration
         //   ask round (`r-`)      — nested on the ask
-        //   audience source (`tps-`) — fetched per-id
+        //   person source (`ps-`) — fetched per-id
         //   simulation config (`c-`) — no list endpoint yet
         default:
             return;