Core objects
| Term | Definition |
|---|---|
| Workspace | The top-level container that holds your studies, asks, people, sources, and secrets, and the unit ish bills and caps against. Alias prefix w-. |
| Study | The persistent unit of research: show simulated people something, read their reactions, change it, and run again. Alias prefix s-. |
| Iteration | One configured version of a study that attaches the single artifact (a URL, a media file, or a chatbot endpoint) participants experience. Labelled A, B, C, with alias prefix i-. |
| Ask | A lighter comparison: one prompt and one or more variants of creative put in front of a fixed panel. Alias prefix a-. |
| Round | One pass of an ask’s panel over a prompt and its variants. The first round is created with the ask; later rounds reuse the same people. An ask holds up to five. |
| Variant | One candidate inside an ask round: a headline, a hero image, an ad cut. Each has a kind and a value. |
| Brand | A workspace flagged as a comparison target (type competitor). Shares the w- alias prefix; surfaced in its own brand namespace. MCP only. |
| Benchmark | A clone of a study across a set of brands so each brand runs the same study head to head. MCP only. |
People
| Term | Definition |
|---|---|
| Person | A durable persona definition: structured demographics, universal enums, and a versioned accessibility profile. Alias prefix p- on the CLI, tp- on the MCP server. |
| Participant | One instance of a person inside a single run. The same person across two runs produces two participants reading from the same profile. |
| Audience | The set of people a run dispatches: sampled from the pool, named explicitly, or generated to fit a brief. |
| Panel | The audience of an ask, fixed at creation so every round runs the same people. |
| Pool | The people available to a workspace, filtered by demographic to assemble an audience. |
| Visibility | The scope that decides who can see and use a profile: workspace, platform, or community-shared. |
| Source | Real evidence (a transcript, recording, screenshot, support email, PDF) handed to person generation to ground a persona in how someone actually reacted. |
Study definition
| Term | Definition |
|---|---|
| Modality | The kind of thing a study puts in front of people. ish supports seven: interactive, text, image, video, audio, document, chat. |
| Content type | An optional sub-type that tunes a modality (for example editorial or reference for text). Five modalities carry one; interactive and chat do not. |
| Assignment | A single task a simulated person attempts during a run. A study carries one or more, run in order. |
| Step | An ordered atomic action inside an assignment, each a name of 1 to 80 characters. |
| Questionnaire | The set of questions each simulated person answers. Lives on the study, alongside assignments. |
| Site access | How ish reaches a gated URL: public, HTTP basic auth, a session cookie, or a login form. Configured per workspace. |
| Secret | A per-workspace named value that backs a {{secret:KEY}} placeholder in chatbot endpoint config, resolved on the wire at dispatch. |
Running and reading
| Term | Definition |
|---|---|
| Run | Sending simulated people through a real surface end to end (a link, an app, a video) against the latest or a named iteration. |
| Dispatch | One request that sends a group of simulated people at once. Capped at 20 participants, independent of tier. |
| Reactions | What each simulated person reports back: what they noticed, where they got stuck, and what they would do next. |
| Reported journey | The full record a run returns per participant: transcript, signals, and the reasoning behind them, plus screenshots for interactive runs. Not a score. |
| Signals | The measured layers of a reported journey: sentiment, friction, blockers, completion. Each carries the reasoning behind it. |
| Sentiment | A per-participant label and valence, rolled up as a histogram across the panel from completed participants only. |
| Share link | A public, no-login URL to one study’s results, hosted on the web app, that anyone opens in a browser to read the run as a stakeholder would. |
Credits and limits
| Term | Definition |
|---|---|
| Credits | A usage allowance every run draws down. Paid plans refill monthly; the free tier gets a one-time grant of 200 at signup. Not money. |
| Limits | Per-tier caps on how many entities (workspaces, studies, people) an account can hold. Enforced at create time, distinct from credits. |
| Dispatch cap | The structural limit of 20 participants on every single dispatch, independent of tier and credits. Larger panels split into multiple runs. |
Surfaces and tooling
| Term | Definition |
|---|---|
| CLI | The ish command line, reading as ish <noun> <verb>. One developer surface onto the backend. |
| MCP server | The same operations exposed as tools an AI agent calls, hosted at https://mcp.ishlabs.io/mcp. The other developer surface. |
| Active context | The CLI’s saved workspace, study, and ask, kept in ~/.ish/config.json (or ISH_HOME), so you do not repeat IDs. The MCP server is stateless. |
| Alias | A short, prefixed id every object carries (w-, s-, i-, a-, p- for a person, ps- for a source) that any tool taking that object’s id accepts. |
New to ish? Start with how ish works for the mental model, then the CLI quickstart or connect an agent.