@ishlabs/cli 0.21.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

@@ -8,7 +8,7 @@ import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.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, } from "../lib/study-results-projections.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";
@@ -611,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:
@@ -636,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`);
                 }
@@ -655,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`);
                 }
@@ -671,7 +690,7 @@ 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. Slice with filter flags (--frame, --segment, --turn, --side, --assignment, --step, --sentiment, --actor, --iteration, --participant) or project with --group-by (iteration|frame|segment|turn|assignment|step).")
+        .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. Composes with filters: `--summary --frame login` narrows the summary to the login-screen interactions.")
@@ -688,7 +707,7 @@ list table layout in human mode.`)
         .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 null-sentiment rows.", collectIds, [])
+        .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.")
@@ -713,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",
@@ -733,6 +753,12 @@ When any filter flag is passed, the envelope gains a \`totals_unfiltered\` field
 ("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: [...] }
 
@@ -749,23 +775,34 @@ envelope with participant_count=0 and exit code 0 (not 4).
     "participant_summary": { "comment": "...", "sentiment": {...} }
   }
 
---group-by iteration projection:
-  { study, slices: [{ iteration_id, iteration_label, participant_count, interaction_count, sentiment, sample_comments, top_actions }, ...], totals_unfiltered, warnings }
+--group-by projections share one envelope (uniform across all six axes):
+  { axis, rows, totals_unfiltered, modality_warnings, study_id, modality }
 
---group-by frame projection (interactive only):
-  [{ frame_id, frame_label, interaction_count, sentiment_histogram, sample_comments, participant_aliases }, ...]
+  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)
 
---group-by segment projection (video/audio/text/document):
-  [{ segment_index, segment_label, interaction_count, sentiment_histogram, engagement_histogram, sample_comments }, ...]
+Per-axis row shape (one element of \`rows[]\`):
 
---group-by turn projection (chat only):
-  [{ turn_index, interaction_count, sentiment_histogram, sample_replies, failures }, ...]
+--group-by iteration:
+  { iteration_id, iteration_label, participant_count, interaction_count, sentiment, sample_comments, top_actions }
 
---group-by assignment projection:
-  [{ assignment_id, assignment_name, interaction_count, sentiment_histogram, step_completion }, ...]
+--group-by frame (interactive only):
+  { frame_id, frame_label, interaction_count, sentiment_histogram, sample_comments, participant_aliases }
 
---group-by step projection:
-  [{ assignment_id, assignment_name, step_id, step_name, total, passed, inconclusive, failed, rate, participant_verdicts: [{ participant_alias, verdict, reason, evidence_interaction_ids }, ...] }, ...]
+--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\`),
@@ -794,17 +831,24 @@ 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 projections):
-  --get slices.iteration_label                       # per-iteration: one label per line
-  --get slices.0.participant_count                   # per-iteration: first slice's count
-  --get 0.frame_label                                # per-frame: first frame's label
-  --get 0.sentiment_histogram                        # per-frame/segment/turn: first slice's sentiment map
-  --get 0.segment_index                              # per-segment: first segment's index
-  --get 0.turn_index                                 # per-turn: first turn's index
-  --get 0.assignment_name                            # per-assignment/step: first slice's assignment
-  --get 0.step_name                                  # per-step: first slice's step
-  --get 0.rate                                       # per-step: first step's pass-rate
-  --get 0.participant_verdicts.verdict               # per-step: verdict per participant
+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) => {
@@ -930,15 +974,27 @@ When no runs have completed, the default envelope is returned with zero counts a
             // (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"]);
+                throw new ValidationError(`--group-by frame requires modality=interactive; this study is "${modality}".`, ["interactive"], axisHint(modality));
             }
             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);
+                throw new ValidationError(`--group-by segment requires modality ∈ {${SEGMENT_MODALITIES.join(", ")}}; this study is "${modality}".`, SEGMENT_MODALITIES, axisHint(modality));
             }
             if (groupByKind === "turn" && modality !== "chat") {
-                throw new ValidationError(`--group-by turn requires modality=chat; this study is "${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
@@ -995,7 +1051,8 @@ When no runs have completed, the default envelope is returned with zero counts a
                         projection = buildStudyResultsPerStep(filtered);
                         break;
                 }
-                formatStudyResultsGroupBy(projection, groupByKind, globals.json);
+                const envelope = wrapSliceProjection(filtered, groupByKind, projection, rid, modality);
+                formatStudyResultsGroupBy(envelope, groupByKind, globals.json);
                 return;
             }
             if (wantsSummary) {
@@ -1011,13 +1068,18 @@ When no runs have completed, the default envelope is returned with zero counts a
                 return;
             }
             // Default (no --group-by, no --summary) but filters set: stable
-            // envelope on the filtered participants + totals_unfiltered. Empty
-            // slice contract: zero matches yields participant_count=0 and exit
-            // 0, never a 4/not-found.
+            // 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 });
         });

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)")

package/dist/lib/docs.js

@@ -635,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
@@ -657,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
@@ -1174,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.
@@ -1336,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\`.
 
@@ -1406,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
@@ -1658,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
@@ -1746,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
@@ -1906,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)
@@ -2423,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
@@ -2473,11 +2473,14 @@ reshaping output.
 \`--turn\`, \`--side\`, \`--assignment\`, \`--step\`, \`--sentiment\`,
 \`--actor\`, \`--iteration\`, \`--participant\`) and projection flags
 (\`--group-by iteration|frame|segment|turn|assignment|step\`). When any
-filter is passed, 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.
+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),
@@ -2509,7 +2512,7 @@ client-side; no extra round trip beyond the standard study fetch.
 | \`--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 or label (\`A\`, \`B\`, … case-insensitive).                                    | 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                              |
@@ -2520,33 +2523,52 @@ The exception is \`--group-by\` — see below.
 
 ## Projection flags (--group-by)
 
-| Axis        | Output shape                                                                                                                                                              | Modality |
+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\` | \`{study, slices: [{iteration_id, iteration_label, participant_count, interaction_count, sentiment, sample_comments, top_actions}, ...], totals_unfiltered, warnings}\` | 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            |
+| \`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.
+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
-**stable envelope shape** with:
+**uniform envelope** with:
 
-- \`participant_count: 0\`
+- \`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.
+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
 
@@ -2617,22 +2639,26 @@ No match at all errors and lists the available frame names.
 
 \`\`\`
 # 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:
---get slices.iteration_label             # one label per line
---get slices.0.participant_count
---get slices.0.sentiment
+# 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 (bare array):
---get 0.frame_label
---get 0.segment_index
---get 0.sentiment_histogram
+# 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 0.rate
---get 0.participant_verdicts.verdict     # one verdict per participant
+--get rows.0.rate
+--get rows.0.participant_verdicts.verdict
 \`\`\`
 
 ## Related
@@ -3013,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
@@ -3447,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)
@@ -3609,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:
@@ -3995,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\`)
 

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;
@@ -110,13 +116,12 @@ export declare function formatAskResults(ask: Record<string, unknown>, json: boo
 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. JSON mode is a thin pass-through
- * to jsonOutput with `preProjected: true` so the lean transform doesn't
- * strip our stable empties. Human mode renders one section per slice plus
- * a small ASCII sentiment histogram.
- *
- * The renderer accepts both the wrapped `{study, slices, ...}` shape (per-
- * iteration) and the bare-array shape (every other --group-by); the
- * surface (T5) doesn't need to know the difference.
+ * 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;

package/dist/lib/output.js

@@ -278,6 +278,53 @@ function pickFields(data, fields) {
     }
     return data;
 }
+/**
+ * Pattern A: when an agent passes `--fields foo,bar` and one of those names
+ * doesn't exist on the response, emit a one-line stderr warning naming the
+ * missing fields plus a sample of what IS available. Otherwise unknown names
+ * silently drop and the agent assumes the field doesn't exist on the wire,
+ * when the more common cause is a typo or the wrong projection.
+ *
+ * Probes the response shape: for an object response, the top-level keys;
+ * for a list-wrapper response, the keys of `items[0]`; for a bare array,
+ * the keys of element 0. Warns at most once per command invocation
+ * (the caller invokes this from jsonOutput before pickFields).
+ */
+function warnOnUnknownFields(data, fields) {
+    let probe = null;
+    if (Array.isArray(data) && data.length > 0 && typeof data[0] === "object" && data[0] !== null) {
+        probe = data[0];
+    }
+    else if (data && typeof data === "object" && !Array.isArray(data)) {
+        const obj = data;
+        if (isListWrapper(obj) && Array.isArray(obj.items) && obj.items.length > 0
+            && typeof obj.items[0] === "object" && obj.items[0] !== null) {
+            probe = obj.items[0];
+        }
+        else {
+            probe = obj;
+        }
+    }
+    if (!probe)
+        return;
+    const missing = fields.filter((f) => !(f in probe));
+    if (missing.length === 0)
+        return;
+    // Pattern DD: surface↔backend rename hints. The agent-friendly noun is
+    // "workspace" but the backend stores `product_id`; agents who guess the
+    // surface name need a did-you-mean to find the actual response key.
+    const RENAME_MAP = {
+        workspace_id: "product_id",
+        workspace: "product",
+    };
+    const renameHints = missing
+        .filter((m) => RENAME_MAP[m] && RENAME_MAP[m] in probe)
+        .map((m) => `${m} → ${RENAME_MAP[m]}`);
+    const available = Object.keys(probe).slice(0, 12).join(", ");
+    const more = Object.keys(probe).length > 12 ? `, … (${Object.keys(probe).length - 12} more)` : "";
+    const didYouMean = renameHints.length > 0 ? ` Did you mean: ${renameHints.join(", ")}?` : "";
+    console.error(`warning: --fields requested ${missing.length === 1 ? "name" : "names"} not on the response: ${missing.join(", ")}.${didYouMean} Available: ${available}${more}.`);
+}
 /** Serialize data as JSON, applying lean transform and field selection. */
 function jsonOutput(data, options = {}) {
     let out;
@@ -297,6 +344,7 @@ function jsonOutput(data, options = {}) {
         out = leanJson(data, options.writePath);
     }
     if (_fields && _fields.length > 0) {
+        warnOnUnknownFields(out, _fields);
         out = pickFields(out, _fields);
     }
     // Pattern Ω capture mode: --get <field> returns bare values instead of
@@ -396,12 +444,19 @@ export function outputList(rows, json) {
 /**
  * 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 class ValidationError extends Error {
     valid_options;
-    constructor(message, valid_options) {
+    hint;
+    constructor(message, valid_options, hint) {
         super(message);
         this.valid_options = valid_options;
+        this.hint = hint;
         this.name = "ValidationError";
     }
 }
@@ -434,6 +489,11 @@ function suggestionsForError(err) {
                 return [
                     "Run a list command to see available resources",
                     "Check that the alias or ID is correct",
+                    // Pattern R: an active workspace / study / ask saved in config can
+                    // outlive the resource on the server. Implicit lookups then 404
+                    // with no indication that the ID came from config. `ish status`
+                    // flags orphans; `<entity> use --clear` resets the active value.
+                    "If you didn't pass the resource explicitly, your saved active workspace/study/ask may be stale — run `ish status` to check, then `ish workspace use --clear` (or `ish study use --clear` / `ish ask use --clear`) to reset.",
                 ];
             case "insufficient_credits":
                 return ["Purchase more credits at https://app.ishlabs.io"];
@@ -593,11 +653,14 @@ export function outputError(err, json) {
                 error_code: "validation_error",
                 retryable: false,
                 valid_options: err.valid_options,
+                ...(err.hint && { hint: err.hint }),
                 ...(suggestions.length > 0 && { suggestions }),
             }));
         }
         else {
             console.error(`Error: ${err.message}`);
+            if (err.hint)
+                console.error(`  hint: ${err.hint}`);
             for (const s of suggestions)
                 console.error(`  → ${s}`);
         }
@@ -635,6 +698,9 @@ export function outputError(err, json) {
             ? tagged.suggestions.filter((s) => typeof s === "string")
             : [];
         const mergedSuggestions = [...new Set([...suggestions, ...taggedSuggestions])];
+        const availableValues = Array.isArray(tagged.available_values)
+            ? tagged.available_values.filter((s) => typeof s === "string")
+            : undefined;
         if (json) {
             console.error(JSON.stringify({
                 // Generic Error: CLI-thrown (we control the message), so we don't
@@ -647,6 +713,7 @@ export function outputError(err, json) {
                 ...(errorKind && { error_kind: errorKind }),
                 ...(example && { example }),
                 ...(progress !== undefined && { progress }),
+                ...(availableValues && availableValues.length > 0 && { available_values: availableValues }),
                 ...(seededIds && { seeded_but_not_dispatched_ids: seededIds }),
                 ...(seededAliases && { seeded_but_not_dispatched_aliases: seededAliases }),
                 ...(mergedSuggestions.length > 0 && { suggestions: mergedSuggestions }),
@@ -998,6 +1065,14 @@ export function buildStudyResultsEnvelope(study, participants) {
         ? deterministicAlias(ALIAS_PREFIX.study, String(study.id))
         : null;
     const completedCount = allParticipants.filter((t) => t.status === "completed" || t.status === "complete").length;
+    // Pattern N: per-status breakdown so callers can distinguish running /
+    // pending / cancelled from terminal completed/failed. Additive — the
+    // aggregate counts (`completed_count` / `failed_count`) stay alongside.
+    const participantStatusCounts = {};
+    for (const t of allParticipants) {
+        const key = (t.status || "unknown").toLowerCase();
+        participantStatusCounts[key] = (participantStatusCounts[key] || 0) + 1;
+    }
     // Aggregate sentiment across all interactions on all participants.
     const sentimentCounts = {};
     let sentimentTotal = 0;
@@ -1066,6 +1141,7 @@ export function buildStudyResultsEnvelope(study, participants) {
         participant_count: allParticipants.length,
         completed_count: completedCount,
         failed_count: failedCount,
+        participant_status_counts: participantStatusCounts,
         sentiment,
         interview_answers: interviewAnswers,
         participants: participantRows,
@@ -2253,16 +2329,13 @@ function asciiHistogram(hist, options = {}) {
     });
 }
 function slicesFromProjection(projection) {
-    // Iteration projection wraps `{ study, slices, totals_unfiltered, warnings }`;
-    // all others are bare arrays. Both come through here.
-    if (Array.isArray(projection)) {
-        return projection.filter((s) => Boolean(s) && typeof s === "object" && !Array.isArray(s));
-    }
-    if (projection && typeof projection === "object") {
-        const wrapped = projection;
-        const slices = wrapped.slices;
-        if (Array.isArray(slices)) {
-            return slices.filter((s) => Boolean(s) && typeof s === "object" && !Array.isArray(s));
+    // Surface wraps every --group-by axis in the uniform SliceResponse envelope
+    // `{ axis, rows, totals_unfiltered, modality_warnings, study_id, modality }`;
+    // slices live under `rows`.
+    if (projection && typeof projection === "object" && !Array.isArray(projection)) {
+        const rows = projection.rows;
+        if (Array.isArray(rows)) {
+            return rows.filter((s) => Boolean(s) && typeof s === "object" && !Array.isArray(s));
         }
     }
     return [];
@@ -2393,14 +2466,13 @@ function renderStepSlice(slice) {
     }
 }
 /**
- * Render a `--group-by <kind>` projection. JSON mode is a thin pass-through
- * to jsonOutput with `preProjected: true` so the lean transform doesn't
- * strip our stable empties. Human mode renders one section per slice plus
- * a small ASCII sentiment histogram.
- *
- * The renderer accepts both the wrapped `{study, slices, ...}` shape (per-
- * iteration) and the bare-array shape (every other --group-by); the
- * surface (T5) doesn't need to know the difference.
+ * 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 function formatStudyResultsGroupBy(projection, kind, json) {
     if (json) {

package/dist/lib/skill-content.js

@@ -954,6 +954,12 @@ ish study results s-b2c --frame doesnotexist --json
 #   degraded captures (frame_version_id: null) back.
 \`\`\`
 
+Every \`--group-by <axis>\` call returns the same envelope:
+\`{axis, rows, totals_unfiltered, modality_warnings, study_id, modality}\`.
+The \`rows\` array holds axis-specific slice objects. The envelope is
+uniform across all six axes — agents can code one shape and key on
+\`axis\` / \`modality\` to dispatch on what's inside \`rows\`.
+
 Rules to remember:
 - **Filters compose with AND across flags; OR within \`--sentiment\`.**
   \`--frame login --sentiment Frustrated,Confused\` keeps only login-frame
@@ -974,7 +980,8 @@ Rules to remember:
   the filtered set. \`--transcript\` is single-participant and errors
   (exit 2) when **any** filter or \`--group-by\` is set.
 - Per-step output exposes \`participant_verdicts: [{participant_alias,
-  verdict, reason, evidence_interaction_ids}]\` — not
+  verdict, reason, evidence_interaction_ids}]\` on **each row of
+  \`rows[]\`** (one per \`(assignment, step)\` pair) — not
   \`per_participant_verdicts\`. The verdict enum is \`passed\` /
   \`inconclusive\` / \`failed\`.
 
@@ -1078,6 +1085,7 @@ table, projection shapes, and the defensive null-handling rules.
 | Per-step pass/fail with reasons inline    | \`study participant --json\` per participant + jq | \`ish study results <id> --step verify-email --group-by step --json\` |
 | Frustrated reactions to one media segment | \`study results --json\` + jq | \`ish study results <id> --segment 3 --sentiment Frustrated --json\` |
 | Sanity-check filter coverage              | hand-count \`.participants\` vs total | \`--get totals_unfiltered.participant_count\` (set on every sliced envelope) |
+| Know the sliced-results envelope shape    | guess per axis                         | \`{axis, rows[], totals_unfiltered, modality_warnings, study_id, modality}\` — every \`--group-by\` axis |
 | Chat transcript for one participant (external_chatbot) | \`study participant --json\` + jq      | \`ish study results <id> --transcript <participant_id> --json\`           |
 | Pair-mode conversation transcripts        | \`study participant --json\` per participant       | \`ish iteration get <iter-id> --json \\| jq '.conversations[]'\`     |
 | Participant headline only (no action timeline) | \`study participant --json\` + jq            | \`ish study participant <id> --summary --json\`                           |

package/dist/lib/study-results-filters.js

@@ -79,10 +79,16 @@ function normaliseIterations(rawIterations) {
     }
     return out;
 }
-/** Throw a ValidationError-tagged Error (the wrapper maps it to exit 2). */
-function validationError(message) {
+/** Throw a ValidationError-tagged Error (the wrapper maps it to exit 2).
+ *  Optional `availableValues` rides along as a structured field in the
+ *  emitted JSON envelope so agents can parse the recovery set without
+ *  string-extracting it from the message (Pattern V from round 3). */
+function validationError(message, availableValues) {
     const err = new Error(message);
     err.name = "ValidationError";
+    if (availableValues && availableValues.length > 0) {
+        err.available_values = availableValues;
+    }
     return err;
 }
 /** Resolve `--frame <ref>` into a set of frame_version_ids.
@@ -143,19 +149,21 @@ function resolveFrameRef(ref, frames) {
     const needle = ref.toLowerCase();
     const candidates = frames.filter((f) => f.name && f.name.toLowerCase().includes(needle));
     if (candidates.length === 0) {
-        const available = frames
+        // Pattern V: dedupe + cap the frame list so duplicates (workspace-side
+        // data hazards) don't double-list in the error prose. Carry the
+        // deduped list as a structured `available_values` field for agents.
+        const dedupedNames = Array.from(new Set(frames
             .map((f) => f.name)
-            .filter((n) => typeof n === "string")
-            .slice(0, 10);
-        const hint = available.length > 0
-            ? ` Available frames: ${available.join(", ")}.`
+            .filter((n) => typeof n === "string"))).slice(0, 10);
+        const hint = dedupedNames.length > 0
+            ? ` Available frames: ${dedupedNames.join(", ")}.`
             : " This study has no named frames yet.";
-        throw validationError(`--frame "${ref}" matched no frames on this study.${hint}`);
+        throw validationError(`--frame "${ref}" matched no frames on this study.${hint}`, dedupedNames);
     }
     if (candidates.length > 1) {
-        const names = candidates.map((c) => c.name).filter((n) => !!n);
+        const names = Array.from(new Set(candidates.map((c) => c.name).filter((n) => !!n)));
         throw validationError(`--frame "${ref}" is ambiguous — matched ${candidates.length} frames: ${names.join(", ")}. ` +
-            `Use a more specific substring, a full Frame UUID, or an \`f-…\` alias.`);
+            `Use a more specific substring, a full Frame UUID, or an \`f-…\` alias.`, names);
     }
     indexFrame(candidates[0]);
     return { matchedFrameVersionIds: matched, frameVersionLookup: lookup };
@@ -192,10 +200,23 @@ function resolveAssignmentRef(ref, assignments) {
     return out;
 }
 /** Resolve `--iteration <ref>` to a single iteration_id, or null if no
- *  match (caller errors). UUID-exact or label-exact. */
+ *  match (caller errors). Accepts UUID, iteration alias (`i-…`), or label. */
 function resolveIterationRef(ref, iterations) {
-    if (UUID_RE.test(ref)) {
-        const m = iterations.find((i) => i.id === ref);
+    // Pattern M: iteration aliases (`i-…`) are the canonical short ID
+    // everywhere else in the CLI; accept them here too. Try alias resolution
+    // first, then fall through to UUID-direct, then label match.
+    let candidate = ref;
+    if (ref.startsWith("i-")) {
+        try {
+            candidate = resolveId(ref);
+        }
+        catch {
+            // Unknown alias — let the downstream "matched no iterations" branch
+            // emit the labels hint; the resolveId error doesn't add value here.
+        }
+    }
+    if (UUID_RE.test(candidate)) {
+        const m = iterations.find((i) => i.id === candidate);
         if (!m) {
             throw validationError(`No iteration matches "${ref}" on this study.`);
         }
@@ -383,7 +404,7 @@ export function applyResultsFilters(study, participants, rawFrames, filters) {
         warnings.push(`--turn is only meaningful on chat studies; ignored on modality "${modality}".`);
     }
     if (filters.side !== undefined && !isParticipantPair(study)) {
-        warnings.push(`--side is only meaningful on participant_pair chat studies; ignored.`);
+        warnings.push(`--side is only meaningful on participant_pair chat studies; ignored on modality "${modality}".`);
     }
     // Normalise sentiment labels to lowercase up-front (case-insensitive).
     const sentimentFilter = filters.sentiment

package/dist/lib/study-results-projections.d.ts

@@ -3,14 +3,10 @@
  *
  * Each `buildStudyResultsPer<Kind>` consumes a `FilteredResults` (the output
  * of `applyResultsFilters` in `study-results-filters.ts`) and returns a
- * plain JSON-serialisable value. The surface (T5) hands the result to
- * `output(..., json, { preProjected: true })` for JSON, or to
- * `formatStudyResultsGroupBy` (T6) for human mode.
- *
- * Per-iteration is the only projection that wraps a `{study, slices, ...}`
- * envelope; the others return plain arrays of slice objects. The surface
- * attaches `totals_unfiltered` and `warnings` from the same `FilteredResults`
- * for the array projections.
+ * bare array of slice objects. The surface (`commands/study.ts`) wraps the
+ * array uniformly in a `SliceResponse` envelope alongside `totals_unfiltered`,
+ * `modality_warnings`, `study_id`, and `modality` before handing it off to
+ * `formatStudyResultsGroupBy` for JSON or human rendering.
  *
  * Conventions mirror `buildStudyResultsEnvelope` (`output.ts:1081`) and
  * `buildStudyResultsSummary` (`output.ts:1292`):
@@ -23,18 +19,52 @@
  * Has no IO and no console side-effects.
  */
 import type { FilteredResults } from "./study-results-filters.js";
+import type { StudyResultsGroupByKind } from "./output.js";
 export type { FilteredResults } from "./study-results-filters.js";
 /**
- * `--group-by iteration` — one slice per iteration that has any surviving
- * participants. Slices are ordered by the iteration order on the study
- * (so callers see them in the same order as `ish study get`).
- *
- * Unlike the array-returning projections, this one wraps a stable envelope
- * with `totals_unfiltered` + `warnings` because per-iteration is the
- * "default agent slice" — the one most likely to be piped directly without
- * the surface re-wrapping.
+ * Uniform envelope emitted for every `ish study results --group-by <axis>`
+ * call, mirroring the MCP backend's `SliceResponse[T]`. Six top-level keys,
+ * stable across all six axes — `rows` carries the bare slice array returned
+ * by the matching `buildStudyResultsPer<Kind>` builder.
+ */
+export interface SliceResponse<T> {
+    axis: StudyResultsGroupByKind;
+    rows: T[];
+    totals_unfiltered: {
+        participant_count: number;
+        interaction_count: number;
+    };
+    modality_warnings: string[];
+    study_id: string;
+    modality: string;
+}
+/**
+ * Wrap a bare projection array in the uniform `SliceResponse` envelope.
+ * The surface calls this once after dispatching to one of the six
+ * `buildStudyResultsPer<Kind>` builders, then hands the envelope to
+ * `formatStudyResultsGroupBy`.
+ */
+export declare function wrapSliceProjection<T>(filtered: FilteredResults, axis: StudyResultsGroupByKind, rows: T[], studyId: string, modality: string): SliceResponse<T>;
+interface IterationSlice {
+    iteration_id: string;
+    iteration_label: string | null;
+    participant_count: number;
+    interaction_count: number;
+    sentiment: Record<string, number>;
+    sample_comments: string[];
+    top_actions: Array<{
+        action_type: string;
+        count: number;
+    }>;
+}
+/**
+ * `--group-by iteration` — one slice per declared iteration, in the same
+ * order as `ish study get`. Iterations with zero surviving participants
+ * still appear with `participant_count: 0` so the consumer sees the full
+ * matrix at stable size. Returns a bare array; the surface wraps it in
+ * the uniform `SliceResponse` envelope.
  */
-export declare function buildStudyResultsPerIteration(filtered: FilteredResults): Record<string, unknown>;
+export declare function buildStudyResultsPerIteration(filtered: FilteredResults): IterationSlice[];
 interface FrameSlice {
     frame_id: string;
     frame_label: string | null;

package/dist/lib/study-results-projections.js

@@ -3,14 +3,10 @@
  *
  * Each `buildStudyResultsPer<Kind>` consumes a `FilteredResults` (the output
  * of `applyResultsFilters` in `study-results-filters.ts`) and returns a
- * plain JSON-serialisable value. The surface (T5) hands the result to
- * `output(..., json, { preProjected: true })` for JSON, or to
- * `formatStudyResultsGroupBy` (T6) for human mode.
- *
- * Per-iteration is the only projection that wraps a `{study, slices, ...}`
- * envelope; the others return plain arrays of slice objects. The surface
- * attaches `totals_unfiltered` and `warnings` from the same `FilteredResults`
- * for the array projections.
+ * bare array of slice objects. The surface (`commands/study.ts`) wraps the
+ * array uniformly in a `SliceResponse` envelope alongside `totals_unfiltered`,
+ * `modality_warnings`, `study_id`, and `modality` before handing it off to
+ * `formatStudyResultsGroupBy` for JSON or human rendering.
  *
  * Conventions mirror `buildStudyResultsEnvelope` (`output.ts:1081`) and
  * `buildStudyResultsSummary` (`output.ts:1292`):
@@ -23,6 +19,22 @@
  * Has no IO and no console side-effects.
  */
 import { deterministicAlias, ALIAS_PREFIX } from "./alias-store.js";
+/**
+ * Wrap a bare projection array in the uniform `SliceResponse` envelope.
+ * The surface calls this once after dispatching to one of the six
+ * `buildStudyResultsPer<Kind>` builders, then hands the envelope to
+ * `formatStudyResultsGroupBy`.
+ */
+export function wrapSliceProjection(filtered, axis, rows, studyId, modality) {
+    return {
+        axis,
+        rows,
+        totals_unfiltered: filtered.totals_unfiltered,
+        modality_warnings: filtered.warnings,
+        study_id: deterministicAlias(ALIAS_PREFIX.study, studyId),
+        modality,
+    };
+}
 const SAMPLE_COMMENT_CAP = 5;
 const SAMPLE_COMMENT_MAX_LEN = 200;
 const PARTICIPANT_ALIAS_CAP = 10;
@@ -44,21 +56,24 @@ function asString(v) {
 function truncate(str, maxLen) {
     if (str.length <= maxLen)
         return str;
-    return str.slice(0, maxLen - 3) + "...";
+    // Pattern H: trim at the last word boundary before the cap so quoted
+    // `sample_comments` / `sample_replies` don't end mid-word ("…koncentrera").
+    // Prefer the last sentence terminator if one exists in the kept range;
+    // otherwise fall back to the last whitespace. If neither is found
+    // (a single long unbroken token), hard-cut at the cap.
+    const head = str.slice(0, maxLen - 3);
+    const sentenceBreak = Math.max(head.lastIndexOf(". "), head.lastIndexOf("! "), head.lastIndexOf("? "));
+    if (sentenceBreak >= maxLen / 2)
+        return head.slice(0, sentenceBreak + 1) + "…";
+    const spaceBreak = head.lastIndexOf(" ");
+    if (spaceBreak >= maxLen / 2)
+        return head.slice(0, spaceBreak) + " …";
+    return head + "…";
 }
 function participantAlias(participant) {
     const id = asString(participant.id);
     return id ? deterministicAlias(ALIAS_PREFIX.participant, id) : null;
 }
-function studyHeader(filtered) {
-    const study = filtered.study;
-    const id = asString(study.id);
-    return {
-        alias: id ? deterministicAlias(ALIAS_PREFIX.study, id) : null,
-        name: asString(study.name) ?? null,
-        modality: asString(study.modality) ?? null,
-    };
-}
 function readSentimentLabel(interaction) {
     const s = asRecord(interaction.sentiment);
     return s ? asString(s.label) : null;
@@ -111,14 +126,11 @@ function collectParticipantAlias(bucket, seen, participant) {
     bucket.push(alias);
 }
 /**
- * `--group-by iteration` — one slice per iteration that has any surviving
- * participants. Slices are ordered by the iteration order on the study
- * (so callers see them in the same order as `ish study get`).
- *
- * Unlike the array-returning projections, this one wraps a stable envelope
- * with `totals_unfiltered` + `warnings` because per-iteration is the
- * "default agent slice" — the one most likely to be piped directly without
- * the surface re-wrapping.
+ * `--group-by iteration` — one slice per declared iteration, in the same
+ * order as `ish study get`. Iterations with zero surviving participants
+ * still appear with `participant_count: 0` so the consumer sees the full
+ * matrix at stable size. Returns a bare array; the surface wraps it in
+ * the uniform `SliceResponse` envelope.
  */
 export function buildStudyResultsPerIteration(filtered) {
     const iterations = asArray(filtered.study.iterations);
@@ -176,16 +188,7 @@ export function buildStudyResultsPerIteration(filtered) {
             .map(([action_type, count]) => ({ action_type, count }));
         byIteration.get(iterId).top_actions = rows;
     }
-    // Keep every declared iteration as a slice so the consumer sees the full
-    // matrix at stable size. Iterations with zero surviving rows still appear
-    // with `participant_count: 0` — useful for "matched X / Y" framing.
-    const slices = order.map((o) => byIteration.get(o.id));
-    return {
-        study: studyHeader(filtered),
-        slices,
-        totals_unfiltered: filtered.totals_unfiltered,
-        warnings: filtered.warnings,
-    };
+    return order.map((o) => byIteration.get(o.id));
 }
 /**
  * `--group-by frame` — one slice per Frame that had a surviving interaction.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {