@ishlabs/cli 0.17.7 → 0.19.0

package/dist/lib/skill-content.js

@@ -23,9 +23,9 @@ const VERSION = pkg.version;
  * the description with verbs the user is likely to say plus the noun
  * "ish". Hard cap is 1024 chars. Front-load the use case.
  */
-const SKILL_DESCRIPTION = "Use this skill whenever the user mentions ish, a study, a tester profile, " +
-    "a simulation run, an \"ask\", an audience, a chatbot probe, wants to " +
-    "dispatch tests against AI testers, or wants to rehearse a conversation " +
+const SKILL_DESCRIPTION = "Use this skill whenever the user mentions ish, a study, a person, " +
+    "a simulation run, an \"ask\", a group of people, a chatbot probe, wants to " +
+    "dispatch tests against AI participants, or wants to rehearse a conversation " +
     "between two AI personas (e.g. sales rep vs. skeptical buyer). Covers both " +
     "the `ish` CLI (via Bash) and the hosted ish MCP server " +
     "(`mcp__claude_ai_ish__*` on claude.ai) — same operations, pick whichever " +
@@ -37,7 +37,7 @@ ish runs user-research simulations: simulated people experience your draft (page
 
 ## When to invoke
 
-The user mentioned \`ish\`, a study, an "ask", a tester profile, an audience, a simulation, "rehearse", "compare variants", "test before shipping", "probe a chatbot".
+The user mentioned \`ish\`, a study, an "ask", a person, a group of people, a simulation, "rehearse", "compare variants", "test before shipping", "probe a chatbot".
 
 ## Drivers
 
@@ -48,8 +48,10 @@ ish has two surfaces; pick whichever your environment has:
 
 Both wrap the same operations. If neither is present, tell the user: \`npm i -g @ishlabs/cli\`, or enable the ish connector on claude.ai. Don't try to drive ish without a driver.
 
+**Bridging CLI → MCP for the user's editor / desktop agent**: if the user has the CLI but their editor or desktop agent (Cursor, VS Code, Claude Code, Claude Desktop, Windsurf) isn't yet wired to call ish, one command does it: \`ish mcp add --all --yes\`. Writes the per-client MCP config block, never embeds a token (OAuth on first connect), idempotent. See \`ish docs get-page guides/mcp-add\`.
+
 **When both are available, pick by op:**
-- Streaming results to a watching user → **CLI** with \`--wait\` (per-tester output as testers complete).
+- Streaming results to a watching user → **CLI** with \`--wait\` (per-participant output as participants complete).
 - Structured one-shot reads or run dispatch → **MCP** (JSON in, JSON out, no shell).
 - Idempotent setup (e.g. cold-start workspace) → **CLI** has \`--ensure\`; MCP doesn't.
 - Local file uploads (images, video, docs) → **CLI** only — MCP doesn't accept binaries.
@@ -60,16 +62,16 @@ Both wrap the same operations. If neither is present, tell the user: \`npm i -g
 
 \`\`\`
 Workspace (= product)
-├── Tester Profile (tp-…)    reusable AI persona
+├── Person (p-…)    reusable AI persona
 ├── Study (s-…)              persistent artifact for testing a real surface
 │   └── Iteration (i-…)      one configured run; carries the URL or media
 ├── Ask (a-…)                lightweight artifact for reactions to text/image variants
-│   └── Round                unit of execution; audience fixed at ask creation
+│   └── Round                unit of execution; participants fixed at ask creation
 └── Chat Endpoint            workspace-level definition of an external chatbot
                               (referenced by study modality: chat, mode: external_chatbot)
 \`\`\`
 
-**Audience is a query, not an entity.** Both \`ask_run\` and \`study_run\` take an \`audience\` argument shaped as \`{ profile_ids: [...] }\` (explicit) or \`{ sample: N, filters: {...} }\` (sampled from an existing pool). There is no \`audience\` resource to create — you build profiles via \`audience_build\` (or reuse existing ones via \`profile_list\`) and pass them in.
+**Audience is a query, not an entity.** Both \`ask_run\` and \`study_run\` take an \`audience\` argument shaped as \`{ person_ids: [...] }\` (explicit) or \`{ sample: N, filters: {...} }\` (sampled from an existing pool). There is no \`audience\` resource to create — you build profiles via \`group_build\` (or reuse existing ones via \`profile_list\`) and pass them in.
 
 Two run verbs:
 - **study run** — simulate on a real surface (URL, media, document, chat endpoint).
@@ -81,11 +83,11 @@ Heuristic: **study** for "test this prototype/page/flow"; **ask** for "which cop
 
 Each shape names the verb, the *required precursors*, and the **load-bearing knobs** — the arguments that change output quality, not just behavior. Look up the full schema in the MCP tool description or \`ish <command> --help\` once you've picked the shape.
 
-Examples below use MCP shape; for CLI, kebab-case the tool name (\`ask_run\` → \`ish ask run\`) and pass equivalent flags (\`profile_ids: [...]\` → \`--profile-id tp-… --profile-id tp-…\`).
+Examples below use MCP shape; for CLI, kebab-case the tool name (\`ask_run\` → \`ish ask run\`) and pass equivalent flags (\`person_ids: [...]\` → \`--person-id p-… --person-id p-…\`).
 
 ### Compare text or image variants → \`ask_run\`
 
-- **Precursor**: an audience (see "Audience is a query" above). If you don't already have suitable tester profiles, build them first via \`audience_build\`; reuse via \`profile_list\` when possible.
+- **Precursor**: a group of people (see "Audience is a query" above). If you don't already have suitable people, build them first via \`group_build\`; reuse via \`profile_list\` when possible.
 - **Load-bearing knobs**:
   - \`wants_pick: true\` — adds an aggregate winner verdict. Without it you get prose reactions but no clear answer.
   - \`wants_ratings: true\` — adds per-variant numeric scores.
@@ -96,22 +98,23 @@ Examples below use MCP shape; for CLI, kebab-case the tool name (\`ask_run\` →
   \`\`\`
   ask_run({
     variants:  [ { label: "A", content: "..." }, { label: "B", content: "..." } ],
-    audience:  { profile_ids: ["tp-…", ...] },   // or { sample: 10 }
+    audience:  { person_ids: ["p-…", ...] },   // or { sample: 10 }
     wants_pick: true,
     wants_ratings: true,
     wait: true,
   })
   \`\`\`
-- **Output**: per-tester reasoning + (if \`wants_pick\`) aggregate winner with confidence.
+- **Output**: per-participant reasoning + (if \`wants_pick\`) aggregate winner with confidence.
 
 ### Test a live page or prototype → \`study_run\` (modality: interactive)
 
-- **Precursor**: a study with a URL. Either inline at create-time (\`study_create({ modality: "interactive", url: "..." })\`) or as a separate iteration (\`iteration_create({ study_id, url })\`) when you want to A/B iterations later or upload local files. An **assignment** is required — what the tester is supposed to attempt.
-- **Audience**: pass \`audience: { profile_ids: [...] }\` or \`{ sample: N }\` to \`study_run\`, same contract as \`ask_run\`. Audience is set on the *run*, not the study.
+- **Precursor**: a study with a URL. Either inline at create-time (\`study_create({ modality: "interactive", url: "..." })\`) or as a separate iteration (\`iteration_create({ study_id, url })\`) when you want to A/B iterations later or upload local files. An **assignment** is required — what the participant is supposed to attempt.
+- **Audience**: pass \`audience: { person_ids: [...] }\` or \`{ sample: N }\` to \`study_run\`, same contract as \`ask_run\`. Audience is set on the *run*, not the study.
 - **Load-bearing knobs**:
-  - \`assignment\` (on \`study_create\`) — what the tester is supposed to do. Format: \`"<label>:<instruction>"\`. The whole run hinges on this being clear.
-  - \`wait\` (MCP) / \`--wait\` (CLI) — streams per-tester results as they complete. CLI streams to stdout in real-time; MCP blocks until the whole run finishes. For a watching user, prefer the CLI here.
-  - \`count\` (on \`study_run\`) — how many testers.
+  - \`assignment\` (on \`study_create\`) — what the participant is supposed to do. Format: \`"<label>:<instruction>"\`. The whole run hinges on this being clear.
+  - **steps (optional checklist)** — an assignment can carry an ordered \`steps\` list of atomic actions (\`{name, description?}\`), authored via the CLI JSON forms (\`--assignments-file\` / \`--assignments\`) — not the \`"<label>:<instruction>"\` shorthand. Honored for **interactive** and **external_chatbot chat** only. After a run, \`study get\` reports a per-step \`step_completion\` rollup (pass rate + sample failures). Use steps when "did they finish?" is a checklist, not a single yes/no.
+  - \`wait\` (MCP) / \`--wait\` (CLI) — streams per-participant results as they complete. CLI streams to stdout in real-time; MCP blocks until the whole run finishes. For a watching user, prefer the CLI here.
+  - \`count\` (on \`study_run\`) — how many participants.
 - **Shape**:
   \`\`\`
   study_create({
@@ -119,18 +122,18 @@ Examples below use MCP shape; for CLI, kebab-case the tool name (\`ask_run\` →
     url: "https://staging.acme.io/welcome",
     assignment: "Complete signup:Go through the 4-step wizard end-to-end",
   })
-  study_run({ study_id: "s-…", audience: { profile_ids: [...] }, count: 15, wait: true })
+  study_run({ study_id: "s-…", audience: { person_ids: [...] }, count: 15, wait: true })
   \`\`\`
-- **Output**: per-tester journey transcripts + aggregate friction / blocker / positive-moment counts.
+- **Output**: per-participant journey transcripts + aggregate friction / blocker / positive-moment counts.
 
 ### Probe a customer chatbot → \`study_run\` (modality: chat, mode: external_chatbot)
 
 - **Precursors**:
-  1. A **chat endpoint** definition at the workspace level. \`chat_endpoint_init\` from a curl spec (handles auth headers, request/response shape; **upsert-by-name** — safe to re-call with the same \`name\` to rotate auth or change the request shape) → \`chat_endpoint_test\` to confirm it responds correctly before dispatching simulated testers.
+  1. A **chat endpoint** definition at the workspace level. \`chat_endpoint_init\` from a curl spec (handles auth headers, request/response shape; **upsert-by-name** — safe to re-call with the same \`name\` to rotate auth or change the request shape) → \`chat_endpoint_test\` to confirm it responds correctly before dispatching simulated participants.
   2. A study with \`modality: "chat"\`, \`mode: "external_chatbot"\`, the endpoint reference, and an \`assignment\`.
-- **Audience**: same \`{ profile_ids } | { sample }\` contract; pass to \`study_run\`. For custom personas (e.g. "frustrated vs polite"), \`audience_build\` first.
+- **Audience**: same \`{ person_ids } | { sample }\` contract; pass to \`study_run\`. For custom personas (e.g. "frustrated vs polite"), \`group_build\` first.
 - **Load-bearing knobs**:
-  - \`assignment\` — what the tester tries to do (\`"Cancel:Try to cancel your subscription"\`).
+  - \`assignment\` — what the participant tries to do (\`"Cancel:Try to cancel your subscription"\`).
   - \`count\` on the run.
 - **Shape**:
   \`\`\`
@@ -138,52 +141,52 @@ Examples below use MCP shape; for CLI, kebab-case the tool name (\`ask_run\` →
   chat_endpoint_test({ endpoint: "support-bot", message: "hi" })
   study_create({ modality: "chat", mode: "external_chatbot", endpoint: "support-bot",
                  assignment: "Cancel:Try to cancel your subscription" })
-  study_run({ study_id: "s-…", audience: { profile_ids: [...] }, count: 8, wait: true })
+  study_run({ study_id: "s-…", audience: { person_ids: [...] }, count: 8, wait: true })
   \`\`\`
-- **Output**: full conversation transcripts per tester + aggregate success / blocker analysis.
+- **Output**: full conversation transcripts per participant + aggregate success / blocker analysis.
 
 ### Test a media artifact (document, image, video, audio) → \`study_run\`
 
 - **Precursors**:
   1. A study with the chosen modality: \`study_create({ modality: "document" | "image" | "video" | "audio", assignment: "..." })\`.
   2. An **iteration** carrying the media. For local files, **CLI only** — \`ish iteration create --study s-… --media @./deck.pdf\` (the \`@\` prefix triggers upload). For hosted URLs, either driver works: \`iteration_create({ study_id, content_url: "https://..." })\`.
-- **Audience**: same \`{ profile_ids } | { sample }\` contract; pass to \`study_run\`. Reusable across runs (see "Lifecycle" below).
+- **Audience**: same \`{ person_ids } | { sample }\` contract; pass to \`study_run\`. Reusable across runs (see "Lifecycle" below).
 - **Load-bearing knobs**:
   - \`assignment\` on \`study_create\` — for review-style media (decks, ad creative), frame as decision: \`"Take a first meeting:Review this Series A deck and decide whether you'd take a first meeting"\`. Page/timestamp-level attribution depends on the assignment asking for it explicitly.
   - \`wait\` / \`--wait\` — same streaming story as interactive.
   - \`count\` on \`study_run\`.
-- **Iterating on the artifact** (v2 deck, v3 deck): create a **new iteration** on the same study (\`iteration_create\`), reuse the audience's \`profile_ids\`. See "Lifecycle".
-- **Output**: per-tester reactions to the artifact + aggregate themes.
+- **Iterating on the artifact** (v2 deck, v3 deck): create a **new iteration** on the same study (\`iteration_create\`), reuse the people's \`person_ids\`. See "Lifecycle".
+- **Output**: per-participant reactions to the artifact + aggregate themes.
 
-### Rehearse a conversation between two AI personas → \`study_run\` (modality: chat, mode: tester_pair)
+### Rehearse a conversation between two AI personas → \`study_run\` (modality: chat, mode: participant_pair)
 
 **If the user might want the same persona across multiple turns, pin profiles up-front — you can't retro-pin after a run.** Without pinning, personas are re-synthesized from the assignment text each time, so "the same VC from earlier" becomes prose-only continuity.
 
-- **Precursor**: a workspace and (optionally) one or two tester profiles for persona pinning. If you skip the profiles, ish synthesizes both personas from the \`assignment\` text per-run — fine for one-shot rehearsals, drifts between iterations.
-- **Audience**: optional. For persona continuity across iterations, build profiles via \`audience_build\` (or reuse via \`profile_list\`) and pass \`audience: { profile_ids: [...] }\` to \`study_run\` — the same profiles play the same roles each time.
+- **Precursor**: a workspace and (optionally) one or two people for persona pinning. If you skip the people, ish synthesizes both personas from the \`assignment\` text per-run — fine for one-shot rehearsals, drifts between iterations.
+- **Audience**: optional. For persona continuity across iterations, build profiles via \`group_build\` (or reuse via \`profile_list\`) and pass \`audience: { person_ids: [...] }\` to \`study_run\` — the same profiles play the same roles each time.
 - **Load-bearing knobs**:
   - \`assignment\` — encodes BOTH personas and what each is trying to do. More prose-heavy than other assignments; be specific. Example: \`"Founder pitches Series A to skeptical VC. Founder: defends AI customer-support startup, $2M ARR, 15% MoM. VC: thinks SaaS-for-SaaS is saturated, probes moat and unit economics."\`
   - \`count\` — typically 1 per run; set higher to generate variations.
-- **Iterating the scenario** (turn-by-turn refinement): create a **new iteration** with a revised assignment; reuse the same \`profile_ids\` if you pinned personas. See "Lifecycle".
+- **Iterating the scenario** (turn-by-turn refinement): create a **new iteration** with a revised assignment; reuse the same \`person_ids\` if you pinned personas. See "Lifecycle".
 - **Output**: a full transcript per rehearsal.
 
-### Generate a fresh audience → \`audience_build\`
+### Generate a fresh group → \`group_build\`
 
 - **Input**: a \`description\`, a \`count\`, and optionally \`sources\` (transcripts / audio / images / docs that seed persona generation — for "make profiles that feel like these real customers"). Local files force CLI (binary upload constraint).
-- **Output**: a list of \`profile_ids\` to pass into \`ask_run\` or \`study_run\`.
+- **Output**: a list of \`person_ids\` to pass into \`ask_run\` or \`study_run\`.
 - **Cost**: slow (~30-120s) + credit-bearing. Reuse profiles via \`profile_list\` when possible. Sensible defaults: \`count: 5-10\` for ad-hoc tests, \`count: 20+\` for studies where you want statistical signal.
-- **Growing an audience**: build only the delta — don't rebuild. Concat the new \`profile_ids\` with the existing ones for the next run. The "audience is a query" framing means there's no audience entity to update.
+- **Growing a group of people**: build only the delta — don't rebuild. Concat the new \`person_ids\` with the existing ones for the next run. The "audience is a query" framing means there's no audience entity to update.
 - **Shapes**:
   \`\`\`
   // Simple — description only
-  audience_build({
+  group_build({
     description: "Parents of toddlers (ages 1-3), US, evening-routine focused",
     count: 8,
   })
-  // → { profile_ids: ["tp-…", ...] }
+  // → { person_ids: ["p-…", ...] }
 
   // Seeded from real transcripts (CLI only for local files)
-  // ish audience build --description "..." --count 10 \\
+  // ish person generate --description "..." --count 10 \\
   //   --source @./interviews/customer-1.md \\
   //   --source @./interviews/customer-2.md
   \`\`\`
@@ -194,28 +197,29 @@ The most common multi-turn question: "user wants to change X — re-use the exis
 
 | Change you want | What to do |
 |---|---|
-| Same ask, **same audience**, new variants | Pass \`ask_id\` (MCP) or \`--ask\` (CLI) on \`ask_run\` — re-uses the locked audience. |
-| Same ask, **different audience** | New ask: omit \`ask_id\` (MCP) or pass \`--new\` (CLI). Audience is locked at ask creation. |
+| Same ask, **same participants**, new variants | Pass \`ask_id\` (MCP) or \`--ask\` (CLI) on \`ask_run\` — re-uses the locked participants. |
+| Same ask, **different participants** | New ask: omit \`ask_id\` (MCP) or pass \`--new\` (CLI). Participants are locked at ask creation. |
 | Same study, **new media** (v2 deck, new image) | New **iteration** on the same study (\`iteration_create({ study_id, content_url \\| --media @path })\`). Iterations are immutable once they have results — never edit. |
-| Same study, **new assignment** | **New study.** Assignment lives on the study; there's no in-place edit. Keep the old study's id for side-by-side comparison. *(Tester-pair exception: the assignment IS the content there — use a new **iteration** on the same study, not a new study.)* |
-| Same audience across multiple runs / studies | Reuse the \`profile_ids\` array. Profiles are workspace-scoped resources (\`tp-…\`) — they live independently of any ask or study. |
+| Same study, **new assignment** | **New study.** Assignment lives on the study; there's no in-place edit. Keep the old study's id for side-by-side comparison. *(Participant-pair exception: the assignment IS the content there — use a new **iteration** on the same study, not a new study.)* |
+| Same people across multiple runs / studies | Reuse the \`person_ids\` array. Profiles are workspace-scoped resources (\`p-…\`) — they live independently of any ask or study. |
 | Chat endpoint definition needs to change (auth rotate, URL change) | \`chat_endpoint_init\` is **upsert-by-name** — re-init with the same \`name\` and a new \`from_curl\` spec. Re-run \`chat_endpoint_test\` to confirm. |
-| Persona reuse in tester-pair | Pin via \`profile_ids\` on the first \`study_run\`; pass the same ids on subsequent runs. Without pinning, personas are re-synthesized from the assignment per run. |
+| Persona reuse in participant-pair | Pin via \`person_ids\` on the first \`study_run\`; pass the same ids on subsequent runs. Without pinning, personas are re-synthesized from the assignment per run. |
 
 When in doubt: side-by-side comparison usually beats in-place edits. Ids are cheap; result history isn't.
 
 ## Pitfalls
 
 - **Cold start on free plan**: \`workspace_create\` returns \`usage_limit_reached\` at the free-plan cap (1 workspace). Always inspect with \`workspace_list\` first. **MCP-only recipe** (no \`--ensure\` available): \`workspace_list\` → if non-empty, use the first; if empty, \`workspace_create\`; if \`workspace_create\` returns \`usage_limit_reached\`, re-call \`workspace_list\` (a workspace exists you didn't see — possibly created by another session). **CLI shortcut**: \`ish workspace create --name <name> --ensure\` is idempotent by name.
-- **Ask audience vs variants** — see Lifecycle table for the re-use vs new-ask decision.
+- **Ask participants vs variants** — see Lifecycle table for the re-use vs new-ask decision.
 - **Study iterations are immutable once they have results** — see Lifecycle table for new-iteration vs new-study.
-- **Credit costs**: \`ask_run\`, \`study_run\`, and \`audience_build\` consume credits. Check \`workspace_get\`'s \`credits\` headroom before dispatching large runs. For free-plan ad-hoc tests, default \`count: 5-8\` testers + 2 variants is usually within budget.
-- **\`audience_build\` may return fewer profiles than requested** if the description is over-constrained. Always read the returned \`profile_ids\` count, don't trust the requested \`count\` blindly.
+- **Credit costs**: \`ask_run\`, \`study_run\`, and \`group_build\` consume credits. Check \`workspace_get\`'s \`credits\` headroom before dispatching large runs. For free-plan ad-hoc tests, default \`count: 5-8\` participants + 2 variants is usually within budget.
+- **\`group_build\` may return fewer profiles than requested** if the description is over-constrained. Always read the returned \`person_ids\` count, don't trust the requested \`count\` blindly.
 - **Variants of wildly different length** (one-line vs paragraph) can skew picks toward the longer one. Keep variants comparable in shape.
-- **Chatbot endpoint response-shape mismatch**: \`chat_endpoint_test\` succeeds shallowly if the bot responds at all, but a wrong response path (e.g. bot returns \`{ data: { reply } }\` instead of \`{ reply }\`) produces empty transcripts on the actual run. Inspect one full test response before dispatching testers.
+- **Chatbot endpoint response-shape mismatch**: \`chat_endpoint_test\` succeeds shallowly if the bot responds at all, but a wrong response path (e.g. bot returns \`{ data: { reply } }\` instead of \`{ reply }\`) produces empty transcripts on the actual run. Inspect one full test response before dispatching participants.
 - **Chatbot auth drift**: tokens/sessions baked into \`--from-curl\` expire. If transcripts come back as identical short error strings, re-run \`chat_endpoint_test\` and refresh the curl spec.
-- **401 surfaces as fake blocker**: an unauthenticated endpoint produces "tester got stuck on auth screen" — looks like a UX blocker but is config. Always confirm endpoint auth before reading transcripts as user-research data.
+- **401 surfaces as fake blocker**: an unauthenticated endpoint produces "participant got stuck on auth screen" — looks like a UX blocker but is config. Always confirm endpoint auth before reading transcripts as user-research data.
 - **No per-page/per-timestamp scoping for media**: there's no "evaluate just slide 14" or "react to seconds 0-30" API. State the focus explicitly in the \`assignment\` text, or pre-stitch the artifact (e.g. replace one slide locally, upload as a new iteration).
+- **\`study get --json\` participants live at the top level**, not nested under \`iterations[*].participants\`. The backend split made \`/studies/{id}\` lite (metadata + iteration shells, no participant graph) and added \`/studies/{id}/participants\`; the CLI joins them so \`study get --json\` carries a flat \`participants[]\` with \`iteration_id\` on each row. Read \`.participants[]\`, not \`.iterations[].participants[]\`.
 
 ## When in doubt
 
@@ -232,7 +236,7 @@ Each workflow below is a complete transcript an agent can adapt. Run
 ## 1. First study from zero
 
 Goal: from a fresh install to a finished interactive study with 3
-testers and one question.
+participants and one question.
 
 \`\`\`bash
 # 1. Authenticate (browser flow, saves tokens to ~/.ish/config.json)
@@ -242,8 +246,8 @@ ish login
 ish workspace create --name "Demo" --base-url https://example.com
 ish workspace use w-…
 
-# 3. Generate a small audience
-ish profile generate \\
+# 3. Generate a small group of people
+ish person generate \\
     --description "Tech-savvy millennials in the US who use mobile banking" \\
     --count 3
 
@@ -266,6 +270,33 @@ ish study run --all --wait
 ish study results --json | jq .
 \`\`\`
 
+### 1a. Give the assignment a step-by-step checklist
+
+When "did they finish?" is a checklist rather than a single yes/no, attach
+\`steps\` to the assignment. Steps are JSON-only (no inline shorthand) and
+honored for **interactive** + **external_chatbot chat** modalities only.
+
+\`\`\`bash
+# assignments.json
+# [
+#   { "name": "Buy", "instructions": "Add an item to cart and check out",
+#     "steps": [
+#       { "name": "Find a product", "description": "Browse to any item" },
+#       { "name": "Add to cart" },
+#       { "name": "Complete checkout" }
+#     ] }
+# ]
+ish study create --name "Checkout" --modality interactive \\
+    --url https://shop.example.com \\
+    --assignments-file ./assignments.json
+ish study use s-…
+ish study run --all --wait
+
+# After the run, each step gets a pass-rate rollup:
+ish study get s-…                       # human: "✓ Add to cart 4/5 (80%)" per step
+ish study get s-… --json --verbose      # step_completion[] incl. sample_failures[].participant_id
+\`\`\`
+
 ## 2. Quick A/B ask with image variants
 
 Goal: ship 30 simulated reactions to two hero images, with a "which do
@@ -289,7 +320,7 @@ adds an \`aggregates\` field per round with \`picks\`, \`ratings\` (mean
 + n per variant), and a \`winner\`. See \`ish docs get-page
 reference/json-mode\` for the full shape.
 
-Add a follow-up round with no audience change:
+Add a follow-up round with no participant change:
 
 \`\`\`bash
 ish ask run --prompt "Which one would you click on?" \\
@@ -300,29 +331,41 @@ ish ask run --prompt "Which one would you click on?" \\
 
 ## 3. Generate profiles from a real source
 
-Goal: turn a customer interview transcript into a 4-profile audience.
+Goal: turn a customer interview transcript into a 4-person group.
+
+\`person generate\` is an async agentic job: it reads your brief and any
+uploaded sources (transcripts, emails, PDFs, audio, images) describing how
+real people reacted, then produces profiles PLUS scenarios grounded in those
+reactions. It enqueues, polls ~30-60s, then prints the profiles (with
+scenarios attached unless \`--no-scenarios\`). \`--json\` returns
+\`{job: {person_ids}, profiles: [...]}\`.
 
 \`\`\`bash
 # Inline — auto-uploads the file:
-ish profile generate --source ./interviews/sarah.txt --count 4
+ish person generate --source ./interviews/sarah.txt --count 4
+
+# The per-source note is the researcher's: how the person reacted to THAT file.
+ish source upload ./proposal.eml --description "called this proposal lazy and vague"
+# → ps-3a4 (status: processed)
+ish person generate --description "Skeptical enterprise buyer" --source ps-3a4 --count 1 --json
 
 # Or upload once and reuse the source alias:
 ish source upload ./call.mp3 --diarize
-# → tps-3a4 (status: processed)
-ish profile generate --source tps-3a4 --propose-count
+# → ps-3a4 (status: processed)
+ish person generate --source ps-3a4 --propose-count
 # → { proposed_count: 4, rationale: "..." }
-ish profile generate --source tps-3a4 --count 4
+ish person generate --source ps-3a4 --count 4
 \`\`\`
 
-## 4. Build a specific simulated tester from notes
+## 4. Build a specific simulated person from notes
 
 Goal: rebuild one named persona (a real prospect, a stakeholder for
 a pitch rehearsal) via the iterative probe loop — distinct from
-\`profile generate\`, which is for audiences.
+\`person generate\`, which is for groups.
 
 \`\`\`bash
 # 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 oncall for the payments edge. Burned by a Black Friday \\
         outage last year." \\
@@ -333,33 +376,33 @@ ish profile suggest-scenarios \\
 #    [{"text":"...","source":"situation","scenario_prompt":"..."}, ...]
 #    Valid source values: situation, voice, binary, micro-story
 
-# 3. Save the profile shell
-ish profile create --file ./persona.json
-# → tp-d4e
+# 3. Save the person shell
+ish person create --file ./persona.json
+# → p-d4e
 
 # 4. Persist the answers as structured evidence
-ish profile evidence add tp-d4e --traces-file ./answers.json
+ish person evidence add p-d4e --traces-file ./answers.json
 
 # 5. Read back what's saved (also useful before the next probe round)
-ish profile evidence list tp-d4e
+ish person evidence list p-d4e
 \`\`\`
 
 To iterate, feed prior prompts/answers back in so the LLM doesn't
 paraphrase what you already asked:
 
 \`\`\`bash
-ish profile suggest-scenarios \\
+ish person suggest-scenarios \\
     --context-file ./notes.md --count 3 \\
     --already-surfaced '["PagerDuty fires at 02:00."]' \\
     --previous-answers @./answers.json
 \`\`\`
 
-See \`ish docs get-page guides/build-specific-tester\` for the full
+See \`ish docs get-page guides/build-specific-person\` for the full
 walkthrough including the four probe-type shapes.
 
 ## 5. Target a gated URL (Vercel preview / staging gate / login form)
 
-Configure credentials once on the workspace; testers reuse them.
+Configure credentials once on the workspace; participants reuse them.
 
 \`\`\`bash
 # Show what's configured:
@@ -371,7 +414,7 @@ ish workspace site-access basic-auth --username alice --password hunter2
 # Session cookie (Vercel preview, Lovable, etc.):
 ish workspace site-access cookie --name session --value abc123
 
-# Login form (typed by the tester into the page):
+# Login form (typed by the participant into the page):
 ish workspace site-access login --username demo --password demo
 \`\`\`
 
@@ -383,28 +426,28 @@ printf %s "$STAGING_PW" | ish workspace site-access basic-auth \\
     --username alice --password -
 \`\`\`
 
-## 6. Re-run a study with a fresh audience
+## 6. Re-run a study with a fresh group
 
-Goal: same study, same iteration, but compare audiences.
+Goal: same study, same iteration, but compare groups.
 
 \`\`\`bash
 # First run — Swedish 35-50:
 ish study run --country SE --min-age 35 --max-age 50 --sample 5 --wait
 
-# Second run — every female profile in the workspace, same iteration:
+# Second run — every female person in the workspace, same iteration:
 ish study run --gender female --all --wait
 
-# Free-text filters: --search matches the profile **name**, --bio
-# matches the profile **bio**, --occupation matches the profile
+# Free-text filters: --search matches the person **name**, --bio
+# matches the person **bio**, --occupation matches the person
 # **occupation** (repeatable, OR-joined). All are case-insensitive
-# substrings — the same flag set works on \`ish profile list\`,
-# \`ish ask run\`, \`ish ask add-testers\`, and \`ish ask create\`.
+# substrings — the same flag set works on \`ish person list\`,
+# \`ish ask run\`, \`ish ask add-people\`, and \`ish ask create\`.
 ish study run --bio "screen reader" --all --wait
 ish study run --occupation founder --occupation designer --sample 6 --wait
 \`\`\`
 
-If you don't pass any audience flags, \`ish study run\` reuses the
-iteration's existing testers — useful for re-running after fixing the
+If you don't pass any people flags, \`ish study run\` reuses the
+iteration's existing participants — useful for re-running after fixing the
 target page.
 
 ## 7. Localhost target (dev environment)
@@ -438,9 +481,9 @@ ish iteration create --url "$URL"
 The chat modality has **two modes**, picked by
 \`iteration.details.mode_details.mode\`:
 
-- **\`external_chatbot\`** — testers probe a customer chatbot endpoint
+- **\`external_chatbot\`** — participants probe a customer chatbot endpoint
   (the original chat behaviour). Audience size is set on \`study run\`.
-- **\`tester_pair\`** — two AI tester audiences converse with each
+- **\`participant_pair\`** — two AI people converse with each
   other. Each side has its own scenario + goal; the other side does
   not see it (asymmetry contract). Audiences are pinned to the
   iteration: equal counts zip 1:1 by index, or one side of 1
@@ -488,12 +531,12 @@ ish chat endpoint get "$ID" --verbose \\
   | ish chat endpoint update "$ID" --endpoint-config -
 
 # 4. Run a chat-modality study referencing the endpoint. Audience size
-#    is set on study run, not study create (--sample, --all, --profile).
+#    is set on study run, not study create (--sample, --all, --person).
 STUDY=$(ish study create --modality chat --endpoint "$ID" \\
           --name "Sign-up Q1" --assignment "Sign up:Try to sign up" \\
         | jq -r .id)
 ish study run --study "$STUDY" --sample 5 --wait
-ish study results "$STUDY" --json | jq '.testers'
+ish study results "$STUDY" --json | jq '.participants'
 \`\`\`
 
 For stateful bots, thread \`conversation_id\` across single-turn
@@ -528,21 +571,21 @@ into \`update --endpoint-config -\`. Field-shorthand flags
 without round-tripping.
 
 Failed chat workers surface their error in
-\`study results --json\` under \`testers[].error_message\` and
+\`study results --json\` under \`participants[].error_message\` and
 also in \`study poll --json\`. Branch on it instead of treating
 \`interaction_count: 0\` as a generic failure.
 
 Pre-flight tip: \`ish workspace info\` exposes
-\`{studies_used, studies_max, testers_used, testers_max, tier}\` so
+\`{studies_used, studies_max, participants_used, participants_max, tier}\` so
 you can branch on plan caps before \`study create\` returns
 \`error_code: usage_limit_reached\`.
 
 The full reference is at \`ish docs get-page guides/chat\`,
 secrets are at \`ish docs get-page concepts/secret\`.
 
-### 7b. tester_pair — rehearse a two-AI conversation
+### 7b. participant_pair — rehearse a two-AI conversation
 
-Goal: pit two AI tester audiences against each other to see how a
+Goal: pit two AI people against each other to see how a
 two-role conversation unfolds — a sales rep vs. a skeptical CTO, a
 founder vs. an investor archetype, a manager vs. a direct report
 ahead of a difficult conversation. Each side has its own scenario
@@ -552,10 +595,10 @@ what makes the rehearsal credible).
 One-shot study + iteration:
 
 \`\`\`bash
-ish study create --modality chat --chat-mode tester_pair \\
+ish study create --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 "You are a senior sales rep pitching ish to a new prospect." \\
     --scenario-b "You are a skeptical CTO; surface risks before agreeing to a pilot." \\
     --assignment "Pitch:Try to land a pilot"
@@ -566,50 +609,50 @@ ish study run -y
 Or add a pair iteration to an existing chat study:
 
 \`\`\`bash
-ish iteration create --study s-... --chat-mode tester_pair \\
-    --audience-a tp-a1,tp-a2 --audience-b tp-b1,tp-b2 \\
+ish iteration create --study s-... --chat-mode participant_pair \\
+    --group-a p-a1,p-a2 --group-b p-b1,p-b2 \\
     --scenario-a @./scenario_a.md --scenario-b @./scenario_b.md \\
     --max-turns 14
 \`\`\`
 
 Rules to remember:
-- Each side needs **either** \`--profile-*\` (explicit IDs) **or**
+- Each side needs **either** \`--person-*\` (explicit IDs) **or**
   \`--role-criteria-*\` (a filter the backend resolves). They can also
   be combined — criteria then validates the explicit list.
-- When **both sides** use explicit \`--audience-a\` / \`--audience-b\`, they
-  must be the same length (≥ 1). Pairs run 1:1 by index. Same profile
+- When **both sides** use explicit \`--group-a\` / \`--group-b\`, they
+  must be the same length (≥ 1). Pairs run 1:1 by index. Same person
   on both sides is allowed (self-talk rehearsal).
-- **1×N broadcast**: pass exactly one profile on one side and N on
+- **1×N broadcast**: pass exactly one person on one side and N on
   the other to rehearse one fixed side against N variations. The CLI
   auto-broadcasts the singleton to match. E.g.
-  \`--audience-a tp-rep --audience-b tp-cto1,tp-cto2,tp-cto3\` → 3
+  \`--group-a p-rep --group-b p-cto1,p-cto2,p-cto3\` → 3
   conversations, same rep, three different CTOs. Stderr notice fires
   when broadcasting kicks in.
 - Both \`--scenario-a\` and \`--scenario-b\` are required and asymmetric.
   Use \`@./file.md\` to read from disk.
 - \`--initiator-side\` (\`a\` default) picks who speaks first.
-- \`--chat-mode\` accepts both \`tester_pair\` and \`tester-pair\`.
+- \`--chat-mode\` accepts both \`participant_pair\` and \`participant-pair\`.
   The same hyphen/underscore tolerance applies to \`--screen-format\`,
   \`--kind\` on \`source upload\`, and the question \`type\` field in
   \`--questionnaire\` / \`--questions\` manifests.
 - Audiences are **authoritative on the iteration**.
-  \`ish study run\` refuses \`--profile\` / \`--sample\` / \`--all\` /
+  \`ish study run\` refuses \`--person\` / \`--sample\` / \`--all\` /
   demographic filters on a pair iteration with a clear error. To
-  change audiences, update the iteration via
+  change groups, update the iteration via
   \`ish iteration update <id> --details-json '{...}'\`.
 - \`--max-turns\` / \`--early-termination\` on \`study run\` override the
   iteration's saved values for that single dispatch (they don't
   persist back to the iteration).
 - Dispatch is per-Conversation (one task per pair). Per-Conversation
   summaries (\`end_reason\`, \`dominant_dynamic\`, \`who_steered\`) land on
-  \`iteration.conversations[]\`. Per-tester summaries land on
-  \`tester.summary\` as before.
+  \`iteration.conversations[]\`. Per-participant summaries land on
+  \`participant.summary\` as before.
 
-### Filtering audiences with role criteria (persona-first)
+### Filtering groups with role criteria (persona-first)
 
 \`--role-criteria-a\` / \`--role-criteria-b\` accept a JSON object (or
 \`@./file.json\`) describing who's eligible for that side. The
-backend resolves the matching tester-profile pool and persists the
+backend resolves the matching person pool and persists the
 IDs on the iteration. Keys (all optional):
 
 \`\`\`json
@@ -632,8 +675,8 @@ IDs on the iteration. Keys (all optional):
 \`\`\`
 
 The five \`*_in\` arrays accept snake_case spec values verbatim
-(see \`https://ishlabs.io/spec/profile-enums.v1.json\`). The five
-accessibility filters are coarse booleans over each tester's
+(see \`https://ishlabs.io/spec/person-enums.v1.json\`). The five
+accessibility filters are coarse booleans over each participant's
 \`accessibility_profile\` JSONB.
 
 MECE rules for the list filters:
@@ -641,13 +684,13 @@ MECE rules for the list filters:
   children; \`couple_no_kids\` is strictly child-free. \`single\` means
   lives alone with no partner, roommates, parents, or children
   sharing the household.
-- \`employment_status_in\`: pick the tester's primary daytime
+- \`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\`.
 
-The **persona-first** principle: the tester's persona is sacred and
+The **persona-first** principle: the participant's persona is sacred and
 the LLM prompt construction does not change. Criteria filter the
-*eligible pool* upstream so that by the time a tester reaches the
+*eligible pool* upstream so that by the time a participant reaches the
 prompt, their persona is already plausible for the role described
 in \`scenario_*\`. Don't cram demographic constraints into the
 scenario text — that breaks the asymmetry contract and produces
@@ -658,7 +701,7 @@ pick who plays the role.
 If the resolved pool is smaller than the requested count for a side,
 \`ish study run\` exits 2 with the backend's pool-too-small error
 intact. Broaden the criteria, generate more profiles
-(\`ish profile generate\`), or fall back to explicit \`--profile-*\`.
+(\`ish person generate\`), or fall back to explicit \`--person-*\`.
 
 ### Rehearsing against N variations of one side (1×N)
 
@@ -667,11 +710,11 @@ The most common rehearsal shape: fix one side, vary the other.
 
 \`\`\`bash
 # 1. Generate N distinct profiles for the varying side (or pick
-#    existing ones via \`ish profile list\`).
-ish profile generate \\
+#    existing ones via \`ish person list\`).
+ish person generate \\
     --description "Skeptical CTO at a Series B SaaS startup" \\
     --count 3 --json | jq -r '.items[].alias'
-# → tp-cto1, tp-cto2, tp-cto3
+# → p-cto1, p-cto2, p-cto3
 
 # 2. Write the two scenarios as separate files. Each is a system
 #    prompt for ONE role; the partner never sees it. Cover voice,
@@ -682,15 +725,15 @@ ish profile generate \\
 #    ./sales_rep.md       — the user's pitch + goals
 #    ./skeptical_cto.md   — CTO's posture + concerns
 
-# 3. Create the iteration with ONE profile on the fixed side and
+# 3. Create the iteration with ONE person on the fixed side and
 #    N on the varying side. CLI auto-broadcasts the singleton and
-#    prints a stderr notice ("Broadcasting --audience-a (1 profile)
+#    prints a stderr notice ("Broadcasting --group-a (1 person)
 #    to length 3…") so you see the expansion.
 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"
@@ -705,11 +748,11 @@ ish iteration get <iter-id> --json \\
 \`\`\`
 
 The CLI emits a stderr notice when it broadcasts ("Broadcasting
---audience-a (1 profile) to length 3…") so you can see the
+--group-a (1 person) to length 3…") so you can see the
 expansion happen.
 
 **Criteria alternative**: \`--role-criteria-b '{"occupation":["cto"]}'\`
-on a single \`--audience-a tp-rep\` lets the backend pick the CTOs.
+on a single \`--group-a p-rep\` lets the backend pick the CTOs.
 Less control over distinctness — for guaranteed variety, generate
 explicit profiles first.
 
@@ -746,18 +789,18 @@ Inspect after running:
 \`\`\`bash
 ish iteration get <iter-id> --json \\
     | jq '.details.mode_details.mode, .conversations[]'
-ish study results <study-id> --transcript <tester-id> --json
+ish study results <study-id> --transcript <participant-id> --json
 \`\`\`
 
 ## 9. Stage an ask for human review, then dispatch
 
 Goal: prepare a billable A/B but let the user inspect and approve the
-audience + prompt before any credits are spent. Two-step flow with a
+people + prompt before any credits are spent. Two-step flow with a
 DRAFT status in between.
 
 \`\`\`bash
 # 1. Stage. No worker enqueued, no bill. Audience flags are still
-#    required — testers materialize at create time.
+#    required — participants materialize at create time.
 ASK=$(ish ask create --name "tagline AB" \\
         --prompt "Which sounds better?" \\
         --variant text:"Short and punchy." \\
@@ -768,7 +811,7 @@ ASK=$(ish ask create --name "tagline AB" \\
 
 # Hand the alias back to the user. They can inspect it:
 #   ish ask get "$ASK"            # status: draft
-#   ish ask get "$ASK" --json | jq '.testers | length'
+#   ish ask get "$ASK" --json | jq '.participants | length'
 
 # 2. Dispatch once approved (BILLABLE). Idempotent: a non-DRAFT ask
 #    returns 409 mapped to exit 2, so re-running is safe.
@@ -812,9 +855,9 @@ The mental rule: **\`--get\` is for capture, bare commands / \`--human\`
 are for display, \`--json\` is for chaining (multiple fields at once).**
 If you find yourself reaching for \`jq -r .x\`, you wanted \`--get x\`.
 
-## 11. Extend a tester past its step cap (or redirect mid-run)
+## 11. Extend a participant past its step cap (or redirect mid-run)
 
-Goal: a tester hit the \`--max-interactions\` cap before finishing, or
+Goal: a participant hit the \`--max-interactions\` cap before finishing, or
 veered off into the wrong flow. Resume it with more steps and an
 optional mid-run instruction — without re-running the whole cohort.
 
@@ -822,13 +865,13 @@ optional mid-run instruction — without re-running the whole cohort.
 # 1. Source run with a small cap to feel the limit:
 ish study run --sample 1 --max-interactions 5 --wait
 SRC=$(ish study run --sample 1 --max-interactions 5 --wait \\
-        --get tester_aliases | head -1)
+        --get participant_aliases | head -1)
 
 # 2. Inspect what stopped (optional, useful for the LLM to choose
 #    a redirect instruction):
-ish study tester "$SRC" --summary
+ish study participant "$SRC" --summary
 
-# 3a. Add 15 more steps, no new instruction — let the tester continue:
+# 3a. Add 15 more steps, no new instruction — let the participant continue:
 ish study extend "$SRC" --add-steps 15 --wait --timeout 600
 
 # 3b. OR redirect with a mid-run instruction (captured as user_message;
@@ -837,20 +880,20 @@ ish study extend "$SRC" \\
     --instruction "Stop browsing the blog. Open the pricing page and try to upgrade to Pro." \\
     --add-steps 10 --wait
 
-# 4. Capture the new tester alias to chain into results:
-NEW=$(ish study extend "$SRC" --add-steps 10 --get tester_alias)
-ish study tester "$NEW" --summary
+# 4. Capture the new participant alias to chain into results:
+NEW=$(ish study extend "$SRC" --add-steps 10 --get participant_alias)
+ish study participant "$NEW" --summary
 \`\`\`
 
 Rules to remember:
-- Source tester must be **terminal** (\`completed\` / \`failed\` /
+- Source participant must be **terminal** (\`completed\` / \`failed\` /
   \`cancelled\`). If it's still running, \`ish study cancel <src>\` first.
   \`cancel\` is non-destructive — every interaction, screenshot, and
   questionnaire answer survives. \`cancel\` + \`extend\` form a
   reversible stop/start pair.
-- A **new** tester id is created under the same iteration (the backend
+- A **new** participant id is created under the same iteration (the backend
   branches from the source's last interaction). The source row is left
-  untouched. Get the new id from \`.tester_id\` / \`.tester_alias\` on
+  untouched. Get the new id from \`.participant_id\` / \`.participant_alias\` on
   \`--json\`.
 - \`--add-steps\` is **only** the extra budget; it does NOT include the
   source's original cap. Credits debit per
@@ -869,54 +912,56 @@ mental model (cancel + extend as a pair, error envelopes, cost model).
 ## Tips for chaining commands as an agent
 
 - Capture aliases from JSON: \`ITER=$(ish iteration create --url … --json | jq -r .alias)\`
-- After \`ish study run --json\`, the testers you just dispatched are at
-  \`.tester_aliases[]\` (and \`.tester_ids[]\` for UUIDs). Pass these to
-  \`ish study poll/wait/cancel <tester_id>\`. The \`simulations[]\` array
+- After \`ish study run --json\`, the participants you just dispatched are at
+  \`.participant_aliases[]\` (and \`.participant_ids[]\` for UUIDs). Pass these to
+  \`ish study poll/wait/cancel <participant_id>\`. The \`simulations[]\` array
   is collapsed to one batch entry per study with nested
-  \`tester_ids[]\` / \`tester_aliases[]\` / \`job_ids[]\` so an N-sample
+  \`participant_ids[]\` / \`participant_aliases[]\` / \`job_ids[]\` so an N-sample
   batch is a single row, not N near-duplicate rows.
 - \`ish study poll\` honors the active study set by \`ish study use\` —
   pass no \`--study\` flag and it polls the active study (parity with
   \`study results\` / \`study wait\` / \`study run\`).
 - \`ish study results --json\` includes per-answer \`sentiment\` (the
-  tester's session-level sentiment label) on every \`interview_answers[]
+  participant's session-level sentiment label) on every \`interview_answers[]
   .answers[]\` row, plus \`sentiment\` + \`comment\` on every
-  \`testers[]\` row. No need to fetch \`study tester <id>\` per row.
+  \`participants[]\` row. No need to fetch \`study participant <id>\` per row.
 - \`ish study results --summary --json\` drops the interview_answers
-  payload and gives you counts + sentiment + per-tester
+  payload and gives you counts + sentiment + per-participant
   {alias, status, sentiment, comment}. The cheapest "did this run land?"
   shape.
-- \`ish study results --transcript <tester_id> --json\` is the
+- \`ish study results --transcript <participant_id> --json\` is the
   chat-modality projection — **external_chatbot mode only**. Returns
   a flat \`transcript[]\` of {role, text, turn_index, action_type?,
   option_label?, sentiment?, failure?} with a \`unique_bot_replies\`
   count (1 on a multi-turn run = the M2 loop signature). Same shape
-  as the MCP \`get_chat_transcript\` tool. For tester_pair
+  as the MCP \`get_chat_transcript\` tool. For participant_pair
   conversations, fetch \`.conversations[]\` from
-  \`ish iteration get <iter-id> --json\` instead — bot/tester roles
-  don't apply when both speakers are testers.
+  \`ish iteration get <iter-id> --json\` instead — bot/participant roles
+  don't apply when both speakers are participants.
 - \`ish study run --json\` on a pair iteration includes a
-  \`pair_preview\` block (audience sizes, conversation count,
+  \`pair_preview\` block (group sizes, conversation count,
   initiator side, scenario previews) so agents can confirm what
   they just dispatched without a follow-up \`iteration get\`.
-- \`ish study tester <id> --summary --json\` drops the action timeline
-  and returns just {tester, sentiment, comment, error_message}.
+- \`ish study participant <id> --summary --json\` drops the action timeline
+  and returns just {participant, sentiment, comment, error_message}.
 - \`ish ask results --json\` keeps \`variant_pick_id\` on every
   response without needing \`--verbose\` — it's the load-bearing field
   for "who picked what". Same logic on \`ask get\`.
-- \`ish iteration get --json\` testers carry \`alias\` + \`name\` (M12
+- \`ish iteration get --json\` participants carry \`alias\` + \`name\` (M12
   parity with \`study results --json\`).
 - Use \`--fields\` to keep JSON tight: \`ish study list --fields alias,name,status\`
 - Always pass \`--wait\` (or \`ish study wait\`) before reading
   \`ish study results\` — without it you may read partial data.
-- For \`ask\` write-paths (update/archive/wait/add-questions/add-testers),
+- For \`ask\` write-paths (update/archive/wait/add-questions/add-people),
   default JSON is compact (changed fields + alias). Pass \`--verbose\` for
   the full Ask payload.
-- For \`profile generate --json\`, \`simulation_config\` is trimmed by
-  default (~9× smaller). Pass \`--include-simulation-config\` to include it.
+- \`person generate --json\` returns \`{job: {id, status, person_ids},
+  profiles: [...]}\`; each person is the lean person shape with its
+  evidence-grounded \`scenarios\` attached (\`--no-scenarios\` to omit,
+  \`--verbose\` for the full record incl. \`simulation_config\`).
 - On \`error_code: "usage_limit_reached"\` (HTTP 403), don't retry —
   read \`tier\`, \`limit\`, \`current\`, \`max\`, and \`upgrade_url\` from
-  the JSON body to construct a recovery message. \`profile generate\` /
+  the JSON body to construct a recovery message. \`person generate\` /
   \`study generate\` refuse the entire batch when the post-generation
   count would exceed the cap; re-issue with a smaller \`--count\`.
 - Every verb's \`--help\` ends with a "Tips:" footer naming \`--get\`
@@ -925,12 +970,12 @@ mental model (cancel + extend as a pair, error envelopes, cost model).
 - \`ish study run --wait\` returns \`error_code: "wait_timeout"\`
   on wait expiry (exit 5, retryable) — distinct from network /
   server timeouts. The envelope carries \`progress\` so you can
-  resume by polling the listed testers instead of re-dispatching.
-  Same envelope on \`ish study wait\` and per-tester \`study wait\`.
+  resume by polling the listed participants instead of re-dispatching.
+  Same envelope on \`ish study wait\` and per-participant \`study wait\`.
 - \`ish study run\` accepts \`--dispatch-timeout <s>\` (default 120)
   for the per-POST budget. On dispatch failure the error envelope
   includes \`seeded_but_not_dispatched_ids[]\` /
-  \`seeded_but_not_dispatched_aliases[]\` — testers exist
+  \`seeded_but_not_dispatched_aliases[]\` — participants exist
   server-side; resume by polling them, don't re-run \`study run\`.
 - \`ish ask run --new\` is non-idempotent and marked
   \`retryable: false\` on any failure. If you do see one, run
@@ -946,20 +991,20 @@ mental model (cancel + extend as a pair, error envelopes, cost model).
 | You want to…                              | Don't                                  | Do                                                                 |
 |-------------------------------------------|----------------------------------------|--------------------------------------------------------------------|
 | Capture a single value (alias, id, …)     | \`--json \\| jq -r .alias\`             | \`--get alias\`                                                      |
-| Capture a nested value                    | \`--json \\| jq -r .tester_profile.name\` | \`--get tester_profile.name\`                                        |
+| Capture a nested value                    | \`--json \\| jq -r .person.name\` | \`--get person.name\`                                        |
 | Capture every alias from a list           | \`--json \\| jq -r '.items[].alias'\`   | \`--get alias\` (auto-descends into \`items\`, one per line)            |
 | Force human output through tee/redirect   | none, output silently became JSON      | \`--human\`                                                          |
-| Look up 2-3 specific profiles             | \`profile list --json \\| jq '.items[] \\| select(...)'\` | \`ish profile get tp-1b9 tp-fc1 tp-2fc\`                             |
+| Look up 2-3 specific profiles             | \`person list --json \\| jq '.items[] \\| select(...)'\` | \`ish person get p-1b9 p-fc1 p-2fc\`                             |
 | Show only some fields                     | \`--json \\| jq '{alias, name, country}'\` | \`--fields alias,name,country\`                                      |
-| Count testers on an ask                   | \`--json \\| jq '.testers \\| length'\`  | \`ish ask get a-… --fields alias,testers_count\`                     |
+| Count participants on an ask                   | \`--json \\| jq '.participants \\| length'\`  | \`ish ask get a-… --fields alias,participants_count\`                     |
 | Count responses on a round                | \`--json \\| jq '.rounds[0].responses \\| length'\` | \`ish ask get a-… --fields alias,rounds,responses_complete,responses_total\` |
 | Pick the A/B winner                       | \`--json \\| jq '.rounds[0].responses…'\` | \`ish ask results a-… --json\` then read \`.rounds[].aggregates.winner\` |
-| List of testers from \`study run\`        | \`--json \\| jq '.testers[].id'\`        | \`--get tester_aliases\` (or \`tester_ids\` for UUIDs)                |
-| Per-answer sentiment                      | \`--json \\| jq '...'\` per tester       | \`ish study results <id> --json\` (sentiment is on every answer row) |
+| List of participants from \`study run\`        | \`--json \\| jq '.participants[].id'\`        | \`--get participant_aliases\` (or \`participant_ids\` for UUIDs)                |
+| Per-answer sentiment                      | \`--json \\| jq '...'\` per participant       | \`ish study results <id> --json\` (sentiment is on every answer row) |
 | "Did this run land?" headline             | \`study results --json\` + jq filtering | \`ish study results <id> --summary --json\`                          |
-| Chat transcript for one tester (external_chatbot) | \`study tester --json\` + jq      | \`ish study results <id> --transcript <tester_id> --json\`           |
-| Pair-mode conversation transcripts        | \`study tester --json\` per tester       | \`ish iteration get <iter-id> --json \\| jq '.conversations[]'\`     |
-| Tester headline only (no action timeline) | \`study tester --json\` + jq            | \`ish study tester <id> --summary --json\`                           |
+| Chat transcript for one participant (external_chatbot) | \`study participant --json\` + jq      | \`ish study results <id> --transcript <participant_id> --json\`           |
+| Pair-mode conversation transcripts        | \`study participant --json\` per participant       | \`ish iteration get <iter-id> --json \\| jq '.conversations[]'\`     |
+| Participant headline only (no action timeline) | \`study participant --json\` + jq            | \`ish study participant <id> --summary --json\`                           |
 | Variant pick id on an ask response        | \`ask results --json --verbose\`        | \`ish ask results a-… --json\` (variant_pick_id is preserved)        |
 
 The bias here is intentional: \`ish\` ships shapes designed for agent
@@ -986,14 +1031,17 @@ ish <command> --help
 | \`study\`     | Persistent research artifact                    | concepts/study              |
 | \`iteration\` | One configured run of a study (URL or media)    | concepts/iteration          |
 | \`ask\`       | Lightweight reaction artifact                   | concepts/ask                |
-| \`profile\`   | Tester profiles, audience generation, and the \`suggest-scenarios\` + \`evidence add\`/\`list\` probe loop for crafting one specific persona | concepts/profile            |
-| \`source\`    | Upload sources for profile generation           | concepts/source             |
+| \`person\`    | People, people generation, and the \`suggest-scenarios\` + \`evidence add\`/\`list\` probe loop for crafting one specific persona | concepts/person             |
+| \`source\`    | Upload sources for person generation           | concepts/source             |
 | \`config\`    | Simulation configs (model, timing, retries)     | (run \`ish config --help\`)   |
-| \`chat\`      | Chat endpoint CRUD + smoke test (external_chatbot mode); pair-mode iterations created via \`iteration create --chat-mode tester_pair\` | guides/chat                 |
+| \`chat\`      | Chat endpoint CRUD + smoke test (external_chatbot mode); pair-mode iterations created via \`iteration create --chat-mode participant_pair\` | guides/chat                 |
 | \`secret\`    | Per-workspace secrets (\`{{secret:KEY}}\` resolver) | concepts/secret           |
 | \`docs\`      | Offline docs for agents                         | (run \`ish docs --help\`)     |
 | \`init\`      | Drop this skill into a Claude Code / Codex /    | (run \`ish init --help\`)     |
 |             | Cursor / Cline / Roo project                    |                             |
+| \`mcp\`       | Wire the hosted ish MCP server into local AI    | guides/mcp-add              |
+|             | clients (Cursor, VS Code, Claude Code,          |                             |
+|             | Claude Desktop, Windsurf). Idempotent.          |                             |
 | \`login\`     | Browser-based auth                              | —                           |
 | \`logout\`    | Clear saved credentials                         | —                           |
 | \`status\`    | Show active session (user, workspace,           | concepts/active-context     |
@@ -1016,8 +1064,8 @@ the right \`ish docs get-page <slug>\` to read deep context.
 
 ## Aliases
 
-Short prefixed IDs (e.g. \`s-b2c\`, \`tp-795\`, \`a-6ec\`, \`i-d4e\`,
-\`t-a17\`, \`tps-3a4\`, \`w-6ec\`, \`c-c3c\`) are accepted anywhere a UUID
+Short prefixed IDs (e.g. \`s-b2c\`, \`p-795\`, \`a-6ec\`, \`i-d4e\`,
+\`t-a17\`, \`ps-3a4\`, \`w-6ec\`, \`c-c3c\`) are accepted anywhere a UUID
 is expected. Full UUIDs always work too. See
 \`ish docs get-page reference/aliases\`.