@ishlabs/cli 0.17.7 → 0.19.0

package/README.md

@@ -1,6 +1,6 @@
 # ish
 
-CLI tool for [Ish](https://ishlabs.io) — run studies, send asks, and expose your localhost for AI tester sessions.
+CLI tool for [Ish](https://ishlabs.io) — run studies, send asks, and expose your localhost for AI participant sessions.
 
 ## Install
 
@@ -49,27 +49,27 @@ Test plan is available at `/Users/felixweiland/ish-cli-test-plan.md`.
 
 ## Concepts
 
-Two top-level research primitives, both consume reusable tester profiles:
+Two top-level research primitives, both consume reusable people:
 
 ```
 Workspace (= product, top-level container)
 │
-├── Tester Profiles        ← reusable audience personas
+├── People                 ← reusable personas
 │     └── Audience Sources (images/PDFs/audio/video/text transcripts that seed generation)
 │
 ├── Study  ─────────────── "structured research artifact"
 │     ├── modality (interactive | text | video | audio | image | document)
 │     ├── content-type (for non-interactive studies: email | social_post | ad | etc.)
-│     ├── assignments (tasks the tester does)
-│     ├── questionnaire (questions testers answer — text, slider, likert, choice)
+│     ├── assignments (tasks the participant does)
+│     ├── questionnaire (questions participants answer — text, slider, likert, choice)
 │     └── Iterations       ← the unit of execution within a study
-│           └── Testers    ← instance of a Profile inside this Iteration
+│           └── Participants ← instance of a Person inside this Iteration
 │                 └── Interactions / results
 │
 └── Ask  ──────────────── "lightweight reaction artifact"
-      ├── Audience (testers, fixed at creation, max 5 rounds per ask)
+      ├── Audience (participants, fixed at creation, max 5 rounds per ask)
       └── Rounds           ← the unit of execution within an ask
-            └── Responses (per-tester reactions to a variant)
+            └── Responses (per-participant reactions to a variant)
 ```
 
 **The two primary run verbs:**
@@ -79,7 +79,7 @@ Workspace (= product, top-level container)
 | Default | Run the latest iteration on the active study | Append a round to the active ask |
 | Fresh setup | Create the iteration first: `ish iteration create …` | `--new` (creates ask + round 1 in one shot) |
 | Specific target | `--iteration <id>` | Pass the ask id as positional arg |
-| Audience | `--profile <ids>`, `--sample <N>`, `--all`, or demographic filters (`--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`) — else reuse iteration's testers | `--profile <ids>`, `--sample <N>`, `--all-simulatable`, or demographic filters (with `--new`) |
+| Audience | `--person <ids>`, `--sample <N>`, `--all`, or demographic filters (`--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`) — else reuse iteration's participants | `--person <ids>`, `--sample <N>`, `--all-simulatable`, or demographic filters (with `--new`) |
 
 ## Commands
 
@@ -95,36 +95,36 @@ ish upgrade --release 0.8.1        # pin a specific release
 
 `ish upgrade` only works on standalone-binary installs (curl/Homebrew). On npm-installed CLIs (`npm install -g @ishlabs/cli`) it refuses with a pointer to `npm install -g @ishlabs/cli@latest` — overwriting `node` would break every other Node tool.
 
-### Workspaces, studies, iterations, profiles, configs (CRUD groups)
+### Workspaces, studies, iterations, people, configs (CRUD groups)
 
 ```bash
 ish workspace  list | create | get | update | delete | use | info
 ish workspace  site-access status | basic-auth | cookie | login | affirm-public | clear
 ish study      list | create | generate | get | results | update | delete | use
 ish iteration  list | create | get | update | delete
-ish profile    list | create | generate | get | update | delete
+ish person     list | create | generate | get | update | delete
 ish source     upload | get | delete
 ish config     list | create | get | schema | update | delete
 ish chat       endpoint list | create | get | update | delete | use | init | test
 ish secret     list | set | delete
 ```
 
-`ish workspace info` reports `studies_used / studies_max / testers_used / testers_max / tier` so an agent can branch on plan caps before a destructive call returns `error_code: usage_limit_reached`.
+`ish workspace info` reports `studies_used / studies_max / participants_used / participants_max / tier` so an agent can branch on plan caps before a destructive call returns `error_code: usage_limit_reached`.
 
 `ish chat endpoint` configures HTTP-bot endpoints for chat-modality studies (auto-detect from a curl example, smoke-test, edit). `ish secret` is the per-workspace KV store referenced from chatbot endpoint headers via `{{secret:KEY}}` placeholders. Run `ish docs get-page guides/chat` for the end-to-end recipe.
 
-Testers live as a nested group on a study (low-level — usually created via `study run`):
+Participants live as a nested group on a study (low-level — usually created via `study run`):
 
 ```bash
-ish study tester <id>                              # show tester details and results
-ish study tester create | batch-create | delete    # low-level escape hatches
+ish study participant <id>                              # show participant details and results
+ish study participant create | batch-create | delete    # low-level escape hatches
 ```
 
-`use` saves an active workspace/study/ask to `~/.ish/config.json` so you don't repeat `--workspace`/`--study`/`--ask` on every command. Aliases like `w-6ec`, `s-b2c`, `a-…`, `i-…`, `t-…` work anywhere an ID is expected.
+`use` saves an active workspace/study/ask to `~/.ish/config.json` so you don't repeat `--workspace`/`--study`/`--ask` on every command. Aliases like `w-6ec`, `s-b2c`, `a-…`, `i-…`, `pt-…` work anywhere an ID is expected.
 
 ### Define a study — `ish study create`
 
-A study locks in the persistent shape: modality, optional content-type taxonomy, the tasks testers do (`--assignment`), and the questionnaire they answer (`--question` or `--questionnaire`). The actual URL or file lives on an iteration (next step).
+A study locks in the persistent shape: modality, optional content-type taxonomy, the tasks participants do (`--assignment`), and the questionnaire they answer (`--question` or `--questionnaire`). The actual URL or file lives on an iteration (next step).
 
 ```bash
 # Interactive study, one assignment + a single-question questionnaire:
@@ -178,7 +178,7 @@ ish iteration create --image-urls ./post.png \
 
 ### Configure site access — `ish workspace site-access`
 
-For studies that target a gated URL (HTTP basic auth, a session-cookie wall like Vercel preview protection, or a login form), set credentials on the workspace once. Testers reuse them whenever a study points at a matching origin. Credentials are encrypted at rest; the CLI never reads them back, only checks whether each method is configured.
+For studies that target a gated URL (HTTP basic auth, a session-cookie wall like Vercel preview protection, or a login form), set credentials on the workspace once. Participants reuse them whenever a study points at a matching origin. Credentials are encrypted at rest; the CLI never reads them back, only checks whether each method is configured.
 
 ```bash
 # Show what's configured:
@@ -190,7 +190,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 — credentials the tester types into the page:
+# Login form — credentials the participant types into the page:
 ish workspace site-access login --username demo --password demo
 
 # Mark the site as public (silences the "credentials needed?" check):
@@ -209,19 +209,19 @@ printf %s "$STAGING_PW" | ish workspace site-access basic-auth --username alice
 
 ### Run a study — `ish study run`
 
-Picks the latest iteration on the study (or `--iteration <id>`), creates testers (explicit `--profile`, demographic-filtered sample, or reusing the iteration's existing testers), and dispatches simulations. If the study has no iterations, run `ish iteration create` first.
+Picks the latest iteration on the study (or `--iteration <id>`), creates participants (explicit `--person`, demographic-filtered sample, or reusing the iteration's existing participants), and dispatches simulations. If the study has no iterations, run `ish iteration create` first.
 
 ```bash
-# Run the latest iteration, reusing its testers (after `study use`):
+# Run the latest iteration, reusing its participants (after `study use`):
 ish study run -y
 
-# Run the latest iteration with an explicit audience:
-ish study run --profile tp-795,tp-af2
+# Run with explicit people:
+ish study run --person p-795,p-af2
 
-# Sample 3 Swedish profiles aged 35–50 from the workspace pool:
+# Sample 3 Swedish people aged 35–50 from the workspace pool:
 ish study run --country SE --min-age 35 --max-age 50 --sample 3
 
-# Run with every female profile in the workspace:
+# Run with every female person in the workspace:
 ish study run --gender female --all
 
 # Run a specific iteration:
@@ -238,28 +238,28 @@ ish study run --wait --timeout 600
 ish study run --local --headed --slow-mo 500
 ```
 
-**Audience flags** (shared with `ish ask`): `--profile <ids>` for explicit IDs, or any of `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility` paired with `--sample <N>` or `--all` to seed from the workspace pool. Mutually exclusive with `--profile`.
+**Audience flags** (shared with `ish ask`): `--person <ids>` for explicit IDs, or any of `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility` paired with `--sample <N>` or `--all` to seed from the workspace pool. Mutually exclusive with `--person`.
 
 **Other study verbs (low-level):**
 
 ```bash
 ish study poll --study <id>                                      # one-shot progress
-ish study poll <tester_id>                                       # single tester status
+ish study poll <participant_id>                                  # single participant status
 ish study wait --study <id>                                      # block until all done
 ish study wait --iteration <id>                                  # block on one iteration
-ish study wait <tester_id> --timeout 600                         # block on one tester
-ish study cancel <tester_id>                                     # cancel a running sim
+ish study wait <participant_id> --timeout 600                    # block on one participant
+ish study cancel <participant_id>                                # cancel a running sim
 ```
 
-`<tester_id>` is a tester alias (`t-...`) or UUID. Get them from `ish study run --json`'s `tester_aliases[]` / `tester_ids[]` arrays:
+`<participant_id>` is a participant alias (`pt-...`) or UUID. Get them from `ish study run --json`'s `participant_aliases[]` / `participant_ids[]` arrays:
 
 ```bash
-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, ...
 ```
 
 ### Run an ask — `ish ask run`
 
-Smart wrapper around the ask flow. With `--new`, creates a fresh ask + round 1 (audience from `--profile`, `--sample`, `--all-simulatable`, or any demographic filter — `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`). Without `--new`, appends a new round to the active or specified ask.
+Smart wrapper around the ask flow. With `--new`, creates a fresh ask + round 1 (people from `--person`, `--sample`, `--all-simulatable`, or any demographic filter — `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`). Without `--new`, appends a new round to the active or specified ask.
 
 ```bash
 # Append a round to the active ask:
@@ -270,25 +270,25 @@ ish ask run --prompt "And now which?" \
 ish ask run a-6ec --prompt "Round 2" \
     --variant text:"A" --variant text:"B"
 
-# Create a fresh ask with round 1, sample 30 profiles, wait for results:
+# Create a fresh ask with round 1, sample 30 people, wait for results:
 ish ask run --new --name "tagline AB" \
     --prompt "Which sounds better?" \
     --variant text:"Short and punchy." \
     --variant text:"A longer, descriptive line." \
     --sample 30 --wants-pick --wait
 
-# Demographic-filtered sample (Swedish profiles aged 35–50):
+# Demographic-filtered sample (Swedish people aged 35–50):
 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 --wants-pick
 
-# Image comparison from local files (auto-uploaded), explicit profiles:
+# Image comparison from local files (auto-uploaded), explicit people:
 ish ask run --new --name "hero shots" \
     --prompt "Which feels premium?" \
     --variant image:./hero-a.png::label=A \
     --variant image:./hero-b.png::label=B \
-    --profile tp-d4e,tp-a17 --wants-ratings
+    --person p-d4e,p-a17 --wants-ratings
 
 # Text from a markdown file + JSON questionnaire:
 ish ask run --new --name "newsletter" \
@@ -306,15 +306,15 @@ ish ask run --new --name "newsletter" \
 ]
 ```
 
-**Audience flags** (`--profile`, `--sample`, `--all-simulatable`, `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`, `--name`, `--description`, `--workspace`) only apply with `--new` — the audience is fixed at ask creation.
+**People flags** (`--person`, `--sample`, `--all-simulatable`, `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`, `--name`, `--description`, `--workspace`) only apply with `--new` — the people are fixed at ask creation.
 
 **`--visibility` values** (same set everywhere it's accepted):
 
 | Value | Selects |
 |---|---|
-| `workspace` | Profiles owned by your workspace (default scope). |
-| `shared` | Community-published profiles visible across workspaces. |
-| `platform` | Admin-curated profiles from the platform pool. |
+| `workspace` | People owned by your workspace (default scope). |
+| `shared` | Community-published people visible across workspaces. |
+| `platform` | Admin-curated people from the platform pool. |
 
 Old values `private` (now `workspace`) and `public` (now `platform`) keep working until the next release; the server logs a deprecation warning and maps them to the new vocabulary.
 
@@ -327,26 +327,26 @@ ish ask results [id] [--round <n>]
 ish ask wait [id] [--round <n>] [--timeout <s>]
 ish ask add-round [id] --prompt … --variant …       # explicit form of `run`
 ish ask add-questions [id] --round <n> --questions ./qs.json
-ish ask add-testers [id] --profile …                # extend audience for one round
+ish ask add-people [id] --person …                   # extend people for one round
 ish ask create …                                    # explicit form of `run --new`
 ish ask update | archive | unarchive | delete | use
 ```
 
-### Generate tester profiles
+### Generate people
 
-`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 interviews, screenshots) and returns either a single profile or a full audience.
+`ish person generate` runs the same generation flow used in the web UI: an LLM reads your description and any uploaded sources (transcripts, customer records, audio interviews, screenshots) and returns either a single person or a group of people.
 
 ```bash
-# 5 profiles from a written brief:
-ish profile generate \
+# 5 people from a written brief:
+ish person generate \
   --description "Tech-savvy millennials in the US who use mobile banking" \
   --count 5
 
-# One profile from a transcript — the file is uploaded automatically:
-ish profile generate --source ./interviews/sarah.txt --count 1
+# One person from a transcript — the file is uploaded automatically:
+ish person generate --source ./interviews/sarah.txt --count 1
 
 # Audio call with a written brief, diarized:
-ish profile generate \
+ish person generate \
   --description "Voices behind support tickets" \
   --source ./call.mp3 --diarize --count 3
 ```
@@ -355,12 +355,12 @@ For explicit control over uploads — e.g. reusing the same source across multip
 
 ```bash
 ish source upload ./call.mp3 --diarize
-# → tps-3a4 (status: processed)
+# → ps-3a4 (status: processed)
 
-ish profile generate --source tps-3a4 --propose-count
+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
 ```
 
 ### Chat-modality studies — `ish chat`
@@ -387,10 +387,10 @@ ish chat endpoint test ep-abc -m "Hello"
 ish chat endpoint test ep-abc -m "Tell me more" --conversation-id "$CID"   # stateful threading
 
 # Run a chat-modality study using the saved endpoint (existing study verbs).
-# Audience size lives on study run via --sample / --all / --profile.
+# Audience size lives on study run via --sample / --all / --person.
 ish study create --modality chat --endpoint ep-abc --name "Sign-up Q1" --assignment "Sign up:Try to sign up"
 ish study run --study stu-xyz --sample 5 --wait
-ish study results stu-xyz --json | jq '.testers'
+ish study results stu-xyz --json | jq '.participants'
 ```
 
 Local bots (`localhost` / `127.0.0.1` / `0.0.0.0`) auto-flag `is_tunnel_backed=true` on `init`; pair with `ish connect <port>` in another shell. Override with `--tunnel-backed` / `--no-tunnel-backed`.
@@ -413,7 +413,7 @@ ish disconnect --json                     # graceful shutdown of an active tunne
 ISH_TOKEN=YOUR_TOKEN ish connect 8080
 ```
 
-Foreground `connect` is long-running — keep it open while testers run. The tunnel URL prints prominently after "Connected"; pass `--json` for one-line machine-readable output (`{"status":"connected","tunnel_url":"...","local_port":3000,"registered":true}`). The `--detach` form forks after the first successful heartbeat and returns immediately, tracking PID + URL in `~/.ish/connect.lock` so `connect status` and `disconnect` find it later.
+Foreground `connect` is long-running — keep it open while participants run. The tunnel URL prints prominently after "Connected"; pass `--json` for one-line machine-readable output (`{"status":"connected","tunnel_url":"...","local_port":3000,"registered":true}`). The `--detach` form forks after the first successful heartbeat and returns immediately, tracking PID + URL in `~/.ish/connect.lock` so `connect status` and `disconnect` find it later.
 
 Destructive verbs in `--json` mode (e.g. `chat endpoint delete`, `study delete`) require an explicit `--yes`; the rejection envelope carries `error_kind: "ConfirmationRequired"` and an `example` field with the same command + `--yes` appended, so an agent can recover without re-reading the help text.
 

package/dist/commands/ask.d.ts

@@ -2,16 +2,16 @@
  * ish ask — Create and run asks (multi-round surveys with variants).
  */
 import type { Command } from "commander";
-import type { AudienceSubset } from "../lib/types.js";
+import type { ParticipantSubset } from "../lib/types.js";
 /**
  * Parse the `--subset-round <n> --subset-variant <variant_id>` pair into
- * an `AudienceSubset` payload (Pattern B). Both flags must be passed
+ * an `ParticipantSubset` payload (Pattern B). Both flags must be passed
  * together or neither — half a subset is a misconfiguration the agent
  * should fix before dispatch, not a silent fallthrough to the full
- * audience.
+ * participant list.
  *
  * Returns `undefined` when neither flag is set; throws when only one is
  * set or when `--subset-round` isn't a positive integer.
  */
-export declare function parseAudienceSubset(subsetRound: string | undefined, subsetVariant: string | undefined): AudienceSubset | undefined;
+export declare function parseParticipantSubset(subsetRound: string | undefined, subsetVariant: string | undefined): ParticipantSubset | undefined;
 export declare function registerAskCommands(program: Command): void;