@ishlabs/cli 0.20.0 → 0.22.0

package/dist/commands/chat.js

@@ -115,7 +115,7 @@ Examples:
     });
     parent
         .command("create")
-        .description("Create a chatbot endpoint from a config file or stdin")
+        .description("Create a chatbot endpoint from a hand-written ChatbotEndpointConfig JSON (advanced — use `chat endpoint init` to infer the config from a curl sample, JSON, or template).")
         .requiredOption("--endpoint-config <file>", 'Path to JSON file (or "-" for stdin)')
         .option("--name <name>", "Override the name from the config file")
         .option("--workspace <id>", "Workspace ID")
@@ -342,7 +342,7 @@ endpoint, apply the override, and PUT the merged result. Field flags win over
 function attachChatEndpointInit(parent) {
     parent
         .command("init")
-        .description("Author an endpoint from a curl/JSON sample via test-and-map, or from a known-good template")
+        .description("Author an endpoint from a curl/JSON sample via test-and-map, or from a known-good template (recommended for most users — use `chat endpoint create` only when you already have a hand-written ChatbotEndpointConfig).")
         .option("--from-curl <file>", 'Path to a curl example file (or "-" for stdin)')
         .option("--from-json <file>", 'Path to a JSON request/response sample (or "-" for stdin)')
         .option("--template <name>", `Start from a known-good template (one of: ${TEMPLATE_NAMES.join(", ")})`)

package/dist/commands/config.js

@@ -78,11 +78,25 @@ Run \`ish docs overview\` for the full mental model.`);
     });
     config
         .command("schema")
-        .description("Get simulation config schema with defaults")
+        .description("Get simulation config schema with defaults (admin-only — non-admin accounts: ask an admin to share an existing config ID and pass it via `ish study run --config <id>`).")
         .action(async (_opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get("/dev/simulation-configs/schema");
-            output(data, globals.json);
+            try {
+                const data = await client.get("/dev/simulation-configs/schema");
+                output(data, globals.json);
+            }
+            catch (err) {
+                // Pattern Z: re-throw with a hint pointing non-admin agents at the
+                // workaround (use a shared config ID via `study run --config`).
+                if (err instanceof Error && err.status === 403) {
+                    const tagged = err;
+                    const extra = "Non-admin accounts cannot introspect the simulation-config schema. To still use a config, ask an admin to share an existing config ID and pass it via `ish study run --config <id>` (`config --help` for the full workflow).";
+                    tagged.suggestions = Array.isArray(tagged.suggestions)
+                        ? [...tagged.suggestions, extra]
+                        : [extra];
+                }
+                throw err;
+            }
         });
     });
     config

package/dist/commands/source.js

@@ -27,7 +27,7 @@ same attachment across multiple generation runs; otherwise pass a local path dir
 to \`person generate --source\` and it auto-uploads.
 
 Concept pages: ish docs get-page concepts/source
-                ish docs get-page concepts/profile`);
+                ish docs get-page concepts/person`);
     source
         .command("upload")
         .description("Upload a file as a participant attachment and wait for processing")

package/dist/commands/study-analyze.js

@@ -14,7 +14,7 @@
  * about latency than load).
  */
 import { withClient, resolveStudy, parseWaitTimeout } from "../lib/command-helpers.js";
-import { resolveId } from "../lib/alias-store.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, printTable } from "../lib/output.js";
 import { WaitTimeoutError } from "./study-run.js";
 const POLL_INTERVAL_MS = 5_000;
@@ -160,11 +160,24 @@ Trigger a new run with \`ish study analyze --wait\`.`)
             const history = await client.get(`/studies/${studyId}/results`);
             const latest = history[0] ?? null;
             if (globals.json) {
+                // Pattern K: never emit empty stdout. When no analyses have run,
+                // ship a stable envelope with a hint pointing at the verb that
+                // populates it. Mirrors the `study results` empty-envelope contract.
+                if (!latest) {
+                    const studyAlias = tagAlias(ALIAS_PREFIX.study, studyId);
+                    output({
+                        latest: null,
+                        history: [],
+                        hint: `No analyses run yet. Trigger one with \`ish study analyze ${studyAlias}\`.`,
+                    }, true, { preProjected: true });
+                    return;
+                }
                 output({ latest, history }, true);
                 return;
             }
             if (!latest) {
-                console.log("No analysis runs yet. Trigger one with `ish study analyze`.");
+                const studyAlias = tagAlias(ALIAS_PREFIX.study, studyId);
+                console.log(`No analysis runs yet. Trigger one with \`ish study analyze ${studyAlias}\`.`);
                 return;
             }
             if (opts.all) {

package/dist/commands/study-participant.js

@@ -76,6 +76,25 @@ Tips:
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.participant, String(result.id));
+            // Pattern L: enrich with parent-graph aliases so agents can traverse
+            // from a participant straight to its study without hopping through
+            // `iteration get`. The participant response carries `iteration_id` but
+            // not `study_id`; one iteration fetch supplies both.
+            const iterationId = typeof result.iteration_id === "string" ? result.iteration_id : null;
+            if (iterationId) {
+                result.iteration_alias = tagAlias(ALIAS_PREFIX.iteration, iterationId);
+                try {
+                    const iter = await client.get(`/iterations/${iterationId}`);
+                    if (typeof iter.study_id === "string") {
+                        result.study_id = iter.study_id;
+                        result.study_alias = tagAlias(ALIAS_PREFIX.study, iter.study_id);
+                    }
+                }
+                catch {
+                    // Best-effort enrichment; if the iteration fetch fails (deleted,
+                    // permission), keep going with the alias we already injected.
+                }
+            }
             if (opts.summary) {
                 output(buildParticipantSummary(result), globals.json, { preProjected: true });
                 return;

package/dist/commands/study.js

@@ -3,10 +3,12 @@
  */
 import { readFileSync } from "node:fs";
 import { Option } from "commander";
-import { withClient, getWebUrl, terminalLink, resolveWorkspace, confirmDestructive, readFileOrStdin } from "../lib/command-helpers.js";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, confirmDestructive, readFileOrStdin, collectIds } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
-import { formatStudyList, formatStudyDetail, formatStudyResults, buildStudyResultsSummary, buildChatTranscript, output, ValidationError, } from "../lib/output.js";
+import { formatStudyList, formatStudyDetail, formatStudyResults, buildStudyResultsEnvelope, buildStudyResultsSummary, buildChatTranscript, formatStudyResultsGroupBy, output, ValidationError, } from "../lib/output.js";
+import { applyResultsFilters } from "../lib/study-results-filters.js";
+import { buildStudyResultsPerIteration, buildStudyResultsPerFrame, buildStudyResultsPerSegment, buildStudyResultsPerTurn, buildStudyResultsPerAssignment, buildStudyResultsPerStep, wrapSliceProjection, } from "../lib/study-results-projections.js";
 import { VALID_CONTENT_TYPES } from "../lib/types.js";
 import { fetchStudyParticipants } from "../lib/study-participants.js";
 import { parseAssignment, loadAssignmentsFile, validateAssignmentsArray, parseQuestion } from "../lib/study-inputs.js";
@@ -609,7 +611,7 @@ Next: configure a run with \`ish iteration create --study <id>\`,
     });
     study
         .command("get")
-        .description("Get study overview (accepts multiple IDs for batched lookup)")
+        .description("Get the full study payload — iterations (with run details), assignments, interview questions, sentiment + status counts. Accepts multiple IDs for batched lookup. NOTE: this is the full payload, not a roll-up — for a compact cross-study comparison view use `study results <id> --summary`.")
         .argument("<ids...>", "Study ID(s) — one or more aliases/UUIDs (space- or comma-separated)")
         .addHelpText("after", `
 Examples:
@@ -634,6 +636,18 @@ list table layout in human mode.`)
                 const result = data;
                 if (result.id)
                     result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
+                // Pattern I-r3-1: inline iterations carry only label/name/details
+                // from the wire; tag each with its `alias` (computed from id via
+                // the local alias-store) so agents can drill from `study get` into
+                // `iteration get <alias>` / `study results --iteration <alias>`
+                // without a separate `iteration list` round-trip.
+                if (Array.isArray(result.iterations)) {
+                    for (const iter of result.iterations) {
+                        if (typeof iter.id === "string") {
+                            iter.alias = tagAlias(ALIAS_PREFIX.iteration, iter.id);
+                        }
+                    }
+                }
                 if (data.product_id) {
                     result.url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
                 }
@@ -653,6 +667,13 @@ list table layout in human mode.`)
                 const r = data;
                 if (r.id)
                     r.alias = tagAlias(ALIAS_PREFIX.study, String(r.id));
+                if (Array.isArray(r.iterations)) {
+                    for (const iter of r.iterations) {
+                        if (typeof iter.id === "string") {
+                            iter.alias = tagAlias(ALIAS_PREFIX.iteration, iter.id);
+                        }
+                    }
+                }
                 if (data.product_id) {
                     r.url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
                 }
@@ -669,22 +690,41 @@ list table layout in human mode.`)
     });
     study
         .command("results")
-        .description("View aggregated results: participant counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed.")
+        .description("View aggregated results: participant counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed. Slice with filter flags (--frame [interactive], --segment [video/audio/text/document], --turn [chat], --side [chat participant_pair], --assignment, --step, --sentiment, --actor, --iteration, --participant) or project with --group-by <axis> (iteration | frame [interactive] | segment [media] | turn [chat] | assignment | step).")
         .argument("<id>", "Study ID")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
-        .option("--summary", "Lean summary projection: counts + sentiment + per-participant {alias, status, sentiment, comment}. Drops interview_answers + per-interaction breakdowns.")
+        .option("--summary", "Lean summary projection: counts + sentiment + per-participant {alias, status, sentiment, comment}. Drops interview_answers + per-interaction breakdowns. Composes with filters: `--summary --frame login` narrows the summary to the login-screen interactions.")
         // PC-N4: agents reach for `--summarize` (verb) by analogy with the MCP
         // `summarize` action; accept it as a hidden alias of --summary so the
         // canonical flag stays the documented one but the muscle-memory variant
         // works without a round-trip.
         .addOption(new Option("--summarize", "Hidden alias for --summary").hideHelp())
-        .option("--transcript <participant_id>", "Chat transcript projection for one participant: flat role/text/turn-index array (chat-modality only). Mirrors the MCP `get_chat_transcript` shape.")
+        .option("--transcript <participant_id>", "Chat transcript projection for one participant: flat role/text/turn-index array (chat-modality only). Mirrors the MCP `get_chat_transcript` shape. Cannot combine with filters or --group-by (transcript is a single-participant projection).")
+        // --- Slice / projection flags (T5) ---
+        .option("--frame <ref>", "Filter to interactions whose Frame name contains <ref> (case-insensitive), or whose Frame UUID / `f-…` alias / frame_version_id matches. Interactive only — warned and ignored on other modalities.")
+        .option("--segment <ref>", "Filter media studies (video/audio/text/document) by segment index (integer) or segment label (substring). Image and other modalities: warned and ignored.")
+        .option("--turn <n>", "Filter chat interactions to a single `actions[0].data.turn_index`. Non-chat modalities: warned and ignored.")
+        .option("--side <a|b>", "Filter participant_pair chat interactions by assignment side. Other modalities: warned and ignored.")
+        .option("--assignment <ref>", "Filter to a single assignment by UUID or name (substring, case-insensitive).")
+        .option("--step <ref>", "Filter `participant_assignments[].step_results[]` to a single step by step-id or name (substring). Pair with --include-evidence to also drop non-evidence interactions.")
+        .option("--sentiment <labels>", "Filter to interactions whose sentiment.label is in the comma-separated list (case-insensitive; repeatable). Drops interactions whose sentiment is null. A participant is kept when at least one of their interactions matches, even if their aggregate session sentiment is null (e.g. failed runs with a pre-error matching interaction).", collectIds, [])
+        .option("--actor <actor>", "Filter to interactions whose actor is `ai`, `human`, or `user` (case-insensitive).")
+        .option("--iteration <ref>", "Restrict to a single iteration by UUID or label.")
+        .option("--participant <ref>", "Restrict to a single participant by UUID or `pt-…` alias.")
+        .option("--include-unmatched", "When --frame is set, keep interactions with null frame_version_id under a synthetic `_unmatched` bucket instead of dropping them.")
+        .option("--include-evidence", "When --step is set, also drop interactions not listed in any surviving step_results[].evidence_interaction_ids[].")
+        .option("--group-by <axis>", "Project results into per-axis slices: iteration | frame | segment | turn | assignment | step. Mutually exclusive with --summary and --transcript.")
         .addHelpText("after", `
 Examples:
   $ ish study results <id>
   $ ish study results <id> --json
   $ ish study results <id> --summary --json
   $ ish study results <id> --transcript pt-d4e --json
+  # Slice (filters compose: AND across flags, OR within --sentiment)
+  $ ish study results <id> --frame login --group-by iteration
+  $ ish study results <id> --segment 3 --sentiment Frustrated
+  $ ish study results <id> --assignment "Sign up" --step verify-email --group-by step
+  $ ish study results <id> --side a --turn 4
 
 Default --json envelope (M10: per-answer sentiment now included):
   {
@@ -692,6 +732,7 @@ Default --json envelope (M10: per-answer sentiment now included):
     "participant_count": 12,
     "completed_count": 8,
     "failed_count": 0,
+    "participant_status_counts": { "completed": 8, "running": 3, "draft": 1 },
     "sentiment": { "counts": { "Satisfied": 5, "Frustrated": 2 }, "total": 7 },
     "interview_answers": [
       { "question": "...", "type": "text",
@@ -707,6 +748,17 @@ Default --json envelope (M10: per-answer sentiment now included):
     ]
   }
 
+When any filter flag is passed, the envelope gains a \`totals_unfiltered\` field
+({ participant_count, interaction_count }) so callers 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).
+
+Filtered count semantics: \`participant_count\` is the matched-set total (every
+participant whose interactions matched the filter — including running and
+failed). The unfiltered denominator is \`totals_unfiltered.participant_count\`,
+and the same envelope still carries \`completed_count\` / \`failed_count\` so
+agents can compute "completed AND matched" without a second call.
+
 --summary projection (M2-friction-7: drops the interview_answers payload):
   { study, participant_count, completed_count, failed_count, sentiment, participants: [...] }
 
@@ -723,6 +775,35 @@ Default --json envelope (M10: per-answer sentiment now included):
     "participant_summary": { "comment": "...", "sentiment": {...} }
   }
 
+--group-by projections share one envelope (uniform across all six axes):
+  { axis, rows, totals_unfiltered, modality_warnings, study_id, modality }
+
+  axis              echoes the requested axis (iteration|frame|segment|turn|assignment|step)
+  study_id          the \`s-…\` alias
+  modality          the study's modality
+  totals_unfiltered { participant_count, interaction_count } — pre-filter counts
+  modality_warnings any filter-flag mismatches (e.g. --turn on a non-chat study)
+
+Per-axis row shape (one element of \`rows[]\`):
+
+--group-by iteration:
+  { iteration_id, iteration_label, participant_count, interaction_count, sentiment, sample_comments, top_actions }
+
+--group-by frame (interactive only):
+  { frame_id, frame_label, interaction_count, sentiment_histogram, sample_comments, participant_aliases }
+
+--group-by segment (video/audio/text/document):
+  { segment_index, segment_label, interaction_count, sentiment_histogram, engagement_histogram, sample_comments }
+
+--group-by turn (chat only):
+  { turn_index, interaction_count, sentiment_histogram, sample_replies, failures }
+
+--group-by assignment:
+  { assignment_id, assignment_name, interaction_count, sentiment_histogram, step_completion }
+
+--group-by step:
+  { assignment_id, assignment_name, step_id, step_name, total, passed, inconclusive, failed, rate, participant_verdicts: [{ participant_alias, verdict, reason, evidence_interaction_ids }] }
+
 Tips:
   Use \`--get <path>\` for a single value (e.g. \`--get participant_count\`),
   \`--fields a,b,c\` to project the JSON output further.
@@ -741,6 +822,7 @@ Common --get paths (default envelope):
   --get interview_answers                       # full per-question payload
   --get interview_answers.0.question            # text of the first question
   --get interview_answers.0.answers.0.answer    # first answer to the first question
+  --get totals_unfiltered.participant_count          # pre-filter participant count (when slicing)
 
 Common --get paths (--transcript <participant_id> envelope):
   --get transcript                              # full role/text/turn array
@@ -749,6 +831,25 @@ Common --get paths (--transcript <participant_id> envelope):
   --get participant_summary.sentiment                # aggregate sentiment map
   --get unique_bot_replies                      # bot-side message count
 
+Common --get paths (--group-by envelope — uniform across axes):
+  --get axis                                         # echoes the requested axis
+  --get study_id                                     # s-… alias
+  --get modality                                     # study's modality
+  --get modality_warnings                            # filter-flag mismatches (one warning per line)
+  --get totals_unfiltered.participant_count          # pre-filter participant count
+  --get totals_unfiltered.interaction_count          # pre-filter interaction count
+
+  --get rows.iteration_label                         # per-iteration: one label per line
+  --get rows.0.participant_count                     # per-iteration: first row's count
+  --get rows.0.frame_label                           # per-frame: first row's label
+  --get rows.0.sentiment_histogram                   # per-frame/segment/turn: first row's sentiment map
+  --get rows.0.segment_index                         # per-segment: first row's index
+  --get rows.0.turn_index                            # per-turn: first row's index
+  --get rows.0.assignment_name                       # per-assignment/step: first row's assignment
+  --get rows.0.step_name                             # per-step: first row's step
+  --get rows.0.rate                                  # per-step: first row's pass-rate
+  --get rows.0.participant_verdicts.verdict          # per-step: verdict per participant
+
 When no runs have completed, the default envelope is returned with zero counts and empty arrays.`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
@@ -756,10 +857,76 @@ When no runs have completed, the default envelope is returned with zero counts a
             // into a single boolean before validation so the rest of the
             // handler reads only `summary`.
             const wantsSummary = !!(opts.summary || opts.summarize);
+            // T5: detect whether any filter flag was passed. Interaction-level
+            // and participant-level flags both count — they all narrow the
+            // result set. `--include-unmatched`/`--include-evidence` are
+            // modifiers that only make sense alongside --frame/--step but
+            // count as "filter intent" for the transcript/conflict check.
+            const hasFilter = opts.frame !== undefined ||
+                opts.segment !== undefined ||
+                opts.turn !== undefined ||
+                opts.side !== undefined ||
+                opts.assignment !== undefined ||
+                opts.step !== undefined ||
+                (opts.sentiment !== undefined && opts.sentiment.length > 0) ||
+                opts.actor !== undefined ||
+                opts.iteration !== undefined ||
+                opts.participant !== undefined ||
+                opts.includeUnmatched === true ||
+                opts.includeEvidence === true;
+            const hasGroupBy = opts.groupBy !== undefined;
+            // --- Conflict validation (no IO yet) ---
             if (wantsSummary && opts.transcript) {
                 throw new ValidationError("Pass only one of: --summary, --transcript.", ["--summary", "--transcript"]);
             }
+            if (opts.transcript && (hasFilter || hasGroupBy)) {
+                // --transcript is a single-participant chat projection — slicing
+                // doesn't make sense.
+                throw new ValidationError("--transcript is a single-participant projection; cannot combine with filter flags or --group-by.", ["--transcript"]);
+            }
+            if (wantsSummary && hasGroupBy) {
+                throw new ValidationError("Pass only one of: --summary, --group-by.", ["--summary", "--group-by"]);
+            }
+            // --side validation: must be exactly "a" or "b" (case-insensitive).
+            const sideNormalised = opts.side ? opts.side.toLowerCase() : undefined;
+            if (sideNormalised !== undefined && sideNormalised !== "a" && sideNormalised !== "b") {
+                throw new ValidationError(`--side must be "a" or "b", got "${opts.side}".`, ["a", "b"]);
+            }
+            // --actor validation: must be one of ai|human|user (case-insensitive).
+            const actorNormalised = opts.actor ? opts.actor.toLowerCase() : undefined;
+            if (actorNormalised !== undefined &&
+                actorNormalised !== "ai" &&
+                actorNormalised !== "human" &&
+                actorNormalised !== "user") {
+                throw new ValidationError(`--actor must be "ai", "human", or "user", got "${opts.actor}".`, ["ai", "human", "user"]);
+            }
+            // --turn validation: must parse as a non-negative integer.
+            let turnNum;
+            if (opts.turn !== undefined) {
+                const n = parseInt(opts.turn, 10);
+                if (Number.isNaN(n) || n < 0 || String(n) !== opts.turn.trim()) {
+                    throw new ValidationError(`--turn must be a non-negative integer, got "${opts.turn}".`, []);
+                }
+                turnNum = n;
+            }
+            // --group-by axis whitelist.
+            const VALID_GROUP_BY = [
+                "iteration",
+                "frame",
+                "segment",
+                "turn",
+                "assignment",
+                "step",
+            ];
+            let groupByKind;
+            if (opts.groupBy !== undefined) {
+                if (!VALID_GROUP_BY.includes(opts.groupBy)) {
+                    throw new ValidationError(`--group-by must be one of: ${VALID_GROUP_BY.join(", ")}. Got "${opts.groupBy}".`, VALID_GROUP_BY);
+                }
+                groupByKind = opts.groupBy;
+            }
             const rid = resolveId(id);
+            // --- --transcript fast path (no fetch of study payload) ---
             if (opts.transcript) {
                 // --transcript <participant_id>: bypass the study aggregator; fetch
                 // the named participant directly. Cheaper (one GET, no nested
@@ -769,20 +936,152 @@ When no runs have completed, the default envelope is returned with zero counts a
                 output(buildChatTranscript(participant), globals.json, { preProjected: true });
                 return;
             }
-            const [data, participants] = await Promise.all([
+            // --- Default-fast path: no filter, no group-by ---
+            if (!hasFilter && !hasGroupBy) {
+                const [data, participants] = await Promise.all([
+                    client.get(`/studies/${rid}`),
+                    fetchStudyParticipants(client, rid),
+                ]);
+                if (wantsSummary) {
+                    output(buildStudyResultsSummary(data, participants), globals.json, { preProjected: true });
+                }
+                else {
+                    formatStudyResults(data, participants, globals.json);
+                }
+                if (!globals.json && data.product_id) {
+                    const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
+                    console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                }
+                return;
+            }
+            // --- Slice / projection path: fetch in parallel, then filter+project ---
+            //
+            // Modality gating for --group-by happens AFTER the study fetch
+            // (we need study.modality), but BEFORE any further work — see the
+            // post-fetch validation block below. Pre-fetch validation above is
+            // limited to checks that don't need wire data.
+            const fetchFrames = opts.frame !== undefined;
+            const [study, participants, framesPayload] = await Promise.all([
                 client.get(`/studies/${rid}`),
                 fetchStudyParticipants(client, rid),
+                fetchFrames
+                    ? client.get(`/studies/${rid}/frames`)
+                    : Promise.resolve([]),
             ]);
-            if (wantsSummary) {
-                output(buildStudyResultsSummary(data, participants), globals.json, { preProjected: true });
+            const studyRec = study;
+            const modality = typeof studyRec.modality === "string" ? studyRec.modality : "unknown";
+            // Modality gating for --group-by — router-level, NOT projection-level
+            // (devon's T7 note: projection builders are intentionally
+            // modality-agnostic and bucket non-matching rows into `_unmatched`;
+            // the surface is responsible for refusing nonsensical axes up front).
+            // Pattern B: modality-mismatched --group-by names the offending axis's
+            // domain AND suggests the axis that DOES apply to the study's current
+            // modality, so a cold-start agent can retry productively in one hop.
+            const axisHint = (mod) => {
+                if (mod === "interactive")
+                    return "use --group-by frame";
+                if (["video", "audio", "text", "document"].includes(mod))
+                    return "use --group-by segment";
+                if (mod === "chat")
+                    return "use --group-by turn";
+                return undefined;
+            };
+            if (groupByKind === "frame" && modality !== "interactive") {
+                throw new ValidationError(`--group-by frame requires modality=interactive; this study is "${modality}".`, ["interactive"], axisHint(modality));
             }
-            else {
-                formatStudyResults(data, participants, globals.json);
+            const SEGMENT_MODALITIES = ["video", "audio", "text", "document"];
+            if (groupByKind === "segment" && !SEGMENT_MODALITIES.includes(modality)) {
+                throw new ValidationError(`--group-by segment requires modality ∈ {${SEGMENT_MODALITIES.join(", ")}}; this study is "${modality}".`, SEGMENT_MODALITIES, axisHint(modality));
             }
-            if (!globals.json && data.product_id) {
-                const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
-                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            if (groupByKind === "turn" && modality !== "chat") {
+                throw new ValidationError(`--group-by turn requires modality=chat; this study is "${modality}".`, ["chat"], axisHint(modality));
             }
+            // Coerce the frames payload to a plain array of records (the API
+            // returns a bare array). Tolerate `{items: [...]}` shape in case the
+            // endpoint ever normalises.
+            const rawFrames = Array.isArray(framesPayload)
+                ? framesPayload
+                : Array.isArray(framesPayload?.items)
+                    ? (framesPayload.items)
+                    : [];
+            const filters = {
+                frame: opts.frame,
+                segment: opts.segment,
+                turn: turnNum,
+                side: sideNormalised,
+                assignment: opts.assignment,
+                step: opts.step,
+                sentiment: opts.sentiment && opts.sentiment.length > 0 ? opts.sentiment : undefined,
+                actor: actorNormalised,
+                iteration: opts.iteration,
+                participant: opts.participant,
+                includeUnmatched: opts.includeUnmatched === true ? true : undefined,
+                includeEvidence: opts.includeEvidence === true ? true : undefined,
+            };
+            const filtered = applyResultsFilters(studyRec, participants, rawFrames, filters);
+            // Surface modality-mismatch warnings (and any other diagnostics from
+            // applyResultsFilters) on stderr so JSON output stays clean. The
+            // filter pipeline downgrades mismatched flags to no-ops; the warnings
+            // tell the agent which flags were ignored and why.
+            if (filtered.warnings.length > 0 && !globals.quiet) {
+                for (const w of filtered.warnings) {
+                    console.error(`warning: ${w}`);
+                }
+            }
+            // --- Dispatch: --group-by projection > --summary on filtered > filtered envelope ---
+            if (groupByKind !== undefined) {
+                let projection;
+                switch (groupByKind) {
+                    case "iteration":
+                        projection = buildStudyResultsPerIteration(filtered);
+                        break;
+                    case "frame":
+                        projection = buildStudyResultsPerFrame(filtered);
+                        break;
+                    case "segment":
+                        projection = buildStudyResultsPerSegment(filtered);
+                        break;
+                    case "turn":
+                        projection = buildStudyResultsPerTurn(filtered);
+                        break;
+                    case "assignment":
+                        projection = buildStudyResultsPerAssignment(filtered);
+                        break;
+                    case "step":
+                        projection = buildStudyResultsPerStep(filtered);
+                        break;
+                }
+                const envelope = wrapSliceProjection(filtered, groupByKind, projection, rid, modality);
+                formatStudyResultsGroupBy(envelope, groupByKind, globals.json);
+                return;
+            }
+            if (wantsSummary) {
+                // --summary on filtered participants: narrowed summary projection.
+                // Attach totals_unfiltered so callers can still see the pre-filter
+                // denominator (e.g. "12 / 80 participants matched").
+                const summary = buildStudyResultsSummary(filtered.study, filtered.participants);
+                const summaryOut = {
+                    ...summary,
+                    totals_unfiltered: filtered.totals_unfiltered,
+                };
+                output(summaryOut, globals.json, { preProjected: true });
+                return;
+            }
+            // Default (no --group-by, no --summary) but filters set: stable
+            // envelope on the filtered participants + totals_unfiltered + the
+            // modality_warnings array (Pattern U). Without `modality_warnings`
+            // on this envelope, agents who pipe stderr to /dev/null lose the
+            // filter-mismatch signal entirely; the `--group-by` envelope
+            // already carries it (see wrapSliceProjection), so this is just
+            // closing the asymmetry. Empty slice contract: zero matches still
+            // yields participant_count=0 and exit 0, never a 4/not-found.
+            const envelope = buildStudyResultsEnvelope(filtered.study, filtered.participants);
+            const envelopeOut = {
+                ...envelope,
+                totals_unfiltered: filtered.totals_unfiltered,
+                modality_warnings: filtered.warnings,
+            };
+            output(envelopeOut, globals.json, { preProjected: true });
         });
     });
     study

package/dist/lib/alias-store.d.ts

@@ -19,6 +19,7 @@ export declare const ALIAS_PREFIX: {
     readonly askRound: "r";
     readonly chatEndpoint: "ep";
     readonly chatConfig: "cc";
+    readonly frame: "f";
 };
 /**
  * Save aliases for a list of IDs under the given prefix.

package/dist/lib/alias-store.js

@@ -22,6 +22,7 @@ export const ALIAS_PREFIX = {
     askRound: "r",
     chatEndpoint: "ep",
     chatConfig: "cc",
+    frame: "f",
 };
 /** Format a number with zero-padding (minimum 2 digits). */
 function padNum(n) {
@@ -133,6 +134,7 @@ const HYDRATE_HINT = {
     a: "ish ask list",
     r: "ish ask get <ask-id>",
     ep: "ish chat endpoint list",
+    f: "ish study results <study-id> --frame <name>  # frames are discovered via the study's frames endpoint",
     // Legacy two-letter prefixes the deterministic generator may have
     // produced before; defaults below cover anything else.
 };

package/dist/lib/command-helpers.js

@@ -294,15 +294,16 @@ function enforceParticipantCap(ids, flags, opts) {
  */
 export function addPersonFilterFlags(cmd, opts = {}) {
     const allFlag = opts.allFlagName ?? "--all";
-    const allDesc = opts.allFlagDescription ?? "Use every person matching the filters";
+    const allDesc = (opts.allFlagDescription ?? "Use every person matching the filters")
+        + " (capped at 20 per dispatch — split into multiple slices for larger cohorts)";
     return cmd
         .option("--person <ids>", "Person IDs/aliases (comma-separated or repeatable)", collectIds, [])
-        .option("--sample <N>", "Randomly sample N people from the matching pool")
+        .option("--sample <N>", "Randomly sample N people from the matching pool (max 20 per dispatch — split into multiple slices for larger cohorts)")
         .option(allFlag, allDesc)
         .option("--search <text>", "Substring match against person name")
         .option("--bio <text>", "Substring match against person bio")
         .option("--occupation <text>", "Substring match against person occupation (repeatable)", collectRepeatable, [])
-        .option("--gender <gender>", "Filter by gender (repeatable)", collectRepeatable, [])
+        .option("--gender <gender>", "Filter by gender (female, male, nonbinary; repeatable, OR semantics)", collectRepeatable, [])
         .option("--country <code>", "Filter by 2-letter country code (repeatable)", collectRepeatable, [])
         .option("--min-age <n>", "Minimum age (inclusive)")
         .option("--max-age <n>", "Maximum age (inclusive)")