@ishlabs/cli 0.19.0 → 0.20.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
@@ -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
 
 \`\`\`
@@ -2254,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
@@ -2294,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.
@@ -2411,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
@@ -2430,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
 \`\`\`
@@ -2439,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"
 }
 \`\`\`
 
@@ -2453,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

package/dist/lib/output.js

@@ -224,7 +224,11 @@ function wrapList(items, existing, opts = {}) {
     const limit = typeof existing?.limit === "number" ? existing.limit : returned;
     const offset = typeof existing?.offset === "number" ? existing.offset : 0;
     const has_more = total > offset + returned;
-    const leanItems = _verbose || opts.preProjectedItems
+    // ISSUE-031: if the user explicitly named fields via --fields or --get,
+    // skip the per-item lean-strip so the requested fields actually survive
+    // to the output. Otherwise `--fields id,alias` silently drops `id`.
+    const userSpecifiedFields = (_fields && _fields.length > 0) || (typeof _getField === "string" && _getField.length > 0);
+    const leanItems = _verbose || opts.preProjectedItems || userSpecifiedFields
         ? items
         : leanJson(items) ?? [];
     return { items: leanItems, total, returned, limit, offset, has_more };
@@ -277,9 +281,16 @@ function pickFields(data, fields) {
 /** Serialize data as JSON, applying lean transform and field selection. */
 function jsonOutput(data, options = {}) {
     let out;
-    if (_verbose || options.preProjected) {
-        // Verbose: full payload. preProjected: caller already chose the fields,
-        // so don't strip again (otherwise leanJson would drop e.g. created_at).
+    // ISSUE-031: when the user explicitly names fields via --fields or
+    // --get, their request takes precedence over the default lean-strip.
+    // Previously --fields id,alias would silently drop `id` because
+    // leanJson ran first and stripped UUID-valued fields. The user
+    // asking for a field is unambiguous intent — bypass the strip.
+    const userSpecifiedFields = (_fields && _fields.length > 0) || (typeof _getField === "string" && _getField.length > 0);
+    if (_verbose || options.preProjected || userSpecifiedFields) {
+        // Verbose: full payload. preProjected: caller already chose the fields.
+        // userSpecifiedFields: caller said exactly what they want — don't
+        // second-guess by stripping UUIDs they asked for.
         out = data;
     }
     else {
@@ -461,6 +472,29 @@ function suggestionsForError(err) {
     }
     return [];
 }
+/**
+ * Pattern F (ISSUE-023): rewrite server-side internal entity names to the
+ * user-facing CLI surface names so messages like "Product not found" don't
+ * leak the backend's internal vocabulary to a first-time CLI user.
+ *
+ * Mapping reflects the rename audit: server still calls workspaces
+ * "products" and people "profiles" / "tester profiles" in some response
+ * messages; the CLI surface is `workspace` / `person`. Source is
+ * `attachment` server-side.
+ *
+ * Word-boundary anchored to avoid touching e.g. "productivity" or
+ * "Attachments must be ..." (the latter is genuinely about attachments).
+ */
+function remapEntityName(message) {
+    return message
+        .replace(/\bProduct not found\b/g, "Workspace not found")
+        .replace(/\bproduct not found\b/g, "workspace not found")
+        .replace(/\bTester [Pp]rofile not found\b/g, (m) => m.includes("P") ? "Person not found" : "person not found")
+        .replace(/\bProfile not found\b/g, "Person not found")
+        .replace(/\bprofile not found\b/g, "person not found")
+        .replace(/\bAttachment not found\b/g, "Source not found")
+        .replace(/\battachment not found\b/g, "source not found");
+}
 export function outputError(err, json) {
     const suggestions = suggestionsForError(err);
     if (err instanceof ApiError) {
@@ -505,7 +539,7 @@ export function outputError(err, json) {
             : undefined;
         if (json) {
             console.error(JSON.stringify({
-                error: err.message,
+                error: remapEntityName(err.message),
                 error_code: err.error_code,
                 status: err.status,
                 retryable: err.retryable,
@@ -527,7 +561,7 @@ export function outputError(err, json) {
                 console.error("Error: Insufficient credits. Purchase more at https://app.ishlabs.io");
             }
             else {
-                console.error(`Error: ${err.message}`);
+                console.error(`Error: ${remapEntityName(err.message)}`);
             }
             if (Array.isArray(bodyErrors)) {
                 for (const entry of bodyErrors) {
@@ -549,6 +583,12 @@ export function outputError(err, json) {
     else if (err instanceof ValidationError) {
         if (json) {
             console.error(JSON.stringify({
+                // ValidationError is CLI-thrown (we control its message), so we
+                // don't apply remapEntityName — that helper exists to translate
+                // server-side internal vocabulary ("Product"/"Profile"/"Attachment")
+                // back to user-facing names. Applying it here risks mangling
+                // user-supplied content (e.g. a workspace name containing "Profile
+                // not found"). Restrict the remap to the ApiError branch.
                 error: err.message,
                 error_code: "validation_error",
                 retryable: false,
@@ -597,6 +637,10 @@ export function outputError(err, json) {
         const mergedSuggestions = [...new Set([...suggestions, ...taggedSuggestions])];
         if (json) {
             console.error(JSON.stringify({
+                // Generic Error: CLI-thrown (we control the message), so we don't
+                // apply remapEntityName — see ValidationError branch above for the
+                // same reasoning. Server-side names only leak through the ApiError
+                // branch where remapEntityName IS applied.
                 error: err.message,
                 error_code: errorCode,
                 retryable,
@@ -702,7 +746,7 @@ export function formatWorkspaceList(workspaces, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.workspace);
-    printTable(["#", "NAME", "ROOM", "STUDIES", "ASKS", "PARTICIPANTS", "LAST ACTIVITY"], workspaces.map((w) => [
+    printTable(["ALIAS", "NAME", "ROOM", "STUDIES", "ASKS", "PARTICIPANTS", "LAST ACTIVITY"], workspaces.map((w) => [
         aliasMap.get(String(w.id)) || String(w.id || ""),
         String(w.name || ""),
         formatHeadroom(w.has_headroom),
@@ -784,7 +828,7 @@ export function formatStudyList(studies, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.study);
-    printTable(["#", "NAME", "MODALITY", "TYPE", "STATUS", "PARTICIPANTS"], studies.map((s) => [
+    printTable(["ALIAS", "NAME", "MODALITY", "TYPE", "STATUS", "PARTICIPANTS"], studies.map((s) => [
         aliasMap.get(String(s.id)) || String(s.id || ""),
         String(s.name || ""),
         String(s.modality || "-"),
@@ -934,7 +978,7 @@ export function formatStudyDetail(study, json, options = {}, participants) {
     const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
     if (allParticipants.length > 0) {
         console.log(`\nParticipants (${allParticipants.length}):`);
-        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS"], allParticipants.map((t) => [
+        printTable(["ALIAS", "NAME", "ITERATION", "STATUS", "INTERACTIONS"], allParticipants.map((t) => [
             t.id ? deterministicAlias(ALIAS_PREFIX.participant, t.id) : t.id,
             t.name,
             t.iterationLabel,
@@ -1074,7 +1118,7 @@ export function formatStudyResults(study, participants, json) {
     // Participants table
     if (allParticipants.length > 0) {
         console.log("\nParticipants:");
-        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS", "SENTIMENT"], allParticipants.map((t) => {
+        printTable(["ALIAS", "NAME", "ITERATION", "STATUS", "INTERACTIONS", "SENTIMENT"], allParticipants.map((t) => {
             const parts = Object.entries(t.sentimentCounts).map(([label, count]) => `${count} ${label.toLowerCase()}`);
             return [
                 t.id ? deterministicAlias(ALIAS_PREFIX.participant, t.id) : t.id,
@@ -1375,7 +1419,7 @@ export function formatIterationList(iterations, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.iteration);
-    printTable(["#", "LABEL", "NAME", "PARTICIPANTS", "CREATED"], iterations.map((it) => {
+    printTable(["ALIAS", "LABEL", "NAME", "PARTICIPANTS", "CREATED"], iterations.map((it) => {
         const participants = Array.isArray(it.participants) ? it.participants.length : 0;
         return [
             aliasMap.get(String(it.id)) || String(it.id || ""),
@@ -1449,7 +1493,7 @@ export function formatPersonList(profiles, json, limit) {
         console.log("No participant profiles.");
         return;
     }
-    printTable(["#", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
+    printTable(["ALIAS", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
         String(p.alias || p.id || ""),
         String(p.name || ""),
         String(p.occupation || "-"),
@@ -1504,7 +1548,7 @@ export function formatGeneratedProfileList(profiles, json) {
         console.log(jsonOutput(list));
         return;
     }
-    printTable(["#", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
+    printTable(["ALIAS", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
         String(p.alias || p.id || ""),
         String(p.name || ""),
         String(p.occupation || "-"),
@@ -1529,7 +1573,7 @@ export function formatSimulationPoll(results, json, isMedia = false) {
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.participant);
     const countHeader = isMedia ? "SEGMENTS" : "INTERACTIONS";
-    printTable(["#", "PARTICIPANT", "STATUS", countHeader], results.map((r) => {
+    printTable(["ALIAS", "PARTICIPANT", "STATUS", countHeader], results.map((r) => {
         const id = String(r.id || r.participant_id || "");
         return [
             aliasMap.get(id) || id,
@@ -1574,7 +1618,7 @@ export function formatAskList(asks, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.ask);
-    printTable(["#", "NAME", "STATUS", "PARTICIPANTS", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
+    printTable(["ALIAS", "NAME", "STATUS", "PARTICIPANTS", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
         aliasMap.get(String(a.id)) || String(a.id || ""),
         String(a.name || ""),
         String(a.status || "-"),
@@ -1675,7 +1719,7 @@ export function formatAskDetail(ask, json) {
                 String(obj.status || "-"),
             ];
         });
-        printTable(["#", "NAME", "STATUS"], rows);
+        printTable(["ALIAS", "NAME", "STATUS"], rows);
         if (participants.length > 20)
             console.log(`  … and ${participants.length - 20} more`);
     }
@@ -2145,7 +2189,7 @@ export function formatConfigList(configs, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.config);
-    printTable(["#", "NAME", "SOURCE", "CREATED"], configs.map((c) => [
+    printTable(["ALIAS", "NAME", "SOURCE", "CREATED"], configs.map((c) => [
         aliasMap.get(String(c.id)) || String(c.id || ""),
         String(c.name || ""),
         String(c.source_type || "manual"),