@ishlabs/cli 0.8.1 → 0.8.2

package/dist/commands/ask.js

@@ -0,0 +1,722 @@
+/**
+ * ish ask — Create and run asks (multi-round surveys with variants).
+ */
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveAsk, collectRepeatable, parseWaitTimeout, resolveAudienceProfileIds, addAudienceFilterFlags, } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { loadConfig, saveConfig } from "../config.js";
+import { formatAskList, formatAskDetail, formatRoundDetail, formatAskResults, output, } from "../lib/output.js";
+import { parseVariantInputs, uploadAndBuildVariants, } from "../lib/ask-variants.js";
+import { loadQuestionsManifest } from "../lib/ask-questions.js";
+const POLL_INTERVAL_MS = 5_000;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Map raw Commander opts (with `allSimulatable`) to the shared AudienceFilterOpts shape. */
+function audienceFlags(opts) {
+    return {
+        profile: opts.profile,
+        sample: opts.sample,
+        all: opts.allSimulatable,
+        search: opts.search,
+        gender: opts.gender,
+        country: opts.country,
+        minAge: opts.minAge,
+        maxAge: opts.maxAge,
+        visibility: opts.visibility,
+    };
+}
+function truncate60(s) {
+    return s.length > 60 ? s.slice(0, 57) + "..." : s;
+}
+/**
+ * Pick the ask id to operate on. Both forms are supported:
+ *   - positional `[id]`
+ *   - `--ask <id>` flag
+ * If both are passed and disagree, --ask wins and a stderr warning is emitted.
+ */
+function pickAskRef(positional, flag) {
+    if (flag && positional && flag !== positional) {
+        process.stderr.write(`Warning: both [id] (${positional}) and --ask (${flag}) provided; using --ask.\n`);
+    }
+    return flag ?? positional;
+}
+function getRoundByIndexOrId(ask, ref) {
+    const rounds = ask.rounds ?? [];
+    if (typeof ref === "number") {
+        const r = rounds.find((x) => x.order_index === ref - 1);
+        if (!r)
+            throw new Error(`Ask has no round ${ref}.`);
+        return r;
+    }
+    // String — try numeric first, else treat as round id (UUID or alias).
+    const asNum = parseInt(ref, 10);
+    if (!Number.isNaN(asNum) && /^\d+$/.test(ref)) {
+        return getRoundByIndexOrId(ask, asNum);
+    }
+    const rid = resolveId(ref);
+    const r = rounds.find((x) => x.id === rid);
+    if (!r)
+        throw new Error(`Ask has no round with id ${ref}.`);
+    return r;
+}
+async function pollUntilRoundDone(client, askId, roundIndex, timeoutMs, quiet) {
+    const start = Date.now();
+    let lastReported = "";
+    while (true) {
+        const ask = await client.get(`/asks/${askId}`);
+        const round = ask.rounds?.find((r) => r.order_index === roundIndex);
+        if (!round) {
+            throw new Error(`Round at order_index ${roundIndex} not found while waiting.`);
+        }
+        const responses = round.responses ?? [];
+        const completed = responses.filter((r) => r.status === "completed").length;
+        const errored = responses.filter((r) => r.status === "errored").length;
+        const status = `${round.status} · ${completed}/${responses.length} done${errored > 0 ? `, ${errored} errored` : ""}`;
+        if (!quiet && status !== lastReported) {
+            process.stderr.write(`  ${status}\n`);
+            lastReported = status;
+        }
+        if (round.status === "completed" || round.status === "errored") {
+            return ask;
+        }
+        if (Date.now() - start > timeoutMs) {
+            throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for round ${roundIndex + 1}. ` +
+                `Run \`ish ask get <ask-id>\` to check status.`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+}
+async function buildRoundInput(client, productId, opts, quiet) {
+    const parsed = parseVariantInputs({ variant: opts.variant, variants: opts.variants });
+    if (opts.wantsPick && parsed.length < 2) {
+        throw new Error("--wants-pick requires at least 2 variants.");
+    }
+    if (opts.wantsRatings && parsed.length < 1) {
+        throw new Error("--wants-ratings requires at least 1 variant.");
+    }
+    const variants = await uploadAndBuildVariants(client, productId, parsed, { quiet });
+    const questions = opts.questions
+        ? loadQuestionsManifest(opts.questions)
+        : undefined;
+    const round = {
+        prompt: opts.prompt,
+        variants,
+        wants_pick: !!opts.wantsPick,
+        wants_ratings: !!opts.wantsRatings,
+    };
+    if (questions)
+        round.questions = questions;
+    return round;
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+export function registerAskCommands(program) {
+    const ask = program
+        .command("ask")
+        .description("Create and run asks — quick variant comparisons with an audience")
+        .addHelpText("after", `
+An ask is a lightweight reaction artifact. Audience is fixed at creation; up to 5 rounds per ask.
+Reach for an ask for tagline/image/copy comparisons; reach for a study when the tester must do something.
+
+Concept pages: ish docs get-page concepts/ask
+                ish docs get-page concepts/round
+                ish docs get-page concepts/run-verbs`);
+    // ---- run ----------------------------------------------------------------
+    // Smart wrapper: --new creates a new ask + first round (like `ask create`);
+    // otherwise appends a round to the active or specified ask (like `ask add-round`).
+    const askRun = ask
+        .command("run")
+        .description("Run an ask — append a round to the active ask, or `--new` to create a fresh ask")
+        .argument("[id]", "Ask alias or UUID to append to (defaults to active ask; ignored with --new)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--new", "Create a new ask instead of appending a round")
+        .option("--name <name>", "Ask name (with --new; auto-generated if omitted)")
+        .option("--description <description>", "Ask description (with --new only)")
+        .option("--workspace <id>", "Workspace ID (with --new only)")
+        .requiredOption("--prompt <prompt>", "Round prompt — what testers respond to")
+        .option("--variant <kind:value>", "Variant: text:\"...\", ./file.png, image:./file.png, ./file.png::label=B (repeatable)", collectRepeatable, [])
+        .option("--variants <file.json>", "JSON manifest of variants (alternative to --variant)")
+        .option("--wants-pick", "Each tester picks a favourite variant (compatible with --wants-ratings; can be set together).")
+        .option("--wants-ratings", "Each tester rates every variant 1–5 (compatible with --wants-pick; can be set together). If neither is set, testers leave a free-form comment only.")
+        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"open_ended"|"slider"|"choice"|"likert"}]`)
+        .option("--language <code>", "2-letter language code (with --new only)", "en");
+    addAudienceFilterFlags(askRun, {
+        allFlagName: "--all-simulatable",
+        allFlagDescription: "Use every simulatable AI profile matching the filters (with --new only)",
+    })
+        .option("--wait", "Wait until the round completes (or errors)")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
+        .addHelpText("after", `
+Examples:
+  # Append a round to the active ask:
+  $ ish ask run --prompt "And now which?" --variant text:"X" --variant text:"Y" --wait
+
+  # Append to a specific ask:
+  $ ish ask run a-6ec --prompt "Round 2" --variant text:"A" --variant text:"B"
+
+  # Create a fresh ask with round 1, sampled from a demographic:
+  $ ish ask run --new --name "tagline AB" \\
+      --prompt "Which sounds better?" \\
+      --variant text:"Short and punchy." \\
+      --variant text:"A longer, descriptive line." \\
+      --country SE --min-age 35 --max-age 50 --sample 10 --wants-pick --wait
+`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const pickedId = pickAskRef(id, opts.ask);
+            if (opts.new) {
+                if (pickedId) {
+                    throw new Error("Cannot pass an ask id together with --new. Drop the id, or drop --new to append a round.");
+                }
+                const wid = resolveWorkspace(opts.workspace);
+                const testerIds = await resolveAudienceProfileIds(client, wid, audienceFlags(opts), { requireSimulatable: true, allFlagName: "--all-simulatable" });
+                const round = await buildRoundInput(client, wid, opts, !!globals.quiet);
+                const askName = opts.name || `CLI ${new Date().toISOString().slice(0, 16)}`;
+                const body = {
+                    name: askName,
+                    ...(opts.description !== undefined && { description: opts.description }),
+                    language: opts.language,
+                    tester_profile_ids: testerIds,
+                    first_round: round,
+                };
+                let data = await client.post(`/products/${wid}/asks`, body, { timeout: 120_000 });
+                if (data.id) {
+                    const config = loadConfig();
+                    config.ask = data.id;
+                    saveConfig(config);
+                }
+                if (opts.wait) {
+                    const timeoutMs = parseWaitTimeout(opts.timeout);
+                    data = await pollUntilRoundDone(client, data.id, 0, timeoutMs, !!globals.quiet);
+                }
+                const result = data;
+                if (result.id)
+                    result.alias = tagAlias(ALIAS_PREFIX.ask, String(result.id));
+                formatAskDetail(result, globals.json);
+                if (!globals.json && data.id) {
+                    const url = getWebUrl(globals, `/${wid}/asks/${data.id}`);
+                    process.stderr.write(`\n  ${terminalLink(url, "Open in browser ↗")}\n\n`);
+                }
+                return;
+            }
+            // Append-round path — reject audience/creation flags that have no effect here
+            const appendAudienceSet = (opts.profile && opts.profile.length > 0)
+                || opts.sample !== undefined
+                || opts.allSimulatable
+                || opts.search
+                || (opts.gender && opts.gender.length > 0)
+                || (opts.country && opts.country.length > 0)
+                || opts.minAge
+                || opts.maxAge
+                || opts.visibility;
+            if (opts.name || opts.description || opts.workspace || appendAudienceSet) {
+                throw new Error("Audience and ask-creation flags (--name, --description, --workspace, --profile, --sample, --all-simulatable, --country, --gender, --min-age, --max-age, --search, --visibility) are only valid with --new. " +
+                    "Drop them to append a round, or add --new to create a fresh ask.");
+            }
+            let aid;
+            try {
+                aid = resolveAsk(pickedId);
+            }
+            catch {
+                throw new Error("No active ask. Use `ish ask use <id>`, pass an ask id as an argument, or `--new` to create a fresh ask.");
+            }
+            const ask = await client.get(`/asks/${aid}`);
+            const round = await buildRoundInput(client, ask.product_id, opts, !!globals.quiet);
+            const created = await client.post(`/asks/${aid}/rounds`, round);
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                await pollUntilRoundDone(client, aid, created.order_index, timeoutMs, !!globals.quiet);
+                const refreshed = await client.get(`/asks/${aid}`);
+                const target = refreshed.rounds.find((r) => r.id === created.id);
+                if (target) {
+                    formatRoundDetail(target, globals.json);
+                    return;
+                }
+            }
+            formatRoundDetail(created, globals.json);
+        });
+    });
+    // ---- list ---------------------------------------------------------------
+    ask
+        .command("list")
+        .description("List asks for a workspace")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--archived", "Include archived asks alongside active ones (default: active only).")
+        .addHelpText("after", "\nExamples:\n  $ ish ask list --workspace w-6ec\n  $ ish ask list --workspace w-6ec --json")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const wid = resolveWorkspace(opts.workspace);
+            const data = await client.get(`/products/${wid}/asks`);
+            const filtered = opts.archived ? data : data.filter((a) => !a.is_archived);
+            // Enrich each item with description and first_round_prompt (truncated to 60 chars)
+            // so listings with duplicate names can be disambiguated. The list endpoint
+            // doesn't return rounds, so fetch them in parallel.
+            const enriched = await Promise.all(filtered.map(async (item) => {
+                let firstRoundPrompt = null;
+                try {
+                    const detail = await client.get(`/asks/${item.id}`);
+                    const first = (detail.rounds ?? []).find((r) => r.order_index === 0);
+                    if (first?.prompt)
+                        firstRoundPrompt = truncate60(first.prompt);
+                }
+                catch {
+                    // Best-effort: leave first_round_prompt as null on fetch failure.
+                }
+                const out = item;
+                return {
+                    ...out,
+                    description: out.description ? truncate60(String(out.description)) : null,
+                    first_round_prompt: firstRoundPrompt,
+                };
+            }));
+            formatAskList(enriched, globals.json);
+        });
+    });
+    // ---- create -------------------------------------------------------------
+    const askCreate = ask
+        .command("create")
+        .description("Create a new ask with a first round and dispatch to the audience")
+        .option("--workspace <id>", "Workspace ID")
+        .requiredOption("--name <name>", "Ask name")
+        .option("--description <description>", "Ask description")
+        .requiredOption("--prompt <prompt>", "Round prompt — what testers respond to")
+        .option("--variant <kind:value>", "Variant: text:\"...\", ./file.png, image:./file.png, ./file.png::label=B (repeatable)", collectRepeatable, [])
+        .option("--variants <file.json>", "JSON manifest of variants (alternative to --variant)")
+        .option("--wants-pick", "Each tester picks a favourite variant (compatible with --wants-ratings; can be set together).")
+        .option("--wants-ratings", "Each tester rates every variant 1–5 (compatible with --wants-pick; can be set together). If neither is set, testers leave a free-form comment only.")
+        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"open_ended"|"slider"|"choice"|"likert"}]`)
+        .option("--language <code>", "2-letter language code", "en");
+    addAudienceFilterFlags(askCreate, {
+        allFlagName: "--all-simulatable",
+        allFlagDescription: "Use every simulatable AI profile matching the filters",
+    })
+        .option("--wait", "Wait until the first round completes (or errors)")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
+        .addHelpText("after", `
+Examples:
+  # Two-text comparison, sample 30 testers, wait for results:
+  $ ish ask create --workspace w-6ec --name "tagline AB" \\
+      --prompt "Which sounds better?" \\
+      --variant text:"Short and punchy." \\
+      --variant text:"A longer, descriptive line." \\
+      --sample 30 --wants-pick --wait
+
+  # Demographic-filtered sample (Swedish profiles aged 35–50):
+  $ ish ask create --workspace w-6ec --name "SE 35-50" \\
+      --prompt "Which sounds better?" \\
+      --variant text:"A" --variant text:"B" \\
+      --country SE --min-age 35 --max-age 50 --sample 10 --wants-pick
+
+  # Image comparison from files with explicit profiles and ratings:
+  $ ish ask create --workspace w-6ec --name "hero shots" \\
+      --prompt "Which feels premium?" \\
+      --variant image:./hero-a.png::label=A \\
+      --variant image:./hero-b.png::label=B \\
+      --profile tp-d4e,tp-a17 --wants-ratings
+
+  # Text from a markdown file + JSON questionnaire:
+  $ ish ask create --workspace w-6ec --name "newsletter" \\
+      --prompt "Would you read this?" \\
+      --variant text:@./body.md \\
+      --questions ./questions.json --sample 30
+
+Minimal --questions JSON (server keys: "question" + "type"):
+  [
+    { "question": "What stood out?", "type": "open_ended" },
+    { "question": "Rate it 1-5", "type": "slider" }
+  ]
+`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const wid = resolveWorkspace(opts.workspace);
+            const testerIds = await resolveAudienceProfileIds(client, wid, audienceFlags(opts), { requireSimulatable: true, allFlagName: "--all-simulatable" });
+            const round = await buildRoundInput(client, wid, opts, !!globals.quiet);
+            const body = {
+                name: opts.name,
+                ...(opts.description !== undefined && { description: opts.description }),
+                language: opts.language,
+                tester_profile_ids: testerIds,
+                first_round: round,
+            };
+            let data = await client.post(`/products/${wid}/asks`, body);
+            if (data.id) {
+                const config = loadConfig();
+                config.ask = data.id;
+                saveConfig(config);
+            }
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                data = await pollUntilRoundDone(client, data.id, 0, timeoutMs, !!globals.quiet);
+            }
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.ask, String(result.id));
+            formatAskDetail(result, globals.json);
+            if (!globals.json && data.id) {
+                const url = getWebUrl(globals, `/${wid}/asks/${data.id}`);
+                process.stderr.write(`\n  ${terminalLink(url, "Open in browser ↗")}\n\n`);
+            }
+        });
+    });
+    // ---- get ----------------------------------------------------------------
+    ask
+        .command("get")
+        .description("Get full ask detail including rounds and responses")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask from `ish ask use`)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--round <n>", "Show only round N (1-indexed)")
+        .addHelpText("after", "\nExamples:\n  $ ish ask get a-6ec\n  $ ish ask get a-6ec --round 2 --json")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const data = await client.get(`/asks/${aid}`);
+            if (opts.round !== undefined) {
+                const target = parseInt(opts.round, 10);
+                if (Number.isNaN(target) || target <= 0) {
+                    throw new Error(`--round must be a positive integer.`);
+                }
+                const round = getRoundByIndexOrId(data, target);
+                formatRoundDetail(round, globals.json);
+                return;
+            }
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.ask, String(result.id));
+            formatAskDetail(result, globals.json);
+            if (!globals.json && data.product_id) {
+                const url = getWebUrl(globals, `/${data.product_id}/asks/${aid}`);
+                process.stderr.write(`\n  ${terminalLink(url, "Open in browser ↗")}\n\n`);
+            }
+        });
+    });
+    // ---- results ------------------------------------------------------------
+    ask
+        .command("results")
+        .description("Show aggregated results (picks, mean ratings, comments, summary)")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--round <n>", "Show only round N (1-indexed; default: all rounds)")
+        .addHelpText("after", "\nExamples:\n  $ ish ask results a-6ec\n  $ ish ask results a-6ec --round 1 --json")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const data = await client.get(`/asks/${aid}`);
+            const target = opts.round !== undefined ? parseInt(opts.round, 10) : undefined;
+            if (target !== undefined && (Number.isNaN(target) || target <= 0)) {
+                throw new Error(`--round must be a positive integer.`);
+            }
+            formatAskResults(data, globals.json, target);
+        });
+    });
+    // ---- wait ---------------------------------------------------------------
+    ask
+        .command("wait")
+        .description("Poll until a round is completed (or errored)")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--round <n>", "Round number to wait for (1-indexed; default: last round)")
+        .option("--timeout <s>", "Max seconds to wait (default 300)")
+        .addHelpText("after", "\nExamples:\n  $ ish ask wait a-6ec\n  $ ish ask wait a-6ec --round 2 --timeout 600")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const initial = await client.get(`/asks/${aid}`);
+            if (!initial.rounds || initial.rounds.length === 0) {
+                throw new Error("Ask has no rounds to wait for.");
+            }
+            let targetIdx;
+            if (opts.round !== undefined) {
+                const n = parseInt(opts.round, 10);
+                if (Number.isNaN(n) || n <= 0)
+                    throw new Error(`--round must be a positive integer.`);
+                targetIdx = n - 1;
+            }
+            else {
+                targetIdx = Math.max(...initial.rounds.map((r) => r.order_index));
+            }
+            const timeoutMs = parseWaitTimeout(opts.timeout);
+            const data = await pollUntilRoundDone(client, aid, targetIdx, timeoutMs, !!globals.quiet);
+            if (!globals.json || globals.verbose) {
+                formatAskDetail(data, globals.json);
+                return;
+            }
+            const round = data.rounds.find((r) => r.order_index === targetIdx);
+            const responses = round?.responses ?? [];
+            const completed = responses.filter((r) => r.status === "completed").length;
+            const errored = responses.filter((r) => r.status === "errored").length;
+            output({
+                id: data.id,
+                alias: tagAlias(ALIAS_PREFIX.ask, data.id),
+                name: data.name,
+                round: round
+                    ? {
+                        round_number: round.order_index + 1,
+                        status: round.status,
+                        completed_at: round.completed_at ?? null,
+                        response_count: responses.length,
+                        completed_count: completed,
+                        errored_count: errored,
+                    }
+                    : null,
+            }, globals.json);
+        });
+    });
+    // ---- add-round ----------------------------------------------------------
+    ask
+        .command("add-round")
+        .description("Append a new round to an existing ask (max 5 per ask)")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .requiredOption("--prompt <prompt>", "Round prompt")
+        .option("--variant <kind:value>", "Variant flag (repeatable; same syntax as `ask create`)", collectRepeatable, [])
+        .option("--variants <file.json>", "JSON manifest of variants")
+        .option("--wants-pick", "Each tester picks a favourite variant (compatible with --wants-ratings; can be set together).")
+        .option("--wants-ratings", "Each tester rates every variant 1–5 (compatible with --wants-pick; can be set together). If neither is set, testers leave a free-form comment only.")
+        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"open_ended"|"slider"|"choice"|"likert"}]`)
+        .option("--wait", "Wait until the new round completes")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
+        .addHelpText("after", "\nExamples:\n  $ ish ask add-round a-6ec --prompt \"And now?\" --variant text:\"Hello\" --variant text:\"Hi\" --wait")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const ask = await client.get(`/asks/${aid}`);
+            const round = await buildRoundInput(client, ask.product_id, opts, !!globals.quiet);
+            const created = await client.post(`/asks/${aid}/rounds`, round);
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                await pollUntilRoundDone(client, aid, created.order_index, timeoutMs, !!globals.quiet);
+                const refreshed = await client.get(`/asks/${aid}`);
+                const target = refreshed.rounds.find((r) => r.id === created.id);
+                if (target) {
+                    formatRoundDetail(target, globals.json);
+                    return;
+                }
+            }
+            formatRoundDetail(created, globals.json);
+        });
+    });
+    // ---- add-questions ------------------------------------------------------
+    ask
+        .command("add-questions")
+        .description("Append questionnaire questions to a round (resets responses, re-dispatches)")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .requiredOption("--round <n|round-id>", "Round number (1-indexed) or round id/alias")
+        .requiredOption("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"open_ended"|"slider"|"choice"|"likert"}]`)
+        .addHelpText("after", `
+Examples:
+  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json
+
+Minimal valid --questions JSON:
+  [
+    { "question": "What stood out?", "type": "open_ended" },
+    { "question": "Rate it 1-5", "type": "slider" }
+  ]
+
+Note: the server requires the key "question" (not "text"). Valid type values:
+open_ended, slider, choice, likert.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const ask = await client.get(`/asks/${aid}`);
+            const round = getRoundByIndexOrId(ask, opts.round);
+            const questions = loadQuestionsManifest(opts.questions);
+            const body = { questions };
+            const updated = await client.post(`/asks/${aid}/rounds/${round.id}/questions`, body);
+            if (!globals.json || globals.verbose) {
+                formatRoundDetail(updated, globals.json);
+                return;
+            }
+            output({
+                id: aid,
+                alias: tagAlias(ALIAS_PREFIX.ask, aid),
+                round: {
+                    round_number: updated.order_index + 1,
+                    status: updated.status,
+                    question_count: (updated.questions ?? []).length,
+                },
+            }, globals.json);
+        });
+    });
+    // ---- add-testers --------------------------------------------------------
+    const askAddTesters = ask
+        .command("add-testers")
+        .description("Add testers to an existing ask (optionally backfill prior rounds)")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .requiredOption("--round <n|round-id>", "Round to add testers to (required)");
+    addAudienceFilterFlags(askAddTesters, {
+        allFlagName: "--all-simulatable",
+        allFlagDescription: "Add every simulatable AI profile matching the filters not already in the audience",
+    })
+        .option("--backfill", "Backfill prior rounds in order for new testers")
+        .addHelpText("after", `
+Examples:
+  $ ish ask add-testers a-6ec --round 1 --sample 5
+  $ ish ask add-testers a-6ec --round 1 --country GB --sample 3 --backfill
+  $ ish ask add-testers a-6ec --round 2 --profile tp-d4e,tp-a17 --backfill`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const askDetail = await client.get(`/asks/${aid}`);
+            const round = getRoundByIndexOrId(askDetail, opts.round);
+            const existingProfileIds = new Set((askDetail.testers ?? [])
+                .map((t) => (t.tester_profile_id ? String(t.tester_profile_id) : ""))
+                .filter(Boolean));
+            const candidateIds = await resolveAudienceProfileIds(client, askDetail.product_id, audienceFlags(opts), {
+                requireSimulatable: true,
+                allFlagName: "--all-simulatable",
+                excludeProfileIds: existingProfileIds,
+            });
+            const body = {
+                tester_profile_ids: candidateIds,
+                round_id: round.id,
+                backfill_prior_rounds: !!opts.backfill,
+            };
+            const data = await client.post(`/asks/${aid}/testers`, body);
+            if (!globals.json || globals.verbose) {
+                formatAskDetail(data, globals.json);
+                return;
+            }
+            const targetRound = data.rounds.find((r) => r.id === round.id);
+            const responses = targetRound?.responses ?? [];
+            output({
+                id: data.id,
+                alias: tagAlias(ALIAS_PREFIX.ask, data.id),
+                name: data.name,
+                round: {
+                    round_number: (targetRound?.order_index ?? round.order_index) + 1,
+                    tester_count: (data.testers ?? []).length,
+                    response_count: responses.length,
+                    new_tester_count: candidateIds.length,
+                },
+            }, globals.json);
+        });
+    });
+    // ---- update -------------------------------------------------------------
+    ask
+        .command("update")
+        .description("Update an ask's name or description")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--name <name>", "New name")
+        .option("--description <description>", "New description")
+        .addHelpText("after", "\nExamples:\n  $ ish ask update a-6ec --name \"renamed\"")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const body = {};
+            if (opts.name !== undefined)
+                body.name = opts.name;
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (Object.keys(body).length === 0) {
+                throw new Error("Pass --name or --description.");
+            }
+            const data = await client.patch(`/asks/${aid}`, body);
+            if (!globals.json || globals.verbose) {
+                formatAskDetail(data, globals.json);
+                return;
+            }
+            output({
+                id: data.id,
+                alias: tagAlias(ALIAS_PREFIX.ask, data.id),
+                name: data.name,
+                description: data.description ?? null,
+                updated_at: data.updated_at,
+            }, globals.json);
+        });
+    });
+    // ---- archive / unarchive ------------------------------------------------
+    ask
+        .command("archive")
+        .description("Archive an ask (hides it from default list)")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const data = await client.patch(`/asks/${aid}`, { is_archived: true });
+            if (!globals.json || globals.verbose) {
+                formatAskDetail(data, globals.json);
+                return;
+            }
+            output({
+                id: data.id,
+                alias: tagAlias(ALIAS_PREFIX.ask, data.id),
+                name: data.name,
+                is_archived: data.is_archived,
+                updated_at: data.updated_at,
+            }, globals.json);
+        });
+    });
+    ask
+        .command("unarchive")
+        .description("Restore an archived ask")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const data = await client.patch(`/asks/${aid}`, { is_archived: false });
+            if (!globals.json || globals.verbose) {
+                formatAskDetail(data, globals.json);
+                return;
+            }
+            output({
+                id: data.id,
+                alias: tagAlias(ALIAS_PREFIX.ask, data.id),
+                name: data.name,
+                is_archived: data.is_archived,
+                updated_at: data.updated_at,
+            }, globals.json);
+        });
+    });
+    // ---- delete -------------------------------------------------------------
+    ask
+        .command("delete")
+        .description("Delete an ask and all its rounds, responses, and audience")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .addHelpText("after", "\nExamples:\n  $ ish ask delete a-6ec")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            await client.del(`/asks/${aid}`);
+            // If we just deleted the active ask, clear it from config.
+            const config = loadConfig();
+            if (config.ask === aid) {
+                delete config.ask;
+                saveConfig(config);
+            }
+            output({ message: "Ask deleted" }, globals.json);
+        });
+    });
+    // ---- use ----------------------------------------------------------------
+    ask
+        .command("use")
+        .description("Set the active ask (saved to ~/.ish/config.json)")
+        .argument("[id]", "Ask alias or UUID")
+        .option("--clear", "Remove the active ask from config")
+        .addHelpText("after", "\nExamples:\n  $ ish ask use a-6ec\n  $ ish ask use --clear")
+        .action(async (id, opts, cmd) => {
+        if (opts.clear) {
+            const config = loadConfig();
+            delete config.ask;
+            saveConfig(config);
+            process.stderr.write("Cleared active ask.\n");
+            return;
+        }
+        if (!id)
+            throw new Error("Provide an ask alias or UUID, or use --clear.");
+        await withClient(cmd, async (client) => {
+            const rid = resolveId(id);
+            const data = await client.get(`/asks/${rid}`);
+            const config = loadConfig();
+            config.ask = rid;
+            saveConfig(config);
+            process.stderr.write(`Active ask set to "${data.name || rid}".\n`);
+        });
+    });
+}