@ishlabs/cli 0.10.0 → 0.11.0

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

@@ -1783,8 +1783,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 +1819,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 +2186,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/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

@@ -520,8 +520,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 +552,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
@@ -837,3 +849,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/package.json

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