@ishlabs/cli 0.9.0 → 0.11.0

package/dist/commands/study.js

@@ -2,18 +2,33 @@
  * ish study — Manage studies.
  */
 import { readFileSync } from "node:fs";
-import { withClient, getWebUrl, terminalLink, resolveWorkspace, confirmDestructive } from "../lib/command-helpers.js";
+import { Option } from "commander";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, confirmDestructive, readFileOrStdin } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
-import { formatStudyList, formatStudyDetail, formatStudyResults, output, ValidationError } from "../lib/output.js";
+import { formatStudyList, formatStudyDetail, formatStudyResults, buildStudyResultsSummary, buildChatTranscript, output, ValidationError, } from "../lib/output.js";
 import { VALID_CONTENT_TYPES } from "../lib/types.js";
 import { parseAssignment, loadAssignmentsFile, parseQuestion } from "../lib/study-inputs.js";
 import { loadQuestionsManifest } from "../lib/ask-questions.js";
+import { isLocalPath } from "../lib/upload.js";
 import { attachStudyRunCommands } from "./study-run.js";
 import { attachStudyTesterCommands } from "./study-tester.js";
 function collectRepeatable(value, prev = []) {
     return prev.concat([value]);
 }
+/**
+ * Pattern G.1: render the `VALID_CONTENT_TYPES` registry as a help-text block.
+ * The single source of truth is `src/lib/types.ts`; this helper formats it for
+ * `study create --help` so agents don't have to discover the legal
+ * --content-type values per modality through a round-trip error.
+ *
+ * `interactive` and `chat` modalities don't carry a content_type; they're
+ * deliberately omitted (matches the registry).
+ */
+function describeContentTypes() {
+    const lines = Object.entries(VALID_CONTENT_TYPES).map(([modality, types]) => `  ${modality.padEnd(9)} ${types.join(", ")}`);
+    return lines.join("\n");
+}
 function resolveAssignments(opts) {
     const sources = [];
     if (opts.assignment && opts.assignment.length > 0)
@@ -77,12 +92,12 @@ Concept pages: ish docs get-page concepts/study
     });
     study
         .command("create")
-        .description("Create a new study (the persistent shape: modality, tasks, questionnaire). Optionally creates iteration A inline when --content-text or --url is passed.")
+        .description("Create a new study (the persistent shape: modality, tasks, questionnaire). Optionally creates iteration A inline when --content-text, --url, --image-urls, --content-url, or --endpoint is passed.")
         .option("--workspace <id>", "Workspace ID")
         .requiredOption("--name <name>", "Study name")
         .option("--description <description>", "Study description")
         .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document, chat)")
-        .option("--content-type <type>", "Content type (varies by modality — see examples below)")
+        .option("--content-type <type>", "Content type (per-modality enum — see 'Content types by modality' below). Not used for interactive / chat.")
         .option("--assignment <name:instructions>", "Assignment as 'Name:Instructions' (repeatable)", collectRepeatable, [])
         .option("--assignments-file <path>", "JSON file with assignments array")
         .option("--assignments <json>", "Inline JSON array of assignments (escape hatch)")
@@ -90,6 +105,13 @@ Concept pages: ish docs get-page concepts/study
         .option("--questionnaire <path>", "JSON file defining the questionnaire (supports text, slider, likert, single-choice, multiple-choice, number; timing=before|after)")
         .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file. Creates iteration A inline (text modality only)")
         .option("--url <url>", "URL to test. Creates iteration A inline (interactive modality only)")
+        .option("--screen-format <format>", "Screen format for interactive iterations: desktop (default) or mobile_portrait")
+        .option("--content-url <url>", "Public URL of the media file. Creates iteration A inline (video, audio, document modalities). For local files, use the 2-step `iteration create` flow.")
+        .option("--image-urls <urls>", "Comma-separated public image URLs. Creates iteration A inline (image modality). For local files, use the 2-step `iteration create` flow.")
+        .option("--title <title>", "Content title (text + media modalities — image, video, audio, document; optional). Not used for interactive / chat.")
+        .option("--endpoint <id>", "Saved chatbot endpoint id or alias. Creates iteration A inline (chat modality only)")
+        .option("--endpoint-config <file>", "ChatbotEndpointConfig JSON file (or `-` for stdin); embedded directly. Mutually exclusive with --endpoint (chat modality only)")
+        .option("--max-turns <n>", "Maximum conversation turns per tester (chat modality only; default 12)", (v) => Number(v))
         .addHelpText("after", `
 Note: --workspace is optional if set via \`ish workspace use <alias>\`.
 
@@ -98,12 +120,46 @@ quickly add simple text questions, or \`--questionnaire <file.json>\` for richer
 types (slider, likert, single-choice, multiple-choice, number) and custom
 timing. The two forms are mutually exclusive — pick one.
 
+Inline iteration shortcuts (one-shot study + iteration A):
+  --modality interactive  --url <url> [--screen-format desktop|mobile_portrait]
+  --modality text         --content-text <text-or-@file>
+  --modality image        --image-urls <url1,url2,...>
+  --modality video        --content-url <url>
+  --modality audio        --content-url <url>
+  --modality document     --content-url <url>
+  --modality chat         --endpoint <id> | --endpoint-config <file>
+
+Local file paths in --content-url and --image-urls are NOT accepted on
+\`study create\` (they need an existing study to upload against). For local
+files, use the 2-step flow: \`study create\` (no media flags) then
+\`iteration create --content-url ./file.mp4\`.
+
 Examples:
   # Interactive study with one assignment and a single-question questionnaire:
   $ ish study create --name "Onboarding UX" --modality interactive \\
       --assignment "Sign up:Complete the signup flow" \\
       --question "How easy was it?"
 
+  # One-shot interactive (URL + screen format inline):
+  $ ish study create --name "HN scan" --modality interactive \\
+      --url https://news.ycombinator.com --screen-format desktop \\
+      --assignment "Skim:Skim the top stories"
+
+  # One-shot image A/B (uses iteration A inline):
+  $ ish study create --name "Hero shots" --modality image \\
+      --image-urls "https://cdn.example.com/a.png,https://cdn.example.com/b.png" \\
+      --assignment "Compare:Which feels more premium?"
+
+  # One-shot video study:
+  $ ish study create --name "Product Ad" --modality video \\
+      --content-url https://cdn.example.com/ad.mp4 \\
+      --assignment "Watch:Watch this ad and share your reaction"
+
+  # One-shot document study:
+  $ ish study create --name "Whitepaper" --modality document \\
+      --content-url https://cdn.example.com/report.pdf \\
+      --assignment "Skim:Skim the report and summarise"
+
   # Multiple assignments + a richer questionnaire from a file:
   $ ish study create --name "Checkout" --modality interactive \\
       --assignment "Browse:Find a product you like" \\
@@ -114,11 +170,15 @@ Examples:
   $ ish study create --name "Newsletter" --modality text --content-type email \\
       --assignments-file ./assignments.json
 
-  # Video ad study with a quick two-question questionnaire:
-  $ ish study create --name "Product Ad" --modality video --content-type ad \\
-      --assignment "Watch:Watch this ad and share your reaction" \\
-      --question "What stuck with you?" \\
-      --question "Would you click through?"
+  # Chat study targeting a saved chatbot endpoint:
+  $ ish study create --name "Onboarding bot" --modality chat \\
+      --endpoint ep-abc \\
+      --assignment "Sign up:Complete the signup flow" \\
+      --max-turns 20
+
+  # Chat study with an inline endpoint config (stdin or file):
+  $ cat ./endpoint.json | ish study create --name "Bot smoke" \\
+      --modality chat --endpoint-config -
 
   # Sample questionnaire.json (full InterviewQuestion shape):
   #   [
@@ -128,15 +188,15 @@ Examples:
   #       "options": ["A","B","C"] }
   #   ]
 
-Content types by modality:
-  text:     narrative, informational, commercial, editorial, reference, email, news
-  video:    tutorial, documentary, entertainment, review, lifestyle, news, social_post, ad
-  audio:    music, narration, conversation, speech, soundscape, news, ad
-  image:    product, photography, infographic, artwork, interface, social_post, ad
-  document: deck, presentation, report, brochure, guide
+Content types by modality (source: VALID_CONTENT_TYPES in src/lib/types.ts; interactive + chat omitted — they don't take --content-type):
+${describeContentTypes()}
+
+Tips:
+  Use \`--get <path>\` to capture a single value (e.g. \`--get id\`),
+  \`--fields a,b,c\` to project the JSON output to listed fields.
 
 Next: configure a run with \`ish iteration create --study <id>\`,
-      then dispatch with \`ish study run\`.`)
+      then dispatch with \`ish study run\` (audience size is set on run, not create).`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const assignments = resolveAssignments(opts);
@@ -148,13 +208,51 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                     throw new ValidationError(`Invalid content type "${opts.contentType}" for modality "${opts.modality}".`, validTypes);
                 }
             }
-            // Pattern E (cli half): build an inline iteration A when --content-text
-            // or --url is provided, so a single `study create` produces a study
-            // that's immediately runnable. Without these flags the backend
-            // creates zero iterations and the first `iteration create` becomes A.
-            // The backend requires a non-empty `name` on the inline iteration; we
-            // default to "A" to match the iteration-naming convention.
+            // --endpoint and --endpoint-config are mutually exclusive. Modality
+            // mismatch is enforced inside the chat branch below, mirroring how
+            // --content-text / --url validate against modality.
+            if (opts.endpoint !== undefined && opts.endpointConfig !== undefined) {
+                throw new ValidationError("Pass only one of: --endpoint, --endpoint-config.", ["--endpoint", "--endpoint-config"]);
+            }
+            // Pattern E + D + J (cli half): build an inline iteration A when one
+            // of the modality-specific content flags is provided, so a single
+            // `study create` produces a study that's immediately runnable.
+            // Without these flags the backend creates zero iterations and the
+            // first `iteration create` becomes A. The backend requires a
+            // non-empty `name` on the inline iteration; we default to "A" to
+            // match the iteration-naming convention.
+            //
+            // Local file paths in --content-url / --image-urls are NOT supported
+            // here because the upload endpoint requires a study_id, which doesn't
+            // exist until after `studies` POST. For local files, agents fall
+            // back to the existing 2-step `iteration create` path which uploads
+            // against the freshly-created study.
+            const inlineMediaFlagsSet = [
+                opts.contentText !== undefined ? "--content-text" : null,
+                opts.url !== undefined ? "--url" : null,
+                opts.contentUrl !== undefined ? "--content-url" : null,
+                opts.imageUrls !== undefined ? "--image-urls" : null,
+                (opts.endpoint !== undefined || opts.endpointConfig !== undefined) ? "--endpoint/--endpoint-config" : null,
+            ].filter((f) => f !== null);
+            if (inlineMediaFlagsSet.length > 1) {
+                throw new ValidationError(`Pass only one inline-iteration flag: ${inlineMediaFlagsSet.join(", ")}.`, inlineMediaFlagsSet);
+            }
+            if (opts.screenFormat !== undefined && opts.url === undefined) {
+                throw new Error("--screen-format only applies when --url is set (interactive modality).");
+            }
+            // Pattern G.2: --title is metadata, not content. The backend
+            // accepts it on text + media modalities (see
+            // `buildIterationDetails` in iteration.ts). Reject it only on
+            // shapes that have no title field — interactive (URL only) and
+            // chat (endpoint config carries its own metadata).
+            if (opts.title !== undefined
+                && opts.contentText === undefined
+                && opts.contentUrl === undefined
+                && opts.imageUrls === undefined) {
+                throw new Error("--title only applies with --content-text (text) or --content-url / --image-urls (media). Interactive + chat iterations don't carry a title.");
+            }
             let inlineIteration;
+            let chatbotEndpointId = null;
             if (opts.contentText !== undefined) {
                 if (opts.modality && opts.modality !== "text") {
                     throw new Error(`--content-text is only valid with --modality text (got "${opts.modality}").`);
@@ -162,7 +260,14 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 const text = opts.contentText.startsWith("@")
                     ? readFileSync(opts.contentText.slice(1), "utf8")
                     : opts.contentText;
-                inlineIteration = { name: "A", details: { type: "text", content_text: text } };
+                inlineIteration = {
+                    name: "A",
+                    details: {
+                        type: "text",
+                        content_text: text,
+                        ...(opts.title && { title: opts.title }),
+                    },
+                };
             }
             else if (opts.url !== undefined) {
                 if (opts.modality && opts.modality !== "interactive") {
@@ -170,7 +275,89 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 }
                 inlineIteration = {
                     name: "A",
-                    details: { type: "interactive", url: opts.url, platform: "browser" },
+                    details: {
+                        type: "interactive",
+                        url: opts.url,
+                        platform: "browser",
+                        screen_format: opts.screenFormat || "desktop",
+                    },
+                };
+            }
+            else if (opts.imageUrls !== undefined) {
+                if (opts.modality && opts.modality !== "image") {
+                    throw new Error(`--image-urls is only valid with --modality image (got "${opts.modality}").`);
+                }
+                const urls = opts.imageUrls.split(",").map((s) => s.trim()).filter(Boolean);
+                if (urls.length === 0) {
+                    throw new Error("--image-urls is empty. Provide one or more comma-separated URLs.");
+                }
+                const localPaths = urls.filter((u) => isLocalPath(u));
+                if (localPaths.length > 0) {
+                    throw new Error(`--image-urls on \`study create\` only accepts http(s) URLs (local files need an existing study to upload against). Got local path(s): ${localPaths.join(", ")}. Use the 2-step flow: \`ish study create\` (no --image-urls) then \`ish iteration create --image-urls "${opts.imageUrls}"\`.`);
+                }
+                inlineIteration = {
+                    name: "A",
+                    details: {
+                        type: "image",
+                        image_urls: urls,
+                        ...(opts.title && { title: opts.title }),
+                    },
+                };
+            }
+            else if (opts.contentUrl !== undefined) {
+                const mediaModalities = ["video", "audio", "document"];
+                if (opts.modality && !mediaModalities.includes(opts.modality)) {
+                    throw new Error(`--content-url is only valid with --modality video|audio|document (got "${opts.modality}").`);
+                }
+                if (!opts.modality) {
+                    throw new Error("--content-url requires --modality video|audio|document so the iteration shape is unambiguous.");
+                }
+                if (isLocalPath(opts.contentUrl)) {
+                    throw new Error(`--content-url on \`study create\` only accepts an http(s) URL (local files need an existing study to upload against). Got local path: ${opts.contentUrl}. Use the 2-step flow: \`ish study create\` (no --content-url) then \`ish iteration create --content-url "${opts.contentUrl}"\`.`);
+                }
+                inlineIteration = {
+                    name: "A",
+                    details: {
+                        type: opts.modality,
+                        content_url: opts.contentUrl,
+                        ...(opts.title && { title: opts.title }),
+                    },
+                };
+            }
+            else if (opts.endpoint !== undefined || opts.endpointConfig !== undefined) {
+                if (opts.modality && opts.modality !== "chat") {
+                    throw new ValidationError(`--endpoint / --endpoint-config require --modality chat (got "${opts.modality}").`, ["chat"]);
+                }
+                let endpointConfig;
+                if (opts.endpoint !== undefined) {
+                    const epId = resolveId(opts.endpoint);
+                    const ep = await client.get(`/chatbot-endpoints/${epId}`);
+                    const cfg = ep?.config;
+                    if (!cfg || typeof cfg !== "object") {
+                        throw new Error(`Chatbot endpoint ${epId} returned no config.`);
+                    }
+                    endpointConfig = cfg;
+                    chatbotEndpointId = epId;
+                }
+                else {
+                    const raw = await readFileOrStdin(opts.endpointConfig);
+                    try {
+                        endpointConfig = JSON.parse(raw);
+                    }
+                    catch {
+                        throw new Error("Invalid --endpoint-config JSON.");
+                    }
+                }
+                const maxTurns = opts.maxTurns ?? 12;
+                inlineIteration = {
+                    name: "A",
+                    details: {
+                        type: "chat",
+                        endpoint: endpointConfig,
+                        chatbot_endpoint_id: chatbotEndpointId,
+                        max_turns: maxTurns,
+                        early_termination: true,
+                    },
                 };
             }
             const resolvedWs = resolveWorkspace(opts.workspace);
@@ -193,6 +380,15 @@ Next: configure a run with \`ish iteration create --study <id>\`,
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
+            const firstIteration = Array.isArray(data.iterations) && data.iterations.length > 0
+                ? data.iterations[0]
+                : undefined;
+            if (firstIteration?.id) {
+                result.iteration_id = firstIteration.id;
+            }
+            if (opts.modality === "chat" && inlineIteration) {
+                result.chatbot_endpoint_id = chatbotEndpointId;
+            }
             formatStudyDetail(result, globals.json, { writePath: true });
             if (!globals.json && data.id) {
                 const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
@@ -276,34 +472,110 @@ list table layout in human mode.`)
         .description("View aggregated results: tester counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed.")
         .argument("<id>", "Study ID")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
+        .option("--summary", "Lean summary projection: counts + sentiment + per-tester {alias, status, sentiment, comment}. Drops interview_answers + per-interaction breakdowns.")
+        // PC-N4: agents reach for `--summarize` (verb) by analogy with the MCP
+        // `summarize` action; accept it as a hidden alias of --summary so the
+        // canonical flag stays the documented one but the muscle-memory variant
+        // works without a round-trip.
+        .addOption(new Option("--summarize", "Hidden alias for --summary").hideHelp())
+        .option("--transcript <tester_id>", "Chat transcript projection for one tester: flat role/text/turn-index array (chat-modality only). Mirrors the MCP `get_chat_transcript` shape.")
         .addHelpText("after", `
 Examples:
   $ ish study results <id>
   $ ish study results <id> --json
+  $ ish study results <id> --summary --json
+  $ ish study results <id> --transcript t-d4e --json
 
-Example response (--json):
+Default --json envelope (M10: per-answer sentiment now included):
   {
-    "study_id": "<uuid>",
-    "alias": "s-...",
-    "name": "...",
+    "study": { "alias": "s-...", "name": "...", "modality": "..." },
     "tester_count": 12,
     "completed_count": 8,
-    "errored_count": 0,
-    "total_interactions": 142,
-    "sentiment": { "Satisfied": 5, "Frustrated": 2, "Neutral": 1 },
+    "failed_count": 0,
+    "sentiment": { "counts": { "Satisfied": 5, "Frustrated": 2 }, "total": 7 },
     "interview_answers": [
-      { "question_id": "...", "question": "...", "type": "text",
-        "answers": [ { "tester_id": "...", "tester_alias": "t-...", "answer": "..." } ] }
+      { "question": "...", "type": "text",
+        "answers": [
+          { "tester_alias": "t-...", "tester_name": "...", "iteration": "A",
+            "answer": "...", "sentiment": "Satisfied" }
+        ] }
+    ],
+    "testers": [
+      { "alias": "t-...", "name": "...", "iteration": "A", "status": "completed",
+        "interaction_count": 12, "sentiment": "Satisfied", "comment": "...",
+        "error_message": "..." }
+    ]
+  }
+
+--summary projection (M2-friction-7: drops the interview_answers payload):
+  { study, tester_count, completed_count, failed_count, sentiment, testers: [...] }
+
+--transcript <tester_id> projection (M2-friction-12, chat modality):
+  {
+    "tester_id": "...", "tester_alias": "t-...",
+    "instance_name": "...", "modality": "chat",
+    "transcript": [
+      { "role": "bot",    "text": "Hi…",    "turn_index": 0, "failure": null },
+      { "role": "tester", "text": "Pricing?", "turn_index": 0,
+        "action_type": "send_text", "option_label": null, "sentiment": null }
     ],
-    "testers": [ { "id": "...", "alias": "t-...", "name": "...", "status": "completed", "interaction_count": 12 } ]
+    "unique_bot_replies": 2,
+    "tester_summary": { "comment": "...", "sentiment": {...} }
   }
 
-When no runs have completed, the same envelope is returned with zero counts and empty arrays.`)
-        .action(async (id, _opts, cmd) => {
+Tips:
+  Use \`--get <path>\` for a single value (e.g. \`--get tester_count\`),
+  \`--fields a,b,c\` to project the JSON output further.
+
+Common --get paths (default envelope):
+  --get tester_count                            # how many testers ran
+  --get completed_count                         # how many finished
+  --get failed_count                            # how many errored
+  --get sentiment                               # {counts, total} histogram
+  --get sentiment.counts                        # bare label→count map
+  --get sentiment.total                         # total sentiment-tagged answers
+  --get study.modality                          # interactive | text | image | …
+  --get testers.alias                           # one alias per line
+  --get testers.0.comment                       # first tester's narrative comment
+  --get testers.0.sentiment                     # first tester's aggregate sentiment
+  --get interview_answers                       # full per-question payload
+  --get interview_answers.0.question            # text of the first question
+  --get interview_answers.0.answers.0.answer    # first answer to the first question
+
+Common --get paths (--transcript <tester_id> envelope):
+  --get transcript                              # full role/text/turn array
+  --get transcript.text                         # one text per turn
+  --get tester_summary.comment                  # narrative comment
+  --get tester_summary.sentiment                # aggregate sentiment map
+  --get unique_bot_replies                      # bot-side message count
+
+When no runs have completed, the default envelope is returned with zero counts and empty arrays.`)
+        .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            // PC-N4: --summarize is a hidden alias for --summary. Merge them
+            // into a single boolean before validation so the rest of the
+            // handler reads only `summary`.
+            const wantsSummary = !!(opts.summary || opts.summarize);
+            if (wantsSummary && opts.transcript) {
+                throw new ValidationError("Pass only one of: --summary, --transcript.", ["--summary", "--transcript"]);
+            }
             const rid = resolveId(id);
+            if (opts.transcript) {
+                // --transcript <tester_id>: bypass the study aggregator; fetch
+                // the named tester directly. Cheaper (one GET, no nested
+                // iterations payload) and shapes 1:1 with the MCP transcript.
+                const testerId = resolveId(opts.transcript);
+                const tester = await client.get(`/testers/${testerId}`);
+                output(buildChatTranscript(tester), globals.json, { preProjected: true });
+                return;
+            }
             const data = await client.get(`/studies/${rid}`);
-            formatStudyResults(data, globals.json);
+            if (wantsSummary) {
+                output(buildStudyResultsSummary(data), globals.json, { preProjected: true });
+            }
+            else {
+                formatStudyResults(data, globals.json);
+            }
             if (!globals.json && data.product_id) {
                 const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
                 console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);

package/dist/commands/workspace.js

@@ -112,6 +112,38 @@ Concept pages: ish docs get-page concepts/workspace
         });
     });
     registerSiteAccessCommands(workspace);
+    workspace
+        .command("info")
+        .description("Show workspace details + plan-limit usage counters")
+        .option("--workspace <id>", "Workspace ID; defaults to active workspace")
+        .addHelpText("after", `
+Usage counters:
+  studies_used / studies_max — current study count vs the user's plan cap
+  testers_used / testers_max — workspace-private tester profile count vs cap
+
+Caps fall back to null when the user's plan grants unlimited (math.inf). The
+account tier is read from /account/me; limit tables come from /billing/limits.
+
+Examples:
+  $ ish workspace info
+  $ ish workspace info --json | jq '{studies_used, studies_max}'`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const wid = resolveWorkspace(opts.workspace);
+            const usage = await collectWorkspaceUsage(client, wid);
+            if (globals.json) {
+                output(usage, true);
+                return;
+            }
+            const renderCap = (n) => (n === null ? "∞" : String(n));
+            console.log(`Workspace:      ${usage.name ?? wid} (${tagAlias(ALIAS_PREFIX.workspace, wid)})`);
+            console.log(`ID:             ${wid}`);
+            if (usage.tier)
+                console.log(`Plan:           ${usage.tier}`);
+            console.log(`Studies:        ${usage.studies_used} / ${renderCap(usage.studies_max)}`);
+            console.log(`Custom testers: ${usage.testers_used} / ${renderCap(usage.testers_max)}`);
+        });
+    });
     workspace
         .command("use")
         .description("Set the active workspace (saved to ~/.ish/config.json)")
@@ -141,6 +173,55 @@ Concept pages: ish docs get-page concepts/workspace
         });
     });
 }
+async function collectWorkspaceUsage(client, workspaceId) {
+    // Workspace shape — name + base_url are nice-to-have for human render.
+    const productPromise = client.get(`/products/${workspaceId}`).catch(() => null);
+    // studies_used: list endpoint returns an array; length is the count.
+    const studiesPromise = client
+        .get(`/products/${workspaceId}/studies`)
+        .catch(() => []);
+    // testers_used: paginated list returns { total, items, ... }. Backend
+    // gates `maxCustomTesterProfiles` on visibility=private.
+    const testersPromise = client
+        .get("/tester-profiles", {
+        product_id: workspaceId,
+        visibility: "private",
+        type: "ai",
+        limit: "1",
+        offset: "0",
+    })
+        .catch(() => ({ total: 0 }));
+    // Plan caps: tier from /account/me, table from /billing/limits.
+    const acctPromise = client
+        .get("/account/me")
+        .catch(() => ({}));
+    const limitsPromise = client
+        .get("/billing/limits")
+        .catch(() => ({ tiers: {} }));
+    const [product, studies, testers, account, limits] = await Promise.all([
+        productPromise,
+        studiesPromise,
+        testersPromise,
+        acctPromise,
+        limitsPromise,
+    ]);
+    const tier = typeof account.credits?.tier === "string" ? account.credits.tier : null;
+    const tierTable = tier ? limits.tiers?.[tier] ?? null : null;
+    const studiesMax = tierTable && "maxStudiesPerProduct" in tierTable ? tierTable.maxStudiesPerProduct : null;
+    const testersMax = tierTable && "maxCustomTesterProfiles" in tierTable
+        ? tierTable.maxCustomTesterProfiles
+        : null;
+    return {
+        id: workspaceId,
+        name: product?.name ?? null,
+        base_url: product?.base_url ?? null,
+        tier,
+        studies_used: Array.isArray(studies) ? studies.length : 0,
+        studies_max: studiesMax,
+        testers_used: typeof testers.total === "number" ? testers.total : 0,
+        testers_max: testersMax,
+    };
+}
 // ---------------------------------------------------------------------------
 // site-access — workspace-level credentials for gated test sites.
 // Stored as product secrets with reserved keys (see src/lib/site-access.ts).

package/dist/config.d.ts

@@ -13,6 +13,9 @@ export interface IshConfig {
     workspace?: string;
     study?: string;
     ask?: string;
+    /** Active chatbot endpoint id; used as the default for `ish chat endpoint *` verbs
+     *  when a positional id is omitted. Set by `ish chat endpoint use <id>`. */
+    chat_endpoint?: string;
     [key: string]: string | undefined;
 }
 export declare function loadConfig(): IshConfig;

package/dist/connect.d.ts

@@ -5,3 +5,6 @@ export declare function runTunnel(port: number, tokenArg?: string, apiUrlArg?: s
     json?: boolean;
     quiet?: boolean;
 }): Promise<void>;
+export declare function runDetached(port: number, apiUrlArg: string | undefined, tokenArg: string | undefined, tokenFileArg: string | undefined): Promise<void>;
+export declare function connectStatus(json: boolean): void;
+export declare function disconnect(json: boolean): Promise<void>;