@ishlabs/cli 0.18.0 → 0.20.0

package/dist/lib/baggage.js

@@ -2,10 +2,11 @@
  * Helpers for setting OTel Baggage entries and propagating them on
  * outbound fetches.
  *
- * The CLI carries three baggage entries on every backend call so the
- * backend can attribute spans + Sentry events to the right surface:
+ * The CLI carries four baggage entries on every backend call so the
+ * backend can attribute spans + Sentry events to the right surface and,
+ * when the command is workspace-scoped, the right workspace:
  *
- *     baggage: client.name=ish-cli,client.surface=<command>,client.version=<x.y.z>
+ *     baggage: client.name=ish-cli,client.surface=<command>,client.version=<x.y.z>[,workspace_id=<uuid>]
  *
  * In Node mode, `@opentelemetry/instrumentation-undici` will inject the
  * active baggage onto outbound `fetch` automatically once
@@ -25,13 +26,15 @@ export const BAGGAGE_KEY_CLIENT_NAME = "client.name";
 export const BAGGAGE_KEY_CLIENT_SURFACE = "client.surface";
 export const BAGGAGE_KEY_CLIENT_VERSION = "client.version";
 export const BAGGAGE_KEY_CONSENT_ANALYTICS = "consent.analytics";
+export const BAGGAGE_KEY_WORKSPACE_ID = "workspace_id";
 /** The fixed ``client.name`` we tag every CLI invocation with. The plan
  * pins this string — backend dashboards filter on it. */
 export const CLIENT_NAME = "ish-cli";
 /**
  * Stamp the active OTel baggage with ``client.name`` / ``client.surface``
- * / ``client.version`` and stash a process-local copy for the
- * manual-injection ``withBaggage`` helper.
+ * / ``client.version`` (always) and ``workspace_id`` (when the command
+ * carries one), then stash a process-local copy for the manual-injection
+ * ``withBaggage`` helper.
  *
  * Idempotent — subsequent calls overwrite the previous surface, which is
  * what we want when Commander invokes ``preAction`` once per resolved
@@ -51,17 +54,20 @@ export const CLIENT_NAME = "ish-cli";
  * Safe to call even with no OTel SDK registered — `@opentelemetry/api`
  * ships no-op fallbacks.
  */
-export function setSurfaceBaggage(commandName) {
+export function setSurfaceBaggage(input) {
     const existing = propagation.getActiveBaggage() ?? propagation.createBaggage();
-    const next = existing
+    let next = existing
         .setEntry(BAGGAGE_KEY_CLIENT_NAME, { value: CLIENT_NAME })
-        .setEntry(BAGGAGE_KEY_CLIENT_SURFACE, { value: commandName })
+        .setEntry(BAGGAGE_KEY_CLIENT_SURFACE, { value: input.surface })
         .setEntry(BAGGAGE_KEY_CLIENT_VERSION, { value: pkg.version })
         // CLI runs on a developer's machine with no client-side consent UI.
         // Emit "unknown" so the backend resolver falls through to the
         // authenticated user's persisted consent rather than default-denying
         // via baggage absence.
         .setEntry(BAGGAGE_KEY_CONSENT_ANALYTICS, { value: "unknown" });
+    if (input.workspaceId) {
+        next = next.setEntry(BAGGAGE_KEY_WORKSPACE_ID, { value: input.workspaceId });
+    }
     _activeBaggage = next;
 }
 /** Process-local copy of the active baggage for the manual-injection path.

package/dist/lib/command-helpers.d.ts

@@ -23,6 +23,7 @@ export interface PersonResolveOpts {
     /** Profile IDs to exclude from the fetched pool (e.g. participants already on an ask). */
     excludeProfileIds?: Set<string>;
 }
+export declare function normalizeVisibility(raw: string | undefined): string | undefined;
 /** True when any person-selection flag is set on the command. */
 export declare function hasPersonFlags(flags: PersonFilterOpts): boolean;
 /**

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
@@ -1083,12 +1102,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 \`n_participants * (1 + len(questions))\` credits per round; \`questions\` follow-ups bill *per participant* on top of the base response, so a 3-person panel with 2 follow-up questions costs \`3 * (1 + 2) = 9\` credits when all complete (not 3).
 `;
 const CONCEPT_ROUND = `# concept: round
 
@@ -1261,6 +1300,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 +1357,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 +1477,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
 
 \`\`\`
@@ -2059,6 +2155,15 @@ The CLI guarantees these contracts so agents can chain safely:
   sentiment histogram + per-participant {alias, status, sentiment, comment,
   error_message}. Drops \`interview_answers\` and per-interaction
   breakdowns. Cheapest "did this run land?" shape.
+- **\`study get --json\` carries a flat top-level \`participants[]\`**
+  (post backend-split). Each row carries \`iteration_id\` as a
+  discriminator and the per-participant graph
+  (\`person\`, \`interactions[]\`, \`participant_summary\`,
+  \`interview_answers\`, \`conversation_id\`, …). The previous nesting
+  under \`iterations[*].participants[*]\` is gone — read participants from
+  the top level. The lite iteration list under \`iterations[]\` still
+  carries each iteration's \`details\` and (for pair-mode chat) the
+  conversation refs at \`iterations[*].conversations[]\`.
 - **\`study get --json\` carries assignment step completion** when an
   assignment has a checklist (see \`concepts/assignment\`). Each
   \`assignments[].step_completion[]\` row is
@@ -2245,17 +2350,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
@@ -2285,6 +2406,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.
@@ -2402,13 +2529,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
@@ -2421,7 +2554,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
 \`\`\`
@@ -2430,12 +2564,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"
 }
 \`\`\`
 
@@ -2444,19 +2579,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
@@ -3079,7 +3278,7 @@ ish study run stu-xyz --sample 5 --wait
 
 Pull raw interactions:
 \`\`\`
-ish study results stu-xyz --json | jq '.interactions'
+ish study results stu-xyz --json | jq '.participants[].interactions'
 \`\`\`
 
 Note: chat is currently excluded from the LLM-analysis route; the

package/dist/lib/output.d.ts

@@ -47,15 +47,15 @@ export declare function formatWorkspaceList(workspaces: Record<string, unknown>[
 export declare function formatWorkspaceDetail(workspace: Record<string, unknown>, json: boolean, options?: OutputOptions): void;
 export declare function formatSiteAccessStatus(summary: import("./site-access.js").SiteAccessSummary, json: boolean): void;
 export declare function formatStudyList(studies: Record<string, unknown>[], json: boolean): void;
-export declare function formatStudyDetail(study: Record<string, unknown>, json: boolean, options?: OutputOptions): void;
-export declare function formatStudyResults(study: Record<string, unknown>, json: boolean): void;
+export declare function formatStudyDetail(study: Record<string, unknown>, json: boolean, options?: OutputOptions, participants?: ReadonlyArray<Record<string, unknown>>): void;
+export declare function formatStudyResults(study: Record<string, unknown>, participants: ReadonlyArray<Record<string, unknown>>, json: boolean): void;
 /**
  * `study results --summary` projection. Drops interview_answers + per-participant
  * interaction breakdowns; keeps headline counters, sentiment histogram, and a
  * per-participant {alias, status, sentiment, comment} row. Useful for agents that
  * need to branch on outcome without paying for the full envelope.
  */
-export declare function buildStudyResultsSummary(study: Record<string, unknown>): Record<string, unknown>;
+export declare function buildStudyResultsSummary(study: Record<string, unknown>, participants: ReadonlyArray<Record<string, unknown>>): Record<string, unknown>;
 /**
  * `study results --transcript <participant_id>` projection. Mirrors the schema
  * MCP's `get_chat_transcript` returns (`src/ish_mcp/projections.py: