@ishlabs/cli 0.15.0 → 0.17.0

package/README.md

@@ -308,6 +308,16 @@ ish ask run --new --name "newsletter" \
 
 **Audience flags** (`--profile`, `--sample`, `--all-simulatable`, `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`, `--name`, `--description`, `--workspace`) only apply with `--new` — the audience is fixed at ask creation.
 
+**`--visibility` values** (same set everywhere it's accepted):
+
+| Value | Selects |
+|---|---|
+| `workspace` | Profiles owned by your workspace (default scope). |
+| `shared` | Community-published profiles visible across workspaces. |
+| `platform` | Admin-curated profiles from the platform pool. |
+
+Old values `private` (now `workspace`) and `public` (now `platform`) keep working until the next release; the server logs a deprecation warning and maps them to the new vocabulary.
+
 **Other ask verbs:**
 
 ```bash

package/dist/commands/ask.js

@@ -19,6 +19,8 @@ function audienceFlags(opts) {
         sample: opts.sample,
         all: opts.allSimulatable,
         search: opts.search,
+        bio: opts.bio,
+        occupation: opts.occupation,
         gender: opts.gender,
         country: opts.country,
         minAge: opts.minAge,

package/dist/commands/profile.js

@@ -30,7 +30,9 @@ Concept pages: ish docs get-page concepts/profile
         .command("list")
         .description("List profiles (defaults to simulatable AI profiles)")
         .option("--workspace <id>", "Filter by workspace ID")
-        .option("--search <query>", "Free-text search (matches profile name and bio)")
+        .option("--search <query>", "Substring match against profile name")
+        .option("--bio <text>", "Substring match against profile bio")
+        .option("--occupation <text>", "Substring match against profile occupation (repeatable)", collect, [])
         .option("--type <type>", "Profile type: ai, human, all (default: ai)", "ai")
         .option("--gender <gender>", "Filter by gender (repeatable)", collect, [])
         .option("--country <country>", "Filter by country code, e.g. US (repeatable)", collect, [])
@@ -42,10 +44,12 @@ Concept pages: ish docs get-page concepts/profile
 Examples:
   $ ish profile list
   $ ish profile list --search "engineer" --country US
+  $ ish profile list --bio "voice-first user"
+  $ ish profile list --occupation founder --occupation designer
   $ ish profile list --gender female --gender male --country US --country GB
   $ ish profile list --type all --json
 
-  # Pagination — default --limit is 50; iterate with --offset:
+  # Pagination: default --limit is 50, iterate with --offset.
   $ ish profile list --limit 100
   $ ish profile list --limit 100 --offset 100   # next page
   # When more results exist, a stderr hint surfaces the next --offset / --limit.`)
@@ -58,6 +62,10 @@ Examples:
             };
             if (opts.search)
                 params.search = opts.search;
+            if (opts.bio)
+                params.bio = opts.bio;
+            if (opts.occupation.length > 0)
+                params.occupation = opts.occupation;
             if (opts.type !== "all")
                 params.type = opts.type;
             if (opts.gender.length > 0)

package/dist/commands/study-run.js

@@ -11,6 +11,7 @@ import * as readline from "node:readline/promises";
 import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy, parseWaitTimeout, resolveAudienceProfileIds, addAudienceFilterFlags, hasAudienceFlags, readFileOrStdin, } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatSimulationPoll } from "../lib/output.js";
+import { streamStudyEvents } from "../lib/study-events.js";
 import { isMediaModality, isChatModality, iterationHasContent, describeRequiredContentFlag, readChatMode, readTesterPairConfig, summarizeRoleCriteria, } from "../lib/modality.js";
 import { runLocalSimulations } from "../lib/local-sim/loop.js";
 import { ensureBrowser } from "../lib/local-sim/install.js";
@@ -93,6 +94,11 @@ function dedupeSimulations(simResults) {
     ];
 }
 const POLL_INTERVAL_MS = 5_000;
+// When the backend SSE stream is connected we drop to a slow backstop —
+// events wake us up promptly, so re-fetching every 5s is wasteful. If the
+// stream dies (older backend, broker offline, token mint failure) the loop
+// transparently reverts to POLL_INTERVAL_MS.
+const SSE_BACKSTOP_INTERVAL_MS = 30_000;
 const TERMINAL_STATUSES = new Set(["completed", "errored", "failed", "cancelled", "canceled"]);
 function flattenTesterStatuses(iterations, only) {
     const rows = [];
@@ -118,38 +124,90 @@ function flattenTesterStatuses(iterations, only) {
 async function pollStudyUntilDone(client, opts) {
     const start = Date.now();
     let lastReported = "";
-    while (true) {
-        const study = await client.get(`/studies/${opts.studyId}`, undefined, { timeout: 60_000 });
-        const isMedia = isMediaModality(study.modality);
-        let iterations = study.iterations;
-        if (opts.iterationId) {
-            iterations = (iterations ?? []).filter((it) => it.id === opts.iterationId);
-        }
-        const rows = flattenTesterStatuses(iterations, opts.testerIds);
-        const total = rows.length;
-        const done = rows.filter((r) => TERMINAL_STATUSES.has(r.status)).length;
-        const errored = rows.filter((r) => r.status === "errored" || r.status === "failed").length;
-        const summary = `${done}/${total} done${errored > 0 ? `, ${errored} errored/failed` : ""}`;
-        if (!opts.quiet && summary !== lastReported) {
-            process.stderr.write(`  ${summary}\n`);
-            lastReported = summary;
-        }
-        if (total > 0 && done === total) {
-            return { rows, isMedia };
-        }
-        if (Date.now() - start > opts.timeoutMs) {
-            throw new WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for simulations. ` +
-                `${done}/${total} done. Run \`ish study poll --study ${opts.studyId}\` to check status.`, {
-                study_id: opts.studyId,
-                ...(opts.iterationId && { iteration_id: opts.iterationId }),
-                timeout_seconds: Math.round(opts.timeoutMs / 1000),
-                done,
-                total,
-                pending: total - done,
-                rows,
-            });
+    // Open the SSE event stream as a wake source. When the backend supports
+    // it (enable_realtime=true + broker live), tester status changes wake
+    // the loop the moment they happen — no need to wait for the next poll
+    // tick. When it doesn't, the iterator exits silently on the first read
+    // and we fall through to pure polling at POLL_INTERVAL_MS.
+    const ac = new AbortController();
+    const eventIter = streamStudyEvents(client, opts.studyId, ac.signal);
+    // Optimistic: we assume the stream will deliver until the first read
+    // confirms otherwise. The first `await pendingEvent` settles within
+    // milliseconds for an unavailable stream (token mint 503 / endpoint 503)
+    // and is essentially a no-op for the latency budget.
+    let sseAlive = true;
+    let pendingEvent = eventIter.next();
+    try {
+        while (true) {
+            const study = await client.get(`/studies/${opts.studyId}`, undefined, { timeout: 60_000 });
+            const isMedia = isMediaModality(study.modality);
+            let iterations = study.iterations;
+            if (opts.iterationId) {
+                iterations = (iterations ?? []).filter((it) => it.id === opts.iterationId);
+            }
+            const rows = flattenTesterStatuses(iterations, opts.testerIds);
+            const total = rows.length;
+            const done = rows.filter((r) => TERMINAL_STATUSES.has(r.status)).length;
+            const errored = rows.filter((r) => r.status === "errored" || r.status === "failed").length;
+            const summary = `${done}/${total} done${errored > 0 ? `, ${errored} errored/failed` : ""}`;
+            if (!opts.quiet && summary !== lastReported) {
+                process.stderr.write(`  ${summary}\n`);
+                lastReported = summary;
+            }
+            if (total > 0 && done === total) {
+                return { rows, isMedia };
+            }
+            if (Date.now() - start > opts.timeoutMs) {
+                throw new WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for simulations. ` +
+                    `${done}/${total} done. Run \`ish study poll --study ${opts.studyId}\` to check status.`, {
+                    study_id: opts.studyId,
+                    ...(opts.iterationId && { iteration_id: opts.iterationId }),
+                    timeout_seconds: Math.round(opts.timeoutMs / 1000),
+                    done,
+                    total,
+                    pending: total - done,
+                    rows,
+                });
+            }
+            // Wait for either the next backend event or the next tick. Use the
+            // backstop interval while the stream is delivering (events are the
+            // primary wake source); fall back to POLL_INTERVAL_MS once the
+            // stream is dead (older backend or broker dropped mid-run).
+            const interval = sseAlive ? SSE_BACKSTOP_INTERVAL_MS : POLL_INTERVAL_MS;
+            if (sseAlive && pendingEvent !== null) {
+                let timerHandle;
+                const timer = new Promise((resolve) => {
+                    timerHandle = setTimeout(() => resolve({ kind: "timer" }), interval);
+                });
+                const eventOrEnd = pendingEvent.then((r) => ({ kind: "event", result: r }), () => ({ kind: "event", result: { value: undefined, done: true } }));
+                const winner = await Promise.race([eventOrEnd, timer]);
+                if (timerHandle !== undefined)
+                    clearTimeout(timerHandle);
+                if (winner.kind === "event") {
+                    if (winner.result.done) {
+                        // Stream ended; revert to pure polling for the rest of the run.
+                        sseAlive = false;
+                        pendingEvent = null;
+                    }
+                    else {
+                        // Re-arm for the next event. We deliberately don't act on
+                        // the event payload here — the next loop iteration re-fetches
+                        // status and that's the truth source.
+                        pendingEvent = eventIter.next();
+                    }
+                }
+                // Timer winning doesn't replace pendingEvent — it stays parked
+                // and resolves on whichever event arrives next.
+            }
+            else {
+                await new Promise((resolve) => setTimeout(resolve, interval));
+            }
         }
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    finally {
+        // Stop the SSE fetch + reader so we don't leave a dangling HTTP
+        // connection to the backend after returning / throwing.
+        ac.abort();
     }
 }
 function readIterationDetails(details) {
@@ -202,9 +260,10 @@ Note: --workspace and --study are optional if you have set active context
   first with \`ish iteration create\`.
 
   Audience: pass nothing to reuse the iteration's existing testers. Pass
-  --profile to use specific profiles, or filter flags (--country, --gender,
-  --min-age, --max-age, --search, --visibility) with --sample <N> or --all
-  to seed a fresh audience from the workspace pool.
+  --profile to use specific profiles, or filter flags (--bio, --country,
+  --gender, --min-age, --max-age, --occupation, --search, --visibility)
+  with --sample <N> or --all to seed a fresh audience from the workspace
+  pool.
 
 Examples:
   # Run the latest iteration, reusing its testers:
@@ -395,15 +454,22 @@ Examples:
                 throw new Error(`Iteration "${iterationLabel}" has no testers and no audience flags were given. ` +
                     "Pass --profile <ids>, or filter flags (--country, --gender, --min-age, --max-age, --search, --visibility) with --sample <N> or --all.");
             }
-            // Step 3: Resolve simulation config (per-profile fallback for
-            // media + chat external_chatbot, both of which require a config_id
-            // per batch item). Pair-mode chat dispatch is per-conversation,
-            // not per-tester; the backend resolves configs via the tester rows
-            // it creates on /testers/pair-batch, so the CLI doesn't pre-fetch.
+            // Step 3: Resolve simulation config. Always pre-flight every profile
+            // when no --config override is given: missing simulation_config_id
+            // is fatal across all modalities (media + chat batch dispatch use it
+            // per-item; interactive + pair dispatch fail server-side on the
+            // first sim start) and creating tester rows before discovering it
+            // leaves phantom DRAFT rows in the iteration. Pair mode reads
+            // pairConfig.audience_a; non-pair uses profileIds. profileConfigMap
+            // is consumed by the media branch; other branches just need the
+            // validation side effect.
             const resolvedConfigOverride = opts.config ? resolveId(opts.config) : undefined;
             const profileConfigMap = new Map();
-            if ((isMedia || (isChat && !isPair)) && !resolvedConfigOverride) {
-                for (const pid of profileIds) {
+            if (!resolvedConfigOverride) {
+                const idsToCheck = isPair && pairConfig
+                    ? [...new Set([...pairConfig.audience_a, ...pairConfig.audience_b])]
+                    : profileIds;
+                for (const pid of idsToCheck) {
                     const profile = await client.get(`/tester-profiles/${pid}`);
                     if (profile.simulation_config_id) {
                         profileConfigMap.set(pid, profile.simulation_config_id);
@@ -732,18 +798,21 @@ Examples:
                         // Fall back to the first audience_a profile's
                         // simulation_config_id. Pair dispatch takes a single config
                         // for the whole batch, so we don't need the per-profile map
-                        // the external_chatbot path builds.
+                        // the external_chatbot path builds. Step 3 already populated
+                        // profileConfigMap with every audience profile's config when
+                        // --config was not passed, so reuse that.
                         const fallbackProfileId = pairConfig.audience_a[0];
                         if (!fallbackProfileId) {
                             throw new Error("Pair-mode dispatch requires --config <id>: the iteration has no audience profile to draw a default config_id from.");
                         }
-                        const fallbackProfile = await client.get(`/tester-profiles/${fallbackProfileId}`);
-                        if (!fallbackProfile.simulation_config_id) {
+                        pairConfigId = profileConfigMap.get(fallbackProfileId);
+                        if (!pairConfigId) {
+                            // Defensive: Step 3 should have either populated the map or
+                            // thrown. If we land here something upstream changed.
                             throw new Error(`Pair-mode dispatch requires a config_id. Profile ${fallbackProfileId} has no simulation config assigned and --config was not passed.\n` +
                                 "Use --config <id> to specify one, or assign a config to the profile.\n" +
                                 "List configs with: ish config list");
                         }
-                        pairConfigId = fallbackProfile.simulation_config_id;
                     }
                     const simResult = await dispatchAttempt(() => client.post("/simulation/chat/pair/start/batch", {
                         product_id: resolvedWorkspace,

package/dist/commands/workspace.js

@@ -214,11 +214,12 @@ async function collectWorkspaceUsage(client, workspaceId) {
         .get(`/products/${workspaceId}/studies`)
         .catch(() => []);
     // testers_used: paginated list returns { total, items, ... }. Backend
-    // gates `maxCustomTesterProfiles` on visibility=private.
+    // gates `maxCustomTesterProfiles` on visibility=workspace (rows owned by
+    // this workspace; was `private` before the visibility rename).
     const testersPromise = client
         .get("/tester-profiles", {
         product_id: workspaceId,
-        visibility: "private",
+        visibility: "workspace",
         type: "ai",
         limit: "1",
         offset: "0",

package/dist/connect.js

@@ -284,12 +284,14 @@ async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
 // --- Branding ---
 function printBanner() {
     console.log(`
-${c.orange}${c.bold}   ██╗███████╗██╗  ██╗
-   ██║██╔════╝██║  ██║
-   ██║███████╗███████║
-   ██║╚════██║██╔══██║
-   ██║███████║██║  ██║
-   ╚═╝╚══════╝╚═╝  ╚═╝${c.reset}
+${c.orange}${c.bold}    /██           /██
+   |__/          | ██
+    /██  /███████| ███████
+   | ██ /██_____/| ██__  ██
+   | ██|  ██████ | ██  \\ ██
+   | ██ \\____  ██| ██  | ██
+   | ██ /███████/| ██  | ██
+   |__/|_______/ |__/  |__/${c.reset}
 
    Connected
 `);

package/dist/index.js

@@ -30,7 +30,7 @@ import pkg from "../package.json" with { type: "json" };
 const { version } = pkg;
 program
     .name("ish")
-    .description("Ish CLI — run studies and asks against AI tester audiences")
+    .description("ish CLI — run studies and asks against AI tester audiences")
     .version(version)
     .addHelpText("after", AGENT_HELP_FOOTER);
 // Unified error envelope for Commander-level failures (unknown command,

package/dist/lib/api-client.d.ts

@@ -20,6 +20,13 @@ export declare class ApiClient {
         token: string;
     });
     get accessToken(): string;
+    /** Resolved base URL including the ``/api/v1`` prefix.
+     *
+     * Exposed so helpers that bypass the JSON-decoding ``fetch`` wrappers
+     * (e.g. the SSE stream in ``lib/study-events.ts``) can build their own
+     * requests against the same backend.
+     */
+    get apiBase(): string;
     private headers;
     get<T = unknown>(path: string, params?: Record<string, string | string[]>, opts?: RequestOpts): Promise<T>;
     post<T = unknown>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;

package/dist/lib/api-client.js

@@ -83,6 +83,15 @@ export class ApiClient {
     get accessToken() {
         return this.token;
     }
+    /** Resolved base URL including the ``/api/v1`` prefix.
+     *
+     * Exposed so helpers that bypass the JSON-decoding ``fetch`` wrappers
+     * (e.g. the SSE stream in ``lib/study-events.ts``) can build their own
+     * requests against the same backend.
+     */
+    get apiBase() {
+        return this.baseUrl;
+    }
     headers() {
         return {
             Authorization: `Bearer ${this.token}`,

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

@@ -9,6 +9,8 @@ export interface AudienceFilterOpts {
     sample?: string;
     all?: boolean;
     search?: string;
+    bio?: string;
+    occupation?: string[];
     gender?: string[];
     country?: string[];
     minAge?: string;

package/dist/lib/command-helpers.js

@@ -33,6 +33,10 @@ function describeFilters(flags) {
     const parts = [];
     if (flags.search)
         parts.push(`--search "${flags.search}"`);
+    if (flags.bio)
+        parts.push(`--bio "${flags.bio}"`);
+    if (flags.occupation?.length)
+        parts.push(...flags.occupation.map((o) => `--occupation ${o}`));
     if (flags.gender?.length)
         parts.push(...flags.gender.map((g) => `--gender ${g}`));
     if (flags.country?.length)
@@ -75,6 +79,10 @@ async function suggestCountries(client, workspace, flags, opts) {
             if (keepOtherFilters) {
                 if (flags.search)
                     broader.search = flags.search;
+                if (flags.bio)
+                    broader.bio = flags.bio;
+                if (flags.occupation && flags.occupation.length > 0)
+                    broader.occupation = flags.occupation;
                 if (flags.gender && flags.gender.length > 0)
                     broader.gender = flags.gender;
                 if (flags.minAge)
@@ -118,6 +126,8 @@ async function suggestCountries(client, workspace, flags, opts) {
 }
 function hasFilterFlag(flags) {
     return Boolean(flags.search
+        || flags.bio
+        || (flags.occupation && flags.occupation.length > 0)
         || (flags.gender && flags.gender.length > 0)
         || (flags.country && flags.country.length > 0)
         || flags.minAge
@@ -153,7 +163,7 @@ export async function resolveAudienceProfileIds(client, workspace, flags, opts =
     const filtersUsed = hasFilterFlag(flags);
     if (explicit.length > 0) {
         if (sampleN !== undefined || flags.all || filtersUsed) {
-            throw new Error(`Use either explicit --profile flags or --sample/${allFlagName}/filter flags (--country, --gender, --min-age, --max-age, --search, --visibility), not both.`);
+            throw new Error(`Use either explicit --profile flags or --sample/${allFlagName}/filter flags (--bio, --country, --gender, --min-age, --max-age, --occupation, --search, --visibility), not both.`);
         }
         return explicit;
     }
@@ -161,7 +171,7 @@ export async function resolveAudienceProfileIds(client, workspace, flags, opts =
         throw new Error(`Use either --sample <N> or ${allFlagName}, not both. --sample picks a random subset; ${allFlagName} returns every match.`);
     }
     if (sampleN === undefined && !flags.all && !filtersUsed) {
-        throw new Error(`Pick an audience: pass --profile <id> (repeatable), --sample <N>, ${allFlagName}, or filter flags (--country, --gender, --min-age, --max-age, --search, --visibility).`);
+        throw new Error(`Pick an audience: pass --profile <id> (repeatable), --sample <N>, ${allFlagName}, or filter flags (--bio, --country, --gender, --min-age, --max-age, --occupation, --search, --visibility).`);
     }
     const params = {
         product_id: workspace,
@@ -171,6 +181,10 @@ export async function resolveAudienceProfileIds(client, workspace, flags, opts =
     };
     if (flags.search)
         params.search = flags.search;
+    if (flags.bio)
+        params.bio = flags.bio;
+    if (flags.occupation && flags.occupation.length > 0)
+        params.occupation = flags.occupation;
     if (flags.gender && flags.gender.length > 0)
         params.gender = flags.gender;
     if (flags.country && flags.country.length > 0)
@@ -240,12 +254,14 @@ export function addAudienceFilterFlags(cmd, opts = {}) {
         .option("--profile <ids>", "Tester profile IDs/aliases (comma-separated or repeatable)", collectIds, [])
         .option("--sample <N>", "Randomly sample N profiles from the matching pool")
         .option(allFlag, allDesc)
-        .option("--search <text>", "Free-text search (matches profile name and bio)")
+        .option("--search <text>", "Substring match against profile name")
+        .option("--bio <text>", "Substring match against profile bio")
+        .option("--occupation <text>", "Substring match against profile occupation (repeatable)", collectRepeatable, [])
         .option("--gender <gender>", "Filter by gender (repeatable)", collectRepeatable, [])
         .option("--country <code>", "Filter by 2-letter country code (repeatable)", collectRepeatable, [])
         .option("--min-age <n>", "Minimum age (inclusive)")
         .option("--max-age <n>", "Maximum age (inclusive)")
-        .option("--visibility <v>", "Filter by visibility (private|public)");
+        .option("--visibility <v>", "Filter by visibility: workspace (your workspace), shared (community-published), platform (admin-curated). Old values `private` / `public` still accepted as aliases for `workspace` / `platform` until the next release; server logs a deprecation warning.");
 }
 export function getGlobals(cmd) {
     let globals;

package/dist/lib/docs.js

@@ -1267,8 +1267,15 @@ flags. Two ways to select:
    - \`--gender female\`  (repeatable)
    - \`--min-age 25\`
    - \`--max-age 50\`
-   - \`--search "early adopter"\`
-   - \`--visibility shared|private\`
+   - \`--search "Anna"\`  (substring match against profile name)
+   - \`--bio "voice-first user"\`  (substring match against profile bio)
+   - \`--occupation founder\`  (substring match against profile occupation; repeatable, OR semantics)
+   - \`--visibility workspace|shared|platform\` (filter by where the
+     profile lives: your workspace, the community-published pool, or
+     the admin-curated platform pool; old values \`private\` /
+     \`public\` still accepted as aliases for \`workspace\` /
+     \`platform\` until the next release with a server-side
+     deprecation warning)
 
 The two modes are **mutually exclusive** — pass either \`--profile\` or
 the filter set, not both.
@@ -1297,20 +1304,22 @@ Two adjacent footguns surface most often on first-time audience
 construction. Both are documented here because they cost a round-trip
 to discover by experiment.
 
-### \`occupation\` is a loose substring match
-
-\`audience_build\` (and the \`--search\` flag) treats \`occupation\` as
-a **loose, case-insensitive substring filter**, not a whole-token /
-taxonomy match. \`occupation=["manager"]\` will match hotel managers,
-retail store managers, bank branch managers — anything containing
-the literal string "manager". Three patterns that recover the
-specificity you usually want:
-
-- **Whole-token alternation**: \`occupation=["engineering manager",
-  "software engineering manager", "vp engineering", "tech lead"]\` —
-  exhaustive enumeration of the role surface beats one short token.
-- **Pair with other filters**: \`occupation=["manager"]\` +
-  \`min_age=28\` + \`country=["US","SE"]\` narrows even a loose substring
+### \`--occupation\` is a loose substring match
+
+\`audience_build\` and the \`--occupation\` flag treat the value as a
+**loose, case-insensitive substring filter**, not a whole-token or
+taxonomy match. \`--occupation manager\` will match hotel managers,
+retail store managers, bank branch managers: anything containing the
+literal string "manager". Three patterns that recover the specificity
+you usually want:
+
+- **Whole-token alternation**: \`--occupation "engineering manager"
+  --occupation "software engineering manager" --occupation "vp
+  engineering" --occupation "tech lead"\`: exhaustive enumeration of
+  the role surface beats one short token. Multiple \`--occupation\`
+  flags OR together server-side.
+- **Pair with other filters**: \`--occupation manager --min-age 28
+  --country US --country SE\` narrows even a loose substring
   meaningfully.
 - **Preview before dispatch**: \`audience_build\` returns a
   \`match_preview\` summary on the response — a 1-line histogram of
@@ -1353,6 +1362,12 @@ ish study run --profile tp-795,tp-af2
 # Sample 3 Swedish profiles aged 35-50:
 ish study run --country SE --min-age 35 --max-age 50 --sample 3
 
+# Every female founder or designer:
+ish study run --gender female --occupation founder --occupation designer --all
+
+# Bio substring (e.g. accessibility cohort):
+ish study run --bio "screen reader" --all
+
 # Every female profile in the workspace:
 ish study run --gender female --all