@ishlabs/cli 0.8.5 → 0.10.0

package/dist/commands/iteration.js

@@ -5,13 +5,35 @@
  * content/file for media). Create one before `ish study run` dispatches
  * simulations against it.
  */
-import { withClient, resolveStudy, resolveWorkspace } from "../lib/command-helpers.js";
+import { withClient, resolveStudy, resolveWorkspace, readFileOrStdin } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
-import { output, formatIterationList } from "../lib/output.js";
+import { output, formatIterationList, ValidationError } from "../lib/output.js";
 import { resolveContentUrl, resolveContentUrls, resolveTextContent } from "../lib/upload.js";
-import { MEDIA_MODALITIES } from "../lib/types.js";
-function isMediaModality(modality) {
-    return !!modality && MEDIA_MODALITIES.includes(modality);
+import { isMediaModality, validateIterationDetails } from "../lib/modality.js";
+/**
+ * Pattern C / M12: project each tester row on an iteration response so its
+ * `alias` and `name` survive `leanJson` (which strips raw UUID values). The
+ * existing `id` and `tester_profile` payload still pass through under
+ * `--verbose`, but the agent-default `--json` shape now exposes the same
+ * `{alias, name, status}` triple `study results` already does, so an agent
+ * can correlate testers across the two verbs.
+ */
+function enrichIterationTesters(iteration) {
+    const testers = iteration.testers;
+    if (!Array.isArray(testers))
+        return;
+    for (const t of testers) {
+        if (!t || typeof t !== "object")
+            continue;
+        const tester = t;
+        const id = tester.id ? String(tester.id) : "";
+        if (id)
+            tester.alias = tagAlias(ALIAS_PREFIX.tester, id);
+        const profile = tester.tester_profile;
+        if (!tester.name) {
+            tester.name = profile?.name ?? tester.instance_name ?? null;
+        }
+    }
 }
 function buildCopyContent(opts) {
     if (!opts.copyText)
@@ -23,6 +45,30 @@ function buildCopyContent(opts) {
         ...(opts.copyPosition && { position: opts.copyPosition }),
     };
 }
+function parseJsonFlag(raw, flagName) {
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`Invalid ${flagName}: expected a JSON object`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("Invalid "))
+            throw err;
+        throw new Error(`Invalid ${flagName}: expected valid JSON object`);
+    }
+}
+function mediaExtras(opts) {
+    const segmentation = parseJsonFlag(opts.segmentationJson, "--segmentation-json");
+    const contentConfig = parseJsonFlag(opts.contentConfigJson, "--content-config-json");
+    return {
+        ...(segmentation && { segmentation }),
+        ...(contentConfig && { content_config: contentConfig }),
+    };
+}
 function buildIterationDetails(modality, opts) {
     switch (modality) {
         case "text":
@@ -35,6 +81,10 @@ function buildIterationDetails(modality, opts) {
                 ...(opts.contentHtml && { content_html: opts.contentHtml }),
                 ...(opts.title && { title: opts.title }),
                 ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...(opts.senderName && { sender_name: opts.senderName }),
+                ...(opts.senderEmail && { sender_email: opts.senderEmail }),
+                ...(opts.featuredImageUrl && { featured_image_url: opts.featuredImageUrl }),
+                ...mediaExtras(opts),
             };
         case "video":
         case "audio": {
@@ -48,6 +98,7 @@ function buildIterationDetails(modality, opts) {
                 ...(opts.title && { title: opts.title }),
                 ...(opts.mimeType && { mime_type: opts.mimeType }),
                 ...(copy && { copy_content: copy }),
+                ...mediaExtras(opts),
             };
         }
         case "image": {
@@ -61,6 +112,7 @@ function buildIterationDetails(modality, opts) {
                 ...(opts.title && { title: opts.title }),
                 ...(opts.mimeType && { mime_type: opts.mimeType }),
                 ...(copy && { copy_content: copy }),
+                ...mediaExtras(opts),
             };
         }
         case "document":
@@ -72,17 +124,45 @@ function buildIterationDetails(modality, opts) {
                 content_url: opts.contentUrl,
                 ...(opts.title && { title: opts.title }),
                 ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...mediaExtras(opts),
+            };
+        case "chat": {
+            const endpoint = parseJsonFlag(opts.chatEndpointJson, "--chat-endpoint-json");
+            if (!endpoint && !opts.chatEndpointId) {
+                throw new Error("Chat iterations require either --chat-endpoint-id (saved endpoint) or --chat-endpoint-json (inline config).");
+            }
+            let maxTurns;
+            if (opts.maxTurns !== undefined) {
+                const parsed = Number.parseInt(opts.maxTurns, 10);
+                if (!Number.isFinite(parsed) || parsed < 1) {
+                    throw new Error("Invalid --max-turns: expected a positive integer");
+                }
+                maxTurns = parsed;
+            }
+            return {
+                type: "chat",
+                ...(endpoint && { endpoint }),
+                ...(opts.chatEndpointId && { chatbot_endpoint_id: opts.chatEndpointId }),
+                ...(maxTurns !== undefined && { max_turns: maxTurns }),
+                ...(opts.earlyTermination !== undefined && { early_termination: opts.earlyTermination }),
             };
+        }
         default:
             if (!opts.url) {
                 throw new Error("Interactive iterations require --url. Provide the URL to test.");
             }
+            if (opts.platform === "figma" && (!opts.fileKey || !opts.startNodeId)) {
+                throw new Error("Figma interactive iterations require both --file-key and --start-node-id.");
+            }
             return {
                 type: "interactive",
                 platform: opts.platform || "browser",
                 url: opts.url,
                 screen_format: opts.screenFormat || "desktop",
                 ...(opts.locale && { locale: opts.locale }),
+                ...(opts.fileKey && { file_key: opts.fileKey }),
+                ...(opts.startNodeId && { start_node_id: opts.startNodeId }),
+                ...(opts.flowName && { flow_name: opts.flowName }),
             };
     }
 }
@@ -91,9 +171,11 @@ export function registerIterationCommands(program) {
         .command("iteration")
         .description("Manage iterations of a study (a study's run-time configuration)")
         .addHelpText("after", `
-An iteration is one configured run of a study — it carries the URL (interactive) or
-media content (text/video/image/document). A study has 1..N iterations; \`ish study run\`
-defaults to the latest. Local file paths in --content-url / --image-urls are auto-uploaded.
+An iteration is one configured run of a study — it carries the URL (interactive),
+media content (text/video/image/document), or chatbot endpoint (chat). A study has
+1..N iterations; \`ish study run\` defaults to the latest. Local file paths in
+--content-url / --image-urls are auto-uploaded. Segments and per-segment labels
+live inside --segmentation-json.
 
 Concept pages: ish docs get-page concepts/iteration
                 ish docs get-page concepts/study`);
@@ -145,9 +227,15 @@ Concept pages: ish docs get-page concepts/iteration
         .option("--url <url>", "URL to test — interactive only")
         .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only")
         .option("--locale <locale>", "Locale code (e.g. en-US) — interactive only")
+        .option("--file-key <key>", "Figma file key — required when --platform=figma")
+        .option("--start-node-id <id>", "Figma start node id — required when --platform=figma")
+        .option("--flow-name <name>", "Figma flow name — interactive only")
         // Media text
         .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file — text modality")
         .option("--content-html <html>", "HTML version of the text, or @filepath to read from file — text modality")
+        .option("--sender-name <name>", "Email 'From' display name — text modality (email rendering)")
+        .option("--sender-email <email>", "Email sender address — text modality (email rendering)")
+        .option("--featured-image-url <url>", "Hero image URL — text modality (email rendering)")
         // Media video/audio/document
         .option("--content-url <url>", "URL or local file path to media file — video, audio, document modalities")
         // Media image
@@ -160,6 +248,21 @@ Concept pages: ish docs get-page concepts/iteration
         .option("--copy-html <html>", "HTML version of copy text (or @filepath)")
         .option("--social-platform <platform>", "Social platform (instagram, tiktok, facebook, linkedin, x)")
         .option("--copy-position <pos>", "Copy position relative to media (before, after)", "after")
+        // Segmentation / per-iteration evaluation config (media modalities)
+        .option("--segmentation-json <json>", "Segmentation JSON — time_based {intervals_seconds, labels?}, section_based {sections[{name,label,...}]}, or page_based {} — media modalities")
+        .option("--content-config-json <json>", "Content config JSON — {early_termination, selected_segment_indices?} — media modalities")
+        // Chat modality
+        .option("--chat-endpoint-id <id>", "Saved chatbot endpoint id — chat modality (legacy; prefer --endpoint)")
+        .option("--chat-endpoint-json <json>", "Inline chatbot endpoint config JSON — chat modality (legacy; prefer --endpoint-config)")
+        .option("--max-turns <n>", "Max tester turns (1-50) — chat modality (default 12)")
+        .option("--early-termination", "End the chat session early when the tester signals stop — chat modality")
+        // Agent-friendly chat shortcuts: --endpoint <id> resolves a saved
+        // chatbot endpoint via alias / UUID and fetches its config inline;
+        // --endpoint-config <file> takes a raw config file (or `-` for
+        // stdin). Mutually exclusive with each other and with the legacy
+        // --chat-endpoint-* flags. Only meaningful for chat-modality studies.
+        .option("--endpoint <id>", "Saved chatbot endpoint id (alias or UUID) — chat modality")
+        .option("--endpoint-config <file>", "Raw ChatbotEndpointConfig JSON file or `-` for stdin — chat modality")
         // Escape hatch
         .option("--details-json <json>", "Raw iteration details JSON (overrides individual flags)")
         .addHelpText("after", `
@@ -194,6 +297,32 @@ Examples:
   $ ish iteration create --image-urls ./post.png \\
       --copy-text @./caption.txt --social-platform instagram
 
+  # Email with sender + featured image + section-based segmentation:
+  $ ish iteration create --content-text @./email.txt --content-html @./email.html \\
+      --sender-name "Marketing" --sender-email "marketing@example.com" \\
+      --featured-image-url https://cdn.example.com/hero.png \\
+      --segmentation-json '{"type":"section_based","sections":[{"name":"intro","label":"Intro","paragraph_start":0,"paragraph_end":1}]}'
+
+  # Video with time-based segmentation + labels and early termination:
+  $ ish iteration create --content-url ./promo.mp4 \\
+      --segmentation-json '{"type":"time_based","intervals_seconds":[0,30,60],"labels":["Hook","Body","CTA"]}' \\
+      --content-config-json '{"early_termination":true,"selected_segment_indices":[0,2]}'
+
+  # Figma interactive (file_key + start_node_id required):
+  $ ish iteration create --platform figma --url https://figma.com/proto \\
+      --screen-format mobile_portrait --file-key abc123 --start-node-id 0:1 \\
+      --flow-name "Onboarding A"
+
+  # Chat — saved endpoint (the parent study's modality determines the type):
+  $ ish iteration create --study s-b2c --endpoint ep-abc --max-turns 6
+
+  # Chat — inline endpoint config (file or stdin):
+  $ ish iteration create --study s-b2c --endpoint-config ./bot.json
+  $ cat ./bot.json | ish iteration create --study s-b2c --endpoint-config -
+
+  # Chat — legacy flags still work:
+  $ ish iteration create --chat-endpoint-id ce-abc --max-turns 10 --early-termination
+
   # Raw JSON escape hatch (overrides individual flags):
   $ ish iteration create --study s-b2c --details-json \\
       '{"type":"interactive","platform":"browser","url":"https://example.com","screen_format":"desktop"}'
@@ -204,9 +333,13 @@ workspace's public storage bucket. Validation now happens before upload.
 Next: \`ish study run\` to dispatch simulations against this iteration.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            if (opts.endpoint !== undefined && opts.endpointConfig !== undefined) {
+                throw new ValidationError("Pass only one of: --endpoint, --endpoint-config.", ["--endpoint", "--endpoint-config"]);
+            }
             if (opts.workspace)
                 resolveWorkspace(opts.workspace);
             const studyId = resolveStudy(opts.study);
+            let chatbotEndpointIdForOutput = null;
             let details;
             if (opts.detailsJson) {
                 try {
@@ -221,12 +354,16 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                 const study = await client.get(`/studies/${studyId}`);
                 const modality = study.modality || "interactive";
                 const isMedia = isMediaModality(modality);
-                if (isMedia && opts.url) {
-                    throw new Error(`This study uses "${modality}" modality — --url is for interactive studies. Use --content-text, --content-url, or --image-urls instead.`);
+                const isChat = modality === "chat";
+                if ((isMedia || isChat) && opts.url) {
+                    throw new Error(`This study uses "${modality}" modality — --url is for interactive studies. Use the modality-specific flags instead.`);
                 }
-                if (!isMedia && (opts.contentText || opts.contentUrl || opts.imageUrls)) {
+                if (!isMedia && !isChat && (opts.contentText || opts.contentUrl || opts.imageUrls)) {
                     throw new Error(`This study uses "interactive" modality — --content-text, --content-url, and --image-urls are for media studies. Use --url instead.`);
                 }
+                if (!isChat && (opts.endpoint !== undefined || opts.endpointConfig !== undefined)) {
+                    throw new Error(`This study uses "${modality}" modality — --endpoint / --endpoint-config are for chat studies.`);
+                }
                 // Validate per-modality required flags BEFORE any upload so we don't
                 // orphan blobs in storage when the wrong flag is passed (e.g.
                 // --content-url to an image-modality study).
@@ -252,6 +389,18 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                             throw new Error("Document iterations require --content-url. Provide the URL or local file path.");
                         }
                         break;
+                    case "chat":
+                        if (!opts.chatEndpointId
+                            && !opts.chatEndpointJson
+                            && !opts.endpoint
+                            && !opts.endpointConfig) {
+                            throw new Error("Chat iterations require one of: --endpoint <id>, --endpoint-config <file>, --chat-endpoint-id, or --chat-endpoint-json.");
+                        }
+                        if ((opts.endpoint || opts.endpointConfig)
+                            && (opts.chatEndpointId || opts.chatEndpointJson)) {
+                            throw new ValidationError("Pass only one of: --endpoint / --endpoint-config (preferred) or the legacy --chat-endpoint-id / --chat-endpoint-json.", ["--endpoint", "--endpoint-config"]);
+                        }
+                        break;
                     default:
                         if (!opts.url) {
                             throw new Error("Interactive iterations require --url. Provide the URL to test.");
@@ -275,7 +424,55 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                         resolved.imageUrls = urls.join(",");
                     }
                 }
-                details = buildIterationDetails(modality, resolved);
+                if (isChat && (opts.endpoint || opts.endpointConfig)) {
+                    // Agent-friendly path: fetch a saved endpoint by alias / UUID
+                    // (or read a raw config from a file / stdin) and embed the full
+                    // ChatbotEndpointConfig inline at iteration.details.endpoint.
+                    // Backend's chat iteration shape is wider than what
+                    // buildIterationDetails covers; we materialise it here.
+                    let endpointConfig;
+                    let chatbotEndpointId = null;
+                    if (opts.endpoint) {
+                        const id = resolveId(opts.endpoint);
+                        const ep = await client.get(`/chatbot-endpoints/${id}`);
+                        endpointConfig = ep.config;
+                        chatbotEndpointId = id;
+                    }
+                    else {
+                        const raw = await readFileOrStdin(opts.endpointConfig);
+                        try {
+                            const parsed = JSON.parse(raw);
+                            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                                throw new Error("expected a JSON object");
+                            }
+                            endpointConfig = parsed;
+                        }
+                        catch (err) {
+                            const reason = err instanceof Error ? err.message : "invalid JSON";
+                            throw new Error(`Invalid --endpoint-config: ${reason}`);
+                        }
+                    }
+                    let maxTurns = 12;
+                    if (opts.maxTurns !== undefined) {
+                        const parsed = Number.parseInt(opts.maxTurns, 10);
+                        if (!Number.isFinite(parsed) || parsed < 1) {
+                            throw new Error("Invalid --max-turns: expected a positive integer");
+                        }
+                        maxTurns = parsed;
+                    }
+                    const earlyTermination = opts.earlyTermination !== undefined ? opts.earlyTermination : true;
+                    details = {
+                        type: "chat",
+                        endpoint: endpointConfig,
+                        chatbot_endpoint_id: chatbotEndpointId,
+                        max_turns: maxTurns,
+                        early_termination: earlyTermination,
+                    };
+                    chatbotEndpointIdForOutput = chatbotEndpointId;
+                }
+                else {
+                    details = buildIterationDetails(modality, resolved);
+                }
             }
             const body = {
                 name: opts.name || `CLI ${new Date().toISOString().slice(0, 16)}`,
@@ -286,6 +483,9 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+            if (chatbotEndpointIdForOutput !== null) {
+                result.chatbot_endpoint_id = chatbotEndpointIdForOutput;
+            }
             output(result, globals.json);
         });
     });
@@ -311,6 +511,7 @@ With multiple IDs, returns a {items:[...], total:N} envelope.`)
                 const result = data;
                 if (result.id)
                     result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+                enrichIterationTesters(result);
                 output(result, globals.json);
                 return;
             }
@@ -319,6 +520,7 @@ With multiple IDs, returns a {items:[...], total:N} envelope.`)
                 const r = data;
                 if (r.id)
                     r.alias = tagAlias(ALIAS_PREFIX.iteration, String(r.id));
+                enrichIterationTesters(r);
                 return r;
             }));
             if (globals.json) {
@@ -359,7 +561,24 @@ With multiple IDs, returns a {items:[...], total:N} envelope.`)
                 console.error("No update flags provided. Run `ish iteration update --help` for options.");
                 return;
             }
-            const data = await client.put(`/iterations/${resolveId(id)}`, body);
+            const resolvedIterationId = resolveId(id);
+            // Pattern C: validate --details-json shape against the parent
+            // study's modality before sending. The backend has its own
+            // schema, but a bare `{"url":"..."}` blob silently passing
+            // through to a chat iteration corrupts it. One GET on the
+            // iteration + one on the study is cheap insurance.
+            if (body.details !== undefined) {
+                const iter = await client.get(`/iterations/${resolvedIterationId}`);
+                if (!iter.study_id) {
+                    throw new Error(`Iteration ${id} has no study_id; cannot validate --details-json against modality.`);
+                }
+                const parentStudy = await client.get(`/studies/${iter.study_id}`);
+                const verdict = validateIterationDetails(parentStudy.modality, body.details);
+                if (!verdict.ok) {
+                    throw new Error(`--details-json rejected: ${verdict.reason} (study modality is "${parentStudy.modality ?? "unknown"}"). ${verdict.suggestion}`);
+                }
+            }
+            const data = await client.put(`/iterations/${resolvedIterationId}`, body);
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));

package/dist/commands/secret.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ish secret — Manage workspace secrets used in {{secret:KEY}} placeholders.
+ *
+ * Workspace secrets back the `{{secret:KEY}}` placeholder in chatbot endpoint
+ * config (request body / headers). They live on the same product-secrets
+ * surface as site-access (see src/lib/site-access.ts), but with general,
+ * user-chosen keys instead of the reserved BASIC_AUTH_/SESSION_COOKIE_/
+ * LOGIN_ keys.
+ *
+ * Security posture:
+ *   - Values are write-only. The backend's list endpoint never returns them;
+ *     this command additionally drops any `value`-shaped fields client-side
+ *     before printing, so an accidental backend regression doesn't leak.
+ *   - Inputs come from a positional value, --value-file <path>, or stdin via
+ *     --value-stdin (mutually exclusive). Stdin/file paths keep secrets out
+ *     of shell history.
+ *   - No interactive prompts (CLI is for autonomous agents).
+ */
+import type { Command } from "commander";
+export declare function registerSecretCommands(program: Command): void;

package/dist/commands/secret.js

@@ -0,0 +1,246 @@
+/**
+ * ish secret — Manage workspace secrets used in {{secret:KEY}} placeholders.
+ *
+ * Workspace secrets back the `{{secret:KEY}}` placeholder in chatbot endpoint
+ * config (request body / headers). They live on the same product-secrets
+ * surface as site-access (see src/lib/site-access.ts), but with general,
+ * user-chosen keys instead of the reserved BASIC_AUTH_/SESSION_COOKIE_/
+ * LOGIN_ keys.
+ *
+ * Security posture:
+ *   - Values are write-only. The backend's list endpoint never returns them;
+ *     this command additionally drops any `value`-shaped fields client-side
+ *     before printing, so an accidental backend regression doesn't leak.
+ *   - Inputs come from a positional value, --value-file <path>, or stdin via
+ *     --value-stdin (mutually exclusive). Stdin/file paths keep secrets out
+ *     of shell history.
+ *   - No interactive prompts (CLI is for autonomous agents).
+ */
+import { withClient, resolveWorkspace, readFileOrStdin } from "../lib/command-helpers.js";
+import { output } from "../lib/output.js";
+const RESERVED_SITE_ACCESS_KEYS = new Set([
+    "BASIC_AUTH_USERNAME",
+    "BASIC_AUTH_PASSWORD",
+    "BASIC_AUTH_ORIGIN",
+    "LOGIN_USERNAME",
+    "LOGIN_PASSWORD",
+    "SESSION_COOKIE_NAME",
+    "SESSION_COOKIE_VALUE",
+    "SESSION_COOKIE_ORIGIN",
+    "SITE_ACCESS_PUBLIC_AFFIRMED_ORIGIN",
+]);
+const KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+/** Strip any `value`-shaped fields before render — defensive against backend regressions. */
+function sanitize(secret) {
+    return {
+        id: String(secret.id ?? ""),
+        key: String(secret.key ?? ""),
+        description: typeof secret.description === "string" ? secret.description : null,
+        scope: String(secret.scope ?? ""),
+        variable_type: String(secret.variable_type ?? ""),
+        created_at: String(secret.created_at ?? ""),
+        updated_at: String(secret.updated_at ?? ""),
+        expires_at: typeof secret.expires_at === "string" ? secret.expires_at : null,
+    };
+}
+function validateKey(key) {
+    if (!KEY_PATTERN.test(key)) {
+        const err = new Error(`Invalid secret key "${key}". Keys must start with an uppercase letter and use only A-Z, 0-9, and underscores (e.g. "GROQ_API_KEY").`);
+        err.name = "ValidationError";
+        throw err;
+    }
+    if (RESERVED_SITE_ACCESS_KEYS.has(key)) {
+        const err = new Error(`"${key}" is a reserved site-access key. Use \`ish workspace site-access\` to manage it.`);
+        err.name = "ValidationError";
+        throw err;
+    }
+}
+async function readValueFromStdin() {
+    if (process.stdin.isTTY) {
+        const err = new Error("--value-stdin requires the value to be piped on stdin.");
+        err.name = "ValidationError";
+        throw err;
+    }
+    return await new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data.replace(/\r?\n$/, "")));
+        process.stdin.on("error", reject);
+    });
+}
+export function registerSecretCommands(program) {
+    const secret = program
+        .command("secret")
+        .description("Manage workspace secrets used in {{secret:KEY}} placeholders")
+        .addHelpText("after", `
+Workspace secrets back the \`{{secret:KEY}}\` placeholder in chatbot
+endpoint config (request body / headers). Values are write-only — the
+backend never returns them after creation, and \`secret list\` only
+shows keys.
+
+Site-access credentials (BASIC_AUTH_*, LOGIN_*, SESSION_COOKIE_*) live
+on the same store but are managed via \`ish workspace site-access\` so
+the paired-key invariant is enforced.
+
+Examples:
+  $ ish secret set GROQ_API_KEY gsk_live_abc...
+  $ ish secret set GROQ_API_KEY --value-file ./key.txt
+  $ printf %s "$KEY" | ish secret set GROQ_API_KEY --value-stdin
+  $ ish secret list
+  $ ish secret delete GROQ_API_KEY`);
+    secret
+        .command("list")
+        .description("List secret keys for the active workspace (values never returned)")
+        .option("--workspace <id>", "Workspace ID; defaults to active workspace")
+        .addHelpText("after", "\nValues are write-only. This command returns key + metadata only; even if the backend regresses, values are stripped client-side before render.")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const wid = resolveWorkspace(opts.workspace);
+            const data = await client.get(`/products/${wid}/secrets`);
+            const sanitized = data.map((s) => sanitize(s));
+            if (globals.json) {
+                output(sanitized, true);
+                return;
+            }
+            if (sanitized.length === 0) {
+                console.log("No secrets configured for this workspace.");
+                return;
+            }
+            for (const s of sanitized) {
+                const desc = s.description ? ` — ${s.description}` : "";
+                console.log(`  ${s.key} (${s.variable_type}, scope=${s.scope})${desc}`);
+            }
+        });
+    });
+    secret
+        .command("set")
+        .description("Create or update a workspace secret")
+        .argument("<key>", "Secret key (uppercase, e.g. GROQ_API_KEY)")
+        .argument("[value]", "Secret value. Omit when using --value-file or --value-stdin.")
+        .option("--value-file <path>", "Read the value from a file on disk (use \"-\" for stdin)")
+        .option("--value-stdin", "Read the value from stdin (alias for --value-file -)")
+        .option("--description <text>", "Optional description (what this secret is used for)")
+        .option("--scope <scope>", "Visibility scope: agent | project (default: agent)", "agent")
+        .option("--workspace <id>", "Workspace ID; defaults to active workspace")
+        .addHelpText("after", `
+Pick exactly one of: positional <value>, --value-file <path>, --value-stdin.
+Stdin and --value-file are preferred for real keys so the value never lands
+in shell history.
+
+Examples:
+  $ ish secret set GROQ_API_KEY gsk_live_abc...
+  $ ish secret set GROQ_API_KEY --value-file ./key.txt
+  $ printf %s "$KEY" | ish secret set GROQ_API_KEY --value-stdin
+  $ ish secret set GROQ_API_KEY --value-file - < ./key.txt`)
+        .action(async (key, value, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            validateKey(key);
+            // Exactly one input source.
+            const sources = [
+                value !== undefined,
+                opts.valueFile !== undefined,
+                opts.valueStdin === true,
+            ].filter(Boolean).length;
+            if (sources === 0) {
+                const err = new Error("No value provided. Pass a positional value, --value-file <path>, or --value-stdin.");
+                err.name = "ValidationError";
+                throw err;
+            }
+            if (sources > 1) {
+                const err = new Error("Pass exactly one of: positional value, --value-file, --value-stdin.");
+                err.name = "ValidationError";
+                throw err;
+            }
+            let resolvedValue;
+            if (opts.valueStdin) {
+                resolvedValue = await readValueFromStdin();
+            }
+            else if (opts.valueFile !== undefined) {
+                resolvedValue = (await readFileOrStdin(opts.valueFile)).replace(/\r?\n$/, "");
+            }
+            else {
+                resolvedValue = value;
+            }
+            if (resolvedValue.length === 0) {
+                const err = new Error("Secret value is empty.");
+                err.name = "ValidationError";
+                throw err;
+            }
+            const scope = opts.scope === "project" ? "project" : "agent";
+            const wid = resolveWorkspace(opts.workspace);
+            // Find an existing entry by key so we PUT instead of POST when the
+            // user is updating. The list endpoint never returns the value, so
+            // this lookup leaks nothing.
+            const existing = await client.get(`/products/${wid}/secrets`);
+            const match = existing.find((s) => s.key === key);
+            let saved;
+            if (match) {
+                saved = await client.put(`/products/${wid}/secrets/${match.id}`, {
+                    value: resolvedValue,
+                    ...(opts.description !== undefined && { description: opts.description }),
+                    scope,
+                });
+            }
+            else {
+                const body = {
+                    key,
+                    value: resolvedValue,
+                    scope,
+                    variable_type: "secret",
+                    ...(opts.description !== undefined && { description: opts.description }),
+                };
+                saved = await client.post(`/products/${wid}/secrets`, body);
+            }
+            // Lean envelope. No value echoed.
+            const sanitized = sanitize(saved);
+            output({
+                success: true,
+                action: match ? "updated" : "created",
+                key: sanitized.key,
+                id: sanitized.id,
+                scope: sanitized.scope,
+                variable_type: sanitized.variable_type,
+                workspace_id: wid,
+            }, globals.json);
+        });
+    });
+    secret
+        .command("delete")
+        .description("Delete a workspace secret by key")
+        .argument("<key>", "Secret key to delete")
+        .option("--workspace <id>", "Workspace ID; defaults to active workspace")
+        .addHelpText("after", "\nExamples:\n  $ ish secret delete GROQ_API_KEY")
+        .action(async (key, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (!KEY_PATTERN.test(key)) {
+                const err = new Error(`Invalid secret key "${key}". Keys must start with an uppercase letter and use only A-Z, 0-9, and underscores.`);
+                err.name = "ValidationError";
+                throw err;
+            }
+            const wid = resolveWorkspace(opts.workspace);
+            const all = await client.get(`/products/${wid}/secrets`);
+            const match = all.find((s) => s.key === key);
+            if (!match) {
+                // Surface as ApiError so exitCodeFromError maps to 4 (not-found).
+                const { ApiError } = await import("../lib/api-client.js");
+                throw new ApiError(404, "Not Found", {
+                    detail: {
+                        detail: `No secret with key "${key}" in this workspace.`,
+                        error_code: "secret_not_found",
+                    },
+                });
+            }
+            await client.del(`/products/${wid}/secrets/${match.id}`);
+            output({
+                success: true,
+                action: "deleted",
+                key,
+                id: match.id,
+                workspace_id: wid,
+            }, globals.json);
+        });
+    });
+}