@ishlabs/cli 0.8.1 → 0.8.2

package/dist/lib/docs.js

@@ -0,0 +1,930 @@
+/**
+ * ish docs — In-binary documentation aimed at AI coding agents.
+ *
+ * Pages ship as TypeScript string constants so they survive both the `tsc`
+ * build and the `bun build --compile` single-binary build. Slugs use
+ * forward-slashes so the surface mirrors a doc tree (`concepts/study`).
+ */
+const OVERVIEW = `# ish — overview for agents
+
+ish is a CLI for running studies and asks against AI tester audiences.
+The agent (you) is the primary user. Every command supports \`--json\`,
+exits non-zero on failure, and resolves IDs from short aliases.
+
+## Mental model
+
+\`\`\`
+Workspace (= product)
+├── Tester Profiles ────── reusable audience personas (alias: tp-…)
+│     └── Sources ──────── transcripts/audio/images that seed generation
+├── Study ──────────────── persistent research artifact (alias: s-…)
+│     ├── modality ──────── interactive | text | video | audio | image | document
+│     ├── assignments ───── tasks the tester does
+│     ├── questionnaire ─── questions the tester answers
+│     └── Iterations ────── one configured run (URL or content) (alias: i-…)
+│           └── Testers ─── instance of a Profile in this iteration (alias: t-…)
+└── Ask ────────────────── lightweight reaction artifact (alias: a-…)
+      └── Rounds ────────── unit of execution; audience fixed at ask creation
+\`\`\`
+
+Two top-level run verbs:
+- \`ish study run\`  — dispatches simulations on the latest iteration of a study.
+- \`ish ask run\`    — appends a round to an ask (or creates one with \`--new\`).
+
+## How agents should use this CLI
+
+1. Run \`ish docs list\` to see every concept and reference page available offline.
+2. Run \`ish docs get-page <slug>\` to read a specific page (e.g. \`concepts/study\`).
+3. Run \`ish docs search <query>\` for keyword lookup across all pages.
+4. Every command prints structured JSON when stdout is piped or \`--json\` is set.
+5. Aliases like \`s-b2c\`, \`a-6ec\`, \`tp-795\`, \`i-d4e\`, \`t-a17\` are accepted
+   anywhere an ID is expected. See \`ish docs get-page reference/aliases\`.
+
+## Where to look next
+
+- New here? \`ish docs get-page concepts/workspace\`, then \`concepts/study\`.
+- Running your first study? \`ish docs get-page guides/first-study\`.
+- Comparing study vs ask? \`ish docs get-page concepts/run-verbs\`.
+- Need machine-readable output? \`ish docs get-page reference/json-mode\`.
+- Auth gated URL? \`ish docs get-page concepts/site-access\`.
+
+## Install the skill into this project
+
+\`ish init\` writes a SKILL.md (https://agentskills.io spec) into your
+project so your agent loads ish context automatically:
+- Claude Code:                    \`ish init\`                  → \`.claude/skills/ish/\`
+- Codex / Cursor / Cline / Roo:   \`ish init --target agents\`  → \`.agents/skills/ish/\`
+- Both:                           \`ish init --target both\`
+`;
+const CONCEPT_WORKSPACE = `# concept: workspace
+
+A **workspace** is the top-level container — one per product. Everything
+else (studies, asks, profiles, sources, configs) belongs to exactly one
+workspace.
+
+- Alias prefix: \`w-\`
+- Created via: \`ish workspace create --name "My product"\`
+- Selected via: \`ish workspace use <id>\` — saved to \`~/.ish/config.json\`,
+  used as the default for every subsequent command.
+
+A workspace carries:
+- \`base_url\` — default origin used by site-access rules and study URLs.
+- Site-access credentials (encrypted at rest) — see \`concepts/site-access\`.
+- Tester profiles + sources visible to every study/ask in the workspace.
+
+## Common commands
+
+\`\`\`
+ish workspace list
+ish workspace create --name "My product" --base-url https://example.com
+ish workspace use w-6ec        # set as active
+ish workspace get              # show the active workspace
+ish workspace site-access status
+\`\`\`
+`;
+const CONCEPT_STUDY = `# concept: study
+
+A **study** is the persistent research artifact. It defines:
+- \`modality\`: \`interactive\` (the tester drives a real browser) or one of
+  \`text | video | audio | image | document\` (media reaction studies).
+- \`content_type\` (media studies only): \`email | social_post | ad | …\` —
+  controls the framing the tester is given.
+- \`assignments\`: the tasks the tester performs. See \`concepts/assignment\`.
+- \`questionnaire\`: the questions the tester answers. See \`concepts/questionnaire\`.
+
+A study does **not** carry the URL or media being tested — that lives on
+its iterations. Think: a study is the recipe; an iteration is one batch.
+
+- Alias prefix: \`s-\`
+- Created via: \`ish study create …\`
+- Selected via: \`ish study use <id>\` — becomes the default for run/iteration commands.
+
+## Lifecycle
+
+1. \`ish study create --name "Onboarding UX" --modality interactive --assignment "Sign up:Complete the signup flow" --question "How easy was it?"\`
+2. \`ish iteration create --url https://example.com\` (creates the first iteration)
+3. \`ish study run --sample 5 --country SE\` (dispatches simulations)
+4. \`ish study results\` or \`ish study wait\` to gather outputs.
+
+## Related
+
+- \`concepts/iteration\` — the unit of execution within a study.
+- \`concepts/assignment\` — task definition syntax.
+- \`concepts/questionnaire\` — question types and timing.
+- \`concepts/run-verbs\` — when to use \`study run\` vs \`ask run\`.
+`;
+const CONCEPT_ITERATION = `# concept: iteration
+
+An **iteration** is one configured run of a study. It carries the
+volatile bits — the URL (interactive) or the media (video/text/etc.) —
+while the study carries the persistent shape (assignments, questionnaire,
+modality).
+
+- Alias prefix: \`i-\`
+- A study has 1..N iterations. \`ish study run\` defaults to the latest.
+- Local files passed to \`--content-url\`, \`--image-urls\`, etc. are
+  uploaded automatically. \`@filepath\` reads text from a file.
+
+## Why two layers?
+
+Because you want to A/B different URLs or content variants while keeping
+the same task definitions and questionnaire. Each iteration also owns
+its own roster of testers, so you can compare audiences as well.
+
+## Common commands
+
+\`\`\`
+# Interactive — URL:
+ish iteration create --study s-b2c --url https://example.com
+
+# Interactive on mobile screen format:
+ish iteration create --url https://example.com --screen-format mobile_portrait
+
+# Text/email content from a file:
+ish iteration create --content-text @./email.html --title "Newsletter"
+
+# Video (URL or local file):
+ish iteration create --content-url ./video.mp4
+
+# Image set:
+ish iteration create --image-urls "./a.png,./b.png"
+
+# Document (PDF):
+ish iteration create --content-url ./report.pdf
+
+# Inspect:
+ish iteration list --study s-b2c
+ish iteration get i-d4e
+\`\`\`
+
+## Related
+
+- \`concepts/study\` — the parent artifact.
+- \`concepts/run-verbs\` — how \`ish study run\` selects the iteration.
+- \`concepts/audience\` — how testers are picked for a run.
+`;
+const CONCEPT_ASSIGNMENT = `# concept: assignment
+
+An **assignment** is a single task a tester performs during an
+interactive study (or considers, for media studies). A study has 1..N
+assignments and they run in order.
+
+Each assignment has:
+- \`name\` — short label shown to the tester ("Sign up").
+- \`instructions\` — what the tester is asked to do ("Complete the signup
+  flow using a personal email").
+
+## CLI input formats
+
+Three flags, mutually exclusive (pass exactly one or none):
+
+\`\`\`
+# Repeatable inline form — "<name>:<instructions>":
+ish study create --name "Onboarding" --modality interactive \\
+    --assignment "Sign up:Complete the signup flow" \\
+    --assignment "Verify:Confirm the email and log in"
+
+# JSON file:
+ish study create --name "Checkout" --modality interactive \\
+    --assignments-file ./assignments.json
+
+# Inline JSON string:
+ish study create … --assignments '[{"name":"Browse","instructions":"…"}]'
+\`\`\`
+
+\`assignments.json\` shape:
+\`\`\`json
+[
+  { "name": "Browse", "instructions": "Find a product you like" },
+  { "name": "Buy",    "instructions": "Add to cart and checkout" }
+]
+\`\`\`
+
+## Update or replace
+
+\`ish study update <id> --assignment …\` (or \`--assignments-file\`)
+replaces the full assignment list — additive editing is not supported.
+
+## Related
+
+- \`concepts/study\` — assignments are immutable to the run; questionnaire is too.
+- \`concepts/questionnaire\` — the other half of the study definition.
+`;
+const CONCEPT_QUESTIONNAIRE = `# concept: questionnaire
+
+The **questionnaire** is the list of \`interview_questions\` a tester
+answers before, during, or after their assignments. A study has 0..N
+questions, each with a type and a timing.
+
+## Question shape
+
+\`\`\`json
+{
+  "question": "How easy was checkout?",
+  "type": "slider",          // text | slider | likert | choice_single |
+                             // choice_multiple | number | …
+  "timing": "after",         // before | during | after
+  "min": 1, "max": 7, "step": 1,
+  "labels": ["Hard", "Easy"],
+  "options": ["A", "B", "C"] // only for choice_*
+}
+\`\`\`
+
+## CLI input formats
+
+Two flags, mutually exclusive:
+
+\`\`\`
+# --question is repeatable. Defaults to type=text, timing=after.
+ish study create … --question "How easy was it?" --question "Anything confusing?"
+
+# Richer types from a JSON manifest:
+ish study create … --questionnaire ./questionnaire.json
+\`\`\`
+
+\`questionnaire.json\` is an array of question objects in the shape above.
+The same shape is accepted by \`ish ask add-questions … --questions …\`.
+
+## Related
+
+- \`concepts/ask\` — asks have per-round questions, similar shape.
+- \`concepts/study\` — questionnaire is part of the persistent study definition.
+`;
+const CONCEPT_ASK = `# concept: ask
+
+An **ask** is a lightweight reaction artifact — much less ceremony than
+a study. It has an audience (fixed at creation) and a sequence of
+**rounds**. Each round shows the audience a prompt plus 1..N variants
+(text or image) and collects their reactions.
+
+- Alias prefix: \`a-\`
+- Audience is fixed at ask creation — you cannot swap audiences between
+  rounds. (You can extend it via \`ish ask add-testers\`.)
+- Up to 5 rounds per ask.
+
+## When to use ask vs study
+
+- Reach for **ask** for: tagline A/B, hero-image picks, copy comparisons,
+  quick reactions to creative variants.
+- Reach for **study** for: anything that needs a tester to *do* something
+  (interactive flow, multi-step task, time-on-page).
+
+See \`concepts/run-verbs\` for the side-by-side.
+
+## Lifecycle
+
+\`\`\`
+# One-shot: create ask + run round 1
+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
+
+# Append round 2 to the active ask:
+ish ask run --prompt "And now which?" \\
+    --variant text:"X" --variant text:"Y" --wait
+
+# Inspect:
+ish ask list
+ish ask get a-6ec --round 2
+ish ask results a-6ec
+\`\`\`
+
+## Variant syntax
+
+\`--variant <type>:<value>[::label=<label>]\`
+
+- \`text:"A"\`           — inline text
+- \`text:@./body.md\`    — text from a file
+- \`image:./hero-a.png\` — local image (auto-uploaded)
+- \`image:./a.png::label=A\` — with explicit label
+
+## Related
+
+- \`concepts/round\` — what a round is and how it executes.
+- \`concepts/audience\` — how testers are chosen at ask creation.
+- \`concepts/run-verbs\` — \`ish ask run\` vs \`ish study run\`.
+`;
+const CONCEPT_ROUND = `# concept: round
+
+A **round** is the unit of execution within an ask. Each round shows the
+ask's audience a prompt + variants and collects reactions.
+
+- Up to 5 rounds per ask.
+- Rounds are 1-indexed in user-facing flags (\`--round 2\`) but stored
+  with \`order_index\` starting at 0.
+- Each round can carry its own per-round questions in addition to
+  \`--wants-pick\` / \`--wants-ratings\`.
+
+## Common commands
+
+\`\`\`
+ish ask run --prompt … --variant …          # append a round to active ask
+ish ask add-round a-6ec --prompt … --variant …  # explicit form
+ish ask add-questions a-6ec --round 1 --questions ./qs.json
+ish ask wait a-6ec --round 2 --timeout 600
+ish ask results a-6ec --round 1
+\`\`\`
+
+## Related
+
+- \`concepts/ask\` — the parent artifact.
+- \`concepts/audience\` — fixed at ask creation; rounds reuse it.
+`;
+const CONCEPT_PROFILE = `# concept: tester profile
+
+A **tester profile** is a reusable audience persona — the simulated
+human whose behaviour drives a tester instance during a study or ask.
+
+- Alias prefix: \`tp-\`
+- Lives at the workspace level, reusable across studies and asks.
+- Distinct from a "tester" (\`t-\`) — a tester is one *instance* of a
+  profile inside one iteration.
+
+## Generation vs. manual creation
+
+\`ish profile generate\` runs the same audience-generation flow used in
+the web UI: an LLM reads your description and any uploaded sources
+(transcripts, customer records, audio, images) and returns either a
+single profile or a full audience.
+
+\`\`\`
+# 5 profiles from a written brief:
+ish profile generate \\
+    --description "Tech-savvy millennials in the US who use mobile banking" \\
+    --count 5
+
+# One profile from a transcript (auto-uploaded):
+ish profile generate --source ./interviews/sarah.txt --count 1
+
+# Audio with diarization:
+ish profile generate --description "Voices behind support tickets" \\
+    --source ./call.mp3 --diarize --count 3
+\`\`\`
+
+For explicit control over uploads (reusing one source across runs):
+
+\`\`\`
+ish source upload ./call.mp3 --diarize
+# → tps-3a4 (status: processed)
+ish profile generate --source tps-3a4 --count 4
+\`\`\`
+
+## Manual create
+
+\`\`\`
+ish profile create --file profile.json
+\`\`\`
+
+Expected JSON: \`{ "name": "...", "type": "ai", "gender": "female",
+"country": "US", "occupation": "...", "bio": "..." }\`
+
+## Related
+
+- \`concepts/source\` — the inputs to \`profile generate\`.
+- \`concepts/audience\` — how profiles get selected into a run.
+`;
+const CONCEPT_SOURCE = `# concept: source
+
+A **source** is an input to \`ish profile generate\`: a transcript,
+audio file, image, or PDF that an LLM reads to ground generated profiles
+in real customer evidence.
+
+- Alias prefix: \`tps-\`
+- Source kinds: \`text_file | audio | image\` (auto-detected from extension).
+- Audio supports speaker diarization via \`--diarize\`.
+
+## Two ways to use a source
+
+1. **Inline** — pass a local file directly to \`profile generate\`. The
+   file is uploaded and processed in-line:
+   \`\`\`
+   ish profile generate --source ./call.mp3 --diarize --count 3
+   \`\`\`
+
+2. **Upload-then-reuse** — upload once, reference the alias from many
+   \`generate\` runs:
+   \`\`\`
+   ish source upload ./call.mp3 --diarize
+   # → tps-3a4 (status: processed)
+   ish profile generate --source tps-3a4 --count 4
+   \`\`\`
+
+## Inspect
+
+\`\`\`
+ish source get tps-3a4
+\`\`\`
+
+## Related
+
+- \`concepts/profile\` — sources feed profile generation.
+`;
+const CONCEPT_AUDIENCE = `# concept: audience selection
+
+Both \`ish study run\` and \`ish ask run --new\` accept the same audience
+flags. Two ways to select:
+
+1. **Explicit profile IDs** — \`--profile tp-795,tp-af2\` (or repeated).
+2. **Demographic-filtered sample from the workspace pool** — combine any
+   of the filters with \`--sample <N>\` or \`--all\` / \`--all-simulatable\`:
+   - \`--country SE,NO\`  (repeatable)
+   - \`--gender female\`  (repeatable)
+   - \`--min-age 25\`
+   - \`--max-age 50\`
+   - \`--search "early adopter"\`
+   - \`--visibility shared|private\`
+
+The two modes are **mutually exclusive** — pass either \`--profile\` or
+the filter set, not both.
+
+## Defaults
+
+- \`ish study run\` with no audience flags → reuses the iteration's
+  existing testers. Ideal for re-running the same audience.
+- \`ish ask run\` (without \`--new\`) → cannot change audience; the ask
+  fixes it at creation. Audience flags only apply with \`--new\`.
+
+## Examples
+
+\`\`\`
+# Explicit:
+ish study run --profile tp-795,tp-af2
+
+# Sample 3 Swedish profiles aged 35-50:
+ish study run --country SE --min-age 35 --max-age 50 --sample 3
+
+# Every female profile in the workspace:
+ish study run --gender female --all
+
+# Ask + audience in one shot:
+ish ask run --new --name "SE 35-50" --prompt "Which sounds better?" \\
+    --variant text:"A" --variant text:"B" \\
+    --country SE --min-age 35 --max-age 50 --sample 10
+\`\`\`
+
+## Related
+
+- \`concepts/profile\` — generate profiles to fill the pool.
+- \`concepts/run-verbs\` — when audience flags apply.
+`;
+const CONCEPT_SITE_ACCESS = `# concept: site access
+
+For interactive studies that target a gated URL — HTTP basic auth,
+session-cookie walls (Vercel preview, Lovable, etc.), or login forms —
+configure credentials on the workspace once. Testers reuse them when a
+study points at a matching origin.
+
+Credentials are encrypted at rest. The CLI never reads them back; it
+only checks whether each method is configured.
+
+## Methods
+
+\`\`\`
+# Show what's configured:
+ish workspace site-access status
+
+# HTTP basic auth (e.g. staging gate):
+ish workspace site-access basic-auth --username alice --password hunter2
+
+# Session cookie:
+ish workspace site-access cookie --name session --value abc123
+
+# Login form (typed by the tester):
+ish workspace site-access login --username demo --password demo
+
+# Mark as public (silence the "credentials needed?" prompt):
+ish workspace site-access affirm-public
+
+# Clear:
+ish workspace site-access clear cookie
+ish workspace site-access clear all
+\`\`\`
+
+\`--origin\` defaults to the workspace \`base_url\`
+(\`ish workspace update --base-url …\`).
+
+## Keep secrets out of shell history
+
+Pass \`-\` for \`--password\` or \`--value\` to read from stdin:
+
+\`\`\`
+printf %s "$STAGING_PW" | ish workspace site-access basic-auth \\
+    --username alice --password -
+\`\`\`
+`;
+const CONCEPT_RUN_VERBS = `# concept: run verbs — \`study run\` vs \`ask run\`
+
+Both verbs dispatch simulations against an audience, but the lifecycle
+and what they target differ.
+
+## Side by side
+
+|                | \`ish study run\`                                 | \`ish ask run\`                                 |
+|----------------|--------------------------------------------------|------------------------------------------------|
+| Default        | latest iteration of the active study             | append a round to the active ask              |
+| Fresh setup    | \`ish iteration create …\` first, then run         | \`--new\` (creates ask + round 1 in one shot) |
+| Specific target| \`--iteration <id>\`                               | positional ask id (\`a-6ec\`)                 |
+| Audience       | \`--profile\` OR filters with \`--sample\`/\`--all\` — else reuse iteration's testers | only at \`--new\`; fixed for the ask afterwards |
+| Output unit    | per-tester interactions + questionnaire answers  | per-tester reactions per round                |
+
+## Decision rule
+
+- The tester needs to **do** something on a real surface
+  (URL/app/document)? → study.
+- The tester needs to **react** to one or more variants
+  (text/image) of creative? → ask.
+
+## Common commands
+
+\`\`\`
+# Study — reuse iteration testers, block until done:
+ish study run --wait
+
+# Study — fresh audience by demographic:
+ish study run --country SE --min-age 35 --sample 3
+
+# Ask — append a round:
+ish ask run --prompt "And now?" --variant text:"X" --variant text:"Y" --wait
+
+# Ask — fresh ask + round 1 in one shot:
+ish ask run --new --name "tagline AB" \\
+    --prompt "Which sounds better?" \\
+    --variant text:"A" --variant text:"B" --sample 30 --wants-pick --wait
+\`\`\`
+
+## Tracking individual testers after \`study run\`
+
+\`ish study run --json\` returns a top-level \`tester_aliases[]\` and
+\`tester_ids[]\` for the testers it just dispatched. Pass either to the
+low-level lifecycle verbs:
+
+\`\`\`
+ish study run --study s-b2c -y --json | jq -r '.tester_aliases[]'   # → t-072, t-1ed, ...
+
+ish study poll <tester_id>                # one-shot status for one tester
+ish study wait <tester_id> --timeout 600  # block until that tester finishes
+ish study cancel <tester_id>              # cancel a running simulation
+\`\`\`
+
+\`<tester_id>\` accepts a tester alias (\`t-…\`) or a full UUID. The
+study-level \`poll\`/\`wait\` forms also exist (\`--study <id>\` /
+\`--iteration <id>\`) for whole-batch progress.
+`;
+const REFERENCE_ALIASES = `# reference: aliases
+
+ish accepts short, prefixed aliases anywhere a UUID is expected. Aliases
+are derived from a deterministic hash of the entity ID and persist
+across sessions. They are written to \`~/.ish/config.json\` the first
+time the CLI sees an entity.
+
+## Prefixes
+
+- \`w-\`    workspace
+- \`s-\`    study
+- \`i-\`    iteration
+- \`t-\`    tester (instance of a profile in an iteration)
+- \`tp-\`   tester profile
+- \`tps-\`  tester-profile source
+- \`a-\`    ask
+- \`c-\`    config (simulation config)
+
+## Examples
+
+\`\`\`
+ish iteration create --study s-b2c --url https://example.com
+ish iteration get i-d4e
+ish study tester t-a17
+ish profile generate --source tps-3a4 --count 4
+\`\`\`
+
+The full UUID is also always accepted. Add \`--verbose\` to JSON output
+to see UUIDs alongside aliases.
+`;
+const REFERENCE_JSON_MODE = `# reference: JSON output for agents
+
+Every command that produces output supports machine-readable JSON. JSON
+mode is **auto-enabled when stdout is piped**, so an agent rarely needs
+\`--json\` explicitly.
+
+## Flags
+
+- \`--json\`            — force JSON output even on a TTY.
+- \`--fields a,b,c\`    — keep only these fields in JSON output (e.g.
+                          \`alias,name,status\`). Filters per item only;
+                          paginated wrappers (\`{items, total, limit,
+                          offset}\`) keep their shape.
+- \`--verbose\`          — include full UUIDs, timestamps, and (on
+                          write paths) the full server payload instead
+                          of the compact response.
+- \`-q, --quiet\`        — suppress progress messages on stderr (errors
+                          still go to stderr).
+
+## Stable shape rules
+
+The CLI guarantees these contracts so agents can chain safely:
+
+- **Lists keep their wrapper.** \`--fields\` strips per-item, never the
+  envelope. A paginated list with \`{items, total, limit, offset}\` will
+  always have those four keys.
+- **Write paths always include \`id\` AND \`alias\`.** Even with
+  \`--fields\` set, you can identify the affected resource. Default
+  write-path JSON is compact (\`{id, alias, name, updated_at,
+  ...changed_fields}\`); pass \`--verbose\` for the full server payload.
+- **\`profile generate\` trims \`simulation_config\` by default** (~9×
+  smaller than the raw response). Pass \`--include-simulation-config\`
+  if you need it.
+- **\`study run --json\` exposes tester handles.** The top-level
+  \`tester_ids[]\` and \`tester_aliases[]\` arrays are the canonical
+  inputs to \`ish study poll/wait/cancel\`.
+
+## Exit codes
+
+| Code | Meaning              |
+|------|----------------------|
+| 0    | Success              |
+| 1    | General error        |
+| 2    | Usage / validation   |
+| 3    | Auth (re-run \`ish login\`) |
+| 4    | Not found            |
+| 5    | Transient — retryable (timeout, 5xx, network) |
+
+Use these to branch in scripts; do not parse the human stderr message.
+
+## Error envelope
+
+When a command fails with \`--json\` (or piped stdout), the CLI prints
+a structured error object on **stdout** and a human message on
+**stderr**:
+
+\`\`\`json
+{
+  "error": "Validation error",
+  "error_code": "validation",
+  "status": 422,
+  "retryable": false,
+  "errors": [
+    {
+      "loc": ["body", "testers", 0, "tester_profile_id"],
+      "msg": "Input should be a valid UUID",
+      "type": "uuid_parsing",
+      "input": "tp-bogus",
+      "allowed_values": ["..."]
+    }
+  ],
+  "suggestions": ["Pass a tester profile alias (tp-...) or UUID."]
+}
+\`\`\`
+
+\`error_code\` mirrors the exit-code family
+(\`validation\`, \`auth\`, \`not_found\`, \`timeout\`, \`server\`,
+\`network\`, …). \`retryable: true\` matches exit code 5.
+
+## Conventions
+
+- Successful commands exit 0 and print one JSON object/array on stdout.
+- Lists print as JSON arrays (or paginated wrappers). Single resources
+  as JSON objects.
+- Field names match the underlying API resource (snake_case).
+- Aliases (\`s-…\`, \`a-…\`, \`tp-…\`, …) appear alongside UUIDs in
+  \`--verbose\` mode and replace UUIDs in default lean mode.
+
+## Examples
+
+\`\`\`
+ish workspace list --json | jq '.[].alias'
+ish study get s-b2c --fields alias,name,status,iterations
+ish ask results a-6ec --round 1 --json
+ish profile generate --description "..." --count 3 --json | jq '.[].alias'
+\`\`\`
+
+## Composing commands
+
+JSON mode + alias resolution makes pipelines safe:
+
+\`\`\`
+ITER=$(ish iteration create --url https://example.com --json | jq -r .alias)
+TESTERS=$(ish study run --iteration "$ITER" --sample 5 --country SE \\
+            --json | jq -r '.tester_aliases[]')
+for t in $TESTERS; do
+  ish study wait "$t" --timeout 600
+done
+ish study results --json | jq .
+\`\`\`
+`;
+const GUIDE_FIRST_STUDY = `# guide: your first study, end to end
+
+Goal: from zero to a finished interactive study with 3 testers and one
+question, produced in a single workspace.
+
+## 1. Authenticate
+
+\`\`\`
+ish login
+\`\`\`
+
+## 2. Create + select a workspace
+
+\`\`\`
+ish workspace create --name "Demo" --base-url https://example.com
+ish workspace use w-…    # use the alias printed above
+\`\`\`
+
+## 3. Generate a small audience
+
+\`\`\`
+ish profile generate \\
+    --description "Tech-savvy millennials in the US who use mobile banking" \\
+    --count 3
+\`\`\`
+
+## 4. Define the study
+
+\`\`\`
+ish study create --name "Onboarding UX" --modality interactive \\
+    --assignment "Sign up:Complete the signup flow" \\
+    --question "How easy was it?"
+ish study use s-…
+\`\`\`
+
+## 5. Configure an iteration with the URL under test
+
+\`\`\`
+ish iteration create --url https://example.com
+\`\`\`
+
+## 6. Run
+
+\`\`\`
+ish study run --all --wait
+\`\`\`
+
+## 7. Read results
+
+\`\`\`
+ish study results --json | jq .
+\`\`\`
+
+## Variations
+
+- Gated URL? \`ish docs get-page concepts/site-access\`.
+- Localhost? \`ish connect 3000\` to expose a Cloudflare tunnel, then use
+  the printed URL as \`--url\`.
+- Want a quick reaction test instead of an interactive study? Skip to
+  \`ish docs get-page concepts/ask\`.
+`;
+const PAGES = [
+    {
+        slug: "overview",
+        title: "ish — overview for agents",
+        description: "Mental model, agent traversal order, where to look next.",
+        body: OVERVIEW,
+    },
+    {
+        slug: "concepts/workspace",
+        title: "concept: workspace",
+        description: "Top-level container; one per product.",
+        body: CONCEPT_WORKSPACE,
+    },
+    {
+        slug: "concepts/study",
+        title: "concept: study",
+        description: "Persistent research artifact: modality, assignments, questionnaire.",
+        body: CONCEPT_STUDY,
+    },
+    {
+        slug: "concepts/iteration",
+        title: "concept: iteration",
+        description: "One configured run of a study (URL or media).",
+        body: CONCEPT_ITERATION,
+    },
+    {
+        slug: "concepts/assignment",
+        title: "concept: assignment",
+        description: "A single task a tester performs; CLI input formats.",
+        body: CONCEPT_ASSIGNMENT,
+    },
+    {
+        slug: "concepts/questionnaire",
+        title: "concept: questionnaire",
+        description: "Question types, timing, JSON manifest shape.",
+        body: CONCEPT_QUESTIONNAIRE,
+    },
+    {
+        slug: "concepts/ask",
+        title: "concept: ask",
+        description: "Lightweight reaction artifact; rounds + variants.",
+        body: CONCEPT_ASK,
+    },
+    {
+        slug: "concepts/round",
+        title: "concept: round",
+        description: "Unit of execution within an ask.",
+        body: CONCEPT_ROUND,
+    },
+    {
+        slug: "concepts/profile",
+        title: "concept: tester profile",
+        description: "Reusable audience persona; generate vs manual create.",
+        body: CONCEPT_PROFILE,
+    },
+    {
+        slug: "concepts/source",
+        title: "concept: source",
+        description: "Inputs to profile generation: transcripts, audio, images, PDFs.",
+        body: CONCEPT_SOURCE,
+    },
+    {
+        slug: "concepts/audience",
+        title: "concept: audience selection",
+        description: "Audience flags shared by study run and ask run --new.",
+        body: CONCEPT_AUDIENCE,
+    },
+    {
+        slug: "concepts/site-access",
+        title: "concept: site access",
+        description: "Credentials for gated URLs (basic auth, cookies, login forms).",
+        body: CONCEPT_SITE_ACCESS,
+    },
+    {
+        slug: "concepts/run-verbs",
+        title: "concept: run verbs — study run vs ask run",
+        description: "Side-by-side; decision rule for choosing one over the other.",
+        body: CONCEPT_RUN_VERBS,
+    },
+    {
+        slug: "reference/aliases",
+        title: "reference: aliases",
+        description: "Short prefixed IDs accepted anywhere a UUID is expected.",
+        body: REFERENCE_ALIASES,
+    },
+    {
+        slug: "reference/json-mode",
+        title: "reference: JSON output for agents",
+        description: "JSON, --fields, --verbose, exit codes, pipe behaviour.",
+        body: REFERENCE_JSON_MODE,
+    },
+    {
+        slug: "guides/first-study",
+        title: "guide: your first study, end to end",
+        description: "Login → workspace → audience → study → iteration → run → results.",
+        body: GUIDE_FIRST_STUDY,
+    },
+];
+const PAGES_BY_SLUG = new Map(PAGES.map((p) => [p.slug, p]));
+export function listPages() {
+    return [...PAGES];
+}
+export function getPage(slug) {
+    return PAGES_BY_SLUG.get(slug);
+}
+/** Concise pointer printed at the bottom of `--help` outputs. */
+export const AGENT_HELP_FOOTER = "\nFor agents: run `ish docs overview` for the mental model, " +
+    "`ish docs list` for every concept page, " +
+    "or `ish docs search <query>` for keyword lookup. Every command supports `--json`.\n\n" +
+    "Global flags (--json, --fields, --verbose, --quiet, --token, --api-url) apply to all subcommands. " +
+    "Run `ish --help` to see them.";
+/**
+ * Substring search over title + description + body. Title hits score
+ * highest, then description, then body. Returns at most `limit` hits
+ * sorted by score desc.
+ */
+export function searchPages(query, limit = 10) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const hits = [];
+    for (const page of PAGES) {
+        const titleHit = page.title.toLowerCase().includes(q);
+        const descHit = page.description.toLowerCase().includes(q);
+        const bodyLower = page.body.toLowerCase();
+        const bodyIdx = bodyLower.indexOf(q);
+        if (!titleHit && !descHit && bodyIdx === -1)
+            continue;
+        let score = 0;
+        if (titleHit)
+            score += 100;
+        if (descHit)
+            score += 50;
+        if (bodyIdx !== -1)
+            score += 10;
+        let snippet = page.description;
+        if (bodyIdx !== -1) {
+            const start = Math.max(0, bodyIdx - 60);
+            const end = Math.min(page.body.length, bodyIdx + q.length + 140);
+            snippet = (start > 0 ? "…" : "") +
+                page.body.slice(start, end).replace(/\s+/g, " ").trim() +
+                (end < page.body.length ? "…" : "");
+        }
+        hits.push({
+            slug: page.slug,
+            title: page.title,
+            description: page.description,
+            snippet,
+            score,
+        });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, limit);
+}