@ishlabs/cli 0.20.0 → 0.22.0

package/dist/lib/docs.js

@@ -315,6 +315,8 @@ pick was wrong.
 - \`concepts/assignment\` — task definition syntax.
 - \`concepts/questionnaire\` — question types and timing.
 - \`concepts/run-verbs\` — when to use \`study run\` vs \`ask run\`.
+- \`guides/slicing-results\` — filter / project \`study results\` by frame,
+  segment, turn, sentiment, assignment, step.
 - \`reference/billing-limits\` — \`maxStudiesPerProduct\` cap on study creation.
 - \`reference/credits\` — per-run credit cost & how to preview before dispatch.
 `;
@@ -633,7 +635,7 @@ Tunables (both modes):
   the parties signal the conversation is over.
 
 Pair-mode rules:
-- Each side needs **either** \`--profile-*\` (explicit IDs) **or**
+- Each side needs **either** \`--group-a\` / \`--group-b\` (explicit IDs) **or**
   \`--role-criteria-*\` (filter the backend resolves). The two can also
   be combined — criteria then acts as validation on the explicit list.
 - When both sides use explicit \`--group-a\` / \`--group-b\`, they
@@ -655,7 +657,7 @@ Pair-mode rules:
   \`type\` field in \`--questionnaire\` / \`--questions\` manifests
   (\`single-choice\` ↔ \`single_choice\`).
 - Audiences are pinned to the iteration. \`ish study run\` refuses
-  run-time people overrides (\`--profile\` / \`--sample\` / \`--all\` /
+  run-time people overrides (\`--person\` / \`--sample\` / \`--all\` /
   filters) on a pair iteration — change the peoples via
   \`ish iteration update <id> --details-json '{...}'\` instead.
 - \`--max-turns\` / \`--early-termination\` on \`ish study run\` override
@@ -851,6 +853,9 @@ ride along when present in the JSON forms.
 
 - \`concepts/study\` — assignments are immutable to the run; questionnaire is too.
 - \`concepts/questionnaire\` — the other half of the study definition.
+- \`guides/slicing-results\` — slice the post-run envelope by step
+  (\`--step verify-email --group-by step\`), surface per-participant verdicts
+  inline, or restrict to the evidence interactions with \`--include-evidence\`.
 - \`reference/json-mode\` — how \`step_completion\` renders in lean vs --verbose.
 `;
 const CONCEPT_QUESTIONNAIRE = `# concept: questionnaire
@@ -1127,7 +1132,7 @@ deleted ask was the active one.
 - \`concepts/round\` — what a round is and how it executes.
 - \`concepts/people\` — how participants are chosen at ask creation.
 - \`concepts/run-verbs\` — \`ish ask run\` vs \`ish study run\`.
-- \`reference/credits\` — ask rounds bill \`n_participants * (1 + len(questions))\` credits per round; \`questions\` follow-ups bill *per participant* on top of the base response, so a 3-person panel with 2 follow-up questions costs \`3 * (1 + 2) = 9\` credits when all complete (not 3).
+- \`reference/credits\` — ask rounds bill **one credit per successful participant per round**, regardless of how many \`questions\` were included. The backend's asks worker bills \`amount=succeeded\` once per round dispatch; questions and round-summary synthesis don't trigger separate debits. A 3-person panel with 2 follow-up questions costs \`3\` credits when all complete, the same as a no-questions run. Failed participant responses (pre-flight errors, refusals) don't bill.
 `;
 const CONCEPT_ROUND = `# concept: round
 
@@ -1169,7 +1174,7 @@ const CONCEPT_PROFILE = `# concept: person
 A **person** is a reusable persona — the simulated
 human whose behaviour drives a participant instance during a study or ask.
 
-- Alias prefix: \`tp-\`
+- Alias prefix: \`p-\`
 - Lives at the workspace level, reusable across studies and asks.
 - Distinct from a "participant" (\`pt-\`) — a participant is one *instance* of a
   profile inside one iteration.
@@ -1331,7 +1336,7 @@ A **source** is an input to \`ish person generate\`: a transcript,
 audio file, image, or PDF that an LLM reads to ground generated profiles
 in real customer evidence.
 
-- Alias prefix: \`tps-\`
+- Alias prefix: \`ps-\`
 - Source kinds: \`text_file | audio | image\` (auto-detected from extension; \`text-file\` is accepted as a hyphen variant).
 - Audio supports speaker diarization via \`--diarize\`.
 
@@ -1401,7 +1406,7 @@ flags. Two ways to select:
      \`platform\` until the next release with a server-side
      deprecation warning)
 
-The two modes are **mutually exclusive** — pass either \`--profile\` or
+The two modes are **mutually exclusive** — pass either \`--person\` or
 the filter set, not both.
 
 ## Empty-pool suggestions
@@ -1653,7 +1658,7 @@ and what they target differ.
 | 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 participants | only at \`--new\`; fixed for the ask afterwards |
+| Audience       | \`--person\` OR filters with \`--sample\`/\`--all\` — else reuse iteration's participants | only at \`--new\`; fixed for the ask afterwards |
 | Output unit    | per-participant interactions + questionnaire answers  | per-participant reactions per round                |
 
 ## Decision rule
@@ -1741,7 +1746,7 @@ When extend is **not** the right verb:
 - Source participant is still RUNNING. \`cancel\` it first, then extend.
   Extend refuses non-terminal sources server-side.
 - You want a fresh cohort with new people flags. Use \`study run\`
-  with \`--profile\` / \`--sample\` / \`--all\` instead — extend is a
+  with \`--person\` / \`--sample\` / \`--all\` instead — extend is a
   per-participant resume, not a batch op.
 - You want to change the iteration's URL or content. Edit the iteration
   itself (\`iteration update\` or a fresh iteration) — extend always
@@ -1901,8 +1906,8 @@ time the CLI sees an entity.
 - \`s-\`    study
 - \`i-\`    iteration
 - \`pt-\`   participant (instance of a person in an iteration)
-- \`tp-\`   person
-- \`tps-\`  person source
+- \`p-\`    person
+- \`ps-\`   person source
 - \`a-\`    ask
 - \`r-\`    ask round
 - \`c-\`    config (simulation config)
@@ -2418,7 +2423,7 @@ not branch on \`status: 0\` — that value is never emitted as of 0.20.
 - 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
+- Aliases (\`s-…\`, \`a-…\`, \`p-…\`, …) appear alongside UUIDs in
   \`--verbose\` mode and replace UUIDs in default lean mode.
 
 ## Examples
@@ -2461,6 +2466,210 @@ ish study results --human
 When you genuinely need multiple fields in one parse pass, \`--json\` is
 still the right tool — \`--get\` is for single-value capture, not for
 reshaping output.
+
+## Slicing study results
+
+\`ish study results <id>\` accepts filter flags (\`--frame\`, \`--segment\`,
+\`--turn\`, \`--side\`, \`--assignment\`, \`--step\`, \`--sentiment\`,
+\`--actor\`, \`--iteration\`, \`--participant\`) and projection flags
+(\`--group-by iteration|frame|segment|turn|assignment|step\`). When any
+filter is passed on the default \`study results\` envelope, the envelope
+gains a \`totals_unfiltered\` field (\`{participant_count,
+interaction_count}\`) so an agent can sanity-check coverage: "matched
+12 / 80 participants". A zero-match filter returns the stable envelope
+with \`participant_count: 0\` and exit code **0** (not 4) — slicing
+never errors on no-match. \`--group-by\` returns a different shape — a
+uniform envelope \`{axis, rows, totals_unfiltered, modality_warnings,
+study_id, modality}\` (see \`guides/slicing-results\`).
+
+\`--group-by\` is **router-gated by modality**: \`frame\` requires
+interactive, \`segment\` requires media (video / audio / text / document),
+\`turn\` requires chat. Mismatched filter flags (e.g. \`--segment 0\` on
+an interactive study) emit a stderr warning and are ignored — they
+don't error. Full worked examples in \`guides/slicing-results\`.
+`;
+const GUIDE_SLICING_RESULTS = `# guide: slicing study results
+
+\`ish study results <id>\` returns a kitchen-sink envelope by default
+(every participant, every interaction, every interview answer). For
+narrower questions — *"what differed on the login screen across these
+five iterations?"*, *"who failed verify-email, and why?"*, *"frustrated
+reactions to segment 3 of the video"* — \`ish study results\` accepts
+**filter flags** (which interactions to keep) and **projection flags**
+(how to roll up what survives). Filters compose with AND across flags
+and OR within \`--sentiment\`. Filters and projections are pure
+client-side; no extra round trip beyond the standard study fetch.
+
+## Filter flags
+
+| Flag                          | Matches                                                                                       | Where it applies                                                |
+|-------------------------------|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------|
+| \`--frame <ref>\`             | Interactions whose Frame name contains \`<ref>\` (case-insensitive). Also accepts a full Frame UUID, an \`f-…\` alias, or a \`frame_version_id\` UUID. | interactive — warn + ignore on chat / media                      |
+| \`--segment <ref>\`           | Integer matches \`actions[0].data.segment_index\`; non-integer is a substring match against \`segment_label\`. | video, audio, text, document — warn + ignore elsewhere           |
+| \`--turn <n>\`                | Interactions whose \`actions[0].data.turn_index == n\`.                                       | chat (external_chatbot + participant_pair)                       |
+| \`--side <a\|b>\`             | Interactions whose parent assignment has \`side == a\` or \`side == b\`.                       | chat participant_pair — warn + ignore on other chat / non-chat   |
+| \`--assignment <ref>\`        | Assignment UUID, or substring match against the assignment name.                              | all                                                              |
+| \`--step <ref>\`              | Filters \`participant_assignments[].step_results[]\` to verdicts matching the step id or name. | interactive + external_chatbot chat (steps live there)           |
+| \`--sentiment <labels>\`      | Comma-separated, case-insensitive label list (repeatable). Drops null-sentiment rows.         | all                                                              |
+| \`--actor <ai\|human\|user>\` | Restrict by actor.                                                                            | all                                                              |
+| \`--iteration <ref>\`         | Iteration UUID, iteration alias (\`i-…\`), or label (\`A\`, \`B\`, … case-insensitive).        | all                                                              |
+| \`--participant <ref>\`       | Participant UUID or \`pt-…\` alias.                                                            | all                                                              |
+| \`--include-unmatched\`       | With \`--frame\`, keep degraded captures (\`frame_version_id: null\`) under a synthetic \`_unmatched\` bucket instead of dropping them. | interactive                                                      |
+| \`--include-evidence\`        | With \`--step\`, also drop interactions not listed in any surviving \`step_results[].evidence_interaction_ids[]\`. | interactive + external_chatbot chat                              |
+
+**Modality mismatch is not an error.** Pass \`--segment 0\` on an
+interactive study and the filter is ignored with a stderr warning.
+The exception is \`--group-by\` — see below.
+
+## Projection flags (--group-by)
+
+Every \`--group-by\` axis returns the same envelope:
+\`{axis, rows, totals_unfiltered, modality_warnings, study_id, modality}\`.
+Top-level \`axis\` echoes the requested axis; \`study_id\` is the \`s-…\`
+alias; \`modality\` echoes the study's modality. \`rows\` is an
+axis-specific array of slice objects (see the table below for the per-row
+shape). \`modality_warnings\` carries any filter-flag mismatches
+(e.g. \`--turn\` on a non-chat study); empty array when none.
+
+| Axis        | Row shape (one element of \`rows[]\`)                                                                                                                                       | Modality |
+|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+| \`iteration\` | \`{iteration_id, iteration_label, participant_count, interaction_count, sentiment, sample_comments, top_actions}\`                                                       | all      |
+| \`frame\`   | \`{frame_id, frame_label, interaction_count, sentiment_histogram, sample_comments, participant_aliases}\`                                                                   | interactive (router errors on non-interactive) |
+| \`segment\` | \`{segment_index, segment_label, interaction_count, sentiment_histogram, engagement_histogram, sample_comments}\`                                                           | media (router errors on non-media)             |
+| \`turn\`    | \`{turn_index, interaction_count, sentiment_histogram, sample_replies, failures}\`                                                                                          | chat (router errors on non-chat)               |
+| \`assignment\` | \`{assignment_id, assignment_name, interaction_count, sentiment_histogram, step_completion}\`                                                                             | all      |
+| \`step\`    | \`{assignment_id, assignment_name, step_id, step_name, total, passed, inconclusive, failed, rate, participant_verdicts: [{participant_alias, verdict, reason, evidence_interaction_ids}]}\` | interactive + external_chatbot chat            |
+
+\`--group-by\` is **mutually exclusive with \`--summary\` and
+\`--transcript\`**. \`--group-by frame\` on a chat study, \`--group-by
+turn\` on a video study, etc. error at the surface (exit 2) with a
+clear message before any IO. The error envelope includes a \`hint\`
+field naming the axis that DOES apply to the study's modality
+(\`use --group-by segment\` on audio/video/text/document, \`use --group-by
+turn\` on chat, \`use --group-by frame\` on interactive) — agents can
+branch on it to retry productively in one hop.
+
+## The empty-slice contract
+
+A filter combination that matches zero interactions returns the
+**uniform envelope** with:
+
+- \`rows: []\`
+- \`totals_unfiltered: {participant_count: <N>, interaction_count: <M>}\` populated
+- \`axis\`, \`study_id\`, \`modality\` still populated
+- exit code **0** (not 4)
+
+\`totals_unfiltered\` is the agent's sanity check: *"my filter matched
+0 of 80 participants — is the filter too tight, or did the run not
+produce data?"*. The shape never collapses to \`null\` or a different
+envelope; \`--get participant_count\` is always safe on the default
+(non-\`--group-by\`) envelope.
+
+The default+filter envelope (no \`--group-by\`) also carries
+\`modality_warnings: string[]\` — any filter flags that were dropped as
+off-modality (e.g. \`--turn 1\` on an interactive study) appear here.
+Agents piping stderr to \`/dev/null\` get the same signal on stdout.
+
+## Worked examples
+
+\`\`\`bash
+# What differed on the login screen across the five iterations?
+ish study results s-b2c --frame login --group-by iteration
+
+# Frustrated reactions to segment 3 of the video
+ish study results s-b2c --segment 3 --sentiment Frustrated
+
+# Who failed the "verify email" step, and why?
+ish study results s-b2c --assignment "Sign up" --step verify-email --group-by step
+
+# Chat participant_pair: only side A turn 4
+ish study results s-b2c --side a --turn 4
+
+# Surface degraded captures (frame_version_id: null) under a "_unmatched" bucket:
+ish study results s-b2c --frame login --include-unmatched --group-by frame
+
+# Narrow the lean summary to a slice:
+ish study results s-b2c --summary --frame checkout --json
+\`\`\`
+
+## Combining filters
+
+Filters compose with **AND across flags** and **OR within
+\`--sentiment\`**. \`--frame login --sentiment Frustrated,Confused\`
+means "interactions on the login frame whose sentiment is Frustrated
+OR Confused". \`--summary\` is orthogonal to filters and narrows the
+summary over the filtered set. \`--transcript\` is single-participant
+and **errors when any filter or \`--group-by\` is set** (exit 2).
+
+## Defensive handling of nullable fields
+
+- \`interaction.sentiment\` is nullable (chat failure stubs,
+  pre-sentiment rows). Dropped **only** when \`--sentiment\` is set; kept
+  by every other filter.
+- \`interaction.frame_version_id\` is nullable on interactive studies
+  (degraded captures, ~12% on a failing iteration). Dropped by
+  \`--frame\` unless \`--include-unmatched\` is passed; surfaced as a
+  \`_unmatched\` bucket in \`--group-by frame\`.
+- Chat \`bot_reply.failure\` rows are kept in the default envelope,
+  dropped by \`--sentiment\` (they have \`sentiment: null\`), kept by
+  \`--actor\`, visible in \`--group-by turn\` under a \`failures\`
+  counter.
+
+## --frame resolution
+
+\`--frame login\` walks the frame list returned by
+\`GET /studies/{id}/frames\` and matches **case-insensitive substring**
+against the frame name. Other accepted shapes:
+
+- \`--frame 6ec…\` — full Frame UUID (exact match)
+- \`--frame f-6ec\` — short alias resolved via \`alias-store\`
+- \`--frame 7ec…\` — a \`frame_version_id\` UUID (matches only that version)
+
+Ambiguous substring (matches >1 frame) errors with the candidate list:
+
+\`\`\`
+ish study results s-b2c --frame log
+# Error: --frame "log" is ambiguous — matched 2 frames: Login, Logout.
+# Use a more specific substring, a full Frame UUID, or an \`f-…\` alias.
+\`\`\`
+
+No match at all errors and lists the available frame names.
+
+## Common --get paths on a sliced envelope
+
+\`\`\`
+# Sanity-check coverage:
+--get axis
+--get study_id
+--get modality
+--get totals_unfiltered.participant_count
+--get totals_unfiltered.interaction_count
+--get modality_warnings
+
+# Per-iteration projection rows:
+--get rows.iteration_label               # one label per line
+--get rows.0.participant_count
+--get rows.0.sentiment
+
+# Per-frame / per-segment / per-turn (rows[] is the axis array):
+--get rows.0.frame_label
+--get rows.0.segment_index
+--get rows.0.sentiment_histogram
+
+# Per-step:
+--get rows.0.rate
+--get rows.0.participant_verdicts.verdict
+\`\`\`
+
+## Related
+
+- \`concepts/study\` — the parent artifact whose results are being sliced.
+- \`concepts/assignment\` — defines the steps that \`--step\` and
+  \`--group-by step\` filter against.
+- \`reference/json-mode\` — display vs capture vs chain output rules
+  (\`--get\`, \`--fields\`, exit codes).
+- \`reference/aliases\` — \`s-…\` for studies, \`pt-…\` for participants,
+  \`f-…\` for frames. Any UUID-accepting flag also accepts the alias.
 `;
 const GUIDE_FIRST_STUDY = `# guide: your first study, end to end
 
@@ -2830,6 +3039,8 @@ free credits before re-dispatch.
   estimate at preview time — the CLI prints the shape (\`N × … × 2\`)
   instead of a number.
 
+**Naming note:** "tier" in ish means **billing** tier (FREE / STARTER / PRO / ENTERPRISE — a credit-budget knob). It is NOT a simulation-quality dial. Per-run simulation behaviour (model, timing, retries) is controlled via \`ish config\` — see \`ish config --help\`. \`docs search tier\` returns billing results by design.
+
 ## Related
 
 - \`reference/billing-limits\` — per-tier *entity* caps (max
@@ -3264,13 +3475,13 @@ Optional \`--max-turns <n>\` (default 12) caps the chat per participant.
 
 Audience size is set at run time for **external_chatbot** chat
 studies. Use \`--sample <N>\` to pick N random simulatable profiles,
-or \`--all\` for the full pool. \`--profile <id>\` is also supported
+or \`--all\` for the full pool. \`--person <ids>\` is also supported
 for explicit selection:
 \`\`\`
 ish study run stu-xyz --sample 5 --wait
 \`\`\`
 
-> **Pair-mode is different.** \`--sample\` / \`--profile\` / demographic
+> **Pair-mode is different.** \`--sample\` / \`--person\` / demographic
 > filters on \`study run\` are **refused** for participant_pair iterations
 > — pair groups live on the iteration itself. Set them at
 > iteration-create time via \`--group-a/-b\` (with 1×N broadcast)
@@ -3426,7 +3637,7 @@ Keys (all optional): \`occupation\`, \`min_age\`, \`max_age\`,
 \`requires_captions\`, \`uses_screen_reader\`, \`prefers_reduced_motion\`,
 \`prefers_high_contrast\`, \`has_any_accessibility_need\`. The five \`*_in\`
 arrays accept snake_case spec values; the five accessibility filters are
-booleans. Combine \`--profile-*\` and \`--role-criteria-*\` on the same side
+booleans. Combine \`--group-a\` / \`--group-b\` and \`--role-criteria-*\` on the same side
 to make criteria validate an explicit list (mismatch blocks the run).
 
 MECE notes for the list filters:
@@ -3812,7 +4023,7 @@ cap at 40 entries.
 - \`concepts/person\` — what a person is; structured fields.
 - \`concepts/source\` — interview transcripts / audio / PDF inputs
   for the people-generation flow.
-- \`reference/aliases\` — \`tp-…\` is the profile alias prefix.
+- \`reference/aliases\` — \`p-…\` is the person alias prefix.
 `;
 const GUIDE_MCP_ADD = `# guide: wire ish into your AI clients (\`ish mcp add\`)
 
@@ -4053,6 +4264,12 @@ const PAGES = [
         description: "Login → workspace → people → study → iteration → run → results.",
         body: GUIDE_FIRST_STUDY,
     },
+    {
+        slug: "guides/slicing-results",
+        title: "guide: slicing study results by frame / segment / turn / sentiment",
+        description: "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.",
+        body: GUIDE_SLICING_RESULTS,
+    },
     {
         slug: "guides/chat",
         title: "guide: chat-modality studies",

package/dist/lib/output.d.ts

@@ -35,10 +35,16 @@ export declare function outputList(rows: unknown[], json: boolean): void;
 /**
  * Error with valid options — used for content_type and similar validation.
  * Surfaces valid_options in JSON so agents can self-correct.
+ *
+ * Optional `hint` is the agent's *actionable next step* (e.g. for a wrong
+ * --group-by axis on the current modality, the axis that DOES apply). Distinct
+ * from `valid_options`, which describes where the supplied value WOULD be
+ * valid. Both serialize into the error envelope when present.
  */
 export declare class ValidationError extends Error {
     valid_options: string[];
-    constructor(message: string, valid_options: string[]);
+    hint?: string | undefined;
+    constructor(message: string, valid_options: string[], hint?: string | undefined);
 }
 export declare function outputError(err: unknown, json: boolean): void;
 export declare function printTable(headers: string[], rows: string[][]): void;
@@ -48,6 +54,12 @@ export declare function formatWorkspaceDetail(workspace: Record<string, unknown>
 export declare function formatSiteAccessStatus(summary: import("./site-access.js").SiteAccessSummary, json: boolean): void;
 export declare function formatStudyList(studies: Record<string, unknown>[], json: boolean): void;
 export declare function formatStudyDetail(study: Record<string, unknown>, json: boolean, options?: OutputOptions, participants?: ReadonlyArray<Record<string, unknown>>): void;
+/**
+ * Stable JSON envelope for `study results`. Schema is fixed regardless of
+ * study state — fields default to `null`, `0`, or `[]` when nothing has run.
+ * Agents can rely on the keys always being present (M4).
+ */
+export declare function buildStudyResultsEnvelope(study: Record<string, unknown>, participants: ReadonlyArray<Record<string, unknown>>): Record<string, unknown>;
 export declare function formatStudyResults(study: Record<string, unknown>, participants: ReadonlyArray<Record<string, unknown>>, json: boolean): void;
 /**
  * `study results --summary` projection. Drops interview_answers + per-participant
@@ -102,3 +114,14 @@ export declare function deriveWinnerConfidence(args: {
 }): "low" | "medium" | "high";
 export declare function formatAskResults(ask: Record<string, unknown>, json: boolean, roundFilter?: number): void;
 export declare function formatConfigList(configs: Record<string, unknown>[], json: boolean): void;
+export type StudyResultsGroupByKind = "iteration" | "frame" | "segment" | "turn" | "assignment" | "step";
+/**
+ * Render a `--group-by <kind>` projection wrapped in the uniform
+ * `SliceResponse` envelope (`{ axis, rows, totals_unfiltered,
+ * modality_warnings, study_id, modality }`). JSON mode is a thin
+ * pass-through to jsonOutput with `preProjected: true` so the lean
+ * transform doesn't strip our stable empties. Human mode pulls slices
+ * out of `rows` and renders one section per slice plus a small ASCII
+ * sentiment histogram.
+ */
+export declare function formatStudyResultsGroupBy(projection: unknown, kind: StudyResultsGroupByKind, json: boolean): void;