@ishlabs/cli 0.14.1 → 0.15.0

package/dist/commands/profile.js

@@ -7,7 +7,7 @@ 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 { assertEnumValue, EDUCATION_LEVELS, EVIDENCE_SOURCES, 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);
@@ -393,6 +393,242 @@ Schema: https://ishlabs.io/spec/accessibility-profile-schema.v1.json`)
             output({ id: rid, alias: tagAlias(ALIAS_PREFIX.testerProfile, rid), message: "Profile deleted" }, globals.json, { writePath: true });
         });
     });
+    profile
+        .command("suggest-scenarios")
+        .description("Ask the LLM for scenario probes to craft a specific simulated tester")
+        .option("--workspace <id>", "Workspace (product) ID; falls back to active workspace")
+        .option("--context <text>", "What you already know about this tester. Use @path to read from file.")
+        .option("--context-file <path>", "Read --context from a file")
+        .option("--count <n>", "Number of scenarios to return (1-10, default 5)")
+        .option("--previous-answers <json-or-@path>", "Answers already collected this session. Inline JSON, @/path/to.json, or - for stdin. Array of {type, prompt, answer}; max 40.")
+        .option("--already-surfaced <json-or-@path>", "Prompt labels already shown this session, so the LLM avoids paraphrasing them. Inline JSON, @/path, or -. Array of strings; max 40.")
+        .addHelpText("after", `
+Examples:
+  # Bare invocation: 5 scenarios from a free-form context blob
+  $ ish profile suggest-scenarios --context "Mid-career engineer who handles oncall for a Stripe-using fintech"
+
+  # Load context from a file, ask for 3 scenarios
+  $ ish profile suggest-scenarios --context-file ./persona-notes.md --count 3
+
+  # Follow-up probe: skip prompts already shown, build on prior answers
+  $ ish profile suggest-scenarios \\
+      --context "$(cat notes.md)" \\
+      --count 3 \\
+      --already-surfaced '["How do you triage 02:00 pages?"]' \\
+      --previous-answers @./answers.json
+
+  # Capture just the first scenario's type
+  $ ish profile suggest-scenarios --context "..." --count 1 --get scenarios[0].type
+
+The loop: suggest → answer locally → persist via \`ish profile evidence add <id>\` (read back with \`evidence list\`).
+See \`ish docs get-page guides/build-specific-tester\` for the full workflow.`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const productId = resolveWorkspace(opts.workspace);
+            let context;
+            if (opts.context)
+                context = resolveTextContent(opts.context);
+            if (opts.contextFile)
+                context = resolveTextContent(`@${opts.contextFile}`);
+            if (!context) {
+                throw new Error("Provide --context (text or @path) or --context-file.");
+            }
+            const trimmed = context.trim();
+            if (trimmed.length === 0) {
+                throw new Error("--context cannot be empty.");
+            }
+            if (trimmed.length > 20_000) {
+                throw new Error(`--context is ${trimmed.length} chars; backend max is 20000. Trim before retrying.`);
+            }
+            const body = {
+                product_id: productId,
+                context: trimmed,
+            };
+            if (opts.count !== undefined) {
+                const n = parseInt(opts.count, 10);
+                if (Number.isNaN(n) || n < 1 || n > 10) {
+                    throw new Error("--count must be an integer between 1 and 10.");
+                }
+                body.count = n;
+            }
+            if (opts.previousAnswers) {
+                const parsed = await parseJsonFlag(opts.previousAnswers, "--previous-answers");
+                if (!Array.isArray(parsed)) {
+                    throw new Error("--previous-answers must be a JSON array of {type, prompt, answer}.");
+                }
+                if (parsed.length > 40) {
+                    throw new Error(`--previous-answers max 40 entries (got ${parsed.length}).`);
+                }
+                for (let i = 0; i < parsed.length; i++) {
+                    const row = parsed[i];
+                    if (!row || typeof row !== "object") {
+                        throw new Error(`--previous-answers[${i}]: expected object {type, prompt, answer}.`);
+                    }
+                    if (typeof row.type !== "string" || typeof row.prompt !== "string" || typeof row.answer !== "string") {
+                        throw new Error(`--previous-answers[${i}]: missing or non-string {type, prompt, answer}.`);
+                    }
+                    assertEnumValue(row.type, EVIDENCE_SOURCES, `--previous-answers[${i}].type`);
+                }
+                body.previous_answers = parsed;
+            }
+            if (opts.alreadySurfaced) {
+                const parsed = await parseJsonFlag(opts.alreadySurfaced, "--already-surfaced");
+                if (!Array.isArray(parsed) || parsed.some((s) => typeof s !== "string")) {
+                    throw new Error("--already-surfaced must be a JSON array of strings.");
+                }
+                if (parsed.length > 40) {
+                    throw new Error(`--already-surfaced max 40 entries (got ${parsed.length}).`);
+                }
+                body.already_surfaced_prompts = parsed;
+            }
+            if (!globals.quiet) {
+                const target = body.count ?? 5;
+                console.error(`  suggesting ${target} scenario${target === 1 ? "" : "s"}...`);
+            }
+            const data = await client.post("/tester-profiles/suggest-scenarios", body, { timeout: 180_000 });
+            output(data, globals.json);
+        });
+    });
+    const evidence = profile
+        .command("evidence")
+        .description("Manage scenario-answer evidence on a tester profile")
+        .addHelpText("after", `
+Evidence rows persist answers to \`suggest-scenarios\` probes onto a
+specific profile. The \`source\` field on every trace is the same enum
+as the \`type\` field on a suggested scenario — copy verbatim when
+building a traces.json.
+
+Guide: ish docs get-page guides/build-specific-tester`);
+    evidence
+        .command("add")
+        .description("Persist scenario answers as structured evidence on a profile")
+        .argument("<id>", "Profile ID (alias or UUID)")
+        .option("--traces <json-or-@path>", `Array of {text, source, scenario_prompt?, raw_response?} where source ∈ ${EVIDENCE_SOURCES.join("|")}. Inline JSON, @/path/to.json, or - for stdin.`)
+        .option("--traces-file <path>", "Read --traces from a JSON file")
+        .addHelpText("after", `
+Examples:
+  # Inline JSON for a single trace
+  $ ish profile evidence add tp-d4e --traces '[{"text":"I would page my staff engineer first.","source":"situation","scenario_prompt":"PagerDuty fires at 02:00."}]'
+
+  # From a file
+  $ ish profile evidence add tp-d4e --traces-file ./answers.json
+
+  # From stdin (pipe-friendly)
+  $ jq -c '.traces' session.json | ish profile evidence add tp-d4e --traces -
+
+  # Project the response
+  $ ish profile evidence add tp-d4e --traces-file ./answers.json --fields id,source,created_at
+
+Valid source values: ${EVIDENCE_SOURCES.join(", ")}.
+\`source\` on a trace = \`type\` on a suggested scenario — same enum.
+Pair with \`ish profile suggest-scenarios\` to drive the iterative probe → answer loop.
+Verify with \`ish profile evidence list <id>\`.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (opts.traces && opts.tracesFile) {
+                throw new Error("Pass either --traces or --traces-file, not both.");
+            }
+            if (!opts.traces && !opts.tracesFile) {
+                throw new Error("Provide --traces (JSON, @path, or -) or --traces-file <path>.");
+            }
+            const parsed = opts.tracesFile
+                ? await readJsonFileOrStdin(opts.tracesFile)
+                : await parseJsonFlag(opts.traces, "--traces");
+            if (!Array.isArray(parsed) || parsed.length === 0) {
+                throw new Error("traces must be a non-empty JSON array.");
+            }
+            const traces = [];
+            for (let i = 0; i < parsed.length; i++) {
+                const row = parsed[i];
+                if (!row || typeof row !== "object") {
+                    throw new Error(`traces[${i}]: expected object {text, source, ...}.`);
+                }
+                if (typeof row.text !== "string" || row.text.length === 0) {
+                    throw new Error(`traces[${i}].text: required non-empty string.`);
+                }
+                if (typeof row.source !== "string") {
+                    throw new Error(`traces[${i}].source: required string.`);
+                }
+                assertEnumValue(row.source, EVIDENCE_SOURCES, `traces[${i}].source`);
+                if (row.scenario_prompt !== undefined && typeof row.scenario_prompt !== "string") {
+                    throw new Error(`traces[${i}].scenario_prompt: must be a string if provided.`);
+                }
+                traces.push({
+                    text: row.text,
+                    source: row.source,
+                    scenario_prompt: row.scenario_prompt ?? "",
+                    ...(row.raw_response !== undefined ? { raw_response: row.raw_response } : {}),
+                });
+            }
+            const rid = resolveId(id);
+            const body = { traces };
+            if (!globals.quiet) {
+                console.error(`  persisting ${traces.length} evidence trace${traces.length === 1 ? "" : "s"} on ${tagAlias(ALIAS_PREFIX.testerProfile, rid)}...`);
+            }
+            const data = await client.post(`/tester-profiles/${rid}/scenarios`, body);
+            if (globals.json) {
+                output({ items: data, total: data.length }, true);
+            }
+            else {
+                output(data, false);
+            }
+        });
+    });
+    evidence
+        .command("list")
+        .description("List evidence traces persisted on a tester profile (newest first)")
+        .argument("<id>", "Profile ID (alias or UUID)")
+        .addHelpText("after", `
+Examples:
+  # Read back every trace on a profile
+  $ ish profile evidence list tp-d4e
+
+  # Project per-row fields
+  $ ish profile evidence list tp-d4e --fields id,source,scenario_prompt
+
+  # Capture just the sources, one per line (auto-descends into items)
+  $ ish profile evidence list tp-d4e --get source
+
+Returns a {items, total} envelope. Use the same id you passed to \`evidence add\`.`)
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveId(id);
+            const data = await client.get(`/tester-profiles/${rid}/scenarios`);
+            if (globals.json) {
+                output({ items: data, total: data.length }, true);
+            }
+            else {
+                output(data, false);
+            }
+        });
+    });
+}
+/**
+ * Parse a flag that accepts inline JSON, an @path reference, or `-` for stdin.
+ * Mirrors the @path convention on --description (resolveTextContent) and the
+ * stdin convention on --file. Used by --traces, --previous-answers, etc.
+ */
+async function parseJsonFlag(value, flagName) {
+    if (value === "-") {
+        return readJsonFileOrStdin();
+    }
+    if (value.startsWith("@")) {
+        const path = value.slice(1);
+        if (!path) {
+            throw new Error(`Missing file path after @ in ${flagName}. Usage: ${flagName} @/path/to/file.json`);
+        }
+        return readJsonFileOrStdin(path);
+    }
+    const trimmed = value.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (e) {
+            throw new Error(`Invalid JSON in ${flagName}: ${e.message}`);
+        }
+    }
+    throw new Error(`${flagName} expects inline JSON (starting with { or [), an @path reference (@/path/to/file.json), or '-' for stdin.`);
 }
 /**
  * If the value matches the testerProfileSource alias pattern (e.g. "tps-3a4"),

package/dist/commands/study-run.js

@@ -8,7 +8,7 @@
  * Lower-level: `study poll`, `study cancel`.
  */
 import * as readline from "node:readline/promises";
-import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy, parseWaitTimeout, resolveAudienceProfileIds, addAudienceFilterFlags, hasAudienceFlags, } from "../lib/command-helpers.js";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy, parseWaitTimeout, resolveAudienceProfileIds, addAudienceFilterFlags, hasAudienceFlags, readFileOrStdin, } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatSimulationPoll } from "../lib/output.js";
 import { isMediaModality, isChatModality, iterationHasContent, describeRequiredContentFlag, readChatMode, readTesterPairConfig, summarizeRoleCriteria, } from "../lib/modality.js";
@@ -1065,4 +1065,183 @@ Examples:
             output(data, globals.json);
         });
     });
+    // --- Extend ---
+    //
+    // Resume a terminal tester with `additional_steps` more turns — the
+    // "start" half of the cancel + extend pair. The backend spawns a NEW
+    // tester under the same iteration, branched from the source's last
+    // interaction; the source row is left untouched. When --instruction is
+    // set, the new tester treats it as overriding direction (the backend
+    // surfaces it in a dedicated <user_added_instructions> block on every
+    // prompt — see app-simulation Fix 1).
+    study
+        .command("extend")
+        .description("Extend a terminal tester with more steps (and optionally a mid-run instruction)")
+        .argument("<tester_id>", "Tester to extend (alias or UUID). Must be in a terminal state (completed/failed/cancelled).")
+        .option("--add-steps <n>", "Extra interactions past the source's original cap (1-50; backend caps server-side)", "10")
+        .option("--instruction <text>", "User message to inject as the new tester resumes. Accepts inline text, `@/path/to/file`, or `-` for stdin.")
+        .option("--wait", "Block until the new tester reaches a terminal state")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300; only with --wait)")
+        .option("--dispatch-timeout <s>", "Per-POST timeout in seconds for the dispatch call (default 120)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from <tester_id>)")
+        .addHelpText("after", `
+The source tester is left untouched; a new tester is spawned under the
+same iteration and branched from the source's last interaction. Get the
+new tester ID from \`.tester_id\` / \`.tester_alias\` on the JSON output.
+
+Examples:
+  # Add 5 more steps to a completed run (no new instruction):
+  $ ish study extend t-072 --add-steps 5
+
+  # Inject a mid-run instruction and wait for completion:
+  $ ish study extend t-072 \\
+      --instruction "Open the language selector and switch to German." \\
+      --wait
+
+  # Long instruction from a file:
+  $ ish study extend t-072 --instruction @/tmp/prompt.txt --wait --timeout 600
+
+  # Instruction from stdin (pipe-friendly):
+  $ echo "Try the search bar instead." | ish study extend t-072 --instruction -
+
+Get tester IDs from \`ish study run --json\` (.tester_aliases[] / .tester_ids[]).
+See \`ish docs get-page concepts/extending-a-simulation\` for the full mental model.`)
+        .action(async (testerId, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            // --add-steps: client-side parser fails fast before the network
+            // call. Bound mirrors the backend's `le=50` cap; if the backend
+            // moves the bound, this message will lag — the backend remains
+            // authoritative and any 422 is surfaced verbatim.
+            const addStepsRaw = opts.addSteps ?? "10";
+            const addSteps = parseInt(addStepsRaw, 10);
+            if (Number.isNaN(addSteps) || addSteps < 1 || addSteps > 50) {
+                throw new Error(`--add-steps must be an integer between 1 and 50, got "${addStepsRaw}".`);
+            }
+            // --instruction: inline text | `@path` | `-` (stdin).
+            let instruction;
+            if (opts.instruction !== undefined) {
+                let raw;
+                if (opts.instruction === "-") {
+                    raw = await readFileOrStdin("-");
+                }
+                else if (opts.instruction.startsWith("@")) {
+                    raw = await readFileOrStdin(opts.instruction.slice(1));
+                }
+                else {
+                    raw = opts.instruction;
+                }
+                const trimmed = raw.trim();
+                if (trimmed.length === 0) {
+                    throw new Error("--instruction must be non-empty (after trimming).");
+                }
+                instruction = trimmed;
+            }
+            const dispatchTimeoutMs = opts.dispatchTimeout
+                ? Math.max(1, parseInt(opts.dispatchTimeout, 10)) * 1000
+                : 120_000;
+            if (opts.dispatchTimeout &&
+                (Number.isNaN(parseInt(opts.dispatchTimeout, 10)) ||
+                    parseInt(opts.dispatchTimeout, 10) < 1)) {
+                throw new Error(`--dispatch-timeout must be a positive integer (seconds), got "${opts.dispatchTimeout}".`);
+            }
+            const sourceId = resolveId(testerId);
+            const sourceAlias = tagAlias(ALIAS_PREFIX.tester, sourceId);
+            if (!globals.quiet) {
+                const stepNote = `${addSteps} step${addSteps === 1 ? "" : "s"}`;
+                const instrNote = instruction ? " and a new instruction" : "";
+                console.error(`Extending ${sourceAlias} with ${stepNote}${instrNote}...`);
+            }
+            const body = {
+                source_tester_id: sourceId,
+                additional_steps: addSteps,
+            };
+            if (instruction)
+                body.user_message = instruction;
+            const data = await client.post("/simulation/interactive/extend", body, { timeout: dispatchTimeoutMs });
+            const newTesterId = String(data.tester_id);
+            const newAlias = tagAlias(ALIAS_PREFIX.tester, newTesterId);
+            // UUIDs preserved on the output — `study extend` is a write-path
+            // dispatch command and the new `tester_id` is the load-bearing
+            // return value (mirrors how `study run` keeps tester_ids in lean
+            // output via the writePath option).
+            const baseEnvelope = {
+                tester_id: newTesterId,
+                tester_alias: newAlias,
+                source_tester_id: sourceId,
+                source_alias: sourceAlias,
+                study_id: data.study_id,
+                job_id: data.job_id,
+                additional_steps: addSteps,
+                ...(instruction && { instruction }),
+                message: data.message,
+            };
+            if (!opts.wait) {
+                if (globals.json) {
+                    output(baseEnvelope, true, { writePath: true });
+                }
+                else {
+                    console.error(`  New tester: ${newAlias}`);
+                    if (data.message)
+                        console.error(`  ${data.message}`);
+                    console.error(`  Run \`ish study wait ${newAlias} --timeout 600\` to block until it finishes.`);
+                }
+                return;
+            }
+            // --wait: poll the new tester until it reaches a terminal state.
+            // Mirrors the per-tester wait block in `study wait <tester_id>`
+            // above — same WaitTimeoutError shape (exit 5, retryable) so the
+            // failure envelope is consistent across commands.
+            const timeoutMs = parseWaitTimeout(opts.timeout);
+            if (!globals.quiet) {
+                console.error(`Waiting for ${newAlias} to finish...`);
+            }
+            const start = Date.now();
+            let lastStatus = "";
+            while (true) {
+                const status = await client.get(`/simulation/status/${newTesterId}`, undefined, { timeout: 60_000 });
+                const s = String(status.status ?? "unknown");
+                if (!globals.quiet && s !== lastStatus) {
+                    process.stderr.write(`  ${s}\n`);
+                    lastStatus = s;
+                }
+                if (TERMINAL_STATUSES.has(s)) {
+                    const result = {
+                        status: s,
+                        ...(typeof status.interaction_count === "number" && {
+                            interaction_count: status.interaction_count,
+                        }),
+                        ...(status.tester_name && { tester_name: status.tester_name }),
+                        ...(status.error && { error: status.error }),
+                    };
+                    if (globals.json) {
+                        output({ ...baseEnvelope, result }, true, { writePath: true });
+                    }
+                    else {
+                        console.error(`  ${newAlias} finished: ${s}`);
+                        if (status.error)
+                            console.error(`  error: ${status.error}`);
+                    }
+                    return;
+                }
+                if (Date.now() - start > timeoutMs) {
+                    throw new WaitTimeoutError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for tester ${newAlias}. Last status: ${s}.`, {
+                        study_id: newTesterId,
+                        timeout_seconds: Math.round(timeoutMs / 1000),
+                        done: 0,
+                        total: 1,
+                        pending: 1,
+                        rows: [
+                            {
+                                id: newTesterId,
+                                status: s,
+                                tester_name: String(status.tester_name ?? "Unknown"),
+                                interaction_count: typeof status.interaction_count === "number" ? status.interaction_count : 0,
+                            },
+                        ],
+                    });
+                }
+                await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+            }
+        });
+    });
 }

package/dist/lib/docs.js

@@ -1213,6 +1213,10 @@ The legacy \`--tech-savviness\` flag was removed in
 
 - \`concepts/source\` — the inputs to \`profile generate\`.
 - \`concepts/audience\` — how profiles get selected into a run.
+- \`guides/build-specific-tester\` — iterative probe loop
+  (\`profile suggest-scenarios\` + \`profile evidence add\`/\`list\`)
+  for crafting one specific persona, distinct from the
+  audience-generation flow.
 - \`reference/billing-limits\` — \`maxCustomTesterProfiles\` cap on profile creation.
 `;
 const CONCEPT_SOURCE = `# concept: source
@@ -1526,18 +1530,200 @@ ish study run --study s-b2c -y --json | jq -r '.tester_aliases[]'   # → t-072,
 ish study poll <tester_id>                # one-shot status for one tester
 ish study wait <tester_id> --timeout 600  # block until that tester finishes
 ish study cancel <tester_id>              # cancel a running simulation
+ish study extend <tester_id> --add-steps 10   # resume a terminal tester with N more steps
 \`\`\`
 
 \`<tester_id>\` accepts a tester alias (\`t-…\`) or a full UUID. The
 study-level \`poll\`/\`wait\` forms also exist (\`--study <id>\` /
 \`--iteration <id>\`) for whole-batch progress.
 
+\`cancel\` and \`extend\` form a reversible stop/start pair. \`cancel\`
+walks a running tester to a terminal \`cancelled\` status (no row
+removed); \`extend\` then spawns a fresh tester branched from the
+cancelled tester's last interaction. See
+\`concepts/extending-a-simulation\` for the full mental model.
+
 ## Related
 
 - \`reference/json-mode\` — output modes (display vs capture vs chain).
   Use \`--get tester_aliases\` to capture the run's testers without
   piping through \`jq\`. \`--human\` forces table output even through
   \`tee\`/redirection.
+- \`concepts/extending-a-simulation\` — \`study extend\` flow, when to
+  use it, and the mid-run \`--instruction\` UX.
+`;
+const CONCEPT_EXTENDING_SIMULATION = `# concept: extending a simulation
+
+\`ish study extend <tester_id>\` resumes a **terminal** tester with
+more interactions — and optionally a mid-run instruction. The source
+tester is left untouched; a **new** tester row is spawned under the
+same iteration, branched from the source's last interaction. Use it
+when a run hits the \`--max-interactions\` cap before the tester
+finished, or when you want to probe a "what if I had told them X
+mid-run?" scenario without restarting from scratch.
+
+## When extend is the right verb
+
+- Run hit the step cap (\`--max-interactions\`) before the tester
+  completed the assignment — give it 10 more steps to push through.
+- Tester veered off into a dead-end — cancel it, then extend with an
+  instruction redirecting it ("Stop browsing the blog. Open the pricing
+  page and try to add a seat.").
+- You want to test how a tester reacts to a mid-run change you didn't
+  capture in the original assignment — without re-running the whole
+  cohort.
+
+When extend is **not** the right verb:
+
+- Source tester is still RUNNING. \`cancel\` it first, then extend.
+  Extend refuses non-terminal sources server-side.
+- You want a fresh cohort with new audience flags. Use \`study run\`
+  with \`--profile\` / \`--sample\` / \`--all\` instead — extend is a
+  per-tester resume, not a batch op.
+- You want to change the iteration's URL or content. Edit the iteration
+  itself (\`iteration update\` or a fresh iteration) — extend always
+  inherits the source's iteration config.
+
+## Mental model — cancel + extend are a reversible pair
+
+\`cancel\` and \`extend\` are siblings in the tester lifecycle:
+
+\`\`\`
+  RUNNING ──(cancel)──▶ CANCELLED ──(extend)──▶ new RUNNING tester
+                                                (branched from the
+                                                 cancelled tester's
+                                                 last interaction)
+
+  COMPLETED / FAILED ──(extend)──▶ new RUNNING tester
+\`\`\`
+
+\`cancel\` is non-destructive — the tester row, every interaction, every
+screenshot, and the questionnaire answers all survive. \`extend\` then
+forks from the last interaction to keep the new tester's history
+seamlessly continuous.
+
+## Flags
+
+\`\`\`
+ish study extend <tester_id>
+    [--add-steps <n>]                 # extra steps, 1-50, default 10
+    [--instruction <text|@path|->]    # optional mid-run user message
+    [--wait]                          # block until terminal
+    [--timeout <s>]                   # wait timeout (default 300)
+    [--dispatch-timeout <s>]          # POST timeout (default 120)
+\`\`\`
+
+\`--instruction\` accepts three input shapes, matching the rest of the
+CLI:
+
+\`\`\`bash
+# Inline:
+ish study extend t-072 --instruction "Switch to the German pricing page."
+
+# From a file (long-form prompts, version-controlled):
+ish study extend t-072 --instruction @/tmp/redirect.md
+
+# From stdin (pipe-friendly):
+echo "Try the search bar instead." | ish study extend t-072 --instruction -
+\`\`\`
+
+The instruction is sent to the backend as \`user_message\`. The new
+tester treats it as **overriding direction** for the rest of the run —
+the backend surfaces it in a dedicated \`<user_added_instructions>\`
+block on every prompt, not just the first turn, so the LLM doesn't
+forget about it as the run goes on.
+
+## JSON output (lean, write-path)
+
+Default (no \`--wait\`):
+
+\`\`\`json
+{
+  "tester_id": "<new-uuid>",
+  "tester_alias": "t-xyz",
+  "source_tester_id": "<source-uuid>",
+  "source_alias": "t-abc",
+  "study_id": "<study-uuid>",
+  "job_id": "<job-uuid>",
+  "additional_steps": 10,
+  "instruction": "Switch to the German pricing page.",
+  "message": "Simulation queued"
+}
+\`\`\`
+
+With \`--wait\`, a \`result\` field is appended once the new tester
+reaches a terminal status:
+
+\`\`\`json
+{
+  ...,
+  "result": {
+    "status": "completed",
+    "interaction_count": 14,
+    "tester_name": "Anna, 34, Munich"
+  }
+}
+\`\`\`
+
+UUID fields (\`tester_id\`, \`source_tester_id\`, \`study_id\`, \`job_id\`)
+are preserved in lean output because the new \`tester_id\` is the
+load-bearing return value — same exception \`study run\` makes.
+
+## Errors
+
+| Backend | CLI behavior | Exit |
+|---|---|---|
+| Source not terminal (RUNNING / QUEUED) | \`Tester is still running — cancel it first or wait for completion.\` | 2 |
+| Source tester not found | \`Tester not found: <id>\` | 4 |
+| \`additional_steps\` out of range | Client-side parser rejects before the network call | 2 |
+| Insufficient credits | Bubbles the server message; retry only after topping up | 5 |
+| Wait timed out (\`--wait\` only) | \`WaitTimeoutError\` envelope with current status under \`progress.rows[0]\` — the run keeps going server-side; resume with \`study wait <new-tester>\` | 5 |
+
+## Cost model
+
+\`extend\` charges credits for **only \`additional_steps\`**, not for
+the source's original \`max_interactions\` cap. The formula is the same
+as \`study run\` for interactive runs: \`max(1, round(N / 10))\` per
+tester. So \`--add-steps 10\` costs **1 credit**; \`--add-steps 50\`
+costs **5 credits**. See \`reference/credits\` for the full table.
+
+## Worked example — push past the step cap
+
+\`\`\`bash
+# 1. Run a study with a small step cap to feel the limit:
+ish study run --sample 1 --max-interactions 5 --wait
+# → tester t-072 (status: completed_with_errors, hit cap on step 5)
+
+# 2. Inspect what happened:
+ish study tester t-072 --summary
+
+# 3. Give it 15 more steps:
+ish study extend t-072 --add-steps 15 --wait --timeout 600
+# → new tester t-9af, status: completed, 18 interactions total
+
+# 4. Read the new tester's transcript:
+ish study tester t-9af --summary
+\`\`\`
+
+## Worked example — redirect mid-run
+
+\`\`\`bash
+# Tester wandered into the wrong flow. Cancel, then redirect:
+ish study cancel t-072
+ish study extend t-072 \\
+    --instruction "Stop browsing the blog. Open the pricing page and try to upgrade to Pro." \\
+    --add-steps 10 --wait
+\`\`\`
+
+## Related
+
+- \`concepts/run-verbs\` — the top-level decision rule (\`study run\` vs
+  \`ask run\`); extend is a lifecycle verb downstream of either.
+- \`reference/credits\` — per-modality cost formulas. \`extend\` follows
+  the interactive formula scaled to \`additional_steps\`.
+- \`reference/aliases\` — the \`t-…\` prefix and how aliases resolve.
+- \`reference/json-mode\` — capture-mode (\`--get tester_alias\`) for
+  chaining the new tester into the next call.
 `;
 const REFERENCE_ALIASES = `# reference: aliases
 
@@ -3236,6 +3422,122 @@ without a second round-trip.
 - \`reference/json-mode\` — error envelope shape and exit code mapping
   (\`usage_limit_reached\` is HTTP 403, exit 1, non-retryable).
 `;
+const GUIDE_BUILD_SPECIFIC_TESTER = `# guide: build a specific simulated tester from notes
+
+\`profile generate\` is the right tool for *audiences* (many profiles
+from a description or interview sources). When you want **one specific
+tester** — modelling a real prospect, rebuilding a persona from a
+single interview, or simulating a named stakeholder for a pitch
+rehearsal — use the iterative probe loop:
+
+1. \`ish profile suggest-scenarios\` — describe what you already
+   know; the LLM returns 1–10 scenario probes designed to expose what
+   you don't.
+2. Answer the probes locally (in chat, with the user, or from
+   transcripts).
+3. \`ish profile create --file ...\` — save the profile shell.
+4. \`ish profile evidence add <id>\` — persist the answered probes
+   as structured evidence on the profile so they survive into runtime
+   persona injection.
+5. \`ish profile evidence list <id>\` — read back what's saved,
+   newest first. Useful for verifying a session or branching on prior
+   state before the next probe round.
+
+## Probe types
+
+\`suggest-scenarios\` returns four discriminated shapes. Each is meant
+to surface a different facet of the persona:
+
+- \`situation\` — \`{situation, options[2..4]}\`: "you're in scenario
+  X; which option fits?" Multiple-choice, lets the persona pick
+  behavior.
+- \`voice\` — \`{situation, options[2..4]}\`: same shape as situation
+  but framed around tone/phrasing the tester would actually use.
+- \`binary\` — \`{description, option_a, option_b}\`: forced choice
+  between two competing values or trade-offs.
+- \`micro-story\` — \`{prompt}\`: open-ended; the persona narrates a
+  short story. Answer with a multi-sentence free-text reply.
+
+The wire format keeps \`option_a\` / \`option_b\` (snake_case). The
+CLI passes them through verbatim — don't transform to camelCase.
+
+**Identity rule** — when building \`traces.json\` after answering a
+probe, copy the scenario's \`type\` straight into the trace's
+\`source\`. Same enum, two field names. The mechanical mapping:
+
+| Suggested scenario field | Trace field      |
+|--------------------------|------------------|
+| \`scenario.type\`          | \`trace.source\`   |
+| \`scenario.situation\` / \`scenario.description\` / \`scenario.prompt\` | \`trace.scenario_prompt\` (one line, whatever question label the user actually answered) |
+| (user's answer)          | \`trace.text\`     |
+
+## Worked example
+
+\`\`\`
+# 1. Suggest 5 probes from a context blob
+ish profile suggest-scenarios \\
+    --context "Staff platform engineer at a Stripe-using fintech. \\
+        Owns on-call for the payments edge. Burned by a Black Friday \\
+        outage last year." \\
+    --count 5
+# → {scenarios: [{type: "situation", ...}, {type: "binary", ...}, ...]}
+
+# 2. (offline) answer the probes — build a local answers.json:
+# [
+#   {"text": "Page the staff engineer first, then start the runbook.",
+#    "source": "situation",
+#    "scenario_prompt": "PagerDuty fires at 02:00 on payments edge."},
+#   {"text": "Option A — cut the rollout, take the revenue hit.",
+#    "source": "binary",
+#    "scenario_prompt": "Ship the migration or hold for incident review?"}
+# ]
+
+# 3. Create the profile shell
+ish profile create --file ./persona.json
+# → tp-d4e
+
+# 4. Persist the answered probes as evidence
+ish profile evidence add tp-d4e --traces-file ./answers.json
+# → {items: [{id, text, source, scenario_prompt, created_at}, ...], total: N}
+
+# 5. Read back what got saved (also useful before the next probe round)
+ish profile evidence list tp-d4e
+ish profile evidence list tp-d4e --get source   # one source per line
+\`\`\`
+
+## Iterating the probe loop
+
+To go deeper on a follow-up pass, feed the prior round back in so the
+LLM doesn't paraphrase what you already asked:
+
+\`\`\`
+ish profile suggest-scenarios \\
+    --context-file ./notes.md \\
+    --count 3 \\
+    --already-surfaced '["PagerDuty fires at 02:00 on payments edge."]' \\
+    --previous-answers @./answers.json
+\`\`\`
+
+\`--previous-answers\` is the array of \`{type, prompt, answer}\` rows
+already collected. \`--already-surfaced\` is the array of prompt
+labels already shown — the LLM uses these to avoid re-asking. Both
+cap at 40 entries.
+
+## When to reach for which command
+
+| Need | Command |
+|---|---|
+| Many profiles from a description or interview | \`ish profile generate\` |
+| One specific persona, iterative probe loop | \`ish profile suggest-scenarios\` + \`evidence add\`/\`list\` |
+| Exact profile from a JSON spec, no LLM | \`ish profile create --file\` |
+
+## Related
+
+- \`concepts/profile\` — what a tester profile is; structured fields.
+- \`concepts/source\` — interview transcripts / audio / PDF inputs
+  for the audience-generation flow.
+- \`reference/aliases\` — \`tp-…\` is the profile alias prefix.
+`;
 const PAGES = [
     {
         slug: "overview",
@@ -3321,6 +3623,12 @@ const PAGES = [
         description: "Side-by-side; decision rule for choosing one over the other.",
         body: CONCEPT_RUN_VERBS,
     },
+    {
+        slug: "concepts/extending-a-simulation",
+        title: "concept: extending a simulation (study extend)",
+        description: "Resume a terminal tester with more steps and an optional mid-run instruction. Cancel + extend as a reversible stop/start pair.",
+        body: CONCEPT_EXTENDING_SIMULATION,
+    },
     {
         slug: "concepts/active-context",
         title: "concept: active context",
@@ -3375,6 +3683,12 @@ const PAGES = [
         description: "What to do when workspace_create returns usage_limit_reached on a saturated account. Inspect workspace_get (has_headroom / child_counts / last_activity_at), pick a reuse target, or call ish workspace create --ensure name.",
         body: GUIDE_COLD_START,
     },
+    {
+        slug: "guides/build-specific-tester",
+        title: "guide: build a specific simulated tester from notes",
+        description: "Iterative probe loop for one specific persona: profile suggest-scenarios returns LLM probes; answer them locally; profile evidence add persists answers; profile evidence list reads them back.",
+        body: GUIDE_BUILD_SPECIFIC_TESTER,
+    },
 ];
 const PAGES_BY_SLUG = new Map(PAGES.map((p) => [p.slug, p]));
 export function listPages() {

package/dist/lib/enums.d.ts

@@ -44,6 +44,14 @@ export declare const LOCALE_TYPES: readonly ["urban", "suburban", "small_town",
 export type LocaleType = typeof LOCALE_TYPES[number];
 export declare const INCOME_LEVELS: readonly ["lower", "lower_middle", "middle", "upper_middle", "upper", "prefer_not_to_say"];
 export type IncomeLevel = typeof INCOME_LEVELS[number];
+/**
+ * Source kinds for a persisted scenario answer (EvidenceTrace.source). Matches
+ * the backend `EvidenceSource` literal union — one value is hyphenated
+ * (`micro-story`) so the wire format is mixed; `assertEnumValue` is strict
+ * about this and does not fold hyphens to underscores.
+ */
+export declare const EVIDENCE_SOURCES: readonly ["situation", "voice", "binary", "micro-story"];
+export type EvidenceSourceEnum = typeof EVIDENCE_SOURCES[number];
 export declare const EMPLOYMENT_STATUSES: readonly ["employed_full_time", "employed_part_time", "self_employed", "unemployed_seeking", "student", "homemaker", "retired", "unable_to_work", "other"];
 export type EmploymentStatus = typeof EMPLOYMENT_STATUSES[number];
 /**

package/dist/lib/enums.js

@@ -76,6 +76,18 @@ export const INCOME_LEVELS = [
     "upper",
     "prefer_not_to_say",
 ];
+/**
+ * Source kinds for a persisted scenario answer (EvidenceTrace.source). Matches
+ * the backend `EvidenceSource` literal union — one value is hyphenated
+ * (`micro-story`) so the wire format is mixed; `assertEnumValue` is strict
+ * about this and does not fold hyphens to underscores.
+ */
+export const EVIDENCE_SOURCES = [
+    "situation",
+    "voice",
+    "binary",
+    "micro-story",
+];
 export const EMPLOYMENT_STATUSES = [
     "employed_full_time",
     "employed_part_time",

package/dist/lib/skill-content.js

@@ -213,6 +213,7 @@ See \`references/workflows.md\` in this skill for end-to-end transcripts:
 - Generating profiles from a transcript or audio source
 - Targeting a gated URL (basic auth, session cookie, login form)
 - Re-running a study with a fresh audience
+- Extending a tester past its step cap (or redirecting mid-run with \`study extend\`)
 
 ## Display vs. capture: the right output mode
 
@@ -358,6 +359,13 @@ implies \`--quiet\` so the bare value is the only thing on stdout.
 - **\`ask add-questions\` supports \`--wait\` / \`--timeout\`.** Match
   the parity of \`ask create\` and \`ask run\`. Without \`--wait\` the
   command returns after dispatch (round still running).
+- **\`study extend <tester>\` resumes a terminal tester.** Use it when
+  a run hit \`--max-interactions\` before finishing, or pair with
+  \`study cancel\` to redirect mid-run via \`--instruction\` (inline,
+  \`@path\`, or stdin via \`-\`). Spawns a **new** tester branched from
+  the source's last interaction — source row untouched. Credits debit
+  per \`max(1, round(additional_steps / 10))\`. See workflow #11 and
+  \`ish docs get-page concepts/extending-a-simulation\`.
 - **\`pick_confidence\` (0..1) is on every \`--wants-pick\` response.**
   The model's self-reported confidence in its variant choice. Use it
   to break ties when nominal pick counts are close. See
@@ -607,7 +615,50 @@ ish profile generate --source tps-3a4 --propose-count
 ish profile generate --source tps-3a4 --count 4
 \`\`\`
 
-## 4. Target a gated URL (Vercel preview / staging gate / login form)
+## 4. Build a specific simulated tester from notes
+
+Goal: rebuild one named persona (a real prospect, a stakeholder for
+a pitch rehearsal) via the iterative probe loop — distinct from
+\`profile generate\`, which is for audiences.
+
+\`\`\`bash
+# 1. Suggest 5 probes from a context blob
+ish profile suggest-scenarios \\
+    --context "Staff platform engineer at a Stripe-using fintech. \\
+        Owns oncall for the payments edge. Burned by a Black Friday \\
+        outage last year." \\
+    --count 5
+# → {scenarios: [{type:"situation",...},{type:"binary",...},...]}
+
+# 2. (offline) Answer the probes — build answers.json:
+#    [{"text":"...","source":"situation","scenario_prompt":"..."}, ...]
+#    Valid source values: situation, voice, binary, micro-story
+
+# 3. Save the profile shell
+ish profile create --file ./persona.json
+# → tp-d4e
+
+# 4. Persist the answers as structured evidence
+ish profile evidence add tp-d4e --traces-file ./answers.json
+
+# 5. Read back what's saved (also useful before the next probe round)
+ish profile evidence list tp-d4e
+\`\`\`
+
+To iterate, feed prior prompts/answers back in so the LLM doesn't
+paraphrase what you already asked:
+
+\`\`\`bash
+ish profile suggest-scenarios \\
+    --context-file ./notes.md --count 3 \\
+    --already-surfaced '["PagerDuty fires at 02:00."]' \\
+    --previous-answers @./answers.json
+\`\`\`
+
+See \`ish docs get-page guides/build-specific-tester\` for the full
+walkthrough including the four probe-type shapes.
+
+## 5. Target a gated URL (Vercel preview / staging gate / login form)
 
 Configure credentials once on the workspace; testers reuse them.
 
@@ -633,7 +684,7 @@ printf %s "$STAGING_PW" | ish workspace site-access basic-auth \\
     --username alice --password -
 \`\`\`
 
-## 5. Re-run a study with a fresh audience
+## 6. Re-run a study with a fresh audience
 
 Goal: same study, same iteration, but compare audiences.
 
@@ -649,7 +700,7 @@ If you don't pass any audience flags, \`ish study run\` reuses the
 iteration's existing testers — useful for re-running after fixing the
 target page.
 
-## 6. Localhost target (dev environment)
+## 7. Localhost target (dev environment)
 
 Expose a port via a Cloudflare tunnel; \`ish connect\` prints the public
 URL the study iteration can point at. \`connect\` is foreground and
@@ -675,7 +726,7 @@ URL=$(jq -r 'select(.status=="connected") | .tunnel_url' /tmp/ish-tunnel.log | h
 ish iteration create --url "$URL"
 \`\`\`
 
-## 7. Chat-modality study (drive a chatbot endpoint)
+## 8. Chat-modality study (drive a chatbot endpoint)
 
 The chat modality has **two modes**, picked by
 \`iteration.details.mode_details.mode\`:
@@ -991,7 +1042,7 @@ ish iteration get <iter-id> --json \\
 ish study results <study-id> --transcript <tester-id> --json
 \`\`\`
 
-## 8. Stage an ask for human review, then dispatch
+## 9. Stage an ask for human review, then dispatch
 
 Goal: prepare a billable A/B but let the user inspect and approve the
 audience + prompt before any credits are spent. Two-step flow with a
@@ -1025,7 +1076,7 @@ status as a column.
 wait for. Pass \`--wait\` to \`ish ask dispatch\` instead if you want to
 block until the round settles.
 
-## 9. Display-vs-capture: a script that does both
+## 10. Display-vs-capture: a script that does both
 
 Goal: drive an A/B in a script, capture aliases without \`jq\`, and
 still show the human a readable result table at the end.
@@ -1054,6 +1105,60 @@ The mental rule: **\`--get\` is for capture, bare commands / \`--human\`
 are for display, \`--json\` is for chaining (multiple fields at once).**
 If you find yourself reaching for \`jq -r .x\`, you wanted \`--get x\`.
 
+## 11. Extend a tester past its step cap (or redirect mid-run)
+
+Goal: a tester hit the \`--max-interactions\` cap before finishing, or
+veered off into the wrong flow. Resume it with more steps and an
+optional mid-run instruction — without re-running the whole cohort.
+
+\`\`\`bash
+# 1. Source run with a small cap to feel the limit:
+ish study run --sample 1 --max-interactions 5 --wait
+SRC=$(ish study run --sample 1 --max-interactions 5 --wait \\
+        --get tester_aliases | head -1)
+
+# 2. Inspect what stopped (optional, useful for the LLM to choose
+#    a redirect instruction):
+ish study tester "$SRC" --summary
+
+# 3a. Add 15 more steps, no new instruction — let the tester continue:
+ish study extend "$SRC" --add-steps 15 --wait --timeout 600
+
+# 3b. OR redirect with a mid-run instruction (captured as user_message;
+#     the backend surfaces it on every prompt for the rest of the run):
+ish study extend "$SRC" \\
+    --instruction "Stop browsing the blog. Open the pricing page and try to upgrade to Pro." \\
+    --add-steps 10 --wait
+
+# 4. Capture the new tester alias to chain into results:
+NEW=$(ish study extend "$SRC" --add-steps 10 --get tester_alias)
+ish study tester "$NEW" --summary
+\`\`\`
+
+Rules to remember:
+- Source tester must be **terminal** (\`completed\` / \`failed\` /
+  \`cancelled\`). If it's still running, \`ish study cancel <src>\` first.
+  \`cancel\` is non-destructive — every interaction, screenshot, and
+  questionnaire answer survives. \`cancel\` + \`extend\` form a
+  reversible stop/start pair.
+- A **new** tester id is created under the same iteration (the backend
+  branches from the source's last interaction). The source row is left
+  untouched. Get the new id from \`.tester_id\` / \`.tester_alias\` on
+  \`--json\`.
+- \`--add-steps\` is **only** the extra budget; it does NOT include the
+  source's original cap. Credits debit per
+  \`max(1, round(additional_steps / 10))\` — same formula as
+  \`study run\` interactive, just scoped to the extension.
+- \`--instruction\` accepts three input shapes (matching the rest of
+  the CLI): inline text, \`@/path/to/file\`, or \`-\` for stdin. Empty
+  values after trimming are rejected client-side.
+- Don't use \`extend\` to change the iteration's URL / content. Edit
+  the iteration directly (\`iteration update\`) or run a fresh
+  \`study run\`. Extend always inherits the source's iteration config.
+
+See \`ish docs get-page concepts/extending-a-simulation\` for the full
+mental model (cancel + extend as a pair, error envelopes, cost model).
+
 ## Tips for chaining commands as an agent
 
 - Capture aliases from JSON: \`ITER=$(ish iteration create --url … --json | jq -r .alias)\`
@@ -1174,7 +1279,7 @@ ish <command> --help
 | \`study\`     | Persistent research artifact                    | concepts/study              |
 | \`iteration\` | One configured run of a study (URL or media)    | concepts/iteration          |
 | \`ask\`       | Lightweight reaction artifact                   | concepts/ask                |
-| \`profile\`   | Tester profiles + audience generation           | concepts/profile            |
+| \`profile\`   | Tester profiles, audience generation, and the \`suggest-scenarios\` + \`evidence add\`/\`list\` probe loop for crafting one specific persona | concepts/profile            |
 | \`source\`    | Upload sources for profile generation           | concepts/source             |
 | \`config\`    | Simulation configs (model, timing, retries)     | (run \`ish config --help\`)   |
 | \`chat\`      | Chat endpoint CRUD + smoke test (external_chatbot mode); pair-mode iterations created via \`iteration create --chat-mode tester_pair\` | guides/chat                 |

package/dist/lib/types.d.ts

@@ -188,6 +188,62 @@ export interface GeneratedProfile {
     custom_field_values?: Record<string, unknown>;
     [key: string]: unknown;
 }
+export type EvidenceSource = "situation" | "voice" | "binary" | "micro-story";
+export interface SessionAnswer {
+    type: EvidenceSource;
+    prompt: string;
+    answer: string;
+}
+export interface SuggestScenariosRequest {
+    product_id: string;
+    context: string;
+    count?: number;
+    already_surfaced_prompts?: string[];
+    previous_answers?: SessionAnswer[];
+}
+/**
+ * Discriminated union — wire shape matches the backend (snake_case
+ * `option_a`/`option_b` for binary scenarios). The CLI is wire-honest
+ * in JSON output; FE-side camelCase transforms are deliberately not
+ * applied here.
+ */
+export type SuggestedScenario = {
+    type: "situation";
+    situation: string;
+    options: string[];
+} | {
+    type: "voice";
+    situation: string;
+    options: string[];
+} | {
+    type: "binary";
+    description: string;
+    option_a: string;
+    option_b: string;
+} | {
+    type: "micro-story";
+    prompt: string;
+};
+export interface SuggestScenariosResponse {
+    scenarios: SuggestedScenario[];
+}
+export interface EvidenceTraceInput {
+    text: string;
+    source: EvidenceSource;
+    scenario_prompt?: string;
+    raw_response?: Record<string, unknown> | null;
+}
+export interface AddEvidenceRequest {
+    traces: EvidenceTraceInput[];
+}
+export interface EvidenceTraceResponse {
+    id: string;
+    text: string;
+    source: EvidenceSource;
+    scenario_prompt: string;
+    raw_response: Record<string, unknown> | null;
+    created_at: string;
+}
 export interface Tester {
     id: string;
     iteration_id: string;

package/package.json

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