@ishlabs/cli 0.10.0 → 0.12.0

package/dist/commands/ask.js

@@ -347,6 +347,7 @@ Examples:
         allFlagName: "--all-simulatable",
         allFlagDescription: "Use every simulatable AI profile matching the filters",
     })
+        .option("--no-dispatch", "Create the ask in DRAFT status without billing or dispatching the round. Hand the draft id back to the user, then start it with `ish ask dispatch <id>`. Audience flags are still required because the testers are materialized at create time. Mutually exclusive with --wait (nothing to wait for).")
         .option("--wait", "Wait until the first round completes (or errors)")
         .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
@@ -389,6 +390,9 @@ Picks come back with a \`pick_confidence\` (0..1) score per tester when
 `)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            if (opts.dispatch === false && opts.wait) {
+                throw new Error("--no-dispatch and --wait are incompatible — a draft ask has nothing to wait for. Drop --wait, or run `ish ask dispatch <id> --wait` after the draft is created.");
+            }
             const wid = resolveWorkspace(opts.workspace);
             const testerIds = await resolveAudienceProfileIds(client, wid, audienceFlags(opts), { requireSimulatable: true, allFlagName: "--all-simulatable" });
             const round = await buildRoundInput(client, wid, opts, !!globals.quiet);
@@ -398,6 +402,7 @@ Picks come back with a \`pick_confidence\` (0..1) score per tester when
                 language: opts.language,
                 tester_profile_ids: testerIds,
                 first_round: round,
+                ...(opts.dispatch === false && { dispatch: false }),
             };
             let data = await client.post(`/products/${wid}/asks`, body);
             if (data.id) {
@@ -414,11 +419,58 @@ Picks come back with a \`pick_confidence\` (0..1) score per tester when
                 result.alias = tagAlias(ALIAS_PREFIX.ask, String(result.id));
             formatAskDetail(result, globals.json);
             if (!globals.json && data.id) {
+                if (opts.dispatch === false) {
+                    const askAlias = tagAlias(ALIAS_PREFIX.ask, data.id);
+                    process.stderr.write(`\n  Draft created. Start it with: ish ask dispatch ${askAlias}\n`);
+                }
                 const url = getWebUrl(globals, `/${wid}/asks/${data.id}`);
                 process.stderr.write(`\n  ${terminalLink(url, "Open in browser ↗")}\n\n`);
             }
         });
     });
+    // ---- dispatch -----------------------------------------------------------
+    // Pattern B-dispatch: flip a DRAFT ask to RUNNING and enqueue the worker.
+    // Idempotent on the server (409 on non-DRAFT) — surface that as a usage
+    // error rather than a transient failure.
+    ask
+        .command("dispatch")
+        .description("Dispatch a draft ask — bills credits and starts the round")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--wait", "Wait until the first round completes (or errors)")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
+        .addHelpText("after", `
+Use after \`ish ask create --no-dispatch\` to start a draft once the user has
+reviewed it. The dispatch is BILLABLE — credits are charged when responses
+land, the same as a normal create.
+
+Examples:
+  # Dispatch the active draft and wait for results:
+  $ ish ask dispatch --wait
+
+  # Dispatch a specific draft, JSON output:
+  $ ish ask dispatch a-6ec --json
+
+A non-DRAFT ask returns a 409 (\`already dispatched\`). The CLI maps that to a
+usage error so re-running this command is safe — no duplicate run.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            let data = await client.post(`/asks/${aid}/dispatch`, {});
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                data = await pollUntilRoundDone(client, aid, 0, timeoutMs, !!globals.quiet);
+            }
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.ask, String(result.id));
+            formatAskDetail(result, globals.json);
+            if (!globals.json && data.product_id) {
+                const url = getWebUrl(globals, `/${data.product_id}/asks/${aid}`);
+                process.stderr.write(`\n  ${terminalLink(url, "Open in browser ↗")}\n\n`);
+            }
+        });
+    });
     // ---- get ----------------------------------------------------------------
     ask
         .command("get")

package/dist/commands/chat.js

@@ -17,6 +17,7 @@ import { loadConfig, saveConfig } from "../config.js";
 import { ApiError } from "../lib/api-client.js";
 import { output } from "../lib/output.js";
 import { formatChatEndpointList, formatChatEndpointDetail, envelopeFromRow, } from "../lib/chat-endpoint-formatters.js";
+import { getChatEndpointTemplate, TEMPLATE_NAMES, } from "../lib/chat-endpoint-templates.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -57,7 +58,7 @@ function urlLooksLocal(url) {
     }
 }
 function inferredToConfig(inferred) {
-    return {
+    const cfg = {
         transport: inferred.transport,
         outgoing: {
             url: inferred.outgoing.url ?? undefined,
@@ -70,6 +71,10 @@ function inferredToConfig(inferred) {
         incoming: inferred.incoming,
         asyncPoll: inferred.asyncPoll ?? null,
     };
+    if (inferred.streaming) {
+        cfg.streaming = inferred.streaming;
+    }
+    return cfg;
 }
 async function tunnelGuard(client) {
     try {
@@ -197,7 +202,7 @@ endpoint, apply the override, and PUT the merged result. Field flags win over
   $ ish chat endpoint update ep-abc --name "Production"
   $ ish chat endpoint update ep-abc --url https://api.example.com/v2/chat
   $ ish chat endpoint get ep-abc --verbose \\
-      | jq '.config.incoming.slotsContainerPaths += ["response.options"]' \\
+      | jq '.config.incoming.slots += [{"containerPath": "response.options", "kind": "alternatives"}]' \\
       | ish chat endpoint update ep-abc --endpoint-config -`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
@@ -355,32 +360,93 @@ endpoint, apply the override, and PUT the merged result. Field flags win over
 function attachChatEndpointInit(parent) {
     parent
         .command("init")
-        .description("Author an endpoint from a curl/JSON sample via auto-detect-shape")
+        .description("Author an endpoint from a curl/JSON sample via auto-detect-shape, or from a known-good template")
         .option("--from-curl <file>", 'Path to a curl example file (or "-" for stdin)')
         .option("--from-json <file>", 'Path to a JSON request/response sample (or "-" for stdin)')
+        .option("--template <name>", `Start from a known-good template (one of: ${TEMPLATE_NAMES.join(", ")})`)
         .option("--name <name>", "Save the inferred config under this display name")
         .option("--no-save", "Infer the shape without persisting it")
         .option("--workspace <id>", "Workspace ID")
         .option("--tunnel-backed", "Force isTunnelBacked=true (overrides localhost auto-detect)")
         .option("--no-tunnel-backed", "Force isTunnelBacked=false (overrides localhost auto-detect)")
         .addHelpText("after", `
-Pass exactly one of --from-curl or --from-json. Both accept "-" for stdin.
+Pass exactly one of --from-curl, --from-json, or --template. --from-curl and
+--from-json accept "-" for stdin. --template <name> emits a hand-curated
+ChatbotEndpointConfig from public docs (no LLM round-trip), substituting
+{{secret:NAME}} placeholders for auth tokens.
+
+Available templates:
+${TEMPLATE_NAMES.map((n) => `  ${n}`).join("\n")}
 
 isTunnelBacked decision: explicit flag wins; else true when the inferred URL
-points at localhost / 127.0.0.1 / 0.0.0.0.
+points at localhost / 127.0.0.1 / 0.0.0.0 (templates always default to false).
 
 Examples:
   $ ish chat endpoint init --from-curl ./bot.curl --name my-bot
-  $ ish chat endpoint init --from-json ./shape.json --no-save | jq '.config'`)
+  $ ish chat endpoint init --from-json ./shape.json --no-save | jq '.config'
+  $ ish chat endpoint init --template openai --name "OpenAI"
+  $ ish chat endpoint init --template anthropic --no-save | jq '.config'`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            if (!opts.fromCurl && !opts.fromJson) {
-                throw new Error("Pass exactly one of --from-curl <file> or --from-json <file>.");
+            const sources = [opts.fromCurl, opts.fromJson, opts.template].filter((s) => s !== undefined).length;
+            if (sources === 0) {
+                throw new Error("Pass exactly one of --from-curl <file>, --from-json <file>, or --template <name>.");
             }
-            if (opts.fromCurl && opts.fromJson) {
-                throw new Error("Pass either --from-curl or --from-json, not both.");
+            if (sources > 1) {
+                throw new Error("Pass exactly one of --from-curl, --from-json, or --template — not multiple.");
             }
             const ws = resolveWorkspace(opts.workspace);
+            // Template path — fully local, no auto-detect call.
+            if (opts.template !== undefined) {
+                const tmpl = getChatEndpointTemplate(opts.template);
+                if (!tmpl) {
+                    throw new Error(`Unknown template "${opts.template}". Available: ${TEMPLATE_NAMES.join(", ")}.`);
+                }
+                const config = JSON.parse(JSON.stringify(tmpl.config));
+                const inferredUrl = (typeof config.outgoing?.url === "string" ? config.outgoing.url : null) ?? null;
+                const detectedTunnel = urlLooksLocal(inferredUrl);
+                let tunnelBacked;
+                if (opts.tunnelBacked === true)
+                    tunnelBacked = true;
+                else if (opts.tunnelBacked === false)
+                    tunnelBacked = false;
+                else
+                    tunnelBacked = detectedTunnel;
+                config.isTunnelBacked = tunnelBacked;
+                let endpointId = null;
+                let endpointAlias = null;
+                let saved = false;
+                const saveExplicitlyDisabled = opts.save === false;
+                const proposedName = opts.name ?? `template:${tmpl.name}`;
+                if (!saveExplicitlyDisabled) {
+                    const created = await client.post(`/products/${ws}/chatbot-endpoints`, { name: proposedName, config, isTunnelBacked: tunnelBacked });
+                    if (created.id) {
+                        endpointId = created.id;
+                        endpointAlias = tagAlias(ALIAS_PREFIX.chatEndpoint, created.id);
+                        saved = true;
+                        if (!globals.quiet) {
+                            console.error(`Created endpoint ${endpointAlias}`);
+                        }
+                    }
+                }
+                const result = {
+                    success: true,
+                    saved,
+                    endpoint_id: endpointId,
+                    alias: endpointAlias,
+                    config,
+                    tunnel_backed: tunnelBacked,
+                    tunnel_backed_detected: detectedTunnel,
+                    template: tmpl.name,
+                    description: tmpl.description,
+                    warnings: [
+                        "Templates use {{secret:NAME}} placeholders for auth — set the matching workspace secrets via `ish secret set` before testing.",
+                    ],
+                };
+                output(result, globals.json, { writePath: true });
+                return;
+            }
+            // Auto-detect path (curl or JSON paste).
             const path = (opts.fromCurl ?? opts.fromJson);
             const paste = await readFileOrStdin(path);
             const inferRes = await client.post(`/products/${ws}/chat/auto-detect-shape`, { paste }, { timeout: 120_000 });

package/dist/lib/chat-endpoint-formatters.d.ts

@@ -4,8 +4,17 @@
  * The backend returns a nested camelCase shape (id, name, productId, config,
  * isTunnelBacked, createdAt, updatedAt). The lean projection keeps only the
  * fields an agent typically branches on: id/alias/name, transport, the
- * outgoing url + method, the incoming messagePath, the slot-path count, and
+ * outgoing url + method, the incoming messagePath, slot/reference counts, and
  * isTunnelBacked. `--verbose` (or piped) passes the raw response.
+ *
+ * Slots-only model: `incoming.slots` and `incoming.references` are typed
+ * binding lists. Each slot carries `{containerPath, kind, labelPath, idPath}`;
+ * each reference carries `{containerPath, labelPath, urlPath}`. Legacy fields
+ * (`optionsPath`, `formRequestPath`, `cardsPath`, `artifactsPath`,
+ * `suggestedFollowupsPath`, plus the parallel `slotsContainerPaths` /
+ * `slotsKindHints` / `slotsLabelPaths` / `slotsIdPaths` /
+ * `referencesContainerPaths` arrays) are gone — anything interactive is a
+ * slot tagged with `kind`; anything passive is a reference.
  */
 export interface OutgoingHttp {
     url?: string;
@@ -13,15 +22,41 @@ export interface OutgoingHttp {
     mode?: string;
     [key: string]: unknown;
 }
+export interface SlotBinding {
+    containerPath: string;
+    kind?: "alternatives" | "form" | "text" | null;
+    labelPath?: string | null;
+    idPath?: string | null;
+}
+export interface ReferenceBinding {
+    containerPath: string;
+    labelPath?: string | null;
+    urlPath?: string | null;
+}
 export interface IncomingHttp {
     messagePath?: string;
-    slotsContainerPaths?: string[];
+    conversationIdPath?: string | null;
+    endOfConversationPath?: string | null;
+    errorPath?: string | null;
+    toolCallsPath?: string | null;
+    tokenUsagePath?: string | null;
+    slots?: SlotBinding[];
+    references?: ReferenceBinding[];
+    responseStub?: unknown;
     [key: string]: unknown;
 }
+export interface StreamingSettings {
+    eventFormat?: "openai" | "anthropic" | "raw";
+    deltaPath?: string | null;
+    terminalEvent?: string | null;
+    maxWaitSeconds?: number;
+}
 export interface ChatbotEndpointConfig {
     transport?: string;
     outgoing?: OutgoingHttp;
     incoming?: IncomingHttp;
+    streaming?: StreamingSettings | null;
+    asyncPoll?: unknown;
     isTunnelBacked?: boolean;
     [key: string]: unknown;
 }

package/dist/lib/chat-endpoint-formatters.js

@@ -4,8 +4,17 @@
  * The backend returns a nested camelCase shape (id, name, productId, config,
  * isTunnelBacked, createdAt, updatedAt). The lean projection keeps only the
  * fields an agent typically branches on: id/alias/name, transport, the
- * outgoing url + method, the incoming messagePath, the slot-path count, and
+ * outgoing url + method, the incoming messagePath, slot/reference counts, and
  * isTunnelBacked. `--verbose` (or piped) passes the raw response.
+ *
+ * Slots-only model: `incoming.slots` and `incoming.references` are typed
+ * binding lists. Each slot carries `{containerPath, kind, labelPath, idPath}`;
+ * each reference carries `{containerPath, labelPath, urlPath}`. Legacy fields
+ * (`optionsPath`, `formRequestPath`, `cardsPath`, `artifactsPath`,
+ * `suggestedFollowupsPath`, plus the parallel `slotsContainerPaths` /
+ * `slotsKindHints` / `slotsLabelPaths` / `slotsIdPaths` /
+ * `referencesContainerPaths` arrays) are gone — anything interactive is a
+ * slot tagged with `kind`; anything passive is a reference.
  */
 import { tagAlias, ALIAS_PREFIX } from "./alias-store.js";
 import { output, printTable } from "./output.js";
@@ -29,10 +38,10 @@ function leanRow(row) {
         out.mode = cfg.outgoing.mode;
     if (cfg.incoming?.messagePath)
         out.message_path = cfg.incoming.messagePath;
-    const slotsCount = Array.isArray(cfg.incoming?.slotsContainerPaths)
-        ? cfg.incoming.slotsContainerPaths.length
+    out.slots = Array.isArray(cfg.incoming?.slots) ? cfg.incoming.slots.length : 0;
+    out.references = Array.isArray(cfg.incoming?.references)
+        ? cfg.incoming.references.length
         : 0;
-    out.slots_paths = slotsCount;
     return out;
 }
 /** Return the round-trippable envelope used by `endpoint get --verbose`. */
@@ -68,6 +77,25 @@ export function formatChatEndpointList(rows, json, verbose) {
         r.is_tunnel_backed ? "yes" : "no",
     ]));
 }
+function formatSlotLine(slot) {
+    const kindLabel = slot.kind ?? "auto";
+    const subParts = [];
+    if (slot.labelPath)
+        subParts.push(`label=${slot.labelPath}`);
+    if (slot.idPath)
+        subParts.push(`id=${slot.idPath}`);
+    const tail = subParts.length > 0 ? `  (${subParts.join(", ")})` : "";
+    return `    ${slot.containerPath}  [${kindLabel}]${tail}`;
+}
+function formatReferenceLine(ref) {
+    const subParts = [];
+    if (ref.labelPath)
+        subParts.push(`label=${ref.labelPath}`);
+    if (ref.urlPath)
+        subParts.push(`url=${ref.urlPath}`);
+    const tail = subParts.length > 0 ? `  (${subParts.join(", ")})` : "";
+    return `    ${ref.containerPath}${tail}`;
+}
 export function formatChatEndpointDetail(row, json, verbose) {
     if (json) {
         if (verbose) {
@@ -96,9 +124,31 @@ export function formatChatEndpointDetail(row, json, verbose) {
     if (cfg.incoming) {
         console.log("");
         console.log(`  Message path  ${cfg.incoming.messagePath ?? "-"}`);
-        const slots = Array.isArray(cfg.incoming.slotsContainerPaths)
-            ? cfg.incoming.slotsContainerPaths.length
-            : 0;
-        console.log(`  Slot paths    ${slots}`);
+        if (cfg.incoming.conversationIdPath) {
+            console.log(`  Session path  ${cfg.incoming.conversationIdPath}`);
+        }
+        if (cfg.incoming.errorPath) {
+            console.log(`  Error path    ${cfg.incoming.errorPath}`);
+        }
+        const slots = Array.isArray(cfg.incoming.slots) ? cfg.incoming.slots : [];
+        console.log(`  Slots         ${slots.length}`);
+        for (const slot of slots) {
+            console.log(formatSlotLine(slot));
+        }
+        const refs = Array.isArray(cfg.incoming.references) ? cfg.incoming.references : [];
+        console.log(`  References    ${refs.length}`);
+        for (const ref of refs) {
+            console.log(formatReferenceLine(ref));
+        }
+    }
+    if (cfg.transport === "streaming" && cfg.streaming) {
+        console.log("");
+        console.log(`  Streaming     ${cfg.streaming.eventFormat ?? "openai"}`);
+        if (cfg.streaming.deltaPath) {
+            console.log(`    delta_path  ${cfg.streaming.deltaPath}`);
+        }
+        if (cfg.streaming.terminalEvent) {
+            console.log(`    terminal    ${cfg.streaming.terminalEvent}`);
+        }
     }
 }

package/dist/lib/chat-endpoint-templates.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Hand-curated `ChatbotEndpointConfig` templates for `ish chat endpoint init
+ * --template <name>`.
+ *
+ * Each template is a known-good wire shape an agent can drop straight into
+ * `create_chatbot_endpoint` — derived from public docs for the named
+ * provider. Auth / API key values are placeholder secret refs
+ * (`{{secret:NAME}}`); the agent stores the real value via
+ * `ish secret set` before testing.
+ *
+ * Templates are intentionally minimal:
+ *   - `transport`, `outgoing`, `incoming` (slots-only).
+ *   - No `retry` block — defaults are fine.
+ *   - No `asyncPoll` — none of the listed providers use it.
+ *   - `streaming` only when the provider's default flow is SSE-shaped
+ *     (we currently keep all templates in `sync` mode; agents who want
+ *     streaming flip the transport themselves after init).
+ *
+ * Slots / references are populated when the provider documents a stable
+ * structured-output container (e.g. Bot Framework's `suggestedActions`,
+ * Watson Assistant's `output.generic[]`). Where the provider is pure text
+ * (vanilla OpenAI / Anthropic chat-completions), the lists stay empty —
+ * the runtime auto-classifier handles any structured content the bot
+ * decides to emit per turn.
+ */
+import type { ChatbotEndpointConfig } from "./chat-endpoint-formatters.js";
+export type ChatEndpointTemplateName = "openai" | "anthropic" | "voiceflow" | "dialogflow-cx" | "botframework";
+export interface ChatEndpointTemplate {
+    name: ChatEndpointTemplateName;
+    description: string;
+    config: ChatbotEndpointConfig;
+}
+export declare const TEMPLATE_NAMES: ChatEndpointTemplateName[];
+export declare function getChatEndpointTemplate(name: string): ChatEndpointTemplate | undefined;
+export declare function listChatEndpointTemplates(): ChatEndpointTemplate[];

package/dist/lib/chat-endpoint-templates.js

@@ -0,0 +1,210 @@
+/**
+ * Hand-curated `ChatbotEndpointConfig` templates for `ish chat endpoint init
+ * --template <name>`.
+ *
+ * Each template is a known-good wire shape an agent can drop straight into
+ * `create_chatbot_endpoint` — derived from public docs for the named
+ * provider. Auth / API key values are placeholder secret refs
+ * (`{{secret:NAME}}`); the agent stores the real value via
+ * `ish secret set` before testing.
+ *
+ * Templates are intentionally minimal:
+ *   - `transport`, `outgoing`, `incoming` (slots-only).
+ *   - No `retry` block — defaults are fine.
+ *   - No `asyncPoll` — none of the listed providers use it.
+ *   - `streaming` only when the provider's default flow is SSE-shaped
+ *     (we currently keep all templates in `sync` mode; agents who want
+ *     streaming flip the transport themselves after init).
+ *
+ * Slots / references are populated when the provider documents a stable
+ * structured-output container (e.g. Bot Framework's `suggestedActions`,
+ * Watson Assistant's `output.generic[]`). Where the provider is pure text
+ * (vanilla OpenAI / Anthropic chat-completions), the lists stay empty —
+ * the runtime auto-classifier handles any structured content the bot
+ * decides to emit per turn.
+ */
+const OPENAI = {
+    name: "openai",
+    description: "OpenAI chat-completions wire shape. Stateless by default; ish ships the rolled-up history per turn. Drop in any OpenAI-compatible bot (Groq / Together / vLLM / OpenRouter / LiteLLM).",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://api.openai.com/v1/chat/completions",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Authorization: "Bearer {{secret:OPENAI_API_KEY}}",
+            },
+            bodyTemplate: {
+                model: "gpt-4o-mini",
+                messages: "{{history_with_current}}",
+            },
+            mode: "stateless",
+            roleAliases: {},
+        },
+        incoming: {
+            messagePath: "choices[0].message.content",
+            toolCallsPath: "choices[0].message.tool_calls",
+            tokenUsagePath: "usage",
+            slots: [],
+            references: [],
+        },
+    },
+};
+const ANTHROPIC = {
+    name: "anthropic",
+    description: "Anthropic Messages API. Stateless: each request carries the full history and a fresh system prompt. Default model is the latest Sonnet.",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://api.anthropic.com/v1/messages",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "anthropic-version": "2023-06-01",
+                "x-api-key": "{{secret:ANTHROPIC_API_KEY}}",
+            },
+            bodyTemplate: {
+                model: "claude-sonnet-4-20250514",
+                max_tokens: 1024,
+                messages: "{{history_with_current}}",
+            },
+            mode: "stateless",
+            roleAliases: {},
+        },
+        incoming: {
+            messagePath: "content[0].text",
+            tokenUsagePath: "usage",
+            slots: [],
+            references: [],
+        },
+    },
+};
+const VOICEFLOW = {
+    name: "voiceflow",
+    description: "Voiceflow Dialog Manager API. Stateful — the URL embeds the user/session id, and Voiceflow returns a list of trace objects. Body is `{action: {type: 'text', payload: <text>}}` per turn.",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://general-runtime.voiceflow.com/state/user/{{conversation_id}}/interact",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Authorization: "{{secret:VOICEFLOW_API_KEY}}",
+                versionID: "production",
+            },
+            bodyTemplate: {
+                action: {
+                    type: "text",
+                    payload: "{{action.text}}",
+                },
+            },
+            mode: "stateful",
+            roleAliases: {},
+        },
+        incoming: {
+            // Voiceflow's runtime returns an array of trace objects; the bot's
+            // textual reply lives in the first `speak` / `text` trace's payload.
+            // Agents typically tighten this path after a probe turn.
+            messagePath: "[0].payload.message",
+            slots: [
+                {
+                    containerPath: "[0].payload.choices",
+                    kind: "alternatives",
+                    labelPath: "name",
+                    idPath: "intent",
+                },
+            ],
+            references: [],
+        },
+    },
+};
+const DIALOGFLOW_CX = {
+    name: "dialogflow-cx",
+    description: "Google Dialogflow CX `detectIntent`. Stateful: the URL embeds the agent + session id and the response carries the next `currentPage` plus a list of fulfillment messages.",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://dialogflow.googleapis.com/v3/projects/{{secret:GCP_PROJECT}}/locations/global/agents/{{secret:DIALOGFLOW_AGENT_ID}}/sessions/{{conversation_id}}:detectIntent",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Authorization: "Bearer {{secret:GOOGLE_ACCESS_TOKEN}}",
+            },
+            bodyTemplate: {
+                queryInput: {
+                    text: { text: "{{action.text}}" },
+                    languageCode: "en",
+                },
+            },
+            mode: "stateful",
+            roleAliases: {},
+        },
+        incoming: {
+            messagePath: "queryResult.responseMessages[0].text.text[0]",
+            conversationIdPath: "responseId",
+            slots: [
+                {
+                    containerPath: "queryResult.responseMessages",
+                    kind: null,
+                },
+            ],
+            references: [],
+        },
+    },
+};
+const BOTFRAMEWORK = {
+    name: "botframework",
+    description: "Microsoft Bot Framework Direct Line `conversations/{id}/activities`. Stateful via the conversation id; activities[] carry the bot's reply plus suggestedActions for choice slots.",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://directline.botframework.com/v3/directline/conversations/{{conversation_id}}/activities",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Authorization: "Bearer {{secret:DIRECTLINE_SECRET}}",
+            },
+            bodyTemplate: {
+                type: "message",
+                from: { id: "{{tester.name}}" },
+                text: "{{action.text}}",
+            },
+            mode: "stateful",
+            roleAliases: {},
+        },
+        incoming: {
+            messagePath: "activities[0].text",
+            conversationIdPath: "activities[0].conversation.id",
+            slots: [
+                {
+                    containerPath: "activities[0].suggestedActions.actions",
+                    kind: "alternatives",
+                    labelPath: "title",
+                    idPath: "value",
+                },
+            ],
+            references: [
+                {
+                    containerPath: "activities[0].attachments",
+                    labelPath: "name",
+                    urlPath: "contentUrl",
+                },
+            ],
+        },
+    },
+};
+const TEMPLATES = {
+    openai: OPENAI,
+    anthropic: ANTHROPIC,
+    voiceflow: VOICEFLOW,
+    "dialogflow-cx": DIALOGFLOW_CX,
+    botframework: BOTFRAMEWORK,
+};
+export const TEMPLATE_NAMES = Object.keys(TEMPLATES);
+export function getChatEndpointTemplate(name) {
+    return TEMPLATES[name];
+}
+export function listChatEndpointTemplates() {
+    return TEMPLATE_NAMES.map((n) => TEMPLATES[n]);
+}

package/dist/lib/docs.js

@@ -574,6 +574,49 @@ ish ask results a-6ec
 ish ask results a-6ec --json | jq '.rounds[0].aggregates'
 \`\`\`
 
+## Status field
+
+Asks carry a top-level \`status\`:
+
+- \`draft\` — created but not dispatched yet. No credits charged. Created
+  by \`ish ask create --no-dispatch\`.
+- \`running\` — dispatched; the round is executing or queued.
+- \`completed\` — round 1 (or the most recent round) finished.
+- \`cancelled\` — terminated explicitly.
+
+Surfaces in \`ish ask list\` (table column) and \`ish ask get\` (header
+metadata line and JSON \`status\` field). Lean JSON keeps the field
+intact — no \`--verbose\` needed to see it.
+
+## Stage-then-dispatch (draft asks)
+
+When you want a human to review the audience and prompt **before** any
+credits are spent, separate creation from dispatch:
+
+\`\`\`
+# 1. Stage — materializes testers, no worker enqueue, no bill yet
+ish ask create --workspace w-6ec --name "tagline AB" \\
+    --prompt "Which sounds better?" \\
+    --variant text:"Short and punchy." \\
+    --variant text:"A longer, descriptive line." \\
+    --sample 30 --wants-pick \\
+    --no-dispatch
+
+# Returns an ask with status="draft". Hand the alias back to the user.
+
+# 2. Dispatch — flips DRAFT → RUNNING and enqueues the round (BILLABLE)
+ish ask dispatch a-6ec --wait
+\`\`\`
+
+\`--no-dispatch\` requires audience flags (testers are still materialized
+at create time — only the worker enqueue and billing are deferred). It
+is incompatible with \`--wait\` since there is nothing to wait for.
+
+\`ish ask dispatch\` is idempotent on the server: a non-DRAFT ask returns
+HTTP 409 (\`already dispatched\`) which the CLI maps to a usage error, so
+re-running the command is safe. The user who calls \`dispatch\` is the
+billing principal — keep that in mind for shared workspaces.
+
 ## Reading the verdict
 
 For \`--wants-pick\` / \`--wants-ratings\` rounds, \`ask results --json\`
@@ -1783,8 +1826,7 @@ ish chat endpoint get ep-abc --verbose \\
   | ish chat endpoint update ep-abc --endpoint-config -
 
 ish chat endpoint get ep-abc --verbose \\
-  | jq '.config.incoming.slotsContainerPaths += ["response.options"]
-        | .config.incoming.slotsKindHints["response.options"] = "alternatives"' \\
+  | jq '.config.incoming.slots += [{"containerPath": "response.options", "kind": "alternatives"}]' \\
   | ish chat endpoint update ep-abc --endpoint-config -
 \`\`\`
 
@@ -1820,6 +1862,106 @@ The renderer expands these tokens at request time:
 }
 \`\`\`
 
+### Slot bindings (interactive containers)
+
+The bot's response shape is described by two typed lists on
+\`incoming\`:
+
+- \`incoming.slots[]\` — INTERACTIVE containers the persona must
+  respond to. Each entry is
+  \`{containerPath, kind?, labelPath?, idPath?}\`.
+- \`incoming.references[]\` — PASSIVE containers (citations,
+  followups, file artifacts, related links). Each entry is
+  \`{containerPath, labelPath?, urlPath?}\`.
+
+\`kind\` is one of \`alternatives\` (pick from a list), \`form\`
+(fill named fields), or \`text\` (free text). Leaving \`kind\` unset
+(the default) means "auto-classify per-turn from the live shape" —
+ish inspects the container value at parse time and dispatches on the
+shape it sees. Use that whenever the bot returns different slot
+kinds across turns.
+
+\`labelPath\` / \`idPath\` (alternatives) and \`labelPath\` /
+\`urlPath\` (references) are optional sub-paths within each item.
+When omitted, ish falls back to \`label\` / \`text\` / \`title\` for
+labels, \`id\` / \`value\` / \`payload\` for ids, and
+\`url\` / \`uri\` / \`href\` for urls.
+
+The legacy per-affordance fields (\`optionsPath\`,
+\`formRequestPath\`, \`cardsPath\`, \`artifactsPath\`,
+\`suggestedFollowupsPath\`) are gone. Anything interactive is a
+slot tagged with \`kind\`; anything passive is a reference. New
+affordance shapes ship as a new \`kind\` value, no schema migration.
+
+\`auto-detect-shape\` (the engine behind \`init\`) populates these
+lists from the response stub via a shape-based classifier:
+\`list[{label, id?}]\` becomes \`alternatives\`,
+\`{fields: [...]}\` becomes \`form\`,
+\`list[{label, url}]\` becomes a reference, and
+\`list[str]\` becomes a string-list reference. The classifier never
+emits \`kind=text\` — that's a hand-set tag for free-text follow-ups.
+
+### Streaming endpoints
+
+When a bot speaks Server-Sent Events (Accept: text/event-stream,
+\`-N\` / \`--no-buffer\` curl flags, or \`"stream": true\` in the
+body), \`init\` flips \`transport\` to \`"streaming"\` and seeds a
+\`streaming\` block:
+
+\`\`\`json
+{
+  "transport": "streaming",
+  "streaming": {
+    "eventFormat": "openai",
+    "deltaPath": null,
+    "terminalEvent": null,
+    "maxWaitSeconds": 120
+  }
+}
+\`\`\`
+
+\`eventFormat\` is one of:
+
+- \`"openai"\` — chunks shaped like
+  \`{choices: [{delta: {content: "..."}}]}\`; ends on \`[DONE]\` or
+  \`finish_reason != null\`. Matches OpenAI / Groq / vLLM / LiteLLM /
+  OpenRouter / Chainlit.
+- \`"anthropic"\` — \`event: content_block_delta\` chunks carrying
+  \`{delta: {type: "text_delta", text: "..."}}\`; ends on
+  \`event: message_stop\`.
+- \`"raw"\` — body-text concatenation; no JSON decoding; closes on
+  connection drop.
+
+Override the format-specific defaults via \`deltaPath\` (e.g. an
+OpenAI-compatible proxy that nests delta under
+\`message.delta.content\`) and \`terminalEvent\`. \`maxWaitSeconds\`
+caps the streaming-loop deadline.
+
+### From a template
+
+For well-known providers, skip auto-detect and start from a
+hand-curated config:
+
+\`\`\`
+ish chat endpoint init --template openai --name "OpenAI"
+ish chat endpoint init --template anthropic --no-save | jq '.config'
+ish chat endpoint init --template voiceflow --name "Sales bot"
+ish chat endpoint init --template dialogflow-cx --name "Support"
+ish chat endpoint init --template botframework --name "Concierge"
+\`\`\`
+
+Templates use \`{{secret:NAME}}\` placeholders for auth tokens; set
+the matching workspace secrets before testing:
+
+\`\`\`
+printf %s "$OPENAI_API_KEY" | ish secret set OPENAI_API_KEY --value-stdin
+\`\`\`
+
+Available templates: openai, anthropic, voiceflow, dialogflow-cx,
+botframework. Each is derived from the provider's public docs and
+is intentionally minimal — agents typically tighten the message
+path / model / slot bindings after one round-trip with the real bot.
+
 ### Auth via workspace secrets
 
 For bots behind an API key, store the value as a workspace secret
@@ -2087,7 +2229,7 @@ const PAGES = [
     {
         slug: "guides/chat",
         title: "guide: chat-modality studies",
-        description: "Configure a chatbot endpoint, smoke test it, run a chat-modality study.",
+        description: "Configure a chatbot endpoint (slots-only model), smoke test it, run a chat-modality study. Covers slot bindings, streaming endpoints, and built-in templates.",
         body: GUIDE_CHAT,
     },
 ];

package/dist/lib/output.js

@@ -1452,9 +1452,10 @@ export function formatAskList(asks, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.ask);
-    printTable(["#", "NAME", "AUDIENCE", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
+    printTable(["#", "NAME", "STATUS", "AUDIENCE", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
         aliasMap.get(String(a.id)) || String(a.id || ""),
         String(a.name || ""),
+        String(a.status || "-"),
         String(a.audience_count ?? "0"),
         String(a.round_count ?? "0"),
         formatDate(a.last_round_at),
@@ -1533,6 +1534,8 @@ export function formatAskDetail(ask, json) {
     if (ask.description)
         console.log(String(ask.description));
     const meta = [];
+    if (ask.status)
+        meta.push(String(ask.status));
     if (ask.is_archived)
         meta.push("archived");
     meta.push(formatDate(ask.created_at));

package/dist/lib/skill-content.d.ts

@@ -29,3 +29,21 @@ export interface SkillTargetSpec {
     consumers: string[];
 }
 export declare const SKILL_TARGETS: SkillTargetSpec[];
+/**
+ * Walks from `startDir` upward (inclusive of the home directory, capped at
+ * the filesystem root) looking for an installed ish skill at any of
+ * SKILL_TARGETS. Returns the first hit, identified by the presence of a
+ * SKILL.md file. Used by `ish status` to nudge agents toward `ish init`
+ * when the project doesn't have the skill installed yet.
+ */
+export declare function findInstalledSkill(startDir: string, fs: {
+    existsSync: (p: string) => boolean;
+}, path: {
+    join: (...p: string[]) => string;
+    dirname: (p: string) => string;
+    resolve: (p: string) => string;
+}, homeDir: string): {
+    target: SkillTargetSpec;
+    root: string;
+    skillMdPath: string;
+} | null;

package/dist/lib/skill-content.js

@@ -138,6 +138,11 @@ ish study create --modality chat --endpoint my-bot --assignment "Sign up:Try to
 ish study run --sample 5 --country SE --wait
 ish ask run --new --name "..." --prompt "..." --variant text:"A" --variant text:"B" --sample 30 --wants-pick --wait
 
+# Stage an ask for human review, then dispatch (no credits charged on stage)
+ish ask create --name "..." --prompt "..." --variant text:"A" --variant text:"B" \
+    --sample 30 --wants-pick --no-dispatch
+ish ask dispatch a-6ec --wait
+
 # Results
 ish study results
 ish ask results a-6ec --round 1
@@ -236,6 +241,15 @@ implies \`--quiet\` so the bare value is the only thing on stdout.
   follow-up question to a completed round preserves prior comments,
   picks, and ratings; only the new question is dispatched. Pass
   \`--redispatch-all\` for the legacy reset-and-rerun behavior.
+- **\`ask create --no-dispatch\` stages a draft, no bill yet.** Pair
+  with \`ish ask dispatch <id>\` to flip DRAFT → RUNNING and start
+  the round. Use this when the user wants to review the audience or
+  prompt before any credits are charged. Audience flags are still
+  required (testers materialize at create time); only the worker
+  enqueue and billing are deferred. Asks now carry a top-level
+  \`status\` (\`draft | running | completed | cancelled\`) visible in
+  \`ask list\` and \`ask get\`. \`dispatch\` is idempotent — a
+  non-DRAFT ask returns 409 mapped to a usage error.
 - **\`ask results --json\` adds \`cross_round_summary\` for 2+ rounds.**
   Top-level field with per-round picks/winner snapshots and
   \`picks_delta\` (R1 → last). Don't diff two \`ask results\` calls by
@@ -520,8 +534,20 @@ ish iteration create --url "$URL"
 
 Goal: configure a customer chatbot endpoint, smoke test it, and run
 a chat-modality study end to end. The CLI talks to the endpoint
-through whatever transport it's configured for (sync / async-poll);
-local bots reach ish via \`ish connect\`.
+through whatever transport it's configured for (sync / async-poll /
+streaming); local bots reach ish via \`ish connect\`.
+
+Endpoint shape is slots-only: \`incoming.slots[]\` lists interactive
+containers (\`{containerPath, kind?, labelPath?, idPath?}\`,
+\`kind\` ∈ \`alternatives\` / \`form\` / \`text\` or unset to
+auto-classify per-turn) and \`incoming.references[]\` lists passive
+containers (citations / followups / artifacts). Auto-detect derives
+both from the response stub via shape rules — no markers to learn.
+
+For well-known providers, skip auto-detect and start from a
+hand-curated template:
+\`ish chat endpoint init --template <openai|anthropic|voiceflow|dialogflow-cx|botframework>\`.
+Templates use \`{{secret:NAME}}\` placeholders for auth.
 
 \`\`\`bash
 # 1. Author the endpoint from a curl example (or a ChatbotEndpointConfig file).
@@ -540,7 +566,7 @@ ish chat endpoint test "$ID" -m "Hello"
 #    one-liner shorthand. Mirrors the editor dialog's PUT contract.
 ish chat endpoint update "$ID" --name "Production support bot"
 ish chat endpoint get "$ID" --verbose \\
-  | jq '.config.incoming.slotsContainerPaths += ["response.options"]' \\
+  | jq '.config.incoming.slots += [{"containerPath": "response.options", "kind": "alternatives"}]' \\
   | ish chat endpoint update "$ID" --endpoint-config -
 
 # 4. Run a chat-modality study referencing the endpoint. Audience size
@@ -596,7 +622,41 @@ you can branch on plan caps before \`study create\` returns
 The full reference is at \`ish docs get-page guides/chat\`,
 secrets are at \`ish docs get-page concepts/secret\`.
 
-## 8. Display-vs-capture: a script that does both
+## 8. Stage an ask for human review, then dispatch
+
+Goal: prepare a billable A/B but let the user inspect and approve the
+audience + prompt before any credits are spent. Two-step flow with a
+DRAFT status in between.
+
+\`\`\`bash
+# 1. Stage. No worker enqueued, no bill. Audience flags are still
+#    required — testers materialize at create time.
+ASK=$(ish ask create --name "tagline AB" \\
+        --prompt "Which sounds better?" \\
+        --variant text:"Short and punchy." \\
+        --variant text:"A longer, descriptive line." \\
+        --sample 30 --wants-pick \\
+        --no-dispatch \\
+        --get alias)
+
+# Hand the alias back to the user. They can inspect it:
+#   ish ask get "$ASK"            # status: draft
+#   ish ask get "$ASK" --json | jq '.testers | length'
+
+# 2. Dispatch once approved (BILLABLE). Idempotent: a non-DRAFT ask
+#    returns 409 mapped to exit 2, so re-running is safe.
+ish ask dispatch "$ASK" --wait
+\`\`\`
+
+The \`status\` field on the ask reflects lifecycle (\`draft\` → \`running\`
+→ \`completed\`); \`is_archived\` is orthogonal. \`ish ask list\` shows
+status as a column.
+
+\`--no-dispatch\` is incompatible with \`--wait\` — there is nothing to
+wait for. Pass \`--wait\` to \`ish ask dispatch\` instead if you want to
+block until the round settles.
+
+## 9. Display-vs-capture: a script that does both
 
 Goal: drive an A/B in a script, capture aliases without \`jq\`, and
 still show the human a readable result table at the end.
@@ -837,3 +897,32 @@ export const SKILL_TARGETS = [
         consumers: ["Codex", "Cursor", "Cline", "Roo Code"],
     },
 ];
+/**
+ * Walks from `startDir` upward (inclusive of the home directory, capped at
+ * the filesystem root) looking for an installed ish skill at any of
+ * SKILL_TARGETS. Returns the first hit, identified by the presence of a
+ * SKILL.md file. Used by `ish status` to nudge agents toward `ish init`
+ * when the project doesn't have the skill installed yet.
+ */
+export function findInstalledSkill(startDir, fs, path, homeDir) {
+    let dir = path.resolve(startDir);
+    const home = path.resolve(homeDir);
+    // Walk until the parent stops changing (filesystem root). Include `home`
+    // itself in the search so a global ~/.claude/skills/ish counts, but stop
+    // right after — don't claim a skill installed somewhere above $HOME.
+    while (true) {
+        for (const target of SKILL_TARGETS) {
+            const root = path.join(dir, target.path);
+            const skillMdPath = path.join(root, "SKILL.md");
+            if (fs.existsSync(skillMdPath)) {
+                return { target, root, skillMdPath };
+            }
+        }
+        if (dir === home)
+            return null;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/lib/types.d.ts

@@ -245,6 +245,7 @@ export interface SimulationConfig {
 }
 export type AskVariantKind = "image" | "text" | "audio" | "video" | "document";
 export declare const ASK_VARIANT_KINDS: AskVariantKind[];
+export type AskStatus = "draft" | "running" | "completed" | "cancelled";
 export type AskRoundStatus = "running" | "completed" | "errored";
 export type AskResponseStatus = "pending" | "completed" | "errored";
 export interface AskVariant {
@@ -293,6 +294,7 @@ export interface AskCreateInput {
     language?: string;
     tester_profile_ids: string[];
     first_round: AskRoundInput;
+    dispatch?: boolean;
 }
 export interface AskUpdateInput {
     name?: string;
@@ -355,6 +357,7 @@ export interface Ask {
     name: string;
     description?: string | null;
     is_archived: boolean;
+    status?: AskStatus;
     testers: AskAudienceTester[];
     rounds: AskRound[];
     created_at: string;
@@ -367,6 +370,7 @@ export interface AskListItem {
     name: string;
     description?: string | null;
     is_archived: boolean;
+    status?: AskStatus;
     audience_count: number;
     round_count: number;
     last_round_at?: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {
@@ -41,4 +41,4 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"
   }
-}
+}