@ishlabs/cli 0.12.2 → 0.14.0

package/dist/commands/iteration.js

@@ -5,11 +5,46 @@
  * content/file for media). Create one before `ish study run` dispatches
  * simulations against it.
  */
-import { withClient, resolveStudy, resolveWorkspace, readFileOrStdin } from "../lib/command-helpers.js";
+import { readFileSync } from "node:fs";
+import { withClient, resolveStudy, resolveWorkspace, readFileOrStdin, collectIds } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatIterationList, ValidationError } from "../lib/output.js";
 import { resolveContentUrl, resolveContentUrls, resolveTextContent } from "../lib/upload.js";
-import { isMediaModality, validateIterationDetails } from "../lib/modality.js";
+import { isMediaModality, validateIterationDetails, normalizeChatMode, validateRoleCriteria } from "../lib/modality.js";
+import { normalizeEnumValue, SCREEN_FORMATS } from "../lib/enums.js";
+/**
+ * Read text inline or from a file when prefixed with `@/path/to/file`.
+ * Mirrors the `--content-text @./email.html` pattern used elsewhere.
+ */
+function readTextOrAtFile(value) {
+    if (value.startsWith("@")) {
+        return readFileSync(value.slice(1), "utf8");
+    }
+    return value;
+}
+/**
+ * Parse a JSON-blob flag that also supports `@filepath` (read from disk).
+ * Used for tester_pair `--role-criteria-a/-b` and any future blob inputs.
+ * Throws a descriptive Error on bad JSON or wrong top-level type.
+ */
+function parseJsonOrAtFile(raw, flagName) {
+    if (raw === undefined)
+        return undefined;
+    const text = readTextOrAtFile(raw).trim();
+    if (text.length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Invalid ${flagName}: expected valid JSON object.`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Invalid ${flagName}: expected a JSON object.`);
+    }
+    return parsed;
+}
 /**
  * Pattern C / M12: project each tester row on an iteration response so its
  * `alias` and `name` survive `leanJson` (which strips raw UUID values). The
@@ -127,9 +162,9 @@ function buildIterationDetails(modality, opts) {
                 ...mediaExtras(opts),
             };
         case "chat": {
-            const endpoint = parseJsonFlag(opts.chatEndpointJson, "--chat-endpoint-json");
-            if (!endpoint && !opts.chatEndpointId) {
-                throw new Error("Chat iterations require either --chat-endpoint-id (saved endpoint) or --chat-endpoint-json (inline config).");
+            const mode = opts.chatMode === undefined ? "external_chatbot" : normalizeChatMode(opts.chatMode);
+            if (mode === null) {
+                throw new ValidationError(`Invalid --chat-mode "${opts.chatMode}". Expected "external_chatbot" or "tester_pair" (hyphenated variants accepted: "external-chatbot", "tester-pair").`, ["external_chatbot", "tester_pair"]);
             }
             let maxTurns;
             if (opts.maxTurns !== undefined) {
@@ -139,13 +174,111 @@ function buildIterationDetails(modality, opts) {
                 }
                 maxTurns = parsed;
             }
-            return {
+            const topLevel = {
                 type: "chat",
-                ...(endpoint && { endpoint }),
-                ...(opts.chatEndpointId && { chatbot_endpoint_id: opts.chatEndpointId }),
                 ...(maxTurns !== undefined && { max_turns: maxTurns }),
                 ...(opts.earlyTermination !== undefined && { early_termination: opts.earlyTermination }),
             };
+            if (mode === "tester_pair") {
+                // Reject external-chatbot flags so users don't silently lose them.
+                const conflictingFlags = [];
+                if (opts.chatEndpointId)
+                    conflictingFlags.push("--chat-endpoint-id");
+                if (opts.chatEndpointJson)
+                    conflictingFlags.push("--chat-endpoint-json");
+                if (conflictingFlags.length > 0) {
+                    throw new ValidationError(`--chat-mode tester_pair is incompatible with ${conflictingFlags.join(", ")}. Use --audience-a/-b or --role-criteria-a/-b plus --scenario-a/-b instead.`, conflictingFlags);
+                }
+                const audA = (opts.audienceA ?? []).map(resolveId);
+                const audB = (opts.audienceB ?? []).map(resolveId);
+                const critARaw = parseJsonOrAtFile(opts.roleCriteriaA, "--role-criteria-a");
+                const critBRaw = parseJsonOrAtFile(opts.roleCriteriaB, "--role-criteria-b");
+                let critA;
+                let critB;
+                try {
+                    critA = validateRoleCriteria(critARaw, "--role-criteria-a");
+                    critB = validateRoleCriteria(critBRaw, "--role-criteria-b");
+                }
+                catch (err) {
+                    throw new ValidationError(err instanceof Error ? err.message : "Invalid role criteria.", ["--role-criteria-a", "--role-criteria-b"]);
+                }
+                const sideAHasInput = audA.length > 0 || !!critA;
+                const sideBHasInput = audB.length > 0 || !!critB;
+                if (!sideAHasInput || !sideBHasInput) {
+                    throw new ValidationError("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).", ["--audience-a", "--audience-b", "--role-criteria-a", "--role-criteria-b"]);
+                }
+                // 1×N broadcast: the canonical "rehearse one side against N
+                // variations" shape. When one side has exactly one explicit
+                // profile and the other has more, broadcast the singleton so
+                // every conversation has the same fixed side and a distinct
+                // varying side. Example: --audience-a tp-rep --audience-b
+                // tp-cto1,tp-cto2,tp-cto3 → N=3 conversations, same rep vs
+                // 3 different CTO personas. Same backend wire shape, just
+                // CLI-side ergonomics.
+                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.`;
+                }
+                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.`;
+                }
+                if (broadcastMsg) {
+                    // stderr so it doesn't pollute --json stdout.
+                    console.error(broadcastMsg);
+                }
+                // Pairing rule (after CLI's 1×N broadcast cloning above): equal
+                // counts zip 1:1 by index; mismatched counts > 1 reject. Criteria
+                // resolution happens server-side and may yield differing counts.
+                const bothExplicit = audA_final.length > 0 && audB_final.length > 0 && !critA && !critB;
+                if (bothExplicit && audA_final.length !== audB_final.length) {
+                    throw new ValidationError(`--audience-a (${audA_final.length}) and --audience-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"]);
+                }
+                if (!opts.scenarioA || !opts.scenarioB) {
+                    throw new ValidationError("tester_pair chat iterations require --scenario-a and --scenario-b (text or @filepath).", ["--scenario-a", "--scenario-b"]);
+                }
+                const scenarioA = readTextOrAtFile(opts.scenarioA);
+                const scenarioB = readTextOrAtFile(opts.scenarioB);
+                if (scenarioA.trim().length === 0 || scenarioB.trim().length === 0) {
+                    throw new Error("--scenario-a and --scenario-b must be non-empty.");
+                }
+                const initiatorRaw = (opts.initiatorSide ?? "a").toLowerCase();
+                if (initiatorRaw !== "a" && initiatorRaw !== "b") {
+                    throw new ValidationError(`Invalid --initiator-side "${opts.initiatorSide}". Expected "a" or "b".`, ["a", "b"]);
+                }
+                return {
+                    ...topLevel,
+                    mode_details: {
+                        mode: "tester_pair",
+                        audience_a: audA_final,
+                        audience_b: audB_final,
+                        scenario_a: scenarioA,
+                        scenario_b: scenarioB,
+                        initiator_side: initiatorRaw,
+                        ...(critA && { role_criteria_a: critA }),
+                        ...(critB && { role_criteria_b: critB }),
+                    },
+                };
+            }
+            // external_chatbot (default)
+            const endpoint = parseJsonFlag(opts.chatEndpointJson, "--chat-endpoint-json");
+            if (!endpoint && !opts.chatEndpointId) {
+                throw new Error("Chat iterations require either --chat-endpoint-id (saved endpoint) or --chat-endpoint-json (inline config). For two-AI rehearsal use --chat-mode tester_pair with --audience-a/-b and --scenario-a/-b.");
+            }
+            return {
+                ...topLevel,
+                mode_details: {
+                    mode: "external_chatbot",
+                    ...(endpoint && { endpoint }),
+                    ...(opts.chatEndpointId && { chatbot_endpoint_id: opts.chatEndpointId }),
+                },
+            };
         }
         default:
             if (!opts.url) {
@@ -154,11 +287,19 @@ function buildIterationDetails(modality, opts) {
             if (opts.platform === "figma" && (!opts.fileKey || !opts.startNodeId)) {
                 throw new Error("Figma interactive iterations require both --file-key and --start-node-id.");
             }
+            let screenFormat = "desktop";
+            if (opts.screenFormat !== undefined) {
+                const normalized = normalizeEnumValue(opts.screenFormat, SCREEN_FORMATS);
+                if (normalized === null) {
+                    throw new ValidationError(`Invalid --screen-format "${opts.screenFormat}". Expected: ${SCREEN_FORMATS.join(" | ")} (hyphen/underscore variants accepted).`, [...SCREEN_FORMATS]);
+                }
+                screenFormat = normalized;
+            }
             return {
                 type: "interactive",
                 platform: opts.platform || "browser",
                 url: opts.url,
-                screen_format: opts.screenFormat || "desktop",
+                screen_format: screenFormat,
                 ...(opts.locale && { locale: opts.locale }),
                 ...(opts.fileKey && { file_key: opts.fileKey }),
                 ...(opts.startNodeId && { start_node_id: opts.startNodeId }),
@@ -225,7 +366,7 @@ Concept pages: ish docs get-page concepts/iteration
         // Interactive
         .option("--platform <platform>", "Platform (browser, android, figma, code) — interactive only")
         .option("--url <url>", "URL to test — interactive only")
-        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only")
+        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only; hyphen/underscore variants accepted")
         .option("--locale <locale>", "Locale code (e.g. en-US) — interactive only")
         .option("--file-key <key>", "Figma file key — required when --platform=figma")
         .option("--start-node-id <id>", "Figma start node id — required when --platform=figma")
@@ -252,17 +393,29 @@ Concept pages: ish docs get-page concepts/iteration
         .option("--segmentation-json <json>", "Segmentation JSON — time_based {intervals_seconds, labels?}, section_based {sections[{name,label,...}]}, or page_based {} — media modalities")
         .option("--content-config-json <json>", "Content config JSON — {early_termination, selected_segment_indices?} — media modalities")
         // Chat modality
-        .option("--chat-endpoint-id <id>", "Saved chatbot endpoint id — chat modality (legacy; prefer --endpoint)")
-        .option("--chat-endpoint-json <json>", "Inline chatbot endpoint config JSON — chat modality (legacy; prefer --endpoint-config)")
+        .option("--chat-mode <mode>", "Chat mode: external_chatbot (default; probe a customer chatbot) or tester_pair (two AI audiences talk to each other)")
+        .option("--chat-endpoint-id <id>", "Saved chatbot endpoint id — chat modality, external_chatbot mode (legacy; prefer --endpoint)")
+        .option("--chat-endpoint-json <json>", "Inline chatbot endpoint config JSON — chat modality, external_chatbot mode (legacy; prefer --endpoint-config)")
         .option("--max-turns <n>", "Max tester turns (1-50) — chat modality (default 12)")
         .option("--early-termination", "End the chat session early when the tester signals stop — chat modality")
         // Agent-friendly chat shortcuts: --endpoint <id> resolves a saved
         // chatbot endpoint via alias / UUID and fetches its config inline;
         // --endpoint-config <file> takes a raw config file (or `-` for
         // stdin). Mutually exclusive with each other and with the legacy
-        // --chat-endpoint-* flags. Only meaningful for chat-modality studies.
-        .option("--endpoint <id>", "Saved chatbot endpoint id (alias or UUID) — chat modality")
-        .option("--endpoint-config <file>", "Raw ChatbotEndpointConfig JSON file or `-` for stdin — chat modality")
+        // --chat-endpoint-* flags. Only meaningful for chat-modality studies,
+        // external_chatbot mode.
+        .option("--endpoint <id>", "Saved chatbot endpoint id (alias or UUID) — chat modality, external_chatbot mode")
+        .option("--endpoint-config <file>", "Raw ChatbotEndpointConfig JSON file or `-` for stdin — chat modality, external_chatbot mode")
+        // tester_pair (two-AI rehearsal) flags. audience_a and audience_b must
+        // be the same length — pairs are 1:1 by index. Each side has its own
+        // scenario + goal; the partner does NOT see the other side's prompt.
+        .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", collectIds, [])
+        .option("--audience-b <ids>", "Tester profile IDs/aliases for audience B (comma-separated or repeatable). 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", collectIds, [])
+        .option("--scenario-a <text-or-@file>", "Side-A scenario + goal text, or @filepath — chat tester_pair mode")
+        .option("--scenario-b <text-or-@file>", "Side-B scenario + goal text, or @filepath — 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 (inline JSON 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. Persona-first: filters the eligible profile pool without altering personas. Use INSTEAD of --audience-a or alongside it (criteria then validates the explicit list). 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.")
         // Escape hatch
         .option("--details-json <json>", "Raw iteration details JSON (overrides individual flags)")
         .addHelpText("after", `
@@ -364,6 +517,17 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                 if (!isChat && (opts.endpoint !== undefined || opts.endpointConfig !== undefined)) {
                     throw new Error(`This study uses "${modality}" modality — --endpoint / --endpoint-config are for chat studies.`);
                 }
+                const pairFlagsSet = (opts.audienceA && opts.audienceA.length > 0)
+                    || (opts.audienceB && opts.audienceB.length > 0)
+                    || opts.scenarioA !== undefined
+                    || opts.scenarioB !== undefined
+                    || opts.initiatorSide !== undefined
+                    || opts.roleCriteriaA !== undefined
+                    || opts.roleCriteriaB !== undefined
+                    || normalizeChatMode(opts.chatMode) === "tester_pair";
+                if (!isChat && pairFlagsSet) {
+                    throw new Error(`This study uses "${modality}" modality — --chat-mode / --audience-a/-b / --scenario-a/-b / --role-criteria-a/-b are for chat studies.`);
+                }
                 // Validate per-modality required flags BEFORE any upload so we don't
                 // orphan blobs in storage when the wrong flag is passed (e.g.
                 // --content-url to an image-modality study).
@@ -389,18 +553,47 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                             throw new Error("Document iterations require --content-url. Provide the URL or local file path.");
                         }
                         break;
-                    case "chat":
+                    case "chat": {
+                        const mode = opts.chatMode === undefined ? "external_chatbot" : normalizeChatMode(opts.chatMode);
+                        if (mode === null) {
+                            throw new ValidationError(`Invalid --chat-mode "${opts.chatMode}". Expected "external_chatbot" or "tester_pair" (hyphenated variants accepted).`, ["external_chatbot", "tester_pair"]);
+                        }
+                        if (mode === "tester_pair") {
+                            const conflicting = [];
+                            if (opts.endpoint)
+                                conflicting.push("--endpoint");
+                            if (opts.endpointConfig)
+                                conflicting.push("--endpoint-config");
+                            if (opts.chatEndpointId)
+                                conflicting.push("--chat-endpoint-id");
+                            if (opts.chatEndpointJson)
+                                conflicting.push("--chat-endpoint-json");
+                            if (conflicting.length > 0) {
+                                throw new ValidationError(`--chat-mode tester_pair is incompatible with ${conflicting.join(", ")}. Use --audience-a/-b or --role-criteria-a/-b plus --scenario-a/-b instead.`, conflicting);
+                            }
+                            const sideAHasInput = (opts.audienceA && opts.audienceA.length > 0) || !!opts.roleCriteriaA;
+                            const sideBHasInput = (opts.audienceB && opts.audienceB.length > 0) || !!opts.roleCriteriaB;
+                            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).");
+                            }
+                            if (!opts.scenarioA || !opts.scenarioB) {
+                                throw new Error("tester_pair chat iterations require --scenario-a <text-or-@file> and --scenario-b <text-or-@file>.");
+                            }
+                            break;
+                        }
+                        // external_chatbot mode (default)
                         if (!opts.chatEndpointId
                             && !opts.chatEndpointJson
                             && !opts.endpoint
                             && !opts.endpointConfig) {
-                            throw new Error("Chat iterations require one of: --endpoint <id>, --endpoint-config <file>, --chat-endpoint-id, or --chat-endpoint-json.");
+                            throw new Error("Chat iterations (external_chatbot mode) require one of: --endpoint <id>, --endpoint-config <file>, --chat-endpoint-id, or --chat-endpoint-json. For two-AI rehearsal use --chat-mode tester_pair.");
                         }
                         if ((opts.endpoint || opts.endpointConfig)
                             && (opts.chatEndpointId || opts.chatEndpointJson)) {
                             throw new ValidationError("Pass only one of: --endpoint / --endpoint-config (preferred) or the legacy --chat-endpoint-id / --chat-endpoint-json.", ["--endpoint", "--endpoint-config"]);
                         }
                         break;
+                    }
                     default:
                         if (!opts.url) {
                             throw new Error("Interactive iterations require --url. Provide the URL to test.");
@@ -427,9 +620,10 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                 if (isChat && (opts.endpoint || opts.endpointConfig)) {
                     // Agent-friendly path: fetch a saved endpoint by alias / UUID
                     // (or read a raw config from a file / stdin) and embed the full
-                    // ChatbotEndpointConfig inline at iteration.details.endpoint.
-                    // Backend's chat iteration shape is wider than what
-                    // buildIterationDetails covers; we materialise it here.
+                    // ChatbotEndpointConfig inline at
+                    // `iteration.details.mode_details.endpoint`. Backend's chat
+                    // iteration shape now wraps mode-specific fields under
+                    // `mode_details` with a `mode` discriminator.
                     let endpointConfig;
                     let chatbotEndpointId = null;
                     if (opts.endpoint) {
@@ -463,8 +657,11 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                     const earlyTermination = opts.earlyTermination !== undefined ? opts.earlyTermination : true;
                     details = {
                         type: "chat",
-                        endpoint: endpointConfig,
-                        chatbot_endpoint_id: chatbotEndpointId,
+                        mode_details: {
+                            mode: "external_chatbot",
+                            endpoint: endpointConfig,
+                            ...(chatbotEndpointId && { chatbot_endpoint_id: chatbotEndpointId }),
+                        },
                         max_turns: maxTurns,
                         early_termination: earlyTermination,
                     };

package/dist/commands/profile.js

@@ -1,11 +1,14 @@
 /**
  * ish profile — Manage profiles, audience generation, and source uploads.
  */
+import fs from "node:fs";
 import { withClient, readJsonFileOrStdin, resolveWorkspace } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { formatTesterProfileList, formatGeneratedProfileList, output, } from "../lib/output.js";
 import { resolveTextContent } from "../lib/upload.js";
 import { isUuid, resolveSourceRef } from "../lib/profile-sources.js";
+import { assertEnumValue, EDUCATION_LEVELS, HOUSEHOLDS, LOCALE_TYPES, INCOME_LEVELS, EMPLOYMENT_STATUSES, } from "../lib/enums.js";
+import { validateAccessibilityProfile } from "../lib/accessibility-profile.js";
 function collect(value, prev) {
     return prev.concat(value);
 }
@@ -301,16 +304,34 @@ list table layout in human mode. Use --fields to project per-item.`)
         .option("--country <code>", "Country code, e.g. US")
         .option("--gender <g>", "Gender, e.g. female")
         .option("--date-of-birth <YYYY-MM-DD>", "Date of birth")
-        .option("--tech-savviness <n>", "Tech savviness score")
+        .option("--education-level <value>", `Education level. One of: ${EDUCATION_LEVELS.join(", ")}`)
+        .option("--household <value>", `Household composition (MECE). One of: ${HOUSEHOLDS.join(", ")}. A couple raising children is couple_with_kids, not couple_no_kids; "single" means lives alone with no partner, roommates, parents, or children in the household.`)
+        .option("--locale-type <value>", `Self-described neighborhood type. One of: ${LOCALE_TYPES.join(", ")}`)
+        .option("--income-level <value>", `Self-identified relative socioeconomic position. One of: ${INCOME_LEVELS.join(", ")}`)
+        .option("--employment-status <value>", `Primary daytime activity / labor-force status. One of: ${EMPLOYMENT_STATUSES.join(", ")}`)
+        .option("--accessibility-profile <json-or-path>", "AccessibilityProfile v1.0 as an inline JSON string OR a path to a JSON file. Empty object {} is the canonical default. Validated client-side against the spec before submit.")
         .addHelpText("after", `
 Examples:
   $ ish profile update <id> --bio "Edited bio"
-  $ ish profile update <id> --name "Alice" --country US --tech-savviness 8
+  $ ish profile update <id> --name "Alice" --country US --education-level bachelor
+  $ ish profile update <id> --household couple_with_kids --locale-type suburban
+  $ ish profile update <id> --income-level middle --employment-status employed_full_time
+  $ ish profile update <id> --accessibility-profile '{"version":"1.0","visual":{"uses_screen_reader":true,"text_size":"large"},"cognitive":{"reduce_motion":true},"assistive_tech":["VoiceOver"]}'
+  $ ish profile update <id> --accessibility-profile ./a11y.json
   $ ish profile update <id> --file updates.json
 
 Inline flags compose into the patch body. --file is an escape hatch when you
 need fields not covered by the inline flags. When both are provided, inline
-flags override values from --file.`)
+flags override values from --file.
+
+Household MECE rule: a couple raising children is \`couple_with_kids\`, not
+\`couple_no_kids\`. \`single\` means lives alone with no partner, roommates,
+parents, or children sharing the household.
+
+\`--accessibility-profile\` accepts either an inline JSON string OR a path to
+a JSON file. An empty object \`{}\` means "no accessibility configuration
+declared". When non-empty, \`version\` is required and must be \`"1.0"\`.
+Schema: https://ishlabs.io/spec/accessibility-profile-schema.v1.json`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             let body = {};
@@ -331,12 +352,23 @@ flags override values from --file.`)
                 body.gender = opts.gender;
             if (opts.dateOfBirth !== undefined)
                 body.date_of_birth = opts.dateOfBirth;
-            if (opts.techSavviness !== undefined) {
-                const n = parseInt(opts.techSavviness, 10);
-                if (Number.isNaN(n)) {
-                    throw new Error("--tech-savviness must be an integer.");
-                }
-                body.tech_savviness = n;
+            if (opts.educationLevel !== undefined) {
+                body.education_level = assertEnumValue(opts.educationLevel, EDUCATION_LEVELS, "--education-level");
+            }
+            if (opts.household !== undefined) {
+                body.household = assertEnumValue(opts.household, HOUSEHOLDS, "--household");
+            }
+            if (opts.localeType !== undefined) {
+                body.locale_type = assertEnumValue(opts.localeType, LOCALE_TYPES, "--locale-type");
+            }
+            if (opts.incomeLevel !== undefined) {
+                body.income_level = assertEnumValue(opts.incomeLevel, INCOME_LEVELS, "--income-level");
+            }
+            if (opts.employmentStatus !== undefined) {
+                body.employment_status = assertEnumValue(opts.employmentStatus, EMPLOYMENT_STATUSES, "--employment-status");
+            }
+            if (opts.accessibilityProfile !== undefined) {
+                body.accessibility_profile = parseAccessibilityProfileFlag(opts.accessibilityProfile);
             }
             if (Object.keys(body).length === 0) {
                 throw new Error("Nothing to update. Provide --file or at least one inline flag (e.g. --bio).");
@@ -377,3 +409,37 @@ function tryResolveSourceAlias(value) {
         return undefined;
     }
 }
+/**
+ * Resolve `--accessibility-profile` from either an inline JSON string or a
+ * filesystem path, then validate against the v1.0 schema. Returns the
+ * canonical object (an empty `{}` means "no accessibility configuration").
+ */
+function parseAccessibilityProfileFlag(raw) {
+    const trimmed = raw.trim();
+    let parsed;
+    const looksLikeJson = trimmed.startsWith("{") || trimmed.startsWith("[");
+    if (looksLikeJson) {
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (e) {
+            throw new Error(`Invalid --accessibility-profile: JSON parse failed (${e.message}).`);
+        }
+    }
+    else {
+        let content;
+        try {
+            content = fs.readFileSync(trimmed, "utf-8");
+        }
+        catch {
+            throw new Error(`Invalid --accessibility-profile: "${trimmed}" is neither inline JSON (must start with "{") nor a readable file.`);
+        }
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            throw new Error(`Invalid --accessibility-profile: file "${trimmed}" is not valid JSON (${e.message}).`);
+        }
+    }
+    return validateAccessibilityProfile(parsed);
+}

package/dist/commands/source.js

@@ -8,6 +8,7 @@
  */
 import { withClient, resolveWorkspace } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { normalizeEnumValue } from "../lib/enums.js";
 import { formatAudienceSource, output } from "../lib/output.js";
 import { inferSourceKind, uploadAndProcessSource, } from "../lib/profile-sources.js";
 const VALID_KINDS = ["text_file", "audio", "image"];
@@ -27,7 +28,7 @@ Concept pages: ish docs get-page concepts/source
         .description("Upload a file as an audience source and wait for processing")
         .argument("<file>", "Local file path (transcript, audio, image, PDF, etc.)")
         .option("--workspace <id>", "Workspace (product) ID; falls back to active workspace")
-        .option("--kind <kind>", "Source kind: text_file | audio | image (auto-detected if omitted)")
+        .option("--kind <kind>", "Source kind: text_file | audio | image (auto-detected if omitted; hyphen/underscore variants accepted)")
         .option("--description <text>", "Context note attached to the source (max 500 chars)")
         .option("--diarize", "Apply speaker diarization to audio sources (silently ignored for text/image)")
         .option("--no-wait", "Don't poll until terminal status — return after confirm")
@@ -42,10 +43,11 @@ Examples:
             const productId = resolveWorkspace(opts.workspace);
             let kind;
             if (opts.kind) {
-                if (!VALID_KINDS.includes(opts.kind)) {
-                    throw new Error(`Invalid --kind "${opts.kind}". Valid: ${VALID_KINDS.join(", ")}`);
+                const normalized = normalizeEnumValue(opts.kind, VALID_KINDS);
+                if (normalized === null) {
+                    throw new Error(`Invalid --kind "${opts.kind}". Valid: ${VALID_KINDS.join(", ")} (hyphen/underscore variants accepted).`);
                 }
-                kind = opts.kind;
+                kind = normalized;
             }
             else {
                 kind = inferSourceKind(file);

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

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