@ishlabs/cli 0.17.7 → 0.19.0

package/dist/lib/docs.js

@@ -7,7 +7,7 @@
  */
 const OVERVIEW = `# ish — overview for agents
 
-ish is a CLI for running studies and asks against AI tester audiences.
+ish is a CLI for running studies and asks against AI people.
 The agent (you) is the primary user. Every command supports \`--json\`,
 exits non-zero on failure, and resolves IDs from short aliases.
 
@@ -15,16 +15,16 @@ exits non-zero on failure, and resolves IDs from short aliases.
 
 \`\`\`
 Workspace (= product)
-├── Tester Profiles ────── reusable audience personas (alias: tp-…)
+├── People ────── reusable personas (alias: tp-…)
 │     └── Sources ──────── transcripts/audio/images that seed generation
 ├── Study ──────────────── persistent research artifact (alias: s-…)
 │     ├── modality ──────── interactive | text | video | audio | image | document | chat
-│     ├── assignments ───── tasks the tester does
-│     ├── questionnaire ─── questions the tester answers
+│     ├── assignments ───── tasks the participant does
+│     ├── questionnaire ─── questions the participant answers
 │     └── Iterations ────── one configured run (URL or content) (alias: i-…)
-│           └── Testers ─── instance of a Profile in this iteration (alias: t-…)
+│           └── Participants ─── instance of a Profile in this iteration (alias: t-…)
 └── Ask ────────────────── lightweight reaction artifact (alias: a-…)
-      └── Rounds ────────── unit of execution; audience fixed at ask creation
+      └── Rounds ────────── unit of execution; participants fixed at ask creation
 \`\`\`
 
 Two top-level run verbs:
@@ -37,7 +37,7 @@ Two top-level run verbs:
 2. Run \`ish docs get-page <slug>\` to read a specific page (e.g. \`concepts/study\`).
 3. Run \`ish docs search <query>\` for keyword lookup across all pages.
 4. Every command prints structured JSON when stdout is piped or \`--json\` is set.
-5. Aliases like \`s-b2c\`, \`a-6ec\`, \`tp-795\`, \`i-d4e\`, \`t-a17\` are accepted
+5. Aliases like \`s-b2c\`, \`a-6ec\`, \`p-795\`, \`i-d4e\`, \`pt-a17\` are accepted
    anywhere an ID is expected. See \`ish docs get-page reference/aliases\`.
 
 ## Where to look next
@@ -73,7 +73,7 @@ workspace.
 A workspace carries:
 - \`base_url\` — default origin used by site-access rules and study URLs.
 - Site-access credentials (encrypted at rest) — see \`concepts/site-access\`.
-- Tester profiles + sources visible to every study/ask in the workspace.
+- People + sources visible to every study/ask in the workspace.
 
 ## Selecting a workspace per command
 
@@ -113,15 +113,15 @@ ish workspace info --json
 {
   "studies_used": 2,
   "studies_max": 3,
-  "testers_used": 0,
-  "testers_max": 3,
+  "participants_used": 0,
+  "participants_max": 3,
   "tier": "free"
 }
 \`\`\`
 
 A \`null\` value on a \`*_max\` field means "unlimited" (paid tiers).
 Branch on \`studies_used >= studies_max\` before \`study create\`,
-likewise for \`testers_used\` before \`study run --sample\`.
+likewise for \`participants_used\` before \`study run --sample\`.
 
 ## Cold start — \`workspace_create\` is not safe to call blind
 
@@ -138,13 +138,13 @@ Each row in the list response carries:
 - \`last_activity_at\` — most recent run, iteration, ask, or write on
   this workspace. Pick the most recently active workspace if you want
   one the user is likely already thinking about.
-- \`child_counts\` — \`{ studies, asks, tester_profiles }\`. Zero across
+- \`child_counts\` — \`{ studies, asks, persons }\`. Zero across
   the board = a quiet/empty workspace, safe to reuse without
   cluttering anyone's view.
 - \`has_headroom\` — \`true\` if the workspace is below
   \`maxStudiesPerProduct\`, \`maxIterationsPerStudy\`, and
-  \`maxCustomTesterProfiles\` for the caller's tier. Branch on this
-  before \`study create\` / \`profile generate\` — \`false\` here will be
+  \`maxCustomPersons\` for the caller's tier. Branch on this
+  before \`study create\` / \`person generate\` — \`false\` here will be
   \`usage_limit_reached\` on the next call.
 
 For the idempotent create-or-reuse-by-name path, use
@@ -167,14 +167,14 @@ transcript) lives at \`guides/cold-start\`.
 const CONCEPT_STUDY = `# concept: study
 
 A **study** is the persistent research artifact. It defines:
-- \`modality\`: \`interactive\` (the tester drives a real browser), one of
+- \`modality\`: \`interactive\` (the participant drives a real browser), one of
   \`text | video | audio | image | document\` (media reaction studies),
   or \`chat\` (multi-turn conversation — either with an external chatbot
-  endpoint or between two AI personas via tester_pair mode).
+  endpoint or between two AI personas via participant_pair mode).
 - \`content_type\` (media studies only): \`email | social_post | ad | …\` —
-  controls the framing the tester is given.
-- \`assignments\`: the tasks the tester performs. See \`concepts/assignment\`.
-- \`questionnaire\`: the questions the tester answers. See \`concepts/questionnaire\`.
+  controls the framing the participant is given.
+- \`assignments\`: the tasks the participant performs. See \`concepts/assignment\`.
+- \`questionnaire\`: the questions the participant answers. See \`concepts/questionnaire\`.
 
 A study does **not** carry the URL or media being tested — that lives on
 its iterations. Think: a study is the recipe; an iteration is one batch.
@@ -204,7 +204,7 @@ test artifact and don't need to A/B iterations:
 | \`video\`       | \`--content-url <url>\`                              |
 | \`audio\`       | \`--content-url <url>\`                              |
 | \`document\`    | \`--content-url <url>\`                              |
-| \`chat\`        | \`--endpoint <id>\` or \`--endpoint-config <file>\` (external_chatbot mode), or \`--chat-mode tester_pair --audience-a/-b --scenario-a/-b\` (two-AI rehearsal) |
+| \`chat\`        | \`--endpoint <id>\` or \`--endpoint-config <file>\` (external_chatbot mode), or \`--chat-mode participant_pair --group-a/-b --scenario-a/-b\` (two-AI rehearsal) |
 
 \`\`\`
 # Text — single email artifact:
@@ -256,8 +256,8 @@ Every study response carries two status-shaped fields:
 
 - \`status\` — the raw lifecycle column on the row, values
   \`draft | running | completed | cancelled\`. Updated lazily; can
-  disagree with what the testers actually did.
-- \`runtime_status\` — derived by aggregating the iteration testers'
+  disagree with what the participants actually did.
+- \`runtime_status\` — derived by aggregating the iteration participants'
   states. Values: \`draft | running | completed |
   completed_with_errors | cancelled\`. **Never reports \`failed\` while
   completed runs exist** (the Bk2 invariant). Prefer this for any
@@ -307,8 +307,8 @@ the chat payload (chat) — while the study carries the persistent
 shape (assignments, questionnaire, modality).
 
 For chat modality, the iteration's \`details.mode_details\` discriminator
-selects between **external_chatbot** (testers probe a customer chatbot
-endpoint) and **tester_pair** (two AI tester audiences converse with
+selects between **external_chatbot** (participants probe a customer chatbot
+endpoint) and **participant_pair** (two AI people converse with
 each other, one Conversation per pair index). Wire-shape examples and
 pair-mode rules live under the "## Chat modality" section below; the
 full chat-author workflow is at \`guides/chat\`.
@@ -322,7 +322,7 @@ full chat-author workflow is at \`guides/chat\`.
 
 Because you want to A/B different URLs or content variants while keeping
 the same task definitions and questionnaire. Each iteration also owns
-its own roster of testers, so you can compare audiences as well.
+its own roster of participants, so you can compare groups as well.
 
 ## Common commands
 
@@ -358,9 +358,9 @@ ish iteration create --content-url ./report.pdf
 # Chat (external_chatbot) — probe a saved chatbot endpoint:
 ish iteration create --chat-endpoint-id ce-... --max-turns 10 --early-termination
 
-# Chat (tester_pair) — rehearse a conversation between two AI audiences:
-ish iteration create --chat-mode tester_pair \\
-  --audience-a tp-a1,tp-a2 --audience-b tp-b1,tp-b2 \\
+# Chat (participant_pair) — rehearse a conversation between two AI groups:
+ish iteration create --chat-mode participant_pair \\
+  --group-a p-a1,p-a2 --group-b p-b1,p-b2 \\
   --scenario-a "You're a senior sales rep pitching ish." \\
   --scenario-b "You're a skeptical CTO evaluating ish."
 
@@ -376,7 +376,7 @@ can be collected per **segment** instead of over the whole asset. A
 segment is a contiguous slice of the iteration's content — a 30-second
 window of a video, a paragraph range of an email, a section of a PDF.
 Each segment can carry a human-readable **label** ("Intro", "Pricing
-section", "Call to action") that surfaces in the tester UI and in
+section", "Call to action") that surfaces in the participant UI and in
 results.
 
 Segments live inside the iteration's \`segmentation\` field — there is
@@ -423,7 +423,7 @@ reactions; otherwise the default just works.
 
 ### content_config — early termination + selected segments
 
-A sibling of \`segmentation\` that controls how the tester progresses
+A sibling of \`segmentation\` that controls how the participant progresses
 through segments:
 
 - \`early_termination: true\` — stop the session once every selected
@@ -437,7 +437,7 @@ Pass via \`--content-config-json '<json>'\`.
 
 - **Text modality**: pair plain \`--content-text\` with rich
   \`--content-html\` to render emails / articles with formatting. The
-  plain text is what testers reason over; the HTML is what they see.
+  plain text is what participants reason over; the HTML is what they see.
 - **Media captions** (video, audio, image): \`--copy-text\` and
   \`--copy-html\` attach a caption to the media — the social-post
   pattern. Add \`--social-platform\` (instagram/tiktok/facebook/linkedin/x)
@@ -455,12 +455,12 @@ Chat iterations hold a multi-turn conversation. The conversation can
 take one of two shapes, picked by the \`mode_details.mode\` discriminator
 on the iteration:
 
-- **\`external_chatbot\`** — a tester talks to a customer chatbot
+- **\`external_chatbot\`** — a participant talks to a customer chatbot
   endpoint (the original chat behaviour). The endpoint config or saved
   chatbot-endpoint reference lives at
   \`details.mode_details.endpoint\` / \`details.mode_details.chatbot_endpoint_id\`.
-- **\`tester_pair\`** — two AI tester profiles talk to each other.
-  audience_a and audience_b pair 1:1 by index when counts match (N
+- **\`participant_pair\`** — two AI people talk to each other.
+  group_a and group_b pair 1:1 by index when counts match (N
   pairs → N conversations); a side of exactly 1 broadcasts across the
   other side (so 1 × N → N conversations all sharing the lone profile).
   Each side carries its own scenario + goal; the other side does not
@@ -483,13 +483,13 @@ Wire-shape:
   "early_termination": true
 }
 
-// tester_pair (with explicit audiences)
+// participant_pair (with explicit groups)
 {
   "type": "chat",
   "mode_details": {
-    "mode": "tester_pair",
-    "audience_a": ["tp-uuid-1", "tp-uuid-2"],
-    "audience_b": ["tp-uuid-3", "tp-uuid-4"],
+    "mode": "participant_pair",
+    "group_a": ["p-uuid-1", "p-uuid-2"],
+    "group_b": ["p-uuid-3", "p-uuid-4"],
     "scenario_a": "You are a senior sales rep pitching ish.",
     "scenario_b": "You are a skeptical CTO evaluating ish.",
     "initiator_side": "a"
@@ -498,13 +498,13 @@ Wire-shape:
   "early_termination": true
 }
 
-// tester_pair (with role criteria — backend resolves the pool)
+// participant_pair (with role criteria — backend resolves the pool)
 {
   "type": "chat",
   "mode_details": {
-    "mode": "tester_pair",
-    "audience_a": [],
-    "audience_b": [],
+    "mode": "participant_pair",
+    "group_a": [],
+    "group_b": [],
     "role_criteria_a": {
       "occupation": ["founder", "ceo"],
       "min_age": 28, "max_age": 55,
@@ -520,23 +520,23 @@ Wire-shape:
 }
 \`\`\`
 
-## Audience selection (tester_pair)
+## Audience selection (participant_pair)
 
-Each side of a pair needs **either** an explicit audience list **or** a
+Each side of a pair needs **either** an explicit people list **or** a
 role-criteria filter (or both). Three input modes:
 
 | Side A input | Side B input | Behaviour |
 | --- | --- | --- |
-| \`--audience-a\` (UUIDs) | \`--audience-b\` (UUIDs) | Explicit pairing. Equal counts zip 1:1 by index; a side of exactly 1 broadcasts to the other. |
+| \`--group-a\` (UUIDs) | \`--group-b\` (UUIDs) | Explicit pairing. Equal counts zip 1:1 by index; a side of exactly 1 broadcasts to the other. |
 | \`--role-criteria-a\` (JSON) | \`--role-criteria-b\` (JSON) | Backend resolves matching pool from each side's criteria and persists the IDs back to the iteration. |
 | Either flag pair | Either flag pair | Mixed (e.g. explicit A + criteria B). Backend handles each side independently. |
 | Both flags on one side | (any) | Criteria validates the explicit list; mismatch blocks run with a clear error. |
 
-**Persona-first principle**: the tester's persona is sacred — never
+**Persona-first principle**: the participant's persona is sacred — never
 altered by the scenario. Criteria filter the *eligible pool* upstream
-so that by the time a tester reaches the LLM prompt, their persona is
+so that by the time a participant reaches the LLM prompt, their persona is
 already plausible for the role. The prompt construction itself does
-not change between explicit-audience and criteria-driven flows.
+not change between explicit-people and criteria-driven flows.
 
 \`RoleCriteria\` keys (all optional):
 
@@ -554,7 +554,7 @@ not change between explicit-audience and criteria-driven flows.
 If the resolved pool is smaller than the requested conversation count
 for a side, \`ish study run\` exits 2 with the backend's error envelope
 intact. No silent fallback. Broaden the criteria, generate more
-profiles, or pass an explicit \`--audience-*\` list to recover.
+profiles, or pass an explicit \`--group-a/-b\` list to recover.
 
 ## Pair-mode flag names (CLI ↔ MCP alignment)
 
@@ -564,7 +564,7 @@ agent doesn't pay a translation tax when switching surfaces:
 
 | CLI flag                  | MCP field                  | What it carries                                     |
 |---------------------------|----------------------------|-----------------------------------------------------|
-| \`--audience-a\` / \`-b\`   | \`audience_a\` / \`audience_b\` | Explicit tester profile IDs (UUIDs or aliases) for that side. |
+| \`--group-a\` / \`-b\`   | \`group_a\` / \`group_b\` | Explicit person IDs (UUIDs or aliases) for that side. |
 | \`--role-criteria-a\` / \`-b\` | \`role_criteria_a\` / \`role_criteria_b\` | JSON filter (occupation, country, …) the backend resolves into a pool. |
 | \`--scenario-a\` / \`-b\`    | \`scenario_a\` / \`scenario_b\` | The system-prompt-shaped role text injected into one side's prompt only (asymmetry contract). |
 | \`--initiator-side\`        | \`initiator_side\`            | Which side speaks first (\`a\` default).             |
@@ -572,9 +572,9 @@ agent doesn't pay a translation tax when switching surfaces:
 | \`--early-termination\`     | \`early_termination\`         | Allow the worker to end early when parties signal.  |
 
 The pre-2026-05 \`--profile-a\` / \`--profile-b\` CLI flags were
-renamed to \`--audience-a\` / \`--audience-b\` to match the MCP and
-the wire shape (\`mode_details.audience_a\` /
-\`mode_details.audience_b\`). Same intent, same accepted inputs
+renamed to \`--group-a\` / \`--group-b\` to match the MCP and
+the wire shape (\`mode_details.group_a\` /
+\`mode_details.group_b\`). Same intent, same accepted inputs
 (comma-separated UUIDs or aliases, repeatable). \`--role-criteria-a\`
 / \`--role-criteria-b\` were already aligned with MCP and did not
 change.
@@ -592,14 +592,14 @@ ish iteration create --endpoint-config ./bot.json
 ish iteration create --chat-endpoint-id ep-abc --max-turns 10
 ish iteration create --chat-endpoint-json '{"url":"https://..."}'
 
-# tester_pair — two AI audiences, asymmetric per-side scenarios:
-ish iteration create --chat-mode tester_pair \\
-  --audience-a tp-a1,tp-a2 --audience-b tp-b1,tp-b2 \\
+# participant_pair — two AI groups, asymmetric per-side scenarios:
+ish iteration create --chat-mode participant_pair \\
+  --group-a p-a1,p-a2 --group-b p-b1,p-b2 \\
   --scenario-a @./sales_rep.md --scenario-b @./skeptical_cto.md \\
   --max-turns 14
 
-# tester_pair — criteria-driven audience (persona-first filtering):
-ish iteration create --chat-mode tester_pair \\
+# participant_pair — criteria-driven group (persona-first filtering):
+ish iteration create --chat-mode participant_pair \\
   --role-criteria-a '{"occupation":["founder","ceo"],"min_age":28}' \\
   --role-criteria-b @./criteria_investor.json \\
   --scenario-a @./sales_rep.md --scenario-b @./skeptical_cto.md \\
@@ -608,7 +608,7 @@ ish iteration create --chat-mode tester_pair \\
 
 Tunables (both modes):
 - \`--max-turns N\` — cap the conversation length (default 12 for
-  external_chatbot, 14 for tester_pair; persona drift starts ~20 turns
+  external_chatbot, 14 for participant_pair; persona drift starts ~20 turns
   so cap accordingly).
 - \`--early-termination\` — let the worker end the session early when
   the parties signal the conversation is over.
@@ -617,27 +617,27 @@ Pair-mode rules:
 - Each side needs **either** \`--profile-*\` (explicit IDs) **or**
   \`--role-criteria-*\` (filter the backend resolves). The two can also
   be combined — criteria then acts as validation on the explicit list.
-- When both sides use explicit \`--audience-a\` / \`--audience-b\`, they
+- When both sides use explicit \`--group-a\` / \`--group-b\`, they
   must be the same length (≥ 1). Same profile on both sides is allowed
   (self-talk rehearsal). When either side defers to criteria, the
   length match is enforced server-side after pool resolution.
 - **1×N broadcast**: pass exactly one profile on one side and N
   profiles on the other to rehearse the fixed side against N
   variations. The CLI auto-broadcasts the singleton to match length
-  N. Example: \`--audience-a tp-rep --audience-b tp-cto1,tp-cto2,tp-cto3\`
-  produces 3 conversations, all sharing tp-rep on side A. The CLI
+  N. Example: \`--group-a p-rep --group-b p-cto1,p-cto2,p-cto3\`
+  produces 3 conversations, all sharing p-rep on side A. The CLI
   prints a stderr notice so you know broadcasting kicked in.
 - Both \`--scenario-a\` and \`--scenario-b\` are required and asymmetric.
 - \`--initiator-side\` defaults to \`a\` (side A speaks first).
-- \`--chat-mode\` accepts both \`tester_pair\` and \`tester-pair\`
+- \`--chat-mode\` accepts both \`participant_pair\` and \`participant-pair\`
   (hyphenated variants are normalised). Same normalisation applies to
   \`--screen-format\` (\`mobile_portrait\` ↔ \`mobile-portrait\`),
   \`--kind\` on \`source upload\` (\`text_file\` ↔ \`text-file\`), and the
   \`type\` field in \`--questionnaire\` / \`--questions\` manifests
   (\`single-choice\` ↔ \`single_choice\`).
 - Audiences are pinned to the iteration. \`ish study run\` refuses
-  run-time audience overrides (\`--profile\` / \`--sample\` / \`--all\` /
-  filters) on a pair iteration — change the audiences via
+  run-time people overrides (\`--profile\` / \`--sample\` / \`--all\` /
+  filters) on a pair iteration — change the peoples via
   \`ish iteration update <id> --details-json '{...}'\` instead.
 - \`--max-turns\` / \`--early-termination\` on \`ish study run\` override
   the iteration's saved values for that single dispatch (they are not
@@ -704,7 +704,7 @@ persona drift starts to dominate.
 A scenario describes **voice, knowledge, and goal** for one role —
 *not* the demographics of who plays it. Demographic constraints
 ("you are 35-year-old Swedish founder") belong in
-\`--role-criteria-a\` / \`--role-criteria-b\` instead. The tester's
+\`--role-criteria-a\` / \`--role-criteria-b\` instead. The participant's
 persona stays sacred; criteria filter the eligible pool upstream so
 the persona is already plausible for the role by the time the LLM
 sees the prompt. Mixing demographics into the scenario text
@@ -749,20 +749,22 @@ Treat this as actionable, not transient — re-running won't change anything.
 
 - \`concepts/study\` — the parent artifact.
 - \`concepts/run-verbs\` — how \`ish study run\` selects the iteration.
-- \`concepts/audience\` — how testers are picked for a run.
+- \`concepts/people\` — how participants are picked for a run.
 - \`reference/billing-limits\` — \`maxIterationsPerStudy\` cap on iteration creation.
-- \`reference/credits\` — per-iteration-run credit cost & preview shape (\`pair_preview.credit_estimate\` for tester-pair, top-level \`credit_estimate\` otherwise).
+- \`reference/credits\` — per-iteration-run credit cost & preview shape (\`pair_preview.credit_estimate\` for participant-pair, top-level \`credit_estimate\` otherwise).
 `;
 const CONCEPT_ASSIGNMENT = `# concept: assignment
 
-An **assignment** is a single task a tester performs during an
+An **assignment** is a single task a participant performs during an
 interactive study (or considers, for media studies). A study has 1..N
 assignments and they run in order.
 
 Each assignment has:
-- \`name\` — short label shown to the tester ("Sign up").
-- \`instructions\` — what the tester is asked to do ("Complete the signup
+- \`name\` — short label shown to the participant ("Sign up").
+- \`instructions\` — what the participant is asked to do ("Complete the signup
   flow using a personal email").
+- \`steps\` (optional) — an ordered checklist of atomic actions the participant
+  should accomplish (see "Steps" below).
 
 ## CLI input formats
 
@@ -782,27 +784,59 @@ ish study create --name "Checkout" --modality interactive \\
 ish study create … --assignments '[{"name":"Browse","instructions":"…"}]'
 \`\`\`
 
-\`assignments.json\` shape:
+\`assignments.json\` shape (note the optional \`steps\` checklist):
 \`\`\`json
 [
   { "name": "Browse", "instructions": "Find a product you like" },
-  { "name": "Buy",    "instructions": "Add to cart and checkout" }
+  {
+    "name": "Buy",
+    "instructions": "Add to cart and checkout",
+    "steps": [
+      { "name": "Find a product", "description": "Browse to any item" },
+      { "name": "Add to cart" },
+      { "name": "Complete checkout" }
+    ]
+  }
 ]
 \`\`\`
 
+## Steps (checklist)
+
+An assignment may carry an ordered \`steps\` list — atomic actions the participant
+should accomplish. Each step is \`{ "name": "...", "description"?: "..." }\`
+(name 1–80 chars, description ≤500). Steps are authored **only via the JSON
+forms** (\`--assignments-file\` / \`--assignments\`); the inline
+\`--assignment "Name:Instructions"\` shorthand cannot express them.
+
+Steps are honored for **interactive** and **external_chatbot chat** studies
+only. The backend rejects steps on media modalities (text/video/audio/image/
+document) and on chat \`participant_pair\`.
+
+After a run, an LLM verifier grades each step per participant. \`ish study get <id>\`
+then surfaces, on each assignment:
+- \`steps\` — the resolved checklist, each with a server-assigned \`id\` (a slug
+  like \`add-to-cart\`).
+- \`step_completion\` — a per-step rollup: \`step_id\`, \`total\`, \`passed\`,
+  \`rate\` (null until graded), and up to 3 \`sample_failures\`
+  (\`{participant_id, reason}\`). Human output shows a pass-rate line per step;
+  \`sample_failures[].participant_id\` is a UUID, so it only appears under
+  \`--verbose\` in JSON mode.
+
 ## Update or replace
 
 \`ish study update <id> --assignment …\` (or \`--assignments-file\`)
-replaces the full assignment list — additive editing is not supported.
+replaces the full assignment list — additive editing is not supported. Steps
+ride along when present in the JSON forms.
 
 ## Related
 
 - \`concepts/study\` — assignments are immutable to the run; questionnaire is too.
 - \`concepts/questionnaire\` — the other half of the study definition.
+- \`reference/json-mode\` — how \`step_completion\` renders in lean vs --verbose.
 `;
 const CONCEPT_QUESTIONNAIRE = `# concept: questionnaire
 
-The **questionnaire** is the list of \`interview_questions\` a tester
+The **questionnaire** is the list of \`interview_questions\` a participant
 answers before or after their assignments. A study has 0..N
 questions, each with a type and a timing.
 
@@ -848,20 +882,20 @@ so either works in your manifest.
 const CONCEPT_ASK = `# concept: ask
 
 An **ask** is a lightweight reaction artifact — much less ceremony than
-a study. It has an audience (fixed at creation) and a sequence of
-**rounds**. Each round shows the audience a prompt plus 1..N variants
+a study. It has a group of people (fixed at creation) and a sequence of
+**rounds**. Each round shows the people a prompt plus 1..N variants
 (text or image) and collects their reactions.
 
 - Alias prefix: \`a-\`
-- Audience is fixed at ask creation — you cannot swap audiences between
-  rounds. (You can extend it via \`ish ask add-testers\`.)
+- Audience is fixed at ask creation — you cannot swap groups between
+  rounds. (You can extend it via \`ish ask add-people\`.)
 - Up to 5 rounds per ask.
 
 ## When to use ask vs study
 
 - Reach for **ask** for: tagline A/B, hero-image picks, copy comparisons,
   quick reactions to creative variants.
-- Reach for **study** for: anything that needs a tester to *do* something
+- Reach for **study** for: anything that needs a participant to *do* something
   (interactive flow, multi-step task, time-on-page).
 
 See \`concepts/run-verbs\` for the side-by-side.
@@ -903,11 +937,11 @@ intact — no \`--verbose\` needed to see it.
 
 ## Stage-then-dispatch (draft asks)
 
-When you want a human to review the audience and prompt **before** any
+When you want a human to review the people and prompt **before** any
 credits are spent, separate creation from dispatch:
 
 \`\`\`
-# 1. Stage — materializes testers, no worker enqueue, no bill yet
+# 1. Stage — materializes participants, no worker enqueue, no bill yet
 ish ask create --workspace w-6ec --name "tagline AB" \\
     --prompt "Which sounds better?" \\
     --variant text:"Short and punchy." \\
@@ -921,7 +955,7 @@ ish ask create --workspace w-6ec --name "tagline AB" \\
 ish ask dispatch a-6ec --wait
 \`\`\`
 
-\`--no-dispatch\` requires audience flags (testers are still materialized
+\`--no-dispatch\` requires people flags (participants are still materialized
 at create time — only the worker enqueue and billing are deferred). It
 is incompatible with \`--wait\` since there is nothing to wait for.
 
@@ -986,7 +1020,7 @@ When the ask has 2+ rounds, \`ask results\` also includes a top-level
 \`ish ask retry <ask> --round N\` re-dispatches only the ERRORED
 responses on a round. COMPLETED responses are left untouched (their
 answers are the source of truth). Use this after a partial failure
-(e.g. 4 of 5 testers errored on round 1) — fix the underlying cause,
+(e.g. 4 of 5 participants errored on round 1) — fix the underlying cause,
 then \`ask retry\` to backfill the missing rows. Idempotent: zero-errored
 is a no-op. Add \`--wait\` to block until the retried round settles.
 
@@ -1004,7 +1038,7 @@ abort without parsing prose.
 \`ish ask add-questions --round N --questions ./qs.json\` is **additive
 by default**: prior phase-1 outputs (comment, pick, ratings) are
 preserved on every non-errored response, and the worker only answers
-the newly-added questions for each tester. Existing picks stay stable.
+the newly-added questions for each participant. Existing picks stay stable.
 
 Pass \`--redispatch-all\` for the legacy reset behavior — useful when a
 question is sufficiently different that you want fresh first
@@ -1033,11 +1067,11 @@ round-trips when you know them up front:
   agent-tool result budgets. Pass
   \`include_accessibility_profile=true\` to include it. Mirrors the
   existing \`include_bio=false\` default — same opt-in pattern.
-- **\`ask_testers\` uses \`dispatch_into_round\`, not \`round\`.** The
+- **\`ask_participants\` uses \`dispatch_into_round\`, not \`round\`.** The
   parameter name was renamed from the ambiguous \`round\` (which read
   as "start from round N") to the verbatim \`dispatch_into_round\`
-  ("add these new testers into round N"). Behavior is unchanged —
-  it appends testers to the named round on an existing ask, it does
+  ("add these new participants into round N"). Behavior is unchanged —
+  it appends participants to the named round on an existing ask, it does
   not roll back or restart any prior round.
 
 ## Variant syntax
@@ -1052,14 +1086,14 @@ round-trips when you know them up front:
 ## Related
 
 - \`concepts/round\` — what a round is and how it executes.
-- \`concepts/audience\` — how testers are chosen at ask creation.
+- \`concepts/people\` — how participants are chosen at ask creation.
 - \`concepts/run-verbs\` — \`ish ask run\` vs \`ish study run\`.
 - \`reference/credits\` — ask rounds bill 1 credit per successful response.
 `;
 const CONCEPT_ROUND = `# concept: round
 
 A **round** is the unit of execution within an ask. Each round shows the
-ask's audience a prompt + variants and collects reactions.
+ask.s participants a prompt + variants and collects reactions.
 
 - Up to 5 rounds per ask.
 - Rounds are 1-indexed in user-facing flags (\`--round 2\`) but stored
@@ -1081,7 +1115,7 @@ ish ask results a-6ec --round 1
 
 Appending questions to a completed round preserves prior data — variant
 comments, picks, ratings, and earlier-question answers all stay. Only
-the new question(s) get dispatched to the existing testers. Cost is
+the new question(s) get dispatched to the existing participants. Cost is
 roughly N phase-2 LLM calls instead of 2N (no phase-1 re-run). Errored
 responses are skipped entirely; completed responses flip to PENDING and
 re-finalize after the new question is answered.
@@ -1089,51 +1123,67 @@ re-finalize after the new question is answered.
 ## Related
 
 - \`concepts/ask\` — the parent artifact.
-- \`concepts/audience\` — fixed at ask creation; rounds reuse it.
+- \`concepts/people\` — fixed at ask creation; rounds reuse it.
 `;
-const CONCEPT_PROFILE = `# concept: tester profile
+const CONCEPT_PROFILE = `# concept: person
 
-A **tester profile** is a reusable audience persona — the simulated
-human whose behaviour drives a tester instance during a study or ask.
+A **person** is a reusable persona — the simulated
+human whose behaviour drives a participant instance during a study or ask.
 
 - Alias prefix: \`tp-\`
 - Lives at the workspace level, reusable across studies and asks.
-- Distinct from a "tester" (\`t-\`) — a tester is one *instance* of a
+- Distinct from a "participant" (\`pt-\`) — a participant is one *instance* of a
   profile inside one iteration.
 
 ## Generation vs. manual creation
 
-\`ish profile generate\` runs the same audience-generation flow used in
-the web UI: an LLM reads your description and any uploaded sources
-(transcripts, customer records, audio, images) and returns either a
-single profile or a full audience.
+\`ish person generate\` runs an agentic generation job: it reads your
+description (a researcher brief) and any uploaded sources (transcripts,
+emails, customer records, audio, images) describing how real people
+reacted, then produces people PLUS scenarios grounded in those
+reactions. It is async — ish enqueues the job, polls until it's done
+(~30-60s), then prints the resulting profile(s) with their scenarios.
+Provide \`--description\` (>=10 chars) and/or at least one \`--source\`.
 
 \`\`\`
 # 5 profiles from a written brief:
-ish profile generate \\
+ish person generate \\
     --description "Tech-savvy millennials in the US who use mobile banking" \\
     --count 5
 
 # One profile from a transcript (auto-uploaded):
-ish profile generate --source ./interviews/sarah.txt --count 1
+ish person generate --source ./interviews/sarah.txt --count 1
 
 # Audio with diarization:
-ish profile generate --description "Voices behind support tickets" \\
+ish person generate --description "Voices behind support tickets" \\
     --source ./call.mp3 --diarize --count 3
+
+# Ground a profile in how someone reacted to a real artifact:
+ish source upload ./proposal.eml --description "called this proposal lazy and vague"
+# → ps-3a4
+ish person generate --description "Skeptical enterprise buyer" \\
+    --source ps-3a4 --count 1 --json
 \`\`\`
 
+The per-source \`--description\` (set on \`source upload\`, or
+\`--source-description\` on an inline path) is the researcher note: how
+that person reacted to THAT file. The job grounds each scenario in those
+notes plus the source content. Pass \`--no-scenarios\` to skip fetching
+the scenarios. The job keeps running server-side past \`--timeout\`
+(default 600s) — re-poll the job, don't re-enqueue.
+
 For explicit control over uploads (reusing one source across runs):
 
 \`\`\`
 ish source upload ./call.mp3 --diarize
-# → tps-3a4 (status: processed)
-ish profile generate --source tps-3a4 --count 4
+# → ps-3a4 (status: processed)
+ish person generate --source ps-3a4 --count 4
 \`\`\`
 
 ## Manual create
 
 \`\`\`
-ish profile create --file profile.json
+ish person create --file profile.json
 \`\`\`
 
 Expected JSON: \`{ "name": "...", "type": "ai", "gender": "female",
@@ -1141,10 +1191,12 @@ Expected JSON: \`{ "name": "...", "type": "ai", "gender": "female",
 
 ## Generation behavior to expect
 
-- **Latency**: \`profile generate\` is LLM-backed and typically takes
-  10–20s for 1–5 profiles. The CLI emits stderr progress lines
-  (\`generating N profiles…\` then \`generated N profiles\`) so you
-  know it's not stuck. Suppress with \`--quiet\`.
+- **Latency**: \`person generate\` runs an async job that typically
+  takes ~30-60s. The CLI enqueues, then polls every ~2.5s and prints a
+  stderr status line each time the job's progress message changes, so you
+  know it's not stuck. Suppress with \`--quiet\`. Bound the wait with
+  \`--timeout\` (seconds, default 600); on timeout the job keeps running
+  server-side, so re-poll rather than re-enqueueing.
 - **Brief fidelity**: bios reference domain-specific terms from your
   description verbatim or as close paraphrase. If you mention
   \`F-skatt\`, "manual Excel invoicing", "Stripe payouts", or similar
@@ -1152,16 +1204,16 @@ Expected JSON: \`{ "name": "...", "type": "ai", "gender": "female",
   each generated bio's daily-routine framing — not sanded down to
   generic prose.
 - **DOB diversity**: month-and-day are derived from a deterministic
-  per-profile hash so birthdays spread across the year (no more
-  every-profile-on-\`06-15\`). Year follows the requested age.
+  per-person hash so birthdays spread across the year (no more
+  every-person-on-\`06-15\`). Year follows the requested age.
   Re-generating the same name/country/occupation/age yields the
   same DOB.
 
-## Structured profile fields
+## Structured person fields
 
 Five universal enums + a versioned accessibility JSONB live on every
-TesterProfile. Values are snake_case and match
-\`https://ishlabs.io/spec/profile-enums.v1.json\` byte-for-byte.
+Person. Values are snake_case and match
+\`https://ishlabs.io/spec/person-enums.v1.json\` byte-for-byte.
 
 - \`education_level\`: \`less_than_secondary\`, \`secondary\`,
   \`some_post_secondary\`, \`vocational_or_associate\`, \`bachelor\`, \`graduate\`
@@ -1182,12 +1234,12 @@ TesterProfile. Values are snake_case and match
   \`auditory\`, \`motor\`, \`cognitive\`, \`data\` groups, plus
   \`assistive_tech: string[]\` and \`notes\`. Empty \`{}\` means "no
   accessibility configuration declared". Schema:
-  \`https://ishlabs.io/spec/accessibility-profile-schema.v1.json\`.
+  \`https://ishlabs.io/spec/accessibility-person-schema.v1.json\`.
 
-Set them on \`ish profile update\`:
+Set them on \`ish person update\`:
 
 \`\`\`
-ish profile update tp-1b9 \\
+ish person update p-1b9 \\
     --education-level bachelor \\
     --household couple_with_kids \\
     --locale-type suburban \\
@@ -1195,33 +1247,33 @@ ish profile update tp-1b9 \\
     --employment-status employed_full_time
 
 # accessibility_profile accepts inline JSON or a path:
-ish profile update tp-1b9 --accessibility-profile '{
+ish person update p-1b9 --accessibility-profile '{
   "version": "1.0",
   "visual": {"uses_screen_reader": true, "text_size": "large"},
   "cognitive": {"reduce_motion": true},
   "assistive_tech": ["VoiceOver"]
 }'
 
-ish profile update tp-1b9 --accessibility-profile ./a11y.json
+ish person update p-1b9 --accessibility-profile ./a11y.json
 \`\`\`
 
 The legacy \`--tech-savviness\` flag was removed in
-\`profile-schema-v2\`; passing it now produces commander's standard
+\`person-schema-v2\`; passing it now produces commander's standard
 "unknown option" error.
 
 ## Related
 
-- \`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\`)
+- \`concepts/source\` — the inputs to \`person generate\`.
+- \`concepts/people\` — how profiles get selected into a run.
+- \`guides/build-specific-person\` — iterative probe loop
+  (\`person suggest-scenarios\` + \`person evidence add\`/\`list\`)
   for crafting one specific persona, distinct from the
-  audience-generation flow.
-- \`reference/billing-limits\` — \`maxCustomTesterProfiles\` cap on profile creation.
+  people-generation flow.
+- \`reference/billing-limits\` — \`maxCustomPersons\` cap on person creation.
 `;
 const CONCEPT_SOURCE = `# concept: source
 
-A **source** is an input to \`ish profile generate\`: a transcript,
+A **source** is an input to \`ish person generate\`: a transcript,
 audio file, image, or PDF that an LLM reads to ground generated profiles
 in real customer evidence.
 
@@ -1231,36 +1283,36 @@ in real customer evidence.
 
 ## Two ways to use a source
 
-1. **Inline** — pass a local file directly to \`profile generate\`. The
+1. **Inline** — pass a local file directly to \`person generate\`. The
    file is uploaded and processed in-line:
    \`\`\`
-   ish profile generate --source ./call.mp3 --diarize --count 3
+   ish person generate --source ./call.mp3 --diarize --count 3
    \`\`\`
 
 2. **Upload-then-reuse** — upload once, reference the alias from many
    \`generate\` runs:
    \`\`\`
    ish source upload ./call.mp3 --diarize
-   # → tps-3a4 (status: processed)
-   ish profile generate --source tps-3a4 --count 4
+   # → ps-3a4 (status: processed)
+   ish person generate --source ps-3a4 --count 4
    \`\`\`
 
 ## Inspect
 
 \`\`\`
-ish source get tps-3a4
+ish source get ps-3a4
 \`\`\`
 
 ## Related
 
-- \`concepts/profile\` — sources feed profile generation.
+- \`concepts/person\` — sources feed profile generation.
 `;
-const CONCEPT_AUDIENCE = `# concept: audience selection
+const CONCEPT_PEOPLE = `# concept: people selection
 
-Both \`ish study run\` and \`ish ask run --new\` accept the same audience
+Both \`ish study run\` and \`ish ask run --new\` accept the same people-selection
 flags. Two ways to select:
 
-1. **Explicit profile IDs** — \`--profile tp-795,tp-af2\` (or repeated).
+1. **Explicit profile IDs** — \`--person p-795,p-af2\` (or repeated).
 2. **Demographic-filtered sample from the workspace pool** — combine any
    of the filters with \`--sample <N>\` or \`--all\` / \`--all-simulatable\`:
    - \`--country SE,NO\`  (repeatable)
@@ -1285,14 +1337,14 @@ the filter set, not both.
 When a filter combination matches zero profiles, the error message
 includes the top three populated countries that satisfy your *other*
 filters — so you can pivot to a country with actual coverage without a
-second \`profile list\` round-trip:
+second \`person list\` round-trip:
 
 \`\`\`
 $ ish study run --country XX --min-age 35 --sample 5
-Error: No simulatable AI tester profiles in workspace w-b32 match:
+Error: No simulatable AI people in workspace w-b32 match:
        --country XX --min-age 35.
        Populated countries with these other filters: SE (12), DE (8), NL (3).
-       Broaden your filters or run \`ish profile list\` to inspect the pool.
+       Broaden your filters or run \`ish person list\` to inspect the pool.
 \`\`\`
 
 The suggestion is best-effort — it never replaces the original error,
@@ -1300,13 +1352,13 @@ just augments it.
 
 ## Audience-build behaviors to know before dispatch
 
-Two adjacent footguns surface most often on first-time audience
+Two adjacent footguns surface most often on first-time people
 construction. Both are documented here because they cost a round-trip
 to discover by experiment.
 
 ### \`--occupation\` is a loose substring match
 
-\`audience_build\` and the \`--occupation\` flag treat the value as a
+\`group_build\` and the \`--occupation\` flag treat the value as a
 **loose, case-insensitive substring filter**, not a whole-token or
 taxonomy match. \`--occupation manager\` will match hotel managers,
 retail store managers, bank branch managers: anything containing the
@@ -1321,7 +1373,7 @@ you usually want:
 - **Pair with other filters**: \`--occupation manager --min-age 28
   --country US --country SE\` narrows even a loose substring
   meaningfully.
-- **Preview before dispatch**: \`audience_build\` returns a
+- **Preview before dispatch**: \`group_build\` returns a
   \`match_preview\` summary on the response — a 1-line histogram of
   matched occupations (e.g. \`"matched 17 — software developer (12),
   DevOps engineer (3), other (2)"\`). Read it before
@@ -1330,34 +1382,34 @@ you usually want:
 
 ### The public profile pool skews non-tech / non-Western
 
-The default public tester-profile pool was built from a broad
+The default public person pool was built from a broad
 demographic sample — so a substring like \`"software engineering
 manager"\` may return only a handful of matches, while \`"hotel
 manager"\` or \`"retail associate"\` return many. Two adaptations:
 
-- **Don't assume Silicon Valley defaults.** A criteria-driven audience
+- **Don't assume Silicon Valley defaults.** A criteria-driven group
   that works on a private testing pool may resolve to a much smaller
   count in the public pool. Read the \`match_preview\` (or count) on
-  every \`audience_build\` before dispatching a run that depends on
+  every \`group_build\` before dispatching a run that depends on
   reaching N matches.
 - **Seed your own pool when you need a specific archetype.** If the
-  public pool is genuinely thin for your role, generate the audience
-  yourself via \`ish profile generate --description "..."\` — that
+  public pool is genuinely thin for your role, generate the people
+  yourself via \`ish person generate --description "..."\` — that
   produces profiles plausible for the role you described, regardless
-  of public-pool composition. See \`concepts/profile\`.
+  of public-pool composition. See \`concepts/person\`.
 
 ## Defaults
 
-- \`ish study run\` with no audience flags → reuses the iteration's
-  existing testers. Ideal for re-running the same audience.
-- \`ish ask run\` (without \`--new\`) → cannot change audience; the ask
+- \`ish study run\` with no people flags → reuses the iteration's
+  existing participants. Ideal for re-running the same participants.
+- \`ish ask run\` (without \`--new\`) → cannot change participants; the ask
   fixes it at creation. Audience flags only apply with \`--new\`.
 
 ## Examples
 
 \`\`\`
 # Explicit:
-ish study run --profile tp-795,tp-af2
+ish study run --person p-795,p-af2
 
 # Sample 3 Swedish profiles aged 35-50:
 ish study run --country SE --min-age 35 --max-age 50 --sample 3
@@ -1371,7 +1423,7 @@ ish study run --bio "screen reader" --all
 # Every female profile in the workspace:
 ish study run --gender female --all
 
-# Ask + audience in one shot:
+# Ask + people in one shot:
 ish ask run --new --name "SE 35-50" --prompt "Which sounds better?" \\
     --variant text:"A" --variant text:"B" \\
     --country SE --min-age 35 --max-age 50 --sample 10
@@ -1379,14 +1431,14 @@ ish ask run --new --name "SE 35-50" --prompt "Which sounds better?" \\
 
 ## Related
 
-- \`concepts/profile\` — generate profiles to fill the pool.
-- \`concepts/run-verbs\` — when audience flags apply.
+- \`concepts/person\` — generate profiles to fill the pool.
+- \`concepts/run-verbs\` — when people flags apply.
 `;
 const CONCEPT_SITE_ACCESS = `# concept: site access
 
 For interactive studies that target a gated URL — HTTP basic auth,
 session-cookie walls (Vercel preview, Lovable, etc.), or login forms —
-configure credentials on the workspace once. Testers reuse them when a
+configure credentials on the workspace once. Participants reuse them when a
 study points at a matching origin.
 
 Credentials are encrypted at rest. The CLI never reads them back; it
@@ -1404,7 +1456,7 @@ ish workspace site-access basic-auth --username alice --password hunter2
 # Session cookie:
 ish workspace site-access cookie --name session --value abc123
 
-# Login form (typed by the tester):
+# Login form (typed by the participant):
 ish workspace site-access login --username demo --password demo
 
 # Mark as public (silence the "credentials needed?" prompt):
@@ -1495,7 +1547,7 @@ or shouldn't be committed to a config JSON file, use a secret.
 `;
 const CONCEPT_RUN_VERBS = `# concept: run verbs — \`study run\` vs \`ask run\`
 
-Both verbs dispatch simulations against an audience, but the lifecycle
+Both verbs dispatch simulations against a group of people, but the lifecycle
 and what they target differ.
 
 ## Side by side
@@ -1505,23 +1557,23 @@ and what they target differ.
 | Default        | latest iteration of the active study             | append a round to the active ask              |
 | Fresh setup    | \`ish iteration create …\` first, then run         | \`--new\` (creates ask + round 1 in one shot) |
 | Specific target| \`--iteration <id>\`                               | positional ask id (\`a-6ec\`)                 |
-| Audience       | \`--profile\` OR filters with \`--sample\`/\`--all\` — else reuse iteration's testers | only at \`--new\`; fixed for the ask afterwards |
-| Output unit    | per-tester interactions + questionnaire answers  | per-tester reactions per round                |
+| Audience       | \`--profile\` OR filters with \`--sample\`/\`--all\` — else reuse iteration's participants | only at \`--new\`; fixed for the ask afterwards |
+| Output unit    | per-participant interactions + questionnaire answers  | per-participant reactions per round                |
 
 ## Decision rule
 
-- The tester needs to **do** something on a real surface
+- The participant needs to **do** something on a real surface
   (URL/app/document)? → study.
-- The tester needs to **react** to one or more variants
+- The participant needs to **react** to one or more variants
   (text/image) of creative? → ask.
 
 ## Common commands
 
 \`\`\`
-# Study — reuse iteration testers, block until done:
+# Study — reuse iteration participants, block until done:
 ish study run --wait
 
-# Study — fresh audience by demographic:
+# Study — fresh group by demographic:
 ish study run --country SE --min-age 35 --sample 3
 
 # Ask — append a round:
@@ -1533,35 +1585,35 @@ ish ask run --new --name "tagline AB" \\
     --variant text:"A" --variant text:"B" --sample 30 --wants-pick --wait
 \`\`\`
 
-## Tracking individual testers after \`study run\`
+## Tracking individual participants after \`study run\`
 
-\`ish study run --json\` returns a top-level \`tester_aliases[]\` and
-\`tester_ids[]\` for the testers it just dispatched. Pass either to the
+\`ish study run --json\` returns a top-level \`participant_aliases[]\` and
+\`participant_ids[]\` for the participants it just dispatched. Pass either to the
 low-level lifecycle verbs:
 
 \`\`\`
-ish study run --study s-b2c -y --json | jq -r '.tester_aliases[]'   # → t-072, t-1ed, ...
+ish study run --study s-b2c -y --json | jq -r '.participant_aliases[]'   # → pt-072, pt-1ed, ...
 
-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
+ish study poll <participant_id>                # one-shot status for one participant
+ish study wait <participant_id> --timeout 600  # block until that participant finishes
+ish study cancel <participant_id>              # cancel a running simulation
+ish study extend <participant_id> --add-steps 10   # resume a terminal participant with N more steps
 \`\`\`
 
-\`<tester_id>\` accepts a tester alias (\`t-…\`) or a full UUID. The
+\`<participant_id>\` accepts a participant 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
+walks a running participant to a terminal \`cancelled\` status (no row
+removed); \`extend\` then spawns a fresh participant branched from the
+cancelled participant'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
+  Use \`--get participant_aliases\` to capture the run's participants without
   piping through \`jq\`. \`--human\` forces table output even through
   \`tee\`/redirection.
 - \`concepts/extending-a-simulation\` — \`study extend\` flow, when to
@@ -1569,58 +1621,58 @@ cancelled tester's last interaction. See
 `;
 const CONCEPT_EXTENDING_SIMULATION = `# concept: extending a simulation
 
-\`ish study extend <tester_id>\` resumes a **terminal** tester with
+\`ish study extend <participant_id>\` resumes a **terminal** participant with
 more interactions — and optionally a mid-run instruction. The source
-tester is left untouched; a **new** tester row is spawned under the
+participant is left untouched; a **new** participant 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
+when a run hits the \`--max-interactions\` cap before the participant
 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
+- Run hit the step cap (\`--max-interactions\`) before the participant
   completed the assignment — give it 10 more steps to push through.
-- Tester veered off into a dead-end — cancel it, then extend with an
+- Participant 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
+- You want to test how a participant 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.
+- Source participant 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\`
+- You want a fresh cohort with new people flags. Use \`study run\`
   with \`--profile\` / \`--sample\` / \`--all\` instead — extend is a
-  per-tester resume, not a batch op.
+  per-participant 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:
+\`cancel\` and \`extend\` are siblings in the participant lifecycle:
 
 \`\`\`
-  RUNNING ──(cancel)──▶ CANCELLED ──(extend)──▶ new RUNNING tester
+  RUNNING ──(cancel)──▶ CANCELLED ──(extend)──▶ new RUNNING participant
                                                 (branched from the
-                                                 cancelled tester's
+                                                 cancelled participant's
                                                  last interaction)
 
-  COMPLETED / FAILED ──(extend)──▶ new RUNNING tester
+  COMPLETED / FAILED ──(extend)──▶ new RUNNING participant
 \`\`\`
 
-\`cancel\` is non-destructive — the tester row, every interaction, every
+\`cancel\` is non-destructive — the participant 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
+forks from the last interaction to keep the new participant's history
 seamlessly continuous.
 
 ## Flags
 
 \`\`\`
-ish study extend <tester_id>
+ish study extend <participant_id>
     [--add-steps <n>]                 # extra steps, 1-50, default 10
     [--instruction <text|@path|->]    # optional mid-run user message
     [--wait]                          # block until terminal
@@ -1633,17 +1685,17 @@ CLI:
 
 \`\`\`bash
 # Inline:
-ish study extend t-072 --instruction "Switch to the German pricing page."
+ish study extend pt-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
+ish study extend pt-072 --instruction @/tmp/redirect.md
 
 # From stdin (pipe-friendly):
-echo "Try the search bar instead." | ish study extend t-072 --instruction -
+echo "Try the search bar instead." | ish study extend pt-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 —
+participant 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.
@@ -1654,10 +1706,10 @@ Default (no \`--wait\`):
 
 \`\`\`json
 {
-  "tester_id": "<new-uuid>",
-  "tester_alias": "t-xyz",
-  "source_tester_id": "<source-uuid>",
-  "source_alias": "t-abc",
+  "participant_id": "<new-uuid>",
+  "participant_alias": "pt-xyz",
+  "source_participant_id": "<source-uuid>",
+  "source_alias": "pt-abc",
   "study_id": "<study-uuid>",
   "job_id": "<job-uuid>",
   "additional_steps": 10,
@@ -1666,7 +1718,7 @@ Default (no \`--wait\`):
 }
 \`\`\`
 
-With \`--wait\`, a \`result\` field is appended once the new tester
+With \`--wait\`, a \`result\` field is appended once the new participant
 reaches a terminal status:
 
 \`\`\`json
@@ -1675,31 +1727,31 @@ reaches a terminal status:
   "result": {
     "status": "completed",
     "interaction_count": 14,
-    "tester_name": "Anna, 34, Munich"
+    "participant_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
+UUID fields (\`participant_id\`, \`source_participant_id\`, \`study_id\`, \`job_id\`)
+are preserved in lean output because the new \`participant_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 |
+| Source not terminal (RUNNING / QUEUED) | \`Participant is still running — cancel it first or wait for completion.\` | 2 |
+| Source participant not found | \`Participant 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 |
+| 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-participant>\` | 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\`
+participant. 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
@@ -1707,25 +1759,25 @@ costs **5 credits**. See \`reference/credits\` for the full table.
 \`\`\`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)
+# → participant pt-072 (status: completed_with_errors, hit cap on step 5)
 
 # 2. Inspect what happened:
-ish study tester t-072 --summary
+ish study participant pt-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
+ish study extend pt-072 --add-steps 15 --wait --timeout 600
+# → new participant pt-9af, status: completed, 18 interactions total
 
-# 4. Read the new tester's transcript:
-ish study tester t-9af --summary
+# 4. Read the new participant's transcript:
+ish study participant pt-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 \\
+# Participant wandered into the wrong flow. Cancel, then redirect:
+ish study cancel pt-072
+ish study extend pt-072 \\
     --instruction "Stop browsing the blog. Open the pricing page and try to upgrade to Pro." \\
     --add-steps 10 --wait
 \`\`\`
@@ -1737,8 +1789,8 @@ ish study extend t-072 \\
 - \`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.
+- \`reference/json-mode\` — capture-mode (\`--get participant_alias\`) for
+  chaining the new participant into the next call.
 `;
 const REFERENCE_ALIASES = `# reference: aliases
 
@@ -1752,9 +1804,9 @@ time the CLI sees an entity.
 - \`w-\`    workspace
 - \`s-\`    study
 - \`i-\`    iteration
-- \`t-\`    tester (instance of a profile in an iteration)
-- \`tp-\`   tester profile
-- \`tps-\`  tester-profile source
+- \`pt-\`   participant (instance of a person in an iteration)
+- \`tp-\`   person
+- \`tps-\`  person source
 - \`a-\`    ask
 - \`r-\`    ask round
 - \`c-\`    config (simulation config)
@@ -1766,8 +1818,8 @@ time the CLI sees an entity.
 \`\`\`
 ish iteration create --study s-b2c --url https://example.com
 ish iteration get i-d4e
-ish study tester t-a17
-ish profile generate --source tps-3a4 --count 4
+ish study participant pt-a17
+ish person generate --source ps-3a4 --count 4
 \`\`\`
 
 The full UUID is also always accepted. Add \`--verbose\` to JSON output
@@ -1776,7 +1828,7 @@ to see UUIDs alongside aliases.
 const REFERENCE_SCREENSHOTS = `# reference: screenshots and iteration media
 
 Interactive study runs produce per-frame screenshots server-side. They
-let you (or an agent) see what testers actually saw alongside the
+let you (or an agent) see what participants actually saw alongside the
 sentiment summary.
 
 ## Screenshots — interactive studies only
@@ -1794,14 +1846,14 @@ ish study screenshots download <study-id> --all --out ./shots/
 \`\`\`
 
 The list is grouped by frame. Each frame represents a distinct viewport
-testers landed on (e.g. the hero, the pricing block, a documentation
+participants landed on (e.g. the hero, the pricing block, a documentation
 page). Pulling every screenshot can be heavy — start with the listing,
 then download representative frames.
 
 ### MCP (agent-facing)
 
 \`ish-mcp\` exposes the same artifacts as MCP Resources so an agent can
-look at them inline. \`study_get(view='summary' | 'per_tester')\` on an
+look at them inline. \`study_get(view='summary' | 'per_participant')\` on an
 interactive study now carries:
 
 - \`screenshots_resource: ish://study/<id>/screenshots\` — JSON index
@@ -1862,7 +1914,7 @@ post-process CLI output with \`jq\` or \`python\` for routine tasks:
 |-------------------------------------------|--------------------------------------------------|
 | Show the user a list of workspaces        | bare command (TTY) or \`--human\` if redirecting   |
 | Capture an alias for a follow-up command  | \`--get alias\`                                   |
-| Inspect a specific nested field           | \`--get tester_profile.name\`                     |
+| Inspect a specific nested field           | \`--get person.name\`                     |
 | Compare 2+ fields, or pipe into jq        | \`--json\` (or auto-on when piped)                |
 | Force human output through \`tee\`         | \`--human\`                                       |
 | Force JSON on a TTY                       | \`--json\`                                        |
@@ -1902,7 +1954,7 @@ ish ask results "$ASK" --human | tee /tmp/transcript.txt
                           \`--get\`.
 - \`--get <field>\`      — extract a single field from the JSON response
                           and print only its bare value. Supports dotted
-                          paths (\`tester_profile.name\`). On a paginated
+                          paths (\`person.name\`). On a paginated
                           \`{items: [...]}\` response, the path
                           auto-descends into \`items\` so \`--get alias\`
                           on a list yields one value per line. Implies
@@ -1955,10 +2007,12 @@ The CLI guarantees these contracts so agents can chain safely:
   \`--fields\` set, you can identify the affected resource. Default
   write-path JSON is compact (\`{id, alias, name, updated_at,
   ...changed_fields}\`); pass \`--verbose\` for the full server payload.
-- **\`profile generate\` trims \`simulation_config\` by default** (~9×
-  smaller than the raw response). Pass \`--include-simulation-config\`
-  if you need it.
-- **\`<entity> get\` accepts multiple IDs.** \`profile get\`, \`study get\`,
+- **\`person generate\` returns \`{job: {id, status, person_ids},
+  profiles: [...]}\`** in \`--json\` mode. Each profile is the
+  lean \`person\` shape (pass \`--verbose\` for the full record,
+  including \`simulation_config\`) with its evidence-grounded
+  \`scenarios\` attached; pass \`--no-scenarios\` to omit them.
+- **\`<entity> get\` accepts multiple IDs.** \`person get\`, \`study get\`,
   \`iteration get\`, and \`ask get\` all take \`<ids...>\` — pass two or
   more aliases (space- or comma-separated) and the response is a
   \`{items:[...], total:N}\` envelope. Use this instead of piping
@@ -1969,7 +2023,7 @@ The CLI guarantees these contracts so agents can chain safely:
 
   \`\`\`json
   {
-    "testers_count":      3,
+    "participants_count":      3,
     "responses_total":    9,
     "responses_complete": 9,
     "rounds": [
@@ -1979,13 +2033,13 @@ The CLI guarantees these contracts so agents can chain safely:
   \`\`\`
 
   \`responses_errored\` only appears when at least one response errored.
-  Use these instead of \`jq '.testers | length'\` /
+  Use these instead of \`jq '.participants | length'\` /
   \`jq '.rounds[0].responses | length'\`.
-- **\`study run --json\` exposes tester handles.** The top-level
-  \`tester_ids[]\` and \`tester_aliases[]\` arrays are the canonical
+- **\`study run --json\` exposes participant handles.** The top-level
+  \`participant_ids[]\` and \`participant_aliases[]\` arrays are the canonical
   inputs to \`ish study poll/wait/cancel\`. The \`simulations[]\` array
   is collapsed to one batch entry per study (M13) with nested
-  \`tester_ids[]\`, \`tester_aliases[]\`, \`job_ids[]\`, and \`count\` —
+  \`participant_ids[]\`, \`participant_aliases[]\`, \`job_ids[]\`, and \`count\` —
   an N-sample dispatch is a single row, not N near-duplicate rows.
 - **\`study\` JSON includes a \`url\` field.** \`study create\`,
   \`study generate\`, \`study get\`, \`study list\` (per item), and
@@ -1998,27 +2052,44 @@ The CLI guarantees these contracts so agents can chain safely:
   with the \`ISH_APP_URL\` env var for staging or self-hosted UIs.
 - **\`study results --json\` includes per-answer sentiment** (M10).
   Every \`interview_answers[].answers[]\` row carries \`sentiment\`
-  (the tester's session-level label from \`tester_summary.sentiment\`),
-  and every \`testers[]\` row carries \`sentiment\` + \`comment\`. No
-  \`study tester <id>\` round-trip required.
+  (the participant's session-level label from \`participant_summary.sentiment\`),
+  and every \`participants[]\` row carries \`sentiment\` + \`comment\`. No
+  \`study participant <id>\` round-trip required.
 - **\`study results --summary\`** is a lean projection: counts +
-  sentiment histogram + per-tester {alias, status, sentiment, comment,
+  sentiment histogram + per-participant {alias, status, sentiment, comment,
   error_message}. Drops \`interview_answers\` and per-interaction
   breakdowns. Cheapest "did this run land?" shape.
-- **\`study results --transcript <tester_id>\`** is the chat-modality
+- **\`study get --json\` carries a flat top-level \`participants[]\`**
+  (post backend-split). Each row carries \`iteration_id\` as a
+  discriminator and the per-participant graph
+  (\`person\`, \`interactions[]\`, \`participant_summary\`,
+  \`interview_answers\`, \`conversation_id\`, …). The previous nesting
+  under \`iterations[*].participants[*]\` is gone — read participants from
+  the top level. The lite iteration list under \`iterations[]\` still
+  carries each iteration's \`details\` and (for pair-mode chat) the
+  conversation refs at \`iterations[*].conversations[]\`.
+- **\`study get --json\` carries assignment step completion** when an
+  assignment has a checklist (see \`concepts/assignment\`). Each
+  \`assignments[].step_completion[]\` row is
+  \`{step_id, name, total, passed, rate, sample_failures}\`. \`step_id\`
+  (a slug like \`add-to-cart\`), \`total\`, \`passed\`, and \`rate\`
+  survive the lean default; \`sample_failures[].participant_id\` is a UUID and
+  so is stripped unless you pass \`--verbose\`. \`rate\` is \`null\` until
+  a run grades the steps.
+- **\`study results --transcript <participant_id>\`** is the chat-modality
   projection — **external_chatbot mode only in v1**. Returns
-  \`{tester_id, tester_alias, transcript: [...], unique_bot_replies,
-  tester_summary}\`. Each transcript entry is \`{role, text, turn_index,
+  \`{participant_id, participant_alias, transcript: [...], unique_bot_replies,
+  participant_summary}\`. Each transcript entry is \`{role, text, turn_index,
   ...}\` — bot turns add \`failure\` (set when the dispatch crashed);
-  tester turns add \`action_type\`, \`option_label\`, and \`sentiment\`.
-  \`text\` is null on tester turns whose action carries no text
+  participant turns add \`action_type\`, \`option_label\`, and \`sentiment\`.
+  \`text\` is null on participant turns whose action carries no text
   (\`select_option\`, \`ignore_offered\`); read intent from
   \`action_type\` + \`option_label\`. Same shape as the MCP
   \`get_chat_transcript\` tool. \`unique_bot_replies = 1\` on a
   multi-turn run is the M2 loop signature.
 
-  **For tester_pair conversations**, the bot/tester role pair doesn't
-  apply (both speakers are testers). Inspect pair transcripts via the
+  **For participant_pair conversations**, the bot/participant role pair doesn't
+  apply (both speakers are participants). Inspect pair transcripts via the
   iteration response instead:
 
   \`\`\`bash
@@ -2026,19 +2097,19 @@ The CLI guarantees these contracts so agents can chain safely:
   # → [{ id, pair_index, started_at, ended_at, end_reason, summary, ... }]
   \`\`\`
 
-  Per-side tester summaries still land on each tester row
-  (\`ish study tester <id> --json\`); the conversation-level summary
+  Per-side participant summaries still land on each participant row
+  (\`ish study participant <id> --json\`); the conversation-level summary
   (\`end_reason\`, \`dominant_dynamic\`, \`who_steered\`) lands on
   \`iteration.conversations[]\`.
-- **\`study tester --summary\`** drops the action timeline and
-  returns just \`{tester, interaction_count, sentiment, comment,
+- **\`study participant --summary\`** drops the action timeline and
+  returns just \`{participant, interaction_count, sentiment, comment,
   error_message?, error_kind?}\`.
 - **\`study poll\` honors the active study.** Pass no \`--study\`
   flag and it falls back to the active study (set by
   \`ish study use\`), parity with \`study results\` /
   \`study wait\` / \`study run\`.
-- **\`iteration get --json\` testers carry \`alias\` + \`name\`** (M12).
-  Same identifying triple as \`study results --json\`'s tester rows.
+- **\`iteration get --json\` participants carry \`alias\` + \`name\`** (M12).
+  Same identifying triple as \`study results --json\`'s participant rows.
 - **\`ask results --json\` keeps \`variant_pick_id\` on every response**
   (C5-Bug4). It's the load-bearing field for "who picked what" — no
   \`--verbose\` required. Same logic on \`ask get --json\`.
@@ -2051,12 +2122,12 @@ The CLI guarantees these contracts so agents can chain safely:
   envelope carries \`progress: {study_id, iteration_id?,
   timeout_seconds, done, total, pending, rows[]}\` so the agent
   can resume by polling rather than re-dispatching. Same shape on
-  \`study wait\` (single-tester rows[] has length 1).
+  \`study wait\` (single-participant rows[] has length 1).
 - **\`study run\` accepts \`--dispatch-timeout <s>\`** (default 120)
-  for the per-POST testers/batch + simulation/start budget. On
+  for the per-POST participants/batch + simulation/start budget. On
   timeout (or any dispatch failure), the error envelope includes
   \`seeded_but_not_dispatched_ids[]\` + \`seeded_but_not_dispatched_aliases[]\`
-  listing the testers that exist server-side but didn't get
+  listing the participants that exist server-side but didn't get
   dispatched. Resume by polling those instead of re-running
   \`study run\` (which would create another batch on top).
 - **\`ask run --new\` is non-idempotent and marked \`retryable: false\`**
@@ -2083,13 +2154,13 @@ The CLI guarantees these contracts so agents can chain safely:
 - **Study responses carry a derived \`runtime_status\` field**
   (\`draft | running | completed | completed_with_errors | cancelled\`).
   Prefer this over the raw \`status\` field — \`runtime_status\` is
-  computed from the iteration testers' actual run state and never
+  computed from the iteration participants' actual run state and never
   reports \`failed\` while completed runs exist. Available on
   \`study get\`, \`study results\`, and the response from
   \`study generate\`. The CLI also surfaces a \`status_inferred\` field
   alongside the raw \`status\` when it detects a partial-failure
   inconsistency, plus a stderr warning ("Warning: study reports
-  status='failed' but N/M testers completed…").
+  status='failed' but N/M participants completed…").
 - **\`study generate --json\` includes a \`modality_rationale\`** —
   one short sentence explaining why the LLM picked that modality. Use
   it to detect mis-classifications (e.g. brief was a static concept doc
@@ -2114,11 +2185,11 @@ The CLI guarantees these contracts so agents can chain safely:
   agent tool result budgets. Pass
   \`include_accessibility_profile=true\` to opt in. Mirrors the
   existing \`include_bio=false\` opt-in.
-- **\`ask_testers\` parameter is \`dispatch_into_round\`, not
-  \`round\`.** Reads verbatim — "dispatch these new testers into round
+- **\`ask_participants\` parameter is \`dispatch_into_round\`, not
+  \`round\`.** Reads verbatim — "dispatch these new participants into round
   N". The old name (\`round\`) read as "start from round N", which
   was wrong: the call never restarts prior rounds, it only appends
-  testers to the named round. Behavior unchanged across the rename.
+  participants to the named round. Behavior unchanged across the rename.
 - **No more auto-empty iteration A.** \`study create\` and
   \`study generate\` no longer produce a placeholder iteration A. The
   first explicit \`ish iteration create\` becomes label A.
@@ -2126,13 +2197,13 @@ The CLI guarantees these contracts so agents can chain safely:
   (interactive) inline so a single call yields a runnable study.
   Running \`study run\` on a study with zero iterations exits 2 with
   a suggestion to run \`ish iteration create\` first.
-- **Tester responses include \`error_message\`.** When a tester is
+- **Participant responses include \`error_message\`.** When a participant is
   \`status: failed\`, the JSON exposes \`error_message: "<reason>"\` so
   agents can act without drilling into logs. \`study results\` rolls
-  this up: top-level \`failed_count\`, plus per-tester \`error_message\`
-  in the \`testers[]\` array, and a "Failed testers" subsection in
-  human output. Empty when the tester succeeded.
-- **\`profile list\` emits a stderr pagination hint** when
+  this up: top-level \`failed_count\`, plus per-participant \`error_message\`
+  in the \`participants[]\` array, and a "Failed participants" subsection in
+  human output. Empty when the participant succeeded.
+- **\`person list\` emits a stderr pagination hint** when
   \`has_more=true\` and \`--quiet\` is not set. The hint goes to **stderr
   in every mode** including \`--json\` and piped stdout — it never
   pollutes machine-readable stdout but is visible to any agent that
@@ -2174,11 +2245,11 @@ The CLI guarantees these contracts so agents can chain safely:
   COMPLETED rows are left untouched; only ERRORED responses are reset
   to PENDING and re-run from scratch. Idempotent: zero-errored is a
   no-op. Add \`--wait\` to block until the retry settles.
-- **\`ask results --json\` deduplicates tester profile snapshots.** When
-  \`tester_profile\` and \`tester_profile_snapshot\` share all
+- **\`ask results --json\` deduplicates person snapshots.** When
+  \`person\` and \`person_snapshot\` share all
   overlapping fields (the common case — they only diverge if the
   profile was edited after dispatch), the snapshot is collapsed to
-  \`{snapshotted_at, snapshot_version, _matches_tester_profile: true}\`.
+  \`{snapshotted_at, snapshot_version, _matches_person: true}\`.
   Use \`--verbose\` to keep both copies in full.
 
 ## Exit codes
@@ -2208,14 +2279,14 @@ a structured error object on **stdout** and a human message on
   "retryable": false,
   "errors": [
     {
-      "loc": ["body", "testers", 0, "tester_profile_id"],
+      "loc": ["body", "participants", 0, "person_id"],
       "msg": "Input should be a valid UUID",
       "type": "uuid_parsing",
-      "input": "tp-bogus",
+      "input": "p-bogus",
       "allowed_values": ["..."]
     }
   ],
-  "suggestions": ["Pass a tester profile alias (tp-...) or UUID."]
+  "suggestions": ["Pass a person alias (p-...) or UUID."]
 }
 \`\`\`
 
@@ -2245,7 +2316,7 @@ ish ask results a-6ec --human | tee /tmp/results.txt
 WS=$(ish workspace list --get alias | head -1)
 
 # Inspect a nested field:
-ish study tester t-a17 --get tester_profile.name
+ish study participant pt-a17 --get person.name
 
 # Chain (full JSON for jq when you need multiple fields):
 ish study get s-b2c --fields alias,name,status,iterations --json
@@ -2260,8 +2331,8 @@ a script, then display the final result back to the user:
 \`\`\`
 # Capture — bare values, no jq needed:
 ITER=$(ish iteration create --url https://example.com --get alias)
-TESTERS=$(ish study run --iteration "$ITER" --sample 5 --country SE --get tester_aliases)
-for t in $TESTERS; do
+PARTICIPANTS=$(ish study run --iteration "$ITER" --sample 5 --country SE --get participant_aliases)
+for t in $PARTICIPANTS; do
   ish study wait "$t" --timeout 600
 done
 
@@ -2275,7 +2346,7 @@ reshaping output.
 `;
 const GUIDE_FIRST_STUDY = `# guide: your first study, end to end
 
-Goal: from zero to a finished interactive study with 3 testers and one
+Goal: from zero to a finished interactive study with 3 participants and one
 question, produced in a single workspace.
 
 ## 1. Authenticate
@@ -2291,10 +2362,10 @@ ish workspace create --name "Demo" --base-url https://example.com
 ish workspace use w-…    # use the alias printed above
 \`\`\`
 
-## 3. Generate a small audience
+## 3. Generate a small group of people
 
 \`\`\`
-ish profile generate \\
+ish person generate \\
     --description "Tech-savvy millennials in the US who use mobile banking" \\
     --count 3
 \`\`\`
@@ -2433,31 +2504,31 @@ compute cost. Agents should:
 
 - For prospective cost preview: read \`credit_estimate\` from \`study run\`'s
   JSON envelope (top-level for solo/media runs; under \`pair_preview\` for
-  tester-pair chat).
+  participant-pair chat).
 - For hard budget checks: catch the backend's \`insufficient_credits\`
   rejection (HTTP 402; envelope shape below) and react to
   \`required\` / \`available\`.
 
 | Surface             | Per-principal cost              | Total formula                                    | Example                              |
 |---------------------|---------------------------------|--------------------------------------------------|--------------------------------------|
-| Interactive (URL)   | \`max(1, round(steps/10))\`       | \`testers × per-tester\`                           | 10 testers × 30 steps → 30 credits   |
-| Text/image/video/audio/document | same                | same                                             | 5 testers × 20 steps → 10 credits    |
-| Chat (external chatbot, solo) | \`max(1, round(turns/10))\` | \`testers × per-tester\`                           | 5 testers × 12 turns → 10 credits    |
-| Chat (tester pair)  | \`max(1, round(turns/10))\` × 2   | \`conv × per-side × 2\`                            | 3 conv × 14 turns → 6 credits        |
-| Ask round           | 1 / successful response         | \`successful_testers\`                             | 50 responses → 50 credits            |
+| Interactive (URL)   | \`max(1, round(steps/10))\`       | \`participants × per-participant\`                           | 10 participants × 30 steps → 30 credits   |
+| Text/image/video/audio/document | same                | same                                             | 5 participants × 20 steps → 10 credits    |
+| Chat (external chatbot, solo) | \`max(1, round(turns/10))\` | \`participants × per-participant\`                           | 5 participants × 12 turns → 10 credits    |
+| Chat (participant pair)  | \`max(1, round(turns/10))\` × 2   | \`conv × per-side × 2\`                            | 3 conv × 14 turns → 6 credits        |
+| Ask round           | 1 / successful response         | \`successful_participants\`                             | 50 responses → 50 credits            |
 | Study insights      | first free, then **10 flat**    | n/a                                              | 2nd analysis → 10 credits            |
 
 All numbers are **upper bounds**. Early termination, refusals, or
-backend audience trimming can reduce actual charge.
+backend trimming can reduce actual charge.
 
 ## Capping interactive/media spend (\`--max-interactions\`)
 
 \`ish study run\` always sends \`max_interactions\` to the backend for
 interactive and media runs. Precedence: \`--max-interactions <n>\` flag
 > the iteration's stored \`details.max_interactions\` > **CLI default
-of 20**. The default exists to prevent runaway spend when a tester
+of 20**. The default exists to prevent runaway spend when a participant
 gets stuck on a broken or non-responsive surface — without a cap, one
-stuck tester can rack up 100+ steps before the SDK gives up. Pass
+stuck participant can rack up 100+ steps before the SDK gives up. Pass
 \`--max-interactions\` to override (e.g. \`--max-interactions 50\` for
 deeper exploration, \`--max-interactions 5\` for a cheap smoke test).
 The confirmation block shows the resolved value and where it came
@@ -2502,14 +2573,14 @@ Solo media/interactive/chat — top-level \`credit_estimate\`:
   "iteration_id": "…",
   "credit_estimate": {
     "upper_bound": 30,
-    "formula": "media_per_tester",
-    "breakdown": "10 tester(s) × max(1, round(30 steps / 10)) = 10 × 3 = 30",
+    "formula": "media_per_participant",
+    "breakdown": "10 participant(s) × max(1, round(30 steps / 10)) = 10 × 3 = 30",
     "unit": "credits"
   }
 }
 \`\`\`
 
-The \`formula\` key is stable: agents can branch on it (\`media_per_tester\`,
+The \`formula\` key is stable: agents can branch on it (\`media_per_participant\`,
 \`chat_solo\`, \`chat_pair\`, \`ask_per_response\`).
 
 ## Tier allotments
@@ -2601,11 +2672,11 @@ request time, for any client, is the backend's \`TIER_LIMITS\` dict in
 | \`maxProducts\`               | 1    | 1     | ∞       | ∞   | ∞          |
 | \`maxStudiesPerProduct\`      | 3    | ∞     | ∞       | ∞   | ∞          |
 | \`maxIterationsPerStudy\`     | 2    | ∞     | ∞       | ∞   | ∞          |
-| \`maxCustomTesterProfiles\`   | 3    | 10    | 10      | ∞   | ∞          |
+| \`maxCustomPersons\`   | 3    | 10    | 10      | ∞   | ∞          |
 
 Commands that may hit a limit: \`ish workspace create\`,
 \`ish study create\`, \`ish study generate\`, \`ish iteration create\`,
-\`ish profile create\`, \`ish profile generate\`.
+\`ish person create\`, \`ish person generate\`.
 
 ## What you see when a limit is hit
 
@@ -2645,7 +2716,7 @@ upgrade or delete an existing resource to free up headroom.
 - Use \`limit\`, \`current\`, \`max\`, \`tier\` to construct your own
   recovery message. The \`limit\` value matches the table above and is
   stable.
-- The \`generate\` endpoints (\`study generate\`, \`profile generate\`)
+- The \`generate\` endpoints (\`study generate\`, \`person generate\`)
   refuse the entire batch when the post-generation count would exceed
   the cap, rather than partially fulfilling — re-issue with a smaller
   \`--count\` after upgrading or pruning.
@@ -2658,16 +2729,16 @@ upgrade or delete an existing resource to free up headroom.
 - \`concepts/workspace\` — \`maxProducts\` is per-account.
 - \`concepts/study\`     — \`maxStudiesPerProduct\` gates study creation.
 - \`concepts/iteration\` — \`maxIterationsPerStudy\` gates iteration creation.
-- \`concepts/profile\`   — \`maxCustomTesterProfiles\` gates profile creation.
+- \`concepts/person\`   — \`maxCustomPersons\` gates person creation.
 - \`reference/json-mode\` — full error envelope shape and exit codes.
 `;
 const GUIDE_CHAT = `# guide: chat-modality studies
 
 Chat-modality studies cover two distinct shapes:
 
-- **external_chatbot** — testers probe a customer chatbot endpoint
+- **external_chatbot** — participants probe a customer chatbot endpoint
   (sections 1-3 below: configure → smoke test → run).
-- **tester_pair** — two AI personas converse with each other for
+- **participant_pair** — two AI personas converse with each other for
   rehearsal scenarios. Pitch rehearsals, difficult-conversation
   prep, founder-vs-investor archetypes. See section 7a/7b and the
   TL;DR below.
@@ -2680,17 +2751,17 @@ scenarios — no extra files needed:
 
 \`\`\`bash
 # Capture aliases for the rep (1) and CTOs (3) via subshell:
-REP=$(ish profile generate \\
+REP=$(ish person generate \\
   --description "Senior B2B SaaS account executive; concise, technical" \\
   --count 1 --json | jq -r '.items[0].alias')
-CTOS=$(ish profile generate \\
+CTOS=$(ish person generate \\
   --description "Skeptical CTO at Series B SaaS; distrusts AI vendors" \\
   --count 3 --json | jq -r '[.items[].alias] | join(",")')
 
 # One-shot study + iteration A (1×N broadcast does the rest):
-ish study create --modality chat --chat-mode tester_pair \\
+ish study create --modality chat --chat-mode participant_pair \\
   --name "Pitch rehearsal" \\
-  --audience-a "$REP" --audience-b "$CTOS" \\
+  --group-a "$REP" --group-b "$CTOS" \\
   --scenario-a "You are pitching <your product>. Be concise, push back on vague objections. Goal: land a pilot or a clear next step." \\
   --scenario-b "You are a skeptical CTO. Probe for technical depth, distrust marketing-speak, refuse to commit without evidence. Goal: leave with either a concrete proof point or a graceful 'no'." \\
   --assignment "Pitch:Land a pilot" --max-turns 14
@@ -2704,7 +2775,7 @@ ish iteration get <iter-id> --json \\
 \`\`\`
 
 Section 7b below has the longer version with scenario-writing
-guidance, criteria-driven audiences, and the broadcast rule.
+guidance, criteria-driven groups, and the broadcast rule.
 
 ---
 
@@ -2804,7 +2875,7 @@ The renderer expands these tokens at request time:
 - \`{{turn.role}}\` / \`{{turn.text}}\`: per-turn expansion. Place
   one element with these tokens inside an array literal; the
   renderer expands it to one entry per past turn.
-- \`{{tester.name}}\` / \`{{tester.locale}}\`: persona attributes.
+- \`{{participant.name}}\` / \`{{participant.locale}}\`: persona attributes.
 - \`{{conversation_id}}\`: bot-supplied session id (stateful mode).
 - \`{{secret:KEY}}\`: workspace secret (see below).
 
@@ -2999,7 +3070,7 @@ cat ./bot-config.json | ish study create \\
     --name "Sign-up Q1" --assignment "Sign up:Try to sign up"
 \`\`\`
 
-Optional \`--max-turns <n>\` (default 12) caps the chat per tester.
+Optional \`--max-turns <n>\` (default 12) caps the chat per participant.
 
 Audience size is set at run time for **external_chatbot** chat
 studies. Use \`--sample <N>\` to pick N random simulatable profiles,
@@ -3010,14 +3081,14 @@ ish study run stu-xyz --sample 5 --wait
 \`\`\`
 
 > **Pair-mode is different.** \`--sample\` / \`--profile\` / demographic
-> filters on \`study run\` are **refused** for tester_pair iterations
-> — pair audiences live on the iteration itself. Set them at
-> iteration-create time via \`--audience-a/-b\` (with 1×N broadcast)
-> or \`--role-criteria-a/-b\`. See the tester_pair section below.
+> filters on \`study run\` are **refused** for participant_pair iterations
+> — pair groups live on the iteration itself. Set them at
+> iteration-create time via \`--group-a/-b\` (with 1×N broadcast)
+> or \`--role-criteria-a/-b\`. See the participant_pair section below.
 
 Pull raw interactions:
 \`\`\`
-ish study results stu-xyz --json | jq '.interactions'
+ish study results stu-xyz --json | jq '.participants[].interactions'
 \`\`\`
 
 Note: chat is currently excluded from the LLM-analysis route; the
@@ -3036,23 +3107,23 @@ ish iteration create --study stu-xyz --endpoint-config ./bot.json
 
 Same flag set as \`study create\`'s chat shortcut.
 
-## tester_pair: rehearse a conversation between two AI personas
+## participant_pair: rehearse a conversation between two AI personas
 
-\`Modality.CHAT\` also supports a **tester_pair** mode where two AI
-tester profiles converse with each other — useful for rehearsing a
+\`Modality.CHAT\` also supports a **participant_pair** mode where two AI
+people converse with each other — useful for rehearsing a
 sales pitch, a difficult conversation, a fundraising chat, or any
 two-role scenario. Each side has its own scenario + goal text; the
 other side does NOT see it (the asymmetry contract). Audiences are
-1:1 paired by index (audience_a[i] talks to audience_b[i]).
+1:1 paired by index (group_a[i] talks to group_b[i]).
 
 One-shot study + iteration:
 
 \`\`\`
 ish study create \\
-    --modality chat --chat-mode tester_pair \\
+    --modality chat --chat-mode participant_pair \\
     --name "Pitch rehearsal" \\
-    --audience-a tp-sales-1,tp-sales-2 \\
-    --audience-b tp-cto-skeptic-1,tp-cto-skeptic-2 \\
+    --group-a p-sales-1,p-sales-2 \\
+    --group-b p-cto-skeptic-1,p-cto-skeptic-2 \\
     --scenario-a @./sales_rep.md \\
     --scenario-b @./skeptical_cto.md \\
     --assignment "Pitch:Try to win the meeting"
@@ -3061,8 +3132,8 @@ ish study create \\
 Or add a pair iteration to an existing chat study:
 
 \`\`\`
-ish iteration create --study stu-xyz --chat-mode tester_pair \\
-    --audience-a tp-a1,tp-a2 --audience-b tp-b1,tp-b2 \\
+ish iteration create --study stu-xyz --chat-mode participant_pair \\
+    --group-a p-a1,p-a2 --group-b p-b1,p-b2 \\
     --scenario-a "..." --scenario-b "..." \\
     --max-turns 14
 \`\`\`
@@ -3070,23 +3141,23 @@ ish iteration create --study stu-xyz --chat-mode tester_pair \\
 ### Rehearsing against N variations of one side (1×N)
 
 The most common rehearsal shape: fix one side (your role) and vary
-the other (the audience you're rehearsing against). E.g. "pitch this
+the other (the people you're rehearsing against). E.g. "pitch this
 once and see how it lands against 3 different skeptical CTOs."
 
 Step 1 — produce N distinct profiles for the varying side:
 
 \`\`\`bash
 # Generate 3 skeptical-CTO profiles (or any archetype):
-ish profile generate \\
+ish person generate \\
     --description "Skeptical CTO at a Series B SaaS startup; distrusts AI vendors" \\
     --count 3 --json | jq -r '.items[].alias'
-# → tp-cto1, tp-cto2, tp-cto3
+# → p-cto1, p-cto2, p-cto3
 \`\`\`
 
 If you already have profiles you want to reuse, list them:
 
 \`\`\`bash
-ish profile list --search "cto" --json | jq -r '.items[].alias'
+ish person list --search "cto" --json | jq -r '.items[].alias'
 \`\`\`
 
 Step 2 — author the two scenarios as separate files (\`sales_rep.md\`
@@ -3101,21 +3172,21 @@ template.
 Step 3 — create the iteration with **one profile** on the fixed
 side and **N profiles** on the varying side. The CLI auto-broadcasts
 the singleton to match length N (and prints a stderr notice like
-\`Broadcasting --audience-a (1 profile) to length 3 to match --audience-b\`
+\`Broadcasting --group-a (1 profile) to length 3 to match --group-b\`
 when it does, so you can see it happen):
 
 \`\`\`bash
 ish study create \\
-    --modality chat --chat-mode tester_pair \\
+    --modality chat --chat-mode participant_pair \\
     --name "Pitch rehearsal — 3 CTO variants" \\
-    --audience-a tp-rep \\
-    --audience-b tp-cto1,tp-cto2,tp-cto3 \\
+    --group-a p-rep \\
+    --group-b p-cto1,p-cto2,p-cto3 \\
     --scenario-a @./sales_rep.md \\
     --scenario-b @./skeptical_cto.md \\
     --assignment "Pitch:Land a pilot or a clear next step"
 
-# Result: 3 conversations, all using tp-rep on side A, one each
-# of tp-cto1/2/3 on side B. Same scenario for the CTOs (they share
+# Result: 3 conversations, all using p-rep on side A, one each
+# of p-cto1/2/3 on side B. Same scenario for the CTOs (they share
 # the role description) but different underlying personas, so the
 # conversations diverge in tone and pressure points.
 \`\`\`
@@ -3136,22 +3207,22 @@ ish iteration get <iter-id> --json \\
 **When to use criteria instead**: if you don't care about specific
 profile IDs and just want "any 3 CTOs the backend can find", pass
 \`--role-criteria-b '{"occupation":["cto"]}'\` (alone or with a single
-\`--audience-a tp-rep\`). The backend resolves the matching pool at
+\`--group-a p-rep\`). The backend resolves the matching pool at
 iteration-create time. Caveat: the resolved pool may collapse onto
 similar personas — for guaranteed distinctness, generate explicit
 profiles first.
 
-### Criteria-driven audience (persona-first filtering)
+### Criteria-driven group (persona-first filtering)
 
 When you don't want to hand-pick UUIDs, pass a **role-criteria
 filter** per side. The backend resolves it into an eligible pool of
-tester profiles and pairs them 1:1. The persona itself is never
+people and pairs them 1:1. The persona itself is never
 altered — criteria filter the pool upstream so the persona is
 already plausible for the role:
 
 \`\`\`
 ish study create \\
-    --modality chat --chat-mode tester_pair \\
+    --modality chat --chat-mode participant_pair \\
     --name "Pitch rehearsal" \\
     --role-criteria-a '{"occupation":["sales","account executive"],"min_age":28}' \\
     --role-criteria-b '{"occupation":["cto","vp engineering"],"country":["US","SE"]}' \\
@@ -3172,23 +3243,23 @@ MECE notes for the list filters:
 - \`household_in\`: \`couple_with_kids\` covers couples raising children;
   \`couple_no_kids\` is strictly child-free. \`single\` means lives alone
   (no partner, no roommates, no parents, no children in the household).
-- \`employment_status_in\`: pick the tester's primary daytime activity.
+- \`employment_status_in\`: pick the participant's primary daytime activity.
   A student who works 15 hrs/week is \`student\`; a retiree who freelances
   is \`retired\`.
 
 If the resolved pool is too small, \`ish study run\` exits 2 with the
 backend's error message intact — no silent fallback. Broaden the
 criteria or generate more matching profiles via
-\`ish profile generate --description "..."\`.
+\`ish person generate --description "..."\`.
 
 Dispatch is per-Conversation (one task per pair index). Run-time
-audience overrides (\`--profile\`, \`--sample\`, \`--all\`, demographic
-filters) are refused on pair iterations — the iteration's audiences
+people overrides (\`--profile\`, \`--sample\`, \`--all\`, demographic
+filters) are refused on pair iterations — the iteration's groups
 are authoritative. To change them, update the iteration:
 
 \`\`\`
 ish study run --study stu-xyz --iteration i-pair -y
-ish iteration update i-pair --details-json '{...}'   # change audiences
+ish iteration update i-pair --details-json '{...}'   # change groups
 \`\`\`
 
 Inspect:
@@ -3198,8 +3269,8 @@ ish iteration get i-pair --json | jq '.details.mode_details.mode, .conversations
 \`\`\`
 
 Per-Conversation summaries (\`end_reason\`, \`dominant_dynamic\`,
-\`who_steered\`) land on \`iteration.conversations[]\`. Per-tester
-summaries land on \`tester.summary\` as before.
+\`who_steered\`) land on \`iteration.conversations[]\`. Per-participant
+summaries land on \`participant.summary\` as before.
 
 ## Active-endpoint convention
 
@@ -3234,7 +3305,7 @@ Mirrors \`workspace use\` / \`study use\` / \`ask use\`.
 - \`concepts/iteration\` — chat iteration shape
   (\`details.mode_details\` discriminator, \`mode_details.endpoint\` /
   \`mode_details.chatbot_endpoint_id\` for external_chatbot,
-  \`mode_details.audience_a/_b\` + \`scenario_a/_b\` for tester_pair,
+  \`mode_details.group_a/_b\` + \`scenario_a/_b\` for participant_pair,
   \`details.max_turns\`).
 - \`concepts/study\` — modality + assignments + iteration nesting.
 - \`reference/json-mode\` — JSON output, error envelope, exit codes.
@@ -3296,13 +3367,13 @@ ish workspace list --json
       "id": "...", "alias": "w-6ec", "name": "Onboarding revamp",
       "base_url": "https://example.com",
       "last_activity_at": "2026-05-10T14:22:00Z",
-      "child_counts": { "studies": 2, "asks": 1, "tester_profiles": 4 },
+      "child_counts": { "studies": 2, "asks": 1, "persons": 4 },
       "has_headroom": true
     },
     {
       "id": "...", "alias": "w-d02", "name": "Demo",
       "last_activity_at": "2025-11-02T09:11:00Z",
-      "child_counts": { "studies": 3, "asks": 0, "tester_profiles": 0 },
+      "child_counts": { "studies": 3, "asks": 0, "persons": 0 },
       "has_headroom": false
     }
   ],
@@ -3315,14 +3386,14 @@ Read three fields per row:
 - **\`last_activity_at\`** — most recent run, iteration, ask, or write
   on this workspace. The most recently active one is usually the
   workspace the user is mentally already in.
-- **\`child_counts\`** — \`{ studies, asks, tester_profiles }\`. Zero
+- **\`child_counts\`** — \`{ studies, asks, persons }\`. Zero
   across the board = quiet/empty, ideal reuse target without
   cluttering anyone's view. A workspace with content the user owns is
   also fine to reuse if there's still headroom.
 - **\`has_headroom\`** — \`true\` if the workspace still has room under
   \`maxStudiesPerProduct\`, \`maxIterationsPerStudy\`, and
-  \`maxCustomTesterProfiles\` for the caller's tier. If \`false\`, the
-  next \`study create\` / \`profile generate\` against this workspace
+  \`maxCustomPersons\` for the caller's tier. If \`false\`, the
+  next \`study create\` / \`person generate\` against this workspace
   will be \`usage_limit_reached\`. Filter these out unless the user
   explicitly wants to free space by deleting state.
 
@@ -3381,11 +3452,11 @@ ish workspace list --json --fields alias,name,last_activity_at,child_counts,has_
 # [
 #   {"alias":"w-6ec","name":"Onboarding revamp",
 #    "last_activity_at":"2026-05-10T14:22:00Z",
-#    "child_counts":{"studies":2,"asks":1,"tester_profiles":4},
+#    "child_counts":{"studies":2,"asks":1,"persons":4},
 #    "has_headroom":true},
 #   {"alias":"w-d02","name":"Demo",
 #    "last_activity_at":"2025-11-02T09:11:00Z",
-#    "child_counts":{"studies":3,"asks":0,"tester_profiles":0},
+#    "child_counts":{"studies":3,"asks":0,"persons":0},
 #    "has_headroom":false},
 #   ...
 # ]
@@ -3394,7 +3465,7 @@ ish workspace list --json --fields alias,name,last_activity_at,child_counts,has_
 ish workspace use w-6ec
 
 # 3. Carry on as if the workspace_create had succeeded.
-ish profile generate --description "..." --count 3
+ish person generate --description "..." --count 3
 ish study create --modality interactive --name "..." \\
   --url https://example.com \\
   --assignment "..." --question "..."
@@ -3437,24 +3508,24 @@ 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
+const GUIDE_BUILD_SPECIFIC_PERSON = `# guide: build a specific simulated person from notes
 
-\`profile generate\` is the right tool for *audiences* (many profiles
+\`person generate\` is the right tool for *groups* (many profiles
 from a description or interview sources). When you want **one specific
-tester** — modelling a real prospect, rebuilding a persona from a
+person** — 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
+1. \`ish person 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
+3. \`ish person create --file ...\` — save the profile shell.
+4. \`ish person 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,
+5. \`ish person 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.
 
@@ -3467,7 +3538,7 @@ to surface a different facet of the persona:
   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.
+  but framed around tone/phrasing the participant 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
@@ -3490,7 +3561,7 @@ probe, copy the scenario's \`type\` straight into the trace's
 
 \`\`\`
 # 1. Suggest 5 probes from a context blob
-ish profile suggest-scenarios \\
+ish person 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." \\
@@ -3508,16 +3579,16 @@ ish profile suggest-scenarios \\
 # ]
 
 # 3. Create the profile shell
-ish profile create --file ./persona.json
-# → tp-d4e
+ish person create --file ./persona.json
+# → p-d4e
 
 # 4. Persist the answered probes as evidence
-ish profile evidence add tp-d4e --traces-file ./answers.json
+ish person evidence add p-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
+ish person evidence list p-d4e
+ish person evidence list p-d4e --get source   # one source per line
 \`\`\`
 
 ## Iterating the probe loop
@@ -3526,7 +3597,7 @@ 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 \\
+ish person suggest-scenarios \\
     --context-file ./notes.md \\
     --count 3 \\
     --already-surfaced '["PagerDuty fires at 02:00 on payments edge."]' \\
@@ -3542,17 +3613,123 @@ cap at 40 entries.
 
 | 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\` |
+| Many profiles from a description or interview | \`ish person generate\` |
+| One specific persona, iterative probe loop | \`ish person suggest-scenarios\` + \`evidence add\`/\`list\` |
+| Exact profile from a JSON spec, no LLM | \`ish person create --file\` |
 
 ## Related
 
-- \`concepts/profile\` — what a tester profile is; structured fields.
+- \`concepts/person\` — what a person is; structured fields.
 - \`concepts/source\` — interview transcripts / audio / PDF inputs
-  for the audience-generation flow.
+  for the people-generation flow.
 - \`reference/aliases\` — \`tp-…\` is the profile alias prefix.
 `;
+const GUIDE_MCP_ADD = `# guide: wire ish into your AI clients (\`ish mcp add\`)
+
+The hosted ish MCP server lets agents inside Cursor, VS Code, Claude
+Code, Claude Desktop, and Windsurf call ish operations (study
+run, ask run, person generate, …) directly. \`ish mcp add\` writes the
+per-client config block so each client knows where to find the
+server. OAuth is handled by the server itself on first connect — no
+token is written to your client config file.
+
+## When to run this
+
+- You've installed the ish CLI and want your editor/desktop agent to
+  drive ish without you copy-pasting JSON into a config file.
+- You're switching machines and want to re-wire every client in one
+  command.
+- You changed the server URL (\`ISH_MCP_URL\`) and want every client
+  re-pointed at the new endpoint.
+
+## Verbs
+
+\`\`\`bash
+ish mcp list                      # read-only: which clients are detected + status
+ish mcp add                       # dry-run plan + next-step hint (default)
+ish mcp add --all --yes           # wire every detected client
+ish mcp add --client cursor --yes # wire one specific client
+ish mcp remove --client cursor --yes
+\`\`\`
+
+## Supported clients
+
+| Client          | Config path                                                                       | Server key         |
+|-----------------|-----------------------------------------------------------------------------------|--------------------|
+| cursor          | \`~/.cursor/mcp.json\`                                                            | \`mcpServers\`     |
+| vscode          | \`~/Library/Application Support/Code/User/mcp.json\` (macOS), \`~/.config/Code/User/mcp.json\` (Linux), \`%APPDATA%\\Code\\User\\mcp.json\` (Windows) | \`servers\`        |
+| claude-code     | \`~/.claude.json\` (user scope)                                                   | \`mcpServers\`     |
+| claude-desktop  | \`~/Library/Application Support/Claude/claude_desktop_config.json\` (macOS), \`%APPDATA%\\Claude\\claude_desktop_config.json\` (Windows). Not available on Linux. | \`mcpServers\`     |
+| windsurf        | \`~/.codeium/windsurf/mcp_config.json\`                                           | \`mcpServers\`     |
+
+Detection is by per-client config-dir existence — if the dir is
+missing, the client is reported \`detected: false\`. You can still wire
+that client explicitly via \`--client <name>\` (the dir is created on
+write).
+
+## Conventions
+
+- **Atomic writes.** A tmp file is renamed into place; partially-written
+  configs never appear.
+- **Idempotent.** Re-running \`mcp add\` is a no-op when the ish block
+  already matches the expected shape.
+- **Preserves unrelated keys.** Other MCP servers in the same config
+  file, and unrelated top-level settings, are kept verbatim.
+- **No tokens written.** The hosted MCP server handles OAuth on first
+  connect; only the URL goes into the client config file.
+- **Drift refusal.** If the existing ish block in a client config has
+  a different URL/shape than ours, \`mcp add\` exits 2 unless
+  \`--force\` is passed.
+
+## Flags
+
+| Flag              | Effect                                                                                  |
+|-------------------|-----------------------------------------------------------------------------------------|
+| \`--client a,b\`  | Comma-separated and/or repeatable client keys. Mutually exclusive with \`--all\`.       |
+| \`--all\`         | Apply to every *detected* client on this OS.                                            |
+| \`--dry-run\`     | Print the planned mutations as JSON; write nothing.                                     |
+| \`--force\`       | Overwrite an existing ish block that has drifted.                                       |
+| \`-y, --yes\`     | Confirm writes. Required when stdout is piped or \`--json\` is set.                     |
+
+## JSON output
+
+\`\`\`json
+{
+  "ok": true,
+  "server_url": "https://mcp.ishlabs.io/mcp",
+  "dry_run": true,
+  "plan": [
+    {
+      "client": "cursor",
+      "display_name": "Cursor",
+      "config_path": "/Users/me/.cursor/mcp.json",
+      "action": "create",
+      "expected": { "url": "https://mcp.ishlabs.io/mcp" }
+    }
+  ],
+  "hint": "Re-run with \`ish mcp add --all --yes\` to commit these writes."
+}
+\`\`\`
+
+\`action\` is one of: \`create\` (no client config file yet),
+\`update\` (file exists, ish block being added or overwritten),
+\`skip\` (already up to date), \`refuse-drift\` (different block exists,
+re-run with \`--force\`), \`remove\` / \`remove-noop\` (for \`mcp remove\`).
+
+## Overriding the server URL
+
+\`\`\`bash
+ISH_MCP_URL=http://localhost:8000/mcp ish mcp add --client cursor --yes
+\`\`\`
+
+Useful for the dev backend or a hosted preview environment. The same
+env var is read by \`mcp list\` so the reported status reflects the
+overridden URL.
+
+## Related
+
+- \`reference/json-mode\` — display vs capture vs chain output rules.
+`;
 const PAGES = [
     {
         slug: "overview",
@@ -3575,13 +3752,13 @@ const PAGES = [
     {
         slug: "concepts/iteration",
         title: "concept: iteration",
-        description: "One configured run of a study (URL, media, or chat). Covers segments, segment labels, HTML content, and chat mode_details (external_chatbot vs tester_pair).",
+        description: "One configured run of a study (URL, media, or chat). Covers segments, segment labels, HTML content, and chat mode_details (external_chatbot vs participant_pair).",
         body: CONCEPT_ITERATION,
     },
     {
         slug: "concepts/assignment",
         title: "concept: assignment",
-        description: "A single task a tester performs; CLI input formats.",
+        description: "A single task a participant performs; CLI input formats.",
         body: CONCEPT_ASSIGNMENT,
     },
     {
@@ -3603,9 +3780,9 @@ const PAGES = [
         body: CONCEPT_ROUND,
     },
     {
-        slug: "concepts/profile",
-        title: "concept: tester profile",
-        description: "Reusable audience persona; generate vs manual create.",
+        slug: "concepts/person",
+        title: "concept: person",
+        description: "Reusable persona; generate vs manual create.",
         body: CONCEPT_PROFILE,
     },
     {
@@ -3615,10 +3792,10 @@ const PAGES = [
         body: CONCEPT_SOURCE,
     },
     {
-        slug: "concepts/audience",
-        title: "concept: audience selection",
-        description: "Audience flags shared by study run and ask run --new.",
-        body: CONCEPT_AUDIENCE,
+        slug: "concepts/people",
+        title: "concept: people selection",
+        description: "People-selection flags shared by study run and ask run --new.",
+        body: CONCEPT_PEOPLE,
     },
     {
         slug: "concepts/site-access",
@@ -3641,7 +3818,7 @@ const PAGES = [
     {
         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.",
+        description: "Resume a terminal participant with more steps and an optional mid-run instruction. Cancel + extend as a reversible stop/start pair.",
         body: CONCEPT_EXTENDING_SIMULATION,
     },
     {
@@ -3683,13 +3860,13 @@ const PAGES = [
     {
         slug: "guides/first-study",
         title: "guide: your first study, end to end",
-        description: "Login → workspace → audience → study → iteration → run → results.",
+        description: "Login → workspace → people → study → iteration → run → results.",
         body: GUIDE_FIRST_STUDY,
     },
     {
         slug: "guides/chat",
         title: "guide: chat-modality studies",
-        description: "Configure a chatbot endpoint (slots-only model), smoke test it, run a chat-modality study (external_chatbot mode). Also: tester_pair mode — two AI personas talk to each other for rehearsal scenarios.",
+        description: "Configure a chatbot endpoint (slots-only model), smoke test it, run a chat-modality study (external_chatbot mode). Also: participant_pair mode — two AI personas talk to each other for rehearsal scenarios.",
         body: GUIDE_CHAT,
     },
     {
@@ -3699,10 +3876,16 @@ const PAGES = [
         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,
+        slug: "guides/build-specific-person",
+        title: "guide: build a specific simulated person from notes",
+        description: "Iterative probe loop for one specific persona: person suggest-scenarios returns LLM probes; answer them locally; person evidence add persists answers; person evidence list reads them back.",
+        body: GUIDE_BUILD_SPECIFIC_PERSON,
+    },
+    {
+        slug: "guides/mcp-add",
+        title: "guide: wire ish into your AI clients (`ish mcp add`)",
+        description: "One command wires the hosted ish MCP server into Cursor, VS Code, Claude Code, Claude Desktop, and Windsurf. Idempotent, atomic, preserves unrelated keys, no tokens written.",
+        body: GUIDE_MCP_ADD,
     },
 ];
 const PAGES_BY_SLUG = new Map(PAGES.map((p) => [p.slug, p]));