@ishlabs/cli 0.14.1 → 0.16.0

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
@@ -1264,7 +1268,12 @@ flags. Two ways to select:
    - \`--min-age 25\`
    - \`--max-age 50\`
    - \`--search "early adopter"\`
-   - \`--visibility shared|private\`
+   - \`--visibility workspace|shared|platform\` (filter by where the
+     profile lives: your workspace, the community-published pool, or
+     the admin-curated platform pool; old values \`private\` /
+     \`public\` still accepted as aliases for \`workspace\` /
+     \`platform\` until the next release with a server-side
+     deprecation warning)
 
 The two modes are **mutually exclusive** — pass either \`--profile\` or
 the filter set, not both.
@@ -1526,18 +1535,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 +3427,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 +3628,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 +3688,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/study-events.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SSE consumer for the backend's per-study event stream.
+ *
+ * Used by `study run --wait` to wake up the poll loop as soon as a tester
+ * status / interaction event arrives, instead of waiting for the next poll
+ * tick. The canonical truth source remains `GET /studies/{id}` — SSE here
+ * only shortens the latency between a backend event and the next status
+ * fetch; the poll fallback still runs on a slow timer in case events are
+ * missed.
+ *
+ * Best-effort:
+ *  - Mints a short-lived stream token (POST /auth/stream-token).
+ *  - Opens `GET /studies/{id}/events?token=…` via `fetch` and streams the
+ *    response body.
+ *  - Returns (silently exits the iterator) on any failure — token mint
+ *    503 (server not configured), endpoint 503 (broker offline on this
+ *    instance), network error, abort. The caller's polling rhythm is the
+ *    safety net; we never raise.
+ *
+ * Stream-token TTL is 1h on the backend. For runs longer than that the
+ * fetch will end (server closes); the caller falls back to pure polling
+ * for the remainder.
+ */
+import { ApiClient, ApiError } from "./api-client.js";
+export interface StudyEvent {
+    type: string;
+    study_id: string;
+    iteration_id?: string | null;
+    tester_id?: string | null;
+    interaction_id?: string | null;
+    frame_id?: string | null;
+    frame_version_id?: string | null;
+    tester_status?: string | null;
+    ts: string;
+    seq: number;
+    payload?: unknown;
+}
+/**
+ * Async generator that yields parsed StudyEvents from the backend SSE
+ * stream. Exits silently (without throwing) on failure or abort — callers
+ * MUST have a polling fallback that drives correctness.
+ */
+export declare function streamStudyEvents(client: ApiClient, studyId: string, signal: AbortSignal): AsyncGenerator<StudyEvent, void, void>;
+/** Type narrower used by callers to skip the synthetic LAG marker. */
+export declare function isLagEvent(event: StudyEvent): boolean;
+export { ApiError };