@ishlabs/cli 0.13.0 → 0.14.1

package/dist/commands/study.js

@@ -11,6 +11,8 @@ import { VALID_CONTENT_TYPES } from "../lib/types.js";
 import { parseAssignment, loadAssignmentsFile, 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 { attachStudyAnalyzeCommands } from "./study-analyze.js";
@@ -88,8 +90,13 @@ Concept pages: ish docs get-page concepts/study
         .addHelpText("after", "\nExamples:\n  $ ish study list --workspace <id>\n  $ ish study list --workspace <id> --json")
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get(`/products/${resolveWorkspace(opts.workspace)}/studies`);
-            formatStudyList(data, globals.json);
+            const resolvedWs = resolveWorkspace(opts.workspace);
+            const data = await client.get(`/products/${resolvedWs}/studies`);
+            const withUrls = data.map((s) => ({
+                ...s,
+                url: getWebUrl(globals, `/${resolvedWs}/${String(s.id ?? "")}/overview`),
+            }));
+            formatStudyList(withUrls, globals.json);
         });
     });
     study
@@ -107,13 +114,21 @@ Concept pages: ish docs get-page concepts/study
         .option("--questionnaire <path>", "JSON file defining the questionnaire (supports text, slider, likert, single-choice, multiple-choice, number; timing=before|after)")
         .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file. Creates iteration A inline (text modality only)")
         .option("--url <url>", "URL to test. Creates iteration A inline (interactive modality only)")
-        .option("--screen-format <format>", "Screen format for interactive iterations: desktop (default) or mobile_portrait")
+        .option("--screen-format <format>", "Screen format for interactive iterations: desktop (default) or mobile_portrait (hyphen/underscore variants accepted)")
         .option("--content-url <url>", "Public URL of the media file. Creates iteration A inline (video, audio, document modalities). For local files, use the 2-step `iteration create` flow.")
         .option("--image-urls <urls>", "Comma-separated public image URLs. Creates iteration A inline (image modality). For local files, use the 2-step `iteration create` flow.")
         .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 only)")
-        .option("--endpoint-config <file>", "ChatbotEndpointConfig JSON file (or `-` for stdin); embedded directly. Mutually exclusive with --endpoint (chat modality only)")
+        .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.")
         .addHelpText("after", `
 Note: --workspace is optional if set via \`ish workspace use <alias>\`.
 
@@ -229,12 +244,25 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             // exist until after `studies` POST. For local files, agents fall
             // back to the existing 2-step `iteration create` path which uploads
             // 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"]);
+            }
+            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
+                || normalizedChatMode === "tester_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,
             ].filter((f) => f !== null);
             if (inlineMediaFlagsSet.length > 1) {
                 throw new ValidationError(`Pass only one inline-iteration flag: ${inlineMediaFlagsSet.join(", ")}.`, inlineMediaFlagsSet);
@@ -242,6 +270,14 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             if (opts.screenFormat !== undefined && opts.url === undefined) {
                 throw new Error("--screen-format only applies when --url is set (interactive modality).");
             }
+            let normalizedScreenFormat;
+            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]);
+                }
+                normalizedScreenFormat = normalized;
+            }
             // Pattern G.2: --title is metadata, not content. The backend
             // accepts it on text + media modalities (see
             // `buildIterationDetails` in iteration.ts). Reject it only on
@@ -281,7 +317,7 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                         type: "interactive",
                         url: opts.url,
                         platform: "browser",
-                        screen_format: opts.screenFormat || "desktop",
+                        screen_format: normalizedScreenFormat || "desktop",
                     },
                 };
             }
@@ -330,6 +366,9 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 if (opts.modality && opts.modality !== "chat") {
                     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"]);
+                }
                 let endpointConfig;
                 if (opts.endpoint !== undefined) {
                     const epId = resolveId(opts.endpoint);
@@ -355,8 +394,117 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                     name: "A",
                     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: true,
+                    },
+                };
+            }
+            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"]);
+                }
+                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"]);
+                }
+                const audA = (opts.audienceA ?? []).map(resolveId);
+                const audB = (opts.audienceB ?? []).map(resolveId);
+                // Parse + validate role criteria if supplied (JSON or @filepath).
+                const parseCriteria = (raw, flag) => {
+                    if (raw === undefined)
+                        return undefined;
+                    const text = raw.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw;
+                    const trimmed = text.trim();
+                    if (trimmed.length === 0)
+                        return undefined;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(trimmed);
+                    }
+                    catch {
+                        throw new Error(`Invalid ${flag}: expected valid JSON object.`);
+                    }
+                    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                        throw new Error(`Invalid ${flag}: expected a JSON object.`);
+                    }
+                    return validateRoleCriteria(parsed, flag);
+                };
+                let critA;
+                let critB;
+                try {
+                    critA = parseCriteria(opts.roleCriteriaA, "--role-criteria-a");
+                    critB = parseCriteria(opts.roleCriteriaB, "--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 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).");
+                }
+                // 1×N broadcast: canonical "rehearse one side against N
+                // variations" shape. See iteration.ts buildIterationDetails
+                // tester_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.`;
+                }
+                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) {
+                    console.error(broadcastMsg);
+                }
+                const bothExplicit = audA_final.length > 0 && audB_final.length > 0 && !critA && !critB;
+                if (bothExplicit && audA_final.length !== audB_final.length) {
+                    // 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. ` +
+                        `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 Error("tester_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")
+                    : opts.scenarioA;
+                const scenarioB = opts.scenarioB.startsWith("@")
+                    ? readFileSync(opts.scenarioB.slice(1), "utf8")
+                    : opts.scenarioB;
+                if (scenarioA.trim().length === 0 || scenarioB.trim().length === 0) {
+                    throw new Error("--scenario-a and --scenario-b must be non-empty.");
+                }
+                const initiator = (opts.initiatorSide ?? "a").toLowerCase();
+                if (initiator !== "a" && initiator !== "b") {
+                    throw new ValidationError(`Invalid --initiator-side "${opts.initiatorSide}". Expected "a" or "b".`, ["a", "b"]);
+                }
+                const maxTurns = opts.maxTurns ?? 12;
+                inlineIteration = {
+                    name: "A",
+                    details: {
+                        type: "chat",
+                        mode_details: {
+                            mode: "tester_pair",
+                            audience_a: audA_final,
+                            audience_b: audB_final,
+                            scenario_a: scenarioA,
+                            scenario_b: scenarioB,
+                            initiator_side: initiator,
+                            ...(critA && { role_criteria_a: critA }),
+                            ...(critB && { role_criteria_b: critB }),
+                        },
                         max_turns: maxTurns,
                         early_termination: true,
                     },
@@ -391,6 +539,9 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             if (opts.modality === "chat" && inlineIteration) {
                 result.chatbot_endpoint_id = chatbotEndpointId;
             }
+            if (data.id) {
+                result.url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
+            }
             formatStudyDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
@@ -416,6 +567,9 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
+            if (data.id) {
+                result.url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
+            }
             formatStudyDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
@@ -447,6 +601,9 @@ list table layout in human mode.`)
                 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);
                 if (!globals.json && data.product_id) {
                     const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
@@ -455,10 +612,14 @@ list table layout in human mode.`)
                 return;
             }
             const results = await Promise.all(flat.map(async (raw) => {
-                const data = await client.get(`/studies/${resolveId(raw)}`);
+                const rid = resolveId(raw);
+                const data = await client.get(`/studies/${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`);
+                }
                 return r;
             }));
             if (globals.json) {

package/dist/commands/workspace.js

@@ -29,13 +29,44 @@ Concept pages: ish docs get-page concepts/workspace
     });
     workspace
         .command("create")
-        .description("Create a new workspace")
+        .description("Create a new workspace (or reuse an existing one with --ensure)")
         .requiredOption("--name <name>", "Workspace name")
         .option("--description <description>", "Workspace description")
         .option("--base-url <url>", "Default base URL")
-        .addHelpText("after", "\nExamples:\n  $ ish workspace create --name \"My App\" --base-url https://example.com\n  $ ish workspace create --name \"My App\" --json")
+        .option("--ensure", "Idempotent: if a workspace with this exact name already exists in the caller's account, return it instead of creating. Useful on saturated accounts where create would 402/usage_limit_reached.")
+        .addHelpText("after", `
+Examples:
+  $ ish workspace create --name "My App" --base-url https://example.com
+  $ ish workspace create --name "My App" --json
+
+  # Idempotent — returns an existing workspace if --name matches one you own:
+  $ ish workspace create --name "My App" --ensure
+
+With --ensure the response includes a top-level \`reused: true\` flag when an
+existing workspace was returned. On creation, \`reused: false\`.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            if (opts.ensure) {
+                const existing = await client.get("/products");
+                const match = Array.isArray(existing)
+                    ? existing.find((w) => w.name === opts.name)
+                    : undefined;
+                if (match) {
+                    const result = match;
+                    if (result.id)
+                        result.alias = tagAlias(ALIAS_PREFIX.workspace, String(result.id));
+                    result.reused = true;
+                    formatWorkspaceDetail(result, globals.json, { writePath: true });
+                    if (!globals.json) {
+                        console.error(`Reusing existing workspace "${opts.name}".`);
+                        if (match.id) {
+                            const url = getWebUrl(globals, `/${match.id}`);
+                            console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                        }
+                    }
+                    return;
+                }
+            }
             const body = {
                 name: opts.name,
                 ...(opts.description !== undefined && { description: opts.description }),
@@ -45,6 +76,8 @@ Concept pages: ish docs get-page concepts/workspace
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.workspace, String(result.id));
+            if (opts.ensure)
+                result.reused = false;
             formatWorkspaceDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${data.id}`);

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

@@ -0,0 +1,12 @@
+/**
+ * Client-side validator for the AccessibilityProfile v1.0 JSONB shape on
+ * TesterProfile.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
+ * `"1.0"`.
+ *
+ * Surfacing validation here is cheaper than a server round-trip and gives
+ * agents the same exit-2 error contract they get for other CLI inputs.
+ */
+export declare function validateAccessibilityProfile(raw: unknown): Record<string, unknown>;

package/dist/lib/accessibility-profile.js

@@ -0,0 +1,136 @@
+/**
+ * Client-side validator for the AccessibilityProfile v1.0 JSONB shape on
+ * TesterProfile.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
+ * `"1.0"`.
+ *
+ * Surfacing validation here is cheaper than a server round-trip and gives
+ * agents the same exit-2 error contract they get for other CLI inputs.
+ */
+const SPEC_URL = "https://ishlabs.io/spec/accessibility-profile-schema.v1.json";
+const TEXT_SIZE = new Set(["default", "large", "xl", "xxl"]);
+const CONTRAST_PREFERENCE = new Set(["default", "more", "less"]);
+const COLOR_SCHEME = new Set(["no_preference", "light", "dark"]);
+const COLOR_FILTER = new Set([
+    "none",
+    "deuteranopia",
+    "protanopia",
+    "tritanopia",
+    "grayscale",
+]);
+const VISUAL_BOOLEANS = new Set([
+    "reduce_transparency",
+    "forced_colors",
+    "inverted_colors",
+    "uses_screen_reader",
+    "uses_magnifier",
+    "dyslexia_friendly_font",
+]);
+const VISUAL_STRINGS = {
+    text_size: TEXT_SIZE,
+    contrast_preference: CONTRAST_PREFERENCE,
+    color_scheme: COLOR_SCHEME,
+    color_filter: COLOR_FILTER,
+};
+const AUDITORY_BOOLEANS = new Set([
+    "captions_required",
+    "audio_descriptions_required",
+    "mono_audio",
+    "visual_alerts_required",
+    "uses_hearing_aid",
+]);
+const MOTOR_BOOLEANS = new Set([
+    "uses_switch_control",
+    "uses_voice_control",
+    "uses_eye_tracking",
+    "needs_larger_tap_targets",
+    "extended_interaction_timeouts",
+    "avoid_hover_interactions",
+    "sticky_keys",
+]);
+const COGNITIVE_BOOLEANS = new Set([
+    "reduce_motion",
+    "simple_language_preferred",
+    "extra_reading_time",
+    "avoid_flashing",
+    "predictable_navigation",
+]);
+const DATA_BOOLEANS = new Set(["reduce_data"]);
+const TOP_LEVEL_KEYS = new Set([
+    "version",
+    "visual",
+    "auditory",
+    "motor",
+    "cognitive",
+    "data",
+    "assistive_tech",
+    "notes",
+    "extensions",
+]);
+function err(path, msg) {
+    return new Error(`Invalid --accessibility-profile at ${path}: ${msg}. See ${SPEC_URL}.`);
+}
+function checkGroup(group, path, bools, strs = {}) {
+    if (group === undefined || group === null)
+        return;
+    if (typeof group !== "object" || Array.isArray(group)) {
+        throw err(path, "must be an object");
+    }
+    for (const [key, value] of Object.entries(group)) {
+        if (bools.has(key)) {
+            if (typeof value !== "boolean")
+                throw err(`${path}.${key}`, "must be a boolean");
+            continue;
+        }
+        if (key in strs) {
+            const allowed = strs[key];
+            if (typeof value !== "string" || !allowed.has(value)) {
+                throw err(`${path}.${key}`, `must be one of ${[...allowed].join(", ")}`);
+            }
+            continue;
+        }
+        throw err(`${path}.${key}`, "unknown property");
+    }
+}
+export function validateAccessibilityProfile(raw) {
+    if (raw === undefined || raw === null) {
+        throw err("$", "must be a JSON object");
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw err("$", "must be a JSON object");
+    }
+    const obj = raw;
+    const keys = Object.keys(obj);
+    if (keys.length === 0)
+        return {};
+    for (const key of keys) {
+        if (!TOP_LEVEL_KEYS.has(key)) {
+            throw err(`$.${key}`, "unknown property");
+        }
+    }
+    if (obj.version !== "1.0") {
+        throw err("$.version", 'is required and must be "1.0" when the object is non-empty');
+    }
+    checkGroup(obj.visual, "$.visual", VISUAL_BOOLEANS, VISUAL_STRINGS);
+    checkGroup(obj.auditory, "$.auditory", AUDITORY_BOOLEANS);
+    checkGroup(obj.motor, "$.motor", MOTOR_BOOLEANS);
+    checkGroup(obj.cognitive, "$.cognitive", COGNITIVE_BOOLEANS);
+    checkGroup(obj.data, "$.data", DATA_BOOLEANS);
+    if (obj.assistive_tech !== undefined) {
+        if (!Array.isArray(obj.assistive_tech)
+            || !obj.assistive_tech.every((v) => typeof v === "string")) {
+            throw err("$.assistive_tech", "must be an array of strings");
+        }
+    }
+    if (obj.notes !== undefined && typeof obj.notes !== "string") {
+        throw err("$.notes", "must be a string");
+    }
+    if (obj.extensions !== undefined) {
+        if (typeof obj.extensions !== "object" || obj.extensions === null || Array.isArray(obj.extensions)) {
+            throw err("$.extensions", "must be an object");
+        }
+    }
+    return obj;
+}

package/dist/lib/ask-questions.js

@@ -7,6 +7,7 @@
  */
 import { readFileSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
+import { normalizeEnumValue, QUESTION_TYPES } from "./enums.js";
 export function loadQuestionsManifest(filePath) {
     let raw;
     try {
@@ -30,6 +31,14 @@ export function loadQuestionsManifest(filePath) {
         if (!q || typeof q !== "object" || typeof q.question !== "string" || !q.question.trim()) {
             throw new Error(`questions[${i}].question must be a non-empty string.`);
         }
+        // Fold underscored variants (`single_choice`) back to the canonical
+        // hyphenated form (`single-choice`). Unknown types pass through untouched
+        // so the backend remains the source of truth for shape validation.
+        if (typeof q.type === "string") {
+            const canonical = normalizeEnumValue(q.type, QUESTION_TYPES);
+            if (canonical !== null)
+                q.type = canonical;
+        }
     }
     return parsed;
 }

package/dist/lib/billing.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Credit cost estimators — mirror the backend's billing formulas so the CLI
+ * can surface a pre-dispatch estimate without a network round-trip.
+ *
+ * The numbers here MUST match `ish-backend/app/{media,chat}/billing.py`
+ * and `app/billing/service.py`. If the backend formula changes, update
+ * this file in the same commit, otherwise the CLI will mislead agents.
+ *
+ * Today every modality uses the same shape: `max(1, round(steps / 10))`
+ * per principal (per tester for media/interactive, per conversation for
+ * chat, ×2 for tester-pair). Asks bill flat 1 credit per successful
+ * tester response. These are intentionally per-run estimates; long-term
+ * we'll fetch `GET /billing/rates` and parameterise modalities — see
+ * `reference/credits` docs page.
+ */
+export interface CreditEstimate {
+    /** Upper bound (no early termination). Never claims exactness. */
+    upper_bound: number;
+    /** Stable identifier so agents can branch on shape if the formula evolves. */
+    formula: "media_per_tester" | "chat_solo" | "chat_pair" | "ask_per_response";
+    /** Human-readable breakdown so agents can explain the number to users. */
+    breakdown: string;
+    /** Always "credits" today; reserved for future-proofing (e.g. millicredits). */
+    unit: "credits";
+}
+/** Mirror of `app/media/billing.py::media_credit_cost`. */
+export declare function mediaCreditCost(steps: number): number;
+/** Mirror of `app/chat/billing.py::chat_credit_cost`. */
+export declare function chatCreditCost(turns: number): number;
+/**
+ * Media/interactive run: 1 credit-cost-per-tester × tester count. Modality
+ * doesn't currently affect the rate (interactive == text == video at the
+ * billing layer) — kept as a parameter for forward compatibility.
+ */
+export declare function estimateMediaRun(args: {
+    testerCount: number;
+    maxInteractions: number;
+}): CreditEstimate;
+/** Solo chat (single tester, external chatbot). */
+export declare function estimateChatSolo(args: {
+    testerCount: number;
+    maxTurns: number;
+}): CreditEstimate;
+/** Tester-pair chat: each turn bills both sides, so cost doubles. */
+export declare function estimateChatPair(args: {
+    conversationCount: number;
+    maxTurns: number;
+}): CreditEstimate;
+/**
+ * Ask round: flat 1 credit per successful tester response (charged only
+ * for completed responses; the upper bound assumes everyone completes).
+ */
+export declare function estimateAskRound(args: {
+    testerCount: number;
+}): CreditEstimate;

package/dist/lib/billing.js

@@ -0,0 +1,77 @@
+/**
+ * Credit cost estimators — mirror the backend's billing formulas so the CLI
+ * can surface a pre-dispatch estimate without a network round-trip.
+ *
+ * The numbers here MUST match `ish-backend/app/{media,chat}/billing.py`
+ * and `app/billing/service.py`. If the backend formula changes, update
+ * this file in the same commit, otherwise the CLI will mislead agents.
+ *
+ * Today every modality uses the same shape: `max(1, round(steps / 10))`
+ * per principal (per tester for media/interactive, per conversation for
+ * chat, ×2 for tester-pair). Asks bill flat 1 credit per successful
+ * tester response. These are intentionally per-run estimates; long-term
+ * we'll fetch `GET /billing/rates` and parameterise modalities — see
+ * `reference/credits` docs page.
+ */
+/** Mirror of `app/media/billing.py::media_credit_cost`. */
+export function mediaCreditCost(steps) {
+    if (!Number.isFinite(steps) || steps <= 0)
+        return 1;
+    return Math.max(1, Math.round(steps / 10));
+}
+/** Mirror of `app/chat/billing.py::chat_credit_cost`. */
+export function chatCreditCost(turns) {
+    if (!Number.isFinite(turns) || turns <= 0)
+        return 1;
+    return Math.max(1, Math.round(turns / 10));
+}
+/**
+ * Media/interactive run: 1 credit-cost-per-tester × tester count. Modality
+ * doesn't currently affect the rate (interactive == text == video at the
+ * billing layer) — kept as a parameter for forward compatibility.
+ */
+export function estimateMediaRun(args) {
+    const perTester = mediaCreditCost(args.maxInteractions);
+    const total = Math.max(0, args.testerCount) * perTester;
+    return {
+        upper_bound: total,
+        formula: "media_per_tester",
+        breakdown: `${args.testerCount} tester(s) × max(1, round(${args.maxInteractions} steps / 10)) = ${args.testerCount} × ${perTester} = ${total}`,
+        unit: "credits",
+    };
+}
+/** Solo chat (single tester, external chatbot). */
+export function estimateChatSolo(args) {
+    const perTester = chatCreditCost(args.maxTurns);
+    const total = Math.max(0, args.testerCount) * perTester;
+    return {
+        upper_bound: total,
+        formula: "chat_solo",
+        breakdown: `${args.testerCount} tester(s) × max(1, round(${args.maxTurns} turns / 10)) = ${args.testerCount} × ${perTester} = ${total}`,
+        unit: "credits",
+    };
+}
+/** Tester-pair chat: each turn bills both sides, so cost doubles. */
+export function estimateChatPair(args) {
+    const perSide = chatCreditCost(args.maxTurns);
+    const total = Math.max(0, args.conversationCount) * perSide * 2;
+    return {
+        upper_bound: total,
+        formula: "chat_pair",
+        breakdown: `${args.conversationCount} conv × max(1, round(${args.maxTurns} turns / 10)) × 2 sides = ${args.conversationCount} × ${perSide} × 2 = ${total}`,
+        unit: "credits",
+    };
+}
+/**
+ * Ask round: flat 1 credit per successful tester response (charged only
+ * for completed responses; the upper bound assumes everyone completes).
+ */
+export function estimateAskRound(args) {
+    const total = Math.max(0, args.testerCount);
+    return {
+        upper_bound: total,
+        formula: "ask_per_response",
+        breakdown: `${args.testerCount} tester(s) × 1 credit/response = ${total} (upper bound; only successful responses bill)`,
+        unit: "credits",
+    };
+}