# ish — agent documentation

> ish is a CLI for running studies and asks against simulated people — they experience your draft (a landing page, ad, pitch, email, chatbot, video, or document) and report what they noticed, where they stalled, and what they would do next, before you ship. The primary user is an AI agent: every command speaks JSON, exits non-zero on failure, and resolves short aliases. For the whole corpus inlined in one file, see [llms-full.txt](llms-full.txt).

These are the same offline docs `ish docs` serves, rendered as markdown. Each link points at one page's markdown body — fetch the ones relevant to your task. Links are relative slugs (`concepts/study.md`) so they resolve offline, under `ish docs get-page`, and behind whichever host serves them. Start with the overview, then the concept for the artifact you are testing.

## Overview

- [ish — overview for agents](overview.md): Mental model, agent traversal order, where to look next.

## Concepts

- [concept: workspace](concepts/workspace.md): Top-level container; one per product.
- [concept: study](concepts/study.md): Persistent research artifact: modality, assignments, questionnaire.
- [concept: iteration](concepts/iteration.md): 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).
- [concept: assignment](concepts/assignment.md): A single task a participant performs; CLI input formats.
- [concept: questionnaire](concepts/questionnaire.md): Question types, timing, JSON manifest shape.
- [concept: ask](concepts/ask.md): Lightweight reaction artifact; rounds + variants.
- [concept: round](concepts/round.md): Unit of execution within an ask.
- [concept: person](concepts/person.md): Reusable person; generate vs manual create.
- [concept: person context](concepts/person-context.md): Real interactions (threads, transcripts, commented documents) read into episodes of beats in a person's own words; add, review, edit, approve (a real third party only by a human), leave out, use again, erase, patterns.
- [concept: source](concepts/source.md): Inputs to person generation: transcripts, audio, images, PDFs.
- [concept: people selection](concepts/people.md): People-selection flags shared by study run and ask run --new.
- [concept: site access](concepts/site-access.md): Per-site credentials for gated URLs (basic auth, cookies, login forms) and a site's hosts.
- [concept: secret](concepts/secret.md): Per-workspace KV store for {{secret:KEY}} placeholders in chatbot endpoint headers.
- [concept: run verbs — study run vs ask run](concepts/run-verbs.md): Side-by-side; decision rule for choosing one over the other.
- [concept: extending a simulation (study extend)](concepts/extending-a-simulation.md): Resume a terminal participant with more steps and an optional mid-run instruction. Cancel + extend as a reversible stop/start pair.
- [concept: active context](concepts/active-context.md): Saved workspace/study/ask state and how to inspect it (ish status).
- [concept: sharing study results](concepts/sharing.md): Public no-login share links for a study: study share / study unshare / --list, --expires, token vs URL, branding with workspace --logo.

## Reference

- [reference: aliases](reference/aliases.md): Short prefixed IDs accepted anywhere a UUID is expected.
- [reference: ish commands — the machine-readable manifest](reference/commands.md): ish commands --json: the whole command tree, flags, exit codes, alias prefixes, and first calls in one JSON object.
- [reference: error codes](reference/errors.md): Every error_code (both families), retryable class, retry_after_seconds, doc_url, and per-code remediation.
- [reference: output modes for agents (display, capture, chain)](reference/json-mode.md): Display vs capture vs chain: --human, --get, --json, --fields, exit codes, pipe behavior.
- [reference: screenshots and iteration media](reference/screenshots.md): How to list and fetch interactive-run screenshots and iteration media URLs from CLI and MCP, and the cross-origin auth boundary.
- [reference: billing tier limits](reference/billing-limits.md): Per-tier caps on workspaces/studies/iterations/people; usage_limit_reached error shape.
- [reference: credits & usage preview](reference/credits.md): Credits as a usage allowance (paid plans refill monthly; free tier is a one-time signup grant), per-modality credit draw formulas, where the CLI surfaces usage estimates (Scale line, pair_preview.credit_estimate, top-level credit_estimate), tier allotments, insufficient_credits error shape.
- [reference: pitfalls & gotchas](reference/pitfalls.md): The non-obvious traps that fail silently — output-shape quirks (study get participants at top level), local/native screenshots, idempotency (login, chat_endpoint_init, ask run --new), person list scoping, reserved secret keys, destructive-delete blast radius, and CLI conveniences that replace jq.

## Guides

- [guide: your first study, end to end](guides/first-study.md): Login → workspace → people → study → iteration → run → results.
- [guide: slicing study results by frame / segment / turn / sentiment](guides/slicing-results.md): Filter and project `ish study results` — --frame, --segment, --turn, --side, --assignment, --step, --sentiment, --actor, --iteration, --participant; --group-by iteration|frame|segment|turn|assignment|step; totals_unfiltered + empty-slice contract.
- [guide: chat-modality studies](guides/chat.md): Configure a chatbot endpoint (slots-only model), smoke test it, run a chat-modality study (external_chatbot mode). Also: participant_pair mode — two AI participants talk to each other for rehearsal scenarios.
- [guide: cold start on a saturated account](guides/cold-start.md): What to do when workspace_create returns usage_limit_reached on a saturated account. Inspect workspace_get (has_headroom / child_counts / last_activity_at), pick a reuse target, or call ish workspace create --ensure name.
- [guide: build a specific simulated person](guides/build-specific-person.md): One specific person from their real interactions: create them, mark a real third party, add context, review and approve episodes, read patterns.
- [guide: native app studies (ios / android)](guides/native-app.md): Run an interactive study against a native iOS or Android app on a local simulator/emulator: check ios/android, create a --platform ios/android iteration with --app (bundle id or .app/.apk), run --local, per-participant state reset, locale/keyboard, and where local screenshots live.
- [guide: wire ish into your AI clients (`ish mcp add`)](guides/mcp-add.md): 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.
- [guide: report a bug or send feedback (`ish feedback`)](guides/feedback.md): File a bug/feature/other report from the terminal: message via arg/@file/stdin, --type, auto-attached environment+account diagnostics and your recent CLI errors (--no-diagnostics to opt out), --health for setup checks + local-sim logs, --dry-run preview. Also: the `report` hint the CLI appends to genuine-fault errors (once per ten minutes) and the tally line after several failures.