@ishlabs/cli 0.19.0 → 0.21.0

package/dist/lib/command-helpers.js

@@ -28,7 +28,7 @@ const VISIBILITY_ALIASES = {
     private: "workspace",
     public: "platform",
 };
-function normalizeVisibility(raw) {
+export function normalizeVisibility(raw) {
     if (raw === undefined)
         return undefined;
     return VISIBILITY_ALIASES[raw] ?? raw;
@@ -186,6 +186,12 @@ export async function resolvePersonIds(client, workspace, flags, opts = {}) {
     if (sampleN === undefined && !flags.all && !filtersUsed) {
         throw new Error(`Select people: pass --person <id> (repeatable), --sample <N>, ${allFlagName}, or filter flags (--bio, --country, --gender, --min-age, --max-age, --occupation, --search, --visibility).`);
     }
+    // NEW-CP-2 / Pattern H: --sample N > backend cap is detectable without
+    // any API call — fail fast so a bad value doesn't burn a /people round-trip
+    // before the cap message surfaces.
+    if (sampleN !== undefined && sampleN > PARTICIPANT_BATCH_CAP) {
+        throw new Error(`--sample ${sampleN} exceeds the per-dispatch participant cap of ${PARTICIPANT_BATCH_CAP}. Pass --sample ${PARTICIPANT_BATCH_CAP} or fewer, or split the run into multiple dispatches.`);
+    }
     const params = {
         product_id: workspace,
         type: "ai",
@@ -245,15 +251,41 @@ export async function resolvePersonIds(client, workspace, flags, opts = {}) {
         throw new Error(`No ${sim}people found in workspace ${workspace}.${opts.requireSimulatable ? " Create people with simulation configs first." : ""}`);
     }
     if (flags.all)
-        return pool.map((p) => p.id);
+        return enforceParticipantCap(pool.map((p) => p.id), flags, opts);
     if (sampleN !== undefined) {
         if (sampleN > pool.length) {
             throw new Error(`--sample ${sampleN} requested but only ${pool.length} matching person${pool.length === 1 ? "" : "s"} available.`);
         }
+        // sampleN > PARTICIPANT_BATCH_CAP is caught earlier (before the
+        // /people fetch) so we don't reach here with an over-cap sample.
         return shuffleInPlace([...pool]).slice(0, sampleN).map((p) => p.id);
     }
-    // Filters only, no --sample/--all → return every match.
-    return pool.map((p) => p.id);
+    // Filters only, no --sample/--all → return every match (subject to cap).
+    return enforceParticipantCap(pool.map((p) => p.id), flags, opts);
+}
+/**
+ * Backend caps each dispatch batch at 20 simulations (Pydantic
+ * `max_length=20` on the `simulations` array in
+ * app/api/models/simulation.py, media.py, and chat.py). Without a
+ * client-side guard, `--all` on a workspace with platform-visible
+ * people resolves to ~200 (the `/people` pagination limit) and the
+ * backend returns a `validation_error` ("List should have at most 20
+ * items after validation, not 200") that's confusing without context.
+ * Throw a helpful client-side error before the dispatch so the user
+ * knows to sample explicitly.
+ *
+ * Discovered during the 2026-05-26 post-remediation checkpoint sweep
+ * (NEW-CP-2). If the backend cap changes, update PARTICIPANT_BATCH_CAP.
+ */
+const PARTICIPANT_BATCH_CAP = 20;
+function enforceParticipantCap(ids, flags, opts) {
+    if (ids.length <= PARTICIPANT_BATCH_CAP)
+        return ids;
+    const allFlagName = opts.allFlagName ?? "--all";
+    const filterDesc = describeFilters(flags) || "no filter";
+    throw new Error(`Resolved ${ids.length} participants (${filterDesc}) but the backend caps each dispatch at ${PARTICIPANT_BATCH_CAP}. ` +
+        `Pass \`--sample ${PARTICIPANT_BATCH_CAP}\` to randomly subsample the pool, narrow your filters, or run the dispatch ` +
+        `multiple times against different slices. ${allFlagName} without --sample is only safe when the matching pool is ≤${PARTICIPANT_BATCH_CAP}.`);
 }
 /**
  * Attach the person-selection flag set to a Commander command.
@@ -375,7 +407,25 @@ export function exitCodeFromError(err) {
             return 5;
     }
     if (err instanceof Error) {
-        // Auth-related client errors (e.g. missing token)
+        // Pattern D: structured `error_code` on the Error object takes
+        // precedence over message-regex sniffing. Sites that self-tag
+        // (alias-store, auth, sub-command envelopes) get a deterministic
+        // exit code; sites that don't fall back to the legacy regex below.
+        // Order matters: this block must run BEFORE the /^invalid /i and
+        // /no auth token found/ regexes (which would otherwise misclassify
+        // the new `not_found` tag as `2` because the message starts with
+        // "Invalid ID").
+        const code = err.error_code;
+        if (typeof code === "string") {
+            if (code === "usage_error")
+                return 2;
+            if (code === "auth_failed")
+                return 3;
+            if (code === "not_found")
+                return 4;
+        }
+        // Auth-related client errors (e.g. missing token) — legacy regex
+        // path; the new error_code tagging above is the preferred route.
         if (/no auth token found|run "ish login"|saved token is invalid|session expired/i.test(err.message))
             return 3;
         // Client-side validation failures
@@ -393,8 +443,30 @@ export function exitCodeFromError(err) {
         // Structured error_kind on the Error object (set by chat endpoint test/init,
         // simulation routes, etc.). TunnelInactive is the canonical transient one.
         const kind = err.error_kind;
-        if (typeof kind === "string" && kind === "TunnelInactive")
-            return 5;
+        if (typeof kind === "string") {
+            // Transient: user can fix the cause and retry (tunnel down, bot
+            // auth credentials missing/wrong, upstream rate-limited).
+            if (kind === "TunnelInactive" || kind === "BotAuthError")
+                return 5;
+            // Validation-shaped: user passed something bad to the CLI/endpoint.
+            if (kind === "ConfirmationRequired" || kind === "BotShapeError")
+                return 2;
+        }
+        // (error_code mapping moved earlier in the function — see top of the
+        // `err instanceof Error` block. Order matters: it must run BEFORE
+        // the legacy regex sniffers to honor self-tagged errors.)
+        // Pattern E (ISSUE-021): DNS / connection failures are transient.
+        // Node's fetch surfaces them as TypeError with .cause = { code: "..." }.
+        const cause = err.cause;
+        if (cause && typeof cause === "object") {
+            const causeCode = cause.code;
+            if (typeof causeCode === "string" && (causeCode === "ENOTFOUND"
+                || causeCode === "ECONNREFUSED"
+                || causeCode === "ECONNRESET"
+                || causeCode === "ETIMEDOUT"
+                || causeCode === "EAI_AGAIN"))
+                return 5;
+        }
     }
     return 1;
 }

package/dist/lib/docs.js

@@ -156,6 +156,25 @@ first scraping the list.
 The full saturated-account walkthrough (with branch logic + a worked
 transcript) lives at \`guides/cold-start\`.
 
+## Deleting a workspace
+
+\`ish workspace delete <id>\` is the **highest-blast-radius destructive op
+in the CLI** — it removes ALL nested studies, asks, people, secrets,
+configs, sources, and chat endpoints. The confirmation guard is
+mandatory:
+
+- **Interactive (TTY)**: prompts on stderr naming the workspace; type
+  \`y\` to proceed.
+- **Non-interactive** (\`--json\`, piped, or non-TTY stdin): pass
+  \`-y\` / \`--yes\` to confirm. Without it, the CLI exits with usage
+  code 2 rather than deleting silently.
+
+\`\`\`
+ish workspace delete w-6ec              # interactive prompt
+ish workspace delete w-6ec --yes        # skip prompt
+ish workspace delete w-6ec --json --yes # JSON/agent consumers must be explicit
+\`\`\`
+
 ## Related
 
 - \`guides/cold-start\` — saturated-account first-step playbook
@@ -296,6 +315,8 @@ pick was wrong.
 - \`concepts/assignment\` — task definition syntax.
 - \`concepts/questionnaire\` — question types and timing.
 - \`concepts/run-verbs\` — when to use \`study run\` vs \`ask run\`.
+- \`guides/slicing-results\` — filter / project \`study results\` by frame,
+  segment, turn, sentiment, assignment, step.
 - \`reference/billing-limits\` — \`maxStudiesPerProduct\` cap on study creation.
 - \`reference/credits\` — per-run credit cost & how to preview before dispatch.
 `;
@@ -832,6 +853,9 @@ ride along when present in the JSON forms.
 
 - \`concepts/study\` — assignments are immutable to the run; questionnaire is too.
 - \`concepts/questionnaire\` — the other half of the study definition.
+- \`guides/slicing-results\` — slice the post-run envelope by step
+  (\`--step verify-email --group-by step\`), surface per-participant verdicts
+  inline, or restrict to the evidence interactions with \`--include-evidence\`.
 - \`reference/json-mode\` — how \`step_completion\` renders in lean vs --verbose.
 `;
 const CONCEPT_QUESTIONNAIRE = `# concept: questionnaire
@@ -1083,12 +1107,32 @@ round-trips when you know them up front:
 - \`image:./hero-a.png\` — local image (auto-uploaded)
 - \`image:./a.png::label=A\` — with explicit label
 
+## Deleting an ask
+
+\`ish ask delete <id>\` requires explicit confirmation (parallels
+\`workspace delete\`, \`study delete\`, \`person delete\`, \`source
+delete\`, \`chat endpoint delete\`):
+
+- **Interactive (TTY)**: prompts on stderr; type \`y\` to proceed.
+- **Non-interactive** (\`--json\`, piped, or non-TTY stdin): pass
+  \`-y\` / \`--yes\` to confirm. Without it, the CLI exits with usage
+  code 2 rather than deleting silently.
+
+\`\`\`
+ish ask delete a-6ec              # interactive prompt
+ish ask delete a-6ec --yes        # skip prompt
+ish ask delete a-6ec --json --yes # JSON consumers must be explicit
+\`\`\`
+
+The active ask is auto-cleared from \`~/.ish/config.json\` if the
+deleted ask was the active one.
+
 ## Related
 
 - \`concepts/round\` — what a round is and how it executes.
 - \`concepts/people\` — how participants are chosen at ask creation.
 - \`concepts/run-verbs\` — \`ish ask run\` vs \`ish study run\`.
-- \`reference/credits\` — ask rounds bill 1 credit per successful response.
+- \`reference/credits\` — ask rounds bill **one credit per successful participant per round**, regardless of how many \`questions\` were included. The backend's asks worker bills \`amount=succeeded\` once per round dispatch; questions and round-summary synthesis don't trigger separate debits. A 3-person panel with 2 follow-up questions costs \`3\` credits when all complete, the same as a no-questions run. Failed participant responses (pre-flight errors, refusals) don't bill.
 `;
 const CONCEPT_ROUND = `# concept: round
 
@@ -1261,6 +1305,21 @@ The legacy \`--tech-savviness\` flag was removed in
 \`person-schema-v2\`; passing it now produces commander's standard
 "unknown option" error.
 
+## Deleting a person
+
+\`ish person delete <id>\` requires explicit confirmation:
+
+- **Interactive (TTY)**: prompts on stderr; type \`y\` to proceed.
+- **Non-interactive** (\`--json\`, piped, or non-TTY stdin): pass
+  \`-y\` / \`--yes\` to confirm. Without it, the CLI exits with usage
+  code 2 rather than deleting silently.
+
+\`\`\`
+ish person delete p-d4e              # interactive prompt
+ish person delete p-d4e --yes        # skip prompt
+ish person delete p-d4e --json --yes # JSON consumers must be explicit
+\`\`\`
+
 ## Related
 
 - \`concepts/source\` — the inputs to \`person generate\`.
@@ -1303,6 +1362,24 @@ in real customer evidence.
 ish source get ps-3a4
 \`\`\`
 
+## Deleting a source
+
+\`ish source delete <id>\` requires explicit confirmation:
+
+- **Interactive (TTY)**: prompts on stderr; type \`y\` to proceed.
+- **Non-interactive** (\`--json\`, piped, or non-TTY stdin): pass
+  \`-y\` / \`--yes\` to confirm. Without it, the CLI exits with usage
+  code 2 rather than deleting silently.
+
+\`\`\`
+ish source delete ps-3a4              # interactive prompt
+ish source delete ps-3a4 --yes        # skip prompt
+ish source delete ps-3a4 --json --yes # JSON consumers must be explicit
+\`\`\`
+
+The backend ref-counts the underlying file: the storage object is
+removed only when no profile mappings remain.
+
 ## Related
 
 - \`concepts/person\` — sources feed profile generation.
@@ -1405,6 +1482,30 @@ manager"\` or \`"retail associate"\` return many. Two adaptations:
 - \`ish ask run\` (without \`--new\`) → cannot change participants; the ask
   fixes it at creation. Audience flags only apply with \`--new\`.
 
+## Per-dispatch cap (20)
+
+Each \`study run\` / \`ask run\` / \`chat\` dispatch is capped at **20
+participants** by the backend (\`max_length=20\` on the \`simulations\`
+list). The CLI enforces this client-side BEFORE the network round-trip
+so a too-large \`--sample\` or an unbounded \`--all\` returns a clear
+error instead of a confusing server-side \`validation_error\`:
+
+\`\`\`
+$ ish study run --all                # on a workspace with platform pool
+Error: Resolved 200 participants (no filter) but the backend caps each dispatch at 20.
+  Pass \`--sample 20\` to randomly subsample the pool, narrow your filters, or run
+  the dispatch multiple times against different slices. --all without --sample is
+  only safe when the matching pool is ≤20.
+
+$ ish study run --sample 25          # bad value caught before /people fetch
+Error: --sample 25 exceeds the per-dispatch participant cap of 20.
+  Pass --sample 20 or fewer, or split the run into multiple dispatches.
+\`\`\`
+
+For larger panels: dispatch multiple times against different demographic
+slices (\`--country SE\`, then \`--country GB\`, etc.) or use the web UI
+which batches behind the scenes.
+
 ## Examples
 
 \`\`\`
@@ -2254,17 +2355,33 @@ The CLI guarantees these contracts so agents can chain safely:
 
 ## Exit codes
 
-| Code | Meaning              |
-|------|----------------------|
-| 0    | Success              |
-| 1    | General error        |
-| 2    | Usage / validation   |
-| 3    | Auth (re-run \`ish login\`) |
-| 4    | Not found            |
-| 5    | Transient — retryable (timeout, 5xx, network) |
+| Code | Meaning              | Common \`error_code\` values |
+|------|----------------------|------------------------------|
+| 0    | Success              | —                            |
+| 1    | General error        | \`server\`, \`client_error\` (uncategorized) |
+| 2    | Usage / validation   | \`usage_error\` (Commander), \`validation_error\` (server), \`ConfirmationRequired\` |
+| 3    | Auth (re-run \`ish login\`) | \`auth_failed\`, missing-token errors |
+| 4    | Not found            | \`not_found\`                |
+| 5    | Transient — retryable | \`timeout\`, \`TunnelInactive\`, \`BotAuthError\`, DNS / network (\`ENOTFOUND\`, \`ECONNREFUSED\`) |
 
 Use these to branch in scripts; do not parse the human stderr message.
 
+**Commander-level errors** (unknown command, missing required argument,
+missing required option) all exit **2** with \`error_code: "usage_error"\`.
+The suggestion field points at the right help target:
+
+- Unknown command → \`Run \`ish --help\` for usage\` (the typo IS the
+  command name — don't point at it; Commander also appends
+  \`(Did you mean workspace?)\` for near-matches).
+- Missing argument / option → \`Run \`ish <command> --help\` for usage\`
+  (substituted with the actual command, e.g. \`ish workspace --help\`).
+
+**DNS / connection failures** (a wrong \`--api-url\`, a backend that's
+down, a captive portal) exit **5** so scripts retry rather than abort
+permanently. The underlying \`fetch\` \`TypeError\` is detected via its
+\`cause.code\` (\`ENOTFOUND\`, \`ECONNREFUSED\`, \`ECONNRESET\`,
+\`ETIMEDOUT\`, \`EAI_AGAIN\`).
+
 ## Error envelope
 
 When a command fails with \`--json\` (or piped stdout), the CLI prints
@@ -2294,6 +2411,12 @@ a structured error object on **stdout** and a human message on
 (\`validation\`, \`auth\`, \`not_found\`, \`timeout\`, \`server\`,
 \`network\`, …). \`retryable: true\` matches exit code 5.
 
+The \`status\` field carries the upstream **HTTP status code** when one
+is available (e.g. \`401\`, \`404\`, \`422\`). It is **omitted entirely**
+from envelopes that don't originate from an HTTP response (Commander
+parse errors, local validation failures, alias-resolution errors). Do
+not branch on \`status: 0\` — that value is never emitted as of 0.20.
+
 ## Conventions
 
 - Successful commands exit 0 and print one JSON object/array on stdout.
@@ -2343,6 +2466,184 @@ ish study results --human
 When you genuinely need multiple fields in one parse pass, \`--json\` is
 still the right tool — \`--get\` is for single-value capture, not for
 reshaping output.
+
+## Slicing study results
+
+\`ish study results <id>\` accepts filter flags (\`--frame\`, \`--segment\`,
+\`--turn\`, \`--side\`, \`--assignment\`, \`--step\`, \`--sentiment\`,
+\`--actor\`, \`--iteration\`, \`--participant\`) and projection flags
+(\`--group-by iteration|frame|segment|turn|assignment|step\`). When any
+filter is passed, 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\` is **router-gated by modality**: \`frame\` requires
+interactive, \`segment\` requires media (video / audio / text / document),
+\`turn\` requires chat. Mismatched filter flags (e.g. \`--segment 0\` on
+an interactive study) emit a stderr warning and are ignored — they
+don't error. Full worked examples in \`guides/slicing-results\`.
+`;
+const GUIDE_SLICING_RESULTS = `# guide: slicing study results
+
+\`ish study results <id>\` returns a kitchen-sink envelope by default
+(every participant, every interaction, every interview answer). For
+narrower questions — *"what differed on the login screen across these
+five iterations?"*, *"who failed verify-email, and why?"*, *"frustrated
+reactions to segment 3 of the video"* — \`ish study results\` accepts
+**filter flags** (which interactions to keep) and **projection flags**
+(how to roll up what survives). Filters compose with AND across flags
+and OR within \`--sentiment\`. Filters and projections are pure
+client-side; no extra round trip beyond the standard study fetch.
+
+## Filter flags
+
+| Flag                          | Matches                                                                                       | Where it applies                                                |
+|-------------------------------|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------|
+| \`--frame <ref>\`             | Interactions whose Frame name contains \`<ref>\` (case-insensitive). Also accepts a full Frame UUID, an \`f-…\` alias, or a \`frame_version_id\` UUID. | interactive — warn + ignore on chat / media                      |
+| \`--segment <ref>\`           | Integer matches \`actions[0].data.segment_index\`; non-integer is a substring match against \`segment_label\`. | video, audio, text, document — warn + ignore elsewhere           |
+| \`--turn <n>\`                | Interactions whose \`actions[0].data.turn_index == n\`.                                       | chat (external_chatbot + participant_pair)                       |
+| \`--side <a\|b>\`             | Interactions whose parent assignment has \`side == a\` or \`side == b\`.                       | chat participant_pair — warn + ignore on other chat / non-chat   |
+| \`--assignment <ref>\`        | Assignment UUID, or substring match against the assignment name.                              | all                                                              |
+| \`--step <ref>\`              | Filters \`participant_assignments[].step_results[]\` to verdicts matching the step id or name. | interactive + external_chatbot chat (steps live there)           |
+| \`--sentiment <labels>\`      | Comma-separated, case-insensitive label list (repeatable). Drops null-sentiment rows.         | all                                                              |
+| \`--actor <ai\|human\|user>\` | Restrict by actor.                                                                            | all                                                              |
+| \`--iteration <ref>\`         | Iteration UUID or label (\`A\`, \`B\`, … case-insensitive).                                    | all                                                              |
+| \`--participant <ref>\`       | Participant UUID or \`pt-…\` alias.                                                            | all                                                              |
+| \`--include-unmatched\`       | With \`--frame\`, keep degraded captures (\`frame_version_id: null\`) under a synthetic \`_unmatched\` bucket instead of dropping them. | interactive                                                      |
+| \`--include-evidence\`        | With \`--step\`, also drop interactions not listed in any surviving \`step_results[].evidence_interaction_ids[]\`. | interactive + external_chatbot chat                              |
+
+**Modality mismatch is not an error.** Pass \`--segment 0\` on an
+interactive study and the filter is ignored with a stderr warning.
+The exception is \`--group-by\` — see below.
+
+## Projection flags (--group-by)
+
+| Axis        | Output shape                                                                                                                                                              | 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            |
+
+\`--group-by\` is **mutually exclusive with \`--summary\` and
+\`--transcript\`**. \`--group-by frame\` on a chat study, \`--group-by
+turn\` on a video study, etc. error at the surface (exit 2) with a
+clear message before any IO.
+
+## The empty-slice contract
+
+A filter combination that matches zero interactions returns the
+**stable envelope shape** with:
+
+- \`participant_count: 0\`
+- \`totals_unfiltered: {participant_count: <N>, interaction_count: <M>}\` 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.
+
+## Worked examples
+
+\`\`\`bash
+# What differed on the login screen across the five iterations?
+ish study results s-b2c --frame login --group-by iteration
+
+# Frustrated reactions to segment 3 of the video
+ish study results s-b2c --segment 3 --sentiment Frustrated
+
+# Who failed the "verify email" step, and why?
+ish study results s-b2c --assignment "Sign up" --step verify-email --group-by step
+
+# Chat participant_pair: only side A turn 4
+ish study results s-b2c --side a --turn 4
+
+# Surface degraded captures (frame_version_id: null) under a "_unmatched" bucket:
+ish study results s-b2c --frame login --include-unmatched --group-by frame
+
+# Narrow the lean summary to a slice:
+ish study results s-b2c --summary --frame checkout --json
+\`\`\`
+
+## Combining filters
+
+Filters compose with **AND across flags** and **OR within
+\`--sentiment\`**. \`--frame login --sentiment Frustrated,Confused\`
+means "interactions on the login frame whose sentiment is Frustrated
+OR Confused". \`--summary\` is orthogonal to filters and narrows the
+summary over the filtered set. \`--transcript\` is single-participant
+and **errors when any filter or \`--group-by\` is set** (exit 2).
+
+## Defensive handling of nullable fields
+
+- \`interaction.sentiment\` is nullable (chat failure stubs,
+  pre-sentiment rows). Dropped **only** when \`--sentiment\` is set; kept
+  by every other filter.
+- \`interaction.frame_version_id\` is nullable on interactive studies
+  (degraded captures, ~12% on a failing iteration). Dropped by
+  \`--frame\` unless \`--include-unmatched\` is passed; surfaced as a
+  \`_unmatched\` bucket in \`--group-by frame\`.
+- Chat \`bot_reply.failure\` rows are kept in the default envelope,
+  dropped by \`--sentiment\` (they have \`sentiment: null\`), kept by
+  \`--actor\`, visible in \`--group-by turn\` under a \`failures\`
+  counter.
+
+## --frame resolution
+
+\`--frame login\` walks the frame list returned by
+\`GET /studies/{id}/frames\` and matches **case-insensitive substring**
+against the frame name. Other accepted shapes:
+
+- \`--frame 6ec…\` — full Frame UUID (exact match)
+- \`--frame f-6ec\` — short alias resolved via \`alias-store\`
+- \`--frame 7ec…\` — a \`frame_version_id\` UUID (matches only that version)
+
+Ambiguous substring (matches >1 frame) errors with the candidate list:
+
+\`\`\`
+ish study results s-b2c --frame log
+# Error: --frame "log" is ambiguous — matched 2 frames: Login, Logout.
+# Use a more specific substring, a full Frame UUID, or an \`f-…\` alias.
+\`\`\`
+
+No match at all errors and lists the available frame names.
+
+## Common --get paths on a sliced envelope
+
+\`\`\`
+# Sanity-check coverage:
+--get totals_unfiltered.participant_count
+--get totals_unfiltered.interaction_count
+
+# Per-iteration projection:
+--get slices.iteration_label             # one label per line
+--get slices.0.participant_count
+--get slices.0.sentiment
+
+# Per-frame / per-segment / per-turn (bare array):
+--get 0.frame_label
+--get 0.segment_index
+--get 0.sentiment_histogram
+
+# Per-step:
+--get 0.rate
+--get 0.participant_verdicts.verdict     # one verdict per participant
+\`\`\`
+
+## Related
+
+- \`concepts/study\` — the parent artifact whose results are being sliced.
+- \`concepts/assignment\` — defines the steps that \`--step\` and
+  \`--group-by step\` filter against.
+- \`reference/json-mode\` — display vs capture vs chain output rules
+  (\`--get\`, \`--fields\`, exit codes).
+- \`reference/aliases\` — \`s-…\` for studies, \`pt-…\` for participants,
+  \`f-…\` for frames. Any UUID-accepting flag also accepts the alias.
 `;
 const GUIDE_FIRST_STUDY = `# guide: your first study, end to end
 
@@ -2411,13 +2712,19 @@ The CLI keeps a small amount of session state in \`~/.ish/config.json\`
 (or wherever \`ISH_HOME\` points) so commands don't need to repeat IDs:
 
 - \`access_token\` / \`refresh_token\` — the OAuth pair from \`ish login\`.
-- \`workspace\`  — set by \`ish workspace use <id>\`.
-- \`study\`      — set by \`ish study use <id>\`.
-- \`ask\`        — set by \`ish ask use <id>\`.
+- \`workspace\`      — set by \`ish workspace use <id>\`.
+- \`study\`          — set by \`ish study use <id>\` (or implicitly by \`ish study create\`).
+- \`ask\`            — set by \`ish ask use <id>\` (or implicitly by \`ish ask create\`).
+- \`chat_endpoint\`  — set by \`ish chat endpoint use <id>\`.
 
 Most commands fall back to these when their corresponding flag is
 omitted (\`--workspace\`, \`--study\`, \`--ask\`).
 
+**\`workspace\` is the parent** of \`study\`, \`ask\`, and \`chat_endpoint\` —
+all three are scoped to a single workspace. Switching workspaces
+(\`ish workspace use <other>\`) clears all three to avoid cross-workspace
+footguns, and the CLI prints a one-line stderr note when it does so.
+
 ## Inspecting active context
 
 \`ish status\` (alias: \`ish whoami\`) is the canonical way to see what's
@@ -2430,7 +2737,8 @@ ish status
 # User:       you@example.com  (token valid, expires in 47m)
 # Workspace:  Onboarding revamp (w-6ec)
 # Study:      —
-# Ask:        a-6ec "tagline AB"
+# Ask:        tagline AB (a-6ec)
+# Chat ep:    —
 # Home:       /home/you/.ish
 # API:        https://api.ishlabs.io
 \`\`\`
@@ -2439,12 +2747,13 @@ JSON shape (\`ish status --json\` or piped):
 
 \`\`\`json
 {
-  "user":      { "email": "...", "token_valid": true, "expires_in_seconds": 2820 },
-  "workspace": { "id": "...", "alias": "w-6ec", "name": "Onboarding revamp" },
-  "study":     null,
-  "ask":       { "id": "...", "alias": "a-6ec", "name": "tagline AB" },
-  "api_url":   "https://api.ishlabs.io",
-  "home":      "/home/you/.ish"
+  "user":          { "email": "...", "token_valid": true, "expires_in_seconds": 2820 },
+  "workspace":     { "id": "...", "alias": "w-6ec", "name": "Onboarding revamp" },
+  "study":         null,
+  "ask":           { "id": "...", "alias": "a-6ec", "name": "tagline AB" },
+  "chat_endpoint": null,
+  "api_url":       "https://api.ishlabs.io",
+  "home":          "/home/you/.ish"
 }
 \`\`\`
 
@@ -2453,19 +2762,83 @@ JSON shape (\`ish status --json\` or piped):
 \`ish login\`. Safe to run unconditionally at the start of any
 script or agent session.
 
+### \`ish login\` is idempotent
+
+When you already have a valid saved token, \`ish login\` short-circuits
+with a friendly "Already logged in" message and **does not** open a new
+browser tab or register a fresh OAuth client. Use \`--force\` (or \`-f\`)
+to bypass the guard — typical reason is switching accounts.
+
+\`\`\`bash
+ish login              # no-op when already authenticated
+ish login --force      # always re-run the browser flow
+\`\`\`
+
+The short-circuit returns a structured envelope under \`--json\`:
+
+\`\`\`json
+{
+  "message": "Already logged in",
+  "email": "you@example.com",
+  "token_valid": true,
+  "expires_in_seconds": 2820,
+  "hint": "Pass --force to re-run the browser flow (e.g. to switch accounts)."
+}
+\`\`\`
+
+### Orphan / stale active refs
+
+If an active ref points at an entity that no longer exists or moved
+workspace, \`status\` surfaces a \`warning\` field on that ref (instead
+of silently dropping the \`name\`). Each warned ref also gets a \`hint\`
+field with the exact command to clear or replace it:
+
+\`\`\`json
+{
+  "study": {
+    "id": "...",
+    "alias": "s-74d",
+    "warning": "orphan — entity no longer exists in this workspace",
+    "hint": "Active study is no longer accessible (deleted, moved workspace, or auth issue). Use \`ish study use <id>\` to switch, or \`ish study use --clear\` to drop."
+  }
+}
+\`\`\`
+
+In human output the warning prints as \`⚠ ...\` under the row and a
+follow-up line shows the hint.
+
 ## Setting / clearing active context
 
 \`\`\`bash
-ish workspace use w-6ec        # set
-ish workspace use --clear      # clear
+ish workspace use w-6ec        # set (also clears active study/ask/chat_endpoint if workspace changed)
+ish workspace use --clear      # clear workspace + all workspace-scoped children
 
 ish study use s-b2c
 ish study use --clear
 
 ish ask use a-6ec
 ish ask use --clear
+
+ish chat endpoint use ep-abc
+ish chat endpoint use --clear
 \`\`\`
 
+### Auto-activation on create
+
+\`ish study create\`, \`ish ask create\`, and \`ish workspace use\` all
+update the active context as a side-effect (so the natural next command
+— \`ish iteration create --study <new>\`, \`ish ask add-round\`, etc. —
+"just works" without re-typing the ID). The CLI **emits a one-line
+stderr notice** when this happens; consumers piping stdout get the new
+record while the auto-activate is visible to operators.
+
+### Cleanup on delete
+
+\`ish workspace delete\`, \`ish study delete\`, \`ish ask delete\`, and
+\`ish chat endpoint delete\` automatically clear matching active refs
+from \`~/.ish/config.json\` so subsequent commands don't render orphans.
+\`workspace delete\` also clears all workspace-scoped children.
+
 ## Overriding without persisting
 
 Every read command accepts \`--workspace <id>\`, \`--study <id>\`, or
@@ -3863,6 +4236,12 @@ const PAGES = [
         description: "Login → workspace → people → study → iteration → run → results.",
         body: GUIDE_FIRST_STUDY,
     },
+    {
+        slug: "guides/slicing-results",
+        title: "guide: slicing study results by frame / segment / turn / sentiment",
+        description: "Filter and project `ish study results` — --frame, --segment, --turn, --side, --assignment, --step, --sentiment, --actor, --iteration, --participant; --group-by iteration|frame|segment|turn|assignment|step; totals_unfiltered + empty-slice contract.",
+        body: GUIDE_SLICING_RESULTS,
+    },
     {
         slug: "guides/chat",
         title: "guide: chat-modality studies",